@threadlabs/looma 0.2.19 → 0.3.0

package/dist/index.d.cts

@@ -1,10 +1,29 @@
 import { IconNode } from 'lucide';
-import { F as FieldValidation, a as FieldFormatter, b as FieldIssue } from './validation-bxcou-l-.cjs';
-export { c as FieldFormat, d as FieldRequest, e as FieldResult, f as FieldSchema, g as FieldSchemaResult, h as FieldSelection, i as formatEditingValue, v as validateField } from './validation-bxcou-l-.cjs';
-export { ComponentDefinition, LoomaAdoptionRecord, LoomaControllerModule, attachLoomaComponent, controllerFor, manageComponentLifecycle, registerLoomaPackage } from './declarative.cjs';
+export { ComponentDefinition, LoomaAdoptionRecord, LoomaControllerModule, attachLoomaComponent, controllerFor, manageComponentLifecycle, registerLoomaPackage, updateComponentProps } from './declarative.cjs';
 
+/**
+ * Module-wide coordination for dismissible surfaces in one browser realm.
+ *
+ * Individual components own rendering and open state. This module owns only
+ * the cross-component invariants: Escape/light-dismiss target the most recently
+ * opened surface, document listeners exist only while needed, and scroll stays
+ * locked until the last modal closes. A component must therefore close its
+ * record during teardown even if its DOM node has already disconnected.
+ */
+/** Why an overlay was asked to close; this describes intent, not state ownership. */
 type OverlayCloseReason = "programmatic" | "light-dismiss" | "escape" | "action";
+/** Input modality that initiated an overlay state transition. */
 type OverlayTrigger = "keyboard" | "pointer" | "programmatic";
