@devalok/shilp-sutra 0.41.0 → 0.42.0

package/make-kit/components/popover.md

@@ -0,0 +1,201 @@
+# Popover
+
+Click-triggered floating panel for interactive content anchored to a trigger.
+
+```tsx
+import {
+  Popover,
+  PopoverTrigger,
+  PopoverContent,
+  PopoverAnchor,
+} from '@devalok/shilp-sutra/ui/popover'
+```
+
+## When to use
+
+- Interactive panel anchored to a button: filter form, date picker, color picker, share popover.
+- A list of actions? Use `<DropdownMenu>` — keyboard model differs (arrow nav vs. Tab nav).
+- Inert hover label (tooltip)? Use `<Tooltip>`.
+- Rich hover preview (user card, link preview)? Use `<HoverCard>`.
+- Critical full-attention interaction? Use `<Dialog>`.
+
+On mobile, Popover auto-promotes to a bottom drawer when it would overflow the viewport — don't rebuild this manually.
+
+## Compound shape
+
+```
+Popover (root — open, onOpenChange, defaultOpen, modal)
+  PopoverTrigger          ← asChild around your button
+  PopoverAnchor           ← optional, decouples trigger from positioning origin
+  PopoverContent          ← portalled, accepts side/align/sideOffset
+```
+
+## Root state props (Radix passthrough)
+
+| Prop | Type | Notes |
+|---|---|---|
+| `open` | `boolean` | Controlled. |
+| `onOpenChange` | `(open: boolean) => void` | |
+| `defaultOpen` | `boolean` | Uncontrolled. |
+| `modal` | `boolean` | Default `false`. Set `true` for backdrop + focus trap (rare — usually use Dialog). |
+
+## PopoverContent positioning
+
+| Prop | Type | Notes |
+|---|---|---|
+| `side` | `'top'\|'right'\|'bottom'\|'left'` | Preferred side. Floats to opposite side if it would overflow. |
+| `align` | `'start'\|'center'\|'end'` | Alignment relative to trigger. |
+| `sideOffset` | `number` (px) | Gap between trigger and content. |
+| `collisionPadding` | `number \| { top, right, bottom, left }` | Distance from viewport edges before flipping. |
+
+All Floating-UI positioning options pass through via Radix.
+
+## Examples
+
+**Filter form:**
+```tsx
+<Popover>
+  <PopoverTrigger asChild>
+    <Button variant="soft" startIcon={IconFilter}>Filters</Button>
+  </PopoverTrigger>
+  <PopoverContent align="start">
+    <Stack gap="ds-04">
+      <FormField>
+        <Label htmlFor="status">Status</Label>
+        <Select value={status} onValueChange={setStatus}>
+          <SelectTrigger id="status">
+            <SelectValue />
+          </SelectTrigger>
+          <SelectContent>
+            <SelectItem value="all">All</SelectItem>
+            <SelectItem value="active">Active</SelectItem>
+            <SelectItem value="archived">Archived</SelectItem>
+          </SelectContent>
+        </Select>
+      </FormField>
+      <Stack direction="horizontal" gap="ds-03" justify="end">
+        <Button variant="ghost" size="sm" onClick={reset}>Clear</Button>
+        <Button size="sm" onClick={apply}>Apply</Button>
+      </Stack>
+    </Stack>
+  </PopoverContent>
+</Popover>
+```
+
+**Date picker:**
+```tsx
+<Popover>
+  <PopoverTrigger asChild>
+    <Button variant="soft" startIcon={IconCalendar}>
+      {date ? formatDate(date) : 'Pick a date'}
+    </Button>
+  </PopoverTrigger>
+  <PopoverContent>
+    <Calendar value={date} onChange={(d) => { setDate(d); setOpen(false) }} />
+  </PopoverContent>
+</Popover>
+```
+
+**Share popover with copy link:**
+```tsx
+<Popover>
+  <PopoverTrigger asChild>
+    <Button variant="soft" startIcon={IconShare}>Share</Button>
+  </PopoverTrigger>
+  <PopoverContent side="bottom" align="end">
+    <Stack gap="ds-03">
+      <Text variant="label-sm">Share link</Text>
+      <Stack direction="horizontal" gap="ds-02">
+        <Input value={shareUrl} readOnly className="flex-1" />
+        <IconButton
+          icon={<Icon icon={copied ? IconCheck : IconCopy} />}
+          variant="soft"
+          aria-label="Copy link"
+          onClick={() => { navigator.clipboard.writeText(shareUrl); setCopied(true) }}
+        />
+      </Stack>
+    </Stack>
+  </PopoverContent>
+</Popover>
+```
+
+**Decoupled anchor (trigger ≠ positioning origin):**
+```tsx
+<Popover>
+  <PopoverAnchor>
+    <Card>
+      <CardHeader>
+        <CardTitle>Project</CardTitle>
+        <PopoverTrigger asChild>
+          <IconButton icon={<Icon icon={IconInfo} />} variant="ghost" size="sm" aria-label="About" />
+        </PopoverTrigger>
+      </CardHeader>
+    </Card>
+  </PopoverAnchor>
+  <PopoverContent side="top">
+    Popover positions relative to the whole Card, not the small info button.
+  </PopoverContent>
+</Popover>
+```
+
+**Inside a Dialog (nested overlays work correctly):**
+```tsx
+<Dialog>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>Schedule meeting</DialogTitle>
+    </DialogHeader>
+    <Popover>
+      <PopoverTrigger asChild>
+        <Button variant="soft">Pick a time</Button>
+      </PopoverTrigger>
+      <PopoverContent>
+        <TimePicker value={time} onChange={setTime} />
+      </PopoverContent>
+    </Popover>
+  </DialogContent>
+</Dialog>
+```
+
+Popover uses `z-popover` (1400), above `z-dialog`. Nesting works without z-index fights.
+
+**Controlled with custom close behavior:**
+```tsx
+const [open, setOpen] = useState(false)
+
+<Popover open={open} onOpenChange={setOpen}>
+  <PopoverTrigger asChild>
+    <Button>Open</Button>
+  </PopoverTrigger>
+  <PopoverContent
+    onInteractOutside={(e) => {
+      if (hasUnsavedChanges) {
+        e.preventDefault()
+        confirmClose().then((ok) => ok && setOpen(false))
+      }
+    }}
+  >
+    <UnsavedForm />
+  </PopoverContent>
+</Popover>
+```
+
+## Composability
+
+- **Built on Radix Popover** — every standard Radix prop passes through.
+- **Portal rendering:** PopoverContent portals to body. CSS `overflow: hidden` / `transform` on ancestors don't clip it.
+- **z-popover (1400):** Above Dialog (`z-dialog`). Nested popovers inside dialogs stack correctly.
+- **PopoverAnchor:** Decouples the visual anchor from the interactive trigger. Useful when the trigger is small (icon button) but the popover should position relative to a larger surrounding element.
+
+See `foundations/surfaces.md` for overlay surface, `foundations/motion.md` for the spring open animation, `foundations/spacing.md` for internal popover padding.
+
+## Rules
+
+- Use Popover for interactive content (forms, pickers). Use DropdownMenu for action lists — different keyboard model.
+- `<PopoverTrigger asChild>` around any focusable element — usually a Button or IconButton.
+- Set `modal={true}` only when the popover blocks interaction with the rest of the page. Default `false` is correct for filters / pickers.
+- Set explicit `side` + `align` for predictable positioning. Defaults bottom-center, but designs often want `align="end"` for right-anchored triggers.
+- Don't use Popover for tooltips — Tooltip is for inert hover labels. Popover requires explicit click.
+- Don't nest Popover inside Popover. Use a single Popover with stepped content, or close the first before opening the second.
+- For complex form flows that need full attention, switch to Dialog. Popovers shouldn't host multi-step wizards.
+- The internal padding inside `PopoverContent` is preset — don't add wrapper divs with extra padding. Use `<Stack gap>` to space content.

