@askrjs/askr 0.0.29 → 0.0.30

package/dist/benchmark.js

@@ -10,8 +10,8 @@ import { BenchmarkTable } from "./bench/components/benchmark-table.js";
 installRendererBridge();
 const benchmarkMetadata = {
 	packageName: "@askrjs/askr",
-	packageVersion: "0.0.29",
-	buildLabel: "0.0.29-local"
+	packageVersion: "0.0.30",
+	buildLabel: "0.0.30-local"
 };
 function getBenchmarkMetadata() {
 	return { ...benchmarkMetadata };

package/dist/foundations/core.d.ts

@@ -0,0 +1,15 @@
+import { ComposeHandlersOptions, composeHandlers } from "./utilities/compose-handlers.js";
+import { mergeProps } from "./utilities/merge-props.js";
+import { ariaDisabled, ariaExpanded, ariaSelected } from "./utilities/aria.js";
+import { Ref, composeRefs, setRef } from "./utilities/compose-ref.js";
+import { FormatIdOptions, formatId } from "./utilities/use-id.js";
+import { DefaultPreventable, FocusLikeEvent, KeyboardLikeEvent, PointerLikeEvent, PropagationStoppable } from "./utilities/event-types.js";
+import { PressableOptions, PressableResult, pressable } from "./interactions/pressable.js";
+import { DismissableOptions, dismissable } from "./interactions/dismissable.js";
+import { FocusableOptions, FocusableResult, focusable } from "./interactions/focusable.js";
+import { HoverableOptions, HoverableResult, hoverable } from "./interactions/hoverable.js";
+import { Orientation, RovingFocusOptions, RovingFocusResult, rovingFocus } from "./interactions/roving-focus.js";
+import { InteractionPolicyInput, applyInteractionPolicy, mergeInteractionProps } from "./interactions/interaction-policy.js";
+import { ControllableState, controllableState, isControlled, makeControllable, resolveControllable } from "./state/controllable.js";
+import { IconOwnProps, IconProps, IconSizeToken, IconStyleObject } from "./icon/icon.types.js";
+import { IconBase, getIconContractProps, isIconSizeToken, joinIconStyle, normalizeIconSizeValue, resolveIconSizeVariable, resolveIconStrokeWidthVariable, serializeIconStyle } from "./icon/icon.js";

package/dist/foundations/core.js

@@ -0,0 +1,13 @@
+import "./utilities/aria.js";
+import "./interactions/pressable.js";
+import "./utilities/compose-handlers.js";
+import "./utilities/compose-ref.js";
+import "./utilities/merge-props.js";
+import "./interactions/interaction-policy.js";
+import "./utilities/use-id.js";
+import "./interactions/dismissable.js";
+import "./interactions/focusable.js";
+import "./interactions/hoverable.js";
+import "./interactions/roving-focus.js";
+import "./state/controllable.js";
+import "./icon/icon.js";

package/dist/foundations/index.d.ts

@@ -1,10 +1,23 @@
 import { JSXElement } from "../common/jsx.js";
+import { ComposeHandlersOptions, composeHandlers } from "./utilities/compose-handlers.js";
+import { mergeProps } from "./utilities/merge-props.js";
+import { ariaDisabled, ariaExpanded, ariaSelected } from "./utilities/aria.js";
+import { Ref, composeRefs, setRef } from "./utilities/compose-ref.js";
+import { FormatIdOptions, formatId } from "./utilities/use-id.js";
+import { DefaultPreventable, FocusLikeEvent, KeyboardLikeEvent, PointerLikeEvent, PropagationStoppable } from "./utilities/event-types.js";
+import { PressableOptions, PressableResult, pressable } from "./interactions/pressable.js";
+import { DismissableOptions, dismissable } from "./interactions/dismissable.js";
+import { FocusableOptions, FocusableResult, focusable } from "./interactions/focusable.js";
+import { HoverableOptions, HoverableResult, hoverable } from "./interactions/hoverable.js";
+import { Orientation, RovingFocusOptions, RovingFocusResult, rovingFocus } from "./interactions/roving-focus.js";
+import { InteractionPolicyInput, applyInteractionPolicy, mergeInteractionProps } from "./interactions/interaction-policy.js";
+import { ControllableState, controllableState, isControlled, makeControllable, resolveControllable } from "./state/controllable.js";
+import { IconOwnProps, IconProps, IconSizeToken, IconStyleObject } from "./icon/icon.types.js";
+import { IconBase, getIconContractProps, isIconSizeToken, joinIconStyle, normalizeIconSizeValue, resolveIconSizeVariable, resolveIconStrokeWidthVariable, serializeIconStyle } from "./icon/icon.js";
 import { LayoutComponent, layout } from "./structures/layout.js";
 import { Slot, SlotProps } from "./structures/slot.js";
 import { Presence, PresenceProps } from "./structures/presence.js";
 import { DefaultPortal, Portal, PortalProps, definePortal } from "./structures/portal.js";
 import { Collection, CollectionItem, createCollection } from "./structures/collection.js";
 import { Layer, LayerManager, LayerOptions, createLayer } from "./structures/layer.js";
-import { IconOwnProps, IconProps, IconSizeToken, IconStyleObject } from "./icon/icon.types.js";
-import { IconBase, getIconContractProps, isIconSizeToken, joinIconStyle, normalizeIconSizeValue, resolveIconSizeVariable, resolveIconStrokeWidthVariable, serializeIconStyle } from "./icon/icon.js";
-export { Collection, CollectionItem, DefaultPortal, IconBase, type IconOwnProps, type IconProps, type IconSizeToken, type IconStyleObject, JSXElement, Layer, LayerManager, LayerOptions, LayoutComponent, Portal, PortalProps, Presence, PresenceProps, Slot, SlotProps, createCollection, createLayer, definePortal, getIconContractProps, isIconSizeToken, joinIconStyle, layout, normalizeIconSizeValue, resolveIconSizeVariable, resolveIconStrokeWidthVariable, serializeIconStyle };
+export { Collection, CollectionItem, ComposeHandlersOptions, ControllableState, DefaultPortal, DefaultPreventable, DismissableOptions, FocusLikeEvent, FocusableOptions, FocusableResult, FormatIdOptions, HoverableOptions, HoverableResult, IconBase, type IconOwnProps, type IconProps, type IconSizeToken, type IconStyleObject, InteractionPolicyInput, JSXElement, KeyboardLikeEvent, Layer, LayerManager, LayerOptions, LayoutComponent, Orientation, PointerLikeEvent, Portal, PortalProps, Presence, PresenceProps, PressableOptions, PressableResult, PropagationStoppable, Ref, RovingFocusOptions, RovingFocusResult, Slot, SlotProps, applyInteractionPolicy, ariaDisabled, ariaExpanded, ariaSelected, composeHandlers, composeRefs, controllableState, createCollection, createLayer, definePortal, dismissable, focusable, formatId, getIconContractProps, hoverable, isControlled, isIconSizeToken, joinIconStyle, layout, makeControllable, mergeInteractionProps, mergeProps, normalizeIconSizeValue, pressable, resolveControllable, resolveIconSizeVariable, resolveIconStrokeWidthVariable, rovingFocus, serializeIconStyle, setRef };

package/dist/foundations/index.js

@@ -1,9 +1,22 @@
 import { DefaultPortal, Portal, definePortal } from "./structures/portal.js";
+import { ariaDisabled, ariaExpanded, ariaSelected } from "./utilities/aria.js";
+import { pressable } from "./interactions/pressable.js";
+import { composeHandlers } from "./utilities/compose-handlers.js";
+import { composeRefs, setRef } from "./utilities/compose-ref.js";
+import { mergeProps } from "./utilities/merge-props.js";
+import { applyInteractionPolicy, mergeInteractionProps } from "./interactions/interaction-policy.js";
 import { layout } from "./structures/layout.js";
 import { Slot } from "./structures/slot.js";
 import { Presence } from "./structures/presence.js";
 import { createCollection } from "./structures/collection.js";
 import { createLayer } from "./structures/layer.js";
 import "./structures.js";
+import { formatId } from "./utilities/use-id.js";
+import { dismissable } from "./interactions/dismissable.js";
+import { focusable } from "./interactions/focusable.js";
+import { hoverable } from "./interactions/hoverable.js";
+import { rovingFocus } from "./interactions/roving-focus.js";
+import { controllableState, isControlled, makeControllable, resolveControllable } from "./state/controllable.js";
 import { IconBase, getIconContractProps, isIconSizeToken, joinIconStyle, normalizeIconSizeValue, resolveIconSizeVariable, resolveIconStrokeWidthVariable, serializeIconStyle } from "./icon/icon.js";
-export { DefaultPortal, IconBase, Portal, Presence, Slot, createCollection, createLayer, definePortal, getIconContractProps, isIconSizeToken, joinIconStyle, layout, normalizeIconSizeValue, resolveIconSizeVariable, resolveIconStrokeWidthVariable, serializeIconStyle };
+import "./core.js";
+export { DefaultPortal, IconBase, Portal, Presence, Slot, applyInteractionPolicy, ariaDisabled, ariaExpanded, ariaSelected, composeHandlers, composeRefs, controllableState, createCollection, createLayer, definePortal, dismissable, focusable, formatId, getIconContractProps, hoverable, isControlled, isIconSizeToken, joinIconStyle, layout, makeControllable, mergeInteractionProps, mergeProps, normalizeIconSizeValue, pressable, resolveControllable, resolveIconSizeVariable, resolveIconStrokeWidthVariable, rovingFocus, serializeIconStyle, setRef };

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

@@ -0,0 +1,66 @@
+import { KeyboardLikeEvent, PointerLikeEvent } from "../utilities/event-types.js";
+
+//#region src/foundations/interactions/dismissable.d.ts
+/**
+ * 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
+ */
+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;
+}
+declare function dismissable({
+  node,
+  disabled,
+  onDismiss
+}: DismissableOptions): {
+  onKeyDown: (e: KeyboardLikeEvent) => void;
+  onPointerDownCapture: (e: PointerLikeEvent) => void;
+};
+//#endregion
+export { DismissableOptions, dismissable };
+//# sourceMappingURL=dismissable.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dismissable.d.ts","names":[],"sources":["../../../src/foundations/interactions/dismissable.ts"],"mappings":";;;;;;AAuCA;;;;;;;;;;;AAsBA;;;;;;;;;;;;;;;;;;;;;;;;UAtBiB,kBAAA;EAgCsC;;;EA5BrD,IAAA,GAAO,IAAA;;;;EAKP,QAAA;;;;EAKA,SAAA,IAAa,OAAA;AAAA;AAAA,iBAQC,WAAA,CAAA;EAAc,IAAA;EAAM,QAAA;EAAU;AAAA,GAAa,kBAAA;iBAC/B,iBAAA;4BASW,gBAAA;AAAA"}

