@nocoo/basalt 3.0.0 → 3.1.0

package/ai/DESIGN.md

@@ -64,6 +64,12 @@ Dialog and AlertDialog panels use 16px outer insets on mobile and 24px from
 640px. Their buttons and fields retain compact control spacing. Sheets and
 small floating menus have separate inset contracts.
 
+Form rhythm distinguishes a field from a group: label/control/hint spacing stays
+8px, related fields use 16px layout gaps, and separate sections use 24px. A form's
+stack owns those gaps; individual Field components do not add outer margins.
+DialogFooter owns 16px separation from content and keeps 8px between its actions.
+Do not add a matching margin at every caller or enlarge controls to open a form.
+
 Metric cards use the shared `StatCard`, not a hand-built Header/Body split. A single
 16px inset owns the title, value, comparison and supporting chart; 12px separates
 the heading, metric and content groups, and 4px separates value/supporting text.
@@ -79,9 +85,12 @@ Zero, auto margins and hairline seams are structural exceptions, not new density
 levels. Negative margins may cancel an owned boundary, not invent a new gap.
 Use `p-basalt-card`, `gap-basalt-layout`, `gap-basalt-space-sm`, etc. Default nav
 insets and field gaps remain 8px. Selectable rows use 8px horizontal / 6px vertical
-insets and an 8px icon gap. One component owns each boundary: nested sections must
-not accidentally double outer padding. Indented detail content may derive its
-alignment from the row inset + icon width + gap; this is not another density tier.
+insets and an 8px icon gap. Sidebar destinations alone use 8px vertical padding;
+menus, editable navigation and chat rows retain their compact role. One component
+owns each boundary: nested sections must not accidentally double the same inset.
+Distinct surface, column and semantic-slot boundaries may compose their spacing.
+Indented detail content may derive its alignment from the row inset, icon width
+and gap; this is not another density tier.
 
 Existing numbered `--basalt-space-*` tokens are a geometry scale for icons,
 media and shell widths. They are not an alternative margin/padding scale.
@@ -133,6 +142,8 @@ The shared classes calculate natural size as follows:
   side = 34px. Body prose/code retain the 20px line box. Compound inputs own one
   outer border; inset children do not add another. Segmented tracks keep 12px text
   on a 20px line box: 30px items + 2px track inset per side = 34px.
+- Sidebar destination and disclosure rows use the same 22px line box with 8px
+  vertical padding, yielding 38px reference rows without changing shared controls.
 - Cards, dialogs and layout containers have no mandatory height. Textareas and
   chat inputs grow with content (chat: up to five lines, then scroll).
 
@@ -198,9 +209,12 @@ interaction contracts; do not change their containment as a global workaround.
   opacity or mutes its primary label.
 - SidebarPartition is a major section label (12px, semibold, uppercase, 16px top
   spacing). SidebarGroup is a compact disclosure label (11px, semibold, uppercase,
-  8px inset, 12px group separation), not a destination or hover-highlight target.
-  Ordinary destinations use 14px text and the shared 8px/6px row insets. Groups
-  preserve keyboard expansion and chevron motion; collapsed rails omit labels.
+  22px line box, 8px inset, 12px group separation), not a destination or
+  hover-highlight target. Ordinary sidebar destinations use 14px text and 8px
+  row insets. Groups preserve keyboard expansion and chevron motion; collapsed
+  rails omit labels. Icons stay centered on the 68px collapsed rail, and the brand
+  mark keeps the same center when expanded. Do not trade that axis for a global
+  left-edge alignment.
 - Content wells use the actual surface hierarchy, not selected tokens or muted
   fills. Skeletons, progress tracks and decorative code marks may remain subdued.
 
@@ -219,6 +233,10 @@ use linear motion; decorative motion pauses off-screen/in background tabs.
   do not remeasure the same row for pointer movement, and write geometry without
   React rerenders. Nested lists are isolated. Disabled and hidden rows cannot
   become targets; keyboard selection/focus works independently of pointer hover.
