@askrjs/askr 0.0.21 → 0.0.24

package/dist/foundations/interactions/dismissable.d.ts

@@ -0,0 +1,58 @@
+/**
+ * dismissable
+ *
+ * THE dismissal primitive. Handles Escape key and outside interactions.
+ *
+ * INVARIANTS:
+ * 1. Returns props that compose via mergeProps (no factories)
+ * 2. Disabled state respected exactly once, here
+ * 3. No side effects - pure props generation
+ * 4. Outside detection requires explicit node reference
+ * 5. This is the ONLY dismissal primitive - do not create alternatives
+ *
+ * DESIGN:
+ * - Returns standard event handler props (onKeyDown, onPointerDownCapture)
+ * - Composable via mergeProps with other foundations
+ * - Caller provides node reference for outside detection
+ * - Single onDismiss callback for all dismiss triggers
+ *
+ * PIT OF SUCCESS:
+ * ✓ Can't accidentally bypass (only way to get dismiss behavior)
+ * ✓ Can't duplicate (disabled checked once)
+ * ✓ Composes via mergeProps (standard props)
+ * ✓ Wrong usage is hard (no factories to misuse)
+ *
+ * USAGE:
+ *   const props = dismissable({
+ *     node: elementRef,
+ *     disabled: false,
+ *     onDismiss: () => close()
+ *   });
+ *
+ *   <div ref={elementRef} {...props}>Content</div>
+ *
+ * MISUSE EXAMPLE (PREVENTED):
+ *   ❌ Can't forget to check disabled - checked inside dismissable
+ *   ❌ Can't create custom escape handler - this is the only one
+ *   ❌ Can't bypass via direct event listeners - mergeProps composes correctly
+ */
+export interface DismissableOptions {
+    /**
+     * Reference to the element for outside click detection
+     */
+    node?: Node | null;
+    /**
+     * Whether dismiss is disabled
+     */
+    disabled?: boolean;
+    /**
+     * Called when dismiss is triggered (Escape or outside click)
+     */
+    onDismiss?: (trigger: 'escape' | 'outside') => void;
+}
+import type { KeyboardLikeEvent, PointerLikeEvent } from '../utilities/event-types';
+export declare function dismissable({ node, disabled, onDismiss }: DismissableOptions): {
+    onKeyDown: (e: KeyboardLikeEvent) => void;
+    onPointerDownCapture: (e: PointerLikeEvent) => void;
+};
+//# sourceMappingURL=dismissable.d.ts.map

package/dist/foundations/interactions/dismissable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dismissable.d.ts","sourceRoot":"","sources":["../../../src/foundations/interactions/dismissable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IAEnB;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;OAEG;IACH,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,QAAQ,GAAG,SAAS,KAAK,IAAI,CAAC;CACrD;AAED,OAAO,KAAK,EACV,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,0BAA0B,CAAC;AAElC,wBAAgB,WAAW,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,EAAE,kBAAkB;mBACjD,iBAAiB;8BASN,gBAAgB;EAoBtD"}

package/dist/foundations/interactions/dismissable.js

@@ -0,0 +1 @@
+function u({node:t,disabled:e,onDismiss:r}){function i(n){e||n.key==="Escape"&&(n.preventDefault?.(),n.stopPropagation?.(),r?.("escape"))}function a(n){if(e)return;const o=n.target;o instanceof Node&&t&&(t.contains(o)||r?.("outside"))}return{onKeyDown:i,onPointerDownCapture:a}}export{u as dismissable};

package/dist/foundations/interactions/focusable.d.ts

@@ -0,0 +1,16 @@
+/**
+ * focusable
+ *
+ * Normalize focus-related props for hosts.
+ * - No DOM manipulation here; returns props that the runtime may attach.
+ */
+export interface FocusableOptions {
+    disabled?: boolean;
+    tabIndex?: number | undefined;
+}
+export interface FocusableResult {
+    tabIndex?: number;
+    'aria-disabled'?: 'true';
+}
+export declare function focusable({ disabled, tabIndex, }: FocusableOptions): FocusableResult;
+//# sourceMappingURL=focusable.d.ts.map

