xmlui 0.10.15 → 0.10.16

package/dist/scripts/src/components/Tree/TreeComponent.js

@@ -1,31 +1,287 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.treeComponentRenderer = exports.TreeMd = void 0;
 const jsx_runtime_1 = require("react/jsx-runtime");
 const renderers_1 = require("../../components-core/renderers");
+const themeVars_1 = require("../../components-core/theming/themeVars");
 const container_helpers_1 = require("../container-helpers");
 const metadata_helpers_1 = require("../metadata-helpers");
 const TreeNative_1 = require("./TreeNative");
+const TreeComponent_module_scss_1 = __importDefault(require("./TreeComponent.module.scss"));
 const COMP = "Tree";
 exports.TreeMd = (0, metadata_helpers_1.createMetadata)({
-    status: "in progress",
-    description: `The \`${COMP}\` component is a virtualized tree component that displays hierarchical data.`,
+    status: "stable",
+    description: `The \`${COMP}\` component is a virtualized tree component that displays hierarchical data with support for flat and hierarchy data formats.`,
     props: {
         data: {
-            description: `The data source of the tree.`,
-            required: true,
+            description: `The data source of the tree. Format depends on the dataFormat property.`,
+            isRequired: true,
         },
-        selectedUid: {
-            description: `The ID (optional) of the selected tree row.`,
+        dataFormat: {
+            description: `The input data structure format: "flat" (array with parent relationships) or "hierarchy" (nested objects).`,
+            valueType: "string",
+            defaultValue: TreeNative_1.defaultProps.dataFormat,
+        },
+        idField: {
+            description: `The property name in source data for unique identifiers.`,
+            valueType: "string",
+            defaultValue: TreeNative_1.defaultProps.idField,
+        },
+        nameField: {
+            description: `The property name in source data for display text.`,
+            valueType: "string",
+            defaultValue: TreeNative_1.defaultProps.nameField,
+        },
+        iconField: {
+            description: `The property name in source data for icon identifiers.`,
+            valueType: "string",
+            defaultValue: TreeNative_1.defaultProps.iconField,
+        },
+        iconExpandedField: {
+            description: `The property name in source data for expanded state icons.`,
+            valueType: "string",
+            defaultValue: TreeNative_1.defaultProps.iconExpandedField,
+        },
+        iconCollapsedField: {
+            description: `The property name in source data for collapsed state icons.`,
+            valueType: "string",
+            defaultValue: TreeNative_1.defaultProps.iconCollapsedField,
+        },
+        parentIdField: {
+            description: `The property name in source data for parent relationships (used in flat format).`,
+            valueType: "string",
+            defaultValue: TreeNative_1.defaultProps.parentIdField,
+        },
+        childrenField: {
+            description: `The property name in source data for child arrays (used in hierarchy format).`,
+            valueType: "string",
+            defaultValue: TreeNative_1.defaultProps.childrenField,
+        },
+        selectableField: {
+            description: `The property name in source data for selectable state (default: "selectable").`,
+            valueType: "string",
+            defaultValue: TreeNative_1.defaultProps.selectableField,
+        },
+        selectedValue: {
+            description: `The selected item ID in source data format.`,
+        },
+        defaultExpanded: {
+            description: `Initial expansion state: "none", "all", "first-level", or array of specific IDs.`,
+            valueType: "string",
+            defaultValue: TreeNative_1.defaultProps.defaultExpanded,
+        },
+        autoExpandToSelection: {
+            description: `Automatically expand the path to the selected item.`,
+            valueType: "boolean",
+            defaultValue: TreeNative_1.defaultProps.autoExpandToSelection,
+        },
+        itemClickExpands: {
+            description: "Whether clicking anywhere on a tree item should expand/collapse the node, not just the expand/collapse icon.",
+            valueType: "boolean",
+            defaultValue: TreeNative_1.defaultProps.itemClickExpands,
+        },
+        iconCollapsed: {
+            description: `The icon name to use for collapsed nodes (default: "chevronright").`,
+            valueType: "string",
+            defaultValue: TreeNative_1.defaultProps.iconCollapsed,
+        },
+        iconExpanded: {
+            description: `The icon name to use for expanded nodes (default: "chevrondown").`,
+            valueType: "string",
+            defaultValue: TreeNative_1.defaultProps.iconExpanded,
+        },
+        iconSize: {
+            description: `The size of the expand/collapse icons (default: "16").`,
+            valueType: "string",
+            defaultValue: TreeNative_1.defaultProps.iconSize,
+        },
+        itemHeight: {
+            description: `The height of each tree row in pixels (default: 35).`,
+            valueType: "number",
+            defaultValue: TreeNative_1.defaultProps.itemHeight,
+        },
+        animateExpand: {
+            description: `When true, uses only the collapsed icon and rotates it for expansion instead of switching icons (default: false).`,
+            valueType: "boolean",
+            defaultValue: TreeNative_1.defaultProps.animateExpand,
+        },
+        expandRotation: {
+            description: `The number of degrees to rotate the collapsed icon when expanded in animate mode (default: 90).`,
+            valueType: "number",
+            defaultValue: TreeNative_1.defaultProps.expandRotation,
+        },
+        dynamicField: {
+            description: `The property name in source data for dynamic loading state (default: "dynamic").`,
+            valueType: "string",
+            defaultValue: TreeNative_1.defaultProps.dynamicField,
+        },
+        itemTemplate: {
+            description: "The template for each item in the tree.",
+            valueType: "ComponentDef",
         },
-        itemTemplate: (0, metadata_helpers_1.dComponent)("The template for each item in the tree."),
+    },
+    events: {
+        selectionDidChange: {
+            description: `Fired when the tree selection changes.`,
+            signature: `(event: TreeSelectionEvent) => void`,
+        },
+        nodeDidExpand: {
+            description: `Fired when a tree node is expanded.`,
+            signature: `(node: FlatTreeNode) => void`,
+        },
+        nodeDidCollapse: {
+            description: `Fired when a tree node is collapsed.`,
+            signature: `(node: FlatTreeNode) => void`,
+        },
+        loadChildren: {
+            description: `Fired when a tree node needs to load children dynamically. Should return a Promise that resolves to an array of child data.`,
+            signature: `(node: FlatTreeNode) => Promise<any[]>`,
+        },
+    },
+    apis: {
+        expandAll: {
+            description: `Expand all nodes in the tree.`,
+            signature: "expandAll(): void",
+        },
+        collapseAll: {
+            description: `Collapse all nodes in the tree.`,
+            signature: "collapseAll(): void",
+        },
+        expandToLevel: {
+            description: `Expand nodes up to the specified depth level (0-based).`,
+            signature: "expandToLevel(level: number): void",
+            parameters: {
+                level: "The maximum depth level to expand (0 = root level only)",
+            },
+        },
+        expandNode: {
+            description: `Expand a specific node by its source data ID.`,
+            signature: "expandNode(nodeId: string): void",
+            parameters: {
+                nodeId: "The ID of the node to expand (source data format)",
+            },
+        },
+        collapseNode: {
+            description: `Collapse a specific node by its source data ID.`,
+            signature: "collapseNode(nodeId: string): void",
+            parameters: {
+                nodeId: "The ID of the node to collapse (source data format)",
+            },
+        },
+        selectNode: {
+            description: `Programmatically select a node by its source data ID.`,
+            signature: "selectNode(nodeId: string): void",
+            parameters: {
+                nodeId: "The ID of the node to select (source data format)",
+            },
+        },
+        clearSelection: {
+            description: `Clear the current selection.`,
+            signature: "clearSelection(): void",
+        },
+        getNodeById: {
+            description: `Get a tree node by its source data ID.`,
+            signature: "getNodeById(nodeId: string): TreeNode | null",
+            parameters: {
+                nodeId: "The ID of the node to retrieve (source data format)",
+            },
+        },
+        getExpandedNodes: {
+            description: `Get an array of currently expanded node IDs in source data format.`,
+            signature: "getExpandedNodes(): string[]",
+        },
+        getSelectedNode: {
+            description: `Get the currently selected tree node.`,
+            signature: "getSelectedNode(): TreeNode | null",
+        },
+        appendNode: {
+            description: `Add a new node to the tree as a child of the specified parent node.`,
+            signature: "appendNode(parentNodeId: string | number | null, nodeData: any): void",
+            parameters: {
+                parentNodeId: "The ID of the parent node, or null/undefined to add to root level",
+                nodeData: "The node data object using the format specified in dataFormat and field properties",
+            },
+        },
+        removeNode: {
+            description: `Remove a node and all its descendants from the tree.`,
+            signature: "removeNode(nodeId: string | number): void",
+            parameters: {
+                nodeId: "The ID of the node to remove (along with all its descendants)",
+            },
+        },
+        removeChildren: {
+            description: `Remove all children (descendants) of a node while keeping the node itself.`,
+            signature: "removeChildren(nodeId: string | number): void",
+            parameters: {
+                nodeId: "The ID of the parent node whose children should be removed",
+            },
+        },
+        insertNodeBefore: {
+            description: `Insert a new node before an existing node at the same level.`,
+            signature: "insertNodeBefore(beforeNodeId: string | number, nodeData: any): void",
+            parameters: {
+                beforeNodeId: "The ID of the existing node before which the new node should be inserted",
+                nodeData: "The node data object using the format specified in dataFormat and field properties",
+            },
+        },
+        insertNodeAfter: {
+            description: `Insert a new node after an existing node at the same level.`,
+            signature: "insertNodeAfter(afterNodeId: string | number, nodeData: any): void",
+            parameters: {
+                afterNodeId: "The ID of the existing node after which the new node should be inserted",
+                nodeData: "The node data object using the format specified in dataFormat and field properties",
+            },
+        },
+    },
+    themeVars: (0, themeVars_1.parseScssVar)(TreeComponent_module_scss_1.default.themeVars),
+    defaultThemeVars: {
+        [`backgroundColor-${COMP}-row--selected`]: "$color-primary-50",
+        [`backgroundColor-${COMP}-row--hover`]: "$color-surface-100",
+        [`textColor-${COMP}`]: "$textColor-primary",
+        [`textColor-${COMP}--selected`]: "$color-primary-900",
+        [`textColor-${COMP}--hover`]: "$textColor-primary",
+        [`borderColor-${COMP}-row--focus`]: "$color-primary-500",
+        [`outlineColor-${COMP}--focus`]: "$outlineColor--focus",
+        [`outlineWidth-${COMP}--focus`]: "$outlineWidth--focus",
+        [`outlineStyle-${COMP}--focus`]: "$outlineStyle--focus",
+        [`outlineOffset-${COMP}--focus`]: "$outlineOffset--focus",
     },
 });
 /**
  * This function defines the renderer for the Tree component.
  */
-exports.treeComponentRenderer = (0, renderers_1.createComponentRenderer)(COMP, exports.TreeMd, ({ node, extractValue, renderChild, className }) => {
-    return ((0, jsx_runtime_1.jsx)(TreeNative_1.TreeComponent, { className: className, data: extractValue(node.props.data), selectedUid: extractValue(node.props.selectedUid), itemRenderer: (item) => {
-            return ((0, jsx_runtime_1.jsx)(container_helpers_1.MemoizedItem, { node: node.props.itemTemplate, item: item, renderChild: renderChild }));
+exports.treeComponentRenderer = (0, renderers_1.createComponentRenderer)(COMP, exports.TreeMd, ({ node, extractValue, renderChild, className, lookupEventHandler, registerComponentApi }) => {
+    // Default item template if none is provided:
+    //   <HStack verticalAlignment="center">
+    //     <Icon when="{$item.icon}" name="{$item.icon}" />
+    //     <Text value="{$item.name}" />
+    //   </HStack>
+    const defaultItemTemplate = {
+        type: "HStack",
+        props: {
+            verticalAlignment: "center",
+        },
+        children: [
+            {
+                type: "Icon",
+                when: "{$item.icon}",
+                props: {
+                    name: "{$item.icon}",
+                },
+            },
+            {
+                type: "Text",
+                props: {
+                    value: "{$item.name}",
+                },
+            },
+        ],
+    };
+    return ((0, jsx_runtime_1.jsx)(TreeNative_1.TreeComponent, { registerComponentApi: registerComponentApi, className: className, data: extractValue(node.props.data), dataFormat: extractValue(node.props.dataFormat), idField: extractValue(node.props.idField), nameField: extractValue(node.props.nameField), iconField: extractValue(node.props.iconField), iconExpandedField: extractValue(node.props.iconExpandedField), iconCollapsedField: extractValue(node.props.iconCollapsedField), parentIdField: extractValue(node.props.parentIdField), childrenField: extractValue(node.props.childrenField), selectableField: extractValue(node.props.selectableField), dynamicField: extractValue(node.props.dynamicField), selectedValue: extractValue(node.props.selectedValue), selectedId: extractValue(node.props.selectedId), defaultExpanded: extractValue(node.props.defaultExpanded), autoExpandToSelection: extractValue(node.props.autoExpandToSelection), itemClickExpands: extractValue.asOptionalBoolean(node.props.itemClickExpands), iconCollapsed: extractValue(node.props.iconCollapsed), iconExpanded: extractValue(node.props.iconExpanded), iconSize: extractValue(node.props.iconSize), itemHeight: extractValue.asOptionalNumber(node.props.itemHeight, TreeNative_1.defaultProps.itemHeight), animateExpand: extractValue.asOptionalBoolean(node.props.animateExpand, TreeNative_1.defaultProps.animateExpand), expandRotation: extractValue.asOptionalNumber(node.props.expandRotation, TreeNative_1.defaultProps.expandRotation), onSelectionChanged: lookupEventHandler("selectionDidChange"), onNodeExpanded: lookupEventHandler("nodeDidExpand"), onNodeCollapsed: lookupEventHandler("nodeDidCollapse"), loadChildren: lookupEventHandler("loadChildren"), itemRenderer: (flatTreeNode) => {
+            const itemContext = Object.assign({ id: flatTreeNode.id, name: flatTreeNode.displayName, depth: flatTreeNode.depth, isExpanded: flatTreeNode.isExpanded, hasChildren: flatTreeNode.hasChildren }, flatTreeNode);
+            return node.props.itemTemplate ? ((0, jsx_runtime_1.jsx)(container_helpers_1.MemoizedItem, { node: node.props.itemTemplate, item: itemContext, renderChild: renderChild })) : ((0, jsx_runtime_1.jsx)(container_helpers_1.MemoizedItem, { node: defaultItemTemplate, item: itemContext, renderChild: renderChild }));
         } }));
 });