basalt-ui 1.27.0 → 1.29.0

package/dist/common/errors.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The message table (Blueprint audit §3). Every basalt diagnostic — thrown or logged — is built
+ * here, so the prefix, the `Component: …` shape and the em-dash-then-remedy rhythm are one decision
+ * instead of 60. It is the generalisation of `assertQueryStateLike`, which was the ONLY component
+ * in the library naming itself in its own failure (isomorphic finding F-ERR-1: the other 54 fail as
+ * raw `TypeError`s that `BasaltErrorBoundary` swallows into a blank subtree).
+ *
+ * Every builder returns a string; nothing here throws or logs. The caller decides which it is —
+ * `assertRequiredProps` throws, `useValidateProps` logs, the mount guards log.
+ */
+/** The one namespace every basalt message opens with. */
+export declare const BASALT_PREFIX = "[basalt]";
+/**
+ * A prop the component reads into and cannot render without. This is the F-ERR-1 message: the
+ * component names itself and the prop, instead of the read landing as
+ * `undefined is not an object (evaluating 'field.use')`.
+ */
+export declare function requiredProp(component: string, prop: string, hint?: string): string;
+/** A prop with a closed value set that got something outside it. */
+export declare function oneOf(component: string, prop: string, allowed: readonly string[], got: unknown): string;
+/**
+ * A prop still shipped and still working, with a named successor and the version it goes away in.
+ * Majors are banned here, so the deprecation notice IS the migration channel.
+ */
+export declare function deprecatedProp(component: string, oldProp: string, newProp: string, removeIn: string): string;
+/**
+ * An imperative call needs a layer that is not there — the optional peer is not installed, or the
+ * mount that subscribes to its event bus is disabled. Both halves are named because the remedy
+ * differs: install it, or stop turning it off.
+ */
+export declare function missingLayer(component: string, layer: string, remedy: string): string;
+/** A single-mount component found a second instance alive (`BasaltProvider`, `Notifications`). */
+export declare function duplicateMount(component: string): string;
+/**
+ * The HTTP status behind a thrown envelope (Eden Treaty's `{ status, value }`, a `Response`-shaped
+ * throw), when there is one. Use it to BRANCH — 404 → "not found" copy — rather than to build a
+ * message; `toErrorMessage` already folds the status into its text when the body says nothing.
+ *
+ * @example
+ * if (errorStatus(err) === 404) return <EmptyState title="Gone" />
+ */
+export declare function errorStatus(err: unknown): number | undefined;
+/**
+ * Extract a human-readable message from an unknown thrown value (e.g. the raw Eden envelope
+ * thrown by `unwrap`). Removes the 8-line three-branch boilerplate consumers duplicate.
+ *
+ * Resolution order:
+ *   1. `Error` instance       → err.message
+ *   2. `{ message: string }`  → message (Eden / Elysia error shape)
+ *   3. `{ value: ... }`       → recursively (Eden nested value envelope)
+ *   4. plain string           → itself
+ *   5. anything else          → `JSON.stringify`
+ *
+ * **If that yields nothing a human can read** (`''`, `'{}'`, `'[]'`, `'null'`, `'undefined'`,
+ * `'[object Object]'` — the shapes `JSON.stringify` produces for an opaque envelope) the `fallback`
+ * is returned instead, with `(HTTP <status>)` appended when the envelope carries one. Without that
+ * guard the caller renders a literal `{}` at the user, or — for `toErrorMessage(undefined)` —
+ * the actual value `undefined`, since `JSON.stringify(undefined)` is not a string at all.
+ *
+ * @example
+ * try {
+ *   await unwrap(api.resource.post({ body }))
+ * } catch (e) {
+ *   toast(toErrorMessage(e, 'Could not create share'))   // → "slug already in use"
+ *                                                        // → "Could not create share (HTTP 502)"
+ * }
+ */
+export declare function toErrorMessage(err: unknown, fallback?: string): string;
+//# sourceMappingURL=errors.d.ts.map

package/dist/common/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/common/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,yDAAyD;AACzD,eAAO,MAAM,aAAa,aAAa,CAAA;AAMvC;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAEnF;AAED,oEAAoE;AACpE,wBAAgB,KAAK,CACnB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,GAAG,EAAE,OAAO,GACX,MAAM,CAMR;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,MAAM,CAKR;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAErF;AAED,kGAAkG;AAClG,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAKxD;AAOD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAI5D;AAqBD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,SAAwB,GAAG,MAAM,CAKrF"}

