@devalok/shilp-sutra 0.55.1 → 0.57.0

package/mcp-manifest.json

@@ -2,7 +2,7 @@
   "$schema": "./mcp-manifest.schema.json",
   "manifestVersion": "1.2.0",
   "package": "@devalok/shilp-sutra",
-  "packageVersion": "0.55.1",
+  "packageVersion": "0.57.0",
   "components": {
     "accordion": {
       "displayName": "Accordion",
@@ -603,7 +603,7 @@
           "**Status + Ring + Badge are independent** — you can stack all three on one Avatar. They render in separate layers so they don't conflict visually.",
           "**Use with AvatarGroup:** AvatarGroup applies its own `size` to children. If your Avatar has an explicit `size`, it overrides AvatarGroup's default — keep it consistent across the group.",
           "**AvatarFallback colorSeed:** Deterministic background color from the seed string — identical user IDs produce identical backgrounds across renders. Useful for user-identifying avatars without photos.",
-          "**Ring offset color:** The ring renders with `ring-offset` matching the current surface — it assumes the Avatar sits on `bg-surface-raised`. On other backgrounds, add a ring-offset className to compensate."
+          "**Ring offset color:** The ring renders with `ring-offset` matching the current surface — it assumes the Avatar sits on `bg-surface-panel`. On other backgrounds, add a ring-offset className to compensate."
         ],
         "parts": [
           {
@@ -1427,7 +1427,7 @@
         "<Button variant=\"solid\" color=\"error\" startIcon={<Icon icon={IconTrash} />} loading={isDeleting}>\n  Delete project\n</Button>\n<Button variant=\"soft\" color=\"success\" startIcon={<Icon icon={IconCheck} />}>Approved</Button>\n<Button variant=\"soft\" color=\"warning\" size=\"compact-sm\" shape=\"pill\">Overdue</Button>"
       ],
       "gotchas": [
-        "**Prefer `variant=\"soft\"` over `variant=\"outline\"` for secondary actions.** Soft (tinted step-3 bg, step-11 text) is the Devalok-recommended default — it feels warmer and brand-consistent. Use `outline` only when soft's tint would disappear (on colored/surface-raised bg), in toolbar/icon-dense contexts, or when you need outline's stronger hierarchy next to a primary action.",
+        "**Prefer `variant=\"soft\"` over `variant=\"outline\"` for secondary actions.** Soft (tinted step-3 bg, step-11 text) is the Devalok-recommended default — it feels warmer and brand-consistent. Use `outline` only when soft's tint would disappear (on colored/surface-panel bg), in toolbar/icon-dense contexts, or when you need outline's stronger hierarchy next to a primary action.",
         "DO NOT use variant=\"destructive\" — use variant=\"solid\" color=\"error\"",
         "DO NOT use variant=\"secondary\" — use variant=\"soft\" (preferred) or variant=\"ghost\"",
         "DO NOT use size=\"default\" — use size=\"md\"",
@@ -2306,7 +2306,7 @@
         "notes": [
           "**Server-safe, decorative-only primitive.** Accepts any valid CSS color string — hex, rgb, oklch, hsl, named. Pure presentation, no context.",
           "**Usage patterns:** Inline color marker next to a label, preview dot in lists, color-indicator in a category chip, legend swatch for charts.",
-          "**`ring={true}`** adds a subtle outline — essential for white/very-light colors that would otherwise disappear on surface-raised backgrounds.",
+          "**`ring={true}`** adds a subtle outline — essential for white/very-light colors that would otherwise disappear on surface-panel backgrounds.",
           "**Interactive color picking:** Use ColorInput (which opens a full picker). ColorSwatch is display-only.",
           "No IconProvider cascade, no FormField consumption — composes freely with anything."
         ]
@@ -2626,7 +2626,7 @@
         "columns": {
           "type": {
             "name": "object",
-            "raw": "ColumnDef<TData>[]"
+            "raw": "ColumnDef<TData, TValue>[]"
           },
           "required": false,
           "description": "TanStack column definitions"
@@ -2638,6 +2638,13 @@
           },
           "required": false
         },
+        "className": {
+          "type": {
+            "name": "object",
+            "raw": "string — class name for the wrapper div"
+          },
+          "required": false
+        },
         "sortable": {
           "type": {
             "name": "object",
@@ -2648,7 +2655,7 @@
         "onSort": {
           "type": {
             "name": "function",
-            "raw": "(key: string, dir: 'asc' | 'desc' | false) => void — server-side sort callback (enables manualSorting)"
+            "raw": "(key: string, direction: 'asc' | 'desc' | false) => void — server-side sort callback (enables manualSorting)"
           },
           "required": false
         },
@@ -2659,6 +2666,14 @@
           },
           "required": false
         },
+        "filterableColumns": {
+          "type": {
+            "name": "object",
+            "raw": "string[] — restrict filter inputs to these column IDs"
+          },
+          "required": false,
+          "description": "only with filterable; omit for all filterable columns"
+        },
         "globalFilter": {
           "type": {
             "name": "object",
@@ -2688,6 +2703,14 @@
           "description": "default 10",
           "defaultValue": 10
         },
+        "pageSizeOptions": {
+          "type": {
+            "name": "object",
+            "raw": "number[] — page-size selector options"
+          },
+          "required": false,
+          "description": "default [10, 20, 50, 100]"
+        },
         "selectable": {
           "type": {
             "name": "object",
@@ -2719,7 +2742,7 @@
         "onSelectionChange": {
           "type": {
             "name": "function",
-            "raw": "(selectedRows: TData[]) => void"
+            "raw": "(selectedRows: TData[], selectedIds: Set<string>) => void — does NOT fire on mount"
           },
           "required": false
         },
@@ -2780,13 +2803,28 @@
           },
           "required": false
         },
+        "rowClassName": {
+          "type": {
+            "name": "function",
+            "raw": "(row: TData) => string | undefined — conditional per-row class (the <tr> in table mode, the Card in card mode)"
+          },
+          "required": false
+        },
         "bulkActions": {
           "type": {
             "name": "union",
-            "raw": "BulkAction<TData>[] — floating action bar on selection — { label, onClick, color?: 'default'|'error', disabled? }"
+            "raw": "BulkAction<TData>[] — floating action bar on selection — { label, onClick, icon?: IconInput, color?: 'accent'|'error', disabled? }"
           },
           "required": false
         },
+        "bulkActionsPosition": {
+          "type": {
+            "name": "union",
+            "raw": "'bottom' | 'top' | 'inline' — where the bulk-actions bar renders"
+          },
+          "required": false,
+          "description": "default 'bottom'"
+        },
         "toolbar": {
           "type": {
             "name": "object",
@@ -2795,6 +2833,22 @@
           "required": false,
           "description": "column visibility, density, CSV export"
         },
+        "enableExport": {
+          "type": {
+            "name": "object",
+            "raw": "boolean — show the toolbar's Export CSV button"
+          },
+          "required": false,
+          "description": "default true",
+          "defaultValue": true
+        },
+        "onExport": {
+          "type": {
+            "name": "function",
+            "raw": "(visibleRows: TData[]) => void — replace the built-in CSV export"
+          },
+          "required": false
+        },
         "editable": {
           "type": {
             "name": "object",
@@ -2802,6 +2856,13 @@
           },
           "required": false
         },
+        "onCellEdit": {
+          "type": {
+            "name": "function",
+            "raw": "(rowIndex: number, columnId: string, value: unknown) => void — fired on cell edit commit"
+          },
+          "required": false
+        },
         "virtualRows": {
           "type": {
             "name": "object",
@@ -2809,6 +2870,32 @@
           },
           "required": false
         },
+        "virtualRowHeight": {
+          "type": {
+            "name": "object",
+            "raw": "number — ESTIMATED row height in px (default 48); real heights are measured after mount"
+          },
+          "required": false,
+          "defaultValue": 48
+        },
+        "maxHeight": {
+          "type": {
+            "name": "object",
+            "raw": "number — max height of the virtual scroll container in px"
+          },
+          "required": false,
+          "description": "default 600",
+          "defaultValue": 600
+        },
+        "mobileView": {
+          "type": {
+            "name": "union",
+            "raw": "'card' | 'table' — stacked cards below the sm breakpoint"
+          },
+          "required": false,
+          "description": "default 'table'",
+          "defaultValue": "table"
+        },
         "columnPinning": {
           "type": {
             "name": "object",
@@ -2825,7 +2912,8 @@
               "comfortable"
             ]
           },
-          "required": false
+          "required": false,
+          "defaultValue": "standard"
         }
       },
       "composition": {
@@ -2840,13 +2928,18 @@
           "Pass `selectedIds` (Set<string>) + `onSelectionChange` for controlled row selection.",
           "Provide `getRowId: (row) => row.id` so selection survives data refetches (otherwise TanStack uses array index, which breaks on sort/filter).",
           "`selectableFilter: (row) => boolean` disables selection on specific rows (e.g. archived items). **Row click model:**",
-          "`onRowClick` fires on row-level click BUT excludes clicks on checkboxes, buttons, links, and inputs automatically. No manual `stopPropagation` needed for standard interactive elements. **Virtualization:** `virtualRows={true}` enables row virtualization via `@tanstack/react-virtual`. Turn it on for 1000+ row datasets; the scroll container must have a bounded height. **Density integration:** density is forwarded to `Table`'s `density` prop, which sets `--table-py` (compact 4 / standard 8 / comfortable 12px → rows ≈ 29 / 37 / 45px; header tracks it). DataTableToolbar's density switcher updates this at runtime; the prop sets the initial state only."
+          "`onRowClick` fires on row-level click BUT excludes clicks on checkboxes, buttons, links, and inputs automatically. No manual `stopPropagation` needed for standard interactive elements. **Virtualization:** `virtualRows={true}` enables row virtualization via `@tanstack/react-virtual`. Turn it on for 1000+ row datasets; the scroll container must have a bounded height. Rows stay in normal table flow (each windowed row is its own `<tbody>` measured by the virtualizer, with spacer row groups reserving the un-rendered remainder), so column widths keep tracking `<thead>` and `virtualRowHeight` is only the pre-measurement estimate. **Virtualization + expansion:** `virtualRows` and `expandable` compose. Because each row group is measured, an expanded detail panel of any height contributes to the total scroll size and pushes the rows below it down. The reveal is instant in virtual mode (no height animation) — an animating height would fire a resize on every frame. **Toolbar export:** the Export button renders whenever `toolbar` is on. The built-in CSV export walks `getFilteredRowModel()`, which under server-side `pagination` is only the current page — pass `onExport` to fetch the full set yourself, or `enableExport={false}` to drop the button. **Density integration:** density is forwarded to `Table`'s `density` prop, which sets `--table-py` (compact 4 / standard 8 / comfortable 12px → rows ≈ 29 / 37 / 45px; header tracks it). DataTableToolbar's density switcher updates this at runtime; the prop sets the initial state only."
         ]
       },
       "docPath": "docs/components/ui/data-table.md",
       "defaults": {
         "pageSize": 10,
-        "noResultsText": "No results."
+        "noResultsText": "No results.",
+        "enableExport": true,
+        "mobileView": "table",
+        "virtualRowHeight": 48,
+        "maxHeight": 600,
+        "density": "standard"
       },
       "examples": [
         "import { DataTable } from '@devalok/shilp-sutra/ui/data-table'\n\n<DataTable\n  columns={[\n    { accessorKey: 'name', header: 'Name' },\n    { accessorKey: 'email', header: 'Email' },\n  ]}\n  data={users}\n  sortable\n  onSort={(key, dir) => handleSort(key, dir)}\n  pagination={{ page, pageSize: 20, total: totalCount, onPageChange: setPage }}\n  loading={isLoading}\n  emptyState={<EmptyState title=\"No users\" />}\n/>"
@@ -2859,9 +2952,16 @@
         "selectedIds syncs via useEffect — provide getRowId for custom row IDs",
         "onRowClick does NOT fire when clicking checkboxes, buttons, links, or inputs",
         "Use density=\"compact\" for Karm-style h-9 rows",
-        "`virtualRows={true}` requires a bounded scroll container — unbounded height silently disables virtualization"
+        "`virtualRows={true}` requires a bounded scroll container — unbounded height silently disables virtualization",
+        "`onSelectionChange` does NOT fire on mount, and does NOT fire when selection is synced from the `selectedIds` prop — only on genuine selection changes",
+        "`filterableColumns` is ignored unless `filterable` is also set",
+        "`rowClassName` returns are passed through `cn()` verbatim — a class that does not exist in the token set silently does nothing (use the real scale steps, e.g. `bg-error-3`, not invented names like `bg-error-subtle`)"
       ],
       "changes": [
+        {
+          "version": "0.57.0",
+          "summary": "**Fixed** `onSelectionChange` no longer fires on mount with `[]` — first-render guard added. Root cause of the cascade reported in #213."
+        },
         {
           "version": "0.45.0",
           "summary": "**Fixed** Expander a11y per the expando-row spec: `aria-expanded` on the toggle button, visually-hidden \"Expand rows\" column header; chevron rotation uses `duration-fast-02 ease-productive-standard`."
@@ -3041,7 +3141,8 @@
           "type": {
             "name": "boolean"
           },
-          "required": false
+          "required": false,
+          "defaultValue": false
         },
         "globalFilterValue": {
           "type": {
@@ -3076,7 +3177,17 @@
         },
         "enableExport": {
           "type": {
-            "name": "boolean"
+            "name": "object",
+            "raw": "boolean — show the Export CSV button"
+          },
+          "required": false,
+          "description": "default true",
+          "defaultValue": true
+        },
+        "onExport": {
+          "type": {
+            "name": "function",
+            "raw": "(visibleRows: TData[]) => void — replaces the built-in CSV logic; receives the currently visible filtered rows"
           },
           "required": false
         }
@@ -3090,6 +3201,10 @@
         ]
       },
       "docPath": "docs/components/ui/data-table-toolbar.md",
+      "defaults": {
+        "enableExport": true,
+        "globalFilter": false
+      },
       "examples": [
         "import { DataTableToolbar } from '@devalok/shilp-sutra/ui/data-table-toolbar'\n\n<DataTableToolbar\n  table={table}\n  globalFilter\n  globalFilterValue={filterValue}\n  onGlobalFilterChange={setFilterValue}\n  density={density}\n  onDensityChange={setDensity}\n  enableExport\n/>"
       ],
@@ -3100,6 +3215,10 @@
         "Prefer DataTable's `toolbar={true}` prop over rendering this directly"
       ],
       "changes": [
+        {
+          "version": "0.57.0",
+          "summary": "**Added** `onExport?: (visibleRows: TData[]) => void` — when provided, replaces the built-in CSV logic. Same signature as `DataTable`'s `onExport`, so the prop forwards straight through."
+        },
         {
           "version": "0.5.0",
           "summary": "**Changed** (BREAKING) Removed from `@devalok/shilp-sutra/ui` barrel export — must use `@devalok/shilp-sutra/ui/data-table-toolbar`"
@@ -3373,7 +3492,7 @@
           "**`pulse` = \"live\".** Off by default (static status). Turn it on for active/attention states (recording, live, connecting) — a pulsing dot reads as \"happening now\", so leave it off for settled statuses.",
           "**Powers the higher-level pieces.** `StatusBadge` composes `<Badge>` + `<Dot>`; use `Dot` directly anywhere you need a coloured indicator without a pill.",
           "**Three treatments:** `filled` (active), `ring` (hollow outline), `off` (faint same-tone fill + light border — present but inactive/disabled).",
-          "**`withBorder`** adds a contrast ring (`ring-2 ring-surface-raised`) so the dot reads on avatars, images, or coloured fills — the pattern Avatar's status dot uses.",
+          "**`withBorder`** adds a contrast ring (`ring-2 ring-surface-panel`) so the dot reads on avatars, images, or coloured fills — the pattern Avatar's status dot uses.",
           "**`pulseSpeed`** (slow/normal/fast) tunes the pulse tempo — fast for urgent (recording), slow for ambient (syncing)."
         ]
       },
