@crewlethq/ui 0.2.0 → 0.3.0

package/dist/Link/index.d.ts

@@ -0,0 +1,3 @@
+import './Link.css';
+export { Link } from './Link.js';
+export type { LinkProps, LinkVariant, LinkSize } from './Link.js';

package/dist/Link/index.js

@@ -0,0 +1,3 @@
+export { Link } from '../chunk-2ZQMA2WB.js';
+import '../chunk-BZFWDIV6.js';
+import '../chunk-ODEQTPFM.js';

package/dist/Link-6BEFNMN2.css

@@ -0,0 +1,80 @@
+/*
+ * A link, in the two registers a console needs: a navigation and an identity.
+ *
+ * The ink is the accent's INK step, not the accent fill. The fill is a mark
+ * and clears 3:1; text has to clear 4.5:1, and at caption size it is exactly
+ * the place a fill-as-text fails.
+ */
+
+.crewlet-link {
+  display: inline;
+  color: var(--color-brand-accent-ink);
+  text-decoration: none;
+  border-radius: var(--radius-xs);
+  transition: color var(--motion-duration-fast) var(--motion-easing-default);
+}
+
+.crewlet-link:hover {
+  text-decoration: underline;
+}
+
+.crewlet-link:focus-visible {
+  outline: 2px solid var(--color-focus);
+  outline-offset: 2px;
+}
+
+/* An identity, not an instruction: neutral until a reader reaches for it. */
+.crewlet-link--subtle {
+  color: var(--color-text-primary);
+}
+
+.crewlet-link--subtle:hover {
+  color: var(--color-brand-accent-ink);
+}
+
+.crewlet-link--body {
+  font-size: var(--font-size-sm);
+}
+
+/*
+ * A caption-sized link takes the caption's SIZE and keeps the link's ink. It
+ * is medium weight and does not wrap, because the thing it names (an event id,
+ * a turn, a model) is one token a reader scans for.
+ */
+.crewlet-link--caption {
+  font-size: var(--font-size-xs);
+  font-weight: var(--font-weight-medium);
+  white-space: nowrap;
+}
+
+/*
+ * A whole row is the target. No underline, because the row's own hover says
+ * it is live, and the ring is drawn INSIDE: a row inside a clipping scroller
+ * loses an outset ring to the scroller's edge and to the next row painted
+ * over it.
+ */
+.crewlet-link--block {
+  display: block;
+  width: 100%;
+  color: inherit;
+}
+
+.crewlet-link--block:hover {
+  text-decoration: none;
+}
+
+.crewlet-link--block:focus-visible {
+  outline-offset: var(--size-focus-ring-inset-offset);
+}
+
+.crewlet-link__external {
+  /* Sits on the text baseline beside the last word rather than under it. */
+  vertical-align: -0.125em;
+  margin-inline-start: var(--spacing-1);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .crewlet-link {
+    transition: none;
+  }
+}

package/dist/List/List.d.ts