package/dist/common/errors.js

@@ -0,0 +1,64 @@
+const BASALT_PREFIX = "[basalt]";
+function message(component, body) {
+  return `${BASALT_PREFIX} ${component}: ${body}`;
+}
+function requiredProp(component, prop, hint) {
+  return message(component, `prop "${prop}" is required${hint === void 0 ? "." : ` \u2014 ${hint}`}`);
+}
+function oneOf(component, prop, allowed, got) {
+  return message(
+    component,
+    `prop "${prop}" must be one of ${allowed.map((value) => `'${value}'`).join(" | ")} \u2014 got ${JSON.stringify(got)}.`
+  );
+}
+function deprecatedProp(component, oldProp, newProp, removeIn) {
+  return message(
+    component,
+    `prop "${oldProp}" is deprecated \u2014 use "${newProp}" instead. "${oldProp}" is removed in ${removeIn}.`
+  );
+}
+function missingLayer(component, layer, remedy) {
+  return message(component, `needs ${layer}, which is not available \u2014 ${remedy}.`);
+}
+function duplicateMount(component) {
+  return message(
+    component,
+    "more than one instance is mounted at once \u2014 mount exactly one, at the app root."
+  );
+}
+function errorStatus(err) {
+  if (err === null || typeof err !== "object") return void 0;
+  const status = err.status;
+  return typeof status === "number" ? status : void 0;
+}
+const UNUSABLE_MESSAGES = /* @__PURE__ */ new Set(["", "{}", "[]", "null", "undefined", "[object Object]"]);
+function decodeError(err) {
+  if (err instanceof Error) return err.message;
+  if (typeof err === "string") return err;
+  if (typeof err === "object" && err !== null) {
+    const obj = err;
+    if (typeof obj["message"] === "string") return obj["message"];
+    if ("value" in obj) return decodeError(obj["value"]);
+  }
+  try {
+    return JSON.stringify(err) ?? "";
+  } catch {
+    return String(err);
+  }
+}
+function toErrorMessage(err, fallback = "The request failed.") {
+  const decoded = decodeError(err).trim();
+  if (!UNUSABLE_MESSAGES.has(decoded)) return decoded;
+  const status = errorStatus(err);
+  return status === void 0 ? fallback : `${fallback} (HTTP ${status})`;
+}
+export {
+  BASALT_PREFIX,
+  deprecatedProp,
+  duplicateMount,
+  errorStatus,
+  missingLayer,
+  oneOf,
+  requiredProp,
+  toErrorMessage
+};

package/dist/common/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `common` — the prop, ref, message and validation primitives every basalt component shares.
+ *
+ * Not a published subpath: the pieces are re-exported from the root barrel (`.`) so a consumer has
+ * one import, and `src/surfaces.ts` stays the SSOT for real subpaths. The module is Mantine-free by
+ * rule (`.oxlintrc.json`) and by test (`boundary.test.ts`), so the Mantine-free half of the library
+ * may reach it too.
+ */
+export { type BasaltProps, type SlotClassNames, type SlotStylesProps } from './props.js';
+export { type Tone, type ToneWithNeutral, type Tier, cx } from './props.js';
+export { assignRef, mergeRefs } from './refs.js';
+export { BASALT_PREFIX, requiredProp, oneOf, deprecatedProp, duplicateMount, missingLayer, } from './errors.js';
+export { useValidateProps, assertRequiredProps, resetValidatedProps } from './validate.js';
+export { scrollParentOf, SCROLLPORT_ATTRIBUTE } from './scroll-parent.js';
+export { isDev } from './is-dev.js';
+export { MOTION_DURATION, MOTION_EASE_STANDARD, MOTION_SPRING } from './motion.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/common/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,cAAc,EAAE,KAAK,eAAe,EAAE,MAAM,SAAS,CAAA;AACrF,OAAO,EAAE,KAAK,IAAI,EAAE,KAAK,eAAe,EAAE,KAAK,IAAI,EAAE,EAAE,EAAE,MAAM,SAAS,CAAA;AACxE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAA;AAC7C,OAAO,EACL,aAAa,EACb,YAAY,EACZ,KAAK,EACL,cAAc,EACd,cAAc,EACd,YAAY,GACb,MAAM,UAAU,CAAA;AACjB,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AACvF,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AACtE,OAAO,EAAE,KAAK,EAAE,MAAM,UAAU,CAAA;AAChC,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA"}

