@yuuvis/client-framework 2.18.0 → 2.20.0

package/fesm2022/yuuvis-client-framework-query-list.mjs

@@ -1,5 +1,5 @@
 import * as i0 from '@angular/core';
-import { inject, viewChild, contentChild, input, output, signal, computed, effect, untracked, HostBinding, Component, NgModule } from '@angular/core';
+import { inject, signal, viewChild, contentChild, input, output, computed, untracked, effect, ChangeDetectionStrategy, Component, NgModule } from '@angular/core';
 import { coerceBooleanProperty } from '@angular/cdk/coercion';
 import * as i1 from '@angular/common';
 import { CommonModule } from '@angular/common';
@@ -12,186 +12,441 @@ import { YuvListModule } from '@yuuvis/client-framework/list';
 import { DeviceService } from '@yuuvis/material';
 
 /**
- * Component to display a list of items based on a search query.
- * It will execute the query and render the results using the provided item template.
+ * Query-driven list component that executes a search query and renders the results
+ * using a consumer-provided item template.
  *
- * The component supports pagination, multi-selection, and drag selection.
+ * The component is a thin orchestration layer on top of `yuv-list`: it handles the
+ * full query lifecycle (executing, paginating, refreshing), exposes a typed result
+ * set via the optional `transformer` input, and delegates all keyboard navigation,
+ * selection, and accessibility concerns to the inner `ListComponent`.
  *
- * If you don't provide a transformer function, the raw SearchResultItem objects will be
- * used as items and passed to the template. The transformer function allows you to map
- * the SearchResultItem objects to a custom format before rendering.
+ * **Key Features:**
+ * - Accepts a `SearchQuery` object or a raw CMIS query string
+ * - Optional `transformer` function maps raw `SearchResultItem[]` to any custom type `T`
+ * - Built-in server-side pagination via Angular Material `mat-paginator`
+ * - Multi-selection with mouse drag (`DragSelectDirective`) and keyboard modifiers
+ * - "Drop-in" items prepended to the result set for optimistic UI updates
+ * - Busy state signal for loading indicators
+ * - Exposes a slim imperative API (`select`, `clear`, `refresh`, `goToPage`, …)
+ *   so parents can drive the list programmatically
  *
- * Example usage:
+ * **Content Projection Slots:**
+ * - `#yuvQueryListItem` — required; `ng-template` used to render each result item.
+ *   Receives the (optionally transformed) item as `$implicit`.
+ * - `#yuvQueryListEmpty` — optional; `ng-template` shown when the result set is empty.
+ *
+ * **Basic usage:**
  * ```html
- * <yuv-query-list [transformer]="transformResult" [query]="query" (itemSelect)="onItemSelect($event)">
-    
-    <!-- template used to render result item -->
-    <ng-template #yuvQueryListItem let-item>
-      <yuv-list-tile>
-        <ng-template #titleSlot>{{ item.id }}</ng-template>
-        <ng-template #descriptionSlot>{{ item.modified }}</ng-template>
-      </yuv-list-tile>
-    </ng-template>
-
-    <!-- Content to display when the list is empty -->
-    <ng-template #yuvQueryListEmpty>
-      <div>No documents found.</div>
-    </ng-template>
-
-  </yuv-query-list>
+ * <yuv-query-list [query]="query" (itemSelect)="onSelect($event)">
+ *   <ng-template #yuvQueryListItem let-item>
+ *     <span>{{ item.title }}</span>
+ *   </ng-template>
+ * </yuv-query-list>
  * ```
  *
- * ```ts
- * @Component({...})
- * export class TestQueryListComponent {
- *  query = 'SELECT * FROM system:document';
+ * **With transformer and empty state:**
+ * ```html
+ * <yuv-query-list [query]="query" [transformer]="toViewModel" (itemSelect)="onSelect($event)">
+ *   <ng-template #yuvQueryListItem let-item>
+ *     <yuv-list-tile>
+ *       <ng-template #titleSlot>{{ item.title }}</ng-template>
+ *       <ng-template #descriptionSlot>{{ item.modified }}</ng-template>
+ *     </yuv-list-tile>
+ *   </ng-template>
+ *   <ng-template #yuvQueryListEmpty>
+ *     <p>No results found.</p>
+ *   </ng-template>
+ * </yuv-query-list>
+ * ```
  *
- *  transformResult = (items: SearchResultItem[]) =>
- *   items.map((item) => ({
- *     id: item.fields.get(BaseObjectTypeField.OBJECT_ID),
+ * ```ts
+ * toViewModel = (items: SearchResultItem[]) =>
+ *   items.map(item => ({
+ *     title: item.fields.get(BaseObjectTypeField.OBJECT_ID),
  *     modified: item.fields.get(BaseObjectTypeField.MODIFICATION_DATE)
  *   }));
- * } *
  * ```
+ *
+ * @typeParam T The shape of each item after the optional `transformer` is applied.
+ *              Defaults to `any` when no transformer is provided.
  */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 class QueryListComponent {
+    //#region Dependencies
+    #device;
+    #searchService;
+    #items;
+    #dropInItems;
+    #listItemUpdates;
+    //#endregion
     constructor() {
+        //#region Dependencies
         this.#device = inject(DeviceService);
         this.#searchService = inject(SearchService);
+        //#endregion
+        //#region Angular stuff
+        /**
+         * Current pagination state. Set to a `Pagination` object when the last query
+         * result contained multiple pages; `undefined` when all results fit on one page
+         * or no query has been executed yet.
+         *
+         * Drives the `[class.pagination]` host binding so the template can conditionally
+         * render the `mat-paginator` footer.
+         */
+        this.pagination = signal(undefined);
+        /**
+         * Reference to the inner `ListComponent` instance.
+         *
+         * Used internally to delegate imperative operations (select, clear, focus, …).
+         * Can also be accessed from the parent via a `@ViewChild` on `yuv-query-list` if
+         * fine-grained control over the inner list is needed, though the public API methods
+         * on this component are preferred.
+         */
         this.list = viewChild.required('list');
+        /**
+         * Reference to the `#yuvQueryListItem` `ng-template` projected by the consumer.
+         *
+         * This template is used to render each individual item in the list. The template
+         * receives the (optionally transformed) item as the `$implicit` context variable:
+         * ```html
+         * <ng-template #yuvQueryListItem let-item>{{ item.title }}</ng-template>
+         * ```
+         */
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         this.itemTemplate = contentChild('yuvQueryListItem');
+        /**
+         * Reference to the optional `#yuvQueryListEmpty` `ng-template` projected by the consumer.
+         *
+         * When provided, this template is rendered in place of the list whenever the query
+         * returns zero items. If omitted, nothing is shown for the empty state.
+         * ```html
+         * <ng-template #yuvQueryListEmpty>
+         *   <p>No results found.</p>
+         * </ng-template>
+         * ```
+         */
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         this.emptyTemplate = contentChild('yuvQueryListEmpty');
-        this.isTouchDevice = this.#device.isTouchEnabled;
         /**
-         * The query to execute (SearchQuery object or CMIS query string).
+         * The search query to execute.
+         *
+         * Accepts either a structured `SearchQuery` object (field filters, sort orders, etc.)
+         * or a raw CMIS query string. The query is re-executed reactively every time this
+         * input changes. Set to `null` or `undefined` to clear the list without triggering
+         * a new request.
          */
         this.query = input();
         /**
-         * Optional property name to use as unique identifier for items.
-         * If not provided, the index of the item in the result set will be used.
+         * Property name on the (transformed) item to use as a stable unique identifier.
+         *
+         * When provided, the template renderer uses this property for `@for` tracking instead
+         * of the item's position index, which preserves DOM nodes and component state when the
+         * list is refreshed with partially overlapping results.
+         *
+         * If omitted, the zero-based index is used as the tracking key.
+         *
+         * @default null
          */
         this.idProperty = input(null);
         /**
-         * Optional transformer function to map SearchResultItem to a custom format.
+         * Optional mapping function applied to the raw `SearchResultItem[]` returned by the
+         * search service before the results are rendered.
+         *
+         * Use this to project only the fields your template needs, compute derived properties,
+         * or convert dates/enums to display-friendly values. The generic type parameter `T`
+         * of the component is inferred from the return type of this function.
+         *
+         * If omitted, raw `SearchResultItem` objects are passed to the item template as-is.
+         *
+         * @example
+         * ```ts
+         * transformer = (items: SearchResultItem[]) =>
+         *   items.map(item => ({
+         *     id: item.fields.get(BaseObjectTypeField.OBJECT_ID) as string,
+         *     title: item.fields.get('cm:name') as string
+         *   }));
+         * ```
          */
         this.transformer = input();
         /**
-         * Function that returns `true` if selection changes should be prevented.
-         * This can be used to temporarily block selection changes, e.g. while
-         * there is a pending change inside another component that refers to the
-         * current selection.
+         * Guard function that temporarily blocks all selection changes.
+         *
+         * Forwarded directly to the inner `ListComponent`. As long as the returned predicate
+         * evaluates to `true`, any attempt to change the selection — via click, keyboard, or
+         * the programmatic API — is silently ignored. Useful when the parent has unsaved
+         * changes tied to the current selection and needs to prevent the user from
+         * accidentally navigating away.
+         *
+         * @default () => false  (never prevents)
          */
         this.preventChangeUntil = input(() => false);
         /**
-         * 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.
+         *
+         * Forwarded to the inner `ListComponent`. The selection logic runs once after the
+         * initial query result is displayed and follows this priority:
+         * 1. The first non-disabled item that already carries the `selected` attribute.
+         * 2. If no such item exists and `autoSelect` is `true`, the item at index 0.
+         *
+         * Accepts any truthy string in addition to a real boolean so it can be set as a
+         * plain HTML attribute: `<yuv-query-list autoSelect>`.
+         *
          * @default false
          */
-        this.autoSelect = input(false, { transform: (value) => coerceBooleanProperty(value) });
+        this.autoSelect = input(false, {
+            transform: (value) => coerceBooleanProperty(value)
+        });
         /**
-         * Event emitted when items are selected. Emits an array of selected item indices.
+         * Emits the current selection as an array of zero-based item indices whenever
+         * the selection changes — via click, drag, keyboard, or programmatic API calls.
+         *
+         * An empty array signals that the selection has been cleared.
          */
         this.itemSelect = output();
         /**
-         * Event emitted during drag selection, providing the current selection of item indices.
+         * Emits the live selection indices while the user is actively dragging to select.
+         *
+         * Fires continuously during a drag operation (before the drag is released), allowing
+         * the parent to show a live preview of what will be selected. Once the drag ends,
+         * `itemSelect` fires with the final committed selection.
          */
         this.dragSelectChange = output();
         /**
-         * Event emitted when an item is double-clicked, providing the index of the item.
+         * Emits the zero-based index of an item when it is double-clicked.
+         *
+         * The inner list operates with `selfHandleClick` mode when double-click is active,
+         * so single clicks do not immediately trigger `itemSelect`. The parent should listen
+         * to both `itemSelect` (for single-click selection) and this event (for double-click
+         * actions like opening a detail view).
          */
         this.itemDoubleClick = output();
         /**
-         * Event emitted when the query result is available, providing total count of items.
+         * Emits once per query execution when the search result arrives, providing the total
+         * count of matching items and the raw result page.
+         *
+         * Use this to update external counters, breadcrumbs, or analytics — without having to
+         * execute a separate count query. Note that `totalCount` reflects the server-side total,
+         * not just the number of items on the current page.
          */
         this.queryResult = output();
-        this.#items = signal([]);
-        this.#dropInItems = signal([]);
-        this.dropInSize = computed(() => this.#dropInItems().length);
-        /**
-         * The list of result items after applying the optional transformer.
-         */
-        this.resultItems = computed(() => {
-            const items = this.#items();
-            const updates = this.#listItemUpdates();
-            const transformer = this.transformer();
-            const transformedResult = transformer ? transformer(items) : items;
-            const result = [...this.#dropInItems(), ...transformedResult];
-            // apply updates to transformed result
-            Object.keys(updates).forEach((index) => {
-                result[Number(index)] = updates[Number(index)];
-            });
-            return result;
-        });
-        this.#listItemUpdates = signal({});
         /**
-         * Number of items to fetch per page when executing the query.
+         * Number of items to request per page from the search service.
+         *
+         * Controls the `size` parameter of each search request. When the total result count
+         * exceeds this value, pagination controls are shown and the user can navigate between
+         * pages via `changePage()` / `goToPage()`.
+         *
          * @default SearchService.DEFAULT_QUERY_SIZE
          */
         this.pageSize = input(SearchService.DEFAULT_QUERY_SIZE);
         /**
-         * Enables or disables drag selection of items. If `true`, users can select multiple items by dragging the mouse.
+         * Enables mouse drag-to-select on list items.
+         *
+         * When `true` and `multiselect` is also `true`, the user can click and drag across
+         * items to select a range without holding Shift. Powered by `DragSelectDirective`.
+         * Automatically disabled on touch devices regardless of this input value.
+         *
          * @default true
          */
         this.enableDragSelect = input(true);
         /**
-         * Sets up the ability to select multiple tiles
+         * Enables multi-selection mode.
+         *
+         * When `true`, the user can hold **Shift** or **Ctrl** to extend or toggle the
+         * selection, and drag-to-select becomes available (if `enableDragSelect` is also
+         * `true`). Forwarded to the inner `ListComponent`.
+         *
          * @default false
          */
         this.multiselect = input(false);
         /**
-         * If `true`, the component will handle selection itself. This means that
-         * the parent component will be responsible for styling the selected and
-         * focused items. If `false`, the component will take care of visualizing
-         * the selection and focus states.
+         * Delegates visual selection and focus state rendering to the parent component.
+         *
+         * When `false` (default), `yuv-list` applies CSS classes for selected and active
+         * states automatically. When `true`, those signals are still updated but the host
+         * receives the `self-handle-selection` CSS class, allowing the parent to apply
+         * its own visual treatment. Forwarded to the inner `ListComponent`.
+         *
          * @default false
          */
         this.selfHandleSelection = input(false);
         /**
-         * Indicator signal whether a query is currently being executed.
-         * You could use this to show a loading indicator in the UI.
+         * Whether to include permission information in CMIS search results.
+         * When `true`, the third parameter of `searchCmis()` is set,
+         * causing the backend to return permission data alongside each item.
+         *
+         * @default false
+         */
+        this.includePermissions = input(false);
+        //#endregion
+        //#region Properties
+        /**
+         * Whether the current device has touch input enabled.
+         *
+         * Sourced from `DeviceService`. Used in the template to conditionally disable
+         * drag-to-select, which is not suitable for touch interactions.
+         */
+        this.isTouchDevice = this.#device.isTouchEnabled;
+        /**
+         * Number of drop-in items currently prepended to the result list.
+         *
+         * Derived from the internal `#dropInItems` signal. Exposed publicly so the template
+         * and parent components can easily check whether any temporary items are present
+         * (e.g. to show a visual indicator or adjust layout) without accessing internal state.
+         */
+        this.dropInSize = computed(() => this.#dropInItems().length);
+        /**
+         * The final list of items rendered by the template.
+         *
+         * Computed from three sources, merged in this order:
+         * 1. **Drop-in items** (`#dropInItems`) — temporary items prepended to the list,
+         *    e.g. newly created objects that should appear before they match the query.
+         * 2. **Transformed query results** — raw `SearchResultItem[]` passed through the
+         *    optional `transformer` function (or cast directly to `T[]` if none is provided).
+         * 3. **Optimistic updates** (`#listItemUpdates`) — per-index overrides applied on top
+         *    of the merged list, allowing individual items to be patched without re-fetching.
+         *
+         * Re-evaluates automatically whenever any of the three sources change.
+         */
+        this.resultItems = computed(() => {
+            const items = this.#items();
+            const updates = this.#listItemUpdates();
+            const transformer = this.transformer();
+            const transformedResult = transformer ? transformer(items) : items;
+            const dropIns = this.#dropInItems();
+            let merged;
+            const idProp = this.idProperty();
+            if (dropIns.length > 0 && idProp) {
+                // Deduplicate: filter out server results that already appear as drop-in items
+                const dropInIds = new Set(dropIns.map((item) => item[idProp]));
+                const filtered = transformedResult.filter((item) => !dropInIds.has(item[idProp]));
+                merged = [...dropIns, ...filtered];
+            }
+            else {
+                merged = [...dropIns, ...transformedResult];
+            }
+            // apply updates to transformed result
+            Object.keys(updates).forEach((index) => {
+                merged[Number(index)] = updates[Number(index)];
+            });
+            return merged;
+        });
+        /**
+         * Indicates whether a search request is currently in flight.
+         *
+         * Set to `true` immediately before a query or page request is dispatched to the
+         * search service, and back to `false` once the response (or error) arrives.
+         * Bind this to a loading indicator or `BusyOverlayDirective` in the parent template:
+         * ```html
+         * <yuv-query-list #qList ...>...</yuv-query-list>
+         * <yuv-busy-overlay [active]="qList.busy()" />
+         * ```
          */
         this.busy = signal(false);
-        this.#executeQueryEffect = effect(() => {
+        this.#items = signal([]);
+        this.#dropInItems = signal([]);
+        this.#listItemUpdates = signal({});
+        //#endregion
+        //#region Effects
+        this.#executeQueryEffect = () => {
             // execute the query each time it changes
             const query = this.query();
             if (query)
                 untracked(() => {
                     this.#executeQuery(query || null);
                 });
-        });
+        };
+        effect(this.#executeQueryEffect);
     }
-    #device;
-    #searchService;
-    #items;
-    #dropInItems;
-    #listItemUpdates;
-    #executeQueryEffect;
+    //#region UI Methods
+    /** Resolves the tracking key for a result item in the `@for` loop. */
+    trackItem(item, index) {
+        const prop = this.idProperty();
+        return prop ? item[prop] : index;
+    }
+    /**
+     * Handles a single click on a list item.
+     *
+     * Forwards the click to the inner `ListComponent` with the correct Shift/Ctrl modifier
+     * flags so range- and toggle-selection work correctly. Also transfers DOM focus to the
+     * list host so subsequent keyboard navigation works without an additional Tab press.
+     *
+     * Called from the template via `(click)` on each item wrapper. Not intended for
+     * external callers — use `select()` instead.
+     *
+     * @param idx   Zero-based index of the clicked item.
+     * @param event The originating mouse event (provides `shiftKey` and `ctrlKey` flags).
+     */
     onItemClick(idx, event) {
         this.list().select(idx, event.shiftKey, event.ctrlKey);
         this.list().focus();
     }
+    /**
+     * Handles a double-click on a list item.
+     *
+     * Emits the `itemDoubleClick` output with the item's index. The parent can use this
+     * to trigger a secondary action (e.g. opening a detail panel or navigating to a route)
+     * that is distinct from the primary single-click selection.
+     *
+     * Called from the template via `ClickDoubleDirective`. Not intended for external callers.
+     *
+     * @param idx   Zero-based index of the double-clicked item.
+     * @param event The originating mouse event (unused, kept for directive compatibility).
+     */
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
     onItemDoubleClick(idx, event) {
         this.itemDoubleClick.emit(idx);
     }
+    /**
+     * Handles intermediate drag-selection changes from `DragSelectDirective`.
+     *
+     * Fires continuously while the user is dragging across items. Updates the inner list's
+     * multi-selection state in real time so items are highlighted as the drag progresses,
+     * and also emits `dragSelectChange` so the parent can show a live preview.
+     *
+     * Called from the template via `(dragSelectChange)` on the drag-select host.
+     * Not intended for external callers.
+     *
+     * @param sel Current array of zero-based indices covered by the drag gesture.
+     */
     onDragSelectChange(sel) {
         this.list().multiSelect(sel);
         this.dragSelectChange.emit(sel);
     }
+    /**
+     * Handles the final committed drag-selection from `DragSelectDirective`.
+     *
+     * Called when the user releases the mouse after a drag-to-select gesture. Transfers
+     * DOM focus to the list (so keyboard navigation works immediately after) and emits
+     * the final selection via `itemSelect`.
+     *
+     * Called from the template via `(dragSelect)` on the drag-select host.
+     * Not intended for external callers.
+     *
+     * @param sel Final array of zero-based indices selected by the drag gesture.
+     */
     onDragSelect(sel) {
         this.list().focus();
         this.itemSelect.emit(sel);
     }
+    //#endregion
+    //#region Public methods
     /**
-     * Updates an item in the list at the specified index with the provided value.
-     * The value should match the type returned by the transformer function, if provided.
-     * If you did not provide a transformer, the value should be of type SearchResultItem.
+     * Applies optimistic per-item overrides on top of the current query result.
+     *
+     * Each entry in the `updates` array patches the item at the given `index` with
+     * the provided `value`. The value type must match `T` — i.e. the shape produced
+     * by the `transformer` function, or `SearchResultItem` if no transformer is used.
+     *
+     * Overrides accumulate: calling this method multiple times merges the new entries
+     * with any previously applied ones. All overrides are automatically discarded when
+     * the user navigates to a different page (see `goToPage()`), since a fresh server
+     * response replaces the local data.
      *
-     * Use this method for optimistic updates of list items. The updates be removed
-     * when the user navigates to another search result page.
+     * **Use case:** apply instant visual feedback after a user action (rename, status
+     * change, etc.) without waiting for a full query refresh.
      *
-     * @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 items to patch.
      */
     updateListItems(updates) {
         const updatesRecord = updates.reduce((acc, curr) => {
@@ -203,20 +458,25 @@ class QueryListComponent {
         this.#listItemUpdates.set({ ...this.#listItemUpdates(), ...updatesRecord });
     }
     /**
-     * Optional array of items to be shown in addition to the query results.
-     * These items will be prepended to the list of query results and visually
-     * highlighted. They will also be affected by selection and drag-selection.
+     * Prepends a set of temporary items to the top of the result list.
      *
-     * Use this input to "drop in" items, for example when creating features
-     * like pasting items into a list where they would otherwise not appear due
-     * to the current query/filter.
+     * Drop-in items appear before all query results and are visually distinguished
+     * by the template (e.g. a highlighted background). They participate in selection
+     * and drag-to-select exactly like regular items.
      *
-     * Changing the page of the query will remove the drop-in items again, as
-     * they are meant to be temporary.
+     * The existing selection indices are automatically shifted by `items.length` so that
+     * the currently selected query-result items remain selected after the prepend.
      *
-     * @param items The items to drop into the list.
-     * @param scrollTo If `true`, the list will scroll to the top after dropping
-     * in the items. Default is `true`.
+     * **Typical use case:** when the user pastes or creates an object that does not yet
+     * appear in the current query (e.g. because the index has not been updated), drop it
+     * in temporarily so the user sees it immediately without a full refresh.
+     *
+     * Drop-in items are cleared automatically when the user navigates to a different page.
+     * Call `dropItems([])` to remove them programmatically.
+     *
+     * @param items    Items to prepend. Must be of type `T` (same as query result items).
+     * @param scrollTo Whether to smooth-scroll the list back to the top after prepending.
+     *                 Defaults to `true` so the newly dropped items are immediately visible.
      */
     dropItems(items, scrollTo = true) {
         this.#dropInItems.set(items);
@@ -226,59 +486,124 @@ class QueryListComponent {
         }
     }
     /**
-     * Selects multiple items in the list.
+     * Programmatically replaces the entire selection with the given indices.
+     *
+     * Only effective when `multiselect` is `true`. Out-of-range indices are silently
+     * discarded. The resulting selection is sorted ascending before being applied.
+     *
+     * Use this when the parent needs to restore a previously saved multi-selection
+     * state, e.g. after navigation or component re-initialization.
+     *
+     * @param index Array of zero-based item indices to select.
      */
     multiSelect(index) {
         this.list().multiSelect(index);
     }
+    /**
+     * Selects the item at the given zero-based index.
+     *
+     * Delegates to the inner `ListComponent`. The `preventChangeUntil` guard and
+     * `disableSelection` state are respected. Clamps the index to the valid range.
+     *
+     * @param index Zero-based index of the item to select.
+     */
     select(index) {
         this.list().select(index);
     }
+    /**
+     * Moves keyboard focus to the item at the given index and selects it.
+     *
+     * Combines focus management and selection in one call, and transfers DOM focus
+     * to the list host. Use this when the parent wants to programmatically drive
+     * both the visual focus indicator and the selection simultaneously.
+     *
+     * @param index Zero-based index of the item to activate.
+     */
     setActiveItem(index) {
         this.list().setActiveItem(index);
     }
     /**
-     * Clear the current selection.
-     * @param silent If `true`, the `itemSelect` event will not be emitted.
+     * Clears the current selection and resets the active keyboard-focus index.
+     *
+     * If the selection is already empty, the method is a no-op. The `preventChangeUntil`
+     * guard is respected — if the guard returns `true`, the clear is blocked.
+     *
+     * @param silent When `true`, skips emitting `itemSelect` after clearing. Use this
+     *               when the parent needs to reset state programmatically without
+     *               triggering downstream reactions.
      */
     clear(silent = false) {
         this.list().clear(silent);
     }
     /**
-     * Refreshes the list by re-executing the current query/page.
+     * Re-executes the current query without changing the page or query parameters.
+     *
+     * If pagination is active, re-fetches the same page the user is currently on.
+     * If no pagination is active, re-runs the original query from scratch.
+     *
+     * Use this to reflect server-side changes (e.g. after a create/delete operation)
+     * without navigating away from the current view.
      */
     refresh() {
         const query = this.query();
         if (query) {
-            if (this.pagination) {
-                this.goToPage(this.pagination.page);
+            if (this.pagination()) {
+                this.goToPage(this.pagination().page);
             }
             else
                 this.#executeQuery(query || null);
         }
     }
+    /**
+     * Forces the `transformer` function to be re-applied to the current result set.
+     *
+     * Normally the transformer runs automatically whenever the underlying `#items`
+     * signal changes. Use this method when the transformer itself has external
+     * dependencies that changed (e.g. a locale or display-format setting) but the
+     * raw search result did not — triggering a re-evaluation by creating a new array
+     * reference for `#items` without fetching from the server again.
+     */
     runTransformerAgain() {
         this.#items.set([...this.#items()]);
     }
-    changePage(pe) {
-        this.goToPage(pe.pageIndex + 1);
+    /**
+     * Handles a page-change event emitted by the `mat-paginator`.
+     *
+     * Converts the zero-based `pageEvent.pageIndex` to the one-based page number
+     * expected by `goToPage()` and delegates the request.
+     *
+     * Bound to `(page)` on the `mat-paginator` in the template.
+     *
+     * @param pageEvent The pagination event emitted by `MatPaginatorModule`.
+     */
+    changePage(pageEvent) {
+        this.#dropInItems.set([]);
+        this.goToPage(pageEvent.pageIndex + 1);
     }
+    /**
+     * Fetches and displays the given page of the current query result.
+     *
+     * Sets `busy` to `true` for the duration of the request. On success, updates
+     * the pagination state, clears all optimistic overrides (they are page-scoped),
+     * and replaces `#items` with the new page's results.
+     *
+     * Also used internally by `refresh()` to reload the currently active page.
+     *
+     * @param page One-based page number to navigate to.
+     */
     goToPage(page) {
         const query = this.query();
         if (!query)
             return;
         this.busy.set(true);
         this.#searchService
-            .getPage(query, page, this.pageSize())
+            .getPage(query, page, this.pageSize(), this.includePermissions())
             .subscribe({
             next: (res) => {
                 this.#setupPagination(res);
-                // changing the page, reset any list item updates as they should only be used for
-                // optimistic updates on the current page. Moving between pages would trigger a new
-                // query anyway (will get the recent data).
                 this.#listItemUpdates.set({});
-                this.#dropInItems.set([]);
                 this.#items.set(res.items);
+                this.queryResult.emit({ totalCount: res.totalNumItems, items: res.items });
                 this.busy.set(false);
             },
             error: (err) => {
@@ -288,19 +613,23 @@ class QueryListComponent {
             }
         });
     }
+    //#endregion
+    //#region Utilities
     /**
      * Executes a search query.
-     * @param query The search query to execute. This may be a SearchQuery object or a string. If it's a string, it is supposed to
+     * @param query The search query to execute.
+     * This may be a SearchQuery object or a string. If it's a string, it is supposed to
      * be a CMIS query statement.
      */
     #executeQuery(query) {
         if (query && !this.busy()) {
             this.busy.set(true);
             (typeof query === 'string'
-                ? this.#searchService.searchCmis(query, this.pageSize())
+                ? this.#searchService.searchCmis(query, this.pageSize(), this.includePermissions())
                 : this.#searchService.search(query)).subscribe({
                 next: (res) => {
                     this.#setupPagination(res);
+                    this.#listItemUpdates.set({});
                     this.#items.set(res.items);
                     this.queryResult.emit({ totalCount: res.totalNumItems, items: res.items });
                     this.busy.set(false);
@@ -313,25 +642,31 @@ class QueryListComponent {
         }
     }
     #setupPagination(searchResult) {
-        this.pagination = undefined;
-        this.pagination = searchResult.paging
+        this.pagination.set(searchResult.paging
             ? {
                 total: searchResult.totalNumItems,
                 pages: searchResult.paging.totalPages,
                 page: searchResult.paging.page
             }
-            : undefined;
+            : undefined);
     }
+    //#endregion
+    //#region Effects
+    #executeQueryEffect;
     static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "19.2.20", ngImport: i0, type: QueryListComponent, deps: [], target: i0.ɵɵFactoryTarget.Component }); }
-    static { this.ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "19.2.20", type: QueryListComponent, isStandalone: true, selector: "yuv-query-list", inputs: { query: { classPropertyName: "query", publicName: "query", isSignal: true, isRequired: false, transformFunction: null }, idProperty: { classPropertyName: "idProperty", publicName: "idProperty", isSignal: true, isRequired: false, transformFunction: null }, transformer: { classPropertyName: "transformer", publicName: "transformer", isSignal: true, isRequired: false, transformFunction: null }, preventChangeUntil: { classPropertyName: "preventChangeUntil", publicName: "preventChangeUntil", isSignal: true, isRequired: false, transformFunction: null }, autoSelect: { classPropertyName: "autoSelect", publicName: "autoSelect", isSignal: true, isRequired: false, transformFunction: null }, pageSize: { classPropertyName: "pageSize", publicName: "pageSize", isSignal: true, isRequired: false, transformFunction: null }, enableDragSelect: { classPropertyName: "enableDragSelect", publicName: "enableDragSelect", isSignal: true, isRequired: false, transformFunction: null }, multiselect: { classPropertyName: "multiselect", publicName: "multiselect", isSignal: true, isRequired: false, transformFunction: null }, selfHandleSelection: { classPropertyName: "selfHandleSelection", publicName: "selfHandleSelection", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { itemSelect: "itemSelect", dragSelectChange: "dragSelectChange", itemDoubleClick: "itemDoubleClick", queryResult: "queryResult" }, host: { properties: { "class.pagination": "this.pagination" } }, queries: [{ propertyName: "itemTemplate", first: true, predicate: ["yuvQueryListItem"], descendants: true, isSignal: true }, { propertyName: "emptyTemplate", first: true, predicate: ["yuvQueryListEmpty"], descendants: true, isSignal: true }], viewQueries: [{ propertyName: "list", first: true, predicate: ["list"], descendants: true, isSignal: true }], ngImport: i0, template: "<yuv-list\n  #list\n  [multiselect]=\"multiselect()\"\n  [autoSelect]=\"autoSelect()\"\n  [preventChangeUntil]=\"preventChangeUntil()\"\n  [selfHandleClick]=\"true\"\n  [selfHandleSelection]=\"selfHandleSelection()\"\n  [yuvDragSelect]=\"{ disabled: !enableDragSelect() || !multiselect() || isTouchDevice }\"\n  (dragSelectChange)=\"onDragSelectChange($event)\"\n  (dragSelect)=\"onDragSelect($event)\"\n  (itemSelect)=\"itemSelect.emit($event)\"\n>\n  @for (i of resultItems(); track idProperty() || $index) {\n    <div yuvListItem yuvDragSelectItem [class.drop-in]=\"$index < dropInSize()\"\n    (click.single)=\"onItemClick($index, $event)\"\n    (click.double)=\"onItemDoubleClick($index, $event)\" >\n      <ng-container *ngTemplateOutlet=\"itemTemplate() || null; context: { $implicit: i, index: $index }\"></ng-container>\n    </div>\n  } @empty {\n    <ng-container *ngTemplateOutlet=\"emptyTemplate() || null\"></ng-container>\n  }\n</yuv-list>\n@if (pagination) {\n  <mat-paginator class=\"paginator\" [length]=\"pagination.total\" [pageSize]=\"pageSize()\" (page)=\"changePage($event)\" hidePageSize> </mat-paginator>\n}\n", styles: [":host{--paging-background: var(--ymt-surface);--drop-in-item-outline: 2px dashed rgb(from var(--ymt-primary) r g b / .9);--drop-in-item-outline-offset: -3px;display:flex;flex-direction:column;max-height:100%}:host [yuvListItem].drop-in{outline:var(--drop-in-item-outline);outline-offset:var(--drop-in-item-outline-offset);overflow:hidden}:host yuv-list{flex:1;overflow-y:auto}:host mat-paginator{flex:0 0 auto;font:inherit;border-block-start:1px solid var(--ymt-outline-variant);background-color:var(--paging-background)}\n"], dependencies: [{ kind: "ngmodule", type: CommonModule }, { kind: "directive", type: i1.NgTemplateOutlet, selector: "[ngTemplateOutlet]", inputs: ["ngTemplateOutletContext", "ngTemplateOutlet", "ngTemplateOutletInjector"] }, { kind: "ngmodule", type: YuvListModule }, { kind: "component", type: i2.ListComponent, selector: "yuv-list", inputs: ["preventChangeUntil", "multiselect", "selfHandleSelection", "selfHandleClick", "autoSelect", "disableSelection"], outputs: ["itemSelect", "itemFocus"] }, { kind: "directive", type: i2.ListItemDirective, selector: "[yuvListItem]", inputs: ["disabled", "active", "selected"] }, { kind: "directive", type: ClickDoubleDirective, selector: "[click.single],[click.double]", inputs: ["debounceTime"], outputs: ["click.double", "click.single"] }, { kind: "directive", type: DragSelectDirective, selector: "[yuvDragSelect]", inputs: ["yuvDragSelect"], outputs: ["dragSelectChange", "dragSelect"] }, { kind: "directive", type: DragSelectItemDirective, selector: "[yuvDragSelectItem]" }, { kind: "ngmodule", type: MatPaginatorModule }, { kind: "component", type: i3.MatPaginator, selector: "mat-paginator", inputs: ["color", "pageIndex", "length", "pageSize", "pageSizeOptions", "hidePageSize", "showFirstLastButtons", "selectConfig", "disabled"], outputs: ["page"], exportAs: ["matPaginator"] }] }); }
+    static { this.ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "19.2.20", type: QueryListComponent, isStandalone: true, selector: "yuv-query-list", inputs: { query: { classPropertyName: "query", publicName: "query", isSignal: true, isRequired: false, transformFunction: null }, idProperty: { classPropertyName: "idProperty", publicName: "idProperty", isSignal: true, isRequired: false, transformFunction: null }, transformer: { classPropertyName: "transformer", publicName: "transformer", isSignal: true, isRequired: false, transformFunction: null }, preventChangeUntil: { classPropertyName: "preventChangeUntil", publicName: "preventChangeUntil", isSignal: true, isRequired: false, transformFunction: null }, autoSelect: { classPropertyName: "autoSelect", publicName: "autoSelect", isSignal: true, isRequired: false, transformFunction: null }, pageSize: { classPropertyName: "pageSize", publicName: "pageSize", isSignal: true, isRequired: false, transformFunction: null }, enableDragSelect: { classPropertyName: "enableDragSelect", publicName: "enableDragSelect", isSignal: true, isRequired: false, transformFunction: null }, multiselect: { classPropertyName: "multiselect", publicName: "multiselect", isSignal: true, isRequired: false, transformFunction: null }, selfHandleSelection: { classPropertyName: "selfHandleSelection", publicName: "selfHandleSelection", isSignal: true, isRequired: false, transformFunction: null }, includePermissions: { classPropertyName: "includePermissions", publicName: "includePermissions", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { itemSelect: "itemSelect", dragSelectChange: "dragSelectChange", itemDoubleClick: "itemDoubleClick", queryResult: "queryResult" }, host: { properties: { "class.pagination": "!!pagination()" } }, queries: [{ propertyName: "itemTemplate", first: true, predicate: ["yuvQueryListItem"], descendants: true, isSignal: true }, { propertyName: "emptyTemplate", first: true, predicate: ["yuvQueryListEmpty"], descendants: true, isSignal: true }], viewQueries: [{ propertyName: "list", first: true, predicate: ["list"], descendants: true, isSignal: true }], ngImport: i0, template: "<yuv-list\n  #list\n  [multiselect]=\"multiselect()\"\n  [autoSelect]=\"autoSelect()\"\n  [preventChangeUntil]=\"preventChangeUntil()\"\n  [selfHandleClick]=\"true\"\n  [selfHandleSelection]=\"selfHandleSelection()\"\n  [yuvDragSelect]=\"{ disabled: !enableDragSelect() || !multiselect() || isTouchDevice }\"\n  (dragSelectChange)=\"onDragSelectChange($event)\"\n  (dragSelect)=\"onDragSelect($event)\"\n  (itemSelect)=\"itemSelect.emit($event)\"\n>\n  @for (resultItem of resultItems(); track trackItem(resultItem, $index)) {\n    <div\n      yuvListItem\n      yuvDragSelectItem\n      [class.drop-in]=\"$index < dropInSize()\"\n      (click.single)=\"onItemClick($index, $event)\"\n      (click.double)=\"onItemDoubleClick($index, $event)\"\n    >\n      <ng-container *ngTemplateOutlet=\"itemTemplate() || null; context: { $implicit: resultItem, index: $index }\" />\n    </div>\n  } @empty {\n    <ng-container *ngTemplateOutlet=\"emptyTemplate() || null\" />\n  }\n</yuv-list>\n@if (pagination(); as pag) {\n  <mat-paginator\n    class=\"paginator\"\n    [length]=\"pag.total\"\n    [pageSize]=\"pageSize()\"\n    (page)=\"changePage($event)\"\n    hidePageSize\n  />\n}\n", styles: [":host{--paging-background: var(--ymt-surface);--drop-in-item-outline: 2px dashed rgb(from var(--ymt-primary) r g b / .9);--drop-in-item-outline-offset: -3px;display:flex;flex-direction:column;max-height:100%}:host [yuvListItem].drop-in{outline:var(--drop-in-item-outline);outline-offset:var(--drop-in-item-outline-offset);overflow:hidden}:host yuv-list{flex:1;overflow-y:auto}:host mat-paginator{flex:0 0 auto;font:inherit;border-block-start:1px solid var(--ymt-outline-variant);background-color:var(--paging-background)}\n"], dependencies: [{ kind: "ngmodule", type: CommonModule }, { kind: "directive", type: i1.NgTemplateOutlet, selector: "[ngTemplateOutlet]", inputs: ["ngTemplateOutletContext", "ngTemplateOutlet", "ngTemplateOutletInjector"] }, { kind: "ngmodule", type: YuvListModule }, { kind: "component", type: i2.ListComponent, selector: "yuv-list", inputs: ["preventChangeUntil", "multiselect", "selfHandleSelection", "selfHandleClick", "autoSelect", "disableSelection"], outputs: ["itemSelect", "itemFocus"] }, { kind: "directive", type: i2.ListItemDirective, selector: "[yuvListItem]", inputs: ["disabled", "active", "selected"] }, { kind: "directive", type: ClickDoubleDirective, selector: "[click.single],[click.double]", inputs: ["debounceTime"], outputs: ["click.double", "click.single"] }, { kind: "directive", type: DragSelectDirective, selector: "[yuvDragSelect]", inputs: ["yuvDragSelect"], outputs: ["dragSelectChange", "dragSelect"] }, { kind: "directive", type: DragSelectItemDirective, selector: "[yuvDragSelectItem]" }, { kind: "ngmodule", type: MatPaginatorModule }, { kind: "component", type: i3.MatPaginator, selector: "mat-paginator", inputs: ["color", "pageIndex", "length", "pageSize", "pageSizeOptions", "hidePageSize", "showFirstLastButtons", "selectConfig", "disabled"], outputs: ["page"], exportAs: ["matPaginator"] }], changeDetection: i0.ChangeDetectionStrategy.OnPush }); }
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.2.20", ngImport: i0, type: QueryListComponent, decorators: [{
             type: Component,
-            args: [{ selector: 'yuv-query-list', imports: [CommonModule, YuvListModule, ClickDoubleDirective, DragSelectDirective, DragSelectItemDirective, MatPaginatorModule], template: "<yuv-list\n  #list\n  [multiselect]=\"multiselect()\"\n  [autoSelect]=\"autoSelect()\"\n  [preventChangeUntil]=\"preventChangeUntil()\"\n  [selfHandleClick]=\"true\"\n  [selfHandleSelection]=\"selfHandleSelection()\"\n  [yuvDragSelect]=\"{ disabled: !enableDragSelect() || !multiselect() || isTouchDevice }\"\n  (dragSelectChange)=\"onDragSelectChange($event)\"\n  (dragSelect)=\"onDragSelect($event)\"\n  (itemSelect)=\"itemSelect.emit($event)\"\n>\n  @for (i of resultItems(); track idProperty() || $index) {\n    <div yuvListItem yuvDragSelectItem [class.drop-in]=\"$index < dropInSize()\"\n    (click.single)=\"onItemClick($index, $event)\"\n    (click.double)=\"onItemDoubleClick($index, $event)\" >\n      <ng-container *ngTemplateOutlet=\"itemTemplate() || null; context: { $implicit: i, index: $index }\"></ng-container>\n    </div>\n  } @empty {\n    <ng-container *ngTemplateOutlet=\"emptyTemplate() || null\"></ng-container>\n  }\n</yuv-list>\n@if (pagination) {\n  <mat-paginator class=\"paginator\" [length]=\"pagination.total\" [pageSize]=\"pageSize()\" (page)=\"changePage($event)\" hidePageSize> </mat-paginator>\n}\n", styles: [":host{--paging-background: var(--ymt-surface);--drop-in-item-outline: 2px dashed rgb(from var(--ymt-primary) r g b / .9);--drop-in-item-outline-offset: -3px;display:flex;flex-direction:column;max-height:100%}:host [yuvListItem].drop-in{outline:var(--drop-in-item-outline);outline-offset:var(--drop-in-item-outline-offset);overflow:hidden}:host yuv-list{flex:1;overflow-y:auto}:host mat-paginator{flex:0 0 auto;font:inherit;border-block-start:1px solid var(--ymt-outline-variant);background-color:var(--paging-background)}\n"] }]
-        }], propDecorators: { pagination: [{
-                type: HostBinding,
-                args: ['class.pagination']
-            }] } });
+            args: [{ selector: 'yuv-query-list', imports: [
+                        CommonModule,
+                        YuvListModule,
+                        ClickDoubleDirective,
+                        DragSelectDirective,
+                        DragSelectItemDirective,
+                        MatPaginatorModule
+                    ], host: { '[class.pagination]': '!!pagination()' }, changeDetection: ChangeDetectionStrategy.OnPush, template: "<yuv-list\n  #list\n  [multiselect]=\"multiselect()\"\n  [autoSelect]=\"autoSelect()\"\n  [preventChangeUntil]=\"preventChangeUntil()\"\n  [selfHandleClick]=\"true\"\n  [selfHandleSelection]=\"selfHandleSelection()\"\n  [yuvDragSelect]=\"{ disabled: !enableDragSelect() || !multiselect() || isTouchDevice }\"\n  (dragSelectChange)=\"onDragSelectChange($event)\"\n  (dragSelect)=\"onDragSelect($event)\"\n  (itemSelect)=\"itemSelect.emit($event)\"\n>\n  @for (resultItem of resultItems(); track trackItem(resultItem, $index)) {\n    <div\n      yuvListItem\n      yuvDragSelectItem\n      [class.drop-in]=\"$index < dropInSize()\"\n      (click.single)=\"onItemClick($index, $event)\"\n      (click.double)=\"onItemDoubleClick($index, $event)\"\n    >\n      <ng-container *ngTemplateOutlet=\"itemTemplate() || null; context: { $implicit: resultItem, index: $index }\" />\n    </div>\n  } @empty {\n    <ng-container *ngTemplateOutlet=\"emptyTemplate() || null\" />\n  }\n</yuv-list>\n@if (pagination(); as pag) {\n  <mat-paginator\n    class=\"paginator\"\n    [length]=\"pag.total\"\n    [pageSize]=\"pageSize()\"\n    (page)=\"changePage($event)\"\n    hidePageSize\n  />\n}\n", styles: [":host{--paging-background: var(--ymt-surface);--drop-in-item-outline: 2px dashed rgb(from var(--ymt-primary) r g b / .9);--drop-in-item-outline-offset: -3px;display:flex;flex-direction:column;max-height:100%}:host [yuvListItem].drop-in{outline:var(--drop-in-item-outline);outline-offset:var(--drop-in-item-outline-offset);overflow:hidden}:host yuv-list{flex:1;overflow-y:auto}:host mat-paginator{flex:0 0 auto;font:inherit;border-block-start:1px solid var(--ymt-outline-variant);background-color:var(--paging-background)}\n"] }]
+        }], ctorParameters: () => [] });
 
 const cmp = [QueryListComponent];
 class YuvQueryListModule {