# components/palette/PaletteList (zidane-ui)

Import: `import { … } from 'zidane-ui'`. Source: [ui/src/components/palette/PaletteList.tsx](https://github.com/Tahul/zidane/blob/main/ui/src/components/palette/PaletteList.tsx).

## Components

### `MatchedTitle`

Component.

A title with its match. The match is shown when it reads as the words
typed (one run per word): those runs in full weight and color, the rest
of the title quieter. Letters picked across the title are not shown.

```ts
function MatchedTitle(props: MatchedTitleProps): Element
```

**Parameters**

- `props` (`MatchedTitleProps`): Component props.

**Returns** `Element`

**Props**

- `indices` (`readonly number[]`): Indices of the matched characters in `text`.
- `terms` (`number`): Number of words in the query. The match shows only when it forms at most that many runs.
- `text` (`string`): The title to show.

Source: [ui/src/components/palette/PaletteList.tsx:290](https://github.com/Tahul/zidane/blob/main/ui/src/components/palette/PaletteList.tsx#L290)

### `PaletteIcon`

Component.

The item's glyph in the icon slot, quiet until its row is marked.

```ts
function PaletteIcon(props: PaletteIconProps): Element
```

**Parameters**

- `props` (`PaletteIconProps`): Component props.

**Returns** `Element`

**Props**

- `className?` (`string`): Extra classes on the root element.
- `icon?` (`string`): Icon class. A small dot shows when omitted.
- `style?` (`CSSProperties`): Inline styles on the root element, merged after the component's own.

Source: [ui/src/components/palette/PaletteList.tsx:388](https://github.com/Tahul/zidane/blob/main/ui/src/components/palette/PaletteList.tsx#L388)

### `PaletteList`

Component.

Renders the palette's results: titled sections of rows in a `listbox`, windowed so only the
rows in view are mounted. A block under the rows glides to the marked row.

```ts
function PaletteList<T extends PaletteEntry>(props: PaletteListProps<T>): Element
```

**Type parameters**

- `T` (`extends PaletteEntry`)

**Parameters**

- `props` (`PaletteListProps<T>`): Component props.

**Returns** `Element`

**Props**

- `className?` (`string`): Extra classes on the root element.
- `cursor` (`number`): Flat index of the marked row, across sections. The list scrolls to keep it in view.
- `groups` (`readonly PaletteSection<T>[]`): The ranked sections to show.
- `nested` (`boolean`): A picker's level: its `toggle` rows are choices (a check), not settings (a switch).
- `onHover` (`(index: number) => void`): Called with a row's flat index when the pointer moves over it.
- `onRun` (`(row: PaletteRowData<T>) => void`): Called with the row when it is clicked.
- `query` (`string`): The current query. Its word count decides whether a title match is shown.
- `renderIcon?` (`(row: PaletteRowData<T>) => ReactNode`): The default row's icon; else a dot.
- `renderKeys?` (`PaletteKeys`, default `defaultPaletteKeys`): Draws a keybinding spec as keycaps.
- `renderRow?` (`(props: PaletteRowProps<T>) => ReactNode`): Draws a row; return `undefined` for the default row. Keep it stable (rows are memoized on their props).
- `style?` (`CSSProperties`): Inline styles on the root element, merged after the component's own.

Source: [ui/src/components/palette/PaletteList.tsx:132](https://github.com/Tahul/zidane/blob/main/ui/src/components/palette/PaletteList.tsx#L132)

### `PaletteOption`

Component.

One palette option: a menu row with listbox semantics (focus stays in the query input).

```ts
function PaletteOption<T extends PaletteEntry>(props: PaletteOptionProps<T>): Element
```

**Type parameters**

- `T` (`extends PaletteEntry`)

**Parameters**

- `props` (`PaletteOptionProps<T>`): The row's [`PaletteRowProps`](https://zidane.si/docs/reference/ui-components-palette-palette-list.md#PaletteRowProps) plus the `icon`, `title`, `description`,
  `trailing`, `toggle` and `checked` props of a [`MenuRow`](https://zidane.si/docs/reference/ui-components-menu.md#MenuRow).

**Returns** `Element`

**Props**

- `active` (`boolean`, from `PaletteRowProps`): Whether the cursor is on this row.
- `checked?` (`boolean`, from `Pick`): The current choice: a check in the trailing slot.
- `choice` (`boolean`, from `PaletteRowProps`): In a picker: a checked row is the current choice.
- `className?` (`string`): Extra classes on the root element.
- `description?` (`ReactNode`, from `Pick`): Secondary text after the title. Inline it truncates to one line; `size="lg"` stacks it under
  the title, clamped to two lines.
- `icon?` (`ReactNode`, from `Pick`): Leading glyph, drawn muted. Use it only when it means something (a kind, a folder). No icon
  slot renders when omitted.
- `index` (`number`, from `PaletteRowProps`): Position of the row in the whole list, across sections.
- `onHover` (`(index: number) => void`, from `PaletteRowProps`): Called with the row's `index` when the pointer moves over it.
- `onRun` (`(row: PaletteRowData<T>) => void`, from `PaletteRowProps`): Called with the row when it is clicked.
- `row` (`PaletteRowData<T>`, from `PaletteRowProps`): The row's item and title matches.
- `style?` (`CSSProperties`): Inline styles on the root element, merged after the component's own.
- `terms` (`number`, from `PaletteRowProps`): Words in the query: a title match is shown when each reads as one run.
- `title` (`ReactNode`, from `Pick`): The row's label.
- `toggle?` (`boolean`, from `Pick`): An on/off option: a switch in the trailing slot (use with `role="menuitemcheckbox"`).
- `top` (`number`, from `PaletteRowProps`): Offset inside its section.
- `trailing?` (`ReactNode`, from `Pick`): Content at the row's end, such as a keycap or a meta value. A check or switch from `checked` or
  `toggle` follows it.

Source: [ui/src/components/palette/PaletteList.tsx:334](https://github.com/Tahul/zidane/blob/main/ui/src/components/palette/PaletteList.tsx#L334)

### `PaletteRow`

Component.

The default row: icon, matched title, detail when marked, then a switch, a check, a caret or the shortcut.

```ts
const PaletteRow: MemoExoticComponent<(props: PaletteRowProps<PaletteEntry> & Pick<PaletteOptionProps<PaletteEntry>, 'className' | 'style'> & { renderIcon?: (row: PaletteRowData) => ReactNode; renderKeys?: PaletteKeys }) => Element>
```

Source: [ui/src/components/palette/PaletteList.tsx:399](https://github.com/Tahul/zidane/blob/main/ui/src/components/palette/PaletteList.tsx#L399)

## Constants

### `defaultPaletteKeys`

Constant.

The default [`PaletteKeys`](https://zidane.si/docs/reference/ui-components-palette-palette-list.md#PaletteKeys): a small [`KeyCombo`](https://zidane.si/docs/reference/ui-components-keycap.md#KeyCombo) for the binding spec.

```ts
const defaultPaletteKeys: PaletteKeys
```

Source: [ui/src/components/palette/PaletteList.tsx:95](https://github.com/Tahul/zidane/blob/main/ui/src/components/palette/PaletteList.tsx#L95)

## Interfaces

### `MatchedTitleProps`

Interface.

Props for [`MatchedTitle`](https://zidane.si/docs/reference/ui-components-palette-palette-list.md#MatchedTitle).

```ts
interface MatchedTitleProps
```

**Properties**

- `indices` (`readonly number[]`): Indices of the matched characters in `text`.
- `terms` (`number`): Number of words in the query. The match shows only when it forms at most that many runs.
- `text` (`string`): The title to show.

Source: [ui/src/components/palette/PaletteList.tsx:274](https://github.com/Tahul/zidane/blob/main/ui/src/components/palette/PaletteList.tsx#L274)

### `PaletteEntry`

Interface.

What a palette row shows. Structural, so an app's own item type fits as is.

```ts
interface PaletteEntry
```

**Properties**

- `checked?` (`boolean`): Current state of a `toggle` item: on, or the current choice in a picker.
- `description?` (`string`): Detail text. It shows while the row is marked, or when the query matched only the description.
- `disabled?` (`string`): Why the row can't run; the row reads as disabled and shows it as a tooltip.
- `id` (`string`): Stable identifier of the item.
- `keybinding?` (`string`): Shown on the marked row, as keycaps.
- `kind?` (`string`): `toggle`: a setting (a switch; a check in a picker). `picker`: opens a nested list (a caret).
- `title` (`string`): The row's label. The query is matched against it.

Source: [ui/src/components/palette/PaletteList.tsx:33](https://github.com/Tahul/zidane/blob/main/ui/src/components/palette/PaletteList.tsx#L33)

### `PaletteIconProps`

Interface.

Props for [`PaletteIcon`](https://zidane.si/docs/reference/ui-components-palette-palette-list.md#PaletteIcon).

```ts
interface PaletteIconProps
```

**Properties**

- `className?` (`string`): Extra classes on the root element.
- `icon?` (`string`): Icon class. A small dot shows when omitted.
- `style?` (`CSSProperties`): Inline styles on the root element, merged after the component's own.

Source: [ui/src/components/palette/PaletteList.tsx:374](https://github.com/Tahul/zidane/blob/main/ui/src/components/palette/PaletteList.tsx#L374)

### `PaletteListProps`

Interface.

Props of [`PaletteList`](https://zidane.si/docs/reference/ui-components-palette-palette-list.md#PaletteList).

```ts
interface PaletteListProps<T extends PaletteEntry = PaletteEntry>
```

**Type parameters**

- `T` (`extends PaletteEntry`, default `PaletteEntry`)

**Properties**

- `className?` (`string`): Extra classes on the root element.
- `cursor` (`number`): Flat index of the marked row, across sections. The list scrolls to keep it in view.
- `groups` (`readonly PaletteSection<T>[]`): The ranked sections to show.
- `nested` (`boolean`): A picker's level: its `toggle` rows are choices (a check), not settings (a switch).
- `onHover` (`(index: number) => void`): Called with a row's flat index when the pointer moves over it.
- `onRun` (`(row: PaletteRowData<T>) => void`): Called with the row when it is clicked.
- `query` (`string`): The current query. Its word count decides whether a title match is shown.
- `renderIcon?` (`(row: PaletteRowData<T>) => ReactNode`): The default row's icon; else a dot.
- `renderKeys?` (`PaletteKeys`, default `defaultPaletteKeys`): Draws a keybinding spec as keycaps.
- `renderRow?` (`(props: PaletteRowProps<T>) => ReactNode`): Draws a row; return `undefined` for the default row. Keep it stable (rows are memoized on their props).
- `style?` (`CSSProperties`): Inline styles on the root element, merged after the component's own.

Source: [ui/src/components/palette/PaletteList.tsx:98](https://github.com/Tahul/zidane/blob/main/ui/src/components/palette/PaletteList.tsx#L98)

### `PaletteOptionProps`

Interface.

Props for [`PaletteOption`](https://zidane.si/docs/reference/ui-components-palette-palette-list.md#PaletteOption): the row's [`PaletteRowProps`](https://zidane.si/docs/reference/ui-components-palette-palette-list.md#PaletteRowProps) plus the `icon`, `title`,
`description`, `trailing`, `toggle` and `checked` props of a [`MenuRow`](https://zidane.si/docs/reference/ui-components-menu.md#MenuRow).

```ts
interface PaletteOptionProps<T extends PaletteEntry = PaletteEntry> extends PaletteRowProps<T>, Pick<MenuRowProps, 'icon' | 'title' | 'description' | 'trailing' | 'toggle' | 'checked'>
```

**Type parameters**

- `T` (`extends PaletteEntry`, default `PaletteEntry`)

**Properties**

- `active` (`boolean`, from `PaletteRowProps`): Whether the cursor is on this row.
- `checked?` (`boolean`, from `Pick`): The current choice: a check in the trailing slot.
- `choice` (`boolean`, from `PaletteRowProps`): In a picker: a checked row is the current choice.
- `className?` (`string`): Extra classes on the root element.
- `description?` (`ReactNode`, from `Pick`): Secondary text after the title. Inline it truncates to one line; `size="lg"` stacks it under
  the title, clamped to two lines.
- `icon?` (`ReactNode`, from `Pick`): Leading glyph, drawn muted. Use it only when it means something (a kind, a folder). No icon
  slot renders when omitted.
- `index` (`number`, from `PaletteRowProps`): Position of the row in the whole list, across sections.
- `onHover` (`(index: number) => void`, from `PaletteRowProps`): Called with the row's `index` when the pointer moves over it.
- `onRun` (`(row: PaletteRowData<T>) => void`, from `PaletteRowProps`): Called with the row when it is clicked.
- `row` (`PaletteRowData<T>`, from `PaletteRowProps`): The row's item and title matches.
- `style?` (`CSSProperties`): Inline styles on the root element, merged after the component's own.
- `terms` (`number`, from `PaletteRowProps`): Words in the query: a title match is shown when each reads as one run.
- `title` (`ReactNode`, from `Pick`): The row's label.
- `toggle?` (`boolean`, from `Pick`): An on/off option: a switch in the trailing slot (use with `role="menuitemcheckbox"`).
- `top` (`number`, from `PaletteRowProps`): Offset inside its section.
- `trailing?` (`ReactNode`, from `Pick`): Content at the row's end, such as a keycap or a meta value. A check or switch from `checked` or
  `toggle` follows it.

Source: [ui/src/components/palette/PaletteList.tsx:320](https://github.com/Tahul/zidane/blob/main/ui/src/components/palette/PaletteList.tsx#L320)

### `PaletteRowData`

Interface.

One ranked result: the item and where its title matched the query (character indices).

```ts
interface PaletteRowData<T extends PaletteEntry = PaletteEntry>
```

**Type parameters**

- `T` (`extends PaletteEntry`, default `PaletteEntry`)

**Properties**

- `item` (`T`): The matched item.
- `titleMatches` (`readonly number[]`): Indices of the characters of `item.title` that matched the query. Empty when nothing matched in
  the title.

Source: [ui/src/components/palette/PaletteList.tsx:53](https://github.com/Tahul/zidane/blob/main/ui/src/components/palette/PaletteList.tsx#L53)

### `PaletteRowProps`

Interface.

Props of one palette row, as passed to `renderRow`.

```ts
interface PaletteRowProps<T extends PaletteEntry = PaletteEntry>
```

**Type parameters**

- `T` (`extends PaletteEntry`, default `PaletteEntry`)

**Properties**

- `active` (`boolean`): Whether the cursor is on this row.
- `choice` (`boolean`): In a picker: a checked row is the current choice.
- `index` (`number`): Position of the row in the whole list, across sections.
- `onHover` (`(index: number) => void`): Called with the row's `index` when the pointer moves over it.
- `onRun` (`(row: PaletteRowData<T>) => void`): Called with the row when it is clicked.
- `row` (`PaletteRowData<T>`): The row's item and title matches.
- `terms` (`number`): Words in the query: a title match is shown when each reads as one run.
- `top` (`number`): Offset inside its section.

Source: [ui/src/components/palette/PaletteList.tsx:72](https://github.com/Tahul/zidane/blob/main/ui/src/components/palette/PaletteList.tsx#L72)

### `PaletteSection`

Interface.

A titled group of ranked rows.

```ts
interface PaletteSection<T extends PaletteEntry = PaletteEntry>
```

**Type parameters**

- `T` (`extends PaletteEntry`, default `PaletteEntry`)

**Properties**

- `rows` (`readonly PaletteRowData<T>[]`): The section's rows, in order.
- `title` (`string`): Heading of the section.

Source: [ui/src/components/palette/PaletteList.tsx:64](https://github.com/Tahul/zidane/blob/main/ui/src/components/palette/PaletteList.tsx#L64)

## Types

### `PaletteKeys`

Type.

Keycaps for a binding spec (`cmd+k`); an app with its own binding grammar passes its own.

```ts
type PaletteKeys = (spec: string) => ReactNode
```

Source: [ui/src/components/palette/PaletteList.tsx:92](https://github.com/Tahul/zidane/blob/main/ui/src/components/palette/PaletteList.tsx#L92)