+  Sidebar hover starts at the pointer's row and disappears there. It never uses
+  the current route or stale pointer focus as an entry/exit destination. Only
+  continuous movement between hovered rows animates; gaps and disclosure labels
+  end that sequence. Keyboard focus retains its independent focus indicator.
 - Selection indicators snap to the first valid measured selection before paint.
   Never animate from `(0, 0)`, including controlled initial values, non-first
   segments, remounts or initially hidden panels. Animate only between established
@@ -260,7 +278,9 @@ natural height, no scenic wrappers, negative insets or fixed empty openings.
 Scrollable gallery previews reserve 8px of internal space on every edge for
 control rings, focus outlines and shadows. Padding outside the scroll viewport
 does not protect that paint. Center previews safely so oversized content keeps
-its leading edge reachable.
+its leading edge reachable. Multi-column Table, DataTable and DiffTable examples
+span the category grid; do not squeeze a working data surface into a half-width
+thumbnail. Compact examples such as TablePager retain their smaller grid cells.
 The component library uses one LayerCard per category, separated by 24px. Each
 category uses LayerCard.Header above its grid, not individual cards per component.
 Its light surface is white-toned; dark mode uses the same surface hierarchy rather
@@ -275,6 +295,42 @@ painted divs. Use library controls and tables instead of rebuilding their spacin
 focus, selection and motion in page CSS. Semantic color overrides and purposeful
 chart/canvas geometry remain separate from shared control geometry.
 
+### Alignment hierarchy
+
+Alignment is local to a meaningful scope, not a requirement that every text node
+start at the page edge. Establish the outer rail before composing the inner one:
+
+| Scope | Alignment rule |
+| --- | --- |
+| Page | PageHeader and region edges share the ContentIsland rail |
+| Surface | Header, body and footer share their panel inset |
+| Field or column | Labels, controls and values follow that group's start or end rail |
+| Semantic slot | Checkboxes, row numbers and status glyphs reserve their own consistent space |
+
+Related text keeps its rail across sorting, selection and missing optional icons.
+Numeric headings and values share the end rail; a sort glyph sits inward of that
+label rather than pushing it away from the values. Reserve the same glyph slot
+for Keep, Add and Remove instead of indenting only changed rows. Ordinary button
+padding is not a table-header inset. Preserve the focus target through a shared
+header control rather than compensating with negative page margins.
+
+Table cells keep 8px horizontal / 6px vertical insets and 36px reference rows.
+An edge attached to a panel uses `--basalt-space-table-edge` (the panel's 16px
+horizontal inset), independently of the space between columns. The owner of the
+column structure marks the actual edge cells; DOM first/last-child selectors
+cannot infer that boundary across rowSpan. DataTable owns this through
+`edge="attached"`; native Table compositions use `ps-basalt-table-edge` and
+`pe-basalt-table-edge` only on the corresponding edge cells. A full-width cell
+uses both. Row fills and header rules remain full width, and nested tables keep
+their own insets. An already inset table retains the default cell spacing.
+TableCaption owns its 16px horizontal and 12px vertical panel insets, without an
+outside margin. Its text must not touch an enclosing table frame's bottom edge.
+
+Purposeful nesting, such as a preview's focus clearance around a self-contained
+surface, remains valid. Increase the separation between groups before increasing
+every inner gap; breathing room comes from distinguishable groups and adequate
+content width, not uniformly loose controls or one global density multiplier.
+
 ### Container boundary ownership
 
 Choose the boundary before choosing a spacing token. A valid token on the wrong
@@ -287,7 +343,7 @@ owner is still a design error:
 | Full-width disclosure heading | `LayerCard.Header asChild` | Slot onto `CollapsibleTrigger`; one hit target, 16/12px insets |
 | Expanded prose or fields | `LayerCard.Body` | Inside `CollapsibleContent unstyled`; one 16px inset |
 | Attached code | `CodeBlock attached` / `CodeHighlighted attached` | Direct child of unstyled disclosure; code owns its 16/12px insets |
-| Edge-to-edge table/list | Its row/cell components | Direct card child; no Body with `p-0` or compensating margins |
+| Edge-to-edge table/list | Its row/cell components | Direct card child; panel inset on edge cells, no Body with `p-0` or compensating margins |
 | Compact status/action strip | `Banner` | Control spacing, not a hand-drawn card |
 
 Collapsible owns visibility, focus semantics and motion; it does not add another

