@podoba/react 0.0.32 → 0.0.35

package/src/components/side-panel.examples.tsx

@@ -0,0 +1,80 @@
+import { useState } from 'react'
+
+import { Button } from './button'
+import { SidePanel } from './side-panel'
+
+function DefaultExample(): React.ReactNode {
+	const [open, setOpen] = useState(false)
+	return (
+		<>
+			<Button onPress={() => setOpen(true)}>Open panel</Button>
+			<SidePanel
+				isOpen={open}
+				onOpenChange={setOpen}
+				title="Assistant"
+				description="Acme Robotics"
+				closeLabel="Close assistant"
+				footer={<Button className="w-full">Send</Button>}
+			>
+				<p className="text-small text-fg-muted">Ask a question about the current Brand.</p>
+			</SidePanel>
+		</>
+	)
+}
+
+function SizeExample({ size }: { size: 'sm' | 'md' | 'lg' }): React.ReactNode {
+	const [open, setOpen] = useState(false)
+	return (
+		<>
+			<Button variant="secondary" onPress={() => setOpen(true)}>
+				{size.toUpperCase()}
+			</Button>
+			<SidePanel
+				isOpen={open}
+				onOpenChange={setOpen}
+				title={`${size.toUpperCase()} panel`}
+				closeLabel="Close panel"
+				size={size}
+			>
+				<p className="text-small text-fg">Responsive owned-scroll content.</p>
+			</SidePanel>
+		</>
+	)
+}
+
+function PendingExample(): React.ReactNode {
+	const [open, setOpen] = useState(false)
+	return (
+		<>
+			<Button variant="secondary" onPress={() => setOpen(true)}>Pending state</Button>
+			<SidePanel
+				isOpen={open}
+				onOpenChange={setOpen}
+				title="Saving"
+				description="Dismissal is temporarily disabled."
+				closeLabel="Close panel"
+				isDismissable={false}
+			>
+				<div role="status" className="text-small text-fg-muted">Working…</div>
+			</SidePanel>
+		</>
+	)
+}
+
+export const examples = {
+	default: () => <DefaultExample />,
+	sizes: () => (
+		<div className="flex gap-2">
+			<SizeExample size="sm" />
+			<SizeExample size="md" />
+			<SizeExample size="lg" />
+		</div>
+	),
+	states: () => <PendingExample />,
+}
+
+export const meta = {
+	category: 'Layout',
+	description: 'Accessible right-side modal panel with responsive full-screen mobile behavior.',
+}
+

package/src/components/side-panel.tsx

