@orangelogic/design-system 3.4.0 → 3.5.0

package/library/packages/tools/src/fetch-image/fetch-image.d.ts

@@ -28,46 +28,69 @@ export declare class FetchImageController implements ReactiveController {
     constructor(host: ReactiveElement, options?: FetchImageControllerOptions);
     get totalDataCount(): number;
     setSecurityByPassToken(token: string | undefined): void;
-    fetchImages({ end, extraFields, format, start, transformations, }: {
+    /**
+     * Changes how many items each request asks for.
+     *
+     * A new size moves every page boundary, so cached pages are dropped and the next fetch
+     * starts from page 1. `data` is kept — it is indexed absolutely, so the refetch
+     * overwrites in place instead of blanking the grid.
+     *
+     * Shrinking is ignored once pages are cached: collapsing already has what it needs.
+     */
+    setPageSize(pageSize: number): void;
+    fetchImages({ end, extraFields, format, manualFormat, start, transformations, }: {
         end: number;
         extraFields: string[];
         format?: string;
+        /**
+         * When false, `format` is ignored and each item resolves its own from its file
+         * extension. Defaults to true so existing callers keep their explicit format.
+         */
+        manualFormat?: boolean;
         start: number;
         transformations?: Transformation[];
     }): Promise<ExtendedGalleryItem[] | undefined>;
-    fetchImagesInFolderBySlide({ activeSlide, extraFields, folderId, forceRefetch, format, minLimit, noPlaceholders, transformations, }: {
+    fetchImagesInFolderBySlide({ activeSlide, extraFields, folderId, forceRefetch, format, manualFormat, minLimit, noPlaceholders, transformations, }: {
         activeSlide: number;
         extraFields?: string[];
         folderId: string;
         forceRefetch?: boolean;
         format?: string;
+        manualFormat?: boolean;
         minLimit?: number;
         noPlaceholders?: boolean;
         transformations?: Transformation[];
     }): Promise<ExtendedGalleryItem[]>;
-    fetchImagesByIDs({ extraFields, format, recordIds, transformations, }: {
+    fetchImagesByIDs({ extraFields, format, manualFormat, recordIds, transformations, }: {
         extraFields?: string[];
         format?: string;
+        /**
+         * When false, `format` is ignored and each item resolves its own from its file
+         * extension. Defaults to true so existing callers keep their explicit format.
+         */
+        manualFormat?: boolean;
         recordIds: string[];
         transformations?: Transformation[];
     }): Promise<ExtendedGalleryItem[]>;
-    fetchImagesInFolderByPage({ extraFields, folderId, forceRefetch, format, noPlaceholders, page, pageSize, transformations, }: {
+    fetchImagesInFolderByPage({ extraFields, folderId, forceRefetch, format, manualFormat, noPlaceholders, page, pageSize, transformations, }: {
         extraFields?: string[];
         folderId: string;
         forceRefetch?: boolean;
         format?: string;
+        manualFormat?: boolean;
         noPlaceholders?: boolean;
         page: number;
         pageSize?: number;
         transformations?: Transformation[];
     }): Promise<ExtendedGalleryItem[]>;
-    fetchImagesInFolderByChunk({ chunkSize: rawChunkSize, end, extraFields, folderId, forceRefetch, format, start, transformations, }: {
+    fetchImagesInFolderByChunk({ chunkSize: rawChunkSize, end, extraFields, folderId, forceRefetch, format, manualFormat, start, transformations, }: {
         chunkSize?: number;
         end?: number;
         extraFields?: string[];
         folderId: string;
         forceRefetch?: boolean;
         format?: string;
+        manualFormat?: boolean;
         start?: number;
         transformations?: Transformation[];
     }): AsyncGenerator<ExtendedGalleryItem[], void, unknown>;

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

@@ -58,7 +58,6 @@ export type Asset = {
     identifier: string;
     imageUrl: string;
     name: string;
-    originalUrl: string;
     scrubUrl: string;
     size: string;
     tags: string;

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

@@ -64,6 +64,11 @@ export type PropertyConfig<T = Record<string, any>> = Omit<TraitProperties, 'opt
         defaultFormat?: string;
         dialogLabel?: string;
         formatKey?: string;
+        /**
+         * The block-attribute key that records whether the format was picked by hand. When
+         * absent or false the format follows the asset's file extension.
+         */
+        manualFormatKey?: string;
         multiple?: boolean;
         noCrop?: boolean;
         noResize?: boolean;
@@ -114,6 +119,8 @@ export type PropertyConfig<T = Record<string, any>> = Omit<TraitProperties, 'opt
         dialog: DialogType;
         /** The block-attribute key for the format used to resolve records' src URLs after picking. */
         formatKey?: string;
+        /** The block-attribute key recording whether that format was picked by hand. */
+        manualFormatKey?: string;
         transformationRecordIdKey?: string;
         transformationsKey?: string;
     };

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

@@ -25,6 +25,7 @@ export type GalleryItem = {
     className?: string;
     details?: string;
     docType?: MediaType | '';
+    extension?: string;
     filler?: boolean;
     header?: string;
     id: string;

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

@@ -6,6 +6,7 @@ export declare enum MasonryVariant {
 }
 export type MasonryItem = {
     alt?: string;
+    extension?: string;
     hasError?: boolean;
     id: string;
     loading?: boolean;

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

@@ -46,6 +46,42 @@ 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 is always transcoded to a raster image, whatever the source file is. */
+export declare const AUTO_FALLBACK_FORMAT = "TR1";
+/**
+ * Largest original file `Auto` will serve untouched, in bytes.
+ *
+ * Past this the transcoded proxy wins even for extensions that would normally keep their
+ * original: delivering a very large original costs the viewer more than the animation or
+ * alpha it preserves.
+ */
+export declare const AUTO_ORIGINAL_FORMAT_MAX_BYTES: number;
+/**
+ * Reads an asset file size into bytes, or `undefined` when the value says nothing usable.
+ *
+ * `CoreField.FileSize` is typed as a string and has been observed both as a plain byte
+ * count (`'1024'`) and as a formatted value (`'63.47 KB'`), so both are accepted. A bare
+ * number is read as bytes, matching the raw form.
+ *
+ * Returns `undefined` rather than `0` for unusable input so callers can tell "no size
+ * reported" apart from "genuinely empty file" — the two lead to different decisions.
+ */
+export declare function parseFileSizeToBytes(size: string | number | null | undefined): number | undefined;
+/**
+ * Picks the proxy format an asset should be served under when the author chose `Auto`
+ * instead of naming a format.
+ *
+ * Extensions that would lose something to a transcode (animation, alpha, bit depth) take
+ * the original-file proxy, but only up to `AUTO_ORIGINAL_FORMAT_MAX_BYTES`; everything
+ * else takes the transcoded raster proxy, which is the one `buildAssetSrcset` may resize.
+ *
+ * An unknown or missing extension resolves to the raster proxy — the safe default for the
+ * majority of assets, and the same value the format ladders already fall back to.
+ *
+ * An unknown *size* does not: a size the API did not report is treated as within the
+ * limit, so a missing field never silently strips a GIF of its animation.
+ */
+export declare function resolveAutoFormat(extension: string | null | undefined, size?: string | number | null): string;
 /**
  * Builds a `srcset` value for an asset-link URL by emitting one width-only resize
  * candidate per ladder entry, letting the browser fetch and decode only the pixels
@@ -56,11 +92,14 @@ export declare function hasTransformSegment(url: string): boolean;
  * ladder, the smallest candidate is still emitted so a `srcset` is always produced
  * for an eligible URL.
  *
- * Returns an empty string when the URL is not an asset link, or when it already carries
- * a transformation — signalling the caller to omit the attribute and honour the width
- * that was configured upstream.
+ * Returns an empty string when the URL is not an asset link, when it already carries
+ * a transformation (the width was configured upstream), or when it is an animated GIF
+ * served as the original file — resizing that flattens it to a still frame, so the
+ * original has to be delivered untouched.
  */
 export declare function buildAssetSrcset(url: string, options?: {
+    extension?: string | null;
+    format?: string;
     maxWidth?: number;
     widths?: readonly number[];
 }): string;

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

@@ -22,19 +22,19 @@
             export type CxGraphViewNodeAction = { controlType: 'default' | 'switch'; icon: string; id: string; name: string; showDivider: boolean; style: { color: string; }; };
             export type CxGraphViewRecord = any;
             export type CxGraphViewSummary = { icon: string; texts: string[]; };
-            export type CxMasonryMasonryItem = { alt: string; hasError: boolean; id: string; loading: boolean; objectFit: 'contain' | 'cover' | 'fill' | 'none' | 'scale-down'; src: string; };
+            export type CxMasonryMasonryItem = { alt: string; extension: string; hasError: boolean; id: string; loading: boolean; objectFit: 'contain' | 'cover' | 'fill' | 'none' | 'scale-down'; src: string; };
             export type CxMasonryMasonryItemAction = { color: string; event: string; icon: string; src: string; tooltip: string; };
             export type CxMentionsAutocompleteItem = { id: string; label: string; name: string; suffixContent: string; suffixIcon: string; suffixTooltip: string; suffixType: 'badge'; title: string; type: string; };
             export type CxMultiSelectColumnData = { id: string; items: { disabled: boolean; group: string; id: string; index: string; text: string; tooltip: string; type: string; }[]; sort: boolean; title: string; };
             export type CxShareOptionListShareOptionListItem = { disabled: boolean; icon: string; id: string; name: string; tooltip: string; };
             export type CxStepperWizardStepData = { color: string; description: string; icon: string; iconVariant: 'outlined' | 'filled' | 'fa'; id: string; name: string; readonly: boolean; state: 'Done' | 'Active' | 'None' | 'Disabled'; };
-            export type CxAssetLinkFormatAsset = { allowATSLink: boolean; docSubType: string; docType: 'Album' | 'Audio' | 'Audio segment' | 'Image' | 'Multimedia' | 'ProjectDocument' | 'Story' | 'Video' | 'Widget'; extension: string; height: string; id: string; identifier: string; imageUrl: string; name: string; originalUrl: string; scrubUrl: string; size: string; tags: string; width: string; };
+            export type CxAssetLinkFormatAsset = { allowATSLink: boolean; docSubType: string; docType: 'Album' | 'Audio' | 'Audio segment' | 'Image' | 'Multimedia' | 'ProjectDocument' | 'Story' | 'Video' | 'Widget'; extension: string; height: string; id: string; identifier: string; imageUrl: string; name: string; scrubUrl: string; size: string; tags: string; width: string; };
             export type CxAssetLinkFormatCropMode = { auto: boolean; disabledSize: boolean; label: string; value: string; };
             export type CxAssetLinkFormatFocusMode = { auto: boolean; label: string; value: string; };
             export type CxAssetLinkFormatProxy = { cdnName: string; extension: string; formatHeight: number; formatWidth: number; height: number; id: string; permanentLink: string; proxyLabel: string; proxyName: string; width: number; };
             export type CxAssetLinkFormatTransformation = { key: 'Crop' | 'Metadata' | 'Proxy' | 'Quality' | 'Resize' | 'Rotate'; value: { disabledSize: boolean; focusMode: string; height: number; isFocusModeAuto: boolean; keepMetadata: boolean; mode: string; position: 'bottom-center' | 'bottom-left' | 'bottom-right' | 'center-center' | 'center-left' | 'center-right' | 'top-center' | 'top-left' | 'top-right'; quality: number; ratioHeight: number; ratioWidth: number; rotation: number; unit: '%' | 'px'; width: number; x: number; y: number; }; };
-            export type CxBentoGridGalleryItem = { additions: string[]; alt: string; cardType: 'asset' | 'folder' | 'link' | 'page' | 'space'; className: string; details: string; docType: '' | 'Album' | 'Audio' | 'Audio segment' | 'Image' | 'Multimedia' | 'ProjectDocument' | 'Story' | 'Video' | 'Widget'; filler: boolean; header: string; id: string; isClone: boolean; name: string; objectFit: 'contain' | 'cover' | 'fill' | 'none' | 'scale-down'; openInNewTab: boolean; pageId: string; rawId: string; size: string; src: string; url: string; };
-            export type CxCarouselGalleryItem = { additions: string[]; alt: string; cardType: 'asset' | 'folder' | 'link' | 'page' | 'space'; className: string; details: string; docType: '' | 'Album' | 'Audio' | 'Audio segment' | 'Image' | 'Multimedia' | 'ProjectDocument' | 'Story' | 'Video' | 'Widget'; filler: boolean; header: string; id: string; isClone: boolean; name: string; objectFit: 'contain' | 'cover' | 'fill' | 'none' | 'scale-down'; openInNewTab: boolean; pageId: string; rawId: string; size: string; src: string; url: string; };
+            export type CxBentoGridGalleryItem = { additions: string[]; alt: string; cardType: 'asset' | 'folder' | 'link' | 'page' | 'space'; className: string; details: string; docType: '' | 'Album' | 'Audio' | 'Audio segment' | 'Image' | 'Multimedia' | 'ProjectDocument' | 'Story' | 'Video' | 'Widget'; extension: string; filler: boolean; header: string; id: string; isClone: boolean; name: string; objectFit: 'contain' | 'cover' | 'fill' | 'none' | 'scale-down'; openInNewTab: boolean; pageId: string; rawId: string; size: string; src: string; url: string; };
+            export type CxCarouselGalleryItem = { additions: string[]; alt: string; cardType: 'asset' | 'folder' | 'link' | 'page' | 'space'; className: string; details: string; docType: '' | 'Album' | 'Audio' | 'Audio segment' | 'Image' | 'Multimedia' | 'ProjectDocument' | 'Story' | 'Video' | 'Widget'; extension: string; filler: boolean; header: string; id: string; isClone: boolean; name: string; objectFit: 'contain' | 'cover' | 'fill' | 'none' | 'scale-down'; openInNewTab: boolean; pageId: string; rawId: string; size: string; src: string; url: string; };
             export type CxChatbotChatbotEvent = { event: string; excludedFromPurposes: string[]; label: string; };
             export type CxTableTimeFormatterParams = { color: string; fontSize: string; fontWeight: string; inputUnit: string; locale: string; placeholder: string; style: dictionary; unitsFormat: string; displayStyle: string; paramsMapField: string; paramsMap: dictionary; };
             export type CxTableTextFormatParams = { colorMap: dictionary; color: string; };
@@ -2572,7 +2572,7 @@
         */
         retryOnError?: boolean;
         /**
-          * Maximum number of retry attempts when `retry-on-error` is enabled.
+          * Maximum number of retry attempts when `retry-on-error` is enabled. <br/> Set high enough to outlast a transient backend overload: a page full of images can push the transform service into 503s, and those images need to keep retrying until it recovers rather than falling back to a broken-image icon. The backoff is exponential and capped at 10s per attempt, so the attempts spread out instead of adding to the load.
         */
         maxRetries?: number;
         /**
@@ -5648,7 +5648,7 @@
         /**
           * 
         */
-        image?: { extension: string; height: number; originalUrl: string; rotation: number; url: string; width: number; x: number; y: number; };
+        image?: { extension: string; height: number; rotation: number; url: string; width: number; x: number; y: number; };
         /**
           * 
         */
@@ -6774,7 +6774,15 @@
         /**
           * The key to use for the id of the items in the masonry layout.
         */
-        idKey?: 'src' | 'loading' | 'alt' | 'hasError' | 'id' | 'objectFit';
+        idKey?: 'src' | 'extension' | 'loading' | 'alt' | 'hasError' | 'id' | 'objectFit';
+        /**
+          * The proxy format the item images were resolved with. <br/> Only used to decide whether a `srcset` may be generated: an original-file format paired with an animated source must be delivered untouched.
+        */
+        format?: string;
+        /**
+          * Whether `format` was picked by hand. When false each item's format follows its own file extension instead, so a mixed list can serve animated originals and resizable raster proxies side by side.
+        */
+        manualFormat?: boolean;
         /**
           * When true, forwards `no-crossorigin` to each inner `cx-image`, disabling CORS mode (e.g. in Site Builder contexts where CORS headers are absent).
         */
@@ -7879,6 +7887,14 @@
           * The ID of the default proxy format. This is a string that represents the ID of the selected proxy format from the list of available proxies.
         */
         defaultProxy?: string;
+        /**
+          * Whether the format listbox offers an `Auto` entry, which derives the proxy from the asset's file extension instead of the author naming one.
+        */
+        canAutoFormat?: boolean;
+        /**
+          * Whether `Auto` is the current choice. <br/> Tracked next to `selectedProxy` rather than encoded into it, so `selectedProxy` stays a real proxy id for every consumer that reads it — only the origin of that id differs.
+        */
+        autoFormat?: boolean;
         /**
           * 
         */
@@ -7961,6 +7977,10 @@
           * The default format to fall back to if the asset has no transformations or selected proxy.
         */
         defaultFormat?: string;
+        /**
+          * Whether the author picked the format by hand rather than letting it follow the asset's file extension. `false` (the default) means `Auto`.
+        */
+        manualFormat?: boolean;
         /**
           * Optional label rendered as the dialog title. Falls back to the localized "Asset format" term.
         */
@@ -8051,6 +8071,14 @@
           * Total number of items in the dataset, including those not yet loaded. When set, the scroll container height is extended to reflect the full dataset size so the scrollbar is accurate from the first render. Unloaded slots are approximated as 1×1 items.
         */
         totalItems?: number;
+        /**
+          * The proxy format the item images were resolved with. <br/> Only used to decide whether a `srcset` may be generated: an original-file format paired with an animated source must be delivered untouched.
+        */
+        format?: string;
+        /**
+          * Whether `format` was picked by hand. When false each item's format follows its own file extension instead, so a mixed grid can serve animated originals and resizable raster proxies side by side.
+        */
+        manualFormat?: boolean;
         /**
           * Delay in milliseconds between releasing one row of images and the next. <br/> Images are held back until their row is released, so the browser opens roughly one row's worth of requests at a time instead of one per rendered item. Each transform URL is an uncached backend render, and enough of them in parallel returns 503. <br/> A row also waits for the previous row's images to finish (capped by `ROW_RELEASE_TIMEOUT`), so this is the floor between releases rather than the exact cadence. Set to `0` to disable gating and let every rendered row load immediately.
         */
@@ -8211,6 +8239,14 @@
           * The real total number of data in the carousel. Not affected by chunking.
         */
         totalData?: number;
+        /**
+          * The proxy format the slide images were resolved with. <br/> Only used to decide whether a `srcset` may be generated: an original-file format paired with an animated source must be delivered untouched.
+        */
+        format?: string;
+        /**
+          * Whether `format` was picked by hand. When false each slide's format follows its own file extension instead, so a mixed carousel can serve animated originals and resizable raster proxies side by side.
+        */
+        manualFormat?: boolean;
         /**
           * When set, allows the user to navigate the carousel in the same direction indefinitely.
         */
@@ -9609,6 +9645,10 @@
           * Asset transformation proxy format key.
         */
         format?: string;
+        /**
+          * Whether `format` was picked by hand. When false each card's format follows its own file extension instead.
+        */
+        manualFormat?: boolean;
         /**
           * Asset transformations applied to the image.
         */
@@ -9735,6 +9775,10 @@
           * Asset transformation proxy format key.
         */
         format?: string;
+        /**
+          * Whether `format` was picked by hand. When false each item's format follows its own file extension instead.
+        */
+        manualFormat?: boolean;
         /**
           * Asset transformations applied to the image.
         */