@ponchia/ui 0.5.0 → 0.6.3

package/qwik/index.d.ts

@@ -1,60 +1,45 @@
-/** @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 useDisabledGuard(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 useModal(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/internal.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/internal.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":"AAgHA;;;;;;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,wCADK,yBAAyB,GAAmB,IAAI,CAGG;AAExD,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,gCADK,yBAAyB,GAAmB,IAAI,CAGL;AAEhD,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;;sBAhLtB,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,sDACd,IAAI,CAAC,CAAC,EAAE,MAAM,CAAC,GAAG;IAAE,IAAI,CAAC,EAAE,iBAAiB,CAAA;CAAE;sCAI9B,CAAC,SAAhB,YAAa,sDACd,iBAAiB,CAAC,CAAC,CAAC,GAC1B,CAAC,MAAM,iBAAiB,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC,GAC/C,IAAI,GACJ,SAAS;iCAyBT,uBAAuB"}

package/qwik/index.js

@@ -24,12 +24,39 @@
  * 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 {
   applyStoredTheme,
   initThemeToggle,
   dismissible,
+  initDisabledGuard,
   initDisclosure,
   initMenu,
   initFormValidation,
@@ -38,6 +65,7 @@ import {
   initTableSort,
   initTabs,
   initDialog,
+  initModal,
   initCarousel,
   initDotGlyph,
   initLegend,
@@ -64,8 +92,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 +113,94 @@ 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 useDisabledGuard = (opts) =>
+  // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
+  useVisibleTask$((ctx) => start(initDisabledGuard, 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 useModal = (opts) =>
+  // eslint-disable-next-line qwik/no-use-visible-task -- delegated DOM glue + cleanup
+  useVisibleTask$((ctx) => start(initModal, 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,42 @@
-/** @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 useDisabledGuard(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 useModal(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/internal.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/internal.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":"AA8FA;;;;;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,wCADK,yBAAyB,GAAmB,IAAI,CACwB;AAE7E,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,gCADK,yBAAyB,GAAmB,IAAI,CACQ;AAE7D,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;;sBA3HtB,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,sDACd,IAAI,CAAC,CAAC,EAAE,MAAM,CAAC,GAAG;IAAE,IAAI,CAAC,EAAE,iBAAiB,CAAA;CAAE;sCAI9B,CAAC,SAAhB,YAAa,sDACd,iBAAiB,CAAC,CAAC,CAAC,GAC1B,CAAC,MAAM,iBAAiB,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC,GAC/C,IAAI,GACJ,SAAS;iCAyBT,uBAAuB"}

package/react/index.js

@@ -16,12 +16,41 @@
  *     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 {
   applyStoredTheme,
   initThemeToggle,
   dismissible,
+  initDisabledGuard,
   initDisclosure,
   initMenu,
   initFormValidation,
@@ -30,6 +59,7 @@ import {
   initTableSort,
   initTabs,
   initDialog,
+  initModal,
   initCarousel,
   initDotGlyph,
   initLegend,
@@ -53,36 +83,66 @@ 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 useDisabledGuard = (opts) => useBrontoBehavior(initDisabledGuard, 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 useModal = (opts) => useBrontoBehavior(initModal, 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

package/solid/index.d.ts

@@ -1,62 +1,69 @@
-/** @ponchia/ui/solid — thin Solid bindings over the SSR-safe behaviors.
- *  Optional peer dep `solid-js`. Primitives 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 dispose). 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 dispose). Options resolve on mount, after refs exist.
+ * @param {(opts?: DelegateOpts) => Cleanup | void} init
+ * @param {BrontoBindingOptsResolver} [opts]
+ * @returns {void}
+ */
+export function useBrontoBehavior(init: (opts?: DelegateOpts) => Cleanup | void, opts?: BrontoBindingOptsResolver): void;
+/** @type {(opts?: BrontoBindingOptsResolver<ThemeStorageOpts & DelegateOpts>) => void} */
+export const useThemeToggle: (opts?: BrontoBindingOptsResolver<ThemeStorageOpts & DelegateOpts>) => void;
+/** @type {(opts?: BrontoBindingOptsResolver) => void} */
+export const useDismissible: (opts?: BrontoBindingOptsResolver) => void;
+/** @type {(opts?: BrontoBindingOptsResolver) => void} */
+export const useDisabledGuard: (opts?: BrontoBindingOptsResolver) => void;
+/** @type {(opts?: BrontoBindingOptsResolver) => void} */
+export const useDisclosure: (opts?: BrontoBindingOptsResolver) => void;
+/** @type {(opts?: BrontoBindingOptsResolver) => void} */
+export const useMenu: (opts?: BrontoBindingOptsResolver) => void;
+/** @type {(opts?: BrontoBindingOptsResolver) => void} */
+export const useFormValidation: (opts?: BrontoBindingOptsResolver) => void;
+/** @type {(opts?: BrontoBindingOptsResolver) => void} */
+export const useCombobox: (opts?: BrontoBindingOptsResolver) => void;
+/** @type {(opts?: BrontoBindingOptsResolver) => void} */
+export const usePopover: (opts?: BrontoBindingOptsResolver) => void;
+/** @type {(opts?: BrontoBindingOptsResolver) => void} */
+export const useTableSort: (opts?: BrontoBindingOptsResolver) => void;
+/** @type {(opts?: BrontoBindingOptsResolver) => void} */
+export const useTabs: (opts?: BrontoBindingOptsResolver) => void;
+/** @type {(opts?: BrontoBindingOptsResolver) => void} */
+export const useDialog: (opts?: BrontoBindingOptsResolver) => void;
+/** @type {(opts?: BrontoBindingOptsResolver) => void} */
+export const useModal: (opts?: BrontoBindingOptsResolver) => void;
+/** @type {(opts?: BrontoBindingOptsResolver) => void} */
+export const useCarousel: (opts?: BrontoBindingOptsResolver) => void;
+/** @type {(opts?: BrontoBindingOptsResolver) => void} */
+export const useDotGlyph: (opts?: BrontoBindingOptsResolver) => void;
+/** @type {(opts?: BrontoBindingOptsResolver) => void} */
+export const useLegend: (opts?: BrontoBindingOptsResolver) => void;
+/** @type {(opts?: BrontoBindingOptsResolver) => void} */
+export const useConnectors: (opts?: BrontoBindingOptsResolver) => void;
+/** @type {(opts?: BrontoBindingOptsResolver) => void} */
+export const useSpotlight: (opts?: BrontoBindingOptsResolver) => void;
+/** @type {(opts?: BrontoBindingOptsResolver) => void} */
+export const useCrosshair: (opts?: BrontoBindingOptsResolver) => void;
+/** @type {(opts?: BrontoBindingOptsResolver) => void} */
+export const useCommand: (opts?: BrontoBindingOptsResolver) => void;
+/** The `toast()` imperative (no lifecycle of its own).
+ * @type {() => (message: string, opts?: ToastOpts) => Cleanup} */
+export const 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;
+/**
+ * Behavior options with the `root` widened to accept Solid refs/resolvers.
+ */
+export type BrontoBindingOpts<T extends DelegateOpts = import("../behaviors/internal.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 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?: 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';
+/**
+ * `BrontoBindingOpts<T>`, or a callback that returns it on mount (after refs).
+ */
+export type BrontoBindingOptsResolver<T extends DelegateOpts = import("../behaviors/internal.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/solid/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.js"],"names":[],"mappings":"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"}