@djangocfg/layouts 2.1.319 → 2.1.321

package/README.md

@@ -23,115 +23,68 @@ Peers: `@djangocfg/ui-core`, `@djangocfg/ui-nextjs`, React 19, Next.js 16+, Tail
 
 ---
 
-## BaseApp
+## Quick start
 
-Root provider (theme, auth, analytics, SWR, toasts). Use when you **don't** need route-based layout switching.
-
-```tsx
-<BaseApp
-  project="my-app"
-  theme={{ defaultTheme: 'system', storageKey: 'my-theme' }}
-  auth={{ apiUrl: process.env.NEXT_PUBLIC_API_URL }}
->
-  {children}
-</BaseApp>
-```
-
-| Prop | Role |
-|---|---|
-| `project` | Name for monitor / debug. Enables `window.monitor`. |
-| `theme` | `defaultTheme`, `storageKey`, and optional **`style`** (preset + CSS-var overrides). |
-| `auth`, `analytics`, `centrifugo`, `errorTracking`, `errorBoundary`, `swr`, `pwaInstall`, `monitor`, `debug` | Optional integrations. |
-
-### `theme.style`
-
-Mounts `ThemeStyleBridge` → injects `<style id="djangocfg-baseapp-theme-style">` with `--*` variables. Merge order: imported globals → preset → `vars` (strongest).
-
-| Piece | Meaning |
-|---|---|
-| `preset` | One of `THEME_STYLE_PRESET_ORDER`. Bundles live in `THEME_STYLE_PRESETS`. |
-| `vars.light` / `vars.dark` | Partial `ThemeCssVarMap` — HSL triplets (`192 90% 35%`); `radius` accepts any CSS length. |
-
-Presets: `default` · `django-cfg` · `ios` · `soft` · `dense` · `high-contrast`.
-
-Playground-only buckets (shadows, typography, spacing) are **not** injected — export full CSS from the Theme Configurator when you need them.
-
-Exports: `ThemeStyleConfig`, `ThemeCssVarKey`, `ThemeCssVarMap`, `ThemeStylePresetId`, `THEME_STYLE_PRESETS`, `THEME_STYLE_PRESET_ORDER`, `buildThemeStyleSheet`, `ThemeStyleBridge`.
-
----
-
-## AppLayout
-
-Wraps `BaseApp` and picks **admin → private → public** layout by path (`matchesPath` / `enabledPath`). `noLayoutPaths` skips the shell entirely (fullscreen / embeds). `publicChrome` merges navbar/footer/main spacing defaults.
+`AppLayout` wraps `BaseApp` (theme, auth, analytics, SWR, toasts) and routes the page to the right shell based on path:
 
 ```tsx
 <AppLayout
   layouts={{
-    public:  { component: PublicLayout,  enabledPath: ['/', '/legal', '/contact'] },
+    public:  { component: PublicLayout,  enabledPath: ['/', '/legal'] },
     private: { component: PrivateLayout, enabledPath: ['/dashboard'] },
     admin:   { component: AdminLayout,   enabledPath: '/admin' },
-    noLayoutPaths: ['/embed', '/ui'],
+    noLayoutPaths: ['/embed'],
   }}
   baseApp={{ project: 'my-app', theme: { defaultTheme: 'system' }, auth: { apiUrl: '…' } }}
-  i18n={{ locale, locales, onLocaleChange }}
+  i18n={{ locale, locales, onLocaleChange: changeLocale, routing }}
 >
   {children}
 </AppLayout>
 ```
 
-> **`i18n` is required** for correct path matching when using `next-intl` or any locale-prefixed routing. Without it the fallback regex can mis-strip 2-letter path segments (e.g. `/ui/*` treated as locale `ui`).
+Use `BaseApp` directly when you don't need route-based layout switching — see [AppLayout README](./src/layouts/AppLayout/README.md) for the matching rules, `noLayoutPaths`, `publicChrome`, and `i18n.routing` plumbing.
+
+> **Pass `i18n`** when using `next-intl` or any locale-prefixed routing. Without it, the path matcher can mis-strip 2-letter segments (e.g. `/ui/*` treated as locale `ui`).
 
 ---
 
 ## Layouts
 
