@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.
Files changed (2) hide show
  1. package/README.md +29 -30
  2. 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.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).
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, stretch, variant, feature and variation settings, kerning, letter spacing, line height, text decoration and underline offset, text transform |
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, while the text keeps the step's line height. Rows keep `itemHeight`. |
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. `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
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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@aiquants/directory-tree",
3
- "version": "5.0.0",
3
+ "version": "5.0.1",
4
4
  "description": "High-performance directory tree component for React with virtual scrolling and file selection",
5
5
  "sideEffects": [
6
6
  "**/*.css"