@devalok/shilp-sutra 0.41.0 → 0.42.0

package/make-kit/components/table.md

@@ -0,0 +1,215 @@
+# Table
+
+Server-safe semantic wrappers around `<table>`. For static / presentational tables.
+
+```tsx
+import {
+  Table,
+  TableHeader,
+  TableBody,
+  TableFooter,
+  TableRow,
+  TableHead,
+  TableCell,
+  TableCaption,
+} from '@devalok/shilp-sutra/ui/table'
+```
+
+## When to use
+
+- Static or small data displays where you control every row and cell.
+- Marketing / pricing comparison tables.
+- Documentation tables (API references, prop tables).
+- Server-rendered tables (RSC) — Table and sub-components are server-safe.
+- Need sorting / filtering / pagination / selection / virtualization? Use `<DataTable>` from `@devalok/shilp-sutra/ui/data-table` — out of scope for this guide.
+
+## Compound shape
+
+```
+Table (<table>)
+  TableCaption (<caption>)        ← optional summary for screen readers
+  TableHeader (<thead>)
+    TableRow (<tr>)
+      TableHead (<th scope="col">)
+  TableBody (<tbody>)
+    TableRow (<tr>)
+      TableCell (<td>)
+  TableFooter (<tfoot>)
+    TableRow
+      TableCell
+```
+
+Each component is a thin semantic wrapper — no props beyond standard HTML attributes plus `className`.
+
+## Examples
+
+**Standard:**
+```tsx
+<Table>
+  <TableHeader>
+    <TableRow>
+      <TableHead>Name</TableHead>
+      <TableHead>Status</TableHead>
+      <TableHead>Owner</TableHead>
+      <TableHead>Updated</TableHead>
+    </TableRow>
+  </TableHeader>
+  <TableBody>
+    {projects.map((p) => (
+      <TableRow key={p.id}>
+        <TableCell>{p.name}</TableCell>
+        <TableCell>
+          <Badge color={p.status === 'active' ? 'success' : 'neutral'}>
+            {p.status}
+          </Badge>
+        </TableCell>
+        <TableCell>
+          <Stack direction="horizontal" gap="ds-02" align="center">
+            <Avatar size="xs" src={p.owner.avatar} alt={p.owner.name} />
+            <Text variant="body-sm">{p.owner.name}</Text>
+          </Stack>
+        </TableCell>
+        <TableCell>
+          <Text variant="body-sm" className="text-fg-muted">
+            {formatDate(p.updatedAt)}
+          </Text>
+        </TableCell>
+      </TableRow>
+    ))}
+  </TableBody>
+</Table>
+```
+
+**With caption + footer:**
+```tsx
+<Table>
+  <TableCaption>Q4 revenue by region.</TableCaption>
+  <TableHeader>
+    <TableRow>
+      <TableHead>Region</TableHead>
+      <TableHead>Revenue</TableHead>
+    </TableRow>
+  </TableHeader>
+  <TableBody>
+    <TableRow><TableCell>NA</TableCell><TableCell>$1.2M</TableCell></TableRow>
+    <TableRow><TableCell>EU</TableCell><TableCell>$0.8M</TableCell></TableRow>
+    <TableRow><TableCell>APAC</TableCell><TableCell>$0.4M</TableCell></TableRow>
+  </TableBody>
+  <TableFooter>
+    <TableRow>
+      <TableCell><Text variant="label-sm">Total</Text></TableCell>
+      <TableCell><Text variant="label-sm">$2.4M</Text></TableCell>
+    </TableRow>
+  </TableFooter>
+</Table>
+```
+
+**Row actions (IconButton in last cell):**
+```tsx
+<Table>
+  <TableHeader>
+    <TableRow>
+      <TableHead>File</TableHead>
+      <TableHead>Size</TableHead>
+      <TableHead className="w-12" />
+    </TableRow>
+  </TableHeader>
+  <TableBody>
+    {files.map((f) => (
+      <TableRow key={f.id}>
+        <TableCell>{f.name}</TableCell>
+        <TableCell>{formatFileSize(f.size)}</TableCell>
+        <TableCell>
+          <DropdownMenu>
+            <DropdownMenuTrigger asChild>
+              <IconButton icon={<Icon icon={IconDots} />} variant="ghost" size="sm" aria-label="Actions" />
+            </DropdownMenuTrigger>
+            <DropdownMenuContent>
+              <DropdownMenuItem onSelect={() => download(f)}>Download</DropdownMenuItem>
+              <DropdownMenuSeparator />
+              <DropdownMenuItem onSelect={() => remove(f)}>Delete</DropdownMenuItem>
+            </DropdownMenuContent>
+          </DropdownMenu>
+        </TableCell>
+      </TableRow>
+    ))}
+  </TableBody>
+</Table>
+```
+
+**Inside a Card:**
+```tsx
+<Card>
+  <CardHeader>
+    <CardTitle>Team members</CardTitle>
+  </CardHeader>
+  <CardContent>
+    <Table>
+      <TableHeader>
+        <TableRow>
+          <TableHead>Member</TableHead>
+          <TableHead>Role</TableHead>
+        </TableRow>
+      </TableHeader>
+      <TableBody>
+        {members.map((m) => (
+          <TableRow key={m.id}>
+            <TableCell>{m.name}</TableCell>
+            <TableCell><Badge color="neutral">{m.role}</Badge></TableCell>
+          </TableRow>
+        ))}
+      </TableBody>
+    </Table>
+  </CardContent>
+</Card>
+```
+
+When inside a `<Card>`, the Table's surrounding padding comes from `CardContent`. Don't add extra padding on the Table.
+
+**Server-rendered table (RSC):**
+```tsx
+// app/projects/page.tsx — no 'use client'
+export default async function ProjectsPage() {
+  const projects = await db.projects.findMany()
+  return (
+    <Table>
+      <TableHeader>
+        <TableRow>
+          <TableHead>Name</TableHead>
+          <TableHead>Status</TableHead>
+        </TableRow>
+      </TableHeader>
+      <TableBody>
+        {projects.map((p) => (
+          <TableRow key={p.id}>
+            <TableCell>{p.name}</TableCell>
+            <TableCell><Badge>{p.status}</Badge></TableCell>
+          </TableRow>
+        ))}
+      </TableBody>
+    </Table>
+  )
+}
+```
+
+Table + Badge (server-safe via Badge.Group context — verify per use) + Avatar all render in RSC trees. Skip client components.
+
+## Composability
+
+- **Server-safe:** Table and its sub-components are pure HTML semantic wrappers. No state, no context. Use in RSC trees without `'use client'`.
+- **TableHead scope:** Headers automatically get `scope="col"` for screen-reader navigation. Don't override it.
+- **Composes with primitives:** Drop `<Badge>`, `<Avatar>`, `<IconButton>`, `<StatusDot>` inside cells. Check each component's server-safety if you need RSC compatibility.
+- **TableCaption:** Renders as HTML `<caption>` — screen readers announce it before content. Use it for any non-trivial table.
+
+See `foundations/typography.md` for the body / label variants inside cells, `foundations/surfaces.md` for table-in-card surface guidance.
+
+## Rules
+
+- For anything with sorting / filtering / pagination / selection / virtualization, use `<DataTable>` from `/ui/data-table`. Don't rebuild that machinery on bare Table.
+- Always wrap header cells in `<TableHead>` (renders `<th>`). Don't use `<TableCell>` (`<td>`) in headers — breaks screen-reader column scope.
+- Use `<TableCaption>` for any table that's not self-evident. Renders the HTML `<caption>` which screen readers announce.
+- Inside Card, drop the Table directly in `<CardContent>` — don't add wrapper divs that fight the card's padding cascade.
+- For wide tables on mobile, wrap in an `overflow-x-auto` container. Don't try to make a Table responsive via column stacking — switch to a card list on small viewports.
+- Don't style cell text with raw Tailwind palette utilities. Use `text-fg-muted` from `foundations/color.md`.
+- Compose with Badge for status, Avatar for users, IconButton for row actions. Don't invent new primitives per table.
+- Keep TableCell content single-line where possible — multi-line cells make scanning hard. Use `<Stack>` only when each row genuinely needs two lines.

