@devalok/shilp-sutra 0.44.0 → 0.45.0

package/make-kit/components/card.md

@@ -6,18 +6,20 @@ The default container for any panel-style content that sits **on** the page.
 import {
   Card,
   CardAction,
+  CardBleed,
   CardHeader,
   CardTitle,
   CardDescription,
   CardContent,
   CardFooter,
+  CardSection,
 } from '@devalok/shilp-sutra/ui/card'
 ```
 
 ## When to use
 
 - Any rectangular region that reads as a discrete unit on the page: dashboards widgets, list items, marketing feature blocks.
-- Need built-in header / actions / footer slots? Use `<ContentCard>` (composed wrapper).
+- Header / actions / footer are built in as slots (`CardHeader`, `CardAction`, `CardFooter`) — don't reach for a wrapper. (`<ContentCard>` is deprecated; use Card slots.)
 - Need just a tinted region with no card affordance? Use a `<div className="bg-surface-raised">` (rare; usually Card is right).
 
 Card renders on `surface-raised` with `shadow-raised`. **Never** override its background or border.
@@ -38,27 +40,62 @@ Card renders on `surface-raised` with `shadow-raised`. **Never** override its ba
 | `default` (default) | Standard border. |
 | `accent`, `error`, `success`, `warning`, `info`, `neutral` | Border picks up the semantic color at step-7. Use to signal status without filling the whole card. |
 
-## Sizes (padding cascade)
+## Sizes (one CSS variable)
 
-`size` on Card propagates to `CardHeader`, `CardContent`, `CardFooter` via React context:
+`size` sets `--card-spacing` / `--card-gap` once on the root. The container reads them for its
+vertical padding + inter-slot gap; every slot reads `--card-spacing` for its horizontal inset;
+`CardAction` corners and `CardBleed` negations read the same variable.
 
-| Size | Default padding |
-|---|---|
-| `sm` | `ds-04` (12 px) |
-| `md` (default) | `ds-05` (16 px) |
-| `lg` | `ds-07` (32 px) |
+| Size | `--card-spacing` | `--card-gap` |
+|---|---|---|
+| `sm` | `ds-05` (16 px) | `ds-03` (8 px) |
+| `md` (default) | `ds-05b` (20 px) | `ds-04` (12 px) |
+| `lg` | `ds-06` (24 px) | `ds-05` (16 px) |
 
-Override on a sub-component via `className` only if absolutely necessary — it breaks the cascade.
+To retune a single card, override the variable — never add `p-*`/`pt-*` classes:
+
+```tsx
+<Card className="[--card-spacing:var(--spacing-ds-07)]">…</Card>
+```
 
 ## Compound shape
 
 ```
-Card (root)
-  CardHeader      ← inherits size from Card
+Card (root)              ← owns py + gap (vertical rhythm)
+  CardBleed side="top"   ← optional full-bleed media (negates the card padding)
+  CardHeader             ← owns px only
     CardTitle
     CardDescription
