@devalok/shilp-sutra 0.51.0 → 0.53.0

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/docs/components/ui/button.md

@@ -6,7 +6,7 @@
 
 ## Props
     variant: "solid" | "soft" | "outline" | "ghost" | "link"
-    color: "accent" | "error" | "success" | "warning" | "neutral"
+    color: "accent" | "error" | "success" | "warning" | "info" | "neutral"
     size: "xs" | "sm" | "md" | "lg" | "compact-xs" | "compact-sm" | "compact-md" | "icon" | "icon-xs" | "icon-sm" | "icon-md" | "icon-lg"
     weight: "semibold" | "normal"
     shape: "default" | "pill"
@@ -17,7 +17,7 @@
     fullWidth: boolean
     asChild: boolean
     processing: boolean | 'ambient' | 'working' | 'urgent' (marching ants SVG border)
-    processingColor: 'accent' | 'error' | 'success' | 'warning' | 'neutral' (override animation color)
+    processingColor: 'accent' | 'error' | 'success' | 'warning' | 'info' | 'neutral' (override animation color)
     processingDisabled: boolean (disable button during processing, default: true)
     onClickAsync: (e: MouseEvent) => Promise<void> (auto loading->success/error->idle, auto-activates processing)
     asyncFeedbackDuration: number (ms, default 1500)

package/docs/components/ui/segmented-control.md

@@ -6,32 +6,37 @@
 
 ## Props
     size: "sm" | "md" | "lg"
-    variant: "default" | "solid"
+    variant: "soft" | "solid"
     options: SegmentedControlOption[] (REQUIRED)
-    selectedId: string (REQUIRED)
-    onSelect: (id: string) => void (REQUIRED)
+    value: string                          // controlled
+    defaultValue: string                   // uncontrolled initial
+    onValueChange: (id: string) => void
     disabled: boolean
+    fullWidth: boolean
+    selectedId: string                     // @deprecated — use value
+    onSelect: (id: string) => void         // @deprecated — use onValueChange
 
 ## Types
-    SegmentedControlOption = { id: string, text: string, icon?: ComponentType<{ className?: string }> }
+    SegmentedControlOption = { id: string, text?: React.ReactNode, icon?: IconInput, ariaLabel?: string }
     SegmentedControlSize = 'sm' | 'md' | 'lg'
-    SegmentedControlVariant = 'default' | 'solid'
+    SegmentedControlVariant = 'soft' | 'solid'
 
 ## Defaults
     size: "md"
-    variant: "default"
+    variant: "soft"
+    fullWidth: false
 
 ## Example
 ```jsx
 <SegmentedControl
   size="md"
-  variant="default"
+  variant="soft"
   options={[
     { id: 'list', text: 'List' },
     { id: 'grid', text: 'Grid' },
   ]}
-  selectedId={viewMode}
-  onSelect={setViewMode}
+  value={viewMode}
+  onValueChange={setViewMode}
 />
 ```
 
@@ -39,15 +44,30 @@
 - **Data-driven, not compound** — unlike Tabs/ToggleGroup, SegmentedControl takes an `options` array rather than children. This makes it easier to render from a list but harder to customize per-option styling; use Tabs if you need compound children.
 - **When to use vs Tabs:** SegmentedControl is for mutually-exclusive VIEW-MODE toggles (List/Grid/Kanban) — short labels, no associated content panel. Tabs is for content switching where each tab has a corresponding TabsContent. SegmentedControl renders `role="radiogroup"` with `role="radio"` segments (a panel-less single-select); Tabs renders `role="tablist"`.
 - **Option icons** auto-size based on the `size` prop — don't set explicit icon sizes.
-- Fully controlled — there's no `defaultSelectedId`. Manage state in parent.
+- **`fullWidth`** switches segments from content-hug (default) to equal-fill: each segment takes an equal share of the container (a 2-item toggle splits 50/50, a 3-item switcher gives each a third). Use for view switchers and toolbar toggles that should fill their column; leave off for compact inline toolbars.
+- **Visual model:** a rounded-rect track (not a full pill) — a translucent recessed groove with a single soft-shadowed sliding thumb. The track has no border/inset shadow; the thumb carries the only edge. Elevation inverts in dark so the groove stays visible.
+- **Controlled or uncontrolled** — pass `value` + `onValueChange` to control it, or `defaultValue` (optional; falls back to the first option) to let it own state. Matches the Tabs/ToggleGroup vocabulary. `selectedId`/`onSelect` are deprecated aliases that still work.
+- **Option labels accept `ReactNode`** — a segment can hold a count badge or custom node, not just a string. `text` is optional: omit it for an **icon-only** segment and set `ariaLabel` so the segment still has an accessible name.
+- **Touch targets** — each segment has a 44px minimum hit area (via `touch-target`) even though the visual height stays dense.
+- **RTL** — Arrow-key navigation tracks reading order: in a right-to-left context `ArrowLeft` moves to the next option and `ArrowRight` to the previous (detected from the nearest `dir` attribute).
 - Built from scratch (no Radix primitive) — standard HTML buttons with `role="radio"` + `aria-checked` and roving tabindex.
 
 ## Gotchas