package/dist/foundations/interactions/focusable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"focusable.d.ts","sourceRoot":"","sources":["../../../src/foundations/interactions/focusable.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAgB,SAAS,CAAC,EACxB,QAAQ,EACR,QAAQ,GACT,EAAE,gBAAgB,GAAG,eAAe,CAKpC"}

package/dist/foundations/interactions/focusable.js

@@ -0,0 +1 @@
+import{ariaDisabled as i}from"../utilities/aria.js";function a({disabled:o,tabIndex:r}){return{tabIndex:o?-1:r===void 0?0:r,...i(o)}}export{a as focusable};

package/dist/foundations/interactions/hoverable.d.ts

@@ -0,0 +1,19 @@
+/**
+ * hoverable
+ *
+ * Produces props for pointer enter/leave handling. Pure and deterministic.
+ */
+export interface HoverableOptions {
+    disabled?: boolean;
+    onEnter?: (e: HoverEvent) => void;
+    onLeave?: (e: HoverEvent) => void;
+}
+import type { DefaultPreventable, PropagationStoppable } from '../utilities/event-types';
+type HoverEvent = DefaultPreventable & PropagationStoppable;
+export interface HoverableResult {
+    onPointerEnter?: (e: HoverEvent) => void;
+    onPointerLeave?: (e: HoverEvent) => void;
+}
+export declare function hoverable({ disabled, onEnter, onLeave, }: HoverableOptions): HoverableResult;
+export {};
+//# sourceMappingURL=hoverable.d.ts.map

package/dist/foundations/interactions/hoverable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hoverable.d.ts","sourceRoot":"","sources":["../../../src/foundations/interactions/hoverable.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,UAAU,KAAK,IAAI,CAAC;IAClC,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,UAAU,KAAK,IAAI,CAAC;CACnC;AAED,OAAO,KAAK,EACV,kBAAkB,EAClB,oBAAoB,EACrB,MAAM,0BAA0B,CAAC;AAElC,KAAK,UAAU,GAAG,kBAAkB,GAAG,oBAAoB,CAAC;AAE5D,MAAM,WAAW,eAAe;IAC9B,cAAc,CAAC,EAAE,CAAC,CAAC,EAAE,UAAU,KAAK,IAAI,CAAC;IACzC,cAAc,CAAC,EAAE,CAAC,CAAC,EAAE,UAAU,KAAK,IAAI,CAAC;CAC1C;AAED,wBAAgB,SAAS,CAAC,EACxB,QAAQ,EACR,OAAO,EACP,OAAO,GACR,EAAE,gBAAgB,GAAG,eAAe,CAapC"}

package/dist/foundations/interactions/hoverable.js

@@ -0,0 +1 @@
+function t({disabled:e,onEnter:n,onLeave:r}){return{onPointerEnter:e?void 0:o=>{n?.(o)},onPointerLeave:e?void 0:o=>{r?.(o)}}}export{t as hoverable};

package/dist/foundations/interactions/index.d.ts

@@ -0,0 +1,5 @@
+export * from './pressable';
+export * from './focusable';
+export * from './hoverable';
+export * from './dismissable';
+//# sourceMappingURL=index.d.ts.map

package/dist/foundations/interactions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/foundations/interactions/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC"}

package/dist/foundations/interactions/interaction-policy.d.ts

