@sesamehr/react-design-system 2.0.0-beta.6 → 2.0.0-beta.7

package/dist/Forms/Inputs/InputPassword/InputPassword.d.ts

@@ -15,6 +15,14 @@ export interface InputPasswordProps extends Omit<React.HTMLAttributes<HTMLDivEle
  * InputPassword root — mirrors `@sesame/orxata-core` InputPassword.
  * Provides the value and clear-text state to `InputPasswordInput` and
  * `InputPasswordToggle` through context.
- * Both `field` and `visible` work controlled or uncontrolled.
+ *
+ * Both `field` and `visible` work controlled or uncontrolled, and which one
+ * you get depends on **whether the change handler is there, not whether the
+ * value is**. The Vue original is a pair of `defineModel`s, and a
+ * `defineModel` given a value but no listener keeps driving itself. Gate on
+ * the value alone and `visible={false}` — a perfectly ordinary way to say
+ * "start hidden" — turns the reveal toggle into a dead button: `toggle()`
+ * computes the next state, declines to store it because the prop is present,
+ * and calls a handler nobody passed.
  */
 export declare const InputPassword: import('react').ForwardRefExoticComponent<InputPasswordProps & import('react').RefAttributes<HTMLDivElement>>;

package/dist/Forms/Inputs/InputText/InputText.d.ts

@@ -12,5 +12,14 @@ export interface InputTextProps extends Omit<React.InputHTMLAttributes<HTMLInput
  * `field` + `onFieldChange` are the controlled pair; native `value`/`onChange`
  * still pass through via `...props` for anyone who prefers them. `type`
  * defaults to `'text'`, and a `type` passed by the caller wins.
+ *
+ * **`field` alone does not mean "controlled" — `field` *with* `onFieldChange`
+ * does.** The Vue original is a `defineModel`, and a `defineModel` only hands
+ * control to the parent when the parent actually listens; given a value and no
+ * listener it seeds its own state and goes on working. Port `field` as
+ * unconditionally controlled and that same usage becomes an input pinned to
+ * its initial value with nothing able to change it — one that silently will
+ * not accept a keystroke. Which is exactly what `<OxInputText field="" />`
+ * did, in the story and in any app that wrote it.
  */
 export declare const InputText: import('react').ForwardRefExoticComponent<InputTextProps & import('react').RefAttributes<HTMLInputElement>>;

package/dist/Forms/Inputs/SearchBar/useSearchDelay.d.ts

@@ -2,7 +2,7 @@
  * The quiet period between typing and searching — mirrors
  * `@sesame/orxata-core` `useSearchDelay`.
  *
- * A search field that emits on every keystroke turns "María" into five
+ * A search field that emits on every keystroke turns "Marie" into five
  * requests, four of which are already stale by the time they land. Waiting for
  * typing to stop collapses them into one.
  *

package/dist/Forms/Inputs/SearchPanel/SearchPanel.d.ts