package/ai/INTEGRATION.md

@@ -428,9 +428,9 @@ Do not wrap those regions in another full-viewport column. Do not set `h-screen`
 
 ### Shared navigation geometry
 
-`SidebarNav` and `NavigationMenuList` own one `--basalt-space-nav-inset` (8px) boundary and `--basalt-space-nav-gap` (2px) between rows. Sidebar groups do not add another horizontal inset. Top-level items, group items, editable/folder rows and horizontal navigation links reuse the existing row roles: 8px horizontal, 6px vertical, 8px icon gap, 22px line box and a 34px reference height. Header, search wrapper and footer share the same navigation inset. Do not add caller-owned `px-basalt-space-lg`, `pt-basalt-space-sm` or item-stack padding to compensate for missing package geometry.
+`SidebarNav` and `NavigationMenuList` own one `--basalt-space-nav-inset` (8px) boundary and `--basalt-space-nav-gap` (2px) between rows. Sidebar groups do not add another horizontal inset. Sidebar destinations and search use 8px horizontal/vertical padding, an 8px icon gap and a 22px line box for a 38px reference row. This is local to Sidebar: editable/folder rows, horizontal navigation links and menus retain 6px vertical padding and 34px rows. Header, search wrapper and footer share the same navigation inset. Do not add caller-owned `px-basalt-space-lg`, `pt-basalt-space-sm` or item-stack padding to compensate for missing package geometry.
 
-Use `SidebarNav` for vertical lists, including standalone lists of `EditableNavItem` / `FolderNavItem`; `NavigationMenuList` owns horizontal/vertical Radix navigation. Both compose the existing list-local hover adapter. One background moves with transform between enabled rows, follows keyboard focus and returns to selection on pointer leave. Nested lists own separate highlights. Hidden, disabled and actively renamed rows are excluded. Geometry reads are batched per animation frame, same-row pointer motion causes no updates, and reduced motion disables transitions. Navigation state, routes and rename operations remain application-owned; the adapter is View-only.
+Use `SidebarNav` for vertical lists, including standalone lists of `EditableNavItem` / `FolderNavItem`; `NavigationMenuList` owns horizontal/vertical Radix navigation. Both compose the existing list-local hover adapter. One background moves with transform between enabled rows. Sidebar hover appears at the actual pointer row and disappears there on leave or over a gap/disclosure label; it never launches from or returns to the active route or stale pointer focus. Only continuous row-to-row hover animates. Keyboard focus remains independent. NavigationMenuList retains its focus/selection-following behavior. Nested lists own separate highlights. Hidden, disabled and actively renamed rows are excluded. Geometry reads are batched per animation frame, same-row pointer motion causes no updates, and reduced motion disables transitions. Navigation state, routes and rename operations remain application-owned; the adapter is View-only.
 
 `SidebarHeader` and `SidebarFooter` already pad horizontally. Brand, version pill, and collapse control go directly in the header. The version string is read from the app `package.json` at build time. Never hardcode it. `SidebarPartition` aligns with row text. `SidebarGroup` adds only section spacing, never a second item gutter.
 
@@ -486,13 +486,13 @@ Use `SidebarNav` for vertical lists, including standalone lists of `EditableNavI
 </Sidebar>
 ```
 
-SidebarPartition marks a major section; SidebarGroup is a smaller uppercase, semibold disclosure label with additional group spacing. Group labels do not participate in the destination hover layer. Do not restyle them as ordinary SidebarItem rows or add per-page indentation repairs.
+SidebarPartition marks a major section; SidebarGroup is a smaller uppercase, semibold disclosure label with a 22px line box, 8px insets and 12px group separation. Group labels do not participate in the destination hover layer. Do not restyle them as ordinary SidebarItem rows or add per-page indentation repairs.
 
 ### Collapsed tree
 
 Pass `collapsed` on `Sidebar`. The element becomes 68px. Children are icon-sized and centered. Still no inner width/height wrapper.
 