package/make-kit/components/tabs.md

@@ -0,0 +1,162 @@
+# Tabs
+
+Switch between sibling views inside a single region. Not for top-level navigation.
+
+```tsx
+import { Tabs, TabsList, TabsTrigger, TabsContent } from '@devalok/shilp-sutra/ui/tabs'
+```
+
+## When to use
+
+- Sub-sections of a single page / panel that share context (Overview / Activity / Settings on a project).
+- Filtered views over the same dataset (All / Mine / Archived).
+- Need URL-driven routes per tab? Wire `value` / `onValueChange` to router state.
+- Top-level app navigation? Use `<Sidebar>` / `<TopBar>`, not Tabs.
+- Multi-step flows? Use `<Stepper>` or a wizard pattern.
+
+## Compound shape
+
+```
+Tabs (root — value, defaultValue, onValueChange)
+  TabsList (variant, size, orientation)
+    TabsTrigger (value)         ← inherits variant/size/orientation from TabsList
+  TabsContent (value)           ← rendered inline (not portalled)
+```
+
+## TabsList props
+
+| Prop | Type | Notes |
+|---|---|---|
+| `variant` | `'line'\|'contained'` | Default `line`. |
+| `size` | `'sm'\|'md'\|'lg'` | Default `md`. |
+| `orientation` | `'horizontal'\|'vertical'` | Default `horizontal`. Vertical also changes keyboard nav to ArrowUp/Down. |
+| `color` | `'accent'\|'neutral'` | Affects the line-variant active indicator. |
+
+## Variants
+
+| Variant | When |
+|---|---|
+| `line` (default) | Underline active indicator. Most common — pairs with section headings. |
+| `contained` | Pill background per active trigger. Use inside cards or compact toolbars. |
+
+## Root state props (Radix passthrough)
+
+| Prop | Type | Notes |
+|---|---|---|
+| `value` | `string` | Controlled active tab. |
+| `defaultValue` | `string` | Uncontrolled initial tab. |
+| `onValueChange` | `(value: string) => void` | Fires on tab change. |
+
+## TabsTrigger / TabsContent
+
+Both require a `value: string` prop. The values must match between a trigger and its content.
+
+`TabsTrigger` reads `variant` / `size` / `orientation` from `TabsList` via context. Override per-trigger if needed, but normally don't.
+
+## Examples
+
+**Standard line tabs:**
+```tsx
+<Tabs defaultValue="overview">
+  <TabsList>
+    <TabsTrigger value="overview">Overview</TabsTrigger>
+    <TabsTrigger value="activity">Activity</TabsTrigger>
+    <TabsTrigger value="settings">Settings</TabsTrigger>
+  </TabsList>
+  <TabsContent value="overview">
+    <ProjectOverview />
+  </TabsContent>
+  <TabsContent value="activity">
+    <ActivityFeed />
+  </TabsContent>
+  <TabsContent value="settings">
+    <ProjectSettings />
+  </TabsContent>
+</Tabs>
+```
+
+**Contained variant inside a card:**
+```tsx
+<Card>
+  <CardContent>
+    <Tabs defaultValue="day">
+      <TabsList variant="contained" size="sm">
+        <TabsTrigger value="day">Day</TabsTrigger>
+        <TabsTrigger value="week">Week</TabsTrigger>
+        <TabsTrigger value="month">Month</TabsTrigger>
+      </TabsList>
+      <TabsContent value="day"><Chart range="day" /></TabsContent>
+      <TabsContent value="week"><Chart range="week" /></TabsContent>
+      <TabsContent value="month"><Chart range="month" /></TabsContent>
+    </Tabs>
+  </CardContent>
+</Card>
+```
+
+**Vertical orientation (settings-style):**
+```tsx
+<Tabs defaultValue="account" orientation="vertical">
+  <Stack direction="horizontal" gap="ds-07" align="start">
+    <TabsList orientation="vertical">
+      <TabsTrigger value="account">Account</TabsTrigger>
+      <TabsTrigger value="billing">Billing</TabsTrigger>
+      <TabsTrigger value="notifications">Notifications</TabsTrigger>
+    </TabsList>
+    <div className="flex-1">
+      <TabsContent value="account"><AccountForm /></TabsContent>
+      <TabsContent value="billing"><BillingForm /></TabsContent>
+      <TabsContent value="notifications"><NotificationsForm /></TabsContent>
+    </div>
+  </Stack>
+</Tabs>
+```
+
+**With icons + badges:**
+```tsx
+<Tabs defaultValue="inbox">
+  <TabsList>
+    <TabsTrigger value="inbox">
+      <Icon icon={IconInbox} /> Inbox
+      <Badge size="xs" color="accent">12</Badge>
+    </TabsTrigger>
+    <TabsTrigger value="sent">
+      <Icon icon={IconSend} /> Sent
+    </TabsTrigger>
+  </TabsList>
+  <TabsContent value="inbox"><InboxList /></TabsContent>
+  <TabsContent value="sent"><SentList /></TabsContent>
+</Tabs>
+```
+
+**Router-driven (Next.js App Router):**
+```tsx
+'use client'
+const router = useRouter()
+const pathname = usePathname()
+const tab = pathname.split('/').pop() ?? 'overview'
+
+<Tabs value={tab} onValueChange={(v) => router.push(`/projects/${id}/${v}`)}>
+  <TabsList>
+    <TabsTrigger value="overview">Overview</TabsTrigger>
+    <TabsTrigger value="activity">Activity</TabsTrigger>
+  </TabsList>
+</Tabs>
+```
+
+## Composability
+
+- **Context cascade:** `TabsList` propagates `variant` / `size` / `orientation` to every child `TabsTrigger`. Don't repeat those props on each trigger.
+- **Inline content:** `TabsContent` renders inline (not portalled). Container-scoped queries in tests work.
+- **Keyboard:** Roving tabindex via Radix — ArrowLeft/Right (horizontal) or ArrowUp/Down (vertical). Home / End jump to first / last. Don't re-implement.
+
+See `foundations/spacing.md` for the gap between TabsList and TabsContent, `foundations/icons.md` for icon sizing inside triggers.
+
+## Rules
+
+- Put `variant` / `size` / `orientation` on `TabsList`, NOT on `Tabs` root or `TabsTrigger`.
+- Every `TabsTrigger` and `TabsContent` needs a `value` — the values must match.
+- For top-level app navigation use Sidebar / TopBar, not Tabs.
+- Don't stack two Tabs inside the same region — pick one. Nested tabs confuse keyboard nav and section structure.
+- For router-bound tabs, keep `value` controlled — don't mix `defaultValue` with router-driven URLs.
+- For 5+ tabs that overflow on mobile, consider a Select dropdown on small viewports or wrap in a horizontally scrollable container.
+- Icons in TabsTrigger don't auto-size via IconProvider — set explicit `<Icon icon={...} size="sm" />` when the trigger feels off.

