From 70bb1e55b361d8a6e96d58ba38f90b1e3250e6b6 Mon Sep 17 00:00:00 2001 From: habubey Date: Mon, 16 Jan 2023 11:33:39 +0300 Subject: [PATCH] Refactor on tree.d.ts --- components/lib/tree/tree.d.ts | 483 +++++++++++++++++++++++++++++----- 1 file changed, 412 insertions(+), 71 deletions(-) diff --git a/components/lib/tree/tree.d.ts b/components/lib/tree/tree.d.ts index 159a52d5ad..e909694f8d 100644 --- a/components/lib/tree/tree.d.ts +++ b/components/lib/tree/tree.d.ts @@ -1,159 +1,500 @@ +/** + * + * Tree is used to display hierarchical data. + * + * [Live Demo](https://www.primefaces.org/primereact/tree/) + * + * @module tree + * + */ import * as React from 'react'; import TreeNode from '../treenode'; -type TreeSelectionModeType = 'single' | 'multiple' | 'checkbox'; - -type TreeSelectionKeys = string | TreeMultipleSelectionKeys | TreeCheckboxSelectionKeys | null; - -type TreeSelectionKeyType = boolean | TreeCheckboxSelectionKeyType; - -type TreeFilterModeType = 'lenient' | 'strict'; - -type TreeHeaderTemplateType = React.ReactNode | ((options: TreeHeaderTemplateOptions) => React.ReactNode); - -type TreeFilterTemplateType = React.ReactNode | ((options: TreeFilterOptions) => React.ReactNode); - -type TreeFooterTemplateType = React.ReactNode | ((props: TreeProps) => React.ReactNode); - -type TreeNodeTemplateType = React.ReactNode | ((node: TreeNode, options: TreeNodeTemplateOptions) => React.ReactNode); - -type TreeTogglerTemplateType = React.ReactNode | ((node: TreeNode, options: TreeTogglerTemplateOptions) => React.ReactNode); - +/** + * @todo Write the documentation. + */ interface TreeHeaderTemplateOptions { + /** + * @todo Write the documentation. + */ filterContainerClassName: string; + /** + * @todo Write the documentation. + */ filterIconClasssName: string; + /** + * @todo Write the documentation. + */ filterInput: TreeFilterInputOptions; + /** + * @todo Write the documentation. + */ filterElement: JSX.Element; + /** + * @todo Write the documentation. + */ element: JSX.Element; + /** + * @todo Write the documentation. + */ props: TreeProps; } +/** + * @todo Write the documentation. + */ interface TreeFilterInputOptions { + /** + * @todo Write the documentation. + */ className: string; + /** + * @todo Write the documentation. + */ onKeyDown(event: React.KeyboardEvent): void; + /** + * @todo Write the documentation. + */ onChange(event: React.KeyboardEvent): void; } +/** + * @todo Write the documentation. + */ interface TreeNodeTemplateOptions { - onTogglerClick(e: React.SyntheticEvent): void; + /** + * @todo Write the documentation. + */ + onTogglerClick(event: React.SyntheticEvent): void; + /** + * @todo Write the documentation. + */ className: string; + /** + * @todo Write the documentation. + */ element: JSX.Element; + /** + * @todo Write the documentation. + */ props: TreeProps; + /** + * @todo Write the documentation. + */ expanded: boolean; } +/** + * @todo Write the documentation. + */ interface TreeTogglerTemplateOptions { - onClick(e: React.SyntheticEvent): void; + /** + * @todo Write the documentation. + */ + onClick(event: React.SyntheticEvent): void; + /** + * @todo Write the documentation. + */ containerClassName: string; + /** + * @todo Write the documentation. + */ iconClassName: string; + /** + * @todo Write the documentation. + */ element: JSX.Element; + /** + * @todo Write the documentation. + */ props: TreeProps; + /** + * @todo Write the documentation. + */ expanded: boolean; } +/** + * @todo Write the documentation. + */ interface TreeMultipleSelectionKeys { + /** + * @todo Write the documentation. + */ [key: string]: boolean; } +/** + * @todo Write the documentation. + */ interface TreeCheckboxSelectionKeys { + /** + * @todo Write the documentation. + */ [key: string]: TreeCheckboxSelectionKeyType; } +/** + * @todo Write the documentation. + */ interface TreeCheckboxSelectionKeyType { + /** + * @todo Write the documentation. + */ checked?: boolean; + /** + * @todo Write the documentation. + */ partialChecked?: boolean; } +/** + * @todo Write the documentation. + */ interface TreeExpandedKeysType { + /** + * @todo Write the documentation. + */ [key: string]: boolean; } -interface TreeExpandedParams { +/** + * Custom tree event. + * @see {@link TreeProps.onToggle} + * @event + */ +interface TreeExpandedEvent { + /** + * Browser event. + */ originalEvent: React.SyntheticEvent; + /** + * @todo Write the documentation. + */ value: TreeExpandedKeysType; } -interface TreeSelectionParams { +/** + * Custom tree event. + * @see {@link TreeProps.onSelectionChange},{@link TreeProps.onContextMenuSelectionChange} + * @event + */ +interface TreeSelectionEvent { + /** + * Browser event. + */ originalEvent: React.SyntheticEvent; - value: TreeSelectionKeys; + /** + * Selected node key(s). + */ + value: string | TreeMultipleSelectionKeys | TreeCheckboxSelectionKeys | null; } -export interface TreeEventNodeParams { +/** + * Custom tree event. + * @see {@link TreeProps.onSelect},{@link TreeProps.onUnselect},{@link TreeProps.onExpand},{@link TreeProps.onCollapse},{@link TreeProps.onContextMenu} + * @event + */ +export interface TreeEventNodeEvent { + /** + * Browser event. + */ originalEvent: React.SyntheticEvent; + /** + * Unselected node instance. + */ node: TreeNode; } -interface TreeDragDropParams { +/** + * Custom dragdrop event. + * @see {@link TreeProps.onDragDrop} + * @event + */ +interface TreeDragDropEvent { + /** + * Browser event. + */ originalEvent: React.SyntheticEvent; + /** + * New value after the dragdrop. + */ value: TreeNode[]; + /** + * @todo Write the documentation. + */ dragNode: TreeNode; - dropNode: TreeNode; + /** + * @todo Write the documentation. + */ dropIndex: number; } -interface TreeFilterValueChangeParams { +/** + * Custom filter value change event. + * @see {@link TreeProps.onFilterValueChange} + * @event + */ +interface TreeFilterValueChangeEvent { + /** + * Browser event. + */ originalEvent: React.FormEvent; + /** + * The filtered value. + */ value: string; } -interface TreeNodeClickParams { +/** + * Custom click event + * @see {@link TreeProps.onNodeClick} + */ +interface TreeNodeClickEvent { + /** + * Browser event + */ originalEvent: React.SyntheticEvent; + /** + * The current node + */ node: TreeNode; } +/** + * @todo Write the documentation. + */ interface TreeFilterOptions { + /** + * @todo Write the documentation. + */ filter?: (event?: KeyboardEvent) => void; + /** + * @todo Write the documentation. + */ reset?: () => void; } -interface TreeNodeDoubleClickParams extends TreeNodeClickParams {} +/** + * Custom click event. + * @see {@link TreeProps.onNodeDoubleClick} + * @extends {TreeNodeClickEvent} + * @event + */ +interface TreeNodeDoubleClickEvent extends TreeNodeClickEvent {} +/** + * Defines valid properties in TreeProps component. + * @group Properties + */ export interface TreeProps { - id?: string; - value?: TreeNode[]; - disabled?: boolean; - selectionMode?: TreeSelectionModeType; - selectionKeys?: TreeSelectionKeys; - contextMenuSelectionKey?: string; - expandedKeys?: TreeExpandedKeysType; - style?: React.CSSProperties; - className?: string; - contentStyle?: React.CSSProperties; - contentClassName?: string; - metaKeySelection?: boolean; - propagateSelectionUp?: boolean; - propagateSelectionDown?: boolean; - loading?: boolean; - loadingIcon?: string; - dragdropScope?: string; - header?: TreeHeaderTemplateType; - footer?: TreeFooterTemplateType; - filterTemplate?: TreeFilterTemplateType; - showHeader?: boolean; - filter?: boolean; - filterValue?: string; - filterBy?: string; - filterMode?: TreeFilterModeType; - filterPlaceholder?: string; - filterLocale?: string; - togglerTemplate?: TreeTogglerTemplateType; - nodeTemplate?: TreeNodeTemplateType; - onSelectionChange?(e: TreeSelectionParams): void; - onContextMenuSelectionChange?(e: TreeSelectionParams): void; - onSelect?(e: TreeEventNodeParams): void; - onUnselect?(e: TreeEventNodeParams): void; - onExpand?(e: TreeEventNodeParams): void; - onCollapse?(e: TreeEventNodeParams): void; - onToggle?(e: TreeExpandedParams): void; - onDragDrop?(e: TreeDragDropParams): void; - onContextMenu?(e: TreeEventNodeParams): void; - onFilterValueChange?(e: TreeFilterValueChangeParams): void; - onNodeClick?(e: TreeNodeClickParams): void; - onNodeDoubleClick?(e: TreeNodeDoubleClickParams): void; - children?: React.ReactNode; + /** + * Unique identifier of the element. + */ + id?: string | undefined; + /** + * An array of treenodes. + */ + value?: TreeNode[] | undefined; + /** + * When present, it specifies that the component should be disabled. + * @defaultValue false + */ + disabled?: boolean | undefined; + /** + * Defines the selection mode, valid values "single", "multiple", and "checkbox". + */ + selectionMode?: 'single' | 'multiple' | 'checkbox' | undefined; + /** + * A single or an array of keys to control the selection state. + */ + selectionKeys?: string | TreeMultipleSelectionKeys | TreeCheckboxSelectionKeys | null; + /** + * A single key to control the selection with the context menu. + */ + contextMenuSelectionKey?: string | undefined; + /** + * An array of keys to represent the state of the tree expansion state in controlled mode. + */ + expandedKeys?: TreeExpandedKeysType | undefined; + /** + * Inline style of the component. + */ + style?: React.CSSProperties | undefined; + /** + * Style class of the component. + */ + className?: string | undefined; + /** + * Inline style of the tree content. + */ + contentStyle?: React.CSSProperties | undefined; + /** + * Style class of the tree content. + */ + contentClassName?: string | undefined; + /** + * Defines how multiple items can be selected, when true metaKey needs to be pressed to select or unselect an item and when set to false selection of each item can be toggled individually. On touch enabled devices, metaKeySelection is turned off automatically. + * @defaultValue true + */ + metaKeySelection?: boolean | undefined; + /** + * Whether checkbox selections propagate to ancestor nodes. + * @defaultValue true + */ + propagateSelectionUp?: boolean | undefined; + /** + * Whether checkbox selections propagate to descendant nodes. + * @defaultValue true + */ + propagateSelectionDown?: boolean | undefined; + /** + * Whether to display loading indicator. + * @defaultValue false + */ + loading?: boolean | undefined; + /** + * Icon to display when tree is loading. + * @defaultValue pi pi-spin + */ + loadingIcon?: string | undefined; + /** + * Unique key to enable dragdrop functionality. + * @defaultValue false + */ + dragdropScope?: string | undefined; + /** + * The template of header. + */ + header?: React.ReactNode | ((options: TreeHeaderTemplateOptions) => React.ReactNode); + /** + * The template of header. + */ + footer?: React.ReactNode | ((props: TreeProps) => React.ReactNode); + /** + * Template of filter element. + */ + filterTemplate?: React.ReactNode | ((options: TreeFilterOptions) => React.ReactNode); + /** + * Whether to show the header or not. + * @defaultValue true + */ + showHeader?: boolean | undefined; + /** + * When specified, displays an input field to filter the items. + * @defaultValue false + */ + filter?: boolean | undefined; + /** + * When filtering is enabled, the value of input field. + */ + filterValue?: string | undefined; + /** + * When filtering is enabled, filterBy decides which field or fields (comma separated) to search against. + * @defaultValue label + */ + filterBy?: string | undefined; + /** + * Mode for filtering valid values are "lenient" and "strict". Default is lenient. + * @defaultValue lenient + */ + filterMode?: 'lenient' | 'strict' | undefined; + /** + * Placeholder text to show when filter input is empty. + */ + filterPlaceholder?: string | undefined; + /** + * Locale to use in filtering. The default locale is the host environment's current locale. + * @defaultValue undefined + */ + filterLocale?: string | undefined; + /** + * Template of toggler element. + */ + togglerTemplate?: React.ReactNode | ((node: TreeNode, options: TreeTogglerTemplateOptions) => React.ReactNode); + /** + * Template of node element. + * @defaultValue false + */ + nodeTemplate?: React.ReactNode | ((node: TreeNode, options: TreeNodeTemplateOptions) => React.ReactNode); + /** + * Callback to invoke when selection changes. + * @param {TreeSelectionEvent} event - Custom select event. + */ + onSelectionChange?(event: TreeSelectionEvent): void; + /** + * Callback to invoke when selection changes with a context menu. + * @param {TreeSelectionEvent} event - Custom select event. + */ + onContextMenuSelectionChange?(event: TreeSelectionEvent): void; + /** + * Callback to invoke when a node is selected. + * @param {TreeEventNodeEvent} event - Custom node event. + */ + onSelect?(event: TreeEventNodeEvent): void; + /** + * Callback to invoke when a node is unselected. + * @param {TreeEventNodeEvent} event - Custom node event. + */ + onUnselect?(event: TreeEventNodeEvent): void; + /** + * Callback to invoke when a node is expanded. + * @param {TreeEventNodeEvent} event - Custom node event. + */ + onExpand?(event: TreeEventNodeEvent): void; + /** + * Callback to invoke when a node is collapsed. + * @param {TreeEventNodeEvent} event - Custom node event. + */ + onCollapse?(event: TreeEventNodeEvent): void; + /** + * Callback to invoke when a node is toggled. + * @param {TreeExpandedEvent} event - Custom expand event. + */ + onToggle?(event: TreeExpandedEvent): void; + /** + * Callback to invoke when a node is selected. + * @param {TreeDragDropEvent} event - Custom dragdrop event. + */ + onDragDrop?(event: TreeDragDropEvent): void; + /** + * Callback to invoke when a node is selected with a context menu. + * @param {TreeEventNodeEvent} event - Custom node event. + */ + onContextMenu?(event: TreeEventNodeEvent): void; + /** + * Callback to invoke when filter value changes. + * @param {TreeFilterValueChangeEvent} event - Custom filter value change event. + */ + onFilterValueChange?(event: TreeFilterValueChangeEvent): void; + /** + * Callback to invoke when the node is clicked. + * @param {TreeNodeClickEvent} event - Custom click event. + */ + onNodeClick?(event: TreeNodeClickEvent): void; + /** + * Callback to invoke when the node is double-clicked. + * @param {TreeNodeDoubleClickEvent} event - Custom doubleclick event. + */ + onNodeDoubleClick?(event: TreeNodeDoubleClickEvent): void; + /** + * Used to get the child elements of the component. + * @readonly + */ + children?: React.ReactNode | undefined; } +/** + * @group Component + */ export declare class Tree extends React.Component { + /** + * @todo Write the documentation. + */ public filter(value: T): void; + /** + * Used to get container element. + * @return {HTMLDivElement} Container element + */ public getElement(): HTMLDivElement; }