@@ -0,0 +1,71 @@
+import { Command } from 'cmdk';
+export interface SearchPanelProps extends Omit<React.ComponentPropsWithoutRef<typeof Command>, 'value' | 'onValueChange' | 'onSelect'> {
+    /** A row was chosen — by click or by Enter. Carries that row's `value`. */
+    onSelect?: (value: string) => void;
+    /** Escape was pressed. What closing means is the caller's to decide. */
+    onClose?: () => void;
+    dataTestid: string;
+}
+/**
+ * A panel of search results, grouped under headings — the command-palette
+ * pattern. Choosing a row runs something: it navigates, opens a document, or
+ * fires an action.
+ *
+ * Named for what it is rather than what it shows. It was `SearchResults`, which
+ * described the one thing it does not do: it does not search, does not filter
+ * and produces no results — the caller supplies the rows. What it *is* is the
+ * surface searching happens on, a field above a grouped list, and `SearchPanel`
+ * promises nothing it cannot keep.
+ *
+ * `Menu` was the other candidate and is wrong for a reason worth writing down:
+ * in ARIA a `menu` is application commands with their own keyboard model, and
+ * this is a `listbox`. A component called `Menu` that renders `role="listbox"`
+ * invites the next reader to resolve the mismatch in the wrong direction.
+ *
+ * **This card is the field, and nothing else.** Collapsed it is exactly the
+ * search row with the same air above it as below; the results are not in it.
+ * `SearchPanelList` draws its own card and floats it over the page, tethered
+ * to this one — so a result arriving moves nothing below the panel, which is
+ * the whole reason a global search can live in a header. See that file for how
+ * the two are made to read as one surface.
+ *
+ * `Popover.Root` is pinned open and holds no state: the caller decides whether
+ * the list renders at all, so there is no second open state here. What it is
+ * for is the anchor — the card below is the box the list positions itself
+ * against, flips away from and takes its width from.
+ *
+ * **The list brings its own motion**, because the popper gives it a
+ * `data-state` and the shared surface animates on that. Do not wrap it in an
+ * `OxTransition*`: those animate a box growing in the flow, which is the
+ * behaviour this component was changed to stop, and their enter class would be
+ * competing with the surface's own keyframe for the `animation` property.
+ *
+ * Deliberately not a `Combobox`. A combobox's model is "pick a value, the
+ * field then shows it", which is wrong here twice over — the search box must
+ * keep the words the user typed, and a row that ran an action is not a value
+ * anything holds afterwards. Bending a combobox to this shape means clearing
+ * the value after every pick and suppressing the selected state, and the bug
+ * that arrives three months later is the one where a stale selection survives
+ * a reset. shadcn keeps `Command` apart from `Combobox` for the same reason.
+ *
+ * So this root reports `onSelect` and holds nothing. cmdk's own `value` is the
+ * *highlight*, not a selection, which is exactly the model wanted: no row is
+ * ever checked and no row draws a check.
+ *
+ * `shouldFilter` is off. The caller already has the term — `OxSearchBar` owns
+ * the debounce — and whether a result matches is a question about their data,
+ * not about the strings in the DOM.
+ *
+ * The component knows nothing about what is in it. The headings, the icons and
+ * the row contents are all `children`: a caller listing employees with avatars
+ * and files with sizes needs nothing here to change. The categories in the
+ * stories are one application's, not this package's.
+ *
+ * The keyboard comes from cmdk: arrows and Home/End move the highlight while
+ * focus stays in the search field, Enter runs the highlighted row, and
+ * `aria-activedescendant` keeps a screen reader in step. Focusing the field
+ * highlights the first row, so Enter on a fresh panel runs the top hit without
+ * arrowing to it — which also means the first arrow press moves to the
+ * *second* row. Escape is cmdk's one gap and is handled here.
+ */
+export declare const SearchPanel: import('react').ForwardRefExoticComponent<SearchPanelProps & import('react').RefAttributes<HTMLDivElement>>;

package/dist/Forms/Inputs/SearchPanel/SearchPanelEmpty.d.ts

@@ -0,0 +1,16 @@
+export type SearchPanelEmptyProps = React.ComponentPropsWithoutRef<'div'>;
+/**
+ * Shown in place of the rows when a search found nothing.
+ *
+ * No default text. "No results found" is English, and which of the caller's
+ * words belong here — and in which language — is not this package's to guess;
+ * `OxComboboxEmpty` carries one for backwards compatibility and that is the
+ * exception, not the pattern. Rendering is the caller's condition too: only
+ * they know whether an empty list means "nothing matched" or "nothing typed
+ * yet".
+ *
+ * Deliberately not cmdk's `CommandEmpty`, which decides for itself when to
+ * appear by counting the items its own filter left — and this panel's filter
+ * is the caller's.
+ */
+export declare const SearchPanelEmpty: import('react').ForwardRefExoticComponent<Omit<import('react').DetailedHTMLProps<import('react').HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & import('react').RefAttributes<HTMLDivElement>>;

package/dist/Forms/Inputs/SearchPanel/SearchPanelGroup.d.ts

@@ -0,0 +1,14 @@
+import { CommandGroup } from 'cmdk';
+export interface SearchPanelGroupProps extends React.ComponentPropsWithoutRef<typeof CommandGroup> {
+    /** The heading above the rows. Anything renderable, and always the caller's. */
+    label?: React.ReactNode;
+}
+/**
+ * A heading and the rows under it.
+ *
+ * Nothing here knows what the heading might say. "Documents", "Recent
+ * conversations", "People" are one application's categories on one day; a
+ * design system that shipped an enum of them would be wrong by the following
+ * release, and wrong for every other application immediately.
+ */
+export declare const SearchPanelGroup: import('react').ForwardRefExoticComponent<SearchPanelGroupProps & import('react').RefAttributes<HTMLDivElement>>;

package/dist/Forms/Inputs/SearchPanel/SearchPanelInput.d.ts

