@orangelogic/design-system 3.18.0 → 3.19.0

package/library/packages/atoms/src/components/color-picker/color-picker.d.ts

@@ -1,13 +1,20 @@
 import { CortexFormControl, default as CortexElement } from '../../../../base/src/cortex-element.ts';
-import { ColorFormat } from '../../../../types/src/color-picker';
+import { ColorFormat, ColorPickerMode, GradientType } from '../../../../types/src/color-picker';
 import { CSSResultGroup } from 'lit';
 import { default as CxButton } from '../button/button';
 import { default as CxButtonGroup } from '../button-group/button-group';
 import { default as CxDropdown } from '../dropdown/dropdown';
 import { default as CxIcon } from '../icon/icon';
 import { default as CxInput } from '../input/input';
+import { default as CxOption } from '../option/option';
+import { default as CxSelect } from '../select/select';
 import { default as CxSpinner } from '../spinner/spinner';
+import { default as CxTab } from '../tab/tab';
+import { default as CxTabGroup } from '../tab-group/tab-group';
+import { default as CxTabPanel } from '../tab-panel/tab-panel';
 import { default as CxVisuallyHidden } from '../visually-hidden/visually-hidden';
+import { default as CxGradientSlider } from './components/gradient-slider/gradient-slider';
+import { default as CxGradientStopList } from './components/gradient-stop-list/gradient-stop-list';
 
 /**
  * @summary Color pickers allow the user to select a color.
@@ -52,6 +59,15 @@ import { default as CxVisuallyHidden } from '../visually-hidden/visually-hidden'
  * @csspart format-button__label - The format button’s exported `label` part.
  * @csspart format-button__suffix - The format button’s exported `suffix` part.
  * @csspart format-button__caret - The format button’s exported `caret` part.
+ * @csspart gradient-slider - The gradient preview bar shown in the Gradient tab.
+ * @csspart gradient-track - The gradient slider’s exported `track` part.
+ * @csspart gradient-marker - The gradient slider’s exported `marker` part.
+ * @csspart gradient-stop-list - The list of editable stop rows.
+ * @csspart gradient-stop-row - The stop list’s exported `row` part.
+ * @csspart gradient-add-stop-button - The stop list’s exported `add-button` part.
+ * @csspart gradient-delete-stop-button - The stop list’s exported `delete-button` part.
+ * @csspart gradient-type-select - The gradient type select (Linear / Radial).
+ * @csspart gradient-angle-input - The gradient angle input.
  *
  * @cssproperty --grid-width - The width of the color grid.
  * @cssproperty --grid-height - The height of the color grid.
@@ -73,9 +89,16 @@ export default class CxColorPicker extends CortexElement implements CortexFormCo
         'cx-button': typeof CxButton;
         'cx-button-group': typeof CxButtonGroup;
         'cx-dropdown': typeof CxDropdown;
+        'cx-gradient-slider': typeof CxGradientSlider;
+        'cx-gradient-stop-list': typeof CxGradientStopList;
         'cx-icon': typeof CxIcon;
         'cx-input': typeof CxInput;
+        'cx-option': typeof CxOption;
+        'cx-select': typeof CxSelect;
         'cx-spinner': typeof CxSpinner;
+        'cx-tab': typeof CxTab;
+        'cx-tab-group': typeof CxTabGroup;
+        'cx-tab-panel': typeof CxTabPanel;
         'cx-visually-hidden': typeof CxVisuallyHidden;
     };
     private readonly formControlController;
@@ -85,6 +108,7 @@ export default class CxColorPicker extends CortexElement implements CortexFormCo
     input: CxInput;
     opacityInput: CxInput;
     dropdown: CxDropdown;
+    tabGroup: CxTabGroup;
     previewButton: HTMLButtonElement;
     trigger: HTMLButtonElement;
     private hasFocus;
@@ -96,6 +120,14 @@ export default class CxColorPicker extends CortexElement implements CortexFormCo
     private saturation;
     private brightness;
     private alpha;
+    /** The gradient being edited in the Gradient tab. */
+    private gradientValue;
+    /** The id of the gradient stop that the color controls currently edit. */
+    private activeStopId;
+    /** `swatches` parsed into a list, derived whenever that property changes. */
+    private parsedSwatches;
+    /** `customSwatches` parsed into a list, derived whenever that property changes. */
+    private parsedCustomSwatches;
     /**
      * The current value of the color picker. The value's format will vary based the `format` attribute. To get the value
      * in a specific format, use the `getFormattedValue()` method. The value is submitted as a name/value pair with form
@@ -128,6 +160,21 @@ export default class CxColorPicker extends CortexElement implements CortexFormCo
     emitFormat: ColorFormat | undefined;
     /** Renders the color picker inline rather than in a dropdown. */
     inline: boolean;