-| Component | Use |
-|---|---|
-| **`PublicLayout`** | Marketing / docs. Slots for navbar + footer. All anchors render through `<Link>` from `@djangocfg/ui-core/components` — wrap with `LinkProvider` higher in the tree to inject a locale-aware Link (e.g. `next-intl`). All three navbars accept a `controls` block to show theme / locale switchers next to `UserMenu`; locale data flows from `LayoutI18nProvider` (mounted by `AppLayout` / `BaseApp` when you pass `i18n`). The locale switcher renders SVG country flags and matches the `UserMenu` avatar size at `size="icon"`. **[See PublicLayout README](./src/layouts/PublicLayout/README.md)** for full props, navbar variants (`FloatingNavbar` / `FlushNavbar` / `MinimalNavbar`), `DefaultFooter`, `NavAction`, `NavControls`, and hooks. |
-| **`PrivateLayout`** | App shell — sidebar + header. Defaults to the `boxed` visual (inset rounded card on a sidebar-coloured canvas); pass `visual={{ variant: 'full-bleed' }}` for the legacy edge-to-edge layout. |
-| **`AuthLayout`** | Sign-in flows. |
-| **`AdminLayout`** | Admin console. |
-| **`ProfileLayout`** | Profile page — avatar, editable fields, 2FA, tabs, slots (see below). |
+| Component | Use | Docs |
+|---|---|---|
+| **`PublicLayout`** | Marketing / docs. Slots for navbar (`Floating`/`Flush`/`Minimal`) + footer + locale + auth controls. | [README](./src/layouts/PublicLayout/README.md) |
+| **`PrivateLayout`** | Authenticated app shell — sidebar (collapsible icon rail, accordion groups, rail/featured/CTA slots) + popover account footer. | [README](./src/layouts/PrivateLayout/README.md) |
+| **`AuthLayout`** | Sign-in / sign-up flows. | [README](./src/layouts/AuthLayout/README.md) |
+| **`AdminLayout`** | Admin console. | — |
+| **`ProfileLayout`** | Profile page — see below. |  |
 
-### `PrivateLayout` visual variants
+### `ProfileLayout`
 
 ```tsx
-<PrivateLayout
-  sidebar={sidebar}
-  header={header}
-  visual={{ variant: 'boxed', inset: 12, radius: '2xl', border: true }}
->
-  {children}
-</PrivateLayout>
+<ProfileLayout enable2FA enableDeleteAccount tabs={tabs} slots={slots} />
 ```
 
-`boxed` (default) — `<SidebarInset>` becomes a rounded card; the wrapper paints `bg-sidebar` so the brand colour bleeds to the viewport edges. Mobile (<md) degrades to full-bleed automatically.
-`full-bleed` — content stretches edge-to-edge next to the sidebar (legacy look). Opt in with `visual={{ variant: 'full-bleed' }}`.
+| Prop | Role |
+|---|---|
+| `enable2FA` | Show Security tab with 2FA management. |
+| `enableDeleteAccount` | Show Delete account in `⋯` menu. |
+| `tabs` | Extra `ProfileTab[]` appended after built-ins. |
+| `slots.headerBadge` / `headerMenuItems` / `headerAfter` / `footer` | Slot content around the avatar row, menu, and tab body. |
 
-| Field | Type | Default | Notes |
-|---|---|---|---|
-| `variant` | `'full-bleed' \| 'boxed'` | `'boxed'` | Switch between the two shells. |
-| `inset` | `number \| { x?: number; y?: number }` | `12` | Gap (px) between the card and the viewport edges (md+). |
-| `radius` | `'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| '3xl'` | `'2xl'` | Card corner radius. |
-| `background` | `'sidebar' \| 'muted' \| 'card' \| 'background'` | `'sidebar'` | Canvas colour painted *behind* the boxed card. |
-| `border` | `boolean` | `true` | 1px border on the card. |
-| `maxWidth` | `'none' \| '7xl' \| 'screen-xl' \| 'screen-2xl'` | `'none'` | Optional inner content width cap. |
+---
 