@@ -0,0 +1,31 @@
+import { CommandInput } from 'cmdk';
+export type SearchPanelInputProps = Omit<React.ComponentPropsWithoutRef<typeof CommandInput>, 'asChild'>;
+/**
+ * Joins the caller's search field to the list's keyboard.
+ *
+ * Put exactly one control inside — `OxSearchBar` is the intended one, since it
+ * already owns the debounce. `asChild` hands it the arrow/Home/End/Enter
+ * handlers and `aria-activedescendant`, so the highlight moves through the
+ * rows while focus never leaves the field. Radix's `Slot`, which cmdk uses,
+ * throws on a second child rather than quietly merging onto the first.
+ *
+ * This renders no field of its own on purpose. A results panel is a way of
+ * showing what a search found, not a second opinion about what a search box
+ * looks like.
+ *
+ * It does render the row the field sits in, which is a different thing: the
+ * design draws a padded title row across the top of the panel, and `asChild`
+ * alone would have put that padding on the caller's search bar — where it would
+ * have moved the field's own border in from the panel edge instead of insetting
+ * the row.
+ *
+ * Two things cmdk decides that the field cannot override, because it writes
+ * them *after* the spread: the control becomes `type="text"` rather than
+ * `type="search"`, and it is given `role="combobox"` with `aria-controls` and
+ * `aria-activedescendant`. Neither is a problem — the only thing `type=search`
+ * adds is the browser's own clear button, which `OxSearchBar` hides and
+ * redraws anyway, and a text field that owns a list of options is what the
+ * combobox role is for, whatever the panel above it is called. It is a real
+ * difference from the Vue port, where the field keeps `type="search"`.
+ */
+export declare const SearchPanelInput: import('react').ForwardRefExoticComponent<SearchPanelInputProps & import('react').RefAttributes<HTMLInputElement>>;

package/dist/Forms/Inputs/SearchPanel/SearchPanelItem.d.ts

@@ -0,0 +1,20 @@
+import { CommandItem } from 'cmdk';
+export interface SearchPanelItemProps extends Omit<React.ComponentPropsWithoutRef<typeof CommandItem>, 'value' | 'onSelect'> {
+    /** Handed back through the panel's `onSelect`. Unique within the panel. */
+    value: string;
+    disabled?: boolean;
+}
+/**
+ * One result. Choosing it makes the panel call `onSelect` with this `value`.
+ *
+ * No check indicator, and that is the point: nothing here is selected in the
+ * sense a `Select` option is. The row is a thing you run, so it never becomes
+ * the panel's current answer and never grows a tick beside it. The shared row
+ * only leaves room on the right when an indicator is passed, so these sit
+ * flush.
+ *
+ * Whatever goes inside is the caller's — an icon and a label, an avatar and
+ * two lines, a filename and a size. `value` is the only thing this package
+ * wants, and only so it has something to hand back.
+ */
+export declare const SearchPanelItem: import('react').ForwardRefExoticComponent<SearchPanelItemProps & import('react').RefAttributes<HTMLDivElement>>;

package/dist/Forms/Inputs/SearchPanel/SearchPanelList.d.ts

@@ -0,0 +1,42 @@
+import { CommandList } from 'cmdk';
+export type SearchPanelListProps = React.ComponentPropsWithoutRef<typeof CommandList>;
+/**
+ * The scrolling list of groups and rows — `role="listbox"` and the rows in it —
+ * on a card that floats over the page.
+ *
+ * **It floats, and that is the point.** In the flow it pushed everything below
+ * the panel down the moment an answer landed, which is not what a dropdown does
+ * and is disqualifying for a search that lives in a header. The card is
+ * positioned by Radix's popper against the anchor `SearchPanel` wraps around
+ * itself, so it is exactly the field's width, it flips above the field when
+ * there is no room below, and it is `position: fixed` — no ancestor's
+ * `overflow` can clip it.
+ *
+ * **No portal, and that is also the point.** Everything the keyboard is made of
+ * is a relationship between this list and the field above it: cmdk gathers the
+ * rows by querying the `Command` element they sit inside, `aria-activedescendant`
+ * on the field points at a row's `id`, and the panel's custom properties reach
+ * the rows by inheriting down the tree. A `Popover.Portal` would move the rows
+ * out of `Command` entirely, and the arrows would stop finding them.
+ * Popper-positioned content does not need a portal to escape the flow —
+ * `position: fixed` already does — so it does not get one.
+ *
+ * The two auto-focus events are prevented for the same reason. A popover
+ * focuses its content when it opens and hands focus back when it closes; both
+ * would take focus off the search field, which is the one thing the arrow keys
+ * depend on. `role="presentation"` and the blanked `aria-labelledby` finish the
+ * job: the primitive believes it is a dialog, a screen reader must not, and the
+ * name it points at belongs to a trigger this panel does not have. Radix
+ * spreads the caller's props *after* its own `role`, so saying so here is
+ * enough — the Vue port has to write the same two attributes one level further
+ * down, where reka merges last.
+ */
+export declare const SearchPanelList: import('react').ForwardRefExoticComponent<Omit<{
+    children?: React.ReactNode;
+} & Pick<Pick<import('react').DetailedHTMLProps<import('react').HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "key" | keyof import('react').HTMLAttributes<HTMLDivElement>> & {
+    ref?: React.Ref<HTMLDivElement>;
+} & {
+    asChild?: boolean;
+}, "asChild" | "key" | keyof import('react').HTMLAttributes<HTMLDivElement>> & {
+    label?: string;
+} & import('react').RefAttributes<HTMLDivElement>, "ref"> & import('react').RefAttributes<HTMLDivElement>>;

