@djangocfg/layouts 2.1.425 → 2.1.427

package/src/layouts/PublicLayout/components/UserMenu.tsx

@@ -30,7 +30,7 @@
 
 'use client';
 
-import { ArrowRight, Globe, LogOut } from 'lucide-react';
+import { ArrowRight, Languages, LogOut } from 'lucide-react';
 import { Link } from '@djangocfg/ui-core/components';
 import React, { useMemo } from 'react';
 
@@ -40,18 +40,10 @@ import { useAppT } from '@djangocfg/i18n';
 import { useLogout } from '../../../hooks';
 import {
   Button,
-  DropdownMenu,
-  DropdownMenuContent,
-  DropdownMenuGroup,
-  DropdownMenuItem,
-  DropdownMenuLabel,
-  DropdownMenuSeparator,
-  DropdownMenuSub,
-  DropdownMenuSubContent,
-  DropdownMenuSubTrigger,
-  DropdownMenuTrigger,
   LanguageFlag,
+  MenuBuilder,
 } from '@djangocfg/ui-core/components';
+import type { MenuItem } from '@djangocfg/ui-core/components';
 
 import { LOCALE_LABELS } from '../../_components/LocaleSwitcher';
 import { UserAvatar } from './UserAvatar';
@@ -124,8 +116,6 @@ export function UserMenu({
     };
   }, [i18n]);
 
