@toyonix/web-kit 0.1.0 → 0.1.2

package/dist/css/components.css

@@ -111,6 +111,35 @@
   outline: var(--tx-border-width) solid var(--tx-border);
 }
 
+/* Narrow screens: app links get their own row under the logo, scrolling sideways if needed. */
+@media (max-width: 640px) {
+  .tx-header__inner {
+    flex-wrap: wrap;
+    row-gap: 4px;
+    padding-top: 10px;
+    padding-bottom: 8px;
+    min-height: 0;
+  }
+
+  .tx-header__inner .tx-icon-btn {
+    margin-left: auto;
+  }
+
+  .tx-nav {
+    order: 3;
+    flex-wrap: nowrap;
+    width: 100%;
+    margin-left: 0;
+    padding: 4px 3px 6px;
+    overflow-x: auto;
+    scrollbar-width: none;
+  }
+
+  .tx-nav a {
+    flex: none;
+  }
+}
+
 .tx-subnav {
   border-bottom: var(--tx-border-width) solid var(--tx-border);
   background: var(--tx-surface);
@@ -562,6 +591,27 @@
   font-style: italic;
 }
 
+/* Wide images span the column; tall ones are capped at most of the viewport and centered. */
+.tx-prose img {
+  display: block;
+  width: auto;
+  max-width: 100%;
+  height: auto;
+  max-height: min(80vh, 900px);
+  margin: 1.6em auto;
+  border: var(--tx-border-width) solid var(--tx-border);
+  box-shadow: var(--tx-shadow);
+}
+
+/* Section break: a short accent marker bar, centered. */
+.tx-prose hr {
+  width: 96px;
+  height: 0;
+  margin: 2.6em auto;
+  border: 0;
+  border-top: 6px solid var(--tx-accent);
+}
+
 .tx-dropcap::first-letter,
 .tx-prose--dropcap > p:first-of-type::first-letter {
   float: left;
@@ -870,9 +920,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/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.0",
+  "version": "0.1.2",
   "description": "Shared design system, components, and tooling for every toyonix static site.",
   "license": "MIT",
   "author": "ToYoNiX",