package/dist/common/index.js

@@ -0,0 +1,35 @@
+import {} from "./props.js";
+import { cx } from "./props.js";
+import { assignRef, mergeRefs } from "./refs.js";
+import {
+  BASALT_PREFIX,
+  requiredProp,
+  oneOf,
+  deprecatedProp,
+  duplicateMount,
+  missingLayer
+} from "./errors.js";
+import { useValidateProps, assertRequiredProps, resetValidatedProps } from "./validate.js";
+import { scrollParentOf, SCROLLPORT_ATTRIBUTE } from "./scroll-parent.js";
+import { isDev } from "./is-dev.js";
+import { MOTION_DURATION, MOTION_EASE_STANDARD, MOTION_SPRING } from "./motion.js";
+export {
+  BASALT_PREFIX,
+  MOTION_DURATION,
+  MOTION_EASE_STANDARD,
+  MOTION_SPRING,
+  SCROLLPORT_ATTRIBUTE,
+  assertRequiredProps,
+  assignRef,
+  cx,
+  deprecatedProp,
+  duplicateMount,
+  isDev,
+  mergeRefs,
+  missingLayer,
+  oneOf,
+  requiredProp,
+  resetValidatedProps,
+  scrollParentOf,
+  useValidateProps
+};

package/dist/common/is-dev.d.ts

@@ -0,0 +1,3 @@
+/** Dev-mode gate. Bundlers constant-fold `process.env.NODE_ENV` so the branch disappears in production builds. */
+export declare function isDev(): boolean;
+//# sourceMappingURL=is-dev.d.ts.map

package/dist/common/is-dev.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"is-dev.d.ts","sourceRoot":"","sources":["../../src/common/is-dev.ts"],"names":[],"mappings":"AAAA,kHAAkH;AAClH,wBAAgB,KAAK,IAAI,OAAO,CAE/B"}

package/dist/common/is-dev.js

@@ -0,0 +1,6 @@
+function isDev() {
+  return process.env["NODE_ENV"] !== "production";
+}
+export {
+  isDev
+};

package/dist/{motion/index.d.ts → common/motion.d.ts}

@@ -26,4 +26,4 @@ export declare const MOTION_SPRING: {
     readonly damping: 32;
     readonly mass: 0.9;
 };
-//# sourceMappingURL=index.d.ts.map
+//# sourceMappingURL=motion.d.ts.map

package/dist/common/motion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"motion.d.ts","sourceRoot":"","sources":["../../src/common/motion.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;GAIG;AACH,eAAO,MAAM,eAAe;;;;CAIlB,CAAA;AAEV,6EAA6E;AAC7E,eAAO,MAAM,oBAAoB,2BAA4B,CAAA;AAE7D,4FAA4F;AAC5F,eAAO,MAAM,aAAa;;;;;CAAsE,CAAA"}

