UI kit reference

zidane-ui/palette

import { … } from 'zidane-ui/palette'ui/src/palette/index.ts

Components#

`CommandPalette`Component#

Renders the command palette: sources, levels and running from controller, the surface from PalettePanel.

TypeScript

function CommandPalette(props: CommandPaletteProps): Element

Parameters

Parameters
Name	Type	Description
props	`CommandPaletteProps`	`CommandPaletteProps`.

Returns

Element

Props

CommandPalette props
Name	Type	Description
busy?	`boolean`	Turns the header spinner while the app's own search is out.
controller	`PaletteController`	The palette's state, from `usePaletteController`.
extraGroups?	`readonly PaletteSection<PaletteItem>[]`	Groups shown after the ranked ones, never reordering them. Keep the array stable.

ui/src/palette/CommandPalette.tsx:32

`PaletteDialog`Component#

Renders the palette surface in the modal slot usePaletteModalSlot opened. Esc and the backdrop tell the palette; the palette closing (Cmd+K again, an item ran) closes the slot.

TypeScript

function PaletteDialog(props: PaletteDialogProps): Element

Parameters

Parameters
Name	Type	Description
props	`PaletteDialogProps`	`PaletteDialogProps`.

Returns

Element

Props

PaletteDialog props
Name	Type	Description
archive?	`'all' \| 'active' \| 'archived'`	Which sessions `sessions` was loaded with.
className?	`string`	Classes merged on the surface's root.
context	`PaletteContext`	The snapshot handed to every source. Keep it stable while nothing in it changed.
onInsert?	`(text: string) => void`	Receives an `insert` result's text.
onPrompt?	`(text: string) => void`	Receives a `prompt` result's text.
rows?	`PaletteRows`	The app rows, from `createPaletteRows` (module scope). Absent: the surface's default rows.
sessions?	`readonly PaletteSession[]`	Every loaded session, for the matches inside conversations. Absent: no "In conversations" group.
style?	`CSSProperties`	Inline styles on the surface's root.

ui/src/palette/PaletteDialog.tsx:62

`PaletteProvider`Component#

Holds the palette's state (open, sources, recents) for the components below it.

TypeScript

function PaletteProvider(props: PaletteProviderProps): Element

Parameters

Parameters
Name	Type	Description
props	`PaletteProviderProps`	The `host`, optional `labels` and `createRankWorker`, and the `children`.

Returns

Element

Props

