@ponchia/ui 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ponchia/ui",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "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": [
@@ -62,6 +62,9 @@
     "docs/stability.md",
     "docs/usage.md",
     "docs/reporting.md",
+    "docs/mermaid.md",
+    "docs/d2.md",
+    "docs/vega.md",
     "docs/annotations.md",
     "docs/legends.md",
     "docs/marks.md",
@@ -85,59 +88,75 @@
     "format": "prettier --write .",
     "check:format": "prettier --check .",
     "size:report": "node scripts/size-report.mjs",
+    "report:pdf": "node scripts/render-pdf.mjs",
+    "gen": "npm run prepack",
+    "fresh:build": "node scripts/gen-all.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",
+    "dts:emit": "node scripts/emit-dts.mjs",
     "glyphs:build": "node scripts/gen-glyphs.mjs",
     "skins:build": "node scripts/gen-skins.mjs",
     "charts:build": "node scripts/gen-charts.mjs",
+    "mermaid:build": "node scripts/gen-mermaid.mjs",
+    "d2:build": "node scripts/gen-d2.mjs",
+    "vega:build": "node scripts/gen-vega.mjs",
     "reference:build": "node scripts/gen-reference.mjs",
+    "classes:json:build": "node scripts/gen-classes-json.mjs",
     "contrast:build": "node scripts/gen-contrast.mjs",
     "vscode:build": "node scripts/gen-vscode-data.mjs",
     "dist:build": "node scripts/build-dist.mjs",
     "check:exports": "node scripts/check-exports.mjs",
-    "check:tokens": "node scripts/check-tokens.mjs",
+    "check:fresh": "node scripts/check-fresh.mjs",
     "check:classes": "node scripts/check-classes.mjs",
-    "check:dts": "node scripts/check-dts.mjs",
+    "check:recipe-types": "node scripts/check-recipe-types.mjs",
+    "check:chain": "node scripts/check-chain.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:dts-emit": "node scripts/check-dts-emit.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:mermaid": "node scripts/check-mermaid.mjs",
+    "check:d2": "node scripts/check-d2.mjs",
+    "check:vega": "node scripts/check-vega.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",
     "check:shiki": "node scripts/check-shiki.mjs",
     "check:dist": "node scripts/check-dist.mjs",
     "check:pack": "node scripts/check-pack.mjs",
     "check:release": "node scripts/check-release.mjs",
-    "check:reference": "node scripts/check-reference.mjs",
+    "check:versions": "node scripts/check-versions.mjs",
+    "check:doc-recipes": "node scripts/check-doc-recipes.mjs",
+    "check:contract": "node scripts/check-contract.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: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",
+    "check:publint": "publint --strict",
+    "check:attw": "attw --pack --ignore-rules no-resolution cjs-resolves-to-esm",
+    "check": "npm run lint && npm run check:format && npm run check:exports && npm run check:fresh && npm run check:classes && npm run check:recipe-types && npm run check:types && npm run check:shiki && npm run check:dist && npm run check:pack && npm run check:publint && npm run check:attw && npm run check:release && npm run check:versions && npm run check:doc-recipes && npm run check:contract && npm run check:contrast && npm run check:behaviors && npm run check:dts-emit && npm run check:glyphs && npm run check:color-policy && npm run check:skins && npm run check:charts && npm run check:mermaid && npm run check:d2 && npm run check:vega && npm run check:report && npm run check:legend && npm run check:chain",
     "test": "node --test \"test/*.test.mjs\"",
-    "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",
+    "prepack": "npm run tokens:css:build && npm run tokens:build && npm run dtcg:build && npm run resolved:build && npm run dts:build && npm run dts:emit && npm run reference:build && npm run classes:json:build && npm run contrast:build && npm run vscode:build && npm run skins:build && npm run charts:build && npm run mermaid:build && npm run d2:build && npm run vega:build && npm run dist:build && npm run glyphs:build",
     "prepublishOnly": "npm run check && npm test"
   },
   "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.3",
     "@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",
+    "publint": "^0.3.21",
     "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"