@@ -4934,6 +5053,7 @@
         "Omit `value` (or pass `null`) for indeterminate.",
         "Pass an explicit `color` to override `autoColor`.",
         "Compound `Progress.Track` needs a name — an `aria-label`, or a `Progress.Label` whose `id` the Track's `aria-labelledby` points to. A Track with neither is an unnamed progressbar (axe will flag it).",
+        "**`<Progress value={72} />` with no name warns in DEV.** `aria-valuenow` already carries the number, so an unnamed bar announces as \"progressbar, 72%\" — the reader learns the value but not *what* is progressing. Pass `label` (renders visible text and wires `aria-labelledby`) or `aria-label` when the bar must stay visually unlabelled. The component deliberately does **not** invent a default like \"Progress: 72%\": that would silence the audit while leaving the announcement equally uninformative, and only you know what the bar measures. Warns once per session, not per render.",
         "`Progress.Indicator` / `Segment` / `Value` throw if rendered outside `Progress.Root`."
       ],
       "changes": [
@@ -6980,7 +7100,7 @@
       ],
       "gotchas": [
         "**Edge OR elevation, never both.** Combining `bordered` with a shadowed elevation (raised/floating/overlay) is the double-edge anti-pattern and dev-warns. Use `elevation=\"flat\"` with `bordered`, or drop `bordered` and let the shadow be the edge.",
-        "`flat` still uses `bg-surface-raised` (a card without a shadow), not the page background — it is a surface, not a hole."
+        "`flat` still uses `bg-surface-panel` (a card without a shadow), not the page background — it is a surface, not a hole."
       ]
     },
     "switch": {
@@ -8454,10 +8574,10 @@
         "borderColor": {
           "type": {
             "name": "union",
-            "raw": "\"surface-base\" | \"surface-raised\" (default: \"surface-raised\") — overlap border color"
+            "raw": "\"surface-base\" | \"surface-panel\" (default: \"surface-panel\") — overlap border color"
           },
           "required": false,
-          "defaultValue": "surface-raised"
+          "defaultValue": "surface-panel"
         },
         "onOverflowClick": {
           "type": {
@@ -8495,7 +8615,7 @@
           "**Built on ui/Avatar** — each slot is an Avatar with overlap + border + optional Tooltip.",
           "**Wraps TooltipProvider internally** — don't add another.",
           "**renderAvatar** escape hatch for custom shapes. Wrapper handles overlap/border positioning; your renderer sets size + shape.",
-          "**borderColor** must match the surface the group sits on (`surface-raised` on Card, `surface-base` on page bg). Mismatch = visible seam.",
+          "**borderColor** must match the surface the group sits on (`surface-panel` on Card, `surface-base` on page bg). Mismatch = visible seam.",
           "**Overflow:** +N badge with optional `onOverflowClick` → pair with a Popover/Sheet for \"show all members\".",
           "Per-user `ring` (lead/admin/client) surfaces Avatar's ring semantic at group level — use for role/presence hints."
         ]
@@ -8505,7 +8625,7 @@
         "size": "md",
         "max": 4,
         "showTooltip": true,
-        "borderColor": "surface-raised",
+        "borderColor": "surface-panel",
         "expandDirection": "right",
         "expandAmount": "default"
       },
@@ -8517,7 +8637,7 @@
         "Users beyond `max` are collapsed into a \"+N\" overflow badge",
         "Missing `image` falls back to initials derived from `name`",
         "Hover expand animation uses CSS `group-hover` — parent must not clip overflow",
-        "`borderColor` should match the surface the group sits on (`surface-base` on page bg, `surface-raised` on cards)",
+        "`borderColor` should match the surface the group sits on (`surface-base` on page bg, `surface-panel` on cards)",
         "`renderAvatar` wrapper is positioning-only — pass `size` directly to your Avatar (do NOT use `className=\"h-full w-full\"`)"
       ],
       "changes": [
@@ -9683,6 +9803,27 @@
             "raw": "(hunk) => void (adds per-change Reject control)"
           },
           "required": false
