@excom/kit-scroller 0.1.0

package/.rush/temp/chunked-rush-logs/kit-scroller.apply-exports.chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: cd \"$RUSH_PROJECT_FOLDER\" && node ../heft-rig/scripts/apply-exports.mjs \n"}

package/.rush/temp/operation/apply-exports/all.log

@@ -0,0 +1 @@
+Invoking: cd "$RUSH_PROJECT_FOLDER" && node ../heft-rig/scripts/apply-exports.mjs 

package/.rush/temp/operation/apply-exports/log-chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: cd \"$RUSH_PROJECT_FOLDER\" && node ../heft-rig/scripts/apply-exports.mjs \n"}

package/.rush/temp/operation/apply-exports/state.json

@@ -0,0 +1,3 @@
+{
+  "nonCachedDurationMs": 37.73691699999995
+}

package/.rush/temp/shrinkwrap-deps.json

@@ -0,0 +1,3 @@
+{
+  "../../packages/kit-scroller": "../../packages/kit-scroller:DpFAJ6l9NZ7PxsGv74etlzI4VS4IyRu5jGEhInb3gEw=:"
+}

package/config/rig.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/rig-package/rig.schema.json",
+  "rigPackageName": "@excom/heft-rig",
+  "rigProfile": "default"
+}
+

package/index.ts

