elements-kit 0.20.0 → 0.22.0

package/dist/ui/overlay/index.d.mts

@@ -1,27 +1,50 @@
-//#region src/ui/overlay/constrain.d.ts
+import { Placement } from "@floating-ui/dom";
+
+//#region src/ui/overlay/constraint.d.ts
 /**
- * The overlay constraint — the rect an `.x-overlay` lives in. Every
- * location clamp and gesture bound derives from the
- * `--overlay-constraint-top/-left/-width/-height` variables (declared in
- * index.css with viewport defaults). This module is the JS side of that
- * interface: syncing a rect into the variables and resolving them back to
- * pixels for the gesture bounds.
+ * The constraint — one of the two spatial primitives (with the anchor).
+ * A `Region` is a reactive rect; `constraint()` builds one from an
+ * element, a plain rect, or nothing (the live viewport). `confine()`
+ * applies a region to an overlay by syncing it into the
+ * `--overlay-constraint-top/-left/-width/-height` channels every location
+ * clamp and gesture bound derives from (declared in index.css with
+ * viewport defaults). Derived values build on regions — `detents()`
+ * quantizes one, `rubber()` resists at its edges.
  */
+/** A reactive rect — the shape `createElementRect` returns, so an
+ * `Element` works directly and custom rects (a static region, a virtual
+ * area) can be supplied too. */
+interface Region {
+  top(): number;
+  left(): number;
+  width(): number;
+  height(): number;
+}
+/** A plain rect a `Region` can be built from. */
+interface RectInit {
+  top: number;
+  left: number;
+  width: number;
+  height: number;
+}
+/**
+ * Builds a {@link Region}: from an `Element` (observed via
+ * `ResizeObserver` through `createElementRect`; cleanup routes through
+ * the current scope), from a plain rect (static), or with no argument —
+ * the live viewport (read at call time, not observed).
+ */
+declare function constraint(source?: Element | RectInit): Region;
 interface OverlayConstraint {
   dispose(): void;
   [Symbol.dispose](): void;
 }
 /**
- * A reactive source of the constraint rect — the shape `createElementRect`
- * returns, so an `Element` works directly and custom rects (a non-element
- * region, a virtual anchor) can be supplied too.
+ * Resolves a custom property holding a length to pixels. Plain `px` values
+ * parse directly; anything else (`svh` / `calc()` / fractions of the
+ * constraint) resolves natively by measuring a hidden probe. `fallback` is
+ * a CSS length expression used when the property is unset.
  */