+        },
+        "language": {
+          "type": {
+            "name": "string"
+          },
+          "required": false,
+          "description": "syntax-highlight full lines as this language — inline/split, \"line\" granularity only; lazy-loads react-syntax-highlighter, one-dark theme, same pattern as MarkdownViewer"
+        },
+        "beforeParseError": {
+          "type": {
+            "name": "function",
+            "raw": "(raw: string) => ReactNode (custom render when `before` fails to parse as JSON in fields mode; default is a plain message)"
+          },
+          "required": false
+        },
+        "afterParseError": {
+          "type": {
+            "name": "function",
+            "raw": "(raw: string) => ReactNode (custom render when `after` fails to parse as JSON in fields mode; default is a plain message)"
+          },
+          "required": false
         }
       },
       "composition": {
@@ -9710,10 +9851,13 @@
         "<Diff before={committed} after={pending} mode=\"split\" />\n<Diff before={a} after={b} granularity=\"word\" />          // prose\n<Diff before={jsonA} after={jsonB} mode=\"fields\" />       // structured, diffs by key\n<Diff before={a} after={b} onAcceptHunk={fn} onRejectHunk={fn} />  // review flow\n\n// Composable — bring your own layout:\n<Diff.Root before={a} after={b} mode=\"split\">\n  <header><Diff.ColumnLabels /><Diff.Summary /></header>\n  <Diff.Body />\n</Diff.Root>"
       ],
       "gotchas": [
-        "`fields` mode requires valid JSON on both sides; it reports a clear message otherwise. For YAML, parse to an object and `JSON.stringify` before passing.",
-        "`granularity=\"word\"` is for prose; it renders a flowing word-level diff, not line gutters.",
+        "`fields` mode requires valid JSON on both sides; it reports a clear message per side otherwise (override with `beforeParseError`/`afterParseError`). For YAML, parse to an object and `JSON.stringify` before passing.",
+        "`granularity=\"word\"` is for prose; it renders a flowing word-level diff, not line gutters. `language` has no effect in word granularity or `fields` mode.",
         "Accept/Reject controls only appear when the matching handler is provided — the Diff itself doesn't mutate content; the consumer applies the decision.",
         "Hunk = a contiguous run of added/removed lines; `onAcceptHunk`/`onRejectHunk` receive `{ index, before, after }`."
+      ],
+      "peers": [
+        "react-syntax-highlighter"
       ]
     },
     "emoji-picker": {
@@ -11699,8 +11843,19 @@
         }
       ],
       "peers": [
+        "@tiptap/core",
+        "@tiptap/extension-highlight",
+        "@tiptap/extension-image",
+        "@tiptap/extension-list",
+        "@tiptap/extension-mention",
+        "@tiptap/extension-text-align",
+        "@tiptap/extensions",
+        "@tiptap/markdown",
         "@tiptap/pm",
-        "@tiptap/react"
+        "@tiptap/react",
+        "@tiptap/starter-kit",
+        "@tiptap/suggestion",
+        "date-fns"
       ]
     },
     "rich-text-editor": {
@@ -11863,8 +12018,18 @@
         }
       ],
       "peers": [
+        "@tiptap/core",
+        "@tiptap/extension-highlight",
+        "@tiptap/extension-image",
+        "@tiptap/extension-list",
+        "@tiptap/extension-mention",
+        "@tiptap/extension-text-align",
+        "@tiptap/extensions",
+        "@tiptap/markdown",
         "@tiptap/pm",
-        "@tiptap/react"
+        "@tiptap/react",
+        "@tiptap/starter-kit",
+        "@tiptap/suggestion"
       ]
     },
     "schedule-view": {
@@ -12333,6 +12498,100 @@
         }
       ]
     },