@@ -0,0 +1,73 @@
+import { type HTMLAttributes, type LiHTMLAttributes, type ReactNode } from 'react';
+export type ListVariant = 
+/**
+ * Rows with nothing between them. A set of chips, a stack of links in a
+ * footer: a group where a hairline would draw a table nobody asked for.
+ */
+'plain'
+/** A bullet per row: prose, not data. */
+ | 'bulleted'
+/** A number per row: an order somebody follows. */
+ | 'numbered'
+/**
+ * A hairline between rows: a feed, a set of results, a conversation. THE
+ * DEFAULT, because it is the list every screen in the product draws: rows a
+ * reader scans down want a boundary they can count.
+ */
+ | 'divided';
+export interface ListProps extends HTMLAttributes<HTMLElement> {
+    variant?: ListVariant | undefined;
+    /**
+     * A grid template for every row, so a feed's rows scan as COLUMNS rather
+     * than as a ragged stack: `'auto 1fr auto'`. It is set on the list rather
+     * than on each row for exactly that reason, a column only lines up if every
+     * row measures itself against the same track list.
+     */
+    template?: string | undefined;
+}
+/**
+ * The non-tabular list: an activity feed, a set of search results, a
+ * conversation, the goals on a seat.
+ *
+ * A LIST, NOT A TABLE. A table promises that every row carries the same fields
+ * and that a reader may sort and compare them. A feed promises neither, and
+ * rendering one as a table makes a screen reader announce a column count that
+ * means nothing. What a feed does want is alignment, which `template` gives it
+ * without the promise.
+ */
+export declare function List({ variant, template, className, style, children, ...rest }: ListProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace List {
+    var Item: typeof ListItem;
+}
+export type ListItemTone = 'default' | 'danger';
+export interface ListItemProps extends Omit<LiHTMLAttributes<HTMLLIElement>, 'onClick'> {
+    /** Makes the whole row a link. */
+    href?: string | undefined;
+    /** Makes the whole row a button. Ignored when `href` is given. */
+    onClick?: (() => void) | undefined;
+    /** Drawn before the row's content: a glyph, an avatar, a status mark. */
+    leading?: ReactNode;
+    /** Drawn after it: a time, a count, a chevron. */
+    trailing?: ReactNode;
+    tone?: ListItemTone | undefined;
+    /** Read in place of the danger rail, so colour is never the only signal. */
+    dangerLabel?: string | undefined;
+    /** This row is the one the reader is on. */
+    selected?: boolean | undefined;
+    /**
+     * Render the single child element as the row's control, for a router's own
+     * Link. The row's content then comes from that element's children.
+     */
+    asChild?: boolean | undefined;
+}
+/**
+ * One row.
+ *
+ * A ROW THAT DOES SOMETHING IS A CONTROL, never a `div` with a click handler:
+ * `href` draws a real anchor and `onClick` a real button, so both are reached
+ * by Tab, activated by Enter, and announced as what they are. The row's own
+ * hover and focus ring belong to that control rather than to the `li` around
+ * it, which is what stops a keyboard reader seeing a ring around a row they
+ * cannot activate.
+ */
+export declare function ListItem({ href, onClick, leading, trailing, tone, dangerLabel, selected, asChild, className, children, ...rest }: ListItemProps): import("react/jsx-runtime").JSX.Element;

package/dist/List/index.d.ts

@@ -0,0 +1,3 @@
+import './List.css';
+export { List, ListItem } from './List.js';
+export type { ListProps, ListVariant, ListItemProps, ListItemTone } from './List.js';

package/dist/List/index.js

@@ -0,0 +1,3 @@
+export { List, ListItem } from '../chunk-HZ5XZNPS.js';
+import '../chunk-BZFWDIV6.js';
+import '../chunk-ODEQTPFM.js';

package/dist/List-XTHESXLR.css

@@ -0,0 +1,161 @@
+/*
+ * The non-tabular list. One row recipe, four framings.
+ *
+ * The row's height is --size-row-md, so every list in a product lines up with
+ * every other and a density setting reaches all of them at once.
+ */
+
+.crewlet-list {
+  display: flex;
+  flex-direction: column;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  min-width: 0;
+}
+
+.crewlet-list__item {
+  min-width: 0;
+}
+
+.crewlet-list__row {
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-3);
+  width: 100%;
+  min-width: 0;
+  min-height: var(--size-row-md);
+  padding: var(--spacing-2) var(--spacing-3);
+  border-radius: var(--radius-xs);
+  text-align: left;
+  font: inherit;
+  color: inherit;
+  background: none;
+  border: none;
+  text-decoration: none;
+}
+
+/*
+ * Columns, on every row at once. A track list set per row lines nothing up,
+ * which is the whole reason the template belongs to the list.
+ */
+.crewlet-list--templated .crewlet-list__row--templated {
+  display: grid;
+  grid-template-columns: var(--crewlet-list-template);
+  align-items: center;
+}
+
+.crewlet-list__content {
+  min-width: 0;
+}
+
+.crewlet-list__leading,
+.crewlet-list__trailing {
+  display: inline-flex;
+  align-items: center;
+  flex: none;
+}
+
+/* The row's own words take the room; a time or a count sits at the end. */
+.crewlet-list__trailing {
+  margin-inline-start: auto;
+}
+
+.crewlet-list--templated .crewlet-list__trailing {
+  margin-inline-start: 0;
+}
+
+.crewlet-list__row--interactive {
+  cursor: pointer;
+  transition: background var(--motion-duration-fast) var(--motion-easing-default);
+}
+
+.crewlet-list__row--interactive:hover {
+  background: var(--color-surface-hover);
+}
+
+/*
+ * The ring is drawn INSIDE the row. A list sits in a clipping scroller more
+ * often than not, where an outset ring is cut off on the first and last rows
+ * and painted over by the row below.
+ */
+.crewlet-list__row:focus-visible {
+  outline: 2px solid var(--color-focus);
+  outline-offset: var(--size-focus-ring-inset-offset);
+}
+
+/* ---- Framings ---------------------------------------------------------- */
+
+.crewlet-list--divided .crewlet-list__item {
+  border-bottom: 1px solid var(--color-border-default);
+}
+
+.crewlet-list--divided .crewlet-list__item:last-child {
+  border-bottom: none;
+}
+
+.crewlet-list--divided .crewlet-list__row {
+  border-radius: 0;
+}
+
+/*
+ * Bullets and numbers are prose furniture, so those two framings drop the row
+ * height and the horizontal pad: a paragraph's list should sit against the
+ * paragraph's own left edge.
+ */
+.crewlet-list--bulleted,
+.crewlet-list--numbered {
+  padding-inline-start: var(--spacing-5);
+  list-style: revert;
+}
+
+.crewlet-list--bulleted .crewlet-list__item,
+.crewlet-list--numbered .crewlet-list__item {
+  display: list-item;
+}
+
+.crewlet-list--bulleted .crewlet-list__row,
+.crewlet-list--numbered .crewlet-list__row {
+  min-height: 0;
+  padding-inline: 0;
+}
+
+/* ---- States ------------------------------------------------------------ */
+
+/*
+ * The row the reader is on. The accent is the one colour that means "here",
+ * and the rail is what carries it at a glance in a long list.
+ */
+.crewlet-list__item--selected > .crewlet-list__row {
+  background: var(--color-brand-accent-soft);
+  box-shadow: inset 2px 0 0 var(--color-brand-accent);
+}
+
+/*
+ * A selected row does NOT also take the hover overlay. Both are a background
+ * on the same element, the selected tint wins, and a composite of the two is a
+ * colour nothing has measured.
+ */
+.crewlet-list__item--selected > .crewlet-list__row--interactive:hover {
+  background: var(--color-brand-accent-soft);
+}
+
+/*
+ * A row that failed. The rail is the scannable half and the glyph beside it is
+ * the honest one: a reader who cannot tell the rail's hue from the row above
+ * still meets a mark and a word.
+ */
+.crewlet-list__item--danger > .crewlet-list__row {
+  box-shadow: inset 2px 0 0 var(--color-feedback-danger);
+}
+
+.crewlet-list__danger-mark {
+  flex: none;
+  color: var(--color-feedback-danger);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .crewlet-list__row--interactive {
+    transition: none;
+  }
+}