package/dist/foundations/interactions/dismissable.js

@@ -0,0 +1,26 @@
+//#region src/foundations/interactions/dismissable.ts
+function dismissable({ node, disabled, onDismiss }) {
+	function handleKeyDown(e) {
+		if (disabled) return;
+		if (e.key === "Escape") {
+			e.preventDefault?.();
+			e.stopPropagation?.();
+			onDismiss?.("escape");
+		}
+	}
+	function handlePointerDownCapture(e) {
+		if (disabled) return;
+		const target = e.target;
+		if (!(target instanceof Node)) return;
+		if (!node) return;
+		if (!node.contains(target)) onDismiss?.("outside");
+	}
+	return {
+		onKeyDown: handleKeyDown,
+		onPointerDownCapture: handlePointerDownCapture
+	};
+}
+//#endregion
+export { dismissable };
+
+//# sourceMappingURL=dismissable.js.map

package/dist/foundations/interactions/dismissable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dismissable.js","names":[],"sources":["../../../src/foundations/interactions/dismissable.ts"],"sourcesContent":["/**\n * dismissable\n *\n * THE dismissal primitive. Handles Escape key and outside interactions.\n *\n * INVARIANTS:\n * 1. Returns props that compose via mergeProps (no factories)\n * 2. Disabled state respected exactly once, here\n * 3. No side effects - pure props generation\n * 4. Outside detection requires explicit node reference\n * 5. This is the ONLY dismissal primitive - do not create alternatives\n *\n * DESIGN:\n * - Returns standard event handler props (onKeyDown, onPointerDownCapture)\n * - Composable via mergeProps with other foundations\n * - Caller provides node reference for outside detection\n * - Single onDismiss callback for all dismiss triggers\n *\n * PIT OF SUCCESS:\n * ✓ Can't accidentally bypass (only way to get dismiss behavior)\n * ✓ Can't duplicate (disabled checked once)\n * ✓ Composes via mergeProps (standard props)\n * ✓ Wrong usage is hard (no factories to misuse)\n *\n * USAGE:\n *   const props = dismissable({\n *     node: elementRef,\n *     disabled: false,\n *     onDismiss: () => close()\n *   });\n *\n *   <div ref={elementRef} {...props}>Content</div>\n *\n * MISUSE EXAMPLE (PREVENTED):\n *   ❌ Can't forget to check disabled - checked inside dismissable\n *   ❌ Can't create custom escape handler - this is the only one\n *   ❌ Can't bypass via direct event listeners - mergeProps composes correctly\n */\n\nexport interface DismissableOptions {\n  /**\n   * Reference to the element for outside click detection\n   */\n  node?: Node | null;\n\n  /**\n   * Whether dismiss is disabled\n   */\n  disabled?: boolean;\n\n  /**\n   * Called when dismiss is triggered (Escape or outside click)\n   */\n  onDismiss?: (trigger: 'escape' | 'outside') => void;\n}\n\nimport type {\n  KeyboardLikeEvent,\n  PointerLikeEvent,\n} from '../utilities/event-types';\n\nexport function dismissable({ node, disabled, onDismiss }: DismissableOptions) {\n  function handleKeyDown(e: KeyboardLikeEvent) {\n    if (disabled) return;\n    if (e.key === 'Escape') {\n      e.preventDefault?.();\n      e.stopPropagation?.();\n      onDismiss?.('escape');\n    }\n  }\n\n  function handlePointerDownCapture(e: PointerLikeEvent) {\n    if (disabled) return;\n\n    const target = e.target;\n    if (!(target instanceof Node)) return;\n\n    // If no node provided, can't detect outside clicks\n    if (!node) return;\n\n    // Check if click is outside\n    if (!node.contains(target)) {\n      onDismiss?.('outside');\n    }\n  }\n\n  return {\n    onKeyDown: handleKeyDown,\n    // Use capture phase to catch events before they bubble\n    onPointerDownCapture: handlePointerDownCapture,\n  };\n}\n"],"mappings":";AA6DA,SAAgB,YAAY,EAAE,MAAM,UAAU,aAAiC;CAC7E,SAAS,cAAc,GAAsB;AAC3C,MAAI,SAAU;AACd,MAAI,EAAE,QAAQ,UAAU;AACtB,KAAE,kBAAkB;AACpB,KAAE,mBAAmB;AACrB,eAAY,SAAS;;;CAIzB,SAAS,yBAAyB,GAAqB;AACrD,MAAI,SAAU;EAEd,MAAM,SAAS,EAAE;AACjB,MAAI,EAAE,kBAAkB,MAAO;AAG/B,MAAI,CAAC,KAAM;AAGX,MAAI,CAAC,KAAK,SAAS,OAAO,CACxB,aAAY,UAAU;;AAI1B,QAAO;EACL,WAAW;EAEX,sBAAsB;EACvB"}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"focusable.d.ts","names":[],"sources":["../../../src/foundations/interactions/focusable.ts"],"mappings":";;AASA;;;;;UAAiB,gBAAA;EACf,QAAA;EACA,QAAA;AAAA;AAAA,UAGe,eAAA;EACf,QAAA;EACA,eAAA;AAAA;AAAA,iBAGc,SAAA,CAAA;EACd,QAAA;EACA;AAAA,GACC,gBAAA,GAAmB,eAAA"}

package/dist/foundations/interactions/focusable.js

@@ -0,0 +1,18 @@
+import { ariaDisabled } from "../utilities/aria.js";
+//#region src/foundations/interactions/focusable.ts
+/**
+* focusable
+*
+* Normalize focus-related props for hosts.
+* - No DOM manipulation here; returns props that the runtime may attach.
+*/
+function focusable({ disabled, tabIndex }) {
+	return {
+		tabIndex: disabled ? -1 : tabIndex === void 0 ? 0 : tabIndex,
+		...ariaDisabled(disabled)
+	};
+}
+//#endregion
+export { focusable };
+
+//# sourceMappingURL=focusable.js.map

package/dist/foundations/interactions/focusable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"focusable.js","names":[],"sources":["../../../src/foundations/interactions/focusable.ts"],"sourcesContent":["/**\n * focusable\n *\n * Normalize focus-related props for hosts.\n * - No DOM manipulation here; returns props that the runtime may attach.\n */\n\nimport { ariaDisabled } from '../utilities/aria';\n\nexport interface FocusableOptions {\n  disabled?: boolean;\n  tabIndex?: number | undefined;\n}\n\nexport interface FocusableResult {\n  tabIndex?: number;\n  'aria-disabled'?: 'true';\n}\n\nexport function focusable({\n  disabled,\n  tabIndex,\n}: FocusableOptions): FocusableResult {\n  return {\n    tabIndex: disabled ? -1 : tabIndex === undefined ? 0 : tabIndex,\n    ...ariaDisabled(disabled),\n  };\n}\n"],"mappings":";;;;;;;;AAmBA,SAAgB,UAAU,EACxB,UACA,YACoC;AACpC,QAAO;EACL,UAAU,WAAW,KAAK,aAAa,SAAY,IAAI;EACvD,GAAG,aAAa,SAAS;EAC1B"}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"hoverable.d.ts","names":[],"sources":["../../../src/foundations/interactions/hoverable.ts"],"mappings":";;;;;;AAMA;;UAAiB,gBAAA;EACf,QAAA;EACA,OAAA,IAAW,CAAA,EAAG,UAAA;EACd,OAAA,IAAW,CAAA,EAAG,UAAA;AAAA;AAAA,KAQX,UAAA,GAAa,kBAAA,GAAqB,oBAAA;AAAA,UAEtB,eAAA;EACf,cAAA,IAAkB,CAAA,EAAG,UAAA;EACrB,cAAA,IAAkB,CAAA,EAAG,UAAA;AAAA;AAAA,iBAGP,SAAA,CAAA;EACd,QAAA;EACA,OAAA;EACA;AAAA,GACC,gBAAA,GAAmB,eAAA"}

package/dist/foundations/interactions/hoverable.js

