@djangocfg/layouts 2.1.426 → 2.1.427

package/src/layouts/SettingsLayout/hooks/useSettingsSections.ts

@@ -0,0 +1,123 @@
+'use client';
+
+/**
+ * useSettingsSections — resolve raw section/group config into the ordered,
+ * grouped, search-filtered structure the nav rail renders.
+ *
+ * Pure derivation (no side effects): built-ins + app sections are merged,
+ * hidden ones dropped from the rail, sorted by (group order, section order,
+ * declaration index), then partitioned into groups. A search query filters by
+ * label text + keywords.
+ */
+
+import { useMemo } from 'react';
+
+import type { SettingsGroup, SettingsSection } from '../types';
+
+/** A group paired with its resolved, ordered sections. */
+export interface ResolvedGroup {
+  id: string;
+  label?: React.ReactNode;
+  sections: SettingsSection[];
+}
+
+export interface UseSettingsSectionsArgs {
+  /** Built-in + app sections, already concatenated by the caller. */
+  sections: SettingsSection[];
+  /** Group definitions for ordering/labelling. */
+  groups?: SettingsGroup[];
+  /** Live search query (case-insensitive). Empty = no filtering. */
+  query?: string;
+}
+
+export interface UseSettingsSectionsResult {
+  /** Groups (with sections) for the nav rail, in render order. */
+  groups: ResolvedGroup[];
+  /** Flat list of all visible sections, in render order. */
+  visible: SettingsSection[];
+  /** Lookup by id across ALL sections (incl. hidden) — for resolving active. */
+  byId: Map<string, SettingsSection>;
+  /** All known section ids (incl. hidden) — handed to the URL resolver. */
+  ids: Set<string>;
+}
+
+const DEFAULT_GROUP_ID = '__default__';
+
+/** Extract searchable text from a label that may be a string or JSX. */
+function labelText(label: React.ReactNode): string {
+  return typeof label === 'string' ? label : '';
+}
+
+function matchesQuery(section: SettingsSection, q: string): boolean {
+  if (!q) return true;
+  const haystack = [
+    labelText(section.label),
+    labelText(section.title),
+    ...(section.keywords ?? []),
+  ]
+    .join(' ')
+    .toLowerCase();
+  return haystack.includes(q);
+}
+
+export function useSettingsSections({
+  sections,
+  groups,
+  query = '',
+}: UseSettingsSectionsArgs): UseSettingsSectionsResult {
+  return useMemo(() => {
+    const q = query.trim().toLowerCase();
+
+    const byId = new Map<string, SettingsSection>();
+    const ids = new Set<string>();
+    for (const s of sections) {
+      byId.set(s.id, s);
+      ids.add(s.id);
+    }
+
+    // Group order: explicit `order`, else declaration order; default group first.
+    const groupOrder = new Map<string, number>();
+    groupOrder.set(DEFAULT_GROUP_ID, -Infinity);
+    (groups ?? []).forEach((g, i) => {
+      groupOrder.set(g.id, g.order ?? i);
+    });
+    const groupLabel = new Map<string, React.ReactNode>();
+    (groups ?? []).forEach((g) => g.label && groupLabel.set(g.id, g.label));
+
+    // Bucket visible (not hidden, passes search) sections by group.
+    const buckets = new Map<string, Array<{ section: SettingsSection; index: number }>>();
+    const visible: SettingsSection[] = [];
+
+    sections.forEach((section, index) => {
+      if (section.hidden) return;
+      if (!matchesQuery(section, q)) return;
+      const gid = section.group && groupOrder.has(section.group) ? section.group
+        : section.group ?? DEFAULT_GROUP_ID;
+      // Register ad-hoc groups (named on a section but not declared) so they sort stably.
+      if (!groupOrder.has(gid)) groupOrder.set(gid, buckets.size);
+      if (!buckets.has(gid)) buckets.set(gid, []);
+      buckets.get(gid)!.push({ section, index });
+    });
+
+    // Sort sections within each bucket, then emit groups in group order.
+    const resolved: ResolvedGroup[] = [...buckets.entries()]
+      .sort((a, b) => (groupOrder.get(a[0])! - groupOrder.get(b[0])!))
+      .map(([gid, entries]) => {
+        const ordered = entries
+          .sort((a, b) => {
+            const oa = a.section.order ?? a.index;
+            const ob = b.section.order ?? b.index;
+            return oa - ob;
+          })
+          .map((e) => e.section);
+        ordered.forEach((s) => visible.push(s));
+        return {
+          id: gid,
+          label: gid === DEFAULT_GROUP_ID ? undefined : groupLabel.get(gid),
+          sections: ordered,
+        };
+      });
+
+    return { groups: resolved, visible, byId, ids };
+  }, [sections, groups, query]);
+}

