@classic-homes/files-svelte 0.6.0 → 0.6.2

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
@@ -25,6 +25,18 @@ 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
+
28
40
  ### Opening files in the pane
29
41
 
30
42
  By default a file opens in a modal dialog. With `preview="pane"` it opens in place
@@ -41,7 +53,9 @@ on one row at any width (the name truncates; below 640px Details and Download ar
41
53
  icons). Esc or Close return to the folder; changing folder or drive closes the
42
54
  file. The filter box hides while a file is open, so an active filter shows as a
43
55
  strip above the branch with a Clear button (the file stays open). Below 768px
44
- the document fills the browser and a "Files" button opens the branch in a sheet.
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").
45
59
 
46
60
  Bind `file` (the open file's name in the current folder) to keep it in the URL.
47
61
  Setting it opens that file, also when it is past the first page (looked up with
@@ -52,6 +66,11 @@ folder, or containing `/`) clears the binding once that is certain:
52
66
  `onerror` instead. In pane mode `onnavigate` also fires when a file opens, changes
53
67
  or closes, with `file` set; `onfilechange` reports it in both modes.
54
68
 
69
+ A link without `rootId` opens on the first drive the caller can read and keeps its
70
+ `path` and `file`: the `onnavigate` for that pick carries the pending `file` (pane
71
+ mode), so a URL rebuilt from it keeps the document. An unknown `rootId` also falls
72
+ back to the first drive, but at its top with no file open.
73
+
55
74
  ```svelte
56
75
  <FileBrowser
57
76
  {source}
@@ -18,7 +18,7 @@
18
18
  TREE_CLASS,
19
19
  TREE_NOTE_CLASS,
20
20
  } from './tree-rows.js';
21
- import { cn, splitNameTail } from './utils.js';
21
+ import { cn, nameClipped, splitNameTail } from './utils.js';
22
22
 
23
23
  interface Props {
24
24
  /** Label of the drive (level 1). */
@@ -184,6 +184,71 @@
184
184
  if (current !== undefined) el(current)?.scrollIntoView({ block: 'nearest' });
185
185
  });
186
186
 
187
+ /*
188
+ * Middle truncation: the "…" shows only while a name's head is clipped
189
+ * (`data-clipped` on its `[data-name-split]`). One ResizeObserver serves the
190
+ * whole branch: it watches each head (the room it has) and its text (the
191
+ * width it wants), and a frame later measures every name that changed in one
192
+ * pass, reads before writes. Writing in the observer callback would resize
193
+ * observed elements mid-delivery and raise "ResizeObserver loop" errors.
194
+ */
195
+ let clipObserver: ResizeObserver | undefined;
196
+ const clipPending = new Set<HTMLElement>();
197
+ let clipFrame = 0;
198
+
199
+ function measureClips() {
200
+ clipFrame = 0;
201
+ const results: [HTMLElement, boolean][] = [];
202
+ for (const split of clipPending) {
203
+ if (!split.isConnected) continue;
204
+ const head = split.querySelector<HTMLElement>('[data-name-head]');
205
+ const text = split.querySelector<HTMLElement>('[data-name-text]');
206
+ const dots = split.querySelector<HTMLElement>('[data-name-ellipsis]');
207
+ if (!head || !text) continue;
208
+ const shown = split.hasAttribute('data-clipped');
209
+ results.push([
210
+ split,
211
+ nameClipped(
212
+ text.getBoundingClientRect().width,
213
+ head.getBoundingClientRect().width,
214
+ shown && dots ? dots.getBoundingClientRect().width : 0
215
+ ),
216
+ ]);
217
+ }
218
+ clipPending.clear();
219
+ for (const [split, clipped] of results) split.toggleAttribute('data-clipped', clipped);
220
+ }
221
+
222
+ function watchClip(split: HTMLElement) {
223
+ if (typeof ResizeObserver === 'undefined') return; // no layout (SSR, jsdom): plain text
224
+ clipObserver ??= new ResizeObserver((records) => {
225
+ for (const record of records) {
226
+ const owner = (record.target as HTMLElement).closest<HTMLElement>('[data-name-split]');
227
+ if (owner) clipPending.add(owner);
228
+ }
229
+ if (clipPending.size && !clipFrame) clipFrame = requestAnimationFrame(measureClips);
230
+ });
231
+ const targets = [
232
+ split.querySelector<HTMLElement>('[data-name-head]'),
233
+ split.querySelector<HTMLElement>('[data-name-text]'),
234
+ ].filter((t): t is HTMLElement => !!t);
235
+ for (const t of targets) clipObserver.observe(t);
236
+ return {
237
+ destroy() {
238
+ for (const t of targets) clipObserver?.unobserve(t);
239
+ clipPending.delete(split);
240
+ },
241
+ };
242
+ }
243
+
244
+ $effect(() => () => {
245
+ clipObserver?.disconnect();
246
+ clipObserver = undefined;
247
+ if (clipFrame) cancelAnimationFrame(clipFrame);
248
+ clipFrame = 0;
249
+ clipPending.clear();
250
+ });
251
+
187
252
  /** "Load more" clicked: move to the first new row once it lands (the button may go). */
188
253
  let focusFrom = $state<number>();
189
254
  function loadMoreClicked() {
@@ -242,12 +307,14 @@
242
307
  <FileIcon name={row.entry.name} type={row.entry.type} size={16} />
243
308
  {/if}
244
309
  {#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
- >
310
+ <!-- Middle truncation: the head clips, our own "…" (only while it is clipped)
311
+ joins it tight to the tail (…-FHN.xlsx), which stays. A CSS ellipsis would
312
+ snap to whole glyphs and leave a gap. Screen readers get the name once, whole. -->
313
+ <span class="group flex min-w-0" aria-hidden="true" data-name-split use:watchClip>
314
+ <span class="min-w-0 overflow-hidden whitespace-nowrap" data-name-head
315
+ ><span class="inline-block w-max" data-name-text>{split.head}</span></span
316
+ ><span class="hidden shrink-0 group-data-[clipped]:inline" data-name-ellipsis>…</span
317
+ ><span class="shrink-0 whitespace-nowrap" data-name-tail>{split.tail}</span>
251
318
  </span>
252
319
  <span class="sr-only">{row.name}</span>
253
320
  {:else}
@@ -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). */
@@ -1,11 +1,12 @@
1
1
  <script lang="ts">
2
- import type { Snippet } from 'svelte';
2
+ import type { ComponentProps, Snippet } from 'svelte';
3
3
  import { tick, untrack } from 'svelte';
4
4
  import { MediaQuery } from 'svelte/reactivity';
5
5
  import {
6
6
  Alert,
7
7
  Button,
8
8
  Dialog,
9
+ DropdownMenu,
9
10
  EmptyState,
10
11
  Icon,
11
12
  LiveRegion,
@@ -43,7 +44,11 @@
43
44
  interface Props {
44
45
  /** Where the data comes from: `createChapiFilesSource()`, `createMemoryFilesSource()` or your own. */
45
46
  source: FilesSource;
46
- /** Current root. Bindable; defaults to the first root the caller can read. */
47
+ /**
48
+ * Current root. Bindable; defaults to the first root the caller can read,
49
+ * keeping `path` and `file` (a deep link without a drive). An unknown root
50
+ * also falls back to the first one, but starts at its top with no file open.
51
+ */
47
52
  rootId?: string;
48
53
  /** Current folder, root-relative (`''` = the root). Bindable. */
49
54
  path?: string;
@@ -264,10 +269,25 @@
264
269
  const current = untrack(() => rootId);
265
270
  if (list.length && !list.some((r) => r.id === current)) {
266
271
  // Unknown or missing root: start on the first one the caller can read.
267
- rootId = list[0].id;
268
- if (current !== undefined) path = '';
269
- onrootchange?.(list[0].id);
270
- onnavigate?.({ rootId: list[0].id, path: untrack(() => currentPath) });
272
+ const first = list[0].id;
273
+ if (current !== undefined) {
274
+ // An unknown drive: its folder (and so its file) means nothing here.
275
+ path = '';
276
+ if (untrack(() => file) !== undefined) {
277
+ file = undefined;
278
+ onfilechange?.(undefined);
279
+ }
280
+ }
281
+ rootId = first;
282
+ onrootchange?.(first);
283
+ // No drive given is not a drive change: a deep link's `path` and
284
+ // `file` stay, and the reported location keeps the pending file.
285
+ const pending = untrack(() => file);
286
+ onnavigate?.(
287
+ preview === 'pane' && pending !== undefined
288
+ ? { rootId: first, path: untrack(() => currentPath), file: pending }
289
+ : { rootId: first, path: untrack(() => currentPath) }
290
+ );
271
291
  }
272
292
  },
273
293
  (err) => {
@@ -466,7 +486,9 @@
466
486
 
467
487
  // `file` from outside (a deep link, Back/Forward): open or close to match. A
468
488
  // location change closes the open file; a new `file` then resolves in the new folder.
489
+ // Picking the first drive when none was given is not a change: nothing was open.
469
490
  let lastLocation: string | undefined;
491
+ let lastRootId: string | undefined;
470
492
  let resolveController: AbortController | undefined;
471
493
  $effect(() => {
472
494
  const want = file;
@@ -475,8 +497,10 @@
475
497
  const listed = listedKey;
476
498
  const key = locationKey(id, folder);
477
499
  untrack(() => {
478
- if (lastLocation !== undefined && key !== lastLocation) hidePreview();
500
+ if (lastLocation !== undefined && lastRootId !== undefined && key !== lastLocation)
501
+ hidePreview();
479
502
  lastLocation = key;
503
+ lastRootId = id;
480
504
  const openName = previewOpen ? previewEntry?.name : undefined;
481
505
  if (want === openName) return;
482
506
  resolveController?.abort();
@@ -705,10 +729,28 @@
705
729
  };
706
730
  });
707
731
 
708
- const showPane = $derived(navigationPane && wide.current && roots.length > 0);
709
732
  // Two panes: the folder tree beside the list, or the folder's branch beside a document.
710
733
  const split = $derived(wide.current && roots.length > 0 && (navigationPane || docOpen));
711
734
  const rootOptions = $derived(roots.map((r) => ({ value: r.id, label: r.label })));
735
+ // Phones open the folder tree (which lists every drive) from a button beside the breadcrumbs.
736
+ const showFoldersButton = $derived(navigationPane && !wide.current && roots.length > 0);
737
+ // The drive picker, only where no folder tree lists the drives.
738
+ const showRootPicker = $derived(roots.length > 1 && !navigationPane);
739
+ /** Phones: the header's secondary controls, behind one ⋯ button. */
740
+ // The component's own item type, not the exported `DropdownMenuItem`: that one lacks
741
+ // `checked` up to theme-svelte 1.50.1, and this package accepts any theme-svelte (`*`).
742
+ const moreItems = $derived<ComponentProps<typeof DropdownMenu>['items']>([
743
+ {
744
+ label: 'Show hidden files',
745
+ checked: showHidden,
746
+ onSelect: () => (showHidden = !showHidden),
747
+ },
748
+ { label: 'Refresh', icon: 'refresh', onSelect: refresh },
749
+ ]);
750
+ /** The open folder as a path, for the phone "Files" button's tooltip. */
751
+ const folderTrail = $derived(
752
+ [rootLabel, ...(currentPath ? currentPath.split('/') : [])].join(' / ')
753
+ );
712
754
  const listLabel = $derived(`${folderName} contents`);
713
755
 
714
756
  const countText = $derived.by(() => {
@@ -762,13 +804,31 @@
762
804
  {:else}
763
805
  <!-- The open document's header carries the name; the branch beside it carries navigation. -->
764
806
  {#if !docOpen}
807
+ <!-- Phones: two rows (Folders + breadcrumbs; filter + toolbar + ⋯ menu). From md up: one row. -->
765
808
  <div
766
- class="flex flex-col gap-3 border-b border-border p-3 md:flex-row md:flex-wrap md:items-center md:gap-x-4 md:gap-y-2"
809
+ class="flex flex-col gap-2 border-b border-border p-3 md:flex-row md:flex-wrap md:items-center md:gap-x-4 md:gap-y-2"
767
810
  data-file-browser-header
768
811
  >
769
- <div class="flex min-w-0 flex-col gap-2 sm:flex-row sm:items-center md:flex-[1_1_16rem]">
770
- {#if roots.length > 1 && !showPane}
771
- <div class="sm:w-64">
812
+ <div
813
+ class="flex min-w-0 flex-wrap items-center gap-2 md:flex-[1_1_16rem] md:flex-nowrap"
814
+ data-file-browser-location
815
+ >
816
+ {#if showFoldersButton}
817
+ <Button
818
+ variant="outline"
819
+ size="sm"
820
+ class="shrink-0 px-2 sm:px-3"
821
+ onclick={() => (foldersOpen = true)}
822
+ aria-haspopup="dialog"
823
+ aria-label="Folders"
824
+ title="Folders"
825
+ >
826
+ <Icon name="sidebar" size={16} />
827
+ <span class="hidden sm:inline">Folders</span>
828
+ </Button>
829
+ {/if}
830
+ {#if showRootPicker}
831
+ <div class="w-full sm:w-64 sm:shrink-0">
772
832
  <Select
773
833
  label="Drive"
774
834
  value={rootId}
@@ -781,20 +841,29 @@
781
841
  {#if root}
782
842
  <FileBreadcrumbs
783
843
  rootLabel={root.label}
844
+ rootTitle={root.description ?? undefined}
784
845
  path={currentPath}
785
846
  onnavigate={(p) => navigate(p)}
786
- class="min-w-0 flex-1"
847
+ class={cn('min-w-0', wide.current && root.description ? 'flex-[0_1_auto]' : 'flex-1')}
787
848
  />
849
+ {#if wide.current && root.description && !showRootPicker}
850
+ <!-- Secondary: takes only the room the breadcrumbs leave, truncating. -->
851
+ <p
852
+ class="min-w-0 flex-[1_1_0] truncate text-xs text-muted-foreground"
853
+ title={root.description}
854
+ data-file-browser-description
855
+ >
856
+ {root.description}
857
+ </p>
858
+ {/if}
788
859
  {/if}
789
860
  </div>
790
- {#if root?.description && (roots.length === 1 || showPane)}
791
- <p class="-mt-1 text-xs text-muted-foreground md:order-last md:basis-full">
792
- {root.description}
793
- </p>
794
- {/if}
795
861
 
796
- <div class="flex flex-wrap items-center gap-x-4 gap-y-2 md:flex-[0_1_auto]">
797
- <div class="relative min-w-[12rem] flex-1 md:w-56 md:flex-none">
862
+ <div
863
+ class="flex flex-wrap items-center gap-2 md:flex-[0_1_auto] md:gap-x-4"
864
+ data-file-browser-controls
865
+ >
866
+ <div class="relative min-w-[10rem] flex-1 md:w-56 md:flex-none">
798
867
  <label for={filterId} class="sr-only"
799
868
  >{source.search ? 'Search files' : 'Filter files in this folder'}</label
800
869
  >
@@ -817,29 +886,35 @@
817
886
  aria-hidden="true">/</kbd
818
887
  >
819
888
  </div>
820
- <div class="flex items-center gap-2">
821
- <Switch id={hiddenId} checked={showHidden} onchange={(v) => (showHidden = v)} />
822
- <label for={hiddenId} class="whitespace-nowrap text-sm">Show hidden files</label>
823
- </div>
889
+ {#if wide.current}
890
+ <div class="flex items-center gap-2">
891
+ <Switch id={hiddenId} checked={showHidden} onchange={(v) => (showHidden = v)} />
892
+ <label for={hiddenId} class="whitespace-nowrap text-sm">Show hidden files</label>
893
+ </div>
894
+ {/if}
824
895
  {#if toolbar && caps.any}
825
896
  <div class="flex items-center gap-2" data-file-browser-toolbar>
826
897
  {@render toolbar(context)}
827
898
  </div>
828
899
  {/if}
829
- {#if navigationPane && !wide.current && roots.length > 0}
830
- <Button
831
- variant="outline"
832
- size="sm"
833
- onclick={() => (foldersOpen = true)}
834
- aria-haspopup="dialog"
835
- >
836
- <Icon name="sidebar" size={16} />
837
- Folders
900
+ {#if wide.current}
901
+ <Button variant="ghost" size="icon" onclick={refresh} aria-label="Refresh">
902
+ <Icon name="refresh" size={16} />
838
903
  </Button>
904
+ {:else}
905
+ <DropdownMenu
906
+ items={moreItems}
907
+ align="end"
908
+ triggerVariant="ghost"
909
+ triggerSize="icon"
910
+ triggerClass="shrink-0"
911
+ triggerLabel="More options"
912
+ >
913
+ {#snippet trigger()}
914
+ <Icon name="more-horizontal" size={16} />
915
+ {/snippet}
916
+ </DropdownMenu>
839
917
  {/if}
840
- <Button variant="ghost" size="icon" onclick={refresh} aria-label="Refresh">
841
- <Icon name="refresh" size={16} />
842
- </Button>
843
918
  </div>
844
919
  </div>
845
920
  {/if}
@@ -971,7 +1046,13 @@
971
1046
  {/snippet}
972
1047
 
973
1048
  {#snippet filesButton()}
974
- <Button variant="outline" size="sm" onclick={() => (filesOpen = true)} aria-haspopup="dialog">
1049
+ <Button
1050
+ variant="outline"
1051
+ size="sm"
1052
+ onclick={() => (filesOpen = true)}
1053
+ aria-haspopup="dialog"
1054
+ title={`Files in ${folderTrail}`}
1055
+ >
975
1056
  <Icon name="list" size={16} />
976
1057
  Files
977
1058
  </Button>
@@ -5,7 +5,11 @@ import type { FileBrowserContext } from './types.js';
5
5
  interface Props {
6
6
  /** Where the data comes from: `createChapiFilesSource()`, `createMemoryFilesSource()` or your own. */
7
7
  source: FilesSource;
8
- /** Current root. Bindable; defaults to the first root the caller can read. */
8
+ /**
9
+ * Current root. Bindable; defaults to the first root the caller can read,
10
+ * keeping `path` and `file` (a deep link without a drive). An unknown root
11
+ * also falls back to the first one, but starts at its top with no file open.
12
+ */
9
13
  rootId?: string;
10
14
  /** Current folder, root-relative (`''` = the root). Bindable. */
11
15
  path?: string;
@@ -15,7 +15,15 @@ export declare function downloadEntry(source: FilesSource, rootId: string, entry
15
15
  /** True when a key event comes from a place that types text. */
16
16
  export declare function isTextInput(target: EventTarget | null): boolean;
17
17
  /**
18
- * Split a file name for middle truncation: the head shrinks (ellipsis), the
18
+ * Whether a middle-truncated name's head is clipped: its text (`textWidth`, the
19
+ * natural width) is wider than the room it has. While the "…" shows it takes
20
+ * `ellipsisWidth` of that room, so pass it then: the name only goes back to
21
+ * plain text once it fits without the "…" (no flip-flopping at the boundary).
22
+ * Half a pixel of slack absorbs subpixel layout.
23
+ */
24
+ export declare function nameClipped(textWidth: number, boxWidth: number, ellipsisWidth?: number): boolean;
25
+ /**
26
+ * Split a file name for middle truncation: the head shrinks (clipped, with a "…" after it), the
19
27
  * tail always shows. The tail is the extension (from the last dot, unless the
20
28
  * dot leads the name or the extension is over 10 characters) plus the 6
21
29
  * characters before it, never splitting a character (grapheme). The split moves
package/dist/lib/utils.js CHANGED
@@ -56,7 +56,17 @@ function graphemes(text) {
56
56
  return Array.from(text); // code points: never splits a surrogate pair
57
57
  }
58
58
  /**
59
- * Split a file name for middle truncation: the head shrinks (ellipsis), the
59
+ * Whether a middle-truncated name's head is clipped: its text (`textWidth`, the
60
+ * natural width) is wider than the room it has. While the "…" shows it takes
61
+ * `ellipsisWidth` of that room, so pass it then: the name only goes back to
62
+ * plain text once it fits without the "…" (no flip-flopping at the boundary).
63
+ * Half a pixel of slack absorbs subpixel layout.
64
+ */
65
+ export function nameClipped(textWidth, boxWidth, ellipsisWidth = 0) {
66
+ return textWidth > boxWidth + ellipsisWidth + 0.5;
67
+ }
68
+ /**
69
+ * Split a file name for middle truncation: the head shrinks (clipped, with a "…" after it), the
60
70
  * tail always shows. The tail is the extension (from the last dot, unless the
61
71
  * dot leads the name or the extension is over 10 characters) plus the 6
62
72
  * characters before it, never splitting a character (grapheme). The split moves
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@classic-homes/files-svelte",
3
- "version": "0.6.0",
3
+ "version": "0.6.2",
4
4
  "description": "Svelte network-drive file browser for Classic Theme: FileBrowser plus FileList, FileBreadcrumbs, FileIcon, FilePreview and FileDetails, with previews through the document viewers",
5
5
  "type": "module",
6
6
  "svelte": "./dist/lib/index.js",