@nadicodeai/ui 6.0.1 → 6.1.0

package/docs/component-classification.md

@@ -19,8 +19,9 @@ copy, and behavior.
 
 | Component | Classification | Built on | Required states | Package-owned accessibility | Fixture |
 | --- | --- | --- | --- | --- | --- |
-| `SettingsSection` | Net-new NadicodeAI product composition. | shadcn `FieldGroup` plus standard section markup. | header with optional actions; field group content. | section structure; no form behavior. | `../tests/guards/product-compositions.test.ts` |
-| `SettingsField` | Net-new NadicodeAI product composition. | shadcn `Field`, `FieldLabel`, `FieldDescription`, and `FieldError`. | valid and invalid field rows; disabled rows. | Label `htmlFor`; render props receive control attributes; element controls require an explicit matching `id` and described-by wiring. | `../tests/guards/product-compositions.test.ts` |
+| `ActionMenu` | Canonical record-action composition. | shadcn `Button` and `DropdownMenu`. | closed, open, keyboard selection, focus return. | Required accessible trigger name; inherited menu mechanics. | `../src/components/action-menu.test.tsx` |
+| `SettingsSection` | NadicodeAI product composition. | shadcn Card slots, Separator, and FieldGroup. | header, field group, and divided action footer. | Section structure; consumer owns the form transaction. | `../src/components/settings-section.test.tsx` |
+| `SettingsField` | NadicodeAI product composition. | shadcn Field, FieldLabel, FieldDescription, and FieldError. | valid, invalid, required, and disabled field rows. | Render callback supplies the control's label and message associations in server and client components. | `../src/components/settings-section.test.tsx` |
 | `FeedbackState` | Net-new central product state composition adapted from shadcn empty-state patterns. | shadcn `Empty` and lucide status icons. | `empty`, `loading`, `saving`, `error`, `permission`, `offline`, `no-results`, `fatal`. | `role="status"` for loading/saving; `role="alert"` for error, permission, offline, and fatal. | `../tests/guards/product-compositions.test.ts` |
 
 ## App-Owned Boundaries

package/docs/contract.md

@@ -27,6 +27,9 @@ Physical role, not content importance, chooses depth:
   work chooses it explicitly.
 - `Card surface="plain"` is the explicit structural/auth/website escape and
   carries no elevation.
+- `Card surface="outlined"` is a flat panel with a single semantic border and
+  compact corners; it carries no elevation ring or shadow. Bounded fact cells
+  use it inside resting record sections. Portal's kit keeps the resting default.
 - Tooltip, menu, popover, select, combobox, navigation popup, hover card,
   chart tooltip, and toast roots own `nc-elevation-floating` internally.
 - Dialog, alert dialog, drawer, and sheet roots own `nc-elevation-modal`
@@ -64,11 +67,36 @@ transparent and unframed because the Card already owns containment.
 
 ### Tables
 
-`Table` owns the native table structure, solid semantic background, horizontal
-overflow, and one compact density: 36px header rows and 40px body rows. Consumers
+`Table` owns the native table structure, solid semantic background, an overflow
+safety boundary, and one compact density: 36px header rows and 40px body rows. Consumers
 compose `TableHeader`, `TableBody`, `TableRow`, `TableHead`, and `TableCell`; they
 do not replace table layout with grid or flex, hide the header to create another
