basalt-ui 1.27.0 → 1.28.0

package/dist/commands/index.d.ts

@@ -28,12 +28,21 @@
  * import { runCommand } from 'basalt-ui/commands'
  * runCommand('file:save')
  *
+ * // usage.ts — the registry-free confirm dialog:
+ * import { overlays } from 'basalt-ui/commands'
+ * const ok = await overlays.confirm({ title: 'Discard draft?', onConfirm: () => reset() })
+ * overlays.confirmDelete({ subject: 'item', count: 3, onConfirm: () => removeSelected() })
+ *
+ * // Mounting ModalsProvider yourself instead of letting <BasaltOverlays> do it:
+ * import { registerModalsProvider } from 'basalt-ui/commands'
+ * useEffect(() => registerModalsProvider(), [])
+ *
  * // Open/close Spotlight programmatically:
  * import { openSpotlight, closeSpotlight } from 'basalt-ui/commands'
  * openSpotlight()
  */
 export { defineCommands, defineCommand, runCommand, type Command, type CommandMap, type CommandId, type CommandRunContext, } from './define-commands.js';
-export { defineOverlays, defineOverlay, overlays, type Overlay, type OverlayMap, type OverlayKey, } from './define-overlays.js';
+export { defineOverlays, defineOverlay, overlays, registerModalsProvider, type Overlay, type OverlayMap, type OverlayKey, type ConfirmOptions, type ConfirmDeleteOptions, } from './define-overlays.js';
 export { toSpotlightActions, toRouteActions, toShortcutList, toHotkeyBindings, type RouteActionItem, type RouteActionSection, type ToRouteActionsOptions, type ShortcutEntry, type HotkeyBinding, } from './projectors.js';
 export { parseShortcut, detectMac, formatShortcutDisplay } from './shortcut-format.js';
 export { useCommandHotkeys } from './useCommandHotkeys.js';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/commands/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAGH,OAAO,EACL,cAAc,EACd,aAAa,EACb,UAAU,EACV,KAAK,OAAO,EACZ,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,iBAAiB,GACvB,MAAM,mBAAmB,CAAA;AAG1B,OAAO,EACL,cAAc,EACd,aAAa,EACb,QAAQ,EACR,KAAK,OAAO,EACZ,KAAK,UAAU,EACf,KAAK,UAAU,GAChB,MAAM,mBAAmB,CAAA;AAG1B,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,cAAc,EACd,gBAAgB,EAChB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,aAAa,EAClB,KAAK,aAAa,GACnB,MAAM,cAAc,CAAA;AAGrB,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAA;AAGnF,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAGvD,OAAO,EAAE,aAAa,EAAE,KAAK,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AAGxE,OAAO,EACL,cAAc,EACd,KAAK,mBAAmB,EACxB,eAAe,EACf,aAAa,EACb,cAAc,GACf,MAAM,kBAAkB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/commands/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAGH,OAAO,EACL,cAAc,EACd,aAAa,EACb,UAAU,EACV,KAAK,OAAO,EACZ,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,iBAAiB,GACvB,MAAM,mBAAmB,CAAA;AAG1B,OAAO,EACL,cAAc,EACd,aAAa,EACb,QAAQ,EACR,sBAAsB,EACtB,KAAK,OAAO,EACZ,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,oBAAoB,GAC1B,MAAM,mBAAmB,CAAA;AAG1B,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,cAAc,EACd,gBAAgB,EAChB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,aAAa,EAClB,KAAK,aAAa,GACnB,MAAM,cAAc,CAAA;AAGrB,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAA;AAGnF,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAGvD,OAAO,EAAE,aAAa,EAAE,KAAK,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AAGxE,OAAO,EACL,cAAc,EACd,KAAK,mBAAmB,EACxB,eAAe,EACf,aAAa,EACb,cAAc,GACf,MAAM,kBAAkB,CAAA"}

package/dist/commands/index.js