+/**
+ * A live entry in the overlay stack.
+ *
+ * `requestClose` is deliberately a request rather than a mutation. Controlled
+ * components notify their owner and may remain open; uncontrolled components
+ * may close immediately. The manager must not guess which mode is active.
+ *
+ * @ownership The component owns the element and open state. The manager borrows
+ * the record only to coordinate stack order, dismissal, and modal accounting.
+ */
 interface OverlayRecord {
     id: string;
     modal: boolean;
@@ -15,12 +34,37 @@ interface OverlayRecord {
     dismissible?: boolean;
     requestClose: (reason: OverlayCloseReason, trigger: OverlayTrigger) => void;
 }
+/**
+ * Moves an overlay to the top of the interaction stack.
+ * Reopening an existing id replaces its record so modal accounting cannot be
+ * incremented twice and the newest callbacks/related elements take effect.
+ *
+ * @lifecycle The record remains active until its id is closed or replaced;
+ * callers must close it during teardown even after the element disconnects.
+ */
 declare function openOverlay(record: OverlayRecord): void;
+/** Removes an overlay record and releases global resources when the stack empties. */
 declare function closeOverlay(id: string): void;
+/** Returns the most recently opened live record without mutating stack order. */
 declare function getTopOverlay(): OverlayRecord | undefined;
+/** Reports whether an id currently owns Escape and light-dismiss handling. */
 declare function isTopOverlay(id: string): boolean;
+/**
+ * Routes a dismissal request to the topmost overlay only.
+ *
+ * Returning `true` means a request was delivered, not that the overlay closed;
+ * controlled owners decide whether and when the corresponding state changes.
+ */
 declare function requestTopOverlayClose(reason: OverlayCloseReason, trigger: OverlayTrigger): boolean;
 
+/**
+ * Rectangle in CSS-pixel viewport coordinates.
+ *
+ * `left`/`top` are not assumed to be zero because the visual viewport can be
+ * offset inside the layout viewport during pinch zoom or when an on-screen
+ * keyboard is present. Values are compatible with fixed-position surfaces and
+ * `getBoundingClientRect()` measurements used by this module.
+ */
 interface ViewportRect {
     left: number;
     top: number;
@@ -29,51 +73,104 @@ interface ViewportRect {
     width: number;
     height: number;
 }
+/** Geometry accepted from DOMRect or a framework-neutral measurement adapter. */
 interface RectLike extends ViewportRect {
 }
+/** A point in the same CSS-pixel viewport coordinate space as `RectLike`. */
 interface Point {
     x: number;
     y: number;
 }
+/** Scope-level policy for non-hit-testable anticipatory affordances. */
 interface ProximityCoordinatorOptions {
-    /** Event surface for pointer tracking. Defaults to the interaction scope. */
+    /** Event surface for pointer tracking. Defaults to the scope's owning document. */
     pointerTarget?: EventTarget;
     /** Descendants participating in proximity. */
     anchorSelector?: string;
     /** Distance outside an anchor that activates its anticipatory state. */
     nearRadius?: number;
 }
+/**
+ * Owns shared pointer tracking and reflected proximity state for one scope.
+ *
+ * @lifecycle `destroy` is terminal: it cancels pending measurement, removes its
+ * listeners, and clears only the attributes reflected by this coordinator.
+ */
 interface ProximityCoordinator {
-    /** Refreshes the anchor list and its cached geometry after a layout change. */
+    /**
+     * Invalidates the anchor list and cached geometry after layout changes.
+     * Work is coalesced into the next animation frame; callers do not need to
+     * debounce resize, editor-transaction, or content-change notifications.
+     */
     refresh(): void;
-    /** Removes the scope-level listeners and all reflected interaction state. */
+    /**
+     * Removes scope-level listeners, cancels scheduled work, and clears every
+     * `data-ui-proximity`/`data-ui-interaction` attribute owned by the coordinator.
+     */
     destroy(): void;
 }
+/** Logical placement preference; collision handling may flip either axis. */
 type AnchoredPlacement = "bottom-start" | "bottom-end" | "top-start" | "top-end";
+/**
+ * Policy for an anchored floating surface.
+ * Gaps are CSS pixels. `anchor` remains application-owned and may be replaced;
+ * the controller only borrows it to measure and temporarily extend
+ * `anchor-name` without erasing an existing author value.
+ */
 interface AnchoredSurfaceOptions {
     anchor?: HTMLElement | null;
     placement?: AnchoredPlacement;
     gap?: number;
     viewportGap?: number;
 }
+/**
+ * Lifecycle controller for one application-owned floating element.
+ *
+ * `hide` keeps the current anchor binding for cheap reopening. `destroy` is the
+ * terminal operation: it hides the surface, releases listeners/observers and
+ * animation frames, and restores the anchor's original `anchor-name` style.
+ *
+ * @ownership The application owns both DOM nodes; the controller owns only its
+ * temporary anchor-name contribution and open-session browser resources.
+ */
 interface AnchoredSurface {
+    /** Rebinds ownership bookkeeping from the previous anchor to the next one. */
     setAnchor(anchor: HTMLElement | null): void;
+    /** Opens relative to the current element anchor. */
     show(): void;
+    /** Opens at a viewport-coordinate point, temporarily overriding the anchor. */
     showAtPoint(point: Point): void;
+    /** Closes the top-layer surface and active listeners but preserves its anchor binding. */
     hide(): void;
+    /** Requests a coalesced remeasurement while open; it is inert while hidden. */
     refresh(): void;
+    /** Performs terminal cleanup and restores styles borrowed from the anchor. */
     destroy(): void;
 }
+/**
+ * Minimal lifecycle for unanchored top-layer UI such as toast regions.
+ * The caller owns the element and its viewport CSS; destruction only closes the
+ * top-layer participation and does not remove the node.
+ *
+ * @ownership The application retains the element; this controller owns only its
+ * participation in the browser's top layer.
+ */
 interface ViewportSurface {
     show(): void;
+    /** Closes the surface without removing the application-owned element. */
     hide(): void;
+    /** Terminal alias for closing; retained for a uniform controller lifecycle. */
     destroy(): void;
 }
+/** Default pointer halo in CSS pixels; it never changes native hit targets. */
 declare const DEFAULT_AFFORDANCE_NEAR_RADIUS = 16;
 /**
  * Places unanchored floating UI, such as a toast region, in the browser top
  * layer. Its viewport position remains CSS-owned; the controller only provides
  * the native Popover API boundary and its no-Popover fallback.
+ *
+ * @ownership The caller owns the element and its CSS; this controller owns only
+ * top-layer participation and never removes the node.
  */
 declare function createViewportSurface(surface: HTMLElement): ViewportSurface;
 /**
@@ -81,10 +178,35 @@ declare function createViewportSurface(surface: HTMLElement): ViewportSurface;
  * Popover provides the top layer and CSS Anchor Positioning follows a named
  * element. Browsers without Anchor Positioning use the same flip/shift
  * geometry through scroll/resize listeners that exist only while open.
+ *
+ * @ownership The caller owns both DOM nodes. The controller temporarily owns
+ * its generated anchor name, observers, listeners, and scheduled frames.
+ * @lifecycle `hide` releases open-only work but preserves the anchor binding;
+ * `destroy` is terminal and restores the anchor's original inline style.
  */
 declare function createAnchoredSurface(surface: HTMLElement, options?: AnchoredSurfaceOptions): AnchoredSurface;
+/**
+ * Returns the currently visible fixed-position viewport, not merely the layout
+ * viewport. This keeps menus inside the region left visible by zoom and virtual
+ * keyboards; browsers without Visual Viewport fall back to `innerWidth/Height`.
+ *
+ * @contract The returned edges and dimensions share CSS-pixel viewport
+ * coordinates with `getBoundingClientRect()` and fixed-position surfaces.
+ */
 declare function getVisualViewportRect(owner?: Window): ViewportRect;
+/**
+ * Calculates the translation needed to contain a rectangle inside a viewport.
+ *
+ * The input is never mutated. If a surface is larger than the available area,
+ * its leading edge is pinned to the gutter rather than oscillating between two
+ * impossible edge constraints.
+ */
 declare function clampRectToViewport(rect: RectLike, viewport?: ViewportRect, gutter?: number): Point;
+/**
+ * Measures Euclidean distance to the nearest rectangle edge, returning zero
+ * for points inside it. This lets anticipatory affordances share generous visual
+ * proximity without enlarging or overlapping their actual pointer hit targets.
+ */
 declare function distanceFromPointToRect(point: Point, rect: RectLike): number;
 /**
  * Coordinates anticipatory UI within one interaction scope.
@@ -93,6 +215,11 @@ declare function distanceFromPointToRect(point: Point, rect: RectLike): number;
  * update for the whole scope. Anchors remain the only hit-testable controls; the
  * reflected state is presentation-only, so overlapping near regions do not steal
  * pointer input from each other or from surrounding content.
+ *
+ * @ownership The coordinator owns every proximity attribute it reflects plus
+ * one abortable listener set; it never owns the anchors themselves.
+ * @lifecycle `refresh` coalesces geometry invalidation into one frame, while
+ * `destroy` cancels pending work, removes listeners, and clears reflected state.
  */
 declare function createProximityCoordinator(scope: HTMLElement, options?: ProximityCoordinatorOptions): ProximityCoordinator;
 
@@ -100,6 +227,9 @@ declare function createProximityCoordinator(scope: HTMLElement, options?: Proxim
  * Reflects real touch use instead of guessing from device capability media
  * queries. Hybrid devices therefore keep compact pointer affordances until the
  * user actually touches the interface.
+ *
+ * @lifecycle Initialization is idempotent per document. Its passive listeners
+ * live with that document, and touch modality is sticky once observed.
  */
 declare function initializeInputModality(owner?: Document): void;
 
@@ -151,12 +281,21 @@ declare const LOOMA_ICONS: {
     underline: IconNode;
     undo: IconNode;
 };
+/** Stable key selecting an icon from Looma's shipped interaction vocabulary. */
 type LoomaIconName = keyof typeof LOOMA_ICONS;
+/** Framework-neutral Lucide element tree used to produce Looma icon markup. */
 type LoomaIconNode = IconNode;
 /** Creates consistent, currentColor-driven SVG markup for framework-neutral components. */
 declare function loomaIconMarkup(name: LoomaIconName, className?: string): string;
 
+/** Relative insertion target resolved from a pointer's vertical row position. */
 type DropPosition = 'before' | 'inside' | 'after';
+/**
+ * Controls one replaceable delayed intent keyed by the hovered target.
+ *
+ * @lifecycle `cancel` clears pending work but permits reuse; `destroy` provides
+ * terminal cleanup for owners even though this controller holds no other state.
+ */
 interface HoverIntentController {
     schedule(key: string): void;
     cancel(): void;
@@ -167,49 +306,69 @@ interface HoverIntentController {
  * middle half for containment; leaf rows split cleanly at their midpoint.
  */
 declare function classifyDropPosition(rect: Pick<DOMRect, 'top' | 'bottom' | 'height'>, clientY: number, acceptsChildren: boolean): DropPosition;
-/** Use the rendered row—not the tiny handle—as the browser drag preview. */
+/**
+ * Uses the rendered row—not the tiny handle—as the browser drag preview.
+ *
+ * @contract Missing or non-browser data-transfer implementations are a no-op;
+ * otherwise the preview is inset from the left and vertically centered.
+ */
 declare function setElementDragImage(dataTransfer: DataTransfer | null, element: HTMLElement): void;
-/** A keyed, replaceable hover timer suitable for expansion and disclosure intent. */
+/**
+ * Creates a keyed, replaceable hover timer for expansion and disclosure intent.
+ *
+ * Scheduling the same pending key is idempotent; scheduling a different key
+ * cancels the prior intent so only the newest target can fire.
+ *
+ * @lifecycle Cancellation and destruction suppress pending callbacks. Once an
+ * intent fires, the controller returns to an idle reusable state.
+ */
 declare function createHoverIntent(delay: number, onIntent: (key: string) => void): HoverIntentController;
 
-interface ComboboxOption<Metadata = unknown> {
+/**
+ * Renderable validation problem, optionally located within structured input.
+ * Warning severity preserves accepted output; omitted severity is an error.
+ */
+interface FieldIssue {
+    readonly message: string;
+    readonly path?: ReadonlyArray<PropertyKey | {
+        readonly key: PropertyKey;
+    }>;
+    readonly severity?: 'error' | 'warning';
+}
+
+/**
+ * Canonical option shape at Looma's domain boundary.
+ *
+ * `id` is stable identity for rendering and selection bookkeeping; `value` is
+ * the form/domain value. They are separate so labels or backend identifiers can
+ * change without making list reconciliation or selected-option lookup ambiguous.
+ * Options are authored as `<option>`/`<optgroup>` children; selected items cross
+ * the attribute boundary as JSON in this shape.
+ */
+interface ComboboxOption {
     id: string;
     value: string;
     label: string;
-    description?: string;
-    metadata?: Metadata;
     group?: string;
     disabled?: boolean;
 }
-interface ComboboxRequest<Context = unknown> {
-    query: string;
-    context: Context;
-    signal: AbortSignal;
-    reason: 'input' | 'disclosure' | 'context';
-}
-type ComboboxProvider = (request: ComboboxRequest) => readonly ComboboxOption[] | Promise<readonly ComboboxOption[]>;
-/** Map domain records at the boundary, preserving typed metadata for rich rows. */
-declare function mapComboboxOptions<T>(rows: readonly T[], map: (row: T) => Omit<ComboboxOption<T>, 'metadata'>): ComboboxOption<T>[];
-interface ComboboxConfig extends FieldValidation {
-    options?: readonly ComboboxOption[];
-    provider?: ComboboxProvider;
-    filter?: (option: ComboboxOption, query: string, context: unknown) => boolean;
-    context?: unknown;
-    invalidation?: 'clear' | 'retain-query' | 'retain';
-    debounce?: number;
-    allowFreeText?: boolean;
-    allowCreate?: boolean;
-    format?: FieldFormatter;
-    formatOn?: 'input' | 'blur';
-    validateOn?: 'input' | 'blur' | 'submit';
-}
+/**
+ * Semantic value transition emitted by the combobox.
+ * `kind` explains the state-machine path while `trigger` records user modality;
+ * consumers should not infer either from low-level input/click events.
+ */
 interface ComboboxChange {
     value: string | null;
     query: string;
     option: ComboboxOption | null;
-    kind: 'selection' | 'clear' | 'free-entry' | 'create' | 'invalidation';
+    kind: 'selection' | 'clear' | 'free-entry' | 'create';
     trigger: 'keyboard' | 'pointer' | 'programmatic';
 }
+/**
+ * Renderable validation snapshot. `output` is defined only when the current
+ * value passed all error-severity checks; warnings preserve output and remain
+ * visible.
+ */
 interface ComboboxValidationState {
     status: 'pristine' | 'pending' | 'valid' | 'warning' | 'error';
     touched: boolean;
@@ -218,21 +377,38 @@ interface ComboboxValidationState {
     output?: unknown;
 }
 
+/**
+ * Semantic transition between display and editing modes.
+ *
+ * The reason identifies the state-machine path while the trigger records input
+ * modality, so consumers need not reconstruct intent from low-level events.
+ */
 interface EditableChange {
     edit: boolean;
     reason: 'activate' | 'light-dismiss' | 'escape' | 'programmatic';
     trigger: 'keyboard' | 'pointer' | 'programmatic';
 }
 
+/** Canonical selected item; multiple mode retains the full option for chip rendering. */
 type MultiComboboxItem = ComboboxOption;
+/**
+ * One item-list transition. The list itself is owner-controlled; `index`
+ * identifies the insertion position or the removed item's former position
+ * rather than authorizing Looma to mutate an application collection.
+ */
 interface MultiComboboxItemChange {
     item: MultiComboboxItem;
     index: number;
     trigger: 'keyboard' | 'pointer' | 'programmatic';
 }
+/**
+ * Request to create an item from unmatched editing text.
+ * The application owns deduplication, persistence, and the eventual controlled
+ * item-list update.
+ */
 interface MultiComboboxCreate {
     query: string;
     trigger: 'keyboard' | 'pointer' | 'programmatic';
 }
 
-export { type AnchoredPlacement, type AnchoredSurface, type AnchoredSurfaceOptions, type ComboboxChange, type ComboboxConfig, type ComboboxOption, type ComboboxProvider, type ComboboxRequest, type ComboboxValidationState, DEFAULT_AFFORDANCE_NEAR_RADIUS, type DropPosition, type EditableChange, FieldFormatter, FieldIssue, FieldValidation, type HoverIntentController, LOOMA_ICONS, type LoomaIconName, type LoomaIconNode, type MultiComboboxCreate, type MultiComboboxItem, type MultiComboboxItemChange, type OverlayCloseReason, type OverlayRecord, type OverlayTrigger, type Point, type ProximityCoordinator, type ProximityCoordinatorOptions, type RectLike, type ViewportRect, type ViewportSurface, clampRectToViewport, classifyDropPosition, closeOverlay, createAnchoredSurface, createHoverIntent, createProximityCoordinator, createViewportSurface, distanceFromPointToRect, getTopOverlay, getVisualViewportRect, initializeInputModality, isTopOverlay, loomaIconMarkup, mapComboboxOptions, openOverlay, requestTopOverlayClose, setElementDragImage };
+export { type AnchoredPlacement, type AnchoredSurface, type AnchoredSurfaceOptions, type ComboboxChange, type ComboboxOption, type ComboboxValidationState, DEFAULT_AFFORDANCE_NEAR_RADIUS, type DropPosition, type EditableChange, type FieldIssue, type HoverIntentController, LOOMA_ICONS, type LoomaIconName, type LoomaIconNode, type MultiComboboxCreate, type MultiComboboxItem, type MultiComboboxItemChange, type OverlayCloseReason, type OverlayRecord, type OverlayTrigger, type Point, type ProximityCoordinator, type ProximityCoordinatorOptions, type RectLike, type ViewportRect, type ViewportSurface, clampRectToViewport, classifyDropPosition, closeOverlay, createAnchoredSurface, createHoverIntent, createProximityCoordinator, createViewportSurface, distanceFromPointToRect, getTopOverlay, getVisualViewportRect, initializeInputModality, isTopOverlay, loomaIconMarkup, openOverlay, requestTopOverlayClose, setElementDragImage };