@askrjs/askr 0.0.9 → 0.0.10

package/dist/foundations/structures.d.ts

@@ -0,0 +1,223 @@
+export { L as LayoutComponent, l as layout } from '../layout-BINPv-nz.js';
+import '../types-DxdosFWx.js';
+import { J as JSXElement } from '../jsx-CSWf4VFg.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.
+ *    **Slot props override child props** (injection pattern).
+ *
+ * 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>;
+
+/**
+ * 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;
+
+export { type Collection, type CollectionItem, DefaultPortal, JSXElement, type Layer, type LayerManager, type LayerOptions, type Portal, Presence, type PresenceProps, Slot, type SlotProps, createCollection, createLayer, definePortal };

package/dist/foundations/structures.js

@@ -0,0 +1 @@
+export{b as Presence,a as Slot,c as createCollection,d as createLayer}from'../chunk-CI6AOGB5.js';export{d as DefaultPortal,c as definePortal}from'../chunk-4RTKQ7SC.js';export{a as layout}from'../chunk-FFSNBDHN.js';import'../chunk-37RC6ZT3.js';import'../chunk-62D2TNHX.js';