@@ -0,0 +1,96 @@
+/**
+ * INTERACTION POLICY (FRAMEWORK LAW)
+ *
+ * This is THE ONLY way to create interactive elements. Components MUST NOT
+ * implement interaction logic directly.
+ *
+ * INVARIANTS (ENFORCED):
+ * 1. "Press" is the semantic. Click/touch/Enter/Space are implementation details.
+ * 2. Disabled is enforced exactly once, here. Components may not check disabled.
+ * 3. Keyboard handling is automatic. Components may not add onKeyDown for activation.
+ * 4. Native elements opt out of polyfills, not semantics.
+ * 5. asChild may replace the host element, not interaction behavior.
+ * 6. This policy is the SINGLE SOURCE OF TRUTH for interactive behavior.
+ *
+ * DESIGN:
+ * - Single public function: applyInteractionPolicy
+ * - Returns props that compose via mergeProps
+ * - Delegates to pressable for mechanics
+ * - Enforces disabled once and only once
+ * - No configuration beyond disabled and native element type
+ *
+ * PIT OF SUCCESS:
+ * ✓ Can't bypass policy (only way to get interaction behavior)
+ * ✓ Can't duplicate disabled checks (enforced once, here)
+ * ✓ Can't write custom keyboard handlers for buttons (policy owns it)
+ * ✓ Composes via mergeProps (standard props)
+ * ✓ Wrong usage is impossible (no escape hatch)
+ *
+ * USAGE:
+ *   function Button({ onPress, disabled }) {
+ *     const interaction = applyInteractionPolicy({
+ *       isNative: true,
+ *       disabled,
+ *       onPress
+ *     });
+ *
+ *     return <button {...interaction}>Click me</button>;
+ *   }
+ *
+ * MISUSE EXAMPLE (PREVENTED):
+ *   ❌ Button checking disabled again:
+ *      function Button({ disabled, onPress }) {
+ *        if (disabled) return; // NO! Policy handles this
+ *        const interaction = applyInteractionPolicy(...);
+ *      }
+ *
+ *   ❌ Custom keyboard handler:
+ *      function Button({ onPress }) {
+ *        const interaction = applyInteractionPolicy(...);
+ *        return <button {...interaction} onKeyDown={...}>; // NO! Policy owns this
+ *      }
+ *
+ *   ❌ Direct event handler:
+ *      <button onClick={onPress}>; // NO! Use applyInteractionPolicy
+ */
+import { Ref } from '../utilities/compose-ref';
+export interface InteractionPolicyInput {
+    /** Whether the host element is a native interactive element (button, a, etc) */
+    isNative: boolean;
+    /** Disabled state - checked ONLY here, never in components */
+    disabled: boolean;
+    /** User-provided press handler - semantic action, not DOM event */
+    onPress?: (e: Event) => void;
+    /** Optional ref to compose */
+    ref?: Ref<unknown>;
+}
+/**
+ * THE interaction policy. Components MUST use this, NEVER implement
+ * interaction logic directly.
+ */
+export declare function applyInteractionPolicy({ isNative, disabled, onPress, ref, }: InteractionPolicyInput): {
+    disabled: true | undefined;
+    onClick: (e: Event) => void;
+    ref: Ref<unknown>;
+} | {
+    'aria-disabled': true | undefined;
+    tabIndex: number;
+    ref: Ref<unknown>;
+    onClick: (e: import("../utilities").DefaultPreventable & import("../utilities").PropagationStoppable) => void;
+    disabled?: true;
+    role?: "button";
+    onKeyDown?: (e: import("../utilities").KeyboardLikeEvent) => void;
+    onKeyUp?: (e: import("../utilities").KeyboardLikeEvent) => void;
+};
+/**
+ * Merge rule for Slot / asChild
+ *
+ * Precedence:
+ *   policy → user → child
+ *
+ * Event handlers are composed (policy first).
+ * Refs are always composed.
+ * Policy props MUST take precedence to enforce invariants.
+ */
+export declare function mergeInteractionProps(childProps: Record<string, unknown>, policyProps: Record<string, unknown>, userProps?: Record<string, unknown>): Record<string, unknown>;
+//# sourceMappingURL=interaction-policy.d.ts.map

package/dist/foundations/interactions/interaction-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interaction-policy.d.ts","sourceRoot":"","sources":["../../../src/foundations/interactions/interaction-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAIH,OAAO,EAAe,GAAG,EAAE,MAAM,0BAA0B,CAAC;AAG5D,MAAM,WAAW,sBAAsB;IACrC,gFAAgF;IAChF,QAAQ,EAAE,OAAO,CAAC;IAClB,8DAA8D;IAC9D,QAAQ,EAAE,OAAO,CAAC;IAClB,mEAAmE;IACnE,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,KAAK,IAAI,CAAC;IAC7B,8BAA8B;IAC9B,GAAG,CAAC,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,EACrC,QAAQ,EACR,QAAQ,EACR,OAAO,EACP,GAAG,GACJ,EAAE,sBAAsB;;iBAcN,KAAK;;;;;;;;;;;EAkBvB;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,2BAiCpC"}

