@excom/scroll-into-view 0.1.0

package/.rush/temp/chunked-rush-logs/scroll-into-view.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/chunked-rush-logs/scroll-into-view.build_docs.chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: node node_modules/@excom/heft-rig/scripts/build-docs.mjs \n"}

package/.rush/temp/chunked-rush-logs/scroll-into-view.build_package-metas.chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: node node_modules/@excom/heft-rig/scripts/build-package-metas.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": 33.73985300000004
+}

package/.rush/temp/operation/build_docs/all.log

@@ -0,0 +1 @@
+Invoking: node node_modules/@excom/heft-rig/scripts/build-docs.mjs 

package/.rush/temp/operation/build_docs/log-chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: node node_modules/@excom/heft-rig/scripts/build-docs.mjs \n"}

package/.rush/temp/operation/build_docs/state.json

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

package/.rush/temp/operation/build_package-metas/all.log

@@ -0,0 +1 @@
+Invoking: node node_modules/@excom/heft-rig/scripts/build-package-metas.mjs 

package/.rush/temp/operation/build_package-metas/log-chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: node node_modules/@excom/heft-rig/scripts/build-package-metas.mjs \n"}

package/.rush/temp/operation/build_package-metas/state.json

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

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

@@ -0,0 +1,3 @@
+{
+  "../../packages/scroll-into-view": "../../packages/scroll-into-view:FiQhO2kLyBFBN2Sjs0m2s+Zh0vbMGja8Orzrnv4l1do=:"
+}

package/config/rig.json

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

package/index.css

@@ -0,0 +1,5 @@
+@import "./src/scroll-into-view.css";
+
+@layer {
+  @mixin module-scroll-into-view;
+}

package/index.ts

@@ -0,0 +1,17 @@
+import { ScrollIntoView } from "./scroll-into-view";
+
+ScrollIntoView.define();
+
+export { ScrollIntoView };
+
+type T_HTMLScrollIntoViewElement = typeof ScrollIntoView.CustomElement;
+declare global {
+  interface HTMLScrollIntoViewElement extends T_HTMLScrollIntoViewElement {}
+  interface Window {
+    HTMLScrollIntoViewElement: HTMLScrollIntoViewElement;
+  }
+  interface HTMLElementTagNameMap {
+    "scroll-into-view": HTMLScrollIntoViewElement;
+  }
+}
+export type { HTMLScrollIntoViewElement };

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@excom/scroll-into-view",
+  "version": "0.1.0",
+  "description": "<scroll-into-view> custom element",
+  "license": "MIT",
+  "engines": {
+    "node": ">=24.13.0"
+  },
+  "type": "module",
+  "dependencies": {
+    "@excom/kit-scroller": "^0.1.0",
+    "@excom/neutron": "^0.1.0",
+    "@excom/kit-utils": "^0.1.0",
+    "@excom/listenable-element": "^0.1.0"
+  },
+  "peerDependencies": {},
+  "devDependencies": {
+    "@excom/heft-rig": "^0.1.0"
+  },
+  "repository": {
+    "url": "excom-dev/nucleus",
+    "directory": "packages/scroll-into-view"
+  },
+  "homepage": "https://github.com/excom-dev/nucleus/tree/main/packages/scroll-into-view/support/docs/README.md",
+  "bugs": "https://github.com/excom-dev/nucleus/issues",
+  "keywords": [
+    "scroll-into-view",
+    "neutron",
+    "custom-elements"
+  ],
+  "excom": {
+    "packageType": "kit-element"
+  },
+  "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",
+    "dev": "node node_modules/@excom/heft-rig/scripts/vite-dev.mjs",
+    "preview": "node node_modules/@excom/heft-rig/scripts/vite-preview.mjs",
+    "build:package-metas": "node node_modules/@excom/heft-rig/scripts/build-package-metas.mjs",
+    "build:docs": "node node_modules/@excom/heft-rig/scripts/build-docs.mjs"
+  }
+}

package/rush-logs/scroll-into-view.apply-exports.cache.log

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

package/rush-logs/scroll-into-view.apply-exports.log

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

package/rush-logs/scroll-into-view.build_docs.cache.log

@@ -0,0 +1 @@
+This project does not define the caching behavior of the "build:docs" command, so caching has been disabled.

package/rush-logs/scroll-into-view.build_docs.log

@@ -0,0 +1 @@
+Invoking: node node_modules/@excom/heft-rig/scripts/build-docs.mjs 

package/rush-logs/scroll-into-view.build_package-metas.cache.log

@@ -0,0 +1 @@
+This project does not define the caching behavior of the "build:package-metas" command, so caching has been disabled.

package/rush-logs/scroll-into-view.build_package-metas.log

@@ -0,0 +1 @@
+Invoking: node node_modules/@excom/heft-rig/scripts/build-package-metas.mjs 

package/scroll-into-view.ts

