@aiquants/directory-tree 5.0.0 → 5.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +29 -30
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -33,7 +33,7 @@ This package requires the following peer dependencies:
|
|
|
33
33
|
npm install react react-dom @aiquants/virtualscroll
|
|
34
34
|
```
|
|
35
35
|
|
|
36
|
-
`@aiquants/virtualscroll` must be 3.
|
|
36
|
+
`@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
37
|
|
|
38
38
|
## Quick Start
|
|
39
39
|
|
|
@@ -41,24 +41,26 @@ npm install react react-dom @aiquants/virtualscroll
|
|
|
41
41
|
import React from 'react';
|
|
42
42
|
import { DirectoryTree, useDirectoryTreeState } from '@aiquants/directory-tree';
|
|
43
43
|
import { useTheme } from './hooks/useTheme'; // Your theme hook
|
|
44
|
-
import type { DirectoryEntry } from '@aiquants/directory-tree';
|
|
44
|
+
import type { DirectoryEntry, DirectoryTreeClickEvent } from '@aiquants/directory-tree';
|
|
45
45
|
|
|
46
46
|
const sampleData: DirectoryEntry[] = [
|
|
47
47
|
{
|
|
48
48
|
name: 'src',
|
|
49
|
+
type: 'directory',
|
|
49
50
|
absolutePath: '/src',
|
|
50
51
|
relativePath: 'src',
|
|
51
52
|
children: [
|
|
52
53
|
{
|
|
53
54
|
name: 'components',
|
|
55
|
+
type: 'directory',
|
|
54
56
|
absolutePath: '/src/components',
|
|
55
57
|
relativePath: 'src/components',
|
|
56
58
|
children: [
|
|
57
59
|
{
|
|
58
60
|
name: 'App.tsx',
|
|
61
|
+
type: 'file',
|
|
59
62
|
absolutePath: '/src/components/App.tsx',
|
|
60
|
-
relativePath: 'src/components/App.tsx'
|
|
61
|
-
children: null
|
|
63
|
+
relativePath: 'src/components/App.tsx'
|
|
62
64
|
}
|
|
63
65
|
]
|
|
64
66
|
}
|
|
@@ -489,7 +491,7 @@ accept only properties that can neither move nor resize them:
|
|
|
489
491
|
|
|
490
492
|
| Option | Type | Accepts |
|
|
491
493
|
| --- | --- | --- |
|
|
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,
|
|
494
|
+
| `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
495
|
| `expandIconStyle` | `DirectoryTreeExpandIconStyle` | `color` and `opacity` (`EXPAND_ICON_STYLE_PROPERTIES`); the glyph is drawn in `currentColor` |
|
|
494
496
|
|
|
495
497
|
Both lists and both types are exported. Any other property (a size, padding including vertical padding, margin,
|
|
@@ -503,6 +505,17 @@ that names the option and the property, for example `visual.entryStyle.height`,
|
|
|
503
505
|
mode alike), an entry's `style` whenever its row renders. A property outside the lists whose value is `undefined` sets
|
|
504
506
|
nothing and is ignored; any other value, `null`, `""` and `0` included, is refused.
|
|
505
507
|
|
|
508
|
+
Only the listed names pass: a longhand of a listed shorthand that is not listed itself (`borderTopColor`,
|
|
509
|
+
`fontVariantNumeric`, `backgroundPositionX`) is refused like any other property. A style that is neither `undefined`
|
|
510
|
+
nor an object (`null`, a string, a number) throws a `RangeError` saying that it must be an object of CSS properties or
|
|
511
|
+
undefined, for example `visual.entryStyle must be an object of CSS properties or undefined, got string.`
|
|
512
|
+
|
|
513
|
+
The row styles are laid over each other in a fixed order, the later winning: on a list row the highlight styles
|
|
514
|
+
(`hoverStyle`, then the selected style that applies), then `visual.entryStyle`, then `entry.style`; on a grid row the
|
|
515
|
+
highlight styles, then `entry.style`. The tree writes its own box properties after all of them (the row height, and on
|
|
516
|
+
a list row the indent and the `removeRootIndent` shift), as it writes the 14 px expand box's size after
|
|
517
|
+
`expandIconStyle`.
|
|
518
|
+
|
|
506
519
|
To change a box, use the sizing options instead: `itemHeight` (row height), `indentSize` (indent per level),
|
|
507
520
|
`typeIconSize` (icon box) and `fontSize` (label text); see [Sizing](#sizing). Draw a border as a shadow or an outline
|
|
508
521
|
(`boxShadow: "inset 3px 0 0 green"`), which takes no room.
|
|
@@ -555,7 +568,7 @@ Three settings size the parts of a row in list rows and grid rows alike; omitted
|
|
|
555
568
|
| --- | --- | --- |
|
|
556
569
|
| `indentSize` | `12` | The indentation per depth level: a row at depth *d* is padded by *d* × `indentSize` (in grid mode, its name cell). |
|
|
557
570
|
| `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,
|
|
571
|
+
| `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
572
|
|
|
560
573
|
From its indentation, every row lays out the 14 px expand box (the chevron, or the tree lines'
|
|
561
574
|
glyph), the type icon box, then the label. The tree lines follow these sizes at any row height,
|
|
@@ -602,9 +615,12 @@ setting even when the host binds nothing:
|
|
|
602
615
|
| `--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
616
|
|
|
604
617
|
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
|
-
|
|
618
|
+
them on its own elements. The label sets the step's font size on itself (`directoryTreeClasses.name`), so it does not
|
|
619
|
+
take the row's: a size on the row (a font-size class in `entryClassName`, `fontSize` in `entryStyle`) changes the row
|
|
620
|
+
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
|
|
621
|
+
label follows `visual.fontSize` (which replaces only the size), a font-size class in `nameClassName`, and `nameStyle`,
|
|
622
|
+
which win over the step; a host that wants the label to follow the row passes `nameStyle: { fontSize: "inherit" }`.
|
|
623
|
+
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
624
|
the text size.
|
|
609
625
|
|
|
610
626
|
```css
|
|
@@ -771,31 +787,14 @@ rows carry no row-level accessible name (their cells name them), so the kind wor
|
|
|
771
787
|
- **Forwarding**: `locale` and the engine keys reach both the embedded `VirtualScroll` and the grid-mode
|
|
772
788
|
horizontal `ScrollBar`. An inline `labels={{…}}` object is fine: the forwarded engine labels keep their identity
|
|
773
789
|
while the strings are unchanged, so the virtualized body is not re-rendered.
|
|
790
|
+
- **One surface**: `locale` and `labels` are props of `DirectoryTree` only; the type of the `virtualScroll` options
|
|
791
|
+
(`DirectoryTreeVirtualScrollOptions`) takes neither.
|
|
792
|
+
- **Not a formatting locale**: `locale` switches only the language of the UI chrome; the package has no BCP 47
|
|
793
|
+
formatting axis.
|
|
774
794
|
|
|
775
795
|
Exports: `DirectoryTreeLocale`, `DirectoryTreeLabels`, `DirectoryTreeLabelOverrides`, `DIRECTORY_TREE_LABEL_KEYS`,
|
|
776
796
|
`DIRECTORY_TREE_LABEL_CATALOGS`, `resolveDirectoryTreeLabels`.
|
|
777
797
|
|
|
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
798
|
## TypeScript Support
|
|
800
799
|
|
|
801
800
|
This package is written in TypeScript and provides comprehensive type definitions. All components and hooks are fully typed for the best development experience.
|