@aiquants/directory-tree 5.0.1 → 6.1.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.
package/README.md CHANGED
@@ -7,7 +7,7 @@ A high-performance React directory tree component with virtualization, file sele
7
7
  - **🚀 High Performance**: Built with [@aiquants/virtualscroll](../virtualscroll) to handle large directory structures efficiently with O(log n) operations
8
8
  - **🌀 Ultrafast Scrolling**: Inherits adaptive tap scroll circle from VirtualScroll for navigating massive datasets
9
9
  - **📁 File Selection**: Interactive file selection with visual feedback and multiple selection modes
10
- - **🎨 Theming**: Customizable line colors with external theme control support
10
+ - **🎨 Colour schemes**: Every built-in colour follows the host's `color-scheme` through CSS `light-dark()`, at WCAG 2.2 AAA contrast in both schemes, with no `.dark` class to wire up. See [Colours and color-scheme](#colours-and-color-scheme)
11
11
  - **♿ Accessibility**: Full keyboard navigation and screen reader support
12
12
  - **📱 Responsive**: Optimized for both desktop and mobile interfaces
13
13
  - **🔧 TypeScript**: Complete TypeScript support with comprehensive type definitions
@@ -18,10 +18,6 @@ A high-performance React directory tree component with virtualization, file sele
18
18
  ## Installation
19
19
 
20
20
  ```bash
21
- npm install @aiquants/directory-tree
22
- # or
23
- yarn add @aiquants/directory-tree
24
- # or
25
21
  pnpm add @aiquants/directory-tree
26
22
  ```
27
23
 
@@ -30,7 +26,7 @@ pnpm add @aiquants/directory-tree
30
26
  This package requires the following peer dependencies:
31
27
 
32
28
  ```bash
33
- npm install react react-dom @aiquants/virtualscroll
29
+ pnpm add react react-dom @aiquants/virtualscroll
34
30
  ```
35
31
 
36
32
  `@aiquants/virtualscroll` must be 3.22.0 or later: it supplies the `locale` / `labels` chrome catalog, the pill-aware `scrollToIndex(index, { align: "nearest" })` that reveals focused rows, and the edge pills that hide while the pane rests at their edge (so the first and last rows are never left under a pill).