-- Controlled only — selectedId + onSelect are required
+- Controlled (`value`) or uncontrolled (`defaultValue`) — `selectedId`/`onSelect` are deprecated aliases
 - Uses data-driven API (options prop), not compound children
 - Use Tabs (not SegmentedControl) when you need associated content panels per option
 
 ## Changes
+### v0.52.0
+- **Changed** Visual rebuild — rounded-rect track (was full pill), translucent recessed track with no border/inset, single ring-less soft-shadow thumb. Dark-mode elevation inverts so the groove stays visible. New tokens: `--color-segment-track`, `--color-segment-thumb`, `--shadow-segment`.
+- **Added** `value` / `defaultValue` / `onValueChange` — canonical controlled+uncontrolled API (aligns with Tabs/ToggleGroup).
+- **Added** `fullWidth` prop — segments split the container equally.
+- **Added** 44px minimum touch targets (`touch-target`), keeping dense visual height.
+- **Added** Crisp bounce-free thumb motion (reduced-motion aware) + `motion-safe` press-scale feedback.
+- **Changed** Option `text` widened from `string` to `ReactNode`, and made optional (omit for icon-only segments).
+- **Added** `ariaLabel` per option for icon-only segments; RTL-aware Arrow-key navigation.
+- **Deprecated** `variant="default"` → `variant="soft"`; `selectedId` → `value`; `onSelect` → `onValueChange`. All old names still accepted as aliases; update call sites.
+
 ### v0.38.0
 - **Removed** (BREAKING) deprecated `variant="accent"` alias. Use `variant="solid"`.
 

package/docs/recipes/install-remix.md

@@ -127,10 +127,10 @@ For runtime toggling inside React components, use `useColorMode`:
 import { useColorMode } from "@devalok/shilp-sutra/hooks/use-color-mode";
 
 export function ThemeToggle() {
-  const { mode, toggle } = useColorMode();
+  const { colorMode, toggleColorMode } = useColorMode();
   return (
-    <button onClick={toggle} aria-label="Toggle theme">
-      {mode === "dark" ? "☀" : "☾"}
+    <button onClick={toggleColorMode} aria-label="Toggle theme">
+      {colorMode === "dark" ? "☀" : "☾"}
     </button>
   );
 }

package/docs/recipes/install-vite.md

@@ -121,10 +121,10 @@ Wire the runtime hook from anywhere in the app (e.g., a header button):
 import { useColorMode } from "@devalok/shilp-sutra/hooks/use-color-mode";
 
 export function ThemeToggle() {
-  const { mode, toggle } = useColorMode();
+  const { colorMode, toggleColorMode } = useColorMode();
   return (
-    <button onClick={toggle} aria-label="Toggle theme">
-      {mode === "dark" ? "☀" : "☾"}
+    <button onClick={toggleColorMode} aria-label="Toggle theme">
+      {colorMode === "dark" ? "☀" : "☾"}
     </button>
   );
 }

package/docs/recipes/server-components.md

@@ -151,8 +151,8 @@ Both `<Suspense>` and `<LoadingSkeleton>` are server-safe.
 import { useColorMode } from "@devalok/shilp-sutra/hooks/use-color-mode";
 
 export default function ServerPage() {
-  const { mode } = useColorMode(); // breaks
-  return <div>{mode}</div>;
+  const { colorMode } = useColorMode(); // breaks
+  return <div>{colorMode}</div>;
 }
 ```
 

package/llms.txt

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

@@ -103,6 +103,26 @@ Available as `accent-1` … `accent-12`. Apply via `bg-accent-N`, `text-accent-N
 
 The same 12-step pattern repeats for `error-*`, `success-*`, `warning-*`, `info-*` (subset: 2, 3, 4, 5, 6, 7, 9, 10, 11).
 
+## Component `color` prop — support matrix
+
+The `color` prop accepts a different set per component, because each serves a different job. **The shared intent set — safe to pass to all three from one token — is `accent` · `error` · `success` · `warning` · `info` · `neutral`.**
+
+| color | Button | Card | Badge |
+|---|:---:|:---:|:---:|
+| `accent` | ✅ | ✅ | ✅ |
+| `error` | ✅ | ✅ | ✅ |
+| `success` | ✅ | ✅ | ✅ |
+| `warning` | ✅ | ✅ | ✅ |
+| `info` | ✅ | ✅ | ✅ |
+| `neutral` | ✅ | ✅ | ✅ |
+| `default` | — | ✅ | ✅ |
+| `teal` `amber` `slate` `indigo` `cyan` `orange` `emerald` | — | — | ✅ |
+| `custom` (`--badge-color`) | — | — | ✅ |
+
+- **Button / Card** carry the six **semantic intents** — they communicate *state or emphasis* (a destructive action, a warning panel). That set is aligned across both.
+- **Badge** adds a **category palette** (`teal`, `amber`, `indigo`, …) plus `custom`, because badges label/categorize many peer items where hue is a taxonomy, not a status. Those category hues are intentionally **not** on Button/Card — a "teal primary button" would read as an intent that doesn't exist.
+- To tint a Card + Badge + Button set from one variable, constrain the token to the shared intent set above.
+
 ## Theming — never hardcode
 
 Consumers swap the accent by overriding `--color-accent-1` through `--color-accent-12` in a `:root { }` block placed **after** the kit's CSS import. Dark mode is derived algorithmically — no separate dark overrides needed.