@@ -0,0 +1,140 @@
+import type { ReactNode } from 'react'
+import {
+	Button as RACButton,
+	Dialog as RACDialog,
+	Heading,
+	Modal as RACModal,
+	ModalOverlay as RACModalOverlay,
+} from 'react-aria-components'
+
+import { uic } from '../utils/uic'
+
+export type SidePanelSize = 'sm' | 'md' | 'lg'
+
+export interface SidePanelProps {
+	/** Controlled open state. */
+	isOpen: boolean
+	/** Called for Escape, backdrop dismissal and the close control. */
+	onOpenChange: (isOpen: boolean) => void
+	/** Accessible panel title. */
+	title: ReactNode
+	/** Optional supporting copy below the title. */
+	description?: ReactNode
+	/** App-supplied localized label for the close control. */
+	closeLabel: string
+	/** Panel width from the shared responsive scale. */
+	size?: SidePanelSize
+	/** Disable Escape/backdrop dismissal while a critical operation is pending. */
+	isDismissable?: boolean
+	/** Owned-scroll panel content. */
+	children: ReactNode | ((options: { close: () => void }) => ReactNode)
+	/** Optional pinned action area below the scroll region. */
+	footer?: ReactNode | ((options: { close: () => void }) => ReactNode)
+	/** Optional test id forwarded to the dialog element. */
+	'data-testid'?: string
+}
+
+const SidePanelOverlay = uic(RACModalOverlay, {
+	displayName: 'SidePanel.Overlay',
+	baseClass:
+		'fixed inset-0 z-50 flex justify-end bg-modal-backdrop backdrop-blur-modal-backdrop ' +
+		'data-[entering]:animate-modal-overlay-in data-[exiting]:animate-modal-overlay-out ' +
+		'motion-reduce:data-[entering]:animate-none motion-reduce:data-[exiting]:animate-none',
+})
+
+const SidePanelSurface = uic(RACModal, {
+	displayName: 'SidePanel.Surface',
+	baseClass:
+		'ml-auto flex h-dvh w-full flex-col overflow-hidden bg-surface outline-none shadow-modal-surface ' +
+		'sm:rounded-l-lg data-[entering]:animate-side-panel-in data-[exiting]:animate-side-panel-out ' +
+		'motion-reduce:data-[entering]:animate-none motion-reduce:data-[exiting]:animate-none',
+	variants: {
+		size: {
+			sm: 'sm:max-w-sm',
+			md: 'sm:max-w-md',
+			lg: 'sm:max-w-lg',
+		},
+	},
+	defaultVariants: { size: 'md' },
+})
+
+const SidePanelClose = uic(RACButton, {
+	displayName: 'SidePanel.Close',
+	baseClass:
+		'inline-flex h-11 w-11 shrink-0 items-center justify-center rounded-full text-fg-subtle outline-none ' +
+		'transition-colors hover:bg-surface-muted hover:text-fg ' +
+		'data-[focus-visible]:ring-2 data-[focus-visible]:ring-ring data-[focus-visible]:ring-offset-2',
+})
+
+/**
+ * Responsive modal side panel.
+ *
+ * React Aria owns focus containment, Escape/backdrop dismissal, scroll locking
+ * and trigger focus return. The surface is a full-screen owned-scroll sheet on
+ * mobile and a right-aligned panel on larger viewports. All copy and product
+ * content are supplied by the consuming application.
+ */
+export function SidePanel({
+	isOpen,
+	onOpenChange,
+	title,
+	description,
+	closeLabel,
+	size = 'md',
+	isDismissable = true,
+	children,
+	footer,
+	'data-testid': testId,
+}: SidePanelProps): React.ReactNode {
+	return (
+		<SidePanelOverlay
+			isOpen={isOpen}
+			onOpenChange={onOpenChange}
+			isDismissable={isDismissable}
+		>
+			<SidePanelSurface size={size}>
+				<RACDialog
+					data-testid={testId}
+					className="flex min-h-0 flex-1 flex-col outline-none"
+				>
+					{renderProps => (
+						<>
+							<header className="flex shrink-0 items-start justify-between gap-4 border-b border-border px-5 py-4">
+								<div className="min-w-0 pt-1">
+									<Heading slot="title" className="text-heading1 font-medium tracking-tight text-fg">
+										{title}
+									</Heading>
+									{description ? (
+										<p className="mt-1 text-small text-fg-muted">{description}</p>
+									) : null}
+								</div>
+								<SidePanelClose aria-label={closeLabel} onClick={() => onOpenChange(false)}>
+									<svg
+										width="20"
+										height="20"
+										viewBox="0 0 24 24"
+										fill="none"
+										stroke="currentColor"
+										strokeWidth="2"
+										strokeLinecap="round"
+										aria-hidden="true"
+									>
+										<path d="M6 6l12 12M18 6 6 18" />
+									</svg>
+								</SidePanelClose>
+							</header>
+							<div className="min-h-0 flex-1 overflow-y-auto p-5">
+								{typeof children === 'function' ? children(renderProps) : children}
+							</div>
+							{footer ? (
+								<footer className="shrink-0 border-t border-border px-5 pt-4 pb-mobile-cta-bottom sm:pb-4">
+									{typeof footer === 'function' ? footer(renderProps) : footer}
+								</footer>
+							) : null}
+						</>
+					)}
+				</RACDialog>
+			</SidePanelSurface>
+		</SidePanelOverlay>
+	)
+}

package/src/components/subtle.tsx

