@yuuvis/client-framework 2.19.0 → 2.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (27) hide show
  1. package/breadcrumb/index.d.ts +2 -0
  2. package/breadcrumb/lib/breadcrumb/breadcrumb.component.d.ts +94 -0
  3. package/breadcrumb/lib/models/breadcrumb-item.model.d.ts +14 -0
  4. package/breadcrumb/lib/models/index.d.ts +1 -0
  5. package/fesm2022/yuuvis-client-framework-breadcrumb.mjs +117 -0
  6. package/fesm2022/yuuvis-client-framework-breadcrumb.mjs.map +1 -0
  7. package/fesm2022/yuuvis-client-framework-list.mjs +365 -121
  8. package/fesm2022/yuuvis-client-framework-list.mjs.map +1 -1
  9. package/fesm2022/yuuvis-client-framework-object-details.mjs +28 -26
  10. package/fesm2022/yuuvis-client-framework-object-details.mjs.map +1 -1
  11. package/fesm2022/yuuvis-client-framework-object-form.mjs.map +1 -1
  12. package/fesm2022/yuuvis-client-framework-object-versions.mjs +1 -1
  13. package/fesm2022/yuuvis-client-framework-object-versions.mjs.map +1 -1
  14. package/fesm2022/yuuvis-client-framework-query-list.mjs +462 -127
  15. package/fesm2022/yuuvis-client-framework-query-list.mjs.map +1 -1
  16. package/fesm2022/yuuvis-client-framework-tile-list.mjs +695 -178
  17. package/fesm2022/yuuvis-client-framework-tile-list.mjs.map +1 -1
  18. package/lib/assets/i18n/ar.json +2 -1
  19. package/lib/assets/i18n/de.json +2 -1
  20. package/lib/assets/i18n/en.json +2 -1
  21. package/list/lib/list.component.d.ts +256 -44
  22. package/object-details/lib/object-details-header/object-details-header.component.d.ts +5 -2
  23. package/object-details/lib/object-details-shell/object-details-shell.component.d.ts +5 -2
  24. package/object-details/lib/object-details.component.d.ts +3 -1
  25. package/package.json +8 -4
  26. package/query-list/lib/query-list.component.d.ts +381 -86
  27. package/tile-list/lib/tile-list/tile-list.component.d.ts +527 -72
@@ -6,188 +6,483 @@ import { ListComponent } from '@yuuvis/client-framework/list';
6
6
  import { Pagination } from '@yuuvis/client-framework/pagination';
7
7
  import * as i0 from "@angular/core";