package/dist/ListInput/ListInput.d.ts

@@ -0,0 +1,68 @@
+import { type ReactNode } from 'react';
+export interface ListInputProps {
+    /** The list's name, such as "Responsibilities". It is the group's legend. */
+    label: string;
+    /** One item's name in lower case, such as "responsibility". Every control is named with it. */
+    itemName: string;
+    value: readonly string[];
+    onChange: (next: string[]) => void;
+    /** Items are paragraphs: Shift+Enter makes a newline. */
+    multiline?: boolean | undefined;
+    /** Where the values come from, or what shape they take. */
+    helper?: ReactNode | undefined;
+    /** Why the last value was refused. */
+    error?: ReactNode | undefined;
+    /** Shown in the new-item box. */
+    placeholder?: string | undefined;
+    disabled?: boolean | undefined;
+    /** Says "(optional)" beside the legend. */
+    optional?: boolean | undefined;
+    /** Draws the Enter keycap inside the new-item box, which is what adds one. */
+    enterHint?: boolean | undefined;
+    /** The name of the control beside the legend that appends what the box holds. */
+    addLabel?: ((itemName: string) => string) | undefined;
+    itemLabel?: ((name: string, position: string) => string) | undefined;
+    newItemLabel?: ((itemName: string) => string) | undefined;
+    moveUpLabel?: ((itemName: string, position: string) => string) | undefined;
+    moveDownLabel?: ((itemName: string, position: string) => string) | undefined;
+    removeLabel?: ((itemName: string, position: string) => string) | undefined;
+    addedMessage?: ((itemName: string, position: string) => string) | undefined;
+    removedMessage?: ((itemName: string, position: string) => string) | undefined;
+    movedMessage?: ((itemName: string, position: number, count: number) => string) | undefined;
+}
+/**
+ * An ordered list of strings, edited in place.
+ *
+ * WHY IT EXISTS. A seat's responsibilities, a unit's goals and a company's
+ * policies are ordered lists of sentences, and the order is meaning: the
+ * first policy is read first. A comma-separated text box loses the commas
+ * inside a sentence, and one row per item with no way to reorder turns "move
+ * this up" into deleting and retyping it.
+ *
+ * THE RULES IT KEEPS.
+ *
+ * - ENTER ADDS. In the new-item box, Enter appends what was typed (trimmed at
+ *   the ends) and leaves focus in the box for the next one. In an item, Enter
+ *   moves on to the next item, or to the new-item box after the last. It is
+ *   never allowed to submit the form the list sits in: finishing a sentence
+ *   is not saving the editor.
+ * - SHIFT+ENTER IS A NEWLINE in a multiline list, where an item is a paragraph.
+ * - A KEY AN INPUT METHOD IS COMPOSING WITH IS ITS OWN: the Enter that accepts
+ *   a word neither adds the item nor moves on, and Alt+Arrow does not reorder
+ *   under a half-built word.
+ * - EVERY ITEM IS EDITED WHERE IT IS, as its own labelled control ("Goal 2 of
+ *   3"), with Move up, Move down and Remove beside it.
+ * - ALT+UP AND ALT+DOWN MOVE THE FOCUSED ITEM, and focus moves with it. After
+ *   a Move button, focus stays on that item's button, or on its other one when
+ *   the item reached an end, so pressing it again keeps working.
+ * - REMOVING an item moves focus to the item that took its place, else the one
+ *   before, else the new-item box, so focus never falls to the page.
+ * - EVERY CHANGE IS ANNOUNCED, because a move or a removal is otherwise silent
+ *   to anybody not watching the rows.
+ * - AN ITEM KEEPS ITS ELEMENT ACROSS A MOVE, so a caret and an input method's
+ *   composition survive reordering. Two identical sentences are still two
+ *   items.
+ *
+ * Ported from the engine dashboard's `ui/ListField.tsx`.
+ */
+export declare function ListInput({ label, itemName, value, onChange, multiline, helper, error, placeholder, disabled, optional, enterHint, addLabel, itemLabel, newItemLabel, moveUpLabel, moveDownLabel, removeLabel, addedMessage, removedMessage, movedMessage, }: ListInputProps): import("react/jsx-runtime").JSX.Element;