package/src/layouts/SettingsLayout/hooks/useSettingsUrl.ts

@@ -0,0 +1,140 @@
+'use client';
+
+/**
+ * useSettingsUrl — two-way bind the SettingsDialog store to the URL hash.
+ *
+ * Shape: `#settings/<section>` (Claude.ai style). The leading key is
+ * configurable (`urlKey`). Examples:
+ *   #settings            → open, first/last-active section
+ *   #settings/usage      → open, "usage" section active
+ *   (no/other hash)      → closed
+ *
+ * Direction of truth:
+ *   URL  → store : on mount and on every hashchange/popstate. This is what makes
+ *                  deep-links, refresh, and the back button "just work" — the
+ *                  browser owns history, we mirror it into state.
+ *   store → URL : when the user opens/closes/switches section via the UI, we
+ *                  push or replace the hash so it stays shareable.
+ *
+ * We lean on ui-core's `useLocation` (a `useSyncExternalStore` over a patched
+ * history + `hashchange`) so this is framework-agnostic — no next/router import.
+ */
+
+import { useEffect, useRef } from 'react';
+
+import { useLocation, useNavigate } from '@djangocfg/ui-core/hooks';
+
+import { useSettingsDialogStore } from '../store';
+
+export interface UseSettingsUrlOptions {
+  /** Hash namespace before the section id. Default: "settings". */
+  urlKey?: string;
+  /** Disable the binding entirely (imperative-only mode). Default: false. */
+  enabled?: boolean;
+  /**
+   * Validate / normalize a section id read from the URL. Return null to reject
+   * an unknown id (dialog still opens, on the fallback section). The shell
+   * passes the set of known section ids here.
+   */
+  resolveSection?: (id: string | null) => string | null;
+}
+
+interface ParsedHash {
+  open: boolean;
+  section: string | null;
+}
+
+/** Parse `#settings/usage` → { open: true, section: 'usage' }. */
+function parseHash(hash: string, urlKey: string): ParsedHash {
+  // hash includes the leading '#': "#settings/usage"
+  const raw = hash.startsWith('#') ? hash.slice(1) : hash;
+  if (!raw) return { open: false, section: null };
+
+  const [key, ...rest] = raw.split('/');
+  if (key !== urlKey) return { open: false, section: null };
+
+  const section = rest.join('/') || null;
+  return { open: true, section };
+}
+
+/** Build `#settings/usage` (or `#settings` when no section). */
+function buildHash(urlKey: string, section: string | null): string {
+  return section ? `#${urlKey}/${section}` : `#${urlKey}`;
+}
+
+/** Strip a trailing hash, keeping pathname + search intact. */
+function urlWithoutHash(): string {
+  if (typeof window === 'undefined') return '/';
+  const { pathname, search } = window.location;
+  return `${pathname}${search}`;
+}
+
+export function useSettingsUrl(options: UseSettingsUrlOptions = {}): void {
+  const { urlKey = 'settings', enabled = true, resolveSection } = options;
+
+  const { hash } = useLocation();
+  const { navigate } = useNavigate();
+
+  const isOpen = useSettingsDialogStore((s) => s.isOpen);
+  const activeSection = useSettingsDialogStore((s) => s.activeSection);
+  const open = useSettingsDialogStore((s) => s.open);
+  const close = useSettingsDialogStore((s) => s.close);
+
+  // Guard against the URL→store and store→URL effects fighting each other:
+  // when we write the hash ourselves we tag the value we wrote and skip the
+  // next URL→store pass for that exact value.
+  const selfWrittenHash = useRef<string | null>(null);
+
+  // ── URL → store ──────────────────────────────────────────────────────────
+  useEffect(() => {
+    if (!enabled) return;
+
+    // Ignore the echo of a hash we just wrote ourselves.
+    if (selfWrittenHash.current === hash) {
+      selfWrittenHash.current = null;
+      return;
+    }
+
+    const parsed = parseHash(hash, urlKey);
+
+    if (parsed.open) {
+      const resolved = resolveSection
+        ? resolveSection(parsed.section)
+        : parsed.section;
+      // open() preserves the current section when called without one, so only
+      // pass a section when the URL actually named a (valid) one.
+      open(resolved ?? undefined);
+    } else if (isOpen) {
+      // Hash no longer points at us (back button, manual edit) → close.
+      close();
+    }
+    // We intentionally depend on `hash` only; isOpen is read fresh via the
+    // store getter semantics above. Re-running on isOpen would double-fire.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [hash, enabled, urlKey]);
+
+  // ── store → URL ──────────────────────────────────────────────────────────
+  useEffect(() => {
+    if (!enabled) return;
+    if (typeof window === 'undefined') return;
+
+    const current = window.location.hash;
+
+    if (isOpen) {
+      const next = buildHash(urlKey, activeSection);
+      if (current !== next) {
+        selfWrittenHash.current = next;
+        // push so the back button can close; refresh keeps the section.
+        navigate(`${urlWithoutHash()}${next}`);
+      }
+    } else {
+      // Only strip if the hash is *ours*; never clobber an unrelated hash.
+      const parsed = parseHash(current, urlKey);
+      if (parsed.open) {
+        selfWrittenHash.current = '';
+        navigate(urlWithoutHash(), { replace: true });
+      }
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [isOpen, activeSection, enabled, urlKey]);
+}

package/src/layouts/SettingsLayout/index.ts

@@ -0,0 +1,67 @@
+/**
+ * SettingsLayout
+ *
+ * A Claude.ai-style settings surface: a searchable, grouped section rail on the
+ * left and a scrollable detail panel on the right, available as a global dialog
+ * (URL-hash driven, zustand-backed) or an inline form.
+ *
+ * Designed to eventually supersede ProfileLayout. Built in parallel — both
+ * coexist for now.
+ *
+ *   // Mount once (PrivateLayout does this):
+ *   <SettingsDialog sections={appSections} builtins={{ security: true }} />
+ *
+ *   // Open from anywhere:
+ *   const settings = useSettingsDialog();
+ *   settings.open('billing');          // or navigate to #settings/billing
+ *
+ *   // Inline page variant:
+ *   <SettingsForm sections={appSections} />
+ */
+
+'use client';
+
+// Top-level components
+export { SettingsDialog } from './SettingsDialog';
+export { SettingsForm } from './SettingsForm';
+
+// Store + public hooks
+export { useSettingsDialogStore } from './store';
+export {
+  useSettingsDialog,
+  useSettingsUrl,
+  useSettingsSections,
+} from './hooks';
+export type {
+  UseSettingsDialogReturn,
+  UseSettingsUrlOptions,
+  ResolvedGroup,
+} from './hooks';
+
+// Context (for advanced custom shells)
+export { SettingsProvider, useSettingsContext } from './context';
+export type { SettingsProviderProps } from './context';
+
+// Shell parts (compose a bespoke layout if needed)
+export { SettingsShell, SettingsNav, SettingsNavItem, SettingsPanel, SettingsSearch, SettingsTabs } from './components';
+
+// Built-in sections + helpers (extend/replace the defaults)
+export {
+  buildBuiltinSections,
+  BUILTIN_GROUP,
+  AccountSection,
+  SecuritySection,
+  ApiKeysSection,
+  SettingRow,
+  SettingsBlock,
+} from './sections';
+
+// Types
+export type {
+  SettingsSection,
+  SettingsGroup,
+  SettingsBuiltins,
+  SettingsContent,
+  SettingsFormProps,
+  SettingsDialogProps,
+} from './types';

package/src/layouts/SettingsLayout/sections/AccountSection.tsx

@@ -0,0 +1,100 @@
+'use client';
+
+import React from 'react';
+
+import { useAuth } from '@djangocfg/api/auth';
+import { SettingRow, SettingsBlock } from '@djangocfg/ui-core/components';
+
+import { AvatarSection } from '../components/AvatarSection';
+import { useProfileSave } from '../hooks/useProfileSave';
+import { DeleteAccountRow } from './DeleteAccountRow';
+import { PreferencesRows } from './PreferencesRows';
+
+interface AccountSectionProps {
+  /** Render the "Danger zone" delete-account control. Default: true. */
+  enableDeleteAccount?: boolean;
+}
+
+/**
+ * Built-in "Account" section — macOS / Claude-settings layout: flat blocks of
+ * label↔control rows divided by hairlines, no card frames.
+ *
+ * Editable fields are declared inline via SettingRow's props API
+ * (`value` + `editable` + `onSave`); the chip/input styling lives in SettingRow.
+ * Save logic + labels come from `useProfileSave` (no context wrapper needed).
+ */
+export const AccountSection: React.FC<AccountSectionProps> = ({
+  enableDeleteAccount = true,
+}) => {
+  const { labels, save: onFieldSave } = useProfileSave();
+  const { user } = useAuth();
+
+  if (!user) return null;
+
+  return (
+    <div className="mx-auto max-w-2xl space-y-7">
+      <SettingsBlock title={labels.personalInfo}>
+        <SettingRow label="Avatar">
+          {/* AvatarSection ships a 56–80px avatar; constrain to ~40px without
+              forking it (the fixed box drives row height, inner scale shrinks). */}
+          <div className="flex h-10 w-10 items-center justify-center">
+            <div className="origin-center scale-[0.5]">
+              <AvatarSection />
+            </div>
+          </div>
+        </SettingRow>
+        <SettingRow
+          label={labels.firstName}
+          value={user.first_name || ''}
+          placeholder={labels.addFirstName}
+          editable
+          onSave={(v) => onFieldSave('first_name', v)}
+        />
+        <SettingRow
+          label={labels.lastName}
+          value={user.last_name || ''}
+          placeholder={labels.addLastName}
+          editable
+          onSave={(v) => onFieldSave('last_name', v)}
+        />
+        <SettingRow
+          label={labels.phone}
+          value={user.phone || ''}
+          placeholder={labels.addPhone}
+          type="phone"
+          editable
+          onSave={(v) => onFieldSave('phone', v)}
+        />
+      </SettingsBlock>
+
+      <SettingsBlock title={labels.work}>
+        <SettingRow
+          label={labels.company}
+          value={user.company || ''}
+          placeholder={labels.addCompany}
+          editable
+          onSave={(v) => onFieldSave('company', v)}
+        />
+        <SettingRow
+          label={labels.position}
+          value={user.position || ''}
+          placeholder={labels.addPosition}
+          editable
+          onSave={(v) => onFieldSave('position', v)}
+        />
+      </SettingsBlock>
+
+      <SettingsBlock title={labels.preferences ?? 'Preferences'}>
+        <PreferencesRows />
+      </SettingsBlock>
+
+      {enableDeleteAccount && (
+        // The whole Danger zone is collapsible (closed by default) so
+        // destructive actions stay tucked away until deliberately revealed.
+        <SettingsBlock title="Danger zone" collapsible defaultOpen={false}>
+          <DeleteAccountRow />
+        </SettingsBlock>
+      )}
+    </div>
+  );
+};

package/src/layouts/SettingsLayout/sections/ApiKeysSection.tsx

@@ -0,0 +1,15 @@
+'use client';
+
+import React from 'react';
+
+import { ApiKeySection } from '../components/ApiKeySection';
+
+/**
+ * Built-in "API keys" section body. Wraps the existing ApiKeySection (display,
+ * regenerate, test). The panel header supplies the title.
+ */
+export const ApiKeysSection: React.FC = () => (
+  <div className="mx-auto max-w-2xl space-y-6">
+    <ApiKeySection />
+  </div>
+);

package/src/layouts/SettingsLayout/sections/DeleteAccountRow.tsx

@@ -0,0 +1,57 @@
+'use client';
+
+import React from 'react';
+import { Loader2, Trash2 } from 'lucide-react';
+
+import { useAuth, useDeleteAccount } from '@djangocfg/api/auth';
+import { useAppT } from '@djangocfg/i18n';
+import { Button, SettingRow } from '@djangocfg/ui-core/components';
+
+/**
+ * Compact "Delete account" row — a flat row with a small destructive button on
+ * the right. Lives inside the collapsible "Danger zone" block, so the section
+ * itself is what's hidden by default; the typed-confirmation prompt is the
+ * final safety gate.
+ */
+export const DeleteAccountRow: React.FC = () => {
+  const { logout } = useAuth();
+  const { deleteAccount, isLoading } = useDeleteAccount();
+  const t = useAppT();
+
+  const confirmationWord = t('layouts.profilePage.confirmationWord');
+
+  const handleDelete = async () => {
+    const value = await window.dialog.prompt({
+      title: t('layouts.profilePage.deleteAccountTitle'),
+      message: t('layouts.profilePage.deleteAccountDesc'),
+      placeholder: confirmationWord,
+      confirmText: t('layouts.profilePage.deleteAccount'),
+      cancelText: t('layouts.profilePage.cancel'),
+      variant: 'destructive',
+    });
+
+    if (value?.toUpperCase() !== confirmationWord.toUpperCase()) return;
+
+    const result = await deleteAccount();
+    if (result.success) logout();
+  };
+
+  return (
+    <SettingRow
+      label={t('layouts.profilePage.deleteAccount')}
+      description="Permanently remove your account and all associated data."
+      action={
+        <Button
+          variant="destructive"
+          size="sm"
+          onClick={handleDelete}
+          disabled={isLoading}
+          className="shrink-0"
+        >
+          {isLoading ? <Loader2 className="size-4 animate-spin" /> : <Trash2 className="size-4" />}
+          {t('layouts.profilePage.deleteAccount')}
+        </Button>
+      }
+    />
+  );
+};

package/src/layouts/SettingsLayout/sections/PreferencesRows.tsx

@@ -0,0 +1,43 @@
+'use client';
+
+import React from 'react';
+
+import { SettingRow } from '@djangocfg/ui-core/components';
+import { ThemeSegmented } from '@djangocfg/ui-core/theme';
+
+import { LocaleSwitcherDropdown } from '../../_components/locale-switcher';
+import { useLayoutI18nOptional } from '../../AppLayout/LayoutI18nProvider';
+
+/**
+ * Preferences as native SettingRows (Language + Theme), so they share the exact
+ * row/divider/spacing of the rest of the settings panel. Mirrors the controls
+ * from ProfileLayout's PreferencesSection but in the lighter Claude-style row
+ * layout. Language only renders when a layout i18n context is present.
+ */
+export const PreferencesRows: React.FC = () => {
+  const layoutI18n = useLayoutI18nOptional();
+
+  return (
+    <>
+      {layoutI18n && (
+        <SettingRow
+          label="Language"
+          action={
+            <LocaleSwitcherDropdown
+              locale={layoutI18n.locale}
+              locales={layoutI18n.locales}
+              onChange={layoutI18n.onLocaleChange}
+              variant="outline"
+              size="sm"
+              showCode
+              showIcon={false}
+              showFlag
+              showTriggerLabel
+            />
+          }
+        />
+      )}
+      <SettingRow label="Theme" action={<ThemeSegmented />} />
+    </>
+  );
+};

package/src/layouts/SettingsLayout/sections/SecuritySection.tsx

@@ -0,0 +1,15 @@
+'use client';
+
+import React from 'react';
+
+import { TwoFactorSection } from '../components/TwoFactorSection';
+
+/**
+ * Built-in "Security" section body — two-factor auth setup/disable.
+ * Wraps the existing TwoFactorSection; the panel header supplies the title.
+ */
+export const SecuritySection: React.FC = () => (
+  <div className="mx-auto max-w-2xl space-y-6">
+    <TwoFactorSection />
+  </div>
+);

package/src/layouts/SettingsLayout/sections/builtins.tsx

@@ -0,0 +1,77 @@
+'use client';
+
+import React from 'react';
+
+import { KeyRound, ShieldCheck, UserRound } from 'lucide-react';
+
+import type { SettingsBuiltins, SettingsGroup, SettingsSection } from '../types';
+import { AccountSection } from './AccountSection';
+import { ApiKeysSection } from './ApiKeysSection';
+import { SecuritySection } from './SecuritySection';
+
+/**
+ * The group every built-in section belongs to. App sections can reuse this id
+ * to sit alongside the built-ins, or define their own groups.
+ */
+export const BUILTIN_GROUP: SettingsGroup = { id: 'general', label: 'General', order: 0 };
+
+interface BuildBuiltinArgs {
+  builtins: SettingsBuiltins;
+  enableDeleteAccount: boolean;
+}
+
+/**
+ * Construct the enabled built-in sections. Pure function of the flags — labels
+ * are left as plain strings here (the inner section bodies pull localized copy
+ * from ProfileProvider); only the nav-level label/title live at this layer.
+ *
+ * Defaults: account on, security off (needs API support), apiKeys on.
+ */
+export function buildBuiltinSections({
+  builtins,
+  enableDeleteAccount,
+}: BuildBuiltinArgs): SettingsSection[] {
+  const { account = true, security = false, apiKeys = true } = builtins;
+  const sections: SettingsSection[] = [];
+
+  if (account) {
+    sections.push({
+      id: 'account',
+      label: 'Account',
+      icon: UserRound,
+      group: BUILTIN_GROUP.id,
+      title: 'Account',
+      description: 'Manage your profile, preferences, and account.',
+      keywords: ['profile', 'name', 'email', 'avatar', 'language', 'theme', 'preferences'],
+      content: <AccountSection enableDeleteAccount={enableDeleteAccount} />,
+    });
+  }
+
+  if (security) {
+    sections.push({
+      id: 'security',
+      label: 'Security',
+      icon: ShieldCheck,
+      group: BUILTIN_GROUP.id,
+      title: 'Security',
+      description: 'Two-factor authentication and active sessions.',
+      keywords: ['2fa', 'two-factor', 'mfa', 'authenticator', 'password', 'devices'],
+      content: <SecuritySection />,
+    });
+  }
+
+  if (apiKeys) {
+    sections.push({
+      id: 'api-keys',
+      label: 'API keys',
+      icon: KeyRound,
+      group: BUILTIN_GROUP.id,
+      title: 'API keys',
+      description: 'Create and manage keys for programmatic access.',
+      keywords: ['api', 'token', 'key', 'secret', 'developer'],
+      content: <ApiKeysSection />,
+    });
+  }
+
+  return sections;
+}

package/src/layouts/SettingsLayout/sections/index.ts

@@ -0,0 +1,8 @@
+export { buildBuiltinSections, BUILTIN_GROUP } from './builtins';
+export { AccountSection } from './AccountSection';
+export { SecuritySection } from './SecuritySection';
+export { ApiKeysSection } from './ApiKeysSection';
+// SettingRow/SettingsBlock now live in ui-core (universal). Re-export for
+// backward compatibility with consumers importing them from @djangocfg/layouts.
+export { SettingRow, SettingsBlock } from '@djangocfg/ui-core/components';
+export { PreferencesRows } from './PreferencesRows';