@aiquants/directory-tree 3.3.0 → 3.5.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/src/types.ts CHANGED
@@ -37,8 +37,34 @@ export type DirectoryEntry = {
37
37
  * エントリ用のオプションのインラインスタイル。
38
38
  */
39
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>
40
56
  }
41
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
+
42
68
  /**
43
69
  * Row height for directory tree entries.
44
70
  * Either a fixed pixel value applied to every row, or a function computing the
@@ -499,6 +525,23 @@ export type DirectoryTreeProps = {
499
525
  * `grid.columns` と各 `render` / `footer` は参照安定必須(`itemHeight` と同じ制約)。
500
526
  */
501
527
  grid?: DirectoryTreeGrid
528
+
529
+ /**
530
+ * Optional comparator applied to every sibling group before the tree is flattened
531
+ * into rows. Only a shallow copy of each sibling array is sorted, so every
532
+ * `DirectoryEntry` object and every `children` array keeps its identity and
533
+ * consumer-side memoization (row memo, reference-preserving decorators, hydration
534
+ * caches) continues to work. Omit it to render the entries in their given order.
535
+ *
536
+ * 各兄弟グループへフラット化前に適用する任意の比較関数。並べ替えは兄弟配列の浅いコピーに
537
+ * 対してのみ行うため、`DirectoryEntry` と `children` 配列の identity は保持され、利用側の
538
+ * メモ化 (行メモ・参照保持デコレータ・ハイドレーションキャッシュ) はそのまま機能する。
539
+ * 省略時は与えられた順序のまま描画。
540
+ *
541
+ * @remarks 参照を安定させること (`useMemo` / `useCallback`)。identity が毎レンダー変わると
542
+ * ツリー走査が都度再計算され、パフォーマンスが劣化する (`itemHeight` と同じ制約)。
543
+ */
544
+ sort?: DirectoryEntryComparator
502
545
  }
503
546
 
504
547
  /**
@@ -526,6 +569,18 @@ export type UseDirectoryTreeStateProps = {
526
569
  export type DirectoryEntryItemProps = {
527
570
  entry: DirectoryEntry
528
571
  indentLevel: number
572
+ /**
573
+ * Logical depth from the roots, 0-based, independent of the visual indent.
574
+ * ルートからの論理的な深さ (0 始まり)。視覚的インデントとは独立。
575
+ *
576
+ * `visual.removeRootIndent` は `indentLevel` を負方向へずらすため、`aria-level` の算出には
577
+ * こちらを用いる (支援技術へ伝えるのは見た目のずれではなく実際の階層)。
578
+ */
579
+ depth: number
580
+ /** 1-based position among its siblings (`aria-posinset`). / 兄弟内の位置 (1 始まり)。 */
581
+ positionInSet: number
582
+ /** Number of siblings in the same group (`aria-setsize`). / 同一グループの兄弟数。 */
583
+ setSize: number
529
584
  /** Resolved height of this row in px. / この行の解決済み高さ (px)。 */
530
585
  rowHeight: number
531
586
  isDirOpen: (path: string) => boolean