basalt-ui 1.25.0 → 1.26.0

package/dist/router-tanstack/search-store.d.ts

@@ -0,0 +1,81 @@
+import type { AnyField, FieldHandle, SearchValues, StoredValues } from '../state.js';
+export type CreateSearchStoreOptions<S extends Record<string, AnyField>> = {
+    /** localStorage key (namespaced `basalt:<key>` automatically). One entry per store. */
+    key: string;
+    /** The fields, built with `field.*`. The key of each is its default URL param name. */
+    fields: S;
+    /** Envelope version — bump when the field set changes to discard stale localStorage. */
+    version?: number;
+};
+export type SearchStore<S extends Record<string, AnyField>> = {
+    /**
+     * Pass directly to `createFileRoute({ validateSearch })`. Returns every URL-lane param, resolved
+     * URL ⊳ localStorage ⊳ fallback — a route wired to it therefore always has the params, which is
+     * what makes `use()`'s "does this route own the field" check trivial and exact.
+     */
+    validateSearch: (raw: Record<string, unknown>) => SearchValues<S>;
+    /**
+     * The click-time `search:` value for a nav link. Pass it BY REFERENCE
+     * (`search: store.linkSearch`) inside `defineNav` — never a literal object, which pins the
+     * fallback on every click and is why one consumer's reader had zero call sites (C10, A2).
+     */
+    linkSearch: () => SearchValues<S>;
+    /** Plain read for non-React contexts (a redirect, a loader, a guard, a test). */
+    readStored: () => Partial<StoredValues<S>>;
+    /** The per-field handles every basalt control takes instead of `value`/`onChange` (C2). */
+    field: {
+        [K in keyof S]: FieldHandle<S[K]>;
+    };
+    /** Option labels for enum / multi / range fields. Chainable — call it once, at definition. */
+    labels: (map: Partial<{
+        [K in keyof S]: Record<string, string>;
+    }>) => SearchStore<S>;
+    /** Every URL-lane param, resolved — the object a page hands to its query. */
+    useValues: () => SearchValues<S>;
+    /** How many fields differ from their fallback — the `n` in a `Filters (n)` pill. */
+    useActiveCount: () => number;
+    /** Resets every field to its fallback: one navigate, one storage write. */
+    useReset: () => () => void;
+};
+/**
+ * The public store plus the one member only the deprecated wrappers need: `markReaderWired`, so a
+ * consumer whose only reader is the wrapper's own `useStore()` still counts as wired and never sees
+ * the pinned-link warning it never used to see.
+ *
+ * @internal — absent from `SearchStore`, so it is invisible on `createSearchStore`'s return type.
+ */
+export type InternalSearchStore<S extends Record<string, AnyField>> = SearchStore<S> & {
+    markReaderWired: () => void;
+};
+/**
+ * The store, plus the one knob the deprecated wrappers need: `legacyValueField` keeps the
+ * enum-only stores' single-value storage layout so an already-persisted selection still resolves.
+ * Not exported from the barrel — `createSearchStore` is the public door.
+ */
+export declare function buildSearchStore<const S extends Record<string, AnyField>>(o: CreateSearchStoreOptions<S> & {
+    legacyValueField?: string;
+}): InternalSearchStore<S>;
+/**
+ * One store per page (or per feature), over typed fields. `key` is the localStorage key; each
+ * field's map key is its default URL param name.
+ *
+ * @example
+ * export const analytics = createSearchStore({
+ *   key: 'analytics',
+ *   fields: {
+ *     range: field.range({ presets: ['7d', '30d', '90d'], fallback: '30d', custom: true }),
+ *     compare: field.enum(['none', 'previous'], 'none'),
+ *     channels: field.multi(CHANNELS, []),
+ *   },
+ * }).labels({ range: { '7d': 'Last 7 days', '30d': 'Last 30 days', '90d': 'Last 90 days' } })
+ *
+ * export const Route = createFileRoute('/analytics')({
+ *   validateSearch: analytics.validateSearch,
+ *   loaderDeps: ({ search }) => search,
+ * })
+ *
+ * // in the page: <RangeFilter field={analytics.field.range} />
+ * // in the nav:  linkOptions({ to: '/analytics', search: analytics.linkSearch })
+ */
+export declare function createSearchStore<const S extends Record<string, AnyField>>(o: CreateSearchStoreOptions<S>): SearchStore<S>;
+//# sourceMappingURL=search-store.d.ts.map