package/dist/common/props.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The prop vocabulary every basalt component shares (Blueprint audit §1, isomorphic finding C8).
+ *
+ * The finding this file answers: 98 of 123 exported components drop `className`, so a consumer who
+ * needs one margin has to fork the component. Fixing that per component is 79 edits; fixing it once
+ * here is one — every component's props type extends `BasaltProps`, and the root element takes
+ * `cx(classes.root, className)` plus `style`.
+ *
+ * **`className` + per-slot `classNames`, and nothing else.** No `styles` object, no `vars`: basalt
+ * does not spread `...rest` onto the DOM (which is why the harness saw zero unknown-attribute
+ * warnings), and a `styles`/`vars` surface would re-open the styling seam Mantine already owns for
+ * the primitives underneath. A composite that needs more than its root styled declares its SLOT
+ * NAMES in its own props type — `SlotStylesProps<'root' | 'header' | 'body'>` — so the slot set is
+ * a documented, compiler-checked union rather than an open record.
+ *
+ * This module is **Mantine-free and React-type-only** so `./charts` and `./tokens` may reach it
+ * without breaching the layer boundary (`common/boundary.test.ts` pins that, and `.oxlintrc.json`
+ * bans `@mantine/*` here the same way it does for `state`/`query`/`guard`).
+ */
+import type { CSSProperties } from 'react';
+/**
+ * The base every basalt component accepts. `| undefined` is explicit on both members because
+ * `exactOptionalPropertyTypes` is on: a component destructuring `className` and forwarding it to a
+ * child would otherwise fail to type-check at every call site.
+ */
+export interface BasaltProps {
+    /** Appended to the root element's own class — never replaces it. */
+    readonly className?: string | undefined;
+    /** Merged onto the root element's own inline style, if it has one. */
+    readonly style?: CSSProperties | undefined;
+}
+/** One class per named slot. The slot union is the component's documented contract. */
+export type SlotClassNames<S extends string> = Partial<Record<S, string>>;
+/**
+ * The composite half of the contract: a container that paints more than one box publishes its slot
+ * names here. The set is small on purpose — `Section`, `StatCard`, `ChartCard`, `PageBar`,
+ * `PageAside`, `WidgetHeader`, `EmptyState`, `QueryState`, `BasaltDataTable`. A leaf takes
+ * `BasaltProps` alone.
+ */
+export interface SlotStylesProps<S extends string> {
+    readonly classNames?: SlotClassNames<S> | undefined;
+}
+/**
+ * The ONE status vocabulary (audit A13). Five forks exist today — `StatCardTone` and
+ * `SidebarBlockTone` are byte-identical to this, `CalloutKind` / `AccountBadgeTone` /
+ * `NotificationIntent` each differ — and they stay put for now: an adopter aliases its fork to this
+ * type, it does not get renamed out from under a consumer.
+ */
+export type Tone = 'good' | 'warn' | 'bad';
+/** `Tone` plus the un-toned state — a badge or a block with nothing to say yet. */
+export type ToneWithNeutral = Tone | 'neutral';
+/**
+ * The heading tier (`docs/CONTROLS-SPEC.md` §2.2). Re-exported from its owner rather than declared
+ * twice — `WidgetHeaderTier` stays the name on the public barrel; `Tier` is what `common`-aware
+ * code spells. Type-only, so this file emits no runtime edge into the Mantine-coupled half.
+ */
+export type { WidgetHeaderTier as Tier } from '../dashboard/widget-header.js';
+/**
+ * The class joiner. Replaces the `[a, b].filter(Boolean).join(' ')` spelled out in seven files
+ * today; falsy parts drop, so `cx(classes.root, open && classes.open, className)` is the idiom.
+ */
+export declare function cx(...parts: Array<string | false | null | undefined>): string;
+//# sourceMappingURL=props.d.ts.map

package/dist/common/props.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"props.d.ts","sourceRoot":"","sources":["../../src/common/props.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AAE1C;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,oEAAoE;IACpE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC,sEAAsE;IACtE,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,GAAG,SAAS,CAAA;CAC3C;AAED,uFAAuF;AACvF,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAA;AAEzE;;;;;GAKG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,MAAM;IAC/C,QAAQ,CAAC,UAAU,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,SAAS,CAAA;CACpD;AAED;;;;;GAKG;AACH,MAAM,MAAM,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,CAAA;AAE1C,mFAAmF;AACnF,MAAM,MAAM,eAAe,GAAG,IAAI,GAAG,SAAS,CAAA;AAE9C;;;;GAIG;AACH,YAAY,EAAE,gBAAgB,IAAI,IAAI,EAAE,MAAM,4BAA4B,CAAA;AAE1E;;;GAGG;AACH,wBAAgB,EAAE,CAAC,GAAG,KAAK,EAAE,KAAK,CAAC,MAAM,GAAG,KAAK,GAAG,IAAI,GAAG,SAAS,CAAC,GAAG,MAAM,CAE7E"}

package/dist/common/props.js

@@ -0,0 +1,6 @@
+function cx(...parts) {
+  return parts.filter((part) => typeof part === "string" && part !== "").join(" ");
+}
+export {
+  cx
+};

