Story-2264 walkthrough - standard keyboard shortcuts across editable content blocks

PR: #565: feat(app): standardize editable block shortcuts [Story-2264] by @anyamshwr

Files changed

8 file(s), +186 / -41 lines

Path	Role	+	-
src/components/matter-detail/brief/editable-field-with-history.stories.tsx	Component	+1	-1
src/components/matter-detail/brief/frame-summary-history.stories.tsx	Component	+2	-3
src/components/matter-detail/brief/frame-summary-history.test.tsx	Component	+37	-0
src/components/matter-detail/brief/frame-summary-history.tsx	Component	+4	-30
src/components/shared/editable-surface-preset.test.ts	Component	+33	-0
src/components/shared/editable-surface-shortcuts.test.ts	Component	+67	-0
src/components/shared/editable-surface-shortcuts.ts	Component	+20	-0
src/components/shared/editable-surface.tsx	Component	+22	-7

Story-2264: standard keyboard shortcuts across editable content blocks

The shared editing substrate already unified the editor engine, presets, and history rail, but keyboard behavior still had two product-level gaps: Ctrl/Cmd+S fell through to the browser instead of saving the focused editor, and the shared history wrapper still consumed Ctrl/Cmd+Z / redo for version navigation. This revision keeps the editor thin: StarterKit continues to own rich-text shortcuts such as bold and italic, while PRAMAAN adds only the two application-specific bindings it actually owns: save and explicit underline blocking.

What changed

Bold and italic stay native to StarterKit. There is no custom Mod-b or Mod-i production logic. When a preset enables bold / italic (light and full), StarterKit provides those shortcuts. When plain disables those marks, the shortcuts disappear with them.

The custom shortcut layer owns only Mod-s and Mod-u. Mod-s blurs the focused editor and reuses the existing onBlur commit path, which saves only that one dirty block and prevents browser Save Page. Mod-u is blocked consistently because underline remains intentionally unsupported.

Undo/redo stays the editor's own history. The shared history wrapper no longer binds Ctrl/Cmd+Z, Ctrl/Cmd+Shift+Z, or Ctrl/Cmd+Y for saved-version navigation, so typing undo/redo is never hijacked by the version rail.

Read-only, locked, and canonical surfaces stay inert. Non-editable surfaces still do not mutate, and the save shortcut path now returns without blurring or committing when the surface is not editable.

Acceptance criteria map

Acceptance criterion	How this Story satisfies it
Consistent Ctrl/Cmd shortcut behavior across editable content blocks	The shared substrate still owns the app-specific keyboard policy once, and every `EditableSurface` caller inherits it.
Rich presets support `Ctrl/Cmd+B` and `Ctrl/Cmd+I`	StarterKit provides those shortcuts natively when the preset enables the `bold` and `italic` marks. `plain` disables those marks, so there is no rich shortcut path to preserve there.
Underline decided explicitly	Underline is intentionally unsupported, and `Ctrl/Cmd+U` is blocked consistently in the shared shortcut layer.
`Ctrl/Cmd+Z` and redo preserve native editor history	Saved-version navigation shortcuts were removed from `EditableFieldWithHistory`.
`Ctrl/Cmd+S` saves only the focused dirty block	`Mod-s` blurs only the focused editor, which commits through the existing single-editor blur-save path; sibling editors are untouched.
Read-only / locked / canonical blocks are inert	The app-specific shortcut layer exits without save/blur side effects when the surface is not editable.
Automated tests cover Ctrl, Cmd, and inert states	Focused Vitest coverage now splits between preset-level StarterKit behavior, the app-specific `Mod-s`/`Mod-u` layer, and the non-hijack history rail.
Observability handling documented per pramaan-docs ADR-124	This work is instrumentation-exempt: it adds no new route, workflow boundary, transport, background job, or external call. It only adjusts client-side editor shortcut behavior.

Acceptance criterion

How this Story satisfies it

Consistent Ctrl/Cmd shortcut behavior across editable content blocks

The shared substrate still owns the app-specific keyboard policy once, and every EditableSurface caller inherits it.

Rich presets support Ctrl/Cmd+B and Ctrl/Cmd+I

