@treeui/mcp 0.2.0 → 0.4.0

package/dist/index.cjs

@@ -47,9 +47,9 @@ module.exports = __toCommonJS(index_exports);
 
 // src/generated/treeui.catalog.json
 var treeui_catalog_default = {
-  generatedAt: "2026-06-26T22:57:20.487Z",
+  generatedAt: "2026-07-18T01:52:38.578Z",
   packageName: "@treeui/vue",
-  packageVersion: "0.8.0",
+  packageVersion: "0.14.0",
   decisionGuides: [
     {
       id: "single-choice",
@@ -247,6 +247,50 @@ var treeui_catalog_default = {
           notes: []
         }
       ]
+    },
+    {
+      id: "data-viz-choice",
+      question: "Visualize numeric data",
+      options: [
+        {
+          use: "TStat",
+          when: [
+            "The story is a single headline number, optionally with a trend and delta.",
+            "It is not a plot \u2014 prefer the number over a chart when one value says it."
+          ],
+          notes: []
+        },
+        {
+          use: "TSparkline",
+          when: [
+            "You want an inline micro-trend next to a value, in a table cell, or in text.",
+            "No axes, legend, or tooltip are needed."
+          ],
+          notes: []
+        },
+        {
+          use: "TChart",
+          when: [
+            "You need line, area, or bar plots with axes, gridlines, legend, and hover tooltip.",
+            "There are one or more series over shared categories."
+          ],
+          notes: []
+        },
+        {
+          use: "TDonutChart",
+          when: [
+            "The data is a part-of-whole breakdown (donut or pie)."
+          ],
+          notes: []
+        },
+        {
+          use: "TProgress",
+          when: [
+            "You are showing completion toward a single target, not a distribution or trend."
+          ],
+          notes: []
+        }
+      ]
     }
   ],
   recipes: [
@@ -296,11 +340,28 @@ var treeui_catalog_default = {
         "Set end `min` from the selected start time when appropriate."
       ]
     },