+    /**
+     * Adds a Gradient tab alongside the Solid tab. When the Gradient tab is active, `value` holds a
+     * CSS gradient string (e.g. `linear-gradient(90deg, #f00 0%, #00f 100%)`) instead of a single color.
+     */
+    gradient: boolean;
+    /**
+     * Which editing surface is active. Set automatically when `value` is assigned a gradient string,
+     * and when the user switches tabs. Has no effect unless `gradient` is enabled.
+     */
+    mode: ColorPickerMode;
+    /**
+     * The gradient types offered in the Gradient tab.
+     * Pass a space-separated string (e.g., "linear radial") or an array of gradient type values.
+     */
+    gradientTypes: GradientType[];
     /** Determines the size of the color picker's trigger. This has no effect on inline color pickers. */
     size: 'small' | 'medium' | 'large';
     /** Removes the button that lets users toggle between format.   */
@@ -178,10 +225,21 @@ export default class CxColorPicker extends CortexElement implements CortexFormCo
      * Pairing value with emitFormat attribute. This is used to emit the value in a wanted format.
      */
     emitValue: string;
-    /** Gets the validity state object */
+    /**
+     * Gets the validity state object.
+     *
+     * The text input lives in the Solid tab's controls, so it is absent while the Gradient tab
+     * is showing. `FormControlController` still polls this, so fall back to the host's own
+     * validity rather than dereferencing a missing input.
+     */
     get validity(): ValidityState;
     /** Gets the validation message */
     get validationMessage(): string;
+    /**
+     * Validity for the states this component can judge without the text input: a required
+     * control needs a value.
+     */
+    private get formValidity();
     constructor();
     runFirstUpdated(): void;
     private handleCopy;
@@ -208,6 +266,49 @@ export default class CxColorPicker extends CortexElement implements CortexFormCo
     private parseColor;
     private setColor;
     private setLetterCase;
+    /**
+     * Adopts an externally assigned CSS gradient string as the current gradient.
+     * @param value - The gradient string, already known to be parseable in shape.
+     */
+    private adoptGradientValue;
+    /** True when the Gradient tab is enabled and active. */
+    private get isGradientMode();
+    /** The gradient stop the color controls currently edit, if any. */
+    private get activeStop();
+    /**
+     * Writes the current HSVA state into the active stop and republishes `value` as a CSS
+     * gradient string.
+     * @param currentColor - The parsed color represented by the current HSVA state.
+     */
+    private syncGradientValue;
+    /**
+     * Formats the active stop's color for the text input, honoring the current format.
+     * @param currentColor - The parsed color represented by the current HSVA state.
+     * @returns The formatted color string.
+     */
+    private getStopInputValue;
+    /**
+     * Loads a stop's color into the HSVA controls without writing back to `value`.
+     * @param stop - The stop to load.
+     */
+    private loadStopIntoControls;
+    /**
+     * Publishes the current gradient as `value` without letting the `value` watcher re-adopt
+     * it. Re-adopting would re-parse the string and mint fresh stop ids, which destroys the
+     * marker being dragged; `isSafeValue` is the existing guard for "this component wrote
+     * `value` itself", and it must always be cleared again once the update settles.
+     */
+    private publishGradientValue;
+    /**
+     * Replaces the gradient's stops, republishes `value`, and keeps the active stop valid.
+     * @param stops - The next set of stops.
+     */
+    private applyGradientStops;
+    /**
+     * Seeds a two-stop gradient from the current solid color so switching to the Gradient tab
+     * starts from something visible rather than an empty bar.
+     */
+    private seedGradientFromCurrentColor;
     private syncValues;
     private handleAfterHide;
     private handleEyeDropper;