package/dist/ListInput/index.d.ts

@@ -0,0 +1,3 @@
+import './ListInput.css';
+export { ListInput } from './ListInput.js';
+export type { ListInputProps } from './ListInput.js';

package/dist/ListInput/index.js

@@ -0,0 +1,10 @@
+export { ListInput } from '../chunk-EN6K2IFA.js';
+import '../chunk-SFZOKW2G.js';
+import '../chunk-O6232G37.js';
+import '../chunk-PQADV6P6.js';
+import '../chunk-7RPGY3JE.js';
+import '../chunk-ITHXJHBB.js';
+import '../chunk-F27EPQ7D.js';
+import '../chunk-RSAQOKH3.js';
+import '../chunk-BZFWDIV6.js';
+import '../chunk-ODEQTPFM.js';

package/dist/ListInput-O7LJKOIG.css

@@ -0,0 +1,147 @@
+/*
+ * ListInput: an ordered list of sentences, written in the box at the top and
+ * listed under it.
+ *
+ * THE LIST IS ONE CARD, and each item one line of it. A stack of separate
+ * boxes, each a two-row textarea with three buttons beside it, is a form per
+ * item: three of them measured 256px where the console's own list draws 111,
+ * and the second row of every textarea was empty. The card, the dividing
+ * rules and the drawn position are what make a list of sentences read as a
+ * list rather than as a column of fields.
+ */
+
+.crewlet-list-input__add {
+  display: flex;
+  align-items: flex-start;
+}
+
+.crewlet-list-input__add > * {
+  flex: 1;
+  min-width: 0;
+}
+
+.crewlet-list-input__items {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  /*
+   * Split rather than the shorthand, so the width and the style are readable
+   * where the colour is not: the suites substitute the length tokens and
+   * deliberately leave a colour standing, which drops a whole shorthand
+   * holding one.
+   */
+  border-width: 1px;
+  border-style: solid;
+  border-color: var(--color-border-default);
+  border-radius: var(--radius-md);
+  /*
+   * The page's own ground, one step from the sheet's. A card drawn on the
+   * ground it sits on is a card nobody can see: the sheet is the subtle step,
+   * so the list takes the step beside it in both palettes (#ffffff on
+   * #f4f4f5, #15171c on #1c1e24).
+   */
+  background: var(--color-surface-background);
+  /*
+   * The card clips, so the first and last rows take its corners: a square row
+   * painted over a rounded edge is the corner disappearing under its own
+   * content.
+   */
+  overflow: hidden;
+}
+
+/*
+ * ONE LINE PER ITEM. The inline padding is the card's own; the block padding
+ * is what is left over once the row's controls have their height, so a row
+ * holding one line of text stands at the height the console draws and a row
+ * holding three grows with them.
+ */
+.crewlet-list-input__item {
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-2);
+  padding: var(--spacing-1) var(--spacing-3);
+  border-block-end-width: 1px;
+  border-block-end-style: solid;
+  border-block-end-color: var(--color-border-default);
+}
+
+.crewlet-list-input__item:last-child {
+  border-block-end-style: none;
+}
+
+.crewlet-list-input__item > .crewlet-input,
+.crewlet-list-input__item > .crewlet-textarea {
+  flex: 1;
+  min-width: 0;
+}
+
+/*
+ * THE ITEM'S CONTROL READS AS THE TEXT IT HOLDS, until it is reached. A
+ * bordered box per row would draw the card's rule twice and turn the list
+ * back into a column of fields; the boundary comes back on hover and the
+ * focus ring is untouched, so nothing about reaching the control is quieter,
+ * only its resting state.
+ */
+.crewlet-list-input__item .crewlet-input,
+.crewlet-list-input__item .crewlet-textarea {
+  background: none;
+  border-color: transparent;
+  /*
+   * THE ROW OWNS THE ROW'S HEIGHT. A control standing at its own step inside
+   * a row that already insets it is a row an inch taller than the sentence in
+   * it: at the control's 44px minimum the list measured 53px a row against
+   * the console's 37. The control's block padding stays, because the text
+   * still needs to clear the rule above and below it; its inline padding goes,
+   * because the position beside it and the row's own gap are that inset
+   * already, and paying it twice indents every sentence past its own number.
+   */
+  min-height: 0;
+}
+
+.crewlet-list-input__item .crewlet-input__control,
+.crewlet-list-input__item .crewlet-textarea {
+  padding-block: var(--spacing-1);
+  padding-inline: 0;
+}
+
+.crewlet-list-input__index {
+  flex: none;
+  min-width: var(--spacing-4);
+  text-align: center;
+  font-size: var(--font-size-xs);
+  font-weight: var(--font-weight-bold);
+  /* The accent's own ink step, which is what the position is: a mark on the
+     card's ground rather than a word in the sentence beside it. */
+  color: var(--color-brand-accent);
+}
+
+.crewlet-list-input__actions {
+  display: inline-flex;
+  align-items: center;
+  flex: none;
+}
+
+/*
+ * MOVE UP AND MOVE DOWN ARE THE ROW'S SECOND THOUGHT. Three controls on every
+ * row is what made this list a grid of buttons; the console draws one. They
+ * are revealed by the pointer and by the focus, never removed: an invisible
+ * control that still takes a Tab is the worst of both, so the same state that
+ * lets the keyboard reach them is the state that draws them.
+ */
+.crewlet-list-input__move {
+  display: inline-flex;
+  align-items: center;
+  opacity: 0;
+  transition: opacity var(--motion-duration-fast) var(--motion-easing-default);
+}
+
+.crewlet-list-input__item:hover .crewlet-list-input__move,
+.crewlet-list-input__item:focus-within .crewlet-list-input__move {
+  opacity: 1;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .crewlet-list-input__move {
+    transition: none;
+  }
+}

