@nice2dev/ui 1.3.8 → 1.3.9

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/dist/index.d.ts CHANGED
@@ -23307,6 +23307,33 @@ export { NiceTransitionState }
23307
23307
 
23308
23308
  export { NiceTranslateFn }
23309
23309
 
23310
+ /**
23311
+ * treeCheck — the check state of a tree with cascading checkboxes, shared by NiceTreeGrid,
23312
+ * NiceTreeList and NiceTreeView.
23313
+ *
23314
+ * - A **check node** is a node that can carry a checkbox (`isCheckable`, default true).
23315
+ * - A **check leaf** is a check node without check nodes below it — a module whose children are
23316
+ * only informational rows is a leaf. The check state lives on the leaves; every other node's
23317
+ * state is derived from the leaves below it: checked when all are, indeterminate when some are.
23318
+ * - A node that is **not checkable** never has a checkbox and is never emitted. Above check
23319
+ * nodes (a group header) it is transparent: its ancestors count the leaves below it.
23320
+ * - A **locked** leaf (disabled, or below a disabled node with `inheritDisabled`) keeps its
23321
+ * state when an ancestor is toggled. A parent still shows checked only when all its leaves are,
23322
+ * locked ones included.
23323
+ *
23324
+ * The leaves of every node form one contiguous slice of `index.leaves` (pre-order), so states
23325
+ * and counts are O(1) from a prefix sum; building the index and emitting keys are O(n).
23326
+ */
23327
+ export declare type NiceTreeCheckState = 'checked' | 'unchecked' | 'indeterminate';
23328
+
23329
+ /**
23330
+ * Which keys a checked tree reports:
23331
+ * - `'all'` — every check node whose leaves are all checked (parents and leaves);
23332
+ * - `'leaves'` — only the checked leaves;
23333
+ * - `'parents'` — the topmost fully checked nodes (a fully checked parent stands for its subtree).
23334
+ */
23335
+ export declare type NiceTreeCheckStrategy = 'all' | 'leaves' | 'parents';
23336
+
23310
23337
  /** A context-menu action for {@link NiceTreeView} nodes. */
