elements-kit 0.18.2 → 0.20.0

package/dist/{infer-B7T5hi_D.d.mts → types-ncUK9rki.d.mts}

@@ -1,13 +1,10 @@
 import { n as AttrChangeHandler, t as ATTRIBUTES } from "./attributes-3r7Diua4.mjs";
-import { t as CustomElementRegistry } from "./custom-elements-D5CgfNKc.mjs";
-import { n as Slot, r as PrimitiveNodeType, t as SLOTS } from "./slot-B8y0aEoz.mjs";
+import { n as Slot, r as PrimitiveNodeType, t as SLOTS } from "./slot-BFWXeFRl.mjs";
+import { t as CustomElementRegistry } from "./custom-elements-DK5VUcWA.mjs";
 import { JSX } from "dom-expressions/src/jsx-h";
 
 //#region src/jsx-runtime/element.d.ts
-declare function createElement(type: string | Component, {
-  ref,
-  ...props
-}?: JSX$1.IntrinsicAttributes & Record<string, unknown>): JSX$1.Element;
+declare function createElement(type: string | Component, allProps?: JSX$1.IntrinsicAttributes & Record<string, unknown>): JSX$1.Element;
 //#endregion
 //#region src/signals/lib.d.ts
 declare const SIGNAL: unique symbol;
@@ -111,6 +108,19 @@ declare function computed<T>(getter: (previousValue?: T) => T): () => T;
  * stop();            // final cleanup: abort the last fetch
  * ```
  */
+/**
+ * @internal Method key for settling a reactive async wrapper from a
+ * serialized server snapshot (hydration seeding). Lives here so
+ * `utilities/promise`, `utilities/async` and `hydrate` can share it without
+ * a utility-to-utility dependency.
+ */
+declare const SEED: unique symbol;
+/**
+ * @internal Method key for the hydrate claim protocol: the claim walk hands
+ * each async wrapper its ek-data record (or undefined). The wrapper decides —
+ * seed and discard any deferred run, or execute the deferred run now.
+ */
+declare const CLAIM: unique symbol;
 declare function effect(fn: () => void): () => void;
 /**
  * Creates an ownership scope that groups reactive effects so they can all be
@@ -333,142 +343,8 @@ type MaybeReactive<T> = T | Computed<T>;
  * ```
  */
 declare function resolve<T>(value: MaybeReactive<T>): T;
-/**
- * Turn a reactive-props object into a bag of per-key getters. Callers may
- * pass values or reactive sources (`signal`, `computed`); reading
- * `props.name()` inside an effect or JSX getter subscribes to whatever
- * drives it. Static values become stable thunks, signals and computed pass
- * through unchanged — so identity is preserved (`props.name === props.name`).
- *
- * The JSX runtime auto-applies this to function-component props — call
- * directly only for non-JSX call sites or nested prop bags.
- *
- * @example
- * ```ts
- * import { resolveProps } from "elements-kit/signals";
- * import { signal } from "elements-kit/signals";
- *
- * const count = signal(0);
- * const props = resolveProps({ count, label: "n" });
- * props.count();   // 0 — subscribes to count
- * props.label();   // "n"
- * ```
- */
 declare function resolveProps<P extends object>(raw: { [K in keyof P]: MaybeReactive<P[K]> }): ReactiveProps<P>;
 //#endregion