-presentation, or reconstruct the native semantics with ARIA.
+presentation, or reconstruct the native semantics with ARIA. Portal collections
+must fit their available width without horizontal scrolling: preserve identity
+and actions in columns and place supporting facts in native detail rows before
+the full schema becomes cramped. Test the table container itself, not only the
+document width; retaining the overflow safety boundary must not conceal a
+layout defect.
+
+`CollectionScope` chooses the parent of one record collection. It places the
+scope selector and optional detail action above the collection toolbar. Empty
+parents stay in the selector. Apps bind authorized options and URL state; clearing
+record filters preserves the parent scope. Parent details belong on their detail
+page, not in repeated panels surrounding identical child tables.
+
+`BreakdownTable` owns its responsive comparison layout: identity and value stay
+in the main row; share moves into a labeled detail row when space is tight.
+Its caption names the table. Callers supply data and labels, not column-hiding CSS.
+
+### Record action menus
+
+`ActionMenu` is the shared three-dot composition of `Button` and `DropdownMenu`:
+a ghost icon trigger, horizontal ellipsis, and end-aligned popup. It inherits the
+menu's glass, elevation, motion, keyboard behavior, and focus return. Supply
+`label` as a localized, record-specific accessible name; `triggerId` supports
+focus return from an app-owned confirmation, and `children` supplies menu items.
+Apps own action selection, permission, placement, and confirmation. Reuse this
+composition instead of drawing another trigger or popup.
 
 ## Status Vocabulary
 
@@ -121,12 +149,15 @@ fundamental `Card` with explicit `visual`, `name`, `job`, `status`, `meta`,
 and `action` slots and owns presentation only; when it is the page identity,
 the `name` slot carries the page's `h1`. The app owns Agent data, recipe
 assignment, status grammar, routing, and actions; it assigns a recipe
-explicitly and never infers or randomizes one from a free-form role, and an
-Agent that is a recognizable content object renders through `AgentCard`. There is no `AgentGlyph`,
+explicitly and never infers or randomizes one from a free-form role.
+When the product chooses a card presentation, use `AgentCard`; registry cells,
+membership rows, and compact detail headers compose the shared `AgentVisual`
+within the structure their reading task requires. An Agent's presence does not
+by itself choose a card layout. There is no `AgentGlyph`,
 `AgentRow`, `KpiCard`, or product-domain `agent` object prop in the shared
 package.
 