package/dist/Forms/Inputs/SearchPanel/context.d.ts

@@ -0,0 +1,11 @@
+export interface SearchPanelContextValue {
+    /** Called with a row's `value` when that row is chosen. */
+    select: (value: string) => void;
+}
+export declare const SearchPanelContext: import('react').Context<SearchPanelContextValue | null>;
+/**
+ * The Vue port reaches the root through reka's own listbox context; React has
+ * no equivalent to inject, so the root publishes one. The error message
+ * matches the Vue side's on purpose.
+ */
+export declare const useSearchPanelContext: () => SearchPanelContextValue;

package/dist/Forms/Inputs/SearchPanel/index.d.ts

@@ -0,0 +1,6 @@
+export { SearchPanel, type SearchPanelProps } from './SearchPanel.tsx';
+export { SearchPanelEmpty, type SearchPanelEmptyProps, } from './SearchPanelEmpty.tsx';
+export { SearchPanelGroup, type SearchPanelGroupProps, } from './SearchPanelGroup.tsx';
+export { SearchPanelInput, type SearchPanelInputProps, } from './SearchPanelInput.tsx';
+export { SearchPanelItem, type SearchPanelItemProps, } from './SearchPanelItem.tsx';
+export { SearchPanelList, type SearchPanelListProps, } from './SearchPanelList.tsx';

package/dist/Forms/Inputs/Select/SelectContent.d.ts

@@ -7,5 +7,11 @@ export interface SelectContentProps extends Omit<React.ComponentPropsWithoutRef<
 /**
  * The floating list. Always positioned against the trigger rather than over it,
  * so the popup matches the trigger's width and never covers it.
+ *
+ * `asChild` hands the primitive's positioning, `data-state` and `data-side` to
+ * the shared `Surface`, which is the one element `Popover`, `Select`,
+ * `Combobox` and `SearchPanel` may have in common. Exactly one child sits at
+ * each slot position — Radix's `Slot` throws on a second, which is the whole
+ * reason the arrangement is safe to read at a glance.
  */
 export declare const SelectContent: import('react').ForwardRefExoticComponent<SelectContentProps & import('react').RefAttributes<HTMLDivElement>>;

package/dist/Forms/Inputs/Select/SelectGroup.d.ts

@@ -1,7 +1,11 @@
 import * as SelectPrimitive from '@radix-ui/react-select';
 export interface SelectGroupProps extends React.ComponentPropsWithoutRef<typeof SelectPrimitive.Group> {
-    /** Optional group heading. */
-    label?: string;
+    /**
+     * The group heading. A node rather than a string: it is the caller's word
+     * for their own category, and taking it as text would decide for them that
+     * it can only ever be text.
+     */
+    label?: React.ReactNode;
 }
 /** Groups related options under a heading, announced as a group label. */
 export declare const SelectGroup: import('react').ForwardRefExoticComponent<SelectGroupProps & import('react').RefAttributes<HTMLDivElement>>;

package/dist/Forms/Inputs/Select/SelectItem.d.ts