package/dist/Listbox/index.d.ts

@@ -0,0 +1,5 @@
+import './Listbox.css';
+export { useListbox } from './useListbox.js';
+export type { Listbox, ListboxOptions } from './useListbox.js';
+export { TYPE_AHEAD_WINDOW, useOptionKeys } from './useOptionKeys.js';
+export type { OptionKeys, OptionKeysOptions } from './useOptionKeys.js';

package/dist/Listbox/index.js

@@ -0,0 +1,2 @@
+export { TYPE_AHEAD_WINDOW, useListbox, useOptionKeys } from '../chunk-GTOUGQQK.js';
+import '../chunk-ITHXJHBB.js';

package/dist/Listbox/useListbox.d.ts

@@ -0,0 +1,97 @@
+/**
+ * The keyboard half of a listbox that follows a text field.
+ *
+ * WHY IT EXISTS. A field that offers a list while somebody types (a combobox,
+ * a searchable multi-select, a command palette) keeps focus in the text box
+ * and points at the highlighted option with `aria-activedescendant`. The keys
+ * that move that highlight, take an option and dismiss the list are the same
+ * in every one of them, and a second hand-written copy is how one list starts
+ * wrapping at the ends while the other stops, or how Escape in one closes the
+ * dialog around it.
+ *
+ * THE RULES IT KEEPS.
+ *
+ * - THE HIGHLIGHT WRAPS: Down from the last option goes to the first, Up from
+ *   the first to the last.
+ * - IT IS CLAMPED, NOT RESET, when the list shrinks under somebody's typing,
+ *   so the highlight stays on a row that exists instead of jumping to the top.
+ * - ENTER TAKES THE HIGHLIGHTED OPTION and is prevented, because the field is
+ *   usually inside a form that submits on Enter, and choosing is not saving.
+ *   Tab takes it too where the list is a completion (`tabCommits`); a
+ *   multi-select leaves Tab to move focus, as every form control does.
+ * - ESCAPE CLOSES THE LIST AND NOTHING ELSE. It stops there, so the dialog or
+ *   sheet the field sits in stays open; a second Escape reaches it. That holds
+ *   for a list that is showing with nothing in it too, and for nothing else:
+ *   `open` means the reader can see a list, so an Escape with none on screen
+ *   goes straight to the surface around it.
+ * - THE LIST IS A POPUP ON THE LAYER STACK, so a press outside it closes the
+ *   list before anything beneath it: a press on a dialog's veil while the list
+ *   is open closes the list and leaves the dialog. The component attaches
+ *   `listRef` to the list it draws and `anchorRef` to the element around the
+ *   field, whose presses are not outside.
+ * - A LIST THAT IS A MODAL'S WHOLE BODY IS NOT A POPUP (`popup: false`). A
+ *   command palette is a modal whose content is its results: the modal's own
+ *   Escape and veil already close it. Registered as a popup above that modal,
+ *   the list would take Escape from the stack and the veil's press on
+ *   `pointerdown`, closing the palette before the press's click and letting
+ *   that click land on whatever the veil was covering.
+ * - THE HIGHLIGHTED ROW STAYS IN VIEW, by scrolling THE LIST ELEMENT and
+ *   nothing else. `scrollIntoView` scrolls every scrollable ancestor it finds,
+ *   and jsdom does not implement it at all, so an unguarded call throws the
+ *   moment a suite opens a list. Re-run when the options change as well as the
+ *   cursor: typing over a list scrolled by the wheel leaves the cursor at 0
+ *   and the row out of view.
+ * - NOTHING IS TAKEN MID-COMPOSITION. While an input method is composing a
+ *   word, the arrows, Enter and Escape are its own, and the handler reports
+ *   them unhandled so the component around it leaves them alone too.
+ * - A PRESS ON AN OPTION IS TAKEN ON `mousedown`, with the default prevented:
+ *   the field would otherwise blur first, and a list that closes on blur takes
+ *   the row out from under the click that was choosing it.
+ *
+ * It owns no markup and no filtering: the component renders the list, decides
+ * what is offered and what taking an option means. The classes it is drawn
+ * with are in `Listbox.css`.
+ *
+ * Ported from the engine dashboard's `ui/useListbox.ts`.
+ */
+import { type KeyboardEvent, type MouseEvent } from 'react';
+export interface ListboxOptions {
+    /** A stable base for element ids, usually from `useId`. */
+    id: string;
+    /** Whether a list is on screen, including one that says nothing matches. */
+    open: boolean;
+    /** How many options are offered right now. */
+    count: number;
+    /** Taking the option at `index`. */
+    onCommit: (index: number) => void;
+    /** Escape, or a press outside the list, while the list is a popup. */
+    onClose: () => void;
+    /**
+     * Whether the list is a popup on the layer stack (the default), or the body
+     * of a modal that owns Escape and its veil itself.
+     */
+    popup?: boolean | undefined;
+    /** Whether Tab takes the highlighted option (a completion) or moves focus (a form control). */
+    tabCommits?: boolean | undefined;
+}
+export interface Listbox {
+    /** The highlighted option's index, clamped to what is offered; -1 when nothing is. */
+    active: number;
+    setActive: (index: number) => void;
+    /** The listbox element's id. */
+    listId: string;
+    /** The list on screen: what a press outside is measured against, and what scrolls. */
+    listRef: (el: HTMLElement | null) => void;
+    /** The element around the field: a press on it is not outside the list. */
+    anchorRef: (el: HTMLElement | null) => void;
+    /** The id of the option element at `index`. */
+    optionId: (index: number) => string;
+    /** The field's keydown handler. Returns whether it handled the key. */
+    onKeyDown: (event: KeyboardEvent<HTMLElement>) => boolean;
+    /** Mouse wiring for the option element at `index`. */
+    optionHandlers: (index: number) => {
+        onMouseDown: (event: MouseEvent<HTMLElement>) => void;
+        onMouseEnter: () => void;
+    };
+}
+export declare function useListbox({ id, open, count, onCommit, onClose, tabCommits, popup, }: ListboxOptions): Listbox;