@marktiderman/genesis-ui 2.3.0 → 2.4.0

package/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: genesis-ui
+description: Build web UI with the Genesis design system (@marktiderman/genesis-ui) — pick the right rung (pattern, slots, primitives, hooks), import by subpath, theme from a brand. Load before writing any page, list, form or dashboard on Genesis.
+---
+
+# genesis-ui
+
+Genesis is a starting point, not a ceiling. **Reuse > Extend > Create**: before
+writing a component, find the export that already answers the question, then
+step down the ladder one rung — never off it.
+
+## The ladder
+
+Every pattern offers four rungs. Take the highest that fits.
+
+**1 · The pattern** — the whole page, wired.
+
+```tsx
+<ResourcePage title="Questions" resource="questions" columns={["title"]} />
+```
+
+**2 · `slots` / `slotProps`** — keep the wiring, change one part. `null` ejects a part.
+
+```tsx
+<ResourcePage
+  title="Questions"
+  slots={{ filters: MyFilters, bulkBar: null }} // replace a part, or drop it
+  slotProps={{ table: { className: "text-xs" } }} // or feed it more props — wins over ours
+/>
+```
+
+**3 · The primitives** — compose the page yourself from Genesis parts.
+
+```tsx
+<DataPageShell title="Questions" filters={<DataFilters … />}>
+  <DataTable … />
+</DataPageShell>
+```
+
+**4 · The hook** — all of the logic, none of the markup.
+
+```tsx
+const page = useResourcePage({ … }); // state, paging, selection, sorting
+return <WhateverYouWant {...page} />;
+```
+
+Dropping to rung 3 because one part was wrong re-derives wiring that was
+already right; that re-derivation is where forks come from. Reach for rung 2
+first. When the app hand-builds something Genesis nearly had, that is a bug
+report against Genesis (`packages/ui/EXTENDING.md`), not a reason to fork.
+
+## The layer contract (docs/FRAMEWORK.md)
+
+1. Layers: tokens → primitives → patterns → layouts → data-bound; each depends downward only.
+2. A primitive does one interaction and knows no domain words; a pattern composes primitives.
+3. A layout positions things without knowing what they are; it carries no domain and no data.
+4. Data-bound components need a resource contract (`DataProvider`); nothing else fetches.
+5. Capability ships additively; removals ship as a deprecated alias until the next major.
+
+## Reach for this first
+
+| You need                                                      | Use                                                                                | Import from                                                       |
+| ------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| App skeleton: nav, header, content                            | `AppShell`                                                                         | `@marktiderman/genesis-ui/layout`                                 |
+| Page title row with count, view toggle, options               | `PageHeader` (+ `options.configurable` for the in-header options popover)          | `/layout`                                                         |
+| List page chrome: header, filters, loading/empty/error        | `DataPageShell` (`stats`, `filters` slots)                                         | `/data`                                                           |
+| A whole CRUD list page over a resource                        | `ResourcePage`                                                                     | `/data`                                                           |
+| Record detail side panel                                      | `DetailPanel`                                                                      | `/data`                                                           |
+| Dashboard / settings / form / detail page shape               | `DashboardPage`, `SettingsPage`, `FormPage`, `DetailPage`                          | `/dashboard-page`, `/settings-page`, `/form-page`, `/detail-page` |
+| KPI tile                                                      | `StatCard`                                                                         | `/data`                                                           |
+| Table cells: dates, numbers, money, badges, links, thumbnails | `DateCell`, `NumberCell`, `CurrencyCell`, `BadgeCell`, `LinkCell`, `ThumbnailCell` | `/data`                                                           |
+| Search, sort, filters, status chips/tabs, saved views         | `DataFilters`                                                                      | `/data`                                                           |
+| Create/edit form bound to a resource                          | `ResourceForm` / `useResourceForm`                                                 | `/data` / `@marktiderman/genesis-core/hooks`                      |
+| Nothing-here state with optional clear-filters                | `EmptyState`                                                                       | `/empty-state`                                                    |
+| Settings list rows                                            | `SettingsRow`, `ToggleRow`                                                         | `/settings-row`, `/toggle-row`                                    |
+| Cmd-K palette                                                 | `CommandPalette`, `useCommandPaletteHotkey`                                        | `/command-palette`                                                |
+| Arrow-key list navigation                                     | `useKeyboardNavigation`                                                            | `/hooks/use-keyboard-navigation`                                  |
+| Persisted page size / density                                 | `useViewSettings`                                                                  | `/hooks/use-view-settings`                                        |
+
+## Import rule
+
+Import by subpath, never the root barrel in app code: `@marktiderman/genesis-ui/button`,
+`/card`, `/data`, `/layout`. The root barrel drags every component and peer dependency into
+the bundle. Hooks are `@marktiderman/genesis-ui/hooks/<file>` (e.g. `/hooks/use-view-settings`),
+not `/hooks`. Never import from the legacy `@genesis/*` scope.
+
+## Theming
+
+Tokens come from `@marktiderman/genesis-design-system`. A Tailwind v4 web app imports, in
+order: `tailwindcss`, then `@marktiderman/genesis-design-system/themes/genesis.css` (the
+semantic variables), then `.../themes/genesis-tailwind4.css` (the `@theme inline` bridge that
+turns them into `bg-primary`, `font-sans` and the rest, plus the `.dark` class variant). Do not
+hand-write that bridge, and do not use `presets/tailwind`: it is a v3-shaped JS preset. Override
+fonts or colours in an unlayered `:root` after the imports, not in `@theme`, since genesis.css
+wins over `@layer theme`. `tailwindFromBrand(brand).css` adds brand ramps
+(`--color-neutral-500` and the like) on top. Components reference only semantic tokens
+(`bg-primary`, `text-muted-foreground`), never raw colours.
+
+## Full inventory
+
+`docs/component-reference.md` lists every export with its props and stability tag. It is
+generated (`pnpm gen:component-reference`); do not edit it by hand.
+
+## Wiring into an app
+
+**Tailwind class scanning.** Tailwind v4 skips git-ignored paths such as `node_modules`, so genesis-ui's classes
+are missing unless the app points at them. Import the shipped source entry — never hardcode an
+`@source` path into `node_modules`:
+
+```css
+@import "tailwindcss";
+@import "@marktiderman/genesis-ui/styles.css"; /* = @source over the package's dist/ */
+```
+
+**Active nav items with `?query` / `#hash`.** Pass the full location as `activePath`
+(`pathname + search + hash`). Plain items still match on the path; an item whose `to` carries a
+query or hash (`/admin?tab=users`, `/settings#profile`) is active only when those match too.
+Do not write a custom `isActive` for this. `isPathActive(to, activePath, { end: true })` is the
+exact-path variant.
+
+**Hierarchical "up" navigation.** Describe the logical hierarchy once as a `NavigationNode` tree
+and call `resolveNavigation(tree, pathname)` from the root barrel or `/data`. It returns
+`{ current, parent, items, trail, params }` with every path interpolated from the URL's params.
+Use `parent` for a back-to-parent link and `items` for contextual nav — never `history.back()`.
+
+```ts
+const nav = resolveNavigation(
+  { id: "app", path: "/app", label: "Home", items: globalItems, children: [
+    { id: "clients", path: "/dashboard", label: "Clients", items: [], children: [
+      { id: "client", path: "/clients/$clientId", label: "Client", items: clientItems },
+    ] },
+  ] },
+  pathname,
+);
+// pathname "/clients/c1/tasks" → nav.current.id "client", nav.parent.path "/dashboard",
+// nav.params { clientId: "c1" }
+```

