@aiquants/directory-tree 3.11.0 → 3.11.2

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 (45) hide show
  1. package/dist/DirectoryTree.d.ts +2 -21
  2. package/dist/DirectoryTreeGrid.d.ts +3 -17
  3. package/dist/TreeLine.d.ts +2 -8
  4. package/dist/cli.server.d.ts +0 -1
  5. package/dist/entryRendering.d.ts +2 -42
  6. package/dist/gridUtils.d.ts +1 -30
  7. package/dist/index.cjs +2 -2
  8. package/dist/index.d.ts +3 -14
  9. package/dist/index.js +101 -101
  10. package/dist/logger.d.ts +0 -63
  11. package/dist/scrollAnchor.d.ts +0 -28
  12. package/dist/styles/directory-tree.standalone.css +1 -1
  13. package/dist/types.d.ts +3 -497
  14. package/dist/useDirectoryTreeState.d.ts +1 -14
  15. package/dist/useEntryInteraction.d.ts +2 -8
  16. package/package.json +6 -7
  17. package/dist/DirectoryTree.d.ts.map +0 -1
  18. package/dist/DirectoryTreeGrid.d.ts.map +0 -1
  19. package/dist/TreeLine.d.ts.map +0 -1
  20. package/dist/cli.server.d.ts.map +0 -1
  21. package/dist/entryRendering.d.ts.map +0 -1
  22. package/dist/gridUtils.d.ts.map +0 -1
  23. package/dist/index.d.ts.map +0 -1
  24. package/dist/logger.d.ts.map +0 -1
  25. package/dist/scrollAnchor.d.ts.map +0 -1
  26. package/dist/types.d.ts.map +0 -1
  27. package/dist/useDirectoryTreeState.d.ts.map +0 -1
  28. package/dist/useEntryInteraction.d.ts.map +0 -1
  29. package/src/DirectoryTree.tsx +0 -1257
  30. package/src/DirectoryTreeGrid.tsx +0 -285
  31. package/src/TreeLine.tsx +0 -300
  32. package/src/cli.server.ts +0 -38
  33. package/src/entryRendering.tsx +0 -299
  34. package/src/gridUtils.ts +0 -88
  35. package/src/index.ts +0 -32
  36. package/src/logger.ts +0 -162
  37. package/src/scrollAnchor.spec.ts +0 -105
  38. package/src/scrollAnchor.ts +0 -86
  39. package/src/styles/components.entry.css +0 -10
  40. package/src/styles/directory-tree.css +0 -87
  41. package/src/styles/standalone.entry.css +0 -12
  42. package/src/types.ts +0 -761
  43. package/src/useDirectoryTreeState.ts +0 -133
  44. package/src/useEntryInteraction.ts +0 -74
  45. package/src/virtualScrollOptionsSeal.spec.ts +0 -43