package/dist/common/query-state-like.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The query envelope every basalt container reads, and the ONE runtime assertion that stands in for
+ * the compiler over it.
+ *
+ * It lives in `common/` because two independent readers grew their own copy and the copies
+ * DISAGREED: `QueryState` (`dashboard/query-state.tsx`) checked the `data` key and that `refetch` is
+ * a function; `dataQueryBranch` (`data/query-branch.ts`) checked neither, so the table accepted a
+ * result whose Retry button did nothing. A validator that exists twice is a validator with two
+ * strictnesses, which is exactly the class of defect the assertion exists to catch.
+ *
+ * Mantine-free by construction (`common/boundary.test.ts`): types, a set and a throw.
+ */
+/**
+ * The structural subset of a TanStack `UseQueryResult` these components read.
+ *
+ * Typed as a SUBSET rather than as `UseQueryResult<T>` on purpose: a composed, derived or
+ * hand-rolled result must be passable without a cast, and the components stay independent of which
+ * `@tanstack/react-query` major a consumer pins. This is NOT a claim that the root barrel is free of
+ * that package — `./connectivity` imports `onlineManager` as a value and is re-exported from
+ * `src/index.ts`. The cost of the subset is that the compiler stops policing the shape — which is
+ * why {@link assertQueryStateLike} checks it at runtime.
+ */
+export type QueryStateLike<TData> = {
+    data: TData | undefined;
+    isError: boolean;
+    error: unknown;
+    fetchStatus: 'fetching' | 'paused' | 'idle';
+    refetch: () => unknown;
+};
+/** The three `fetchStatus` values a `UseQueryResult` can carry. */
+export declare const FETCH_STATUSES: ReadonlySet<string>;
+/**
+ * `QueryStateLike` is a structural subset, so TypeScript cannot protect a hand-composed result the
+ * way it protects a real `UseQueryResult` — and every field it drops fails SILENTLY in the exact
+ * direction these components exist to prevent. A missing `isError` renders "no data" over a 500. A
+ * misspelled `fetchStatus` never leaves the spinner. A missing `refetch` renders a Retry button that
+ * does nothing. Each of those is a false claim about the data, so it throws.
+ *
+ * `component` opens the message so the throw names the container that got the bad envelope —
+ * `QueryState`, `BasaltDataTable`, `BasaltVirtualList` all read the same shape.
+ */
+export declare function assertQueryStateLike(component: string, query: unknown): asserts query is QueryStateLike<unknown>;
+//# sourceMappingURL=query-state-like.d.ts.map

package/dist/common/query-state-like.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-state-like.d.ts","sourceRoot":"","sources":["../../src/common/query-state-like.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;;;;;GASG;AACH,MAAM,MAAM,cAAc,CAAC,KAAK,IAAI;IAClC,IAAI,EAAE,KAAK,GAAG,SAAS,CAAA;IACvB,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,EAAE,OAAO,CAAA;IACd,WAAW,EAAE,UAAU,GAAG,QAAQ,GAAG,MAAM,CAAA;IAC3C,OAAO,EAAE,MAAM,OAAO,CAAA;CACvB,CAAA;AAED,mEAAmE;AACnE,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,MAAM,CAA2C,CAAA;AAE1F;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,KAAK,IAAI,cAAc,CAAC,OAAO,CAAC,CAgB1C"}

package/dist/common/query-state-like.js

@@ -0,0 +1,20 @@
+const FETCH_STATUSES = /* @__PURE__ */ new Set(["fetching", "paused", "idle"]);
+function assertQueryStateLike(component, query) {
+  const bad = (detail) => {
+    throw new Error(
+      `${component}: \`query\` ${detail}. It must carry { data, isError, error, fetchStatus, refetch } \u2014 a TanStack UseQueryResult does; a hand-composed one must spell every field, because a missing branch flag renders a false claim about the data instead of an error.`
+    );
+  };
+  if (query === null || typeof query !== "object")
+    bad(`is ${query === null ? "null" : typeof query}`);
+  const q = query;
+  if (!("data" in q)) bad("has no `data` key");
+  if (typeof q["isError"] !== "boolean") bad("has no boolean `isError`");
+  if (typeof q["fetchStatus"] !== "string" || !FETCH_STATUSES.has(q["fetchStatus"]))
+    bad(`has fetchStatus=${JSON.stringify(q["fetchStatus"])}, not 'fetching' | 'paused' | 'idle'`);
+  if (typeof q["refetch"] !== "function") bad("has no `refetch()`");
+}
+export {
+  FETCH_STATUSES,
+  assertQueryStateLike
+};