-  const hasProfileGroups = profileGroups.length > 0;
-
   const localeLabel = (code: string) => LOCALE_LABELS[code] || code.toUpperCase();
 
   if (!mounted) {
@@ -269,107 +259,72 @@ export function UserMenu({
     );
   }
 
-  // Desktop variant
-  return (
-    <DropdownMenu>
-      <DropdownMenuTrigger asChild>
-        <Button variant="ghost" size="icon" className="rounded-full p-0">
-          <UserAvatar src={userAvatar} name={displayName} size="sm" />
-          <span className="sr-only">{labels.userMenu}</span>
-        </Button>
-      </DropdownMenuTrigger>
-      <DropdownMenuContent align="end" className="w-56">
-        <DropdownMenuLabel>
-          <div className="flex flex-col space-y-1">
-            <p className="text-sm font-medium leading-none">{displayName}</p>
-            <p className="text-xs leading-none text-muted-foreground">
-              {user.email}
-            </p>
-          </div>
-        </DropdownMenuLabel>
-        <DropdownMenuSeparator />
-        {profileGroups.map((group, groupIndex) => (
-          <React.Fragment key={groupIndex}>
-            {groupIndex > 0 && <DropdownMenuSeparator />}
-            <DropdownMenuGroup>
-              {group.title && (
-                <DropdownMenuLabel className="text-[11px] font-normal text-muted-foreground/70 py-1">
-                  {group.title}
-                </DropdownMenuLabel>
-              )}
-              {group.items.map((item, itemIndex) => {
-                const Icon = item.icon;
-                const isDestructive = item.variant === 'destructive';
-
-                if (item.onClick) {
-                  return (
-                    <DropdownMenuItem
-                      key={itemIndex}
-                      onClick={item.onClick}
-                      className={isDestructive ? 'text-destructive focus:text-destructive' : ''}
-                    >
-                      {Icon && <Icon className="mr-2 h-4 w-4" />}
-                      <span>{item.label}</span>
-                    </DropdownMenuItem>
-                  );
-                }
-
-                if (item.href) {
-                  return (
-                    <DropdownMenuItem key={itemIndex} asChild>
-                      <Link
-                        href={item.href}
-                        className={`flex items-center ${isDestructive ? 'text-destructive' : ''}`}
-                      >
-                        {Icon && <Icon className="mr-2 h-4 w-4" />}
-                        <span>{item.label}</span>
-                      </Link>
-                    </DropdownMenuItem>
-                  );
-                }
+  // Desktop variant — declarative menu via the shared MenuBuilder.
+  const menuItems: MenuItem[] = [
+    {
+      kind: 'label',
+      id: 'identity',
+      label: (
+        <div className="flex flex-col space-y-1">
+          <p className="text-sm font-medium leading-none">{displayName}</p>
+          <p className="text-xs leading-none text-muted-foreground">{user.email}</p>
+        </div>
+      ),
+    },
+    // App-provided link groups (each its own section with a trailing separator).
+    ...profileGroups.map((group, i): MenuItem => ({
+      kind: 'section',
+      id: `group-${i}`,
+      label: group.title,
+      items: group.items.map((item, j): MenuItem => ({
+        kind: 'item',
+        id: item.href ?? `${i}-${j}`,
+        label: item.label,
+        icon: item.icon,
+        href: item.href,
+        onSelect: item.onClick ? () => item.onClick!() : undefined,
+        variant: item.variant === 'destructive' ? 'destructive' : 'default',
+      })),
+    })),
+    // Language submenu — radio group of locales (flag + label + checkmark).
+    ...(localeMenu
+      ? [{
+          kind: 'submenu' as const,
+          id: 'language',
+          label: labels.language,
+          icon: Languages,
+          items: [{
+            kind: 'radio-group' as const,
+            id: 'locale',
+            value: localeMenu.current,
+            onValueChange: localeMenu.onChange,
+            options: localeMenu.codes.map((code) => ({
+              id: code,
+              value: code,
+              label: localeLabel(code),
+              icon: <LanguageFlag code={code} className="h-3 w-4 shrink-0" rounded />,
+            })),
+          }],
+        }]
+      : []),
+    { kind: 'separator', id: 'sep-logout' },
+    {
+      kind: 'item',
+      id: 'signout',
+      label: signOutItem.label,
+      icon: LogOut,
+      variant: 'destructive',
+      onSelect: () => signOutItem.onClick(),
+    },
+  ];
 
-                return null;
-              })}
-            </DropdownMenuGroup>
-          </React.Fragment>
-        ))}
-        {localeMenu && (
-          <>
-            {hasProfileGroups && <DropdownMenuSeparator />}
-            <DropdownMenuSub>
-              <DropdownMenuSubTrigger className="cursor-default">
-                <Globe className="mr-2 h-4 w-4" />
-                <span>{labels.language}</span>
-              </DropdownMenuSubTrigger>
-              <DropdownMenuSubContent>
-                {localeMenu.codes.map((code) => (
-                  <DropdownMenuItem
-                    key={code}
-                    onSelect={() => {
-                      localeMenu.onChange(code);
-                    }}
-                    className={code === localeMenu.current ? 'bg-accent' : ''}
-                  >
-                    <LanguageFlag code={code} className="mr-2 h-3 w-4" rounded />
-                    {localeLabel(code)}
-                  </DropdownMenuItem>
-                ))}
-              </DropdownMenuSubContent>
-            </DropdownMenuSub>
-          </>
-        )}
-        <DropdownMenuSeparator />
-        <DropdownMenuGroup>
-          <DropdownMenuItem
-            onClick={signOutItem.onClick}
-            className="text-destructive focus:text-destructive"
-          >
-            <LogOut className="mr-2 h-4 w-4" />
-            <span>{signOutItem.label}</span>
-          </DropdownMenuItem>
-        </DropdownMenuGroup>
-      </DropdownMenuContent>
-    </DropdownMenu>
+  return (
+    <MenuBuilder items={menuItems} align="end" contentClassName="w-56">
+      <Button variant="ghost" size="icon" className="rounded-full p-0">
+        <UserAvatar src={userAvatar} name={displayName} size="sm" />
+        <span className="sr-only">{labels.userMenu}</span>
+      </Button>
+    </MenuBuilder>
   );
 }
 

package/src/layouts/PublicLayout/navbars/MinimalNavbar/MinimalNavbar.tsx

@@ -30,12 +30,6 @@ import type { NavigationItem, UserMenuConfig } from '../../../types';
 
 import { MinimalMobileDrawer } from './MinimalMobileDrawer';
 
-/**
- * @deprecated Use `NavAction` from `@djangocfg/layouts`. Kept as an alias so
- * existing imports keep working.
- */
-export type MinimalNavbarAction = NavAction;
-
 export interface MinimalNavbarConfig {
   brand?: ReactNode;
   /** @default '/' */

package/src/layouts/PublicLayout/navbars/MinimalNavbar/index.ts

@@ -1,3 +1,3 @@
 export { MinimalNavbar } from './MinimalNavbar';
-export type { MinimalNavbarConfig, MinimalNavbarProps, MinimalNavbarAction } from './MinimalNavbar';
+export type { MinimalNavbarConfig, MinimalNavbarProps } from './MinimalNavbar';
 export { MinimalMobileDrawer } from './MinimalMobileDrawer';

package/src/layouts/SettingsLayout/README.md

@@ -0,0 +1,258 @@
+# 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, openable from anywhere) or an **inline form**.
+
+Designed to eventually supersede [`ProfileLayout`](../ProfileLayout/README.md).
+The two coexist for now — `SettingsLayout` is built in parallel and does not touch
+the old component.
+
+**Desktop** — master/detail (nav rail + scrolling panel):
+
+```
+┌─ Settings ───────────────────────────────────┐
+│ ⌕ Search           │  Account            ✕    │
+│ GENERAL            │  ───────────────────────  │
+│  Account     ◀     │  PERSONAL INFORMATION     │
+│  Security          │  Avatar          ( J )    │
+│  API keys          │  First name      [ Jane ] │
+│ WORKSPACE          │  Last name       [Cooper] │
+│  Usage             │  …                        │
+└────────────────────┴───────────────────────────┘
+```
+
+**Mobile** (`<md`) — title header + horizontal tab strip + panel
+(Claude phone pattern):
+
+```
+┌─ Settings                              ✕ ─┐
+│ [Account] Security  API keys  Usage  …    │
+│ ─────────────────────────────────────────  │
+│  PERSONAL INFORMATION                       │
+│  …                                          │
+└────────────────────────────────────────────┘
+```
+
+The two layouts are switched with `useIsMobile` (see Responsive below) because
+they use genuinely different nav components — a vertical grouped rail vs. a flat
+horizontal tab strip — not just a flex-direction flip.
+
+## Quick start
+
+### Global dialog (recommended)
+
+Mount it once near the root of the authenticated app (PrivateLayout does this for
+you via its `settings` prop), then open it from anywhere.
+
+```tsx
+// 1. Mount once — either let PrivateLayout do it…
+<PrivateLayout settings={{ sections: appSections, builtins: { security: true } }}>
+  {children}
+</PrivateLayout>
+
+// …or mount <SettingsDialog/> yourself.
+<SettingsDialog sections={appSections} builtins={{ security: true }} />
+
+// 2. Open from any component:
+const settings = useSettingsDialog();
+<button onClick={() => settings.open()}>Settings</button>
+<button onClick={() => settings.open('billing')}>Billing</button>
+
+// 3. …or just navigate to the hash:
+//    #settings           → opens
+//    #settings/api-keys  → opens on the API-keys section
+```
+
+### Inline page
+
+```tsx
+<SettingsForm sections={appSections} builtins={{ security: true }} />
+```
+
+## URL sync (`#settings/<section>`)
+
+When `syncUrl` is on (default for `SettingsDialog`), the dialog two-way-binds to
+the URL hash:
+
+| URL                  | Result                                  |
+| -------------------- | --------------------------------------- |
+| `#settings`          | open, first / last-active section       |
+| `#settings/usage`    | open, **usage** section active          |
+| no / other hash      | closed                                  |
+
+- **Deep-link / refresh** reopens on the same section.
+- **Back button** closes the dialog (the open state is a history entry).
+- Switching section **pushes** a new hash, so it's shareable.
+
+It's powered by ui-core's framework-agnostic `useLocation` (a `useSyncExternalStore`
+over patched `history` + `hashchange`) — **no `next/router` import**, works in any
+adapter. An unknown section id in the URL falls back gracefully (dialog opens on
+the first section instead of selecting nothing).
+
+Disable with `syncUrl={false}` for imperative-only use (e.g. inside Storybook,
+where the preview iframe URL shouldn't be hijacked).
+
+## Sections
+
+A section is a plain config object — apps extend the surface by appending to an
+array. The shape mirrors the old `ProfileTab` (`{ id, label, content }`) so
+migrating a tab is a near-rename.
+
+```ts
+interface SettingsSection {
+  id: string;                       // unique; also the URL hash segment
+  label: React.ReactNode;           // nav label
+  icon?: React.ComponentType;       // lucide icon (optional)
+  group?: string;                   // group id; default group when omitted
+  title?: React.ReactNode;          // panel heading (defaults to label)
+  description?: React.ReactNode;    // panel sub-heading
+  content: React.ReactNode;         // the panel body
+  keywords?: string[];              // extra search terms
+  order?: number;                   // sort within group
+  badge?: React.ReactNode;          // trailing nav accessory
+  hidden?: boolean;                 // hide from rail, still reachable by id
+}
+```
+
+Only the **active** section's `content` is mounted. Switching sections remounts
+the panel subtree (resets scroll + transient form state) — the expected settings
+UX. Closing the dialog unmounts everything (Radix default), so heavy panels cost
+nothing while closed.
+
+### Groups
+
+Sections cluster into labelled groups in the rail. Declare them for
+ordering/labelling, or just name an ad-hoc `group` on a section:
+
+```ts
+const groups = [
+  { id: 'general', label: 'General', order: 0 },
+  { id: 'workspace', label: 'Workspace', order: 1 },
+];
+```
+
+### Built-in sections
+
+`SettingsLayout` ships the proven ProfileLayout pieces as default sections,
+toggled via `builtins`:
+
+| id          | flag                 | default | content                              |
+| ----------- | -------------------- | ------- | ------------------------------------ |
+| `account`   | `builtins.account`   | `true`  | avatar + inline-editable profile/work fields, Preferences (Language dropdown + `ThemeSegmented`), and a **collapsible Danger zone** (delete account) |
+| `security`  | `builtins.security`  | `false` | two-factor auth (row-style)          |
+| `api-keys`  | `builtins.apiKeys`   | `true`  | API key display / regenerate / test (row-style) |
+
+Built-ins are merged **ahead of** app sections. They reuse the localized labels
+and save/validation logic from `ProfileProvider`, so behaviour stays in one place.
+The built-in bodies are built from the ui-core `SettingRow`/`SettingsBlock`
+primitives (see below) — flat rows with hairline dividers, no card frames.
+
+> The `security` / `api-keys` bodies hit the real backend (2FA status, API key
+> retrieval). With no backend (e.g. Storybook) they show an error/empty state —
+> that's expected; gate them with `builtins` where there's no API.
+
+## Row primitives live in ui-core
+
+The building blocks for section bodies are **universal** and live in
+`@djangocfg/ui-core/components`, not here — so any settings-like surface in the
+product can reuse them:
+
+```tsx
+import { SettingRow, SettingsBlock } from '@djangocfg/ui-core/components';
+import { ThemeSegmented } from '@djangocfg/ui-core/theme';
+```
+
+**`SettingRow`** — one `label ↔ control` line with a hairline divider. Props-driven
+control modes (precedence top→bottom):
+
+| Mode | Props | Renders |
+| --- | --- | --- |
+| Editable value | `value` + `editable` + `onSave` (`type='text'\|'phone'`) | inline-edit chip → ui-core `Input` (`sm`) on click |
+| Read-only value | `value` | a value chip |
+| Toggle | `toggle` + `checked` + `onToggle` | ui-core `Switch` |
+| Navigation | `navigation` (+ `onClick`) | full-row button with a trailing chevron |
+| Action | `action={<Button/>}` | right-aligned node |
+| Custom | `children` | anything (e.g. `ThemeSegmented`) |
+
+**`SettingsBlock`** — a titled cluster of rows (`title` renders as a small uppercase
+header). Pass `collapsible` (+ `defaultOpen`) to make the whole block expandable
+(used for the Danger zone).
+
+```tsx
+<SettingsBlock title="Personal information">
+  <SettingRow label="First name" value={user.firstName} editable onSave={save} />
+  <SettingRow label="Notifications" toggle checked={on} onToggle={setOn} />
+  <SettingRow label="Manage memory" navigation onClick={openMemory} />
+  <SettingRow label="Theme"><ThemeSegmented /></SettingRow>
+</SettingsBlock>
+
+<SettingsBlock title="Danger zone" collapsible>
+  <SettingRow label="Delete account" action={<DeleteButton />} />
+</SettingsBlock>
+```
+
+> These were promoted out of this package into ui-core during the Claude-style
+> redesign so they're reusable everywhere and benefit from the global Input
+> focus/token system. See ui-core `styles/README.md` for the token + focus rules.
+
+## Architecture
+
+Decomposed so it's safe to grow:
+
+```
+SettingsLayout/
+├── index.ts                 public barrel
+├── types.ts                 SettingsSection / Group / Content / props
+├── store.ts                 zustand: { isOpen, activeSection, open/close/setSection }
+├── SettingsDialog.tsx       global modal (store + URL sync → SettingsForm)
+├── SettingsForm.tsx         inline shell (ProfileProvider → SettingsProvider → Shell)
+├── context/
+│   └── SettingsContext.tsx  resolved sections + active + search, shared by shell parts
+├── hooks/
+│   ├── useSettingsUrl.ts      hash ⇄ store two-way bind
+│   ├── useSettingsDialog.ts   public open/close API for consumers
+│   └── useSettingsSections.ts pure: merge/order/group/filter sections
+├── components/
+│   ├── SettingsShell.tsx      desktop rail+panel vs mobile tabs+panel (useIsMobile)
+│   ├── SettingsNav.tsx        desktop rail: title + search + grouped items
+│   ├── SettingsNavItem.tsx    one rail row
+│   ├── SettingsTabs.tsx       mobile horizontal tab strip (text chips, auto-scroll active)
+│   ├── SettingsSearch.tsx     filter box
+│   └── SettingsPanel.tsx      header + independently-scrolling body
+└── sections/
+    ├── builtins.tsx           account/security/api-keys factory
+    ├── AccountSection.tsx     avatar + fields + preferences + danger zone (row-style)
+    ├── PreferencesRows.tsx    Language dropdown + ThemeSegmented as SettingRows
+    ├── DeleteAccountRow.tsx   compact destructive row (inside collapsible Danger zone)
+    ├── SecuritySection.tsx    2FA wrapper
+    └── ApiKeysSection.tsx     API-keys wrapper
+```
+
+> The row primitives (`SettingRow` / `SettingsBlock`) live in **ui-core**, not
+> here — section bodies import them. See "Row primitives live in ui-core" above.
+
+- **Selection** is controlled by the dialog (bound to the store) or uncontrolled
+  (local state) for the inline form — `SettingsProvider` hides the difference.
+- **Search** filters the rail by label + `keywords`; picking a section clears it.
+- **Responsive** is JS-driven via ui-core's SSR-safe `useIsMobile` (false on the
+  server, re-syncs on mount). Desktop (`≥md`): vertical grouped rail + panel.
+  Mobile (`<md`): title header + horizontal tab strip + panel; the dialog goes
+  near-fullscreen. A breakpoint hook (not CSS) is used because the two layouts
+  use different nav components, not just a different flex direction.
+
+## Customising the shell
+
+For a bespoke layout, compose the parts yourself with `SettingsProvider` +
+`useSettingsContext`, or reuse `SettingsShell`, `SettingsNav`, `SettingsTabs`,
+`SettingsPanel` directly. The built-in section bodies (`AccountSection`, etc.) are
+exported too; the row primitives come from `@djangocfg/ui-core/components`.
+
+## Migrating from ProfileLayout
+
+1. A `ProfileTab` `{ value, label, content }` → a `SettingsSection`
+   `{ id, label, content }` (rename `value` → `id`; add `icon`/`group`/`keywords`
+   as desired).
+2. `useProfileDialogStore.open({ initialTab })` → `useSettingsDialog().open(id)`.
+3. Mount `<SettingsDialog/>` instead of `<ProfileDialog/>` (or pass `settings` to
+   PrivateLayout). The account button can be repointed to `useSettingsDialog()`.

package/src/layouts/SettingsLayout/SettingsDialog.tsx

@@ -0,0 +1,101 @@
+'use client';
+
+import React, { useCallback, useMemo } from 'react';
+
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogTitle,
+} from '@djangocfg/ui-core/components';
+import { useIsMobile } from '@djangocfg/ui-core/hooks';
+import { cn } from '@djangocfg/ui-core/lib';
+
+import { SettingsForm } from './SettingsForm';
+import { useSettingsUrl } from './hooks/useSettingsUrl';
+import { buildBuiltinSections } from './sections';
+import { useSettingsDialogStore } from './store';
+import type { SettingsDialogProps } from './types';
+
+/**
+ * SettingsDialog — the globally-mounted settings modal.
+ *
+ * Mount once (PrivateLayout does this). Open it from anywhere via
+ * `useSettingsDialog().open()` or by navigating to `#settings/<section>`.
+ *
+ * Reads transient state (open + active section) from the zustand store and
+ * binds it to the controlled <SettingsForm>. When `syncUrl` (default) it also
+ * two-way-binds that state to the URL hash via useSettingsUrl.
+ */
+export const SettingsDialog: React.FC<SettingsDialogProps> = ({
+  syncUrl = true,
+  urlKey = 'settings',
+  title,
+  sections: appSections = [],
+  groups,
+  builtins = {},
+  initialSection,
+  searchable = true,
+  enableDeleteAccount = true,
+}) => {
+  const isOpen = useSettingsDialogStore((s) => s.isOpen);
+  const activeSection = useSettingsDialogStore((s) => s.activeSection);
+  const close = useSettingsDialogStore((s) => s.close);
+  const setSection = useSettingsDialogStore((s) => s.setSection);
+  const isMobile = useIsMobile();
+
+  // Set of valid ids, so a bad URL hash falls back gracefully instead of
+  // selecting a non-existent section. Cheap to recompute; built-ins are pure.
+  const knownIds = useMemo(() => {
+    const builtin = buildBuiltinSections({ builtins, enableDeleteAccount });
+    const ids = new Set<string>();
+    [...builtin, ...appSections].forEach((s) => ids.add(s.id));
+    return ids;
+  }, [builtins, enableDeleteAccount, appSections]);
+
+  const resolveSection = useCallback(
+    (id: string | null) => (id && knownIds.has(id) ? id : null),
+    [knownIds],
+  );
+
+  useSettingsUrl({ urlKey, enabled: syncUrl, resolveSection });
+
+  const resolvedTitle = title ?? 'Settings';
+
+  return (
+    <Dialog open={isOpen} onOpenChange={(open) => !open && close()}>
+      <DialogContent
+        // Desktop: centered card with breathing room (capped, gap to edges).
+        // Mobile: near-fullscreen sheet (small inset) so the phone settings get
+        // the whole screen, like Claude. Elevated `bg-card` lifts it off the page.
+        className={cn(
+          'flex max-w-none flex-col gap-0 overflow-hidden border border-border bg-card p-0',
+          isMobile
+            ? 'h-[calc(100dvh-2rem)] w-[calc(100vw-1.5rem)]'
+            : 'h-[min(620px,calc(100vh-6rem))] w-[min(900px,calc(100vw-4rem))]',
+        )}
+      >
+        {/* Accessible label — the visible heading lives in the nav rail. */}
+        <DialogTitle className="sr-only">
+          {typeof resolvedTitle === 'string' ? resolvedTitle : 'Settings'}
+        </DialogTitle>
+        <DialogDescription className="sr-only">
+          Application settings
+        </DialogDescription>
+
+        <SettingsForm
+          bare
+          title={resolvedTitle}
+          sections={appSections}
+          groups={groups}
+          builtins={builtins}
+          initialSection={initialSection}
+          searchable={searchable}
+          enableDeleteAccount={enableDeleteAccount}
+          activeSection={activeSection ?? undefined}
+          onSectionChange={setSection}
+        />
+      </DialogContent>
+    </Dialog>
+  );
+};