-- **Standard components, not app-owned product features.** This package ships primitives, standard UI components, assistant-ui compositions, brand adapters, React adapters, reusable sections, and presentational product components. It must not ship app-specific feature/use-case screens or names such as operator-login, portal activation, customer credential control, or customer management. Generic data tables, command palettes, and chart cards are app-owned shadcn registry adaptations. The source-backed `chart-*` package surface is the plan-approved exception per issue #166; chart cards remain app-owned. Every data-shaped chart exposes an equivalent non-visual data alternative. A component whose complete value is already available in visible text or `aria-valuetext` does not add a redundant table.
+- **Standard components, not app-owned product features.** This package ships primitives, standard UI components, assistant-ui compositions, brand adapters, React adapters, reusable sections, and presentational product components. It must not ship app-specific feature/use-case screens or names such as operator-login, portal activation, customer credential control, or customer management. Domain registries, command search providers, and chart dashboards bind app data and routes in the app; that binding is not a reason to copy reusable presentation. Portal's DataTable owns its Next.js query and registry protocol once, while consuming the shared UI foundation. Product-independent compositions belong here with a real consumer. The source-backed `chart-*` package surface is the plan-approved exception per issue #166; apps select charts and bind their titles, data, and navigation. Every data-shaped chart exposes an equivalent non-visual data alternative. A component whose complete value is already available in visible text or `aria-valuetext` does not add a redundant table.
 - **Auth routes are consumer-owned shadcn block work.** Login, signup, OTP, two-factor, magic-link, and provider-button flows start from the selected shadcn block/example in the consuming app, with app-owned Better Auth behavior. Do not ship generic auth, signup, OTP, federated-login, or provider abstractions from this package unless a later explicit boundary decision replaces the selected shadcn block.
 - **Reusable sections and compositions live here after proof.** Bento grids, media mounts, demo surfaces, page frames, section intros, CTA bands, proof slots, benefits grids, generic shells, and homepage/use-case sections belong in `@nadicodeai/ui` when a second concrete consumer, a plan-approved shared component, or a named validation slice proves the package boundary. Website, portal, and sibling Nadia routes pass data and media children into existing compositions instead of rebuilding layout locally.
 - **Brand renderers live here for React consumers.** Logo geometry, asset generation, and usage semantics are owned by [`packages/design-system/DESIGN.md`, "Brand media authority"](../../design-system/DESIGN.md#brand-media-authority). `BrandLockup` supplies the approved horizontal lockup. `BrandMark` serves tight spaces and `BrandWordmark` serves placements where the name must read by itself. All three render the package's public neutral geometry seam with React-scoped SVG ids, dynamic theme paint, and accessible names. Consuming routes use these adapters; they never import raw logo assets, draw brand SVG inline, mask or recolor assets, or create another lockup rule.
@@ -135,17 +166,57 @@ package.
 
 ## Accessibility Invariant
 
-**Tier-1 accessibility is tested, browser-free.** Every rendering component test uses the package `expectAccessible` helper; the coverage guard derives the applicable test set and fails omissions. The jsdom tier is structural: rendered contrast, landmark context, focus, and keyboard behavior belong to real-browser Playwright coverage. The shared library ESLint configuration is the executable authority for static JSX accessibility rules, and the repository quality doctrine owns their policy; this contract does not copy the rule inventory.
+**Tier-1 accessibility is tested, browser-free.** Rendering component tests use the package `expectAccessible` helper to check the rendered DOM. The jsdom tier is structural: rendered contrast, landmark context, focus, and keyboard behavior belong to real-browser Playwright coverage. The shared library ESLint configuration is the executable authority for static JSX accessibility rules, and the repository quality doctrine owns their policy; this contract does not copy the rule inventory.
 
 ## Reusable Sections
 
 The source tree, barrels, and package exports own the current reusable section vocabulary. When a page needs a variation, extend the owning source component with a small typed prop or slot; do not fork the layout in a consumer or document a second component inventory here.
 
+`KpiStatGroup` owns the metric strip, responsive tiles, and link treatment; `KpiStat` owns its value, note, delta, and decorative trend. Apps supply metrics and bind links through `render`. Time-series charts expose `size`; their lightweight layout module also sizes deferred placeholders, so consumers never select internal chart elements.
+
+`CollectionToolbar` owns the collection-control layout: compact filters at the
+leading edge, a flexible search field, and trailing actions. Its slot order is
+also the reading and focus order, including when controls wrap. Consumers supply
+existing controls and own their query state; they do not set independent search
+widths or align filters to table columns. `CollectionFilters` owns the controlled
+field/value picker and applied-filter chips; callers supply options, localized
+copy, and callbacks. The component owns discovery, edit/remove, keyboard focus,
+and empty search results. It does not own routing or fetch state.
+
+`SettingsFactsSection` owns a named record or settings reading section: its
+heading and optional action, header separator, and bounded responsive fact
+cells in two equal columns, stacked on compact screens. Consumers supply labels,
+values, an optional contextual footer, and a Card surface; paragraph facts take a full row. The stable heading remains a programmatic focus target
+when an editor closes. Keep fact labels, order, and cells stable when data is
+missing: null and undefined values use the required localized
+`missingValueLabel`, while zero remains a value. Consumers do not filter out
+unknown facts or replace them with indefinite loading skeletons. Editable
+controls remain in `SettingsSection`.
+
+`SettingsSection` composes Card's named header, divider, FieldGroup body, and
+optional divided `footer` for local save actions and feedback. The caller owns
+the form transaction and controls; the section owns their shared geometry.
+Header `actions` are optional supporting commands, distinct from footer submission.
+`SettingsField` uses one render callback in server and client components. Spread
+its `controlProps` onto the control to retain the visible label, descriptions,
+error association, and disabled/required state; do not wire another copy by hand.
+
+`TableDetailRow` keeps supporting collection facts readable at compact widths
+inside a native full-width table cell. It shares the owning column labels and
+values rather than requiring another responsive cell implementation. Identity
+and status retain their column headers. Missing values retain their place.
+`Table compactDetails` and `TableDetailRow layout` share `tableCompactLayouts`:
+`standard` retains full columns at 768px of container width, `wide` at 1024px,
+and `spacious` at 1152px for schemas with additional operational columns.
+The same owner switches column visibility, detail visibility, and row boundaries.
+Two supporting facts use two columns; additional facts can use three when they fit.
+The cell renderer supplies the value, leaving the label to the detail row.
+
 ## Consumer Boundary
 
 Consumers own routing, auth, app data, server actions, runtime construction and adapters, permission decisions, analytics, and app-specific copy. The package owns reusable React presentation and the public Agent UI dependency boundary. Agent state and behavior come through the Agents interface; non-React and TUI contracts belong to their consuming products.
 
-App source composes layout, data, behavior, and semantic content around package components. It does not restyle an imported component root: appearance changes enter through the component's typed variant or are added to the owning package component. App `className` values on package components are limited to structural layout and sizing. App source uses semantic roles such as `bg-background` and `text-foreground`; canonical `nc-*` color utilities stay behind package-owned primitives such as `BrandField`. Raw Tailwind palette colors are not available to anyone: the generated theme clears the `--color-*` namespace, so `bg-red-500` produces no CSS and `better-tailwindcss/no-unknown-classes` reports it. Visible controls come from `@nadicodeai/ui`, while hidden inputs remain valid form transport. The root ESLint rules `nadicodeai/no-shadcn-appearance-override` and `nadicodeai/no-native-visible-control` enforce the rest of this boundary; each takes a `packageOwnedPrimitives` option (`"exempt"` by default, `"lint"` to hold this package's own source to the same rule).
+App source composes layout, data, behavior, and semantic content around package components. It does not restyle an imported component root: appearance changes enter through the component's typed variant or are added to the owning package component. App `className` values on package components arrange and size the component root. Descendant `data-slot` selectors are not a public styling API; internal spacing, type, and sizing belong to the shared component, enforced by `nadicodeai/no-shadcn-appearance-override`. App source uses semantic roles such as `bg-background` and `text-foreground`; canonical `nc-*` color utilities stay behind package-owned primitives such as `BrandField`. Raw Tailwind palette colors are not available to anyone: the generated theme clears the `--color-*` namespace, so `bg-red-500` produces no CSS and `better-tailwindcss/no-unknown-classes` reports it. Visible controls come from `@nadicodeai/ui`, while hidden inputs remain valid form transport. The root ESLint rules `nadicodeai/no-shadcn-appearance-override` and `nadicodeai/no-native-visible-control` enforce the rest of this boundary; each takes a `packageOwnedPrimitives` option (`"exempt"` by default, `"lint"` to hold this package's own source to the same rule).
 
 When this package is read from an installed npm package, follow the [consumer setup guide](consuming-cross-repo.md) for setup and public import paths. The styling invariant above remains the authority for component implementation.
 

