# Search and navigation

Beyond clicking through the file tree, the workbench gives the reader a handful of ways to jump
straight to what they're after: a palette over everything, language-aware jumps in the editor,
and two panes — Search and Problems — that list places rather than show one file at a time.

## The command palette

`Mod-P` opens the palette on files; `Mod-K` or `Mod-Shift-P` opens it on commands; `Mod-Shift-O`
opens it on the symbols in the file showing. Typing a leading character switches mode wherever
the palette is already open, the way VS Code's quick open does:

| Prefix | Mode                               |
| ------ | ---------------------------------- |
| `>`    | Commands                           |
| `@`    | Symbols in the file showing        |
| `#`    | Symbols across the whole workspace |

Escape closes the palette; choosing a row runs it.

On files, open tabs are listed first, in tab order, then the rest of the tree. On commands, it
lists everything a manifest declared with `contributes.commands` and registered with
`vscode.commands.registerCommand` — an extension reaches the palette just by doing both, nothing
extra to opt in. The two symbol modes ask whatever language provider is registered for the file:
the workspace-wide one is empty until a provider exists for it.

:read-more{to="/api/commands"}

## Quick pick and prompts

Anything an extension asks the reader — pick one of these, type a value — comes through the same
field the palette uses. `window.showQuickPick` puts up a list and resolves with what was chosen;
`window.showInputBox` puts up a single text field. Both close themselves once answered, or on
Escape.

```ts
const choice = await vscode.window.showQuickPick(["staging", "production"], {
  placeHolder: "Deploy to…",
});
```

`window.createQuickPick` and `window.createInputBox` build the same widget for a session that
stays open across several answers — filtering as the reader types, say, or showing a busy state
while something loads.

:read-more{to="/api/ui"}

## Go to definition, hover and references

These come from a language provider, not from the editor itself — a workbench with none attached
answers every gesture with nothing to jump to.

- **Hover** a symbol to see its type or doc comment, if a provider registered one.
- **`Mod`-click**, or place the caret and press **`F12`**, jumps to where a symbol is defined.
- **Find All References**, from the document's right-click menu, lists every use of the symbol
  under the caret across the workspace — which needs somewhere to draw a list of places, not just
  a jump, so it only appears once an extension has called
  `codelet.window.registerLocationsView`. `codelet/extensions/search` is the built-in that does,
  landing a references search in the same rows a text search does.

A jump only lands where the workbench can actually open something: a `/`-rooted path already in
the tree, or a URI a registered scheme provider answers for. Anywhere else, there's no underline
under the held modifier and no jump — a promise the workbench can't keep isn't offered.

## Search

Search isn't built in. Import `codelet/extensions/search` and pass it to `extensions` to add a
Search icon to the activity bar:

```ts
import { search } from "codelet/extensions/search";
import { Workbench, FileSystem } from "codelet/workbench";

const workbench = new Workbench({
  parent: document.getElementById("app")!,
  fs: new FileSystem({ "/README.md": "# Hello" }),
  extensions: [search],
});
```

It's a case-insensitive substring scan across every file's text and path, listed as a tree with
the matching lines under each file. Opening a match puts the file in the preview tab with the
match selected, and the same view is where a Find All References list lands.

Try it — the filter box searches file contents and paths as you type:

::codelet-playground{mode="workbench" extensions="search" view="search" height="420"}

```ts [greet.ts]
export const greet = (name: string) => `hi ${name}`;
```

```ts [index.ts]
import { greet } from "./greet";

console.log(greet("codelet"));
```

```md [README.md]
# greet

A greeting, and a second mention of greet in prose.
```

::

:read-more{to="/extensions/search"}

## Problems

Problems needs no extension — it's built in. Any diagnostic a registered language provider
publishes, such as a language server client, shows up grouped by file in the panel's Problems
view, with a squiggle under the code itself and an error/warning count in the status bar.

::codelet-playground{mode="workbench" extensions="lsp-typescript" height="420"}

```ts [index.ts]
interface User {
  name: string;
  age: number;
}

const user: User = { name: "Ada", age: "36" };
```

::

Open the panel and switch to the Problems tab to see the row; hovering the squiggle under `age`
in the editor shows the same message.

## Notifications and the status bar

`window.showInformationMessage`, `showWarningMessage` and `showErrorMessage` put a card in the
corner, oldest on top — or, raised with `{ modal: true }`, a dialog over the whole shell for a
question the reader has to answer before doing anything else. `window.withProgress` reports a
running task's progress in the status bar rather than a toast.

An extension's own status bar entry, from `window.createStatusBarItem`, sits in that same bar
alongside the built-in progress and diagnostics count.

:read-more{to="/api/ui"}