StarterKit provides those shortcuts natively when the preset enables the bold and italic marks. plain disables those marks, so there is no rich shortcut path to preserve there.

Underline decided explicitly

Underline is intentionally unsupported, and Ctrl/Cmd+U is blocked consistently in the shared shortcut layer.

Ctrl/Cmd+Z and redo preserve native editor history

Saved-version navigation shortcuts were removed from EditableFieldWithHistory.

Ctrl/Cmd+S saves only the focused dirty block

Mod-s blurs only the focused editor, which commits through the existing single-editor blur-save path; sibling editors are untouched.

Read-only / locked / canonical blocks are inert

The app-specific shortcut layer exits without save/blur side effects when the surface is not editable.

Automated tests cover Ctrl, Cmd, and inert states

Focused Vitest coverage now splits between preset-level StarterKit behavior, the app-specific Mod-s/Mod-u layer, and the non-hijack history rail.

Observability handling documented per pramaan-docs ADR-124

This work is instrumentation-exempt: it adds no new route, workflow boundary, transport, background job, or external call. It only adjusts client-side editor shortcut behavior.

Files

File	Change
`src/components/shared/editable-surface.tsx`	Remains the thin shared editor wrapper; wires in the minimal app-specific save/underline shortcut layer and keeps blur-save / dirty-baseline behavior intact.
`src/components/shared/editable-surface-shortcuts.ts`	New minimal TipTap shortcut layer for `Mod-s` and `Mod-u` only.
`src/components/shared/editable-surface-shortcuts.test.ts`	Unit tests the app-specific shortcut layer directly.
`src/components/shared/editable-surface-preset.test.ts`	Preset-level proof that StarterKit bold/italic are enabled only for rich presets and absent for `plain`.
`src/components/matter-detail/brief/frame-summary-history.tsx`	Removes saved-version keyboard hijack and updates the helper copy shown while viewing history.
`src/components/matter-detail/brief/frame-summary-history.test.tsx`	Proves undo/redo no longer navigates saved versions while editing or in read-only history views.
`src/components/matter-detail/brief/*.stories.tsx`	Updates story copy so the docs match the shipped shortcut behavior.

File

Change

src/components/shared/editable-surface.tsx

Remains the thin shared editor wrapper; wires in the minimal app-specific save/underline shortcut layer and keeps blur-save / dirty-baseline behavior intact.

src/components/shared/editable-surface-shortcuts.ts

New minimal TipTap shortcut layer for Mod-s and Mod-u only.

src/components/shared/editable-surface-shortcuts.test.ts

Unit tests the app-specific shortcut layer directly.

src/components/shared/editable-surface-preset.test.ts

Preset-level proof that StarterKit bold/italic are enabled only for rich presets and absent for plain.

src/components/matter-detail/brief/frame-summary-history.tsx

Removes saved-version keyboard hijack and updates the helper copy shown while viewing history.

src/components/matter-detail/brief/frame-summary-history.test.tsx

Proves undo/redo no longer navigates saved versions while editing or in read-only history views.

src/components/matter-detail/brief/*.stories.tsx

Updates story copy so the docs match the shipped shortcut behavior.

Verify

pnpm exec vitest run src/components/shared/editable-surface.test.tsx src/components/shared/editable-surface-shortcuts.test.ts src/components/shared/editable-surface-preset.test.ts src/components/matter-detail/brief/frame-summary-history.test.tsx

- passed.

pnpm lint src/components/shared/editable-surface.tsx src/components/shared/editable-surface-shortcuts.ts src/components/shared/editable-surface-shortcuts.test.ts src/components/shared/editable-surface-preset.test.ts src/components/matter-detail/brief/frame-summary-history.tsx src/components/shared/editable-surface.test.tsx src/components/matter-detail/brief/frame-summary-history.test.tsx src/components/matter-detail/brief/editable-field-with-history.stories.tsx src/components/matter-detail/brief/frame-summary-history.stories.tsx

- passed.

$env:NEXT_PUBLIC_ENV='local'; pnpm build - passed.

pnpm test - not rerun end-to-end here; previously it still had unrelated pre-existing freshness failures in generated registry/catalog files outside Story-2264 scope.