@cardstack/boxel-cli 0.10.0 → 0.10.1-unstable.0

package/bundled-realms/pretui/components/edit-in-place.md

@@ -0,0 +1,63 @@
+## What it is
+
+A displayed value that becomes an editable field, then commits or cancels.
+
+Use it where a value is usually read and occasionally changed — a title, a note, a field on a record detail. For a value that is always being edited, use the field directly.
+
+## The contract
+
+```
+@value?            — the committed value
+@label (required)  — the field's name
+@placeholder?      — shown, muted, when the value is empty. Default 'Empty'
+@editing?, @defaultEditing?, @onEditingChange? — controlled / uncontrolled mode
+@onCommit?         — fires with the draft; RETURN FALSE to refuse and stay in edit mode
+@onCancel?         — fires on Escape or an explicit Cancel
+@onDraftChange?    — live draft channel, for a caller mirroring the draft elsewhere
+@invalid?, @error? — rejected state and the message under the editor
+@canEdit?          — not editable: renders the display content bare, with no chrome
+@activateOn?       — 'row' also activates on a click in the display. Never the only path
+@commitOn?         — 'blur' (default) commits on leaving; 'action' renders Save / Cancel
+                     and ignores blur
+@multiline?        — Enter inserts a newline; ⌘/Ctrl-Enter commits
+@announce?         — announce the mode change politely. Default true
+@saveLabel?, @cancelLabel?
+
+<:display> — the resting presentation; any content, never wrapped in a control
+<:editor>  — the editor, receiving a draft api. Omit for a Pretui Input
+```
+
+**Returning `false` from `@onCommit` refuses the commit and stays in edit mode.** That is the honest way for a caller to reject a value without a validation framework — the draft is not lost and the reader is not ejected.
+
+**`@label` is required** because an unnamed in-place editor is an unnamed editor: it supplies both the visually-hidden label and the trigger's name.
+
+**`@activateOn='row'` is pointer convenience and never the only path.** There is always a real trigger; click-the-text is an addition to it.
+
+**`@commitOn='action'` ignores blur entirely.** Commit-on-blur is right for a quick title edit and wrong for anything a reader might tab out of to check something.
+
+**`<:display>` is never wrapped in a control**, which is what lets arbitrary content — a chip, a link, a formatted value — be the resting state without nesting interactives.
+
+## Prior art
+
+**boxel-catalog's blog-app editable-field.**
+
+Where Pretui is better: the refusal path, the explicit commit mode, and the display block not being wrapped in a button — the source wrapped its display content, which made a link inside it unreachable.
+
+Where it is thinner: no optimistic state, no undo after commit, and no draft persistence across unmount — cancel means the draft is gone.
+
+## Accessibility
+
+- **The mode change is announced politely by default.** Moving from reading to editing is a change a screen-reader user cannot see, and silence is the common failure.
+- **There is always a real trigger**, so entering edit mode never depends on clicking text.
+- **`@error` is announced and referenced by `aria-describedby`**, so a refusal is both heard and located.
+- **Escape cancels**, and `@commitOn='action'` gives an explicit Cancel for readers who do not use it.
+- **`@multiline` changes what Enter means**, and says so: Enter inserts a newline, ⌘/Ctrl-Enter commits. A multiline editor that commits on Enter is unusable.
+- **`@canEdit={{false}}` renders the display bare, with no chrome at all** — not a disabled control, just the value, which is what a read-only row should be.
+
+## Theming
+
+`--pretui-destructive-ink` for the rejected state, `--pretui-radius-encroach` for the editor's fit against the display box, and the shared `--pretui-dur-snap` / `--pretui-ease-snap` for the mode transition.
+
+`--pretui-radius-encroach` is the detail that makes the swap look deliberate: the editor has to sit inside the space the display occupied without the corners disagreeing, and a shared encroachment value is what keeps that consistent across every in-place editor in a theme.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/edit-in-place.usage.gts

