prime-ui-kit 0.14.0 → 0.16.0

package/dist/internal/RowAction.d.ts

@@ -0,0 +1,26 @@
+import * as React from "react";
+import { type TooltipSide } from "../components/tooltip/Tooltip";
+import { type ControlSize } from "./states";
+type RowActionProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "children" | "aria-label" | "type"> & {
+    /** Accessible name and tooltip of the action («Копировать», «Создать задачу»). */
+    label: string;
+    /** The tier of the row; the action is one tier down (foundation §6). */
+    size: ControlSize;
+    /** Where the tooltip opens. */
+    side?: TooltipSide;
+    /**
+     * The glyph (`<Icon name="…" />`); with `asChild`, the one element (a link) whose children are
+     * the glyph: the action becomes that element with the button look.
+     */
+    children: React.ReactNode;
+    asChild?: boolean;
+    ref?: React.Ref<HTMLButtonElement>;
+};
+/**
+ * A small action beside a row (copy a value, write to an address, create inside a section): a
+ * ghost neutral icon Button one tier below the row, named by `label`, which is also its tooltip.
+ * With `asChild` it is a link (`mailto:`, another page) with the same look. Hosts:
+ * `DescriptionList.ItemAction`, `Sidebar.ItemAction`.
+ */
+export declare function RowAction({ label, size, side, asChild, children, ...rest }: RowActionProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/internal/SwitcherScroller.d.ts

@@ -0,0 +1,11 @@
+import { type ScrollContainerProps } from "../components/scroll-container/ScrollContainer";
+type SwitcherScrollerProps = Omit<ScrollContainerProps, "as" | "axis" | "scrollbar" | "anchor" | "onReachStart" | "onReachEnd" | "snap" | "lock">;
+/**
+ * The row of a switcher (foundation §9): a sideways `ScrollContainer` with a hidden bar — items
+ * that do not fit scroll inside it, a vertical wheel scrolls it sideways, the hidden edges fade
+ * (`edges`, default `fade`; `none` for a switcher that draws its own edge overlays). It never
+ * wraps and never truncates: the host keeps its items at least as wide as their content. The
+ * selected item comes into view with `revealInScroller` (`selectionIndicator`).
+ */
+export declare function SwitcherScroller({ edges, className, ...rest }: SwitcherScrollerProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/internal/attachmentTile.d.ts

@@ -4,7 +4,7 @@ import styles from "./attachmentTile.module.css";
 export { styles as attachmentTileStyles };
 /** What a tile shows: a picture, a video's first frame, or a file placeholder. */
 export type AttachmentTileKind = "image" | "video" | "file";
-export type AttachmentTileProps = Omit<React.HTMLAttributes<HTMLElement>, "children" | "id" | "onKeyDown"> & {
+type AttachmentTileProps = Omit<React.HTMLAttributes<HTMLElement>, "children" | "id" | "onKeyDown"> & {
     /** The id of the item in its `Dnd.Sortable`. */
     id: string;
     kind: AttachmentTileKind;

package/dist/internal/audio.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The audio helpers a recording and its playback share (Composer's recorder, VoicePlayer's
+ * `getWaveform`): the Web Audio constructor, the length of a voice message's waveform and the
+ * scaling of its levels.
+ */
+/** Bars in a voice message's `waveform`: what the recorder hands over and `getWaveform` returns. */
+export declare const WAVEFORM_BARS = 48;
+type AudioContextCtor = typeof AudioContext;
+/** The browser's `AudioContext` (or Safari's prefixed one), `undefined` without Web Audio. */
+export declare function audioContextCtor(): AudioContextCtor | undefined;
+/** Levels scaled so the loudest is 1, rounded to hundredths; all-silent levels stay as they are. */
+export declare function normalizePeaks(levels: readonly number[]): number[];
+export {};

package/dist/{components/badge/tier.d.ts → internal/chipTier.d.ts}

@@ -1,9 +1,10 @@
-import { type ControlSize } from "../../internal/states";
+import { type ControlSize } from "./states";
 /**
- * Badge tiers (`--prime-badge-<tier>-*`): 16 · 20 · 24 · 28 · 32. Shared by Badge and Kbd.
- * Pairing rule (foundation §6): inside a control of tier T a badge uses the tier one step down.
+ * Chip tiers (`--prime-badge-<tier>-*`: 16 · 20 · 24 · 28 · 32), shared by Badge and Kbd with the
+ * `.tier` class of `chipTier.module.css`. Pairing rule (foundation §6): inside a control of tier T
+ * a chip uses the tier one step down.
  */
-export type ResolvedBadgeTier = {
+type ChipTier = {
     /** Nominal size exposed as `data-size`: the explicit prop, else the surrounding control size. */
     size: ControlSize;
     /** Visual tier exposed as `data-tier`; drives every dimension in CSS. */
@@ -13,4 +14,5 @@ export type ResolvedBadgeTier = {
  * Explicit `size` wins and is used as is. Without it the chip follows the nearest
  * `ControlSizeProvider` one tier down (`stepDown`); with no provider the default is `m`.
  */
-export declare function useBadgeTier(sizeProp: ControlSize | undefined): ResolvedBadgeTier;
+export declare function useChipTier(sizeProp: ControlSize | undefined): ChipTier;
+export {};

package/dist/internal/context.d.ts

@@ -1,4 +1,11 @@
 import * as React from "react";
+type ComponentContextOptions = {
+    /**
+     * What the parts must be inside, as the error names it. Default: the name itself when it is a
+     * part (`"Radio.Group"`, `"Stepper.Item"`), else its root (`"Input"` → `Input.Root`).
+     */
+    parent?: string;
+};
 /**
  * Factory for creating typed React Context + a guard hook that throws
  * a descriptive error when used outside the provider.
@@ -6,5 +13,7 @@ import * as React from "react";
  *
  * @example
  * const [InputProvider, useInputContext] = createComponentContext<InputContextValue>("Input");
+ * const [GroupProvider, useGroup] = createComponentContext<GroupValue>("Radio.Group");
  */
-export declare function createComponentContext<T>(displayName: string): readonly [React.Provider<T | null>, () => T];
+export declare function createComponentContext<T>(displayName: string, { parent, }?: ComponentContextOptions): readonly [React.Provider<T | null>, (part?: string) => T];
+export {};

package/dist/internal/controlValue.d.ts

@@ -0,0 +1,7 @@
+/** A native control whose value the kit writes as typing would. */
+export type ValueControl = HTMLInputElement | HTMLTextAreaElement;
+/**
+ * Writes a value into a native control the way typing does, so React's `onChange` (and the owner's
+ * `onValueChange`) receive it whether the field is controlled or not.
+ */
+export declare function setControlValue(control: ValueControl, value: string): void;

package/dist/internal/edgeAutoScroll.d.ts

@@ -1,30 +1,48 @@
-/**
- * Edge auto-scroll: the one mechanism behind every gesture that scrolls a ScrollContainer (or the
- * page) while the pointer is held near its edge — a Dnd drag, a Gantt bar moved or drawn along the
- * time axis, a drag that paints a selection over DataTable rows or chat messages. Within
- * `EDGE_ZONE_PX` of an edge the scroller moves toward it, faster the closer the pointer is, up to
- * `MAX_SPEED_PX_PER_MS` on the edge itself. Speed is per millisecond, so a 120 Hz display scrolls
- * as fast as a 60 Hz one. A region that cannot scroll (`data-fits`, ScrollContainer `lock`: both
- * `overflow: hidden`) is never moved.
- */
-/** Distance from an edge where the scroller starts to move (`--prime-space-16`). */
-export declare const EDGE_ZONE_PX = 64;
-/** Top speed, on the edge itself. */
-export declare const MAX_SPEED_PX_PER_MS = 1.1;
-export type EdgePoint = {
+import { type ScrollAxes } from "./scrollAncestors";
+type EdgePoint = {
     x: number;
     y: number;
 };
-/** Speed toward an edge `distance` px away from the pointer: 0 outside the zone. */
-export declare function edgeSpeed(distance: number, zone?: number): number;
-/** Scrollable boxes between `element` and the root, innermost first: a list that can still scroll wins over the page. */
-export declare function scrollableAncestors(element: Element | null): HTMLElement[];
 /**
- * One frame of edge auto-scroll: scrolls the innermost of `containers` that wants to move and still
- * can. `axes` limits the axes a gesture scrolls (a list's drag only up and down). Returns whether
- * anything moved, so the gesture re-reads what is under the pointer.
+ * How far in from a scroller's edges its zones start, in px, by logical side: a scroller with a
+ * pinned column (Gantt's names) scrolls from the end of that column, not from its own edge.
+ * Inline sides follow the scroller's writing direction.
+ */
+type EdgeInsets = {
+    inlineStart?: number;
+    inlineEnd?: number;
+    blockStart?: number;
+    blockEnd?: number;
+};
+/**
+ * The boxes a gesture that started on `element` may scroll, innermost first — a list that can
+ * still scroll wins over the page. The page itself scrolls through the document element even with
+ * `overflow: visible`.
+ */
+export declare function edgeScrollers(element: Element | null): HTMLElement[];
+type EdgeAutoScrollOptions = {
+    /** The boxes to scroll, innermost first (`edgeScrollers`); `setScrollers` replaces them. */
+    scrollers: readonly HTMLElement[];
+    /** The axes the gesture scrolls (a list's drag: only up and down). Both by default. */
+    axes?: ScrollAxes;
+    /** Where a scroller's zones start (a pinned column), read every frame. */
+    insets?: (container: HTMLElement) => EdgeInsets | undefined;
+    /** Something scrolled under the pointer: the gesture re-reads what it is over. */
+    onScrolled: () => void;
+};
+export type EdgeAutoScroll = {
+    /** The pointer moved during the gesture: scrolls while it is held near an edge. */
+    follow: (point: EdgePoint) => void;
+    /** The pointer went over another box: the boxes to scroll from now on. */
+    setScrollers: (scrollers: readonly HTMLElement[]) => void;
+    /** The gesture ended. */
+    stop: () => void;
+};
+/**
+ * The frame loop of a gesture held near an edge: `follow` starts it, each frame scrolls by the
+ * time that passed (clamped to `MAX_FRAME_MS`) and calls `onScrolled` when something moved. A frame
+ * that moves nothing (the pointer left the zones, the scroller reached its end) rests the loop
+ * until the pointer moves again.
  */
-export declare function autoScrollStep(containers: HTMLElement[], point: EdgePoint, elapsedMs: number, axes?: {
-    x: boolean;
-    y: boolean;
-}): boolean;
+export declare function createEdgeAutoScroll(options: EdgeAutoScrollOptions): EdgeAutoScroll;
+export {};

package/dist/internal/fieldCell.d.ts

@@ -4,7 +4,8 @@ import * as React from "react";
  * a framed field without a `label` of its own takes it as its label (and keeps its own `label`, if
  * any), so every field in a row has a name without a visible label per row. The column heading
  * shows the name once above the rows; the field's label is read, not shown, until the list stacks
- * its rows into blocks in a narrow container (`FIELD_LIST_CONTAINER`), where each field shows it.
+ * its rows into blocks in a narrow container (the `prime-field-list` container FieldList sets),
+ * where each field shows it.
  */
 export type FieldCell = {
     /** The column heading: the name of the field in this cell. */
@@ -14,8 +15,8 @@ export type FieldCell = {
      * a one-column list, named by the list's own label, shows none in either layout.
      */
     hidden: "wide" | "always";
+    /** The column is required: the field in the cell is required too (`useFieldFrame`). */
+    required: boolean;
 };
 export declare const FieldCellContext: React.Context<FieldCell | null>;
-/** Name of the size container `FieldList` sets; FieldFrame shows a cell label under its query. */
-export declare const FIELD_LIST_CONTAINER = "prime-field-list";
 export declare function useFieldCell(): FieldCell | null;

package/dist/internal/fieldClasses.d.ts

@@ -2,8 +2,21 @@
 export declare const fieldSurfaceClass: string;
 /** `--field-*` tier variables, resolved from `data-size` on the same element (`fieldTier.module.css`). */
 export declare const fieldTierClass: string;
+/** Field label text of the tier (Label); joined next to `fieldTierClass`. */
+export declare const fieldLabelTextClass: string;
+/** Support row text of the tier (Hint, the character counter); joined next to `fieldTierClass`. */
+export declare const fieldHintTextClass: string;
 /**
- * Tier + surface + trigger layout of a button-shaped field (`fieldTrigger.module.css`). Classes are
- * joined here, in TSX, never by a cross-file CSS `composes` (the bundler cannot order those).
+ * An editable value of the tier: at least 16px on touch screens and narrow viewports (iOS zooms
+ * into smaller text). Inside an element with `fieldTierClass`.
+ */
+export declare const fieldInputTextClass: string;
+/** A cell of a one-time code (DigitInput): the `--field-code` square and its corner. */
+export declare const fieldCodeCellClass: string;
+/**
+ * Tier + surface + trigger layout of a button-shaped field (`fieldTrigger.module.css`), its press
+ * (the shared press feedback) and the touch hit area grown in height: a trigger fills its row, and xs and
+ * s are under 44px. Classes are joined here, in TSX, never by a cross-file CSS `composes` (the
+ * bundler cannot order those).
  */
 export declare const fieldTriggerClass: string;

package/dist/internal/fileSize.d.ts

@@ -1,2 +1,6 @@
-/** «820 КБ», «1,2 МБ»: Russian digits, one decimal from a megabyte on. */
+/**
+ * «820 КБ», «1,2 МБ»: Russian digits, one decimal from a megabyte on. The value is rounded before
+ * its unit is final, so a size that rounds up to 1024 moves to the next unit («1 МБ», never
+ * «1 024 КБ»).
+ */
 export declare function formatFileSize(bytes: number): string;

package/dist/internal/formatClock.d.ts

@@ -1,2 +1,4 @@
 /** A media position or length: `m:ss`, `h:mm:ss` from an hour on. */
 export declare function formatClock(seconds: number): string;
+/** A time of day: `HH:mm`, 24-hour, in the local zone («09:05»). */
+export declare function formatTimeOfDay(date: Date): string;

package/dist/internal/formatNumber.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The kit's default display of a number: Russian digit groups and a decimal comma (`12 480`,
+ * `0,5`). `maximumFractionDigits` caps the decimals (a share: `1` → `12,5`); without it the
+ * locale default (up to 3) applies.
+ */
+export declare function formatNumber(value: number, maximumFractionDigits?: number): string;

package/dist/internal/glyphSwap.d.ts

@@ -1,15 +1,11 @@
 import * as React from "react";
 /**
- * What a glyph is: the element type with its `name` prop (an `<Icon name>`) and its key. Text and
- * numbers are one glyph whose words change in place (a percent ticking up never cross-fades).
- */
-export declare function glyphKey(node: React.ReactNode): string;
-/**
- * A glyph that changes cross-fades in place (foundation §7 rule 7): the outgoing one shrinks to 0.6
- * and fades, the incoming one grows from 0.6 (`fast` · standard) and plays its own gesture once
+ * A glyph that changes cross-fades in place (foundation §7 rule 7): the outgoing one shrinks to
+ * `--prime-motion-scale-mark` and fades, the incoming one grows from it (`fast` · standard) and plays its own gesture once
  * (`data-play`, `icons/glyphMotion`). Both share one grid cell, so the box keeps the glyph's size.
- * A change of the same glyph (new words, new props) updates in place. Reduced motion swaps at once
- * and plays no gesture. Used by `Button.Icon` and the centre of ProgressCircle.
+ * A change of the same glyph (new words, new props) updates in place. Reduced motion drops the old
+ * glyph at once, fades the new one in without the scale and plays no gesture. The one glyph slot
+ * of the kit: every glyph that changes in place goes through it.
  */
 export declare function GlyphSwap({ children, className, layerClassName, }: {
     children?: React.ReactNode;

package/dist/internal/hasContent.d.ts

@@ -0,0 +1,6 @@
+import type * as React from "react";
+/**
+ * Whether a node draws something: `null`, `undefined`, booleans, `""` and lists of only those do
+ * not (a label, hint, error or region slot with nothing in it takes no room).
+ */
+export declare function hasContent(node: React.ReactNode): boolean;

package/dist/internal/highlightTsx.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Minimal TS / TSX tokenizer for CodeBlock: comments, strings, numbers, keywords and JSX tags. It
+ * returns plain tokens, never markup — the component renders each as a text node in a span.
+ */
+export type TsxTokenKind = "keyword" | "string" | "comment" | "number" | "tag" | "text";
+type TsxToken = {
+    kind: TsxTokenKind;
+    text: string;
+};
+/** The tokens of a TS / TSX source, in order; their texts join back into the source. */
+export declare function highlightTsx(source: string): TsxToken[];
+export {};

package/dist/internal/iconBox.d.ts

@@ -6,4 +6,10 @@ import type { ControlSize } from "./states";
  * `ControlSizeProvider`), else `m`.
  */
 export declare function iconBoxClass(size: ControlSize | undefined, tier: ControlSize | undefined): string;
+/**
+ * A slot that holds a glyph the kit does not draw (a raw `<svg>` of an app's own icon set): the
+ * svg takes the host's `--prime-icon-size`, like a kit `Icon` in the same place. A kit `Icon`
+ * keeps its own box (the slot rule has no specificity).
+ */
+export declare const iconSlotClass: string;
 export { styles as iconBoxStyles };

package/dist/internal/iconLayout.d.ts

@@ -1,5 +1,5 @@
 import * as React from "react";
-export type IconLayout = {
+type IconLayout = {
     /** Only icons: a square control without side padding. */
     iconOnly: boolean;
     /** An icon first, then text: the start side takes the optical padding. */
@@ -13,3 +13,4 @@ export type IconLayout = {
  * and where a loading spinner goes. `iconType` is the control's own Icon part.
  */
 export declare function iconLayout(children: React.ReactNode, iconType: React.ElementType): IconLayout;
+export {};

package/dist/internal/imageSlot.d.ts

@@ -1,8 +1,13 @@
 import * as React from "react";
 import { type ImageStatus } from "../hooks/useImageStatus";
 export type ImageSlotImageProps = Omit<React.ImgHTMLAttributes<HTMLImageElement>, "src" | "alt"> & {
+    /**
+     * Image URL.
+     */
     src: string;
-    /** Empty (default) when the text next to it already names the subject. */
+    /**
+     * Empty when the text next to the thumbnail names the object, otherwise a description.
+     */
     alt?: string;
     ref?: React.Ref<HTMLImageElement>;
 };

package/dist/internal/interactiveElement.d.ts

@@ -0,0 +1,41 @@
+import type * as React from "react";
+type BaseProps = Omit<React.HTMLAttributes<HTMLElement>, "onClick"> & {
+    /** One callback ref fits whichever element renders. */
+    ref?: React.Ref<HTMLElement>;
+    /** Out of action: no click runs, no navigation, no Tab stop (`aria-disabled` or native). */
+    disabled?: boolean;
+    onClick?: React.MouseEventHandler<HTMLElement>;
+};
+/** The link attributes exist only on the `link` element. */
+type LinkAttributes = Pick<React.AnchorHTMLAttributes<HTMLAnchorElement>, "target" | "rel" | "download" | "hrefLang" | "referrerPolicy" | "ping">;
+type ButtonAttributes = Pick<React.ButtonHTMLAttributes<HTMLButtonElement>, "form" | "name" | "value" | "formAction">;
+/**
+ * One interactive element of a part, by kind:
+ * - `link` — an `<a href>`;
+ * - `button` — a `<button>` (`type` defaults to `button`);
+ * - `static` — a `<div>` with no action of its own (a brand without a link): it takes no `onClick`,
+ *   since a click handler needs a button or a link to reach it from the keyboard;
+ * - `slot` — the consumer's one element (`asChild`: a router link), through `Slot`.
+ */
+type InteractiveElementProps = (BaseProps & LinkAttributes & {
+    element: "link";
+    href: string;
+}) | (BaseProps & ButtonAttributes & {
+    element: "button";
+    type?: "button" | "submit" | "reset";
+}) | (Omit<BaseProps, "onClick"> & {
+    element: "static";
+    onClick?: never;
+}) | (BaseProps & {
+    element: "slot";
+    children: React.ReactElement;
+});
+/**
+ * The interactive element behind items, rows and links (`Sidebar.Item`, `List.Item`,
+ * `BottomNav.Item`, LinkButton, Button `asChild`), with the disabled guard on every branch: a
+ * disabled element runs no `onClick` (the event is default-prevented) and carries `aria-disabled`;
+ * a link loses its `href`, a button is natively `disabled`, a slot child leaves the Tab order and a
+ * link child loses its `href` (`Slot`).
+ */
+export declare function InteractiveElement(props: InteractiveElementProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/internal/labels.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The component's `labels`: its Russian defaults with the consumer's overrides on top (an
+ * `undefined` override keeps the default). The result keeps its identity while the overrides keep
+ * their content, so an inline `labels={{ … }}` object does not re-render what reads it.
+ */
+export declare function useLabels<L extends object>(defaults: L, labels: Partial<L> | undefined): L;

package/dist/internal/leaveInPlace.d.ts

@@ -1,9 +1,10 @@
 /**
  * The exit of a part the owner removed (a chip, a queue row): React drops the node at once, so a
- * copy of it stays in the flow at the same spot and closes up — it fades, settles a little smaller
- * and shrinks to nothing along `axis`, taking its gap with it, so the neighbours glide into the
- * place instead of jumping. Call it from a layout-effect cleanup, while the node is still drawn;
- * the copy is placed after the commit, and only if the node really left (Strict Mode replays an
- * unmount on a node that stays). Inert and hidden from assistive tech; gone when the motion ends.
+ * copy of it stays in the flow at the same spot and closes up — it fades, settles to the entering
+ * scale (`--prime-motion-scale-enter`) and shrinks to nothing along `axis` (`fast` · `exit`),
+ * taking its gap with it, so the neighbours glide into the place instead of jumping. Call it from
+ * a layout-effect or ref cleanup, while the node is still drawn; the copy is placed after the
+ * commit, and only if the node really left (Strict Mode replays an unmount on a node that stays).
+ * Inert and hidden from assistive tech; gone when the motion ends.
  */
 export declare function leaveInPlace(node: HTMLElement, axis: "inline" | "block"): void;

package/dist/internal/listPresence.d.ts

@@ -0,0 +1,32 @@
+import * as React from "react";
+/** What changed in a keyed list since the last render. */
+export type ListPresence = {
+    /** The keys, in order. */
+    keys: readonly string[];
+    /**
+     * Bumps when the rows should glide from where they stood (a move, an addition, a large
+     * removal): the layout key of the host's FLIP (`useFlipList`). A plain removal keeps it, so the
+     * rows below follow the closing instead.
+     */
+    settle: number;
+    /** Keys new in the data: their rows rise in once. */
+    entering: Set<string>;
+    /**
+     * Keys taken out: their rows close up in place as they unmount. One set for the life of the
+     * list, so a row that unmounts reads the change that removed it.
+     */
+    leaving: Set<string>;
+};
+/**
+ * Keyed list enter and leave (foundation §7 rule 11) for a host that renders application data as
+ * rows (dialogs, records): called with the keys in order on every render, it says which rows are
+ * new, which were taken out, and when the rest should glide. Each row reads it with
+ * `useListItemPresence`. The first render enters nothing.
+ */
+export declare function useListPresence(keys: readonly string[]): ListPresence;
+/**
+ * One row of a `useListPresence` list: whether it entered (join `enterMotion.enter` on its first
+ * render), and on unmount, when the data took it out, the element in `node` closes up in place
+ * along the block axis.
+ */
+export declare function useListItemPresence(list: Pick<ListPresence, "entering" | "leaving">, key: string, node: React.RefObject<HTMLElement | null>): boolean;

package/dist/internal/listbox.d.ts

@@ -1,12 +1,12 @@
 import * as React from "react";
 /**
  * Listboxes with a virtual highlight (`aria-activedescendant`), shared by Select, TagSelect and
- * CommandMenu. Options carry `data-value` and `data-label`; disabled ones `data-disabled="true"`.
+ * CommandMenu: the item registry, the highlight store, the keyboard and the typeahead. Focus stays
+ * on the field (the search, the listbox); the highlight is a value, and Enter activates the
+ * highlighted item through the registry, never through a synthetic DOM click.
  */
 /** `id` of an option for `aria-activedescendant` (no spaces: a valid id). */
 export declare const optionDomId: (listboxId: string, value: string) => string;
-/** Enabled options of a listbox, in DOM order. */
-export declare function enabledOptions(container: HTMLElement | null): HTMLElement[];
 export type Store<T> = {
     get: () => T;
     set: (next: T) => void;
@@ -20,40 +20,80 @@ export declare function useCreateStore<T>(initial: T): Store<T>;
  * `highlighted === value`, so moving the highlight re-renders two options, not the whole list.
  */
 export declare function useStoreSlice<T, S>(store: Store<T>, select: (value: T) => S): S;
-export type ListboxKeyContext = {
-    items: HTMLElement[];
-    highlight: Store<string | undefined>;
-    onSelect: (value: string, label: string) => void;
+/** What an item tells its listbox. */
+type ListboxItem = {
+    /** The visible name: typeahead, the trigger after the list closed, announcements. */
+    label: string;
+    /** The text a query is matched against, in lower case. */
+    haystack: string;
+    /** Shown but skipped by the arrows and never activated. */
+    disabled?: boolean;
+    /** Shown whatever the query, after the matches (create from the query, an action row). */
+    persistent?: boolean;
+    /** What Enter on the highlighted item and a click on it do. */
+    onActivate: () => void;
+};
+/** The items a query leaves on screen. */
+type ListboxView = {
+    /** Shown items: the matches, then the persistent ones. */
+    visible: ReadonlySet<string>;
+    /** Shown, enabled items in their order: what the arrows walk. */
+    navigable: readonly string[];
+    /** Shown items that match the query (persistent ones apart): the empty state. */
+    matchCount: number;
+};
+export type ListboxRegistry = {
+    /** Registers a mounted item (from a layout effect); returns the unregistration. */
+    register: (id: string, item: ListboxItem, node?: () => Element | null) => () => void;
+    /** Runs the item's `onActivate`; `false` when it is unknown, unmounted or disabled. */
+    activate: (id: string) => boolean;
+    /** The item's label, kept after it unmounts (the trigger of a closed list); else the id. */
+    labelOf: (id: string) => string;
+    /** The item's element, to bring the highlight into view. */
+    nodeOf: (id: string) => Element | null;
+    /** The items a query leaves on screen; the same object until an item or the query changes. */
+    view: (query: string, filter: boolean) => ListboxView;
+    subscribe: (listener: () => void) => () => void;
 };
+/** One registry per listbox instance. */
+export declare function useListboxRegistry(): ListboxRegistry;
+/** The items `query` leaves on screen; re-renders when an item (un)registers or changes. */
+export declare function useListboxView(registry: ListboxRegistry, query?: string, filter?: boolean): ListboxView;
 /**
- * Arrows, Home and End move the highlight (wrapping); Enter and Space pick it. Escape is the layer
- * stack's (it closes the panel).
+ * Registers an item while it is mounted. `onActivate` is read when it runs, so a new handler every
+ * render does not re-register the item; `nodeRef` is the element the highlight brings into view.
  */
-export declare function handleListboxKeyDown(event: React.KeyboardEvent<HTMLElement>, { items, highlight, onSelect }: ListboxKeyContext): void;
+export declare function useListboxItem(registry: ListboxRegistry, id: string, item: ListboxItem, nodeRef?: React.RefObject<Element | null>): void;
 /**
- * Typeahead by option label: the typed prefix finds the next match; the same letter repeated
- * cycles through the options that start with it. Returns the match to highlight.
+ * A key that belongs to an input method composing text (a Chinese, Japanese or Korean IME, a
+ * dictation): its Enter confirms the composition and its arrows pick a candidate, so a listbox
+ * leaves them alone. Safari reports such keys as `keyCode` 229 without `isComposing`.
  */
-export declare function useTypeahead(): {
-    find: (key: string, items: HTMLElement[], highlighted: string | undefined) => HTMLElement | undefined;
-    isTyping: () => boolean;
-};
-export type LoadMoreOptions = {
-    /** More can be requested now: `hasMore`, a handler, nothing loading, no load error. */
-    enabled: boolean;
-    onLoadMore: (() => void | Promise<void>) | undefined;
-    /** The list's own scroller: the observer root. */
-    scrollRef: React.RefObject<HTMLElement | null>;
-    /** Changes when the list changes (a batch arrived): re-arms the request. */
-    rearm: unknown;
+export declare function isComposingKey(event: React.KeyboardEvent): boolean;
+/**
+ * Brings the highlighted option into view inside the list's own scroller after a keyboard move
+ * (`block: "nearest"`); a highlight that follows the pointer never scrolls.
+ */
+export declare function revealHighlighted(element: Element | null | undefined): void;
+type ListboxKeyContext = {
+    /** The navigable items, in order. */
+    ids: readonly string[];
+    highlight: Store<string | undefined>;
+    /** Enter and Space on the highlighted item (the registry's `activate`). */
+    activate: (id: string) => void;
 };
 /**
- * Load more at the end of a list (Select, CommandMenu): a sentinel after the last option asks once
- * per round when it scrolls into the list's own scroller; `request` asks the same way from the
- * keyboard (the highlight reached the last option). Without `IntersectionObserver` (jsdom, old
- * engines) only `request` asks.
+ * Arrows, Home and End move the highlight (wrapping); Enter and Space activate it. Escape is the
+ * layer stack's (it closes the panel); a key of a composing input method is left alone. Returns
+ * the item the highlight moved to, for the host to reveal (`revealHighlighted`), or `null`.
  */
-export declare function useLoadMore({ enabled, onLoadMore, scrollRef, rearm }: LoadMoreOptions): {
-    sentinelRef: React.RefObject<HTMLDivElement | null>;
-    request: () => void;
+export declare function handleListboxKeyDown(event: React.KeyboardEvent<HTMLElement>, { ids, highlight, activate }: ListboxKeyContext): string | null;
+/**
+ * Typeahead by item label: the typed prefix finds the next match; the same letter repeated cycles
+ * through the items that start with it. Returns the match to highlight.
+ */
+export declare function useTypeahead(): {
+    find: (key: string, ids: readonly string[], highlighted: string | undefined, labelOf: (id: string) => string) => string | undefined;
+    isTyping: () => boolean;
 };
+export {};

package/dist/internal/longPress.d.ts

@@ -0,0 +1,42 @@
+import * as React from "react";
+/**
+ * A finger held this long picks up what it rests on to carry it: shorter than a long press, so a
+ * grab never feels like waiting, longer than the slow start of a scroll.
+ */
+export declare const DRAG_HOLD_MS = 280;
+/** A finger that moves further than this (px) before its hold ends is scrolling, not pressing. */
+export declare const PRESS_SLOP_PX = 8;
+/** Pointer travel (px) that turns a mouse or pen press into a drag: past the tremor of a click. */
+export declare const DRAG_THRESHOLD_PX = 4;
+type LongPressPoint = {
+    x: number;
+    y: number;
+};
+type LongPressOptions = {
+    /** Off: a press does nothing. */
+    enabled?: boolean;
+    /** The hold ended without the finger moving: the point it rests on, in client coordinates. */
+    onLongPress: (point: LongPressPoint) => void;
+    /** How long the finger rests. */
+    delay?: number;
+};
+type LongPressHandlers = {
+    onPointerDown: (event: React.PointerEvent) => void;
+    onPointerMove: (event: React.PointerEvent) => void;
+    onPointerUp: () => void;
+    onPointerCancel: () => void;
+};
+/**
+ * A long press of a finger on an element (a mouse has its right click): the hold starts on a touch
+ * press, ends in `onLongPress` when the finger rests for `delay`, and is given up when the finger
+ * moves past `PRESS_SLOP_PX` (it scrolls), lifts or is cancelled. `takeFired()` answers once
+ * whether the last press ended as a long press, so the click that follows the lift does not also
+ * activate the element. Spread `handlers` on the element; a host that has its own pointer
+ * handlers calls them from its own.
+ */
+export declare function useLongPress({ enabled, onLongPress, delay, }: LongPressOptions): {
+    handlers: LongPressHandlers;
+    cancel: () => void;
+    takeFired: () => boolean;
+};
+export {};