@unpunnyfuns/swatchbook-blocks 0.64.0 → 0.65.0

package/dist/index.d.mts

@@ -99,11 +99,14 @@ interface ProjectSnapshot {
   /** The default tuple — `{ axis: axis.default }` for every axis. */
   defaultTuple: Record<string, string>;
   /**
-   * Pre-built `resolveAt(tuple)` accessor. The addon's preview
-   * decorator instantiates this once per iframe lifetime, backed by
-   * `resolveAllAt` over the stable `tokenGraph` export. Hand-built
-   * snapshots (tests, MDX) can omit this; blocks fall back to
-   * building a graph-backed resolver from `tokenGraph`.
+   * Pre-built `resolveAt(tuple)` accessor. The addon's preview decorator
+   * instantiates this once per iframe lifetime. When present, use-project
+   * prefers it over building its own from `tokenGraph`, so it MUST preserve
+   * alias provenance — back it with `resolveAllWithProvenanceAt`, not the raw
+   * leaf `resolveAllAt`, or axis-varying aliases silently lose their chain /
+   * reverse refs / description at non-default tuples. Hand-built snapshots
+   * (tests, MDX) can omit this; blocks then fall back to a provenance-aware
+   * graph-backed resolver built from `tokenGraph`.
    */
   resolveAt?: (tuple: Record<string, string>) => Record<string, VirtualTokenShape>;
 }
@@ -765,6 +768,18 @@ declare function TokenUsageSnippet({
   path
 }: TokenUsageSnippetProps): ReactElement | null;
 //#endregion