+    {
+      id: "app-shell",
+      name: "Full-viewport application shell",
+      useWhen: [
+        "The app needs a header plus side navigation that fills the whole screen and adapts to mobile.",
+        "The layout must use the full page width on large monitors, not a centered column."
+      ],
+      compose: [
+        "TAppShell",
+        "TNavMenu"
+      ],
+      notes: [
+        "`TAppShell` orchestrates the header, sidebar, and fluid content in one component; put a `TNavMenu` in its `sidebar` slot and it inherits collapsed state automatically.",
+        "Leave `mobile` unset to auto-switch at `breakpoint` (default 768px), or bind it to force mobile; the sidebar becomes an off-canvas drawer with a header menu button.",
+        "Mount it at the app root. Wrap only inner regions in `TContainer` if a specific area needs a constrained reading width."
+      ]
+    },
     {
       id: "sidebar-shell",
       name: "Sidebar application shell",
       useWhen: [
-        "The screen needs persistent section navigation."
+        "The screen needs persistent section navigation and you are composing the shell by hand."
       ],
       compose: [
         "TSidebar",
@@ -309,7 +370,8 @@ var treeui_catalog_default = {
         "TContainer"
       ],
       notes: [
-        "Let `TNavMenu` inherit collapsed state from `TSidebar` when possible."
+        "Let `TNavMenu` inherit collapsed state from `TSidebar` when possible.",
+        "Prefer `TAppShell` (recipe `app-shell`) when you also need full-viewport sizing and a responsive mobile drawer."
       ]
     },
     {
@@ -407,15 +469,38 @@ var treeui_catalog_default = {
       id: "chart-surface",
       name: "Chart surface",
       useWhen: [
-        "A screen needs data visualization, but the charting engine should stay external to TreeUI."
+        "A screen needs data visualization inside a framed, titled surface."
       ],
       compose: [
         "TCard",
         "TStack",
-        "external chart library"
+        "TChart",
+        "TSelect"
       ],
       notes: [
-        "Use TreeUI for the surrounding surface, headings, badges, filters, and empty/loading states."
+        "Prefer the native TChart / TDonutChart / TSparkline \u2014 no external charting library is required.",
+        "Use TreeUI for the surrounding surface, headings, badges, range filters, and empty/loading states.",
+        "TChart has its own loading and empty slots; you can still wrap it in TCard for the frame.",
+        "Only reach for an external chart engine for chart types TreeUI does not cover yet (e.g. scatter, heatmap)."
+      ]
+    },
+    {
+      id: "metric-dashboard",
+      name: "Metric dashboard",
+      useWhen: [
+        "A dashboard shows KPIs alongside trends and breakdowns."
+      ],
+      compose: [
+        "TStat",
+        "TSparkline",
+        "TChart",
+        "TDonutChart",
+        "TGrid"
+      ],
+      notes: [
+        "Lead with TStat tiles; embed a TSparkline in a stat's meta slot for the inline trend.",
+        "Use one TChart for the main time series and a TDonutChart for a part-of-whole split.",
+        "Keep series colors stable across the dashboard \u2014 rely on the --tree-color-chart-* order, do not remap by rank."
       ]
     },
     {
@@ -565,17 +650,27 @@ var treeui_catalog_default = {
           "Use `accept`, `multiple`, and size limits in the app layer to constrain uploads."
         ]
       },
+      TAppShell: {
+        required: [],
+        notes: [
+          "Mount at the app root; it fills the viewport (100dvh, full width) and scrolls its content region independently.",
+          "Put navigation in the `sidebar` slot (e.g. `TNavMenu`) \u2014 it inherits collapsed state from the shell provider like `TSidebar`.",
+          "Leave `mobile` unset to auto-switch to an off-canvas drawer at `breakpoint`, or bind `mobile` to control it explicitly.",
+          "Use `v-model:collapsed` for the desktop rail and `v-model:sidebarOpen` for the mobile drawer when the app persists layout state."
+        ]
+      },
       TSidebar: {
         required: [],
         notes: [
           "Pair with `TNavMenu` for app-section navigation.",
-          "Use controlled `collapsed` state when the app shell persists layout preferences."
+          "Use controlled `collapsed` state when the app shell persists layout preferences.",
+          "Prefer `TAppShell` when you also want full-viewport sizing, a top header, and a responsive mobile drawer."
         ]
       },
       TNavMenu: {
         required: [],
         notes: [
-          "When nested inside `TSidebar`, `collapsed` can be inherited from the sidebar provider."
+          "When nested inside `TSidebar` or `TAppShell`, `collapsed` can be inherited from the sidebar provider."
         ]
       },
       TTreeView: {
@@ -609,6 +704,32 @@ var treeui_catalog_default = {
           "Use `href` for native links.",
           "Use `to` when the app has vue-router and breadcrumb items should render RouterLink."
         ]
+      },
+      TChart: {
+        required: [],
+        notes: [
+          "Pass `series` as `{ name, data, color? }[]` and `labels` as a parallel `string[]` (one label per data index).",
+          "Set `type` to `line`, `area`, or `bar`; use `stacked` only with `bar`.",
+          "Series colors come from `--tree-color-chart-1..8` in order; pass `color` per series to override \u2014 do not remap colors when the series set changes.",
+          "Pass `valueFormat: (n) => string` to format axis and tooltip values (currency, compact, etc.).",
+          "No charting library or provider is required \u2014 the SVG and geometry are built in."
+        ]
+      },
+      TSparkline: {
+        required: [],
+        notes: [
+          "Pass `data` as `number[]`; there are no axes, legend, or tooltip by design.",
+          "Size it with `width`/`height`; use it inside `TStat`, table cells, or text.",
+          "Always keep a visible number nearby \u2014 a sparkline supplements a value, it does not replace it."
+        ]
+      },
+      TDonutChart: {
+        required: [],
+        notes: [
+          "Pass `segments` as `{ label, value, color? }[]`; non-positive values are dropped.",
+          "Set `thickness: 0` for a full pie; keep the default for a donut with a center readout.",
+          "Use the `center` slot (donut only) for a custom center; otherwise it shows the total or the hovered slice."
+        ]
       }
     },
     appPatterns: {
@@ -622,6 +743,9 @@ var treeui_catalog_default = {
       commonCompositions: [
         "TFormField + input-like control",
         "TGrid + TStat",
+        "TStat + TSparkline",
+        "TCard + TChart",
+        "TAppShell + TNavMenu",
         "TSidebar + TNavMenu",
         "TTable + TPagination",
         "TPricing + TPricingCard"
@@ -782,6 +906,211 @@ var treeui_catalog_default = {
       },
       recipes: []
     },
+    {
+      name: "TAppShell",
+      aliases: [],
+      package: "@treeui/vue",
+      kind: "layout",
+      category: "Layout",
+      status: "available",
+      purpose: "Full-viewport application shell with a top header, a persistent side navigation, and a fluid content area that collapses the sidebar into an off-canvas drawer on small screens.",
+      sourceFile: "packages/vue/src/components/TAppShell.vue",
+      storyFile: "apps/docs/src/stories/AppShell.stories.ts",
+      storyTitle: "Components/Layout/AppShell",
+      manifestFile: "docs/ai/COMPONENTS/app-shell.yaml",
+      props: [
+        {
+          name: "as",
+          type: "string",
+          default: "div"
+        },
+        {
+          name: "side",
+          type: "TSidebarSide",
+          default: "left",
+          values: [
+            "left",
+            "right"
+          ]
+        },
+        {
+          name: "sidebarWidth",
+          type: "string",
+          default: "17.5rem"
+        },
+        {
+          name: "collapsedWidth",
+          type: "string",
+          default: "4.75rem"
+        },
+        {
+          name: "collapsible",
+          type: "boolean",
+          default: "false"
+        },
+        {
+          name: "collapsed",
+          type: "boolean",
+          default: "undefined"
+        },
+        {
+          name: "defaultCollapsed",
+          type: "boolean",
+          default: "false"
+        },
+        {
+          name: "mobile",
+          type: "boolean",
+          default: "undefined"
+        },
+        {
+          name: "breakpoint",
+          type: "string",
+          default: "768px"
+        },
+        {
+          name: "sidebarOpen",
+          type: "boolean",
+          default: "undefined"
+        },
+        {
+          name: "defaultSidebarOpen",
+          type: "boolean",
+          default: "false"
+        },
+        {
+          name: "closeOnEscape",
+          type: "boolean",
+          default: "true"
+        },
+        {
+          name: "closeOnOverlay",
+          type: "boolean",
+          default: "true"
+        },
+        {
+          name: "showMenuButton",
+          type: "boolean",
+          default: "true"
+        },
+        {
+          name: "menuLabel",
+          type: "string",
+          default: "Open menu"
+        },
+        {
+          name: "closeLabel",
+          type: "string",
+          default: "Close menu"
+        },
+        {
+          name: "sidebarLabel",
+          type: "string",
+          default: "Sidebar"
+        }
+      ],
+      events: [
+        {
+          name: "update:collapsed"
+        },
+        {
+          name: "collapse-change"
+        },
+        {
+          name: "update:sidebarOpen"
+        },
+        {
+          name: "sidebar-open-change"
+        }
+      ],
+      slots: [
+        {
+          name: "header"
+        },
+        {
+          name: "sidebar"
+        },
+        {
+          name: "default"
+        },
+        {
+          name: "menu-icon"
+        }
+      ],
+      a11y: [
+        "role: dialog",
+        "aria_modal: true",
+        "focus_trap: true",
+        "restores_focus_on_close: true",
+        "escape_closes_when_enabled: true",
+        "menu_button_aria_expanded: true",
+        "menu_button_aria_controls_drawer: true",
+        "sidebar_labelled_by_sidebar_label: true"
+      ],
+      behavior: [
+        "fills_viewport_full_width_and_height: true",
+        "header_spans_full_width_above_sidebar_and_content: true",
+        "content_area_scrolls_independently: true",
+        "auto_switches_to_mobile_at_breakpoint_when_mobile_undefined: true",
+        "mobile_prop_forces_mobile_mode: true",
+        "mobile_sidebar_becomes_off_canvas_drawer: true",
+        "auto_menu_button_in_header_on_mobile: true",
+        "controlled_and_uncontrolled_collapsed_state: true",
+        "controlled_and_uncontrolled_sidebar_open_state: true",
+        "provides_collapsed_state_to_descendants: true",
+        "drawer_reports_collapsed_false_to_descendants_and_slots: true",
+        "left_and_right_variants: true",
+        "locks_body_scroll_while_drawer_open: true",
+        "overlay_click_closes_when_enabled: true",
+        "exposes_slot_props_with_mobile_collapsed_and_toggles: true"
+      ],
+      selection: {
+        keywords: [
+          "app shell",
+          "layout",
+          "dashboard",
+          "admin",
+          "header sidebar",
+          "full screen",
+          "responsive shell",
+          "off-canvas"
+        ],
+        useWhen: [
+          "You need a full-viewport application layout with a header, a side navigation, and a fluid content area.",
+          "The layout should use the entire page width (not a centered max-width) and switch the sidebar to an off-canvas drawer on small screens."
+        ],
+        avoidWhen: [
+          "You only need one region (just a top bar, or just a side rail) \u2014 compose TNavbar or TSidebar directly.",
+          "The page content should be centered with a readable max width \u2014 use TContainer inside the shell content instead."
+        ],
+        alternatives: [
+          {
+            component: "TSidebar",
+            when: "You want a standalone collapsible side rail without the header/content orchestration or responsive drawer."
+          },
+          {
+            component: "TNavbar",
+            when: "You only need the top application bar."
+          },
+          {
+            component: "TDrawer",
+            when: "You need a general temporary overlay panel rather than the shell's responsive navigation."
+          }
+        ]
+      },
+      setup: {
+        required: [],
+        notes: [
+          "Mount at the app root; it fills the viewport (100dvh, full width) and scrolls its content region independently.",
+          "Put navigation in the `sidebar` slot (e.g. `TNavMenu`) \u2014 it inherits collapsed state from the shell provider like `TSidebar`.",
+          "Leave `mobile` unset to auto-switch to an off-canvas drawer at `breakpoint`, or bind `mobile` to control it explicitly.",
+          "Use `v-model:collapsed` for the desktop rail and `v-model:sidebarOpen` for the mobile drawer when the app persists layout state."
+        ]
+      },
+      recipes: [
+        "app-shell"
+      ]
+    },
     {
       name: "TAvatar",
       aliases: [],
@@ -1005,15 +1334,17 @@ var treeui_catalog_default = {
         },
         {
           name: "variant",
-          type: "TVariant",
+          type: "TVariant | brand",
           default: "solid",
           values: [
             "solid",
             "outline",
             "ghost",
             "soft",
-            "danger"
-          ]
+            "danger",
+            "brand"
+          ],
+          note: "`brand` is a button-only, high-emphasis gradient variant driven by the `--tree-gradient-brand` token. Use it for the single primary CTA of a screen."
         },
         {
           name: "size",
@@ -1143,7 +1474,8 @@ var treeui_catalog_default = {
       ],
       a11y: [],
       behavior: [
-        "body_wrapper_class: tree-card__body"
+        "body_wrapper_class: t-card__body",
+        "solid_variant_rescopes_color_tokens_for_nested_content: true"
       ],
       selection: {
         keywords: [
@@ -1178,6 +1510,202 @@ var treeui_catalog_default = {
         "chart-surface"
       ]
     },
+    {
+      name: "TChart",
+      aliases: [],
+      package: "@treeui/vue",
+      kind: "data-display",
+      category: "Data Display",
+      status: "available",
+      purpose: "Lightweight cartesian chart (line, area, bar) for multi-series data, with axes, gridlines, hover tooltip, legend, and an accessible data table. No external charting dependency.",
+      sourceFile: "packages/vue/src/components/TChart.vue",
+      storyFile: "apps/docs/src/stories/Chart.stories.ts",
+      storyTitle: "Components/Data Display/Chart",
+      manifestFile: "docs/ai/COMPONENTS/chart.yaml",
+      props: [
+        {
+          name: "type",
+          type: "TChartType",
+          default: "line",
+          values: [
+            "line",
+            "area",
+            "bar"
+          ]
+        },
+        {
+          name: "series",
+          type: "TChartSeries[]",
+          default: "[]",
+          note: "Each item is { name: string; data: number[]; color?: string }."
+        },
+        {
+          name: "labels",
+          type: "string[]",
+          default: "[]",
+          note: "X-axis categories, aligned index-for-index to each series' data."
+        },
+        {
+          name: "height",
+          type: "number",
+          default: "260",
+          note: "Width is fluid (measured via ResizeObserver)."
+        },
+        {
+          name: "smooth",
+          type: "boolean",
+          default: "false",
+          note: "Curved line/area."
+        },
+        {
+          name: "stacked",
+          type: "boolean",
+          default: "false",
+          note: "Stacks bar series; ignored for line/area. Negative values are clamped to 0 in stacked mode (grouped mode renders them)."
+        },
+        {
+          name: "showGrid",
+          type: "boolean",
+          default: "true"
+        },
+        {
+          name: "showLegend",
+          type: "boolean",
+          default: "auto (true when more than one series)"
+        },
+        {
+          name: "showXAxis",
+          type: "boolean",
+          default: "true"
+        },
+        {
+          name: "showYAxis",
+          type: "boolean",
+          default: "true"
+        },
+        {
+          name: "showTooltip",
+          type: "boolean",
+          default: "true"
+        },
+        {
+          name: "showPoints",
+          type: "boolean",
+          default: "false",
+          note: "Always draw markers on line/area points."
+        },
+        {
+          name: "yTicks",
+          type: "number",
+          default: "5"
+        },
+        {
+          name: "valueFormat",
+          type: "(value: number) => string",
+          default: "locale integers for |value| >= 1000"
+        },
+        {
+          name: "minY",
+          type: "number",
+          default: "auto"
+        },
+        {
+          name: "maxY",
+          type: "number",
+          default: "auto"
+        },
+        {
+          name: "animated",
+          type: "boolean",
+          default: "true",
+          note: "Draw-in animation; disabled under prefers-reduced-motion."
+        },
+        {
+          name: "loading",
+          type: "boolean",
+          default: "false"
+        },
+        {
+          name: "ariaLabel",
+          type: "string",
+          default: "auto-generated summary"
+        }
+      ],
+      events: [
+        {
+          name: "point-click",
+          payload: "{ index: number; label: string; values: { name: string; value: number; color: string }[] }"
+        }
+      ],
+      slots: [
+        {
+          name: "legend"
+        },
+        {
+          name: "tooltip"
+        },
+        {
+          name: "empty"
+        }
+      ],
+      a11y: [
+        "SVG is aria-hidden; a visually-hidden <table> mirrors the series data for assistive tech.",
+        "Legend defaults on for multiple series so identity is not color-only.",
+        "Provide a meaningful ariaLabel describing what the chart shows."
+      ],
+      behavior: [
+        "colors_auto_assign_from_chart_palette: --tree-color-chart-1..8, cycling; per-series color overrides",
+        "bar_zero_baseline: true",
+        "line_domain_uses_nice_ticks: true",
+        "hover_shows_crosshair_and_tooltip: true"
+      ],
+      selection: {
+        keywords: [
+          "chart",
+          "graph",
+          "line chart",
+          "area chart",
+          "bar chart",
+          "plot",
+          "dashboard",
+          "time series",
+          "analytics"
+        ],
+        useWhen: [
+          "You need a line, area, or bar chart with axes, gridlines, legend, and a hover tooltip.",
+          "One or more series share a set of category labels."
+        ],
+        avoidWhen: [
+          "A single value tells the story \u2014 use TStat.",
+          "You only need an inline trend with no axes \u2014 use TSparkline.",
+          "The data is a part-of-whole breakdown \u2014 use TDonutChart."
+        ],
+        alternatives: [
+          {
+            component: "TSparkline",
+            when: "The trend should be inline and axis-less."
+          },
+          {
+            component: "TDonutChart",
+            when: "The data is proportional (parts of a whole)."
+          }
+        ]
+      },
+      setup: {
+        required: [],
+        notes: [
+          "Pass `series` as `{ name, data, color? }[]` and `labels` as a parallel `string[]` (one label per data index).",
+          "Set `type` to `line`, `area`, or `bar`; use `stacked` only with `bar`.",
+          "Series colors come from `--tree-color-chart-1..8` in order; pass `color` per series to override \u2014 do not remap colors when the series set changes.",
+          "Pass `valueFormat: (n) => string` to format axis and tooltip values (currency, compact, etc.).",
+          "No charting library or provider is required \u2014 the SVG and geometry are built in."
+        ]
+      },
+      recipes: [
+        "chart-surface",
+        "metric-dashboard"
+      ]
+    },
     {
       name: "TCheckbox",
       aliases: [],
@@ -1661,9 +2189,14 @@ var treeui_catalog_default = {
           "The page shell should stay full-width while content stays readable."
         ],
         avoidWhen: [
-          "You need internal spacing between children."
+          "You need internal spacing between children.",
+          "You are laying out a whole screen \u2014 reach for TPage, which adds page padding and vertical rhythm."
         ],
         alternatives: [
+          {
+            component: "TPage",
+            when: "You want a full page region with block padding and vertical spacing between sections, not just a width constraint."
+          },
           {
             component: "TStack",
             when: "The main need is vertical or horizontal spacing."
@@ -2149,6 +2682,142 @@ var treeui_catalog_default = {
       },
       recipes: []
     },
+    {
+      name: "TDonutChart",
+      aliases: [],
+      package: "@treeui/vue",
+      kind: "data-display",
+      category: "Data Display",
+      status: "available",
+      purpose: "Part-of-whole chart rendered as a donut (default) or full pie, with a legend, percentages, an interactive center readout, and an accessible label.",
+      sourceFile: "packages/vue/src/components/TDonutChart.vue",
+      storyFile: "apps/docs/src/stories/DonutChart.stories.ts",
+      storyTitle: "Components/Data Display/Donut Chart",
+      manifestFile: "docs/ai/COMPONENTS/donut-chart.yaml",
+      props: [
+        {
+          name: "segments",
+          type: "TDonutSegment[]",
+          default: "[]",
+          note: "Each item is { label: string; value: number; color?: string }. Non-positive values are omitted."
+        },
+        {
+          name: "size",
+          type: "number",
+          default: "200",
+          note: "Square canvas in px."
+        },
+        {
+          name: "thickness",
+          type: "number",
+          default: "26",
+          note: "Ring thickness; 0 renders a full pie."
+        },
+        {
+          name: "gap",
+          type: "number",
+          default: "2",
+          note: "Gap between slices, in degrees."
+        },
+        {
+          name: "rounded",
+          type: "boolean",
+          default: "false",
+          note: "Round the ends of donut segments (widens the gap to make room). Best with a thinner ring."
+        },
+        {
+          name: "showLegend",
+          type: "boolean",
+          default: "true"
+        },
+        {
+          name: "showPercent",
+          type: "boolean",
+          default: "true"
+        },
+        {
+          name: "centerLabel",
+          type: "string",
+          default: "Total",
+          note: "Donut only; ignored for pie."
+        },
+        {
+          name: "centerValue",
+          type: "string | number",
+          default: "auto (sum of values)"
+        },
+        {
+          name: "valueFormat",
+          type: "(value: number) => string",
+          default: "locale integers for |value| >= 1000"
+        },
+        {
+          name: "loading",
+          type: "boolean",
+          default: "false"
+        },
+        {
+          name: "ariaLabel",
+          type: "string",
+          default: "auto-generated summary"
+        }
+      ],
+      events: [],
+      slots: [
+        {
+          name: "center"
+        },
+        {
+          name: "empty"
+        }
+      ],
+      a11y: [
+        "Renders role=img with an aria-label summarizing the chart.",
+        "Legend + percentages give a non-visual reading of each slice."
+      ],
+      behavior: [
+        "colors_auto_assign_from_chart_palette: --tree-color-chart-1..8, cycling; per-segment color overrides",
+        "hovering_a_slice_dims_the_rest_and_updates_center: true",
+        "center_shows_total_or_the_hovered_segment: true"
+      ],
+      selection: {
+        keywords: [
+          "donut",
+          "doughnut",
+          "pie",
+          "proportion",
+          "share",
+          "breakdown",
+          "part of whole",
+          "percentage"
+        ],
+        useWhen: [
+          "You are showing how a total splits into a handful of categories.",
+          "A donut center readout (total or hovered slice) is useful."
+        ],
+        avoidWhen: [
+          "There are many categories or precise comparison matters \u2014 use TChart bars.",
+          "The data is a trend over time \u2014 use TChart or TSparkline."
+        ],
+        alternatives: [
+          {
+            component: "TChart",
+            when: "Precise magnitude comparison across categories is needed (bars)."
+          }
+        ]
+      },
+      setup: {
+        required: [],
+        notes: [
+          "Pass `segments` as `{ label, value, color? }[]`; non-positive values are dropped.",
+          "Set `thickness: 0` for a full pie; keep the default for a donut with a center readout.",
+          "Use the `center` slot (donut only) for a custom center; otherwise it shows the total or the hovered slice."
+        ]
+      },
+      recipes: [
+        "metric-dashboard"
+      ]
+    },
     {
       name: "TDrawer",
       aliases: [],
@@ -2350,6 +3019,16 @@ var treeui_catalog_default = {
           name: "label",
           type: "string",
           default: ""
+        },
+        {
+          name: "align",
+          type: "TDropdownAlign",
+          default: "start",
+          values: [
+            "start",
+            "end"
+          ],
+          note: "Horizontal alignment of the menu relative to the trigger. Use `end` when the trigger sits near the right edge of a clipping container (e.g. a table actions column)."
         }
       ],
       events: [
@@ -2385,7 +3064,8 @@ var treeui_catalog_default = {
       behavior: [
         "outside_click_closes_menu: true",
         "focus_restores_on_close: true",
-        "chevron_rotates_when_open: true"
+        "chevron_rotates_when_open: true",
+        "menu_grows_to_fit_items_without_wrapping: true"
       ],
       selection: {
         keywords: [
@@ -2515,7 +3195,7 @@ var treeui_catalog_default = {
       kind: "form",
       category: "Form",
       status: "available",
-      purpose: "Composable dropzone and file picker with browse, drag-and-drop, and Ctrl+V paste support.",
+      purpose: "Composable dropzone and file picker with browse, drag-and-drop, and Ctrl+V paste support, plus per-file upload state: progress, remaining time, thumbnails, and independent per-file retry/resume.",
       sourceFile: "packages/vue/src/components/TFileUpload.vue",
       storyFile: "apps/docs/src/stories/FileUpload.stories.ts",
       storyTitle: "Components/Form/FileUpload",
@@ -2539,12 +3219,14 @@ var treeui_catalog_default = {
         {
           name: "disabled",
           type: "boolean",
-          default: "false"
+          default: "false",
+          description: "The ONLY prop that gates interaction. Disables the dropzone, the native input, Clear all, and every per-row Remove/Retry."
         },
         {
           name: "loading",
           type: "boolean",
-          default: "false"
+          default: "false",
+          description: "Presentational only. Applies `is-loading`, `aria-busy` on the dropzone, and the corner spinner. It gates NO interaction \u2014 see behavior.loading_is_presentational."
         },
         {
           name: "invalid",
@@ -2577,72 +3259,170 @@ var treeui_catalog_default = {
           default: "Drop files here"
         },
         {
-          name: "description",
+          name: "description",
+          type: "string",
+          default: "Click to browse, drag and drop, or paste with Ctrl+V."
+        },
+        {
+          name: "buttonLabel",
+          type: "string",
+          default: "Browse files"
+        },
+        {
+          name: "filesLabel",
+          type: "string",
+          default: "Selected files"
+        },
+        {
+          name: "paste",
+          type: "boolean",
+          default: "true"
+        },
+        {
+          name: "drop",
+          type: "boolean",
+          default: "true"
+        },
+        {
+          name: "showFileList",
+          type: "boolean",
+          default: "true"
+        },
+        {
+          name: "uploadState",
+          type: "TFileUploadStateSource",
+          default: "none",
+          description: "Per-file transport state, keyed by File OBJECT IDENTITY. Accepts a ReadonlyMap<File, TFileUploadState> or a (file, index) => TFileUploadState | undefined resolver. Omit it and the component renders exactly as before: no bars, no status lines, no retry."
+        },
+        {
+          name: "dragLabel",
+          type: "string",
+          default: "Release to upload",
+          description: "Replaces `label` in the dropzone while an acceptable drag is over it. Set it to the same value as `label` to opt out of the text swap."
+        },
+        {
+          name: "dragRejectLabel",
           type: "string",
-          default: "Click to browse, drag and drop, or paste with Ctrl+V."
+          default: "This file type is not accepted",
+          description: "Replaces `label` while a drag that cannot work is over the dropzone. Only reachable when drag-reject detection is possible \u2014 see behavior.drag_reject_detection_is_mime_only."
         },
         {
-          name: "buttonLabel",
-          type: "string",
-          default: "Browse files"
+          name: "thumbnails",
+          type: "boolean",
+          default: "true",
+          description: "Mint object-URL previews and decode dimensions for image/* files. Set false when you always supply `state.thumbnailUrl` yourself."
         },
         {
-          name: "filesLabel",
+          name: "maxThumbnailSize",
+          type: "number | null",
+          default: "10 * 1024 * 1024",
+          description: "Skip auto-thumbnailing above this byte size. null removes the cap."
+        },
+        {
+          name: "retryLabel",
           type: "string",
-          default: "Selected files"
+          default: "Retry"
         },
         {
-          name: "paste",
-          type: "boolean",
-          default: "true"
+          name: "resumeLabel",
+          type: "(percent: number) => string",
+          default: "(percent) => `Resume from ${percent}%`",
+          description: "Receives Math.round(state.progress). Used only when state.resumable === true AND state.progress is a number."
         },
         {
-          name: "drop",
-          type: "boolean",
-          default: "true"
+          name: "remainingTimeFormat",
+          type: "(remainingMs: number) => string",
+          default: "5s/60s/60min thresholds \u2014 see behavior.remaining_time_strings",
+          description: "Formats state.remainingMs. Ignored for a row that supplies state.remainingLabel."
         },
         {
-          name: "showFileList",
-          type: "boolean",
-          default: "true"
+          name: "statusLabels",
+          type: "Partial<Record<TFileUploadStatus, string>>",
+          default: "{}",
+          description: "MERGED over the defaults { pending: Waiting, uploading: Uploading, paused: Paused, error: Upload failed, success: Uploaded } \u2014 pass only the keys you override."
         }
       ],
       events: [
         {
-          name: "update:modelValue"
+          name: "update:modelValue",
+          description: "Emitted with the next file list when files are added, removed, or cleared.",
+          payload: "File[]"
+        },
+        {
+          name: "files-accepted",
+          description: "Emitted with only the newly accepted files, after accept/maxFiles/maxFileSize validation.",
+          payload: "File[]"
         },
         {
-          name: "files-accepted"
+          name: "files-rejected",
+          description: "Pre-acceptance validation failures. Unrelated to transport errors, which you report through `uploadState`.",
+          payload: "TFileUploadRejection[]"
         },
         {
-          name: "files-rejected"
+          name: "retry",
+          description: "Emitted when a row's retry affordance is activated. Pure intent \u2014 the component performs no upload. Use `payload.mode` ('resume' | 'restart'); it reports the affordance the component ACTUALLY DREW, so never re-derive it from your own state.",
+          payload: "TFileUploadRetryPayload"
+        },
+        {
+          name: "cancel",
+          description: "Emitted ONLY for rows whose status is 'uploading' or 'paused', immediately BEFORE the `update:modelValue` that drops them \u2014 so the file is still in the list when your handler runs and you can abort the request. `reason` is 'remove' for one row or 'clear' (one event per in-flight file) for Clear all.",
+          payload: "TFileUploadCancelPayload"
         }
       ],
       slots: [
         {
-          name: "icon"
+          name: "icon",
+          description: "Replaces the dropzone icon."
         },
         {
-          name: "default"
+          name: "default",
+          description: "Replaces the dropzone body. Receives `{ files, isDragActive, isDragReject, openFileDialog, clearFiles }`."
         },
         {
-          name: "file"
+          name: "file",
+          description: "Full row override. Receives all of TFileUploadFileSlotProps, including every derived label, so a custom row re-derives nothing."
         },
         {
-          name: "actions"
+          name: "file-status",
+          description: "Replaces ONLY the progress bar + status line + error block inside the default row. Receives TFileUploadFileSlotProps. Name, meta, thumbnail, Retry, and Remove keep rendering. Ignored when the `file` slot is provided."
+        },
+        {
+          name: "actions",
+          description: "Footer actions. Receives `{ files, openFileDialog, clearFiles }` \u2014 no upload state."
         }
       ],
       a11y: [
         "dropzone_role: button",
         "keyboard_activation: Enter_and_Space_open_the_file_picker",
         "supports_paste_when_component_is_focused: true",
-        "file_feedback_announced_via_live_region: true"
+        "file_feedback_announced_via_live_region: true",
+        "aria_busy_on_dropzone_tracks_loading_prop: true",
+        "aria_busy_on_row_tracks_that_rows_uploading_status: true",
+        "per_row_progressbar_is_labelled_with_status_and_filename: e.g. 'Uploading hero.png' \u2014 every row's bar has a distinct accessible name.",
+        "terminal_transitions_announced_with_filenames: One polite root live region (`role=log`) announces only success/error, e.g. 'alpha.txt uploaded.' / 'alpha.txt failed. Connection lost.'",
+        "repeated_identical_messages_are_still_announced: The log appends each message as a new node rather than overwriting one string, so a retry that fails with the byte-identical error still mutates the region and is announced. It is not aria-atomic: only the appended message is read, and the trimmed history (5 most recent) is not.",
+        "percentages_are_never_announced: Percent and ETA live in non-live text; the value reaches assistive tech through the progressbar's aria-valuenow.",
+        "retry_button_is_described_by_its_row_error: Announces 'Resume from 90%, Connection lost at 90%'.",
+        "focus_is_rescued_when_retry_unmounts: Flipping error -> uploading removes the focused Retry; focus moves to that row's Remove (or the dropzone), and only when it was genuinely lost.",
+        "remove_and_retry_meet_the_44px_target: true"
       ],
       behavior: [
         "accepts_files_from_input_drop_and_paste: true",
         "multiple_false_replaces_existing_selection: true",
         "accept_maxFiles_and_maxFileSize_apply_to_all_entry_points: true",
-        "selected_files_can_be_removed_or_cleared: true"
+        "selected_files_can_be_removed_or_cleared: true",
+        "upload_state_is_keyed_by_file_identity: Both source shapes key on the File object, never on index or name. Key your own store with the File objects you receive from `files-accepted`.",
+        "a_lookup_miss_renders_nothing: An unknown File yields `undefined` and the row falls back to name + meta only \u2014 no bar, no status, no retry. This fail-blank is deliberate: it is the back-compat path and it fails loudly instead of showing another file's percentage.",
+        "loading_is_presentational: BREAKING since 0.14.0 \u2014 `loading` no longer disables anything. It was freezing the dropzone, Clear all, and every Remove, which blocked removing file 1 while file 4 uploaded. Use `:disabled` to reproduce the old behavior; prefer `uploadState` and freeze nothing.",
+        "each_file_has_an_independent_track: One row's error, progress, or retry never gates another's. Remove stays enabled for in-flight rows and emits `cancel` so you can abort.",
+        "errors_are_per_row: Transport errors go in `state.error` and render under their own row. They never enter the dropzone feedback list, which Remove and Clear all wipe.",
+        "drag_feedback_has_three_signals: Border, glow, and a text swap to `dragLabel` \u2014 all three fire together, including when files are already listed.",
+        "drag_reject_detection_is_mime_only: `is-drag-reject` + `dragRejectLabel` require every `accept` token to be a MIME token; with any `.ext` token the dropzone stays neutral, because a drag exposes only `.type`. A mixed drag (one good file, one bad) is NOT rejected, and the drop is never blocked \u2014 rejected files always get the normal `files-rejected` explanation.",
+        "progress_bar_visibility: Shown on uploading/paused/error, and on success only with numeric progress. 'uploading' without progress is indeterminate; paused/error without progress is a determinate 0 \u2014 an errored bar must never animate.",
+        "the_bar_is_never_reset_on_error: It holds `state.progress` in the error tone. That retained 90% is what makes the resume promise legible.",
+        "remaining_time_strings: < 5000ms -> 'Less than 5s left'; < 60s -> 'About 12s left'; < 60min -> 'About 2 min left'; else 'About 2h left'. Negative, NaN, and Infinity render nothing.",
+        "status_line_composition: Joins the present parts with ' \xB7 ': 'Uploading \xB7 62% \xB7 About 12s left' while uploading, 'Upload failed \xB7 2.1 MB of 2.4 MB uploaded' on a resumable error.",
+        "thumbnails_are_client_only: Object URLs are minted after mount and revoked on removal and unmount. SSR and the hydrating render both show the extension chip, so there is no mismatch."
       ],
       selection: {
         keywords: [],
@@ -2885,7 +3665,8 @@ var treeui_catalog_default = {
       },
       recipes: [
         "date-range-form",
-        "stat-grid"
+        "stat-grid",
+        "metric-dashboard"
       ]
     },
     {
@@ -3696,7 +4477,7 @@ var treeui_catalog_default = {
           name: "items",
           type: "TNavMenuItem[]",
           default: "[]",
-          note: "Array of `{ label, value, shortLabel?, description?, icon?, to?, badge?, disabled? }`."
+          note: "Array of `{ label, value, shortLabel?, description?, icon?, to?, badge?, disabled?, exact? }`."
         },
         {
           name: "size",
@@ -3717,6 +4498,12 @@ var treeui_catalog_default = {
           name: "disabled",
           type: "boolean",
           default: "false"
+        },
+        {
+          name: "exact",
+          type: "boolean",
+          default: "true",
+          note: "Default active-match strategy for router-link items. `true` keeps only the exactly-active route highlighted (prevents prefix matches from lighting up several items at once). Override per item via `TNavMenuItem.exact`."
         }
       ],
       events: [
@@ -3775,10 +4562,11 @@ var treeui_catalog_default = {
       setup: {
         required: [],
         notes: [
-          "When nested inside `TSidebar`, `collapsed` can be inherited from the sidebar provider."
+          "When nested inside `TSidebar` or `TAppShell`, `collapsed` can be inherited from the sidebar provider."
         ]
       },
       recipes: [
+        "app-shell",
         "sidebar-shell"
       ]
     },
@@ -3889,6 +4677,193 @@ var treeui_catalog_default = {
       },
       recipes: []
     },
+    {
+      name: "TPage",
+      aliases: [],
+      package: "@treeui/vue",
+      kind: "layout",
+      category: "Layout",
+      status: "available",
+      purpose: "Semantic page region under the app shell: block padding, a centered max-width content column, and standardized vertical rhythm between sections.",
+      sourceFile: "packages/vue/src/components/TPage.vue",
+      storyFile: "apps/docs/src/stories/Page.stories.ts",
+      storyTitle: "Components/Layout/Page",
+      manifestFile: "docs/ai/COMPONENTS/page.yaml",
+      props: [
+        {
+          name: "as",
+          type: "string",
+          default: "div"
+        },
+        {
+          name: "width",
+          type: "TContainerSize",
+          default: "lg",
+          values: [
+            "sm",
+            "md",
+            "lg",
+            "xl",
+            "full"
+          ],
+          note: "Max-width of the centered content column. Mirrors TContainer sizes."
+        },
+        {
+          name: "padded",
+          type: "boolean",
+          default: "true",
+          note: "Adds vertical (block) padding on the region and horizontal padding on the inner column."
+        },
+        {
+          name: "gap",
+          type: "TPageGap",
+          default: "lg",
+          values: [
+            "sm",
+            "md",
+            "lg"
+          ],
+          note: "Vertical spacing between direct children (e.g. a TPageHeader and content sections)."
+        }
+      ],
+      events: [],
+      slots: [
+        {
+          name: "default"
+        }
+      ],
+      a11y: [
+        "Structural wrapper only; landmark semantics come from `as` and the surrounding app shell (avoid nesting a second `main`)."
+      ],
+      behavior: [
+        "centers_content_column_by_width: true",
+        "applies_block_padding_when_padded: true",
+        "spaces_children_vertically_by_gap: true"
+      ],
+      selection: {
+        keywords: [
+          "page",
+          "page shell",
+          "content column",
+          "screen layout"
+        ],
+        useWhen: [
+          "You want a standard screen region under the app shell with consistent max width, page padding, and vertical rhythm between sections."
+        ],
+        avoidWhen: [
+          "You only need a bare width constraint with no page padding or child spacing."
+        ],
+        alternatives: [
+          {
+            component: "TContainer",
+            when: "You just need a centered max-width wrapper without page-level block padding or child spacing."
+          },
+          {
+            component: "TStack",
+            when: "You only need to space a group of children, not lay out a whole page."
+          }
+        ]
+      },
+      setup: {
+        required: [],
+        notes: []
+      },
+      recipes: []
+    },
+    {
+      name: "TPageHeader",
+      aliases: [],
+      package: "@treeui/vue",
+      kind: "layout",
+      category: "Layout",
+      status: "available",
+      purpose: "Canonical page title block: heading, optional subtitle, and a right-aligned actions area, so title hierarchy and alignment stay consistent across screens.",
+      sourceFile: "packages/vue/src/components/TPageHeader.vue",
+      storyFile: "apps/docs/src/stories/PageHeader.stories.ts",
+      storyTitle: "Components/Layout/PageHeader",
+      manifestFile: "docs/ai/COMPONENTS/page-header.yaml",
+      props: [
+        {
+          name: "title",
+          type: "string",
+          default: "",
+          note: "Rendered inside the heading element. Overridden by the `title` slot."
+        },
+        {
+          name: "subtitle",
+          type: "string",
+          default: ""
+        },
+        {
+          name: "level",
+          type: "1 | 2 | 3 | 4 | 5 | 6",
+          default: "1",
+          note: "Heading level for the title element. Default `1` treats it as the page title; lower it when the page already has an h1."
+        },
+        {
+          name: "as",
+          type: "string",
+          default: "header"
+        }
+      ],
+      events: [],
+      slots: [
+        {
+          name: "breadcrumb"
+        },
+        {
+          name: "title"
+        },
+        {
+          name: "subtitle"
+        },
+        {
+          name: "actions"
+        },
+        {
+          name: "default"
+        }
+      ],
+      a11y: [
+        "Title renders as a real heading element (`h1`\u2013`h6`) chosen by `level`; keep one h1 per page.",
+        "Actions area holds standard focusable controls (e.g. TButton) \u2014 no custom roles added."
+      ],
+      behavior: [
+        "title_and_subtitle_optional: true",
+        "heading_level_controlled_by_level: true",
+        "actions_area_right_aligned_and_wraps: true",
+        "default_slot_renders_below_heading: true"
+      ],
+      selection: {
+        keywords: [
+          "page header",
+          "title bar",
+          "page title",
+          "heading and actions"
+        ],
+        useWhen: [
+          "A screen needs a title (and optional subtitle) with a right-aligned actions area in a consistent hierarchy."
+        ],
+        avoidWhen: [
+          "You need cross-page hierarchy or navigation trails rather than a single page title."
+        ],
+        alternatives: [
+          {
+            component: "TBreadcrumb",
+            when: "You are showing where the page sits in a hierarchy, not its title."
+          },
+          {
+            component: "TNavbar",
+            when: "You need a top application bar, not a per-page title block."
+          }
+        ]
+      },
+      setup: {
+        required: [],
+        notes: []
+      },
+      recipes: []
+    },
     {
       name: "TPagination",
       aliases: [],
@@ -4605,7 +5580,8 @@ var treeui_catalog_default = {
         "check_icon_on_selected_option: true",
         "outside_click_closes_dropdown: true",
         "focus_restores_on_close: true",
-        "numeric_values_supported_without_string_coercion: true"
+        "numeric_values_supported_without_string_coercion: true",
+        "listbox_flips_above_trigger_when_space_below_is_insufficient: true"
       ],
       selection: {
         keywords: [
@@ -4638,7 +5614,9 @@ var treeui_catalog_default = {
           "Use `placeholder` when no selection has been made."
         ]
       },
-      recipes: []
+      recipes: [
+        "chart-surface"
+      ]
     },
     {
       name: "TSelectableList",
@@ -4860,7 +5838,8 @@ var treeui_catalog_default = {
         "controlled_and_uncontrolled_collapsed_state: true",
         "provides_collapsed_state_to_descendants: true",
         "left_and_right_variants: true",
-        "exposes_slot_props_with_collapsed_state: true"
+        "exposes_slot_props_with_collapsed_state: true",
+        "collapsed_state_centers_header_and_footer_content: true"
       ],
       selection: {
         keywords: [
@@ -4885,7 +5864,8 @@ var treeui_catalog_default = {
         required: [],
         notes: [
           "Pair with `TNavMenu` for app-section navigation.",
-          "Use controlled `collapsed` state when the app shell persists layout preferences."
+          "Use controlled `collapsed` state when the app shell persists layout preferences.",
+          "Prefer `TAppShell` when you also want full-viewport sizing, a top header, and a responsive mobile drawer."
         ]
       },
       recipes: [
@@ -4955,6 +5935,129 @@ var treeui_catalog_default = {
       },
       recipes: []
     },
+    {
+      name: "TSparkline",
+      aliases: [],
+      package: "@treeui/vue",
+      kind: "data-display",
+      category: "Data Display",
+      status: "available",
+      purpose: "Tiny, axis-less inline trend chart (line, area, or bar) sized for stat tiles, table cells, and running text.",
+      sourceFile: "packages/vue/src/components/TSparkline.vue",
+      storyFile: "apps/docs/src/stories/Sparkline.stories.ts",
+      storyTitle: "Components/Data Display/Sparkline",
+      manifestFile: "docs/ai/COMPONENTS/sparkline.yaml",
+      props: [
+        {
+          name: "data",
+          type: "number[]",
+          default: "[]"
+        },
+        {
+          name: "type",
+          type: "line | area | bar",
+          default: "line"
+        },
+        {
+          name: "color",
+          type: "string",
+          default: "var(--tree-color-chart-1)",
+          note: "Any CSS color."
+        },
+        {
+          name: "width",
+          type: "number",
+          default: "120"
+        },
+        {
+          name: "height",
+          type: "number",
+          default: "32"
+        },
+        {
+          name: "smooth",
+          type: "boolean",
+          default: "false",
+          note: "Curved line/area."
+        },
+        {
+          name: "strokeWidth",
+          type: "number",
+          default: "2",
+          note: "Line/area only."
+        },
+        {
+          name: "min",
+          type: "number",
+          default: "data min"
+        },
+        {
+          name: "max",
+          type: "number",
+          default: "data max"
+        },
+        {
+          name: "showLastPoint",
+          type: "boolean",
+          default: "false",
+          note: "Marker on the final point (line/area)."
+        },
+        {
+          name: "ariaLabel",
+          type: "string",
+          default: "Trend sparkline"
+        }
+      ],
+      events: [],
+      slots: [],
+      a11y: [
+        "Renders role=img with an aria-label; pass a specific one for meaningful trends.",
+        "Pair with a visible number \u2014 a sparkline supplements a value, it does not replace it."
+      ],
+      behavior: [
+        "no_axes_or_legend: true",
+        "flat_series_renders_centered: true",
+        "scales_to_intrinsic_width_and_height: true"
+      ],
+      selection: {
+        keywords: [
+          "sparkline",
+          "mini chart",
+          "inline chart",
+          "micro trend",
+          "trend line",
+          "table chart"
+        ],
+        useWhen: [
+          "You want a compact trend beside a value, in a table cell, or inline in text.",
+          "No axes, legend, or tooltip are required."
+        ],
+        avoidWhen: [
+          "You need axes, multiple labeled series, or a tooltip \u2014 use TChart."
+        ],
+        alternatives: [
+          {
+            component: "TChart",
+            when: "The chart needs axes, a legend, or a tooltip."
+          },
+          {
+            component: "TStat",
+            when: "A single value with a trend badge is enough."
+          }
+        ]
+      },
+      setup: {
+        required: [],
+        notes: [
+          "Pass `data` as `number[]`; there are no axes, legend, or tooltip by design.",
+          "Size it with `width`/`height`; use it inside `TStat`, table cells, or text.",
+          "Always keep a visible number nearby \u2014 a sparkline supplements a value, it does not replace it."
+        ]
+      },
+      recipes: [
+        "metric-dashboard"
+      ]
+    },
     {
       name: "TSpinner",
       aliases: [],
@@ -5208,6 +6311,10 @@ var treeui_catalog_default = {
           {
             component: "TCard",
             when: "The content is not a metric."
+          },
+          {
+            component: "TSparkline",
+            when: "You want to show the metric's trend as an inline mini-chart."
           }
         ]
       },
@@ -5216,7 +6323,8 @@ var treeui_catalog_default = {
         notes: []
       },
       recipes: [
-        "stat-grid"
+        "stat-grid",
+        "metric-dashboard"
       ]
     },
     {