elements-kit 0.27.7 → 0.27.9

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

@@ -78,12 +78,17 @@ 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;
+}
 /**
  * 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. The box is placed as given: one larger than its room overflows
- * rather than shrinks, as CSS does.
+ * 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.
  *
  * 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
@@ -94,7 +99,7 @@ interface Region {
   readonly right: number | null;
   readonly top: number | null;
   readonly bottom: number | null;
-  place(box: ReadonlyBox): Box;
+  place(box: ReadonlyBox): Placement;
 }
 /**
  * A {@link Region} driven by writes — for gestures, where the box grows away
@@ -112,7 +117,7 @@ declare class MutableRegion implements Region {
   set right(v: number | null);
   set top(v: number | null);
   set bottom(v: number | null);
-  place(box: ReadonlyBox): Box;
+  place(box: ReadonlyBox): Placement;
 }
 //#endregion
 //#region src/ui/overlay/anchor.d.ts
@@ -139,6 +144,23 @@ type Inset = PhysicalInset | "inset-block-start" | "inset-block-end" | "inset-in
  * box's reactive geometry, so calling it inside an `effect` tracks the anchor.
  */
 declare function anchor_length(box: Box & Partial<IDirection>, inset: Inset, side: BlockSide | InlineSide | number): number;
+/** Keywords naming the block axis. */
+type BlockKeyword = "top" | "bottom" | "span-top" | "span-bottom" | "block-start" | "block-end" | "span-block-start" | "span-block-end" | "y-start" | "y-end" | "span-y-start" | "span-y-end";
+/** Keywords naming the inline axis. */
+type InlineKeyword = "left" | "right" | "span-left" | "span-right" | "inline-start" | "inline-end" | "span-inline-start" | "span-inline-end" | "x-start" | "x-end" | "span-x-start" | "span-x-end";
+/** Keywords naming no axis — each takes whichever one is still free. */
+type AmbiguousKeyword = "center" | "span-all" | "start" | "end" | "span-start" | "span-end" | "self-start" | "self-end" | "span-self-start" | "span-self-end";
+type AreaKeyword = BlockKeyword | InlineKeyword | AmbiguousKeyword;
+/** Two keywords, in either order — `position-area` is unordered. */
+type Unordered<A extends string, B extends string> = `${A} ${B}` | `${B} ${A}`;
+/**
+ * A valid `position-area` value: one keyword, or two naming different axes.
+ * Two of the same explicit axis (`top bottom`, `left right`) is not a value —
+ * {@link resolveArea} resolves anything invalid to the `block-end` fallback,
+ * so catching it here is the difference between a compile error and a menu
+ * that quietly opens on the wrong side.
+ */
+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
@@ -162,7 +184,7 @@ declare function anchor_length(box: Box & Partial<IDirection>, inset: Inset, sid
 declare class PositionArea implements Region, ReadonlyBox {
   #private;
   readonly anchor: ReadonlyBox;
-  constructor(anchor: ReadonlyBox, area: string);
+  constructor(anchor: ReadonlyBox, area: PositionAreaValue);
   get x(): number;
   get y(): number;
   get w(): number;
@@ -172,7 +194,7 @@ declare class PositionArea implements Region, ReadonlyBox {
   get top(): number | null;
   get bottom(): number | null;
   /** Every axis is pinned, so only the box's size is read. */
-  place(box: Pick<ReadonlyBox, "w" | "h">): Box;
+  place(box: Pick<ReadonlyBox, "w" | "h">): Placement;
 }
 //#endregion
 //#region src/ui/overlay/overlay.d.ts
@@ -261,4 +283,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, PositionArea, 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 InlineSide, type Inset, Motion, MutableRegion, OverlayBox, type PhysicalInset, type Pin, type Placement, PositionArea, type PositionAreaValue, type ReadonlyBox, type Region, WINDOW_BOX, WindowBox, anchor_length };

package/dist/ui/overlay/index.mjs

@@ -74,9 +74,7 @@ var MutableRegion = class {
 	place(box) {
 		return {
 			x: placeAxis(this.#x(), box.x, box.w),
-			y: placeAxis(this.#y(), box.y, box.h),
-			w: box.w,
-			h: box.h
+			y: placeAxis(this.#y(), box.y, box.h)
 		};
 	}
 };
@@ -183,7 +181,8 @@ const A = (region, self = false) => ({
 	physical: false,
 	self
 });
-/** The full `position-area` keyword grammar → axis + physical region. */
+/** The full `position-area` keyword grammar → axis + physical region. The
+* key type forces this table and {@link PositionAreaValue} to stay in step. */
 const KEYWORDS = {
 	top: B("start", true),
 	bottom: B("end", true),
@@ -370,9 +369,7 @@ var PositionArea = class {
 	place(box) {
 		return {
 			x: placePinned(this.#px, box.w),
-			y: placePinned(this.#py, box.h),
-			w: box.w,
-			h: box.h
+			y: placePinned(this.#py, box.h)
 		};
 	}
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "elements-kit",
   "type": "module",
-  "version": "0.27.7",
+  "version": "0.27.9",
   "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",