@@ -0,0 +1,330 @@
+// TODO replace with a battle-tested library; most of this was vibecoded
+
+type Axis = "y" | "x";
+type ScrollBehaviorOption = "auto" | "smooth" | "instant";
+type Align = "start" | "center" | "end" | "nearest";
+
+interface ScrollAdvancedOptions {
+  behavior?: ScrollBehaviorOption; // default: 'smooth'
+  block?: Align; // default: 'start'
+  inline?: Align; // default: 'nearest'
+  offsetBlock?: number; // default: 0 (applies along Y axis)
+  offsetInline?: number; // default: 0 (applies along X axis)
+  onlyIfNeeded?: boolean; // default true: skip if already fully visible
+  padInView?: number; // default 0: extra slack when testing visibility
+}
+
+type ScrollContainer = Element | Document;
+
+function isViewportContainer(c: ScrollContainer | null): c is Document {
+  return !c || c === document || c === document.scrollingElement;
+}
+
+function getAxisProps(axis: Axis) {
+  return axis === "y"
+    ? {
+        overflowProp: "overflowY" as const,
+        scrollSize: "scrollHeight" as const,
+        clientSize: "clientHeight" as const,
+        scrollPos: "scrollTop" as const,
+      }
+    : {
+        overflowProp: "overflowX" as const,
+        scrollSize: "scrollWidth" as const,
+        clientSize: "clientWidth" as const,
+        scrollPos: "scrollLeft" as const,
+      };
+}
+
+/** Nearest scrollable ancestor on this axis (walks through shadow roots). */
+export function getNearestScrollableContainer(
+  node: Node,
+  axis: Axis = "y"
+): Element | Document | null {
+  const props = getAxisProps(axis);
+
+  const isScrollableElement = (el: Element) => {
+    const cs = getComputedStyle(el);
+    const val = cs[props.overflowProp];
+    if (!/(auto|scroll|overlay)/.test(val)) return false;
+    const canScroll =
+      (el as any)[props.scrollSize] > (el as any)[props.clientSize];
+    // Still a candidate when overflow isn't `visible`, even if not overflowing now
+    return canScroll && !["hidden", "visible"].includes(val);
+  };
+
+  let cur: Node | null = node;
+
+  while (cur) {
+    if (cur instanceof Element) {
+      // `position: fixed` descendants scroll with the viewport
+      const cs = getComputedStyle(cur);
+      if (cs.position === "fixed") break;
+
+      if (isScrollableElement(cur)) return cur;
+    }
+
+    if (cur.parentNode) {
+      cur = cur.parentNode;
+      continue;
+    }
+
+    // Hop out of shadow root to host
+    const root = (cur as any).getRootNode?.();
+    if (root && (root as ShadowRoot).host) {
+      cur = (root as ShadowRoot).host;
+      continue;
+    }
+
+    break;
+  }
+
+  return document.scrollingElement ? document : document; // Viewport is always `Document`
+}
+
+/** Fully visible on this axis inside the container (or viewport)? */
+function isFullyInViewOnAxis(
+  container: ScrollContainer | null,
+  el: Element,
+  axis: Axis,
+  pad = 0
+): boolean {
+  const r = el.getBoundingClientRect();
+
+  if (isViewportContainer(container)) {
+    if (axis === "y")
+      return r.top >= pad && r.bottom <= window.innerHeight - pad;
+    else return r.left >= pad && r.right <= window.innerWidth - pad;
+  }
+
+  const cRect = (container as Element).getBoundingClientRect();
+  if (axis === "y") {
+    const top = cRect.top + pad;
+    const bottom = cRect.bottom - pad;
+    return r.top >= top && r.bottom <= bottom;
+  } else {
+    const left = cRect.left + pad;
+    const right = cRect.right - pad;
+    return r.left >= left && r.right <= right;
+  }
+}
+
+/** Target scroll position for one axis, given alignment and offset. */
+function computeTargetForAxis(params: {
+  container: ScrollContainer | null;
+  el: Element;
+  axis: Axis;
+  align: Align; // 'start' | 'center' | 'end' | 'nearest'
+  offset: number; // additional px offset along that axis
+  padInView: number; // visibility pad used for 'onlyIfNeeded' and 'nearest'
+}) {
+  const { container, el, axis, align, offset, padInView } = params;
+  const props = getAxisProps(axis);
+  const elRect = el.getBoundingClientRect();
+
+  // Current scroll position and sizes
+  if (isViewportContainer(container)) {
+    const current = axis === "y" ? window.scrollY : window.scrollX;
+    const vpSize = axis === "y" ? window.innerHeight : window.innerWidth;
+
+    // Positions relative to the viewport origin
+    const startPos = current + (axis === "y" ? elRect.top : elRect.left);
+    const endPos = current + (axis === "y" ? elRect.bottom : elRect.right);
+    const elSize = axis === "y" ? elRect.height : elRect.width;
+    const centerEl = startPos + elSize / 2;
+    const vpStart = current;
+    const vpEnd = current + vpSize;
+    // const centerVp = vpStart + vpSize / 2;
+
+    let target: number;
+
+    switch (align) {
+      case "start":
+        target = startPos + offset;
+        break;
+      case "end":
+        target = endPos - vpSize + offset;
+        break;
+      case "center":
+        target = centerEl - vpSize / 2 + offset;
+        break;
+      case "nearest": {
+        // Already fully visible (with pad): keep current
+        const fully = isFullyInViewOnAxis(document, el, axis, padInView);
+        if (fully) return { needed: false, target: current };
+        // Smaller move to bring into view (start vs end)
+        const toStart = startPos - (vpStart + padInView);
+        const toEnd = endPos - (vpEnd - padInView);
+        // Extends past both edges: pick the larger magnitude
+        if (toStart < 0 && toEnd > 0) {
+          // Larger than the viewport: prefer start unless end is closer
+          target =
+            Math.abs(toStart) < Math.abs(toEnd)
+              ? current + toStart + offset
+              : current + toEnd + offset;
+        } else if (toStart < 0) {
+          target = current + toStart + offset; // up / left
+        } else {
+          target = current + toEnd + offset; // down / right
+        }
+        break;
+      }
+      default:
+        target = startPos + offset;
+    }
+
+    return { needed: true, target };
+  }
+
+  // Element container
+  const c = container as Element;
+  const cRect = c.getBoundingClientRect();
+  const current = (c as any)[props.scrollPos] as number;
+  const cSize = (c as any)[props.clientSize] as number;
+
+  const elStart =
+    (axis === "y" ? elRect.top : elRect.left) -
+    (axis === "y" ? cRect.top : cRect.left) +
+    current;
+  const elEnd = elStart + (axis === "y" ? elRect.height : elRect.width);
+  const cStart = current;
+  const cEnd = current + cSize;
+  const elCenter = (elStart + elEnd) / 2;
+  // const cCenter = (cStart + cEnd) / 2;
+
+  let target: number;
+
+  switch (align) {
+    case "start":
+      target = elStart + offset;
+      break;
+    case "end":
+      target = elEnd - cSize + offset;
+      break;
+    case "center":
+      target = elCenter - cSize / 2 + offset;
+      break;
+    case "nearest": {
+      const fully = isFullyInViewOnAxis(c, el, axis, padInView);
+      if (fully) return { needed: false, target: current };
+      const toStart = elStart - (cStart + padInView);
+      const toEnd = elEnd - (cEnd - padInView);
+      if (toStart < 0 && toEnd > 0) {
+        target =
+          Math.abs(toStart) < Math.abs(toEnd)
+            ? current + toStart + offset
+            : current + toEnd + offset;
+      } else if (toStart < 0) {
+        target = current + toStart + offset;
+      } else {
+        target = current + toEnd + offset;
+      }
+      break;
+    }
+    default:
+      target = elStart + offset;
+  }
+
+  return { needed: true, target };
+}
+
+/**
+ * Scroll an element into view. Picks the nearest scrollable ancestor
+ * per axis, can do Y, X, or both, and honors start / center / end /
+ * nearest like native `scrollIntoView`.
+ */
+export function scrollElementIntoView(
+  el: Element,
+  {
+    behavior = "smooth",
+    block,
+    inline,
+    offsetBlock = 0,
+    offsetInline = 0,
+    onlyIfNeeded = true,
+    padInView = 0,
+  }: ScrollAdvancedOptions = {}
+): { y?: ScrollContainer; x?: ScrollContainer } {
+  if (!el || !el.getBoundingClientRect) return {};
+
+  const result: { y?: ScrollContainer; x?: ScrollContainer } = {};
+  const axes = [inline && "x", block && "y"];
+
+  if (el.checkVisibility() === false) {
+    // No box to scroll to (`display: none` or `display: contents`).
+    throw new Error(
+      "scrollElementIntoView: element.checkVisibility() failed. Cannot scroll element into view."
+    );
+  }
+  // Y axis
+  if (axes.includes("y")) {
+    const cy = getNearestScrollableContainer(el, "y");
+    const fullyY = onlyIfNeeded
+      ? isFullyInViewOnAxis(
+          cy,
+          el,
+          "y",
+          Math.max(padInView, Math.abs(offsetBlock))
+        )
+      : false;
+
+    if (!(onlyIfNeeded && fullyY)) {
+      const { needed, target } = computeTargetForAxis({
+        container: cy,
+        el,
+        axis: "y",
+        align: block ?? "start",
+        offset: offsetBlock,
+        padInView,
+      });
+
+      if (!onlyIfNeeded || needed) {
+        if (isViewportContainer(cy)) {
+          window.scrollTo({ top: Math.round(target), behavior });
+        } else {
+          (cy as Element).scrollTo({ top: Math.round(target), behavior });
+        }
+        result.y = cy || document;
+      }
+    } else {
+      result.y = cy || document;
+    }
+  }
+
+  // X axis
+  if (axes.includes("x")) {
+    const cx = getNearestScrollableContainer(el, "x");
+    const fullyX = onlyIfNeeded
+      ? isFullyInViewOnAxis(
+          cx,
+          el,
+          "x",
+          Math.max(padInView, Math.abs(offsetInline))
+        )
+      : false;
+
+    if (!(onlyIfNeeded && fullyX)) {
+      const { needed, target } = computeTargetForAxis({
+        container: cx,
+        el,
+        axis: "x",
+        align: inline ?? "nearest",
+        offset: offsetInline,
+        padInView,
+      });
+
+      if (!onlyIfNeeded || needed) {
+        if (isViewportContainer(cx)) {
+          window.scrollTo({ left: Math.round(target), behavior });
+        } else {
+          (cx as Element).scrollTo({ left: Math.round(target), behavior });
+        }
+        result.x = cx || document;
+      }
+    } else {
+      result.x = cx || document;
+    }
+  }
+
+  return result;
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@excom/kit-scroller",
+  "version": "0.1.0",
+  "description": "kit-scroller library",
+  "license": "MIT",
+  "engines": {
+    "node": ">=24.13.0"
+  },
+  "type": "module",
+  "dependencies": {},
+  "peerDependencies": {},
+  "devDependencies": {
+    "@excom/heft-rig": "^0.1.0"
+  },
+  "repository": {
+    "url": "excom-dev/nucleus",
+    "directory": "packages/kit-scroller"
+  },
+  "homepage": "https://github.com/excom-dev/nucleus/tree/main/packages/kit-scroller/support/docs/README.md",
+  "bugs": "https://github.com/excom-dev/nucleus/issues",
+  "keywords": [
+    "kit-scroller"
+  ],
+  "excom": {
+    "documented": false,
+    "packageType": "library"
+  },
+  "scripts": {
+    "build": "node node_modules/@excom/heft-rig/scripts/vite-build.mjs",
+    "build:watch": "node node_modules/@excom/heft-rig/scripts/vite-build-watch.mjs",
+    "format": "node node_modules/@excom/heft-rig/scripts/format.mjs",
+    "test": "node node_modules/@excom/heft-rig/scripts/vitest.mjs",
+    "coverage": "node node_modules/@excom/heft-rig/scripts/coverage.mjs"
+  }
+}

