@devalok/shilp-sutra 0.52.0 → 0.53.0

package/docs/components/composed/schedule-view.md

@@ -10,14 +10,19 @@
     events: ScheduleEvent[] (REQUIRED) — { id, title, start: Date, end: Date, color? }
     onEventClick?: (event: ScheduleEvent) => void
     onSlotClick?: (start: Date, end: Date) => void
-    startHour: number (default: 8)
-    endHour: number (default: 18, exclusive)
-    slotDuration: number (minutes, default: 30)
+    startHour?: number (default: 8)
+    endHour?: number (default: 18, exclusive)
+    slotDuration?: number (minutes, default: 30)
+    selectedEventId?: string (rings the active event)
+    renderEvent?: (event) => ReactNode (custom event body)
+    header?: ReactNode (toolbar slot above the grid)
+    emptyState?: ReactNode (shown when events is empty)
+    height?: number | string (grid body height, default 480)
 
 Event colors: "accent" | "success" | "warning" | "error" | "info" | "neutral"
 
 ## Defaults
-    startHour=8, endHour=18, slotDuration=30
+    startHour=8, endHour=18, slotDuration=30, height=480
 
 ## Example
 ```jsx
@@ -32,7 +37,12 @@ Event colors: "accent" | "success" | "warning" | "error" | "info" | "neutral"
 ## Composability
 - **Day / Week calendar view** for time-block display (meetings, shifts, availability). Not a full calendar app — no month view, no drag-to-create.
 - **Event data is consumer-owned:** You pass `events` as an array; ScheduleView doesn't fetch, doesn't cache, doesn't expand recurring events. All scheduling logic lives in your app.
-- **Event click + slot click** — `onEventClick` for existing events; `onSlotClick` for creating new events (fires with start/end of the empty slot).
+- **Event click + slot click** — `onEventClick` for existing events; `onSlotClick` for creating new events (fires with start/end of the empty slot). **Slots are only interactive (focusable + keyboard-navigable) when `onSlotClick` is set** — otherwise they render as inert grid lines, so a read-only schedule adds no keyboard/AT tab stops.
+- **Keyboard (interactive slots):** roving tabindex — Arrow keys move between slots (up/down within a day, left/right across days, RTL-aware), Home/End jump within the day; only one slot is in the tab order at a time.
+- **Overlapping events** are partitioned into side-by-side columns automatically so double-booked times stay legible.
+- **Live now-line** ticks every minute and scrolls into view on mount.
+- **`renderEvent`** customizes the event block body; **`header`** adds a toolbar; **`selectedEventId`** rings the active event; **`emptyState`** shows when there are no events.
+- **Composes the DS card shell tokens** (`surface-2` + `rounded-surface` + border) and is RTL-safe (logical properties throughout).
 - **Color vocabulary matches the DS** — `accent/success/warning/error/info/neutral`. Map your event types to these at the data layer.
 - **endHour is exclusive:** `endHour=18` means the last visible slot starts at 17:30 (with 30min slots). Match your UX expectation: 9-5 typically means `startHour=9, endHour=18`.
 - **Pairs with date-picker/composed** — use DatePicker or DateRangePicker to choose which date to show; pass that as ScheduleView's `date`.
@@ -43,6 +53,11 @@ Event colors: "accent" | "success" | "warning" | "error" | "info" | "neutral"
 - Events that span outside `startHour`/`endHour` may be clipped
 
 ## Changes
+### v0.53.0
+- **Changed** Read-only schedules no longer flood the tab order — slots are interactive only when `onSlotClick` is set; otherwise inert grid lines. Interactive slots use roving tabindex + Arrow/Home/End keyboard navigation (RTL-aware).
+- **Changed** Overlapping events now lay out in side-by-side columns instead of stacking illegibly. The now-line ticks live (per-minute) and scrolls into view; shell uses the `surface-2` card tier (fixed the prior `surface-raised` + dead-`border-card-strong` regression); layout uses logical (RTL-safe) properties; magic-number sizes tokenized.
+- **Added** `selectedEventId`, `renderEvent`, `header`, `emptyState`, and `height` props.
+
 ### v0.49.0
 - **BREAKING** `ScheduleEvent.color` value `"primary"` renamed `"accent"` (DS colour vocabulary). It was the default, so untyped events are unaffected.
 - **Added** keyboard focus rings on slot cells + event blocks; current-time indicator uses the shared `<Dot>`.

package/docs/components/shell/bottom-navbar.md

@@ -6,16 +6,23 @@
 
 ## Props
     currentPath?: string (optional)
-    user?: BottomNavbarUser | null (optional)
+    user?: BottomNavbarUser | null (drives per-item role gating, optional)
     primaryItems?: BottomNavItem[] (max 4 recommended, optional)
-    moreItems?: BottomNavItem[] (overflow items in "More" menu, optional)
+    moreItems?: BottomNavItem[] (overflow items in "More" sheet, optional)
+    indicator?: 'pill' | 'underline' | 'tint' | 'none' (active-item indicator; default 'pill')
+    labelVisibility?: 'always' | 'selected'
     className?: string
 
-BottomNavItem: { title: string, href: string, icon: ReactNode, exact?: boolean, badge?: number }
+BottomNavItem: { title: string, href: string, icon: IconInput, activeIcon?: IconInput, exact?: boolean, badge?: number, roles?: string[], canView?: (user: BottomNavbarUser | null) => boolean }
 BottomNavbarUser: { name: string, role?: string }
 
 ## Defaults
-    None
+    currentPath: '/'
+    user: null
+    primaryItems: []
+    moreItems: []
+    indicator: 'pill'
+    labelVisibility: 'always'
 
 ## Example
 ```jsx
