@cosmicdrift/kumiko-headless 0.200.0 → 0.201.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-headless",
-  "version": "0.200.0",
+  "version": "0.201.0",
   "description": "Headless UI logic for Kumiko — Dispatcher contract, Form-Controller, View-Model, Nav-Resolver. Plattform- und React-frei; jeder Renderer (renderer, renderer-web, renderer-native, …) komponiert darauf.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -36,7 +36,7 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.200.0",
+    "@cosmicdrift/kumiko-framework": "0.201.0",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3"
   },

package/src/apex/__tests__/render.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, test } from "bun:test";
+import { APEX_NAV_MENU_CSS, APEX_NAV_TOGGLE_RESPONSIVE_CSS, APEX_STRUCTURAL_CSS } from "../css";
 import { type ApexPage, renderApexPage } from "../index";
 
 const brand = { tokensCss: ":root{--primary:#123;--primary-fg:#fff;--bg:#fff;--fg:#000;}" };
@@ -92,6 +93,78 @@ describe("renderApexPage", () => {
     expect(html).toContain('<a href="#pricing">Pricing</a>');
   });
 
+  test("nav-links wrap in a mobile hamburger toggle; no navLinks omits it", () => {
+    const withNav = renderApexPage(
+      page({
+        header: {
+          brand: { href: "/", label: "Acme" },
+          navLinks: [{ label: "Pricing", href: "#pricing" }],
+        },
+      }),
+    );
+    expect(withNav).toContain('<details class="nav-toggle">');
+    expect(withNav).toContain('<summary class="nav-toggle__trigger" aria-label="Menu">');
+    expect(withNav).toContain('<nav class="nav-links">');
+
+    const customLabel = renderApexPage(
+      page({
+        header: {
+          brand: { href: "/", label: "Acme" },
+          navLinks: [{ label: "Pricing", href: "#pricing" }],
+          menuLabel: "Menü",
+        },
+      }),
+    );
+    expect(customLabel).toContain('aria-label="Menü"');
+
+    const withoutNav = renderApexPage(page());
+    expect(withoutNav).not.toContain('<details class="nav-toggle">');
+  });
+
+  test("mobile-open .nav-toggle rule wins the cascade over the desktop-hidden default", () => {
+    // APEX_NAV_MENU_CSS sets `.nav-toggle { display: none; }` unconditionally;
+    // APEX_NAV_TOGGLE_RESPONSIVE_CSS re-declares it `.nav .nav-toggle { display:
+    // inline-flex; }` inside the 640px query. A markup-only assertion can't catch
+    // a reordering that silently restores fw#2047 (nav-links hidden on mobile
+    // with no way to reopen them).
+    const hiddenDefault = APEX_STRUCTURAL_CSS.indexOf(".nav-toggle { display: none; }");
+    const mobileOpen = APEX_STRUCTURAL_CSS.indexOf(".nav .nav-toggle { display: inline-flex; }");
+    expect(hiddenDefault).toBeGreaterThan(-1);
+    expect(mobileOpen).toBeGreaterThan(-1);
+    expect(mobileOpen).toBeGreaterThan(hiddenDefault);
+  });
+
+  test("APEX_NAV_TOGGLE_RESPONSIVE_CSS's mobile-open rules outrank APEX_NAV_MENU_CSS's hidden default regardless of concatenation order (fw#2125)", () => {
+    // money-horse/show-pony/the docs sample call renderApexHeader() standalone and
+    // concatenate APEX_NAV_MENU_CSS with their own page CSS in whatever order they
+    // choose — they don't control ordering relative to APEX_STRUCTURAL_CSS's
+    // internal layout. The "show" rules are therefore specificity-hardened
+    // (`.nav .nav-toggle`, 2 classes) rather than relying on source order to beat
+    // APEX_NAV_MENU_CSS's bare `.nav-toggle` default (1 class) — verify both carry
+    // that extra `.nav ` prefix so the fix holds even when a consumer emits
+    // APEX_NAV_TOGGLE_RESPONSIVE_CSS BEFORE APEX_NAV_MENU_CSS.
+    expect(APEX_NAV_MENU_CSS).toContain(".nav-toggle { display: none; }");
+    expect(APEX_NAV_MENU_CSS).toContain(".nav-toggle__trigger { display: none;");
+    expect(APEX_NAV_MENU_CSS).not.toContain(".nav-toggle { display: inline-flex");
+    expect(APEX_NAV_MENU_CSS).not.toContain(".nav-toggle__trigger { display: inline-flex");
+
+    expect(APEX_NAV_TOGGLE_RESPONSIVE_CSS).toContain(".nav .nav-toggle { display: inline-flex; }");
+    expect(APEX_NAV_TOGGLE_RESPONSIVE_CSS).toContain(
+      ".nav .nav-toggle__trigger { display: inline-flex; }",
+    );
+  });
+
+  test("APEX_NAV_TOGGLE_RESPONSIVE_CSS declares .nav as the positioned ancestor for the open dropdown", () => {
+    // `.nav-toggle[open] > .nav-links` is `position: absolute; top: calc(100% +
+    // 0.5rem); left: 0; right: 0` — it needs `.nav { position: relative; }` as
+    // its containing block. renderApexPage gets that from CHROME_LIGHT, but a
+    // standalone renderApexHeader() consumer's own header CSS typically doesn't
+    // declare it, and without it the dropdown opens off-screen against the
+    // viewport instead of under the header (fw#2125 follow-up: verified none of
+    // money-horse/show-pony/the docs sample's HEADER_CSS set it).
+    expect(APEX_NAV_TOGGLE_RESPONSIVE_CSS).toContain(".nav { position: relative; }");
+  });
+
   test("pricing: featured card gets badge + featured class, cap line precedes benefits", () => {
     const html = renderApexPage(
       page({

package/src/apex/css.ts

@@ -126,7 +126,7 @@ const CHROME_LIGHT = `
     background: color-mix(in srgb, var(--bg) 85%, transparent);
     backdrop-filter: saturate(140%) blur(8px);
     border-bottom: 1px solid var(--border); }
-  .nav { display: flex; align-items: center; justify-content: space-between; gap: 1rem; padding-block: 0.85rem; }
+  .nav { position: relative; display: flex; align-items: center; justify-content: space-between; gap: 1rem; padding-block: 0.85rem; }
   .brand { display: flex; align-items: center; gap: 0.55rem; font-weight: 700; font-size: 1.125rem; color: var(--fg); }
   .brand a { color: var(--fg); display: inline-flex; align-items: center; gap: 0.55rem; }
   .brand a:hover { color: var(--fg); }
@@ -199,29 +199,39 @@ const RESPONSIVE = `
   }
 `;
 
-// Dropdown nav entry (kind:"menu"): CSS-only, reveals on hover AND keyboard
-// focus-within (the trigger is a real <button>, panel items are <a>). The panel
-// is a light popover in BOTH themes — only the trigger color tracks the
-// surrounding nav. Nav is hidden < 640px (CHROME_*), so this is desktop-only.
-// Exported standalone so a consumer rendering its own header chrome (not the
-// full apex page) can include just this, without duplicating the rules.
+// header renders navLinks TWICE (renderApexHeader): a plain always-visible
+// .nav-links row, plus a copy nested in .nav-toggle for < 640px — a closed
+// <details> can't be forced "always open" on desktop via CSS (Chrome keeps
+// its content unpainted regardless of a child's own `display`), so two
+// copies sidestep that instead of fighting it. Exported standalone so a
+// consumer rendering its own header chrome can include just this. A
+// consumer using renderApexHeader() outside renderApexPage also needs
+// APEX_NAV_TOGGLE_RESPONSIVE_CSS below for the mobile toggle to open.
 export const APEX_NAV_MENU_CSS = `
+  .nav-toggle { display: none; }
+  .nav-toggle__trigger { display: none; align-items: center; justify-content: center;
+    width: 2.25rem; height: 2.25rem; border-radius: 0.5rem; cursor: pointer;
+    color: var(--fg-muted); list-style: none; }
+  .nav-toggle__trigger::-webkit-details-marker { display: none; }
+  .nav-toggle__trigger:hover { color: var(--fg); background: var(--bg-muted); }
+  .nav-toggle__trigger svg { width: 1.35rem; height: 1.35rem; }
+  .apex-dark .nav-toggle__trigger { color: var(--on-dark-muted); }
+  .apex-dark .nav-toggle__trigger:hover { color: var(--on-dark); background: rgba(255,255,255,0.08); }
+
   .nav-menu { position: relative; display: inline-flex; }
   .nav-menu__trigger { display: inline-flex; align-items: center; gap: 0.3rem;
     font: inherit; font-size: 0.9375rem; color: var(--fg-muted);
-    background: none; border: 0; padding: 0; cursor: pointer; }
+    cursor: pointer; list-style: none; }
+  .nav-menu__trigger::-webkit-details-marker { display: none; }
   .nav-menu__trigger:hover { color: var(--fg); }
   .nav-menu__chev { display: inline-flex; transition: transform 0.15s; opacity: 0.7; }
   .nav-menu__chev svg { width: 0.95em; height: 0.95em; }
-  .nav-menu:hover .nav-menu__chev, .nav-menu:focus-within .nav-menu__chev { transform: rotate(180deg); }
+  .nav-menu[open] .nav-menu__chev { transform: rotate(180deg); }
   .nav-menu__panel { position: absolute; top: calc(100% + 0.5rem); left: 0; z-index: 20;
     min-width: 21rem; padding: 0.5rem; background: var(--bg-card); color: var(--fg);
     border: 1px solid var(--border); border-radius: 0.75rem; box-shadow: var(--shadow);
-    display: flex; flex-direction: column; gap: 0.125rem;
-    opacity: 0; visibility: hidden; transform: translateY(0.375rem);
-    transition: opacity 0.15s, transform 0.15s, visibility 0.15s; }
-  .nav-menu:hover .nav-menu__panel, .nav-menu:focus-within .nav-menu__panel {
-    opacity: 1; visibility: visible; transform: translateY(0); }
+    flex-direction: column; gap: 0.125rem; }
+  .nav-menu[open] .nav-menu__panel { display: flex; }
   .nav-menu__item { display: flex; gap: 0.75rem; align-items: flex-start;
     padding: 0.6rem 0.7rem; border-radius: 0.5rem; color: var(--fg); }
   .nav-menu__item:hover { background: var(--bg-muted); color: var(--fg); }
@@ -247,6 +257,38 @@ export const APEX_NAV_MENU_CSS = `
   .nav-menu__panel a.nav-menu__more:hover { color: var(--primary-hover); }
 `;
 
+// Standalone mobile-open rules for .nav-toggle, split out of RESPONSIVE so a
+// consumer calling renderApexHeader() outside renderApexPage (money-horse,
+// show-pony, the docs sample) can include just this alongside
+// APEX_NAV_MENU_CSS, without pulling in the rest of RESPONSIVE's page-level
+// grid breakpoints. The two "show" rules use the `.nav ` prefix (matching
+// renderApexHeader's `<div class="container nav">` wrapper) to raise their
+// specificity above APEX_NAV_MENU_CSS's bare `.nav-toggle`/`.nav-toggle__trigger`
+// "display: none" defaults — that makes them win regardless of concatenation
+// order, since a standalone consumer controls the order, not this file.
+// Also declares `.nav { position: relative; }`: the open dropdown positions
+// itself against .nav (`top/left/right` below), and renderApexPage's own
+// CHROME_LIGHT already sets that, but a standalone consumer's own header CSS
+// generally doesn't — without it the dropdown would anchor to the viewport
+// instead of the header and open off-screen. Redeclaring it here is a no-op
+// inside APEX_STRUCTURAL_CSS (same value, harmless if repeated).
+export const APEX_NAV_TOGGLE_RESPONSIVE_CSS = `
+  @media (max-width: 640px) {
+    .nav { position: relative; }
+    .nav .nav-toggle { display: inline-flex; }
+    .nav .nav-toggle__trigger { display: inline-flex; }
+    .nav-toggle[open] > .nav-links { display: flex; flex-direction: column; align-items: stretch;
+      gap: 0.25rem; position: absolute; top: calc(100% + 0.5rem); left: 0; right: 0; z-index: 30;
+      background: var(--bg-card); border: 1px solid var(--border); border-radius: 0.75rem;
+      box-shadow: var(--shadow); padding: 0.75rem; }
+    .nav-toggle[open] > .nav-links > a { color: var(--fg); padding: 0.4rem 0.25rem; }
+    .nav-toggle[open] > .nav-links > a:hover { color: var(--fg); }
+    .nav-toggle .nav-menu { display: block; }
+    .nav-toggle .nav-menu__panel { position: static; min-width: 0;
+      margin-top: 0.375rem; box-shadow: none; }
+  }
+`;
+
 export const APEX_STRUCTURAL_CSS =
   BASE_LAYOUT +
   HERO +
@@ -257,4 +299,5 @@ export const APEX_STRUCTURAL_CSS =
   CHROME_LIGHT +
   CHROME_DARK +
   APEX_NAV_MENU_CSS +
+  APEX_NAV_TOGGLE_RESPONSIVE_CSS +
   RESPONSIVE;

package/src/apex/index.ts

@@ -8,7 +8,7 @@ import { escapeHtml } from "../format";
 import { APEX_STRUCTURAL_CSS } from "./css";
 import { APEX_LIGHTBOX_HTML, APEX_LIGHTBOX_SCRIPT } from "./lightbox";
 
-export { APEX_NAV_MENU_CSS, APEX_STRUCTURAL_CSS } from "./css";
+export { APEX_NAV_MENU_CSS, APEX_NAV_TOGGLE_RESPONSIVE_CSS, APEX_STRUCTURAL_CSS } from "./css";
 export {
   APEX_LIGHTBOX_HTML,
   APEX_LIGHTBOX_SCRIPT,
@@ -81,6 +81,8 @@ export type ApexHeader = {
   /** Plain links and/or dropdown menus, in order. */
   readonly navLinks?: readonly ApexNavEntry[];
   readonly actions?: readonly ApexCta[];
+  /** aria-label for the mobile hamburger trigger (< 640px). Default "Menu". */
+  readonly menuLabel?: string;
 };
 
 export type ApexFooterColumn = { readonly heading: string; readonly links: readonly ApexLink[] };
@@ -398,7 +400,7 @@ function renderNavMenu(m: ApexNavMenu): string {
     m.footer !== undefined
       ? `<div class="nav-menu__sep"></div><a class="nav-menu__more" href="${escapeHtml(m.footer.href)}">${escapeHtml(m.footer.label)}</a>`
       : "";
-  return `<div class="nav-menu"><button type="button" class="nav-menu__trigger" aria-haspopup="true">${escapeHtml(m.label)}<span class="nav-menu__chev">${svgIcon('<path d="m6 9 6 6 6-6"/>')}</span></button><div class="nav-menu__panel">${itemsHtml}${footer}</div></div>`;
+  return `<details class="nav-menu"><summary class="nav-menu__trigger">${escapeHtml(m.label)}<span class="nav-menu__chev">${svgIcon('<path d="m6 9 6 6 6-6"/>')}</span></summary><div class="nav-menu__panel">${itemsHtml}${footer}</div></details>`;
 }
 
 function renderNavEntry(entry: ApexNavEntry): string {
@@ -418,7 +420,7 @@ export function renderApexHeader(h: ApexHeader): string {
   return `<header>
     <div class="container nav">
       <div class="brand"><a href="${escapeHtml(h.brand.href)}">${logo}${escapeHtml(h.brand.label)}</a></div>
-      ${navLinksHtml !== "" ? `<nav class="nav-links">${navLinksHtml}</nav>` : ""}
+      ${navLinksHtml !== "" ? `<nav class="nav-links">${navLinksHtml}</nav><details class="nav-toggle"><summary class="nav-toggle__trigger" aria-label="${escapeHtml(h.menuLabel ?? "Menu")}">${svgIcon('<path d="M4 6h16M4 12h16M4 18h16"/>')}</summary><nav class="nav-links">${navLinksHtml}</nav></details>` : ""}
       ${actionsHtml !== "" ? `<div class="nav-actions">${actionsHtml}</div>` : ""}
     </div>
   </header>`;