-  CardContent     ← inherits size from Card
-  CardFooter      ← inherits size from Card
+  CardContent            ← owns px only
+  CardFooter             ← owns px only
+  CardAction             ← absolute corner overlay
+```
+
+Direct children of Card span its **full width** (only slots are inset). A `<Separator />` or a
+tinted band placed between slots is edge-to-edge for free. The flip side: **text must live inside
+a slot** — a bare `<p>` as a direct child gets no horizontal inset (dev builds warn).
+
+### CardBleed (escape the padding)
+
+| Prop | Type | Notes |
+|---|---|---|
+| `side` | `'x'` (default) `\| 'top' \| 'bottom' \| 'y' \| 'all'` | Which card padding to negate. `top`/`bottom`/`y` are for **direct children** (cover images, edge bands) and inherit the card radius. `x`/`all` are for content **inside a slot**. Never use `x`/`all` on a direct child — it will overflow. |
+
+### Horizontal cards
+
+`orientation="horizontal"` turns the root into a padding-less row; put the media pane first and
+wrap the text column in `<CardSection>`, which re-establishes py + gap from the same variables:
+
+```tsx
+<Card orientation="horizontal">
+  <div className="w-28 shrink-0 overflow-hidden rounded-l-surface">
+    <img className="h-full w-full object-cover" src={thumb} alt="" />
+  </div>
+  <CardSection>
+    <CardHeader><CardTitle>Title</CardTitle></CardHeader>
+    <CardFooter>meta</CardFooter>
+  </CardSection>
+</Card>
 ```
 
 ## Other props
@@ -152,6 +189,7 @@ Card (root)
 - **Never** `bg-surface-base` on a Card — cards sit on `surface-raised`. The pre-publish audit rejects this.
 - **Never** combine `border-*` + `shadow-*` on a Card. Pick one (Card already does — don't override).
 - **Use `interactive` + `onClick` + `aria-label`** for clickable cards. Don't wrap a Card in a `<button>` — broken nesting.
-- **`size` on Card** drives sub-component padding. Don't set padding on `CardContent` directly.
-- **Don't stack `default` cards inside another `default` card.** The nested one should be `flat` or `outline`.
-- For row-style content (avatar + title + meta + actions), prefer `<ContentCard>` from `/composed/content-card` — it bundles the slots.
+- **`size` on Card** drives all spacing via `--card-spacing`. Never set `p-*` on Card or a slot — override the variable if a one-off is truly needed.
+- **Full-bleed** media/dividers use `<CardBleed>` (or plain direct children for full-width strips) — never negative-margin hacks.
+- **Don't stack `default` cards inside another `default` card.** The nested one should be `flat` or `outline`, or better, a `bg-surface-base` recess.
+- For row-style content (avatar + title + meta + actions), compose Card slots — `<ContentCard>` is deprecated and will be removed next major.

package/make-kit/components/table.md

@@ -12,7 +12,9 @@ import {
   TableHead,
   TableCell,
   TableCaption,
+  TableRowActions,
 } from '@devalok/shilp-sutra/ui/table'
+import { TableRowLink } from '@devalok/shilp-sutra/ui/table-row-link' // client-only
 ```
 
 ## When to use
@@ -39,7 +41,19 @@ Table (<table>)
       TableCell
 ```
 
-Each component is a thin semantic wrapper — no props beyond standard HTML attributes plus `className`.
+## Props
+
+| Component | Prop | Values | Notes |
+|---|---|---|---|
+| `Table` | `density` | `compact` \| `standard` (default) \| `comfortable` | Rows ≈ 29 / 37 / 45 px via `--table-py`; header height tracks it |
+| `Table` | `striped` | boolean | Opt-in zebra. Hairline separators are the default row cue — stripe only very wide/dense tables |
+| `TableCell` / `TableHead` | `numeric` | boolean | Right-align + tabular figures. Quantities only — dates/phones/IDs stay left |
+| `TableRowActions` | `persist` | boolean | Actions always visible instead of hover/focus reveal |
+| `TableRowLink` | `href`, `stretch` | string, boolean (default true) | Real-anchor whole-row navigation; `stretch={false}` = title-only link |
+
+Everything else is a thin semantic wrapper over standard HTML attributes plus `className`.
+
+**Density → cell content.** Rows grow silently when content is taller than the text line: `compact` = text only, `standard` = `Avatar size="xs"` max + single-line identity, `comfortable` = the only density for two-line identity (name + email).
 
 ## Examples
 
@@ -104,22 +118,23 @@ Each component is a thin semantic wrapper — no props beyond standard HTML attr
 </Table>
 ```
 
-**Row actions (IconButton in last cell):**
+**Row actions (hover/focus-revealed via TableRowActions):**
 ```tsx
 <Table>
   <TableHeader>
     <TableRow>
       <TableHead>File</TableHead>
-      <TableHead>Size</TableHead>
-      <TableHead className="w-12" />
+      <TableHead numeric>Size</TableHead>
+      <TableHead className="w-12"><span className="sr-only">Actions</span></TableHead>
     </TableRow>
   </TableHeader>
   <TableBody>
     {files.map((f) => (
       <TableRow key={f.id}>
         <TableCell>{f.name}</TableCell>
-        <TableCell>{formatFileSize(f.size)}</TableCell>
+        <TableCell numeric>{formatFileSize(f.size)}</TableCell>
         <TableCell>
+          <TableRowActions>
           <DropdownMenu>
             <DropdownMenuTrigger asChild>
               <IconButton icon={<Icon icon={IconDots} />} variant="ghost" size="sm" aria-label="Actions" />
@@ -130,6 +145,7 @@ Each component is a thin semantic wrapper — no props beyond standard HTML attr
               <DropdownMenuItem onSelect={() => remove(f)}>Delete</DropdownMenuItem>
             </DropdownMenuContent>
           </DropdownMenu>
+          </TableRowActions>
         </TableCell>
       </TableRow>
     ))}
@@ -137,6 +153,25 @@ Each component is a thin semantic wrapper — no props beyond standard HTML attr
 </Table>
 ```
 
