@meetreeve/ui 0.2.0

package/README.md

@@ -0,0 +1,134 @@
+# @meetreeve/ui
+
+Shared brand-adaptive UI primitives for MindFortress frontends: design tokens, a favicon→logo→monogram `BrandGlyph`, a `ResponsiveHeader` that keeps the search bar usable on mobile, and `AppSidebar` — a viewport-driven auto-collapse navigation ladder (DEV-4351).
+
+`"use client"` components ship in one bundle (`.`); server-safe design tokens ship separately (`./tokens`, `./tokens.css`) so consumers that don't need the interactive pieces aren't forced into a client boundary.
+
+## Install
+
+```bash
+pnpm add @meetreeve/ui
+# peers: react >=18, react-dom >=18, next >=14, lucide-react >=0.400.0, zod >=3.24.0
+```
+
+## AppSidebar (DEV-4351)
+
+The sidebar for apps with more modules than a short viewport can show at once. It pre-calculates every collapse step (a **ladder**) rather than computing a layout on the fly: as the container shrinks, whole module groups fold into a single hover/click "flyout" row — nothing is ever hidden, just one level deeper.
+
+```tsx
+import { AppSidebar, type AppSidebarModuleDef } from "@meetreeve/ui";
+import { usePathname } from "next/navigation";
+import ladderConfig from "@/config/sidebar-ladder.json";
+import { MODULE_REGISTRY, GROUP_ORDER } from "@/app/_lib/modules";
+
+const modules: AppSidebarModuleDef[] = MODULE_REGISTRY.map((m) => ({
+  moduleId: m.name,
+  label: m.label,
+  icon: m.icon.displayName ?? m.icon.name, // lucide-react export name, e.g. "Mail"
+  group: m.group,
+  href: `/modules/${m.name}`,
+}));
+
+export function Sidebar() {
+  const activePath = usePathname();
+  return (
+    <AppSidebar
+      ladder={ladderConfig} // omit/undefined when no per-tenant config exists yet
+      modules={modules}
+      groupOrder={GROUP_ORDER}
+      activePath={activePath}
+      brand={{ label: "reeve-tenant", href: "/dashboard" }}
+      topItem={{ href: "/dashboard", label: "Overview", icon: "LayoutDashboard" }}
+    />
+  );
+}
+```
+
+### The ladder data model
+
+A `SidebarLadder` is a per-tenant JSON artifact (`src/config/sidebar-ladder.json` by convention) — an ordered list of **rungs**, most-expanded first. Each rung declares every row as either a bare `app` (one module) or a folded `group` (a parent row whose `children` open in a flyout). `rows` strictly decreases rung-over-rung; rung 0 is always the fully-expanded layout (no folded groups).
+
+```ts
+interface SidebarLadder {
+  version: number;
+  rungs: SidebarRung[]; // ordered, most-expanded first
+}
+interface SidebarRung {
+  rows: number; // === items.length
+  items: RungItem[]; // top-to-bottom render order
+}
+type RungItem =
+  | { type: "app"; moduleId: string }
+  | { type: "group"; id: string; label: string; icon: string; children: string[] };
+```
+
+`icon` is a **lucide-react named export string** (e.g. `"Mail"`, `"Layers"`) — the ladder is plain JSON, so it can't carry a component reference; `AppSidebar` resolves the name to a component at render time (falling back to `Layers` if unresolved).
+
+`zSidebarLadder` (exported from `@meetreeve/ui`) enforces every invariant at load: every module appears exactly once per rung (as its own row, or inside exactly one group — never both, never twice); the module set is identical across every rung (folding can't invent or lose a module); group `children` is non-empty; rung 0 has no folded groups.
+
+### No config? No agent output? It still works.
+
+If `ladder` is omitted, `null`, or fails `zSidebarLadder` validation, `AppSidebar` derives a deterministic ladder from `modules` + `groupOrder` (`deriveFallbackLadder`) — folding the **last** group in `groupOrder` first, walking backward. A bad agent-authored config can never brick a tenant's navigation.
+
+A valid-but-stale ladder (modules added/removed since it was authored) is reconciled against the live `modules` list (`reconcileLadder`, exported alongside): an unknown `moduleId` is dropped; a `moduleId` the ladder doesn't reference anywhere is appended as a new top-level row on every rung.
+
+### Rung selection (`useLadderRung`)
+
+`AppSidebar` measures its nav container with `ResizeObserver` and snaps to the largest rung whose `rows` fits `floor(containerHeight / rowHeight)`. Stepping DOWN to a more-folded rung is immediate; stepping back UP requires an extra row of slack (`hysteresisRows`, default 1) so a resize sitting right at a boundary doesn't flap. The hook (and `AppSidebar`'s `ladderOptions` prop) exposes both `rowHeight` and `hysteresisRows` for tuning.
+
+Server renders rung 0; the real rung is selected client-side in `useLayoutEffect`, before paint — no visible snap flash on load.
+
+### Mobile
+
+The ladder itself is desktop-only. Below the `md` breakpoint, `AppSidebar` renders a self-contained hamburger trigger + overlay drawer (no `shadcn`/`Sheet` dependency) showing rung 0 — the full, flat module list — scrollable.
+
+### Folded groups (`Flyout`)
+
+A folded group's row opens a horizontal flyout on hover (desktop) or click (keyboard/touch parity): `aria-expanded` + menu roles, focus moves to the first child on open, Esc closes and returns focus to the trigger. If the active route's module is inside a folded group, the group's own row shows the active state and the flyout highlights the specific child. No open/close transition under `prefers-reduced-motion`.
+
+## ResponsiveHeader
+
+```tsx
+import { ResponsiveHeader } from "@meetreeve/ui";
+
+<ResponsiveHeader
+  brand={{ name: "Cadasense", favicon: "/favicon.ico", logo: null }}
+  search={<SearchInput />}
+  nav={[{ label: "Docs", href: "/docs" }]}
+  auth={<AuthMenu />}
+  themeToggle={<ThemeToggle />}
+/>;
+```
+
+Search is the primary slot — always inline, floored at a minimum width from `@meetreeve/ui/tokens`. Under width pressure everything ELSE collapses first: the wordmark drops to glyph-only, secondary controls fold into a hamburger disclosure below `md`.
+
+## BrandGlyph
+
+```tsx
+import { BrandGlyph } from "@meetreeve/ui";
+
+<BrandGlyph brand={{ name: "Cadasense", favicon: "/favicon.ico", logo: null }} size="lg" />;
+```
+
+Resolution order: favicon → logo → initials monogram.
+
+## Tokens
+
+```ts
+import { MIN_SIZES, BREAKPOINTS } from "@meetreeve/ui/tokens";
+```
+
+```css
+@import "@meetreeve/ui/tokens.css"; /* Tailwind v4 @theme custom properties */
+```
+
+## Development
+
+```bash
+npm install       # this package uses npm, NOT the monorepo's pnpm — see repo root CLAUDE.md
+npm run typecheck
+npm run test
+npm run build
+```
+
+No lint script by design — the quality gate is `typecheck` + `test` + `build`.

