@apia/tree 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [year] [fullname]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,28 @@
+# Initiator
+
+Este package se creó con la única utilidad de copiarlo entero y pegarlo a la hora de crear un nuevo package.
+
+Este iniciador permite crear un paquete que compila typescript y puede ser importado desde otros packages.
+
+## IMPORTANTE
+
+Los archivos **tsconfig.json** y **tsup.config.ts** no son archivos únicos sino symlinks a archivos de configuración comunes a todos los packages. En caso de que sea necesario modificar alguno de ellos **que en la gran mayoría de los casos no sería necesario**, es necesario eliminar el archivo a modificar y crear uno nuevo.
+
+## Procedimiento
+
+ - Copiar la carpeta initiator y pegarla con otro nombre dentro de packages.
+ - Modificar el package.json:
+   - Eliminar la línea ```private: true```.
+   - Cambiar la ocurrencia `initiator` por el nombre del nuevo paquete. 
+   - Agregar los scripts convenientes: dev, build, etc.
+ - Ejecutar el comando lerna bootstrap desde la carpeta raíz.
+
+Luego de ejecutar estos pasos, el package estaría listo para comenzar a usarse.
+
+Este package trae como dependencias por defecto theme-ui y react. Si se desea agregar más dependencias se debe ejecutar el comando ```lerna add --scope="@apia/packageName" dependencyName```. Ejemplo, si creamos un paquete con el nombre @apia/myPackage y queremos agregar lodash como dependencia, ejecutamos el comando ```lerna add --scope="@apia/myPackage" lodash```. 
+
+**Importante 1**: Dado que estamos desarrollando packages, es importante determinar si las dependencias que vamos a agregar son de tipo dependency o de tipo peerDependency.
+
+**Importante 2**: lerna no permite instalar de a varias dependencias a la vez como lo hace npm, por lo tanto, si se desea agregar varias dependencias se debe ejecutar el comando anterior tantas veces como dependencias se quiera agregar.
+
+**Importante 3**: React y theme-ui vienen instalados como peerDependencies. En caso de no ser necesarios pueden ser removidos, pero en cualquier caso asegurarse de que estas dependencias no sean instaladas como dependencies puesto que esto causaría comportamientos indeseados en la aplicación.

package/cleanDist.json

@@ -0,0 +1,3 @@
+{
+  "cleanDist": 0.2318938201855587
+}

package/dist/index.d.ts

@@ -0,0 +1,334 @@
+import * as theme_ui_jsx_runtime from 'theme-ui/jsx-runtime';
+import React, { RefObject } from 'react';
+import { EventEmitter, PropsStore, TModify, TRequireOnlyOne, TUpdateFieldConfiguration, TPropsConfiguration } 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;
+}> {
+    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;
+    /**
+     * 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.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;
+    /**
+     * Borra todos los nodos del árbol.
+     */
+    removeAll(): void;
+    selectAll(): void;
+    setFocusedNode(key: TId, avoidSelection?: boolean): void;
+    setSelectedNodes(nodes: TId[], force?: boolean): void;
+    setSelectedNodesByClickEvent(ev: React.MouseEvent): void;
+    setState(updateProps: Partial<TTreeDataControllerState>, conf?: TUpdateFieldConfiguration): void;
+    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.FunctionComponent<TDataNode<NodeProps> & {
+    level: number;
+}>;
+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;
+    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.KeyboardEvent | React.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).
+     */
+    selectionMode: 'onFocus' | 'explicit';
+    /**
+     * 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.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>) => theme_ui_jsx_runtime.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: TId[];
+        forceUpdate: number;
+    };
+    handler: TreeDataController<NodeProps, NodeType>;
+    keyHandler: {
+        id: string;
+        onKeyDown: (ev: React.KeyboardEvent) => void;
+        onMouseDown: (ev: React.MouseEvent) => void;
+        onClick: (ev: React.MouseEvent) => void;
+        ref: React.MutableRefObject<HTMLDivElement | null>;
+    };
+};
+
+export { TDataNode, TTreeLabelRenderer, TTreeProps, _default as Tree, TreeDataController, useTreeContext, useTreeData, useTreeDataController, useTreeSelector, useTreeSelectorByName };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sources":[],"sourcesContent":[],"names":[],"mappings":""}