@djangocfg/layouts 2.1.595 → 2.1.596

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/layouts",
-  "version": "2.1.595",
+  "version": "2.1.596",
   "description": "Simple, straightforward layout components for Next.js - import and use with props",
   "keywords": [
     "layouts",
@@ -87,14 +87,15 @@
   ],
   "scripts": {
     "lint": "eslint .",
-    "check": "tsc --noEmit"
+    "check": "tsc --noEmit",
+    "test": "vitest run"
   },
   "peerDependencies": {
-    "@djangocfg/analytics": "^2.1.595",
-    "@djangocfg/api": "^2.1.595",
-    "@djangocfg/devtools": "^2.1.595",
-    "@djangocfg/i18n": "^2.1.595",
-    "@djangocfg/ui-core": "^2.1.595",
+    "@djangocfg/analytics": "^2.1.596",
+    "@djangocfg/api": "^2.1.596",
+    "@djangocfg/devtools": "^2.1.596",
+    "@djangocfg/i18n": "^2.1.596",
+    "@djangocfg/ui-core": "^2.1.596",
     "@hookform/resolvers": "^5.2.2",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
@@ -124,12 +125,12 @@
     "uuid": "^11.1.1"
   },
   "devDependencies": {
-    "@djangocfg/analytics": "^2.1.595",
-    "@djangocfg/api": "^2.1.595",
-    "@djangocfg/devtools": "^2.1.595",
-    "@djangocfg/i18n": "^2.1.595",
-    "@djangocfg/typescript-config": "^2.1.595",
-    "@djangocfg/ui-core": "^2.1.595",
+    "@djangocfg/analytics": "^2.1.596",
+    "@djangocfg/api": "^2.1.596",
+    "@djangocfg/devtools": "^2.1.596",
+    "@djangocfg/i18n": "^2.1.596",
+    "@djangocfg/typescript-config": "^2.1.596",
+    "@djangocfg/ui-core": "^2.1.596",
     "@storybook/react-vite": "^10.5.0",
     "@types/node": "^25.9.5",
     "@types/react": "19.2.15",
@@ -138,6 +139,7 @@
     "next-intl": "^4.13.2",
     "storybook": "^10.5.0",
     "typescript": "^5.9.3",
+    "vitest": "^4.1.10",
     "zustand": "^5.0.14"
   },
   "publishConfig": {

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

@@ -11,27 +11,23 @@
 
 'use client';
 
-import { ChevronDown, Languages } from 'lucide-react';
+import { ChevronDown } from 'lucide-react';
 import { Link } from '@djangocfg/ui-core/components';
 import React, { memo } from 'react';
 
 import { useAuth } from '@djangocfg/api/auth';
-import { useAppT } from '@djangocfg/i18n';
 import {
   Avatar,
   AvatarFallback,
   AvatarImage,
   Button,
-  LanguageFlag,
   MenuBuilder,
 } from '@djangocfg/ui-core/components';
 import type { MenuItem } from '@djangocfg/ui-core/components';
 import { cn, isDev } from '@djangocfg/ui-core/lib';
 import { useSidebar } from '@djangocfg/ui-core/components';
 
-import { useLayoutI18nOptional } from '../../../shared/LayoutI18nProvider';
 import { LucideIcon as LucideIconRender } from '../../../components';
-import { getLocaleMeta } from '../../_components/locale-switcher/localeMeta';
 import { usePeekPin } from '../hooks';
 import { usePrivateLayoutContext } from '../context';
 import { useAccountMenuItems } from '../../SettingsLayout/hooks';
@@ -52,8 +48,6 @@ interface AccountView {
 
 function PrivateSidebarAccountRaw({ header }: PrivateSidebarAccountProps) {
   const { user } = useAuth();
-  const t = useAppT();
-  const layoutI18n = useLayoutI18nOptional();
   const { setOpen: setSidebarOpen } = useSidebar();
   const { isMobile } = usePrivateLayoutContext();
   const [isAccountMenuOpen, setIsAccountMenuOpen] = React.useState(false);
@@ -95,34 +89,9 @@ function PrivateSidebarAccountRaw({ header }: PrivateSidebarAccountProps) {
 
   const headerLabelText = account.email ?? (account.source === 'dev-fallback' ? 'No active session' : null);
 
-  // Language submenu and the app's account links sit between the shared Settings shortcuts and Sign out.
+  // The app's account links sit between the shared Settings shortcuts and Sign out.
   const extraItems = React.useMemo<MenuItem[]>(() => {
     const items: MenuItem[] = [];
-    if (layoutI18n && layoutI18n.locales.length > 1) {
-      items.push({
-        kind: 'submenu',
-        id: 'language',
-        label: t('layouts.profile.language') || 'Language',
-        icon: Languages,
-        items: [
-          {
-            kind: 'radio-group',
-            id: 'locale',
-            value: layoutI18n.locale,
-            onValueChange: layoutI18n.onLocaleChange,
-            options: layoutI18n.locales.map((code) => {
-              const meta = getLocaleMeta(code);
-              return {
-                id: code,
-                value: code,
-                label: meta.native,
-                icon: <LanguageFlag code={code} rounded className="h-3 w-4 shrink-0" />,
-              };
-            }),
-          },
-        ],
-      });
-    }
     if (accountLinks.length > 0) {
       items.push({ kind: 'separator', id: 'sep-links' });
       for (const link of accountLinks) {
@@ -130,7 +99,7 @@ function PrivateSidebarAccountRaw({ header }: PrivateSidebarAccountProps) {
       }
     }
     return items;
-  }, [t, layoutI18n, accountLinks]);
+  }, [accountLinks]);
 
   // Shared with every host: email, Settings, section shortcuts, Sign out (logout confirm opens over a CLOSED menu).
   const menuItems = useAccountMenuItems({ extra: extraItems, label: headerLabelText });

package/src/layouts/SettingsLayout/README.md

@@ -79,6 +79,7 @@ the URL hash:
 | -------------------- | --------------------------------------- |
 | `#settings`          | open, first / last-active section       |
 | `#settings/usage`    | open, **usage** section active          |
+| `#settings/mcp?request=…` | open on **mcp** with a one-shot intent: a section reads it with `useSettingsIntent('mcp')`; the query is stripped from the address after it is read, and a closed dialog drops it |
 | no / other hash      | closed                                  |
 
 - **Deep-link / refresh** reopens on the same section.

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

@@ -5,6 +5,7 @@ import React from 'react';
 import { ScrollArea } from '@djangocfg/ui-core/components';
 
 import { useSettingsContext } from '../context';
+import { useSettingsIntent } from '../intent/useSettingsIntent';
 
 /**
  * Right side: the active section's detail in an independently scrolling body.
@@ -16,6 +17,7 @@ import { useSettingsContext } from '../context';
  */
 export const SettingsPanel: React.FC = () => {
   const { active } = useSettingsContext();
+  const intent = useSettingsIntent(active?.id ?? '');
 
   if (!active) {
     return (
@@ -35,7 +37,7 @@ export const SettingsPanel: React.FC = () => {
         {/* key forces a fresh subtree per section: resets scroll + transient
             form state when switching, which is the expected settings UX. */}
         <div key={active.id} className="px-6 py-5 md:px-8 md:py-6">
-          {active.content}
+          {typeof active.content === 'function' ? active.content({ intent }) : active.content}
         </div>
       </ScrollArea>
     </div>

package/src/layouts/SettingsLayout/hooks/{useAccountMenuItems.ts → useAccountMenuItems.tsx}

@@ -1,13 +1,16 @@
 'use client';
 
-import { LogOut, Settings as SettingsIcon } from 'lucide-react';
+import { Languages, LogOut, Settings as SettingsIcon } from 'lucide-react';
 import { useMemo } from 'react';
 
 import { useAuth } from '@djangocfg/api/auth';
 import { useAppT } from '@djangocfg/i18n';
+import { LanguageFlag } from '@djangocfg/ui-core/components';
 import type { MenuItem } from '@djangocfg/ui-core/components';
 
 import { useLogout } from '../../../hooks';
+import { useLayoutI18nOptional } from '../../../shared/LayoutI18nProvider';
+import { getLocaleMeta } from '../../_components/locale-switcher/localeMeta';
 import { useSettingsDialogStore } from '../store';
 
 const SETTINGS_SHORTCUT = '⇧⌘,';
@@ -17,21 +20,25 @@ export interface UseAccountMenuItemsOptions {
   extra?: MenuItem[];
   /** Label above the items; defaults to the signed-in user's email. */
   label?: string | null;
+  /** Language submenu, shown when the layout i18n context offers more than one locale. @default true */
+  language?: boolean;
 }
 
 /**
  * The user menu every host shares: email, one row per Settings section (built-in and the host's, as in the dialog's sidebar),
- * then Sign out. Feed it to `MenuBuilder` with any trigger, so a site's own chrome gets the same menu as
+ * a Language submenu when the layout offers more than one locale, then Sign out. Feed it to `MenuBuilder` with any trigger, so a site's own chrome gets the same menu as
  * `PrivateLayout`'s sidebar footer instead of a hand-rolled copy.
  */
-export function useAccountMenuItems({ extra, label }: UseAccountMenuItemsOptions = {}): MenuItem[] {
+export function useAccountMenuItems({ extra, label, language = true }: UseAccountMenuItemsOptions = {}): MenuItem[] {
   const { user } = useAuth();
   const t = useAppT();
   const handleLogout = useLogout();
+  const layoutI18n = useLayoutI18nOptional();
   const sections = useSettingsDialogStore((s) => s.sections);
   const headerLabel = label === undefined ? (user?.email ?? null) : label;
   const signOutLabel = t('layouts.profile.signOut');
   const settingsLabel = t('layouts.profile.settings') || 'Settings';
+  const languageLabel = t('layouts.profile.language') || 'Language';
 
   return useMemo<MenuItem[]>(() => {
     const items: MenuItem[] = [];
@@ -60,6 +67,29 @@ export function useAccountMenuItems({ extra, label }: UseAccountMenuItemsOptions
       });
     });
 
+    if (language && layoutI18n && layoutI18n.locales.length > 1) {
+      items.push({
+        kind: 'submenu',
+        id: 'language',
+        label: languageLabel,
+        icon: Languages,
+        items: [
+          {
+            kind: 'radio-group',
+            id: 'locale',
+            value: layoutI18n.locale,
+            onValueChange: layoutI18n.onLocaleChange,
+            options: layoutI18n.locales.map((code) => ({
+              id: code,
+              value: code,
+              label: getLocaleMeta(code).native,
+              icon: <LanguageFlag code={code} rounded className="h-3 w-4 shrink-0" />,
+            })),
+          },
+        ],
+      });
+    }
+
     if (extra?.length) items.push(...extra);
 
     items.push({ kind: 'separator', id: 'sep-logout' });
@@ -72,5 +102,5 @@ export function useAccountMenuItems({ extra, label }: UseAccountMenuItemsOptions
       onSelect: () => handleLogout(),
     });
     return items;
-  }, [headerLabel, settingsLabel, sections, extra, signOutLabel, handleLogout]);
+  }, [headerLabel, settingsLabel, languageLabel, language, layoutI18n, sections, extra, signOutLabel, handleLogout]);
 }

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

@@ -7,6 +7,7 @@
  * configurable (`urlKey`). Examples:
  *   #settings            → open, first/last-active section
  *   #settings/usage      → open, "usage" section active
+ *   #settings/mcp?request=… → open on "mcp" with a one-shot intent (see `useSettingsIntent`); the query is stripped
  *   (no/other hash)      → closed
  *
  * Direction of truth:
@@ -26,6 +27,7 @@ import { useEffect, useRef } from 'react';
 
 import { useHashState } from '@djangocfg/ui-core/hooks';
 
+import { buildSettingsHash as buildHash, parseSettingsHash as parseHash } from '../intent/parseSettingsHash';
 import { useSettingsDialogStore } from '../store';
 
 export interface UseSettingsUrlOptions {
@@ -41,30 +43,6 @@ export interface UseSettingsUrlOptions {
   resolveSection?: (id: string | null) => string | null;
 }
 
-interface ParsedHash {
-  open: boolean;
-  section: string | null;
-}
-
-/**
- * Parse a bare fragment (no leading '#', as `useHashState` yields):
- * `"settings/usage"` → { open: true, section: 'usage' }.
- */
-function parseHash(fragment: string, urlKey: string): ParsedHash {
-  if (!fragment) return { open: false, section: null };
-
-  const [key, ...rest] = fragment.split('/');
-  if (key !== urlKey) return { open: false, section: null };
-
-  const section = rest.join('/') || null;
-  return { open: true, section };
-}
-
-/** Build the bare fragment `"settings/usage"` (or `"settings"` when no section). */
-function buildHash(urlKey: string, section: string | null): string {
-  return section ? `${urlKey}/${section}` : urlKey;
-}
-
 export function useSettingsUrl(options: UseSettingsUrlOptions = {}): void {
   const { urlKey = 'settings', enabled = true, resolveSection } = options;
 
@@ -75,6 +53,7 @@ export function useSettingsUrl(options: UseSettingsUrlOptions = {}): void {
   const activeSection = useSettingsDialogStore((s) => s.activeSection);
   const open = useSettingsDialogStore((s) => s.open);
   const close = useSettingsDialogStore((s) => s.close);
+  const setIntent = useSettingsDialogStore((s) => s.setIntent);
 
   // Guard against the URL→store and store→URL effects fighting each other:
   // when we write the fragment ourselves we tag the value we wrote and skip the
@@ -100,6 +79,13 @@ export function useSettingsUrl(options: UseSettingsUrlOptions = {}): void {
       // open() preserves the current section when called without one, so only
       // pass a section when the URL actually named a (valid) one.
       open(resolved ?? undefined);
+      if (Object.keys(parsed.params).length > 0) {
+        // A one-shot intent: hand it to the section, then strip the query so it is not shared, bookmarked or replayed.
+        setIntent({ section: resolved, params: parsed.params });
+        const stripped = buildHash(urlKey, resolved);
+        selfWrittenFragment.current = stripped;
+        setFragment(stripped, { replace: true });
+      }
     } else if (isOpen) {
       // Hash no longer points at us (back button, manual edit) → close.
       close();

package/src/layouts/SettingsLayout/index.ts

@@ -29,6 +29,8 @@ export type { AccountMenuButtonProps } from './components/AccountMenuButton';
 
 // Store + public hooks
 export { useSettingsDialogStore } from './store';
+export { useSettingsIntent } from './intent/useSettingsIntent';
+export type { SettingsIntent } from './intent/useSettingsIntent';
 export {
   useSettingsDialog,
   useSettingsUrl,
@@ -61,6 +63,7 @@ export {
 // Types
 export type {
   SettingsSection,
+  SettingsSectionContext,
   SettingsGroup,
   SettingsBuiltins,
   SettingsContent,

package/src/layouts/SettingsLayout/intent/parseSettingsHash.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest';
+
+import { buildSettingsHash, parseSettingsHash } from './parseSettingsHash';
+
+describe('parseSettingsHash', () => {
+  it('is closed for an empty or foreign fragment', () => {
+    expect(parseSettingsHash('', 'settings').open).toBe(false);
+    expect(parseSettingsHash('profile/mcp', 'settings').open).toBe(false);
+  });
+
+  it('opens on the bare key with no section', () => {
+    expect(parseSettingsHash('settings', 'settings')).toEqual({ open: true, section: null, params: {} });
+  });
+
+  it('reads the section before the query, not the query as part of it', () => {
+    expect(parseSettingsHash('settings/mcp?request=abc&client=Claude', 'settings')).toEqual({
+      open: true,
+      section: 'mcp',
+      params: { request: 'abc', client: 'Claude' },
+    });
+  });
+
+  it('decodes values and keeps a section-less query', () => {
+    expect(parseSettingsHash('settings?request=a%2Bb', 'settings').params).toEqual({ request: 'a+b' });
+  });
+
+  it('drops an over-long value and caps the number of params', () => {
+    const long = 'x'.repeat(5000);
+    expect(parseSettingsHash(`settings/mcp?request=${long}&ok=1`, 'settings').params).toEqual({ ok: '1' });
+    const many = Array.from({ length: 20 }, (_, i) => `p${i}=1`).join('&');
+    expect(Object.keys(parseSettingsHash(`settings/mcp?${many}`, 'settings').params)).toHaveLength(8);
+  });
+});
+
+describe('buildSettingsHash', () => {
+  it('never carries params', () => {
+    expect(buildSettingsHash('settings', 'mcp')).toBe('settings/mcp');
+    expect(buildSettingsHash('settings', null)).toBe('settings');
+  });
+});

package/src/layouts/SettingsLayout/intent/parseSettingsHash.ts

@@ -0,0 +1,44 @@
+/**
+ * The fragment grammar of the Settings dialog: `settings/<section>?<params>`.
+ *
+ * The query is a one-shot arrival intent (an assistant's consent request, a pre-filled form). It rides in the
+ * fragment so it never reaches a server log, a CDN log or a `Referer`; the dialog reads it once and strips it.
+ */
+
+/** Hard caps: the fragment is attacker-reachable input, and the store keeps what it parses. */
+const MAX_PARAMS = 8;
+const MAX_VALUE_LENGTH = 4096;
+
+export interface ParsedSettingsHash {
+  open: boolean;
+  section: string | null;
+  /** Flat and length-capped; empty when the fragment carried no query. */
+  params: Record<string, string>;
+}
+
+const CLOSED: ParsedSettingsHash = { open: false, section: null, params: {} };
+
+/** Parse a bare fragment (no leading '#'): `"settings/mcp?request=abc"` → `{ open, section: 'mcp', params: { request: 'abc' } }`. */
+export function parseSettingsHash(fragment: string, urlKey: string): ParsedSettingsHash {
+  if (!fragment) return CLOSED;
+
+  const queryAt = fragment.indexOf('?');
+  const path = queryAt === -1 ? fragment : fragment.slice(0, queryAt);
+  const query = queryAt === -1 ? '' : fragment.slice(queryAt + 1);
+
+  const [key, ...rest] = path.split('/');
+  if (key !== urlKey) return CLOSED;
+
+  const params: Record<string, string> = {};
+  for (const [name, value] of new URLSearchParams(query)) {
+    if (Object.keys(params).length >= MAX_PARAMS) break;
+    if (value.length > MAX_VALUE_LENGTH) continue;
+    params[name] = value;
+  }
+  return { open: true, section: rest.join('/') || null, params };
+}
+
+/** Build the bare fragment `"settings/usage"` (or `"settings"` when no section). Never carries params: an intent is not written back. */
+export function buildSettingsHash(urlKey: string, section: string | null): string {
+  return section ? `${urlKey}/${section}` : urlKey;
+}

package/src/layouts/SettingsLayout/intent/useSettingsIntent.ts

@@ -0,0 +1,23 @@
+'use client';
+
+import { useCallback } from 'react';
+
+import { useSettingsDialogStore } from '../store';
+
+export interface SettingsIntent {
+  /** The section the link named, when it named a known one. */
+  section: string | null;
+  params: Record<string, string>;
+}
+
+/**
+ * What the address asked of this section (`#settings/<section>?…`), or null when it asked nothing. The dialog sets it
+ * once from the fragment and strips the query; it stays until the section calls `clear` or the dialog closes, so a
+ * section that mounts a moment later still sees it.
+ */
+export function useSettingsIntent(sectionId: string): { params: Record<string, string>; clear: () => void } | null {
+  const intent = useSettingsDialogStore((s) => s.intent);
+  const clearIntent = useSettingsDialogStore((s) => s.clearIntent);
+  const clear = useCallback(() => clearIntent(), [clearIntent]);
+  return intent && intent.section === sectionId ? { params: intent.params, clear } : null;
+}

package/src/layouts/SettingsLayout/store.ts

@@ -15,6 +15,8 @@
 
 import { create } from 'zustand';
 
+import type { SettingsIntent } from './intent/useSettingsIntent';
+
 /** What a menu needs to link to a section; the dialog registers these (host sections are only known to it). */
 export interface SettingsMenuSection {
   id: string;
@@ -41,6 +43,10 @@ interface SettingsDialogState {
   toggle: () => void;
   /** Switch the active section (no-op on open state). */
   setSection: (sectionId: string) => void;
+  /** One-shot parameters from the address (`#settings/<section>?…`), read by the section they name. */
+  intent: SettingsIntent | null;
+  setIntent: (intent: SettingsIntent) => void;
+  clearIntent: () => void;
 }
 
 /**
@@ -71,7 +77,11 @@ export const useSettingsDialogStore = create<SettingsDialogState>((set, get) =>
       isOpen: true,
       activeSection: sectionId ?? state.activeSection,
     })),
-  close: () => set({ isOpen: false }),
+  /* Closing drops an unanswered intent: reopening later must not replay a stale request. */
+  close: () => set({ isOpen: false, intent: null }),
   toggle: () => set((state) => ({ isOpen: !state.isOpen })),
   setSection: (sectionId) => set({ activeSection: sectionId }),
+  intent: null,
+  setIntent: (intent) => set({ intent }),
+  clearIntent: () => set({ intent: null }),
 }));

package/src/layouts/SettingsLayout/types.ts

@@ -23,6 +23,12 @@ export interface SettingsGroup {
   order?: number;
 }
 
+/** What a function `content` receives. */
+export interface SettingsSectionContext {
+  /** The one-shot intent for this section, or null; `clear` consumes it. */
+  intent: { params: Record<string, string>; clear: () => void } | null;
+}
+
 /**
  * One settings section = one nav entry + one detail panel.
  *
@@ -42,8 +48,11 @@ export interface SettingsSection {
   title?: React.ReactNode;
   /** Sub-heading under the panel title. */
   description?: React.ReactNode;
-  /** The panel body. Rendered only while this section is active (Radix unmounts closed dialogs). */
-  content: React.ReactNode;
+  /**
+   * The panel body. Rendered only while this section is active (Radix unmounts closed dialogs). A function receives what the
+   * address asked of this section (`#settings/<id>?…`, see `useSettingsIntent`), so a package can react to it without importing layouts.
+   */
+  content: React.ReactNode | ((context: SettingsSectionContext) => React.ReactNode);
   /** Extra terms the search box matches against, beyond the label. */
   keywords?: string[];
   /** Sort order within the group (ascending). Defaults to declaration order. */