@aiquants/directory-tree 6.1.3 → 6.2.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
@@ -138,7 +138,7 @@ The main component for rendering the directory tree.
138
138
  | Prop | Type | Required | Default | Description |
139
139
  | --- | --- | --- | --- | --- |
140
140
  | `onEntryClick` | `(event: DirectoryTreeClickEvent) => void` | Yes | - | Callback function triggered when an entry is clicked |
141
- | `selectedPath` | `string \| null` | No | - | The currently selected file path (highlighted with `data-entry-selected`). In classic mode the selected row is also where the tree's Tab stop starts (grid rows are each a Tab stop) — see [Keyboard and focus](#keyboard-and-focus) |
141
+ | `selectedPath` | `string \| null` | No | - | The currently selected file path (highlighted with `data-entry-selected`). The selected row is also where the tree's Tab stop starts, in classic and grid mode alike — see [Keyboard and focus](#keyboard-and-focus) |
142
142
  | `currentPath` | `string \| null` | No | - | The entry the host shows as current (for example the open document). Its row carries `aria-current="page"` in every selection mode, so assistive technology can tell the shown entry from the selected set in multiple selection. The tree draws no style for it; style `[aria-current="page"]` yourself |
143
143
  | `mode` | `'none' \| 'single' \| 'multiple'` | No | `'none'` | Selection mode for items |
144
144
  | `selectedItems` | `Set<string>` | No | - | Set of paths for currently selected items |
@@ -152,7 +152,7 @@ The main component for rendering the directory tree.
152
152
  | `style` | `React.CSSProperties` | No | - | Optional inline styles for the container |
153
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) |
154
154
  | `showTreeLines` | `boolean` | No | `true` | Flag indicating whether to render tree connector lines |
155
- | `showExpandIcons` | `boolean` | No | `true` | Flag indicating whether to render directory expand icons |
155
+ | `showExpandIcons` | `boolean` | No | `true` | Flag indicating whether to render directory expand icons. It also governs the glyphs drawn on the tree-line canvas while `showTreeLines` is `true`: with `false` no directory draws a glyph, the lines run through a directory row as they run through a file row (a last directory child ends in the same elbow as a last file), and the expand box keeps its column, so every line stays where it was |
156
156
  | `showDirectoryIcons` | `boolean` | No | `true` | Flag indicating whether to render directory type icons |
157
157
  | `showFileIcons` | `boolean` | No | `true` | Flag indicating whether to render file type icons |
158
158
  | `iconOverrides` | `DirectoryTreeIconOverrides` | No | - | Icon overrides applied globally |
@@ -180,7 +180,7 @@ The main component for rendering the directory tree.
180
180
 
181
181
  - `overscanCount`: Adjust how many items render beyond the viewport for smoother scrolling (default: `15`).
182
182
  - `scrollBarOptions`: Configure scrollbar appearance and behavior (width, thumb drag, track click, arrow buttons, tap scroll circle).
183
- A host that drives the classic tree from the keyboard can pass `enableArrowButtonTabStops: false` to make the scrollbar and the
183
+ A host that drives the tree from the keyboard (classic or grid mode) can pass `enableArrowButtonTabStops: false` to make the scrollbar and the
184
184
  Top/Bottom buttons pointer-only: the tree's own arrow keys, Home and End keep the focused row in view. In grid mode the option
185
185
  reaches the vertical scrollbar and the Top/Bottom buttons only; the horizontal scrollbar of the numeric columns keeps its arrow
186
186
  buttons as Tab stops, because it is the only keyboard path to the columns scrolled out of view.
@@ -233,7 +233,9 @@ Example:
233
233
 
234
234
  ### Keyboard and focus
235
235
 
236
- The classic tree follows the WAI-ARIA tree pattern with a roving tabindex: it always has exactly one Tab stop.
236
+ The tree follows the WAI-ARIA tree pattern (grid mode: the treegrid pattern with focus on rows) with a roving tabindex:
237
+ it always has exactly one Tab stop. Grid mode has the same keyboard model as the classic tree; only the roles differ
238
+ (`treegrid` / `row` instead of `tree` / `treeitem`).
237
239
 
238
240
  - **Where Tab enters**: the row that last received focus — while it still holds focus, or while the selection has not
239
241
  changed since it received focus — else the selected row (`selection.selectedPath`), else the first row. A candidate
@@ -248,7 +250,9 @@ The classic tree follows the WAI-ARIA tree pattern with a roving tabindex: it al
248
250
  collapsed folder or moves to its first child (an open folder without child rows keeps the focus), `ArrowLeft` closes
249
251
  an open folder or moves to the parent, `Enter` and `Space` activate the row once per press (the auto-repeat of a held
250
252
  key only has its default action prevented, so a held key never flips a folder or a gathered entry back and forth).
251
- Grid rows activate on `Enter` with the same rule.
253
+ Activation does what a click does — `selection.onEntryClick`, and the selection toggle of a file in a selection
254
+ mode — except that a folder opens or closes at once: a click waits 500 ms to tell a single click from a double click
255
+ (which expands the folder recursively), and a key press has no double press to wait for.
252
256
  - **Keys with Alt, Ctrl or ⌘ are not the tree's**: an arrow key, `Home` or `End` held with Alt, Ctrl or Meta (⌘) is
253
257
  neither handled nor has its default action prevented, so the browser's history keys (Alt+Left / Alt+Right,