package/rush-logs/kit-scroller.apply-exports.cache.log

@@ -0,0 +1 @@
+Caching has been disabled for this project's "apply-exports" command.

package/rush-logs/kit-scroller.apply-exports.log

@@ -0,0 +1 @@
+Invoking: cd "$RUSH_PROJECT_FOLDER" && node ../heft-rig/scripts/apply-exports.mjs 

package/support/tests/kit-scroller.test.ts

@@ -0,0 +1,150 @@
+import { getNearestScrollableContainer, scrollElementIntoView } from "../../index";
+import {
+  afterEach,
+  describe,
+  expect,
+  it,
+  vi,
+} from "@excom/heft-rig/node_modules/vitest";
+
+describe("getNearestScrollableContainer", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("returns document when no scrollable ancestors exist", () => {
+    const child = document.createElement("div");
+    document.body.appendChild(child);
+    const result = getNearestScrollableContainer(child);
+    expect(result).toBe(document);
+  });
+
+  it("returns nearest scrollable ancestor on y-axis", () => {
+    const container = document.createElement("div");
+    container.style.overflowY = "auto";
+    Object.defineProperty(container, "scrollHeight", {
+      value: 200,
+      configurable: true,
+    });
+    Object.defineProperty(container, "clientHeight", {
+      value: 100,
+      configurable: true,
+    });
+    const child = document.createElement("div");
+    container.appendChild(child);
+    document.body.appendChild(container);
+    const result = getNearestScrollableContainer(child);
+    expect(result).toBe(container);
+  });
+
+  it("returns nearest scrollable ancestor on x-axis", () => {
+    const container = document.createElement("div");
+    container.style.overflowX = "auto";
+    Object.defineProperty(container, "scrollWidth", {
+      value: 400,
+      configurable: true,
+    });
+    Object.defineProperty(container, "clientWidth", {
+      value: 200,
+      configurable: true,
+    });
+    const child = document.createElement("div");
+    container.appendChild(child);
+    document.body.appendChild(container);
+    const result = getNearestScrollableContainer(child, "x");
+    expect(result).toBe(container);
+  });
+
+  it("skips elements with overflow hidden", () => {
+    const hidden = document.createElement("div");
+    hidden.style.overflowY = "hidden";
+    Object.defineProperty(hidden, "scrollHeight", {
+      value: 200,
+      configurable: true,
+    });
+    Object.defineProperty(hidden, "clientHeight", {
+      value: 100,
+      configurable: true,
+    });
+    const child = document.createElement("div");
+    hidden.appendChild(child);
+    document.body.appendChild(hidden);
+    const result = getNearestScrollableContainer(child);
+    expect(result).toBe(document);
+  });
+
+  it("skips non-scrollable overflow auto elements", () => {
+    const container = document.createElement("div");
+    container.style.overflowY = "auto";
+    Object.defineProperty(container, "scrollHeight", {
+      value: 100,
+      configurable: true,
+    });
+    Object.defineProperty(container, "clientHeight", {
+      value: 100,
+      configurable: true,
+    });
+    const child = document.createElement("div");
+    container.appendChild(child);
+    document.body.appendChild(container);
+    const result = getNearestScrollableContainer(child);
+    expect(result).toBe(document);
+  });
+
+  it("finds deeply nested scrollable container", () => {
+    const outer = document.createElement("div");
+    const middle = document.createElement("div");
+    middle.style.overflowY = "scroll";
+    Object.defineProperty(middle, "scrollHeight", {
+      value: 300,
+      configurable: true,
+    });
+    Object.defineProperty(middle, "clientHeight", {
+      value: 100,
+      configurable: true,
+    });
+    const inner = document.createElement("div");
+    const child = document.createElement("div");
+    inner.appendChild(child);
+    middle.appendChild(inner);
+    outer.appendChild(middle);
+    document.body.appendChild(outer);
+    expect(getNearestScrollableContainer(child)).toBe(middle);
+  });
+});
+
+describe("scrollElementIntoView", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+    vi.restoreAllMocks();
+  });
+
+  it("returns empty object when element is null", () => {
+    const result = scrollElementIntoView(null as any);
+    expect(result).toEqual({});
+  });
+
+  it("throws when element is not visible", () => {
+    const el = document.createElement("div");
+    el.checkVisibility = () => false;
+    document.body.appendChild(el);
+    expect(() => scrollElementIntoView(el, { block: "start" })).toThrow(
+      "checkVisibility",
+    );
+  });
+
+  it("returns empty when no axis specified", () => {
+    const el = document.createElement("div");
+    document.body.appendChild(el);
+    const result = scrollElementIntoView(el);
+    expect(result).toEqual({});
+  });
+
+  it("scrolls on y-axis when block is specified", () => {
+    const el = document.createElement("div");
+    document.body.appendChild(el);
+    const scrollToSpy = vi.spyOn(window, "scrollTo").mockImplementation(() => {});
+    scrollElementIntoView(el, { block: "start", onlyIfNeeded: false });
+    expect(scrollToSpy).toHaveBeenCalled();
+  });
+});