+    "app-shell": {
+      "displayName": "AppShell",
+      "tier": "shell",
+      "import": "@devalok/shilp-sutra/shell/app-shell",
+      "serverSafe": false,
+      "description": "",
+      "props": {
+        "variant": {
+          "type": {
+            "name": "enum",
+            "value": [
+              "flat",
+              "inset"
+            ]
+          },
+          "required": false
+        },
+        "chrome": {
+          "type": {
+            "name": "enum",
+            "value": [
+              "dim",
+              "bright"
+            ]
+          },
+          "required": false
+        },
+        "className": {
+          "type": {
+            "name": "string"
+          },
+          "required": false
+        }
+      },
+      "composition": {},
+      "docPath": "docs/components/shell/app-shell.md",
+      "subComponents": {
+        "AppShellBar": {
+          "props": {
+            "bordered": {
+              "type": {
+                "name": "boolean"
+              },
+              "required": false
+            },
+            "className": {
+              "type": {
+                "name": "string"
+              },
+              "required": false
+            }
+          }
+        },
+        "AppShellSidebar": {
+          "props": {
+            "collapsed": {
+              "type": {
+                "name": "boolean"
+              },
+              "required": false
+            },
+            "className": {
+              "type": {
+                "name": "string"
+              },
+              "required": false
+            }
+          }
+        },
+        "AppShellBody": {
+          "props": {
+            "className": {
+              "type": {
+                "name": "string"
+              },
+              "required": false
+            }
+          }
+        },
+        "AppShellCanvas": {
+          "props": {
+            "className": {
+              "type": {
+                "name": "string"
+              },
+              "required": false
+            }
+          }
+        }
+      },
+      "examples": [
+        "import {\n  AppShell, AppShellBar, AppShellBody, AppShellCanvas, AppShellSidebar,\n} from '@devalok/shilp-sutra/shell/app-shell'\nimport { TopBar } from '@devalok/shilp-sutra/shell/top-bar'\n\nexport function Layout({ children }) {\n  return (\n    <AppShell variant=\"inset\" chrome=\"dim\">\n      <AppShellBar>\n        <TopBar>\n          <TopBar.Left><TopBar.Title>Projects</TopBar.Title></TopBar.Left>\n          <TopBar.Right><TopBar.UserMenu user={user} /></TopBar.Right>\n        </TopBar>\n      </AppShellBar>\n\n      <AppShellBody>\n        <AppShellSidebar>\n          <Nav />\n        </AppShellSidebar>\n        <AppShellCanvas className=\"overflow-auto\">\n          {children}\n        </AppShellCanvas>\n      </AppShellBody>\n    </AppShell>\n  )\n}"
+      ]
+    },
     "bottom-navbar": {
       "displayName": "BottomNavbar",
       "tier": "shell",
@@ -13664,27 +13923,39 @@
         "value": "Canvas"
       },
       {
-        "name": "--color-surface-sunken",
+        "name": "--color-surface-panel",
         "value": "Canvas"
       },
       {
-        "name": "--color-surface-raised",
+        "name": "--color-surface-overlay",
         "value": "Canvas"
       },
       {
-        "name": "--color-surface-overlay",
+        "name": "--color-surface-panel-hover",
         "value": "Canvas"
       },
       {
-        "name": "--color-surface-raised-hover",
+        "name": "--color-surface-panel-active",
         "value": "Canvas"
       },
       {
-        "name": "--color-surface-raised-active",
+        "name": "--color-surface-sunken",
+        "value": "Canvas"
+      },
+      {
+        "name": "--color-surface-sunken-hover",
+        "value": "Canvas"
+      },
+      {
+        "name": "--color-surface-raised",
+        "value": "Canvas"
+      },
+      {
+        "name": "--color-surface-raised-hover",
         "value": "Canvas"
       },
       {
-        "name": "--color-surface-chrome",
+        "name": "--color-surface-raised-active",
         "value": "Canvas"
       },
       {
@@ -13715,6 +13986,10 @@
         "name": "--color-surface-fg-subtle",
         "value": "GrayText"
       },
