@sdcorejs/angular 19.3.0 → 19.3.1

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 (63) hide show
  1. package/README.md +2 -2
  2. package/components/file-explorer/index.d.ts +1 -0
  3. package/components/file-explorer/src/components/actions.component.d.ts +40 -0
  4. package/components/file-explorer/src/components/command-sheet.component.d.ts +49 -0
  5. package/components/file-explorer/src/components/folder-tree.component.d.ts +41 -11
  6. package/components/file-explorer/src/components/item-list.component.d.ts +68 -13
  7. package/components/file-explorer/src/components/menu-trigger.component.d.ts +27 -0
  8. package/components/file-explorer/src/components/preview-panel.component.d.ts +6 -4
  9. package/components/file-explorer/src/file-explorer-actions.d.ts +80 -0
  10. package/components/file-explorer/src/file-explorer-column.directive.d.ts +20 -0
  11. package/components/file-explorer/src/file-explorer-move.d.ts +12 -0
  12. package/components/file-explorer/src/file-explorer-normalize.d.ts +72 -0
  13. package/components/file-explorer/src/file-explorer.component.d.ts +106 -23
  14. package/components/file-explorer/src/file-explorer.model.d.ts +210 -29
  15. package/components/file-explorer/src/file-explorer.utils.d.ts +1 -1
  16. package/components/file-explorer/src/file-explorer.view-model.d.ts +75 -5
  17. package/components/form-generic/src/components/form-builder/form-builder.component.d.ts +5 -0
  18. package/components/form-generic/src/components/form-builder/inspector/inspector.component.d.ts +75 -67
  19. package/components/form-generic/src/components/form-builder/state/builder-commands.d.ts +3 -1
  20. package/components/form-generic/src/components/form-builder/state/builder-document.d.ts +6 -2
  21. package/components/form-generic/src/components/form-builder/state/builder-store.d.ts +18 -1
  22. package/components/form-generic/src/components/form-render/components/item/components/datetime/datetime.component.d.ts +7 -6
  23. package/components/form-generic/src/components/form-render/components/item/item.component.d.ts +3 -1
  24. package/components/form-generic/src/components/form-render/form-render.component.d.ts +31 -4
  25. package/components/form-generic/src/models/form-generic-schema.model.d.ts +2 -1
  26. package/components/index.d.ts +1 -0
  27. package/components/kanban/index.d.ts +3 -0
  28. package/components/kanban/src/kanban.component.d.ts +83 -0
  29. package/components/kanban/src/kanban.model.d.ts +65 -0
  30. package/components/kanban/src/kanban.templates.d.ts +30 -0
  31. package/components/kanban/src/kanban.utils.d.ts +5 -0
  32. package/components/section/src/section-item/section-item.component.d.ts +2 -1
  33. package/components/tab/src/tab-group.component.d.ts +3 -1
  34. package/fesm2022/sdcorejs-angular-components-button.mjs +2 -2
  35. package/fesm2022/sdcorejs-angular-components-button.mjs.map +1 -1
  36. package/fesm2022/sdcorejs-angular-components-file-explorer.mjs +2158 -86
  37. package/fesm2022/sdcorejs-angular-components-file-explorer.mjs.map +1 -1
  38. package/fesm2022/sdcorejs-angular-components-form-generic.mjs +637 -34
  39. package/fesm2022/sdcorejs-angular-components-form-generic.mjs.map +1 -1
  40. package/fesm2022/sdcorejs-angular-components-kanban.mjs +441 -0
  41. package/fesm2022/sdcorejs-angular-components-kanban.mjs.map +1 -0
  42. package/fesm2022/sdcorejs-angular-components-section.mjs +4 -3
  43. package/fesm2022/sdcorejs-angular-components-section.mjs.map +1 -1
  44. package/fesm2022/sdcorejs-angular-components-stepper.mjs +5 -1
  45. package/fesm2022/sdcorejs-angular-components-stepper.mjs.map +1 -1
  46. package/fesm2022/sdcorejs-angular-components-tab.mjs +11 -3
  47. package/fesm2022/sdcorejs-angular-components-tab.mjs.map +1 -1
  48. package/fesm2022/sdcorejs-angular-components.mjs +1 -0
  49. package/fesm2022/sdcorejs-angular-components.mjs.map +1 -1
  50. package/fesm2022/sdcorejs-angular-forms-segmented.mjs +244 -0
  51. package/fesm2022/sdcorejs-angular-forms-segmented.mjs.map +1 -0
  52. package/fesm2022/sdcorejs-angular-forms.mjs +8 -0
  53. package/fesm2022/sdcorejs-angular-forms.mjs.map +1 -1
  54. package/fesm2022/sdcorejs-angular-i18n.mjs +300 -0
  55. package/fesm2022/sdcorejs-angular-i18n.mjs.map +1 -1
  56. package/fesm2022/sdcorejs-angular-services-confirm.mjs +2 -2
  57. package/forms/index.d.ts +1 -0
  58. package/forms/segmented/index.d.ts +2 -0
  59. package/forms/segmented/src/segmented.component.d.ts +57 -0
  60. package/forms/segmented/src/segmented.model.d.ts +28 -0
  61. package/forms/src/forms.module.d.ts +7 -6
  62. package/i18n/src/en.d.ts +59 -0
  63. package/package.json +13 -5
@@ -1,28 +1,54 @@
1
1
  import { ElementRef, Signal, WritableSignal } from '@angular/core';
2
2
  import { SdBreadcrumbItem } from '@sdcorejs/angular/components/breadcrumb';
