@yuuvis/client-framework 2.18.0 → 2.20.0

package/tile-list/lib/tile-list/tile-list.component.d.ts

@@ -1,5 +1,5 @@
 import { ElementRef, OnInit } from '@angular/core';
-import { DmsObject, ResolvedObjectConfigItem, SearchQuery, SearchResultItem } from '@yuuvis/client-core';
+import { DmsObject, SearchQuery, SearchResultItem } from '@yuuvis/client-core';
 import { BooleanInput } from '@angular/cdk/coercion';
 import { MatMenuTrigger } from '@angular/material/menu';
 import { Action } from '@yuuvis/client-framework/actions';
@@ -11,171 +11,626 @@ import * as i0 from "@angular/core";
 type InnerTileData = TileData & {
     actions: any;
 };
+/**
+ * Query-driven tile list that renders `DmsObject` search results as rich, configurable
+ * tiles based on `ObjectConfig` definitions.
+ *
+ * The component wraps `yuv-query-list` and adds DMS-specific concerns: it resolves the
+ * `ObjectConfigRecord` for each result item (via `ObjectConfigService`), maps raw
+ * `SearchResultItem` data to the `TileData` view model, and supports per-object-type
+ * flavors, inline actions, context menus, and keyboard shortcuts for copy/cut.
+ *
+ * **Key Features:**
+ * - Automatic object config resolution (title, description, icon, meta, aside, actions)
+ * - Per-tile action buttons rendered from the resolved `ObjectConfigRecord`
+ * - Optional `ObjectFlavor` overlay to switch the visual representation of specific SOTs
+ * - Server-side pagination forwarded from the inner `yuv-query-list`
+ * - Multi-selection with Shift/Ctrl modifier keys and mouse drag-to-select
+ * - Programmatic pre-selection by object ID (`preselect` input, `selectById()` method)
+ * - Per-item CSS highlight styles via the `highlights` input
+ * - Optimistic list updates without a full re-fetch (`updateListItems`, `updateTileList`, `dropItems`)
+ * - Keyboard shortcuts: **Ctrl+C** emits `tileCopy`, **Ctrl+X** emits `tileCut`
+ * - Optional custom context menu via projected `TileActionsMenuComponent`
+ * - Isolated tile config bucket so multiple instances can have different column layouts
+ *
+ * **Content Projection Slots:**
+ * - `TileActionsMenuComponent` — optional; project a `<yuv-tile-actions-menu>` to attach
+ *   a context menu to every tile's action trigger.
+ * - `#empty` — optional template reference; shown when the query returns no results.
+ *
+ * **Basic usage:**
+ * ```html
+ * <yuv-tile-list [query]="query" (itemSelect)="onSelect($event)" />
+ * ```
+ *
+ * **Multi-select with custom bucket and highlights:**
+ * ```html
+ * <yuv-tile-list
+ *   bucket="my-feature"
+ *   [query]="query"
+ *   [multiselect]="true"
+ *   [highlights]="highlights"
+ *   (selectionChange)="onSelectionChange($event)"
+ * />
+ * ```
+ *
+ * **With context menu:**
+ * ```html
+ * <yuv-tile-list [query]="query" (ctxMenu)="onCtxMenu($event)">
+ *   <yuv-tile-actions-menu>
+ *     <button mat-menu-item (click)="openDetails()">Open</button>
+ *   </yuv-tile-actions-menu>
+ * </yuv-tile-list>
+ * ```
+ */
 export declare class TileListComponent implements OnInit {
     #private;
+    /**
+     * Optional projected `TileActionsMenuComponent` instance.
+     *
+     * When present, its `matMenu()` is wired as the context menu for every tile's
+     * action trigger button. The menu closes automatically whenever the user selects
+     * a menu item (managed by `#closeMenuEffect`).
+     *
+     * Project it into the component:
+     * ```html
+     * <yuv-tile-list ...>
+     *   <yuv-tile-actions-menu>
+     *     <button mat-menu-item>Open</button>
+     *   </yuv-tile-actions-menu>
+     * </yuv-tile-list>
+     * ```
+     */
     menuComponent: import("@angular/core").Signal<TileActionsMenuComponent | undefined>;
-    menu: import("@angular/core").Signal<import("@angular/material/menu").MatMenu | null>;
+    /**
+     * Optional projected element shown when the query returns an empty result set.
+     *
+     * Reference the element with the `#empty` template variable:
+     * ```html
+     * <yuv-tile-list ...>
+     *   <div #empty>No items found.</div>
+     * </yuv-tile-list>
+     * ```
+     */
     emptyContent: import("@angular/core").Signal<ElementRef<any> | undefined>;
+    /**
+     * Reference to the inner `QueryListComponent` instance.
+     *
+     * Used internally to delegate imperative operations (select, multiSelect, refresh, …).
+     * Prefer the public API methods on this component over accessing `list()` directly from
+     * the parent, as the inner list's API may change independently.
+     */
     list: import("@angular/core").Signal<QueryListComponent<TileData>>;
-    menuTriggers: import("@angular/core").Signal<readonly MatMenuTrigger[]>;
-    transformer: (res: SearchResultItem[]) => {
-        actions: Action[];
-        id: string;
-        objectTypeId: string;
-        icon?: ResolvedObjectConfigItem;
-        title: ResolvedObjectConfigItem;
-        description?: ResolvedObjectConfigItem;
-        meta?: ResolvedObjectConfigItem;
-        aside?: ResolvedObjectConfigItem;
-        badges?: import("@yuuvis/client-core").ObjectConfigBadge[];
-        instanceData?: Record<string, unknown>;
-        dmsObject: DmsObject;
-    }[];
-    onCopy(event: Event): void;
-    onCut(event: Event): void;
-    private oc?;
-    private _selection;
-    private _lastSelection?;
-    selectedTile: import("@angular/core").WritableSignal<TileData[]>;
     /**
-     * The ID of the selected list item
+     * All `MatMenuTrigger` instances rendered inside the tile list.
+     *
+     * Used by `#closeMenuEffect` to close every open context/action menu when the user
+     * selects a menu item, ensuring only one menu is open at a time.
      */
-    selection: import("@angular/core").WritableSignal<string[]>;
+    menuTriggers: import("@angular/core").Signal<readonly MatMenuTrigger[]>;
     /**
-     * Tile configurations are stored globally for all apps. If you want a
-     * separate config for your app/component you can specify a bucket. A bucket
-     * is basically an ID where your custom tile config will be stored and
-     * retrieved. Buckets should be unique so be sure to use a unique namespace.
+     * Namespace key for storing and retrieving this instance's tile configuration.
+     *
+     * Tile column/field layout is persisted globally via `ObjectConfigService`. Providing
+     * a bucket isolates this instance's configuration from the global default, so two
+     * tile lists with different purposes (e.g. inbox vs. archive) can each remember their
+     * own preferred layout independently.
+     *
+     * Use a unique, stable string — e.g. `"my-app.inbox-list"`. If omitted, the global
+     * default configuration is used.
      */
     bucket: import("@angular/core").InputSignal<string | undefined>;
     /**
-     * The number of items to display per page.
+     * Number of result items to request per page from the search service.
+     *
+     * Forwarded to the inner `QueryListComponent`. When the total result count exceeds
+     * this value, pagination controls appear. Reducing this number improves initial load
+     * time; increasing it reduces the need for pagination.
+     *
+     * @default SearchService.DEFAULT_QUERY_SIZE
      */
     pageSize: import("@angular/core").InputSignal<number>;
     /**
-     * Sets up the ability to select multiple tiles
+     * Enables multi-selection mode.
+     *
+     * When `true`, the user can hold **Shift** to range-select or **Ctrl** to toggle
+     * individual tiles, and mouse drag-to-select becomes available. `selectionChange`
+     * then emits the full selection array; `itemSelect` still emits only the most
+     * recently added single tile.
+     *
      * @default false
      */
     multiselect: import("@angular/core").InputSignal<boolean>;
     /**
-     * If `true`, the tiles will be rendered in a more compact, denser style.
+     * Renders tiles in a compact, reduced-height style.
+     *
+     * Drives the `[class.dense]` host binding. Use this when vertical space is limited
+     * or when many items need to be visible at once without scrolling.
+     *
      * @default false
      */
     dense: import("@angular/core").InputSignal<boolean>;
     /**
-     * Configuration options for the tile list component.
+     * Extended configuration options for the tile list.
+     *
+     * See `TileListConfigOptions` for the full set of options, including:
+     * - `actionContext` — passed to `ActionsService.getActionById()` when resolving inline
+     *   tile actions, so actions can behave differently per context.
+     * - `configTypes` — virtual config type overrides that let you map specific
+     *   object-type / SOT combinations to a different `ObjectConfigRecord` entry.
      */
     options: import("@angular/core").InputSignal<TileListConfigOptions | undefined>;
     /**
-     * The object flavor to be applied to the tiles.
+     * Object flavor to overlay on matching tiles.
+     *
+     * An `ObjectFlavor` defines an alternative visual representation for objects that carry
+     * a specific SOT. When set, tiles whose `DmsObject.sots` array includes
+     * `flavor.sot` are rendered using the config entry identified by `flavor.id` instead
+     * of their own object-type config.
+     *
+     * Changes are applied reactively via `#flavorEffect` and re-evaluated against the
+     * last raw result set via `applyFlavor()`.
      */
     flavor: import("@angular/core").InputSignal<ObjectFlavor | undefined>;
     /**
-     * The currently applied object flavor.
+     * The search query to execute.
+     *
+     * Accepts a structured `SearchQuery` object or a raw CMIS query string. The query is
+     * re-executed reactively every time this input changes. The result set must include the
+     * `system:objectTypeId` field — tiles without a resolved object type will throw at
+     * mapping time.
      */
-    appliedFlavor?: ObjectFlavor;
+    query: import("@angular/core").InputSignal<string | SearchQuery | null | undefined>;
     /**
-     * The search query to be executed. This may be a SearchQuery object or a CMIS query statement.
-     * Ensure that the query includes the object type ID field to allow proper tile rendering.
+     * Object IDs to select as soon as the list finishes loading.
+     *
+     * If the list is still busy when this input is set, the IDs are stored internally and
+     * applied once the query completes (via `#preselectEffect`). Items whose IDs are not
+     * found in the current result set are silently ignored.
+     *
+     * For programmatic selection after the list is loaded, prefer `selectById()`.
+     *
+     * @default []
      */
-    query: import("@angular/core").InputSignal<string | SearchQuery | null | undefined>;
     preselect: import("@angular/core").InputSignal<string[]>;
+    /**
+     * Per-item CSS style overrides rendered as inline styles on matching tiles.
+     *
+     * Each `TileListHighlight` entry specifies an array of object IDs and a
+     * `cssStyles` record. All styles for the same ID are merged, with later entries in
+     * the array taking precedence. Used to visually call out specific items (e.g. newly
+     * created, recently modified, flagged).
+     *
+     * @default []
+     */
     highlights: import("@angular/core").InputSignal<TileListHighlight[] | null>;
-    highlightStyles: import("@angular/core").Signal<Record<string, Record<string, unknown>>>;
     /**
-     * Prevent selection changes while the provided function returns false.
+     * Guard function that temporarily blocks all selection changes.
+     *
+     * Forwarded to the inner `ListComponent`. As long as the returned predicate evaluates
+     * to `true`, any attempt to change the selection is silently ignored. Useful when the
+     * parent has unsaved changes tied to the current selection.
+     *
+     * @default () => false  (never prevents)
      */
     preventChangeUntil: import("@angular/core").InputSignal<() => boolean>;
     /**
-     * If `true`, the list will select an item automatically on initialization.
-     * First, list will search for an item item that has the "selected"-attribute
-     * and is not disabled. If no such item exists, the first item will be selected.
+     * Automatically selects an item when the list is first rendered.
+     *
+     * Follows the same priority as `ListComponent.autoSelect`: first non-disabled item
+     * with the `selected` attribute, then index 0. Accepts any truthy string so it can
+     * be set as a plain HTML attribute: `<yuv-tile-list autoSelect>`.
+     *
      * @default false
      */
     autoSelect: import("@angular/core").InputSignalWithTransform<boolean, BooleanInput>;
+    /**
+     * Suppresses the component's built-in context menu handling.
+     *
+     * When `true`, right-clicking a tile does not call `event.preventDefault()`, does not
+     * auto-select the right-clicked tile, and does not emit `ctxMenu`. Use this when the
+     * parent wants to handle `contextmenu` events itself.
+     *
+     * @default false
+     */
     disableCustomContextMenu: import("@angular/core").InputSignal<boolean>;
     /**
-     * Emitted when a list item has been selected
+     * Emits the `TileData` of the most recently selected tile.
+     *
+     * In single-select mode this fires for every selection change. In multi-select mode
+     * it fires only when exactly one tile ends up selected (i.e. a plain click with no
+     * modifier keys). For the full multi-selection result, listen to `selectionChange`.
      */
     itemSelect: import("@angular/core").OutputEmitterRef<TileData>;
+    /**
+     * Emits the currently selected tiles when the user presses **Ctrl+C**.
+     *
+     * The parent is responsible for handling the actual copy operation (e.g. writing to
+     * the clipboard or storing the objects for a subsequent paste action). The default
+     * browser copy behavior is suppressed.
+     */
     tileCopy: import("@angular/core").OutputEmitterRef<TileData[]>;
+    /**
+     * Emits the currently selected tiles when the user presses **Ctrl+X**.
+     *
+     * The parent is responsible for handling the cut operation. The default browser cut
+     * behavior is suppressed. Typically used together with `dropItems()` on a target list
+     * to implement a move-via-clipboard interaction.
+     */
     tileCut: import("@angular/core").OutputEmitterRef<TileData[]>;
+    /**
+     * Mirrors the inner `QueryListComponent.busy` signal as an output event.
+     *
+     * Emits `true` when a query request starts and `false` when it completes (or errors).
+     * Useful when the parent needs to react to loading state changes without holding a
+     * `@ViewChild` reference to this component.
+     */
     busy: import("@angular/core").OutputEmitterRef<boolean>;
+    /**
+     * Emits once per query execution when the search result arrives.
+     *
+     * Provides the server-side total item count and the raw `SearchResultItem[]` for the
+     * current page. Forwarded directly from the inner `QueryListComponent`.
+     */
     queryResult: import("@angular/core").OutputEmitterRef<{
         totalCount: number;
         items: SearchResultItem[];
     }>;
     /**
-     * Emitted when selected items changed. If 'multiselect' input is set to true, this will
-     * emit the whole selection, while 'itemSelect' will only emit the item that currently
-     * has bee added to the selection.
+     * Emits the full current selection as `TileData[]` on every selection change.
+     *
+     * Unlike `itemSelect` — which emits a single tile — this output always reflects the
+     * complete selection. In single-select mode the array contains at most one element.
+     * Emits an empty array when the selection is cleared.
      */
     selectionChange: import("@angular/core").OutputEmitterRef<TileData[]>;
     /**
-     * Emitted when a list item has been double-clicked
+     * Emits the `TileData` of a tile when it is double-clicked.
+     *
+     * The primary single-click selection is handled separately via `itemSelect`. Use this
+     * output to trigger a secondary action such as opening a detail view or navigating
+     * to a route.
      */
     itemDblClick: import("@angular/core").OutputEmitterRef<TileData>;
+    /**
+     * Emits when the user right-clicks a tile and `disableCustomContextMenu` is `false`.
+     *
+     * Provides the originating mouse event (for positioning a custom menu overlay) and
+     * the current selection as an array of object IDs. The right-clicked tile is
+     * auto-selected before the event fires if it was not already part of the selection.
+     */
     ctxMenu: import("@angular/core").OutputEmitterRef<{
         event: MouseEvent | PointerEvent;
         selection: any;
     }>;
+    /**
+     * The `MatMenu` instance resolved from the projected `TileActionsMenuComponent`.
+     *
+     * `null` when no `TileActionsMenuComponent` is projected. Used in the template to
+     * conditionally bind `[matMenuTriggerFor]` on tile action buttons.
+     */
+    menu: import("@angular/core").Signal<import("@angular/material/menu").MatMenu | null>;
+    /**
+     * The full `TileData` objects for all currently selected tiles.
+     *
+     * Updated on every selection change alongside `selection`. Prefer this signal when
+     * the parent needs rich tile data (fields, DMS object reference, actions) rather than
+     * just IDs.
+     */
+    selectedTile: import("@angular/core").WritableSignal<TileData[]>;
+    /**
+     * Object IDs of the currently selected tiles.
+     *
+     * A flat `string[]` signal — convenient for ID comparisons, permission checks, or
+     * passing to services that work with IDs. For the full tile data, use `selectedTile`.
+     */
+    selection: import("@angular/core").WritableSignal<string[]>;
+    /**
+     * The `ObjectFlavor` currently applied to matching tiles, or `undefined` if none.
+     *
+     * Toggled by `applyFlavor()`: calling it with the same flavor a second time clears it
+     * (acts as a toggle). Persisted across query refreshes until explicitly changed.
+     */
+    appliedFlavor?: ObjectFlavor;
+    /**
+     * Computed map of per-object-ID inline CSS styles derived from the `highlights` input.
+     *
+     * Merges all `TileListHighlight` entries that reference the same ID so the template
+     * only needs a single lookup: `highlightStyles()[item.id]`. Returns an empty object
+     * for IDs with no highlight rules.
+     */
+    highlightStyles: import("@angular/core").Signal<Record<string, Record<string, unknown>>>;
+    /**
+     * The `TileData` view models currently rendered in the list.
+     *
+     * Populated by `onQueryResult()` after each successful search response and also
+     * prepended by `dropItems()`. The template iterates over this signal directly.
+     * Read this from the parent to access displayed tile data without an extra query.
+     */
     items: import("@angular/core").WritableSignal<TileData[]>;
+    /**
+     * Indicates whether at least one search has been executed successfully.
+     *
+     * Remains `false` until the first `onQueryResult()` call. Use this in the template
+     * to distinguish between "initial loading" (show a spinner) and "empty result"
+     * (show the empty-state slot) without relying on `items().length` alone.
+     */
     searchExecuted: import("@angular/core").WritableSignal<boolean>;
+    private objectConfig?;
+    private _selection;
+    private _lastSelection?;
     constructor();
+    ngOnInit(): void;
+    /**
+     * Host **Ctrl+C** handler — emits the current selection via `tileCopy`.
+     *
+     * Suppresses the default browser copy behavior. Fires only when at least one tile
+     * is selected. Bound via the `host` metadata as `(keydown.control.c)`.
+     *
+     * @param event The keyboard event (used to call `preventDefault`).
+     */
+    onCopy(event: Event): void;
+    /**
+     * Host **Ctrl+X** handler — emits the current selection via `tileCut`.
+     *
+     * Suppresses the default browser cut behavior. Fires only when at least one tile
+     * is selected. Bound via the `host` metadata as `(keydown.control.x)`.
+     *
+     * @param event The keyboard event (used to call `preventDefault`).
+     */
+    onCut(event: Event): void;
+    /**
+     * Handles a double-click event forwarded from the inner `QueryListComponent`.
+     *
+     * If the double-clicked tile is not already the sole selected item, it is selected
+     * first (without modifier keys) so that `itemDblClick` always fires in the context
+     * of a known selection state. Then `itemDblClick` is emitted with the tile's data.
+     *
+     * Called from the template via `(itemDoubleClick)`. Not intended for external callers.
+     *
+     * @param index Zero-based index of the double-clicked tile in the current `items` array.
+     */
     onItemDoubleClick(index: number): void;
-    contextMenuHandler(event: MouseEvent, index: number): void;
-    executeAction(t: InnerTileData, a: Action, evt: Event): void;
-    selectById(ids: string[]): void;
-    multiSelect(index: number[]): void;
-    select(index: number): void;
-    onQueryResult(e: {
+    /**
+     * Handles the query result emitted by the inner `QueryListComponent`.
+     *
+     * Marks the component as having executed at least one search (`searchExecuted`),
+     * updates the `items` signal with the freshly mapped `TileData` view models, and
+     * re-emits the raw result via `queryResult` so the parent can update counters or
+     * analytics without a separate query.
+     *
+     * Called from the template via `(queryResult)`. Not intended for external callers.
+     *
+     * @param result The search result object containing `totalCount` and `items`.
+     */
+    onQueryResult(result: {
         totalCount: number;
         items: SearchResultItem[];
     }): void;
+    /**
+     * Handles the committed selection emitted by the inner list.
+     *
+     * For a single-item selection the full `#select()` path is taken so that `itemSelect`
+     * is also emitted. For multi-item selections only `#updateSelectionState()` runs to
+     * keep `selectionChange` and the internal state in sync without the single-item emit.
+     *
+     * Called from the template via `(itemSelect)` on `yuv-query-list`.
+     * Not intended for external callers.
+     *
+     * @param sel Array of zero-based indices representing the new selection.
+     */
     onListItemsSelect(sel: number[]): void;
+    /**
+     * Handles live drag-selection changes forwarded from the inner `QueryListComponent`.
+     *
+     * Fires continuously while the user drags across tiles, updating the selection state
+     * in real time so the visual highlight tracks the gesture. Does not emit `itemSelect`
+     * (that fires only on the final committed selection via `onListItemsSelect`).
+     *
+     * Called from the template via `(dragSelectChange)`. Not intended for external callers.
+     *
+     * @param sel Current array of zero-based indices covered by the drag gesture.
+     */
     onDragSelectChange(sel: number[]): void;
+    /**
+     * Transformer function passed to the inner `QueryListComponent`.
+     *
+     * Maps raw `SearchResultItem[]` to the `InnerTileData` view model by:
+     * 1. Storing the raw items in `#rawResultItems` so `applyFlavor()` can re-map them
+     *    without a new server request.
+     * 2. Calling `#mapToTileData()` to resolve `ObjectConfig` fields (title, icon, …).
+     * 3. Resolving each tile's action IDs to full `Action` objects via `ActionsService`,
+     *    filtering out any IDs that are not registered.
+     *
+     * Re-runs automatically whenever the query result or the `ObjectConfigRecord` changes
+     * (the latter is triggered by calling `list().runTransformerAgain()` from
+     * `#getObjectConfig()`).
+     */
+    transformer: (res: SearchResultItem[]) => InnerTileData[];
+    /**
+     * Handles a right-click (contextmenu) event on a tile.
+     *
+     * Suppresses the browser's native context menu. If the clicked tile is not already
+     * part of the selection, it is selected first. After a short delay (to allow the
+     * selection state to propagate), `ctxMenu` is emitted with the originating event and
+     * the current selection so the parent can position and populate a custom menu.
+     *
+     * The delay is intentional: it gives Angular change detection a tick to apply the
+     * selection update before the parent reads `selection()` in the `ctxMenu` handler.
+     *
+     * No-ops when `disableCustomContextMenu` is `true`.
+     *
+     * Called from the template via `(contextmenu)` on each tile. Not intended for
+     * external callers.
+     *
+     * @param event The originating mouse event (used to suppress default and for positioning).
+     * @param index Zero-based index of the right-clicked tile.
+     */
+    contextMenuHandler(event: MouseEvent, index: number): void;
+    /**
+     * Executes a tile inline action against the appropriate set of DMS objects.
+     *
+     * Resolves the target objects from the DMS service: if the tile whose action button
+     * was clicked is part of the current selection, the action runs against all selected
+     * objects (batch action); otherwise it runs against only that single tile's object.
+     *
+     * Suppresses the click event to prevent the tile's own selection handler from firing.
+     * Called from the template via the tile action buttons. Not intended for external callers.
+     *
+     * @param tileData The tile whose action button was clicked.
+     * @param action   The resolved `Action` to execute.
+     * @param event    The originating click event (stopped to prevent tile selection).
+     */
+    executeAction(tileData: InnerTileData, action: Action, event: Event): void;
+    /**
+     * Selects tiles by their object IDs.
+     *
+     * Looks up each ID in the current `items` array and selects the matching indices
+     * in the inner list. If the list is still loading when this is called, the IDs are
+     * stored and applied automatically once the query completes (via `#preselectEffect`).
+     *
+     * IDs not found in the current result set are silently ignored. The first found item
+     * also receives keyboard focus via `setActiveItem()`.
+     *
+     * @param ids Array of object IDs (`system:objectId`) to select.
+     */
+    selectById(ids: string[]): void;
+    /**
+     * Programmatically replaces the entire selection with the given indices.
+     *
+     * Only effective when `multiselect` is `true`. Delegates to the inner
+     * `QueryListComponent`. Out-of-range indices are silently discarded.
+     *
+     * @param index Array of zero-based item indices to select.
+     */
+    multiSelect(index: number[]): void;
+    /**
+     * Selects the tile at the given zero-based index.
+     *
+     * Delegates to the inner `QueryListComponent`. Clamps the index to the valid range.
+     * Use `selectById()` when you have object IDs rather than positional indices.
+     *
+     * @param index Zero-based index of the tile to select.
+     */
+    select(index: number): void;
+    /**
+     * Re-executes the current query without changing the page or query parameters.
+     *
+     * If pagination is active, re-fetches the same page. Use this to reflect server-side
+     * changes (e.g. after a create/delete operation) without navigating away.
+     */
     refresh(): void;
+    /**
+     * Prepends `DmsObject` instances to the top of the tile list as temporary drop-in items.
+     *
+     * The objects are mapped through the same `ObjectConfig` resolution pipeline as regular
+     * query results, including action resolution. The existing selection is shifted so that
+     * currently selected tiles remain selected after the prepend.
+     *
+     * Use this for optimistic UI: show newly created or pasted objects immediately before
+     * the server index reflects them in the query results.
+     *
+     * Drop-in items are cleared automatically when the user navigates to a different page.
+     *
+     * @param objects `DmsObject` instances to prepend to the visible list.
+     */
     dropItems(objects: DmsObject[]): void;
+    /**
+     * Toggles an `ObjectFlavor` on or off and re-maps the current result set.
+     *
+     * If the given flavor is already the active `appliedFlavor`, it is cleared (toggle
+     * off). Otherwise the flavor is applied and all tiles whose `DmsObject.sots` includes
+     * `flavor.sot` are re-rendered using the config entry for `flavor.id`.
+     *
+     * Re-mapping runs against the last raw `SearchResultItem[]` (`#rawResultItems`) so
+     * no server round-trip is needed. Called automatically by `#flavorEffect` when the
+     * `flavor` input changes.
+     *
+     * @param flavor The `ObjectFlavor` to apply or remove.
+     */
     applyFlavor(flavor: ObjectFlavor): void;
     /**
-     * Updates an item in the list at the specified index with the provided value.
+     * Applies per-index optimistic overrides to the displayed tile data.
+     *
+     * Delegates to the inner `QueryListComponent.updateListItems()`. Each entry patches
+     * the tile at the given `index` with a new `TileData` value. Overrides accumulate
+     * until the user navigates to a different page, at which point the fresh server
+     * response replaces all local data.
      *
-     * Use this method for optimistic updates of list items. The updates be removed
-     * when the user navigates to another search result page.
+     * For DMS-object-based updates, prefer `updateTileList()` which resolves indices
+     * from object IDs automatically.
      *
-     * @param index Index of the item to update.
-     * @param value The new value for the item.
+     * @param updates Array of `{ index, value }` pairs describing which tiles to patch.
      */
     updateListItems(updates: {
         index: number;
         value: TileData;
     }[]): void;
     /**
-     * Updates the tile list with the provided DmsObjects. Only tiles that are
-     * already present in the list will be updated. The update is based on
-     * the object ID and will be gone when the user navigates to another search
-     * result page. Use this method for optimistic updates.
-     * @param listItems The DmsObjects to update the tiles with.
+     * Optimistically updates tiles in the list that correspond to the given `DmsObject` instances.
+     *
+     * For each provided object, finds its matching tile by `id` in the current `items`
+     * array, re-maps it through `#mapToTileData()` to get a fresh `TileData` view model,
+     * and applies it via `updateListItems()`. Tiles not currently visible in the list are
+     * silently skipped.
+     *
+     * This is the preferred way to reflect server-confirmed changes (e.g. rename, metadata
+     * edit) without issuing a full query refresh. Updates are scoped to the current page
+     * and are discarded on the next page navigation.
+     *
+     * @param listItems Updated `DmsObject` instances to apply to the list.
      */
     updateTileList(listItems: DmsObject[]): void;
     /**
-     * Clears the current selection.
-     * @param silent If true, the selectionChange event will not be emitted.
+     * Clears the current selection and resets all internal selection state.
+     *
+     * Resets `_selection`, `_lastSelection`, the `selection` signal, and `selectedTile`
+     * to empty. Also delegates to the inner list's `clear()` to sync the visual state.
+     * If the selection is already empty, the method is a no-op.
+     *
+     * @param silent When `true`, skips emitting `selectionChange`. Use this when the
+     *               parent needs to reset state programmatically without triggering
+     *               downstream reactions.
      */
     clearSelection(silent?: boolean): void;
     /**
-     * Selects the next item in the list. If the last item is already selected,
-     * it wraps around to the first item. Does nothing if no item is currently selected.
+     * Advances the selection to the next tile in the list.
+     *
+     * Moves from the last selected index forward by one. Wraps around to index 0
+     * when the last tile is currently selected. Does nothing if no tile is selected
+     * (`_lastSelection` is `undefined`).
+     *
+     * Useful for implementing keyboard-driven "next item" navigation from a parent
+     * detail panel without giving focus back to the list.
      */
     selectNext(): void;
     /**
-     * Selects the previous item in the list. If the first item is already selected,
-     * it wraps around to the last item. Does nothing if no item is currently selected.
+     * Moves the selection to the previous tile in the list.
+     *
+     * Moves from the last selected index backward by one. Wraps around to the last tile
+     * when index 0 is currently selected. Does nothing if no tile is selected
+     * (`_lastSelection` is `undefined`).
+     *
+     * Useful for implementing keyboard-driven "previous item" navigation from a parent
+     * detail panel without giving focus back to the list.
      */
     selectPrev(): void;
-    menuItemClicked(t: TileData, event: Event): void;
+    /**
+     * Handles a click on a projected `TileActionsMenuComponent` menu item.
+     *
+     * If the tile that owns the clicked menu item is part of the current selection,
+     * the click event is stopped from propagating so the tile's own `(click)` handler
+     * does not deselect other tiles. If the tile is not selected, the event is allowed
+     * to propagate normally so the tile gets selected as a side effect.
+     *
+     * Called from the template via the `TileActionsMenuComponent` item click binding.
+     * Not intended for external callers.
+     *
+     * @param tileData The tile that owns the clicked menu item.
+     * @param event    The originating click event.
+     */
+    menuItemClicked(tileData: TileData, event: Event): void;
     private _selectionToTileData;
-    ngOnInit(): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<TileListComponent, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<TileListComponent, "yuv-tile-list", never, { "bucket": { "alias": "bucket"; "required": false; "isSignal": true; }; "pageSize": { "alias": "pageSize"; "required": false; "isSignal": true; }; "multiselect": { "alias": "multiselect"; "required": false; "isSignal": true; }; "dense": { "alias": "dense"; "required": false; "isSignal": true; }; "options": { "alias": "options"; "required": false; "isSignal": true; }; "flavor": { "alias": "flavor"; "required": false; "isSignal": true; }; "query": { "alias": "query"; "required": false; "isSignal": true; }; "preselect": { "alias": "preselect"; "required": false; "isSignal": true; }; "highlights": { "alias": "highlights"; "required": false; "isSignal": true; }; "preventChangeUntil": { "alias": "preventChangeUntil"; "required": false; "isSignal": true; }; "autoSelect": { "alias": "autoSelect"; "required": false; "isSignal": true; }; "disableCustomContextMenu": { "alias": "disableCustomContextMenu"; "required": false; "isSignal": true; }; }, { "itemSelect": "itemSelect"; "tileCopy": "tileCopy"; "tileCut": "tileCut"; "busy": "busy"; "queryResult": "queryResult"; "selectionChange": "selectionChange"; "itemDblClick": "itemDblClick"; "ctxMenu": "ctxMenu"; }, ["menuComponent", "emptyContent"], ["yuv-tile-actions-menu, [yuv-tile-actions-menu]", "*"], true, never>;
 }