@ponchia/ui 0.4.0 → 0.5.0

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@ponchia/ui",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
-  "description": "CSS-first, framework-agnostic UI framework — token-driven restraint (monochrome by default, one rationed accent), OKLCH colorways, a dot-matrix icon set, a colourblind-safe data-viz palette, dot-matrix motifs, zero runtime dependencies.",
+  "description": "CSS-first design system for interfaces that explain themselves — works in HTML, every framework, and PDF, no component runtime. A standard component set plus an opt-in analytical & report layer (annotations, legends, connectors, data-viz, report grammar). Monochrome with one rationed accent, re-skinnable from one --accent knob. Zero runtime dependencies.",
   "keywords": [
     "css",
     "ui",
@@ -46,16 +46,37 @@
     "classes",
     "behaviors",
     "glyphs",
+    "annotations",
+    "connectors",
     "react",
     "solid",
+    "qwik",
     "shiki",
     "llms.txt",
     "CHANGELOG.md",
+    "MIGRATIONS.json",
+    "docs/architecture.md",
     "docs/reference.md",
     "docs/theming.md",
     "docs/contrast.md",
+    "docs/stability.md",
     "docs/usage.md",
-    "docs/adr/0001-color-system.md"
+    "docs/reporting.md",
+    "docs/annotations.md",
+    "docs/legends.md",
+    "docs/marks.md",
+    "docs/connectors.md",
+    "docs/spotlight.md",
+    "docs/crosshair.md",
+    "docs/selection.md",
+    "docs/sources.md",
+    "docs/state.md",
+    "docs/generated.md",
+    "docs/workbench.md",
+    "docs/command.md",
+    "docs/adr/0001-color-system.md",
+    "docs/adr/0002-scope-and-2026-baseline.md",
+    "docs/adr/0003-theme-model.md"
   ],
   "style": "./dist/bronto.css",
   "scripts": {
@@ -63,7 +84,9 @@
     "lint:fix": "stylelint \"css/**/*.css\" --fix",
     "format": "prettier --write .",
     "check:format": "prettier --check .",
+    "size:report": "node scripts/size-report.mjs",
     "tokens:build": "node scripts/gen-tokens-json.mjs",
+    "tokens:css:build": "node scripts/gen-tokens-css.mjs",
     "dtcg:build": "node scripts/gen-dtcg.mjs",
     "resolved:build": "node scripts/gen-resolved.mjs",
     "dts:build": "node scripts/gen-dts.mjs",
@@ -80,10 +103,13 @@
     "check:dts": "node scripts/check-dts.mjs",
     "check:behaviors": "node scripts/check-behaviors.mjs",
     "check:bindings": "node scripts/check-bindings.mjs",
+    "check:helpers-dts": "node scripts/check-helpers-dts.mjs",
     "check:glyphs": "node scripts/check-glyphs.mjs",
     "check:color-policy": "node scripts/check-color-policy.mjs",
     "check:skins": "node scripts/check-skins.mjs",
     "check:charts": "node scripts/check-charts.mjs",
+    "check:report": "node scripts/check-report.mjs",
+    "check:legend": "node scripts/check-legend.mjs",
     "check:types": "tsc -p tsconfig.json",
     "check:dtcg": "node scripts/check-dtcg.mjs",
     "check:resolved": "node scripts/check-resolved.mjs",
@@ -94,26 +120,34 @@
     "check:reference": "node scripts/check-reference.mjs",
     "check:contrast": "node scripts/check-contrast.mjs",
     "check:vscode": "node scripts/check-vscode-data.mjs",
-    "check": "npm run lint && npm run check:format && npm run check:exports && npm run check:tokens && npm run check:classes && npm run check:dts && npm run check:types && npm run check:dtcg && npm run check:resolved && npm run check:shiki && npm run check:dist && npm run check:pack && npm run check:release && npm run check:reference && npm run check:contrast && npm run check:vscode && npm run check:behaviors && npm run check:bindings && npm run check:glyphs && npm run check:color-policy && npm run check:skins && npm run check:charts",
+    "check": "npm run lint && npm run check:format && npm run check:exports && npm run check:tokens && npm run check:classes && npm run check:dts && npm run check:types && npm run check:dtcg && npm run check:resolved && npm run check:shiki && npm run check:dist && npm run check:pack && npm run check:release && npm run check:reference && npm run check:contrast && npm run check:vscode && npm run check:behaviors && npm run check:bindings && npm run check:helpers-dts && npm run check:glyphs && npm run check:color-policy && npm run check:skins && npm run check:charts && npm run check:report && npm run check:legend",
     "test": "node --test \"test/*.test.mjs\"",
-    "prepack": "npm run tokens:build && npm run dtcg:build && npm run resolved:build && npm run dts:build && npm run reference:build && npm run contrast:build && npm run vscode:build && npm run skins:build && npm run charts:build && npm run dist:build && npm run glyphs:build",
+    "prepack": "npm run tokens:css:build && npm run tokens:build && npm run dtcg:build && npm run resolved:build && npm run dts:build && npm run reference:build && npm run contrast:build && npm run vscode:build && npm run skins:build && npm run charts:build && npm run dist:build && npm run glyphs:build",
     "prepublishOnly": "npm run check && npm test"
   },
   "devDependencies": {
     "@axe-core/playwright": "^4.11.3",
+    "@builder.io/qwik": "^1.20.0",
     "@playwright/test": "^1.60.0",
     "jsdom": "^29.1.1",
     "prettier": "^3.8.3",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
+    "solid-js": "^1.9.13",
     "stylelint": "^17.11.1",
     "stylelint-config-standard": "^40.0.0",
     "stylelint-use-logical": "^2.1.3",
     "typescript": "^6.0.3"
   },
   "peerDependencies": {
+    "@builder.io/qwik": ">=1.5",
     "react": ">=18",
     "solid-js": ">=1.6"
   },
   "peerDependenciesMeta": {
+    "@builder.io/qwik": {
+      "optional": true
+    },
     "react": {
       "optional": true
     },
@@ -146,6 +180,20 @@
     "./css/app.css": "./dist/css/app.css",
     "./css/skins.css": "./dist/css/skins.css",
     "./css/dataviz.css": "./dist/css/dataviz.css",
+    "./css/report.css": "./dist/css/report.css",
+    "./css/annotations.css": "./dist/css/annotations.css",
+    "./css/legend.css": "./dist/css/legend.css",
+    "./css/marks.css": "./dist/css/marks.css",
+    "./css/connectors.css": "./dist/css/connectors.css",
+    "./css/spotlight.css": "./dist/css/spotlight.css",
+    "./css/crosshair.css": "./dist/css/crosshair.css",
+    "./css/selection.css": "./dist/css/selection.css",
+    "./css/sources.css": "./dist/css/sources.css",
+    "./css/state.css": "./dist/css/state.css",
+    "./css/generated.css": "./dist/css/generated.css",
+    "./css/workbench.css": "./dist/css/workbench.css",
+    "./css/command.css": "./dist/css/command.css",
+    "./css/analytical.css": "./dist/css/analytical.css",
     "./css/unlayered/tokens.css": "./css/tokens.css",
     "./css/unlayered/fonts.css": "./css/fonts.css",
     "./css/unlayered/base.css": "./css/base.css",
@@ -163,6 +211,19 @@
     "./css/unlayered/app.css": "./css/app.css",
     "./css/unlayered/skins.css": "./css/skins.css",
     "./css/unlayered/dataviz.css": "./css/dataviz.css",
+    "./css/unlayered/report.css": "./css/report.css",
+    "./css/unlayered/annotations.css": "./css/annotations.css",
+    "./css/unlayered/legend.css": "./css/legend.css",
+    "./css/unlayered/marks.css": "./css/marks.css",
+    "./css/unlayered/connectors.css": "./css/connectors.css",
+    "./css/unlayered/spotlight.css": "./css/spotlight.css",
+    "./css/unlayered/crosshair.css": "./css/crosshair.css",
+    "./css/unlayered/selection.css": "./css/selection.css",
+    "./css/unlayered/sources.css": "./css/sources.css",
+    "./css/unlayered/state.css": "./css/state.css",
+    "./css/unlayered/generated.css": "./css/generated.css",
+    "./css/unlayered/workbench.css": "./css/workbench.css",
+    "./css/unlayered/command.css": "./css/command.css",
     "./tokens": {
       "types": "./tokens/index.d.ts",
       "default": "./tokens/index.js"
@@ -173,11 +234,28 @@
     "./tokens/resolved.json": "./tokens/resolved.json",
     "./shiki/nothing.json": "./shiki/nothing.json",
     "./llms.txt": "./llms.txt",
+    "./docs/architecture.md": "./docs/architecture.md",
     "./docs/reference.md": "./docs/reference.md",
     "./docs/theming.md": "./docs/theming.md",
     "./docs/contrast.md": "./docs/contrast.md",
+    "./docs/stability.md": "./docs/stability.md",
     "./docs/usage.md": "./docs/usage.md",
+    "./docs/reporting.md": "./docs/reporting.md",
+    "./docs/annotations.md": "./docs/annotations.md",
+    "./docs/legends.md": "./docs/legends.md",
+    "./docs/marks.md": "./docs/marks.md",
+    "./docs/connectors.md": "./docs/connectors.md",
+    "./docs/spotlight.md": "./docs/spotlight.md",
+    "./docs/crosshair.md": "./docs/crosshair.md",
+    "./docs/selection.md": "./docs/selection.md",
+    "./docs/sources.md": "./docs/sources.md",
+    "./docs/state.md": "./docs/state.md",
+    "./docs/generated.md": "./docs/generated.md",
+    "./docs/workbench.md": "./docs/workbench.md",
+    "./docs/command.md": "./docs/command.md",
     "./docs/adr/0001-color-system.md": "./docs/adr/0001-color-system.md",
+    "./docs/adr/0002-scope-and-2026-baseline.md": "./docs/adr/0002-scope-and-2026-baseline.md",
+    "./docs/adr/0003-theme-model.md": "./docs/adr/0003-theme-model.md",
     "./classes": {
       "types": "./classes/index.d.ts",
       "default": "./classes/index.js"
@@ -190,6 +268,14 @@
       "types": "./glyphs/glyphs.d.ts",
       "default": "./glyphs/glyphs.js"
     },
+    "./annotations": {
+      "types": "./annotations/index.d.ts",
+      "default": "./annotations/index.js"
+    },
+    "./connectors": {
+      "types": "./connectors/index.d.ts",
+      "default": "./connectors/index.js"
+    },
     "./react": {
       "types": "./react/index.d.ts",
       "default": "./react/index.js"
@@ -198,6 +284,10 @@
       "types": "./solid/index.d.ts",
       "default": "./solid/index.js"
     },
+    "./qwik": {
+      "types": "./qwik/index.d.ts",
+      "default": "./qwik/index.js"
+    },
     "./skins": {
       "types": "./tokens/skins.d.ts",
       "default": "./tokens/skins.js"

package/qwik/index.d.ts

@@ -0,0 +1,60 @@
+/** @ponchia/ui/qwik — thin Qwik bindings over the SSR-safe behaviors.
+ *  Optional peer dep `@builder.io/qwik`. Hooks run a delegated behavior on
+ *  visible and register cleanup on dispose (via `useVisibleTask$`); they take
+ *  the same options as the behavior and return void. See behaviors/index.d.ts. */
+import type { Cleanup, DelegateOpts, ThemeStorageOpts, ToastOpts } from '../behaviors/index.js';
+
+export type BrontoBindingRoot =
+  | Document
+  | Element
+  // Qwik `useSignal()` (and any { value } / { current } ref shape).
+  | { value: Document | Element | null | undefined }
+  | { current: Document | Element | null | undefined }
+  | (() => Document | Element | null | undefined)
+  | null
+  | undefined;
+
+export type BrontoBindingOpts<T extends DelegateOpts = DelegateOpts> = Omit<T, 'root'> & {
+  root?: BrontoBindingRoot;
+};
+
+export type BrontoBindingOptsResolver<T extends DelegateOpts = DelegateOpts> =
+  | BrontoBindingOpts<T>
+  | (() => BrontoBindingOpts<T> | null | undefined)
+  | null
+  | undefined;
+
+/** Run any delegated behavior for the component's lifetime (init on visible,
+ *  its returned cleanup on dispose). Prefer the specific `use*` hooks in Qwik
+ *  so the optimizer can serialize the task; this generic form is safe only with
+ *  an optimizer-visible (module-imported) behavior. */
+export declare function useBrontoBehavior(
+  init: (opts?: DelegateOpts) => Cleanup | void,
+  opts?: BrontoBindingOptsResolver,
+): void;
+
+export declare function useThemeToggle(
+  opts?: BrontoBindingOptsResolver<ThemeStorageOpts & DelegateOpts>,
+): void;
+export declare function useDismissible(opts?: BrontoBindingOptsResolver): void;
+export declare function useDisclosure(opts?: BrontoBindingOptsResolver): void;
+export declare function useMenu(opts?: BrontoBindingOptsResolver): void;
+export declare function useFormValidation(opts?: BrontoBindingOptsResolver): void;
+export declare function useCombobox(opts?: BrontoBindingOptsResolver): void;
+export declare function usePopover(opts?: BrontoBindingOptsResolver): void;
+export declare function useTableSort(opts?: BrontoBindingOptsResolver): void;
+export declare function useTabs(opts?: BrontoBindingOptsResolver): void;
+export declare function useDialog(opts?: BrontoBindingOptsResolver): void;
+export declare function useCarousel(opts?: BrontoBindingOptsResolver): void;
+export declare function useDotGlyph(opts?: BrontoBindingOptsResolver): void;
+export declare function useLegend(opts?: BrontoBindingOptsResolver): void;
+export declare function useConnectors(opts?: BrontoBindingOptsResolver): void;
+export declare function useSpotlight(opts?: BrontoBindingOptsResolver): void;
+export declare function useCrosshair(opts?: BrontoBindingOptsResolver): void;
+export declare function useCommand(opts?: BrontoBindingOptsResolver): void;
+
+/** The `toast()` imperative (no lifecycle of its own). */
+export declare function useToast(): (message: string, opts?: ToastOpts) => Cleanup;
+
+export { applyStoredTheme } from '../behaviors/index.js';
+export { cls, ui, cx } from '../classes/index.js';

package/qwik/index.js

@@ -0,0 +1,149 @@
+/**
+ * @ponchia/ui/qwik — thin Qwik bindings over @ponchia/ui/behaviors.
+ *
+ * The CSS is the framework; these are *optional* hooks that wrap the SSR-safe
+ * vanilla `init*` behaviors in Qwik's client lifecycle. Thin adapters, not a
+ * component library (architecture ADR). `@builder.io/qwik` is an optional peer
+ * dependency.
+ *
+ * Qwik is resumable: nothing runs until needed, and our behaviors are exactly
+ * the kind of "enhance on the client" glue that fits — they `useVisibleTask$`
+ * (run when the owning component first becomes visible) and register cleanup,
+ * so a server-rendered page stays zero-JS until interaction. Each hook inlines
+ * its specific behavior so the Qwik optimizer can resolve the import inside the
+ * extracted task segment.
+ *
+ *   import { component$ } from '@builder.io/qwik';
+ *   import { useDialog, useToast } from '@ponchia/ui/qwik';
+ *   export default component$(() => {
+ *     useDialog();                 // wires every .ui-modal under document
+ *     const toast = useToast();
+ *     return <button onClick$={() => toast('Saved', { tone: 'success' })}>Save</button>;
+ *   });
+ *
+ * Scope a behavior to a subtree by passing a Qwik signal:
+ *   const root = useSignal();
+ *   useDialog({ root });           // <section ref={root}> … </section>
+ */
+import { useVisibleTask$ } from '@builder.io/qwik';
+import {
+  applyStoredTheme,
+  initThemeToggle,
+  dismissible,
+  initDisclosure,
+  initMenu,
+  initFormValidation,
+  initCombobox,
+  initPopover,
+  initTableSort,
+  initTabs,
+  initDialog,
+  initCarousel,
+  initDotGlyph,
+  initLegend,
+  initConnectors,
+  initSpotlight,
+  initCrosshair,
+  initCommand,
+  toast,
+} from '../behaviors/index.js';
+
+function resolveMaybe(v) {
+  return typeof v === 'function' ? v() : v;
+}
+
+function resolveRoot(root) {
+  const value = resolveMaybe(root);
+  if (value && typeof value === 'object') {
+    if ('value' in value) return value.value; // Qwik signal (useSignal)
+    if ('current' in value) return value.current; // generic ref shape
+  }
+  return value;
+}
+
+function resolveOpts(opts) {
+  const value = resolveMaybe(opts);
+  if (!value || typeof value !== 'object') return undefined;
+  const root = resolveRoot(value.root);
+  return root ? { ...value, root } : { ...value, root: undefined };
+}
+
+/** Run a delegated behavior on visible and register its cleanup on dispose.
+ *  `init` and `opts` are resolved inside the visible task, so a Qwik-signal
+ *  root is read after the element is assigned. Shared, non-QRL, so the
+ *  optimizer keeps the captured behavior import inside the task segment. */
+function start(init, opts, ctx) {
+  const cleanup = init(resolveOpts(opts));
+  if (typeof cleanup === 'function') ctx.cleanup(cleanup);
+}
+
+/** Generic escape hatch. NOTE for Qwik: prefer the specific `use*` hooks
+ *  below — they inline a statically-imported behavior so the optimizer can
+ *  serialize the task. Passing a runtime function here is only safe when it
+ *  is itself optimizer-visible (a module import). */
+export function useBrontoBehavior(init, opts) {
+  // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
+  useVisibleTask$((ctx) => start(init, opts, ctx));
+}
+
+export const useThemeToggle = (opts) =>
+  // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
+  useVisibleTask$((ctx) => start(initThemeToggle, opts, ctx));
+export const useDismissible = (opts) =>
+  // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
+  useVisibleTask$((ctx) => start(dismissible, opts, ctx));
+export const useDisclosure = (opts) =>
+  // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
+  useVisibleTask$((ctx) => start(initDisclosure, opts, ctx));
+export const useMenu = (opts) =>
+  // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
+  useVisibleTask$((ctx) => start(initMenu, opts, ctx));
+export const useFormValidation = (opts) =>
+  // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
+  useVisibleTask$((ctx) => start(initFormValidation, opts, ctx));
+export const useCombobox = (opts) =>
+  // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
+  useVisibleTask$((ctx) => start(initCombobox, opts, ctx));
+export const usePopover = (opts) =>
+  // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
+  useVisibleTask$((ctx) => start(initPopover, opts, ctx));
+export const useTableSort = (opts) =>
+  // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
+  useVisibleTask$((ctx) => start(initTableSort, opts, ctx));
+export const useTabs = (opts) =>
+  // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
+  useVisibleTask$((ctx) => start(initTabs, opts, ctx));
+export const useDialog = (opts) =>
+  // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
+  useVisibleTask$((ctx) => start(initDialog, opts, ctx));
+export const useCarousel = (opts) =>
+  // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
+  useVisibleTask$((ctx) => start(initCarousel, opts, ctx));
+export const useDotGlyph = (opts) =>
+  // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
+  useVisibleTask$((ctx) => start(initDotGlyph, opts, ctx));
+export const useLegend = (opts) =>
+  // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
+  useVisibleTask$((ctx) => start(initLegend, opts, ctx));
+export const useConnectors = (opts) =>
+  // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
+  useVisibleTask$((ctx) => start(initConnectors, opts, ctx));
+export const useSpotlight = (opts) =>
+  // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
+  useVisibleTask$((ctx) => start(initSpotlight, opts, ctx));
+export const useCrosshair = (opts) =>
+  // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
+  useVisibleTask$((ctx) => start(initCrosshair, opts, ctx));
+export const useCommand = (opts) =>
+  // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
+  useVisibleTask$((ctx) => start(initCommand, opts, ctx));
+
+/** The `toast()` imperative (no lifecycle of its own). */
+export const useToast = () => toast;
+
+// No-flash theme application must run before paint — do it in an inline head
+// script, not on visible. Re-exported for manual/SSR-bootstrap use.
+export { applyStoredTheme };
+
+// Convenience: the framework-agnostic class contract, re-exported.
+export { cls, ui, cx } from '../classes/index.js';

package/react/index.d.ts

@@ -9,25 +9,51 @@ import type {
   ToastOpts,
 } from '../behaviors/index.js';
 
+export type BrontoBindingRoot =
+  | Document
+  | Element
+  | { current: Document | Element | null | undefined }
+  | (() => Document | Element | null | undefined)
+  | null
+  | undefined;
+
+export type BrontoBindingOpts<T extends DelegateOpts = DelegateOpts> = Omit<T, 'root'> & {
+  root?: BrontoBindingRoot;
+};
+
+export type BrontoBindingOptsResolver<T extends DelegateOpts = DelegateOpts> =
+  | BrontoBindingOpts<T>
+  | (() => BrontoBindingOpts<T> | null | undefined)
+  | null
+  | undefined;
+
 /** Run any delegated behavior for the component's lifetime (init on mount,
- *  its returned cleanup on unmount). The behavior is run once. */
+ *  its returned cleanup on unmount). The behavior is run once. Options resolve
+ *  on mount, so scoped roots may be React refs or resolver callbacks. */
 export declare function useBrontoBehavior(
   init: (opts?: DelegateOpts) => Cleanup | void,
-  opts?: DelegateOpts,
+  opts?: BrontoBindingOptsResolver,
 ): void;
 
-export declare function useThemeToggle(opts?: ThemeStorageOpts & DelegateOpts): void;
-export declare function useDismissible(opts?: DelegateOpts): void;
-export declare function useDisclosure(opts?: DelegateOpts): void;
-export declare function useMenu(opts?: DelegateOpts): void;
-export declare function useFormValidation(opts?: DelegateOpts): void;
-export declare function useCombobox(opts?: DelegateOpts): void;
-export declare function usePopover(opts?: DelegateOpts): void;
-export declare function useTableSort(opts?: DelegateOpts): void;
-export declare function useTabs(opts?: DelegateOpts): void;
-export declare function useDialog(opts?: DelegateOpts): void;
-export declare function useCarousel(opts?: DelegateOpts): void;
-export declare function useDotGlyph(opts?: DelegateOpts): void;
+export declare function useThemeToggle(
+  opts?: BrontoBindingOptsResolver<ThemeStorageOpts & DelegateOpts>,
+): void;
+export declare function useDismissible(opts?: BrontoBindingOptsResolver): void;
+export declare function useDisclosure(opts?: BrontoBindingOptsResolver): void;
+export declare function useMenu(opts?: BrontoBindingOptsResolver): void;
+export declare function useFormValidation(opts?: BrontoBindingOptsResolver): void;
+export declare function useCombobox(opts?: BrontoBindingOptsResolver): void;
+export declare function usePopover(opts?: BrontoBindingOptsResolver): void;
+export declare function useTableSort(opts?: BrontoBindingOptsResolver): void;
+export declare function useTabs(opts?: BrontoBindingOptsResolver): void;
+export declare function useDialog(opts?: BrontoBindingOptsResolver): void;
+export declare function useCarousel(opts?: BrontoBindingOptsResolver): void;
+export declare function useDotGlyph(opts?: BrontoBindingOptsResolver): void;
+export declare function useLegend(opts?: BrontoBindingOptsResolver): void;
+export declare function useConnectors(opts?: BrontoBindingOptsResolver): void;
+export declare function useSpotlight(opts?: BrontoBindingOptsResolver): void;
+export declare function useCrosshair(opts?: BrontoBindingOptsResolver): void;
+export declare function useCommand(opts?: BrontoBindingOptsResolver): void;
 
 /** The `toast()` imperative (no lifecycle of its own). */
 export declare function useToast(): (message: string, opts?: ToastOpts) => Cleanup;

package/react/index.js

@@ -7,8 +7,8 @@
  * the architecture ADR. `react` is an optional peer dependency.
  *
  * The behaviors delegate from a root (default `document`), so call a hook once
- * near the relevant subtree; pass `{ root: ref.current }` to scope it. The root
- * is captured on mount — keep it stable (a ref), like any effect dependency.
+ * near the relevant subtree; pass `{ root: ref }` or a resolver callback to
+ * scope it. The options resolve on mount, after refs have been assigned.
  *
  *   import { useDialog, useToast } from '@ponchia/ui/react';
  *   function App() {
@@ -32,14 +32,36 @@ import {
   initDialog,
   initCarousel,
   initDotGlyph,
+  initLegend,
+  initConnectors,
+  initSpotlight,
+  initCrosshair,
+  initCommand,
   toast,
 } from '../behaviors/index.js';
 
+function resolveMaybe(v) {
+  return typeof v === 'function' ? v() : v;
+}
+
+function resolveRoot(root) {
+  const value = resolveMaybe(root);
+  if (value && typeof value === 'object' && 'current' in value) return value.current;
+  return value;
+}
+
+function resolveOpts(opts) {
+  const value = resolveMaybe(opts);
+  if (!value || typeof value !== 'object') return undefined;
+  const root = resolveRoot(value.root);
+  return root ? { ...value, root } : { ...value, root: undefined };
+}
+
 /** Run a delegated behavior for the component's lifetime (init on mount, its
- *  returned cleanup on unmount). The behavior is run once; `opts` is captured
- *  on mount — pass a stable root (a ref) if you scope it. */
+ *  returned cleanup on unmount). The behavior is run once; `opts` resolves
+ *  on mount so refs are usable for scoped roots. */
 export function useBrontoBehavior(init, opts) {
-  useEffect(() => init(opts), []); // eslint-disable-line react-hooks/exhaustive-deps -- delegated once on mount
+  useEffect(() => init(resolveOpts(opts)), []); // eslint-disable-line react-hooks/exhaustive-deps -- delegated once on mount
 }
 
 export const useThemeToggle = (opts) => useBrontoBehavior(initThemeToggle, opts);
@@ -54,6 +76,11 @@ export const useTabs = (opts) => useBrontoBehavior(initTabs, opts);
 export const useDialog = (opts) => useBrontoBehavior(initDialog, opts);
 export const useCarousel = (opts) => useBrontoBehavior(initCarousel, opts);
 export const useDotGlyph = (opts) => useBrontoBehavior(initDotGlyph, opts);
+export const useLegend = (opts) => useBrontoBehavior(initLegend, opts);
+export const useConnectors = (opts) => useBrontoBehavior(initConnectors, opts);
+export const useSpotlight = (opts) => useBrontoBehavior(initSpotlight, opts);
+export const useCrosshair = (opts) => useBrontoBehavior(initCrosshair, opts);
+export const useCommand = (opts) => useBrontoBehavior(initCommand, opts);
 
 /** The `toast()` imperative (no lifecycle of its own). */
 export const useToast = () => toast;

package/solid/index.d.ts

@@ -9,25 +9,51 @@ import type {
   ToastOpts,
 } from '../behaviors/index.js';
 
+export type BrontoBindingRoot =
+  | Document
+  | Element
+  | { current: Document | Element | null | undefined }
+  | (() => Document | Element | null | undefined)
+  | null
+  | undefined;
+
+export type BrontoBindingOpts<T extends DelegateOpts = DelegateOpts> = Omit<T, 'root'> & {
+  root?: BrontoBindingRoot;
+};
+
+export type BrontoBindingOptsResolver<T extends DelegateOpts = DelegateOpts> =
+  | BrontoBindingOpts<T>
+  | (() => BrontoBindingOpts<T> | null | undefined)
+  | null
+  | undefined;
+
 /** Run any delegated behavior for the component's lifetime (init on mount,
- *  its returned cleanup on dispose). */
+ *  its returned cleanup on dispose). The behavior is run once. Options resolve
+ *  on mount, so scoped roots may be refs or resolver callbacks. */
 export declare function useBrontoBehavior(
   init: (opts?: DelegateOpts) => Cleanup | void,
-  opts?: DelegateOpts,
+  opts?: BrontoBindingOptsResolver,
 ): void;
 
-export declare function useThemeToggle(opts?: ThemeStorageOpts & DelegateOpts): void;
-export declare function useDismissible(opts?: DelegateOpts): void;
-export declare function useDisclosure(opts?: DelegateOpts): void;
-export declare function useMenu(opts?: DelegateOpts): void;
-export declare function useFormValidation(opts?: DelegateOpts): void;
-export declare function useCombobox(opts?: DelegateOpts): void;
-export declare function usePopover(opts?: DelegateOpts): void;
-export declare function useTableSort(opts?: DelegateOpts): void;
-export declare function useTabs(opts?: DelegateOpts): void;
-export declare function useDialog(opts?: DelegateOpts): void;
-export declare function useCarousel(opts?: DelegateOpts): void;
-export declare function useDotGlyph(opts?: DelegateOpts): void;
+export declare function useThemeToggle(
+  opts?: BrontoBindingOptsResolver<ThemeStorageOpts & DelegateOpts>,
+): void;
+export declare function useDismissible(opts?: BrontoBindingOptsResolver): void;
+export declare function useDisclosure(opts?: BrontoBindingOptsResolver): void;
+export declare function useMenu(opts?: BrontoBindingOptsResolver): void;
+export declare function useFormValidation(opts?: BrontoBindingOptsResolver): void;
+export declare function useCombobox(opts?: BrontoBindingOptsResolver): void;
+export declare function usePopover(opts?: BrontoBindingOptsResolver): void;
+export declare function useTableSort(opts?: BrontoBindingOptsResolver): void;
+export declare function useTabs(opts?: BrontoBindingOptsResolver): void;
+export declare function useDialog(opts?: BrontoBindingOptsResolver): void;
+export declare function useCarousel(opts?: BrontoBindingOptsResolver): void;
+export declare function useDotGlyph(opts?: BrontoBindingOptsResolver): void;
+export declare function useLegend(opts?: BrontoBindingOptsResolver): void;
+export declare function useConnectors(opts?: BrontoBindingOptsResolver): void;
+export declare function useSpotlight(opts?: BrontoBindingOptsResolver): void;
+export declare function useCrosshair(opts?: BrontoBindingOptsResolver): void;
+export declare function useCommand(opts?: BrontoBindingOptsResolver): void;
 
 /** The `toast()` imperative (no lifecycle of its own). */
 export declare function useToast(): (message: string, opts?: ToastOpts) => Cleanup;