@owlmeans/web-panel 0.1.18-rc.11 → 0.1.18-rc.13

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/web-panel",
-  "version": "0.1.18-rc.10",
-  "generatedAt": "2026-08-25T09:54:15.288Z",
+  "version": "0.1.18-rc.13",
+  "generatedAt": "2026-08-25T21:16:30.725Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/web-panel/SKILL.md

@@ -8,7 +8,7 @@ user-invocable: false
 # @owlmeans/web-panel
 
 **Layer:** Web (React)
-**Install:** `"@owlmeans/web-panel": "^0.1.18-rc.10"` in `dependencies`
+**Install:** `"@owlmeans/web-panel": "^0.1.18-rc.13"` in `dependencies`
 
 ## Key Exports
 
@@ -83,11 +83,48 @@ header. Both render the same items; only one is visible at a time.
 
 | Component | Props |
 |---|---|
-| `NavLayout` | `nav: PanelNavConfig`, `translate?`, `title?: ReactNode`, `home?: string` (brand target — defaults to the first section's first item), `actions?: ReactNode`, `footer?: PanelNavLink[] \| ReactNode`, `contentClassName?`, `className?`, `style?` |
+| `NavLayout` | `nav: PanelNavConfig`, `translate?`, `title?: ReactNode`, `home?: string` (brand target — defaults to the first section's first item), `actions?: ReactNode`, `footer?: PanelNavLink[] \| ReactNode`, `headerClassName?`, `contentClassName?`, `containerClassName?`, `className?`, `style?` |
 | `TopNav` | `config: PanelNavConfig`, `translate?`, `ariaLabel?`, `className?`, `style?` |
 | `SideNav` | the same, plus `variant?: 'side' \| 'bar'` |
 | `Footer` | `links?: PanelNavLink[]`, `translate?`, `children?`, `className?`, `style?` |
 
+**The style slots are REGIONS, and each region is its own SURFACE.** `className` is the root —
+the full-height page *behind* the header, side menu and footer. `headerClassName` is the sticky
+top bar. `contentClassName` is the content area. `containerClassName` is width and padding for
+all three at once, never colour.
+
+The header paints an opaque background of its own, because it is sticky and content scrolls
+beneath it. That makes it a **different surface from the root**, so it states `text-foreground`
+alongside its `bg-background` — not as decoration, and not redundantly. A root carrying a
+contrasting pair (`className="bg-primary text-primary-foreground"`, an ordinary dark shell)
+otherwise inherits its near-white foreground into a near-white bar, and every header child that
+states no colour of its own — the brand, a ghost-variant action button — is painted in the
+foreground of a surface it is not on. It type-checks, it builds, it renders, and the menu is
+invisible. Pinned by `tests/nav.spec.ts` → "the header is its own surface", which measures
+rendered lightness rather than class names; the harness root carries a dark shell permanently so
+every navigation test runs against that case.
+
+**Every style slot is MERGED over its default — none of them substitutes.** `className`,
+`headerClassName`, `contentClassName` and `containerClassName` all go through `cn`, so a caller
+names only the utility it wants to move and tailwind-merge drops just the one it conflicts with.
+This matters most for `containerClassName`, whose default is a four-part rhythm
+(`mx-auto w-full max-w-6xl px-4`): a design asking for a wider page writes `max-w-[1280px]` and
+means *wider*, not *unpadded and uncentred*. Substituting there took `px-4` and `mx-auto` down
+with the width and left the header, content and footer all flush to the window edge. Pinned by
+`nav.spec.ts` → "a width-only rhythm override keeps the side padding"; the harness passes a
+width-only override permanently.
+
+**A dark top bar is asked for with `headerClassName`**, giving it both halves
+(`bg-secondary text-secondary-foreground`) — never by colouring the root and expecting the bar
+to follow.
+
+**The shell reads exactly five theme variables**: `--background` (page and top bar),
+`--foreground` (active section link), `--muted-foreground` (resting section links) and
+`--accent`/`--accent-foreground` (active side-menu item). It reads **no `--sidebar*` variable at
+all**. So `--muted-foreground` is not merely the text colour of the `--muted` surface — it is
+secondary text sitting directly on `--background`, and a theme that lightens it to suit a dark
+muted panel loses its top menu.
+
 Rules that make the shell behave:
 
 - **Labels never reach for i18n implicitly.** `translate` is a **prop** (`NavTranslate`), defaulting

package/build/components/footer/component.js

@@ -14,7 +14,7 @@ export const Footer = ({ links, translate = defaultNavTranslate, children, class
     if ((links == null || links.length < 1) && children == null) {
         return null;
     }
-    return _jsx("footer", { className: cn('border-t py-6', className), style: style, children: _jsxs("div", { className: cn('flex flex-wrap items-center gap-4 text-sm', containerClassName ?? 'px-4'), children: [links?.map((link, idx) => {
+    return _jsx("footer", { className: cn('border-t py-6', className), style: style, children: _jsxs("div", { className: cn('flex flex-wrap items-center gap-4 text-sm px-4', containerClassName), children: [links?.map((link, idx) => {
                     const label = resolveNavLabel(translate, link.label, `modules.${link.alias ?? link.href ?? ''}`, link.alias ?? link.href);
                     return link.href != null
                         ? _jsx(Link, { src: link.href, open: link.open, children: label }, `${link.href}:${idx}`)

package/build/components/footer/component.js.map

@@ -1 +1 @@
-{"version":3,"file":"component.js","sourceRoot":"","sources":["../../../src/components/footer/component.tsx"],"names":[],"mappings":";AACA,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAC7E,OAAO,EAAE,EAAE,EAAE,MAAM,aAAa,CAAA;AAChC,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAIjC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,MAAM,GAAoB,CAAC,EACtC,KAAK,EAAE,SAAS,GAAG,mBAAmB,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,kBAAkB,EACvF,EAAE,EAAE;IACH,IAAI,CAAC,KAAK,IAAI,IAAI,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,QAAQ,IAAI,IAAI,EAAE,CAAC;QAC5D,OAAO,IAAI,CAAA;IACb,CAAC;IAED,OAAO,iBAAQ,SAAS,EAAE,EAAE,CAAC,eAAe,EAAE,SAAS,CAAC,EAAE,KAAK,EAAE,KAAK,YACpE,eAAK,SAAS,EAAE,EAAE,CAAC,2CAA2C,EAAE,kBAAkB,IAAI,MAAM,CAAC,aAC1F,KAAK,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE;oBACxB,MAAM,KAAK,GAAG,eAAe,CAC3B,SAAS,EAAE,IAAI,CAAC,KAAK,EAAE,WAAW,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,IAAI,IAAI,EAAE,EAAE,EAAE,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,IAAI,CAC3F,CAAA;oBAED,OAAO,IAAI,CAAC,IAAI,IAAI,IAAI;wBACtB,CAAC,CAAC,KAAC,IAAI,IAA6B,GAAG,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,YAAG,KAAK,IAA9D,GAAG,IAAI,CAAC,IAAI,IAAI,GAAG,EAAE,CAAiD;wBACnF,CAAC,CAAC,KAAC,IAAI,IAA8B,MAAM,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,YAAG,KAAK,IAAnE,GAAG,IAAI,CAAC,KAAK,IAAI,GAAG,EAAE,CAAqD,CAAA;gBAC5F,CAAC,CAAC,EACD,QAAQ,IACL,GACC,CAAA;AACX,CAAC,CAAA"}
+{"version":3,"file":"component.js","sourceRoot":"","sources":["../../../src/components/footer/component.tsx"],"names":[],"mappings":";AACA,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAC7E,OAAO,EAAE,EAAE,EAAE,MAAM,aAAa,CAAA;AAChC,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAIjC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,MAAM,GAAoB,CAAC,EACtC,KAAK,EAAE,SAAS,GAAG,mBAAmB,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,kBAAkB,EACvF,EAAE,EAAE;IACH,IAAI,CAAC,KAAK,IAAI,IAAI,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,QAAQ,IAAI,IAAI,EAAE,CAAC;QAC5D,OAAO,IAAI,CAAA;IACb,CAAC;IAED,OAAO,iBAAQ,SAAS,EAAE,EAAE,CAAC,eAAe,EAAE,SAAS,CAAC,EAAE,KAAK,EAAE,KAAK,YACpE,eAAK,SAAS,EAAE,EAAE,CAAC,gDAAgD,EAAE,kBAAkB,CAAC,aACrF,KAAK,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE;oBACxB,MAAM,KAAK,GAAG,eAAe,CAC3B,SAAS,EAAE,IAAI,CAAC,KAAK,EAAE,WAAW,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,IAAI,IAAI,EAAE,EAAE,EAAE,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,IAAI,CAC3F,CAAA;oBAED,OAAO,IAAI,CAAC,IAAI,IAAI,IAAI;wBACtB,CAAC,CAAC,KAAC,IAAI,IAA6B,GAAG,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,YAAG,KAAK,IAA9D,GAAG,IAAI,CAAC,IAAI,IAAI,GAAG,EAAE,CAAiD;wBACnF,CAAC,CAAC,KAAC,IAAI,IAA8B,MAAM,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,YAAG,KAAK,IAAnE,GAAG,IAAI,CAAC,KAAK,IAAI,GAAG,EAAE,CAAqD,CAAA;gBAC5F,CAAC,CAAC,EACD,QAAQ,IACL,GACC,CAAA;AACX,CAAC,CAAA"}

package/build/components/nav/layout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../../src/components/nav/layout.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,OAAO,CAAA;AAO/B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAahD;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS,EAAE,EAAE,CAAC,cAAc,CAiCxC,CAAA"}
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../../src/components/nav/layout.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,OAAO,CAAA;AAO/B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAahD;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS,EAAE,EAAE,CAAC,cAAc,CAwDxC,CAAA"}

package/build/components/nav/layout.js

@@ -10,8 +10,8 @@ import { TopNav } from './top.js';
  *
  * It lives in ONE constant because the three regions have to agree: a content area with its own
  * width sits visibly inset from a full-width header, which reads as a mistake rather than as a
- * design. Override it through `containerClassName` — never by giving the content a width of its
- * own.
+ * design. Adjust it through `containerClassName`, which is MERGED over this — never by giving
+ * the content a width of its own.
  */
 const CONTAINER = 'mx-auto w-full max-w-6xl px-4';
 /**
@@ -22,11 +22,18 @@ const CONTAINER = 'mx-auto w-full max-w-6xl px-4';
  * viewports and one strip for narrow ones. Both render only when the active section has
  * more than one screen, so the single-screen case costs nothing but the elements' absence.
  */
-export const NavLayout = ({ nav, translate, title, home, actions, footer, children, className, style, contentClassName, containerClassName }) => {
+export const NavLayout = ({ nav, translate, title, home, actions, footer, children, className, style, headerClassName, contentClassName, containerClassName }) => {
     const navigator = useNavigate();
     const brandAlias = home ?? nav.sections.find(section => section.items.length > 0)?.items[0]?.alias;
-    const container = containerClassName ?? CONTAINER;
-    return _jsxs("div", { className: cn('flex min-h-screen flex-col bg-background text-foreground', className), style: style, children: [_jsxs("header", { className: "sticky top-0 z-40 border-b bg-background", children: [_jsxs("div", { className: cn('flex h-14 items-center gap-6', container), children: [title != null ? _jsx("a", { onClick: brandAlias != null ? navigator.press(brandAlias) : undefined, className: cn('brand flex items-center gap-2 text-lg font-semibold', brandAlias != null && 'cursor-pointer'), children: title }) : null, _jsx(TopNav, { config: nav, translate: translate, ariaLabel: "Sections" }), _jsx("div", { className: "ml-auto flex items-center gap-2", children: actions })] }), _jsx(SideNav, { config: nav, translate: translate, variant: "bar", ariaLabel: "Screens", className: "md:hidden" })] }), _jsxs("div", { className: "flex flex-1", children: [_jsx(SideNav, { config: nav, translate: translate, variant: "side", ariaLabel: "Screens", className: "hidden md:block" }), _jsx("main", { className: cn('flex-1 py-8', contentClassName), children: _jsx("div", { className: cn(container), children: children }) })] }), Array.isArray(footer)
+    // MERGED over the default, never substituted for it. `containerClassName` is how a design
+    // adjusts ONE aspect of the rhythm — almost always the width — and a caller passing
+    // `max-w-[1280px]` means "wider", not "no padding and no centring". Substituting dropped
+    // `px-4` and `mx-auto` along with the width it replaced, which is a page whose header,
+    // content and footer all run flush to the window edge. tailwind-merge keeps the override
+    // winning on the utility it names and leaves the rest of the rhythm standing, so a width-only
+    // value stays a width-only change; `px-8` still overrides the padding when that is the intent.
+    const container = cn(CONTAINER, containerClassName);
+    return _jsxs("div", { className: cn('flex min-h-screen flex-col bg-background text-foreground', className), style: style, children: [_jsxs("header", { className: cn('sticky top-0 z-40 border-b bg-background text-foreground', headerClassName), children: [_jsxs("div", { className: cn('flex h-14 items-center gap-6', container), children: [title != null ? _jsx("a", { onClick: brandAlias != null ? navigator.press(brandAlias) : undefined, className: cn('brand flex items-center gap-2 text-lg font-semibold', brandAlias != null && 'cursor-pointer'), children: title }) : null, _jsx(TopNav, { config: nav, translate: translate, ariaLabel: "Sections" }), _jsx("div", { className: "ml-auto flex items-center gap-2", children: actions })] }), _jsx(SideNav, { config: nav, translate: translate, variant: "bar", ariaLabel: "Screens", className: "md:hidden" })] }), _jsxs("div", { className: "flex flex-1", children: [_jsx(SideNav, { config: nav, translate: translate, variant: "side", ariaLabel: "Screens", className: "hidden md:block" }), _jsx("main", { className: cn('flex-1 py-8', contentClassName), children: _jsx("div", { className: cn(container), children: children }) })] }), Array.isArray(footer)
                 ? _jsx(Footer, { links: footer, translate: translate, containerClassName: container })
                 : footer != null ? _jsx(Footer, { containerClassName: container, children: footer }) : null] });
 };

package/build/components/nav/layout.js.map

@@ -1 +1 @@
-{"version":3,"file":"layout.js","sourceRoot":"","sources":["../../../src/components/nav/layout.tsx"],"names":[],"mappings":";AACA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,EAAE,EAAE,EAAE,MAAM,aAAa,CAAA;AAChC,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAA;AAE/C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AAGjC;;;;;;;;GAQG;AACH,MAAM,SAAS,GAAG,+BAA+B,CAAA;AAEjD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,SAAS,GAAuB,CAAC,EAC5C,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EACxE,gBAAgB,EAAE,kBAAkB,EACrC,EAAE,EAAE;IACH,MAAM,SAAS,GAAG,WAAW,EAAE,CAAA;IAC/B,MAAM,UAAU,GAAG,IAAI,IAAI,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,CAAA;IAClG,MAAM,SAAS,GAAG,kBAAkB,IAAI,SAAS,CAAA;IAEjD,OAAO,eACL,SAAS,EAAE,EAAE,CAAC,0DAA0D,EAAE,SAAS,CAAC,EACpF,KAAK,EAAE,KAAK,aAEZ,kBAAQ,SAAS,EAAC,0CAA0C,aAC1D,eAAK,SAAS,EAAE,EAAE,CAAC,8BAA8B,EAAE,SAAS,CAAC,aAC1D,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,YACf,OAAO,EAAE,UAAU,IAAI,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,SAAS,EACrE,SAAS,EAAE,EAAE,CAAC,qDAAqD,EAAE,UAAU,IAAI,IAAI,IAAI,gBAAgB,CAAC,YAC5G,KAAK,GAAK,CAAC,CAAC,CAAC,IAAI,EACnB,KAAC,MAAM,IAAC,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAC,UAAU,GAAG,EAClE,cAAK,SAAS,EAAC,iCAAiC,YAAE,OAAO,GAAO,IAC5D,EACN,KAAC,OAAO,IAAC,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,EAAC,KAAK,EAAC,SAAS,EAAC,SAAS,EAAC,SAAS,EAAC,WAAW,GAAG,IAC/F,EACT,eAAK,SAAS,EAAC,aAAa,aAC1B,KAAC,OAAO,IAAC,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,EAAC,MAAM,EAAC,SAAS,EAAC,SAAS,EAAC,SAAS,EAAC,iBAAiB,GAAG,EAC7G,eAAM,SAAS,EAAE,EAAE,CAAC,aAAa,EAAE,gBAAgB,CAAC,YAClD,cAAK,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,YAAG,QAAQ,GAAO,GAC1C,IACH,EACL,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;gBACpB,CAAC,CAAC,KAAC,MAAM,IAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,kBAAkB,EAAE,SAAS,GAAI;gBAChF,CAAC,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,KAAC,MAAM,IAAC,kBAAkB,EAAE,SAAS,YAAG,MAAM,GAAU,CAAC,CAAC,CAAC,IAAI,IAChF,CAAA;AACR,CAAC,CAAA"}
+{"version":3,"file":"layout.js","sourceRoot":"","sources":["../../../src/components/nav/layout.tsx"],"names":[],"mappings":"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"}

package/build/components/nav/types.d.ts

@@ -27,12 +27,27 @@ export interface NavLayoutProps extends PropsWithChildren<StyledProps> {
     actions?: ReactNode;
     /** Links array renders the standard footer; a node replaces it entirely. */
     footer?: PanelNavLink[] | ReactNode;
+    /**
+     * Styles the HEADER — the sticky bar carrying the brand, the section menu and `actions`.
+     *
+     * The header is its own SURFACE: it paints an opaque background because content scrolls
+     * under it. Give it a background here and you must give it the paired foreground too
+     * (`bg-secondary text-secondary-foreground`), exactly as on any other surface — this is the
+     * supported way to give an application a dark top bar, and it is why colouring the root
+     * instead is not.
+     */
+    headerClassName?: string;
     /** Styles the content area. NOT its width — see `containerClassName`. */
     contentClassName?: string;
     /**
      * The page's horizontal rhythm — width and side padding — applied identically to the header
      * row, the content and the footer row. Give the content a width of its own and it sits inset
      * from a full-width header, which reads as a bug rather than as a layout.
+     *
+     * MERGED over the shell's default (`mx-auto w-full max-w-6xl px-4`), not substituted for it:
+     * pass `max-w-[1280px]` and only the width changes, while the centring and the side padding
+     * stay. Name the utility you actually want to move — `px-8` widens the gutters — because
+     * anything you do not name keeps its default.
      */
     containerClassName?: string;
 }

package/build/components/nav/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/components/nav/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAA;AACxF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAE9C,UAAU,cAAe,SAAQ,WAAW;IAC1C,MAAM,EAAE,cAAc,CAAA;IACtB,yFAAyF;IACzF,SAAS,CAAC,EAAE,YAAY,CAAA;IACxB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,WAAY,SAAQ,cAAc;CAAI;AAEvD,MAAM,WAAW,YAAa,SAAQ,cAAc;IAClD;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,KAAK,CAAA;CACzB;AAED,MAAM,WAAW,cAAe,SAAQ,iBAAiB,CAAC,WAAW,CAAC;IACpE,GAAG,EAAE,cAAc,CAAA;IACnB,SAAS,CAAC,EAAE,YAAY,CAAA;IACxB,2DAA2D;IAC3D,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,gFAAgF;IAChF,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,yFAAyF;IACzF,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,YAAY,EAAE,GAAG,SAAS,CAAA;IACnC,yEAAyE;IACzE,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAC5B"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/components/nav/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAA;AACxF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAE9C,UAAU,cAAe,SAAQ,WAAW;IAC1C,MAAM,EAAE,cAAc,CAAA;IACtB,yFAAyF;IACzF,SAAS,CAAC,EAAE,YAAY,CAAA;IACxB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,WAAY,SAAQ,cAAc;CAAI;AAEvD,MAAM,WAAW,YAAa,SAAQ,cAAc;IAClD;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,KAAK,CAAA;CACzB;AAED,MAAM,WAAW,cAAe,SAAQ,iBAAiB,CAAC,WAAW,CAAC;IACpE,GAAG,EAAE,cAAc,CAAA;IACnB,SAAS,CAAC,EAAE,YAAY,CAAA;IACxB,2DAA2D;IAC3D,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,gFAAgF;IAChF,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,yFAAyF;IACzF,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,YAAY,EAAE,GAAG,SAAS,CAAA;IACnC;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,yEAAyE;IACzE,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB;;;;;;;;;OASG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAC5B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/web-panel",
-  "version": "0.1.18-rc.11",
+  "version": "0.1.18-rc.13",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -48,7 +48,7 @@
     "@owlmeans/client-flow": "^0.1.18-rc.7",
     "@owlmeans/client-i18n": "^0.1.18-rc.7",
     "@owlmeans/client-entrypoint": "^0.1.18-rc.7",
-    "@owlmeans/client-panel": "^0.1.18-rc.11",
+    "@owlmeans/client-panel": "^0.1.18-rc.12",
     "@owlmeans/client-route": "^0.1.18-rc.7",
     "@owlmeans/config": "^0.1.18-rc.7",
     "@owlmeans/context": "^0.1.18-rc.6",

package/src/components/footer/component.tsx

@@ -21,7 +21,7 @@ export const Footer: FC<FooterProps> = ({
   }
 
   return <footer className={cn('border-t py-6', className)} style={style}>
-    <div className={cn('flex flex-wrap items-center gap-4 text-sm', containerClassName ?? 'px-4')}>
+    <div className={cn('flex flex-wrap items-center gap-4 text-sm px-4', containerClassName)}>
       {links?.map((link, idx) => {
         const label = resolveNavLabel(
           translate, link.label, `modules.${link.alias ?? link.href ?? ''}`, link.alias ?? link.href

package/src/components/nav/layout.tsx

@@ -13,8 +13,8 @@ import type { NavLayoutProps } from './types.js'
  *
  * It lives in ONE constant because the three regions have to agree: a content area with its own
  * width sits visibly inset from a full-width header, which reads as a mistake rather than as a
- * design. Override it through `containerClassName` — never by giving the content a width of its
- * own.
+ * design. Adjust it through `containerClassName`, which is MERGED over this — never by giving
+ * the content a width of its own.
  */
 const CONTAINER = 'mx-auto w-full max-w-6xl px-4'
 
@@ -28,17 +28,40 @@ const CONTAINER = 'mx-auto w-full max-w-6xl px-4'
  */
 export const NavLayout: FC<NavLayoutProps> = ({
   nav, translate, title, home, actions, footer, children, className, style,
-  contentClassName, containerClassName
+  headerClassName, contentClassName, containerClassName
 }) => {
   const navigator = useNavigate()
   const brandAlias = home ?? nav.sections.find(section => section.items.length > 0)?.items[0]?.alias
-  const container = containerClassName ?? CONTAINER
+  // MERGED over the default, never substituted for it. `containerClassName` is how a design
+  // adjusts ONE aspect of the rhythm — almost always the width — and a caller passing
+  // `max-w-[1280px]` means "wider", not "no padding and no centring". Substituting dropped
+  // `px-4` and `mx-auto` along with the width it replaced, which is a page whose header,
+  // content and footer all run flush to the window edge. tailwind-merge keeps the override
+  // winning on the utility it names and leaves the rest of the rhythm standing, so a width-only
+  // value stays a width-only change; `px-8` still overrides the padding when that is the intent.
+  const container = cn(CONTAINER, containerClassName)
 
   return <div
     className={cn('flex min-h-screen flex-col bg-background text-foreground', className)}
     style={style}
   >
-    <header className="sticky top-0 z-40 border-b bg-background">
+    {/*
+      * The header is a SURFACE, and it states both halves of one.
+      *
+      * It has to paint an opaque background — it is sticky, and content scrolls underneath —
+      * which makes it a different surface from the root behind it. A colour set on the root
+      * (`className="bg-secondary text-secondary-foreground"`, a dark application shell) then
+      * inherits INTO this bar while its own `bg-background` stays put, and every child that
+      * states no colour of its own — the brand, a ghost-variant action button — is painted in
+      * the foreground of a surface it is not on. That is light-on-light, it raises nothing at
+      * build or run time, and it is invisible only to whoever opens the page.
+      *
+      * `text-foreground` is what stops the inheritance at the boundary. It is not decoration
+      * and it is not redundant with the root: pairing has to be restated by every element that
+      * repaints its own background. `headerClassName` lands after it, so an app that wants a
+      * dark bar overrides BOTH halves through tailwind-merge.
+      */}
+    <header className={cn('sticky top-0 z-40 border-b bg-background text-foreground', headerClassName)}>
       <div className={cn('flex h-14 items-center gap-6', container)}>
         {title != null ? <a
           onClick={brandAlias != null ? navigator.press(brandAlias) : undefined}

package/src/components/nav/types.ts

@@ -30,12 +30,27 @@ export interface NavLayoutProps extends PropsWithChildren<StyledProps> {
   actions?: ReactNode
   /** Links array renders the standard footer; a node replaces it entirely. */
   footer?: PanelNavLink[] | ReactNode
+  /**
+   * Styles the HEADER — the sticky bar carrying the brand, the section menu and `actions`.
+   *
+   * The header is its own SURFACE: it paints an opaque background because content scrolls
+   * under it. Give it a background here and you must give it the paired foreground too
+   * (`bg-secondary text-secondary-foreground`), exactly as on any other surface — this is the
+   * supported way to give an application a dark top bar, and it is why colouring the root
+   * instead is not.
+   */
+  headerClassName?: string
   /** Styles the content area. NOT its width — see `containerClassName`. */
   contentClassName?: string
   /**
    * The page's horizontal rhythm — width and side padding — applied identically to the header
    * row, the content and the footer row. Give the content a width of its own and it sits inset
    * from a full-width header, which reads as a bug rather than as a layout.
+   *
+   * MERGED over the shell's default (`mx-auto w-full max-w-6xl px-4`), not substituted for it:
+   * pass `max-w-[1280px]` and only the width changes, while the centring and the side padding
+   * stay. Name the utility you actually want to move — `px-8` widens the gutters — because
+   * anything you do not name keeps its default.
    */
   containerClassName?: string
 }

package/tests/harness/mount.tsx

@@ -53,6 +53,16 @@ const Layout: FC<PropsWithChildren> = ({ children }) => <NavLayout
   title="Harness"
   actions={<button id="action-slot">action</button>}
   footer={footerLinks}
+  // A DARK APPLICATION SHELL, which is what a themed app does to the root: a contrasting
+  // surface pair, both halves correct. The header paints its own opaque background, so it is
+  // a different surface, and everything in it must stay legible against `--background`
+  // rather than against this. The harness carries it permanently so every navigation test
+  // runs against the hostile case instead of a default-coloured page.
+  className="bg-primary text-primary-foreground"
+  // A WIDTH-ONLY rhythm override, which is what a design pass writes when it wants a wider
+  // page. It names the width and nothing else, so the centring and the side padding must
+  // survive it — substituting this for the default is a page running flush to the window edge.
+  containerClassName="max-w-[1280px]"
 >{children}</NavLayout>
 
 /** A grouping screen — it renders whichever child the router matched. */

package/tests/nav.spec.ts

@@ -98,6 +98,88 @@ describe('@owlmeans/web-panel — two-layer navigation', () => {
   }, TIMEOUT)
 })
 
+/**
+ * Perceptual lightness of a computed colour, 0 (black) to 1 (white).
+ *
+ * The theme is authored in `oklch(L C H)` and Chromium hands that back from
+ * `getComputedStyle` unchanged — it does not convert to `rgb()`, and neither does a canvas
+ * `fillStyle` round-trip — so L is read straight off. `rgb()` still turns up for the
+ * transparent case, and is approximated through its luminance.
+ *
+ * Comparing lightness rather than colour strings is the point: the failure being pinned is
+ * not a wrong colour, it is two colours too CLOSE to tell apart, which equality never sees.
+ */
+const lightness = (value: string): number => {
+  const oklch = /^oklch\(\s*([\d.]+%?)/i.exec(value.trim())
+  if (oklch != null) {
+    const raw = oklch[1]
+
+    return raw.endsWith('%') ? parseFloat(raw) / 100 : parseFloat(raw)
+  }
+
+  const [r, g, b] = (value.match(/[\d.]+/g) ?? []).slice(0, 3).map(Number)
+  const channel = (c: number): number => {
+    const v = c / 255
+
+    return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4
+  }
+
+  // The cube root maps luminance onto roughly the same perceptual scale as OKLab's L.
+  return (0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b)) ** (1 / 3)
+}
+
+/** The gap below which text stops being readable on its surface — as `ensureReadableTheme`. */
+const READABLE = 0.35
+
+describe('@owlmeans/web-panel — the header is its own surface', () => {
+  // The harness root carries `bg-primary text-primary-foreground`: a dark application shell,
+  // both halves of the pair correct. The header paints `bg-background` over it and is
+  // therefore a DIFFERENT surface — a near-white foreground inherited from the root lands on
+  // a near-white bar, and every child stating no colour of its own goes invisible. Nothing
+  // fails at build or at run time, so this is pinned from outside, on rendered pixels.
+  test('header content stays legible when the shell around it is dark', async () => {
+    const { page, close } = await open('/dash')
+    try {
+      await page.waitForSelector('#dash')
+      const style = async (selector: string, property: 'color' | 'backgroundColor') =>
+        page.locator(selector).first().evaluate(
+          (el, prop) => window.getComputedStyle(el)[prop as 'color'], property
+        )
+
+      const surface = lightness(await style('header', 'backgroundColor'))
+      const legible = async (selector: string) =>
+        Math.abs(lightness(await style(selector, 'color')) - surface) >= READABLE
+
+      // The brand and the action slot state no colour of their own, so they are exactly the
+      // elements that inherit across the boundary. The action slot is the reported case: a
+      // ghost-variant button rendered white on a white bar.
+      expect({
+        brand: await legible('a.brand'),
+        actions: await legible('#action-slot'),
+        section: await legible('[data-slot="navigation-menu-link"]'),
+      }).toEqual({ brand: true, actions: true, section: true })
+    } finally {
+      await close()
+    }
+  }, TIMEOUT)
+
+  test('the header keeps an opaque background of its own', async () => {
+    // This is what makes it a separate surface, and therefore what makes the pairing above
+    // mandatory rather than redundant: it is sticky, so content scrolls beneath it and a
+    // transparent bar would show that content through the menu.
+    const { page, close } = await open('/dash')
+    try {
+      await page.waitForSelector('#dash')
+      const background = await page.locator('header').first()
+        .evaluate(el => window.getComputedStyle(el).backgroundColor)
+
+      expect(background).not.toMatch(/rgba\(0, 0, 0, 0\)|transparent/)
+    } finally {
+      await close()
+    }
+  }, TIMEOUT)
+})
+
 describe('@owlmeans/web-panel — layout rhythm and link styling', () => {
   test('header, content and footer share one horizontal rhythm', async () => {
     // A content area with a width of its own sits visibly inset from a full-width header, which
@@ -121,6 +203,34 @@ describe('@owlmeans/web-panel — layout rhythm and link styling', () => {
     }
   }, TIMEOUT)
 
+  test('a width-only rhythm override keeps the side padding', async () => {
+    // The harness passes `containerClassName="max-w-[1280px]"` — a width and nothing else.
+    // `containerClassName` is merged over the shell's default rhythm rather than substituted
+    // for it, so `px-4` and `mx-auto` survive an override that never mentioned them. Replacing
+    // instead produced a header, content and footer all flush to the window edge.
+    const { page, close } = await open('/prefs')
+    try {
+      await page.waitForSelector('#prefs')
+      const padding = async (selector: string) => page.locator(selector).first().evaluate(el => {
+        const style = window.getComputedStyle(el)
+
+        return [parseFloat(style.paddingLeft), parseFloat(style.paddingRight)]
+      })
+
+      const [header, content, footer] = await Promise.all([
+        padding('header > div'), padding('main > div'), padding('footer > div'),
+      ])
+
+      expect({
+        header: header.every(value => value > 0),
+        content: content.every(value => value > 0),
+        footer: footer.every(value => value > 0),
+      }).toEqual({ header: true, content: true, footer: true })
+    } finally {
+      await close()
+    }
+  }, TIMEOUT)
+
   test('section entries render as links, not buttons', async () => {
     const { page, close } = await open('/dash')
     try {