@askrjs/askr 0.0.8 → 0.0.9

package/dist/foundations/index.d.ts

@@ -94,6 +94,133 @@ interface Portal<T = unknown> {
 declare function definePortal<T = unknown>(): Portal<T>;
 declare const DefaultPortal: Portal<unknown>;
 
+/**
+ * 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();
+ */
+type CollectionItem<TNode, TMetadata = unknown> = {
+    node: TNode;
+    metadata: TMetadata;
+};
+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;
+}
+declare function createCollection<TNode, TMetadata = unknown>(): Collection<TNode, TMetadata>;
+
+/**
+ * createLayer
+ *
+ * Manages stacking order and coordination for overlays (modals, popovers, etc).
+ *
+ * INVARIANTS:
+ * 1. Layers are ordered by registration time (FIFO)
+ * 2. Only the top layer handles Escape key
+ * 3. Only the top layer handles outside pointer events
+ * 4. Nested layers are supported
+ * 5. Does not implement portals (orthogonal concern)
+ * 6. No automatic DOM insertion (caller controls mounting)
+ *
+ * DESIGN:
+ * - Returns a layer manager with register/unregister API
+ * - Each layer has a unique ID and can query if it's the top layer
+ * - Escape and outside pointer coordination via callbacks
+ * - No z-index management (CSS concern)
+ *
+ * USAGE:
+ *   const manager = createLayer();
+ *
+ *   const layer = manager.register({
+ *     onEscape: () => { ... },
+ *     onOutsidePointer: () => { ... }
+ *   });
+ *
+ *   layer.isTop(); // true if this is the topmost layer
+ *   layer.unregister();
+ */
+interface LayerOptions {
+    /**
+     * Called when Escape is pressed and this is the top layer
+     */
+    onEscape?: () => void;
+    /**
+     * Called when pointer event occurs outside and this is the top layer
+     */
+    onOutsidePointer?: (e: PointerEvent) => void;
+    /**
+     * Optional node reference for outside pointer detection
+     */
+    node?: Node | null;
+}
+interface Layer {
+    /**
+     * Unique layer ID
+     */
+    id: number;
+    /**
+     * Check if this layer is the topmost
+     */
+    isTop(): boolean;
+    /**
+     * Remove this layer from the stack
+     */
+    unregister(): void;
+}
+interface LayerManager {
+    /**
+     * Register a new layer
+     */
+    register(options: LayerOptions): Layer;
+    /**
+     * Get all active layers in order
+     */
+    layers(): ReadonlyArray<Layer>;
+    /**
+     * Manually trigger escape handling on the top layer
+     */
+    handleEscape(): void;
+    /**
+     * Manually trigger outside pointer handling on the top layer
+     */
+    handleOutsidePointer(e: PointerEvent): void;
+}
+declare function createLayer(): LayerManager;
+
 /**
  * composeHandlers
  *
@@ -319,22 +446,59 @@ declare function pressable({ disabled, onPress, isNativeButton, }: PressableOpti
 /**
  * dismissable
  *
- * Provides props and helpers to support dismissal behaviour. This helper is
- * runtime-agnostic:
- * - It returns `onKeyDown` prop which will call onDismiss when Escape is
- *   pressed.
- * - It also provides `outsideListener` factory which given an `isInside`
- *   predicate returns a handler suitable to attach at the document level that
- *   will call onDismiss when the pointerdown target is outside the component.
+ * 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 {
-    onDismiss?: () => void;
+    /**
+     * 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({ onDismiss, disabled }: DismissableOptions): {
-    onKeyDown: ((e: KeyboardLikeEvent) => void) | undefined;
-    outsideListener: ((isInside: (target: unknown) => boolean) => (e: PointerLikeEvent) => void) | undefined;
+declare function dismissable({ node, disabled, onDismiss, }: DismissableOptions): {
+    onKeyDown: (e: KeyboardLikeEvent) => void;
+    onPointerDownCapture: (e: PointerLikeEvent) => void;
 };
 
 /**
@@ -371,4 +535,190 @@ interface HoverableResult {
 }
 declare function hoverable({ disabled, onEnter, onLeave, }: HoverableOptions): HoverableResult;
 
-export { type ComposeHandlersOptions, type ControllableState, DefaultPortal, type DismissableOptions, type FocusableOptions, type FocusableResult, type HoverableOptions, type HoverableResult, JSXElement, type Portal, Presence, type PresenceProps, type PressableOptions, type PressableResult, type Ref, Slot, type SlotProps, ariaDisabled, ariaExpanded, ariaSelected, composeHandlers, composeRefs, controllableState, definePortal, dismissable, focusable, hoverable, isControlled, makeControllable, mergeProps, pressable, resolveControllable, setRef, useId };
+/**
+ * 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
+ */
+
+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;
+
+/**
+ * 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
+ */
+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?: any;
+}
+/**
+ * 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: any;
+} | {
+    'aria-disabled': true | undefined;
+    tabIndex: number;
+    ref: any;
+    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, any>, policyProps: Record<string, any>, userProps?: Record<string, any>): Record<string, any>;
+
+export { type Collection, type CollectionItem, type ComposeHandlersOptions, type ControllableState, DefaultPortal, type DismissableOptions, type FocusableOptions, type FocusableResult, type HoverableOptions, type HoverableResult, type InteractionPolicyInput, JSXElement, type Layer, type LayerManager, type LayerOptions, type Orientation, type Portal, Presence, type PresenceProps, type PressableOptions, type PressableResult, type Ref, type RovingFocusOptions, type RovingFocusResult, Slot, type SlotProps, applyInteractionPolicy, ariaDisabled, ariaExpanded, ariaSelected, composeHandlers, composeRefs, controllableState, createCollection, createLayer, definePortal, dismissable, focusable, hoverable, isControlled, makeControllable, mergeInteractionProps, mergeProps, pressable, resolveControllable, rovingFocus, setRef, useId };

package/dist/foundations/index.js

@@ -98,7 +98,95 @@ var DefaultPortal = (() => {
   return Host;
 })();
 
-// src/foundations/utilities/composeHandlers.ts
+// src/foundations/structures/collection.ts
+function createCollection() {
+  const registry = /* @__PURE__ */ new Map();
+  function register(node, metadata) {
+    const item = { node, metadata };
+    registry.set(node, item);
+    return () => {
+      registry.delete(node);
+    };
+  }
+  function items() {
+    return Array.from(registry.values());
+  }
+  function clear() {
+    registry.clear();
+  }
+  function size() {
+    return registry.size;
+  }
+  return {
+    register,
+    items,
+    clear,
+    size
+  };
+}
+
+// src/foundations/structures/layer.ts
+function createLayer() {
+  const stack = [];
+  let nextId = 1;
+  function register(options) {
+    const id = nextId++;
+    const entry = { id, options };
+    stack.push(entry);
+    function isTop() {
+      return stack[stack.length - 1]?.id === id;
+    }
+    function unregister() {
+      const index = stack.findIndex((e) => e.id === id);
+      if (index !== -1) {
+        stack.splice(index, 1);
+      }
+    }
+    return {
+      id,
+      isTop,
+      unregister
+    };
+  }
+  function layers() {
+    return stack.map((entry) => ({
+      id: entry.id,
+      isTop: () => stack[stack.length - 1]?.id === entry.id,
+      unregister: () => {
+        const index = stack.findIndex((e) => e.id === entry.id);
+        if (index !== -1) {
+          stack.splice(index, 1);
+        }
+      }
+    }));
+  }
+  function handleEscape() {
+    const top = stack[stack.length - 1];
+    if (top) {
+      top.options.onEscape?.();
+    }
+  }
+  function handleOutsidePointer(e) {
+    const top = stack[stack.length - 1];
+    if (!top) return;
+    const node = top.options.node;
+    if (node && e.target instanceof Node) {
+      if (!node.contains(e.target)) {
+        top.options.onOutsidePointer?.(e);
+      }
+    } else {
+      top.options.onOutsidePointer?.(e);
+    }
+  }
+  return {
+    register,
+    layers,
+    handleEscape,
+    handleOutsidePointer
+  };
+}
+
+// src/foundations/utilities/compose-handlers.ts
 function isDefaultPrevented(value) {
   return typeof value === "object" && value !== null && "defaultPrevented" in value && value.defaultPrevented === true;
 }
