themelia-react-ui 1.0.2 → 2.0.0

package/dist/workspace-YoFjXi6i.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-YoFjXi6i.js","names":["Icon","React","_Fragment","DisplayLabel","Heading","Text","Button","Stack","Progress","Value","SecondaryValue","Badge","ItemMedia","ItemDescription","ItemActions","ItemGroup","ItemContent","Item","ItemTitle","useLayoutLinkRenderer","React$1","Fragment$1","defaultWorkspaceRecordHeaderStrings","defaultWorkspaceNavStrings","value","defaultWorkspaceLocaleStripStrings","CONTENT_WIDTH_CLASS","STATUS_ICON","Check","Circle","CircleAlert","STATUS_CLASS","clampPercent","DynamicWorkspaceIcon","icon","getStatus","item","active","WorkspaceLayout","props","hasSidebar","sidebar","hasRail","rail","ariaLabel","cn","contentWidth","className","header","headerClassName","bodyClassName","sidebarClassName","mainClassName","contentClassName","railClassName","WorkspaceRecordHeader","stringsProp","strings","useStrings","hasMetadata","metadata","textGap","media","titleSlot","title","badges","status","description","index","actions","secondaryActions","headerEnd","WorkspaceNav","resolvedRenderLink","groups","group","activeId","StatusIcon","completion","handleSelect","context","renderItem","rowContent","itemClassName","linkNode","footerSlot","WorkspaceLocaleStrip","handleLocaleClick","locale","onLocaleChange","locales","activeLocale"],"sources":["../src/components/layout/workspace/workspace.strings.ts","../src/components/layout/workspace/workspace.tsx"],"sourcesContent":["export interface WorkspaceRecordHeaderStrings {\n\tmetadataLabel: string;\n\tactionsLabel: string;\n\tsecondaryActionsLabel: string;\n}\n\nexport const defaultWorkspaceRecordHeaderStrings: WorkspaceRecordHeaderStrings = {\n\tmetadataLabel: 'Record metadata',\n\tactionsLabel: 'Record actions',\n\tsecondaryActionsLabel: 'Secondary actions',\n};\n\nexport interface WorkspaceNavStrings {\n\tariaLabel: string;\n\tcompletionLabel: (value: number) => string;\n\tcurrentLabel: string;\n}\n\nexport const defaultWorkspaceNavStrings: WorkspaceNavStrings = {\n\tariaLabel: 'Workspace navigation',\n\tcompletionLabel: (value) => `${value}% complete`,\n\tcurrentLabel: 'Current',\n};\n\nexport interface WorkspaceLocaleStripStrings {\n\tariaLabel: string;\n\tactiveLabel: string;\n\tcompletionLabel: (value: number) => string;\n}\n\nexport const defaultWorkspaceLocaleStripStrings: WorkspaceLocaleStripStrings = {\n\tariaLabel: 'Workspace locales',\n\tactiveLabel: 'Active',\n\tcompletionLabel: (value) => `${value}% complete`,\n};\n","import * as React from 'react';\nimport {\n\tCheck,\n\tCircle,\n\tCircleAlert,\n\ttype LucideIcon,\n\t} from 'lucide-react';\n\nimport { Badge } from '../../base/badge';\nimport { Button } from '../../base/buttons';\nimport { Progress } from '../../base/feedback';\nimport {\n\tItem,\n\tItemActions,\n\tItemContent,\n\tItemDescription,\n\tItemGroup,\n\tItemMedia,\n\tItemTitle,\n} from '../../base/item';\nimport { Stack } from '../../base/structure';\nimport { SecondaryValue, Value } from '../../primitives';\nimport { DisplayLabel, Heading, Text } from '../../typography';\nimport { useStrings } from '../../../lib/strings';\nimport { cn } from '../../../lib/utils';\n\nimport { useLayoutLinkRenderer } from '../hooks';\nimport type { LayoutIconComponent } from '../layout.types';\nimport {\n\tdefaultWorkspaceLocaleStripStrings,\n\tdefaultWorkspaceNavStrings,\n\tdefaultWorkspaceRecordHeaderStrings,\n} from './workspace.strings';\nimport type {\n\tWorkspaceContentWidth,\n\tWorkspaceLayoutProps,\n\tWorkspaceLocaleItem,\n\tWorkspaceLocaleStripProps,\n\tWorkspaceNavItem,\n\tWorkspaceNavItemStatus,\n\tWorkspaceNavProps,\n\tWorkspaceRecordHeaderProps,\n} from './workspace.types';\n\nconst CONTENT_WIDTH_CLASS: Record<WorkspaceContentWidth, string> = {\n\tdefault: '[--workspace-content-max-width:58rem]',\n\twide: '[--workspace-content-max-width:86rem]',\n\tfull: '[--workspace-content-max-width:none]',\n};\n\nconst STATUS_ICON: Record<WorkspaceNavItemStatus, LucideIcon> = {\n\tcomplete: Check,\n\tcurrent: Circle,\n\tattention: CircleAlert,\n\tdisabled: Circle,\n\tidle: Circle,\n};\n\nconst STATUS_CLASS: Record<WorkspaceNavItemStatus, string> = {\n\tcomplete: 'text-success',\n\tcurrent: 'text-primary-accent',\n\tattention: 'text-warning-accent',\n\tdisabled: 'text-muted-foreground/40',\n\tidle: 'text-muted-foreground',\n};\n\nfunction clampPercent(value: number): number {\n\tif (!Number.isFinite(value)) return 0;\n\treturn Math.min(100, Math.max(0, Math.round(value)));\n}\n\nfunction DynamicWorkspaceIcon({\n\ticon,\n\tclassName,\n}: {\n\t/** Leading glyph. */\n\ticon?: LayoutIconComponent;\n\tclassName?: string;\n}) {\n\tif (!icon) return null;\n\tconst Icon = icon;\n\treturn <Icon className={className} aria-hidden=\"true\" />;\n}\n\nfunction getStatus(item: WorkspaceNavItem, active: boolean): WorkspaceNavItemStatus {\n\tif (item.disabled) return 'disabled';\n\tif (item.status) return item.status;\n\tif (item.warning) return 'attention';\n\tif (active) return 'current';\n\tif (item.completion !== undefined && clampPercent(item.completion) >= 100) return 'complete';\n\treturn 'idle';\n}\n\nexport const WorkspaceLayout = React.forwardRef<HTMLDivElement, WorkspaceLayoutProps>(function WorkspaceLayout({\n\theader,\n\tsidebar,\n\trail,\n\tchildren,\n\tcontentWidth = 'wide',\n\tclassName,\n\theaderClassName,\n\tbodyClassName,\n\tsidebarClassName,\n\tmainClassName,\n\tcontentClassName,\n\trailClassName,\n\tariaLabel,\n\tstyle,\n\t...props\n}, ref) {\n\tconst hasSidebar = !!sidebar;\n\tconst hasRail = !!rail;\n\n\treturn (\n\t\t<div\n\t\t\tref={ref}\n\t\t\taria-label={ariaLabel}\n\t\t\tclassName={cn(\n\t\t\t\t'workspace-layout--component @container/workspace-layout flex h-full min-h-0 w-full flex-col overflow-y-auto overscroll-contain rounded-radius border border-border bg-background text-foreground',\n\t\t\t\t'[--workspace-sidebar-width:16rem] [--workspace-rail-width:20rem]',\n\t\t\t\tCONTENT_WIDTH_CLASS[contentWidth],\n\t\t\t\tclassName,\n\t\t\t)}\n\t\t\tstyle={style}\n\t\t\t{...props}\n\t\t>\n\t\t\t{!!header && (\n\t\t\t\t<header className={cn('workspace-layout--header shrink-0 border-b border-border bg-background', headerClassName)}>\n\t\t\t\t\t{header}\n\t\t\t\t</header>\n\t\t\t)}\n\t\t\t<div\n\t\t\t\tclassName={cn(\n\t\t\t\t\t'workspace-layout--body grid min-h-0 flex-none grid-cols-1 bg-muted/20 @min-[80rem]/workspace-layout:flex-1',\n\t\t\t\t\thasSidebar && !hasRail && '@min-[80rem]/workspace-layout:grid-cols-[var(--workspace-sidebar-width)_minmax(0,1fr)]',\n\t\t\t\t\thasSidebar && hasRail && '@min-[80rem]/workspace-layout:grid-cols-[var(--workspace-sidebar-width)_minmax(0,1fr)] @min-[96rem]/workspace-layout:grid-cols-[var(--workspace-sidebar-width)_minmax(0,1fr)_var(--workspace-rail-width)]',\n\t\t\t\t\t!hasSidebar && hasRail && '@min-[96rem]/workspace-layout:grid-cols-[minmax(0,1fr)_var(--workspace-rail-width)]',\n\t\t\t\t\tbodyClassName,\n\t\t\t\t)}\n\t\t\t>\n\t\t\t\t{!!hasSidebar && (\n\t\t\t\t\t<aside\n\t\t\t\t\t\tclassName={cn(\n\t\t\t\t\t\t\t'workspace-layout--sidebar hidden min-h-0 border-r border-border bg-background @min-[80rem]/workspace-layout:block',\n\t\t\t\t\t\t\tsidebarClassName,\n\t\t\t\t\t\t)}\n\t\t\t\t\t>\n\t\t\t\t\t\t<div className=\"h-full overflow-y-auto overscroll-contain p-space-lg\">\n\t\t\t\t\t\t\t{sidebar}\n\t\t\t\t\t\t</div>\n\t\t\t\t\t</aside>\n\t\t\t\t)}\n\t\t\t\t<main\n\t\t\t\t\ttabIndex={0}\n\t\t\t\t\tclassName={cn(\n\t\t\t\t\t\t\t'workspace-layout--main min-h-0 min-w-0 overflow-visible @min-[80rem]/workspace-layout:overflow-y-auto overscroll-contain focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset',\n\t\t\t\t\t\tmainClassName,\n\t\t\t\t\t)}\n\t\t\t\t>\n\t\t\t\t\t<div\n\t\t\t\t\t\tclassName={cn(\n\t\t\t\t\t\t\t'workspace-layout--content box-border mx-auto flex min-h-full w-full max-w-[var(--workspace-content-max-width)] flex-col gap-space-xl p-surface-lg',\n\t\t\t\t\t\t\tcontentWidth === 'full' && 'max-w-none',\n\t\t\t\t\t\t\tcontentClassName,\n\t\t\t\t\t\t)}\n\t\t\t\t\t>\n\t\t\t\t\t\t{children}\n\t\t\t\t\t</div>\n\t\t\t\t</main>\n\t\t\t\t{!!hasRail && (\n\t\t\t\t\t<aside\n\t\t\t\t\t\tclassName={cn(\n\t\t\t\t\t\t\t'workspace-layout--rail hidden min-h-0 border-l border-border bg-background @min-[96rem]/workspace-layout:block',\n\t\t\t\t\t\t\trailClassName,\n\t\t\t\t\t\t)}\n\t\t\t\t\t>\n\t\t\t\t\t\t<div className=\"h-full overflow-y-auto overscroll-contain p-space-lg\">\n\t\t\t\t\t\t\t{rail}\n\t\t\t\t\t\t</div>\n\t\t\t\t\t</aside>\n\t\t\t\t)}\n\t\t\t</div>\n\t\t</div>\n\t);\n});\n\nWorkspaceLayout.displayName = 'WorkspaceLayout';\n\nexport const WorkspaceRecordHeader = React.forwardRef<HTMLDivElement, WorkspaceRecordHeaderProps>(function WorkspaceRecordHeader({\n\ttitle,\n\tdescription,\n\ttextGap = 'dense',\n\tbadges,\n\tmetadata,\n\tactions,\n\tsecondaryActions,\n\tstatus,\n\tmedia,\n\theaderEnd,\n\ttitleSlot,\n\tclassName,\n\tstrings: stringsProp,\n\t...props\n}, ref) {\n\tconst strings = useStrings(defaultWorkspaceRecordHeaderStrings, stringsProp);\n\tconst hasMetadata = !!metadata?.length;\n\n\treturn (\n\t\t<Stack\n\t\t\tref={ref}\n\t\t\tdirection=\"horizontal\"\n\t\t\tgap=\"xl\"\n\t\t\talign=\"start\"\n\t\t\tjustify=\"between\"\n\t\t\twrap\n\t\t\tclassName={cn(\n\t\t\t\t'workspace-record-header--component p-surface-lg',\n\t\t\t\tclassName,\n\t\t\t)}\n\t\t\t{...props}\n\t\t>\n\t\t\t\t<Stack gap={textGap} className=\"workspace-record-header--identity min-w-0 max-w-full flex-1 basis-64\">\n\t\t\t\t\t<Stack direction=\"horizontal\" gap=\"lg\" align=\"center\" wrap={false}>\n\t\t\t\t{!!media && (\n\t\t\t\t\t<div className=\"workspace-record-header--media flex size-12 shrink-0 items-center justify-center overflow-hidden rounded-inner border border-border bg-muted/40\">\n\t\t\t\t\t\t{media}\n\t\t\t\t\t</div>\n\t\t\t\t)}\n\t\t\t\t\t\t<Stack direction=\"horizontal\" gap=\"md\" className=\"workspace-record-header--title-row min-w-0 flex-1\">\n\t\t\t\t\t\t{titleSlot ?? (\n\t\t\t\t\t\t\t<Heading tag=\"h4\" className=\"[overflow-wrap:anywhere]\">\n\t\t\t\t\t\t\t\t{title}\n\t\t\t\t\t\t\t</Heading>\n\t\t\t\t\t\t)}\n\t\t\t\t\t\t\t{!!badges && <Stack direction=\"horizontal\" wrap align=\"center\" gap=\"sm\" className=\"workspace-record-header--badges\">{badges}</Stack>}\n\t\t\t\t\t\t\t{!!status && <div className=\"workspace-record-header--status\">{status}</div>}\n\t\t\t\t\t\t</Stack>\n\t\t\t\t\t</Stack>\n\t\t\t\t\t{!!description && (\n\t\t\t\t\t\t<Text type=\"secondary\" className=\"workspace-record-header--description max-w-4xl leading-relaxed\">\n\t\t\t\t\t\t\t{description}\n\t\t\t\t\t\t</Text>\n\t\t\t\t\t)}\n\t\t\t\t\t{!!hasMetadata && (\n\t\t\t\t\t\t<div\n\t\t\t\t\t\t\taria-label={strings.metadataLabel}\n\t\t\t\t\t\t\tclassName=\"workspace-record-header--metadata flex flex-wrap items-center gap-x-space-xl gap-y-space-xs\"\n\t\t\t\t\t\t>\n\t\t\t\t\t\t\t{metadata.map((item, index) => (\n\t\t\t\t\t\t\t\t<div key={item.id ?? index} className=\"flex items-baseline gap-space-sm\">\n\t\t\t\t\t\t\t\t\t<DisplayLabel>\n\t\t\t\t\t\t\t\t\t\t{item.label}\n\t\t\t\t\t\t\t\t\t</DisplayLabel>\n\t\t\t\t\t\t\t\t\t<Value className=\"tabular-nums\">\n\t\t\t\t\t\t\t\t\t\t{item.value}\n\t\t\t\t\t\t\t\t\t</Value>\n\t\t\t\t\t\t\t\t\t</div>\n\t\t\t\t\t\t\t\t))}\n\t\t\t\t\t\t\t</div>\n\t\t\t\t\t)}\n\t\t\t\t</Stack>\n\t\t\t{!!(actions || secondaryActions || headerEnd) && (\n\t\t\t\t<div className=\"workspace-record-header--actions flex max-w-full shrink-0 flex-wrap items-center gap-space-md justify-end\">\n\t\t\t\t\t{!!secondaryActions && (\n\t\t\t\t\t\t<Stack direction=\"horizontal\" wrap align=\"center\" gap=\"sm\" aria-label={strings.secondaryActionsLabel}>\n\t\t\t\t\t\t\t{secondaryActions}\n\t\t\t\t\t\t</Stack>\n\t\t\t\t\t)}\n\t\t\t\t\t{!!actions && (\n\t\t\t\t\t\t<Stack direction=\"horizontal\" wrap align=\"center\" gap=\"sm\" aria-label={strings.actionsLabel}>\n\t\t\t\t\t\t\t{actions}\n\t\t\t\t\t\t</Stack>\n\t\t\t\t\t)}\n\t\t\t\t\t{!!headerEnd && <div className=\"workspace-record-header--end\">{headerEnd}</div>}\n\t\t\t\t</div>\n\t\t\t)}\n\t\t</Stack>\n\t);\n});\n\nWorkspaceRecordHeader.displayName = 'WorkspaceRecordHeader';\n\nexport const WorkspaceNav = React.forwardRef<HTMLElement, WorkspaceNavProps>(function WorkspaceNav({\n\tgroups,\n\tactiveId,\n\tonSelect,\n\trenderItem,\n\tfooterSlot,\n\trenderLink,\n\tclassName,\n\tstrings: stringsProp,\n\t...props\n}, ref) {\n\tconst strings = useStrings(defaultWorkspaceNavStrings, stringsProp);\n\tconst resolvedRenderLink = useLayoutLinkRenderer({ renderLink });\n\n\treturn (\n\t\t<Stack\n\t\t\trender={(\n\t\t\t\t<nav\n\t\t\t\t\tref={ref}\n\t\t\t\t\taria-label={props['aria-label'] ?? strings.ariaLabel}\n\t\t\t\t\t{...props}\n\t\t\t\t/>\n\t\t\t)}\n\t\t\tgap=\"xl\"\n\t\t\tclassName={cn('workspace-nav--component h-full', className)}\n\t\t>\n\t\t\t<Stack gap=\"xl\" className=\"workspace-nav--groups min-h-0 flex-1\">\n\t\t\t\t{groups.map((group) => (\n\t\t\t\t\t<Stack key={group.id} gap=\"md\" className=\"workspace-nav--group\">\n\t\t\t\t\t\t{!!group.label && (\n\t\t\t\t\t\t\t<Stack gap=\"dense\" className=\"workspace-nav--group-header px-space-xs\">\n\t\t\t\t\t\t\t\t<DisplayLabel>\n\t\t\t\t\t\t\t\t\t{group.label}\n\t\t\t\t\t\t\t\t</DisplayLabel>\n\t\t\t\t\t\t\t\t{!!group.description && (\n\t\t\t\t\t\t\t\t\t<Text size=\"xs\" type=\"secondary\">\n\t\t\t\t\t\t\t\t\t\t{group.description}\n\t\t\t\t\t\t\t\t\t</Text>\n\t\t\t\t\t\t\t\t)}\n\t\t\t\t\t\t\t</Stack>\n\t\t\t\t\t\t)}\n\t\t\t\t\t\t<ItemGroup className=\"workspace-nav--items gap-space-xs\">\n\t\t\t\t\t\t\t{group.items.map((item, index) => {\n\t\t\t\t\t\t\t\tconst active = item.id === activeId;\n\t\t\t\t\t\t\t\tconst status = getStatus(item, active);\n\t\t\t\t\t\t\t\tconst StatusIcon = STATUS_ICON[status];\n\t\t\t\t\t\t\t\tconst completion = item.completion === undefined ? undefined : clampPercent(item.completion);\n\t\t\t\t\t\t\t\tconst handleSelect = (event: React.MouseEvent<HTMLElement>) => {\n\t\t\t\t\t\t\t\t\tif (item.disabled) {\n\t\t\t\t\t\t\t\t\t\tevent.preventDefault();\n\t\t\t\t\t\t\t\t\t\treturn;\n\t\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t\t\tonSelect?.(item);\n\t\t\t\t\t\t\t\t};\n\t\t\t\t\t\t\t\tconst context = { active, group, index, onSelect: handleSelect };\n\n\t\t\t\t\t\t\t\tif (renderItem) {\n\t\t\t\t\t\t\t\t\treturn <React.Fragment key={item.id}>{renderItem(item, context)}</React.Fragment>;\n\t\t\t\t\t\t\t\t}\n\n\t\t\t\t\t\t\t\tconst rowContent = (\n\t\t\t\t\t\t\t\t\t<>\n\t\t\t\t\t\t\t\t\t\t<ItemMedia variant=\"icon\" className={cn(active && 'bg-primary/10 text-primary-accent')}>\n\t\t\t\t\t\t\t\t\t\t\t{item.icon ? (\n\t\t\t\t\t\t\t\t\t\t\t\t<DynamicWorkspaceIcon icon={item.icon} className=\"size-icon\" />\n\t\t\t\t\t\t\t\t\t\t\t) : (\n\t\t\t\t\t\t\t\t\t\t\t\t<StatusIcon className={cn('size-icon-md', STATUS_CLASS[status])} aria-hidden=\"true\" />\n\t\t\t\t\t\t\t\t\t\t\t)}\n\t\t\t\t\t\t\t\t\t\t</ItemMedia>\n\t\t\t\t\t\t\t\t\t\t<ItemContent>\n\t\t\t\t\t\t\t\t\t\t\t<div className=\"flex items-center gap-space-sm\">\n\t\t\t\t\t\t\t\t\t\t\t\t<ItemTitle>{item.label}</ItemTitle>\n\t\t\t\t\t\t\t\t\t\t\t\t{active && (\n\t\t\t\t\t\t\t\t\t\t\t<Text tag=\"span\" size=\"inherit\" className=\"sr-only\">{strings.currentLabel}</Text>\n\t\t\t\t\t\t\t\t\t\t\t\t)}\n\t\t\t\t\t\t\t\t\t\t\t</div>\n\t\t\t\t\t\t\t\t\t\t\t{!!item.description && <ItemDescription clamp={2}>{item.description}</ItemDescription>}\n\t\t\t\t\t\t\t\t\t\t\t{completion !== undefined && (\n\t\t\t\t\t\t\t\t\t\t\t\t<div className=\"mt-1.5 flex items-center gap-space-md\">\n\t\t\t\t\t\t\t\t\t\t\t<Progress\n\t\t\t\t\t\t\t\t\t\t\t\tvalue={completion}\n\t\t\t\t\t\t\t\t\t\t\t\tsize=\"sm\"\n\t\t\t\t\t\t\t\t\t\t\t\taria-label={strings.completionLabel(completion)}\n\t\t\t\t\t\t\t\t\t\t\t\tclassName=\"flex-1\"\n\t\t\t\t\t\t\t\t\t\t\t/>\n\t\t\t\t\t\t\t\t\t\t\t\t\t<SecondaryValue size=\"xs\" className=\"tabular-nums\">\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t{strings.completionLabel(completion)}\n\t\t\t\t\t\t\t\t\t\t\t\t\t</SecondaryValue>\n\t\t\t\t\t\t\t\t\t\t\t\t</div>\n\t\t\t\t\t\t\t\t\t\t\t)}\n\t\t\t\t\t\t\t\t\t\t</ItemContent>\n\t\t\t\t\t\t\t\t\t\t{!!item.badge && <ItemActions>{item.badge}</ItemActions>}\n\t\t\t\t\t\t\t\t\t</>\n\t\t\t\t\t\t\t\t);\n\n\t\t\t\t\t\t\t\tconst itemClassName = cn(\n\t\t\t\t\t\t\t\t\t'workspace-nav--item w-full border border-transparent px-row-x py-row-y text-left transition-colors',\n\t\t\t\t\t\t\t\t\tactive && 'border-primary/20 bg-primary/5',\n\t\t\t\t\t\t\t\t\titem.warning && !active && 'border-warning/30 bg-warning/5',\n\t\t\t\t\t\t\t\t\titem.disabled && 'pointer-events-none opacity-50',\n\t\t\t\t\t\t\t\t);\n\n\t\t\t\t\t\t\t\tif (item.href) {\n\t\t\t\t\t\t\t\t\tconst linkNode = resolvedRenderLink({\n\t\t\t\t\t\t\t\t\t\thref: item.href,\n\t\t\t\t\t\t\t\t\t\tchildren: rowContent,\n\t\t\t\t\t\t\t\t\t\tclassName: 'block',\n\t\t\t\t\t\t\t\t\t\tactive,\n\t\t\t\t\t\t\t\t\t\tdisabled: item.disabled,\n\t\t\t\t\t\t\t\t\t\texternal: item.external,\n\t\t\t\t\t\t\t\t\t\ttarget: item.target,\n\t\t\t\t\t\t\t\t\t\trel: item.rel,\n\t\t\t\t\t\t\t\t\t\tonClick: handleSelect as React.MouseEventHandler<HTMLAnchorElement>,\n\t\t\t\t\t\t\t\t\t});\n\t\t\t\t\t\t\t\t\treturn (\n\t\t\t\t\t\t\t\t\t\t<Item key={item.id} size=\"md\" render={linkNode as React.ReactElement} className={itemClassName}>\n\t\t\t\t\t\t\t\t\t\t\t{rowContent}\n\t\t\t\t\t\t\t\t\t\t</Item>\n\t\t\t\t\t\t\t\t\t);\n\t\t\t\t\t\t\t\t}\n\n\t\t\t\t\t\t\t\treturn (\n\t\t\t\t\t\t\t\t\t<Item\n\t\t\t\t\t\t\t\t\t\tkey={item.id}\n\t\t\t\t\t\t\t\t\t\tsize=\"md\"\n\t\t\t\t\t\t\t\t\t\trender={<button type=\"button\" onClick={handleSelect} disabled={item.disabled} />}\n\t\t\t\t\t\t\t\t\t\tclassName={itemClassName}\n\t\t\t\t\t\t\t\t\t>\n\t\t\t\t\t\t\t\t\t\t{rowContent}\n\t\t\t\t\t\t\t\t\t</Item>\n\t\t\t\t\t\t\t\t);\n\t\t\t\t\t\t\t})}\n\t\t\t\t\t\t</ItemGroup>\n\t\t\t\t\t</Stack>\n\t\t\t\t))}\n\t\t\t</Stack>\n\t\t\t{!!footerSlot && <div className=\"workspace-nav--footer shrink-0 border-t border-border pt-space-lg\">{footerSlot}</div>}\n\t\t</Stack>\n\t);\n});\n\nWorkspaceNav.displayName = 'WorkspaceNav';\n\nexport const WorkspaceLocaleStrip = React.forwardRef<HTMLDivElement, WorkspaceLocaleStripProps>(function WorkspaceLocaleStrip({\n\tlocales,\n\tactiveLocale,\n\tonLocaleChange,\n\tactions,\n\tstatus,\n\tclassName,\n\tstrings: stringsProp,\n\t...props\n}, ref) {\n\tconst strings = useStrings(defaultWorkspaceLocaleStripStrings, stringsProp);\n\n\tconst handleLocaleClick = (locale: WorkspaceLocaleItem) => {\n\t\tif (locale.disabled) return;\n\t\tonLocaleChange?.(locale);\n\t};\n\n\treturn (\n\t\t<div\n\t\t\tref={ref}\n\t\t\tclassName={cn('workspace-locale-strip--component flex flex-col gap-space-lg border-t border-border bg-muted/20 px-surface-lg py-surface min-[64rem]:flex-row min-[64rem]:items-center min-[64rem]:justify-between', className)}\n\t\t\t{...props}\n\t\t>\n\t\t\t<Stack direction=\"horizontal\" wrap align=\"center\" gap=\"md\" className=\"workspace-locale-strip--locales min-w-0\" role=\"group\" aria-label={strings.ariaLabel}>\n\t\t\t\t{locales.map((locale) => {\n\t\t\t\t\tconst active = locale.id === activeLocale;\n\t\t\t\t\tconst completion = locale.completion === undefined ? undefined : clampPercent(locale.completion);\n\t\t\t\t\treturn (\n\t\t\t\t\t\t<Button\n\t\t\t\t\t\t\tkey={locale.id}\n\t\t\t\t\t\t\ttype=\"button\"\n\t\t\t\t\t\t\ttone={active ? 'primary' : 'secondary'}\n\t\t\t\t\t\t\tbuttonStyle={active ? 'solid' : 'ghost'}\n\t\t\t\t\t\t\tonClick={() => handleLocaleClick(locale)}\n\t\t\t\t\t\t\tdisabled={locale.disabled}\n\t\t\t\t\t\t\taria-pressed={active}\n\t\t\t\t\t\t\tclassName={cn('workspace-locale-strip--item justify-start')}\n\t\t\t\t\t\t>\n\t\t\t\t\t\t\t<Stack direction=\"horizontal\" align=\"center\" gap=\"md\" render={<span />} className=\"min-w-0\">\n\t\t\t\t\t\t\t<Text tag=\"span\" size=\"inherit\" className=\"truncate text-inherit\">{locale.label}</Text>\n\t\t\t\t\t\t\t{active && <Text tag=\"span\" size=\"inherit\" className=\"sr-only\">{strings.activeLabel}</Text>}\n\t\t\t\t\t\t\t\t{completion !== undefined && (\n\t\t\t\t\t\t\t\t\t/* On an active pill the button surface is solid, so the tonal\n\t\t\t\t\t\t\t\t\t    badge variants land coloured-on-coloured. Derive the nested\n\t\t\t\t\t\t\t\t\t    badge from the primary foreground pair so it remains legible\n\t\t\t\t\t\t\t\t\t    when dark themes intentionally lighten `--primary`. */\n\t\t\t\t\t\t\t\t\t<Badge\n\t\t\t\t\t\t\t\t\t\ttone={completion >= 100 ? 'success' : 'secondary'}\n\t\t\t\t\t\t\t\t\t\tclassName={cn(\n\t\t\t\t\t\t\t\t\t\t\t'shrink-0',\n\t\t\t\t\t\t\t\t\t\t\tactive && 'border-primary-foreground/20 bg-primary-foreground/10 text-primary-foreground',\n\t\t\t\t\t\t\t\t\t\t)}\n\t\t\t\t\t\t\t\t\t>\n\t\t\t\t\t\t\t\t\t\t{strings.completionLabel(completion)}\n\t\t\t\t\t\t\t\t\t</Badge>\n\t\t\t\t\t\t\t\t)}\n\t\t\t\t\t\t\t\t{!!locale.status && <span className=\"shrink-0\">{locale.status}</span>}\n\t\t\t\t\t\t\t</Stack>\n\t\t\t\t\t\t</Button>\n\t\t\t\t\t);\n\t\t\t\t})}\n\t\t\t</Stack>\n\t\t\t{!!(status || actions) && (\n\t\t\t\t<Stack direction=\"horizontal\" wrap align=\"center\" gap=\"md\" className=\"workspace-locale-strip--actions shrink-0\">\n\t\t\t\t\t{!!status && <div className=\"workspace-locale-strip--status\">{status}</div>}\n\t\t\t\t\t{!!actions && <Stack direction=\"horizontal\" wrap align=\"center\" gap=\"sm\" className=\"\">{actions}</Stack>}\n\t\t\t\t</Stack>\n\t\t\t)}\n\t\t</div>\n\t);\n});\n\nWorkspaceLocaleStrip.displayName = 'WorkspaceLocaleStrip';\n"],"mappings":"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"}

