@askrjs/askr 0.0.9 → 0.0.10

package/dist/foundations/core.d.ts

@@ -0,0 +1,449 @@
+import { S as State } from '../component-mtwBWhUr.js';
+import '../jsx-CSWf4VFg.js';
+
+/**
+ * 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;
+
+declare function mergeProps<TBase extends object, TInjected extends object>(base: TBase, injected: TInjected): TInjected & TBase;
+
+/**
+ * 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';
+};
+
+/**
+ * Ref composition utilities
+ *
+ * POLICY DECISIONS (LOCKED):
+ *
+ * 1. Ref Types Supported
+ *    - Callback refs: (value: T | null) => void
+ *    - Object refs: { current: T | null }
+ *    - null/undefined (no-op)
+ *
+ * 2. Write Failure Handling
+ *    setRef catches write failures (readonly refs) and ignores them.
+ *    This is intentional — refs may be readonly in some contexts.
+ *
+ * 3. Composition Order
+ *    composeRefs applies refs in array order (left to right).
+ *    All refs are called even if one fails.
+ */
+type Ref<T> = ((value: T | null) => void) | {
+    current: T | null;
+} | null | undefined;
+declare function setRef<T>(ref: Ref<T>, value: T | null): void;
+declare function composeRefs<T>(...refs: Array<Ref<T>>): (value: T | null) => void;
+
+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;
+
+interface DefaultPreventable {
+    defaultPrevented?: boolean;
+    preventDefault?: () => void;
+}
+interface PropagationStoppable {
+    stopPropagation?: () => void;
+}
+interface KeyboardLikeEvent extends DefaultPreventable, PropagationStoppable {
+    key: string;
+}
+interface PointerLikeEvent extends DefaultPreventable, PropagationStoppable {
+    target?: unknown;
+}
+
+/**
+ * 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;
+
+/**
+ * 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;
+};
+
+/**
+ * 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;
+
+/**
+ * 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;
+
+/**
+ * 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;
+
+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>;
+
+/**
+ * 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.
+ */
+
+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>;
+
+export { type ComposeHandlersOptions, type ControllableState, type DismissableOptions, type FocusableOptions, type FocusableResult, type FormatIdOptions, type HoverableOptions, type HoverableResult, type InteractionPolicyInput, type Orientation, type PressableOptions, type PressableResult, type Ref, type RovingFocusOptions, type RovingFocusResult, applyInteractionPolicy, ariaDisabled, ariaExpanded, ariaSelected, composeHandlers, composeRefs, controllableState, dismissable, focusable, formatId, hoverable, isControlled, makeControllable, mergeInteractionProps, mergeProps, pressable, resolveControllable, rovingFocus, setRef };

package/dist/foundations/core.js

@@ -0,0 +1 @@
+export{i as controllableState,b as dismissable,c as focusable,a as formatId,d as hoverable,f as isControlled,h as makeControllable,g as resolveControllable,e as rovingFocus}from'../chunk-Q7GRUZHR.js';import'../chunk-LOSY3JCR.js';export{i as applyInteractionPolicy,c as ariaDisabled,d as ariaExpanded,e as ariaSelected,a as composeHandlers,g as composeRefs,j as mergeInteractionProps,b as mergeProps,h as pressable,f as setRef}from'../chunk-DPHQ4JD6.js';import'../chunk-534P7OMI.js';import'../chunk-JJDSOK6C.js';import'../chunk-OQMK7H2R.js';import'../chunk-37RC6ZT3.js';import'../chunk-62D2TNHX.js';