-### `ProfileLayout`
+## Theme
 
-```tsx
-<ProfileLayout enable2FA enableDeleteAccount tabs={tabs} slots={slots} />
-```
+`baseApp.theme.style` injects `<style id="djangocfg-baseapp-theme-style">` with `--*` CSS variables. Merge order: imported globals → preset → `vars` (strongest).
 
-| Prop | Type | Role |
-|---|---|---|
-| `enable2FA` | `boolean` | Show Security tab with 2FA management. |
-| `enableDeleteAccount` | `boolean` | Show Delete account in `⋯` menu. |
-| `tabs` | `ProfileTab[]` | Extra tabs appended after built-in ones. |
-| `slots.headerBadge` | `ReactNode` | Next to user name (plan, role…). |
-| `slots.headerMenuItems` | `ReactNode` | Extra `DropdownMenuItem`s in `⋯` menu. |
-| `slots.headerAfter` | `ReactNode` | Below avatar row, above tabs. |
-| `slots.footer` | `ReactNode` | Below all tab content. |
+| Piece | Meaning |
+|---|---|
+| `preset` | `default` · `django-cfg` · `ios` · `soft` · `dense` · `high-contrast`. |
+| `vars.light` / `vars.dark` | Partial `ThemeCssVarMap` — HSL triplets (`192 90% 35%`); `radius` accepts any CSS length. |
+
+Playground-only buckets (shadows, typography, spacing) are **not** injected — export full CSS from the Theme Configurator when you need them.
+
+Exports: `ThemeStyleConfig`, `ThemeCssVarKey`, `ThemeCssVarMap`, `ThemeStylePresetId`, `THEME_STYLE_PRESETS`, `THEME_STYLE_PRESET_ORDER`, `buildThemeStyleSheet`, `ThemeStyleBridge`.
 
 ---
 
@@ -142,29 +95,16 @@ import { useLocaleSwitcher } from '@djangocfg/nextjs/i18n/client';
 import { routing } from '@djangocfg/nextjs/i18n/routing';
 
 const { locale, locales, changeLocale } = useLocaleSwitcher();
