@skdx/react 0.26.0

package/dist/transfer/TransferList.d.cts

@@ -0,0 +1,29 @@
+import * as React from 'react';
+import type { TransferListProps } from './types.cjs';
+/**
+ * One side of a {@link Transfer}: a multi-select `role="listbox"` built on
+ * {@link Listbox}, with its own tab stop, its own roving focus, its own
+ * typeahead, and its own marked-for-move selection. The two lists are two
+ * independent roving-focus groups — Tab moves *between* them, arrows only ever
+ * move within one.
+ *
+ * Renders one `TransferItem` per visible item on its side by default, using
+ * each item's `label` as both its content and its typeahead `textValue`. Pass
+ * children to render the options yourself; they still get their side, their
+ * marked state, and their tab stop from the root.
+ *
+ * Beyond what `Listbox` already handles it adds three keyboard paths:
+ *
+ * - **Shift+ArrowUp/Down** extends the marked range from the anchor (the last
+ *   option marked without Shift), the keyboard equivalent of Shift+Click.
+ * - **Ctrl/Cmd+A** marks every enabled option currently visible in this list.
+ * - **The outward horizontal arrow** moves the marked items to the other list
+ *   — ArrowRight from the source under LTR, and ArrowLeft under `dir="rtl"`,
+ *   because the target list is on the left there. With nothing marked it moves
+ *   the focused option alone.
+ *
+ * Publishes `data-side` and, while it has nothing to render, `data-empty` plus
+ * `tabIndex={0}` — an empty list stays reachable so focus after a move that
+ * empties it has somewhere to land.
+ */
+export declare const TransferList: React.ForwardRefExoticComponent<Omit<TransferListProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/transfer/TransferList.d.ts

@@ -0,0 +1,29 @@
+import * as React from 'react';
+import type { TransferListProps } from './types.js';
+/**
+ * One side of a {@link Transfer}: a multi-select `role="listbox"` built on
+ * {@link Listbox}, with its own tab stop, its own roving focus, its own
+ * typeahead, and its own marked-for-move selection. The two lists are two
+ * independent roving-focus groups — Tab moves *between* them, arrows only ever
+ * move within one.
+ *
+ * Renders one `TransferItem` per visible item on its side by default, using
+ * each item's `label` as both its content and its typeahead `textValue`. Pass
+ * children to render the options yourself; they still get their side, their
+ * marked state, and their tab stop from the root.
+ *
+ * Beyond what `Listbox` already handles it adds three keyboard paths:
+ *
+ * - **Shift+ArrowUp/Down** extends the marked range from the anchor (the last
+ *   option marked without Shift), the keyboard equivalent of Shift+Click.
+ * - **Ctrl/Cmd+A** marks every enabled option currently visible in this list.
+ * - **The outward horizontal arrow** moves the marked items to the other list
+ *   — ArrowRight from the source under LTR, and ArrowLeft under `dir="rtl"`,
+ *   because the target list is on the left there. With nothing marked it moves
+ *   the focused option alone.
+ *
+ * Publishes `data-side` and, while it has nothing to render, `data-empty` plus
+ * `tabIndex={0}` — an empty list stays reachable so focus after a move that
+ * empties it has somewhere to land.
+ */
+export declare const TransferList: React.ForwardRefExoticComponent<Omit<TransferListProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/transfer/TransferListHeader.d.cts

@@ -0,0 +1,23 @@
+import * as React from 'react';
+import type { TransferListHeaderProps } from './types.cjs';
+/**
+ * The visible heading naming one of the two lists, and the element that list
+ * points `aria-labelledby` at. Give both sides one: "Available" and "Selected"
+ * next to two otherwise identical listboxes is the whole difference between a
+ * usable widget and two anonymous lists.
+ *
+ * It sits *beside* its `TransferList`, not inside it — a `role="listbox"` may
+ * only contain options and groups, so a heading inside one is invalid ARIA.
+ * That is also why it takes its own `side`: it has no list around it to
+ * inherit one from.
+ *
+ * Rendering one is what switches its list from a generic fallback name
+ * ("Available items") to this heading's text.
+ *
+ * @example
+ * ```tsx
+ * <TransferListHeader side="source">Available</TransferListHeader>
+ * <TransferList side="source" />
+ * ```
+ */
+export declare const TransferListHeader: React.ForwardRefExoticComponent<Omit<TransferListHeaderProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/transfer/TransferListHeader.d.ts

