@podoba/react 0.0.34 → 0.0.35

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

@@ -0,0 +1,83 @@
+import { useState, type ReactNode } from 'react'
+import { Button } from './button'
+import { SettingsDialogSurface } from './settings-dialog-surface'
+import { Select, SelectItem } from './select'
+import { uic } from '../utils/uic'
+
+export const MEDIA_SETTINGS_DISPLAY_MODES = ['media', 'gallery'] as const
+export const MEDIA_SETTINGS_WIDTHS = ['text', 'wide', 'full'] as const
+export const MEDIA_SETTINGS_LAYOUTS = ['carousel', 'grid'] as const
+export type MediaSettingsValue = {
+	displayMode: (typeof MEDIA_SETTINGS_DISPLAY_MODES)[number]
+	mediaWidth: (typeof MEDIA_SETTINGS_WIDTHS)[number]
+	galleryLayout: (typeof MEDIA_SETTINGS_LAYOUTS)[number]
+}
+
+export type MediaSettingsLabels = {
+	title: ReactNode
+	displayTitle: ReactNode
+	displayHint: ReactNode
+	displayMode: ReactNode
+	media: ReactNode
+	gallery: ReactNode
+	widthTitle: ReactNode
+	widthHint: ReactNode
+	mediaWidth: ReactNode
+	textWidth: ReactNode
+	wide: ReactNode
+	fullWidth: ReactNode
+	layoutTitle: ReactNode
+	layoutHint: ReactNode
+	galleryLayout: ReactNode
+	carousel: ReactNode
+	grid: ReactNode
+	cancel: ReactNode
+	save: ReactNode
+	close: string
+}
+
+export type MediaSettingsDialogProps = {
+	isOpen: boolean
+	onClose: () => void
+	onSave: (value: MediaSettingsValue) => void
+	value: MediaSettingsValue
+	isDisabled?: boolean
+	labels: MediaSettingsLabels
+}
+
+const Field = uic('section', { displayName: 'MediaSettingsField', baseClass: 'flex flex-col gap-0 [&>div]:mt-6' })
+const FieldTitle = uic('h2', { displayName: 'MediaSettingsFieldTitle', baseClass: 'm-0 text-panel-heading font-medium text-fg' })
+const Hint = uic('p', { displayName: 'MediaSettingsHint', baseClass: 'm-0 text-small leading-4.5 font-normal text-fg-workflow-muted' })
+
+function MediaSettingsDialogInner({ value, labels, isDisabled, onClose, onSave }: Omit<MediaSettingsDialogProps, 'isOpen'>) {
+	const [draft, setDraft] = useState(value)
+	const update = <K extends keyof MediaSettingsValue>(key: K, next: MediaSettingsValue[K]) => setDraft(current => ({ ...current, [key]: next }))
+	return (
+		<SettingsDialogSurface variant="edit" isOpen onOpenChange={open => { if (!open) onClose() }} title={labels.title} closeLabel={labels.close}
+			footer={<><Button variant="secondary" onPress={onClose}>{labels.cancel}</Button><Button onPress={() => { if (!isDisabled) onSave(draft) }} isDisabled={isDisabled}>{labels.save}</Button></>}
+		>
+							<Field>
+								<FieldTitle>{labels.displayTitle}</FieldTitle><Hint>{labels.displayHint}</Hint>
+								<Select label={labels.displayMode} placeholder="" selectedKey={draft.displayMode} onSelectionChange={key => update('displayMode', String(key) as MediaSettingsValue['displayMode'])} isDisabled={isDisabled}>
+									<SelectItem id="media">{labels.media}</SelectItem><SelectItem id="gallery">{labels.gallery}</SelectItem>
+								</Select>
+							</Field>
+							{draft.displayMode === 'media' ? <Field key="width">
+								<FieldTitle>{labels.widthTitle}</FieldTitle><Hint>{labels.widthHint}</Hint>
+								<Select label={labels.mediaWidth} placeholder="" selectedKey={draft.mediaWidth} onSelectionChange={key => update('mediaWidth', String(key) as MediaSettingsValue['mediaWidth'])} isDisabled={isDisabled}>
+									<SelectItem id="text">{labels.textWidth}</SelectItem><SelectItem id="wide">{labels.wide}</SelectItem><SelectItem id="full">{labels.fullWidth}</SelectItem>
+								</Select>
+							</Field> : <Field key="layout">
+								<FieldTitle>{labels.layoutTitle}</FieldTitle><Hint>{labels.layoutHint}</Hint>
+								<Select label={labels.galleryLayout} placeholder="" selectedKey={draft.galleryLayout} onSelectionChange={key => update('galleryLayout', String(key) as MediaSettingsValue['galleryLayout'])} isDisabled={isDisabled}>
+									<SelectItem id="carousel">{labels.carousel}</SelectItem><SelectItem id="grid">{labels.grid}</SelectItem>
+								</Select>
+							</Field>}
+		</SettingsDialogSurface>
+	)
+}
+
+export function MediaSettingsDialog({ isOpen, ...props }: MediaSettingsDialogProps) {
+	if (!isOpen) return null
+	return <MediaSettingsDialogInner {...props} />
+}