3
- import type { SdFileExplorerItem, SdFileExplorerOpenEvent, SdFileExplorerOption, SdFileExplorerTransfer, SdFileExplorerView } from './file-explorer.model';
4
- import type { SdFileExplorerContentState, SdFileExplorerItemView, SdFileExplorerMetaRow, SdFileExplorerPreviewState, SdFileExplorerShareFeedback, SdFileExplorerShareState, SdFileExplorerTransferView, SdFileExplorerTreeNode } from './file-explorer.view-model';
3
+ import { SdFileExplorerColumnDef } from './file-explorer-column.directive';
4
+ import { SdFileExplorerCommandSheet, type SdFileExplorerSheetActivation } from './components/command-sheet.component';
5
+ import type { SdFileExplorerItem, SdFileExplorerOpenEvent, SdFileExplorerConfig, SdFileExplorerMoveRequest, SdFileExplorerSelectionAction, SdFileExplorerTransfer, SdFileExplorerView } from './file-explorer.model';
6
+ import type { SdFileExplorerCommandSheetView, SdFileExplorerContentState, SdFileExplorerItemView, SdFileExplorerMetaRow, SdFileExplorerPreviewState, SdFileExplorerSelectionView, SdFileExplorerShareFeedback, SdFileExplorerShareState, SdFileExplorerTransferView, SdFileExplorerTreeNode } from './file-explorer.view-model';
5
7
  import * as i0 from "@angular/core";
8
+ /** Where a compact command drawer was opened: a list row, a grid card or a tree node. */
9
+ type CommandOrigin = SdFileExplorerView | 'tree';
6
10
  /**
7
11
  * Google-Drive-like file browser: folder tree, breadcrumb, list / grid, search, file detail drawer, uploads with
8
12
  * drag-and-drop, downloads and a transfer queue — all inside one element.
9
13
  *
10
- * Storage-agnostic: every read and write goes through the callbacks of `SdFileExplorerOption`.
14
+ * Storage-agnostic: every read and write goes through the callbacks of `SdFileExplorerOption<T>`.
11
15
  *
12
16
  * @example
13
17
  * ```html
14
18
  * <sd-file-explorer [option]="option" (open)="onOpen($event)" />
15
19
  * ```
16
20
  */