@@ -6,6 +6,12 @@ export interface SelectItemProps extends React.ComponentPropsWithoutRef<typeof S
 /**
  * A single option.
  *
+ * `asChild` hands Radix's item behaviour — `role="option"`, `data-highlighted`,
+ * `data-state`, typeahead, selection — to the shared row, which is the one
+ * thing `Select`, `Combobox` and `SearchPanel` may share. The primitive
+ * itself is not shared: this one and `Combobox`'s wrap different roots and
+ * swapping them breaks the keyboard in both.
+ *
  * The rendered text is published to the root on mount so the trigger's render
  * prop can name the selection. Reading it off the DOM keeps arbitrary markup
  * working, and it runs while the list is closed too: the primitive keeps items

package/dist/Forms/Inputs/Textarea/Textarea.d.ts

@@ -0,0 +1,69 @@
+import { ReactNode } from 'react';
+import { TextareaCounterState } from './index.ts';
+export interface TextareaProps extends Omit<React.TextareaHTMLAttributes<HTMLTextAreaElement>, 'rows' | 'children'> {
+    /**
+     * How tall the surface may grow before it starts to scroll, counted in lines
+     * of text.
+     *
+     * In rows rather than pixels so the cap moves with the line height instead
+     * of cutting a row in half the first time anyone changes the type scale. The
+     * default is the design's 100px box, which is four 20px lines inside its own
+     * padding.
+     */
+    maxRows?: number;
+    /** Controlled value. Pair with `onFieldChange`; omit for uncontrolled. */
+    field?: string;
+    /** Called on every input with the next value. */
+    onFieldChange?: (value: string) => void;
+    /**
+     * Bottom-right inside the box. A node, or a render prop called with
+     * `{ value, length }` — the limit is the caller's business and the count is
+     * the value's, so neither is a prop.
+     */
+    counter?: ReactNode | ((state: TextareaCounterState) => ReactNode);
+    dataTestid: string;
+}
+/**
+ * The multi-line field: a `<textarea>` in the same box the single-line
+ * controls draw, that grows with its content and then scrolls.
+ * Mirrors `@sesame/orxata-core` Textarea.
+ *
+ * **Not `OxChatInput`.** That one is a chat composer — it owns a send
+ * contract, Enter submits, and it draws two corners of action buttons around
+ * the text. This one is a form field: it has no idea what happens to the
+ * value, Enter inserts a newline, and it sits inside an `<OxFieldGroup>` with
+ * a label above it and a message below. Reach for `OxChatInput` when the value
+ * is a message being sent somewhere; reach for this when the value is an
+ * answer on a form. They share `useAutoGrow` and nothing else, which is the
+ * only part of the two that is genuinely the same problem.
+ *
+ * **The label and the message are not here, and that is the point.**
+ * `<OxFieldLabel>` and `<OxFieldMessage>` already exist, already order
+ * themselves around a control, and — through `useFieldControl` below — already
+ * carry the `id`, `aria-invalid` and `aria-describedby` that tie the three
+ * together. A `label` prop would be a second, worse spelling of a component
+ * that is already in the package, and the design system ships no strings
+ * anyway.
+ *
+ * ```tsx
+ * <OxFieldGroup variant="error">
+ *   <OxFieldLabel>Notes</OxFieldLabel>
+ *   <OxTextarea field={notes} onFieldChange={setNotes} dataTestid="notes" />
+ *   <OxFieldMessage>Keep it under 100 characters.</OxFieldMessage>
+ * </OxFieldGroup>
+ * ```
+ *
+ * **`field` alone does not mean "controlled" — `field` *with* `onFieldChange`
+ * does.** The Vue original is a `defineModel`, and a `defineModel` only hands
+ * control to the parent when the parent actually listens; given a value and no
+ * listener it seeds its own state and goes on working. Port `field` as
+ * unconditionally controlled and the same usage becomes a field pinned to its
+ * initial value that silently will not accept a keystroke.
+ *
+ * The `ref` is the **textarea**, not the box — which is where it differs from
+ * `OxChatInput`, whose ref is its root. This is a form control: what a caller
+ * reaches for a ref to do is focus it, select in it, or hand it to a form
+ * library. `className` still lands on the box, since the box is what reads as
+ * the control.
+ */
+export declare const Textarea: import('react').ForwardRefExoticComponent<TextareaProps & import('react').RefAttributes<HTMLTextAreaElement>>;

package/dist/Forms/Inputs/Textarea/index.d.ts