package/dist/foundations/interactions/interaction-policy.js

@@ -0,0 +1 @@
+import{pressable as v}from"./pressable.js";import{composeHandlers as p}from"../utilities/compose-handlers.js";import{composeRefs as H}from"../utilities/compose-ref.js";import{mergeProps as d}from"../utilities/merge-props.js";function y({isNative:r,disabled:n,onPress:e,ref:t}){function f(o){if(n){o.preventDefault?.();return}e?.(o)}if(r)return{disabled:n||void 0,onClick:o=>f(o),ref:t};const c=v({disabled:n,isNativeButton:!1,onPress:o=>f(o)});return{...c,"aria-disabled":n||void 0,tabIndex:n?-1:c.tabIndex??0,ref:t}}function g(r,n,e){let t=d(r,n);e&&(t=d(t,e));for(const i in t){if(!i.startsWith("on"))continue;const s=n?.[i],m=e?.[i],u=r?.[i];if(s||m||u){const a=l=>typeof l=="function"?l:void 0;t[i]=p(a(s),p(a(m),a(u)))}}const f=r?.ref,c=e?.ref,o=n?.ref;return t.ref=H(f,c,o),t}export{y as applyInteractionPolicy,g as mergeInteractionProps};

package/dist/foundations/interactions/pressable.d.ts

@@ -0,0 +1,54 @@
+/**
+ * pressable
+ *
+ * Interaction helper that produces VNode props for 'press' semantics.
+ * - Pure and deterministic: no DOM construction or mutation here
+ * - The runtime owns event attachment and scheduling
+ * - This helper returns plain props (handlers) intended to be attached by the runtime
+ *
+ * Behaviour:
+ * - For native buttons: only an `onClick` prop is provided (no ARIA or keyboard shims)
+ * - For non-button elements: add `role="button"` and `tabIndex` and keyboard handlers
+ * - Activation: `Enter` activates on keydown, `Space` activates on keyup (matches native button)
+ * - Disabled: handlers short-circuit and `aria-disabled` is set for all hosts
+ *
+ * POLICY DECISIONS (LOCKED):
+ *
+ * 1. Activation Timing (Platform Parity)
+ *    - Enter fires on keydown (immediate response)
+ *    - Space fires on keyup (allows cancel by moving focus, matches native)
+ *    - Space keydown prevents scroll (matches native button behavior)
+ *
+ * 2. Disabled Enforcement Strategy
+ *    - Native buttons: Use HTML `disabled` attribute (platform-enforced non-interactivity)
+ *                     AND `aria-disabled` (consistent a11y signaling)
+ *    - Non-native: Use `tabIndex=-1` (removes from tab order)
+ *                  AND `aria-disabled` (signals disabled state to AT)
+ *    - Click handler short-circuits as defense-in-depth (prevents leaked focus issues)
+ *
+ * 3. Key Repeat Behavior
+ *    - Held Enter/Space will fire onPress repeatedly (matches native button)
+ *    - No debouncing or repeat prevention (platform parity)
+ */
+export interface PressableOptions {
+    disabled?: boolean;
+    onPress?: (e: PressEvent) => void;
+    /**
+     * Whether the host is a native button. Defaults to false.
+     */
+    isNativeButton?: boolean;
+}
+import type { DefaultPreventable, KeyboardLikeEvent, PropagationStoppable } from '../utilities/event-types';
+type PressEvent = DefaultPreventable & PropagationStoppable;
+export interface PressableResult {
+    onClick: (e: PressEvent) => void;
+    disabled?: true;
+    role?: 'button';
+    tabIndex?: number;
+    onKeyDown?: (e: KeyboardLikeEvent) => void;
+    onKeyUp?: (e: KeyboardLikeEvent) => void;
+    'aria-disabled'?: 'true';
+}
+export declare function pressable({ disabled, onPress, isNativeButton, }: PressableOptions): PressableResult;
+export {};
+//# sourceMappingURL=pressable.d.ts.map

