@orangelogic/design-system 2.0.0-29DUO2-beta-3 → 2.0.0-29IORR-beta-2

package/library/packages/atoms/src/components/table/tabulator-tables/modules/Filter/Filter.d.ts

@@ -59,9 +59,16 @@ export default class Filter extends Module implements IFilter {
     trackChanges(): void;
     hasChanged(): boolean;
     /**
-     * Normally, filter operates on a single field. To create a filter that operates on multiple or all fields,
-     * first pass the field names (or none to match all) to this method, then use this method as the filter's field.
-     * @param fields - The fields to match against. If not provided, all fields will be matched.
+     * Normally, filter operates on a single field. To create a filter that operates on multiple
+     * or all registered columns, first pass the field names (or none to default to every
+     * registered column's field) to this method, then use this method as the filter's field.
+     *
+     * When `fields` is omitted, the search iterates only over fields that have a registered
+     * column. Data keys without a column (e.g. hidden payload fields) are skipped so the search
+     * matches what the user actually sees on screen. If the column manager has no columns yet
+     * (table not yet initialized), falls back to iterating all data keys.
+     *
+     * @param fields - The fields to match against. If not provided, all fields with a registered column will be matched.
      * @returns A function that can be used to match against the data.
      */
     createFilterFieldFunction(fields?: string[]): (data: any, filter: FilterType) => boolean;

package/library/packages/atoms/src/components/table/tabulator-tables/modules/Filter/formatter-display-resolvers.d.ts

@@ -0,0 +1,93 @@
+import { CompositeElement, ITabulator } from '../../../../../../../types/src/table';
+
+interface ResolverInput {
+    formatterParams: any;
+    rawValue: unknown;
+    rowData: Record<string, unknown>;
+    separator: string | undefined;
+    table: ITabulator | null | undefined;
+}
+declare function resolveCompositeElementSourceValue(element: CompositeElement, columnField: string, rawValue: unknown, rowData: Record<string, unknown>, separator: string | undefined): unknown;
+declare function resolveCompositeDisplayValues(input: ResolverInput, columnField: string): unknown[];
+declare function resolveLookupDisplayValues(input: ResolverInput): unknown[];
+declare function resolveArrayDisplayValues(input: ResolverInput): unknown[];
+declare function resolveTagDisplayValues(input: ResolverInput): unknown[];
+/**
+ * Mirrors the priority chain in link.ts:
+ * 1. label starts as the raw cell value
+ * 2. `labelField` (string nested-data path) overrides
+ * 3. `label` overrides — string wins; **function is skipped on purpose** because invoking
+ *    `label(cell)` requires a live `CellComponent` (with `getElement`, `getRow`, etc.).
+ *    Search will fall back to raw match for that case.
+ *
+ * Returns the **single** final label the formatter would render, never both `labelField`
+ * and `label` together (that would create a false positive against text the user does not see).
+ */
+declare function resolveLinkDisplayValues(input: ResolverInput): unknown[];
+declare function resolveMoneyDisplayValues(input: ResolverInput): unknown[];
+declare function resolveNumberDisplayValues(input: ResolverInput): unknown[];
+declare function resolveDatetimeDisplayValues(input: ResolverInput): unknown[];
+declare function resolveDatetimeDiffDisplayValues(input: ResolverInput): unknown[];
+declare function resolvePlaintextDisplayValues(input: ResolverInput): unknown[];
+declare function resolveTypographyDisplayValues(input: ResolverInput): unknown[];
+declare function resolveHtmlDisplayValues(input: ResolverInput): unknown[];
+declare function resolveTextareaDisplayValues(input: ResolverInput): unknown[];
+declare function resolveJsonDisplayValues(input: ResolverInput): unknown[];
+/**
+ * The mock cell handed to user-supplied `formatterLookup` and `paramsLookup` callbacks only
+ * exposes `getValue()` and `getData()` — there is no live `CellComponent`, so calls like
+ * `cell.getColumn()`, `cell.getRow()`, `cell.getElement()`, or `cell.getTable()` will throw.
+ * `safeCall` swallows those errors and the resolver returns `[]` for that row, falling back
+ * to raw-value matching. If a column needs richer cell access during adaptive lookup, the
+ * search will silently miss the formatted display — keep `formatterLookup` callbacks
+ * dependent only on cell value and row data for full search coverage.
+ */
+declare function resolveAdaptableDisplayValues(input: ResolverInput, columnField: string): unknown[];
+interface CollectFromDefinitionInput {
+    columnField: string;
+    formatter: unknown;
+    formatterParams: unknown;
+    rawValue: unknown;
+    rowData: Record<string, unknown>;
+    separator: string | undefined;
+    table: ITabulator | null | undefined;
+}
+declare function collectFormatterDisplayValuesFromDefinition(args: CollectFromDefinitionInput): unknown[];
+/**
+ * Entry point used by `Filter.createFilterFieldFunction`. Looks up the column for
+ * `field` from the table's column manager, reads its formatter definition, and
+ * dispatches to the matching resolver. Returns `[]` when no column is registered,
+ * the formatter is unknown, or the resolver produces no candidates.
+ *
+ * Pass an optional `columnCache` to avoid re-running `getColumnByField` for every row × key.
+ * The Filter pipeline iterates ~`rows * columns` times; without a cache the column manager
+ * is hit on each iteration. The caller (`createFilterFieldFunction`) owns the cache so its
+ * lifetime matches the search invocation, never leaking across filter calls.
+ *
+ * `null` cached entries mean "no column registered for this field" — they let us skip the
+ * lookup on subsequent rows for unknown fields too.
+ */
+export type ColumnDefinitionCache = Map<string, {
+    definition: any;
+} | null>;
+export declare function collectFormatterDisplayValues(table: ITabulator | null | undefined, field: string, rawValue: unknown, rowData: Record<string, unknown>, columnCache?: ColumnDefinitionCache): unknown[];
+export declare const __testables: {
+    collectFormatterDisplayValuesFromDefinition: typeof collectFormatterDisplayValuesFromDefinition;
+    resolveAdaptableDisplayValues: typeof resolveAdaptableDisplayValues;
+    resolveArrayDisplayValues: typeof resolveArrayDisplayValues;
+    resolveCompositeDisplayValues: typeof resolveCompositeDisplayValues;
+    resolveCompositeElementSourceValue: typeof resolveCompositeElementSourceValue;
+    resolveDatetimeDiffDisplayValues: typeof resolveDatetimeDiffDisplayValues;
+    resolveDatetimeDisplayValues: typeof resolveDatetimeDisplayValues;
+    resolveHtmlDisplayValues: typeof resolveHtmlDisplayValues;
+    resolveJsonDisplayValues: typeof resolveJsonDisplayValues;
+    resolveLinkDisplayValues: typeof resolveLinkDisplayValues;
+    resolveLookupDisplayValues: typeof resolveLookupDisplayValues;
+    resolveMoneyDisplayValues: typeof resolveMoneyDisplayValues;
+    resolveNumberDisplayValues: typeof resolveNumberDisplayValues;
+    resolvePlaintextDisplayValues: typeof resolvePlaintextDisplayValues;
+    resolveTagDisplayValues: typeof resolveTagDisplayValues;
+    resolveTextareaDisplayValues: typeof resolveTextareaDisplayValues;
+    resolveTypographyDisplayValues: typeof resolveTypographyDisplayValues;
+};
+export {};

package/library/packages/atoms/src/components/table/tabulator-tables/modules/GroupRows/Group.d.ts

@@ -1,4 +1,5 @@
 import { default as CxIconButton } from '../../../../icon-button/icon-button.ts';
+import { GroupLoadMoreEventPayload, GroupLoadMoreState } from '../../../../../../../types/src/table';
 import { default as Row } from '../../core/row/Row';
 import { default as GroupComponent } from './GroupComponent';
 import { default as GroupRows } from './GroupRows';
@@ -34,6 +35,8 @@ export default class Group {
     visible: boolean | ((key: any, count: number, data: any[], component: GroupComponent) => boolean);
     component: GroupComponent | null;
     addBindingsFlag?: boolean;
+    private _loadMoreRow;
+    private _loadMoreStateKey;
     constructor(groupManager: GroupRows, parent: Group | false, level: number, key: any, field: string | false, generator: GroupGenerator, oldGroup: Group | false);
     wipe(elementsOnly?: boolean): void;
     createElements(): void;
@@ -51,6 +54,11 @@ export default class Group {
     conformRowData(data: Record<string, any>): Record<string, any>;
     removeRow(row: Row): void;
     removeGroup(group: Group): void;
+    getPathKey(): string;
+    getLoadMoreState(): GroupLoadMoreState | undefined;
+    getGroupLoadMoreEventPayload(): GroupLoadMoreEventPayload;
+    generateLoadMoreRow(): Row | false;
+    private applyGroupIndent;
     getHeadersAndRows(): Array<Group | Row>;
     getData(visible?: boolean, transform?: string): any[];
     getRowCount(): number;

package/library/packages/atoms/src/components/table/tabulator-tables/modules/GroupRows/GroupComponent.d.ts

@@ -1,4 +1,4 @@
-import { IGroupComponent, ITabulator, ScrollToRowPosition } from '../../../../../../../types/src/table';
+import { GroupLoadMorePathSegment, IGroupComponent, ITabulator, ScrollToRowPosition } from '../../../../../../../types/src/table';
 import { default as Group } from './Group';
 
 export default class GroupComponent implements IGroupComponent {
@@ -11,6 +11,8 @@ export default class GroupComponent implements IGroupComponent {
     getRows(): any[];
     getSubGroups(): any[];
     getParentGroup(): GroupComponent | false;
+    getPath(): GroupLoadMorePathSegment[];
+    getPathKey(): string;
     isVisible(): boolean;
     show(): void;
     hide(): void;

package/library/packages/atoms/src/components/table/tabulator-tables/modules/GroupRows/GroupLoadMore.d.ts

@@ -0,0 +1,7 @@
+import { GroupLoadMoreEventPayload, GroupLoadMoreMeta, GroupLoadMorePathSegment, GroupLoadMoreState } from '../../../../../../../types/src/table';
+import { default as Group } from './Group';
+
+export declare function getGroupPath(group: Group): GroupLoadMorePathSegment[];
+export declare function getGroupPathKey(path: GroupLoadMorePathSegment[]): string;
+export declare function getGroupLoadMoreState(meta: GroupLoadMoreMeta | undefined, pathKey: string): GroupLoadMoreState | undefined;
+export declare function getGroupLoadMoreEventPayload(group: Group): GroupLoadMoreEventPayload;

package/library/packages/atoms/src/components/table/tabulator-tables/modules/GroupRows/GroupRows.d.ts

@@ -1,3 +1,4 @@
+import { GroupLoadMoreMeta } from '../../../../../../../types/src/table';
 import { default as Module } from '../../core/Module';
 import { default as Row } from '../../core/row/Row';
 import { default as RowComponent } from '../../core/row/RowComponent';
@@ -38,6 +39,7 @@ export default class GroupRows extends Module {
     setGroupStartOpen(values: GroupStartOpen | GroupStartOpen[]): void;
     private updateGroupVisibility;
     setGroupHeader(values: GroupHeaderGenerator | GroupHeaderGenerator[] | false): void;
+    setGroupLoadMoreMeta(meta: GroupLoadMoreMeta | undefined): void;
     userGetGroups(_values?: boolean): GroupComponent[];
     userGetGroup(key: any): GroupComponent | false;
     private findGroupByKey;

package/library/packages/atoms/src/components/table/tabulator-tables/modules/Page/Page.d.ts

@@ -4,7 +4,7 @@ import { default as Module } from '../../core/Module';
 import { default as Tabulator } from '../../core/Tabulator';
 
 export default class Page extends Module implements IPage {
-    static moduleName: string;
+    static readonly moduleName = "page";
     paginationElement: CxPagination;
     element: HTMLElement | null;
     size: number | true;
@@ -44,7 +44,7 @@ export default class Page extends Module implements IPage {
     /**
      * Pagination is mounted on `table.toolbar` (outside Tabulator's root element).
      * Tabulator.destroy() only clears the table element, so we must detach on destroy
-     * or a full re-init (e.g. paginationSizeSelector change) leaves duplicate cx-pagination nodes.
+     * or a full re-init (e.g. pageSizeOptions change) leaves duplicate cx-pagination nodes.
      */
     cleanup(): void;
     initializePaginator(): void;

package/library/packages/atoms/src/components/textarea/textarea.d.ts

@@ -1,4 +1,5 @@
 import { CortexFormControl, default as CortexElement } from '../../../../base/src/cortex-element.ts';
+import { TextareaRows } from '../../../../types/src/textarea';
 import { CSSResultGroup } from 'lit';
 
 /**
@@ -20,6 +21,8 @@ import { CSSResultGroup } from 'lit';
  * @csspart base - The component's base wrapper.
  * @csspart textarea - The internal `<textarea>` control.
  * @csspart character-count - The container that wraps the character count.
+ *
+ * @typedef {number | 'max'} TextareaRows - Use a number for a fixed row count. Use `'max'` to fill the parent container height (parent must have a definite height). With `'max'`, `resize="vertical"` and `resize="none"` work; `resize="auto"` does not (it is disabled).
  */
 export default class CxTextarea extends CortexElement implements CortexFormControl {
     static styles: CSSResultGroup;
@@ -27,6 +30,7 @@ export default class CxTextarea extends CortexElement implements CortexFormContr
     private readonly hasSlotController;
     private resizeObserver;
     input: HTMLTextAreaElement;
+    private formControlRoot;
     private hasFocus;
     title: string;
     /** The name of the textarea, submitted as a name/value pair with form data. */
@@ -43,9 +47,17 @@ export default class CxTextarea extends CortexElement implements CortexFormContr
     helpText: string;
     /** Placeholder text to show as a hint when the input is empty. */
     placeholder: string;
-    /** The number of rows to display by default. */
-    rows: number;
-    /** Controls how the textarea can be resized. */
+    /**
+     * The number of rows to display by default.
+     * Set to `"max"` (or `TextareaRows.Max`) to make the textarea fill its parent container height.
+     * The parent element must have a definite height (e.g. via flex, grid, or an explicit `height`) for `"max"` to take effect.
+     * With `"max"`, `resize="vertical"` (default) and `resize="none"` are supported; `resize="auto"` is not (fill height and auto-grow conflict, so auto resize is disabled).
+     */
+    rows: number | TextareaRows;
+    /**
+     * Controls how the textarea can be resized.
+     * When `rows` is `"max"`, `auto` is ignored; use `vertical` or `none`.
+     */
     resize: 'none' | 'vertical' | 'auto';
     /** Disables the textarea. */
     disabled: boolean;
@@ -87,13 +99,16 @@ export default class CxTextarea extends CortexElement implements CortexFormContr
     inputMode: 'none' | 'text' | 'decimal' | 'numeric' | 'tel' | 'search' | 'email' | 'url';
     /** The default value of the form control. Primarily used for resetting the form control. */
     defaultValue: string;
+    /** Tracks the px height applied by fill-mode so we can distinguish a host resize (recalculate) from a user drag (preserve). */
+    private _fillHeightPx;
     /** Gets the validity state object */
     get validity(): ValidityState;
     /** Gets the validation message */
     get validationMessage(): string;
-    connectedCallback(): void;
+    connectedUpdatedCallback(): void;
     runFirstUpdated(): void;
     disconnectedCallback(): void;
+    private updateResizeObserver;
     private handleBlur;
     private handleChange;
     private handleFocus;

package/library/packages/atoms/src/components/video/video.d.ts

@@ -96,6 +96,7 @@ export default class CxVideo extends ResizableElement {
     videoHeight: number;
     protected autoPlayTimeout: number | null;
     parsedName: string;
+    formattedPoster: string;
     /**
      * The current time of the video.
      */
@@ -130,7 +131,7 @@ export default class CxVideo extends ResizableElement {
     protected addVideoEventListeners(): void;
     protected removeVideoEventListeners(): void;
     attachSeekbar(): void;
-    protected setupVideoJsPlayer(): void;
+    protected setupVideoJsPlayer(src?: string): void;
     handleLoopChange(): Promise<void>;
     handleMutedChange(): Promise<void>;
     handleControlsChange(): Promise<void>;
@@ -138,6 +139,7 @@ export default class CxVideo extends ResizableElement {
     handleDisableRemotePlaybackChange(): Promise<void>;
     handleDisableVolumePanelChange(): Promise<void>;
     handlePosterChange(): Promise<void>;
+    handleFormattedPosterChange(): Promise<void>;
     handleSrcChange(): Promise<void>;
     handleParsedNameChange(): Promise<void>;
     private handleSizeChange;

package/library/packages/events/src/cx-asset-transformation-dialog-cancel.d.ts

@@ -0,0 +1,6 @@
+export type CxAssetTransformationDialogCancelEvent = CustomEvent<Record<PropertyKey, never>>;
+declare global {
+    interface GlobalEventHandlersEventMap {
+        'cx-asset-transformation-dialog-cancel': CxAssetTransformationDialogCancelEvent;
+    }
+}

package/library/packages/events/src/cx-asset-transformation-dialog-confirm.d.ts

@@ -0,0 +1,11 @@
+import { Transformation } from '../../types/src/asset-link-format';
+
+export type CxAssetTransformationDialogConfirmEvent = CustomEvent<{
+    format: string;
+    transformations: Transformation[];
+}>;
+declare global {
+    interface GlobalEventHandlersEventMap {
+        'cx-asset-transformation-dialog-confirm': CxAssetTransformationDialogConfirmEvent;
+    }
+}

package/library/packages/events/src/cx-asset-transformation-dialog-delete.d.ts

@@ -0,0 +1,6 @@
+export type CxAssetTransformationDialogDeleteEvent = CustomEvent<Record<PropertyKey, never>>;
+declare global {
+    interface GlobalEventHandlersEventMap {
+        'cx-asset-transformation-dialog-delete': CxAssetTransformationDialogDeleteEvent;
+    }
+}

package/library/packages/events/src/cx-bento-range-change.d.ts

@@ -0,0 +1,9 @@
+export type CxBentoRangeChangeEvent = CustomEvent<{
+    first: number;
+    last: number;
+}>;
+declare global {
+    interface GlobalEventHandlersEventMap {
+        'cx-bento-range-change': CxBentoRangeChangeEvent;
+    }
+}

package/library/packages/events/src/cx-content-builder-gallery-fetched.d.ts

@@ -0,0 +1,10 @@
+import { Image } from '../../types/src/gallery-config';
+
+export type CxContentBuilderGalleryFetchedEvent = CustomEvent<{
+    data: Image[];
+}>;
+declare global {
+    interface GlobalEventHandlersEventMap {
+        'cx-content-builder-gallery-fetched': CxContentBuilderGalleryFetchedEvent;
+    }
+}

package/library/packages/events/src/cx-lightbox-close.d.ts

@@ -0,0 +1,6 @@
+export type CxLightboxCloseEvent = CustomEvent<Record<PropertyKey, unknown>>;
+declare global {
+    interface GlobalEventHandlersEventMap {
+        'cx-lightbox-close': CxLightboxCloseEvent;
+    }
+}

package/library/packages/events/src/cx-lightbox-download.d.ts

@@ -0,0 +1,11 @@
+import { GalleryItem } from '../../types/src/gallery-item';
+
+export type CxLightboxDownloadEvent = CustomEvent<{
+    index: number;
+    item: GalleryItem;
+}>;
+declare global {
+    interface GlobalEventHandlersEventMap {
+        'cx-lightbox-download': CxLightboxDownloadEvent;
+    }
+}

package/library/packages/events/src/cx-unauthorized.d.ts

@@ -0,0 +1,10 @@
+export type CxUnauthorizedEvent = CustomEvent<CxUnauthorizedDetail>;
+export type CxUnauthorizedDetail = {
+    status: number;
+    url: string;
+};
+declare global {
+    interface GlobalEventHandlersEventMap {
+        'cx-unauthorized': CxUnauthorizedEvent;
+    }
+}

package/library/packages/events/src/cx-video-format-picker-delete.d.ts

@@ -0,0 +1,6 @@
+export type CxVideoFormatPickerDeleteEvent = CustomEvent<Record<PropertyKey, unknown>>;
+declare global {
+    interface GlobalEventHandlersEventMap {
+        'cx-video-format-delete': CxVideoFormatPickerDeleteEvent;
+    }
+}

package/library/packages/events/src/cx-video-format-picker-select.d.ts

@@ -0,0 +1,8 @@
+import { VideoFormatValue } from '../../types/src/video-format-picker';
+
+export type CxVideoFormatPickerSelectEvent = CustomEvent<VideoFormatValue>;
+declare global {
+    interface GlobalEventHandlersEventMap {
+        'cx-video-format-select': CxVideoFormatPickerSelectEvent;
+    }
+}

package/library/packages/events/src/events.d.ts

@@ -14,6 +14,10 @@ export * from './cx-asset-data-display-slot-change';
 export * from './cx-asset-picker-delete';
 export * from './cx-asset-picker-select';
 export * from './cx-asset-request-status';
+export * from './cx-asset-transformation-dialog-cancel';
+export * from './cx-asset-transformation-dialog-confirm';
+export * from './cx-asset-transformation-dialog-delete';
+export * from './cx-bento-range-change';
 export * from './cx-bento-resize';
 export * from './cx-bicolor-picker-change';
 export * from './cx-blur';
@@ -21,8 +25,8 @@ export * from './cx-border-input-group-change';
 export * from './cx-cancel';
 export * from './cx-cancel-connection';
 export * from './cx-cancel-upload';
-export * from './cx-chart-plan-change';
 export * from './cx-change';
+export * from './cx-chart-plan-change';
 export * from './cx-clear';
 export * from './cx-clear-cache';
 export * from './cx-clear-upload';
@@ -38,6 +42,7 @@ export * from './cx-comment-mention-select';
 export * from './cx-connect';
 export * from './cx-connected';
 export * from './cx-content-builder-gallery-change';
+export * from './cx-content-builder-gallery-fetched';
 export * from './cx-content-builder-page-change';
 export * from './cx-content-builder-page-delete';
 export * from './cx-content-builder-translatable-value-change';
@@ -52,6 +57,8 @@ export * from './cx-dot-status-click';
 export * from './cx-download-format-picker-delete';
 export * from './cx-download-format-picker-select';
 export * from './cx-download-format-request-status';
+export * from './cx-video-format-picker-delete';
+export * from './cx-video-format-picker-select';
 export * from './cx-drag-end';
 export * from './cx-drag-start';
 export * from './cx-e-chart-drill-down';
@@ -88,6 +95,8 @@ export * from './cx-invoked';
 export * from './cx-keydown';
 export * from './cx-lazy-change';
 export * from './cx-lazy-load';
+export * from './cx-lightbox-close';
+export * from './cx-lightbox-download';
 export * from './cx-list-editor-change';
 export * from './cx-load';
 export * from './cx-mark-favorite';
@@ -138,6 +147,7 @@ export * from './cx-time-based-change';
 export * from './cx-time-update';
 export * from './cx-typeface-change';
 export * from './cx-typeface-download';
+export * from './cx-unauthorized';
 export * from './cx-unmark-favorite';
 export * from './cx-video-click';
 export * from './cx-video-editor-track-canvas-ready';

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

@@ -44,6 +44,8 @@ export default class CxCropper extends CortexElement {
     disabled: boolean;
     loadable: boolean;
     loading: boolean;
+    multiple: boolean;
+    useInternalLoading: boolean;
     private showLoading;
     private handleLoadingChange;
     render(): TemplateResult;

package/library/packages/molecules/src/cropper/react/Cropper.d.ts

@@ -26,6 +26,7 @@ type Props = {
     };
     loadable: boolean;
     loading: boolean;
+    multiple: boolean;
     resizer: {
         height: number;
         maxHeight: number;
@@ -33,6 +34,7 @@ type Props = {
         width: number;
     };
     rotation: number;
+    useInternalLoading?: boolean;
 };
 declare const CropPreviewer: import('react').ForwardRefExoticComponent<Props & import('react').RefAttributes<unknown>>;
 export default CropPreviewer;

package/library/packages/molecules/src/estimated-reading-time/estimated-reading-time.d.ts

@@ -7,7 +7,8 @@ import { CSSResultGroup } from 'lit';
  * @summary Displays the estimated reading time for a target element's text content.
  *
  * @description Calculates reading time based on the visible text of a target element,
- * using an average reading speed of 238 words per minute.
+ * using an average reading speed of 238 words per minute. Rendered as `"<duration> read"`
+ * (e.g. "12 minutes read", "1 hour, 1 minute read"), with the duration formatted by `cx-format-time`.
  * `resolveTarget` is a JS-only property (no HTML attribute) since it accepts non-serialisable values.
  * If `resolveTarget` is not set, the component does nothing.
  *
@@ -30,7 +31,7 @@ export default class CxEstimatedReadingTime extends CortexElement {
     private observer;
     /** The target element to calculate reading time for. Accepts a raw HTMLElement or a function that returns one. */
     resolveTarget: HTMLElement | (() => HTMLElement | null) | null;
-    /** Display style for the formatted reading time. Defaults to "long". */
+    /** Display style forwarded to `cx-format-time`. Defaults to "long". */
     displayStyle: DisplayStyle;
     private durationMs;
     connectedCallback(): void;

package/library/packages/molecules/src/folder-select/components/folder-select-tree/folder-select-tree.d.ts

@@ -1,6 +1,8 @@
 import { default as CxButton } from '../../../../../atoms/src/components/button/button.ts';
 import { default as CxTree } from '../../../../../atoms/src/components/tree/tree.ts';
+import { default as CxTreeItem } from '../../../../../atoms/src/components/tree-item/tree-item.ts';
 import { default as CortexElement } from '../../../../../base/src/cortex-element.ts';
+import { CxSelectionChangeEvent } from '../../../../../events/src/events.ts';
 import { Folder, FolderSelectApi } from '../../../../../types/src/folder-select';
 import { TemplateResult } from 'lit';
 import { default as CxFolderSelectTreeItem } from '../folder-select-tree-item/folder-select-tree-item';
@@ -22,6 +24,7 @@ export default class CxFolderSelectTree extends CortexElement {
     baseUrl: string;
     extraFolderId: string;
     extraFolderTitle: string;
+    extraFolderIcon: string;
     seeThru: boolean;
     extraFolderData: Folder | null;
     api?: FolderSelectApi;
@@ -30,6 +33,18 @@ export default class CxFolderSelectTree extends CortexElement {
     data: Folder[];
     hasMore: boolean;
     loading: boolean;
+    /**
+     * Selected folders encoded as `${path}-${id}`. Owned by this component
+     * and forwarded down to all cx-folder-select-tree-items so they can
+     * recompute their selected/indeterminate state declaratively.
+     */
+    currentRootIDsSet: Set<string>;
+    /**
+     * IDs (`${path}-${id}`) explicitly unselected while their ancestor was
+     * selected. Used so a selected ancestor renders as indeterminate when a
+     * descendant has been unchecked.
+     */
+    removedIDs: string[];
     get empty(): boolean;
     /**
      * This is used to render the cx-tree inside the cx-folder-select without the shadow root so that the cx-folder-select can query select the cx-tree inside
@@ -37,6 +52,17 @@ export default class CxFolderSelectTree extends CortexElement {
     createRenderRoot(): this;
     runFirstUpdated(): void;
     handleExtraFolderIdChange(): Promise<void>;
+    /**
+     * Update `currentRootIDsSet` from a tree-item's toggle. Per-folder
+     * selection: each folder is independent, so a click only adds/removes
+     * the clicked folder — never its ancestors or descendants. Parents
+     * showing an indeterminate hint is purely visual (computed in
+     * `cx-folder-select-tree-item.syncBoxes` from path-prefix matches),
+     * not a real selection.
+     *
+     * Only runs in multiple mode — single mode is still driven by `selectedValue`.
+     */
+    handleSelectedChange(event: CxSelectionChangeEvent<CxTreeItem>): Promise<void>;
     loadMore(event: MouseEvent): Promise<void>;
     handleFetchFolders(): Promise<void>;
     private fetchFolders;

package/library/packages/molecules/src/folder-select/components/folder-select-tree-item/folder-select-tree-item.d.ts

@@ -19,14 +19,45 @@ export default class CxFolderSelectTreeItem extends CortexElement {
         'cx-tree-item': typeof CxTreeItem;
     };
     role: string;
+    /**
+     * cx-tree's syncCheckboxes/syncAncestors machinery walks `parentElement`
+     * and treats anything with `role="treeitem"` as a CxTreeItem. We expose
+     * this wrapper as a treeitem (for ARIA + selection plumbing) but it
+     * isn't a real CxTreeItem — it has no `getChildrenItems`. Telling
+     * syncAncestors to skip past us prevents `treeItem.getChildrenItems is
+     * not a function` and matches our per-folder selection model where
+     * parent state isn't auto-synced from children.
+     */
+    disabledSyncCheckboxes: boolean;
     readonly treeItem: CxTreeItem;
     folderId: string;
     hasChildren: boolean;
+    selectable: boolean;
     fullPath: string;
     docType: MediaType;
     name: string;
     representativeAssetId: string;
     selectedValue: string;
+    /**
+     * Selection mode propagated from cx-folder-select-tree.
+     * When `'multiple'`, selection state is driven declaratively from
+     * `currentRootIDsSet` / `removedIDs` via `syncBoxes()` (file-on-demand pattern),
+     * so it survives data reloads (search filters) and parents can show
+     * indeterminate from selected descendants without those descendants
+     * being loaded yet. When `'single'`, the legacy `selectedValue === folderId`
+     * binding on the inner cx-tree-item is used.
+     */
+    selection: 'multiple' | 'single';
+    /**
+     * Set of selected root IDs encoded as `${path}-${id}`. The set is owned by
+     * cx-folder-select-tree and passed in; tree-items only read from it.
+     */
+    currentRootIDsSet: Set<string>;
+    /**
+     * IDs (`${path}-${id}`) explicitly unchecked while their ancestor was
+     * selected. Used to render `indeterminate` on a selected ancestor.
+     */
+    removedIDs: string[];
     token: string;
     bearerToken: string;
     baseUrl: string;
@@ -34,6 +65,8 @@ export default class CxFolderSelectTreeItem extends CortexElement {
     api?: FolderSelectApi;
     excludeVirtualFolders: boolean;
     url: string;
+    /** Overrides the default `folder` icon name when set. */
+    icon: string;
     data: Folder[] | null;
     hasMore: boolean;
     loading: boolean;
@@ -47,6 +80,19 @@ export default class CxFolderSelectTreeItem extends CortexElement {
     }): Promise<GetFolderResponse>;
     loadMore(event: MouseEvent): Promise<void>;
     private handleLazyLoad;
+    /**
+     * Recompute this tree-item's selected/indeterminate state from the
+     * top-level selection set, purely declaratively. This lets us:
+     * - Persist selection across data reloads (e.g. when the user types a
+     *   search term, items get re-rendered but their state is recomputed
+     *   from the same set).
+     * - Show a parent as indeterminate when a descendant 3-4 levels deep
+     *   is selected, even if the descendant isn't loaded yet — we only
+     *   need its path prefix to match.
+     *
+     * Mirrors `cx-folder-item.syncBoxes` from packages/organisms/file-on-demand.
+     */
+    syncBoxes(): Promise<void>;
     render(): TemplateResult;
 }
 declare global {