@meetreeve/ui 0.2.0

package/dist/index.d.ts

@@ -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 };