@@ -0,0 +1,15 @@
+//#region src/foundations/interactions/hoverable.ts
+function hoverable({ disabled, onEnter, onLeave }) {
+	return {
+		onPointerEnter: disabled ? void 0 : (e) => {
+			onEnter?.(e);
+		},
+		onPointerLeave: disabled ? void 0 : (e) => {
+			onLeave?.(e);
+		}
+	};
+}
+//#endregion
+export { hoverable };
+
+//# sourceMappingURL=hoverable.js.map

package/dist/foundations/interactions/hoverable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hoverable.js","names":[],"sources":["../../../src/foundations/interactions/hoverable.ts"],"sourcesContent":["/**\n * hoverable\n *\n * Produces props for pointer enter/leave handling. Pure and deterministic.\n */\n\nexport interface HoverableOptions {\n  disabled?: boolean;\n  onEnter?: (e: HoverEvent) => void;\n  onLeave?: (e: HoverEvent) => void;\n}\n\nimport type {\n  DefaultPreventable,\n  PropagationStoppable,\n} from '../utilities/event-types';\n\ntype HoverEvent = DefaultPreventable & PropagationStoppable;\n\nexport interface HoverableResult {\n  onPointerEnter?: (e: HoverEvent) => void;\n  onPointerLeave?: (e: HoverEvent) => void;\n}\n\nexport function hoverable({\n  disabled,\n  onEnter,\n  onLeave,\n}: HoverableOptions): HoverableResult {\n  return {\n    onPointerEnter: disabled\n      ? undefined\n      : (e) => {\n          onEnter?.(e);\n        },\n    onPointerLeave: disabled\n      ? undefined\n      : (e) => {\n          onLeave?.(e);\n        },\n  };\n}\n"],"mappings":";AAwBA,SAAgB,UAAU,EACxB,UACA,SACA,WACoC;AACpC,QAAO;EACL,gBAAgB,WACZ,UACC,MAAM;AACL,aAAU,EAAE;;EAElB,gBAAgB,WACZ,UACC,MAAM;AACL,aAAU,EAAE;;EAEnB"}

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

