@duro-app/cli 5.20.0 → 5.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duro-app/cli",
-  "version": "5.20.0",
+  "version": "5.22.0",
   "type": "module",
   "license": "MIT",
   "description": "Machine-queryable docs for the Duro design system: components, props, recipes, tokens and rules as CLI output, JSON, or an MCP server.",
@@ -46,7 +46,7 @@
   },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": ">=1.0.0",
-    "@duro-app/ui": "^5.20.0"
+    "@duro-app/ui": "^5.22.0"
   },
   "peerDependenciesMeta": {
     "@duro-app/ui": {
@@ -61,9 +61,9 @@
     "@types/node": "^24.0.0",
     "ts-morph": "^26.0.0",
     "typescript": "^5.7.0",
-    "@duro-app/eslint-plugin": "^5.20.0",
-    "@duro-app/ui": "^5.20.0",
-    "@duro-app/tokens": "^5.20.0"
+    "@duro-app/eslint-plugin": "^5.22.0",
+    "@duro-app/ui": "^5.22.0",
+    "@duro-app/tokens": "^5.22.0"
   },
   "scripts": {
     "registry": "node scripts/build-registry.mjs",

package/registry.json

@@ -1182,7 +1182,7 @@
       "importPath": "@duro-app/ui",
       "kind": "component",
       "meta": {
-        "description": "A block of code with a copy button: a pre that scrolls sideways when a line is long, and a Button that copies its text, shows the copied label for copiedDuration ms and announces it through a polite LiveRegion. Labels come from props.",
+        "description": "A block of code with a copy button: a pre that scrolls sideways when a line is long, and a Button that copies its text, shows the copied label for copiedDuration ms and announces it through a polite LiveRegion. Labels come from props. With language=\"diff\", added, removed and hunk lines are coloured from tokens. On native the text is selectable and scrolls sideways; there is no copy button.",
         "example": "<CodeBlock copyLabel=\"Copy\" copiedLabel=\"Copied\">\n  <code>pnpm add @duro-app/ui</code>\n</CodeBlock>",
         "relatedTo": [
           {
@@ -1206,7 +1206,7 @@
         ]
       },
       "name": "CodeBlock",
-      "native": false,
+      "native": true,
       "props": [
         {
           "description": "The code: text, or the `<code>` element a Markdown renderer produced (highlighted spans included). What is copied is its text content.",
@@ -1214,6 +1214,12 @@
           "required": true,
           "type": "ReactNode"
         },
+        {
+          "description": "The code's language (\"diff\", \"ts\"), exposed as `data-language` on the `pre`. `\"diff\"` also gives each added (`+`), removed (`-`) and hunk (`@@`) line its own colour; what is copied stays the raw text. Diff rendering works on the text content, so highlighted spans inside `children` are flattened to plain text. The language is a data attribute only: it is not announced to assistive technology.",
+          "name": "language",
+          "required": false,
+          "type": "string"
+        },
         {
           "description": "The copy button's label (\"Copy\"), from your text catalog.",
           "name": "copyLabel",
@@ -1378,13 +1384,25 @@
           "description": "Initial preference (uncontrolled). Default `'system'`. For SSR with no hydration flash, pass the value you persisted server-side (e.g. a cookie).",
           "name": "defaultPreference",
           "required": false,
-          "type": "ColorModePreference"
+          "type": "ColorModePreference",
+          "union": [
+            "system",
+            "dark",
+            "light",
+            "high-contrast"
+          ]
         },
         {
           "description": "Controlled preference — when set, the provider does not own the state.",
           "name": "preference",
           "required": false,
-          "type": "ColorModePreference"
+          "type": "ColorModePreference",
+          "union": [
+            "system",
+            "dark",
+            "light",
+            "high-contrast"
+          ]
         },
         {
           "description": "Fired whenever the preference changes (controlled or not).",
@@ -3307,8 +3325,8 @@
       "importPath": "@duro-app/ui",
       "kind": "component",
       "meta": {
-        "description": "Semantic heading element (h1-h6) with typography presets. Always use the correct level for document hierarchy. Visual size can differ from semantic level via the variant prop.",
-        "example": "<Stack gap=\"md\">\n  <Heading level={1}>Page Title</Heading>\n  <Heading level={2} variant=\"headingMd\">Section</Heading>\n  <Heading level={3}>Subsection</Heading>\n</Stack>",
+        "description": "Semantic heading element (h1-h6) with typography presets. Always use the correct level for document hierarchy. The look is `variant` (heading, display, overline) and its size is `size` (sm, md, lg, xl), both independent of the semantic level. The old combined variants (headingSm, displayLg, …) still work and are deprecated.",
+        "example": "<Stack gap=\"md\">\n  <Heading level={1}>Page Title</Heading>\n  <Heading level={2} size=\"md\">Section</Heading>\n  <Heading level={1} variant=\"display\" size=\"lg\">Hero</Heading>\n  <Heading level={3} variant=\"overline\" color=\"muted\">Group</Heading>\n  <Heading level={2} variant=\"overline\" size=\"lg\">Large group</Heading>\n</Stack>",
         "relatedTo": [
           {
             "component": "Text",
@@ -3324,7 +3342,8 @@
         "whenToUse": [
           "Page titles (level 1)",
           "Section headers (level 2-3)",
-          "Card or panel titles (level 3-4)"
+          "Card or panel titles (level 3-4)",
+          "Group titles over a list of rows or a form section (level 3-4, variant=\"overline\", any size)"
         ]
       },
       "name": "Heading",
@@ -3336,10 +3355,14 @@
           "type": "1 | 2 | 3 | 4 | 5 | 6"
         },
         {
+          "description": "The look: `heading` (default), `display` (fluid hero titles), `overline` (small uppercase group titles).",
           "name": "variant",
           "required": false,
           "type": "HeadingVariant",
           "union": [
+            "heading",
+            "display",
+            "overline",
             "displayLg",
             "displayMd",
             "displaySm",
@@ -3349,6 +3372,18 @@
             "headingSm"
           ]
         },
+        {
+          "description": "The size within the look. Default: the level's size for `heading`, `md` for `display`, `sm` for `overline`; `display` and `overline` stop at `lg`.",
+          "name": "size",
+          "required": false,
+          "type": "HeadingSize",
+          "union": [
+            "sm",
+            "md",
+            "lg",
+            "xl"
+          ]
+        },
         {
           "default": "'default'",
           "name": "color",
@@ -5209,7 +5244,7 @@
       "importPath": "@duro-app/ui",
       "kind": "component",
       "meta": {
-        "description": "The container for HTML Duro does not author — rendered Markdown, CMS output: headings, paragraphs, lists, tables, blockquotes, inline code, links and images are styled from tokens by descendant rules scoped to it (plain CSS in dist/index.css, :where() and its own cascade layer). Duro components inside it keep their styles, and an app's own CSS wins over every Prose rule. Web only.",
+        "description": "The container for HTML Duro does not author — rendered Markdown, CMS output: headings, paragraphs, lists, tables, blockquotes, inline code, links and images are styled from tokens by descendant rules scoped to it (plain CSS in dist/index.css, :where() and its own cascade layer). Duro components inside it keep their styles, and an app's own CSS wins over every Prose rule. On native it is a reading-width column with a token gap; the renderer maps Markdown to Duro primitives.",
         "example": "<Prose>\n  <ReactMarkdown components={{pre: ({children}) => <CodeBlock copyLabel=\"Copy\" copiedLabel=\"Copied\">{children}</CodeBlock>}}>\n    {body}\n  </ReactMarkdown>\n</Prose>",
         "relatedTo": [
           {
@@ -5233,7 +5268,7 @@
         ]
       },
       "name": "Prose",
-      "native": false,
+      "native": true,
       "props": [
         {
           "description": "HTML Duro does not author: the output of a Markdown renderer.",
@@ -5909,7 +5944,7 @@
             "Pane"
           ]
         },
-        "description": "Two panes side by side with a resizable separator: the first Pane is sized by the Handle (pointer drag, arrow keys, Shift for larger steps, Home and End), the second takes the rest. Min, max and starting widths are size tokens. Below collapseBelow, measured on its own width, the panes stack in one column and the handle goes; on native they always stack. The Handle is a hairline that thickens to the accent on hover, keyboard focus or drag.",
+        "description": "Two panes side by side with a resizable separator: the first Pane is sized by the Handle (pointer drag, arrow keys, Shift for larger steps, Home and End), the second takes the rest. Min, max and starting widths are size tokens. Below collapseBelow, measured on its own width, the panes stack in one column and the handle goes; on native they always stack. A controlled collapsed prop shrinks the first pane to a strip (the iconButton size) that shows collapsedContent, removes the Handle, and keeps the first pane’s own children mounted but inert and hidden (state kept, no tab stops, out of the accessibility tree); the prior width returns when it turns false. Native ignores both. The Handle is a hairline that thickens to the accent on hover, keyboard focus or drag.",
         "example": "<SplitPane.Root aria-label=\"Resize the session list\" minSize=\"sidebarW\" maxSize=\"panelLg\">\n  <SplitPane.Pane>\n    <List.Root aria-label=\"Sessions\">…</List.Root>\n  </SplitPane.Pane>\n  <SplitPane.Handle />\n  <SplitPane.Pane>\n    <Panel.Root>…</Panel.Root>\n  </SplitPane.Pane>\n</SplitPane.Root>",
         "relatedTo": [
           {
@@ -6007,6 +6042,19 @@
                 "xl"
               ]
             },
+            {
+              "default": "false",
+              "description": "Controlled: shrink the primary pane to a strip (the `iconButton` size), show `collapsedContent` in it and remove the handle. The pane's own children stay mounted (their state is kept) but are inert and hidden. When it turns false the pane returns to its prior width. Ignored when stacked.",
+              "name": "collapsed",
+              "required": false,
+              "type": "boolean"
+            },
+            {
+              "description": "What the strip shows while `collapsed` (an expand button, icons).",
+              "name": "collapsedContent",
+              "required": false,
+              "type": "ReactNode"
+            },
             {
               "description": "The handle's accessible name (\"Resize list\").",
               "name": "aria-label",
@@ -7250,13 +7298,13 @@
           }
         ],
         "whenNotToUse": [
-          "Page or section titles — use Heading",
+          "Page, section or group titles — use Heading, even in overline style (variant=\"overline\")",
           "Form field labels — use Field.Label (auto-binds to form)"
         ],
         "whenToUse": [
           "Body text (paragraphs, descriptions)",
           "UI labels and metadata",
-          "Captions, code snippets, overlines"
+          "Captions, code snippets, and overline eyebrows above a Heading"
         ]
       },
       "name": "Text",
@@ -7460,7 +7508,7 @@
       "importPath": "@duro-app/ui",
       "kind": "component",
       "meta": {
-        "description": "Multi-line text input with automatic Field/Form integration. Same Field binding behavior as Input.",
+        "description": "Multi-line text input with automatic Field/Form integration. Same Field binding behavior as Input. autoGrow makes the height follow the content from rows up to maxRows, then it scrolls (CSS field-sizing, with a scrollHeight fallback; native grows with the content and caps at maxRows). The anchor props of Listbox.getAnchorProps() (role combobox, aria-controls, aria-expanded, aria-activedescendant) are forwarded as ARIA attributes on web and as the matching accessibility props on native, so a Listbox can be anchored to it while the editor keeps focus.",
         "example": "<Field.Root name=\"message\">\n  <Field.Label>Message</Field.Label>\n  <Textarea placeholder=\"Tell us what you think...\" rows={4} />\n  <Field.Description>At least 10 characters</Field.Description>\n  <Field.Error />\n</Field.Root>",
         "relatedTo": [
           {
@@ -7478,12 +7526,26 @@
           "Single-line input — use Input"
         ],
         "whenToUse": [
-          "Multi-line text entry (comments, messages, descriptions)"
+          "Multi-line text entry (comments, messages, descriptions)",
+          "A composer that grows with its text (autoGrow, maxRows)",
+          "An editor a Listbox is anchored to for mentions or slash commands (spread Listbox.getAnchorProps())"
         ]
       },
       "name": "Textarea",
       "native": true,
       "props": [
+        {
+          "description": "The height follows the content, from `rows` up to `maxRows`, then it scrolls.",
+          "name": "autoGrow",
+          "required": false,
+          "type": "true | false"
+        },
+        {
+          "description": "The most rows the field shows before it scrolls. Default: no limit",
+          "name": "maxRows",
+          "required": false,
+          "type": "number"
+        },
         {
           "default": "'default'",
           "name": "variant",
@@ -8130,7 +8192,7 @@
             "aria-label"
           ]
         },
-        "description": "A row of controls with one tab stop (the WAI-ARIA toolbar pattern): Tab enters at the last focused control, Left/Right move across every control inside — through attached ButtonGroups too — and Home/End jump to the ends. A Select or Menu trigger keeps its own keys, and a control whose popup is open keeps Left/Right.",
+        "description": "A row of controls with one tab stop (the WAI-ARIA toolbar pattern): Tab enters at the last focused control, Left/Right move across every control inside — through attached ButtonGroups too — and Home/End jump to the ends. A Select or Menu trigger keeps its own keys, and a control whose popup is open keeps Left/Right. On native it is the same row of controls without the roving tab stop and arrow keys.",
         "example": "<Toolbar aria-label=\"Formatting\">\n  <ButtonGroup attached aria-label=\"Text style\">\n    <Toggle aria-label=\"Bold\" pressed={bold} onPressedChange={setBold}>B</Toggle>\n    <Toggle aria-label=\"Italic\" pressed={italic} onPressedChange={setItalic}>I</Toggle>\n  </ButtonGroup>\n  <Menu.Root>\n    <Menu.Trigger>Insert</Menu.Trigger>\n    <Menu.Popup>…</Menu.Popup>\n  </Menu.Root>\n</Toolbar>",
         "relatedTo": [
           {
@@ -8160,7 +8222,7 @@
         ]
       },
       "name": "Toolbar",
-      "native": false,
+      "native": true,
       "props": [
         {
           "description": "Names the toolbar (\"Formatting\"). Required: a toolbar is a landmark-like widget.",
@@ -8423,7 +8485,7 @@
           "optional": [],
           "required": []
         },
-        "description": "A windowed list on @tanstack/react-virtual: only the rows in view (plus overscan) are mounted, and rows are measured so they may differ in height. role=\"list\" with listitem rows carrying aria-setsize and aria-posinset. anchor=\"end\" opens at the last item and stays pinned to the bottom while new items arrive and the reader is at the bottom (a transcript, a log). It fills its parent, or stops at maxHeight. Web only: on native, host FlashList or Legend List behind your own .native.tsx leaf.",
+        "description": "A windowed list on @tanstack/react-virtual: only the rows in view (plus overscan) are mounted, and rows are measured so they may differ in height. role=\"list\" with listitem rows carrying aria-setsize and aria-posinset. anchor=\"end\" opens at the last item and stays pinned to the bottom while new items arrive and the reader is at the bottom (a transcript, a log). It fills its parent, or stops at maxHeight. onStartReached fires once each time the reader scrolls to the start (load older history), and prepending items keeps the first visible row in place. On native it is a FlatList with the same props (role list; rows carry no listitem role, which React Native lacks) (maintainVisibleContentPosition for prepend).",
         "example": "<VirtualList\n  aria-label=\"Transcript\"\n  items={messages}\n  getKey={(m) => m.id}\n  estimateSize=\"controlLg\"\n  anchor=\"end\"\n  renderItem={(m) => <Text>{m.text}</Text>}\n/>",
         "relatedTo": [
           {
@@ -8444,11 +8506,12 @@
         ],
         "whenToUse": [
           "Hundreds to tens of thousands of rows: sessions, a chat transcript, log lines",
-          "A list that grows at the bottom while the reader follows it (anchor=\"end\")"
+          "A list that grows at the bottom while the reader follows it (anchor=\"end\")",
+          "A transcript that pages older history in at the top (onStartReached, then prepend items)"
         ]
       },
       "name": "VirtualList",
-      "native": false,
+      "native": true,
       "props": [
         {
           "name": "items",
@@ -8486,6 +8549,12 @@
           "required": false,
           "type": "'start' | 'end'"
         },
+        {
+          "description": "Called once each time the reader scrolls to within 44px (touchTarget) of the start (load older history). It fires again only after they move away. A list too short to scroll calls it once for each new first item or length, until it fills. Prepending items keeps the first visible row where it was on screen.",
+          "name": "onStartReached",
+          "required": false,
+          "type": "() => void"
+        },
         {
           "description": "Cap the list's height; without it, it fills its parent.",
           "name": "maxHeight",
@@ -10793,6 +10862,12 @@
           {
             "key": "overline"
           },
+          {
+            "key": "overlineMd"
+          },
+          {
+            "key": "overlineLg"
+          },
           {
             "key": "headingSm"
           },
@@ -10938,6 +11013,12 @@
       "filled",
       "interactive"
     ],
+    "ColorModePreference": [
+      "system",
+      "dark",
+      "light",
+      "high-contrast"
+    ],
     "ContainerSize": [
       "compact",
       "default",
@@ -10990,7 +11071,16 @@
       "split-wide",
       "content-aside"
     ],
+    "HeadingSize": [
+      "sm",
+      "md",
+      "lg",
+      "xl"
+    ],
     "HeadingVariant": [
+      "heading",
+      "display",
+      "overline",
       "displayLg",
       "displayMd",
       "displaySm",