@samirdamle/calipers 0.0.0-stage → 0.1.0

package/dist/index.js

@@ -0,0 +1,524 @@
+// 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;
+}
+
+// src/geom/index.ts
+var ANCHOR_FRACTIONS = {
+  tl: [0, 0],
+  tc: [0.5, 0],
+  tr: [1, 0],
+  cl: [0, 0.5],
+  cc: [0.5, 0.5],
+  cr: [1, 0.5],
+  bl: [0, 1],
+  bc: [0.5, 1],
+  br: [1, 1],
+  t: [0.5, 0],
+  b: [0.5, 1],
+  l: [0, 0.5],
+  r: [1, 0.5]
+};
+function anchorPoint(rect, anchor = "cc") {
+  if (typeof anchor === "function") return anchor(rect);
+  const [fx, fy] = typeof anchor === "string" ? ANCHOR_FRACTIONS[anchor] : "x" in anchor ? [anchor.x, anchor.y] : anchor;
+  return { x: rect.x + fx * rect.width, y: rect.y + fy * rect.height };
+}
+function distanceBetween(a, b) {
+  return Math.hypot(a.x - b.x, a.y - b.y);
+}
+function angleBetween(from, to) {
+  return Math.atan2(to.y - from.y, to.x - from.x);
+}
+function gapBetween(a, b) {
+  return {
+    x: Math.max(0, Math.max(b.x - (a.x + a.width), a.x - (b.x + b.width))),
+    y: Math.max(0, Math.max(b.y - (a.y + a.height), a.y - (b.y + b.height)))
+  };
+}
+function overlapArea(a, b) {
+  const w = Math.min(a.x + a.width, b.x + b.width) - Math.max(a.x, b.x);
+  const h = Math.min(a.y + a.height, b.y + b.height) - Math.max(a.y, b.y);
+  return Math.max(0, w) * Math.max(0, h);
+}
+function overlaps(a, b) {
+  return overlapArea(a, b) > 0;
+}
+function containsRect(outer, inner) {
+  return outer.x <= inner.x && outer.y <= inner.y && outer.x + outer.width >= inner.x + inner.width && outer.y + outer.height >= inner.y + inner.height;
+}
+
+// src/measure/index.ts
+var ALL_FIELDS = [
+  "dx",
+  "dy",
+  "distance",
+  "gapX",
+  "gapY",
+  "angleDeg",
+  "angleRad",
+  "width",
+  "height",
+  "overlaps",
+  "overlapArea",
+  "contains",
+  "visible"
+];
+function measure(a, b, options = {}) {
+  const {
+    anchor = "cc",
+    ofAnchor = "cc",
+    fields = ALL_FIELDS,
+    box,
+    space
+  } = options;
+  const rectOptions = { box, space };
+  const ra = rectOf(a, rectOptions);
+  const rb = rectOf(b, rectOptions);
+  const pointA = anchorPoint(ra, anchor);
+  const pointB = anchorPoint(rb, ofAnchor);
+  const result = { target: a, source: b, pointA, pointB };
+  const want = new Set(fields);
+  if (want.has("dx") || want.has("dy") || want.has("distance") || want.has("angleDeg") || want.has("angleRad")) {
+    const dx = pointA.x - pointB.x;
+    const dy = pointA.y - pointB.y;
+    if (want.has("dx")) result.dx = dx;
+    if (want.has("dy")) result.dy = dy;
+    if (want.has("distance")) result.distance = Math.hypot(dx, dy);
+    if (want.has("angleDeg") || want.has("angleRad")) {
+      const rad = Math.atan2(dy, dx);
+      if (want.has("angleRad")) result.angleRad = rad;
+      if (want.has("angleDeg")) result.angleDeg = rad * 180 / Math.PI;
+    }
+  }
+  if (want.has("gapX") || want.has("gapY")) {
+    const gap = gapBetween(ra, rb);
+    if (want.has("gapX")) result.gapX = gap.x;
+    if (want.has("gapY")) result.gapY = gap.y;
+  }
+  if (want.has("width")) result.width = ra.width;
+  if (want.has("height")) result.height = ra.height;
+  if (want.has("overlaps") || want.has("overlapArea")) {
+    const area = overlapArea(ra, rb);
+    if (want.has("overlapArea")) result.overlapArea = area;
+    if (want.has("overlaps")) result.overlaps = area > 0;
+  }
+  if (want.has("contains")) result.contains = containsRect(ra, rb);
+  if (want.has("visible"))
+    result.visible = overlapArea(ra, rectOf("viewport", { space: space ?? "viewport" })) > 0;
+  return result;
+}
+function calipers(targets, source, options = {}) {
+  return expandTargets(targets).map((t) => measure(t, source, options));
+}
+function expandTargets(targets) {
+  if (typeof targets === "string")
+    return Array.from(document.querySelectorAll(targets));
+  if (targets === window || targets === "viewport") return [targets];
+  if (isList(targets)) {
+    const out = [];
+    for (const e of Array.from(targets)) {
+      if (typeof e === "string")
+        out.push(...Array.from(document.querySelectorAll(e)));
+      else out.push(e);
+    }
+    return out;
+  }
+  return [targets];
+}
+function isList(v) {
+  return typeof v === "object" && v !== null && typeof v.length === "number" && !(v instanceof Element);
+}
+
+// src/place/index.ts
+function place(el, options = {}) {
+  const { anchor = "tl", offset = {}, using = "transform" } = options;
+  const ox = offset.x ?? 0;
+  const oy = offset.y ?? 0;
+  const gap = normalizeGap(options.gap);
+  if (using === "transform") {
+    const target = targetPoint(options.at, "viewport", "visual");
+    const { rect, translate } = rendered(el, "visual");
+    const cur = anchorPoint(rect, anchor);
+    const dir = gapDirection(rect, anchor);
+    shiftTranslate(
+      el,
+      translate,
+      target.x + ox + gap.x * dir.x - cur.x,
+      target.y + oy + gap.y * dir.y - cur.y
+    );
+  } else {
+    placeByPosition(
+      el,
+      anchor,
+      targetPoint(options.at, "document"),
+      ox,
+      oy,
+      gap
+    );
+  }
+}
+function gapDirection(rect, anchor) {
+  const c = anchorPoint(rect, "cc");
+  const p = anchorPoint(rect, anchor);
+  return { x: Math.sign(c.x - p.x), y: Math.sign(c.y - p.y) };
+}
+function targetPoint(at, space, box = "border") {
+  if (!at) return anchorPoint(rectOf("viewport", { space }), "cc");
+  if (isRawPoint(at)) {
+    return space === "document" ? { x: at.x + window.scrollX, y: at.y + window.scrollY } : { ...at };
+  }
+  const placeAt = at;
+  const of = typeof at.width === "number" ? at : placeAt.of ?? "viewport";
+  if (isRawPoint(of)) {
+    return space === "document" ? { x: of.x + window.scrollX, y: of.y + window.scrollY } : { ...of };
+  }
+  return anchorPoint(rectOf(of, { box, space }), placeAt.anchor ?? "cc");
+}
+function isRawPoint(v) {
+  return typeof v === "object" && v !== null && typeof v.x === "number" && typeof v.y === "number" && typeof v.width !== "number";
+}
+function placeByPosition(el, anchor, target, ox, oy, gap) {
+  const cs = getComputedStyle(el);
+  const positioned = cs.position === "static" ? "absolute" : cs.position;
+  if (cs.position === "static") el.style.position = "absolute";
+  const op = el.offsetParent;
+  const border = rectOf(el, { box: "border", space: "document" });
+  const a = anchorPoint(
+    { x: 0, y: 0, width: border.width, height: border.height },
+    anchor
+  );
+  const dir = gapDirection(border, anchor);
+  const ml = px(cs.marginLeft);
+  const mt = px(cs.marginTop);
+  let fx = target.x;
+  let fy = target.y;
+  if (op) {
+    const ob = rectOf(op, { box: "border", space: "document" });
+    const ocs = getComputedStyle(op);
+    fx -= ob.x + px(ocs.borderLeftWidth);
+    fy -= ob.y + px(ocs.borderTopWidth);
+  } else if (positioned === "fixed") {
+    fx -= window.scrollX;
+    fy -= window.scrollY;
+  }
+  el.style.left = `${fx + ox + gap.x * dir.x - a.x - ml}px`;
+  el.style.top = `${fy + oy + gap.y * dir.y - a.y - mt}px`;
+}
+
+export { align, anchorPoint, angleBetween, calipers, containsRect, distanceBetween, distribute, gapBetween, measure, overlapArea, overlaps, place, rectOf, stack };

