components/listbox/listbox.react.tsx

Functions

Imports

It imports components/listbox/listbox.ts. Imported by components/command-menu/command-menu.react.tsx.

Source

1import { Fragment, useId, type HTMLAttributes, type ReactNode } from "react";
2import { resultsText, type ListboxMode, type Selection } from "./listbox.ts";
3
4export { emptyText, filterCommands, groupBy, matchesQuery, nextTypeahead, resultsText, step, stepEnabled } from "./listbox.ts";
5export type { ListboxMode, Selection } from "./listbox.ts";
6
7// The listbox's HTML contract, rendered from props. The state that changes (which option is
8// active, which is chosen, what is filtered out) is the caller's React state, passed down as
9// `active` and `selected`; use the pure functions above for the filtering and the stepping.
10// For an input that holds focus, give it aria-activedescendant={the active option's id}.
11// Nothing here sets a `style` prop, so it renders on the server under style-src 'self'.
12
13export interface ListboxProps extends Omit<HTMLAttributes<HTMLDivElement>, "role"> {
14  // Name it: aria-label or aria-labelledby.
15  selection?: Selection;
16  mode?: ListboxMode;
17  // Draws its own border and surface, for a list on its own page.
18  variant?: "surface";
19  // Set when something else (Base UI, your own handler) moves the highlight, so the pointer
20  // does not also light the row under it.
21  controlled?: boolean;
22}
23
24export function Listbox({ selection = "none", mode = "descendant", variant, controlled, className, children, ...rest }: ListboxProps) {
25  return (
26    <div
27      tabIndex={mode === "descendant" ? 0 : undefined}
28      {...rest}
29      role="listbox"
30      className={className ? `cap-listbox ${className}` : "cap-listbox"}
31      aria-multiselectable={selection === "multi" ? true : undefined}
32      data-selection={selection}
33      data-mode={mode}
34      data-variant={variant}
35      data-controlled={controlled ? "" : undefined}
36    >
37      {children}
38    </div>
39  );
40}
41
42const Check = () => (
43  <svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true" focusable="false">
44    <path d="M3.5 8.5 6.5 11.5 12.5 4.5" />
45  </svg>
46);
47
48export interface OptionProps extends Omit<HTMLAttributes<HTMLDivElement>, "role" | "id"> {
49  // Required for aria-activedescendant to name it.
50  id: string;
51  value?: string;
52  // Chosen. Leave undefined in a list where nothing is chosen (a command menu).
53  selected?: boolean;
54  // The current option (the one Enter acts on).
55  active?: boolean;
56  disabled?: boolean;
57  tone?: "crit";
58  // Other words that find it.
59  keywords?: readonly string[];
60  icon?: ReactNode;
61  // A note in words, read after the label: "asks a reason".
62  hint?: ReactNode;
63  // Shortcut caps ["g", "o"], or any node.
64  keys?: readonly string[] | ReactNode;
65}
66
67export function Option({ id, value, selected, active, disabled, tone, keywords, icon, hint, keys, className, children, ...rest }: OptionProps) {
68  const caps = Array.isArray(keys) ? (keys as readonly string[]) : null;
69  const hasKeys = hint != null || (caps ? caps.length > 0 : keys != null);
70  return (
71    <div
72      {...rest}
73      id={id}
74      role="option"
75      className={className ? `cap-option ${className}` : "cap-option"}
76      aria-selected={selected === undefined ? undefined : selected}
77      aria-disabled={disabled ? true : undefined}
78      data-active={active ? "" : undefined}
79      data-tone={tone}
80      data-value={value}
81      data-keywords={keywords?.length ? keywords.join(",") : undefined}
82    >
83      {icon != null ? <span className="cap-option-icon">{icon}</span> : null}
84      <span className="cap-option-label">{children}</span>
85      {hasKeys ? (
86        <span className="cap-option-keys">
87          {hint != null ? (
88            <>
89              <span className="cap-sr-only">, </span>
90              <span className="cap-option-hint">{hint}</span>
91            </>
92          ) : null}
93          {caps ? (
94            <>
95              <span className="cap-sr-only">, shortcut </span>
96              {caps.map((cap, i) => (
97                <Fragment key={`${cap}-${i}`}>
98                  {i > 0 ? " " : null}
99                  <kbd>{cap}</kbd>
100                </Fragment>
101              ))}
102            </>
103          ) : (
104            (keys as ReactNode)
105          )}
106        </span>
107      ) : null}
108      {selected !== undefined ? (
109        <span className="cap-option-indicator" aria-hidden="true">
110          <Check />
111        </span>
112      ) : null}
113    </div>
114  );
115}
116
117export interface OptionGroupProps extends Omit<HTMLAttributes<HTMLDivElement>, "role"> {
118  label: ReactNode;
119}
120
121export function OptionGroup({ label, className, children, ...rest }: OptionGroupProps) {
122  const labelId = useId();
123  return (
124    <div {...rest} role="group" aria-labelledby={labelId} className={className ? `cap-listbox-group ${className}` : "cap-listbox-group"}>
125      <div className="cap-listbox-label" id={labelId} role="presentation">
126        {label}
127      </div>
128      {children}
129    </div>
130  );
131}
132
133export function ListboxSeparator() {
134  return <div className="cap-listbox-separator" aria-hidden="true" />;
135}
136
137// "No results for ..." beside the list, in a status region. Takes no room while empty.
138export function ListboxEmpty({ children }: { children?: ReactNode }) {
139  return (
140    <p className="cap-listbox-empty" role="status">
141      {children}
142    </p>
143  );
144}
145
146// The polite live region that says the count after a filter. Visually hidden.
147export function ListboxStatus({ count, filtered }: { count: number; filtered: boolean }) {
148  return (
149    <div className="cap-sr-only" role="status" aria-atomic="true">
150      {filtered && count > 0 ? resultsText(count) : ""}
151    </div>
152  );
153}