package/src/components/preview-info-card.examples.tsx

@@ -0,0 +1,18 @@
+import { PreviewInfoCard, PreviewInfoRow, PreviewInfoLabel, PreviewInfoCount, PreviewInfoTitle, PreviewInfoActions } from './preview-info-card'
+import { Button } from './button'
+
+const Card = ({ disabled = false, long = false }) => (
+ <div className="relative h-48">
+  <PreviewInfoCard>
+   <PreviewInfoRow><PreviewInfoLabel>{long ? 'A long section name that must not displace the counter' : 'Section'}</PreviewInfoLabel><PreviewInfoCount>1/3</PreviewInfoCount></PreviewInfoRow>
+   <PreviewInfoTitle>Template preview</PreviewInfoTitle>
+   <PreviewInfoActions><Button isDisabled={disabled}>Open editor</Button></PreviewInfoActions>
+  </PreviewInfoCard>
+ </div>
+)
+export const examples = {
+ default: () => <Card />,
+ variants: () => <Card long />,
+ states: () => <Card disabled />,
+}
+export const meta = { category: 'Composite', description: 'Domain-free preview information overlay with original Manager spacing. Navigation and workflow actions are supplied by the consumer.' }

package/src/components/preview-info-card.tsx

@@ -0,0 +1,27 @@
+import { uic } from '../utils/uic'
+
+// Shared, domain-free information overlay. Position belongs to the preview pane.
+export const PreviewInfoCard = uic('div', {
+ displayName: 'PreviewInfoCard',
+ baseClass: 'pointer-events-none absolute bottom-0 left-0 z-10 flex w-80 max-w-full flex-col gap-3 rounded-md bg-surface p-4',
+})
+export const PreviewInfoRow = uic('div', {
+ displayName: 'PreviewInfoRow',
+ baseClass: 'flex min-h-6 items-center justify-between gap-2',
+})
+export const PreviewInfoLabel = uic('span', {
+ displayName: 'PreviewInfoLabel',
+ baseClass: 'min-w-0 truncate text-label font-normal leading-5 text-fg-muted',
+})
+export const PreviewInfoCount = uic('span', {
+ displayName: 'PreviewInfoCount',
+ baseClass: 'shrink-0 rounded-full bg-surface-muted px-2 py-0.5 text-micro font-medium leading-5 tracking-tight text-fg',
+})
+export const PreviewInfoTitle = uic('h3', {
+ displayName: 'PreviewInfoTitle',
+ baseClass: 'm-0 truncate text-compact font-medium leading-4 text-fg',
+})
+export const PreviewInfoActions = uic('div', {
+ displayName: 'PreviewInfoActions',
+ baseClass: 'pointer-events-auto flex flex-wrap gap-2 pt-1',
+})

package/src/components/reload-icon.examples.tsx

