@cascivo/react 0.14.0 → 0.16.1

package/dist/index.d.ts

@@ -21,8 +21,8 @@
  * Docs: https://cascivo.com/llms.txt — or fully offline, no website needed:
  *   npx -y @cascivo/docs            (index; `npx @cascivo/docs <component>` for one doc)
  */
-import { DismissableLayer, DismissableLayerProps, ErrorBoundary, FocusScope, LinkComponent, LinkComponentProps, Machine, MachineConfig, Portal, Presence, ProgressInput, RovingOrientation, Signal, Slot, SlotProps, SpaceStep, SuspenseBoundary, ToneInput, UseClipboardOptions, UseClipboardReturn, UseControllableSignalOptions, UseDisclosureOptions, UseDisclosureReturn, VisuallyHidden, VisuallyHiddenProps, batch, cn, composeRefs, computePosition, computed, createMachine, createScope, createStreamBuffer, effect, getLinkComponent, mergeProps, setLinkComponent, signal, useAnchorPosition, useClipboard, useComputed, useControllableSignal, useDisclosure, useEffectPropSignal, useId, useMachine, useMediaQuery, useRovingFocus, useScope, useScrollLock, useSignal, useSignalEffect, useSignals, useStreamBuffer, useTypeahead } from "@cascivo/core";
 import { AnchorHTMLAttributes, ButtonHTMLAttributes, FormHTMLAttributes, HTMLAttributes, ImgHTMLAttributes, InputHTMLAttributes, LabelHTMLAttributes, LiHTMLAttributes, MouseEvent, ReactElement, ReactNode, RefObject, SelectHTMLAttributes, TextareaHTMLAttributes, TimeHTMLAttributes } from "react";
+import { DismissableLayer, DismissableLayerProps, ErrorBoundary, FocusScope, LinkComponent, LinkComponentProps, Machine, MachineConfig, Portal, Presence, ProgressInput, RovingOrientation, Signal, Slot, SlotProps, SpaceStep, SuspenseBoundary, ThemeProvider, ThemeProviderProps, ToneInput, UseClipboardOptions, UseClipboardReturn, UseControllableSignalOptions, UseDisclosureOptions, UseDisclosureReturn, VisuallyHidden, VisuallyHiddenProps, applyTheme, batch, cn, composeRefs, computePosition, computed, createMachine, createScope, createStreamBuffer, effect, getLinkComponent, mergeProps, setLinkComponent, setTheme, signal, themePreloadScript, themeSignal, useAnchorPosition, useClipboard, useComputed, useControllableSignal, useDisclosure, useEffectPropSignal, useId, useMachine, useMediaQuery, useRovingFocus, useScope, useScrollLock, useSignal, useSignalEffect, useSignals, useStreamBuffer, useTheme, useTypeahead } from "@cascivo/core";
 
 interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
   /**
@@ -433,6 +433,15 @@ interface SelectOption {
    */
   disabled?: boolean;
 }