@@ -40,7 +36,6 @@ npm install react react-dom @aiquants/virtualscroll
40
36
  ```tsx
41
37
  import React from 'react';
42
38
  import { DirectoryTree, useDirectoryTreeState } from '@aiquants/directory-tree';
43
- import { useTheme } from './hooks/useTheme'; // Your theme hook
44
39
  import type { DirectoryEntry, DirectoryTreeClickEvent } from '@aiquants/directory-tree';
45
40
 
46
41
  const sampleData: DirectoryEntry[] = [
@@ -69,7 +64,6 @@ const sampleData: DirectoryEntry[] = [
69
64
  ];
70
65
 
71
66
  export default function App() {
72
- const { theme } = useTheme();
73
67
  const {
74
68
  toggle,
75
69
  isExpanded,
@@ -80,9 +74,6 @@ export default function App() {
80
74
  storageKey: 'my-directory-tree'
81
75
  });
82
76
 
83
- // Calculate line color based on theme
84
- const lineColor = theme === "dark" ? "#4A5568" : "#A0AEC0";
85
-
86
77
  const handleEntryClick = (event: DirectoryTreeClickEvent) => {
87
78
  console.log(`Entry clicked: ${event.entry.absolutePath}`);
88
79
  };
@@ -103,7 +94,6 @@ export default function App() {
103
94
  selectedPath: null
104
95
  }}
105
96
  visual={{
106
- lineColor,
107
97
  className: "h-full"
108
98
  }}
109
99
  />
@@ -139,7 +129,7 @@ The main component for rendering the directory tree.
139
129
  | `isExpanded` | `(path: string) => boolean` | Yes | - | Function to check if a directory is expanded |
140
130
  | `expandMultiple` | `(paths: string[]) => void` | Yes | - | Function to expand multiple directories |
141
131
  | `collapseMultiple` | `(paths: string[]) => void` | Yes | - | Function to collapse multiple directories |
142
- | `isPending` | `boolean` | No | `false` | Whether the tree is in a pending state |
132
+ | `isPending` | `boolean` | No | `false` | Whether a transition the host started is pending (`useDirectoryTreeState`'s `isPending`). While it is, the tree marks itself busy (`aria-busy` on the element with the tree's role) and shows the progress cursor; nothing is dimmed, and the rows stay operable |
143
133
  | `alwaysExpanded` | `boolean` | No | `false` | If true, all directories are always expanded |
144
134
  | `doubleClickAction` | `'recursive' \| 'toggle'` | No | `'recursive'` | Action on double-clicking a directory |
145
135
 
@@ -160,7 +150,7 @@ The main component for rendering the directory tree.
160
150
  | --- | --- | --- | --- | --- |
161
151
  | `className` | `string` | No | - | Optional CSS class name for the container |
162
152
  | `style` | `React.CSSProperties` | No | - | Optional inline styles for the container |
163
- | `lineColor` | `string` | No | `'#A0AEC0'` | The color of the tree lines |
153
+ | `lineColor` | `string` | No | `'#71829b'` (`DEFAULT_LINE_COLOR`) | The colour of the connector lines and the expand glyphs drawn with them, on a canvas above the rows: any colour a canvas reads, one value for both schemes (a canvas cannot resolve `light-dark()`). The default keeps 3.5:1 or more on every ground a row can show in both schemes. See [Colours and color-scheme](#colours-and-color-scheme) |
164
154
  | `showTreeLines` | `boolean` | No | `true` | Flag indicating whether to render tree connector lines |
165
155
  | `showExpandIcons` | `boolean` | No | `true` | Flag indicating whether to render directory expand icons |
166
156
  | `showDirectoryIcons` | `boolean` | No | `true` | Flag indicating whether to render directory type icons |
@@ -181,8 +171,8 @@ The main component for rendering the directory tree.
181
171
  | `directoryNameStyle` | `React.CSSProperties` | No | - | Additional inline styles specifically for directory names |
182
172
  | `fileNameClassName` | `string` | No | - | Additional CSS classes specifically for file names |
183
173
  | `fileNameStyle` | `React.CSSProperties` | No | - | Additional inline styles specifically for file names |
184
- | `expandIconClassName` | `string` | No | - | Additional CSS classes for the expand glyph (the chevron drawn in the row when `showTreeLines` is `false`), merged like `nameClassName`: the selected-row colour class still follows it, and a colour class replaces only the light default, so the built-in `dark:text-gray-400` stays unless the class carries a `dark:` colour too. Not checked: keep box utilities out of it |
185
- | `expandIconStyle` | `DirectoryTreeExpandIconStyle` | No | - | Inline styles for the expand glyph, applied like `nameStyle` (they win over every class, the selected-row colour included): `color` and `opacity` only (`EXPAND_ICON_STYLE_PROPERTIES`); any other property throws a `RangeError` at render, because the 14 px expand box is the tree's. The glyph is drawn in `currentColor`, so `{ color: "var(--your-token)" }` follows your colour tokens independently of the `dark` class. The canvas glyph drawn with the tree lines takes `lineColor`. See [Row and expand-icon styles](#row-and-expand-icon-styles) |
174
+ | `expandIconClassName` | `string` | No | - | Additional CSS classes for the expand glyph (the chevron drawn in the row when `showTreeLines` is `false`), merged like `nameClassName`: the selected-row colour class still follows it. The default colour is one `light-dark()` class with no `dark:` variant, so a colour class replaces it in both schemes; a class whose colour has to differ by scheme carries its own `light-dark()` value or a variable. Not checked: keep box utilities out of it |
175
+ | `expandIconStyle` | `DirectoryTreeExpandIconStyle` | No | - | Inline styles for the expand glyph, applied like `nameStyle` (they win over every class, the selected-row colour included): `color` and `opacity` only (`EXPAND_ICON_STYLE_PROPERTIES`); any other property throws a `RangeError` at render, because the 14 px expand box is the tree's. The glyph is drawn in `currentColor`, so `{ color: "var(--your-token)" }` follows your colour tokens. The canvas glyph drawn with the tree lines takes `lineColor`. See [Row and expand-icon styles](#row-and-expand-icon-styles) |
186
176
 
187
177
  ### Virtual Scroll Options
188
178
 
@@ -211,9 +201,10 @@ These are **not** accepted, because the tree owns them:
211
201
  - `behaviorOptions.enableKeyboardNavigation` and `behaviorOptions.enableEscapeRowReturn`: the tree's rows own the
212
202
  keyboard (see [Keyboard and focus](#keyboard-and-focus)); the tree always turns the engine's row navigation off,
213
203
  because its row wrappers would otherwise be focusable elements between `role="tree"` and the treeitems.
214
- - `contentProps.role`, `contentProps["aria-label"]`, `contentProps["aria-labelledby"]` and
215
- `contentProps["aria-multiselectable"]`: the tree's name comes from `visual.ariaLabel` / `visual.ariaLabelledBy`
216
- and its multiselection from `selection.mode`.
204
+ - `contentProps.role`, `contentProps["aria-label"]`, `contentProps["aria-labelledby"]`,
205
+ `contentProps["aria-multiselectable"]` and `contentProps["aria-busy"]`: the tree's name comes from
206
+ `visual.ariaLabel` / `visual.ariaLabelledBy`, its multiselection from `selection.mode` and its busy state from
207
+ `expansion.isPending`.
217
208
 
218
209
  Writing one of them in an object literal typed as `DirectoryTreeVirtualScrollOptions` is a type error. A value that
219
210
  reaches the tree any other way (a variable of a wider type, an object built by a generic helper or a spread, a
@@ -277,7 +268,7 @@ The classic tree follows the WAI-ARIA tree pattern with a roving tabindex: it al
277
268
  appears in the render that follows the one where the Tab stop row left the render window (the tree measures that
278
269
  in its own layout effect), so look it up after that commit, not in a layout effect of the same commit.
279
270
 
280
- The element that carries `role="tree"` (with the tree's name and `aria-multiselectable`) is the scroll pane's
271
+ The element that carries `role="tree"` (with the tree's name, `aria-multiselectable` and `aria-busy`) is the scroll pane's
281
272
  content element, which owns only the rows: the scrollbar, the Top/Bottom buttons and the live region
282
273
  (`virtualScroll.liveRegion`) stay outside the tree, and the wrappers between the tree and its rows carry no role,
283
274
  tabindex or ARIA attribute. The root container has no role; target it through `visual.className`.
@@ -364,7 +355,7 @@ type DirectoryEntry = {
364
355
 
365
356
  ## Styling
366
357
 
367
- The component's hand-written classes ship in **two CSS artifacts**; choose by host type. The tree is built on `@aiquants/virtualscroll`, so that package's stylesheet is a **peer CSS dependency** — import it once alongside directory-tree. Theme control (light/dark) stays with the calling app.
358
+ The component's hand-written classes ship in **two CSS artifacts**; choose by host type. The tree is built on `@aiquants/virtualscroll`, so that package's stylesheet is a **peer CSS dependency** — import it once alongside directory-tree. The colours follow the `color-scheme` the host sets (see [Colours and color-scheme](#colours-and-color-scheme)).
368
359
 
369
360
  - **Tailwind v4 host** — import the components-only build in `layer(components)`, do the same for the virtualscroll peer build, and let your Tailwind build generate the JSX utilities from the package source:
370
361
 
@@ -384,32 +375,71 @@ The component's hand-written classes ship in **two CSS artifacts**; choose by ho
384
375
  @import "@aiquants/directory-tree/styles/directory-tree.standalone.css";
385
376
  ```