@@ -1,10 +1,12 @@
-import type { ReactNode } from 'react'
+import type { ComponentProps } from 'react'
+
+import { uic } from '../utils/uic'
 
 /**
- * Subtle — inline de-emphasised text (the light `fg-subtle` grey, #b3b3b3). Wraps its
- * children in a `text-fg-subtle` span; anything OUTSIDE it stays at the surrounding
- * full-contrast `fg`. Compose it freely to two-tone arbitrary runs of a line — unlike
- * a fixed-slot header it handles mid-line emphasis in ANY order and ANY language:
+ * Subtle — inline de-emphasised text. Wraps its children in a de-emphasised span;
+ * anything OUTSIDE it stays at the surrounding full-contrast `fg`. Compose it freely
+ * to two-tone arbitrary runs of a line — unlike a fixed-slot header it handles
+ * mid-line emphasis in ANY order and ANY language:
  *
  *   <h1>
  *     <Subtle>Good afternoon</Subtle> {name} 👋
@@ -15,7 +17,61 @@ import type { ReactNode } from 'react'
  * With i18n, put the `<subtle>…</subtle>` runs INSIDE the translation string and render
  * it via `<Trans components={{ subtle: <Subtle /> }} />`, so each locale places the
  * emphasis where its own word order needs it. Presentational only (hard rule #1).
+ *
+ * ## Tone
+ *
+ * `muted` (the default) is `fg-muted`. It clears WCAG 2.1 AA normal-text contrast on
+ * the READING surfaces — `surface` 5.98:1, `surface-card` 5.53:1, `surface-muted`
+ * 4.96:1 in light; 6.52:1 / 5.30:1 in dark. Meaningful copy — a greeting, a task
+ * count, a caption — belongs here.
+ *
+ * `muted` covers the reading surfaces and nothing else. Every surface that carries
+ * its OWN ink needs the matching tone, because `fg-muted` is below AA on all of
+ * them — `Tile.mutedTone()` has always encoded this pairing, and these two tones
+ * are the same rule made reachable from a bare run of text:
+ *
+ *   surface-inverted (#242423 — does NOT flip, so it is a dark panel in the LIGHT
+ *     theme too: a dark `Tile`, `Badge color="dark"`)   fg-muted 2.60:1
+ *     → `inverted`, `fg-inverted/60` — 6.49:1 light, 4.99:1 dark
+ *
+ *   the FIXED brand fills, which never flip: brand-green (fg-muted 3.95:1),
+ *     accent-yellow (4.01:1), brand-secondary (3.60:1) — a teal or yellow `Tile`,
+ *     a `CtaPill`, a green/yellow `Badge`
+ *     → `on-brand`, `fg-on-brand/70` — 6.08:1 / 6.11:1 / 5.78:1, theme-stable
+ *
+ * All four blends are asserted in @podoba/tokens `contrast.test.ts`.
+ *
+ * ## Migrating from ≤ 0.0.34
+ *
+ * BREAKING on `surface-inverted` ONLY. `fg-subtle` is light enough that it happened
+ * to PASS on that dark panel (7.41:1) while failing everywhere else, so a run that
+ * sat on a dark `Tile` had a working colour by accident and now needs
+ * `tone="inverted"` to keep it. Nothing detects this for you: the tone is a prop,
+ * and no lint rule knows which surface a run lands on — grep for `<Subtle` and
+ * `tone="subtle"` inside dark `Tile`s and `bg-surface-inverted` panels.
+ *
+ * Everywhere else the new default is an improvement, not a migration. On the
+ * reading surfaces it goes 2.10 → 5.98 (and 1.74 → 4.96 on `surface-muted`); on the
+ * brand fills 1.39 → 3.95, which is better but still short of AA — those runs were
+ * ALWAYS broken and `tone="on-brand"` is the fix, not a regression to undo.
+ *
+ * `decorative` is the lighter `fg-subtle` (#b3b3b3) this component used to apply
+ * unconditionally. It measures 2.10:1 on `surface` and 1.94:1 on `surface-card`, below
+ * even the 3:1 large-text floor, so it is ORNAMENTAL ONLY: separators, watermarks,
+ * repeated decorative runs that carry no information a reader would miss. Never put
+ * text a user has to read behind it.
  */
-export function Subtle({ children }: { children: ReactNode }) {
-	return <span className="text-fg-subtle">{children}</span>
-}
+export const Subtle = uic('span', {
+	displayName: 'Subtle',
+	variants: {
+		tone: {
+			muted: 'text-fg-muted',
+			inverted: 'text-fg-inverted/60',
+			'on-brand': 'text-fg-on-brand/70',
+			decorative: 'text-fg-subtle',
+		},
+	},
+	defaultVariants: { tone: 'muted' },
+})
+
+export type SubtleProps = ComponentProps<typeof Subtle>

package/src/components/table.examples.tsx

@@ -0,0 +1,9 @@
+import { Table } from './table'
+const columns = [{ key: 'name', header: 'Name' }, { key: 'city', header: 'City' }]
+const data = [{ name: 'Annual report', city: 'Prague' }]
+export const examples = {
+	default: () => <Table columns={columns} data={data} aria-label="Projects" />,
+	worksheet: () => <Table appearance="worksheet" columns={columns} data={data} aria-label="CSV preview" />,
+	empty: () => <Table appearance="worksheet" columns={columns} data={[]} emptyMessage="No preview rows available." aria-label="Empty CSV" />,
+}
+export const meta = { category: 'Composite', description: 'Default data table and the source Manager worksheet appearance with monospace column labels.' }

package/src/components/table.tsx

@@ -1,5 +1,7 @@
-import { useMemo, useState, type ReactNode } from 'react'
+import { useMemo, useState, type CSSProperties, type HTMLAttributes, type ReactNode } from 'react'
 import { ChevronDownIcon, ChevronUpIcon } from './icons'
