@skdx/react 0.26.0 → 0.28.0

package/dist/transfer/types.d.cts

@@ -1,19 +1,13 @@
 import type * as React from 'react';
 import type { PrimitivePropsWithRef } from '../utils/primitive.cjs';
-/**
- * Which of the two lists a part belongs to. `'source'` is the pool an item
- * starts in; `'target'` is the result — the array `Transfer`'s `value` holds.
- *
- * Named by role rather than by position: under `dir="rtl"` the target list is
- * on the left, so a `'left'`/`'right'` API would be wrong for half the world.
- */
+/** `'source'` is the pool, `'target'` is the array `Transfer`'s `value` holds; named by role, not position. */
 export type TransferSide = 'source' | 'target';
-/**
- * A move, named by where it lands rather than by which arrow it looks like.
- * `'toTarget'` adds to the value, `'toSource'` removes from it — true in both
- * writing directions, which `'right'`/`'left'` would not be.
- */
+/** Named by where items land: `'toTarget'` adds to value, `'toSource'` removes. */
 export type TransferDirection = 'toTarget' | 'toSource';
+/** How the built-in matcher compares queries against item labels. */
+export type TransferFilterMatchMode = 'startsWith' | 'contains' | 'endsWith';
+/** Where items land on target side: `'items'` keeps collection order; `'append'` / `'prepend'` follow moves. */
+export type TransferTargetOrder = 'items' | 'append' | 'prepend';
 /** One entry in a {@link Transfer}'s collection. */
 export interface TransferItemData {
     /** Unique id. This is what appears in `Transfer`'s `value` once the item is on the target side. */
@@ -21,129 +15,195 @@ export interface TransferItemData {
     /** Human-readable text, used as the option's content and its typeahead `textValue` when the list renders itself. */
     label: string;
     /**
-     * Excludes this item from selection, from keyboard navigation, and from
-     * every move — including "move all".
-     * @default undefined — the item behaves normally.
+     * Excludes item from selection, navigation, and moves.
+     * @default undefined — item behaves normally.
      */
     disabled?: boolean;
 }
 /** @internal Shared state distributed from {@link Transfer} to its parts via context. Not part of the public API. */
 export interface TransferContextValue {
-    /** Stable id prefix the parts derive their wiring ids from. */
     baseId: string;
-    /** Whether the whole widget is disabled. */
     disabled: boolean;
-    /** Whether the search plumbing is on; `TransferListSearch` renders nothing while it is off. */
+    /** Whether search is active; `TransferListSearch` renders nothing when off. */
     searchable: boolean;
-    /** Every item on a side, before the search filter. */
+    /** All items on each side before search filtering. */
     sideItems: Record<TransferSide, TransferItemData[]>;
-    /** Every item on a side that survives the current search query — what is actually rendered. */
+    /** Items on each side that survive the current search query. */
     visibleItems: Record<TransferSide, TransferItemData[]>;
-    /** Each side's marked-for-move selection, already pruned of values that side no longer holds. */
+    /** Each side's marked-for-move selection, pruned to values still present. */
     marked: Record<TransferSide, string[]>;
-    /** Replaces one side's marked selection wholesale. */
     setMarked: (side: TransferSide, values: string[]) => void;
-    /** Each side's search query. */
     query: Record<TransferSide, string>;
     setQuery: (side: TransferSide, query: string) => void;
-    /** The option value holding each list's own tab stop — one roving group per side. */
+    /** The roving-focus option id for each list. */
     active: Record<TransferSide, string | null>;
     setActive: (side: TransferSide, value: string | null) => void;
-    /** Range-selection anchor per side: the last option marked *without* Shift. */
+    /** Range-selection anchor per side (last option marked without Shift). */
     anchor: React.MutableRefObject<Record<TransferSide, string | null>>;
-    /** Whether a `TransferListHeader` is mounted for a side, which decides `aria-labelledby` vs `aria-label`. */
+    /** Whether `TransferListHeader` is mounted (decides `aria-labelledby` vs `aria-label`). */
     labelled: Record<TransferSide, boolean>;
     registerHeader: (side: TransferSide, present: boolean) => void;
-    /** Lets the root find a list element again, to place focus after a move. */
     registerList: (side: TransferSide, node: HTMLDivElement | null) => void;
-    /** Moves `values` (silently dropping any disabled ones), announces the outcome, and re-places focus. */
+    /** Flag to suppress `focusin` being mistaken for external Tab after programmatic focus. */
+    suppressFocusIn: React.MutableRefObject<boolean>;
+    /** Moves values, announces outcome, and re-places focus; silently drops disabled items. */
     move: (direction: TransferDirection, values: string[]) => void;
-    /** The accessible name each move trigger gives itself — the root's `getMoveLabel`, or the built-in English one. */
+    /** Accessible name for move triggers (from `getMoveLabel` or built-in English). */
     moveLabel: (count: number, direction: TransferDirection, all: boolean) => string;
+    emitListScroll: (side: TransferSide, list: HTMLElement) => void;
 }
-/** What a move just did, handed to {@link TransferProps.getMoveAnnouncement} so it can word the live-region message. */
+/** Move outcome, handed to {@link TransferProps.getMoveAnnouncement} for wording. */
 export interface TransferMoveDetail {
-    /** How many items actually moved (disabled ones are never counted). */
+    /** How many items moved (disabled items never counted). */
     moved: number;
-    /** How many items are left on the side they came from. */
+    /** Items left on the origin side. */
     remaining: number;
-    /** Which way they went. */
     direction: TransferDirection;
-    /** The side they left. */
     from: TransferSide;
-    /** The side they landed on. */
     to: TransferSide;
 }
+/** Search results, handed to {@link TransferProps.getSearchResultsAnnouncement}. */
+export interface TransferSearchResultsDetail {
+    /** Items on this side that match the query. */
+    shown: number;
+    /** Total items on this side before filtering. */
+    total: number;
+    side: TransferSide;
+    /** The settled query (empty if user cleared the box). */
+    query: string;
+}
+/** List scroll geometry, carried by {@link TransferProps.onListScroll}. */
+export interface TransferListScrollDetail {
+    side: TransferSide;
+    scrollTop: number;
+    scrollHeight: number;
+    clientHeight: number;
+}
+/** Reason {@link TransferEmpty} is showing, handed to a function child. */
+export interface TransferEmptyContext {
+    /** `'empty'` when side holds nothing; `'no-results'` when filtered to nothing. */
+    reason: 'empty' | 'no-results';
+    /** The active search query (empty string if reason is `'empty'`). */
+    query: string;
+}
 /** Props for the {@link Transfer} root. */
 export interface TransferProps extends Omit<PrimitivePropsWithRef<'div'>, 'onChange' | 'defaultValue'> {
     /**
-     * The whole collection, both sides at once. Each side is *derived* from this
-     * plus `value`, never stored separately — one array is the source of truth,
-     * so the two lists cannot drift apart.
+     * Manually-composed parts; omitted, derives headed searchable lists from `titles` and `renderItem`.
+     * @default undefined — derives anatomy.
      */
+    children?: React.ReactNode;
+    /** Entire collection; both sides are derived from this plus `value`. */
     items: TransferItemData[];
     /**
-     * The ids currently on the target side, for controlled usage. Pair with
-     * `onValueChange`. Rendering order always follows `items`, not this array,
-     * so a controlled consumer never has to keep two orderings in sync.
-     * @default undefined — uncontrolled, tracks its own membership internally.
+     * Target-side ids for controlled usage; pair with `onValueChange`.
+     * @default undefined — uncontrolled.
      */
     value?: string[];
     /**
-     * The ids initially on the target side, for uncontrolled usage.
-     * @default undefined — every item starts on the source side.
+     * Initial target-side ids for uncontrolled usage.
+     * @default undefined — all items start on source.
      */
     defaultValue?: string[];
     /**
-     * Fires with the whole new target-side id array whenever a move happens,
-     * controlled or not.
-     * @default undefined — no-op if omitted.
+     * Fires with new target-side ids whenever items move.
+     * @default undefined — no-op.
      */
     onValueChange?: (value: string[]) => void;
     /**
-     * Fires alongside `onValueChange` with the items that actually moved and
-     * which way, for side effects that need the moved rows rather than the new
-     * membership — a toast, an undo entry, a server call.
-     * @default undefined — no-op if omitted.
+     * Fires alongside `onValueChange` with moved items and direction.
+     * @default undefined — no-op.
      */
     onMove?: (items: TransferItemData[], direction: TransferDirection) => void;
     /**
-     * Disables both lists and every move trigger at once. Individual items can
-     * still be disabled on their own via `TransferItemData.disabled`.
+     * Disables both lists and all move triggers; individual items have their own `disabled`.
      * @default false
      */
     disabled?: boolean;
     /**
-     * Enables per-list filtering. While `false`, `TransferListSearch` renders
-     * nothing and `filter` is never called — so the search box cannot be left
-     * on screen as decoration that does not work.
-     * @default false — both lists show everything on their side.
+     * Form field name; target-side ids submit as separate entries (not joined).
+     * @default undefined — submits nothing.
+     */
+    name?: string;
+    /**
+     * Form id for the submitted entries when Transfer is outside the form.
+     * @default undefined — entries belong to nearest ancestor form.
+     */
+    form?: string;
+    /**
+     * Enables per-list filtering; while false, `TransferListSearch` renders nothing.
+     * @default false
      */
     searchable?: boolean;
     /**
-     * Decides whether an item survives its list's current query. Only consulted
-     * while `searchable`.
-     * @default undefined — case-insensitive substring match against `item.label`.
+     * Custom filter; returns true if item survives query. Only consulted when `searchable`.
+     * @default undefined — case-insensitive substring match.
      */
     filter?: (item: TransferItemData, query: string) => boolean;
     /**
-     * Words the accessible name of every `TransferMoveTrigger` and
-     * `TransferMoveAllTrigger` under this root. `all` distinguishes the two, and
-     * `count` is how many items pressing it would actually move — zero included,
-     * because the trigger stays focusable with nothing to move and has to say
-     * why.
-     *
-     * The only way to translate those names: they are computed from live counts,
-     * so a static `aria-label` on the trigger cannot express them.
-     * @default undefined — the built-in English wording ("Move 3 items to selected").
+     * How built-in matcher compares queries to labels; ignored if `filter` is given.
+     * @default 'contains'
+     */
+    filterMatchMode?: TransferFilterMatchMode;
+    /**
+     * Words move-trigger accessible names (count is items to move, including zero).
+     * @default undefined — built-in English.
      */
     getMoveLabel?: (count: number, direction: TransferDirection, all: boolean) => string;
     /**
-     * Words the polite live-region announcement made after each move. Return
-     * `''` to say nothing at all.
-     * @default undefined — the built-in English wording ("3 items moved to selected. 5 remaining in available.").
+     * Words the polite live-region announcement after moves (return empty string to silence).
+     * @default undefined — built-in English.
      */
     getMoveAnnouncement?: (detail: TransferMoveDetail) => string;
+    /**
+     * Words the polite live-region announcement when search settles per side (return empty to silence).
+     * @default undefined — built-in English.
+     */
+    getSearchResultsAnnouncement?: (detail: TransferSearchResultsDetail) => string;
+    /**
+     * Where items land on target: `'items'` keeps collection order; `'append'` / `'prepend'` follow moves.
+     * @default 'items'
+     */
+    targetOrder?: TransferTargetOrder;
+    /**
+     * Fires on either list scroll with geometry for infinite-scroll loading.
+     * @default undefined — no-op.
+     */
+    onListScroll?: (detail: TransferListScrollDetail) => void;
+    /**
+     * Heading text for derived `TransferListHeader`s. Ignored when `children` given.
+     * @default { source: 'Available items', target: 'Selected items' }
+     */
+    titles?: TransferTitles;
+    /**
+     * Text for derived `TransferEmpty` states (`{query}` replaced with search text).
+     * @default { empty: 'Nothing here.', noMatch: 'No match for "{query}".' }
+     */
+    emptyText?: TransferEmptyText;
+    /**
+     * Whether derived `TransferControls` include a move-all trigger (off by default due to destructiveness).
+     * @default false
+     */
+    showMoveAll?: boolean;
+    /**
+     * Renders derived `TransferItem` content instead of `label`. Ignored when `children` given.
+     * @default undefined — each item renders its `label`.
+     */
+    renderItem?: (item: TransferItemData) => React.ReactNode;
+}
+/** Text for empty states. See {@link TransferProps.emptyText}. */
+export interface TransferEmptyText {
+    /** Shown when side holds no items. @default 'Nothing here.' */
+    empty?: string;
+    /** Shown when search filters all items (`{query}` replaced). @default 'No match for "{query}".' */
+    noMatch?: string;
+}
+/** List headings for derived anatomy. See {@link TransferProps.titles}. */
+export interface TransferTitles {
+    /** Source (available) list heading. @default 'Available items' */
+    source?: string;
+    /** Target (selected) list heading. @default 'Selected items' */
+    target?: string;
 }
 /** @internal Wiring passed from a {@link TransferList} to the {@link TransferItem}s inside it. Not part of the public API. */
 export interface TransferListContextValue {
@@ -154,8 +214,13 @@ export interface TransferListProps extends Omit<PrimitivePropsWithRef<'div'>, 'o
     /** Which of the two sides this list renders the items for. */
     side: TransferSide;
     /**
-     * Your own `TransferItem`s, when the default rendering is not enough.
-     * @default undefined — the list renders one `TransferItem` per visible item on its side, using `label` as both content and `textValue`.
+     * Renders derived `TransferItem` content instead of `label`. Ignored when `children` given.
+     * @default undefined — each item renders its `label`.
+     */
+    renderItem?: (item: TransferItemData) => React.ReactNode;
+    /**
+     * Custom `TransferItem`s to override the default rendering of items.
+     * @default undefined — one `TransferItem` per visible item, using `label` as content.
      */
     children?: React.ReactNode;
 }
@@ -174,31 +239,36 @@ export interface TransferItemProps extends PrimitivePropsWithRef<'div'> {
     /** The id of the `TransferItemData` entry this option renders. */
     value: string;
     /**
-     * Excludes this option from marking, navigation, and moves.
+     * Excludes option from marking, navigation, and moves.
      * @default false
      */
     disabled?: boolean;
     /**
-     * Text typeahead matches this option against, published as `data-text-value`.
-     * @default undefined — falls back to the option's rendered text content, indicator glyph included.
+     * Text typeahead matches against, published as `data-text-value`.
+     * @default undefined — falls back to rendered text content.
      */
     textValue?: string;
 }
 /** Props for {@link TransferControls}, the named group holding the move triggers. */
 export interface TransferControlsProps extends PrimitivePropsWithRef<'div'> {
 }
-/** Props for {@link TransferMoveTrigger}, which moves the marked items one way. */
+/** Props for {@link TransferMoveTrigger}, moves marked items. */
 export interface TransferMoveTriggerProps extends PrimitivePropsWithRef<'button'> {
-    /** Which way this trigger moves: `'toTarget'` adds to the value, `'toSource'` removes from it. */
+    /** Direction: `'toTarget'` adds to value, `'toSource'` removes. */
     direction: TransferDirection;
 }
-/** Props for {@link TransferMoveAllTrigger}, which moves every visible item one way. */
+/** Props for {@link TransferMoveAllTrigger}, moves all visible items. */
 export interface TransferMoveAllTriggerProps extends PrimitivePropsWithRef<'button'> {
-    /** Which way this trigger moves: `'toTarget'` adds to the value, `'toSource'` removes from it. */
+    /** Direction: `'toTarget'` adds to value, `'toSource'` removes. */
     direction: TransferDirection;
 }
-/** Props for {@link TransferEmpty}, shown while one side has nothing to render. */
-export interface TransferEmptyProps extends PrimitivePropsWithRef<'div'> {
-    /** Which side's emptiness this message covers. */
+/** Props for {@link TransferEmpty}, shown when side has nothing to render. */
+export interface TransferEmptyProps extends Omit<PrimitivePropsWithRef<'div'>, 'children'> {
+    /** Which side ('source' or 'target') this empty state applies to. */
     side: TransferSide;
+    /**
+     * Message; pass function to differentiate empty vs no-results (published as `data-reason` / `data-query`).
+     * @default undefined — renders element only.
+     */
+    children?: React.ReactNode | ((context: TransferEmptyContext) => React.ReactNode);
 }