@@ -37,7 +44,11 @@ BottomNavbarUser: { name: string, role?: string }
   ```
 - **Primary vs overflow:** `primaryItems` (max 4) for the always-visible slots; `moreItems` go into a "More" sheet that opens on tap. Don't exceed 4 primary — the bar becomes cramped.
 - **Router integration via LinkProvider:** Each nav item is rendered using the framework-specific Link component registered in LinkProvider. Without LinkProvider, you get full-page reloads on tap.
-- **Badge numbers** cap at 99+ (same as BadgeIndicator pattern).
+- **Badge numbers** cap at 99+ (composes the `Badge` primitive).
+- **Role gating:** each item may declare `roles: string[]` (shown only when `user.role` matches) or a `canView(user)` predicate for arbitrary logic (`canView` wins). Items with neither are always visible. Gating applies to both `primaryItems` and `moreItems`.
+- **Overflow sheet:** the "More" surface is the DS `Sheet` (`side="bottom"`) — it inherits focus trap, scroll lock, return-focus, and `aria-modal`; the trigger is wired with `aria-haspopup`/`aria-controls` automatically.
+- **Indicator (animated):** the active indicator slides to the selected item (shared-element `layoutId`) and fades in on first appearance. Modes: `pill` (default, Material-3 tonal pill behind the icon), `underline` (top accent bar), `tint` (subtle bg on the whole active cell), `none` (no shape — pair with `activeIcon` for the iOS filled-icon look). `labelVisibility="selected"` shows labels only for the active item.
+- **Filled-when-active:** set `activeIcon` on an item (e.g. a Tabler `*Filled` variant) to swap the icon for a filled version while it's the active route; falls back to `icon`.
 - **Not for desktop:** The viewport-fixed positioning + touch-optimized sizing don't translate well to desktop. Hide behind `md:hidden`.
 
 ## Gotchas
@@ -47,6 +58,14 @@ BottomNavbarUser: { name: string, role?: string }
 - Requires LinkProvider for framework-specific link components (e.g., Next.js Link)
 
 ## Changes
+### v0.53.0
+- **Changed** Overflow "More" menu re-founded on the DS `Sheet` primitive — inherits focus trap, scroll lock, return-focus, `aria-modal`, and trigger↔panel ARIA wiring (was a hand-rolled `role="dialog"` with none of these). Composes `Badge` for notification counts and the Sheet's built-in close (≥ touch target).
+- **Added** Per-item role gating: `roles?: string[]` and `canView?: (user) => boolean` on `BottomNavItem`. The previously-inert `user` prop now drives it.
+- **Added** `activeIcon` per item — a filled/alternate icon shown while active (falls back to `icon`). Tightened the icon lozenge padding so icon-only items read less airy.
+- **Added** `indicator` (default **`pill`** — Material-3; plus `underline`, `tint`, `none`) and `labelVisibility` ('always' | 'selected'). The active indicator animates (slides) between items via a shared-element `layoutId`.
+- **Added** Label truncation + logical (RTL-safe) properties; overflow grid adapts to item count.
+- **Fixed** Notification badge `zoom-in` animation now reduced-motion gated.
+
 ### v0.19.0
 - **Changed** Background elevated from `bg-surface-1` to `bg-surface-2` for visual hierarchy above app background
 - **Changed** "More" menu and interactive items bumped accordingly

package/docs/components/ui/autocomplete.md

@@ -6,16 +6,23 @@
 
 ## Props
     options: AutocompleteOption[] (REQUIRED) — { value: string, label: string }
-    value: AutocompleteOption | null
+    value?: AutocompleteOption | null (controlled)
+    defaultValue?: AutocompleteOption | null (uncontrolled initial)
     onValueChange?: (option: AutocompleteOption) => void
-    placeholder: string
-    emptyText: string (default: "No options")
-    disabled: boolean
-    className: string
-    id: string
+    placeholder?: string
+    emptyText?: string (default: "No options")
+    disabled?: boolean
+    size?: (forwarded to Input)
+    state?: 'default' | 'error' | 'warning' | 'success' (forwarded to Input)
+    isLoading?: boolean
+    loadingText?: string (default: "Loading…")
+    renderOption?: (option, query) => ReactNode
+    className?: string
+    id?: string
 
 ## Defaults
     emptyText="No options"
+    loadingText="Loading…"
 
 ## Example
 ```jsx