package/dist/router-tanstack/search-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-store.d.ts","sourceRoot":"","sources":["../../src/router-tanstack/search-store.ts"],"names":[],"mappings":"AAiCA,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,YAAY,EAAc,YAAY,EAAE,MAAM,UAAU,CAAA;AAI7F,MAAM,MAAM,wBAAwB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI;IACzE,uFAAuF;IACvF,GAAG,EAAE,MAAM,CAAA;IACX,uFAAuF;IACvF,MAAM,EAAE,CAAC,CAAA;IACT,wFAAwF;IACxF,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI;IAC5D;;;;OAIG;IACH,cAAc,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,YAAY,CAAC,CAAC,CAAC,CAAA;IACjE;;;;OAIG;IACH,UAAU,EAAE,MAAM,YAAY,CAAC,CAAC,CAAC,CAAA;IACjC,iFAAiF;IACjF,UAAU,EAAE,MAAM,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAA;IAC1C,2FAA2F;IAC3F,KAAK,EAAE;SAAG,CAAC,IAAI,MAAM,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;KAAE,CAAA;IAC5C,8FAA8F;IAC9F,MAAM,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC;SAAG,CAAC,IAAI,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;KAAE,CAAC,KAAK,WAAW,CAAC,CAAC,CAAC,CAAA;IACpF,6EAA6E;IAC7E,SAAS,EAAE,MAAM,YAAY,CAAC,CAAC,CAAC,CAAA;IAChC,oFAAoF;IACpF,cAAc,EAAE,MAAM,MAAM,CAAA;IAC5B,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,MAAM,IAAI,CAAA;CAC3B,CAAA;AA4DD;;;;;;GAMG;AACH,MAAM,MAAM,mBAAmB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,GAAG;IACrF,eAAe,EAAE,MAAM,IAAI,CAAA;CAC5B,CAAA;AAQD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,EACvE,CAAC,EAAE,wBAAwB,CAAC,CAAC,CAAC,GAAG;IAAE,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7D,mBAAmB,CAAC,CAAC,CAAC,CAoMxB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,EACxE,CAAC,EAAE,wBAAwB,CAAC,CAAC,CAAC,GAC7B,WAAW,CAAC,CAAC,CAAC,CAEhB"}

package/dist/router-tanstack/search-store.js

