@unpunnyfuns/swatchbook-blocks 0.62.4 → 0.64.0

package/dist/index.d.mts

@@ -29,6 +29,12 @@ interface VirtualTokenShape {
   $type?: string | undefined;
   $value?: unknown;
   $description?: string | undefined;
+  /**
+   * DTCG `$deprecated` — `true` or a message string. Mirrors core's
+   * `SwatchbookToken.$deprecated`; reaches blocks via the resolved token
+   * map reconstructed from the wire `tokenGraph`.
+   */
+  $deprecated?: string | boolean | undefined;
   aliasOf?: string | undefined;
   aliasChain?: readonly string[] | undefined;
   aliasedBy?: readonly string[] | undefined;

package/dist/index.mjs

@@ -3,7 +3,7 @@ import { COLOR_FORMATS } from "@unpunnyfuns/swatchbook-core/color-formats";
 import { formatColor, parseColor } from "@unpunnyfuns/swatchbook-core/format-color";
 import { createContext, memo, useCallback, useContext, useDeferredValue, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
-import { getVariance, listPaths, resolveAllAt } from "@unpunnyfuns/swatchbook-core/graph";
+import { getVariance, listPaths, resolveAllWithProvenanceAt } from "@unpunnyfuns/swatchbook-core/graph";
 import { makeCssVar } from "@unpunnyfuns/swatchbook-core/css-var";
 import { SWATCHBOOK_STYLE_ELEMENT_ID, ensureStyleElement } from "@unpunnyfuns/swatchbook-core/style-element";
 import { tupleToName } from "@unpunnyfuns/swatchbook-core/themes";
@@ -244,7 +244,7 @@ function defaultTuple(axes) {
 }
 function makeResolveAt(graph) {
 	if (!graph) return () => ({});
-	return (tuple) => resolveAllAt(graph, tuple);
+	return (tuple) => resolveAllWithProvenanceAt(graph, tuple);
 }
 function snapshotResolveAt(snapshot) {
 	if (snapshot.resolveAt) return snapshot.resolveAt;
@@ -3455,6 +3455,8 @@ function TokenDetail({ path, heading }) {
 	const gamut = isColor ? formatColor(token.$value, colorFormat) : null;
 	const value = formatTokenValue(token.$value, token.$type, colorFormat, listing[path]);
 	const outOfGamut = gamut?.outOfGamut ?? false;
+	const dep = token.$deprecated;
+	const isDeprecated = dep === true || typeof dep === "string" && dep.length > 0;
 	return /* @__PURE__ */ jsxs("div", {
 		...wrapperAttrs,
 		className: cx(wrapperAttrs["className"], "sb-token-detail"),
@@ -3463,6 +3465,19 @@ function TokenDetail({ path, heading }) {
 				path,
 				...heading !== void 0 && { heading }
 			}),
+			isDeprecated && /* @__PURE__ */ jsxs("div", {
+				className: "sb-token-detail__deprecated",
+				"data-testid": "token-detail-deprecated",
+				role: "note",
+				children: [
+					/* @__PURE__ */ jsx("span", {
+						"aria-hidden": true,
+						children: "⚠ "
+					}),
+					"Deprecated",
+					typeof dep === "string" ? `: ${dep}` : ""
+				]
+			}),
 			/* @__PURE__ */ jsxs("div", {
 				className: "sb-token-detail__section-header",
 				children: ["Resolved value · ", activeTheme]
@@ -3593,6 +3608,219 @@ function findBodyChildContaining(node) {
 	return cursor;
 }
 //#endregion
+//#region src/token-navigator/navigate.ts
+/**
+* The group paths to expand so `path` becomes visible in the tree — the
+* cumulative dotted prefixes of `path`, excluding `path` itself and any
+* prefix at or above `root` (the navigator's implicit root container is not
+* a group node). Matches `buildTree`'s full-dotted group-path scheme.
+*/
+function ancestorGroupPaths(path, root) {
+	const segments = path.split(".");
+	const out = [];
+	for (let i = 1; i < segments.length; i += 1) {
+		const prefix = segments.slice(0, i).join(".");
+		if (root && !prefix.startsWith(`${root}.`)) continue;
+		out.push(prefix);
+	}
+	return out;
+}
+/**
+* Whether `path` survives the navigator's structural (`root` / `type`)
+* filters and exists in the resolved map — i.e. it can be selected in the
+* current tree. Transient search is NOT considered here: a target hidden
+* only by an active query is still "in view" once the query is cleared,
+* which the caller handles.
+*/
+function isInView(path, ctx) {
+	const token = ctx.resolved[path];
+	if (!token) return false;
+	if (ctx.root && !(path === ctx.root || path.startsWith(`${ctx.root}.`))) return false;
+	if (ctx.typeFilter && !(token.$type !== void 0 && ctx.typeFilter.has(token.$type))) return false;
+	return true;
+}
+//#endregion
+//#region src/indicators/RowIndicators.tsx
+function relativeLabel(path, root) {
+	if (root && path.startsWith(`${root}.`)) return path.slice(root.length + 1);
+	return path;
+}
+/**
+* The forward alias chain for one row. Full chain in `aria-label`; visually
+* capped to first … last beyond two hops (no width measurement). Each shown
+* node navigates when in view, else renders as plain text.
+*/
+function ForwardChain({ chain, root, canReference, onReferenceClick }) {
+	const full = chain.map((p) => relativeLabel(p, root)).join(" → ");
+	const capped = chain.length > 2;
+	const shown = capped ? [chain[0], chain[chain.length - 1]] : [...chain];
+	return /* @__PURE__ */ jsxs("span", {
+		className: "sb-indicator__alias-forward",
+		"data-testid": "row-indicator-alias-forward",
+		"aria-label": `aliases ${full}`,
+		children: [/* @__PURE__ */ jsx("span", {
+			className: "sb-indicator__alias-arrow",
+			"aria-hidden": true,
+			children: "→"
+		}), shown.map((target, i) => {
+			const label = relativeLabel(target, root);
+			return /* @__PURE__ */ jsxs("span", { children: [canReference(target) ? /* @__PURE__ */ jsx("button", {
+				type: "button",
+				className: "sb-indicator__alias-node",
+				"data-testid": "alias-node",
+				"aria-label": target,
+				onClick: (e) => {
+					e.stopPropagation();
+					onReferenceClick(target);
+				},
+				children: label
+			}) : /* @__PURE__ */ jsx("span", {
+				className: "sb-indicator__alias-node sb-indicator__alias-node--offview",
+				"data-testid": "alias-node",
+				title: "outside current view",
+				children: label
+			}), capped && i === 0 ? /* @__PURE__ */ jsxs("span", {
+				className: "sb-indicator__alias-arrow",
+				"aria-hidden": true,
+				children: [
+					" ",
+					"→ … →",
+					" "
+				]
+			}) : i < shown.length - 1 ? /* @__PURE__ */ jsxs("span", {
+				className: "sb-indicator__alias-arrow",
+				"aria-hidden": true,
+				children: [
+					" ",
+					"→",
+					" "
+				]
+			}) : null] }, target);
+		})]
+	});
+}
+function DeprecatedBadge({ deprecated }) {
+	const label = typeof deprecated === "string" ? `deprecated: ${deprecated}` : "deprecated";
+	return /* @__PURE__ */ jsx("span", {
+		className: "sb-indicator__deprecated",
+		"data-testid": "row-indicator-deprecated",
+		title: label,
+		"aria-label": label,
+		children: "deprecated"
+	});
+}
+function VarianceBadge({ variance }) {
+	if (variance.kind === "constant") return null;
+	const axes = variance.varyingAxes;
+	const label = variance.kind === "single" ? variance.axis : `${axes.length} axes`;
+	return /* @__PURE__ */ jsxs("span", {
+		className: "sb-indicator__variance",
+		"data-testid": "row-indicator-variance",
+		"aria-label": `varies by ${axes.join(", ")}`,
+		children: [/* @__PURE__ */ jsx("span", {
+			className: "sb-indicator__variance-glyph",
+			"aria-hidden": true,
+			children: "⊹"
+		}), label]
+	});
+}
+function ReverseCount({ referents, canReference, onReferenceClick }) {
+	const [open, setOpen] = useState(false);
+	const wrapRef = useRef(null);
+	const count = referents.length;
+	const single = count === 1;
+	useEffect(() => {
+		if (single || !open) return;
+		(wrapRef.current?.querySelector("button[role=\"menuitem\"]:not(:disabled)"))?.focus();
+		const handlePointerDown = (e) => {
+			if (wrapRef.current && !wrapRef.current.contains(e.target)) setOpen(false);
+		};
+		document.addEventListener("pointerdown", handlePointerDown);
+		return () => {
+			document.removeEventListener("pointerdown", handlePointerDown);
+		};
+	}, [open, single]);
+	return /* @__PURE__ */ jsxs("span", {
+		ref: wrapRef,
+		className: "sb-indicator__reverse-wrap",
+		onKeyDown: (e) => {
+			if (e.key === "Escape") setOpen(false);
+		},
+		children: [/* @__PURE__ */ jsxs("button", {
+			type: "button",
+			className: "sb-indicator__alias-reverse",
+			"data-testid": "row-indicator-alias-reverse",
+			"aria-label": `referenced by ${count} ${count === 1 ? "token" : "tokens"}`,
+			"aria-haspopup": single ? void 0 : "menu",
+			"aria-expanded": single ? void 0 : open,
+			onClick: (e) => {
+				e.stopPropagation();
+				if (single) onReferenceClick(referents[0]);
+				else setOpen((v) => !v);
+			},
+			children: [/* @__PURE__ */ jsx("span", {
+				className: "sb-indicator__alias-arrow",
+				"aria-hidden": true,
+				children: "←"
+			}), count]
+		}), !single && open && /* @__PURE__ */ jsx("ul", {
+			className: "sb-indicator__reverse-menu",
+			role: "menu",
+			children: referents.map((ref) => /* @__PURE__ */ jsx("li", {
+				role: "none",
+				children: /* @__PURE__ */ jsx("button", {
+					type: "button",
+					role: "menuitem",
+					className: "sb-indicator__reverse-item",
+					disabled: !canReference(ref),
+					title: canReference(ref) ? void 0 : "outside current view",
+					onClick: (e) => {
+						e.stopPropagation();
+						setOpen(false);
+						onReferenceClick(ref);
+					},
+					children: ref
+				})
+			}, ref))
+		})]
+	});
+}
+/** Per-row indicator strip: alias references, variance, gamut, deprecation. */
+function RowIndicators(props) {
+	const { token, root, variance, colorFormat, canReference, onReferenceClick } = props;
+	const aliasChain = Array.isArray(token.aliasChain) && token.aliasChain.length > 0 ? token.aliasChain : void 0;
+	const reverseCount = Array.isArray(token.aliasedBy) && token.aliasedBy.length > 0 ? token.aliasedBy.length : 0;
+	const isVarying = variance !== void 0 && variance.kind !== "constant";
+	const outOfGamut = token.$type === "color" && (formatColor(token.$value, colorFormat)?.outOfGamut ?? false);
+	const deprecated = token.$deprecated;
+	const isDeprecated = deprecated === true || typeof deprecated === "string" && deprecated.length > 0;
+	if (!aliasChain && reverseCount === 0 && !isVarying && !outOfGamut && !isDeprecated) return null;
+	return /* @__PURE__ */ jsxs("span", {
+		className: "sb-indicator__indicators",
+		children: [
+			isDeprecated && deprecated !== void 0 && /* @__PURE__ */ jsx(DeprecatedBadge, { deprecated }),
+			aliasChain && /* @__PURE__ */ jsx(ForwardChain, {
+				chain: aliasChain,
+				root,
+				canReference,
+				onReferenceClick
+			}),
+			reverseCount > 0 && token.aliasedBy && /* @__PURE__ */ jsx(ReverseCount, {
+				referents: token.aliasedBy,
+				canReference,
+				onReferenceClick
+			}),
+			variance && /* @__PURE__ */ jsx(VarianceBadge, { variance }),
+			outOfGamut && /* @__PURE__ */ jsx("span", {
+				className: "sb-indicator__gamut",
+				title: "Out of sRGB gamut for this format",
+				"aria-label": "out of gamut",
+				children: "⚠"
+			})
+		]
+	});
+}
+//#endregion
 //#region src/TokenNavigator.tsx
 function buildTree(resolved, root, typeFilter) {
 	const rootPrefix = root && root.length > 0 ? `${root}.` : "";
@@ -3769,6 +3997,37 @@ function TokenNavigator({ root, type, initiallyExpanded = 1, searchable = true,
 	}, [onSelect, setSelectedPath]);
 	const [storedFocus, setStoredFocus] = useState(null);
 	const treeItemRefs = useRef(/* @__PURE__ */ new Map());
+	const resolveInView = useCallback((path) => isInView(path, {
+		resolved,
+		root,
+		typeFilter
+	}), [
+		resolved,
+		root,
+		typeFilter
+	]);
+	const navigateTo = useCallback((target) => {
+		setQuery("");
+		setExpanded((prev) => {
+			const next = new Set(prev);
+			for (const p of ancestorGroupPaths(target, root)) next.add(p);
+			return next;
+		});
+		if (onSelect) onSelect(target);
+		else setSelectedPath(target);
+		setStoredFocus(target);
+		requestAnimationFrame(() => {
+			const el = treeItemRefs.current.get(target);
+			el?.scrollIntoView({ block: "nearest" });
+			el?.focus();
+		});
+	}, [
+		root,
+		onSelect,
+		setQuery,
+		setExpanded,
+		setSelectedPath
+	]);
 	const registerTreeItem = useCallback((path) => (el) => {
 		if (el) treeItemRefs.current.set(path, el);
 		else treeItemRefs.current.delete(path);
@@ -3944,6 +4203,9 @@ function TokenNavigator({ root, type, initiallyExpanded = 1, searchable = true,
 					onToggle: toggle,
 					onFocusPath: setStoredFocus,
 					onLeafClick: handleLeafClick,
+					root,
+					resolveInView,
+					onNavigate: navigateTo,
 					level: 1,
 					setsize: visibleTree.length,
 					posinset: i + 1
@@ -3957,13 +4219,16 @@ function TokenNavigator({ root, type, initiallyExpanded = 1, searchable = true,
 		]
 	});
 }
-function TreeNodeRow({ node, expanded, focusedPath, registerTreeItem, onToggle, onFocusPath, onLeafClick, level, setsize, posinset }) {
+function TreeNodeRow({ node, expanded, focusedPath, registerTreeItem, onToggle, onFocusPath, onLeafClick, root, resolveInView, onNavigate, level, setsize, posinset }) {
 	if (node.kind === "leaf") return /* @__PURE__ */ jsx(LeafRow, {
 		node,
 		isFocused: focusedPath === node.path,
 		registerTreeItem,
 		onFocusPath,
 		onLeafClick,
+		root,
+		resolveInView,
+		onNavigate,
 		level,
 		setsize,
 		posinset
@@ -4011,6 +4276,9 @@ function TreeNodeRow({ node, expanded, focusedPath, registerTreeItem, onToggle,
 				onToggle,
 				onFocusPath,
 				onLeafClick,
+				root,
+				resolveInView,
+				onNavigate,
 				level: level + 1,
 				setsize: node.children.length,
 				posinset: i + 1
@@ -4018,8 +4286,13 @@ function TreeNodeRow({ node, expanded, focusedPath, registerTreeItem, onToggle,
 		})]
 	});
 }
-const LeafRow = memo(function LeafRow({ node, isFocused, registerTreeItem, onFocusPath, onLeafClick, level, setsize, posinset }) {
+const LeafRow = memo(function LeafRow({ node, isFocused, registerTreeItem, onFocusPath, onLeafClick, root, resolveInView, onNavigate, level, setsize, posinset }) {
 	const type = node.token.$type ?? "";
+	const project = useProject();
+	const colorFormat = useColorFormat();
+	const variance = project.varianceByPath[node.path];
+	const dep = node.token.$deprecated;
+	const isDeprecated = dep === true || typeof dep === "string" && dep.length > 0;
 	return /* @__PURE__ */ jsx("li", {
 		ref: registerTreeItem(node.path),
 		role: "treeitem",
@@ -4033,6 +4306,7 @@ const LeafRow = memo(function LeafRow({ node, isFocused, registerTreeItem, onFoc
 		children: /* @__PURE__ */ jsxs("div", {
 			className: "sb-token-navigator__leaf-row",
 			"data-testid": "token-navigator-leaf-row",
+			"data-deprecated": isDeprecated ? "true" : void 0,
 			onClick: () => {
 				onFocusPath(node.path);
 				onLeafClick(node.path);
@@ -4051,6 +4325,15 @@ const LeafRow = memo(function LeafRow({ node, isFocused, registerTreeItem, onFoc
 					className: "sb-token-navigator__type-pill",
 					children: type
 				}),
+				/* @__PURE__ */ jsx(RowIndicators, {
+					path: node.path,
+					token: node.token,
+					root,
+					variance,
+					colorFormat,
+					canReference: resolveInView,
+					onReferenceClick: onNavigate
+				}),
 				/* @__PURE__ */ jsx(LeafPreview, {
 					path: node.path,
 					token: node.token
@@ -4122,7 +4405,7 @@ const LeafPreview = memo(function LeafPreview({ path, token }) {
 //#endregion
 //#region src/TokenTable.tsx
 function TokenTable({ filter, type, caption, sortBy = "path", sortDir = "asc", searchable = true, onSelect, id }) {
-	const { resolved, activeTheme, activeAxes, cssVarPrefix, listing } = useProject();
+	const { resolved, activeTheme, activeAxes, cssVarPrefix, listing, varianceByPath } = useProject();
 	const colorFormat = useColorFormat();
 	const blockKey = useBlockKey("TokenTable", [
 		filter,
@@ -4216,79 +4499,110 @@ function TokenTable({ filter, type, caption, sortBy = "path", sortDir = "asc", s
 						className: "sb-token-table__caption",
 						children: captionText
 					}),
-					/* @__PURE__ */ jsx("thead", { children: /* @__PURE__ */ jsxs("tr", { children: [/* @__PURE__ */ jsx("th", {
-						className: cx("sb-token-table__th", "sb-token-table__th--path"),
-						children: "Path"
-					}), /* @__PURE__ */ jsx("th", {
-						className: cx("sb-token-table__th", "sb-token-table__th--value"),
-						children: "Value"
-					})] }) }),
+					/* @__PURE__ */ jsx("thead", { children: /* @__PURE__ */ jsxs("tr", { children: [
+						/* @__PURE__ */ jsx("th", {
+							className: cx("sb-token-table__th", "sb-token-table__th--path"),
+							children: "Path"
+						}),
+						/* @__PURE__ */ jsx("th", {
+							className: cx("sb-token-table__th", "sb-token-table__th--value"),
+							children: "Value"
+						}),
+						/* @__PURE__ */ jsx("th", {
+							className: "sb-token-table__th sb-token-table__th--refs",
+							children: /* @__PURE__ */ jsx("span", {
+								className: "sb-token-table__sr-status",
+								children: "References and status"
+							})
+						})
+					] }) }),
 					/* @__PURE__ */ jsxs("tbody", { children: [visibleRows.length === 0 && /* @__PURE__ */ jsx("tr", { children: /* @__PURE__ */ jsxs("td", {
-						colSpan: 2,
+						colSpan: 3,
 						className: "sb-token-table__td sb-token-table__empty-row",
 						children: [
 							"No tokens match \"",
 							query.trim(),
 							"\"."
 						]
-					}) }), visibleRows.map((row) => /* @__PURE__ */ jsxs("tr", {
-						className: "sb-token-table__row",
-						onClick: () => handleRowClick(row.path),
-						onKeyDown: (e) => {
-							if (e.key === "Enter" || e.key === " ") {
-								e.preventDefault();
-								handleRowClick(row.path);
-							}
-						},
-						tabIndex: 0,
-						"aria-haspopup": "dialog",
-						"aria-label": `Inspect ${row.path}`,
-						"data-testid": "token-table-row",
-						"data-path": row.path,
-						children: [/* @__PURE__ */ jsx("td", {
-							className: cx("sb-token-table__td", "sb-token-table__path"),
-							children: row.path
-						}), /* @__PURE__ */ jsx("td", {
-							className: "sb-token-table__td",
-							children: /* @__PURE__ */ jsxs("span", {
-								className: "sb-token-table__value-cell",
-								children: [
-									row.type && /* @__PURE__ */ jsx("span", {
-										className: "sb-token-table__type-pill",
-										children: row.type
-									}),
-									row.isColor && /* @__PURE__ */ jsx("span", {
-										className: "sb-token-table__swatch",
-										style: { background: row.cssVar },
-										"aria-hidden": true
-									}),
-									/* @__PURE__ */ jsx("span", {
-										className: "sb-token-table__value-text",
-										title: row.value,
-										"data-testid": "token-table-value",
-										children: row.value
-									}),
-									row.outOfGamut && /* @__PURE__ */ jsx("span", {
-										title: "Out of sRGB gamut for this format",
-										"aria-label": "out of gamut",
-										className: "sb-token-table__gamut-warn",
-										children: "⚠"
-									}),
-									/* @__PURE__ */ jsx("span", {
-										className: "sb-token-table__copy-wrap",
-										onClick: (e) => e.stopPropagation(),
-										onKeyDown: (e) => e.stopPropagation(),
-										role: "presentation",
-										children: /* @__PURE__ */ jsx(CopyButton$1, {
-											value: row.value,
-											label: `Copy value ${row.value}`,
-											className: "sb-token-table__copy"
-										})
+					}) }), visibleRows.map((row) => {
+						const token = resolved[row.path];
+						const dep = token?.$deprecated;
+						const isDeprecated = dep === true || typeof dep === "string" && dep.length > 0;
+						return /* @__PURE__ */ jsxs("tr", {
+							className: "sb-token-table__row",
+							onClick: () => handleRowClick(row.path),
+							onKeyDown: (e) => {
+								if (e.key === "Enter" || e.key === " ") {
+									e.preventDefault();
+									handleRowClick(row.path);
+								}
+							},
+							tabIndex: 0,
+							"aria-haspopup": "dialog",
+							"aria-label": `Inspect ${row.path}`,
+							"data-testid": "token-table-row",
+							"data-path": row.path,
+							children: [
+								/* @__PURE__ */ jsx("td", {
+									className: cx("sb-token-table__td", "sb-token-table__path"),
+									"data-deprecated": isDeprecated ? "true" : void 0,
+									children: row.path
+								}),
+								/* @__PURE__ */ jsx("td", {
+									className: "sb-token-table__td",
+									children: /* @__PURE__ */ jsxs("span", {
+										className: "sb-token-table__value-cell",
+										children: [
+											row.type && /* @__PURE__ */ jsx("span", {
+												className: "sb-token-table__type-pill",
+												children: row.type
+											}),
+											row.isColor && /* @__PURE__ */ jsx("span", {
+												className: "sb-token-table__swatch",
+												style: { background: row.cssVar },
+												"aria-hidden": true
+											}),
+											/* @__PURE__ */ jsx("span", {
+												className: "sb-token-table__value-text",
+												title: row.value,
+												"data-testid": "token-table-value",
+												children: row.value
+											}),
+											row.outOfGamut && /* @__PURE__ */ jsx("span", {
+												title: "Out of sRGB gamut for this format",
+												"aria-label": "out of gamut",
+												className: "sb-token-table__gamut-warn",
+												children: "⚠"
+											}),
+											/* @__PURE__ */ jsx("span", {
+												className: "sb-token-table__copy-wrap",
+												onClick: (e) => e.stopPropagation(),
+												onKeyDown: (e) => e.stopPropagation(),
+												role: "presentation",
+												children: /* @__PURE__ */ jsx(CopyButton$1, {
+													value: row.value,
+													label: `Copy value ${row.value}`,
+													className: "sb-token-table__copy"
+												})
+											})
+										]
 									})
-								]
-							})
-						})]
-					}, row.path))] })
+								}),
+								/* @__PURE__ */ jsx("td", {
+									className: "sb-token-table__td sb-token-table__refs",
+									children: token && /* @__PURE__ */ jsx(RowIndicators, {
+										path: row.path,
+										token,
+										root: void 0,
+										variance: varianceByPath[row.path],
+										colorFormat,
+										canReference: (p) => p in resolved,
+										onReferenceClick: (p) => setSelectedPath(p)
+									})
+								})
+							]
+						}, row.path);
+					})] })
 				]
 			}),
 			selectedPath !== null && /* @__PURE__ */ jsx(DetailOverlay, {