package/dist/foundations/interactions/pressable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pressable.d.ts","sourceRoot":"","sources":["../../../src/foundations/interactions/pressable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,UAAU,KAAK,IAAI,CAAC;IAClC;;OAEG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,OAAO,KAAK,EACV,kBAAkB,EAClB,iBAAiB,EACjB,oBAAoB,EACrB,MAAM,0BAA0B,CAAC;AAGlC,KAAK,UAAU,GAAG,kBAAkB,GAAG,oBAAoB,CAAC;AAE5D,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,CAAC,CAAC,EAAE,UAAU,KAAK,IAAI,CAAC;IACjC,QAAQ,CAAC,EAAE,IAAI,CAAC;IAChB,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAC3C,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,iBAAiB,KAAK,IAAI,CAAC;IACzC,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAgB,SAAS,CAAC,EACxB,QAAQ,EACR,OAAO,EACP,cAAsB,GACvB,EAAE,gBAAgB,GAAG,eAAe,CAwDpC"}

package/dist/foundations/interactions/pressable.js

@@ -0,0 +1 @@
+import{ariaDisabled as o}from"../utilities/aria.js";function u({disabled:n,onPress:e,isNativeButton:f=!1}){const r={onClick:t=>{if(n){t.preventDefault?.(),t.stopPropagation?.();return}e?.(t)}};return f?(n&&(r.disabled=!0,Object.assign(r,o(n))),r):(r.role="button",r.tabIndex=n?-1:0,r.onKeyDown=t=>{if(n){t.preventDefault?.(),t.stopPropagation?.();return}if(t.key==="Enter"){t.preventDefault?.(),e?.(t);return}t.key===" "&&t.preventDefault?.()},r.onKeyUp=t=>{if(n){t.preventDefault?.(),t.stopPropagation?.();return}t.key===" "&&(t.preventDefault?.(),e?.(t))},n&&Object.assign(r,o(n)),r)}export{u as pressable};

package/dist/foundations/interactions/roving-focus.d.ts

@@ -0,0 +1,117 @@
+/**
+ * rovingFocus
+ *
+ * Single tab stop navigation with arrow-key control.
+ *
+ * INVARIANTS:
+ * 1. Only one item in the group is reachable via Tab (single tab stop)
+ * 2. Arrow keys move focus within the group
+ * 3. Orientation determines which arrow keys are active
+ * 4. Looping is opt-in
+ * 5. Disabled items are skipped
+ * 6. Returns props objects, never factories (composes via mergeProps)
+ *
+ * DESIGN:
+ * - Container gets onKeyDown for arrow navigation
+ * - Each item gets tabIndex based on current selection
+ * - Navigation logic is pure - caller controls focus application
+ * - Disabled check happens per-item via predicate
+ *
+ * PIT OF SUCCESS:
+ * ✓ Can't accidentally break tab order (tabIndex assigned correctly)
+ * ✓ Can't duplicate navigation logic (single source)
+ * ✓ Composes via mergeProps (all standard props)
+ * ✓ Type-safe - invalid indices caught at call site
+ *
+ * USAGE:
+ *   const nav = rovingFocus({
+ *     currentIndex: 0,
+ *     itemCount: 3,
+ *     orientation: 'horizontal',
+ *     onNavigate: setIndex
+ *   });
+ *
+ *   <div {...nav.container}>
+ *     <button {...nav.item(0)}>First</button>
+ *     <button {...nav.item(1)}>Second</button>
+ *   </div>
+ *
+ * MISUSE EXAMPLE (PREVENTED):
+ *   ❌ Can't forget to set tabIndex - returned in item props
+ *   ❌ Can't create conflicting arrow handlers - mergeProps composes
+ *   ❌ Can't skip disabled items incorrectly - logic is internal
+ */
+import type { KeyboardLikeEvent } from '../utilities/event-types';
+export type Orientation = 'horizontal' | 'vertical' | 'both';
+export interface RovingFocusOptions {
+    /**
+     * Current focused index
+     */
+    currentIndex: number;
+    /**
+     * Total number of items
+     */
+    itemCount: number;
+    /**
+     * Navigation orientation
+     * - horizontal: ArrowLeft/ArrowRight
+     * - vertical: ArrowUp/ArrowDown
+     * - both: all arrow keys
+     */
+    orientation?: Orientation;
+    /**
+     * Whether to loop when reaching the end
+     */
+    loop?: boolean;
+    /**
+     * Callback when navigation occurs
+     */
+    onNavigate?: (index: number) => void;
+    /**
+     * Optional disabled state check per index
+     */
+    isDisabled?: (index: number) => boolean;
+}
+export interface RovingFocusResult {
+    /**
+     * Props for the container element (composes via mergeProps)
+     */
+    container: {
+        onKeyDown: (e: KeyboardLikeEvent) => void;
+    };
+    /**
+     * Generate props for an item at the given index (composes via mergeProps)
+     */
+    item: (index: number) => {
+        tabIndex: number;
+        'data-roving-index': number;
+    };
+}
+export declare function rovingFocus(options: RovingFocusOptions): RovingFocusResult;
+/**
+ * USAGE EXAMPLE:
+ *
+ * function Menu() {
+ *   const [focusIndex, setFocusIndex] = state(0);
+ *   const items = ['File', 'Edit', 'View'];
+ *
+ *   const navigation = rovingFocus({
+ *     currentIndex: focusIndex(),
+ *     itemCount: items.length,
+ *     orientation: 'horizontal',
+ *     loop: true,
+ *     onNavigate: setFocusIndex,
+ *   });
+ *
+ *   return (
+ *     <div {...navigation.container}>
+ *       {items.map((label, index) => (
+ *         <button {...navigation.item(index)}>
+ *           {label}
+ *         </button>
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ */
+//# sourceMappingURL=roving-focus.d.ts.map

