@djangocfg/layouts 2.1.601 → 2.1.603

package/src/layouts/PrivateLayout/types.ts

@@ -15,9 +15,8 @@ import type { UserMenuConfig } from '../types';
 // Sidebar Item Types
 // ============================================================================
 
-export interface SidebarItem {
+interface SidebarItemBase {
   label: string;
-  href: string;
   icon?: string | LucideIcon;
   badge?: string | number;
   /** Visual style of `badge`: `'count'` (default, neutral pill) or `'pill'` (accent-tinted, e.g. "lite"/"new"). */
@@ -26,15 +25,39 @@ export interface SidebarItem {
   tooltip?: string;
 }
 
+/** A row that navigates to a route. */
+export interface SidebarLinkItem extends SidebarItemBase {
+  href: string;
+  settingsSection?: never;
+}
+
+/**
+ * A row that opens the Settings dialog on a section. It renders only while the mounted `SettingsDialog` lists that
+ * section, so there is no dead door when a section is switched off or not registered yet; it is active while the
+ * dialog shows the section. `Id` is the section-id union (see `defineSettingsSections`); a bare `SidebarItem` takes any string.
+ */
+export interface SidebarSettingsItem<Id extends string = string> extends SidebarItemBase {
+  settingsSection: Id;
+  href?: never;
+}
+
+/** A sidebar row: a link (`href`) or a Settings launcher (`settingsSection`). */
+export type SidebarItem<Id extends string = string> = SidebarLinkItem | SidebarSettingsItem<Id>;
+
 // ============================================================================
 // Sidebar Group Types
 // ============================================================================
 
-export interface SidebarGroupConfig {
+export interface SidebarGroupConfig<Id extends string = string> {
   /** Group label displayed above items */
   label: string;
-  /** Items in this group */
-  items: SidebarItem[];
+  /** Items in this group. A group whose items are all `settingsSection` rows for unregistered sections is not rendered. */
+  items: SidebarItem<Id>[];
+  /**
+   * A secondary group (setup, connect): a full divider with extra space above it, and the label below the divider if
+   * there is one. The default groups are only a hairline apart. Works in the docked sidebar, the peek panel and the drawer.
+   */
+  separated?: boolean;
   /** If true, group is only shown when it has items (for dynamic groups like extensions) */
   dynamic?: boolean;
   /** Render group as an accordion (Mailersend/Vercel-style). Label becomes a clickable trigger. */
@@ -73,9 +96,9 @@ export interface SidebarFeaturedConfig {
 // Sidebar Config
 // ============================================================================
 
-export interface SidebarConfig {
+export interface SidebarConfig<Id extends string = string> {
   /** Grouped items with labels */
-  groups: SidebarGroupConfig[];
+  groups: SidebarGroupConfig<Id>[];
   /** Home link href */
   homeHref?: string;
   /**

package/src/layouts/SettingsLayout/README.md

@@ -64,6 +64,27 @@ const settings = useSettingsDialog();
 //    #settings/api-keys  → opens on the API-keys section
 ```
 
+### Typed section ids
+
+`useSettingsDialog().open(id)` takes any string by default, so a typo opens the first section silently. Declare the
+sections with `defineSettingsSections` and give the hook the id union; an unknown id is then a compile error.
+
+```tsx
+const sections = defineSettingsSections([mcpSettingsSection(), { id: 'billing', label: 'Billing', content: <Billing /> }]);
+type AppSection = SettingsSectionId<typeof sections>;        // 'mcp' | 'billing' | 'account' | 'general' | 'api-keys'
+
+<PrivateLayout settings={{ sections }} sidebar={{ groups: [
+  { label: 'Workspace', items: [{ label: 'Billing', settingsSection: 'billing' } satisfies SidebarItem<AppSection>] },
+  mcpSidebarGroup({ label: 'Connect' }),                      // separated group, appears only if 'mcp' is registered
+] }}>
+const { open } = useSettingsDialog<AppSection>();            // open('biling') does not compile
+<a href={settingsHref<AppSection>('billing')}>Billing</a>     // "#settings/billing"
+```
+
+`mcpSettingsSection()` returns `id: 'mcp'` as a literal, so it keeps its place in the union; a section whose `id` is a
+plain `string` widens the union to `string` (the old behaviour). Existing `useSettingsDialog()` callers are unchanged.
+`settingsHref(id, urlKey = 'settings')` is the one place that spells the `#settings/<id>` fragment.
+
 ### Inline page
 
 ```tsx

package/src/layouts/SettingsLayout/components/AvatarSection.tsx

@@ -123,7 +123,6 @@ export const AvatarSection = () => {
         size="sm"
         onClick={handlePick}
         disabled={isUploading}
-        className="h-8"
       >
         {isUploading ? 'Uploading…' : 'Change avatar'}
       </Button>

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

@@ -13,3 +13,6 @@ export type {
 
 export { useAccountMenuItems } from './useAccountMenuItems';
 export type { UseAccountMenuItemsOptions } from './useAccountMenuItems';
+
+export { useSettingsSectionState } from './useSettingsSectionState';
+export type { SettingsSectionState } from './useSettingsSectionState';

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

@@ -9,6 +9,9 @@
  *   <Button onClick={() => settings.open()}>Settings</Button>
  *   <MenuItem onClick={() => settings.open('billing')}>Billing</MenuItem>
  *
+ * The id is `string` by default. Pass the union of your sections to make a typo a compile error:
+ *   const settings = useSettingsDialog<SettingsSectionId<typeof sections>>();   // see `defineSettingsSections`
+ *
  * Returns stable callbacks, safe in deps arrays. The dialog itself must be
  * mounted once in the tree (PrivateLayout does this).
  */
@@ -17,24 +20,24 @@ import { useCallback, useMemo } from 'react';
 
 import { useSettingsDialogStore, type SettingsMenuSection } from '../store';
 
-export interface UseSettingsDialogReturn {
+export interface UseSettingsDialogReturn<Id extends string = string> {
   /** Whether the dialog is currently open. */
   isOpen: boolean;
   /** Currently active section id (null = fall back to first). */
-  activeSection: string | null;
+  activeSection: Id | null;
   /** Open the dialog, optionally on a specific section. */
-  open: (sectionId?: string) => void;
+  open: (sectionId?: Id) => void;
   /** Close the dialog. */
   close: () => void;
   /** Toggle open/closed. */
   toggle: () => void;
   /** Switch the active section. */
-  setSection: (sectionId: string) => void;
+  setSection: (sectionId: Id) => void;
   /** The visible sections of the mounted dialog (built-in and the host's), in rail order: for menu shortcuts, `open(id)`. */
   sections: SettingsMenuSection[];
 }
 
-export function useSettingsDialog(): UseSettingsDialogReturn {
+export function useSettingsDialog<Id extends string = string>(): UseSettingsDialogReturn<Id> {
   const isOpen = useSettingsDialogStore((s) => s.isOpen);
   const activeSection = useSettingsDialogStore((s) => s.activeSection);
   const storeOpen = useSettingsDialogStore((s) => s.open);
@@ -43,13 +46,13 @@ export function useSettingsDialog(): UseSettingsDialogReturn {
   const storeSetSection = useSettingsDialogStore((s) => s.setSection);
   const sections = useSettingsDialogStore((s) => s.sections);
 
-  const open = useCallback((sectionId?: string) => storeOpen(sectionId), [storeOpen]);
+  const open = useCallback((sectionId?: Id) => storeOpen(sectionId), [storeOpen]);
   const close = useCallback(() => storeClose(), [storeClose]);
   const toggle = useCallback(() => storeToggle(), [storeToggle]);
-  const setSection = useCallback((id: string) => storeSetSection(id), [storeSetSection]);
+  const setSection = useCallback((id: Id) => storeSetSection(id), [storeSetSection]);
 
   return useMemo(
-    () => ({ isOpen, activeSection, open, close, toggle, setSection, sections }),
+    () => ({ isOpen, activeSection: activeSection as Id | null, open, close, toggle, setSection, sections }),
     [isOpen, activeSection, open, close, toggle, setSection, sections],
   );
 }

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

@@ -0,0 +1,32 @@
+'use client';
+
+/**
+ * useSettingsSectionState — what a launcher of one Settings section needs to know: is the section registered with the
+ * mounted dialog (a launcher for a missing section is a dead door), is the dialog showing it now, and how to open it.
+ *
+ * Reads the same store `useSettingsDialog` does. Registration comes from `<SettingsDialog />`, which lists its visible
+ * sections (built-in and the host's) after it mounts, so before that, or with no dialog, nothing is registered.
+ */
+
+import { useCallback } from 'react';
+
+import { useSettingsDialogStore } from '../store';
+
+export interface SettingsSectionState {
+  /** The dialog lists this section in its rail. */
+  registered: boolean;
+  /** The dialog is open and showing this section (an open dialog with no pick shows the first one). */
+  active: boolean;
+  /** Open the dialog on this section. */
+  open: () => void;
+}
+
+export function useSettingsSectionState(id: string): SettingsSectionState {
+  const registered = useSettingsDialogStore((s) => s.sections.some((section) => section.id === id));
+  const active = useSettingsDialogStore(
+    (s) => s.isOpen && (s.activeSection ?? s.sections[0]?.id ?? null) === id,
+  );
+  const storeOpen = useSettingsDialogStore((s) => s.open);
+  const open = useCallback(() => storeOpen(id), [storeOpen, id]);
+  return { registered, active, open };
+}

package/src/layouts/SettingsLayout/index.ts

@@ -43,6 +43,10 @@ export type {
   ResolvedGroup,
 } from './hooks';
 
+// Typed section ids, the `#settings/<id>` address
+export { defineSettingsSections, settingsHref, MCP_SECTION_ID } from './sectionIds';
+export type { SettingsSectionId, BuiltinSettingsSectionId } from './sectionIds';
+
 // Context (for advanced custom shells)
 export { SettingsProvider, useSettingsContext } from './context';
 export type { SettingsProviderProps } from './context';

package/src/layouts/SettingsLayout/sectionIds.test-d.ts

@@ -0,0 +1,51 @@
+/**
+ * Type tests: tsc (vitest typecheck, and `pnpm check`) must accept the first block and reject every
+ * `@ts-expect-error` line. A line that stops being an error fails the build.
+ */
+
+import type { ComponentType } from 'react';
+import { describe, expectTypeOf, it } from 'vitest';
+
+import { MCP_SECTION_ID, defineSettingsSections, settingsHref, type SettingsSectionId } from './sectionIds';
+import { useSettingsDialog } from './hooks/useSettingsDialog';
+import type { SettingsSection } from './types';
+
+declare const mcpLike: { id: 'mcp'; label: string; content: null; icon: ComponentType<{ className?: string }> };
+
+const sections = defineSettingsSections([mcpLike, { id: 'billing', label: 'Billing', content: null }]);
+type AppId = SettingsSectionId<typeof sections>;
+
+describe('typed settings section ids', () => {
+  it('the id union is the declared ids plus the built-ins', () => {
+    expectTypeOf<AppId>().toEqualTypeOf<'mcp' | 'billing' | 'account' | 'general' | 'api-keys'>();
+    expectTypeOf(MCP_SECTION_ID).toEqualTypeOf<'mcp'>();
+  });
+
+  it('the result still goes where a SettingsSection[] goes', () => {
+    expectTypeOf(sections).toMatchTypeOf<SettingsSection[]>();
+  });
+
+  it('useSettingsDialog<Id> accepts known ids only', () => {
+    const typed = useSettingsDialog<AppId>();
+    typed.open('billing');
+    typed.setSection('mcp');
+    // @ts-expect-error unknown id
+    typed.open('biling');
+    // @ts-expect-error unknown id
+    typed.setSection('nope');
+    expectTypeOf(typed.activeSection).toEqualTypeOf<AppId | null>();
+  });
+
+  it('the untyped default still takes any string', () => {
+    const loose = useSettingsDialog();
+    loose.open('anything');
+    loose.setSection('else');
+    expectTypeOf(loose.activeSection).toEqualTypeOf<string | null>();
+  });
+
+  it('settingsHref keeps the id in the type', () => {
+    expectTypeOf(settingsHref('mcp')).toEqualTypeOf<`#${string}/mcp`>();
+    // @ts-expect-error the helper for a typed id rejects other strings
+    settingsHref<AppId>('biling');
+  });
+});

package/src/layouts/SettingsLayout/sectionIds.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest';
+
+import { parseSettingsHash } from './intent/parseSettingsHash';
+import { MCP_SECTION_ID, defineSettingsSections, settingsHref } from './sectionIds';
+
+describe('settingsHref', () => {
+  it('spells the fragment the dialog reads', () => {
+    expect(settingsHref('mcp')).toBe('#settings/mcp');
+    expect(settingsHref('api-keys')).toBe('#settings/api-keys');
+  });
+
+  it('follows a custom urlKey', () => {
+    expect(settingsHref('mcp', 'prefs')).toBe('#prefs/mcp');
+  });
+
+  it('round-trips through the parser', () => {
+    const fragment = settingsHref('billing').slice(1);
+    expect(parseSettingsHash(fragment, 'settings')).toMatchObject({ open: true, section: 'billing' });
+  });
+});
+
+describe('defineSettingsSections', () => {
+  it('returns the very array it was given', () => {
+    const list = [{ id: 'billing', label: 'Billing', content: null }];
+    expect(defineSettingsSections(list)).toBe(list);
+  });
+
+  it('MCP_SECTION_ID is the id the MCP widget uses', () => {
+    expect(MCP_SECTION_ID).toBe('mcp');
+  });
+});

package/src/layouts/SettingsLayout/sectionIds.ts

@@ -0,0 +1,43 @@
+/**
+ * Typed section ids.
+ *
+ * The dialog is mounted once and driven through a global store, so its `sections` prop cannot type the hooks that
+ * open it. Declare the sections with `defineSettingsSections` and hand the id union to the hook instead:
+ *
+ *   const sections = defineSettingsSections([mcpSettingsSection(), { id: 'billing', ... }]);
+ *   type AppSection = SettingsSectionId<typeof sections>;       // 'mcp' | 'billing' | built-in ids
+ *   useSettingsDialog<AppSection>().open('biling');             // compile error
+ *
+ * Nothing here is runtime weight beyond two one-line functions.
+ */
+
+import type { SettingsSection } from './types';
+
+/** Ids of the sections the layout ships (`builtins`). They are openable whether or not the host switched one off. */
+export type BuiltinSettingsSectionId = 'account' | 'general' | 'api-keys';
+
+/**
+ * The id of the MCP section. `@djangocfg/widget-mcp` (`mcpSettingsSection()`) uses the same literal; layouts cannot
+ * import the widget (a package never depends on a widget), so the two agree by value and each side has a test on it.
+ */
+export const MCP_SECTION_ID = 'mcp' as const;
+
+/** The ids of a section list: the host's own plus the built-ins. Collapses to `string` if any id is not a literal. */
+export type SettingsSectionId<S extends readonly { id: string }[]> = S[number]['id'] | BuiltinSettingsSectionId;
+
+/**
+ * Identity function that keeps each section's `id` as a literal type, so `SettingsSectionId<typeof sections>` is a
+ * closed union. Accepts the result of `mcpSettingsSection()` as is.
+ */
+export function defineSettingsSections<const S extends SettingsSection[]>(sections: S): S {
+  return sections;
+}
+
+/**
+ * The address that opens the dialog on a section: `settingsHref('mcp')` is `"#settings/mcp"`. For a plain link
+ * (`href`, `<a>`), a route table or an email; `useSettingsUrl` opens the dialog when the page lands on it.
+ * `urlKey` follows `SettingsDialog`'s `urlKey` prop.
+ */
+export function settingsHref<Id extends string = string>(id: Id, urlKey = 'settings'): `#${string}/${Id}` {
+  return `#${urlKey}/${id}`;
+}

package/src/testing/MockAuthFormProvider.tsx

@@ -12,7 +12,7 @@ import {
 
 import { AuthFormContext } from '../layouts/AuthLayout/context';
 import { resolveOAuthProviders } from '../layouts/AuthLayout/components/oauth/oauthProviders';
-import type { AuthFormContextType, AuthLayoutConfig } from '../layouts/AuthLayout/types';
+import type { AuthFormContextType, AuthLayoutConfig, OAuthFailure } from '../layouts/AuthLayout/types';
 
 // Storybook-only provider. Reproduces the AuthFormContext shape with
 // in-memory state and no-op async handlers, so step components and the
@@ -117,6 +117,7 @@ const MockAuthFormProviderBase: React.FC<MockAuthFormProviderProps> = ({
   );
 
   const isAutoSubmittingFromUrl = useRef(false);
+  const [oauthNotice, setOAuthNotice] = useState<OAuthFailure | null>(null);
 
   const value: AuthFormContextType = useMemo(() => {
     const stop = (e: React.FormEvent) => {
@@ -177,6 +178,8 @@ const MockAuthFormProviderBase: React.FC<MockAuthFormProviderProps> = ({
       termsUrl,
       privacyUrl,
       oauth,
+      oauthNotice,
+      setOAuthNotice,
       logo,
       redirectUrl,
       marketingConsentConfig,
@@ -197,6 +200,7 @@ const MockAuthFormProviderBase: React.FC<MockAuthFormProviderProps> = ({
     termsUrl,
     privacyUrl,
     oauth,
+    oauthNotice,
     logo,
     redirectUrl,
     marketingConsentConfig,