package/dist/{AppShell-D_E_Hk4g.d.ts → AppShell-CX0M-dfc.d.ts}

@@ -3,7 +3,7 @@ import { ReactNode } from 'react';
 import { LucideIcon } from 'lucide-react';
 import { V as ViewMode } from './view-toggle-CahQ87PW.js';
 import { Density } from './hooks/use-view-settings.js';
-import { L as LinkComponent } from './navigation-CpOEyUSb.js';
+import { L as LinkComponent } from './navigation-DBwcZ6vb.js';
 
 /**
  * Declarative chrome for PageHeader — developer defaults + optional
@@ -18,6 +18,12 @@ interface PageHeaderOptions {
     showViewToggle?: boolean;
     showViewSettings?: boolean;
     showCreate?: boolean;
+    /**
+     * Stat cards row under the title block. Off by default — a header that
+     * receives `stats` still hides them until the developer or the user turns
+     * this on, so an existing page gains no new chrome by upgrading.
+     */
+    showStats?: boolean;
     /** Ghost ListFilter control in the actions cluster */
     showDetailsToggle?: boolean;
     /** Quiet hint beside actions while details are collapsed */
@@ -56,6 +62,13 @@ interface PageHeaderProps {
     optionsStorageKey?: string;
     /** Extra trailing actions (after create); prefer first-class slots below */
     actions?: ReactNode;
+    /**
+     * Stat cards row, full width, directly under the title block and above
+     * `details`. Layout-only: pass `<StatCard>`s (or anything else) and the
+     * header positions them. Rendered only when `options.showStats` resolves
+     * true — see {@link PageHeaderOptions.showStats}.
+     */
+    stats?: ReactNode;
     /** Collapsible details region below the title row */
     details?: ReactNode;
     detailsOpen?: boolean;
@@ -90,7 +103,7 @@ interface PageHeaderProps {
      */
     secondaryActions?: PageHeaderAction[];
 }
-declare function PageHeader({ title, subtitle, icon: Icon, options: optionsProp, optionsStorageKey, actions, details, detailsOpen, onDetailsOpenChange, detailsActive, detailsHint, count, totalCount, entityName, countActive, viewMode, onViewModeChange, pageSize, onPageSizeChange, density, onDensityChange, createAction, secondaryActions, }: PageHeaderProps): React.JSX.Element;
+declare function PageHeader({ title, subtitle, icon: Icon, options: optionsProp, optionsStorageKey, actions, stats, details, detailsOpen, onDetailsOpenChange, detailsActive, detailsHint, count, totalCount, entityName, countActive, viewMode, onViewModeChange, pageSize, onPageSizeChange, density, onDensityChange, createAction, secondaryActions, }: PageHeaderProps): React.JSX.Element;
 
 interface NavItem {
     to: string;
@@ -100,7 +113,10 @@ interface NavItem {
     children?: NavItem[];
     badge?: string | number;
     disabled?: boolean;
-    /** Exact-match active state (e.g. overview `/`) */
+    /**
+     * Exact-match active state (e.g. overview `/`). Exact on the path only, so
+     * an `activePath` carrying `?search#hash` still matches.
+     */
     end?: boolean;
 }
 /**
@@ -207,9 +223,11 @@ interface AppShellProps {
      */
     linkComponent?: LinkComponent;
     /**
-     * Current path used to highlight the active nav item. Router consumers pass
-     * `useLocation().pathname` (RR) or `usePathname()` (Next). Omit to disable
-     * active highlighting.
+     * Current location used to highlight the active nav item. Pass the full
+     * location, `pathname + search + hash` (React Router: `useLocation()`), so
+     * items whose `to` names a query or hash (`/admin?tab=users`) can become
+     * active. A pathname alone still works for path-only items, `end` included.
+     * Omit to disable active highlighting.
      */
     activePath?: string;
     /**

package/dist/chunk-CDYZRZ6U.js

@@ -0,0 +1,141 @@
+"use client";
+import { useState, useEffect, useCallback } from 'react';
+import { jsx } from 'react/jsx-runtime';
+
+// src/navigation.tsx
+var DefaultLink = ({
+  href,
+  children,
+  testID,
+  ...rest
+}) => /* @__PURE__ */ jsx("a", { href, "data-testid": testID, ...rest, children });
+function splitHref(href) {
+  const hashAt = href.indexOf("#");
+  const hash = hashAt === -1 ? "" : href.slice(hashAt + 1);
+  const beforeHash = hashAt === -1 ? href : href.slice(0, hashAt);
+  const searchAt = beforeHash.indexOf("?");
+  const rawPath = searchAt === -1 ? beforeHash : beforeHash.slice(0, searchAt);
+  return {
+    path: rawPath.length > 1 ? rawPath.replace(/\/+$/, "") || "/" : rawPath,
+    search: searchAt === -1 ? "" : beforeHash.slice(searchAt + 1),
+    hash
+  };
+}
+function isPathActive(to, activePath, options) {
+  if (activePath == null) return false;
+  if (to === activePath) return true;
+  const target = splitHref(to);
+  const current = splitHref(activePath);
+  if (!target.search && !target.hash) {
+    if (target.path === current.path) return true;
+    if (options?.end) return false;
+    return target.path !== "/" && current.path.startsWith(target.path + "/");
+  }
+  if (target.path !== current.path) return false;
+  if (target.hash && target.hash !== current.hash) return false;
+  if (target.search) {
+    const want = new URLSearchParams(target.search);
+    const have = new URLSearchParams(current.search);
+    for (const key of new Set(want.keys())) {
+      const wanted = want.getAll(key);
+      const had = have.getAll(key);
+      if (!wanted.every((value) => had.includes(value))) return false;
+    }
+  }
+  return true;
+}
+function pathSegments(path) {
+  return splitHref(path).path.split("/").filter(Boolean);
+}
+function decodeSegment(segment) {
+  try {
+    return decodeURIComponent(segment);
+  } catch {
+    return segment;
+  }
+}
+function resolveNavigation(tree, pathname) {
+  const segments = pathSegments(pathname).map(decodeSegment);
+  const matches = (pattern) => pattern.length <= segments.length && pattern.every(
+    (part, i) => part.startsWith("$") || decodeSegment(part) === segments[i]
+  );
+  const compare = (a, b) => {
+    const shared = Math.min(a.pattern.length, b.pattern.length);
+    for (let i = 0; i < shared; i++) {
+      const aParam = a.pattern[i].startsWith("$");
+      const bParam = b.pattern[i].startsWith("$");
+      if (aParam !== bParam) return aParam ? -1 : 1;
+    }
+    if (a.pattern.length !== b.pattern.length) {
+      return a.pattern.length - b.pattern.length;
+    }
+    return a.trail.length - b.trail.length;
+  };
+  let best;
+  const visit = (node, ancestors) => {
+    const trail2 = [...ancestors, node];
+    const pattern = pathSegments(node.path);
+    if (matches(pattern)) {
+      const candidate = { trail: trail2, pattern };
+      if (!best || compare(candidate, best) > 0) best = candidate;
+    }
+    for (const child of node.children ?? []) visit(child, trail2);
+  };
+  visit(tree, []);
+  const winner = best ?? { trail: [tree], pattern: [] };
+  const params = {};
+  winner.pattern.forEach((part, i) => {
+    if (part.startsWith("$")) params[part.slice(1)] = segments[i];
+  });
+  const interpolate = (node) => ({
+    ...node,
+    path: node.path.split("/").map((part) => {
+      if (!part.startsWith("$")) return part;
+      const value = params[part.slice(1)];
+      return value == null ? part : encodeURIComponent(value);
+    }).join("/")
+  });
+  const trail = winner.trail.map(interpolate);
+  const current = trail[trail.length - 1];
+  return {
+    current,
+    parent: trail.length > 1 ? trail[trail.length - 2] : void 0,
+    items: current.items,
+    trail,
+    params
+  };
+}
+var defaultNavigate = (path) => {
+  if (typeof window !== "undefined") window.location.assign(path);
+};
+function useBrowserSearchParams() {
+  const read = () => new URLSearchParams(
+    typeof window !== "undefined" ? window.location.search : ""
+  );
+  const [searchParams, setLocal] = useState(read);
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+    const onPop = () => setLocal(read());
+    window.addEventListener("popstate", onPop);
+    return () => window.removeEventListener("popstate", onPop);
+  }, []);
+  const setSearchParams = useCallback(
+    (next, options) => {
+      if (typeof window === "undefined") return;
+      const qs = next.toString();
+      const url = window.location.pathname + (qs ? `?${qs}` : "") + window.location.hash;
+      if (options?.replace) {
+        window.history.replaceState(window.history.state, "", url);
+      } else {
+        window.history.pushState(window.history.state, "", url);
+      }
+      setLocal(new URLSearchParams(next));
+    },
+    []
+  );
+  return { searchParams, setSearchParams };
+}
+
+export { DefaultLink, defaultNavigate, isPathActive, resolveNavigation, useBrowserSearchParams };
+//# sourceMappingURL=chunk-CDYZRZ6U.js.map
+//# sourceMappingURL=chunk-CDYZRZ6U.js.map