386
377
 
387
- Dark styles key off the `.dark` class on `<html>`.
388
-
389
- ### Theme Control
378
+ Neither build reads a `.dark` class: the colours follow the host's `color-scheme`.
390
379
 
391
- The `lineColor` prop allows you to control the tree line color based on your application's theme:
380
+ ### Colours and color-scheme
392
381
 
393
- ```tsx
394
- import { useTheme } from './hooks/useTheme';
382
+ Every colour the tree paints by default is one role of its palette: a light-scheme value and a dark-scheme value
383
+ written as CSS `light-dark()`. The tree therefore follows the `color-scheme` the host puts on the root or on an
384
+ ancestor of the tree, and reads neither a `.dark` class nor `prefers-color-scheme`. `light-dark()` needs Chrome / Edge
385
+ 123, Firefox 120 or Safari 17.5.
395
386
 
396
- function MyComponent() {
397
- const { theme } = useTheme();
387
+ ```css
388
+ /* follow the OS */
389
+ :root { color-scheme: light dark; }
398
390
 
399
- // Calculate line color based on theme
400
- const lineColor = theme === "dark" ? "#4A5568" : "#A0AEC0";
391
+ /* or follow your own switch, for example a .dark class on <html> */
392
+ :root { color-scheme: light; }
393
+ :root.dark { color-scheme: dark; }
394
+ ```
401
395
 
402
- return (
403
- <DirectoryTree
404
- // ... other props
405
- visual={{
406
- lineColor: lineColor
407
- }}
408
- />
409
- );
396
+ | Role | Light scheme | Dark scheme | Contrast in both schemes |
397
+ | --- | --- | --- | --- |
398
+ | Name | gray-700 `#364153` | gray-200 `#e5e7eb` | Text: 7:1 or more |
399
+ | Name on a selected row | blue-800 `#193cb8` | blue-200 `#bedbff` | Text: 7:1 or more |
400
+ | Text of a grid's header and footer rows | gray-600 `#4a5565` | gray-300 `#d1d5dc` | Text: 7:1 or more on the host surfaces (those rows are never hovered nor selected) |
401
+ | Chevron and type icons | gray-500 `#6a7282` | gray-400 `#99a1af` | Non-text: 3:1 or more |
402
+ | Chevron and type icons on a selected row | blue-700 `#1447e6` | blue-400 `#51a2ff` | Non-text: 3:1 or more |
403
+ | Inset ring of a file checked in the selection | blue-600 `#155dfc` | blue-400 `#51a2ff` | Non-text: 3:1 or more |
404
+ | Built-in file icons | the 600 step of the kind's hue (spreadsheets and CSV files: emerald-700, presentations: orange-700, images: teal-700, archives: amber-700, whose 600 steps keep less than 3.5:1 on the hovered row; plain text: the icon colour) | the 400 step (plain text: the icon colour) | Non-text: 3.5:1 or more |
405
+ | Connector lines and the glyphs drawn with them (`lineColor`) | `#71829b` | `#71829b` | Non-text: 3.5:1 or more |
406
+ | Hovered row | gray-100 `#f3f4f6` | gray-800 `#1e2939` | Ground |
407
+ | Selected row | blue-50 `#eff6ff` | blue-950 `#162456` | Ground |
408
+
409
+ The ratios hold on every ground a row can show: the host surfaces the defaults are checked on (white and gray-50 in the
410
+ light scheme, gray-950 and gray-900 in the dark one) and the tree's own hovered and selected rows. The tree paints no
411
+ surface of its own, so a host on another surface checks the defaults against it or passes its own colours. Nothing is
412
+ translucent: the hovered and the selected rows are opaque, and a pending transition marks the tree busy (`aria-busy`)
413
+ and shows the progress cursor instead of dimming it.
414
+
415
+ The package exports the colours such a check needs: `FILE_ICON_PAIRS` (each built-in file icon, keyed by `FileIconKind`)
416
+ and `MARK_PAIRS` (the chevron and type icons, the same on a selected row, and the ring of a checked file), each a
417
+ `SchemePair` of six-digit sRGB hex colours. The file icons keep 3.5:1 on the grounds above, which leaves 3:1 on a pale
418
+ accent tint such as blue-100 or blue-900 under a row; a host with its own row colours compares them in its tests:
419
+
420
+ ```ts
421
+ import { FILE_ICON_PAIRS, MARK_PAIRS } from "@aiquants/directory-tree";
422
+
423
+ // contrastRatio and appColours are the host's own.
424
+ for (const pair of [...Object.values(FILE_ICON_PAIRS), ...Object.values(MARK_PAIRS)]) {
425
+ expect(contrastRatio(pair.light, appColours.light.rowTint)).toBeGreaterThanOrEqual(3);
426
+ expect(contrastRatio(pair.dark, appColours.dark.rowTint)).toBeGreaterThanOrEqual(3);
410
427
  }
411
428
  ```