+//#region src/indicators/resolve.d.ts
+/** The individually-toggleable indicators in the row strip. `alias` covers the whole alias unit (forward chain + reverse count). */
+type IndicatorName = 'alias' | 'variance' | 'gamut' | 'deprecation' | 'description';
+/**
+ * Consumer-facing indicator config for the strip-hosting blocks:
+ * - `true` — every indicator on (including the opt-in `description`)
+ * - `false` — every indicator off
+ * - object — per-key override layered over the defaults
+ * - omitted — the defaults
+ */
+type IndicatorsProp = boolean | Partial<Record<IndicatorName, boolean>>;
+//#endregion
 //#region src/TokenNavigator.d.ts
 interface TokenNavigatorProps {
   /** If provided, mount at this dot-path subtree and hide everything outside it. */
@@ -805,6 +820,8 @@ interface TokenNavigatorProps {
    * props otherwise.
    */
   id?: string;
+  /** Configure the per-row indicator strip. See `IndicatorsProp`. */
+  indicators?: IndicatorsProp;
 }
 declare function TokenNavigator({
   root,
@@ -812,7 +829,8 @@ declare function TokenNavigator({
   initiallyExpanded,
   searchable,
   onSelect,
-  id
+  id,
+  indicators
 }: TokenNavigatorProps): ReactElement;
 //#endregion
 //#region src/TokenTable.d.ts
@@ -855,6 +873,8 @@ interface TokenTableProps {
   onSelect?(path: string): void;
   /** Disambiguates persisted UI state for two identical-prop tables on a page. */
   id?: string;
+  /** Configure the per-row indicator strip. See `IndicatorsProp`. */
+  indicators?: IndicatorsProp;
 }
 declare function TokenTable({
   filter,
@@ -864,7 +884,8 @@ declare function TokenTable({
   sortDir,
   searchable,
   onSelect,
-  id
+  id,
+  indicators
 }: TokenTableProps): ReactElement;
 //#endregion
 //#region src/TypographyScale.d.ts

package/dist/index.mjs

@@ -3640,6 +3640,38 @@ function isInView(path, ctx) {
 	return true;
 }
 //#endregion
+//#region src/indicators/resolve.ts
+/** Established-on set; `description` is opt-in. */
+const DEFAULT_INDICATORS = {
+	alias: true,
+	variance: true,
+	gamut: true,
+	deprecation: true,
+	description: false
+};
+/** Normalize an `IndicatorsProp` into a full enabled-map by layering over the defaults. */
+function resolveIndicators(prop) {
+	if (prop === void 0) return { ...DEFAULT_INDICATORS };
+	if (prop === true) return {
+		alias: true,
+		variance: true,
+		gamut: true,
+		deprecation: true,
+		description: true
+	};
+	if (prop === false) return {
+		alias: false,
+		variance: false,
+		gamut: false,
+		deprecation: false,
+		description: false
+	};
+	return {
+		...DEFAULT_INDICATORS,
+		...prop
+	};
+}
+//#endregion
 //#region src/indicators/RowIndicators.tsx
 function relativeLabel(path, root) {
 	if (root && path.startsWith(`${root}.`)) return path.slice(root.length + 1);
@@ -3788,34 +3820,49 @@ function ReverseCount({ referents, canReference, onReferenceClick }) {
 /** Per-row indicator strip: alias references, variance, gamut, deprecation. */
 function RowIndicators(props) {
 	const { token, root, variance, colorFormat, canReference, onReferenceClick } = props;
+	const en = props.enabled ?? resolveIndicators(void 0);
 	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;
+	const description = typeof token.$description === "string" && token.$description.length > 0 ? token.$description : void 0;
+	const showDeprecated = en.deprecation && isDeprecated;
+	const showForward = en.alias && aliasChain !== void 0;
+	const showReverse = en.alias && reverseCount > 0;
+	const showVariance = en.variance && isVarying;
+	const showGamut = en.gamut && outOfGamut;
+	const showDescription = en.description && description !== void 0;
+	if (!showDeprecated && !showForward && !showReverse && !showVariance && !showGamut && !showDescription) return null;
 	return /* @__PURE__ */ jsxs("span", {
 		className: "sb-indicator__indicators",
 		children: [
-			isDeprecated && deprecated !== void 0 && /* @__PURE__ */ jsx(DeprecatedBadge, { deprecated }),
-			aliasChain && /* @__PURE__ */ jsx(ForwardChain, {
+			showDeprecated && deprecated !== void 0 && /* @__PURE__ */ jsx(DeprecatedBadge, { deprecated }),
+			showForward && aliasChain && /* @__PURE__ */ jsx(ForwardChain, {
 				chain: aliasChain,
 				root,
 				canReference,
 				onReferenceClick
 			}),
-			reverseCount > 0 && token.aliasedBy && /* @__PURE__ */ jsx(ReverseCount, {
+			showReverse && token.aliasedBy && /* @__PURE__ */ jsx(ReverseCount, {
 				referents: token.aliasedBy,
 				canReference,
 				onReferenceClick
 			}),
-			variance && /* @__PURE__ */ jsx(VarianceBadge, { variance }),
-			outOfGamut && /* @__PURE__ */ jsx("span", {
+			showVariance && variance && /* @__PURE__ */ jsx(VarianceBadge, { variance }),
+			showGamut && /* @__PURE__ */ jsx("span", {
 				className: "sb-indicator__gamut",
 				title: "Out of sRGB gamut for this format",
 				"aria-label": "out of gamut",
 				children: "⚠"
+			}),
+			showDescription && description !== void 0 && /* @__PURE__ */ jsx("span", {
+				className: "sb-indicator__description",
+				"data-testid": "row-indicator-description",
+				title: description,
+				"aria-label": `description: ${description}`,
+				children: "ⓘ"
 			})
 		]
 	});
@@ -3924,7 +3971,7 @@ function pruneTreeForMatches(nodes, matches, expandOut) {
 	}
 	return out;
 }
-function TokenNavigator({ root, type, initiallyExpanded = 1, searchable = true, onSelect, id }) {
+function TokenNavigator({ root, type, initiallyExpanded = 1, searchable = true, onSelect, id, indicators }) {
 	const { resolved, activeTheme, activeAxes, cssVarPrefix } = useProject();
 	const blockKey = useBlockKey("TokenNavigator", [
 		root,
@@ -3935,6 +3982,7 @@ function TokenNavigator({ root, type, initiallyExpanded = 1, searchable = true,
 		if (type === void 0) return void 0;
 		return new Set(Array.isArray(type) ? type : [type]);
 	}, [type]);
+	const enabledIndicators = useMemo(() => resolveIndicators(indicators), [indicators]);
 	const tree = useMemo(() => buildTree(resolved, root, typeFilter), [
 		resolved,
 		root,
@@ -4206,6 +4254,7 @@ function TokenNavigator({ root, type, initiallyExpanded = 1, searchable = true,
 					root,
 					resolveInView,
 					onNavigate: navigateTo,
+					enabled: enabledIndicators,
 					level: 1,
 					setsize: visibleTree.length,
 					posinset: i + 1
@@ -4219,7 +4268,7 @@ function TokenNavigator({ root, type, initiallyExpanded = 1, searchable = true,
 		]
 	});
 }
-function TreeNodeRow({ node, expanded, focusedPath, registerTreeItem, onToggle, onFocusPath, onLeafClick, root, resolveInView, onNavigate, level, setsize, posinset }) {
+function TreeNodeRow({ node, expanded, focusedPath, registerTreeItem, onToggle, onFocusPath, onLeafClick, root, resolveInView, onNavigate, enabled, level, setsize, posinset }) {
 	if (node.kind === "leaf") return /* @__PURE__ */ jsx(LeafRow, {
 		node,
 		isFocused: focusedPath === node.path,
@@ -4229,6 +4278,7 @@ function TreeNodeRow({ node, expanded, focusedPath, registerTreeItem, onToggle,
 		root,
 		resolveInView,
 		onNavigate,
+		enabled,
 		level,
 		setsize,
 		posinset
@@ -4279,6 +4329,7 @@ function TreeNodeRow({ node, expanded, focusedPath, registerTreeItem, onToggle,
 				root,
 				resolveInView,
 				onNavigate,
+				enabled,
 				level: level + 1,
 				setsize: node.children.length,
 				posinset: i + 1
@@ -4286,7 +4337,7 @@ function TreeNodeRow({ node, expanded, focusedPath, registerTreeItem, onToggle,
 		})]
 	});
 }
-const LeafRow = memo(function LeafRow({ node, isFocused, registerTreeItem, onFocusPath, onLeafClick, root, resolveInView, onNavigate, level, setsize, posinset }) {
+const LeafRow = memo(function LeafRow({ node, isFocused, registerTreeItem, onFocusPath, onLeafClick, root, resolveInView, onNavigate, enabled, level, setsize, posinset }) {
 	const type = node.token.$type ?? "";
 	const project = useProject();
 	const colorFormat = useColorFormat();
@@ -4306,7 +4357,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,
+			"data-deprecated": enabled.deprecation && isDeprecated ? "true" : void 0,
 			onClick: () => {
 				onFocusPath(node.path);
 				onLeafClick(node.path);
@@ -4332,7 +4383,8 @@ const LeafRow = memo(function LeafRow({ node, isFocused, registerTreeItem, onFoc
 					variance,
 					colorFormat,
 					canReference: resolveInView,
-					onReferenceClick: onNavigate
+					onReferenceClick: onNavigate,
+					enabled
 				}),
 				/* @__PURE__ */ jsx(LeafPreview, {
 					path: node.path,
@@ -4404,7 +4456,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 }) {
+function TokenTable({ filter, type, caption, sortBy = "path", sortDir = "asc", searchable = true, onSelect, id, indicators }) {
 	const { resolved, activeTheme, activeAxes, cssVarPrefix, listing, varianceByPath } = useProject();
 	const colorFormat = useColorFormat();
 	const blockKey = useBlockKey("TokenTable", [
@@ -4413,6 +4465,7 @@ function TokenTable({ filter, type, caption, sortBy = "path", sortDir = "asc", s
 		caption,
 		id
 	]);
+	const enabledIndicators = useMemo(() => resolveIndicators(indicators), [indicators]);
 	const [selectedPath, setSelectedPath] = usePersistedState(`${blockKey}::selected`, null);
 	const [query, setQuery] = usePersistedState(`${blockKey}::query`, "");
 	const deferredQuery = useDeferredValue(query);
@@ -4545,7 +4598,7 @@ function TokenTable({ filter, type, caption, sortBy = "path", sortDir = "asc", s
 							children: [
 								/* @__PURE__ */ jsx("td", {
 									className: cx("sb-token-table__td", "sb-token-table__path"),
-									"data-deprecated": isDeprecated ? "true" : void 0,
+									"data-deprecated": enabledIndicators.deprecation && isDeprecated ? "true" : void 0,
 									children: row.path
 								}),
 								/* @__PURE__ */ jsx("td", {
@@ -4597,7 +4650,8 @@ function TokenTable({ filter, type, caption, sortBy = "path", sortDir = "asc", s
 										variance: varianceByPath[row.path],
 										colorFormat,
 										canReference: (p) => p in resolved,
-										onReferenceClick: (p) => setSelectedPath(p)
+										onReferenceClick: (p) => setSelectedPath(p),
+										enabled: enabledIndicators
 									})
 								})
 							]