package/dist/foundations/interactions/roving-focus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roving-focus.d.ts","sourceRoot":"","sources":["../../../src/foundations/interactions/roving-focus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAElE,MAAM,MAAM,WAAW,GAAG,YAAY,GAAG,UAAU,GAAG,MAAM,CAAC;AAE7D,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;IAE1B;;OAEG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IAEf;;OAEG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAErC;;OAEG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;CACzC;AAED,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,SAAS,EAAE;QACT,SAAS,EAAE,CAAC,CAAC,EAAE,iBAAiB,KAAK,IAAI,CAAC;KAC3C,CAAC;IAEF;;OAEG;IACH,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK;QACvB,QAAQ,EAAE,MAAM,CAAC;QACjB,mBAAmB,EAAE,MAAM,CAAC;KAC7B,CAAC;CACH;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,iBAAiB,CAkE1E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG"}

package/dist/foundations/interactions/roving-focus.js

@@ -0,0 +1 @@
+function v(u){const{currentIndex:r,itemCount:e,orientation:o="horizontal",loop:d=!1,onNavigate:l,isDisabled:c}=u;function f(t,i){let n=t+i;if(d)n<0&&(n=e-1),n>=e&&(n=0);else if(n<0||n>=e)return;return c?.(n)?n===t?void 0:f(n,i):n}function s(t){const{key:i}=t;let n;if((o==="horizontal"||o==="both")&&(i==="ArrowRight"&&(n=1),i==="ArrowLeft"&&(n=-1)),(o==="vertical"||o==="both")&&(i==="ArrowDown"&&(n=1),i==="ArrowUp"&&(n=-1)),n===void 0)return;const a=f(r,n);a!==void 0&&(t.preventDefault?.(),t.stopPropagation?.(),l?.(a))}return{container:{onKeyDown:s},item:t=>({tabIndex:t===r?0:-1,"data-roving-index":t})}}export{v as rovingFocus};

package/dist/foundations/state/controllable.d.ts

