@startsimpli/ui 0.4.145 → 0.4.146

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/ui",
-  "version": "0.4.145",
+  "version": "0.4.146",
   "description": "Shared UI components package for StartSimpli applications",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -152,8 +152,8 @@
     "tailwindcss": "^3.4.19",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
-    "@startsimpli/i18n": "0.1.3",
-    "@startsimpli/realtime": "0.0.2"
+    "@startsimpli/realtime": "0.0.2",
+    "@startsimpli/i18n": "0.1.3"
   },
   "keywords": [
     "ui",

package/src/components/__tests__/segmented-control.test.tsx

@@ -0,0 +1,89 @@
+/**
+ * SegmentedControl (bd startsim-whwxd.17): a one-of-N switch that reads as a
+ * control, not a row of tiny links. Built on the package's Tabs primitive, so
+ * it inherits the roving focus and arrow keys rather than re-implementing them.
+ */
+import { act, fireEvent, render, screen, waitFor } from '@testing-library/react'
+import { useState } from 'react'
+
+import { SegmentedControl } from '../ui/segmented-control'
+
+function Harness({ onChange = () => {}, disabledB = false }: { onChange?: (v: string) => void; disabledB?: boolean }) {
+  const [v, setV] = useState('a')
+  return (
+    <div>
+      <SegmentedControl
+        aria-label="Surface"
+        value={v}
+        onValueChange={(next) => {
+          setV(next)
+          onChange(next)
+        }}
+        options={[
+          { value: 'a', label: 'Read' },
+          { value: 'b', label: 'Edit', disabled: disabledB, title: disabledB ? 'Not allowed' : undefined },
+          { value: 'c', label: 'Suggest' },
+        ]}
+        controls="region-1"
+      />
+      <div id="region-1">panel</div>
+    </div>
+  )
+}
+
+describe('SegmentedControl', () => {
+  it('is a named tablist whose selected segment is announced', () => {
+    render(<Harness />)
+    const list = screen.getByRole('tablist', { name: 'Surface' })
+    expect(list).toBeInTheDocument()
+    expect(screen.getByRole('tab', { name: 'Read' })).toHaveAttribute('aria-selected', 'true')
+    expect(screen.getByRole('tab', { name: 'Edit' })).toHaveAttribute('aria-selected', 'false')
+  })
+
+  it('points every segment at the region it drives, not at a panel that does not exist', () => {
+    render(<Harness />)
+    for (const name of ['Read', 'Edit', 'Suggest']) {
+      expect(screen.getByRole('tab', { name })).toHaveAttribute('aria-controls', 'region-1')
+    }
+  })
+
+  it('selects on click (screen readers and automation click, they do not mousedown)', () => {
+    const onChange = jest.fn()
+    render(<Harness onChange={onChange} />)
+    fireEvent.click(screen.getByRole('tab', { name: 'Edit' }))
+    expect(onChange).toHaveBeenLastCalledWith('b')
+    expect(screen.getByRole('tab', { name: 'Edit' })).toHaveAttribute('aria-selected', 'true')
+  })
+
+  it('moves and selects with the arrow keys, one tab stop for the whole control', async () => {
+    const onChange = jest.fn()
+    render(<Harness onChange={onChange} />)
+    const read = screen.getByRole('tab', { name: 'Read' })
+    act(() => read.focus())
+    // Once inside, only the focused segment is in the tab order.
+    expect(read).toHaveAttribute('tabindex', '0')
+    expect(screen.getByRole('tab', { name: 'Edit' })).toHaveAttribute('tabindex', '-1')
+    fireEvent.keyDown(read, { key: 'ArrowRight' })
+    // Radix moves focus on the next tick; focusing a segment selects it.
+    await waitFor(() => expect(screen.getByRole('tab', { name: 'Edit' })).toHaveFocus())
+    expect(onChange).toHaveBeenLastCalledWith('b')
+  })
+
+  it('a disabled segment cannot be chosen and says why', () => {
+    const onChange = jest.fn()
+    render(<Harness onChange={onChange} disabledB />)
+    const edit = screen.getByRole('tab', { name: 'Edit' })
+    expect(edit).toBeDisabled()
+    expect(edit).toHaveAttribute('title', 'Not allowed')
+    fireEvent.click(edit)
+    expect(onChange).not.toHaveBeenCalled()
+  })
+
+  it('is readable: at least 36px tall segments in body-size type, with a distinct selected style', () => {
+    render(<Harness />)
+    const read = screen.getByRole('tab', { name: 'Read' })
+    expect(read.className).toMatch(/\bmin-h-9\b/)
+    expect(read.className).toMatch(/\btext-sm\b/)
+    expect(read.className).toMatch(/data-\[state=active\]:bg-background/)
+  })
+})

package/src/components/track-changes/TrackedField.tsx

@@ -21,10 +21,18 @@
  * offset would describe other text) and not a version loaded once and never
  * advanced (every read after the first save would be held back as stale).
  *
