@usefragments/ui 1.6.0 → 1.7.0

package/src/components/CodeBlock/CodeBlock.contract.json

@@ -1,16 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "CodeBlock",
-  "description": "Syntax-highlighted code display with copy functionality, theming, diff view, and collapsible sections",
+  "description": "Shows code with syntax colors, a copy button, and diff or collapse when you need them.",
   "category": "display",
-  "tags": [
-    "code",
-    "syntax",
-    "highlighting",
-    "documentation",
-    "developer",
-    "diff"
-  ],
+  "tags": ["code", "syntax", "highlighting", "documentation", "developer", "diff"],
   "status": "stable",
   "dependencies": [
     {
@@ -24,7 +17,7 @@
   "propsSummary": [
     "code: string (required)",
     "language: tsx|typescript|ts|javascript|js|jsx|bash|shell|css|scss|sass|json|html|xml|markdown|md|yaml|yml|python|py|ruby|go|rust|java|kotlin|swift|c|cpp|csharp|php|sql|graphql|diff|plaintext|text (default: tsx)",
-    "theme: synthwave-84|github-dark|github-light|one-dark-pro|dracula|nord|monokai|vitesse-dark|vitesse-light|min-dark|min-light (default: one-dark-pro)",
+    "theme: css-variables|synthwave-84|github-dark|github-light|one-dark-pro|dracula|nord|monokai|vitesse-dark|vitesse-light|min-dark|min-light (default: css-variables)",
     "showCopy: boolean (default: true)",
     "title: string",
     "filename: string",
@@ -96,10 +89,11 @@
     },
     "theme": {
       "type": "enum",
-      "description": "Syntax highlighting theme",
-      "default": "one-dark-pro",
+      "description": "Syntax highlighting theme. css-variables maps spans onto --fui-code-token-* so both themes stay readable.",
+      "default": "css-variables",
       "required": false,
       "values": [
+        "css-variables",
         "synthwave-84",
         "github-dark",
         "github-light",
@@ -190,6 +184,12 @@
       "default": "5",
       "required": false
     },
+    "collapseAction": {
+      "type": "\"lines\" | \"expand\"",
+      "description": "Collapse control copy: line-count bar, or a single Expand / Collapse control",
+      "default": "lines",
+      "required": false
+    },
     "compact": {
       "type": "boolean",
       "description": "Compact mode with reduced padding",
@@ -207,11 +207,7 @@
       "description": "Where to place the copy button when not using persistentCopy",
       "default": "auto",
       "required": false,
-      "values": [
-        "auto",
-        "header",
-        "overlay"
-      ]
+      "values": ["auto", "header", "overlay"]
     },
     "bg": {
       "type": "string",
@@ -226,118 +222,97 @@
   },
   "usage": {
     "when": [
-      "Displaying code examples in documentation",
-      "Showing installation commands",
-      "Presenting configuration snippets",
-      "Teaching programming concepts",
-      "Showing code diffs or changes",
-      "Displaying long code files with collapse functionality"
+      "Code examples inside prose or docs",
+      "Install and config snippets",
+      "Showing what changed, as a diff"
     ],
     "whenNot": [
-      "User-editable code (use code editor)",
-      "Very short inline code (use <code> element)",
-      "Non-code content (use Text or Card)"
+      "The user needs to edit it (use an editor)",
+      "A couple of words inline (use a code element)"
     ],
     "guidelines": [
-      "Always specify the correct language for accurate highlighting",
-      "Use filename prop to show source file name in header bar",
-      "Use copyPlacement=\"auto\" to render copy in overlay mode when no filename is provided",
-      "Use title prop for external labels above the code block",
-      "Enable line numbers for longer code samples",
-      "Use highlightLines to draw attention to key lines",
-      "Use addedLines/removedLines for diff highlighting",
-      "Set maxHeight for very long code blocks to prevent layout issues",
-      "Use collapsible for code samples that users may want to skim",
-      "Choose a theme that matches your documentation style",
-      "Keep code examples concise and focused",
-      "Use CodeBlock.Tabbed for multi-language snippets; tabs support controlled value/onValueChange and explicit tab values"
+      "Set language every time — wrong highlighting is worse than none",
+      "filename for a real file, title for a label, caption for the aside",
+      "Line numbers earn their keep once you need to point at a line",
+      "highlightLines for emphasis; addedLines and removedLines for diffs",
+      "maxHeight or collapsible keeps a long file from swallowing the page",
+      "CodeBlock.Tabbed groups the same snippet across languages"
     ],
     "accessibility": [
-      "Code is presented in a semantic pre/code structure",
-      "Copy button has appropriate aria-label",
-      "Keyboard accessible copy functionality",
-      "Collapse button has aria-expanded state"
+      "Renders as semantic pre and code",
+      "The copy button is labelled and keyboard reachable",
+      "The collapse toggle reports aria-expanded"
     ]
   },
   "examples": [
     {
       "name": "Default",
-      "description": "Basic code block with syntax highlighting",
+      "description": "Pass code and language; highlighting and copy come free.",
       "code": "<CodeBlock code={`import { Button } from '@usefragments/ui';\n\nfunction App() {\n  return <Button>Click me</Button>;\n}`} language=\"tsx\" />"
     },
     {
       "name": "With Filename",
-      "description": "Code block with filename in header bar",
+      "description": "A header bar names the source file and holds the copy button.",
       "code": "<CodeBlock filename=\"app.tsx\" code={`import { Button, Card } from '@usefragments/ui';\n\nfunction App() {\n  return (\n    <Card>\n      <Card.Header>Welcome</Card.Header>\n      <Card.Content>\n        <Button>Get Started</Button>\n      </Card.Content>\n    </Card>\n  );\n}`} language=\"tsx\" />"
     },
     {
       "name": "With Title",
-      "description": "Code block with external title label",
+      "description": "A label above the block, outside the code surface.",
       "code": "<CodeBlock title=\"Installation\" code=\"npm install @usefragments/ui\" language=\"bash\" />"
     },
     {
       "name": "With Caption",
-      "description": "Code block with footer caption",
+      "description": "A footer line for the aside that does not belong in the code.",
       "code": "<CodeBlock\n  code={`const API_URL = process.env.NEXT_PUBLIC_API_URL;`}\n  language=\"typescript\"\n  caption=\"Environment variables must be prefixed with NEXT_PUBLIC_ to be available in the browser.\"\n/>"
     },
     {
       "name": "With Line Numbers",
-      "description": "Shows line numbers for reference",
+      "description": "Turn these on once a snippet is long enough to point at.",
       "code": "<CodeBlock code={`const greeting = \"Hello\";\nconst name = \"World\";\nconsole.log(\\`\\${greeting}, \\${name}!\\`);`} language=\"typescript\" showLineNumbers />"
     },
     {
       "name": "Custom Start Line",
-      "description": "Shows code excerpt starting from a specific line number",
+      "description": "Numbering starts where the excerpt actually starts in the file.",
       "code": "<CodeBlock\n  code={`  return (\n    <button onClick={() => setCount(c => c + 1)}>\n      Count: {count}\n    </button>\n  );\n}`}\n  language=\"tsx\"\n  showLineNumbers\n  startLineNumber={15}\n  caption=\"Lines 15-20 from Counter.tsx\"\n/>"
     },
     {
       "name": "With Highlighted Lines",
-      "description": "Emphasizes specific lines of code",
+      "description": "Marks the lines the prose is talking about.",
       "code": "<CodeBlock code={`import { useState } from 'react';\n\nfunction Counter() {\n  const [count, setCount] = useState(0);\n\n  return (\n    <button onClick={() => setCount(c => c + 1)}>\n      Count: {count}\n    </button>\n  );\n}`} language=\"tsx\" showLineNumbers highlightLines={[4, '7-9']} />"
     },
     {
       "name": "Diff View",
-      "description": "Shows added and removed lines in a diff-like format",
+      "description": "Added and removed lines, side by side with the rest.",
       "code": "<CodeBlock\n  code={`import { useState } from 'react';\nimport { useCallback } from 'react';\n\nfunction Counter() {\n  const [count, setCount] = useState(0);\n  const increment = () => setCount(c => c + 1);\n  const increment = useCallback(() => setCount(c => c + 1), []);\n\n  return <button onClick={increment}>Count: {count}</button>;\n}`}\n  language=\"tsx\"\n  showLineNumbers\n  removedLines={[6]}\n  addedLines={[2, 7]}\n/>"
     },
     {
-      "name": "GitHub Dark Theme",
-      "description": "Using the GitHub Dark theme",
+      "name": "Custom Theme",
+      "description": "Any Shiki theme works — pass its name to theme.",
       "code": "<CodeBlock\n  code={`async function fetchUser(id: string) {\n  const response = await fetch(\\`/api/users/\\${id}\\`);\n  return response.json();\n}`}\n  language=\"typescript\"\n  theme=\"github-dark\"\n/>"
     },
-    {
-      "name": "GitHub Light Theme",
-      "description": "Using the GitHub Light theme for light backgrounds",
-      "code": "<CodeBlock\n  code={`def fibonacci(n):\n    if n <= 1:\n        return n\n    return fibonacci(n - 1) + fibonacci(n - 2)`}\n  language=\"python\"\n  theme=\"github-light\"\n/>"
-    },
-    {
-      "name": "Dracula Theme",
-      "description": "Using the popular Dracula theme",
-      "code": "<CodeBlock\n  code={`fn main() {\n    println!(\"Hello, Rust!\");\n}`}\n  language=\"rust\"\n  theme=\"dracula\"\n/>"
-    },
     {
       "name": "Word Wrap",
-      "description": "Long lines wrap instead of scrolling horizontally",
+      "description": "Long lines break instead of scrolling sideways.",
       "code": "<CodeBlock\n  code={`const longString = \"This is a very long string that would normally cause horizontal scrolling, but with word wrap enabled it will break to the next line instead.\";`}\n  language=\"typescript\"\n  wordWrap\n/>"
     },
     {
       "name": "Max Height with Scroll",
-      "description": "Constrains height with scrollable content",
+      "description": "Caps the height so one snippet cannot own the page.",
       "code": "<CodeBlock\n  code={`// This code block has a maximum height\nfunction processItems(items: string[]) {\n  const results = [];\n  for (const item of items) {\n    if (item.startsWith('_')) {\n      continue;\n    }\n    const processed = item.trim().toLowerCase();\n    if (processed.length > 0) {\n      results.push(processed);\n    }\n  }\n  return results;\n}\n\nexport default processItems;`}\n  language=\"typescript\"\n  maxHeight={150}\n  showLineNumbers\n/>"
     },
     {
       "name": "Collapsible",
-      "description": "Long code that can be expanded/collapsed",
+      "description": "Shows the opening lines and hides the rest behind a toggle.",
       "code": "<CodeBlock\n  code={`import React, { useState, useEffect } from 'react';\n\ninterface User {\n  id: string;\n  name: string;\n  email: string;\n  avatar?: string;\n}\n\nexport function UserProfile({ userId }: { userId: string }) {\n  const [user, setUser] = useState<User | null>(null);\n  const [loading, setLoading] = useState(true);\n  const [error, setError] = useState<string | null>(null);\n\n  useEffect(() => {\n    async function fetchUser() {\n      try {\n        setLoading(true);\n        const response = await fetch(\\`/api/users/\\${userId}\\`);\n        if (!response.ok) throw new Error('Failed to fetch');\n        const data = await response.json();\n        setUser(data);\n      } catch (err) {\n        setError(err instanceof Error ? err.message : 'Unknown error');\n      } finally {\n        setLoading(false);\n      }\n    }\n    fetchUser();\n  }, [userId]);\n\n  if (loading) return <div>Loading...</div>;\n  if (error) return <div>Error: {error}</div>;\n  if (!user) return null;\n\n  return (\n    <div>\n      <h1>{user.name}</h1>\n      <p>{user.email}</p>\n    </div>\n  );\n}`}\n  language=\"tsx\"\n  showLineNumbers\n  collapsible\n  defaultCollapsed\n  collapsedLines={8}\n/>"
     },
     {
       "name": "JSON",
-      "description": "Configuration file example",
+      "description": "Config files highlight the same way source does.",
       "code": "<CodeBlock title=\"package.json\" code={`{\n  \"name\": \"my-app\",\n  \"dependencies\": {\n    \"@usefragments/ui\": \"^0.3.0\"\n  }\n}`} language=\"json\" />"
     },
     {
       "name": "Without Copy Button",
-      "description": "Minimal display without copy functionality",
+      "description": "Drop the copy button when the snippet is not meant to be reused.",
       "code": "<CodeBlock code=\"const simple = true;\" language=\"typescript\" showCopy={false} />"
     }
   ],
@@ -357,7 +332,7 @@
     "propsSummary": [
       "code: string - required code content",
       "language: tsx|typescript|javascript|jsx|bash|shell|css|scss|sass|json|html|xml|markdown|md|yaml|yml|python|py|ruby|go|rust|java|kotlin|swift|c|cpp|csharp|php|sql|graphql|diff|plaintext",
-      "theme: synthwave-84|github-dark|github-light|one-dark-pro|dracula|nord|monokai|vitesse-dark|vitesse-light|min-dark|min-light (default: one-dark-pro)",
+      "theme: css-variables|synthwave-84|github-dark|github-light|one-dark-pro|dracula|nord|monokai|vitesse-dark|vitesse-light|min-dark|min-light (default: css-variables)",
       "showCopy: boolean (default: true)",
       "copyPlacement: auto|header|overlay (default: auto)",
       "title: string - optional external label",
@@ -373,18 +348,13 @@
       "collapsible: boolean (default: false)",
       "defaultCollapsed: boolean (default: false)",
       "collapsedLines: number (default: 5)",
-      "CodeBlock.Tabbed: tabs[] plus optional defaultTab/value/onValueChange for multi-language snippets"
+      "CodeBlock.Tabbed: tabs[] plus optional defaultTab/value/onValueChange for multi-language snippets; collapsible/defaultCollapsed/collapsedLines forward to every panel"
     ],
-    "a11yRules": [
-      "A11Y_CODE_SEMANTIC",
-      "A11Y_BTN_LABEL"
-    ]
+    "a11yRules": ["A11Y_CODE_SEMANTIC", "A11Y_BTN_LABEL"]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Tabbed"
-    ]
+    "subComponents": ["Tabbed"]
   },
   "provenance": {
     "source": "migrated",

package/src/components/CodeBlock/CodeBlock.module.scss

@@ -7,7 +7,7 @@
 @use "../../recipes/typography" as typography;
 
 .container {
-  --_fui-code-inline-inset: var(--fui-raw-space-16);
+  --_fui-code-inline-inset: var(--fui-raw-space-16, 16px);
 
   inline-size: 100%;
 }
@@ -27,9 +27,24 @@
 .wrapper {
   position: relative;
   overflow: hidden;
+  // A hairline keeps the block legible on any ground: the light code surface
+  // and the sunken app main share the same tone, so fill alone can vanish.
+  border: var(--fui-stroke-hairline, $fui-stroke-hairline) solid
+    var(--fui-code-border, var(--fui-border, #{$fui-border}));
   border-radius: var(--fui-radius-lg, $fui-radius-lg);
   background-color: var(--fui-code-bg, $fui-code-bg);
   color: var(--fui-code-text, var(--fui-text-primary, #{$fui-text-primary}));
+  --shiki-color-text: var(--fui-code-text, var(--fui-text-primary, #{$fui-text-primary}));
+  --shiki-color-background: var(--fui-code-bg, #{$fui-code-bg});
+  --shiki-token-keyword: var(--fui-code-token-keyword, #{$fui-code-token-keyword});
+  --shiki-token-string: var(--fui-code-token-string, #{$fui-code-token-string});
+  --shiki-token-string-expression: var(--fui-code-token-string, #{$fui-code-token-string});
+  --shiki-token-comment: var(--fui-code-token-comment, #{$fui-code-token-comment});
+  --shiki-token-function: var(--fui-code-token-function, #{$fui-code-token-function});
+  --shiki-token-constant: var(--fui-code-token-number, #{$fui-code-token-number});
+  --shiki-token-parameter: var(--fui-code-token-variable, #{$fui-code-token-variable});
+  --shiki-token-punctuation: var(--fui-code-token-punctuation, #{$fui-code-token-punctuation});
+  --shiki-token-link: var(--fui-link-ink, #{$fui-link-ink});
 }
 
 .header {
@@ -38,7 +53,7 @@
   justify-content: space-between;
   min-block-size: action.track("md");
   padding-inline: layout.gap("lg");
-  border-block-end: var(--fui-stroke-hairline) solid
+  border-block-end: var(--fui-stroke-hairline, $fui-stroke-hairline) solid
     var(--fui-code-border, var(--fui-border, #{$fui-border}));
 }
 
@@ -94,13 +109,6 @@
   .copyOverlay.copied {
     opacity: 1;
   }
-
-  .codeContainer :global(.shiki),
-  .loading pre {
-    padding-inline-end: calc(
-      var(--_fui-code-inline-inset) + #{action.track("sm")} + var(--fui-raw-space-12)
-    );
-  }
 }
 
 .icon {
@@ -117,6 +125,18 @@
   opacity: 1;
 }
 
+// Overlay + persistent copy both sit absolute — reserve trailing space so
+// content-sized blocks don't collide with the control.
+.withCopyOverlay,
+.persistentCopyWrapper {
+  .codeContainer :global(.shiki),
+  .loading pre {
+    padding-inline-end: calc(
+      var(--_fui-code-inline-inset) + #{action.track("sm")} + var(--fui-raw-space-12, 12px)
+    );
+  }
+}
+
 .loading pre,
 .codeContainer :global(.shiki) {
   @include prose.code-block("default");
@@ -152,7 +172,7 @@
     &:global(.highlighted) {
       margin-inline: calc(-1 * var(--_fui-code-inline-inset));
       padding-inline: var(--_fui-code-inline-inset);
-      border-inline-start: var(--fui-stroke-default) solid
+      border-inline-start: var(--fui-stroke-default, $fui-stroke-default) solid
         var(--fui-color-info-text, $fui-color-info-text);
       background-color: var(--fui-code-highlight-bg, var(--fui-bg-hover, #{$fui-bg-hover}));
     }
@@ -174,7 +194,7 @@
   }
 
   :global(.shiki)::-webkit-scrollbar {
-    block-size: var(--fui-raw-space-4);
+    block-size: var(--fui-raw-space-4, 4px);
   }
 
   :global(.shiki)::-webkit-scrollbar-thumb {
@@ -184,7 +204,7 @@
 }
 
 .withLineNumbers .codeContainer :global(.shiki) {
-  padding-inline-start: var(--fui-raw-space-8);
+  padding-inline-start: var(--fui-raw-space-8, 8px);
 }
 
 .withDiff {
@@ -220,7 +240,7 @@
 }
 
 .compact {
-  --_fui-code-inline-inset: var(--fui-raw-space-12);
+  --_fui-code-inline-inset: var(--fui-raw-space-12, 12px);
 
   .wrapper {
     border-radius: var(--fui-radius-md, $fui-radius-md);
@@ -250,8 +270,9 @@
   @include action.size("sm");
 
   inline-size: 100%;
-  border-block-start: 0;
-  background: linear-gradient(to bottom, transparent, var(--fui-code-bg, $fui-code-bg) 40%);
+  border-block-start: var(--fui-stroke-hairline, $fui-stroke-hairline) solid
+    var(--fui-border, $fui-border);
+  background: var(--fui-code-bg, $fui-code-bg);
   color: var(--fui-code-text-muted, var(--fui-text-secondary, #{$fui-text-secondary}));
   cursor: pointer;
 
@@ -266,6 +287,10 @@
   }
 }
 
+.collapseExpand {
+  justify-content: flex-end;
+}
+
 .tabbedPanel {
   margin-block-start: 0;
 }

package/src/components/CodeBlock/css-variables-theme.ts

@@ -0,0 +1,102 @@
+/**
+ * Shiki theme whose token colors are CSS variables from the kit palette.
+ *
+ * Bundled shiki themes (including the old `css-variables` theme) were removed
+ * from shiki 3; this object is the replacement. `codeToHtml` accepts it as the
+ * `theme` option and writes `color: var(--fui-code-token-*)` onto spans.
+ */
+export const FUI_CSS_VARIABLES_THEME = {
+  name: "css-variables",
+  type: "dark" as const,
+  colors: {
+    "editor.foreground": "var(--fui-code-text)",
+    "editor.background": "var(--fui-code-bg)",
+  },
+  tokenColors: [
+    { settings: { foreground: "var(--fui-code-text)" } },
+    {
+      scope: [
+        "comment",
+        "punctuation.definition.comment",
+        "string.comment",
+        "string.quoted.docstring.multi",
+      ],
+      settings: { foreground: "var(--fui-code-token-comment)" },
+    },
+    {
+      scope: [
+        "keyword",
+        "keyword.control",
+        "keyword.other",
+        "storage",
+        "storage.type",
+        "storage.modifier",
+        "storage.control.clojure",
+      ],
+      settings: { foreground: "var(--fui-code-token-keyword)" },
+    },
+    {
+      scope: [
+        "string",
+        "string.quoted",
+        "string.template",
+        "string.interpolated",
+        "string.regexp",
+        "string.unquoted.plain.out.yaml",
+        "markup.inline",
+      ],
+      settings: { foreground: "var(--fui-code-token-string)" },
+    },
+    {
+      scope: [
+        "constant.numeric",
+        "constant.language",
+        "constant.other",
+        "constant.character.format.placeholder",
+        "constant.other.placeholder",
+      ],
+      settings: { foreground: "var(--fui-code-token-number)" },
+    },
+    {
+      scope: [
+        "entity.name.function",
+        "support.function",
+        "meta.function-call",
+        "meta.instance.constructor",
+        "entity.other.attribute-name",
+        "entity.name.tag",
+        "support.class.component",
+        "meta.tag",
+      ],
+      settings: { foreground: "var(--fui-code-token-function)" },
+    },
+    {
+      scope: [
+        "punctuation",
+        "punctuation.separator",
+        "punctuation.definition.arguments",
+        "punctuation.definition.dict",
+        "punctuation.definition.string",
+        "punctuation.definition.template-expression",
+        "meta.brace",
+        "keyword.operator",
+        "keyword.operator.accessor",
+      ],
+      settings: { foreground: "var(--fui-code-token-punctuation)" },
+    },
+    {
+      scope: [
+        "variable",
+        "variable.other",
+        "variable.parameter",
+        "variable.language",
+        "entity.name",
+        "support.variable",
+        "support.type",
+        "meta.property-name",
+        "meta.property-value",
+      ],
+      settings: { foreground: "var(--fui-code-token-variable)" },
+    },
+  ],
+};