@@ -0,0 +1,53 @@
+/**
+ * controllable
+ *
+ * Small utilities for controlled vs uncontrolled components. These helpers are
+ * intentionally minimal and do not manage state themselves; they help component
+ * implementations make correct decisions about when to call `onChange` vs
+ * update internal state.
+ *
+ * POLICY DECISIONS (LOCKED):
+ *
+ * 1. Controlled Detection
+ *    A value is "controlled" if it is not `undefined`.
+ *    This matches React conventions and is SSR-safe.
+ *
+ * 2. onChange Timing
+ *    - Controlled mode: onChange called immediately, no internal update
+ *    - Uncontrolled mode: internal state updated first, then onChange called
+ *    This ensures onChange sees the new value in both modes.
+ *
+ * 3. Value Equality
+ *    controllableState uses Object.is() to prevent unnecessary onChange calls.
+ *    This is intentional — strict equality, no deep comparison.
+ */
+import { type State } from '../../runtime/state';
+export declare function isControlled<T>(value: T | undefined): value is T;
+export declare function resolveControllable<T>(value: T | undefined, defaultValue: T): {
+    value: T;
+    isControlled: boolean;
+};
+export declare function makeControllable<T>(options: {
+    value: T | undefined;
+    defaultValue: T;
+    onChange?: (next: T) => void;
+    setInternal?: (next: T) => void;
+}): {
+    set: (next: T) => void;
+    isControlled: boolean;
+};
+export type ControllableState<T> = State<T> & {
+    isControlled: boolean;
+};
+/**
+ * controllableState
+ *
+ * Hook-like primitive that mirrors `state()` semantics while supporting
+ * controlled/uncontrolled behavior.
+ */
+export declare function controllableState<T>(options: {
+    value: T | undefined;
+    defaultValue: T;
+    onChange?: (next: T) => void;
+}): ControllableState<T>;
+//# sourceMappingURL=controllable.d.ts.map

package/dist/foundations/state/controllable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controllable.d.ts","sourceRoot":"","sources":["../../../src/foundations/state/controllable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAS,KAAK,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAExD,wBAAgB,YAAY,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,SAAS,GAAG,KAAK,IAAI,CAAC,CAEhE;AAED,wBAAgB,mBAAmB,CAAC,CAAC,EACnC,KAAK,EAAE,CAAC,GAAG,SAAS,EACpB,YAAY,EAAE,CAAC,GACd;IAAE,KAAK,EAAE,CAAC,CAAC;IAAC,YAAY,EAAE,OAAO,CAAA;CAAE,CAMrC;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,OAAO,EAAE;IAC3C,KAAK,EAAE,CAAC,GAAG,SAAS,CAAC;IACrB,YAAY,EAAE,CAAC,CAAC;IAChB,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC;IAC7B,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC;CACjC;gBAIoB,CAAC;;EAUrB;AAED,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,GAAG;IAAE,YAAY,EAAE,OAAO,CAAA;CAAE,CAAC;AAExE;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,OAAO,EAAE;IAC5C,KAAK,EAAE,CAAC,GAAG,SAAS,CAAC;IACrB,YAAY,EAAE,CAAC,CAAC;IAChB,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC;CAC9B,GAAG,iBAAiB,CAAC,CAAC,CAAC,CA4BvB"}

package/dist/foundations/state/controllable.js

@@ -0,0 +1 @@
+import{state as s}from"../../runtime/state.js";function c(n){return n!==void 0}function a(n,t){const e=c(n);return{value:e?n:t,isControlled:e}}function C(n){const{value:t,defaultValue:e,onChange:o,setInternal:l}=n,{isControlled:r}=a(t,e);function u(i){r||l?.(i),o?.(i)}return{set:u,isControlled:r}}function d(n){const t=s(n.defaultValue),e=n.value!==void 0;function o(){return e?n.value:t()}return o.set=l=>{const r=o(),u=typeof l=="function"?l(r):l;if(!Object.is(r,u)){if(e){n.onChange?.(u);return}t.set(l),n.onChange?.(u)}},o.isControlled=e,o}export{d as controllableState,c as isControlled,C as makeControllable,a as resolveControllable};

package/dist/foundations/state/index.d.ts

@@ -0,0 +1,2 @@
+export * from './controllable';
+//# sourceMappingURL=index.d.ts.map