package/make-kit/components/select.md

@@ -0,0 +1,148 @@
+# Select
+
+Single-choice picker from a short fixed list. Use instead of `<select>`.
+
+```tsx
+import {
+  Select,
+  SelectTrigger,
+  SelectValue,
+  SelectContent,
+  SelectGroup,
+  SelectLabel,
+  SelectItem,
+  SelectSeparator,
+} from '@devalok/shilp-sutra/ui/select'
+```
+
+## When to use
+
+- Fixed list under ~15 items, no search needed (status, priority, role).
+- Need typeahead / search across many options? Use `<Combobox>`.
+- Free-text with suggestions? Use `<Autocomplete>`.
+- Multi-select? Use `<MultiSelect>` or `<Combobox multiple>`.
+- Yes/no toggle? Use `<Switch>` or `<RadioGroup>` with 2 options.
+
+## Compound shape
+
+```
+Select (root — value, onValueChange, defaultValue)
+  SelectTrigger              ← variant / color / size go HERE
+    SelectValue (placeholder)
+  SelectContent
+    SelectGroup (optional)
+      SelectLabel            ← non-interactive section header
+      SelectItem (value)     ← REQUIRED value, unique
+    SelectSeparator
+```
+
+## SelectTrigger props
+
+| Prop | Type | Notes |
+|---|---|---|
+| `variant` | `'default'\|'outline'\|'ghost'` | Default `default`. |
+| `color` | `'default'\|'error'\|'success'\|'warning'` | Default `default`. `error` sets `aria-invalid`. |
+| `size` | `'xs'\|'sm'\|'md'\|'lg'` | Default `md`. |
+
+Styling lives on the **Trigger**, not on `Select` root. Setting `<Select size="lg">` does nothing — TypeScript won't catch it.
+
+## Root state props (Radix passthrough)
+
+| Prop | Type | Notes |
+|---|---|---|
+| `value` | `string` | Controlled value. |
+| `onValueChange` | `(value: string) => void` | Fires on select. |
+| `defaultValue` | `string` | Uncontrolled. |
+| `open` | `boolean` | Controlled open state. |
+| `onOpenChange` | `(open: boolean) => void` | |
+
+## Examples
+
+**Standard:**
+```tsx
+<Select onValueChange={setStatus}>
+  <SelectTrigger>
+    <SelectValue placeholder="Status" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="todo">To do</SelectItem>
+    <SelectItem value="doing">In progress</SelectItem>
+    <SelectItem value="done">Done</SelectItem>
+  </SelectContent>
+</Select>
+```
+
+**With grouped items and a separator:**
+```tsx
+<Select value={assignee} onValueChange={setAssignee}>
+  <SelectTrigger size="sm">
+    <SelectValue placeholder="Assignee" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectGroup>
+      <SelectLabel>Team</SelectLabel>
+      <SelectItem value="alice">Alice</SelectItem>
+      <SelectItem value="bob">Bob</SelectItem>
+    </SelectGroup>
+    <SelectSeparator />
+    <SelectGroup>
+      <SelectLabel>External</SelectLabel>
+      <SelectItem value="contractor-1">Contractor 1</SelectItem>
+    </SelectGroup>
+  </SelectContent>
+</Select>
+```
+
+**Inside a FormField (manual error wiring):**
+```tsx
+<FormField state={errors.role ? 'error' : 'helper'}>
+  <Label htmlFor="role">Role</Label>
+  <Select value={role} onValueChange={setRole}>
+    <SelectTrigger id="role" color={errors.role ? 'error' : 'default'}>
+      <SelectValue placeholder="Choose a role" />
+    </SelectTrigger>
+    <SelectContent>
+      <SelectItem value="admin">Admin</SelectItem>
+      <SelectItem value="member">Member</SelectItem>
+      <SelectItem value="viewer">Viewer</SelectItem>
+    </SelectContent>
+  </Select>
+  {errors.role && <FormHelperText>{errors.role}</FormHelperText>}
+</FormField>
+```
+
+Select doesn't auto-consume FormField context (unlike Input / Textarea). Set `color="error"` on `SelectTrigger` manually.
+
+**Ghost variant in a toolbar:**
+```tsx
+<Select value={sort} onValueChange={setSort} defaultValue="recent">
+  <SelectTrigger variant="ghost" size="sm">
+    <SelectValue />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="recent">Most recent</SelectItem>
+    <SelectItem value="oldest">Oldest</SelectItem>
+    <SelectItem value="az">A → Z</SelectItem>
+  </SelectContent>
+</Select>
+```
+
+## Composability
+
+- **Radix Select** underneath — `value` / `onValueChange` / `defaultValue` / `open` / `onOpenChange` standard state.
+- **Portal + z-popover (1400):** SelectContent portals to body, stacks above Dialog / Sheet / other overlays.
+- **SelectItem requires a unique `value`** — duplicates produce undefined selection behavior.
+- **FormField integration is manual** — wire `color="error"` on SelectTrigger from your validation state.
+
+See `foundations/surfaces.md` for the overlay surface, `foundations/color.md` for state colors.
+
+## Rules
+
+- Put `variant` / `color` / `size` on `SelectTrigger`, NOT on `Select` root.
+- Every `SelectItem` needs a unique `value` prop.
+- For lists over ~15 items or when users will scan for a term, switch to `<Combobox>` — Select has no typeahead.
+- Set `color="error"` on `SelectTrigger` for validation failures — Select doesn't auto-consume FormField state.
+- Don't use Select for multi-value capture — use `<MultiSelect>` or `<Combobox multiple>`.
+- Always render `<SelectValue placeholder="..." />` — without it, the trigger renders empty before any selection.
+- Group related items with `<SelectGroup>` + `<SelectLabel>` — flat lists over 8 items get hard to scan.
+- Don't customize the dropdown surface — overlays use `surface-1` per `foundations/surfaces.md`.