@@ -222,8 +323,39 @@ export default class CxColorPicker extends CortexElement implements CortexFormCo
      */
     private getFormatFromValue;
     private stopNestedEventPropagation;
+    private handleTabShow;
+    /** Moves editing to the Gradient tab, seeding stops on first use. */
+    private switchToGradientMode;
+    /** Moves editing back to the Solid tab, keeping the active stop's color. */
+    private switchToSolidMode;
+    private handleGradientStopSelect;
+    private handleGradientStopAdd;
+    private handleGradientStopRemove;
+    private handleGradientStopChange;
+    private handleGradientChange;
+    private handleGradientTypeSelect;
+    private handleGradientTypeChange;
+    private handleGradientAngleInput;
     handleFormatChange(): void;
     handleOpacityChange(): void;
+    /**
+     * Parses a swatch list once per change rather than on every render. `render()` used to
+     * split and filter these strings itself, which repeated the work on every update — and
+     * the gradient tab re-renders on every pointer move while a stop is dragged.
+     * @param value - The raw property value, either a delimited string or an array.
+     * @returns The individual color strings.
+     */
+    private parseSwatchList;
+    handleSwatchesChange(): void;
+    handleCustomSwatchesChange(): void;
+    /**
+     * Keeps the tab group in step when `mode` is set programmatically (for example by assigning a
+     * gradient string to `value`). Without this the panel stays hidden, and a hidden panel has no
+     * layout, so the grid and sliders inside it would measure zero.
+     */
+    handleModeChange(): Promise<void>;
+    /** Selects the tab panel matching the current mode. */
+    private syncTabToMode;
     handleValueChange(oldValue: string | undefined, newValue: string): void;
     /** Sets focus on the color picker. */
     focus(options?: FocusOptions): void;
@@ -240,6 +372,32 @@ export default class CxColorPicker extends CortexElement implements CortexFormCo
     /** Sets a custom validation message. Pass an empty string to restore validity. */
     setCustomValidity(message: string): void;
     renderSwatches(swatches: string[]): ("" | import('lit').TemplateResult<1>)[];
