@boxcustodia/library 2.0.0-alpha.10 → 2.0.0-alpha.12

package/src/components/tree/tree.stories.tsx

@@ -0,0 +1,468 @@
+import { Meta, StoryObj } from "@storybook/react-vite";
+import { ComponentType } from "react";
+import { Collection } from "react-aria-components";
+import { createToastManager, ToastProvider } from "../toast";
+
+const toastManager = createToastManager();
+
+import { Tree, TreeNode } from ".";
+import {
+  TreeItem,
+  TreeItemContent,
+  TreeItemIndicator,
+  TreeItemLabel,
+  TreeRoot,
+} from "./tree-primitives";
+
+const files: TreeNode[] = [
+  {
+    id: "1",
+    title: "Work",
+    children: [
+      {
+        id: "1-1",
+        title: "Reports",
+        children: [
+          {
+            id: "1-1-1",
+            title: "2023",
+            children: [
+              {
+                id: "1-1-1-1",
+                title: "Q1 Report",
+                children: [
+                  { id: "1-1-1-1-1", title: "Summary", children: [] },
+                  { id: "1-1-1-1-2", title: "Details", children: [] },
+                ],
+              },
+            ],
+          },
+        ],
+      },
+      {
+        id: "1-2",
+        title: "Presentations",
+        children: [
+          {
+            id: "1-2-1",
+            title: "2023 Projects",
+            children: [
+              {
+                id: "1-2-1-1",
+                title: "Project A",
+                children: [
+                  { id: "1-2-1-1-1", title: "Draft", children: [] },
+                  { id: "1-2-1-1-2", title: "Final", children: [] },
+                ],
+              },
+              {
+                id: "1-2-1-2",
+                title: "Project B",
+                children: [
+                  { id: "1-2-1-2-1", title: "Research", children: [] },
+                ],
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  },
+  {
+    id: "2",
+    title: "Personal",
+    children: [
+      {
+        id: "2-1",
+        title: "Hobbies",
+        children: [
+          {
+            id: "2-1-1",
+            title: "Photography",
+            children: [
+              { id: "2-1-1-1", title: "Travel", children: [] },
+              { id: "2-1-1-2", title: "Portraits", children: [] },
+            ],
+          },
+          {
+            id: "2-1-2",
+            title: "Cooking",
+            children: [{ id: "2-1-2-1", title: "Recipes", children: [] }],
+          },
+        ],
+      },
+    ],
+  },
+  {
+    id: "3",
+    title: "Projects",
+    children: [
+      {
+        id: "3-1",
+        title: "Web Development",
+        children: [
+          {
+            id: "3-1-1",
+            title: "Portfolio",
+            children: [
+              { id: "3-1-1-1", title: "Images", children: [] },
+              { id: "3-1-1-2", title: "CSS", children: [] },
+            ],
+          },
+          { id: "3-1-2", title: "Landing Page", children: [] },
+        ],
+      },
+      {
+        id: "3-2",
+        title: "Mobile Apps",
+        children: [{ id: "3-2-1", title: "Weather App", children: [] }],
+      },
+    ],
+  },
+  {
+    id: "4",
+    title: "Finance",
+    children: [
+      {
+        id: "4-1",
+        title: "Budget",
+        children: [
+          {
+            id: "4-1-1",
+            title: "2023",
+            children: [
+              { id: "4-1-1-1", title: "January", children: [] },
+              { id: "4-1-1-2", title: "February", children: [] },
+            ],
+          },
+        ],
+      },
+    ],
+  },
+  {
+    id: "5",
+    title: "Health",
+    children: [
+      {
+        id: "5-1",
+        title: "Fitness",
+        children: [
+          { id: "5-1-1", title: "Workouts", children: [] },
+          { id: "5-1-2", title: "Nutrition", children: [] },
+        ],
+      },
+      { id: "5-2", title: "Wellness", children: [] },
+    ],
+  },
+];
+
+/**
+ * El componente Tree proporciona una vista jerárquica de datos en forma de árbol.
+ * Está construido sobre [@react-aria](https://react-spectrum.adobe.com/react-aria/Tree.html#tree)
+ * y soporta selección, expansión, navegación por teclado y más.
+ *
+ * ## Nodo
+ * Los nodos del árbol deben tener las siguientes propiedades:
+ *
+ * ```tsx
+ * interface TreeNode {
+ *   id: string | number;
+ *   title: string;
+ *   children: TreeNode[];
+ * }
+ * ```
+ */
+const meta: Meta<typeof Tree> = {
+  title: "Data display/Tree",
+  component: Tree,
+  subcomponents: {
+    TreeRoot: TreeRoot as ComponentType<unknown>,
+    TreeItem: TreeItem as ComponentType<unknown>,
+    TreeItemContent: TreeItemContent as ComponentType<unknown>,
+    TreeItemIndicator: TreeItemIndicator as ComponentType<unknown>,
+    TreeItemLabel: TreeItemLabel as ComponentType<unknown>,
+    Collection: Collection as ComponentType<unknown>,
+  },
+  args: {
+    items: files,
+    selectionMode: "single",
+  },
+  argTypes: {
+    selectedKeys: {
+      description: "Las claves actualmente seleccionadas en la colección",
+      control: "object",
+      table: {
+        type: { summary: "'all' | Iterable<Key>" },
+        defaultValue: { summary: "—" },
+      },
+    },
+    defaultSelectedKeys: {
+      description: "Las claves inicialmente seleccionadas en la colección",
+      control: "object",
+      table: {
+        type: { summary: "'all' | Iterable<Key>" },
+        defaultValue: { summary: "—" },
+      },
+    },
+    expandedKeys: {
+      description: "Las claves actualmente expandidas en la colección",
+      control: "object",
+      table: {
+        type: { summary: "Iterable<Key>" },
+        defaultValue: { summary: "—" },
+      },
+    },
+    defaultExpandedKeys: {
+      description: "Las claves inicialmente expandidas en la colección",
+      control: "object",
+      table: {
+        type: { summary: "Iterable<Key>" },
+        defaultValue: { summary: "—" },
+      },
+    },
+    selectionMode: {
+      description: "El tipo de selección que está permitida en el árbol",
+      control: "select",
+      options: ["none", "single", "multiple"],
+      table: {
+        type: { summary: "'none' | 'single' | 'multiple'" },
+        defaultValue: { summary: "'none'" },
+      },
+    },
+    disabledKeys: {
+      description: "Las claves de los elementos que están deshabilitados",
+      control: "object",
+      table: {
+        type: { summary: "Iterable<Key>" },
+        defaultValue: { summary: "—" },
+      },
+    },
+    disallowEmptySelection: {
+      description:
+        "Si se debe permitir que no haya ningún elemento seleccionado",
+      control: "boolean",
+      table: {
+        type: { summary: "boolean" },
+      },
+    },
+    onSelectionChange: {
+      description: "Manejador llamado cuando cambia la selección",
+      table: {
+        type: { summary: "(keys: 'all' | Iterable<Key>) => void" },
+        defaultValue: { summary: "—" },
+      },
+    },
+    onExpandedChange: {
+      description: "Manejador llamado cuando cambian los elementos expandidos",
+      table: {
+        type: { summary: "(keys: Iterable<Key>) => void" },
+        defaultValue: { summary: "—" },
+      },
+    },
+    onAction: {
+      description:
+        "Manejador llamado cuando un usuario realiza una acción en un elemento. El evento exacto depende del prop selectionBehavior y la modalidad de interacción",
+      table: {
+        type: { summary: "(key: Key) => void" },
+        defaultValue: { summary: "—" },
+      },
+    },
+    onScroll: {
+      description: "Manejador llamado cuando un usuario hace scroll",
+      table: {
+        type: { summary: "(e: UIEvent<Element>) => void" },
+        defaultValue: { summary: "—" },
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Tree>;
+
+/**
+ * Ejemplo básico del árbol con selección simple habilitada.
+ * Los usuarios pueden expandir/colapsar nodos y seleccionar un elemento a la vez.
+ */
+export const Default: Story = {};
+
+/**
+ * Configuración que permite seleccionar un solo elemento a la vez.
+ * Útil cuando necesitas que el usuario elija una única opción del árbol.
+ */
+export const SingleSelection: Story = {
+  args: {
+    selectionMode: "single",
+  },
+};
+
+/**
+ * Permite seleccionar múltiples elementos simultáneamente.
+ * Los usuarios pueden usar `click` para selección individual
+ * o `shift + click` para selección en rango.
+ */
+export const MultipleSelection: Story = {
+  args: {
+    selectionMode: "multiple",
+  },
+};
+
+/**
+ * Ejemplo de árbol con nodos deshabilitados completamente.
+ * Los elementos deshabilitados no pueden ser seleccionados ni expandidos.
+ *
+ * `disabledBehavior="all"` - Deshabilita todas las interacciones
+ *
+ * `disabledKeys` - Array de IDs de elementos a deshabilitar
+ */
+export const Disabled: Story = {
+  args: {
+    disabledBehavior: "all",
+    disabledKeys: ["1", "2", "3"],
+  },
+};
+
+/**
+ * Ejemplo donde solo la selección está deshabilitada.
+ * Los elementos pueden expandirse pero no pueden ser seleccionados.
+ *
+ * `disabledBehavior="selection"` - Solo deshabilita la selección
+ *
+ * `disabledKeys` - Array de IDs de elementos a deshabilitar
+ */
+export const DisabledSelection: Story = {
+  args: {
+    disabledBehavior: "selection",
+    disabledKeys: ["1", "2", "3"],
+  },
+};
+
+/**
+ * Árbol con nodos inicialmente expandidos.
+ * Útil para mostrar cierta estructura desde el inicio.
+ *
+ * `defaultExpandedKeys` - Array de IDs de elementos expandidos por defecto
+ */
+export const DefaultExpanded: Story = {
+  args: {
+    defaultExpandedKeys: ["1", "1-1", "1-1-1", "1-1-1-1"],
+  },
+};
+
+/**
+ * Ejemplo de árbol con expansión controlada.
+ * El estado de expansión es manejado externamente.
+ *
+ * `expandedKeys` - Control explícito de los elementos expandidos
+ */
+export const ControlledExpanded: Story = {
+  args: {
+    expandedKeys: ["1", "7"],
+  },
+};
+
+/**
+ * Árbol con selección inicial predeterminada.
+ *
+ * `defaultSelectedKeys` - Array de IDs de elementos seleccionados por defecto
+ */
+export const DefaultSelected: Story = {
+  args: {
+    selectionMode: "single",
+    defaultSelectedKeys: ["4"],
+  },
+};
+
+/**
+ * Demostración de los eventos disponibles en el árbol.
+ * Muestra notificaciones toast para:
+ * - Cambios en expansión
+ * - Cambios en selección
+ * - Eventos de scroll
+ */
+export const Events: Story = {
+  args: {
+    className: "h-96 overflow-y-auto border",
+    onExpandedChange: (keys: any) =>
+      toastManager.add({
+        variant: "success",
+        description: `Expanded: ${Array.from(keys)}`,
+      }),
+    onSelectionChange: (keys: any) =>
+      toastManager.add({
+        variant: "success",
+        description: `Selected: ${Array.from(keys)}`,
+      }),
+    onScroll: () =>
+      toastManager.add({ variant: "success", description: "Scroll" }),
+  },
+  decorators: [
+    (Story: any) => (
+      <ToastProvider toastManager={toastManager}>
+        <Story />
+      </ToastProvider>
+    ),
+  ],
+};
+
+/**
+ * ## Estructura con componentes primitivos
+ * ```tsx
+ * import { TreeRoot, TreeItem, Collection } from '../../components/tree'
+ *
+ * const Estructura = () => {
+ *   return (
+ *     <TreeRoot>
+ *       <TreeItem>
+ *         <TreeItemContent>
+ *           <TreeItemIndicator />
+ *           <TreeItemLabel>Item Label</TreeItemLabel>
+ *         </TreeItemContent>
+ *         <Collection>
+ *           Child items
+ *         </Collection>
+ *       </TreeItem>
+ *     </TreeRoot>
+ *   )
+ * }
+ * ```
+ *
+ * Los componentes primitivos del Tree son:
+ *
+ * - `TreeRoot`: Contenedor principal que maneja la selección y expansión
+ * - `TreeItem`: Representa cada elemento del árbol
+ * - `TreeItemContent`: Contenedor del contenido del item
+ * - `TreeItemIndicator`: Indicador de expansión (chevron)
+ * - `TreeItemLabel`: Etiqueta del item
+ * - `Collection`: Contenedor de items hijos que permite manejo con teclado
+ */
+
+export const Primitive: Story = {
+  render: () => {
+    const renderItem = (item: TreeNode) => {
+      return (
+        <TreeItem key={item.id} id={item.id} textValue={item.title}>
+          <TreeItemContent>
+            {item.children.length > 0 && <TreeItemIndicator />}
+            <TreeItemLabel>{item.title}</TreeItemLabel>
+          </TreeItemContent>
+          {item.children.length > 0 && (
+            <Collection>
+              {item.children.map((child: any) => renderItem(child))}
+            </Collection>
+          )}
+        </TreeItem>
+      );
+    };
+
+    return (
+      <TreeRoot
+        aria-label="Files"
+        selectionMode="multiple"
+        selectionBehavior="replace"
+      >
+        {files.map((item) => renderItem(item))}
+      </TreeRoot>
+    );
+  },
+};

package/src/components/tree/tree.tsx

@@ -0,0 +1,42 @@
+import * as React from "react";
+import {
+  Collection,
+  TreeItem,
+  TreeItemContent,
+  TreeItemIndicator,
+  TreeItemLabel,
+  TreeRoot,
+} from "./tree-primitives";
+
+export interface TreeNode {
+  id: string | number;
+  title: string;
+  children: TreeNode[];
+}
+
+type TreeRootProps = React.ComponentProps<typeof TreeRoot>;
+type Props<T extends TreeNode> = TreeRootProps & { items: T[] };
+
+export function Tree<T extends TreeNode>({ items, ...props }: Props<T>) {
+  const renderItem = (item: T): React.ReactNode => {
+    return (
+      <TreeItem key={item.id} id={item.id} textValue={item.title}>
+        <TreeItemContent>
+          {item.children?.length ? <TreeItemIndicator /> : null}
+          <TreeItemLabel>{item.title}</TreeItemLabel>
+        </TreeItemContent>
+        {item.children?.length ? (
+          <Collection items={item.children as Iterable<T>}>
+            {renderItem}
+          </Collection>
+        ) : null}
+      </TreeItem>
+    );
+  };
+
+  return (
+    <TreeRoot items={items} {...props}>
+      {items.map((item) => renderItem(item))}
+    </TreeRoot>
+  );
+}

package/src/hooks/index.ts

@@ -0,0 +1,26 @@
+export { useControllableState } from "@radix-ui/react-use-controllable-state";
+export * from "./useArray";
+export * from "./useAsync";
+export * from "./useClickOutside";
+export * from "./useClipboard";
+export * from "./useDebounceCallback";
+export * from "./useDebounceValue";
+export * from "./useDisclosure";
+export * from "./useDocumentTitle";
+export * from "./useEventListener";
+export * from "./useFocusTrap";
+export * from "./useHotkey";
+export * from "./useHover";
+export * from "./useIsVisible";
+export * from "./useLocalStorage";
+export * from "./useMediaQuery";
+export * from "./useMemoizedFn";
+export * from "./useMutation";
+export * from "./useObject";
+export * from "./usePagination";
+export * from "./usePortal";
+export * from "./usePreventCloseWindow";
+export * from "./useRangePagination";
+export * from "./useSelection";
+export * from "./useStep";
+export * from "./useToggle";

package/src/hooks/useArray/__doc__/useArray.stories.tsx

@@ -0,0 +1,100 @@
+import { Meta, StoryObj } from "@storybook/react-vite";
+import { Trash } from "lucide-react";
+import { Button } from "../../../components";
+import useArray from "../useArray";
+
+/**
+ * Hook que facilita el manejo de estado de una lista
+ * Se exponen los siguientes métodos:
+ *
+ * | Método | Descripción |
+ * | --- | --- |
+ * | `insertAt(index: number, item: T)` | Inserta un elemento en un índice específico en la lista. |
+ * | `removeAt(index: number)` | Elimina un elemento en un índice específico de la lista. |
+ * | `updateAt(index: number, newItem: T)` | Actualiza un elemento en un índice específico de la lista. |
+ * | `clear()` | Elimina todos los elementos de la lista. |
+ * | `reset()` | Restablece la lista a su valor por defecto o inicial. |
+ * | `push(item: T)` | Agrega un nuevo elemento al final de la lista. |
+ * | `pop()` | Elimina el último elemento de la lista. |
+ * | `set(newList: T[])` | Actualiza la lista con una nueva lista. |
+ * | `update(predicate: ListIterateeCustom<T, boolean>, newItem: T | (item: T) => T)` | Actualiza un elemento de la lista.
+ */
+const meta: Meta = {
+  title: "hooks/useArray",
+};
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => {
+    const [list, { insertAt, removeAt, clear, reset, pop, update }] =
+      useArray<string>(["First", "Second", "Third"]);
+
+    return (
+      <div className="space-y-2">
+        <div className="flex gap-2 flex-wrap">
+          <Button disabled={list.length < 1} onClick={() => insertAt(1, "woo")}>
+            Insertar despúes del primero
+          </Button>
+          <Button disabled={list.length < 2} onClick={() => removeAt(1)}>
+            Eliminar segundo item
+          </Button>
+          <Button disabled={list.length < 2} onClick={() => pop()}>
+            Eliminar el último item
+          </Button>
+          <Button
+            onClick={() => update((item: string) => item === "First", "🐙")}
+          >
+            Actualizar primer elemento por 🐙
+          </Button>
+          <Button onClick={reset}>Resetear</Button>
+          <Button onClick={clear}>Limpiar</Button>
+        </div>
+
+        <pre className="rounded-md bg-slate-950 p-4 text-white">
+          <code className="block">
+            List:{" "}
+            <span className="text-blue-300">
+              {JSON.stringify(list, null, 2)}
+            </span>
+          </code>
+        </pre>
+      </div>
+    );
+  },
+};
+
+export const DynamicList: Story = {
+  render: () => {
+    const [list, updateList] = useArray<string>([]);
+
+    const addItem = () => updateList.push(`Item ${list.length + 1}`);
+
+    return (
+      <div className="space-y-2">
+        <div className="flex items-center gap-2">
+          <Button onClick={addItem}>Add Item</Button>
+          <Button onClick={updateList.clear}>
+            <Trash /> Clear
+          </Button>
+        </div>
+        <ul>
+          {list.map((item, index) => (
+            <li key={index}>
+              {item}{" "}
+              <Button
+                size="icon"
+                variant="ghost"
+                onClick={() => updateList.removeAt(index)}
+              >
+                <Trash />
+              </Button>
+            </li>
+          ))}
+        </ul>
+      </div>
+    );
+  },
+};