@podoba/react 0.0.34 → 0.0.36

package/src/components/dialog-action-button.examples.tsx

@@ -0,0 +1,7 @@
+import { DialogActionButton } from './dialog-action-button'
+export const examples = {
+	default: () => <DialogActionButton>Review Mapping</DialogActionButton>,
+	variants: () => <><DialogActionButton variant="secondary">Change CSV</DialogActionButton><DialogActionButton>Bind CSV</DialogActionButton></>,
+	states: () => <><DialogActionButton isDisabled>Bind CSV</DialogActionButton><DialogActionButton isPending>Binding CSV…</DialogActionButton></>,
+}
+export const meta = { category: 'Primitives', description: 'Source UI dialog action palette, typography and pointer/keyboard states, independent of dashboard CTAs.' }

package/src/components/dialog-action-button.tsx

@@ -0,0 +1,22 @@
+import { Button as AriaButton } from 'react-aria-components'
+import { uic } from '../utils/uic'
+
+export const DIALOG_ACTION_VARIANTS = ['primary', 'secondary'] as const
+export type DialogActionVariant = (typeof DIALOG_ACTION_VARIANTS)[number]
+
+/** Source UI dialog action, distinct from the frontend dashboard CTA Button.
+ * Shares Button's semantic palette (brand-primary / surface-card) so the two never
+ * drift apart; only the geometry — pill radius, 24/12 padding — is specific here.
+ * Keyboard focus retains the shared RAC treatment.
+ */
+export const DialogActionButton = uic(AriaButton, {
+	displayName: 'DialogActionButton',
+	baseClass: 'inline-flex items-center justify-center rounded-full px-6 py-3 text-body font-medium leading-5 cursor-pointer transition-colors duration-200 motion-reduce:transition-none outline-none ' +
+		'data-[focus-visible]:ring-2 data-[focus-visible]:ring-ring data-[focus-visible]:ring-offset-2 ' +
+		'data-[disabled]:opacity-50 data-[disabled]:cursor-not-allowed data-[pending]:cursor-progress',
+	variants: { variant: {
+		primary: 'border-0 bg-brand-primary text-fg-inverted data-[hovered]:bg-neutral-600 data-[pressed]:bg-brand-primary',
+		secondary: 'border border-border bg-surface-card text-fg data-[hovered]:bg-surface-muted data-[hovered]:border-border-muted data-[pressed]:bg-surface-muted',
+	} },
+	defaultVariants: { variant: 'primary' },
+})

package/src/components/dialog.tsx

