@skdx/react 0.26.0 → 0.28.0

package/dist/tree-select/types.d.ts

@@ -1,202 +1,191 @@
 import type * as React from 'react';
 import type { TreeCheckedState } from '../tree/types.js';
+import type { PassThroughProps } from '../utils/passThrough.js';
 import type { PopperContentProps } from '../utils/popper.js';
 import type { PortalProps } from '../utils/portal.js';
 import type { PrimitivePropsWithRef } from '../utils/primitive.js';
 import type { InteractOutsideEvent } from '../utils/useDismiss.js';
 import type { TreeSelectFlatNode, TreeSelectIndex } from './collection.js';
 /**
- * One node of a {@link TreeSelect}'s `collection`. Plain data, not elements:
- * cascading check state, `valueStrategy` projection, and filtering all need to
- * see branches that are collapsed (and therefore unmounted), which a
- * children-based tree cannot offer.
+ * One node of a TreeSelect's collection — plain data, not elements, needed
+ * for cascading state, filtering, and projection across collapsed branches.
  */
 export interface TreeSelectNode {
-    /** Unique identifier across the whole collection — what lands in `value`, and what every callback names. */
+    /** Unique identifier across the whole collection; what lands in value and callback names. */
     value: string;
     /**
-     * Human-readable text: rendered as the node's content, matched by `filter`, and shown by `TreeSelectValue`.
+     * Human-readable text rendered as node content, matched by filter, shown by TreeSelectValue.
      * @default undefined — falls back to `value`.
      */
     label?: string;
     /**
-     * Excludes this node from checking, cascade propagation, keyboard
-     * navigation, and its parent's checked-ness calculation. Inherited by the
-     * whole subtree — a disabled branch cannot be toggled through its children.
+     * Excludes node from checking, cascade, navigation, and parent calculations;
+     * inherited by the whole subtree.
      * @default false
      */
     disabled?: boolean;
     /**
-     * Child nodes. A node with an empty (or absent) `children` is a leaf: it is
-     * not expandable and reports no `aria-expanded`.
+     * Child nodes. Empty or absent children makes this a leaf (not expandable).
      * @default undefined — a leaf.
      */
     children?: TreeSelectNode[];
+    /**
+     * Marks an unloaded branch as expandable before children arrive, giving
+     * loadChildren something to run on; ignored once the node has children.
+     * @default undefined — branch-ness decided by children alone.
+     */
+    hasChildren?: boolean;
 }
 /**
- * Whether checking a node propagates through its subtree. `'cascade'` makes
- * the tree a tri-state checkbox tree: checking a parent checks every enabled
- * descendant, and a partially-checked parent reports `aria-checked="mixed"`.
- * `'independent'` disables propagation entirely — each node stands alone.
- *
- * Only meaningful while `multiple` is set; a single-select tree has one
- * checked node by definition and never cascades.
+ * Propagation direction when checking a node: both ways, down only, up only, or none. Meaningful only when multiple is set.
  */
-export type TreeSelectCheckStrategy = 'cascade' | 'independent';
+export type TreeSelectCheckStrategy = 'cascade' | 'descendants' | 'ancestors' | 'independent';
 /**
- * Which of the checked nodes are actually emitted in `value`.
- *
- * - `'all'` — every checked node, parents and descendants alike.
- * - `'leaf'` — only checked leaves; branches are dropped.
- * - `'shallowest'` — only the topmost fully-checked node of each branch,
- *   collapsing a fully-checked subtree to the single node that implies it.
- *
- * Ignored (treated as `'all'`) under `checkStrategy="independent"`, where no
- * node implies any other and dropping one would silently lose a selection.
+ * Which checked nodes appear in value: all, leaves only, or the shallowest node of each fully-checked subtree. Ignored where projection cannot be undone.
  */
 export type TreeSelectValueStrategy = 'all' | 'leaf' | 'shallowest';
 /** Predicate deciding whether a node matches the current filter text. */
 export type TreeSelectFilter = (node: TreeSelectNode, inputValue: string) => boolean;
