@wallarm-org/claude-design 0.0.0-stage → 4.9.0

package/dist/project/components/InlineEdit/README.md

@@ -0,0 +1,977 @@
+Turns a displayed value into its own editor, so a reader can correct one field without opening a form — reach for a form when several values change together. Every story composes it inside an `Attribute`, because that is what keeps the read and edit states the same height and stops the row jumping on toggle.
+
+## Props as canvas attributes
+
+Use kebab-case attribute names. Pass non-string values through renderVals holes, including booleans. The full emitted API is in `components/index.d.ts`.
+
+| Attribute | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `T \| undefined` | no | — |  |
+| `default-value` | `T \| undefined` | no | — |  |
+| `on-value-change` | `((value: T) => void) \| undefined` | no | — |  |
+| `on-value-commit` | `((value: T) => void \| Promise<unknown>) \| undefined` | no | — |  |
+| `on-value-revert` | `((value: T) => void) \| undefined` | no | — |  |
+| `on-before-value-commit` | `((value: T, committedValue: T) => boolean \| void \| Promise<boolean \| void>) \| undefined` | no | — | Commit guard. Called on every submit (Enter, blur, popover close, confirm button) before `onValueCommit`, with the draft to be committed and the current committed value. Only an explicit `false` (or a promise resolving to `false`) blocks the commit: the field silently stays in edit mode with the draft. Any other result — `true`, `undefined`, no return — lets the commit proceed. A rejection or a synchronous throw is treated like a commit failure: status `error`, message from the error, field stays in edit mode. While the guard's promise is pending the edit session is held: duplicate submits are suppressed, blur neither submits nor cancels, and the field shows no status (`idle` — the consumer's confirmation UI is the feedback). Escape still cancels; a late resolution after cancel is dropped. The value committed on `true` is exactly the `value` argument the guard received; if the draft changed while the guard was pending, the resolution is dropped and the field stays in edit mode. Guards must settle via non-blocking UI (a promise resolved by dialog buttons). Synchronous blocking dialogs (`window.confirm`) are unsupported with submitMode 'blur'/'both' (the queued blur re-prompts). The guard's owner never gets its consumer UI closed by the DS — treat the dialog's own buttons as the source of truth for closing it. |
+| `edit` | `boolean \| undefined` | no | — |  |
+| `default-edit` | `boolean \| undefined` | no | `false` |  |
+| `on-edit-change` | `((editing: boolean) => void) \| undefined` | no | — |  |
+| `activation-mode` | `InlineEditActivationMode \| undefined` | no | `click` |  |
+| `submit-mode` | `InlineEditSubmitMode \| undefined` | no | `both` |  |
+| `select-on-focus` | `boolean \| undefined` | no | `true` |  |
+| `status` | `InlineEditStatus \| undefined` | no | — |  |
+| `saved-duration` | `number \| undefined` | no | `2000` |  |
+| `disabled` | `boolean \| undefined` | no | `false` |  |
+| `read-only` | `boolean \| undefined` | no | `false` |  |
+| `data-testid` | `string \| undefined` | no | — |  |
+
+## Sub-components
+
+- `WallarmDS.InlineEditControl` — `InlineEditControlProps` in the declaration bundle.
+- `WallarmDS.InlineEditDate` — `InlineEditDateProps` in the declaration bundle.
+- `WallarmDS.InlineEditDateTime` — `InlineEditDateTimeProps` in the declaration bundle.
+- `WallarmDS.InlineEditError` — `InlineEditErrorProps` in the declaration bundle.
+- `WallarmDS.InlineEditInput` — `InlineEditInputProps` in the declaration bundle.
+- `WallarmDS.InlineEditNumber` — `InlineEditNumberProps` in the declaration bundle.
+- `WallarmDS.InlineEditPreview` — `InlineEditPreviewProps` in the declaration bundle.
+- `WallarmDS.InlineEditPreviewIcon` — `InlineEditPreviewIconProps` in the declaration bundle.
+- `WallarmDS.InlineEditPreviewValue` — `InlineEditPreviewValueProps` in the declaration bundle.
+- `WallarmDS.InlineEditSelect` — `InlineEditSelectProps` in the declaration bundle.
+- `WallarmDS.InlineEditTextarea` — `InlineEditTextareaProps` in the declaration bundle.
+- `WallarmDS.InlineEditTime` — `InlineEditTimeProps` in the declaration bundle.
+
+## Stories
+
+### TextEditor
+
+The default editor. Clicking the value swaps in an input of the same size, which is why the
+row does not move.
+
+Source: InlineEdit/InlineEdit.stories.tsx#TextEditor
+
+### NumberEditor
+
+`InlineEditNumber` for a numeric field, with the steppers available while editing and gone
+again once committed.
+
+Source: InlineEdit/InlineEdit.stories.tsx#NumberEditor
+
+### TextareaEditor
+
+For a value long enough to wrap. `lineClamp` on the preview keeps the row short in read mode
+and lets the editor grow past it.
+
+Source: InlineEdit/InlineEdit.stories.tsx#TextareaEditor
+
+### SelectEditor
+
+`InlineEditSelect` for a value from a known set. Its children are ordinary `Select` parts, so
+the menu behaves exactly as it would standalone.
+
+Source: InlineEdit/InlineEdit.stories.tsx#SelectEditor
+
+### MultiSelectEditor
+
+The same editor with `multiple`, for a value that is genuinely a list rather than one choice.
+
+Source: InlineEdit/InlineEdit.stories.tsx#MultiSelectEditor
+
+### TagsEditor
+
+A multi-select whose committed value reads as `Tag` chips, which suits a list the reader
+scans rather than one they read as a sentence.
+
+Source: InlineEdit/InlineEdit.stories.tsx#TagsEditor
+
+### DateEditor
+
+`InlineEditDate` hosts a `Calendar`, so the editor is a popover rather than a field — the row
+stays the same height while it is open.
+
+Source: InlineEdit/InlineEdit.stories.tsx#DateEditor
+
+### TimeEditor
+
+`InlineEditTime` for a time of day, taking the same value objects as `TimeInput`.
+
+Source: InlineEdit/InlineEdit.stories.tsx#TimeEditor
+
+### DateTimeEditor
+
+Date and time in one editor, for a value where the pair only makes sense together.
+
+Source: InlineEdit/InlineEdit.stories.tsx#DateTimeEditor
+
+### HorizontalLayout
+
+`InlineEdit` inside a horizontal `Attribute` — label on the left, value/editor on the right.
+The orientation belongs to `Attribute`, not here: `InlineEdit` has no orientation prop and
+behaves identically either way.
+
+Source: InlineEdit/InlineEdit.stories.tsx#HorizontalLayout
+
+### States
+
+The three async states side by side. `saved` is transient and clears itself after
+`savedDuration`, so it is pinned here to be looked at.
+
+Source: InlineEdit/InlineEdit.stories.tsx#States
+
+### Async
+
+A commit that returns a promise. The field stays in edit mode until it resolves, and a
+rejection keeps the reader's text rather than discarding it.
+
+Source: InlineEdit/InlineEdit.stories.tsx#Async
+
+### NonEditable
+
+`readOnly` and `disabled` are different answers: read-only shows the value plainly with no
+affordance, disabled says there is a control here that you cannot use.
+
+Source: InlineEdit/InlineEdit.stories.tsx#NonEditable
+
+### ConfirmCommit
+
+`onBeforeValueCommit` intercepts the commit — return `false`, or a promise of it, to hold
+the field open. Use it where the change is consequential enough to confirm, not for validation,
+and short-circuit unchanged values: the guard fires on every commit path, no-op submits included.
+
+Source: InlineEdit/InlineEdit.stories.tsx#ConfirmCommit
+
+## Story sources
+
+### InlineEdit/InlineEdit.stories.tsx
+
+```tsx
+import { useRef, useState } from 'react';
+import type { TimeValue } from '@react-aria/datepicker';
+import { format } from 'date-fns';
+import type { Meta, StoryFn } from 'storybook-react-rsbuild';
+import { Calendar, ChevronDown, Clock } from '../../icons';
+import type { DateValue } from '../../index';
+import { CalendarDate, CalendarDateTime, Time } from '../../index';
+import { useTestId } from '../../utils/testId';
+import { Attribute, AttributeLabel, AttributeValue } from '../Attribute';
+import { Button } from '../Button';
+import {
+  CalendarBody,
+  CalendarContent,
+  CalendarGrids,
+  CalendarInputHeader,
+  CalendarTrigger,
+} from '../Calendar';
+import { DateFormatProvider } from '../DateFormatProvider';
+import { DateInput } from '../DateInput';
+import {
+  Dialog,
+  DialogBody,
+  DialogContent,
+  DialogFooter,
+  DialogFooterControls,
+  DialogHeader,
+  DialogTitle,
+} from '../Dialog';
+import { OverflowList } from '../OverflowList';
+import {
+  SelectButton,
+  SelectContent,
+  type SelectDataItem,
+  SelectInput,
+  SelectOption,
+  SelectOptionIndicator,
+  SelectOptionText,
+  SelectPositioner,
+} from '../Select';
+import { Tag } from '../Tag';
+import { Text } from '../Text';
+import { toCalendarDateValue, toReactAriaDateValue, withMinuteGranularity } from './dateValueCast';
+import { InlineEdit } from './InlineEdit';
+import { useInlineEdit } from './InlineEditContext';
+import { InlineEditControl } from './InlineEditControl';
+import { InlineEditDate } from './InlineEditDate';
+import { InlineEditDateTime } from './InlineEditDateTime';
+import { InlineEditError } from './InlineEditError';
+import { InlineEditInput } from './InlineEditInput';
+import { InlineEditNumber } from './InlineEditNumber';
+import { InlineEditPreview } from './InlineEditPreview';
+import { InlineEditPreviewIcon } from './InlineEditPreviewIcon';
+import { InlineEditPreviewValue } from './InlineEditPreviewValue';
+import { InlineEditSelect } from './InlineEditSelect';
+import { InlineEditTextarea } from './InlineEditTextarea';
+import { InlineEditTime } from './InlineEditTime';
+
+const DESCRIPTION = [
+  'Turns a displayed value into its own editor, so a reader can correct one field without opening a form — reach for a form when several values change together.',
+  'Every story composes it inside an `Attribute`, because that is what keeps the read and edit states the same height and stops the row jumping on toggle.',
+].join(' ');
+
+const meta = {
+  title: 'Inputs/InlineEdit',
+  component: InlineEdit,
+  subcomponents: {
+    InlineEditPreview,
+    InlineEditPreviewValue,
+    InlineEditPreviewIcon,
+    InlineEditControl,
+    InlineEditError,
+    InlineEditInput,
+    InlineEditNumber,
+    InlineEditTextarea,
+    InlineEditSelect,
+    InlineEditDate,
+    InlineEditDateTime,
+    InlineEditTime,
+  },
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: DESCRIPTION,
+      },
+    },
+  },
+  argTypes: {
+    status: {
+      control: 'select',
+      options: ['idle', 'loading', 'saved', 'error'],
+      description: 'Async-feedback status. Uncontrolled stories drive this internally.',
+    },
+    activationMode: {
+      control: 'select',
+      options: ['click', 'focus', 'none'],
+      description: 'How the preview enters edit mode.',
+    },
+    submitMode: {
+      control: 'select',
+      options: ['enter', 'blur', 'both', 'none'],
+      description: 'Which interactions commit the draft.',
+    },
+    disabled: {
+      control: 'boolean',
+    },
+    readOnly: {
+      control: 'boolean',
+    },
+    defaultEdit: {
+      control: 'boolean',
+    },
+    selectOnFocus: {
+      control: 'boolean',
+    },
+    savedDuration: {
+      control: 'number',
+      description: 'Milliseconds the `saved` status is shown before reverting to `idle`.',
+    },
+    value: { table: { disable: true } },
+    defaultValue: { table: { disable: true } },
+    onValueChange: { table: { disable: true } },
+    onValueCommit: { table: { disable: true } },
+    onValueRevert: { table: { disable: true } },
+    onBeforeValueCommit: { table: { disable: true } },
+    edit: { table: { disable: true } },
+    onEditChange: { table: { disable: true } },
+    children: { table: { disable: true } },
+    className: { table: { disable: true } },
+    ref: { table: { disable: true } },
+  },
+} satisfies Meta<typeof InlineEdit>;
+
+export default meta;
+
+const roleItems: SelectDataItem[] = [
+  { label: 'Admin', value: 'admin' },
+  { label: 'Editor', value: 'editor' },
+  { label: 'Viewer', value: 'viewer' },
+  { label: 'Auditor', value: 'auditor' },
+];
+
+const tagItems: SelectDataItem[] = [
+  { label: 'production', value: 'production' },
+  { label: 'us-east-1', value: 'us-east-1' },
+  { label: 'critical', value: 'critical' },
+  { label: 'tier-1', value: 'tier-1' },
+  { label: 'public', value: 'public' },
+  { label: 'monitored', value: 'monitored' },
+];
+
+function renderSelectOptions(items: SelectDataItem[]) {
+  return items.map(item => (
+    <SelectOption key={item.value} item={item}>
+      <SelectOptionText>{item.label}</SelectOptionText>
+      <SelectOptionIndicator />
+    </SelectOption>
+  ));
+}
+
+// SelectInput does not self-cascade its testid (unlike SelectButton) — derive
+// it explicitly. Must be its own component: useTestId only resolves from a
+// descendant of <InlineEdit>, not from the story function that renders it.
+function SelectInputTrigger() {
+  const testId = useTestId('input');
+  return <SelectInput data-testid={testId} size='inline-edit' />;
+}
+
+// SelectButton naturally cascades to the `button` slot, but this specific
+// consumer (ConfirmCommit's Role row) needs to preserve the pre-existing
+// `input` slot name that InlineEdit.e2e.ts depends on — same reasoning as
+// SelectInputTrigger above, just for the single-select trigger.
+function SelectButtonTrigger() {
+  const testId = useTestId('input');
+  return <SelectButton data-testid={testId} size='inline-edit' />;
+}
+
+// `Calendar` never re-provides its own testid cascade, so this resolves
+// straight from the ambient InlineEdit root — same reasoning as
+// SelectInputTrigger above, just without needing a bridge.
+function DateInputTrigger({ granularity }: { granularity: 'day' | 'minute' }) {
+  const testId = useTestId('input');
+  const { value, setValue } = useInlineEdit<DateValue | null>();
+  const resolvedValue =
+    granularity === 'minute' ? withMinuteGranularity(value ?? null) : (value ?? null);
+  return (
+    <DateInput
+      data-testid={testId}
+      value={toReactAriaDateValue(resolvedValue)}
+      onChange={v => setValue(toCalendarDateValue(v))}
+      granularity={granularity}
+      size='inline-edit'
+      showIcon={false}
+    />
+  );
+}
+
+/** The default editor. Clicking the value swaps in an input of the same size, which is why the
+ * row does not move. */
+export const TextEditor: StoryFn<typeof meta> = args => {
+  const [text, setText] = useState('Checkout API');
+  return (
+    <div className='w-[320px]'>
+      <Attribute>
+        <AttributeLabel>Name</AttributeLabel>
+        <AttributeValue>
+          <InlineEdit
+            {...args}
+            value={text}
+            onValueCommit={v => setText(v as string)}
+            data-testid='text'
+          >
+            <InlineEditPreview data-analytics-id='inline-edit-name'>{text}</InlineEditPreview>
+            <InlineEditControl>
+              <InlineEditInput data-analytics-id='inline-edit-name-input' aria-label='Name' />
+            </InlineEditControl>
+            <InlineEditError />
+          </InlineEdit>
+        </AttributeValue>
+      </Attribute>
+    </div>
+  );
+};
+
+/** `InlineEditNumber` for a numeric field, with the steppers available while editing and gone
+ * again once committed. */
+export const NumberEditor: StoryFn<typeof meta> = args => {
+  const [port, setPort] = useState('8443');
+  return (
+    <div className='w-[320px]'>
+      <Attribute>
+        <AttributeLabel>Port</AttributeLabel>
+        <AttributeValue>
+          <InlineEdit
+            {...args}
+            value={port}
+            onValueCommit={v => setPort(v as string)}
+            data-testid='number'
+          >
+            <InlineEditPreview>{port}</InlineEditPreview>
+            <InlineEditControl>
+              <InlineEditNumber />
+            </InlineEditControl>
+          </InlineEdit>
+        </AttributeValue>
+      </Attribute>
+    </div>
+  );
+};
+
+/** For a value long enough to wrap. `lineClamp` on the preview keeps the row short in read mode
+ * and lets the editor grow past it. */
+export const TextareaEditor: StoryFn<typeof meta> = args => {
+  const [about, setAbout] = useState(
+    'Displays a labeled value for a single object attribute. Used in detail panels, drawers and forms to present structured information.',
+  );
+  return (
+    <div className='w-[320px]'>
+      <Attribute>
+        <AttributeLabel>About</AttributeLabel>
+        <AttributeValue>
+          <InlineEdit
+            {...args}
+            value={about}
+            onValueCommit={v => setAbout(v as string)}
+            data-testid='textarea'
+          >
+            <InlineEditPreview lineClamp={3}>{about}</InlineEditPreview>
+            <InlineEditControl>
+              <InlineEditTextarea minRows={2} maxRows={6} />
+            </InlineEditControl>
+            <InlineEditError />
+          </InlineEdit>
+        </AttributeValue>
+      </Attribute>
+    </div>
+  );
+};
+
+/** `InlineEditSelect` for a value from a known set. Its children are ordinary `Select` parts, so
+ * the menu behaves exactly as it would standalone. */
+export const SelectEditor: StoryFn<typeof meta> = args => {
+  const [role, setRole] = useState<string[]>(['editor']);
+  const roleLabel = roleItems.find(i => i.value === (role[0] ?? ''))?.label ?? '';
+  return (
+    <div className='w-[320px]'>
+      <Attribute>
+        <AttributeLabel>Role</AttributeLabel>
+        <AttributeValue>
+          <InlineEdit
+            {...args}
+            value={role}
+            onValueCommit={v => setRole(v as string[])}
+            data-testid='select'
+          >
+            <InlineEditPreview>
+              <InlineEditPreviewValue>{roleLabel}</InlineEditPreviewValue>
+              <InlineEditPreviewIcon>
+                <ChevronDown size='md' />
+              </InlineEditPreviewIcon>
+            </InlineEditPreview>
+            <InlineEditControl>
+              <InlineEditSelect items={roleItems}>
+                <SelectButton size='inline-edit' />
+                <SelectPositioner>
+                  <SelectContent>{renderSelectOptions(roleItems)}</SelectContent>
+                </SelectPositioner>
+              </InlineEditSelect>
+            </InlineEditControl>
+          </InlineEdit>
+        </AttributeValue>
+      </Attribute>
+    </div>
+  );
+};
+
+/** The same editor with `multiple`, for a value that is genuinely a list rather than one choice. */
+export const MultiSelectEditor: StoryFn<typeof meta> = args => {
+  const [roles, setRoles] = useState<string[]>(['editor', 'viewer']);
+  const rolesLabel = roles.map(v => roleItems.find(i => i.value === v)?.label ?? v).join(', ');
+  return (
+    <div className='w-[320px]'>
+      <Attribute>
+        <AttributeLabel>Roles</AttributeLabel>
+        <AttributeValue>
+          <InlineEdit
+            {...args}
+            value={roles}
+            onValueCommit={v => setRoles(v as string[])}
+            data-testid='multi-select'
+          >
+            <InlineEditPreview>
+              <InlineEditPreviewValue>{rolesLabel}</InlineEditPreviewValue>
+              <InlineEditPreviewIcon>
+                <ChevronDown size='md' />
+              </InlineEditPreviewIcon>
+            </InlineEditPreview>
+            <InlineEditControl>
+              <InlineEditSelect items={roleItems} multiple>
+                <SelectButton size='inline-edit' />
+                <SelectPositioner>
+                  <SelectContent>{renderSelectOptions(roleItems)}</SelectContent>
+                </SelectPositioner>
+              </InlineEditSelect>
+            </InlineEditControl>
+          </InlineEdit>
+        </AttributeValue>
+      </Attribute>
+    </div>
+  );
+};
+
+/** A multi-select whose committed value reads as `Tag` chips, which suits a list the reader
+ * scans rather than one they read as a sentence. */
+export const TagsEditor: StoryFn<typeof meta> = args => {
+  const [tags, setTags] = useState<string[]>(['production', 'critical']);
+  return (
+    <div className='w-[320px]'>
+      <Attribute>
+        <AttributeLabel>Tags</AttributeLabel>
+        <AttributeValue>
+          <InlineEdit
+            {...args}
+            value={tags}
+            onValueCommit={v => setTags(v as string[])}
+            data-testid='tags'
+          >
+            <InlineEditPreview>
+              <InlineEditPreviewValue>
+                <OverflowList
+                  className='gap-4'
+                  items={tags}
+                  itemRenderer={tag => <Tag key={tag}>{tag}</Tag>}
+                />
+              </InlineEditPreviewValue>
+              <InlineEditPreviewIcon>
+                <ChevronDown size='md' />
+              </InlineEditPreviewIcon>
+            </InlineEditPreview>
+            <InlineEditControl>
+              <InlineEditSelect items={tagItems} multiple>
+                <SelectInputTrigger />
+                <SelectPositioner>
+                  <SelectContent>{renderSelectOptions(tagItems)}</SelectContent>
+                </SelectPositioner>
+              </InlineEditSelect>
+            </InlineEditControl>
+          </InlineEdit>
+        </AttributeValue>
+      </Attribute>
+    </div>
+  );
+};
+
+/** `InlineEditDate` hosts a `Calendar`, so the editor is a popover rather than a field — the row
+ * stays the same height while it is open. */
+export const DateEditor: StoryFn<typeof meta> = args => {
+  const [date, setDate] = useState<DateValue | null>(new CalendarDate(2026, 6, 15));
+  const dateLabel = date
+    ? format(new Date(date.year, date.month - 1, date.day), 'd MMM, yyyy')
+    : '—';
+  return (
+    <div className='w-[320px]'>
+      <DateFormatProvider order='day-first' hourCycle={24}>
+        <Attribute>
+          <AttributeLabel>Date</AttributeLabel>
+          <AttributeValue>
+            <InlineEdit
+              {...args}
+              value={date}
+              onValueCommit={v => setDate(v as DateValue | null)}
+              data-testid='date'
+            >
+              <InlineEditPreview>
+                <InlineEditPreviewValue>{dateLabel}</InlineEditPreviewValue>
+                <InlineEditPreviewIcon>
+                  <Calendar size='md' />
+                </InlineEditPreviewIcon>
+              </InlineEditPreview>
+              <InlineEditControl>
+                <InlineEditDate>
+                  <CalendarTrigger>
+                    <DateInputTrigger granularity='day' />
+                  </CalendarTrigger>
+                  <CalendarContent>
+                    <CalendarBody>
+                      <CalendarGrids />
+                    </CalendarBody>
+                  </CalendarContent>
+                </InlineEditDate>
+              </InlineEditControl>
+            </InlineEdit>
+          </AttributeValue>
+        </Attribute>
+      </DateFormatProvider>
+    </div>
+  );
+};
+
+/** `InlineEditTime` for a time of day, taking the same value objects as `TimeInput`. */
+export const TimeEditor: StoryFn<typeof meta> = args => {
+  const [time, setTime] = useState<TimeValue | null>(new Time(14, 30));
+  const timeLabel = time ? format(new Date(2000, 0, 1, time.hour, time.minute), 'h:mm a') : '—';
+  return (
+    <div className='w-[320px]'>
+      <DateFormatProvider order='day-first' hourCycle={12}>
+        <Attribute>
+          <AttributeLabel>Time</AttributeLabel>
+          <AttributeValue>
+            <InlineEdit
+              {...args}
+              value={time}
+              onValueCommit={v => setTime(v as TimeValue | null)}
+              data-testid='time'
+            >
+              <InlineEditPreview>
+                <InlineEditPreviewValue>{timeLabel}</InlineEditPreviewValue>
+                <InlineEditPreviewIcon>
+                  <Clock size='md' />
+                </InlineEditPreviewIcon>
+              </InlineEditPreview>
+              <InlineEditControl>
+                <InlineEditTime />
+              </InlineEditControl>
+            </InlineEdit>
+          </AttributeValue>
+        </Attribute>
+      </DateFormatProvider>
+    </div>
+  );
+};
+
+/** Date and time in one editor, for a value where the pair only makes sense together. */
+export const DateTimeEditor: StoryFn<typeof meta> = args => {
+  const [dateTime, setDateTime] = useState<CalendarDateTime | null>(
+    new CalendarDateTime(2026, 6, 15, 14, 30),
+  );
+  const dateTimeLabel = dateTime
+    ? format(
+        new Date(dateTime.year, dateTime.month - 1, dateTime.day, dateTime.hour, dateTime.minute),
+        'd MMM, yyyy h:mm a',
+      )
+    : '—';
+  return (
+    <div className='w-[320px]'>
+      <DateFormatProvider order='day-first' hourCycle={12}>
+        <Attribute>
+          <AttributeLabel>Date &amp; Time</AttributeLabel>
+          <AttributeValue>
+            <InlineEdit
+              {...args}
+              value={dateTime}
+              onValueCommit={v => setDateTime(v as CalendarDateTime | null)}
+              data-testid='datetime'
+            >
+              <InlineEditPreview>
+                <InlineEditPreviewValue>{dateTimeLabel}</InlineEditPreviewValue>
+                <InlineEditPreviewIcon>
+                  <Calendar size='md' />
+                </InlineEditPreviewIcon>
+              </InlineEditPreview>
+              <InlineEditControl>
+                <InlineEditDateTime>
+                  <CalendarTrigger>
+                    <DateInputTrigger granularity='minute' />
+                  </CalendarTrigger>
+                  <CalendarContent>
+                    <CalendarBody>
+                      <CalendarInputHeader />
+                      <CalendarGrids />
+                    </CalendarBody>
+                  </CalendarContent>
+                </InlineEditDateTime>
+              </InlineEditControl>
+            </InlineEdit>
+          </AttributeValue>
+        </Attribute>
+      </DateFormatProvider>
+    </div>
+  );
+};
+
+/**
+ * `InlineEdit` inside a horizontal `Attribute` — label on the left, value/editor on the right.
+ * The orientation belongs to `Attribute`, not here: `InlineEdit` has no orientation prop and
+ * behaves identically either way.
+ */
+export const HorizontalLayout: StoryFn<typeof meta> = args => {
+  const [name, setName] = useState('Checkout API');
+  const [role, setRole] = useState<string[]>(['editor']);
+  const roleLabel = roleItems.find(i => i.value === (role[0] ?? ''))?.label ?? '';
+  return (
+    <div className='flex w-[420px] flex-col gap-8'>
+      <Attribute orientation='horizontal'>
+        <AttributeLabel>Name</AttributeLabel>
+        <AttributeValue>
+          <InlineEdit
+            {...args}
+            value={name}
+            onValueCommit={v => setName(v as string)}
+            data-testid='horizontal-text'
+          >
+            <InlineEditPreview>{name}</InlineEditPreview>
+            <InlineEditControl>
+              <InlineEditInput aria-label='Name' />
+            </InlineEditControl>
+            <InlineEditError />
+          </InlineEdit>
+        </AttributeValue>
+      </Attribute>
+
+      <Attribute orientation='horizontal'>
+        <AttributeLabel>Role</AttributeLabel>
+        <AttributeValue>
+          <InlineEdit
+            {...args}
+            value={role}
+            onValueCommit={v => setRole(v as string[])}
+            data-testid='horizontal-select'
+          >
+            <InlineEditPreview>
+              <InlineEditPreviewValue>{roleLabel}</InlineEditPreviewValue>
+              <InlineEditPreviewIcon>
+                <ChevronDown size='md' />
+              </InlineEditPreviewIcon>
+            </InlineEditPreview>
+            <InlineEditControl>
+              <InlineEditSelect items={roleItems}>
+                <SelectButton size='inline-edit' />
+                <SelectPositioner>
+                  <SelectContent>{renderSelectOptions(roleItems)}</SelectContent>
+                </SelectPositioner>
+              </InlineEditSelect>
+            </InlineEditControl>
+          </InlineEdit>
+        </AttributeValue>
+      </Attribute>
+    </div>
+  );
+};
+
+/** The three async states side by side. `saved` is transient and clears itself after
+ * `savedDuration`, so it is pinned here to be looked at. */
+export const States: StoryFn<typeof meta> = args => (
+  <div className='flex w-[420px] flex-col gap-12'>
+    <Attribute>
+      <AttributeLabel>Name</AttributeLabel>
+      <AttributeValue>
+        <InlineEdit
+          {...args}
+          defaultValue='Checkout API and ABC'
+          status='loading'
+          data-testid='loading'
+        >
+          <InlineEditPreview>Checkout API and ABC</InlineEditPreview>
+          <InlineEditControl>
+            <InlineEditInput />
+          </InlineEditControl>
+        </InlineEdit>
+      </AttributeValue>
+    </Attribute>
+
+    <Attribute>
+      <AttributeLabel>Name</AttributeLabel>
+      <AttributeValue>
+        <InlineEdit
+          {...args}
+          defaultValue='Checkout API and ABC'
+          status='saved'
+          data-testid='saved'
+        >
+          <InlineEditPreview>Checkout API and ABC</InlineEditPreview>
+          <InlineEditControl>
+            <InlineEditInput />
+          </InlineEditControl>
+        </InlineEdit>
+      </AttributeValue>
+    </Attribute>
+
+    <Attribute>
+      <AttributeLabel>Name</AttributeLabel>
+      <AttributeValue>
+        <InlineEdit
+          {...args}
+          defaultValue='Checkout API and ABC'
+          defaultEdit
+          status='error'
+          data-testid='error'
+        >
+          <InlineEditPreview>Checkout API and ABC</InlineEditPreview>
+          <InlineEditControl>
+            <InlineEditInput />
+          </InlineEditControl>
+          <InlineEditError>An error message.</InlineEditError>
+        </InlineEdit>
+      </AttributeValue>
+    </Attribute>
+  </div>
+);
+
+/**
+ * A commit that returns a promise. The field stays in edit mode until it resolves, and a
+ * rejection keeps the reader's text rather than discarding it.
+ */
+export const Async: StoryFn<typeof meta> = args => {
+  const [value, setValue] = useState('Checkout API');
+  const save = (v: unknown) =>
+    new Promise<void>((resolve, reject) => {
+      setTimeout(() => {
+        if ((v as string).trim().length === 0) reject(new Error('Name is required.'));
+        else {
+          setValue(v as string);
+          resolve();
+        }
+      }, 1200);
+    });
+  return (
+    <div className='w-[320px]'>
+      <Attribute>
+        <AttributeLabel>Name</AttributeLabel>
+        <AttributeValue>
+          <InlineEdit {...args} value={value} onValueCommit={save} data-testid='attr'>
+            <InlineEditPreview>{value}</InlineEditPreview>
+            <InlineEditControl>
+              <InlineEditInput />
+            </InlineEditControl>
+            <InlineEditError />
+          </InlineEdit>
+        </AttributeValue>
+      </Attribute>
+    </div>
+  );
+};
+
+/**
+ * `readOnly` and `disabled` are different answers: read-only shows the value plainly with no
+ * affordance, disabled says there is a control here that you cannot use.
+ */
+export const NonEditable: StoryFn<typeof meta> = args => (
+  <div className='flex w-[320px] flex-col gap-8'>
+    <Attribute>
+      <AttributeLabel>Read only</AttributeLabel>
+      <AttributeValue>
+        <InlineEdit {...args} defaultValue='Locked value' readOnly data-testid='readonly'>
+          <InlineEditPreview>Locked value</InlineEditPreview>
+          <InlineEditControl>
+            <InlineEditInput />
+          </InlineEditControl>
+        </InlineEdit>
+      </AttributeValue>
+    </Attribute>
+    <Attribute>
+      <AttributeLabel>Disabled</AttributeLabel>
+      <AttributeValue>
+        <InlineEdit {...args} defaultValue='Disabled value' disabled data-testid='disabled'>
+          <InlineEditPreview>Disabled value</InlineEditPreview>
+          <InlineEditControl>
+            <InlineEditInput />
+          </InlineEditControl>
+        </InlineEdit>
+      </AttributeValue>
+    </Attribute>
+  </div>
+);
+
+/**
+ * `onBeforeValueCommit` intercepts the commit — return `false`, or a promise of it, to hold
+ * the field open. Use it where the change is consequential enough to confirm, not for validation,
+ * and short-circuit unchanged values: the guard fires on every commit path, no-op submits included.
+ */
+export const ConfirmCommit: StoryFn<typeof meta> = args => {
+  const [email, setEmail] = useState('dev@wallarm.com');
+  const [role, setRole] = useState<string[]>(['editor']);
+  const [pending, setPending] = useState<string | null>(null);
+  const resolverRef = useRef<((ok: boolean) => void) | null>(null);
+
+  // Promise-based confirm: the guard returns this promise and the dialog
+  // buttons settle it. The DS never closes the dialog — `settle` does.
+  const confirmChange = (message: string) =>
+    new Promise<boolean>(resolve => {
+      resolverRef.current = resolve;
+      setPending(message);
+    });
+
+  const settle = (ok: boolean) => {
+    resolverRef.current?.(ok);
+    resolverRef.current = null;
+    setPending(null);
+  };
+
+  const roleLabel = roleItems.find(i => i.value === (role[0] ?? ''))?.label ?? '';
+
+  return (
+    <div className='flex w-[320px] flex-col gap-8'>
+      <Attribute>
+        <AttributeLabel>Email</AttributeLabel>
+        <AttributeValue>
+          <InlineEdit
+            {...args}
+            value={email}
+            onBeforeValueCommit={(next, prev) =>
+              next === prev || confirmChange(`Change email to ${next as string}?`)
+            }
+            onValueCommit={v => setEmail(v as string)}
+            data-testid='confirm-email'
+          >
+            <InlineEditPreview>{email}</InlineEditPreview>
+            <InlineEditControl>
+              <InlineEditInput type='email' aria-label='Email' />
+            </InlineEditControl>
+          </InlineEdit>
+        </AttributeValue>
+      </Attribute>
+
+      <Attribute>
+        <AttributeLabel>Role</AttributeLabel>
+        <AttributeValue>
+          <InlineEdit
+            {...args}
+            value={role}
+            onBeforeValueCommit={(next, prev) => {
+              // The guard fires on every popover close, including no-op ones —
+              // short-circuit when nothing changed (for dates use `.compare()`).
+              const nextRole = (next as string[]).join();
+              if (nextRole === (prev as string[]).join()) return true;
+              const label =
+                roleItems.find(i => i.value === (next as string[])[0])?.label ?? nextRole;
+              return confirmChange(`Change role to ${label}?`);
+            }}
+            onValueCommit={v => setRole(v as string[])}
+            data-testid='confirm-role'
+          >
+            <InlineEditPreview>
+              <InlineEditPreviewValue>{roleLabel}</InlineEditPreviewValue>
+              <InlineEditPreviewIcon>
+                <ChevronDown size='md' />
+              </InlineEditPreviewIcon>
+            </InlineEditPreview>
+            <InlineEditControl>
+              <InlineEditSelect items={roleItems}>
+                <SelectButtonTrigger />
+                <SelectPositioner>
+                  <SelectContent>{renderSelectOptions(roleItems)}</SelectContent>
+                </SelectPositioner>
+              </InlineEditSelect>
+            </InlineEditControl>
+          </InlineEdit>
+        </AttributeValue>
+      </Attribute>
+
+      <Dialog
+        open={pending !== null}
+        onOpenChange={open => {
+          if (!open) settle(false);
+        }}
+        data-testid='confirm-dialog'
+      >
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>Confirm change</DialogTitle>
+          </DialogHeader>
+          <DialogBody>
+            <Text>{pending}</Text>
+          </DialogBody>
+          <DialogFooter>
+            <DialogFooterControls>
+              <Button
+                variant='ghost'
+                color='neutral'
+                size='large'
+                onClick={() => settle(false)}
+                data-testid='confirm-decline'
+              >
+                Cancel
+              </Button>
+              <Button
+                variant='primary'
+                color='brand'
+                size='large'
+                onClick={() => settle(true)}
+                data-testid='confirm-accept'
+              >
+                Change
+              </Button>
+            </DialogFooterControls>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+    </div>
+  );
+};
+```