package/docs/product-compositions.md

@@ -1,13 +1,10 @@
 # Product Compositions
 
-U4 adds the first shared product compositions for NadicodeAI admin, settings, and agent-work surfaces. These components are presentational only: consumers own routing, persistence, server actions, mutations, analytics, auth providers, permissions, and product-specific page copy.
+Shared product compositions own repeatable presentation and interaction. Consumers bind routing, persistence, permissions, and product copy. See the [component contract](contract.md) for each family's ownership.
 
-When first-party shadcn or assistant-ui registry source already covers the same
-generic product UI, use that registry item in the consuming app instead of
-adding a parallel NadicodeAI package API. Data tables, command palettes, and
-chart cards follow this rule: use `@shadcn/data-table-demo`,
-`@shadcn/command-dialog`, `@shadcn/chart`, or the relevant `@shadcn/chart-*`
-block/example as the source of truth.
+Check first-party shadcn or assistant-ui registry patterns before adding a
+composition. Once adapted, reuse its maintained owner; do not assemble the same
+registry example again for each page.
 
 Import components through the wildcard component subpath after build:
 
@@ -19,12 +16,13 @@ Fixtures live in:
 
 - [`../tests/guards/product-compositions.test.ts`](../tests/guards/product-compositions.test.ts)
 - [`../tests/guards/product-compositions-ssr.test.ts`](../tests/guards/product-compositions-ssr.test.ts)