package/make-kit/components/stack.md

@@ -0,0 +1,165 @@
+# Stack
+
+Flexbox layout primitive. Use instead of `<div className="flex flex-col gap-4">` everywhere.
+
+```tsx
+import { Stack } from '@devalok/shilp-sutra/ui/stack'
+```
+
+## When to use
+
+- Stacking elements vertically or horizontally with consistent gap.
+- Any time you'd write `flex` + `gap-*` + `items-*` + `justify-*` on a div.
+- Centering + width-capping a page section? Use `<Container>`, then a `<Stack>` inside.
+- Grid layouts (rows × columns)? Use a Tailwind `grid` div directly — Stack is for one-axis layouts.
+
+Server-safe — no hydration, no context.
+
+## Props
+
+| Prop | Type | Notes |
+|---|---|---|
+| `direction` | `'vertical'\|'horizontal'\|'row'\|'column'` | Default `vertical`. `row` = `horizontal`, `column` = `vertical` (aliases). |
+| `gap` | `'ds-01'..'ds-13'` \| `0..13` | Design-system spacing token. Numbers map 1:1 to `ds-0N`. |
+| `align` | `'start'\|'center'\|'end'\|'stretch'\|'baseline'` | Cross-axis alignment (`align-items`). |
+| `justify` | `'start'\|'center'\|'end'\|'between'\|'around'\|'evenly'` | Main-axis alignment (`justify-content`). |
+| `wrap` | `boolean` | Enables `flex-wrap`. |
+| `as` | `ElementType` | Default `'div'`. Polymorphic. |
+| `className` | `string` | For overrides — don't reach for raw `flex-*` utilities. |
+
+## Gap cadence
+
+Default to the 3-tier cadence from `foundations/spacing.md`:
+
+| Gap | Use |
+|---|---|
+| `ds-03` (8 px) | Related items inside a group (icon + label, button row). |
+| `ds-05` (16 px) | Grouped sections within a card / form. |
+| `ds-07` (32 px) | Page sections / major regions. |
+
+Don't reach for every adjacent token. If `ds-04` "feels right," it usually means a parent's padding or the section relationship needs a rethink.
+
+## Examples
+
+**Vertical form layout:**
+```tsx
+<Stack gap="ds-05">
+  <FormField>
+    <Label htmlFor="name">Name</Label>
+    <Input id="name" />
+  </FormField>
+  <FormField>
+    <Label htmlFor="email">Email</Label>
+    <Input id="email" />
+  </FormField>
+</Stack>
+```
+
+**Horizontal toolbar:**
+```tsx
+<Stack direction="horizontal" gap="ds-03" align="center">
+  <Button variant="soft" startIcon={IconFilter}>Filter</Button>
+  <Button variant="soft" startIcon={IconSortDescending}>Sort</Button>
+  <Separator orientation="vertical" className="h-6" />
+  <Button variant="solid" startIcon={IconPlus}>New</Button>
+</Stack>
+```
+
+**Avatar + label cluster:**
+```tsx
+<Stack direction="horizontal" gap="ds-03" align="center">
+  <Avatar size="sm" src={user.avatar} alt={user.name} />
+  <Stack gap="ds-01">
+    <Text variant="label-plain-sm">{user.name}</Text>
+    <Text variant="body-xs" className="text-fg-muted">{user.role}</Text>
+  </Stack>
+</Stack>
+```
+
+**Page-section spacing:**
+```tsx
+<Container>
+  <Stack gap="ds-07">
+    <PageHeader title="Projects" description="A workspace for everything you ship." />
+    <Stack gap="ds-05">
+      <SectionHeader title="Active" />
+      <ProjectGrid projects={active} />
+    </Stack>
+    <Stack gap="ds-05">
+      <SectionHeader title="Archived" />
+      <ProjectGrid projects={archived} />
+    </Stack>
+  </Stack>
+</Container>
+```
+
+**Wrap for tag cluster:**
+```tsx
+<Stack direction="horizontal" gap="ds-02" wrap>
+  {tags.map((tag) => <Badge key={tag} color="neutral">{tag}</Badge>)}
+</Stack>
+```
+
+For tag clusters specifically, prefer `<Badge.Group>` — it handles overflow with `+N` automatically.
+
+**Justify-between (label + action):**
+```tsx
+<Stack direction="horizontal" gap="ds-04" align="center" justify="between">
+  <Text variant="heading-md">Team</Text>
+  <Button variant="soft" startIcon={IconPlus} size="sm">Invite</Button>
+</Stack>
+```
+
+**Polymorphic — semantic list:**
+```tsx
+<Stack as="ul" gap="ds-03">
+  {items.map((item) => (
+    <Stack as="li" key={item.id} direction="horizontal" gap="ds-03" align="center">
+      <Icon icon={IconCheck} />
+      <Text variant="body-sm">{item.label}</Text>
+    </Stack>
+  ))}
+</Stack>
+```
+
+**Numeric gap shortcut:**
+```tsx
+<Stack gap={5}>  {/* same as gap="ds-05" */}
+  …
+</Stack>
+```
+
+**Inside Card (no extra padding):**
+```tsx
+<Card>
+  <CardContent>
+    <Stack gap="ds-04">
+      <Text variant="label-sm" className="text-fg-muted">REVENUE</Text>
+      <Text variant="heading-xl">$2.4M</Text>
+      <Text variant="body-sm" className="text-fg-muted">+18% YoY</Text>
+    </Stack>
+  </CardContent>
+</Card>
+```
+
+CardContent already supplies the outer padding. Stack just spaces the children.
+
+## Composability
+
+- **Server-safe.** Nothing to hydrate. Use in RSC trees.
+- **Polymorphic via `as`** — `<Stack as="ul">`, `<Stack as="section">`, `<Stack as="nav">`. Inherits flex behavior on the chosen element.
+- **Compose with Container:** `<Container><Stack>...</Stack></Container>`. Container centers + caps width; Stack arranges children.
+- **No responsive direction prop** — for `flex-col md:flex-row` use a plain div with Tailwind utilities directly, or render two Stacks with display toggling.
+
+See `foundations/spacing.md` for the gap cadence, `foundations/surfaces.md` for layout-on-surfaces context.
+
+## Rules
+
+- Default to the `ds-03 / ds-05 / ds-07` cadence. Reach for other tokens only with a deliberate reason.
+- Use Stack everywhere you'd write `flex` + `gap` on a div. Don't mix Stack and raw flex utilities in the same tree.
+- For grid (2D) layouts, use a plain `grid` div. Stack is one-axis only.
+- For responsive direction changes, drop to a plain div with Tailwind responsive flex utilities. Stack doesn't have a responsive direction prop.
+- Don't add padding to a Stack — wrap it in a Container or Card. Padding lives on containers, not layout primitives.
+- For tag clusters with potential overflow, use `<Badge.Group>` instead of `<Stack wrap>` — it handles `+N` collapsing.
+- Numeric `gap={4}` and string `gap="ds-04"` are equivalent. Pick a convention per file and stick with it.
+- `direction="row"` and `direction="column"` are aliases for `horizontal` / `vertical`. Pick one naming pair per codebase.