@@ -0,0 +1,50 @@
+import { Ref } from "../utilities/compose-ref.js";
+import { DefaultPreventable, KeyboardLikeEvent, PropagationStoppable } from "../utilities/event-types.js";
+//#region src/foundations/interactions/interaction-policy.d.ts
+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.
+ */
+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: DefaultPreventable & PropagationStoppable) => void;
+  disabled?: true;
+  role?: "button";
+  onKeyDown?: (e: KeyboardLikeEvent) => void;
+  onKeyUp?: (e: 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.
+ */
+declare function mergeInteractionProps(childProps: Record<string, unknown>, policyProps: Record<string, unknown>, userProps?: Record<string, unknown>): Record<string, unknown>;
+//#endregion
+export { InteractionPolicyInput, applyInteractionPolicy, mergeInteractionProps };
+//# 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","names":[],"sources":["../../../src/foundations/interactions/interaction-policy.ts"],"mappings":";;;UA6DiB,sBAAA;;EAEf,QAAA;;EAEA,QAAA;;EAEA,OAAA,IAAW,CAAA,EAAG,KAAA;;EAEd,GAAA,GAAM,GAAA;AAAA;;;AAwDR;;iBAjDgB,sBAAA,CAAA;EACd,QAAA;EACA,QAAA;EACA,OAAA;EACA;AAAA,GACC,sBAAA;;eAcgB,KAAA;;;;;;;;;;;;;;;;;;;;;;iBA8BH,qBAAA,CACd,UAAA,EAAY,MAAA,mBACZ,WAAA,EAAa,MAAA,mBACb,SAAA,GAAY,MAAA,oBAAuB,MAAA"}

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

@@ -1,7 +1,7 @@
 import { pressable } from "./pressable.js";
-import "../utilities/compose-handlers.js";
-import "../utilities/compose-ref.js";
-import "../utilities/merge-props.js";
+import { composeHandlers } from "../utilities/compose-handlers.js";
+import { composeRefs } from "../utilities/compose-ref.js";
+import { mergeProps } from "../utilities/merge-props.js";
 //#region src/foundations/interactions/interaction-policy.ts
 /**
 * INTERACTION POLICY (FRAMEWORK LAW)
@@ -87,7 +87,36 @@ function applyInteractionPolicy({ isNative, disabled, onPress, ref }) {
 		ref
 	};
 }
+/**
+* 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.
+*/
+function mergeInteractionProps(childProps, policyProps, userProps) {
+	let out = mergeProps(childProps, policyProps);
+	if (userProps) out = mergeProps(out, userProps);
+	for (const k in out) {
+		if (!k.startsWith("on")) continue;
+		const policyHandler = policyProps?.[k];
+		const userHandler = userProps?.[k];
+		const childHandler = childProps?.[k];
+		if (policyHandler || userHandler || childHandler) {
+			const toHandler = (h) => typeof h === "function" ? h : void 0;
+			out[k] = composeHandlers(toHandler(policyHandler), composeHandlers(toHandler(userHandler), toHandler(childHandler)));
+		}
+	}
+	const childRef = childProps?.ref;
+	const userRef = userProps?.ref;
+	const policyRef = policyProps?.ref;
+	out.ref = composeRefs(childRef, userRef, policyRef);
+	return out;
+}
 //#endregion
-export { applyInteractionPolicy };
+export { applyInteractionPolicy, mergeInteractionProps };
 
 //# sourceMappingURL=interaction-policy.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"interaction-policy.js","names":["mergePropsBase"],"sources":["../../../src/foundations/interactions/interaction-policy.ts"],"sourcesContent":["/**\n * INTERACTION POLICY (FRAMEWORK LAW)\n *\n * This is THE ONLY way to create interactive elements. Components MUST NOT\n * implement interaction logic directly.\n *\n * INVARIANTS (ENFORCED):\n * 1. \"Press\" is the semantic. Click/touch/Enter/Space are implementation details.\n * 2. Disabled is enforced exactly once, here. Components may not check disabled.\n * 3. Keyboard handling is automatic. Components may not add onKeyDown for activation.\n * 4. Native elements opt out of polyfills, not semantics.\n * 5. asChild may replace the host element, not interaction behavior.\n * 6. This policy is the SINGLE SOURCE OF TRUTH for interactive behavior.\n *\n * DESIGN:\n * - Single public function: applyInteractionPolicy\n * - Returns props that compose via mergeProps\n * - Delegates to pressable for mechanics\n * - Enforces disabled once and only once\n * - No configuration beyond disabled and native element type\n *\n * PIT OF SUCCESS:\n * ✓ Can't bypass policy (only way to get interaction behavior)\n * ✓ Can't duplicate disabled checks (enforced once, here)\n * ✓ Can't write custom keyboard handlers for buttons (policy owns it)\n * ✓ Composes via mergeProps (standard props)\n * ✓ Wrong usage is impossible (no escape hatch)\n *\n * USAGE:\n *   function Button({ onPress, disabled }) {\n *     const interaction = applyInteractionPolicy({\n *       isNative: true,\n *       disabled,\n *       onPress\n *     });\n *\n *     return <button {...interaction}>Click me</button>;\n *   }\n *\n * MISUSE EXAMPLE (PREVENTED):\n *   ❌ Button checking disabled again:\n *      function Button({ disabled, onPress }) {\n *        if (disabled) return; // NO! Policy handles this\n *        const interaction = applyInteractionPolicy(...);\n *      }\n *\n *   ❌ Custom keyboard handler:\n *      function Button({ onPress }) {\n *        const interaction = applyInteractionPolicy(...);\n *        return <button {...interaction} onKeyDown={...}>; // NO! Policy owns this\n *      }\n *\n *   ❌ Direct event handler:\n *      <button onClick={onPress}>; // NO! Use applyInteractionPolicy\n */\n\nimport { pressable } from './pressable';\nimport { composeHandlers } from '../utilities/compose-handlers';\nimport { composeRefs, Ref } from '../utilities/compose-ref';\nimport { mergeProps as mergePropsBase } from '../utilities/merge-props';\n\nexport interface InteractionPolicyInput {\n  /** Whether the host element is a native interactive element (button, a, etc) */\n  isNative: boolean;\n  /** Disabled state - checked ONLY here, never in components */\n  disabled: boolean;\n  /** User-provided press handler - semantic action, not DOM event */\n  onPress?: (e: Event) => void;\n  /** Optional ref to compose */\n  ref?: Ref<unknown>;\n}\n\n/**\n * THE interaction policy. Components MUST use this, NEVER implement\n * interaction logic directly.\n */\nexport function applyInteractionPolicy({\n  isNative,\n  disabled,\n  onPress,\n  ref,\n}: InteractionPolicyInput) {\n  // Disabled is enforced exactly once, here.\n  // Components downstream may NOT check disabled.\n  function invokePress(e: Event) {\n    if (disabled) {\n      e.preventDefault?.();\n      return;\n    }\n    onPress?.(e);\n  }\n\n  if (isNative) {\n    return {\n      disabled: disabled || undefined,\n      onClick: (e: Event) => invokePress(e),\n      ref,\n    };\n  }\n\n  // Non-native elements get full button semantics\n  const interaction = pressable({\n    disabled,\n    isNativeButton: false,\n    onPress: (e) => invokePress(e as Event),\n  });\n\n  return {\n    ...interaction,\n    'aria-disabled': disabled || undefined,\n    tabIndex: disabled ? -1 : (interaction.tabIndex ?? 0),\n    ref,\n  };\n}\n\n/**\n * Merge rule for Slot / asChild\n *\n * Precedence:\n *   policy → user → child\n *\n * Event handlers are composed (policy first).\n * Refs are always composed.\n * Policy props MUST take precedence to enforce invariants.\n */\nexport function mergeInteractionProps(\n  childProps: Record<string, unknown>,\n  policyProps: Record<string, unknown>,\n  userProps?: Record<string, unknown>\n) {\n  let out = mergePropsBase(childProps, policyProps);\n  if (userProps) out = mergePropsBase(out, userProps);\n\n  // Ensure policy handlers always run first\n  for (const k in out) {\n    if (!k.startsWith('on')) continue;\n\n    const policyHandler = policyProps?.[k];\n    const userHandler = userProps?.[k];\n    const childHandler = childProps?.[k];\n\n    if (policyHandler || userHandler || childHandler) {\n      const toHandler = (h: unknown) =>\n        typeof h === 'function'\n          ? (h as (...args: readonly unknown[]) => void)\n          : undefined;\n\n      out[k] = composeHandlers(\n        toHandler(policyHandler),\n        composeHandlers(toHandler(userHandler), toHandler(childHandler))\n      );\n    }\n  }\n\n  const childRef = childProps?.ref as Ref<unknown> | undefined;\n  const userRef = userProps?.ref as Ref<unknown> | undefined;\n  const policyRef = policyProps?.ref as Ref<unknown> | undefined;\n\n  out.ref = composeRefs(childRef, userRef, policyRef);\n\n  return out;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4EA,SAAgB,uBAAuB,EACrC,UACA,UACA,SACA,OACyB;CAGzB,SAAS,YAAY,GAAU;AAC7B,MAAI,UAAU;AACZ,KAAE,kBAAkB;AACpB;;AAEF,YAAU,EAAE;;AAGd,KAAI,SACF,QAAO;EACL,UAAU,YAAY;EACtB,UAAU,MAAa,YAAY,EAAE;EACrC;EACD;CAIH,MAAM,cAAc,UAAU;EAC5B;EACA,gBAAgB;EAChB,UAAU,MAAM,YAAY,EAAW;EACxC,CAAC;AAEF,QAAO;EACL,GAAG;EACH,iBAAiB,YAAY;EAC7B,UAAU,WAAW,KAAM,YAAY,YAAY;EACnD;EACD"}
+{"version":3,"file":"interaction-policy.js","names":["mergePropsBase"],"sources":["../../../src/foundations/interactions/interaction-policy.ts"],"sourcesContent":["/**\n * INTERACTION POLICY (FRAMEWORK LAW)\n *\n * This is THE ONLY way to create interactive elements. Components MUST NOT\n * implement interaction logic directly.\n *\n * INVARIANTS (ENFORCED):\n * 1. \"Press\" is the semantic. Click/touch/Enter/Space are implementation details.\n * 2. Disabled is enforced exactly once, here. Components may not check disabled.\n * 3. Keyboard handling is automatic. Components may not add onKeyDown for activation.\n * 4. Native elements opt out of polyfills, not semantics.\n * 5. asChild may replace the host element, not interaction behavior.\n * 6. This policy is the SINGLE SOURCE OF TRUTH for interactive behavior.\n *\n * DESIGN:\n * - Single public function: applyInteractionPolicy\n * - Returns props that compose via mergeProps\n * - Delegates to pressable for mechanics\n * - Enforces disabled once and only once\n * - No configuration beyond disabled and native element type\n *\n * PIT OF SUCCESS:\n * ✓ Can't bypass policy (only way to get interaction behavior)\n * ✓ Can't duplicate disabled checks (enforced once, here)\n * ✓ Can't write custom keyboard handlers for buttons (policy owns it)\n * ✓ Composes via mergeProps (standard props)\n * ✓ Wrong usage is impossible (no escape hatch)\n *\n * USAGE:\n *   function Button({ onPress, disabled }) {\n *     const interaction = applyInteractionPolicy({\n *       isNative: true,\n *       disabled,\n *       onPress\n *     });\n *\n *     return <button {...interaction}>Click me</button>;\n *   }\n *\n * MISUSE EXAMPLE (PREVENTED):\n *   ❌ Button checking disabled again:\n *      function Button({ disabled, onPress }) {\n *        if (disabled) return; // NO! Policy handles this\n *        const interaction = applyInteractionPolicy(...);\n *      }\n *\n *   ❌ Custom keyboard handler:\n *      function Button({ onPress }) {\n *        const interaction = applyInteractionPolicy(...);\n *        return <button {...interaction} onKeyDown={...}>; // NO! Policy owns this\n *      }\n *\n *   ❌ Direct event handler:\n *      <button onClick={onPress}>; // NO! Use applyInteractionPolicy\n */\n\nimport { pressable } from './pressable';\nimport { composeHandlers } from '../utilities/compose-handlers';\nimport { composeRefs, Ref } from '../utilities/compose-ref';\nimport { mergeProps as mergePropsBase } from '../utilities/merge-props';\n\nexport interface InteractionPolicyInput {\n  /** Whether the host element is a native interactive element (button, a, etc) */\n  isNative: boolean;\n  /** Disabled state - checked ONLY here, never in components */\n  disabled: boolean;\n  /** User-provided press handler - semantic action, not DOM event */\n  onPress?: (e: Event) => void;\n  /** Optional ref to compose */\n  ref?: Ref<unknown>;\n}\n\n/**\n * THE interaction policy. Components MUST use this, NEVER implement\n * interaction logic directly.\n */\nexport function applyInteractionPolicy({\n  isNative,\n  disabled,\n  onPress,\n  ref,\n}: InteractionPolicyInput) {\n  // Disabled is enforced exactly once, here.\n  // Components downstream may NOT check disabled.\n  function invokePress(e: Event) {\n    if (disabled) {\n      e.preventDefault?.();\n      return;\n    }\n    onPress?.(e);\n  }\n\n  if (isNative) {\n    return {\n      disabled: disabled || undefined,\n      onClick: (e: Event) => invokePress(e),\n      ref,\n    };\n  }\n\n  // Non-native elements get full button semantics\n  const interaction = pressable({\n    disabled,\n    isNativeButton: false,\n    onPress: (e) => invokePress(e as Event),\n  });\n\n  return {\n    ...interaction,\n    'aria-disabled': disabled || undefined,\n    tabIndex: disabled ? -1 : (interaction.tabIndex ?? 0),\n    ref,\n  };\n}\n\n/**\n * Merge rule for Slot / asChild\n *\n * Precedence:\n *   policy → user → child\n *\n * Event handlers are composed (policy first).\n * Refs are always composed.\n * Policy props MUST take precedence to enforce invariants.\n */\nexport function mergeInteractionProps(\n  childProps: Record<string, unknown>,\n  policyProps: Record<string, unknown>,\n  userProps?: Record<string, unknown>\n) {\n  let out = mergePropsBase(childProps, policyProps);\n  if (userProps) out = mergePropsBase(out, userProps);\n\n  // Ensure policy handlers always run first\n  for (const k in out) {\n    if (!k.startsWith('on')) continue;\n\n    const policyHandler = policyProps?.[k];\n    const userHandler = userProps?.[k];\n    const childHandler = childProps?.[k];\n\n    if (policyHandler || userHandler || childHandler) {\n      const toHandler = (h: unknown) =>\n        typeof h === 'function'\n          ? (h as (...args: readonly unknown[]) => void)\n          : undefined;\n\n      out[k] = composeHandlers(\n        toHandler(policyHandler),\n        composeHandlers(toHandler(userHandler), toHandler(childHandler))\n      );\n    }\n  }\n\n  const childRef = childProps?.ref as Ref<unknown> | undefined;\n  const userRef = userProps?.ref as Ref<unknown> | undefined;\n  const policyRef = policyProps?.ref as Ref<unknown> | undefined;\n\n  out.ref = composeRefs(childRef, userRef, policyRef);\n\n  return out;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4EA,SAAgB,uBAAuB,EACrC,UACA,UACA,SACA,OACyB;CAGzB,SAAS,YAAY,GAAU;AAC7B,MAAI,UAAU;AACZ,KAAE,kBAAkB;AACpB;;AAEF,YAAU,EAAE;;AAGd,KAAI,SACF,QAAO;EACL,UAAU,YAAY;EACtB,UAAU,MAAa,YAAY,EAAE;EACrC;EACD;CAIH,MAAM,cAAc,UAAU;EAC5B;EACA,gBAAgB;EAChB,UAAU,MAAM,YAAY,EAAW;EACxC,CAAC;AAEF,QAAO;EACL,GAAG;EACH,iBAAiB,YAAY;EAC7B,UAAU,WAAW,KAAM,YAAY,YAAY;EACnD;EACD;;;;;;;;;;;;AAaH,SAAgB,sBACd,YACA,aACA,WACA;CACA,IAAI,MAAMA,WAAe,YAAY,YAAY;AACjD,KAAI,UAAW,OAAMA,WAAe,KAAK,UAAU;AAGnD,MAAK,MAAM,KAAK,KAAK;AACnB,MAAI,CAAC,EAAE,WAAW,KAAK,CAAE;EAEzB,MAAM,gBAAgB,cAAc;EACpC,MAAM,cAAc,YAAY;EAChC,MAAM,eAAe,aAAa;AAElC,MAAI,iBAAiB,eAAe,cAAc;GAChD,MAAM,aAAa,MACjB,OAAO,MAAM,aACR,IACD;AAEN,OAAI,KAAK,gBACP,UAAU,cAAc,EACxB,gBAAgB,UAAU,YAAY,EAAE,UAAU,aAAa,CAAC,CACjE;;;CAIL,MAAM,WAAW,YAAY;CAC7B,MAAM,UAAU,WAAW;CAC3B,MAAM,YAAY,aAAa;AAE/B,KAAI,MAAM,YAAY,UAAU,SAAS,UAAU;AAEnD,QAAO"}

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

@@ -0,0 +1,61 @@
+import { DefaultPreventable, KeyboardLikeEvent, PropagationStoppable } from "../utilities/event-types.js";
+
+//#region src/foundations/interactions/pressable.d.ts
+/**
+ * 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)
+ */
+interface PressableOptions {
+  disabled?: boolean;
+  onPress?: (e: PressEvent) => void;
+  /**
+   * Whether the host is a native button. Defaults to false.
+   */
+  isNativeButton?: boolean;
+}
+type PressEvent = DefaultPreventable & PropagationStoppable;
+interface PressableResult {
+  onClick: (e: PressEvent) => void;
+  disabled?: true;
+  role?: 'button';
+  tabIndex?: number;
+  onKeyDown?: (e: KeyboardLikeEvent) => void;
+  onKeyUp?: (e: KeyboardLikeEvent) => void;
+  'aria-disabled'?: 'true';
+}
+declare function pressable({
+  disabled,
+  onPress,
+  isNativeButton
+}: PressableOptions): PressableResult;
+//#endregion
+export { PressableOptions, PressableResult, pressable };
+//# sourceMappingURL=pressable.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pressable.d.ts","names":[],"sources":["../../../src/foundations/interactions/pressable.ts"],"mappings":";;;;;;AAiCA;;;;;;;;;;;AAakC;;;;;AAKlC;;;;;;;;;;;;;UAlBiB,gBAAA;EACf,QAAA;EACA,OAAA,IAAW,CAAA,EAAG,UAAA;EAqBD;;;EAjBb,cAAA;AAAA;AAAA,KAUG,UAAA,GAAa,kBAAA,GAAqB,oBAAA;AAAA,UAEtB,eAAA;EACf,OAAA,GAAU,CAAA,EAAG,UAAA;EACb,QAAA;EACA,IAAA;EACA,QAAA;EACA,SAAA,IAAa,CAAA,EAAG,iBAAA;EAChB,OAAA,IAAW,CAAA,EAAG,iBAAA;EACd,eAAA;AAAA;AAAA,iBAGc,SAAA,CAAA;EACd,QAAA;EACA,OAAA;EACA;AAAA,GACC,gBAAA,GAAmB,eAAA"}

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

@@ -0,0 +1,52 @@
+import { KeyboardLikeEvent } from "../utilities/event-types.js";
+
+//#region src/foundations/interactions/roving-focus.d.ts
+type Orientation = 'horizontal' | 'vertical' | 'both';
+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;
+}
+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;
+  };
+}
+declare function rovingFocus(options: RovingFocusOptions): RovingFocusResult;
+//#endregion
+export { Orientation, RovingFocusOptions, RovingFocusResult, rovingFocus };
+//# 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","names":[],"sources":["../../../src/foundations/interactions/roving-focus.ts"],"mappings":";;;KA8CY,WAAA;AAAA,UAEK,kBAAA;;;;EAIf,YAAA;;;;EAKA,SAAA;;;;;;;EAQA,WAAA,GAAc,WAAA;;;;EAKd,IAAA;;;;EAKA,UAAA,IAAc,KAAA;;;;EAKd,UAAA,IAAc,KAAA;AAAA;AAAA,UAGC,iBAAA;;;;EAIf,SAAA;IACE,SAAA,GAAY,CAAA,EAAG,iBAAA;EAAA;;;;EAMjB,IAAA,GAAO,KAAA;IACL,QAAA;IACA,mBAAA;EAAA;AAAA;AAAA,iBAIY,WAAA,CAAY,OAAA,EAAS,kBAAA,GAAqB,iBAAA"}

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