@@ -0,0 +1,112 @@
+import { scrollElementIntoView } from "@excom/kit-scroller";
+import { selectOne } from "@excom/kit-utils";
+import { isNumber } from "@excom/kit-utils";
+import { ListenableElement } from "@excom/listenable-element";
+import { Neutron, TokenList } from "@excom/neutron";
+
+/**
+ * Scrolls an element into view, based on configuration. By default it
+ * scrolls itself into view as soon as it connects to the DOM; combine with
+ * the inherited `listen-for` attribute to scroll on clicks, custom events,
+ * or lifecycles instead.
+ *
+ * @summary Scroll an element into view — on connect, click, or any event.
+ *
+ * @example
+ * <!-- Jump to a section on click -->
+ * <scroll-into-view target-ref="#pricing" listen-for="click">
+ *   See pricing
+ * </scroll-into-view>
+ */
+export const ScrollIntoView = Neutron.compose([
+  ListenableElement,
+  Neutron({
+    tag: "scroll-into-view",
+    props: {
+      /**
+       * @option
+       * CSS selector of the element to scroll to. Unset scrolls this
+       * element itself.
+       * @values <CSS Selector>
+       */
+      targetRef: String,
+      /**
+       * @option
+       * Two tokens `<inline> <block>` (x and y, respectively) controlling
+       * how the target aligns inside the scrollport. Each token is
+       * `start`, `center`, `end`, `nearest`, or `none` (skip alignment on
+       * that axis).
+       * @default nearest start
+       * @values start | center | end | nearest | none
+       */
+      scrollAlign: {
+        type: TokenList,
+        isValid: (value: string) =>
+          ["start", "center", "end", "nearest", "none"].includes(value),
+        defaultValue: () => ["nearest", "start"],
+      },
+      /**
+       * @option
+       * Two pixel offsets `<x> <y>` applied after alignment — e.g. leave
+       * room for a sticky header by using a negative `<y>`.
+       * @default 0 0
+       * @values <px> <px>
+       */
+      scrollOffset: { type: TokenList, defaultValue: () => ["0", "0"] },
+      /**
+       * @option
+       * Scroll animation.
+       * @default auto
+       * @values auto | smooth | instant
+       */
+      scrollBehavior: { type: String, defaultValue: () => "auto" },
+      /**
+       * @option
+       * Only scroll if the target isn't already fully visible.
+       */
+      ifNeeded: Boolean,
+    },
+  }),
+])
+  .defineMethods({
+    actionHandler: (element) => {
+      const target = (
+        element.targetRef
+          ? selectOne(element.targetRef, {
+              scope: element,
+            })
+          : element
+      ) as HTMLElement;
+      requestAnimationFrame(() => {
+        // wait until after next paint to scroll
+        setTimeout(() => {
+          const scrollInline = element.scrollAlign[0] || "nearest";
+          const scrollBlock = element.scrollAlign[1] || "start";
+          const offsetX = Number(element.scrollOffset[0]);
+          const offsetY = Number(element.scrollOffset[1]);
+          scrollElementIntoView(target, {
+            block:
+              scrollBlock && scrollBlock !== "none"
+                ? (scrollBlock as ScrollLogicalPosition)
+                : undefined,
+            inline:
+              scrollInline && scrollInline !== "none"
+                ? (scrollInline as ScrollLogicalPosition)
+                : undefined,
+            offsetInline: isNumber(offsetX) ? offsetX : undefined,
+            offsetBlock: isNumber(offsetY) ? offsetY : undefined,
+            behavior: element.scrollBehavior as ScrollBehavior,
+            onlyIfNeeded: element.ifNeeded,
+          });
+        }, 0);
+      });
+    },
+  })
+  .onConnected(
+    ({ listenFor, listenForLifecycle, isMoving }) =>
+      !isMoving &&
+      !listenFor?.length &&
+      !listenForLifecycle?.length && {
+        handleEvent: ["connected"],
+      }
+  );

package/src/scroll-into-view.css

@@ -0,0 +1,23 @@
+@import "@excom/listenable-element/src/index.css";
+
+/**
+ * Styles for `<scroll-into-view>`.
+ * @element scroll-into-view
+ */
+
+/* Aliases */
+/**
+ * Apply `<scroll-into-view>` host styles (positioning + the inherited
+ * pointer cursor when clickable) to any element, without registering the
+ * custom element — e.g. server-rendered markup.
+ * @cssalias
+ */
+@custom-selector :--scroll-into-view scroll-into-view, .tag-scroll-into-view;
+
+@define-mixin module-scroll-into-view {
+  :--scroll-into-view {
+    display: block;
+    position: relative;
+    @mixin listenable-element;
+  }
+}

package/support/custom-elements.json