+    "typescript": "^6.0.3",
+    "vega": "^6.2.0",
+    "vega-lite": "^6.4.3"
   },
   "peerDependencies": {
     "@builder.io/qwik": ">=1.5",
@@ -241,6 +260,9 @@
     "./docs/stability.md": "./docs/stability.md",
     "./docs/usage.md": "./docs/usage.md",
     "./docs/reporting.md": "./docs/reporting.md",
+    "./docs/mermaid.md": "./docs/mermaid.md",
+    "./docs/d2.md": "./docs/d2.md",
+    "./docs/vega.md": "./docs/vega.md",
     "./docs/annotations.md": "./docs/annotations.md",
     "./docs/legends.md": "./docs/legends.md",
     "./docs/marks.md": "./docs/marks.md",
@@ -260,6 +282,7 @@
       "types": "./classes/index.d.ts",
       "default": "./classes/index.js"
     },
+    "./classes.json": "./classes/classes.json",
     "./behaviors": {
       "types": "./behaviors/index.d.ts",
       "default": "./behaviors/index.js"
@@ -297,6 +320,21 @@
       "default": "./tokens/charts.js"
     },
     "./charts.json": "./tokens/charts.json",
+    "./mermaid": {
+      "types": "./tokens/mermaid.d.ts",
+      "default": "./tokens/mermaid.js"
+    },
+    "./mermaid.json": "./tokens/mermaid.json",
+    "./d2": {
+      "types": "./tokens/d2.d.ts",
+      "default": "./tokens/d2.js"
+    },
+    "./d2.json": "./tokens/d2.json",
+    "./vega": {
+      "types": "./tokens/vega.d.ts",
+      "default": "./tokens/vega.js"
+    },
+    "./vega.json": "./tokens/vega.json",
     "./fonts/*": "./fonts/*"
   }
 }

package/qwik/index.d.ts

@@ -1,60 +1,43 @@
-/** @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;
+/** 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).
+ *  @param {(opts?: DelegateOpts) => Cleanup | void} init
+ *  @param {BrontoBindingOptsResolver} [opts]
+ *  @returns {void} */
+export function useBrontoBehavior(init: (opts?: DelegateOpts) => Cleanup | void, opts?: BrontoBindingOptsResolver): void;
+export function useThemeToggle(opts?: BrontoBindingOptsResolver<ThemeStorageOpts & DelegateOpts>): void;
+export function useDismissible(opts?: BrontoBindingOptsResolver): void;
+export function useDisclosure(opts?: BrontoBindingOptsResolver): void;
+export function useMenu(opts?: BrontoBindingOptsResolver): void;
+export function useFormValidation(opts?: BrontoBindingOptsResolver): void;
+export function useCombobox(opts?: BrontoBindingOptsResolver): void;
+export function usePopover(opts?: BrontoBindingOptsResolver): void;
+export function useTableSort(opts?: BrontoBindingOptsResolver): void;
+export function useTabs(opts?: BrontoBindingOptsResolver): void;
+export function useDialog(opts?: BrontoBindingOptsResolver): void;
+export function useCarousel(opts?: BrontoBindingOptsResolver): void;
+export function useDotGlyph(opts?: BrontoBindingOptsResolver): void;
+export function useLegend(opts?: BrontoBindingOptsResolver): void;
+export function useConnectors(opts?: BrontoBindingOptsResolver): void;
+export function useSpotlight(opts?: BrontoBindingOptsResolver): void;
+export function useCrosshair(opts?: BrontoBindingOptsResolver): void;
+export function useCommand(opts?: BrontoBindingOptsResolver): void;
+export function useToast(): (message: string, opts?: ToastOpts) => Cleanup;
+export { applyStoredTheme };
+export type Cleanup = import("../behaviors/index.js").Cleanup;
+export type DelegateOpts = import("../behaviors/index.js").DelegateOpts;
+export type ThemeStorageOpts = import("../behaviors/index.js").ThemeStorageOpts;
+export type ToastOpts = import("../behaviors/index.js").ToastOpts;
+export type BrontoBindingRoot = Document | Element | {
+    value: Document | Element | null | undefined;
+} | {
+    current: Document | Element | null | undefined;
+} | (() => Document | Element | null | undefined) | null | undefined;
+export type BrontoBindingOpts<T extends DelegateOpts = import("../behaviors/index.js").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';
+export type BrontoBindingOptsResolver<T extends DelegateOpts = import("../behaviors/index.js").DelegateOpts> = BrontoBindingOpts<T> | (() => BrontoBindingOpts<T> | null | undefined) | null | undefined;
+import { applyStoredTheme } from '../behaviors/index.js';
+export { cls, ui, cx } from "../classes/index.js";
+//# sourceMappingURL=index.d.ts.map

