@orangelogic/design-system 3.20.0 → 3.22.0

package/library/packages/molecules/src/data-tab-group/data-tab-group.d.ts

@@ -7,7 +7,29 @@ import { TabGroupAlignment, TabGroupHidePanelVariant, TabGroupOverflowVariant }
 import { CSSResultGroup } from 'lit';
 
 /**
- * @summary CxDataTabGroup
+ * @summary Renders a tab group from a list of items, exposing the tabs' look as CSS custom properties.
+ *
+ * @slot slot-{id} - The panel content for the item with the matching `id`.
+ *
+ * @cssproperty [--tab-gap=0px] - The gap between tabs.
+ * @cssproperty [--tab-padding=var(--cx-spacing-x-small)] - A tab's padding.
+ * @cssproperty [--tab-panel-padding] - The panel's padding.
+ * @cssproperty [--tab-border-radius=var(--cx-border-radius-small)] - A tab's border radius.
+ * @cssproperty [--tab-color] - A tab's text color.
+ * @cssproperty [--tab-hover-color=var(--tab-color)] - A tab's text color on hover.
+ * @cssproperty [--tab-active-color=#fff] - A tab's text color when active.
+ * @cssproperty [--tab-background-color] - A tab's background color.
+ * @cssproperty [--tab-hover-background-color=var(--tab-background-color)] - A tab's background color on hover.
+ * @cssproperty [--tab-active-background-color=var(--cx-color-primary)] - A tab's background color when active.
+ * @cssproperty [--tab-border=transparent 0px] - A tab's border, as a `<color> <width>` pair.
+ * @cssproperty [--tab-hover-border=var(--tab-border)] - A tab's border on hover.
+ * @cssproperty [--tab-active-border=var(--tab-border)] - A tab's border when active.
+ * @cssproperty [--tab-label-font-family] - The tab label's font family.
+ * @cssproperty [--tab-label-font-style] - The tab label's font style.
+ * @cssproperty [--tab-label-font-weight] - The tab label's font weight.
+ * @cssproperty [--tab-label-font-size=var(--cx-font-size-small)] - The tab label's font size.
+ * @cssproperty [--bottom-line=var(--cx-color-neutral-200) 1px] - The line under the tabs, as a `<color> <width>` pair; only drawn when `show-bottom-line` is set.
+ * @cssproperty [--min-height=200px] - The height reserved when there are no tabs.
  */
 export default class CxDataTabGroup extends CortexElement {
     static readonly styles: CSSResultGroup;
@@ -26,6 +48,13 @@ export default class CxDataTabGroup extends CortexElement {
     hidePanelVariant: TabGroupHidePanelVariant;
     /** Use max panel height. */
     useMaxPanelHeight: boolean;
+    /** Draws the line that separates the tabs from the panel. */
+    showBottomLine: boolean;
+    /**
+     * The tab border sides to draw, as a space-separated list of
+     * `top` / `right` / `bottom` / `left` (e.g. `"top bottom"`).
+     */
+    tabBorderSides: string;
     multiLanguage: boolean;
     render(): import('lit').TemplateResult<1>;
 }

package/library/packages/molecules/src/details-group/details-group.d.ts

@@ -1,24 +1,126 @@
 import { default as CxDetails } from '../../../atoms/src/components/details/details.ts';
+import { default as CxIcon } from '../../../atoms/src/components/icon/icon.ts';
 import { default as CortexElement } from '../../../base/src/cortex-element.ts';
 import { DetailsItem } from '../../../types/src/details-group';
-import { CSSResultGroup } from 'lit';
+import { IconPickerValue } from '../../../types/src/icon-picker';
+import { CSSResultGroup, TemplateResult } from 'lit';
 
 /**
- * @summary CxDetailsGroup
+ * @summary Renders an accordion from a list of items, exposing each section's look as CSS custom properties.
+ *
+ * @description Every custom property below sets the look of all sections. A single section can
+ * override the header colors, border, background image and icons by carrying its own values on
+ * the item — see `DetailsItem` — which take effect once that item sets `customStyle`.
+ *
+ * @slot slot-{id} - The content for the section with the matching `id`.
  *
  * @cssproperty --details-background-color - The background color of the details.
+ * @cssproperty [--details-background-image=none] - A section's background image, covering the whole section so expanding it reveals more. Set per section from a `background` field on the item.
+ * @cssproperty [--details-background-size=cover] - How the section background image fills the section.
+ * @cssproperty [--details-background-position=top center] - Which part of the section background image stays in view.
+ * @cssproperty [--details-border-radius=var(--header-border-radius)] - A section's corner radius, which its background is clipped to. Follows the header's radius unless set.
+ * @cssproperty [--row-gap=var(--cx-spacing-medium)] - The gap between sections.
+ * @cssproperty [--header-padding=var(--cx-spacing-small)] - A section header's padding.
+ * @cssproperty [--section-body-max-width=100%] - Caps the width of a section's title and icon, centring them, while the header background still spans the section. Accepts px or %, and the `section-body-max-width` attribute sets it. Set it to the width of the section's body content so the two line up — most useful on a full-bleed accordion.
+ * @cssproperty [--expand-icon-width=var(--cx-font-size-large)] - The width of a closed section's icon. The height scales with it.
+ * @cssproperty [--hover-icon-width=var(--cx-font-size-large)] - The width of the icon shown while hovering a closed section. The height scales with it.
+ * @cssproperty [--collapse-icon-width=var(--cx-font-size-large)] - The width of an open section's icon. The height scales with it.
+ * @cssproperty [--header-border-radius=var(--cx-border-radius-small)] - A section header's border radius.
+ * @cssproperty --header-background-color - A section header's background color.
+ * @cssproperty --header-color - A section header's text and icon color.
+ * @cssproperty --header-border - A section header's border, as a `<color> <width>` pair.
+ * @cssproperty [--header-hover-background-color=var(--header-background-color)] - A closed section header's background color on hover.
+ * @cssproperty [--header-hover-color=var(--header-color)] - A closed section header's text and icon color on hover.
+ * @cssproperty [--header-hover-border=var(--header-border)] - A closed section header's border on hover.
+ * @cssproperty --header-active-background-color - An open section header's background color.
+ * @cssproperty --header-active-color - An open section header's text and icon color.
+ * @cssproperty --header-active-border - An open section header's border.
+ * @cssproperty [--header-font-size=var(--cx-font-size-large)] - A section header's font size.
+ * @cssproperty [--header-line-height=1.2] - A section header's line height, as a ratio of its font size.
+ * @cssproperty --header-font-family - A section header's font family.
+ * @cssproperty --header-font-style - A section header's font style.
+ * @cssproperty --header-font-weight - A section header's font weight.
+ * @cssproperty --content-padding - A section's content padding.
+ * @cssproperty [--content-font-size=var(--cx-font-size-medium)] - A section's content font size.
+ * @cssproperty [--empty-height=200px] - The height reserved when there are no sections.
  */
 export default class CxDetailsGroup extends CortexElement {
     static readonly styles: CSSResultGroup;
     static readonly dependencies: {
         'cx-details': typeof CxDetails;
+        'cx-icon': typeof CxIcon;
     };
+    /** Attempts per background image, matching `cx-image`'s cap. */
+    private static readonly maxBackgroundRetries;
+    /**
+     * Reads an icon-picker value, stored as JSON. Only an unreadable one (empty or
+     * unparseable, as older blocks store it) takes `fallback` — so the empty payload the
+     * picker writes when cleared means "no icon", not "use the default".
+     */
+    private static createIconConverter;
     private readonly localize;
+    /** Background URLs already probed, so a re-render does not start a second attempt. */
+    private readonly probedBackgrounds;
+    /** How many times each background URL has been retried, against `maxBackgroundRetries`. */
+    private readonly backgroundRetryCounts;
+    /** Pending retry timers, cleared on disconnect. */
+    private readonly backgroundRetryTimers;
     data: DetailsItem[];
     defaultOpenIndexes?: number[];
     multiLanguage: boolean;
+    /**
+     * Caps the width of every section's title row, in px or %. Sets
+     * `--section-body-max-width`, so this is the attribute form of that custom property -
+     * which is what the content builder writes - and styling it directly still works.
+     */
+    sectionBodyMaxWidth: string;
+    /** The icon shown on a closed section. */
+    expandIcon: IconPickerValue | null;
+    /** The icon shown while hovering a closed section. Defaults to the closed icon. */
+    hoverIcon: IconPickerValue | null;
+    /** The icon shown on an open section. */
+    collapseIcon: IconPickerValue | null;
+    /** Cache-bust token per URL. Reactive: changing it is what re-points the CSS background. */
+    private backgroundRetryTokens;
     runFirstUpdated(): void;
-    render(): import('lit').TemplateResult<1>;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /**
+     * Probes each background so a failed load can be retried. A CSS background reports no
+     * error of its own, so the only way to notice one is to load the same URL separately —
+     * normally served from cache.
+     */
+    handleBackgroundProbes(): void;
+    /** Loads a background out of band to see whether it resolves. Once per attempt. */
+    private probeBackground;
+    /**
+     * Re-points the background at a fresh URL after a backoff. Delay and cache-bust mirror
+     * `cx-image`: spread the attempts, and bypass an edge caching the failed response.
+     */
+    private scheduleBackgroundRetry;
+    /** Appends the retry cache-bust parameter while an attempt is in flight. */
+    private withBackgroundRetryToken;
+    /**
+     * The URL a background renders from, transformations applied. Shared with the probe so a
+     * retry tests what the CSS actually requests.
+     */
+    private resolveBackgroundSrc;
+    /**
+     * A section's own icon wins over the group's. Only an unset field inherits — a cleared one
+     * is a choice to show nothing.
+     */
+    private resolveIcon;
+    /**
+     * Turns a section's overrides into a style map of the CSS custom properties `cx-details`
+     * reads. Returns nothing while `customStyle` is off, so the group's look applies.
+     */
+    private resolveSectionStyle;
+    /**
+     * Renders the icon, or a hidden node that still fills the slot — `cx-details` falls back to
+     * its own chevron on an empty slot, so filling it is what makes "cleared" render nothing.
+     */
+    private renderIconSlot;
+    render(): TemplateResult<1>;
 }
 declare global {
     interface HTMLElementTagNameMap {

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

@@ -196,6 +196,11 @@ export default class CxDynamicSelect extends CortexElement {
      * The name of the icon to use for the prefix.
      */
     iconName: string;
+    /**
+     * Image source for the prefix icon, for picked images rather than named
+     * icons. Takes effect through cx-icon-button's own `src`.
+     */
+    iconSrc: string;
     /**
      * When set to true, the select will not show the dropdown.
      */

package/library/packages/molecules/src/font-picker/font-picker.d.ts

@@ -58,10 +58,13 @@ export default class CxFontPicker extends CortexElement {
     private get allTypefaces();
     private get selectedTypeface();
     private get availableFamilies();
+    /** An upright run then an italic one, each by ascending weight. */
+    private get groupedFamilies();
     private handleFamilyChange;
     private handleStyleChange;
     private renderTypefaceOptions;
     private renderFamilySelect;
+    private renderStyleOptions;
     private renderStyleSelect;
     render(): TemplateResult;
 }

package/library/packages/molecules/src/gallery-item/gallery-item.d.ts

@@ -3,6 +3,7 @@ import { default as HighlightableElement } from '../../../base/src/highlightable
 import { default as CxAssetDataDisplay } from '../asset-data-display/asset-data-display.ts';
 import { ObjectFit } from '../../../types/src/index.ts';
 import { GalleryItemContentPosition, GalleryItemContentVariant, GalleryItemShowContentType } from '../../../types/src/gallery-item';
+import { PositionPickerValue } from '../../../types/src/position-picker';
 import { LocalizeController } from '../../../utils/src/custom-element/i18n';
 import { CSSResultGroup } from 'lit';
 
@@ -107,6 +108,15 @@ export default class CxGalleryItem extends HighlightableElement {
      * The object fit style for the image.
      */
     objectFit: ObjectFit;
+    /**
+     * The focal point used to position the image within its container.
+     */
+    cropFocus: PositionPickerValue;
+    /**
+     * The background color shown behind the image, e.g. to fill empty space
+     * left by `object-fit: contain`. Accepts any valid CSS color value.
+     */
+    backgroundColor: string;
     /**
      * When true, forwards `no-crossorigin` to the inner `<cx-image>`, disabling CORS mode.
      * Defaults to false (the image loads with `crossorigin="anonymous"`).

package/library/packages/molecules/src/icon-picker/icon-picker.d.ts

@@ -175,14 +175,13 @@ export default class CxIconPicker extends CortexElement {
      * re-focuses on a timer), so a focus-driven load would re-fire long after
      * the dropdown closed.
      *
-     * The early return matters too: cx-after-show fires on every open, and
-     * chaining onto the already-settled promise would land a requestUpdate()
-     * a microtask into the open sequence, re-rendering the virtualizer while
-     * cx-select is still animating open with its document mousedown/focusin
-     * listeners armed — which intermittently closed the dropdown right after
-     * it appeared.
+     * The virtualizer waits for the first catalog request to settle before it
+     * mounts. Mounting it with an empty item set can leave its visible range
+     * empty until the user scrolls. The open-state guard also prevents a late
+     * request from mounting the list after the control has already closed.
      */
     private ensureIconsData;
+    private showVirtualizerWhenReady;
     private handleSelectShow;
     private handleSelectHide;
     private handleDropdownShow;

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

@@ -33,7 +33,6 @@ export { default as CxPageOutline } from './page-outline/page-outline';
 export { default as CxPdfViewerToolbar } from './pdf-viewer-toolbar/pdf-viewer-toolbar';
 export { default as CxPositionPicker } from './position-picker/position-picker';
 export { default as CxPublishPage } from './publish-page/publish-page';
-export { default as CxSearchBox } from './search-box/search-box';
 export { default as CxShadowInputGroup } from './shadow-input-group/shadow-input-group';
 export { default as CxShareOptionList } from './share-option-list/share-option-list';
 export { default as CxSidebar } from './sidebar/sidebar';

package/library/packages/molecules/src/masonry/masonry.d.ts

@@ -105,6 +105,11 @@ export default class CxMasonry extends CortexElement {
     private get itemSizes();
     handleItemClick(event: MouseEvent, item: MasonryItem): void;
     handleSortableUpdate(event: Sortable.SortableEvent): void;
+    /**
+     * An item without an image gets a browser-made drag preview that lands in the
+     * viewport corner. Use the item itself as the preview so it follows the cursor.
+     */
+    handleSetData(dataTransfer: DataTransfer, dragEl: HTMLElement): void;
     renderActions(item: MasonryItem): import('lit').TemplateResult<1>;
     renderMasonry(): import('lit').TemplateResult<1>;
     renderStandard(): import('lit').TemplateResult<1>;

package/library/packages/organisms/src/asset-link-format/asset-link-format.d.ts

@@ -212,6 +212,7 @@ export default class CxAssetLinkFormat extends CortexElement {
     /** True when there are transformations beyond the frozen index (i.e. user has added new ones). */
     private get hasUnfrozenTransformations();
     private apiGetTransformAssetLink;
+    private transformRequest?;
     private apiGetCropFocusMode;
     /**
      * The unit of the last applied crop transformation, for the no-asset case only. Reflects
@@ -327,6 +328,11 @@ export default class CxAssetLinkFormat extends CortexElement {
         x: number;
         y: number;
     };
+    /** Captures the current request synchronously; later edits cannot change Save's ratio. */
+    getAppliedAspectRatio(): Promise<number | undefined>;
+    private get transformRequestOptions();
+    private getTransformRequest;
+    private requestTransformAsset;
     setActiveSetting(activeSetting: string): void;
     private freezeTransformations;
     private upsertTransformation;

package/library/packages/organisms/src/asset-transformation-dialog/asset-transformation-dialog.d.ts

@@ -20,7 +20,7 @@ import { default as CxAssetLinkFormat } from '../asset-link-format/asset-link-fo
  *   `cx-icon-button`. Automatically disabled when `asset-id` is not set.
  *
  * @event cx-asset-transformation-dialog-cancel - Emitted when the user closes or cancels the dialog.
- * @event {{ detail: { format: string; manualFormat: boolean; transformations: Transformation[] } }} cx-asset-transformation-dialog-confirm - Emitted when the user saves, with the resolved proxy id, whether that id was picked by hand rather than derived from the asset extension, and the transformation array.
+ * @event {{ detail: { aspectRatio?: number; format: string; manualFormat: boolean; transformations: Transformation[] } }} cx-asset-transformation-dialog-confirm - Emitted when the user saves, with the applied image ratio, resolved proxy id, whether that id was picked by hand, and the transformation array.
  * @event cx-asset-transformation-dialog-delete - Emitted when the user resets the format to its default and clears the saved transformations via the reset button.
  */
 export default class CxAssetTransformationDialog extends CortexElement {
@@ -91,6 +91,10 @@ export default class CxAssetTransformationDialog extends CortexElement {
     private proxies;
     /** False while the authorization check is in flight or after it confirms no access. */
     private canAccess;
+    private saving;
+    /** Seeds one editing session; subsequent Apply changes belong to the child. */
+    private initialDraft;
+    private editSession;
     /**
      * Whether the author changed anything away from the block's defaults, which is what the
      * Reset control acts on.

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/color-swatch-group/color-swatch-group.constants.d.ts

@@ -1,60 +1,52 @@
 import { CellComponent } from '../../../hybrid/table-core/src/index.ts';
+import { ColorSwatchCustomColumn } from '../../../types/src/color-swatch-group';
 import { LocalizeController } from '../../../utils/src/custom-element/i18n';
 
 export declare const MIN_WIDTH_GRID_ITEM = 165;
-export declare const validCodes: string[];
+export declare const validCodes: Set<string>;
+export declare const validElements: Set<string>;
 export declare const columnDefaults: {
     resizable: boolean;
 };
 /**
- * A single "Name" column that renders the color swatch and the name together,
- * so the "Name" header spans the whole column instead of truncating inside a
- * narrow swatch-only column.
+ * The column shape this component feeds to `cx-table`. Kept local (rather than
+ * Tabulator's full `ColumnDefinition`) because only these fields are used.
+ *
+ * The definitions below deliberately carry no `width` / `widthGrow` / `minWidth`
+ * / `maxWidth`: those belong to the block's per-column Width mode and
+ * Constraints settings, and `applyColumnSettings` fills them in. A leftover
+ * `widthGrow` here would make "Fill container" columns take unequal shares,
+ * since `fitColumns` distributes free space in proportion to it.
  */
-export declare const nameColumn: {
+export type ColorSwatchColumn = {
     field: string;
-    formatter: (cell: CellComponent) => HTMLDivElement;
+    formatter?: (cell: CellComponent) => HTMLElement | null;
     headerHozAlign: string;
     headerSort: boolean;
     hozAlign: string;
+    maxWidth?: number;
+    minWidth?: number;
+    responsive?: number;
     title: string;
-    widthGrow: number;
+    width?: number;
+    widthGrow?: number;
 };
-export declare const codeColumns: ({
-    field: string;
-    headerHozAlign: string;
-    headerSort: boolean;
-    hozAlign: string;
-    minWidth: number;
-    title: string;
-    responsive?: undefined;
-    widthGrow?: undefined;
-} | {
-    field: string;
-    headerHozAlign: string;
-    headerSort: boolean;
-    hozAlign: string;
-    responsive: number;
-    title: string;
-    widthGrow: number;
-    minWidth?: undefined;
-})[];
-export declare const copyableCodeColumns: (localize: LocalizeController, palette: string) => ({
-    field: string;
-    formatter: (cell: any) => HTMLElement | null;
-    headerHozAlign: string;
-    headerSort: boolean;
-    hozAlign: string;
-    minWidth: number;
-    title: string;
-    widthGrow?: undefined;
-} | {
-    field: string;
-    formatter: (cell: any) => HTMLElement | null;
-    headerHozAlign: string;
-    headerSort: boolean;
-    hozAlign: string;
-    title: string;
-    widthGrow: number;
-    minWidth?: undefined;
-})[];
+/**
+ * A single "Name" column that renders the color swatch and the name together,
+ * so the "Name" header spans the whole column instead of truncating inside a
+ * narrow swatch-only column.
+ */
+export declare const nameColumn: ColorSwatchColumn;
+export declare const codeColumns: ColorSwatchColumn[];
+export declare const copyableCodeColumns: (localize: LocalizeController, palette: string) => ColorSwatchColumn[];
+/**
+ * The `cx-table` column for one author-declared custom column.
+ *
+ * Reads a flat field rather than `metadata.<id>`: the component flattens each
+ * row first, keeping Tabulator away from nested-path lookups. Font overrides
+ * fall back to the block's Content group, so a column created without
+ * presentation settings matches the built-in code columns.
+ */
+export declare function customColumn(column: ColorSwatchCustomColumn): ColorSwatchColumn;
+/** The flat row key a custom column's value is copied to before rendering. */
+export declare function customColumnField(id: string): string;