@@ -0,0 +1,71 @@
+//#region src/foundations/interactions/roving-focus.ts
+function rovingFocus(options) {
+	const { currentIndex, itemCount, orientation = "horizontal", loop = false, onNavigate, isDisabled } = options;
+	function findNextIndex(from, direction) {
+		let next = from + direction;
+		if (loop) {
+			if (next < 0) next = itemCount - 1;
+			if (next >= itemCount) next = 0;
+		} else if (next < 0 || next >= itemCount) return void 0;
+		if (isDisabled?.(next)) {
+			if (next === from) return void 0;
+			return findNextIndex(next, direction);
+		}
+		return next;
+	}
+	function handleKeyDown(e) {
+		const { key } = e;
+		let direction;
+		if (orientation === "horizontal" || orientation === "both") {
+			if (key === "ArrowRight") direction = 1;
+			if (key === "ArrowLeft") direction = -1;
+		}
+		if (orientation === "vertical" || orientation === "both") {
+			if (key === "ArrowDown") direction = 1;
+			if (key === "ArrowUp") direction = -1;
+		}
+		if (direction === void 0) return;
+		const nextIndex = findNextIndex(currentIndex, direction);
+		if (nextIndex === void 0) return;
+		e.preventDefault?.();
+		e.stopPropagation?.();
+		onNavigate?.(nextIndex);
+	}
+	return {
+		container: { onKeyDown: handleKeyDown },
+		item: (index) => ({
+			tabIndex: index === currentIndex ? 0 : -1,
+			"data-roving-index": index
+		})
+	};
+}
+/**
+* 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>
+*   );
+* }
+*/
+//#endregion
+export { rovingFocus };
+
+//# sourceMappingURL=roving-focus.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"roving-focus.js","names":[],"sources":["../../../src/foundations/interactions/roving-focus.ts"],"sourcesContent":["/**\n * rovingFocus\n *\n * Single tab stop navigation with arrow-key control.\n *\n * INVARIANTS:\n * 1. Only one item in the group is reachable via Tab (single tab stop)\n * 2. Arrow keys move focus within the group\n * 3. Orientation determines which arrow keys are active\n * 4. Looping is opt-in\n * 5. Disabled items are skipped\n * 6. Returns props objects, never factories (composes via mergeProps)\n *\n * DESIGN:\n * - Container gets onKeyDown for arrow navigation\n * - Each item gets tabIndex based on current selection\n * - Navigation logic is pure - caller controls focus application\n * - Disabled check happens per-item via predicate\n *\n * PIT OF SUCCESS:\n * ✓ Can't accidentally break tab order (tabIndex assigned correctly)\n * ✓ Can't duplicate navigation logic (single source)\n * ✓ Composes via mergeProps (all standard props)\n * ✓ Type-safe - invalid indices caught at call site\n *\n * USAGE:\n *   const nav = rovingFocus({\n *     currentIndex: 0,\n *     itemCount: 3,\n *     orientation: 'horizontal',\n *     onNavigate: setIndex\n *   });\n *\n *   <div {...nav.container}>\n *     <button {...nav.item(0)}>First</button>\n *     <button {...nav.item(1)}>Second</button>\n *   </div>\n *\n * MISUSE EXAMPLE (PREVENTED):\n *   ❌ Can't forget to set tabIndex - returned in item props\n *   ❌ Can't create conflicting arrow handlers - mergeProps composes\n *   ❌ Can't skip disabled items incorrectly - logic is internal\n */\n\nimport type { KeyboardLikeEvent } from '../utilities/event-types';\n\nexport type Orientation = 'horizontal' | 'vertical' | 'both';\n\nexport interface RovingFocusOptions {\n  /**\n   * Current focused index\n   */\n  currentIndex: number;\n\n  /**\n   * Total number of items\n   */\n  itemCount: number;\n\n  /**\n   * Navigation orientation\n   * - horizontal: ArrowLeft/ArrowRight\n   * - vertical: ArrowUp/ArrowDown\n   * - both: all arrow keys\n   */\n  orientation?: Orientation;\n\n  /**\n   * Whether to loop when reaching the end\n   */\n  loop?: boolean;\n\n  /**\n   * Callback when navigation occurs\n   */\n  onNavigate?: (index: number) => void;\n\n  /**\n   * Optional disabled state check per index\n   */\n  isDisabled?: (index: number) => boolean;\n}\n\nexport interface RovingFocusResult {\n  /**\n   * Props for the container element (composes via mergeProps)\n   */\n  container: {\n    onKeyDown: (e: KeyboardLikeEvent) => void;\n  };\n\n  /**\n   * Generate props for an item at the given index (composes via mergeProps)\n   */\n  item: (index: number) => {\n    tabIndex: number;\n    'data-roving-index': number;\n  };\n}\n\nexport function rovingFocus(options: RovingFocusOptions): RovingFocusResult {\n  const {\n    currentIndex,\n    itemCount,\n    orientation = 'horizontal',\n    loop = false,\n    onNavigate,\n    isDisabled,\n  } = options;\n\n  function findNextIndex(from: number, direction: 1 | -1): number | undefined {\n    let next = from + direction;\n\n    // Handle looping\n    if (loop) {\n      if (next < 0) next = itemCount - 1;\n      if (next >= itemCount) next = 0;\n    } else {\n      if (next < 0 || next >= itemCount) return undefined;\n    }\n\n    // Skip disabled items\n    if (isDisabled?.(next)) {\n      // Recursively find the next non-disabled item\n      if (next === from) return undefined; // Prevent infinite loop\n      return findNextIndex(next, direction);\n    }\n\n    return next;\n  }\n\n  function handleKeyDown(e: KeyboardLikeEvent) {\n    const { key } = e;\n\n    let direction: 1 | -1 | undefined;\n\n    if (orientation === 'horizontal' || orientation === 'both') {\n      if (key === 'ArrowRight') direction = 1;\n      if (key === 'ArrowLeft') direction = -1;\n    }\n\n    if (orientation === 'vertical' || orientation === 'both') {\n      if (key === 'ArrowDown') direction = 1;\n      if (key === 'ArrowUp') direction = -1;\n    }\n\n    if (direction === undefined) return;\n\n    const nextIndex = findNextIndex(currentIndex, direction);\n    if (nextIndex === undefined) return;\n\n    e.preventDefault?.();\n    e.stopPropagation?.();\n\n    onNavigate?.(nextIndex);\n  }\n\n  return {\n    container: {\n      onKeyDown: handleKeyDown,\n    },\n    item: (index: number) => ({\n      tabIndex: index === currentIndex ? 0 : -1,\n      'data-roving-index': index,\n    }),\n  };\n}\n\n/**\n * USAGE EXAMPLE:\n *\n * function Menu() {\n *   const [focusIndex, setFocusIndex] = state(0);\n *   const items = ['File', 'Edit', 'View'];\n *\n *   const navigation = rovingFocus({\n *     currentIndex: focusIndex(),\n *     itemCount: items.length,\n *     orientation: 'horizontal',\n *     loop: true,\n *     onNavigate: setFocusIndex,\n *   });\n *\n *   return (\n *     <div {...navigation.container}>\n *       {items.map((label, index) => (\n *         <button {...navigation.item(index)}>\n *           {label}\n *         </button>\n *       ))}\n *     </div>\n *   );\n * }\n */\n"],"mappings":";AAoGA,SAAgB,YAAY,SAAgD;CAC1E,MAAM,EACJ,cACA,WACA,cAAc,cACd,OAAO,OACP,YACA,eACE;CAEJ,SAAS,cAAc,MAAc,WAAuC;EAC1E,IAAI,OAAO,OAAO;AAGlB,MAAI,MAAM;AACR,OAAI,OAAO,EAAG,QAAO,YAAY;AACjC,OAAI,QAAQ,UAAW,QAAO;aAE1B,OAAO,KAAK,QAAQ,UAAW,QAAO;AAI5C,MAAI,aAAa,KAAK,EAAE;AAEtB,OAAI,SAAS,KAAM,QAAO;AAC1B,UAAO,cAAc,MAAM,UAAU;;AAGvC,SAAO;;CAGT,SAAS,cAAc,GAAsB;EAC3C,MAAM,EAAE,QAAQ;EAEhB,IAAI;AAEJ,MAAI,gBAAgB,gBAAgB,gBAAgB,QAAQ;AAC1D,OAAI,QAAQ,aAAc,aAAY;AACtC,OAAI,QAAQ,YAAa,aAAY;;AAGvC,MAAI,gBAAgB,cAAc,gBAAgB,QAAQ;AACxD,OAAI,QAAQ,YAAa,aAAY;AACrC,OAAI,QAAQ,UAAW,aAAY;;AAGrC,MAAI,cAAc,OAAW;EAE7B,MAAM,YAAY,cAAc,cAAc,UAAU;AACxD,MAAI,cAAc,OAAW;AAE7B,IAAE,kBAAkB;AACpB,IAAE,mBAAmB;AAErB,eAAa,UAAU;;AAGzB,QAAO;EACL,WAAW,EACT,WAAW,eACZ;EACD,OAAO,WAAmB;GACxB,UAAU,UAAU,eAAe,IAAI;GACvC,qBAAqB;GACtB;EACF"}

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

