@webx-ui/core 0.9.0 → 0.11.0

package/dist/composables/useTreeNodes.d.ts

@@ -0,0 +1,96 @@
+import { MaybeRefOrGetter, Ref } from 'vue';
+export type TreeKey = string | number;
+/** Where a dragged node lands relative to the one it was dropped on. */
+export type TreeDropZone = 'before' | 'after' | 'inside';
+/**
+ * How to read one node. Everything else here works through these four, which is what
+ * lets the same machinery drive a tree of its own and a table whose rows happen to
+ * nest: neither has to agree with the other on what a node looks like.
+ */
+export interface TreeAccessors<T> {
+    key: (node: T, path: number[]) => TreeKey;
+    children: (node: T) => T[] | undefined;
+    /** Called when a branch that had no `children` array needs one. */
+    setChildren: (node: T, children: T[]) => void;
+    label?: (node: T) => string;
+    disabled?: (node: T) => boolean;
+    /** Says a node has nothing under it — only needed with `lazy`, where an empty
+     * `children` cannot tell "not loaded yet" from "nothing there". */
+    leaf?: (node: T) => boolean;
+}
+/** One node and everything about where it sits, kept for the whole tree. */
+export interface TreeEntry<T> {
+    node: T;
+    key: TreeKey;
+    depth: number;
+    /** The array this node currently lives in — moving is a splice on it. */
+    siblings: T[];
+    index: number;
+    parent: T | null;
+    parentKey: TreeKey | null;
+    children: T[];
+}
+/** A node as the screen shows it: visible, in order, at a depth. */
+export interface TreeRow<T> extends TreeEntry<T> {
+    expandable: boolean;
+    expanded: boolean;
+    loading: boolean;
+    disabled: boolean;
+    /** Matched the filter itself, as opposed to merely leading to a match. */
+    matched: boolean;
+}
+export interface UseTreeNodesOptions<T> {
+    /**
+     * The tree. A getter or a plain array is enough for a tree that is only read; a
+     * `ref` is what a tree that can be rearranged wants, since a move splices the array
+     * the caller is holding.
+     */
+    nodes: MaybeRefOrGetter<T[]>;
+    accessors: TreeAccessors<T>;
+    /** Keys of the open branches. Owned by the caller, so `v-model:expanded` works. */
+    expanded: Ref<TreeKey[]>;
+    /** Only branches matching this, and the branches leading to them, are shown. */
+    filter?: MaybeRefOrGetter<string | undefined>;
+    /** Opening a branch closes the others at its level. */
+    accordion?: MaybeRefOrGetter<boolean>;
+    /** Children arrive when a branch opens. Requires `load`. */
+    lazy?: MaybeRefOrGetter<boolean>;
+    load?: (node: T) => T[] | Promise<T[]>;
+    /** Vetoes a move before it happens. */
+    allowDrop?: (drag: T, drop: T, zone: TreeDropZone) => boolean;
+}
+/**
+ * The parts of a tree that have nothing to do with how it looks: what is where, what is
+ * open, what a filter leaves standing, and what a move does to the arrays underneath.
+ */
+export declare function useTreeNodes<T>(options: UseTreeNodesOptions<T>): {
+    rows: import('vue').ComputedRef<TreeRow<T>[]>;
+    entries: import('vue').ComputedRef<Map<TreeKey, TreeEntry<T>>>;
+    entry: (key: TreeKey) => TreeEntry<T> | undefined;
+    keyOf: (node: T, path?: number[]) => TreeKey;
+    filtered: import('vue').ComputedRef<{
+        keep: Set<TreeKey>;
+        matched: Set<TreeKey>;
+    } | null>;
+    isExpanded: (key: TreeKey) => boolean;
+    expand: (key: TreeKey) => Promise<void>;
+    collapse: (key: TreeKey) => void;
+    toggle: (key: TreeKey) => void | Promise<void>;
+    expandAll: () => void;
+    collapseAll: () => void;
+    reveal: (key: TreeKey) => void;
+    openPath: (keys: TreeKey[]) => Promise<boolean>;
+    ancestors: (key: TreeKey) => TreeEntry<T>[];
+    path: (key: TreeKey) => TreeEntry<T>[];
+    descendants: (key: TreeKey) => TreeEntry<T>[];
+    isAncestorOf: (key: TreeKey, other: TreeKey) => boolean;
+    canDrop: (dragKey: TreeKey, dropKey: TreeKey, zone: TreeDropZone) => boolean;
+    move: (dragKey: TreeKey, dropKey: TreeKey, zone: TreeDropZone) => {
+        node: T;
+        parent: T | null;
+        siblings: T[];
+        index: number;
+    } | null;
+    loading: Ref<Set<TreeKey> & Omit<Set<TreeKey>, keyof Set<any>>, Set<TreeKey> | (Set<TreeKey> & Omit<Set<TreeKey>, keyof Set<any>>)>;
+};
+export type UseTreeNodes<T> = ReturnType<typeof useTreeNodes<T>>;