@aiquants/directory-tree 5.0.0 โ†’ 6.0.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,35 +26,36 @@ 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
- `@aiquants/virtualscroll` must be 3.11.3 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).
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).
37
33
 
38
34
  ## Quick Start
39
35
 
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
- import type { DirectoryEntry } from '@aiquants/directory-tree';
39
+ import type { DirectoryEntry, DirectoryTreeClickEvent } from '@aiquants/directory-tree';
45
40
 
46
41
  const sampleData: DirectoryEntry[] = [
47
42
  {
48
43
  name: 'src',
44
+ type: 'directory',
49
45
  absolutePath: '/src',
50
46
  relativePath: 'src',
51
47
  children: [
52
48
  {
53
49
  name: 'components',
50
+ type: 'directory',
54
51
  absolutePath: '/src/components',
55
52
  relativePath: 'src/components',
56
53
  children: [
57
54
  {
58
55
  name: 'App.tsx',
56
+ type: 'file',
59
57
  absolutePath: '/src/components/App.tsx',
60
- relativePath: 'src/components/App.tsx',
61
- children: null
58
+ relativePath: 'src/components/App.tsx'
62
59
  }
63
60
  ]
64
61
  }
@@ -67,7 +64,6 @@ const sampleData: DirectoryEntry[] = [
67
64
  ];
68
65
 
69
66
  export default function App() {
70
- const { theme } = useTheme();
71
67
  const {
72
68
  toggle,
73
69
  isExpanded,
@@ -78,9 +74,6 @@ export default function App() {
78
74
  storageKey: 'my-directory-tree'
79
75
  });
80
76
 
81
- // Calculate line color based on theme
82
- const lineColor = theme === "dark" ? "#4A5568" : "#A0AEC0";
83
-
84
77
  const handleEntryClick = (event: DirectoryTreeClickEvent) => {
85
78
  console.log(`Entry clicked: ${event.entry.absolutePath}`);
86
79
  };
@@ -101,7 +94,6 @@ export default function App() {
101
94
  selectedPath: null
102
95
  }}
103
96
  visual={{
104
- lineColor,
105
97
  className: "h-full"
106
98
  }}
107
99
  />
@@ -137,7 +129,7 @@ The main component for rendering the directory tree.
137
129
  | `isExpanded` | `(path: string) => boolean` | Yes | - | Function to check if a directory is expanded |
138
130
  | `expandMultiple` | `(paths: string[]) => void` | Yes | - | Function to expand multiple directories |
139
131
  | `collapseMultiple` | `(paths: string[]) => void` | Yes | - | Function to collapse multiple directories |
140
- | `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 |
141
133
  | `alwaysExpanded` | `boolean` | No | `false` | If true, all directories are always expanded |
142
134
  | `doubleClickAction` | `'recursive' \| 'toggle'` | No | `'recursive'` | Action on double-clicking a directory |
143
135
 
@@ -158,7 +150,7 @@ The main component for rendering the directory tree.
158
150
  | --- | --- | --- | --- | --- |
159
151
  | `className` | `string` | No | - | Optional CSS class name for the container |
160
152
  | `style` | `React.CSSProperties` | No | - | Optional inline styles for the container |
161
- | `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) |
162
154
  | `showTreeLines` | `boolean` | No | `true` | Flag indicating whether to render tree connector lines |
163
155
  | `showExpandIcons` | `boolean` | No | `true` | Flag indicating whether to render directory expand icons |
164
156
  | `showDirectoryIcons` | `boolean` | No | `true` | Flag indicating whether to render directory type icons |
@@ -179,8 +171,8 @@ The main component for rendering the directory tree.
179
171
  | `directoryNameStyle` | `React.CSSProperties` | No | - | Additional inline styles specifically for directory names |
180
172
  | `fileNameClassName` | `string` | No | - | Additional CSS classes specifically for file names |
181
173
  | `fileNameStyle` | `React.CSSProperties` | No | - | Additional inline styles specifically for file names |
182
- | `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 |
183
- | `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) |
184
176
 
185
177
  ### Virtual Scroll Options
186
178
 
@@ -209,9 +201,10 @@ These are **not** accepted, because the tree owns them:
209
201
  - `behaviorOptions.enableKeyboardNavigation` and `behaviorOptions.enableEscapeRowReturn`: the tree's rows own the
210
202
  keyboard (see [Keyboard and focus](#keyboard-and-focus)); the tree always turns the engine's row navigation off,
211
203
  because its row wrappers would otherwise be focusable elements between `role="tree"` and the treeitems.
212
- - `contentProps.role`, `contentProps["aria-label"]`, `contentProps["aria-labelledby"]` and
213
- `contentProps["aria-multiselectable"]`: the tree's name comes from `visual.ariaLabel` / `visual.ariaLabelledBy`
214
- 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`.
215
208
 
216
209
  Writing one of them in an object literal typed as `DirectoryTreeVirtualScrollOptions` is a type error. A value that
217
210
  reaches the tree any other way (a variable of a wider type, an object built by a generic helper or a spread, a
@@ -275,7 +268,7 @@ The classic tree follows the WAI-ARIA tree pattern with a roving tabindex: it al
275
268
  appears in the render that follows the one where the Tab stop row left the render window (the tree measures that
276
269
  in its own layout effect), so look it up after that commit, not in a layout effect of the same commit.
277
270
 
278
- 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
279
272
  content element, which owns only the rows: the scrollbar, the Top/Bottom buttons and the live region
280
273
  (`virtualScroll.liveRegion`) stay outside the tree, and the wrappers between the tree and its rows carry no role,
281
274
  tabindex or ARIA attribute. The root container has no role; target it through `visual.className`.
@@ -362,7 +355,7 @@ type DirectoryEntry = {
362
355
 
363
356
  ## Styling
364
357
 
365
- 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)).
366
359
 
367
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:
368
361
 
@@ -382,30 +375,54 @@ The component's hand-written classes ship in **two CSS artifacts**; choose by ho
382
375
  @import "@aiquants/directory-tree/styles/directory-tree.standalone.css";
383
376
  ```
384
377
 
385
- Dark styles key off the `.dark` class on `<html>`.
378
+ Neither build reads a `.dark` class: the colours follow the host's `color-scheme`.
386
379
 
387
- ### Theme Control
380
+ ### Colours and color-scheme
388
381
 
389
- The `lineColor` prop allows you to control the tree line color based on your application's theme:
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.
390
386
 
391
- ```tsx
392
- import { useTheme } from './hooks/useTheme';
387
+ ```css
388
+ /* follow the OS */
389
+ :root { color-scheme: light dark; }
393
390
 
394
- function MyComponent() {
395
- const { theme } = useTheme();
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
+ ```
396
395
 
397
- // Calculate line color based on theme
398
- const lineColor = theme === "dark" ? "#4A5568" : "#A0AEC0";
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 (archives: amber-700, whose 600 step falls below 3:1 on the hovered row; plain text: the icon colour) | the 400 step (plain text: the icon colour) | Non-text: 3: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 tree draws its connector lines, and the expand glyphs that go with them, on a canvas above the rows, so a row's
416
+ background never hides whether a directory is open; the canvas lets every press through to the rows. A canvas cannot
417
+ resolve `light-dark()`, so `lineColor` is one colour for both schemes: the default keeps 3.5:1 or more on every ground
418
+ 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
419
+ colour has to follow its scheme passes the colour of the current scheme and changes it with the scheme:
399
420
 
400
- return (
401
- <DirectoryTree
402
- // ... other props
403
- visual={{
404
- lineColor: lineColor
405
- }}
406
- />
407
- );
408
- }
421
+ ```tsx
422
+ <DirectoryTree
423
+ // ... other props
424
+ visual={{ lineColor: scheme === "dark" ? appColours.dark.treeLine : appColours.light.treeLine }}
425
+ />
409
426
  ```
410
427
 
411
428
  ### Custom Styling
@@ -419,23 +436,26 @@ You can customize the appearance by passing custom classes or inline styles for
419
436
  style: { height: '400px' },
420
437
 
421
438
  // Style the entry rows: paint and text only (the row's box is the tree's)
422
- entryClassName: "rounded-md hover:bg-slate-100/50",
439
+ entryClassName: "rounded-md",
423
440
  entryStyle: { letterSpacing: "0.01em", textUnderlineOffset: "2px" },
424
441
 
425
442
  // Style the label text
426
443
  nameClassName: "text-sm font-medium",
427
444
 
428
- // Target directory or file names specifically
429
- directoryNameClassName: "text-slate-800 dark:text-slate-100",
430
- fileNameClassName: "text-slate-600 dark:text-slate-300",
445
+ // Target directory or file names specifically: one light-dark() pair per colour (slate-800 / slate-100 and
446
+ // slate-700 / slate-300 keep 7:1 on the default grounds in both schemes)
447
+ directoryNameClassName: "text-[color:light-dark(#1d293d,#f1f5f9)]",
448
+ fileNameClassName: "text-[color:light-dark(#314158,#cad5e2)]",
431
449
  }}
432
450
  // ... other props
433
451
  />
434
452
  ```
435
453
 
436
454
  The expand glyph drawn in the row (when `showTreeLines` is `false`) takes `expandIconClassName` /
437
- `expandIconStyle` the same way. To make its colour follow your own theme rather than the `dark` class, pass a colour
438
- token through `expandIconStyle`: an inline style wins over every class, the built-in `dark:` colour included.
455
+ `expandIconStyle` the same way. Its default colour is one `light-dark()` class, so a colour class in
456
+ `expandIconClassName` replaces it in both schemes; give a class whose colour has to differ by scheme its own
457
+ `light-dark()` value or a variable, for example `"text-(--app-tree-glyph)"`. A colour token passed through
458
+ `expandIconStyle` wins over every class, the selected-row colour included:
439
459
 
440
460
  ```tsx
441
461
  <DirectoryTree
@@ -444,11 +464,6 @@ token through `expandIconStyle`: an inline style wins over every class, the buil
444
464
  />
445
465
  ```
446
466
 
447
- `expandIconClassName` is merged into the built-in classes like `nameClassName`, so a colour class on its own replaces
448
- only the light default (`text-gray-500`): the built-in `dark:text-gray-400` stays and wins under your `dark` class.
449
- To set the colour with a class, give its `dark:` variant as well, for example
450
- `"text-(--app-tree-glyph) dark:text-(--app-tree-glyph)"`.
451
-
452
467
  Alternatively, you can customize components inside the container using global CSS classes:
453
468
 
454
469
  ```css
@@ -457,23 +472,23 @@ Alternatively, you can customize components inside the container using global CS
457
472
  }
458
473
  ```
459
474
 
460
- 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`:
475
+ 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:
461
476
 
462
477
  ```tsx
463
478
  <DirectoryTree
464
479
  visual={{
465
480
  highlightStyles: {
466
- // Custom hover style
467
- hoverClassName: "bg-amber-100 dark:bg-amber-900/20",
468
- hoverStyle: { boxShadow: "inset -2px 0 0 orange" },
469
-
470
- // Custom directory selection style
471
- directorySelectedClassName: "bg-emerald-100 dark:bg-emerald-900/20 font-bold",
472
- directorySelectedStyle: { boxShadow: "inset 3px 0 0 green" },
473
-
474
- // Custom item (file) selection style
475
- itemSelectedClassName: "bg-indigo-100 dark:bg-indigo-900/20 text-indigo-800",
476
- itemSelectedStyle: { boxShadow: "inset 3px 0 0 indigo" },
481
+ // Custom hover style (amber-50 / amber-950, edge amber-700 / amber-400)
482
+ hoverClassName: "bg-[color:light-dark(#fffbeb,#461901)]",
483
+ hoverStyle: { boxShadow: "inset -2px 0 0 light-dark(#bb4d00, #ffb900)" },
484
+
485
+ // Custom directory selection style (emerald-50 / emerald-950, edge emerald-700 / emerald-400)
486
+ directorySelectedClassName: "bg-[color:light-dark(#ecfdf5,#002c22)] font-bold",
487
+ directorySelectedStyle: { boxShadow: "inset 3px 0 0 light-dark(#007a55, #00d492)" },
488
+
489
+ // Custom item (file) selection style (indigo-50 / indigo-950, text indigo-800 / indigo-200, edge indigo-700 / indigo-300)
490
+ itemSelectedClassName: "bg-[color:light-dark(#eef2ff,#1e1a4d)] text-[color:light-dark(#372aac,#c6d2ff)]",
491
+ itemSelectedStyle: { boxShadow: "inset 3px 0 0 light-dark(#432dd7, #a3b3ff)" },
477
492
  }
478
493
  }}
479
494
  // ... other props
@@ -489,7 +504,7 @@ accept only properties that can neither move nor resize them:
489
504
 
490
505
  | Option | Type | Accepts |
491
506
  | --- | --- | --- |
492
- | `entryStyle`, `highlightStyles.hoverStyle` / `directorySelectedStyle` / `itemSelectedStyle`, `DirectoryEntry.style` | `DirectoryTreeRowStyle` | Paint and text properties (`ROW_STYLE_PROPERTIES`): colour, background, opacity, shadows, filters and blend modes, border colour and radius, outline, accent and caret colour, cursor; font family, size, style, weight, stretch, variant, feature and variation settings, kerning, letter spacing, line height, text decoration and underline offset, text transform |
507
+ | `entryStyle`, `highlightStyles.hoverStyle` / `directorySelectedStyle` / `itemSelectedStyle`, `DirectoryEntry.style` | `DirectoryTreeRowStyle` | Paint and text properties (`ROW_STYLE_PROPERTIES`): colour, background, opacity, shadows, filters and blend modes, border colour and radius, outline, accent and caret colour, cursor; font family, size, style, weight, variant, feature and variation settings, kerning, letter spacing, line height, text decoration and underline offset, text transform |
493
508
  | `expandIconStyle` | `DirectoryTreeExpandIconStyle` | `color` and `opacity` (`EXPAND_ICON_STYLE_PROPERTIES`); the glyph is drawn in `currentColor` |
494
509
 
495
510
  Both lists and both types are exported. Any other property (a size, padding including vertical padding, margin,
@@ -503,6 +518,17 @@ that names the option and the property, for example `visual.entryStyle.height`,
503
518
  mode alike), an entry's `style` whenever its row renders. A property outside the lists whose value is `undefined` sets
504
519
  nothing and is ignored; any other value, `null`, `""` and `0` included, is refused.
505
520
 
521
+ Only the listed names pass: a longhand of a listed shorthand that is not listed itself (`borderTopColor`,
522
+ `fontVariantNumeric`, `backgroundPositionX`) is refused like any other property. A style that is neither `undefined`
523
+ nor an object (`null`, a string, a number) throws a `RangeError` saying that it must be an object of CSS properties or
524
+ undefined, for example `visual.entryStyle must be an object of CSS properties or undefined, got string.`
525
+
526
+ The row styles are laid over each other in a fixed order, the later winning: on a list row the highlight styles
527
+ (`hoverStyle`, then the selected style that applies), then `visual.entryStyle`, then `entry.style`; on a grid row the
528
+ highlight styles, then `entry.style`. The tree writes its own box properties after all of them (the row height, and on
529
+ a list row the indent and the `removeRootIndent` shift), as it writes the 14 px expand box's size after
530
+ `expandIconStyle`.
531
+
506
532
  To change a box, use the sizing options instead: `itemHeight` (row height), `indentSize` (indent per level),
507
533
  `typeIconSize` (icon box) and `fontSize` (label text); see [Sizing](#sizing). Draw a border as a shadow or an outline
508
534
  (`boxShadow: "inset 3px 0 0 green"`), which takes no room.
@@ -555,7 +581,7 @@ Three settings size the parts of a row in list rows and grid rows alike; omitted
555
581
  | --- | --- | --- |
556
582
  | `indentSize` | `12` | The indentation per depth level: a row at depth *d* is padded by *d* ร— `indentSize` (in grid mode, its name cell). |
557
583
  | `typeIconSize` | `14` | The side of the file/folder icon's box. The built-in icons fill the box, so they grow and shrink with it; an icon you supply (`iconOverrides`, `entry.icon`) keeps its own size and is centred in the box. |
558
- | `fontSize` | body step (13 px) | The labels' font size: a number in px or any CSS font size (`'0.875rem'`). Omitted, list rows draw their labels at the body text step (13 px on a 20 px line, see [Text size](#text-size)) and grid rows keep the font size they inherit. A given value wins over the step as an inline style, while the text keeps the step's line height. Rows keep `itemHeight`. |
584
+ | `fontSize` | body step (13 px) | The labels' font size: a number in px or any CSS font size (`'0.875rem'`). Omitted, list rows draw their labels at the body text step (13 px on a 20 px line, see [Text size](#text-size)) and grid rows keep the font size they inherit. A given value wins over the step as an inline style, and the line becomes the larger of the step's line and 1.5 ร— the given size (WCAG 1.4.8). Rows keep `itemHeight`. |
559
585
 
560
586
  From its indentation, every row lays out the 14 px expand box (the chevron, or the tree lines'
561
587
  glyph), the type icon box, then the label. The tree lines follow these sizes at any row height,
@@ -602,9 +628,12 @@ setting even when the host binds nothing:
602
628
  | `--dt-line-height-body` | `1.25rem` (20 px) | The list row (`line-height`: the larger of this and 1.5 ร— the text, so a larger `visual.fontSize` grows the line instead of clipping the label's descenders; the label inherits it) |
603
629
 
604
630
  The host may bind them once on `:root`, for example to its own type scale; the tree only reads them and never declares
605
- them on its own elements. `visual.fontSize` (which replaces only the size), a font-size class in `entryClassName` /
606
- `nameClassName`, and `entryStyle` / `nameStyle` still win over the step. Grid rows' labels keep the font size they
607
- inherit from the host. The row height (`itemHeight`, 44 px by default), the icon box and the tree lines do not depend on
631
+ them on its own elements. The label sets the step's font size on itself (`directoryTreeClasses.name`), so it does not
632
+ take the row's: a size on the row (a font-size class in `entryClassName`, `fontSize` in `entryStyle`) changes the row
633
+ element and its line height (the larger of the step's line and 1.5 ร— the row's text), but not the label's size. The
634
+ label follows `visual.fontSize` (which replaces only the size), a font-size class in `nameClassName`, and `nameStyle`,
635
+ which win over the step; a host that wants the label to follow the row passes `nameStyle: { fontSize: "inherit" }`.
636
+ Grid rows' labels keep the font size they inherit from the host. The row height (`itemHeight`, 44 px by default), the icon box and the tree lines do not depend on
608
637
  the text size.
609
638
 
610
639
  ```css
@@ -771,31 +800,14 @@ rows carry no row-level accessible name (their cells name them), so the kind wor
771
800
  - **Forwarding**: `locale` and the engine keys reach both the embedded `VirtualScroll` and the grid-mode
772
801
  horizontal `ScrollBar`. An inline `labels={{โ€ฆ}}` object is fine: the forwarded engine labels keep their identity
773
802
  while the strings are unchanged, so the virtualized body is not re-rendered.
803
+ - **One surface**: `locale` and `labels` are props of `DirectoryTree` only; the type of the `virtualScroll` options
804
+ (`DirectoryTreeVirtualScrollOptions`) takes neither.
805
+ - **Not a formatting locale**: `locale` switches only the language of the UI chrome; the package has no BCP 47
806
+ formatting axis.
774
807
 
775
808
  Exports: `DirectoryTreeLocale`, `DirectoryTreeLabels`, `DirectoryTreeLabelOverrides`, `DIRECTORY_TREE_LABEL_KEYS`,
776
809
  `DIRECTORY_TREE_LABEL_CATALOGS`, `resolveDirectoryTreeLabels`.
777
810
 
778
- ### Migrating to 3.12.0
779
-
780
- - **Runtime requirement โ€” update `@aiquants/virtualscroll` in the same change**: 3.12.0 imports
781
- `VIRTUAL_SCROLL_LABEL_KEYS`, `VIRTUAL_SCROLL_LABEL_CATALOGS`, `resolveVirtualScrollLocale` and
782
- `resolveVirtualScrollLabels`, which exist only in `@aiquants/virtualscroll` >= 3.7.0 (the published peer range is
783
- `^3.7.0`). A `^3.11.x` caret on this package accepts 3.12.0, so a host that updates only `@aiquants/directory-tree`
784
- while its lockfile keeps virtualscroll 3.6.x gets just an unmet-peer warning from pnpm's default (non-strict) peer
785
- handling, and then a missing-export failure at build or load time. Bump both together, e.g.
786
- `"@aiquants/virtualscroll": "^3.6.1"` โ†’ `"^3.7.0"`.
787
- - **Default output is unchanged**: omitting `locale` renders the same English DOM as 3.11.x. To show the chrome in
788
- Japanese (`ใƒ‡ใ‚ฃใƒฌใ‚ฏใƒˆใƒช` / `ใƒ•ใ‚กใ‚คใƒซ`, `ไธŠใธใ‚นใ‚ฏใƒญใƒผใƒซ`, `้ …็›ฎใŒใ‚ใ‚Šใพใ›ใ‚“`, โ€ฆ) pass `locale="ja"` explicitly โ€”
789
- there is no language negotiation.
790
- - **New API**: the top-level `locale` / `labels` props and the exports listed above.
791
- - **`virtualScroll.locale` / `virtualScroll.labels` are rejected by the type** (they were accepted but silently
792
- dropped before, so they never had an effect): move them to the top-level `locale` / `labels`.
793
- - **`DirectoryEntryItemProps` gains two required fields**, `entryKindDirectory` / `entryKindFile` (the resolved kind
794
- words; take them from `resolveDirectoryTreeLabels(locale, labels)`). Only code that builds this exported type
795
- itself is affected.
796
- - **`locale` is not a formatting locale**: this package has no BCP 47 `formatLocale` axis. `locale` switches the UI
797
- chrome language only; entry names, column headers / footers and `visual.ariaLabel` remain your content.
798
-
799
811
  ## TypeScript Support
800
812
 
801
813
  This package is written in TypeScript and provides comprehensive type definitions. All components and hooks are fully typed for the best development experience.
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);