@samirdamle/calipers 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Samir Damle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,74 @@
-# Temporary Holding Version
+# calipers
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A tiny, dependency-free JavaScript geometry toolkit for the web — measure, align, place, and design with HTML and SVG elements.
+
+```js
+import { measure, place } from '@samirdamle/calipers';
+
+// How far is the card from the hero?
+measure('.card', '.hero', { anchor: 'tl', ofAnchor: 'bl', fields: ['dy', 'gapY'] });
+// → { pointA: {…}, pointB: {…}, dy: -24, gapY: 24 }
+
+// Park the tooltip's top-center 8px below the button's bottom-center.
+place('.tooltip', {
+  anchor: 'tc',
+  at: { anchor: 'bc', of: '.button' },
+  offset: { y: 8 },
+});
+```
+
+## Install
+
+```sh
+npm i @samirdamle/calipers
+# pnpm add @samirdamle/calipers
+```
+
+Import only what you use — every module is a separate, tree-shakeable entry point:
+
+```js
+import { rectOf } from '@samirdamle/calipers/rect';
+import { measure, calipers, anchorPoint } from '@samirdamle/calipers/measure';
+import { place } from '@samirdamle/calipers/place';
+```
+
+## Modules
+
+| Import | Does | Size (min+br) |
+|---|---|---|
+| `@samirdamle/calipers/rect` | `rectOf` — resolve anything measurable into a rect, with an explicit box model and coordinate space | 863 B |
+| `@samirdamle/calipers/measure` | `measure` / `calipers` — pairwise geometry, plus a DOM-free pure core | 1723 B |
+| `@samirdamle/calipers/place` | `place` — position an element relative to a point or another element | 1444 B |
+| `@samirdamle/calipers/align` | `align` / `distribute` / `stack` — design-tool alignment, even spacing, and stacking | 1890 B |
+
+Sizes are measured from the actual build (see `size-budgets.json`); a stale figure is a bug.
+
+`fit` and the dev-only `debug` overlay are on the roadmap (plan §9–§10).
+
+## Anchors
+
+Every anchor resolves to exactly one point. The 13 codes are sugar over fractional points — `{ x: 0.25, y: 0 }` and `(rect) => point` work too.
+
+```
+tl ─── tc ─── tr
+│             │
+cl ─── cc ─── cr
+│             │
+bl ─── bc ─── br
+```
+
+`t`/`b`/`l`/`r` are the edge midpoints (`tc`/`bc`/`cl`/`cr`).
+
+## The one rule
+
+Every number names its **box** (`content` | `border` | `margin` | `visual` | `bbox`) and its **coordinate space** (`viewport` | `document`). No silent defaults that change meaning on scroll or under transforms.
+
+## Docs
+
+- [API reference](docs/API.md) — every function, field, and option
+- [Playground demo](https://samirdamle.github.io/calipers/demo/) — drag boxes, watch measurements update (or `pnpm demo` locally)
+- [Library plan](docs/plans/calipers-plan.md) and [goal](docs/meta/goal.md)
+
+## License
+
+MIT

package/dist/align.d.ts

@@ -0,0 +1,76 @@
+import { M as Measurable, B as Box, G as Gap } from './types-PJD4F9tg.js';
+
+type AlignEdge = 'left' | 'right' | 'top' | 'bottom' | 'center-x' | 'center-y';
+interface AlignOptions {
+    /**
+     * Reference to align to. Omit to align to the selection's extreme
+     * (edges) or mean (centers), design-tool style.
+     */
+    to?: Measurable;
+    /** Box model for measurement. @default 'border' */
+    box?: Box;
+}
+type DistributeAxis = 'x' | 'y';
+interface DistributeOptions {
+    /** Fixed gap in px. Omit for even spacing across the selection span. */
+    gap?: number;
+    /** Box model for measurement. @default 'border' */
+    box?: Box;
+}
+/**
+ * Align elements along one edge or centerline, moving each via the CSS
+ * `translate` property (accumulates across calls, composes with `transform`).
+ * Measurement includes each element's existing translate, so repeating the
+ * same call is a no-op instead of re-applying the delta.
+ */
+declare function align(els: ArrayLike<Element>, edge: AlignEdge, options?: AlignOptions): void;
+/**
+ * Spread elements evenly along an axis, in positional order, moving each via
+ * the CSS `translate` property. No-op for fewer than two elements.
+ * Measurement includes each element's existing translate, so repeating the
+ * same call is a no-op instead of re-applying the deltas.
+ */
+declare function distribute(els: ArrayLike<Element>, axis: DistributeAxis, options?: DistributeOptions): void;
+/** Which way a stack grows. */
+type StackDirection = 't' | 'b' | 'l' | 'r';
+/**
+ * Lateral alignment of stacked boxes, relative to the anchor box. Only the
+ * axis perpendicular to `direction` applies; anything else centers.
+ */
+type StackAlign = 't' | 'b' | 'l' | 'r' | 'c';
+interface StackOptions {
+    /**
+     * Reference to stack from (the source). Omit to stack from the selection's
+     * trailing extreme in the stacking direction — that element stays put and
+     * the rest pile after it.
+     */
+    to?: Measurable;
+    /** Which way the stack grows. @default 'b' */
+    direction?: StackDirection;
+    /**
+     * Gap between consecutive boxes. A single number is the axial separation
+     * (as before); `[x, y]` / `{ x, y }` keeps the axial meaning on the
+     * stacking axis and adds a per-step lateral cascade on the other —
+     * e.g. `gap: { x: 12, y: 10 }` with `direction: 'b'` stacks boxes 10px
+     * apart, each 12px further right: a staircase. @default 0
+     */
+    gap?: Gap;
+    /**
+     * Lateral alignment relative to the anchor box. @default 'c'
+     */
+    align?: StackAlign;
+    /** Box model for measurement. @default 'border' */
+    box?: Box;
+}
+/**
+ * Stack elements one after another from a reference, moving each via the CSS
+ * `translate` property (accumulates across calls, composes with `transform`).
+ * Targets are ordered nearest-the-anchor first along the stacking axis, so
+ * e.g. `stack(targets, { to: source, direction: 't', gap: 10, align: 'c' })`
+ * piles them upward from the source with 10px between consecutive boxes,
+ * center-aligned. Measurement includes each element's existing translate, so
+ * repeating the same call is a no-op.
+ */
+declare function stack(els: ArrayLike<Element>, options?: StackOptions): void;
+
+export { type AlignEdge, type AlignOptions, type DistributeAxis, type DistributeOptions, type StackAlign, type StackDirection, type StackOptions, align, distribute, stack };

package/dist/align.js

@@ -0,0 +1,321 @@
+// src/internal/dom.ts
+function isElement(v) {
+  return typeof Element !== "undefined" && v instanceof Element;
+}
+function px(value) {
+  const n = parseFloat(value);
+  return Number.isFinite(n) ? n : 0;
+}
+function parseTranslate(value) {
+  if (!value || value === "none") return { x: 0, y: 0 };
+  const [x = "0", y = "0"] = value.trim().split(/\s+/);
+  return { x: px(x), y: px(y) };
+}
+function getTranslate(el) {
+  return parseTranslate(getComputedStyle(el).translate);
+}
+function shiftTranslate(el, prev, dx, dy) {
+  if (dx === 0 && dy === 0) return;
+  el.style.setProperty("translate", `${prev.x + dx}px ${prev.y + dy}px`);
+}
+
+// src/internal/gap.ts
+function normalizeGap(gap) {
+  if (gap === void 0) return { x: 0, y: 0 };
+  if (typeof gap === "number") return { x: gap, y: gap };
+  if ("x" in gap) return { x: gap.x, y: gap.y };
+  return { x: gap[0], y: gap[1] };
+}
+
+// src/rect/index.ts
+function rectOf(target, options = {}) {
+  const { box = "border", space = "viewport" } = options;
+  const t = classify(target);
+  switch (t.kind) {
+    case "rect":
+      return { ...t.rect };
+    case "viewport":
+      return moveSpace(
+        {
+          x: 0,
+          y: 0,
+          width: window.innerWidth,
+          height: window.innerHeight
+        },
+        "viewport",
+        space
+      );
+    case "element":
+      return elementRect(t.el, box, space);
+  }
+}
+function classify(target) {
+  if (target === "viewport" || target === window) return { kind: "viewport" };
+  if (typeof target === "string") {
+    const el = document.querySelector(target);
+    if (!el)
+      throw new Error(`calipers: no element matches selector "${target}"`);
+    return { kind: "element", el };
+  }
+  if (isElement(target)) return { kind: "element", el: target };
+  if (isRectLike(target)) return { kind: "rect", rect: target };
+  if (isPointLike(target))
+    return {
+      kind: "rect",
+      rect: { x: target.x, y: target.y, width: 0, height: 0 }
+    };
+  const first = target[0];
+  if (first == null)
+    throw new Error("calipers: empty list has no measurable to resolve");
+  return classify(first);
+}
+function isPointLike(v) {
+  return typeof v === "object" && v !== null && typeof v.x === "number" && typeof v.y === "number" && typeof v.width !== "number";
+}
+function isRectLike(v) {
+  return typeof v === "object" && v !== null && typeof v.x === "number" && typeof v.y === "number" && typeof v.width === "number" && typeof v.height === "number";
+}
+function isSVGGraphics(el) {
+  return typeof SVGGraphicsElement !== "undefined" && el instanceof SVGGraphicsElement;
+}
+function elementRect(el, box, space) {
+  return isSVGGraphics(el) ? svgRect(el, box, space) : htmlRect(el, box, space);
+}
+function htmlRect(el, box, space) {
+  if (box === "visual") {
+    const r = el.getBoundingClientRect();
+    return moveSpace(
+      { x: r.x, y: r.y, width: r.width, height: r.height },
+      "viewport",
+      space
+    );
+  }
+  const border = layoutBorderBox(el);
+  const cs = getComputedStyle(el);
+  let rect;
+  if (box === "content") {
+    const bl = px(cs.borderLeftWidth);
+    const br = px(cs.borderRightWidth);
+    const bt = px(cs.borderTopWidth);
+    const bb = px(cs.borderBottomWidth);
+    const pl = px(cs.paddingLeft);
+    const pr = px(cs.paddingRight);
+    const pt = px(cs.paddingTop);
+    const pb = px(cs.paddingBottom);
+    rect = {
+      x: border.x + bl + pl,
+      y: border.y + bt + pt,
+      width: Math.max(0, border.width - bl - br - pl - pr),
+      height: Math.max(0, border.height - bt - bb - pt - pb)
+    };
+  } else if (box === "margin") {
+    const ml = px(cs.marginLeft);
+    const mr = px(cs.marginRight);
+    const mt = px(cs.marginTop);
+    const mb = px(cs.marginBottom);
+    rect = {
+      x: border.x - ml,
+      y: border.y - mt,
+      width: border.width + ml + mr,
+      height: border.height + mt + mb
+    };
+  } else {
+    rect = border;
+  }
+  return moveSpace(rect, "document", space);
+}
+function svgRect(el, box, space) {
+  if (box === "bbox") {
+    const b = el.getBBox();
+    return { x: b.x, y: b.y, width: b.width, height: b.height };
+  }
+  const r = el.getBoundingClientRect();
+  return moveSpace(
+    { x: r.x, y: r.y, width: r.width, height: r.height },
+    "viewport",
+    space
+  );
+}
+function layoutBorderBox(el) {
+  let x = 0;
+  let y = 0;
+  let node = el;
+  const fixed = getComputedStyle(el).position === "fixed";
+  while (node) {
+    x += node.offsetLeft;
+    y += node.offsetTop;
+    node = node.offsetParent;
+  }
+  if (fixed) {
+    x += window.scrollX;
+    y += window.scrollY;
+  }
+  return { x, y, width: el.offsetWidth, height: el.offsetHeight };
+}
+function moveSpace(rect, from, to) {
+  if (from === to) return rect;
+  const dx = from === "viewport" ? window.scrollX : -window.scrollX;
+  const dy = from === "viewport" ? window.scrollY : -window.scrollY;
+  return {
+    x: rect.x + dx,
+    y: rect.y + dy,
+    width: rect.width,
+    height: rect.height
+  };
+}
+
+// src/internal/rendered.ts
+function rendered(el, box) {
+  const rect = rectOf(el, { box, space: "viewport" });
+  const translate = getTranslate(el);
+  if (box === "visual" || translate.x === 0 && translate.y === 0) {
+    return { rect, translate };
+  }
+  return {
+    rect: { ...rect, x: rect.x + translate.x, y: rect.y + translate.y },
+    translate
+  };
+}
+
+// src/align/index.ts
+var pos = (r, ax) => ax === "x" ? r.x : r.y;
+var size = (r, ax) => ax === "x" ? r.width : r.height;
+var other = (ax) => ax === "x" ? "y" : "x";
+function toRect(to, box) {
+  return isElement(to) ? rendered(to, box).rect : rectOf(to, { box, space: "viewport" });
+}
+function mean(vals) {
+  return vals.reduce((a, b) => a + b, 0) / vals.length;
+}
+function align(els, edge, options = {}) {
+  const list = Array.from(els);
+  if (list.length === 0) return;
+  const box = options.box ?? "border";
+  const ax = edge === "left" || edge === "right" || edge === "center-x" ? "x" : "y";
+  const items = list.map((el) => ({ el, ...rendered(el, box) }));
+  const ref = options.to === void 0 ? null : toRect(options.to, box);
+  const line = ref !== null ? edgePos(edge, ref) : aggregate(
+    edge,
+    items.map((it) => edgePos(edge, it.rect))
+  );
+  for (const { el, rect, translate } of items) {
+    const delta = line - edgePos(edge, rect);
+    shiftTranslate(
+      el,
+      translate,
+      ax === "x" ? delta : 0,
+      ax === "y" ? delta : 0
+    );
+  }
+}
+function edgePos(edge, r) {
+  switch (edge) {
+    case "left":
+      return r.x;
+    case "right":
+      return r.x + r.width;
+    case "center-x":
+      return r.x + r.width / 2;
+    case "top":
+      return r.y;
+    case "bottom":
+      return r.y + r.height;
+    case "center-y":
+      return r.y + r.height / 2;
+  }
+}
+function aggregate(edge, vals) {
+  if (edge === "center-x" || edge === "center-y") return mean(vals);
+  return edge === "left" || edge === "top" ? Math.min(...vals) : Math.max(...vals);
+}
+function distribute(els, axis, options = {}) {
+  const list = Array.from(els);
+  if (list.length < 2) return;
+  const box = options.box ?? "border";
+  const ax = axis;
+  const items = list.map((el) => ({ el, ...rendered(el, box) })).sort((a, b) => pos(a.rect, ax) - pos(b.rect, ax));
+  const first = items[0].rect;
+  const last = items[items.length - 1].rect;
+  const span = pos(last, ax) + size(last, ax) - pos(first, ax);
+  const sizes = items.reduce((sum, it) => sum + size(it.rect, ax), 0);
+  const gap = options.gap ?? (span - sizes) / (items.length - 1);
+  let cursor = pos(first, ax);
+  for (const { el, rect, translate } of items) {
+    const delta = cursor - pos(rect, ax);
+    shiftTranslate(
+      el,
+      translate,
+      ax === "x" ? delta : 0,
+      ax === "y" ? delta : 0
+    );
+    cursor += size(rect, ax) + gap;
+  }
+}
+function stack(els, options = {}) {
+  const list = Array.from(els);
+  if (list.length === 0) return;
+  const box = options.box ?? "border";
+  const direction = options.direction ?? "b";
+  const lateral = options.align ?? "c";
+  const ax = direction === "t" || direction === "b" ? "y" : "x";
+  const forward = direction === "b" || direction === "r";
+  const gap = normalizeGap(options.gap);
+  const gapAx = ax === "x" ? gap.x : gap.y;
+  const gapLat = typeof options.gap === "number" || options.gap === void 0 ? 0 : ax === "x" ? gap.y : gap.x;
+  const items = list.map((el) => ({ el, ...rendered(el, box) }));
+  let anchorEl;
+  let anchorRect;
+  if (options.to !== void 0) {
+    const to = options.to;
+    anchorEl = isElement(to) ? to : null;
+    anchorRect = toRect(to, box);
+  } else {
+    anchorEl = items[0].el;
+    anchorRect = items[0].rect;
+    for (const it of items) {
+      if (moreTrailing(it.rect, anchorRect, ax, forward)) {
+        anchorEl = it.el;
+        anchorRect = it.rect;
+      }
+    }
+  }
+  const targets = items.filter((it) => it.el !== anchorEl).sort(
+    (a, b) => forward ? pos(a.rect, ax) - pos(b.rect, ax) : pos(b.rect, ax) + size(b.rect, ax) - (pos(a.rect, ax) + size(a.rect, ax))
+  );
+  if (targets.length === 0) return;
+  let cursor = forward ? pos(anchorRect, ax) + size(anchorRect, ax) + gapAx : pos(anchorRect, ax) - gapAx;
+  let step = 0;
+  for (const { el, rect, translate } of targets) {
+    step += 1;
+    const s = size(rect, ax);
+    const slot = forward ? cursor : cursor - s;
+    const delta = slot - pos(rect, ax);
+    const lat = lateralOffset(lateral, anchorRect, rect, ax) + step * gapLat;
+    shiftTranslate(
+      el,
+      translate,
+      ax === "x" ? delta : lat,
+      ax === "y" ? delta : lat
+    );
+    cursor = forward ? slot + s + gapAx : slot - gapAx;
+  }
+}
+function moreTrailing(r, best, ax, forward) {
+  const e = forward ? pos(r, ax) : pos(r, ax) + size(r, ax);
+  const b = forward ? pos(best, ax) : pos(best, ax) + size(best, ax);
+  return forward ? e < b : e > b;
+}
+function lateralOffset(lateral, anchor, r, ax) {
+  const p = other(ax);
+  const leading = p === "x" ? "l" : "t";
+  const trailing = p === "x" ? "r" : "b";
+  const a0 = pos(anchor, p);
+  const a1 = a0 + size(anchor, p);
+  const r0 = pos(r, p);
+  const r1 = r0 + size(r, p);
+  if (lateral === leading) return a0 - r0;
+  if (lateral === trailing) return a1 - r1;
+  return (a0 + a1) / 2 - (r0 + r1) / 2;
+}
+
+export { align, distribute, stack };

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { AlignEdge, AlignOptions, DistributeAxis, DistributeOptions, StackAlign, StackDirection, StackOptions, align, distribute, stack } from './align.js';
+export { Field, MeasureOptions, MeasureResult, anchorPoint, angleBetween, calipers, containsRect, distanceBetween, gapBetween, measure, overlapArea, overlaps } from './measure.js';
+export { PlaceAt, PlaceOptions, place } from './place.js';
+export { RectOptions, rectOf } from './rect.js';
+export { A as Anchor, a as AnchorCode, B as Box, G as Gap, M as Measurable, P as Point, R as Rect, S as Space } from './types-PJD4F9tg.js';