@@ -0,0 +1,209 @@
+// Pretui — EditInPlace usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { EditInPlace } from './edit-in-place';
+import { FreestyleUsage } from './freestyle-usage';
+import { Select } from './select';
+import type { SelectOption } from './select';
+
+const ACTIVATIONS = ['button', 'row'];
+const COMMIT_MODES = ['blur', 'action'];
+
+// ── EditInPlace ──────────────────────────────────────────────────────────
+// Dropped upstream surface: dblclick activation (no touch equivalent, no
+// visible affordance) and the outside-click timer.
+class EditInPlaceUsage extends Component {
+  activations = ACTIVATIONS;
+  commitModes = COMMIT_MODES;
+  statuses: SelectOption[] = [
+    { value: 'draft', label: 'Draft' },
+    { value: 'review', label: 'In review' },
+    { value: 'live', label: 'Published' },
+  ];
+
+  @tracked title = 'Quarterly revenue review';
+  @tracked status = 'draft';
+  @tracked activateOn = 'button';
+  @tracked commitOn = 'blur';
+  @tracked canEdit = true;
+  @tracked errorText = '';
+  @tracked lastEvent = 'nothing yet';
+
+  setActivateOn = (v: string) => (this.activateOn = v);
+  setCommitOn = (v: string) => (this.commitOn = v);
+  setCanEdit = (v: boolean) => (this.canEdit = v);
+  setErrorText = (v: string) => (this.errorText = v);
+
+  commitTitle = (next: string) => {
+    if (next.trim().length === 0) {
+      this.errorText = 'A title cannot be empty.';
+      this.lastEvent = 'commit refused';
+      return false;
+    }
+    this.errorText = '';
+    this.title = next;
+    this.lastEvent = 'committed';
+    return true;
+  };
+  cancelTitle = () => (this.lastEvent = 'cancelled');
+  commitStatus = (next: string) => {
+    this.status = next;
+    this.lastEvent = 'status committed';
+  };
+
+  get activateOnValue() {
+    return this.activateOn as 'button' | 'row';
+  }
+  get commitOnValue() {
+    return this.commitOn as 'blur' | 'action';
+  }
+  get statusLabel() {
+    let hit = this.statuses.find((option) => option.value === this.status);
+    return hit ? hit.label : this.status;
+  }
+  get usage() {
+    return "<EditInPlace @label='Title' @value={{this.title}} @activateOn='" +
+      this.activateOn +
+      "' @commitOn='" +
+      this.commitOn +
+      "' @onCommit={{this.save}}><:display>…</:display></EditInPlace>";
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='EditInPlace'
+      @description='A display value that becomes an editable field on activation and commits or cancels. Escape cancels, Enter commits, and leaving commits only when focus actually left the editor. The pencil is a real adjacent button, never a wrapper around the display, so a display holding a link is still a link.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='pretui-demo-eip'>
+          <div class='pretui-demo-row'>
+            <span class='pretui-demo-key'>Title</span>
+            <EditInPlace
+              @label='Title'
+              @value={{this.title}}
+              @placeholder='Add a title'
+              @error={{this.errorText}}
+              @activateOn={{this.activateOnValue}}
+              @commitOn={{this.commitOnValue}}
+              @canEdit={{this.canEdit}}
+              @onCommit={{this.commitTitle}}
+              @onCancel={{this.cancelTitle}}
+            >
+              <:display>
+                <span class='pretui-demo-value'>{{this.title}}</span>
+              </:display>
+            </EditInPlace>
+          </div>
+          <div class='pretui-demo-row'>
+            <span class='pretui-demo-key'>Status</span>
+            {{!-- any of the kit inputs, not just text — the editor block
+                  gets the draft api and wires whatever control it likes --}}
+            <EditInPlace
+              @label='Status'
+              @value={{this.status}}
+              @commitOn={{this.commitOnValue}}
+              @canEdit={{this.canEdit}}
+              @onCommit={{this.commitStatus}}
+            >
+              <:display>
+                <span class='pretui-demo-value'>{{this.statusLabel}}</span>
+              </:display>
+              <:editor as |editor|>
+                <Select
+                  @options={{this.statuses}}
+                  @value={{editor.value}}
+                  @controlId={{editor.controlId}}
+                  @onValueChange={{editor.setValue}}
+                  @searchEnabled={{true}}
+                />
+              </:editor>
+            </EditInPlace>
+          </div>
+        </div>
+        <p class='pretui-demo-readout' data-test-eip-readout>
+          {{this.lastEvent}}
+        </p>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='label'
+          @value='Title'
+          @description='Required. It names the visually hidden label on the editor and the pencil button, because an unnamed editor is an unnamed editor.'
+        />
+        <Args.String
+          @name='activateOn'
+          @defaultValue='button'
+          @value={{this.activateOn}}
+          @options={{this.activations}}
+          @description='button is the guaranteed path and is always present. row adds click-anywhere as a pointer enhancement, and it skips clicks that landed on a link or control inside the display so it can never swallow them.'
+          @onInput={{this.setActivateOn}}
+        />
+        <Args.String
+          @name='commitOn'
+          @defaultValue='blur'
+          @value={{this.commitOn}}
+          @options={{this.commitModes}}
+          @description='blur commits when focus genuinely leaves the editor, checked through relatedTarget containment rather than the upstream 50ms timer. action renders Save and Cancel and ignores blur entirely.'
+          @onInput={{this.setCommitOn}}
+        />
+        <Args.Bool
+          @name='canEdit'
+          @defaultValue={{true}}
+          @value={{this.canEdit}}
+          @description='False renders the display content bare, with no wrapper and no dead affordance.'
+          @onInput={{this.setCanEdit}}
+        />
+        <Args.String
+          @name='error'
+          @defaultValue=''
+          @value={{this.errorText}}
+          @description='Message under the editor, referenced by aria-describedby. Its line is reserved so an arriving error never shifts the row.'
+          @onInput={{this.setErrorText}}
+        />
+        <Args.Action
+          @name='onCommit'
+          @description='Fires with the draft. Returning false refuses the commit and keeps the editor open with focus back on the control.'
+        />
+        <Args.Yield
+          @name='editor'
+          @description='Receives value, setValue, controlId, commit, cancel and invalid — enough to wire any control in the kit, which is why the Status row below is a Select.'
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .pretui-demo-eip {
+        display: grid;
+        gap: var(--space-3, 8px);
+        max-width: 26rem;
+      }
+      .pretui-demo-row {
+        display: grid;
+        grid-template-columns: 5rem minmax(0, 1fr);
+        align-items: center;
+        gap: var(--space-3, 8px);
+        padding: var(--space-2, 6px);
+        border-radius: var(--radius);
+        background: var(--card);
+        box-shadow: 0 0 0 1px var(--border);
+      }
+      .pretui-demo-key {
+        font-size: var(--text-ui-sm, 11.5px);
+        font-weight: 500;
+        color: var(--muted-foreground);
+      }
+      .pretui-demo-value {
+        font-size: var(--boxel-font-size-xs);
+      }
+      .pretui-demo-readout {
+        margin: var(--space-4, 12px) 0 0;
+        font-size: var(--text-ui-sm, 11.5px);
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_EDIT_IN_PLACE: Record<string, unknown> = {
+  EditInPlace: EditInPlaceUsage,
+};

package/bundled-realms/pretui/components/editable.gts

@@ -0,0 +1,299 @@
+// Pretui — Editable: text that reads as a value until it is a field. The
+// preview is a real button whose accessible name carries the label and the
+// current value; activating it swaps an Input into the same place. Enter
+// commits, Escape restores, and leaving the field commits unless told
+// otherwise. RecordDetail does this at form scale; this is the one-field atom.
+// No timers: the focus handoff rides the render.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { modifier } from 'ember-modifier';
+import { emit, firstDefined } from '../pretui-primitives';
+import type { ControlNotifyArgs } from '../pretui-primitives';
+import { focusWhen } from '../focus';
+import { iconFor } from '../icon-registry';
+import { Input } from './input';
+
+export interface EditableSignature {
+  Args: ControlNotifyArgs & {
+    value?: string;
+    defaultValue?: string;
+    /** what the value is — "Name" — spoken as part of the trigger's name */
+    label?: string;
+    /** shown in the preview while the value is empty, and inside the field */
+    placeholder?: string;
+    disabled?: boolean;
+    /** alias — React Aria / Base UI spelling of @disabled */
+    isDisabled?: boolean;
+    /** controlled edit state; omit and use @defaultEditing */
+    editing?: boolean;
+    defaultEditing?: boolean;
+    /** alias — Chakra's spelling of @defaultEditing */
+    startWithEditView?: boolean;
+    onEditingChange?: (editing: boolean) => void;
+    /** fires with the committed value; onChange / onValueChange fire only when it differs */
+    onSubmit?: (value: string) => void;
+    onCancel?: () => void;
+    /** commit when focus leaves the field (default true); false restores instead */
+    submitOnBlur?: boolean;
+    /** select the whole value when the field opens (default true) */
+    selectOnFocus?: boolean;
+  };
+  Blocks: {
+    /** the preview, when the value needs markup */
+    preview: [value: string];
+  };
+  Element: HTMLDivElement;
+}
+
+// One editing session per mount of the field, however it opened: the trigger,
+// a parent flipping @editing, or @defaultEditing. Install focuses the input
+// and re-arms the close guard; teardown drops the draft so the next session
+// starts from the current value. Input hands `...attributes` to its inner
+// control, so the input may be the element itself or inside it.
+const fieldSession = modifier(
+  (el: HTMLElement, [select, begin, end]: [boolean, () => void, () => void]) => {
+    begin();
+    let field = el.matches('input, textarea')
+      ? (el as HTMLInputElement)
+      : el.querySelector<HTMLInputElement>('input, textarea');
+    field?.focus();
+    if (select) {
+      field?.select();
+    }
+    return end;
+  },
+);
+
+export class Editable extends Component<EditableSignature> {
+  @tracked internalValue = this.args.defaultValue ?? '';
+  @tracked internalEditing =
+    firstDefined(this.args.defaultEditing, this.args.startWithEditView) ??
+    false;
+  /** the text being edited this session; null until the reader types */
+  @tracked edited: string | null = null;
+  @tracked restoreFocus = false;
+  closing = false;
+
+  get value() {
+    return this.args.value ?? this.internalValue;
+  }
+  get draft() {
+    return this.edited ?? this.value;
+  }
+  get editing() {
+    return this.args.editing ?? this.internalEditing;
+  }
+  get disabled() {
+    return firstDefined(this.args.disabled, this.args.isDisabled) ?? false;
+  }
+  get empty() {
+    return this.value === '';
+  }
+  get shown() {
+    return this.empty ? (this.args.placeholder ?? '') : this.value;
+  }
+  get selectOnFocus() {
+    return this.args.selectOnFocus ?? true;
+  }
+  get triggerLabel() {
+    let what = this.args.label ? `Edit ${this.args.label}` : 'Edit';
+    return this.empty ? `${what}, empty` : `${what}, currently ${this.value}`;
+  }
+
+  setEditing(next: boolean) {
+    if (this.args.editing === undefined) {
+      this.internalEditing = next;
+    }
+    this.args.onEditingChange?.(next);
+  }
+  open = () => {
+    if (this.disabled) {
+      return;
+    }
+    this.setEditing(true);
+  };
+  beginSession = () => {
+    this.closing = false;
+  };
+  endSession = () => {
+    this.edited = null;
+  };
+  setDraft = (value: string) => (this.edited = value);
+  /** `restore` hands focus back to the trigger — Enter and Escape only; on
+   *  blur, focus has already gone where the reader sent it */
+  commit = (restore: boolean) => {
+    if (this.closing) {
+      return;
+    }
+    this.closing = true;
+    let next = this.draft;
+    let changed = next !== this.value;
+    if (this.args.value === undefined) {
+      this.internalValue = next;
+    }
+    if (changed) {
+      emit([this.args.onChange, this.args.onValueChange], next);
+    }
+    this.args.onSubmit?.(next);
+    this.close(restore);
+  };
+  cancel = (restore: boolean) => {
+    if (this.closing) {
+      return;
+    }
+    this.closing = true;
+    this.args.onCancel?.();
+    this.close(restore);
+  };
+  // A parent holding @editing open keeps the field mounted, so the session
+  // continues and the next Enter, Escape or blur must be heard.
+  close(restore: boolean) {
+    this.restoreFocus = restore;
+    this.setEditing(false);
+    if (this.editing) {
+      this.closing = false;
+    }
+  }
+  onKeydown = (ev: Event) => {
+    let key = ev as KeyboardEvent;
+    // the Enter that confirms an IME candidate is not a commit
+    if (key.isComposing) {
+      return;
+    }
+    if (key.key === 'Enter') {
+      ev.preventDefault();
+      this.commit(true);
+    } else if (key.key === 'Escape') {
+      ev.preventDefault();
+      this.cancel(true);
+    }
+  };
+  onFocusout = (ev: Event) => {
+    // a field leaving the DOM (teardown, a parent re-render) also blurs;
+    // that is not the reader leaving the field
+    if (this.isDestroying || !(ev.target as Element).isConnected) {
+      return;
+    }
+    if (this.args.submitOnBlur ?? true) {
+      this.commit(false);
+    } else {
+      this.cancel(false);
+    }
+  };
+  <template>
+    <div
+      class='pretui-editable'
+      data-editing={{if this.editing 'true' 'false'}}
+      data-empty={{if this.empty 'true' 'false'}}
+      data-test-pretui-editable
+      ...attributes
+    >
+      {{#if this.editing}}
+        <Input
+          @value={{this.draft}}
+          placeholder={{@placeholder}}
+          disabled={{this.disabled}}
+          @onInput={{this.setDraft}}
+          aria-label={{@label}}
+          data-test-pretui-editable-field
+          {{fieldSession this.selectOnFocus this.beginSession this.endSession}}
+          {{on 'keydown' this.onKeydown}}
+          {{on 'focusout' this.onFocusout}}
+        />
+      {{else}}
+        <button
+          type='button'
+          class='pretui-editable-trigger'
+          aria-label={{this.triggerLabel}}
+          disabled={{this.disabled}}
+          data-test-pretui-editable-trigger
+          {{focusWhen this.restoreFocus}}
+          {{on 'click' this.open}}
+        >
+          <span class='pretui-editable-value'>
+            {{#if (has-block 'preview')}}
+              {{yield this.value to='preview'}}
+            {{else}}
+              {{this.shown}}
+            {{/if}}
+          </span>
+          {{#let (iconFor 'pencil') as |Pencil|}}
+            {{#if Pencil}}
+              <Pencil class='pretui-editable-pencil' aria-hidden='true' />
+            {{/if}}
+          {{/let}}
+        </button>
+      {{/if}}
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-editable {
+          --ed-h: var(--boxel-form-control-height-sm);
+          --ed-text: var(--boxel-font-size-xs);
+          --ed-pad: var(--space-2, 0.375rem);
+          --ed-snap: var(--pretui-dur-snap, 180ms) var(--pretui-ease-snap, ease);
+          display: inline-grid;
+          inline-size: 100%;
+          min-inline-size: 0;
+          font-size: var(--ed-text);
+          letter-spacing: var(--track-ui, 0.01em);
+        }
+        .pretui-editable-trigger {
+          display: inline-flex;
+          align-items: center;
+          gap: var(--ed-pad);
+          inline-size: 100%;
+          min-block-size: var(--ed-h);
+          margin: 0;
+          padding-block: 0;
+          padding-inline: var(--ed-pad);
+          font: inherit;
+          letter-spacing: inherit;
+          text-align: start;
+          color: inherit;
+          background-color: transparent;
+          border: 0;
+          border-radius: var(--radius);
+          box-shadow: 0 0 0 1px transparent;
+          cursor: text;
+          transition:
+            background-color var(--ed-snap),
+            box-shadow var(--ed-snap);
+        }
+        .pretui-editable-trigger:hover:not(:disabled) {
+          background-color: var(--hover);
+          box-shadow: 0 0 0 1px var(--border);
+        }
+        .pretui-editable-trigger:focus-visible {
+          outline: 2px solid var(--ring);
+          outline-offset: 2px;
+        }
+        .pretui-editable-trigger:disabled {
+          cursor: default;
+          opacity: 0.6;
+        }
+        .pretui-editable-value {
+          flex: 1;
+          min-inline-size: 0;
+          overflow-wrap: anywhere;
+        }
+        .pretui-editable[data-empty='true'] .pretui-editable-value {
+          color: var(--muted-foreground);
+        }
+        .pretui-editable-pencil {
+          flex: none;
+          inline-size: 0.75rem;
+          block-size: 0.75rem;
+          color: var(--muted-foreground);
+          opacity: 0;
+          transition: opacity var(--ed-snap);
+        }
+        .pretui-editable-trigger:hover .pretui-editable-pencil,
+        .pretui-editable-trigger:focus-visible .pretui-editable-pencil {
+          opacity: 1;
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/editable.md

@@ -0,0 +1,79 @@
+## What it is
+
+Text that reads as a value until it is a field. A name in a profile header, a title on a card, a caption under an image: the reader sees plain text, and the person who owns it clicks (or presses Enter on) that text and gets an **Input** in the same place. Enter commits, Escape puts the old value back, and leaving the field commits unless told otherwise.
+
+It is one field. If a record has several of these and they should save together with an undo per field and a docked footer, that is **RecordDetail**, which is this pattern at form scale. If the value is always a field, use **Input** inside a **Field**. If it is a longer passage, there is no textarea mode here; **Textarea** in a Field is the honest choice.
+
+## The contract
+
+```
+@value?             — controlled text; omit for the uncontrolled half
+@defaultValue?      — uncontrolled seed
+@label?             — what the value is ("Name"); spoken in the trigger's name
+@placeholder?       — muted preview text while empty, and the field's placeholder
+@disabled?          — the trigger is a disabled button; nothing opens
+@editing?           — controlled edit state; omit and use @defaultEditing
+@defaultEditing?    — start open (default false)
+@onEditingChange?   — every open and close, with the requested state
+@onSubmit?          — every commit, with the committed string
+@onChange?          — only when the committed value differs (@onValueChange is the alias)
+@onCancel?          — Escape, or blur with @submitOnBlur off
+@submitOnBlur?      — leaving the field commits (default true); false restores
+@selectOnFocus?     — select the whole value when the field opens (default true)
+<:preview as |value|>  — replaces the plain text inside the trigger
+```
+
+Aliases: `@isDisabled` for `@disabled`, `@startWithEditView` for `@defaultEditing`.
+
+**Two hybrid states, one component.** The value and the edit state are each controlled-or-uncontrolled independently, on the usual rule: with the arg undefined the component keeps its own state; with it set the component never moves itself and only reports through the callback. A parent that controls `@editing` can therefore hold the field closed (or open) regardless of what the user does, and `@onEditingChange` tells it what was asked for.
+
+**Commit is not change.** `@onSubmit` fires on every commit, including one that left the text as it was; `@onChange` fires only when the committed value differs from the previous one. A consumer that autosaves listens to one, a consumer that counts edits listens to the other.
+
+**The draft is private.** Typing changes nothing outside the component until Enter or blur. Escape discards the draft and fires `@onCancel`; the value the parent holds is never touched by a cancel.
+
+**Focus returns on Enter and Escape.** When the field closes by either key, the trigger is rendered again and takes focus on that render. When it closes on blur, focus has already gone where the reader sent it and stays there. There is no timer anywhere in this component; the handoff rides the render.
+
+**Every opening is a fresh session.** The trigger, a parent setting `@editing`, and `@defaultEditing` all start the field from the current value, so a controlled `@editing` can open and close any number of times. A field the parent holds open stays in its session: every Enter, Escape and blur is reported again.
+
+**Enter during IME composition does not commit.** The Enter that confirms a candidate belongs to the input method.
+
+## Prior art
+
+**Chakra `Editable`** is the reference shape: `EditablePreview`, `EditableInput` (or `EditableTextarea`), optional `EditableControls` with edit / submit / cancel buttons, and the `value` / `defaultValue` / `onChange` / `onSubmit` / `onCancel` / `submitOnBlur` / `startWithEditView` / `selectAllOnFocus` props. This component takes the same names where it has the same thing, so a port from Chakra mostly renames the tag. **SLDS inline edit** renders the static value as a non-interactive element and hangs a separate pencil button beside it, so the value itself does nothing and a field costs two tab stops; it has no Escape path. **Ant `Typography` with `editable`** is the same idea attached to a text component, with an explicit pencil icon as the only entry.
+
+Where this is better: **the value is the button.** Clicking anywhere on the text opens the field, the field is one tab stop, and the button's name says both what it is and what it currently holds, so a screen reader hears "Edit Name, currently Ada" rather than an unlabelled pencil. Escape exists and returns focus. The pencil is a hover and focus affordance, not the target.
+
+Where it is thinner, plainly: **no inline confirm and cancel controls**, so a pointer user's only cancel path is not there; Escape is keyboard-only and blur commits by default. **No textarea mode**, so a multi-line value does not fit. **No `isPreviewFocusable={false}`**: the preview is always the focusable trigger, which is the accessible choice and also the only one offered. The field is **Input** and nothing else, so `@type`, helper text and validation are not reachable through this component.
+
+## Accessibility
+
+No APG pattern names this exactly; it is a **button** that discloses an **input** in the same place, and both halves are native.
+
+- **The trigger is a `<button type="button">`** with `aria-label` built from `@label` and the value: "Edit Name, currently Ada", or "Edit Name, empty" when there is nothing yet. That name is what makes the component legible to a screen reader; the visible text alone would read as a stray word.
+- **Omitting `@label` is the caller's failure.** The name degrades to "Edit, currently Ada", which says what the button does but not what the value is. Pass the label.
+- **The field is named too**: `@label` lands as `aria-label` on the input, so the person who opened it is told what they are editing.
+- **Focus is managed once, on close.** Opening focuses the input and selects its text (unless `@selectOnFocus` is off); closing renders the trigger and focuses it. Nothing else moves focus, and nothing is timed.
+- **Enter and Escape are handled on the field**, with the default prevented so an enclosing form does not submit on Enter and a dialog does not close on Escape.
+- **Disabled is the native attribute** on the trigger: it leaves the tab order and announces as dimmed. A disabled Editable is therefore not reachable at all, which is right for a value that cannot be changed; if it should still be readable by keyboard, render the text and not this component.
+- **The pencil is decorative** (`aria-hidden`) and appears on hover and focus only; nothing depends on seeing it.
+- Since the trigger is a button, the preview block must not contain another interactive element: a link inside the preview is a nested-interactive failure, and it is the caller's to avoid.
+
+## Theming
+
+Read from the host theme: `--hover` and `--border` (the trigger's hover surface and hairline), `--ring` (the focus outline), `--radius`, `--muted-foreground` (the empty-state placeholder and the pencil). Hoisted once on the root as internal variables: `--boxel-form-control-height-sm` (the trigger's minimum height, the same as the Input it opens into, so the row does not jump when the field opens), `--boxel-font-size-xs` (the Input's text size), `--space-2`, `--track-ui`, and `--pretui-dur-snap` / `--pretui-ease-snap` for the hover transition.
+
+The trigger paints nothing at rest, so it inherits the surface and ink it sits on; hover adds the `--hover` fill and a `--border` hairline so the text reads as editable. The open field is **Input**'s dress entirely, so a theme that retunes Input retunes this. Fixed here: the 0.75rem pencil and its hover-only opacity.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+
+## React ecosystem
+
+| Agent types                                             | Give them                                                                      |
+| ------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| Chakra `Editable` + `EditablePreview` + `EditableInput` | this component; the preview and input are built in                             |
+| `EditableControls` (submit / cancel buttons)            | not offered; Enter, Escape and blur are the paths                              |
+| `EditableTextarea`                                      | **Textarea** in a **Field**                                                    |
+| `startWithEditView`, `selectAllOnFocus`, `submitOnBlur` | `@startWithEditView` (or `@defaultEditing`), `@selectOnFocus`, `@submitOnBlur` |
+| `isPreviewFocusable`, `isDisabled`                      | always focusable; `@isDisabled` or `@disabled`                                 |
+| SLDS inline edit, Ant `Typography editable`             | this component                                                                 |
+| a whole record of inline edits with save / undo         | **RecordDetail**                                                               |