@devalok/shilp-sutra 0.56.0 → 0.59.0

package/docs/components/shell/app-shell.md

@@ -0,0 +1,132 @@
+# AppShell
+
+- Import: @devalok/shilp-sutra/shell/app-shell
+- Server-safe: No
+- Category: shell
+
+## Overview
+
+The frame that lets a bar span above **both** the sidebar and the content.
+
+`SidebarProvider` renders a single flex row, so a bar can only live *inside* the
+content pane — which is why every shadcn example puts its `<header>` inside
+`SidebarInset`. AppShell is the other arrangement: the bar is a sibling above the
+row, the way Carbon's `Header` sits above its `SideNav`.
+
+It provides layout and surfaces only. Put `TopBar` in the bar slot and compose
+the `Sidebar` primitives in the sidebar slot — AppShell does not replace either.
+
+## Subcomponents
+
+| Component | Purpose |
+|-----------|---------|
+| `AppShell` | Root — owns the chrome surface and the arrangement |
+| `AppShellBar` | Full-width bar above everything. Minimum height, never fixed. |
+| `AppShellBody` | The row beneath the bar: sidebar alongside canvas |
+| `AppShellSidebar` | Fixed-width slot, 16rem or 3rem collapsed |
+| `AppShellCanvas` | The content pane; becomes an inset panel when `variant="inset"` |
+
+## Props
+
+### AppShell
+    variant?: 'flat' | 'inset'
+    chrome?: 'dim' | 'bright'
+    className?: string
+
+Defaults: `variant` is `flat`, `chrome` is `dim`. `chrome` only applies when
+`variant="inset"`.
+
+### AppShellBar
+    bordered?: boolean
+    className?: string
+
+Defaults: `bordered` is `true` when the shell is flat and `false` when inset.
+
+### AppShellSidebar
+    collapsed?: boolean
+    className?: string
+
+Defaults: `collapsed` is `false` — 16rem expanded, 3rem collapsed.
+
+### AppShellBody / AppShellCanvas
+    className?: string
+
+## Example
+
+```tsx
+import {
+  AppShell, AppShellBar, AppShellBody, AppShellCanvas, AppShellSidebar,
+} from '@devalok/shilp-sutra/shell/app-shell'
+import { TopBar } from '@devalok/shilp-sutra/shell/top-bar'
+
+export function Layout({ children }) {
+  return (
+    <AppShell variant="inset" chrome="dim">
+      <AppShellBar>
+        <TopBar>
+          <TopBar.Left><TopBar.Title>Projects</TopBar.Title></TopBar.Left>
+          <TopBar.Right><TopBar.UserMenu user={user} /></TopBar.Right>
+        </TopBar>
+      </AppShellBar>
+
+      <AppShellBody>
+        <AppShellSidebar>
+          <Nav />
+        </AppShellSidebar>
+        <AppShellCanvas className="overflow-auto">
+          {children}
+        </AppShellCanvas>
+      </AppShellBody>
+    </AppShell>
+  )
+}
+```
+
+## The three arrangements
+
+**`variant="flat"`** — chrome and content share one surface; a hairline on the
+sidebar and under the bar does the separating. Widest content area.
+
+**`variant="inset"`** — the content sits in a rounded panel inside the chrome.
+`chrome` then decides which plane the frame takes and which the work takes:
+
+| | light chrome | light canvas | dark chrome | dark canvas |
+|---|---|---|---|---|
+| `chrome="dim"` | `#eeeeee` | `#ffffff` | `#0a0a0a` | `#171717` |
+| `chrome="bright"` | `#ffffff` | `#eeeeee` | `#171717` | `#0a0a0a` |
+
+Both come from the same two tokens — `surface-sunken` and `surface-panel` —
+swapped. There is no third tier and no per-theme special case.
+
+The choice is not really about lightness. With `dim` a brand tint lands on the
+frame and the work area stays neutral; with `bright` it is the reverse. That
+decides whether your brand colour surrounds the work or sits underneath it.
+
+## Composability
+
+Layout only. It sets surfaces, widths and the inset geometry; everything inside
+each slot is yours. Any component can go in any slot.
+
+`AppShellSidebar` uses the same widths as `Sidebar` (16rem, 3rem collapsed), so
+the two agree whether or not you nest one inside the other.
+
+## Gotchas
+
+**The bar height is a minimum, not a fixed value.** `TopBar` sizes to its
+content, and a two-line workspace switcher legitimately needs more room than a
+one-line one. Setting a fixed height clips it.
+
+**The inset canvas is flush to the bar and the sidebar** and floats only off the
+bottom-right. That is deliberate: it reads as the frame opening up rather than a
+card dropped into the middle. A symmetric gap fights that.
+
+**No shadow on the inset canvas.** It is a frame, not a floating thing — shadows
+are reserved for what genuinely floats (menus, dialogs, popovers).
+
+**A bar is optional, and dropping it is a product decision.** Without one, the
+account and workspace switcher move into the sidebar footer. That changes what
+the shell is for, not just how it looks.
+
+## Changes
+
+- 0.57.0 — added