+ * OPENS READY TO TYPE (bd startsim-whwxd.17). The source editor is the default
+ * surface for every language: an editor lands in editing mode, a view-only
+ * reviewer in suggesting mode, and with `autoFocus` the caret is already in
+ * the text. Read is one choice away. Nothing is remembered between visits, so
+ * no stored "last surface" can put a click back in front of typing.
+ *
  * LAYOUT on its own container, never the viewport (startsim-jkkn7.12): the
  * rail sits beside the text when the field is wide, under it when narrow.
  */
-import { forwardRef, useCallback, useImperativeHandle, useMemo, useRef, useState, type ReactNode, type Ref } from 'react';
+import { forwardRef, useCallback, useEffect, useId, useImperativeHandle, useMemo, useRef, useState, type ReactNode, type Ref } from 'react';
+
+import { SegmentedControl } from '../ui/segmented-control';
 
 import { ChangesRail } from './ChangesRail';
 import { applyOpenSuggestions } from './final-text';
@@ -52,7 +60,12 @@ export interface TrackedFieldProps {
   onChange?: (value: string) => void;
   /** See the file header. Default: accept at `version`. */
   runAccept?: (accept: (expectedVersion: number) => Promise<AcceptResponseWire>) => Promise<unknown>;
+  /** Default `source`: the field opens editable (whwxd.17). */
   defaultSurface?: TrackedFieldSurface;
+  /** Put the caret in the text on first mount, so typing needs no click.
+   *  Give it to ONE field per page (the one on screen). Switching surfaces
+   *  later never re-takes focus. */
+  autoFocus?: boolean;
   /** Extra controls for the header (word count, save state). */
   headerExtra?: ReactNode;
   /** The Read view's element, for a host that paints its own highlights. */
@@ -67,11 +80,12 @@ export interface TrackedFieldHandle {
   flush: () => Promise<void>;
 }
 
-const seg = (on: boolean) =>
+/** An on/off toggle (Show changes, Show authors), sized like the segments. */
+const toggle = (on: boolean) =>
   [
-    'inline-flex items-center px-2 py-1 text-xs transition-colors',
+    'inline-flex min-h-9 items-center rounded-md border border-border px-3 py-1.5 text-sm font-medium transition-colors',
     'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
-    on ? 'bg-primary text-primary-foreground' : 'bg-transparent text-muted-foreground hover:bg-muted',
+    on ? 'bg-secondary text-secondary-foreground' : 'bg-background text-muted-foreground hover:text-foreground',
   ].join(' ');
 
 export const TrackedField = forwardRef<TrackedFieldHandle, TrackedFieldProps>(function TrackedField(
@@ -86,7 +100,8 @@ export const TrackedField = forwardRef<TrackedFieldHandle, TrackedFieldProps>(fu
     canEdit = true,
     onChange,
     runAccept,
-    defaultSurface,
+    defaultSurface = 'source',
+    autoFocus = false,
     headerExtra,
     readViewRef,
     className,
@@ -94,7 +109,15 @@ export const TrackedField = forwardRef<TrackedFieldHandle, TrackedFieldProps>(fu
   ref,
 ) {
   const tc = useTrackChanges({ client, field, value, version });
-  const [surface, setSurface] = useState<TrackedFieldSurface>(defaultSurface ?? (language === 'markdown' ? 'read' : 'source'));
+  const [surface, setSurface] = useState<TrackedFieldSurface>(defaultSurface);
+  // Focus is taken once, by the editor that mounts with the page. After the
+  // first commit this is false, so an editor re-mounted by a surface switch
+  // leaves focus on the control the reviewer just used.
+  const [focusOnMount, setFocusOnMount] = useState(autoFocus);
+  useEffect(() => {
+    setFocusOnMount(false);
+  }, []);
+  const bodyId = useId();
   const [view, setView] = useState<TrackedFieldView>('current');
   const [showChanges, setShowChanges] = useState(true);
   const [showAuthors, setShowAuthors] = useState(false);
@@ -160,46 +183,36 @@ export const TrackedField = forwardRef<TrackedFieldHandle, TrackedFieldProps>(fu
         <h3 className="text-xs font-semibold uppercase tracking-wide text-muted-foreground">{label}</h3>
         <div className="flex flex-wrap items-center gap-2">
           {headerExtra}
-          <div role="group" aria-label={`${label}: which text`} className="inline-flex overflow-hidden rounded-md border border-border">
-            <button type="button" className={seg(view === 'current')} aria-pressed={view === 'current'} onClick={() => setView('current')}>
-              Current
-            </button>
-            <button
-              type="button"
-              className={seg(view === 'final')}
-              aria-pressed={view === 'final'}
-              onClick={() => setView('final')}
-              title="As it would read with every open suggestion accepted"
-            >
-              Final
-            </button>
-            <button
-              type="button"
-              className={seg(view === 'original')}
-              aria-pressed={view === 'original'}
-              onClick={() => setView('original')}
-              title="As stored, without any suggestion"
-            >
-              Original
-            </button>
-          </div>
+          <SegmentedControl<TrackedFieldView>
+            aria-label={`${label}: which text`}
+            value={view}
+            onValueChange={setView}
+            controls={bodyId}
+            options={[
+              { value: 'current', label: 'Current' },
+              { value: 'final', label: 'Final', title: 'As it would read with every open suggestion accepted' },
+              { value: 'original', label: 'Original', title: 'As stored, without any suggestion' },
+            ]}
+          />
           {marked && (
-            <div role="group" aria-label={`${label}: surface`} className="inline-flex overflow-hidden rounded-md border border-border">
-              <button type="button" className={seg(surface === 'read')} aria-pressed={surface === 'read'} onClick={() => setSurface('read')}>
-                Read
-              </button>
-              <button type="button" className={seg(surface === 'source')} aria-pressed={surface === 'source'} onClick={() => setSurface('source')}>
-                {canEdit ? 'Edit' : 'Suggest'}
-              </button>
-            </div>
+            <SegmentedControl<TrackedFieldSurface>
+              aria-label={`${label}: surface`}
+              value={surface}
+              onValueChange={setSurface}
+              controls={bodyId}
+              options={[
+                { value: 'read', label: 'Read' },
+                { value: 'source', label: canEdit ? 'Edit' : 'Suggest' },
+              ]}
+            />
           )}
           {marked && (
-            <button type="button" className={`${seg(showChanges)} rounded-md border border-border`} aria-pressed={showChanges} onClick={() => setShowChanges((v) => !v)}>
+            <button type="button" className={toggle(showChanges)} aria-pressed={showChanges} onClick={() => setShowChanges((v) => !v)}>
               Show changes
             </button>
           )}
           {marked && surface === 'read' && (
-            <button type="button" className={`${seg(showAuthors)} rounded-md border border-border`} aria-pressed={showAuthors} onClick={() => setShowAuthors((v) => !v)}>
+            <button type="button" className={toggle(showAuthors)} aria-pressed={showAuthors} onClick={() => setShowAuthors((v) => !v)}>
               Show authors
             </button>
           )}
@@ -207,7 +220,7 @@ export const TrackedField = forwardRef<TrackedFieldHandle, TrackedFieldProps>(fu
       </div>
 
       <div className="grid gap-4 p-4 @3xl:grid-cols-[minmax(0,1fr)_18rem]">
-        <div className="min-w-0">
+        <div className="min-w-0" id={bodyId}>
           {!marked ? (
             <>
               <p className="mb-2 text-xs text-muted-foreground" role="status">
@@ -254,6 +267,7 @@ export const TrackedField = forwardRef<TrackedFieldHandle, TrackedFieldProps>(fu
               show={{ suggestions: showChanges, comments: showChanges }}
               showAuthors={showAuthors}
               onShowAuthorsChange={setShowAuthors}
+              autoFocus={focusOnMount}
               onChange={onChange}
               onPropose={tc.propose}
               onActiveChange={(m) => setActive(m && m.kind !== 'blame' && m.kind !== 'local' ? m.id : null)}

package/src/components/track-changes/TrackedTextEditor.tsx

@@ -70,6 +70,7 @@ import {
   type TrackKeys,
   type TrackMark,
 } from './extension';
+import { SegmentedControl } from '../ui/segmented-control';
 import type { BlameSpan, CommentThread, SelectionAnchor, Suggestion } from './types';
 
 export type TrackMode = 'editing' | 'suggesting';
@@ -131,6 +132,11 @@ export interface TrackedTextEditorProps {
   keys?: TrackKeys;
   /** Render the mode and authors toolbar. Default true. */
   toolbar?: boolean;
+  /** Put the caret in the text when the editor mounts, so the reviewer can
+   *  type without a click (bd startsim-whwxd.17). Read once, at mount; it
+   *  never takes focus from another control that already has it. Escape
+   *  gives focus back to the page. */
+  autoFocus?: boolean;
   className?: string;
   editorClassName?: string;
 }
@@ -217,6 +223,7 @@ export const TrackedTextEditor = forwardRef<TrackedTextEditorHandle, TrackedText
     const activeRef = useRef<TrackMark | null>(null);
 
     const helpId = useId();
+    const hostId = useId();
     const [innerMode, setInnerMode] = useState<TrackMode>(defaultMode ?? (canEdit ? 'editing' : 'suggesting'));
     const mode: TrackMode = !canEdit ? 'suggesting' : (modeProp ?? innerMode);
     const [innerShowAuthors, setInnerShowAuthors] = useState(defaultShowAuthors);
@@ -324,6 +331,18 @@ export const TrackedTextEditor = forwardRef<TrackedTextEditorHandle, TrackedText
       });
 
       const k = { ...DEFAULT_KEYS, ...p.keys };
+      // Escape leaves the text, so a page's single-key shortcuts (which stand
+      // down while focus is in an editable element) are one key away even
+      // when the editor took focus on load.
+      const escapeLeaves = keymap.of([
+        {
+          key: 'Escape',
+          run: (v) => {
+            v.contentDOM.blur();
+            return true;
+          },
+        },
+      ]);
       const view = new EditorView({
         parent: host,
         state: EditorState.create({
@@ -331,6 +350,7 @@ export const TrackedTextEditor = forwardRef<TrackedTextEditorHandle, TrackedText
           extensions: [
             trackChanges({ keys: k }),
             compartments.history.of(history()),
+            escapeLeaves,
             keymap.of([...defaultKeymap, ...historyKeymap]),
             EditorView.lineWrapping,
             compartments.language.of([]),
@@ -343,6 +363,10 @@ export const TrackedTextEditor = forwardRef<TrackedTextEditorHandle, TrackedText
         }),
       });
       viewRef.current = view;
+      if (p.autoFocus && typeof document !== 'undefined') {
+        const current = document.activeElement;
+        if (!current || current === document.body) view.contentDOM.focus({ preventScroll: true });
+      }
       return () => {
         void flush();
         view.destroy();
@@ -491,10 +515,10 @@ export const TrackedTextEditor = forwardRef<TrackedTextEditorHandle, TrackedText
     const k = { ...DEFAULT_KEYS, ...keys };
     const segment = (on: boolean) =>
       [
-        'rounded px-2.5 py-1 text-sm font-medium transition-colors',
+        'min-h-9 rounded-md border border-border px-3 py-1.5 text-sm font-medium transition-colors',
         'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
         'disabled:cursor-not-allowed disabled:opacity-50',
-        on ? 'bg-secondary text-secondary-foreground' : 'text-muted-foreground hover:text-foreground',
+        on ? 'bg-secondary text-secondary-foreground' : 'bg-background text-muted-foreground hover:text-foreground',
       ].join(' ');
 
     const suggestDisabledWhy =
@@ -527,28 +551,26 @@ export const TrackedTextEditor = forwardRef<TrackedTextEditorHandle, TrackedText
       <div data-testid="tracked-text-editor" className={['@container flex flex-col gap-2', className].filter(Boolean).join(' ')}>
         {toolbar && (
           <div className="flex flex-col gap-2 @md:flex-row @md:items-center @md:justify-between">
-            <div role="group" aria-label="Mode" className="inline-flex w-fit gap-0.5 rounded-md border border-border p-0.5">
-              <button
-                type="button"
-                className={segment(mode === 'editing')}
-                aria-pressed={mode === 'editing'}
-                disabled={!canEdit || readOnly}
-                title={!canEdit ? 'You can suggest changes to this field but not edit it.' : undefined}
-                onClick={() => setMode('editing')}
-              >
-                Editing
-              </button>
-              <button
-                type="button"
-                className={segment(mode === 'suggesting')}
-                aria-pressed={mode === 'suggesting'}
-                disabled={mode !== 'suggesting' && !!suggestDisabledWhy}
-                title={suggestDisabledWhy}
-                onClick={() => setMode('suggesting')}
-              >
-                Suggesting
-              </button>
-            </div>
+            <SegmentedControl<TrackMode>
+              aria-label={`${label}: mode`}
+              value={mode}
+              onValueChange={setMode}
+              controls={hostId}
+              options={[
+                {
+                  value: 'editing',
+                  label: 'Editing',
+                  disabled: !canEdit || readOnly,
+                  title: !canEdit ? 'You can suggest changes to this field but not edit it.' : undefined,
+                },
+                {
+                  value: 'suggesting',
+                  label: 'Suggesting',
+                  disabled: mode !== 'suggesting' && !!suggestDisabledWhy,
+                  title: suggestDisabledWhy,
+                },
+              ]}
+            />
             <div className="flex flex-wrap items-center gap-x-3 gap-y-1 text-xs text-muted-foreground">
               {proposalLine && <span data-testid="proposal-state">{proposalLine}</span>}
               <button
@@ -564,6 +586,7 @@ export const TrackedTextEditor = forwardRef<TrackedTextEditorHandle, TrackedText
         )}
         <div
           ref={hostRef}
+          id={hostId}
           className={
             editorClassName ??
             'rounded-md border border-input bg-background text-sm leading-relaxed focus-within:ring-2 focus-within:ring-ring'

package/src/components/track-changes/__tests__/edit-default.test.tsx

@@ -0,0 +1,166 @@
+/**
+ * A tracked field opens ready to type (bd startsim-whwxd.17).
+ *
+ * Quinn, 2026-10-08: "you shouldnt need to click 2 buttons to start editting
+ * something." Before this, the blog opened in the rendered Read view: Edit,
+ * then a click into the text, before a key reached the field. These pin the
+ * zero-click landing for both roles, and that landing writes nothing: no
+ * PATCH-bound onChange and no suggestion POST from merely opening the page.
+ */
+import { act, fireEvent, render, screen } from '@testing-library/react'
+
+// react-markdown is ESM-only; the Read view's renderer is not under test here.
+jest.mock('../../blog/MarkdownRenderer', () => ({
+  MarkdownRenderer: ({ content }: { content: string }) => <div data-testid="md">{content}</div>,
+}))
+
+import { TrackedField } from '../TrackedField'
+import type { TrackChangesClient } from '../types'
+
+const { EditorView } = jest.requireActual('@codemirror/view')
+
+beforeAll(() => {
+  // jsdom has no layout; CodeMirror measures text with these.
+  const rect = { x: 0, y: 0, top: 0, left: 0, right: 0, bottom: 0, width: 0, height: 0, toJSON() {} }
+  Range.prototype.getBoundingClientRect = () => rect as DOMRect
+  Range.prototype.getClientRects = () => ({ length: 0, item: () => null, [Symbol.iterator]: [][Symbol.iterator] }) as unknown as DOMRectList
+})
+
+const TEXT = 'Hello world. A second sentence.'
+const page = <T,>(results: T[]) => ({ offset_unit: 'utf16', version: 3, next_cursor: null, results })
+
+function client(): TrackChangesClient {
+  return {
+    listSuggestions: jest.fn().mockResolvedValue(page([])),
+    listComments: jest.fn().mockResolvedValue(page([])),
+    blame: jest.fn().mockResolvedValue({ offset_unit: 'utf16', version: 3, spans: [] }),
+    propose: jest.fn().mockResolvedValue({}),
+    accept: jest.fn().mockResolvedValue({ version: 4 }),
+    comment: jest.fn().mockResolvedValue({}),
+  } as unknown as TrackChangesClient
+}
+
+function editorView() {
+  const el = document.querySelector('.cm-editor') as HTMLElement | null
+  return el ? EditorView.findFromDOM(el) : null
+}
+
+/** Type the way a keystroke does, at the caret, without a click first. */
+function typeAtCaret(text: string) {
+  const view = editorView()!
+  act(() => {
+    view.dispatch(view.state.replaceSelection(text), { userEvent: 'input.type' })
+  })
+}
+
+describe('a tracked field opens ready to type (whwxd.17)', () => {
+  it('an editor lands in the source editor, editing mode, focused: typing works with zero clicks', () => {
+    const onChange = jest.fn()
+    render(
+      <TrackedField client={client()} field="blog" label="Blog post" language="markdown" value={TEXT} version={3} currentActorSub="ada" onChange={onChange} autoFocus />,
+    )
+    // The editor is mounted, not the Read view.
+    expect(screen.getByTestId('tracked-text-editor')).toBeInTheDocument()
+    expect(screen.queryByTestId('tracked-read-view')).toBeNull()
+    const view = editorView()!
+    expect(view.state.readOnly).toBe(false)
+    // Focus is already in the text: no click placed it.
+    expect(view.contentDOM.contains(document.activeElement)).toBe(true)
+    // The surface control says Edit, the mode control says Editing.
+    expect(screen.getByRole('tab', { name: 'Edit' })).toHaveAttribute('aria-selected', 'true')
+    expect(screen.getByRole('tab', { name: 'Editing' })).toHaveAttribute('aria-selected', 'true')
+
+    typeAtCaret('Hi. ')
+    expect(onChange).toHaveBeenLastCalledWith('Hi. ' + TEXT)
+  })
+
+  it('a viewer lands in suggesting mode, focused, and typing makes a proposal, never an edit', () => {
+    jest.useFakeTimers()
+    try {
+      const onChange = jest.fn()
+      const c = client()
+      render(
+        <TrackedField client={c} field="blog" label="Blog post" value={TEXT} version={3} currentActorSub="vee" canEdit={false} onChange={onChange} autoFocus />,
+      )
+      const view = editorView()!
+      expect(view.state.readOnly).toBe(false)
+      expect(view.contentDOM.contains(document.activeElement)).toBe(true)
+      expect(screen.getByRole('tab', { name: 'Suggest' })).toHaveAttribute('aria-selected', 'true')
+      expect(screen.getByRole('tab', { name: 'Suggesting' })).toHaveAttribute('aria-selected', 'true')
+      expect(screen.getByRole('tab', { name: 'Editing' })).toBeDisabled()
+
+      typeAtCaret('Hi. ')
+      expect(onChange).not.toHaveBeenCalled()
+    } finally {
+      jest.useRealTimers()
+    }
+  })
+
+  it('opening the field writes nothing: no edit reported, no suggestion posted, even after blur and every debounce', async () => {
+    jest.useFakeTimers()
+    try {
+      for (const canEdit of [true, false]) {
+        const onChange = jest.fn()
+        const c = client()
+        const { rerender, unmount } = render(
+          <TrackedField client={c} field="blog" label="Blog post" value={TEXT} version={3} currentActorSub="ada" canEdit={canEdit} onChange={onChange} autoFocus />,
+        )
+        // The stored text and version move under it (a save echo, an accept
+        // elsewhere): still nobody typed.
+        rerender(
+          <TrackedField client={c} field="blog" label="Blog post" value={TEXT + ' More.'} version={4} currentActorSub="ada" canEdit={canEdit} onChange={onChange} autoFocus />,
+        )
+        await act(async () => {
+          jest.advanceTimersByTime(10_000)
+        })
+        // Focus leaves the text (a suggesting-mode blur posts a pending proposal).
+        fireEvent.blur(editorView()!.contentDOM)
+        await act(async () => {
+          jest.advanceTimersByTime(10_000)
+        })
+        expect(onChange).not.toHaveBeenCalled()
+        expect(c.propose).not.toHaveBeenCalled()
+        unmount()
+        expect(c.propose).not.toHaveBeenCalled()
+      }
+    } finally {
+      jest.useRealTimers()
+    }
+  })
+
+  it('does not take focus unless the host asks (two fields on one page cannot both have it)', () => {
+    render(<TrackedField client={client()} field="blog" label="Blog post" value={TEXT} version={3} currentActorSub="ada" />)
+    expect(screen.getByTestId('tracked-text-editor')).toBeInTheDocument()
+    expect(editorView()!.contentDOM.contains(document.activeElement)).toBe(false)
+  })
+
+  it('does not steal focus from a control the reviewer is already in', () => {
+    const outside = document.createElement('input')
+    document.body.appendChild(outside)
+    outside.focus()
+    try {
+      render(<TrackedField client={client()} field="blog" label="Blog post" value={TEXT} version={3} currentActorSub="ada" autoFocus />)
+      expect(document.activeElement).toBe(outside)
+    } finally {
+      outside.remove()
+    }
+  })
+
+  it('Escape hands focus back to the page, so its single-key shortcuts work again', () => {
+    render(<TrackedField client={client()} field="blog" label="Blog post" value={TEXT} version={3} currentActorSub="ada" autoFocus />)
+    const view = editorView()!
+    expect(view.contentDOM.contains(document.activeElement)).toBe(true)
+    fireEvent.keyDown(view.contentDOM, { key: 'Escape' })
+    expect(view.contentDOM.contains(document.activeElement)).toBe(false)
+  })
+
+  it('Read is still one choice away, and switching to it does not pull focus back into an editor', () => {
+    render(<TrackedField client={client()} field="blog" label="Blog post" value={TEXT} version={3} currentActorSub="ada" autoFocus />)
+    fireEvent.mouseDown(screen.getByRole('tab', { name: 'Read' }))
+    expect(screen.getByTestId('tracked-read-view')).toBeInTheDocument()
+    expect(screen.queryByTestId('tracked-text-editor')).toBeNull()
+    fireEvent.mouseDown(screen.getByRole('tab', { name: 'Edit' }))
+    expect(screen.getByTestId('tracked-text-editor')).toBeInTheDocument()
+    expect(editorView()!.contentDOM.contains(document.activeElement)).toBe(false)
+  })
+})

package/src/components/track-changes/__tests__/rails.test.tsx

@@ -554,10 +554,10 @@ describe('TrackedField', () => {
   it('shows Final with the open suggestions applied, and Original as stored', async () => {
     render(<TrackedField client={client()} field="blog" label="Blog" language="plain" value={TEXT} version={3} currentActorSub="ada" defaultSurface="read" />)
     await screen.findByRole('button', { name: 'Accept' })
-    fireEvent.click(screen.getByRole('button', { name: 'Final' }))
+    fireEvent.click(screen.getByRole('tab', { name: 'Final' }))
     expect(screen.getByTestId('tracked-read-view')).toHaveTextContent('Hello world. One second sentence. The end.')
     expect(screen.getByText(/as it would read with 1 open suggestion accepted/i)).toBeInTheDocument()
-    fireEvent.click(screen.getByRole('button', { name: 'Original' }))
+    fireEvent.click(screen.getByRole('tab', { name: 'Original' }))
     expect(screen.getByTestId('tracked-read-view')).toHaveTextContent(TEXT)
     expect(screen.getByTestId('tracked-read-view').querySelector('del')).toBeNull()
   })
@@ -574,7 +574,7 @@ describe('TrackedField', () => {
     render(<TrackedField client={client()} field="blog" label="Blog" language="plain" value={TEXT} version={3} currentActorSub="vee" canEdit={false} defaultSurface="read" />)
     await screen.findByTestId('rail-suggestion')
     expect(screen.queryByRole('button', { name: 'Accept' })).toBeNull()
-    expect(screen.getByRole('button', { name: 'Suggest' })).toBeInTheDocument()
+    expect(screen.getByRole('tab', { name: 'Suggest' })).toBeInTheDocument()
     expect(screen.getByLabelText('New comment on Blog')).toBeInTheDocument()
   })
 

package/src/components/track-changes/__tests__/tracked-text-editor.test.tsx

@@ -132,7 +132,7 @@ describe('suggesting mode', () => {
     const { ref, onPropose, onChange } = mountSuggesting({ onModeChange })
     typeAt(ref.current!, 0, 'X')
     await act(async () => {
-      fireEvent.click(screen.getByRole('button', { name: 'Editing' }))
+      fireEvent.click(screen.getByRole('tab', { name: 'Editing' }))
     })
     expect(onPropose).toHaveBeenCalledWith('X' + VALUE, 7)
     expect(onModeChange).toHaveBeenCalledWith('editing')
@@ -172,8 +172,8 @@ describe('who may do what', () => {
     const onChange = jest.fn()
     const ref = createRef<TrackedTextEditorHandle>()
     render(<TrackedTextEditor ref={ref} label="Blog" value={VALUE} version={1} currentActorSub="v" canEdit={false} onChange={onChange} onPropose={jest.fn()} />)
-    expect(screen.getByRole('button', { name: 'Editing' })).toBeDisabled()
-    expect(screen.getByRole('button', { name: 'Suggesting' })).toHaveAttribute('aria-pressed', 'true')
+    expect(screen.getByRole('tab', { name: 'Editing' })).toBeDisabled()
+    expect(screen.getByRole('tab', { name: 'Suggesting' })).toHaveAttribute('aria-selected', 'true')
     typeAt(ref.current!, 0, 'X')
     expect(onChange).not.toHaveBeenCalled()
   })
@@ -182,12 +182,12 @@ describe('who may do what', () => {
     const ref = createRef<TrackedTextEditorHandle>()
     render(<TrackedTextEditor ref={ref} label="Blog" value={VALUE} version={1} currentActorSub="a" onChange={jest.fn()} onPropose={jest.fn()} />)
     typeAt(ref.current!, 0, 'X')
-    expect(screen.getByRole('button', { name: 'Suggesting' })).toBeDisabled()
+    expect(screen.getByRole('tab', { name: 'Suggesting' })).toBeDisabled()
   })
 
   it('cannot suggest on a record with no version', () => {
     render(<TrackedTextEditor label="Blog" value={VALUE} version={null} currentActorSub="a" onChange={jest.fn()} onPropose={jest.fn()} />)
-    expect(screen.getByRole('button', { name: 'Suggesting' })).toBeDisabled()
+    expect(screen.getByRole('tab', { name: 'Suggesting' })).toBeDisabled()
   })
 })
 
@@ -407,7 +407,7 @@ describe('switching into suggesting mode', () => {
     const ref = createRef<TrackedTextEditorHandle>()
     render(<TrackedTextEditor ref={ref} label="Blog" value={VALUE} version={2} currentActorSub="ada" onChange={jest.fn()} onPropose={onPropose} />)
     act(() => ref.current!.view!.focus())
-    const button = screen.getByRole('button', { name: 'Suggesting' })
+    const button = screen.getByRole('tab', { name: 'Suggesting' })
     await act(async () => {
       button.focus() // the editor blurs, as a real click does
       fireEvent.click(button)

package/src/components/ui/index.ts

@@ -37,6 +37,7 @@ export * from './separator'
 export * from './skeleton'
 export * from './table'
 export * from './tabs'
+export * from './segmented-control'
 export * from './textarea'
 export * from './tooltip'
 export * from './feature-gate'

package/src/components/ui/segmented-control.tsx

@@ -0,0 +1,93 @@
+"use client"
+
+/**
+ * SegmentedControl — choose one of a few options that switch what a region
+ * shows or how it behaves (Read / Edit, Editing / Suggesting) (bd
+ * startsim-whwxd.17).
+ *
+ * BUILT ON THE PACKAGE'S TABS (./tabs, Radix), not beside it: the roving tab
+ * stop, arrow keys, Home/End and disabled-skipping come from there. What this
+ * adds is the look (readable, an obvious selected segment) and two fixes for
+ * using a tablist without TabsContent panels:
+ * - `controls` points every segment's aria-controls at the region it drives.
+ *   Radix would otherwise point it at a generated panel id that never exists.
+ * - selection on CLICK as well as mousedown. Radix selects on mousedown only;
+ *   screen readers in browse mode and automation send click.
+ *
+ * LAYOUT on the nearest `@container` ancestor, never the viewport: the
+ * segments share the full width when the container is narrow and sit inline
+ * from `@md` up. It does not declare a container itself: an inline-size
+ * container inside a flex row has no intrinsic width and collapses to zero.
+ */
+import * as React from "react"
+
+import { cn } from "../../lib/utils"
+import { Tabs, TabsList, TabsTrigger } from "./tabs"
+
+export interface SegmentedOption<T extends string = string> {
+  value: T
+  label: React.ReactNode
+  disabled?: boolean
+  /** Shown on hover; say why a disabled segment is disabled. */
+  title?: string
+  /** Accessible name when `label` is not plain text. */
+  "aria-label"?: string
+}
+
+export interface SegmentedControlProps<T extends string = string> {
+  value: T
+  onValueChange: (value: T) => void
+  options: ReadonlyArray<SegmentedOption<T>>
+  /** The control's accessible name ("Blog post: view"). Required. */
+  "aria-label": string
+  /** id of the element this control changes. */
+  controls?: string
+  className?: string
+  "data-testid"?: string
+}
+
+export function SegmentedControl<T extends string = string>({
+  value,
+  onValueChange,
+  options,
+  controls,
+  className,
+  "aria-label": ariaLabel,
+  "data-testid": testId,
+}: SegmentedControlProps<T>) {
+  const select = (next: string) => {
+    if (next === value) return
+    const opt = options.find((o) => o.value === next)
+    if (!opt || opt.disabled) return
+    onValueChange(next as T)
+  }
+  return (
+    <Tabs value={value} onValueChange={select} className={cn("w-full @md:w-auto", className)}>
+      <TabsList
+        aria-label={ariaLabel}
+        data-testid={testId}
+        className="flex h-auto w-full gap-1 rounded-lg border border-border bg-muted p-1 text-muted-foreground @md:inline-flex @md:w-auto"
+      >
+        {options.map((o) => (
+          <TabsTrigger
+            key={o.value}
+            value={o.value}
+            disabled={o.disabled}
+            title={o.title}
+            aria-label={o["aria-label"]}
+            {...(controls ? { "aria-controls": controls } : {})}
+            onClick={() => select(o.value)}
+            className={cn(
+              "min-h-9 flex-1 rounded-md px-3.5 py-1.5 text-sm font-medium @md:flex-none",
+              "text-muted-foreground hover:bg-background/60 hover:text-foreground",
+              "data-[state=active]:bg-background data-[state=active]:font-semibold data-[state=active]:text-foreground data-[state=active]:shadow-sm data-[state=active]:ring-1 data-[state=active]:ring-border",
+              "disabled:cursor-not-allowed",
+            )}
+          >
+            {o.label}
+          </TabsTrigger>
+        ))}
+      </TabsList>
+    </Tabs>
+  )
+}