@askrjs/askr 0.0.5 → 0.0.7

package/dist/component-BBGWJdqJ.d.ts

@@ -0,0 +1,177 @@
+import { P as Props, J as JSXElement } from './jsx-AzPM8gMS.js';
+
+/**
+ * State primitive for Askr components
+ * Optimized for minimal overhead and fast updates
+ *
+ * INVARIANTS ENFORCED:
+ * - state() only callable during component render (currentInstance exists)
+ * - state() called at top-level only (indices must be monotonically increasing)
+ * - state values persist across re-renders (stored in stateValues array)
+ * - state.set() cannot be called during render (causes infinite loops)
+ * - state.set() always enqueues through scheduler (never direct mutation)
+ * - state.set() callback (notifyUpdate) always available
+ */
+
+/**
+ * State value holder - callable to read, has set method to update
+ * @example
+ * const count = state(0);
+ * count();           // read: 0
+ * count.set(1);      // write: triggers re-render
+ */
+interface State<T> {
+    (): T;
+    set(value: T): void;
+    set(updater: (prev: T) => T): void;
+    _hasBeenRead?: boolean;
+    _readers?: Map<ComponentInstance, number>;
+}
+/**
+ * Creates a local state value for a component
+ * Optimized for:
+ * - O(1) read performance
+ * - Minimal allocation per state
+ * - Fast scheduler integration
+ *
+ * IMPORTANT: state() must be called during component render execution.
+ * It captures the current component instance from context.
+ * Calling outside a component function will throw an error.
+ *
+ * @example
+ * ```ts
+ * // ✅ Correct: called during render
+ * export function Counter() {
+ *   const count = state(0);
+ *   return { type: 'button', children: [count()] };
+ * }
+ *
+ * // ❌ Wrong: called outside component
+ * const count = state(0);
+ * export function BadComponent() {
+ *   return { type: 'div' };
+ * }
+ * ```
+ */
+declare function state<T>(initialValue: T): State<T>;
+
+/**
+ * Common call contracts: Component signatures
+ */
+
+type ComponentContext = {
+    signal: AbortSignal;
+};
+type ComponentVNode = {
+    type: string;
+    props?: Props;
+    children?: (string | ComponentVNode | null | undefined | false)[];
+};
+type ComponentFunction = (props: Props, context?: ComponentContext) => JSXElement | ComponentVNode | string | number | null;
+
+/**
+ * Context system: lexical scope + render-time snapshots
+ *
+ * CORE SEMANTIC (Option A — Snapshot-Based):
+ * ============================================
+ * An async resource observes the context of the render that created it.
+ * Context changes only take effect via re-render, not magically mid-await.
+ *
+ * This ensures:
+ * - Deterministic behavior
+ * - Concurrency safety
+ * - Replayable execution
+ * - Debuggability
+ *
+ * INVARIANTS:
+ * - readContext() only works during component render (has currentContextFrame)
+ * - Each render captures a context snapshot
+ * - Async continuations see the snapshot from render start (frozen)
+ * - Provider (Scope) creates a new frame that shadows parent
+ * - Context updates require re-render to take effect
+ */
+
+type ContextKey = symbol;
+interface ContextFrame {
+    parent: ContextFrame | null;
+    values: Map<ContextKey, unknown> | null;
+}
+
+/**
+ * Component instance lifecycle management
+ * Internal only — users never see this
+ */
+
+interface ComponentInstance {
+    id: string;
+    fn: ComponentFunction;
+    props: Props;
+    target: Element | null;
+    mounted: boolean;
+    abortController: AbortController;
+    ssr?: boolean;
+    cleanupStrict?: boolean;
+    stateValues: State<unknown>[];
+    evaluationGeneration: number;
+    notifyUpdate: (() => void) | null;
+    _pendingFlushTask?: () => void;
+    _pendingRunTask?: () => void;
+    _enqueueRun?: () => void;
+    stateIndexCheck: number;
+    expectedStateIndices: number[];
+    firstRenderComplete: boolean;
+    mountOperations: Array<() => void | (() => void) | Promise<void | (() => void)>>;
+    cleanupFns: Array<() => void>;
+    hasPendingUpdate: boolean;
+    ownerFrame: ContextFrame | null;
+    isRoot?: boolean;
+    _currentRenderToken?: number;
+    lastRenderToken?: number;
+    _pendingReadStates?: Set<State<unknown>>;
+    _lastReadStates?: Set<State<unknown>>;
+    _placeholder?: Comment;
+}
+/**
+ * Get the abort signal for the current component
+ * Used to cancel async operations on unmount/navigation
+ *
+ * The signal is guaranteed to be aborted when:
+ * - Component unmounts
+ * - Navigation occurs (different route)
+ * - Parent is destroyed
+ *
+ * IMPORTANT: getSignal() must be called during component render execution.
+ * It captures the current component instance from context.
+ *
+ * @returns AbortSignal that will be aborted when component unmounts
+ * @throws Error if called outside component execution
+ *
+ * @example
+ * ```ts
+ * // ✅ Correct: called during render, used in async operation
+ * export async function UserPage({ id }: { id: string }) {
+ *   const signal = getSignal();
+ *   const user = await fetch(`/api/users/${id}`, { signal });
+ *   return <div>{user.name}</div>;
+ * }
+ *
+ * // ✅ Correct: passed to event handler
+ * export function Button() {
+ *   const signal = getSignal();
+ *   return {
+ *     type: 'button',
+ *     props: {
+ *       onClick: async () => {
+ *         const data = await fetch(url, { signal });
+ *       }
+ *     }
+ *   };
+ * }
+ *
+ * // ❌ Wrong: called outside component context
+ * const signal = getSignal(); // Error: not in component
+ * ```
+ */
+declare function getSignal(): AbortSignal;
+
+export { type ComponentFunction as C, type State as S, getSignal as g, state as s };

package/dist/foundations/index.d.ts

@@ -0,0 +1,373 @@
+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;
+    children: JSXElement;
+    [key: string]: unknown;
+} | {
+    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.
+ *
+ * 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 */
+    (): unknown;
+    /** Render content into the portal */
+    render(props: {
+        children?: T;
+    }): unknown;
+}
+declare function definePortal<T = unknown>(): Portal<T>;
+declare const DefaultPortal: Portal<unknown>;
+
+/**
+ * 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 };