+      {
+        "name": "--color-surface-border-subtle",
+        "value": "GrayText"
+      },
       {
         "name": "--color-surface-border",
         "value": "CanvasText"
@@ -13724,12 +13999,16 @@
         "value": "CanvasText"
       },
       {
-        "name": "--color-surface-border-subtle",
+        "name": "--color-surface-border-card",
         "value": "GrayText"
       },
       {
-        "name": "--color-surface-border-card",
-        "value": "GrayText"
+        "name": "--color-surface-border-interactive",
+        "value": "CanvasText"
+      },
+      {
+        "name": "--color-surface-border-interactive-strong",
+        "value": "CanvasText"
       },
       {
         "name": "--color-backdrop",
@@ -13923,10 +14202,22 @@
         "name": "--color-link-visited",
         "value": "VisitedText"
       },
+      {
+        "name": "--color-category-fg",
+        "value": "var(--neutral-1)"
+      },
+      {
+        "name": "--color-category-teal-2",
+        "value": "var(--teal-2)"
+      },
       {
         "name": "--color-category-teal-3",
         "value": "var(--teal-3)"
       },
+      {
+        "name": "--color-category-teal-4",
+        "value": "var(--teal-4)"
+      },
       {
         "name": "--color-category-teal-7",
         "value": "var(--teal-7)"
@@ -13939,10 +14230,18 @@
         "name": "--color-category-teal-11",
         "value": "var(--teal-11)"
       },