412
429
 
430
+ The tree draws its connector lines, and the expand glyphs that go with them, on a canvas above the rows, so a row's
431
+ background never hides whether a directory is open; the canvas lets every press through to the rows. A canvas cannot
432
+ resolve `light-dark()`, so `lineColor` is one colour for both schemes: the default keeps 3.5:1 or more on every ground
433
+ above (3.55:1 at its lowest in the light scheme and 3.75:1 in the dark one, both on the hovered row). A host whose line
434
+ colour has to follow its scheme passes the colour of the current scheme and changes it with the scheme:
435
+
436
+ ```tsx
437
+ <DirectoryTree
438
+ // ... other props
439
+ visual={{ lineColor: scheme === "dark" ? appColours.dark.treeLine : appColours.light.treeLine }}
440
+ />
441
+ ```
442
+
413
443
  ### Custom Styling
414
444
 
415
445
  You can customize the appearance by passing custom classes or inline styles for specific elements like entry rows, name labels, directory names, or file names, avoiding arbitrary CSS selectors overrides:
@@ -421,23 +451,26 @@ You can customize the appearance by passing custom classes or inline styles for
421
451
  style: { height: '400px' },
422
452
 
423
453
  // Style the entry rows: paint and text only (the row's box is the tree's)
424
- entryClassName: "rounded-md hover:bg-slate-100/50",
454
+ entryClassName: "rounded-md",
425
455
  entryStyle: { letterSpacing: "0.01em", textUnderlineOffset: "2px" },