package/dist/chunk-CDYZRZ6U.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/navigation.tsx"],"names":["trail"],"mappings":";;;;AAgEO,IAAM,cAA6B,CAAC;AAAA,EACzC,IAAA;AAAA,EACA,QAAA;AAAA,EACA,MAAA;AAAA,EACA,GAAG;AACL,CAAA,yBACG,GAAA,EAAA,EAAE,IAAA,EAAY,eAAa,MAAA,EAAS,GAAG,MACrC,QAAA,EACH;AAOF,SAAS,UAAU,IAAA,EAA8D;AAC/E,EAAA,MAAM,MAAA,GAAS,IAAA,CAAK,OAAA,CAAQ,GAAG,CAAA;AAC/B,EAAA,MAAM,OAAO,MAAA,KAAW,EAAA,GAAK,KAAK,IAAA,CAAK,KAAA,CAAM,SAAS,CAAC,CAAA;AACvD,EAAA,MAAM,aAAa,MAAA,KAAW,EAAA,GAAK,OAAO,IAAA,CAAK,KAAA,CAAM,GAAG,MAAM,CAAA;AAC9D,EAAA,MAAM,QAAA,GAAW,UAAA,CAAW,OAAA,CAAQ,GAAG,CAAA;AACvC,EAAA,MAAM,UAAU,QAAA,KAAa,EAAA,GAAK,aAAa,UAAA,CAAW,KAAA,CAAM,GAAG,QAAQ,CAAA;AAC3E,EAAA,OAAO;AAAA,IACL,IAAA,EAAM,QAAQ,MAAA,GAAS,CAAA,GAAI,QAAQ,OAAA,CAAQ,MAAA,EAAQ,EAAE,CAAA,IAAK,GAAA,GAAM,OAAA;AAAA,IAChE,QAAQ,QAAA,KAAa,EAAA,GAAK,KAAK,UAAA,CAAW,KAAA,CAAM,WAAW,CAAC,CAAA;AAAA,IAC5D;AAAA,GACF;AACF;AA2BO,SAAS,YAAA,CACd,EAAA,EACA,UAAA,EACA,OAAA,EACS;AACT,EAAA,IAAI,UAAA,IAAc,MAAM,OAAO,KAAA;AAC/B,EAAA,IAAI,EAAA,KAAO,YAAY,OAAO,IAAA;AAC9B,EAAA,MAAM,MAAA,GAAS,UAAU,EAAE,CAAA;AAC3B,EAAA,MAAM,OAAA,GAAU,UAAU,UAAU,CAAA;AAEpC,EAAA,IAAI,CAAC,MAAA,CAAO,MAAA,IAAU,CAAC,OAAO,IAAA,EAAM;AAClC,IAAA,IAAI,MAAA,CAAO,IAAA,KAAS,OAAA,CAAQ,IAAA,EAAM,OAAO,IAAA;AACzC,IAAA,IAAI,OAAA,EAAS,KAAK,OAAO,KAAA;AACzB,IAAA,OAAO,MAAA,CAAO,SAAS,GAAA,IAAO,OAAA,CAAQ,KAAK,UAAA,CAAW,MAAA,CAAO,OAAO,GAAG,CAAA;AAAA,EACzE;AAEA,EAAA,IAAI,MAAA,CAAO,IAAA,KAAS,OAAA,CAAQ,IAAA,EAAM,OAAO,KAAA;AACzC,EAAA,IAAI,OAAO,IAAA,IAAQ,MAAA,CAAO,IAAA,KAAS,OAAA,CAAQ,MAAM,OAAO,KAAA;AACxD,EAAA,IAAI,OAAO,MAAA,EAAQ;AACjB,IAAA,MAAM,IAAA,GAAO,IAAI,eAAA,CAAgB,MAAA,CAAO,MAAM,CAAA;AAC9C,IAAA,MAAM,IAAA,GAAO,IAAI,eAAA,CAAgB,OAAA,CAAQ,MAAM,CAAA;AAC/C,IAAA,KAAA,MAAW,OAAO,IAAI,GAAA,CAAI,IAAA,CAAK,IAAA,EAAM,CAAA,EAAG;AACtC,MAAA,MAAM,MAAA,GAAS,IAAA,CAAK,MAAA,CAAO,GAAG,CAAA;AAC9B,MAAA,MAAM,GAAA,GAAM,IAAA,CAAK,MAAA,CAAO,GAAG,CAAA;AAC3B,MAAA,IAAI,CAAC,MAAA,CAAO,KAAA,CAAM,CAAC,KAAA,KAAU,IAAI,QAAA,CAAS,KAAK,CAAC,CAAA,EAAG,OAAO,KAAA;AAAA,IAC5D;AAAA,EACF;AACA,EAAA,OAAO,IAAA;AACT;AA2CA,SAAS,aAAa,IAAA,EAAwB;AAC5C,EAAA,OAAO,SAAA,CAAU,IAAI,CAAA,CAAE,IAAA,CAAK,MAAM,GAAG,CAAA,CAAE,OAAO,OAAO,CAAA;AACvD;AAEA,SAAS,cAAc,OAAA,EAAyB;AAC9C,EAAA,IAAI;AACF,IAAA,OAAO,mBAAmB,OAAO,CAAA;AAAA,EACnC,CAAA,CAAA,MAAQ;AACN,IAAA,OAAO,OAAA;AAAA,EACT;AACF;AAkBO,SAAS,iBAAA,CACd,MACA,QAAA,EACuB;AAGvB,EAAA,MAAM,QAAA,GAAW,YAAA,CAAa,QAAQ,CAAA,CAAE,IAAI,aAAa,CAAA;AAGzD,EAAA,MAAM,UAAU,CAAC,OAAA,KACf,QAAQ,MAAA,IAAU,QAAA,CAAS,UAC3B,OAAA,CAAQ,KAAA;AAAA,IACN,CAAC,IAAA,EAAM,CAAA,KAAM,IAAA,CAAK,UAAA,CAAW,GAAG,CAAA,IAAK,aAAA,CAAc,IAAI,CAAA,KAAM,QAAA,CAAS,CAAC;AAAA,GACzE;AAMF,EAAA,MAAM,OAAA,GAAU,CAAC,CAAA,EAAU,CAAA,KAAqB;AAC9C,IAAA,MAAM,MAAA,GAAS,KAAK,GAAA,CAAI,CAAA,CAAE,QAAQ,MAAA,EAAQ,CAAA,CAAE,QAAQ,MAAM,CAAA;AAC1D,IAAA,KAAA,IAAS,CAAA,GAAI,CAAA,EAAG,CAAA,GAAI,MAAA,EAAQ,CAAA,EAAA,EAAK;AAC/B,MAAA,MAAM,SAAS,CAAA,CAAE,OAAA,CAAQ,CAAC,CAAA,CAAG,WAAW,GAAG,CAAA;AAC3C,MAAA,MAAM,SAAS,CAAA,CAAE,OAAA,CAAQ,CAAC,CAAA,CAAG,WAAW,GAAG,CAAA;AAC3C,MAAA,IAAI,MAAA,KAAW,MAAA,EAAQ,OAAO,MAAA,GAAS,EAAA,GAAK,CAAA;AAAA,IAC9C;AACA,IAAA,IAAI,CAAA,CAAE,OAAA,CAAQ,MAAA,KAAW,CAAA,CAAE,QAAQ,MAAA,EAAQ;AACzC,MAAA,OAAO,CAAA,CAAE,OAAA,CAAQ,MAAA,GAAS,CAAA,CAAE,OAAA,CAAQ,MAAA;AAAA,IACtC;AACA,IAAA,OAAO,CAAA,CAAE,KAAA,CAAM,MAAA,GAAS,CAAA,CAAE,KAAA,CAAM,MAAA;AAAA,EAClC,CAAA;AAEA,EAAA,IAAI,IAAA;AACJ,EAAA,MAAM,KAAA,GAAQ,CAAC,IAAA,EAAyB,SAAA,KAAmC;AACzE,IAAA,MAAMA,MAAAA,GAAQ,CAAC,GAAG,SAAA,EAAW,IAAI,CAAA;AACjC,IAAA,MAAM,OAAA,GAAU,YAAA,CAAa,IAAA,CAAK,IAAI,CAAA;AACtC,IAAA,IAAI,OAAA,CAAQ,OAAO,CAAA,EAAG;AACpB,MAAA,MAAM,SAAA,GAAY,EAAE,KAAA,EAAAA,MAAAA,EAAO,OAAA,EAAQ;AACnC,MAAA,IAAI,CAAC,IAAA,IAAQ,OAAA,CAAQ,WAAW,IAAI,CAAA,GAAI,GAAG,IAAA,GAAO,SAAA;AAAA,IACpD;AACA,IAAA,KAAA,MAAW,SAAS,IAAA,CAAK,QAAA,IAAY,EAAC,EAAG,KAAA,CAAM,OAAOA,MAAK,CAAA;AAAA,EAC7D,CAAA;AACA,EAAA,KAAA,CAAM,IAAA,EAAM,EAAE,CAAA;AAEd,EAAA,MAAM,MAAA,GAAgB,QAAQ,EAAE,KAAA,EAAO,CAAC,IAAI,CAAA,EAAG,OAAA,EAAS,EAAC,EAAE;AAC3D,EAAA,MAAM,SAAiC,EAAC;AACxC,EAAA,MAAA,CAAO,OAAA,CAAQ,OAAA,CAAQ,CAAC,IAAA,EAAM,CAAA,KAAM;AAClC,IAAA,IAAI,IAAA,CAAK,UAAA,CAAW,GAAG,CAAA,EAAG,MAAA,CAAO,IAAA,CAAK,KAAA,CAAM,CAAC,CAAC,CAAA,GAAI,QAAA,CAAS,CAAC,CAAA;AAAA,EAC9D,CAAC,CAAA;AAED,EAAA,MAAM,WAAA,GAAc,CAAC,IAAA,MAAgD;AAAA,IACnE,GAAG,IAAA;AAAA,IACH,IAAA,EAAM,KAAK,IAAA,CACR,KAAA,CAAM,GAAG,CAAA,CACT,GAAA,CAAI,CAAC,IAAA,KAAS;AACb,MAAA,IAAI,CAAC,IAAA,CAAK,UAAA,CAAW,GAAG,GAAG,OAAO,IAAA;AAClC,MAAA,MAAM,KAAA,GAAQ,MAAA,CAAO,IAAA,CAAK,KAAA,CAAM,CAAC,CAAC,CAAA;AAClC,MAAA,OAAO,KAAA,IAAS,IAAA,GAAO,IAAA,GAAO,kBAAA,CAAmB,KAAK,CAAA;AAAA,IACxD,CAAC,CAAA,CACA,IAAA,CAAK,GAAG;AAAA,GACb,CAAA;AAEA,EAAA,MAAM,KAAA,GAAQ,MAAA,CAAO,KAAA,CAAM,GAAA,CAAI,WAAW,CAAA;AAC1C,EAAA,MAAM,OAAA,GAAU,KAAA,CAAM,KAAA,CAAM,MAAA,GAAS,CAAC,CAAA;AACtC,EAAA,OAAO;AAAA,IACL,OAAA;AAAA,IACA,MAAA,EAAQ,MAAM,MAAA,GAAS,CAAA,GAAI,MAAM,KAAA,CAAM,MAAA,GAAS,CAAC,CAAA,GAAI,MAAA;AAAA,IACrD,OAAO,OAAA,CAAQ,KAAA;AAAA,IACf,KAAA;AAAA,IACA;AAAA,GACF;AACF;AAkBO,IAAM,eAAA,GAA8B,CAAC,IAAA,KAAS;AACnD,EAAA,IAAI,OAAO,MAAA,KAAW,WAAA,EAAa,MAAA,CAAO,QAAA,CAAS,OAAO,IAAI,CAAA;AAChE;AA4BO,SAAS,sBAAA,GAA8C;AAC5D,EAAA,MAAM,IAAA,GAAO,MACX,IAAI,eAAA;AAAA,IACF,OAAO,MAAA,KAAW,WAAA,GAAc,MAAA,CAAO,SAAS,MAAA,GAAS;AAAA,GAC3D;AAEF,EAAA,MAAM,CAAC,YAAA,EAAc,QAAQ,CAAA,GAAI,SAA0B,IAAI,CAAA;AAE/D,EAAA,SAAA,CAAU,MAAM;AACd,IAAA,IAAI,OAAO,WAAW,WAAA,EAAa;AACnC,IAAA,MAAM,KAAA,GAAQ,MAAM,QAAA,CAAS,IAAA,EAAM,CAAA;AACnC,IAAA,MAAA,CAAO,gBAAA,CAAiB,YAAY,KAAK,CAAA;AACzC,IAAA,OAAO,MAAM,MAAA,CAAO,mBAAA,CAAoB,UAAA,EAAY,KAAK,CAAA;AAAA,EAC3D,CAAA,EAAG,EAAE,CAAA;AAEL,EAAA,MAAM,eAAA,GAAkB,WAAA;AAAA,IACtB,CAAC,MAAM,OAAA,KAAY;AACjB,MAAA,IAAI,OAAO,WAAW,WAAA,EAAa;AACnC,MAAA,MAAM,EAAA,GAAK,KAAK,QAAA,EAAS;AACzB,MAAA,MAAM,GAAA,GACJ,MAAA,CAAO,QAAA,CAAS,QAAA,IAAY,EAAA,GAAK,IAAI,EAAE,CAAA,CAAA,GAAK,EAAA,CAAA,GAAM,MAAA,CAAO,QAAA,CAAS,IAAA;AACpE,MAAA,IAAI,SAAS,OAAA,EAAS;AACpB,QAAA,MAAA,CAAO,QAAQ,YAAA,CAAa,MAAA,CAAO,OAAA,CAAQ,KAAA,EAAO,IAAI,GAAG,CAAA;AAAA,MAC3D,CAAA,MAAO;AACL,QAAA,MAAA,CAAO,QAAQ,SAAA,CAAU,MAAA,CAAO,OAAA,CAAQ,KAAA,EAAO,IAAI,GAAG,CAAA;AAAA,MACxD;AACA,MAAA,QAAA,CAAS,IAAI,eAAA,CAAgB,IAAI,CAAC,CAAA;AAAA,IACpC,CAAA;AAAA,IACA;AAAC,GACH;AAEA,EAAA,OAAO,EAAE,cAAc,eAAA,EAAgB;AACzC","file":"chunk-CDYZRZ6U.js","sourcesContent":["\"use client\";\n\n/**\n * Router-agnostic navigation primitives.\n *\n * genesis-ui does NOT depend on any router. Components that need to render a\n * link or navigate imperatively accept an injectable abstraction defined here,\n * and default to plain browser behavior (`<a>` / `window.location`). Consumers\n * on React Router or Next.js inject a thin adapter that maps these props to\n * their own `<Link>` / router.\n */\nimport {\n  useCallback,\n  useEffect,\n  useState,\n  type AnchorHTMLAttributes,\n  type ComponentType,\n  type ReactNode,\n} from \"react\";\n\n// ---------------------------------------------------------------------------\n// Link abstraction\n// ---------------------------------------------------------------------------\n\n/**\n * Props passed to an injectable link component. The contract is a plain anchor\n * (`href`), so the default works with NO router. A React Router consumer maps\n * `href` → `to`; a Next.js consumer passes `next/link` directly (it already\n * accepts `href`, `className`, `children`).\n *\n * @stability Beta\n */\nexport interface GenesisLinkProps {\n  /** Destination path or URL. */\n  href: string;\n  className?: string;\n  onClick?: () => void;\n  children?: ReactNode;\n  /** Set to \"page\" when the link points at the active route. */\n  \"aria-current\"?: AnchorHTMLAttributes<HTMLAnchorElement>[\"aria-current\"];\n  /** Accessible name — useful when the visible label is hidden (icon rail). */\n  \"aria-label\"?: string;\n  /** Native tooltip / title attribute. */\n  title?: string;\n  /**\n   * Stable test/automation selector. {@link DefaultLink} renders it as\n   * `data-testid`; injected router adapters (`next/link`, RR `Link`) forward it\n   * to the underlying `<a>` too.\n   */\n  testID?: string;\n}\n\n/**\n * A component that renders a navigable link from {@link GenesisLinkProps}.\n *\n * @stability Beta\n */\nexport type LinkComponent = ComponentType<GenesisLinkProps>;\n\n/**\n * Default link — a plain `<a>`. No router required.\n *\n * @stability Beta\n */\nexport const DefaultLink: LinkComponent = ({\n  href,\n  children,\n  testID,\n  ...rest\n}) => (\n  <a href={href} data-testid={testID} {...rest}>\n    {children}\n  </a>\n);\n\n/**\n * Split a href into its path (trailing slash dropped, except for `/`), query\n * (no `?`) and hash (no `#`).\n */\nfunction splitHref(href: string): { path: string; search: string; hash: string } {\n  const hashAt = href.indexOf(\"#\");\n  const hash = hashAt === -1 ? \"\" : href.slice(hashAt + 1);\n  const beforeHash = hashAt === -1 ? href : href.slice(0, hashAt);\n  const searchAt = beforeHash.indexOf(\"?\");\n  const rawPath = searchAt === -1 ? beforeHash : beforeHash.slice(0, searchAt);\n  return {\n    path: rawPath.length > 1 ? rawPath.replace(/\\/+$/, \"\") || \"/\" : rawPath,\n    search: searchAt === -1 ? \"\" : beforeHash.slice(searchAt + 1),\n    hash,\n  };\n}\n\n/**\n * Options for {@link isPathActive}.\n *\n * @stability Beta\n */\nexport interface IsPathActiveOptions {\n  /** Require an exact path match instead of a prefix match (like `NavLink end`). */\n  end?: boolean;\n}\n\n/**\n * Default active-path matcher, mirroring React Router's `NavLink` (prefix\n * match, with `/` treated as exact). Consumers can override via an `isActive`\n * prop where components accept one.\n *\n * `activePath` may carry a query and hash (`pathname + search + hash`). An\n * item whose `to` has neither compares against the path part only, exactly as\n * before. An item that opts in by putting a query or hash in its `to`\n * (`/admin?tab=users`, `/settings#profile`) is active only when the path\n * matches exactly AND every query param it names has the same value in\n * `activePath` (extra params such as `&page=2` are ignored) AND, if it names a\n * hash, the hash is equal.\n *\n * @stability Beta\n */\nexport function isPathActive(\n  to: string,\n  activePath?: string,\n  options?: IsPathActiveOptions,\n): boolean {\n  if (activePath == null) return false;\n  if (to === activePath) return true;\n  const target = splitHref(to);\n  const current = splitHref(activePath);\n\n  if (!target.search && !target.hash) {\n    if (target.path === current.path) return true;\n    if (options?.end) return false;\n    return target.path !== \"/\" && current.path.startsWith(target.path + \"/\");\n  }\n\n  if (target.path !== current.path) return false;\n  if (target.hash && target.hash !== current.hash) return false;\n  if (target.search) {\n    const want = new URLSearchParams(target.search);\n    const have = new URLSearchParams(current.search);\n    for (const key of new Set(want.keys())) {\n      const wanted = want.getAll(key);\n      const had = have.getAll(key);\n      if (!wanted.every((value) => had.includes(value))) return false;\n    }\n  }\n  return true;\n}\n\n// ---------------------------------------------------------------------------\n// Hierarchical navigation resolver\n// ---------------------------------------------------------------------------\n\n/**\n * One node of a logical navigation hierarchy. `path` is a route pattern whose\n * segments are either static (`clients`) or named params (`$clientId`). A\n * node's place in the tree is its LOGICAL parent, which need not share its URL\n * prefix — `/clients/$clientId` can sit under `/dashboard`.\n *\n * @stability Beta\n */\nexport interface NavigationNode<T> {\n  id: string;\n  path: string;\n  label: string;\n  /** Contextual nav items to show while this node is current. */\n  items: T[];\n  children?: NavigationNode<T>[];\n}\n\n/**\n * Result of {@link resolveNavigation}. `current`, `parent` and every `trail`\n * entry are shallow copies of their tree nodes with `path` interpolated from\n * `params` (a param the URL did not supply stays as `$name`).\n *\n * @stability Beta\n */\nexport interface ResolvedNavigation<T> {\n  /** The best-matching node — the root when nothing else matches. */\n  current: NavigationNode<T>;\n  /** `current`'s logical parent, for an \"up\" / back-to-parent link. */\n  parent?: NavigationNode<T>;\n  /** `current.items`. */\n  items: T[];\n  /** Root → `current`, inclusive. */\n  trail: NavigationNode<T>[];\n  /** Params captured by `current.path`, URL-decoded. */\n  params: Record<string, string>;\n}\n\nfunction pathSegments(path: string): string[] {\n  return splitHref(path).path.split(\"/\").filter(Boolean);\n}\n\nfunction decodeSegment(segment: string): string {\n  try {\n    return decodeURIComponent(segment);\n  } catch {\n    return segment;\n  }\n}\n\n/**\n * Resolve where `pathname` sits in a logical navigation tree. Pure: it never\n * reads browser history or `window`.\n *\n * A node matches when its pattern matches a leading run of WHOLE path\n * segments (`/my` matches `/my/tasks`, never `/my-other`). Among matches the\n * winner is decided by positional specificity: at the first position where\n * one pattern is static and the other a `$param`, the static one wins (so\n * `/clients/new` beats `/clients/$clientId` whatever the sibling order, and\n * `/my` beats `/$space/tasks` for `/my/tasks`). Otherwise the pattern matching\n * more segments wins, then the deeper tree node.\n * Non-matching nodes are still searched, so a match keeps its logical\n * ancestors even when their URLs differ.\n *\n * @stability Beta\n */\nexport function resolveNavigation<T>(\n  tree: NavigationNode<T>,\n  pathname: string,\n): ResolvedNavigation<T> {\n  // Compare decoded forms on both sides, so `/caf%C3%A9` matches a `/café`\n  // node (and an encoded pattern matches a decoded pathname).\n  const segments = pathSegments(pathname).map(decodeSegment);\n\n  type Match = { trail: NavigationNode<T>[]; pattern: string[] };\n  const matches = (pattern: string[]) =>\n    pattern.length <= segments.length &&\n    pattern.every(\n      (part, i) => part.startsWith(\"$\") || decodeSegment(part) === segments[i],\n    );\n\n  // > 0 when `a` should win over `b`.\n  // Positional specificity, as TanStack Router and React Router rank routes:\n  // walking left to right, the first position where one pattern is static and\n  // the other a `$param` decides. Only then does the longer match win.\n  const compare = (a: Match, b: Match): number => {\n    const shared = Math.min(a.pattern.length, b.pattern.length);\n    for (let i = 0; i < shared; i++) {\n      const aParam = a.pattern[i]!.startsWith(\"$\");\n      const bParam = b.pattern[i]!.startsWith(\"$\");\n      if (aParam !== bParam) return aParam ? -1 : 1;\n    }\n    if (a.pattern.length !== b.pattern.length) {\n      return a.pattern.length - b.pattern.length;\n    }\n    return a.trail.length - b.trail.length;\n  };\n\n  let best: Match | undefined;\n  const visit = (node: NavigationNode<T>, ancestors: NavigationNode<T>[]) => {\n    const trail = [...ancestors, node];\n    const pattern = pathSegments(node.path);\n    if (matches(pattern)) {\n      const candidate = { trail, pattern };\n      if (!best || compare(candidate, best) > 0) best = candidate;\n    }\n    for (const child of node.children ?? []) visit(child, trail);\n  };\n  visit(tree, []);\n\n  const winner: Match = best ?? { trail: [tree], pattern: [] };\n  const params: Record<string, string> = {};\n  winner.pattern.forEach((part, i) => {\n    if (part.startsWith(\"$\")) params[part.slice(1)] = segments[i]!;\n  });\n\n  const interpolate = (node: NavigationNode<T>): NavigationNode<T> => ({\n    ...node,\n    path: node.path\n      .split(\"/\")\n      .map((part) => {\n        if (!part.startsWith(\"$\")) return part;\n        const value = params[part.slice(1)];\n        return value == null ? part : encodeURIComponent(value);\n      })\n      .join(\"/\"),\n  });\n\n  const trail = winner.trail.map(interpolate);\n  const current = trail[trail.length - 1]!;\n  return {\n    current,\n    parent: trail.length > 1 ? trail[trail.length - 2] : undefined,\n    items: current.items,\n    trail,\n    params,\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Imperative navigation abstraction\n// ---------------------------------------------------------------------------\n\n/**\n * Injectable imperative navigation callback.\n *\n * @stability Beta\n */\nexport type NavigateFn = (path: string) => void;\n\n/**\n * Default navigate — a full-page navigation. No router required.\n *\n * @stability Beta\n */\nexport const defaultNavigate: NavigateFn = (path) => {\n  if (typeof window !== \"undefined\") window.location.assign(path);\n};\n\n// ---------------------------------------------------------------------------\n// Search-params abstraction (for URL-synced hooks)\n// ---------------------------------------------------------------------------\n\n/**\n * Minimal, router-agnostic replacement for React Router's `useSearchParams`\n * return shape. Consumers may inject their router's implementation for full\n * SPA integration; otherwise the browser History API is used.\n *\n * @stability Beta\n */\nexport interface SearchParamsAdapter {\n  searchParams: URLSearchParams;\n  setSearchParams: (\n    next: URLSearchParams,\n    options?: { replace?: boolean },\n  ) => void;\n}\n\n/**\n * Browser-native {@link SearchParamsAdapter} built on the History API. Reads\n * the current query string and writes updates via `pushState`/`replaceState`,\n * staying reactive to `popstate` events. No router required.\n *\n * @stability Beta\n */\nexport function useBrowserSearchParams(): SearchParamsAdapter {\n  const read = () =>\n    new URLSearchParams(\n      typeof window !== \"undefined\" ? window.location.search : \"\",\n    );\n\n  const [searchParams, setLocal] = useState<URLSearchParams>(read);\n\n  useEffect(() => {\n    if (typeof window === \"undefined\") return;\n    const onPop = () => setLocal(read());\n    window.addEventListener(\"popstate\", onPop);\n    return () => window.removeEventListener(\"popstate\", onPop);\n  }, []);\n\n  const setSearchParams = useCallback<SearchParamsAdapter[\"setSearchParams\"]>(\n    (next, options) => {\n      if (typeof window === \"undefined\") return;\n      const qs = next.toString();\n      const url =\n        window.location.pathname + (qs ? `?${qs}` : \"\") + window.location.hash;\n      if (options?.replace) {\n        window.history.replaceState(window.history.state, \"\", url);\n      } else {\n        window.history.pushState(window.history.state, \"\", url);\n      }\n      setLocal(new URLSearchParams(next));\n    },\n    [],\n  );\n\n  return { searchParams, setSearchParams };\n}\n"]}