@@ -0,0 +1,23 @@
+import * as React from 'react';
+import type { TransferListHeaderProps } from './types.js';
+/**
+ * The visible heading naming one of the two lists, and the element that list
+ * points `aria-labelledby` at. Give both sides one: "Available" and "Selected"
+ * next to two otherwise identical listboxes is the whole difference between a
+ * usable widget and two anonymous lists.
+ *
+ * It sits *beside* its `TransferList`, not inside it — a `role="listbox"` may
+ * only contain options and groups, so a heading inside one is invalid ARIA.
+ * That is also why it takes its own `side`: it has no list around it to
+ * inherit one from.
+ *
+ * Rendering one is what switches its list from a generic fallback name
+ * ("Available items") to this heading's text.
+ *
+ * @example
+ * ```tsx
+ * <TransferListHeader side="source">Available</TransferListHeader>
+ * <TransferList side="source" />
+ * ```
+ */
+export declare const TransferListHeader: React.ForwardRefExoticComponent<Omit<TransferListHeaderProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/transfer/TransferListSearch.d.cts

@@ -0,0 +1,24 @@
+import * as React from 'react';
+import type { TransferListSearchProps } from './types.cjs';
+/**
+ * The filter input for one list: an `<input type="search">` bound to that
+ * side's query. Like {@link TransferListHeader} it is a sibling of its list
+ * rather than a child, since a `role="listbox"` may only contain options — so
+ * it takes its own `side`.
+ *
+ * Renders **nothing** while the root is not `searchable`. A filter box that
+ * stays on screen but no longer filters is worse than no box at all, so the
+ * one prop turns the input and the filtering on together.
+ *
+ * Filtering narrows what its list renders and therefore what "move all" moves:
+ * "move all" moves what you can see, not what you cannot.
+ *
+ * @example
+ * ```tsx
+ * <Transfer items={items} searchable>
+ *   <TransferListSearch side="source" placeholder="Filter" />
+ *   <TransferList side="source" />
+ * </Transfer>
+ * ```
+ */
+export declare const TransferListSearch: React.ForwardRefExoticComponent<Omit<TransferListSearchProps, "ref"> & React.RefAttributes<HTMLInputElement>>;

package/dist/transfer/TransferListSearch.d.ts

@@ -0,0 +1,24 @@
+import * as React from 'react';
+import type { TransferListSearchProps } from './types.js';
+/**
+ * The filter input for one list: an `<input type="search">` bound to that
+ * side's query. Like {@link TransferListHeader} it is a sibling of its list
+ * rather than a child, since a `role="listbox"` may only contain options — so
+ * it takes its own `side`.
+ *
+ * Renders **nothing** while the root is not `searchable`. A filter box that
+ * stays on screen but no longer filters is worse than no box at all, so the
+ * one prop turns the input and the filtering on together.
+ *
+ * Filtering narrows what its list renders and therefore what "move all" moves:
+ * "move all" moves what you can see, not what you cannot.
+ *
+ * @example
+ * ```tsx
+ * <Transfer items={items} searchable>
+ *   <TransferListSearch side="source" placeholder="Filter" />
+ *   <TransferList side="source" />
+ * </Transfer>
+ * ```
+ */
+export declare const TransferListSearch: React.ForwardRefExoticComponent<Omit<TransferListSearchProps, "ref"> & React.RefAttributes<HTMLInputElement>>;

package/dist/transfer/TransferMoveAllTrigger.d.cts

@@ -0,0 +1,19 @@
+import * as React from 'react';
+import type { TransferMoveAllTriggerProps } from './types.cjs';
+/**
+ * The button that moves every item currently visible on one side, marked or
+ * not. Same rules as {@link TransferMoveTrigger} — real button, name carries
+ * direction and count, `aria-disabled` rather than `disabled` when there is
+ * nothing to move.
+ *
+ * "Visible" is the operative word while the root is `searchable`: it moves what
+ * the filter is showing, never items hidden behind a query the user has
+ * forgotten is applied. Disabled items are excluded on both counts — the name
+ * and the move.
+ *
+ * @example
+ * ```tsx
+ * <TransferMoveAllTrigger direction="toTarget">⇒</TransferMoveAllTrigger>
+ * ```
+ */
+export declare const TransferMoveAllTrigger: React.ForwardRefExoticComponent<Omit<TransferMoveAllTriggerProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;

package/dist/transfer/TransferMoveAllTrigger.d.ts