+`TableRowActions` reveals on row hover AND keyboard focus (buttons stay permanently tabbable — opacity reveal, never `display:none`); always visible on touch. Pass `persist` to keep actions always visible. Give the column a visually-hidden header.
+
+**Whole-row navigation (TableRowLink — client component):**
+```tsx
+<TableRow>
+  <TableCell className="relative">
+    <TableRowLink href={`/projects/${p.id}`}>{p.name}</TableRowLink>
+  </TableCell>
+  <TableCell><Badge color="success">Active</Badge></TableCell>
+  <TableCell>
+    <TableRowActions>
+      <IconButton className="relative z-[1]" size="xs" variant="ghost" aria-label={`Actions for ${p.name}`} icon={<Icon icon={IconDots} />} />
+    </TableRowActions>
+  </TableCell>
+</TableRow>
+```
+
+A real anchor stretched across the row — cmd/ctrl+click, middle-click, and "open in new tab" work. The primary cell must be `className="relative"`; other interactive elements in the row need `className="relative z-[1]"`. **Never** put `onClick` on a `<TableRow>` for navigation. Trade-off: the stretch blocks text selection — `stretch={false}` gives a title-only link.
+
 **Inside a Card:**
 ```tsx
 <Card>
@@ -164,7 +199,7 @@ Each component is a thin semantic wrapper — no props beyond standard HTML attr
 </Card>
 ```
 
-When inside a `<Card>`, the Table's surrounding padding comes from `CardContent`. Don't add extra padding on the Table.
+Better: for edge-to-edge rows (borders and hover running the full card width), place the Table as a **direct child of Card** instead of inside `CardContent` — first/last cells automatically pad with `var(--card-spacing)` so columns align with the card's header/footer slots. Use `CardContent` wrapping only when the table should stay inset.
 
 **Server-rendered table (RSC):**
 ```tsx
@@ -212,4 +247,7 @@ See `foundations/typography.md` for the body / label variants inside cells, `fou
 - 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.
+- Keep TableCell content single-line where possible — multi-line cells make scanning hard. Two-line identity cells (name + email) require `density="comfortable"`.
+- Quantitative columns get `numeric` (right + tabular figures). Identifier-numbers (dates, phones, IDs) stay left. Negatives: never color alone — pair with a minus sign or parentheses.
+- Row navigation = `<TableRowLink>` (real anchor), never `onClick` on the row. Row actions = `<TableRowActions>` with a visually-hidden column header.
+- Empty cells get a muted em-dash with `aria-label`, never blank: `<span className="text-fg-muted" aria-label="No value">—</span>`.

package/make-kit/foundations/spacing.md

@@ -37,7 +37,9 @@ If you need a *fourth* tier (e.g. between heading and body inside one group), us
 
 ```tsx
 // Padding
-<Card className="p-ds-05">…</Card>          // inside-card spacing
+// Card manages its own padding via the size prop — NEVER add p-* to a Card
+// (it fights the gap model). Use size="sm" | "md" | "lg" instead.
+<Card size="sm">…</Card>                    // tighter card
 <div className="px-ds-07 py-ds-09">…</div>  // page region
 
 // Gaps

package/make-kit/foundations/surfaces.md

@@ -97,7 +97,7 @@ In dark mode the kit lightens surfaces with elevation (so `surface-overlay` is *
     …
   </aside>
   <main className="bg-surface-base p-ds-07">
-    <Card className="bg-surface-raised shadow-raised p-ds-05">  {/* Card */}
+    <Card>  {/* Card — brings its own surface, shadow, and padding (never add p-*) */}
       …
       <Dialog>
         <DialogContent className="bg-surface-overlay shadow-overlay">