package/qwik/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.js"],"names":[],"mappings":"AA8GA;;;;;;sBAMsB;AACtB,wCAHY,CAAC,IAAI,CAAC,EAAE,YAAY,KAAK,OAAO,GAAG,IAAI,SACvC,yBAAyB,GACvB,IAAI,CAIjB;AAGM,sCADK,yBAAyB,CAAC,gBAAgB,GAAG,YAAY,CAAC,GAAmB,IAAI,CAGhC;AAEtD,sCADK,yBAAyB,GAAmB,IAAI,CAGH;AAElD,qCADK,yBAAyB,GAAmB,IAAI,CAGA;AAErD,+BADK,yBAAyB,GAAmB,IAAI,CAGN;AAE/C,yCADK,yBAAyB,GAAmB,IAAI,CAGI;AAEzD,mCADK,yBAAyB,GAAmB,IAAI,CAGF;AAEnD,kCADK,yBAAyB,GAAmB,IAAI,CAGH;AAElD,oCADK,yBAAyB,GAAmB,IAAI,CAGD;AAEpD,+BADK,yBAAyB,GAAmB,IAAI,CAGN;AAE/C,iCADK,yBAAyB,GAAmB,IAAI,CAGJ;AAEjD,mCADK,yBAAyB,GAAmB,IAAI,CAGF;AAEnD,mCADK,yBAAyB,GAAmB,IAAI,CAGF;AAEnD,iCADK,yBAAyB,GAAmB,IAAI,CAGJ;AAEjD,qCADK,yBAAyB,GAAmB,IAAI,CAGA;AAErD,oCADK,yBAAyB,GAAmB,IAAI,CAGD;AAEpD,oCADK,yBAAyB,GAAmB,IAAI,CAGD;AAEpD,kCADK,yBAAyB,GAAmB,IAAI,CAGH;AAIlD,4BADO,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,SAAS,KAAK,OAAO,CACzB;;sBAtKtB,OAAO,uBAAuB,EAAE,OAAO;2BACvC,OAAO,uBAAuB,EAAE,YAAY;+BAC5C,OAAO,uBAAuB,EAAE,gBAAgB;wBAChD,OAAO,uBAAuB,EAAE,SAAS;gCAEzC,QAAQ,GACd,OAAO,GACP;IAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAA;CAAE,GAChD;IAAE,OAAO,EAAE,QAAQ,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAA;CAAE,GAClD,CAAC,MAAM,QAAQ,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,GAC7C,IAAI,GACJ,SAAS;8BAIa,CAAC,SAAhB,YAAa,mDACd,IAAI,CAAC,CAAC,EAAE,MAAM,CAAC,GAAG;IAAE,IAAI,CAAC,EAAE,iBAAiB,CAAA;CAAE;sCAI9B,CAAC,SAAhB,YAAa,mDACd,iBAAiB,CAAC,CAAC,CAAC,GAC1B,CAAC,MAAM,iBAAiB,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC,GAC/C,IAAI,GACJ,SAAS;iCAuBT,uBAAuB"}

package/qwik/index.js

@@ -24,6 +24,32 @@
  * Scope a behavior to a subtree by passing a Qwik signal:
  *   const root = useSignal();
  *   useDialog({ root });           // <section ref={root}> … </section>