@@ -0,0 +1,34 @@
+import { State } from "../../runtime/state.js";
+
+//#region src/foundations/state/controllable.d.ts
+declare function isControlled<T>(value: T | undefined): value is T;
+declare function resolveControllable<T>(value: T | undefined, defaultValue: T): {
+  value: T;
+  isControlled: boolean;
+};
+declare function makeControllable<T>(options: {
+  value: T | undefined;
+  defaultValue: T;
+  onChange?: (next: T) => void;
+  setInternal?: (next: T) => void;
+}): {
+  set: (next: T) => void;
+  isControlled: boolean;
+};
+type ControllableState<T> = State<T> & {
+  isControlled: boolean;
+};
+/**
+ * controllableState
+ *
+ * Hook-like primitive that mirrors `state()` semantics while supporting
+ * controlled/uncontrolled behavior.
+ */
+declare function controllableState<T>(options: {
+  value: T | undefined;
+  defaultValue: T;
+  onChange?: (next: T) => void;
+}): ControllableState<T>;
+//#endregion
+export { ControllableState, controllableState, isControlled, makeControllable, resolveControllable };
+//# sourceMappingURL=controllable.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"controllable.d.ts","names":[],"sources":["../../../src/foundations/state/controllable.ts"],"mappings":";;;iBA0BgB,YAAA,GAAA,CAAgB,KAAA,EAAO,CAAA,eAAgB,KAAA,IAAS,CAAA;AAAA,iBAIhD,mBAAA,GAAA,CACd,KAAA,EAAO,CAAA,cACP,YAAA,EAAc,CAAA;EACX,KAAA,EAAO,CAAA;EAAG,YAAA;AAAA;AAAA,iBAQC,gBAAA,GAAA,CAAoB,OAAA;EAClC,KAAA,EAAO,CAAA;EACP,YAAA,EAAc,CAAA;EACd,QAAA,IAAY,IAAA,EAAM,CAAA;EAClB,WAAA,IAAe,IAAA,EAAM,CAAA;AAAA;cAKF,CAAA;;;KAYT,iBAAA,MAAuB,KAAA,CAAM,CAAA;EAAO,YAAA;AAAA;;;;;;;iBAQhC,iBAAA,GAAA,CAAqB,OAAA;EACnC,KAAA,EAAO,CAAA;EACP,YAAA,EAAc,CAAA;EACd,QAAA,IAAY,IAAA,EAAM,CAAA;AAAA,IAChB,iBAAA,CAAkB,CAAA"}

package/dist/foundations/state/controllable.js

@@ -0,0 +1,81 @@
+import { state } from "../../runtime/state.js";
+//#region src/foundations/state/controllable.ts
+/**
+* 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.
+*/
+function isControlled(value) {
+	return value !== void 0;
+}
+function resolveControllable(value, defaultValue) {
+	const controlled = isControlled(value);
+	return {
+		value: controlled ? value : defaultValue,
+		isControlled: controlled
+	};
+}
+function makeControllable(options) {
+	const { value, defaultValue, onChange, setInternal } = options;
+	const { isControlled } = resolveControllable(value, defaultValue);
+	function set(next) {
+		if (isControlled) onChange?.(next);
+		else {
+			setInternal?.(next);
+			onChange?.(next);
+		}
+	}
+	return {
+		set,
+		isControlled
+	};
+}
+/**
+* controllableState
+*
+* Hook-like primitive that mirrors `state()` semantics while supporting
+* controlled/uncontrolled behavior.
+*/
+function controllableState(options) {
+	const isControlled = options.value !== void 0;
+	const internal = isControlled ? null : state(options.defaultValue);
+	function read() {
+		if (isControlled) return options.value;
+		return internal();
+	}
+	read.set = (nextOrUpdater) => {
+		const prev = read();
+		const next = typeof nextOrUpdater === "function" ? nextOrUpdater(prev) : nextOrUpdater;
+		if (Object.is(prev, next)) return;
+		if (isControlled) {
+			options.onChange?.(next);
+			return;
+		}
+		internal.set(nextOrUpdater);
+		options.onChange?.(next);
+	};
+	read.isControlled = isControlled;
+	return read;
+}
+//#endregion
+export { controllableState, isControlled, makeControllable, resolveControllable };
+
+//# sourceMappingURL=controllable.js.map

