@djangocfg/layouts 2.1.601 → 2.1.602

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/layouts",
-  "version": "2.1.601",
+  "version": "2.1.602",
   "description": "Simple, straightforward layout components for Next.js - import and use with props",
   "keywords": [
     "layouts",
@@ -91,11 +91,11 @@
     "test": "vitest run"
   },
   "peerDependencies": {
-    "@djangocfg/analytics": "^2.1.601",
-    "@djangocfg/api": "^2.1.601",
-    "@djangocfg/devtools": "^2.1.601",
-    "@djangocfg/i18n": "^2.1.601",
-    "@djangocfg/ui-core": "^2.1.601",
+    "@djangocfg/analytics": "^2.1.602",
+    "@djangocfg/api": "^2.1.602",
+    "@djangocfg/devtools": "^2.1.602",
+    "@djangocfg/i18n": "^2.1.602",
+    "@djangocfg/ui-core": "^2.1.602",
     "@hookform/resolvers": "^5.2.2",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
@@ -125,12 +125,12 @@
     "uuid": "^11.1.1"
   },
   "devDependencies": {
-    "@djangocfg/analytics": "^2.1.601",
-    "@djangocfg/api": "^2.1.601",
-    "@djangocfg/devtools": "^2.1.601",
-    "@djangocfg/i18n": "^2.1.601",
-    "@djangocfg/typescript-config": "^2.1.601",
-    "@djangocfg/ui-core": "^2.1.601",
+    "@djangocfg/analytics": "^2.1.602",
+    "@djangocfg/api": "^2.1.602",
+    "@djangocfg/devtools": "^2.1.602",
+    "@djangocfg/i18n": "^2.1.602",
+    "@djangocfg/typescript-config": "^2.1.602",
+    "@djangocfg/ui-core": "^2.1.602",
     "@storybook/react-vite": "^10.5.0",
     "@types/node": "^25.9.5",
     "@types/react": "19.2.15",

package/src/layouts/PrivateLayout/PrivateLayout.tsx

@@ -31,6 +31,8 @@ import type { PrivateLayoutProps } from './types';
 
 export type {
   SidebarItem,
+  SidebarLinkItem,
+  SidebarSettingsItem,
   SidebarGroupConfig,
   SidebarConfig,
   HeaderConfig,

package/src/layouts/PrivateLayout/README.md

@@ -151,7 +151,8 @@ For pages like Kanban boards where the shell must be exactly one viewport tall a
 | Field | Type | Notes |
 |---|---|---|
 | `label` | `string` | Group title. Empty string → flat group (no header). |
-| `items` | `SidebarItem[]` | Nav links. |
+| `items` | `SidebarItem[]` | Nav links, or `settingsSection` rows (below). A group whose rows are all launchers for unregistered sections is not rendered. |
+| `separated` | `boolean` | A secondary group (setup, connect): a full divider with air above it, then the label. Ordinary groups are only a hairline apart. Same in the docked sidebar, the peek panel and the drawer (there is no icon rail: a collapsed sidebar is hidden). |
 | `dynamic` | `boolean` | Hide group when `items` is empty (for extension-driven groups). |
 | `collapsible` | `boolean` | Render as accordion. Label becomes a clickable trigger; auto-expanded if a child is active. |
 | `defaultOpen` | `boolean` | Initial open state for collapsible groups. |
@@ -163,9 +164,12 @@ For pages like Kanban boards where the shell must be exactly one viewport tall a
 | Field | Type | Notes |
 |---|---|---|
 | `label`, `href`, `icon`, `tooltip` | — | Standard nav item fields. |
+| `settingsSection` | section id | Instead of `href`: a row that opens the Settings dialog on that section. Rendered only while the mounted dialog lists the section (no dead door), active while the dialog shows it. Type it with `SidebarItem<AppSectionId>` (see [SettingsLayout](../SettingsLayout/README.md#typed-section-ids)). |
 | `badge` | `string \| number` | Trailing badge content. |
 | `badgeVariant` | `'count' \| 'pill'` | Visual style. `'pill'` is accent-tinted (e.g. "lite"/"new"); `'count'` is neutral (default). |
 
+**MCP defaults.** `mcpSidebarItem({ label, icon = 'Cable' })` and `mcpSidebarGroup({ label, itemLabel = 'MCP' })` are ready entries for the section `mcpSettingsSection()` (`@djangocfg/widget-mcp`) registers. Layouts matches it by id (`MCP_SECTION_ID`), so it has no dependency on the widget. Add them unconditionally; they vanish while the section is not registered.
+
 `SidebarFeaturedConfig`:
 
 | Field | Type | Notes |

package/src/layouts/PrivateLayout/components/SidebarBody.tsx

@@ -8,6 +8,7 @@
 import React, { useMemo } from 'react';
 
 import { usePrivateLayoutContext } from '../context';
+import { sidebarItemKey } from '../sidebarItems';
 import { PrivateSidebarAccount } from './PrivateSidebarAccount';
 import { SidebarBrand } from './SidebarBrand';
 import { SidebarNavGroup } from './SidebarNavGroup';
@@ -19,9 +20,10 @@ export function SidebarBody() {
   const groups = useMemo(
     () =>
       (sidebar?.groups ?? []).map((group) =>
+        // A group of launchers for sections nobody registered renders nothing itself (see SidebarNavGroup).
         group.dynamic && group.items.length === 0 ? null : (
           <SidebarNavGroup
-            key={group.label || `__flat_${group.items.map((i) => i.href).join('|')}`}
+            key={group.label || `__flat_${group.items.map(sidebarItemKey).join('|')}`}
             group={group}
           />
         ),

package/src/layouts/PrivateLayout/components/SidebarNav.test.tsx

@@ -0,0 +1,152 @@
+// @vitest-environment jsdom
+import React, { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeAll, beforeEach, describe, expect, it } from 'vitest';
+
+import { SidebarProvider } from '@djangocfg/ui-core/components';
+
+import { useSettingsDialogStore } from '../../SettingsLayout/store';
+import { PrivateLayoutProvider } from '../context';
+import { mcpSidebarGroup } from '../mcpSidebar';
+import type { SidebarConfig, SidebarGroupConfig } from '../types';
+import { SidebarNavGroup } from './SidebarNavGroup';
+
+// react-dom + jsdom only: the package declares no testing-library.
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+let host: HTMLElement | null = null;
+let root: Root | null = null;
+
+/** Elements by ARIA role and accessible text (own text content), enough for these rows. */
+const screen = {
+  all(selector: string, name?: string): HTMLElement[] {
+    const found = Array.from(host?.querySelectorAll<HTMLElement>(selector) ?? []);
+    return name === undefined ? found : found.filter((el) => el.textContent?.trim() === name);
+  },
+  link: (name: string) => screen.all('a[href]', name)[0] ?? null,
+  button: (name: string) => screen.all('button', name)[0] ?? null,
+  separators: () => screen.all('[role="separator"]'),
+  text: (value: string) => screen.all('span, div, p', value)[0] ?? null,
+};
+
+beforeAll(() => {
+  // jsdom has no matchMedia; the sidebar's mobile check reads it.
+  window.matchMedia ??= ((query: string) => ({
+    matches: false,
+    media: query,
+    onchange: null,
+    addEventListener: () => {},
+    removeEventListener: () => {},
+    addListener: () => {},
+    removeListener: () => {},
+    dispatchEvent: () => false,
+  })) as typeof window.matchMedia;
+});
+
+const registerSections = (...ids: string[]) =>
+  useSettingsDialogStore.setState({ sections: ids.map((id) => ({ id, label: id })) });
+
+function renderGroups(groups: SidebarGroupConfig[], pathname = '/') {
+  const sidebar: SidebarConfig = { groups };
+  host = document.createElement('div');
+  document.body.appendChild(host);
+  root = createRoot(host);
+  act(() => root!.render(
+    <SidebarProvider>
+      <PrivateLayoutProvider sidebar={sidebar} header={undefined} pathname={pathname} isMobile={false}>
+        {groups.map((group, i) => (
+          <SidebarNavGroup key={i} group={group} />
+        ))}
+      </PrivateLayoutProvider>
+    </SidebarProvider>,
+  ));
+}
+
+const main: SidebarGroupConfig = { label: 'Main', items: [{ label: 'Home', href: '/' }, { label: 'Reports', href: '/reports' }] };
+const connect = mcpSidebarGroup({ label: 'Connect', itemLabel: 'MCP' });
+
+beforeEach(() => {
+  useSettingsDialogStore.setState({ sections: [], isOpen: false, activeSection: null, intent: null });
+});
+afterEach(() => {
+  act(() => root?.unmount());
+  host?.remove();
+  host = root = null;
+});
+
+describe('href rows (unchanged)', () => {
+  it('render as links and mark the current route', () => {
+    renderGroups([main], '/reports');
+    const reports = screen.link('Reports')!;
+    expect(reports.getAttribute('href')).toBe('/reports');
+    expect(reports.getAttribute('aria-current')).toBe('page');
+    expect(screen.link('Home')!.getAttribute('aria-current')).toBeNull();
+    expect(screen.separators()).toHaveLength(0);
+  });
+});
+
+describe('settingsSection rows', () => {
+  it('render nothing, and no group, while the section is not registered', () => {
+    renderGroups([main, connect]);
+    expect(screen.button('MCP')).toBeNull();
+    expect(screen.text('Connect')).toBeNull();
+    expect(screen.separators()).toHaveLength(0);
+  });
+
+  it('appear once the section is registered, and open the dialog on it', () => {
+    registerSections('account', 'mcp');
+    renderGroups([main, connect]);
+    act(() => screen.button('MCP')!.click());
+    const state = useSettingsDialogStore.getState();
+    expect(state.isOpen).toBe(true);
+    expect(state.activeSection).toBe('mcp');
+  });
+
+  it('are active only while the dialog shows that section', () => {
+    registerSections('account', 'mcp');
+    renderGroups([main, connect]);
+    const row = () => screen.button('MCP')!;
+    expect(row().getAttribute('aria-current')).toBeNull();
+
+    act(() => useSettingsDialogStore.getState().open('account'));
+    expect(row().getAttribute('aria-current')).toBeNull();
+
+    act(() => useSettingsDialogStore.getState().open('mcp'));
+    expect(row().getAttribute('aria-current')).toBe('true');
+    expect(row().getAttribute('data-active')).toBe('true');
+
+    act(() => useSettingsDialogStore.getState().close());
+    expect(row().getAttribute('aria-current')).toBeNull();
+  });
+
+  it('do not take over the route highlight of href rows', () => {
+    registerSections('mcp');
+    renderGroups([main, connect], '/');
+    expect(screen.link('Home')!.getAttribute('aria-current')).toBe('page');
+  });
+});
+
+describe('separated groups', () => {
+  it('draw a divider above the label', () => {
+    registerSections('mcp');
+    renderGroups([main, connect]);
+    const separators = screen.separators();
+    expect(separators).toHaveLength(1);
+    const divider = separators[0]!;
+    const label = screen.text('Connect')!;
+    expect(divider.compareDocumentPosition(label) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
+    expect(divider.getAttribute('data-sidebar')).toBe('group-divider');
+  });
+
+  it('draw a bare divider when the label is empty', () => {
+    registerSections('mcp');
+    renderGroups([main, mcpSidebarGroup({ label: '' })]);
+    expect(screen.separators()).toHaveLength(1);
+    expect(screen.button('MCP')).not.toBeNull();
+  });
+
+  it('are not drawn for ordinary groups', () => {
+    renderGroups([main, { label: 'More', items: [{ label: 'Docs', href: '/docs' }] }]);
+    expect(screen.separators()).toHaveLength(0);
+  });
+});

package/src/layouts/PrivateLayout/components/SidebarNavGroup.tsx

@@ -20,8 +20,10 @@ import {
 import { cn } from '@djangocfg/ui-core/lib';
 
 import { LucideIcon } from '../../../components';
+import { useSettingsDialogStore } from '../../SettingsLayout/store';
 import { shallowEqualBy } from '../../../utils/shallowEqualBy';
 import { usePrivateLayoutContext } from '../context';
+import { isSettingsItem, isSidebarGroupVisible, sidebarItemKey, visibleSidebarItems } from '../sidebarItems';
 import type { SidebarGroupConfig } from '../types';
 import { SidebarNavItem } from './SidebarNavItem';
 
@@ -30,6 +32,21 @@ const GROUP_CLASS = cn(
   '[&:not(:first-child)]:mt-1 [&:not(:first-child)]:border-t [&:not(:first-child)]:border-sidebar-border/60 [&:not(:first-child)]:pt-2',
 );
 
+/** A `separated` group draws its own, stronger divider (below), so it drops the hairline and takes more air. */
+const SEPARATED_GROUP_CLASS = 'gap-0 px-2 pb-1 pt-0';
+
+/** Full-width rule with room above and below; decorative, so the rail and the drawer read the same. */
+function GroupDivider() {
+  return (
+    <div
+      role="separator"
+      aria-orientation="horizontal"
+      data-sidebar="group-divider"
+      className="mx-2 mb-2 mt-3 h-px shrink-0 bg-sidebar-border"
+    />
+  );
+}
+
 function SidebarNavGroupRaw({ group }: { group: SidebarGroupConfig }) {
   const { isActive, geometry } = usePrivateLayoutContext();
 
@@ -37,9 +54,20 @@ function SidebarNavGroupRaw({ group }: { group: SidebarGroupConfig }) {
   const isCollapsible = Boolean(group.collapsible) && hasLabel;
   const hideItemIcons = group.hideItemIcons ?? isCollapsible;
 
+  const menuSections = useSettingsDialogStore((s) => s.sections);
+  const dialogSection = useSettingsDialogStore((s) =>
+    s.isOpen ? (s.activeSection ?? s.sections[0]?.id ?? null) : null,
+  );
+  const registered = useMemo(() => new Set(menuSections.map((s) => s.id)), [menuSections]);
+  const items = useMemo(() => visibleSidebarItems(group.items, registered), [group.items, registered]);
+  const visible = isSidebarGroupVisible(group, registered);
+
   const hasActiveChild = useMemo(
-    () => group.items.some((item) => isActive(item.href)),
-    [group.items, isActive],
+    () =>
+      items.some((item) =>
+        isSettingsItem(item) ? item.settingsSection === dialogSection : isActive(item.href),
+      ),
+    [items, isActive, dialogSection],
   );
 
   const [open, setOpen] = useState(isCollapsible ? Boolean(group.defaultOpen) || hasActiveChild : true);
@@ -50,59 +78,69 @@ function SidebarNavGroupRaw({ group }: { group: SidebarGroupConfig }) {
 
   const handleOpenChange = useCallback((value: boolean) => setOpen(value), []);
 
-  const items = group.items.map((item) => (
-    <SidebarNavItem key={item.href} item={item} hideItemIcons={hideItemIcons} />
+  const rows = items.map((item) => (
+    <SidebarNavItem key={sidebarItemKey(item)} item={item} hideItemIcons={hideItemIcons} />
   ));
+  if (!visible) return null;
+
+  const groupClass = group.separated ? SEPARATED_GROUP_CLASS : GROUP_CLASS;
+  const divider = group.separated ? <GroupDivider /> : null;
 
   if (isCollapsible) {
     return (
-      <SidebarGroup className={GROUP_CLASS}>
-        <Collapsible open={open} onOpenChange={handleOpenChange} className="w-full">
-          <CollapsibleTrigger asChild>
-            <button
-              type="button"
-              aria-expanded={open}
-              className={cn(
-                'flex w-full items-center gap-2.5 rounded-lg font-normal text-sidebar-foreground',
-                'transition-colors duration-150 hover:bg-sidebar-accent/60',
-                'outline-none ring-sidebar-ring focus-visible:ring-2',
-                geometry.item,
-              )}
-            >
-              {group.icon ? <LucideIcon icon={group.icon} className="shrink-0 text-sidebar-foreground/60" /> : null}
-              <span className="flex-1 truncate text-left">{group.label}</span>
-              <ChevronDown
-                aria-hidden
+      <>
+        {divider}
+        <SidebarGroup className={groupClass}>
+          <Collapsible open={open} onOpenChange={handleOpenChange} className="w-full">
+            <CollapsibleTrigger asChild>
+              <button
+                type="button"
+                aria-expanded={open}
                 className={cn(
-                  'size-4 shrink-0 text-sidebar-foreground/50 transition-transform duration-200',
-                  open && 'rotate-180',
+                  'flex w-full items-center gap-2.5 rounded-lg font-normal text-sidebar-foreground',
+                  'transition-colors duration-150 hover:bg-sidebar-accent/60',
+                  'outline-none ring-sidebar-ring focus-visible:ring-2',
+                  geometry.item,
                 )}
-              />
-            </button>
-          </CollapsibleTrigger>
-          <CollapsibleContent className="overflow-hidden data-[state=closed]:animate-accordion-up data-[state=open]:animate-accordion-down">
-            <SidebarGroupContent>
-              <SidebarMenu className="mt-0.5 gap-0.5">{items}</SidebarMenu>
-            </SidebarGroupContent>
-          </CollapsibleContent>
-        </Collapsible>
-      </SidebarGroup>
+              >
+                {group.icon ? <LucideIcon icon={group.icon} className="shrink-0 text-sidebar-foreground/60" /> : null}
+                <span className="flex-1 truncate text-left">{group.label}</span>
+                <ChevronDown
+                  aria-hidden
+                  className={cn(
+                    'size-4 shrink-0 text-sidebar-foreground/50 transition-transform duration-200',
+                    open && 'rotate-180',
+                  )}
+                />
+              </button>
+            </CollapsibleTrigger>
+            <CollapsibleContent className="overflow-hidden data-[state=closed]:animate-accordion-up data-[state=open]:animate-accordion-down">
+              <SidebarGroupContent>
+                <SidebarMenu className="mt-0.5 gap-0.5">{rows}</SidebarMenu>
+              </SidebarGroupContent>
+            </CollapsibleContent>
+          </Collapsible>
+        </SidebarGroup>
+      </>
     );
   }
 
   return (
-    <SidebarGroup className={GROUP_CLASS}>
-      {hasLabel ? (
-        <SidebarGroupLabel
-          className={cn('font-medium normal-case tracking-normal text-sidebar-foreground/50', geometry.label)}
-        >
-          {group.label}
-        </SidebarGroupLabel>
-      ) : null}
-      <SidebarGroupContent>
-        <SidebarMenu className="gap-0.5">{items}</SidebarMenu>
-      </SidebarGroupContent>
-    </SidebarGroup>
+    <>
+      {divider}
+      <SidebarGroup className={groupClass}>
+        {hasLabel ? (
+          <SidebarGroupLabel
+            className={cn('font-medium normal-case tracking-normal text-sidebar-foreground/50', geometry.label)}
+          >
+            {group.label}
+          </SidebarGroupLabel>
+        ) : null}
+        <SidebarGroupContent>
+          <SidebarMenu className="gap-0.5">{rows}</SidebarMenu>
+        </SidebarGroupContent>
+      </SidebarGroup>
+    </>
   );
 }
 
@@ -112,12 +150,14 @@ const groupEqual = (a: SidebarGroupConfig, b: SidebarGroupConfig) =>
   a.defaultOpen === b.defaultOpen &&
   a.icon === b.icon &&
   a.hideItemIcons === b.hideItemIcons &&
+  a.separated === b.separated &&
   a.dynamic === b.dynamic &&
   shallowEqualBy(
     a.items,
     b.items,
     (x, y) =>
       x.href === y.href &&
+      x.settingsSection === y.settingsSection &&
       x.label === y.label &&
       x.icon === y.icon &&
       x.badge === y.badge &&

package/src/layouts/PrivateLayout/components/SidebarNavItem.tsx

@@ -17,7 +17,9 @@ import { cn } from '@djangocfg/ui-core/lib';
 
 import { LucideIcon } from '../../../components';
 import { usePrivateLayoutContext } from '../context';
-import type { SidebarItem } from '../types';
+import { useSettingsSectionState } from '../../SettingsLayout/hooks/useSettingsSectionState';
+import { isSettingsItem } from '../sidebarItems';
+import type { SidebarItem, SidebarLinkItem, SidebarSettingsItem } from '../types';
 
 interface SidebarNavItemProps {
   item: SidebarItem;
@@ -32,7 +34,47 @@ const ITEM_CLASS = cn(
   'data-[active=true]:[&>svg]:text-sidebar-foreground',
 );
 
-function SidebarNavItemRaw({ item, hideItemIcons }: SidebarNavItemProps) {
+function ItemContent({ item, hideItemIcons }: SidebarNavItemProps) {
+  return (
+    <>
+      {!hideItemIcons && item.icon ? <LucideIcon icon={item.icon} /> : null}
+      <span>{item.label}</span>
+      {item.badge ? (
+        <SidebarMenuBadge
+          className={cn(item.badgeVariant === 'pill' && 'rounded-md bg-primary/15 px-1.5 font-medium text-primary')}
+        >
+          {item.badge}
+        </SidebarMenuBadge>
+      ) : null}
+    </>
+  );
+}
+
+/**
+ * A row that opens Settings on a section. Not rendered while the dialog does not list the section (no dead door),
+ * active while the dialog shows it. The dialog owns the URL, so a row never writes the address itself.
+ */
+function SidebarSettingsNavItem({ item, hideItemIcons }: { item: SidebarSettingsItem; hideItemIcons?: boolean }) {
+  const { geometry } = usePrivateLayoutContext();
+  const { registered, active, open } = useSettingsSectionState(item.settingsSection);
+  if (!registered) return null;
+
+  return (
+    <SidebarMenuItem>
+      <SidebarMenuButton
+        isActive={active}
+        onClick={open}
+        aria-haspopup="dialog"
+        aria-current={active ? 'true' : undefined}
+        className={cn(ITEM_CLASS, geometry.item, hideItemIcons && 'pl-8')}
+      >
+        <ItemContent item={item} hideItemIcons={hideItemIcons} />
+      </SidebarMenuButton>
+    </SidebarMenuItem>
+  );
+}
+
+function SidebarLinkNavItem({ item, hideItemIcons }: { item: SidebarLinkItem; hideItemIcons?: boolean }) {
   const { isActive, geometry } = usePrivateLayoutContext();
   const active = isActive(item.href);
 
@@ -44,25 +86,24 @@ function SidebarNavItemRaw({ item, hideItemIcons }: SidebarNavItemProps) {
         className={cn(ITEM_CLASS, geometry.item, hideItemIcons && 'pl-8')}
       >
         <Link href={item.href} aria-current={active ? 'page' : undefined}>
-          {!hideItemIcons && item.icon ? <LucideIcon icon={item.icon} /> : null}
-          <span>{item.label}</span>
-          {item.badge ? (
-            <SidebarMenuBadge
-              className={cn(
-                item.badgeVariant === 'pill' && 'rounded-md bg-primary/15 px-1.5 font-medium text-primary',
-              )}
-            >
-              {item.badge}
-            </SidebarMenuBadge>
-          ) : null}
+          <ItemContent item={item} hideItemIcons={hideItemIcons} />
         </Link>
       </SidebarMenuButton>
     </SidebarMenuItem>
   );
 }
 
+function SidebarNavItemRaw({ item, hideItemIcons }: SidebarNavItemProps) {
+  return isSettingsItem(item) ? (
+    <SidebarSettingsNavItem item={item} hideItemIcons={hideItemIcons} />
+  ) : (
+    <SidebarLinkNavItem item={item} hideItemIcons={hideItemIcons} />
+  );
+}
+
 const itemEqual = (a: SidebarItem, b: SidebarItem) =>
   a.href === b.href &&
+  a.settingsSection === b.settingsSection &&
   a.label === b.label &&
   a.icon === b.icon &&
   a.badge === b.badge &&

package/src/layouts/PrivateLayout/context.tsx

@@ -11,7 +11,8 @@ import React, { createContext, useContext, useMemo } from 'react';
 
 import { NAV_GEOMETRY } from './geometry';
 import type { NavGeometry } from './geometry';
-import type { HeaderConfig, SidebarConfig, SidebarItem } from './types';
+import { isLinkItem } from './sidebarItems';
+import type { HeaderConfig, SidebarConfig, SidebarLinkItem } from './types';
 
 export interface PrivateLayoutContextValue {
   sidebar: SidebarConfig | undefined;
@@ -19,7 +20,8 @@ export interface PrivateLayoutContextValue {
   pathname: string;
   isMobile: boolean;
   geometry: NavGeometry;
-  allItems: SidebarItem[];
+  /** The route rows; Settings launchers have no route and take no part in the active-route check. */
+  allItems: SidebarLinkItem[];
   isActive: (href: string) => boolean;
   homeHref: string;
   brandTitle: string;
@@ -60,7 +62,7 @@ export function PrivateLayoutProvider({
   ).toUpperCase();
 
   const allItems = useMemo(
-    () => sidebar?.groups.flatMap((g) => g.items) ?? [],
+    () => sidebar?.groups.flatMap((g) => g.items).filter(isLinkItem) ?? [],
     [sidebar?.groups],
   );
 

package/src/layouts/PrivateLayout/index.ts

@@ -4,11 +4,15 @@
 
 export { PrivateLayout } from './PrivateLayout';
 export { PrivateLayoutProvider, usePrivateLayoutContext } from './context';
+export { mcpSidebarItem, mcpSidebarGroup } from './mcpSidebar';
+export type { McpSidebarItemOptions, McpSidebarGroupOptions } from './mcpSidebar';
 export { SidebarBrandSwitcher, ForbiddenState } from './components';
 export type { ForbiddenStateProps } from './components';
 export type {
   PrivateLayoutProps,
   SidebarItem,
+  SidebarLinkItem,
+  SidebarSettingsItem,
   SidebarGroupConfig,
   SidebarConfig,
   HeaderConfig,

package/src/layouts/PrivateLayout/mcpSidebar.ts

@@ -0,0 +1,35 @@
+/**
+ * Ready sidebar entries for the MCP section (`mcpSettingsSection()` from `@djangocfg/widget-mcp`).
+ *
+ * They name the section by id only (`MCP_SECTION_ID`), so layouts holds no import of the widget. They render only
+ * while the host registered that section: add them to the config unconditionally.
+ */
+
+import type { LucideIcon } from 'lucide-react';
+
+import { MCP_SECTION_ID } from '../SettingsLayout/sectionIds';
+import type { SidebarGroupConfig, SidebarSettingsItem } from './types';
+
+export interface McpSidebarItemOptions {
+  /** The row's text. The host's to translate. */
+  label: string;
+  /** Lucide icon name or component. Default `"Cable"`. */
+  icon?: string | LucideIcon;
+}
+
+export interface McpSidebarGroupOptions extends Partial<McpSidebarItemOptions> {
+  /** The group's label, under the divider. Use `''` for a bare divider. */
+  label: string;
+  /** The row's text. Default `"MCP"` (a product name, not translated). */
+  itemLabel?: string;
+}
+
+/** A row that opens Settings on the MCP section; hidden while the section is not registered. */
+export function mcpSidebarItem({ label, icon = 'Cable' }: McpSidebarItemOptions): SidebarSettingsItem<typeof MCP_SECTION_ID> {
+  return { label, icon, settingsSection: MCP_SECTION_ID };
+}
+
+/** A separated group holding the MCP row; the whole group is hidden while the section is not registered. */
+export function mcpSidebarGroup({ label, itemLabel = 'MCP', icon }: McpSidebarGroupOptions): SidebarGroupConfig<typeof MCP_SECTION_ID> {
+  return { label, separated: true, items: [mcpSidebarItem({ label: itemLabel, icon })] };
+}

package/src/layouts/PrivateLayout/sidebarItems.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest';
+
+import { mcpSidebarGroup, mcpSidebarItem } from './mcpSidebar';
+import { isSidebarGroupVisible, sidebarItemKey, visibleSidebarItems } from './sidebarItems';
+import type { SidebarGroupConfig, SidebarItem } from './types';
+
+const link: SidebarItem = { label: 'Home', href: '/' };
+const mcp = mcpSidebarItem({ label: 'MCP' });
+const none: ReadonlySet<string> = new Set();
+const withMcp: ReadonlySet<string> = new Set(['account', 'mcp']);
+
+describe('visibleSidebarItems', () => {
+  it('keeps links whatever is registered', () => {
+    expect(visibleSidebarItems([link], none)).toEqual([link]);
+  });
+
+  it('drops a launcher for a section that is not registered (no dead door)', () => {
+    expect(visibleSidebarItems([link, mcp], none)).toEqual([link]);
+    expect(visibleSidebarItems([link, mcp], withMcp)).toEqual([link, mcp]);
+  });
+});
+
+describe('isSidebarGroupVisible', () => {
+  it('hides a group whose launchers are all unregistered, label and divider with it', () => {
+    const group = mcpSidebarGroup({ label: 'Connect' });
+    expect(isSidebarGroupVisible(group, none)).toBe(false);
+    expect(isSidebarGroupVisible(group, withMcp)).toBe(true);
+  });
+
+  it('keeps a mixed group while one row survives', () => {
+    const group: SidebarGroupConfig = { label: 'Tools', items: [link, mcp] };
+    expect(isSidebarGroupVisible(group, none)).toBe(true);
+  });
+
+  it('keeps the old rules for href-only groups', () => {
+    expect(isSidebarGroupVisible({ label: 'A', items: [link] }, none)).toBe(true);
+    expect(isSidebarGroupVisible({ label: 'A', items: [], dynamic: true }, none)).toBe(false);
+    expect(isSidebarGroupVisible({ label: 'A', items: [] }, none)).toBe(true);
+  });
+});
+
+describe('keys and the MCP defaults', () => {
+  it('keys a link by href and a launcher by section', () => {
+    expect(sidebarItemKey(link)).toBe('/');
+    expect(sidebarItemKey(mcp)).toBe('settings:mcp');
+  });
+
+  it('mcpSidebarItem defaults the icon to Cable and names the section by id only', () => {
+    expect(mcp).toEqual({ label: 'MCP', icon: 'Cable', settingsSection: 'mcp' });
+    expect(mcpSidebarItem({ label: 'X', icon: 'Plug' }).icon).toBe('Plug');
+  });
+
+  it('mcpSidebarGroup is a separated group with one MCP row', () => {
+    const group = mcpSidebarGroup({ label: 'Connect', itemLabel: 'Assistants' });
+    expect(group).toMatchObject({ label: 'Connect', separated: true });
+    expect(group.items).toEqual([{ label: 'Assistants', icon: 'Cable', settingsSection: 'mcp' }]);
+  });
+});

package/src/layouts/PrivateLayout/sidebarItems.ts

@@ -0,0 +1,38 @@
+/**
+ * Pure helpers over sidebar config: which rows are launchers, what is visible, a stable key.
+ * No React and no store, so the rules are tested without rendering.
+ */
+
+import type { SidebarGroupConfig, SidebarItem, SidebarLinkItem, SidebarSettingsItem } from './types';
+
+export function isSettingsItem<Id extends string>(item: SidebarItem<Id>): item is SidebarSettingsItem<Id> {
+  return typeof item.settingsSection === 'string';
+}
+
+export function isLinkItem(item: SidebarItem): item is SidebarLinkItem {
+  return typeof item.href === 'string';
+}
+
+/** Identity of a row for React keys and memo checks. */
+export function sidebarItemKey(item: SidebarItem): string {
+  return isSettingsItem(item) ? `settings:${item.settingsSection}` : (item as SidebarLinkItem).href;
+}
+
+/**
+ * The rows of a group that may render: links always, launchers only for a registered section (no dead door).
+ * `registered` is the id set the mounted SettingsDialog lists.
+ */
+export function visibleSidebarItems(items: SidebarItem[], registered: ReadonlySet<string>): SidebarItem[] {
+  return items.filter((item) => !isSettingsItem(item) || registered.has(item.settingsSection));
+}
+
+/**
+ * Whether a group renders at all. A `dynamic` group needs a row; any group that was given rows needs one of them to
+ * survive, so a "Connect" group whose only row is an unregistered section leaves no label and no divider behind.
+ * A group declared with no rows keeps its old behaviour (it renders, as a label).
+ */
+export function isSidebarGroupVisible(group: SidebarGroupConfig, registered: ReadonlySet<string>): boolean {
+  if (group.dynamic && group.items.length === 0) return false;
+  if (group.items.length === 0) return true;
+  return visibleSidebarItems(group.items, registered).length > 0;
+}

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/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}`;
+}