@treeui/mcp 0.8.1 → 0.8.2

package/README.md

@@ -11,8 +11,8 @@ TreeUI ships a local Model Context Protocol server so coding agents can:
 ## What it serves
 
 - a generated catalog built from `docs/ai/*.yaml` and `@treeui/tokens`
-- MCP resources for catalog, setup, selection, recipes, tokens, and per-component metadata
-- MCP tools for search, recommendation, setup lookup, recipe search, and token search
+- 7 MCP resources: `treeui://catalog`, `treeui://selection`, `treeui://setup`, `treeui://recipes`, `treeui://practices`, `treeui://tokens`, and `treeui://components/<name>` (one per component)
+- 6 MCP tools: `search_components`, `recommend_components`, `get_component`, `get_setup_guide`, `search_recipes`, `search_tokens`
 
 ## Token search
 

package/dist/{chunk-DGIMKZPZ.js → chunk-VPOHUNDH.js}

@@ -1,8 +1,8 @@
 // src/generated/treeui.catalog.json
 var treeui_catalog_default = {
-  generatedAt: "0.32.0",
+  generatedAt: "0.34.1",
   packageName: "@treeui/vue",
-  packageVersion: "0.32.0",
+  packageVersion: "0.34.1",
   decisionGuides: [
     {
       id: "single-choice",
@@ -462,7 +462,7 @@ var treeui_catalog_default = {
         "`TNavMenuItem.icon` is `TIconInput`, so a component is accepted too. Prefer the name: `items` normally lives in a `ref`, a `computed`, or a route config, and a string is never made reactive \u2014 a component object there needs `markRaw` or Vue warns.",
         "An item with no icon (or an unregistered name) falls back to a letter marker, and a `console.warn` lists the valid names \u2014 once per name, in production builds too. Give every item an icon before shipping a collapsible rail, or the collapsed state is a column of letters.",
         "Icons the app needs but TreeUI does not ship are REGISTERED, not worked around: one `registerTreeIcons` call in `main.ts` and they are usable by name everywhere. Never hand-roll an `<svg>` \u2014 without the `absoluteStrokeWidth` correction its stroke scales with the icon (1.67px at size 20, 4px at 48), so it looks bolder than its neighbours at every size above 24.",
-        "Check the name is not already taken before registering it \u2014 `hasTreeIcon(name)` answers that. Registering one of the 364 built-in names replaces that built-in everywhere, silently, which is a supported swap but never what you want when the goal was adding an icon.",
+        "Check the name is not already taken before registering it \u2014 `hasTreeIcon(name)` answers that. Registering one of the 370 built-in names replaces that built-in everywhere, silently, which is a supported swap but never what you want when the goal was adding an icon.",
         "Keep the icon vocabulary consistent: built-ins use TreeUI's descriptive kebab-case names, so register custom ones with the same convention.",
         "Icon registration is process-wide state. In component tests that register icons, call `resetTreeIcons()` in an `afterEach` so one case's icons do not leak into the next.",
         "Set `to` for the route target on each item \u2014 `TNavMenuItem` has no `href` and no `id`; identity is `value`.",
@@ -787,6 +787,7 @@ var treeui_catalog_default = {
         "TDropdown",
         "TFileUpload",
         "TFormField",
+        "TIconTile",
         "TImage",
         "TLinkTile",
         "TMenu",
@@ -794,7 +795,9 @@ var treeui_catalog_default = {
         "TPopover",
         "TSelect",
         "TSkipLink",
+        "TStatGroup",
         "TSteps",
+        "TTable",
         "TTabs",
         "TText",
         "TToast",
@@ -879,6 +882,7 @@ var treeui_catalog_default = {
         "TGrid",
         "THero",
         "THide",
+        "TIconTile",
         "TLinkTile",
         "TList",
         "TModal",
@@ -893,7 +897,9 @@ var treeui_catalog_default = {
         "TSplit",
         "TStack",
         "TStat",
+        "TStatGroup",
         "TSteps",
+        "TTable",
         "TTabs",
         "TText",
         "TTimeline"
@@ -923,6 +929,7 @@ var treeui_catalog_default = {
         "TColorSwatch",
         "TDescriptionList",
         "THero",
+        "TIconTile",
         "TImage",
         "TInput",
         "TKeyValueEditor",
@@ -936,6 +943,7 @@ var treeui_catalog_default = {
         "TSection",
         "TSelect",
         "TStat",
+        "TStatGroup",
         "TSwitch",
         "TTag",
         "TTagInput",
@@ -975,7 +983,7 @@ var treeui_catalog_default = {
     },
     vueSetup: {
       pluginInstall: {
-        import: "import TreeUIPlugin from '@treeui/vue'",
+        import: "import { TreeUIPlugin } from '@treeui/vue'",
         usage: "app.use(TreeUIPlugin)"
       },
       individualImports: {
@@ -2942,6 +2950,12 @@ var treeui_catalog_default = {
       storyTitle: "Components/Data Display/Chart",
       manifestFile: "docs/ai/COMPONENTS/chart.yaml",
       props: [
+        {
+          name: "axisValueFormat",
+          type: "(value: number) => string",
+          default: "undefined",
+          description: "Formatter for the AXIS ticks only, falling back to `valueFormat`. The two have different jobs and the axis is the one with no room: a tooltip can spell `R$ 1.500.000.000,00` in full, while the same string on a y-axis at 320px eats the plot \u2014 and the space reserved for it is capped at 40% of the chart, so past that it clips. One formatter could not serve both."
+        },
         {
           name: "yAxisWidth",
           type: "number",
@@ -3092,6 +3106,7 @@ var treeui_catalog_default = {
         "point-click has no keyboard equivalent \u2014 do not make it the only way to reach a behavior."
       ],
       behavior: [
+        "edge_x_labels_anchor_with_a_class_not_an_attribute: The first and last x labels carry `is-anchor-start` / `is-anchor-end`, not a `text-anchor` ATTRIBUTE. CSS always beats a presentation attribute, so `.t-chart__axis-label--x { text-anchor: middle }` silently won and the anchoring never applied \u2014 the last label kept rendering centred and hanging off the SVG.",
         "colors_auto_assign_from_chart_palette: --tree-color-chart-1..8, cycling by series index; per-series color overrides",
         "zero_baseline_for_bar_and_area: the y domain is extended to include 0 for bar and area; line uses the data extent. minY overrides it.",
         "y_domain_uses_nice_ticks: every type runs through niceScale, which rounds the min down and the max up to round numbers",
@@ -3350,6 +3365,7 @@ var treeui_catalog_default = {
         "copy_button_state: The copy button's aria-label reflects the copied state briefly."
       ],
       behavior: [
+        "copyable_reserves_the_toolbar_width: With the copy button rendered, `.t-code-block.is-copyable .t-code-block__pre` reserves its width as `padding-inline-end`. The toolbar floats over the code, so a wrapped line used to run underneath it and the characters behind the button were unreadable. This only became visible once `wrap` started breaking for real: before, the long token overflowed sideways and never reached the button.",
         'wrap_reduces_the_min_content: `.t-code-block.is-wrap .t-code-block__pre` uses `overflow-wrap: anywhere`, not `break-word`. `break-word` breaks only once a width is already settled, so wherever the block\'s width came from its content \u2014 a grid `auto` track, a table cell, a flex item without `min-width: 0` \u2014 the longest run without a break opportunity became the minimum width and pushed the container instead of wrapping. That is precisely the case `wrap` exists for: a URL, a token, a credential. Same semantics as `TText wrap="anywhere"`.'
       ],
       selection: {
@@ -4831,6 +4847,7 @@ var treeui_catalog_default = {
         "Provide a meaningful ariaLabel describing what the chart shows."
       ],
       behavior: [
+        "legend_label_is_the_flexible_column: `.t-donut-chart__legend-label` is `flex: 1 1 0` with `min-width: 0` and an ellipsis, and `.t-donut-chart__legend-value` is `flex: 0 0 auto`. A 60-character label used to push the value out of the card. The full text is carried in `title`, since truncation hides data the chart is meant to show.",
         "colors_auto_assign_from_chart_palette: --tree-color-chart-1..8, cycling by visible-segment index; per-segment color overrides",
         "hovering_a_slice_dims_the_rest_and_updates_center: the other segments get is-dimmed, the hovered donut segment grows to thickness + 4, and its legend row gets is-active",
         "hovering_a_legend_row_drives_the_same_highlight: legend items carry the same pointerenter/pointerleave handlers as the segments",
@@ -5404,6 +5421,30 @@ var treeui_catalog_default = {
       storyTitle: "Components/Data Entry/FileUpload",
       manifestFile: "docs/ai/COMPONENTS/file-upload.yaml",
       props: [
+        {
+          name: "uploadingLabel",
+          type: "string",
+          default: "Uploading files",
+          description: "Accessible name for the spinner shown while `loading`."
+        },
+        {
+          name: "uploadedAnnouncement",
+          type: "(name: string) => string",
+          default: "(n) => `${n} uploaded.`",
+          description: "What the live region announces when a file succeeds. A function, because the file name sits inside the sentence and its position differs by language."
+        },
+        {
+          name: "failedAnnouncement",
+          type: "(name: string) => string",
+          default: "(n) => `${n} failed.`",
+          description: "The same, for a failure. The error text is appended after it."
+        },
+        {
+          name: "showRejections",
+          type: "boolean",
+          default: "true",
+          description: "Render the built-in rejection messages. Turn it off when the product already surfaces `files-rejected` in its own alert \u2014 otherwise the user reads the same refusal twice, and the embedded copy is the one that cannot be placed where the product wants it. The event fires either way."
+        },
         {
           name: "clearLabel",
           type: "string",
@@ -5630,6 +5671,7 @@ var treeui_catalog_default = {
         "remove_and_retry_meet_the_44px_target: true"
       ],
       behavior: [
+        "a_rejection_follows_the_active_language: A rejection is held as DATA (the file and the reason) and formatted during render. It used to be stored as its rendered string, frozen at refusal time, so switching language afterwards left the old sentence on screen \u2014 the one piece of copy in this component that could not be retranslated.",
         "accepts_files_from_input_drop_and_paste: true",
         "multiple_false_replaces_existing_selection: true",
         "accept_maxFiles_and_maxFileSize_apply_to_all_entry_points: true",
@@ -6722,6 +6764,86 @@ var treeui_catalog_default = {
         "branchline-icons"
       ]
     },
+    {
+      name: "TIconTile",
+      aliases: [],
+      package: "@treeui/vue",
+      kind: "display",
+      category: "Data Display",
+      status: "available",
+      purpose: "A registered icon on a toned ground, sized and coloured so the glyph reads at phone size.",
+      sourceFile: "packages/vue/src/components/TIconTile.vue",
+      storyFile: "apps/docs/src/stories/IconTile.stories.ts",
+      storyTitle: "Components/Data Display/IconTile",
+      manifestFile: "docs/ai/COMPONENTS/icon-tile.yaml",
+      props: [
+        {
+          name: "name",
+          type: "TIconName",
+          default: "undefined",
+          description: "Registry name. Use the default slot for a glyph that is not registered."
+        },
+        {
+          name: "tone",
+          type: "TIconTileTone",
+          default: "brand",
+          values: [
+            "brand",
+            "neutral",
+            "success",
+            "warning",
+            "danger",
+            "info"
+          ],
+          description: "Selects the `--tree-icon-tile-accent` / `--tree-icon-tile-soft` pair. The ink is the tone's full-strength colour on its own `*-soft` tint, which is the pairing that tint is derived for."
+        },
+        {
+          name: "size",
+          type: "TSize",
+          default: "md",
+          values: [
+            "sm",
+            "md",
+            "lg"
+          ],
+          description: "2rem / 2.75rem / 3.5rem. The glyph steps with the tile (16 / 20 / 24px) so the ink keeps its proportion of the pill."
+        },
+        {
+          name: "label",
+          type: "string",
+          default: "undefined",
+          description: "Accessible name. Omit it when the tile sits beside a heading that already says the same thing \u2014 the glyph is then decoration, and a screen reader reading it twice is noise."
+        }
+      ],
+      events: [],
+      slots: [
+        {
+          name: "default"
+        }
+      ],
+      a11y: [
+        "semantic_element: span",
+        'role_img_only_when_named: With `label` the tile is `role="img"` with that name; without it, `aria-hidden`. There is no third state where a glyph is announced as nothing.',
+        "contrast_floor: 3:1, measured. An icon is a non-text UI component under WCAG 1.4.11, so the floor is 3:1 and not the 4.5:1 a badge has to clear \u2014 a badge carries a word. `packages/tokens/src/icon-tile-contrast.test.ts` measures every tone in both themes and fails the build below the floor, the same way the badge's own floor is held."
+      ],
+      behavior: [],
+      selection: {
+        keywords: [],
+        useWhen: [],
+        avoidWhen: [],
+        alternatives: []
+      },
+      setup: {
+        required: [],
+        notes: []
+      },
+      recipes: [],
+      practices: [
+        "accessible-by-default",
+        "content-alignment",
+        "token-driven"
+      ]
+    },
     {
       name: "TImage",
       aliases: [],
@@ -11048,6 +11170,33 @@ var treeui_catalog_default = {
       storyTitle: "Components/Data Display/Stat",
       manifestFile: "docs/ai/COMPONENTS/stat.yaml",
       props: [
+        {
+          name: "variant",
+          type: "TStatVariant",
+          default: "card (plain inside a TStatGroup)",
+          values: [
+            "card",
+            "plain"
+          ],
+          description: "Whether the tile draws its own card. `plain` keeps the padding, the type and the tones and drops the border, radius, shadow and background. Inside a `TStatGroup` the default flips to `plain`, because the group owns the surface; an explicit value always wins. A stat drawing its own card inside a TCard is a card within a card \u2014 doubled frame, summed padding, and eight of them read as eight objects rather than one row of figures."
+        },
+        {
+          name: "metaPlacement",
+          type: "'top' | 'bottom'",
+          default: "top",
+          description: 'Where the `meta` note sits. `top` shares the label\'s line; `bottom` puts it under the value, for the reading order of an indicator with a footnote. It is also a height fix: on the shared line a long label and a long note do not fit, the note wraps onto a line of its own ABOVE the value, and that one tile grows \u2014 the grid then stretches the whole row and every sibling shows an empty band. With `bottom` the DOM follows the visual order, so the announced order is label, value, note. Different from `emphasis="value"`, which promotes the FIGURE and takes the label down with it.'
+        },
+        {
+          name: "size",
+          type: "TSize",
+          default: "md",
+          values: [
+            "sm",
+            "md",
+            "lg"
+          ],
+          description: "Density. `sm` lowers the value's floor from 1.5rem to 1.125rem and tightens the padding, which is what lets two stats share a row on a phone \u2014 at the default floor a formatted negative currency does not fit, so a grid of six indicators collapsed into one tall column. The value still scales to its card through the container query, not to the viewport."
+        },
         {
           name: "label",
           type: "string",
@@ -11172,6 +11321,75 @@ var treeui_catalog_default = {
         "token-driven"
       ]
     },
+    {
+      name: "TStatGroup",
+      aliases: [],
+      package: "@treeui/vue",
+      kind: "layout",
+      status: "available",
+      purpose: "A row of indicators sharing one surface, with a hairline between cells.",
+      sourceFile: "packages/vue/src/components/TStatGroup.vue",
+      manifestFile: "docs/ai/COMPONENTS/stat-group.yaml",
+      props: [
+        {
+          name: "label",
+          type: "string",
+          default: "undefined",
+          description: 'Accessible name for the band. Sets `aria-label` on a `role="group"`, so the row is announced as one unit rather than as a run of unrelated figures.'
+        },
+        {
+          name: "columns",
+          type: "number",
+          default: "undefined",
+          description: "Fixed track count. Leave unset to let `minItemWidth` decide."
+        },
+        {
+          name: "minItemWidth",
+          type: "string",
+          default: "12rem",
+          description: "Smallest a cell may get before a track is dropped. Same meaning as on TGrid."
+        },
+        {
+          name: "balance",
+          type: "boolean",
+          default: "false",
+          description: "Let the last row share itself out. Off by default here, unlike TGrid, and deliberately: a stat's value scales to its own cell (`container-type: inline-size`), so a lone cell stretched across the last row prints a number visibly larger than its siblings', and size on a dashboard reads as importance. An orphan beside empty space is the lesser mistake. The real fix for a band is a track count that divides the figures \u2014 set `columns`, or a `minItemWidth` that lands on one."
+        }
+      ],
+      events: [],
+      slots: [
+        {
+          name: "default"
+        }
+      ],
+      a11y: [
+        "semantic_element: div",
+        "role: group",
+        "naming: `label` is what makes the band a named unit. Without it the group has no accessible name and is announced as an unlabelled grouping."
+      ],
+      behavior: [
+        'children_render_plain_without_being_told: The group provides a context that TStat reads, so every child defaults to `variant="plain"` inside it. The alternative is the consumer repeating `variant="plain"` on all eight, which is the alignment busywork this library exists to absorb \u2014 and which goes wrong on the ninth one added later. An explicit `variant` on a child still wins.',
+        "the_track_is_a_TGrid: Composed, not re-implemented, so `columns`, `minItemWidth` and `balance` behave exactly as they do everywhere else. `gap` is 0: the cells have to meet for the hairline to be a shared edge, and the breathing room comes from each cell's own padding.",
+        "hairlines_survive_reflow: Every cell carries a start and a top line as pseudo-elements, and the track is pulled back one pixel so the outermost pair falls outside the clipped box. A cell that reflows onto a new row keeps its top line and becomes the first of its row, where its start line is the one being clipped \u2014 nothing hanging on the outer edge, nothing doubled between neighbours. `:nth-child` cannot express this, because which cell starts a row depends on a track count only the browser knows.",
+        "pseudo_elements_not_borders: A border would land on the child's own `border-width`. The contract is that a cell in a band measures as frameless from the outside \u2014 `border-width` is actually 0 \u2014 so the lines are drawn beside the cell rather than on it."
+      ],
+      selection: {
+        keywords: [],
+        useWhen: [],
+        avoidWhen: [],
+        alternatives: []
+      },
+      setup: {
+        required: [],
+        notes: []
+      },
+      recipes: [],
+      practices: [
+        "accessible-by-default",
+        "content-alignment",
+        "token-driven"
+      ]
+    },
     {
       name: "TSteps",
       aliases: [
@@ -11401,6 +11619,18 @@ var treeui_catalog_default = {
       storyTitle: "Components/Data Display/Table",
       manifestFile: "docs/ai/COMPONENTS/table.yaml",
       props: [
+        {
+          name: "stackBelow",
+          type: "TBreakpoint",
+          default: "undefined",
+          values: [
+            "sm",
+            "md",
+            "lg",
+            "xl"
+          ],
+          description: "Below this CONTAINER width the grid becomes one block per row: the column marked `stack=\"title\"` is the block's heading, the rest sit under it, and each value carries its column's label because the header row is gone. Above it the table is unchanged, horizontal scroll included. Measured on the wrapper and not the viewport \u2014 a table can sit in a narrow panel on a wide screen, which is the case a media query cannot see. A breakpoint name and not a free length: a container query cannot read a custom property in its condition, so an arbitrary value would need a ResizeObserver per table."
+        },
         {
           name: "columns",
           type: "TTableColumn[]",
@@ -11447,6 +11677,35 @@ var treeui_catalog_default = {
           type: "(row, index) => 'default' | 'muted'",
           required: false,
           description: "Semantic per-row state applied by data, not position, so it survives sorting. `muted` recesses a row (e.g. a resource that no longer exists) via `t-table__row--muted`, written at compound specificity so it wins over the zebra/hover rules."
+        },
+        {
+          name: "rowHref",
+          type: "(row: Record<string, unknown>, index: number) => string | undefined",
+          default: "undefined",
+          description: 'The row NAVIGATES: a real `href` per row, rendered as an `<a>` in the first cell and stretched over the whole row via `::after`, so ctrl/middle-click, "open in new tab", and the status-bar URL all work and the accessible role is `link`. Mutually exclusive with `rowTo` and `rowActivatable` \u2014 dev builds warn. The affordance follows the RESOLVED target: a row whose function returns `undefined` renders no link and gets no pointer.'
+        },
+        {
+          name: "rowTo",
+          type: "(row: Record<string, unknown>, index: number) => string | undefined",
+          default: "undefined",
+          description: "Same as `rowHref`, resolved through the app's RouterLink instead of a plain `<a>`."
+        },
+        {
+          name: "rowLabel",
+          type: "(row: Record<string, unknown>, index: number) => string",
+          default: "undefined",
+          description: "Accessible name for the row's activator, per row \u2014 used by BOTH `rowHref`/`rowTo` and `rowActivatable`. Required with the former and strongly advised with the latter: without it the name is every cell concatenated, repeated for every row."
+        },
+        {
+          name: "rowActivatable",
+          type: "boolean",
+          default: "false",
+          description: 'The row ACTIVATES something that is not a route \u2014 a modal, a selection. Renders a real `<button>` in the first cell, stretched over the row the same way `rowHref` does, rather than `role="button"` on the `<tr>`, which would make every cell presentational and destroy the table\'s grid semantics. Mutually exclusive with `rowHref`/`rowTo` \u2014 dev builds warn.'
+        },
+        {
+          name: "expandedRow",
+          type: "string | number | null",
+          description: "Key of the row whose detail panel is open, matched against the identity `rowKey` resolves."
         }
       ],
       events: [
@@ -11454,6 +11713,11 @@ var treeui_catalog_default = {
           name: "sort",
           description: "Emitted when a sortable column header is clicked.",
           payload: "TTableSortState"
+        },
+        {
+          name: "row-activate",
+          description: "Emitted when an activatable row is activated without navigating \u2014 see `rowActivatable`.",
+          payload: "[row: Record<string, unknown>, index: number]"
         }
       ],
       slots: [
@@ -11468,6 +11732,10 @@ var treeui_catalog_default = {
         {
           name: "empty",
           description: "Content shown when rows array is empty."
+        },
+        {
+          name: "detail",
+          description: "Detail panel for the expanded row, rendered as a `<tr>` adjacent to its own row. Receives `{ row, index }`."
         }
       ],
       a11y: [
@@ -11478,7 +11746,11 @@ var treeui_catalog_default = {
         "keyboard: Sortable headers are focusable and activated with Enter or Space.",
         "scope: col on all th elements."
       ],
-      behavior: [],
+      behavior: [
+        'roles_are_declared_rather_than_implied: `role` is on the table, both rowgroups, every row, every column header and every cell. Each is the element\'s own implicit role, so nothing changes while `display: table` holds \u2014 they exist to survive stacked mode, where `display: block` drops the implicit table semantics in several screen readers and the block would be announced as a run of unrelated text. Measured in the accessibility tree: a stacked cell reads as "Saldo real R$ 1.284,30", carrying its column.',
+        "containment_is_scoped_to_tables_that_use_it: `container-type: inline-size` applies `contain: layout inline-size style`, so it is set only on a wrapper carrying a `stack-below` modifier rather than on every table in the library.",
+        "a_row_link_covers_the_whole_block: Outside stacked mode every cell after the first is raised above the stretched-link overlay, because those are neighbouring columns and one may hold a button. Stacked, those same cells are plain text under the title, and raising them punched a hole in the link. Inside the container query only cells that actually contain something focusable are raised \u2014 and never the first, which holds the overlay: positioning it makes it the overlay's containing block, and `inset: 0` then covers that cell alone."
+      ],
       selection: {
         keywords: [
           "table",
@@ -11513,7 +11785,9 @@ var treeui_catalog_default = {
       ],
       practices: [
         "interaction-feedback",
-        "state-clarity"
+        "accessible-by-default",
+        "state-clarity",
+        "content-alignment"
       ]
     },
     {