8
8
  /**
9
- * Component to display a list of items based on a search query.
10
- * It will execute the query and render the results using the provided item template.
9
+ * Query-driven list component that executes a search query and renders the results
10
+ * using a consumer-provided item template.
11
11
  *
12
- * The component supports pagination, multi-selection, and drag selection.
12
+ * The component is a thin orchestration layer on top of `yuv-list`: it handles the
13
+ * full query lifecycle (executing, paginating, refreshing), exposes a typed result
14
+ * set via the optional `transformer` input, and delegates all keyboard navigation,
15
+ * selection, and accessibility concerns to the inner `ListComponent`.
13
16
  *
14
- * If you don't provide a transformer function, the raw SearchResultItem objects will be
15
- * used as items and passed to the template. The transformer function allows you to map
16
- * the SearchResultItem objects to a custom format before rendering.
17
+ * **Key Features:**
18
+ * - Accepts a `SearchQuery` object or a raw CMIS query string
19
+ * - Optional `transformer` function maps raw `SearchResultItem[]` to any custom type `T`
20
+ * - Built-in server-side pagination via Angular Material `mat-paginator`
21
+ * - Multi-selection with mouse drag (`DragSelectDirective`) and keyboard modifiers
22
+ * - "Drop-in" items prepended to the result set for optimistic UI updates
23
+ * - Busy state signal for loading indicators
24
+ * - Exposes a slim imperative API (`select`, `clear`, `refresh`, `goToPage`, …)
25
+ * so parents can drive the list programmatically
17
26
  *
18
- * Example usage:
27
+ * **Content Projection Slots:**
28
+ * - `#yuvQueryListItem` — required; `ng-template` used to render each result item.
29
+ * Receives the (optionally transformed) item as `$implicit`.
30
+ * - `#yuvQueryListEmpty` — optional; `ng-template` shown when the result set is empty.
31
+ *
32
+ * **Basic usage:**
19
33
  * ```html
20
- * <yuv-query-list [transformer]="transformResult" [query]="query" (itemSelect)="onItemSelect($event)">
21
-
22
- <!-- template used to render result item -->
23
- <ng-template #yuvQueryListItem let-item>
24
- <yuv-list-tile>
25
- <ng-template #titleSlot>{{ item.id }}</ng-template>
26
- <ng-template #descriptionSlot>{{ item.modified }}</ng-template>
27
- </yuv-list-tile>
28
- </ng-template>
29
-
30
- <!-- Content to display when the list is empty -->
31
- <ng-template #yuvQueryListEmpty>
32
- <div>No documents found.</div>
33
- </ng-template>
34
-
35
- </yuv-query-list>
34
+ * <yuv-query-list [query]="query" (itemSelect)="onSelect($event)">
35
+ * <ng-template #yuvQueryListItem let-item>
36
+ * <span>{{ item.title }}</span>
37
+ * </ng-template>
38
+ * </yuv-query-list>
36
39
  * ```
37
40
  *
38
- * ```ts
39
- * @Component({...})
40
- * export class TestQueryListComponent {
41
- * query = 'SELECT * FROM system:document';
41
+ * **With transformer and empty state:**
42
+ * ```html
43
+ * <yuv-query-list [query]="query" [transformer]="toViewModel" (itemSelect)="onSelect($event)">
44
+ * <ng-template #yuvQueryListItem let-item>
45
+ * <yuv-list-tile>
46
+ * <ng-template #titleSlot>{{ item.title }}</ng-template>
47
+ * <ng-template #descriptionSlot>{{ item.modified }}</ng-template>
48
+ * </yuv-list-tile>
49
+ * </ng-template>
50
+ * <ng-template #yuvQueryListEmpty>
51
+ * <p>No results found.</p>
52
+ * </ng-template>
53
+ * </yuv-query-list>
54
+ * ```
42
55
  *
43
- * transformResult = (items: SearchResultItem[]) =>
44
- * items.map((item) => ({
45
- * id: item.fields.get(BaseObjectTypeField.OBJECT_ID),
56
+ * ```ts
57
+ * toViewModel = (items: SearchResultItem[]) =>
58
+ * items.map(item => ({
59
+ * title: item.fields.get(BaseObjectTypeField.OBJECT_ID),
46
60
  * modified: item.fields.get(BaseObjectTypeField.MODIFICATION_DATE)
47
61
  * }));
48
- * } *
49
62
  * ```
63
+ *
64
+ * @typeParam T The shape of each item after the optional `transformer` is applied.
65
+ * Defaults to `any` when no transformer is provided.
50
66
  */