@@ -0,0 +1,19 @@
+import * as React from 'react';
+import type { TransferMoveAllTriggerProps } from './types.js';
+/**
+ * The button that moves every item currently visible on one side, marked or
+ * not. Same rules as {@link TransferMoveTrigger} — real button, name carries
+ * direction and count, `aria-disabled` rather than `disabled` when there is
+ * nothing to move.
+ *
+ * "Visible" is the operative word while the root is `searchable`: it moves what
+ * the filter is showing, never items hidden behind a query the user has
+ * forgotten is applied. Disabled items are excluded on both counts — the name
+ * and the move.
+ *
+ * @example
+ * ```tsx
+ * <TransferMoveAllTrigger direction="toTarget">⇒</TransferMoveAllTrigger>
+ * ```
+ */
+export declare const TransferMoveAllTrigger: React.ForwardRefExoticComponent<Omit<TransferMoveAllTriggerProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;

package/dist/transfer/TransferMoveTrigger.d.cts

@@ -0,0 +1,26 @@
+import * as React from 'react';
+import type { TransferMoveTriggerProps } from './types.cjs';
+/**
+ * The button that moves the marked items one way. A real `<button>` in the tab
+ * order, named for what it does and how much of it — "Move 3 items to
+ * selected", not an unnamed arrow glyph.
+ *
+ * With nothing marked it is **`aria-disabled`, not `disabled`**. A truly
+ * disabled button is skipped by Tab, so a keyboard user exploring the widget
+ * never meets the control that explains the whole interaction, and would be
+ * left guessing why selecting things in a list appears to do nothing. Kept
+ * focusable, it announces "Move items to selected, nothing selected" — the
+ * instruction and the reason in one. Pressing it is a no-op.
+ *
+ * Publishes `data-direction` (the logical `'toTarget'`/`'toSource'`),
+ * `data-count`, and `data-disabled`. Direction is deliberately never published
+ * as left/right: under `dir="rtl"` the target list is on the left, so style the
+ * glyph from `[dir='rtl'] [data-direction='toTarget']` rather than expecting a
+ * physical attribute here.
+ *
+ * @example
+ * ```tsx
+ * <TransferMoveTrigger direction="toTarget">→</TransferMoveTrigger>
+ * ```
+ */
+export declare const TransferMoveTrigger: React.ForwardRefExoticComponent<Omit<TransferMoveTriggerProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;

package/dist/transfer/TransferMoveTrigger.d.ts

@@ -0,0 +1,26 @@
+import * as React from 'react';
+import type { TransferMoveTriggerProps } from './types.js';
+/**
+ * The button that moves the marked items one way. A real `<button>` in the tab
+ * order, named for what it does and how much of it — "Move 3 items to
+ * selected", not an unnamed arrow glyph.
+ *
+ * With nothing marked it is **`aria-disabled`, not `disabled`**. A truly
+ * disabled button is skipped by Tab, so a keyboard user exploring the widget
+ * never meets the control that explains the whole interaction, and would be
+ * left guessing why selecting things in a list appears to do nothing. Kept
+ * focusable, it announces "Move items to selected, nothing selected" — the
+ * instruction and the reason in one. Pressing it is a no-op.
+ *
+ * Publishes `data-direction` (the logical `'toTarget'`/`'toSource'`),
+ * `data-count`, and `data-disabled`. Direction is deliberately never published
+ * as left/right: under `dir="rtl"` the target list is on the left, so style the
+ * glyph from `[dir='rtl'] [data-direction='toTarget']` rather than expecting a
+ * physical attribute here.
+ *
+ * @example
+ * ```tsx
+ * <TransferMoveTrigger direction="toTarget">→</TransferMoveTrigger>
+ * ```
+ */
+export declare const TransferMoveTrigger: React.ForwardRefExoticComponent<Omit<TransferMoveTriggerProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;

package/dist/transfer/index.d.cts

@@ -0,0 +1,10 @@
+export { Transfer, moveAnnouncement } from './Transfer.cjs';
+export { TransferList } from './TransferList.cjs';
+export { TransferListHeader } from './TransferListHeader.cjs';
+export { TransferListSearch } from './TransferListSearch.cjs';
+export { TransferItem } from './TransferItem.cjs';
+export { TransferControls } from './TransferControls.cjs';
+export { TransferMoveTrigger } from './TransferMoveTrigger.cjs';
+export { TransferMoveAllTrigger } from './TransferMoveAllTrigger.cjs';
+export { TransferEmpty } from './TransferEmpty.cjs';
+export type { TransferProps, TransferListProps, TransferListHeaderProps, TransferListSearchProps, TransferItemProps, TransferControlsProps, TransferMoveTriggerProps, TransferMoveAllTriggerProps, TransferEmptyProps, TransferItemData, TransferMoveDetail, TransferSide, TransferDirection, } from './types.cjs';

package/dist/transfer/index.d.ts