package/support/tests/scroll-into-view.test.ts

@@ -0,0 +1,364 @@
+import {
+  getNearestScrollableContainer,
+  scrollElementIntoView,
+} from "../../index";
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+} from "@excom/heft-rig/node_modules/vitest";
+
+type Box = { top?: number; bottom?: number; left?: number; right?: number };
+
+/** Stub an element's layout box (happy-dom has no layout). */
+const setRect = (el: Element, { top = 0, bottom = 0, left = 0, right = 0 }: Box) => {
+  (el as any).getBoundingClientRect = () => ({
+    top,
+    bottom,
+    left,
+    right,
+    height: bottom - top,
+    width: right - left,
+    x: left,
+    y: top,
+    toJSON: () => ({}),
+  });
+};
+
+const defineOwn = (target: object, key: string, value: unknown) =>
+  Object.defineProperty(target, key, { value, configurable: true, writable: true });
+
+/** A scroll container that `getNearestScrollableContainer` recognizes. */
+const makeScroller = (
+  axis: "x" | "y",
+  { scrollSize, clientSize, scrollPos, box }: { scrollSize: number; clientSize: number; scrollPos: number; box: Box }
+) => {
+  const c = document.createElement("div");
+  if (axis === "y") {
+    c.style.overflowY = "auto";
+    defineOwn(c, "scrollHeight", scrollSize);
+    defineOwn(c, "clientHeight", clientSize);
+    c.scrollTop = scrollPos;
+  } else {
+    c.style.overflowX = "auto";
+    defineOwn(c, "scrollWidth", scrollSize);
+    defineOwn(c, "clientWidth", clientSize);
+    c.scrollLeft = scrollPos;
+  }
+  setRect(c, box);
+  const el = document.createElement("span");
+  c.appendChild(el);
+  document.body.appendChild(c);
+  const scrollTo = vi.spyOn(c, "scrollTo").mockImplementation(() => {});
+  return { c, el, scrollTo };
+};
+
+describe("getNearestScrollableContainer (extra branches)", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+    delete (document as any).scrollingElement;
+  });
+
+  it("stops at fixed-position elements and falls back to the document", () => {
+    const scroller = makeScroller("y", { scrollSize: 500, clientSize: 100, scrollPos: 0, box: {} }).c;
+    const fixed = document.createElement("div");
+    fixed.style.position = "fixed";
+    const child = document.createElement("div");
+    fixed.appendChild(child);
+    scroller.appendChild(fixed);
+    expect(getNearestScrollableContainer(child)).toBe(document);
+  });
+
+  it("hops out of a shadow root to find a scrollable host ancestor", () => {
+    const { c: scroller } = makeScroller("y", { scrollSize: 500, clientSize: 100, scrollPos: 0, box: {} });
+    const host = document.createElement("div");
+    scroller.appendChild(host);
+    const root = host.attachShadow({ mode: "open" });
+    const inner = document.createElement("p");
+    root.appendChild(inner);
+    expect(getNearestScrollableContainer(inner)).toBe(scroller);
+  });
+
+  it("returns the document for a detached node", () => {
+    const orphan = document.createElement("div");
+    expect(getNearestScrollableContainer(orphan)).toBe(document);
+  });
+
+  it("still normalizes to the document when scrollingElement is null", () => {
+    Object.defineProperty(document, "scrollingElement", { get: () => null, configurable: true });
+    const child = document.createElement("div");
+    document.body.appendChild(child);
+    expect(getNearestScrollableContainer(child)).toBe(document);
+  });
+});
+
+describe("scrollElementIntoView in the viewport", () => {
+  let scrollTo: ReturnType<typeof vi.spyOn>;
+  let el: HTMLElement;
+
+  beforeEach(() => {
+    window.innerHeight = 500;
+    window.innerWidth = 800;
+    defineOwn(window, "scrollY", 100);
+    defineOwn(window, "scrollX", 20);
+    scrollTo = vi.spyOn(window, "scrollTo").mockImplementation(() => {});
+    el = document.createElement("div");
+    document.body.appendChild(el);
+  });
+
+  afterEach(() => {
+    document.body.innerHTML = "";
+    delete (window as any).scrollY;
+    delete (window as any).scrollX;
+    vi.restoreAllMocks();
+  });
+
+  it("ignores objects without getBoundingClientRect", () => {
+    expect(scrollElementIntoView({} as any, { block: "start" })).toEqual({});
+  });
+
+  it("block start honours offsetBlock and behavior", () => {
+    setRect(el, { top: 200, bottom: 250 });
+    const result = scrollElementIntoView(el, {
+      block: "start",
+      offsetBlock: -10,
+      onlyIfNeeded: false,
+      behavior: "instant",
+    });
+    expect(scrollTo).toHaveBeenCalledWith({ top: 290, behavior: "instant" });
+    expect(result).toEqual({ y: document });
+  });
+
+  it("block end aligns the bottom edge with the viewport bottom", () => {
+    setRect(el, { top: 200, bottom: 250 });
+    scrollElementIntoView(el, { block: "end", onlyIfNeeded: false });
+    expect(scrollTo).toHaveBeenCalledWith({ top: -150, behavior: "smooth" });
+  });
+
+  it("block center centers the element", () => {
+    setRect(el, { top: 200, bottom: 250 });
+    scrollElementIntoView(el, { block: "center", onlyIfNeeded: false });
+    expect(scrollTo).toHaveBeenCalledWith({ top: 75, behavior: "smooth" });
+  });
+
+  it("unknown alignment falls back to start", () => {
+    setRect(el, { top: 200, bottom: 250 });
+    scrollElementIntoView(el, { block: "bogus" as any, onlyIfNeeded: false });
+    expect(scrollTo).toHaveBeenCalledWith({ top: 300, behavior: "smooth" });
+  });
+
+  it("block nearest keeps the current position when fully visible and forced", () => {
+    setRect(el, { top: 200, bottom: 250 });
+    scrollElementIntoView(el, { block: "nearest", onlyIfNeeded: false });
+    expect(scrollTo).toHaveBeenCalledWith({ top: 100, behavior: "smooth" });
+  });
+
+  it("block nearest scrolls up for an element above the viewport", () => {
+    setRect(el, { top: -50, bottom: 0 });
+    const result = scrollElementIntoView(el, { block: "nearest" });
+    expect(scrollTo).toHaveBeenCalledWith({ top: 50, behavior: "smooth" });
+    expect(result.y).toBe(document);
+  });
+
+  it("block nearest scrolls down for an element below the viewport", () => {
+    setRect(el, { top: 600, bottom: 650 });
+    scrollElementIntoView(el, { block: "nearest" });
+    expect(scrollTo).toHaveBeenCalledWith({ top: 250, behavior: "smooth" });
+  });
+
+  it("block nearest picks the smaller move for an element taller than the viewport", () => {
+    setRect(el, { top: -50, bottom: 600 });
+    scrollElementIntoView(el, { block: "nearest" });
+    expect(scrollTo).toHaveBeenLastCalledWith({ top: 50, behavior: "smooth" });
+
+    setRect(el, { top: -300, bottom: 550 });
+    scrollElementIntoView(el, { block: "nearest" });
+    expect(scrollTo).toHaveBeenLastCalledWith({ top: 150, behavior: "smooth" });
+  });
+
+  it("does not scroll when onlyIfNeeded and fully in view", () => {
+    setRect(el, { top: 200, bottom: 250 });
+    const result = scrollElementIntoView(el, { block: "start" });
+    expect(scrollTo).not.toHaveBeenCalled();
+    expect(result).toEqual({ y: document });
+  });
+
+  it("respects padInView when deciding whether a scroll is needed", () => {
+    setRect(el, { top: 5, bottom: 50 });
+    scrollElementIntoView(el, { block: "start", padInView: 10 });
+    expect(scrollTo).toHaveBeenCalledWith({ top: 105, behavior: "smooth" });
+  });
+
+  it("skips the scroll when only the offset pad is violated but nearest is satisfied", () => {
+    setRect(el, { top: 5, bottom: 50 });
+    const result = scrollElementIntoView(el, { block: "nearest", offsetBlock: 10 });
+    expect(scrollTo).not.toHaveBeenCalled();
+    expect(result).toEqual({});
+  });
+
+  it("inline start scrolls horizontally with offsetInline", () => {
+    setRect(el, { left: 100, right: 200 });
+    const result = scrollElementIntoView(el, {
+      inline: "start",
+      offsetInline: 5,
+      onlyIfNeeded: false,
+    });
+    expect(scrollTo).toHaveBeenCalledWith({ left: 125, behavior: "smooth" });
+    expect(result).toEqual({ x: document });
+  });
+
+  it("inline end and center", () => {
+    setRect(el, { left: 100, right: 200 });
+    scrollElementIntoView(el, { inline: "end", onlyIfNeeded: false });
+    expect(scrollTo).toHaveBeenLastCalledWith({ left: -580, behavior: "smooth" });
+    scrollElementIntoView(el, { inline: "center", onlyIfNeeded: false });
+    expect(scrollTo).toHaveBeenLastCalledWith({ left: -230, behavior: "smooth" });
+  });
+
+  it("inline nearest scrolls left for an element off the left edge", () => {
+    setRect(el, { left: -30, right: 10 });
+    scrollElementIntoView(el, { inline: "nearest" });
+    expect(scrollTo).toHaveBeenCalledWith({ left: -10, behavior: "smooth" });
+  });
+
+  it("inline nearest scrolls right for an element off the right edge", () => {
+    setRect(el, { left: 900, right: 950 });
+    scrollElementIntoView(el, { inline: "nearest" });
+    expect(scrollTo).toHaveBeenCalledWith({ left: 170, behavior: "smooth" });
+  });
+
+  it("inline nearest handles elements wider than the viewport", () => {
+    setRect(el, { left: -10, right: 900 });
+    scrollElementIntoView(el, { inline: "nearest" });
+    expect(scrollTo).toHaveBeenLastCalledWith({ left: 10, behavior: "smooth" });
+    setRect(el, { left: -400, right: 810 });
+    scrollElementIntoView(el, { inline: "nearest" });
+    expect(scrollTo).toHaveBeenLastCalledWith({ left: 30, behavior: "smooth" });
+  });
+
+  it("inline defaults to nearest and does nothing when already visible", () => {
+    setRect(el, { left: 100, right: 200 });
+    const result = scrollElementIntoView(el, { inline: "nearest" });
+    expect(scrollTo).not.toHaveBeenCalled();
+    expect(result).toEqual({ x: document });
+  });
+
+  it("scrolls both axes in one call", () => {
+    setRect(el, { top: 600, bottom: 650, left: 900, right: 950 });
+    const result = scrollElementIntoView(el, { block: "start", inline: "start" });
+    expect(scrollTo).toHaveBeenCalledTimes(2);
+    expect(result).toEqual({ x: document, y: document });
+  });
+});
+
+describe("scrollElementIntoView inside a scroll container", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+    vi.restoreAllMocks();
+  });
+
+  const yScroller = () =>
+    makeScroller("y", {
+      scrollSize: 1000,
+      clientSize: 200,
+      scrollPos: 50,
+      box: { top: 100, bottom: 300, left: 0, right: 400 },
+    });
+
+  it("block start / end / center / fallback target the container", () => {
+    const { c, el, scrollTo } = yScroller();
+    setRect(el, { top: 350, bottom: 400 });
+
+    const result = scrollElementIntoView(el, { block: "start", onlyIfNeeded: false });
+    expect(scrollTo).toHaveBeenLastCalledWith({ top: 300, behavior: "smooth" });
+    expect(result).toEqual({ y: c });
+
+    scrollElementIntoView(el, { block: "end", onlyIfNeeded: false, behavior: "auto" });
+    expect(scrollTo).toHaveBeenLastCalledWith({ top: 150, behavior: "auto" });
+
+    scrollElementIntoView(el, { block: "center", onlyIfNeeded: false, offsetBlock: 1 });
+    expect(scrollTo).toHaveBeenLastCalledWith({ top: 226, behavior: "smooth" });
+
+    scrollElementIntoView(el, { block: "bogus" as any, onlyIfNeeded: false });
+    expect(scrollTo).toHaveBeenLastCalledWith({ top: 300, behavior: "smooth" });
+  });
+
+  it("does not scroll when the element is already visible in the container", () => {
+    const { c, el, scrollTo } = yScroller();
+    setRect(el, { top: 150, bottom: 200 });
+    const result = scrollElementIntoView(el, { block: "start" });
+    expect(scrollTo).not.toHaveBeenCalled();
+    expect(result).toEqual({ y: c });
+  });
+
+  it("block nearest keeps position when visible and forced", () => {
+    const { el, scrollTo } = yScroller();
+    setRect(el, { top: 150, bottom: 200 });
+    scrollElementIntoView(el, { block: "nearest", onlyIfNeeded: false });
+    expect(scrollTo).toHaveBeenCalledWith({ top: 50, behavior: "smooth" });
+  });
+
+  it("block nearest scrolls up / down for elements outside the container", () => {
+    const { el, scrollTo } = yScroller();
+    setRect(el, { top: 50, bottom: 80 });
+    scrollElementIntoView(el, { block: "nearest" });
+    expect(scrollTo).toHaveBeenLastCalledWith({ top: 0, behavior: "smooth" });
+
+    setRect(el, { top: 350, bottom: 400 });
+    scrollElementIntoView(el, { block: "nearest" });
+    expect(scrollTo).toHaveBeenLastCalledWith({ top: 150, behavior: "smooth" });
+  });
+
+  it("block nearest picks the smaller move for oversized elements", () => {
+    const { el, scrollTo } = yScroller();
+    setRect(el, { top: 90, bottom: 330 });
+    scrollElementIntoView(el, { block: "nearest" });
+    expect(scrollTo).toHaveBeenLastCalledWith({ top: 40, behavior: "smooth" });
+
+    setRect(el, { top: 50, bottom: 310 });
+    scrollElementIntoView(el, { block: "nearest" });
+    expect(scrollTo).toHaveBeenLastCalledWith({ top: 60, behavior: "smooth" });
+  });
+
+  it("uses padInView against the container edges", () => {
+    const { el, scrollTo } = yScroller();
+    setRect(el, { top: 105, bottom: 150 });
+    scrollElementIntoView(el, { block: "start", padInView: 10 });
+    expect(scrollTo).toHaveBeenCalledWith({ top: 55, behavior: "smooth" });
+  });
+
+  it("handles the inline axis inside an x scroll container", () => {
+    const { c, el, scrollTo } = makeScroller("x", {
+      scrollSize: 2000,
+      clientSize: 400,
+      scrollPos: 30,
+      box: { top: 0, bottom: 100, left: 100, right: 500 },
+    });
+
+    setRect(el, { left: 200, right: 300 });
+    let result = scrollElementIntoView(el, { inline: "start" });
+    expect(scrollTo).not.toHaveBeenCalled();
+    expect(result).toEqual({ x: c });
+
+    result = scrollElementIntoView(el, { inline: "start", onlyIfNeeded: false, offsetInline: -5 });
+    expect(scrollTo).toHaveBeenLastCalledWith({ left: 125, behavior: "smooth" });
+    expect(result).toEqual({ x: c });
+
+    scrollElementIntoView(el, { inline: "end", onlyIfNeeded: false });
+    expect(scrollTo).toHaveBeenLastCalledWith({ left: -170, behavior: "smooth" });
+
+    scrollElementIntoView(el, { inline: "center", onlyIfNeeded: false });
+    expect(scrollTo).toHaveBeenLastCalledWith({ left: -20, behavior: "smooth" });
+
+    setRect(el, { left: 20, right: 60 });
+    scrollElementIntoView(el, { inline: "nearest" });
+    expect(scrollTo).toHaveBeenLastCalledWith({ left: -50, behavior: "smooth" });
+
+    setRect(el, { left: 600, right: 650 });
+    scrollElementIntoView(el, { inline: "nearest" });
+    expect(scrollTo).toHaveBeenLastCalledWith({ left: 180, behavior: "smooth" });
+  });
+});

package/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "@excom/heft-rig/profiles/default/config/tsconfig.json",
+  "include": ["./*.ts"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"]
+}