@papit/table-of-content 0.0.0-stage → 0.0.2

package/README.md

@@ -1,3 +1,139 @@
-# Temporary Holding Version
+# @papit/table-of-content
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A page-aware table of contents that builds a tree from the page's headings and highlights the ones currently in view. Clicking an item jumps to its section via the URL hash.
+
+![Logo](https://raw.githubusercontent.com/onkelhoy/papit/refs/heads/main/asset/logo.svg)
+
+---
+
+![Type](https://img.shields.io/badge/Type-atoms-orange)
+[![Tests](https://github.com/onkelhoy/papit/actions/workflows/pull-request.yml/badge.svg)](https://github.com/onkelhoy/papit/actions/workflows/pull-request.yml)
+[![NPM version](https://img.shields.io/npm/v/@papit/table-of-content.svg?logo=npm)](https://www.npmjs.com/package/@papit/table-of-content)
+
+---
+
+## Installation
+
+```bash
+npm install @papit/table-of-content
+```
+
+### HTML
+
+```html
+<script type="module" defer>
+  import "@papit/table-of-content";
+</script>
+
+<pap-table-of-content></pap-table-of-content>
+```
+
+### JavaScript / TypeScript
+
+```ts
+import "@papit/table-of-content";
+```
+
+---
+
+## Usage
+
+Place `<pap-table-of-content>` anywhere on the page. By default it scans the **root node** (document or shadow root) for all heading elements and `role="heading"` elements, excluding those with `aria-hidden` or `data-skipped`.
+
+```html
+<pap-table-of-content></pap-table-of-content>
+
+<main>
+  <h1>Introduction</h1>
+  <h2>Getting started</h2>
+  <h3>Prerequisites</h3>
+  <h2>API reference</h2>
+</main>
+```
+
+As the user scrolls, the items corresponding to visible headings receive the `marked` class and the host gains the `:state(scrolling)` custom state.
+
+### Custom query
+
+Override which elements are observed by setting the `query` attribute or property:
+
+```html
+<!-- Only observe h2 and h3 -->
+<pap-table-of-content query="h2, h3"></pap-table-of-content>
+```
+
+### Icons
+
+Add a `data-icon` attribute to a heading to render a `pap-icon` beside its label in the tree:
+
+```html
+<h2 data-icon="star">Highlights</h2>
+```
+
+### Reading the active set
+
+```ts
+const toc = document.querySelector("pap-table-of-content");
+toc.addEventListener("change", () => {
+  console.log(toc.value); // [{ href: '#...', name: '...' }, ...]
+});
+```
+
+---
+
+## Properties
+
+| Property | Attribute | Type                               | Default               | Description                                                           |
+| -------- | --------- | ---------------------------------- | --------------------- | --------------------------------------------------------------------- |
+| `query`  | `query`   | `string`                           | All heading selectors | CSS selector used to discover headings. Reflected from the attribute. |
+| `links`  | —         | `Link[]`                           | `[]`                  | Internal list of discovered links; not reflected.                     |
+| `value`  | —         | `{ href: string; name: string }[]` | —                     | Read-only. Returns the subset of links currently marked as visible.   |
+
+---
+
+## Events
+
+| Event    | Detail | Description                                                                              |
+| -------- | ------ | ---------------------------------------------------------------------------------------- |
+| `change` | —      | Fired whenever the set of visible headings changes (throttled via IntersectionObserver). |
+
+---
+
+## CSS Parts
+
+| Part     | Element              | Description                       |
+| -------- | -------------------- | --------------------------------- |
+| `tree`   | `pap-treeview`       | The root tree element.            |
+| `item`   | `pap-treeitem`       | Each individual tree item.        |
+| `anchor` | `<a>` inside an item | The anchor link inside each item. |
+
+---
+
+## Custom States
+
+| State               | Description                                                                 |
+| ------------------- | --------------------------------------------------------------------------- |
+| `:state(scrolling)` | Present while the page is scrolling; removed ~500 ms after scrolling stops. |
+| `:state(active)`    | Present while the inner `pap-treeview` is focused / active.                 |
+
+---
+
+## License
+
+Licensed under the @Papit License 1.0 — Copyright (c) 2024 Henry Pap (@onkelhoy)
+
+**Key points:**
+
+- ✅ Free to use in commercial projects
+- ✅ Free to modify and distribute
+- ✅ Attribution required
+- ❌ Cannot resell the component itself as a standalone product
+
+See the [LICENSE](https://github.com/onkelhoy/papit/blob/main/LICENSE) file for full details.
+
+---
+
+## Related packages
+
+- [@papit/web-component](https://github.com/onkelhoy/papit/tree/main/packages/web/engines/web-component) — Core utilities, decorators, and base component class
+- [@papit/treeview](https://github.com/onkelhoy/papit/tree/main/packages/web/design-system/1-foundations/treeview) — Tree view and tree item components used for rendering

package/asset/translations/en.json

@@ -0,0 +1,7 @@
+{
+  "meta": {
+    "region": "GB",
+    "language": "en-UK"
+  },
+  "table-of-content": "table-of-content"
+}

package/lib/bundle.d.ts

@@ -0,0 +1,66 @@
+import { CustomElementInternals } from '@papit/web-component';
+
+declare type Link = {
+    href: string;
+    name: string;
+    icon: string | null;
+    reference: HTMLElement;
+    marked: boolean;
+    level: number;
+};
+
+/**
+ * `<pap-table-of-content>` — a scroll-aware table of contents web component.
+ *
+ * Scans the root node for heading elements (or any element matching {@link query}),
+ * assigns stable `id` attributes derived from their text content, and renders them
+ * as a hierarchical `<pap-treeview>`. Items corresponding to headings that are
+ * currently intersecting the viewport are highlighted with the `marked` CSS class.
+ *
+ * @fires change - Dispatched whenever the set of visible (intersecting) headings
+ *   changes. Read {@link value} inside the handler to get the current active set.
+ *
+ * @csspart tree   - The root `<pap-treeview>` element.
+ * @csspart item   - Each `<pap-treeitem>` element.
+ * @csspart anchor - The `<a>` element inside each tree item.
+ *
+ * @cssprop --space-3 - Inline padding applied to each tree item's content area (default `0.75rem`).
+ *
+ * @example
+ * ```html
+ * <pap-table-of-content></pap-table-of-content>
+ *
+ * <main>
+ *   <h1>Intro</h1>
+ *   <h2>Details</h2>
+ *   <h3>Sub-section</h3>
+ * </main>
+ * ```
+ */
+export declare class TableOfContent extends CustomElementInternals {
+    static sheet: CSSStyleSheet;
+    /**
+     * The currently visible headings as plain objects.
+     * Useful for driving external navigation UI or breadcrumbs.
+     *
+     * @returns An array of `{ href, name }` pairs for every link whose
+     *   `marked` flag is `true`.
+     */
+    get value(): {
+        href: string;
+        name: string;
+    }[];
+    private observer;
+    links: Link[];
+    query: string;
+    private handleobserve;
+    private handleenter;
+    private handleactive;
+    private handleinactive;
+    private stopscrolling;
+    private buildHierarchy;
+    private renderTreeItems;
+    render(): Node;
+}
+
+export { }

package/lib/bundle.js

@@ -0,0 +1,66 @@
+var f=Object.defineProperty;var g=Object.getOwnPropertyDescriptor;var s=(h,o,t,r)=>{for(var e=r>1?void 0:r?g(o,t):o,n=h.length-1,a;n>=0;n--)(a=h[n])&&(e=(r?a(o,t,e):a(e))||e);return r&&e&&f(o,t,e),e};import{bind as c,CustomElementInternals as b,debounce as w,html as l,property as v,unsafeHTML as k}from"@papit/web-component";import"@papit/treeview";var m=new CSSStyleSheet;m.replaceSync(`:host {
+    pap-treeview {
+        list-style: none;
+        padding: 0;
+
+        pap-treeitem {
+
+            a {
+                color: currentColor;
+                text-decoration: none;
+            }
+
+            &:hover {
+                &>a {
+                    text-decoration: underline;
+                }
+            }
+
+            &::part(content) {
+                padding-inline: var(--space-3, 0.75rem);
+            }
+
+            &:has(pap-treeitem.marked) {
+
+                &::part(content) {
+                    background-color: var(--background);
+                }
+
+                pap-treeitem:not(.marked) {
+                    &::part(content) {
+                        background-color: var(--background);
+                    }
+                }
+            }
+
+
+            &:hover,
+            &.marked {
+                &::part(content) {
+                    background-color: var(--background-dark);
+                }
+            }
+
+        }
+    }
+}`);var u=m;var i=class extends b{constructor(){super(...arguments);this.observer=new IntersectionObserver(this.handleobserve);this.links=[];this.query=['[role="heading"]',"h1","h2","h3","h4","h5","h6"].map(t=>t+":not([aria-hidden]):not([data-skipped])").join(",")}static{this.sheet=u}get value(){return this.links.filter(t=>t.marked).map(t=>({href:t.href,name:t.name}))}handleobserve(t,r){t.forEach(e=>{let n=this.links.find(a=>a.reference===e.target);n&&(n.marked=("isVisible"in e?e.isVisible:!1)||e.isIntersecting)}),this.dispatchEvent(new Event("change")),this._internals.states.add("scrolling"),this.stopscrolling(),this.throttleUpdate()}handleenter(t){t.target instanceof HTMLElement&&(window.location.hash=t.target.querySelector("a")?.getAttribute("href")??"")}handleactive(){this._internals.states.add("active")}handleinactive(){this._internals.states.delete("active")}stopscrolling(){this._internals.states.delete("scrolling")}buildHierarchy(t){let r=[],e=[];for(let n of t){let a={...n,children:[]};for(;e.length>0&&e[e.length-1].level>=n.level;)e.pop();e.length===0?r.push(a):e[e.length-1].item.children.push(a),e.push({item:a,level:n.level})}return r}renderTreeItems(t){return t.length===0?null:t.map(r=>{let e=r.children.length>0,n=r.marked;return e?l`
+                    <pap-treeitem part="item" @enter="${this.handleenter}" aria-expanded="true" class="${n?"marked":""}">
+                        <a part="anchor" tabindex="-1" href="${r.href}">
+                            ${r.icon&&l`<pap-icon name="${r.icon}"></pap-icon>`}
+                            ${k(r.name)}
+                        </a>
+                        ${this.renderTreeItems(r.children)}
+                    </pap-treeitem>
+                `:l`
+                    <pap-treeitem part="item" @enter="${this.handleenter}" aria-expanded="true" class="${n?"marked":""}">
+                        <a part="anchor" tabindex="-1" href="${r.href}">
+                            ${r.icon&&l`<pap-icon name="${r.icon}"></pap-icon>`}
+                            ${k(r.name)}
+                        </a>
+                    </pap-treeitem>
+                `})}render(){let t=this.buildHierarchy(this.links);return l`
+            <slot></slot>
+            <pap-treeview @active="${this.handleactive}" @inactive="${this.handleinactive}" part="tree">
+                ${this.renderTreeItems(t)}
+            </pap-treeview>
+        `}};s([v({attribute:!1})],i.prototype,"links",2),s([v({reflect:!1,after(){let t=this.getRootNode(),r=[];(t instanceof Document||t instanceof ShadowRoot||t instanceof HTMLElement)&&t.querySelectorAll(this.query).forEach(e=>{if(!(e instanceof HTMLElement))return;let n=e.textContent??e.getAttribute("aria-label");if(!n)return;let a=0;if(e.hasAttribute("aria-level"))a=Number(e.getAttribute("aria-level"));else if(e instanceof HTMLHeadingElement){let d=e.nodeName.match(/H(\d)/i);d&&(a=parseInt(d[1],10))}let p=n.toLowerCase().replace(/\s/g,"-");e.setAttribute("id",p),r.push({reference:e,href:"#"+p,name:n,icon:e.getAttribute("data-icon"),marked:!1,level:a}),this.observer.observe(e)}),this.links=r,this.requestUpdate()}})],i.prototype,"query",2),s([c],i.prototype,"handleobserve",1),s([c],i.prototype,"handleenter",1),s([c],i.prototype,"handleactive",1),s([c],i.prototype,"handleinactive",1),s([w(500)],i.prototype,"stopscrolling",1);if(!window.customElements)throw new Error("Custom Elements not supported");window.customElements.get("pap-table-of-content")||window.customElements.define("pap-table-of-content",i);export{i as TableOfContent};

package/lib/react-wrapper.d.ts

@@ -0,0 +1,38 @@
+import type { HTMLAttributes } from 'react';
+import type { ReactElement } from 'react';
+import type { ReactNode } from 'react';
+import type { Ref } from 'react';
+import type { TableOfContent as TableOfContent_2 } from '@papit/table-of-content';
+
+/** React wrapper for the `pap-table-of-content` element. */
+export declare function TableOfContent({ ref, onChange, links, ...props }: TableOfContentProps): ReactElement;
+
+export declare interface TableOfContentProps extends Omit<HTMLAttributes<TableOfContent_2>, "links" | "query" | "disabled" | "onChange"> {
+    links?: TableOfContent_2["links"];
+    query?: TableOfContent_2["query"];
+    /**
+     * Reactive disabled property.
+     * - `rerender: false` → does not trigger a re-render when changed
+     * - `type: Boolean` → coerces values to `true`/`false`
+     * - `aria: 'aria-disabled'` → syncs to ARIA for accessibility
+     * - `removeAttribute: true` → removes `disabled` attribute when false
+     */
+    disabled?: TableOfContent_2["disabled"];
+    /**
+     * Dispatched whenever the set of visible (intersecting) headings
+     * changes. Read {@link value} inside the handler to get the current active set.
+     */
+    onChange?: (event: Event) => void;
+    ref?: Ref<TableOfContent_2>;
+    children?: ReactNode;
+}
+
+declare module "react" {
+    namespace JSX {
+        interface IntrinsicElements {
+            "pap-table-of-content": Omit<TableOfContentProps, "onChange" | "links">;
+        }
+    }
+}
+
+export { }

package/lib/react-wrapper.js

@@ -0,0 +1 @@
+"use client";import{useCallback as u,useEffect as i,useRef as c}from"react";import{jsx as s}from"react/jsx-runtime";typeof window<"u"&&import("@papit/table-of-content");function p({ref:t,onChange:l,links:r,...f}){let o=c(null),a=u(e=>{o.current=e;let n;return typeof t=="function"?n=t(e):t&&(t.current=e),()=>{o.current=null,typeof n=="function"?n():typeof t=="function"?t(null):t&&(t.current=null)}},[t]);return i(()=>{let e=o.current;if(!(!e||!l))return e.addEventListener("change",l),()=>e.removeEventListener("change",l)},[l]),i(()=>{let e=o.current;if(!e)return;let n=!0;return customElements.whenDefined("pap-table-of-content").then(()=>{n&&r!==void 0&&(e.links=r)}),()=>{n=!1}},[r]),s("pap-table-of-content",{suppressHydrationWarning:!0,...f,ref:a})}export{p as TableOfContent};

package/package.json

@@ -1,6 +1,104 @@
 {
   "name": "@papit/table-of-content",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "A page-aware table of contents that builds a tree from the page's headings and highlights the ones currently in view. Clicking an item jumps to its section via the URL hash.",
+  "keywords": [
+    "papit",
+    "web-component",
+    "typescript",
+    "table-of-content",
+    "toc",
+    "navigation",
+    "headings"
+  ],
+  "version": "0.0.2",
+  "scripts": {
+    "build": "npx @papit/build --error",
+    "analyse": "npx @papit/analyse",
+    "generate:react": "npx @papit/react",
+    "watch": "tsc -w",
+    "start": "npx @papit/server --info --live",
+    "test": "npx playwright test -c tests/playwright.config.ts $@",
+    "preversion": "papit-version",
+    "postversion": "papit-version",
+    "component": "npm create @papit --component",
+    "test:update-snapshots": "npx playwright test --update-snapshots -c tests/playwright.config.ts",
+    "test:chrome": "npm test -- --project=chromium"
+  },
+  "main": "./lib/bundle.js",
+  "types": "./lib/bundle.d.ts",
+  "type": "module",
+  "files": [
+    "asset/",
+    "lib/"
+  ],
+  "exports": {
+    ".": {
+      "import": "./lib/bundle.js",
+      "types": "./lib/bundle.d.ts"
+    },
+    "./react": {
+      "import": "./lib/react-wrapper.js",
+      "types": "./lib/react-wrapper.d.ts"
+    }
+  },
+  "author": "henry",
+  "private": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "license": "LicenseRef-Papit-1.0",
+  "homepage": "https://github.com/onkelhoy/papit/tree/main/packages/web/design-system/atoms/table-of-content",
+  "bugs": {
+    "url": "https://github.com/onkelhoy/papit/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/onkelhoy/papit.git",
+    "directory": "packages/web/design-system/atoms/table-of-content"
+  },
+  "sideEffects": true,
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@papit/treeview": "0.0.11",
+    "@papit/web-component": "0.0.11"
+  },
+  "peerDependencies": {
+    "react": "^19"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@papit/codeblock": "0.1.14",
+    "@papit/router": "0.1.7",
+    "@papit/tabs": "0.1.7",
+    "@papit/theme": "0.0.3",
+    "@papit/translator": "0.1.1",
+    "@playwright/test": "1.64.1",
+    "playwright": "1.64.1",
+    "typescript": "5.9.3"
+  },
+  "browserslist": [
+    "defaults",
+    "not IE 11",
+    "not dead"
+  ],
+  "papit": {
+    "publish": true,
+    "type": "web-component",
+    "main": "table-of-content",
+    "htmlprefix": "pap",
+    "components": {
+      "table-of-content": {
+        "className": "TableOfContent",
+        "htmlprefix": "pap"
+      }
+    }
+  },
+  "remoteVersion": ""
 }