@@ -0,0 +1,10 @@
+export { Transfer, moveAnnouncement } from './Transfer.js';
+export { TransferList } from './TransferList.js';
+export { TransferListHeader } from './TransferListHeader.js';
+export { TransferListSearch } from './TransferListSearch.js';
+export { TransferItem } from './TransferItem.js';
+export { TransferControls } from './TransferControls.js';
+export { TransferMoveTrigger } from './TransferMoveTrigger.js';
+export { TransferMoveAllTrigger } from './TransferMoveAllTrigger.js';
+export { TransferEmpty } from './TransferEmpty.js';
+export type { TransferProps, TransferListProps, TransferListHeaderProps, TransferListSearchProps, TransferItemProps, TransferControlsProps, TransferMoveTriggerProps, TransferMoveAllTriggerProps, TransferEmptyProps, TransferItemData, TransferMoveDetail, TransferSide, TransferDirection, } from './types.js';

package/dist/transfer/types.d.cts

@@ -0,0 +1,204 @@
+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.
+ */
+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.
+ */
+export type TransferDirection = 'toTarget' | 'toSource';
+/** 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. */
+    value: string;
+    /** 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.
+     */
+    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. */
+    searchable: boolean;
+    /** Every item on a side, before the search filter. */
+    sideItems: Record<TransferSide, TransferItemData[]>;
+    /** Every item on a side that survives the current search query — what is actually rendered. */
+    visibleItems: Record<TransferSide, TransferItemData[]>;
+    /** Each side's marked-for-move selection, already pruned of values that side no longer holds. */
+    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. */
+    active: Record<TransferSide, string | null>;
+    setActive: (side: TransferSide, value: string | null) => void;
+    /** Range-selection anchor per side: the 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`. */
+    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. */
+    move: (direction: TransferDirection, values: string[]) => void;
+    /** The accessible name each move trigger gives itself — the root's `getMoveLabel`, or the built-in English one. */
+    moveLabel: (count: number, direction: TransferDirection, all: boolean) => string;
+}
+/** What a move just did, handed to {@link TransferProps.getMoveAnnouncement} so it can word the live-region message. */
+export interface TransferMoveDetail {
+    /** How many items actually moved (disabled ones are never counted). */
+    moved: number;
+    /** How many items are left on the side they came from. */
+    remaining: number;
+    /** Which way they went. */
+    direction: TransferDirection;
+    /** The side they left. */
+    from: TransferSide;
+    /** The side they landed on. */
+    to: TransferSide;
+}
+/** 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.
+     */
+    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.
+     */
+    value?: string[];
+    /**
+     * The ids initially on the target side, for uncontrolled usage.
+     * @default undefined — every item starts on the source side.
+     */
+    defaultValue?: string[];
+    /**
+     * Fires with the whole new target-side id array whenever a move happens,
+     * controlled or not.
+     * @default undefined — no-op if omitted.
+     */
+    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.
+     */
+    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`.
+     * @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.
+     */
+    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`.
+     */
+    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").
+     */
+    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.").
+     */
+    getMoveAnnouncement?: (detail: TransferMoveDetail) => string;
+}
+/** @internal Wiring passed from a {@link TransferList} to the {@link TransferItem}s inside it. Not part of the public API. */
+export interface TransferListContextValue {
+    side: TransferSide;
+}
+/** Props for {@link TransferList}, the `role="listbox"` element for one side. */
+export interface TransferListProps extends Omit<PrimitivePropsWithRef<'div'>, 'onChange' | 'defaultValue'> {
+    /** 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`.
+     */
+    children?: React.ReactNode;
+}
+/** Props for {@link TransferListHeader}, the heading naming one list. */
+export interface TransferListHeaderProps extends PrimitivePropsWithRef<'div'> {
+    /** Which side this header names. Must match the `side` of the list it sits beside. */
+    side: TransferSide;
+}
+/** Props for {@link TransferListSearch}, the filter input for one list. */
+export interface TransferListSearchProps extends Omit<PrimitivePropsWithRef<'input'>, 'value' | 'defaultValue' | 'type'> {
+    /** Which of the two sides this input filters the items of. */
+    side: TransferSide;
+}
+/** Props for a single {@link TransferItem} option. */
+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.
+     * @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.
+     */
+    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. */
+export interface TransferMoveTriggerProps extends PrimitivePropsWithRef<'button'> {
+    /** Which way this trigger moves: `'toTarget'` adds to the value, `'toSource'` removes from it. */
+    direction: TransferDirection;
+}
+/** Props for {@link TransferMoveAllTrigger}, which moves every visible item one way. */
+export interface TransferMoveAllTriggerProps extends PrimitivePropsWithRef<'button'> {
+    /** Which way this trigger moves: `'toTarget'` adds to the value, `'toSource'` removes from it. */
+    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. */
+    side: TransferSide;
+}