@skdx/web-components 0.26.0 → 0.28.0

package/dist/transfer/Transfer.d.cts

@@ -1,5 +1,13 @@
 import { LitElement } from 'lit';
-import type { TransferDirection, TransferFilter, TransferItemData, TransferMoveDetail, TransferSide } from './types.cjs';
+import { type SkdxTransferTitles } from './TransferAnatomy.cjs';
+import type { TransferDirection, TransferFilter, TransferFilterMatchMode, TransferItemData, TransferMoveDetail, TransferSearchResultsDetail, TransferSide, TransferTargetOrder } from './types.cjs';
+/** Wording for the two derived Empty states. */
+export interface SkdxTransferEmptyText {
+    /** Text when the side holds no items at all. */
+    empty?: string;
+    /** Text when a search has filtered all items out. {query} is replaced with the search text. */
+    noMatch?: string;
+}
 /** @internal Every option that can hold focus or be moved. Disabled options are skipped by both. */
 export declare const OPTION_SELECTOR = "[role=\"option\"]:not([data-disabled])";
 /** @internal The broadcast every `<skdx-transfer-*>` part subscribes to for re-render. */
@@ -8,57 +16,53 @@ export declare const TRANSFER_INTERNAL_UPDATE = "skdx-transfer-internal-update";
 export declare const ORIGIN_OF: Record<TransferDirection, TransferSide>;
 /** @internal Where a direction takes items *to*. */
 export declare const DESTINATION_OF: Record<TransferDirection, TransferSide>;
-/**
- * @internal The word each side is called in default accessible names and in the
- * move announcement. Deliberately the *same* word in both, so "Move 3 items to
- * selected" and "3 items moved to selected" name the same list.
- */
+/** @internal The word each side is called in default accessible names and the move announcement — deliberately the same word in both. */
 export declare const SIDE_NOUN: Record<TransferSide, string>;
 /**
- * The accessible name of a move trigger: direction *and* count, because "→" is
- * unambiguous next to two labelled lists and meaningless read out on its own.
- *
- * With nothing to move the name says so rather than going silent — the trigger
- * stays focusable (`aria-disabled`, not `disabled`), so it is still the thing
- * that teaches a keyboard user the interaction, and it has to explain why
- * pressing it does nothing.
- *
+ * The accessible name of a move trigger: direction and count, since "→" reads
+ * as nothing on its own. With nothing to move, the name says so instead of
+ * going silent — the trigger stays focusable via `aria-disabled`.
  * @internal
  */
 export declare function moveTriggerLabel(count: number, direction: TransferDirection, all: boolean): string;
-/**
- * The default wording of the post-move announcement. Split out of `move()` so
- * `getMoveAnnouncement` has something to fall back to, and so a consumer can
- * call it for the cases they do not want to re-word.
- */
+/** The default wording of the post-move announcement, split out so `getMoveAnnouncement` has a fallback and consumers can call it directly. */
 export declare function moveAnnouncement({ moved, remaining, from, to }: TransferMoveDetail): string;
+/** The default wording of the search-results announcement, split out so `getSearchResultsAnnouncement` has a fallback for sides left alone. */
+export declare function searchResultsAnnouncement({ shown, total, side, }: TransferSearchResultsDetail): string;
 /** Default `filter`: case-insensitive substring match on the item's `label`. */
 export declare function defaultTransferFilter(item: TransferItemData, query: string): boolean;