PaletteProvider props
Name	Type	Description
children	`ReactNode`	The app's components.
createRankWorker?	`() => Worker`	Starts a worker running `zidane-ui/palette/rank.worker`, so a big catalog (a project's files) is ranked off the main thread. Without one, every query ranks in place.
host?	`PaletteHost`	The data the built-in sources read and where recents persist. Read once, at mount.
labels?	Partial<{ paletteActionTitles: Record<string, string>; paletteAppearanceMode: Record<'dark' \| 'light' \| 'system', string>; paletteAppearanceModeHint: string; paletteAppearanceSettings: string; paletteCloseSidePanel: string; paletteCodeCompletion: string; paletteCommandGone: string; paletteCommandsGroup: string; paletteCompactTranscript: string; paletteCompactTranscriptHint: string; paletteConversationsGroup: string; paletteDiagnostics: Record<'off' \| 'lsp' \| 'tools', string>; paletteDiagnosticsHint: string; paletteEditFiles: string; paletteEditorGroup: string; paletteEditorSettings: string; paletteFileCount: (count: number) => string; paletteFilesGroup: string; paletteFilesPlaceholder: string; paletteFilesTitle: string; paletteFilesTreeSide: Record<'right' \| 'left', string>; paletteFilesTreeSideHint: string; paletteGoToFile: string; paletteHoverDocs: string; paletteImportRepo: string; paletteImportRepoHint: string; paletteMatchCount: (count: number) => string; paletteModelGroup: string; paletteNavigateGroup: string; paletteNeedsLsp: string; paletteNeedsSession: string; paletteOpenAndFind: string; paletteOpenFile: string; paletteOpenSidePanel: string; palettePanelAttention: (count: number, waiting: boolean) => string; palettePanelsGroup: string; palettePanelTitle: (label: string) => string; paletteReducedMotion: string; paletteSearchPlaceholder: string; paletteSessionActionsGroup: string; paletteSessionCurrent: string; paletteSessionsGroup: string; paletteSessionStatus: Record<'error' \| 'attention' \| 'running' \| 'pending', string>; paletteSettingsGroup: string; paletteShowLegacyModels: string; paletteShowLegacyModelsHint: string; paletteSidebarRunDetails: string; paletteSidebarRunDetailsHint: string; paletteSwitchToSession: string; paletteUnavailable: string; paletteUntitledSession: string; paletteViewGroup: string; paletteWordWrap: string }>	Overrides for the palette area's strings. Keys you leave out keep the default English label.

ui/src/palette/PaletteProvider.tsx:72

Functions#

`createPaletteRows`Function#

Builds the palette's app rows over what the app knows about its sessions. Call it once, at module scope: the hooks it is handed run inside the rows.

TypeScript

function createPaletteRows(options?: PaletteRowsOptions): PaletteRows

Parameters

Parameters
Name	Type	Default	Description
options?	`PaletteRowsOptions`	`{}`	`PaletteRowsOptions`.

Returns

PaletteRows

ui/src/palette/PaletteRows.tsx:117

`paletteVerbOf`Function#

What Enter does to a session, a conversation match or a file; the surface names the rest.

TypeScript

function paletteVerbOf(
  row: PaletteRowData<PaletteItem>,
  labels: { paletteActionTitles: Record<string, string>; paletteAppearanceMode: Record<'dark' | 'light' | 'system', string>; paletteAppearanceModeHint: string; paletteAppearanceSettings: string; paletteCloseSidePanel: string; paletteCodeCompletion: string; paletteCommandGone: string; paletteCommandsGroup: string; paletteCompactTranscript: string; paletteCompactTranscriptHint: string; paletteConversationsGroup: string; paletteDiagnostics: Record<'off' | 'lsp' | 'tools', string>; paletteDiagnosticsHint: string; paletteEditFiles: string; paletteEditorGroup: string; paletteEditorSettings: string; paletteFileCount: (count: number) => string; paletteFilesGroup: string; paletteFilesPlaceholder: string; paletteFilesTitle: string; paletteFilesTreeSide: Record<'right' | 'left', string>; paletteFilesTreeSideHint: string; paletteGoToFile: string; paletteHoverDocs: string; paletteImportRepo: string; paletteImportRepoHint: string; paletteMatchCount: (count: number) => string; paletteModelGroup: string; paletteNavigateGroup: string; paletteNeedsLsp: string; paletteNeedsSession: string; paletteOpenAndFind: string; paletteOpenFile: string; paletteOpenSidePanel: string; palettePanelAttention: (count: number, waiting: boolean) => string; palettePanelsGroup: string; palettePanelTitle: (label: string) => string; paletteReducedMotion: string; paletteSearchPlaceholder: string; paletteSessionActionsGroup: string; paletteSessionCurrent: string; paletteSessionsGroup: string; paletteSessionStatus: Record<'error' | 'attention' | 'running' | 'pending', string>; paletteSettingsGroup: string; paletteShowLegacyModels: string; paletteShowLegacyModelsHint: string; paletteSidebarRunDetails: string; paletteSidebarRunDetailsHint: string; paletteSwitchToSession: string; paletteUnavailable: string; paletteUntitledSession: string; paletteViewGroup: string; paletteWordWrap: string },
): string | undefined

Parameters

Parameters
Name	Type	Description
row	`PaletteRowData<PaletteItem>`	The row under the cursor.
labels	{ paletteActionTitles: Record<string, string>; paletteAppearanceMode: Record<'dark' \| 'light' \| 'system', string>; paletteAppearanceModeHint: string; paletteAppearanceSettings: string; paletteCloseSidePanel: string; paletteCodeCompletion: string; paletteCommandGone: string; paletteCommandsGroup: string; paletteCompactTranscript: string; paletteCompactTranscriptHint: string; paletteConversationsGroup: string; paletteDiagnostics: Record<'off' \| 'lsp' \| 'tools', string>; paletteDiagnosticsHint: string; paletteEditFiles: string; paletteEditorGroup: string; paletteEditorSettings: string; paletteFileCount: (count: number) => string; paletteFilesGroup: string; paletteFilesPlaceholder: string; paletteFilesTitle: string; paletteFilesTreeSide: Record<'right' \| 'left', string>; paletteFilesTreeSideHint: string; paletteGoToFile: string; paletteHoverDocs: string; paletteImportRepo: string; paletteImportRepoHint: string; paletteMatchCount: (count: number) => string; paletteModelGroup: string; paletteNavigateGroup: string; paletteNeedsLsp: string; paletteNeedsSession: string; paletteOpenAndFind: string; paletteOpenFile: string; paletteOpenSidePanel: string; palettePanelAttention: (count: number, waiting: boolean) => string; palettePanelsGroup: string; palettePanelTitle: (label: string) => string; paletteReducedMotion: string; paletteSearchPlaceholder: string; paletteSessionActionsGroup: string; paletteSessionCurrent: string; paletteSessionsGroup: string; paletteSessionStatus: Record<'error' \| 'attention' \| 'running' \| 'pending', string>; paletteSettingsGroup: string; paletteShowLegacyModels: string; paletteShowLegacyModelsHint: string; paletteSidebarRunDetails: string; paletteSidebarRunDetailsHint: string; paletteSwitchToSession: string; paletteUnavailable: string; paletteUntitledSession: string; paletteViewGroup: string; paletteWordWrap: string }	The palette labels.

Returns

string | undefined

ui/src/palette/PaletteRows.tsx:84

`useActionsPaletteSource`Function#

Registers the key command registry's actions as a palette source. Registers again only when the set of bound actions changes: the rows run the handlers in effect when picked.

TypeScript

function useActionsPaletteSource(): void

ui/src/palette/app-sources.ts:27

`useConversationHit`Function#

The content hit behind a palette row, if it is one.

TypeScript

function useConversationHit(itemId: string): PaletteConversationHit | undefined

Parameters

Parameters
Name	Type	Description
itemId	`string`	The row's item id.

Returns

PaletteConversationHit | undefined

ui/src/palette/useConversationSearch.ts:113

`useConversationSearch`Function#

Searches inside conversations as the query settles. Nothing (and no request) when the host leaves searchConversations out.

TypeScript

function useConversationSearch(
  query: string,
  options: ConversationSearchOptions,
): ConversationSearch

Parameters

Parameters
Name	Type	Description
query	`string`	The palette's query as typed.
options	`ConversationSearchOptions`	`ConversationSearchOptions`.

Returns

ConversationSearch

ui/src/palette/useConversationSearch.ts:53

`usePalette`Function#

The palette's state and actions. Re-renders on every state change. Throws outside a PaletteProvider.

TypeScript

function usePalette(): PaletteApi

Returns

PaletteApi

ui/src/palette/PaletteProvider.tsx:101

`usePaletteActions`Function#

The palette's stable actions. Never re-renders its caller. Throws outside a PaletteProvider.

TypeScript

function usePaletteActions(): PaletteActions

Returns

PaletteActions

ui/src/palette/PaletteProvider.tsx:108

`usePaletteController`Function#

The command palette's state: gather, rank, levels and running. Call it inside a PaletteProvider.

TypeScript

function usePaletteController(options: PaletteControllerOptions): PaletteController

Parameters

Parameters
Name	Type	Description
options	`PaletteControllerOptions`	The context and where agent-bound results go.

Returns

PaletteController

ui/src/palette/usePaletteController.ts:115

`usePaletteHost`Function#

The PaletteHost given to the nearest PaletteProvider, if any.

TypeScript

function usePaletteHost(): PaletteHost | undefined

Returns

PaletteHost | undefined

ui/src/palette/PaletteProvider.tsx:115

`usePaletteLabels`Function#

The palette area's strings, with the provider's overrides.

TypeScript

function usePaletteLabels(): { paletteActionTitles: Record<string, string>; paletteAppearanceMode: Record<'dark' | 'light' | 'system', string>; paletteAppearanceModeHint: string; paletteAppearanceSettings: string; paletteCloseSidePanel: string; paletteCodeCompletion: string; paletteCommandGone: string; paletteCommandsGroup: string; paletteCompactTranscript: string; paletteCompactTranscriptHint: string; paletteConversationsGroup: string; paletteDiagnostics: Record<'off' | 'lsp' | 'tools', string>; paletteDiagnosticsHint: string; paletteEditFiles: string; paletteEditorGroup: string; paletteEditorSettings: string; paletteFileCount: (count: number) => string; paletteFilesGroup: string; paletteFilesPlaceholder: string; paletteFilesTitle: string; paletteFilesTreeSide: Record<'right' | 'left', string>; paletteFilesTreeSideHint: string; paletteGoToFile: string; paletteHoverDocs: string; paletteImportRepo: string; paletteImportRepoHint: string; paletteMatchCount: (count: number) => string; paletteModelGroup: string; paletteNavigateGroup: string; paletteNeedsLsp: string; paletteNeedsSession: string; paletteOpenAndFind: string; paletteOpenFile: string; paletteOpenSidePanel: string; palettePanelAttention: (count: number, waiting: boolean) => string; palettePanelsGroup: string; palettePanelTitle: (label: string) => string; paletteReducedMotion: string; paletteSearchPlaceholder: string; paletteSessionActionsGroup: string; paletteSessionCurrent: string; paletteSessionsGroup: string; paletteSessionStatus: Record<'error' | 'attention' | 'running' | 'pending', string>; paletteSettingsGroup: string; paletteShowLegacyModels: string; paletteShowLegacyModelsHint: string; paletteSidebarRunDetails: string; paletteSidebarRunDetailsHint: string; paletteSwitchToSession: string; paletteUnavailable: string; paletteUntitledSession: string; paletteViewGroup: string; paletteWordWrap: string }

Returns

{ paletteActionTitles: Record<string, string>; paletteAppearanceMode: Record<'dark' | 'light' | 'system', string>; paletteAppearanceModeHint: string; paletteAppearanceSettings: string; paletteCloseSidePanel: string; paletteCodeCompletion: string; paletteCommandGone: string; paletteCommandsGroup: string; paletteCompactTranscript: string; paletteCompactTranscriptHint: string; paletteConversationsGroup: string; paletteDiagnostics: Record<'off' | 'lsp' | 'tools', string>; paletteDiagnosticsHint: string; paletteEditFiles: string; paletteEditorGroup: string; paletteEditorSettings: string; paletteFileCount: (count: number) => string; paletteFilesGroup: string; paletteFilesPlaceholder: string; paletteFilesTitle: string; paletteFilesTreeSide: Record<'right' | 'left', string>; paletteFilesTreeSideHint: string; paletteGoToFile: string; paletteHoverDocs: string; paletteImportRepo: string; paletteImportRepoHint: string; paletteMatchCount: (count: number) => string; paletteModelGroup: string; paletteNavigateGroup: string; paletteNeedsLsp: string; paletteNeedsSession: string; paletteOpenAndFind: string; paletteOpenFile: string; paletteOpenSidePanel: string; palettePanelAttention: (count: number, waiting: boolean) => string; palettePanelsGroup: string; palettePanelTitle: (label: string) => string; paletteReducedMotion: string; paletteSearchPlaceholder: string; paletteSessionActionsGroup: string; paletteSessionCurrent: string; paletteSessionsGroup: string; paletteSessionStatus: Record<'error' | 'attention' | 'running' | 'pending', string>; paletteSettingsGroup: string; paletteShowLegacyModels: string; paletteShowLegacyModelsHint: string; paletteSidebarRunDetails: string; paletteSidebarRunDetailsHint: string; paletteSwitchToSession: string; paletteUnavailable: string; paletteUntitledSession: string; paletteViewGroup: string; paletteWordWrap: string }

ui/src/palette/PaletteProvider.tsx:120

`usePaletteModalSlot`Function#

Opens the palette surface in the modal slot while the palette is open, and closes the palette when another modal takes the slot. Mount it once, under ModalProvider and PaletteProvider.

TypeScript

function usePaletteModalSlot(options: PaletteModalSlotOptions): void

Parameters

Parameters
Name	Type	Description
options	`PaletteModalSlotOptions`	`PaletteModalSlotOptions`.

ui/src/palette/PaletteDialog.tsx:159

`usePaletteSource`Function#

Registers a source for the component's lifetime. source is read through a ref, so callers can pass a fresh object every render without churning the registry; it registers again only when its id changes. null registers nothing.

TypeScript

function usePaletteSource(source: PaletteProvider | null): void

Parameters

Parameters
Name	Type	Description
source	`PaletteProvider \| null`	The source, or `null`.

ui/src/palette/PaletteProvider.tsx:132

`useRankedItems`Function#

Ranks items for query, off the main thread for a big catalog when the provider has a rank worker.

TypeScript

function useRankedItems(
  items: readonly PaletteItem[],
  query: string,
  recents: readonly string[],
): RankedItems

Parameters

Parameters
Name	Type	Description
items	`readonly PaletteItem[]`	The catalog.
query	`string`	The query.
recents	`readonly string[]`	Recently run ids, for the empty-query order.

Returns

RankedItems

ui/src/palette/useRankedItems.ts:67

`useSessionRank`Function#

A session's palette rank: 0 when it needs the user (attention, a pending approval or question), 1 while it runs, else 2.

TypeScript

function useSessionRank(
  peekRunning: (sessionId: string) => boolean,
): (sessionId: string) => SessionRank

Parameters

Parameters
Name	Type	Description
peekRunning	`(sessionId: string) => boolean`	Whether the app sees the session running now (read when ranking, not subscribed).

Returns

(sessionId: string) => SessionRank

ui/src/palette/app-sources.ts:48

Constants#

`CONVERSATION_SEARCH_MIN_CHARS`Constant#

Shorter queries match nearly every conversation: not worth a scan.

TypeScript

const CONVERSATION_SEARCH_MIN_CHARS = 2

ui/src/palette/useConversationSearch.ts:20

`ConversationHitsContext`Constant#

The hits of the rows on show, for the rows that render them.

TypeScript

const ConversationHitsContext: Context<ReadonlyMap<string, PaletteConversationHit>>

ui/src/palette/useConversationSearch.ts:106

`PALETTE_MODAL_ID`Constant#

The palette's modal-slot id (modal.open({ id })), shared by the slot bridge and the surface.

TypeScript

const PALETTE_MODAL_ID = 'palette'

ui/src/palette/PaletteDialog.tsx:32

Interfaces#

`ConversationSearch`Interface#

What useConversationSearch returns.

TypeScript

interface ConversationSearch

Properties

ConversationSearch properties
Name	Type	Description
hits	`ReadonlyMap<string, PaletteConversationHit>`	Each row's hit, by item id (match count, age).
rows	`readonly RankedPaletteItem[]`	The "In conversations" rows, in the host's order.
searching	`boolean`	A scan for the current query is on its way.

ui/src/palette/useConversationSearch.ts:23

`ConversationSearchOptions`Interface#

Options of useConversationSearch.

TypeScript

interface ConversationSearchOptions

Properties

ConversationSearchOptions properties
Name	Type	Description
archive?	`'all' \| 'active' \| 'archived'`	Which sessions `sessions` was loaded with.
enabled	`boolean`	False in a nested picker: content search is a root-level thing.
listed	`ReadonlySet<string>`	Session ids the ranked rows already show.
sessions	`readonly PaletteSession[]`	Every loaded session.

ui/src/palette/useConversationSearch.ts:35

`PaletteActions`Interface#

What never changes: callers that only open the palette or register a source never re-render with it.

TypeScript

interface PaletteActions

Properties

PaletteActions properties
Name	Type	Description
close	`() => void`	Closes the palette.
open	`() => void`	Opens the palette.
registerSource	`(source: PaletteProvider) => () => void`	Registers a source for as long as the caller wants it; returns the unregister.
toggle	`() => void`	Opens a closed palette, closes an open one (the Cmd+K entry point).

ui/src/palette/PaletteProvider.tsx:31

`PaletteApi`Interface#

The palette's state and actions, from usePalette.

TypeScript

interface PaletteApi extends PaletteActions, PaletteState

Properties

PaletteApi properties
Name	Type	Description
closefrom `PaletteActions`	`() => void`	Closes the palette.
isOpenfrom `PaletteState`	`boolean`	Whether the palette is open.
markRecent	`(id: string) => void`	Puts an item id first in the recents.
openfrom `PaletteActions`	`() => void`	Opens the palette.
recentsfrom `PaletteState`	`readonly string[]`	Recently run item ids, most recent first.
registerSourcefrom `PaletteActions`	`(source: PaletteProvider) => () => void`	Registers a source for as long as the caller wants it; returns the unregister.
sourcesfrom `PaletteState`	`readonly PaletteProvider[]`	Every registered source, in registration order.
togglefrom `PaletteActions`	`() => void`	Opens a closed palette, closes an open one (the Cmd+K entry point).
versionfrom `PaletteState`	`number`	Bumps whenever an open palette's source signalled a change through `subscribe`.

ui/src/palette/PaletteProvider.tsx:43

`PaletteContext`Interface#

JSON-safe snapshot of the host handed to providers. Never holds functions.

TypeScript

interface PaletteContext

Properties

PaletteContext properties
Name	Type	Description
busy?	`boolean`	A run is in flight on the active session.
cwd?	`string`	Working directory of the active session.
host	`PaletteHost`	Which app is asking.
sessionId?	`string`	Id of the active session.

dist/index-Bq87OcGy.d.ts:28132

`PaletteController`Interface#

The palette's state and handlers, for CommandPalette.

TypeScript

interface PaletteController

Properties

PaletteController properties
Name	Type	Description
back	`() => void`	Leaves the nested level. Stable.
clearScope	`() => void`	Searches every section again. Stable.
close	`() => void`	Closes the palette.
cursor	`number`	The highlighted row's index.
cycleScope	`() => void`	Scopes the root search to the next section; after the last, back to every section. Stable while `scopes` holds.
inputRef	`RefObject<HTMLInputElement \| null>`	The query field (focused again when a level opens).
loading	`boolean`	The root items have not landed yet.
nested	`boolean`	Whether a picker's level is shown.
notice	`PaletteNotice \| null`	The notice line (a `notify` result or a failed run).
placeholder	`string \| undefined`	The query field's placeholder.
query	`string`	The query typed.
ranked	`readonly RankedPaletteItem[]`	The ranked rows of the current level.
run	`(row: PaletteRowData<PaletteItem>) => void`	Runs a row. Stable.
running	`boolean`	A row is running.
scope	`string \| null`	The section the root search is scoped to; `null` searches every section.
scopes	`readonly string[]`	The sections a scope can be: the root items' groups in order, then `extraScopes`.
sections	`readonly PaletteGroup[]`	`ranked` grouped into sections.
setCursor	`(index: number) => void`	Moves the highlight.
setQuery	`(query: string) => void`	Sets the query.
settled	`boolean`	The rows are for the query typed.
title	`string \| undefined`	The nested level's title.

ui/src/palette/usePaletteController.ts:65

`PaletteControllerOptions`Interface#

Options of usePaletteController.

TypeScript

interface PaletteControllerOptions

Properties

PaletteControllerOptions properties
Name	Type	Description
context	`PaletteContext`	The snapshot handed to every source. Keep it stable while nothing in it changed.
extraScopes?	`readonly string[]`	Sections the app lists itself (its own groups), offered as scopes after the root items' groups. Keep it stable.
onInsert?	`(text: string) => void`	Receives an `insert` result's text (the palette closes first).
onPrompt?	`(text: string) => void`	Receives a `prompt` result's text (the palette closes first).
recentIdOf?	`(item: PaletteItem) => string`	The id Recent remembers for a run root item. Default: the item's own id.

ui/src/palette/usePaletteController.ts:51

`PaletteDialogProps`Interface#

Props for PaletteDialog.

TypeScript

interface PaletteDialogProps

Properties

PaletteDialogProps properties
Name	Type	Description
archive?	`'all' \| 'active' \| 'archived'`	Which sessions `sessions` was loaded with.
className?	`string`	Classes merged on the surface's root.
context	`PaletteContext`	The snapshot handed to every source. Keep it stable while nothing in it changed.
onInsert?	`(text: string) => void`	Receives an `insert` result's text.
onPrompt?	`(text: string) => void`	Receives a `prompt` result's text.
rows?	`PaletteRows`	The app rows, from `createPaletteRows` (module scope). Absent: the surface's default rows.
sessions?	`readonly PaletteSession[]`	Every loaded session, for the matches inside conversations. Absent: no "In conversations" group.
style?	`CSSProperties`	Inline styles on the surface's root.

ui/src/palette/PaletteDialog.tsx:37

`PaletteItem`Interface#

An entry in the command palette.

TypeScript

interface PaletteItem

Properties

PaletteItem properties
Name	Type	Description
checked?	`boolean`	For `toggle` items.
description?	`string`	Secondary text shown beside the title.
disabled?	`string`	Reason the item cannot run right now; it stays listed, muted.
group	`string`	Section header. Hosts order groups by first appearance after `Recent`.
icon?	`PanelIcon`	Icon for each renderer.
id	`string`	Stable, unique across providers: `builtin:openSettings`, `slash:compact`, `<extension>/<id>`.
keybinding?	`string`	Resolved chord spec (`ctrl+shift+k`); the host formats it for display.
keywords?	`readonly string[]`	Extra search terms not shown in the row.
kind?	`PaletteItemKind`	How the item behaves. Treated as `action` when omitted.
searchOnly?	`boolean`	Only appears once the query matches it: bulk catalogs (every file in the project) stay out of the empty-query listing but are one keystroke away.
source	`string`	Provider that owns `run` for this item. Stamped by the aggregator.
title	`string`	Text shown in the row.

dist/index-Bq87OcGy.d.ts:28101

`PaletteModalSlotOptions`Interface#

Options of usePaletteModalSlot.

TypeScript

interface PaletteModalSlotOptions

Properties

PaletteModalSlotOptions properties
Name	Type	Description
context	`PaletteContext`	The snapshot the surface opens with (reopening picks up a new one).
cwd?	`string`	The project folder: the extension providers' live updates stay on for it while open.
render	`(context: PaletteContext) => ReactNode`	The surface, usually a `PaletteDialog`.

ui/src/palette/PaletteDialog.tsx:144

`PaletteProviderProps`Interface#

Props for PaletteProvider.

TypeScript

interface PaletteProviderProps

Properties

PaletteProviderProps properties
Name	Type	Description
children	`ReactNode`	The app's components.
createRankWorker?	`() => Worker`	Starts a worker running `zidane-ui/palette/rank.worker`, so a big catalog (a project's files) is ranked off the main thread. Without one, every query ranks in place.
host?	`PaletteHost`	The data the built-in sources read and where recents persist. Read once, at mount.
labels?	Partial<{ paletteActionTitles: Record<string, string>; paletteAppearanceMode: Record<'dark' \| 'light' \| 'system', string>; paletteAppearanceModeHint: string; paletteAppearanceSettings: string; paletteCloseSidePanel: string; paletteCodeCompletion: string; paletteCommandGone: string; paletteCommandsGroup: string; paletteCompactTranscript: string; paletteCompactTranscriptHint: string; paletteConversationsGroup: string; paletteDiagnostics: Record<'off' \| 'lsp' \| 'tools', string>; paletteDiagnosticsHint: string; paletteEditFiles: string; paletteEditorGroup: string; paletteEditorSettings: string; paletteFileCount: (count: number) => string; paletteFilesGroup: string; paletteFilesPlaceholder: string; paletteFilesTitle: string; paletteFilesTreeSide: Record<'right' \| 'left', string>; paletteFilesTreeSideHint: string; paletteGoToFile: string; paletteHoverDocs: string; paletteImportRepo: string; paletteImportRepoHint: string; paletteMatchCount: (count: number) => string; paletteModelGroup: string; paletteNavigateGroup: string; paletteNeedsLsp: string; paletteNeedsSession: string; paletteOpenAndFind: string; paletteOpenFile: string; paletteOpenSidePanel: string; palettePanelAttention: (count: number, waiting: boolean) => string; palettePanelsGroup: string; palettePanelTitle: (label: string) => string; paletteReducedMotion: string; paletteSearchPlaceholder: string; paletteSessionActionsGroup: string; paletteSessionCurrent: string; paletteSessionsGroup: string; paletteSessionStatus: Record<'error' \| 'attention' \| 'running' \| 'pending', string>; paletteSettingsGroup: string; paletteShowLegacyModels: string; paletteShowLegacyModelsHint: string; paletteSidebarRunDetails: string; paletteSidebarRunDetailsHint: string; paletteSwitchToSession: string; paletteUnavailable: string; paletteUntitledSession: string; paletteViewGroup: string; paletteWordWrap: string }>	Overrides for the palette area's strings. Keys you leave out keep the default English label.

ui/src/palette/PaletteProvider.tsx:52

`PaletteRows`Interface#

The renderers createPaletteRows returns, for CommandPalette.

TypeScript

interface PaletteRows

Properties

PaletteRows properties
Name	Type	Description
renderIcon	`(row: PaletteRowData<PaletteItem>) => ReactNode`	A file's type badge, else the item's own glyph.
renderKeys	`PaletteKeys`	Keycaps for binding specs that may list alternatives (`ctrl+w \| cmd+w`).
renderRow	`(props: PaletteRowProps<PaletteItem>) => ReactNode`	A session or a conversation match; any other row is the surface's (`undefined`).

ui/src/palette/PaletteRows.tsx:57

`PaletteRowsOptions`Interface#

What the rows read from the app. Every member is optional.

TypeScript

interface PaletteRowsOptions

Properties

PaletteRowsOptions properties
Name	Type	Description
highlight?	`(excerpt: string, query: string) => { ranges: readonly PaletteTextRange[]; text: string }`	Cuts a conversation excerpt around its first match and marks the query's terms in it. Absent: plain excerpt.
StatusDot?	`ComponentType<{ sessionId: string }>`	A session's live status dot, in the row's icon slot.
useSession?	`(sessionId: string) => { current: boolean; updatedAt: number } \| undefined`	A loaded session's last update and whether it is the one on show (a hook, called once per session row).
useSessionStatus?	`(sessionId: string) => string \| undefined`	A session's live status (a hook, called once per session row).

ui/src/palette/PaletteRows.tsx:45

`PaletteSource`Interface#

Source of palette items and the handler that runs them.

TypeScript

interface PaletteSource

Properties

PaletteSource properties
Name	Type	Description
id	`string`	Provider id, stamped on its items as `source`.
items	`(ctx: PaletteContext) => readonly PaletteItem[] \| Promise<readonly PaletteItem[]>`	Items for the current context. Called on open, on `subscribe` emits, and on explicit refresh.
run	`(itemId: string, ctx: PaletteContext) => PaletteRunResult \| Promise<PaletteRunResult>`	Runs the item with the given id. May return a follow-up result.
subscribe?	`(emit: () => void) => () => void`	Live updates while the palette is open, same contract as panels.

dist/index-Bq87OcGy.d.ts:28165

`RankedItems`Interface#

What useRankedItems returns.

TypeScript

interface RankedItems

Properties

RankedItems properties
Name	Type	Description
rows	`readonly RankedPaletteItem[]`	The rows to show.
settled	`boolean`	The rows are for this query (Enter waits for that).

ui/src/palette/useRankedItems.ts:53

Types#

`CommandPaletteProps`Type#

Props for CommandPalette.

TypeScript

type CommandPaletteProps = Pick<PalettePanelProps<PaletteItem>, 'verb' | 'renderRow' | 'renderIcon' | 'renderKeys' | 'className' | 'style'> & { busy?: boolean; controller: PaletteController; extraGroups?: readonly PaletteSection<PaletteItem>[] }

ui/src/palette/CommandPalette.tsx:15

`PaletteRunResult`Type#

What a provider's run may hand back. items opens a nested picker (branches, environments); the host keeps a stack so Backspace on an empty query goes back one level. prompt sends text to the chat, insert puts it in the composer (a / command that takes arguments).

TypeScript

type PaletteRunResult =
  | void
  | undefined
  | { items: readonly PaletteItem[]; kind: 'items'; placeholder?: string; title?: string }
  | { kind: 'prompt'; text: string }
  | { kind: 'insert'; text: string }
  | { kind: 'notify'; text: string; tone?: 'info' | 'warn' | 'error' }

dist/index-Bq87OcGy.d.ts:28148

`PaletteSessionStatus`Type#

A session's status as its palette row words it; quiet states say nothing.

TypeScript

type PaletteSessionStatus = 'running' | 'pending' | 'attention' | 'error'

ui/src/palette/PaletteRows.tsx:42

`PaletteTextRange`Type#

A half-open [start, end) range of a text.

TypeScript

type PaletteTextRange = readonly [start: number, end: number]

ui/src/palette/PaletteRows.tsx:39

Components#

CommandPaletteComponent#

Parameters

Returns

Props

PaletteDialogComponent#

Parameters

Returns

Props

PaletteProviderComponent#

Parameters

Returns

Props

Functions#

createPaletteRowsFunction#

Parameters

Returns

paletteVerbOfFunction#

Parameters

Returns

useActionsPaletteSourceFunction#

useConversationHitFunction#

Parameters

Returns

useConversationSearchFunction#

Parameters

Returns

usePaletteFunction#

Returns

usePaletteActionsFunction#

Returns

usePaletteControllerFunction#

Parameters

Returns

usePaletteHostFunction#

Returns

usePaletteLabelsFunction#

Returns

usePaletteModalSlotFunction#

Parameters

usePaletteSourceFunction#

Parameters

useRankedItemsFunction#

Parameters

Returns

useSessionRankFunction#

Parameters

Returns

Constants#

CONVERSATION_SEARCH_MIN_CHARSConstant#

ConversationHitsContextConstant#

PALETTE_MODAL_IDConstant#

Interfaces#

ConversationSearchInterface#

Properties

ConversationSearchOptionsInterface#

Properties

PaletteActionsInterface#

Properties

PaletteApiInterface#

Properties

PaletteContextInterface#

Properties

PaletteControllerInterface#

Properties

PaletteControllerOptionsInterface#

Properties

PaletteDialogPropsInterface#

Properties

PaletteItemInterface#

Properties

PaletteModalSlotOptionsInterface#

Properties

PaletteProviderPropsInterface#

Properties

PaletteRowsInterface#

Properties

PaletteRowsOptionsInterface#

Properties

PaletteSourceInterface#

`CommandPalette`Component#

`PaletteDialog`Component#

`PaletteProvider`Component#

`createPaletteRows`Function#

`paletteVerbOf`Function#

`useActionsPaletteSource`Function#

`useConversationHit`Function#

`useConversationSearch`Function#

`usePalette`Function#

`usePaletteActions`Function#

`usePaletteController`Function#

`usePaletteHost`Function#

`usePaletteLabels`Function#

`usePaletteModalSlot`Function#

`usePaletteSource`Function#

`useRankedItems`Function#

`useSessionRank`Function#

`CONVERSATION_SEARCH_MIN_CHARS`Constant#

`ConversationHitsContext`Constant#

`PALETTE_MODAL_ID`Constant#

`ConversationSearch`Interface#

`ConversationSearchOptions`Interface#

`PaletteActions`Interface#

`PaletteApi`Interface#

`PaletteContext`Interface#

`PaletteController`Interface#

`PaletteControllerOptions`Interface#

`PaletteDialogProps`Interface#

`PaletteItem`Interface#

`PaletteModalSlotOptions`Interface#

`PaletteProviderProps`Interface#

`PaletteRows`Interface#

`PaletteRowsOptions`Interface#

`PaletteSource`Interface#

`RankedItems`Interface#

`CommandPaletteProps`Type#

`PaletteRunResult`Type#

`PaletteSessionStatus`Type#

`PaletteTextRange`Type#