@cube-dev/ui-kit 0.127.3 → 0.129.0

package/docs/components/content/Tree.md

@@ -0,0 +1,299 @@
+# Tree
+
+Tree displays hierarchical data as a list of nodes you can expand, collapse,
+select, and (optionally) check. Built on `useTree` and `useTreeState`
+(React Aria + React Stately) and styled with Tasty.
+
+The component's data shape (`treeData`) and the public callback shape are
+designed to be a near drop-in for AntD's `Tree` (modulo the `is*` boolean
+prop convention used across `@cube-dev/ui-kit`), so existing AntD `Tree`
+consumers can be migrated with minimal churn.
+
+## When to Use
+
+- Rendering hierarchical structures such as file systems, organizational
+  charts, navigation, or schema browsers.
+- Letting users select one or many nodes from a tree, with cascading
+  parent/child checkbox semantics.
+- Lazily loading children when a node is expanded the first time
+  (`loadData`).
+- Filtering with auto-expanded ancestors (`autoExpandParent`).
+
+## Component
+
+---
+
+### Properties
+
+- **`treeData`** `CubeTreeNodeData[]` — Hierarchical data describing the
+  tree.
+- **`isCheckable`** `boolean` (default: `false`) — Render a checkbox in
+  front of every eligible row.
+- **`isSelectable`** `boolean` — Sugar for `selectionMode="none"` when
+  `false`. `selectionMode` wins when both are passed.
+- **`selectionMode`** `'none' | 'single' | 'multiple'` (default: `'single'`)
+  — Selection cardinality.
+- **`isDisabled`** `boolean` (default: `false`) — Disable the entire tree.
+- **`defaultExpandedKeys`** `string[]` — Default expanded keys
+  (uncontrolled).
+- **`expandedKeys`** `string[]` — Controlled expanded keys.
+- **`autoExpandParent`** `boolean` (default: `false`) — Auto-expand parents
+  of currently expanded keys. Useful for filtering.
+- **`defaultCheckedKeys`** `string[]` — Default checked keys (uncontrolled).
+- **`checkedKeys`** `string[] | { checked: string[]; halfChecked?: string[] }`
+  — Controlled checked keys. Pass the object form to receive the same
+  shape back from `onCheck`.
+- **`defaultSelectedKeys`** `string[]` — Default selected keys
+  (uncontrolled).
+- **`selectedKeys`** `string[]` — Controlled selected keys.
+- **`height`** `number` — Fixed height in pixels. When omitted, the tree
+  fills the available vertical space and scrolls internally.
+- **`loadData`** `(node: TreeLoadDataNode) => Promise<void>` — Async
+  loader called the first time a non-leaf node with no `children` is
+  expanded. The consumer is expected to merge new children into
+  `treeData` (typical AntD pattern).
+- **`onExpand`** `(expandedKeys: Key[], info: TreeOnExpandInfo) => void` —
+  Called when a node is expanded or collapsed.
+- **`onCheck`** `(checked: Key[] | { checked, halfChecked }, info: TreeOnCheckInfo) => void`
+  — Called when a node is checked or unchecked.
+- **`onSelect`** `(selectedKeys: Key[], info: TreeOnSelectInfo) => void` —
+  Called when row selection changes.
+- **`rowStyles`** `Styles` — Override styles for `[data-element="Row"]`.
+
+#### `CubeTreeNodeData`
+
+- **`key`** `string` — Unique identifier of the node.
+- **`title`** `ReactNode` — Visible label.
+- **`children`** `CubeTreeNodeData[]` — Children. Pass `undefined`
+  together with `isLeaf={false}` for lazy nodes.
+- **`isLeaf`** `boolean` — Force leaf rendering (no expand toggle, no
+  `loadData` call).
+- **`isDisabled`** `boolean` — Disable interactions on this row (focus /
+  select / expand / check).
+- **`isCheckboxDisabled`** `boolean` — Disable only the checkbox of this
+  row.
+- **`isCheckable`** `boolean` — Per-node override; `false` hides the
+  checkbox for this row even when the tree is `isCheckable`.
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md)
+
+### Styling Properties
+
+#### styles
+
+Customizes the root `treegrid` element of the Tree.
+
+**Sub-elements:**
+
+- `Row` — A single tree row (also targetable via the dedicated
+  `rowStyles` prop).
+
+#### rowStyles
+
+Customizes `[data-element="Row"]`. Useful when you need to override row
+spacing, hover/selected colors, or cell layout without re-targeting via
+`styles`.
+
+**Sub-elements:**
+
+- `Toggle` — The expand/collapse button.
+- `Checkbox` — The checkbox slot (visible only when `isCheckable`).
+- `Title` — The title label.
+
+### Modifiers
+
+The following row-level modifiers are emitted automatically. They are
+useful when overriding `rowStyles`:
+
+| Modifier        | Type      | Description                                            |
+| --------------- | --------- | ------------------------------------------------------ |
+| `selected`      | `boolean` | Row is selected.                                       |
+| `checked`       | `boolean` | Row is fully checked.                                  |
+| `indeterminate` | `boolean` | Row is in the half-checked state.                      |
+| `expanded`      | `boolean` | Row is expanded.                                       |
+| `disabled`      | `boolean` | Row is disabled.                                       |
+| `loading`       | `boolean` | The row's children are being fetched via `loadData`.   |
+| `leaf`          | `boolean` | Row has no children.                                   |
+| `has-checkbox`  | `boolean` | Row renders a checkbox.                                |
+
+## Variants
+
+### Selection Modes
+
+- `none` — Row click does not select. Useful in pure-display or pure-
+  checkable trees.
+- `single` (default) — One row selected at a time.
+- `multiple` — Multi-select with keyboard modifiers and shift-range.
+
+## Examples
+
+### Basic Usage
+
+```jsx
+const data = [
+  { key: 'fruits', title: 'Fruits', children: [
+    { key: 'apple', title: 'Apple' },
+    { key: 'banana', title: 'Banana' },
+  ]},
+  { key: 'vegetables', title: 'Vegetables', children: [
+    { key: 'carrot', title: 'Carrot' },
+  ]},
+];
+
+<Tree treeData={data} defaultExpandedKeys={['fruits']} />;
+```
+
+### Checkable
+
+`isCheckable` enables AntD-style cascading parent ↔ child checkbox
+behavior: checking a parent checks all eligible descendants, and a
+parent flips into the indeterminate (half-checked) state when only some
+of its descendants are checked.
+
+```jsx
+<Tree
+  treeData={data}
+  isCheckable
+  selectionMode="none"
+  defaultCheckedKeys={['apple']}
+  onCheck={(keys, info) => {
+    console.log('checked', keys);
+    console.log('half-checked', info.halfCheckedKeys);
+  }}
+/>
+```
+
+### Controlled Checked
+
+To match AntD's object-shape API, pass `checkedKeys` as
+`{ checked, halfChecked }`. `onCheck` returns the same shape.
+
+```jsx
+const [checkedKeys, setCheckedKeys] = useState({ checked: [], halfChecked: [] });
+
+<Tree
+  treeData={data}
+  isCheckable
+  checkedKeys={checkedKeys}
+  onCheck={(next) => setCheckedKeys(next)}
+/>
+```
+
+### Lazy Loading
+
+Set `isLeaf: false` and omit `children` on a node, then provide a
+`loadData` callback. The callback should merge new children into
+`treeData`. The row shows a spinner while in flight; subsequent expands
+of the same key won't refire `loadData`.
+
+```jsx
+const handleLoadData = (node) =>
+  fetch(`/api/children?key=${node.key}`)
+    .then((r) => r.json())
+    .then((children) => mergeIntoTreeData(node.key, children));
+
+<Tree treeData={data} loadData={handleLoadData} />
+```
+
+### Auto-expand Parent (Filtering)
+
+Pass the matching keys via `expandedKeys` and set `autoExpandParent` to
+keep their ancestors expanded.
+
+```jsx
+<Tree
+  treeData={data}
+  expandedKeys={matchedKeys}
+  autoExpandParent
+/>
+```
+
+### Per-node Disabling
+
+Disable the entire row, just the checkbox, or hide the checkbox via
+node-level flags.
+
+```jsx
+const data = [
+  { key: 'a', title: 'A', children: [
+    { key: 'a-1', title: 'A-1', isDisabled: true },
+    { key: 'a-2', title: 'A-2', isCheckboxDisabled: true },
+    { key: 'a-3', title: 'A-3', isCheckable: false },
+  ]},
+];
+
+<Tree treeData={data} isCheckable defaultExpandedKeys={['a']} />
+```
+
+### Fixed Height
+
+```jsx
+<Tree treeData={data} height={300} />
+```
+
+## Accessibility
+
+Tree implements the
+[`treegrid` ARIA pattern](https://www.w3.org/WAI/ARIA/apg/patterns/treegrid/)
+via `useTree` from React Aria.
+
+### Keyboard Navigation
+
+- `Tab` — Moves focus into / out of the tree (focus stays on the
+  currently active row inside).
+- `ArrowUp` / `ArrowDown` — Move focus to the previous / next visible row.
+- `ArrowRight` — Expand the focused row (or move to its first child if
+  already expanded).
+- `ArrowLeft` — Collapse the focused row (or move to its parent if
+  already collapsed).
+- `Home` / `End` — Move focus to the first / last visible row.
+- `Space` / `Enter` — Toggle selection on the focused row (in `single`
+  or `multiple` mode).
+
+### Screen Reader Support
+
+- Each row reports `aria-level`, `aria-posinset`, `aria-setsize`, and
+  `aria-expanded` so screen readers can announce the position and
+  expansion state.
+- When `isCheckable` is enabled, the row carries `aria-checked` (`true`,
+  `false`, or `mixed` for the indeterminate state).
+- Disabled rows expose `aria-disabled="true"`.
+
+### ARIA Properties
+
+- `aria-label` — Provide a label that describes the tree's contents
+  (defaults to `"Tree"`).
+
+## Best Practices
+
+1. **Do**: Provide stable, unique `key`s — they are used for selection,
+   expansion, checking, and lazy-load tracking.
+   ```jsx
+   <Tree treeData={data.map((node) => ({ ...node, key: node.id }))} />
+   ```
+2. **Don't**: Mutate `treeData` in place. Always return a new array
+   from `loadData`'s commit step so React Stately can rebuild the
+   collection.
+3. **Accessibility**: When using checkboxes for selection, set
+   `selectionMode="none"` so the row click doesn't compete with the
+   checkbox.
+4. **Performance**: For very large trees, prefer virtualization (planned;
+   see Suggested Improvements) or use `loadData` to defer subtree
+   construction.
+
+## Suggested Improvements
+
+- Built-in virtualization for very large trees (10k+ rows).
+- Drag-and-drop reordering, mirroring AntD's `draggable` API.
+- An `onRightClick`/context menu hook.
+- Reveal-on-mount: scroll the focused row into view when expanded
+  programmatically.
+- Optional inline title editing.
+
+## Related Components
+
+- [ListBox](/components/ListBox) — Flat list with single/multi selection.
+- [Menu](/components/Menu) — Hierarchical action lists in popovers.
+- [Tabs](/components/Tabs) — Switch between sibling content panels.

package/docs/components/fields/FilterListBox.md

@@ -28,7 +28,7 @@ A searchable list selection component that combines a ListBox with an integrated
 - **`size`** `'small' | 'medium' | 'large'` (default: `medium`) — FilterListBox size
 - **`searchPlaceholder`** `string` (default: `Search...`) — Placeholder text in the search input
 - **`filter`** `((textValue: string, inputValue: string) => boolean) | false` — Custom filter function or `false` to disable filtering
-- **`emptyLabel`** `ReactNode` (default: `No items` / `No results found`) — Label displayed when no items match
+- **`emptyLabel`** `ReactNode` (default: context-aware: `No items` or `No results found`) — Label shown when the list is empty. When provided, overrides both defaults for any empty state
 - **`allowsCustomValue`** `boolean` (default: `false`) — Whether to allow custom values not in the options list
 - **`isCheckable`** `boolean` (default: `false`) — Whether to show checkboxes for multiple selection
 - **`shouldFocusWrap`** `boolean` (default: `false`) — Whether keyboard navigation should wrap around
@@ -44,6 +44,7 @@ A searchable list selection component that combines a ListBox with an integrated
 - **`onOptionClick`** `(key: Key) => void` — Callback when an option is clicked
 - **`items`** `Iterable<T>` — Array of items for dynamic content with render function pattern
 - **`isLoading`** `boolean` (default: `false`) — Whether the FilterListBox is in a loading state (shows loading icon in search input)
+- **`isLoadingItems`** `boolean` (default: `false`) — Whether items are currently loading. Shows a loading icon in the search input suffix
 - **`autoFocus`** `boolean` — Whether the search input should have autofocus
 - **`customValueProps`** `Partial<CubeItemProps>` — Props to apply to existing custom values (already selected but not in predefined options)
 - **`newCustomValueProps`** `Partial<CubeItemProps>` — Props to apply to new custom values appearing in search results (merged with `customValueProps`)
@@ -142,6 +143,7 @@ The `mods` property accepts the following modifiers you can override:
 - `disabled` `boolean` — Applied when `isDisabled={true}`
 - `focused` `boolean` — Applied when the FilterListBox has focus
 - `loading` `boolean` — Applied when `isLoading={true}`
+- `loading-items` `boolean` — Applied when `isLoadingItems={true}`
 - `searchable` `boolean` — Always true for FilterListBox
 - `prefix` `boolean` — Applied when loading icon is shown
 
@@ -622,36 +624,44 @@ Use `customValueProps` to style existing custom values and `newCustomValueProps`
 - `customValueProps` - Applied to custom values that are already selected
 - `newCustomValueProps` - Applied to new custom values appearing when typing in search (merged with `customValueProps`)
 
-### External Filtering
+### Server-Side / Dynamic Search
 
-For server-side filtering or complex custom logic, use `filter={false}` with controlled search:
+For server-side filtering, use `filter={false}` with controlled search and dynamic `items`. Items are replaced when the server responds, and `isLoadingItems` shows a subtle spinner in the search input while the fetch is in flight.
 
 ```jsx
+const [items, setItems] = useState(initialItems);
 const [searchValue, setSearchValue] = useState('');
-const [filteredItems, setFilteredItems] = useState(allItems);
+const [isLoadingItems, setIsLoadingItems] = useState(false);
 
-useEffect(() => {
-  // Your custom filtering logic (e.g., API call, complex algorithm)
-  const filtered = customFilterLogic(allItems, searchValue);
-  setFilteredItems(filtered);
-}, [searchValue, allItems]);
+const handleSearchChange = useCallback((value) => {
+  setSearchValue(value);
+  setIsLoadingItems(true);
+  debouncedFetch(value)
+    .then(setItems)
+    .finally(() => setIsLoadingItems(false));
+}, []);
 
 <FilterListBox
+  items={items}
   searchValue={searchValue}
-  onSearchChange={setSearchValue}
+  onSearchChange={handleSearchChange}
   filter={false}
+  isLoadingItems={isLoadingItems}
 >
-  {filteredItems.map(item => (
+  {(item) => (
     <FilterListBox.Item key={item.id}>{item.name}</FilterListBox.Item>
-  ))}
+  )}
 </FilterListBox>
 ```
 
-**When to use:**
-- Server-side filtering for large datasets
-- Complex custom search algorithms
-- Debounced API calls
-- Multi-field search logic
+**How it works:**
+- **`filter={false}`** disables client-side filtering so items appear exactly as the server returns them
+- **`searchValue` + `onSearchChange`** give you control over the search input; debounce and fetch on your side
+- **`items`** is reactive — replace it with server results and the list updates automatically
+- **`isLoadingItems`** shows a loading spinner in the search input suffix while fetching. While loading, stale items that do not text-match the current search are hidden client-side so the user only sees relevant suggestions
+- **Selected custom values** (with `allowsCustomValue` in multi-select) are filtered against the search input too, so they don't appear when they don't match
+- **`emptyLabel`** can be used to customize the empty state message (e.g. `"Loading items..."` during initial load)
+- Debouncing is the consumer's responsibility (300-500ms is typical)
 
 ### Escape Key Handling
 

package/docs/components/fields/FilterPicker.md

@@ -24,6 +24,7 @@ A versatile selection component that combines a trigger button with a searchable
 - **`selectionMode`** `'single' | 'multiple'` (default: `single`) — Selection mode for the picker
 - **`allowsCustomValue`** `boolean` (default: `false`) — Whether to allow entering custom values that are not present in the predefined options
 - **`isClearable`** `boolean` (default: `false`) — Whether the filter picker is clearable using a clear button in the rightIcon slot
+- **`isLoadingItems`** `boolean` (default: `false`) — Whether items are currently loading. Shows a loading spinner in the search input suffix inside the popover. Unlike `isLoading`, does not disable the trigger.
 - **`disallowEmptySelection`** `boolean` (default: `false`) — Whether to disallow empty selection
 - **`disabledKeys`** `Key[]` — Array of keys for disabled items
 - **`items`** `Iterable<T>` — Array of items to render when using the render function pattern for large datasets with dynamic content
@@ -33,7 +34,7 @@ A versatile selection component that combines a trigger button with a searchable
 - **`theme`** `'default' | 'special'` (default: `default`) — Button theme
 - **`size`** `'small' | 'medium' | 'large'` (default: `medium`) — Size of the picker component
 - **`searchPlaceholder`** `string` — Placeholder text in the search input
-- **`emptyLabel`** `string` — Custom label to display when no results are found after filtering
+- **`emptyLabel`** `ReactNode` (default: context-aware: `No items` or `No results found`) — Label shown when the list is empty. When provided, overrides both defaults for any empty state
 - **`filter`** `((textValue: string, inputValue: string) => boolean) | false` — Custom filter function for determining if an option should be included in search results
 - **`header`** `ReactNode` — Custom header content
 - **`footer`** `ReactNode` — Custom footer content
@@ -455,6 +456,22 @@ const categories = [
 </FilterPicker>
 ```
 
+### Loading Items
+
+Use `isLoadingItems` to indicate that items are currently being fetched. Unlike `isLoading`, the trigger stays enabled so users can still open the popover and interact with items that have already loaded. A loading spinner appears in the search input suffix.
+
+```jsx
+<FilterPicker
+  label="Loading Items"
+  placeholder="Select a fruit..."
+  isLoadingItems={true}
+  selectionMode="multiple"
+>
+  <FilterPicker.Item key="apple">Apple</FilterPicker.Item>
+  <FilterPicker.Item key="banana">Banana</FilterPicker.Item>
+</FilterPicker>
+```
+
 ### Complex Example
 
 ```jsx
@@ -714,78 +731,60 @@ The clear button:
 - Calls the optional `onClear` callback
 - Is hidden when the picker is disabled or read-only
 
-### External Filtering
-
-FilterPicker provides two approaches for implementing external filtering when you need to control the filtering logic outside the component:
+### Server-Side / Dynamic Search
 
-#### Approach 1: Disabled Internal Filtering
-
-Use `filter={false}` to disable internal filtering while providing pre-filtered items:
-
-```jsx
-const [externalSearch, setExternalSearch] = useState('');
-
-const filteredFruits = useMemo(() => {
-  if (!externalSearch.trim()) return allFruits;
-  return allFruits.filter((fruit) =>
-    fruit.label.toLowerCase().includes(externalSearch.toLowerCase())
-  );
-}, [externalSearch]);
-
-<FilterPicker
-  label="Select Fruits"
-  placeholder="Choose fruits..."
-  selectionMode="multiple"
-  filter={false}
-  items={filteredFruits}
-  searchPlaceholder="Type to search..."
->
-  {(fruit) => (
-    <FilterPicker.Item key={fruit.key}>{fruit.label}</FilterPicker.Item>
-  )}
-</FilterPicker>
-```
-
-#### Approach 2: Controlled Search Input
-
-Use `searchValue` and `onSearchChange` for complete control over the search behavior:
+When items come from a backend API, use `filter={false}` with controlled search to let the server handle filtering. Items are replaced when the response arrives, and `isLoadingItems` shows a subtle spinner in the search input while the fetch is in flight.
 
 ```jsx
+const [items, setItems] = useState(initialItems);
 const [searchValue, setSearchValue] = useState('');
+const [isLoadingItems, setIsLoadingItems] = useState(false);
 
-// Simulate debounced search
-const [processedSearch, setProcessedSearch] = useState('');
-useEffect(() => {
-  const timer = setTimeout(() => setProcessedSearch(searchValue), 300);
-  return () => clearTimeout(timer);
-}, [searchValue]);
-
-const filteredFruits = useMemo(() => {
-  if (!processedSearch.trim()) return allFruits;
-  return allFruits.filter((fruit) =>
-    fruit.label.toLowerCase().includes(processedSearch.toLowerCase())
-  );
-}, [processedSearch]);
+const handleSearchChange = useCallback((value) => {
+  setSearchValue(value);
+  setIsLoadingItems(true);
+  debouncedFetch(value)
+    .then(setItems)
+    .finally(() => setIsLoadingItems(false));
+}, []);
 
 <FilterPicker
-  label="Select Fruits"
-  placeholder="Choose fruits..."
-  selectionMode="multiple"
+  items={items}
   searchValue={searchValue}
+  onSearchChange={handleSearchChange}
   filter={false}
-  items={filteredFruits}
-  onSearchChange={setSearchValue}
+  sortSelectedToTop={false}
+  isLoadingItems={isLoadingItems}
+  placeholder="Search items..."
+  selectionMode="multiple"
+  onOpenChange={(isOpen) => {
+    if (!isOpen) {
+      setSearchValue('');
+      setItems(initialItems);
+    }
+  }}
 >
-  {(fruit) => (
-    <FilterPicker.Item key={fruit.key}>{fruit.label}</FilterPicker.Item>
+  {(item) => (
+    <FilterPicker.Item key={item.id} textValue={item.name}>
+      {item.name}
+    </FilterPicker.Item>
   )}
 </FilterPicker>
 ```
 
-**When to use each approach:**
-- **`filter={false}`**: Simpler approach when you just need to pre-filter items without controlling the search input itself. Good for server-side filtering or custom filter logic.
-- **Controlled Search**: Use when you need full control over the search input (debouncing, external UI sync, clearing from outside, or tracking search analytics).
-- **Combine Both**: You can use both together for maximum control - controlled search input with external filtering.
+**How it works:**
+- **`filter={false}`** disables client-side filtering so items are shown exactly as the server returns them
+- **`searchValue` + `onSearchChange`** give you control over the search input; debounce and fetch on your side
+- **`items`** is a reactive prop — replace it with server results and the list updates automatically
+- **`isLoadingItems`** shows a loading spinner in the search input suffix while fetching. While loading, stale items that do not text-match the current search are hidden client-side so the user only sees relevant suggestions
+- **Selected custom values** (with `allowsCustomValue` in multi-select) are filtered against the search input too, so they don't appear when they don't match
+- **`sortSelectedToTop={false}`** is recommended when the server controls item order
+- **`emptyLabel`** can be used to customize the empty state message (e.g. `"Loading items..."` during initial load)
+- **Reset on close** — use `onOpenChange` to restore the initial item set and clear the search when the popover closes, ensuring the trigger label resolves correctly
+
+**Tips:**
+- Debouncing is the consumer's responsibility (300-500ms is typical)
+- During the debounce delay, old items remain visible — if you want instant client-side feedback while waiting, use a filter function instead of `false`
 
 ## Performance
 

package/docs/tasty/dsl.md

@@ -59,6 +59,7 @@ Control how a sub-element selector attaches to the root selector using the `$` p
 | *(none)* | ` [el]` | Descendant (default) |
 | `>` | `> [el]` | Direct child |
 | `>Body>Row>` | `> [Body] > [Row] > [el]` | Chained elements |
+| `> SubElementName` | `> [SubElementName]` | Self-name shorthand — when the trailing element name matches the sub-element's own key, it acts as the placeholder (same as `@`); no duplication |
 | `h1` | ` h1` | Tag selector (no key injection) |
 | `h1 >` | ` h1 > [el]` | Key is direct child of tag |
 | `h1 *` | ` h1 *` | Any descendant of tag |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cube-dev/ui-kit",
-  "version": "0.127.3",
+  "version": "0.129.0",
   "type": "module",
   "description": "UIKit for Cube Projects",
   "repository": {
@@ -45,7 +45,7 @@
     "@react-types/shared": "^3.32.1",
     "@tabler/icons-react": "^3.31.0",
     "@tanstack/react-virtual": "^3.13.12",
-    "@tenphi/tasty": "2.1.0",
+    "@tenphi/tasty": "2.1.1",
     "clipboard-copy": "^4.0.1",
     "clsx": "^1.1.1",
     "diff": "^8.0.3",