@@ -0,0 +1,189 @@
+{
+  "schemaVersion": "1.0.0",
+  "modules": [
+    {
+      "kind": "javascript-module",
+      "path": "scroll-into-view.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "name": "ScrollIntoView",
+          "customElement": true,
+          "tagName": "scroll-into-view",
+          "mixins": [
+            {
+              "name": "ListenableElement",
+              "package": "@excom/listenable-element"
+            }
+          ],
+          "summary": "Scroll an element into view — on connect, click, or any event.",
+          "description": "Scrolls an element into view, based on configuration. By default it scrolls itself into view as soon as it connects to the DOM; combine with the inherited `listen-for` attribute to scroll on clicks, custom events, or lifecycles instead.",
+          "attributes": [
+            {
+              "name": "target-ref",
+              "type": {
+                "text": "string"
+              },
+              "description": "CSS selector of the element to scroll to. Unset scrolls this element itself.",
+              "fieldName": "targetRef",
+              "values": [
+                "<CSS Selector>"
+              ]
+            },
+            {
+              "name": "scroll-align",
+              "type": {
+                "text": "tokenlist"
+              },
+              "description": "Two tokens `<inline> <block>` (x and y, respectively) controlling how the target aligns inside the scrollport. Each token is `start`, `center`, `end`, `nearest`, or `none` (skip alignment on that axis).",
+              "fieldName": "scrollAlign",
+              "default": "nearest start",
+              "values": [
+                "start",
+                "center",
+                "end",
+                "nearest",
+                "none"
+              ]
+            },
+            {
+              "name": "scroll-offset",
+              "type": {
+                "text": "tokenlist"
+              },
+              "description": "Two pixel offsets `<x> <y>` applied after alignment — e.g. leave room for a sticky header by using a negative `<y>`.",
+              "fieldName": "scrollOffset",
+              "default": "0 0",
+              "values": [
+                "<px> <px>"
+              ]
+            },
+            {
+              "name": "scroll-behavior",
+              "type": {
+                "text": "string"
+              },
+              "description": "Scroll animation.",
+              "fieldName": "scrollBehavior",
+              "default": "auto",
+              "values": [
+                "auto",
+                "smooth",
+                "instant"
+              ]
+            },
+            {
+              "name": "if-needed",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Only scroll if the target isn't already fully visible.",
+              "fieldName": "ifNeeded"
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "targetRef",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "CSS selector of the element to scroll to. Unset scrolls this element itself.",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "scrollAlign",
+              "type": {
+                "text": "tokenlist"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Two tokens `<inline> <block>` (x and y, respectively) controlling how the target aligns inside the scrollport. Each token is `start`, `center`, `end`, `nearest`, or `none` (skip alignment on that axis).",
+              "default": "nearest start",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "scrollOffset",
+              "type": {
+                "text": "tokenlist"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Two pixel offsets `<x> <y>` applied after alignment — e.g. leave room for a sticky header by using a negative `<y>`.",
+              "default": "0 0",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "scrollBehavior",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Scroll animation.",
+              "default": "auto",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "ifNeeded",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Only scroll if the target isn't already fully visible.",
+              "_neutron": {
+                "surface": "option"
+              }
+            }
+          ],
+          "_neutron": {
+            "cssAliases": [
+              {
+                "name": ":--scroll-into-view",
+                "selectors": [
+                  "scroll-into-view",
+                  ".tag-scroll-into-view"
+                ],
+                "kind": "element",
+                "description": "Apply `<scroll-into-view>` host styles (positioning + the inherited pointer cursor when clickable) to any element, without registering the custom element — e.g. server-rendered markup."
+              }
+            ]
+          }
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "ScrollIntoView",
+          "declaration": {
+            "name": "ScrollIntoView",
+            "module": "scroll-into-view.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "scroll-into-view",
+          "declaration": {
+            "name": "ScrollIntoView",
+            "module": "scroll-into-view.ts"
+          }
+        }
+      ]
+    }
+  ]
+}

package/support/demos/simple.html

@@ -0,0 +1,12 @@
+<div>
+  <div class="scroll-area">
+    <p>Keep scrolling…</p>
+    <p>Keep scrolling…</p>
+    <p>Keep scrolling…</p>
+    <scroll-into-view>
+      <p role="note">👋 Scrolled into view on connect — no attributes needed.</p>
+    </scroll-into-view>
+    <p>More content below.</p>
+    <p>More content below.</p>
+  </div>
+</div>

package/support/demos/sticky-header.html

@@ -0,0 +1,22 @@
+<div>
+  <scroll-into-view role="button" target-ref="#section-3" listen-for="click"
+    scroll-offset="0 -50" scroll-behavior="smooth">
+    Jump to Section 3
+  </scroll-into-view>
+  <div class="scroll-area">
+    <header>Sticky header</header>
+    <section id="section-1">
+      <h4>Section 1</h4>
+      <p>The target section is further down.</p>
+    </section>
+    <section id="section-2">
+      <h4>Section 2</h4>
+      <p>Keep scrolling…</p>
+    </section>
+    <section id="section-3">
+      <h4>Section 3</h4>
+      <p>The sticky header would normally cover this —
+        <code>scroll-offset="0 -50"</code> leaves room for it.</p>
+    </section>
+  </div>
+</div>

package/support/dist-docs/scroll-into-view.md

@@ -0,0 +1,130 @@
+# scroll-into-view
+
+Scrolls an element into view — on connect by default, or on click / any event via the inherited `listen-for`.
+
+
+```html
+<div>
+  <div class="scroll-area">
+    <p>Keep scrolling…</p>
+    <p>Keep scrolling…</p>
+    <p>Keep scrolling…</p>
+    <scroll-into-view>
+      <p role="note">👋 Scrolled into view on connect — no attributes needed.</p>
+    </scroll-into-view>
+    <p>More content below.</p>
+    <p>More content below.</p>
+  </div>
+</div>
+```
+
+
+## Features
+
+- **Scroll on connect** Works with no attributes needed
+- **Any trigger** Combine with `listen-for` to scroll on click, custom events, or lifecycles
+- **Alignment control** `scroll-align` picks start / center / end / nearest per axis
+- **Offset for fixed headers** `scroll-offset` nudges the final position after alignment
+- **Skip redundant scrolls** `if-needed` scrolls only when the target isn't already visible
+
+## Installation
+
+
+`@excom/scroll-into-view` v0.1.0
+
+```bash
+pnpm add @excom/scroll-into-view
+```
+
+```bash
+npm install @excom/scroll-into-view
+```
+
+```bash
+yarn add @excom/scroll-into-view
+```
+
+### Import
+
+```ts
+import "@excom/scroll-into-view";
+```
+
+
+
+## Usage
+
+By default, `<scroll-into-view>` scrolls *itself* into view as soon as it connects to the DOM. Set `target-ref` to scroll a different element instead, and pair with the inherited `listen-for` to trigger on click or any event rather than on connect.
+
+```html
+<!-- Jump to a section on click -->
+<scroll-into-view target-ref="#pricing" listen-for="click">
+  See pricing
+</scroll-into-view>
+```
+
+### API Reference
+
+
+#### Attributes
+
+| Name | Surface | Type | Default | Values | Description | Inherited from |
+| --- | --- | --- | --- | --- | --- | --- |
+| `target-ref` | option | `string` |  | `<CSS Selector>` | CSS selector of the element to scroll to. Unset scrolls this element itself. |  |
+| `scroll-align` | option | `tokenlist` | `"nearest start"` | `"start"` \| `"center"` \| `"end"` \| `"nearest"` \| `"none"` | Two tokens `<inline> <block>` (x and y, respectively) controlling how the target aligns inside the scrollport. Each token is `start`, `center`, `end`, `nearest`, or `none` (skip alignment on that axis). |  |
+| `scroll-offset` | option | `tokenlist` | `"0 0"` | `<px> <px>` | Two pixel offsets `<x> <y>` applied after alignment — e.g. leave room for a sticky header by using a negative `<y>`. |  |
+| `scroll-behavior` | option | `string` | `"auto"` | `"auto"` \| `"smooth"` \| `"instant"` | Scroll animation. |  |
+| `if-needed` | option | `boolean` |  |  | Only scroll if the target isn't already fully visible. |  |
+| `host-ref` | option | `string` |  | `<CSS Selector>` \| `"window"` \| `"document"` \| `"html"` \| `"body"` \| `"head"` | Listen on another element / `window` / `document` — e.g. Escape to dismiss a dialog from a global `keydown`. Defaults to `:scope`. Used with `listen-for`. Not compatible with `listen-for-lifecycle`. The selector MUST resolve when `host-ref` is set — it will not wait for a match to appear. | `@excom/listenable-element` |
+| `listen-for` | option | `tokenlist` |  | `<EventName>…` | Space-separated event names to listen for. Defaults to `click` when unset (and no lifecycle list is set). | `@excom/listenable-element` |
+| `listen-for-lifecycle` | option | `tokenlist` |  | `"connected"` \| `"disconnected"` \| `"adopted"` | Space-separated element lifecycles to handle. | `@excom/listenable-element` |
+| `listen-once` | option | `boolean` |  |  | Handle each distinct event name / lifecycle at most once. | `@excom/listenable-element` |
+| `selector-filter` | option | `string` |  | `<CSS Selector>` | Only handle events whose `event.target` matches this CSS selector. Does not support `:scope` in the selector. | `@excom/listenable-element` |
+| `keycode-filter` | option | `tokenlist` |  | `<key` \| `mod+key>…` | Space-separated key filters (OR). Join modifiers with `+` (AND, any order): `shift+k tab` → Shift+K or Tab. Modifiers: `shift`, `alt`, `ctrl`/`control`, `meta`. Case-insensitive. | `@excom/listenable-element` |
+| `pathname-filter` | option | `tokenlist` |  | `<pathname>…` | Only handle when `location.pathname` is one of these values — route-aware behaviors without a separate router element. | `@excom/listenable-element` |
+| `prevent-default` | option | `boolean` |  |  | Call `preventDefault()` on matched events (ignored for lifecycles). | `@excom/listenable-element` |
+| `stop-propagation` | option | `boolean` |  |  | Call `stopPropagation()` on matched events (ignored for lifecycles). | `@excom/listenable-element` |
+| `stop-immediate-propagation` | option | `boolean` |  |  | Call `stopImmediatePropagation()` on matched events (ignored for lifecycles). | `@excom/listenable-element` |
+| `vibrate-ms` | option | `number` | `"20 (when attribute is present with no value)"` |  | Vibrate on handle (`navigator.vibrate`). Empty / `0` uses a 20ms pulse. | `@excom/listenable-element` |
+| `delay-ms` | option | `number` |  |  | Delay handling by this many milliseconds. | `@excom/listenable-element` |
+| `is-debounced` | option | `boolean` |  |  | With `delay-ms`, coalesce bursts into one trailing call (debounce). | `@excom/listenable-element` |
+
+#### CSS Aliases
+
+| Alias | Kind | Matches | Description |
+| --- | --- | --- | --- |
+| `:--scroll-into-view` | element | `scroll-into-view`, `.tag-scroll-into-view` | Apply `<scroll-into-view>` host styles (positioning + the inherited pointer cursor when clickable) to any element, without registering the custom element — e.g. server-rendered markup. |
+
+
+
+### Examples
+
+#### Offset for a sticky header
+
+`scroll-offset="0 -50"` (negative `<y>`) leaves room for a sticky header after alignment; `scroll-behavior="smooth"` animates the scroll. This is the pattern used to jump between sections without the header covering the target's heading.
+
+
+```html
+<div>
+  <scroll-into-view role="button" target-ref="#section-3" listen-for="click"
+    scroll-offset="0 -50" scroll-behavior="smooth">
+    Jump to Section 3
+  </scroll-into-view>
+  <div class="scroll-area">
+    <header>Sticky header</header>
+    <section id="section-1">
+      <h4>Section 1</h4>
+      <p>The target section is further down.</p>
+    </section>
+    <section id="section-2">
+      <h4>Section 2</h4>
+      <p>Keep scrolling…</p>
+    </section>
+    <section id="section-3">
+      <h4>Section 3</h4>
+      <p>The sticky header would normally cover this —
+        <code>scroll-offset="0 -50"</code> leaves room for it.</p>
+    </section>
+  </div>
+</div>
+```

package/support/docs/README.md

@@ -0,0 +1,40 @@
+# scroll-into-view
+
+Scrolls an element into view — on connect by default, or on click / any event via the inherited `listen-for`.
+
+<include-content data-demo="simple"></include-content>
+
+## Features
+
+- **Scroll on connect** Works with no attributes needed
+- **Any trigger** Combine with `listen-for` to scroll on click, custom events, or lifecycles
+- **Alignment control** `scroll-align` picks start / center / end / nearest per axis
+- **Offset for fixed headers** `scroll-offset` nudges the final position after alignment
+- **Skip redundant scrolls** `if-needed` scrolls only when the target isn't already visible
+
+## Installation
+
+<include-content is-active template-ref="/views/install-section/install-section.html"></include-content>
+
+## Usage
+
+By default, `<scroll-into-view>` scrolls *itself* into view as soon as it connects to the DOM. Set `target-ref` to scroll a different element instead, and pair with the inherited `listen-for` to trigger on click or any event rather than on connect.
+
+```html
+<!-- Jump to a section on click -->
+<scroll-into-view target-ref="#pricing" listen-for="click">
+  See pricing
+</scroll-into-view>
+```
+
+### API Reference
+
+<include-content is-active template-ref="/views/api-reference/api-reference.html"></include-content>
+
+### Examples
+
+#### Offset for a sticky header
+
+`scroll-offset="0 -50"` (negative `<y>`) leaves room for a sticky header after alignment; `scroll-behavior="smooth"` animates the scroll. This is the pattern used to jump between sections without the header covering the target's heading.
+
+<include-content data-demo="sticky-header"></include-content>

package/support/package-meta.json

@@ -0,0 +1,220 @@
+{
+  "shortName": "scroll-into-view",
+  "package": {
+    "name": "@excom/scroll-into-view",
+    "version": "0.1.0",
+    "description": "<scroll-into-view> custom element",
+    "peerDependencies": {},
+    "excom": {
+      "packageType": "kit-element"
+    }
+  },
+  "demos": {
+    "simple": "<div>\n  <div class=\"scroll-area\">\n    <p>Keep scrolling…</p>\n    <p>Keep scrolling…</p>\n    <p>Keep scrolling…</p>\n    <scroll-into-view>\n      <p role=\"note\">👋 Scrolled into view on connect — no attributes needed.</p>\n    </scroll-into-view>\n    <p>More content below.</p>\n    <p>More content below.</p>\n  </div>\n</div>\n",
+    "sticky-header": "<div>\n  <scroll-into-view role=\"button\" target-ref=\"#section-3\" listen-for=\"click\"\n    scroll-offset=\"0 -50\" scroll-behavior=\"smooth\">\n    Jump to Section 3\n  </scroll-into-view>\n  <div class=\"scroll-area\">\n    <header>Sticky header</header>\n    <section id=\"section-1\">\n      <h4>Section 1</h4>\n      <p>The target section is further down.</p>\n    </section>\n    <section id=\"section-2\">\n      <h4>Section 2</h4>\n      <p>Keep scrolling…</p>\n    </section>\n    <section id=\"section-3\">\n      <h4>Section 3</h4>\n      <p>The sticky header would normally cover this —\n        <code>scroll-offset=\"0 -50\"</code> leaves room for it.</p>\n    </section>\n  </div>\n</div>\n"
+  },
+  "readme": "<h1 id=\"md-scroll-into-view\">scroll-into-view</h1>\n<p>Scrolls an element into view — on connect by default, or on click / any event via the inherited <code>listen-for</code>.</p>\n<p><include-content data-demo=\"simple\"></include-content></p>\n<h2 id=\"md-features\">Features</h2>\n<ul>\n<li><strong>Scroll on connect</strong> Works with no attributes needed</li>\n<li><strong>Any trigger</strong> Combine with <code>listen-for</code> to scroll on click, custom events, or lifecycles</li>\n<li><strong>Alignment control</strong> <code>scroll-align</code> picks start / center / end / nearest per axis</li>\n<li><strong>Offset for fixed headers</strong> <code>scroll-offset</code> nudges the final position after alignment</li>\n<li><strong>Skip redundant scrolls</strong> <code>if-needed</code> scrolls only when the target isn&#39;t already visible</li>\n</ul>\n<h2 id=\"md-installation\">Installation</h2>\n<p><include-content is-active template-ref=\"/views/install-section/install-section.html\"></include-content></p>\n<h2 id=\"md-usage\">Usage</h2>\n<p>By default, <code>&lt;scroll-into-view&gt;</code> scrolls <em>itself</em> into view as soon as it connects to the DOM. Set <code>target-ref</code> to scroll a different element instead, and pair with the inherited <code>listen-for</code> to trigger on click or any event rather than on connect.</p>\n<include-content data-language=\"html\"><template>&lt;!-- Jump to a section on click --&gt;\n&lt;scroll-into-view target-ref=\"#pricing\" listen-for=\"click\"&gt;\n  See pricing\n&lt;/scroll-into-view&gt;</template></include-content>\n<h3 id=\"md-api-reference\">API Reference</h3>\n<p><include-content is-active template-ref=\"/views/api-reference/api-reference.html\"></include-content></p>\n<h3 id=\"md-examples\">Examples</h3>\n<h4 id=\"md-offset-for-a-sticky-header\">Offset for a sticky header</h4>\n<p><code>scroll-offset=&quot;0 -50&quot;</code> (negative <code>&lt;y&gt;</code>) leaves room for a sticky header after alignment; <code>scroll-behavior=&quot;smooth&quot;</code> animates the scroll. This is the pattern used to jump between sections without the header covering the target&#39;s heading.</p>\n<p><include-content data-demo=\"sticky-header\"></include-content></p>\n",
+  "docs": {
+    "readme": "<h1 id=\"md-scroll-into-view\">scroll-into-view</h1>\n<p>Scrolls an element into view — on connect by default, or on click / any event via the inherited <code>listen-for</code>.</p>\n<p><include-content data-demo=\"simple\"></include-content></p>\n<h2 id=\"md-features\">Features</h2>\n<ul>\n<li><strong>Scroll on connect</strong> Works with no attributes needed</li>\n<li><strong>Any trigger</strong> Combine with <code>listen-for</code> to scroll on click, custom events, or lifecycles</li>\n<li><strong>Alignment control</strong> <code>scroll-align</code> picks start / center / end / nearest per axis</li>\n<li><strong>Offset for fixed headers</strong> <code>scroll-offset</code> nudges the final position after alignment</li>\n<li><strong>Skip redundant scrolls</strong> <code>if-needed</code> scrolls only when the target isn&#39;t already visible</li>\n</ul>\n<h2 id=\"md-installation\">Installation</h2>\n<p><include-content is-active template-ref=\"/views/install-section/install-section.html\"></include-content></p>\n<h2 id=\"md-usage\">Usage</h2>\n<p>By default, <code>&lt;scroll-into-view&gt;</code> scrolls <em>itself</em> into view as soon as it connects to the DOM. Set <code>target-ref</code> to scroll a different element instead, and pair with the inherited <code>listen-for</code> to trigger on click or any event rather than on connect.</p>\n<include-content data-language=\"html\"><template>&lt;!-- Jump to a section on click --&gt;\n&lt;scroll-into-view target-ref=\"#pricing\" listen-for=\"click\"&gt;\n  See pricing\n&lt;/scroll-into-view&gt;</template></include-content>\n<h3 id=\"md-api-reference\">API Reference</h3>\n<p><include-content is-active template-ref=\"/views/api-reference/api-reference.html\"></include-content></p>\n<h3 id=\"md-examples\">Examples</h3>\n<h4 id=\"md-offset-for-a-sticky-header\">Offset for a sticky header</h4>\n<p><code>scroll-offset=&quot;0 -50&quot;</code> (negative <code>&lt;y&gt;</code>) leaves room for a sticky header after alignment; <code>scroll-behavior=&quot;smooth&quot;</code> animates the scroll. This is the pattern used to jump between sections without the header covering the target&#39;s heading.</p>\n<p><include-content data-demo=\"sticky-header\"></include-content></p>\n"
+  },
+  "installation": {
+    "name": "@excom/scroll-into-view",
+    "shortName": "scroll-into-view",
+    "version": "0.1.0",
+    "description": "<scroll-into-view> custom element",
+    "packageType": "kit-element",
+    "cdn": "<script src=\"https://unpkg.com/@excom/kit-utils/dist/index.umd.min.js\"></script>\n<script src=\"https://unpkg.com/@excom/neutron/dist/index.umd.min.js\"></script>\n<script src=\"https://unpkg.com/@excom/scroll-into-view@0.1.0/dist/index.umd.min.js\"></script>\n<link rel=\"stylesheet\" href=\"https://unpkg.com/@excom/scroll-into-view@0.1.0/dist/index.css\">",
+    "install": {
+      "npm": "npm install @excom/scroll-into-view"
+    },
+    "imports": {
+      "js": "import \"@excom/scroll-into-view\";",
+      "css": "@import \"@excom/scroll-into-view\";",
+      "html": "<!-- import path to `node_modules` will depend on your build setup -->\n<script type=\"module\" src=\"/node_modules/@excom/scroll-into-view\"></script>\n<link rel=\"stylesheet\" href=\"/node_modules/@excom/scroll-into-view\">"
+    },
+    "peerDependencies": []
+  },
+  "elementApis": [
+    {
+      "tag": "scroll-into-view",
+      "summary": "Scroll an element into view — on connect, click, or any event.",
+      "kind": "class",
+      "attributes": [
+        {
+          "name": "delay-ms",
+          "type": "number",
+          "description": "Delay handling by this many milliseconds.",
+          "fieldName": "delayMs",
+          "surface": "option",
+          "inheritedFrom": "@excom/listenable-element"
+        },
+        {
+          "name": "host-ref",
+          "type": "string",
+          "description": "Listen on another element / <code>window</code> / <code>document</code> — e.g. Escape to dismiss a dialog from a global <code>keydown</code>. Defaults to <code>:scope</code>. Used with <code>listen-for</code>. Not compatible with <code>listen-for-lifecycle</code>. The selector MUST resolve when <code>host-ref</code> is set — it will not wait for a match to appear.",
+          "fieldName": "hostRef",
+          "surface": "option",
+          "values": "<CSS Selector> | \"window\" | \"document\" | \"html\" | \"body\" | \"head\"",
+          "inheritedFrom": "@excom/listenable-element"
+        },
+        {
+          "name": "if-needed",
+          "type": "boolean",
+          "description": "Only scroll if the target isn&#39;t already fully visible.",
+          "fieldName": "ifNeeded",
+          "surface": "option"
+        },
+        {
+          "name": "is-debounced",
+          "type": "boolean",
+          "description": "With <code>delay-ms</code>, coalesce bursts into one trailing call (debounce).",
+          "fieldName": "isDebounced",
+          "surface": "option",
+          "inheritedFrom": "@excom/listenable-element"
+        },
+        {
+          "name": "keycode-filter",
+          "type": "tokenlist",
+          "description": "Space-separated key filters (OR). Join modifiers with <code>+</code> (AND, any order): <code>shift+k tab</code> → Shift+K or Tab. Modifiers: <code>shift</code>, <code>alt</code>, <code>ctrl</code>/<code>control</code>, <code>meta</code>. Case-insensitive.",
+          "fieldName": "keycodeFilter",
+          "surface": "option",
+          "values": "<key | mod+key>…",
+          "inheritedFrom": "@excom/listenable-element"
+        },
+        {
+          "name": "listen-for",
+          "type": "tokenlist",
+          "description": "Space-separated event names to listen for. Defaults to <code>click</code> when unset (and no lifecycle list is set).",
+          "fieldName": "listenFor",
+          "surface": "option",
+          "values": "<EventName>…",
+          "inheritedFrom": "@excom/listenable-element"
+        },
+        {
+          "name": "listen-for-lifecycle",
+          "type": "tokenlist",
+          "description": "Space-separated element lifecycles to handle.",
+          "fieldName": "listenForLifecycle",
+          "surface": "option",
+          "values": "\"connected\" | \"disconnected\" | \"adopted\"",
+          "inheritedFrom": "@excom/listenable-element"
+        },
+        {
+          "name": "listen-once",
+          "type": "boolean",
+          "description": "Handle each distinct event name / lifecycle at most once.",
+          "fieldName": "listenOnce",
+          "surface": "option",
+          "inheritedFrom": "@excom/listenable-element"
+        },
+        {
+          "name": "pathname-filter",
+          "type": "tokenlist",
+          "description": "Only handle when <code>location.pathname</code> is one of these values — route-aware behaviors without a separate router element.",
+          "fieldName": "pathnameFilter",
+          "surface": "option",
+          "values": "<pathname>…",
+          "inheritedFrom": "@excom/listenable-element"
+        },
+        {
+          "name": "prevent-default",
+          "type": "boolean",
+          "description": "Call <code>preventDefault()</code> on matched events (ignored for lifecycles).",
+          "fieldName": "preventDefault",
+          "surface": "option",
+          "inheritedFrom": "@excom/listenable-element"
+        },
+        {
+          "name": "scroll-align",
+          "type": "tokenlist",
+          "description": "Two tokens <code>&lt;inline&gt; &lt;block&gt;</code> (x and y, respectively) controlling how the target aligns inside the scrollport. Each token is <code>start</code>, <code>center</code>, <code>end</code>, <code>nearest</code>, or <code>none</code> (skip alignment on that axis).",
+          "fieldName": "scrollAlign",
+          "surface": "option",
+          "default": "\"nearest start\"",
+          "values": "\"start\" | \"center\" | \"end\" | \"nearest\" | \"none\""
+        },
+        {
+          "name": "scroll-behavior",
+          "type": "string",
+          "description": "Scroll animation.",
+          "fieldName": "scrollBehavior",
+          "surface": "option",
+          "default": "\"auto\"",
+          "values": "\"auto\" | \"smooth\" | \"instant\""
+        },
+        {
+          "name": "scroll-offset",
+          "type": "tokenlist",
+          "description": "Two pixel offsets <code>&lt;x&gt; &lt;y&gt;</code> applied after alignment — e.g. leave room for a sticky header by using a negative <code>&lt;y&gt;</code>.",
+          "fieldName": "scrollOffset",
+          "surface": "option",
+          "default": "\"0 0\"",
+          "values": "<px> <px>"
+        },
+        {
+          "name": "selector-filter",
+          "type": "string",
+          "description": "Only handle events whose <code>event.target</code> matches this CSS selector. Does not support <code>:scope</code> in the selector.",
+          "fieldName": "selectorFilter",
+          "surface": "option",
+          "values": "<CSS Selector>",
+          "inheritedFrom": "@excom/listenable-element"
+        },
+        {
+          "name": "stop-immediate-propagation",
+          "type": "boolean",
+          "description": "Call <code>stopImmediatePropagation()</code> on matched events (ignored for lifecycles).",
+          "fieldName": "stopImmediatePropagation",
+          "surface": "option",
+          "inheritedFrom": "@excom/listenable-element"
+        },
+        {
+          "name": "stop-propagation",
+          "type": "boolean",
+          "description": "Call <code>stopPropagation()</code> on matched events (ignored for lifecycles).",
+          "fieldName": "stopPropagation",
+          "surface": "option",
+          "inheritedFrom": "@excom/listenable-element"
+        },
+        {
+          "name": "target-ref",
+          "type": "string",
+          "description": "CSS selector of the element to scroll to. Unset scrolls this element itself.",
+          "fieldName": "targetRef",
+          "surface": "option",
+          "values": "<CSS Selector>"
+        },
+        {
+          "name": "vibrate-ms",
+          "type": "number",
+          "description": "Vibrate on handle (<code>navigator.vibrate</code>). Empty / <code>0</code> uses a 20ms pulse.",
+          "fieldName": "vibrateMs",
+          "surface": "option",
+          "default": "\"20 (when attribute is present with no value)\"",
+          "inheritedFrom": "@excom/listenable-element"
+        }
+      ],
+      "events": [],
+      "slots": [],
+      "cssProperties": [],
+      "cssClasses": [],
+      "cssAliases": [
+        {
+          "name": ":--scroll-into-view",
+          "selectors": [
+            "scroll-into-view",
+            ".tag-scroll-into-view"
+          ],
+          "kind": "element",
+          "description": "Apply <code>&lt;scroll-into-view&gt;</code> host styles (positioning + the inherited pointer cursor when clickable) to any element, without registering the custom element — e.g. server-rendered markup."
+        }
+      ],
+      "listens": [],
+      "commands": [],
+      "defaultActions": [],
+      "expectedChildren": [],
+      "provisions": []
+    }
+  ],
+  "exportedFiles": {}
+}

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

@@ -0,0 +1,77 @@
+import {
+  afterEach,
+  describe,
+  expect,
+  fixture,
+  it,
+  vi,
+  wait,
+} from "@excom/heft-rig/profiles/default/config/test-utils";
+import "../../index";
+
+describe("scroll-into-view", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+    vi.restoreAllMocks();
+  });
+
+  it("invokes scroll on connect when no triggers configured", async () => {
+    const scrollToSpy = vi
+      .spyOn(window, "scrollTo")
+      .mockImplementation(() => {});
+    fixture<HTMLScrollIntoViewElement>(
+      `<scroll-into-view></scroll-into-view>`,
+    );
+    await wait(50);
+    expect(scrollToSpy).toHaveBeenCalled();
+  });
+
+  it("scrolls target element when targetRef is set", async () => {
+    const target = document.createElement("div");
+    target.id = "scroll-target";
+    document.body.appendChild(target);
+    const scrollToSpy = vi
+      .spyOn(window, "scrollTo")
+      .mockImplementation(() => {});
+    fixture<HTMLScrollIntoViewElement>(
+      `<scroll-into-view target-ref="#scroll-target"></scroll-into-view>`,
+    );
+    await wait(50);
+    expect(scrollToSpy).toHaveBeenCalled();
+  });
+
+  it("defaults scrollAlign to nearest/start", () => {
+    const el = fixture<HTMLScrollIntoViewElement>(
+      `<scroll-into-view></scroll-into-view>`,
+    );
+    expect(el.scrollAlign).toEqual(["nearest", "start"]);
+  });
+
+  it("defaults scrollBehavior to auto", () => {
+    const el = fixture<HTMLScrollIntoViewElement>(
+      `<scroll-into-view></scroll-into-view>`,
+    );
+    expect(el.scrollBehavior).toBe("auto");
+  });
+
+  it("defaults scrollOffset to 0 0", () => {
+    const el = fixture<HTMLScrollIntoViewElement>(
+      `<scroll-into-view></scroll-into-view>`,
+    );
+    expect(el.scrollOffset).toEqual(["0", "0"]);
+  });
+
+  it("accepts custom scroll-align", () => {
+    const el = fixture<HTMLScrollIntoViewElement>(
+      `<scroll-into-view scroll-align="center end"></scroll-into-view>`,
+    );
+    expect(el.scrollAlign).toEqual(["center", "end"]);
+  });
+
+  it("accepts custom scroll-offset", () => {
+    const el = fixture<HTMLScrollIntoViewElement>(
+      `<scroll-into-view scroll-offset="10 20"></scroll-into-view>`,
+    );
+    expect(el.scrollOffset).toEqual(["10", "20"]);
+  });
+});