package/dist/{chunk-UBCYXOXT.js → chunk-DWM7ELFI.js}

@@ -8,7 +8,7 @@ import { Switch } from './chunk-27ELYTGE.js';
 import { Button } from './chunk-NWSCYLPT.js';
 import { Label } from './chunk-F47U5KNW.js';
 import { cn } from './chunk-NZ5WBA4R.js';
-import { DefaultLink, isPathActive } from './chunk-6NPEMLBA.js';
+import { DefaultLink, isPathActive } from './chunk-CDYZRZ6U.js';
 import { useId, useState, useEffect, useMemo, useCallback } from 'react';
 import { ListFilter, MoreHorizontal, SlidersHorizontal, Menu, X, PanelLeft, PanelLeftClose, Sun, Moon, ChevronDown } from 'lucide-react';
 import { jsxs, jsx, Fragment } from 'react/jsx-runtime';
@@ -44,6 +44,7 @@ var OPTION_DEFAULTS = {
   showViewToggle: true,
   showViewSettings: true,
   showCreate: true,
+  showStats: false,
   showDetailsToggle: true,
   showDetailsHint: true,
   subtitleInDetails: void 0,
@@ -58,6 +59,7 @@ var BOOLEAN_OPTION_KEYS = [
   "showViewToggle",
   "showViewSettings",
   "showCreate",
+  "showStats",
   "showDetailsToggle",
   "showDetailsHint",
   "subtitleInDetails",
@@ -89,6 +91,7 @@ function PageHeader({
   options: optionsProp,
   optionsStorageKey,
   actions,
+  stats,
   details,
   detailsOpen,
   onDetailsOpenChange,
@@ -109,6 +112,7 @@ function PageHeader({
 }) {
   const detailsRegionId = useId();
   const hasDetails = details != null;
+  const hasStats = stats != null;
   const hasCount = count !== void 0 && totalCount !== void 0;
   const hasViewToggle = Boolean(viewMode && onViewModeChange);
   const hasViewSettings = Boolean(onPageSizeChange && onDensityChange);
@@ -143,13 +147,14 @@ function PageHeader({
       merged.subtitleInDetails = hasDetails;
     }
     if (merged.configurable === void 0) {
-      merged.configurable = hasDetails || hasCount || hasViewSettings || hasViewToggle;
+      merged.configurable = hasDetails || hasStats || hasCount || hasViewSettings || hasViewToggle;
     }
     return merged;
   }, [
     optionsProp,
     userOverrides,
     hasDetails,
+    hasStats,
     hasCount,
     hasViewSettings,
     hasViewToggle
@@ -185,6 +190,7 @@ function PageHeader({
       available: hasViewSettings
     },
     { key: "showCreate", label: "Create action", available: hasCreate },
+    { key: "showStats", label: "Stat cards", available: hasStats },
     {
       key: "showDetailsToggle",
       label: "Filters / details",
@@ -197,6 +203,7 @@ function PageHeader({
     }
   ].filter((t) => t.available);
   const showDetailsToggle = hasDetails && Boolean(resolved.showDetailsToggle);
+  const showStats = hasStats && Boolean(resolved.showStats);
   const showHint = hasDetails && !open && Boolean(resolved.showDetailsHint) && detailsHint != null;
   const actionsCluster = /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-1.5 shrink-0", children: [
     showHint ? /* @__PURE__ */ jsx("span", { className: "hidden max-w-[14rem] truncate text-xs text-muted-foreground sm:inline", children: detailsHint }) : null,
@@ -353,11 +360,23 @@ function PageHeader({
     ] }),
     actionsCluster
   ] });
+  const statsRow = showStats ? /* @__PURE__ */ jsx(
+    "div",
+    {
+      "data-testid": "page-header-stats",
+      className: "mt-3 grid gap-3 sm:grid-cols-2 lg:grid-cols-4",
+      children: stats
+    }
+  ) : null;
   if (!hasDetails) {
-    return titleRow;
+    return /* @__PURE__ */ jsxs(Fragment, { children: [
+      titleRow,
+      statsRow
+    ] });
   }
   return /* @__PURE__ */ jsxs(Collapsible, { open, onOpenChange: setOpen, children: [
     titleRow,
+    statsRow,
     /* @__PURE__ */ jsx(CollapsibleContent, { id: detailsRegionId, className: "mt-3", children: /* @__PURE__ */ jsxs("div", { className: "flex flex-col gap-3 rounded-lg border border-border bg-card/40 p-3 sm:p-4", children: [
       moveSubtitle && subtitle && resolved.showSubtitle !== false ? /* @__PURE__ */ jsx("p", { className: "text-sm text-muted-foreground", children: subtitle }) : null,
       details
@@ -431,7 +450,7 @@ function ThemeToggle({ testId }) {
 }
 function itemIsActive(item, activePath, isActive) {
   if (item.end) {
-    return Boolean(activePath && activePath === item.to);
+    return isPathActive(item.to, activePath, { end: true });
   }
   if (isActive(item.to, activePath)) return true;
   return Boolean(
@@ -537,7 +556,9 @@ function NavGroup({
       }
     );
   }
-  const selfExact = Boolean(item.to && activePath && activePath === item.to);
+  const selfExact = Boolean(
+    item.to && isPathActive(item.to, activePath, { end: true })
+  );
   const selfActive = item.to ? item.end ? selfExact : isActive(item.to, activePath) : false;
   const groupHighlight = selfActive || childActive;
   const pad = density === "compact" ? "px-2.5 py-1.5" : "px-3 py-2";
@@ -1128,5 +1149,5 @@ function AppShell({
 }
 
 export { AppShell, PageHeader };
-//# sourceMappingURL=chunk-UBCYXOXT.js.map
-//# sourceMappingURL=chunk-UBCYXOXT.js.map
+//# sourceMappingURL=chunk-DWM7ELFI.js.map
+//# sourceMappingURL=chunk-DWM7ELFI.js.map