-/** @internal Shared state distributed from {@link TreeSelect} to its parts via context. Not part of the public API. */
+/** @internal Shared state distributed from TreeSelect to its parts via context. */
 export interface TreeSelectContextValue {
     collection: readonly TreeSelectNode[];
     index: TreeSelectIndex;
     /** Every node value in collection pre-order. */
     order: readonly string[];
-    /** The emitted value: the checked set projected through `valueStrategy`. */
+    /** The checked set projected through valueStrategy. */
     value: readonly string[];
     multiple: boolean;
-    /** Whether checking actually propagates: `checkStrategy === 'cascade'` *and* `multiple`. */
+    /** Whether checking propagates: checkStrategy is not independent and multiple is set. */
     cascade: boolean;
     disabled: boolean;
     readOnly: boolean;
-    /** A node's tri-state value, derived from its enabled leaf descendants under `cascade`. */
+    /** Node's tri-state value derived from enabled leaf descendants. */
     checkStateOf: (value: string) => TreeCheckedState;
-    /** Toggles a node (respecting `checkStrategy`), emits the projected value, and closes when `closeOnSelect`. */
+    /** Toggle node, emit projected value, close if closeOnSelect is set. */
     commit: (value: string) => void;
     open: boolean;
     onOpenChange: (open: boolean) => void;
-    /** Effective expanded ids — the caller's expansion plus, while filtering, the ancestors of every match. */
+    /** Caller's expansion plus, while filtering, ancestors of every match. */
     expandedIds: string[];
     expanded: ReadonlySet<string>;
     setExpanded: (value: string, expand: boolean) => void;
-    /** Adapter turning the composed `Tree`'s whole-array expansion callback back into a single-node change. */
+    /** Node values whose loadChildren call is still pending. */
+    loadingValues: ReadonlySet<string>;
+    /** Adapter for Tree's array expansion callback to single-node change. */
     onTreeExpandedIdsChange: (ids: string[]) => void;
-    /** Values whose check state is fully `true`, handed to the composed `Tree` as its `selectedIds`. */
-    selectedIds: string[];
-    /** Whether a node survives the current filter (always `true` when not filtering). */
+    /** Whether clicking a branch row toggles its expansion as well as checking. */
+    expandOnClick: boolean;
+    /** Whether a node survives the current filter (always true when not filtering). */
     isVisible: (value: string) => boolean;
     /** Visible, expanded nodes in navigation order. */
     flat: readonly TreeSelectFlatNode[];
     flatMap: ReadonlyMap<string, TreeSelectFlatNode>;
     activeValue: string | null;
     setActiveValue: (value: string | null) => void;
-    /** DOM id of a node's `treeitem`, for `aria-activedescendant`. */
+    /** DOM id of a node's treeitem for aria-activedescendant. */
     itemId: (value: string) => string;
     treeId: string;
-    contentId: string;
     triggerRef: React.RefObject<HTMLButtonElement | null>;
     contentRef: React.RefObject<HTMLDivElement | null>;
     inputRef: React.RefObject<HTMLInputElement | null>;
-    /** Whether a `TreeSelectInput` is mounted — it takes DOM focus, and with it `aria-activedescendant`, off the trigger. */
+    /** Whether TreeSelectInput is mounted; it takes focus and aria-activedescendant from trigger. */
     hasInput: boolean;
     setHasInput: (hasInput: boolean) => void;
     inputValue: string;
     onInputValueChange: (value: string) => void;
-    /** A node's `label`, or its `value` when it has none. */
+    /** Node's label or its value when label is absent. */
     getLabel: (value: string) => string;
-    /** The shared keydown handler both `TreeSelectTrigger` and `TreeSelectInput` delegate to. */
+    /** Shared keydown handler that both TreeSelectTrigger and TreeSelectInput delegate to. */
     onNavigationKeyDown: (event: React.KeyboardEvent<HTMLElement>, options: {
         typeahead: boolean;
         selectOnSpace: boolean;
     }) => void;
+    /**
+     * Node values `TreeSelectTree` actually renders when its `rows` prop windows
+     * the collection below what `flat` considers visible; `null` when unrestricted.
+     * Keyboard navigation and the initial active node are drawn from this set so
+     * `aria-activedescendant` never names a node with no rendered treeitem.
+     */
+    visibleRowValues: ReadonlySet<string> | null;
+    /** Reported by TreeSelectTree whenever its `rows` prop changes. */
+    setVisibleRowValues: (values: ReadonlySet<string> | null) => void;
 }
-/** @internal Per-node state distributed from {@link TreeSelectItem} to `TreeSelectItemIndicator` via context. Not part of the public API. */
+/** @internal Per-node state distributed from TreeSelectItem to TreeSelectItemIndicator via context. */
 export interface TreeSelectItemContextValue {
     value: string;
     checkState: TreeCheckedState;
     disabled: boolean;
     expanded: boolean;
     hasChildren: boolean;
-    /** Whether this node is the virtually-focused one named by `aria-activedescendant`. */
+    /** Whether this node is the virtually-focused one named by aria-activedescendant. */
     active: boolean;
 }
