elements-kit 0.18.2 → 0.19.0

package/dist/ui/overlay/index.css

@@ -0,0 +1,70 @@
+.x-overlay {
+  --overlay-constraint-top: 0px;
+  --overlay-constraint-left: 0px;
+  --overlay-constraint-width: 100vw;
+  --overlay-constraint-height: 100vh;
+  --_ct: var(--overlay-constraint-top, 0px);
+  --_cl: var(--overlay-constraint-left, 0px);
+  --_cw: var(--overlay-constraint-width, 100vw);
+  --_ch: var(--overlay-constraint-height, 100vh);
+}
+
+@supports (height: 1svh) {
+  .x-overlay {
+    --overlay-constraint-width: 100svw;
+    --overlay-constraint-height: 100svh;
+  }
+}
+
+.x-overlay {
+  top: var(--_ct);
+  left: var(--_cl);
+  translate: calc(-50% + var(--_ex, 0px) + var(--overlay-dx, 0px) +
+        clamp(50%,
+          var(--overlay-x, calc(var(--_cw) / 2)),
+          calc(-50% + var(--_cw))))
+    calc(-50% + var(--_ey, 0px) + var(--overlay-dy, 0px) +
+        clamp(50%,
+          var(--overlay-y, calc(var(--_ch) / 2)),
+          calc(-50% + var(--_ch))));
+  --overlay-width: 480px;
+  width: var(--overlay-w, var(--overlay-width));
+  max-width: var(--_cw);
+  height: var(--overlay-h, fit-content);
+  max-height: var(--_ch);
+  --overlay-duration: .3s;
+  --overlay-easing: cubic-bezier(.32, .72, 0, 1);
+  transition: top var(--overlay-duration) var(--overlay-easing),
+    left var(--overlay-duration) var(--overlay-easing),
+    translate var(--overlay-duration) var(--overlay-easing),
+    width var(--overlay-duration) var(--overlay-easing),
+    height var(--overlay-duration) var(--overlay-easing);
+  grid-template-rows: minmax(0, 1fr);
+}
+
+.x-overlay:not([open], :popover-open) {
+  pointer-events: none;
+}
+
+.x-overlay:where([popover]) {
+  display: none;
+}
+
+.x-overlay:where([open], :popover-open) {
+  display: grid;
+}
+
+@supports not (translate: 0px) {
+  .x-overlay {
+    top: auto;
+    left: auto;
+    margin: auto;
+    inset: 0;
+  }
+}
+
+@supports (interpolate-size: allow-keywords) {
+  .x-overlay {
+    interpolate-size: allow-keywords;
+  }
+}

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

