@cosmicdrift/kumiko-headless 0.98.0 → 0.102.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-headless",
-  "version": "0.98.0",
+  "version": "0.102.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>",
@@ -32,7 +32,7 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.98.0",
+    "@cosmicdrift/kumiko-framework": "0.102.0",
     "zod": "^4.4.3"
   },
   "publishConfig": {

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

@@ -53,6 +53,45 @@ describe("renderApexPage", () => {
     expect(html).toContain("<rect/>");
   });
 
+  test("nav menu entry renders a dropdown; plain links stay anchors", () => {
+    const html = renderApexPage(
+      page({
+        header: {
+          brand: { href: "/", label: "Acme" },
+          navLinks: [
+            {
+              kind: "menu",
+              label: "Product",
+              items: [
+                { icon: "<rect/>", title: "Planner", desc: "Plan it", href: "/p" },
+                { title: "<b>Reports</b>", href: "/r" },
+              ],
+              footer: { label: "See all", href: "/all" },
+            },
+            { label: "Pricing", href: "#pricing" },
+          ],
+        },
+      }),
+    );
+    // Menu chrome + trigger label.
+    expect(html).toContain('class="nav-menu"');
+    expect(html).toContain('class="nav-menu__trigger"');
+    expect(html).toContain("Product");
+    // Items: title, description, wrapped icon; missing desc/icon simply omitted.
+    expect(html).toContain('class="nav-menu__item" href="/p"');
+    expect(html).toContain("Planner");
+    expect(html).toContain("Plan it");
+    expect(html).toContain("<rect/>");
+    // Footer link under the divider.
+    expect(html).toContain('class="nav-menu__more" href="/all"');
+    expect(html).toContain("See all");
+    // Item titles are escaped (app-data, not trusted HTML).
+    expect(html).toContain("&lt;b&gt;Reports&lt;/b&gt;");
+    expect(html).not.toContain("<b>Reports</b>");
+    // The sibling plain link still renders as a normal anchor.
+    expect(html).toContain('<a href="#pricing">Pricing</a>');
+  });
+
   test("pricing: featured card gets badge + featured class, cap line precedes benefits", () => {
     const html = renderApexPage(
       page({

package/src/apex/css.ts

@@ -189,6 +189,45 @@ 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.
+export const APEX_NAV_MENU_CSS = `
+  .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; }
+  .nav-menu__trigger:hover { color: var(--fg); }
+  .nav-menu__chev { font-size: 0.7em; transition: transform 0.15s; }
+  .nav-menu:hover .nav-menu__chev, .nav-menu:focus-within .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); }
+  .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); }
+  .nav-menu__icon { flex: none; display: inline-flex; align-items: center; justify-content: center;
+    width: 2rem; height: 2rem; border-radius: 0.5rem;
+    background: color-mix(in srgb, var(--primary) 12%, transparent); color: var(--primary); }
+  .nav-menu__icon svg { width: 1.1rem; height: 1.1rem; }
+  .nav-menu__text { display: flex; flex-direction: column; gap: 0.1rem; }
+  .nav-menu__title { font-weight: 600; font-size: 0.9rem; line-height: 1.2; }
+  .nav-menu__desc { font-size: 0.8rem; color: var(--fg-muted); line-height: 1.35; }
+  .nav-menu__sep { height: 1px; background: var(--border); margin: 0.375rem 0.3rem; }
+  .nav-menu__more { display: inline-flex; padding: 0.4rem 0.7rem; font-size: 0.85rem; font-weight: 600; color: var(--primary); }
+  .nav-menu__more:hover { color: var(--primary-hover); }
+  .apex-dark .nav-menu__trigger { color: var(--on-dark-muted); }
+  .apex-dark .nav-menu__trigger:hover { color: var(--on-dark); }
+`;
+
 export const APEX_STRUCTURAL_CSS =
   BASE_LAYOUT +
   HERO +
@@ -198,4 +237,5 @@ export const APEX_STRUCTURAL_CSS =
   FINAL_CTA +
   CHROME_LIGHT +
   CHROME_DARK +
+  APEX_NAV_MENU_CSS +
   RESPONSIVE;

package/src/apex/index.ts

@@ -7,6 +7,8 @@
 import { escapeHtml } from "../format";
 import { APEX_STRUCTURAL_CSS } from "./css";
 
+export { APEX_NAV_MENU_CSS, APEX_STRUCTURAL_CSS } from "./css";
+
 export type ApexTheme = "light" | "dark";
 
 /** Brand is raw CSS the app owns: the :root token block and optional @font-face.
@@ -28,6 +30,28 @@ export type ApexCta = {
 };
 
 export type ApexLink = { readonly label: string; readonly href: string };
+
+/** One entry inside a dropdown nav menu: icon + title + optional description. */
+export type ApexNavMenuItem = {
+  /** Inner SVG markup (paths), wrapped by the standard 24px icon <svg>. Trusted. */
+  readonly icon?: string;
+  readonly title: string;
+  readonly desc?: string;
+  readonly href: string;
+};
+
+/** A header nav entry that opens a dropdown (icon/title/desc rows) instead of
+ *  navigating. CSS-only: reveals on hover + keyboard focus. */
+export type ApexNavMenu = {
+  readonly kind: "menu";
+  readonly label: string;
+  readonly items: readonly ApexNavMenuItem[];
+  /** Optional link under a divider at the foot of the panel (e.g. "See all →"). */
+  readonly footer?: ApexLink;
+};
+
+/** A header nav entry: a plain link, or a dropdown menu. */
+export type ApexNavEntry = ApexLink | ApexNavMenu;
 export type ApexImage = {
   readonly src: string;
   readonly alt: string;
@@ -37,7 +61,8 @@ export type ApexImage = {
 
 export type ApexHeader = {
   readonly brand: { readonly href: string; readonly label: string; readonly logoSrc?: string };
-  readonly navLinks?: readonly ApexLink[];
+  /** Plain links and/or dropdown menus, in order. */
+  readonly navLinks?: readonly ApexNavEntry[];
   readonly actions?: readonly ApexCta[];
 };
 
@@ -329,12 +354,37 @@ function renderSection(s: ApexSection): string {
   }
 }
 
-function renderHeader(h: ApexHeader): string {
+function renderNavMenu(m: ApexNavMenu): string {
+  const items = m.items
+    .map(
+      (it) =>
+        `<a class="nav-menu__item" href="${escapeHtml(it.href)}">${
+          it.icon !== undefined ? `<span class="nav-menu__icon">${svgIcon(it.icon)}</span>` : ""
+        }<span class="nav-menu__text"><span class="nav-menu__title">${escapeHtml(it.title)}</span>${
+          it.desc !== undefined ? `<span class="nav-menu__desc">${escapeHtml(it.desc)}</span>` : ""
+        }</span></a>`,
+    )
+    .join("");
+  const footer =
+    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" aria-hidden="true">▾</span></button><div class="nav-menu__panel">${items}${footer}</div></div>`;
+}
+
+function renderNavEntry(entry: ApexNavEntry): string {
+  return "items" in entry
+    ? renderNavMenu(entry)
+    : `<a href="${escapeHtml(entry.href)}">${escapeHtml(entry.label)}</a>`;
+}
+
+/** Render just the apex header chrome (brand + nav + actions). Exported so a
+ *  consumer that composes its own page shell (not a full apex page) can reuse
+ *  the identical header — markup stays single-source. */
+export function renderApexHeader(h: ApexHeader): string {
   const logo =
     h.brand.logoSrc !== undefined ? `<img src="${escapeHtml(h.brand.logoSrc)}" alt="" /> ` : "";
-  const navLinks = (h.navLinks ?? [])
-    .map((l) => `<a href="${escapeHtml(l.href)}">${escapeHtml(l.label)}</a>`)
-    .join("\n      ");
+  const navLinks = (h.navLinks ?? []).map(renderNavEntry).join("\n      ");
   const actions = (h.actions ?? []).map(renderCta);
   return `<header>
     <div class="container nav">
@@ -445,7 +495,7 @@ export function renderApexPage(page: ApexPage): string {
     <style>${css}</style>
   </head>
   <body${theme === "dark" ? ` class="apex-dark"` : ""}>
-    ${renderHeader(page.header)}
+    ${renderApexHeader(page.header)}
 
     ${sections}
 

package/src/view-model/__tests__/list.test.ts

@@ -118,6 +118,41 @@ describe("computeListViewModel", () => {
     ).toThrow(/unknown field "doesNotExist"/);
   });
 
+  test("labeled column with no matching field → virtual presentational column (no throw)", () => {
+    const vm = computeListViewModel({
+      screen: listScreen([
+        "title",
+        { field: "tags", label: "Tags", renderer: { react: { __component: "TagsCell" } } },
+      ]),
+      entity: taskEntity,
+      rows: [],
+      translate,
+      featureName: "tasks",
+    });
+    // `field` becomes the column key; label is taken verbatim (translate is
+    // identity here), type defaults to text, never server-sortable.
+    expect(vm.columns[1]).toEqual({
+      field: "tags",
+      label: "Tags",
+      type: "text",
+      sortable: false,
+      renderer: { react: { __component: "TagsCell" } },
+    });
+  });
+
+  test("label overrides the field-convention header on a real field", () => {
+    const vm = computeListViewModel({
+      screen: listScreen([{ field: "title", label: "custom.header" }]),
+      entity: taskEntity,
+      rows: [],
+      translate,
+      featureName: "tasks",
+    });
+    // label goes through translate (identity here) instead of the
+    // tasks:entity:task:field:title convention key.
+    expect(vm.columns[0]?.label).toBe("custom.header");
+  });
+
   test("translate is called with the expected i18n-key per field", () => {
     const spy = mock((key: string) => `T:${key}`);
     computeListViewModel({

package/src/view-model/list.ts

@@ -42,18 +42,31 @@ export function computeListViewModel(input: ComputeListViewModelInput): ListView
       // columns carry no reference/select metadata and never server-sort.
       const derivedDef = entity.derivedFields?.[normalized.field];
       if (!derivedDef) {
-        // Screen references a field that's neither stored nor derived. Fail
-        // loud — the boot-validator (r.screen) should catch this, but a stale
-        // field-rename would leave the screen referring to a ghost column
-        // until ops re-runs boot. We throw so the renderer sees the error
-        // instead of drawing an empty column.
+        // A labeled column with no matching stored/derived field is a *virtual*
+        // presentational column — drawn entirely by a columnRenderer component
+        // from the row (e.g. tag chips); value is undefined and it never
+        // server-sorts. `field` is just the column key. Without a label it's an
+        // author typo (or a stale field-rename) → fail loud so the renderer
+        // doesn't silently draw an empty column.
+        if (normalized.label !== undefined) {
+          columns.push({
+            field: normalized.field,
+            label: translate(normalized.label),
+            type: "text",
+            sortable: false,
+            ...(normalized.renderer !== undefined && { renderer: normalized.renderer }),
+          });
+          continue;
+        }
         throw new Error(
           `computeListViewModel: screen "${screen.id}" references unknown field "${normalized.field}" on entity "${screen.entity}"`,
         );
       }
       columns.push({
         field: normalized.field,
-        label: translate(fieldLabelKey(featureName, screen.entity, normalized.field)),
+        label: translate(
+          normalized.label ?? fieldLabelKey(featureName, screen.entity, normalized.field),
+        ),
         type: derivedDef.valueType,
         // Display-only: a header sort would round-trip to the server, which has
         // no column to sort by (see DerivedFieldDef). Never offer the affordance.
@@ -62,7 +75,9 @@ export function computeListViewModel(input: ComputeListViewModelInput): ListView
       });
       continue;
     }
-    const label = translate(fieldLabelKey(featureName, screen.entity, normalized.field));
+    const label = translate(
+      normalized.label ?? fieldLabelKey(featureName, screen.entity, normalized.field),
+    );
     // Tier 2.7e-3 + Cross-Feature: Reference-Field — entity-String
     // kann same-feature ("user") oder cross-feature ("users:user")
     // sein. parseRefTarget gibt (featureName, entityName), der