@treeui/mcp 0.3.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-07-15T22:47:49.302Z",
+  generatedAt: "2026-07-18T01:52:38.578Z",
   packageName: "@treeui/vue",
-  packageVersion: "0.13.0",
+  packageVersion: "0.14.0",
   decisionGuides: [
     {
       id: "single-choice",
@@ -1334,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",
@@ -2187,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."
@@ -3188,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",
@@ -3212,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",
@@ -3278,44 +3287,142 @@ var treeui_catalog_default = {
           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: "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: "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: "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: "Retry"
+        },
+        {
+          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: "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: "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"
+          name: "files-accepted",
+          description: "Emitted with only the newly accepted files, after accept/maxFiles/maxFileSize validation.",
+          payload: "File[]"
         },
         {
-          name: "files-rejected"
+          name: "files-rejected",
+          description: "Pre-acceptance validation failures. Unrelated to transport errors, which you report through `uploadState`.",
+          payload: "TFileUploadRejection[]"
+        },
+        {
+          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: [],
@@ -4370,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",
@@ -4391,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: [
@@ -4564,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: [],

package/dist/index.js

@@ -9,7 +9,7 @@ import {
   recommendComponents,
   searchComponents,
   searchRecipes
-} from "./chunk-QO4S3UWW.js";
+} from "./chunk-K6NB25EB.js";
 
 // src/catalog-source.ts
 import fs from "fs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@treeui/mcp",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Model Context Protocol server and AI catalog for TreeUI.",
   "type": "module",
   "main": "./dist/index.cjs",