package/docs/consumer-skill/SKILL.md

@@ -5,11 +5,23 @@ description: Use when building, integrating, theming or migrating React apps and
 
 # Themelia React UI consumer
 
-Build from the public owner that fits the task. Use the exact family import,
-its supported props and the application's data, callbacks and product conventions.
-Before writing JSX, resolve the installed contract below. Select an owner in the
-table or finder, read its declaration and the matching recipe, then adapt the
-app's data/callbacks. Do not infer props or missing capabilities from names alone.
+Build from the public owner that fits the task: resolve the installed contract,
+pick the exact family import in the table or finder, read its declaration and
+recipe, then adapt the app's data and callbacks. Never infer props from names.
+
+## House rules
+
+Each rule has an owning prop or component, and the [optional checker](references/review.md) warns on most; depart only for a nameable product reason.
+
+1. Mount `UIProvider` (`themelia-react-ui/ui-provider`) once at the app root; calls inherit its currency, locale, date, density, button, badge and card defaults.
+2. Give every admin route a `Page` (`themelia-react-ui/layout/page`); its title is the route's `h1`, so do not repeat it in the body.
+3. Give commands roles: one `header.primaryAction`, ordered `header.secondaryActions`, `destructive: true` plus `ConfirmDialog`. An untoned `Button` is the neutral outline; give only the main command `tone="primary"` (solid), one per page or surface.
+4. Space siblings with `Stack`/`Grid` and their semantic `gap` (`themelia-react-ui/base/structure`), not flex divs with gap or margin utilities.
+5. Write copy with `Heading`/`Text`, not raw `h1`–`h6`; show values with `Money`, `Date`, `Number` and `Percent`, and use `useMoneyFormatter()` inside strings.
+6. Color with semantic classes (`bg-muted`, `text-muted-foreground`, `border-border`, status tones); palette classes such as `bg-blue-500` bypass theming and dark mode.
+7. Badges stay neutral unless the status means `success`, `warning`, `destructive` or `info`. Titles, facts and rows get no decorative icons, and gaps, not dividers, separate a card's sections.
+8. In a Card, badges go in `titleSuffix`, one quick control in `headerAction`, a command list in `actions` and the commit action in `footerSlot`.
+9. Dialogs, confirmations, drawers and sheets come only from `themelia-react-ui/features/overlays` (`ActionDialog`, `ConfirmDialog`, `ActionDrawer` with `useOverlayVisibility`); never hand-roll a modal, import `Dialog`/`Sheet` primitives or add a modal library.
 
 ## Start with an owner
 