@@ -0,0 +1,21 @@
+export { Textarea, type TextareaProps } from './Textarea.tsx';
+/**
+ * What the `counter` slot is handed.
+ *
+ * Both numbers come from the field rather than from the caller, so a counter
+ * works the same whether the value is controlled or left to the textarea — an
+ * uncontrolled field posting itself in a plain `<form>` has no value in the
+ * caller's scope to count.
+ *
+ * There is no `cva` here on purpose. `Textarea` has no variants: the design
+ * draws one box, and its states come from `OxFieldGroup` through the
+ * `--controller-*` properties rather than from a class this component picks.
+ * An empty variant map would be one more thing to keep in step across two
+ * packages in exchange for nothing.
+ */
+export interface TextareaCounterState {
+    /** The text the field holds now. */
+    value: string;
+    /** How many characters that is — what `<OxCounter>` wants for its `value`. */
+    length: number;
+}

package/dist/Forms/Inputs/Toggle/RadioButton/RadioGroup.d.ts

@@ -5,5 +5,10 @@ export interface RadioGroupProps extends React.ComponentPropsWithoutRef<typeof R
 /**
  * RadioGroup — built on `@radix-ui/react-radio-group`.
  * `v-model` maps to Radix `value` / `onValueChange` (+ `defaultValue`).
+ *
+ * The group is what a field names, not the radios inside it: one id cannot sit
+ * on several `<button role="radio">`s at once, so `RadioButton` stays out of
+ * the field context and this root carries `aria-labelledby` instead. Radix
+ * gives it `role="radiogroup"`, which is what makes that name land.
  */
 export declare const RadioGroup: import('react').ForwardRefExoticComponent<RadioGroupProps & import('react').RefAttributes<HTMLDivElement>>;

package/dist/Forms/Inputs/Toggle/ToggleLabel/ToggleLabel.d.ts

@@ -1,5 +1,14 @@
 export interface ToggleLabelProps extends React.LabelHTMLAttributes<HTMLLabelElement> {
     htmlFor?: string;
 }
-/** ToggleLabel — mirrors `@sesame/orxata-core` ToggleLabel. */
+/**
+ * ToggleLabel — mirrors `@sesame/orxata-core` ToggleLabel.
+ *
+ * `htmlFor` falls back to whichever control claimed the surrounding
+ * `<OxFieldGroup>`'s id, because the commonest checkbox layout in the system —
+ * a field wrapping an `<OxToggleGroup>` wrapping a toggle and this — would
+ * otherwise leave the toggle's own label naming nothing. It does not take the
+ * group's `labelId`: `OxFieldLabel` already carries that, and two elements
+ * cannot share an id.
+ */
 export declare const ToggleLabel: import('react').ForwardRefExoticComponent<ToggleLabelProps & import('react').RefAttributes<HTMLLabelElement>>;

package/dist/Forms/Inputs/index.d.ts

@@ -5,6 +5,10 @@ export * from './InputPassword/index.ts';
 export * from './InputOtp/index.ts';
 export * from './Calendar/index.ts';
 export * from './Combobox/index.ts';
+export * from './ChatInput/index.ts';
+export * from './DatePicker/index.ts';
 export * from './SearchBar/index.ts';
+export * from './SearchPanel/index.ts';
 export * from './Select/index.ts';
+export * from './Textarea/index.ts';
 export * from './Toggle/index.ts';

package/dist/Layout/Scrollbar/Scrollbar.d.ts

@@ -0,0 +1,46 @@
+import { ScrollbarPort } from './useScrollbar.ts';
+export interface ScrollbarProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children'> {
+    /**
+     * The element that scrolls. Everything is measured from it, and its native
+     * scrollbar is hidden for as long as this one is drawn over it.
+     */
+    port?: ScrollbarPort;
+    dataTestid: string;
+}
+/**
+ * An overlay scrollbar for a container that scrolls vertically, drawn instead
+ * of the browser's own. Mirrors `@sesame/orxata-core` Scrollbar.
+ *
+ * Reach for it where the native bar cannot say what it needs to say. A
+ * virtualised table is the case it was built for: the bar has to start below
+ * the column names, and the native one runs the full height of the scrollport
+ * because the scrollport contains the header. A chat composer that grows to a
+ * few lines and then scrolls is the other: a native bar there is a strip of
+ * system chrome inside a rounded box, and in the browsers that reserve a gutter
+ * it shifts the text sideways the moment the field overflows.
+ *
+ * It behaves the way an overlay bar does: out of the way until you scroll or
+ * reach for the edge, and gone again shortly after. The track takes no clicks —
+ * only the thumb does — so the strip down the right of the content stays live.
+ *
+ * **Placement is the parent's.** This positions itself absolutely inside the
+ * nearest positioned ancestor and reads four custom properties for where that
+ * is, all with fallbacks that spell "fill the containing block down its right
+ * edge": `--scrollbar-top` (`0px`), `--scrollbar-right` (`0px`),
+ * `--scrollbar-left` (`auto`) and `--scrollbar-height` (`100%`).
+ *
+ * A parent whose scrollport *is* the containing block sets none of them. One
+ * that has to compensate for something — a header inside the scrollport, an
+ * `offsetParent` that is not the scrollport — works the numbers out itself and
+ * writes them here, which is why none of that arithmetic is a prop.
+ *
+ * Vertical only, deliberately. Horizontal overflow is read from the content
+ * running out of room and from the shadows at the edges; nothing in the system
+ * wants a second bar, and adding one later takes nothing away.
+ *
+ * The bar is `aria-hidden`: it is a picture of a scroll position, and the
+ * scrollport it belongs to is already reachable and scrollable from the
+ * keyboard. `mousedown`/`mousemove` are what drive the thumb, so a coarse
+ * pointer gets nothing from it and keeps the native scrolling it already had.
+ */
+export declare const Scrollbar: import('react').ForwardRefExoticComponent<ScrollbarProps & import('react').RefAttributes<HTMLDivElement>>;