@@ -28,17 +35,26 @@
 ```
 
 ## Composability
-- **Autocomplete vs Combobox:** Autocomplete allows free-text input (users can type anything); Combobox enforces selection from the list. Pick by whether "off-list" values are valid (e.g. city field that accepts typos → Autocomplete; tag picker from a fixed vocabulary → Combobox).
-- **Value shape is an object** (`{ value, label }`), not a plain string — this preserves label/value decoupling for display-vs-storage.
-- **FormField:** Does NOT auto-consume FormField state. Set explicit error styling via className if needed.
+- **Composes `Input`** — the field is the DS `Input`, so it inherits `size`, error/`state` painting, read-only, hover, and FormField wiring. Autocomplete owns only the dropdown + behavior.
+- **Autocomplete vs Combobox:** Autocomplete allows free-text input (users can type anything); Combobox enforces selection from the list.
+- **Value shape is an object** (`{ value, label }`), not a plain string. Controlled via `value`, or uncontrolled via `defaultValue`.
+- **FormField:** auto-consumes FormField state (via the composed Input) — inside a FormField, error border + `aria-invalid`/`aria-describedby`/`required` are wired automatically. Pass `state` to override.
+- **Async / "type to search":** set `isLoading` to show a spinner (in the field + the listbox) with `loadingText`.
+- **Matched-text highlight:** the query substring is bolded in each option by default; override the whole row with `renderOption`.
 - **Portal rendering:** Dropdown portals to body with z-popover (1400) — stacks above Dialog/Sheet.
-- **Keyboard:** ArrowDown/Up navigate suggestions, Enter selects, Esc closes. Typeahead is the input's native filtering.
+- **Keyboard:** ArrowDown/Up/Home/End navigate, Enter selects, Esc closes.
 
 ## Gotchas
 - Allows free-text input (no forced selection) — use Combobox for forced selection
 - value is an object { value, label }, NOT just a string
+- Client-side filtering only (known list). For huge/remote lists, drive `options` yourself with `isLoading` — no built-in virtualization.
 
 ## Changes
+### v0.53.0
+- **Changed** Re-parented onto the DS `Input` primitive — inherits `size`, error/`state` painting, read-only, hover, and FormField auto-consumption (previously re-rolled its own `<input>` and read FormField error but never painted it).
+- **Added** `defaultValue` (uncontrolled), `size`, `state`, `isLoading`/`loadingText` (async), `renderOption`, and matched-substring highlighting.
+- **Fixed** Doc corrected — it DOES auto-consume FormField (via Input). Dropped a keystroke-frequency stagger animation + a dead effect.
+
 ### v0.18.0
 - **Fixed** Added `useEffect` to sync query when external value changes
 

package/llms.txt

@@ -1,6 +1,6 @@
 # @devalok/shilp-sutra
 
-> Radix UI + Tailwind 4 (CSS-first) + CVA design system for Devalok apps, v0.52.0.
+> Radix UI + Tailwind 4 (CSS-first) + CVA design system for Devalok apps, v0.53.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).
 

package/mcp-manifest.json

@@ -2,7 +2,7 @@
   "$schema": "./mcp-manifest.schema.json",
   "manifestVersion": "1.2.0",
   "package": "@devalok/shilp-sutra",
-  "packageVersion": "0.52.0",
+  "packageVersion": "0.53.0",
   "components": {
     "accordion": {
       "displayName": "Accordion",
@@ -386,7 +386,16 @@
             "name": "union",
             "raw": "AutocompleteOption | null"
           },
-          "required": false
+          "required": false,
+          "description": "controlled"
+        },
+        "defaultValue": {
+          "type": {
+            "name": "union",
+            "raw": "AutocompleteOption | null"
+          },
+          "required": false,
+          "description": "uncontrolled initial"
         },
         "onValueChange": {
           "type": {
@@ -414,6 +423,46 @@
           },
           "required": false
         },
+        "size": {
+          "type": {
+            "name": "object",
+            "raw": "(forwarded to Input)"
+          },
+          "required": false
+        },
+        "state": {
+          "type": {
+            "name": "enum",
+            "value": [
+              "default",
+              "error",
+              "warning",
+              "success"
+            ]
+          },
+          "required": false,
+          "description": "forwarded to Input"
+        },
+        "isLoading": {
+          "type": {
+            "name": "boolean"
+          },
+          "required": false
+        },
+        "loadingText": {
+          "type": {
+            "name": "string"
+          },
+          "required": false,
+          "defaultValue": "Loading…"
+        },
+        "renderOption": {
+          "type": {
+            "name": "function",
+            "raw": "(option, query) => ReactNode"
+          },
+          "required": false
+        },
         "className": {
           "type": {
             "name": "string"
@@ -429,25 +478,34 @@
       },
       "composition": {
         "notes": [
-          "**Autocomplete vs Combobox:** Autocomplete allows free-text input (users can type anything); Combobox enforces selection from the list. Pick by whether \"off-list\" values are valid (e.g. city field that accepts typos → Autocomplete; tag picker from a fixed vocabulary → Combobox).",
-          "**Value shape is an object** (`{ value, label }`), not a plain string — this preserves label/value decoupling for display-vs-storage.",
-          "**FormField:** Does NOT auto-consume FormField state. Set explicit error styling via className if needed.",
+          "**Composes `Input`** — the field is the DS `Input`, so it inherits `size`, error/`state` painting, read-only, hover, and FormField wiring. Autocomplete owns only the dropdown + behavior.",
+          "**Autocomplete vs Combobox:** Autocomplete allows free-text input (users can type anything); Combobox enforces selection from the list.",
+          "**Value shape is an object** (`{ value, label }`), not a plain string. Controlled via `value`, or uncontrolled via `defaultValue`.",
+          "**FormField:** auto-consumes FormField state (via the composed Input) — inside a FormField, error border + `aria-invalid`/`aria-describedby`/`required` are wired automatically. Pass `state` to override.",
+          "**Async / \"type to search\":** set `isLoading` to show a spinner (in the field + the listbox) with `loadingText`.",
+          "**Matched-text highlight:** the query substring is bolded in each option by default; override the whole row with `renderOption`.",
           "**Portal rendering:** Dropdown portals to body with z-popover (1400) — stacks above Dialog/Sheet.",
-          "**Keyboard:** ArrowDown/Up navigate suggestions, Enter selects, Esc closes. Typeahead is the input's native filtering."
+          "**Keyboard:** ArrowDown/Up/Home/End navigate, Enter selects, Esc closes."
         ]
       },
       "docPath": "docs/components/ui/autocomplete.md",
       "defaults": {
-        "emptyText": "No options"
+        "emptyText": "No options",
+        "loadingText": "Loading…"
       },
       "examples": [
         "<Autocomplete\n  options={[{ value: 'mumbai', label: 'Mumbai' }]}\n  value={selectedCity}\n  onValueChange={setSelectedCity}\n  placeholder=\"Search cities...\"\n/>"
       ],
       "gotchas": [
         "Allows free-text input (no forced selection) — use Combobox for forced selection",
-        "value is an object { value, label }, NOT just a string"
+        "value is an object { value, label }, NOT just a string",
+        "Client-side filtering only (known list). For huge/remote lists, drive `options` yourself with `isLoading` — no built-in virtualization."
       ],
       "changes": [
+        {
+          "version": "0.53.0",
+          "summary": "**Changed** Re-parented onto the DS `Input` primitive — inherits `size`, error/`state` painting, read-only, hover, and FormField auto-consumption (previously re-rolled its own `<input>` and read FormField error but never painted it)."
+        },
         {
           "version": "0.18.0",
           "summary": "**Fixed** Added `useEffect` to sync query when external value changes"
@@ -10968,7 +11026,7 @@
       "displayName": "PriorityIndicator",
       "tier": "composed",
       "import": "@devalok/shilp-sutra/composed/priority-indicator",
-      "serverSafe": true,
+      "serverSafe": false,
       "description": "",
       "props": {
         "priority": {
@@ -10978,6 +11036,13 @@
           },
           "required": false
         },
+        "iconOnly": {
+          "type": {
+            "name": "boolean"
+          },
+          "required": false,
+          "description": "icon-only chip, no visible text"
+        },
         "display": {
           "type": {
             "name": "enum",
@@ -10987,31 +11052,41 @@
             ]
           },
           "required": false,
-          "defaultValue": "full"
+          "description": "@deprecated — use iconOnly"
+        },
+        "children": {
+          "type": {
+            "name": "ReactNode"
+          },
+          "required": false,
+          "description": "override the label, e.g. i18n"
         }
       },
       "composition": {
         "notes": [
-          "**Server-safe priority label** — icon + color + text for task / issue priority.",
+          "**Composes `Badge`** — radius, color semantics, a11y labelling, and reduced-motion handling all come from one place (no bespoke re-roll).",
           "**Composes inside list rows, DataTable cells, Card headers, task panels** — anywhere a priority flag fits.",
-          "**display=\"compact\"** shows only the icon (with priority text as title attribute for tooltip). Use in tight cells; use `display=\"full\"` (default) in free space.",
-          "**Case-insensitive priority** — accepts both UPPERCASE (LOW/MEDIUM/HIGH/URGENT) and lowercase. Designed to match both backend conventions without manual coercion.",
-          "Color semantics: LOW=success, MEDIUM=warning, HIGH=error, URGENT=error with bolder icon."
+          "**`iconOnly`** shows only the icon with a real accessible name (`role=\"img\"` + `aria-label`), for tight cells. Omit it (default) for icon + label.",
+          "**Severity by weight, not motion** — URGENT renders as a solid fill so the top tier reads at a glance; the others are soft. No animation (removes the prior perpetual pulse).",
+          "**Case-insensitive priority** — accepts both UPPERCASE and lowercase; unknown values fall back to MEDIUM instead of throwing.",
+          "**`children`** overrides the label for i18n / custom copy.",
+          "Color semantics: LOW = slate (neutral), MEDIUM = warning, HIGH = error (soft), URGENT = error (solid)."
         ]
       },
       "docPath": "docs/components/composed/priority-indicator.md",