+      {
+        "name": "--color-category-amber-2",
+        "value": "var(--amber-2)"
+      },
       {
         "name": "--color-category-amber-3",
         "value": "var(--amber-3)"
       },
+      {
+        "name": "--color-category-amber-4",
+        "value": "var(--amber-4)"
+      },
       {
         "name": "--color-category-amber-7",
         "value": "var(--amber-7)"
@@ -13955,10 +14254,18 @@
         "name": "--color-category-amber-11",
         "value": "var(--amber-11)"
       },
+      {
+        "name": "--color-category-slate-2",
+        "value": "var(--slate-2)"
+      },
       {
         "name": "--color-category-slate-3",
         "value": "var(--slate-3)"
       },
+      {
+        "name": "--color-category-slate-4",
+        "value": "var(--slate-4)"
+      },
       {
         "name": "--color-category-slate-7",
         "value": "var(--slate-7)"
@@ -13971,10 +14278,18 @@
         "name": "--color-category-slate-11",
         "value": "var(--slate-11)"
       },
+      {
+        "name": "--color-category-indigo-2",
+        "value": "var(--indigo-2)"
+      },
       {
         "name": "--color-category-indigo-3",
         "value": "var(--indigo-3)"
       },
+      {
+        "name": "--color-category-indigo-4",
+        "value": "var(--indigo-4)"
+      },
       {
         "name": "--color-category-indigo-7",
         "value": "var(--indigo-7)"
@@ -13987,10 +14302,18 @@
         "name": "--color-category-indigo-11",
         "value": "var(--indigo-11)"
       },