@@ -22,6 +34,8 @@ app's data/callbacks. Do not infer props or missing capabilities from names alon
 | Query criteria and facets | `themelia-react-ui/features/filters`: `FilterLayout`, `SelectFacet`, `SearchFacet`, `DateFacet` |
 | Modal action, confirmation, drawer | `themelia-react-ui/features/overlays`: `ActionDialog`, `ConfirmDialog`, `ActionDrawer`, `useOverlayVisibility` |
 | Fields, schema-driven forms, inline drafts | `themelia-react-ui/base/forms`: `FormField`, `FormSection`, `FormActionsBar`; `themelia-react-ui/features/schema-form`: `SchemaForm`; `themelia-react-ui/base/inline-edit`: `InlineEdit` |
+| Passive rows, stacks, tracks and spans | `themelia-react-ui/base/structure`: `Stack`, `Grid`, `GridCell`, `AdaptiveGrid`; a row is `Stack direction="horizontal"` |
+| Content measure, sections, main/aside split | `themelia-react-ui/layout/containers`: `Container`, `Section`, `TwoColumnLayout`, `PageViewport` |
 | Application shell, sidebar, route identity | `themelia-react-ui/layout/app-shell`: `AppLayout`; `themelia-react-ui/layout/sidebar`: `AppSidebar`; `themelia-react-ui/layout/page`: `Page` |
 | Public website and content sections | `themelia-react-ui/layout/containers`: `Container`, `Section`, `PageViewport` |
 | Task summaries and conversation messages | `themelia-react-ui/blocks/planning`: `TaskCard`; `themelia-react-ui/blocks/collaboration`: `Message`, `MessageBubble` |