+    /**
+     * Renders one gradient type toggle. The type travels on a data attribute so the click
+     * handler can stay a bound method rather than a per-render arrow function.
+     * @param type - The gradient type this button selects.
+     */
+    /**
+     * Returns a gradient type's user-facing name.
+     * @param type - The gradient type to label.
+     */
+    private getGradientTypeLabel;
+    /**
+     * Renders the gradient type selector and, for linear gradients, the angle input.
+     */
+    private renderGradientOptions;
+    /**
+     * Renders the shared color controls, wrapped in a Solid / Gradient tab group when the
+     * gradient tab is enabled. When it is not, the controls render exactly as they always have,
+     * so existing consumers see an unchanged DOM.
+     */
+    private renderTabsOrControls;
+    /**
+     * Renders the color grid, hue/alpha sliders, and the text inputs. These controls are shared
+     * by both tabs: in Solid mode they edit `value` directly, and in Gradient mode they edit the
+     * active gradient stop.
+     */
+    private renderColorControls;
     render(): import('lit').TemplateResult<1>;
 }
 declare global {

package/library/packages/atoms/src/components/color-picker/components/gradient-slider/gradient-slider.d.ts

@@ -0,0 +1,80 @@
+import { default as CortexElement } from '../../../../../../base/src/cortex-element.ts';
+import { GradientStop } from '../../../../../../types/src/color-picker';
+import { CSSResultGroup } from 'lit';
+
+/**
+ * @summary Renders a gradient preview bar with draggable stop markers.
+ *
+ * @description An internal building block for `cx-color-picker`'s gradient tab. The bar is a
+ * preview plus a positioning control: markers select and reposition stops, while adding and
+ * removing them belongs to the stop list beside it. The component is fully controlled — it
+ * renders the `stops` it is given and reports intent through events, and every event carries
+ * the complete next set of stops so the owner can assign it straight back to `stops`.
+ *
+ * @event {{ id: string }} cx-gradient-stop-select - Emitted when a marker becomes the active stop.
+ * @event {{ stops: GradientStop[] }} cx-gradient-stop-change - Emitted continuously while a marker is dragged.
+ * @event {{ stops: GradientStop[] }} cx-gradient-change - Emitted when a position change is committed.
+ * @event {{ id: string }} cx-gradient-stop-remove - Emitted when a stop is removed with the keyboard.
+ *
+ * @csspart base - The component's base wrapper.
+ * @csspart track - The gradient preview bar.
+ * @csspart marker - Each individual stop marker.
+ *
+ * @cssproperty [--gradient-track-height=28px] - The height of the gradient bar.
+ * @cssproperty [--gradient-marker-size=20px] - The size of each stop marker.
+ * @cssproperty [--gradient-marker-tail=6px] - The size of the marker's pointer tail.
+ */
+export default class CxGradientSlider extends CortexElement {
+    static readonly styles: CSSResultGroup;
+    private readonly localize;
+    /** The gradient's color stops. Rendered in sorted order without mutating the input. */
+    stops: GradientStop[];
+    /** The id of the stop currently being edited. */
+    activeStopId: string;
+    /** Disables interaction with the markers. */
+    disabled: boolean;
+    /** The id of the marker being dragged, used only to drive the grabbing cursor. */
+    private draggingStopId;
+    /** False once the gradient is down to the minimum number of stops. */
+    private get canRemoveStop();
+    /**
+     * Selects a stop, making it the target of the picker's color controls.
+     * @param id - The stop to select.
+     */
+    private selectStop;
+    /**
+     * Moves a stop to a new position and reports the resulting set of stops.
+     * @param id - The stop to move.
+     * @param position - The new position, clamped to 0-100.
+     * @param commit - Whether this is the final position rather than an intermediate drag frame.
+     */
+    private moveStop;
+    /**
+     * Removes a stop, refusing when doing so would leave fewer than the minimum.
+     * @param id - The stop to remove.
+     */
+    private removeStop;
+    /**
+     * Converts a pointer offset within the bar into a stop position.
+     * @param offsetX - The pointer's horizontal offset from the bar's left edge.
+     * @param trackWidth - The bar's rendered width.
+     * @returns The equivalent position, 0-100.
+     */
+    private getPositionFromOffset;
+    private handleMarkerPointerDown;
+    private handleMarkerKeyDown;
+    /**
+     * Builds the CSS gradient shown on the bar. The preview is always left-to-right regardless
+     * of the gradient's real type, because the bar represents the gradient line itself rather
+     * than its rendered orientation.
+     * @param sortedStops - The stops in ascending position order.
+     * @returns A CSS gradient string.
+     */
+    private getTrackBackground;
+    render(): import('lit').TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'cx-gradient-slider': CxGradientSlider;
+    }
+}

package/library/packages/atoms/src/components/color-picker/components/gradient-slider/gradient-slider.styles.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import('lit').CSSResult;
+export default _default;

