@mitcsutt/kiln-ui 0.4.0 → 0.6.0

package/dist/components/display/CodeBlock/CodeBlock.d.ts

@@ -1,9 +1,25 @@
 import { type HTMLAttributes, type ReactNode } from 'react';
+/**
+ * What a piece of highlighted source is. Each kind is coloured from the theme's own tokens, so
+ * highlighted code follows the theme and the colour mode.
+ */
+export type CodeTokenType = 'keyword' | 'string' | 'comment' | 'constant' | 'function' | 'type' | 'tag' | 'attribute' | 'punctuation';
+/** A run of source text and its kind. A token with no `type` is plain text. */
+export interface CodeToken {
+    content: string;
+    type?: CodeTokenType;
+}
 export interface CodeBlockProps extends Omit<HTMLAttributes<HTMLElement>, 'title'> {
     /** The source, verbatim. Trailing newlines are trimmed. */
     code: string;
-    /** Shown as a label ("TypeScript", "bash"). No syntax highlighting — the code is the design. */
+    /** Shown as a label ("TypeScript", "bash"). It doesn't turn on highlighting: `tokens` does. */
     language?: string;
+    /**
+     * Syntax highlighting for `code`: one array of tokens per line, as `highlight` from
+     * `@mitcsutt/kiln-ui/highlight` returns them. Without it, or when the tokens don't spell out
+     * `code` line for line (say, tokens from a previous `code`), the code is plain.
+     */
+    tokens?: CodeToken[][];
     /** Filename or caption shown in the header: `src/queries/keys.ts`. */
     title?: ReactNode;
     /** Number the lines in a gutter (not copied with a selection). */
@@ -23,8 +39,33 @@ export interface CodeBlockProps extends Omit<HTMLAttributes<HTMLElement>, 'title
  *
  * @remarks
  * `CodeBlock` shows code: a snippet in an article, a command, a config example. It's a plain
- * surface with an optional title bar, never fake window chrome, and it has no syntax highlighting:
- * the code is the design. Every code sample in these docs is a `CodeBlock`.
+ * surface with an optional title bar, never fake window chrome. It's plain unless you pass
+ * `tokens`: `highlight` from `@mitcsutt/kiln-ui/highlight` turns JavaScript, JSX, TypeScript and
+ * TSX into tokens, coloured from the theme. Every code sample in these docs is a `CodeBlock`.
+ *
+ * ## Highlighting
+ *
+ * `highlight(code, language)` resolves to the tokens for `code`, or to `undefined` for a language
+ * other than `js`, `jsx`, `ts` or `tsx` (or `javascript` and `typescript`), which `CodeBlock`
+ * shows as plain code. It runs [Shiki](https://shiki.style), an optional peer dependency, so
+ * install `shiki` to use it. The main `@mitcsutt/kiln-ui` entry never loads it.
+ *
+ * Keywords and tags take the accent, strings, constants, functions and types take the theme's
+ * tones, and comments and punctuation are muted. A custom theme needs no code palette of its own.
+ *
+ * The tokens are plain data, so highlight wherever the code is ready. In a server component or
+ * at build time, `await` it and pass the tokens to the client component that renders the
+ * `CodeBlock`, and the browser downloads no highlighter. In the browser, call it in an effect, as
+ * in the example above: Shiki and the grammar load on the first call.
+ *
+ * ```tsx
+ * import { highlight } from '@mitcsutt/kiln-ui/highlight'
+ *
+ * export async function Snippet({ source }: { source: string }) {
+ *   const tokens = await highlight(source, 'tsx')
+ *   return <SnippetBlock code={source} tokens={tokens} />
+ * }
+ * ```
  *
  * @privateRemarks
  * A block of source: a snippet in a blog post, a command in a README, a config example.

package/dist/components/display/CodeBlock/CodeBlock.js

@@ -1,85 +1,90 @@
 import { cx as e } from "../../../utils/cx.js";
 import { CheckIcon as t, CopyIcon as n } from "../../../icons/icons.js";
 import { Button as r } from "../../actions/Button/Button.js";
-import i from "./CodeBlock.module.js";
-import { forwardRef as a, useEffect as o, useId as s, useRef as c, useState as l } from "react";
-import { jsx as u, jsxs as d } from "react/jsx-runtime";
+import { trimTrailingNewlines as i } from "../../../utils/newlines.js";
+import a from "./CodeBlock.module.js";
+import { forwardRef as o, useEffect as s, useId as c, useRef as l, useState as u } from "react";
+import { jsx as d, jsxs as f } from "react/jsx-runtime";
 //#region src/components/display/CodeBlock/CodeBlock.tsx
-var f = a(function({ code: a, language: f, title: p, showLineNumbers: m = !1, highlightLines: h, copyable: g = !0, wrap: _ = !1, copyLabel: v = "Copy code", className: y, ...b }, x) {
-	let [S, C] = l("idle"), w = c(void 0), T = s(), E = a.replace(/\n+$/, ""), D = E.split("\n"), O = new Set(h), k = !!p || !!f || g;
-	o(() => () => {
-		clearTimeout(w.current);
+var p = o(function({ code: o, language: p, tokens: m, title: h, showLineNumbers: g = !1, highlightLines: _, copyable: v = !0, wrap: y = !1, copyLabel: b = "Copy code", className: x, ...S }, C) {
+	let [w, T] = u("idle"), E = l(void 0), D = c(), O = i(o), k = O.split("\n"), A = m?.length === k.length && m.every((e, t) => e.map((e) => e.content).join("") === k[t]) ? m : void 0, j = new Set(_), M = !!h || !!p || v;
+	s(() => () => {
+		clearTimeout(E.current);
 	}, []);
-	let A = async () => {
-		clearTimeout(w.current);
+	let N = async () => {
+		clearTimeout(E.current);
 		try {
-			await navigator.clipboard.writeText(E), C("copied");
+			await navigator.clipboard.writeText(O), T("copied");
 		} catch {
-			C("failed");
+			T("failed");
 		}
-		w.current = setTimeout(() => {
-			C("idle");
+		E.current = setTimeout(() => {
+			T("idle");
 		}, 2e3);
 	};
-	return /* @__PURE__ */ d("figure", {
-		ref: x,
-		className: e(i.codeBlock, y),
+	return /* @__PURE__ */ f("figure", {
+		ref: C,
+		className: e(a.codeBlock, x),
 		"data-kiln-component": "",
-		"data-wrap": _ || void 0,
-		"data-line-numbers": m || void 0,
-		"aria-labelledby": p ? T : void 0,
-		...b,
+		"data-wrap": y || void 0,
+		"data-line-numbers": g || void 0,
+		"aria-labelledby": h ? D : void 0,
+		...S,
 		children: [
-			k ? /* @__PURE__ */ d("figcaption", {
-				className: i.header,
+			M ? /* @__PURE__ */ f("figcaption", {
+				className: a.header,
 				children: [
-					p ? /* @__PURE__ */ u("span", {
-						id: T,
-						className: i.title,
-						children: p
+					h ? /* @__PURE__ */ d("span", {
+						id: D,
+						className: a.title,
+						children: h
 					}) : null,
-					f ? /* @__PURE__ */ u("span", {
-						className: i.language,
-						children: f
+					p ? /* @__PURE__ */ d("span", {
+						className: a.language,
+						children: p
 					}) : null,
-					g ? /* @__PURE__ */ u(r, {
+					v ? /* @__PURE__ */ d(r, {
 						variant: "ghost",
 						tone: "neutral",
 						size: "sm",
-						className: i.copy,
-						leadingIcon: u(S === "copied" ? t : n, {}),
-						"aria-label": v,
+						className: a.copy,
+						leadingIcon: d(w === "copied" ? t : n, {}),
+						"aria-label": b,
 						onClick: () => {
-							A();
+							N();
 						},
-						"data-state": S,
-						children: S === "copied" ? "Copied" : S === "failed" ? "Copy failed" : "Copy"
+						"data-state": w,
+						children: w === "copied" ? "Copied" : w === "failed" ? "Copy failed" : "Copy"
 					}) : null
 				]
 			}) : null,
-			/* @__PURE__ */ u("pre", {
-				className: i.pre,
+			/* @__PURE__ */ d("pre", {
+				className: a.pre,
 				tabIndex: 0,
-				children: /* @__PURE__ */ u("code", {
-					className: i.code,
-					children: D.map((e, t) => /* @__PURE__ */ d("span", {
-						className: i.line,
-						"data-line": m ? t + 1 : void 0,
-						"data-highlighted": O.has(t + 1) || void 0,
-						children: [e, t < D.length - 1 ? "\n" : null]
+				children: /* @__PURE__ */ d("code", {
+					className: a.code,
+					children: k.map((e, t) => /* @__PURE__ */ f("span", {
+						className: a.line,
+						"data-line": g ? t + 1 : void 0,
+						"data-highlighted": j.has(t + 1) || void 0,
+						children: [A?.[t] ? A[t].map((e, t) => e.type ? /* @__PURE__ */ d("span", {
+							className: a.token,
+							"data-token": e.type,
+							children: e.content
+						}, t) : e.content) : e, t < k.length - 1 ? "\n" : null]
 					}, t))
 				})
 			}),
-			g ? /* @__PURE__ */ u("span", {
-				className: i.visuallyHidden,
+			v ? /* @__PURE__ */ d("span", {
+				className: a.visuallyHidden,
 				role: "status",
 				"aria-live": "polite",
-				children: S === "copied" ? "Copied to clipboard" : S === "failed" ? "Copy failed" : ""
+				children: w === "copied" ? "Copied to clipboard" : w === "failed" ? "Copy failed" : ""
 			}) : null
 		]
 	});
 });
 //#endregion
-export { f as CodeBlock };
+export { p as CodeBlock };
 
 //# sourceMappingURL=CodeBlock.js.map

package/dist/components/display/CodeBlock/CodeBlock.js.map

@@ -1 +1 @@
-{"version":3,"file":"CodeBlock.js","names":["styles","CodeBlock_module_default","CodeBlock","forwardRef","rest","copy","setCopy","useState","timer","useRef","captionId","useId","source","code","lines","highlighted","highlightLines","hasHeader","title","language","copyable","onCopy","cx","className","wrap","showLineNumbers","Button","jsx","CheckIcon","CopyIcon","copyLabel","i","line"],"sources":["../../../../src/components/display/CodeBlock/CodeBlock.tsx"],"sourcesContent":["import {\n  forwardRef,\n  useEffect,\n  useId,\n  useRef,\n  useState,\n  type HTMLAttributes,\n  type ReactNode,\n} from 'react'\nimport { CheckIcon, CopyIcon } from '#icons'\nimport { Button } from '#components/actions/Button'\nimport { cx } from '#utils/cx'\nimport styles from './CodeBlock.module.css'\n\nexport interface CodeBlockProps extends Omit<HTMLAttributes<HTMLElement>, 'title'> {\n  /** The source, verbatim. Trailing newlines are trimmed. */\n  code: string\n  /** Shown as a label (\"TypeScript\", \"bash\"). No syntax highlighting — the code is the design. */\n  language?: string\n  /** Filename or caption shown in the header: `src/queries/keys.ts`. */\n  title?: ReactNode\n  /** Number the lines in a gutter (not copied with a selection). */\n  showLineNumbers?: boolean\n  /** 1-based line numbers to mark with the theme's highlight colour. */\n  highlightLines?: number[]\n  /** Show a copy button. Default `true`. */\n  copyable?: boolean\n  /** Wrap long lines instead of scrolling sideways. */\n  wrap?: boolean\n  /** Accessible name of the copy button. Default \"Copy code\". */\n  copyLabel?: string\n}\n\ntype CopyState = 'idle' | 'copied' | 'failed'\n\n/**\n * A block of source with an optional filename bar, line numbers, highlighted lines and a copy\n * button.\n *\n * @remarks\n * `CodeBlock` shows code: a snippet in an article, a command, a config example. It's a plain\n * surface with an optional title bar, never fake window chrome, and it has no syntax highlighting:\n * the code is the design. Every code sample in these docs is a `CodeBlock`.\n *\n * @privateRemarks\n * A block of source: a snippet in a blog post, a command in a README, a config example.\n * A plain surface with an optional filename bar — no fake window chrome.\n *\n * <CodeBlock title=\"queries/keys.ts\" language=\"TypeScript\" code={source} highlightLines={[3, 4]} />\n */\nexport const CodeBlock = forwardRef<HTMLElement, CodeBlockProps>(function CodeBlock(\n  {\n    code,\n    language,\n    title,\n    showLineNumbers = false,\n    highlightLines,\n    copyable = true,\n    wrap = false,\n    copyLabel = 'Copy code',\n    className,\n    ...rest\n  },\n  ref,\n) {\n  const [copy, setCopy] = useState<CopyState>('idle')\n  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)\n  const captionId = useId()\n  const source = code.replace(/\\n+$/, '')\n  const lines = source.split('\\n')\n  const highlighted = new Set(highlightLines)\n  const hasHeader = Boolean(title) || Boolean(language) || copyable\n\n  useEffect(\n    () => () => {\n      clearTimeout(timer.current)\n    },\n    [],\n  )\n\n  const onCopy = async () => {\n    clearTimeout(timer.current)\n    try {\n      await navigator.clipboard.writeText(source)\n      setCopy('copied')\n    } catch {\n      setCopy('failed')\n    }\n    timer.current = setTimeout(() => {\n      setCopy('idle')\n    }, 2000)\n  }\n\n  return (\n    <figure\n      ref={ref}\n      className={cx(styles.codeBlock, className)}\n      data-kiln-component=\"\"\n      data-wrap={wrap || undefined}\n      data-line-numbers={showLineNumbers || undefined}\n      aria-labelledby={title ? captionId : undefined}\n      {...rest}\n    >\n      {hasHeader ? (\n        <figcaption className={styles.header}>\n          {title ? (\n            <span id={captionId} className={styles.title}>\n              {title}\n            </span>\n          ) : null}\n          {language ? <span className={styles.language}>{language}</span> : null}\n          {copyable ? (\n            <Button\n              variant=\"ghost\"\n              tone=\"neutral\"\n              size=\"sm\"\n              className={styles.copy}\n              leadingIcon={copy === 'copied' ? <CheckIcon /> : <CopyIcon />}\n              aria-label={copyLabel}\n              onClick={() => {\n                void onCopy()\n              }}\n              data-state={copy}\n            >\n              {copy === 'copied' ? 'Copied' : copy === 'failed' ? 'Copy failed' : 'Copy'}\n            </Button>\n          ) : null}\n        </figcaption>\n      ) : null}\n      {/* A scrollable region must be reachable by keyboard. */}\n      <pre className={styles.pre} tabIndex={0}>\n        <code className={styles.code}>\n          {lines.map((line, i) => (\n            <span\n              key={i}\n              className={styles.line}\n              data-line={showLineNumbers ? i + 1 : undefined}\n              data-highlighted={highlighted.has(i + 1) || undefined}\n            >\n              {line}\n              {i < lines.length - 1 ? '\\n' : null}\n            </span>\n          ))}\n        </code>\n      </pre>\n      {copyable ? (\n        <span className={styles.visuallyHidden} role=\"status\" aria-live=\"polite\">\n          {copy === 'copied' ? 'Copied to clipboard' : copy === 'failed' ? 'Copy failed' : ''}\n        </span>\n      ) : null}\n    </figure>\n  )\n})\n"],"mappings":";;;;;;;AAkDA,IAAaE,IAAYC,EAAwC,SAC/D,EACE,SACA,aACA,UACA,qBAAkB,IAClB,mBACA,cAAW,IACX,UAAO,IACP,eAAY,aACZ,cACA,GAAGC,KAEL,GACA;CACA,IAAM,CAACC,GAAMC,KAAWC,EAAoB,MAAM,GAC5CC,IAAQC,EAAkD,KAAA,CAAS,GACnEC,IAAYC,EAAM,GAClBC,IAASC,EAAK,QAAQ,QAAQ,EAAE,GAChCC,IAAQF,EAAO,MAAM,IAAI,GACzBG,IAAc,IAAI,IAAIC,CAAc,GACpCC,IAAY,EAAQC,KAAU,EAAQC,KAAaC;CAEzD,cACc;EACV,aAAaZ,EAAM,OAAO;CAC5B,GACA,CAAC,CACH;CAEA,IAAMa,IAAS,YAAY;EACzB,aAAab,EAAM,OAAO;EAC1B,IAAI;GAEF,AADA,MAAM,UAAU,UAAU,UAAUI,CAAM,GAC1CN,EAAQ,QAAQ;EAClB,QAAQ;GACN,EAAQ,QAAQ;EAClB;EACA,EAAM,UAAU,iBAAiB;GAC/B,EAAQ,MAAM;EAChB,GAAG,GAAI;CACT;CAEA,OACE,kBAAC,UAAD;EACO;EACL,WAAWgB,EAAGtB,EAAO,WAAWuB,CAAS;EACzC,uBAAoB;EACpB,aAAWC,KAAQ,KAAA;EACnB,qBAAmBC,KAAmB,KAAA;EACtC,mBAAiBP,IAAQR,IAAY,KAAA;EACrC,GAAIN;EAPN,UAAA;GASGa,IACC,kBAAC,cAAD;IAAY,WAAWjB,EAAO;IAA9B,UAAA;KACGkB,IACC,kBAAC,QAAD;MAAM,IAAIR;MAAW,WAAWV,EAAO;MACpC,UAAAkB;KACG,CAAA,IACJ;KACHC,IAAW,kBAAC,QAAD;MAAM,WAAWnB,EAAO;MAAW,UAAAmB;KAAe,CAAA,IAAI;KACjEC,IACC,kBAACM,GAAD;MACE,SAAQ;MACR,MAAK;MACL,MAAK;MACL,WAAW1B,EAAO;MAClB,aAAiC2B,EAApBtB,MAAS,WAAYuB,IAAgBC,GAAjB,CAAY,CAAe;MAC5D,cAAYC;MACZ,eAAe;OACb,EAAY;MACd;MACA,cAAYzB;MAEX,UAAAA,MAAS,WAAW,WAAWA,MAAS,WAAW,gBAAgB;KAC9D,CAAA,IACN;IACM;GACV,CAAA,IAAA;GAEJ,kBAAC,OAAD;IAAK,WAAWL,EAAO;IAAK,UAAU;IACpC,UAAA,kBAAC,QAAD;KAAM,WAAWA,EAAO;KACrB,UAAAc,EAAM,KAAK,GAAM,MAChB,kBAAC,QAAD;MAEE,WAAWd,EAAO;MAClB,aAAWyB,IAAkBM,IAAI,IAAI,KAAA;MACrC,oBAAkBhB,EAAY,IAAIgB,IAAI,CAAC,KAAK,KAAA;MAJ9C,UAAA,CAMGC,GACAD,IAAIjB,EAAM,SAAS,IAAI,OAAO,IAC3B;KAPC,GAAAiB,CAOD,CACP;IACG,CAAA;GACH,CAAA;GACJX,IACC,kBAAC,QAAD;IAAM,WAAWpB,EAAO;IAAgB,MAAK;IAAS,aAAU;IAC7D,UAAAK,MAAS,WAAW,wBAAwBA,MAAS,WAAW,gBAAgB;GAC7E,CAAA,IACJ;EACE;;AAEZ,CAAC"}
+{"version":3,"file":"CodeBlock.js","names":["styles","CodeBlock_module_default","CodeBlock","forwardRef","rest","copy","setCopy","useState","timer","useRef","captionId","useId","source","trimTrailingNewlines","code","lines","lineTokens","tokens","line","token","i","highlighted","highlightLines","hasHeader","title","language","copyable","onCopy","cx","className","wrap","showLineNumbers","Button","jsx","CheckIcon","CopyIcon","copyLabel","j"],"sources":["../../../../src/components/display/CodeBlock/CodeBlock.tsx"],"sourcesContent":["import {\n  forwardRef,\n  useEffect,\n  useId,\n  useRef,\n  useState,\n  type HTMLAttributes,\n  type ReactNode,\n} from 'react'\nimport { CheckIcon, CopyIcon } from '#icons'\nimport { Button } from '#components/actions/Button'\nimport { cx } from '#utils/cx'\nimport { trimTrailingNewlines } from '#utils/newlines'\nimport styles from './CodeBlock.module.css'\n\n/**\n * What a piece of highlighted source is. Each kind is coloured from the theme's own tokens, so\n * highlighted code follows the theme and the colour mode.\n */\nexport type CodeTokenType =\n  | 'keyword'\n  | 'string'\n  | 'comment'\n  | 'constant'\n  | 'function'\n  | 'type'\n  | 'tag'\n  | 'attribute'\n  | 'punctuation'\n\n/** A run of source text and its kind. A token with no `type` is plain text. */\nexport interface CodeToken {\n  content: string\n  type?: CodeTokenType\n}\n\nexport interface CodeBlockProps extends Omit<HTMLAttributes<HTMLElement>, 'title'> {\n  /** The source, verbatim. Trailing newlines are trimmed. */\n  code: string\n  /** Shown as a label (\"TypeScript\", \"bash\"). It doesn't turn on highlighting: `tokens` does. */\n  language?: string\n  /**\n   * Syntax highlighting for `code`: one array of tokens per line, as `highlight` from\n   * `@mitcsutt/kiln-ui/highlight` returns them. Without it, or when the tokens don't spell out\n   * `code` line for line (say, tokens from a previous `code`), the code is plain.\n   */\n  tokens?: CodeToken[][]\n  /** Filename or caption shown in the header: `src/queries/keys.ts`. */\n  title?: ReactNode\n  /** Number the lines in a gutter (not copied with a selection). */\n  showLineNumbers?: boolean\n  /** 1-based line numbers to mark with the theme's highlight colour. */\n  highlightLines?: number[]\n  /** Show a copy button. Default `true`. */\n  copyable?: boolean\n  /** Wrap long lines instead of scrolling sideways. */\n  wrap?: boolean\n  /** Accessible name of the copy button. Default \"Copy code\". */\n  copyLabel?: string\n}\n\ntype CopyState = 'idle' | 'copied' | 'failed'\n\n/**\n * A block of source with an optional filename bar, line numbers, highlighted lines and a copy\n * button.\n *\n * @remarks\n * `CodeBlock` shows code: a snippet in an article, a command, a config example. It's a plain\n * surface with an optional title bar, never fake window chrome. It's plain unless you pass\n * `tokens`: `highlight` from `@mitcsutt/kiln-ui/highlight` turns JavaScript, JSX, TypeScript and\n * TSX into tokens, coloured from the theme. Every code sample in these docs is a `CodeBlock`.\n *\n * ## Highlighting\n *\n * `highlight(code, language)` resolves to the tokens for `code`, or to `undefined` for a language\n * other than `js`, `jsx`, `ts` or `tsx` (or `javascript` and `typescript`), which `CodeBlock`\n * shows as plain code. It runs [Shiki](https://shiki.style), an optional peer dependency, so\n * install `shiki` to use it. The main `@mitcsutt/kiln-ui` entry never loads it.\n *\n * Keywords and tags take the accent, strings, constants, functions and types take the theme's\n * tones, and comments and punctuation are muted. A custom theme needs no code palette of its own.\n *\n * The tokens are plain data, so highlight wherever the code is ready. In a server component or\n * at build time, `await` it and pass the tokens to the client component that renders the\n * `CodeBlock`, and the browser downloads no highlighter. In the browser, call it in an effect, as\n * in the example above: Shiki and the grammar load on the first call.\n *\n * ```tsx\n * import { highlight } from '@mitcsutt/kiln-ui/highlight'\n *\n * export async function Snippet({ source }: { source: string }) {\n *   const tokens = await highlight(source, 'tsx')\n *   return <SnippetBlock code={source} tokens={tokens} />\n * }\n * ```\n *\n * @privateRemarks\n * A block of source: a snippet in a blog post, a command in a README, a config example.\n * A plain surface with an optional filename bar — no fake window chrome.\n *\n * <CodeBlock title=\"queries/keys.ts\" language=\"TypeScript\" code={source} highlightLines={[3, 4]} />\n */\nexport const CodeBlock = forwardRef<HTMLElement, CodeBlockProps>(function CodeBlock(\n  {\n    code,\n    language,\n    tokens,\n    title,\n    showLineNumbers = false,\n    highlightLines,\n    copyable = true,\n    wrap = false,\n    copyLabel = 'Copy code',\n    className,\n    ...rest\n  },\n  ref,\n) {\n  const [copy, setCopy] = useState<CopyState>('idle')\n  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)\n  const captionId = useId()\n  const source = trimTrailingNewlines(code)\n  const lines = source.split('\\n')\n  const lineTokens =\n    tokens?.length === lines.length &&\n    tokens.every((line, i) => line.map((token) => token.content).join('') === lines[i])\n      ? tokens\n      : undefined\n  const highlighted = new Set(highlightLines)\n  const hasHeader = Boolean(title) || Boolean(language) || copyable\n\n  useEffect(\n    () => () => {\n      clearTimeout(timer.current)\n    },\n    [],\n  )\n\n  const onCopy = async () => {\n    clearTimeout(timer.current)\n    try {\n      await navigator.clipboard.writeText(source)\n      setCopy('copied')\n    } catch {\n      setCopy('failed')\n    }\n    timer.current = setTimeout(() => {\n      setCopy('idle')\n    }, 2000)\n  }\n\n  return (\n    <figure\n      ref={ref}\n      className={cx(styles.codeBlock, className)}\n      data-kiln-component=\"\"\n      data-wrap={wrap || undefined}\n      data-line-numbers={showLineNumbers || undefined}\n      aria-labelledby={title ? captionId : undefined}\n      {...rest}\n    >\n      {hasHeader ? (\n        <figcaption className={styles.header}>\n          {title ? (\n            <span id={captionId} className={styles.title}>\n              {title}\n            </span>\n          ) : null}\n          {language ? <span className={styles.language}>{language}</span> : null}\n          {copyable ? (\n            <Button\n              variant=\"ghost\"\n              tone=\"neutral\"\n              size=\"sm\"\n              className={styles.copy}\n              leadingIcon={copy === 'copied' ? <CheckIcon /> : <CopyIcon />}\n              aria-label={copyLabel}\n              onClick={() => {\n                void onCopy()\n              }}\n              data-state={copy}\n            >\n              {copy === 'copied' ? 'Copied' : copy === 'failed' ? 'Copy failed' : 'Copy'}\n            </Button>\n          ) : null}\n        </figcaption>\n      ) : null}\n      {/* A scrollable region must be reachable by keyboard. */}\n      <pre className={styles.pre} tabIndex={0}>\n        <code className={styles.code}>\n          {lines.map((line, i) => (\n            <span\n              key={i}\n              className={styles.line}\n              data-line={showLineNumbers ? i + 1 : undefined}\n              data-highlighted={highlighted.has(i + 1) || undefined}\n            >\n              {lineTokens?.[i]\n                ? lineTokens[i].map((token, j) =>\n                    token.type ? (\n                      <span key={j} className={styles.token} data-token={token.type}>\n                        {token.content}\n                      </span>\n                    ) : (\n                      token.content\n                    ),\n                  )\n                : line}\n              {i < lines.length - 1 ? '\\n' : null}\n            </span>\n          ))}\n        </code>\n      </pre>\n      {copyable ? (\n        <span className={styles.visuallyHidden} role=\"status\" aria-live=\"polite\">\n          {copy === 'copied' ? 'Copied to clipboard' : copy === 'failed' ? 'Copy failed' : ''}\n        </span>\n      ) : null}\n    </figure>\n  )\n})\n"],"mappings":";;;;;;;;AAuGA,IAAaE,IAAYC,EAAwC,SAC/D,EACE,SACA,aACA,WACA,UACA,qBAAkB,IAClB,mBACA,cAAW,IACX,UAAO,IACP,eAAY,aACZ,cACA,GAAGC,KAEL,GACA;CACA,IAAM,CAACC,GAAMC,KAAWC,EAAoB,MAAM,GAC5CC,IAAQC,EAAkD,KAAA,CAAS,GACnEC,IAAYC,EAAM,GAClBC,IAASC,EAAqBC,CAAI,GAClCC,IAAQH,EAAO,MAAM,IAAI,GACzBI,IACJC,GAAQ,WAAWF,EAAM,UACzBE,EAAO,OAAO,GAAM,MAAMC,EAAK,KAAK,MAAUC,EAAM,OAAO,CAAC,CAAC,KAAK,EAAE,MAAMJ,EAAMK,EAAE,IAC9EH,IACA,KAAA,GACAI,IAAc,IAAI,IAAIC,CAAc,GACpCC,IAAY,EAAQC,KAAU,EAAQC,KAAaC;CAEzD,cACc;EACV,aAAalB,EAAM,OAAO;CAC5B,GACA,CAAC,CACH;CAEA,IAAMmB,IAAS,YAAY;EACzB,aAAanB,EAAM,OAAO;EAC1B,IAAI;GAEF,AADA,MAAM,UAAU,UAAU,UAAUI,CAAM,GAC1CN,EAAQ,QAAQ;EAClB,QAAQ;GACN,EAAQ,QAAQ;EAClB;EACA,EAAM,UAAU,iBAAiB;GAC/B,EAAQ,MAAM;EAChB,GAAG,GAAI;CACT;CAEA,OACE,kBAAC,UAAD;EACO;EACL,WAAWsB,EAAG5B,EAAO,WAAW6B,CAAS;EACzC,uBAAoB;EACpB,aAAWC,KAAQ,KAAA;EACnB,qBAAmBC,KAAmB,KAAA;EACtC,mBAAiBP,IAAQd,IAAY,KAAA;EACrC,GAAIN;EAPN,UAAA;GASGmB,IACC,kBAAC,cAAD;IAAY,WAAWvB,EAAO;IAA9B,UAAA;KACGwB,IACC,kBAAC,QAAD;MAAM,IAAId;MAAW,WAAWV,EAAO;MACpC,UAAAwB;KACG,CAAA,IACJ;KACHC,IAAW,kBAAC,QAAD;MAAM,WAAWzB,EAAO;MAAW,UAAAyB;KAAe,CAAA,IAAI;KACjEC,IACC,kBAACM,GAAD;MACE,SAAQ;MACR,MAAK;MACL,MAAK;MACL,WAAWhC,EAAO;MAClB,aAAiCiC,EAApB5B,MAAS,WAAY6B,IAAgBC,GAAjB,CAAY,CAAe;MAC5D,cAAYC;MACZ,eAAe;OACb,EAAY;MACd;MACA,cAAY/B;MAEX,UAAAA,MAAS,WAAW,WAAWA,MAAS,WAAW,gBAAgB;KAC9D,CAAA,IACN;IACM;GACV,CAAA,IAAA;GAEJ,kBAAC,OAAD;IAAK,WAAWL,EAAO;IAAK,UAAU;IACpC,UAAA,kBAAC,QAAD;KAAM,WAAWA,EAAO;KACrB,UAAAe,EAAM,KAAK,GAAM,MAChB,kBAAC,QAAD;MAEE,WAAWf,EAAO;MAClB,aAAW+B,IAAkBX,IAAI,IAAI,KAAA;MACrC,oBAAkBC,EAAY,IAAID,IAAI,CAAC,KAAK,KAAA;MAJ9C,UAAA,CAMGJ,IAAaI,KACVJ,EAAWI,EAAE,CAAC,KAAK,GAAO,MACxBD,EAAM,OACJ,kBAAC,QAAD;OAAc,WAAWnB,EAAO;OAAO,cAAYmB,EAAM;OACtD,UAAAA,EAAM;MACH,GAFKkB,CAEL,IAENlB,EAAM,OAEV,IACAD,GACHE,IAAIL,EAAM,SAAS,IAAI,OAAO,IAC3B;KAjBC,GAAAK,CAiBD,CACP;IACG,CAAA;GACH,CAAA;GACJM,IACC,kBAAC,QAAD;IAAM,WAAW1B,EAAO;IAAgB,MAAK;IAAS,aAAU;IAC7D,UAAAK,MAAS,WAAW,wBAAwBA,MAAS,WAAW,gBAAgB;GAC7E,CAAA,IACJ;EACE;;AAEZ,CAAC"}

package/dist/components/display/CodeBlock/CodeBlock.module.js

@@ -1,5 +1,5 @@
 //#region src/components/display/CodeBlock/CodeBlock.module.css
-var e = "kiln-CodeBlock__codeBlock", t = "kiln-CodeBlock__header", n = "kiln-CodeBlock__title", r = "kiln-CodeBlock__language", i = "kiln-CodeBlock__copy", a = "kiln-CodeBlock__pre", o = "kiln-CodeBlock__code", s = "kiln-CodeBlock__line", c = "kiln-CodeBlock__visuallyHidden", l = {
+var e = "kiln-CodeBlock__codeBlock", t = "kiln-CodeBlock__header", n = "kiln-CodeBlock__title", r = "kiln-CodeBlock__language", i = "kiln-CodeBlock__copy", a = "kiln-CodeBlock__pre", o = "kiln-CodeBlock__code", s = "kiln-CodeBlock__line", c = "kiln-CodeBlock__token", l = "kiln-CodeBlock__visuallyHidden", u = {
 	codeBlock: e,
 	header: t,
 	title: n,
@@ -8,9 +8,10 @@ var e = "kiln-CodeBlock__codeBlock", t = "kiln-CodeBlock__header", n = "kiln-Cod
 	pre: a,
 	code: o,
 	line: s,
-	visuallyHidden: c
+	token: c,
+	visuallyHidden: l
 };
 //#endregion
-export { o as code, e as codeBlock, i as copy, l as default, t as header, r as language, s as line, a as pre, n as title, c as visuallyHidden };
+export { o as code, e as codeBlock, i as copy, u as default, t as header, r as language, s as line, a as pre, n as title, c as token, l as visuallyHidden };
 
 //# sourceMappingURL=CodeBlock.module.js.map

package/dist/components/display/CodeBlock/CodeBlock.module.js.map

@@ -1 +1 @@
-{"version":3,"file":"CodeBlock.module.js","names":["codeBlock","header","title","language","copy","pre","code","line","visuallyHidden","CodeBlock_module_default"],"sources":["../../../../src/components/display/CodeBlock/CodeBlock.module.css"],"sourcesContent":["/*\n * Component tokens (themes may set any of these on [data-theme]):\n *   --codeblock-bg          default var(--color-surface-sunken)\n *   --codeblock-radius      default var(--radius-surface)\n *   --codeblock-size        default var(--text-xs)\n *   --codeblock-highlight   highlighted line fill, default var(--color-highlight)\n *\n * One edge: a hairline. The header is separated by the same rule, not a fill.\n */\n/* Zero-specificity reset, so a surrounding flow (Prose, Stack) or a className can space it. */\n:where(.codeBlock) {\n  margin: 0;\n}\n.codeBlock {\n  --_pad: var(--space-4);\n\n  display: flex;\n  flex-direction: column;\n  min-inline-size: 0;\n  overflow: hidden;\n  border: var(--border-width) solid var(--color-line);\n  border-radius: var(--codeblock-radius, var(--radius-surface));\n  background: var(--codeblock-bg, var(--color-surface-sunken));\n  color: var(--color-ink);\n}\n\n.header {\n  display: flex;\n  align-items: center;\n  gap: var(--space-3);\n  min-block-size: calc(var(--control-sm) + var(--space-2));\n  padding-inline: var(--_pad) var(--space-2);\n  border-block-end: var(--border-width) solid var(--color-line);\n  font-family: var(--font-text);\n  font-size: var(--text-xs);\n  line-height: var(--leading-snug);\n}\n\n.title {\n  min-inline-size: 0;\n  overflow: hidden;\n  text-overflow: ellipsis;\n  white-space: nowrap;\n  color: var(--color-ink);\n  font-weight: var(--label-weight);\n}\n\n.language {\n  color: var(--color-ink-subtle);\n}\n.title + .language::before {\n  content: '·';\n  margin-inline-end: var(--space-3);\n}\n\n.copy {\n  margin-inline-start: auto;\n  color: var(--color-ink-muted);\n}\n.copy[data-state='copied'] {\n  color: var(--tone-positive-text);\n}\n.copy[data-state='failed'] {\n  color: var(--tone-critical-text);\n}\n\n.pre {\n  margin: 0;\n  padding-block: var(--space-3);\n  overflow-x: auto;\n  font-family: var(--font-mono);\n  font-stretch: var(--mono-stretch);\n  font-size: var(--codeblock-size, var(--text-xs));\n  font-variant-ligatures: none;\n  line-height: 1.7;\n  tab-size: 2;\n  white-space: pre;\n  scrollbar-width: thin;\n}\n.pre:focus-visible {\n  outline: 2px solid var(--color-focus);\n  outline-offset: -2px;\n}\n\n.code {\n  display: inline-block;\n  min-inline-size: 100%;\n  font: inherit;\n}\n\n.line {\n  display: block;\n  position: relative;\n  padding-inline: var(--_pad);\n}\n\n.codeBlock[data-line-numbers] .line {\n  padding-inline-start: calc(var(--_pad) + 4ch);\n}\n.codeBlock[data-line-numbers] .line::before {\n  content: attr(data-line);\n  position: absolute;\n  inset-inline-start: 0;\n  inline-size: calc(var(--_pad) + 2.5ch);\n  padding-inline-end: 1ch;\n  text-align: end;\n  color: var(--color-ink-subtle);\n  font-variant-numeric: tabular-nums;\n  user-select: none;\n}\n\n.line[data-highlighted] {\n  background: var(--codeblock-highlight, var(--color-highlight));\n  color: var(--color-highlight-ink);\n}\n.line[data-highlighted]::before {\n  color: inherit;\n}\n\n.codeBlock[data-wrap] .pre {\n  white-space: pre-wrap;\n  overflow-wrap: anywhere;\n}\n.codeBlock[data-wrap] .code {\n  display: block;\n}\n\n.visuallyHidden {\n  position: absolute;\n  inline-size: 1px;\n  block-size: 1px;\n  margin: -1px;\n  padding: 0;\n  overflow: hidden;\n  clip-path: inset(50%);\n  white-space: nowrap;\n  border: 0;\n}\n"],"mappings":""}
+{"version":3,"file":"CodeBlock.module.js","names":["codeBlock","header","title","language","copy","pre","code","line","token","visuallyHidden","CodeBlock_module_default"],"sources":["../../../../src/components/display/CodeBlock/CodeBlock.module.css"],"sourcesContent":["/*\n * Component tokens (themes may set any of these on [data-theme]):\n *   --codeblock-bg          default var(--color-surface-sunken)\n *   --codeblock-radius      default var(--radius-surface)\n *   --codeblock-size        default var(--text-xs)\n *   --codeblock-highlight   highlighted line fill, default var(--color-highlight)\n *\n * One edge: a hairline. The header is separated by the same rule, not a fill.\n */\n/* Zero-specificity reset, so a surrounding flow (Prose, Stack) or a className can space it. */\n:where(.codeBlock) {\n  margin: 0;\n}\n.codeBlock {\n  --_pad: var(--space-4);\n\n  display: flex;\n  flex-direction: column;\n  min-inline-size: 0;\n  overflow: hidden;\n  border: var(--border-width) solid var(--color-line);\n  border-radius: var(--codeblock-radius, var(--radius-surface));\n  background: var(--codeblock-bg, var(--color-surface-sunken));\n  color: var(--color-ink);\n}\n\n.header {\n  display: flex;\n  align-items: center;\n  gap: var(--space-3);\n  min-block-size: calc(var(--control-sm) + var(--space-2));\n  padding-inline: var(--_pad) var(--space-2);\n  border-block-end: var(--border-width) solid var(--color-line);\n  font-family: var(--font-text);\n  font-size: var(--text-xs);\n  line-height: var(--leading-snug);\n}\n\n.title {\n  min-inline-size: 0;\n  overflow: hidden;\n  text-overflow: ellipsis;\n  white-space: nowrap;\n  color: var(--color-ink);\n  font-weight: var(--label-weight);\n}\n\n.language {\n  color: var(--color-ink-subtle);\n}\n.title + .language::before {\n  content: '·';\n  margin-inline-end: var(--space-3);\n}\n\n.copy {\n  margin-inline-start: auto;\n  color: var(--color-ink-muted);\n}\n.copy[data-state='copied'] {\n  color: var(--tone-positive-text);\n}\n.copy[data-state='failed'] {\n  color: var(--tone-critical-text);\n}\n\n.pre {\n  margin: 0;\n  padding-block: var(--space-3);\n  overflow-x: auto;\n  font-family: var(--font-mono);\n  font-stretch: var(--mono-stretch);\n  font-size: var(--codeblock-size, var(--text-xs));\n  font-variant-ligatures: none;\n  line-height: 1.7;\n  tab-size: 2;\n  white-space: pre;\n  scrollbar-width: thin;\n}\n.pre:focus-visible {\n  outline: 2px solid var(--color-focus);\n  outline-offset: -2px;\n}\n\n.code {\n  display: inline-block;\n  min-inline-size: 100%;\n  font: inherit;\n}\n\n.line {\n  display: block;\n  position: relative;\n  padding-inline: var(--_pad);\n}\n\n.codeBlock[data-line-numbers] .line {\n  padding-inline-start: calc(var(--_pad) + 4ch);\n}\n.codeBlock[data-line-numbers] .line::before {\n  content: attr(data-line);\n  position: absolute;\n  inset-inline-start: 0;\n  inline-size: calc(var(--_pad) + 2.5ch);\n  padding-inline-end: 1ch;\n  text-align: end;\n  color: var(--color-ink-subtle);\n  font-variant-numeric: tabular-nums;\n  user-select: none;\n}\n\n/*\n * Highlighted tokens (the `tokens` prop) take the theme's own text colours, so a theme needs no\n * code palette of its own: keywords in the accent, strings, constants and names in the tones.\n */\n.token[data-token='keyword'],\n.token[data-token='tag'] {\n  color: var(--color-accent-text);\n}\n.token[data-token='string'] {\n  color: var(--tone-positive-text);\n}\n.token[data-token='constant'] {\n  color: var(--tone-caution-text);\n}\n.token[data-token='function'],\n.token[data-token='type'] {\n  color: var(--tone-info-text);\n}\n.token[data-token='attribute'],\n.token[data-token='punctuation'] {\n  color: var(--color-ink-muted);\n}\n.token[data-token='comment'] {\n  color: var(--color-ink-subtle);\n}\n\n.line[data-highlighted] {\n  background: var(--codeblock-highlight, var(--color-highlight));\n  color: var(--color-highlight-ink);\n}\n.line[data-highlighted]::before,\n.line[data-highlighted] .token {\n  color: inherit;\n}\n\n.codeBlock[data-wrap] .pre {\n  white-space: pre-wrap;\n  overflow-wrap: anywhere;\n}\n.codeBlock[data-wrap] .code {\n  display: block;\n}\n\n.visuallyHidden {\n  position: absolute;\n  inline-size: 1px;\n  block-size: 1px;\n  margin: -1px;\n  padding: 0;\n  overflow: hidden;\n  clip-path: inset(50%);\n  white-space: nowrap;\n  border: 0;\n}\n"],"mappings":""}

package/dist/components/display/CodeBlock/index.d.ts

@@ -1,2 +1,2 @@
 export { CodeBlock } from './CodeBlock.js';
-export type { CodeBlockProps } from './CodeBlock.js';
+export type { CodeBlockProps, CodeToken, CodeTokenType } from './CodeBlock.js';

package/dist/components/display/List/List.d.ts

@@ -2,6 +2,8 @@ import { type HTMLAttributes, type LiHTMLAttributes, type ReactNode } from 'reac
 import type { CategoryColor } from '../../../utils/tokens.js';
 export type ListDensity = 'compact' | 'regular';
 export type ListElement = 'ul' | 'ol';
+/** `surface` and `raised` set the list on one sheet, like `Card`'s `outline` and `raised`. */
+export type ListSurface = 'none' | 'surface' | 'raised';
 export interface ListProps extends HTMLAttributes<HTMLUListElement> {
     /** Hairline rules between rows. Default `true`. */
     divided?: boolean;
@@ -9,6 +11,12 @@ export interface ListProps extends HTMLAttributes<HTMLUListElement> {
     density?: ListDensity;
     /** `ol` when order is the content (a leaderboard). Default `ul`. */
     as?: ListElement;
+    /**
+     * Set the rows on a sheet so they read as rows, not text on the page: `surface` is the
+     * surface fill inside a hairline edge, `raised` stands on the theme's surface shadow. Rows run
+     * edge to edge, clipped to the sheet's corners. Default `none`.
+     */
+    surface?: ListSurface;
 }
 export interface ListItemProps extends Omit<LiHTMLAttributes<HTMLLIElement>, 'color'> {
     /** Hover affordance. Implied by `asChild`. */

package/dist/components/display/List/List.js

@@ -4,14 +4,15 @@ import { createContext as n, forwardRef as r, useContext as i } from "react";
 import { jsx as a } from "react/jsx-runtime";
 import { Slot as o } from "radix-ui";
 //#region src/components/display/List/List.tsx
-var s = r(function({ divided: n = !0, density: r = "regular", as: i = "ul", className: o, ...s }, c) {
+var s = r(function({ divided: n = !0, density: r = "regular", as: i = "ul", surface: o = "none", className: s, ...c }, l) {
 	return /* @__PURE__ */ a(i, {
-		ref: c,
+		ref: l,
 		role: "list",
-		className: e(t.list, o),
+		className: e(t.list, s),
 		"data-divided": n || void 0,
 		"data-density": r,
-		...s
+		"data-surface": o === "none" ? void 0 : o,
+		...c
 	});
 }), c = n(!1), l = r(function({ interactive: n = !1, asChild: r = !1, selected: i = !1, highlighted: s = !1, muted: l = !1, color: u, className: d, children: f, ...p }, m) {
 	let h = r ? o.Root : "div";

package/dist/components/display/List/List.js.map

@@ -1 +1 @@
-{"version":3,"file":"List.js","names":["styles","List_module_default","ListRoot","forwardRef","Comp","rest","cx","className","divided","density","RowIsControl","createContext","ListItem","Row","asChild","Slot","interactive","selected","highlighted","muted","color","ListLeading","useContext","ListContent","ListDescription","ListTrailing","List"],"sources":["../../../../src/components/display/List/List.tsx"],"sourcesContent":["import {\n  createContext,\n  forwardRef,\n  useContext,\n  type HTMLAttributes,\n  type LiHTMLAttributes,\n  type ReactNode,\n} from 'react'\nimport { Slot } from 'radix-ui'\nimport { cx } from '#utils/cx'\nimport type { CategoryColor } from '#utils/tokens'\nimport styles from './List.module.css'\n\nexport type ListDensity = 'compact' | 'regular'\nexport type ListElement = 'ul' | 'ol'\n\nexport interface ListProps extends HTMLAttributes<HTMLUListElement> {\n  /** Hairline rules between rows. Default `true`. */\n  divided?: boolean\n  /** Row height. Default `regular`. */\n  density?: ListDensity\n  /** `ol` when order is the content (a leaderboard). Default `ul`. */\n  as?: ListElement\n}\n\n/**\n * The workhorse row list. Leading, content and trailing slots, divided by hairlines, never boxed\n * in cards.\n *\n * @remarks\n * `List` is for rows of similar things: trips, people, invoices, recent activity. Each row has up\n * to three slots: `List.Leading` (an avatar, an icon, a rank), `List.Content` (a title and\n * `List.Description`), and `List.Trailing` (an amount, a time, an action). Rows are divided by\n * hairlines.\n *\n * @privateRemarks\n * The workhorse row list: leaderboards, team members, invoices, recent work. Rows are\n * `Leading · Content · Trailing`, divided by hairlines, never boxed in cards.\n *\n * <List><List.Item><List.Leading>1</List.Leading><List.Content>…</List.Content></List.Item></List>\n */\nconst ListRoot = forwardRef<HTMLUListElement, ListProps>(function List(\n  { divided = true, density = 'regular', as: Comp = 'ul', className, ...rest },\n  ref,\n) {\n  return (\n    <Comp\n      // @ts-expect-error — ul/ol share HTMLOListElement-compatible attributes; ref type differs only nominally\n      ref={ref}\n      role=\"list\"\n      className={cx(styles.list, className)}\n      data-divided={divided || undefined}\n      data-density={density}\n      {...rest}\n    />\n  )\n})\n\n/**\n * Whether the row is the asChild link or button. Its slots are then spans, the only content a\n * button may hold; elsewhere they're divs, so block components (Stat, Stack) fit in them.\n */\nconst RowIsControl = createContext(false)\n\nexport interface ListItemProps extends Omit<LiHTMLAttributes<HTMLLIElement>, 'color'> {\n  /** Hover affordance. Implied by `asChild`. */\n  interactive?: boolean\n  /**\n   * Make the whole row one link or button: the single child becomes the row, so there\n   * is exactly one interactive element and no nested anchors.\n   * `<List.Item asChild><a href=\"/projects/atlas\">…slots…</a></List.Item>`\n   */\n  asChild?: boolean\n  /** The current item (accent-soft fill) — e.g. the open page in a list of links. */\n  selected?: boolean\n  /** Draw attention to a row with `--color-highlight` — typically \"you\". */\n  highlighted?: boolean\n  /** Out of play (eliminated, archived, past): every ink drops to the muted step, which still reads. */\n  muted?: boolean\n  /** A categorical colour drawn as a rail at the row's start: whose row it is, matching their `Tag`. */\n  color?: CategoryColor\n  children?: ReactNode\n}\n\nconst ListItem = forwardRef<HTMLLIElement, ListItemProps>(function ListItem(\n  {\n    interactive = false,\n    asChild = false,\n    selected = false,\n    highlighted = false,\n    muted = false,\n    color,\n    className,\n    children,\n    ...rest\n  },\n  ref,\n) {\n  const Row = asChild ? Slot.Root : 'div'\n  return (\n    <li\n      ref={ref}\n      className={cx(styles.item, className)}\n      data-interactive={interactive || asChild || undefined}\n      data-selected={selected || undefined}\n      data-highlighted={highlighted || undefined}\n      data-muted={muted || undefined}\n      data-color={color}\n      {...rest}\n    >\n      <RowIsControl.Provider value={asChild}>\n        <Row className={styles.row}>{children}</Row>\n      </RowIsControl.Provider>\n    </li>\n  )\n})\n\n/** Rank, avatar or icon at the start of the row. Numbers are tabular and right-aligned. */\nconst ListLeading = forwardRef<HTMLElement, HTMLAttributes<HTMLElement>>(function ListLeading(\n  { className, ...rest },\n  ref,\n) {\n  const Comp = useContext(RowIsControl) ? 'span' : 'div'\n  // @ts-expect-error — polymorphic ref across span/div is safe here\n  return <Comp ref={ref} className={cx(styles.leading, className)} {...rest} />\n})\n\n/** Title (the direct text) and an optional `List.Description` below it. */\nconst ListContent = forwardRef<HTMLElement, HTMLAttributes<HTMLElement>>(function ListContent(\n  { className, ...rest },\n  ref,\n) {\n  const Comp = useContext(RowIsControl) ? 'span' : 'div'\n  // @ts-expect-error — polymorphic ref across span/div is safe here\n  return <Comp ref={ref} className={cx(styles.content, className)} {...rest} />\n})\n\nconst ListDescription = forwardRef<HTMLElement, HTMLAttributes<HTMLElement>>(\n  function ListDescription({ className, ...rest }, ref) {\n    const Comp = useContext(RowIsControl) ? 'span' : 'div'\n    // @ts-expect-error — polymorphic ref across span/div is safe here\n    return <Comp ref={ref} className={cx(styles.description, className)} {...rest} />\n  },\n)\n\n/** Value, meta or actions at the end of the row. Numbers are tabular. */\nconst ListTrailing = forwardRef<HTMLElement, HTMLAttributes<HTMLElement>>(function ListTrailing(\n  { className, ...rest },\n  ref,\n) {\n  const Comp = useContext(RowIsControl) ? 'span' : 'div'\n  // @ts-expect-error — polymorphic ref across span/div is safe here\n  return <Comp ref={ref} className={cx(styles.trailing, className)} {...rest} />\n})\n\nexport const List = Object.assign(ListRoot, {\n  Item: ListItem,\n  Leading: ListLeading,\n  Content: ListContent,\n  Description: ListDescription,\n  Trailing: ListTrailing,\n})\n"],"mappings":";;;;;;AAyCA,IAAME,IAAWC,EAAwC,SACvD,EAAE,aAAU,IAAM,aAAU,WAAW,IAAIC,IAAO,MAAM,cAAW,GAAGC,KACtE,GACA;CACA,OACE,kBAACD,GAAD;EAEO;EACL,MAAK;EACL,WAAWE,EAAGN,EAAO,MAAMO,CAAS;EACpC,gBAAcC,KAAW,KAAA;EACzB,gBAAcC;EACd,GAAIJ;CACL,CAAA;AAEL,CAAC,GAMKK,IAAeC,EAAc,EAAK,GAsBlCC,IAAWT,EAAyC,SACxD,EACE,iBAAc,IACd,aAAU,IACV,cAAW,IACX,iBAAc,IACd,WAAQ,IACR,UACA,cACA,aACA,GAAGE,KAEL,GACA;CACA,IAAMQ,IAAMC,IAAUC,EAAK,OAAO;CAClC,OACE,kBAAC,MAAD;EACO;EACL,WAAWT,EAAGN,EAAO,MAAMO,CAAS;EACpC,oBAAkBS,KAAeF,KAAW,KAAA;EAC5C,iBAAeG,KAAY,KAAA;EAC3B,oBAAkBC,KAAe,KAAA;EACjC,cAAYC,KAAS,KAAA;EACrB,cAAYC;EACZ,GAAIf;EAEJ,UAAA,kBAACK,EAAa,UAAd;GAAuB,OAAOI;GAC5B,UAAA,kBAACD,GAAD;IAAK,WAAWb,EAAO;IAAM;GAAc,CAAA;EACtB,CAAA;CACrB,CAAA;AAER,CAAC,GAGKqB,IAAclB,EAAqD,SACvE,EAAE,cAAW,GAAGE,KAChB,GACA;CACA,IAAMD,IAAOkB,EAAWZ,CAAY,IAAI,SAAS;CAEjD,OAAO,kBAACN,GAAD;EAAW;EAAK,WAAWE,EAAGN,EAAO,SAASO,CAAS;EAAG,GAAIF;CAAO,CAAA;AAC9E,CAAC,GAGKkB,IAAcpB,EAAqD,SACvE,EAAE,cAAW,GAAGE,KAChB,GACA;CACA,IAAMD,IAAOkB,EAAWZ,CAAY,IAAI,SAAS;CAEjD,OAAO,kBAACN,GAAD;EAAW;EAAK,WAAWE,EAAGN,EAAO,SAASO,CAAS;EAAG,GAAIF;CAAO,CAAA;AAC9E,CAAC,GAEKmB,IAAkBrB,EACtB,SAAyB,EAAE,cAAW,GAAGE,KAAQ,GAAK;CACpD,IAAMD,IAAOkB,EAAWZ,CAAY,IAAI,SAAS;CAEjD,OAAO,kBAACN,GAAD;EAAW;EAAK,WAAWE,EAAGN,EAAO,aAAaO,CAAS;EAAG,GAAIF;CAAO,CAAA;AAClF,CACF,GAGMoB,IAAetB,EAAqD,SACxE,EAAE,cAAW,GAAGE,KAChB,GACA;CACA,IAAMD,IAAOkB,EAAWZ,CAAY,IAAI,SAAS;CAEjD,OAAO,kBAACN,GAAD;EAAW;EAAK,WAAWE,EAAGN,EAAO,UAAUO,CAAS;EAAG,GAAIF;CAAO,CAAA;AAC/E,CAAC,GAEYqB,IAAO,OAAO,OAAOxB,GAAU;CAC1C,MAAMU;CACN,SAASS;CACT,SAASE;CACT,aAAaC;CACb,UAAUC;AACZ,CAAC"}
+{"version":3,"file":"List.js","names":["styles","List_module_default","ListRoot","forwardRef","Comp","rest","cx","className","divided","density","surface","RowIsControl","createContext","ListItem","Row","asChild","Slot","interactive","selected","highlighted","muted","color","ListLeading","useContext","ListContent","ListDescription","ListTrailing","List"],"sources":["../../../../src/components/display/List/List.tsx"],"sourcesContent":["import {\n  createContext,\n  forwardRef,\n  useContext,\n  type HTMLAttributes,\n  type LiHTMLAttributes,\n  type ReactNode,\n} from 'react'\nimport { Slot } from 'radix-ui'\nimport { cx } from '#utils/cx'\nimport type { CategoryColor } from '#utils/tokens'\nimport styles from './List.module.css'\n\nexport type ListDensity = 'compact' | 'regular'\nexport type ListElement = 'ul' | 'ol'\n/** `surface` and `raised` set the list on one sheet, like `Card`'s `outline` and `raised`. */\nexport type ListSurface = 'none' | 'surface' | 'raised'\n\nexport interface ListProps extends HTMLAttributes<HTMLUListElement> {\n  /** Hairline rules between rows. Default `true`. */\n  divided?: boolean\n  /** Row height. Default `regular`. */\n  density?: ListDensity\n  /** `ol` when order is the content (a leaderboard). Default `ul`. */\n  as?: ListElement\n  /**\n   * Set the rows on a sheet so they read as rows, not text on the page: `surface` is the\n   * surface fill inside a hairline edge, `raised` stands on the theme's surface shadow. Rows run\n   * edge to edge, clipped to the sheet's corners. Default `none`.\n   */\n  surface?: ListSurface\n}\n\n/**\n * The workhorse row list. Leading, content and trailing slots, divided by hairlines, never boxed\n * in cards.\n *\n * @remarks\n * `List` is for rows of similar things: trips, people, invoices, recent activity. Each row has up\n * to three slots: `List.Leading` (an avatar, an icon, a rank), `List.Content` (a title and\n * `List.Description`), and `List.Trailing` (an amount, a time, an action). Rows are divided by\n * hairlines.\n *\n * ## On a surface\n *\n * On a busy page, or a theme whose canvas has a texture, `surface=\"surface\"` sets the whole list\n * on one sheet, and `surface=\"raised\"` stands it on the theme's surface shadow. The rows stay rows\n * on it and run edge to edge: a highlighted, selected or hovered row is a band across the sheet,\n * and a categorical rail is the row's edge, following the sheet's corners at either end.\n *\n * @privateRemarks\n * The workhorse row list: leaderboards, team members, invoices, recent work. Rows are\n * `Leading · Content · Trailing`, divided by hairlines, never boxed in cards.\n *\n * <List><List.Item><List.Leading>1</List.Leading><List.Content>…</List.Content></List.Item></List>\n */\nconst ListRoot = forwardRef<HTMLUListElement, ListProps>(function List(\n  { divided = true, density = 'regular', as: Comp = 'ul', surface = 'none', className, ...rest },\n  ref,\n) {\n  return (\n    <Comp\n      // @ts-expect-error — ul/ol share HTMLOListElement-compatible attributes; ref type differs only nominally\n      ref={ref}\n      role=\"list\"\n      className={cx(styles.list, className)}\n      data-divided={divided || undefined}\n      data-density={density}\n      data-surface={surface === 'none' ? undefined : surface}\n      {...rest}\n    />\n  )\n})\n\n/**\n * Whether the row is the asChild link or button. Its slots are then spans, the only content a\n * button may hold; elsewhere they're divs, so block components (Stat, Stack) fit in them.\n */\nconst RowIsControl = createContext(false)\n\nexport interface ListItemProps extends Omit<LiHTMLAttributes<HTMLLIElement>, 'color'> {\n  /** Hover affordance. Implied by `asChild`. */\n  interactive?: boolean\n  /**\n   * Make the whole row one link or button: the single child becomes the row, so there\n   * is exactly one interactive element and no nested anchors.\n   * `<List.Item asChild><a href=\"/projects/atlas\">…slots…</a></List.Item>`\n   */\n  asChild?: boolean\n  /** The current item (accent-soft fill) — e.g. the open page in a list of links. */\n  selected?: boolean\n  /** Draw attention to a row with `--color-highlight` — typically \"you\". */\n  highlighted?: boolean\n  /** Out of play (eliminated, archived, past): every ink drops to the muted step, which still reads. */\n  muted?: boolean\n  /** A categorical colour drawn as a rail at the row's start: whose row it is, matching their `Tag`. */\n  color?: CategoryColor\n  children?: ReactNode\n}\n\nconst ListItem = forwardRef<HTMLLIElement, ListItemProps>(function ListItem(\n  {\n    interactive = false,\n    asChild = false,\n    selected = false,\n    highlighted = false,\n    muted = false,\n    color,\n    className,\n    children,\n    ...rest\n  },\n  ref,\n) {\n  const Row = asChild ? Slot.Root : 'div'\n  return (\n    <li\n      ref={ref}\n      className={cx(styles.item, className)}\n      data-interactive={interactive || asChild || undefined}\n      data-selected={selected || undefined}\n      data-highlighted={highlighted || undefined}\n      data-muted={muted || undefined}\n      data-color={color}\n      {...rest}\n    >\n      <RowIsControl.Provider value={asChild}>\n        <Row className={styles.row}>{children}</Row>\n      </RowIsControl.Provider>\n    </li>\n  )\n})\n\n/** Rank, avatar or icon at the start of the row. Numbers are tabular and right-aligned. */\nconst ListLeading = forwardRef<HTMLElement, HTMLAttributes<HTMLElement>>(function ListLeading(\n  { className, ...rest },\n  ref,\n) {\n  const Comp = useContext(RowIsControl) ? 'span' : 'div'\n  // @ts-expect-error — polymorphic ref across span/div is safe here\n  return <Comp ref={ref} className={cx(styles.leading, className)} {...rest} />\n})\n\n/** Title (the direct text) and an optional `List.Description` below it. */\nconst ListContent = forwardRef<HTMLElement, HTMLAttributes<HTMLElement>>(function ListContent(\n  { className, ...rest },\n  ref,\n) {\n  const Comp = useContext(RowIsControl) ? 'span' : 'div'\n  // @ts-expect-error — polymorphic ref across span/div is safe here\n  return <Comp ref={ref} className={cx(styles.content, className)} {...rest} />\n})\n\nconst ListDescription = forwardRef<HTMLElement, HTMLAttributes<HTMLElement>>(\n  function ListDescription({ className, ...rest }, ref) {\n    const Comp = useContext(RowIsControl) ? 'span' : 'div'\n    // @ts-expect-error — polymorphic ref across span/div is safe here\n    return <Comp ref={ref} className={cx(styles.description, className)} {...rest} />\n  },\n)\n\n/** Value, meta or actions at the end of the row. Numbers are tabular. */\nconst ListTrailing = forwardRef<HTMLElement, HTMLAttributes<HTMLElement>>(function ListTrailing(\n  { className, ...rest },\n  ref,\n) {\n  const Comp = useContext(RowIsControl) ? 'span' : 'div'\n  // @ts-expect-error — polymorphic ref across span/div is safe here\n  return <Comp ref={ref} className={cx(styles.trailing, className)} {...rest} />\n})\n\nexport const List = Object.assign(ListRoot, {\n  Item: ListItem,\n  Leading: ListLeading,\n  Content: ListContent,\n  Description: ListDescription,\n  Trailing: ListTrailing,\n})\n"],"mappings":";;;;;;AAwDA,IAAME,IAAWC,EAAwC,SACvD,EAAE,aAAU,IAAM,aAAU,WAAW,IAAIC,IAAO,MAAM,aAAU,QAAQ,cAAW,GAAGC,KACxF,GACA;CACA,OACE,kBAACD,GAAD;EAEO;EACL,MAAK;EACL,WAAWE,EAAGN,EAAO,MAAMO,CAAS;EACpC,gBAAcC,KAAW,KAAA;EACzB,gBAAcC;EACd,gBAAcC,MAAY,SAAS,KAAA,IAAYA;EAC/C,GAAIL;CACL,CAAA;AAEL,CAAC,GAMKM,IAAeC,EAAc,EAAK,GAsBlCC,IAAWV,EAAyC,SACxD,EACE,iBAAc,IACd,aAAU,IACV,cAAW,IACX,iBAAc,IACd,WAAQ,IACR,UACA,cACA,aACA,GAAGE,KAEL,GACA;CACA,IAAMS,IAAMC,IAAUC,EAAK,OAAO;CAClC,OACE,kBAAC,MAAD;EACO;EACL,WAAWV,EAAGN,EAAO,MAAMO,CAAS;EACpC,oBAAkBU,KAAeF,KAAW,KAAA;EAC5C,iBAAeG,KAAY,KAAA;EAC3B,oBAAkBC,KAAe,KAAA;EACjC,cAAYC,KAAS,KAAA;EACrB,cAAYC;EACZ,GAAIhB;EAEJ,UAAA,kBAACM,EAAa,UAAd;GAAuB,OAAOI;GAC5B,UAAA,kBAACD,GAAD;IAAK,WAAWd,EAAO;IAAM;GAAc,CAAA;EACtB,CAAA;CACrB,CAAA;AAER,CAAC,GAGKsB,IAAcnB,EAAqD,SACvE,EAAE,cAAW,GAAGE,KAChB,GACA;CACA,IAAMD,IAAOmB,EAAWZ,CAAY,IAAI,SAAS;CAEjD,OAAO,kBAACP,GAAD;EAAW;EAAK,WAAWE,EAAGN,EAAO,SAASO,CAAS;EAAG,GAAIF;CAAO,CAAA;AAC9E,CAAC,GAGKmB,IAAcrB,EAAqD,SACvE,EAAE,cAAW,GAAGE,KAChB,GACA;CACA,IAAMD,IAAOmB,EAAWZ,CAAY,IAAI,SAAS;CAEjD,OAAO,kBAACP,GAAD;EAAW;EAAK,WAAWE,EAAGN,EAAO,SAASO,CAAS;EAAG,GAAIF;CAAO,CAAA;AAC9E,CAAC,GAEKoB,IAAkBtB,EACtB,SAAyB,EAAE,cAAW,GAAGE,KAAQ,GAAK;CACpD,IAAMD,IAAOmB,EAAWZ,CAAY,IAAI,SAAS;CAEjD,OAAO,kBAACP,GAAD;EAAW;EAAK,WAAWE,EAAGN,EAAO,aAAaO,CAAS;EAAG,GAAIF;CAAO,CAAA;AAClF,CACF,GAGMqB,IAAevB,EAAqD,SACxE,EAAE,cAAW,GAAGE,KAChB,GACA;CACA,IAAMD,IAAOmB,EAAWZ,CAAY,IAAI,SAAS;CAEjD,OAAO,kBAACP,GAAD;EAAW;EAAK,WAAWE,EAAGN,EAAO,UAAUO,CAAS;EAAG,GAAIF;CAAO,CAAA;AAC/E,CAAC,GAEYsB,IAAO,OAAO,OAAOzB,GAAU;CAC1C,MAAMW;CACN,SAASS;CACT,SAASE;CACT,aAAaC;CACb,UAAUC;AACZ,CAAC"}

package/dist/components/display/List/List.module.js.map

@@ -1 +1 @@
-{"version":3,"file":"List.module.js","names":["list","item","row","leading","content","description","trailing","List_module_default"],"sources":["../../../../src/components/display/List/List.module.css"],"sourcesContent":["/*\n * Component tokens (themes may set any of these on [data-theme]):\n *   --list-inset         default var(--space-2) — row padding-inline (room for fills)\n *   --list-row-radius    default var(--radius-field) — hover/selected/highlighted fill\n *   --list-trailing-size default: the row's text size (same as the title)\n *   --list-rail-width    default var(--space-1) — the categorical rail of a `color` row\n *   --highlight-tone-{positive,caution,critical,info}-text, --highlight-accent-text\n *                        tone text inside a highlighted row (shared with Table)\n *\n * Structure: li.item > .row (a div, or the asChild link/button) > slots. The row carries\n * padding, hover and focus so a linked row is one target edge to edge. Slots are divs, so\n * block components (Stat, Stack, a sized Media) fit in them, and spans inside an asChild row,\n * the only content a button may hold.\n */\n.list {\n  display: flex;\n  flex-direction: column;\n  margin: 0;\n  padding: 0;\n  list-style: none;\n  font-family: var(--font-text);\n  color: var(--color-ink);\n}\n\n.item {\n  --_py: var(--space-3);\n  --_fill: transparent;\n  --_fill-ink: inherit;\n\n  position: relative;\n  min-inline-size: 0;\n}\n.list[data-density='compact'] > .item {\n  --_py: var(--space-2);\n}\n\n.list[data-divided] > .item + .item {\n  border-block-start: var(--border-width) solid var(--color-line);\n}\n/* A filled row doesn't need rules either side — the fill is its edge. */\n.list[data-divided] > .item:is([data-highlighted], [data-selected]),\n.list[data-divided] > .item:is([data-highlighted], [data-selected]) + .item {\n  border-block-start-color: transparent;\n}\n\n.row {\n  display: flex;\n  align-items: center;\n  gap: var(--space-3);\n  inline-size: 100%;\n  min-inline-size: 0;\n  margin: 0;\n  padding-block: var(--_py);\n  padding-inline: var(--list-inset, var(--space-2));\n  border: 0;\n  border-radius: var(--list-row-radius, var(--radius-field));\n  background: var(--_fill);\n  color: var(--_fill-ink);\n  font: inherit;\n  text-align: start;\n  text-decoration: none;\n  transition: background-color var(--dur-1) var(--ease-out);\n}\n\n.item[data-selected] {\n  --_fill: var(--color-accent-soft);\n  --_fill-ink: var(--color-ink);\n}\n.item[data-highlighted] {\n  --_fill: var(--color-highlight);\n  --_fill-ink: var(--color-highlight-ink);\n  --_band-positive: var(\n    --highlight-tone-positive-text,\n    color-mix(in oklab, var(--tone-positive-text) 75%, var(--color-highlight-ink))\n  );\n  --_band-caution: var(\n    --highlight-tone-caution-text,\n    color-mix(in oklab, var(--tone-caution-text) 75%, var(--color-highlight-ink))\n  );\n  --_band-critical: var(\n    --highlight-tone-critical-text,\n    color-mix(in oklab, var(--tone-critical-text) 75%, var(--color-highlight-ink))\n  );\n  --_band-info: var(\n    --highlight-tone-info-text,\n    color-mix(in oklab, var(--tone-info-text) 75%, var(--color-highlight-ink))\n  );\n  --_band-accent: var(\n    --highlight-accent-text,\n    color-mix(in oklab, var(--color-accent-text) 75%, var(--color-highlight-ink))\n  );\n}\n\n/*\n * A filled row re-points the colour roles for its content, so a muted description, a\n * tone-coloured Numeral or a LiveIndicator stays legible on the fill (gold in Fiesta\n * night). The item publishes fill/ink under private names and the row swaps the roles —\n * redefining a role from itself on one element would be a var() cycle (see Section).\n */\n.item:is([data-highlighted], [data-selected]) > .row {\n  --color-ink: var(--_fill-ink);\n  --color-ink-muted: color-mix(in oklab, var(--_fill-ink), var(--_fill) 25%);\n  --color-ink-subtle: color-mix(in oklab, var(--_fill-ink), var(--_fill) 35%);\n}\n.item[data-highlighted] > .row {\n  --tone-positive-text: var(--_band-positive);\n  --tone-caution-text: var(--_band-caution);\n  --tone-critical-text: var(--_band-critical);\n  --tone-info-text: var(--_band-info);\n  --color-accent-text: var(--_band-accent);\n  /* Soft fills (a soft Badge or Tag) tint the band, like Section's accent band, so the\n     re-pointed tone texts above stay legible on them in every mode. */\n  --tone-positive-soft: color-mix(in oklab, var(--_band-positive) 8%, var(--_fill));\n  --tone-caution-soft: color-mix(in oklab, var(--_band-caution) 8%, var(--_fill));\n  --tone-critical-soft: color-mix(in oklab, var(--_band-critical) 8%, var(--_fill));\n  --tone-info-soft: color-mix(in oklab, var(--_band-info) 8%, var(--_fill));\n  --color-accent-soft: color-mix(in oklab, var(--_band-accent) 8%, var(--_fill));\n}\n\n.item[data-interactive] > .row {\n  cursor: pointer;\n}\n\n/* Muted: out of play. The title drops to the muted step, which still clears AA. */\n.item[data-muted] > .row {\n  --color-ink: var(--color-ink-muted);\n\n  color: var(--color-ink-muted);\n}\n\n/* A categorical rail in the row's start inset: whose row it is, in their Tag's colour. */\n.item[data-color]::before {\n  content: '';\n  position: absolute;\n  inset-block: var(--space-1);\n  inset-inline-start: 0;\n  inline-size: var(--list-rail-width, var(--space-1));\n  border-radius: var(--radius-chip);\n  background: var(--_cat);\n}\n.item[data-color='1'] {\n  --_cat: var(--color-cat-1);\n}\n.item[data-color='2'] {\n  --_cat: var(--color-cat-2);\n}\n.item[data-color='3'] {\n  --_cat: var(--color-cat-3);\n}\n.item[data-color='4'] {\n  --_cat: var(--color-cat-4);\n}\n.item[data-color='5'] {\n  --_cat: var(--color-cat-5);\n}\n.item[data-color='6'] {\n  --_cat: var(--color-cat-6);\n}\n.item[data-color='7'] {\n  --_cat: var(--color-cat-7);\n}\n.item[data-color='8'] {\n  --_cat: var(--color-cat-8);\n}\n.item[data-color] > .row {\n  padding-inline-start: calc(var(--list-inset, var(--space-2)) + var(--space-2));\n}\n@media (hover: hover) {\n  .item[data-interactive]:not([data-highlighted], [data-selected]) > .row:hover {\n    background: var(--color-surface-sunken);\n  }\n  .item[data-interactive]:is([data-highlighted], [data-selected]) > .row:hover {\n    background: color-mix(in oklch, var(--_fill) 88%, var(--color-ink));\n  }\n}\n.row:focus-visible {\n  outline: 2px solid var(--color-focus);\n  outline-offset: -2px;\n}\n\n/* ── Slots ───────────────────────────────────────────────────────────────── */\n\n.leading {\n  display: inline-flex;\n  flex: none;\n  align-items: center;\n  justify-content: flex-end;\n  min-inline-size: 2ch;\n  color: var(--color-ink-muted);\n  font-family: var(--font-numeric);\n  font-stretch: var(--numeric-stretch);\n  font-weight: var(--label-weight);\n  font-variant-numeric: tabular-nums lining-nums;\n  font-size: var(--text-md);\n}\n.item[data-highlighted] .leading {\n  color: inherit;\n}\n\n.content {\n  display: flex;\n  flex: 1 1 auto;\n  flex-direction: column;\n  gap: calc(var(--space-1) / 2);\n  min-inline-size: 0;\n  font-size: var(--text-md);\n  font-weight: var(--label-weight);\n  line-height: var(--leading-snug);\n  /* Wrap between words; break inside one only when a single word can't fit the column. */\n  overflow-wrap: break-word;\n}\n\n.description {\n  color: var(--color-ink-muted);\n  font-size: var(--text-sm);\n  font-weight: 400;\n}\n\n.trailing {\n  --stat-align: end;\n  --stat-container-type: normal;\n\n  display: inline-flex;\n  flex: none;\n  align-items: center;\n  justify-content: flex-end;\n  gap: var(--space-2);\n  margin-inline-start: auto;\n  text-align: end;\n  /*\n   * The row's text face and size, with tabular figures: a bare \"7 tasks\" sits level with the\n   * title instead of looming in the numeric face. Put a <Numeral>/<Amount> here for figures\n   * that should carry the numeric face (receipt mono in Ledger).\n   */\n  font-variant-numeric: tabular-nums lining-nums;\n  font-size: var(--list-trailing-size, var(--text-md));\n  font-weight: var(--label-weight);\n  line-height: var(--leading-snug);\n  white-space: nowrap;\n}\n"],"mappings":""}
+{"version":3,"file":"List.module.js","names":["list","item","row","leading","content","description","trailing","List_module_default"],"sources":["../../../../src/components/display/List/List.module.css"],"sourcesContent":["/*\n * Component tokens (themes may set any of these on [data-theme]):\n *   --list-inset         default var(--space-2), var(--space-4) on a surface — row padding-inline\n *   --list-row-radius    default var(--radius-field), square on a surface — row fills\n *   --list-trailing-size default: the row's text size (same as the title)\n *   --list-rail-width    default var(--space-1) — the categorical rail of a `color` row\n *   --list-surface-bg    default var(--color-surface), var(--color-surface-raised) when `raised`\n *   --list-surface-radius default var(--radius-surface) — the sheet of a `surface` list\n *   --highlight-tone-{positive,caution,critical,info}-text, --highlight-accent-text\n *                        tone text inside a highlighted row (shared with Table)\n *\n * Structure: li.item > .row (a div, or the asChild link/button) > slots. The row carries\n * padding, hover and focus so a linked row is one target edge to edge. Slots are divs, so\n * block components (Stat, Stack, a sized Media) fit in them, and spans inside an asChild row,\n * the only content a button may hold.\n */\n.list {\n  --_inset: var(--space-2);\n  --_row-radius: var(--radius-field);\n\n  display: flex;\n  flex-direction: column;\n  margin: 0;\n  padding: 0;\n  list-style: none;\n  font-family: var(--font-text);\n  color: var(--color-ink);\n}\n\n/*\n * On a surface: the whole list on one sheet, with Card's edges (`outline` for surface,\n * `raised` for raised), so rows read as rows on a textured or busy canvas. Rows run edge to\n * edge and the sheet clips them to its radius, so a fill is a band across the sheet, and a\n * categorical rail sits flush with the sheet's inner edge and follows its corners on the\n * first and last rows. Rows take a wider inset so text clears the edge.\n */\n.list[data-surface] {\n  --_inset: var(--space-4);\n  --_row-radius: 0px;\n\n  overflow: hidden;\n  border: var(--border-width) solid var(--color-line);\n  border-radius: var(--list-surface-radius, var(--radius-surface));\n  background: var(--list-surface-bg, var(--color-surface));\n}\n.list[data-surface='raised'] {\n  border-color: var(--color-line-strong);\n  background: var(--list-surface-bg, var(--color-surface-raised));\n  box-shadow: var(--shadow-surface);\n}\n\n.item {\n  --_py: var(--space-3);\n  --_fill: transparent;\n  --_fill-ink: inherit;\n\n  position: relative;\n  min-inline-size: 0;\n}\n.list[data-density='compact'] > .item {\n  --_py: var(--space-2);\n}\n\n.list[data-divided] > .item + .item {\n  border-block-start: var(--border-width) solid var(--color-line);\n}\n/* A filled row doesn't need rules either side — the fill is its edge. */\n.list[data-divided] > .item:is([data-highlighted], [data-selected]),\n.list[data-divided] > .item:is([data-highlighted], [data-selected]) + .item {\n  border-block-start-color: transparent;\n}\n\n.row {\n  display: flex;\n  align-items: center;\n  gap: var(--space-3);\n  inline-size: 100%;\n  min-inline-size: 0;\n  margin: 0;\n  padding-block: var(--_py);\n  padding-inline: var(--list-inset, var(--_inset));\n  border: 0;\n  border-radius: var(--list-row-radius, var(--_row-radius));\n  background: var(--_fill);\n  color: var(--_fill-ink);\n  font: inherit;\n  text-align: start;\n  text-decoration: none;\n  transition: background-color var(--dur-1) var(--ease-out);\n}\n\n.item[data-selected] {\n  --_fill: var(--color-accent-soft);\n  --_fill-ink: var(--color-ink);\n}\n.item[data-highlighted] {\n  --_fill: var(--color-highlight);\n  --_fill-ink: var(--color-highlight-ink);\n  --_band-positive: var(\n    --highlight-tone-positive-text,\n    color-mix(in oklab, var(--tone-positive-text) 75%, var(--color-highlight-ink))\n  );\n  --_band-caution: var(\n    --highlight-tone-caution-text,\n    color-mix(in oklab, var(--tone-caution-text) 75%, var(--color-highlight-ink))\n  );\n  --_band-critical: var(\n    --highlight-tone-critical-text,\n    color-mix(in oklab, var(--tone-critical-text) 75%, var(--color-highlight-ink))\n  );\n  --_band-info: var(\n    --highlight-tone-info-text,\n    color-mix(in oklab, var(--tone-info-text) 75%, var(--color-highlight-ink))\n  );\n  --_band-accent: var(\n    --highlight-accent-text,\n    color-mix(in oklab, var(--color-accent-text) 75%, var(--color-highlight-ink))\n  );\n}\n\n/*\n * A filled row re-points the colour roles for its content, so a muted description, a\n * tone-coloured Numeral or a LiveIndicator stays legible on the fill (gold in Fiesta\n * night). The item publishes fill/ink under private names and the row swaps the roles —\n * redefining a role from itself on one element would be a var() cycle (see Section).\n */\n.item:is([data-highlighted], [data-selected]) > .row {\n  --color-ink: var(--_fill-ink);\n  --color-ink-muted: color-mix(in oklab, var(--_fill-ink), var(--_fill) 25%);\n  --color-ink-subtle: color-mix(in oklab, var(--_fill-ink), var(--_fill) 35%);\n}\n.item[data-highlighted] > .row {\n  --tone-positive-text: var(--_band-positive);\n  --tone-caution-text: var(--_band-caution);\n  --tone-critical-text: var(--_band-critical);\n  --tone-info-text: var(--_band-info);\n  --color-accent-text: var(--_band-accent);\n  /* Soft fills (a soft Badge or Tag) tint the band, like Section's accent band, so the\n     re-pointed tone texts above stay legible on them in every mode. */\n  --tone-positive-soft: color-mix(in oklab, var(--_band-positive) 8%, var(--_fill));\n  --tone-caution-soft: color-mix(in oklab, var(--_band-caution) 8%, var(--_fill));\n  --tone-critical-soft: color-mix(in oklab, var(--_band-critical) 8%, var(--_fill));\n  --tone-info-soft: color-mix(in oklab, var(--_band-info) 8%, var(--_fill));\n  --color-accent-soft: color-mix(in oklab, var(--_band-accent) 8%, var(--_fill));\n}\n\n.item[data-interactive] > .row {\n  cursor: pointer;\n}\n\n/* Muted: out of play. The title drops to the muted step, which still clears AA. */\n.item[data-muted] > .row {\n  --color-ink: var(--color-ink-muted);\n\n  color: var(--color-ink-muted);\n}\n\n/* A categorical rail in the row's start inset: whose row it is, in their Tag's colour. */\n.item[data-color]::before {\n  content: '';\n  position: absolute;\n  inset-block: var(--space-1);\n  inset-inline-start: 0;\n  inline-size: var(--list-rail-width, var(--space-1));\n  border-radius: var(--radius-chip);\n  background: var(--_cat);\n}\n/* On a sheet the rail is an edge of the row: full height, square, and over the rule above it. */\n.list[data-surface] > .item[data-color]::before {\n  inset-block: 0;\n  border-radius: 0;\n}\n.list[data-surface][data-divided] > .item + .item[data-color]::before {\n  inset-block-start: calc(var(--border-width) * -1);\n}\n.item[data-color='1'] {\n  --_cat: var(--color-cat-1);\n}\n.item[data-color='2'] {\n  --_cat: var(--color-cat-2);\n}\n.item[data-color='3'] {\n  --_cat: var(--color-cat-3);\n}\n.item[data-color='4'] {\n  --_cat: var(--color-cat-4);\n}\n.item[data-color='5'] {\n  --_cat: var(--color-cat-5);\n}\n.item[data-color='6'] {\n  --_cat: var(--color-cat-6);\n}\n.item[data-color='7'] {\n  --_cat: var(--color-cat-7);\n}\n.item[data-color='8'] {\n  --_cat: var(--color-cat-8);\n}\n.item[data-color] > .row {\n  padding-inline-start: calc(var(--list-inset, var(--_inset)) + var(--space-2));\n}\n@media (hover: hover) {\n  .item[data-interactive]:not([data-highlighted], [data-selected]) > .row:hover {\n    background: var(--color-surface-sunken);\n  }\n  .item[data-interactive]:is([data-highlighted], [data-selected]) > .row:hover {\n    background: color-mix(in oklch, var(--_fill) 88%, var(--color-ink));\n  }\n}\n.row:focus-visible {\n  outline: 2px solid var(--color-focus);\n  outline-offset: -2px;\n}\n\n/* ── Slots ───────────────────────────────────────────────────────────────── */\n\n.leading {\n  display: inline-flex;\n  flex: none;\n  align-items: center;\n  justify-content: flex-end;\n  min-inline-size: 2ch;\n  color: var(--color-ink-muted);\n  font-family: var(--font-numeric);\n  font-stretch: var(--numeric-stretch);\n  font-weight: var(--label-weight);\n  font-variant-numeric: tabular-nums lining-nums;\n  font-size: var(--text-md);\n}\n.item[data-highlighted] .leading {\n  color: inherit;\n}\n\n.content {\n  display: flex;\n  flex: 1 1 auto;\n  flex-direction: column;\n  gap: calc(var(--space-1) / 2);\n  min-inline-size: 0;\n  font-size: var(--text-md);\n  font-weight: var(--label-weight);\n  line-height: var(--leading-snug);\n  /* Wrap between words; break inside one only when a single word can't fit the column. */\n  overflow-wrap: break-word;\n}\n\n.description {\n  color: var(--color-ink-muted);\n  font-size: var(--text-sm);\n  font-weight: 400;\n}\n\n.trailing {\n  --stat-align: end;\n  --stat-container-type: normal;\n\n  display: inline-flex;\n  flex: none;\n  align-items: center;\n  justify-content: flex-end;\n  gap: var(--space-2);\n  margin-inline-start: auto;\n  text-align: end;\n  /*\n   * The row's text face and size, with tabular figures: a bare \"7 tasks\" sits level with the\n   * title instead of looming in the numeric face. Put a <Numeral>/<Amount> here for figures\n   * that should carry the numeric face (receipt mono in Ledger).\n   */\n  font-variant-numeric: tabular-nums lining-nums;\n  font-size: var(--list-trailing-size, var(--text-md));\n  font-weight: var(--label-weight);\n  line-height: var(--leading-snug);\n  white-space: nowrap;\n}\n"],"mappings":""}

package/dist/components/display/List/index.d.ts

@@ -1,2 +1,2 @@
 export { List } from './List.js';
-export type { ListProps, ListItemProps, ListDensity, ListElement } from './List.js';
+export type { ListProps, ListItemProps, ListDensity, ListElement, ListSurface } from './List.js';

package/dist/components/display/Media/Media.d.ts

@@ -17,6 +17,8 @@ export interface MediaProps extends Omit<HTMLAttributes<HTMLElement>, 'children'
     /**
      * A fixed height, for a small image that sits inline beside text (a flag by a name, a logo
      * in a row). The width follows `ratio`, or the image's own ratio when `ratio` is `auto`.
+     * With a fixed `ratio`, the image also gets `width` and `height` attributes, so its box is
+     * known before it loads; with `auto`, pass them in `imgProps`.
      * Default: none, so the frame fills its container.
      */
     size?: MediaSize;

package/dist/components/display/Media/Media.js

@@ -3,49 +3,65 @@ import t from "./Media.module.js";
 import { forwardRef as n, useEffect as r, useRef as i, useState as a } from "react";
 import { jsx as o, jsxs as s } from "react/jsx-runtime";
 //#region src/components/display/Media/Media.tsx
-var c = n(function({ src: n, alt: c, ratio: l = "auto", fit: u = "cover", radius: d = "media", size: f, dimmed: p = !1, caption: m, fallback: h, loading: g = "lazy", imgProps: _, className: v, ...y }, b) {
-	let [x, S] = a(!1), C = i(null);
+var c = {
+	xs: 16,
+	sm: 20,
+	md: 24,
+	lg: 32,
+	xl: 96
+};
+function l(e, t) {
+	if (e === void 0 || t === "auto") return {};
+	let [n, r] = t.split("/").map(Number), i = c[e];
+	return {
+		width: Math.round(i * n / r),
+		height: i
+	};
+}
+var u = n(function({ src: n, alt: c, ratio: u = "auto", fit: d = "cover", radius: f = "media", size: p, dimmed: m = !1, caption: h, fallback: g, loading: _ = "lazy", imgProps: v, className: y, ...b }, x) {
+	let [S, C] = a(!1), w = i(null);
 	r(() => {
-		let e = C.current;
-		S(!!(e?.complete && e.naturalWidth === 0 && typeof e.currentSrc == "string" && e.currentSrc !== ""));
+		let e = w.current;
+		C(!!(e?.complete && e.naturalWidth === 0 && typeof e.currentSrc == "string" && e.currentSrc !== ""));
 	}, [n]);
-	let w = m === void 0 ? f ? "span" : "div" : "figure", T = f ? "span" : "div";
-	return /* @__PURE__ */ s(w, {
-		ref: b,
-		className: e(t.media, v),
-		"data-ratio": l,
-		"data-fit": u,
-		"data-radius": d,
-		"data-size": f,
-		"data-dimmed": p || void 0,
-		"data-failed": x || void 0,
-		...y,
-		children: [/* @__PURE__ */ o(T, {
+	let T = h === void 0 ? p ? "span" : "div" : "figure", E = p ? "span" : "div";
+	return /* @__PURE__ */ s(T, {
+		ref: x,
+		className: e(t.media, y),
+		"data-ratio": u,
+		"data-fit": d,
+		"data-radius": f,
+		"data-size": p,
+		"data-dimmed": m || void 0,
+		"data-failed": S || void 0,
+		...b,
+		children: [/* @__PURE__ */ o(E, {
 			className: t.frame,
-			children: x ? /* @__PURE__ */ o(T, {
+			children: S ? /* @__PURE__ */ o(E, {
 				className: t.fallback,
 				role: c ? "img" : void 0,
 				"aria-label": c || void 0,
-				children: h
+				children: g
 			}) : /* @__PURE__ */ o("img", {
-				ref: C,
+				ref: w,
 				className: t.image,
 				src: n,
 				alt: c,
-				loading: g,
+				loading: _,
 				decoding: "async",
 				onError: () => {
-					S(!0);
+					C(!0);
 				},
-				..._
+				...l(p, u),
+				...v
 			})
-		}), m === void 0 ? null : /* @__PURE__ */ o("figcaption", {
+		}), h === void 0 ? null : /* @__PURE__ */ o("figcaption", {
 			className: t.caption,
-			children: m
+			children: h
 		})]
 	});
 });
 //#endregion
-export { c as Media };
+export { u as Media };
 
 //# sourceMappingURL=Media.js.map

package/dist/components/display/Media/Media.js.map

@@ -1 +1 @@
-{"version":3,"file":"Media.js","names":["styles","Media_module_default","Media","forwardRef","rest","failed","setFailed","useState","imgRef","useRef","img","src","Root","caption","size","Box","cx","className","ratio","fit","radius","dimmed","alt","fallback","imgProps"],"sources":["../../../../src/components/display/Media/Media.tsx"],"sourcesContent":["import {\n  forwardRef,\n  useEffect,\n  useRef,\n  useState,\n  type HTMLAttributes,\n  type ImgHTMLAttributes,\n  type ReactNode,\n} from 'react'\nimport { cx } from '#utils/cx'\nimport styles from './Media.module.css'\n\nexport type MediaRatio = '1/1' | '4/3' | '3/2' | '16/9' | '21/9' | '3/4' | '2/3' | 'auto'\nexport type MediaFit = 'cover' | 'contain'\nexport type MediaRadius = 'none' | 'media' | 'surface'\n/** Fixed heights for inline thumbnails: about 16, 20, 24, 32 and 96px. */\nexport type MediaSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl'\n\nexport interface MediaProps extends Omit<HTMLAttributes<HTMLElement>, 'children'> {\n  src: string\n  /** Required. Describe the image; pass `\"\"` only when it's purely decorative. */\n  alt: string\n  /** Frame ratio. The image is fitted inside. Default `auto` (the image's own ratio). */\n  ratio?: MediaRatio\n  /** Default `cover`. Use `contain` for logos, diagrams and screenshots that must not crop. */\n  fit?: MediaFit\n  /** Corner role. Default `media`. */\n  radius?: MediaRadius\n  /**\n   * A fixed height, for a small image that sits inline beside text (a flag by a name, a logo\n   * in a row). The width follows `ratio`, or the image's own ratio when `ratio` is `auto`.\n   * Default: none, so the frame fills its container.\n   */\n  size?: MediaSize\n  /**\n   * Out of play: the image fades toward grey but stays recognisable, like a knocked-out\n   * team's flag or a past event's photo. Pair it with a muted `List.Item` or `Table.Row`.\n   */\n  dimmed?: boolean\n  /** Renders a `<figure>` with this as its `<figcaption>`. */\n  caption?: ReactNode\n  /** Shown inside the frame if the image fails to load. Default: an empty sunken frame. */\n  fallback?: ReactNode\n  /** Default `lazy`. Use `eager` for the image above the fold. */\n  loading?: 'lazy' | 'eager'\n  /** Extra attributes for the `<img>` (srcSet, sizes, width/height, fetchPriority). */\n  imgProps?: Omit<ImgHTMLAttributes<HTMLImageElement>, 'src' | 'alt' | 'loading'>\n}\n\n/**\n * A framed image with a fixed ratio, lazy loading, a caption, and a calm failure state.\n *\n * @remarks\n * `Media` frames an image: it holds a ratio while loading, fits the image, loads lazily, and when\n * the image fails it keeps its shape and shows a quiet fallback instead of a broken-image icon.\n *\n * @privateRemarks\n * A framed image: fixed ratio, fitted, lazy by default, with a caption and a graceful\n * failure state. Screenshots, company logos, scanned documents.\n *\n * <Media src=\"/images/dashboard.png\" alt=\"Revenue dashboard, September\" ratio=\"16/9\" caption=\"Dashboard, 2026\" />\n */\nexport const Media = forwardRef<HTMLElement, MediaProps>(function Media(\n  {\n    src,\n    alt,\n    ratio = 'auto',\n    fit = 'cover',\n    radius = 'media',\n    size,\n    dimmed = false,\n    caption,\n    fallback,\n    loading = 'lazy',\n    imgProps,\n    className,\n    ...rest\n  },\n  ref,\n) {\n  const [failed, setFailed] = useState(false)\n  const imgRef = useRef<HTMLImageElement>(null)\n\n  // Reset when the source changes; also catch an error that fired before hydration.\n  useEffect(() => {\n    const img = imgRef.current\n    setFailed(\n      Boolean(\n        img?.complete &&\n        img.naturalWidth === 0 &&\n        typeof img.currentSrc === 'string' &&\n        img.currentSrc !== '',\n      ),\n    )\n  }, [src])\n\n  // A sized thumbnail is phrasing content (spans), so it can sit in a button or a line of text.\n  const Root = caption !== undefined ? 'figure' : size ? 'span' : 'div'\n  const Box = size ? 'span' : 'div'\n  return (\n    <Root\n      // @ts-expect-error — polymorphic ref across figure/div is safe here\n      ref={ref}\n      className={cx(styles.media, className)}\n      data-ratio={ratio}\n      data-fit={fit}\n      data-radius={radius}\n      data-size={size}\n      data-dimmed={dimmed || undefined}\n      data-failed={failed || undefined}\n      {...rest}\n    >\n      <Box className={styles.frame}>\n        {failed ? (\n          <Box\n            className={styles.fallback}\n            role={alt ? 'img' : undefined}\n            aria-label={alt || undefined}\n          >\n            {fallback}\n          </Box>\n        ) : (\n          <img\n            ref={imgRef}\n            className={styles.image}\n            src={src}\n            alt={alt}\n            loading={loading}\n            decoding=\"async\"\n            onError={() => {\n              setFailed(true)\n            }}\n            {...imgProps}\n          />\n        )}\n      </Box>\n      {caption !== undefined ? <figcaption className={styles.caption}>{caption}</figcaption> : null}\n    </Root>\n  )\n})\n"],"mappings":";;;;;AA8DA,IAAaE,IAAQC,EAAoC,SACvD,EACE,QACA,QACA,WAAQ,QACR,SAAM,SACN,YAAS,SACT,SACA,YAAS,IACT,YACA,aACA,aAAU,QACV,aACA,cACA,GAAGC,KAEL,GACA;CACA,IAAM,CAACC,GAAQC,KAAaC,EAAS,EAAK,GACpCC,IAASC,EAAyB,IAAI;CAG5C,QAAgB;EACd,IAAMC,IAAMF,EAAO;EACnB,EACE,GACEE,GAAK,YACLA,EAAI,iBAAiB,KACrB,OAAOA,EAAI,cAAe,YAC1BA,EAAI,eAAe,GAEvB;CACF,GAAG,CAACC,CAAG,CAAC;CAGR,IAAMC,IAAOC,MAAY,KAAA,IAAuBC,IAAO,SAAS,QAA3B,UAC/BC,IAAMD,IAAO,SAAS;CAC5B,OACE,kBAACF,GAAD;EAEO;EACL,WAAWI,EAAGhB,EAAO,OAAOiB,CAAS;EACrC,cAAYC;EACZ,YAAUC;EACV,eAAaC;EACb,aAAWN;EACX,eAAaO,KAAU,KAAA;EACvB,eAAahB,KAAU,KAAA;EACvB,GAAID;EAVN,UAAA,CAYE,kBAACW,GAAD;GAAK,WAAWf,EAAO;GACpB,UAAAK,IACC,kBAACU,GAAD;IACE,WAAWf,EAAO;IAClB,MAAMsB,IAAM,QAAQ,KAAA;IACpB,cAAYA,KAAO,KAAA;IAElB,UAAAC;GACE,CAAA,IAEL,kBAAC,OAAD;IACE,KAAKf;IACL,WAAWR,EAAO;IACb;IACA;IACI;IACT,UAAS;IACT,eAAe;KACb,EAAU,EAAI;IAChB;IACA,GAAIwB;GACL,CAAA;EAEA,CAAA,GACJX,MAAY,KAAA,IAA4E,OAAhE,kBAAC,cAAD;GAAY,WAAWb,EAAO;GAAU,UAAAa;EAAoB,CAAA,CACjF;;AAEV,CAAC"}
+{"version":3,"file":"Media.js","names":["styles","Media_module_default","SIZE_PX","sizeHints","size","ratio","w","h","height","Media","forwardRef","rest","failed","setFailed","useState","imgRef","useRef","img","src","Root","caption","Box","cx","className","fit","radius","dimmed","alt","fallback","imgProps"],"sources":["../../../../src/components/display/Media/Media.tsx"],"sourcesContent":["import {\n  forwardRef,\n  useEffect,\n  useRef,\n  useState,\n  type HTMLAttributes,\n  type ImgHTMLAttributes,\n  type ReactNode,\n} from 'react'\nimport { cx } from '#utils/cx'\nimport styles from './Media.module.css'\n\nexport type MediaRatio = '1/1' | '4/3' | '3/2' | '16/9' | '21/9' | '3/4' | '2/3' | 'auto'\nexport type MediaFit = 'cover' | 'contain'\nexport type MediaRadius = 'none' | 'media' | 'surface'\n/** Fixed heights for inline thumbnails: about 16, 20, 24, 32 and 96px. */\nexport type MediaSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl'\n\n/** Nominal heights in px, for the image's width/height hints; the CSS sets the real size. */\nconst SIZE_PX: Record<MediaSize, number> = { xs: 16, sm: 20, md: 24, lg: 32, xl: 96 }\n\n/**\n * The width and height attributes a sized image carries, so the browser knows its box before it\n * loads (and audits don't flag it). Only known with a fixed ratio: an `auto` frame takes the\n * image's own ratio, so pass `imgProps.width`/`height` there.\n */\nfunction sizeHints(size: MediaSize | undefined, ratio: MediaRatio) {\n  if (size === undefined || ratio === 'auto') return {}\n  const [w, h] = ratio.split('/').map(Number) as [number, number]\n  const height = SIZE_PX[size]\n  return { width: Math.round((height * w) / h), height }\n}\n\nexport interface MediaProps extends Omit<HTMLAttributes<HTMLElement>, 'children'> {\n  src: string\n  /** Required. Describe the image; pass `\"\"` only when it's purely decorative. */\n  alt: string\n  /** Frame ratio. The image is fitted inside. Default `auto` (the image's own ratio). */\n  ratio?: MediaRatio\n  /** Default `cover`. Use `contain` for logos, diagrams and screenshots that must not crop. */\n  fit?: MediaFit\n  /** Corner role. Default `media`. */\n  radius?: MediaRadius\n  /**\n   * A fixed height, for a small image that sits inline beside text (a flag by a name, a logo\n   * in a row). The width follows `ratio`, or the image's own ratio when `ratio` is `auto`.\n   * With a fixed `ratio`, the image also gets `width` and `height` attributes, so its box is\n   * known before it loads; with `auto`, pass them in `imgProps`.\n   * Default: none, so the frame fills its container.\n   */\n  size?: MediaSize\n  /**\n   * Out of play: the image fades toward grey but stays recognisable, like a knocked-out\n   * team's flag or a past event's photo. Pair it with a muted `List.Item` or `Table.Row`.\n   */\n  dimmed?: boolean\n  /** Renders a `<figure>` with this as its `<figcaption>`. */\n  caption?: ReactNode\n  /** Shown inside the frame if the image fails to load. Default: an empty sunken frame. */\n  fallback?: ReactNode\n  /** Default `lazy`. Use `eager` for the image above the fold. */\n  loading?: 'lazy' | 'eager'\n  /** Extra attributes for the `<img>` (srcSet, sizes, width/height, fetchPriority). */\n  imgProps?: Omit<ImgHTMLAttributes<HTMLImageElement>, 'src' | 'alt' | 'loading'>\n}\n\n/**\n * A framed image with a fixed ratio, lazy loading, a caption, and a calm failure state.\n *\n * @remarks\n * `Media` frames an image: it holds a ratio while loading, fits the image, loads lazily, and when\n * the image fails it keeps its shape and shows a quiet fallback instead of a broken-image icon.\n *\n * @privateRemarks\n * A framed image: fixed ratio, fitted, lazy by default, with a caption and a graceful\n * failure state. Screenshots, company logos, scanned documents.\n *\n * <Media src=\"/images/dashboard.png\" alt=\"Revenue dashboard, September\" ratio=\"16/9\" caption=\"Dashboard, 2026\" />\n */\nexport const Media = forwardRef<HTMLElement, MediaProps>(function Media(\n  {\n    src,\n    alt,\n    ratio = 'auto',\n    fit = 'cover',\n    radius = 'media',\n    size,\n    dimmed = false,\n    caption,\n    fallback,\n    loading = 'lazy',\n    imgProps,\n    className,\n    ...rest\n  },\n  ref,\n) {\n  const [failed, setFailed] = useState(false)\n  const imgRef = useRef<HTMLImageElement>(null)\n\n  // Reset when the source changes; also catch an error that fired before hydration.\n  useEffect(() => {\n    const img = imgRef.current\n    setFailed(\n      Boolean(\n        img?.complete &&\n        img.naturalWidth === 0 &&\n        typeof img.currentSrc === 'string' &&\n        img.currentSrc !== '',\n      ),\n    )\n  }, [src])\n\n  // A sized thumbnail is phrasing content (spans), so it can sit in a button or a line of text.\n  const Root = caption !== undefined ? 'figure' : size ? 'span' : 'div'\n  const Box = size ? 'span' : 'div'\n  return (\n    <Root\n      // @ts-expect-error — polymorphic ref across figure/div is safe here\n      ref={ref}\n      className={cx(styles.media, className)}\n      data-ratio={ratio}\n      data-fit={fit}\n      data-radius={radius}\n      data-size={size}\n      data-dimmed={dimmed || undefined}\n      data-failed={failed || undefined}\n      {...rest}\n    >\n      <Box className={styles.frame}>\n        {failed ? (\n          <Box\n            className={styles.fallback}\n            role={alt ? 'img' : undefined}\n            aria-label={alt || undefined}\n          >\n            {fallback}\n          </Box>\n        ) : (\n          <img\n            ref={imgRef}\n            className={styles.image}\n            src={src}\n            alt={alt}\n            loading={loading}\n            decoding=\"async\"\n            onError={() => {\n              setFailed(true)\n            }}\n            {...sizeHints(size, ratio)}\n            {...imgProps}\n          />\n        )}\n      </Box>\n      {caption !== undefined ? <figcaption className={styles.caption}>{caption}</figcaption> : null}\n    </Root>\n  )\n})\n"],"mappings":";;;;;AAmBA,IAAME,IAAqC;CAAE,IAAI;CAAI,IAAI;CAAI,IAAI;CAAI,IAAI;CAAI,IAAI;AAAG;AAOpF,SAASC,EAAU,GAA6B,GAAmB;CACjE,IAAIC,MAAS,KAAA,KAAaC,MAAU,QAAQ,OAAO,CAAC;CACpD,IAAM,CAACC,GAAGC,KAAKF,EAAM,MAAM,GAAG,CAAC,CAAC,IAAI,MAAM,GACpCG,IAASN,EAAQE;CACvB,OAAO;EAAE,OAAO,KAAK,MAAOI,IAASF,IAAKC,CAAC;EAAG;CAAO;AACvD;AAgDA,IAAaE,IAAQC,EAAoC,SACvD,EACE,QACA,QACA,WAAQ,QACR,SAAM,SACN,YAAS,SACT,SACA,YAAS,IACT,YACA,aACA,aAAU,QACV,aACA,cACA,GAAGC,KAEL,GACA;CACA,IAAM,CAACC,GAAQC,KAAaC,EAAS,EAAK,GACpCC,IAASC,EAAyB,IAAI;CAG5C,QAAgB;EACd,IAAMC,IAAMF,EAAO;EACnB,EACE,GACEE,GAAK,YACLA,EAAI,iBAAiB,KACrB,OAAOA,EAAI,cAAe,YAC1BA,EAAI,eAAe,GAEvB;CACF,GAAG,CAACC,CAAG,CAAC;CAGR,IAAMC,IAAOC,MAAY,KAAA,IAAuBhB,IAAO,SAAS,QAA3B,UAC/BiB,IAAMjB,IAAO,SAAS;CAC5B,OACE,kBAACe,GAAD;EAEO;EACL,WAAWG,EAAGtB,EAAO,OAAOuB,CAAS;EACrC,cAAYlB;EACZ,YAAUmB;EACV,eAAaC;EACb,aAAWrB;EACX,eAAasB,KAAU,KAAA;EACvB,eAAad,KAAU,KAAA;EACvB,GAAID;EAVN,UAAA,CAYE,kBAACU,GAAD;GAAK,WAAWrB,EAAO;GACpB,UAAAY,IACC,kBAACS,GAAD;IACE,WAAWrB,EAAO;IAClB,MAAM2B,IAAM,QAAQ,KAAA;IACpB,cAAYA,KAAO,KAAA;IAElB,UAAAC;GACE,CAAA,IAEL,kBAAC,OAAD;IACE,KAAKb;IACL,WAAWf,EAAO;IACb;IACA;IACI;IACT,UAAS;IACT,eAAe;KACb,EAAU,EAAI;IAChB;IACA,GAAIG,EAAUC,GAAMC,CAAK;IACzB,GAAIwB;GACL,CAAA;EAEA,CAAA,GACJT,MAAY,KAAA,IAA4E,OAAhE,kBAAC,cAAD;GAAY,WAAWpB,EAAO;GAAU,UAAAoB;EAAoB,CAAA,CACjF;;AAEV,CAAC"}