@orangelogic/design-system 3.18.0 → 3.19.0

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/types/src/board.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Display-only summary of the selection a `cx-board` cannot see, supplied by the host that
+ * owns the selection (`cx-multi-select`). The board renders it (header tick/dash, footer
+ * count) and never acts on it.
+ */
+export declare enum HiddenSelectionState {
+    All = "all",
+    None = "none",
+    Partial = "partial"
+}
+export interface BoardItem {
+    /** When true, the item is locked: not draggable, not selectable, not movable. */
+    disabled?: boolean;
+    group: string;
+    id: string;
+    index?: string;
+    /**
+     * Free-form metadata supplied by the host. Each key is a facet field whose display name comes
+     * from `cx-multi-select`'s `labelMap`; keys absent from that map are ignored.
+     */
+    metadata?: Record<string, string>;
+    text: string;
+    tooltip: string;
+    type?: string;
+}

package/library/packages/types/src/color-picker.d.ts

@@ -43,7 +43,40 @@ export type ParseColorValue = {
 };
 export declare enum ColorFormat {
     Hex = "hex",
-    Rgb = "rgb",
     Hsl = "hsl",
-    Hsv = "hsv"
+    Hsv = "hsv",
+    Rgb = "rgb"
 }
+/** The kind of CSS gradient produced by the color picker's gradient tab. */
+export declare enum GradientType {
+    Linear = "linear",
+    Radial = "radial"
+}
+/** Which editing surface the color picker is currently on. */
+export declare enum ColorPickerMode {
+    Gradient = "gradient",
+    Solid = "solid"
+}
+/** A single color stop within a gradient. */
+export type GradientStop = {
+    /**
+     * The stop's color. Always stored in a format that carries alpha (`rgba()` or 8-digit hex)
+     * so round-tripping through the picker never silently drops opacity.
+     */
+    color: string;
+    /**
+     * A stable identifier for the stop. Required because dragging a stop past another one
+     * re-sorts the array, and keyed rendering must not recreate the handle mid-drag.
+     */
+    id: string;
+    /** Position along the gradient line, 0-100. */
+    position: number;
+};
+/** A parsed gradient: its type, angle, and stops. */
+export type GradientValue = {
+    /** Angle in degrees, 0-360. Only meaningful when `type` is `GradientType.Linear`. */
+    angle: number;
+    /** Color stops, always sorted by `position` ascending, always at least two entries. */
+    stops: GradientStop[];
+    type: GradientType;
+};

package/library/packages/utils/src/custom-element/i18n.d.ts