@@ -6,7 +6,8 @@ import {
 import {
   defineOverlays,
   defineOverlay,
-  overlays
+  overlays,
+  registerModalsProvider
 } from "./define-overlays.js";
 import {
   toSpotlightActions,
@@ -37,6 +38,7 @@ export {
   openSpotlight,
   overlays,
   parseShortcut,
+  registerModalsProvider,
   runCommand,
   toHotkeyBindings,
   toRouteActions,

package/dist/commands/overlays-mount.d.ts

@@ -2,9 +2,16 @@
  * overlays-mount — composable overlay mount for basalt-ui apps.
  *
  * `BasaltOverlays` bundles ModalsProvider, Spotlight, and Notifications into a single mount point.
- * Put it inside BasaltProvider, before the router. It replaces the standalone `<BasaltNotifications />`
- * from `basalt-ui/notifications` — do NOT mount both `<BasaltOverlays notifications />` and
- * `<BasaltNotifications />` in the same tree (double-mount of `<Notifications />`).
+ * Put it inside BasaltProvider, before the router. It replaces the standalone
+ * `<BasaltNotifications />` from `basalt-ui/notifications` — do NOT mount both
+ * `<BasaltOverlays notifications />` and `<BasaltNotifications />` in the same tree (double-mount
+ * of `<Notifications />`).
+ *
+ * Every layer — ModalsProvider included — mounts as a SIBLING of `children`, never as a wrapper:
+ * see the comment in the component body (R1). `@mantine/modals`' imperative API (`modals.open*`,
+ * and so basalt's own `overlays.open`) is a window CustomEvent bus that ModalsProvider subscribes
+ * to, so nothing needs to be inside it; the one thing a sibling cannot serve is Mantine's
+ * `useModals()` context hook.
  *
  * Each overlay system is opt-in via props (all default to true). Use flags to disable layers the
  * app does not need — e.g. a charts-only app that has no commands can set `spotlight={false}`.
@@ -98,9 +105,9 @@ export type BasaltOverlaysProps = {
     children: ReactNode;
 };
 /**
- * Composable overlay mount — wraps children in ModalsProvider and renders Spotlight +
- * Notifications siblings. All three layers are enabled by default; pass `false` to disable.
- * A disabled layer's optional peer is never imported.
+ * Composable overlay mount — renders ModalsProvider, Spotlight and Notifications as siblings of
+ * `children`. All three layers are enabled by default; pass `false` to disable. A disabled layer's
+ * optional peer is never imported.
  *
  * Mount exactly ONE BasaltOverlays per app. Do NOT combine with a standalone
  * `<BasaltNotifications />` from `basalt-ui/notifications` — that would double-mount

package/dist/commands/overlays-mount.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"overlays-mount.d.ts","sourceRoot":"","sources":["../../src/commands/overlays-mount.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,OAAO,KAAK,EAAiB,SAAS,EAAE,MAAM,OAAO,CAAA;AAGrD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAChE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AAiC7D;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe;gBAChB,IAAI;iBAGH,IAAI;kBAGH,IAAI;CAGjB,CAAA;AAID,0DAA0D;AAC1D,wBAAgB,aAAa,IAAI,IAAI,CAEpC;AAED,2DAA2D;AAC3D,wBAAgB,cAAc,IAAI,IAAI,CAErC;AAID,MAAM,MAAM,mBAAmB,GAAG;IAChC,2DAA2D;IAC3D,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,yEAAyE;IACzE,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,iJAAiJ;IACjJ,kBAAkB,CAAC,EAAE,IAAI,CAAC,kBAAkB,EAAE,UAAU,CAAC,CAAA;IACzD;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,mBAAmB,EAAE,CAAA;IACxC;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,8BAA8B;IAC9B,QAAQ,EAAE,SAAS,CAAA;CACpB,CAAA;AA2FD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,EAC7B,MAAM,EAAE,YAAmB,EAC3B,SAAS,EAAE,eAAsB,EACjC,aAAa,EAAE,mBAA0B,EACzC,OAAO,EAAE,aAAoB,EAC7B,kBAAkB,EAClB,gBAAgB,EAChB,eAAsB,EACtB,QAAQ,GACT,EAAE,mBAAmB,+BAmCrB"}
+{"version":3,"file":"overlays-mount.d.ts","sourceRoot":"","sources":["../../src/commands/overlays-mount.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,OAAO,KAAK,EAAiB,SAAS,EAAE,MAAM,OAAO,CAAA;AAGrD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAChE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AAmC7D;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe;gBAChB,IAAI;iBAGH,IAAI;kBAGH,IAAI;CAGjB,CAAA;AAID,0DAA0D;AAC1D,wBAAgB,aAAa,IAAI,IAAI,CAEpC;AAED,2DAA2D;AAC3D,wBAAgB,cAAc,IAAI,IAAI,CAErC;AAID,MAAM,MAAM,mBAAmB,GAAG;IAChC,2DAA2D;IAC3D,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,yEAAyE;IACzE,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,iJAAiJ;IACjJ,kBAAkB,CAAC,EAAE,IAAI,CAAC,kBAAkB,EAAE,UAAU,CAAC,CAAA;IACzD;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,mBAAmB,EAAE,CAAA;IACxC;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,8BAA8B;IAC9B,QAAQ,EAAE,SAAS,CAAA;CACpB,CAAA;AAqHD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,EAC7B,MAAM,EAAE,YAAmB,EAC3B,SAAS,EAAE,eAAsB,EACjC,aAAa,EAAE,mBAA0B,EACzC,OAAO,EAAE,aAAoB,EAC7B,kBAAkB,EAClB,gBAAgB,EAChB,eAAsB,EACtB,QAAQ,GACT,EAAE,mBAAmB,+BAkCrB"}

package/dist/commands/overlays-mount.js

@@ -1,8 +1,10 @@
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { lazy, Suspense } from "react";
 import { runCommand } from "./define-commands.js";
+import { useModalsLayer } from "./define-overlays.js";
 import { toSpotlightActions } from "./projectors.js";
 import { useCommandHotkeys } from "./useCommandHotkeys.js";
+import { useNotificationsMountGuard } from "../notifications/mount-guard.js";
 let spotlightHandlePromise;
 function loadSpotlightHandle() {
   spotlightHandlePromise ??= import("@mantine/spotlight").then(({ createSpotlight }) => {
@@ -34,6 +36,7 @@ function PassthroughFragment({ children }) {
 const LazyModalsProvider = lazy(
   () => import("@mantine/modals").then((m) => ({ default: m.ModalsProvider })).catch(() => ({ default: PassthroughFragment }))
 );
+Object.assign(LazyModalsProvider, { displayName: "LazyModalsProvider" });
 function NullFallback() {
   return null;
 }
@@ -63,12 +66,28 @@ const LazySpotlightMount = lazy(
     return { default: SpotlightMountInner };
   }).catch(() => ({ default: NullFallback }))
 );
+Object.assign(LazySpotlightMount, { displayName: "LazySpotlightMount" });
 function NotificationsFallback(_props) {
   return null;
 }
 const LazyNotifications = lazy(
   () => import("@mantine/notifications").then((m) => ({ default: m.Notifications })).catch(() => ({ default: NotificationsFallback }))
 );
+Object.assign(LazyNotifications, { displayName: "LazyNotifications" });
+function NotificationsLayer({
+  notificationsProps
+}) {
+  useNotificationsMountGuard();
+  return /* @__PURE__ */ jsx(Suspense, { fallback: null, children: /* @__PURE__ */ jsx(
+    LazyNotifications,
+    {
+      position: "bottom-right",
+      autoClose: 4e3,
+      limit: 5,
+      ...notificationsProps
+    }
+  ) });
+}
 function HotkeysMount() {
   useCommandHotkeys();
   return null;
@@ -83,7 +102,8 @@ function BasaltOverlays({
   projectCommands = true,
   children
 }) {
-  const content = /* @__PURE__ */ jsxs(Fragment, { children: [
+  useModalsLayer(enableModals);
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
     enableSpotlight && /* @__PURE__ */ jsx(Suspense, { fallback: null, children: /* @__PURE__ */ jsx(
       LazySpotlightMount,
       {
@@ -91,22 +111,11 @@ function BasaltOverlays({
         ...spotlightActions !== void 0 && { extraActions: spotlightActions }
       }
     ) }),
-    enableNotifications && /* @__PURE__ */ jsx(Suspense, { fallback: null, children: /* @__PURE__ */ jsx(
-      LazyNotifications,
-      {
-        position: "bottom-right",
-        autoClose: 4e3,
-        limit: 5,
-        ...notificationsProps
-      }
-    ) }),
+    enableNotifications && /* @__PURE__ */ jsx(NotificationsLayer, { notificationsProps }),
     enableHotkeys && /* @__PURE__ */ jsx(HotkeysMount, {}),
+    enableModals && /* @__PURE__ */ jsx(Suspense, { fallback: null, children: /* @__PURE__ */ jsx(LazyModalsProvider, {}) }),
     children
   ] });
-  if (enableModals) {
-    return /* @__PURE__ */ jsx(Suspense, { fallback: /* @__PURE__ */ jsx(Fragment, { children: content }), children: /* @__PURE__ */ jsx(LazyModalsProvider, { children: content }) });
-  }
-  return /* @__PURE__ */ jsx(Fragment, { children: content });
 }
 export {
   BasaltOverlays,

package/dist/common/errors.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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;
+//# 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"}

package/dist/common/errors.js

@@ -0,0 +1,36 @@
+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."
+  );
+}
+export {
+  BASALT_PREFIX,
+  deprecatedProp,
+  duplicateMount,
+  missingLayer,
+  oneOf,
+  requiredProp
+};

package/dist/common/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `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';
+//# 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"}

package/dist/common/index.js

@@ -0,0 +1,29 @@
+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";
+export {
+  BASALT_PREFIX,
+  SCROLLPORT_ATTRIBUTE,
+  assertRequiredProps,
+  assignRef,
+  cx,
+  deprecatedProp,
+  duplicateMount,
+  mergeRefs,
+  missingLayer,
+  oneOf,
+  requiredProp,
+  resetValidatedProps,
+  scrollParentOf,
+  useValidateProps
+};

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 '../widget-header/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,gCAAgC,CAAA;AAE9E;;;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 "../utils/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
+};