-//#region src/jsx-runtime/fragment.d.ts
-/**
- * Used by the JSX transform for `<>...</>` fragments.
- *
- * Each child is routed through `mountChild`, which handles Nodes, strings,
- * numbers, arrays, and reactive getters — matching the behavior of any other
- * JSX container. `mountChild` also wires each child's cleanup via its own
- * `effectScope`, which links to the enclosing `effectScope` created by
- * `createElement(Fragment, ...)` for disposal propagation.
- */
-declare function Fragment(props: {
-  children?: () => Child;
-}): DocumentFragment;
-//#endregion
-//#region src/jsx-runtime/index.d.ts
-/**
- * Maps slot names to `Child` content.
- * Use this to type `slot:name` JSX props on a custom component.
- *
- * @example
- * ```tsx
- * function Card(props: { title: string } & SlotProps<"header" | "footer">) { … }
- * // caller: <Card title="…" slot:header={<h1>…</h1>} slot:footer={<p>…</p>} />
- * ```
- */
-type SlotProps<K extends string> = { [P in K as `slot:${P}`]?: Child };
-/**
- * Get the full JSX prop types for a given tag name, including reactive
- * attributes, events, and all our namespace extensions.
- *
- * @example
- * ```ts
- * type InputProps = Attrs<"input">;   // typed props for <input>
- * type DivProps   = Attrs<"div">;     // typed props for <div>
- * ```
- */
-type Attrs<K extends keyof JSX$1.IntrinsicElements> = JSX$1.IntrinsicElements[K];
-/**
- * Namespaced JSX props added by elements-kit on top of dom-expressions.
- * All four are tag-aware via the element type `E`.
- *
- * - `ref` — callback invoked with the mounted element, typed as the concrete
- *   element class for intrinsics and registered custom elements.
- * - `class:foo` — open string + `MaybeReactive<boolean>`. Class names are
- *   user-defined CSS so the key stays open (no autocomplete possible).
- * - `style:cssProp` — keys mapped from `DomJSX.CSSProperties` (csstype's
- *   hyphenated property names) for autocomplete; value typed per-property.
- * - `prop:K` — inferred from `keyof E`. On `<div>` exposes
- *   `prop:className`, `prop:id`, etc. (from `HTMLDivElement`); on a
- *   registered custom element exposes its public fields too.
- *
- * `slot:foo` is NOT here — it's emitted per-element via `SlotsOf<C>` only
- * for elements that declare `[SLOTS]`. Plain HTML intrinsics don't accept
- * slot props (the runtime ignores them).
- */
-type CssStyleKey = Extract<keyof JSX.CSSProperties, string> extends infer K ? K extends `-${string}` ? never : K : never;
-type StyleNamespace = { [K in CssStyleKey as `style:${K}`]?: MaybeReactive<JSX.CSSProperties[K] | null> };
-type PropNamespace<E> = { [K in keyof E as K extends string ? `prop:${K}` : never]?: MaybeReactive<E[K]> };
-type JsxNamespaces<E extends Element = Element> = {
-  ref?: (el: E) => void;
-  [cls: `class:${string}`]: MaybeReactive<boolean>;
-} & StyleNamespace & PropNamespace<E>;
-type XlinkAttrs = {
-  "xlink:href"?: MaybeReactive<string | undefined>;
-  "xlink:title"?: MaybeReactive<string | undefined>;
-  "xlink:show"?: MaybeReactive<"new" | "replace" | "embed" | "other" | "none" | undefined>;
-  "xlink:role"?: MaybeReactive<string | undefined>;
-  "xlink:type"?: MaybeReactive<"simple" | "extended" | "locator" | "arc" | "resource" | "title" | undefined>;
-  "xlink:arcrole"?: MaybeReactive<string | undefined>;
-  "xlink:actuate"?: MaybeReactive<"onLoad" | "onRequest" | "other" | "none" | undefined>;
-};
-type XmlAttrs = {
-  "xml:lang"?: MaybeReactive<string | undefined>;
-  "xml:space"?: MaybeReactive<"default" | "preserve" | undefined>;
-  "xml:base"?: MaybeReactive<string | undefined>;
-};
-type SvgNamespaceAttrs = XlinkAttrs & XmlAttrs;
-type JsxNamespaceKeys = "ref" | `class:${string}` | `style:${string}` | `prop:${string}`;
-type WithJsxNamespaces<T, E extends Element = Element> = Omit<T, JsxNamespaceKeys> & JsxNamespaces<E>;
-type IntrinsicElementOf<T> = T extends {
-  ref?: infer R | undefined;
-} ? Extract<R, (el: any) => any> extends ((el: infer E) => any) ? E : Element : Element;
-declare namespace JSX$1 {
-  export type Element = globalThis.Element | globalThis.DocumentFragment | null;
-  export type ElementType = Child | Component;
-  export interface ElementChildrenAttribute {
-    children: {};
-  }
-  export interface IntrinsicAttributes {
-    ref?: (el: Element) => void;
-  }
-  export type LibraryManagedAttributes<C, P> = ResolveProps<C, P>;
-  type RegisteredElements = { [K in keyof CustomElementRegistry]: CustomElementRegistry[K] extends infer C extends AnyElementCtor ? WithJsxNamespaces<MaybeReactiveProps<ElementProps<C>>, InstanceType<C>> : never };
-  export type IntrinsicElements = { [K in keyof JSX.IntrinsicElements]: WithJsxNamespaces<JSX.IntrinsicElements[K], IntrinsicElementOf<JSX.IntrinsicElements[K]>> & (IntrinsicElementOf<JSX.IntrinsicElements[K]> extends SVGElement ? SvgNamespaceAttrs : {}) } & RegisteredElements;
-  export {};
-}
-//#endregion
-//#region src/jsx-runtime/types.d.ts
-/** An instance created by a component class — must expose `render()`. */
-interface ComponentInstance {
-  render(): JSX$1.Element;
-}
-/** A class whose constructor returns a ComponentInstance. */
-type ComponentClass<P extends Record<PropertyKey, unknown> = any> = new (props: P) => ComponentInstance;
-type ComponentFn<P extends Record<PropertyKey, unknown> = any> = (props: ReactiveProps<P>) => JSX$1.Element;
-/** Anything valid as the first arg to `createElement` / a JSX tag target. */
-type Component = NonNullable<JSX$1.Element> | ComponentClass | ComponentFn;
-/** A resolved runtime node — what `applyProps` / `applyChildren` operate on. */
-type PropsTarget = NonNullable<JSX$1.Element> | ComponentInstance;
-/** Anything that can appear as a JSX child. */
-type Child = PrimitiveNodeType | JSX$1.Element | AnyFn | Child[];
-type AnyFn = (...args: any[]) => Child;
-//#endregion
 //#region src/jsx-runtime/infer.d.ts
 type AnyElementCtor = abstract new (...args: any[]) => HTMLElement;
 type Inst<C> = C extends (abstract new (...args: any[]) => infer I) ? I : never;