23311
23338
  export declare interface NiceTreeContextMenuItem {
23312
23339
  /** Unique key. */
@@ -23319,16 +23346,31 @@ export declare interface NiceTreeContextMenuItem {
23319
23346
  disabled?: boolean;
23320
23347
  }
23321
23348
 
23322
- export declare function NiceTreeGrid<T extends NiceTreeGridNode>({ columns, data, keyField, parentKeyField, nested, childrenField, expandedKeys: controlledExpanded, onExpandedChange, defaultExpandAll, sortable, sortField: controlledSortField, sortDirection: controlledSortDir, onSort, selectable, selectedKeys: controlledSelected, onSelectionChange, searchable, searchPlaceholder, striped, compact, size, loading, disabled, readOnly, error, emptyText, toolbar, onRowClick, className, style, }: NiceTreeGridProps<T>): default_2.JSX.Element;
23349
+ export declare function NiceTreeGrid<T extends NiceTreeGridNode>({ columns, data, keyField, parentKeyField, nested, childrenField, expandedKeys: controlledExpanded, defaultExpandedKeys, onExpandedChange, defaultExpandAll, sortable, sortField: controlledSortField, sortDirection: controlledSortDir, onSort, selectable, selectedKeys: controlledSelected, onSelectionChange, checkable, checkedKeys, defaultCheckedKeys, onCheckedChange, checkStrategy, isRowCheckable, isRowDisabled, checkboxPlacement, checkOnRowClick, showCheckedCount, showSelectAll, showOnlyChecked: controlledOnlyChecked, defaultShowOnlyChecked, onShowOnlyCheckedChange, toolbarActions, searchable, searchPlaceholder, searchText, defaultSearchText, onSearchChange, searchFields, searchFilter, searchKeepDescendants, searchAutoExpand, highlightMatches, rowClassName, getRowLabel, virtualScroll, rowHeight, height, striped, compact, size, loading, disabled, readOnly, error, emptyText, toolbar, onRowClick, className, style, id, testId, 'data-testid': dataTestId, accessMode, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, }: NiceTreeGridProps<T>): default_2.JSX.Element | null;
23350
+
23351
+ /** What changed in a {@link NiceTreeGrid} check — the second argument of `onCheckedChange`. */
23352
+ export declare interface NiceTreeGridCheckInfo<T = NiceTreeGridNode> {
23353
+ /** A row's checkbox (or Space / a row click), the header's "select all", or "clear selection". */
23354
+ source: 'row' | 'selectAll' | 'clear';
23355
+ /** Whether rows went on. */
23356
+ checked: boolean;
23357
+ /** The toggled row (source `'row'`). */
23358
+ key?: string;
23359
+ row?: T;
23360
+ /** The checked leaves, whatever `checkStrategy` reports. */
23361
+ leafKeys: string[];
23362
+ /** Rows with checkboxes that are partly checked. */
23363
+ halfCheckedKeys: string[];
23364
+ }
23323
23365
 
23324
23366
  /** A row node in the {@link NiceTreeGrid} (supports index-signature for dynamic fields). */
23325
23367
  export declare interface NiceTreeGridNode {
23326
23368
  [field: string]: unknown;
23327
23369
  }
23328
23370
 
23329
- /** Props for the {@link NiceTreeGrid} component — a hierarchical data grid with sorting, selection, search, and NiceDataGrid column features. */
23330
- export declare interface NiceTreeGridProps<T extends NiceTreeGridNode = NiceTreeGridNode> extends NiceBaseProps {
23331
- /** Column definitions (reuses NiceDataGridColumn). */
23371
+ /** Props for the {@link NiceTreeGrid} component — a hierarchical data grid with sorting, selection, cascading checkboxes, search, and NiceDataGrid column features. */
23372
+ export declare interface NiceTreeGridProps<T extends NiceTreeGridNode = NiceTreeGridNode> extends NiceStandardProps {
23373
+ /** Column definitions (reuses NiceDataGridColumn). The tree (indent, expander, checkbox) sits in the first one. */
23332
23374
  columns?: NiceDataGridColumn<T>[];
23333
23375
  /** Row data. */
23334
23376
  data?: T[];
@@ -23342,9 +23384,11 @@ export declare interface NiceTreeGridProps<T extends NiceTreeGridNode = NiceTree
23342
23384
  childrenField?: string;
23343
23385
  /** Currently expanded keys. */
23344
23386
  expandedKeys?: string[];
23345
- /** Called when expanded keys change. */
23387
+ /** Rows expanded until the user expands or collapses one (uncontrolled). */
23388
+ defaultExpandedKeys?: string[];
23389
+ /** Called when expanded keys change. Not called for the rows a search opens. */
23346
23390
  onExpandedChange?: (keys: string[]) => void;
23347
- /** Expand all nodes by default. */
23391
+ /** Expand all nodes by default — also rows that arrive later, until the user toggles one. */
23348
23392
  defaultExpandAll?: boolean;
23349
23393
  /** Enable sorting. */
23350
23394
  sortable?: boolean;
@@ -23354,16 +23398,92 @@ export declare interface NiceTreeGridProps<T extends NiceTreeGridNode = NiceTree
23354
23398
  sortDirection?: SortDirection;
23355
23399
  /** Called when sort changes. */
23356
23400
  onSort?: (field: string, direction: SortDirection) => void;
23357
- /** Enable row selection. */
23401
+ /**
23402
+ * Enable flat row selection: a checkbox per row, no cascade. With `checkable` the checkbox
23403
+ * belongs to the check and a row click toggles this selection (row highlight).
23404
+ */
23358
23405
  selectable?: boolean;
23359
23406
  /** Currently selected keys. */
23360
23407
  selectedKeys?: Set<string>;
23361
23408
  /** Called when selection changes. */
23362
23409
  onSelectionChange?: (keys: Set<string>) => void;
23410
+ /**
23411
+ * Cascading checkboxes: checking a parent checks every row below it, a parent shows checked
23412
+ * when all rows below it are and indeterminate when some are.
23413
+ */
23414
+ checkable?: boolean;
23415
+ /** Checked keys (controlled). A parent key checks its whole subtree. */
23416
+ checkedKeys?: string[];
23417
+ /** Checked keys at mount (uncontrolled). */
23418
+ defaultCheckedKeys?: string[];
23419
+ /** Called with the checked keys (see `checkStrategy`) and what changed. */
23420
+ onCheckedChange?: (keys: string[], info: NiceTreeGridCheckInfo<T>) => void;
23421
+ /**
23422
+ * Which keys `onCheckedChange` reports: `'all'` (default) every fully checked row, parents
23423
+ * included; `'leaves'` only the checked rows with no checkboxes below them; `'parents'` the
23424
+ * topmost fully checked rows. Keys of rows not in `data` are kept.
23425
+ */
23426
+ checkStrategy?: NiceTreeCheckStrategy;
23427
+ /**
23428
+ * `false` makes a row informational: no checkbox, never reported. Above checkable rows it is a
23429
+ * group header its ancestors count through; below a checkable row (a module's categories) the
23430
+ * checkable row counts as a leaf.
23431
+ */
23432
+ isRowCheckable?: (row: T) => boolean;
23433
+ /** `true` locks a row and every row below it: their checks keep their state. */
23434
+ isRowDisabled?: (row: T) => boolean;
23435
+ /** Where the checkboxes go: after the expander in the tree column (default) or a column of their own. */
23436
+ checkboxPlacement?: 'tree' | 'column';
23437
+ /** A row click toggles the row's checkbox. */
23438
+ checkOnRowClick?: boolean;
23439
+ /** Show a "checked / total" badge on rows with checkboxes below them. */
23440
+ showCheckedCount?: boolean;
23441
+ /** A "select all" checkbox in the header — while searching, it acts on the results. Default true. */
23442
+ showSelectAll?: boolean;
23443
+ /** Show only the checked rows (controlled). */
23444
+ showOnlyChecked?: boolean;
23445
+ /** Show only the checked rows at mount (uncontrolled). */
23446
+ defaultShowOnlyChecked?: boolean;
23447
+ /** Called when "show selected only" is switched. */
23448
+ onShowOnlyCheckedChange?: (value: boolean) => void;
23449
+ /**
23450
+ * Built-in toolbar buttons: `true` for all that apply (expand all, collapse all and — when
23451
+ * `checkable` — show selected only, clear selection), or a list of them.
23452
+ */
23453
+ toolbarActions?: boolean | NiceTreeGridToolbarAction[];
23363
23454
  /** Show a search box. */
23364
23455
  searchable?: boolean;
23365
23456
  /** Search input placeholder. */
23366
23457
  searchPlaceholder?: string;
23458
+ /** Search text (controlled). */
23459
+ searchText?: string;
23460
+ /** Search text at mount (uncontrolled). */
23461
+ defaultSearchText?: string;
23462
+ /** Called when the search text changes. */
23463
+ onSearchChange?: (text: string) => void;
23464
+ /** Fields the search looks in (default: the visible columns). */
23465
+ searchFields?: string[];
23466
+ /** Own match test, instead of a substring of `searchFields`. */
23467
+ searchFilter?: (row: T, query: string) => boolean;
23468
+ /** A matching row keeps all rows below it, not only the matching ones. */
23469
+ searchKeepDescendants?: boolean;
23470
+ /** Open the rows above every match while searching (default true); the user's own expansion comes back when the search is cleared. */
23471
+ searchAutoExpand?: boolean;
23472
+ /** Mark the matches in columns without a `render` (default true). */
23473
+ highlightMatches?: boolean;
23474
+ /** Extra class name of a row. */
23475
+ rowClassName?: string | ((row: T, index: number) => string | undefined);
23476
+ /** A row's name for its checkbox label (default: its first column's value). */
23477
+ getRowLabel?: (row: T) => string;
23478
+ /**
23479
+ * Render only the rows in view, for thousands of rows. Rows get a fixed height (`rowHeight`)
23480
+ * and long cells are cut with an ellipsis.
23481
+ */
23482
+ virtualScroll?: boolean;
23483
+ /** Row height in px with `virtualScroll` (default 36). */
23484
+ rowHeight?: number;
23485
+ /** Height of the scrolling body with `virtualScroll` (default 480). */
23486
+ height?: number | string;
23367
23487
  /** Alternate row coloring. */
23368
23488
  striped?: boolean;
23369
23489
  /** Reduced padding. */
@@ -23386,6 +23506,9 @@ export declare interface NiceTreeGridProps<T extends NiceTreeGridNode = NiceTree
23386
23506
  onRowClick?: (row: T) => void;
23387
23507
  }
23388
23508
 
23509
+ /** A built-in toolbar button of {@link NiceTreeGrid}. */
23510
+ export declare type NiceTreeGridToolbarAction = 'expandAll' | 'collapseAll' | 'onlyChecked' | 'clearChecked';
23511
+
23389
23512
  export declare function NiceTreeList<T extends NiceTreeListNode>({ columns, data, keyField, parentKeyField, expandedKeys: controlledExpanded, onExpandedChange, selectedKeys, onSelectionChange, selectable, sortable, loading, emptyText, className, style, accessMode, id, }: NiceTreeListProps<T>): default_2.JSX.Element | null;
23390
23513
 
23391
23514
  /** A tree-list node for the {@link NiceTreeList} component. */
@@ -23414,11 +23537,17 @@ export declare interface NiceTreeListProps<T extends NiceTreeListNode = NiceTree
23414
23537
  expandedKeys?: string[];
23415
23538
  /** Called when expanded keys change. */
23416
23539
  onExpandedChange?: (keys: string[]) => void;
23417
- /** Currently selected keys. */
23540
+ /**
23541
+ * Currently selected keys. A parent key selects its whole subtree. The keys handed back are every
23542
+ * fully selected row, parents included, in document order; keys of rows not in `data` are kept.
23543
+ */
23418
23544
  selectedKeys?: string[];
23419
23545
  /** Called when selection changes. */
23420
23546
  onSelectionChange?: (keys: string[]) => void;
23421
- /** Enable row selection. Checking a parent row cascades to all its descendants. */
23547
+ /**
23548
+ * Enable row selection. Checking a parent row cascades to all its descendants; a parent shows
23549
+ * checked when all its descendants are, indeterminate when some are.
23550
+ */
23422
23551
  selectable?: boolean;
23423
23552
  /** Enable column sorting (opt-in per column via `NiceDataGridColumn.sortable`). */
23424
23553
  sortable?: boolean;
@@ -23498,9 +23627,9 @@ export declare interface NiceTreeNode {
23498
23627
  icon?: default_2.ReactNode;
23499
23628
  /** Child nodes. */
23500
23629
  children?: NiceTreeNode[];
23501
- /** Disable the node. */
23630
+ /** Disable the node. With cascading checkboxes, its own checkbox keeps its state. */
23502
23631
  disabled?: boolean;
23503
- /** Default expanded state. */
23632
+ /** Expanded when the tree mounts (uncontrolled `expandedKeys` only). */
23504
23633
  expanded?: boolean;
23505
23634
  /** If true, children are loaded lazily via onLoadChildren. */
23506
23635
  leaf?: boolean;
@@ -23554,7 +23683,11 @@ export declare interface NiceTreeViewProps extends NiceBaseProps {
23554
23683
  * a title bar, toolbar or count. Pass any node; omit for no header.
23555
23684
  */
23556
23685
  header?: default_2.ReactNode;
23557
- /** Currently selected node keys. */
23686
+ /**
23687
+ * Currently selected node keys. With `showCheckboxes` and `selectionMode="multiple"` the
23688
+ * checkboxes cascade: a parent key checks its subtree, and the keys handed back are every fully
23689
+ * checked node, parents included, in document order.
23690
+ */
23558
23691
  selectedKeys?: string[];
23559
23692
  /** Currently expanded node keys. */
23560
23693
  expandedKeys?: string[];