@classic-homes/files-svelte 0.5.0 → 0.6.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.
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  Svelte 5 network-drive file browser for Classic Theme.
4
4
 
5
- - `FileBrowser`: Explorer-style folder pane (drives, open folder's parents expanded, resizable), root picker, breadcrumbs, paged listing, filter, hidden files, preview dialog, download, details, every error state, offline banner
5
+ - `FileBrowser`: Explorer-style folder pane (drives, open folder's parents expanded, resizable), root picker, breadcrumbs, paged listing, filter, hidden files, preview in a dialog or in the pane, download, details, every error state, offline banner
6
6
  - Building blocks: `FileTree`, `FileList`, `FileBreadcrumbs`, `FileIcon`, `FilePreview`, `FileDetails`, `FileErrorState`
7
7
  - Previews reuse [`@classic-homes/viewer-svelte`](../viewer-svelte): pass a `viewers` registry of lazy imports
8
8
  - Re-exports the [`@classic-homes/files-core`](../files-core) sources and helpers
@@ -25,6 +25,68 @@ Svelte 5 network-drive file browser for Classic Theme.
25
25
  <FileBrowser {source} {viewers} class="h-[80vh]" />
26
26
  ```
27
27
 
28
+ ### The header
29
+
30
+ From 768px up the header is one row: breadcrumbs (the drive's description
31
+ trailing them as muted text that truncates), the filter, "Show hidden files",
32
+ any write `toolbar` and Refresh. Below 768px it is two rows: a "Folders" button
33
+ (icon-only below 640px) and the breadcrumbs, then the filter, the `toolbar` and a
34
+ ⋯ "More options" menu holding "Show hidden files" (a checkable item) and
35
+ Refresh. On phones the description is the root crumb's tooltip, and the drives
36
+ are reached through the Folders sheet, so the drive picker only shows with
37
+ `navigationPane={false}` (when there is more than one drive). `/` focuses the
38
+ filter and Esc clears it at any width.
39
+
40
+ ### Opening files in the pane
41
+
42
+ By default a file opens in a modal dialog. With `preview="pane"` it opens in place
43
+ of the list instead: the folder tree on the left focuses on the branch you are
44
+ in (the drive, each folder down to the open one, expanded, then that folder's
45
+ subfolders and files as the list showed them, same filter and sort; siblings of
46
+ the folders above are left out). Long file names truncate in the middle so the
47
+ end stays visible (`May 2026 Cost…es-FHN.xlsx`; hover for the full name). The
48
+ open file is marked and kept in view; click
49
+ another file (or arrow onto it) to switch, or click a folder on the branch to
50
+ close the file and go there (the open folder itself just closes it). The
51
+ preview header carries the name, previous / next, Details, Download and Close,
52
+ on one row at any width (the name truncates; below 640px Details and Download are
53
+ icons). Esc or Close return to the folder; changing folder or drive closes the
54
+ file. The filter box hides while a file is open, so an active filter shows as a
55
+ strip above the branch with a Clear button (the file stays open). Below 768px
56
+ the document fills the browser and a "Files" button opens the branch in a sheet
57
+ (its tooltip and accessible description name the folder, e.g. "Files in Land
58
+ Development / 105 BREWERY").
59
+
60
+ Bind `file` (the open file's name in the current folder) to keep it in the URL.
61
+ Setting it opens that file, also when it is past the first page (looked up with
62
+ `source.info()`). A name that doesn't resolve to a file in the folder (missing, a
63
+ folder, or containing `/`) clears the binding once that is certain:
64
+ `onfilechange(undefined)`, and in pane mode `onnavigate` without `file`, so a stale
65
+ `?file=` drops out of the URL. A transient lookup error (network, 401) goes to
66
+ `onerror` instead. In pane mode `onnavigate` also fires when a file opens, changes
67
+ or closes, with `file` set; `onfilechange` reports it in both modes.
68
+
69
+ ```svelte
70
+ <FileBrowser
71
+ {source}
72
+ {viewers}
73
+ preview="pane"
74
+ frame={false}
75
+ bind:rootId
76
+ bind:path
77
+ bind:file
78
+ onnavigate={({ rootId, path, file }) => updateUrl({ rootId, path, file })}
79
+ class="h-full"
80
+ />
81
+ ```
82
+
83
+ `frame={false}` drops the browser's rounded border for an edge-to-edge layout.
84
+ The building blocks take the same pieces: `FileList` has `compact` (name column
85
+ only, no header) and `current` (the open file's path: `aria-current`, highlighted,
86
+ kept in view) for a side list of your own; `FilePreview` has `onclose` (a trailing Close button), `onprev` / `onnext`
87
+ (the buttons show when either is set, the missing one disabled) and a `start`
88
+ snippet for extra controls before the name.
89
+
28
90
  Add `./node_modules/@classic-homes/files-svelte/dist/**/*.{js,svelte}` to your Tailwind `content`. Read-only for now: write slots (`toolbar`, `rowActions`) render only when the source implements writes and the root's `canWrite` is true.
29
91
 
30
92
  Docs: `/docs/files/file-browser`; demo: `/examples/file-browser`.
@@ -0,0 +1,278 @@
1
+ <!--
2
+ @component
3
+ Internal: the left pane while a document is open. The folder tree, focused on
4
+ the branch the user is in: the drive, each folder down to the current one
5
+ (expanded), and the current folder's entries as the list shows them. Built
6
+ from what the browser already has, so it never loads anything itself.
7
+ -->
8
+ <script lang="ts">
9
+ import { tick } from 'svelte';
10
+ import { Button, Icon } from '@classic-homes/theme-svelte';
11
+ import { pathSegments, type FileEntry } from '@classic-homes/files-core';
12
+ import FileIcon from './FileIcon.svelte';
13
+ import {
14
+ noteIndent,
15
+ treeChevronClass,
16
+ treeIndent,
17
+ treeRowClass,
18
+ TREE_CLASS,
19
+ TREE_NOTE_CLASS,
20
+ } from './tree-rows.js';
21
+ import { cn, splitNameTail } from './utils.js';
22
+
23
+ interface Props {
24
+ /** Label of the drive (level 1). */
25
+ rootLabel: string;
26
+ /** Current folder, root-relative and normalized (`''` = the drive). */
27
+ path: string;
28
+ /** The current folder's entries, in display order. */
29
+ entries: FileEntry[];
30
+ /** Path of the open file: marked `aria-current`, highlighted and kept in view. */
31
+ current?: string;
32
+ /** The folder's first page is loading. */
33
+ loading?: boolean;
34
+ hasMore?: boolean;
35
+ loadingMore?: boolean;
36
+ onloadmore?: () => void;
37
+ /** The drive (`''`), a folder on the branch, or a subfolder was activated. */
38
+ onfolder?: (path: string) => void;
39
+ /** A file was activated (click, Enter). */
40
+ onfile?: (entry: FileEntry) => void;
41
+ /** The arrow keys (or Home / End) moved onto a file. */
42
+ onstep?: (entry: FileEntry) => void;
43
+ /** Shown under the folder when it has no entries. */
44
+ emptyText?: string;
45
+ /** Explanation for links. */
46
+ linkMessage?: string;
47
+ label?: string;
48
+ class?: string;
49
+ }
50
+
51
+ let {
52
+ rootLabel,
53
+ path,
54
+ entries,
55
+ current,
56
+ loading = false,
57
+ hasMore = false,
58
+ loadingMore = false,
59
+ onloadmore,
60
+ onfolder,
61
+ onfile,
62
+ onstep,
63
+ emptyText = 'This folder is empty',
64
+ linkMessage = "This is a shortcut to another location and can't be opened here.",
65
+ label = 'Files',
66
+ class: className,
67
+ }: Props = $props();
68
+
69
+ interface Row {
70
+ /** The row's path; the drive is `''`. Unique: entries sit below every folder on the branch. */
71
+ path: string;
72
+ name: string;
73
+ level: number;
74
+ /** Drive or a folder on the branch (shown expanded). */
75
+ branch: boolean;
76
+ entry?: FileEntry;
77
+ }
78
+
79
+ const segments = $derived.by(() => {
80
+ try {
81
+ return pathSegments(path);
82
+ } catch {
83
+ return [];
84
+ }
85
+ });
86
+ const childLevel = $derived(segments.length + 2);
87
+
88
+ const rows = $derived.by<Row[]>(() => [
89
+ { path: '', name: rootLabel, level: 1, branch: true },
90
+ ...segments.map((s, i) => ({ path: s.path, name: s.name, level: i + 2, branch: true })),
91
+ // Subfolders first, then files: as the tree lists folders, in the list's order.
92
+ ...[...entries.filter((e) => e.type === 'dir'), ...entries.filter((e) => e.type !== 'dir')].map(
93
+ (e) => ({ path: e.path, name: e.name, level: childLevel, branch: false, entry: e })
94
+ ),
95
+ ]);
96
+
97
+ let tree = $state<HTMLElement>();
98
+ let focusedPath = $state<string>();
99
+
100
+ const tabPath = $derived.by(() => {
101
+ if (focusedPath !== undefined && rows.some((r) => r.path === focusedPath)) return focusedPath;
102
+ if (current !== undefined && rows.some((r) => r.path === current)) return current;
103
+ return segments.at(-1)?.path ?? '';
104
+ });
105
+
106
+ function el(p: string | undefined): HTMLElement | null {
107
+ if (!tree || p === undefined) return null;
108
+ for (const node of tree.querySelectorAll<HTMLElement>('[role="treeitem"]')) {
109
+ if (node.dataset.path === p) return node;
110
+ }
111
+ return null;
112
+ }
113
+
114
+ /** Focus the open file's row (or the current folder's). */
115
+ export async function focus() {
116
+ focusedPath = undefined;
117
+ await tick();
118
+ el(tabPath)?.focus();
119
+ }
120
+
121
+ async function focusRow(row: Row | undefined, step: boolean) {
122
+ if (!row) return;
123
+ focusedPath = row.path;
124
+ if (step && row.entry?.type === 'file' && row.path !== current) onstep?.(row.entry);
125
+ await tick();
126
+ const node = el(row.path);
127
+ node?.focus();
128
+ node?.scrollIntoView({ block: 'nearest' });
129
+ }
130
+
131
+ function activate(row: Row) {
132
+ focusedPath = row.path;
133
+ if (!row.entry || row.entry.type === 'dir') onfolder?.(row.path);
134
+ else if (row.entry.type === 'file') onfile?.(row.entry);
135
+ // Links are listed, never opened.
136
+ }
137
+
138
+ function onkeydown(event: KeyboardEvent, row: Row) {
139
+ const index = rows.findIndex((r) => r.path === row.path);
140
+ switch (event.key) {
141
+ case 'ArrowDown':
142
+ event.preventDefault();
143
+ void focusRow(rows[index + 1], true);
144
+ break;
145
+ case 'ArrowUp':
146
+ if (event.altKey) return;
147
+ event.preventDefault();
148
+ void focusRow(rows[index - 1], true);
149
+ break;
150
+ case 'Home':
151
+ event.preventDefault();
152
+ void focusRow(rows[0], true);
153
+ break;
154
+ case 'End':
155
+ event.preventDefault();
156
+ void focusRow(rows[rows.length - 1], true);
157
+ break;
158
+ case 'ArrowRight':
159
+ // Into the branch; a collapsed subfolder only opens with Enter (it closes the document).
160
+ event.preventDefault();
161
+ if (row.branch && rows[index + 1]?.level === row.level + 1)
162
+ void focusRow(rows[index + 1], false);
163
+ break;
164
+ case 'ArrowLeft':
165
+ event.preventDefault();
166
+ for (let i = index - 1; i >= 0; i--) {
167
+ if (rows[i].level === row.level - 1) {
168
+ void focusRow(rows[i], false);
169
+ break;
170
+ }
171
+ }
172
+ break;
173
+ case 'Enter':
174
+ case ' ':
175
+ event.preventDefault();
176
+ activate(row);
177
+ break;
178
+ }
179
+ }
180
+
181
+ // Keep the open file in view (a long folder, or a file opened from elsewhere).
182
+ $effect(() => {
183
+ void rows;
184
+ if (current !== undefined) el(current)?.scrollIntoView({ block: 'nearest' });
185
+ });
186
+
187
+ /** "Load more" clicked: move to the first new row once it lands (the button may go). */
188
+ let focusFrom = $state<number>();
189
+ function loadMoreClicked() {
190
+ focusFrom = entries.length;
191
+ onloadmore?.();
192
+ }
193
+ $effect(() => {
194
+ const from = focusFrom;
195
+ if (from === undefined || loadingMore) return;
196
+ focusFrom = undefined;
197
+ const first = entries[from];
198
+ if (first)
199
+ void focusRow(
200
+ rows.find((r) => r.path === first.path),
201
+ false
202
+ );
203
+ });
204
+ </script>
205
+
206
+ <div class={cn('relative', className)} data-file-branch>
207
+ <ul bind:this={tree} role="tree" aria-label={label} class={TREE_CLASS}>
208
+ {#each rows as row (row.path)}
209
+ {@const isCurrent = current !== undefined && row.path === current}
210
+ {@const isLink = row.entry?.type === 'link'}
211
+ {@const isDir = !row.entry || row.entry.type === 'dir'}
212
+ {@const split = isDir ? null : splitNameTail(row.name)}
213
+ <li
214
+ role="treeitem"
215
+ data-path={row.path}
216
+ data-type={row.entry?.type ?? 'dir'}
217
+ aria-level={row.level}
218
+ aria-expanded={row.branch ? true : isDir ? false : undefined}
219
+ aria-selected={isCurrent}
220
+ aria-current={isCurrent ? 'true' : undefined}
221
+ aria-disabled={isLink ? 'true' : undefined}
222
+ tabindex={row.path === tabPath ? 0 : -1}
223
+ class={treeRowClass({
224
+ current: isCurrent,
225
+ hidden: row.entry?.hidden,
226
+ disabled: isLink,
227
+ })}
228
+ style:padding-left={treeIndent(row.level)}
229
+ title={isLink ? linkMessage : row.name}
230
+ onclick={() => activate(row)}
231
+ onkeydown={(e) => onkeydown(e, row)}
232
+ onfocus={() => (focusedPath = row.path)}
233
+ >
234
+ <span class={treeChevronClass(!isDir)} aria-hidden="true">
235
+ <Icon name={row.branch ? 'chevron-down' : 'chevron-right'} size={14} />
236
+ </span>
237
+ {#if row.level === 1}
238
+ <Icon name="home" size={16} class="shrink-0 text-muted-foreground" />
239
+ {:else if !row.entry}
240
+ <FileIcon type="dir" size={16} />
241
+ {:else}
242
+ <FileIcon name={row.entry.name} type={row.entry.type} size={16} />
243
+ {/if}
244
+ {#if split}
245
+ <!-- Middle truncation: the head takes the ellipsis, the tail (…-FHN.xlsx) stays.
246
+ Screen readers get the name once, whole. -->
247
+ <span class="flex min-w-0" aria-hidden="true" data-name-split>
248
+ <span class="min-w-0 truncate">{split.head}</span><span
249
+ class="shrink-0 whitespace-nowrap">{split.tail}</span
250
+ >
251
+ </span>
252
+ <span class="sr-only">{row.name}</span>
253
+ {:else}
254
+ <span class="truncate">{row.name}</span>
255
+ {/if}
256
+ {#if row.entry?.hidden}
257
+ <span class="sr-only">(hidden)</span>
258
+ {/if}
259
+ </li>
260
+ {/each}
261
+ {#if loading && entries.length === 0}
262
+ <li role="none" style:padding-left={noteIndent(childLevel)} class={TREE_NOTE_CLASS}>
263
+ Loading…
264
+ </li>
265
+ {:else if entries.length === 0}
266
+ <li role="none" style:padding-left={noteIndent(childLevel)} class={TREE_NOTE_CLASS}>
267
+ {emptyText}
268
+ </li>
269
+ {/if}
270
+ </ul>
271
+ {#if hasMore}
272
+ <div class="py-2" style:padding-left={noteIndent(childLevel)}>
273
+ <Button variant="outline" size="sm" loading={loadingMore} onclick={loadMoreClicked}>
274
+ Load more
275
+ </Button>
276
+ </div>
277
+ {/if}
278
+ </div>
@@ -0,0 +1,39 @@
1
+ import { type FileEntry } from '@classic-homes/files-core';
2
+ interface Props {
3
+ /** Label of the drive (level 1). */
4
+ rootLabel: string;
5
+ /** Current folder, root-relative and normalized (`''` = the drive). */
6
+ path: string;
7
+ /** The current folder's entries, in display order. */
8
+ entries: FileEntry[];
9
+ /** Path of the open file: marked `aria-current`, highlighted and kept in view. */
10
+ current?: string;
11
+ /** The folder's first page is loading. */
12
+ loading?: boolean;
13
+ hasMore?: boolean;
14
+ loadingMore?: boolean;
15
+ onloadmore?: () => void;
16
+ /** The drive (`''`), a folder on the branch, or a subfolder was activated. */
17
+ onfolder?: (path: string) => void;
18
+ /** A file was activated (click, Enter). */
19
+ onfile?: (entry: FileEntry) => void;
20
+ /** The arrow keys (or Home / End) moved onto a file. */
21
+ onstep?: (entry: FileEntry) => void;
22
+ /** Shown under the folder when it has no entries. */
23
+ emptyText?: string;
24
+ /** Explanation for links. */
25
+ linkMessage?: string;
26
+ label?: string;
27
+ class?: string;
28
+ }
29
+ /**
30
+ * Internal: the left pane while a document is open. The folder tree, focused on
31
+ * the branch the user is in: the drive, each folder down to the current one
32
+ * (expanded), and the current folder's entries as the list shows them. Built
33
+ * from what the browser already has, so it never loads anything itself.
34
+ */
35
+ declare const FileBranch: import("svelte").Component<Props, {
36
+ focus: () => Promise<void>;
37
+ }, "">;
38
+ type FileBranch = ReturnType<typeof FileBranch>;
39
+ export default FileBranch;
@@ -6,6 +6,8 @@
6
6
  interface Props {
7
7
  /** Label of the root crumb, e.g. the drive's name. */
8
8
  rootLabel: string;
9
+ /** Tooltip (`title`) on the root crumb, e.g. the drive's description. */
10
+ rootTitle?: string;
9
11
  /** Current folder, root-relative. */
10
12
  path: string;
11
13
  /** Called with the crumb's path (`''` for the root). */
@@ -19,6 +21,7 @@
19
21
 
20
22
  let {
21
23
  rootLabel,
24
+ rootTitle,
22
25
  path,
23
26
  onnavigate,
24
27
  maxItems = 4,
@@ -59,12 +62,13 @@
59
62
  <span
60
63
  aria-current="page"
61
64
  class="inline-flex items-center gap-1.5 px-1.5 py-1 font-medium text-foreground"
65
+ title={rootTitle}
62
66
  >
63
67
  <Icon name="home" size={16} />
64
68
  {rootLabel}
65
69
  </span>
66
70
  {:else}
67
- <button type="button" class={crumbClass} onclick={() => onnavigate?.('')}>
71
+ <button type="button" class={crumbClass} title={rootTitle} onclick={() => onnavigate?.('')}>
68
72
  <Icon name="home" size={16} />
69
73
  <span class="truncate">{rootLabel}</span>
70
74
  </button>
@@ -1,6 +1,8 @@
1
1
  interface Props {
2
2
  /** Label of the root crumb, e.g. the drive's name. */
3
3
  rootLabel: string;
4
+ /** Tooltip (`title`) on the root crumb, e.g. the drive's description. */
5
+ rootTitle?: string;
4
6
  /** Current folder, root-relative. */
5
7
  path: string;
6
8
  /** Called with the crumb's path (`''` for the root). */