@orangelogic/design-system 3.20.0 → 4.0.0

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/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/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";
 /**

package/library/react-web-component.d.ts

@@ -10070,6 +10070,10 @@
           * Initial data for the content builder This should be a JSON string representing the initial state of the content builder. <br/>@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. <br/>@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'. <br/>@default 'desktop'
         */