@djangocfg/layouts 2.1.601 → 2.1.603

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