@toyonix/web-kit 0.1.1 → 0.1.3

package/dist/css/components.css

@@ -111,6 +111,83 @@
   outline: var(--tx-border-width) solid var(--tx-border);
 }
 
+/*
+ * Narrow screens: stay on one row. The header gets more compact, and if the app links still
+ * don't fit, they scroll sideways (AppShell scrolls the current app into view).
+ */
+@media (max-width: 640px) {
+  .tx-header__inner {
+    gap: 10px;
+    min-height: 56px;
+  }
+
+  .tx-logo {
+    flex: none;
+    gap: 8px;
+    font-size: 20px;
+  }
+
+  .tx-logo__mark {
+    width: 26px;
+    height: 26px;
+    font-size: 13px;
+  }
+
+  .tx-nav {
+    flex: 0 1 auto;
+    flex-wrap: nowrap;
+    min-width: 0;
+    padding: 3px; /* room for the current app's outline */
+    overflow-x: auto;
+    scrollbar-width: none;
+  }
+
+  .tx-nav::-webkit-scrollbar {
+    display: none;
+  }
+
+  /* Fade only the edges that have more links beyond them (set by AppShell), hinting at the scroll. */
+  .tx-nav[data-more-left],
+  .tx-nav[data-more-right] {
+    --tx-nav-fade-left: 0px;
+    --tx-nav-fade-right: 0px;
+    -webkit-mask-image: linear-gradient(
+      to right,
+      transparent,
+      #000 var(--tx-nav-fade-left),
+      #000 calc(100% - var(--tx-nav-fade-right)),
+      transparent
+    );
+    mask-image: linear-gradient(
+      to right,
+      transparent,
+      #000 var(--tx-nav-fade-left),
+      #000 calc(100% - var(--tx-nav-fade-right)),
+      transparent
+    );
+  }
+
+  .tx-nav[data-more-left] {
+    --tx-nav-fade-left: 22px;
+  }
+
+  .tx-nav[data-more-right] {
+    --tx-nav-fade-right: 22px;
+  }
+
+  .tx-nav a {
+    flex: none;
+    padding: 6px 9px;
+    font-size: 14px;
+  }
+
+  .tx-header__inner .tx-icon-btn {
+    flex: none;
+    width: 36px;
+    height: 36px;
+  }
+}
+
 .tx-subnav {
   border-bottom: var(--tx-border-width) solid var(--tx-border);
   background: var(--tx-surface);
@@ -891,9 +968,204 @@
   outline: var(--tx-border-width) solid var(--tx-border);
 }
 
