gadgets
Version:
Reusable React UI widgets - This is my widget library. There are many like it, but this one is mine...
218 lines (217 loc) • 9.64 kB
TypeScript
/**
* This component represents data in a hierarchical parent/child view. The
* underlying code uses the [react-sortable-tree](https://www.npmjs.com/package/react-sortable-tree)
* react component written by Chris Fritz. The [README](https://github.com/fritz-c/react-sortable-tree/blob/master/README.md)
* for the project shows examples and properties for the component.
*
* The control relies on feeding data back into the control via props (as
* treeData state) to control the contents; the calling app is responsible for
* the data. The `treeData` uses the following array of node structures
* (TreeviewItem), where a node is defined as:
*
* [
* {title: "string", subtitle: "string", expanded: "boolean", children: ["treeData"]},
* {title: "string", subtitle: "string", expanded: "boolean", children: [
* {title: "string", subtitle: "string", expanded: "boolean", children: ["treeData"]},
* {title: "string", subtitle: "string", expanded: "boolean", children: ["treeData"]}
* ]}
* ...
* ]
*
* Where `title` and `subtitle` are shown on the node as Label. It is editable
* by double clicking the text in the node. The `expanded` boolean will show objects
* under the parent (if they exist) based on the `children` prop. The
* `children` prop is an array on the parent node of the child nodes linked to
* this parent. Each of these nodes are also potential parent, etc (recursive
* relationship). When the tree data is passed to this component via props a UUID is generated
* for eacxh node and stored in the *id* key. Also the children of a parent node are given this
* id as the *parentId*. These values are stored on the TreeItem nodes, so these keys and their
* relationships are available to the caller (via callbacks when changes occur).
*
* ## Screen:
* <img src="https://github.com/jmquigley/gadgets/blob/master/images/treeview.png" width="60%" />
*
* ## Examples:
*
* ```javascript
* import {TreeItem, Treeview} from 'gadgets';
*
* ...
*
* this.state = {
* treeData: [
* {title: '1.0', expanded: true, children: [
* {title: '1.1'},
* {title: '1.2'},
* {title: '1.3'}
* ]},
* {title: '2.0', expanded: true, children: [
* {title: '2.1'},
* {title: '2.2'},
* {title: '2.3'}
* ]},
* {title: '3.0', expanded: true, children: [
* {title: '3.1'},
* {title: '3.2'},
* {title: '3.3'}
* ]}
* ];
*
* ...
*
* <Treeview
* height="640px"
* onChange={(treeData: TreeItem[]) => this.setState({treeData})}
* treeData={this.state.treeData}
* />
* ```
*
* These are the minimum properties required to display the control.
*
* ## API
* #### Events
* - `onAdd(node: ExtendedNodeData, treeData: TreeItem[])` - Invoked when a new node is
* added to the tree via the "+" add button of the parent (when highlighting the parent
* node). The node sent to the callback represents the node added to the tree.
* - `onChange(treeData: {TreeItem[]})` - Invoked when something in the tree has
* changed. The callback receives an array of TreeItem nodes used to represent the
* current state of the tree.
* - `onCollapse(treeData: TreeItem[])` - Invoked when the full tree is collapsed
* via the collapse all button.
* - `onDelete(node: TreeItem, treeData: TreeItem[]` - Invoked when a node is
* removed from the tree. The node parameter is the node that was deleted.
* - `onExpand(treeData: TreeItem[])` - Invoked when the full tree is expanded
* via the expand all button.
* - `onInit(treeData: TreeItem[])` - Invoked when the constructor first builds the
* internal tree from the props treeData it may not have all parent/child keys.
* This callback will send back a sanitized version of the treeData structure when
* the tree is initialized. This is only called once.
* - `onSearch(node: TreeItem)` - Invoked when a search is performed. It returns
* the current item found in the search. This callback is also called when moving
* to/from previous/next the title.
* - `onSelection(node: TreeItem)` - Invoked when a tree item is selected. The node
* selected is passed to the callback. The node that was selected is also highlighted.
* - `onUpdate(currentNode: TreeItem, previousNode: TreeItem, treeData: TreeItem[])` -
* Invoked when the contents of a tree node (title) have been changed. It passes
* a reference to the new node (current), the previous node before the change, and the
* new treeData array after the change was applied.
*
* #### Styles
* - `ui-treeview` - Root style applied to the SortableTree component wrapper.
* - `ui-treeview-container` - applied to a div that surrounds the tree control and the
* toolbar used to control it.
* this is where the height of the control is handled.
* - `ui-treeview-toolbar` - applied to the search toollbar
*
* #### Properties
* - `addAsFirstChild=true {boolean}` - when set to true new nodes are added at
* the front of the parent. Otherwise they are added to the end. The default is
* to add them to the front.
* - `defaultTitle='New Title' {string}` - When a new node is added this title is
* used as the placeholder label.
* - `direction=Direction.top {Direction}` - Determines the location of the search
* toolbar. If set to Direction.top it is at the top of the component. If set to
* Direction.bottom it is on the bottom.
* - `height="15em" {string}` - The height of the treeview container. This must
* be set or the tree will not display anything.
* - `kbAdd="" {string}` - keyboard combination to add a new node as a child
* of the selected node.
* - `kbCollapseAll="ctrl+-" {string}` - keyboard combination to collapse all
* nodes.
* - `kbDelete="" {string}` - keyboard combination to remove the node that is
* selected.
* - `kbExpandAll="ctrl+=" {string}` - keyboard combination to expand all nodes.
* - `nodeWidth="20em" {string}` - the width of the text nodes that are displayed.
* - `noscroll=false {boolean}` - turns off the scroll bars when the width/height
* of all nodes expands past the right or bottom edge of the display container.
* - `nosearch=false {boolean}` - turns off the search toolbar for the widget
* - `nosubtitles=false {boolean}` - turns the node subtitle display on or off
* It is on by default.
* - `selectedId=null {number|string}` - the id value of the node that should
* be selected. Only use this if the parent component that will wrap this one
* needs to control what is selected in the component.
* - `selectNew=true {boolean}` - When a new node is added it is selected by
* default (true). If this property is false, then the parent remains selected
* when a child node is added.
* - `treeData=[] {TreeItem[]}` - The data structure that describes the
* tree hierarchy (see example above).
* - `usehidden=true {boolean}` - by default the add/delete buttons are hidden on
* each of the nodes. They are revealed when hovering over the node. This behavior
* can be turned off by setting this prop to false.
*
* @module Treeview
*/
/// <reference types="react" />
import { ExtendedNodeData, NodeData } from "react-sortable-tree";
import { GeneralTreeItem } from "util.ds";
import { BaseComponent, BaseProps, BaseState, Direction } from "../shared";
export declare type TreeviewSelectedId = string | number;
export interface TreeviewData {
title?: string;
subtitle?: string;
expanded?: boolean;
[key: string]: any;
}
export { NodeData, ExtendedNodeData };
export declare type TreeItem = GeneralTreeItem<TreeviewData>;
export interface TreeviewProps extends BaseProps {
addAsFirstChild: boolean;
defaultTitle: string;
direction: Direction;
isVirtualized: boolean;
kbAdd: string;
kbCollapseAll: string;
kbDelete: string;
kbExpandAll: string;
nodeWidth?: string;
noscroll?: boolean;
nosearch?: boolean;
nosubtitles?: boolean;
onAdd?: (node: TreeItem, treeData: TreeItem[]) => void;
onChange?: (treeData: TreeItem[]) => void;
onCollapse?: (treeData: TreeItem[]) => void;
onDelete?: (node: TreeItem, treeData: TreeItem[]) => void;
onExpand?: (treeData: TreeItem[]) => void;
onInit?: (treeData: TreeItem[]) => void;
onSearch?: (node: TreeItem) => void;
onSelection?: (node: TreeItem) => void;
onUpdate?: (node: TreeItem, previous: TreeItem, treeData: TreeItem[]) => void;
selectedId?: TreeviewSelectedId;
selectNew: boolean;
treeData: TreeItem[];
usehidden?: boolean;
}
export interface TreeviewState extends BaseState {
matches?: NodeData[];
search?: string;
searchFocusIndex?: number;
searchFoundCount?: number;
selectedId?: TreeviewSelectedId;
}
export declare class Treeview extends BaseComponent<TreeviewProps, TreeviewState> {
static defaultProps: TreeviewProps;
private _rowHeights;
private _td;
private _toolbar;
constructor(props: TreeviewProps);
readonly rowHeight: any;
private buildToolbar;
private clearSearch;
private customNodeProperties;
private handleAdd;
private handleChange;
private handleDelete;
private handleKeyboardDelete;
private handleNextMatch;
private handleNodeExpand;
private handleNodeCollapse;
private handleNodeExpansion;
private handleNodeUpdate;
private handlePreviousMatch;
private handleSearch;
private handleSearchFinish;
private handleSelection;
componentDidUpdate(prevProps: TreeviewProps, prevState: TreeviewState): void;
render(): JSX.Element;
}
export default Treeview;