package/dist/common/refs.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Ref plumbing for composites (Blueprint audit §2). React 19 made `ref` an ordinary prop, which
+ * removed `forwardRef` — it did NOT remove the need to merge: a component that both forwards its
+ * caller's ref and keeps its own (a measurement, a focus target) still has two refs and one node.
+ *
+ * The React 19 wrinkle these two functions exist to get right: a callback ref MAY return a cleanup
+ * function, and when it does React never calls it again with `null`. So merging cannot just fan out
+ * — it has to fan out the cleanups too, and null out the refs that returned none.
+ */
+import type { Ref, RefCallback } from 'react';
+/**
+ * Writes `value` into one ref of either shape.
+ *
+ * @returns the callback ref's own cleanup when it returned one, else `undefined`.
+ */
+export declare function assignRef<T>(ref: Ref<T> | undefined, value: T | null): (() => void) | undefined;
+/**
+ * Fans one node out to several refs.
+ *
+ * Returns a NEW function on every call, so a component that passes it straight to JSX re-attaches
+ * on every render — wrap it in `useCallback`/`useMemo` over the refs it merges when the node is
+ * expensive to re-attach.
+ *
+ * @example
+ * const merged = useMemo(() => mergeRefs(ref, localRef), [ref])
+ * return <div ref={merged} />
+ */
+export declare function mergeRefs<T>(...refs: Array<Ref<T> | undefined>): RefCallback<T>;
+//# sourceMappingURL=refs.d.ts.map

package/dist/common/refs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refs.d.ts","sourceRoot":"","sources":["../../src/common/refs.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,OAAO,CAAA;AAE7C;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,GAAG,SAAS,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAU/F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAkB/E"}

package/dist/common/refs.js

@@ -0,0 +1,29 @@
+function assignRef(ref, value) {
+  if (ref === void 0 || ref === null) return void 0;
+  if (typeof ref === "function") {
+    const cleanup = ref(value);
+    return typeof cleanup === "function" ? cleanup : void 0;
+  }
+  ref.current = value;
+  return void 0;
+}
+function mergeRefs(...refs) {
+  return (value) => {
+    const cleanups = refs.map((ref) => assignRef(ref, value));
+    if (cleanups.every((cleanup) => cleanup === void 0)) return void 0;
+    return () => {
+      refs.forEach((ref, index) => {
+        const cleanup = cleanups[index];
+        if (cleanup !== void 0) {
+          cleanup();
+          return;
+        }
+        assignRef(ref, null);
+      });
+    };
+  };
+}
+export {
+  assignRef,
+  mergeRefs
+};

package/dist/common/scroll-parent.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `scrollParentOf` — which box actually scrolls `el`.
+ *
+ * Since `BasaltShell` made `AppShell.Main` the scrollport (`shell/app-main.module.css`), the
+ * document no longer scrolls inside a shell: `window.scrollY` is pinned at 0 and a `scroll`
+ * listener on `window` never fires. Everything in the package that reacted to page scroll had to
+ * stop asking the window and start asking whichever ancestor is really scrolling — and it has to
+ * keep working in a SHELL-LESS app, where the answer genuinely is the window.
+ *
+ * `null` IS the answer for "the document scrolls this", not a failure — callers listen on `window`
+ * and read `window.scrollY` in that case.
+ */
+/** The attribute `BasaltShell` puts on `AppShell.Main`. Also the public handle for a consumer. */
+export declare const SCROLLPORT_ATTRIBUTE = "data-basalt-scrollport";
+/**
+ * The nearest scrolling ANCESTOR of `el`, or `null` when the document is the scroller.
+ *
+ * `el` itself is never considered — the question is which box scrolls it, not whether it scrolls
+ * its own children. `<body>` and `<html>` are never returned either: an app that scrolls at the
+ * document level is exactly the `null` case.
+ */
+export declare function scrollParentOf(el: Element | null): HTMLElement | null;
+//# sourceMappingURL=scroll-parent.d.ts.map

package/dist/common/scroll-parent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scroll-parent.d.ts","sourceRoot":"","sources":["../../src/common/scroll-parent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,kGAAkG;AAClG,eAAO,MAAM,oBAAoB,2BAA2B,CAAA;AAW5D;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,GAAG,WAAW,GAAG,IAAI,CASrE"}

package/dist/common/scroll-parent.js