package/dist/Layout/Scrollbar/index.d.ts

@@ -0,0 +1,2 @@
+export { Scrollbar, type ScrollbarProps } from './Scrollbar.tsx';
+export { useScrollbar, SCROLLBAR_THICKNESS, type ScrollbarPort, type UseScrollbarReturn, } from './useScrollbar.ts';

package/dist/Layout/Scrollbar/useScrollbar.d.ts

@@ -0,0 +1,52 @@
+import { RefObject } from 'react';
+/**
+ * The track's own width, `w-3`.
+ *
+ * Exported because a parent that places the bar by its *left* edge has to pull
+ * it back by the full width to sit inside the scrollport rather than alongside
+ * it, and the number it pulls back by has to be the one the stylesheet uses.
+ */
+export declare const SCROLLBAR_THICKNESS = 12;
+/**
+ * The element that scrolls, as a ref or as the element itself. A ref because
+ * that is what a parent normally has, and a `useRef` never re-renders anything
+ * when it fills in.
+ */
+export type ScrollbarPort = RefObject<HTMLElement | null> | HTMLElement | null | undefined;
+export interface UseScrollbarReturn {
+    /** Shown while scrolling, while dragging, and near the right edge. */
+    visible: boolean;
+    /** The thumb is being dragged. */
+    dragging: boolean;
+    /** The pointer is in the strip the bar occupies, so the bar widens. */
+    near: boolean;
+    /** Where the thumb goes, in pixels. A height of zero means no thumb at all. */
+    thumb: {
+        top: number;
+        height: number;
+    };
+    /** Recompute the thumb from the port's current scroll metrics. */
+    measure: () => void;
+    /** `onMouseDown` on the thumb. */
+    startDrag: (event: React.MouseEvent) => void;
+    /** `onMouseEnter` on the thumb. See `near`. */
+    approach: () => void;
+}
+/**
+ * The behaviour of an overlay scrollbar, with no opinion about where it sits.
+ * Mirrors `@sesame/orxata-core` useScrollbar.
+ *
+ * Geometry only goes one way here: the track is positioned and sized by CSS,
+ * and this reads back the height it ended up with. That is what keeps the
+ * placement out — a virtualised table subtracts its `<thead>` and compensates
+ * for an `offsetParent`, a chat composer does neither, and neither of those
+ * facts has to be expressible here for both to work.
+ *
+ * Both elements are watched for resize, which is also what makes the
+ * measurement land in the right frame: a `<textarea>` that auto-grows writes
+ * its own height, the track follows it, and the resize callback runs after that
+ * write and before the paint. That matters more here than on the Vue side —
+ * a child's effects run before its parent's, so the bar cannot be ordered
+ * after the growth by declaration order alone.
+ */
+export declare const useScrollbar: (port: ScrollbarPort, track: RefObject<HTMLElement | null>) => UseScrollbarReturn;

package/dist/hooks/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Hooks shared by more than one component — the React side of the Vue
+ * package's `src/composables/`, which is the rename the parity rules apply
+ * (`composables` ↔ `hooks`, see `packages/eslint-plugin/src/parity/compare.js`).
+ *
+ * A hook lives beside its component until a second one needs it; at that point
+ * it belongs here, because the alternative is a component importing out of a
+ * sibling's folder and a reader having to know that `Textarea`'s sizing is
+ * really `ChatInput`'s. See `.claude/rules/component-architecture.md` §13.
+ */
+export { useAutoGrow } from './useAutoGrow.ts';
+export type { UseAutoGrowReturn } from './useAutoGrow.ts';