+/**
+ * ⚠ `Select` is a **native `<select>` wrapper**, so its change handler is the DOM
+ * `onChange(event)` — read the value off `event.target.value`. There is **no**
+ * `onValueChange`; TypeScript unhelpfully suggests `onVolumeChange` when you try it.
+ *
+ * The catalog's `onValueChange` convention covers composite components that invent their
+ * own value (`Tabs`, `Combobox`, `Toggle`, …). `Select`, like `Checkbox` and
+ * `NativeSelect`, spreads onto a real element and inherits that element's event.
+ */
 interface SelectProps extends Omit<SelectHTMLAttributes<HTMLSelectElement>, 'size'> {
   label?: string;
   hint?: string;
@@ -526,6 +535,13 @@ interface ToggleProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'onC
  * not work there.
  */
 declare const Toggle: import("react").ForwardRefExoticComponent<ToggleProps & import("react").RefAttributes<HTMLButtonElement>>;
+/**
+ * ⚠ `Slider` is a **native `<input type="range">` wrapper**, so its change handler is the
+ * DOM `onChange(event)` — read the value off `event.target.value`. There is **no**
+ * `onValueChange`, despite the catalog convention of that name for value-carrying
+ * callbacks: that convention covers composite components that invent their own value,
+ * while this one inherits the underlying element's event.
+ */
 interface SliderProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'type'> {
   label?: string;
 }
@@ -652,6 +668,26 @@ declare function TabsList({
 interface TabsTriggerProps extends HTMLAttributes<HTMLButtonElement> {
   value: string;
   disabled?: boolean;
+  /**
+   * Render your own element instead of the `<button>`, keeping every tab behaviour
+   * (`role="tab"`, `aria-selected`, `aria-controls`, the roving `tabIndex`, `data-state`)
+   * and the tab styling.
+   *
+   * This exists for **URL-driven tabs**, the canonical dashboard shape: one route per tab.
+   * Navigating from `onValueChange` instead loses middle-click, cmd-click, open-in-new-tab
+   * and a crawlable `href` — a real anchor gives you all four for free.
+   *
+   * ```tsx
+   * <TabsTrigger value="overview" asChild>
+   *   <Link to="/projects/$id/overview">Overview</Link>
+   * </TabsTrigger>
+   * ```
+   *
+   * With `asChild`, `disabled` becomes `aria-disabled`: it is not a valid attribute on an
+   * anchor, and a slotted element gets no `type` either. See
+   * [USING-WITH-A-ROUTER.md](../../../../docs/USING-WITH-A-ROUTER.md) for the full recipe.
+   */
+  asChild?: boolean;
 }
 /**
  * `forwardRef` so `ref` reaches the tab `<button>` — see `textarea.tsx` for the full
@@ -679,9 +715,14 @@ declare function Accordion({
   className,
   children
 }: AccordionProps): import("react").JSX.Element;
-interface AccordionItemProps extends HTMLAttributes<HTMLDivElement> {
+interface AccordionItemProps extends HTMLAttributes<HTMLElement> {
   value: string;
 }
+/**
+ * Renders the `<details>` element itself, so `AccordionTrigger` (a `<summary>`) and
+ * `AccordionContent` land as its first and second children — which is exactly the shape
+ * consumers already write.
+ */
 declare function AccordionItem({
   value,
   className,
@@ -689,11 +730,12 @@ declare function AccordionItem({
   ...props
 }: AccordionItemProps): import("react").JSX.Element;
 /**
- * `forwardRef` so `ref` reaches the trigger `<button>` — see `textarea.tsx` for the full
- * rationale (2026-07-28 report C10). The ref is threaded through the private Inner, which is
- * where the button actually lives.
+ * `forwardRef` so `ref` reaches the trigger element — see `textarea.tsx` for the full
+ * rationale (2026-07-28 report C10). The target is the `<summary>`, not a `<button>`:
+ * `<summary>` must be the first child of `<details>`, so it cannot be nested inside a
+ * heading. The heading moves inside it instead, which `<summary>`'s content model allows.
  */
-declare const AccordionTrigger: import("react").ForwardRefExoticComponent<HTMLAttributes<HTMLButtonElement> & import("react").RefAttributes<HTMLButtonElement>>;
+declare const AccordionTrigger: import("react").ForwardRefExoticComponent<HTMLAttributes<HTMLElement> & import("react").RefAttributes<HTMLElement>>;
 declare function AccordionContent(props: HTMLAttributes<HTMLDivElement>): import("react").JSX.Element;
 interface ActionSheetAction {
   label: ReactNode;
@@ -1407,19 +1449,24 @@ interface Column<Row> {
   align?: 'start' | 'end';
   /**
    * Preferred column width, any CSS length (`'8rem'`, `'120px'`, `'12%'`). Set it on
-   * identifier-shaped columns (commit hashes, IDs, timestamps) — default sizing doesn't
-   * consider content shape, so a hash wraps mid-hash.
+   * identifier-shaped columns (ids, statuses, dates) so they stop stealing space from the
+   * free-form ones.
    *
-   * **Mixing sized and unsized columns is supported**: unsized columns absorb the
-   * remaining width and never collapse below their content. Only when *every* column
-   * declares a width does the table switch to a fixed layout (which keeps widths
-   * identical across pages); otherwise widths are preferred sizes, not hard ones.
+   * It is a *preferred* size with a **content floor**: a sized column never shrinks below
+   * its own longest word, so you do not need a paired `minWidth` just to stop it
+   * collapsing. Use `minWidth` only to raise the floor above the content.
+   *
+   * ⚠ **Sizing EVERY column changes the layout mode.** Only then does the table switch to
+   * `table-layout: fixed` (which keeps widths identical across pages), and a fixed table
+   * can exceed its container — the extra columns are reachable by horizontal scroll, not
+   * dropped. Leave at least one free-form column unsized unless you specifically want
+   * page-stable widths.
    */
   width?: string;
   /**
-   * Floor for the column's width, any CSS length. Use it on a free-form column
-   * (a commit message, a description) that must stay readable when the table is narrow —
-   * the table then scrolls horizontally rather than squeezing the column to nothing.
+   * Floor for the column's width, any CSS length. Use it on a free-form column that should
+   * get a minimum share, or to raise a sized column's floor above its content — the
+   * content floor is automatic, so this is no longer needed merely to prevent collapse.
    */
   minWidth?: string;
 }
@@ -2016,11 +2063,17 @@ declare function Menu({
 }: MenuProps): import("react").JSX.Element;
 interface MenuTriggerProps {
   children: ReactNode;
+  /**
+   * Invisible accessible name. The catalog convention (see the item-identity table in
+   * `docs/AI-RULES.md`); `aria-label` is accepted as an alias for the DOM spelling.
+   */
+  ariaLabel?: string;
   'aria-label'?: string;
 }
 declare function MenuTrigger({
   children,
-  'aria-label': ariaLabel
+  ariaLabel,
+  'aria-label': ariaLabelDom
 }: MenuTriggerProps): import("react").JSX.Element;
 interface MenuItemProps {
   children: ReactNode;
@@ -2655,6 +2708,20 @@ interface StatProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
   value: string | number;
   delta?: string;
   trend?: 'up' | 'down' | 'flat';
+  /**
+   * Which direction is *good* for this metric — the colour, independent of the arrow.
+   *
+   * `trend` says which way the number moved; this says whether that is welcome. They are
+   * the same question only for metrics where up is better, and hard-coding that made every
+   * error-rate, latency, cost and churn tile render its worst news in green. Lying about
+   * `trend` to fix the colour also reverses the arrow, so there was no correct answer.
+   *
+   * `'neutral'` keeps the arrow and drops the sentiment colour, for metrics where neither
+   * direction is inherently good (headcount, page views).
+   *
+   * @defaultValue `up`
+   */
+  goodDirection?: 'up' | 'down' | 'neutral';
   helpText?: string;
   /**
    * Wrap the tile in the same card chrome (surface, border, radius, padding) that
@@ -2672,6 +2739,7 @@ declare function Stat({
   value,
   delta,
   trend,
+  goodDirection,
   helpText,
   card,
   visual,
@@ -3406,10 +3474,11 @@ interface CollapsibleProps {
   defaultOpen?: boolean;
   /** Called whenever the open state should change. */
   onOpenChange?: (open: boolean) => void;
-  /** Content rendered inside the trigger button. */
+  /** Content rendered inside the trigger. */
   trigger: ReactNode;
   /**
-   * Disables the trigger button
+   * Disables the trigger. Enforced in the enhancement layer — <details> has no native
+   * disabled state, so with JavaScript off a disabled Collapsible is still operable
    *
    * @defaultValue `false`
    * @see the component manifest
@@ -3520,14 +3589,27 @@ interface MenubarMenu {
   label: ReactNode;
   items: MenubarItem[];
 }
-interface MenubarProps {
+interface MenubarBaseProps {
   menus: MenubarMenu[];
-  'aria-label': string;
   className?: string;
 }
+/**
+ * Exactly one of `ariaLabel` / `aria-label` is required — a menubar landmark with no
+ * accessible name is a bug, so this stays enforced by the type rather than a dev warning.
+ * `ariaLabel` is the catalog's convention; `aria-label` is the DOM spelling this component
+ * shipped with. Both work, mirroring `IconButton`.
+ */
+type MenubarProps = MenubarBaseProps & ({
+  ariaLabel: string;
+  'aria-label'?: never;
+} | {
+  'aria-label': string;
+  ariaLabel?: never;
+});
 declare function Menubar({
   menus,
-  'aria-label': ariaLabel,
+  ariaLabel,
+  'aria-label': ariaLabelDom,
   className
 }: MenubarProps): import("react").JSX.Element;
 interface NavigationMenuItem {
@@ -3538,6 +3620,11 @@ interface NavigationMenuItem {
 }
 interface NavigationMenuProps {
   items: NavigationMenuItem[];
+  /**
+   * Invisible accessible name. The catalog convention (see the item-identity table in
+   * `docs/AI-RULES.md`); `aria-label` is accepted as an alias for the DOM spelling.
+   */
+  ariaLabel?: string;
   'aria-label'?: string;
   /**
    * Layout orientation of the component.
@@ -3550,7 +3637,8 @@ interface NavigationMenuProps {
 }
 declare function NavigationMenu({
   items,
-  'aria-label': ariaLabel,
+  'aria-label': ariaLabelDom,
+  ariaLabel,
   orientation,
   className
 }: NavigationMenuProps): import("react").JSX.Element;
@@ -3570,6 +3658,11 @@ interface TreeViewProps {
   defaultExpanded?: string[];
   onExpandedChange?: (expanded: string[]) => void;
   className?: string;
+  /**
+   * Invisible accessible name. The catalog convention (see the item-identity table in
+   * `docs/AI-RULES.md`); `aria-label` is accepted as an alias for the DOM spelling.
+   */
+  ariaLabel?: string;
   'aria-label'?: string;
 }
 declare function TreeView({
@@ -3582,19 +3675,30 @@ declare function TreeView({
   defaultExpanded,
   onExpandedChange,
   className,
-  'aria-label': ariaLabel
+  'aria-label': ariaLabelDom,
+  ariaLabel
 }: TreeViewProps): import("react").JSX.Element;
 declare const treeViewMessages: {
   loading: () => string;
   expand: () => string;
   collapse: () => string;
 };
+/**
+ * One row's data. **This is a type, not a component.**
+ *
+ * `StructuredList` is config-driven: pass `items`, not children. An adopter imported
+ * `StructuredListItem` expecting a composable `<StructuredListItem>` — a reasonable guess,
+ * since most catalogs ship both forms — wrote markup against it, and only then found the
+ * real API. There is no composable form and none is planned; the config shape is what
+ * makes the list keyboard-navigable and selectable without per-row wiring.
+ */
 interface StructuredListItem {
   id: string;
   cells: ReactNode[];
   selected?: boolean;
 }
 interface StructuredListProps {
+  /** The rows. `StructuredList` is config-driven — there is no composable child form. */
   items: StructuredListItem[];
   headers?: ReactNode[];
   /**
@@ -4042,6 +4146,219 @@ declare function Dock({
   className,
   ariaLabel
 }: DockProps): import("react").JSX.Element;
+interface LargeTitleHeaderProps {
+  /** The page title. Rendered as the large heading and mirrored in the collapsed bar. */
+  title: string;
+  /** Content of the scrolling region, rendered below the title. */
+  children: ReactNode;
+  /** Leading slot of the compact bar — typically a back control. */
+  leading?: ReactNode;
+  /** Trailing slot of the compact bar — typically icon buttons. */
+  actions?: ReactNode;
+  /**
+   * Heading level for the title, mapping to h1–h3.
+   *
+   * @defaultValue `1`
+   * @see the component manifest
+   */
+  level?: 1 | 2 | 3;
+  /**
+   * Scroll distance (px) over which the large title collapses into the bar.
+   *
+   * @defaultValue `48`
+   * @see the component manifest
+   */
+  collapseDistance?: number;
+  className?: string;
+}
+/**
+ * Scrolling region with an iOS-style page header: the large title scrolls away and a
+ * compact sticky bar reveals the same title in its place.
+ *
+ * The collapse is a CSS scroll-driven animation — no scroll listener, no
+ * IntersectionObserver, no client JavaScript of any kind, so this renders complete from
+ * the server and never hydrates. Where `animation-timeline` is unsupported the mirrored
+ * title stays hidden and the region degrades to a plain sticky bar above a heading; the
+ * heading itself is always present, so no content depends on the enhancement.
+ *
+ * The component owns the scroll container so the sticky bar and the scroll timeline
+ * cannot be broken by the surrounding markup. Give it a parent with a resolved height.
+ */
+declare function LargeTitleHeader({
+  title,
+  children,
+  leading,
+  actions,
+  level,
+  collapseDistance,
+  className
+}: LargeTitleHeaderProps): import("react").JSX.Element;
+interface InfiniteScrollProps {
+  /** Called when the sentinel comes into view, or the button is activated. */
+  onLoadMore: () => Promise<unknown> | unknown;
+  /**
+   * When true, stops observing and renders nothing — there are no more pages.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
+  disabled?: boolean;
+  /**
+   * How far ahead of the end to start loading, as an IntersectionObserver root margin.
+   *
+   * @defaultValue `'200px'`
+   * @see the component manifest
+   */
+  rootMargin?: string;
+  labels?: {
+    loadMore?: string;
+    loading?: string;
+  };
+  className?: string;
+}
+/**
+ * Loads the next page when the end of a list comes into view.
+ *
+ * Place it as the last child of the scrolling region, after the list. It renders a real
+ * "Load more" button and auto-activates it via an `IntersectionObserver` — so the next
+ * page is reachable by keyboard and by screen reader, not only by scrolling, which is the
+ * standing accessibility complaint against scroll-only infinite lists. Re-entry is
+ * guarded, so a sentinel that stays visible after a short page cannot loop.
+ */
+declare function InfiniteScroll({
+  onLoadMore,
+  disabled,
+  rootMargin,
+  labels,
+  className
+}: InfiniteScrollProps): import("react").JSX.Element | null;
+interface ReorderItem {
+  id: string;
+  label: ReactNode;
+  /** Plain-text name used in announcements when `label` is not a string. */
+  name?: string;
+}
+interface ReorderListProps {
+  value: ReorderItem[];
+  onValueChange: (value: ReorderItem[]) => void;
+  /**
+   * When true, disables the control and removes it from the tab order.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
+  disabled?: boolean;
+  labels?: {
+    handle?: string;
+    grabbed?: string;
+    moved?: string;
+    dropped?: string;
+    cancelled?: string;
+  };
+  className?: string;
+}
+/**
+ * A list whose rows can be reordered by pointer drag or entirely by keyboard.
+ *
+ * Each row carries a drag handle. Space or Enter picks the row up, Arrow keys move it,
+ * Space or Enter drops it, and Escape restores the order it had before the pick-up — the
+ * keyboard path Ionic's pointer-only `ion-reorder` has no equivalent for. Every transition
+ * is announced through a polite live region.
+ */
+declare function ReorderList({
+  value,
+  onValueChange,
+  disabled,
+  labels,
+  className
+}: ReorderListProps): import("react").JSX.Element;
+interface VirtualListProps<Item> {
+  items: Item[];
+  /** Fixed row height in px. Rows must all be this tall for positions to be correct. */
+  itemHeight: number;
+  /**
+   * Height of the scrolling viewport, in px.
+   *
+   * Deliberately not a CSS length: the visible row count is computed from this number, and
+   * a relative length like `100%` cannot be resolved without measuring. Wrap the list and
+   * pass a measured px value if the height has to be fluid.
+   */
+  height: number;
+  renderItem: (item: Item, index: number) => ReactNode;
+  /**
+   * Extra rows rendered above and below the visible window, to cover fast scrolling.
+   *
+   * @defaultValue `3`
+   * @see the component manifest
+   */
+  overscan?: number;
+  /** Accessible label for the list; defaults to none, so label it when standalone. */
+  ariaLabel?: string;
+  className?: string;
+}
+/**
+ * Renders only the rows inside the scrolled viewport, so a list of any length costs a
+ * constant number of DOM nodes.
+ *
+ * Row height is fixed: positions are arithmetic rather than measured, which keeps scrolling
+ * on the compositor and avoids a layout pass per frame. Each rendered row carries
+ * `aria-setsize` and `aria-posinset` for the **full** collection, so assistive technology
+ * reports "3 of 10000" rather than the size of the rendered window.
+ */
+declare function VirtualList<Item>({
+  items,
+  itemHeight,
+  height,
+  renderItem,
+  overscan,
+  ariaLabel,
+  className
+}: VirtualListProps<Item>): import("react").JSX.Element;
+interface WheelPickerOption {
+  value: string;
+  label: string;
+}
+interface WheelPickerProps {
+  options: WheelPickerOption[];
+  value: string;
+  onValueChange: (value: string) => void;
+  /**
+   * How many rows are visible. Odd numbers keep the selection centred.
+   *
+   * @defaultValue `5`
+   * @see the component manifest
+   */
+  visibleCount?: number;
+  /**
+   * Row height in px.
+   *
+   * @defaultValue `36`
+   * @see the component manifest
+   */
+  itemHeight?: number;
+  ariaLabel?: string;
+  className?: string;
+}
+/**
+ * iOS-style drum picker: a column of options that scrolls and snaps to a centred selection.
+ *
+ * The wheel is CSS scroll-snap, not a JavaScript gesture engine — momentum, rubber-banding
+ * and snapping are the platform's, so the whole gesture runs on the compositor and behaves
+ * natively on every device. JavaScript only reads which row settled and moves the column
+ * when the value changes from outside.
+ *
+ * Semantically a single-select listbox whose selection follows focus: Arrow keys, Home and
+ * End move the selection and scroll to match, so there is nothing to confirm.
+ */
+declare function WheelPicker({
+  options,
+  value,
+  onValueChange,
+  visibleCount,
+  itemHeight,
+  ariaLabel,
+  className
+}: WheelPickerProps): import("react").JSX.Element;
 interface DrawerProps {
   /** Controlled open state. */
   open?: boolean;
@@ -4395,6 +4712,11 @@ interface RadialProgressProps {
    */
   variant?: RadialProgressVariant;
   children?: React.ReactNode;
+  /**
+   * Invisible accessible name. The catalog convention (see the item-identity table in
+   * `docs/AI-RULES.md`); `aria-label` is accepted as an alias for the DOM spelling.
+   */
+  ariaLabel?: string;
   'aria-label'?: string;
   className?: string;
 }
@@ -4404,6 +4726,7 @@ declare function RadialProgress({
   variant,
   children,
   className,
+  ariaLabel,
   ...aria
 }: RadialProgressProps): import("react").JSX.Element;
 type SwapMode = 'rotate' | 'flip';
@@ -4422,6 +4745,11 @@ interface SwapProps {
   /** @deprecated Use `onValueChange` — it receives the same `checked` boolean. */
   onChange?: (checked: boolean) => void;
   mode?: SwapMode;
+  /**
+   * Invisible accessible name. The catalog convention (see the item-identity table in
+   * `docs/AI-RULES.md`); `aria-label` is accepted as an alias for the DOM spelling.
+   */
+  ariaLabel?: string;
   'aria-label'?: string;
   className?: string;
 }
@@ -4433,6 +4761,7 @@ declare function Swap({
   onChange,
   mode,
   className,
+  ariaLabel,
   ...aria
 }: SwapProps): import("react").JSX.Element;
 interface SwipeAction {
@@ -4653,143 +4982,4 @@ declare function PageHeader({
   actions,
   className
 }: PageHeaderProps): import("react").JSX.Element;
-/**
- * Set the active theme imperatively, from anywhere. Persists the choice and
- * drives the `data-theme` attribute through the mounted {@link ThemeProvider}.
- *
- * Requires a mounted {@link ThemeProvider} — this writes the signal, the provider writes
- * the DOM. Without one, nothing restyles (dev builds warn). To write the attribute
- * directly, with no provider and no React, use {@link applyTheme}.
- */
-declare function setTheme(next: string): void;
-/**
- * Write a theme onto an element directly, with no provider and no React.
- *
- * The escape hatch for imperative setups: a theme toggle in a non-React shell, a
- * pre-hydration inline script, a Storybook decorator, an e2e test. Also updates the theme
- * signal, so a React tree reading {@link useTheme} stays in sync.
- *
- * `setTheme` deliberately does **not** do this itself: it is SSR-callable, and
- * `ThemeProvider` can scope a theme to any subtree via its `target` ref. A direct document
- * write inside `setTheme` would break scoped theming and touch `document` on the server.
- *
- * ```ts
- * applyTheme('midnight')                       // <html data-theme="midnight">
- * applyTheme('warm', panelRef.current)         // scope to a subtree
- * ```
- *
- * No-op on the server (no `document`).
- */
-declare function applyTheme(next: string, target?: HTMLElement | null): void;
-/**
- * Read and set the active theme. Returns the current theme **name** (a plain
- * string) and a setter — the component re-renders when the theme changes with no
- * signal handling on your part (this hook calls `useSignals()` for you, so it
- * works in React apps with no Babel transform). This is the React-idiomatic shape;
- * for signal-native code (`computed()`, `effect()`, Preact) use {@link themeSignal}.
- *
- * ```tsx
- * const [theme, setTheme] = useTheme()
- * return <button onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}>
- *   {theme}
- * </button>
- * ```
- */
-declare function useTheme(): readonly [string, (next: string) => void];
-/**
- * The underlying theme signal, for signal-native code — `computed()`, `effect()`,
- * or a Preact app where signals are natively reactive. Most React apps want
- * {@link useTheme}, which hands back a plain string and handles subscription.
- */
-declare function themeSignal(): Signal<string>;
-interface ThemeProviderProps {
-  /**
-   * Theme to use when nothing is persisted yet. When set, it **wins over** the
-   * visitor's OS `prefers-color-scheme` — pass it for a "dark by default" or
-   * custom-theme (`'midnight'`, …) app. Omit it to follow the OS (light/dark),
-   * falling back to `'light'`. Precedence: persisted value > `defaultTheme` (if
-   * set) > OS preference > `'light'`.
-   */
-  defaultTheme?: string;
-  /**
-   * Controlled theme. When set, the provider mirrors it on every render and the
-   * persisted value is ignored — the parent owns the state (React semantics).
-   */
-  value?: string;
-  /** localStorage key for the persisted choice. Defaults to `cascivo-theme`. */
-  storageKey?: string;
-  /** Attribute written to the target element. Defaults to `data-theme`. */
-  attribute?: string;
-  /**
-   * Element to theme. Omit to theme the whole document (`<html>`). Pass a ref to
-   * a container to scope the theme to a subtree — cascivo themes resolve against
-   * the nearest `data-theme`, so a scoped subtree can differ from the page.
-   */
-  target?: RefObject<HTMLElement | null>;
-  /** Called whenever the active theme changes. */
-  onChange?: (theme: string) => void;
-  /**
-   * CSP nonce forwarded to the inline attribute-setter script emitted for the
-   * controlled ({@link ThemeProviderProps.value}) SSR flow. Set it to match your
-   * Content-Security-Policy `script-src 'nonce-…'`.
-   */
-  nonce?: string;
-  children?: ReactNode;
-}
-/**
- * Binds the active theme signal to a `data-theme` attribute and persists the
- * choice — the reusable, SSR-safe form of the wiring apps otherwise hand-roll.
- *
- * - No flash of the wrong theme: pair with {@link themePreloadScript} in your
- *   document `<head>` so the correct theme paints on first byte.
- * - No banned React hooks: the DOM write happens in `useSignalEffect`, not
- *   `useEffect`; there is no `useState`/`useContext`.
- * - Uncontrolled by default (persists to localStorage); pass `value` to control.
- * - SSR-safe when controlled: with a `value` (and no scoped `target`), the
- *   provider renders a tiny inline script that sets `data-theme` during HTML
- *   parsing, so the server-rendered first paint is themed — no flash, no
- *   hydration mismatch (the same markup renders on both sides; the client effect
- *   owns every update after hydration). For the uncontrolled/persisted flow, pair
- *   with {@link themePreloadScript} in `<head>` instead.
- */
-declare function ThemeProvider({
-  defaultTheme,
-  value,
-  storageKey,
-  attribute,
-  target,
-  onChange,
-  nonce,
-  children
-}: ThemeProviderProps): ReactNode;
-/**
- * A tiny script to inline in your document `<head>` (before the app bundle) so
- * the persisted theme paints on the first byte — no flash of the wrong theme on
- * SSR or a hard reload. Pass the same `storageKey`/`attribute`/`defaultTheme`
- * you give {@link ThemeProvider}.
- *
- * Precedence matches {@link ThemeProvider}: persisted value > `defaultTheme`
- * (if set) > OS `prefers-color-scheme` > `'light'`. Passing `defaultTheme`
- * suppresses the OS check, so a "dark by default" app stays dark on a light-OS
- * visitor.
- *
- * The script sets `data-theme` **before** React hydrates, so add
- * `suppressHydrationWarning` to the element that carries the attribute (usually
- * `<html>`) — the mutation is intentional, and without the flag React 19 logs a
- * hydration mismatch.
- *
- * ```tsx
- * // Next.js app/layout.tsx
- * <html suppressHydrationWarning>
- *   <head>
- *     <script dangerouslySetInnerHTML={{ __html: themePreloadScript({ defaultTheme: 'dark' }) }} />
- *   </head>
- * </html>
- * ```
- */
-declare function themePreloadScript(options?: {
-  storageKey?: string;
-  attribute?: string;
-  defaultTheme?: string;
-}): string;
-export { Accordion, AccordionContent, AccordionItem, AccordionItemProps, AccordionProps, AccordionTrigger, ActionSheet, ActionSheetAction, ActionSheetProps, Alert, AlertDialog, AlertDialogLabels, AlertDialogProps, AlertProps, AppShell, AppShellProps, AspectRatio, AspectRatioProps, AutoGrid, AutoGridProps, Avatar, AvatarGroup, AvatarGroupLabels, AvatarGroupProps, AvatarProps, Badge, BadgeProps, Blockquote, BlockquoteProps, BottomSheet, BottomSheetProps, Breadcrumb, BreadcrumbItem, BreadcrumbProps, Button, ButtonGroup, ButtonGroupProps, ButtonProps, Calendar, CalendarLabels, CalendarProps, Card, CardContent, CardContentProps, CardFooter, CardFooterProps, CardHeader, CardHeaderProps, CardProps, CardTitle, CardTitleProps, Carousel, CarouselLabels, CarouselProps, Center, CenterProps, ChatBubble, ChatBubbleProps, ChatBubbleSide, Checkbox, CheckboxCard, CheckboxCardProps, CheckboxProps, Code, type CodeLang, CodeProps, CodeSnippet, CodeSnippetProps, Collapsible, CollapsibleProps, ColorPicker, ColorPickerLabels, ColorPickerProps, Column, Columns, ColumnsProps, Combobox, ComboboxLabels, ComboboxOption, ComboboxProps, CommandAction, CommandGroup, CommandItem, CommandMenu, CommandMenuProps, CommandPage, CommandScope, CommandStatus, Comparison, ComparisonProps, ContainedList, ContainedListItem, ContainedListItemProps, ContainedListProps, ContextMenu, ContextMenuItem, ContextMenuItemProps, ContextMenuProps, CopyButton, CopyButtonProps, DataList, DataListItem, DataListProps, DataTable, DataTableLabels, DataTableProps, DatePicker, DatePickerLabels, DatePickerProps, DateRange, DateRangePicker, DateRangePickerLabels, DateRangePickerProps, DateRangePreset, DismissableLayer, type DismissableLayerProps, Dock, DockItem, DockProps, Drawer, DrawerProps, Dropdown, DropdownItem, DropdownProps, Editable, EditableProps, EmptyState, EmptyStateProps, ErrorBoundary, Fab, FabAction, FabProps, Field, FieldProps, FileUploader, FileUploaderLabels, FileUploaderProps, Filter, FilterOption, FilterProps, FilterVariant, Flex, FlexProps, FocusScope, Form, FormConfig, FormProps, FormStore, FuzzyMatch, Grid, GridAlign, GridItem, GridItemProps, GridProps, Header, HeaderLabels, HeaderLink, HeaderPanel, HeaderPanelLabels, HeaderPanelProps, HeaderProps, Heading, HeadingLevel, HeadingProps, HeadingSize, HoverCard, HoverCardContent, HoverCardContentProps, HoverCardProps, HoverCardTrigger, HoverCardTriggerProps, IconButton, IconButtonProps, Image, ImageProps, Indicator, IndicatorPlacement, IndicatorProps, InlineLoading, InlineLoadingProps, InlineLoadingStatus, Input, InputGroup, InputGroupAddon, type InputGroupAddonProps, type InputGroupProps, InputProps, Item, ItemActions, ItemActionsProps, ItemContent, ItemContentProps, ItemDescription, ItemDescriptionProps, ItemMedia, ItemMediaProps, ItemProps, ItemTitle, ItemTitleProps, Join, JoinOrientation, JoinProps, Kbd, KbdProps, Label, LabelProps, Link, type LinkComponent, type LinkComponentProps, LinkProps, List, ListItem, ListItemProps, ListProps, LogLevel, LogLine, LogViewer, LogViewerLabels, LogViewerProps, type Machine, type MachineConfig, Menu, MenuButton, MenuButtonItem, MenuButtonProps, MenuItem, MenuItemProps, MenuProps, MenuSeparator, MenuTrigger, MenuTriggerProps, Menubar, MenubarItem, MenubarMenu, MenubarProps, Modal, ModalProps, MultiSelect, MultiSelectLabels, MultiSelectOption, MultiSelectProps, NativeSelect, NativeSelectOption, NativeSelectProps, NavigationMenu, NavigationMenuItem, NavigationMenuProps, Notification, NotificationProps, NotificationVariant, NumberInput, NumberInputProps, OtpInput, OtpInputProps, OverflowMenu, OverflowMenuItem, OverflowMenuProps, PageHeader, PageHeaderProps, Pagination, PaginationLabels, PaginationProps, PasswordInput, PasswordInputLabels, PasswordInputProps, Popover, PopoverContent, PopoverContentProps, PopoverProps, PopoverTrigger, PopoverTriggerProps, Portal, Presence, Progress, ProgressBar, ProgressBarProps, ProgressCircle, ProgressCircleProps, ProgressIndicator, ProgressIndicatorProps, ProgressProps, ProgressSize, ProgressStep, ProgressVariant, Prose, ProseProps, PullToRefresh, PullToRefreshProps, QrCode, QrCodeProps, RadialProgress, RadialProgressProps, RadialProgressSize, RadialProgressVariant, Radio, RadioCard, RadioCardGroup, RadioCardGroupProps, RadioCardProps, RadioGroup, RadioGroupProps, RadioProps, RatingGroup, RatingGroupLabels, RatingGroupProps, RelativeTime, RelativeTimeProps, Resizable, ResizableProps, Responsive, ScrollArea, ScrollAreaProps, Search, SearchProps, SegmentedControl, SegmentedControlOption, SegmentedControlProps, Select, SelectOption, SelectProps, Separator, SeparatorProps, Sheet, SheetProps, ShellHeader, ShellHeaderAction, ShellHeaderBrand, ShellHeaderLabels, ShellHeaderNavItem, ShellHeaderNavLink, ShellHeaderNavMenu, ShellHeaderNavMenuItem, ShellHeaderProps, SideNav, SideNavGroup, SideNavItem, SideNavLinkProps, SideNavLinkSubItem, SideNavProps, SideNavSubItem, SideNavTone, Skeleton, SkeletonProps, SkipNavLink, SkipNavLinkProps, SkipNavTarget, SkipNavTargetProps, Slider, SliderProps, Slot, type SlotProps, SortDirection, SortState, Spacer, SpacerProps, Spinner, SpinnerProps, Stack, StackProps, type StandardSchemaV1, Stat, StatProps, Status, StatusProps, Step, StepState, Steps, StepsProps, StructuredList, StructuredListItem, StructuredListProps, SuspenseBoundary, Swap, SwapMode, SwapProps, SwipeAction, SwipeItem, SwipeItemProps, Switcher, SwitcherEntry, SwitcherLink, SwitcherProps, Tabs, TabsContent, TabsContentProps, TabsList, TabsProps, TabsTrigger, TabsTriggerProps, Tag, TagProps, TagsInput, TagsInputProps, Text, TextProps, Textarea, TextareaProps, ThemeProvider, type ThemeProviderProps, Tile, TileProps, TimePicker, TimePickerProps, Timeline, TimelineItem, TimelineProps, ToastOptions, ToastProvider, ToastVariant, Toc, TocItem, TocProps, Toggle, ToggleGroup, ToggleGroupItem, ToggleGroupProps, ToggleProps, Toggletip, ToggletipPlacement, ToggletipProps, Tooltip, TooltipProps, TreeNode, TreeView, TreeViewProps, UploaderFile, type UseClipboardOptions, type UseClipboardReturn, type UseControllableSignalOptions, type UseDisclosureOptions, type UseDisclosureReturn, type UsePopoverOptions, type UsePopoverReturn, type UseTocFromRegionOptions, User, UserProps, VisuallyHidden, VisuallyHiddenProps, applyTheme, batch, cn, composeRefs, computePosition, computed, createForm, createMachine, createScope, createStreamBuffer, dismissAllToasts, effect, fuzzyMatch, fuzzyScore, getLinkComponent, mergeProps, setLinkComponent, setTheme, signal, themePreloadScript, themeSignal, treeViewMessages, useAnchorPosition, useClipboard, useComputed, useControllableSignal, useDisclosure, useEffectPropSignal, useForm, useId, useMachine, useMediaQuery, usePopover, useRovingFocus, useScope, useScrollLock, useSignal, useSignalEffect, useSignals, useStreamBuffer, useTheme, useToast, useTocFromRegion, useTypeahead };
+export { Accordion, AccordionContent, AccordionItem, AccordionItemProps, AccordionProps, AccordionTrigger, ActionSheet, ActionSheetAction, ActionSheetProps, Alert, AlertDialog, AlertDialogLabels, AlertDialogProps, AlertProps, AppShell, AppShellProps, AspectRatio, AspectRatioProps, AutoGrid, AutoGridProps, Avatar, AvatarGroup, AvatarGroupLabels, AvatarGroupProps, AvatarProps, Badge, BadgeProps, Blockquote, BlockquoteProps, BottomSheet, BottomSheetProps, Breadcrumb, BreadcrumbItem, BreadcrumbProps, Button, ButtonGroup, ButtonGroupProps, ButtonProps, Calendar, CalendarLabels, CalendarProps, Card, CardContent, CardContentProps, CardFooter, CardFooterProps, CardHeader, CardHeaderProps, CardProps, CardTitle, CardTitleProps, Carousel, CarouselLabels, CarouselProps, Center, CenterProps, ChatBubble, ChatBubbleProps, ChatBubbleSide, Checkbox, CheckboxCard, CheckboxCardProps, CheckboxProps, Code, type CodeLang, CodeProps, CodeSnippet, CodeSnippetProps, Collapsible, CollapsibleProps, ColorPicker, ColorPickerLabels, ColorPickerProps, Column, Columns, ColumnsProps, Combobox, ComboboxLabels, ComboboxOption, ComboboxProps, CommandAction, CommandGroup, CommandItem, CommandMenu, CommandMenuProps, CommandPage, CommandScope, CommandStatus, Comparison, ComparisonProps, ContainedList, ContainedListItem, ContainedListItemProps, ContainedListProps, ContextMenu, ContextMenuItem, ContextMenuItemProps, ContextMenuProps, CopyButton, CopyButtonProps, DataList, DataListItem, DataListProps, DataTable, DataTableLabels, DataTableProps, DatePicker, DatePickerLabels, DatePickerProps, DateRange, DateRangePicker, DateRangePickerLabels, DateRangePickerProps, DateRangePreset, DismissableLayer, type DismissableLayerProps, Dock, DockItem, DockProps, Drawer, DrawerProps, Dropdown, DropdownItem, DropdownProps, Editable, EditableProps, EmptyState, EmptyStateProps, ErrorBoundary, Fab, FabAction, FabProps, Field, FieldProps, FileUploader, FileUploaderLabels, FileUploaderProps, Filter, FilterOption, FilterProps, FilterVariant, Flex, FlexProps, FocusScope, Form, FormConfig, FormProps, FormStore, FuzzyMatch, Grid, GridAlign, GridItem, GridItemProps, GridProps, Header, HeaderLabels, HeaderLink, HeaderPanel, HeaderPanelLabels, HeaderPanelProps, HeaderProps, Heading, HeadingLevel, HeadingProps, HeadingSize, HoverCard, HoverCardContent, HoverCardContentProps, HoverCardProps, HoverCardTrigger, HoverCardTriggerProps, IconButton, IconButtonProps, Image, ImageProps, Indicator, IndicatorPlacement, IndicatorProps, InfiniteScroll, InfiniteScrollProps, InlineLoading, InlineLoadingProps, InlineLoadingStatus, Input, InputGroup, InputGroupAddon, type InputGroupAddonProps, type InputGroupProps, InputProps, Item, ItemActions, ItemActionsProps, ItemContent, ItemContentProps, ItemDescription, ItemDescriptionProps, ItemMedia, ItemMediaProps, ItemProps, ItemTitle, ItemTitleProps, Join, JoinOrientation, JoinProps, Kbd, KbdProps, Label, LabelProps, LargeTitleHeader, LargeTitleHeaderProps, Link, type LinkComponent, type LinkComponentProps, LinkProps, List, ListItem, ListItemProps, ListProps, LogLevel, LogLine, LogViewer, LogViewerLabels, LogViewerProps, type Machine, type MachineConfig, Menu, MenuButton, MenuButtonItem, MenuButtonProps, MenuItem, MenuItemProps, MenuProps, MenuSeparator, MenuTrigger, MenuTriggerProps, Menubar, MenubarBaseProps, MenubarItem, MenubarMenu, MenubarProps, Modal, ModalProps, MultiSelect, MultiSelectLabels, MultiSelectOption, MultiSelectProps, NativeSelect, NativeSelectOption, NativeSelectProps, NavigationMenu, NavigationMenuItem, NavigationMenuProps, Notification, NotificationProps, NotificationVariant, NumberInput, NumberInputProps, OtpInput, OtpInputProps, OverflowMenu, OverflowMenuItem, OverflowMenuProps, PageHeader, PageHeaderProps, Pagination, PaginationLabels, PaginationProps, PasswordInput, PasswordInputLabels, PasswordInputProps, Popover, PopoverContent, PopoverContentProps, PopoverProps, PopoverTrigger, PopoverTriggerProps, Portal, Presence, Progress, ProgressBar, ProgressBarProps, ProgressCircle, ProgressCircleProps, ProgressIndicator, ProgressIndicatorProps, ProgressProps, ProgressSize, ProgressStep, ProgressVariant, Prose, ProseProps, PullToRefresh, PullToRefreshProps, QrCode, QrCodeProps, RadialProgress, RadialProgressProps, RadialProgressSize, RadialProgressVariant, Radio, RadioCard, RadioCardGroup, RadioCardGroupProps, RadioCardProps, RadioGroup, RadioGroupProps, RadioProps, RatingGroup, RatingGroupLabels, RatingGroupProps, RelativeTime, RelativeTimeProps, ReorderItem, ReorderList, ReorderListProps, Resizable, ResizableProps, Responsive, ScrollArea, ScrollAreaProps, Search, SearchProps, SegmentedControl, SegmentedControlOption, SegmentedControlProps, Select, SelectOption, SelectProps, Separator, SeparatorProps, Sheet, SheetProps, ShellHeader, ShellHeaderAction, ShellHeaderBrand, ShellHeaderLabels, ShellHeaderNavItem, ShellHeaderNavLink, ShellHeaderNavMenu, ShellHeaderNavMenuItem, ShellHeaderProps, SideNav, SideNavGroup, SideNavItem, SideNavLinkProps, SideNavLinkSubItem, SideNavProps, SideNavSubItem, SideNavTone, Skeleton, SkeletonProps, SkipNavLink, SkipNavLinkProps, SkipNavTarget, SkipNavTargetProps, Slider, SliderProps, Slot, type SlotProps, SortDirection, SortState, Spacer, SpacerProps, Spinner, SpinnerProps, Stack, StackProps, type StandardSchemaV1, Stat, StatProps, Status, StatusProps, Step, StepState, Steps, StepsProps, StructuredList, StructuredListItem, StructuredListProps, SuspenseBoundary, Swap, SwapMode, SwapProps, SwipeAction, SwipeItem, SwipeItemProps, Switcher, SwitcherEntry, SwitcherLink, SwitcherProps, Tabs, TabsContent, TabsContentProps, TabsList, TabsProps, TabsTrigger, TabsTriggerProps, Tag, TagProps, TagsInput, TagsInputProps, Text, TextProps, Textarea, TextareaProps, ThemeProvider, type ThemeProviderProps, Tile, TileProps, TimePicker, TimePickerProps, Timeline, TimelineItem, TimelineProps, ToastOptions, ToastProvider, ToastVariant, Toc, TocItem, TocProps, Toggle, ToggleGroup, ToggleGroupItem, ToggleGroupProps, ToggleProps, Toggletip, ToggletipPlacement, ToggletipProps, Tooltip, TooltipProps, TreeNode, TreeView, TreeViewProps, UploaderFile, type UseClipboardOptions, type UseClipboardReturn, type UseControllableSignalOptions, type UseDisclosureOptions, type UseDisclosureReturn, type UsePopoverOptions, type UsePopoverReturn, type UseTocFromRegionOptions, User, UserProps, VirtualList, VirtualListProps, VisuallyHidden, VisuallyHiddenProps, WheelPicker, WheelPickerOption, WheelPickerProps, applyTheme, batch, cn, composeRefs, computePosition, computed, createForm, createMachine, createScope, createStreamBuffer, dismissAllToasts, effect, fuzzyMatch, fuzzyScore, getLinkComponent, mergeProps, setLinkComponent, setTheme, signal, themePreloadScript, themeSignal, treeViewMessages, useAnchorPosition, useClipboard, useComputed, useControllableSignal, useDisclosure, useEffectPropSignal, useForm, useId, useMachine, useMediaQuery, usePopover, useRovingFocus, useScope, useScrollLock, useSignal, useSignalEffect, useSignals, useStreamBuffer, useTheme, useToast, useTocFromRegion, useTypeahead };