package/library/packages/atoms/src/components/color-picker/components/gradient-stop-list/gradient-stop-list.d.ts

@@ -0,0 +1,85 @@
+import { default as CortexElement } from '../../../../../../base/src/cortex-element.ts';
+import { GradientStop } from '../../../../../../types/src/color-picker';
+import { CSSResultGroup } from 'lit';
+import { default as CxButton } from '../../../button/button';
+import { default as CxDropdown } from '../../../dropdown/dropdown';
+import { default as CxIcon } from '../../../icon/icon';
+import { default as CxIconButton } from '../../../icon-button/icon-button';
+import { default as CxInput } from '../../../input/input';
+
+/**
+ * @summary Lists a gradient's color stops as editable rows.
+ *
+ * @description An internal building block for `cx-color-picker`'s gradient tab. Each row edits
+ * one stop's hex, opacity, and position, and can delete it. Like `cx-gradient-slider`, the
+ * component is fully controlled and every event carries the complete next set of stops.
+ *
+ * @event {{ id: string }} cx-gradient-stop-select - Emitted when a row becomes the active stop.
+ * @event {{ color: string, position: number }} cx-gradient-stop-add - Emitted when a stop is added.
+ * @event {{ id: string }} cx-gradient-stop-remove - Emitted when a stop is deleted.
+ * @event {{ stops: GradientStop[] }} cx-gradient-change - Emitted when a row's field is committed.
+ *
+ * @csspart base - The component's base wrapper.
+ * @csspart header - The row holding the title and the add button.
+ * @csspart add-button - The button that appends a stop.
+ * @csspart row - Each stop's row.
+ * @csspart hex-input - A row's hex input.
+ * @csspart swatch - A row's color chip.
+ * @csspart opacity-input - A row's opacity input.
+ * @csspart position-input - A row's position input.
+ * @csspart delete-button - A row's delete button.
+ *
+ * @cssproperty [--stop-swatch-size=28px] - The size of each row's color chip.
+ * @cssproperty [--stop-list-max-height=168px] - The height at which the rows start scrolling.
+ */
+export default class CxGradientStopList extends CortexElement {
+    static readonly styles: CSSResultGroup;
+    static readonly dependencies: {
+        'cx-button': typeof CxButton;
+        'cx-dropdown': typeof CxDropdown;
+        'cx-icon': typeof CxIcon;
+        'cx-icon-button': typeof CxIconButton;
+        'cx-input': typeof CxInput;
+    };
+    private readonly localize;
+    /** The gradient's color stops. Rendered in sorted order without mutating the input. */
+    stops: GradientStop[];
+    /** The id of the stop currently being edited. */
+    activeStopId: string;
+    /** Disables every control in the list. */
+    disabled: boolean;
+    /** False once the gradient is down to the minimum number of stops. */
+    private get canRemoveStop();
+    /**
+     * Reads a row's stop id from the element that raised an event.
+     * @param event - The event whose `currentTarget` carries the id.
+     * @returns The stop id, or an empty string when the attribute is missing.
+     */
+    private getStopId;
+    /**
+     * Replaces one stop and reports the resulting set.
+     * @param id - The stop to change.
+     * @param changes - The fields to overwrite.
+     */
+    private commitStopChange;
+    private handleRowClick;
+    private handleAddClick;
+    private handleDropdownClick;
+    private handlePickerInput;
+    private handleDeleteClick;
+    private handleHexChange;
+    private handleOpacityChange;
+    private handlePositionChange;
+    /**
+     * Renders one stop's row of fields.
+     * @param stop - The stop this row edits.
+     * @param index - The stop's position in the sorted list, used for labelling.
+     */
+    private renderRow;
+    render(): import('lit').TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'cx-gradient-stop-list': CxGradientStopList;
+    }
+}

package/library/packages/atoms/src/components/color-picker/components/gradient-stop-list/gradient-stop-list.styles.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import('lit').CSSResult;
+export default _default;