package/support/tests/scroll-options.test.ts

@@ -0,0 +1,169 @@
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  fixture,
+  it,
+  wait,
+} from "@excom/heft-rig/profiles/default/config/test-utils";
+// `vi` must come from "vitest" itself so `vi.mock` is hoisted with it
+import { vi } from "vitest";
+import { scrollElementIntoView } from "@excom/kit-scroller";
+import "../../index";
+
+// Intercept the scroller so the options `<scroll-into-view>` derives from its
+// attributes can be asserted directly (layout is meaningless in the test DOM).
+vi.mock("@excom/kit-scroller", async (importOriginal) => {
+  const original =
+    await importOriginal<typeof import("@excom/kit-scroller")>();
+  return { ...original, scrollElementIntoView: vi.fn(() => ({})) };
+});
+
+const scrollMock = vi.mocked(scrollElementIntoView);
+
+// actionHandler waits for a frame and then a macrotask before scrolling
+const settle = () => wait(50);
+
+describe("scroll-into-view (option parsing)", () => {
+  beforeEach(() => {
+    scrollMock.mockClear();
+  });
+
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("passes the default alignment, offsets and behavior", async () => {
+    const el = fixture<HTMLScrollIntoViewElement>(
+      `<scroll-into-view></scroll-into-view>`,
+    );
+    await settle();
+    expect(scrollMock).toHaveBeenCalledTimes(1);
+    expect(scrollMock).toHaveBeenCalledWith(el, {
+      block: "start",
+      inline: "nearest",
+      offsetInline: 0,
+      offsetBlock: 0,
+      behavior: "auto",
+      onlyIfNeeded: false,
+    });
+  });
+
+  it("maps scroll-align, scroll-offset, scroll-behavior and if-needed", async () => {
+    const el = fixture<HTMLScrollIntoViewElement>(
+      `<scroll-into-view scroll-align="center end" scroll-offset="10 -20" scroll-behavior="smooth" if-needed></scroll-into-view>`,
+    );
+    await settle();
+    expect(scrollMock).toHaveBeenCalledWith(el, {
+      block: "end",
+      inline: "center",
+      offsetInline: 10,
+      offsetBlock: -20,
+      behavior: "smooth",
+      onlyIfNeeded: true,
+    });
+  });
+
+  it("skips an axis whose alignment token is `none`", async () => {
+    const el = fixture<HTMLScrollIntoViewElement>(
+      `<scroll-into-view scroll-align="none none"></scroll-into-view>`,
+    );
+    await settle();
+    expect(scrollMock).toHaveBeenCalledWith(el, {
+      block: undefined,
+      inline: undefined,
+      offsetInline: 0,
+      offsetBlock: 0,
+      behavior: "auto",
+      onlyIfNeeded: false,
+    });
+  });
+
+  it("falls back to nearest / start for missing alignment tokens", async () => {
+    const el = fixture<HTMLScrollIntoViewElement>(
+      `<scroll-into-view scroll-align="end"></scroll-into-view>`,
+    );
+    expect(el.scrollAlign).toEqual(["end"]);
+    await settle();
+    expect(scrollMock).toHaveBeenLastCalledWith(
+      el,
+      expect.objectContaining({ inline: "end", block: "start" }),
+    );
+
+    scrollMock.mockClear();
+    el.scrollAlign = [];
+    el.actionHandler();
+    await settle();
+    expect(scrollMock).toHaveBeenLastCalledWith(
+      el,
+      expect.objectContaining({ inline: "nearest", block: "start" }),
+    );
+  });
+
+  it("drops non-numeric offsets", async () => {
+    const el = fixture<HTMLScrollIntoViewElement>(
+      `<scroll-into-view scroll-offset="abc xyz"></scroll-into-view>`,
+    );
+    await settle();
+    expect(scrollMock).toHaveBeenCalledWith(
+      el,
+      expect.objectContaining({
+        offsetInline: undefined,
+        offsetBlock: undefined,
+      }),
+    );
+  });
+
+  it("resolves target-ref relative to itself", async () => {
+    const wrapper = fixture<HTMLDivElement>(
+      `<div>
+        <p id="scroll-target-a">a</p>
+        <scroll-into-view target-ref="#scroll-target-a"></scroll-into-view>
+      </div>`,
+    );
+    await settle();
+    expect(scrollMock).toHaveBeenCalledWith(
+      wrapper.querySelector("#scroll-target-a"),
+      expect.any(Object),
+    );
+  });
+
+  it("hands a missing target-ref to the scroller as null", async () => {
+    fixture<HTMLScrollIntoViewElement>(
+      `<scroll-into-view target-ref="#does-not-exist"></scroll-into-view>`,
+    );
+    await settle();
+    expect(scrollMock).toHaveBeenCalledWith(null, expect.any(Object));
+  });
+});
+
+describe("scroll-into-view (triggers)", () => {
+  beforeEach(() => {
+    scrollMock.mockClear();
+  });
+
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("does not scroll on connect when listen-for is set, only on the event", async () => {
+    const el = fixture<HTMLScrollIntoViewElement>(
+      `<scroll-into-view listen-for="click">Go</scroll-into-view>`,
+    );
+    await settle();
+    expect(scrollMock).not.toHaveBeenCalled();
+    el.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    await settle();
+    expect(scrollMock).toHaveBeenCalledTimes(1);
+    expect(scrollMock).toHaveBeenCalledWith(el, expect.any(Object));
+  });
+
+  it("does not scroll on connect when listen-for-lifecycle is set", async () => {
+    fixture<HTMLScrollIntoViewElement>(
+      `<scroll-into-view listen-for-lifecycle="disconnected"></scroll-into-view>`,
+    );
+    await settle();
+    expect(scrollMock).not.toHaveBeenCalled();
+  });
+});