package/make-kit/foundations/dark-mode.md

@@ -18,17 +18,14 @@ Dark tokens are **algorithmically derived** from the OKLCH primitives, not hand-
 import { useColorMode } from '@devalok/shilp-sutra/hooks/use-color-mode'
 
 function ThemeToggle() {
-  const { mode, resolvedMode, setMode } = useColorMode()
-  // mode: 'light' | 'dark' | 'system'
-  // resolvedMode: 'light' | 'dark' (after resolving 'system')
+  const { colorMode, setColorMode, toggleColorMode } = useColorMode()
+  // colorMode: 'light' | 'dark' | 'system'
+  // setColorMode(next): set an explicit mode  ·  toggleColorMode(): flip light↔dark
 
   return (
-    <Button
-      variant="soft"
-      onClick={() => setMode(resolvedMode === 'dark' ? 'light' : 'dark')}
-    >
-      <Icon icon={resolvedMode === 'dark' ? IconSun : IconMoon} />
-      {resolvedMode === 'dark' ? 'Light' : 'Dark'}
+    <Button variant="soft" onClick={toggleColorMode}>
+      <Icon icon={colorMode === 'dark' ? IconSun : IconMoon} />
+      {colorMode === 'dark' ? 'Light' : 'Dark'}
     </Button>
   )
 }

package/make-kit/foundations/icons.md

@@ -17,7 +17,7 @@ import { Icon } from '@devalok/shilp-sutra/ui/icon'
 import { IconHome, IconUser, IconSettings } from '@tabler/icons-react'
 
 <Icon icon={IconHome} />
-<Icon icon={IconUser} size={20} />
+<Icon icon={IconUser} size="lg" />
 <Icon icon={IconSettings} className="text-fg-muted" />
 ```
 
@@ -55,7 +55,7 @@ Don't add `className="h-4 w-4"` on every Icon. Wrap a subtree:
 ```tsx
 import { IconProvider } from '@devalok/shilp-sutra/ui/icon-context'
 
-<IconProvider size={16}>
+<IconProvider size="sm">
   <NavSection>
     <Icon icon={IconHome} />
     <Icon icon={IconUser} />
@@ -64,7 +64,7 @@ import { IconProvider } from '@devalok/shilp-sutra/ui/icon-context'
 </IconProvider>
 ```
 
-Override per-icon with `<Icon icon={...} size={24} />`.
+Override per-icon with `<Icon icon={...} size="xl" />`.
 
 Default sizes by component context:
 

package/make-kit/setup.md

@@ -53,7 +53,7 @@ import { IconProvider } from '@devalok/shilp-sutra/ui/icon-context'
 export default function App({ children }) {
   return (
     <MotionProvider reducedMotion="user">
-      <IconProvider size={16}>
+      <IconProvider size="sm">
         {children}
         <Toaster />
       </IconProvider>
@@ -63,7 +63,7 @@ export default function App({ children }) {
 ```
 
 - `MotionProvider` — required. `reducedMotion="user"` respects OS preference. Without this provider, motion primitives still work but reduced-motion is ignored.
-- `IconProvider` — optional but recommended. Sets default icon size for all `<Icon>` children. Override per-call with `<Icon size={20} />`.
+- `IconProvider` — optional but recommended. Sets default icon size for all `<Icon>` children. Size is a tier (`"xs" | "sm" | "md" | "lg" | "xl" | "2xl"`), not a pixel number. Override per-call with `<Icon size="lg" />`.
 - `Toaster` — only needed if the app calls `toast(...)`. Mount exactly once.
 
 ## Dark mode toggle
@@ -74,9 +74,9 @@ Add the `.dark` class on `<html>` or `<body>` to flip the entire token system to
 import { useColorMode } from '@devalok/shilp-sutra/hooks/use-color-mode'
 
 function ThemeToggle() {
-  const { mode, setMode } = useColorMode() // 'light' | 'dark' | 'system'
+  const { colorMode, setColorMode } = useColorMode() // 'light' | 'dark' | 'system'
   return (
-    <Button onClick={() => setMode(mode === 'dark' ? 'light' : 'dark')}>
+    <Button onClick={() => setColorMode(colorMode === 'dark' ? 'light' : 'dark')}>
       Toggle theme
     </Button>
   )