51
67
  export declare class QueryListComponent<T = any> {
52
68
  #private;
69
+ /**
70
+ * Current pagination state. Set to a `Pagination` object when the last query
71
+ * result contained multiple pages; `undefined` when all results fit on one page
72
+ * or no query has been executed yet.
73
+ *
74
+ * Drives the `[class.pagination]` host binding so the template can conditionally
75
+ * render the `mat-paginator` footer.
76
+ */
77
+ pagination: import("@angular/core").WritableSignal<Pagination | undefined>;
78
+ /**
79
+ * Reference to the inner `ListComponent` instance.
80
+ *
81
+ * Used internally to delegate imperative operations (select, clear, focus, …).
82
+ * Can also be accessed from the parent via a `@ViewChild` on `yuv-query-list` if
83
+ * fine-grained control over the inner list is needed, though the public API methods
84
+ * on this component are preferred.
85
+ */
53
86
  list: import("@angular/core").Signal<ListComponent>;
87
+ /**
88
+ * Reference to the `#yuvQueryListItem` `ng-template` projected by the consumer.
89
+ *
90
+ * This template is used to render each individual item in the list. The template
91
+ * receives the (optionally transformed) item as the `$implicit` context variable:
92
+ * ```html
93
+ * <ng-template #yuvQueryListItem let-item>{{ item.title }}</ng-template>
94
+ * ```
95
+ */
54
96
  itemTemplate: import("@angular/core").Signal<TemplateRef<any> | undefined>;
97
+ /**
98
+ * Reference to the optional `#yuvQueryListEmpty` `ng-template` projected by the consumer.
99
+ *
100
+ * When provided, this template is rendered in place of the list whenever the query
101
+ * returns zero items. If omitted, nothing is shown for the empty state.
102
+ * ```html
103
+ * <ng-template #yuvQueryListEmpty>
104
+ * <p>No results found.</p>
105
+ * </ng-template>
106
+ * ```
107
+ */
55
108
  emptyTemplate: import("@angular/core").Signal<TemplateRef<any> | undefined>;
56
- isTouchDevice: boolean;
57
109
  /**
58
- * The query to execute (SearchQuery object or CMIS query string).
110
+ * The search query to execute.
111
+ *
112
+ * Accepts either a structured `SearchQuery` object (field filters, sort orders, etc.)
113
+ * or a raw CMIS query string. The query is re-executed reactively every time this
114
+ * input changes. Set to `null` or `undefined` to clear the list without triggering
115
+ * a new request.
59
116
  */
60
117
  query: import("@angular/core").InputSignal<string | SearchQuery | null | undefined>;
61
118
  /**
62
- * Optional property name to use as unique identifier for items.
63
- * If not provided, the index of the item in the result set will be used.
119
+ * Property name on the (transformed) item to use as a stable unique identifier.
120
+ *
121
+ * When provided, the template renderer uses this property for `@for` tracking instead
122
+ * of the item's position index, which preserves DOM nodes and component state when the
123
+ * list is refreshed with partially overlapping results.
124
+ *
125
+ * If omitted, the zero-based index is used as the tracking key.
126
+ *
127
+ * @default null
64
128
  */
65
129
  idProperty: import("@angular/core").InputSignal<string | null>;
66
130
  /**
67
- * Optional transformer function to map SearchResultItem to a custom format.
131
+ * Optional mapping function applied to the raw `SearchResultItem[]` returned by the
132
+ * search service before the results are rendered.
133
+ *
134
+ * Use this to project only the fields your template needs, compute derived properties,
135
+ * or convert dates/enums to display-friendly values. The generic type parameter `T`
136
+ * of the component is inferred from the return type of this function.
137
+ *
138
+ * If omitted, raw `SearchResultItem` objects are passed to the item template as-is.
139
+ *
140
+ * @example
141
+ * ```ts
142
+ * transformer = (items: SearchResultItem[]) =>
143
+ * items.map(item => ({
144
+ * id: item.fields.get(BaseObjectTypeField.OBJECT_ID) as string,
145
+ * title: item.fields.get('cm:name') as string
146
+ * }));
147
+ * ```
68
148
  */
69
149
  transformer: import("@angular/core").InputSignal<((items: SearchResultItem[]) => T[]) | null | undefined>;
70
150
  /**
71
- * Function that returns `true` if selection changes should be prevented.
72
- * This can be used to temporarily block selection changes, e.g. while
73
- * there is a pending change inside another component that refers to the
74
- * current selection.
151
+ * Guard function that temporarily blocks all selection changes.
152
+ *
153
+ * Forwarded directly to the inner `ListComponent`. As long as the returned predicate
154
+ * evaluates to `true`, any attempt to change the selection — via click, keyboard, or
155
+ * the programmatic API — is silently ignored. Useful when the parent has unsaved
156
+ * changes tied to the current selection and needs to prevent the user from
157
+ * accidentally navigating away.
158
+ *
159
+ * @default () => false (never prevents)
75
160
  */
76
161
  preventChangeUntil: import("@angular/core").InputSignal<() => boolean>;
77
162
  /**
78
- * If `true`, the list will select an item automatically on initialization.
79
- * First, list will search for an item item that has the "selected"-attribute
80
- * and is not disabled. If no such item exists, the first item will be selected.
163
+ * Automatically selects an item when the list is first rendered.
164
+ *
165
+ * Forwarded to the inner `ListComponent`. The selection logic runs once after the
166
+ * initial query result is displayed and follows this priority:
167
+ * 1. The first non-disabled item that already carries the `selected` attribute.
168
+ * 2. If no such item exists and `autoSelect` is `true`, the item at index 0.
169
+ *
170
+ * Accepts any truthy string in addition to a real boolean so it can be set as a
171
+ * plain HTML attribute: `<yuv-query-list autoSelect>`.
172
+ *
81
173
  * @default false
82
174
  */
83
175
  autoSelect: import("@angular/core").InputSignalWithTransform<boolean, BooleanInput>;
84
176
  /**
85
- * Event emitted when items are selected. Emits an array of selected item indices.
177
+ * Emits the current selection as an array of zero-based item indices whenever
178
+ * the selection changes — via click, drag, keyboard, or programmatic API calls.
179
+ *
180
+ * An empty array signals that the selection has been cleared.
86
181
  */
87
182
  itemSelect: import("@angular/core").OutputEmitterRef<number[]>;
88
183
  /**
89
- * Event emitted during drag selection, providing the current selection of item indices.
184
+ * Emits the live selection indices while the user is actively dragging to select.
185
+ *
186
+ * Fires continuously during a drag operation (before the drag is released), allowing
187
+ * the parent to show a live preview of what will be selected. Once the drag ends,
188
+ * `itemSelect` fires with the final committed selection.
90
189
  */
91
190
  dragSelectChange: import("@angular/core").OutputEmitterRef<number[]>;
92
191
  /**
93
- * Event emitted when an item is double-clicked, providing the index of the item.
192
+ * Emits the zero-based index of an item when it is double-clicked.
193
+ *
194
+ * The inner list operates with `selfHandleClick` mode when double-click is active,
195
+ * so single clicks do not immediately trigger `itemSelect`. The parent should listen
196
+ * to both `itemSelect` (for single-click selection) and this event (for double-click
197
+ * actions like opening a detail view).
94
198
  */
95
199
  itemDoubleClick: import("@angular/core").OutputEmitterRef<number>;
96
200
  /**
97
- * Event emitted when the query result is available, providing total count of items.
201
+ * Emits once per query execution when the search result arrives, providing the total
202
+ * count of matching items and the raw result page.
203
+ *
204
+ * Use this to update external counters, breadcrumbs, or analytics — without having to
205
+ * execute a separate count query. Note that `totalCount` reflects the server-side total,
206
+ * not just the number of items on the current page.
98
207
  */
99
208
  queryResult: import("@angular/core").OutputEmitterRef<{
100
209
  totalCount: number;
101
210
  items: SearchResultItem[];
102
211
  }>;
103
- dropInSize: import("@angular/core").Signal<number>;
104
212
  /**
105
- * The list of result items after applying the optional transformer.
106
- */
107
- resultItems: import("@angular/core").Signal<T[]>;
108
- /**
109
- * Number of items to fetch per page when executing the query.
213
+ * Number of items to request per page from the search service.
214
+ *
215
+ * Controls the `size` parameter of each search request. When the total result count
216
+ * exceeds this value, pagination controls are shown and the user can navigate between
217
+ * pages via `changePage()` / `goToPage()`.
218
+ *
110
219
  * @default SearchService.DEFAULT_QUERY_SIZE
111
220
  */
112
221
  pageSize: import("@angular/core").InputSignal<number>;
113
222
  /**
114
- * Enables or disables drag selection of items. If `true`, users can select multiple items by dragging the mouse.
223
+ * Enables mouse drag-to-select on list items.
224
+ *
225
+ * When `true` and `multiselect` is also `true`, the user can click and drag across
226
+ * items to select a range without holding Shift. Powered by `DragSelectDirective`.
227
+ * Automatically disabled on touch devices regardless of this input value.
228
+ *
115
229
  * @default true
116
230
  */
117
231
  enableDragSelect: import("@angular/core").InputSignal<boolean>;
118
232
  /**
119
- * Sets up the ability to select multiple tiles
233
+ * Enables multi-selection mode.
234
+ *
235
+ * When `true`, the user can hold **Shift** or **Ctrl** to extend or toggle the
236
+ * selection, and drag-to-select becomes available (if `enableDragSelect` is also
237
+ * `true`). Forwarded to the inner `ListComponent`.
238
+ *
120
239
  * @default false
121
240
  */
122
241
  multiselect: import("@angular/core").InputSignal<boolean>;
123
242
  /**
124
- * If `true`, the component will handle selection itself. This means that
125
- * the parent component will be responsible for styling the selected and
126
- * focused items. If `false`, the component will take care of visualizing
127
- * the selection and focus states.
243
+ * Delegates visual selection and focus state rendering to the parent component.
244
+ *
245
+ * When `false` (default), `yuv-list` applies CSS classes for selected and active
246
+ * states automatically. When `true`, those signals are still updated but the host
247
+ * receives the `self-handle-selection` CSS class, allowing the parent to apply
248
+ * its own visual treatment. Forwarded to the inner `ListComponent`.
249
+ *
128
250
  * @default false
129
251
  */
130
252
  selfHandleSelection: import("@angular/core").InputSignal<boolean>;
131
253
  /**
132
- * Indicator signal whether a query is currently being executed.
133
- * You could use this to show a loading indicator in the UI.
254
+ * Whether to include permission information in CMIS search results.
255
+ * When `true`, the third parameter of `searchCmis()` is set,
256
+ * causing the backend to return permission data alongside each item.
257
+ *
258
+ * @default false
259
+ */
260
+ includePermissions: import("@angular/core").InputSignal<boolean>;
261
+ /**
262
+ * Whether the current device has touch input enabled.
263
+ *
264
+ * Sourced from `DeviceService`. Used in the template to conditionally disable
265
+ * drag-to-select, which is not suitable for touch interactions.
266
+ */
267
+ isTouchDevice: boolean;
268
+ /**
269
+ * Number of drop-in items currently prepended to the result list.
270
+ *
271
+ * Derived from the internal `#dropInItems` signal. Exposed publicly so the template
272
+ * and parent components can easily check whether any temporary items are present
273
+ * (e.g. to show a visual indicator or adjust layout) without accessing internal state.
274
+ */
275
+ dropInSize: import("@angular/core").Signal<number>;
276
+ /**
277
+ * The final list of items rendered by the template.
278
+ *
279
+ * Computed from three sources, merged in this order:
280
+ * 1. **Drop-in items** (`#dropInItems`) — temporary items prepended to the list,
281
+ * e.g. newly created objects that should appear before they match the query.
282
+ * 2. **Transformed query results** — raw `SearchResultItem[]` passed through the
283
+ * optional `transformer` function (or cast directly to `T[]` if none is provided).
284
+ * 3. **Optimistic updates** (`#listItemUpdates`) — per-index overrides applied on top
285
+ * of the merged list, allowing individual items to be patched without re-fetching.
286
+ *
287
+ * Re-evaluates automatically whenever any of the three sources change.
288
+ */
289
+ resultItems: import("@angular/core").Signal<T[]>;
290
+ /**
291
+ * Indicates whether a search request is currently in flight.
292
+ *
293
+ * Set to `true` immediately before a query or page request is dispatched to the
294
+ * search service, and back to `false` once the response (or error) arrives.
295
+ * Bind this to a loading indicator or `BusyOverlayDirective` in the parent template:
296
+ * ```html
297
+ * <yuv-query-list #qList ...>...</yuv-query-list>
298
+ * <yuv-busy-overlay [active]="qList.busy()" />
299
+ * ```
134
300
  */
135
301
  busy: import("@angular/core").WritableSignal<boolean>;
136
- pagination?: Pagination;
302
+ constructor();
303
+ /** Resolves the tracking key for a result item in the `@for` loop. */
304
+ trackItem(item: T, index: number): unknown;
305
+ /**
306
+ * Handles a single click on a list item.
307
+ *
308
+ * Forwards the click to the inner `ListComponent` with the correct Shift/Ctrl modifier
309
+ * flags so range- and toggle-selection work correctly. Also transfers DOM focus to the
310
+ * list host so subsequent keyboard navigation works without an additional Tab press.
311
+ *
312
+ * Called from the template via `(click)` on each item wrapper. Not intended for
313
+ * external callers — use `select()` instead.
314
+ *
315
+ * @param idx Zero-based index of the clicked item.
316
+ * @param event The originating mouse event (provides `shiftKey` and `ctrlKey` flags).
317
+ */
137
318
  onItemClick(idx: number, event: MouseEvent): void;
319
+ /**
320
+ * Handles a double-click on a list item.
321
+ *
322
+ * Emits the `itemDoubleClick` output with the item's index. The parent can use this
323
+ * to trigger a secondary action (e.g. opening a detail panel or navigating to a route)
324
+ * that is distinct from the primary single-click selection.
325
+ *
326
+ * Called from the template via `ClickDoubleDirective`. Not intended for external callers.
327
+ *
328
+ * @param idx Zero-based index of the double-clicked item.
329
+ * @param event The originating mouse event (unused, kept for directive compatibility).
330
+ */
138
331
  onItemDoubleClick(idx: number, event: MouseEvent): void;
332
+ /**
333
+ * Handles intermediate drag-selection changes from `DragSelectDirective`.
334
+ *
335
+ * Fires continuously while the user is dragging across items. Updates the inner list's
336
+ * multi-selection state in real time so items are highlighted as the drag progresses,
337
+ * and also emits `dragSelectChange` so the parent can show a live preview.
338
+ *
339
+ * Called from the template via `(dragSelectChange)` on the drag-select host.
340
+ * Not intended for external callers.
341
+ *
342
+ * @param sel Current array of zero-based indices covered by the drag gesture.
343
+ */
139
344
  onDragSelectChange(sel: number[]): void;
345
+ /**
346
+ * Handles the final committed drag-selection from `DragSelectDirective`.
347
+ *
348
+ * Called when the user releases the mouse after a drag-to-select gesture. Transfers
349
+ * DOM focus to the list (so keyboard navigation works immediately after) and emits
350
+ * the final selection via `itemSelect`.
351
+ *
352
+ * Called from the template via `(dragSelect)` on the drag-select host.
353
+ * Not intended for external callers.
354
+ *
355
+ * @param sel Final array of zero-based indices selected by the drag gesture.
356
+ */
140
357
  onDragSelect(sel: number[]): void;
141
358
  /**
142
- * Updates an item in the list at the specified index with the provided value.
143
- * The value should match the type returned by the transformer function, if provided.
144
- * If you did not provide a transformer, the value should be of type SearchResultItem.
359
+ * Applies optimistic per-item overrides on top of the current query result.
145
360
  *
146
- * Use this method for optimistic updates of list items. The updates be removed
147
- * when the user navigates to another search result page.
361
+ * Each entry in the `updates` array patches the item at the given `index` with
362
+ * the provided `value`. The value type must match `T` — i.e. the shape produced
363
+ * by the `transformer` function, or `SearchResultItem` if no transformer is used.
148
364
  *
149
- * @param index Index of the item to update.
150
- * @param value The new value for the item.
365
+ * Overrides accumulate: calling this method multiple times merges the new entries
366
+ * with any previously applied ones. All overrides are automatically discarded when
367
+ * the user navigates to a different page (see `goToPage()`), since a fresh server
368
+ * response replaces the local data.
369
+ *
370
+ * **Use case:** apply instant visual feedback after a user action (rename, status
371
+ * change, etc.) without waiting for a full query refresh.
372
+ *
373
+ * @param updates Array of `{ index, value }` pairs describing which items to patch.
151
374
  */
152
375
  updateListItems(updates: {
153
376
  index: number;
154
377
  value: T;
155
378
  }[]): void;
156
379
  /**
157
- * Optional array of items to be shown in addition to the query results.
158
- * These items will be prepended to the list of query results and visually
159
- * highlighted. They will also be affected by selection and drag-selection.
380
+ * Prepends a set of temporary items to the top of the result list.
381
+ *
382
+ * Drop-in items appear before all query results and are visually distinguished
383
+ * by the template (e.g. a highlighted background). They participate in selection
384
+ * and drag-to-select exactly like regular items.
160
385
  *
161
- * Use this input to "drop in" items, for example when creating features
162
- * like pasting items into a list where they would otherwise not appear due
163
- * to the current query/filter.
386
+ * The existing selection indices are automatically shifted by `items.length` so that
387
+ * the currently selected query-result items remain selected after the prepend.
164
388
  *
165
- * Changing the page of the query will remove the drop-in items again, as
166
- * they are meant to be temporary.
389
+ * **Typical use case:** when the user pastes or creates an object that does not yet
390
+ * appear in the current query (e.g. because the index has not been updated), drop it
391
+ * in temporarily so the user sees it immediately without a full refresh.
167
392
  *
168
- * @param items The items to drop into the list.
169
- * @param scrollTo If `true`, the list will scroll to the top after dropping
170
- * in the items. Default is `true`.
393
+ * Drop-in items are cleared automatically when the user navigates to a different page.
394
+ * Call `dropItems([])` to remove them programmatically.
395
+ *
396
+ * @param items Items to prepend. Must be of type `T` (same as query result items).
397
+ * @param scrollTo Whether to smooth-scroll the list back to the top after prepending.
398
+ * Defaults to `true` so the newly dropped items are immediately visible.
171
399
  */
172
400
  dropItems(items: T[], scrollTo?: boolean): void;
173
401
  /**
174
- * Selects multiple items in the list.
402
+ * Programmatically replaces the entire selection with the given indices.
403
+ *
404
+ * Only effective when `multiselect` is `true`. Out-of-range indices are silently
405
+ * discarded. The resulting selection is sorted ascending before being applied.
406
+ *
407
+ * Use this when the parent needs to restore a previously saved multi-selection
408
+ * state, e.g. after navigation or component re-initialization.
409
+ *
410
+ * @param index Array of zero-based item indices to select.
175
411
  */
176
412
  multiSelect(index: number[]): void;
413
+ /**
414
+ * Selects the item at the given zero-based index.
415
+ *
416
+ * Delegates to the inner `ListComponent`. The `preventChangeUntil` guard and
417
+ * `disableSelection` state are respected. Clamps the index to the valid range.
418
+ *
419
+ * @param index Zero-based index of the item to select.
420
+ */
177
421
  select(index: number): void;
422
+ /**
423
+ * Moves keyboard focus to the item at the given index and selects it.
424
+ *
425
+ * Combines focus management and selection in one call, and transfers DOM focus
426
+ * to the list host. Use this when the parent wants to programmatically drive
427
+ * both the visual focus indicator and the selection simultaneously.
428
+ *
429
+ * @param index Zero-based index of the item to activate.
430
+ */
178
431
  setActiveItem(index: number): void;
179
432
  /**
180
- * Clear the current selection.
181
- * @param silent If `true`, the `itemSelect` event will not be emitted.
433
+ * Clears the current selection and resets the active keyboard-focus index.
434
+ *
435
+ * If the selection is already empty, the method is a no-op. The `preventChangeUntil`
436
+ * guard is respected — if the guard returns `true`, the clear is blocked.
437
+ *
438
+ * @param silent When `true`, skips emitting `itemSelect` after clearing. Use this
439
+ * when the parent needs to reset state programmatically without
440
+ * triggering downstream reactions.
182
441
  */
183
442
  clear(silent?: boolean): void;
184
443
  /**
185
- * Refreshes the list by re-executing the current query/page.
444
+ * Re-executes the current query without changing the page or query parameters.
445
+ *
446
+ * If pagination is active, re-fetches the same page the user is currently on.
447
+ * If no pagination is active, re-runs the original query from scratch.
448
+ *
449
+ * Use this to reflect server-side changes (e.g. after a create/delete operation)
450
+ * without navigating away from the current view.
186
451
  */
187
452
  refresh(): void;
453
+ /**
454
+ * Forces the `transformer` function to be re-applied to the current result set.
455
+ *
456
+ * Normally the transformer runs automatically whenever the underlying `#items`
457
+ * signal changes. Use this method when the transformer itself has external
458
+ * dependencies that changed (e.g. a locale or display-format setting) but the
459
+ * raw search result did not — triggering a re-evaluation by creating a new array
460
+ * reference for `#items` without fetching from the server again.
461
+ */
188
462
  runTransformerAgain(): void;
189
- changePage(pe: PageEvent): void;
463
+ /**
464
+ * Handles a page-change event emitted by the `mat-paginator`.
465
+ *
466
+ * Converts the zero-based `pageEvent.pageIndex` to the one-based page number
467
+ * expected by `goToPage()` and delegates the request.
468
+ *
469
+ * Bound to `(page)` on the `mat-paginator` in the template.
470
+ *
471
+ * @param pageEvent The pagination event emitted by `MatPaginatorModule`.
472
+ */
473
+ changePage(pageEvent: PageEvent): void;
474
+ /**
475
+ * Fetches and displays the given page of the current query result.
476
+ *
477
+ * Sets `busy` to `true` for the duration of the request. On success, updates
478
+ * the pagination state, clears all optimistic overrides (they are page-scoped),
479
+ * and replaces `#items` with the new page's results.
480
+ *
481
+ * Also used internally by `refresh()` to reload the currently active page.
482
+ *
483
+ * @param page One-based page number to navigate to.
484
+ */
190
485
  goToPage(page: number): void;
191
486
  static ɵfac: i0.ɵɵFactoryDeclaration<QueryListComponent<any>, never>;
192
- static ɵcmp: i0.ɵɵComponentDeclaration<QueryListComponent<any>, "yuv-query-list", never, { "query": { "alias": "query"; "required": false; "isSignal": true; }; "idProperty": { "alias": "idProperty"; "required": false; "isSignal": true; }; "transformer": { "alias": "transformer"; "required": false; "isSignal": true; }; "preventChangeUntil": { "alias": "preventChangeUntil"; "required": false; "isSignal": true; }; "autoSelect": { "alias": "autoSelect"; "required": false; "isSignal": true; }; "pageSize": { "alias": "pageSize"; "required": false; "isSignal": true; }; "enableDragSelect": { "alias": "enableDragSelect"; "required": false; "isSignal": true; }; "multiselect": { "alias": "multiselect"; "required": false; "isSignal": true; }; "selfHandleSelection": { "alias": "selfHandleSelection"; "required": false; "isSignal": true; }; }, { "itemSelect": "itemSelect"; "dragSelectChange": "dragSelectChange"; "itemDoubleClick": "itemDoubleClick"; "queryResult": "queryResult"; }, ["itemTemplate", "emptyTemplate"], never, true, never>;
487
+ static ɵcmp: i0.ɵɵComponentDeclaration<QueryListComponent<any>, "yuv-query-list", never, { "query": { "alias": "query"; "required": false; "isSignal": true; }; "idProperty": { "alias": "idProperty"; "required": false; "isSignal": true; }; "transformer": { "alias": "transformer"; "required": false; "isSignal": true; }; "preventChangeUntil": { "alias": "preventChangeUntil"; "required": false; "isSignal": true; }; "autoSelect": { "alias": "autoSelect"; "required": false; "isSignal": true; }; "pageSize": { "alias": "pageSize"; "required": false; "isSignal": true; }; "enableDragSelect": { "alias": "enableDragSelect"; "required": false; "isSignal": true; }; "multiselect": { "alias": "multiselect"; "required": false; "isSignal": true; }; "selfHandleSelection": { "alias": "selfHandleSelection"; "required": false; "isSignal": true; }; "includePermissions": { "alias": "includePermissions"; "required": false; "isSignal": true; }; }, { "itemSelect": "itemSelect"; "dragSelectChange": "dragSelectChange"; "itemDoubleClick": "itemDoubleClick"; "queryResult": "queryResult"; }, ["itemTemplate", "emptyTemplate"], never, true, never>;
193
488
  }