tree-element 0.1.0

package/lib/index.d.ts

@@ -0,0 +1,367 @@
+import type { MoveInfo, TreeEvent, TreeEventName, TreeEvents } from "./events.js";
+import type { NodeData, NodeId, Position } from "./node.js";
+import type { TreeElementOptions } from "./options.js";
+import type { SavedState } from "./saveStateHandler.js";
+import type { SelectNodeOptions } from "./selectNodeHandler.js";
+import { Node } from "./node.js";
+export type { MoveInfo, Node, NodeData, NodeId, Position, SavedState, SelectNodeOptions, TreeElementOptions, TreeEvent, TreeEventName, TreeEvents, };
+export type TriggerEventProvider = (element: HTMLElement, eventName: TreeEventName, values?: TreeEvents[TreeEventName]) => boolean;
+interface TreeElementParams extends Partial<TreeElementOptions> {
+    /** The element the tree is rendered into. Its content is replaced. */
+    htmlElement: HTMLElement;
+    /** Replaces how events are dispatched. It must return whether the event
+     * was not cancelled. This exists for tests and for integrating with
+     * another event system. */
+    overrideTriggerEventProvider?: TriggerEventProvider;
+}
+export default class TreeElement {
+    /** @hidden */
+    tree: Node;
+    private classNames;
+    private dataLoader;
+    private dndHandler;
+    private htmlElement;
+    private isInitialized;
+    private keyHandler;
+    private mouseHandler;
+    private nodeMap;
+    private options;
+    private renderer;
+    private saveStateHandler;
+    private scrollHandler;
+    private selectNodeHandler;
+    private triggerEventProvider;
+    /** @hidden */
+    constructor({ htmlElement, overrideTriggerEventProvider, ...options }: TreeElementParams);
+    /**
+     * Adds a sibling after a node.
+     *
+     * @returns The new node, or `null` when the node has no parent.
+     * @group Changing the tree
+     */
+    addNodeAfter(nodeData: NodeData, existingNode: Node): Node | null;
+    /**
+     * Adds a sibling before a node.
+     *
+     * @returns The new node, or `null` when the node has no parent.
+     * @group Changing the tree
+     */
+    addNodeBefore(nodeData: NodeData, existingNode: Node): Node | null;
+    /**
+     * Inserts a new node between a node and its parent, taking the node as its
+     * child.
+     *
+     * @returns The new node, or `null` when the node has no parent.
+     * @group Changing the tree
+     */
+    addParentNode(nodeData: NodeData, existingNode: Node): Node | null;
+    /**
+     * Adds a node to the selection instead of replacing it.
+     *
+     * @param mustSetFocus - Move the focus to the node. Default `true`.
+     * @group Selection
+     */
+    addToSelection(node: Node, mustSetFocus?: boolean): void;
+    /**
+     * Adds a node as the last child of a parent.
+     *
+     * @example
+     * ```js
+     * tree.appendNode({ name: "child", id: 5 }, tree.getNodeById(1));
+     * ```
+     *
+     * @returns The new node.
+     * @group Changing the tree
+     */
+    appendNode(nodeData: NodeData, parentNode: Node): Node;
+    /**
+     * Closes a folder.
+     *
+     * @param slide - Override the `slide` option for this call.
+     * @group Opening and closing
+     */
+    closeNode(node: Node, slide?: boolean): void;
+    /**
+     * Empties the element and removes the tree's document-level keyboard
+     * listener. Call it when you remove the tree from the page.
+     *
+     * @group Other
+     */
+    deinit(): void;
+    /**
+     * Returns the node that belongs to a `li` element the tree rendered.
+     *
+     * @group Finding nodes
+     */
+    getNode(element: HTMLElement): Node | null;
+    /**
+     * Returns the first node for which the callback returns `true`.
+     *
+     * @example
+     * ```js
+     * const node = tree.getNodeByCallback((node) => node.children.length > 3);
+     * ```
+     *
+     * @group Finding nodes
+     */
+    getNodeByCallback(callback: (node: Node) => boolean): Node | null;
+    /**
+     * Returns the node with this id.
+     *
+     * @example
+     * ```js
+     * const node = tree.getNodeById(1);
+     * ```
+     *
+     * @group Finding nodes
+     */
+    getNodeById(id: NodeId): Node | null;
+    /**
+     * Returns the first node with this name.
+     *
+     * @group Finding nodes
+     */
+    getNodeByName(name: string): Node | null;
+    /**
+     * Like `getNodeByName`, but throws when there is no such node. Convenient
+     * in tests and when a missing node is a bug.
+     *
+     * @group Finding nodes
+     */
+    getNodeByNameMustExist(name: string): Node;
+    /**
+     * Returns all nodes with this property value.
+     *
+     * @example
+     * ```js
+     * tree.getNodesByProperty("color", "green");
+     * ```
+     *
+     * @group Finding nodes
+     */
+    getNodesByProperty(key: string, value: unknown): Node[];
+    /**
+     * Returns the selected node, or `false` when nothing is selected.
+     *
+     * @group Selection
+     */
+    getSelectedNode(): false | Node;
+    /**
+     * Returns the selected nodes.
+     *
+     * @group Selection
+     */
+    getSelectedNodes(): Node[];
+    /**
+     * Returns the current state — `open_nodes` and `selected_node` — whether or
+     * not `saveState` is enabled.
+     *
+     * @group State
+     */
+    getState(): null | SavedState;
+    /**
+     * Returns the state as it is stored.
+     *
+     * @group State
+     */
+    getStateFromStorage(): null | SavedState;
+    /**
+     * Returns the root node. It is not rendered; its `children` are the
+     * top-level nodes. Also available as the `tree` property.
+     *
+     * @group Finding nodes
+     */
+    getTree(): Node;
+    /**
+     * Returns the version of tree-element.
+     *
+     * @group Other
+     */
+    getVersion(): string;
+    /**
+     * Returns whether the user is dragging a node.
+     *
+     * @group Other
+     */
+    isDragging(): boolean;
+    /**
+     * Returns whether the node is selected.
+     *
+     * @group Selection
+     */
+    isNodeSelected(node: Node): boolean;
+    /**
+     * Loads data into the tree.
+     *
+     * @param parentNode - Replace this node's children instead of the whole
+     * tree.
+     * @group Loading data
+     */
+    loadData(data: NodeData[] | null, parentNode?: Node): void;
+    /**
+     * Fetches data and loads it into the tree, or into `parentNode`.
+     *
+     * @param url - Defaults to the `dataUrl` option.
+     * @group Loading data
+     */
+    loadDataFromUrl(url?: string, parentNode?: Node): Promise<void>;
+    /**
+     * Selects the next visible node, like the down arrow key.
+     *
+     * @group Selection
+     */
+    moveDown(): void;
+    /**
+     * Moves a node inside the tree.
+     *
+     * @example
+     * ```js
+     * tree.moveNode(tree.getNodeById(2), tree.getNodeById(1), "inside");
+     * ```
+     *
+     * @param position - `"before"`, `"after"` or `"inside"`.
+     * @group Changing the tree
+     */
+    moveNode(node: Node, targetNode: Node, position: Position): void;
+    /**
+     * Selects the previous visible node, like the up arrow key.
+     *
+     * @group Selection
+     */
+    moveUp(): void;
+    /**
+     * Opens a folder, and the folders above it. A node marked `load_on_demand`
+     * is fetched first, so await the promise when you need to know it is really
+     * open.
+     *
+     * @example
+     * ```js
+     * await tree.openNode(node);
+     * console.log("open");
+     * ```
+     *
+     * @param slide - Override the `slide` option for this call.
+     * @group Opening and closing
+     */
+    openNode(node: Node, slide?: boolean): Promise<void>;
+    /**
+     * Adds a node as the first child of a parent.
+     *
+     * @returns The new node.
+     * @group Changing the tree
+     */
+    prependNode(nodeData: NodeData, parentNode: Node): Node;
+    /**
+     * Re-renders the whole tree. Needed after changing node data directly
+     * instead of through these methods.
+     *
+     * @group Changing the tree
+     */
+    refresh(): void;
+    /**
+     * Recomputes the drop targets. Call this if the layout changes during a
+     * drag.
+     *
+     * @group Other
+     */
+    refreshHitAreas(): void;
+    /**
+     * Removes a node from the selection.
+     *
+     * @group Selection
+     */
+    removeFromSelection(node: Node): void;
+    /**
+     * Removes a node and its children.
+     *
+     * @group Changing the tree
+     */
+    removeNode(node: Node): void;
+    /**
+     * Scrolls the node into view.
+     *
+     * @group Selection
+     */
+    scrollToNode(node: Node): void;
+    /**
+     * Replaces the selection, and opens the parents of the node.
+     *
+     * @param node - `null` clears the selection.
+     * @param options - `mustSetFocus`: move focus to the node, default `true`.
+     * `mustToggle`: deselect the node if it is already selected, default
+     * `false`.
+     * @group Selection
+     */
+    selectNode(node: Node | null, options?: SelectNodeOptions): void;
+    /**
+     * Changes an option after construction. See
+     * [Options](/reference/options#changing-an-option-later) for the caveats.
+     *
+     * @group Other
+     */
+    setOption(option: string, value: unknown): void;
+    /**
+     * Applies a state to the tree.
+     *
+     * @group State
+     */
+    setState(state: SavedState): void;
+    /**
+     * Closes an open node and opens a closed one.
+     *
+     * @param slide - Override the `slide` option for this call.
+     * @group Opening and closing
+     */
+    toggle(node: Node, slide?: boolean | null): void;
+    /**
+     * Returns the tree as a json string, including changes made through the
+     * api.
+     *
+     * @group Other
+     */
+    toJson(): string;
+    /**
+     * Updates the data of a node and re-renders it. A string updates just the
+     * name.
+     *
+     * Changing the `id` re-indexes the node. `children` and `parent` are
+     * ignored — use `loadData` or `moveNode` for those.
+     *
+     * @example
+     * ```js
+     * tree.updateNode(node, "new name");
+     * tree.updateNode(node, { name: "new name", color: "red" });
+     * ```
+     *
+     * @group Changing the tree
+     */
+    updateNode(node: Node, data: NodeData): void;
+    private createFolderElement;
+    private createNodeElement;
+    private createRequestUrl;
+    private deselectCurrentNode;
+    private deselectNodes;
+    private getAutoOpenMaxLevel;
+    private getNodeElement;
+    private getNodeElementForNode;
+    private getNodeIdToBeSelected;
+    private initData;
+    private initTree;
+    private isFocusOnTree;
+    private isSelectedNodeInSubtree;
+    private loadFolderOnDemand;
+    private loadSubtree;
+    private mouseCapture;
+    private mouseDrag;
+    private mouseStart;
+    private mouseStop;
+    private openParents;
+    private refreshElements;
+    private saveState;
+    private selectCurrentNode;
+    private setInitialState;
+    private setInitialStateOnDemand;
+    private setNodeElement;
+    private triggerEvent;
+}
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE/E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAQ7D,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAgB9B,YAAY,EACV,QAAQ,EACR,IAAI,EACJ,QAAQ,EACR,MAAM,EACN,QAAQ,EACR,UAAU,EACV,iBAAiB,EACjB,kBAAkB,EAClB,SAAS,EACT,aAAa,EACb,UAAU,GACX,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG,CACjC,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,aAAa,EACxB,MAAM,CAAC,EAAE,UAAU,CAAC,aAAa,CAAC,KAC/B,OAAO,CAAC;AAEb,UAAU,iBAAkB,SAAQ,OAAO,CAAC,kBAAkB,CAAC;IAC7D,sEAAsE;IACtE,WAAW,EAAE,WAAW,CAAC;IACzB;;+BAE2B;IAC3B,4BAA4B,CAAC,EAAE,oBAAoB,CAAC;CACrD;AAED,MAAM,CAAC,OAAO,OAAO,WAAW;IAC9B,cAAc;IACP,IAAI,EAAE,IAAI,CAAC;IAElB,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,UAAU,CAAqB;IACvC,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,aAAa,CAAU;IAC/B,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,QAAQ,CAAmB;IACnC,OAAO,CAAC,gBAAgB,CAAmB;IAC3C,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,iBAAiB,CAAoB;IAC7C,OAAO,CAAC,oBAAoB,CAAuB;IAEnD,cAAc;gBACF,EAAE,WAAW,EAAE,4BAA4B,EAAE,GAAG,OAAO,EAAE,EAAE,iBAAiB;IAwLxF;;;;;OAKG;IACI,YAAY,CACjB,QAAQ,EAAE,QAAQ,EAClB,YAAY,EAAE,IAAI,GACjB,IAAI,GAAG,IAAI;IAUd;;;;;OAKG;IACI,aAAa,CAClB,QAAQ,EAAE,QAAQ,EAClB,YAAY,EAAE,IAAI,GACjB,IAAI,GAAG,IAAI;IAUd;;;;;;OAMG;IACI,aAAa,CAClB,QAAQ,EAAE,QAAQ,EAClB,YAAY,EAAE,IAAI,GACjB,IAAI,GAAG,IAAI;IAUd;;;;;OAKG;IACI,cAAc,CAAC,IAAI,EAAE,IAAI,EAAE,YAAY,CAAC,EAAE,OAAO;IASxD;;;;;;;;;;OAUG;IACI,UAAU,CAAC,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,IAAI,GAAG,IAAI;IAQ7D;;;;;OAKG;IACI,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,IAAI;IAWnD;;;;;OAKG;IACI,MAAM,IAAI,IAAI;IAUrB;;;;OAIG;IACI,OAAO,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,GAAG,IAAI;IAYjD;;;;;;;;;OASG;IACI,iBAAiB,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,GAAG,IAAI,GAAG,IAAI;IAIxE;;;;;;;;;OASG;IACI,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAI3C;;;;OAIG;IACI,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAI/C;;;;;OAKG;IACI,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIjD;;;;;;;;;OASG;IACI,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,EAAE;IAI9D;;;;OAIG;IACI,eAAe,IAAI,KAAK,GAAG,IAAI;IAItC;;;;OAIG;IACI,gBAAgB,IAAI,IAAI,EAAE;IAIjC;;;;;OAKG;IACI,QAAQ,IAAI,IAAI,GAAG,UAAU;IAIpC;;;;OAIG;IACI,mBAAmB,IAAI,IAAI,GAAG,UAAU;IAI/C;;;;;OAKG;IACI,OAAO,IAAI,IAAI;IAItB;;;;OAIG;IACI,UAAU,IAAI,MAAM;IAI3B;;;;OAIG;IACI,UAAU,IAAI,OAAO;IAI5B;;;;OAIG;IACI,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO;IAI1C;;;;;;OAMG;IACI,QAAQ,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,UAAU,CAAC,EAAE,IAAI,GAAG,IAAI;IAoBjE;;;;;OAKG;IACU,eAAe,CAC1B,GAAG,CAAC,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,IAAI,GAChB,OAAO,CAAC,IAAI,CAAC;IAQhB;;;;OAIG;IACI,QAAQ;IAOf;;;;;;;;;;OAUG;IACI,QAAQ,CACb,IAAI,EAAE,IAAI,EACV,UAAU,EAAE,IAAI,EAChB,QAAQ,EAAE,QAAQ,GACjB,IAAI;IAKP;;;;OAIG;IACI,MAAM;IAOb;;;;;;;;;;;;;OAaG;IACU,QAAQ,CACnB,IAAI,EAAE,IAAI,EACV,KAAK,CAAC,EAAE,OAAO,GACd,OAAO,CAAC,IAAI,CAAC;IAwChB;;;;;OAKG;IACI,WAAW,CAAC,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,IAAI,GAAG,IAAI;IAQ9D;;;;;OAKG;IACI,OAAO;IAId;;;;;OAKG;IACI,eAAe;IAItB;;;;OAIG;IACI,mBAAmB,CAAC,IAAI,EAAE,IAAI;IAOrC;;;;OAIG;IACI,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAQnC;;;;OAIG;IACI,YAAY,CAAC,IAAI,EAAE,IAAI;IAY9B;;;;;;;;OAQG;IACI,UAAU,CACf,IAAI,EAAE,IAAI,GAAG,IAAI,EACjB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,IAAI;IAWP;;;;;OAKG;IACI,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;IAI/C;;;;OAIG;IACI,QAAQ,CAAC,KAAK,EAAE,UAAU;IAKjC;;;;;OAKG;IACI,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,GAAE,OAAO,GAAG,IAAW;IAUtD;;;;;OAKG;IACI,MAAM,IAAI,MAAM;IAIvB;;;;;;;;;;;;;;OAcG;IACI,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,GAAG,IAAI;IA6BnD,OAAO,CAAC,mBAAmB;IAuB3B,OAAO,CAAC,iBAAiB;IAqBzB,OAAO,CAAC,gBAAgB;IA+BxB,OAAO,CAAC,mBAAmB;IAQ3B,OAAO,CAAC,aAAa;IASrB,OAAO,CAAC,mBAAmB;IAa3B,OAAO,CAAC,cAAc;IAStB,OAAO,CAAC,qBAAqB;IAQ7B,OAAO,CAAC,qBAAqB;IAI7B,OAAO,CAAC,QAAQ;IAchB,OAAO,CAAC,QAAQ;IA+BhB,OAAO,CAAC,aAAa;IAkBrB,OAAO,CAAC,uBAAuB;YAUjB,kBAAkB;IAWhC,OAAO,CAAC,WAAW;IASnB,OAAO,CAAC,YAAY;IAQpB,OAAO,CAAC,SAAS;IAWjB,OAAO,CAAC,UAAU;IASlB,OAAO,CAAC,SAAS;IAUjB,OAAO,CAAC,WAAW;IAYnB,OAAO,CAAC,eAAe;IAevB,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,iBAAiB;IAUzB,OAAO,CAAC,eAAe;YAkDT,uBAAuB;IA4DrC,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,YAAY;CAGrB"}