+ *
+ * @typedef {import('../behaviors/index.js').Cleanup} Cleanup
+ * @typedef {import('../behaviors/index.js').DelegateOpts} DelegateOpts
+ * @typedef {import('../behaviors/index.js').ThemeStorageOpts} ThemeStorageOpts
+ * @typedef {import('../behaviors/index.js').ToastOpts} ToastOpts
+ *
+ * @typedef {Document
+ *   | Element
+ *   | { value: Document | Element | null | undefined }
+ *   | { current: Document | Element | null | undefined }
+ *   | (() => Document | Element | null | undefined)
+ *   | null
+ *   | undefined} BrontoBindingRoot
+ */
+
+/**
+ * @template {DelegateOpts} [T=DelegateOpts]
+ * @typedef {Omit<T, 'root'> & { root?: BrontoBindingRoot }} BrontoBindingOpts
+ */
+
+/**
+ * @template {DelegateOpts} [T=DelegateOpts]
+ * @typedef {BrontoBindingOpts<T>
+ *   | (() => BrontoBindingOpts<T> | null | undefined)
+ *   | null
+ *   | undefined} BrontoBindingOptsResolver
  */
 import { useVisibleTask$ } from '@builder.io/qwik';
 import {
@@ -64,8 +90,13 @@ function resolveRoot(root) {
 function resolveOpts(opts) {
   const value = resolveMaybe(opts);
   if (!value || typeof value !== 'object') return undefined;
+  // No `root` key → no scope requested; leave root out so the behavior
+  // delegates from `document`. A `root` key that resolves falsy means a scope
+  // WAS requested but the ref is not ready: emit `root: null` so the behavior
+  // no-ops instead of hijacking the whole document.
+  if (!('root' in value)) return { ...value };
   const root = resolveRoot(value.root);
-  return root ? { ...value, root } : { ...value, root: undefined };
+  return { ...value, root: root || null };
 }
 
 /** Run a delegated behavior on visible and register its cleanup on dispose.
@@ -80,65 +111,86 @@ function start(init, opts, ctx) {
 /** 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). */
+ *  is itself optimizer-visible (a module import).
+ *  @param {(opts?: DelegateOpts) => Cleanup | void} init
+ *  @param {BrontoBindingOptsResolver} [opts]
+ *  @returns {void} */
 export function useBrontoBehavior(init, opts) {
   // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
   useVisibleTask$((ctx) => start(init, opts, ctx));
 }
 
+/** @param {BrontoBindingOptsResolver<ThemeStorageOpts & DelegateOpts>} [opts] @returns {void} */
 export const useThemeToggle = (opts) =>
   // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
   useVisibleTask$((ctx) => start(initThemeToggle, opts, ctx));
+/** @param {BrontoBindingOptsResolver} [opts] @returns {void} */
 export const useDismissible = (opts) =>
   // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
   useVisibleTask$((ctx) => start(dismissible, opts, ctx));
+/** @param {BrontoBindingOptsResolver} [opts] @returns {void} */
 export const useDisclosure = (opts) =>
   // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
   useVisibleTask$((ctx) => start(initDisclosure, opts, ctx));
+/** @param {BrontoBindingOptsResolver} [opts] @returns {void} */
 export const useMenu = (opts) =>
   // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
   useVisibleTask$((ctx) => start(initMenu, opts, ctx));
+/** @param {BrontoBindingOptsResolver} [opts] @returns {void} */
 export const useFormValidation = (opts) =>
   // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
   useVisibleTask$((ctx) => start(initFormValidation, opts, ctx));
+/** @param {BrontoBindingOptsResolver} [opts] @returns {void} */
 export const useCombobox = (opts) =>
   // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
   useVisibleTask$((ctx) => start(initCombobox, opts, ctx));
+/** @param {BrontoBindingOptsResolver} [opts] @returns {void} */
 export const usePopover = (opts) =>
   // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
   useVisibleTask$((ctx) => start(initPopover, opts, ctx));
+/** @param {BrontoBindingOptsResolver} [opts] @returns {void} */
 export const useTableSort = (opts) =>
   // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
   useVisibleTask$((ctx) => start(initTableSort, opts, ctx));
+/** @param {BrontoBindingOptsResolver} [opts] @returns {void} */
 export const useTabs = (opts) =>
   // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
   useVisibleTask$((ctx) => start(initTabs, opts, ctx));
+/** @param {BrontoBindingOptsResolver} [opts] @returns {void} */
 export const useDialog = (opts) =>
   // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
   useVisibleTask$((ctx) => start(initDialog, opts, ctx));
+/** @param {BrontoBindingOptsResolver} [opts] @returns {void} */
 export const useCarousel = (opts) =>
   // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
   useVisibleTask$((ctx) => start(initCarousel, opts, ctx));
+/** @param {BrontoBindingOptsResolver} [opts] @returns {void} */
 export const useDotGlyph = (opts) =>
   // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
   useVisibleTask$((ctx) => start(initDotGlyph, opts, ctx));
+/** @param {BrontoBindingOptsResolver} [opts] @returns {void} */
 export const useLegend = (opts) =>
   // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
   useVisibleTask$((ctx) => start(initLegend, opts, ctx));
+/** @param {BrontoBindingOptsResolver} [opts] @returns {void} */
 export const useConnectors = (opts) =>
   // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
   useVisibleTask$((ctx) => start(initConnectors, opts, ctx));
+/** @param {BrontoBindingOptsResolver} [opts] @returns {void} */
 export const useSpotlight = (opts) =>
   // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
   useVisibleTask$((ctx) => start(initSpotlight, opts, ctx));
+/** @param {BrontoBindingOptsResolver} [opts] @returns {void} */
 export const useCrosshair = (opts) =>
   // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
   useVisibleTask$((ctx) => start(initCrosshair, opts, ctx));
+/** @param {BrontoBindingOptsResolver} [opts] @returns {void} */
 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). */
+/** The `toast()` imperative (no lifecycle of its own).
+ *  @returns {(message: string, opts?: ToastOpts) => Cleanup} */
 export const useToast = () => toast;
 
 // No-flash theme application must run before paint — do it in an inline head

package/react/index.d.ts

@@ -1,62 +1,40 @@
-/** @ponchia/ui/react — thin React bindings over the SSR-safe behaviors.
- *  Optional peer dep `react`. Hooks run a delegated behavior for the
- *  component's lifetime; they take the same options as the behavior and
- *  return void (the cleanup is wired to unmount). See behaviors/index.d.ts. */
-import type {
-  Cleanup,
-  DelegateOpts,
-  ThemeStorageOpts,
-  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;
+/** Run a delegated behavior for the component's lifetime (init on mount, its
+ *  returned cleanup on unmount). The behavior is run once; `opts` resolves
+ *  on mount so refs are usable for scoped roots.
+ *  @param {(opts?: DelegateOpts) => Cleanup | void} init
+ *  @param {BrontoBindingOptsResolver} [opts]
+ *  @returns {void} */
+export function useBrontoBehavior(init: (opts?: DelegateOpts) => Cleanup | void, opts?: BrontoBindingOptsResolver): void;
+export function useThemeToggle(opts?: BrontoBindingOptsResolver<ThemeStorageOpts & DelegateOpts>): void;
+export function useDismissible(opts?: BrontoBindingOptsResolver): void;
+export function useDisclosure(opts?: BrontoBindingOptsResolver): void;
+export function useMenu(opts?: BrontoBindingOptsResolver): void;
+export function useFormValidation(opts?: BrontoBindingOptsResolver): void;
+export function useCombobox(opts?: BrontoBindingOptsResolver): void;
+export function usePopover(opts?: BrontoBindingOptsResolver): void;
+export function useTableSort(opts?: BrontoBindingOptsResolver): void;
+export function useTabs(opts?: BrontoBindingOptsResolver): void;
+export function useDialog(opts?: BrontoBindingOptsResolver): void;
+export function useCarousel(opts?: BrontoBindingOptsResolver): void;
+export function useDotGlyph(opts?: BrontoBindingOptsResolver): void;
+export function useLegend(opts?: BrontoBindingOptsResolver): void;
+export function useConnectors(opts?: BrontoBindingOptsResolver): void;
+export function useSpotlight(opts?: BrontoBindingOptsResolver): void;
+export function useCrosshair(opts?: BrontoBindingOptsResolver): void;
+export function useCommand(opts?: BrontoBindingOptsResolver): void;
+export function useToast(): (message: string, opts?: ToastOpts) => Cleanup;
+export { applyStoredTheme };
+export type Cleanup = import("../behaviors/index.js").Cleanup;
+export type DelegateOpts = import("../behaviors/index.js").DelegateOpts;
+export type ThemeStorageOpts = import("../behaviors/index.js").ThemeStorageOpts;
+export type ToastOpts = import("../behaviors/index.js").ToastOpts;
+export type BrontoBindingRoot = Document | Element | {
+    current: Document | Element | null | undefined;
+} | (() => Document | Element | null | undefined) | null | undefined;
+export type BrontoBindingOpts<T extends DelegateOpts = import("../behaviors/index.js").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. Options resolve
- *  on mount, so scoped roots may be React refs or resolver callbacks. */
-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';
+export type BrontoBindingOptsResolver<T extends DelegateOpts = import("../behaviors/index.js").DelegateOpts> = BrontoBindingOpts<T> | (() => BrontoBindingOpts<T> | null | undefined) | null | undefined;
+import { applyStoredTheme } from '../behaviors/index.js';
+export { cls, ui, cx } from "../classes/index.js";
+//# sourceMappingURL=index.d.ts.map

package/react/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.js"],"names":[],"mappings":"AA4FA;;;;;sBAKsB;AACtB,wCAHY,CAAC,IAAI,CAAC,EAAE,YAAY,KAAK,OAAO,GAAG,IAAI,SACvC,yBAAyB,GACvB,IAAI,CAGjB;AAGM,sCADK,yBAAyB,CAAC,gBAAgB,GAAG,YAAY,CAAC,GAAmB,IAAI,CACb;AAEzE,sCADK,yBAAyB,GAAmB,IAAI,CACgB;AAErE,qCADK,yBAAyB,GAAmB,IAAI,CACkB;AAEvE,+BADK,yBAAyB,GAAmB,IAAI,CACM;AAE3D,yCADK,yBAAyB,GAAmB,IAAI,CAC0B;AAE/E,mCADK,yBAAyB,GAAmB,IAAI,CACc;AAEnE,kCADK,yBAAyB,GAAmB,IAAI,CACY;AAEjE,oCADK,yBAAyB,GAAmB,IAAI,CACgB;AAErE,+BADK,yBAAyB,GAAmB,IAAI,CACM;AAE3D,iCADK,yBAAyB,GAAmB,IAAI,CACU;AAE/D,mCADK,yBAAyB,GAAmB,IAAI,CACc;AAEnE,mCADK,yBAAyB,GAAmB,IAAI,CACc;AAEnE,iCADK,yBAAyB,GAAmB,IAAI,CACU;AAE/D,qCADK,yBAAyB,GAAmB,IAAI,CACkB;AAEvE,oCADK,yBAAyB,GAAmB,IAAI,CACgB;AAErE,oCADK,yBAAyB,GAAmB,IAAI,CACgB;AAErE,kCADK,yBAAyB,GAAmB,IAAI,CACY;AAIjE,4BADO,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,SAAS,KAAK,OAAO,CACzB;;sBArHtB,OAAO,uBAAuB,EAAE,OAAO;2BACvC,OAAO,uBAAuB,EAAE,YAAY;+BAC5C,OAAO,uBAAuB,EAAE,gBAAgB;wBAChD,OAAO,uBAAuB,EAAE,SAAS;gCAEzC,QAAQ,GACd,OAAO,GACP;IAAE,OAAO,EAAE,QAAQ,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAA;CAAE,GAClD,CAAC,MAAM,QAAQ,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,GAC7C,IAAI,GACJ,SAAS;8BAIa,CAAC,SAAhB,YAAa,mDACd,IAAI,CAAC,CAAC,EAAE,MAAM,CAAC,GAAG;IAAE,IAAI,CAAC,EAAE,iBAAiB,CAAA;CAAE;sCAI9B,CAAC,SAAhB,YAAa,mDACd,iBAAiB,CAAC,CAAC,CAAC,GAC1B,CAAC,MAAM,iBAAiB,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC,GAC/C,IAAI,GACJ,SAAS;iCAuBT,uBAAuB"}

package/react/index.js

@@ -16,6 +16,34 @@
  *     const toast = useToast();
  *     return <button onClick={() => toast('Saved', { tone: 'success' })}>Save</button>;
  *   }
+ *
+ * The public types below are JSDoc `@typedef`s; the shipped `index.d.ts` is
+ * generated from them (and these signatures) by `tsc --emitDeclarationOnly`.
+ *
+ * @typedef {import('../behaviors/index.js').Cleanup} Cleanup
+ * @typedef {import('../behaviors/index.js').DelegateOpts} DelegateOpts
+ * @typedef {import('../behaviors/index.js').ThemeStorageOpts} ThemeStorageOpts
+ * @typedef {import('../behaviors/index.js').ToastOpts} ToastOpts
+ *
+ * @typedef {Document
+ *   | Element
+ *   | { current: Document | Element | null | undefined }
+ *   | (() => Document | Element | null | undefined)
+ *   | null
+ *   | undefined} BrontoBindingRoot
+ */
+
+/**
+ * @template {DelegateOpts} [T=DelegateOpts]
+ * @typedef {Omit<T, 'root'> & { root?: BrontoBindingRoot }} BrontoBindingOpts
+ */
+
+/**
+ * @template {DelegateOpts} [T=DelegateOpts]
+ * @typedef {BrontoBindingOpts<T>
+ *   | (() => BrontoBindingOpts<T> | null | undefined)
+ *   | null
+ *   | undefined} BrontoBindingOptsResolver
  */
 import { useEffect } from 'react';
 import {
@@ -53,36 +81,62 @@ function resolveRoot(root) {
 function resolveOpts(opts) {
   const value = resolveMaybe(opts);
   if (!value || typeof value !== 'object') return undefined;
+  // No `root` key → no scope requested; leave root out so the behavior
+  // delegates from `document`. A `root` key that resolves falsy means a scope
+  // WAS requested but the ref is not ready: emit `root: null` so the behavior
+  // no-ops instead of hijacking the whole document.
+  if (!('root' in value)) return { ...value };
   const root = resolveRoot(value.root);
-  return root ? { ...value, root } : { ...value, root: undefined };
+  return { ...value, root: root || null };
 }
 
 /** Run a delegated behavior for the component's lifetime (init on mount, its
  *  returned cleanup on unmount). The behavior is run once; `opts` resolves
- *  on mount so refs are usable for scoped roots. */
+ *  on mount so refs are usable for scoped roots.
+ *  @param {(opts?: DelegateOpts) => Cleanup | void} init
+ *  @param {BrontoBindingOptsResolver} [opts]
+ *  @returns {void} */
 export function useBrontoBehavior(init, opts) {
   useEffect(() => init(resolveOpts(opts)), []); // eslint-disable-line react-hooks/exhaustive-deps -- delegated once on mount
 }
 
+/** @param {BrontoBindingOptsResolver<ThemeStorageOpts & DelegateOpts>} [opts] @returns {void} */
 export const useThemeToggle = (opts) => useBrontoBehavior(initThemeToggle, opts);
+/** @param {BrontoBindingOptsResolver} [opts] @returns {void} */
 export const useDismissible = (opts) => useBrontoBehavior(dismissible, opts);
+/** @param {BrontoBindingOptsResolver} [opts] @returns {void} */
 export const useDisclosure = (opts) => useBrontoBehavior(initDisclosure, opts);
+/** @param {BrontoBindingOptsResolver} [opts] @returns {void} */
 export const useMenu = (opts) => useBrontoBehavior(initMenu, opts);
+/** @param {BrontoBindingOptsResolver} [opts] @returns {void} */
 export const useFormValidation = (opts) => useBrontoBehavior(initFormValidation, opts);
+/** @param {BrontoBindingOptsResolver} [opts] @returns {void} */
 export const useCombobox = (opts) => useBrontoBehavior(initCombobox, opts);
+/** @param {BrontoBindingOptsResolver} [opts] @returns {void} */
 export const usePopover = (opts) => useBrontoBehavior(initPopover, opts);
+/** @param {BrontoBindingOptsResolver} [opts] @returns {void} */
 export const useTableSort = (opts) => useBrontoBehavior(initTableSort, opts);
+/** @param {BrontoBindingOptsResolver} [opts] @returns {void} */
 export const useTabs = (opts) => useBrontoBehavior(initTabs, opts);
+/** @param {BrontoBindingOptsResolver} [opts] @returns {void} */
 export const useDialog = (opts) => useBrontoBehavior(initDialog, opts);
+/** @param {BrontoBindingOptsResolver} [opts] @returns {void} */
 export const useCarousel = (opts) => useBrontoBehavior(initCarousel, opts);
+/** @param {BrontoBindingOptsResolver} [opts] @returns {void} */
 export const useDotGlyph = (opts) => useBrontoBehavior(initDotGlyph, opts);
+/** @param {BrontoBindingOptsResolver} [opts] @returns {void} */
 export const useLegend = (opts) => useBrontoBehavior(initLegend, opts);
+/** @param {BrontoBindingOptsResolver} [opts] @returns {void} */
 export const useConnectors = (opts) => useBrontoBehavior(initConnectors, opts);
+/** @param {BrontoBindingOptsResolver} [opts] @returns {void} */
 export const useSpotlight = (opts) => useBrontoBehavior(initSpotlight, opts);
+/** @param {BrontoBindingOptsResolver} [opts] @returns {void} */
 export const useCrosshair = (opts) => useBrontoBehavior(initCrosshair, opts);
+/** @param {BrontoBindingOptsResolver} [opts] @returns {void} */
 export const useCommand = (opts) => useBrontoBehavior(initCommand, opts);
 
-/** The `toast()` imperative (no lifecycle of its own). */
+/** The `toast()` imperative (no lifecycle of its own).
+ *  @returns {(message: string, opts?: ToastOpts) => Cleanup} */
 export const useToast = () => toast;
 
 // No-flash theme application has to run before paint; do it in an inline head