package/library/packages/atoms/src/components/input/input.d.ts

@@ -21,7 +21,7 @@ import { default as CxIcon } from '../icon/icon';
  * @event cx-focus - Emitted when the control gains focus.
  * @event cx-input - Emitted when the control receives input.
  * @event cx-invalid - Emitted when the form control has been checked for validity and its constraints aren't satisfied.
- * @event cx-keydown - Emitted when a key is pressed down on the control.
+ * @event {{ event: KeyboardEvent; value: string }} cx-keydown - Emitted when a key is pressed down on the control.
  *
  * @csspart form-control - The form control that wraps the label, input, and help text.
  * @csspart form-control-label - The label’s wrapper.

package/library/packages/atoms/src/components/option/option.d.ts

@@ -19,7 +19,7 @@ import { default as CxSpace } from '../space/space';
  * @csspart suffix - The container that wraps the suffix.
  *
  * @cssproperty [--option-color=var(--cx-color-neutral-700)] - The option's color.
- * @cssproperty [--option-current-background-color=transparent] - The background color of the option under the keyboard cursor (`aria-activedescendant`). Only one option is current at a time, and it is not necessarily the selected one.
+ * @cssproperty [--option-current-background-color=var(--cx-menu-item-background-color-hover)] - The background color of the option under the keyboard cursor (`aria-activedescendant`). Only one option is current at a time, and it is not necessarily the selected one.
  * @cssproperty [--option-font-weight=var(--cx-font-weight-regular)] - The option's font weight.
  * @cssproperty [--option-help-text-color=var(--cx-color-neutral-600)] - The option's help text color.
  * @cssproperty [--option-help-text-font-weight=var(--cx-font-weight-regular)] - The option's help text font weight.

package/library/packages/events/src/cx-gradient-change.d.ts

@@ -0,0 +1,10 @@
+import { GradientStop } from '../../types/src/color-picker';
+
+export type CxGradientChangeEvent = CustomEvent<{
+    stops: GradientStop[];
+}>;
+declare global {
+    interface GlobalEventHandlersEventMap {
+        'cx-gradient-change': CxGradientChangeEvent;
+    }
+}

package/library/packages/events/src/cx-gradient-stop-add.d.ts

@@ -0,0 +1,9 @@
+export type CxGradientStopAddEvent = CustomEvent<{
+    color: string;
+    position: number;
+}>;
+declare global {
+    interface GlobalEventHandlersEventMap {
+        'cx-gradient-stop-add': CxGradientStopAddEvent;
+    }
+}

package/library/packages/events/src/cx-gradient-stop-change.d.ts

@@ -0,0 +1,10 @@
+import { GradientStop } from '../../types/src/color-picker';
+
+export type CxGradientStopChangeEvent = CustomEvent<{
+    stops: GradientStop[];
+}>;
+declare global {
+    interface GlobalEventHandlersEventMap {
+        'cx-gradient-stop-change': CxGradientStopChangeEvent;
+    }
+}

package/library/packages/events/src/cx-gradient-stop-remove.d.ts

@@ -0,0 +1,8 @@
+export type CxGradientStopRemoveEvent = CustomEvent<{
+    id: string;
+}>;
+declare global {
+    interface GlobalEventHandlersEventMap {
+        'cx-gradient-stop-remove': CxGradientStopRemoveEvent;
+    }
+}

package/library/packages/events/src/cx-gradient-stop-select.d.ts

@@ -0,0 +1,8 @@
+export type CxGradientStopSelectEvent = CustomEvent<{
+    id: string;
+}>;
+declare global {
+    interface GlobalEventHandlersEventMap {
+        'cx-gradient-stop-select': CxGradientStopSelectEvent;
+    }
+}

package/library/packages/events/src/cx-keydown.d.ts