+export const TABLE_APPEARANCES = ['default', 'worksheet', 'team'] as const
+export type TableAppearance = (typeof TABLE_APPEARANCES)[number]
 
 /**
  * Table — the design-system data table (port of gs-platform's `GSTable`). A light,
@@ -35,10 +37,15 @@ export type TableColumn<Row> = {
 }
 
 export type TableProps<Row> = {
+	/** Worksheet matches Manager's plain GSTable; default preserves existing consumers. */
+	appearance?: TableAppearance
 	columns: TableColumn<Row>[]
 	data: Row[]
 	/** Stable per-row key. Defaults to the row index (fine for static lists). */
 	getRowKey?: (row: Row, index: number) => string
+	/** Additional semantic/event props for each rendered row. */
+	getRowProps?: (row: Row) => HTMLAttributes<HTMLTableRowElement>
+	columnTemplate?: string
 	/** Enable client-side sorting on `sortable` columns. */
 	enableSorting?: boolean
 	/** Whole-row press handler — renders rows as interactive (hover + keyboard). */
@@ -69,10 +76,13 @@ export function Table<Row>({
 	columns,
 	data,
 	getRowKey,
+	getRowProps,
+	columnTemplate,
 	enableSorting = false,
 	onRowClick,
 	emptyMessage = 'No rows.',
 	className,
+	appearance = 'default',
 	...aria
 }: TableProps<Row>) {
 	const [sort, setSort] = useState<{ key: string; dir: 'asc' | 'desc' } | null>(null)
@@ -100,12 +110,15 @@ export function Table<Row>({
 
 	const rowKey = getRowKey ?? ((_row: Row, index: number) => String(index))
 	const interactive = Boolean(onRowClick)
+	const worksheet = appearance === 'worksheet'
+	const team = appearance === 'team'
+	const gridTemplate = columnTemplate ?? `repeat(${columns.length}, minmax(0, 1fr))`
 
 	return (
 		<div className={['w-full overflow-x-auto', className].filter(Boolean).join(' ')}>
-			<table className="w-full border-collapse text-small" {...aria}>
-				<thead>
-					<tr className="border-b border-border">
+			<table style={team ? { '--table-columns': gridTemplate } as CSSProperties : undefined} className={`w-full border-collapse text-small ${worksheet ? 'border-b border-border font-normal leading-4.5' : ''} ${team ? 'block border-b border-border font-normal leading-4.5' : ''}`} {...aria}>
+				<thead className={team ? 'block' : undefined}>
+					<tr className={`${worksheet ? '' : 'border-b border-border'} ${team ? 'grid grid-cols-[var(--table-columns)] gap-3 bg-surface-muted px-4 max-[1023px]:hidden' : ''}`}>
 						{columns.map((column) => {
 							const align = column.align ?? 'left'
 							const canSort = enableSorting && column.sortable
@@ -118,7 +131,7 @@ export function Table<Row>({
 									aria-sort={
 										canSort ? (active ? (sort?.dir === 'asc' ? 'ascending' : 'descending') : 'none') : undefined
 									}
-									className={`${ALIGN_CLASS[align]} px-4 py-3 text-label font-medium tracking-wide text-fg-muted uppercase`}
+									className={`${ALIGN_CLASS[align]} ${worksheet ? 'border-0 px-3 py-4 align-middle font-mono text-small font-normal leading-4.5 tracking-normal text-fg normal-case bg-surface whitespace-nowrap' : team ? 'border-0 px-4 py-3 align-middle font-mono text-small font-normal leading-4.5 tracking-normal text-fg normal-case whitespace-nowrap' : 'px-4 py-3 text-label font-medium tracking-wide text-fg-muted uppercase'}`}
 								>
 									{canSort ? (
 										<button
@@ -145,17 +158,20 @@ export function Table<Row>({
 						})}
 					</tr>
 				</thead>
-				<tbody>
+				<tbody className={team ? 'block' : undefined}>
 					{sorted.length === 0 ? (
 						<tr>
-							<td colSpan={columns.length} className="px-4 py-10 text-center text-small text-fg-muted">
+							<td colSpan={columns.length} className={worksheet ? 'border-y border-border px-6 py-4 text-small font-normal leading-4.5 text-fg' : 'px-4 py-10 text-center text-small text-fg-muted'}>
 								{emptyMessage}
 							</td>
 						</tr>
 					) : (
-						sorted.map((row, index) => (
+						sorted.map((row, index) => {
+						const rowProps = getRowProps?.(row)
+						return (
 							<tr
 								key={rowKey(row, index)}
+								{...rowProps}
 								{...(interactive
 									? {
 											tabIndex: 0,
@@ -169,22 +185,23 @@ export function Table<Row>({
 											},
 										}
 									: {})}
-								className={`border-b border-border/60 outline-none ${
+								className={`${worksheet ? 'min-h-15' : team ? 'grid grid-cols-[var(--table-columns)] gap-3 border-b border-border px-4 py-3 text-label font-normal leading-4.5 max-[1023px]:grid max-[1023px]:grid-cols-1 max-[1023px]:gap-2 max-[1023px]:p-4' : 'border-b border-border/60'} ${team ? 'focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring' : ''} outline-none ${
 									interactive
 										? 'cursor-pointer transition-colors hover:bg-surface-muted focus-visible:bg-surface-muted focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring'
 										: ''
-								}`}
+								}${rowProps?.className ? ` ${rowProps.className}` : ''}`}
 							>
 								{columns.map((column) => {
 									const align = column.align ?? 'left'
 									return (
-										<td key={column.key} className={`${ALIGN_CLASS[align]} px-4 py-3 align-middle text-fg`}>
+										<td key={column.key} className={`${ALIGN_CLASS[align]} ${worksheet ? 'border border-border first:border-l-0 last:border-r-0 px-6 py-4 text-small font-normal leading-4.5' : team ? 'px-0 py-0 align-middle text-small font-normal leading-4.5 max-[1023px]:block' : 'px-4 py-3'} align-middle text-fg`}>
 											{column.render ? column.render(row) : String(defaultSortValue(column, row))}
 										</td>
 									)
 								})}
 							</tr>
-						))
+						)
+						})
 					)}
 				</tbody>
 			</table>

package/src/components/template-catalog-card.examples.tsx

@@ -0,0 +1,25 @@
+import { useState } from 'react'
+import { CatalogMetricCard } from './template-catalog-card'
+import { CatalogLaunchCard, CatalogSummaryBadge, CatalogSummaryGrid, CatalogSummaryCard, TemplateCatalogBrowseCard, TemplateCatalogBrowseGrid } from './template-catalog-card'
+import { TemplateCatalogCard, TemplateCatalogGrid, TemplateReferenceGrid, TemplateReferenceList, TemplateReferenceItem, CatalogMetadataSummary } from './template-catalog-card'
+
+function Example({ selected = false, locked = false, title = 'Annual report' }: { selected?: boolean; locked?: boolean; title?: string }) {
+	const [value, setValue] = useState(selected)
+	return <TemplateCatalogCard title={title} isSelected={value} isSelectionLocked={locked}
+		onToggle={() => setValue(!value)} preview={<span className="flex h-full aspect-3/4 items-center justify-center bg-surface text-fg">Aa</span>} />
+}
+
+export const examples = {
+	metrics: () => <CatalogSummaryGrid>{['0', '205', '—'].map(value => <CatalogMetricCard key={value} title="Templates" value={value} footer={value === '0' ? undefined : 'Catalog'} />)}</CatalogSummaryGrid>,
+	launch: () => <CatalogLaunchCard title="Annual report" description="Prepare the yearly report." details="2 sections · 3 outputs" action={<button type="button" aria-label="Start Annual report" className="absolute inset-0 rounded-lg focus-visible:ring-2 focus-visible:ring-ring" />} />,
+	launchWithoutBrief: () => <CatalogLaunchCard title="Annual report" details="2 sections · 3 outputs" action={<button type="button" disabled aria-label="Start Annual report" className="absolute inset-0 rounded-lg" />} />,
+	summary: () => <CatalogSummaryGrid>{['Campaign', 'Annual report', 'Social launch'].map(title => <CatalogSummaryCard key={title} title={title} badge={<CatalogSummaryBadge color="green">active</CatalogSummaryBadge>} description="Reusable production scenario" details="2 sections · 4 outputs" />)}</CatalogSummaryGrid>,
+	readOnly: () => <TemplateCatalogBrowseGrid><TemplateCatalogBrowseCard title="Annual report" templateId="annual" preview={<span>Aa</span>} /><TemplateCatalogBrowseCard title="A long template title that wraps onto multiple lines" templateId="long" preview={<span>Aa</span>} /></TemplateCatalogBrowseGrid>,
+	metadata: () => <CatalogMetadataSummary title="Summary" ariaLabel="Template summary" items={[{ label: 'Name', value: 'Annual report', fullWidth: true }, { label: 'Type', value: 'Print' }, { label: 'Format', value: 'A4' }, { label: 'Reference ID', value: 'long-reference-123456789012345678901234567890', fullWidth: true }]} />,
+	browsing: () => <TemplateReferenceGrid columns={2}><TemplateReferenceItem title="Annual report" meta="Template" templateId="report" view="preview_grid" onOpen={() => undefined} preview={<span>Aa</span>} /><TemplateReferenceItem title="Unavailable" meta="Template" templateId="missing" view="preview_grid" isDisabled onOpen={() => undefined} preview={<span>Un</span>} /></TemplateReferenceGrid>,
+	list: () => <TemplateReferenceList><TemplateReferenceItem title="Annual report" meta="Template" templateId="report" view="compact_list" onOpen={() => undefined} preview={<span>Aa</span>} /><TemplateReferenceItem title="Unavailable" meta="Template" templateId="missing" view="compact_list" isDisabled onOpen={() => undefined} preview={<span>Un</span>} /></TemplateReferenceList>,
+	default: () => <TemplateCatalogGrid><Example /></TemplateCatalogGrid>,
+	variants: () => <TemplateCatalogGrid><Example /><Example selected /></TemplateCatalogGrid>,
+	states: () => <TemplateCatalogGrid><Example selected locked /><Example title="A long template title that wraps instead of disappearing behind an ellipsis" /></TemplateCatalogGrid>,
+}
+export const meta = { category: 'Composite', description: 'Selection tiles with a contained preview, keyboard focus and locked assignments. Hover and selection share the original green fill.' }

package/src/components/template-catalog-card.tsx

@@ -0,0 +1,178 @@
+import type { CSSProperties, ReactNode } from 'react'
+import { Button as AriaButton } from 'react-aria-components'
+import { uic } from '../utils/uic'
+import { Tile } from './tile'
+
+export const TEMPLATE_CATALOG_SELECTIONS = ['available', 'selected'] as const
+export type TemplateCatalogSelection = (typeof TEMPLATE_CATALOG_SELECTIONS)[number]
+
+/** Legacy StatsCard label-1 value, distinct from the Tile heading ramp. */
+export const CatalogMetricValue = uic('span', {
+	displayName: 'CatalogMetricValue',
+	baseClass: 'block w-full text-center text-display-large font-medium leading-(--line-height-display-large) tracking-wider',
+})
+
+export const CATALOG_METRIC_FOOTERS = ['present', 'missing'] as const
+export type CatalogMetricFooter = (typeof CATALOG_METRIC_FOOTERS)[number]
+const MetricContent = uic('div', {
+	displayName: 'CatalogMetricContent',
+	baseClass: 'flex min-h-0 w-full flex-1 flex-col items-center justify-center text-center',
+	variants: { footer: { present: '', missing: 'pb-12' } },
+})
+
+/** Compact source statistics: preserve the centered content band without a tail. */
+export function CatalogMetricCard({ title, value, footer, onPress, 'aria-label': ariaLabel }: {
+	title: string; value: ReactNode; footer?: string; onPress?: () => void; 'aria-label'?: string
+}) {
+	return <Tile theme="light" eyebrow={title} footer={footer || undefined} onPress={onPress}
+		aria-label={ariaLabel} className="h-52 min-h-52 max-h-52">
+		<MetricContent data-slot="catalog-metric-content" footer={footer ? 'present' : 'missing'}>
+			<CatalogMetricValue>{value}</CatalogMetricValue>
+		</MetricContent>
+	</Tile>
+}
+
+const SummaryCard = uic('article', { displayName: 'CatalogSummaryCard', baseClass: 'flex h-95 w-full min-w-0 flex-col gap-6 overflow-hidden rounded-lg bg-surface-card p-4 text-fg' })
+export const CatalogSummaryGrid = uic('div', { displayName: 'CatalogSummaryGrid', baseClass: 'grid w-full min-w-0 grid-cols-1 gap-x-2 gap-y-4 overflow-x-hidden min-[768px]:grid-cols-3 min-[768px]:gap-x-3' })
+const SummaryHead = uic('div', { displayName: 'CatalogSummaryHead', baseClass: 'flex w-full min-w-0 items-center justify-between gap-3' })
+export const CatalogSummaryBadge = uic('span', { displayName: 'CatalogSummaryBadge', baseClass: 'ml-3 flex h-6 shrink-0 items-center rounded-2xl px-2.5 text-micro font-medium leading-5', style: { fontFeatureSettings: '"liga" off, "clig" off' }, variants: { color: { green: 'bg-brand-green text-fg-on-brand', grey: 'bg-surface-muted text-(--color-neutral-600)' } }, defaultVariants: { color: 'grey' } })
+const SummaryTitle = uic('h2', { displayName: 'CatalogSummaryTitle', baseClass: 'm-0 min-w-0 truncate text-heading5 font-medium' })
+const SummaryTail = uic('div', { displayName: 'CatalogSummaryTail', baseClass: 'mt-auto flex flex-col gap-1 text-small font-normal text-fg-workflow-muted' })
+/** Display-only catalog tile. No synthetic imagery when a preview is absent. */
+export function CatalogSummaryCard({ title, badge, description, details }: { title: string; badge: ReactNode; description?: string; details: ReactNode }) {
+	return <SummaryCard><SummaryHead><SummaryTitle>{title}</SummaryTitle><span className="shrink-0">{badge}</span></SummaryHead><SummaryTail>{description ? <p className="m-0">{description}</p> : null}<span>{details}</span></SummaryTail></SummaryCard>
+}
+
+/** Compact launcher card. Missing artwork is not replaced by synthetic imagery. */
+export function CatalogLaunchCard({ title, description, details, action }: { title: string; description?: string; details: ReactNode; action: ReactNode }) {
+	return <SummaryCard data-testid="scenario-launch-card" className="relative h-70 min-h-70 max-h-70 transition-colors duration-200 focus-within:ring-2 focus-within:ring-ring">
+		<SummaryHead><SummaryTitle asChild><h3>{title}</h3></SummaryTitle></SummaryHead>
+		<SummaryTail>{description ? <p className="m-0">{description}</p> : null}<span>{details}</span></SummaryTail>
+		{action}
+	</SummaryCard>
+}
+
+const MetadataSection = uic('section', { displayName: 'CatalogMetadataSection', baseClass: 'm-0 w-full' })
+/** Source metadata layout: full-width identity, paired attributes, wrapping IDs. */
+export function CatalogMetadataSummary({ title, ariaLabel, items }: {
+	title: string; ariaLabel: string; items: { label: string; value: ReactNode; fullWidth?: boolean }[]
+}) {
+	let column = 0
+	return <MetadataSection aria-label={ariaLabel}>
+		<h2 className="mb-3 mt-0 text-heading3 font-medium text-fg">{title}</h2>
+		<dl className="m-0 grid w-full grid-cols-1 border-t border-border min-[641px]:grid-cols-2">
+			{items.map(item => {
+				const second = !item.fullWidth && column % 2 === 1
+				column = item.fullWidth ? 0 : column + 1
+				return <div key={item.label} className={`flex min-w-0 flex-col gap-1 border-b border-border py-3 ${item.fullWidth ? 'col-span-full' : ''} ${second ? 'min-[641px]:border-l min-[641px]:pl-3' : ''}`}>
+					<dt className="m-0 text-body font-normal text-fg-subtle">{item.label}</dt>
+					<dd className="m-0 text-body font-normal text-fg [overflow-wrap:anywhere]">{item.value}</dd>
+				</div>
+			})}
+		</dl>
+	</MetadataSection>
+}
+
+export const TEMPLATE_REFERENCE_VIEWS = ['preview_grid', 'compact_list'] as const
+export type TemplateReferenceView = (typeof TEMPLATE_REFERENCE_VIEWS)[number]
+export const TemplateReferenceGrid = uic('div', {
+	displayName: 'TemplateReferenceGrid',
+	baseClass: 'grid w-full grid-cols-1 gap-3',
+	variants: { columns: { 1: 'grid-cols-1', 2: 'min-[761px]:grid-cols-2', 3: 'min-[761px]:grid-cols-3' } },
+	defaultVariants: { columns: 1 },
+})
+export const TemplateReferenceList = uic('div', {
+	displayName: 'TemplateReferenceList', baseClass: 'flex w-full flex-col gap-2',
+})
+const ReferenceButton = uic(AriaButton, {
+	displayName: 'TemplateReferenceButton',
+	baseClass: 'w-full cursor-pointer border-0 p-0 text-start outline-none disabled:cursor-default data-[focus-visible]:ring-2 data-[focus-visible]:ring-ring data-[focus-visible]:ring-offset-2',
+	variants: { view: {
+		preview_grid: 'flex aspect-square items-center justify-center overflow-hidden rounded-lg bg-surface-card',
+		compact_list: 'grid min-h-14 grid-cols-[3rem_minmax(0,1fr)] items-center gap-3 border-b border-border bg-transparent last:border-b-0',
+	} },
+})
+/** Read-only browsing surfaces: activation opens a preview, never selects it. */
+export function TemplateReferenceItem({ title, meta, preview, view, isDisabled, onOpen, templateId }: {
+	title: string; meta: string; preview: ReactNode; view: TemplateReferenceView
+	isDisabled?: boolean; onOpen: () => void; templateId: string
+}) {
+	return <ReferenceButton type="button" view={view} isDisabled={isDisabled} onPress={onOpen} aria-label={title} data-template-id={templateId}>
+		<span aria-hidden="true" className={view === 'compact_list' ? 'flex size-12 items-center justify-center overflow-hidden rounded-sm bg-surface-card [&>div]:w-full' : 'flex h-full w-full items-center justify-center [&>div]:w-full'}>{preview}</span>
+		{view === 'compact_list' ? <span className="flex min-w-0 flex-col gap-1"><span className="truncate text-small font-medium text-fg">{title}</span><span className="truncate text-label font-medium text-fg-subtle">{meta}</span></span> : null}
+	</ReferenceButton>
+}
+
+export const TemplateCatalogGrid = uic('div', {
+	displayName: 'TemplateCatalogGrid',
+	baseClass: 'grid w-full min-w-0 grid-cols-1 items-stretch gap-2 p-0 md:grid-cols-2 md:gap-3 lg:grid-cols-3',
+})
+
+const Card = uic(AriaButton, {
+	displayName: 'TemplateCatalogCardSurface',
+	baseClass: 'group box-border flex h-(--template-catalog-height) min-w-0 w-full cursor-pointer flex-col gap-6 overflow-hidden rounded-lg border-0 p-4 text-start outline-none transition-colors duration-200 motion-reduce:transition-none hover:bg-brand-green hover:text-fg-on-brand data-[focus-visible]:ring-2 data-[focus-visible]:ring-ring data-[focus-visible]:ring-offset-2',
+	variants: {
+		selection: {
+			available: 'bg-surface-card text-fg',
+			selected: 'bg-brand-green text-fg-on-brand',
+		},
+	},
+	defaultVariants: { selection: 'available' },
+})
+const Title = uic('span', {
+	displayName: 'TemplateCatalogCardTitle',
+	baseClass: 'block min-h-5 min-w-0 shrink-0 text-body font-medium leading-5',
+})
+const Preview = uic('span', {
+	displayName: 'TemplateCatalogCardPreview',
+	baseClass: 'box-border flex min-h-0 w-full flex-1 items-center justify-center overflow-hidden rounded-md bg-transparent p-3 [&>div]:w-full',
+})
+
+const geometry: CSSProperties & { '--template-catalog-height': string } = {
+	'--template-catalog-height': 'clamp(calc(var(--spacing) * 64), 30vw, calc(var(--spacing) * 76))',
+	letterSpacing: 0,
+}
+
+export const TemplateCatalogBrowseGrid = uic('div', {
+	displayName: 'TemplateCatalogBrowseGrid',
+	baseClass: 'grid w-full min-w-0 grid-cols-1 items-stretch gap-2 p-0 md:grid-cols-2 md:gap-3 lg:grid-cols-4',
+})
+const BrowseCard = uic('div', {
+	displayName: 'TemplateCatalogBrowseSurface',
+	baseClass: 'box-border flex h-(--template-catalog-height) min-w-0 w-full cursor-default flex-col gap-6 overflow-hidden rounded-lg border-0 bg-surface-card p-4 text-start text-fg outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2',
+})
+/** Legacy readOnly catalog: no activation, hover shadow or extra card CTA. */
+export function TemplateCatalogBrowseCard({ title, preview, templateId, id, testId }: {
+	title: string; preview: ReactNode; templateId: string; id?: string; testId?: string
+}) {
+	return <BrowseCard role="group" tabIndex={0} aria-label={title} id={id} data-catalog-template-id={templateId} data-testid={testId} style={geometry}>
+		<Title>{title}</Title><Preview aria-hidden="true" className="pointer-events-none">{preview}</Preview>
+	</BrowseCard>
+}
+
+/** Selection-only catalog tile. No badge, selected ring, nested action, or artwork
+ * rounding is added. A locked assignment stays focusable and selected, just as in
+ * the original catalog; aria-disabled and the press guard prevent its removal.
+ * The caller owns selection and supplies a non-interactive, contain-fit preview.
+ */
+export function TemplateCatalogCard({ title, preview, isSelected = false, isSelectionLocked = false,
+	onToggle, onOpen, templateId, testId,
+}: {
+	title: string
+	preview: ReactNode
+	isSelected?: boolean
+	isSelectionLocked?: boolean
+	onToggle?: () => void
+	/** Browsing mode opens a preview, without announcing a toggle state. */
+	onOpen?: () => void
+	templateId?: string
+	testId?: string
+}) {
+	return <Card type="button" selection={isSelected ? 'selected' : 'available'}
+		aria-label={title} aria-pressed={onOpen ? undefined : isSelected} aria-disabled={isSelectionLocked}
+		data-template-id={templateId} data-testid={testId} style={geometry}
+		onPress={() => { if (!isSelectionLocked) { if (onOpen) onOpen(); else onToggle?.() } }}>
+		<Title>{title}</Title>
+		<Preview aria-hidden="true">{preview}</Preview>
+	</Card>
+}