components/palette/PaletteList
import { … } from 'zidane-ui'ui/src/components/palette/PaletteList.tsx
Components#
MatchedTitleComponent#
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.
function MatchedTitle(props: MatchedTitleProps): ElementParameters
| Name | Type | Description |
|---|---|---|
| props | MatchedTitleProps | Component props. |
Returns
ElementProps
| Name | Type | Description |
|---|---|---|
| indices | readonly number[] | Indices of the matched characters in |
| 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. |
PaletteIconComponent#
The item's glyph in the icon slot, quiet until its row is marked.
function PaletteIcon(props: PaletteIconProps): ElementParameters
| Name | Type | Description |
|---|---|---|
| props | PaletteIconProps | Component props. |
Returns
ElementProps
| Name | Type | Description |
|---|---|---|
| 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. |
PaletteListComponent#
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.
function PaletteList<T extends PaletteEntry>(props: PaletteListProps<T>): ElementType parameters
| Name | Type | Description |
|---|---|---|
| T | extends PaletteEntry |
Parameters
| Name | Type | Description |
|---|---|---|
| props | PaletteListProps<T> | Component props. |
Returns
ElementProps
| Name | Type | Default | Description |
|---|---|---|---|
| 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 | |
| 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 | defaultPaletteKeys | Draws a keybinding spec as keycaps. |
| renderRow? | (props: PaletteRowProps<T>) => ReactNode | Draws a row; return | |
| style? | CSSProperties | Inline styles on the root element, merged after the component's own. |
PaletteOptionComponent#
One palette option: a menu row with listbox semantics (focus stays in the query input).
function PaletteOption<T extends PaletteEntry>(props: PaletteOptionProps<T>): ElementType parameters
| Name | Type | Description |
|---|---|---|
| T | extends PaletteEntry |
Parameters
| Name | Type | Description |
|---|---|---|
| props | PaletteOptionProps<T> | The row's |
Returns
ElementProps
| Name | Type | Description |
|---|---|---|
activefrom PaletteRowProps | boolean | Whether the cursor is on this row. |
checked?from Pick | boolean | The current choice: a check in the trailing slot. |
choicefrom PaletteRowProps | boolean | In a picker: a checked row is the current choice. |
| className? | string | Extra classes on the root element. |
description?from Pick | ReactNode | Secondary text after the title. Inline it truncates to one line; |
icon?from Pick | ReactNode | Leading glyph, drawn muted. Use it only when it means something (a kind, a folder). No icon slot renders when omitted. |
indexfrom PaletteRowProps | number | Position of the row in the whole list, across sections. |
onHoverfrom PaletteRowProps | (index: number) => void | Called with the row's |
onRunfrom PaletteRowProps | (row: PaletteRowData<T>) => void | Called with the row when it is clicked. |
rowfrom PaletteRowProps | PaletteRowData<T> | The row's item and title matches. |
| style? | CSSProperties | Inline styles on the root element, merged after the component's own. |
termsfrom PaletteRowProps | number | Words in the query: a title match is shown when each reads as one run. |
titlefrom Pick | ReactNode | The row's label. |
toggle?from Pick | boolean | An on/off option: a switch in the trailing slot (use with |
topfrom PaletteRowProps | number | Offset inside its section. |
trailing?from Pick | ReactNode | Content at the row's end, such as a keycap or a meta value. A check or switch from |
PaletteRowComponent#
The default row: icon, matched title, detail when marked, then a switch, a check, a caret or the shortcut.
const PaletteRow: MemoExoticComponent<(props: PaletteRowProps<PaletteEntry> & Pick<PaletteOptionProps<PaletteEntry>, 'className' | 'style'> & { renderIcon?: (row: PaletteRowData) => ReactNode; renderKeys?: PaletteKeys }) => Element>Constants#
defaultPaletteKeysConstant#
The default PaletteKeys: a small KeyCombo for the binding spec.
const defaultPaletteKeys: PaletteKeysInterfaces#
MatchedTitlePropsInterface#
Props for MatchedTitle.
interface MatchedTitlePropsProperties
| Name | Type | Description |
|---|---|---|
| indices | readonly number[] | Indices of the matched characters in |
| 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. |
PaletteEntryInterface#
What a palette row shows. Structural, so an app's own item type fits as is.
interface PaletteEntryProperties
| Name | Type | Description |
|---|---|---|
| checked? | boolean | Current state of a |
| 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 |
|
| title | string | The row's label. The query is matched against it. |
PaletteIconPropsInterface#
Props for PaletteIcon.
interface PaletteIconPropsProperties
| Name | Type | Description |
|---|---|---|
| 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. |
PaletteListPropsInterface#
Props of PaletteList.
interface PaletteListProps<T extends PaletteEntry = PaletteEntry>Type parameters
| Name | Type | Default | Description |
|---|---|---|---|
| T | extends PaletteEntry | PaletteEntry |
Properties
| Name | Type | Default | Description |
|---|---|---|---|
| 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 | |
| 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 | defaultPaletteKeys | Draws a keybinding spec as keycaps. |
| renderRow? | (props: PaletteRowProps<T>) => ReactNode | Draws a row; return | |
| style? | CSSProperties | Inline styles on the root element, merged after the component's own. |
PaletteOptionPropsInterface#
Props for PaletteOption: the row's PaletteRowProps plus the icon, title,
description, trailing, toggle and checked props of a MenuRow.
interface PaletteOptionProps<T extends PaletteEntry = PaletteEntry> extends PaletteRowProps<T>, Pick<MenuRowProps, 'icon' | 'title' | 'description' | 'trailing' | 'toggle' | 'checked'>Type parameters
| Name | Type | Default | Description |
|---|---|---|---|
| T | extends PaletteEntry | PaletteEntry |
Properties
| Name | Type | Description |
|---|---|---|
activefrom PaletteRowProps | boolean | Whether the cursor is on this row. |
checked?from Pick | boolean | The current choice: a check in the trailing slot. |
choicefrom PaletteRowProps | boolean | In a picker: a checked row is the current choice. |
| className? | string | Extra classes on the root element. |
description?from Pick | ReactNode | Secondary text after the title. Inline it truncates to one line; |
icon?from Pick | ReactNode | Leading glyph, drawn muted. Use it only when it means something (a kind, a folder). No icon slot renders when omitted. |
indexfrom PaletteRowProps | number | Position of the row in the whole list, across sections. |
onHoverfrom PaletteRowProps | (index: number) => void | Called with the row's |
onRunfrom PaletteRowProps | (row: PaletteRowData<T>) => void | Called with the row when it is clicked. |
rowfrom PaletteRowProps | PaletteRowData<T> | The row's item and title matches. |
| style? | CSSProperties | Inline styles on the root element, merged after the component's own. |
termsfrom PaletteRowProps | number | Words in the query: a title match is shown when each reads as one run. |
titlefrom Pick | ReactNode | The row's label. |
toggle?from Pick | boolean | An on/off option: a switch in the trailing slot (use with |
topfrom PaletteRowProps | number | Offset inside its section. |
trailing?from Pick | ReactNode | Content at the row's end, such as a keycap or a meta value. A check or switch from |
PaletteRowDataInterface#
One ranked result: the item and where its title matched the query (character indices).
interface PaletteRowData<T extends PaletteEntry = PaletteEntry>Type parameters
| Name | Type | Default | Description |
|---|---|---|---|
| T | extends PaletteEntry | PaletteEntry |
Properties
| Name | Type | Description |
|---|---|---|
| item | T | The matched item. |
| titleMatches | readonly number[] | Indices of the characters of |
PaletteRowPropsInterface#
Props of one palette row, as passed to renderRow.
interface PaletteRowProps<T extends PaletteEntry = PaletteEntry>Type parameters
| Name | Type | Default | Description |
|---|---|---|---|
| T | extends PaletteEntry | PaletteEntry |
Properties
| Name | Type | Description |
|---|---|---|
| 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 |
| 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. |
PaletteSectionInterface#
A titled group of ranked rows.
interface PaletteSection<T extends PaletteEntry = PaletteEntry>Type parameters
| Name | Type | Default | Description |
|---|---|---|---|
| T | extends PaletteEntry | PaletteEntry |
Properties
| Name | Type | Description |
|---|---|---|
| rows | readonly PaletteRowData<T>[] | The section's rows, in order. |
| title | string | Heading of the section. |
Types#
PaletteKeysType#
Keycaps for a binding spec (cmd+k); an app with its own binding grammar passes its own.
type PaletteKeys = (spec: string) => ReactNode