@financedistrict/apps-ui 0.1.0

package/dist/select.d.cts

@@ -0,0 +1,357 @@
+import { S as SelectOption } from './SelectTrigger-By0iPBI3.cjs';
+export { a as SelectTrigger, b as SelectTriggerProps, s as selectTriggerLabel } from './SelectTrigger-By0iPBI3.cjs';
+import * as React from 'react';
+import * as class_variance_authority_types from 'class-variance-authority/types';
+import { VariantProps } from 'class-variance-authority';
+
+/**
+ * Find the next enabled option index moving `dir` (1 = down, -1 = up) from
+ * `from`, skipping `disabled` rows and clamping at the ends (no wrap). If no
+ * enabled row exists in that direction, `from` is returned unchanged. Pure —
+ * unit-testable in isolation.
+ */
+declare function nextEnabledIndex(options: SelectOption[], from: number, dir: 1 | -1): number;
+/** Options for {@link useSelectListbox}. Trigger-agnostic — any button-shaped
+ *  trigger (field, line, inline) can drive the same listbox orchestration. */
+interface UseSelectListboxOptions {
+    /** The options to choose from (array-of-data API). */
+    options: SelectOption[];
+    /** Controlled selection. `string` in single mode, `string[]` in multi. */
+    value?: string | string[];
+    /** Uncontrolled initial selection. */
+    defaultValue?: string | string[];
+    /** Fires with the next selection — `string` (single) or `string[]` (multi). */
+    onValueChange?: (value: string | string[]) => void;
+    /** Single (default) vs multi select. */
+    multiple?: boolean;
+    /** Disabled — the trigger won't open and keys are ignored. */
+    disabled?: boolean;
+    /**
+     * Whether a single-select pick closes the listbox. Default `true` (Select /
+     * InlineSelect behaviour, unchanged). When `false`, single-select does NOT
+     * close on pick — it stays open like multi, keeping the active row on the
+     * chosen option. Multi never closes on pick regardless of this flag. Filter
+     * passes `false` (its dropdown persists so several picks / a Reset are
+     * possible without reopening).
+     */
+    closeOnSelect?: boolean;
+    /** Base id for the widget (trigger id); the listbox id derives from it. */
+    id: string;
+    /** Consumer's forwarded ref to the trigger button (merged with the internal ref). */
+    ref?: React.Ref<HTMLButtonElement>;
+}
+/**
+ * The ARIA popup + activedescendant attributes a trigger button must spread.
+ * `role` is intentionally NOT included — a field trigger uses `role="combobox"`
+ * to legitimize `aria-activedescendant`/`aria-controls` (ADR-0013 #3), which it
+ * sets itself; these attributes are the shared wiring both triggers need.
+ */
+interface SelectTriggerAriaProps {
+    onClick: () => void;
+    onKeyDown: (event: React.KeyboardEvent<HTMLButtonElement>) => void;
+    "aria-haspopup": "listbox";
+    "aria-expanded": boolean;
+    "aria-controls": string | undefined;
+    "aria-activedescendant": string | undefined;
+}
+/** The props a trigger passes straight to `<SelectListbox>` (minus the a11y name). */
+interface SelectListboxOwnProps {
+    id: string;
+    options: SelectOption[];
+    selected: string[];
+    multiple: boolean;
+    activeIndex: number;
+    anchorRect: DOMRect | null;
+    onSelect: (value: string) => void;
+    onActiveChange: (index: number) => void;
+}
+/** Everything a trigger + `<SelectListbox>` need to render a select. */
+interface UseSelectListboxResult {
+    /** Currently selected values (normalized to an array for both modes). */
+    selected: string[];
+    /** Whether the listbox is open (flips the trigger caret + `aria-expanded`). */
+    open: boolean;
+    /** Callback ref for the trigger button (merges the consumer's ref + internal). */
+    setTriggerRef: (node: HTMLButtonElement | null) => void;
+    /** id of the listbox element (the trigger's `aria-controls` target). */
+    listboxId: string;
+    /** id of the active `aria-activedescendant` row, or undefined when none. */
+    activeId: string | undefined;
+    /** ARIA + handler props to spread on the trigger button. */
+    triggerProps: SelectTriggerAriaProps;
+    /** Props to spread on `<SelectListbox>` (supply the a11y name separately). */
+    listboxProps: SelectListboxOwnProps;
+    /** Close the listbox; `restoreFocus` returns focus to the trigger. */
+    closeListbox: (restoreFocus: boolean) => void;
+    /** Resolved display text for the trigger (from `selectTriggerLabel`). */
+    text: string;
+    /** Whether `text` is the placeholder (muted) vs a real value. */
+    isPlaceholder: boolean;
+    /**
+     * Clear the selection, committing the empty value through the same
+     * controlled/uncontrolled + `onValueChange` path as a normal pick (single →
+     * `""`, multi → `[]`). Does NOT close the listbox — the caller decides. Used
+     * by Filter's Reset footer.
+     */
+    reset: () => void;
+}
+/**
+ * Trigger-agnostic orchestration for a select-style listbox widget — extracted
+ * from `Select` so alternate triggers (`InlineSelect`) reuse the exact same
+ * behavior. Owns:
+ *
+ * - selection state (controlled via `value`, uncontrolled via `defaultValue`),
+ * - `open` / `activeIndex` / `anchorRect`, the merged trigger ref,
+ * - the type-ahead buffer, reposition-on-scroll/resize, outside-`pointerdown`
+ *   close, the full keydown model (↑/↓/Home/End/Enter/Space/Escape/Tab +
+ *   type-ahead, disabled-skip, no-wrap clamp), and the select/click handlers.
+ *
+ * Focus stays on the trigger; the roving highlight lives in the portaled
+ * listbox via `aria-activedescendant` (ADR-0013 #2). The consumer supplies a
+ * `placeholder` to `selectTriggerLabel` itself if it needs the resolved text —
+ * this hook exposes the raw pieces; `text`/`isPlaceholder` are computed against
+ * the passed `placeholder` below.
+ */
+declare function useSelectListbox(options: UseSelectListboxOptions & {
+    placeholder?: string;
+}): UseSelectListboxResult;
+
+interface SelectProps extends Omit<React.ComponentProps<"button">, "value" | "defaultValue" | "onChange"> {
+    /** The options to choose from (array-of-data API, not compound children). */
+    options: SelectOption[];
+    /** Controlled selection. `string` in single mode, `string[]` in multi. */
+    value?: string | string[];
+    /** Uncontrolled initial selection. */
+    defaultValue?: string | string[];
+    /** Fires with the next selection — `string` (single) or `string[]` (multi). */
+    onValueChange?: (value: string | string[]) => void;
+    /** Single (default) vs multi select. */
+    multiple?: boolean;
+    /** `field` (bordered box, default) | `line` (bottom border only). */
+    variation?: "field" | "line";
+    /** Shown when nothing is selected. */
+    placeholder?: string;
+    /** Uppercase label above the field. */
+    label?: React.ReactNode;
+    /** Error state — destructive border/label/hint. */
+    error?: boolean;
+    /** Helper text below the field; destructive when `error`. */
+    hint?: React.ReactNode;
+    /** Leading adornment in the trigger (decorative). */
+    leadingSlot?: React.ReactNode;
+    /**
+     * Toggles the resting visibility of the bottom line on the **`line`**
+     * variation only (mirrors `Input`). Default `true` (line visible at rest).
+     * When `false`, the bottom line is hidden at rest (transparent) but still
+     * appears on focus (accent) and on error (destructive); the 1px `border-b` is
+     * kept in all cases so there is no layout shift. Has NO effect on the `field`
+     * variation.
+     */
+    showBottomLine?: boolean;
+    /** Class names for the outer wrapper (the label/field/hint stack). */
+    wrapperClassName?: string;
+    /** Class names for the trigger field row. */
+    fieldClassName?: string;
+}
+/**
+ * Select — a shared base select with a custom, portaled dropdown. Single and
+ * multi in one component; two visual variations (`field` / `line`); one `lg`
+ * size. Uncontrolled by default (`defaultValue`) with a controlled escape hatch
+ * (`value` + `onValueChange`).
+ *
+ * The trigger is a `<button>` styled as an input field (reusing `inputVariants`
+ * — the Figma Select field IS the base-input field). The dropdown is a portaled
+ * `role="listbox"` positioned from the trigger's rect, flipping above when short
+ * on room and repositioning on scroll/resize. Focus stays on the trigger via
+ * `aria-activedescendant` (no focus trap): ↑/↓/Home/End move the active row,
+ * Enter/Space toggle, Escape closes and restores focus, type-ahead jumps to a
+ * matching label, and disabled rows are skipped. `ref` is a normal React 19
+ * prop, forwarded to the trigger button.
+ *
+ * The trigger-agnostic orchestration (selection state, open/active/anchor, the
+ * keyboard model, type-ahead, reposition + outside-click) lives in the shared
+ * `useSelectListbox` hook; this component wires the hook to the field trigger +
+ * portaled listbox.
+ */
+declare function Select({ options, value: valueProp, defaultValue, onValueChange, multiple, variation, placeholder, label, error, hint, leadingSlot, showBottomLine, disabled, id: idProp, className, wrapperClassName, fieldClassName, ref, ...props }: SelectProps): React.JSX.Element;
+
+/** How the portaled panel is sized horizontally (see {@link computeListboxHorizontal}). */
+type ListboxWidthMode = "trigger" | "auto";
+/**
+ * Pure placement math for the portaled panel. Given the trigger's rect, the
+ * measured panel height, and the viewport height, decide whether the panel goes
+ * below (default) or flips above, and return the absolute `top`/`left`/`width`
+ * (in document coordinates the caller offsets by scroll).
+ *
+ * Flips above only when there is no room below AND there is room above — so a
+ * panel taller than either side stays below (then scrolls). Kept free of the
+ * DOM/React so the branch is unit-testable.
+ */
+declare function computeListboxPosition(anchor: DOMRect, listboxHeight: number, viewportHeight: number): {
+    top: number;
+    left: number;
+    width: number;
+    placement: "top" | "bottom";
+};
+/**
+ * Pure horizontal-sizing math for the portaled panel — the width/left half of
+ * placement, split out from {@link computeListboxPosition} (which owns the
+ * vertical top/flip) so each branch is unit-testable and Select's behaviour is
+ * provably untouched.
+ *
+ * - `"trigger"` (Select, default): the panel matches the trigger exactly — a
+ *   fixed pixel `width` = `anchor.width` at `left` = `anchor.left`. Byte-for-byte
+ *   what Select produced before this helper existed.
+ * - `"auto"` (InlineSelect): the panel sizes to its content. `width` is left
+ *   undefined (the caller applies `width: "max-content"` in the style), bounded
+ *   by `minWidth` = `anchor.width` (never narrower than the trigger) and
+ *   `maxWidth` = viewport − 2×margin (never wider than the viewport). `left` is
+ *   clamped into `[margin, viewportWidth − margin − measuredWidth]` so the
+ *   measured panel never overflows either edge; the lower bound wins if the
+ *   viewport is narrower than the panel (clamp collapses to `margin`).
+ */
+declare function computeListboxHorizontal(anchor: DOMRect, widthMode: ListboxWidthMode, measuredWidth: number, viewportWidth: number, margin: number): {
+    left: number;
+    width?: number;
+    minWidth?: number;
+    maxWidth?: number;
+};
+interface SelectListboxProps {
+    /** id of the listbox element (the trigger's `aria-controls` target). */
+    id: string;
+    options: SelectOption[];
+    /** Currently selected values (normalized to an array for both modes). */
+    selected: string[];
+    /** Multi-select: rows show a leading checkbox + `aria-multiselectable`. */
+    multiple: boolean;
+    /** Index of the roving `aria-activedescendant` highlight (-1 = none). */
+    activeIndex: number;
+    /** The trigger's rect, captured on open + scroll/resize (null → not placed). */
+    anchorRect: DOMRect | null;
+    /**
+     * How the panel is sized horizontally. `"trigger"` (default) matches the
+     * trigger's width/left (Select). `"auto"` sizes to content, never narrower
+     * than the trigger nor wider than the viewport, clamped inside the viewport
+     * (InlineSelect). See {@link computeListboxHorizontal}.
+     */
+    widthMode?: ListboxWidthMode;
+    /** Toggle/choose a value (single closes upstream; multi stays open). */
+    onSelect: (value: string) => void;
+    /** Move the active highlight (pointer hover keeps keyboard + mouse in sync). */
+    onActiveChange: (index: number) => void;
+    /**
+     * Optional content pinned BELOW the scrollable list (e.g. Filter's Reset
+     * button). When `undefined` the panel renders EXACTLY as before — the `<ul>`
+     * IS the portaled/positioned card (no DOM or class change for Select /
+     * InlineSelect). When provided, the card chrome moves to a wrapping panel
+     * `<div>` (a flex column): the scrolling `role="listbox"` on top and this
+     * footer pinned below, staying visible while the list scrolls under the
+     * `max-height` cap. The footer is outside the `role="listbox"` (it is not an
+     * option), so it must supply its own semantics/labels.
+     */
+    footer?: React.ReactNode;
+    /** Accessible name for the listbox (mirrors the trigger's name). */
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+}
+/**
+ * The portaled dropdown panel. Renders through `createPortal` into
+ * `document.body` (so it escapes any `overflow:hidden`/stacking ancestor),
+ * absolutely positioned from the trigger's rect via `computeListboxPosition`
+ * (matched width, below by default, flips above when short on room), capped at
+ * `LISTBOX_MAX_HEIGHT` with internal scroll.
+ *
+ * Selection semantics live on the `role="option"` rows (`aria-selected`); the
+ * multi-select checkbox is a *visual mirror* only — kept out of the tab/AT flow
+ * (`tabIndex=-1`, `aria-hidden`) so the option is the single source of truth for
+ * assistive tech. Focus never enters the panel (activedescendant pattern), so
+ * rows are chosen via `onMouseDown` (before the trigger's outside-click
+ * `pointerdown` can fire) rather than a focus-stealing click.
+ */
+declare function SelectListbox({ id, options, selected, multiple, activeIndex, anchorRect, widthMode, onSelect, onActiveChange, footer, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledby, }: SelectListboxProps): React.ReactPortal;
+
+/**
+ * Select styling — the parts of the Select that are NOT already solved by
+ * `inputVariants`. Binds ONLY to the semantic token layer (never primitives,
+ * never arbitrary values); theme switching is automatic via the `.dark` class,
+ * so no `dark:` variants are needed.
+ *
+ * The trigger's field-row styling (field/line × focus-border × error) is reused
+ * verbatim from `../input/inputVariants` — the Figma Select field IS the
+ * base-input field — so it is NOT re-declared here. This file owns only:
+ *
+ * - `selectListboxVariants` — the portaled dropdown panel (card surface).
+ * - `selectOptionVariants` — the option rows (resting / active / selected /
+ *   disabled), where "active" is the roving `aria-activedescendant` highlight
+ *   (keyboard/pointer), NOT the browser `:focus` (focus never leaves the
+ *   trigger in the activedescendant pattern).
+ */
+/**
+ * The portaled dropdown surface. A card: white background, 1px card border,
+ * 4px radius (`radius/sm`, matching the `field` trigger), and the Figma
+ * `shadow/s` drop shadow. Vertical padding gives the first/last rows breathing
+ * room; `max-height` + `overflow-y-auto` cap the list and scroll internally
+ * (the pixel cap is applied inline in `SelectListbox` alongside the measured
+ * position, since it is layout- not token-driven).
+ */
+declare const selectListboxVariants: (props?: class_variance_authority_types.ClassProp | undefined) => string;
+type SelectListboxVariantsProps = VariantProps<typeof selectListboxVariants>;
+/**
+ * Footer-mode panel chrome. When `<SelectListbox>` gets a `footer` slot the
+ * card surface (background/border/radius/shadow) moves from the `<ul>` to a
+ * wrapping panel `<div>`, so the footer can pin BELOW the scrollable list while
+ * the list scrolls under the `max-height` cap. The `<ul>` inside then carries
+ * ONLY its scroll + `py-1` inset (see `selectListboxScrollVariants`), never the
+ * chrome — keeping the no-footer path (the `<ul>` as the panel) byte-identical.
+ *
+ * The panel itself is a flex COLUMN clipping to its rounded corners
+ * (`overflow-hidden`) so the footer's top border and the list's scroll both sit
+ * inside the radius; `min-h-0` lets the `<ul>` shrink and scroll rather than
+ * push the footer out of the capped panel.
+ */
+declare const selectListboxPanelVariants: (props?: class_variance_authority_types.ClassProp | undefined) => string;
+/**
+ * The scrolling `<ul>` when it lives INSIDE a footer panel: it owns the scroll
+ * and the `py-1` inset (moved off the panel chrome above), and `min-h-0` +
+ * `flex-1` so it takes the remaining height and scrolls under the cap while the
+ * footer stays pinned. No card chrome here — the panel owns it.
+ */
+declare const selectListboxScrollVariants: (props?: class_variance_authority_types.ClassProp | undefined) => string;
+/**
+ * The pinned footer region under the list (Filter's Reset row). A top divider
+ * (`border-t-card-border`) separates it from the scrolling list; it never
+ * scrolls. Horizontal padding matches an option row's inset (`px-3`) so the
+ * footer's content left-aligns with the option labels.
+ */
+declare const selectListboxFooterVariants: (props?: class_variance_authority_types.ClassProp | undefined) => string;
+/**
+ * An option row. Layout is a horizontal flex row (leading checkbox in multi);
+ * typography is `body-03` (Archivo 14/20). Colours bind to the Figma
+ * `selectable-list-item` (node 4921:8203) tokens — the **card/neutral** family
+ * (this is content on a card surface), NOT the `input-*` family the trigger
+ * borrows: resting text `text-foreground`, disabled text `text-foreground-muted`
+ * (the row is also skipped by keyboard nav in `Select`). The `active` state is
+ * the keyboard/pointer highlight driven by `aria-activedescendant` — it fills
+ * with `bg-card-accent` (Figma `card/neutral/normal/accent`) so the highlight
+ * reads as "this row is targeted".
+ *
+ * `selected` differs by mode (`multiple`):
+ * - **single**: the single-select selected state — a brand-tinted row
+ *   (`bg-card-brand-accent`), a 3px left accent bar
+ *   (`border-l-3 border-l-card-brand-border-accent`), and brand foreground text
+ *   (`text-card-brand-foreground`). NO trailing check — the fill + bar are the
+ *   affordance. This wins over the neutral `active` highlight so a selected row
+ *   stays branded on hover.
+ * - **multi**: no row tint — the leading checkbox carries the selected look
+ *   (matching the Figma multiselect/selected state), and the neutral `active`
+ *   highlight still applies on hover.
+ */
+declare const selectOptionVariants: (props?: ({
+    active?: boolean | null | undefined;
+    selected?: boolean | null | undefined;
+    multiple?: boolean | null | undefined;
+    disabled?: boolean | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+type SelectOptionVariantsProps = VariantProps<typeof selectOptionVariants>;
+
+export { type ListboxWidthMode, Select, SelectListbox, type SelectListboxOwnProps, type SelectListboxProps, type SelectListboxVariantsProps, SelectOption, type SelectOptionVariantsProps, type SelectProps, type SelectTriggerAriaProps, type UseSelectListboxOptions, type UseSelectListboxResult, computeListboxHorizontal, computeListboxPosition, nextEnabledIndex, selectListboxFooterVariants, selectListboxPanelVariants, selectListboxScrollVariants, selectListboxVariants, selectOptionVariants, useSelectListbox };