package/dist/foundations/state/controllable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"controllable.js","names":[],"sources":["../../../src/foundations/state/controllable.ts"],"sourcesContent":["/**\n * controllable\n *\n * Small utilities for controlled vs uncontrolled components. These helpers are\n * intentionally minimal and do not manage state themselves; they help component\n * implementations make correct decisions about when to call `onChange` vs\n * update internal state.\n *\n * POLICY DECISIONS (LOCKED):\n *\n * 1. Controlled Detection\n *    A value is \"controlled\" if it is not `undefined`.\n *    This matches React conventions and is SSR-safe.\n *\n * 2. onChange Timing\n *    - Controlled mode: onChange called immediately, no internal update\n *    - Uncontrolled mode: internal state updated first, then onChange called\n *    This ensures onChange sees the new value in both modes.\n *\n * 3. Value Equality\n *    controllableState uses Object.is() to prevent unnecessary onChange calls.\n *    This is intentional — strict equality, no deep comparison.\n */\n\nimport { state, type State } from '../../runtime/state';\n\nexport function isControlled<T>(value: T | undefined): value is T {\n  return value !== undefined;\n}\n\nexport function resolveControllable<T>(\n  value: T | undefined,\n  defaultValue: T\n): { value: T; isControlled: boolean } {\n  const controlled = isControlled(value);\n  return {\n    value: controlled ? (value as T) : defaultValue,\n    isControlled: controlled,\n  };\n}\n\nexport function makeControllable<T>(options: {\n  value: T | undefined;\n  defaultValue: T;\n  onChange?: (next: T) => void;\n  setInternal?: (next: T) => void;\n}) {\n  const { value, defaultValue, onChange, setInternal } = options;\n  const { isControlled } = resolveControllable(value, defaultValue);\n\n  function set(next: T) {\n    if (isControlled) {\n      onChange?.(next);\n    } else {\n      setInternal?.(next);\n      onChange?.(next);\n    }\n  }\n\n  return { set, isControlled };\n}\n\nexport type ControllableState<T> = State<T> & { isControlled: boolean };\n\n/**\n * controllableState\n *\n * Hook-like primitive that mirrors `state()` semantics while supporting\n * controlled/uncontrolled behavior.\n */\nexport function controllableState<T>(options: {\n  value: T | undefined;\n  defaultValue: T;\n  onChange?: (next: T) => void;\n}): ControllableState<T> {\n  const isControlled = options.value !== undefined;\n  const internal = isControlled ? null : state<T>(options.defaultValue);\n\n  function read(): T {\n    if (isControlled) {\n      return options.value as T;\n    }\n\n    return internal!();\n  }\n\n  read.set = (nextOrUpdater: T | ((prev: T) => T)) => {\n    const prev = read();\n    const next =\n      typeof nextOrUpdater === 'function'\n        ? (nextOrUpdater as (p: T) => T)(prev)\n        : (nextOrUpdater as T);\n\n    if (Object.is(prev, next)) return;\n\n    if (isControlled) {\n      options.onChange?.(next);\n      return;\n    }\n\n    internal!.set(nextOrUpdater as never);\n    options.onChange?.(next);\n  };\n\n  (read as ControllableState<T>).isControlled = isControlled;\n  return read as ControllableState<T>;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AA0BA,SAAgB,aAAgB,OAAkC;AAChE,QAAO,UAAU;;AAGnB,SAAgB,oBACd,OACA,cACqC;CACrC,MAAM,aAAa,aAAa,MAAM;AACtC,QAAO;EACL,OAAO,aAAc,QAAc;EACnC,cAAc;EACf;;AAGH,SAAgB,iBAAoB,SAKjC;CACD,MAAM,EAAE,OAAO,cAAc,UAAU,gBAAgB;CACvD,MAAM,EAAE,iBAAiB,oBAAoB,OAAO,aAAa;CAEjE,SAAS,IAAI,MAAS;AACpB,MAAI,aACF,YAAW,KAAK;OACX;AACL,iBAAc,KAAK;AACnB,cAAW,KAAK;;;AAIpB,QAAO;EAAE;EAAK;EAAc;;;;;;;;AAW9B,SAAgB,kBAAqB,SAIZ;CACvB,MAAM,eAAe,QAAQ,UAAU;CACvC,MAAM,WAAW,eAAe,OAAO,MAAS,QAAQ,aAAa;CAErE,SAAS,OAAU;AACjB,MAAI,aACF,QAAO,QAAQ;AAGjB,SAAO,UAAW;;AAGpB,MAAK,OAAO,kBAAwC;EAClD,MAAM,OAAO,MAAM;EACnB,MAAM,OACJ,OAAO,kBAAkB,aACpB,cAA8B,KAAK,GACnC;AAEP,MAAI,OAAO,GAAG,MAAM,KAAK,CAAE;AAE3B,MAAI,cAAc;AAChB,WAAQ,WAAW,KAAK;AACxB;;AAGF,WAAU,IAAI,cAAuB;AACrC,UAAQ,WAAW,KAAK;;AAGzB,MAA8B,eAAe;AAC9C,QAAO"}

package/dist/foundations/utilities/aria.d.ts

@@ -0,0 +1,16 @@
+//#region src/foundations/utilities/aria.d.ts
+/**
+ * Tiny aria helpers
+ */
+declare function ariaDisabled(disabled?: boolean): {
+  'aria-disabled'?: 'true';
+};
+declare function ariaExpanded(expanded?: boolean): {
+  'aria-expanded'?: 'true' | 'false';
+};
+declare function ariaSelected(selected?: boolean): {
+  'aria-selected'?: 'true' | 'false';
+};
+//#endregion
+export { ariaDisabled, ariaExpanded, ariaSelected };
+//# sourceMappingURL=aria.d.ts.map

package/dist/foundations/utilities/aria.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aria.d.ts","names":[],"sources":["../../../src/foundations/utilities/aria.ts"],"mappings":";;AAIA;;iBAAgB,YAAA,CAAa,QAAA;EAAuB,eAAA;AAAA;AAAA,iBAIpC,YAAA,CAAa,QAAA;EAC3B,eAAA;AAAA;AAAA,iBAOc,YAAA,CAAa,QAAA;EAC3B,eAAA;AAAA"}

package/dist/foundations/utilities/aria.js

@@ -5,7 +5,13 @@
 function ariaDisabled(disabled) {
 	return disabled ? { "aria-disabled": "true" } : {};
 }
+function ariaExpanded(expanded) {
+	return expanded === void 0 ? {} : { "aria-expanded": String(expanded) };
+}
+function ariaSelected(selected) {
+	return selected === void 0 ? {} : { "aria-selected": String(selected) };
+}
 //#endregion
-export { ariaDisabled };
+export { ariaDisabled, ariaExpanded, ariaSelected };
 
 //# sourceMappingURL=aria.js.map

package/dist/foundations/utilities/aria.js.map

@@ -1 +1 @@
-{"version":3,"file":"aria.js","names":[],"sources":["../../../src/foundations/utilities/aria.ts"],"sourcesContent":["/**\n * Tiny aria helpers\n */\n\nexport function ariaDisabled(disabled?: boolean): { 'aria-disabled'?: 'true' } {\n  return disabled ? { 'aria-disabled': 'true' } : {};\n}\n\nexport function ariaExpanded(expanded?: boolean): {\n  'aria-expanded'?: 'true' | 'false';\n} {\n  return expanded === undefined\n    ? {}\n    : { 'aria-expanded': String(expanded) as 'true' | 'false' };\n}\n\nexport function ariaSelected(selected?: boolean): {\n  'aria-selected'?: 'true' | 'false';\n} {\n  return selected === undefined\n    ? {}\n    : { 'aria-selected': String(selected) as 'true' | 'false' };\n}\n"],"mappings":";;;;AAIA,SAAgB,aAAa,UAAkD;AAC7E,QAAO,WAAW,EAAE,iBAAiB,QAAQ,GAAG,EAAE"}
+{"version":3,"file":"aria.js","names":[],"sources":["../../../src/foundations/utilities/aria.ts"],"sourcesContent":["/**\n * Tiny aria helpers\n */\n\nexport function ariaDisabled(disabled?: boolean): { 'aria-disabled'?: 'true' } {\n  return disabled ? { 'aria-disabled': 'true' } : {};\n}\n\nexport function ariaExpanded(expanded?: boolean): {\n  'aria-expanded'?: 'true' | 'false';\n} {\n  return expanded === undefined\n    ? {}\n    : { 'aria-expanded': String(expanded) as 'true' | 'false' };\n}\n\nexport function ariaSelected(selected?: boolean): {\n  'aria-selected'?: 'true' | 'false';\n} {\n  return selected === undefined\n    ? {}\n    : { 'aria-selected': String(selected) as 'true' | 'false' };\n}\n"],"mappings":";;;;AAIA,SAAgB,aAAa,UAAkD;AAC7E,QAAO,WAAW,EAAE,iBAAiB,QAAQ,GAAG,EAAE;;AAGpD,SAAgB,aAAa,UAE3B;AACA,QAAO,aAAa,SAChB,EAAE,GACF,EAAE,iBAAiB,OAAO,SAAS,EAAsB;;AAG/D,SAAgB,aAAa,UAE3B;AACA,QAAO,aAAa,SAChB,EAAE,GACF,EAAE,iBAAiB,OAAO,SAAS,EAAsB"}

package/dist/foundations/utilities/compose-handlers.d.ts

@@ -0,0 +1,37 @@
+//#region src/foundations/utilities/compose-handlers.d.ts
+/**
+ * composeHandlers
+ *
+ * Compose two event handlers into one. The first handler runs, and unless it
+ * calls `event.preventDefault()` (or sets `defaultPrevented`), the second
+ * handler runs. This prevents accidental clobbering of child handlers when
+ * injecting props.
+ *
+ * POLICY DECISIONS (LOCKED):
+ *
+ * 1. Execution Order
+ *    First handler runs before second (injected before base).
+ *    This allows injected handlers to prevent default behavior.
+ *
+ * 2. Default Prevention Check
+ *    By default, checks `defaultPrevented` on first argument.
+ *    Can be disabled via options.checkDefaultPrevented = false.
+ *
+ * 3. Undefined Handler Support
+ *    Undefined handlers are skipped (no-op). This simplifies usage
+ *    where handlers are optional.
+ *
+ * 4. Type Safety
+ *    Args are readonly to prevent mutation. Return type matches input.
+ */
+interface ComposeHandlersOptions {
+  /**
+   * When true (default), do not run the second handler if the first prevented default.
+   * When false, always run both handlers.
+   */
+  checkDefaultPrevented?: boolean;
+}
+declare function composeHandlers<A extends readonly unknown[]>(first?: (...args: A) => void, second?: (...args: A) => void, options?: ComposeHandlersOptions): (...args: A) => void;
+//#endregion
+export { ComposeHandlersOptions, composeHandlers };
+//# sourceMappingURL=compose-handlers.d.ts.map

