Proposal: Action Palette + Command/Action vocabulary (RFC)#2284
Draft
merchako wants to merge 3 commits into
Draft
Proposal: Action Palette + Command/Action vocabulary (RFC)#2284merchako wants to merge 3 commits into
merchako wants to merge 3 commits into
Conversation
merchako
added a commit
that referenced
this pull request
May 16, 2026
The existing "command palette" overlay is a per-WebView generic
searchable picker (currently used by hello-rock3 to pick USFM
markers), not a global command-launcher. The CommandPalette name
was misleading from day one — the original type comment even
hinted at the conflation ("marker code like 'ft' or command
name") — and it conflicted with the broader Action Palette
concept proposed separately (see PR #2284 and
docs/plans/2026-05-15-action-palette-proposal.md).
This overlay is the cross-iframe analog of the in-tree `ComboBox`
component in `platform-bible-react` — both are built on shadcn's
`Command` (which wraps cmdk). cmdk explicitly positions its
`Command` primitive as serving both command palettes and
accessible comboboxes; aligning the overlay's name with `ComboBox`
puts the right breadcrumb for extension authors.
Renames:
- Types: CommandPaletteItem → ComboBoxItem,
CommandPaletteRequest → ComboBoxRequest
- Service method: showCommandPalette → showComboBox
- Component files: overlay-command-palette.* → overlay-combo-box.*
(matches pbr's combo-box.component.tsx kebab-case)
- Internal symbols: validateCommandPaletteRequest, OverlayCommandPalette*,
localizeCommandPaletteItems, etc.
- Overlay discriminator: 'commandPalette' → 'comboBox'
- Data attributes: data-overlay-command-palette* → data-overlay-combo-box*
- LocalizeKeys: %overlay_commandPalette_*% → %overlay_comboBox_*%,
%overlay_aria_commandPaletteOpened% → ...comboBoxOpened%
Public PAPI surface preserves CommandPaletteItem,
CommandPaletteRequest, and showCommandPalette as @deprecated
aliases so out-of-repo extensions keep working.
Capitalization note: cmdk's preferred spelling for non-command-palette
uses of `Command` is `Combobox` (lowercase b). pbr uses `ComboBox`
(capital B); this overlay matches pbr for consistency. Harmonizing
toward cmdk's spelling is out of scope here — a future refactor
could rename pbr's `ComboBox` → `Combobox`, pbr's
`MultiSelectComboBox` → `ComboboxMulti`, and the overlay
correspondingly. Flagged for a follow-up PR.
Localization values updated:
- en: 'Command palette opened' → 'Combo box opened'
- es: 'Paleta de comandos abierta' → 'Cuadro combinado abierto'
(flag for localizer review)
167 overlay tests pass; ESLint clean; papi.d.ts regenerated.
Adds CONTEXT.md establishing the distinction between Commands (machine-layer PAPI RPCs) and Actions (user-facing wrappers with localization, arg-flow, and confirmation). Adds ADR 0001 recording the decision to name the catch-all UI surface "Action Palette" rather than the industry-standard "Command Palette" to keep the user-facing vocabulary aligned with the Action concept.
Composes the appeal for the Action Palette feature and the Command/Action mental model: problem statement, glossary recap, worked examples drawn from real candidate palette items, alternatives considered, architectural posture, and explicit flagging that the code rename on this branch is illustrative — not a mandate.
- Leads 'Why this matters' with team velocity and trigger decoupling (P10 Power vs P10 Simple); user discovery third. - New top-level section 'Why two concepts instead of one?' engaging the flatten-into-Commands alternative directly, with six failure modes for the one-concept version. - Subsection 'The cost' acknowledging the seven-concept shape. - Replaces the 'illustrative rename' section with the discovery story (existing overlay is a generic picker, not an Action Palette). - Rewrites 'The ask' to invite engagement and pushback rather than ask permission to proceed. - Cuts apologetic hedges throughout.
merchako
force-pushed
the
refactor/action-palette
branch
from
db91fe8 to
5bba7af
Compare
merchako
added a commit
that referenced
this pull request
May 16, 2026
The existing "command palette" overlay is a per-WebView generic
searchable picker (currently used by hello-rock3 to pick USFM
markers), not a global command-launcher. The CommandPalette name
was misleading from day one — the original type comment even
hinted at the conflation ("marker code like 'ft' or command
name") — and it conflicted with the broader Action Palette
concept proposed separately (see PR #2284 and
docs/plans/2026-05-15-action-palette-proposal.md).
This overlay is the cross-iframe analog of the in-tree `ComboBox`
component in `platform-bible-react` — both are built on shadcn's
`Command` (which wraps cmdk). cmdk explicitly positions its
`Command` primitive as serving both command palettes and
accessible comboboxes; aligning the overlay's name with `ComboBox`
puts the right breadcrumb for extension authors.
Renames:
- Types: CommandPaletteItem → ComboBoxItem,
CommandPaletteRequest → ComboBoxRequest
- Service method: showCommandPalette → showComboBox
- Component files: overlay-command-palette.* → overlay-combo-box.*
(matches pbr's combo-box.component.tsx kebab-case)
- Internal symbols: validateCommandPaletteRequest, OverlayCommandPalette*,
localizeCommandPaletteItems, etc.
- Overlay discriminator: 'commandPalette' → 'comboBox'
- Data attributes: data-overlay-command-palette* → data-overlay-combo-box*
- LocalizeKeys: %overlay_commandPalette_*% → %overlay_comboBox_*%,
%overlay_aria_commandPaletteOpened% → ...comboBoxOpened%
Public PAPI surface preserves CommandPaletteItem,
CommandPaletteRequest, and showCommandPalette as @deprecated
aliases so out-of-repo extensions keep working.
Capitalization note: cmdk's preferred spelling for non-command-palette
uses of `Command` is `Combobox` (lowercase b). pbr uses `ComboBox`
(capital B); this overlay matches pbr for consistency. Harmonizing
toward cmdk's spelling is out of scope here — a future refactor
could rename pbr's `ComboBox` → `Combobox`, pbr's
`MultiSelectComboBox` → `ComboboxMulti`, and the overlay
correspondingly. Flagged for a follow-up PR.
Localization values updated:
- en: 'Command palette opened' → 'Combo box opened'
- es: 'Paleta de comandos abierta' → 'Cuadro combinado abierto'
(flag for localizer review)
167 overlay tests pass; ESLint clean; papi.d.ts regenerated.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
TL;DR
Proposing a feature — the Action Palette — and a vocabulary shift to support it: separating Command (PAPI RPC, machine layer) from Action (user-facing wrapper with localized presentation, arg-flow, confirmation). @tjcouch-sil, this is an RFC asking for your engagement and pushback, not a sign-off.
Read this: the full proposal lives in this PR's diff at
docs/plans/2026-05-15-action-palette-proposal.md. It covers the case, worked examples from real candidate palette items, a dedicated section on why two concepts instead of one (the alternative you're most likely to prefer), an honest section on the layering cost, and explicit questions for you to react to.This branch is docs-only:
CONTEXT.md— glossary entry for Command, Action, Action Provider, Bound Action, Arg-flow, Deep Link, Action Palettedocs/adr/0001-action-palette-naming.md— naming rationale (Action Palette vs. Command Palette)docs/plans/2026-05-15-action-palette-proposal.md— the proposal itselfCompanion PR: while preparing this proposal I started renaming the existing `overlay-command-palette` code and discovered something that strengthens the case: the existing overlay is a generic per-WebView picker (used today by hello-rock3 to pick USFM markers), not an Action Palette. The original `CommandPaletteItem` doc even hinted at the dual use (`marker code like 'ft' or command name`). That rename — retargeted at a generic name (
ComboBox) — is on a separate draft PR: #2286. The two decisions are independent; please evaluate them separately.Status: draft. Not asking to merge. Asking you to grill the model, push back on the layering, raise concerns I haven't anticipated, and give me your gut on whether this is the direction the platform should grow and on timing.
This change is