@@ -0,0 +1,21 @@
+const SCROLLPORT_ATTRIBUTE = "data-basalt-scrollport";
+function isScrollport(element) {
+  if (element.hasAttribute(SCROLLPORT_ATTRIBUTE)) return true;
+  const overflowY = getComputedStyle(element).overflowY;
+  if (overflowY !== "auto" && overflowY !== "scroll") return false;
+  return element.scrollHeight > element.clientHeight;
+}
+function scrollParentOf(el) {
+  if (el === null || typeof window === "undefined") return null;
+  const root = el.ownerDocument.documentElement;
+  let node = el.parentElement;
+  while (node !== null && node !== root && node !== el.ownerDocument.body) {
+    if (isScrollport(node)) return node;
+    node = node.parentElement;
+  }
+  return null;
+}
+export {
+  SCROLLPORT_ATTRIBUTE,
+  scrollParentOf
+};

package/dist/common/validate.d.ts

@@ -0,0 +1,38 @@
+/** A check returns the message(s) it has, or nothing. `null`/`undefined` entries are ignored. */
+type CheckResult = string | null | undefined | Array<string | null | undefined>;
+/**
+ * Dev-only prop validation. `console.error`s each message ONCE per `(component, message)` pair, and
+ * is a no-op in production: `isDev()` reads `process.env.NODE_ENV`, which every bundler
+ * constant-folds, so the whole body disappears from a production build.
+ *
+ * **The dedup key is `${component} ${message}`, and nothing else** — not the instance, not the
+ * props. Two instances of one component producing the SAME message say it once between them, which
+ * is the intent (a dev warning is about the code). A caller that wants it said per instance has to
+ * embed the identifying context IN the message — the title, the persist key, the field name — the
+ * way `Section` writes `Section "<title>": …`. A message built from nothing instance-specific is a
+ * message the second faulty call site never gets.
+ *
+ * @example
+ * useValidateProps(
+ *   'Section',
+ *   () => (persistKey !== undefined && !collapsible ? sectionPersistMessage : null),
+ *   [persistKey, collapsible],
+ * )
+ */
+export declare function useValidateProps(component: string, check: () => CheckResult, deps: unknown[]): void;
+/** Test seam. The once-per-message Set is module state, so a suite has to be able to clear it. */
+export declare function resetValidatedProps(): void;
+/**
+ * THROWS on a missing required prop, in every build, before the component reads into it.
+ *
+ * This is the F-ERR-1 remedy, and the reason it is not dev-gated: the component was going to crash
+ * either way (`undefined is not an object (evaluating 'field.use')`), so the only thing in question
+ * is whether the stack reaching `BasaltErrorBoundary` names the component and the prop. It does
+ * now. A prop that is merely questionable belongs in `useValidateProps`, not here.
+ *
+ * @example
+ * assertRequiredProps('SelectFilter', props, ['field'])
+ */
+export declare function assertRequiredProps<P extends object>(component: string, props: P, keys: ReadonlyArray<Extract<keyof P, string>>, hints?: Partial<Record<Extract<keyof P, string>, string>>): void;
+export {};
+//# sourceMappingURL=validate.d.ts.map

package/dist/common/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/common/validate.ts"],"names":[],"mappings":"AAYA,iGAAiG;AACjG,KAAK,WAAW,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,KAAK,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAA;AAU/E;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,WAAW,EACxB,IAAI,EAAE,OAAO,EAAE,GACd,IAAI,CAeN;AAED,kGAAkG;AAClG,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,MAAM,EAClD,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,CAAC,EACR,IAAI,EAAE,aAAa,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,EAC7C,KAAK,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,GACxD,IAAI,CASN"}

package/dist/common/validate.js

@@ -0,0 +1,36 @@
+import { useEffect } from "react";
+import { isDev } from "./is-dev.js";
+import { requiredProp } from "./errors.js";
+const reported = /* @__PURE__ */ new Set();
+function useValidateProps(component, check, deps) {
+  useEffect(() => {
+    if (!isDev()) return;
+    const result = check();
+    const messages = Array.isArray(result) ? result : [result];
+    for (const raw of messages) {
+      if (raw === null || raw === void 0) continue;
+      const key = `${component} ${raw}`;
+      if (reported.has(key)) continue;
+      reported.add(key);
+      console.error(raw);
+    }
+  }, deps);
+}
+function resetValidatedProps() {
+  reported.clear();
+}
+function assertRequiredProps(component, props, keys, hints) {
+  for (const key of keys) {
+    const value = props[key];
+    if (value !== void 0 && value !== null) continue;
+    const hint = hints?.[key];
+    throw new Error(
+      hint === void 0 ? requiredProp(component, key) : requiredProp(component, key, hint)
+    );
+  }
+}
+export {
+  assertRequiredProps,
+  resetValidatedProps,
+  useValidateProps
+};

