@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 +104 -92
- package/dist/cli.js +3 -3
- package/dist/index.cjs +2 -2
- package/dist/index.js +955 -934
- package/dist/palette.d.ts +125 -0
- package/dist/styles/directory-tree.standalone.css +1 -1
- package/dist/types.d.ts +2 -2
- package/package.json +5 -5
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
|
-
- **๐จ
|
|
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
|
-
|
|
29
|
+
pnpm add react react-dom @aiquants/virtualscroll
|
|
34
30
|
```
|
|
35
31
|
|
|
36
|
-
`@aiquants/virtualscroll` must be 3.
|
|
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 {
|
|
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
|
|
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 | `'#
|
|
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,
|
|
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
|
|
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"]
|
|
213
|
-
`contentProps["aria-multiselectable"]`: the tree's name comes from
|
|
214
|
-
|
|
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-
|
|
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.
|
|
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
|
-
|
|
378
|
+
Neither build reads a `.dark` class: the colours follow the host's `color-scheme`.
|
|
386
379
|
|
|
387
|
-
###
|
|
380
|
+
### Colours and color-scheme
|
|
388
381
|
|
|
389
|
-
|
|
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
|
-
```
|
|
392
|
-
|
|
387
|
+
```css
|
|
388
|
+
/* follow the OS */
|
|
389
|
+
:root { color-scheme: light dark; }
|
|
393
390
|
|
|
394
|
-
|
|
395
|
-
|
|
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
|
-
|
|
398
|
-
|
|
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
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
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
|
|
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
|
-
|
|
430
|
-
|
|
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.
|
|
438
|
-
|
|
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-
|
|
468
|
-
hoverStyle: { boxShadow: "inset -2px 0 0
|
|
469
|
-
|
|
470
|
-
// Custom directory selection style
|
|
471
|
-
directorySelectedClassName: "bg-
|
|
472
|
-
directorySelectedStyle: { boxShadow: "inset 3px 0 0
|
|
473
|
-
|
|
474
|
-
// Custom item (file) selection style
|
|
475
|
-
itemSelectedClassName: "bg-
|
|
476
|
-
itemSelectedStyle: { boxShadow: "inset 3px 0 0
|
|
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,
|
|
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,
|
|
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.
|
|
606
|
-
|
|
607
|
-
|
|
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),
|
|
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(
|
|
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:
|
|
115
|
+
r.info(`Unknown command: ${n[0]}`), r.info("Usage: node dist/cli.js demo"), process.exit(1);
|