+      {
+        "name": "--color-category-cyan-2",
+        "value": "var(--cyan-2)"
+      },
       {
         "name": "--color-category-cyan-3",
         "value": "var(--cyan-3)"
       },
+      {
+        "name": "--color-category-cyan-4",
+        "value": "var(--cyan-4)"
+      },
       {
         "name": "--color-category-cyan-7",
         "value": "var(--cyan-7)"
@@ -14003,10 +14326,18 @@
         "name": "--color-category-cyan-11",
         "value": "var(--cyan-11)"
       },
+      {
+        "name": "--color-category-orange-2",
+        "value": "var(--orange-2)"
+      },
       {
         "name": "--color-category-orange-3",
         "value": "var(--orange-3)"
       },
+      {
+        "name": "--color-category-orange-4",
+        "value": "var(--orange-4)"
+      },
       {
         "name": "--color-category-orange-7",
         "value": "var(--orange-7)"
@@ -14019,10 +14350,18 @@
         "name": "--color-category-orange-11",
         "value": "var(--orange-11)"
       },
+      {
+        "name": "--color-category-emerald-2",
+        "value": "var(--emerald-2)"
+      },
       {
         "name": "--color-category-emerald-3",
         "value": "var(--emerald-3)"
       },
+      {
+        "name": "--color-category-emerald-4",
+        "value": "var(--emerald-4)"
+      },
       {
         "name": "--color-category-emerald-7",
         "value": "var(--emerald-7)"