426
456
 
427
457
  // Style the label text
428
458
  nameClassName: "text-sm font-medium",
429
459
 
430
- // Target directory or file names specifically
431
- directoryNameClassName: "text-slate-800 dark:text-slate-100",
432
- fileNameClassName: "text-slate-600 dark:text-slate-300",
460
+ // Target directory or file names specifically: one light-dark() pair per colour (slate-800 / slate-100 and
461
+ // slate-700 / slate-300 keep 7:1 on the default grounds in both schemes)
462
+ directoryNameClassName: "text-[color:light-dark(#1d293d,#f1f5f9)]",
463
+ fileNameClassName: "text-[color:light-dark(#314158,#cad5e2)]",
433
464
  }}
434
465
  // ... other props
435
466
  />
436
467
  ```
437
468
 
438
469
  The expand glyph drawn in the row (when `showTreeLines` is `false`) takes `expandIconClassName` /
439
- `expandIconStyle` the same way. To make its colour follow your own theme rather than the `dark` class, pass a colour
440
- token through `expandIconStyle`: an inline style wins over every class, the built-in `dark:` colour included.
470
+ `expandIconStyle` the same way. Its default colour is one `light-dark()` class, so a colour class in
471
+ `expandIconClassName` replaces it in both schemes; give a class whose colour has to differ by scheme its own
472
+ `light-dark()` value or a variable, for example `"text-(--app-tree-glyph)"`. A colour token passed through
473
+ `expandIconStyle` wins over every class, the selected-row colour included:
441
474
 
442
475
  ```tsx
443
476
  <DirectoryTree
@@ -446,11 +479,6 @@ token through `expandIconStyle`: an inline style wins over every class, the buil
446
479
  />
447
480
  ```
448
481
 
449
- `expandIconClassName` is merged into the built-in classes like `nameClassName`, so a colour class on its own replaces
450
- only the light default (`text-gray-500`): the built-in `dark:text-gray-400` stays and wins under your `dark` class.
451
- To set the colour with a class, give its `dark:` variant as well, for example
452
- `"text-(--app-tree-glyph) dark:text-(--app-tree-glyph)"`.
453
-
454
482
  Alternatively, you can customize components inside the container using global CSS classes:
455
483
 
456
484
  ```css