+/* ============================== table of contents ============================== */
+
+/*
+ * Wide screens: article + sticky "On this page" column. Narrow screens: the column is hidden
+ * and a floating button opens the same list in a menu that slides in from the right.
+ */
+.tx-with-toc {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr);
+  gap: 64px;
+  align-items: start;
+}
+
+.tx-toc {
+  display: none;
+}
+
+@media (min-width: 1100px) {
+  .tx-with-toc {
+    grid-template-columns: minmax(0, 1fr) 240px;
+  }
+
+  .tx-toc {
+    display: block;
+    position: sticky;
+    top: 96px;
+    max-height: calc(100vh - 120px);
+    overflow-y: auto;
+    padding: 6px 4px 12px 0;
+  }
+
+  .tx-toc-trigger {
+    display: none !important;
+  }
+}
+
+.tx-toc__title {
+  margin-bottom: 18px;
+  font-size: 18px;
+}
+
+.tx-toc__list {
+  margin: 0;
+  padding: 0 0 0 14px;
+  border-left: var(--tx-border-width) solid var(--tx-border);
+  list-style: none;
+}
+
+.tx-toc__item {
+  margin: 0;
+}
+
+.tx-toc__item--sub {
+  padding-left: 14px;
+}
+
+.tx-toc__link {
+  display: block;
+  padding: 5px 0;
+  color: var(--tx-text-muted);
+  font-size: 14px;
+  line-height: 1.35;
+  text-decoration: none;
+}
+
+.tx-toc__item--sub .tx-toc__link {
+  font-size: 13px;
+}
+
+.tx-toc__link:hover {
+  color: var(--tx-text);
+}
+
+.tx-toc__link[aria-current] {
+  color: var(--tx-text);
+  font-weight: 600;
+}
+
+/* The current section gets the marker highlight, like <em> in headlines. */
+.tx-toc__link[aria-current] .tx-toc__text {
+  background: linear-gradient(transparent 58%, var(--tx-accent) 58%, var(--tx-accent) 92%, transparent 92%);
+  -webkit-box-decoration-break: clone;
+  box-decoration-break: clone;
+}
+
+.tx-toc-trigger {
+  position: fixed;
+  right: 16px;
+  bottom: calc(16px + env(safe-area-inset-bottom));
+  z-index: 40;
+  font-size: 14px;
+}
+
+.tx-toc-overlay {
+  z-index: 60;
+}
+
+.tx-toc-drawer {
+  position: fixed;
+  top: 0;
+  right: 0;
+  bottom: 0;
+  z-index: 61;
+  display: flex;
+  flex-direction: column;
+  width: min(340px, 86vw);
+  padding: 20px 20px calc(24px + env(safe-area-inset-bottom));
+  overflow-y: auto;
+  border-left: var(--tx-border-width) solid var(--tx-border);
+  background: var(--tx-surface);
+  box-shadow: -6px 0 0 var(--tx-border);
+  color: var(--tx-text);
+}
+
+.tx-toc-drawer[data-state="open"] {
+  animation: tx-slide-in-right 0.22s ease-out;
+}
+
+.tx-toc-drawer[data-state="closed"] {
+  animation: tx-slide-out-right 0.16s ease-in;
+}
+
+.tx-toc-overlay[data-state="open"] {
+  animation: tx-fade-in 0.2s ease-out;
+}
+
+.tx-toc-overlay[data-state="closed"] {
+  animation: tx-fade-out 0.16s ease-in;
+}
+
+.tx-toc-drawer__head {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 12px;
+  margin-bottom: 4px;
+}
+
+.tx-toc-drawer__close {
+  padding: 6px 12px;
+}
+
+.tx-toc-drawer .tx-toc__link {
+  padding: 10px 0; /* bigger tap targets */
+  font-size: 16px;
+}
+
+.tx-toc-drawer .tx-toc__item--sub .tx-toc__link {
+  font-size: 15px;
+}
+
+@keyframes tx-slide-in-right {
+  from {
+    transform: translateX(100%);
+  }
+}
+
+@keyframes tx-slide-out-right {
+  to {
+    transform: translateX(100%);
+  }
+}
+
+@keyframes tx-fade-in {
+  from {
+    opacity: 0;
+  }
+}
+
+@keyframes tx-fade-out {
+  to {
+    opacity: 0;
+  }
+}
+
+/* Anchor jumps (table of contents, #links) land below the sticky header, not under it. */
+.tx-prose :is(h2, h3, h4) {
+  scroll-margin-top: 96px;
+}
+
+.tx-visually-hidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  clip: rect(0 0 0 0);
+  clip-path: inset(50%);
+  white-space: nowrap;
+}
+
 /* ============================== motion ============================== */
 
 @media (prefers-reduced-motion: reduce) {
+  .tx-toc-drawer,
+  .tx-toc-overlay {
+    animation: none !important;
+  }
+
   .tx-btn,
   .tx-card--link,
   .tx-switch,

package/dist/react/AppShell.js

@@ -3,6 +3,7 @@ import { appHref, getAppId } from "../env.js";
 import { navApps } from "../registry/index.js";
 import { ThemeToggle } from "./ThemeToggle.js";
 import { useRegistry } from "./use-registry.js";
+import { useEffect, useRef } from "react";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 //#region src/react/AppShell.tsx
 /**
@@ -12,6 +13,29 @@ import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 function AppShell({ children, registry, appTitle, nav, footer }) {
 	const appId = getAppId();
 	const apps = navApps(useRegistry(registry));
+	const navRef = useRef(null);
+	const appCount = apps.length;
+	useEffect(() => {
+		const nav = navRef.current;
+		if (!nav) return;
+		const markEdges = () => {
+			const max = nav.scrollWidth - nav.clientWidth;
+			nav.toggleAttribute("data-more-left", max > 1 && nav.scrollLeft > 1);
+			nav.toggleAttribute("data-more-right", max > 1 && nav.scrollLeft < max - 1);
+		};
+		const update = () => {
+			const current = nav.querySelector("[aria-current]");
+			if (current && nav.scrollWidth > nav.clientWidth + 1) nav.scrollLeft = current.offsetLeft - (nav.clientWidth - current.offsetWidth) / 2;
+			markEdges();
+		};
+		update();
+		nav.addEventListener("scroll", markEdges, { passive: true });
+		window.addEventListener("resize", update);
+		return () => {
+			nav.removeEventListener("scroll", markEdges);
+			window.removeEventListener("resize", update);
+		};
+	}, [appCount]);
 	if (appId !== "root" && !apps.some((app) => app.id === appId)) apps.push({
 		id: appId,
 		title: appTitle ?? appId,
@@ -42,6 +66,7 @@ function AppShell({ children, registry, appTitle, nav, footer }) {
 						}), /* @__PURE__ */ jsx("span", { children: "toyonix" })]
 					}),
 					/* @__PURE__ */ jsxs("nav", {
+						ref: navRef,
 						className: "tx-nav",
 						"aria-label": "toyonix apps",
 						children: [/* @__PURE__ */ jsx("a", {

package/dist/react/TableOfContents.d.ts

@@ -0,0 +1,23 @@
+//#region src/react/TableOfContents.d.ts
+export interface TocItem {
+  /** The heading element's id (the anchor). */
+  id: string;
+  text: string;
+  /** 2 for `##`, 3 for `###`. Deeper levels are better left out. */
+  depth: 2 | 3;
+}
+export interface TableOfContentsProps {
+  items: TocItem[];
+  /** Below this many items nothing renders (a short note doesn't need an index). Default 3. */
+  minItems?: number;
+  title?: string;
+  className?: string;
+}
+/**
+ * "On this page" navigation for long articles. Place it as the second child of a `.tx-with-toc`
+ * grid, next to the article. Wide screens get a sticky column; narrow screens get a floating
+ * button that opens a menu sliding in from the right. Works without JS (plain anchor links);
+ * JS adds the current-section highlight and the mobile menu.
+ */
+export declare function TableOfContents({ items, minItems, title, className }: TableOfContentsProps): import("react").JSX.Element | null;
+//#endregion

package/dist/react/TableOfContents.js

@@ -0,0 +1,135 @@
+"use client";
+import { cx } from "./cx.js";
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { Dialog } from "radix-ui";
+//#region src/react/TableOfContents.tsx
+/** How far below the viewport top a heading counts as "current" (clears the sticky header). */
+const ACTIVE_OFFSET = 120;
+/** The id of the last heading scrolled past, or the first one before any. */
+function useActiveHeading(ids) {
+	const [active, setActive] = useState(ids[0]);
+	useEffect(() => {
+		if (ids.length === 0) return;
+		let frame = 0;
+		const update = () => {
+			frame = 0;
+			let current = ids[0];
+			for (const id of ids) {
+				const element = document.getElementById(id);
+				if (element && element.getBoundingClientRect().top <= ACTIVE_OFFSET) current = id;
+			}
+			setActive(current);
+		};
+		const onScroll = () => {
+			if (!frame) frame = requestAnimationFrame(update);
+		};
+		update();
+		window.addEventListener("scroll", onScroll, { passive: true });
+		window.addEventListener("resize", onScroll);
+		return () => {
+			window.removeEventListener("scroll", onScroll);
+			window.removeEventListener("resize", onScroll);
+			if (frame) cancelAnimationFrame(frame);
+		};
+	}, [ids]);
+	return active;
+}
+function TocList({ items, active, onNavigate }) {
+	return /* @__PURE__ */ jsx("ol", {
+		className: "tx-toc__list",
+		children: items.map((item) => /* @__PURE__ */ jsx("li", {
+			className: cx("tx-toc__item", item.depth === 3 && "tx-toc__item--sub"),
+			children: /* @__PURE__ */ jsx("a", {
+				className: "tx-toc__link",
+				href: `#${item.id}`,
+				"aria-current": item.id === active ? "location" : void 0,
+				onClick: onNavigate ? (event) => onNavigate(event, item.id) : void 0,
+				children: /* @__PURE__ */ jsx("span", {
+					className: "tx-toc__text",
+					children: item.text
+				})
+			})
+		}, item.id))
+	});
+}
+/**
+* "On this page" navigation for long articles. Place it as the second child of a `.tx-with-toc`
+* grid, next to the article. Wide screens get a sticky column; narrow screens get a floating
+* button that opens a menu sliding in from the right. Works without JS (plain anchor links);
+* JS adds the current-section highlight and the mobile menu.
+*/
+function TableOfContents({ items, minItems = 3, title = "On this page", className }) {
+	const [open, setOpen] = useState(false);
+	const [pending, setPending] = useState(null);
+	const idKey = items.map((item) => item.id).join("\n");
+	const active = useActiveHeading(useMemo(() => idKey ? idKey.split("\n") : [], [idKey]));
+	const navigateFromMenu = useCallback((event, id) => {
+		event.preventDefault();
+		setPending(id);
+		setOpen(false);
+	}, []);
+	const finishNavigation = useCallback((event) => {
+		if (!pending) return;
+		event.preventDefault();
+		const target = document.getElementById(pending);
+		setPending(null);
+		if (!target) return;
+		history.pushState(null, "", `#${pending}`);
+		target.scrollIntoView({ block: "start" });
+	}, [pending]);
+	if (items.length < minItems) return null;
+	return /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsxs("nav", {
+		className: cx("tx-toc", className),
+		"aria-label": title,
+		children: [/* @__PURE__ */ jsx("p", {
+			className: "tx-section-label tx-toc__title",
+			children: title
+		}), /* @__PURE__ */ jsx(TocList, {
+			items,
+			active
+		})]
+	}), /* @__PURE__ */ jsxs(Dialog.Root, {
+		open,
+		onOpenChange: setOpen,
+		children: [/* @__PURE__ */ jsxs(Dialog.Trigger, {
+			className: "tx-btn tx-btn--primary tx-toc-trigger",
+			"aria-label": `Open: ${title}`,
+			children: [
+				/* @__PURE__ */ jsx("span", {
+					"aria-hidden": "true",
+					children: "☰"
+				}),
+				" ",
+				title
+			]
+		}), /* @__PURE__ */ jsxs(Dialog.Portal, { children: [/* @__PURE__ */ jsx(Dialog.Overlay, { className: "tx-overlay tx-toc-overlay" }), /* @__PURE__ */ jsxs(Dialog.Content, {
+			className: "tx-toc-drawer",
+			onCloseAutoFocus: finishNavigation,
+			children: [
+				/* @__PURE__ */ jsxs("div", {
+					className: "tx-toc-drawer__head",
+					children: [/* @__PURE__ */ jsx(Dialog.Title, {
+						className: "tx-section-label tx-toc__title",
+						children: title
+					}), /* @__PURE__ */ jsx(Dialog.Close, {
+						className: "tx-btn tx-btn--ghost tx-toc-drawer__close",
+						"aria-label": "Close",
+						children: "✕"
+					})]
+				}),
+				/* @__PURE__ */ jsx(Dialog.Description, {
+					className: "tx-visually-hidden",
+					children: "Jump to a section of this page."
+				}),
+				/* @__PURE__ */ jsx(TocList, {
+					items,
+					active,
+					onNavigate: navigateFromMenu
+				})
+			]
+		})] })]
+	})] });
+}
+//#endregion
+export { TableOfContents };

package/dist/react/index.d.ts

@@ -18,4 +18,5 @@ import { Dialog, DialogClose, DialogContent, DialogContentProps, DialogTrigger }
 import { DropdownMenu, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuTrigger } from "./DropdownMenu.js";
 import { Tooltip, TooltipProps } from "./Tooltip.js";
 import { Tabs, TabsContent, TabsList, TabsTrigger } from "./Tabs.js";
-export { Alert, type AlertTone, AppLink, type AppLinkProps, AppShell, type AppShellProps, Badge, type BadgeTone, Badges, Button, type ButtonProps, ButtonRow, type ButtonVariant, Card, CardBody, CardCta, CardGrid, CardMeta, type CardProps, CardTitle, CardTop, Checkbox, CodeBlock, Container, Dialog, DialogClose, DialogContent, type DialogContentProps, DialogTrigger, Display, DropdownMenu, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuTrigger, Eyebrow, Field, Form, Input, Lead, LinkButton, type LinkButtonProps, LinkCard, Mark, Prose, Radio, Row, Section, SectionLabel, Select, Stack, Switch, Table, Tabs, TabsContent, TabsList, TabsTrigger, Tag, Tags, Textarea, ThemeScript, type ThemeState, ThemeToggle, Tooltip, type TooltipProps, cx, useRegistry, useTheme };
+import { TableOfContents, TableOfContentsProps, TocItem } from "./TableOfContents.js";
+export { Alert, type AlertTone, AppLink, type AppLinkProps, AppShell, type AppShellProps, Badge, type BadgeTone, Badges, Button, type ButtonProps, ButtonRow, type ButtonVariant, Card, CardBody, CardCta, CardGrid, CardMeta, type CardProps, CardTitle, CardTop, Checkbox, CodeBlock, Container, Dialog, DialogClose, DialogContent, type DialogContentProps, DialogTrigger, Display, DropdownMenu, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuTrigger, Eyebrow, Field, Form, Input, Lead, LinkButton, type LinkButtonProps, LinkCard, Mark, Prose, Radio, Row, Section, SectionLabel, Select, Stack, Switch, Table, TableOfContents, type TableOfContentsProps, Tabs, TabsContent, TabsList, TabsTrigger, Tag, Tags, Textarea, ThemeScript, type ThemeState, ThemeToggle, type TocItem, Tooltip, type TooltipProps, cx, useRegistry, useTheme };

package/dist/react/index.js

@@ -18,4 +18,5 @@ import { Dialog, DialogClose, DialogContent, DialogTrigger } from "./Dialog.js";
 import { DropdownMenu, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuTrigger } from "./DropdownMenu.js";
 import { Tooltip } from "./Tooltip.js";
 import { Tabs, TabsContent, TabsList, TabsTrigger } from "./Tabs.js";
-export { Alert, AppLink, AppShell, Badge, Badges, Button, ButtonRow, Card, CardBody, CardCta, CardGrid, CardMeta, CardTitle, CardTop, Checkbox, CodeBlock, Container, Dialog, DialogClose, DialogContent, DialogTrigger, Display, DropdownMenu, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuTrigger, Eyebrow, Field, Form, Input, Lead, LinkButton, LinkCard, Mark, Prose, Radio, Row, Section, SectionLabel, Select, Stack, Switch, Table, Tabs, TabsContent, TabsList, TabsTrigger, Tag, Tags, Textarea, ThemeScript, ThemeToggle, Tooltip, cx, useRegistry, useTheme };
+import { TableOfContents } from "./TableOfContents.js";
+export { Alert, AppLink, AppShell, Badge, Badges, Button, ButtonRow, Card, CardBody, CardCta, CardGrid, CardMeta, CardTitle, CardTop, Checkbox, CodeBlock, Container, Dialog, DialogClose, DialogContent, DialogTrigger, Display, DropdownMenu, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuTrigger, Eyebrow, Field, Form, Input, Lead, LinkButton, LinkCard, Mark, Prose, Radio, Row, Section, SectionLabel, Select, Stack, Switch, Table, TableOfContents, Tabs, TabsContent, TabsList, TabsTrigger, Tag, Tags, Textarea, ThemeScript, ThemeToggle, Tooltip, cx, useRegistry, useTheme };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toyonix/web-kit",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Shared design system, components, and tooling for every toyonix static site.",
   "license": "MIT",
   "author": "ToYoNiX",