Copilot instructions

1---
2applyTo: 'apps/studio/**'
3---
4 
5# Studio Shortcut Review Rules
6 
7All comments are **advisory**.
8 
9## Core Principle
10 
11When Studio UI changes introduce or materially alter repeated user actions, consider whether keyboard shortcut coverage should be added or updated. Shortcuts should use the shared Studio shortcut system and be discoverable from the visible UI.
12 
13## When to Flag
14 
15- PR adds a primary repeated action, toolbar action, list/table operation, or sub-page navigation without considering shortcut coverage.
16- PR adds a one-off `keydown` listener for a normal Studio action instead of using the shortcut registry and `useShortcut`.
17- PR registers a shortcut but does not expose it via `ShortcutTooltip`, `ShortcutBadge`, or command-menu badge where the action is visible.
18- PR uses `G then ...` for a non-navigation action.
19- PR adds a broad `Mod+letter` shortcut that overlaps common browser, editor, system, copy/save/search, or devtools behaviour.
20- PR adds a shortcut without checking existing registry and non-registry listeners for collisions.
21- PR adds a search/filter `<Input>` without `onKeyDown={onSearchInputEscape(...)}` — see **Search Inputs** below.
22 
23## Preferred Pattern
24 
25- Add definitions in `apps/studio/state/shortcuts/registry.ts` or `apps/studio/state/shortcuts/registry/*`.
26- Register with `useShortcut`.
27- Gate availability with `enabled`.
28- Surface visible actions with `ShortcutTooltip` or `ShortcutBadge`.
29- Prefer scoped, mnemonic sequential chords over global modifier chords.
30- Set `showInSettings: false` on contextual shortcuts (scoped to a specific page state, sheet, or panel).
31- When a shortcut group should appear in the reference sheet (`Mod+/`), add the group key to `SHORTCUT_REFERENCE_GROUP_ORDER` in `apps/studio/state/shortcuts/referenceGroups.ts` and a human label to `GROUP_LABELS` in `ShortcutsReferenceSheet.tsx`.
32- For sheet-scoped shortcuts (active only while a `<Sheet>` is open), mount `useShortcut` inside the sheet component gated by the `open` prop — see `apps/studio/components/interfaces/ConnectSheet/useConnectSheetShortcut.ts` as the canonical example.
33 
34## Search Inputs
35 
36Every `<Input>` used as a search or filter field must include the staged-Escape handler from `apps/studio/lib/keyboard.ts`:
37 
38```tsx
39import { onSearchInputEscape } from '@/lib/keyboard'
40 
41;<Input
42  value={query}
43  onChange={(e) => setQuery(e.target.value)}
44  onKeyDown={onSearchInputEscape(query, setQuery)}
45/>
46```
47 
48Behaviour:
49 
50- **Escape while the input has a value** → clears the value, keeps focus (so a second Escape then blurs)
51- **Escape while the input is empty** → blurs the input
52- Stops propagation on Escape so the keystroke does not accidentally close a parent dialog or sheet
53 
54When pairing with `useShortcut(LIST_PAGE_FOCUS_SEARCH, ...)` to focus a search input via keyboard, always also add `onSearchInputEscape` on the same input — focus and escape-to-blur are always a pair.
55 
56Canonical implementation context: `apps/studio/state/shortcuts/registry.ts`, `apps/studio/state/shortcuts/useShortcut.tsx`, and `apps/studio/components/ui/Shortcut*.tsx`
57