-<AppLayout i18n={{ locale, locales, onLocaleChange: changeLocale, routing }}>
-  {children}
-</AppLayout>
+<AppLayout i18n={{ locale, locales, onLocaleChange: changeLocale, routing }}>...</AppLayout>
 ```
 
-`i18n.routing` is the object returned by `defineRouting()` (`next-intl/routing`). When passed, `BaseApp` builds a locale-aware `Link` adapter from it and mounts a `LinkProvider`, so every `<Link>` rendered inside layouts (navbar, footer, drawer, …) keeps the active locale prefix on click. Drop it for default-locale-only apps — raw `next/link` works fine.
+When `routing` is set, `BaseApp` mounts a locale-aware `<Link>` adapter so every layout-rendered link keeps the active locale prefix. Drop it for default-locale-only apps.
 
 ---
 
 ## Monitor & debug
 
-`project` on `BaseApp` enables `window.monitor`. Debug panel: `Cmd+D` or `?debug=1`.
-
----
-
-## Utilities
-
-| API | Role |
-|---|---|
-| `useErrorEmitter`, `emitRuntimeError` | Error tracking hooks. |
-| `ErrorLayout` (`/components/errors`) | 404 / error pages. |
-| `RedirectPage` | Auth redirect helper. |
-| `PrivacyPage`, `TermsPage`, … (`/pages/legal`) | Legal templates. |
+`baseApp.project` enables `window.monitor`. Debug panel: `Cmd+D` or `?debug=1`.
 
 ---
 
@@ -174,13 +114,12 @@ const { locale, locales, changeLocale } = useLocaleSwitcher();
 |---|---|
 | `@djangocfg/layouts` | Barrel. |
 | `@djangocfg/layouts/layouts` | Layout components. |
-| `@djangocfg/layouts/components` | Misc. |
-| `@djangocfg/layouts/pages/legal` | Legal pages. |
+| `@djangocfg/layouts/components` | Misc + `ErrorLayout`, `RedirectPage`. |
+| `@djangocfg/layouts/pages/legal` | Legal page templates. |
+| `@djangocfg/layouts/configurator` | JSON Schemas for `<JsonSchemaForm>`-driven configurator UIs (PrivateLayout for now). Pair with `@djangocfg/ui-tools`. |
 | `@djangocfg/layouts/styles` | Base CSS. |
 
-## Extensions
-
-`@djangocfg/ext-newsletter`, `ext-knowbase`, `ext-leads`, `ext-payments`, `ext-support`, …
+Extensions: `@djangocfg/ext-newsletter`, `ext-knowbase`, `ext-leads`, `ext-payments`, `ext-support`, …
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/layouts",
-  "version": "2.1.319",
+  "version": "2.1.321",
   "description": "Simple, straightforward layout components for Next.js - import and use with props",
   "keywords": [
     "layouts",
@@ -60,6 +60,16 @@
       "import": "./src/pages/index.ts",
       "require": "./src/pages/index.ts"
     },
+    "./configurator": {
+      "types": "./src/configurator/index.ts",
+      "import": "./src/configurator/index.ts",
+      "require": "./src/configurator/index.ts"
+    },
+    "./configurator/private": {
+      "types": "./src/configurator/private/index.ts",
+      "import": "./src/configurator/private/index.ts",
+      "require": "./src/configurator/private/index.ts"
+    },
     "./styles": "./src/styles/index.css",
     "./styles/dashboard": "./src/styles/dashboard.css"
   },
@@ -74,14 +84,13 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/api": "^2.1.319",
-    "@djangocfg/centrifugo": "^2.1.319",
-    "@djangocfg/debuger": "^2.1.319",
-    "@djangocfg/i18n": "^2.1.319",
-    "@djangocfg/monitor": "^2.1.319",
-    "@djangocfg/ui-core": "^2.1.319",
-    "@djangocfg/ui-nextjs": "^2.1.319",
-    "@djangocfg/ui-tools": "^2.1.319",
+    "@djangocfg/api": "^2.1.321",
+    "@djangocfg/centrifugo": "^2.1.321",
+    "@djangocfg/debuger": "^2.1.321",
+    "@djangocfg/i18n": "^2.1.321",
+    "@djangocfg/monitor": "^2.1.321",
+    "@djangocfg/ui-core": "^2.1.321",
+    "@djangocfg/ui-nextjs": "^2.1.321",
     "@hookform/resolvers": "^5.2.2",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
@@ -111,15 +120,15 @@
     "uuid": "^11.1.0"
   },
   "devDependencies": {
-    "@djangocfg/api": "^2.1.319",
-    "@djangocfg/centrifugo": "^2.1.319",
-    "@djangocfg/debuger": "^2.1.319",
-    "@djangocfg/i18n": "^2.1.319",
-    "@djangocfg/monitor": "^2.1.319",
-    "@djangocfg/typescript-config": "^2.1.319",
-    "@djangocfg/ui-core": "^2.1.319",
-    "@djangocfg/ui-nextjs": "^2.1.319",
-    "@djangocfg/ui-tools": "^2.1.319",
+    "@djangocfg/api": "^2.1.321",
+    "@djangocfg/centrifugo": "^2.1.321",
+    "@djangocfg/debuger": "^2.1.321",
+    "@djangocfg/i18n": "^2.1.321",
+    "@djangocfg/monitor": "^2.1.321",
+    "@djangocfg/typescript-config": "^2.1.321",
+    "@djangocfg/ui-core": "^2.1.321",
+    "@djangocfg/ui-nextjs": "^2.1.321",
+    "@djangocfg/ui-tools": "^2.1.321",
     "@types/node": "^24.7.2",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",

package/src/configurator/index.ts

@@ -0,0 +1,14 @@
+/**
+ * JSON Schema descriptors for `<JsonSchemaForm>`-driven layout configurators.
+ *
+ * Drop a schema + uiSchema into `@djangocfg/ui-tools`'s `<JsonSchemaForm>` and
+ * you get a ready-made sidebar that edits the matching `<Layout>` props live.
+ *
+ * Public surface today:
+ *   - `private` — `PrivateLayout` configurator (shell + sidebar + header)
+ *
+ * Public + theme configurators are not exported yet — they currently live in
+ * the demo app while the schema shape is iterated on.
+ */
+
+export * from './private';

package/src/configurator/private/index.ts

@@ -0,0 +1,6 @@
+export {
+  privateLayoutConfiguratorSchema,
+  privateLayoutConfiguratorUiSchema,
+  defaultPrivateLayoutConfiguratorData,
+} from './schema';
+export type { PrivateLayoutConfiguratorData } from './schema';

package/src/configurator/private/schema.ts

@@ -0,0 +1,190 @@
+/**
+ * JSON Schema + uiSchema for a `PrivateLayout` configurator UI.
+ *
+ * The shape mirrors the real `PrivateLayout` runtime API:
+ *   - `shell.*`     → `visual` prop (`LayoutVisualConfig`)
+ *   - `sidebar.*`   → flags consumed by `SidebarConfig` (caller still maps these
+ *                     into a real `SidebarConfig` with concrete `groups`)
+ *   - `header.*`    → fields consumed by `HeaderConfig`
+ *
+ * Pair with `<JsonSchemaForm density="compact" schema={...} uiSchema={...}>`
+ * from `@djangocfg/ui-tools` to get a ready-made sidebar configurator. The
+ * `defaultPrivateLayoutConfiguratorData` is a safe initial value that already
+ * matches the schema (no nullable fields, no missing keys).
+ *
+ * Playground-only knobs (sample item count, banner toggles, etc.) live in the
+ * consuming app, not here — this stays a clean view of the real layout API.
+ */
+
+import type { CustomJsonSchema7, CustomJsonUiSchema7 } from '@djangocfg/ui-core/lib';
+
+/** Strongly-typed mirror of the schema — feed this back into PrivateLayout. */
+export interface PrivateLayoutConfiguratorData {
+  shell: {
+    variant: 'full-bleed' | 'boxed';
+    inset: number;
+    radius: 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl';
+    background: 'sidebar' | 'muted' | 'card' | 'background';
+    border: boolean;
+    maxWidth: 'none' | '7xl' | 'screen-xl' | 'screen-2xl';
+  };
+  sidebar: {
+    activeIndicator: 'background' | 'rail' | 'both';
+    groupLabelStyle: 'uppercase' | 'plain';
+    collapsibleGroups: boolean;
+    showFeatured: boolean;
+  };
+  header: {
+    userPlan: string;
+    showSecondaryAction: boolean;
+  };
+}
+
+export const privateLayoutConfiguratorSchema: CustomJsonSchema7 = {
+  type: 'object',
+  properties: {
+    shell: {
+      type: 'object',
+      title: 'Shell',
+      properties: {
+        variant: {
+          type: 'string',
+          title: 'Variant',
+          enum: ['full-bleed', 'boxed'],
+          description: '`boxed` paints a sidebar-coloured canvas around a rounded content card.',
+        },
+        inset: {
+          type: 'integer',
+          title: 'Inset (md+)',
+          minimum: 0,
+          maximum: 32,
+          description: 'Gap between the card and viewport edges.',
+        },
+        radius: {
+          type: 'string',
+          title: 'Radius',
+          enum: ['sm', 'md', 'lg', 'xl', '2xl', '3xl'],
+        },
+        background: {
+          type: 'string',
+          title: 'Canvas background',
+          enum: ['sidebar', 'muted', 'card', 'background'],
+          description: 'Colour painted behind the boxed card.',
+        },
+        border: {
+          type: 'boolean',
+          title: 'Border on card',
+          description: '1px hairline border around the boxed card.',
+        },
+        maxWidth: {
+          type: 'string',
+          title: 'Inner max-width',
+          enum: ['none', '7xl', 'screen-xl', 'screen-2xl'],
+        },
+      },
+    },
+    sidebar: {
+      type: 'object',
+      title: 'Sidebar',
+      properties: {
+        activeIndicator: {
+          type: 'string',
+          title: 'Active indicator',
+          enum: ['background', 'rail', 'both'],
+          description: 'Visual treatment for the active nav item.',
+        },
+        groupLabelStyle: {
+          type: 'string',
+          title: 'Group label style',
+          enum: ['uppercase', 'plain'],
+          description: 'Collapsible groups always render `plain` regardless of this setting.',
+        },
+        collapsibleGroups: {
+          type: 'boolean',
+          title: 'Collapsible groups',
+          description: 'Mailersend-style accordion: label becomes a clickable trigger.',
+        },
+        showFeatured: {
+          type: 'boolean',
+          title: 'Featured CTA tile',
+          description: 'Accent-tinted tile rendered below groups.',
+        },
+      },
+    },
+    header: {
+      type: 'object',
+      title: 'Header / account footer',
+      properties: {
+        userPlan: {
+          type: 'string',
+          title: 'User plan',
+          enum: ['', 'Free plan', 'Pro plan', 'Max plan', 'Enterprise'],
+          description: 'Subtitle under the display name in the footer trigger. Empty hides it.',
+        },
+        showSecondaryAction: {
+          type: 'boolean',
+          title: 'Footer secondary action',
+          description: 'Adds a download-style icon button inside the footer trigger with a pulsing accent dot.',
+        },
+      },
+    },
+  },
+};
+
+export const privateLayoutConfiguratorUiSchema: CustomJsonUiSchema7 = {
+  shell: {
+    'ui:collapsible': true,
+    inset: {
+      'ui:widget': 'slider',
+      'ui:options': { unit: 'px', step: 2, showInput: false },
+      'ui:disabledWhen': { path: 'shell.variant', notEq: 'boxed' },
+    },
+    radius: {
+      'ui:disabledWhen': { path: 'shell.variant', notEq: 'boxed' },
+    },
+    background: {
+      'ui:disabledWhen': { path: 'shell.variant', notEq: 'boxed' },
+    },
+    border: {
+      'ui:widget': 'switch',
+      'ui:disabledWhen': { path: 'shell.variant', notEq: 'boxed' },
+    },
+  },
+  sidebar: {
+    'ui:collapsible': true,
+    'ui:groups': [
+      {
+        title: 'Visual',
+        fields: ['activeIndicator', 'groupLabelStyle', 'collapsibleGroups', 'showFeatured'],
+        defaultOpen: true,
+      },
+    ],
+    collapsibleGroups: { 'ui:widget': 'switch' },
+    showFeatured: { 'ui:widget': 'switch' },
+  },
+  header: {
+    'ui:collapsible': true,
+    showSecondaryAction: { 'ui:widget': 'switch' },
+  },
+};
+
+export const defaultPrivateLayoutConfiguratorData: PrivateLayoutConfiguratorData = {
+  shell: {
+    variant: 'boxed',
+    inset: 12,
+    radius: '2xl',
+    background: 'sidebar',
+    border: true,
+    maxWidth: 'none',
+  },
+  sidebar: {
+    activeIndicator: 'background',
+    groupLabelStyle: 'uppercase',
+    collapsibleGroups: false,
+    showFeatured: false,
+  },
+  header: {
+    userPlan: 'Pro plan',
+    showSecondaryAction: false,
+  },
+};

package/src/layouts/PrivateLayout/PrivateLayout.tsx

@@ -13,7 +13,7 @@ import { useRouter } from 'next/navigation';
 
 import { useAuth } from '@djangocfg/api/auth';
 import { Preloader } from '@djangocfg/ui-core/components';
-import { SidebarInset, SidebarProvider } from '@djangocfg/ui-nextjs/components';
+import { SidebarInset, SidebarProvider } from '@djangocfg/ui-core/components';
 
 import type { AppLayoutPublicChrome } from '../AppLayout/AppLayout';
 import type { LayoutVisualConfig } from '../types';
@@ -27,6 +27,8 @@ export interface SidebarItem {
   href: string;
   icon?: string | LucideIconType;
   badge?: string | number;
+  /** Visual style of `badge`: `'count'` (default, neutral pill) or `'pill'` (accent-tinted, e.g. "lite"/"new"). */
+  badgeVariant?: 'count' | 'pill';
   /** Collapsed rail: shown in tooltip; defaults to `label`. */
   tooltip?: string;
 }
@@ -38,6 +40,32 @@ export interface SidebarGroupConfig {
   items: SidebarItem[];
   /** 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. */
+  collapsible?: boolean;
+  /** Initial open state for collapsible groups. Auto-expanded if any child is active. Default `false`. */
+  defaultOpen?: boolean;
+  /** Icon for the group trigger (only when `collapsible`). */
+  icon?: string | LucideIconType;
+  /**
+   * Hide per-item icons inside the group. Defaults to `true` when `collapsible`,
+   * `false` otherwise (Mailersend convention: icons live on the trigger, not on children).
+   */
+  hideItemIcons?: boolean;
+}
+
+/** Active-state visual treatment for sidebar nav items. */
+export type SidebarActiveIndicator = 'background' | 'rail' | 'both';
+
+/** Rendering of group labels. `'uppercase'` is the legacy ultra-light caps; `'plain'` is sm bold. */
+export type SidebarGroupLabelStyle = 'uppercase' | 'plain';
+
+/** Featured CTA tile rendered below groups. */
+export interface SidebarFeaturedConfig {
+  icon?: string | LucideIconType;
+  label: string;
+  href: string;
+  badge?: string;
+  accent?: 'green' | 'blue' | 'amber' | 'primary';
 }
 
 export interface SidebarConfig {
@@ -65,6 +93,12 @@ export interface SidebarConfig {
   menuEndShowOnCollapsed?: boolean;
   /** Custom footer component rendered at the bottom of the sidebar */
   footer?: ReactNode;
+  /** Active-state visual on nav items. Default `'background'` (legacy). */
+  activeIndicator?: SidebarActiveIndicator;
+  /** Style of group labels. Default `'uppercase'` (legacy). Collapsible groups always use `plain`. */
+  groupLabelStyle?: SidebarGroupLabelStyle;
+  /** Featured CTA tile rendered below all groups, above `menuEnd`. */
+  featured?: SidebarFeaturedConfig;
 }
 
 export interface HeaderConfig {
@@ -86,6 +120,17 @@ export interface HeaderConfig {
   groups?: UserMenuConfig['groups'];
   /** Auth page path (for sign in button) */
   authPath?: string;
+  /** Subtitle under the display name in the sidebar footer (e.g. "Max plan"). */
+  userPlan?: string;
+  /** Optional secondary action button rendered inside the footer trigger (e.g. Get apps download button). */
+  footerSecondaryAction?: {
+    icon: string | LucideIconType;
+    href?: string;
+    onClick?: () => void;
+    ariaLabel: string;
+    /** Show pulsing accent dot on the action (Claude-style "new"). */
+    pulse?: boolean;
+  };
 }
 
 export interface PrivateLayoutProps {