@webx-ui/core 0.9.0 → 0.10.0

package/README.md

@@ -46,10 +46,28 @@ const title = ref('')
 `@webx-ui/core/style.css` already includes the token variables, so importing
 `@webx-ui/tokens/tokens.css` separately is optional.
 
-## Implemented
+## What is in it
 
-`WxButton`, `WxInput`, `WxCard`. The full component roadmap lives in
-[the docs](https://webx-ui.github.io/webx-ui/guide/roadmap.html).
+91 components — the form controls, the layout, the overlays, the data ones (`WxTable` takes
+Laravel's `paginate()` payload as it comes), and the ones an admin panel needs that Element Plus
+has no name for: `WxListDetail`, `WxKanban`, `WxEntityCard`, `WxSelectionArea`,
+`WxSortableList`. The [roadmap](https://webx-ui.github.io/webx-ui/guide/roadmap.html) lists every
+one of them and what is still open.
+
+Not everything is a component:
+
+```ts
+import { toast, confirm, openModal, createModal } from '@webx-ui/core'
+
+toast.success('Saved')
+if (await confirm('Delete this product?')) await api.delete(product)
+
+/* Any component, mounted from code and awaited for its answer. */
+const product = await createModal<Product>(ProductBrowser, { resolveOn: 'select' })()
+```
+
+One directive ships with the library, `v-wx-select`, which hands an item to the selection area
+around it. `app.use(WebxUI)` registers it along with the components.
 
 ## Conventions
 

package/dist/components/Table/Table.d.ts

@@ -12,8 +12,9 @@ declare const _default: <T extends TableRow = TableRow>(__VLS_props: NonNullable
         readonly "onSort-change"?: ((sort: TableSort | null) => any) | undefined;
         readonly "onSelection-change"?: ((keys: RowKey[], rows: T[]) => any) | undefined;
         readonly "onExpand-change"?: ((keys: RowKey[], rows: T[]) => any) | undefined;
+        readonly "onNode-drop"?: ((event: import('./types').TableNodeDropEvent<T>) => any) | undefined;
         readonly "onState-change"?: ((state: TableState) => any) | undefined;
-    } & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps, never>, "onSearch" | "onUpdate:page" | "onUpdate:perPage" | "onUpdate:selected" | "onUpdate:expanded" | "onUpdate:sort" | "onUpdate:search" | "onRow-click" | "onSort-change" | "onSelection-change" | "onExpand-change" | "onState-change"> & ({
+    } & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps, never>, "onSearch" | "onUpdate:page" | "onUpdate:perPage" | "onUpdate:selected" | "onUpdate:expanded" | "onUpdate:sort" | "onUpdate:search" | "onRow-click" | "onSort-change" | "onSelection-change" | "onExpand-change" | "onNode-drop" | "onState-change"> & ({
         selected?: RowKey[];
         expanded?: RowKey[];
         sort?: TableSort | null;
@@ -70,7 +71,7 @@ declare const _default: <T extends TableRow = TableRow>(__VLS_props: NonNullable
             index: number;
         }) => unknown;
     };
-    emit: (((evt: "search", term: string) => void) & ((evt: "row-click", row: T, index: number, event: MouseEvent) => void) & ((evt: "sort-change", sort: TableSort | null) => void) & ((evt: "selection-change", keys: RowKey[], rows: T[]) => void) & ((evt: "expand-change", keys: RowKey[], rows: T[]) => void) & ((evt: "state-change", state: TableState) => void)) & (((evt: "update:page", value: number) => void) & ((evt: "update:perPage", value: number) => void) & ((evt: "update:selected", value: RowKey[]) => void) & ((evt: "update:expanded", value: RowKey[]) => void) & ((evt: "update:sort", value: TableSort | null) => void) & ((evt: "update:search", value: string) => void));
+    emit: (((evt: "search", term: string) => void) & ((evt: "row-click", row: T, index: number, event: MouseEvent) => void) & ((evt: "sort-change", sort: TableSort | null) => void) & ((evt: "selection-change", keys: RowKey[], rows: T[]) => void) & ((evt: "expand-change", keys: RowKey[], rows: T[]) => void) & ((evt: "node-drop", event: import('./types').TableNodeDropEvent<T>) => void) & ((evt: "state-change", state: TableState) => void)) & (((evt: "update:page", value: number) => void) & ((evt: "update:perPage", value: number) => void) & ((evt: "update:selected", value: RowKey[]) => void) & ((evt: "update:expanded", value: RowKey[]) => void) & ((evt: "update:sort", value: TableSort | null) => void) & ((evt: "update:search", value: string) => void));
 }>) => import('vue').VNode & {
     __ctx?: Awaited<typeof __VLS_setup>;
 };

package/dist/components/Table/types.d.ts

@@ -1,4 +1,6 @@
 import { ControlSize } from '../../composables/useFormField';
+import { TreeDropZone } from '../../composables/useTreeNodes';
+export type { TreeDropZone };
 /**
  * A page as Laravel's `->paginate()` serialises it. Taken as it arrives, with the
  * snake_case keys intact — renaming them in every controller is work the table can
@@ -63,6 +65,57 @@ export interface TableSummaryRow {
     strong?: boolean;
     class?: string;
 }
+/**
+ * Turns the rows into a tree: the first column keeps the disclosure and the
+ * indentation, every other column is still a column.
+ *
+ * A tree is a structure, and the two things a table does to a flat list destroy it —
+ * so in this mode `sortable` columns are drawn without their control and `pagination`
+ * is off. Ordering a tree is what dragging is for, and a page of it would cut branches
+ * in half.
+ */
+export interface TableTreeOptions<T = TableRow> {
+    /** Field holding the children of a row. */
+    childrenKey?: string;
+    /**
+     * Field that says a row has children before any have been fetched — Laravel's
+     * `withCount('children')` under its own name, or a boolean of your own. Without it a
+     * lazy table cannot tell a leaf from a branch nobody has opened yet.
+     */
+    hasChildrenKey?: string;
+    /** Children arrive when a row is opened. Requires `load`. */
+    lazy?: boolean;
+    /** Fetches the children of one row. */
+    load?: (row: T) => T[] | Promise<T[]>;
+    /** Open every branch that is already loaded, once, on the first render. */
+    defaultExpandAll?: boolean;
+    /** How far one level sits from the next, in pixels. */
+    indent?: number;
+    /** Rows can be picked up and dropped before, after or inside another. */
+    draggable?: boolean;
+    /** Rows this returns `false` for cannot be picked up. */
+    allowDrag?: (row: T) => boolean;
+    /** Vetoes a landing spot before anything moves. */
+    allowDrop?: (drag: T, drop: T, zone: TreeDropZone) => boolean;
+    /**
+     * How long a row dragged over a closed branch waits before that branch opens.
+     * Dropping into a branch you cannot see the inside of is a guess; this turns the
+     * guess into a look. Zero switches it off.
+     */
+    springDelay?: number;
+}
+/** What a finished move says: the row, where it went, and how it got there. */
+export interface TableNodeDropEvent<T = TableRow> {
+    row: T;
+    /** The row it was dropped on. */
+    target: T;
+    zone: TreeDropZone;
+    /** The row it now hangs from — `null` at the top level. */
+    parent: T | null;
+    /** Its position among its new siblings. */
+    index: number;
+    via: 'pointer' | 'keyboard';
+}
 /** Everything the table asks the backend for, in one object. */
 export interface TableState {
     page: number;
@@ -124,6 +177,8 @@ export interface TableProps<T = TableRow> {
     maxHeight?: string | number;
     /** Extra class per row, for status colouring and the like. */
     rowClass?: (row: T, index: number) => string | undefined;
+    /** Draws the rows as a tree. See {@link TableTreeOptions}. */
+    tree?: TableTreeOptions<T>;
     /** Fixes the column widths instead of letting the content decide. */
     layout?: 'auto' | 'fixed';
     ariaLabel?: string;
@@ -133,6 +188,8 @@ export interface TableEmits<T = TableRow> {
     'sort-change': [sort: TableSort | null];
     'selection-change': [keys: RowKey[], rows: T[]];
     'expand-change': [keys: RowKey[], rows: T[]];
+    /** A row was moved in tree mode. The rows have already been rearranged. */
+    'node-drop': [event: TableNodeDropEvent<T>];
     search: [term: string];
     /**
      * Everything the backend needs, together. Fires once on mount — with whatever

package/dist/components/Transfer/Transfer.d.ts

@@ -0,0 +1,57 @@
+import { TransferItem, TransferProps, TransferSide, TransferValue } from './types';
+type __VLS_Props = TransferProps;
+type __VLS_PublicProps = {
+    modelValue?: TransferValue[];
+} & __VLS_Props;
+declare function __VLS_template(): {
+    attrs: Partial<{}>;
+    slots: Readonly<{
+        /** One row, on either side. */
+        item?: (props: {
+            item: TransferItem;
+            side: TransferSide;
+        }) => unknown;
+        /** Shown in a panel with nothing in it. */
+        empty?: (props: {
+            side: TransferSide;
+        }) => unknown;
+    }> & {
+        /** One row, on either side. */
+        item?: (props: {
+            item: TransferItem;
+            side: TransferSide;
+        }) => unknown;
+        /** Shown in a panel with nothing in it. */
+        empty?: (props: {
+            side: TransferSide;
+        }) => unknown;
+    };
+    refs: {};
+    rootEl: HTMLDivElement;
+};
+type __VLS_TemplateResult = ReturnType<typeof __VLS_template>;
+declare const __VLS_component: import('vue').DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    change: (change: import('./types').TransferChange) => any;
+    "update:modelValue": (value: TransferValue[]) => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    onChange?: ((change: import('./types').TransferChange) => any) | undefined;
+    "onUpdate:modelValue"?: ((value: TransferValue[]) => any) | undefined;
+}>, {
+    size: import('../..').ControlSize;
+    disabled: boolean;
+    emptyText: string;
+    height: number | string;
+    items: TransferItem[];
+    searchable: boolean;
+    searchPlaceholder: string;
+    titles: [string, string];
+    toRightLabel: string;
+    toLeftLabel: string;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, HTMLDivElement>;
+declare const _default: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
+export default _default;
+type __VLS_WithTemplateSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/components/Transfer/index.d.ts

@@ -0,0 +1,2 @@
+export { default as WxTransfer } from './Transfer';
+export type * from './types';

package/dist/components/Transfer/types.d.ts

@@ -0,0 +1,40 @@
+import { ControlSize } from '../../composables/useFormField';
+export type TransferValue = string | number;
+export type TransferSide = 'left' | 'right';
+export interface TransferItem {
+    value: TransferValue;
+    /** What is read on the row. Falls back to the value. */
+    label?: string;
+    /** A second line under the label. */
+    description?: string;
+    /** Cannot be moved, from either side. */
+    disabled?: boolean;
+}
+export interface TransferProps {
+    /** Everything there is to choose from, both panels together. */
+    items?: TransferItem[];
+    /** Headings of the two panels. */
+    titles?: [string, string];
+    /** A search field over each panel. */
+    searchable?: boolean;
+    searchPlaceholder?: string;
+    /** Height of a list: a number in pixels, or any CSS length. */
+    height?: number | string;
+    /** Shown in a panel with nothing in it. */
+    emptyText?: string;
+    size?: ControlSize;
+    disabled?: boolean;
+    /** Accessible names for the two buttons. */
+    toRightLabel?: string;
+    toLeftLabel?: string;
+}
+export interface TransferChange {
+    /** What moved, in the order it was shown. */
+    values: TransferValue[];
+    /** Which panel it moved to. */
+    to: TransferSide;
+}
+export interface TransferEmits {
+    /** Something moved. The model has already been rewritten. */
+    change: [change: TransferChange];
+}

package/dist/components/Tree/Tree.d.ts

@@ -0,0 +1,79 @@
+import { TreeKey } from '../../composables/useTreeNodes';
+import { TreeNode, TreeProps } from './types';
+declare const _default: <T extends TreeNode>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_expose?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
+    props: __VLS_PrettifyLocal<Pick<Partial<{}> & Omit<{
+        readonly "onUpdate:modelValue"?: ((value: T[]) => any) | undefined;
+        readonly onCheck?: ((keys: TreeKey[], detail: {
+            node: T;
+            checked: boolean;
+        }) => any) | undefined;
+        readonly onSelect?: ((node: T | null, key: TreeKey | null) => any) | undefined;
+        readonly onCollapse?: ((node: T) => any) | undefined;
+        readonly onDrop?: ((event: import('./types').TreeDropEvent<T>) => any) | undefined;
+        readonly onExpand?: ((node: T) => any) | undefined;
+        readonly "onUpdate:selected"?: ((value: TreeKey | null) => any) | undefined;
+        readonly "onUpdate:expanded"?: ((value: TreeKey[]) => any) | undefined;
+        readonly "onUpdate:checked"?: ((value: TreeKey[]) => any) | undefined;
+        readonly "onNode-click"?: ((node: T, event: MouseEvent) => any) | undefined;
+    } & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps, never>, "onUpdate:modelValue" | "onDrop" | "onSelect" | "onCollapse" | "onExpand" | "onUpdate:selected" | "onUpdate:expanded" | "onCheck" | "onUpdate:checked" | "onNode-click"> & ({
+        modelValue?: T[];
+        expanded?: TreeKey[];
+        selected?: TreeKey | null;
+        checked?: TreeKey[];
+    } & TreeProps<T>) & Partial<{}>> & import('vue').PublicProps;
+    expose(exposed: import('vue').ShallowUnwrapRef<{
+        /** Opens every branch on the way to a node. */
+        reveal: (key: TreeKey) => void;
+        /**
+         * Opens a named path one level at a time, waiting for each lazy level before asking
+         * for the next — the way to reach a node the tree has not fetched yet.
+         */
+        openPath: (keys: TreeKey[]) => Promise<boolean>;
+        expandAll: () => void;
+        collapseAll: () => void;
+        /** The node itself and everything above it — a breadcrumb of the tree. */
+        path: (key: TreeKey) => T[];
+    }>): void;
+    attrs: any;
+    slots: Readonly<{
+        /** One node's label. Without it the tree reads `labelKey` and highlights the filter. */
+        default?: (props: {
+            node: T;
+            depth: number;
+            expanded: boolean;
+            selected: boolean;
+        }) => unknown;
+        /** The end of a row, where the buttons that act on it go. */
+        actions?: (props: {
+            node: T;
+            depth: number;
+        }) => unknown;
+        /** Shown in place of an empty tree. */
+        empty?: () => unknown;
+    }> & {
+        /** One node's label. Without it the tree reads `labelKey` and highlights the filter. */
+        default?: (props: {
+            node: T;
+            depth: number;
+            expanded: boolean;
+            selected: boolean;
+        }) => unknown;
+        /** The end of a row, where the buttons that act on it go. */
+        actions?: (props: {
+            node: T;
+            depth: number;
+        }) => unknown;
+        /** Shown in place of an empty tree. */
+        empty?: () => unknown;
+    };
+    emit: (((evt: "check", keys: TreeKey[], detail: {
+        node: T;
+        checked: boolean;
+    }) => void) & ((evt: "select", node: T | null, key: TreeKey | null) => void) & ((evt: "collapse", node: T) => void) & ((evt: "drop", event: import('./types').TreeDropEvent<T>) => void) & ((evt: "expand", node: T) => void) & ((evt: "node-click", node: T, event: MouseEvent) => void)) & (((evt: "update:modelValue", value: T[]) => void) & ((evt: "update:selected", value: TreeKey | null) => void) & ((evt: "update:expanded", value: TreeKey[]) => void) & ((evt: "update:checked", value: TreeKey[]) => void));
+}>) => import('vue').VNode & {
+    __ctx?: Awaited<typeof __VLS_setup>;
+};
+export default _default;
+type __VLS_PrettifyLocal<T> = {
+    [K in keyof T]: T[K];
+} & {};

package/dist/components/Tree/index.d.ts

@@ -0,0 +1,2 @@
+export { default as WxTree } from './Tree';
+export type * from './types';

package/dist/components/Tree/types.d.ts

@@ -0,0 +1,99 @@
+import { TreeDropZone, TreeKey } from '../../composables/useTreeNodes';
+export type { TreeDropZone, TreeKey };
+export type TreeSize = 'sm' | 'md';
+/**
+ * A node as the tree hopes to find it. Every field is optional and every name is a prop
+ * away from being something else, so a record straight out of a Laravel controller —
+ * `{ id, title, children }` — is a tree without a `map` over it first.
+ */
+export interface TreeNode {
+    id?: TreeKey;
+    key?: TreeKey;
+    label?: string;
+    children?: TreeNode[];
+    disabled?: boolean;
+    /**
+     * Says this node has nothing under it. Only needed with `lazy`, where an empty
+     * `children` cannot tell "not loaded yet" from "nothing there".
+     */
+    leaf?: boolean;
+    [field: string]: unknown;
+}
+/** What a finished move says: the node, where it went, and how it got there. */
+export interface TreeDropEvent<T = TreeNode> {
+    node: T;
+    /** The node it was dropped on. */
+    target: T;
+    zone: TreeDropZone;
+    /** The node it now hangs from — `null` at the top level. */
+    parent: T | null;
+    /** Its position among its new siblings. */
+    index: number;
+    via: 'pointer' | 'keyboard';
+}
+export interface TreeProps<T = TreeNode> {
+    /** Field holding the identity of a node. */
+    nodeKey?: string;
+    /** Field holding the text of a node. */
+    labelKey?: string;
+    /** Field holding the array of children. */
+    childrenKey?: string;
+    /** Field that, when true, makes a node unselectable and unmovable. */
+    disabledKey?: string;
+    /** Field that says a node has no children to fetch. Only read when `lazy`. */
+    leafKey?: string;
+    /** Expand every branch once, on the first render. */
+    defaultExpandAll?: boolean;
+    /** Opening a branch closes the others at its level. */
+    accordion?: boolean;
+    /** Clicking a label opens the branch as well as selecting it. */
+    expandOnClick?: boolean;
+    /** Adds a checkbox to every node. */
+    checkable?: boolean;
+    /**
+     * Checking a branch leaves its children alone. Off — the default — a branch follows
+     * its children and its children follow it, which is what a permission tree wants.
+     */
+    checkStrictly?: boolean;
+    /** Rows can be picked up and dropped before, after or inside another. */
+    draggable?: boolean;
+    /** Nodes this returns `false` for cannot be picked up. */
+    allowDrag?: (node: T) => boolean;
+    /** Vetoes a landing spot — say, to keep a page out of the root. */
+    allowDrop?: (drag: T, drop: T, zone: TreeDropZone) => boolean;
+    /** Children are fetched when a branch first opens. Requires `load`. */
+    lazy?: boolean;
+    /** Fetches the children of one node. */
+    load?: (node: T) => T[] | Promise<T[]>;
+    /**
+     * Shows only the nodes whose label contains this, together with the branches that
+     * lead to them — which are opened for as long as the term stands.
+     */
+    filter?: string;
+    /** Draws the guide lines that connect a child to its parent. */
+    showLines?: boolean;
+    /** How far one level sits from the next, in pixels. */
+    indent?: number;
+    size?: TreeSize;
+    /** Shown when there is nothing to draw. */
+    emptyText?: string;
+    /** What the drag handle is called, before the name of the node it holds. */
+    dragLabel?: string;
+    /** Accessible name for the tree. */
+    ariaLabel?: string;
+}
+export interface TreeEmits<T = TreeNode> {
+    /** A node was clicked — before anything was decided about selection. */
+    'node-click': [node: T, event: MouseEvent];
+    /** The selected node changed. */
+    select: [node: T | null, key: TreeKey | null];
+    /** A checkbox changed. The keys are every checked node, branches included. */
+    check: [keys: TreeKey[], detail: {
+        node: T;
+        checked: boolean;
+    }];
+    expand: [node: T];
+    collapse: [node: T];
+    /** A node was moved. The tree has already been rearranged. */
+    drop: [event: TreeDropEvent<T>];
+}

package/dist/components/TreeSelect/TreeSelect.d.ts

@@ -0,0 +1,47 @@
+import { TreeNode } from '../Tree/types';
+import { TreeSelectProps, TreeSelectValue } from './types';
+declare const _default: <T extends TreeNode>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_expose?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
+    props: __VLS_PrettifyLocal<Pick<Partial<{}> & Omit<{
+        readonly onChange?: ((value: TreeSelectValue, nodes: T[]) => any) | undefined;
+        readonly "onUpdate:modelValue"?: ((value: TreeSelectValue) => any) | undefined;
+        readonly onClose?: (() => any) | undefined;
+        readonly onOpen?: (() => any) | undefined;
+        readonly onClear?: (() => any) | undefined;
+    } & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps, never>, "onChange" | "onUpdate:modelValue" | "onOpen" | "onClose" | "onClear"> & ({
+        modelValue?: TreeSelectValue;
+    } & TreeSelectProps<T>) & Partial<{}>> & import('vue').PublicProps;
+    expose(exposed: import('vue').ShallowUnwrapRef<{}>): void;
+    attrs: any;
+    slots: Readonly<{
+        /** One node in the panel. */
+        node?: (props: {
+            node: T;
+            depth: number;
+            expanded: boolean;
+            selected: boolean;
+        }) => unknown;
+        /** What the field shows instead of the labels. */
+        value?: (props: {
+            nodes: T[];
+        }) => unknown;
+    }> & {
+        /** One node in the panel. */
+        node?: (props: {
+            node: T;
+            depth: number;
+            expanded: boolean;
+            selected: boolean;
+        }) => unknown;
+        /** What the field shows instead of the labels. */
+        value?: (props: {
+            nodes: T[];
+        }) => unknown;
+    };
+    emit: (((evt: "change", value: TreeSelectValue, nodes: T[]) => void) & ((evt: "close") => void) & ((evt: "open") => void) & ((evt: "clear") => void)) & ((evt: "update:modelValue", value: TreeSelectValue) => void);
+}>) => import('vue').VNode & {
+    __ctx?: Awaited<typeof __VLS_setup>;
+};
+export default _default;
+type __VLS_PrettifyLocal<T> = {
+    [K in keyof T]: T[K];
+} & {};

