@koobiq/components 20.1.0 → 20.3.0

package/list/index.d.ts

@@ -1,24 +1,27 @@
-import * as i0 from '@angular/core';
-import { OnDestroy, OnInit, AfterContentInit, AfterViewInit, QueryList, EventEmitter, ElementRef } from '@angular/core';
-import * as i1 from '@angular/cdk/a11y';
+import * as _angular_core from '@angular/core';
+import { Provider, AfterContentInit, AfterViewInit, OnDestroy, OnInit, ElementRef, QueryList, EventEmitter } from '@angular/core';
+import * as i1$1 from '@angular/cdk/a11y';
 import { FocusMonitor } from '@angular/cdk/a11y';
+import { BooleanInput } from '@angular/cdk/coercion';
 import { SelectionModel } from '@angular/cdk/collections';
+import * as i1 from '@angular/cdk/drag-drop';
+import { CdkDragDrop } from '@angular/cdk/drag-drop';
 import { ControlValueAccessor } from '@angular/forms';
-import * as i2 from '@koobiq/components/core';
-import { IFocusableOption, KbqTitleTextRef, FocusKeyManager, MultipleMode, KbqOptgroup, KbqOptionActionComponent, KbqPseudoCheckbox, KbqLine } from '@koobiq/components/core';
+import * as i3 from '@koobiq/components/core';
+import { FocusKeyManager, IFocusableOption, KbqTitleTextRef, KbqOptgroup, KbqOptionActionComponent, KbqPseudoCheckbox, MultipleMode, KbqLine } from '@koobiq/components/core';
 import { KbqDropdownTrigger } from '@koobiq/components/dropdown';
 import { KbqTooltipTrigger } from '@koobiq/components/tooltip';
-import { Observable, Subject } from 'rxjs';
-import * as i3 from '@koobiq/components/icon';
+import { Subject, Observable } from 'rxjs';
+import * as i4 from '@koobiq/components/icon';
 
