useCircleCharter

Location: src/hooks/useCircleCharter.js

Overview

This file provides hooks and utilities for working with Circle Charters -- toggle-based behavioral norms that circle owners can enable for their circles. For example, a charter might enable "slow replies" or "no dunking" norms.

The file exports four items:

• useCharterToggleDefinitions -- fetch all available toggle definitions (cached in memory)
• useCircleCharter -- fetch a specific circle's charter
• useUpdateCharter -- update a circle's charter toggles
• getCharterHints -- utility function that returns context-aware hint strings

---

useCharterToggleDefinitions

Signature

function useCharterToggleDefinitions(): {
  definitions: CharterToggleDefinition[],
  loading: boolean,
  error: string | null
}

Parameters

None.

Return Value

Property	Type	Description
definitions	CharterToggleDefinition[]	All available charter toggle definitions from the charter_toggle_definitions table, ordered by sort_order. Cached in memory after first fetch.
loading	boolean	true while the initial fetch is in progress.
error	string | null	Error message if the fetch failed, otherwise null.

---

useCircleCharter

Signature

function useCircleCharter(
  circleId: string | null
): {
  charter: CircleCharterRow | null,
  loading: boolean,
  error: string | null,
  enabledToggles: string[],
  isToggleEnabled: (toggleId: string) => boolean,
  refetch: () => Promise<void>
}

Parameters

Parameter	Type	Required	Description
circleId	string | null	Yes	The circle ID to fetch the charter for. If null, loading resolves immediately.

Return Value

Property	Type	Description
charter	CircleCharterRow | null	The full charter row from circle_charters, or null if no charter exists for this circle.
loading	boolean	true while the fetch is in progress.
error	string | null	Error message if the fetch failed, otherwise null.
enabledToggles	string[]	Array of toggle IDs that are currently enabled in this charter.
isToggleEnabled	(toggleId: string) => boolean	Check if a specific toggle is enabled.
refetch	() => Promise<void>	Re-fetch the charter data.

---

useUpdateCharter

Signature

function useUpdateCharter(
  circleId: string | null
): {
  updateCharter: (toggles: Record<string, boolean>) => Promise<{ success?: boolean, charter?: CircleCharterRow, error?: string }>,
  saving: boolean,
  error: string | null
}

Parameters

Parameter	Type	Required	Description
circleId	string | null	Yes	The circle ID whose charter to update.

Return Value

Property	Type	Description
updateCharter	(toggles) => Promise	Upserts the charter with the provided toggles object. Returns { success, charter } on success or { error } on failure.
saving	boolean	true while the update is in progress.
error	string | null	Error message if the last update failed.

---

getCharterHints

Signature

function getCharterHints(
  enabledToggles: string[],
  postIntent?: string | null
): string[]

A pure utility function (not a hook) that generates context-aware hint strings based on which charter toggles are enabled and the current post intent.

Parameters

Parameter	Type	Required	Description
enabledToggles	string[]	Yes	Array of enabled toggle IDs.
postIntent	string | null	No	The intent of the current post, used for context-specific hints.

Return Value

Returns an array of human-readable hint strings. Examples:

• "This circle encourages slow replies." (when slow_replies is enabled)
• "This is a personal post -- read with care." (when gentle_personal is enabled and intent is sharing_personal)
• "Assume good intent; clarify before escalating." (when repair_first is enabled)
• "Critique ideas, not people." (when no_dunking is enabled)

Usage

function CircleSettings({ circleId }) {
  const { definitions } = useCharterToggleDefinitions();
  const { charter, enabledToggles, isToggleEnabled } = useCircleCharter(circleId);
  const { updateCharter, saving } = useUpdateCharter(circleId);

  const handleToggle = async (toggleId) => {
    const newToggles = {
      ...charter?.toggles,
      [toggleId]: !isToggleEnabled(toggleId)
    };
    await updateCharter(newToggles);
  };

  return (
    <div>
      {definitions.map(def => (
        <label key={def.id}>
          <input
            type="checkbox"
            checked={isToggleEnabled(def.id)}
            onChange={() => handleToggle(def.id)}
            disabled={saving}
          />
          {def.label}
        </label>
      ))}
    </div>
  );
}

---

Last updated: 2026-02-07