highsoft-ui 1.0.172 → 1.0.173

package/CLAUDE.md

@@ -960,6 +960,42 @@ import NextLink from 'next/link'
 - The disabled edge card is a non-interactive `aria-disabled` span — not focusable, so keyboard users skip straight to the real links, while AT can still read "Previous —" as "there is no previous page".
 - DOM order is prev → back → next, matching the desktop visual order, so focus moves left-to-right across the row.
 
+### TableOfContents
+"On this page" navigation for an article: a rule down the left, a semibold title and one link per heading. Uncontrolled by default with a built-in scroll spy; pass `activeId` to drive the highlight yourself.
+
+```tsx
+const items: TableOfContentsItem[] = [
+  { id: 'requirements', title: 'Requirements' },
+  { id: 'install', title: '1. Install Highcharts React' },
+  { id: 'customize', title: '3. Customize your chart' },
+  { id: 'chart-elements', title: 'Chart elements', level: 2 },   // indented under the row above
+]
+
+// Scroll spy on: the current row is the last heading past the fold line.
+// Set spyOffset to the sticky header's height (plus the headings' scroll-margin-top).
+<TableOfContents items={items} spyOffset={96} style={{ position: 'sticky', top: 96 }} />
+
+// Controlled: you own the highlight; onActiveChange reports clicks
+<TableOfContents items={items} activeId={active} onActiveChange={setActive} />
+
+// Take over the navigation (eased scroll with a header offset) — the row still goes current
+<TableOfContents items={items} onItemClick={(item, e) => { e.preventDefault(); scrollTo(item.id) }} />
+```
+
+- **`items`:** `TableOfContentsItem[]` — `{ id, title, level?, href? }`. `id` is the heading element's id: the link target (`#id`) and what the spy watches. `level` `1` (default) | `2` | `3` indents 12px per step. `href` overrides the `#id` target. Renders nothing when empty.
+- **`title`:** the heading above the list (default `'On this page'`); `null` hides it.
+- **`activeId` / `onActiveChange(id)`:** controlled highlight; `null` highlights nothing. When `activeId` is given the spy is off. `onActiveChange` fires on spy changes and on clicks. **`defaultActiveId`** seeds the highlight in uncontrolled mode; the spy takes over once it finds headings, and while there are none (not rendered yet, or `spy={false}`) the highlight stays put and clicks move it.
+- **`spy`** (default `true`) / **`spyOffset`** (default `0`): the current heading is the last one whose top has crossed `spyOffset` px from the top of the viewport. The listener runs in the capture phase, so a scrolling container works as well as the window. **A clicked row stays current while its heading is on screen** even if it can't reach the fold line (a short last section never can); any wheel, touch or key input hands control back to the spy. A hash in the URL on mount pins its row the same way.
+- **`onItemClick(item, event)`:** runs before the hash navigation; `preventDefault()` to take it over.
+- Rows are 14px/1.3 tertiary text on a 25px pitch (7px gap), text 15px in from the rule, 32px above the title and 12px below the last row — the Figma geometry. Hover lifts a row to `--HS-text-primary-default` and grows a 2px `--HS-surface-ui-border-300` bar over the rule; the current row keeps the bar in `--HS-surface-ui-border-1000`. The bar is a `::before` whose width animates in and out on `--hsui-toc-bar-bounce` (default `--animations-bounce-fast`, so it overshoots a touch and settles); it isn't a border, so the text never moves. **Colours are not transitioned** — neither the text nor the bar — for the same reason as ButtonGroup: a colour transition can't tell a hover from a `data-theme` flip, so it would fade the rail behind the rest of the page on a theme change. The rule is a pseudo-element too, so the bar can cover it. Everything is `--HS-*` tokens, so dark mode is automatic (border-1000 remaps to neutral-0). Width, stickiness and the breakpoint that hides the rail belong to the page.
+
+**Accessibility:**
+- A real `<nav>` named by its visible title via `aria-labelledby` (AT announces "On this page, navigation"); with `title={null}` it takes `aria-label`, falling back to "On this page". Pass `aria-label` explicitly to override either way.
+- The rows are a `<ul role="list">` of real links (the role keeps Safari/VoiceOver from dropping list semantics from an unstyled list), so a screen reader hears "list, 6 items" and can jump between them. The current row carries `aria-current="location"` — the value for "where you are within the page" — so it is announced whichever way it was reached.
+- Keyboard: Tab through the links, Enter follows the hash and marks the row current; `:focus-visible` draws the shared two-tone brand focus ring (the `a11y-focus-ring` mixin, animating on `--animations-bounce-default`). Keyboard scrolling counts as reader input and releases a pinned row to the spy.
+- Hover and current states pair the bar with a text-colour change, so neither rests on colour alone. The bar's width grows on the bounce token and is instant under `prefers-reduced-motion: reduce`, which leaves nothing animating; colours switch instantly in every mode. The spy only swaps which row is current.
+- Rows are 18px tall on a 25px pitch: under the 24px minimum of WCAG 2.5.8, but the pitch keeps every target at least 24px from the next, which is the criterion's spacing exception. Nested rows indent without shrinking.
+
 ## Hooks
 
 ### useSuccessFlash