@@ -37,6 +37,7 @@ export interface Translation extends DefaultTranslation {
     addControl: string;
     addCurrent: string;
     addFolderCard: string;
+    addGradientStop: string;
     addLimitExceeded: (limit: number) => string;
     addMarker: string;
     addPageCard: string;
@@ -506,6 +507,10 @@ export interface Translation extends DefaultTranslation {
     goToFirstPage: string;
     goToLastPage: string;
     goToSlide: (slide: number, count: number) => string;
+    gradient: string;
+    gradientAngle: string;
+    gradientStopNumber: (index: number) => string;
+    gradientStops: string;
     grid: string;
     groupBy: string;
     guttersWidth: string;
@@ -516,6 +521,7 @@ export interface Translation extends DefaultTranslation {
     height: string;
     heightMode: string;
     help: string;
+    hex: string;
     hideCode: string;
     hideColumn: string;
     hidePassword: string;
@@ -810,6 +816,7 @@ export interface Translation extends DefaultTranslation {
     quality: string;
     qualityHelpText: string;
     quote: string;
+    radial: string;
     radixPoint: string;
     read: string;
     readingMode: string;
@@ -825,6 +832,7 @@ export interface Translation extends DefaultTranslation {
     remove: string;
     removeBlock: string;
     removeFolder: (num: number) => string;
+    removeGradientStop: string;
     renderAudio: string;
     replace: string;
     replaceAll: string;

package/library/packages/utils/src/gradient/gradient.d.ts

@@ -0,0 +1,65 @@
+import { GradientStop, GradientValue } from '../../../types/src/color-picker';
+
+/** A gradient needs at least a start and an end color to be meaningful. */
+export declare const MIN_GRADIENT_STOPS = 2;
+/**
+ * Creates a process-unique identifier for a gradient stop.
+ * @returns An identifier that stays stable for the lifetime of the stop.
+ * @example createStopId() => "gradient-stop-1"
+ */
+export declare function createStopId(): string;
+/**
+ * Splits a string on a separator, ignoring separators nested inside parentheses.
+ * Needed because `rgba(255, 0, 0, 1)` contains commas that must not split the stop list.
+ * @param value - The string to split.
+ * @param separator - The single character to split on.
+ * @returns The trimmed top-level segments, with empty segments removed.
+ * @example splitTopLevel('rgba(1, 2, 3, 1) 0%, #fff 100%', ',') => ['rgba(1, 2, 3, 1) 0%', '#fff 100%']
+ */
+export declare function splitTopLevel(value: string, separator: string): string[];
+/**
+ * Normalizes any angle into the 0-360 range.
+ * @param degrees - The angle in degrees, possibly negative or above 360.
+ * @returns The equivalent angle within 0-360.
+ * @example normalizeAngle(-90) => 270
+ */
+export declare function normalizeAngle(degrees: number): number;
+/**
+ * Sorts stops by position ascending, preserving the relative order of equal positions.
+ * @param stops - The stops to sort.
+ * @returns A new sorted array; the input is not mutated.
+ * @example sortStops([{ position: 100 }, { position: 0 }]) => [0%, 100%]
+ */
+export declare function sortStops(stops: GradientStop[]): GradientStop[];
+/**
+ * Checks whether a value looks like a CSS gradient this module can handle.
+ * @param value - The candidate string.
+ * @returns True for `linear-gradient(...)` and `radial-gradient(...)` strings.
+ * @example isGradientString('linear-gradient(90deg, red, blue)') => true
+ */
+export declare function isGradientString(value: string): boolean;
+/**
+ * Parses a CSS gradient string into structured stops.
+ * @param value - The gradient string to parse.
+ * @returns The parsed gradient, or null when the value is not a supported gradient or does
+ * not contain at least two valid color stops.
+ * @example parseGradient('linear-gradient(90deg, #f00 0%, #00f 100%)')
+ */
+export declare function parseGradient(value: string): GradientValue | null;
+/**
+ * Serializes structured stops back into a CSS gradient string.
+ * @param value - The gradient to serialize.
+ * @returns A CSS gradient string suitable for a `background` declaration.
+ * @example serializeGradient({ angle: 90, stops, type: GradientType.Linear })
+ * => 'linear-gradient(90deg, #ff0000 0%, #0000ff 100%)'
+ */
+export declare function serializeGradient(value: GradientValue): string;
+/**
+ * Computes the color a new stop should take when inserted at a position, by blending the
+ * two stops it falls between.
+ * @param stops - The existing stops; need not be sorted.
+ * @param position - Where the new stop is being inserted, 0-100.
+ * @returns An `rgba()` color string, or an empty string when there are no stops to blend.
+ * @example interpolateStopColor(redAtZeroAndBlueAtHundred, 50) => 'rgba(128, 0, 128, 1)'
+ */
+export declare function interpolateStopColor(stops: GradientStop[], position: number): string;

package/library/packages/utils/src/gradient/index.d.ts

@@ -0,0 +1 @@
+export * from './gradient';

package/library/packages/utils/src/index.d.ts

@@ -32,6 +32,7 @@ export * from './event';
 export * from './fetch';
 export * from './font';
 export * from './form';
+export * from './gradient';
 export * from './history-manager';
 export * from './image';
 export * from './keyboard';