254
258
  ⌘+Left / ⌘+Right) and a host's own shortcuts on them (for example Alt+Shift+Arrow) work while a row has focus.
@@ -263,9 +267,11 @@ The classic tree follows the WAI-ARIA tree pattern with a roving tabindex: it al
263
267
  double-click hit the same row. A row that gets focus back because the window or browser tab became active again is not
264
268
  scrolled: focus never left it, and the browser does not scroll there either.
265
269
  - **Rows outside the render window**: when the Tab stop row is virtualized away, a visually hidden stand-in Tab stop
266
- (`data-directory-tree-tab-stop`, outside `role="tree"`) takes its place in the Tab order; when it receives focus it
270
+ (`data-directory-tree-tab-stop`, outside `role="tree"` in classic mode) takes its place in the Tab order; when it receives focus it
267
271
  scrolls the Tab stop row into view and hands the focus to it. A host that hands focus to the tree by selector should
268
- look for `[role="tree"] [role="treeitem"][tabindex="0"]` and then `[data-directory-tree-tab-stop]`. The stand-in
272
+ look for `[role="tree"] [role="treeitem"][tabindex="0"]` (grid mode: `[role="treegrid"] [role="row"][tabindex="0"]`)
273
+ and then `[data-directory-tree-tab-stop]`. Only the Tab stop row carries `tabindex="0"`; every other row carries
274
+ `tabindex="-1"`, so a selector for `tabindex="0"` finds that one row, not every row. The stand-in
269
275
  appears in the render that follows the one where the Tab stop row left the render window (the tree measures that
270
276
  in its own layout effect), so look it up after that commit, not in a layout effect of the same commit.
271
277
 
@@ -274,9 +280,9 @@ content element, which owns only the rows: the scrollbar, the Top/Bottom buttons
274
280
  (`virtualScroll.liveRegion`) stay outside the tree, and the wrappers between the tree and its rows carry no role,
275
281
  tabindex or ARIA attribute. The root container has no role; target it through `visual.className`.
276
282
 
277
- Grid mode (`grid`) differs: every grid row is a Tab stop and the rows have no arrow-key navigation, and
278
- `role="treegrid"` sits on the root container, so the vertical and horizontal scrollbars and the live region are inside
279
- the treegrid.
283
+ Grid mode (`grid`) differs in structure only: `role="treegrid"` sits on the root container, so the vertical and
284
+ horizontal scrollbars, the live region and the stand-in Tab stop are inside the treegrid. The stand-in stands just before
285
+ the rowgroup of the body rows (outside every rowgroup), at the rows' place in the Tab order.
280
286
 
281
287
  ### Scroll handle (`ref`)
282
288
 
@@ -1,6 +1,6 @@
1
1
  import { directoryTreeClasses } from "./entryRendering.tsx";
2
2
  import { TreeLineLayout } from "./rowSizing.ts";
3
3
  import { DirectoryTreeProps, TreeLineGeometry, TreeLineItemInfo } from "./types.ts";
4
- export declare const buildTreeLineGeometry: (items: TreeLineItemInfo[], itemHeights: number[], itemOffsets: number[], layout: TreeLineLayout) => TreeLineGeometry;
4
+ export declare const buildTreeLineGeometry: (items: TreeLineItemInfo[], itemHeights: number[], itemOffsets: number[], layout: TreeLineLayout, showExpandGlyphs: boolean) => TreeLineGeometry;
5
5
  export declare const DirectoryTree: ({ entries, expansion: { toggle, isExpanded, expandMultiple, collapseMultiple, isPending, alwaysExpanded, doubleClickAction }, selection: { onEntryClick, selectedPath, currentPath, mode: selectionMode, selectedItems, onSelectionChange }, visual: { className, style, ariaLabel, ariaLabelledBy, lineColor, showTreeLines, showExpandIcons, showDirectoryIcons, showFileIcons, iconOverrides, expandIconSize, typeIconSize, fontSize, indentSize, itemHeight, removeRootIndent, highlightStyles, entryClassName, entryStyle, nameClassName, nameStyle, directoryNameClassName, directoryNameStyle, fileNameClassName, fileNameStyle, expandIconClassName, expandIconStyle, }, virtualScroll: virtualScrollOptions, grid, sort, locale, labels, ref, }: DirectoryTreeProps) => import("react").JSX.Element;
6
6
  export { directoryTreeClasses };
@@ -1,3 +1,4 @@
1
+ import { KeyboardEvent } from "react";
1
2
  import { DirectoryTreeExpandIconStyle } from "./hostStyle.ts";
2
3
  import { DirectoryEntry, DirectoryTreeColumn, DirectoryTreeIconOverrides, HighlightStyles } from "./types.ts";
3
4
  export type GridRowVisual = {
@@ -22,6 +23,9 @@ export type DirectoryTreeGridRowProps = {
22
23
  setSize: number;
23
24
  rowIndex: number;
24
25
  flatIndex: number;
26
+ isActive: boolean;
27
+ registerRowRef: (index: number, node: HTMLDivElement | null) => void;
28
+ onNavigationKeyDown: (event: KeyboardEvent<HTMLDivElement>, index: number) => void;
25
29
  onRowFocus: (index: number, path: string, row: HTMLElement) => void;
26
30
  onRowBlur: (path: string, row: HTMLElement) => void;
27
31
  isSelectedForAria: boolean;