package/README.md

@@ -15,6 +15,7 @@ The Highsoft design system — a React component library, design tokens, a Story
 | --- | --- | --- | --- |
 | `lib/` | The component library (the published package) | `npm run build` → `dist/` | npm — `highsoft-ui` |
 | `src/` | The Astro docs site (multi-page, React islands) | `npm run build:app` → `dist-app/` | design.highdev.dev |
+| `tools/icon-studio/` | 3D icon studio and local Blender helper | `npm run build:app` | Design site only — never npm |
 | `stories/` | Storybook stories | `npm run build-storybook` | storybook.highdev.dev |
 
 `lib/` is the source of truth; the docs site and Storybook both consume it directly (via the `highsoft-ui` alias), so a change to a component shows up in all three.

package/dist/TableOfContents-d26S7KYx.js

@@ -0,0 +1,93 @@
+"use client";
+import { t as e } from "./clsx-BWCAbrjV.js";
+import { forwardRef as t, useEffect as n, useId as r, useRef as i, useState as a } from "react";
+import { jsx as o, jsxs as s } from "react/jsx-runtime";
+var c = {
+	active: "_0J7mWW_active",
+	item: "_0J7mWW_item",
+	"level-2": "_0J7mWW_level-2",
+	"level-3": "_0J7mWW_level-3",
+	link: "_0J7mWW_link",
+	list: "_0J7mWW_list",
+	title: "_0J7mWW_title",
+	toc: "_0J7mWW_toc"
+}, l = t(({ items: t, title: l = "On this page", activeId: u, defaultActiveId: d = null, onActiveChange: f, spy: p = !0, spyOffset: m = 0, onItemClick: h, className: g, "aria-label": _, ...v }, y) => {
+	let b = r(), x = u !== void 0, [S, C] = a(d), w = x ? u : S, T = i(null), E = i(void 0), D = i(f);
+	D.current = f;
+	let O = !x && p && t.length > 0, k = t.map((e) => e.id).join("\n");
+	if (n(() => {
+		if (!O) return;
+		let e = k.split("\n"), t = decodeURIComponent(window.location.hash.slice(1));
+		t && e.includes(t) && (T.current = t);
+		let n = (e) => {
+			e !== E.current && (E.current = e, C(e), D.current?.(e));
+		}, r = () => {
+			if (T.current) {
+				let e = document.getElementById(T.current)?.getBoundingClientRect().top;
+				if (e !== void 0 && e >= 0 && e <= window.innerHeight) {
+					n(T.current);
+					return;
+				}
+				T.current = null;
+			}
+			let t = null;
+			for (let n of e) {
+				let e = document.getElementById(n);
+				e && (t === null && (t = n), e.getBoundingClientRect().top <= m && (t = n));
+			}
+			t !== null && n(t);
+		}, i = () => {
+			T.current = null;
+		};
+		return r(), window.addEventListener("scroll", r, {
+			capture: !0,
+			passive: !0
+		}), window.addEventListener("resize", r), window.addEventListener("wheel", i, {
+			capture: !0,
+			passive: !0
+		}), window.addEventListener("touchmove", i, {
+			capture: !0,
+			passive: !0
+		}), window.addEventListener("keydown", i, { capture: !0 }), () => {
+			window.removeEventListener("scroll", r, { capture: !0 }), window.removeEventListener("resize", r), window.removeEventListener("wheel", i, { capture: !0 }), window.removeEventListener("touchmove", i, { capture: !0 }), window.removeEventListener("keydown", i, { capture: !0 });
+		};
+	}, [
+		O,
+		k,
+		m
+	]), t.length === 0) return null;
+	let A = (e, t) => {
+		h?.(e, t), T.current = e.id, x || C(e.id), (x || E.current !== e.id) && (E.current = e.id, f?.(e.id));
+	}, j = l != null;
+	return /* @__PURE__ */ s("nav", {
+		ref: y,
+		className: e(c.toc, g),
+		"aria-labelledby": j && _ == null ? b : void 0,
+		"aria-label": _ ?? (j ? void 0 : "On this page"),
+		...v,
+		children: [j && /* @__PURE__ */ o("p", {
+			id: b,
+			className: c.title,
+			children: l
+		}), /* @__PURE__ */ o("ul", {
+			className: c.list,
+			role: "list",
+			children: t.map((t) => {
+				let n = w === t.id;
+				return /* @__PURE__ */ o("li", {
+					className: e(c.item, c[`level-${t.level ?? 1}`]),
+					children: /* @__PURE__ */ o("a", {
+						href: t.href ?? `#${t.id}`,
+						className: e(c.link, n && c.active),
+						"aria-current": n ? "location" : void 0,
+						onClick: (e) => A(t, e),
+						children: t.title
+					})
+				}, t.id);
+			})
+		})]
+	});
+});
+l.displayName = "TableOfContents";
+//#endregion
+export { l as t };

package/dist/components/TableOfContents/index.js

@@ -0,0 +1,2 @@
+import { t as e } from "../../TableOfContents-d26S7KYx.js";
+export { e as TableOfContents };