package/dist/measure.d.ts

@@ -0,0 +1,70 @@
+import { R as Rect, A as Anchor, P as Point, M as Measurable } from './types-PJD4F9tg.js';
+import { RectOptions } from './rect.js';
+
+/** Resolve an anchor to a single point of a rect. Function anchors receive the rect and return an absolute point. */
+declare function anchorPoint(rect: Rect, anchor?: Anchor): Point;
+/** Euclidean distance between two points. */
+declare function distanceBetween(a: Point, b: Point): number;
+/**
+ * Direction from `from` to `to`, in radians.
+ * 0 = east, positive clockwise (screen coordinates, y down), range (−π, π].
+ */
+declare function angleBetween(from: Point, to: Point): number;
+/** Edge-to-edge separation per axis; 0 on an axis when the projections overlap. */
+declare function gapBetween(a: Rect, b: Rect): {
+    x: number;
+    y: number;
+};
+/** Intersection area of two rects in px²; 0 when disjoint. */
+declare function overlapArea(a: Rect, b: Rect): number;
+/** Whether two rects intersect with non-zero area. */
+declare function overlaps(a: Rect, b: Rect): boolean;
+/** Whether `outer` fully encloses `inner`. */
+declare function containsRect(outer: Rect, inner: Rect): boolean;
+
+type Field = 'dx' | 'dy' | 'distance' | 'gapX' | 'gapY' | 'angleDeg' | 'angleRad' | 'width' | 'height' | 'overlaps' | 'overlapArea' | 'contains' | 'visible';
+interface MeasureOptions extends RectOptions {
+    /** Anchor of the target. @default 'cc' */
+    anchor?: Anchor;
+    /** Anchor of the source. @default 'cc' */
+    ofAnchor?: Anchor;
+    /** Fields to compute. @default all */
+    fields?: readonly Field[];
+}
+interface MeasureResult {
+    target: Measurable;
+    source: Measurable;
+    /** Resolved target anchor — always present. */
+    pointA: Point;
+    /** Resolved source anchor — always present. */
+    pointB: Point;
+    /** Signed deltas, target − source. */
+    dx?: number;
+    dy?: number;
+    /** Euclidean distance between the anchor points. */
+    distance?: number;
+    /** Edge-to-edge separation per axis. */
+    gapX?: number;
+    gapY?: number;
+    /** Direction from source point to target point. */
+    angleDeg?: number;
+    angleRad?: number;
+    /** Target box size. */
+    width?: number;
+    height?: number;
+    overlaps?: boolean;
+    overlapArea?: number;
+    /** Whether the target box fully encloses the source box. */
+    contains?: boolean;
+    /** Whether any part of the target box intersects the viewport. */
+    visible?: boolean;
+}
+/** Measure one target against one source. */
+declare function measure(a: Measurable, b: Measurable, options?: MeasureOptions): MeasureResult;
+/**
+ * Measure many targets against one source.
+ * A selector string expands to *all* matches; array-likes expand per entry.
+ */
+declare function calipers(targets: Measurable, source: Measurable, options?: MeasureOptions): MeasureResult[];
+
+export { type Field, type MeasureOptions, type MeasureResult, anchorPoint, angleBetween, calipers, containsRect, distanceBetween, gapBetween, measure, overlapArea, overlaps };