package/dist/foundations/utilities/compose-handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose-handlers.d.ts","names":[],"sources":["../../../src/foundations/utilities/compose-handlers.ts"],"mappings":";;AA0BA;;;;;AAmBA;;;;;;;;;;;;;;;;;;;UAnBiB,sBAAA;EAuBH;;;;EAlBZ,qBAAA;AAAA;AAAA,iBAcc,eAAA,8BAAA,CACd,KAAA,OAAY,IAAA,EAAM,CAAA,WAClB,MAAA,OAAa,IAAA,EAAM,CAAA,WACnB,OAAA,GAAU,sBAAA,OACL,IAAA,EAAM,CAAA"}

package/dist/foundations/utilities/compose-ref.d.ts

@@ -23,5 +23,5 @@ type Ref<T> = ((value: T | null) => void) | {
 declare function setRef<T>(ref: Ref<T>, value: T | null): void;
 declare function composeRefs<T>(...refs: Array<Ref<T>>): (value: T | null) => void;
 //#endregion
-export { Ref };
+export { Ref, composeRefs, setRef };
 //# sourceMappingURL=compose-ref.d.ts.map

package/dist/foundations/utilities/compose-ref.js

@@ -13,6 +13,6 @@ function composeRefs(...refs) {
 	};
 }
 //#endregion
-export { composeRefs };
+export { composeRefs, setRef };
 
 //# sourceMappingURL=compose-ref.js.map

package/dist/foundations/utilities/event-types.d.ts

@@ -0,0 +1,20 @@
+//#region src/foundations/utilities/event-types.d.ts
+interface DefaultPreventable {
+  defaultPrevented?: boolean;
+  preventDefault?: () => void;
+}
+interface PropagationStoppable {
+  stopPropagation?: () => void;
+}
+interface KeyboardLikeEvent extends DefaultPreventable, PropagationStoppable {
+  key: string;
+}
+interface PointerLikeEvent extends DefaultPreventable, PropagationStoppable {
+  target?: unknown;
+}
+interface FocusLikeEvent extends DefaultPreventable, PropagationStoppable {
+  relatedTarget?: unknown;
+}
+//#endregion
+export { DefaultPreventable, FocusLikeEvent, KeyboardLikeEvent, PointerLikeEvent, PropagationStoppable };
+//# sourceMappingURL=event-types.d.ts.map

package/dist/foundations/utilities/event-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-types.d.ts","names":[],"sources":["../../../src/foundations/utilities/event-types.ts"],"mappings":";UAAiB,kBAAA;EACf,gBAAA;EACA,cAAA;AAAA;AAAA,UAGe,oBAAA;EACf,eAAA;AAAA;AAAA,UAGe,iBAAA,SACP,kBAAA,EAAoB,oBAAA;EAC5B,GAAA;AAAA;AAAA,UAGe,gBAAA,SACP,kBAAA,EAAoB,oBAAA;EAC5B,MAAA;AAAA;AAAA,UAGe,cAAA,SACP,kBAAA,EAAoB,oBAAA;EAC5B,aAAA;AAAA"}

package/dist/foundations/utilities/merge-props.d.ts

@@ -0,0 +1,5 @@
+//#region src/foundations/utilities/merge-props.d.ts
+declare function mergeProps<TBase extends object, TInjected extends object>(base: TBase, injected: TInjected): TInjected & TBase;
+//#endregion
+export { mergeProps };
+//# sourceMappingURL=merge-props.d.ts.map

package/dist/foundations/utilities/merge-props.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-props.d.ts","names":[],"sources":["../../../src/foundations/utilities/merge-props.ts"],"mappings":";iBAiCgB,UAAA,gDAAA,CACd,IAAA,EAAM,KAAA,EACN,QAAA,EAAU,SAAA,GACT,SAAA,GAAY,KAAA"}

package/dist/foundations/utilities/use-id.d.ts

@@ -0,0 +1,32 @@
+//#region src/foundations/utilities/use-id.d.ts
+interface FormatIdOptions {
+  /** Defaults to 'askr' */
+  prefix?: string;
+  /** Stable, caller-provided identity */
+  id: string | number;
+}
+/**
+ * formatId
+ *
+ * Formats a stable ID from a caller-provided identity.
+ * - Pure and deterministic (no time/randomness/global counters)
+ * - SSR-safe
+ *
+ * POLICY DECISIONS (LOCKED):
+ *
+ * 1. No Auto-Generation
+ *    Caller must provide the `id`. No random/sequential generation.
+ *    This ensures determinism and SSR safety.
+ *
+ * 2. Format Convention
+ *    IDs are formatted as `{prefix}-{id}`.
+ *    Default prefix is "askr".
+ *
+ * 3. Type Coercion
+ *    Numbers are coerced to strings via String().
+ *    This is deterministic and consistent.
+ */
+declare function formatId(options: FormatIdOptions): string;
+//#endregion
+export { FormatIdOptions, formatId };
+//# sourceMappingURL=use-id.d.ts.map

package/dist/foundations/utilities/use-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-id.d.ts","names":[],"sources":["../../../src/foundations/utilities/use-id.ts"],"mappings":";UAAiB,eAAA;EAAA;EAEf,MAAA;;EAEA,EAAA;AAAA;AAwBF;;;;;;;;;;;;;;;;;;;;;AAAA,iBAAgB,QAAA,CAAS,OAAA,EAAS,eAAA"}

package/dist/foundations/utilities/use-id.js

@@ -0,0 +1,29 @@
+//#region src/foundations/utilities/use-id.ts
+/**
+* formatId
+*
+* Formats a stable ID from a caller-provided identity.
+* - Pure and deterministic (no time/randomness/global counters)
+* - SSR-safe
+*
+* POLICY DECISIONS (LOCKED):
+*
+* 1. No Auto-Generation
+*    Caller must provide the `id`. No random/sequential generation.
+*    This ensures determinism and SSR safety.
+*
+* 2. Format Convention
+*    IDs are formatted as `{prefix}-{id}`.
+*    Default prefix is "askr".
+*
+* 3. Type Coercion
+*    Numbers are coerced to strings via String().
+*    This is deterministic and consistent.
+*/
+function formatId(options) {
+	return `${options.prefix ?? "askr"}-${String(options.id)}`;
+}
+//#endregion
+export { formatId };
+
+//# sourceMappingURL=use-id.js.map

package/dist/foundations/utilities/use-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-id.js","names":[],"sources":["../../../src/foundations/utilities/use-id.ts"],"sourcesContent":["export interface FormatIdOptions {\n  /** Defaults to 'askr' */\n  prefix?: string;\n  /** Stable, caller-provided identity */\n  id: string | number;\n}\n\n/**\n * formatId\n *\n * Formats a stable ID from a caller-provided identity.\n * - Pure and deterministic (no time/randomness/global counters)\n * - SSR-safe\n *\n * POLICY DECISIONS (LOCKED):\n *\n * 1. No Auto-Generation\n *    Caller must provide the `id`. No random/sequential generation.\n *    This ensures determinism and SSR safety.\n *\n * 2. Format Convention\n *    IDs are formatted as `{prefix}-{id}`.\n *    Default prefix is \"askr\".\n *\n * 3. Type Coercion\n *    Numbers are coerced to strings via String().\n *    This is deterministic and consistent.\n */\nexport function formatId(options: FormatIdOptions): string {\n  const prefix = options.prefix ?? 'askr';\n  return `${prefix}-${String(options.id)}`;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AA4BA,SAAgB,SAAS,SAAkC;AAEzD,QAAO,GADQ,QAAQ,UAAU,OAChB,GAAG,OAAO,QAAQ,GAAG"}

package/dist/index.d.ts

@@ -9,9 +9,9 @@ import { HistoryScrollBehavior, NavigateOptions, NavigationScrollBehavior, Scrol
 import { HydrateSPAConfig, IslandConfig, IslandsConfig, SPAConfig, cleanupApp, createIsland, createIslands, createSPA, hasApp, hydrateSPA } from "./boot/index.js";
 import { Show, ShowProps } from "./control/show.js";
 import { Case, CaseProps, Match, MatchProps } from "./control/case.js";
+import { jsx, jsxs } from "./jsx-runtime.js";
 import { Slot, SlotProps } from "./foundations/structures/slot.js";
 import { DefaultPortal, Portal, PortalProps, definePortal } from "./foundations/structures/portal.js";
-import { jsx, jsxs } from "./jsx-runtime.js";
 import { Derived, derive } from "./runtime/derive.js";
 import { Selector, selector } from "./runtime/selector.js";
 import { ResourceResult, resource } from "./runtime/operations.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askrjs/askr",
-  "version": "0.0.29",
+  "version": "0.0.30",
   "description": "Actor-backed deterministic UI framework",
   "keywords": [
     "askr",
@@ -100,7 +100,7 @@
     "@axe-core/playwright": "^4.11.2",
     "@playwright/test": "^1.59.1",
     "@types/node": "^25.6.0",
-    "jsdom": "^29.1.0",
+    "jsdom": "^29.1.1",
     "playwright": "^1.59.1",
     "tsd": "^0.33.0",
     "typescript": "^6.0.3",