@@ -1,4 +1,7 @@
-export type CxKeydownEvent = CustomEvent<Record<PropertyKey, never>>;
+export type CxKeydownEvent = CustomEvent<{
+    event: KeyboardEvent;
+    value: string;
+}>;
 declare global {
     interface GlobalEventHandlersEventMap {
         'cx-keydown': CxKeydownEvent;

package/library/packages/events/src/events.d.ts

@@ -101,6 +101,11 @@ export * from './cx-gallery-item-open-config';
 export * from './cx-gallery-item-select';
 export * from './cx-gallery-lightbox-hide';
 export * from './cx-gallery-lightbox-show';
+export * from './cx-gradient-change';
+export * from './cx-gradient-stop-add';
+export * from './cx-gradient-stop-change';
+export * from './cx-gradient-stop-remove';
+export * from './cx-gradient-stop-select';
 export * from './cx-hide';
 export * from './cx-hover';
 export * from './cx-hub-connection-disconnected';

package/library/packages/molecules/src/multi-select/components/board/board.d.ts

@@ -1,21 +1,34 @@
+import { default as CxDivider } from '../../../../../atoms/src/components/divider/divider.ts';
 import { default as CxIcon } from '../../../../../atoms/src/components/icon/icon.ts';
 import { default as CxIconButton } from '../../../../../atoms/src/components/icon-button/icon-button.ts';
 import { default as CxInput } from '../../../../../atoms/src/components/input/input.ts';
 import { default as CxTooltip } from '../../../../../atoms/src/components/tooltip/tooltip.ts';
 import { default as CortexElement } from '../../../../../base/src/cortex-element.ts';
-import { BoardItem } from '../../../../../types/src/board';
+import { BoardItem, HiddenSelectionState } from '../../../../../types/src/board';
 import { default as Sortable } from 'sortablejs';
 import { default as CxBoardListItem } from '../board-list-item/board-list-item';
 
 /**
  * @summary Board is a list of items that can be reordered by dragging and dropping them.
+ * @description One column of `cx-multi-select`. Owns its own selection, an optional search input,
+ * and a virtualised window over the rows. What it displays is narrowed by its own search term;
+ * the host narrows it further by handing it narrowed `data`. On drag and drop the board reports
+ * back exactly the rows it holds.
  *
- * @event {{ items: string[] }} cx-sort-change - Emitted when the list items changes.
+ * @event {{ id: string; isMultiDrag?: boolean; items: string[]; newIndex?: number; type: string }} cx-board-change - Emitted when rows are added, removed, or reordered. `items` is the board's full id list after the change; `type` is SortableJS's `add` / `remove` / `update`.
+ * @event {{ id: string; items: string[]; type?: string }} cx-board-selected-change - Emitted when the row selection changes. `items` is the selected ids in the order they were picked.
+ *
+ * @csspart divider - The rule under the header. Only rendered when `divider-color` is set.
+ * @csspart list - The scrolling row container.
+ * @csspart search-input - The search input. Only rendered when `allow-search` is set.
+ * @csspart search-input-clear - The clear button inside the search input.
+ * @csspart select-all - The select-all checkbox in the header. Only rendered when `all` is set.
  */
 export default class CxBoard extends CortexElement {
     static readonly styles: import('lit').CSSResult[];
     static readonly dependencies: {
         'cx-board-list-item': typeof CxBoardListItem;
+        'cx-divider': typeof CxDivider;
         'cx-icon': typeof CxIcon;
         'cx-icon-button': typeof CxIconButton;
         'cx-input': typeof CxInput;
@@ -36,6 +49,28 @@ export default class CxBoard extends CortexElement {
     configurable: boolean;
     all: boolean;
     allowSearch: boolean;
+    /**
+     * Color of the rule under the board header. Empty (the default) draws no rule at all — not a
+     * transparent one — so a board that says nothing about it keeps byte-for-byte the header it has
+     * always had, rather than every existing consumer silently gaining a 1px line.
+     *
+     * One property rather than a separate show/hide flag: the color's presence *is* the switch, so
+     * there is no "shown but uncolored" or "colored but hidden" state to reconcile.
+     *
+     * Takes any CSS color, but prefer a design token — `var(--cx-color-primary-500)` — over a raw
+     * hex so the rule follows the theme.
+     */
+    dividerColor: string;
+    /**
+     * Display-only: the host's summary of selected rows this board cannot see (the host may be
+     * narrowing `data`). Read in exactly four render outputs — the header glyph, its
+     * `aria-checked`, the tint, and the footer count — and never acted on: it does not touch
+     * `data`, the selection, drag, or any event. Same species of input as `divider-color`, not a
+     * control channel.
+     */
+    hiddenSelection: HiddenSelectionState;
+    /** Display-only: how many selected rows the host is hiding; added to the footer count. */
+    hiddenSelectedCount: number;
     /**
      * A boolean property that indicates whether the drag operation should be aborted.
      * When set to `true`, the current drag action will be canceled,
@@ -66,7 +101,21 @@ export default class CxBoard extends CortexElement {
     private previous;
     private lastSelectedItem;
     get selectedCount(): number;
+    /**
+     * Whether the tick, rather than the dash, is what the header should show.
+     *
+     * With rows on screen the board answers from what it sees: every visible selectable row
+     * selected. With nothing left on screen there is no row to describe, so it defers to
+     * `hiddenSelection` — the host's display-only summary of the selection this board cannot
+     * see. `All` there means every selectable row of the whole column is selected, which is
+     * exactly what the tick claims.
+     */
     get isAllSelected(): boolean;
+    /**
+     * Something is selected that the tick cannot stand for — including a selection the host is
+     * currently hiding, which is then the only thing still telling the user a selection
+     * survives the filter.
+     */
     get isPartiallySelected(): boolean;
     /**
      * Rows counted toward "select all" (excludes synthetic group headers, disabled, and
@@ -118,6 +167,13 @@ export default class CxBoard extends CortexElement {
     handleMove(evt: Sortable.MoveEvent): boolean | undefined;
     deselectAll(force?: boolean): void;
     selectAll(): void;
+    /**
+     * Restores a selection after the host replaced `data` (which resets it), without emitting
+     * `cx-board-selected-change` — only the selection's owner calls this, so it already knows.
+     * Ids the board does not currently hold are skipped; the order of `ids` becomes the
+     * selection order.
+     */
+    restoreSelection(ids: string[]): void;
     handleSelectAll(): void;
     private handleSelectAllKeydown;
     /** Index in `this.items` immediately after the last real (non-header) visible row. */

package/library/packages/molecules/src/multi-select/components/board-list-item/board-list-item.d.ts

@@ -5,6 +5,20 @@ import { default as CxTooltip } from '../../../../../atoms/src/components/toolti
 import { default as CortexElement } from '../../../../../base/src/cortex-element.ts';
 import { TemplateResult } from 'lit';
 
+/**
+ * @summary A single row inside `cx-board`: a selection indicator, the row's label, and an
+ * optional configure button.
+ * @description The label is clamped to two lines; hovering it opens the row's `tooltip` content,
+ * which is rendered as HTML. The configure button appears only when the row is `configurable` and
+ * not `readonly`, and stops its own click from reaching the board's row-selection handler.
+ *
+ * @event {{ id: string }} cx-multi-select-configure - Emitted when the configure button is activated. Carries the row's `data-id`.
+ *
+ * @csspart config-button - The configure (cog) button.
+ * @csspart text - The wrapper around the row's label.
+ * @csspart text-content - The clamped label itself.
+ * @csspart tooltip - The tooltip holding the row's `tooltip` content.
+ */
 export default class CxBoardListItem extends CortexElement {
     static readonly styles: import('lit').CSSResult[];
     static readonly dependencies: {