-/** Props for the {@link TreeSelect} root. */
-export interface TreeSelectProps {
+/**
+ * Props for the TreeSelect root. Standard attributes land on the derived
+ * TreeSelectTrigger. TreeSelect itself renders no DOM.
+ */
+export interface TreeSelectProps extends PassThroughProps {
     /**
-     * The `TreeSelectTrigger`/`TreeSelectPortal` parts, rendered as children — `TreeSelect` itself renders no DOM.
+     * The TreeSelectTrigger/TreeSelectPortal parts, rendered as children.
      * @default undefined — renders nothing without children.
      */
     children?: React.ReactNode;
     /**
-     * The hierarchical data the popup's tree is built from. Node `value`s must be
-     * unique across the whole collection — every callback, `value` entry and DOM
-     * id is keyed by them.
+     * Hierarchical data the tree is built from; node values must be unique across the whole collection.
      */
     collection: readonly TreeSelectNode[];
     /**
-     * Checked node values, for controlled usage — always an array, whether or not
-     * `multiple`, and always in the shape `valueStrategy` describes. Pair with
-     * `onValueChange`.
-     * @default undefined — uncontrolled, tracks its own checked set internally.
+     * Controlled checked node values, always in the shape valueStrategy describes. Pair with onValueChange.
+     * @default undefined — uncontrolled.
      */
     value?: string[];
     /**
-     * Initially checked node values, for uncontrolled usage. Same shape as `value`.
+     * Initially checked node values for uncontrolled usage.
      * @default [] — nothing checked.
      */
     defaultValue?: string[];
     /**
-     * Fires with the whole new value whenever the checked set changes, controlled
-     * or not — projected through `valueStrategy`, not the node that was toggled.
+     * Fires with the new value whenever the checked set changes, projected through valueStrategy.
      * @default undefined — no-op if omitted.
      */
     onValueChange?: (value: string[]) => void;
     /**
-     * Allows more than one node to be checked: the tree gets
-     * `aria-multiselectable`, activating a node toggles it rather than replacing
-     * the selection, and `checkStrategy` starts to mean something.
+     * Allows more than one node to be checked; tree gets aria-multiselectable and checkStrategy becomes meaningful.
      * @default false
      */
     multiple?: boolean;
     /**
-     * Whether checking a node propagates through its subtree — see
-     * {@link TreeSelectCheckStrategy}. Ignored unless `multiple`.
-     * @default 'cascade' — checking a parent checks its whole enabled subtree, and a partially-checked parent reports `aria-checked="mixed"`.
+     * Whether and in which direction checking propagates; see TreeSelectCheckStrategy. Ignored unless multiple.
+     * @default 'cascade'
      */
     checkStrategy?: TreeSelectCheckStrategy;
     /**
-     * Which checked nodes appear in the emitted `value` — see
-     * {@link TreeSelectValueStrategy}. Ignored under
-     * `checkStrategy="independent"`.
-     * @default 'all' — every checked node, which is the most faithful round-trip but the most verbose payload; `'shallowest'` is usually what an API wants.
+     * Which checked nodes appear in the emitted value; see TreeSelectValueStrategy. Ignored where checkStrategy lacks the direction to rebuild.
+     * @default 'all'
      */
     valueStrategy?: TreeSelectValueStrategy;
     /**
-     * Expanded node values, for controlled usage. Pair with `onExpandedChange`.
-     * While filtering, the ancestors of every match are expanded *on top of* this
-     * value without being written back to it.
-     * @default undefined — uncontrolled, tracks its own expanded set internally.
+     * Controlled expanded node ids, paired with onExpandedChange; while filtering, ancestors of every match are expanded on top of this value.
+     * @default undefined — uncontrolled.
      */
-    expandedValue?: string[];
+    expandedIds?: string[];
     /**
-     * Initially expanded node values, for uncontrolled usage.
+     * Initially expanded node values for uncontrolled usage.
      * @default [] — every branch collapsed.
      */
-    defaultExpandedValue?: string[];
+    defaultExpandedIds?: string[];
     /**
-     * Fires with the new expanded set whenever a branch is expanded or collapsed,
-     * controlled or not. Never fires for the transient expansion filtering adds.
+     * Fires with the new expanded set whenever a branch expands or collapses, never for filter-driven expansion.
      * @default undefined — no-op if omitted.
      */
-    onExpandedChange?: (expandedValue: string[]) => void;
+    onExpandedChange?: (expandedIds: string[]) => void;
     /**
-     * Whether the popup is open, for controlled usage. Pair with `onOpenChange`.
+     * Whether the popup is open for controlled usage. Pair with onOpenChange.
      * @default undefined — uncontrolled, tracks its own open state internally.
      */
     open?: boolean;
     /**
-     * Initial open state, for uncontrolled usage.
+     * Initial open state for uncontrolled usage.
      * @default false
      */
     defaultOpen?: boolean;
@@ -206,20 +195,17 @@ export interface TreeSelectProps {
      */
     onOpenChange?: (open: boolean) => void;
     /**
-     * Fires with the new open state once the change has finished on screen —
-     * after `TreeSelectContent`'s enter or exit animation ends, or as soon as it
-     * has settled when the popup declares no animation. Use it for work that must
-     * not race the transition; use `onOpenChange` for work that must not wait for it.
+     * Fires once the open state change finishes on screen, after animation ends or immediately if none.
      * @default undefined — no-op if omitted.
      */
     onOpenChangeComplete?: (open: boolean) => void;
     /**
-     * The `TreeSelectInput`'s filter text, for controlled usage. Pair with `onInputValueChange`.
+     * The TreeSelectInput's filter text for controlled usage. Pair with onInputValueChange.
      * @default undefined — uncontrolled, tracks its own filter text internally.
      */
     inputValue?: string;
     /**
-     * Initial filter text, for uncontrolled usage.
+     * Initial filter text for uncontrolled usage.
      * @default '' — unfiltered.
      */
     defaultInputValue?: string;
@@ -229,132 +215,159 @@ export interface TreeSelectProps {
      */
     onInputValueChange?: (inputValue: string) => void;
     /**
-     * Decides whether a node matches the filter text. A match keeps its whole
-     * ancestor chain visible (a matched leaf under a hidden parent would be
-     * unreachable) and its whole subtree visible.
-     * @default defaultTreeSelectFilter — case-insensitive substring match on `label ?? value`.
+     * Decides whether a node matches the filter; matches keep their ancestor chain and subtree visible.
+     * @default defaultTreeSelectFilter
      */
     filter?: TreeSelectFilter;
     /**
-     * Blocks the whole control: the trigger is a disabled `<button>`, the popup
-     * cannot open, and no key changes anything.
+     * Blocks the whole control; trigger is disabled and no key changes anything.
      * @default false
      */
     disabled?: boolean;
     /**
-     * Lets the user open, navigate and read the tree but never change the value —
-     * unlike `disabled`, which also removes it from the tab order.
+     * Form field name; each selected node value submits separately under this name.
+     * @default undefined — submits nothing.
+     */
+    name?: string;
+    /**
+     * Id of the form the submitted entries belong to, for a TreeSelect not a DOM descendant of it.
+     * @default undefined — entries belong to the nearest ancestor form.
+     */
+    form?: string;
+    /**
+     * Lets the user open and navigate the tree without changing the value, unlike disabled which also removes from the tab order.
      * @default false
      */
     readOnly?: boolean;
     /**
-     * Closes the popup as soon as a node is checked, returning focus to the trigger.
-     * @default !multiple — a single-select answer is complete on the first pick; a multi-select one is not.
+     * Closes the popup as soon as a node is checked, returning focus to trigger.
+     * @default !multiple
      */
     closeOnSelect?: boolean;
     /**
-     * Formats the message announced (through the shared `LiveAnnouncer`) each
-     * time the number of filter matches changes while the popup is open —
-     * filtering is silent for screen-reader users otherwise. Return an empty
-     * string to announce nothing.
-     * @default defaultGetMatchCountLabel — e.g. `"3 matches available"`
+     * Loads a node's children the first time it expands, for non-materialized collection. Mark branches with hasChildren; does not run while filtering.
+     * @default undefined — collection is complete as given.
+     */
+    loadChildren?: (nodeValue: string) => void | Promise<void>;
+    /**
+     * Formats the announced message each time filter matches change while the popup is open.
+     * @default defaultGetMatchCountLabel
      */
     getMatchCountLabel?: (count: number) => string;
+    /**
+     * Supplies the label for a value whose node is not in collection, consulted by TreeSelectValue before the raw-value fallback.
+     * @default undefined — unknown value renders as itself.
+     */
+    getValueLabel?: (value: string) => string;
+    /**
+     * Whether clicking a branch row toggles its expansion as well as checking it; ArrowRight/ArrowLeft are unaffected either way.
+     * @default false
+     */
+    expandOnClick?: boolean;
+    /**
+     * Renders a node's content when deriving anatomy, forwarded to TreeSelectTree; ignored under full manual composition.
+     * @default undefined — renders each node's label ?? value as plain text.
+     */
+    renderNode?: (node: TreeSelectNode) => React.ReactNode;
+    /**
+     * Placeholder for the derived trigger while nothing is checked, read only while deriving anatomy.
+     * @default undefined
+     */
+    placeholder?: string;
+    /**
+     * Empty-state message shown when no node matches the filter; only read while deriving anatomy.
+     * @default 'No matches'
+     */
+    emptyMessage?: string;
+    /**
+     * Accessible name for derived components; only read while deriving anatomy. Falls back to placeholder.
+     * @default undefined — if neither is set, no attribute is emitted.
+     */
+    'aria-label'?: string;
 }
 /** Props for {@link TreeSelectTrigger}, the `role="combobox"` button that opens the popup. */
 export interface TreeSelectTriggerProps extends PrimitivePropsWithRef<'button'> {
 }
-/** Props for {@link TreeSelectValue}, the trigger's read-out of the current selection. */
+/** Props for TreeSelectValue, the trigger's read-out of the current selection. */
 export interface TreeSelectValueProps extends PrimitivePropsWithRef<'span'> {
     /**
-     * Stand-in content rendered while nothing at all is checked.
-     * @default undefined — renders nothing when empty.
+     * Stand-in content rendered while nothing is checked.
+     * @default undefined
      */
     placeholder?: React.ReactNode;
 }
-/** Props for {@link TreeSelectPortal}, which teleports the popup to `document.body` while open. */
+/** Props for TreeSelectPortal, which teleports the popup to document.body while open. */
 export interface TreeSelectPortalProps extends PortalProps {
     /**
-     * Render (and mount `TreeSelectContent`) even while closed, instead of
-     * unmounting. Useful for animation libraries that need the outgoing content
-     * present in the DOM during an exit transition.
+     * Renders and mounts TreeSelectContent even while closed, for animation libraries needing the outgoing content during exit.
      * @default false
      */
     forceMount?: boolean;
 }
 /**
- * Props for {@link TreeSelectContent}, the popup panel. Extends
- * {@link PopperContentProps} (`side`, `align`, `sideOffset`, `alignOffset`,
- * `avoidCollisions`, `collisionPadding`) for floating-ui positioning relative
- * to the trigger — note `TreeSelectContent` defaults `side` to `'bottom'`,
- * `align` to `'start'`, and `sideOffset` to `4`, instead of the popper base
- * defaults (`'bottom'` / `'center'` / `0`).
+ * Props for TreeSelectContent, the popup panel; extends PopperContentProps (side, align, sideOffset, alignOffset, avoidCollisions, collisionPadding).
  */
 export interface TreeSelectContentProps extends PopperContentProps {
     /**
-     * Keep this popup mounted even while closed, instead of unmounting it.
+     * Mounts this popup even while closed, instead of unmounting it.
      * @default false
      */
     forceMount?: boolean;
     /**
-     * Fires on Escape while the popup is open, before it closes. Call
-     * `event.preventDefault()` to keep it open.
+     * Fires on Escape while the popup is open, before it closes; call preventDefault() to keep it open.
      * @default undefined — no-op if omitted.
      */
     onEscapeKeyDown?: (event: KeyboardEvent) => void;
     /**
-     * Fires on a pointer-down outside the popup and trigger. `preventDefault()` keeps it open.
+     * Fires on a pointer-down outside the popup and trigger; call preventDefault() to keep it open.
      * @default undefined — no-op if omitted.
      */
     onPointerDownOutside?: (event: PointerEvent) => void;
     /**
-     * Fires when focus moves outside the popup and trigger, carrying a
-     * cancelable stand-in for the uncancelable `focusin`. `preventDefault()`
-     * keeps it open.
+     * Fires when focus moves outside the popup and trigger; call preventDefault() to keep open.
      * @default undefined — no-op if omitted.
      */
     onFocusOutside?: (event: CustomEvent<FocusEvent>) => void;
     /**
-     * Fires for *either* kind of outside interaction, immediately before the
-     * specific handler and with the same event — so one `preventDefault()`
-     * vetoes both paths.
+     * Fires for either kind of outside interaction, before the specific handler with the same event.
      * @default undefined — no-op if omitted.
      */
     onInteractOutside?: (event: InteractOutsideEvent) => void;
 }
-/** Props for {@link TreeSelectTree}, the `role="tree"` inside the popup. */
+/** Props for TreeSelectTree, the role="tree" inside the popup. */
 export interface TreeSelectTreeProps extends Omit<PrimitivePropsWithRef<'div'>, 'children' | 'defaultValue'> {
     /**
-     * Renders a node's content — the label, and anything beside it such as a
-     * `TreeItemIndicator` chevron or a `TreeSelectItemIndicator` checkmark. The
-     * returned nodes render *inside* the node's `treeitem`, so both indicators
-     * find their context there.
-     * @default undefined — renders the node's `label ?? value` as plain text.
+     * Renders a node's content (label, indicators); returned nodes render inside the node's treeitem.
+     * @default undefined — renders the node's label ?? value as plain text.
      */
     renderLabel?: (node: TreeSelectNode) => React.ReactNode;
+    /**
+     * Renders exactly this row set instead of the whole collection; rows render flat as { value, depth } pairs with row.depth supplying aria-level.
+     * @default undefined — renders every visible node from collection, nested.
+     */
+    rows?: readonly Pick<TreeSelectFlatNode, 'value' | 'depth'>[];
 }
-/** Props for a single {@link TreeSelectItem} node. Normally rendered for you by `TreeSelectTree`. */
+/** Props for a single TreeSelectItem node. Normally rendered by TreeSelectTree. */
 export interface TreeSelectItemProps extends Omit<PrimitivePropsWithRef<'div'>, 'children'> {
     /** The collection node this row stands for. */
     node: TreeSelectNode;
     /**
      * The row's content — the label, plus any indicators.
-     * @default undefined — renders an empty row.
+     * @default undefined
      */
     children?: React.ReactNode;
 }
-/** Props for {@link TreeSelectItemIndicator}, the checkmark shown on a checked (or partially checked) node. */
+/** Props for TreeSelectItemIndicator, the checkmark shown on checked or partially-checked nodes. */
 export interface TreeSelectItemIndicatorProps extends PrimitivePropsWithRef<'span'> {
     /**
-     * Render even while the node is unchecked, instead of returning `null` —
-     * for animating the check in and out, or for reserving its space.
+     * Renders even while the node is unchecked, for animating the check or reserving its space.
      * @default false
      */
     forceMount?: boolean;
 }
-/** Props for {@link TreeSelectEmpty}, shown in place of the tree when the filter matches nothing. */
+/** Props for TreeSelectEmpty, shown in place of the tree when the filter matches nothing. */
 export interface TreeSelectEmptyProps extends PrimitivePropsWithRef<'div'> {
 }
-/** Props for {@link TreeSelectInput}, the optional filter text field inside the popup. */
+/** Props for TreeSelectInput, the optional filter text field inside the popup. */
 export interface TreeSelectInputProps extends Omit<PrimitivePropsWithRef<'input'>, 'value' | 'defaultValue'> {
 }

package/dist/utils/cardNesting.cjs

@@ -0,0 +1 @@
+"use strict";var u=Object.create;var c=Object.defineProperty;var m=Object.getOwnPropertyDescriptor;var R=Object.getOwnPropertyNames;var h=Object.getPrototypeOf,p=Object.prototype.hasOwnProperty;var g=(e,t)=>{for(var n in t)c(e,n,{get:t[n],enumerable:!0})},l=(e,t,n,r)=>{if(t&&typeof t=="object"||typeof t=="function")for(let o of R(t))!p.call(e,o)&&o!==n&&c(e,o,{get:()=>t[o],enumerable:!(r=m(t,o))||r.enumerable});return e};var C=(e,t,n)=>(n=e!=null?u(h(e)):{},l(t||!e||!e.__esModule?c(n,"default",{value:e,enumerable:!0}):n,e)),E=e=>l(c({},"__esModule",{value:!0}),e);var L={};g(L,{useCardNestingWarning:()=>T});module.exports=E(L);var i=C(require("react"),1),d=require("./is-dev-mode.cjs"),f=require("./tabbable.cjs"),b='input[type="checkbox"], input[type="radio"]';function T(e,t){let n=i.useRef("");i.useEffect(()=>{let r=t.current;if(!r)return;let o=Array.from(r.querySelectorAll(f.TABBABLE_SELECTOR)).filter(a=>!a.matches(b)),s=o.map(a=>a.localName).join(",");s!==n.current&&(n.current=s,o.length!==0&&(0,d.isDevMode)()&&console.warn(`[skdx] ${e}: found ${o.length} focusable element(s) nested inside the card \u2014 ${o.map(a=>`<${a.localName}>`).join(", ")}. The card root is a <label>, so clicking one of these also toggles the card, and a <label> may not contain interactive content. Put actions beside the card, never inside it.`))})}0&&(module.exports={useCardNestingWarning});

package/dist/utils/cardNesting.d.cts

@@ -0,0 +1,25 @@
+import * as React from 'react';
+/**
+ * Warns when a card root contains a focusable descendant that is not its own
+ * Control.
+ *
+ * Both card families document the rule — "nothing interactive may be nested
+ * inside the card" — and until this existed nothing enforced it: no runtime
+ * check, no lint rule, no assertion. It is not a style preference. The root is
+ * a `<label>`, so a nested `<a>` or `<button>` is an HTML content-model
+ * violation *and* a live usability bug: clicking the inner control activates
+ * the label too, so a "Learn more" link inside a card silently toggles the
+ * card on the way to the link. That is exactly the thing the first consumer who
+ * wants a link on a card will build, and the failure is invisible in review.
+ *
+ * A warning rather than a thrown error: the page still works, badly, and
+ * breaking a consumer's render over a composition mistake is a worse trade than
+ * telling them about it. Runs from an effect, so it sees the *rendered*
+ * subtree — which is the only place the answer lives, since the offending child
+ * may come from a consumer's own component.
+ *
+ * @param family the card family's name, so the message says which card is wrong
+ * @param rootRef the card root `<label>`
+ * @internal
+ */
+export declare function useCardNestingWarning(family: 'CheckboxCard' | 'RadioCard', rootRef: React.RefObject<HTMLElement | null>): void;

package/dist/utils/cardNesting.d.ts

@@ -0,0 +1,25 @@
+import * as React from 'react';
+/**
+ * Warns when a card root contains a focusable descendant that is not its own
+ * Control.
+ *
+ * Both card families document the rule — "nothing interactive may be nested
+ * inside the card" — and until this existed nothing enforced it: no runtime
+ * check, no lint rule, no assertion. It is not a style preference. The root is
+ * a `<label>`, so a nested `<a>` or `<button>` is an HTML content-model
+ * violation *and* a live usability bug: clicking the inner control activates
+ * the label too, so a "Learn more" link inside a card silently toggles the
+ * card on the way to the link. That is exactly the thing the first consumer who
+ * wants a link on a card will build, and the failure is invisible in review.
+ *
+ * A warning rather than a thrown error: the page still works, badly, and
+ * breaking a consumer's render over a composition mistake is a worse trade than
+ * telling them about it. Runs from an effect, so it sees the *rendered*
+ * subtree — which is the only place the answer lives, since the offending child
+ * may come from a consumer's own component.
+ *
+ * @param family the card family's name, so the message says which card is wrong
+ * @param rootRef the card root `<label>`
+ * @internal
+ */
+export declare function useCardNestingWarning(family: 'CheckboxCard' | 'RadioCard', rootRef: React.RefObject<HTMLElement | null>): void;

package/dist/utils/cardNesting.js

@@ -0,0 +1 @@
+import*as n from"react";import{isDevMode as s}from"./is-dev-mode.js";import{TABBABLE_SELECTOR as l}from"./tabbable.js";var d='input[type="checkbox"], input[type="radio"]';function m(c,i){let o=n.useRef("");n.useEffect(()=>{let r=i.current;if(!r)return;let t=Array.from(r.querySelectorAll(l)).filter(e=>!e.matches(d)),a=t.map(e=>e.localName).join(",");a!==o.current&&(o.current=a,t.length!==0&&s()&&console.warn(`[skdx] ${c}: found ${t.length} focusable element(s) nested inside the card \u2014 ${t.map(e=>`<${e.localName}>`).join(", ")}. The card root is a <label>, so clicking one of these also toggles the card, and a <label> may not contain interactive content. Put actions beside the card, never inside it.`))})}export{m as useCardNestingWarning};

package/dist/utils/createContext.cjs

@@ -1 +1 @@
-"use strict";var l=Object.create;var i=Object.defineProperty;var C=Object.getOwnPropertyDescriptor;var R=Object.getOwnPropertyNames;var h=Object.getPrototypeOf,g=Object.prototype.hasOwnProperty;var v=(e,t)=>{for(var n in t)i(e,n,{get:t[n],enumerable:!0})},x=(e,t,n,r)=>{if(t&&typeof t=="object"||typeof t=="function")for(let o of R(t))!g.call(e,o)&&o!==n&&i(e,o,{get:()=>t[o],enumerable:!(r=C(t,o))||r.enumerable});return e};var w=(e,t,n)=>(n=e!=null?l(h(e)):{},x(t||!e||!e.__esModule?i(n,"default",{value:e,enumerable:!0}):n,e)),b=e=>x(i({},"__esModule",{value:!0}),e);var P={};v(P,{createSafeContext:()=>k});module.exports=b(P);var c=w(require("react"),1),f=require("react/jsx-runtime");function j(e,t){let n=Object.keys(e);return n.length!==Object.keys(t).length?!1:n.every(r=>r in t&&Object.is(e[r],t[r]))}function k(e,t){let n=c.createContext(t);function r(u){let{children:s,...a}=u,d=c.useRef(a);return j(d.current,a)||(d.current=a),(0,f.jsx)(n.Provider,{value:d.current,children:s})}r.displayName=`${e}Provider`;function o(u){let s=c.useContext(n);if(s!==void 0)return s;if(t!==void 0)return t;throw new Error(`[skandadx] \`${u}\` must be used within \`${e}\`.`)}return[r,o]}0&&(module.exports={createSafeContext});
+"use strict";var C=Object.create;var i=Object.defineProperty;var R=Object.getOwnPropertyDescriptor;var h=Object.getOwnPropertyNames;var g=Object.getPrototypeOf,v=Object.prototype.hasOwnProperty;var w=(e,t)=>{for(var n in t)i(e,n,{get:t[n],enumerable:!0})},x=(e,t,n,r)=>{if(t&&typeof t=="object"||typeof t=="function")for(let o of h(t))!v.call(e,o)&&o!==n&&i(e,o,{get:()=>t[o],enumerable:!(r=R(t,o))||r.enumerable});return e};var b=(e,t,n)=>(n=e!=null?C(g(e)):{},x(t||!e||!e.__esModule?i(n,"default",{value:e,enumerable:!0}):n,e)),j=e=>x(i({},"__esModule",{value:!0}),e);var P={};w(P,{createSafeContext:()=>O});module.exports=j(P);var c=b(require("react"),1),f=require("react/jsx-runtime");function k(e,t){let n=Object.keys(e);return n.length!==Object.keys(t).length?!1:n.every(r=>r in t&&Object.is(e[r],t[r]))}function O(e,t){let n=c.createContext(t);function r(u){let{children:s,...a}=u,d=c.useRef(a);return k(d.current,a)||(d.current=a),(0,f.jsx)(n.Provider,{value:d.current,children:s})}r.displayName=`${e}Provider`;function o(u){let s=c.useContext(n);if(s!==void 0)return s;if(t!==void 0)return t;throw new Error(`[skandadx] \`${u}\` must be used within \`${e}\`.`)}function l(){return c.useContext(n)??t}return[r,o,l]}0&&(module.exports={createSafeContext});

package/dist/utils/createContext.d.cts

@@ -8,7 +8,7 @@ import * as React from 'react';
  *
  * @param rootComponentName - Name of the root component, used in the Provider's `displayName` and in error messages.
  * @param defaultValue - Optional fallback so the context also works without a Provider (rare; most compound components require one).
- * @returns A `[Provider, useContext]` tuple. `useContext` takes the *consuming* part's name so its error message names the right component.
+ * @returns A `[Provider, useContext, useOptionalContext]` tuple. `useContext` takes the *consuming* part's name so its error message names the right component; `useOptionalContext` returns `undefined` instead of throwing, for the rare part whose root is optional.
  *
  * @example
  * ```tsx
@@ -26,4 +26,4 @@ export declare function createSafeContext<ContextValue extends object | null>(ro
         children: React.ReactNode;
     }): React.JSX.Element;
     displayName: string;
-}, (consumerName: string) => ContextValue];
+}, (consumerName: string) => ContextValue, () => ContextValue | undefined];

package/dist/utils/createContext.d.ts

@@ -8,7 +8,7 @@ import * as React from 'react';
  *
  * @param rootComponentName - Name of the root component, used in the Provider's `displayName` and in error messages.
  * @param defaultValue - Optional fallback so the context also works without a Provider (rare; most compound components require one).
- * @returns A `[Provider, useContext]` tuple. `useContext` takes the *consuming* part's name so its error message names the right component.
+ * @returns A `[Provider, useContext, useOptionalContext]` tuple. `useContext` takes the *consuming* part's name so its error message names the right component; `useOptionalContext` returns `undefined` instead of throwing, for the rare part whose root is optional.
  *
  * @example
  * ```tsx
@@ -26,4 +26,4 @@ export declare function createSafeContext<ContextValue extends object | null>(ro
         children: React.ReactNode;
     }): React.JSX.Element;
     displayName: string;
-}, (consumerName: string) => ContextValue];
+}, (consumerName: string) => ContextValue, () => ContextValue | undefined];

