@askrjs/askr 0.0.6 → 0.0.7

package/dist/foundations/index.d.ts

@@ -1,6 +1,7 @@
-export { L as LayoutComponent, l as layout } from '../layout-D5MqtW_q.js';
+export { L as LayoutComponent, l as layout } from '../layout-BINPv-nz.js';
 import '../types-uOPfcrdz.js';
 import { J as JSXElement } from '../jsx-AzPM8gMS.js';
+import { S as State } from '../component-BBGWJdqJ.js';
 
 type SlotProps = {
     asChild: true;
@@ -10,13 +11,76 @@ type SlotProps = {
     asChild?: false;
     children?: unknown;
 };
+/**
+ * Slot
+ *
+ * Structural primitive for prop forwarding patterns.
+ *
+ * POLICY DECISIONS (LOCKED):
+ *
+ * 1. asChild Pattern
+ *    When asChild=true, merges props into the single child element.
+ *    Child must be a valid JSXElement; non-element children return null.
+ *
+ * 2. Fallback Behavior
+ *    When asChild=false, returns a Fragment (structural no-op).
+ *    No DOM element is introduced.
+ *
+ * 3. Type Safety
+ *    asChild=true requires exactly one JSXElement child (enforced by type).
+ *    Runtime validates with isElement() check.
+ */
 declare function Slot(props: SlotProps): JSXElement | null;
 
+interface PresenceProps {
+    present: boolean | (() => boolean);
+    children?: unknown;
+}
+/**
+ * Presence
+ *
+ * Structural policy primitive for conditional mount/unmount.
+ * - No timers
+ * - No animation coupling
+ * - No DOM side-effects
+ *
+ * POLICY DECISIONS (LOCKED):
+ *
+ * 1. Present as Function
+ *    Accepts boolean OR function to support lazy evaluation patterns.
+ *    Function is called once per render. Use boolean form for static values.
+ *
+ * 2. Children Type
+ *    `children` is intentionally `unknown` to remain runtime-agnostic.
+ *    The runtime owns child normalization and validation.
+ *
+ * 3. Immediate Mount/Unmount
+ *    No exit animations or transitions. When `present` becomes false,
+ *    children are removed immediately. Animation must be layered above
+ *    this primitive.
+ */
+declare function Presence({ present, children, }: PresenceProps): JSXElement | null;
+
 /**
  * Portal / Host primitive.
  *
- * A portal is a named render slot within the existing tree.
- * It does NOT create a second tree or touch the DOM directly.
+ * Foundations remain runtime-agnostic: a portal is an explicit read/write slot.
+ * Scheduling and attachment are owned by the runtime when `createPortalSlot`
+ * exists; otherwise this falls back to a local slot (deterministic, but does
+ * not schedule updates).
+ *
+ * POLICY DECISIONS (LOCKED):
+ *
+ * 1. Local Mutable State
+ *    Foundations may use local mutable state ONLY to model deterministic slots,
+ *    never to coordinate timing, effects, or ordering. The fallback mode uses
+ *    closure-local `mounted` and `value` variables which are non-escaping and
+ *    deterministic.
+ *
+ * 2. Return Type Philosophy
+ *    Portal call signatures return `unknown` (intentionally opaque). The runtime
+ *    owns the concrete type. This prevents foundations from assuming JSX.Element
+ *    or DOM node types, maintaining runtime-agnostic portability.
  */
 interface Portal<T = unknown> {
     /** Mount point — rendered exactly once */
@@ -29,4 +93,281 @@ interface Portal<T = unknown> {
 declare function definePortal<T = unknown>(): Portal<T>;
 declare const DefaultPortal: Portal<unknown>;
 
-export { DefaultPortal, JSXElement, type Portal, Slot, type SlotProps, definePortal };
+/**
+ * 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 UseIdOptions {
+    /** Defaults to 'askr' */
+    prefix?: string;
+    /** Stable, caller-provided identity */
+    id: string | number;
+}
+/**
+ * useId
+ *
+ * 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 useId(options: UseIdOptions): string;
+
+/**
+ * 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>;
+
+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
+ *
+ * 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.
+ */
+interface DismissableOptions {
+    onDismiss?: () => void;
+    disabled?: boolean;
+}
+
+declare function dismissable({ onDismiss, disabled }: DismissableOptions): {
+    onKeyDown: ((e: KeyboardLikeEvent) => void) | undefined;
+    outsideListener: ((isInside: (target: unknown) => boolean) => (e: PointerLikeEvent) => void) | undefined;
+};
+
+/**
+ * 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;
+
+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 };