@@ -0,0 +1,187 @@
+import { useNavigate, useSearch } from "@tanstack/react-router";
+import { createStoreCore } from "../state.js";
+function warnLinkPinsFallback(input) {
+  const { key, param, urlValue, storedValue } = input;
+  console.warn(
+    `[basalt-ui] createSearchStore('${key}'): the URL pinned \`${param}=${urlValue}\` (the fallback) while '${storedValue}' was persisted, and nothing has read this store back. A nav link is almost certainly declaring \`search: { ${param}: '${urlValue}' }\` at module scope, which overrides the stored value on every click \u2014 pass the store's own reader instead: \`search: <store>.linkSearch\`. (dev only)`
+  );
+}
+function useCurrentSearch() {
+  const search = useSearch({ strict: false });
+  return typeof search === "object" && search !== null ? search : {};
+}
+function describeValue(value) {
+  return typeof value === "string" ? value : JSON.stringify(value);
+}
+function warnWriteHasNowhereToGo(input) {
+  const { key, name, param } = input;
+  console.warn(
+    `[basalt-ui] createSearchStore('${key}'): wrote field '${name}' from a route that does not validate \`${param}\`, and the field is \`persist: false\` \u2014 so the write was dropped. Either render this control on the route wired to \`validateSearch\`, or give the field the localStorage lane (drop \`persist: false\`) so a write from elsewhere survives until the owning route reads it. (dev only)`
+  );
+}
+function isMemoryLane(entry) {
+  return !entry.codec.lane.url && !entry.codec.lane.persist;
+}
+function buildSearchStore(o) {
+  const core = createStoreCore(o);
+  let readerWired = false;
+  let warned = false;
+  const markReaderWired = () => {
+    readerWired = true;
+  };
+  const nowhereWarned = /* @__PURE__ */ new Set();
+  const flatten = (search, record) => {
+    const out = {};
+    for (const entry of core.urlEntries) {
+      Object.assign(out, entry.codec.toSearch(core.resolve(entry, search, record)));
+    }
+    return out;
+  };
+  const maybeWarn = (raw, record) => {
+    if (warned || readerWired || process.env["NODE_ENV"] === "production") return;
+    for (const entry of core.urlEntries) {
+      const fromUrl = entry.codec.fromSearch(raw);
+      if (fromUrl === null || !entry.codec.equals(fromUrl, entry.codec.fallback)) continue;
+      const stored = entry.codec.decode(record[entry.name]);
+      if (stored === null || entry.codec.equals(stored, fromUrl)) continue;
+      warned = true;
+      warnLinkPinsFallback({
+        key: o.key,
+        param: entry.codec.primary,
+        urlValue: describeValue(entry.codec.toSearch(fromUrl)[entry.codec.primary]),
+        storedValue: describeValue(entry.codec.toSearch(stored)[entry.codec.primary])
+      });
+      return;
+    }
+  };
+  const validateSearch = (raw) => {
+    const record = core.readRecord();
+    maybeWarn(raw, record);
+    return flatten(raw, record);
+  };
+  const linkSearch = () => {
+    readerWired = true;
+    return flatten(null, core.readRecord());
+  };
+  const readStored = () => {
+    readerWired = true;
+    return core.readStoredFlat();
+  };
+  const urlUse = (entry) => () => {
+    const search = useCurrentSearch();
+    const navigate = useNavigate();
+    const [record, setRecord] = core.usePersistedRecord();
+    markReaderWired();
+    const value = core.resolve(entry, search, record);
+    const validated = Object.hasOwn(search, entry.codec.primary);
+    return [
+      value,
+      (next) => {
+        if (validated) {
+          navigate({
+            to: ".",
+            search: (prev) => ({ ...prev, ...entry.codec.toSearch(next) }),
+            replace: entry.codec.lane.history === "replace",
+            // A filter lives halfway down a page as often as it lives in the bar, and the router's
+            // default scroll restoration treats this same-route search write as a navigation — so
+            // without this a select two screens down jumps the reader back to the top on every
+            // change. Never a prop: there is no filter write that WANTS the page to scroll.
+            resetScroll: false
+          });
+        }
+        if (entry.codec.lane.persist) {
+          core.writeField(setRecord, entry.name, next);
+          return;
+        }
+        if (validated || nowhereWarned.has(entry.name)) return;
+        if (process.env["NODE_ENV"] === "production") return;
+        nowhereWarned.add(entry.name);
+        warnWriteHasNowhereToGo({ key: o.key, name: entry.name, param: entry.codec.primary });
+      }
+    ];
+  };
+  const localUse = (entry) => () => {
+    const [record, setRecord] = core.usePersistedRecord();
+    markReaderWired();
+    return [
+      core.resolve(entry, null, record),
+      (next) => core.writeField(setRecord, entry.name, next)
+    ];
+  };
+  const memoryEntries = core.entries.filter(isMemoryLane);
+  const field = {};
+  for (const entry of core.entries) {
+    const use = entry.codec.lane.url ? urlUse(entry) : entry.codec.lane.persist ? localUse(entry) : core.memoryUse(entry);
+    field[entry.name] = core.handle(entry, use);
+  }
+  const useValues = () => {
+    const search = useCurrentSearch();
+    const [record] = core.usePersistedRecord();
+    markReaderWired();
+    return flatten(search, record);
+  };
+  const useActiveCount = () => {
+    const search = useCurrentSearch();
+    const [record] = core.usePersistedRecord();
+    core.useMemoryVersion();
+    let count = 0;
+    for (const entry of core.entries) {
+      const value = isMemoryLane(entry) ? core.readMemoryValue(entry) : core.resolve(entry, entry.codec.lane.url ? search : null, record);
+      if (!entry.codec.equals(value, entry.codec.fallback)) count += 1;
+    }
+    return count;
+  };
+  const useReset = () => {
+    const search = useCurrentSearch();
+    const navigate = useNavigate();
+    const [, setRecord] = core.usePersistedRecord();
+    return () => {
+      const validatedEntries = core.urlEntries.filter(
+        (entry) => Object.hasOwn(search, entry.codec.primary)
+      );
+      if (validatedEntries.length > 0) {
+        const patch = {};
+        for (const entry of validatedEntries) {
+          Object.assign(patch, entry.codec.toSearch(entry.codec.fallback));
+        }
+        navigate({
+          to: ".",
+          search: (prev) => ({ ...prev, ...patch }),
+          replace: true,
+          // Same reason as a single field's write above — a `Reset all` pressed from the mobile
+          // sheet must not also scroll the page it was pressed on.
+          resetScroll: false
+        });
+      }
+      if (memoryEntries.length > 0) core.resetMemory();
+      if (!core.anyPersisted) return;
+      const next = { ...core.readRecord() };
+      for (const entry of core.entries) {
+        if (entry.codec.lane.persist) next[entry.name] = entry.codec.fallback;
+      }
+      setRecord(next);
+    };
+  };
+  const store = {
+    validateSearch,
+    linkSearch,
+    readStored,
+    field,
+    labels: (map) => {
+      core.setLabels(map);
+      return store;
+    },
+    useValues,
+    useActiveCount,
+    useReset,
+    markReaderWired
+  };
+  return store;
+}
+function createSearchStore(o) {
+  return buildSearchStore(o);
+}
+export {
+  buildSearchStore,
+  createSearchStore
+};

