Command Palette

Command Palette

The command palette is the primary keyboard-driven navigation surface. It opens with Cmd+K (macOS) or Ctrl+K (Windows/Linux), presents a unified search input that queries page titles and content simultaneously, supports keyboard-only navigation through results, and closes via Escape or a backdrop click. It also surfaces quick actions such as creating a new page.

Preconditions

• Workspace is open and loaded (sidebar is visible)
• Seed workspace contains at least 5 pages with distinct titles and content for search differentiation
• At least one page has content containing a unique body phrase (distinct from its title)

Scenarios

Seed: seed.spec.ts

1. Open palette with keyboard shortcut

The palette opens in response to the global Cmd+K / Ctrl+K shortcut regardless of where focus currently sits in the app.

Steps:

1. Navigate to the app root and ensure the workspace is loaded
2. Click somewhere in the main content area (not the search trigger button) to confirm focus is not on any special element
3. Press Cmd+K (macOS) or Ctrl+K (Windows/Linux)

Expected: A modal dialog appears with aria-label="Command Palette". The text input inside the dialog is automatically focused. The placeholder text reads “Search pages or type a command…“.

2. Open palette by clicking the sidebar search trigger

The sidebar contains a clickable search bar that opens the palette. It is an alternative entry point to the keyboard shortcut.

Steps:

1. Locate the sidebar search trigger button labelled “Search or jump to…” with a ⌘K hint
2. Click the button

Expected: The command palette dialog opens with the same modal as in scenario 1. The input is focused.

3. Close palette with Escape key

The Escape key closes the palette and returns focus to the underlying app without any navigation change.

Steps:

1. Open the command palette via Cmd+K
2. Press Escape

Expected: The command palette dialog is no longer visible. No navigation has occurred — the previously active page (if any) remains displayed.

4. Close palette by clicking outside (backdrop click)

Clicking the semi-transparent backdrop behind the palette dialog closes it.

Steps:

1. Open the command palette via Cmd+K
2. Click the backdrop overlay area (outside the white dialog box, in the dimmed region)

Expected: The command palette dialog closes. The underlying app content is visible and interactive.

5. Partial-name search returns matching pages

Typing a partial string that matches a subset of page titles narrows the results list to those matching pages under the “Pages” section.

Steps:

1. Open the command palette
2. Type the first 3–4 characters of a known page title (e.g., “Rese” for “Research Notes”)

Expected: The “Pages” section appears in the results list. At least one result item displays the matching page title. The input is not cleared and the typed string remains visible.

6. Result list shows “Pages” and “Content matches” sections

A query that matches both a page title and also appears inside the body of a different page should produce results in two distinct labeled sections.

Steps:

1. Open the command palette
2. Type a word that exists as part of at least one page title AND inside the body of a separate page

Expected: The results area shows a “Pages” section header above title-match results, and a “Content matches” section header above body-match results. Both sections are present simultaneously.

7. Navigate results with arrow keys

Arrow Down and Arrow Up move a visual selection highlight through the result items. Selection wraps at the bottom back to the top.

Steps:

1. Open the command palette and type a query that returns at least 3 results
2. Press ArrowDown once — record which item is highlighted
3. Press ArrowDown again — confirm highlight moved to the next item
4. Press ArrowUp once — confirm highlight moved back to the previous item
5. With the first item selected, press ArrowUp once more (wrap test)

Expected: Each ArrowDown press advances the blue/accent highlight to the next result item. ArrowUp retreats one item. Pressing ArrowUp when the first item is selected wraps to the last item (or vice versa for ArrowDown at the end). The footer shows ”↑ ↓ to navigate” hint text.

8. Select a result with Enter key navigates to the page

After using arrow keys to highlight a page result, pressing Enter closes the palette and loads that page in the editor.

Steps:

1. Open the command palette
2. Type a partial title to surface results
3. Press ArrowDown to highlight the first “Pages” result
4. Press Enter

Expected: The command palette closes. The editor area displays the selected page. The page title in the editor matches the result that was highlighted in the palette.

9. Select a result by clicking it navigates to the page

Clicking directly on a result item (without using keyboard navigation) closes the palette and loads the page.

Steps:

1. Open the command palette
2. Type a query that produces at least one page result
3. Click on a result item in the “Pages” section

Expected: The command palette closes. The editor displays the clicked page.

10. Empty state when query has no matches

Typing a string that cannot match any page title or content body displays a “no results” message rather than an empty or broken layout.

Steps:

1. Open the command palette
2. Type a string that is guaranteed to be absent from the workspace (e.g., “zzz_no_match_xyz_999”)

Expected: The results area shows “No results found” text. No result sections or empty section headers are rendered. The input field still displays the typed string.

11. Empty state before any query (prompt state)

When the palette opens with no query typed, it shows a prompt to start typing rather than an empty list.

Steps:

1. Open the command palette
2. Do not type anything — observe the results area

Expected: The results area shows “Start typing to search…” text (or equivalent prompt). No result items are displayed.

12. Cmd+K while palette is open toggles it closed

Pressing Cmd+K a second time while the palette is already open closes it, making it a toggle.

Steps:

1. Press Cmd+K to open the palette
2. Press Cmd+K again

Expected: The command palette dialog closes. This mirrors the same close behavior as Escape.

13. Create new page from the palette (action result)

The palette surfaces a “New Page” (or equivalent) action result that triggers page creation.

Steps:

1. Open the command palette
2. Type “new” or leave the input empty and look for an “Actions” section
3. Locate the “New Page” action result under the “Actions” section
4. Click the action result (or navigate to it with arrow keys and press Enter)

Expected: The command palette closes and the create-page dialog opens (or a new untitled page is immediately created and focused in the editor).

14. Keyboard hint footer is always visible

The footer showing keyboard hints (↑↓, ↵, esc) is visible inside the palette at all times regardless of the results state.

Steps:

1. Open the command palette with an empty query
2. Observe the bottom of the palette dialog

Expected: The footer area is present and displays keyboard shortcut hints: arrow keys for navigation, Enter to select, Escape to close.

15. Query is cleared when palette is reopened

Typing a query, closing the palette, then reopening it starts with a fresh empty input rather than the previous query.

Steps:

1. Open the command palette and type “chapter”
2. Close the palette with Escape
3. Press Cmd+K to reopen

Expected: The input field is empty. The results area shows the prompt state (“Start typing to search…”).

Test Data

Key	Value	Notes
partial_title_query	First 4 chars of a seed page title	Must match at least one page
body_only_phrase	Unique phrase in page body, not in any title	Produces content-match results only
no_match_query	zzz_no_match_xyz_999	Must not match any seed page
action_trigger_query	new	Should surface “New Page” action

Notes

• The palette uses role="dialog" and aria-modal="true" — these attributes are the primary query targets for Playwright accessibility selectors
• Section headers “Pages”, “Content matches”, “Recent Workspaces”, and “Actions” are rendered only when each result array is non-empty
• Arrow key wrapping: ArrowDown at the last item wraps to index 0; ArrowUp at index 0 wraps to the last item
• A brief “Improving search…” message may appear in the input during first workspace load — this is not a failure state; wait for it to clear before asserting results
• On macOS use Meta+k; on Windows/Linux use Control+k in Playwright press_key calls