17
- export declare class SdFileExplorer {
21
+ export declare class SdFileExplorer<T = unknown> {
18
22
  #private;
19
- /** Data callbacks and display settings. See `SdFileExplorerOption`. */
20
- readonly option: import("@angular/core").InputSignal<SdFileExplorerOption>;
23
+ protected readonly movePending: WritableSignal<boolean>;
24
+ protected readonly moveStatus: WritableSignal<string>;
25
+ protected readonly moveRefreshError: WritableSignal<boolean>;
26
+ protected readonly movePickerItems: WritableSignal<readonly SdFileExplorerItem<T>[] | null>;
27
+ protected readonly moveTarget: WritableSignal<SdFileExplorerItem<T> | null>;
28
+ protected readonly moveDropTarget: WritableSignal<string | null | undefined>;
29
+ protected readonly canMove: Signal<boolean>;
30
+ protected readonly movePickerNodes: Signal<{
31
+ selected: boolean;
32
+ key: string;
33
+ id: string | null;
34
+ item: SdFileExplorerItem<T> | null;
35
+ name: string;
36
+ level: number;
37
+ expandable: boolean;
38
+ expanded: boolean;
39
+ status: "idle" | "loading" | "error";
40
+ autoId?: string;
41
+ }[]>;
42
+ protected readonly canSubmitMove: Signal<boolean>;
43
+ protected readonly columnDefs: Signal<readonly SdFileExplorerColumnDef<T>[]>;
44
+ protected readonly columns: Signal<SdFileExplorerColumnDef<T>[]>;
45
+ /** Data callbacks and display settings. See `SdFileExplorerOption<T>`. */
46
+ readonly option: import("@angular/core").InputSignal<SdFileExplorerConfig<T>>;
21
47
  /**
22
48
  * Emitted exactly once each time the user opens a file (click, `Enter` or `Space` on a file in the list,
23
49
  * grid or search results), right before the detail drawer starts loading. Never emitted for folders.
24
50
  */
25
- readonly open: import("@angular/core").OutputEmitterRef<SdFileExplorerOpenEvent>;
51
+ readonly open: import("@angular/core").OutputEmitterRef<SdFileExplorerOpenEvent<T>>;
26
52
  protected readonly view: WritableSignal<SdFileExplorerView>;
27
53
  protected readonly keyword: WritableSignal<string>;
28
54
  protected readonly previewState: WritableSignal<SdFileExplorerPreviewState>;
@@ -34,7 +60,7 @@ export declare class SdFileExplorer {
34
60
  protected readonly folderSubmitting: WritableSignal<boolean>;
35
61
  protected readonly folderError: WritableSignal<string>;
36
62
  /** File whose share dialog is open. */
37
- protected readonly shareItem: WritableSignal<SdFileExplorerItem | null>;
63
+ protected readonly shareItem: WritableSignal<SdFileExplorerItem<T> | null>;
38
64
  protected readonly shareState: WritableSignal<SdFileExplorerShareState>;
39
65
  /** Result of the last copy attempt: copied to the clipboard, or selected for a manual Ctrl+C. */
40
66
  protected readonly shareFeedback: WritableSignal<SdFileExplorerShareFeedback>;
@@ -50,8 +76,10 @@ export declare class SdFileExplorer {
50
76
  protected readonly shareInput: Signal<ElementRef<HTMLInputElement> | undefined>;
51
77
  protected readonly shareDialog: Signal<ElementRef<HTMLElement> | undefined>;
52
78
  protected readonly sidebar: Signal<ElementRef<HTMLElement> | undefined>;
79
+ protected readonly commandDrawer: Signal<SdFileExplorerCommandSheet<any> | undefined>;
53
80
  protected readonly instanceId: string;
54
81
  protected readonly compact: Signal<boolean>;
82
+ protected readonly touch: Signal<boolean>;
55
83
  readonly autoId: Signal<string | undefined>;
56
84
  protected readonly locale: Signal<string>;
57
85
  protected readonly rootLabel: Signal<string>;
@@ -59,9 +87,35 @@ export declare class SdFileExplorer {
59
87
  protected readonly canDownload: Signal<boolean>;
60
88
  protected readonly canCreateFolder: Signal<boolean>;
61
89
  protected readonly canShare: Signal<boolean>;
90
+ protected readonly uploadDisabled: Signal<boolean>;
91
+ protected readonly createDisabled: Signal<boolean>;
62
92
  protected readonly currentName: Signal<string>;
63
93
  protected readonly searching: Signal<boolean>;
64
- protected readonly itemViews: Signal<readonly SdFileExplorerItemView[]>;
94
+ protected readonly itemViews: Signal<readonly SdFileExplorerItemView<T>[]>;
95
+ /** The row download / share shortcuts stay until the consumer declares `fileCommands` (even `[]`). */
96
+ protected readonly rowShortcuts: Signal<boolean>;
97
+ /** Selection actions remain caller-owned when declared, including an intentional empty array. */
98
+ protected readonly selectionActions: Signal<readonly SdFileExplorerSelectionAction<T>[]>;
99
+ /**
100
+ * Frozen snapshot of the selection handed to callbacks and actions: selected files that are still visible and
101
+ * eligible, in display order. A file that a refresh drops, or that becomes disabled, leaves it.
102
+ */
103
+ protected readonly selectedItems: Signal<readonly SdFileExplorerItem<T>[]>;
104
+ /** Selection state of the item list; `null` (no checkbox, no band) without selector or without files in view. */
105
+ protected readonly selectionView: Signal<SdFileExplorerSelectionView | null>;
106
+ /**
107
+ * Status sentence of the band, split around the number so the template can set it in semibold: "2 tệp đã chọn",
108
+ * "已选择 2 个文件". Nothing selected: `count` is 0 and `before` holds the whole sentence.
109
+ */
110
+ protected readonly selectionSummary: Signal<{
111
+ count: number;
112
+ before: string;
113
+ after: string;
114
+ }>;
115
+ /** Content of the drawer: the item's commands resolved for it now; `null` when nothing is left to show. */
116
+ protected readonly commandSheet: Signal<SdFileExplorerCommandSheetView<T> | null>;
117
+ protected readonly itemsMenuOpenId: Signal<string | null>;
118
+ protected readonly treeMenuOpenId: Signal<string | null>;
65
119
  protected readonly contentState: Signal<SdFileExplorerContentState>;
66
120
  protected readonly refreshing: Signal<boolean>;
67
121
  protected readonly errorMessage: Signal<string>;
@@ -76,30 +130,43 @@ export declare class SdFileExplorer {
76
130
  /** Breadcrumb trail plus the folder each entry navigates to. */
77
131
  protected readonly breadcrumb: Signal<{
78
132
  items: SdBreadcrumbItem[];
79
- targets: Map<SdBreadcrumbItem, SdFileExplorerItem | null>;
133
+ targets: Map<SdBreadcrumbItem, SdFileExplorerItem<T> | null>;
80
134
  }>;
81
- protected readonly treeNodes: Signal<readonly SdFileExplorerTreeNode[]>;
82
- protected readonly previewView: Signal<SdFileExplorerItemView | null>;
135
+ protected readonly treeNodes: Signal<readonly SdFileExplorerTreeNode<T>[]>;
136
+ protected readonly previewView: Signal<SdFileExplorerItemView<T> | null>;
83
137
  protected readonly previewMeta: Signal<readonly SdFileExplorerMetaRow[]>;
84
138
  protected readonly transferViews: Signal<readonly SdFileExplorerTransferView[]>;
85
139
  protected readonly transfersTitle: Signal<string>;
86
140
  protected readonly canClearTransfers: Signal<boolean>;
87
141
  constructor();
142
+ /** Moves visible files through the caller's storage callback. False includes cancellation, rejection or refresh failure. */
143
+ moveFiles(items: readonly SdFileExplorerItem<T>[], targetFolder: SdFileExplorerItem<T> | null, source?: SdFileExplorerMoveRequest<T>['source']): Promise<boolean>;
144
+ /** Cooperatively aborts the current mutation. A consumer may already have committed its storage change. */
145
+ cancelMove(): void;
146
+ /** Repeats failed listing only; never calls onMove again. */
147
+ retryMoveRefresh(): Promise<boolean>;
148
+ protected openMovePicker(items: readonly SdFileExplorerItem<T>[], event?: Event): void;
149
+ protected closeMovePicker(): void;
150
+ protected submitMoveFromEvent(event: Event): void;
151
+ protected submitMove(source?: 'menu' | 'keyboard'): Promise<void>;
152
+ protected onMoveDragStart(event: DragEvent): void;
153
+ protected onMoveDragEnd(): void;
88
154
  /**
89
155
  * Lists the current folder again and drops the cached children of folders that are neither open in the
90
- * tree nor on the current path. Re-runs the active search, if any.
156
+ * tree nor on the current path. Re-runs the active search, if any. Clears the file selection and closes the command
157
+ * drawer of the compact layout.
91
158
  */
92
159
  reload(): void;
93
- protected navigate(folder: SdFileExplorerItem | null): void;
160
+ protected navigate(folder: SdFileExplorerItem<T> | null): void;
94
161
  protected onBreadcrumb(entry: SdBreadcrumbItem): void;
95
- protected onTreeSelect(node: SdFileExplorerTreeNode): void;
96
- protected onTreeToggle(node: SdFileExplorerTreeNode): void;
97
- protected onTreeRetry(node: SdFileExplorerTreeNode): void;
162
+ protected onTreeSelect(node: SdFileExplorerTreeNode<T>): void;
163
+ protected onTreeToggle(node: SdFileExplorerTreeNode<T>): void;
164
+ protected onTreeRetry(node: SdFileExplorerTreeNode<T>): void;
98
165
  protected retryContent(): void;
99
166
  protected toggleSidebar(): void;
100
167
  protected setView(view: SdFileExplorerView): void;
101
- protected onActivate(view: SdFileExplorerItemView): void;
102
- protected openFile(item: SdFileExplorerItem): void;
168
+ protected onActivate(view: SdFileExplorerItemView<T>): void;
169
+ protected openFile(item: SdFileExplorerItem<T>): void;
103
170
  /**
104
171
  * Closes the detail drawer. Focus goes back to the row / card that opened it: `sd-side-drawer` restores the
105
172
  * previously focused element when its focus trap closes.
@@ -107,9 +174,24 @@ export declare class SdFileExplorer {
107
174
  protected closePreview(): void;
108
175
  protected retryPreview(): void;
109
176
  protected onPreviewImageError(): void;
110
- protected downloadItem(item: SdFileExplorerItem): void;
177
+ protected downloadItem(item: SdFileExplorerItem<T>): void;
111
178
  protected downloadPreview(): void;
112
179
  protected sharePreview(): void;
180
+ protected toggleSelection(item: SdFileExplorerItem<T>): void;
181
+ protected toggleSelectAll(): void;
182
+ protected clearSelection(): void;
183
+ protected openCommands(item: SdFileExplorerItem<T>, origin: CommandOrigin, trigger: HTMLElement): void;
184
+ /** The user closed the drawer (close button, `Escape`, backdrop). */
185
+ protected onCommandsClosed(): void;
186
+ /**
187
+ * Runs a command pressed in the drawer. The press is checked against the current item, definitions and states: a
188
+ * stale entry, a state the consumer changed since the last render or a second press runs nothing.
189
+ *
190
+ * The drawer closes first, at once. The command runs after the next render: by then the drawer's focus trap is gone
191
+ * and has handed focus back, so it cannot pull focus away from a dialog or a preview the command opens. Right before
192
+ * it runs, the same check is made again, and `click` receives the item as listed at that moment.
193
+ */
194
+ protected runCommand({ command, group }: SdFileExplorerSheetActivation): void;
113
195
  protected onKeywordInput(value: string): void;
114
196
  protected clearSearch(): void;
115
197
  protected onFilesPicked(input: HTMLInputElement): void;
@@ -124,12 +206,13 @@ export declare class SdFileExplorer {
124
206
  protected clearFinishedTransfers(): void;
125
207
  protected openFolderDialog(): void;
126
208
  protected closeFolderDialog(): void;
127
- protected openShare(item: SdFileExplorerItem): void;
209
+ protected openShare(item: SdFileExplorerItem<T>): void;
128
210
  protected retryShare(): void;
129
211
  protected closeShare(): void;
130
212
  protected copyShareLink(): Promise<void>;
131
213
  protected submitFolder(event: Event): Promise<void>;
132
214
  protected onEscape(event: Event): void;
133
- static ɵfac: i0.ɵɵFactoryDeclaration<SdFileExplorer, never>;
134
- static ɵcmp: i0.ɵɵComponentDeclaration<SdFileExplorer, "sd-file-explorer", never, { "option": { "alias": "option"; "required": true; "isSignal": true; }; }, { "open": "open"; }, never, never, true, never>;
215
+ static ɵfac: i0.ɵɵFactoryDeclaration<SdFileExplorer<any>, never>;
216
+ static ɵcmp: i0.ɵɵComponentDeclaration<SdFileExplorer<any>, "sd-file-explorer", never, { "option": { "alias": "option"; "required": true; "isSignal": true; }; }, { "open": "open"; }, ["columnDefs"], never, true, never>;
135
217
  }
218
+ export {};
@@ -1,3 +1,5 @@
1
+ import type { SdButtonColor, SdButtonType } from '@sdcorejs/angular/components/button';
2
+ import type { SdIconSet } from '@sdcorejs/angular/modules/icon';
1
3
  /**
2
4
  * Kind of an explorer entry. Folders can be opened and listed; files can be previewed and downloaded.
3
5
  */
@@ -5,12 +7,12 @@ export type SdFileExplorerItemKind = 'folder' | 'file';
5
7
  /**
6
8
  * One file or folder shown by `<sd-file-explorer>`.
7
9
  *
8
- * The explorer never talks to a storage API itself: every item comes from `SdFileExplorerOption.list`
10
+ * The explorer never talks to a storage API itself: every item comes from `SdFileExplorerOption<T>.list`
9
11
  * (or `search`), so map your own DTO into this shape inside the callback.
10
12
  *
11
13
  * @example
12
14
  * ```ts
13
- * const item: SdFileExplorerItem = {
15
+ * const item: SdFileExplorerItem<T> = {
14
16
  * id: 'f-42',
15
17
  * parentId: 'folder-7', // null = item sits in the root folder
16
18
  * name: 'Contract.pdf',
@@ -21,7 +23,9 @@ export type SdFileExplorerItemKind = 'folder' | 'file';
21
23
  * };
22
24
  * ```
23
25
  */
24
- export interface SdFileExplorerItem {
26
+ export interface SdFileExplorerItem<T = unknown> {
27
+ /** Caller-owned DTO, preserved by identity and never serialized by the explorer. */
28
+ data?: T;
25
29
  /** Stable id, unique across the whole tree. Used for tracking, navigation and `autoId` suffixes. */
26
30
  id: string;
27
31
  /** Id of the containing folder, or `null` when the item sits in the root folder. */
@@ -48,7 +52,7 @@ export interface SdFileExplorerItem {
48
52
  /** Image URL shown on the grid card instead of the file-type icon. Caller-owned: the explorer never revokes it. */
49
53
  thumbnailUrl?: string;
50
54
  }
51
- /** Arguments of `SdFileExplorerOption.list`. */
55
+ /** Arguments of `SdFileExplorerOption<T>.list`. */
52
56
  export interface SdFileExplorerListArgs {
53
57
  /** Folder whose direct children are requested; `null` is the root folder. */
54
58
  parentId: string | null;
@@ -59,7 +63,7 @@ export interface SdFileExplorerListArgs {
59
63
  */
60
64
  signal: AbortSignal;
61
65
  }
62
- /** Arguments of `SdFileExplorerOption.search`. */
66
+ /** Arguments of `SdFileExplorerOption<T>.search`. */
63
67
  export interface SdFileExplorerSearchArgs {
64
68
  /** Folder the user is currently viewing; `null` is the root folder. */
65
69
  parentId: string | null;
@@ -68,15 +72,15 @@ export interface SdFileExplorerSearchArgs {
68
72
  /** Aborted when a newer keyword supersedes this one, the search is cleared or the user navigates away. */
69
73
  signal: AbortSignal;
70
74
  }
71
- /** Arguments of `SdFileExplorerOption.preview`. */
72
- export interface SdFileExplorerPreviewArgs {
75
+ /** Arguments of `SdFileExplorerOption<T>.preview`. */
76
+ export interface SdFileExplorerPreviewArgs<T = unknown> {
73
77
  /** File being previewed. */
74
- item: SdFileExplorerItem;
78
+ item: SdFileExplorerItem<T>;
75
79
  /** Aborted when the detail drawer is closed or another file is opened before this one resolves. */
76
80
  signal: AbortSignal;
77
81
  }
78
82
  /**
79
- * Content returned by `SdFileExplorerOption.preview`.
83
+ * Content returned by `SdFileExplorerOption<T>.preview`.
80
84
  *
81
85
  * - `string`: a URL. Caller-owned — the explorer uses it as-is and never revokes it.
82
86
  * - `Blob` / `File`: the explorer creates an object URL when needed and revokes it when the preview closes,
@@ -101,26 +105,26 @@ export interface SdFileExplorerTransferArgs {
101
105
  */
102
106
  signal: AbortSignal;
103
107
  }
104
- /** Arguments of `SdFileExplorerOption.upload`. */
108
+ /** Arguments of `SdFileExplorerOption<T>.upload`. */
105
109
  export interface SdFileExplorerUploadArgs extends SdFileExplorerTransferArgs {
106
110
  /** File picked through the upload button or dropped onto the explorer. */
107
111
  file: File;
108
112
  /** Destination folder (the folder being viewed when the upload started); `null` is the root folder. */
109
113
  parentId: string | null;
110
114
  }
111
- /** Arguments of `SdFileExplorerOption.download`. */
112
- export interface SdFileExplorerDownloadArgs extends SdFileExplorerTransferArgs {
115
+ /** Arguments of `SdFileExplorerOption<T>.download`. */
116
+ export interface SdFileExplorerDownloadArgs<T = unknown> extends SdFileExplorerTransferArgs {
113
117
  /** File to download. */
114
- item: SdFileExplorerItem;
118
+ item: SdFileExplorerItem<T>;
115
119
  }
116
- /** Arguments of `SdFileExplorerOption.share`. */
117
- export interface SdFileExplorerShareArgs {
120
+ /** Arguments of `SdFileExplorerOption<T>.share`. */
121
+ export interface SdFileExplorerShareArgs<T = unknown> {
118
122
  /** File to share. */
119
- item: SdFileExplorerItem;
123
+ item: SdFileExplorerItem<T>;
120
124
  /** Aborted when the user closes the share dialog before the link is ready, or the explorer is destroyed. */
121
125
  signal: AbortSignal;
122
126
  }
123
- /** Arguments of `SdFileExplorerOption.createFolder`. */
127
+ /** Arguments of `SdFileExplorerOption<T>.createFolder`. */
124
128
  export interface SdFileExplorerCreateFolderArgs {
125
129
  /** Folder that receives the new folder (the folder being viewed); `null` is the root folder. */
126
130
  parentId: string | null;
@@ -129,6 +133,116 @@ export interface SdFileExplorerCreateFolderArgs {
129
133
  }
130
134
  /** Layout of the item area. */
131
135
  export type SdFileExplorerView = 'list' | 'grid';
136
+ /**
137
+ * Static or per-context state of an explorer action (`hidden`, `disabled`, `loading`).
138
+ *
139
+ * A function receives the same context as the action's `click`: the selected files for `selector.actions`, the item
140
+ * of the row, card or tree node for `fileCommands` / `folderCommands`. It is evaluated while rendering and again
141
+ * right before `click` runs; read Angular signals inside it so the explorer re-renders when the state changes.
142
+ */
143
+ export type SdFileExplorerState<T> = boolean | ((context: T) => boolean);
144
+ /** Appearance and state shared by every explorer action, flat button or group. */
145
+ export interface SdFileExplorerActionAppearance<T> {
146
+ /**
147
+ * Visible label. Without it the button is icon-only and `tooltip` is its accessible name. A menu item shows its
148
+ * `title`, or its `tooltip` when it has no title. Every definition needs a `title` or a `tooltip`.
149
+ */
150
+ title?: string;
151
+ /** Tooltip, and the accessible name of an icon-only button. */
152
+ tooltip?: string;
153
+ /** Icon before the label. A group without one shows `more_vert`. */
154
+ prefixIcon?: string;
155
+ /** Icon after the label. */
156
+ suffixIcon?: string;
157
+ /** Icon set of `prefixIcon` / `suffixIcon`. Defaults to the app icon provider. */
158
+ fontSet?: SdIconSet;
159
+ /**
160
+ * Semantic color, as on `sd-button` (`primary`, `secondary`, `info`, `success`, `warning`, `error`, `black`). Use
161
+ * `'error'` for destructive actions. Unset: `primary` in `selector.actions`, `secondary` in commands; menu items stay
162
+ * neutral. In the compact command drawer it colors the icons only, like on menu items, and unset stays neutral.
163
+ */
164
+ color?: SdButtonColor;
165
+ /**
166
+ * `sd-button` variant: `fill`, `light`, `outline` or `text`. Desktop buttons only: ignored for menu items and in the
167
+ * compact command drawer. Unset: `light` for a flat selector action, `text` for a selector group trigger and for
168
+ * every file / folder command.
169
+ */
170
+ type?: SdButtonType;
171
+ /** Removes the action. A group whose children are all hidden is removed too. */
172
+ hidden?: SdFileExplorerState<T>;
173
+ /** Keeps the action visible but blocks it. */
174
+ disabled?: SdFileExplorerState<T>;
175
+ /** Shows a spinner and blocks the action while your own work runs. A loading menu item is also disabled. */
176
+ loading?: SdFileExplorerState<T>;
177
+ }
178
+ /** Legacy callable leaf contract. Consumers may extend this interface and invoke `click` directly. */
179
+ export interface SdFileExplorerActionLeaf<T> extends SdFileExplorerActionAppearance<T> {
180
+ click: (context: T) => void;
181
+ onClick?: never;
182
+ children?: never;
183
+ }
184
+ /** A configured leaf accepts the canonical `onClick` callback or the legacy callable `click` contract. */
185
+ export type SdFileExplorerActionLeafDefinition<T> = SdFileExplorerActionLeaf<T> | (SdFileExplorerActionAppearance<T> & {
186
+ onClick: (context: T) => void;
187
+ click?: never;
188
+ children?: never;
189
+ });
190
+ /** Button that only opens a menu of leaves. Groups are one level deep. */
191
+ export interface SdFileExplorerActionGroup<T> extends SdFileExplorerActionAppearance<T> {
192
+ /** Menu items in display order. Leaves only: a group cannot contain another group. */
193
+ children: readonly SdFileExplorerActionLeaf<T>[];
194
+ click?: never;
195
+ onClick?: never;
196
+ }
197
+ /** Configured one-level menu; both canonical and legacy leaf callbacks are accepted. */
198
+ export interface SdFileExplorerActionGroupDefinition<T> extends SdFileExplorerActionAppearance<T> {
199
+ children: readonly SdFileExplorerActionLeafDefinition<T>[];
200
+ click?: never;
201
+ onClick?: never;
202
+ }
203
+ /**
204
+ * One entry of `selector.actions`, `fileCommands` or `folderCommands`: a leaf with `click`, or a group with
205
+ * `children`. Siblings render in the declared order; the explorer never moves them into an overflow menu.
206
+ */
207
+ export type SdFileExplorerAction<T> = SdFileExplorerActionLeafDefinition<T> | SdFileExplorerActionGroupDefinition<T>;
208
+ /** Action on the selected files. `click` receives a frozen snapshot of the selection. */
209
+ export type SdFileExplorerSelectionAction<T = unknown> = SdFileExplorerAction<readonly SdFileExplorerItem<T>[]>;
210
+ /** Action on one file or folder. `click` receives the item exactly as returned by `list` or `search`. */
211
+ export type SdFileExplorerCommand<T = unknown> = SdFileExplorerAction<SdFileExplorerItem<T>>;
212
+ /**
213
+ * Multi-file selection of `<sd-file-explorer>`.
214
+ *
215
+ * Only the files visible in the current folder or search results can be selected — never folders, never items of
216
+ * other folders. The selection survives switching between list and grid and opening a file, and is cleared when the
217
+ * folder, the search keyword or `list` changes, or on `reload()`. A file that a refresh drops or that `disabled`
218
+ * starts locking leaves the selection without a callback and is not selected again when it comes back.
219
+ */
220
+ export interface SdFileExplorerSelector<T = unknown> {
221
+ /** Allows selection when useful actions or an explicit picker contract exist. @defaultValue `true` */
222
+ visible?: boolean;
223
+ /**
224
+ * `actions` requires a usable configured selection action; `picker` deliberately allows selection without actions.
225
+ * When omitted, existing `onSelect` / `onSelectAll` callbacks retain picker behavior; other selectors use `actions`.
226
+ */
227
+ mode?: 'actions' | 'picker';
228
+ /**
229
+ * Actions on the selected files, shown in the selection band while at least one file is selected. Without `type`,
230
+ * a flat action is `light` and a group trigger `text`; without `color`, both are `primary`.
231
+ * Omitted in action mode: configured move/share/download callbacks provide the default actions. An explicit `[]`
232
+ * suppresses those defaults. Static hidden actions and empty groups do not enable selection; disabled/loading
233
+ * actions still do. A `hidden` predicate controls the action for the current selection, without removing checkboxes
234
+ * or clearing intermediate selections. Withdraw the action configuration or use `visible: false` to disable selection.
235
+ */
236
+ actions?: readonly SdFileExplorerSelectionAction<T>[];
237
+ /** Files for which it returns `true` show a disabled checkbox and are left out of "select all". */
238
+ disabled?: (item: SdFileExplorerItem<T>) => boolean;
239
+ /** Called after a file checkbox is toggled, with the file and the new selection. */
240
+ onSelect?: (item: SdFileExplorerItem<T>, selectedItems: readonly SdFileExplorerItem<T>[]) => void;
241
+ /** Called once after the select-all checkbox selects every eligible file or deselects them all (`[]`). */
242
+ onSelectAll?: (selectedItems: readonly SdFileExplorerItem<T>[]) => void;
243
+ /** Called once when a non-empty selection is cleared: the band's clear button, or a folder / search / `list` change or `reload()`. */
244
+ onClear?: () => void;
245
+ }
132
246
  /**
133
247
  * Configuration of `<sd-file-explorer>`.
134
248
  *
@@ -142,7 +256,7 @@ export type SdFileExplorerView = 'list' | 'grid';
142
256
  *
143
257
  * @example
144
258
  * ```ts
145
- * readonly option: SdFileExplorerOption = {
259
+ * readonly option: SdFileExplorerOption<T> = {
146
260
  * title: 'My files',
147
261
  * list: ({ parentId, signal }) => firstValueFrom(this.api.children(parentId, { signal })),
148
262
  * search: ({ parentId, keyword }) => firstValueFrom(this.api.search(parentId, keyword)),
@@ -154,14 +268,22 @@ export type SdFileExplorerView = 'list' | 'grid';
154
268
  * };
155
269
  * ```
156
270
  */
157
- export interface SdFileExplorerOption {
271
+ export interface SdFileExplorerOption<T = unknown> {
272
+ /** Canonical grouped callbacks; an explicit group wins over its legacy root callback. */
273
+ capabilities?: SdFileExplorerCapabilities<T>;
274
+ /** Opt-in file move; caller performs the storage mutation. */
275
+ move?: {
276
+ movable?: SdFileExplorerState<SdFileExplorerMoveRequest<T>>;
277
+ onMove: (request: SdFileExplorerMoveRequest<T>) => boolean | void | Promise<boolean | void>;
278
+ };
279
+ dataSource?: never;
158
280
  /**
159
281
  * Returns the direct children (files and folders) of a folder. Required.
160
282
  *
161
283
  * Called lazily: once per folder when it is first opened or expanded in the tree, then cached until
162
284
  * `reload()` or a successful upload / folder creation in that folder. `parentId` is `null` for the root.
163
285
  */
164
- list: (args: SdFileExplorerListArgs) => SdFileExplorerItem[] | Promise<SdFileExplorerItem[]>;
286
+ list: (args: SdFileExplorerListArgs) => SdFileExplorerItem<T>[] | Promise<SdFileExplorerItem<T>[]>;
165
287
  /**
166
288
  * Server-side search inside the current folder. Called 300 ms after the user stops typing, and only for a
167
289
  * non-empty keyword; stale requests are aborted and their results ignored.
@@ -169,7 +291,7 @@ export interface SdFileExplorerOption {
169
291
  * When omitted, the search box filters the already loaded children of the current folder by name
170
292
  * (case- and Vietnamese-accent-insensitive) without calling any callback.
171
293
  */
172
- search?: (args: SdFileExplorerSearchArgs) => SdFileExplorerItem[] | Promise<SdFileExplorerItem[]>;
294
+ search?: (args: SdFileExplorerSearchArgs) => SdFileExplorerItem<T>[] | Promise<SdFileExplorerItem<T>[]>;
173
295
  /**
174
296
  * Resolves the content shown in the detail drawer when a file is opened.
175
297
  *
@@ -177,7 +299,7 @@ export interface SdFileExplorerOption {
177
299
  * preview a PDF do not download PDF.js). Return `null`/`undefined` — or omit the callback — to show the
178
300
  * "no preview" fallback. Other formats always show the fallback with a download button.
179
301
  */
180
- preview?: (args: SdFileExplorerPreviewArgs) => SdFileExplorerPreviewSource | null | undefined | Promise<SdFileExplorerPreviewSource | null | undefined>;
302
+ preview?: (args: SdFileExplorerPreviewArgs<T>) => SdFileExplorerPreviewSource | null | undefined | Promise<SdFileExplorerPreviewSource | null | undefined>;
181
303
  /**
182
304
  * Downloads a file. Enables the download buttons in list, grid and preview.
183
305
  *
@@ -185,7 +307,7 @@ export interface SdFileExplorerOption {
185
307
  * - Return nothing: you handed the download to the browser yourself (for example `window.open(url)` or an
186
308
  * anchor with `download`). The transfer is then marked "handed to the browser" without a fake percentage.
187
309
  */
188
- download?: (args: SdFileExplorerDownloadArgs) => Blob | void | Promise<Blob | void>;
310
+ download?: (args: SdFileExplorerDownloadArgs<T>) => Blob | void | Promise<Blob | void>;
189
311
  /**
190
312
  * Creates a shareable link for a file and returns its URL. Enables the "Share" buttons (list rows and
191
313
  * detail drawer).
@@ -194,7 +316,7 @@ export interface SdFileExplorerOption {
194
316
  * explicit click, so it works even when the callback takes a while. Throw (or reject) to show the error
195
317
  * `message` with a retry button. Expiry, permissions or audience stay in your API.
196
318
  */
197
- share?: (args: SdFileExplorerShareArgs) => string | Promise<string>;
319
+ share?: (args: SdFileExplorerShareArgs<T>) => string | Promise<string>;
198
320
  /**
199
321
  * Uploads one file into `parentId`. Enables the upload button and drag-and-drop.
200
322
  *
@@ -202,12 +324,12 @@ export interface SdFileExplorerOption {
202
324
  * destination folder is listed again. Throw (or reject) to mark the transfer as failed — the error `message`
203
325
  * is shown as the failure reason and the user can retry.
204
326
  */
205
- upload?: (args: SdFileExplorerUploadArgs) => SdFileExplorerItem | void | Promise<SdFileExplorerItem | void>;
327
+ upload?: (args: SdFileExplorerUploadArgs) => SdFileExplorerItem<T> | void | Promise<SdFileExplorerItem<T> | void>;
206
328
  /**
207
329
  * Creates a folder inside the current folder. Enables the "New folder" button.
208
330
  * After success the current folder is listed again. Throw (or reject) to keep the dialog open with the error.
209
331
  */
210
- createFolder?: (args: SdFileExplorerCreateFolderArgs) => SdFileExplorerItem | void | Promise<SdFileExplorerItem | void>;
332
+ createFolder?: (args: SdFileExplorerCreateFolderArgs) => SdFileExplorerItem<T> | void | Promise<SdFileExplorerItem<T> | void>;
211
333
  /** Heading shown in the explorer header. When omitted the header shows only search and upload. */
212
334
  title?: string;
213
335
  /** Secondary line under `title`. Ignored when `title` is omitted. */
@@ -216,6 +338,22 @@ export interface SdFileExplorerOption {
216
338
  rootLabel?: string;
217
339
  /** Initial layout of the item area. The user can switch afterwards. @defaultValue `'list'` */
218
340
  defaultView?: SdFileExplorerView;
341
+ /**
342
+ * Multi-file selection: checkboxes on files, a select-all checkbox in the list header (above the grid) and a
343
+ * selection band with `selector.actions`. See `SdFileExplorerSelector<T>`.
344
+ */
345
+ selector?: SdFileExplorerSelector<T>;
346
+ /**
347
+ * Actions on one file, in list rows and grid cards — in the compact layout, in the command drawer each row or card
348
+ * opens. Declaring it — even as `[]` — replaces the row download and share shortcuts, in that drawer too; the detail
349
+ * drawer keeps its own Download and Share buttons.
350
+ */
351
+ fileCommands?: readonly SdFileExplorerCommand<T>[];
352
+ /**
353
+ * Actions on one folder, in list rows, grid cards and the folder tree (never on the root) — in the compact layout,
354
+ * in the command drawer each row, card or tree node opens.
355
+ */
356
+ folderCommands?: readonly SdFileExplorerCommand<T>[];
219
357
  /** E2E scope. Produces `data-autoid="components-file-explorer-{autoId}"` and derived child ids. */
220
358
  autoId?: string;
221
359
  }
@@ -226,11 +364,11 @@ export interface SdFileExplorerOption {
226
364
  * grid or search results). Not emitted for folders, which navigate instead, nor when the detail drawer
227
365
  * re-renders or reloads.
228
366
  */
229
- export interface SdFileExplorerOpenEvent {
367
+ export interface SdFileExplorerOpenEvent<T = unknown> {
230
368
  /** The file that was opened. */
231
- item: SdFileExplorerItem;
369
+ item: SdFileExplorerItem<T>;
232
370
  /** Folders from the root (excluded) down to the folder being viewed when the file was opened. */
233
- path: readonly SdFileExplorerItem[];
371
+ path: readonly SdFileExplorerItem<T>[];
234
372
  }
235
373
  /** Direction of a transfer shown in the transfer panel. */
236
374
  export type SdFileExplorerTransferDirection = 'upload' | 'download';
@@ -266,3 +404,46 @@ export interface SdFileExplorerTransfer {
266
404
  /** Reason of the failure when `status` is `'error'`. */
267
405
  readonly error?: unknown;
268
406
  }
407
+ /** File-only, consumer-controlled move. Abort is cooperative, not rollback. */
408
+ export interface SdFileExplorerMoveRequest<T = unknown> {
409
+ readonly items: readonly SdFileExplorerItem<T>[];
410
+ readonly targetFolder: SdFileExplorerItem<T> | null;
411
+ readonly source: 'drag' | 'menu' | 'keyboard' | 'api';
412
+ readonly signal: AbortSignal;
413
+ }
414
+ export interface SdFileExplorerCapabilities<T = unknown> {
415
+ share?: {
416
+ shareable?: SdFileExplorerState<SdFileExplorerItem<T>>;
417
+ onShare: NonNullable<SdFileExplorerOption<T>['share']>;
418
+ };
419
+ download?: {
420
+ downloadable?: SdFileExplorerState<SdFileExplorerItem<T>>;
421
+ onDownload: NonNullable<SdFileExplorerOption<T>['download']>;
422
+ };
423
+ preview?: {
424
+ previewable?: SdFileExplorerState<SdFileExplorerItem<T>>;
425
+ onPreview: NonNullable<SdFileExplorerOption<T>['preview']>;
426
+ };
427
+ upload?: {
428
+ uploadable?: SdFileExplorerState<{
429
+ parentId: string | null;
430
+ }>;
431
+ onUpload: NonNullable<SdFileExplorerOption<T>['upload']>;
432
+ };
433
+ createFolder?: {
434
+ creatable?: SdFileExplorerState<{
435
+ parentId: string | null;
436
+ }>;
437
+ onCreateFolder: NonNullable<SdFileExplorerOption<T>['createFolder']>;
438
+ };
439
+ }
440
+ /** New source-only surface. Legacy source callbacks remain callable on SdFileExplorerOption. */
441
+ export interface SdFileExplorerDataSourceOption<T = unknown> extends Omit<SdFileExplorerOption<T>, 'list' | 'search' | 'dataSource'> {
442
+ dataSource: {
443
+ onList: SdFileExplorerOption<T>['list'];
444
+ onSearch?: SdFileExplorerOption<T>['search'];
445
+ };
446
+ list?: never;
447
+ search?: never;
448
+ }
449
+ export type SdFileExplorerConfig<T = unknown> = SdFileExplorerOption<T> | SdFileExplorerDataSourceOption<T>;
@@ -47,6 +47,6 @@ export declare function sdFileExplorerIsAbort(error: unknown): boolean;
47
47
  * Folders first, then files. Within each group the order returned by the callback is kept, so the
48
48
  * consumer (or its API) decides how items are sorted.
49
49
  */
50
- export declare function sdFileExplorerFoldersFirst(items: readonly SdFileExplorerItem[]): SdFileExplorerItem[];
50
+ export declare function sdFileExplorerFoldersFirst<T>(items: readonly SdFileExplorerItem<T>[]): SdFileExplorerItem<T>[];
51
51
  /** Element-safe id fragment for `autoId` / DOM ids. */
52
52
  export declare function sdFileExplorerSafeId(value: string): string;