package/dist/components/TreeSelect/index.d.ts

@@ -0,0 +1,2 @@
+export { default as WxTreeSelect } from './TreeSelect';
+export type * from './types';

package/dist/components/TreeSelect/types.d.ts

@@ -0,0 +1,76 @@
+import { ControlSize, ControlStatus } from '../../composables/useFormField';
+import { TreeKey, TreeNode } from '../Tree/types';
+export type { TreeKey, TreeNode };
+/** One key, several of them with `multiple`, or nothing chosen. */
+export type TreeSelectValue = TreeKey | TreeKey[] | null;
+export interface TreeSelectProps<T = TreeNode> {
+    /** The tree to choose from — the same shape `WxTree` takes. */
+    nodes?: T[];
+    /** Adds checkboxes and turns the model into an array. */
+    multiple?: boolean;
+    /**
+     * With `multiple`, a tick stays where it was made instead of running down into the
+     * children and up into the parent. The model then holds exactly what was ticked,
+     * which is usually what a form wants to send.
+     */
+    checkStrictly?: boolean;
+    /** Field holding the identity of a node. */
+    nodeKey?: string;
+    /** Field holding the text of a node. */
+    labelKey?: string;
+    /** Field holding the array of children. */
+    childrenKey?: string;
+    /** Field that, when true, makes a node unchoosable. */
+    disabledKey?: string;
+    /** Field that says a node has no children to fetch. Only read when `lazy`. */
+    leafKey?: string;
+    /** Open every branch when the panel is first built. */
+    defaultExpandAll?: boolean;
+    /** Children are fetched when a branch first opens. Requires `load`. */
+    lazy?: boolean;
+    /** Fetches the children of one node. */
+    load?: (node: T) => T[] | Promise<T[]>;
+    /**
+     * The path to what is chosen — the ancestors and the node itself — for a tree that
+     * has not fetched it yet. A lazy field has no other way to name the value it holds,
+     * or to know which branches to open in order to show it. One path, or an array of
+     * them with `multiple`.
+     *
+     * A backend that knows the record knows its ancestors, so this is the same query the
+     * form already makes.
+     */
+    selectedPath?: T[] | T[][];
+    /** Adds the search field above the tree. */
+    filterable?: boolean;
+    filterPlaceholder?: string;
+    /**
+     * Shows the whole path in the field — `Engine / Pistons` — rather than the label
+     * alone. Worth it wherever the same name appears under two parents.
+     */
+    showPath?: boolean;
+    /** What goes between the steps of a path. */
+    separator?: string;
+    /** How tall the tree inside the panel may get before it scrolls. */
+    panelHeight?: number | string;
+    /** Shows a button that empties the selection. */
+    clearable?: boolean;
+    placeholder?: string;
+    /** Shown in the panel when there is nothing to choose from. */
+    emptyText?: string;
+    /** Render the panel in a portal so it escapes `overflow: hidden`. */
+    teleport?: boolean;
+    disabled?: boolean;
+    size?: ControlSize;
+    status?: ControlStatus;
+    id?: string;
+    name?: string;
+    /** Accessible label used when there is no visible `<label>`. */
+    ariaLabel?: string;
+}
+export interface TreeSelectEmits<T = TreeNode> {
+    /** The selection changed. The nodes come with it, since an id alone rarely is it. */
+    change: [value: TreeSelectValue, nodes: T[]];
+    clear: [];
+    open: [];
+    close: [];
+}

package/dist/components/index.d.ts

@@ -88,4 +88,7 @@ export * from './TimelineItem';
 export * from './TimePicker';
 export * from './Toaster';
 export * from './Tooltip';
+export * from './Transfer';
+export * from './Tree';
+export * from './TreeSelect';
 export * from './Upload';

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>>;