elements-kit 0.27.9 → 0.27.11

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

@@ -7,6 +7,10 @@ type Axis = keyof ReadonlyBox;
 interface IDirection {
   readonly direction: "ltr" | "rtl";
 }
+interface Point {
+  x: number;
+  y: number;
+}
 interface ReadonlyBox {
   readonly x: number;
   readonly y: number;
@@ -78,28 +82,31 @@ type NoInline = {
  * both edges of one axis.
  */
 type Boundary = (BlockEdge & InlineEdge) | (BlockEdge & NoInline) | (NoBlock & InlineEdge);
-/** Where {@link Region.place} puts a box's top-left corner. */
-interface Placement {
-  readonly x: number;
-  readonly y: number;
+/** Horizontal origin keyword, as CSS spells it. */
+type OriginX = "left" | "center" | "right";
+/** The vertical one. */
+type OriginY = "top" | "center" | "bottom";
+/** Which point of a box lands on its position. A `transform-origin`. */
+interface Origin {
+  readonly x: OriginX;
+  readonly y: OriginY;
+}
+/** Has an origin. */
+interface IOrigin {
+  readonly origin: Origin;
 }
 /**
- * Somewhere a box may go: a semi-bounded plane, each axis pinned or free.
- * `place` is the only operation: it never writes, so the caller picks which
- * channels to take — `box.x = region.place(box).x` moves one axis and leaves
- * the rest. Size is never returned: the box is placed as given, so one larger
- * than its room overflows rather than shrinks, as CSS does.
+ * Somewhere a box may go: each axis pinned or free. `place` never writes, so
+ * the caller takes the channels it wants, and never returns a size, so a box
+ * larger than its room overflows rather than shrinks, as CSS does.
  *
- * The four insets read back as CSS would want them: the pinned edge's
- * coordinate, `null` for the other three (`auto`). A centred axis is not an
- * inset — both its edges are `null`.
+ * `x`/`y` are the pin lines, `origin` the box point landing on them — the
+ * pair places a box without measuring it. A free axis has no pin (`null`).
  */
-interface Region {
-  readonly left: number | null;
-  readonly right: number | null;
-  readonly top: number | null;
-  readonly bottom: number | null;
-  place(box: ReadonlyBox): Placement;
+interface Region extends IOrigin {
+  readonly x: number | null;
+  readonly y: number | null;
+  place(box: ReadonlyBox): Point;
 }
 /**
  * A {@link Region} driven by writes — for gestures, where the box grows away
@@ -109,6 +116,11 @@ interface Region {
 declare class MutableRegion implements Region {
   #private;
   constructor(boundary: Boundary);
+  /** The pin line on each axis — `null` where the axis is free. */
+  get x(): number | null;
+  get y(): number | null;
+  /** The box point that lands on ({@link x}, {@link y}). */
+  get origin(): Origin;
   get left(): number | null;
   get right(): number | null;
   get top(): number | null;
@@ -117,7 +129,7 @@ declare class MutableRegion implements Region {
   set right(v: number | null);
   set top(v: number | null);
   set bottom(v: number | null);
-  place(box: ReadonlyBox): Placement;
+  place(box: ReadonlyBox): Point;
 }
 //#endregion
 //#region src/ui/overlay/anchor.d.ts
@@ -162,39 +174,29 @@ type Unordered<A extends string, B extends string> = `${A} ${B}` | `${B} ${A}`;
  */
 type PositionAreaValue = AreaKeyword | Unordered<BlockKeyword, InlineKeyword> | Unordered<BlockKeyword, AmbiguousKeyword> | Unordered<InlineKeyword, AmbiguousKeyword> | `${AmbiguousKeyword} ${AmbiguousKeyword}`;
 /**
- * The reactive `position-area` property: the region of the viewport an
- * overlay anchored to `anchor` may occupy, with the region's default
- * self-alignment as {@link Region.place} — outward regions hug the anchor,
- * spans go flush against its far edge, center is `anchor-center`. Nothing is
- * written; the caller takes what it wants from `place`:
- *
- *   const area = new PositionArea(a, "top span-left");
- *   effect(() => { overlay.x = area.place(overlay).x; });
+ * The reactive `position-area` property: which of the anchor's edges a box
+ * pins to, and the self-alignment that follows — outward regions hug the
+ * anchor's near edge, spans its far edge, center is `anchor-center`. Not a
+ * box: a pin per axis, with no geometry of its own.
  *
- * The value is parsed once, at construction; the geometry reads the anchor
- * and window on every access, so reading it inside an `effect` tracks both.
+ * Parsed once, at construction; the pins read the anchor on every access, so
+ * reading them in an `effect` tracks it.
  *
- * Bounded by the window. A tighter bound (a `Constraint`, a scroll container)
- * is an intersection with the region, so it composes afterwards rather than
- * being a parameter here.
- *
- * There is no gap parameter, for the same reason CSS has none: the offset off
- * the anchor is the overlay's own `margin`.
+ * No gap parameter, for the same reason CSS has none: the offset off the
+ * anchor is the overlay's own `margin`.
  */
-declare class PositionArea implements Region, ReadonlyBox {
+declare class PositionArea implements Region {
   #private;
   readonly anchor: ReadonlyBox;
   constructor(anchor: ReadonlyBox, area: PositionAreaValue);
+  /** The pin lines — the viewport point {@link origin} lands on. */
   get x(): number;
   get y(): number;
-  get w(): number;
-  get h(): number;
-  get left(): number | null;
-  get right(): number | null;
-  get top(): number | null;
-  get bottom(): number | null;
+  /** The box point landing on ({@link x}, {@link y}). Two axes, not one
+   * side: a corner area pins a corner. */
+  get origin(): Origin;
   /** Every axis is pinned, so only the box's size is read. */
-  place(box: Pick<ReadonlyBox, "w" | "h">): Placement;
+  place(box: Pick<ReadonlyBox, "w" | "h">): Point;
 }
 //#endregion
 //#region src/ui/overlay/overlay.d.ts
@@ -224,10 +226,16 @@ declare class Displacement extends PartialBox {
   apply(): void;
   clear(): void;
 }
-declare class OverlayBox extends TransformableBox implements IDirection {
+declare class OverlayBox extends TransformableBox implements IDirection, IOrigin {
   #private;
   readonly element: HTMLElement;
   constructor(element: HTMLElement);
+  /** The box point that lands on (x, y), and the scale's origin. */
+  get origin(): Origin;
+  set origin({
+    x,
+    y
+  }: Origin);
   get w(): number;
   set w(value: number);
   get h(): number;
@@ -283,4 +291,4 @@ declare class Motion implements IMotion {
   abort(initial?: number): void;
 }
 //#endregion
-export { type Align, type Axis, type BlockSide, type Boundary, ElementBox, gestures_d_exports as Gestures, type IDirection, type IMotion, type InlineSide, type Inset, Motion, MutableRegion, OverlayBox, type PhysicalInset, type Pin, type Placement, PositionArea, type PositionAreaValue, type ReadonlyBox, type Region, WINDOW_BOX, WindowBox, anchor_length };
+export { type Align, type Axis, type BlockSide, type Boundary, ElementBox, gestures_d_exports as Gestures, type IDirection, type IMotion, type IOrigin, type InlineSide, type Inset, Motion, MutableRegion, type Origin, type OriginX, type OriginY, OverlayBox, type PhysicalInset, type Pin, PositionArea, type PositionAreaValue, type ReadonlyBox, type Region, WINDOW_BOX, WindowBox, anchor_length };

package/dist/ui/overlay/index.mjs

@@ -12,10 +12,20 @@ function placePinned(pin, n) {
 	if (pin.align === "end") return pin.at - n;
 	return pin.at - n / 2;
 }
-/** One axis of a {@link Region.place}: pinned, or `own` if the axis is free. */
+/** One axis of {@link Region.place}: pinned, or `own` if free. */
 function placeAxis(pin, own, n) {
 	return pin ? placePinned(pin, n) : own;
 }
+/** The box point a pin lands. Physical: direction is resolved before a pin
+* exists, so `left` is left in RTL. A free axis lands the near edge. */
+function originX(pin) {
+	if (!pin) return "left";
+	return pin.align === "start" ? "left" : pin.align === "end" ? "right" : "center";
+}
+function originY(pin) {
+	if (!pin) return "top";
+	return pin.align === "start" ? "top" : pin.align === "end" ? "bottom" : "center";
+}
 /** The inset a pin yields on one edge: its coordinate if it pins that edge. */
 function inset(pin, edge) {
 	return pin?.align === edge ? pin.at : null;
@@ -35,6 +45,20 @@ var MutableRegion = class {
 		if (top !== void 0) this.top = top;
 		if (bottom !== void 0) this.bottom = bottom;
 	}
+	/** The pin line on each axis — `null` where the axis is free. */
+	get x() {
+		return this.#x()?.at ?? null;
+	}
+	get y() {
+		return this.#y()?.at ?? null;
+	}
+	/** The box point that lands on ({@link x}, {@link y}). */
+	get origin() {
+		return {
+			x: originX(this.#x()),
+			y: originY(this.#y())
+		};
+	}
 	get left() {
 		return inset(this.#x(), "start");
 	}
@@ -79,47 +103,6 @@ var MutableRegion = class {
 	}
 };
 //#endregion
-//#region src/ui/overlay/box.ts
-var WindowBox = class {
-	get x() {
-		return 0;
-	}
-	get y() {
-		return 0;
-	}
-	get w() {
-		return windowSize.width();
-	}
-	get h() {
-		return windowSize.height();
-	}
-	get direction() {
-		return direction();
-	}
-};
-const WINDOW_BOX = new WindowBox();
-var ElementBox = class {
-	#rect;
-	constructor(el) {
-		this.#rect = createElementRect(el);
-	}
-	[Symbol.dispose]() {
-		this.#rect[Symbol.dispose]();
-	}
-	get x() {
-		return this.#rect().left;
-	}
-	get y() {
-		return this.#rect().top;
-	}
-	get w() {
-		return this.#rect().width;
-	}
-	get h() {
-		return this.#rect().height;
-	}
-};
-//#endregion
 //#region src/ui/overlay/anchor.ts
 /**
 * The reactive `anchor()` function: the viewport coordinate of an anchor line
@@ -280,37 +263,17 @@ function resolveArea(area, dir = "ltr", selfDir = dir) {
 		inline: inline ? toPhysical(inline, "inline", dir, selfDir) : "center"
 	};
 }
-/** One axis of the position-area containing block, as `[lo, hi]` viewport
-* coordinates. The anchor's two edges cut `[bLo, bHi]` into before/over/after. */
-function axisSpan(lo, hi, bLo, bHi, region) {
-	switch (region) {
-		case "start": return [bLo, lo];
-		case "end": return [hi, bHi];
-		case "center": return [lo, hi];
-		case "span-start": return [bLo, hi];
-		case "span-end": return [lo, bHi];
-		default: return [bLo, bHi];
-	}
-}
 /**
-* The reactive `position-area` property: the region of the viewport an
-* overlay anchored to `anchor` may occupy, with the region's default
-* self-alignment as {@link Region.place} — outward regions hug the anchor,
-* spans go flush against its far edge, center is `anchor-center`. Nothing is
-* written; the caller takes what it wants from `place`:
-*
-*   const area = new PositionArea(a, "top span-left");
-*   effect(() => { overlay.x = area.place(overlay).x; });
+* The reactive `position-area` property: which of the anchor's edges a box
+* pins to, and the self-alignment that follows — outward regions hug the
+* anchor's near edge, spans its far edge, center is `anchor-center`. Not a
+* box: a pin per axis, with no geometry of its own.
 *
-* The value is parsed once, at construction; the geometry reads the anchor
-* and window on every access, so reading it inside an `effect` tracks both.
+* Parsed once, at construction; the pins read the anchor on every access, so
+* reading them in an `effect` tracks it.
 *
-* Bounded by the window. A tighter bound (a `Constraint`, a scroll container)
-* is an intersection with the region, so it composes afterwards rather than
-* being a parameter here.
-*
-* There is no gap parameter, for the same reason CSS has none: the offset off
-* the anchor is the overlay's own `margin`.
+* No gap parameter, for the same reason CSS has none: the offset off the
+* anchor is the overlay's own `margin`.
 */
 var PositionArea = class {
 	anchor;
@@ -319,18 +282,6 @@ var PositionArea = class {
 		this.anchor = anchor;
 		this.#area = resolveArea(area, rootDirection());
 	}
-	/** The inline axis as `[lo, hi]`, re-read from the anchor and window. */
-	get #ix() {
-		const a = this.anchor;
-		const w = WINDOW_BOX;
-		return axisSpan(a.x, a.x + a.w, w.x, w.x + w.w, this.#area.inline);
-	}
-	/** The block axis as `[lo, hi]`. */
-	get #iy() {
-		const a = this.anchor;
-		const w = WINDOW_BOX;
-		return axisSpan(a.y, a.y + a.h, w.y, w.y + w.h, this.#area.block);
-	}
 	get #px() {
 		const a = this.anchor;
 		return pinOf(this.#area.inline, a.x, a.x + a.w);
@@ -339,31 +290,20 @@ var PositionArea = class {
 		const a = this.anchor;
 		return pinOf(this.#area.block, a.y, a.y + a.h);
 	}
+	/** The pin lines — the viewport point {@link origin} lands on. */
 	get x() {
-		return this.#ix[0];
+		return this.#px.at;
 	}
 	get y() {
-		return this.#iy[0];
+		return this.#py.at;
 	}
-	get w() {
-		const [lo, hi] = this.#ix;
-		return hi - lo;
-	}
-	get h() {
-		const [lo, hi] = this.#iy;
-		return hi - lo;
-	}
-	get left() {
-		return inset(this.#px, "start");
-	}
-	get right() {
-		return inset(this.#px, "end");
-	}
-	get top() {
-		return inset(this.#py, "start");
-	}
-	get bottom() {
-		return inset(this.#py, "end");
+	/** The box point landing on ({@link x}, {@link y}). Two axes, not one
+	* side: a corner area pins a corner. */
+	get origin() {
+		return {
+			x: originX(this.#px),
+			y: originY(this.#py)
+		};
 	}
 	/** Every axis is pinned, so only the box's size is read. */
 	place(box) {
@@ -401,6 +341,47 @@ function pinOf(region, lo, hi) {
 	}
 }
 //#endregion
+//#region src/ui/overlay/box.ts
+var WindowBox = class {
+	get x() {
+		return 0;
+	}
+	get y() {
+		return 0;
+	}
+	get w() {
+		return windowSize.width();
+	}
+	get h() {
+		return windowSize.height();
+	}
+	get direction() {
+		return direction();
+	}
+};
+const WINDOW_BOX = new WindowBox();
+var ElementBox = class {
+	#rect;
+	constructor(el) {
+		this.#rect = createElementRect(el);
+	}
+	[Symbol.dispose]() {
+		this.#rect[Symbol.dispose]();
+	}
+	get x() {
+		return this.#rect().left;
+	}
+	get y() {
+		return this.#rect().top;
+	}
+	get w() {
+		return this.#rect().width;
+	}
+	get h() {
+		return this.#rect().height;
+	}
+};
+//#endregion
 //#region src/ui/overlay/overlay.ts
 var __create = Object.create;
 var __defProp = Object.defineProperty;
@@ -560,16 +541,27 @@ var Displacement = class extends PartialBox {
 		});
 	}
 };
+const OFFSET = {
+	left: "0%",
+	top: "0%",
+	center: "50%",
+	right: "100%",
+	bottom: "100%"
+};
 var OverlayBox = class extends TransformableBox {
 	element;
 	#rect;
+	#origin = {
+		x: "left",
+		y: "top"
+	};
 	constructor(element) {
 		super();
 		this.element = element;
 		this.#rect = createElementRect(element);
 		element.style.setProperty("top", "0");
 		element.style.setProperty("left", "0");
-		element.style.setProperty("translate", "calc(var(--x, 0px) + var(--dx, 0px) + var(--_ex, 0px)) calc(var(--y, 0px) + var(--dy, 0px) + var(--_ey, 0px))");
+		element.style.setProperty("translate", "calc(var(--x, 0px) + var(--dx, 0px) + var(--_ex, 0px) - var(--_ox, 0%)) calc(var(--y, 0px) + var(--dy, 0px) + var(--_ey, 0px) - var(--_oy, 0%))");
 		const [, stop] = scope(() => {
 			effect(() => {
 				this.#project("--x", this.transform.x);
@@ -595,6 +587,19 @@ var OverlayBox = class extends TransformableBox {
 			this.#rect[Symbol.dispose]();
 		};
 	}
+	/** The box point that lands on (x, y), and the scale's origin. */
+	get origin() {
+		return this.#origin;
+	}
+	set origin({ x, y }) {
+		this.#origin = {
+			x,
+			y
+		};
+		this.element.style.setProperty("--_ox", OFFSET[x]);
+		this.element.style.setProperty("--_oy", OFFSET[y]);
+		this.element.style.transformOrigin = `${x} ${y}`;
+	}
 	/** Write a size channel, or unset it when the axis is AUTO (NaN) so the
 	* element falls back to content sizing (`var(--w, auto)`). */
 	#project(name, ...value) {

package/dist/utilities/element-rect.d.mts

@@ -2,19 +2,14 @@ import { r as MaybeReactive, t as Computed } from "../index-BSAqa0-0.mjs";
 
 //#region src/utilities/element-rect.d.ts
 /**
- * Observes the full bounding rect of `target` and returns it as ONE reactive
- * `DOMRect`, so every field a reader sees was measured at the same instant.
- * Change sources: a `ResizeObserver` for size, plus capture-phase `scroll` and
- * window `resize` for position — a `ResizeObserver` stays silent when an
- * element merely moves.
+ * `target`'s bounding rect as one reactive `DOMRect`, every field from the
+ * same instant. Refreshed by a `ResizeObserver` (size) and capture-phase
+ * `scroll` / window `resize` (position), never on read. Size is the observer's
+ * border box, not the rect's: a transform scales the rect and never fires the
+ * observer.
  *
- * `target` may be a getter, in which case the observer follows it: the previous
- * element is unobserved before the new one is observed. The returned computed
- * keeps its identity across a swap, so consumers never rebind.
- *
- * The value is CACHED, not measured per read: it refreshes when one of the
- * sources above fires, not at the moment you read it. Dispose explicitly, or
- * let the enclosing scope do it.
+ * A reactive `target` is followed, keeping the computed's identity. Dispose
+ * explicitly, or let the enclosing scope do it.
  */
 declare function createElementRect(target: MaybeReactive<Element>): Computed<DOMRect> & Disposable;
 //#endregion

package/dist/utilities/element-rect.mjs

@@ -3,30 +3,38 @@ import { resolve } from "../signals/index.mjs";
 import { createResizeObserver } from "./resize-observer.mjs";
 //#region src/utilities/element-rect.ts
 /**
-* Observes the full bounding rect of `target` and returns it as ONE reactive
-* `DOMRect`, so every field a reader sees was measured at the same instant.
-* Change sources: a `ResizeObserver` for size, plus capture-phase `scroll` and
-* window `resize` for position — a `ResizeObserver` stays silent when an
-* element merely moves.
+* `target`'s bounding rect as one reactive `DOMRect`, every field from the
+* same instant. Refreshed by a `ResizeObserver` (size) and capture-phase
+* `scroll` / window `resize` (position), never on read. Size is the observer's
+* border box, not the rect's: a transform scales the rect and never fires the
+* observer.
 *
-* `target` may be a getter, in which case the observer follows it: the previous
-* element is unobserved before the new one is observed. The returned computed
-* keeps its identity across a swap, so consumers never rebind.
-*
-* The value is CACHED, not measured per read: it refreshes when one of the
-* sources above fires, not at the moment you read it. Dispose explicitly, or
-* let the enclosing scope do it.
+* A reactive `target` is followed, keeping the computed's identity. Dispose
+* explicitly, or let the enclosing scope do it.
 */
 function createElementRect(target) {
-	const cache = signal(resolve(target).getBoundingClientRect());
+	let size;
+	const read = (el) => {
+		const r = el.getBoundingClientRect();
+		return size ? new DOMRect(r.x, r.y, size.width, size.height) : r;
+	};
+	const cache = signal(read(resolve(target)));
 	const updateRect = (el) => {
-		cache(el.getBoundingClientRect());
+		cache(read(el));
 	};
 	const stop = effectScope(() => {
 		effect(() => {
 			const el = resolve(target);
+			size = void 0;
 			createResizeObserver(el, (entries) => {
-				for (const entry of entries) updateRect(entry.target);
+				for (const entry of entries) {
+					const box = entry.borderBoxSize?.[0];
+					if (box) size = {
+						width: box.inlineSize,
+						height: box.blockSize
+					};
+					updateRect(entry.target);
+				}
 			});
 			const remeasure = () => updateRect(el);
 			window.addEventListener("scroll", remeasure, {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "elements-kit",
   "type": "module",
-  "version": "0.27.9",
+  "version": "0.27.11",
   "description": "A lightweight reactive UI library that transforms native HTMLElements into reactive components with signals. Ideal for framework-agnostic applications and web components.",
   "keywords": [
     "webcomponents",