@samirdamle/calipers 0.0.0-stage → 0.1.0

package/dist/measure.js

@@ -0,0 +1,274 @@
+// 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/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;
+}
+
+// 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/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);
+}
+
+export { anchorPoint, angleBetween, calipers, containsRect, distanceBetween, gapBetween, measure, overlapArea, overlaps };

package/dist/place.d.ts

@@ -0,0 +1,45 @@
+import { A as Anchor, M as Measurable, P as Point, R as Rect, G as Gap } from './types-PJD4F9tg.js';
+
+interface PlaceAt {
+    /** Anchor of the `of` target. @default 'cc' */
+    anchor?: Anchor;
+    /** What to place against. @default 'viewport' */
+    of?: Measurable | Point | Rect;
+}
+interface PlaceOptions {
+    /** Which point of `el` to position. @default 'tl' */
+    anchor?: Anchor;
+    /**
+     * Target: `{ anchor, of }`, a raw viewport point, or a rect.
+     * @default viewport center
+     */
+    at?: PlaceAt | Point | Rect;
+    /** Extra shift in px. */
+    offset?: {
+        x?: number;
+        y?: number;
+    };
+    /**
+     * Gap in px between the placed box and the target. Unlike `offset`
+     * (a raw signed shift), the gap pushes the box *away* from the target
+     * along the ray from the anchor through the box center — e.g.
+     * `place(tip, { anchor: 'tc', at: { anchor: 'bc', of: btn }, gap: 8 })`
+     * puts the tooltip 8px below the button. A center anchor has no
+     * direction, so the gap is a no-op there (use `offset` instead).
+     */
+    gap?: Gap;
+    /**
+     * `transform` (default): sets the CSS `translate` property — compositor-friendly,
+     * composes with `transform`, accumulates across calls.
+     * `position`: sets `left`/`top` (upgrades `static` to `absolute`);
+     * exact for absolute/fixed positioning.
+     */
+    using?: 'transform' | 'position';
+}
+/**
+ * Position `el` so its anchor lands on the target point, plus `offset` and `gap`.
+ * Reads layout once per call. Repeating the same call is a no-op.
+ */
+declare function place(el: HTMLElement, options?: PlaceOptions): void;
+
+export { type PlaceAt, type PlaceOptions, place };

package/dist/place.js

@@ -0,0 +1,274 @@
+// 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 };
+}
+
+// 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);
+  {
+    return { rect, translate };
+  }
+}
+
+// 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 { place };

package/dist/rect.d.ts

@@ -0,0 +1,27 @@
+import { B as Box, S as Space, M as Measurable, R as Rect } from './types-PJD4F9tg.js';
+
+interface RectOptions {
+    /**
+     * Which box to measure.
+     * - `border` (default): layout border box, no transforms.
+     * - `content` / `margin`: derived from the border box via computed style.
+     * - `visual`: `getBoundingClientRect()`, including CSS transforms.
+     * - `bbox`: SVG only — `getBBox()` in local user units, untransformed.
+     *   For HTML elements it falls back to `border`.
+     */
+    box?: Box;
+    /**
+     * Coordinate space of the result. `viewport` rects shift on scroll;
+     * `document` rects don't. `bbox` results are always in local SVG units.
+     * @default 'viewport'
+     */
+    space?: Space;
+}
+/**
+ * Resolve any measurable into a normalized `{ x, y, width, height }` rect.
+ * A `Point` resolves to a zero-size rect at that point. Lists resolve their
+ * first entry. Reads layout exactly once per call.
+ */
+declare function rectOf(target: Measurable, options?: RectOptions): Rect;
+
+export { type RectOptions, rectOf };