release: 0.1.4

Author: hanityx

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.1.4
+
+- Added `progressMode: "content"` for article-height reading progress instead of outline-item progress.
+- Added `activeBoundary: "viewport-end"` so active heading and progress can follow the lower viewport edge.
+- Added `edge.afterBoundary` and `edge.afterOffset` for smoother after-content fade timing.
+- Moved the live demo link to the top of the README.
+
 ## 0.1.3
 
 - Fixed rail sizing at shorter viewport heights so the panel and list stay inside the viewport.

README.md

@@ -2,6 +2,8 @@
 
 Sticky reading rail for long articles — TOC links, scroll progress, and active heading state. Vanilla TypeScript, ESM-only, zero dependencies.
 
+[Live demo](https://hanityx.github.io/toc-rail/) · [npm](https://www.npmjs.com/package/toc-rail)
+
 ![toc-rail demo](https://raw.githubusercontent.com/hanityx/toc-rail/main/demo/demo.png)
 
 ```sh
@@ -36,9 +38,13 @@ change after a re-render.
 | `ariaLabel` | `string` | title text or `"Table of contents"` | Accessible label on the nav element. |
 | `minWidth` | `number` | `1140` | Hide below this viewport width (px). |
 | `topOffset` | `number` | `52` | Fixed header height for scroll math. |
-| `activeOffset` | `number` | `32` | Extra offset for deciding the active heading. |
+| `activeBoundary` | `"viewport-start" \| "viewport-end"` | `"viewport-start"` | Boundary used for deciding the active heading. |
+| `activeOffset` | `number` | `32` | Extra offset for deciding the active heading. With `viewport-end`, this is distance above the bottom edge. |
+| `progressMode` | `"outline" \| "content"` | `"outline"` | `outline` follows the active TOC item. `content` fills by article reading progress. |
 | `edge.hideBefore` | `boolean` | `true` | Hide before the article enters the viewport. |
 | `edge.hideAfter` | `boolean` | `true` | Hide after the article leaves the viewport. |
+| `edge.afterBoundary` | `"viewport-start" \| "viewport-end"` | `"viewport-start"` | Boundary used for after-content fade. Use `viewport-end` to fade when the article end reaches the bottom of the viewport. |
+| `edge.afterOffset` | `number` | `0` | Extra distance after the after-boundary before fade starts. |
 | `edge.beforeOffset` | `number` | `120` | Before-content threshold (px). |
 | `edge.afterFadeDistance` | `number` | `160` | Fade distance (px) near the article end. |
 | `classes` | `object` | — | Extra class hooks: `root`, `link`, `activeItem`. |
@@ -49,8 +55,6 @@ change after a re-render.
 
 Progress-only mode ignores navigation-only options like link classes and active item classes.
 
-Live example: [demo](https://hanityx.github.io/toc-rail/)
-
 ## Styling
 
 Override CSS tokens:

demo/index.html

@@ -5,7 +5,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>toc-rail demo</title>
     <link rel="icon" href="data:," />
-    <link rel="stylesheet" href="../style.css?v=demo-0.1.3" />
+    <link rel="stylesheet" href="../style.css?v=demo-0.1.4" />
     <style>
       :root {
         color-scheme: light;
@@ -474,8 +474,8 @@ <h2 id="final-check">Final check</h2>
     </main>
     <script type="module">
       const moduleUrl = location.hostname.endsWith("github.io")
-        ? "https://cdn.jsdelivr.net/npm/toc-rail@0.1.3/+esm"
-        : "../dist/index.js?v=demo-0.1.3";
+        ? "https://cdn.jsdelivr.net/npm/toc-rail@0.1.4/+esm"
+        : "../dist/index.js?v=demo-0.1.4";
       const { mountTocRail } = await import(moduleUrl);
 
       mountTocRail({

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "toc-rail",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Sticky reading rail with table-of-contents, scroll progress, and active heading state. Vanilla, ESM, zero dependencies.",
   "type": "module",
   "license": "MIT",

package.json

@@ -77,8 +77,11 @@ export function findActiveHeadingIndex(
   win: Window,
   options: TocRailOptions
 ): number {
+  const activeOffset = options.activeOffset ?? DEFAULT_ACTIVE_OFFSET;
   const activePoint =
-    win.scrollY + (options.topOffset ?? DEFAULT_TOP_OFFSET) + (options.activeOffset ?? DEFAULT_ACTIVE_OFFSET);
+    options.activeBoundary === "viewport-end"
+      ? win.scrollY + win.innerHeight - activeOffset
+      : win.scrollY + (options.topOffset ?? DEFAULT_TOP_OFFSET) + activeOffset;
   let activeIndex = -1;
 
   for (let index = 0; index < headings.length; index += 1) {
@@ -109,7 +112,10 @@ function calculateAfterFade(
   }
 
   const fadeDistance = Math.max(options.edge?.afterFadeDistance ?? DEFAULT_AFTER_FADE_DISTANCE, 1);
-  const afterDistance = topOffset - getRectBottom(metrics.contentRect);
+  const afterBoundary =
+    options.edge?.afterBoundary === "viewport-end" ? metrics.innerHeight : topOffset;
+  const afterOffset = options.edge?.afterOffset ?? 0;
+  const afterDistance = afterBoundary - getRectBottom(metrics.contentRect) - afterOffset;
   const opacity = 1 - clamp(afterDistance / fadeDistance, 0, 1);
   return {
     opacity,

src/geometry.ts

@@ -134,19 +134,16 @@ export function mountTocRail(options: TocRailOptions): TocRailInstance {
     const visualState = computeVisualState(metrics, options);
     const activeIndex = findActiveHeadingIndex(headingData, win, options);
     syncActiveItemVisibility(view, itemData, activeIndex);
-    const progress =
-      itemData.length > 0
-        ? getOutlineProgress(
-            view,
-            itemData,
-            headingData,
-            activeIndex,
-            metrics,
-            win,
-            options,
-            visualState.progress
-          )
-        : visualState.progress;
+    const progress = getProgress({
+      activeIndex,
+      headings: headingData,
+      items: itemData,
+      metrics,
+      options,
+      fallbackProgress: visualState.progress,
+      view,
+      win
+    });
 
     currentProgress = progress;
     currentActiveId = applyActiveItem(itemData, activeIndex, options);
@@ -189,6 +186,61 @@ function resolveElement(target: string | Element, doc: Document): Element | null
   return typeof target === "string" ? doc.querySelector(target) : target;
 }
 
+function getViewportContentProgress(
+  metrics: ReturnType<typeof measureRailMetrics>,
+  options: TocRailOptions
+): number {
+  const topOffset = options.topOffset ?? DEFAULT_TOP_OFFSET;
+  const activeOffset = options.activeOffset ?? DEFAULT_ACTIVE_OFFSET;
+  const contentTop = metrics.contentRect.top + metrics.scrollY;
+  const contentHeight = Math.max(metrics.scrollHeight || metrics.contentRect.height, 1);
+  const contentEnd = contentTop + contentHeight;
+  const progressPoint =
+    options.activeBoundary === "viewport-end"
+      ? metrics.scrollY + metrics.innerHeight - activeOffset
+      : metrics.scrollY + topOffset;
+
+  if (contentEnd <= contentTop) return progressPoint >= contentTop ? 1 : 0;
+  return clamp((progressPoint - contentTop) / (contentEnd - contentTop), 0, 1);
+}
+
+function getProgress({
+  activeIndex,
+  headings,
+  items,
+  metrics,
+  options,
+  fallbackProgress,
+  view,
+  win
+}: {
+  activeIndex: number;
+  headings: readonly InternalTocRailHeading[];
+  items: readonly TocRailItem[];
+  metrics: ReturnType<typeof measureRailMetrics>;
+  options: TocRailOptions;
+  fallbackProgress: number;
+  view: ReturnType<typeof createTocRailView>;
+  win: Window;
+}): number {
+  if (options.progressMode === "content") {
+    return getViewportContentProgress(metrics, options);
+  }
+
+  if (items.length === 0) return fallbackProgress;
+
+  return getOutlineProgress(
+    view,
+    items,
+    headings,
+    activeIndex,
+    metrics,
+    win,
+    options,
+    fallbackProgress
+  );
+}
+
 function syncActiveItemVisibility(
   view: ReturnType<typeof createTocRailView>,
   items: readonly TocRailItem[],
@@ -240,9 +292,11 @@ function getOutlineProgress(
   const currentCenter = getLinkCenter(items[activeIndex]!.link);
   let targetCenter = currentCenter;
   const activePoint =
-    win.scrollY +
-    (options.topOffset ?? DEFAULT_TOP_OFFSET) +
-    (options.activeOffset ?? DEFAULT_ACTIVE_OFFSET);
+    options.activeBoundary === "viewport-end"
+      ? win.scrollY + win.innerHeight - (options.activeOffset ?? DEFAULT_ACTIVE_OFFSET)
+      : win.scrollY +
+        (options.topOffset ?? DEFAULT_TOP_OFFSET) +
+        (options.activeOffset ?? DEFAULT_ACTIVE_OFFSET);
 
   const nextHeading = headings[activeIndex + 1];
   const nextItem = items[activeIndex + 1];

src/mount.ts

@@ -23,10 +23,14 @@ export interface TocRailOptions {
   ariaLabel?: string;
   minWidth?: number;
   topOffset?: number;
+  activeBoundary?: "viewport-start" | "viewport-end";
   activeOffset?: number;
+  progressMode?: "outline" | "content";
   edge?: {
     hideBefore?: boolean;
     hideAfter?: boolean;
+    afterBoundary?: "viewport-start" | "viewport-end";
+    afterOffset?: number;
     beforeOffset?: number;
     afterFadeDistance?: number;
   };

src/types.ts

@@ -384,6 +384,119 @@ test("browser fixture covers progress-only, encoded fragments, and hidden state
   await expect(hiddenRail.locator(".toc-rail__link")).toHaveAttribute("tabindex", "-1");
 });
 
+test("viewport-end content progress stays synced in a real browser layout", async ({ page }) => {
+  await page.goto(`${baseUrl}/demo/index.html`);
+
+  await page.evaluate(async () => {
+    document.body.innerHTML =
+      '<main style="width:min(100%,1120px);margin:0 auto;padding:64px 24px 120vh"><article id="viewport-content" style="width:min(100%,680px)"><h1>Viewport content</h1></article></main>';
+    const article = document.querySelector("#viewport-content");
+    if (!article) throw new Error("Missing viewport content article.");
+
+    for (let index = 1; index <= 8; index += 1) {
+      const heading = document.createElement("h2");
+      heading.id = `viewport-section-${index}`;
+      heading.textContent = `Viewport section ${index}`;
+      heading.style.marginTop = index === 1 ? "96px" : "420px";
+      heading.style.scrollMarginTop = "84px";
+
+      const paragraph = document.createElement("p");
+      paragraph.textContent = "Body ".repeat(140);
+      article.append(heading, paragraph);
+    }
+
+    const { mountTocRail } = (await window.eval('import("/dist/index.js")')) as typeof import("../dist/index.js");
+    mountTocRail({
+      content: "#viewport-content",
+      headings: "#viewport-content h2[id]",
+      title: false,
+      minWidth: 800,
+      topOffset: 56,
+      activeBoundary: "viewport-end",
+      activeOffset: 120,
+      progressMode: "content",
+      edge: {
+        hideBefore: false,
+        afterBoundary: "viewport-end",
+        afterOffset: 120,
+        afterFadeDistance: 160
+      }
+    });
+
+    document.documentElement.style.setProperty("scroll-behavior", "auto", "important");
+    document.body.style.setProperty("scroll-behavior", "auto", "important");
+  });
+
+  const rail = page.locator("[data-toc-rail='true']");
+  await expect(rail).toBeVisible();
+
+  const samples = await page.evaluate(async () => {
+    const article = document.querySelector<HTMLElement>("#viewport-content");
+    if (!article) throw new Error("Missing viewport content article.");
+    const articleTop = article.getBoundingClientRect().top + window.scrollY;
+    const articleEnd = articleTop + Math.max(article.scrollHeight, article.getBoundingClientRect().height);
+    const results: Array<{
+      expected: number;
+      progress: number;
+      activeHref: string | null;
+      state: string | null;
+    }> = [];
+
+    for (const sectionId of ["viewport-section-1", "viewport-section-4", "viewport-section-8"]) {
+      const heading = document.getElementById(sectionId);
+      if (!heading) throw new Error(`Missing heading ${sectionId}`);
+      window.scrollTo(0, Math.max(0, heading.getBoundingClientRect().top + window.scrollY - window.innerHeight + 120));
+      window.dispatchEvent(new Event("scroll"));
+      await new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve)));
+
+      const rail = document.querySelector<HTMLElement>("[data-toc-rail='true']");
+      const active = document.querySelector<HTMLAnchorElement>("[data-toc-rail-active='true'] a");
+      const progress = Number(rail?.getAttribute("data-toc-rail-progress"));
+      const progressPoint = window.scrollY + window.innerHeight - 120;
+      const expected = Math.min(1, Math.max(0, Number(((progressPoint - articleTop) / (articleEnd - articleTop)).toFixed(4))));
+      results.push({
+        expected,
+        progress,
+        activeHref: active?.getAttribute("href") ?? null,
+        state: rail?.getAttribute("data-toc-rail-state") ?? null
+      });
+    }
+
+    return results;
+  });
+
+  for (const sample of samples) {
+    expect(sample.state).toBe("visible");
+    expect(sample.progress).toBeCloseTo(sample.expected, 3);
+  }
+  expect(samples.map((sample) => sample.activeHref)).toEqual([
+    "#viewport-section-1",
+    "#viewport-section-4",
+    "#viewport-section-8"
+  ]);
+
+  const afterContent = await page.evaluate(async () => {
+    const article = document.querySelector<HTMLElement>("#viewport-content");
+    if (!article) throw new Error("Missing viewport content article.");
+    const articleBottom = article.getBoundingClientRect().bottom + window.scrollY;
+    window.scrollTo(0, articleBottom - window.innerHeight + 240);
+    window.dispatchEvent(new Event("scroll"));
+    await new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve)));
+
+    const rail = document.querySelector<HTMLElement>("[data-toc-rail='true']");
+    return {
+      progress: Number(rail?.getAttribute("data-toc-rail-progress")),
+      state: rail?.getAttribute("data-toc-rail-state") ?? null,
+      opacity: Number(rail?.style.getPropertyValue("--toc-rail-edge-opacity"))
+    };
+  });
+
+  expect(afterContent.progress).toBe(1);
+  expect(afterContent.state).toBe("fading-after");
+  expect(afterContent.opacity).toBeGreaterThan(0);
+  expect(afterContent.opacity).toBeLessThan(1);
+});
+
 test("long outlines keep the active item visible and synced", async ({ page }) => {
   await page.goto(`${baseUrl}/demo/index.html`);
 

test/browser-smoke.spec.ts

@@ -71,7 +71,16 @@ try {
       import { mountReadingRail, mountTocRail, type TocRailHeading, type TocRailInstance, type TocRailOptions } from "toc-rail";
       import "toc-rail/style.css";
 
-      const options: TocRailOptions = { content: document.body, headings: false };
+      const options: TocRailOptions = {
+        content: document.body,
+        headings: false,
+        activeBoundary: "viewport-end",
+        progressMode: "content",
+        edge: {
+          afterBoundary: "viewport-end",
+          afterOffset: 120
+        }
+      };
       const rail: TocRailInstance = mountTocRail(options);
       const alias: typeof mountTocRail = mountReadingRail;
       const headings: readonly TocRailHeading[] = rail.headings;