@@ -0,0 +1,7 @@
+import { ReloadIcon } from './reload-icon'
+export const examples = {
+	default: () => <ReloadIcon />,
+	labeled: () => <span><ReloadIcon />Import CSV</span>,
+	muted: () => <span className="text-fg-muted"><ReloadIcon /></span>,
+}
+export const meta = { category: 'Primitives', description: 'Decorative original 15px reload glyph; the parent action supplies its accessible name.' }

package/src/components/reload-icon.tsx

@@ -0,0 +1,6 @@
+import type { IconProps } from './icons'
+
+/** Original Manager context glyph: Radix ReloadIcon 1.3.2 (MIT), 15px grid. */
+export const ReloadIcon = (props: IconProps) => <svg width="15" height="15" viewBox="0 0 15 15" fill="none" aria-hidden="true" {...props}>
+	<path d="M1.84998 7.49998C1.84998 4.66458 4.05979 1.84998 7.49998 1.84998C10.2783 1.84998 11.6515 3.9064 12.2367 5H10.5C10.2239 5 10 5.22386 10 5.5C10 5.77614 10.2239 6 10.5 6H13.5C13.7761 6 14 5.77614 14 5.5V2.5C14 2.22386 13.7761 2 13.5 2C13.2239 2 13 2.22386 13 2.5V4.31318C12.2955 3.07126 10.6659 0.849976 7.49998 0.849976C3.43716 0.849976 0.849976 4.18537 0.849976 7.49998C0.849976 10.8146 3.43716 14.15 7.49998 14.15C9.44382 14.15 11.0622 13.3808 12.2145 12.2084C12.8315 11.5806 13.3133 10.839 13.6418 10.0407C13.7469 9.78536 13.6251 9.49315 13.3698 9.38806C13.1144 9.28296 12.8222 9.40478 12.7171 9.66014C12.4363 10.3425 12.0251 10.9745 11.5013 11.5074C10.5295 12.4963 9.16504 13.15 7.49998 13.15C4.05979 13.15 1.84998 10.3354 1.84998 7.49998Z" fill="currentColor" fillRule="evenodd" clipRule="evenodd" />
+</svg>

package/src/components/request-changes-modal.examples.tsx

@@ -0,0 +1,26 @@
+import { useState } from 'react'
+import { Button } from './button'
+import { RequestChangesModal } from './request-changes-modal'
+
+function Example({ pending = false, error }: { pending?: boolean; error?: string }) {
+	const [open, setOpen] = useState(false)
+	return <>
+		<Button onPress={() => setOpen(true)}>Request changes</Button>
+		{open ? <RequestChangesModal
+			isOpen onOpenChange={setOpen} isPending={pending} error={error}
+			onConfirm={() => setOpen(false)}
+			labels={{
+				title: 'Request changes', body: 'Describe what needs to change before the next review.',
+				noteLabel: 'Requested changes', notePlaceholder: 'Describe the requested changes…',
+				cancel: 'Cancel', confirm: 'Request changes', submitting: 'Submitting…',
+			}}
+		/> : null}
+	</>
+}
+
+export const examples = {
+	default: () => <Example />,
+	pending: () => <Example pending />,
+	error: () => <Example error="The decision could not be saved. Please try again." />,
+}
+export const meta = { category: 'Composite', description: 'Required review note with shared filled field, focus management, pending dismissal lock and retry feedback.' }

package/src/components/request-changes-modal.tsx

@@ -11,12 +11,16 @@
 // follow-up `changes` task returned by the command.
 //
 // a11y: the textarea is label-associated (htmlFor/id), marked `required` +
-// `aria-invalid` while empty; the server error is role="alert"; confirm shows a
-// pending state and is disabled while in flight or while the note is empty.
+// the server error is role="alert"; confirm shows a pending state and is disabled
+// while in flight or while the note is empty. The note is marked `isRequired`
+// (→ aria-required), NOT aria-invalid-while-empty as the raw textarea used to be:
+// an untouched required field is incomplete, not invalid, and RAC coupling
+// `isInvalid` to the danger ring would alarm the field before anyone typed.
 