@@ -681,4 +557,127 @@ type ComponentProps<C extends ComponentClass<any>> = C extends ComponentClass<in
  */
 type Props<C> = (C extends (abstract new (...args: any[]) => infer I) ? MaybeReactiveProps<InstanceProps<I>> : C extends ((props: infer P, ...rest: any[]) => any) ? P extends object ? MaybeReactiveProps<RawProps<P>> : {} : MaybeReactiveProps<InstanceProps<C>>) & SlotsOf<C>;
 //#endregion
-export { SIGNAL as A, signal as B, isReactive as C, COMPUTED as D, resolveProps as E, isComputed as F, untracked as H, isEffect as I, isEffectScope as L, computed as M, effect as N, EFFECT as O, effectScope as P, isSignal as R, Updater as S, resolve as T, createElement as U, trigger as V, SlotProps as _, RawProps as a, MaybeReactive as b, ResolveProps as c, ComponentClass as d, ComponentFn as f, JSX$1 as g, Attrs as h, Props as i, batch as j, EFFECT_SCOPE as k, Child as l, PropsTarget as m, ElementProps as n, ReactiveProps as o, ComponentInstance as p, MaybeReactiveProps as r, Require as s, ComponentProps as t, Component as u, Fragment as v, reactive as w, Signal as x, Computed as y, onCleanup as z };
+//#region src/jsx-runtime/fragment.d.ts
+/**
+ * Used by the JSX transform for `<>...</>` fragments.
+ *
+ * Each child is routed through `mountChild`, which handles Nodes, strings,
+ * numbers, arrays, and reactive getters — matching the behavior of any other
+ * JSX container. `mountChild` also wires each child's cleanup via its own
+ * `effectScope`, which links to the enclosing `effectScope` created by
+ * `createElement(Fragment, ...)` for disposal propagation.
+ *
+ * **Raw HTML mode** — `<Fragment html>{markup}</Fragment>`: the child is a
+ * `MaybeReactive<string>` rendered as markup inside a Slot region (comment
+ * markers), so the server renderer and the hydration claim pass share the
+ * region boundary. Reactive sources re-render the region on change. This is
+ * the library's only raw-HTML sink: the string is NOT escaped — sanitize
+ * untrusted input at the call site. `<script>` tags never execute.
+ */
+declare function Fragment(props: Props<{
+  children: Child;
+}> | {
+  html: true;
+  children: MaybeReactive<string>;
+}): DocumentFragment;
+//#endregion
+//#region src/jsx-runtime/index.d.ts
+/**
+ * Maps slot names to `Child` content.
+ * Use this to type `slot:name` JSX props on a custom component.
+ *
+ * @example
+ * ```tsx
+ * function Card(props: { title: string } & SlotProps<"header" | "footer">) { … }
+ * // caller: <Card title="…" slot:header={<h1>…</h1>} slot:footer={<p>…</p>} />
+ * ```
+ */
+type SlotProps<K extends string> = { [P in K as `slot:${P}`]?: Child };
+/**
+ * Get the full JSX prop types for a given tag name, including reactive
+ * attributes, events, and all our namespace extensions.
+ *
+ * @example
+ * ```ts
+ * type InputProps = Attrs<"input">;   // typed props for <input>
+ * type DivProps   = Attrs<"div">;     // typed props for <div>
+ * ```
+ */
+type Attrs<K extends keyof JSX$1.IntrinsicElements> = JSX$1.IntrinsicElements[K];
+/**
+ * Namespaced JSX props added by elements-kit on top of dom-expressions.
+ * All four are tag-aware via the element type `E`.
+ *
+ * - `ref` — callback invoked with the mounted element, typed as the concrete
+ *   element class for intrinsics and registered custom elements.
+ * - `class:foo` — open string + `MaybeReactive<boolean>`. Class names are
+ *   user-defined CSS so the key stays open (no autocomplete possible).
+ * - `style:cssProp` — keys mapped from `DomJSX.CSSProperties` (csstype's
+ *   hyphenated property names) for autocomplete; value typed per-property.
+ * - `prop:K` — inferred from `keyof E`. On `<div>` exposes
+ *   `prop:className`, `prop:id`, etc. (from `HTMLDivElement`); on a
+ *   registered custom element exposes its public fields too.
+ *
+ * `slot:foo` is NOT here — it's emitted per-element via `SlotsOf<C>` only
+ * for elements that declare `[SLOTS]`. Plain HTML intrinsics don't accept
+ * slot props (the runtime ignores them).
+ */
+type CssStyleKey = Extract<keyof JSX.CSSProperties, string> extends infer K ? K extends `-${string}` ? never : K : never;
+type StyleNamespace = { [K in CssStyleKey as `style:${K}`]?: MaybeReactive<JSX.CSSProperties[K] | null> };
+type PropNamespace<E> = { [K in keyof E as K extends string ? `prop:${K}` : never]?: MaybeReactive<E[K]> };
+type JsxNamespaces<E extends Element = Element> = {
+  ref?: (el: E) => void;
+  [cls: `class:${string}`]: MaybeReactive<boolean>;
+} & StyleNamespace & PropNamespace<E>;
+type XlinkAttrs = {
+  "xlink:href"?: MaybeReactive<string | undefined>;
+  "xlink:title"?: MaybeReactive<string | undefined>;
+  "xlink:show"?: MaybeReactive<"new" | "replace" | "embed" | "other" | "none" | undefined>;
+  "xlink:role"?: MaybeReactive<string | undefined>;
+  "xlink:type"?: MaybeReactive<"simple" | "extended" | "locator" | "arc" | "resource" | "title" | undefined>;
+  "xlink:arcrole"?: MaybeReactive<string | undefined>;
+  "xlink:actuate"?: MaybeReactive<"onLoad" | "onRequest" | "other" | "none" | undefined>;
+};
+type XmlAttrs = {
+  "xml:lang"?: MaybeReactive<string | undefined>;
+  "xml:space"?: MaybeReactive<"default" | "preserve" | undefined>;
+  "xml:base"?: MaybeReactive<string | undefined>;
+};
+type SvgNamespaceAttrs = XlinkAttrs & XmlAttrs;
+type JsxNamespaceKeys = "ref" | `class:${string}` | `style:${string}` | `prop:${string}`;
+type WithJsxNamespaces<T, E extends Element = Element> = Omit<T, JsxNamespaceKeys> & JsxNamespaces<E>;
+type IntrinsicElementOf<T> = T extends {
+  ref?: infer R | undefined;
+} ? Extract<R, (el: any) => any> extends ((el: infer E) => any) ? E : Element : Element;
+declare namespace JSX$1 {
+  export type Element = globalThis.Element | globalThis.DocumentFragment | null;
+  export type ElementType = Child | Component;
+  export interface ElementChildrenAttribute {
+    children: {};
+  }
+  export interface IntrinsicAttributes {
+    ref?: (el: Element) => void;
+  }
+  export type LibraryManagedAttributes<C, P> = ResolveProps<C, P>;
+  type RegisteredElements = { [K in keyof CustomElementRegistry]: CustomElementRegistry[K] extends infer C extends AnyElementCtor ? WithJsxNamespaces<MaybeReactiveProps<ElementProps<C>>, InstanceType<C>> : never };
+  export type IntrinsicElements = { [K in keyof JSX.IntrinsicElements]: WithJsxNamespaces<JSX.IntrinsicElements[K], IntrinsicElementOf<JSX.IntrinsicElements[K]>> & (IntrinsicElementOf<JSX.IntrinsicElements[K]> extends SVGElement ? SvgNamespaceAttrs : {}) } & RegisteredElements;
+  export {};
+}
+//#endregion
+//#region src/jsx-runtime/types.d.ts
+/** An instance created by a component class — must expose `render()`. */
+interface ComponentInstance {
+  render(): JSX$1.Element;
+}
+/** A class whose constructor returns a ComponentInstance. */
+type ComponentClass<P extends Record<PropertyKey, unknown> = any> = new (props: P) => ComponentInstance;
+type ComponentFn<P extends Record<PropertyKey, unknown> = any> = (props: ReactiveProps<P>) => JSX$1.Element;
+/** Anything valid as the first arg to `createElement` / a JSX tag target. */
+type Component = NonNullable<JSX$1.Element> | ComponentClass | ComponentFn;
+/** A resolved runtime node — what `applyProps` / `applyChildren` operate on. */
+type PropsTarget = NonNullable<JSX$1.Element> | ComponentInstance;
+/** Anything that can appear as a JSX child. */
+type Child = PrimitiveNodeType | JSX$1.Element | AnyFn | Child[];
+type AnyFn = (...args: any[]) => Child;
+//#endregion
+export { EFFECT_SCOPE as A, isSignal as B, isReactive as C, CLAIM as D, resolveProps as E, effect as F, createElement as G, signal as H, effectScope as I, isComputed as L, SIGNAL as M, batch as N, COMPUTED as O, computed as P, isEffect as R, Updater as S, resolve as T, trigger as U, onCleanup as V, untracked as W, Require as _, ComponentInstance as a, MaybeReactive as b, JSX$1 as c, ComponentProps as d, ElementProps as f, ReactiveProps as g, RawProps as h, ComponentFn as i, SEED as j, EFFECT as k, SlotProps as l, Props as m, Component as n, PropsTarget as o, MaybeReactiveProps as p, ComponentClass as r, Attrs as s, Child as t, Fragment as u, ResolveProps as v, reactive as w, Signal as x, Computed as y, isEffectScope as z };

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 };