-interface ConstraintRect {
-  top(): number;
-  left(): number;
-  width(): number;
-  height(): number;
-}
+declare function resolveVarPx(overlay: HTMLElement, name: string, axis: "height" | "width", fallback?: string): number;
 /** Resolves the constraint rect every gesture bound derives from. */
 declare function resolveConstraint(overlay: HTMLElement): {
   top: number;
@@ -30,14 +53,14 @@ declare function resolveConstraint(overlay: HTMLElement): {
   height: number;
 };
 /**
- * Confines an overlay to a rect source by syncing it into the
- * `--overlay-constraint-*` variables. Pass an `Element` (observed via
- * `ResizeObserver` through `createElementRect`) or a custom
- * {@link ConstraintRect}. Every location clamp and gesture bound derives
- * from those variables, so the overlay re-clamps when the rect changes.
+ * Confines an overlay to a {@link Region} by syncing it into the
+ * `--overlay-constraint-*` variables. Every location clamp and gesture
+ * bound derives from those variables, so the overlay re-clamps when the
+ * region changes.
  *
- * Caveat: `ResizeObserver` fires on size changes — a container that moves
- * without resizing (e.g. page scroll) does not retrigger the sync.
+ * Caveat: an element region observes size changes (`ResizeObserver`) — a
+ * container that moves without resizing (e.g. page scroll) does not
+ * retrigger the sync.
  *
  * Registers its cleanup with the current scope (`onCleanup`) and also
  * returns it as `dispose` / `Symbol.dispose`; disposing removes the
@@ -45,19 +68,100 @@ declare function resolveConstraint(overlay: HTMLElement): {
  *
  * @example
  * ```ts
- * import { constrainOverlay } from "elements-kit/ui/overlay";
+ * import { constraint, confine } from "elements-kit/ui/overlay";
  *
  * const panel = document.querySelector("dialog.x-overlay")!;
- * constrainOverlay(panel, document.querySelector("main")!);
+ * confine(panel, constraint(document.querySelector("main")!));
+ * ```
+ */
+declare function confine(overlay: HTMLElement, region: Region): OverlayConstraint;
+//#endregion
+//#region src/ui/overlay/anchor.d.ts
+/**
+ * The anchor — one of the two spatial primitives (with the constraint).
+ * `anchor(overlay, follow?)` gives the overlay an anchor ELEMENT it
+ * follows for its whole life; the anchor element follows `follow` until
+ * something else moves it (a `draggable()` service, author code). The
+ * overlay itself has no states — dragging, tearing off, re-pinning are
+ * all things that happen to the anchor.
+ *
+ * Two engines, chosen once at wire time, never switched:
+ *
+ * - Native CSS anchor positioning (compound gate, no `within`/`arrow`):
+ *   the overlay's `position-anchor` points at the anchor element; when
+ *   `follow` is an element the anchor pins itself to it through a second
+ *   native hop (`[data-follow]` rule in index.css mirrors the followed
+ *   box via `anchor()`/`anchor-size()`). Placement, flip and scroll
+ *   tracking are compositor-side through both hops — zero JS.
+ * - Floating UI (below the gate, or `within`/`arrow` requested — native
+ *   CSS has no boundary control and no flip signal): `autoUpdate` writes
+ *   the box center into the `--overlay-x`/`-y` channels while the
+ *   overlay is open; a `dragmove` event from the drag service triggers
+ *   an immediate reposition. The initial positioning write is instant;
+ *   geometry transitions re-enable after it (Base UI's `data-instant`
+ *   semantics), so re-pins and live area changes morph by the
+ *   stylesheet. During an anchor drag, writes suppress geometry
+ *   transitions again — the overlay must not ease behind the finger.
+ *
+ * `data-anchor="element"` is a static wiring marker (stamped here,
+ * removed on dispose, never toggled). `data-placed` is output state —
+ * the settled side, feeding the arrow and `transform-origin` (a hint
+ * from `--overlay-area` under the native engine, the real side under
+ * Floating UI). A first pointer-down from `draggable()` tears the
+ * follow pin (the `data-follow` contract); a fresh open re-pins.
+ */
+interface AnchorOptions {
+  /** Flip/shift boundary — placement confined to this region instead of
+   * the viewport. Forces the Floating UI engine. */
+  within?: Region;
+  /** Caret pointing at the anchor (`.x-overlay-arrow`, injected when not
+   * authored; a number sets `--overlay-arrow-size` in px). Forces the
+   * Floating UI engine. */
+  arrow?: number | boolean;
+}
+/**
+ * Maps a `position-area` value to the Floating UI placement. Spanning
+ * toward an edge leaves the box flush with the *opposite* edge, so
+ * `span-*-end` is a `-start` alignment (and vice versa) — Floating UI
+ * resolves `-start`/`-end` logically, so the span tokens need no dir
+ * check; only the physical inline sides do. Unknown values fall back to
+ * `bottom` (the CSS default, `block-end`).
+ */
+declare function areaToPlacement(area: string, rtl?: boolean): Placement;
+/**
+ * Gives `overlay` its anchor element and returns it. The overlay follows
+ * the anchor for life; the anchor follows `follow` (element or rect)
+ * until something moves it. Pass the returned element to `draggable()`
+ * to make the composition tearable — dragging moves the anchor.
+ *
+ * `follow` may be a getter reading a signal — re-pinning on change is
+ * how a shared popover slides between nav triggers: the native chain
+ * glides there on the anchor element's CSS transition; the channel
+ * engine lets that one write animate.
+ *
+ * Registers all cleanup with the current scope (`onCleanup`): the anchor
+ * element, the wiring, and the stamped attributes are removed together.
+ *
+ * @example
+ * ```ts
+ * import { anchor, draggable, rubber } from "elements-kit/ui/overlay";
+ *
+ * const a = anchor(panel, trigger);
+ * draggable(a, undefined, rubber()).attach(panel);
+ *
+ * // shared nav popover — re-anchors (and glides) when the signal changes
+ * const active = signal(firstTrigger);
+ * anchor(menu, () => active(), { arrow: true });
  * ```
  */
-declare function constrainOverlay(overlay: HTMLElement, source: Element | ConstraintRect): OverlayConstraint;
+declare function anchor(overlay: HTMLElement, follow?: Element | RectInit | (() => Element | RectInit | null | undefined), opts?: AnchorOptions): HTMLElement;
 //#endregion
 //#region src/ui/overlay/resize-strategy.d.ts
 /**
  * Resize strategies — pluggable policy for a resize drag's live bounds
  * and resting size. Pure (no DOM); the gesture injects the context.
- * Built-ins: `freeResize` (default), `detents`.
+ * Built-in: `freeResize` (default). `detents()` (detents.ts) quantizes a
+ * constraint region and doubles as a strategy.
  */
 /** How far (ms) a release velocity is projected when picking a rest. */
 declare const PROJECTION_MS = 160;
@@ -112,12 +216,92 @@ declare function closestDetent(sizePx: number, detentsPx: readonly number[], vel
 declare function freeResize(opts?: {
   min?: number;
 }): ResizeStrategy;
+//#endregion
+//#region src/ui/overlay/detents.d.ts
 /**
- * Snap to discrete steps — each a fraction of the constraint along the
- * axis (number `0–1`) or a CSS length (string). Flick-aware; shrinking
- * past the smallest step dismisses.
+ * Detents — a customization of the constraint: the region, quantized.
+ * One snapping concept for both services: `resize()` (and the markup
+ * gestures) snap extents to the stops; `draggable()` snaps positions to
+ * them. A bottom sheet's size detents and its top-edge position detents
+ * were always the same thing — here they are literally the same object.
  */
-declare function detents(steps: readonly (number | string)[]): ResizeStrategy;
+/** A {@link Region} with quantized stops. Doubles as a `ResizeStrategy`
+ * (the stops resolve per axis through the gesture's `ResizeContext`). */
+interface Space extends ResizeStrategy {
+  readonly region: Region;
+  readonly stops: readonly (number | string)[];
+  /** The numeric stops resolved against a region axis (px, sorted) —
+   * position snapping for `draggable()`. String stops (CSS lengths) need
+   * an element context and only apply to resizes. */
+  positions(axis: "width" | "height"): number[];
+}
+/**
+ * Quantizes a region: each stop is a fraction of the region along the
+ * axis (number `0–1`) or a CSS length (string, resize-only). Flick-aware
+ * on release; shrinking past the smallest stop dismisses (when the
+ * consumer allows dismissal).
+ *
+ * @example
+ * ```ts
+ * import { constraint, detents } from "elements-kit/ui/overlay";
+ *
+ * const d = detents(constraint(), [0.25, 0.6, 0.9]); // of the viewport
+ * ```
+ */
+declare function detents(region: Region, stops: readonly (number | string)[]): Space;
+//#endregion
+//#region src/ui/overlay/rubber.d.ts
+/**
+ * Effects — composable physics for motion through a space. Services
+ * (`draggable`, `resize`) run each axis value through the effect chain:
+ * `during` on every move, `settle` on release (`null` = dismiss signal).
+ * `rubber()` is the built-in; custom effects are just objects.
+ */
+interface Effect {
+  /** Transform a live value (px on one axis) against the axis bounds. */
+  during?(value: number, bounds: readonly [number, number]): number;
+  /** Pick the resting value on release, or `null` to signal dismissal. */
+  settle?(value: number, velocity: number, bounds: readonly [number, number]): number | null;
+}
+/**
+ * Edge resistance — values past the bounds move at a fraction of the
+ * pointer (the iOS rubber band). Pure `resist()` under the hood; no
+ * channels involved, so it applies to anything a service moves.
+ */
+declare function rubber(): Effect;
+//#endregion
+//#region src/ui/overlay/draggable.d.ts
+/**
+ * The drag service — moves a target element through a space. Generic by
+ * design: drag any positioned element by any handle. For overlays, the
+ * target is the anchor element from `anchor()` — dragging the anchor
+ * drags the overlay, with no overlay state involved.
+ *
+ * The pipeline runs per axis: live values go through each effect's
+ * `during` (e.g. `rubber()` resistance at the space edges); on release
+ * the value goes through each `settle`, then snaps to the space's
+ * numeric stops when a `detents()` space is given (`null` from a settle
+ * = dismiss signal, surfaced on the `dragend` detail). Events on the
+ * target: `dragmove` (`{x, y}`) every move, `dragend`
+ * (`{x, y, velocity, rest}`) on release.
+ *
+ * First pointer-down tears a `data-follow` pin (the `anchor()` contract):
+ * the target freezes at its current rect and the pointer takes over.
+ */
+interface DragService {
+  /** Move the target programmatically (through the `during` effects). */
+  update(point: {
+    x: number;
+    y: number;
+  }): void;
+  /** Wire the pointer plumbing to a handle. */
+  attach(handle: Element): {
+    dispose(): void;
+  };
+  dispose(): void;
+  [Symbol.dispose](): void;
+}
+declare function draggable(target: HTMLElement, space?: Region | Space, ...effects: Effect[]): DragService;
 //#endregion
 //#region src/ui/overlay/gestures.d.ts
 interface OverlayGestureOptions {
@@ -163,47 +347,37 @@ interface OverlayGestures {
  *
  * @example
  * ```ts
- * import { createOverlayGestures, detents } from "elements-kit/ui/overlay";
+ * import { constraint, createOverlayGestures, detents } from "elements-kit/ui/overlay";
  *
  * const el = document.querySelector("dialog.x-overlay")!;
- * createOverlayGestures(el, { resize: detents([0.25, 0.6, 0.9]) });
+ * createOverlayGestures(el, { resize: detents(constraint(), [0.25, 0.6, 0.9]) });
  * el.addEventListener("resizechange", (e) => console.log(e.detail));
  * ```
  */
 declare function createOverlayGestures(overlay: HTMLElement, options?: OverlayGestureOptions): OverlayGestures;
 //#endregion
-//#region src/ui/overlay/overlay.d.ts
-interface OverlayConfig extends OverlayGestureOptions {
-  /** Confine the overlay to an element's rect (or a custom
-   * {@link ConstraintRect}). Omit for the default viewport constraint. */
-  constrain?: Element | ConstraintRect;
-}
-interface OverlayController {
+//#region src/ui/overlay/resize.d.ts
+/**
+ * The resize service — sizes a target through a space. The handle you
+ * `attach()` is the whole gesture zone (unlike the markup gestures,
+ * which zone-detect on the overlay surface); the side comes from the
+ * target's `data-resize` value, same vocabulary as the stylesheet.
+ *
+ * The space is any `ResizeStrategy` — pass a `detents()` space to snap,
+ * omit for `freeResize()`. Effects apply on release: each `settle` runs
+ * over the strategy's rested size (`null` = dismiss). Live rubber past
+ * the strategy bounds is built into the sessions.
+ */
+interface ResizeService {
   /** Resize to a size (px) along the resize axis — animated by CSS. */
-  resize(size: number): void;
+  update(size: number): void;
+  /** Wire the pointer plumbing to a handle. */
+  attach(handle: Element): {
+    dispose(): void;
+  };
   dispose(): void;
   [Symbol.dispose](): void;
 }
-/**
- * One-call wiring for an interactive `.x-overlay`: optional constraint
- * sync + pointer gestures, under a single disposable. Structure stays in
- * markup (`data-resize` / `data-draggable`); policy is config.
- *
- * Registers its cleanup with the current scope (`onCleanup`) and also
- * returns it as `dispose` / `Symbol.dispose`.
- *
- * @example
- * ```ts
- * import { overlay, detents } from "elements-kit/ui/overlay";
- *
- * const el = document.querySelector("dialog.x-overlay")!;
- * const o = overlay(el, {
- *   constrain: document.querySelector("main")!,
- *   resize: detents([0.25, 0.6, 0.9]),
- *   onResize: (size) => console.log(size),
- * });
- * ```
- */
-declare function overlay(el: HTMLElement, config?: OverlayConfig): OverlayController;
+declare function resize(target: HTMLElement, space?: ResizeStrategy, ...effects: Effect[]): ResizeService;
 //#endregion
-export { ConstraintRect, OverlayConfig, OverlayConstraint, OverlayController, OverlayGestureOptions, OverlayGestures, PROJECTION_MS, ResizeContext, ResizeStrategy, clamp, closestDetent, constrainOverlay, createOverlayGestures, detents, freeResize, overlay, resolveConstraint };
+export { AnchorOptions, DragService, Effect, OverlayConstraint, OverlayGestureOptions, OverlayGestures, PROJECTION_MS, RectInit, Region, ResizeContext, ResizeService, ResizeStrategy, Space, anchor, areaToPlacement, clamp, closestDetent, confine, constraint, createOverlayGestures, detents, draggable, freeResize, resize, resolveConstraint, resolveVarPx, rubber };