+- [`../src/components/settings-section.test.tsx`](../src/components/settings-section.test.tsx)
 
 ## Boundaries
 
 | Component | Package owns | Consumer owns |
 | --- | --- | --- |
-| `SettingsSection` / `SettingsField` | Horizontal settings layout, `Field` composition, labels, descriptions, errors, deterministic description and error ids, `data-invalid`, and render-prop control wiring. | Form state, validation rules, submission, persistence, settings taxonomy, save/cancel behavior, and explicit control wiring for element children. |
+| `SettingsSection` / `SettingsField` | Header, divided save footer, field layout, labels, descriptions, errors, and control associations. | Form state, validation, submission, persistence, settings taxonomy, and save/cancel behavior. |
 | `FeedbackState` | Shared empty, loading, saving, error, permission, offline, no-results, and fatal state presentation. | Recovery actions, retry behavior, permission escalation, app-specific state language. |
 
 ## SettingsSection
@@ -35,6 +33,7 @@ Use `SettingsSection` and `SettingsField` for horizontal settings rows that need
 <SettingsSection
   title="Workspace defaults"
   description="Shared defaults for agent work."
+  footer={<Button type="submit">Save</Button>}
 >
   <SettingsField
     id="review-window"
@@ -44,7 +43,7 @@ Use `SettingsSection` and `SettingsField` for horizontal settings rows that need
     invalid={Boolean(reviewWindowError)}
   >
     {({ controlProps }) => (
-      <input {...controlProps} value={reviewWindow} onChange={onReviewWindowChange} />
+      <Input {...controlProps} value={reviewWindow} onChange={onReviewWindowChange} />
     )}
   </SettingsField>
 </SettingsSection>
@@ -53,11 +52,15 @@ Use `SettingsSection` and `SettingsField` for horizontal settings rows that need
 | Prop | Purpose |
 | --- | --- |
 | `title` / `description` / `actions` | Section header content and right-side action slot. |
+| `footer` | Local Save/Cancel controls and completion feedback. The owning form wraps the section. |
 | `id` / `label` | Required field identity and accessible label. |
 | `description` / `error` / `invalid` | Field helper text, error text, and invalid state. |
-| `children` | A render function receives `controlProps` for the real control and requires a client-component consumer. An element child renders unchanged and must put an explicit `id` matching the field `id` on its control. |
+| `children` | A render function receives `controlProps` for the real control in server and client components. |
 
-Accessibility: `FieldLabel` uses the field `id` as `htmlFor`. The render-prop form passes `id`, `aria-invalid`, `aria-describedby`, `disabled`, and `required` to the consumer for placement on the real control. Functions cannot cross the React Server Component boundary, so this form requires a client-component consumer. Element children render unchanged; the consumer must put the matching `id` on the control and add `aria-describedby` when needed. Descriptions render with `${id}-description`, and errors render with `${id}-error`.
+Spread `controlProps` onto the real control. SettingsField invokes the callback
+before rendered children cross any client boundary; it does not forward the
+callback to a client component. The [contract](contract.md) owns the field's
+accessibility and state guarantees.
 
 ## FeedbackState
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nadicodeai/ui",
-  "version": "6.0.1",
+  "version": "6.1.0",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -70,7 +70,7 @@
     "@assistant-ui/react": "0.15.18",
     "@assistant-ui/react-markdown": "0.14.14",
     "@base-ui/react": "^1.8.0",
-    "@nadicodeai/design-system": "6.0.1",
+    "@nadicodeai/design-system": "6.1.0",
     "@paper-design/shaders": "0.0.80",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
@@ -106,6 +106,7 @@
     "@stryker-mutator/vitest-runner": "10.0.0",
     "@tailwindcss/postcss": "^4.3.3",
     "@testing-library/react": "^16.3.3",
+    "@testing-library/user-event": "^14.6.7",
     "@types/react": "19.2.18",
     "@types/react-dom": "19.2.7",
     "axe-core": "^4.13.0",