package/dist/hooks/useAutoGrow.d.ts

@@ -0,0 +1,22 @@
+import { RefObject } from 'react';
+export interface UseAutoGrowReturn {
+    /** Re-measure and re-apply the height. Cheap; call it on every keystroke. */
+    resize: () => void;
+}
+/**
+ * Grows a `<textarea>` with its content up to `maxRows`, then lets it scroll.
+ * Mirrors `@sesame/orxata-core` useAutoGrow.
+ *
+ * Measuring is the whole trick and it has one rule: the height has to be
+ * cleared before `scrollHeight` is read. `scrollHeight` never reports less
+ * than the element's own height, so measuring against the height left over
+ * from the previous keystroke makes the field a one-way ratchet — it grows
+ * when text is added and never shrinks when it is deleted.
+ *
+ * The cap is applied here rather than as a CSS `max-height` so that the
+ * overflow can be switched with it. A permanently scrollable textarea shows a
+ * scrollbar gutter in the browsers that reserve one, which moves the text by a
+ * few pixels for as long as the field is a single line — visible, and wrong
+ * against a design that has no scrollbar in it.
+ */
+export declare const useAutoGrow: (element: RefObject<HTMLTextAreaElement | null>, value: string, maxRows: number) => UseAutoGrowReturn;

package/dist/internal/Listbox/ListboxEmpty.d.ts

@@ -0,0 +1,3 @@
+export type ListboxEmptyProps = React.ComponentPropsWithoutRef<'div'>;
+/** Shown in place of the rows when a search matched nothing. Internal. */
+export declare const ListboxEmpty: import('react').ForwardRefExoticComponent<Omit<import('react').DetailedHTMLProps<import('react').HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & import('react').RefAttributes<HTMLDivElement>>;

package/dist/internal/Listbox/ListboxItem.d.ts

@@ -0,0 +1,23 @@
+export interface ListboxItemProps extends React.ComponentPropsWithoutRef<'div'> {
+    /**
+     * The check mark, for lists that have one. Pass it — even as a fragment that
+     * renders nothing while the row is unchecked — and the row reserves the space
+     * on its right; leave it out and the row sits flush.
+     */
+    indicator?: React.ReactNode;
+}
+/**
+ * One row of a list: `Select`'s option, `Combobox`'s option, `SearchPanel`'
+ * result. Port of `core/src/internal/Listbox/ListboxItem`.
+ *
+ * Whether the row leaves room on the right is decided by the presence of the
+ * `indicator` prop, not by whether the row is currently checked — a list with
+ * check marks always passes it and a list without one never does, so the gap
+ * is stable instead of appearing the moment a row becomes checked.
+ *
+ * The indicator wrapper is rendered here rather than left to the caller so the
+ * positioning lives in one file. That matters less in React than in Vue, where
+ * scoped CSS would simply not reach an element authored elsewhere, but keeping
+ * the two ports the same shape is what makes them comparable.
+ */
+export declare const ListboxItem: import('react').ForwardRefExoticComponent<ListboxItemProps & import('react').RefAttributes<HTMLDivElement>>;

package/dist/internal/Listbox/ListboxLabel.d.ts

@@ -0,0 +1,9 @@
+export type ListboxLabelProps = React.ComponentPropsWithoutRef<'div'>;
+/**
+ * The heading above a group of rows. Internal — see `Surface.tsx`.
+ *
+ * Content is `children`, never a string prop: the heading is the caller's word
+ * for their own category, and a design system that took it as a prop would be
+ * deciding how it can be written.
+ */
+export declare const ListboxLabel: import('react').ForwardRefExoticComponent<Omit<import('react').DetailedHTMLProps<import('react').HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & import('react').RefAttributes<HTMLDivElement>>;

package/dist/internal/Listbox/ListboxSeparator.d.ts

@@ -0,0 +1,3 @@
+export type ListboxSeparatorProps = React.ComponentPropsWithoutRef<'div'>;
+/** The rule between two groups of rows. Internal — see `Surface.tsx`. */
+export declare const ListboxSeparator: import('react').ForwardRefExoticComponent<Omit<import('react').DetailedHTMLProps<import('react').HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & import('react').RefAttributes<HTMLDivElement>>;