-import { useId, useState } from 'react'
+import { useLayoutEffect, useRef, useState } from 'react'
 import { Button } from './button'
 import { Dialog } from './dialog'
+import { Textarea } from './textarea'
 
 /** Strings the request-changes modal renders — supplied by the app (i18n). */
 export interface RequestChangesModalLabels {
@@ -63,14 +67,24 @@ export function RequestChangesModal({
 	labels,
 	'data-testid': testId,
 }: RequestChangesModalProps): React.ReactNode {
-	const noteId = useId()
 	// CONTROLLED textarea: the confirm button's disabled state depends on whether
 	// the note is non-empty, so the value drives dependent UI (unlike approve).
 	const [note, setNote] = useState('')
+	const noteRootRef = useRef<HTMLDivElement>(null)
 	const isEmpty = note.trim().length === 0
 	const canConfirm = !isEmpty && !isPending
 
+	useLayoutEffect(() => {
+		if (!isOpen || isPending) return
+		noteRootRef.current?.querySelector('textarea')?.focus()
+		const frame = requestAnimationFrame(() => {
+			noteRootRef.current?.querySelector('textarea')?.focus()
+		})
+		return () => cancelAnimationFrame(frame)
+	}, [isOpen, isPending])
+
 	const handleConfirm = (): void => {
+		if (isPending) return
 		const trimmed = note.trim()
 		if (trimmed.length === 0) return
 		onConfirm(trimmed)
@@ -82,27 +96,30 @@ export function RequestChangesModal({
 			data-testid={testId ?? 'request-changes-modal'}
 			isOpen={isOpen}
 			onOpenChange={(open) => {
+				if (isPending) return
 				if (!open) setNote('')
 				onOpenChange(open)
 			}}
+			isDismissable={!isPending}
+			closeLabel={labels.cancel}
 		>
 			<div className="flex flex-col gap-3">
 				<p className="text-small text-fg-muted">{labels.body}</p>
-				<label htmlFor={noteId} className="text-small font-medium text-fg">
-					{labels.noteLabel}
-				</label>
-				<textarea
-					id={noteId}
-					data-testid="request-changes-note"
-					value={note}
-					onChange={(event) => setNote(event.target.value)}
-					maxLength={10_000}
-					rows={4}
-					required
-					aria-invalid={isEmpty ? true : undefined}
-					placeholder={labels.notePlaceholder}
-					className="w-full rounded-md border border-border bg-surface px-3 py-2 text-small text-fg outline-none transition-colors placeholder:text-fg-muted focus-visible:ring-2 focus-visible:ring-ring"
-				/>
+				<div ref={noteRootRef}>
+					<Textarea
+						autoFocus
+						appearance="filled"
+						label={labels.noteLabel}
+						data-testid="request-changes-note"
+						value={note}
+						isDisabled={isPending}
+						onChange={setNote}
+						maxLength={10_000}
+						rows={4}
+						isRequired
+						placeholder={labels.notePlaceholder}
+					/>
+				</div>
 				{error ? (
 					<p data-testid="request-changes-error" role="alert" className="text-small text-danger">
 						{error}

package/src/components/rich-text-editor.tsx

@@ -145,7 +145,7 @@ export function RichTextEditor({
 				</div>
 				<div
 					ref={ref}
-					className="prose prose-sm max-w-none px-4 py-3.5 text-small leading-relaxed text-fg outline-none empty:before:text-fg-subtle empty:before:content-[attr(data-placeholder)]"
+					className="prose prose-sm max-w-none px-4 py-3.5 text-small leading-relaxed text-fg outline-none empty:before:text-fg-muted empty:before:content-[attr(data-placeholder)]"
 					style={{ minHeight: bodyMinHeight }}
 					contentEditable
 					suppressContentEditableWarning

package/src/components/select.examples.tsx

@@ -0,0 +1,17 @@
+import { Select, SelectItem } from './select'
+import type { FieldAppearance } from './field-appearance'
+
+function Example({ appearance = 'outlined', disabled = false, invalid = false }: { appearance?: FieldAppearance; disabled?: boolean; invalid?: boolean }) {
+	return <Select appearance={appearance} label="Content behavior" placeholder="Choose behavior" isDisabled={disabled}
+		isInvalid={invalid} errorMessage="Choose a behavior." defaultSelectedKey={invalid ? undefined : 'shared'}>
+		<SelectItem id="shared">Shared across outputs</SelectItem>
+		<SelectItem id="separate">Edited separately per output</SelectItem>
+		<SelectItem id="unavailable" isDisabled>Unavailable behavior</SelectItem>
+	</Select>
+}
+export const examples = {
+	default: () => <Example />,
+	variants: () => <><Example /><Example appearance="filled" /></>,
+	states: () => <><Example appearance="filled" disabled /><Example appearance="filled" invalid /></>,
+}
+export const meta = { category: 'Form', description: 'Outlined and Manager-style filled selects with keyboard/typeahead navigation. Filled options retain a keyboard outline and larger narrow-screen hit targets for accessibility.' }

package/src/components/select.tsx

@@ -1,4 +1,4 @@
-import type { ReactNode } from 'react'
+import { createContext, useContext, type CSSProperties, type ReactNode } from 'react'
 import {
 	Button as RACButton,
 	FieldError,
@@ -14,6 +14,12 @@ import {
 } from 'react-aria-components'
 import { uic } from '../utils/uic'
 import { useInFocusOverlay } from './focus-context'
+import type { FieldAppearance } from './field-appearance'
+
+const SelectAppearanceContext = createContext<FieldAppearance>('outlined')
+const filledPopoverStyle: CSSProperties & { '--select-popup-max-width': string } = {
+	'--select-popup-max-width': 'calc(100vw - var(--spacing) * 6)',
+}
 
 /**
  * Select — accessible dropdown built on React Aria Components `Select`.
@@ -29,32 +35,77 @@ import { useInFocusOverlay } from './focus-context'
  */
 const SelectTrigger = uic(RACButton, {
 	displayName: 'SelectTrigger',
-	// gs source control geometry (58px tall, 20px inline padding, 8px radius) with
-	// the shared bordered fill: gs draws it borderless on cream, but our Card is
-	// also surface-card and dark theme collapses surface-card onto surface, so a
-	// borderless cream trigger disappears. White fill + border keeps it visible and
-	// consistent with the other form controls; hover darkens the border.
+	// Filled follows the Manager's borderless control; outlined preserves the
+	// existing default for consumers which have not opted into that appearance.
 	baseClass:
-		'flex h-control-tall w-full items-center justify-between gap-2.5 rounded-lg border border-border bg-surface px-5 ' +
-		'text-small text-fg outline-none transition-colors ' +
+		'flex w-full items-center justify-between gap-2.5 rounded-lg px-5 text-small text-fg outline-none transition-colors',
+	variants: {
+		appearance: {
+			filled: 'min-h-control-tall border-0 bg-surface-card py-5 font-normal leading-4.5 duration-200 motion-reduce:transition-none ' +
+				'data-[hovered]:bg-surface-muted group-data-[open]:bg-surface-card ' +
+				'data-[focus-visible]:outline-2 data-[focus-visible]:outline-ring data-[focus-visible]:outline-offset-2 ' +
+				'group-data-[invalid]:ring-1 group-data-[invalid]:ring-danger ' +
+				'data-[disabled]:bg-surface-card data-[disabled]:opacity-50 data-[disabled]:cursor-not-allowed',
+			outlined: 'h-control-tall border border-border bg-surface ' +
 		'data-[hovered]:border-fg-subtle ' +
 		'data-[focus-visible]:ring-2 data-[focus-visible]:ring-ring ' +
 		'group-data-[invalid]:border-danger group-data-[invalid]:ring-2 group-data-[invalid]:ring-danger ' +
 		'data-[disabled]:bg-surface-muted data-[disabled]:opacity-60 data-[disabled]:pointer-events-none',
+		},
+	},
+	defaultVariants: { appearance: 'outlined' },
 })
 
-export const SelectItem = uic(ListBoxItem, {
+const StyledSelectItem = uic(ListBoxItem, {
 	displayName: 'SelectItem',
-	// gs item: 0/20px padding (px-5, no vertical pad), 6px radius, selected =
-	// medium weight. We add a `surface-muted` focus background (gs highlights with
-	// weight only) so keyboard focus stays clearly visible on the cream content.
+	// Filled highlights through weight, as in Manager. Retain a keyboard outline
+	// and larger narrow-screen hit targets as explicit accessibility exceptions.
 	baseClass:
-		'flex cursor-pointer select-none items-center rounded-md px-3 py-2 text-small text-fg outline-none ' +
+		'flex cursor-pointer select-none items-center rounded-md text-small text-fg outline-none data-[disabled]:opacity-50 data-[disabled]:pointer-events-none',
+	variants: {
+		appearance: {
+			filled: 'min-w-0 overflow-hidden px-5 py-0 font-normal leading-4.5 max-md:min-h-11 ' +
+				'data-[hovered]:font-medium data-[focused]:font-medium data-[selected]:font-medium ' +
+				'data-[focus-visible]:outline-2 data-[focus-visible]:outline-ring data-[focus-visible]:-outline-offset-2',
+			outlined: 'px-3 py-2 ' +
 		'data-[hovered]:bg-surface-muted data-[focused]:bg-surface-muted data-[selected]:font-medium ' +
 		'data-[disabled]:opacity-50 data-[disabled]:pointer-events-none',
-}) as (props: ListBoxItemProps) => ReactNode
+		},
+	},
+	defaultVariants: { appearance: 'outlined' },
+}) as (props: ListBoxItemProps & { appearance?: FieldAppearance }) => ReactNode
+
+export const SelectItem = (props: ListBoxItemProps): ReactNode => {
+	const appearance = useContext(SelectAppearanceContext)
+	if (appearance === 'outlined') return <StyledSelectItem {...props} appearance={appearance} />
+	// Manager's ItemText is a single ellipsized line. Keep the full value in the
+	// label/textValue so keyboard search and assistive technology don't see a cut-off label.
+	const { children, textValue, ...rest } = props
+	return <StyledSelectItem {...rest} appearance={appearance} textValue={textValue ?? (typeof children === 'string' ? children : undefined)}>
+		{state => <Text slot="label" className="min-w-0 truncate">{typeof children === 'function' ? children(state) : children}</Text>}
+	</StyledSelectItem>
+}
+
+const SelectListBox = uic(ListBox, {
+	displayName: 'SelectListBox',
+	baseClass: 'flex flex-col overflow-auto overscroll-contain outline-none',
+	variants: { appearance: { outlined: 'max-h-72 gap-0.5 p-1', filled: 'gap-3 px-0 py-5' } },
+	defaultVariants: { appearance: 'outlined' },
+})
+const SelectPopover = uic(Popover, {
+	displayName: 'SelectPopover',
+	baseClass: 'overflow-hidden rounded-lg bg-surface-card shadow-lg',
+	variants: { appearance: {
+		outlined: 'min-w-(--trigger-width)',
+		filled: 'w-(--trigger-width) max-w-(--select-popup-max-width)',
+	} },
+	defaultVariants: { appearance: 'outlined' },
+})
 
 export type SelectProps<T extends object> = RACSelectProps<T> & {
+	appearance?: FieldAppearance
+	/** Keep the accessible label without reserving an empty label row. */
+	isLabelHidden?: boolean
 	/** Visible label (required for accessibility). */
 	label: ReactNode
 	description?: ReactNode
@@ -80,14 +131,16 @@ export const Select = <T extends object>({
 	children,
 	rootClassName,
 	triggerClassName,
+	appearance = 'outlined',
+	isLabelHidden = false,
 	...props
 }: SelectProps<T>) => {
 	// In a focus overlay, show the options inline (seamless) instead of a popover.
 	const inFocus = useInFocusOverlay()
 	const listbox = (
-		<ListBox className="flex max-h-72 flex-col gap-0.5 overflow-auto overscroll-contain p-1 outline-none">
+		<SelectListBox appearance={appearance} style={appearance === 'filled' ? { maxHeight: 'inherit' } : undefined}>
 			{children}
-		</ListBox>
+		</SelectListBox>
 	)
 	const desc = description ? (
 		<Text slot="description" className="text-label text-fg-muted">
@@ -97,8 +150,9 @@ export const Select = <T extends object>({
 	const err = <FieldError className="text-label text-danger">{errorMessage}</FieldError>
 
 	return (
+		<SelectAppearanceContext.Provider value={appearance}>
 		<RACSelect {...props} placeholder={placeholder} className={`group flex flex-col gap-3 ${rootClassName ?? ''}`}>
-			<Label className="text-panel-heading font-medium text-fg">{label}</Label>
+			<Label className={isLabelHidden ? 'sr-only' : 'text-panel-heading font-medium text-fg'}>{label}</Label>
 			{inFocus ? (
 				<>
 					{listbox}
@@ -107,7 +161,7 @@ export const Select = <T extends object>({
 				</>
 			) : (
 				<>
-					<SelectTrigger className={triggerClassName}>
+					<SelectTrigger className={triggerClassName} appearance={appearance}>
 						<SelectValue className="data-[placeholder]:text-fg-muted" />
 						{/* gs chevron: 9.5px caret, dark (neutral-400 → fg), non-interactive. */}
 						<svg
@@ -123,13 +177,15 @@ export const Select = <T extends object>({
 					</SelectTrigger>
 					{desc}
 					{err}
-					{/* Cream fill, 8px radius, shadow-lg, NO border. 4px inset so each option's
-					    highlight sits as a padded pill; small gap for an even list rhythm. */}
-					<Popover className="min-w-[var(--trigger-width)] overflow-hidden rounded-lg bg-surface-card shadow-lg">
+					{/* Filled uses the trigger width and Manager's 4px popup offset. */}
+					<SelectPopover appearance={appearance} offset={appearance === 'filled' ? 4 : undefined}
+						containerPadding={appearance === 'filled' ? 12 : undefined}
+						style={appearance === 'filled' ? filledPopoverStyle : undefined}>
 						{listbox}
-					</Popover>
+					</SelectPopover>
 				</>
 			)}
 		</RACSelect>
+		</SelectAppearanceContext.Provider>
 	)
 }

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

@@ -0,0 +1,44 @@
+import { useState } from 'react'
+import { Button } from './button'
+import { Input } from './input'
+import { WizardForm, WizardBrief, WizardFormDialog, ProductionSettingsDialog, ProductionSettingsAction, SettingsDialogDisclosure, SettingsDialogProductionColumns } from './settings-dialog-surface'
+import { DialogActionButton } from './dialog-action-button'
+import { SettingsDialogSurface, SettingsDialogIdentity, SettingsDialogAction, SettingsDialogEmphasis, SettingsDialogDescription, SettingsDialogLabel, SettingsDialogHint, type SettingsDialogVariant } from './settings-dialog-surface'
+
+function Example({ variant = 'create', pending = false, error = false, wide = false }: { variant?: SettingsDialogVariant; pending?: boolean; error?: boolean; wide?: boolean }) {
+	const [open, setOpen] = useState(false)
+	const Action = variant === 'basic' ? DialogActionButton : SettingsDialogAction
+	return <>
+		<Button onPress={() => setOpen(true)}>Open {variant} dialog{pending ? ' (pending)' : error ? ' (error)' : ''}</Button>
+		<SettingsDialogSurface variant={variant} isOpen={open} onOpenChange={setOpen} isPending={pending}
+			isWide={wide} description={variant === 'csv' ? 'Review the column-to-field mapping before importing.' : undefined}
+			label="Settings example" closeLabel="Close settings"
+			title={variant === 'basic' ? <><SettingsDialogEmphasis>{'Set the project name\nand describe '}</SettingsDialogEmphasis>the brief.</> : variant === 'catalog' ? <>Choose an output template<br />to add to this section.</> : <>Create <span className="text-fg">a new section</span> for your <span className="text-fg">production workspace</span>.</>}
+			footer={<><Action variant="secondary" isDisabled={pending} onPress={() => setOpen(false)}>Cancel</Action><Action isPending={pending} isDisabled={pending}>Save</Action></>}
+		>
+			{variant === 'basic' ? <SettingsDialogDescription><SettingsDialogLabel>Basic information</SettingsDialogLabel><SettingsDialogHint>Keep the project name clear and add a short brief so the team understands what this work is about.</SettingsDialogHint></SettingsDialogDescription> : null}
+			<SettingsDialogIdentity><Input appearance="filled" label="Section name" defaultValue="Spring campaign" isDisabled={pending} /></SettingsDialogIdentity>
+			{error ? <p role="alert" className="text-small text-danger">The changes could not be saved. Please try again.</p> : null}
+		</SettingsDialogSurface>
+	</>
+}
+function ProductionExample() {
+	const [open, setOpen] = useState(false)
+	return <><Button onPress={() => setOpen(true)}>Open production settings</Button><ProductionSettingsDialog isOpen={open} onOpenChange={setOpen} prefix="Template settings" title="Poster" description="Configure production details." closeLabel="Close settings" preview={<span>Artwork preview</span>} footer={<><ProductionSettingsAction variant="secondary" onPress={() => setOpen(false)}>Close</ProductionSettingsAction><ProductionSettingsAction isDisabled>Save</ProductionSettingsAction></>}><SettingsDialogDisclosure title="General"><Input label="Name" appearance="filled" defaultValue="Poster" /></SettingsDialogDisclosure></ProductionSettingsDialog></>
+}
+function WizardExample({ expanded = false, pending = false }: { expanded?: boolean; pending?: boolean }) {
+	const [open, setOpen] = useState(false)
+	return <><Button onPress={() => setOpen(true)}>Open wizard {expanded ? 'catalog' : 'form'}{pending ? ' pending' : ''}</Button><WizardFormDialog isOpen={open} onOpenChange={setOpen} isExpanded={expanded} isPending={pending} closeLabel="Close wizard" title={<>Create a <SettingsDialogEmphasis>new preset</SettingsDialogEmphasis><br />and define its details.</>} footer={<><Button variant="secondary" isDisabled={pending} onPress={() => setOpen(false)}>Cancel</Button><Button isPending={pending} isDisabled={pending}>Next</Button></>}><WizardForm><Input label="Name" appearance="filled" isDisabled={pending} defaultValue="Campaign" /><WizardBrief label="Scenario brief">Prepare the selected templates and shared content.</WizardBrief></WizardForm></WizardFormDialog></>
+}
+export const examples = {
+	wizard: () => <WizardExample />,
+	wizardSizes: () => <><WizardExample /><WizardExample expanded /></>,
+	wizardPending: () => <WizardExample pending />,
+	production: () => <ProductionExample />,
+	default: () => <Example />,
+	productionColumns: () => <SettingsDialogProductionColumns><Input label="Material" appearance="filled" /><Input label="Surface finish" appearance="filled" /></SettingsDialogProductionColumns>,
+	disclosures: () => <><SettingsDialogDisclosure title="Settings" description="Campaign templates"><Input label="Name" appearance="filled" defaultValue="Poster" /></SettingsDialogDisclosure><SettingsDialogDisclosure title="Print" description="Available for Print templates" defaultExpanded={false}><Input label="Material" appearance="filled" isDisabled /></SettingsDialogDisclosure></>,
+	variants: () => <><Example variant="create" /><Example variant="edit" /><Example variant="catalog" /><Example variant="csv" /><Example variant="csv" wide /><Example variant="basic" /></>,
+	states: () => <><Example pending /><Example error /><Example variant="basic" pending /><Example variant="basic" error /></>,
+}
+export const meta = { category: 'Layout', description: 'Responsive settings and catalog frames with fixed headings/actions and a scrolling form body.' }