package/src/types.ts DELETED
@@ -1,761 +0,0 @@
1
- /**
2
- * @file This file defines types related to the DirectoryTree component.
3
- * このファイルは、DirectoryTree コンポーネントに関連する型を定義します。
4
- */
5
-
6
- import type { VirtualScroll } from "@aiquants/virtualscroll"
7
- import type { ComponentProps, CSSProperties, ReactNode } from "react"
8
-
9
- /**
10
- * @type DirectoryEntry
11
- * @description Represents an entry in the directory tree, which can be a file or a directory.
12
- * ディレクトリツリー内のエントリを表す。ファイルまたはディレクトリの場合がある。
13
- * @property {string} name - Name of the entry. エントリ名。
14
- * @property {ReactNode} [label] - Optional label to render instead of name. 名前のかわりに描画する任意のラベル。
15
- * @property {"file" | "directory"} type - Type of the entry. エントリの種別。
16
- * @property {string} absolutePath - Absolute path of the entry. エントリの絶対パス。
17
- * @property {string} relativePath - Relative path of the entry. エントリの相対パス。
18
- * @property {DirectoryEntry[]} [children] - Child entries if it's a directory. ディレクトリの場合の子エントリ。
19
- * @property {DirectoryTreeIconRenderer} [icon] - Optional icon renderer for the entry. エントリ用の任意のアイコン描画設定。
20
- */
21
- export type DirectoryEntry = {
22
- name: string
23
- label?: ReactNode
24
- type: "file" | "directory"
25
- absolutePath: string
26
- relativePath: string
27
- mimeType?: string
28
- children?: DirectoryEntry[]
29
- icon?: DirectoryTreeIconRenderer
30
- /**
31
- * Optional CSS class name for the entry.
32
- * エントリ用のオプション CSS クラス名。
33
- */
34
- className?: string
35
- /**
36
- * Optional inline styles for the entry.
37
- * エントリ用のオプションのインラインスタイル。
38
- */
39
- style?: CSSProperties
40
- /**
41
- * Extra `data-*` attributes rendered on this entry's row. Keys are given **without** the
42
- * `data-` prefix (`{ open: true }` renders `data-open="true"`); values are stringified.
43
- * camelCase keys are converted to kebab-case exactly as the DOM `dataset` API does
44
- * (`{ panelCount: 2 }` renders `data-panel-count="2"`).
45
- *
46
- * この行へ付与する追加の `data-*` 属性。キーは `data-` を**含めずに**渡し
47
- * (`{ open: true }` は `data-open="true"` になる)、値は文字列化される。
48
- * camelCase のキーは DOM の `dataset` と同じ規約で kebab-case へ変換される
49
- * (`{ panelCount: 2 }` は `data-panel-count="2"`)。
50
- *
51
- * @remarks 用途は、状態を CSS クラスではなく属性として公開し、テストやスタイルが
52
- * クラス名に依存しないようにすること。クラス名は整形や prefix 変更で無言に壊れる。
53
- * このコンポーネント自身が出力する `data-entry-*` は上書きできない (常に後勝ち)。
54
- */
55
- data?: Record<string, string | number | boolean>
56
- }
57
-
58
- /**
59
- * Comparator applied to a sibling group before the tree is flattened into rows.
60
- * Receives two entries that share the same parent and returns the usual
61
- * `Array.prototype.sort` ordering number.
62
- *
63
- * ツリーを行へフラット化する前に、同一の親を持つ兄弟グループへ適用する比較関数。
64
- * 戻り値は `Array.prototype.sort` と同じ順序数値。
65
- */
66
- export type DirectoryEntryComparator = (a: DirectoryEntry, b: DirectoryEntry) => number
67
-
68
- /**
69
- * Row height for directory tree entries.
70
- * Either a fixed pixel value applied to every row, or a function computing the
71
- * height per entry (for variable-height rows). When a function is supplied it
72
- * receives the entry and its flattened (visible) index.
73
- *
74
- * ディレクトリツリー各行の高さ。
75
- * 全行に適用する固定ピクセル値、またはエントリごとに高さを算出する関数(可変高さ行)。
76
- * 関数を渡す場合は、エントリとフラット化後(表示上)のインデックスが渡される。
77
- *
78
- * @remarks
79
- * 関数を渡す場合は参照を安定させること(例: `useCallback`)。identity が毎レンダー
80
- * 変わると仮想スクロールの高さモデルが都度再計算され、パフォーマンスが劣化する。
81
- *
82
- * 不正値(`NaN` / `Infinity` / `0` / 負値)を返した行は既定 20px にフォールバックする。
83
- *
84
- * 高さを実行時に変更する場合、可視外アイテムのスクロールバー総高は一時的に旧値のまま
85
- * となり、スクロールに伴い自己修復される(表示中の行と接続線は即座に正確)。変更直後から
86
- * 総高を厳密にしたい場合は `virtualScroll.behaviorOptions.resetOnGetItemHeightChange` を
87
- * 有効化する。
88
- */
89
- export type ItemHeight = number | ((entry: DirectoryEntry, index: number) => number)
90
-
91
- /**
92
- * Context object passed to icon renderer functions.
93
- * アイコン描画関数に渡されるコンテキストオブジェクト。
94
- */
95
- export type DirectoryTreeIconRenderContext = {
96
- entry: DirectoryEntry
97
- isDirectory: boolean
98
- isExpanded: boolean
99
- isSelected: boolean
100
- isItemSelected: boolean
101
- extension?: string
102
- mimeType?: string
103
- }
104
-
105
- /**
106
- * Type definition for icon renderer.
107
- * アイコン描画ロジックの定義。
108
- */
109
- export type DirectoryTreeIconRenderer = ReactNode | ((context: DirectoryTreeIconRenderContext) => ReactNode)
110
-
111
- /**
112
- * Icon override options for directory tree entries.
113
- * ディレクトリツリーエントリのアイコン差し替えオプション。
114
- */
115
- export type DirectoryTreeIconOverrides = {
116
- directory?: DirectoryTreeIconRenderer
117
- directoryExpanded?: DirectoryTreeIconRenderer
118
- file?: DirectoryTreeIconRenderer
119
- fileByExtension?: Record<string, DirectoryTreeIconRenderer>
120
- }
121
-
122
- /**
123
- * Highlight styles configuration for hover and selection states.
124
- * ホバー時および選択時のハイライトスタイルの設定。
125
- */
126
- export type HighlightStyles = {
127
- /** CSS class name for hover state. / ホバー時の CSS クラス名。 */
128
- hoverClassName?: string
129
- /** Inline style for hover state. / ホバー時のインラインスタイル。 */
130
- hoverStyle?: CSSProperties
131
- /** CSS class name for selected directory. / ディレクトリ選択時の CSS クラス名。 */
132
- directorySelectedClassName?: string
133
- /** Inline style for selected directory. / ディレクトリ選択時のインラインスタイル。 */
134
- directorySelectedStyle?: CSSProperties
135
- /** CSS class name for selected item (file). / アイテム(ファイル)選択時の CSS クラス名。 */
136
- itemSelectedClassName?: string
137
- /** Inline style for selected item (file). / アイテム(ファイル)選択時のインラインスタイル。 */
138
- itemSelectedStyle?: CSSProperties
139
- }
140
-
141
- /**
142
- * Event object passed to the onEntryClick callback.
143
- * onEntryClick コールバックに渡されるイベントオブジェクト。
144
- */
145
- export type DirectoryTreeClickEvent = {
146
- /** The entry that was clicked. / クリックされたエントリ。 */
147
- entry: DirectoryEntry
148
- /** Whether the entry is a directory. / エントリがディレクトリかどうか。 */
149
- isDirectory: boolean
150
- /** Whether the directory is currently expanded (always false for files). / ディレクトリが展開中か (ファイルは常に false)。 */
151
- isExpanded: boolean
152
- /**
153
- * Call to prevent the default behavior.
154
- * For directories, this prevents the expand/collapse toggle.
155
- * For files, this is a no-op (there is no default behavior to prevent).
156
- *
157
- * デフォルト動作を抑制する。
158
- * ディレクトリの場合、展開/折りたたみのトグルを抑制する。
159
- * ファイルの場合、抑制するデフォルト動作がないため何もしない。
160
- */
161
- preventDefault: () => void
162
- }
163
-
164
- /**
165
- * Options for configuring virtual scroll behavior.
166
- * 仮想スクロールの挙動を設定するためのオプション。
167
- *
168
- * ❗ **横軸のシームは丸ごと封じる。** DirectoryTree は横スクロールを自前で所有する
169
- * (`onWheelHorizontal` を内部結線する) ため、`onWheelHorizontal` に加えて、同じシームに属する
170
- * `horizontalKeyInputs` / `horizontalKeyStep` (virtualscroll 2.5.0 でトップレベルに追加) も
171
- * 除外する。これらが素通りすると、封じたはずの横軸へキーボード経由で到達でき、`"arrow"` 指定は
172
- * ツリー自身の ArrowLeft / ArrowRight (折りたたみ / 展開) ナビゲーションと競合する。
173
- */
174
- export type DirectoryTreeVirtualScrollOptions = Omit<ComponentProps<typeof VirtualScroll>, "itemCount" | "getItem" | "getItemHeight" | "children" | "viewportSize" | "onWheelHorizontal" | "horizontalKeyInputs" | "horizontalKeyStep" | "ref"> & {
175
- /** Override for viewport height. / 内部計測をスキップするための任意の固定ビューポート高さ。 */
176
- viewportHeightOverride?: number
177
- /**
178
- * Keeps the first visible row visually stationary when the row list mutates
179
- * (e.g. streaming insertions above the viewport). Applies only while scrolled
180
- * away from the top; at the top the list stays top-anchored as usual.
181
- *
182
- * 行リストの変異時 (ストリーミング追記など) に先頭可視行を画面上で静止させる。
183
- * 最上部 (scroll 0) では通常どおり先頭アンカーのままとし、スクロール中のみ作用する。
184
- */
185
- preserveScrollAnchor?: boolean
186
- }
187
-
188
- /**
189
- * Compile-time constraint: the type parameter must be `never`.
190
- * コンパイル時制約: 型引数が `never` であることを強制する補助型。
191
- */
192
- type MustBeNever<T extends never> = T
193
-
194
- /**
195
- * Compile-time seal guard for the horizontal-axis seam of
196
- * {@link DirectoryTreeVirtualScrollOptions}. If any sealed prop ever leaks back into the
197
- * type (i.e. someone drops it from the `Omit<>` list), `Extract` yields that key instead
198
- * of `never` and this line becomes a TS2344 compile error naming the leaked prop. A RENAME
199
- * on the `@aiquants/virtualscroll` side is NOT caught (the leak then re-grows under the
200
- * new name, which this list cannot know) — that case is owned by the pass-through review
201
- * that accompanies every virtualscroll version bump.
202
- *
203
- * {@link DirectoryTreeVirtualScrollOptions} の横軸シーム封印のコンパイル時ガード。封じた
204
- * props が型へ漏れ戻ると (`Omit<>` リストからの脱落)、`Extract` が `never` でなく漏れた
205
- * キーを返し、この行が漏れた prop 名入りの TS2344 コンパイルエラーになる仕組み。
206
- * virtualscroll 側の**リネーム**は捕まらない (新名で漏れ戻るため本リストでは知り得ない) —
207
- * その系は virtualscroll 版上げ時の pass-through 見直しが受け持つ。
208
- *
209
- * 消費者視点の対 (封印 3 props の代入拒否 + 封じていない props が通る陽性コントロール) は
210
- * `virtualScrollOptionsSeal.spec.ts` が持つ。テスト側の `@ts-expect-error` が機能するのは
211
- * `tsconfig.json` が spec / test ファイルを型検査対象に含めているからであり (3.10.0 で
212
- * exclude を撤去)、除外へ戻すとテスト側ガードは誰にも検査されない空砲に戻る
213
- * (旧構成で変異検証により実証済み)。本ガードは定義の隣で `Omit<>` リスト自体を固定する。
214
- */
215
- export type HorizontalSeamSealGuard = MustBeNever<Extract<keyof DirectoryTreeVirtualScrollOptions, "onWheelHorizontal" | "horizontalKeyInputs" | "horizontalKeyStep" | "ref">>
216
-
217
- /**
218
- * A single column definition for the TreeGrid (columns) mode.
219
- * `columns[0]` is always the name / tree column (indent + expand glyph + type icon live here).
220
- *
221
- * TreeGrid(列)モードの列定義。`columns[0]` は常に名前(ツリー)列。
222
- *
223
- * @remarks
224
- * `render` / `footer` の関数は参照を安定させること(`useMemo` / `useCallback`)。
225
- * identity が毎レンダー変わると行のメモ化が無効化され、可視行が毎回再描画されて
226
- * 仮想スクロールの利点が失われる(`ItemHeight` と同じ制約)。
227
- */
228
- export type DirectoryTreeColumn = {
229
- /** Unique column key (duplicates are flagged in dev). / 一意なキー(dev で重複検証)。 */
230
- key: string
231
- /** Column header content. / 列ヘッダ内容。 */
232
- header?: ReactNode
233
- /**
234
- * Footer content. The function form receives **every node of the `entries` prop
235
- * (including collapsed subtrees)**, not just the visible rows.
236
- * フッタ内容。関数形は entries prop の全ノード(折り畳み subtree 含む)を受け取る。
237
- */
238
- footer?: ReactNode | ((allEntries: DirectoryEntry[]) => ReactNode)
239
- /**
240
- * Column width in px. The name column (`columns[0]`) uses this as its frozen width;
241
- * numeric columns use it as the grid track width.
242
- * 列幅(px)。名前列は凍結幅、数値列は grid track 幅として使用。
243
- * 既定: 名前列 240、数値列 96。
244
- */
245
- width?: number
246
- /** Cell text alignment. Default `left` (numeric columns should use `right`). / セル寄せ。既定 left。 */
247
- align?: "left" | "right" | "center"
248
- /** Extra class name for cells in this column. / この列のセルに付与する追加クラス。 */
249
- className?: string
250
- /**
251
- * Cell content renderer. In the name column the indent / expand glyph / type icon are
252
- * drawn by the library, and this render output is placed as the label content
253
- * (falls back to `entry.name` when omitted).
254
- * セル内容レンダラ。名前列では indent/glyph/icon はライブラリが描画し、本 render の
255
- * 戻り値がラベル内容として配置される(省略時は `entry.name`)。
256
- */
257
- render?: (entry: DirectoryEntry, ctx: { indentLevel: number; isDirectory: boolean; isExpanded: boolean }) => ReactNode
258
- }
259
-
260
- /**
261
- * TreeGrid (columns) mode configuration. When provided, the name column is frozen on the
262
- * left (indent + connector lines confined there) and the remaining columns render as an
263
- * aligned grid with an aligned header/footer and a horizontally scrollable numeric region.
264
- * When omitted, the classic label-based tree rendering is used.
265
- *
266
- * TreeGrid(列)モード設定。指定時は名前列を凍結し数値列を整列グリッドで描画、整列ヘッダ/フッタと
267
- * 数値領域の横スクロールを提供する。省略時は従来のラベルツリー描画。
268
- *
269
- * @remarks `columns` と各 `render` / `footer` は参照安定必須。
270
- */
271
- export type DirectoryTreeGrid = {
272
- /** Column definitions (**stable reference required**). `columns[0]` is the name/tree column. / 列定義(参照安定必須)。 */
273
- columns: DirectoryTreeColumn[]
274
- /** Render the header row. Default true. / ヘッダ行表示。既定 true。 */
275
- showHeader?: boolean
276
- /** Render the footer row. Default false. / フッタ行表示。既定 false。 */
277
- showFooter?: boolean
278
- /** Extra class for the header row. / ヘッダ行の追加クラス。 */
279
- headerClassName?: string
280
- /** Extra class for the footer row. / フッタ行の追加クラス。 */
281
- footerClassName?: string
282
- /** Extra class (or per-entry factory) for body rows. / 行の追加クラス(またはエントリ別ファクトリ)。 */
283
- rowClassName?: string | ((entry: DirectoryEntry) => string)
284
- /**
285
- * Vertical scrollbar width, used to keep the header/footer numeric viewport aligned with
286
- * the body (whose width is reduced by the vertical scrollbar). Default 12.
287
- * 縦スクロールバー幅。ヘッダ/フッタの数値ビューポート幅を本体と一致させるために使用。既定 12。
288
- */
289
- scrollBarWidth?: number
290
- }
291
-
292
- /**
293
- * Represents the state and actions for a directory tree.
294
- * ディレクトリツリーの状態とアクションを表します。
295
- */
296
- export type DirectoryTreeState = {
297
- /**
298
- * A set of strings representing the paths of the expanded directories.
299
- * 展開されているディレクトリのパスを表す文字列のセット。
300
- */
301
- expanded: Set<string>
302
- /**
303
- * Toggles the expansion state of a directory.
304
- * ディレクトリの展開状態を切り替えます。
305
- * @param path - The path of the directory to toggle.
306
- */
307
- toggle: (path: string) => void
308
- /**
309
- * Expands a directory.
310
- * ディレクトリを展開します。
311
- * @param path - The path of the directory to expand.
312
- */
313
- expand: (path: string) => void
314
- /**
315
- * Collapses a directory.
316
- * ディレクトリを折りたたみます。
317
- * @param path - The path of the directory to collapse.
318
- */
319
- collapse: (path: string) => void
320
- /**
321
- * Collapses multiple specified directories.
322
- * 指定された複数のディレクトリを折りたたみます。
323
- * @param paths - An array of directory paths to collapse.
324
- */
325
- collapseMultiple: (paths: string[]) => void
326
- /**
327
- * Expands multiple specified directories.
328
- * 指定された複数のディレクトリを展開します。
329
- * @param paths - An array of directory paths to expand.
330
- */
331
- expandMultiple: (paths: string[]) => void
332
- /**
333
- * Collapses all directories.
334
- * すべてのディレクトリを折りたたみます。
335
- */
336
- collapseAll: () => void
337
- /**
338
- * Checks if a directory is expanded.
339
- * ディレクトリが展開されているかどうかを確認します。
340
- * @param path - The path of the directory to check.
341
- * @returns True if the directory is expanded, false otherwise.
342
- */
343
- isExpanded: (path: string) => boolean
344
- /**
345
- * A boolean that is true if a transition is pending.
346
- * トランジションが保留中の場合に true となる真偽値。
347
- */
348
- isPending: boolean
349
- }
350
-
351
- /**
352
- * @type DirectoryTreeProps
353
- * @description Props for the DirectoryTree component.
354
- * DirectoryTree コンポーネントの Props。
355
- */
356
- export type DirectoryTreeProps = {
357
- /**
358
- * The directory entries to display.
359
- * 表示するディレクトリエンティティの配列。
360
- */
361
- entries: DirectoryEntry[]
362
-
363
- /**
364
- * Configuration for tree expansion state and behavior.
365
- * ツリーの展開状態と動作の設定。
366
- */
367
- expansion: {
368
- /**
369
- * Function to toggle the expansion state of a directory.
370
- * ディレクトリの展開状態を切り替える関数。
371
- */
372
- toggle: (path: string) => void
373
- /**
374
- * Function to check if a directory is expanded.
375
- * ディレクトリが展開されているか確認する関数。
376
- */
377
- isExpanded: (path: string) => boolean
378
- /**
379
- * Function to expand multiple specified directories.
380
- * 指定された複数のディレクトリを展開する関数。
381
- */
382
- expandMultiple: (paths: string[]) => void
383
- /**
384
- * Function to collapse all specified directories.
385
- * 指定されたすべてのディレクトリを折りたたむ関数。
386
- */
387
- collapseMultiple: (paths: string[]) => void
388
- /**
389
- * Flag to indicate if the tree is in a pending state.
390
- * ツリーが保留状態かどうかを示すフラグ。
391
- */
392
- isPending?: boolean
393
- /**
394
- * If true, all directories are always expanded.
395
- * true の場合、すべてのディレクトリが常に展開されます。
396
- */
397
- alwaysExpanded?: boolean
398
- /**
399
- * The action to perform on double-clicking a directory.
400
- * ディレクトリをダブルクリックしたときのアクション。
401
- */
402
- doubleClickAction?: "toggle" | "recursive"
403
- }
404
-
405
- /**
406
- * Configuration for item selection.
407
- * アイテム選択の設定。
408
- */
409
- selection: {
410
- /**
411
- * Selection mode for items.
412
- * アイテムの選択モード。
413
- */
414
- mode?: "none" | "single" | "multiple"
415
- /**
416
- * The currently selected path.
417
- * 現在選択されているパス。
418
- */
419
- selectedPath?: string | null
420
- /**
421
- * Set of paths for currently selected items.
422
- * 現在選択されているアイテムのパスのセット。
423
- */
424
- selectedItems?: Set<string>
425
- /**
426
- * Callback when an entry (file or directory) is clicked.
427
- * エントリ(ファイルまたはディレクトリ)がクリックされたときのコールバック。
428
- *
429
- * For files: called immediately on click.
430
- * For directories: called immediately on click, then expand/collapse follows
431
- * unless preventDefault() is called on the event.
432
- *
433
- * ファイルの場合: クリック時に即座に呼ばれる。
434
- * ディレクトリの場合: クリック時に即座に呼ばれ、イベントで preventDefault() が
435
- * 呼ばれない限り展開/折りたたみが続行される。
436
- */
437
- onEntryClick: (event: DirectoryTreeClickEvent) => void
438
- /**
439
- * Callback when item selection changes.
440
- * アイテム選択状態変更時のコールバック。
441
- */
442
- onSelectionChange?: (entry: DirectoryEntry, isSelected: boolean) => void
443
- }
444
-
445
- /**
446
- * Visual customization options.
447
- * 表示のカスタマイズオプション。
448
- */
449
- visual?: {
450
- /**
451
- * Optional CSS class name for the container.
452
- * コンテナ用のオプション CSS クラス名。
453
- */
454
- className?: string
455
- /**
456
- * Optional inline styles for the container.
457
- * コンテナ用のオプションのインラインスタイル。
458
- */
459
- style?: CSSProperties
460
- /**
461
- * Accessible name for the tree as a whole (`aria-label` on the tree/treegrid element).
462
- * ツリー全体のアクセシブル名 (tree/treegrid 要素の `aria-label`)。
463
- *
464
- * 支援技術にとって、ページ内に複数のツリーがある場合これが唯一の識別手段になる。
465
- * 可視の見出しがある場合は `ariaLabelledBy` の方が望ましい。
466
- */
467
- ariaLabel?: string
468
- /**
469
- * `id` of a visible element naming the tree (`aria-labelledby`). Takes precedence over `ariaLabel`.
470
- * ツリーを説明する可視要素の `id` (`aria-labelledby`)。`ariaLabel` より優先。
471
- */
472
- ariaLabelledBy?: string
473
- /**
474
- * Line color for tree connections.
475
- * ツリーラインの色。
476
- */
477
- lineColor?: string
478
- /**
479
- * Flag indicating whether to render tree connector lines.
480
- * ツリーのコネクタラインをレンダリングするかどうかのフラグ。
481
- */
482
- showTreeLines?: boolean
483
- /**
484
- * Flag indicating whether to render directory expand icons.
485
- * ディレクトリの展開アイコンを描画するかどうかのフラグ。
486
- */
487
- showExpandIcons?: boolean
488
- /**
489
- * Flag indicating whether to render directory type icons.
490
- * ディレクトリアイコンを描画するかどうかのフラグ。
491
- */
492
- showDirectoryIcons?: boolean
493
- /**
494
- * Flag indicating whether to render file type icons.
495
- * ファイルアイコンを描画するかどうかのフラグ。
496
- */
497
- showFileIcons?: boolean
498
- /**
499
- * Icon overrides applied globally.
500
- * グローバルに適用するアイコン差し替え設定。
501
- */
502
- iconOverrides?: DirectoryTreeIconOverrides
503
- /**
504
- * Size of the expand icon in px.
505
- * 展開アイコンのサイズ (px)。
506
- */
507
- expandIconSize?: number
508
- /**
509
- * Size of the file/directory type icon in px.
510
- * ファイル/ディレクトリアイコンのサイズ (px)。
511
- */
512
- typeIconSize?: number
513
- /**
514
- * Font size of entry labels in px or CSS string (e.g. 12 or "0.75rem").
515
- * ラベル文字のフォントサイズ (px または CSS 文字列)。
516
- */
517
- fontSize?: number | string
518
- /**
519
- * Indentation width per depth level in px.
520
- * 1 階層あたりのインデント幅 (px)。
521
- */
522
- indentSize?: number
523
- /**
524
- * Row height in px, or a function computing the height per entry. Default 20 (or 18 in compact mode).
525
- * When a function is supplied, rows may have different heights and the tree
526
- * connector lines follow each row's cumulative offset.
527
- *
528
- * 各行の高さ (px)、またはエントリごとに高さを算出する関数。既定 20 (コンパクトモード時 18)。
529
- * 関数を渡すと行ごとに高さを変えられ、ツリー接続線は各行の累積オフセットに追従する。
530
- */
531
- itemHeight?: ItemHeight
532
- /**
533
- * If true, removes the indentation and connector lines for root-level items.
534
- * true の場合、ルートレベルのアイテムのインデントとコネクタラインを削除します。
535
- */
536
- removeRootIndent?: boolean
537
- /**
538
- * Highlight styles configuration for hover and selection states.
539
- * ホバー時および選択時のハイライトスタイルの設定。
540
- */
541
- highlightStyles?: HighlightStyles
542
- /** CSS class name for each entry. / 各エントリ(行)に適用する追加の CSS クラス名。 */
543
- entryClassName?: string
544
- /** Inline styles for each entry. / 各エントリ(行)に適用する追加のインラインスタイル。 */
545
- entryStyle?: CSSProperties
546
- /** CSS class name for the name (label) part. / 名前(ラベル)部分に適用する追加の CSS クラス名。 */
547
- nameClassName?: string
548
- /** Inline styles for the name (label) part. / 名前(ラベル)部分に適用する追加のインラインスタイル。 */
549
- nameStyle?: CSSProperties
550
- /** CSS class name specifically for directory names. / ディレクトリ名特有の追加の CSS クラス名。 */
551
- directoryNameClassName?: string
552
- /** Inline styles specifically for directory names. / ディレクトリ名特有の追加のインラインスタイル。 */
553
- directoryNameStyle?: CSSProperties
554
- /** CSS class name specifically for file names. / ファイル名特有の追加の CSS クラス名。 */
555
- fileNameClassName?: string
556
- /** Inline styles specifically for file names. / ファイル名特有の追加のインラインスタイル。 */
557
- fileNameStyle?: CSSProperties
558
- }
559
-
560
- /**
561
- * Additional options for VirtualScroll integration.
562
- * VirtualScroll の設定を上書きするオプション。
563
- */
564
- virtualScroll?: DirectoryTreeVirtualScrollOptions
565
-
566
- /**
567
- * TreeGrid (columns) mode. When provided, the name column is frozen on the left and the
568
- * remaining columns render as an aligned grid with header/footer and a horizontally
569
- * scrollable numeric region. When omitted, the classic label-based tree is rendered.
570
- *
571
- * TreeGrid(列)モード。指定時は名前列を凍結し数値列を整列グリッドで描画する。省略時は従来のツリー。
572
- *
573
- * `grid.columns` と各 `render` / `footer` は参照安定必須(`itemHeight` と同じ制約)。
574
- */
575
- grid?: DirectoryTreeGrid
576
-
577
- /**
578
- * Optional comparator applied to every sibling group before the tree is flattened
579
- * into rows. Only a shallow copy of each sibling array is sorted, so every
580
- * `DirectoryEntry` object and every `children` array keeps its identity and
581
- * consumer-side memoization (row memo, reference-preserving decorators, hydration
582
- * caches) continues to work. Omit it to render the entries in their given order.
583
- *
584
- * 各兄弟グループへフラット化前に適用する任意の比較関数。並べ替えは兄弟配列の浅いコピーに
585
- * 対してのみ行うため、`DirectoryEntry` と `children` 配列の identity は保持され、利用側の
586
- * メモ化 (行メモ・参照保持デコレータ・ハイドレーションキャッシュ) はそのまま機能する。
587
- * 省略時は与えられた順序のまま描画。
588
- *
589
- * @remarks 参照を安定させること (`useMemo` / `useCallback`)。identity が毎レンダー変わると
590
- * ツリー走査が都度再計算され、パフォーマンスが劣化する (`itemHeight` と同じ制約)。
591
- */
592
- sort?: DirectoryEntryComparator
593
- }
594
-
595
- /**
596
- * Props for the useDirectoryTreeState hook.
597
- * useDirectoryTreeState フックのプロパティ。
598
- */
599
- export type UseDirectoryTreeStateProps = {
600
- /**
601
- * An optional set of initially expanded directory paths.
602
- * 初期状態で展開されているディレクトリパスのオプションのセット。
603
- */
604
- initialExpanded?: Set<string>
605
- /**
606
- * An optional key to store the expanded state in localStorage.
607
- * 展開状態を localStorage に保存するためのオプションのキー。
608
- */
609
- storageKey?: string
610
- }
611
-
612
- /**
613
- * @type DirectoryEntryItemProps
614
- * @description Props for the DirectoryEntryItem component.
615
- * DirectoryEntryItem コンポーネントの Props。
616
- */
617
- export type DirectoryEntryItemProps = {
618
- entry: DirectoryEntry
619
- indentLevel: number
620
- /**
621
- * Logical depth from the roots, 0-based, independent of the visual indent.
622
- * ルートからの論理的な深さ (0 始まり)。視覚的インデントとは独立。
623
- *
624
- * `visual.removeRootIndent` は `indentLevel` を負方向へずらすため、`aria-level` の算出には
625
- * こちらを用いる (支援技術へ伝えるのは見た目のずれではなく実際の階層)。
626
- */
627
- depth: number
628
- /** True when this row is part of the item-selection set (`aria-selected`). / 選択集合に含まれるか。 */
629
- isSelectedForAria: boolean
630
- /** Index of this row in the flattened (visible) list. / フラット化後 (可視) リスト内の位置。 */
631
- flatIndex: number
632
- /** True when this row is the single tab stop of the tree (roving tabindex). / ツリー内で唯一のタブ停止点か。 */
633
- isActive: boolean
634
- /** Registers the row element so the tree can move focus to it. / フォーカス移動のために行要素を登録する。 */
635
- registerRowRef: (index: number, node: HTMLDivElement | null) => void
636
- /** Handles tree-level navigation keys. / ツリー全体のナビゲーションキーを処理する。 */
637
- onNavigationKeyDown: (event: import("react").KeyboardEvent<HTMLDivElement>, index: number) => void
638
- /** 1-based position among its siblings (`aria-posinset`). / 兄弟内の位置 (1 始まり)。 */
639
- positionInSet: number
640
- /** Number of siblings in the same group (`aria-setsize`). / 同一グループの兄弟数。 */
641
- setSize: number
642
- /** Resolved height of this row in px. / この行の解決済み高さ (px)。 */
643
- rowHeight: number
644
- isDirOpen: (path: string) => boolean
645
-
646
- expansion: {
647
- toggleDirectory: (path: string) => void
648
- onToggleDirectoryRecursive: (entry: DirectoryEntry) => void
649
- doubleClickAction?: "toggle" | "recursive"
650
- }
651
-
652
- selection: {
653
- selectedPath: string | null
654
- mode?: "none" | "single" | "multiple"
655
- selectedItems?: Set<string>
656
- onEntryClick: (event: DirectoryTreeClickEvent) => void
657
- onSelectionChange?: (entry: DirectoryEntry, isSelected: boolean) => void
658
- }
659
-
660
- visual: {
661
- showExpandIcons?: boolean
662
- showDirectoryIcons?: boolean
663
- showFileIcons?: boolean
664
- iconOverrides?: DirectoryTreeIconOverrides
665
- expandIconSize?: number
666
- typeIconSize?: number
667
- fontSize?: number | string
668
- indentSize?: number
669
- useCanvasExpandIcons?: boolean
670
- highlightStyles?: HighlightStyles
671
- entryClassName?: string
672
- entryStyle?: CSSProperties
673
- nameClassName?: string
674
- nameStyle?: CSSProperties
675
- directoryNameClassName?: string
676
- directoryNameStyle?: CSSProperties
677
- fileNameClassName?: string
678
- fileNameStyle?: CSSProperties
679
- }
680
-
681
- parentIsLast: boolean[]
682
- renderChildren?: boolean
683
- }
684
-
685
- /**
686
- * Information for a single item in the tree line.
687
- *
688
- * ツリーラインの単一アイテムの情報。
689
- */
690
- export type TreeLineItemInfo = {
691
- id: string // アイテムの一意な識別子
692
- absolutePath: string // アイテムの絶対パス
693
- name: string // アイテム名
694
- indentLevel: number // アイテムのインデントレベル
695
- isLastChild: boolean // アイテムが親の最後の子であるかどうか
696
- ancestorIsLast: boolean[] // 各祖先が最後の子であるかを示す配列
697
- isDirectory: boolean // アイテムがディレクトリであるかどうか
698
- isOpen?: boolean // ディレクトリが開いているかどうか (任意)
699
- isExpanded: boolean // ディレクトリが展開されているかどうか
700
- hideLines?: boolean // ツリーラインを隠すかどうか
701
- }
702
-
703
- /**
704
- * Segment data for TreeLine rendering.
705
- *
706
- * TreeLine 描画用のセグメントデータ。
707
- */
708
- export type TreeLineSegment = {
709
- key: string // セグメントの一意なキー
710
- x1: number // 線分の始点X座標
711
- y1: number // 線分の始点Y座標
712
- x2: number // 線分の終点X座標
713
- y2: number // 線分の終点Y座標
714
- itemIndex: number // セグメントが属するアイテムのインデックス
715
- }
716
-
717
- /**
718
- * Glyph data for expand icons rendered on the tree line canvas.
719
- *
720
- * ツリーラインキャンバスに描画する展開アイコンのグリフ情報。
721
- */
722
- export type TreeLineGlyph = {
723
- key: string // グリフの一意なキー
724
- itemIndex: number // グリフが属するアイテムのインデックス
725
- centerX: number // グリフの中心X座標
726
- centerY: number // グリフの中心Y座標
727
- size: number // グリフのサイズ
728
- isExpanded: boolean // 展開状態かどうか
729
- }
730
-
731
- /**
732
- * Geometric data for tree line rendering.
733
- *
734
- * ツリーライン描画用のジオメトリデータ。
735
- */
736
- export type TreeLineGeometry = {
737
- segmentsByItem: TreeLineSegment[][] // アイテムごとの線分配列
738
- glyphsByItem: TreeLineGlyph[][] // アイテムごとのグリフ配列
739
- }
740
-
741
- /**
742
- * Props for the TreeLine component.
743
- *
744
- * TreeLine コンポーネントの Props。
745
- */
746
- export type TreeLineProps = {
747
- segmentsByItem: TreeLineSegment[][] // アイテムごとのセグメント配列
748
- glyphsByItem: TreeLineGlyph[][] // アイテムごとのグリフ配列
749
- itemHeight: number // 各アイテムの高さ
750
- width: number // SVG 領域の全体の幅
751
- viewportHeight: number // ビューポートの高さ
752
- scrollPosition: number // 現在のスクロール位置
753
- color?: string // ツリーラインの色 (任意)
754
- strokeWidth?: number // ツリーラインの線の太さ (任意)
755
- renderStartIndex?: number // レンダリングを開始するインデックス (任意)
756
- renderEndIndex?: number // レンダリングを終了するインデックス (任意)
757
- lookaheadEndIndex?: number // 表示範囲外も考慮したインデックス上限 (任意)
758
- devicePixelRatio?: number // デバイスピクセル比 (任意)
759
- expandGlyphColor?: string // 展開アイコンの色 (任意)
760
- expandGlyphSize?: number // 展開アイコンのサイズ (任意)
761
- }