@@ -120,7 +208,7 @@ function composeHandlers(first, second, options) {
 function noop() {
 }
 
-// src/foundations/utilities/mergeProps.ts
+// src/foundations/utilities/merge-props.ts
 function isEventHandlerKey(key) {
   return key.startsWith("on");
 }
@@ -156,7 +244,7 @@ function ariaSelected(selected) {
   return selected === void 0 ? {} : { "aria-selected": String(selected) };
 }
 
-// src/foundations/utilities/composeRef.ts
+// src/foundations/utilities/compose-ref.ts
 function setRef(ref, value) {
   if (!ref) return;
   if (typeof ref === "function") {
@@ -174,7 +262,7 @@ function composeRefs(...refs) {
   };
 }
 
-// src/foundations/utilities/useId.ts
+// src/foundations/utilities/use-id.ts
 function useId(options) {
   const prefix = options.prefix ?? "askr";
   return `${prefix}-${String(options.id)}`;
@@ -1020,24 +1108,32 @@ function pressable({
 }
 
 // src/foundations/interactions/dismissable.ts
-function dismissable({ onDismiss, disabled }) {
-  return {
-    // Prop for the component root to handle Escape
-    onKeyDown: disabled ? void 0 : (e) => {
-      if (e.key === "Escape") {
-        e.preventDefault?.();
-        e.stopPropagation?.();
-        onDismiss?.();
-      }
-    },
-    // Factory: runtime should attach this listener at the appropriate scope.
-    outsideListener: disabled ? void 0 : (isInside) => (e) => {
-      if (!isInside(e.target)) {
-        e.preventDefault?.();
-        e.stopPropagation?.();
-        onDismiss?.();
-      }
+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,
+    // Use capture phase to catch events before they bubble
+    onPointerDownCapture: handlePointerDownCapture
   };
 }
 
@@ -1068,6 +1164,111 @@ function hoverable({
   };
 }
 
-export { DefaultPortal, Presence, Slot, ariaDisabled, ariaExpanded, ariaSelected, composeHandlers, composeRefs, controllableState, definePortal, dismissable, focusable, hoverable, isControlled, layout, makeControllable, mergeProps, pressable, resolveControllable, setRef, useId };
+// 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
+    })
+  };
+}
+
+// src/foundations/interactions/interaction-policy.ts
+function applyInteractionPolicy({
+  isNative,
+  disabled,
+  onPress,
+  ref
+}) {
+  function invokePress(e) {
+    if (disabled) {
+      e.preventDefault?.();
+      return;
+    }
+    onPress?.(e);
+  }
+  if (isNative) {
+    return {
+      disabled: disabled || void 0,
+      onClick: (e) => invokePress(e),
+      ref
+    };
+  }
+  const interaction = pressable({
+    disabled,
+    isNativeButton: false,
+    onPress: (e) => invokePress(e)
+  });
+  return {
+    ...interaction,
+    "aria-disabled": disabled || void 0,
+    tabIndex: disabled ? -1 : interaction.tabIndex ?? 0,
+    ref
+  };
+}
+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) {
+      out[k] = composeHandlers(
+        policyHandler,
+        composeHandlers(userHandler, childHandler)
+      );
+    }
+  }
+  out.ref = composeRefs(childProps?.ref, userProps?.ref, policyProps?.ref);
+  return out;
+}
+
+export { DefaultPortal, Presence, Slot, applyInteractionPolicy, ariaDisabled, ariaExpanded, ariaSelected, composeHandlers, composeRefs, controllableState, createCollection, createLayer, definePortal, dismissable, focusable, hoverable, isControlled, layout, makeControllable, mergeInteractionProps, mergeProps, pressable, resolveControllable, rovingFocus, setRef, useId };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map