@@ -459,23 +487,23 @@ Alternatively, you can customize components inside the container using global CS
459
487
  }
460
488
  ```
461
489
 
462
- Alternatively, you can dynamically configure specific highlight styles for hover, directory selection, and item (file) selection by passing custom class names or inline styles via `highlightStyles`:
490
+ Alternatively, you can dynamically configure specific highlight styles for hover, directory selection, and item (file) selection by passing custom class names or inline styles via `highlightStyles`. Keep the backgrounds opaque: a translucent one mixes with whatever lies behind the row, so the contrast of the row's text and icons is no longer the one you checked. The colours below keep every default text of the row at 7:1 and every mark at 3:1 in both schemes:
463
491
 
464
492
  ```tsx
465
493
  <DirectoryTree
466
494
  visual={{
467
495
  highlightStyles: {
468
- // Custom hover style
469
- hoverClassName: "bg-amber-100 dark:bg-amber-900/20",
470
- hoverStyle: { boxShadow: "inset -2px 0 0 orange" },
471
-
472
- // Custom directory selection style
473
- directorySelectedClassName: "bg-emerald-100 dark:bg-emerald-900/20 font-bold",
474
- directorySelectedStyle: { boxShadow: "inset 3px 0 0 green" },
475
-
476
- // Custom item (file) selection style
477
- itemSelectedClassName: "bg-indigo-100 dark:bg-indigo-900/20 text-indigo-800",
478
- itemSelectedStyle: { boxShadow: "inset 3px 0 0 indigo" },
496
+ // Custom hover style (amber-50 / amber-950, edge amber-700 / amber-400)
497
+ hoverClassName: "bg-[color:light-dark(#fffbeb,#461901)]",
498
+ hoverStyle: { boxShadow: "inset -2px 0 0 light-dark(#bb4d00, #ffb900)" },
499
+
500
+ // Custom directory selection style (emerald-50 / emerald-950, edge emerald-700 / emerald-400)
501
+ directorySelectedClassName: "bg-[color:light-dark(#ecfdf5,#002c22)] font-bold",
502
+ directorySelectedStyle: { boxShadow: "inset 3px 0 0 light-dark(#007a55, #00d492)" },
503
+
504
+ // Custom item (file) selection style (indigo-50 / indigo-950, text indigo-800 / indigo-200, edge indigo-700 / indigo-300)
505
+ itemSelectedClassName: "bg-[color:light-dark(#eef2ff,#1e1a4d)] text-[color:light-dark(#372aac,#c6d2ff)]",
506
+ itemSelectedStyle: { boxShadow: "inset 3px 0 0 light-dark(#432dd7, #a3b3ff)" },
479
507
  }
480
508
  }}
481
509
  // ... other props
package/dist/cli.js CHANGED
@@ -98,10 +98,10 @@ class s {
98
98
  this.level <= 3 && this.impl.error(...this.formatMessage(t), ...e);
99
99
  }
100
100
  }
101
- const l = f(import.meta.url), p = a.dirname(l), r = new s(o.INFO, "[directory-tree]"), n = process.argv.slice(2);
101
+ const l = f(import.meta.url), h = a.dirname(l), r = new s(o.INFO, "[directory-tree]"), n = process.argv.slice(2);
102
102
  if (n[0] === "demo") {
103
103
  r.info("Starting demo server...");
104
- const i = a.join(p, "..", "demo"), t = m("pnpm", ["run", "dev"], {
104
+ const i = a.join(h, "..", "demo"), t = m("pnpm", ["run", "dev"], {
105
105
  cwd: i,
106
106
  stdio: "inherit",
107
107
  shell: process.platform === "win32"
@@ -112,4 +112,4 @@ if (n[0] === "demo") {
112
112
  r.error("Failed to start demo server:", e);
113
113
  });
114
114
  } else
115
- r.info(`Unknown command: ${n[0]}`), r.info("Usage: npx @aiquants/directory-tree demo"), process.exit(1);
115
+ r.info(`Unknown command: ${n[0]}`), r.info("Usage: node dist/cli.js demo"), process.exit(1);