package/make-kit/components/text.md

@@ -0,0 +1,139 @@
+# Text
+
+Typography primitive. Use instead of raw `<h1>`–`<h6>`, `<p>`, `<span>` for any visible text.
+
+```tsx
+import { Text } from '@devalok/shilp-sutra/ui/text'
+```
+
+## When to use
+
+- Any visible text: headings, body copy, captions, section labels, inline microcopy.
+- Inline code spans inside body text? Pair with `<Code>`.
+- Polymorphic — `<Text as="span">`, `<Text as="div">`, etc. — to demote semantics while keeping visual weight.
+- Server-safe — renders in RSC trees without `'use client'`.
+
+## Variants
+
+| Variant | Default element | Use |
+|---|---|---|
+| `heading-2xl` | `h1` | Page title / hero. |
+| `heading-xl` | `h2` | Section title. |
+| `heading-lg` | `h3` | Sub-section title. |
+| `heading-md` | `h4` | Card title (used by `<CardTitle>`). |
+| `heading-sm` | `h5` | Compact sub-heading. |
+| `heading-xs` | `h6` | Smallest heading. |
+| `body-lg` | `p` | Lead paragraphs. |
+| `body-md` (default) | `p` | Standard body. |
+| `body-sm` | `p` | Dense body — captions inside cards, table cells. |
+| `body-xs` | `p` | Footnotes, fine print. |
+| `label-lg` / `md` / `sm` / `xs` | `span` | UPPERCASE section labels, eyebrows. |
+| `label-plain-lg` / `md` / `sm` / `xs` | `span` | Mixed-case labels (form labels, inline UI text). |
+| `caption` | `span` | Image / chart captions. |
+| `overline` | `span` | UPPERCASE marketing eyebrow. |
+| `code` | `code` | Inline monospace code. |
+
+`label-*` and `overline` variants are automatically uppercase. `label-plain-*` keeps mixed case.
+
+## Props
+
+| Prop | Type | Notes |
+|---|---|---|
+| `variant` | See variants table | Default `body-md`. |
+| `as` | `ElementType` | Override the auto-selected HTML element. |
+| `className` | `string` | For color / alignment overrides. Use semantic tokens only. |
+
+Plus all standard HTML attributes for whatever element it renders.
+
+## Examples
+
+**Page heading + body:**
+```tsx
+<Stack gap="ds-04">
+  <Text variant="heading-2xl">Projects</Text>
+  <Text variant="body-md" className="text-fg-muted">
+    A workspace for everything you ship.
+  </Text>
+</Stack>
+```
+
+**Section label + heading pair:**
+```tsx
+<Stack gap="ds-02">
+  <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>
+```
+
+**Visual demotion via `as`:**
+```tsx
+{/* h2-sized heading rendered as a div — useful when the element already has a heading ancestor */}
+<Card>
+  <CardHeader>
+    <CardTitle>Activity</CardTitle> {/* h4 */}
+    <Text variant="heading-xl" as="div">Weekly summary</Text>
+  </CardHeader>
+</Card>
+```
+
+**Inline span inside a paragraph:**
+```tsx
+<Text>
+  Press <Text as="kbd" variant="code">⌘ K</Text> to open the command palette.
+</Text>
+```
+
+**Caption under an image:**
+```tsx
+<Stack gap="ds-02">
+  <img src={chart} alt="" />
+  <Text variant="caption" className="text-fg-muted">
+    Figure 1. Active users by region.
+  </Text>
+</Stack>
+```
+
+**Form field label (label-plain variant):**
+```tsx
+<Stack gap="ds-02">
+  <Text variant="label-plain-sm" as="label" htmlFor="email">Email</Text>
+  <Input id="email" type="email" />
+</Stack>
+```
+
+Use `<Label>` for form fields when wired with FormField — `Text` is for non-form labels.
+
+**Body with inline code:**
+```tsx
+<Text>
+  Call <Code>onSubmit</Code> with the form values, or pass <Code>asChild</Code> to merge with a child element.
+</Text>
+```
+
+**Truncated single line:**
+```tsx
+<Text variant="body-sm" className="truncate max-w-[200px]">
+  {longUserName}
+</Text>
+```
+
+## Composability
+
+- **Server-safe.** No client hooks. Use freely in RSC trees.
+- **No context cascade** — pure typography primitive. Variants don't propagate through children.
+- **Underpins other components.** `<CardTitle>`, `<Alert>`'s title, `<PageHeader>`, `<EmptyState>`, `<SectionHeader>` all render Text internally with specific variants. Don't wrap another Text inside them.
+- **`as` overrides element only, not variant.** Visual weight stays. Use to demote semantics when you have a heading ancestor.
+
+See `foundations/typography.md` for the full type scale, line-height tokens, font stack.
+
+## Rules
+
+- Use Text for every visible text element. Don't write raw `<h1>` / `<p>` / `<span>` with manual classes.
+- Pick variant by semantic intent, not visual size. `heading-xl` is an `<h2>` — use it for section headings, not because you want big text in a body paragraph (use `as="div"` for that).
+- Don't wrap a `<Text>` inside `<CardTitle>` / `<Alert>` title — they already render Text internally.
+- `label-*` and `overline` variants are automatically uppercase. Don't add `uppercase` class.
+- For form labels paired with controls, use `<Label htmlFor>` from `/ui/label`. `Text variant="label-plain-*"` is for non-form labels.
+- Color overrides go through semantic tokens (`text-fg-muted`, `text-fg`, `text-fg-subtle`). Never raw Tailwind palette utilities.
+- Don't use Text inside another semantic heading — it produces nested headings that break screen-reader navigation.
+- For inline code, use `<Code>`. `Text variant="code"` works but Code is the dedicated primitive.