-The 68px rail uses `--basalt-size-rail`. Header and footer center their content automatically; SidebarIconItem uses the shared 34px control size. The navigation region centers its icon rows on that same rail axis without caller margin overrides. Render icon-only content with an accessible name and tooltip when collapsed; the library does not hide arbitrary application text. Keep a brand mark's expanded inset consistent with the collapsed axis instead of adding collapse-only offsets.
+The 68px rail uses `--basalt-size-rail`. Header and footer center their content automatically; SidebarIconItem keeps the 34px control width and derives its 38px minimum height from the sidebar line box and padding. The navigation region centers its icon rows on that same rail axis without caller margin overrides. Render icon-only content with an accessible name and tooltip when collapsed; the library does not hide arbitrary application text. Keep a brand mark's expanded inset consistent with the collapsed axis instead of adding collapse-only offsets.
 
 ```tsx excerpt:sidebar-collapsed-structure
 <Sidebar collapsed={collapsed}>
@@ -1021,6 +1021,12 @@ Stack one `SectionRule` per region. Live recipe: `/layout`. Catalog: `/ui/page-h
 
 Basalt form controls participate in standard forms and controlled state pipelines.
 
+Keep the Field's label/control/hint gap at 8px. Compose related fields with
+`space-y-basalt-layout` or `gap-basalt-layout` (16px); separate sections with the
+24px `layout-lg` role. The form owns the group gap, not each Field's margin.
+Action buttons keep their 8px internal gap. DialogFooter owns 16px separation
+from preceding content, so callers do not need a repeated margin override.
+
 ### Working Native HTML Form & FormData Pattern
 
 Standard inputs (`Input`, `InputArea`, `Checkbox`, `Radio`, `Switch`) reliably supply their values via standard `FormData(event.currentTarget)`:
