themelia-react-ui 2.0.0 → 2.0.1

package/docs/consumer-skill/examples/detail.tsx

@@ -1,12 +1,17 @@
+import { useState, type ReactNode } from 'react';
 import { Button } from 'themelia-react-ui/base/buttons';
 import { Card } from 'themelia-react-ui/base/cards';
-import { MetadataList } from 'themelia-react-ui/blocks/data-display';
+import { MetadataList } from 'themelia-react-ui/base/metadata-list';
+import { ConfirmDialog, useOverlayVisibility } from 'themelia-react-ui/features/overlays';
+import { Page, type PageHeaderAction } from 'themelia-react-ui/layout/page';
 import { Date, Email, Money, Value } from 'themelia-react-ui/primitives';
-import { Page } from 'themelia-react-ui/layout/page';
+import { Text } from 'themelia-react-ui/typography';
 
 export interface AccountDetailRecord {
   id: string; name: string; email: string | null;
   createdAt: string | null; balanceMinor: number | null; currency: string;
+  /** Shown as the one status badge beside the title. */
+  overdue?: boolean;
 }
 export interface AccountDetailProps {
   account: AccountDetailRecord;
@@ -14,21 +19,63 @@ export interface AccountDetailProps {
   onBack: () => void;
 }
 
-export function AccountDetail({ account, onEdit, onBack }: AccountDetailProps) {
+/** One framed subject for a drawer or dashboard: one quick control, no page chrome. */
+export function AccountDetail({ account, onEdit }: AccountDetailProps) {
   return <Card title={account.name} headerPlacement="frame"
-    headerAction={<Button tone="primary" onClick={() => onEdit(account.id)}>Edit account</Button>}
-    footerSlot={<Button tone="secondary" buttonStyle="outline" onClick={onBack}>Back to accounts</Button>}>
+    headerAction={<Button onClick={() => onEdit(account.id)}>Edit</Button>}>
     <AccountFacts account={account}/>
   </Card>;
 }
 
-/** A focused resource route: Page owns measure, gutters, identity and commands. */
-export function AccountDetailPage({account,onEdit,onBack}:AccountDetailProps) {
-  return <Page narrow header={{title:account.name,description:'Account details',onBack,
-    backLabel:'Back to accounts',primaryAction:{label:'Edit account',onClick:()=>onEdit(account.id)}}}>
-    <Card title="Contact and billing" headerPlacement="frame">
-      <AccountFacts account={account}/>
-    </Card>
+export type AccountSection = 'overview' | 'invoices' | 'activity';
+
+export interface AccountDetailPageProps extends AccountDetailProps {
+  section: AccountSection;
+  onSectionChange: (section: AccountSection) => void;
+  invoiceCount: number;
+  onSendStatement: (id: string) => void;
+  /** Reject on failure; the confirmation stays open and shows the error. */
+  onDelete: (id: string) => Promise<void>;
+  /** The app's invoice table or activity log for the other sections. */
+  children?: ReactNode;
+}
+
+/**
+ * A record route: Page owns the title, status, commands and section tabs.
+ * Commands carry roles, not colours; the header places them.
+ */
+export function AccountDetailPage({ account, onEdit, onBack, section, onSectionChange,
+  invoiceCount, onSendStatement, onDelete, children }: AccountDetailPageProps) {
+  const deletion = useOverlayVisibility();
+  const [error, setError] = useState<string>();
+  const commands: PageHeaderAction[] = [
+    { label: 'Send statement', onClick: () => onSendStatement(account.id) },
+    { label: 'Delete account', destructive: true, onClick: () => { setError(undefined); deletion.show(); } },
+  ];
+  return <Page header={{
+    title: account.name, onBack, backLabel: 'Back to accounts',
+    titleBadges: account.overdue ? [{ label: 'Overdue', tone: 'warning' }] : undefined,
+    primaryAction: { label: 'Edit account', onClick: () => onEdit(account.id) },
+    secondaryActions: commands,
+    tabs: {
+      label: 'Account sections', value: section,
+      onValueChange: id => onSectionChange(id as AccountSection),
+      items: [
+        { id: 'overview', label: 'Overview' },
+        { id: 'invoices', label: 'Invoices', badge: invoiceCount },
+        { id: 'activity', label: 'Activity' },
+      ],
+    },
+  }}>
+    {section === 'overview'
+      ? <Card title="Contact and billing" headerPlacement="frame"><AccountFacts account={account}/></Card>
+      : children}
+    <ConfirmDialog {...deletion.overlayProps} destructive
+      title={`Delete ${account.name}?`} description="This permanently removes the account."
+      onAsyncConfirm={() => onDelete(account.id)}
+      onError={() => setError('Deletion failed. The account is kept; retry or cancel.')}>
+      {error && <Text role="alert" type="error">{error}</Text>}
+    </ConfirmDialog>
   </Page>;
 }
 

package/docs/consumer-skill/examples/edit.tsx

@@ -53,7 +53,7 @@ export function AccountEdit({ initial, onSave, onCancel }: AccountEditProps) {
         {saved && <Text role="status">Account saved.</Text>}
         <Stack direction={{ base: 'vertical', sm: 'horizontal' }} gap="sm">
           <Button tone="primary" type="submit" loading={pending} strings={{ loading: 'Saving account…' }}>Save account</Button>
-          <Button type="button" tone="secondary" buttonStyle="outline" disabled={pending} onClick={onCancel}>Cancel edit</Button>
+          <Button type="button" disabled={pending} onClick={onCancel}>Cancel edit</Button>
         </Stack>
       </Stack>
     </form>

package/docs/consumer-skill/examples/receipt.tsx

@@ -1,5 +1,5 @@
 import { Receipt, ReceiptItems, type ReceiptLineItem } from 'themelia-react-ui/blocks/commerce/receipt';
-import { MetadataList } from 'themelia-react-ui/blocks/data-display';
+import { MetadataList } from 'themelia-react-ui/base/metadata-list';
 import { Money } from 'themelia-react-ui/primitives';
 import { Separator } from 'themelia-react-ui/base/display';
 import { Stack } from 'themelia-react-ui/base/structure';
@@ -13,7 +13,7 @@ export function PurchaseReceipt({ items, total, reference }: { items: readonly R
 			<Separator dashed />
 			<ReceiptItems items={items} currency="EUR" unit="minor" />
 			<Separator dashed />
-			<MetadataList layout="rows" items={[{ label: 'Total', value: <Money tag="div" className="block" amount={total} currency="EUR" unit="minor" weight="semibold" /> }]} />
+			<MetadataList layout="rows" valueAlign="end" items={[{ label: 'Total', value: <Money tag="div" className="block" amount={total} currency="EUR" unit="minor" weight="semibold" /> }]} />
 		</Stack>
 	</Receipt>;
 }

package/docs/consumer-skill/examples/scoped-directory.tsx

@@ -70,7 +70,7 @@ export function ScopedDirectory(props: ScopedDirectoryProps) {
           props.state.status === 'error' ? 'Contacts could not be loaded.' :
           props.filters.length ? 'No contacts match these criteria.' : 'No contacts in this business yet.'}
         emptyStateAction={props.state.status === 'error' ? <Stack gap="dense"><Text role="alert" type="error">{props.state.message}</Text>
-          <Button tone="secondary" buttonStyle="outline" onClick={props.onRetry}>Retry contacts</Button></Stack> : undefined}
+          <Button onClick={props.onRetry}>Retry contacts</Button></Stack> : undefined}
         rowActions={rowActions} />
     </FilterProvider>
   </Page>;

package/docs/consumer-skill/examples/website.tsx

@@ -43,7 +43,7 @@ export function WebsiteLandingPage({ title, description, actionLabel, actionHref
         <Heading tag="h2" size="2xl" id={servicesId}>{servicesTitle}</Heading>
         <Grid columns={{ base: 1, md: 2, lg: 3 }} gap="xl">
           {offers.map(offer => <Card key={offer.id} title={offer.title} description={offer.description}
-            footerSlot={<Button href={offer.href} tone="secondary" buttonStyle="outline">{offer.actionLabel}</Button>}>
+            footerSlot={<Button href={offer.href}>{offer.actionLabel}</Button>}>
             <Stack gap="dense">
               <Money {...offer.price} locale={locale} align="left" weight="semibold" />
               <Text type="secondary" size="xs">{offer.priceNote}</Text>

package/docs/consumer-skill/references/agents-md.md

@@ -0,0 +1,33 @@
+# Project instructions block
+
+Agents load a skill only when they decide to, and often never open it. Paste this
+block into the consuming app's `AGENTS.md`, which Codex, Cursor, Copilot and
+Claude Code read; in a project that has only `CLAUDE.md`, paste it there. It
+points agents at this installed skill and states when UI work is done.
+
+```md
+<!-- themelia-react-ui:start 2.0.1 -->
+## UI built with themelia-react-ui
+Before writing UI, read node_modules/themelia-react-ui/docs/consumer-skill/SKILL.md and the
+installed declarations; prefer them over memory. Find the owner for a task with:
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/find-components.mjs <task nouns>
+Rules: one Page per route, whose title is the h1. Commands go in header.primaryAction
+(one) and ordered header.secondaryActions; destructive ones confirm with ConfirmDialog.
+A record's sections go in header.tabs. Space siblings with Stack/Grid gap; write copy
+with Heading/Text and values with Money/Date/Number; use semantic colors; badges stay
+neutral unless they state status; dialogs come only from themelia-react-ui/features/overlays.
+Done means: node node_modules/themelia-react-ui/docs/consumer-skill/scripts/check-composition.mjs <changed files>
+reports no errors (fix and re-run, at most three rounds), then the app's typecheck, lint
+and tests pass. Hand back each check as run or not run, and every kept warning with
+file:line and its reason.
+<!-- themelia-react-ui:end -->
+```
+
+- Keep the block between its markers and replace all of it after an upgrade. The
+  start marker records the package version it was generated for; app rules belong
+  outside the markers.
+- It names only the Node scripts that ship in `docs/consumer-skill/scripts`, so
+  every agent can run them without a plugin, MCP server or global CLI.
+- The done condition is the agent's, not the build's: app CI can stay
+  non-blocking on checker warnings. See [review](review.md#done-means) for the
+  hand-back and the checker's coverage.

package/docs/consumer-skill/references/analytics.md

@@ -15,7 +15,7 @@ application data and never fetch or define a business metric.
 | Current versus previous metric | `MetricComparison` from `themelia-react-ui/blocks/analytics` | Uses current/previous `MetricData`; app defines the comparison baseline. |
 | Used/limit quotas with shares, daily values and period selection | `UsageCard` from `themelia-react-ui/blocks/analytics/usage-card` | Owns a Card and ready/loading/error/empty presentation with retry/period callbacks. No optional chart peer. |
 | One plain label/value fact | `InlineStat` from `themelia-react-ui/blocks/data-display` | Card-free; app chooses whether this subject needs a Card. |
-| Several facts about one record | `MetadataList` from `themelia-react-ui/blocks/data-display` | Card-free; value primitives own formatting. |
+| Several facts about one record | `MetadataList` from `themelia-react-ui/base/metadata-list` | Card-free; value primitives own formatting. |
 | Caller-owned chart series | `ChartCard` from `themelia-react-ui/blocks/analytics` | Card-free chart composition; caller supplies chart content and an optional Card boundary. |
 
 Start with these subject owners before constructing a Card with a number and

package/docs/consumer-skill/references/composition.md

@@ -35,7 +35,12 @@ a detail workspace or a form; they need different information hierarchies.
 
 For a DataTable composition, put queries in `topbarContent`, exports or collection
 tools in `topbarEnd`, selection commands in `bulkActions`, and record commands
-in `rowActions`. Other arrangements are valid when the product has a distinct
+in `rowActions`. `bulkActions` render in the shared `BatchActionBar`, docked to
+the viewport while rows are selected (`selectionToolbarPlacement="inline"` keeps
+it in flow); they need no disabled state for an empty selection. Any other list
+with a selection mounts `BatchActionBar` from
+`themelia-react-ui/base/batch-action-bar` rather than a hand-built selection
+toolbar. Other arrangements are valid when the product has a distinct
 query region; choose one owner deliberately and keep queries close to their
 results. DataView already owns coordinated filtering; do not add a second filter
 store around it without inspecting its contract.
@@ -57,8 +62,10 @@ and CellStack where its smaller secondary-value contract fits.
 Commands need explicit importance as well as scope. Describe page commands by
 role in Page's header: `primaryAction` is the route's one main command, and
 `secondaryActions` lists supporting commands in priority order. The header owns
-their treatment: a solid primary button, outline secondary buttons, and a More
-actions menu for overflow, destructive commands and narrow screens. Choosing which
+their treatment and order: outline secondary buttons, the solid primary button,
+then a More actions menu for overflow, destructive commands and narrow screens,
+which always ends the row. WorkspaceRecordHeader, ResourceHeader, the resource
+shells and SettingsShell take the same props and render the same row. Choosing which
 command is primary, which are `destructive`, and which are `visible` remains an
 application decision; confirm destructive commands in their handler. Use
 `actions` only for non-command controls such as a period select. A back link,
@@ -75,6 +82,29 @@ export and destructive command should not all inherit the same visual emphasis.
 }}>{/* route content */}</Page>
 ```
 
+A record split into sections adds `header.tabs`. The tabs sit under the header's
+copy and commands, a `badge` shows a count, tabs that do not fit move into a More
+menu, and `onValueChange` switches the section or routes. Labels name the
+command; an icon on every command repeats it, so keep `+` on an add command and
+leave the others plain.
+
+```tsx
+<Page header={{
+  title: member.name,
+  titleBadges: [{ label: 'Needs attention', tone: 'warning' }],
+  primaryAction: { label: 'Generate report', onClick: onReport },
+  secondaryActions: [
+    { label: 'Update profile', onClick: onEdit },
+    { label: 'Record membership decision', onClick: onDecision },
+  ],
+  tabs: { value: section, onValueChange: setSection, items: [
+    { id: 'documents', label: 'Documents', badge: documents.length },
+    { id: 'hours', label: 'CPD hours', badge: hours },
+    { id: 'privacy', label: 'Privacy' },
+  ] },
+}}>{/* active section */}</Page>
+```
+
 | Drift | Better decision |
 | --- | --- |
 | Same parent named in header, context strip and fixed filter | One contextual lead; repeat only where it clarifies a separate task |
@@ -154,6 +184,13 @@ is appropriate only for inline content. The allowlist strips arbitrary styling,
 embedded media and unsafe links; it is not a Markdown parser or email-layout
 renderer. Keep outer width/padding on the surrounding structure. RichTextEditor
 owns editing; EmailComposer owns structured email/variable/delivery contracts.
+Images are opt-in on both: create one object with `useRichTextImages({ upload,
+renderImage })` from `features/rich-text-editor` and pass it as `images` to the
+editor and to RichText. Your `upload(file, { signal })` stores the file and
+resolves `{ src, alt?, width?, height? }`; the editor owns insertion, the upload
+placeholder, retry, alt text and the source policy (http, https, `blob:` and
+relative sources only), and `renderImage` draws read-only images with your
+component.
 Read the relevant declarations and [integration](integration.md) before choosing
 the content owner. Embedded React UI can opt out of reading rhythm through
 `not-typeset` or `data-not-typeset` on its subtree; those opt-outs do not bypass
@@ -200,6 +237,9 @@ should stay off: separate a card's sections with `contentGap` or a Stack gap
 clearly larger than the row gap (`2xl` between sections). UIProvider can configure
 `card.defaultHeaderDivider` and `card.defaultFooterDivider`; explicit per-card
 booleans win. Header/footer-only cards still render one shared divider.
+Overlays are the exception: `ActionDialog`, `ActionDrawer` and `ConfirmDialog`
+draw one rule between header, body and footer (one rule when there is no body),
+owned by the overlay; do not add borders to their content.
 
 Use titleSuffix for status/count/version badges. Long titles/suffixes wrap through the shared owner; no literal spaces/local margins to manufacture gaps. headerAction/actions are trailing controls, headerStart pre-title context. footerSlot/footer definitions own card-level actions; footerDivider owns the rule and inset. Do not simulate a footer inside children. SmartCard and ContentBlock are deprecated migration names; use Card in new code.
 
@@ -256,7 +296,7 @@ peer rhythm, and a horizontal Stack wraps footer actions. The app supplies the
 subjects and commands. For viewport-responsive columns use Grid; for available
 parent width use AdaptiveGrid or `TwoColumnLayout adaptTo="container"`.
 
-MetadataList owns medium-weight labels and normal-weight routine values. Its
+MetadataList owns semibold labels and normal-weight routine values. Its
 compact density tightens gaps/rows without shrinking primary values. Plain values
 and typed descriptors retain the shared roles; React nodes, `display` and `render`
 preserve supplied typography. Keep custom formatted values consistent with value
@@ -285,12 +325,14 @@ PopoverContent defaults to display/default; Command defaults to compact. An expl
 
 At shipped roots, compact shell padding is 8px; row inline padding is 12px; default row block padding is 8px and minimum height 36px. Compact/comfortable rows use 6/10px block padding and 32/40px minimum heights. Content can grow when it wraps. These are token-derived measurements, not app constants. Flush compact header/footer shell padding matches the list (8px inline). Header text bodies without a leading control and footer captions add the row inset once, aligning text at 20px. Actions keep the 8px shell edge. Nested public slots do not repeat these insets.
 
-Input frames use the input semantic token; collection dividers use border/60; focus uses ring separately. Equal responsibilities share recipes, while different semantic roles retain their own treatment. CommandInput keeps its existing onValueChange search contract and native refs; use the actual public Input through its default composition rather than restyling an unframed native field.
+Input frames and outline buttons share the input semantic token; collection dividers use border/60; focus uses ring separately and draws one indicator everywhere (a full-strength edge inside a soft halo). Equal responsibilities share recipes, while different semantic roles retain their own treatment. CommandInput keeps its existing onValueChange search contract and native refs; use the actual public Input through its default composition rather than restyling an unframed native field.
 
 ActionMenu density="table" remains a legacy table/overflow adapter. AsyncPreview padding="lg" owns a compatibility content boundary. Neither expands the default/compact surface vocabulary.
 
 Button separates tone from buttonStyle (solid, outline, ghost). ActionButtons renders the same definitions as ActionMenu. Badge tones describe actual states, not a decorative palette.
 
+Overflow menus use ActionMenu's own trigger: the ⋯ glyph named "More actions", context="inline" (default) for the ghost square in rows, cards and footers, context="commands" for the outline square beside outline commands. Pass buttonProps.size only to match the controls beside it; otherwise it follows the provider scale. Place the menu after the row's primary command and keep destructive entries last. Do not pass a MoreVertical icon, buttonStyle, tone or size-action classes to restyle it.
+
 ## Migration
 
 Use exact themelia-react-ui paths. Presentation imports use blocks/<family>, replacing composed/<family>. Raw UI, Radix, cmdk and routers are not consumer foundations. Read installed types instead of assuming historical CSS-kit props.
@@ -422,9 +464,10 @@ TwoColumnLayout. A wide comparison/directory can deliberately use `maxWidth="ful
 Setting full on every route defeats the resource measure. Do not remove Page's
 gutters to make its title touch the sidebar; align the header and body through
 the same Page. Density, container measure and page inset are separate choices.
-The [detail recipe](../examples/detail.tsx) includes `AccountDetailPage`: a
-centered resource measure, route-level commands, native Card icon/frame anatomy
-and MetadataList facts, with no duplicated subject header or gutter.
+The [detail recipe](../examples/detail.tsx) includes `AccountDetailPage`: the
+default record measure, a status badge, route-level commands and section tabs in
+the header, and MetadataList facts in one framed Card, with no duplicated subject
+header or gutter.
 
 Compose HeaderUserMenu in topbar `slots.headerEnd` or a local toolbar, and
 SidebarNavigationUser in AppSidebar `slots.footer` when account access belongs

package/docs/consumer-skill/references/design-contract.md

@@ -31,9 +31,17 @@ than rebuilding its accessible interaction behavior.
 | Action geometry and centered text | Button/IconButton/Badge recipes | Supported size/tone/style/variant |
 | Row labels, icons and selection indicators | Item and collection recipes | Supported row content, descriptions and density |
 | Semantic surfaces and states | Central theme and family state recipes | Theme foreground/surface pairs and supported tone/state props |
+| Hover, selection, current, pressed and disabled states | Shared interaction recipes: rows and selection use `--accent`, toggles hover with `--muted`, tables use a quieter muted ladder, disabled content dims to 50% | Theme `--accent`, `--muted` and `--card`; supported `active`, `selected`, `pressed` and `disabled` props |
+| Status tints | One tint scale per tone (wash, tint, edge, halo, line), contrast-tested with its ink | `tone` on Badge, Alert, IconBadge, StackedAvatars and toned blocks; the theme's tone colours |
+| Neutral regions, chips and elevation | One neutral strength per role (quiet wash, header band, track, chip) and one theme shadow per role (resting, card, raised, lifted, modal) | Theme `--muted`, `--foreground` and the `--shadow-*` ladder; supported surface variants |
 | Corners and elevation | Shared radius and theme shadow ladder | Theme roots and supported surface variants |
 | Presence, dismissal and focus | Base UI plus library overlay/motion owners | Public open/state/dismissal callbacks and library overlays |
 
+Restyle states through the theme roles so every family moves together: a
+darker `--accent` changes every row hover and selection at once. Passing
+`bg-success/15` or `hover:bg-muted/40` to one library row creates a second scale
+that the contrast contract does not test.
+
 An inset has one owner. A searchable menu needs the search region's outer inset
 and the Input's inner text inset; it does not need a third padded wrapper. A
 card-free block can be framed by a Card at its composition boundary.
@@ -96,9 +104,10 @@ a divider, or recolor a divider to simulate focus. Theme status colors keep thei
 foreground pairs; a status tone is not a decorative brand palette.
 
 Native fields, field-shaped triggers and compound field frames share the same
-focus and invalid treatment. Invalid state marks the frame and error copy;
-editable values keep their normal semantic foreground. Compound fields show one
-outer ring. Use validation and disabled/loading props instead of supplying a
+focus and invalid treatment. Every focused element draws one indicator: a 1px
+`ring` edge inside a soft 3px halo. Invalid state marks the frame and error copy
+(and tints the halo while focused); editable values keep their normal semantic
+foreground. Compound fields show one outer focus frame. Use validation and disabled/loading props instead of supplying a
 second local state recipe. Selected rows retain the owning primitive's indicator;
 highlighted, selected and destructive states are distinct responsibilities.
 

package/docs/consumer-skill/references/installation.md

@@ -47,7 +47,11 @@ if (fs.realpathSync(selectedSkill) !== fs.realpathSync(installedSkill)) {
   }
   compareAssets(installedSkill);
 }
-console.log(JSON.stringify({ package: manifest.name, version: manifest.version, root, skill: selectedSkill }, null, 2));
+// The app's project instructions block records the version it was pasted from.
+const instructions = ['AGENTS.md', 'CLAUDE.md'].find(file => fs.existsSync(file));
+const marker = instructions && fs.readFileSync(instructions, 'utf8').match(/<!-- themelia-react-ui:start (\S+) -->/);
+const agentsBlock = !marker ? 'missing' : marker[1] === manifest.version ? 'current' : `stale (${marker[1]})`;
+console.log(JSON.stringify({ package: manifest.name, version: manifest.version, root, skill: selectedSkill, agentsBlock }, null, 2));
 JS
 ```
 
@@ -64,6 +68,12 @@ files or publisher markers in the copy are not checked. Keep local product polic
 outside the package guidance. Recopy the complete folder after upgrades, and
 read declarations from the installed package.
 
+`agentsBlock` reports whether the app's `AGENTS.md` (or `CLAUDE.md`) carries the
+[project instructions block](agents-md.md) for the installed version: `missing`,
+`current` or `stale` with the version it was pasted from. Paste or replace the
+whole block between its markers; it is how agents that never open a skill still
+find this one and its done condition.
+
 ## Upgrading to the neutral button default
 
 An untoned `Button` is now the neutral outline (`tone="secondary"`,