-interface KbqOptionEvent {
-    option: KbqListOption;
+interface KbqOptionEvent<T = any> {
+    option: KbqListOption<T>;
 }
-declare const KBQ_SELECTION_LIST_VALUE_ACCESSOR: any;
-declare class KbqListSelectionChange {
-    source: KbqListSelection;
-    option: KbqListOption;
-    constructor(source: KbqListSelection, option: KbqListOption);
+declare const KBQ_SELECTION_LIST_VALUE_ACCESSOR: Provider;
+declare class KbqListSelectionChange<T = any> {
+    source: KbqListSelection<T>;
+    option: KbqListOption<T>;
+    constructor(source: KbqListSelection<T>, option: KbqListOption<T>);
 }
 declare class KbqListSelectAllEvent<T> {
     source: KbqListSelection;
@@ -39,29 +42,105 @@ declare class KbqListCopyEvent<T> {
     event?: KeyboardEvent | undefined;
     constructor(source: KbqListSelection, option: T, event?: KeyboardEvent | undefined);
 }
-declare class KbqListSelection implements AfterContentInit, AfterViewInit, OnDestroy, ControlValueAccessor {
+/**
+ * How the floating copy of an option is rendered while it is dragged.
+ *
+ * `text` shows a compact plate with the option's own text and nothing else, `full` a clone of the
+ * whole row.
+ */
+type KbqListDragPreview = 'text' | 'full';
+/**
+ * Whether a draggable option advertises with the cursor that the whole row can be picked up.
+ *
+ * `auto` leaves the row the cursor it would have anyway, `grab` turns the row into a visible handle.
+ * A projected `cdkDragHandle` takes the grab over either way.
+ */
+type KbqListDragCursor = 'auto' | 'grab';
+/** Event emitted when an option changes its position by dragging. */
+type KbqListSelectionDroppedEvent = Pick<CdkDragDrop<KbqListSelection>, 'previousIndex' | 'currentIndex'> & {
+    /** Option that has been moved. */
+    option: KbqListOption;
+    /** List the option has been moved into. */
+    container: KbqListSelection;
+    /** List the option has been taken from. Equal to `container` when reordering within a single list. */
+    previousContainer: KbqListSelection;
+    /** Pointer event that ended the drag. */
+    event: MouseEvent | TouchEvent;
+};
+declare class KbqListSelection<T = any> implements AfterContentInit, AfterViewInit, OnDestroy, ControlValueAccessor {
     private elementRef;
     private changeDetectorRef;
     private clipboard;
     protected readonly focusMonitor: FocusMonitor;
-    keyManager: FocusKeyManager<KbqListOption>;
-    options: QueryList<KbqListOption>;
-    readonly onSelectAll: i0.OutputEmitterRef<KbqListSelectAllEvent<KbqListOption>>;
-    readonly onCopy: EventEmitter<KbqListCopyEvent<KbqListOption>>;
+    keyManager: FocusKeyManager<KbqListOption<T>>;
+    options: QueryList<KbqListOption<T>>;
+    readonly onSelectAll: _angular_core.OutputEmitterRef<KbqListSelectAllEvent<KbqListOption<T>>>;
+    /**
+     * Kept as a decorator `@Output()`/`EventEmitter` on purpose: `copyActiveOption` branches on
+     * `onCopy.observed` to decide between the consumer handler and the built-in clipboard copy.
+     * `output()` exposes no subscriber introspection, so migrating it would silently run both
+     * paths for every existing `(onCopy)` consumer. Mirrors `KbqTreeSelection.onCopy`.
+     */
+    readonly onCopy: EventEmitter<KbqListCopyEvent<KbqListOption<T>>>;
+    /**
+     * Whether clicking an option clears the rest of the selection.
+     * Stays an accessor input: the constructor turns it off for `multiple="checkbox"`, which a
+     * signal `input()` cannot do (inputs are read-only from inside the component).
+     */
     get autoSelect(): boolean;
     set autoSelect(value: boolean);
     private _autoSelect;
+    /**
+     * Whether the last selected option can be deselected.
+     * Stays an accessor input for the same reason as {@link autoSelect}.
+     */
     get noUnselectLast(): boolean;
     set noUnselectLast(value: boolean);
     private _noUnselectLast;
+    /**
+     * Whether options can be reordered by dragging them.
+     * Reordering never mutates the data — handle the `dropped` event and move the item yourself.
+     */
+    get draggable(): boolean;
+    set draggable(value: boolean);
+    private _draggable;
+    /**
+     * Lists that options of this list can be moved into. Accepts `KbqListSelection` instances or the
+     * `id` of another list. `cdkDropListGroup` on a common ancestor connects lists automatically.
+     */
+    readonly connectedTo: _angular_core.InputSignal<string | KbqListSelection<T> | readonly (string | KbqListSelection<T>)[]>;
+    /**
+     * What the option's floating copy looks like while it is dragged. Defaults to `text`: a compact
+     * plate carrying the option's label and caption, capped at a readable width. Use `full` to drag a
+     * clone of the whole row, checkbox, icons and action button included.
+     */
+    readonly dragPreview: _angular_core.InputSignal<KbqListDragPreview>;
+    /**
+     * Whether a draggable option shows the grab cursor over the whole row. Defaults to `auto`, which
+     * leaves the row the cursor it has anyway. Use `grab` where the whole row is meant to read as a
+     * handle. An option carrying a projected `cdkDragHandle` ignores this — the handle keeps the grab.
+     */
+    readonly dragCursor: _angular_core.InputSignal<KbqListDragCursor>;
+    /** Emits when an option changes its position by dragging. */
+    readonly dropped: _angular_core.OutputEmitterRef<KbqListSelectionDroppedEvent>;
     /** When `true`, a repeated Ctrl/Cmd+A deselects all options. Off by default (Ctrl+A only selects). */
-    readonly selectAllToggle: i0.InputSignalWithTransform<boolean, unknown>;
+    readonly selectAllToggle: _angular_core.InputSignalWithTransform<boolean, unknown>;
     multipleMode: MultipleMode | null;
     get multiple(): boolean;
-    readonly horizontal: i0.InputSignalWithTransform<boolean, unknown>;
-    get tabIndex(): any;
-    set tabIndex(value: any);
+    readonly horizontal: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Tab index of the list.
+     * Stays an accessor input: the getter is derived from {@link disabled} and the setter also
+     * records the user-provided value, which the roving focus logic restores after `tabOut`.
+     */
+    get tabIndex(): number;
+    set tabIndex(value: number);
     private _tabIndex;
+    /**
+     * Whether the list is disabled.
+     * Stays an accessor input: `setDisabledState` writes it from the `ControlValueAccessor`, which a
+     * signal `input()` cannot do.
+     */
     get disabled(): boolean;
     set disabled(value: boolean);
     private _disabled;
@@ -69,51 +148,80 @@ declare class KbqListSelection implements AfterContentInit, AfterViewInit, OnDes
      * Function used for comparing an option against the selected value when determining which
      * options should appear as selected. The first argument is the value of an options. The second
      * one is a value from the selected value. A boolean must be returned.
+     *
+     * Bind a stable reference — a field or a bound method. An expression that builds a new function on
+     * every change detection pass makes the list re-resolve every value against every option each pass.
      */
-    readonly compareWith: i0.InputSignal<(o1: any, o2: any) => boolean>;
+    readonly compareWith: _angular_core.InputSignalWithTransform<(o1: T, o2: T) => boolean, (o1: T, o2: T) => boolean>;
     userTabIndex: number | null;
     get showCheckbox(): boolean;
-    readonly selectionChange: i0.OutputEmitterRef<KbqListSelectionChange>;
-    selectionModel: SelectionModel<KbqListOption>;
-    get optionFocusChanges(): Observable<KbqOptionEvent>;
-    get optionBlurChanges(): Observable<KbqOptionEvent>;
-    _value: string[] | null;
+    readonly selectionChange: _angular_core.OutputEmitterRef<KbqListSelectionChange<T>>;
+    selectionModel: SelectionModel<KbqListOption<T>>;
+    get optionFocusChanges(): Observable<KbqOptionEvent<T>>;
+    get optionBlurChanges(): Observable<KbqOptionEvent<T>>;
+    _value: T[] | null;
     private readonly destroyRef;
     private readonly platform;
-    private optionFocusSubscription;
-    private optionBlurSubscription;
+    private readonly ngZone;
+    private readonly window;
+    private readonly dropList;
+    /**
+     * Distance from the list's content box to the gap the dragged option would land in, or `null`
+     * while no drag is hovering this list. Drives the insertion indicator.
+     */
+    protected readonly dropIndicatorOffset: _angular_core.WritableSignal<number | null>;
+    /** Gap the indicator currently marks, used as `currentIndex` when the drag is dropped here. */
+    private dropIndex;
+    private pendingMoveSubscription;
+    private hasWarnedOnDragContainer;
+    /** Whether a deferred {@link initializeSelection} pass is already queued for this microtask turn. */
+    private pendingSelectionInit;
+    /** Whether a form control has ever written to the list, i.e. whether {@link _value} speaks for a model. */
+    private hasWrittenValue;
     constructor();
     ngAfterContentInit(): void;
     ngAfterViewInit(): void;
     ngOnDestroy(): void;
     focus(): void;
+    /** Clears the active key-manager item (unless an option is still focused) and marks the list as touched. */
     blur(): void;
+    /** Selects every non-disabled option and reports the new value to the `ControlValueAccessor`. */
     selectAll(): void;
+    /** Deselects every option and reports the new value to the `ControlValueAccessor`. */
     deselectAll(): void;
     updateScrollSize(): void;
-    setSelectedOptionsByClick(option: KbqListOption, shiftKey: boolean, ctrlKey: boolean): void;
-    setSelectedOptionsByKey(option: KbqListOption, shiftKey: boolean, ctrlKey: boolean): void;
+    setSelectedOptionsByClick(option: KbqListOption<T>, shiftKey: boolean, ctrlKey: boolean): void;
+    setSelectedOptionsByKey(option: KbqListOption<T>, shiftKey: boolean, ctrlKey: boolean): void;
     selectActiveOptions(): void;
-    writeValue(values: string[]): void;
-    registerOnChange(fn: (value: any) => void): void;
+    writeValue(values: T[] | T | null): void;
+    registerOnChange(fn: (value: T[]) => void): void;
     registerOnTouched(fn: () => void): void;
     setDisabledState(isDisabled: boolean): void;
-    getSelectedOptionValues(): string[];
+    /** Values of the currently selected options. */
+    getSelectedOptionValues(): T[];
     toggleFocusedOption(): void;
-    canDeselectLast(listOption: KbqListOption): boolean;
-    /** @docs-private */
+    /** Whether `listOption` is allowed to be deselected, given {@link noUnselectLast}. */
+    canDeselectLast(listOption: KbqListOption<T>): boolean;
+    /**
+     * Rendered height of the element, or 0 when it is not laid out (SSR, jsdom, `display: none`).
+     * @docs-private
+     */
     getHeight(): number;
     onTouched: () => void;
-    removeOptionFromList(option: KbqListOption): void;
+    removeOptionFromList(option: KbqListOption<T>): void;
     /** Handles keydown events on the list. */
     onKeyDown(event: KeyboardEvent): void;
+    /** Whether the key just handled moved the active option, taking the list orientation into account. */
+    private isNavigationKey;
     reportValueChange(): void;
-    emitChangeEvent(option: KbqListOption): void;
+    emitChangeEvent(option: KbqListOption<T>): void;
     private initializeSelection;
     protected updateTabIndex(): void;
     private onCopyDefaultHandler;
-    private resetOptions;
-    private dropSubscriptions;
+    /**
+     * Re-points the focus/blur streams at the current options every time the query list changes.
+     * `switchMap` tears down the previous `merge` for us, so no manual subscription bookkeeping.
+     */
     private listenToOptionsFocus;
     /** Checks whether any of the options is focused. */
     private hasFocusedOption;
@@ -126,104 +234,243 @@ declare class KbqListSelection implements AfterContentInit, AfterViewInit, OnDes
      */
     private isValidIndex;
     private getOptionIndex;
+    private setupDropListInitialProperties;
+    /**
+     * `CdkDropList` numbers only the options it has rendered, so inside a virtual scroll the indices
+     * `dropped` reports do not address the consumer's backing array and the move silently lands on the
+     * wrong item. Warn instead of letting it pass unnoticed.
+     */
+    private warnOnUnsupportedDragContainer;
+    /** Keeps the underlying CDK directives in sync with the resolved `draggable` state. */
+    private syncDraggableState;
+    private normalizeConnectedTo;
+    private resolveConnectedLists;
+    private resolveConnectedDropLists;
+    /**
+     * Tracks the dragged option and paints the insertion indicator in whichever list the pointer is
+     * over. Lists connected by `id` alone cannot be resolved to an instance, so they never light up.
+     *
+     * @docs-private
+     */
+    onOptionDragMoved(option: KbqListOption, pointer: {
+        x: number;
+        y: number;
+    }): void;
+    /**
+     * Drops the indicator in every list that could be showing one for this drag.
+     *
+     * @docs-private
+     */
+    clearDropIndicators(option: KbqListOption): void;
+    private clearDropIndicator;
+    private containsPoint;
+    /**
+     * Resolves the gap the pointer sits in and positions the indicator on it. Geometry is read on every
+     * move rather than cached at drag start: nothing in the list reflows while dragging, but CDK
+     * auto-scrolls near the edges, which would silently invalidate a cache.
+     */
+    private showDropIndicator;
+    /**
+     * Points the key manager at the option's new place, but only once the consumer has actually applied
+     * the move — the list never reorders its own content, so nothing happens if `dropped` is left
+     * unhandled. `setActiveItem` also re-anchors `previousActiveItemIndex`, which `options.changes`
+     * leaves behind on the slot the option came from and shift-range selection would extend from.
+     */
+    private followMovedOption;
     private onChange;
     /**
      * Function for handling the combination Ctrl + A (select all). By default, the internal handler is used,
      * which toggles the selection of all non-disabled options.
      */
-    get selectAllHandler(): (event: KeyboardEvent, list: KbqListSelection) => void;
-    set selectAllHandler(fn: (event: KeyboardEvent, list: KbqListSelection) => void);
+    get selectAllHandler(): (event: KeyboardEvent, list: KbqListSelection<T>) => void;
+    set selectAllHandler(fn: (event: KeyboardEvent, list: KbqListSelection<T>) => void);
     private _selectAllHandler;
     private copyActiveOption;
-    static ɵfac: i0.ɵɵFactoryDeclaration<KbqListSelection, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<KbqListSelection, "kbq-list-selection", ["kbqListSelection"], { "autoSelect": { "alias": "autoSelect"; "required": false; }; "noUnselectLast": { "alias": "noUnselectLast"; "required": false; }; "selectAllToggle": { "alias": "selectAllToggle"; "required": false; "isSignal": true; }; "horizontal": { "alias": "horizontal"; "required": false; "isSignal": true; }; "tabIndex": { "alias": "tabIndex"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; "compareWith": { "alias": "compareWith"; "required": false; "isSignal": true; }; "selectAllHandler": { "alias": "selectAllHandler"; "required": false; }; }, { "onSelectAll": "onSelectAll"; "onCopy": "onCopy"; "selectionChange": "selectionChange"; }, ["options"], ["*"], true, never>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<KbqListSelection<any>, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<KbqListSelection<any>, "kbq-list-selection", ["kbqListSelection"], { "autoSelect": { "alias": "autoSelect"; "required": false; }; "noUnselectLast": { "alias": "noUnselectLast"; "required": false; }; "draggable": { "alias": "draggable"; "required": false; }; "connectedTo": { "alias": "connectedTo"; "required": false; "isSignal": true; }; "dragPreview": { "alias": "dragPreview"; "required": false; "isSignal": true; }; "dragCursor": { "alias": "dragCursor"; "required": false; "isSignal": true; }; "selectAllToggle": { "alias": "selectAllToggle"; "required": false; "isSignal": true; }; "horizontal": { "alias": "horizontal"; "required": false; "isSignal": true; }; "tabIndex": { "alias": "tabIndex"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; "compareWith": { "alias": "compareWith"; "required": false; "isSignal": true; }; "selectAllHandler": { "alias": "selectAllHandler"; "required": false; }; }, { "onSelectAll": "onSelectAll"; "onCopy": "onCopy"; "dropped": "dropped"; "selectionChange": "selectionChange"; }, ["options"], ["*"], true, [{ directive: typeof i1.CdkDropList; inputs: { "id": "id"; }; outputs: {}; }]>;
+    static ngAcceptInputType_draggable: unknown;
     static ngAcceptInputType_disabled: unknown;
 }
+/**
+ * Marker directive for the secondary line of a `kbq-list-option`.
+ *
+ * Purely a styling hook: it adds the `kbq-list-option-caption` class the list theme keys its
+ * muted caption typography and per-state colors off.
+ */
 declare class KbqListOptionCaption {
-    static ɵfac: i0.ɵɵFactoryDeclaration<KbqListOptionCaption, never>;
-    static ɵdir: i0.ɵɵDirectiveDeclaration<KbqListOptionCaption, "[kbq-list-option-caption]", never, {}, {}, never, never, true, never>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<KbqListOptionCaption, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<KbqListOptionCaption, "[kbq-list-option-caption]", never, {}, {}, never, never, true, never>;
 }
 /**
  * Component for list-options of selection-list. Each list-option can automatically
  * generate a checkbox and can put current item into the selectionModel of selection-list
  * if the current item is selected.
  */
-declare class KbqListOption implements OnDestroy, OnInit, IFocusableOption, KbqTitleTextRef {
+declare class KbqListOption<T = any> implements OnDestroy, OnInit, IFocusableOption, KbqTitleTextRef {
     private elementRef;
     private changeDetector;
     private ngZone;
-    listSelection: KbqListSelection;
+    private readonly drag;
+    private readonly destroyRef;
+    listSelection: KbqListSelection<T>;
     readonly group: KbqOptgroup | null;
     hasFocus: boolean;
     preventBlur: boolean;
-    readonly onFocus: Subject<KbqOptionEvent>;
-    readonly onBlur: Subject<KbqOptionEvent>;
-    readonly actionButton: i0.Signal<KbqOptionActionComponent | undefined>;
+    readonly onFocus: Subject<KbqOptionEvent<T>>;
+    readonly onBlur: Subject<KbqOptionEvent<T>>;
+    readonly actionButton: _angular_core.Signal<KbqOptionActionComponent | undefined>;
     tooltipTrigger?: KbqTooltipTrigger;
     dropdownTrigger?: KbqDropdownTrigger;
-    readonly pseudoCheckbox: i0.Signal<KbqPseudoCheckbox | undefined>;
-    readonly text: i0.Signal<ElementRef<any>>;
+    readonly pseudoCheckbox: _angular_core.Signal<KbqPseudoCheckbox | undefined>;
+    /**
+     * Drag handles the consumer has projected into the option. Nothing else reads them — `CdkDrag`
+     * collects its own through DI — they only tell the option whether the whole row starts a drag.
+     */
+    private readonly dragHandles;
+    readonly text: _angular_core.Signal<ElementRef<any>>;
+    /**
+     * Not a duplicate of {@link text}: this is the `KbqTitleTextRef` property that `title.directive.ts`
+     * reads through `KBQ_TITLE_TEXT_REF`. The interface is a plain `ElementRef`, so it cannot become a
+     * signal query without breaking that contract — same class of constraint as #DS-5079.
+     */
     textElement: ElementRef;
-    readonly checkboxPosition: i0.InputSignal<"before" | "after">;
+    readonly checkboxPosition: _angular_core.InputSignal<"before" | "after">;
     /**
      * This is set to true after the first OnChanges cycle so we don't clear the value of `selected`
      * in the first cycle.
      */
     private inputsInitialized;
-    get value(): any;
-    set value(newValue: any);
+    /**
+     * Value of the option, reported through the list's `ControlValueAccessor`.
+     * Stays an accessor input: the setter drops the selection when the value is replaced.
+     */
+    get value(): T;
+    set value(newValue: T);
     private _value;
-    /** Whether list is disabled. */
+    /**
+     * Whether the option is disabled.
+     * Stays an accessor input: the getter also reports the disabled state inherited from the list
+     * and the option group, which a signal `input()` cannot express.
+     */
     get disabled(): boolean;
     set disabled(value: boolean);
     private _disabled;
-    get showCheckbox(): any;
-    set showCheckbox(value: any);
+    /**
+     * Whether the option can be reordered by dragging. Set it to `false` to pin a single option while
+     * the rest of the list stays draggable. Unrelated to `disabled`: the option keeps taking focus and
+     * selection.
+     *
+     * Stays an accessor input: the getter reports the resolved state, which the option can only narrow —
+     * the list gates its whole drop list, so an option cannot opt back in on its own.
+     */
+    get draggable(): boolean;
+    set draggable(value: boolean);
+    private _draggable;
+    /**
+     * Whether the option renders a pseudo-checkbox.
+     * Stays an accessor input: when unset the getter falls back to the list's own mode.
+     */
+    get showCheckbox(): boolean;
+    set showCheckbox(value: BooleanInput);
     private _showCheckbox;
+    /**
+     * Whether the option is selected.
+     * Stays an accessor input: the state lives in the list's `SelectionModel`, not on the option.
+     */
     get selected(): boolean;
     set selected(value: boolean);
     private _selected;
-    get tabIndex(): any;
-    get externalPseudoCheckbox(): boolean;
+    get tabIndex(): number | null;
+    protected get externalPseudoCheckbox(): boolean;
+    /**
+     * Whether the row itself advertises the grab. Gated on `draggable` so that a pinned option inside a
+     * `dragCursor="grab"` list does not promise a pick-up it would refuse. The handle case is left to
+     * CSS, which already hands the grab over to a projected `cdkDragHandle`.
+     */
+    protected get showsGrabCursor(): boolean;
+    constructor();
+    /**
+     * Keeps the underlying `CdkDrag` in sync with the resolved `draggable` state.
+     *
+     * @docs-private
+     */
+    syncDraggableState(): void;
     ngOnInit(): void;
     ngOnDestroy(): void;
+    /** Toggles the selected state of this option. */
     toggle(): void;
-    getLabel(): any;
+    getLabel(): string;
+    /**
+     * Splits the option's text into the two lines the `text` drag preview shows. The caption is
+     * projected into the same container as the label, so the label is whatever that container holds
+     * apart from the caption — subtracting one string from the other would be guesswork.
+     *
+     * Taken off a clone rather than by walking the container's children, the way `KbqDropdownItem`
+     * drops icons out of its own label: `textContent` on an element skips the comment nodes Angular
+     * leaves behind for its anchors, while reading one of those nodes directly would hand back the
+     * anchor's name.
+     *
+     * Trimmed because `htmlWhitespaceSensitivity: 'ignore'` lets the indentation of the consumer's
+     * template into the projected text.
+     *
+     * @docs-private
+     */
+    getDragPreviewText(): {
+        label: string;
+        caption: string;
+    };
+    /** Sets the selected state directly on the list's `SelectionModel`, bypassing the `selected` input setter. */
     setSelected(selected: boolean): void;
-    /** @docs-private */
+    /**
+     * Rendered height of the element, or 0 when it is not laid out (SSR, jsdom, `display: none`).
+     * @docs-private
+     */
     getHeight(): number;
     /** Handles click events on the list option. */
-    handleClick($event: MouseEvent): void;
-    onKeydown($event: any): void;
+    protected handleClick($event: MouseEvent): void;
+    /** Handles keydown events on the list option. */
+    protected onKeydown($event: KeyboardEvent): void;
+    /** Moves DOM focus to this option, unless it is disabled or already focused. */
     focus(): void;
+    /** Marks this option as blurred once the zone stabilizes, unless {@link preventBlur} is set. */
     blur(): void;
+    /** The option's host DOM element. */
     getHostElement(): HTMLElement;
-    static ɵfac: i0.ɵɵFactoryDeclaration<KbqListOption, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<KbqListOption, "kbq-list-option", ["kbqListOption"], { "checkboxPosition": { "alias": "checkboxPosition"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; "showCheckbox": { "alias": "showCheckbox"; "required": false; }; "selected": { "alias": "selected"; "required": false; }; }, {}, ["actionButton", "pseudoCheckbox", "tooltipTrigger", "dropdownTrigger"], ["kbq-pseudo-checkbox", "[kbq-icon]", "*", "[kbq-list-option-caption]", "kbq-option-action"], true, never>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<KbqListOption<any>, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<KbqListOption<any>, "kbq-list-option", ["kbqListOption"], { "checkboxPosition": { "alias": "checkboxPosition"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; "draggable": { "alias": "draggable"; "required": false; }; "showCheckbox": { "alias": "showCheckbox"; "required": false; }; "selected": { "alias": "selected"; "required": false; }; }, {}, ["actionButton", "pseudoCheckbox", "dragHandles", "tooltipTrigger", "dropdownTrigger"], ["kbq-pseudo-checkbox", "[kbq-icon]", "*", "[kbq-list-option-caption]", "kbq-option-action"], true, [{ directive: typeof i1.CdkDrag; inputs: {}; outputs: {}; }]>;
     static ngAcceptInputType_disabled: unknown;
+    static ngAcceptInputType_draggable: unknown;
     static ngAcceptInputType_selected: unknown;
 }
 
+/**
+ * A plain, non-selectable list container.
+ *
+ * Intentionally carries no ARIA role: it is used both as a semantic list (consumers add
+ * `role="list"` themselves, as `kbq-file-upload` does) and as a purely visual grouping.
+ * For a selectable listbox use `kbq-list-selection` instead.
+ */
 declare class KbqList {
-    static ɵfac: i0.ɵɵFactoryDeclaration<KbqList, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<KbqList, "kbq-list", never, {}, {}, never, ["*"], true, never>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<KbqList, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<KbqList, "kbq-list", never, {}, {}, never, ["*"], true, never>;
 }
+/** A single row of a `kbq-list`. Non-selectable — see `kbq-list-option` for the selectable variant. */
 declare class KbqListItem implements AfterContentInit {
     private elementRef;
     lines: QueryList<KbqLine>;
     ngAfterContentInit(): void;
-    handleFocus(): void;
-    handleBlur(): void;
     getHostElement(): HTMLElement;
-    static ɵfac: i0.ɵɵFactoryDeclaration<KbqListItem, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<KbqListItem, "kbq-list-item, a[kbq-list-item]", never, {}, {}, ["lines"], ["[kbq-list-icon], [mcListIcon]", "[kbq-line], [mcLine]", "*"], true, never>;
+    protected handleFocus(): void;
+    protected handleBlur(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<KbqListItem, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<KbqListItem, "kbq-list-item, a[kbq-list-item]", never, {}, {}, ["lines"], ["[kbq-list-icon], [mcListIcon]", "[kbq-line], [mcLine]", "*"], true, never>;
 }
 
 declare class KbqListModule {
-    static ɵfac: i0.ɵɵFactoryDeclaration<KbqListModule, never>;
-    static ɵmod: i0.ɵɵNgModuleDeclaration<KbqListModule, never, [typeof i1.A11yModule, typeof i2.KbqPseudoCheckboxModule, typeof i2.KbqLine, typeof i2.KbqOptionModule, typeof i2.KbqActionContainer, typeof i3.KbqIconModule, typeof KbqList, typeof KbqListSelection, typeof KbqListItem, typeof KbqListOption, typeof KbqListOptionCaption], [typeof KbqList, typeof KbqListSelection, typeof KbqListItem, typeof KbqListOption, typeof KbqListOptionCaption, typeof i2.KbqOptionModule]>;
-    static ɵinj: i0.ɵɵInjectorDeclaration<KbqListModule>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<KbqListModule, never>;
+    static ɵmod: _angular_core.ɵɵNgModuleDeclaration<KbqListModule, never, [typeof i1$1.A11yModule, typeof i1.CdkDragHandle, typeof i3.KbqPseudoCheckboxModule, typeof i3.KbqLine, typeof i3.KbqOptionModule, typeof i3.KbqActionContainer, typeof i4.KbqIconModule, typeof KbqList, typeof KbqListSelection, typeof KbqListItem, typeof KbqListOption, typeof KbqListOptionCaption], [typeof i1.CdkDragHandle, typeof KbqList, typeof KbqListSelection, typeof KbqListItem, typeof KbqListOption, typeof KbqListOptionCaption, typeof i3.KbqOptionModule]>;
+    static ɵinj: _angular_core.ɵɵInjectorDeclaration<KbqListModule>;
 }
 
 export { KBQ_SELECTION_LIST_VALUE_ACCESSOR, KbqList, KbqListCopyEvent, KbqListItem, KbqListModule, KbqListOption, KbqListOptionCaption, KbqListSelectAllEvent, KbqListSelection, KbqListSelectionChange };
-export type { KbqOptionEvent };
+export type { KbqListDragCursor, KbqListDragPreview, KbqListSelectionDroppedEvent, KbqOptionEvent };

package/list/list-tokens.scss

@@ -9,11 +9,17 @@
     --kbq-list-states-hover-text-color: var(--kbq-foreground-contrast);
     --kbq-list-states-hover-icon-color: var(--kbq-icon-contrast);
     --kbq-list-states-hover-icon-button-color: var(--kbq-icon-contrast-fade);
+    --kbq-list-states-hover-caption-color: var(--kbq-foreground-contrast-secondary);
     --kbq-list-states-selected-container-background: var(--kbq-background-theme-less);
     --kbq-list-multiple-states-selected-container-background: var(--kbq-background-contrast-less);
     --kbq-list-states-selected-text-color: var(--kbq-foreground-contrast);
     --kbq-list-states-selected-icon-color: var(--kbq-icon-contrast);
     --kbq-list-states-selected-icon-button-color: var(--kbq-icon-contrast-fade);
+    --kbq-list-states-selected-caption-color: var(--kbq-foreground-contrast-secondary);
+    --kbq-list-multiple-states-selected-text-color: var(--kbq-foreground-contrast);
+    --kbq-list-multiple-states-selected-icon-color: var(--kbq-icon-contrast);
+    --kbq-list-multiple-states-selected-icon-button-color: var(--kbq-icon-contrast-fade);
+    --kbq-list-multiple-states-selected-caption-color: var(--kbq-foreground-contrast-secondary);
     --kbq-list-states-selected-hover-container-background: var(--kbq-states-background-theme-less-hover);
     --kbq-list-multiple-states-selected-hover-container-background: var(--kbq-states-background-contrast-less-hover);
     --kbq-list-states-selected-active-container-background: var(--kbq-states-background-theme-less-active);
@@ -21,28 +27,57 @@
     --kbq-list-states-selected-hover-text-color: var(--kbq-foreground-contrast);
     --kbq-list-states-selected-hover-icon-color: var(--kbq-icon-contrast);
     --kbq-list-states-selected-hover-icon-button-color: var(--kbq-icon-contrast-fade);
+    --kbq-list-states-selected-hover-caption-color: var(--kbq-foreground-contrast-secondary);
+    --kbq-list-multiple-states-selected-hover-text-color: var(--kbq-foreground-contrast);
+    --kbq-list-multiple-states-selected-hover-icon-color: var(--kbq-icon-contrast);
+    --kbq-list-multiple-states-selected-hover-icon-button-color: var(--kbq-icon-contrast-fade);
+    --kbq-list-multiple-states-selected-hover-caption-color: var(--kbq-foreground-contrast-secondary);
     --kbq-list-states-focused-focus-outline-color: var(--kbq-states-line-focus-theme);
     --kbq-list-states-disabled-container-background: transparent;
     --kbq-list-states-disabled-text-color: var(--kbq-states-foreground-disabled);
     --kbq-list-states-disabled-icon-color: var(--kbq-states-icon-disabled);
     --kbq-list-states-disabled-icon-button-color: var(--kbq-states-icon-disabled);
     --kbq-list-states-disabled-caption-color: var(--kbq-states-foreground-disabled);
+    // The dragged clone floats over the page, so unlike an option in place it needs an opaque surface.
+    --kbq-list-states-dragged-container-background: var(--kbq-background-card);
+    --kbq-list-states-dragged-container-shadow: var(--kbq-shadow-popup);
 }
 
 .kbq-list,
-.kbq-list-selection {
+.kbq-list-selection,
+// The drag preview is inserted into `<body>`, outside any list, so it has to carry the tokens
+// itself — otherwise every themed color below resolves to nothing. Both shapes of it: the clone of
+// the option, and the plate of its text.
+.kbq-list-option.cdk-drag-preview,
+.kbq-list-drag-preview_text {
+    /* SIZE TOKENS — consumed by `.kbq-list-item` / `.kbq-list-option` in list.scss */
     --kbq-list-size-container-padding-left: var(--kbq-size-m);
     --kbq-list-size-container-padding-right: var(--kbq-size-m);
-    --kbq-list-size-container-padding-vertical: var(--kbq-size-xs);
+    --kbq-list-size-container-padding-vertical: var(--kbq-size-xxs);
     --kbq-list-size-container-content-gap-horizontal: var(--kbq-size-s);
     --kbq-list-size-container-content-gap-vertical: var(--kbq-size-3xs);
     --kbq-list-size-container-focus-outline-width: var(--kbq-size-3xs);
-    --kbq-list-size-header-padding-top: var(--kbq-size-s);
-    --kbq-list-size-header-padding-bottom: var(--kbq-size-xxs);
-    --kbq-list-size-header-padding-horizontal: var(--kbq-size-m);
-    --kbq-list-size-subheading-padding-top: var(--kbq-size-m);
-    --kbq-list-size-subheading-padding-bottom: var(--kbq-size-xxs);
-    --kbq-list-size-subheading-padding-horizontal: var(--kbq-size-m);
     /* THEME TOKENS */
     @include list-theme-tokens;
 }
+
+// Declared here rather than in `list-theme-tokens`, which is also included by the option and dropdown
+// token files: the insertion indicator only ever exists on `kbq-list-selection`. The colour still
+// follows the theme, because the global token it points at does.
+.kbq-list-selection {
+    --kbq-list-size-dragged-indicator-thickness: var(--kbq-size-3xs);
+    --kbq-list-states-dragged-indicator-color: var(--kbq-line-theme);
+}
+
+// Also kept out of `list-theme-tokens`: only the text preview has a width of its own to cap, and only
+// it is meant to let through what it covers — the clone stays on the opaque surface declared above.
+// Mixed rather than taken from `--kbq-background-overlay-inverse`, which reads as a scrim and turns
+// black in the dark theme; the preview is a card that lets a little through, so the card is the base.
+.kbq-list-drag-preview_text {
+    --kbq-list-size-drag-preview-max-width: 480px;
+    --kbq-list-states-drag-preview-background: color-mix(
+        in srgb,
+        var(--kbq-background-card) /* color-mix only allows percentage value */ calc(var(--kbq-opacity-overlay) * 100%),
+        transparent
+    );
+}