package/dist/foundations/state/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/foundations/state/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC"}

package/dist/foundations/structures/collection.d.ts

@@ -0,0 +1,67 @@
+/**
+ * createCollection
+ *
+ * Ordered descendant registry for coordinating items without DOM queries.
+ *
+ * INVARIANTS:
+ * 1. Registration order determines item order (no DOM queries)
+ * 2. Stable ordering across renders (insertion order preserved)
+ * 3. Each item may have metadata (type-safe, user-defined)
+ * 4. No implicit global state (explicit collection instances)
+ * 5. No automatic cleanup (caller controls lifecycle)
+ *
+ * DESIGN:
+ * - Returns a registry API ({ register, items, clear })
+ * - Items are stored in insertion order
+ * - Registration returns an unregister function
+ * - No side effects on registration (pure data structure)
+ *
+ * USAGE:
+ *   const collection = createCollection<HTMLElement, { disabled: boolean }>();
+ *   const unregister = collection.register(element, { disabled: false });
+ *   const allItems = collection.items();
+ *   unregister();
+ */
+export type CollectionItem<TNode, TMetadata = unknown> = {
+    node: TNode;
+    metadata: TMetadata;
+};
+export interface Collection<TNode, TMetadata = unknown> {
+    /**
+     * Register a node with optional metadata.
+     * Returns an unregister function.
+     */
+    register(node: TNode, metadata: TMetadata): () => void;
+    /**
+     * Get all registered items in insertion order.
+     */
+    items(): ReadonlyArray<CollectionItem<TNode, TMetadata>>;
+    /**
+     * Clear all registered items.
+     */
+    clear(): void;
+    /**
+     * Get the count of registered items.
+     */
+    size(): number;
+}
+export declare function createCollection<TNode, TMetadata = unknown>(): Collection<TNode, TMetadata>;
+/**
+ * USAGE EXAMPLE:
+ *
+ * // Create a collection for menu items
+ * const menuItems = createCollection<HTMLElement, { disabled: boolean }>();
+ *
+ * // Register items
+ * const unregister1 = menuItems.register(element1, { disabled: false });
+ * const unregister2 = menuItems.register(element2, { disabled: true });
+ *
+ * // Query items
+ * const allItems = menuItems.items();
+ * const enabledItems = allItems.filter(item => !item.metadata.disabled);
+ *
+ * // Cleanup
+ * unregister1();
+ * unregister2();
+ */
+//# sourceMappingURL=collection.d.ts.map

package/dist/foundations/structures/collection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection.d.ts","sourceRoot":"","sources":["../../../src/foundations/structures/collection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,MAAM,MAAM,cAAc,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,IAAI;IACvD,IAAI,EAAE,KAAK,CAAC;IACZ,QAAQ,EAAE,SAAS,CAAC;CACrB,CAAC;AAEF,MAAM,WAAW,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO;IACpD;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,GAAG,MAAM,IAAI,CAAC;IAEvD;;OAEG;IACH,KAAK,IAAI,aAAa,CAAC,cAAc,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC;IAEzD;;OAEG;IACH,KAAK,IAAI,IAAI,CAAC;IAEd;;OAEG;IACH,IAAI,IAAI,MAAM,CAAC;CAChB;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,KAAK,UAAU,CACxE,KAAK,EACL,SAAS,CACV,CA8BA;AAED;;;;;;;;;;;;;;;;;GAiBG"}

package/dist/foundations/structures/collection.js

@@ -0,0 +1 @@
+function s(){const e=new Map;function r(t,u){const o={node:t,metadata:u};return e.set(t,o),()=>{e.delete(t)}}function n(){return Array.from(e.values())}function i(){e.clear()}function c(){return e.size}return{register:r,items:n,clear:i,size:c}}export{s as createCollection};

package/dist/foundations/structures/index.d.ts

@@ -0,0 +1,5 @@
+export * from './layout';
+export * from './slot';
+export * from './portal';
+export * from './presence';
+//# sourceMappingURL=index.d.ts.map

package/dist/foundations/structures/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/foundations/structures/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC"}