@orangelogic/design-system 3.17.0 → 3.19.0

package/library/packages/organisms/src/content-builder/blocks/audio/audio.d.ts

@@ -42,6 +42,7 @@ export default class CxSbAudio extends CxAudio {
      * Support CMS5 edit mode for the audio.
      */
     get isInEditMode(): boolean;
+    runConnectedCallback(): void;
     handleSrcChange(): Promise<void>;
     handleRecordIdChange(): Promise<void>;
     handleFetchedAssetDataChange(): void;

package/library/packages/organisms/src/content-builder/blocks/image/image.d.ts

@@ -151,7 +151,8 @@ export default class CxSbImage extends CxImage {
      * `cx-content-builder-viewer`) that has already batch-fetched asset data
      * for the page. When set outside edit mode, the block stops its child
      * `cx-asset-data-display` from fetching on its own and maps this data into
-     * alt text and overlay content instead.
+     * alt text and overlay content instead — and, inside a viewer, takes its
+     * delivery URL from the `path_*` fields here rather than searching for one.
      */
     fetchedAssetData: Record<string, unknown>;
     /**
@@ -204,6 +205,8 @@ export default class CxSbImage extends CxImage {
     private fetchAssetController?;
     /** Monotonic token to drop out-of-order expired-URL recovery responses. */
     private srcResolveVersion;
+    /** A source recovery is already queued for the current update cycle. */
+    private sourceRecoveryScheduled;
     /**
      * Support CMS5 edit mode for the image.
      */
@@ -309,10 +312,30 @@ export default class CxSbImage extends CxImage {
      */
     private resolveClickSpace;
     /**
-     * When a stored URL has expired, re-resolve a fresh one from the block's
+     * Runs one source recovery per update cycle. A block mounted with both `record-id`
+     * and `src` changes both in the same cycle, and a block with `record-id` alone never
+     * changes `src` at all, so the record watch has to trigger recovery too; coalescing
+     * keeps that from fetching the same URL twice.
+     */
+    private scheduleSourceRecovery;
+    /**
+     * In read mode inside a `cx-content-builder-viewer` the viewer's batched Search already
+     * carries every `path_*` field a recovery could need, so the block never searches for
+     * itself — one call per page instead of one (or more) per block.
+     */
+    private get hasAssetDataProvider();
+    /**
+     * Picks one variant's delivery URL out of the viewer's batched data. Mirrors
+     * `FetchAssetController.refetchFormatUrl`: the original-file proxy is only used for a
+     * browser-displayable original and otherwise falls back to the transcoded one. Empty
+     * until the batch lands, and for a variant the batch did not cover.
+     */
+    private readProvidedSource;
+    /**
+     * When a stored URL has expired, or none was stored, resolve one from the block's
      * `record-id` + `format` (light and dark variants independently). Fires on every
-     * `src` / `srcDarkMode` change and no-ops for non-expired URLs, so working paths
-     * are untouched. On failure it leaves the stored URL in place and lets the
+     * `src` / `srcDarkMode` / record change and no-ops for non-expired URLs, so working
+     * paths are untouched. On failure it leaves the stored URL in place and lets the
      * existing `@error` / fallback path handle it.
      */
     private recoverExpiredSources;

package/library/packages/organisms/src/content-builder/content-builder-constants.d.ts

@@ -30,6 +30,18 @@ export declare const OMITTED_ATTRIBUTES: string[];
 export declare const OMITTED_PROPERTIES: never[];
 export declare const BLOCK_CAROUSEL_LIMITED_BLOCKS: BlockType[];
 export declare const NEWLY_ADDED_COMPONENT_DELAY = 500;
+/**
+ * Grace period the load settle waits for GrapesJS's `update` after its own timer has
+ * elapsed. A swap that produced no countable change never fires `update`, so the settle
+ * must give up rather than latch the change suppression for the element's lifetime.
+ */
+export declare const SETTLE_UPDATE_GRACE = 50;
+/**
+ * Ceiling on how long the load settle waits for the templates refresh. A hung or very
+ * slow `apiGetTemplates` must not keep `softLoading` on - late writes are already made
+ * harmless by the load-generation check.
+ */
+export declare const SETTLE_TEMPLATES_TIMEOUT = 5000;
 export declare const OPEN_ON_NEWLY_ADDED_COMPONENT: Set<BlockType>;
 export declare const MULTI_LANGUAGE_BLOCKS: Set<BlockType>;
 export declare const DEFAULT_IMAGE_FORMAT = "TR1";

package/library/packages/organisms/src/content-builder/content-builder.d.ts

@@ -60,6 +60,16 @@ export default class CxContentBuilder extends CortexElement {
      * @default ''
      */
     initialData: string;
+    /**
+     * Published HTML of the page, used as the content source when it holds more
+     * content blocks than `initial-data` (a page whose JSON was never produced by
+     * this editor, e.g. published through the API with HTML only or with a
+     * partial JSON). Parsed through the registered block types, so every block
+     * the editor knows is recovered. Ignored when `initial-data` has at least as
+     * many blocks.
+     * @default ''
+     */
+    initialHtml: string;
     /**
      * This property reflects the current device type being used in the content builder.
      * It can be one of the predefined device types such as 'desktop', 'tablet', or 'mobile'.
@@ -240,6 +250,17 @@ export default class CxContentBuilder extends CortexElement {
     private _dsm;
     private get dsm();
     private hasBoundUpdate;
+    /**
+     * True while `loadPage` swaps project data into the running editor, so the
+     * swap is never mistaken for an authoring change (no `cx-change`, no
+     * builder re-init from the property watch).
+     */
+    private softLoading;
+    /**
+     * True when the last project load took its content from `initial-html`
+     * rather than `initial-data`; such content settles later than a JSON load.
+     */
+    private adoptedInitialHtml;
     /**
      * In-flight/resolved block-types fetch, kept as a promise (not the awaited value) so the
      * `component:open-picker` handler can share it even if it fires before the prefetch below
@@ -249,6 +270,24 @@ export default class CxContentBuilder extends CortexElement {
     private blockTypesPromise;
     private prefetchBlockTypes;
     private newlyAddedComponentTimeout;
+    /**
+     * Pending tail of a `loadPage` soft switch: lifts the change suppression and
+     * wipes the undo/dirty bookkeeping once GrapesJS has settled.
+     */
+    private loadPageSettleTimeout;
+    /**
+     * The one-shot `update` listener the settle waits on, kept so it can be detached
+     * along with the timer whenever the editor is torn down or a new load starts.
+     */
+    private loadPageSettleUpdateHandler;
+    /**
+     * Bumped on every project load. Async work started by a load compares against it
+     * so a response belonging to a superseded page is dropped instead of written to
+     * the editor the newer page now owns.
+     */
+    private loadGeneration;
+    /** The templates refresh started by the current load, awaited before settling. */
+    private templatesRefreshPromise;
     private readonly initializeCustomFrame;
     private containerDropdownObservers;
     private nextMapHoveredBadgeState;
@@ -314,6 +353,112 @@ export default class CxContentBuilder extends CortexElement {
      * effectively resetting the count of changes made since the last reset.
      */
     resetDirtyCount(): void;
+    /**
+     * Load another page's content into the running editor without recreating the
+     * GrapesJS instance or reloading the canvas frame document (a soft page
+     * switch). Only the project data is swapped here - the canvas document's own
+     * chrome (header, navigation, per-page styles) is the host's responsibility,
+     * typically by asking the frame to re-render itself in place.
+     *
+     * The switch resets selection, undo history and the dirty count, and never
+     * emits `cx-change`, so it cannot trigger an auto-save of the incoming page.
+     *
+     * @param options New page's `canvas-src`, `initial-data` JSON string,
+     * `initial-html` fallback and `page-id`. Omitted fields keep their current
+     * values, except `initial-html`, which belongs to one page and is cleared.
+     * @returns `true` when the switch was applied to a running editor; `false`
+     * when the editor has not booted yet - the caller must then fall back to a
+     * full render/init cycle.
+     */
+    loadPage(options: {
+        canvasSrc?: string;
+        initialData?: string;
+        initialHtml?: string;
+        pageId?: string;
+    }): Promise<boolean>;
+    /**
+     * Drop any pending load settle: both its timer and the `update` listener it is
+     * waiting on.
+     *
+     * Must run before every `contentBuilder.destroy()`. The scheduled callback closes
+     * over the editor it was armed for, and destroying does not null the field, so a
+     * surviving callback would clear the undo history of - and reset the dirty count
+     * of - whichever editor replaced it.
+     */
+    private cancelLoadPageSettle;
+    /**
+     * Run `finish` once GrapesJS has flushed the load, at the earliest after `delay`.
+     *
+     * GrapesJS chains two zero-delay timers on its way to `update`
+     * (`handleUpdates` -> `changesCount` -> `updateChanges` -> `update`), so a bare
+     * timer here fires before the swap's own `update` and would lift the change
+     * suppression while the load is still counted as authoring - emitting `cx-change`
+     * for the page that was just loaded. Waiting for both the delay and that event
+     * closes the gap; a swap that produced no countable change never fires it at all,
+     * so `SETTLE_UPDATE_GRACE` gives up rather than latching the suppression.
+     */
+    private scheduleSettle;
+    /**
+     * Parse the current `initial-data` JSON string into project data, treating a
+     * missing or malformed payload as an empty project.
+     */
+    private parseInitialProjectData;
+    /**
+     * Swap the project in place rather than via `loadProjectData`: that clears
+     * every module including pages/frames, and recreating the frame reloads the
+     * canvas iframe - the very reload this method exists to avoid. Pages and
+     * frames are kept; data sources, styles and the wrapper's component tree
+     * are what actually differ between pages.
+     */
+    private swapProjectData;
+    /**
+     * Number of blocks an author would see under `root`: every component other
+     * than the layout scaffolding (wrapper, cells, column groups), nested ones
+     * included.
+     */
+    private countComponentBlocks;
+    /**
+     * Whether `initial-html` carries blocks the loaded JSON does not. The
+     * published HTML is what readers see, so it wins whenever it holds strictly
+     * more blocks than the project JSON: a page whose JSON was never produced by
+     * this editor (published through the API) may carry only the blocks the
+     * server needs. Both sides are always counted, and after the same block-type
+     * resolution, so JSON that the editor saved itself always matches its HTML
+     * and keeps precedence - and markup with no recognized blocks is never
+     * adopted over JSON that has none either.
+     */
+    private initialHtmlHasMoreBlocks;
+    /**
+     * Fill a project from `initial-html` when the JSON lacks blocks the HTML
+     * has. GrapesJS parses the markup through the block types' `isComponent`
+     * recognizers, so each element comes back as its block with the plugin
+     * defaults merged in - the same component the picker would create. The one
+     * shape the parser cannot produce is the rich-text `content` string: it
+     * yields bare text nodes instead, which the host rejects as an empty block,
+     * so those are folded back into `content`.
+     */
+    private adoptInitialHtml;
+    /**
+     * The page viewer's `--row-gap`, as both the raw CSS value written back into
+     * the root column's style and its parsed pixel value (used for add-block
+     * popup spacing). Falls back to `12px` when the viewer or the property is
+     * missing.
+     */
+    private measureDefaultRowGap;
+    /**
+     * Guarantee the wrapper's root BlockCell: add a locked one when the body has
+     * none, otherwise re-apply that cell's locked settings and keep every
+     * column's drag/drop targets in sync.
+     */
+    private normalizeRootColumn;
+    /**
+     * Normalize a freshly loaded project: fall back to `initial-html` when the
+     * JSON lacks its blocks, lock the wrapper, guarantee the root BlockCell, rebind
+     * the templates data source, and reset the dirty count. Runs on the editor
+     * `load` event and again after every `loadPage` soft switch, outside the
+     * undo history in both cases.
+     */
+    private initializeProjectContent;
     /**
      * This method undoes the last change made in the content builder.
      */
@@ -340,6 +485,11 @@ export default class CxContentBuilder extends CortexElement {
     tryToGetSelectedComponent(): Component | undefined;
     private fetchTeamSpaceRoles;
     private updateTranslatableTextsDataSourceEntries;
+    /**
+     * @param generation The load this refresh belongs to. Once `apiGetTemplates`
+     * resolves, a mismatch means a newer page load (or a new editor) owns the canvas,
+     * and applying this response would write an older page's templates over it.
+     */
     private updateTemplatesDataSourceEntries;
     private getHoveredComponentPlacement;
     private mapHoveredComponent;

package/library/packages/organisms/src/content-builder/content-builder.utils.d.ts

@@ -14,6 +14,26 @@ type FontPickerStoredValues = {
 export declare function getTemplateClass(templateId: string): string;
 export declare function getContentConfigs(traits: PropertyConfig[], adHocProperties: string[]): string[];
 export declare function getLimitedBlocks(blockType: BlockType): BlockType[];
+/**
+ * Whether a GrapesJS component type is a block an author would see - any
+ * registered block type except the layout scaffolding (cells, column groups).
+ */
+export declare function isContentBlockType(type: string | undefined): boolean;
+/**
+ * A component tree in the shape GrapesJS parsers and `toJSON` produce: one
+ * definition, a list of them, or a text string.
+ */
+export type ParsedComponentTree = string | ParsedComponentDefinition | ParsedComponentTree[] | undefined;
+export type ParsedComponentDefinition = {
+    [key: string]: unknown;
+    components?: ParsedComponentTree;
+    type?: string;
+};
+/**
+ * Number of content blocks (see {@link isContentBlockType}) in a parsed
+ * component tree, nested ones included.
+ */
+export declare function countContentBlocks(tree: ParsedComponentTree): number;
 /**
  * The `space-default` typeface inherits the team space's current font, so the
  * backend returns it with no variants of its own. Populate its `families` from

package/library/packages/organisms/src/content-builder/plugins/wrapper-container.d.ts

@@ -1,4 +1,15 @@
 import { Editor } from 'grapesjs';
 
+/**
+ * Hosts the editable wrapper inside the canvas document's content container
+ * instead of the frame body.
+ *
+ * The canvas document is a real page render, and it does not always carry the
+ * container: the same running editor can be pointed at a page with no block
+ * content (a DAM/workspace page) and later back at one that has it. While the
+ * container is absent the wrapper is kept detached and every canvas click is
+ * left to the page itself - GrapesJS's select handler prevents the default
+ * action, which would break the links and buttons of a page it does not own.
+ */
 declare const WrapperContainerPlugin: (selector: string) => (editor: Editor) => void;
 export default WrapperContainerPlugin;

package/library/packages/organisms/src/content-builder-viewer/content-builder-viewer.d.ts

@@ -9,8 +9,9 @@ import { default as CortexLightElement } from '../../../base/src/cortex-light-el
  * call, and for blocks needing the team-space list (`cx-sb-button`, `cx-sb-image`,
  * `cx-sb-video` linking to a space, and `cx-gallery` showing space cards), fetching
  * the space list once and assigning it as `spaces`. It also distributes its
- * `securityBypassToken` to every record-id child (including `cx-timeline`, for
- * expired-URL recovery only) so their own runtime Search calls are authorised. Renders no UI. Blocks skip their own fetch whenever an ancestor supplies
+ * `securityBypassToken` to the record-id children that still search for themselves
+ * (`cx-sb-video`, `cx-sb-audio`, and `cx-timeline` for expired-URL recovery only); an
+ * image block takes its URL from the batch instead. Renders no UI. Blocks skip their own fetch whenever an ancestor supplies
  * it, so they must sit inside this element for that to apply — in the editor that means
  * inside the canvas document.
  *
@@ -45,6 +46,13 @@ export default class CxContentBuilderViewer extends CortexLightElement {
     private getPrimaryRecordId;
     /** Every field a block could map from fetched asset data. */
     private getRequestedFields;
+    /**
+     * Proxy fields that can serve as an image's delivery URL. A hand-picked format names one
+     * proxy; `Auto` is decided by the extension this same response carries, so both candidates
+     * are requested up front rather than in a follow-up call. The original-file proxy always
+     * comes with the transcoded fallback, which is what a non-image original falls back to.
+     */
+    private getImagePathFields;
     private buildFetchPlan;
     private fetchAllAssetData;
     private applyFetchedData;

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';

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

@@ -55,6 +55,8 @@ export declare function applyWidthToAssetUrl(url: string, width: number): string
  * crop or proxy format), so a ladder must not add a competing one.
  */
 export declare function hasTransformSegment(url: string): boolean;
+/** Proxy format that serves the asset's original file rather than a rendered variant. */
+export declare const ORIGINAL_FORMAT = "TRX";
 /** Proxy format that is always transcoded to a raster image, whatever the source file is. */
 export declare const AUTO_FALLBACK_FORMAT = "TR1";
 /**