package/dist/content/article-layout.module.css

@@ -17,6 +17,11 @@
   grid-template-columns: minmax(0, var(--vx-prose-measure));
 }
 
+/* The literal below MUST equal `BREAKPOINTS.article` (src/tokens/index.ts) — a `@media`
+ * condition is resolved before custom properties exist, so `max-width: var(--x)` is invalid CSS
+ * and a stylesheet with a responsive rule has no choice but to write the number. The token is the
+ * readable half; `article-layout.breakpoint.test.ts` asserts the two agree, the same
+ * "literal must match the token" idiom as `styles.floor.test.ts`. Change both or neither. */
 @media (max-width: 1200px) {
   .root {
     grid-template-columns: minmax(0, var(--vx-prose-measure));
@@ -72,10 +77,12 @@
 .tocRail {
   grid-column: 2;
   position: sticky;
-  /* DESKTOP-only value on purpose (no `< sm` override needed): the rail is already `display: none`
-   * below the 1200px `@media` breakpoint just above, well above the `sm` (48em/768px) breakpoint
-   * that switches BasaltShell's header — and, by extension, this clearance — to its mobile value
-   * (see `content/prose.module.css` for the responsive split; docs/CONTENT-SPEC.md §5). */
+  /* The rail sticks inside whatever scrolls it — `AppShell.Main` in a shell, the document without
+   * one — and NOTHING overhangs that box: the app header and `PageBar` row 2's band are both shell
+   * regions rendered outside the scrollport (`shell/app-main.module.css`). So the offset is
+   * `--vx-space-sticky-header-clearance` and nothing else, which is exactly what that token means
+   * since it stopped carrying a header height (tokens/palette.ts, `deriveSpacing`;
+   * docs/CONTENT-SPEC.md §5). */
   top: var(--vx-space-sticky-header-clearance);
   align-self: start;
 }

package/dist/content/callout.d.ts

@@ -8,17 +8,21 @@
  *   <p>This endpoint is rate-limited to 60 requests/minute.</p>
  * </Callout>
  */
-import type { CSSProperties, ReactNode } from 'react';
+import type { ReactNode } from 'react';
+import type { BasaltProps } from '../common/props.js';
+/**
+ * One of the five `Tone` forks (`common/props.ts`) — kept as its own type because `info` has no
+ * `Tone` equivalent: `good`/`warn`/`bad` line up with `Tone` exactly, `info` is the extra kind a
+ * callout needs that a status badge does not.
+ */
 export type CalloutKind = 'info' | 'good' | 'warn' | 'bad';
-export type CalloutProps = {
+export type CalloutProps = BasaltProps & {
     /** Semantic kind — drives the rail/tint color and the default icon. Default `'info'`. */
     readonly kind?: CalloutKind;
     readonly title?: string;
     /** Overrides the default per-kind icon. Only rendered alongside a `title`. */
     readonly icon?: ReactNode;
     readonly children: ReactNode;
-    readonly className?: string;
-    readonly style?: CSSProperties;
 };
 export declare function Callout({ kind, title, icon, children, className, style }: CalloutProps): import("react").JSX.Element;
 //# sourceMappingURL=callout.d.ts.map

package/dist/content/callout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"callout.d.ts","sourceRoot":"","sources":["../../src/content/callout.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAGrD,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,CAAA;AAE1D,MAAM,MAAM,YAAY,GAAG;IACzB,yFAAyF;IACzF,QAAQ,CAAC,IAAI,CAAC,EAAE,WAAW,CAAA;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAA;IACzB,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAA;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAA;CAC/B,CAAA;AAyDD,wBAAgB,OAAO,CAAC,EAAE,IAAa,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,YAAY,+BAc/F"}
+{"version":3,"file":"callout.d.ts","sourceRoot":"","sources":["../../src/content/callout.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEtC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAGlD;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,CAAA;AAE1D,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG;IACvC,yFAAyF;IACzF,QAAQ,CAAC,IAAI,CAAC,EAAE,WAAW,CAAA;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAA;IACzB,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAA;CAC7B,CAAA;AAyDD,wBAAgB,OAAO,CAAC,EAAE,IAAa,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,YAAY,+BAe/F"}