package/docs/components/ui/avatar.md

@@ -38,7 +38,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.
 
 ## Gotchas
 - Status dot renders with role="img" and aria-label (accessible, not decorative)

package/docs/components/ui/button.md

@@ -44,7 +44,7 @@
 - **Prefer `variant="soft"` over `variant="outline"` for secondary actions** (see Gotchas for details). This is a design-system-wide convention.
 
 ## 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"

package/docs/components/ui/chat.md

@@ -155,13 +155,16 @@ Horizontal rule with a formatted date label.
 
 ### Props
     date: Date | string (REQUIRED)
-    format: (date: Date) => string — custom date formatter
+    format: (date: Date) => string — custom date formatter (overrides locale/timeZone)
+    locale: string — BCP 47 locale for the default label's month name (default 'en-US')
+    timeZone: string — IANA time zone for the "Today"/"Yesterday" day-boundary comparison and formatting (default: browser's local time zone)
     className: string
 
 ### Example
 ```jsx
 <DateSeparator date={new Date()} />
 <DateSeparator date="2026-03-25" format={(d) => d.toLocaleDateString()} />
+<DateSeparator date={new Date()} locale="fr-FR" timeZone="Europe/Paris" />
 ```
 
 ---
@@ -219,5 +222,8 @@ Animated bouncing dots with a text description of who is typing.
 - DateSeparator's default formatter shows "Today", "Yesterday", or "Mon DD" / "Mon DD, YYYY"
 
 ## Changes
+### Unreleased
+- **Added** `DateSeparator` gained `locale?: string` and `timeZone?: string` props — the default label previously always used `en-US` month names and the browser's local time zone.
+
 ### v0.29.0
 - **Added** Initial release — 7 chat primitives (MessageList, Message, SystemMessage, MessageInput, DateSeparator, UnreadSeparator, TypingIndicator)

package/docs/components/ui/color-swatch.md

@@ -23,7 +23,7 @@
 ## Composability
 - **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.
 

package/docs/components/ui/data-table-toolbar.md

@@ -11,10 +11,11 @@
     onGlobalFilterChange: (value: string) => void
     density: 'compact' | 'standard' | 'comfortable'
     onDensityChange: (density: Density) => void
-    enableExport: boolean
+    enableExport: boolean — show the Export CSV button (default true)
+    onExport: (visibleRows: TData[]) => void — replaces the built-in CSV logic; receives the currently visible filtered rows
 
 ## Defaults
-    none
+    enableExport=true, globalFilter=false
 
 ## Example
 ```jsx
@@ -44,6 +45,9 @@ import { DataTableToolbar } from '@devalok/shilp-sutra/ui/data-table-toolbar'
 - Prefer DataTable's `toolbar={true}` prop over rendering this directly
 
 ## Changes
+### v0.57.0
+- **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.
+
 ### v0.5.0
 - **Changed** (BREAKING) Removed from `@devalok/shilp-sutra/ui` barrel export — must use `@devalok/shilp-sutra/ui/data-table-toolbar`
 

package/docs/components/ui/data-table.md

@@ -5,20 +5,23 @@
 - Category: ui
 
 ## Props
-    columns: ColumnDef<TData>[] (TanStack column definitions)
+    columns: ColumnDef<TData, TValue>[] (TanStack column definitions)
     data: TData[]
+    className: string — class name for the wrapper div
     sortable: boolean — enable column sorting
-    onSort: (key: string, dir: 'asc' | 'desc' | false) => void — server-side sort callback (enables manualSorting)
+    onSort: (key: string, direction: 'asc' | 'desc' | false) => void — server-side sort callback (enables manualSorting)
     filterable: boolean — enable per-column filters
+    filterableColumns: string[] — restrict filter inputs to these column IDs (only with filterable; omit for all filterable columns)
     globalFilter: boolean — enable global search
     paginated: boolean — enable client-side pagination
     pagination: { page: number, pageSize: number, total: number, onPageChange: (page: number) => void } — server-side pagination (1-based page)
     pageSize: number (default 10)
+    pageSizeOptions: number[] — page-size selector options (default [10, 20, 50, 100])
     selectable: boolean — enable row selection with checkboxes
     selectedIds: Set<string> — controlled selection state
     selectableFilter: (row: TData) => boolean — disable selection on certain rows
     getRowId: (row: TData) => string — custom row ID accessor
-    onSelectionChange: (selectedRows: TData[]) => void
+    onSelectionChange: (selectedRows: TData[], selectedIds: Set<string>) => void — does NOT fire on mount
     expandable: boolean — enable row expansion
     renderExpanded: (row: TData) => ReactNode — expanded row content
     singleExpand: boolean — only one row expanded at a time
@@ -27,15 +30,23 @@
     noResultsText: string (default "No results.")
     stickyHeader: boolean — sticky table header
     onRowClick: (row: TData) => void — row click handler (excludes interactive element clicks)
-    bulkActions: BulkAction<TData>[] — floating action bar on selection — { label, onClick, color?: 'default'|'error', disabled? }
+    rowClassName: (row: TData) => string | undefined — conditional per-row class (the <tr> in table mode, the Card in card mode)
+    bulkActions: BulkAction<TData>[] — floating action bar on selection — { label, onClick, icon?: IconInput, color?: 'accent'|'error', disabled? }
+    bulkActionsPosition: 'bottom' | 'top' | 'inline' — where the bulk-actions bar renders (default 'bottom')
     toolbar: boolean — show DataTableToolbar (column visibility, density, CSV export)
+    enableExport: boolean — show the toolbar's Export CSV button (default true)
+    onExport: (visibleRows: TData[]) => void — replace the built-in CSV export
     editable: boolean — enable double-click cell editing
+    onCellEdit: (rowIndex: number, columnId: string, value: unknown) => void — fired on cell edit commit
     virtualRows: boolean — virtualize rows for large datasets
+    virtualRowHeight: number — ESTIMATED row height in px (default 48); real heights are measured after mount
+    maxHeight: number — max height of the virtual scroll container in px (default 600)
+    mobileView: 'card' | 'table' — stacked cards below the sm breakpoint (default 'table')
     columnPinning: { left?: string[], right?: string[] }
     density: 'compact' | 'standard' | 'comfortable'
 
 ## Defaults
-    pageSize=10, noResultsText="No results."
+    pageSize=10, noResultsText="No results.", enableExport=true, mobileView='table', virtualRowHeight=48, maxHeight=600, density='standard'
 
 ## Example
 ```jsx
@@ -75,7 +86,11 @@ import { DataTable } from '@devalok/shilp-sutra/ui/data-table'
 **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.
+**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.
 
@@ -88,13 +103,32 @@ import { DataTable } from '@devalok/shilp-sutra/ui/data-table'
 - 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
+- `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
+### Unreleased
+- **Added** `bulkActions[].icon?: IconInput` — icon rendered before the label in a bulk-action button.
+- **Added** `bulkActionsPosition?: 'bottom' | 'top' | 'inline'` — where the bulk-actions bar renders (default `'bottom'`, matching prior behavior).
+
+### v0.57.0
+- **Fixed** `onSelectionChange` no longer fires on mount with `[]` — first-render guard added. Root cause of the cascade reported in #213.
+- **Fixed** `virtualRows + expandable` was a silent no-op — the expanded row was only rendered on the non-virtual path. Virtual rows now render one measured `<tbody>` per windowed row (with spacer row groups for the remainder) so the expanded panel renders, contributes its real height to `getTotalSize()`, and cannot overlap the row below.
+- **Changed** Virtual rows are no longer absolutely positioned with a forced `virtualRowHeight`; they sit in normal table flow at their measured height, so column widths track `<thead>`. `virtualRowHeight` is now the pre-measurement ESTIMATE.
+- **Fixed** `enableExport` was stranded on `DataTableToolbar` and never wired through `DataTableProps`. Now exposed with an `onExport` override. Default is unchanged (`true`) — the Export button still renders whenever `toolbar` is on.
+- **Fixed** `filterable + mobileView="card"` rendered no filter inputs — they now render above the card list in `DataTableCards` (card mode renders no `<thead>` for them to live in).
+- **Added** `onSelectionChange` receives `selectedIds: Set<string>` as second argument — complement of the `selectedIds` prop.
+- **Added** `filterableColumns?: string[]` — restrict filter inputs to specific column IDs.
+- **Added** `rowClassName?: (row: TData) => string | undefined` — conditional row classes in table and card layouts.
+- **Added** `enableExport?: boolean` — hide the toolbar's Export CSV button from `DataTableProps`.
+- **Added** `onExport?: (visibleRows: TData[]) => void` — override built-in CSV with a custom export handler.
+
 ### v0.45.0
 - **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`.
 - **Added** Expanded-row content animates open/closed (height + opacity via framer, `springs.smooth`), self-guarded with `useReducedMotion` — instant swap for reduced-motion users. Virtualized tables keep the instant reveal (a height animation would fight the virtualizer's measurements).
 - **Changed** Density now drives Table's `--table-py` variable (rows ≈ 29 / 37 / 45px; was 29 / 53 / 85). Per-cell `cellPadding` threading removed from context.
-- **Fixed** Hover/selected states visible on cards: row/sort-button/expander hover use `surface-raised-hover` (was the invisible `surface-raised`); expanded row is a `surface-base` recess; sticky header bg is `surface-raised`; empty state uses `py-ds-07` (was raw `h-24`).
+- **Fixed** Hover/selected states visible on cards: row/sort-button/expander hover use `surface-panel-hover` (was the invisible `surface-panel`); expanded row is a `surface-base` recess; sticky header bg is `surface-panel`; empty state uses `py-ds-07` (was raw `h-24`).
 - **Changed** Mobile card view composes `<Card size="sm" variant="outline">` (was a hand-rolled 12px bordered box).
 
 ### v0.29.0

package/docs/components/ui/dot.md

@@ -49,7 +49,7 @@ sized, optionally pulsing, filled or ring.
 - **`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).
 
 ## Gotchas

package/docs/components/ui/progress.md

@@ -66,6 +66,7 @@ common cases, or the compound parts (`Progress.Root` / `Track` / `Indicator` /
 - 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

package/docs/components/ui/surface.md

@@ -18,8 +18,8 @@ The low-level elevated container primitive. Owns background + shadow + radius +
     Surface: elevation="raised", padding="none", radius="surface", bordered=false
 
 ## Elevation
-    flat      — bg-surface-raised, no shadow (pair with `bordered` for an on-page tile)
-    raised    — bg-surface-raised + shadow-raised (card level)
+    flat      — bg-surface-panel, no shadow (pair with `bordered` for an on-page tile)
+    raised    — bg-surface-panel + shadow-raised (card level)
     floating  — bg-surface-overlay + shadow-floating (toasts, floating toolbars)
     overlay   — bg-surface-overlay + shadow-overlay (popovers, menus, dialogs)
 
@@ -48,7 +48,7 @@ The low-level elevated container primitive. Owns background + shadow + radius +
 
 ## 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.
 
 ## Changes
 ### Unreleased

package/docs/components/ui/table.md

@@ -106,12 +106,12 @@ See the `RichCells` story for all of these live.
 - **Added** `TableRowLink` (ui/table-row-link) — real-anchor whole-row navigation with pseudo-element stretch (Safari-safe: anchored to the cell, clipped by the table's `overflow-x-clip`), row-level focus ring, `stretch={false}` title-only mode.
 - **Added** `TableRowActions` — hover/focus-revealed action cluster (opacity reveal, permanently tabbable, `:focus-within` + touch fallbacks, `persist` mode).
 - **Added** `numeric` prop on TableCell/TableHead — right-align + tabular figures.
-- **Fixed** TableFooter background was `color-mix(surface-raised 50%)` — invisible on cards (same mis-mapped shadcn `muted/50` family as the row hover). Now a `surface-base` band with a top hairline.
+- **Fixed** TableFooter background was `color-mix(surface-panel 50%)` — invisible on cards (same mis-mapped shadcn `muted/50` family as the row hover). Now a `surface-base` band with a top hairline.
 - **Fixed** Selected+hover tie: selected rows get an explicit `hover:bg-accent-4` step (hover and selected previously tied on specificity).
 - **Added** Cell recipes section (user cell, tag overflow, money, empty-dash) + density→avatar mapping; `RichCells` / `SelectedRows` stories.
 - **Added** `density` prop (`compact | standard | comfortable`) via `--table-py`; header height tracks density instead of a fixed 40px
 - **Added** `striped` prop — opt-in zebra
-- **Changed** Rows regain their hairline separator (`border-b border-surface-border-subtle` — lost in the original port) and hover becomes visible on cards (`hover:bg-surface-raised-hover`, was the invisible `surface-raised`)
+- **Changed** Rows regain their hairline separator (`border-b border-surface-border-subtle` — lost in the original port) and hover becomes visible on cards (`hover:bg-surface-panel-hover`, was the invisible `surface-panel`)
 - **Changed** Cells: `px-ds-04` interior, first/last cells read `--table-edge` (= `--card-spacing` inside a Card); header drops to `text-ds-sm` muted
 - **Changed** Default vertical rhythm tightens: standard rows ~53px → ~37px
 

package/docs/recipes/customize-brand.md

@@ -256,6 +256,64 @@ Every override should consider both modes. Pattern:
 
 `.dark` is a regular class selector — its specificity is higher than `:root`/`@theme` body, so dark-mode overrides win when the class is active.
 
+## High contrast (`[data-contrast]`)
+
+WCAG 2.2 SC 1.4.11 asks for **3:1** between a control's edge and its background.
+The default control edge here is **2.00:1** in light and **2.08:1** in dark — a
+deliberately softer look, and deliberately under that bar. It is recorded as
+`CONTROL-EDGE-BELOW-AA` in the deviations register.
+
+Set `data-contrast="high"` to opt into edges that clear the threshold:
+
+```html
+<!-- whole app -->
+<html data-contrast="high">
+```
+
+```tsx
+{/* or one region — a data-entry screen inside an otherwise soft product */}
+<div data-contrast="high">
+  <InvoiceForm />
+</div>
+```
+
+| | control edge, light | control edge, dark |
+|---|---|---|
+| default | `#b7b7b7` — 2.00:1 | `#4c4c4c` — 2.08:1 |
+| `data-contrast="high"` | `#868686` — **3.64:1** | `#767676` — **3.93:1** |
+
+It affects Input, Textarea, Select, Combobox, Checkbox, Radio, Switch,
+NumberInput and outlined Button — anything using the control-edge tier. It does
+**not** touch decorative borders (card and panel hairlines stay soft), and it
+does not touch the chromatic ramps, so an outlined Button on a colour is
+unchanged.
+
+Composes with everything else — it is a plain attribute, like `.dark` and
+`data-shape`:
+
+```html
+<html class="dark" data-shape="sharp" data-contrast="high">
+```
+
+**Two things worth knowing.**
+
+If you override the neutral ramp, high contrast follows automatically — the
+block resolves `--neutral-8` / `--neutral-9` by name rather than hard-coding
+hexes, so a rebrand gets a correctly-scaled high-contrast mode for free.
+
+If you want the *opposite* — compliant edges everywhere, with no attribute to
+remember — set the tokens directly and skip the attribute entirely:
+
+```css
+:root {
+  --color-surface-border-interactive:        var(--neutral-8);
+  --color-surface-border-interactive-strong: var(--neutral-9);
+}
+```
+
+That is worth considering. A default is what most products ship, so leaving the
+attribute unset means shipping the edge that misses 1.4.11.
+
 ## Forced colors (Windows high-contrast)
 
 If you override semantic colors, the `@media (forced-colors: active)` block in `semantic.css` continues to remap to system keywords. Your override is ignored when the user is in high-contrast mode — this is the correct behavior.

package/docs/recipes/install-astro.md

@@ -36,6 +36,7 @@ Some components ship hard peers as optional. **Install BEFORE first import.**
 | When you import… | Install |
 |---|---|
 | `@devalok/shilp-sutra/composed/date-picker` | `pnpm add date-fns` |
+| `@devalok/shilp-sutra/composed/diff` | `pnpm add react-syntax-highlighter` |
 | `@devalok/shilp-sutra/composed/file-preview` | `pnpm add react-pdf react-zoom-pan-pinch` |
 | `@devalok/shilp-sutra/composed/markdown-viewer` | `pnpm add react-markdown react-syntax-highlighter remark-gfm` |
 | `@devalok/shilp-sutra/composed/rich-chat-input` | `pnpm add @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/starter-kit @tiptap/suggestion date-fns` |

package/docs/recipes/install-next-app-router.md

@@ -49,6 +49,7 @@ Some components depend on third-party libraries that ship as optional peers. **I
 | When you import… | Install |
 |---|---|
 | `@devalok/shilp-sutra/composed/date-picker` | `pnpm add date-fns` |
+| `@devalok/shilp-sutra/composed/diff` | `pnpm add react-syntax-highlighter` |
 | `@devalok/shilp-sutra/composed/file-preview` | `pnpm add react-pdf react-zoom-pan-pinch` |
 | `@devalok/shilp-sutra/composed/markdown-viewer` | `pnpm add react-markdown react-syntax-highlighter remark-gfm` |
 | `@devalok/shilp-sutra/composed/rich-chat-input` | `pnpm add @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/starter-kit @tiptap/suggestion date-fns` |

package/docs/recipes/install-next-pages.md

@@ -16,7 +16,28 @@ If both `app/` and `pages/` exist, prefer [install-next-app-router.md](./install
 
 Same dependencies as the App Router recipe — see [install-next-app-router.md § 2](./install-next-app-router.md#2-install-dependencies). Replace `next-themes`'s `attribute="class"` setup with the same on Pages Router (it works identically).
 
-**Optional peer dependencies** — if you'll render `<DataTable>`, any chart, `<DatePicker>`, `<ScheduleView>`, `<InputOTP>`, `<FilePreview>`, `<MarkdownViewer>`, or `<Toaster>`, install the matching peers BEFORE first import. (The emoji picker and rich-text editors bundle their deps — no install needed; `@tabler/icons-react` auto-installs as a required peer.) Full table at [install-next-app-router.md § 2a](./install-next-app-router.md#2a-optional-peer-dependencies-install-only-when-importing-the-matching-subpath) — identical for Pages Router.
+### 2a. Optional peer dependencies (install only when importing the matching subpath)
+
+Some components depend on third-party libraries that ship as optional peers. **Install BEFORE first import** of the matching component, or `next build` will exit with `Module not found`. Skip entirely if you only use core components (`Button`, `Text`, `Stack`, `Dialog`, `Toast`, `Form*`, `Input`, `Card`, etc.).
+
+| When you import… | Install |
+|---|---|
+| `@devalok/shilp-sutra/composed/date-picker` | `pnpm add date-fns` |
+| `@devalok/shilp-sutra/composed/diff` | `pnpm add react-syntax-highlighter` |
+| `@devalok/shilp-sutra/composed/file-preview` | `pnpm add react-pdf react-zoom-pan-pinch` |
+| `@devalok/shilp-sutra/composed/markdown-viewer` | `pnpm add react-markdown react-syntax-highlighter remark-gfm` |
+| `@devalok/shilp-sutra/composed/rich-chat-input` | `pnpm add @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/starter-kit @tiptap/suggestion date-fns` |
+| `@devalok/shilp-sutra/composed/rich-text-editor` | `pnpm add @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/starter-kit @tiptap/suggestion` |
+| `@devalok/shilp-sutra/composed/schedule-view` | `pnpm add date-fns` |
+| `@devalok/shilp-sutra/ui/charts` | `pnpm add d3-axis d3-scale d3-selection d3-shape` |
+| `@devalok/shilp-sutra/ui/data-table` | `pnpm add @tanstack/react-table @tanstack/react-virtual` |
+| `@devalok/shilp-sutra/ui/data-table-toolbar` | `pnpm add @tanstack/react-table` |
+| `@devalok/shilp-sutra/ui/input-otp` | `pnpm add input-otp` |
+| `@devalok/shilp-sutra/ui/toast` | `pnpm add sonner` |
+| `@devalok/shilp-sutra/ui/toaster` | `pnpm add sonner` |
+| Any `Icon` / `IconButton` with Tabler icons (near-universal — most components use icons internally, so it is a base-install peer) | `pnpm add @tabler/icons-react` |
+
+> These aren't in core deps so consumers who never render a chart, OTP input, or rich-text editor don't pay the install / bundle cost. One-time decision at install.
 
 ## 3. PostCSS
 

package/docs/recipes/install-remix.md

@@ -32,6 +32,7 @@ Some components ship hard peers as optional. **Install BEFORE first import.**
 | When you import… | Install |
 |---|---|
 | `@devalok/shilp-sutra/composed/date-picker` | `pnpm add date-fns` |
+| `@devalok/shilp-sutra/composed/diff` | `pnpm add react-syntax-highlighter` |
 | `@devalok/shilp-sutra/composed/file-preview` | `pnpm add react-pdf react-zoom-pan-pinch` |
 | `@devalok/shilp-sutra/composed/markdown-viewer` | `pnpm add react-markdown react-syntax-highlighter remark-gfm` |
 | `@devalok/shilp-sutra/composed/rich-chat-input` | `pnpm add @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/starter-kit @tiptap/suggestion date-fns` |

package/docs/recipes/install-tanstack-start.md

@@ -41,6 +41,7 @@ Some components ship hard peers as optional. **Install BEFORE first import.**
 | When you import… | Install |
 |---|---|
 | `@devalok/shilp-sutra/composed/date-picker` | `pnpm add date-fns` |
+| `@devalok/shilp-sutra/composed/diff` | `pnpm add react-syntax-highlighter` |
 | `@devalok/shilp-sutra/composed/file-preview` | `pnpm add react-pdf react-zoom-pan-pinch` |
 | `@devalok/shilp-sutra/composed/markdown-viewer` | `pnpm add react-markdown react-syntax-highlighter remark-gfm` |
 | `@devalok/shilp-sutra/composed/rich-chat-input` | `pnpm add @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/starter-kit @tiptap/suggestion date-fns` |

package/docs/recipes/install-vite.md

@@ -47,6 +47,7 @@ Some components ship hard peers as optional. **Install BEFORE first import.**
 | When you import… | Install |
 |---|---|
 | `@devalok/shilp-sutra/composed/date-picker` | `pnpm add date-fns` |
+| `@devalok/shilp-sutra/composed/diff` | `pnpm add react-syntax-highlighter` |
 | `@devalok/shilp-sutra/composed/file-preview` | `pnpm add react-pdf react-zoom-pan-pinch` |
 | `@devalok/shilp-sutra/composed/markdown-viewer` | `pnpm add react-markdown react-syntax-highlighter remark-gfm` |
 | `@devalok/shilp-sutra/composed/rich-chat-input` | `pnpm add @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/starter-kit @tiptap/suggestion date-fns` |
@@ -136,6 +137,7 @@ export function ThemeToggle() {
 
 If you installed `sonner`, mount the Toaster once near the app root:
 
+<!-- typecheck-skip: imports the reader's own App entry -->
 ```tsx
 // src/main.tsx
 import { StrictMode } from "react";

package/docs/recipes/server-components.md

@@ -78,7 +78,7 @@ export function MyButton() {
 |---|---|
 | `ContentCard` | All other composed components become client islands when rendered |
 | `PageHeader` | |
-| `LoadingSkeleton` | |
+| `CardSkeleton` / `TableSkeleton` / `BoardSkeleton` / `ListSkeleton` | |
 | `PageSkeletons` | |
 
 ### `@devalok/shilp-sutra/shell`
@@ -127,20 +127,23 @@ All shilp-sutra components SSR cleanly. They have no client-only side effects at
 
 Use `<Suspense>` boundaries normally:
 
+<!-- typecheck-skip: ClientHeavyComponent is the reader's own component -->
 ```tsx
 import { Suspense } from "react";
-import { LoadingSkeleton } from "@devalok/shilp-sutra/composed/loading-skeleton";
+import { CardSkeleton } from "@devalok/shilp-sutra/composed/loading-skeleton";
 
 export default function Page() {
   return (
-    <Suspense fallback={<LoadingSkeleton variant="page" />}>
+    <Suspense fallback={<CardSkeleton />}>
       <ClientHeavyComponent />
     </Suspense>
   );
 }
 ```
 
-Both `<Suspense>` and `<LoadingSkeleton>` are server-safe.
+Both `<Suspense>` and the skeletons are server-safe. The module exports
+`CardSkeleton`, `TableSkeleton`, `BoardSkeleton` and `ListSkeleton` — pick the
+one whose shape matches what is loading.
 
 ## Common RSC mistakes
 

package/docs/recipes/troubleshoot.md

@@ -91,6 +91,7 @@ After editing, delete the lockfile + `node_modules` and reinstall.
 
 Add:
 
+<!-- typecheck-skip: a fragment of next.config, not a standalone module -->
 ```ts
 transpilePackages: ["@devalok/shilp-sutra"],
 ```

package/llms.txt

@@ -1,6 +1,6 @@
 # @devalok/shilp-sutra
 
-> Radix UI + Tailwind 4 (CSS-first) + CVA design system for Devalok apps, v0.56.0.
+> Radix UI + Tailwind 4 (CSS-first) + CVA design system for Devalok apps, v0.59.0.
 > Built on the same primitives as shadcn/ui but with DIFFERENT prop APIs — never guess from shadcn knowledge; verify every prop.
 > This file is a ROUTER: it tells you what exists and where to get details. Do not look for prop tables here — fetch them per component (MCP tool or per-component doc file below).
 
@@ -152,6 +152,7 @@ Format: `[name](doc path): summary`. Import paths follow `@devalok/shilp-sutra/<
 
 ### shell
 - [app-command-palette](docs/components/shell/app-command-palette.md)
+- [app-shell](docs/components/shell/app-shell.md)
 - [bottom-navbar](docs/components/shell/bottom-navbar.md)
 - [command-registry](docs/components/shell/command-registry.md): Exports: CommandRegistryProvider, useCommandRegistry
 - [link-context](docs/components/shell/link-context.md): Exports: LinkProvider, useLink

package/make-kit/Guidelines.md

@@ -22,10 +22,10 @@
 These are not preferences. Generated code that violates them is wrong.
 
 1. **Use design system components, not raw HTML.** `<Button>` not `<button>`. `<Input>` not `<input>`. `<Text>` not `<span>`/`<p>` (when typographic semantics matter). `<Stack>` not bare flex divs.
-2. **Use semantic tokens, never hex / rgb / hsl.** `bg-surface-raised` not `bg-white`. `text-fg` not `text-zinc-900`. `bg-accent-9` not `bg-pink-500`.
+2. **Use semantic tokens, never hex / rgb / hsl.** `bg-surface-panel` not `bg-white`. `text-fg` not `text-zinc-900`. `bg-accent-9` not `bg-pink-500`.
 3. **Spacing uses `ds-*` cadence.** `p-ds-05`, `gap-ds-03`. Never `p-4` / `p-6`. Default cadence is `ds-03 / ds-05 / ds-07` (related items / grouped sections / page sections). Do not reach for every adjacent token (`ds-04`, `ds-06`) — three tiers, not five.
 4. **Prefer `variant="soft"` over `variant="outline"` for non-primary actions.** Soft (tinted bg, no visible border) reads better in data-dense UIs. Outline only when on a colored bg or paired with a primary for explicit hierarchy.
-5. **Surface layering is strict.** Page = `surface-base`. Cards/panels/widgets = `surface-raised`. Dialogs/popovers/dropdowns/inputs = `surface-overlay`. Shell chrome (sidebar, topbar) = `surface-sunken`. Tooltips = `surface-inverted`. If you're unsure, read `foundations/surfaces.md`.
+5. **Surface layering is strict.** Page = `surface-base`. Cards/panels/widgets = `surface-panel`. Dialogs/popovers/dropdowns/inputs = `surface-overlay`. Shell chrome (sidebar, topbar) = `surface-sunken`. Tooltips = `surface-inverted`. If you're unsure, read `foundations/surfaces.md`.
 6. **Never combine `border-*` + `shadow-*` tokens.** Shadow tokens already include a 1px ring layer. Adding an explicit border creates a 2-px edge.
 7. **Icons use `<Icon icon={...} />` from `@tabler/icons-react`.** Do not import lucide, heroicons, mui-icons. The icon system auto-sizes via `IconProvider` context.
 8. **Toasts mount once at app root.** `<Toaster />` (singleton). All triggering is imperative: `toast.success("...")`, `toast.error("...")`.

package/make-kit/components/button.md

@@ -19,7 +19,7 @@ import { Button } from '@devalok/shilp-sutra/ui/button'
 |---|---|
 | `solid` (default) | Primary CTA. One per region. Heavy visual weight. |
 | `soft` | Secondary action. **Preferred default for any non-primary action.** Tinted bg, colored text, no visible border — warmer than outline, brand-consistent. |
-| `outline` | Secondary action on a colored / `surface-raised` bg where soft's tint disappears. In toolbars / icon-dense rows. Paired adjacent to a primary that needs explicit hierarchy. |
+| `outline` | Secondary action on a colored / `surface-panel` bg where soft's tint disappears. In toolbars / icon-dense rows. Paired adjacent to a primary that needs explicit hierarchy. |
 | `ghost` | Tertiary / dismissive — close, cancel, skip. Minimal weight. |
 | `link` | Inline action that should read as a link but behave as a button. Use sparingly. |