@@ -32,7 +32,7 @@ export const ModalOverlay = uic(RACModalOverlay, {
 export const ModalSurface = uic(RACModal, {
 	displayName: 'DialogModal',
 	baseClass:
-		'rounded-lg bg-surface p-5 outline-none shadow-modal-surface ' +
+		'relative rounded-lg bg-surface p-5 outline-none shadow-modal-surface ' +
 		'data-[entering]:animate-modal-surface-in data-[exiting]:animate-modal-surface-out',
 })
 
@@ -92,6 +92,10 @@ export type DialogProps = RACDialogProps & {
 	badge?: ReactNode
 	/** Width preset — `md` (default) for forms; `sm` for tight confirms; `lg`/`xl` for wide stepper content. */
 	size?: DialogSize
+	/** Optional form-specific width cap; the viewport width preset still applies. */
+	maxWidth?: number
+	/** Responsive intrinsic detail envelope, independent of title sizing. */
+	widthPreset?: 'responsive-detail' | 'custom-task-detail'
 	children: ReactNode | ((opts: { close: () => void }) => ReactNode)
 	/**
 	 * Controlled open state. Provide together with `onOpenChange` to drive the
@@ -115,6 +119,8 @@ export const Dialog = ({
 	badge,
 	// gs DialogContent defaults to `md` (586px form width).
 	size = 'md',
+	maxWidth,
+	widthPreset,
 	children,
 	isOpen,
 	defaultOpen,
@@ -126,6 +132,11 @@ export const Dialog = ({
 	// `full` is a fixed-height flex canvas: the body fills and scrolls internally so
 	// the header (+ a footer the content pins) stay put. Other sizes are content-height.
 	const isFlex = size === 'full'
+	// The Manager header treatment — block layout, floated close, label-ramp
+	// description — belongs to the OPT-IN width presets, not to "any dialog that
+	// isn't `full`". Gating it on `isFlex` made every sm/md/lg/xl dialog render a
+	// display-scale title and stranded `TITLE_CLASS` on the single `full` size.
+	const isCompact = widthPreset !== undefined
 	return (
 		// `isOpen`/`defaultOpen`/`onOpenChange` go to the RAC ModalOverlay: when
 		// provided the dialog is controlled (renders independently of a DialogTrigger);
@@ -142,19 +153,28 @@ export const Dialog = ({
 			onOpenChange={onOpenChange}
 			isDismissable={isDismissable}
 		>
-			<ModalSurface className={SIZE_CLASS[size]}>
+			<ModalSurface
+				className={
+					widthPreset === 'responsive-detail'
+						? 'w-[90vw] max-w-125 md:max-w-150 lg:max-w-160 xl:max-w-180 max-h-[85vh] overflow-y-auto'
+						: widthPreset === 'custom-task-detail'
+							? 'w-[90vw] min-w-[400px] max-w-[500px] md:max-w-[600px] lg:max-w-[640px] xl:max-w-[720px] max-h-[85vh] overflow-y-auto max-[460px]:min-w-0'
+							: SIZE_CLASS[size]
+				}
+				style={maxWidth === undefined ? undefined : { maxWidth }}
+			>
 				<ModalDialog
 					{...props}
 					className={isFlex ? 'flex min-h-0 flex-1 flex-col outline-none' : 'outline-none'}
 				>
 					{(renderProps) => (
 						<>
-							<div className="mb-4 flex shrink-0 items-start justify-between gap-4">
+							<div className={isCompact ? 'block' : 'mb-4 flex shrink-0 items-start justify-between gap-4'}>
 								{title || description ? (
 									<div className="min-w-0">
 										{title ? (
 											<div className="flex items-center gap-2">
-												<Heading slot="title" className={`${TITLE_CLASS[size]} text-fg`}>
+												<Heading slot="title" className={isCompact ? 'm-0 mb-4 max-w-5/6 text-heading1 font-medium tracking-normal text-fg' : `${TITLE_CLASS[size]} text-fg`}>
 													{title}
 												</Heading>
 												{badge ? (
@@ -165,8 +185,8 @@ export const Dialog = ({
 											</div>
 										) : null}
 										{description ? (
-											// gs `.description` = base 16px, text-secondary (=fg).
-											<p className="mt-1 text-body text-fg">{description}</p>
+											// Source ordinary descriptions use the 14px/18px label ramp.
+											<p className={isCompact ? 'm-0 mb-6 max-w-5/6 text-small leading-4.5 font-normal text-fg-workflow-muted' : 'mt-1 text-body text-fg'}>{description}</p>
 										) : null}
 									</div>
 								) : (
@@ -179,19 +199,19 @@ export const Dialog = ({
 									// gs close: 32px square (`h-8 w-8`), medium radius (`rounded-md`),
 									// tertiary icon color (`text-fg-subtle`) → primary (`text-fg`) +
 									// subtle hover bg on hover. Smooth color transition.
-									className="-mr-1 -mt-1 inline-flex h-8 w-8 shrink-0 items-center justify-center rounded-md text-fg-subtle outline-none transition-colors hover:bg-surface-muted hover:text-fg focus-visible:ring-2 focus-visible:ring-ring"
+									className={`${isCompact ? 'absolute top-[calc(var(--spacing)*3.375)] end-4 max-md:end-3' : '-mr-1 -mt-1'} inline-flex h-8 w-8 shrink-0 items-center justify-center rounded-md text-fg-subtle outline-none transition-colors hover:bg-surface-muted hover:text-fg focus-visible:ring-2 focus-visible:ring-ring motion-reduce:transition-none`}
 								>
 									<svg
-										width="18"
-										height="18"
-										viewBox="0 0 24 24"
+										width={isCompact ? 15 : 18}
+										height={isCompact ? 15 : 18}
+										viewBox={isCompact ? '0 0 15 15' : '0 0 24 24'}
 										fill="none"
-										stroke="currentColor"
+										stroke={isCompact ? undefined : 'currentColor'}
 										strokeWidth="2"
 										strokeLinecap="round"
 										aria-hidden="true"
 									>
-										<path d="M6 6l12 12M18 6 6 18" />
+										<path fill={isCompact ? 'currentColor' : undefined} d={isCompact ? 'M11.7816 4.03157C12.0062 3.80702 12.0062 3.44295 11.7816 3.2184C11.5571 2.99385 11.193 2.99385 10.9685 3.2184L7.50005 6.68682L4.03164 3.2184C3.80708 2.99385 3.44301 2.99385 3.21846 3.2184C2.99391 3.44295 2.99391 3.80702 3.21846 4.03157L6.68688 7.49999L3.21846 10.9684C2.99391 11.193 2.99391 11.557 3.21846 11.7816C3.44301 12.0061 3.80708 12.0061 4.03164 11.7816L7.50005 8.31316L10.9685 11.7816C11.193 12.0061 11.5571 12.0061 11.7816 11.7816C12.0062 11.557 12.0062 11.193 11.7816 10.9684L8.31322 7.49999L11.7816 4.03157Z' : 'M6 6l12 12M18 6 6 18'} />
 									</svg>
 								</button>
 							</div>

package/src/components/document-upload-panel.examples.tsx

@@ -0,0 +1,12 @@
+import { DocumentUploadPanel } from './document-upload-panel'
+
+const copy = { title: 'CSV file', actionLabel: 'Select CSV', helperText: 'No CSV file selected yet.\nSelect the CSV file for content mapping.' }
+export const examples = {
+	default: () => <DocumentUploadPanel {...copy} />,
+	dragging: () => <DocumentUploadPanel {...copy} isDragging />,
+	disabled: () => <DocumentUploadPanel {...copy} isDisabled />,
+}
+export const meta = {
+	category: 'Form',
+	description: 'Upload tile with a centred keyboard-accessible action and a native drop surface. Focus/hover use the shared React Aria button; caller owns file validation.',
+}

package/src/components/document-upload-panel.tsx

@@ -0,0 +1,48 @@
+import type { DragEventHandler, ReactNode } from 'react'
+import { uic } from '../utils/uic'
+import { DialogActionButton } from './dialog-action-button'
+import { Tile } from './tile'
+
+const Surface = uic('div', {
+	displayName: 'DocumentUploadSurface',
+	baseClass: 'relative h-95 w-full',
+})
+
+/** Source upload tile: label at top, action centred in the WHOLE tile, helper at bottom.
+ * File ownership, validation and persistence belong to the caller. The real button
+ * provides the keyboard alternative to native file drag/drop.
+ */
+export function DocumentUploadPanel({
+	title, actionLabel, helperText, isDragging = false, isDisabled = false,
+	onAction, onDrop, onDragEnter, onDragOver, onDragLeave,
+	...rest
+}: {
+	title: ReactNode
+	actionLabel: string
+	helperText?: string
+	isDragging?: boolean
+	isDisabled?: boolean
+	onAction?: () => void
+	onDrop?: DragEventHandler<HTMLDivElement>
+	onDragEnter?: DragEventHandler<HTMLDivElement>
+	onDragOver?: DragEventHandler<HTMLDivElement>
+	onDragLeave?: DragEventHandler<HTMLDivElement>
+	'data-testid'?: string
+}) {
+	return <Surface {...rest} onDrop={onDrop} onDragEnter={onDragEnter} onDragOver={onDragOver} onDragLeave={onDragLeave}>
+		<Tile theme="light" className={isDragging && !isDisabled ? 'ring-2 ring-inset ring-fg-subtle' : undefined}
+			eyebrow={<span className="relative z-10 mb-2 text-body font-medium leading-5">{title}</span>}
+			footer={helperText ? <p className="relative z-10 m-0 whitespace-pre-line text-small font-normal text-fg-workflow-muted" style={{ lineHeight: 'normal' }}>
+				{/* Original Tile's `.tile .tail *` wins over the upload helper classes:
+				    BOTH lines inherit the regular muted supporting text. */}
+				{helperText}
+			</p> : undefined}
+		/>
+		<div className="pointer-events-none absolute inset-0 flex items-center justify-center">
+			<DialogActionButton type="button" isDisabled={isDisabled} onPress={onAction}
+				className="pointer-events-auto h-14 w-48 min-w-48 py-0">
+				{actionLabel}
+			</DialogActionButton>
+		</div>
+	</Surface>
+}

package/src/components/dropdown-menu.tsx

@@ -43,7 +43,8 @@ import { uic } from '../utils/uic'
  * tokens): content bg white → `surface` · 1px `#eceae1` border → `border` · 8px
  * radius → `rounded-lg` · `shadow-lg` · item 12/16px padding → `py-3 px-4` · 6px
  * item radius → `rounded-md` · item hover `#f7f6f2` → `surface-card` · item text
- * `#0d0d0d` → `fg` · section label `#aba89c` 13px → `text-fg-subtle text-compact`
+ * `#0d0d0d` → `fg` · section label `#aba89c` 13px → `text-fg-muted text-compact`
+ * (#25: the source grey is 2.10:1 on `surface`; a section label is read, not ornament)
  * · separator `#eceae1` → `border`. The destructive item uses `text-danger`
  * (`#dc2626`) — a light-surface red that reads correctly here (unlike the dark
  * ContextMenu, which needs the lighter `#ffb5b5`).
@@ -82,7 +83,8 @@ export const DropdownMenuSeparator = uic(RACSeparator, {
 export interface DropdownMenuSectionProps<T extends object> extends Omit<RACMenuSectionProps<T>, 'children'> {
 	/**
 	 * Section label (gs `.label`). Rendered as a non-interactive `Header` — 13px
-	 * medium, `fg-subtle` — above the section's items.
+	 * medium, `fg-muted` — above the section's items. (The source grey `fg-subtle`
+	 * is 2.10:1 on `surface`; a section label is read, not ornament — #25.)
 	 */
 	label?: ReactNode
 	/** Static section items (each a {@link DropdownMenuItem}). */
@@ -98,7 +100,7 @@ export function DropdownMenuSection<T extends object>({
 	return (
 		<RACMenuSection {...props}>
 			{label ? (
-				<Header className="px-4 py-3 text-compact font-medium text-fg-subtle">{label}</Header>
+				<Header className="px-4 py-3 text-compact font-medium text-fg-muted">{label}</Header>
 			) : null}
 			{children}
 		</RACMenuSection>

package/src/components/empty-panel-action.examples.tsx

@@ -0,0 +1,7 @@
+import { EmptyPanelAction } from './empty-panel-action'
+export const examples = {
+ default: () => <EmptyPanelAction>Add deadline</EmptyPanelAction>,
+ variants: () => <EmptyPanelAction>Select assets</EmptyPanelAction>,
+ states: () => <><EmptyPanelAction isDisabled>Add deadline</EmptyPanelAction><EmptyPanelAction isPending>Loading</EmptyPanelAction></>,
+}
+export const meta = { category: 'Composite', description: 'Source dashboard empty action: 56px height, 192px minimum width and 16/20 medium text. Uses RAC focus, disabled and pending states.' }

package/src/components/empty-panel-action.tsx

@@ -0,0 +1,8 @@
+import { uic } from '../utils/uic'
+import { DialogActionButton } from './dialog-action-button'
+
+/** Centered action for an empty dashboard panel; keeps the source UI action palette. */
+export const EmptyPanelAction = uic(DialogActionButton, {
+ displayName: 'EmptyPanelAction',
+ baseClass: 'h-14 min-w-48 px-6 py-0 text-body font-medium leading-5',
+})

package/src/components/field-appearance.ts

@@ -0,0 +1,14 @@
+export const FIELD_APPEARANCES = ['outlined', 'filled'] as const
+export type FieldAppearance = (typeof FIELD_APPEARANCES)[number]
+
+/** Borderless Manager field skin. Hover yields to focus; focus uses an offset
+ * outline instead of combining the browser outline with a second inset ring.
+ * Placeholder/error colors retain the library's accessible semantic tokens.
+ */
+export const filledFieldClasses =
+	'border-0 bg-surface-card text-small font-normal leading-4.5 text-fg ' +
+	'outline-none transition-colors duration-200 motion-reduce:transition-none placeholder:text-fg-muted placeholder:font-normal ' +
+	'data-[hovered]:bg-surface-muted data-[focused]:bg-surface-card ' +
+	'focus-visible:outline-2 focus-visible:outline-ring focus-visible:outline-offset-2 ' +
+	'data-[invalid]:ring-1 data-[invalid]:ring-danger data-[invalid]:outline-danger ' +
+	'data-[disabled]:bg-surface-muted data-[disabled]:opacity-50 data-[disabled]:cursor-not-allowed'

package/src/components/focus-field.tsx

@@ -85,8 +85,8 @@ export function FocusFields({ children, className }: { children: ReactNode; clas
 
 // In the overlay, enlarge and de-chrome text controls into a bare headline editor.
 const OVERLAY_EDITOR =
-	'[&_input]:w-full [&_input]:border-0 [&_input]:bg-transparent [&_input]:p-0 [&_input]:text-display [&_input]:font-medium [&_input]:text-fg [&_input]:outline-none [&_input]:shadow-none [&_input]:ring-0 [&_input]:placeholder:text-fg-subtle ' +
-	'[&_textarea]:min-h-40 [&_textarea]:w-full [&_textarea]:resize-none [&_textarea]:border-0 [&_textarea]:bg-transparent [&_textarea]:p-0 [&_textarea]:text-display [&_textarea]:font-medium [&_textarea]:text-fg [&_textarea]:outline-none [&_textarea]:placeholder:text-fg-subtle'
+	'[&_input]:w-full [&_input]:border-0 [&_input]:bg-transparent [&_input]:p-0 [&_input]:text-display [&_input]:font-medium [&_input]:text-fg [&_input]:outline-none [&_input]:shadow-none [&_input]:ring-0 [&_input]:placeholder:text-fg-muted ' +
+	'[&_textarea]:min-h-40 [&_textarea]:w-full [&_textarea]:resize-none [&_textarea]:border-0 [&_textarea]:bg-transparent [&_textarea]:p-0 [&_textarea]:text-display [&_textarea]:font-medium [&_textarea]:text-fg [&_textarea]:outline-none [&_textarea]:placeholder:text-fg-muted'
 
 function IconBadge({ icon }: { icon: ReactNode }) {
 	return (
@@ -166,7 +166,7 @@ export function FocusField({
 				<div className="min-w-0 flex-1">
 					<div className="text-small text-fg-muted">{label}</div>
 					<div className="mt-1 truncate text-body text-fg">
-						{hasValue ? preview : <span className="text-fg-subtle">{placeholder}</span>}
+						{hasValue ? preview : <span className="text-fg-muted">{placeholder}</span>}
 					</div>
 				</div>
 			</div>

package/src/components/icons.tsx

@@ -78,6 +78,36 @@ export const ExternalLinkIcon = (p: IconProps) => (
 		<path d="M15 3h6v6M21 3l-9 9M10 5H5a2 2 0 0 0-2 2v12a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2v-5" />
 	</svg>
 )
+export const PencilIcon = (p: IconProps) => (
+	<svg {...STROKE} {...p}>
+		<path d="M12 20h9" />
+		<path d="M16.5 3.5a2.12 2.12 0 0 1 3 3L8 18l-4 1 1-4z" />
+	</svg>
+)
+export const CopyIcon = (p: IconProps) => (
+	<svg {...STROKE} {...p}>
+		<rect x="9" y="9" width="11" height="11" rx="2" />
+		<path d="M15 9V6a2 2 0 0 0-2-2H6a2 2 0 0 0-2 2v7a2 2 0 0 0 2 2h3" />
+	</svg>
+)
+export const ShareIcon = (p: IconProps) => (
+	<svg {...STROKE} {...p}>
+		<circle cx="18" cy="5" r="3" />
+		<circle cx="6" cy="12" r="3" />
+		<circle cx="18" cy="19" r="3" />
+		<path d="m8.6 10.5 6.8-4M8.6 13.5l6.8 4" />
+	</svg>
+)
+export const PinIcon = (p: IconProps) => (
+	<svg {...STROKE} {...p}>
+		<path d="m9 3 6 6M10 8l-5 5 6 1 1 6 5-5M2 22l6-6" />
+	</svg>
+)
+export const ArchiveIcon = (p: IconProps) => (
+	<svg {...STROKE} {...p}>
+		<path d="M4 7v13h16V7M3 3h18v4H3zM9 11h6" />
+	</svg>
+)
 export const ExpandIcon = (p: IconProps) => (
 	<svg {...STROKE} {...p}><path d="M15 3h6v6M9 21H3v-6M21 3l-7 7M3 21l7-7" /></svg>
 )

package/src/components/input.examples.tsx

@@ -0,0 +1,8 @@
+import { Input } from './input'
+
+export const examples = {
+	default: () => <Input label="Project name" placeholder="Annual report" />,
+	variants: () => <><Input label="Outlined" /><Input appearance="filled" label="Filled" placeholder="Annual report" /></>,
+	states: () => <><Input appearance="filled" label="Disabled" defaultValue="Saved content" isDisabled /><Input appearance="filled" label="Invalid" isInvalid errorMessage="Check the value." /></>,
+}
+export const meta = { category: 'Form', description: 'Labelled input with outlined and Manager-style filled appearances, disabled/error states and keyboard focus.' }

package/src/components/input.tsx

@@ -8,6 +8,7 @@ import {
 	type TextFieldProps,
 } from 'react-aria-components'
 import { uic } from '../utils/uic'
+import { filledFieldClasses, type FieldAppearance } from './field-appearance'
 
 /**
  * Input — labelled single-line text field.
@@ -28,29 +29,36 @@ const StyledInput = uic(RACInput, {
 	// fg-subtle · focus #75e7b8 → brand-green · error → danger. This is the shared
 	// filled-field skin (textarea / combobox / date-field / number-field /
 	// search-field); `fieldSize` adds the single-line height on top.
-	baseClass:
-		'w-full rounded-lg border border-border bg-surface px-4 text-small text-fg ' +
+	baseClass: 'w-full rounded-lg px-4',
+	variants: {
+		appearance: {
+			filled: filledFieldClasses,
+			outlined: 'border border-border bg-surface text-small text-fg ' +
 		'outline-none transition-colors duration-200 placeholder:text-fg-muted ' +
 		'data-[hovered]:border-fg-subtle ' +
 		'data-[focused]:border-brand-green data-[focused]:ring-2 data-[focused]:ring-ring ' +
 		'data-[invalid]:border-danger data-[invalid]:ring-2 data-[invalid]:ring-danger ' +
 		'data-[disabled]:bg-surface-muted data-[disabled]:opacity-60 data-[disabled]:pointer-events-none',
-	variants: {
+		},
 		// `fieldSize` (not `size`) to avoid colliding with the native <input size>
 		// attribute, which RAC's Input inherits (a numeric prop).
 		fieldSize: {
 			sm: 'h-8',
 			md: 'h-10',
+			filled: 'h-10.5 py-3',
 			lg: 'h-12',
 			tall: 'h-control-tall',
 		},
 	},
 	defaultVariants: {
+		appearance: 'outlined',
 		fieldSize: 'md',
 	},
 })
 
 export type InputProps = TextFieldProps & {
+	/** Filled matches the original Manager dialog fields; outlined remains the default. */
+	appearance?: FieldAppearance
 	/** Visible field label (required for accessibility). */
 	label: ReactNode
 	/** Helper text rendered under the field. */
@@ -65,10 +73,10 @@ export type InputProps = TextFieldProps & {
 	inputClassName?: string
 }
 
-export const Input = ({ label, description, errorMessage, placeholder, size, rootClassName, inputClassName, ...props }: InputProps) => (
+export const Input = ({ label, description, errorMessage, placeholder, size, appearance = 'outlined', rootClassName, inputClassName, ...props }: InputProps) => (
 	<TextField {...props} className={`flex w-full flex-col gap-3 ${rootClassName ?? ''}`}>
 		<Label className="text-panel-heading font-medium text-fg">{label}</Label>
-		<StyledInput className={inputClassName} placeholder={placeholder} fieldSize={size} />
+		<StyledInput className={inputClassName} placeholder={placeholder} appearance={appearance} fieldSize={size ?? (appearance === 'filled' ? 'filled' : undefined)} />
 		{description ? (
 			<Text slot="description" className="text-label text-fg-muted">
 				{description}

package/src/components/media-asset-panel.examples.tsx

@@ -0,0 +1,11 @@
+import { MediaAssetPanel } from './media-asset-panel'
+const labels = { heading: 'Assets', emptyDescription: 'No assets yet.', emptyHint: 'Select assets to begin.', selectLabel: 'Select assets', previousLabel: 'Previous asset', nextLabel: 'Next asset' }
+const items = ['First', 'Second'].map(id => ({ id, content: <div className="grid h-full place-items-center bg-surface-muted">{id}</div> }))
+export const examples = {
+	default: () => <MediaAssetPanel {...labels} items={items} mode="media" empty={false} onSelect={() => undefined} />,
+	variants: () => <MediaAssetPanel {...labels} items={items} mode="carousel" empty={false} onSelect={() => undefined} />,
+	states: () => <MediaAssetPanel {...labels} items={[]} mode="media" empty onSelect={() => undefined} />,
+	readOnly: () => <MediaAssetPanel {...labels} items={items} mode="grid" empty={false} />,
+	reference: () => <MediaAssetPanel {...labels} items={items.slice(0, 1)} mode="media" empty={false} identity={{ title: 'Annual report', caption: '1 asset reference', count: 1 }} onSelect={() => undefined} />,
+}
+export const meta = { category: 'Composite', description: 'Asset preview panel with centered empty action and independent carousel controls.' }

package/src/components/media-asset-panel.tsx

@@ -0,0 +1,58 @@
+import type { ReactNode } from 'react'
+import { Button as AriaButton } from 'react-aria-components'
+import { uic } from '../utils/uic'
+import { Button } from './button'
+import { MediaGallery, type MediaGalleryItem } from './media-gallery'
+
+export const MEDIA_ASSET_PANEL_MODES = ['media', 'grid', 'carousel'] as const
+export type MediaAssetPanelMode = (typeof MEDIA_ASSET_PANEL_MODES)[number]
+export type MediaAssetPanelProps = {
+	items: readonly MediaGalleryItem[]
+	mode: MediaAssetPanelMode
+	empty: boolean
+	heading: ReactNode
+	emptyDescription: ReactNode
+	emptyHint: ReactNode
+	selectLabel: string
+	previousLabel: string
+	nextLabel: string
+	onSelect?: () => void
+	/** Optional reference identity; omitted for a media-only gallery. */
+	identity?: { title: ReactNode; caption: ReactNode; count: ReactNode }
+	className?: string
+}
+const Surface = uic('div', {
+	displayName: 'MediaAssetPanel',
+	baseClass: 'group/media-panel relative isolate h-95 w-full shrink-0 overflow-hidden rounded-lg bg-surface-card text-fg',
+})
+const PanelAction = uic(AriaButton, {
+	displayName: 'MediaAssetPanelAction',
+	baseClass: 'absolute inset-0 z-10 cursor-pointer rounded-lg border-0 bg-transparent p-0 outline-none data-[focus-visible]:ring-2 data-[focus-visible]:ring-inset data-[focus-visible]:ring-ring',
+})
+
+/** Full-bleed media with independent selection and carousel controls. */
+export function MediaAssetPanel({ items, mode, empty, heading, emptyDescription, emptyHint, selectLabel, previousLabel, nextLabel, onSelect, identity, className }: MediaAssetPanelProps) {
+	return <Surface className={className}>
+		{onSelect ? empty
+			? <button type="button" aria-label={selectLabel} aria-hidden="true" tabIndex={-1} onClick={onSelect} className="absolute inset-0 z-10 cursor-pointer rounded-lg border-0 bg-transparent p-0" />
+			: <PanelAction aria-label={selectLabel} onPress={onSelect} /> : null}
+		{empty ? <>
+			<div className="pointer-events-none absolute inset-x-4 top-4 z-20 text-body font-medium leading-5">{heading}</div>
+			{onSelect ? <div className="pointer-events-none absolute inset-0 z-20 flex items-center justify-center">
+				<Button className="pointer-events-auto h-14 w-48 p-0" onPress={onSelect}>{selectLabel}</Button>
+			</div> : null}
+			<p className="pointer-events-none absolute inset-x-4 bottom-4 z-20 m-0 text-small">
+				<span className="font-medium text-fg">{emptyDescription}</span><br />
+				<span className="text-fg-muted">{emptyHint}</span>
+			</p>
+		</> : <MediaGallery items={mode === 'media' ? items.slice(0, 1) : items} mode={mode === 'carousel' ? 'carousel' : 'grid'} previousLabel={previousLabel} nextLabel={nextLabel} className="pointer-events-none" />}
+		{!empty && identity ? <>
+			<div aria-hidden="true" className="pointer-events-none absolute inset-y-0 left-0 z-[1] hidden w-[min(56%,34rem)] bg-[linear-gradient(90deg,rgba(0,0,0,0.52)_0%,rgba(0,0,0,0.28)_58%,transparent_100%)] group-has-[img]/media-panel:block" />
+			<div className="pointer-events-none absolute inset-4 z-[2] grid grid-rows-[auto_minmax(0,1fr)_auto] gap-6 text-fg group-has-[img]/media-panel:text-white group-has-[img]/media-panel:[text-shadow:0_1px_3px_rgba(0,0,0,0.5)]">
+				<div className="mb-2 flex items-start justify-between gap-2 text-body font-medium leading-5"><span>{heading}</span><span className="rounded-full bg-surface-muted px-2.5 py-1 text-caption text-fg [text-shadow:none]">{identity.count}</span></div>
+				<p className="m-0 max-w-[19ch] pt-2 text-heading1 font-medium leading-[30px]">{identity.title}</p>
+				<p className="m-0 text-small opacity-80">{identity.caption}</p>
+			</div>
+		</> : null}
+	</Surface>
+}

package/src/components/media-gallery.examples.tsx

@@ -0,0 +1,12 @@
+import { MediaGallery } from './media-gallery'
+
+const sample = (label: string) => <div className="grid h-full min-h-24 place-items-center bg-surface-card text-label text-fg">{label}</div>
+const items = ['One', 'Two', 'Three', 'Four'].map(label => ({ id: label.toLowerCase(), content: sample(label) }))
+
+export const examples = {
+	default: () => <MediaGallery items={items.slice(0, 1)} mode="grid" previousLabel="Previous" nextLabel="Next" className="h-48" />,
+	grid: () => <MediaGallery items={items} mode="grid" previousLabel="Previous" nextLabel="Next" className="h-48" />,
+	carousel: () => <MediaGallery items={items.slice(0, 3)} mode="carousel" previousLabel="Previous image" nextLabel="Next image" className="h-48" />,
+	empty: () => <div className="h-48"><MediaGallery items={[]} mode="grid" previousLabel="Previous" nextLabel="Next" /></div>,
+}
+export const meta = { category: 'Composite', description: 'Media grid and carousel with consumer-rendered previews. Coarse-pointer controls use 44px targets.' }

package/src/components/media-gallery.tsx

@@ -0,0 +1,53 @@
+import { useEffect, useState, type ReactNode, type SyntheticEvent } from 'react'
+import { Button as AriaButton } from 'react-aria-components'
+import { uic } from '../utils/uic'
+
+export const MEDIA_GALLERY_MODES = ['grid', 'carousel'] as const
+export type MediaGalleryMode = (typeof MEDIA_GALLERY_MODES)[number]
+export type MediaGalleryItem = { id: string; content: ReactNode }
+export type MediaGalleryProps = {
+	items: readonly MediaGalleryItem[]
+	mode: MediaGalleryMode
+	previousLabel: string
+	nextLabel: string
+	className?: string
+}
+
+const GalleryRoot = uic('div', {
+	baseClass: 'relative block h-full w-full overflow-hidden bg-surface-muted',
+	displayName: 'MediaGallery',
+})
+const itemClass = 'block h-full min-h-0 w-full overflow-hidden [&>img]:block [&>img]:h-full [&>img]:w-full [&>img]:object-cover [&>video]:block [&>video]:h-full [&>video]:w-full [&>video]:object-cover'
+const stopParentActivation = (event: SyntheticEvent): void => event.stopPropagation()
+const GalleryControl = uic(AriaButton, {
+	baseClass: 'pointer-events-auto inline-flex size-10 items-center justify-center rounded-full border-0 bg-surface p-0 text-title leading-none text-fg cursor-pointer outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 pointer-coarse:size-11',
+	displayName: 'MediaGalleryControl',
+})
+
+export function MediaGallery({ items, mode, previousLabel, nextLabel, className }: MediaGalleryProps) {
+	const firstId = items[0]?.id ?? null
+	const [activeId, setActiveId] = useState<string | null>(firstId)
+	useEffect(() => {
+		setActiveId(current => current && items.some(item => item.id === current) ? current : firstId)
+	}, [firstId, items])
+	if (items.length === 0) return null
+	if (mode === 'grid') {
+		const visibleItems = items.slice(0, 4)
+		return <GalleryRoot className={['grid gap-0.5', visibleItems.length === 1 ? 'grid-cols-1 grid-rows-1' : visibleItems.length === 2 ? 'grid-cols-2 grid-rows-1' : 'grid-cols-2 grid-rows-2', className].filter(Boolean).join(' ')}>
+			{visibleItems.map(item => <div key={item.id} className={itemClass}>{item.content}</div>)}
+		</GalleryRoot>
+	}
+	const activeIndex = Math.max(0, items.findIndex(item => item.id === activeId))
+	const activeItem = items[activeIndex] ?? items[0]
+	// `items` is non-empty past the early return above, but that does not narrow an
+	// indexed access, so make the empty case explicit rather than asserting.
+	if (!activeItem) return null
+	const selectRelative = (offset: number) => setActiveId(items[(activeIndex + offset + items.length) % items.length]?.id ?? firstId)
+	return <GalleryRoot className={className}>
+		<div className={itemClass}>{activeItem.content}</div>
+		{items.length > 1 ? <div className="pointer-events-none absolute inset-0 z-20 flex items-center justify-between p-4">
+			<GalleryControl aria-label={previousLabel} onClick={stopParentActivation} onPress={() => selectRelative(-1)}><span aria-hidden="true">‹</span></GalleryControl>
+			<GalleryControl aria-label={nextLabel} onClick={stopParentActivation} onPress={() => selectRelative(1)}><span aria-hidden="true">›</span></GalleryControl>
+		</div> : null}
+	</GalleryRoot>
+}

package/src/components/media-settings-dialog.examples.tsx

@@ -0,0 +1,21 @@
+import { useState } from 'react'
+
+import { MediaSettingsDialog, type MediaSettingsLabels, type MediaSettingsValue } from './media-settings-dialog'
+
+const labels: MediaSettingsLabels = {
+	title: 'Media settings', displayTitle: 'Display', displayHint: 'Choose how this reference appears.', displayMode: 'Display mode', media: 'Media', gallery: 'Gallery', widthTitle: 'Width', widthHint: 'Choose the content width.', mediaWidth: 'Media width', textWidth: 'Text', wide: 'Wide', fullWidth: 'Full width', layoutTitle: 'Layout', layoutHint: 'Choose the gallery layout.', galleryLayout: 'Gallery layout', carousel: 'Carousel', grid: 'Grid', cancel: 'Cancel', save: 'Save', close: 'Close',
+}
+const initial: MediaSettingsValue = { displayMode: 'media', mediaWidth: 'text', galleryLayout: 'grid' }
+
+function Example({ value = initial }: { value?: MediaSettingsValue }) {
+	const [open, setOpen] = useState(true)
+	const [current, setCurrent] = useState(value)
+	return <MediaSettingsDialog isOpen={open} onClose={() => setOpen(false)} onSave={next => { setCurrent(next); setOpen(false) }} value={current} labels={labels} />
+}
+
+export const examples = {
+	default: () => <Example />,
+	gallery: () => <Example value={{ ...initial, displayMode: 'gallery' }} />,
+	disabled: () => <MediaSettingsDialog isOpen onClose={() => undefined} onSave={() => undefined} value={initial} labels={labels} isDisabled />,
+}
+export const meta = { category: 'Composite', description: 'Media presentation settings with discardable draft and conditional fields.' }