@orangelogic/design-system 3.17.0 → 3.19.0

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: {

package/library/packages/molecules/src/multi-select/controllers/filter-controller.d.ts

@@ -0,0 +1,68 @@
+import { BoardItem } from '../../../../types/src/board';
+import { SelectedFacets } from '../../../../types/src/faceted-filter';
+
+/**
+ * Where a filter came from.
+ *
+ * The `facet:` prefix is load-bearing rather than cosmetic: `facetCountingPool` tells facet
+ * sources apart from every other source by it, and that distinction *is* the drill-down rule.
+ * One source per facet field, mirroring how `cx-table`'s `FilterController` keys its own
+ * `dynamic:facet:<field>` sources.
+ */
+export type MultiSelectFilterSource = 'search' | `facet:${string}`;
+/**
+ * The single owner of every filter `cx-multi-select` applies to its two boards.
+ *
+ * Each filter registers itself as a named source holding one predicate, and nothing outside this
+ * class decides how sources combine. Adding a filter is therefore one `set…` call in the handler
+ * that owns it: the AND below and the facet-counting pool both pick it up with no further edit.
+ * That is the failure this replaces — search used to narrow the boards without narrowing the pool
+ * the facet counts were tallied over, so the panel advertised counts no row could reach.
+ *
+ * Modelled on `packages/hybrid/table-core/src/table/controllers/filter-controller.ts`. That one
+ * hands filter descriptors to Tabulator, which does the filtering; there is no engine on this
+ * side, so sources hold predicates this class evaluates itself.
+ */
+export declare class MultiSelectFilterController {
+    private readonly sources;
+    get hasAnySource(): boolean;
+    /**
+     * Registers the toolbar search term, or drops the source when it is empty.
+     *
+     * Case-insensitive `includes` with no trimming — deliberately the same test `cx-board` applies
+     * to its own header search, so the two boxes select the same rows for the same text. They
+     * differ only in when they run: this one on Enter, the board's on every keystroke.
+     */
+    setSearch(searchValue: string): void;
+    /**
+     * Reconciles one source per facet field from the whole selection map, the way
+     * `FilterController.syncFacetedFilters` does: fields that lost their last value are dropped,
+     * fields that have values are re-registered. Taking the entire map rather than one field at a
+     * time is what makes clearing a value as ordinary as adding one — there is no separate removal
+     * path to forget.
+     *
+     * AND across fields, since each field is its own source; OR within a field, via the set below.
+     */
+    syncFacetSources(selectedFacets: SelectedFacets): void;
+    /**
+     * Rows passing every source, or `null` when nothing is filtering.
+     *
+     * `null` rather than "every row" lets the caller hand the board its full list untouched —
+     * same array, no filtering cost; an empty array means the opposite: no row may show.
+     * Result identity across calls is the caller's business (`stabilizeItems`), not this
+     * class's — two boards share this controller with two different pools, so a single cache
+     * here would thrash.
+     */
+    filterItems(pool: BoardItem[]): BoardItem[] | null;
+    /**
+     * The pool a facet's values are counted over: every source applied *except* the facet ones.
+     *
+     * This is the whole drill-down policy, in one place. Leaving facet sources out is what keeps a
+     * value the user has not ticked yet reachable — counted against its siblings rather than
+     * against itself. The remaining facet-versus-facet part (a facet skips only its own constraint,
+     * never another facet's) belongs to `buildMetadataCounts`, which resolves it for every facet in
+     * a single pass.
+     */
+    facetCountingPool(pool: BoardItem[]): BoardItem[];
+    private matchesEverySource;
+}

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

@@ -1,6 +1,9 @@
+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 { default as CxFacetedFilter } from '../faceted-filter/faceted-filter.ts';
 import { ColumnData } from '../../../types/src/multi-select';
 import { PropertyValues, TemplateResult } from 'lit';
 import { default as CxBoard } from './components/board/board';
@@ -9,17 +12,45 @@ import { default as CxBoard } from './components/board/board';
  * @summary Multi-select allows the user to select multiple items from a list. The items can be moved between two columns. The user can move items between the columns by dragging and dropping them.
  * @element cx-multi-select
  *
+ * A toolbar above the two boards holds the filters. `canSearch` adds a search box there, applied
+ * on Enter, and giving items a `metadata` object adds a facet panel built from it, counted across
+ * both columns — `labelMap` then renames, reorders, or restricts those facets.
+ * Both narrow what the two boards display without changing the data they hold, so a selection
+ * made before filtering survives and still moves across with the arrow buttons — still-visible
+ * rows stay ticked, hidden ones are summarized on each board's header and footer.
+ *
+ * The filter panel opens whenever either is configured, since it also holds "Applied filters":
+ * the search term shows there as a removable chip, and the panel's "Clear" wipes the search along
+ * with any facets. With no `metadata` the panel simply has no facets to tick.
+ *
+ * Separately, `canSearchBoard` controls the search input each board renders in its own header.
+ * It defaults to the first board, matching how this component has always looked; set it to `''`
+ * and turn on `canSearch` to move that search up into the toolbar instead.
+ *
  * @event {{ id: string; items: BoardItem[] }} cx-multi-select-change - Emitted when the list items change.
+ * @event {{ id: string }} cx-multi-select-configure - Emitted when the cog on a second-column row is activated. Requires `configurable`.
+ *
+ * @csspart board-1 - The first ("available") board.
+ * @csspart board-2 - The second ("selected") board.
+ * @csspart faceted-filter - The filter panel above the boards, holding the metadata facets and the applied-filter chips. Rendered whenever the toolbar is.
+ * @csspart search-input - The search box in the toolbar. Only rendered when `can-search` is set.
+ * @csspart search-input-clear - The clear button inside the search box, forwarded from `cx-input`'s
+ * own `clear-button` part. Only present while the box has text.
+ * @csspart tooltip - The tooltips wrapping the two move buttons.
+ *
+ * @cssproperty [--search-width=227px] - Width of the search box in the toolbar.
  *
  * @typedef BoardItem - {
  *   group: string;
  *   id: string;
  *   index?: string;
+ *   metadata?: Record<string, string>;
  *   text: string;
  *   tooltip: string;
  * }
  *
  * @typedef ColumnData - {
+ *   dividerColor?: string;
  *   id: string;
  *   items: BoardItem[];
  *   sort?: boolean;
@@ -30,10 +61,19 @@ export default class CxMultiSelect extends CortexElement {
     static readonly styles: import('lit').CSSResult[];
     static readonly dependencies: {
         'cx-board': typeof CxBoard;
+        'cx-faceted-filter': typeof CxFacetedFilter;
+        'cx-icon': typeof CxIcon;
         'cx-icon-button': typeof CxIconButton;
+        'cx-input': typeof CxInput;
         'cx-tooltip': typeof CxTooltip;
     };
     private readonly localize;
+    /**
+     * The single owner of the toolbar's filters. Both of them — the search box and the metadata
+     * facets — register themselves here as named sources, and it is this object, not any one
+     * handler, that decides how they combine. See `./filter-controller`.
+     */
+    private readonly filters;
     multiSelect: HTMLElement;
     board1: CxBoard;
     board2: CxBoard;
@@ -41,15 +81,100 @@ export default class CxMultiSelect extends CortexElement {
     secondColumnData: ColumnData;
     configurable: boolean;
     ignoreTypes: string[];
+    /**
+     * Shows a search box in the toolbar that narrows both boards by item text. It applies on Enter
+     * (or when cleared), not while typing — unlike the input `cx-board` renders in its own header,
+     * which filters on every keystroke.
+     *
+     * Independent of `labelMap`: search works with no facets configured, and facets work with
+     * search turned off.
+     */
+    canSearch: boolean;
+    /**
+     * Which boards render their own search input in their header, as a space-separated list of
+     * board positions — `'1'`, `'2'`, `'1 2'`, or `''` for neither. Space-separated to match how
+     * every other list-in-a-string attribute in the design system reads (`cx-dot-pagination`,
+     * `cx-menu`, `cx-popup`, …) and native HTML lists like `class` and `part`.
+     *
+     * Defaults to `'1'` because the first board has always shown that input; leaving it alone keeps
+     * every existing consumer looking exactly as it does today. Set it to `''` alongside
+     * `can-search` to move the search up into the toolbar, which is the point of having both:
+     * turning one on does not turn the other off, so a host that set both would show two search
+     * boxes filtering the same rows.
+     *
+     * A plain string rather than an array on purpose. The C# mirror serializes `string[]` as a JSON
+     * array while a delimiter-splitting Lit converter expects `'1 2'`, and the generator never sees
+     * the converter — the mismatch that leaves `cx-dot-pagination`'s `control-ids` unusable from the
+     * platform. A `string` goes down the same path as `href` or `label`, which does work.
+     */
+    canSearchBoard: string;
+    /**
+     * Maps a `BoardItem.metadata` key to the facet group name shown in the filter panel. Doubles as
+     * the allowlist and the display order: naming three keys out of ten is how a host says the
+     * other seven are not filterable.
+     *
+     * Leaving it empty (the default) does not hide the filter — it falls back to every metadata key
+     * present, each headed by the raw key. So the panel appears as soon as items carry `metadata`,
+     * and `labelMap` is only needed to rename facets, reorder them, or leave some out. A host that
+     * wants no filter at all sends no `metadata`.
+     */
+    labelMap: Record<string, string>;
     addLimit: number | undefined;
     private itemMap;
     selectedItems: Record<string, string[]>;
     private initialSecondColumnItems;
+    /** Facet config in `labelMap` order — bound to `cx-faceted-filter`'s `availableFacets`. */
+    private metadataFacetDetails;
+    /** Facet values with their drill-down counts — bound to `cx-faceted-filter`'s `facets`. */
+    private metadataFacets;
+    /** Values the user has ticked in the filter panel, keyed by metadata key. */
+    private selectedMetadataFacets;
+    /**
+     * The search term currently being applied — only what the user has committed with Enter or
+     * wiped with the clear button, never what is merely typed. The box itself holds the in-progress
+     * text, so there is no second field mirroring it here.
+     */
+    searchValue: string;
     private hasCapturedSecondColumnBaseline;
     private board1Data;
     private board2Data;
+    /**
+     * The original (unfiltered), sort-rule-applied list each board would show with no filter —
+     * NOT a snapshot of the consumer's initial data: it is re-derived in willUpdate() on every
+     * column-data change. Two jobs: the pool `recomputeBoardData` filters over, and a sort cache
+     * so the sort runs once per data change instead of on every filter recompute. With the
+     * default `sort` this is the very same reference as the column's `items`; only `sort: false`
+     * makes it a sorted copy.
+     */
+    private board1OriginalData;
+    private board2OriginalData;
     get firstColumnItemIds(): string[];
     get secondColumnItemIds(): string[];
+    /**
+     * The facet key -> heading map actually in force.
+     *
+     * `labelMap` wins when the host supplies one, because it is an allowlist as well as a set of
+     * labels: naming three keys out of ten is how a host says the other seven are not filterable.
+     * With no `labelMap` there is nothing to allowlist against, so every metadata key present
+     * becomes a facet headed by the raw key — attaching `metadata` is then enough to get a filter.
+     */
+    private get effectiveLabelMap();
+    /**
+     * Chips handed to `cx-faceted-filter` for filters it does not own itself — currently just the
+     * toolbar search term.
+     *
+     * This is what puts the search term under the panel's "Clear", and it is the only way to get it
+     * there: "Clear" reports itself by emitting `cx-faceted-filter-remove` once per chip supplied
+     * here, so with no chips it says nothing about the search at all. It also feeds the panel's
+     * applied-filter count, which is what decides whether the "Clear" button renders — without a
+     * chip, a search with no facet ticked leaves the count at zero and no button to press.
+     *
+     * Not gated on `canSearch`: if a term is somehow applied while the box is hidden it is still
+     * narrowing both boards, and a chip is then the only way to see and remove it.
+     */
+    private get appliedFilterTags();
+    /** Board positions parsed out of `canSearchBoard`, tolerant of extra whitespace. */
+    private get boardsWithOwnSearch();
     /**
      * Validates the changes made to the items array based on the specified type of action ('add' or 'remove').
      * If an add limit is set, it checks whether the new items exceed the allowed limit.
@@ -66,8 +191,94 @@ export default class CxMultiSelect extends CortexElement {
     private handleMoveItems;
     private handleMoveItemsRight;
     private handleMoveItemsLeft;
+    /**
+     * Commits what is in the box on Enter — nothing filters until then. There is no separate draft
+     * field because `cx-input` is already holding the typed text: this only has to read it back at
+     * the moment the user commits. The `value` binding cannot fight that, since Lit re-commits an
+     * attribute binding only when the bound value changes, and `searchValue` changes only here.
+     *
+     * The parameter is typed with the payload `cx-input` actually emits (`{ event, value }`)
+     * rather than `CxKeydownEvent`, whose declared detail is empty — using the alias would type
+     * every detail read as `never`. Same situation as `cx-rich-text-toolbar`'s stepper handler,
+     * minus its cast.
+     *
+     * `preventDefault()` does double duty: `cx-input` schedules a form submit on an unmodified
+     * Enter and only skips it when the event was default-prevented, so without this an Enter here
+     * would submit whatever form the component sits in. The `isComposing` guard mirrors the one
+     * `cx-input` applies to that same submit — with an IME open, Enter is picking a candidate, not
+     * asking to search.
+     */
+    private handleSearchKeydown;
+    /**
+     * Clears the applied term — the clear button is its own commit, so it does not wait for Enter.
+     * `cx-input` has already emptied itself and taken focus back by the time this runs.
+     */
+    private handleSearchClear;
+    /**
+     * Removes one of the chips fed in through `appliedFilterTags`, either from its own X or from
+     * the panel's "Clear", which emits this once per chip before clearing its own facets.
+     *
+     * Assigning `searchValue` is the whole fix: the `@watch` below drops the search source from the
+     * controller, and the input's `value` binding empties the box. Unknown keys are ignored rather
+     * than thrown on — the panel may carry chips from filters added later.
+     */
+    private handleAppliedFilterRemove;
+    private handleMetadataFacetChange;
+    /**
+     * Rebuilds the filter panel's own data — the facet config and the values with their counts.
+     *
+     * The pool is `itemMap` rather than the two `items` arrays concatenated: `itemMap` is keyed by
+     * id, so an item present in both columns collapses to one entry. Concatenating would count it
+     * twice for every item the deduplication above has not cut yet.
+     *
+     * `facetCountingPool` then applies every non-facet filter to it, so a count always predicts how
+     * many rows ticking that value would actually leave on screen. Which sources that covers is the
+     * controller's business, not this method's — that is the point of asking it rather than naming
+     * the search term here, as this once did and would have to keep doing for every filter added.
+     *
+     * A count can still reach zero for a value the user has already ticked; `buildMetadataCounts`
+     * keeps such values in the tally so they stay visible and removable.
+     */
+    private rebuildMetadataFacets;
+    /**
+     * Pushes the controller's verdict into what the two boards receive. Only this derived,
+     * per-board view is filtered — the full column state (and with it `itemMap`, drag
+     * reporting, and the facet counting pool) always keeps every row the host owns.
+     *
+     * `stabilizeItems` hands back the previous array when nothing changed, because `cx-board`
+     * treats every new `data` reference as a real data change and resets its selection and
+     * scroll. An unrelated re-render must not do that.
+     */
+    private recomputeBoardData;
+    /**
+     * Puts the visible part of the tracked selection back onto each board after a filter change.
+     *
+     * A filter change hands both boards a new `data` reference, and `cx-board` answers any data
+     * change by resetting its own selection — it cannot tell a filter from a real row change.
+     * This component can, so once the boards have processed the new data it restores what it
+     * still tracks. Ids the filter hides are not on the board to restore; they stay tracked
+     * here, which is what keeps the move buttons live and the display inputs truthful for them.
+     */
+    private restoreBoardSelections;
+    /**
+     * No debouncing here, and none wanted: `searchValue` moves only when the user commits with
+     * Enter or clears the box, so this runs once per deliberate action rather than once per
+     * keystroke. The input holds the text in the meantime.
+     */
+    onSearchValueChanged(): Promise<void>;
     onSecondColumnDataChange(): void;
     protected willUpdate(changedProperties: PropertyValues<this>): void;
+    /**
+     * The filter panel is rendered whenever the toolbar is, even with no facets to tick.
+     *
+     * Its facet list is only half of what it shows: the other half is "Applied filters", which holds
+     * the search chip and the "Clear" that removes it. Gating the whole panel on having facets took
+     * that away from anyone filtering by search alone — with no `metadata`, there was no panel, so
+     * no way to see or clear the term except the box's own X. `cx-faceted-filter` already renders
+     * its applied-filters header unconditionally and only its facet body on having facets, so an
+     * empty facet list costs nothing here.
+     */
+    private renderFilterToolbar;
     render(): TemplateResult;
 }
 declare global {

package/library/packages/molecules/src/multi-select/utils/base.d.ts

@@ -0,0 +1,44 @@
+import { BoardItem } from '../../../../types/src/board';
+import { SelectedFacets } from '../../../../types/src/faceted-filter';
+import { MetadataFacetData } from '../../../../types/src/multi-select';
+
+export declare const compareFunction: (a: BoardItem, b: BoardItem) => number;
+/**
+ * Counts items per `(facet key, value)` pair. The counting unit is the pair, never the value on
+ * its own — the same string under two different keys is two unrelated facet values.
+ *
+ * Counts drill down: a facet is tallied over the items satisfying every *other* selected facet,
+ * never its own. That is what keeps the values a user has not picked yet reachable instead of
+ * dropping them to zero the moment a sibling value is ticked.
+ *
+ * One pass over `items` is enough for that, because a facet counts an item exactly when the item
+ * fails no constraint other than the facet's own. So the item's number of failures decides
+ * everything: none means every facet counts it, exactly one means only the facet owning that
+ * failing constraint counts it, and two or more means no facet can — excluding one still leaves
+ * the other unsatisfied.
+ *
+ * Only keys present in `labelMap` become facets, so the host can push any metadata it likes and
+ * still control what is filterable. Facets that end up with no values are dropped rather than
+ * rendered empty.
+ */
+export declare function buildMetadataCounts(items: BoardItem[], labelMap: Record<string, string>, selectedFacets?: SelectedFacets): Map<string, Map<string, number>>;
+/**
+ * Every metadata key present in `items`, mapped to itself — the fallback for a host that attaches
+ * metadata but does not say what to call each facet. Attaching metadata is then enough to get a
+ * filter, with the raw key as the group heading.
+ *
+ * Keys keep the order they are first seen in rather than being sorted, so the facet order follows
+ * the order the host wrote its own `metadata` objects in — the same thing `labelMap` controls when
+ * it is supplied. Re-assigning a key that is already present does not move it, so the plain
+ * assignment below is enough to keep that order.
+ */
+export declare function deriveLabelMapFromMetadata(items: BoardItem[]): Record<string, string>;
+/**
+ * Maps raw counts onto the pair of bindings `cx-faceted-filter` expects.
+ *
+ * Both arrays are built from the same `labelMap` key order and share one `facetDetails` object
+ * per facet, because the component renders by iterating `availableFacets` and then looking the
+ * facet up in `facets` by `facetFieldName` — a mismatch between the two drops that facet
+ * silently.
+ */
+export declare function toMetadataFacetData(counts: Map<string, Map<string, number>>, labelMap: Record<string, string>): MetadataFacetData;

package/library/packages/molecules/src/multi-select/utils/reconcile.d.ts

@@ -0,0 +1,57 @@
+import { BoardItem, HiddenSelectionState } from '../../../../types/src/board';
+
+/**
+ * Pure helpers that let `cx-multi-select` hand each `cx-board` a *filtered view* as plain
+ * `data` while its own column state keeps every row.
+ *
+ * The board is deliberately dumb: it only ever sees, and reports back, the rows it was given.
+ * With a filter active that report describes the visible list, not the column — so every
+ * board-reported change has to be merged back into the full list here, every board-relative
+ * index translated, and the selection the board cannot see summarized for its display-only
+ * inputs. With no filter active the visible list IS the full list and every function below
+ * degrades to the identity (or `None`), which keeps pre-filter behavior byte-identical.
+ */
+/** What `computeHiddenSelection` reports for one column. */
+export interface HiddenSelectionSummary {
+    count: number;
+    state: HiddenSelectionState;
+}
+/**
+ * Returns `previous` when `next` holds exactly the same item objects in the same order, so an
+ * unchanged result keeps its array identity. Lit compares reactive properties by reference,
+ * and `cx-board` answers every new `data` reference by resetting its selection and scroll
+ * position — identity is what stops an unrelated re-render from doing that.
+ */
+export declare function stabilizeItems(next: BoardItem[], previous: BoardItem[]): BoardItem[];
+/**
+ * Translates an insertion index expressed against the visible (filtered) list into an index in
+ * the full list, anchoring on the visible row the insertion lands before — hidden rows keep
+ * their position relative to their visible neighbors. Past the visible end, the insertion
+ * lands right after the last visible row (before any hidden tail), which is where the user
+ * saw it go; with nothing visible at all it appends at the absolute end.
+ */
+export declare function toFullInsertIndex(visibleIndex: number, visibleItems: BoardItem[], fullItems: BoardItem[]): number;
+/**
+ * Merges a board-reported visible id list back into the full list the host owns.
+ *
+ * The report is treated as a delta against the visible list the host handed the board:
+ * visible rows missing from the report leave the full list, new ids are kept where the report
+ * puts them, and every hidden row stays attached to (in front of) the visible row that
+ * followed it — so hidden rows travel with their anchor on reorder and are never lost. A
+ * hidden group whose anchor itself left the board joins the tail: its position is
+ * unobservable while hidden, and the tail is the one placement that cannot collide with
+ * whatever the user just arranged.
+ */
+export declare function mergeVisibleListIntoFull(reportedIds: string[], visibleBefore: BoardItem[], fullItems: BoardItem[]): string[];
+/**
+ * Describes the part of a column's tracked selection that the board cannot see, feeding the
+ * two display-only inputs `cx-board` renders (`hidden-selection`, `hidden-selected-count`).
+ *
+ * `All` mirrors what the header tick means when rows are visible — every selectable row of
+ * the whole column is selected — so "select all, then filter to nothing" keeps its tick and a
+ * partial selection keeps its dash. The board itself cannot make that call: it only holds the
+ * filtered rows, and the distinction needs the full column. The selectable exclusions mirror
+ * the board's own `selectableItems` (no synthetic group headers, no disabled rows, no ignored
+ * types).
+ */
+export declare function computeHiddenSelection(trackedSelectedIds: string[], visibleItems: BoardItem[], fullItems: BoardItem[], ignoreTypes: string[]): HiddenSelectionSummary;

package/library/packages/organisms/src/bento-grid/bento-grid.d.ts

@@ -42,7 +42,7 @@ export default class CxBentoGrid extends CortexElement {
     /** Cached viewport height — updated on resize only, not on every scroll. */
     private _viewportHeight;
     /** Watches the host element for size changes so the grid reflows when its container resizes. */
-    private _resizeObserver;
+    private resizeObserver;
     /** Tracks the last emitted range to avoid firing cx-bento-range-change when the range hasn't changed. */
     private _lastEmittedFirst;
     private _lastEmittedLast;
@@ -273,6 +273,11 @@ export default class CxBentoGrid extends CortexElement {
     runConnectedCallback(): void;
     disconnectedCallback(): void;
     runFirstUpdated(): void;
+    /**
+     * ResizeObserver on the container covers both window resize and any container-driven
+     * width changes (sidebar toggle, flex layout shifts, etc.).
+     */
+    private observeContainerResize;
     /**
      * Returns the visible viewport height for virtualization.
      *
@@ -339,8 +344,27 @@ export default class CxBentoGrid extends CortexElement {
      * instead of stopping it.
      */
     private scheduleRowRelease;
-    /** Clears any pending release and resets the gate back to its initial state. */
+    /** Drops the pending release, keeping the rows already released. */
+    private cancelRowRelease;
+    /**
+     * Clears any pending release and resets the gate back to its initial state.
+     *
+     * Must run BEFORE `computeLayout()` in the same pass: that call ends by arming the
+     * next release, and a reset landing after it cancels the arm with nothing left to
+     * re-arm, which gates every row for good.
+     */
     private resetRowRelease;
+    /**
+     * Restarts row gating when the dataset shrinks or is replaced wholesale.
+     *
+     * Row indices refer to a specific layout, so keeping a release count across a new
+     * dataset would let its rows load all at once — the burst this gate exists to prevent.
+     * Progress is kept only for an appended page: the new dataset must repeat the previous
+     * items, in order, as its prefix, so the already-released rows still hold the same
+     * items and the new rows queue behind them. Any other replacement restarts the gate,
+     * including a same-length or larger array carrying different items.
+     */
+    private resetRowReleaseForNewData;
     /**
      * Returns the index of the last item whose rowStart is within maxRows.
      */
@@ -377,21 +401,18 @@ export default class CxBentoGrid extends CortexElement {
      * idempotent — safe to call again on already-observed elements.
      */
     private observeItemContentSlots;
+    /**
+     * Decides whether this pass restarts row gating, and does so.
+     *
+     * Must run BEFORE `computeLayout()` — see `resetRowRelease()`.
+     */
+    private applyRowReleaseResets;
     willUpdate(changed: PropertyValues): void;
     /**
      * Re-syncs row content heights whenever the layout recomputes (containerStyles
      * changes on every computeLayout() call, including resize-driven reflows) or
      * the sync-row-content-height flag itself is toggled.
      */
-    /**
-     * Restarts row gating when the dataset shrinks or is replaced wholesale.
-     *
-     * Row indices refer to a specific layout, so keeping a release count across a new
-     * dataset would let its rows load all at once — the burst this gate exists to prevent.
-     * A dataset that only grew is treated as an appended page: the already-released rows
-     * still hold the same items, so their progress is kept and the new rows queue behind.
-     */
-    handleDataChangeForRowRelease(oldData?: unknown, newData?: unknown): void;
     handleRowContentHeightSync(): Promise<void>;
     /**
      * Get content position based on the size of the item.

package/library/packages/organisms/src/carousel/carousel.d.ts

@@ -328,6 +328,7 @@ export default class CxCarousel extends CortexElement {
      * Synchronizes the slides with the IntersectionObserver API.
      */
     private synchronizeSlides;
+    private synchronizeSlidesNow;
     private handleScrollEnd;
     private handleSlideContainerResize;
     private isCarouselItem;