package/dist/router-tanstack/search-store.router.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=search-store.router.test.d.ts.map

package/dist/router-tanstack/search-store.router.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-store.router.test.d.ts","sourceRoot":"","sources":["../../src/router-tanstack/search-store.router.test.tsx"],"names":[],"mappings":""}

package/dist/router-tanstack/search-store.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=search-store.test.d.ts.map

package/dist/router-tanstack/search-store.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-store.test.d.ts","sourceRoot":"","sources":["../../src/router-tanstack/search-store.test.ts"],"names":[],"mappings":""}

package/dist/router-tanstack/use-nav.d.ts

@@ -10,8 +10,6 @@ export type UseNavOptions<G extends ReadonlyArray<AnyNavGroup>> = {
     badges?: Partial<Record<NavItemId<G>, number | ReactNode>>;
     /** Override active detection entirely. */
     isActive?: (item: AnyNavItem) => boolean;
-    /** Passed straight through into the returned `mobileNav`. */
-    moreExtra?: ReactNode;
     getScrollElement?: () => HTMLElement | null;
 };
 /** Spread straight onto `<BasaltShell {...nav} />` — both keys are `BasaltShellProps` keys. */

package/dist/router-tanstack/use-nav.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-nav.d.ts","sourceRoot":"","sources":["../../src/router-tanstack/use-nav.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAe,SAAS,EAAE,MAAM,OAAO,CAAA;AAEnD,OAAO,KAAK,EAAE,eAAe,EAA0B,cAAc,EAAE,MAAM,cAAc,CAAA;AAC3F,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AAEpF,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,aAAa,CAAC,WAAW,CAAC,IAAI;IAChE;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAA;IAC1D,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,OAAO,CAAA;IACxC,6DAA6D;IAC7D,SAAS,CAAC,EAAE,SAAS,CAAA;IACrB,gBAAgB,CAAC,EAAE,MAAM,WAAW,GAAG,IAAI,CAAA;CAC5C,CAAA;AAED,+FAA+F;AAC/F,MAAM,MAAM,UAAU,GAAG;IAAE,QAAQ,EAAE,cAAc,EAAE,CAAC;IAAC,SAAS,EAAE,eAAe,CAAA;CAAE,CAAA;AAEnF;;;;;;GAMG;AACH,wBAAgB,MAAM,CACpB,KAAK,CAAC,CAAC,SAAS,aAAa,CAAC,WAAW,CAAC,EAC1C,KAAK,CAAC,CAAC,SAAS,aAAa,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAC1C,MAAM,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,UAAU,CAqG9D"}
+{"version":3,"file":"use-nav.d.ts","sourceRoot":"","sources":["../../src/router-tanstack/use-nav.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAe,SAAS,EAAE,MAAM,OAAO,CAAA;AAEnD,OAAO,KAAK,EAAE,eAAe,EAA0B,cAAc,EAAE,MAAM,cAAc,CAAA;AAE3F,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AAEpF,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,aAAa,CAAC,WAAW,CAAC,IAAI;IAChE;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAA;IAC1D,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,OAAO,CAAA;IACxC,gBAAgB,CAAC,EAAE,MAAM,WAAW,GAAG,IAAI,CAAA;CAC5C,CAAA;AAED,+FAA+F;AAC/F,MAAM,MAAM,UAAU,GAAG;IAAE,QAAQ,EAAE,cAAc,EAAE,CAAC;IAAC,SAAS,EAAE,eAAe,CAAA;CAAE,CAAA;AAEnF;;;;;;GAMG;AACH,wBAAgB,MAAM,CACpB,KAAK,CAAC,CAAC,SAAS,aAAa,CAAC,WAAW,CAAC,EAC1C,KAAK,CAAC,CAAC,SAAS,aAAa,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAC1C,MAAM,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,UAAU,CAgK9D"}

package/dist/router-tanstack/use-nav.js

@@ -1,5 +1,6 @@
 import { createElement, useMemo } from "react";
 import { Link, useMatchRoute, useRouterState } from "@tanstack/react-router";
+import { flattenNav } from "./nav.js";
 function useNav(config, opts) {
   const matchRoute = useMatchRoute();
   const href = useRouterState({ select: (s) => s.location.href });
@@ -7,29 +8,52 @@ function useNav(config, opts) {
   const isActiveOverride = opts?.isActive;
   const sections = useMemo(() => {
     const badgeOf = (id) => badges?.[id];
-    const isActive = (item) => isActiveOverride?.(item) ?? Boolean(
+    const matchOf = (item) => isActiveOverride?.(item) ?? Boolean(
       matchRoute({
         to: item.link.to,
         ...item.link.params !== void 0 && { params: item.link.params },
-        // Prefix match by default so a parent stays lit on its children; `'/'` would then match
-        // everything, so it is always exact.
         fuzzy: item.exact !== true && item.link.to !== "/"
       })
     );
+    const allItems = flattenNav(config);
+    const specificity = (to) => to.split("/").filter(Boolean).length;
+    const matchedById = /* @__PURE__ */ new Map();
+    let winnerId;
+    let winnerTo;
+    for (const item of allItems) {
+      const matched = matchOf(item);
+      matchedById.set(item.id, matched);
+      if (matched && (winnerTo === void 0 || specificity(item.link.to) > specificity(winnerTo))) {
+        winnerId = item.id;
+        winnerTo = item.link.to;
+      }
+    }
+    const resolveState = (item) => {
+      if (item.id === winnerId) return { active: true, ancestor: false };
+      const matched = matchedById.get(item.id) ?? false;
+      const ancestor = winnerTo !== void 0 && matched && winnerTo.startsWith(`${item.link.to}/`);
+      return { active: false, ancestor };
+    };
     const toSidebarItem = (item) => {
-      const Anchor = (props) => createElement(Link, { ...item.link, ...props });
+      const Anchor = (props) => createElement(Link, {
+        ...item.link,
+        activeOptions: { exact: true },
+        ...props
+      });
       const badge = badgeOf(item.id);
       const children = item.children?.map(toSidebarItem);
+      const { active, ancestor } = resolveState(item);
       return {
         key: item.id,
         label: item.label,
         icon: item.icon,
         Anchor,
-        // Per-destination active only. Rolling a child's active state up into its parent is the
-        // MOBILE SLOT's rule (§2.3.12) and belongs to `projectMobileNav`, which reads `children`
-        // anyway — doing it here too would also light a desktop parent row whose own route does
-        // not match.
-        active: isActive(item),
+        // Exactly one destination in the WHOLE definition reads `active` (`resolveState` above).
+        // Rolling that up into a mobile SLOT (any descendant active → the slot reads active) is
+        // still `projectMobileNav`'s job, which reads `children` for that. `ancestor` is the
+        // desktop-only middle state: a matched item that sits on the winner's path but isn't it.
+        active,
+        ...ancestor && { ancestor },
         ...item.short !== void 0 && { short: item.short },
         ...item.mobile !== void 0 && { mobile: item.mobile },
         ...item.disabled !== void 0 && { disabled: item.disabled },
@@ -47,7 +71,6 @@ function useNav(config, opts) {
     }));
   }, [config, matchRoute, href, badges, isActiveOverride]);
   const mobile = config.mobile;
-  const moreExtra = opts?.moreExtra;
   const getScrollElement = opts?.getScrollElement;
   const mobileNav = useMemo(() => {
     const groupLabelById = new Map(config.groups.map((g) => [g.id, g.label]));
@@ -60,10 +83,9 @@ function useNav(config, opts) {
       ...mobile?.maxTabs !== void 0 && { maxTabs: mobile.maxTabs },
       ...mobile?.menuMax !== void 0 && { menuMax: mobile.menuMax },
       ...mobile?.moreLabel !== void 0 && { moreLabel: mobile.moreLabel },
-      ...moreExtra !== void 0 && { moreExtra },
       ...getScrollElement !== void 0 && { getScrollElement }
     };
-  }, [config, mobile, moreExtra, getScrollElement]);
+  }, [config, mobile, getScrollElement]);
   return { sections, mobileNav };
 }
 export {

package/dist/router-tanstack/use-nav.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=use-nav.test.d.ts.map

package/dist/router-tanstack/use-nav.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-nav.test.d.ts","sourceRoot":"","sources":["../../src/router-tanstack/use-nav.test.tsx"],"names":[],"mappings":""}

package/dist/section/index.d.ts

@@ -0,0 +1,2 @@
+export { Section, type SectionProps } from './section.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/section/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/section/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,WAAW,CAAA"}

package/dist/section/index.js

@@ -0,0 +1,4 @@
+import { Section } from "./section.js";
+export {
+  Section
+};

package/dist/section/section.d.ts

@@ -0,0 +1,24 @@
+import type { ReactNode } from 'react';
+import type { WidgetHeaderProps } from '../widget-header/index.js';
+export type SectionProps = Omit<WidgetHeaderProps, 'tier'> & {
+    /** Rendered in the header row, in its own `CtlSlot` — hidden while the section is collapsed. */
+    tabs?: ReactNode;
+    /** Renders a chevron toggle in the header; the header stays drawn when closed, only `children`
+     * (and `tabs`) unmount. @default false */
+    collapsible?: boolean;
+    /** Persists the fold state at `basalt:section:<persistKey>`. Omit for a local, unpersisted fold
+     * (`useState`). */
+    persistKey?: string;
+    /** The fold state a section opens on, respected only while no persisted value exists — a section
+     * a reader has closed stays closed. `false` is what a long secondary block wants. @default true */
+    defaultOpen?: boolean;
+    /** Rendered directly under the header and ALWAYS visible, collapsed or not: a collapsed section
+     * still states its headline figures, which is what makes collapsing it a real option. Keep it to
+     * one row — the body is what `children` is for. */
+    summary?: ReactNode;
+    /** Turns the root into a scroll anchor (`id` + `scroll-margin-top` cleared for both sticky bars). */
+    id?: string;
+    children: ReactNode;
+};
+export declare function Section({ title, icon, subtitle, info, value, delta, deltaPeriod, sparkline, count, actions, tabs, collapsible, persistKey, defaultOpen, summary, id, children, }: SectionProps): import("react").JSX.Element;
+//# sourceMappingURL=section.d.ts.map

package/dist/section/section.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"section.d.ts","sourceRoot":"","sources":["../../src/section/section.tsx"],"names":[],"mappings":"AA8CA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAGzD,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,iBAAiB,EAAE,MAAM,CAAC,GAAG;IAC3D,gGAAgG;IAChG,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB;8CAC0C;IAC1C,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB;uBACmB;IACnB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;uGACmG;IACnG,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB;;uDAEmD;IACnD,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB,qGAAqG;IACrG,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,QAAQ,EAAE,SAAS,CAAA;CACpB,CAAA;AAgFD,wBAAgB,OAAO,CAAC,EACtB,KAAK,EACL,IAAI,EACJ,QAAQ,EACR,IAAI,EACJ,KAAK,EACL,KAAK,EACL,WAAW,EACX,SAAS,EACT,KAAK,EACL,OAAO,EACP,IAAI,EACJ,WAAmB,EACnB,UAAU,EACV,WAAkB,EAClB,OAAO,EACP,EAAE,EACF,QAAQ,GACT,EAAE,YAAY,+BAiDd"}

package/dist/section/section.js

@@ -0,0 +1,126 @@
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { Children, useId, useMemo, useState } from "react";
+import { CtlSlot } from "../theme/index.js";
+import { createPersistedState } from "../state.js";
+import { WidgetHeader } from "../widget-header/index.js";
+import classes from "./section.module.css";
+function isDev() {
+  return process.env["NODE_ENV"] !== "production";
+}
+function warnPastActionBudget(title, actions) {
+  if (!isDev()) return;
+  const count = Children.count(actions);
+  if (count <= 3) return;
+  console.warn(
+    `Section "${title}": ${count} actions exceeds the \u22643 budget (docs/CONTROLS-SPEC.md C6) \u2014 move the rest behind a menu.`
+  );
+}
+const UNPERSISTED_KEY = "__local__";
+function useSectionOpen(persistKey, defaultOpen) {
+  const [localOpen, setLocalOpen] = useState(defaultOpen);
+  const usePersistedOpen = useMemo(
+    () => createPersistedState({
+      key: `section:${persistKey ?? UNPERSISTED_KEY}`,
+      version: 1,
+      initial: defaultOpen
+    }),
+    [persistKey, defaultOpen]
+  );
+  const [persistedOpen, setPersistedOpen] = usePersistedOpen();
+  if (persistKey !== void 0) return [persistedOpen, setPersistedOpen];
+  return [localOpen, setLocalOpen];
+}
+function ChevronToggle({
+  open,
+  onToggle,
+  controls
+}) {
+  return /* @__PURE__ */ jsx(
+    "button",
+    {
+      type: "button",
+      className: classes.chevron,
+      "data-open": open,
+      "aria-expanded": open,
+      "aria-controls": controls,
+      "aria-label": open ? "Collapse section" : "Expand section",
+      onClick: onToggle,
+      children: /* @__PURE__ */ jsx(
+        "svg",
+        {
+          width: 12,
+          height: 12,
+          viewBox: "0 0 24 24",
+          fill: "none",
+          stroke: "currentColor",
+          strokeWidth: 2.5,
+          "aria-hidden": "true",
+          children: /* @__PURE__ */ jsx("path", { d: "M6 9l6 6 6-6", strokeLinecap: "round", strokeLinejoin: "round" })
+        }
+      )
+    }
+  );
+}
+function Section({
+  title,
+  icon,
+  subtitle,
+  info,
+  value,
+  delta,
+  deltaPeriod,
+  sparkline,
+  count,
+  actions,
+  tabs,
+  collapsible = false,
+  persistKey,
+  defaultOpen = true,
+  summary,
+  id,
+  children
+}) {
+  const [open, setOpen] = useSectionOpen(persistKey, defaultOpen);
+  const bodyId = useId();
+  if (actions !== void 0) warnPastActionBudget(title, actions);
+  const headerActions = tabs !== void 0 || actions !== void 0 || collapsible ? /* @__PURE__ */ jsxs(Fragment, { children: [
+    tabs !== void 0 && open && /* @__PURE__ */ jsx(CtlSlot, { children: tabs }),
+    actions !== void 0 && /* @__PURE__ */ jsx(CtlSlot, { children: actions }),
+    collapsible && /* @__PURE__ */ jsx(ChevronToggle, { open, onToggle: () => setOpen(!open), controls: bodyId })
+  ] }) : void 0;
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      className: classes.root,
+      ...id !== void 0 && { id },
+      ...id !== void 0 && {
+        style: {
+          scrollMarginTop: "calc(var(--app-shell-header-height, 0px) + var(--basalt-page-bar-h, 0px))"
+        }
+      },
+      children: [
+        /* @__PURE__ */ jsx(
+          WidgetHeader,
+          {
+            tier: "section",
+            title,
+            ...icon !== void 0 && { icon },
+            ...subtitle !== void 0 && { subtitle },
+            ...info !== void 0 && { info },
+            ...value !== void 0 && { value },
+            ...delta !== void 0 && { delta },
+            ...deltaPeriod !== void 0 && { deltaPeriod },
+            ...sparkline !== void 0 && { sparkline },
+            ...count !== void 0 && { count },
+            ...headerActions !== void 0 && { actions: headerActions }
+          }
+        ),
+        summary !== void 0 && /* @__PURE__ */ jsx("div", { className: classes.summary, children: summary }),
+        open && /* @__PURE__ */ jsx("div", { id: bodyId, className: classes.body, children })
+      ]
+    }
+  );
+}
+export {
+  Section
+};