package/dist/index.d.mts

@@ -0,0 +1,328 @@
+import * as react from 'react';
+import { ReactNode, RefObject } from 'react';
+import { z } from 'zod';
+
+/**
+ * Brand glyph with a favicon-first cascade (ported/generalised from
+ * DEV-4164's `context/brand-glyph`).
+ *
+ * A tiny square favicon reads far better than a wide wordmark, so we try, in
+ * order:
+ *   1. `brand.favicon` — the site's own square icon,
+ *   2. `brand.logo` rendered `object-contain` (no squish),
+ *   3. a high-contrast letter monogram in a deterministic brand colour.
+ * Each image load error advances to the next candidate.
+ */
+interface Brand {
+    /** Display name — drives the wordmark and the monogram fallback. */
+    name: string;
+    /** Square favicon URL (first cascade step). Use `faviconUrl(domain)` to derive one. */
+    favicon?: string | null;
+    /** Wider brand logo URL (second cascade step, rendered `object-contain`). */
+    logo?: string | null;
+    /** Override the deterministic monogram background colour. */
+    color?: string | null;
+}
+/**
+ * Favicon URL for a brand's canonical domain. Returns null unless `domain`
+ * actually looks like a hostname, so non-domain values (e.g. a plain company
+ * name) skip straight to the logo/monogram steps.
+ */
+declare function faviconUrl(domain: string | null | undefined): string | null;
+interface BrandGlyphProps {
+    brand: Brand;
+    size?: "sm" | "lg";
+    /** Slightly lighter tint behind image sources (e.g. dropdown rows). */
+    subtle?: boolean;
+    className?: string;
+}
+declare function BrandGlyph({ brand, size, subtle, className }: BrandGlyphProps): react.JSX.Element;
+
+interface HeaderNavItem {
+    label: string;
+    href?: string;
+    onSelect?: () => void;
+}
+interface ResponsiveHeaderProps {
+    /** Brand for the glyph + wordmark lockup. */
+    brand: Brand;
+    /**
+     * The PRIMARY slot. Always rendered inline with a guaranteed min-width — it
+     * never collapses to an icon. Give it a full search field.
+     */
+    search: ReactNode;
+    /** Secondary nav links — inline on desktop, in the menu on mobile. */
+    nav?: HeaderNavItem[];
+    /** Auth control (avatar / sign-in) — secondary. */
+    auth?: ReactNode;
+    /** Theme toggle — secondary. */
+    themeToggle?: ReactNode;
+    /** Accessible label for the mobile menu button. */
+    menuLabel?: string;
+    className?: string;
+}
+/**
+ * Brand-adaptive header that fixes the "mobile header crushes the search bar"
+ * class of bug.
+ *
+ * - Search is the primary slot: always inline, floored at `MIN_SIZES.searchInput`.
+ * - Under width pressure the OTHER controls collapse first — below `md` the
+ *   brand wordmark drops to glyph-only and the secondary controls fold into a
+ *   hamburger disclosure. The search is never touched.
+ *
+ * A `"use client"` leaf: it's interactive (matchMedia + disclosure state).
+ */
+declare function ResponsiveHeader({ brand, search, nav, auth, themeToggle, menuLabel, className, }: ResponsiveHeaderProps): react.JSX.Element;
+
+/**
+ * SidebarLadder — the per-tenant JSON artifact (DEV-4351) that pre-calculates
+ * every viewport-driven collapse step for AppSidebar. Agent-authored at spawn
+ * (DEV-4352) or derived deterministically by `deriveFallbackLadder` (see
+ * `./fallback`) when no config exists. The client never invents a layout —
+ * `useLadderRung` only SELECTS a rung from this data.
+ */
+interface AppRungItem {
+    type: "app";
+    moduleId: string;
+}
+interface GroupRungItem {
+    type: "group";
+    /** Stable id for the folded group (also its React key). */
+    id: string;
+    label: string;
+    /** lucide-react named export, e.g. "Layers" — resolved to a component at render time. */
+    icon: string;
+    /** moduleIds folded into this group. Non-empty (zod-enforced). */
+    children: string[];
+}
+type RungItem = AppRungItem | GroupRungItem;
+interface SidebarRung {
+    /** Row count for this rung. Always equals `items.length` (zod-enforced) —
+     *  each item, whether a bare app row or a folded group, is exactly one row. */
+    rows: number;
+    /** Top-to-bottom render order. */
+    items: RungItem[];
+}
+interface SidebarLadder {
+    version: number;
+    /** Ordered rungs, most-expanded first. Rung 0 is always the fully-expanded
+     *  layout (no folded groups); `rows` strictly decreases thereafter. */
+    rungs: SidebarRung[];
+}
+/**
+ * SidebarLadder zod schema — enforces every invariant from the DEV-4351 spec:
+ *  - rung 0 is fully expanded (no folded groups — every item is an app row).
+ *  - `rows` strictly decreases rung-over-rung.
+ *  - a rung's declared `rows` matches its actual item count.
+ *  - group `children` is non-empty (covered at the item level above).
+ *  - every module appears EXACTLY ONCE per rung (as a row, or inside exactly
+ *    one group's children — never both, never twice).
+ *  - the set of modules is identical across every rung — folding can never
+ *    invent or lose a module.
+ */
+declare const zSidebarLadder: z.ZodObject<{
+    version: z.ZodNumber;
+    rungs: z.ZodArray<z.ZodObject<{
+        rows: z.ZodNumber;
+        items: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"app">;
+            moduleId: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"group">;
+            id: z.ZodString;
+            label: z.ZodString;
+            icon: z.ZodString;
+            children: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>], "type">>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type SidebarLadderParsed = z.infer<typeof zSidebarLadder>;
+
+interface UseLadderRungOptions {
+    /** Approximate rendered height of one nav row, px. */
+    rowHeight?: number;
+    /** Extra rows of slack required before stepping back UP to a less-folded
+     *  rung, so a resize sitting right at a boundary doesn't flap. */
+    hysteresisRows?: number;
+}
+/**
+ * Measures a nav container via ResizeObserver and selects the largest ladder
+ * rung (rungs are ordered most-expanded first, `rows` strictly decreasing)
+ * whose row requirement fits `rowsAvailable = floor(height / rowHeight)`.
+ *
+ * SSR-safe: the initial state is always rung 0 (fully expanded) — the
+ * measurement only runs client-side inside `useLayoutEffect`, which fires
+ * before the browser paints, so there's no visible rung-snap flash on first
+ * load (server markup and the first client paint agree).
+ *
+ * Hysteresis: stepping DOWN to a more-folded rung happens the instant it no
+ * longer fits. Stepping back UP to a less-folded rung requires an EXTRA
+ * `hysteresisRows` of slack beyond that rung's own row requirement, so a
+ * resize hovering right at a boundary doesn't flip back and forth.
+ */
+declare function useLadderRung(ladder: SidebarLadder, containerRef: RefObject<HTMLElement | null>, options?: UseLadderRungOptions): SidebarRung;
+
+interface AppSidebarModuleDef {
+    moduleId: string;
+    label: string;
+    /** lucide-react named export, e.g. "Mail". */
+    icon: string;
+    group: string;
+    href: string;
+}
+interface AppSidebarBrand {
+    label: string;
+    href: string;
+}
+interface AppSidebarTopItem {
+    href: string;
+    label: string;
+    /** lucide-react named export. */
+    icon: string;
+}
+interface AppSidebarProps {
+    /** Raw, parsed (but not yet zod-validated) sidebar-ladder.json — or
+     *  `undefined`/`null` when no per-tenant config exists. A ladder that fails
+     *  validation degrades to the deterministic fallback, same as no config. */
+    ladder?: unknown;
+    /** The full module catalog — resolves each row's label/icon/href and
+     *  drives the fallback derivation when no ladder config is supplied. */
+    modules: AppSidebarModuleDef[];
+    /** Group fold order — the LAST group folds first (fallback derivation +
+     *  drift reconciliation both use this). */
+    groupOrder: string[];
+    /** Current pathname — drives the active-route highlight. */
+    activePath: string;
+    /** Brand block rendered above the ladder. */
+    brand?: AppSidebarBrand;
+    /** A fixed nav row above the ladder, unaffected by rung folding (e.g. an "Overview" link). */
+    topItem?: AppSidebarTopItem;
+    /** Accessible label for the mobile hamburger button. */
+    menuLabel?: string;
+    ladderOptions?: UseLadderRungOptions;
+    /** Merged onto the desktop `<aside>` itself — there is no extra wrapping
+     *  element (see the render note below on why that matters for height). */
+    className?: string;
+}
+/**
+ * AppSidebar (DEV-4351) — the viewport-driven auto-collapse ladder sidebar.
+ *
+ * Desktop: measures its nav container and snaps to the largest ladder rung
+ * that fits (see `useLadderRung`); folded groups render as a `Flyout`.
+ * Mobile: the ladder is desktop-only — a self-contained hamburger + overlay
+ * drawer renders rung 0 (fully expanded), scrollable. No shadcn/Sheet
+ * dependency, matching ResponsiveHeader's existing disclosure pattern in
+ * this same package.
+ */
+declare function AppSidebar({ ladder, modules, groupOrder, activePath, brand, topItem, menuLabel, ladderOptions, className, }: AppSidebarProps): react.JSX.Element;
+
+/**
+ * Minimal shape AppSidebar's fallback derivation needs from a module registry
+ * entry — deliberately decoupled from any one app's full module-def shape
+ * (label/icon/description live in the consumer's own registry and are
+ * resolved at render time by AppSidebar, not baked into the ladder here).
+ */
+interface FallbackModuleDef {
+    moduleId: string;
+    group: string;
+}
+/**
+ * Deterministic ladder derivation for when `sidebar-ladder.json` is absent or
+ * fails zod validation — a bad agent output can never brick a tenant's nav.
+ *
+ * Rung 0 is the fully-expanded layout (one row per module, registry order
+ * preserved). Each subsequent rung folds one more group into a single parent
+ * row, walking `groupOrder` BACK TO FRONT — the LAST group folds first (e.g.
+ * for Engage/Data/Intelligence/Commerce/Operations, Operations folds first,
+ * then Commerce, then Intelligence, then Data, then Engage last).
+ *
+ * A group with fewer than 2 members is folded into the accumulated set
+ * without emitting its own rung — collapsing a 1-member group nets zero row
+ * reduction (one app row becomes one group row), which would violate the
+ * ladder's strictly-decreasing-rows invariant if emitted as its own step. It
+ * still gets folded — just bundled into the rung of whichever fold next
+ * produces a real row-count decrease.
+ */
+declare function deriveFallbackLadder(registry: FallbackModuleDef[], groupOrder: string[]): SidebarLadder;
+/**
+ * Reconciles a (possibly stale) ladder against the live registry — mirrors
+ * `use-sidebar-config.ts`'s `reconcileConfig()` (unknown ids dropped, missing
+ * ids appended). Ladder/registry drift can never brick or hide a module:
+ *  - a moduleId the ladder references but the registry no longer has is
+ *    dropped from every rung (and from any group's children).
+ *  - a moduleId the registry has but the ladder doesn't reference anywhere in
+ *    rung 0 is appended as a new top-level row on EVERY rung.
+ */
+declare function reconcileLadder(ladder: SidebarLadder, registry: FallbackModuleDef[]): SidebarLadder;
+/**
+ * The single entry point AppSidebar uses to resolve the ladder it will
+ * render: validate the raw (parsed-JSON) ladder if one was supplied,
+ * reconcile it against the live registry, and fall back to a fresh
+ * deterministic derivation on absence OR validation failure.
+ *
+ * The reconciled result is re-validated against `zSidebarLadder` before it's
+ * returned (deep-review finding, DEV-4351): `reconcileLadder`'s per-rung
+ * filtering can — on a specific drift shape (dropping enough of a folded
+ * group's members that a rung's row count converges with its neighbor's) —
+ * produce a ladder that no longer satisfies the strictly-decreasing-rows
+ * invariant, which would silently orphan a rung in `useLadderRung`'s
+ * first-fit scan. A bad reconciliation degrades to the same deterministic
+ * fallback as a bad or missing config — it never ships invalid output.
+ */
+declare function resolveLadder(raw: unknown, registry: FallbackModuleDef[], groupOrder: string[]): SidebarLadder;
+
+interface FlyoutChild {
+    moduleId: string;
+    label: string;
+    href: string;
+    active: boolean;
+}
+interface FlyoutProps {
+    label: string;
+    /** lucide-react named export, e.g. "Layers". */
+    icon: string;
+    /** True when the active route's module is folded inside this group — the
+     *  PARENT row shows the active state; the child itself is highlighted via
+     *  its own `active` flag. */
+    active: boolean;
+    children: FlyoutChild[];
+    className?: string;
+}
+/**
+ * The "offshoot" for a folded sidebar group (DEV-4351): hover opens a
+ * horizontal flyout listing the group's children on desktop; click toggles it
+ * for keyboard/touch parity. `aria-expanded`, focus moves into the panel on
+ * a CLICK/keyboard open (never on a mere hover — CR CLI finding), Esc closes
+ * and returns focus to the trigger — via the shared `useDismissableDisclosure`
+ * (mirrors ResponsiveHeader's original mobile-disclosure a11y pattern in this
+ * same package).
+ *
+ * Plain links, not `menu`/`menuitem` roles (CR CLI finding): those ARIA roles
+ * promise a roving-tabindex, arrow-key/Home/End keyboard contract this
+ * disclosure doesn't implement — misusing them would announce a keyboard
+ * model to assistive tech that isn't actually there. Native `<a>` Tab
+ * navigation is fully accessible on its own without that promise.
+ *
+ * Hover and click are independent open sources (CR CLI finding): they used
+ * to share one boolean, so a mouse user hovering (which opened it) and then
+ * clicking the row — the normal way to interact with it — immediately
+ * toggled it closed again. `hoverOpen`/`clickOpen` are now tracked
+ * separately; the panel shows while EITHER is true, and only a click/
+ * keyboard-driven open moves focus into it.
+ *
+ * The panel is positioned `position: fixed` at the trigger's actual screen
+ * coordinates, not CSS-anchored (`absolute; left: 100%`) to its nearest
+ * positioned ancestor (outcome-eval finding, live browser check): that
+ * ancestor sits inside AppSidebar's `<nav>`, which has `overflow-y: auto` —
+ * a CSS quirk auto-promotes the OTHER axis to `overflow-x: auto` too, so an
+ * `absolute`-positioned panel extending past the narrow sidebar's edge
+ * inflated the nav's own scrollWidth, and the browser auto-scrolled the nav
+ * horizontally to reveal it — hiding every OTHER nav item off-screen.
+ * `position: fixed` doesn't contribute to any scrolling ancestor's
+ * scrollable overflow at all, so it escapes the problem entirely rather
+ * than working around it. jsdom never computes real scrollable-overflow
+ * geometry, so no unit test caught this — only an actual browser render did.
+ */
+declare function Flyout({ label, icon, active, children, className }: FlyoutProps): react.JSX.Element;
+
+export { type AppRungItem, AppSidebar, type AppSidebarBrand, type AppSidebarModuleDef, type AppSidebarProps, type AppSidebarTopItem, type Brand, BrandGlyph, type BrandGlyphProps, type FallbackModuleDef, Flyout, type FlyoutChild, type FlyoutProps, type GroupRungItem, type HeaderNavItem, ResponsiveHeader, type ResponsiveHeaderProps, type RungItem, type SidebarLadder, type SidebarLadderParsed, type SidebarRung, type UseLadderRungOptions, deriveFallbackLadder, faviconUrl, reconcileLadder, resolveLadder, useLadderRung, zSidebarLadder };