-      "defaults": {
-        "display": "full"
-      },
       "examples": [
-        "<PriorityIndicator priority=\"HIGH\" />\n<PriorityIndicator priority=\"low\" display=\"compact\" />"
+        "<PriorityIndicator priority=\"HIGH\" />\n<PriorityIndicator priority=\"low\" iconOnly />\n<PriorityIndicator priority=\"URGENT\">Critical</PriorityIndicator>"
       ],
       "gotchas": [
-        "Case-insensitive — \"low\" and \"LOW\" both work",
-        "Server-safe: can be imported directly in Next.js Server Components",
-        "`compact` display shows only the icon; `full` shows icon + text label"
+        "Case-insensitive — \"low\" and \"LOW\" both work; unknown values fall back to MEDIUM",
+        "`iconOnly` shows only the icon (accessible-named); default shows icon + text label",
+        "`display` is deprecated — use `iconOnly`"
       ],
       "changes": [
+        {
+          "version": "0.53.0",
+          "summary": "**Changed** Recomposed on the `Badge` primitive (was a bespoke re-rolled chip): inherits pill radius, color semantics, accessible labelling."
+        },
         {
           "version": "0.2.0",
           "summary": "**Added** Identified as server-safe component"
@@ -11596,13 +11671,55 @@
           "required": false,
           "description": "minutes, default: 30",
           "defaultValue": 30
+        },
+        "selectedEventId": {
+          "type": {
+            "name": "string"
+          },
+          "required": false,
+          "description": "rings the active event"
+        },
+        "renderEvent": {
+          "type": {
+            "name": "function",
+            "raw": "(event) => ReactNode (custom event body)"
+          },
+          "required": false
+        },
+        "header": {
+          "type": {
+            "name": "ReactNode"
+          },
+          "required": false,
+          "description": "toolbar slot above the grid"
+        },
+        "emptyState": {
+          "type": {
+            "name": "ReactNode"
+          },
+          "required": false,
+          "description": "shown when events is empty"
+        },
+        "height": {
+          "type": {
+            "name": "union",
+            "raw": "number | string"
+          },
+          "required": false,
+          "description": "grid body height, default 480",
+          "defaultValue": 480
         }
       },
       "composition": {
         "notes": [
           "**Day / Week calendar view** for time-block display (meetings, shifts, availability). Not a full calendar app — no month view, no drag-to-create.",
           "**Event data is consumer-owned:** You pass `events` as an array; ScheduleView doesn't fetch, doesn't cache, doesn't expand recurring events. All scheduling logic lives in your app.",
-          "**Event click + slot click** — `onEventClick` for existing events; `onSlotClick` for creating new events (fires with start/end of the empty slot).",
+          "**Event click + slot click** — `onEventClick` for existing events; `onSlotClick` for creating new events (fires with start/end of the empty slot). **Slots are only interactive (focusable + keyboard-navigable) when `onSlotClick` is set** — otherwise they render as inert grid lines, so a read-only schedule adds no keyboard/AT tab stops.",
+          "**Keyboard (interactive slots):** roving tabindex — Arrow keys move between slots (up/down within a day, left/right across days, RTL-aware), Home/End jump within the day; only one slot is in the tab order at a time.",
+          "**Overlapping events** are partitioned into side-by-side columns automatically so double-booked times stay legible.",
+          "**Live now-line** ticks every minute and scrolls into view on mount.",
+          "**`renderEvent`** customizes the event block body; **`header`** adds a toolbar; **`selectedEventId`** rings the active event; **`emptyState`** shows when there are no events.",
+          "**Composes the DS card shell tokens** (`surface-2` + `rounded-surface` + border) and is RTL-safe (logical properties throughout).",
           "**Color vocabulary matches the DS** — `accent/success/warning/error/info/neutral`. Map your event types to these at the data layer.",
           "**endHour is exclusive:** `endHour=18` means the last visible slot starts at 17:30 (with 30min slots). Match your UX expectation: 9-5 typically means `startHour=9, endHour=18`.",
           "**Pairs with date-picker/composed** — use DatePicker or DateRangePicker to choose which date to show; pass that as ScheduleView's `date`."
@@ -11612,7 +11729,8 @@
       "defaults": {
         "startHour": 8,
         "endHour": 18,
-        "slotDuration": 30
+        "slotDuration": 30,
+        "height": 480
       },
       "examples": [
         "<ScheduleView\n  view=\"week\"\n  date={new Date()}\n  events={calendarEvents}\n  onEventClick={(e) => openEvent(e.id)}\n/>"
@@ -11623,6 +11741,10 @@
         "Events that span outside `startHour`/`endHour` may be clipped"
       ],
       "changes": [
+        {
+          "version": "0.53.0",
+          "summary": "**Changed** Read-only schedules no longer flood the tab order — slots are interactive only when `onSlotClick` is set; otherwise inert grid lines. Interactive slots use roving tabindex + Arrow/Home/End keyboard navigation (RTL-aware)."
+        },
         {
           "version": "0.49.0",
           "summary": "**BREAKING** `ScheduleEvent.color` value `\"primary\"` renamed `\"accent\"` (DS colour vocabulary). It was the default, so untyped events are unaffected."
@@ -11967,7 +12089,7 @@
             "raw": "BottomNavbarUser | null"
           },
           "required": false,
-          "description": "optional"
+          "description": "drives per-item role gating, optional"
         },
         "primaryItems": {
           "type": {
@@ -11983,7 +12105,30 @@
             "raw": "BottomNavItem[]"
           },
           "required": false,
-          "description": "overflow items in \"More\" menu, optional"
+          "description": "overflow items in \"More\" sheet, optional"
+        },
+        "indicator": {
+          "type": {
+            "name": "enum",
+            "value": [
+              "pill",
+              "underline",
+              "tint",
+              "none"
+            ]
+          },
+          "required": false,
+          "description": "active-item indicator; default 'pill'"
+        },
+        "labelVisibility": {
+          "type": {
+            "name": "enum",
+            "value": [
+              "always",
+              "selected"
+            ]
+          },
+          "required": false
         },
         "className": {
           "type": {
@@ -11998,7 +12143,11 @@
           "**Responsive switch pattern:** Use `useIsMobile()` hook to conditionally render AppSidebar (desktop) or BottomNavbar (mobile). Example: ```jsx const isMobile = useIsMobile() return isMobile ? <BottomNavbar ... /> : <AppSidebar ... /> ```",
           "**Primary vs overflow:** `primaryItems` (max 4) for the always-visible slots; `moreItems` go into a \"More\" sheet that opens on tap. Don't exceed 4 primary — the bar becomes cramped.",
           "**Router integration via LinkProvider:** Each nav item is rendered using the framework-specific Link component registered in LinkProvider. Without LinkProvider, you get full-page reloads on tap.",
-          "**Badge numbers** cap at 99+ (same as BadgeIndicator pattern).",
+          "**Badge numbers** cap at 99+ (composes the `Badge` primitive).",
+          "**Role gating:** each item may declare `roles: string[]` (shown only when `user.role` matches) or a `canView(user)` predicate for arbitrary logic (`canView` wins). Items with neither are always visible. Gating applies to both `primaryItems` and `moreItems`.",
+          "**Overflow sheet:** the \"More\" surface is the DS `Sheet` (`side=\"bottom\"`) — it inherits focus trap, scroll lock, return-focus, and `aria-modal`; the trigger is wired with `aria-haspopup`/`aria-controls` automatically.",
+          "**Indicator (animated):** the active indicator slides to the selected item (shared-element `layoutId`) and fades in on first appearance. Modes: `pill` (default, Material-3 tonal pill behind the icon), `underline` (top accent bar), `tint` (subtle bg on the whole active cell), `none` (no shape — pair with `activeIcon` for the iOS filled-icon look). `labelVisibility=\"selected\"` shows labels only for the active item.",
+          "**Filled-when-active:** set `activeIcon` on an item (e.g. a Tabler `*Filled` variant) to swap the icon for a filled version while it's the active route; falls back to `icon`.",
           "**Not for desktop:** The viewport-fixed positioning + touch-optimized sizing don't translate well to desktop. Hide behind `md:hidden`."
         ]
       },
@@ -12013,6 +12162,10 @@
         "Requires LinkProvider for framework-specific link components (e.g., Next.js Link)"
       ],
       "changes": [
+        {
+          "version": "0.53.0",
+          "summary": "**Changed** Overflow \"More\" menu re-founded on the DS `Sheet` primitive — inherits focus trap, scroll lock, return-focus, `aria-modal`, and trigger↔panel ARIA wiring (was a hand-rolled `role=\"dialog\"` with none of these). Composes `Badge` for notification counts and the Sheet's built-in close (≥ touch target)."
+        },
         {
           "version": "0.19.0",
           "summary": "**Changed** Background elevated from `bg-surface-1` to `bg-surface-2` for visual hierarchy above app background"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devalok/shilp-sutra",
-  "version": "0.52.0",
+  "version": "0.53.0",
   "description": "Devalok Design System — accessible React components, OKLCH design tokens, and Tailwind 4 CSS-first setup. Ships with AI-agent setup recipes.",
   "license": "MIT",
   "author": "Devalok Design & Strategy Studios <shilp-sutra@devalok.in>",

package/skill/SKILL.md

@@ -3,7 +3,7 @@ name: shilp-sutra
 description: Add, configure, and use components from Devalok's shilp-sutra design system (@devalok/shilp-sutra) — a Tailwind 4 + React 19 + CVA library with 110+ accessible components, OKLCH design tokens, framer-motion animations, and per-component RSC-safe entry points. Use this skill whenever the user mentions shilp-sutra, Devalok, the @devalok npm scope, or asks to install/add/style/theme UI in any React project that already depends on the package — even if they don't name it explicitly. Use it instead of generic shadcn/ui, MUI, or Chakra knowledge when shilp-sutra is in the project. Covers Next.js (App + Pages), Vite, Astro, Remix, TanStack Start setup playbooks; component API and variant reference; brand token customization; Server Component import patterns; and a troubleshoot tree for the thirteen most common breakages.
 license: MIT
 metadata:
-  version: "0.52.0"
+  version: "0.53.0"
   author: Devalok Design & Strategy Studios
   homepage: https://github.com/devalok-design/shilp-sutra
   npm: https://www.npmjs.com/package/@devalok/shilp-sutra

package/skill/references/components.md

@@ -2,7 +2,7 @@
 
 # @devalok/shilp-sutra
 
-> Radix UI + Tailwind 4 (CSS-first) + CVA design system for Devalok apps, v0.52.0.
+> Radix UI + Tailwind 4 (CSS-first) + CVA design system for Devalok apps, v0.53.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).