@central-design-system/skills 4.0.0-alpha.6

package/skills/cds-builder/references/components/cds-tree/api.md

@@ -0,0 +1,169 @@
+# CdsTree — API
+
+> Generated from meta.json by `bun run generate:skill`. Do not edit manually.
+> Examples: [examples.md](examples.md) · Guidelines: [guidelines.md](guidelines.md) · Tokens: [tokens.md](tokens.md)
+
+A tree shows a hierarchy: catalog sections, project files, an org structure. Nodes expand, get selected by a click or with checkboxes, load from the server and can be dragged, while virtual scrolling keeps everything smooth even with thousands of nodes.
+
+Family: [CdsTree](#cdstree) + subcomponents: [CdsTreeDirectory](#cdstreedirectory), [CdsTreeNode](#cdstreenode).
+
+## CdsTree
+
+**Props**
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `allowDrop` | `NTree.TAllowDrop<NTree.IDataNode> \| undefined` | `true` | no | Decides whether a node accepts a drop |
+| `autoExpandParent` | `boolean \| undefined` | `false` | no | Expands the parent node automatically |
+| `blockNode` | `boolean \| undefined` | `false` | no | The tree node fills all the remaining horizontal space |
+| `checkable` | `boolean \| undefined` | `false` | no | Adds a checkbox before the tree nodes |
+| `checkedKeys` | `NTree.TKey[] \| { checked: NTree.TKey[]; halfChecked: NTree.TKey[]; } \| undefined` | — | no | (v-model) Keys of the checked tree nodes. When the key of a parent node is given, all its child nodes become checked; and the other way around, when the key of a child node is given, its parent node becomes checked too. When `checkable` and `checkStrictly` are both true, the object has the `checked` and `halfChecked` fields, and checking a child or a parent node no longer affects the other. |
+| `checkStrictly` | `boolean \| undefined` | `false` | no | Checks only the node itself, without its parents and children. |
+| `defaultExpandAll` | `boolean \| undefined` | `false` | no | Expands all the nodes by default |
+| `defaultExpandedKeys` | `NTree.TKey[] \| undefined` | `[]` | no | Expands all the nodes by default |
+| `defaultExpandParent` | `boolean \| undefined` | `true` | no | Expands the parent nodes by default |
+| `defaultSelectedKeys` | `NTree.TKey[] \| undefined` | — | no | Tree nodes selected by default |
+| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
+| `draggable` | `boolean \| NTree.TDraggableConfig \| undefined` | `false` | no | Allows dragging the tree nodes |
+| `expandAction` | `NTree.TExpandAction \| undefined` | — | no | Action that expands or collapses the tree nodes |
+| `expandedKeys` | `NTree.TKey[] \| undefined` | — | no | (v-model) Keys of the expanded tree nodes. |
+| `fieldNames` | `NTree.IFieldNames \| undefined` | — | no | Maps the title, key and children fields of a tree node to the matching fields of treeData |
+| `filterTreeNode` | `((treeNode: NTree.IEventDataNode) => boolean) \| undefined` | — | no | Function that filters (highlights) the tree nodes. When it returns true, the node is highlighted. |
+| `height` | `number \| undefined` | — | no | Height of the virtual scrolling list |
+| `icon` | `((nodeProps: NTree.ITreeNodeAttribute) => any) \| undefined` | — | no | Icon of the tree node (also available through slot#icon) |
+| `loadData` | `((treeNode: NTree.IEventDataNode) => Promise<any>) \| undefined` | — | no | Loads the data of a tree node asynchronously |
+| `loadedKeys` | `NTree.TKey[] \| undefined` | `[]` | no | Keys of the already loaded tree nodes. Required to work with loadData |
+| `multiple` | `boolean \| undefined` | `false` | no | Allows selecting several tree nodes |
+| `openAnimation` | `Function \| undefined` | — | no | Animation function for expanding and collapsing a tree node |
+| `selectable` | `boolean \| undefined` | `false` | no | Makes the tree nodes selectable |
+| `selectedKeys` | `NTree.TKey[] \| undefined` | — | no | (v-model) Keys of the selected tree nodes. |
+| `showIcon` | `boolean \| undefined` | `false` | no | Shows the icon of the tree node |
+| `showLine` | `boolean \| { showLeafIcon: string \| boolean; } \| undefined` | — | no | Shows the lines between the tree nodes |
+| `switcherIcon` | `((nodeProps: SwitcherIconProps) => any) \| undefined` | — | no | Icon of the expand/collapse switcher (also available through slot#switcherIcon) |
+| `theme` | `string \| undefined` | — | no | Component theme |
+| `treeData` | `NTree.IDataNode[] \| undefined` | — | no | Data of the tree |
+| `virtual` | `boolean \| undefined` | `true` | no | Enables virtual scrolling of the list inside the tree; enabled by default |
+
+**Events**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `check` | `[checked: NTree.TKey[] \| { checked: NTree.TKey[]; halfChecked: NTree.TKey[]; }, info: NTree.ICheckInfo]` | A node was checked with its checkbox. |
+| `click` | `[event: MouseEvent, node: NTree.IEventDataNode]` | Click on a node. |
+| `dblclick` | `[event: MouseEvent, node: NTree.IEventDataNode]` | Double click on a node. |
+| `doubleclick` | `[event: MouseEvent, node: NTree.IEventDataNode]` | Double click on a node (alias). |
+| `dragend` | `[info: NTree.TNodeDragEventParams]` | Dragging of a node finished. |
+| `dragenter` | `[info: NTree.TNodeDragEventParams & { expandedKeys: NTree.TKey[]; }]` | A dragged node entered the drop area. |
+| `dragleave` | `[info: NTree.TNodeDragEventParams]` | A dragged node left the drop area. |
+| `dragover` | `[info: NTree.TNodeDragEventParams]` | A dragged node moves inside the drop area. |
+| `dragstart` | `[info: NTree.TNodeDragEventParams]` | Dragging of a node started. |
+| `drop` | `[info: NTree.TNodeDragEventParams & { dragNode: NTree.IEventDataNode; dragNodesKeys: NTree.TKey[]; dropPosition: number; dropToGap: boolean; }]` | A node was dropped. |
+| `expand` | `[expandedKeys: NTree.TKey[], info: { node: NTree.IEventDataNode; expanded: boolean; nativeEvent: MouseEvent; }]` | A node was expanded or collapsed. |
+| `load` | `[loadedKeys: NTree.TKey[], info: { event: "load"; node: NTree.IEventDataNode; }]` | Children of a node were loaded (async loadData). |
+| `rightClick` | `[info: { event: MouseEvent; node: NTree.IEventDataNode; }]` | Right click on a node. |
+| `select` | `[selectedKeys: NTree.TKey[], info: { event: "select"; selected: boolean; node: NTree.IEventDataNode; selectedNodes: NTree.IDataNode[]; nativeEvent: MouseEvent; }]` | A node was selected. |
+| `update:checkedKeys` | `[checkedKeys: NTree.TKey[] \| { checked: NTree.TKey[]; halfChecked: NTree.TKey[]; }]` | Checking of a node changed (v-model). |
+| `update:expandedKeys` | `[expandedKeys: NTree.TKey[]]` | Expansion of a node changed (v-model). |
+| `update:selectedKeys` | `[selectedKeys: NTree.TKey[]]` | Selection of a node changed (v-model). |
+
+**Slots**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `default` | `any` | Tree nodes by default (when described declaratively in markup). |
+| `icon` | `NTree.ITreeNodeAttribute` | Custom icon of the tree node. |
+| `switcherIcon` | `any` | Custom icon of the expand/collapse switcher. |
+| `title` | `NTree.IEventDataNode` | Custom title of the tree node. |
+
+**Exposed**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `halfCheckedKeys` | `any` | Keys of the nodes with partially checked children — the “half checked” state. |
+| `loadingKeys` | `any` | Keys of the nodes whose children are being lazily loaded right now. |
+| `scrollTo` | `ScrollTo` | Scrolls the tree to a node by its key or to a given position. |
+| `treeRef` | `any` | Reference to the internal tree instance. |
+
+---
+
+## CdsTreeDirectory
+
+**Props**
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `allowDrop` | `NTree.TAllowDrop<NTree.IDataNode> \| undefined` | `true` | no | Decides whether a node accepts a drop |
+| `autoExpandParent` | `boolean \| undefined` | `false` | no | Expands the parent node automatically |
+| `blockNode` | `boolean \| undefined` | `false` | no | The tree node fills all the remaining horizontal space |
+| `checkable` | `boolean \| undefined` | `false` | no | Adds a checkbox before the tree nodes |
+| `checkedKeys` | `NTree.TKey[] \| { checked: NTree.TKey[]; halfChecked: NTree.TKey[]; } \| undefined` | — | no | (v-model) Keys of the checked tree nodes. When the key of a parent node is given, all its child nodes become checked; and the other way around, when the key of a child node is given, its parent node becomes checked too. When `checkable` and `checkStrictly` are both true, the object has the `checked` and `halfChecked` fields, and checking a child or a parent node no longer affects the other. |
+| `checkStrictly` | `boolean \| undefined` | `false` | no | Checks only the node itself, without its parents and children. |
+| `defaultExpandAll` | `boolean \| undefined` | `false` | no | Expands all the nodes by default |
+| `defaultExpandedKeys` | `NTree.TKey[] \| undefined` | `[]` | no | Expands all the nodes by default |
+| `defaultExpandParent` | `boolean \| undefined` | `true` | no | Expands the parent nodes by default |
+| `defaultSelectedKeys` | `NTree.TKey[] \| undefined` | — | no | Tree nodes selected by default |
+| `draggable` | `boolean \| NTree.TDraggableConfig \| undefined` | `false` | no | Allows dragging the tree nodes |
+| `expandAction` | `string \| false \| undefined` | — | no | Action that expands or collapses the tree nodes |
+| `expandedKeys` | `NTree.TKey[] \| undefined` | — | no | (v-model) Keys of the expanded tree nodes. |
+| `fieldNames` | `NTree.IFieldNames \| undefined` | — | no | Maps the title, key and children fields of a tree node to the matching fields of treeData |
+| `filterTreeNode` | `((treeNode: NTree.IEventDataNode) => boolean) \| undefined` | — | no | Function that filters (highlights) the tree nodes. When it returns true, the node is highlighted. |
+| `height` | `number \| undefined` | — | no | Height of the virtual scrolling list |
+| `icon` | `((nodeProps: NTree.ITreeNodeAttribute) => any) \| undefined` | — | no | Icon of the tree node (also available through slot#icon) |
+| `loadData` | `((treeNode: NTree.IEventDataNode) => Promise<any>) \| undefined` | — | no | Loads the data of a tree node asynchronously |
+| `loadedKeys` | `NTree.TKey[] \| undefined` | `[]` | no | Keys of the already loaded tree nodes. Required to work with loadData |
+| `multiple` | `boolean \| undefined` | `false` | no | Allows selecting several tree nodes |
+| `openAnimation` | `Function \| undefined` | — | no | Animation function for expanding and collapsing a tree node |
+| `selectable` | `boolean \| undefined` | `false` | no | Makes the tree nodes selectable |
+| `selectedKeys` | `NTree.TKey[] \| undefined` | — | no | (v-model) Keys of the selected tree nodes. |
+| `showIcon` | `boolean \| undefined` | `false` | no | Shows the icon of the tree node |
+| `showLine` | `boolean \| { showLeafIcon: string \| boolean; } \| undefined` | — | no | Shows the lines between the tree nodes |
+| `switcherIcon` | `((nodeProps: SwitcherIconProps) => any) \| undefined` | — | no | Icon of the expand/collapse switcher (also available through slot#switcherIcon) |
+| `treeData` | `NTree.IDataNode[] \| undefined` | — | no | Data of the tree |
+| `virtual` | `boolean \| undefined` | `true` | no | Enables virtual scrolling of the list inside the tree; enabled by default |
+
+**Events**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `check` | `[checked: NTree.TKey[] \| { checked: NTree.TKey[]; halfChecked: NTree.TKey[]; }, info: NTree.ICheckInfo]` | A node was checked with its checkbox. |
+| `click` | `[event: MouseEvent, node: NTree.IEventDataNode]` | Click on a node. |
+| `dblclick` | `[event: MouseEvent, node: NTree.IEventDataNode]` | Double click on a node. |
+| `doubleclick` | `[event: MouseEvent, node: NTree.IEventDataNode]` | Double click on a node (alias). |
+| `dragend` | `[info: NTree.TNodeDragEventParams]` | Dragging of a node finished. |
+| `dragenter` | `[info: NTree.TNodeDragEventParams & { expandedKeys: NTree.TKey[]; }]` | A dragged node entered the drop area. |
+| `dragleave` | `[info: NTree.TNodeDragEventParams]` | A dragged node left the drop area. |
+| `dragover` | `[info: NTree.TNodeDragEventParams]` | A dragged node moves inside the drop area. |
+| `dragstart` | `[info: NTree.TNodeDragEventParams]` | Dragging of a node started. |
+| `drop` | `[info: NTree.TNodeDragEventParams & { dragNode: NTree.IEventDataNode; dragNodesKeys: NTree.TKey[]; dragPosition: number; dropToGap: boolean; }]` | A node was dropped. |
+| `expand` | `[expandedKeys: NTree.TKey[], info: { node: NTree.IEventDataNode; expanded: boolean; nativeEvent: MouseEvent; }]` | A node was expanded or collapsed. |
+| `load` | `[treeNode: NTree.IEventDataNode]` | Children of a node were loaded (async loadData). |
+| `rightClick` | `[info: { event: MouseEvent; node: NTree.IEventDataNode; }]` | Right click on a node. |
+| `select` | `[selectedKeys: NTree.TKey[], info: { event: "select"; selected: boolean; node: NTree.IEventDataNode; selectedNodes: NTree.IDataNode[]; nativeEvent: MouseEvent; }]` | A node was selected. |
+| `update:checkedKeys` | `[checkedKeys: NTree.TKey[] \| { checked: NTree.TKey[]; halfChecked: NTree.TKey[]; }]` | Checking of a node changed (v-model). |
+| `update:expandedKeys` | `[expandedKeys: NTree.TKey[]]` | Expansion of a node changed (v-model). |
+| `update:selectedKeys` | `[selectedKeys: NTree.TKey[]]` | Selection of a node changed (v-model). |
+
+---
+
+## CdsTreeNode
+
+**Props**
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `active` | `boolean \| undefined` | — | no | Highlights the node as active |
+| `checkable` | `boolean \| undefined` | — | no | Shows a checkbox next to the node |
+| `data` | `NTree.IDataNode \| undefined` | `undefined as unknown as NTree.IDataNode` | no | Data of the node — the original list item the node is built from |
+| `disableCheckbox` | `boolean \| undefined` | — | no | Disables only the checkbox of the node, leaving the node itself available |
+| `disabled` | `boolean \| undefined` | — | no | Disables the node: it cannot be selected, checked or expanded |
+| `domRef` | `((arg: any) => void) \| undefined` | — | no | Callback that receives the DOM element of the node after mounting |
+| `eventKey` | `NTree.TKey \| undefined` | `''` | no | Unique key of the node — the tree uses it to track selection, expansion and checking |
+| `icon` | `Function \| undefined` | — | no | Function that returns the icon of the node |
+| `isEnd` | `boolean[] \| undefined` | — | no | “Last on its level” flags for every nesting level — the connecting lines are drawn from them |
+| `isLeaf` | `boolean \| undefined` | — | no | The node is a leaf: it has no children and shows no expand switcher |
+| `isStart` | `boolean[] \| undefined` | — | no | “First on its level” flags for every nesting level — the connecting lines are drawn from them |
+| `parent` | `NTree.IDataNode \| undefined` | `undefined as unknown as NTree.IDataNode` | no | Data of the parent node. Not set for the top-level nodes |
+| `prefixCls` | `string \| undefined` | — | no | Prefix of the CSS classes of the node |
+| `selectable` | `boolean \| undefined` | — | no | Allows selecting the node |
+| `switcherIcon` | `Function \| undefined` | — | no | Function that returns the icon of the expand switcher |
+| `title` | `string \| (Function & string) \| undefined` | — | no | Tree node title: a string or a render function |