@@ -51,9 +65,8 @@ export const AccountFacts = () => <MetadataList items={[
 `Metric variant="card"`, default `MetricGrid`, `UsageCard` and `TaskCard` already
 own their surfaces. MetadataList, InlineStat and ChartCard delegate framing;
 Receipt owns its flat paper and insets. Choose a custom subject when its content
-or lifecycle calls for it; reuse the appropriate lower owners within it.
-The analytics barrel requires optional `recharts`, including without a sparkline;
-the focused UsageCard import has no chart peer. See [analytics](references/analytics.md).
+or lifecycle calls for it; reuse the appropriate lower owners within it. The analytics
+barrel needs optional `recharts`; UsageCard's focused import does not. See [analytics](references/analytics.md).
 
 ## Resolve the installed contract
 
@@ -68,37 +81,37 @@ For another task or an unfamiliar prop, run the bundled [finder](references/disc
 node node_modules/themelia-react-ui/docs/consumer-skill/scripts/find-components.mjs record directory --limit 5
 ```
 
-Task nouns retain richer alternatives; case-exact symbols such as `DataTable`
-and exact imports select their precise contract. Follow `relevantSymbols` and
-`nextReads` to the matching declaration, reference and recipe. Check the reported
-optional peers before assigning props. The [public index](references/public-api.json)
-contains all families; catalogue routes and private source paths are not imports.
-RichText accepts sanitized HTML; convert Markdown in the app before passing `html`.
+Task nouns return richer alternatives; exact symbols such as `DataTable` and
+exact imports select one contract. Follow `relevantSymbols` and `nextReads`,
+check reported optional peers, and replace any name listed under `deprecated`.
+The [public index](references/public-api.json) lists all families; catalogue
+routes and source paths are not imports. RichText takes sanitized HTML, not Markdown.
 
 ## Compose and adapt the screen
 
-Use Page for route identity/commands and Container/Section for content-led sites.
-Card frames one independent subject. Put status/count/version badges in
-`titleSuffix`, actions in `headerAction`/`actions`, and pre-title context in
-`headerStart`. Use `surface="flat" padding="none"` within an existing boundary.
+Use Page for routes and Container/Section for content-led sites. Header `actions`
+holds non-command controls such as a period select, never command button rows.
+Card frames one independent subject; `headerStart` holds pre-title context and
+`surface="flat" padding="none"` composes within an existing boundary.
+For headed commerce/variants blocks, choose their `surface` prop instead of
+adding a second Card boundary; see [headed blocks](references/composition.md#headed-blocks-inside-surfaces).
 Use the table/query/selection/row-action seams when they fit the workflow.
 Keep fixed parent context while criteria change; make command scope clear.
 
 Give each inset and gap one owner: page/container gutters, surface padding,
-section rhythm and Stack/Grid sibling gaps. Use Heading/Text and formatted
-primitives for display copy; choose Heading `tag` for semantics and `size` for
-visual emphasis. Keep typography margin-free and primary rows at the shared size.
-Choose `textGap`, density, control `size` and surface padding independently.
-Shells own global corners; controls/rows own bounded inner corners. Change
-`--radius` at the theme boundary; keep per-component radius classes out of callers.
-Omit control size to inherit provider defaults. Public props and regions own
-internal anatomy; application placement, alignment and overflow remain flexible.
-
-Treat appearance feedback as an acceptance criterion. Inspect the reported
-state and improve its owning composition or recipe. A passing static check
-cannot establish that hierarchy, contrast, corners or spacing look right.
-Use CSS semantic surface/foreground pairs and existing structural roots for
-appearance; UIProvider supplies defaults. Use ThemeScope for scoped portals and
+section rhythm and Stack/Grid sibling gaps. Peer Card stacks in TwoColumnLayout
+use `gap="2xl"` to match its default grid rhythm in both axes. Choose Heading
+`tag` for semantics and `size` for emphasis; keep typography margin-free and
+primary rows at the shared size. Choose `textGap`, density, control `size` and
+surface padding independently. Shells own global corners; controls/rows own
+bounded inner corners. Change `--radius` at the theme boundary, never per
+component. Public props and regions own internal anatomy; application
+placement, alignment and overflow remain flexible.
+
+Treat appearance feedback as an acceptance criterion: inspect the reported state
+and improve its owning composition or recipe, since a passing static check cannot
+show that hierarchy, contrast, corners or spacing look right. Theme through
+semantic pairs and structural roots; use ThemeScope for scoped portals and
 native `dir` plus DirectionProvider for RTL. See [theming](references/theming.md).
 
 Keep controlled values authoritative and per-mount callbacks in the component.
@@ -111,7 +124,8 @@ For server-component apps, mount interactive families from a client wrapper.
 
 | Work | Focused guidance and complete example |
 | --- | --- |
-| Structure, Card, public websites, heading scale | [Composition](references/composition.md), [website](examples/website.tsx) |
+| Rows, grids, regions and peer gaps | [Layout-owner map](references/composition.md#structure-and-spacing), [layout blocks](examples/layout-blocks.tsx) |
+| Card, public websites, heading scale | [Composition](references/composition.md), [website](examples/website.tsx) |
 | Shell/sidebar/header and parent adaptation | [Layout composition](references/composition.md#application-layouts), [workspace](examples/app-layout.tsx) |
 | Directory, detail, editing and confirmation | [Workflows](references/workflows.md), [directory](examples/scoped-directory.tsx), [detail](examples/detail.tsx), [edit](examples/edit.tsx), [confirmation](examples/destructive-confirm.tsx) |
 | KPI, facts, quota/task summaries | [Analytics](references/analytics.md), [analytics recipe](examples/analytics.tsx), [task/usage/inline edit](examples/planning-usage-edit.tsx) |
@@ -119,8 +133,7 @@ For server-component apps, mount interactive families from a client wrapper.
 | Shared anatomy and source review | [Design contract](references/design-contract.md), [optional read-only checker](references/review.md) |
 
 Run the app's type/lint/behavior checks. Inspect long content and missing values
-at narrow/desktop parent widths in light/dark themes. Open menus/overlays and
-execute keyboard selection, dismissal/focus return, callbacks, validation and
-failure/retry. Keep source findings, inspected images and executed interactions
-separate; the optional checker reports errors, review warnings and unresolved
-expressions. Install/copy the complete skill manually after package upgrades.
+at narrow/desktop parent widths in light/dark themes. Open menus/overlays and run
+keyboard selection, dismissal/focus return, callbacks, validation and retry. Keep
+source findings, inspected images and executed interactions separate; the checker
+reports errors, warnings and unresolved expressions. Recopy the skill on upgrade.

package/docs/consumer-skill/examples/app-layout.tsx

@@ -1,8 +1,6 @@
 import type { ReactNode } from 'react';
-import { Button } from 'themelia-react-ui/base/buttons';
 import { Card } from 'themelia-react-ui/base/cards';
 import { SidebarTrigger } from 'themelia-react-ui/base/sidebar';
-import { Stack } from 'themelia-react-ui/base/structure';
 import { AppLayout, type AppLayoutVariant } from 'themelia-react-ui/layout/app-shell';
 import { HeaderUserMenu, type HeaderUserMenuProps } from 'themelia-react-ui/layout/header';
 import { Page } from 'themelia-react-ui/layout/page';
@@ -46,13 +44,13 @@ export function WorkspaceLayout({ variant = 'inset', sidebar, navigationGroups =
     slots={{ headerEnd: workspaceSwitcher, footer: user && sidebarAccount ? <SidebarNavigationUser user={user} onLogout={onLogout} /> : undefined }} />;
   const content = <Page narrow={narrow} gutter={variant === 'stacked' ? 'none' : undefined}
     header={{ title: 'Workspace', description: 'Review activity and manage your records.',
-      headingTag: 'h1', actions: <Button onClick={onCreate}>Create record</Button> }}>
+      primaryAction: { label: 'Create record', onClick: onCreate } }}>
     {children ?? <Card title="Activity" footerText="Latest workspace activity"><Text>Application content goes here.</Text></Card>}
   </Page>;
   const trigger = <SidebarTrigger />;
   return <LayoutSidebarProvider adaptTo="container" className="min-h-0">
     {variant === 'stacked' ? <AppLayout variant="stacked" className="h-svh min-h-0" logo={brand}
-      slots={{headerEnd: account}} nav={<Stack direction="horizontal" gap="sm"><Button onClick={onCreate}>Create record</Button></Stack>}>{content}</AppLayout>
+      slots={{headerEnd: account}}>{content}</AppLayout>
       : variant === 'sidebar' || variant === 'inset' ? <AppLayout variant={variant} className="h-svh min-h-0"
         sidebar={navigation} sidebarTrigger={trigger} slots={{ toolbarStart: brand, toolbarEnd: account }}>{content}</AppLayout>
       : <AppLayout variant={variant} className="h-svh min-h-0" logo={brand} sidebar={navigation}

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

@@ -1,4 +1,3 @@
-import { Building2 } from 'lucide-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';
@@ -17,7 +16,7 @@ export interface AccountDetailProps {
 
 export function AccountDetail({ account, onEdit, onBack }: AccountDetailProps) {
   return <Card title={account.name} headerPlacement="frame"
-    headerAction={<Button onClick={() => onEdit(account.id)}>Edit account</Button>}
+    headerAction={<Button tone="primary" onClick={() => onEdit(account.id)}>Edit account</Button>}
     footerSlot={<Button tone="secondary" buttonStyle="outline" onClick={onBack}>Back to accounts</Button>}>
     <AccountFacts account={account}/>
   </Card>;
@@ -26,8 +25,8 @@ export function AccountDetail({ account, onEdit, onBack }: AccountDetailProps) {
 /** 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',actions:<Button onClick={()=>onEdit(account.id)}>Edit account</Button>}}>
-    <Card title="Contact and billing" icon={<Building2/>} headerPlacement="frame">
+    backLabel:'Back to accounts',primaryAction:{label:'Edit account',onClick:()=>onEdit(account.id)}}}>
+    <Card title="Contact and billing" headerPlacement="frame">
       <AccountFacts account={account}/>
     </Card>
   </Page>;

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

@@ -52,7 +52,7 @@ export function AccountEdit({ initial, onSave, onCancel }: AccountEditProps) {
         {error && <Text role="alert" type="error">{error}</Text>}
         {saved && <Text role="status">Account saved.</Text>}
         <Stack direction={{ base: 'vertical', sm: 'horizontal' }} gap="sm">
-          <Button type="submit" loading={pending} strings={{ loading: 'Saving account…' }}>Save account</Button>
+          <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>
         </Stack>
       </Stack>

package/docs/consumer-skill/examples/layout-blocks.tsx

@@ -0,0 +1,20 @@
+import type { ReactNode } from 'react';
+import { Stack } from 'themelia-react-ui/base/structure';
+import { TwoColumnLayout } from 'themelia-react-ui/layout/containers';
+
+export interface LayoutBlocksProps {
+  summary?: ReactNode;
+  primary: ReactNode;
+  secondary: ReactNode;
+  support: ReactNode;
+  actions?: ReactNode;
+}
+
+/** Place inside Page. Pass independently framed subjects; this composition adds no Card or gutter. */
+export function LayoutBlocks({ summary, primary, secondary, support, actions }: LayoutBlocksProps) {
+  return <TwoColumnLayout adaptTo="container" header={summary}
+    main={<Stack gap="2xl">{primary}{secondary}</Stack>}
+    aside={<Stack gap="2xl">{support}</Stack>}
+    footer={actions ? <Stack direction="horizontal" justify="end" gap="md">{actions}</Stack> : undefined}
+  />;
+}

package/docs/consumer-skill/examples/manifest.json

@@ -3,7 +3,9 @@
   "examples": [
     {
       "file": "website.tsx",
-      "exports": ["WebsiteLandingPage"],
+      "exports": [
+        "WebsiteLandingPage"
+      ],
       "phase": "basic",
       "optionalPeers": []
     },
@@ -27,14 +29,20 @@
     },
     {
       "file": "scoped-directory.tsx",
-      "exports": ["ScopedDirectory"],
+      "exports": [
+        "ScopedDirectory"
+      ],
       "phase": "optional",
-      "optionalPeers": ["@tanstack/react-table", "react-day-picker"]
+      "optionalPeers": [
+        "@tanstack/react-table",
+        "react-day-picker"
+      ]
     },
     {
       "file": "detail.tsx",
       "exports": [
-        "AccountDetail", "AccountDetailPage"
+        "AccountDetail",
+        "AccountDetailPage"
       ],
       "phase": "basic",
       "optionalPeers": []
@@ -112,9 +120,23 @@
     },
     {
       "file": "analytics.tsx",
-      "exports": ["RevenueOverview", "RevenueMetric", "PlainStatistic"],
+      "exports": [
+        "RevenueOverview",
+        "RevenueMetric",
+        "PlainStatistic"
+      ],
       "phase": "optional",
-      "optionalPeers": ["recharts"]
+      "optionalPeers": [
+        "recharts"
+      ]
+    },
+    {
+      "file": "layout-blocks.tsx",
+      "exports": [
+        "LayoutBlocks"
+      ],
+      "phase": "basic",
+      "optionalPeers": []
     }
   ]
 }

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

@@ -50,11 +50,11 @@ export function ScopedDirectory(props: ScopedDirectoryProps) {
   const rowActions = useMemo<DataTableProps<DirectoryContact, unknown>['rowActions']>(() => [
     { id: 'open', label: 'Open contact', onClick: contact => props.onOpen(contact.id) },
   ], [props.onOpen]);
-  return <Page header={{ title: 'Contacts', headingTag: 'h1',
+  return <Page header={{ title: 'Contacts',
     description: 'People responsible for bookings, billing and operations.',
     onBack: props.onBack, backLabel: 'All businesses',
     slots: { beforeTitle: <Text type="secondary">Business: {props.scope.label}</Text> },
-    actions: props.onCreate ? <Button tone="primary" onClick={props.onCreate}>New contact</Button> : undefined,
+    primaryAction: props.onCreate ? { label: 'New contact', onClick: props.onCreate } : undefined,
   }}>
     <FilterProvider filters={criteria} activeFilters={props.filters}
       navigating={props.state.status === 'loading'}

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

@@ -54,11 +54,26 @@ accessibility needs and the task can justify richer rows. Explain the priority.
 Custom ResourceCell metadata is caller content; use shared supporting typography
 and CellStack where its smaller secondary-value contract fits.
 
-Commands need explicit importance as well as scope. PageActions does not infer
-primary tone from a label such as “New contact”; choose `tone="primary"` when
-that is the route's main command. Permissions and destructive intent remain
-application decisions. A back link, export and destructive command should not
-all inherit the same visual emphasis by accident.
+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
+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,
+export and destructive command should not all inherit the same visual emphasis.
+
+```tsx
+<Page header={{
+  title: 'Contacts',
+  primaryAction: { label: 'New contact', icon: Plus, onClick: onCreate },
+  secondaryActions: [
+    { label: 'Export', onClick: onExport },
+    { label: 'Delete list', destructive: true, onClick: confirmDelete },
+  ],
+}}>{/* route content */}</Page>
+```
 
 | Drift | Better decision |
 | --- | --- |
@@ -81,6 +96,20 @@ MetricGrid's default peers and UsageCard own their surfaces. A distinct custom
 Card subject remains valid; compare the complete subject contract before rebuilding
 formatting, hierarchy or request-state presentation from lower text primitives.
 
+For rows, grids, main/aside regions and matching peer gaps, use the
+[layout-owner map](#structure-and-spacing).
+
+### Headed blocks inside surfaces
+
+AddressCard, PaymentMethod, SeoListingCard and ProductVariantsManager accept
+Card's `surface`, `padding` and `headerDivider` props. Use `surface="card"` when
+that owner is the framed subject; it supplies the header and aligned body insets
+and inherits provider dividers. Do not add an untitled padded Card around it.
+Omit surface for an unframed embedded subject; its header rule defaults off.
+An explicit divider still wins. ProductVariantsManager also forwards
+`footerDivider` for its footer slot. Separate reusable body content can still be
+composed in a caller-owned Card; choose one owner for each headed boundary.
+
 ## Public websites and service overviews
 
 Compose a landing page or public website from its content. `Container` owns the
@@ -149,9 +178,11 @@ Choose one ordinary Card surface through UIProvider's `card.defaultSurface` and
 let sibling subjects inherit it. Explicit per-card surfaces win: mixing `card`
 and `framed` intentionally changes their visible treatment. Header placement is
 independent: `inside` keeps the heading with the body; `frame` puts context and
-commands on the outer frame above the inset body. Use `icon={<Icon />}` for a
-routine heading glyph and plain `title`; embedding raw SVG in title JSX bypasses
-the owner's icon sizing. Custom titles remain appropriate for richer content.
+commands on the outer frame above the inset body. A Card title needs no icon;
+pass `icon={<Icon />}` only when the glyph carries meaning (state, a brand, a type
+users scan for), never as raw SVG in title JSX. Custom titles remain appropriate
+for richer content. Facts and rows follow the same rule: one glyph repeated on
+every MetadataList item or Item row is decoration, so leave `icon`/media empty.
 
 Card `gap` owns spacing between regions; `contentGap` owns direct body-child
 spacing; `textGap` owns title/supporting-copy rhythm. Region spacing defaults to
@@ -164,7 +195,9 @@ compact subject; it is not the default for forms, settings, metrics or resource
 pages. Component size and
 density do not choose Card padding. `lg` uses 1.8 times the inset (36px), while
 `none` removes it. All sizes follow the surface roots and space-scale.
-UIProvider can configure both
+Dividers are off by default and
+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.
 
@@ -174,15 +207,54 @@ Reusable blocks/features stay card-free unless their explicit purpose is a card.
 
 ## Structure and spacing
 
-Shells own gutters, surfaces own padding, sections own rhythm, Stack/Grid own sibling gaps, typography owns none. Prefer gap/padding/size props to local appearance overrides.
+Choose the smallest owner that describes the region. These layout blocks are
+published primitives and layouts, not the domain compositions under `blocks/*`.
 
-Grid exposes viewport columns; AdaptiveGrid responds to parent width and a semantic minimum column size. GridCell spans belong to the nearest Grid. Keep narrow DOM order meaningful. Horizontal Stack wraps by default; disable it only when overflow is intentionally handled. Tailwind is appropriate for min-w-0, positioning, overflow and drawing geometry.
-
-Independent surfaces need peer rhythm, usually `gap="xl"`; Stack's default
-`md` is general sibling spacing, not a card-grid prescription. Framed Card rings
-extend outside layout rectangles, so two rings can consume a small DOM gap.
-Inspect visible edge clearance in both axes rather than accepting token use alone.
-Copy gaps normal/dense are for supporting text, not spacing independent cards.
+| Responsibility | Exact family and owner | Contract to preserve |
+| --- | --- | --- |
+| Vertical siblings or an action row | `base/structure`: Stack | Vertical by default; `direction="horizontal"` creates a row and wraps by default. Default gap is `md` (8px). There is no separate Row export. |
+| Known responsive tracks | `base/structure`: Grid | Scalar columns are literal; use `columns={{base:1,lg:3}}` for breakpoints. Omitted columns use one, then two from md. Default gap is `xl` (16px). |
+| Track spans | `base/structure`: GridCell | Use `span={{base:1,lg:2}}` inside the nearest Grid; keep meaningful DOM order. |
+| Equal tiles that fit their parent | `base/structure`: AdaptiveGrid | Select `minColumnWidth`; tracks follow available width. Use Grid for prescribed breakpoints or TwoColumnLayout for a supporting rail. |
+| Centered measure and inline gutters | `layout/containers`: Container | Defaults to xl measure and md gutter. Owns no vertical inset, scrolling or surface chrome. |
+| A semantic content section | `layout/containers`: Section | Owns sibling rhythm, default `xl`; it adds no Card frame or page gutter. |
+| Main content with a supporting rail | `layout/containers`: TwoColumnLayout | Owns header/main/aside/footer order and `2xl` gaps (24px). Main/aside contents choose their own Stack gaps. Page rhythm (header to body, major Sections) uses `3xl` (32px). |
+| A bounded page scroll region | `layout/containers`: PageViewport | Owns scrolling and query containment, with no padding. AppLayout already supplies one. |
+| Route title, commands and page content | `layout/page`: Page | Owns measure, inline/block gutters and header/body rhythm. Use `narrow` for a focused resource. |
+| Application header/sidebar chrome | `layout/app-shell`: AppLayout | Select the shell variant, compose slots and router callbacks, and let its viewport contain Page. |
+| A framed subject | `base/cards`: Card | Owns surface padding, header/body/footer alignment and separators; layout blocks own the space between Cards. |
+
+See the typed [layout-block composition](../examples/layout-blocks.tsx) when composing these owners.
+
+Use these public structures for repeated passive composition rather than
+rebuilding the same flex/grid spacing on divs. Tailwind remains appropriate for
+positioning, overflow, chart/table geometry and custom intrinsic tracks. Structure
+preserves child identity; it does not inspect, clone, reorder or frame children.
+
+### Main and aside Card gaps
+
+Peer Cards in a Page/TwoColumnLayout workspace use `gap="2xl"` on both main and
+aside Stacks to match its 24px grid gap. Give a peer Grid the same gap when it
+belongs to that rhythm. A compact local card grid may deliberately keep Grid's
+16px default. Stack's 8px default is general sibling spacing, not an automatic
+Card rhythm; choose the role explicitly. Values above use shipped roots and
+scale through the existing space-scale contract.
+
+The [region recipe](../examples/layout-blocks.tsx) keeps both inner Stacks on that same peer gap.
+
+Use `textGap="normal"|"dense"` for title/description copy; keep action gaps,
+form groups, peer regions and surface insets independent. Do not use small copy
+gaps between independent Cards or shrink Card padding to match control density.
+Framed Card rings extend outside layout rectangles: inspect visible clearance
+in both axes as well as computed gaps.
+
+### Horizontal rows
+
+See the typed [layout-block composition](../examples/layout-blocks.tsx): Page
+supplies its boundary, TwoColumnLayout splits the regions, inner Stacks share
+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
 compact density tightens gaps/rows without shrinking primary values. Plain values

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

@@ -80,6 +80,10 @@ kind, exact `matchedSymbols`, `relevantSymbols`, `nextReads` and up to three
 relevant guidance entries. Exact symbol queries keep that symbol; intent queries
 derive relevantSymbols from selected catalogue API sections and current public
 exports. An exact family import retains the complete public symbol vocabulary.
+Deprecated migration names such as `SmartCard` or `ContentBlockProps` never
+appear in intent recommendations. When a result touches one, its `deprecated`
+map names the replacement, for example `{ "SmartCard": "Use Card." }`; write
+new code with the replacement. The public index carries the same map per family.
 Exact guide aliases precede generic overlap, and unrelated family pages
 do not fill the result merely to reach three entries.
 

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

@@ -64,6 +64,28 @@ 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.
 
+## Upgrading to the neutral button default
+
+An untoned `Button` is now the neutral outline (`tone="secondary"`,
+`buttonStyle="outline"`); a Button with a `tone` and no `buttonStyle` stays
+solid. Screens that relied on untoned Buttons being the solid primary can keep
+their look with the bundled codemod. It reports by default and edits only with
+`--write`; review the diff before committing:
+
+```sh
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/pin-button-defaults.mjs src
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/pin-button-defaults.mjs --write src
+```
+
+It adds `tone="primary"` to every Button, BaseButton or BaseButtonLink imported
+from the package without a `tone`. Add `--solid-only` to skip untoned outline
+and ghost Buttons so they turn neutral instead of keeping the brand color.
+Buttons whose props come from a spread are listed as `unresolved` for review.
+Apps that already set `UIProvider` `button.defaultTone` keep that tone and do not
+need the codemod; `button: { defaultTone: 'primary', defaultButtonStyle: 'solid' }`
+restores the previous default app-wide. Afterwards, demote extra primaries so
+each page or surface keeps one.
+
 ## Manual skill copying
 
 1. Choose an agent skill destination in the user's configured skills directory,

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

@@ -50,7 +50,38 @@ does not replace the single mount-time UIProvider configuration boundary.
 
 Routing comes through href, callbacks or Base UI render composition. React Router is not required. Component chunks preserve client boundaries; pure utilities remain separate.
 
-Use ActionDialog, ActionDrawer, ConfirmDialog and useOverlayVisibility from features/overlays. Pass overlayProps for visibility. onAsyncConfirm awaits the operation; onError reports failure. Do not also pass onConfirm, which takes precedence. Sheet is structural infrastructure, not another workflow API.
+## Dialogs, confirmations and drawers
+
+Every dialog-like surface comes from `themelia-react-ui/features/overlays`; it is
+the only modal system. The overlay owners hold focus entry and trapping, Escape
+and outside-click dismissal, focus return to the trigger, pending and error
+states, portal theming and the shared scrim (a plain tint, never a blur).
+
+| Need | Owner |
+| --- | --- |
+| A focused edit or form with confirm/cancel | `ActionDialog` |
+| A yes/no question, or a destructive confirmation | `ConfirmDialog` (destructive tone for irreversible actions) |
+| A longer form, filters or record details beside the page | `ActionDrawer` |
+| Open state, triggers and several overlays on one screen | `useOverlayVisibility` (`overlayProps`, `show`, `hide`) |
+
+Pass `overlayProps` for visibility. `onAsyncConfirm` awaits the operation and
+keeps the overlay open on failure; `onError` reports it. Do not also pass
+`onConfirm`, which takes precedence. Each overlay owns one primary command, its
+confirm button; compose the body with the ordinary Stack, FormField and Card
+anatomy and leave its insets to the overlay.
+
+Do not hand-roll a modal (a `fixed inset-0` scrim, `role="dialog"`,
+`aria-modal`), do not import the lower-level `Dialog`, `AlertDialog` or `Sheet`
+building blocks, and do not add another modal library (Radix Dialog,
+react-modal, vaul, Headless UI or React Aria dialogs). The optional checker
+warns on each of these. Popovers, menus, selects and tooltips are anchored
+surfaces, not dialogs: use their own owners.
+
+To show a table full screen, use `DataTable`'s own mode (`fullscreen` or
+`defaultFullscreen`, `onFullscreenChange`, `showFullscreenToggle`) instead of
+moving the table into a dialog. It maximises the table in place, so scroll
+position, focus and column state survive; Escape leaves, Tab stays inside and
+focus returns to the toggle.
 
 PlaceAutocomplete from themelia-react-ui/features/map uses Photon by default. Supply a stable or useCallback-memoized searchPlaces: PlaceSearchCallback to use your geocoder; it receives PlaceSearchOptions and an AbortSignal and returns Promise<PlaceFeature[]>. Adapt provider results to the existing place shape and OSM identifiers (duplicates are removed by osm_id). Changing provider identity or search options cancels the old lookup and searches the current query. Respect the signal; superseded responses are ignored even if a provider cannot cancel. Keep provider identity stable during ordinary renders. Notification callbacks may be inline. onSearchError reports current failures; the built-in Retry action repeats the lookup and strings.retry localizes its label.