package/support/tests/simple.view.test.ts

@@ -0,0 +1,21 @@
+import "../../index";
+import {
+  afterEach,
+  describe,
+  expect,
+  it,
+} from "@excom/heft-rig/profiles/default/config/test-utils";
+import { mountView, readDemo } from "@excom/quark/support/tests/view-helpers";
+
+describe("simple view", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("mounts the auto-scroll target", async () => {
+    const { root } = await mountView(readDemo(import.meta.url, "simple"));
+    expect(root.querySelector("scroll-into-view")?.textContent).toMatch(
+      /Scrolled into view/,
+    );
+  });
+});

package/support/tests/sticky-header.view.test.ts

@@ -0,0 +1,27 @@
+import "../../index";
+import {
+  afterEach,
+  describe,
+  expect,
+  it,
+} from "@excom/heft-rig/profiles/default/config/test-utils";
+import {
+  click,
+  flush,
+  mountView,
+  readDemo,
+} from "@excom/quark/support/tests/view-helpers";
+
+describe("sticky-header view", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("jumps to section 3 on click", async () => {
+    const { root } = await mountView(readDemo(import.meta.url, "sticky-header"));
+    const target = root.querySelector("#section-3")!;
+    click(root.querySelector("[role='button']"));
+    await flush();
+    expect(target).toBeTruthy();
+  });
+});

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"]
+}