+/**
+ * The built-in matcher, parameterised by `filterMatchMode` — a declarative
+ * counterpart to `filter` since a function can't cross the attribute boundary.
+ * Case-insensitive and trimmed in every mode.
+ */
+export declare function matchesFilterMode(item: TransferItemData, query: string, mode?: TransferFilterMatchMode): boolean;
+declare const SkdxTransfer_base: typeof LitElement & (new (...args: any[]) => import("../internal/form-associated.cjs").SkdxFormAssociated) & {
+    formAssociated: boolean;
+};
 /**
  * `<skdx-transfer>` — the Web Components implementation of the shared Transfer
- * contract (see `@skdx/shared`'s `transferContract`): a two-list transfer
- * (also "pick list" or "dual list box"), a pool of items on one side, the
- * chosen ones on the other, and triggers that move items between them.
+ * contract (`@skdx/shared`'s `transferContract`): a two-list transfer ("pick
+ * list"/"dual list box"), a pool of items on one side and the chosen ones on
+ * the other, with triggers that move items between them.
  *
  * Renders only a `<slot>` (`display: contents`); the two `role="listbox"`
  * elements are its `<skdx-transfer-list>` parts.
  *
- * Membership is the only stored state: `value` holds the ids on the target
- * side, and both lists are *derived* from `items` plus that array, so the two
- * sides cannot drift apart. Each list additionally owns a transient
- * marked-for-move multi-selection, which is cleared for whichever side an item
- * leaves.
+ * `value` holds the target-side ids, and both lists are derived from `items`
+ * plus that array so they can't drift apart. Each list also owns a transient
+ * marked-for-move selection, cleared for whichever side an item leaves.
  *
- * Every move is reachable without a pointer. Each list is one Tab stop with its
- * own roving focus, the move triggers are real buttons with names that say
- * direction and count, each move is announced politely, and focus lands on the
- * option that took the moved item's place — never on `<body>`.
+ * Every move is reachable without a pointer: roving-focus lists, named move
+ * triggers, polite announcements, and focus that lands on the option that
+ * took the moved item's place.
  *
- * `items` is a JSON array attribute (Lit's `Array` converter), so a transfer
- * works with no script at all; assign the property for anything dynamic.
+ * `items` is a JSON array attribute (Lit's `Array` converter); assign the
+ * property directly for anything dynamic.
  *
  * @fires value-change - Fired with the new target-side values whenever the selection changes, by a move trigger or by the keyboard.
  * @fires move - Fired alongside `value-change` with `{ items, direction }` — the items that actually moved and which way they went. Marking alone never fires it.
+ * @fires list-scroll - Fired as either list is scrolled, with `{ side, scrollTop, scrollHeight, clientHeight }`, so the next page can be loaded as the list nears its end. Not named `scroll`: the root already has the native one.
  *
  * @example
  * ```html
@@ -78,62 +82,93 @@ export declare function defaultTransferFilter(item: TransferItemData, query: str
  * </skdx-transfer>
  * ```
  */