@@ -0,0 +1,209 @@
+//#region src/ui/overlay/constrain.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.
+ */
+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.
+ */
+interface ConstraintRect {
+  top(): number;
+  left(): number;
+  width(): number;
+  height(): number;
+}
+/** Resolves the constraint rect every gesture bound derives from. */
+declare function resolveConstraint(overlay: HTMLElement): {
+  top: number;
+  left: number;
+  width: number;
+  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.
+ *
+ * Caveat: `ResizeObserver` fires on size changes — 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
+ * variables, restoring the viewport constraint.
+ *
+ * @example
+ * ```ts
+ * import { constrainOverlay } from "elements-kit/ui/overlay";
+ *
+ * const panel = document.querySelector("dialog.x-overlay")!;
+ * constrainOverlay(panel, document.querySelector("main")!);
+ * ```
+ */
+declare function constrainOverlay(overlay: HTMLElement, source: Element | ConstraintRect): OverlayConstraint;
+//#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`.
+ */
+/** How far (ms) a release velocity is projected when picking a rest. */
+declare const PROJECTION_MS = 160;
+/** Clamp `value` into `[min, max]`. */
+declare function clamp(value: number, min: number, max: number): number;
+/**
+ * The release context a `ResizeStrategy` decides against. The gesture
+ * builds it per drag; `resolve` turns a step value into pixels.
+ */
+interface ResizeContext {
+  /** Dragged size along the axis (px, before clamping). */
+  size: number;
+  /** Size at the gesture's start (px). */
+  startSize: number;
+  /** Release velocity along the axis (px/ms; positive = shrinking). */
+  velocity: number;
+  /** Resize axis. */
+  axis: "width" | "height";
+  /** Hard room the surface may occupy on the axis (px). */
+  min: number;
+  max: number;
+  /** Whether a drag/flick past the minimum may dismiss. */
+  dismissible: boolean;
+  /** Release velocity (px/ms) past which a sub-minimum release dismisses. */
+  velocityThreshold: number;
+  /** Resolves a step to px — a number is a fraction of the constraint
+   * along the axis; a string is any CSS length. */
+  resolve(value: number | string): number;
+}
+/**
+ * Decides where a resize drag rests. The gesture calls `bounds()` for the
+ * live rubber-band and `rest()` on release (the resting size, or `null`
+ * to dismiss). Built-ins: `freeResize` (default), `detents`.
+ */
+interface ResizeStrategy {
+  /** Soft `[lo, hi]` bounds for the live drag — rubber-band past these.
+   * Defaults to the hard room when omitted. */
+  bounds?(ctx: ResizeContext): [number, number];
+  /** Resting size (px) on release, or `null` to dismiss. */
+  rest(ctx: ResizeContext): number | null;
+}
+/**
+ * Picks the index of the detent closest to the released size, projected
+ * along the release velocity (px/ms, positive = shrinking). Returns `-1`
+ * when the gesture should dismiss instead.
+ */
+declare function closestDetent(sizePx: number, detentsPx: readonly number[], velocityPxPerMs?: number, dismissible?: boolean, velocityThreshold?: number): number;
+/**
+ * Free resize: drag to any size within the room; a flick or shrink past
+ * the minimum dismisses. The default strategy.
+ */
+declare function freeResize(opts?: {
+  min?: number;
+}): ResizeStrategy;
+/**
+ * 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.
+ */
+declare function detents(steps: readonly (number | string)[]): ResizeStrategy;
+//#endregion
+//#region src/ui/overlay/gestures.d.ts
+interface OverlayGestureOptions {
+  /** How a resize drag rests. Default: `freeResize()`. */
+  resize?: ResizeStrategy;
+  /** Allow a drag/flick past the minimum to close. Default `true`. */
+  dismissible?: boolean;
+  /** Release velocity (px/ms, shrinking) that dismisses. Default `0.5`. */
+  velocityThreshold?: number;
+}
+interface OverlayGestures {
+  /** Resize to a size (px) along the resize axis — animated by CSS. */
+  resize(size: number): void;
+  dispose(): void;
+  [Symbol.dispose](): void;
+}
+/**
+ * Opt-in pointer gestures for `.x-overlay`, dispatched by the gesture
+ * attributes (structure stays in markup; policy is options):
+ *
+ * - An edge word (`block-*` / `inline-*`) is a whole-surface size drag
+ *   along that axis — block drags the height (sheets), inline the width
+ *   (drawers), `:dir(rtl)` flips the inline sign. The side names the
+ *   handle; the opposite edge stays put.
+ * - A corner word (`start-start` / … — block side first) is a desktop-
+ *   window resize from a square zone at that corner, anchored at the
+ *   opposite corner so the surface never grows past the constraint. The
+ *   width follows the `resize` strategy; the height is a free clamp.
+ * - `data-draggable` moves the surface in x/y from the top strip,
+ *   rubber-banding at the edges; flinging it off the constraint dismisses
+ *   (when `dismissible`).
+ *
+ * Layered for testability: `gesture-model` owns the pure mode reducers +
+ * math, and `overlay-dom` owns all DOM contact (pointer plumbing + channel
+ * I/O). This function is the wiring — it picks a pure `Session` from
+ * `detectEngagement` and adapts it to the recognizer through the io.
+ * The `resize` strategy (`freeResize` by default, or `detents`) decides the
+ * rested size, written to the public `--overlay-w`/`--overlay-h` channels;
+ * CSS renders and animates them. JS never touches `translate`/`top`/`left`.
+ *
+ * Registers its cleanup with the current scope (`onCleanup`) and also
+ * returns it as `dispose` / `Symbol.dispose`.
+ *
+ * @example
+ * ```ts
+ * import { createOverlayGestures, detents } from "elements-kit/ui/overlay";
+ *
+ * const el = document.querySelector("dialog.x-overlay")!;
+ * createOverlayGestures(el, { resize: detents([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 {
+  /** Resize to a size (px) along the resize axis — animated by CSS. */
+  resize(size: number): 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;
+//#endregion
+export { ConstraintRect, OverlayConfig, OverlayConstraint, OverlayController, OverlayGestureOptions, OverlayGestures, PROJECTION_MS, ResizeContext, ResizeStrategy, clamp, closestDetent, constrainOverlay, createOverlayGestures, detents, freeResize, overlay, resolveConstraint };