@@ -1039,7 +1045,7 @@ export function ProfileForm() {
   };
 
   return (
-    <form onSubmit={handleSubmit}>
+    <form onSubmit={handleSubmit} className="space-y-basalt-layout">
       <Field label="Email" hint="Your primary email address">
         <Input name="email" type="email" required />
       </Field>
@@ -1048,7 +1054,7 @@ export function ProfileForm() {
         <Switch name="notifications" defaultChecked />
       </Field>
 
-      <div className="flex gap-basalt-space-lg mt-basalt-space-lg">
+      <div className="flex gap-basalt-space-lg">
         <Button type="reset" variant="secondary">Reset</Button>
         <Button type="submit" variant="default">Save Changes</Button>
       </div>
@@ -1203,7 +1209,7 @@ export function ProjectSettingsForm() {
   };
 
   return (
-    <form onSubmit={handleSubmit(onSubmit)} className="space-y-basalt-space-lg">
+    <form onSubmit={handleSubmit(onSubmit)} className="space-y-basalt-layout">
       <Field
         label="Project Name"
         hint="Unique name for your project workspace"
@@ -1728,7 +1734,7 @@ export function UserPreferencesForm() {
   };
 
   return (
-    <form onSubmit={handleSubmit} onReset={handleReset} className="space-y-basalt-space-lg max-w-sm">
+    <form onSubmit={handleSubmit} onReset={handleReset} className="space-y-basalt-layout max-w-sm">
       <Field label="Username" hint="Public profile handle">
         <Input name="username" defaultValue="johndoe" required />
       </Field>
@@ -1807,6 +1813,7 @@ Basalt geometry no longer depends on a host's Tailwind `--spacing`. Both CSS ent
 | Field label gap | `--basalt-space-field-gap` | 8px |
 | Textarea minimum height | `--basalt-size-textarea-sm`, `--basalt-size-textarea`, `--basalt-size-textarea-lg` | 64 / 80 / 96px |
 | Table row / horizontal / vertical inset | `--basalt-size-table-row`, `--basalt-space-table-x`, `--basalt-space-table-y` | 36 / 8 / 6px |
+| Attached table outer edge | `--basalt-space-table-edge` | Panel horizontal inset, 16px |
 
 Defaults use rem and unitless line-height, preserving browser font-size preferences. [DESIGN.md](DESIGN.md) defines compact 2/4/6/8px control spacing, separate 12/16/24/32px card and layout spacing, and natural 22/34/46px inline/action/banner categories. The size tokens describe reference geometry, not fixed text-control heights. Use the semantic spacing role for the boundary being laid out; numbered geometry tokens are not padding alternatives. LayerCard accepts `padding="sm|md|lg|xl"` for unstructured content; Grid accepts `gap="sm|md|lg|xl"`. Both default to `md`; 32px `xl` is opt-in. ContentIsland owns a 16px mobile, 24px tablet, and 32px horizontal / 24px vertical desktop inset. Examples must use component size props rather than fixed-height overrides. Textareas, avatars and panels retain content-specific geometry.
 
@@ -1814,6 +1821,66 @@ Defaults use rem and unitless line-height, preserving browser font-size preferen
 
 DataTable uses 13px single-line content, 36px minimum rows, tokenized horizontal/vertical insets and a native horizontally scrollable region. A column's `width` is also its minimum width; the browser must not squeeze names/dates into accidental multi-line rows. Use `column.wrap: true` for actual prose fields, or an explicitly sized inner `truncate` element with a title for long record names and URLs. `maxHeight` bounds the existing scroll region, with sticky opaque headers that stay inside it. Sorting uses a fixed 12px icon slot and retains `aria-sort`; row selection uses the shared Checkbox rather than an unstyled native checkbox. Rich `headerContent` composes icons and labels without changing the plain accessible sort name. Empty/loading/error content remains readable and wraps independently of data-cell defaults.
 
+Use `column.textAlign: "end"` for comparable numbers: the header and values share
+a logical end rail, with the sort glyph inward of the header label. `"start"` is
+the other explicit direction; omitted body-cell alignment remains inherited.
+The same `textAlign` prop is available on TableHead, TableCell and
+TableSortableHeader from `@nocoo/basalt/components/table`. It does not replace
+native HTML `align` attributes. Logical directions follow LTR/RTL consistently.
+
+TableSortableHeader is a flush, ref-forwarding button, not a generic Button with
+extra padding. Pass its `sorted` direction (`"asc"` / `"desc"`, or omitted) and
+sort callback; the enclosing TableHead owns `aria-sort`. Unsortable headers remain
+plain text, not disabled sort controls. DataTable handles those details for its
+own columns.
+
+For a DataTable directly attached to a LayerCard, set `edge="attached"`. It uses
+the 16px panel rail only at the outermost cells, including optional number/select
+columns and full-width state rows. Intercolumn spacing stays 8px per cell side.
+Built-in pagination shares that panel rail and its 12px bottom inset.
+The default `edge="inset"` keeps ordinary table spacing inside an already padded
+region; do not add a zero-padding Body around an attached table.
+
+```tsx compile:integration-attached-table
+import { DataTable, type DataTableColumn } from "@nocoo/basalt/components/data-table";
+import { LayerCard } from "@nocoo/basalt/components/layer-card";
+
+type Invoice = { id: string; amount: number };
+const columns: DataTableColumn<Invoice>[] = [
+  { id: "id", header: "Invoice", accessor: (row) => row.id },
+  { id: "amount", header: "Amount", accessor: (row) => row.amount, textAlign: "end" },
+];
+
+export function InvoicePanel() {
+  return (
+    <LayerCard>
+      <LayerCard.Header>Invoices</LayerCard.Header>
+      <DataTable
+        aria-label="Invoices"
+        edge="attached"
+        columns={columns}
+        data={[{ id: "INV-01", amount: 1240 }, { id: "INV-02", amount: 80 }]}
+        getRowId={(row) => row.id}
+      />
+    </LayerCard>
+  );
+}
+```
+
+Native Table does not infer a grid from its children. For an attached native
+composition, mark the true inline-start cells with `ps-basalt-table-edge`, the
+inline-end cells with `pe-basalt-table-edge`, and a full-width cell with both.
+Rows continuing a preceding `rowSpan` do not gain a new edge at their first DOM
+child. These token utilities keep cell backgrounds, sticky headers and separators
+full width without affecting nested tables. Use ordinary Table cells when no
+panel edge is being attached.
+
+TableCaption owns balanced `--basalt-space-panel-x` / `--basalt-space-panel-y`
+insets (16px horizontal / 12px vertical), not an outside top margin. Keep it
+inside the native table; do not pad the entire scroll region or compensate with
+an extra footer wrapper. This preserves full-width row paint and readable space
+above and below the description inside an enclosing frame.
+
 ### Recommendations
 
 `RecommendationCard` (`components/recommendation-card`) accepts stable-ID options with a label, plain-text description, confidence (`high`, `review`, `none`) and optional action label/disabled state. Alternatives expand with the existing disclosure and shared hover layer; choosing one changes the recommendation, never executes it. `onAccept` runs only after the explicit action. Promise rejection preserves the selection and shows retry feedback; pending acceptance locks controls and successful acceptance cannot be repeated for the current option. Remount with a new key for a new recommendation request. The application must perform authorization and persist any real action. Private model/ViewModel modules own confidence metadata and state, without View or DOM imports.
@@ -1846,6 +1913,14 @@ All model names, progress summaries, searches and tool outputs on this route are
 
 Use one padding owner per boundary: `--basalt-space-panel-x/y` (16/12px) for composite card/header/body/footer sections, `--basalt-space-row-x/y/gap` (8/6/8px) for selectable rows, and `--basalt-space-content-gap` (8px) between related controls inside a composite. Page section gaps instead use `--basalt-space-layout-lg` (24px). `--basalt-space-row-content` derives the detail inset from row padding + a 16px icon slot + the row gap. Selectable action rows use the 22px `--basalt-line-row`, producing 34px single-line rows and growing by full lines when content wraps. Status icons occupy a first-line-height slot, not an arbitrary top margin. Body prose and code keep the 20px body line-height. Ordinary controls use 34px; inline message actions use the 34px `--basalt-size-action` target and 14px glyphs. Align visible glyphs with prose without removing their pointer target.
 
+These are local alignment rails, not one universal left edge. Page headings align
+to the island; card slots align to their panel; columns align their own labels and
+values. A checkbox, row number or optional status glyph has a consistent semantic
+slot. Distinct boundaries may add spacing, but the same boundary has one owner.
+See [alignment hierarchy](DESIGN.md#alignment-hierarchy). Keep nested preview focus
+clearance and give wide table examples enough columns rather than shrinking all
+their padding to fit a thumbnail.
+
 Thinking and ToolChips share row padding; disclosures rotate only their own chevron, never content icons. Approval, recommendation, retrieved context and diff sections share panel insets rather than adding another padding layer. ChatComposer owns its field inset, not an outer painted/padded card; the application owns placement in the page. ChatMessage `sources` renders a compact disclosure beside actions and a flat source list, with the same validated URL policy as ContextCards. Use ContextCards only for actual retrieved text chunks, not as a citation footer. No additional remote images are loaded.
 
 The standalone build generates every Tailwind utility once in canonical order. Do not append handwritten copies of `.p-0`, `.bg-transparent` or other native utilities after generated axis/state rules: a later shorthand can silently erase semantic padding. Browser acceptance measures actual computed insets in both CSS entrypoints, under foreign host spacing and semantic overrides.

package/ai/USAGE.md

@@ -1,6 +1,6 @@
 # Basalt AI & Machine Usage Guide
 
-This document describes how AI code assistants, automated agents, and developers can consume `@nocoo/basalt` (v3.0.0).
+This document describes how AI code assistants, automated agents, and developers can consume `@nocoo/basalt` (v3.1.0).
 
 ---
 
@@ -14,7 +14,7 @@ Document anchors formatted as `ai/registry.json#<slug>` reference specific catal
 It contains:
 - **131 Exported Modules** (1 root barrel, components, charts, providers)
 - **120 Ready Catalog Entries** with full API definitions
-- **776 Public Symbols** (405 runtime values, 371 TypeScript types)
+- **781 Public Symbols** (406 runtime values, 375 TypeScript types)
 - **Detailed Component API**: Props, types, defaults, descriptions, and function callable signatures (including all `toast()` variants)
 - **Exact Peer Dependency Closures**: Identifies optional peers required per subpath (e.g., Recharts)