@apia/tree 3.0.1 → 3.0.6

package/dist/index.d.ts

@@ -1,8 +1,416 @@
-export { default as Tree } from './Tree.js';
-export { useTreeContext } from './TreeContext.js';
-export { default as TreeDataController, useTreeDataController, useTreeSelector, useTreeSelectorByName } from './TreeDataController.js';
-export { default as useTreeData } from './useTreeData.js';
-export { TDataNode, TTreeLabelRenderer, TTreeProps } from './types.js';
-export { OOTree } from './OOTree/index.js';
-export { OOTreeNode, isOOTreeNode } from './OOTree/OOTreeNode.js';
+import * as React from 'react';
+import React__default, { RefObject } from 'react';
+import { EventEmitter, PropsStore, TModify, TRequireOnlyOne, TUpdateFieldConfiguration, TPropsConfiguration, TId as TId$1 } from '@apia/util';
+import { TIconName } from '@apia/icons';
+
+declare function useTreeDataController<TreeType extends TreeDataController<any, any> = TreeDataController<any, any>>(name: string): TreeType;
+declare class TreeDataController<NodeProps extends Record<string, unknown> = Record<string, unknown>, NodeType extends TDataNode<NodeProps> = TDataNode<NodeProps>> extends EventEmitter<{
+    onArrowUpOnFirstElement: boolean;
+    expandNode: NodeType;
+    mustFocus: TId;
+    stateUpdate: null;
+}> {
+    name: string;
+    propsStore: PropsStore<NodeType>;
+    _configuration: RefObject<TTreeDataControllerConfig<NodeProps, NodeType>>;
+    get configuration(): {
+        current: TTreeDataControllerConfig<NodeProps, NodeType> | null;
+    };
+    hasApendedFirstChild: boolean;
+    /**
+     * Este array se usa para conocer los padres faltantes al momento de la
+     * construcción del árbol, de forma de optimizar el proceso
+     */
+    missingParents: TId[];
+    nonEmittedUpdates: TId[];
+    get state(): TTreeDataControllerState;
+    stateKey: string;
+    get stateStore(): PropsStore<TTreeDataControllerState>;
+    constructor(name: string, configuration: RefObject<Partial<TTreeDataControllerConfig<NodeProps, NodeType>>>, propsStore?: PropsStore<NodeType>);
+    destructor(): void;
+    append(node: Omit<TModify<NodeType, {
+        children?: NodeType['children'];
+        parentId?: NodeType['parentId'];
+    }>, 'nodeProps' | 'actualParentId'> & Partial<Pick<NodeType, 'nodeProps'>>): void;
+    /**
+     * Cuando se quieren agregar muchos nodos, es conveniente llamar primero al
+     * método batchInit y luego de finalizar, al método batchFinish()
+     */
+    batchInit(): void;
+    private getNodesRecursive;
+    /**
+     * Cuando se quieren agregar muchos nodos, es conveniente llamar primero al
+     * método batchInit y luego de finalizar, al método batchFinish()
+     */
+    batchFinish(): void;
+    config(newConf: Partial<TTreeDataControllerConfig<NodeProps, NodeType>>): void;
+    deselectAll(): void;
+    forceEmitUpdate(): void;
+    getInitialState(): TTreeDataControllerState;
+    getNodesAsArray(): NodeType[];
+    /**
+     * Devuelve un array que contiene el id de todos los nodos pertenecientes al
+     * árbol
+     */
+    getNodesIds(): string[];
+    getParentId(parentId: TId): TId;
+    /**
+     * Este método permite controlar el comportamiento con el teclado desde fuera
+     * del componente.
+     */
+    handleKey(ev: React__default.KeyboardEvent): void;
+    isNode(node: NodeType | TDataNodeContainer<NodeProps> | TId): node is NodeType;
+    isNodeContainer(node: NodeType | TDataNodeContainer<NodeProps> | TId): node is TDataNodeContainer<NodeProps>;
+    includes(searchNode: NodeType): boolean;
+    initRoot(): void;
+    move(moveNode: TId, destinationNode: TId, afterOrBefore?: TRequireOnlyOne<{
+        after: NodeType | TId;
+        before: NodeType | TId;
+        position: number;
+    }>): void;
+    /**
+     * Borra el nodo del árbol, y dependiendo del parámetro removeChildren, borra
+     * también sus hijos.
+     *
+     * @param removeChildren - Si se pasa en false, los nodos hijos son movidos al root
+     */
+    remove(removeNode: NodeType | TId, removeChildren?: boolean): void;
+    removeMultiple(nodes: TId[], removeChildren?: boolean): void;
+    previousNodes: TId[];
+    /**
+     * Borra todos los nodos del árbol.
+     */
+    removeAll(): void;
+    selectAll(): void;
+    setExpandedNodes(nodes: TId[]): void;
+    setFocusedNode(key: TId, avoidSelection?: boolean): void;
+    setSelectedNodes(nodes: TId[], force?: boolean): void;
+    setSelectedNodesByClickEvent(ev: React__default.MouseEvent): void;
+    setState: (updateProps: Partial<TTreeDataControllerState>, conf?: TUpdateFieldConfiguration) => void;
+    useState: <T>(selector: (state: TTreeDataControllerState) => T) => T;
+    toggleNodeExpandedState(key: TId, shouldExpand?: boolean): void;
+    toggleNodeSelectedState(key: TId, isSelected?: boolean): void;
+}
+/**
+ * Este hook permite escuchar las props de un árbol, para ello es necesario
+ * pasar el handler.
+ *
+ * @param handler
+ * @param configuration
+ * @returns
+ */
+declare function useTreeSelector<NodeProps extends Record<string, unknown> = Record<string, unknown>, NodeType extends TDataNode<NodeProps> = TDataNode<NodeProps>, Selected = Record<string, unknown>, PropsType extends Record<string, unknown> = TTreeDataControllerState>(handler: TreeDataController<NodeProps, NodeType>, configuration?: TPropsConfiguration<Selected, PropsType>): Selected;
+/**
+ * Este hook permite escuchar las props de un árbol, para ello es necesario
+ * pasar el handler.
+ *
+ * @param handler
+ * @param configuration
+ * @returns
+ */
+declare function useTreeSelectorByName<NodeProps extends Record<string, unknown> = Record<string, unknown>, NodeType extends TDataNode<NodeProps> = TDataNode<NodeProps>, Selected = Record<string, unknown>, PropsType extends Record<string, unknown> = TTreeDataControllerState>(treeName: string, configuration?: TPropsConfiguration<Selected, PropsType>): {
+    handler: TreeDataController<NodeProps, NodeType>;
+    selection: Selected;
+};
+
+type TId = string | number;
+type TDataNodeContainer<NodeProps extends Record<string, unknown> = Record<string, unknown>> = Pick<TDataNode<NodeProps>, 'children' | 'id'>;
+type TTreeDataControllerConfig<NodeProps extends Record<string, unknown> = Record<string, unknown>, NodeType extends TDataNode<NodeProps> = TDataNode<NodeProps>> = {
+    emitUpdates?: boolean;
+} & Pick<TTreeProps<NodeProps, NodeType>, 'isMultiple' | 'onLoadData' | 'onExpand' | 'disableSelection' | 'selectionMode'>;
+type TTreeDataControllerState = {
+    expandedNodes: TId[];
+    filteredNodes: TId[];
+    focusedNode: TId | null;
+    isLoading: boolean;
+    length: number;
+    selectedNodes: TId[];
+};
+type TTreeLabelRenderer<NodeProps extends Record<string, unknown> = Record<string, unknown>> = React__default.FunctionComponent<TDataNode<NodeProps>>;
+type TNodesExpandEvent<NodeProps extends Record<string, unknown> = Record<string, unknown>> = TDataNode<NodeProps>;
+type TNodesSelectionEvent<NodeProps extends Record<string, unknown> = Record<string, unknown>> = TDataNode<NodeProps>[];
+type TTreeProps<NodeProps extends Record<string, unknown> = Record<string, unknown>, NodeType extends TDataNode<NodeProps> = TDataNode<NodeProps>> = {
+    /**
+     * Debe ser un texto descriptivo, se usa para las personas no videntes
+     * principalmente.
+     */
+    label: string;
+    name: string;
+} & Partial<{
+    className: string;
+    /**
+     * Permite pasar un controller propio.
+     */
+    controller?: TreeDataController<NodeProps, NodeType>;
+    disableSelection: boolean;
+    /**
+     * Si se pasa un filterString !== undefined => los nodos del árbol cuyo label
+     * no coincida serán ocultados, a menos que alguno de sus hijos si coincida.
+     */
+    filterString: string;
+    /**
+     * Es posible alterar el comportamiento por defecto cada vez que el usuario
+     * selecciona un elemento de la lista mediante esta función, indicando al tree
+     * sobre qué elemento debe colocar el foco.
+     *
+     * Esta función debe tomar el liElement que recibe como parámetro y mediante
+     * querySelectors o el método que se considere correcto devolver la referencia
+     * al hijo sobre el cual se desea colocar el foco.
+     *
+     * @param liElement - Es el li que renderiza el nodo. Los hijos más importantes de este li son:
+     *
+     *  - .tree__nodeItemLabel: Es el wrapper del botón de expandir, del ícono
+     *  del nodo y del (custom?)Renderer. - ul[role="group"]: Es el wrapper de
+     *  todos los hijos del nodo actual.*/
+    focusGetter: (liElement: HTMLElement) => HTMLElement;
+    /**
+     * Esta función es llamada cuando el árbol inicializó con la referencia al
+     * handler como parámetro.
+     */
+    getHandler: (handler: TreeDataController<NodeProps, NodeType>) => unknown;
+    /**
+     * Permite ocultar todos los nodos de tipo folder que no tengan hijos.
+     */
+    hideEmptyFolders: boolean;
+    /**
+     * Permite ocultar la etiqueta de búsqueda
+     */
+    hideSearchLabel: boolean;
+    initialNodes: NodeType[];
+    /**
+     * Pone el mismo spinner que mientras está en modo batch.
+     */
+    isLoading: boolean;
+    /**
+     * Habilita la selección múltiple, por defecto está deshabilitada.
+     */
+    isMultiple: boolean;
+    /**
+     * Este callback es llamado cuando se presiona la flecha arriba en el primer
+     * elemento del árbol. Está pensado para mover el foco hacia el cuadro de
+     * búsqueda.
+     */
+    onArrowUpOnFirstElement?: () => unknown;
+    onDeleteFilterString?: () => unknown;
+    onExpand: (ev: TNodesExpandEvent<NodeProps>) => unknown;
+    /**
+     * Esta función debe devolver una promesa. Cuando se expande un nodo que no
+     * tiene hijos, esta función es llamada y el nodo es puesto en estado de carga
+     * hasta que la promesa se resuelve.
+     */
+    onLoadData: (node: NodeType) => Promise<void>;
+    /**
+     * Cada vez que se hace click sobre un nodo o se presiona enter estando
+     * éste en foco, se llama este callback informando de la acción.
+     */
+    onNodeClick: (ev: React__default.KeyboardEvent | React__default.MouseEvent, node: NodeType) => unknown;
+    onSelect: (ev: TNodesSelectionEvent<NodeProps>) => unknown;
+    /**
+     * Si se pasa **onFocus**, el nodo será seleccionado al recibir foco (por
+     * ejemplo, al navegarlo con las flechas).
+     *
+     * Si se pasa **explicit**, solamente se
+     * hará seleccionará al hacerle click (o presionar enter o espacio).
+     *
+     * Si se pasa **explicitMultiple**, solamente se hará selección al hacer
+     * click o presionar enter o espacio, y además la selección múltiple solamente
+     * funcionará si las teclas Shift o Ctrl están presionadas.
+     *
+     * @default "onFocus"
+     */
+    selectionMode: 'onFocus' | 'explicit' | 'explicitMultiple';
+    /**
+     * Si se pasa en false, los nodos padre solamente se podrán expandir/colapsar
+     * al hacer click en los íconos.
+     */
+    toggleNodesOnLabelClick: boolean;
+    variant: string;
+}>;
+type TTreeIconRenderer<NodeProps extends Record<string, unknown> = Record<string, unknown>> = React__default.FunctionComponent<TDataNode<NodeProps>>;
+type TDataNode<NodeProps extends Record<string, unknown> = Record<string, unknown>> = {
+    actualParentId?: TId;
+    children: TId[];
+    id: TId;
+    label: string;
+    /**
+     * Un objeto arbitrario con propiedades de nodo que no están relacionados a
+     * la estructura del árbol, sino de la estructura de información que
+     * representa.
+     */
+    nodeProps: NodeProps;
+    parentId: TId;
+} & Partial<{
+    /**
+     * Con esta prop se puede evitar que el nodo sea colapsado desde el label
+     */
+    allowToggleExpandedFromLabel?: boolean;
+    className?: string;
+    color?: string;
+    /**
+     * Esta prop marca que ya se pidieron los datos mediante onLoadData para este
+     * nodo.
+     */
+    hasLoaded: boolean;
+    /**
+     * El icon puede ser el nombre de uno de los elementos del mapa de íconos de
+     * Icon.tsx o un TTreeIconRenderer que permite utilizar un componente para
+     * renderizar el ícono.*/
+    icon: TIconName | TTreeIconRenderer<NodeProps>;
+    /**
+     * Este string se usa como height y width del ícono, de modo que se puede
+     * pasar cualquier expresión válida de ThemeUI.
+     */
+    iconSize: string;
+    /**
+     * Cuando un nodo está deshabilitado, no se pondrá foco en él.
+     */
+    isDisabled: boolean;
+    /**
+     * Indica si un nodo está o no expandido, en caso de que se establezca en
+     * true, el mismo será expandido. Esto puede ser útil para controlar el árbol
+     * desde fuera, en cuyo caso se deben modificar las propiedades mediante
+     * handler.propsStore.updateField(node.id, { newProps }).
+     */
+    isExpanded: boolean;
+    /**
+     * Indica que el nodo no debe mostrarse ya que no coincide con los criterios
+     * de filtrado.
+     */
+    isFiltered: boolean;
+    /**
+     * Indica si un nodo está en foco, es importante notar que alterar esta
+     * propiedad no va a alterar qué nodo del árbol está en foco ya que ese
+     * control lo hace internamente el árbol. En caso de querer modificar esto en
+     * forma externa, se deben usar los métodos correspondientes del handler.
+     */
+    isFocused: boolean;
+    /**
+     * Esta prop se usa para decir que un nodo es un sub-árbol, aún cuando no
+     * tiene hijos. Esto es especialmente útil cuando se quiere hacer carga
+     * asíncrona de datos, ya que al expandirse, se llamará al método onLoadData
+     * del tree.
+     */
+    isLeaf: boolean;
+    /**
+     * Se setea en true al momento de llamar a onLoadData y en false al finalizar
+     * la carga de datos.
+     */
+    isLoading: boolean;
+    /**
+     * Por defecto todos los nodos son seleccionables, se debe pasar false
+     * explícitamente para deshabilitar la selección.
+     */
+    isSelectable: boolean;
+    /**
+     * Indica si un nodo está o no seleccionado. Esto puede ser útil para
+     * controlar el árbol desde fuera, en cuyo caso se deben modificar las
+     * propiedades mediante handler.propsStore.updateField(node.id, { newProps }).
+     */
+    isSelected: boolean;
+    /**
+     * Si se pasa un labelRenderer se utilizará en lugar de
+     * DefaultLabelRenderer.tsx. El labelRenderer es el responsable de hacer caso
+     * de los eventos de click para la selección del nodo.
+     */
+    labelRenderer: TTreeLabelRenderer<NodeProps>;
+    title: string;
+}>;
+
+declare const _default: <NodeProps extends Record<string, unknown> = Record<string, unknown>, NodeType extends TDataNode<NodeProps> = TDataNode<NodeProps>>(props: TTreeProps<NodeProps, NodeType>) => React__default.JSX.Element;
+
+type TTreeContext<NodeProps extends Record<string, unknown> = Record<string, unknown>, NodeType extends TDataNode<NodeProps> = TDataNode<NodeProps>> = {
+    forceUpdate: number;
+    name: string;
+    handler: TreeDataController<NodeProps, NodeType>;
+    treeProps: TTreeProps<NodeProps, NodeType>;
+} & Pick<TTreeProps, 'focusGetter'>;
+declare function useTreeContext<NodeProps extends Record<string, unknown> = Record<string, unknown>, NodeType extends TDataNode<NodeProps> = TDataNode<NodeProps>>(): TTreeContext<NodeProps, NodeType>;
+
+interface IUseTreeData<NodeProps extends Record<string, unknown> = Record<string, unknown>, NodeType extends TDataNode<NodeProps> = TDataNode<NodeProps>> {
+    name: string;
+    treeProps: TTreeProps<NodeProps, NodeType>;
+}
+declare function useTreeData<NodeProps extends Record<string, unknown> = Record<string, unknown>, NodeType extends TDataNode<NodeProps> = TDataNode<NodeProps>>({ name, treeProps }: IUseTreeData<NodeProps, NodeType>): {
+    data: {
+        children: number[];
+        forceUpdate: number;
+    };
+    handler: TreeDataController<NodeProps, NodeType>;
+    keyHandler: {
+        id: string;
+        onKeyDown: (ev: React__default.KeyboardEvent) => void;
+        onMouseDown: (ev: React__default.MouseEvent) => void;
+        onClick: (ev: React__default.MouseEvent) => void;
+        ref: React__default.MutableRefObject<HTMLDivElement | null>;
+    };
+};
+
+type PrefixMapEntry = {
+    nodeId: TId;
+    prefix: string;
+};
+type TOOTreeNodeProps<NodeProps extends Record<string, unknown> = Record<string, unknown>> = Omit<TDataNode<NodeProps>, 'actualParentId' | 'parentId' | 'children' | 'hasLoaded'>;
+type TSortOOTreeChildren<NodeProps extends Record<string, unknown> = Record<string, unknown>> = (a: TDataNode<NodeProps>, b: TDataNode<NodeProps>) => number;
+
+declare function isOOTreeNode<NodeProps extends Record<string, unknown> = Record<string, unknown>>(element: OOTreeNode<NodeProps> | TDataNode<NodeProps>): element is OOTreeNode<NodeProps>;
+declare class OOTreeNode<NodeProps extends Record<string, unknown> = Record<string, unknown>> {
+    #private;
+    protected tree: OOTree<NodeProps>;
+    protected parent: OOTreeNode<NodeProps> | TDataNode<NodeProps> | null;
+    protected props: TOOTreeNodeProps<NodeProps>;
+    id: string;
+    prefix: string;
+    constructor(tree: OOTree<NodeProps>, parent: OOTreeNode<NodeProps> | TDataNode<NodeProps> | null, props: TOOTreeNodeProps<NodeProps>);
+    attachToTree(): void;
+    append(props: TOOTreeNodeProps<NodeProps>): OOTreeNode<NodeProps>;
+    collapse(): void;
+    expand(): void;
+    focus(expand?: boolean): void;
+    getAll(): (() => OOTreeNode<NodeProps> | undefined)[];
+    getById(id: TId): OOTreeNode<NodeProps> | undefined;
+    getOriginalId(): string;
+    getParent(): OOTreeNode<NodeProps> | null;
+    getProps(): TDataNode<NodeProps>;
+    remove(): void;
+    sort(sortFunction: TSortOOTreeChildren<NodeProps>): void;
+    update(props: Partial<Omit<TOOTreeNodeProps<NodeProps>, 'id'>>): void;
+}
+
+declare class OOTreeChildren<NodeProps extends Record<string, unknown> = Record<string, unknown>> extends OOTreeNode<NodeProps> {
+    protected tree: OOTree<NodeProps, any>;
+    constructor(tree: OOTree<NodeProps, any>);
+    /**
+     * Se sobreescribe para evitar problemas
+     */
+    expand(): void;
+}
+
+declare class OOTree<NodeProps extends Record<string, unknown> = Record<string, unknown>, Events extends Record<string, unknown> = Record<string, unknown>> extends EventEmitter<Events> {
+    #private;
+    props: TTreeProps<NodeProps>;
+    constructor(props: TTreeProps<NodeProps>);
+    getChildren: () => OOTreeChildren<NodeProps>;
+    getController: () => TreeDataController<NodeProps, TDataNode<NodeProps>>;
+    Component: (props: Partial<TTreeProps<NodeProps>>) => React.JSX.Element;
+    /**
+     * Data manipulation
+     */
+    private prefixJoinCharacter;
+    private prefixWithIdJoinCharacter;
+    protected prefixesMap: Record<string, PrefixMapEntry>;
+    calculateDepth: (id: TId$1) => number;
+    /**
+     * Calcula el prefijo de un nodo que se está agregando al árbol evitando
+     * colisiones. Ese prefijo estará asociado a cada nodo y se utilizará para dar
+     * nombres únicos a sus hijos, no para el nodo en sí. Entonces, cada vez que
+     * se construye un nodo, se le asigna un prefijo considerando el prefijo de su
+     * padre, pero su nombre se hace a partir del prefijo del padre y su id.
+     */
+    calculateNodePrefix: (id: TId$1, prefix?: string) => {
+        prefix: string;
+        id: string;
+    };
+}
+
+export { OOTree, OOTreeNode, type TDataNode, type TNodesSelectionEvent, type TTreeLabelRenderer, type TTreeProps, _default as Tree, TreeDataController, isOOTreeNode, useTreeContext, useTreeData, useTreeDataController, useTreeSelector, useTreeSelectorByName };
 //# sourceMappingURL=index.d.ts.map