-export declare class SkdxTransfer extends LitElement {
+export declare class SkdxTransfer extends SkdxTransfer_base {
     static styles: import("lit").CSSResult;
-    /**
-     * The whole pool, on both sides. A JSON array attribute, e.g.
-     * `items='[{"value":"react","label":"React"}]'`; assign the property
-     * directly for anything beyond a static list.
-     */
+    /** The whole pool, on both sides — a JSON array attribute, e.g. `items='[{"value":"react","label":"React"}]'`; assign the property directly for anything dynamic. */
     items: readonly TransferItemData[];
-    /**
-     * The ids currently on the **target** side. The single source of truth, as
-     * on `<skdx-drawer>`: `default-value` seeds it once on connect, and after that
-     * reading or writing this property is how you observe or drive membership.
-     * Listen for `value-change`.
-     */
+    /** The ids currently on the target side — the single source of truth; `default-value` seeds it once on connect. Listen for `value-change`. */
     value: string[];
     /** Initially on the target side, applied once on connect. */
     defaultValue: string[];
     /** Blocks every move and takes the whole widget out of the tab order. */
     disabled: boolean;
     /**
-     * Turns on the per-list filter inputs *and* the filtering itself. One prop
-     * for both, because a filter box that stays on screen but no longer filters
-     * is worse than no box at all.
+     * Form field name; every id on the target side submits as its own entry
+     * under it, so `formData.getAll(name)` returns the whole array.
+     * @default undefined — the widget submits nothing, like a nameless native input.
      */
+    name?: string;
+    /** Turns on both the per-list filter inputs and the filtering itself — one prop for both, since a box that stops filtering is worse than none. */
     searchable: boolean;
     /**
      * Decides whether an item matches a list's filter text. Set as a property.
      * @default defaultTransferFilter — case-insensitive substring match on `label`.
      */
-    filter: TransferFilter;
+    filter?: TransferFilter;
+    /**
+     * How the built-in matcher compares a query against an item's label;
+     * ignored entirely when the `filter` property is set.
+     * @default 'contains'
+     */
+    filterMatchMode: TransferFilterMatchMode;
     /**
-     * Words the accessible name of every `<skdx-transfer-move-trigger>` and
-     * `<skdx-transfer-move-all-trigger>` 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. A function, so
-     * property-only — it cannot come from markup.
+     * Words the accessible name of every move trigger under this root; `count`
+     * includes zero, since a trigger with nothing to move stays focusable. The
+     * only way to translate these names, since they're computed from live counts.
      * @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 — a transfer inside an already-chatty flow sometimes
-     * wants silence rather than a second sentence. A function, so property-only.
+     * 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 The accessible name a move trigger gives itself: this root's
-     * `getMoveLabel` when set, the built-in English wording otherwise. Resolved
-     * here so the triggers never have to know which one is in play.
+     * Words the polite live-region announcement when a list's search query
+     * settles, since filtering changes no attribute a screen reader reports.
+     * Fired per side, only while `searchable`, never for the initial empty query.
+     * @default undefined — the built-in English wording ("4 of 20 items shown in available.").
      */
+    getSearchResultsAnnouncement?: (detail: TransferSearchResultsDetail) => string;
+    /**
+     * Where an item lands on the target side when moved there: `'items'` keeps
+     * collection order, `'append'`/`'prepend'` place it last/first so a moved
+     * row is visible in a long list.
+     * @default 'items'
+     */
+    targetOrder: TransferTargetOrder;
+    /**
+     * Heading text for the derived anatomy's two `SkdxTransferListHeader`s; a side with no
+     * title gets no derived `SkdxTransferListHeader`, falling back to a generic aria-label.
+     * @default undefined — neither side gets a derived heading.
+     */
+    titles?: SkdxTransferTitles;
+    /**
+     * Renders one item's content in a derived `SkdxTransferList`, in place of its default
+     * plain-text label.
+     * @default undefined — renders the item's `label` as plain text.
+     */
+    renderItem?: (item: TransferItemData, state: {
+        side: TransferSide;
+    }) => unknown;
+    /**
+     * Wording for the two derived Empty states: `empty` for no items, `noMatch`
+     * for a search that filtered them all out (its `{query}` is replaced with
+     * the search text). Plain strings so the prop stays a JSON attribute.
+     * @default { empty: 'Nothing here.', noMatch: 'No match for "{query}".' }
+     */
+    emptyText: SkdxTransferEmptyText;
+    /**
+     * Whether the derived Controls include a MoveAllTrigger for each direction.
+     * Off by default: moving every item at once is destructive enough to ask for.
+     * @default false — no MoveAllTrigger buttons in the derived Controls.
+     */
+    showMoveAll: boolean;
+    /** @internal The accessible name a move trigger gives itself: `getMoveLabel` when set, the built-in wording otherwise. */
     moveLabel(count: number, direction: TransferDirection, all: boolean): string;
+    /** @internal The empty text for a given reason and query, merged with defaults. */
+    getEmptyText(reason: 'empty' | 'no-results', query?: string): string;
     /** @internal Unique per instance, so two transfers on a page never share a header id. */
     readonly baseId: string;
     private _marked;
@@ -146,17 +181,24 @@ export declare class SkdxTransfer extends LitElement {
     readonly listEls: Record<TransferSide, HTMLElement | null>;
     private _initialized;
     connectedCallback(): void;
+    private _anatomyBuilt;
+    /**
+     * Draws the canonical anatomy into the light DOM when this element has no
+     * consumer-authored part, and hands back once one appears. Built once;
+     * `<skdx-transfer-list>` derives its own Items on every change so this
+     * never needs to rebuild for that.
+     */
+    private readonly _fillAnatomy;
+    /** Forces a rebuild — for a change (`titles`, `searchable`) that alters the derived structure itself. */
+    private readonly _rebuildAnatomy;
     /** @internal Every item on each side, before filtering. */
     get sideItems(): Record<TransferSide, TransferItemData[]>;
     /** @internal What each side actually renders — `sideItems` narrowed by its query. */
     get visibleItems(): Record<TransferSide, TransferItemData[]>;
     /**
-     * @internal Each side's marked-for-move set.
-     *
-     * Filtered against what the side actually holds: a marked value that has
-     * since moved to the other side would leave that list's selection pointing at
-     * an option it no longer renders — which is exactly how a transfer ends up
-     * with a tab stop that has nowhere to sit.
+     * @internal Each side's marked-for-move set, filtered against what the
+     * side actually holds — otherwise a moved value leaves a tab stop with
+     * nowhere to sit.
      */
     get marked(): Record<TransferSide, string[]>;
     /** @internal */
@@ -165,8 +207,11 @@ export declare class SkdxTransfer extends LitElement {
     getActive(side: TransferSide): string | null;
     /** @internal Whether a `<skdx-transfer-list-header>` exists for a side. */
     isLabelled(side: TransferSide): boolean;
+    private headerIdOverrides;
     /** @internal The DOM id a side's header carries and its list points `aria-labelledby` at. */
     headerId(side: TransferSide): string;
+    /** @internal Lets a side's header republish an author-assigned id. */
+    setHeaderId(side: TransferSide, id: string): void;
     /** @internal The DOM id a side's listbox carries, for the search box's `aria-controls`. */
     listId(side: TransferSide): string;
     /** @internal */
@@ -177,19 +222,23 @@ export declare class SkdxTransfer extends LitElement {
     setActive(side: TransferSide, next: string | null): void;
     /** @internal Called by `<skdx-transfer-list-header>` on connect and disconnect. */
     registerHeader(side: TransferSide, present: boolean): void;
-    /**
-     * @internal Moves `values` one way, then puts focus on whatever took the
-     * first moved option's place.
-     */
+    /** @internal Moves `values` one way, then puts focus on whatever took the first moved option's place. */
     move(direction: TransferDirection, values: string[]): void;
+    /** Focus after a move, once the lists have re-rendered — the option that took the moved one's place doesn't exist before then. */
+    private restoreFocus;
+    /** @internal Publishes one list's scroll geometry as the root's `list-scroll` event. */
+    emitListScroll(side: TransferSide, list: HTMLElement): void;
     /**
-     * Focus after a move, once the lists have re-rendered. Awaiting the update is
-     * this package's equivalent of React's layout effect — the option that took
-     * the moved one's place does not exist until then.
+     * The query each side was last announced for, keyed on the query rather
+     * than the count since two different queries can leave the same row count.
+     * `announce` debounces, so typing a word produces one announcement.
      */
-    private restoreFocus;
+    private readonly announcedQuery;
+    private announceSearchResults;
     /** @internal Tells every part to re-read the root. */
     broadcast(): void;
+    /** Restores the declared `defaultValue`, like a native control's own reset. */
+    formResetCallback(): void;
     protected updated(changed: Map<string, unknown>): void;
     render(): import("lit").TemplateResult<1>;
 }
@@ -198,3 +247,4 @@ declare global {
         'skdx-transfer': SkdxTransfer;
     }
 }
+export {};

package/dist/transfer/Transfer.d.ts

@@ -1,5 +1,13 @@
 import { LitElement } from 'lit';
-import type { TransferDirection, TransferFilter, TransferItemData, TransferMoveDetail, TransferSide } from './types.js';
+import { type SkdxTransferTitles } from './TransferAnatomy.js';
+import type { TransferDirection, TransferFilter, TransferFilterMatchMode, TransferItemData, TransferMoveDetail, TransferSearchResultsDetail, TransferSide, TransferTargetOrder } from './types.js';
+/** Wording for the two derived Empty states. */
+export interface SkdxTransferEmptyText {
+    /** Text when the side holds no items at all. */
+    empty?: string;
+    /** Text when a search has filtered all items out. {query} is replaced with the search text. */
+    noMatch?: string;
+}
 /** @internal Every option that can hold focus or be moved. Disabled options are skipped by both. */
 export declare const OPTION_SELECTOR = "[role=\"option\"]:not([data-disabled])";
 /** @internal The broadcast every `<skdx-transfer-*>` part subscribes to for re-render. */
@@ -8,57 +16,53 @@ export declare const TRANSFER_INTERNAL_UPDATE = "skdx-transfer-internal-update";
 export declare const ORIGIN_OF: Record<TransferDirection, TransferSide>;
 /** @internal Where a direction takes items *to*. */
 export declare const DESTINATION_OF: Record<TransferDirection, TransferSide>;
-/**
- * @internal The word each side is called in default accessible names and in the
- * move announcement. Deliberately the *same* word in both, so "Move 3 items to
- * selected" and "3 items moved to selected" name the same list.
- */
+/** @internal The word each side is called in default accessible names and the move announcement — deliberately the same word in both. */
 export declare const SIDE_NOUN: Record<TransferSide, string>;
 /**
- * The accessible name of a move trigger: direction *and* count, because "→" is
- * unambiguous next to two labelled lists and meaningless read out on its own.
- *
- * With nothing to move the name says so rather than going silent — the trigger
- * stays focusable (`aria-disabled`, not `disabled`), so it is still the thing
- * that teaches a keyboard user the interaction, and it has to explain why
- * pressing it does nothing.
- *
+ * The accessible name of a move trigger: direction and count, since "→" reads
+ * as nothing on its own. With nothing to move, the name says so instead of
+ * going silent — the trigger stays focusable via `aria-disabled`.
  * @internal
  */
 export declare function moveTriggerLabel(count: number, direction: TransferDirection, all: boolean): string;
-/**
- * The default wording of the post-move announcement. Split out of `move()` so
- * `getMoveAnnouncement` has something to fall back to, and so a consumer can
- * call it for the cases they do not want to re-word.
- */
+/** The default wording of the post-move announcement, split out so `getMoveAnnouncement` has a fallback and consumers can call it directly. */
 export declare function moveAnnouncement({ moved, remaining, from, to }: TransferMoveDetail): string;
+/** The default wording of the search-results announcement, split out so `getSearchResultsAnnouncement` has a fallback for sides left alone. */
+export declare function searchResultsAnnouncement({ shown, total, side, }: TransferSearchResultsDetail): string;
 /** Default `filter`: case-insensitive substring match on the item's `label`. */
 export declare function defaultTransferFilter(item: TransferItemData, query: string): boolean;
+/**
+ * The built-in matcher, parameterised by `filterMatchMode` — a declarative
+ * counterpart to `filter` since a function can't cross the attribute boundary.
+ * Case-insensitive and trimmed in every mode.
+ */
+export declare function matchesFilterMode(item: TransferItemData, query: string, mode?: TransferFilterMatchMode): boolean;
+declare const SkdxTransfer_base: typeof LitElement & (new (...args: any[]) => import("../internal/form-associated.js").SkdxFormAssociated) & {
+    formAssociated: boolean;
+};
 /**
  * `<skdx-transfer>` — the Web Components implementation of the shared Transfer
- * contract (see `@skdx/shared`'s `transferContract`): a two-list transfer
- * (also "pick list" or "dual list box"), a pool of items on one side, the
- * chosen ones on the other, and triggers that move items between them.
+ * contract (`@skdx/shared`'s `transferContract`): a two-list transfer ("pick
+ * list"/"dual list box"), a pool of items on one side and the chosen ones on
+ * the other, with triggers that move items between them.
  *
  * Renders only a `<slot>` (`display: contents`); the two `role="listbox"`
  * elements are its `<skdx-transfer-list>` parts.
  *
- * Membership is the only stored state: `value` holds the ids on the target
- * side, and both lists are *derived* from `items` plus that array, so the two
- * sides cannot drift apart. Each list additionally owns a transient
- * marked-for-move multi-selection, which is cleared for whichever side an item
- * leaves.
+ * `value` holds the target-side ids, and both lists are derived from `items`
+ * plus that array so they can't drift apart. Each list also owns a transient
+ * marked-for-move selection, cleared for whichever side an item leaves.
  *
- * Every move is reachable without a pointer. Each list is one Tab stop with its
- * own roving focus, the move triggers are real buttons with names that say
- * direction and count, each move is announced politely, and focus lands on the
- * option that took the moved item's place — never on `<body>`.
+ * Every move is reachable without a pointer: roving-focus lists, named move
+ * triggers, polite announcements, and focus that lands on the option that
+ * took the moved item's place.
  *
- * `items` is a JSON array attribute (Lit's `Array` converter), so a transfer
- * works with no script at all; assign the property for anything dynamic.
+ * `items` is a JSON array attribute (Lit's `Array` converter); assign the
+ * property directly for anything dynamic.
  *
  * @fires value-change - Fired with the new target-side values whenever the selection changes, by a move trigger or by the keyboard.
  * @fires move - Fired alongside `value-change` with `{ items, direction }` — the items that actually moved and which way they went. Marking alone never fires it.
+ * @fires list-scroll - Fired as either list is scrolled, with `{ side, scrollTop, scrollHeight, clientHeight }`, so the next page can be loaded as the list nears its end. Not named `scroll`: the root already has the native one.
  *
  * @example
  * ```html
@@ -78,62 +82,93 @@ export declare function defaultTransferFilter(item: TransferItemData, query: str
  * </skdx-transfer>
  * ```
  */
-export declare class SkdxTransfer extends LitElement {
+export declare class SkdxTransfer extends SkdxTransfer_base {
     static styles: import("lit").CSSResult;
-    /**
-     * The whole pool, on both sides. A JSON array attribute, e.g.
-     * `items='[{"value":"react","label":"React"}]'`; assign the property
-     * directly for anything beyond a static list.
-     */
+    /** The whole pool, on both sides — a JSON array attribute, e.g. `items='[{"value":"react","label":"React"}]'`; assign the property directly for anything dynamic. */
     items: readonly TransferItemData[];
-    /**
-     * The ids currently on the **target** side. The single source of truth, as
-     * on `<skdx-drawer>`: `default-value` seeds it once on connect, and after that
-     * reading or writing this property is how you observe or drive membership.
-     * Listen for `value-change`.
-     */
+    /** The ids currently on the target side — the single source of truth; `default-value` seeds it once on connect. Listen for `value-change`. */
     value: string[];
     /** Initially on the target side, applied once on connect. */
     defaultValue: string[];
     /** Blocks every move and takes the whole widget out of the tab order. */
     disabled: boolean;
     /**
-     * Turns on the per-list filter inputs *and* the filtering itself. One prop
-     * for both, because a filter box that stays on screen but no longer filters
-     * is worse than no box at all.
+     * Form field name; every id on the target side submits as its own entry
+     * under it, so `formData.getAll(name)` returns the whole array.
+     * @default undefined — the widget submits nothing, like a nameless native input.
      */
+    name?: string;
+    /** Turns on both the per-list filter inputs and the filtering itself — one prop for both, since a box that stops filtering is worse than none. */
     searchable: boolean;
     /**
      * Decides whether an item matches a list's filter text. Set as a property.
      * @default defaultTransferFilter — case-insensitive substring match on `label`.
      */
-    filter: TransferFilter;
+    filter?: TransferFilter;
+    /**
+     * How the built-in matcher compares a query against an item's label;
+     * ignored entirely when the `filter` property is set.
+     * @default 'contains'
+     */
+    filterMatchMode: TransferFilterMatchMode;
     /**
-     * Words the accessible name of every `<skdx-transfer-move-trigger>` and
-     * `<skdx-transfer-move-all-trigger>` 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. A function, so
-     * property-only — it cannot come from markup.
+     * Words the accessible name of every move trigger under this root; `count`
+     * includes zero, since a trigger with nothing to move stays focusable. The
+     * only way to translate these names, since they're computed from live counts.
      * @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 — a transfer inside an already-chatty flow sometimes
-     * wants silence rather than a second sentence. A function, so property-only.
+     * 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 The accessible name a move trigger gives itself: this root's
-     * `getMoveLabel` when set, the built-in English wording otherwise. Resolved
-     * here so the triggers never have to know which one is in play.
+     * Words the polite live-region announcement when a list's search query
+     * settles, since filtering changes no attribute a screen reader reports.
+     * Fired per side, only while `searchable`, never for the initial empty query.
+     * @default undefined — the built-in English wording ("4 of 20 items shown in available.").
      */
+    getSearchResultsAnnouncement?: (detail: TransferSearchResultsDetail) => string;
+    /**
+     * Where an item lands on the target side when moved there: `'items'` keeps
+     * collection order, `'append'`/`'prepend'` place it last/first so a moved
+     * row is visible in a long list.
+     * @default 'items'
+     */
+    targetOrder: TransferTargetOrder;
+    /**
+     * Heading text for the derived anatomy's two `SkdxTransferListHeader`s; a side with no
+     * title gets no derived `SkdxTransferListHeader`, falling back to a generic aria-label.
+     * @default undefined — neither side gets a derived heading.
+     */
+    titles?: SkdxTransferTitles;
+    /**
+     * Renders one item's content in a derived `SkdxTransferList`, in place of its default
+     * plain-text label.
+     * @default undefined — renders the item's `label` as plain text.
+     */
+    renderItem?: (item: TransferItemData, state: {
+        side: TransferSide;
+    }) => unknown;
+    /**
+     * Wording for the two derived Empty states: `empty` for no items, `noMatch`
+     * for a search that filtered them all out (its `{query}` is replaced with
+     * the search text). Plain strings so the prop stays a JSON attribute.
+     * @default { empty: 'Nothing here.', noMatch: 'No match for "{query}".' }
+     */
+    emptyText: SkdxTransferEmptyText;
+    /**
+     * Whether the derived Controls include a MoveAllTrigger for each direction.
+     * Off by default: moving every item at once is destructive enough to ask for.
+     * @default false — no MoveAllTrigger buttons in the derived Controls.
+     */
+    showMoveAll: boolean;
+    /** @internal The accessible name a move trigger gives itself: `getMoveLabel` when set, the built-in wording otherwise. */
     moveLabel(count: number, direction: TransferDirection, all: boolean): string;
+    /** @internal The empty text for a given reason and query, merged with defaults. */
+    getEmptyText(reason: 'empty' | 'no-results', query?: string): string;
     /** @internal Unique per instance, so two transfers on a page never share a header id. */
     readonly baseId: string;
     private _marked;
@@ -146,17 +181,24 @@ export declare class SkdxTransfer extends LitElement {
     readonly listEls: Record<TransferSide, HTMLElement | null>;
     private _initialized;
     connectedCallback(): void;
+    private _anatomyBuilt;
+    /**
+     * Draws the canonical anatomy into the light DOM when this element has no
+     * consumer-authored part, and hands back once one appears. Built once;
+     * `<skdx-transfer-list>` derives its own Items on every change so this
+     * never needs to rebuild for that.
+     */
+    private readonly _fillAnatomy;
+    /** Forces a rebuild — for a change (`titles`, `searchable`) that alters the derived structure itself. */
+    private readonly _rebuildAnatomy;
     /** @internal Every item on each side, before filtering. */
     get sideItems(): Record<TransferSide, TransferItemData[]>;
     /** @internal What each side actually renders — `sideItems` narrowed by its query. */
     get visibleItems(): Record<TransferSide, TransferItemData[]>;
     /**
-     * @internal Each side's marked-for-move set.
-     *
-     * Filtered against what the side actually holds: a marked value that has
-     * since moved to the other side would leave that list's selection pointing at
-     * an option it no longer renders — which is exactly how a transfer ends up
-     * with a tab stop that has nowhere to sit.
+     * @internal Each side's marked-for-move set, filtered against what the
+     * side actually holds — otherwise a moved value leaves a tab stop with
+     * nowhere to sit.
      */
     get marked(): Record<TransferSide, string[]>;
     /** @internal */
@@ -165,8 +207,11 @@ export declare class SkdxTransfer extends LitElement {
     getActive(side: TransferSide): string | null;
     /** @internal Whether a `<skdx-transfer-list-header>` exists for a side. */
     isLabelled(side: TransferSide): boolean;
+    private headerIdOverrides;
     /** @internal The DOM id a side's header carries and its list points `aria-labelledby` at. */
     headerId(side: TransferSide): string;
+    /** @internal Lets a side's header republish an author-assigned id. */
+    setHeaderId(side: TransferSide, id: string): void;
     /** @internal The DOM id a side's listbox carries, for the search box's `aria-controls`. */
     listId(side: TransferSide): string;
     /** @internal */
@@ -177,19 +222,23 @@ export declare class SkdxTransfer extends LitElement {
     setActive(side: TransferSide, next: string | null): void;
     /** @internal Called by `<skdx-transfer-list-header>` on connect and disconnect. */
     registerHeader(side: TransferSide, present: boolean): void;
-    /**
-     * @internal Moves `values` one way, then puts focus on whatever took the
-     * first moved option's place.
-     */
+    /** @internal Moves `values` one way, then puts focus on whatever took the first moved option's place. */
     move(direction: TransferDirection, values: string[]): void;
+    /** Focus after a move, once the lists have re-rendered — the option that took the moved one's place doesn't exist before then. */
+    private restoreFocus;
+    /** @internal Publishes one list's scroll geometry as the root's `list-scroll` event. */
+    emitListScroll(side: TransferSide, list: HTMLElement): void;
     /**
-     * Focus after a move, once the lists have re-rendered. Awaiting the update is
-     * this package's equivalent of React's layout effect — the option that took
-     * the moved one's place does not exist until then.
+     * The query each side was last announced for, keyed on the query rather
+     * than the count since two different queries can leave the same row count.
+     * `announce` debounces, so typing a word produces one announcement.
      */
-    private restoreFocus;
+    private readonly announcedQuery;
+    private announceSearchResults;
     /** @internal Tells every part to re-read the root. */
     broadcast(): void;
+    /** Restores the declared `defaultValue`, like a native control's own reset. */
+    formResetCallback(): void;
     protected updated(changed: Map<string, unknown>): void;
     render(): import("lit").TemplateResult<1>;
 }
@@ -198,3 +247,4 @@ declare global {
         'skdx-transfer': SkdxTransfer;
     }
 }
+export {};