package/dist/utils/createContext.js

@@ -1 +1 @@
-import*as n from"react";import{jsx as x}from"react/jsx-runtime";function d(r,e){let o=Object.keys(r);return o.length!==Object.keys(e).length?!1:o.every(t=>t in e&&Object.is(r[t],e[t]))}function f(r,e){let o=n.createContext(e);function t(s){let{children:c,...i}=s,u=n.useRef(i);return d(u.current,i)||(u.current=i),x(o.Provider,{value:u.current,children:c})}t.displayName=`${r}Provider`;function a(s){let c=n.useContext(o);if(c!==void 0)return c;if(e!==void 0)return e;throw new Error(`[skandadx] \`${s}\` must be used within \`${r}\`.`)}return[t,a]}export{f as createSafeContext};
+import*as t from"react";import{jsx as f}from"react/jsx-runtime";function x(o,e){let n=Object.keys(o);return n.length!==Object.keys(e).length?!1:n.every(r=>r in e&&Object.is(o[r],e[r]))}function l(o,e){let n=t.createContext(e);function r(s){let{children:c,...i}=s,u=t.useRef(i);return x(u.current,i)||(u.current=i),f(n.Provider,{value:u.current,children:c})}r.displayName=`${o}Provider`;function a(s){let c=t.useContext(n);if(c!==void 0)return c;if(e!==void 0)return e;throw new Error(`[skandadx] \`${s}\` must be used within \`${o}\`.`)}function d(){return t.useContext(n)??e}return[r,a,d]}export{l as createSafeContext};