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

package/src/components/tree/tree.test.tsx

@@ -0,0 +1,163 @@
+import {
+  hotkeysCoreFeature,
+  selectionFeature,
+  syncDataLoaderFeature,
+} from "@headless-tree/core";
+import { useTree } from "@headless-tree/react";
+import { render, screen } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { describe, expect, it } from "vitest";
+
+import { TreeItem, TreeItemLabel, TreeRoot } from "./tree";
+
+interface Item {
+  name: string;
+  children?: string[];
+}
+
+const items: Record<string, Item> = {
+  root: { name: "Root", children: ["folder", "leaf"] },
+  folder: { name: "Folder", children: ["nested"] },
+  nested: { name: "Nested" },
+  leaf: { name: "Leaf" },
+};
+
+interface HarnessProps {
+  initialExpanded?: string[];
+  leafIcon?: ReactNode;
+  parentIcon?: ReactNode | ((isExpanded: boolean) => ReactNode);
+  withChildren?: boolean;
+}
+
+function Harness({
+  initialExpanded = [],
+  leafIcon,
+  parentIcon,
+  withChildren = false,
+}: HarnessProps) {
+  const tree = useTree<Item>({
+    rootItemId: "root",
+    getItemName: (item) => item.getItemData().name,
+    isItemFolder: (item) => (item.getItemData().children?.length ?? 0) > 0,
+    dataLoader: {
+      getItem: (itemId) => items[itemId],
+      getChildren: (itemId) => items[itemId]?.children ?? [],
+    },
+    initialState: { expandedItems: initialExpanded },
+    features: [syncDataLoaderFeature, selectionFeature, hotkeysCoreFeature],
+  });
+
+  return (
+    <TreeRoot tree={tree}>
+      {tree.getItems().map((item) =>
+        withChildren ? (
+          <TreeItem
+            key={item.getId()}
+            item={item}
+            data-testid={`item-${item.getId()}`}
+            leafIcon={leafIcon}
+            parentIcon={parentIcon}
+          >
+            <TreeItemLabel>Custom: {item.getItemName()}</TreeItemLabel>
+          </TreeItem>
+        ) : (
+          <TreeItem
+            key={item.getId()}
+            item={item}
+            data-testid={`item-${item.getId()}`}
+            leafIcon={leafIcon}
+            parentIcon={parentIcon}
+          />
+        ),
+      )}
+    </TreeRoot>
+  );
+}
+
+describe("Tree component", () => {
+  it("renders the item name by default", () => {
+    render(<Harness />);
+    expect(screen.getByText("Folder")).toBeInTheDocument();
+    expect(screen.getByText("Leaf")).toBeInTheDocument();
+  });
+
+  it("renders a default chevron parentIcon on folders only", () => {
+    render(<Harness />);
+    expect(
+      screen.getByTestId("item-folder").querySelector("svg"),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByTestId("item-leaf").querySelector("svg"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("opts out of the default chevron when parentIcon is null", () => {
+    render(<Harness parentIcon={null} />);
+    expect(
+      screen.getByTestId("item-folder").querySelector("svg"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("renders leafIcon only on non-folder items", () => {
+    render(
+      <Harness
+        leafIcon={<span data-testid="leaf-icon">L</span>}
+        parentIcon={<span data-testid="parent-icon">P</span>}
+      />,
+    );
+
+    const leafIcons = screen.getAllByTestId("leaf-icon");
+    const parentIcons = screen.getAllByTestId("parent-icon");
+
+    expect(leafIcons).toHaveLength(1);
+    expect(parentIcons).toHaveLength(1);
+    expect(screen.getByTestId("item-leaf")).toContainElement(leafIcons[0]!);
+    expect(screen.getByTestId("item-folder")).toContainElement(parentIcons[0]!);
+  });
+
+  it("calls the parentIcon function with the expanded state", () => {
+    render(
+      <Harness
+        initialExpanded={["folder"]}
+        parentIcon={(isExpanded) => (
+          <span data-testid="parent-icon">
+            {isExpanded ? "open" : "closed"}
+          </span>
+        )}
+      />,
+    );
+
+    expect(screen.getByTestId("item-folder")).toHaveTextContent("open");
+  });
+
+  it("ignores leafIcon / parentIcon when children are provided", () => {
+    render(
+      <Harness
+        withChildren
+        leafIcon={<span data-testid="leaf-icon">L</span>}
+        parentIcon={<span data-testid="parent-icon">P</span>}
+      />,
+    );
+
+    expect(screen.queryByTestId("leaf-icon")).not.toBeInTheDocument();
+    expect(screen.queryByTestId("parent-icon")).not.toBeInTheDocument();
+    expect(screen.getByText("Custom: Folder")).toBeInTheDocument();
+  });
+
+  it("sets data-folder on folder items and aria-expanded based on state", () => {
+    render(<Harness initialExpanded={["folder"]} />);
+
+    const folder = screen.getByTestId("item-folder");
+    expect(folder).toHaveAttribute("data-folder", "true");
+    expect(folder).toHaveAttribute("aria-expanded", "true");
+
+    const leaf = screen.getByTestId("item-leaf");
+    expect(leaf).not.toHaveAttribute("data-folder");
+  });
+
+  it("exposes the --tree-indent CSS variable on the root", () => {
+    render(<Harness />);
+    const root = document.querySelector('[data-slot="tree"]');
+    expect(root).toHaveStyle({ "--tree-indent": "20px" });
+  });
+});

package/src/components/tree/tree.tsx

@@ -1,42 +1,218 @@
-import * as React from "react";
+"use client";
+
+import { mergeProps } from "@base-ui/react/merge-props";
+import { useRender } from "@base-ui/react/use-render";
+import type { ItemInstance, TreeInstance } from "@headless-tree/core";
+import { ChevronRightIcon } from "lucide-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>
-    );
+  type CSSProperties,
+  createContext,
+  type ReactNode,
+  useContext,
+} from "react";
+
+import { cn } from "../../lib";
+
+const DEFAULT_PARENT_ICON = (
+  <ChevronRightIcon
+    aria-hidden
+    className="size-4 shrink-0 text-muted-foreground transition-transform duration-200 in-data-[expanded=true]:rotate-90"
+  />
+);
+
+interface TreeContextValue {
+  tree: TreeInstance<unknown>;
+}
+
+const TreeContext = createContext<TreeContextValue | undefined>(undefined);
+
+function useTreeContext() {
+  const context = useContext(TreeContext);
+  if (!context) {
+    throw new Error("Tree components must be used within a TreeRoot");
+  }
+  return context;
+}
+
+interface TreeItemContextValue {
+  item: ItemInstance<unknown>;
+}
+
+const TreeItemContext = createContext<TreeItemContextValue | undefined>(
+  undefined,
+);
+
+function useTreeItemContext() {
+  const context = useContext(TreeItemContext);
+  if (!context) {
+    throw new Error("TreeItemLabel must be used within a TreeItem");
+  }
+  return context;
+}
+
+interface TreeRootProps<T> extends useRender.ComponentProps<"div"> {
+  tree: TreeInstance<T>;
+  indent?: number;
+}
+
+export function TreeRoot<T>({
+  tree,
+  indent = 20,
+  className,
+  render,
+  style,
+  ...props
+}: TreeRootProps<T>) {
+  const { style: containerStyle, ...containerProps } = tree.getContainerProps();
+
+  const defaultProps = {
+    "data-slot": "tree",
+    ...containerProps,
+    className: cn("flex flex-col outline-none", className),
+    style: {
+      ...containerStyle,
+      ...style,
+      "--tree-indent": `${indent}px`,
+    } as CSSProperties,
   };
 
   return (
-    <TreeRoot items={items} {...props}>
-      {items.map((item) => renderItem(item))}
-    </TreeRoot>
+    <TreeContext.Provider value={{ tree: tree as TreeInstance<unknown> }}>
+      {useRender({
+        defaultTagName: "div",
+        render,
+        props: mergeProps<"div">(defaultProps, props),
+      })}
+    </TreeContext.Provider>
   );
 }
+
+type ParentIcon = ReactNode | ((isExpanded: boolean) => ReactNode);
+
+interface TreeItemProps<T> extends useRender.ComponentProps<"button"> {
+  item: ItemInstance<T>;
+  leafIcon?: ReactNode;
+  parentIcon?: ParentIcon;
+}
+
+export function TreeItem<T>({
+  item,
+  leafIcon,
+  parentIcon = DEFAULT_PARENT_ICON,
+  className,
+  render,
+  children,
+  style,
+  ...props
+}: TreeItemProps<T>) {
+  const { style: itemStyle, ...itemProps } = item.getProps();
+  const level = item.getItemMeta().level;
+  const isFolder = item.isFolder();
+  const isExpanded = item.isExpanded();
+
+  const icon = isFolder
+    ? typeof parentIcon === "function"
+      ? parentIcon(isExpanded)
+      : parentIcon
+    : leafIcon;
+
+  const autoLabel = (
+    <TreeItemLabel>
+      {icon}
+      {item.getItemName()}
+    </TreeItemLabel>
+  );
+
+  const defaultProps = {
+    "data-slot": "tree-item",
+    "data-focused": item.isFocused() || undefined,
+    "data-folder": isFolder || undefined,
+    "data-selected": item.isSelected?.() || undefined,
+    "data-drag-target": item.isDragTarget?.() || undefined,
+    "data-search-match": item.isMatchingSearch?.() || undefined,
+    "data-expanded": isExpanded || undefined,
+    "aria-expanded": isFolder ? isExpanded : undefined,
+    ...itemProps,
+    style: {
+      ...itemStyle,
+      ...style,
+      paddingInlineStart: `calc(var(--tree-indent) * ${level})`,
+    } as CSSProperties,
+    className: cn(
+      "z-10 not-last:pb-0.5 outline-hidden select-none focus:z-20",
+      "data-[disabled]:pointer-events-none data-[disabled]:opacity-50",
+      className,
+    ),
+    children: children ?? autoLabel,
+  };
+
+  return (
+    <TreeItemContext.Provider value={{ item: item as ItemInstance<unknown> }}>
+      {useRender({
+        defaultTagName: "button",
+        render,
+        props: mergeProps<"button">(defaultProps, props),
+      })}
+    </TreeItemContext.Provider>
+  );
+}
+
+export function TreeItemLabel({
+  className,
+  render,
+  children,
+  ...props
+}: useRender.ComponentProps<"span">) {
+  const { item } = useTreeItemContext();
+
+  const defaultProps = {
+    "data-slot": "tree-item-label",
+    className: cn(
+      "flex items-center gap-2 rounded-sm px-2 py-1.5 text-sm transition-colors",
+      "bg-background hover:bg-accent",
+      "in-data-[selected=true]:bg-accent in-data-[selected=true]:text-accent-foreground",
+      "in-data-[drag-target=true]:bg-accent",
+      "in-data-[search-match=true]:bg-blue-50",
+      "in-focus-visible:ring-3 in-focus-visible:ring-ring/50",
+      "[&_svg]:pointer-events-none [&_svg]:shrink-0",
+      className,
+    ),
+    children: children ?? item.getItemName(),
+  };
+
+  return useRender({
+    defaultTagName: "span",
+    render,
+    props: mergeProps<"span">(defaultProps, props),
+  });
+}
+
+export function TreeDragLine({
+  className,
+  render,
+  style,
+  ...props
+}: useRender.ComponentProps<"div">) {
+  const { tree } = useTreeContext();
+  const dragLineStyle = tree.getDragLineStyle?.();
+  if (!dragLineStyle) return null;
+
+  const defaultProps = {
+    "data-slot": "tree-drag-line",
+    style: { ...dragLineStyle, ...style },
+    className: cn(
+      "absolute z-30 -mt-px h-0.5 w-[unset] bg-primary",
+      "before:absolute before:-top-[3px] before:left-0 before:size-2 before:rounded-full",
+      "before:border-2 before:border-primary before:bg-background",
+      className,
+    ),
+  };
+
+  return useRender({
+    defaultTagName: "div",
+    render,
+    props: mergeProps<"div">(defaultProps, props),
+  });
+}
+
+export type { TreeRootProps, TreeItemProps };

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

@@ -2,8 +2,8 @@ import { Meta, StoryObj } from "@storybook/react-vite";
 import { isUndefined } from "lodash";
 import { ChevronLeft, ChevronRight } from "lucide-react";
 import { useState } from "react";
-import { createToastManager, ToastProvider } from "@/components/toast";
-import { Button, Input } from "../../../components";
+import { Button, createToastManager, Input } from "../../../components";
+import { LibraryProvider } from "../../../providers/library-provider";
 import useDebouncedValue from "../../useDebounceValue/useDebouncedValue";
 import useAsync from "../useAsync";
 
@@ -37,7 +37,7 @@ export const Basic = {
         <Input
           type="text"
           value={pokemonName}
-          onChange={setPokemonName}
+          onValueChange={setPokemonName}
           placeholder="Enter Pokémon name"
         />
         {loading && <p>Loading...</p>}
@@ -75,9 +75,9 @@ const fetchPokemonById = async (id: number) => {
 export const Advanced: Story = {
   decorators: [
     (Story) => (
-      <ToastProvider toastManager={toastManager}>
+      <LibraryProvider>
         <Story />
-      </ToastProvider>
+      </LibraryProvider>
     ),
   ],
   render: () => {

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

@@ -36,9 +36,7 @@ export const Default: Story = {
           </code>
         </pre>
 
-        <Button showLoader={false} onClick={() => copy(args.textoACopiar)}>
-          Copy
-        </Button>
+        <Button onClick={() => copy(args.textoACopiar)}>Copy</Button>
       </div>
     );
   },

package/src/hooks/useDebounceCallback/__doc__/useDebouncedCallback.stories.tsx

@@ -1,5 +1,5 @@
 import { Meta, StoryObj } from "@storybook/react-vite";
-import { Heading, Input } from "../../../components";
+import { Input } from "../../../components";
 import { createToastManager, ToastProvider } from "../../../components/toast";
 import { useDebouncedCallback } from "../../useDebounceCallback";
 
@@ -37,7 +37,7 @@ export const Basic = {
           <code className="block">Revisa la consola para ver los logs.</code>
         </pre>
         <Input
-          onChange={(value) => handleSearch(value)}
+          onValueChange={(value) => handleSearch(value)}
           placeholder="Escribe para buscar..."
         />
       </div>
@@ -64,17 +64,17 @@ export const DifferentDelays: StoryObj = {
     return (
       <div className="space-y-4">
         <div>
-          <Heading>Debounce Rápido (200ms)</Heading>
+          <h3 className="text-sm font-semibold">Debounce Rápido (200ms)</h3>
           <Input
-            onChange={(value) => handleFastDebounce(value)}
+            onValueChange={(value) => handleFastDebounce(value)}
             placeholder="Debounce rápido..."
           />
         </div>
 
         <div>
-          <Heading>Debounce Lento (1000ms)</Heading>
+          <h3 className="text-sm font-semibold">Debounce Lento (1000ms)</h3>
           <Input
-            onChange={(value) => handleSlowDebounce(value)}
+            onValueChange={(value) => handleSlowDebounce(value)}
             placeholder="Debounce lento..."
           />
         </div>

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

@@ -18,7 +18,7 @@ export const Default: Story = {
 
     return (
       <div className="space-y-2">
-        <Input onChange={setTitle} value={title} />
+        <Input onValueChange={setTitle} value={title} />
         <Button onClick={() => setTitle(title)}>Set document title</Button>
       </div>
     );

package/src/hooks/useEventListener/__test__/useEventListener.test.tsx

@@ -1,7 +1,7 @@
 import { screen } from "@testing-library/dom";
 import { render, waitFor } from "@testing-library/react";
 import { describe, expect, it, vi } from "vitest";
-import { click } from "../../../utils";
+import { click } from "../../../utils/tests";
 import useEventListener from "../useEventListener";
 
 describe("useEventListener hook", () => {

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

@@ -35,7 +35,7 @@ export const Default = {
 
     return (
       <div className="space-y-2">
-        <Input value={value} onChange={setValue} />
+        <Input value={value} onValueChange={setValue} />
         <Button onClick={removeValue}>Clear</Button>
       </div>
     );

package/src/hooks/usePagination/usePagination.tsx

@@ -1,4 +1,4 @@
-import { useState } from "react";
+import { useControllableState } from "@radix-ui/react-use-controllable-state";
 
 export type usePaginationProps = {
   /**
@@ -10,53 +10,65 @@ export type usePaginationProps = {
    */
   pageSize: number;
   /**
-   * Pagina inicial
+   * Página controlada
+   */
+  currentPage?: number;
+  /**
+   * Página inicial (uncontrolled)
+   */
+  defaultCurrentPage?: number;
+  /**
+   * Callback cuando cambia la página
+   */
+  onCurrentPageChange?: (page: number) => void;
+  /**
+   * @deprecated Usá `defaultCurrentPage`
    */
   initialCurrentPage?: number;
   /**
-   * Callback que se ejecuta cuando cambia la pagina
+   * @deprecated Usá `onCurrentPageChange`
    */
   onChange?: (value: { currentPage: number; pageSize: number }) => void;
-  siblingCount?: number;
 };
 
 function usePagination({
   totalItems,
   pageSize,
-  initialCurrentPage = 1,
+  currentPage: currentPageProp,
+  defaultCurrentPage,
+  onCurrentPageChange,
+  initialCurrentPage,
   onChange,
 }: usePaginationProps) {
-  const [currentPage, setCurrentPage] = useState<number>(initialCurrentPage);
-  const maxPage = Math.ceil(totalItems / pageSize);
-  const isLastPage = currentPage === maxPage;
-  const isFirstPage = currentPage === 1;
+  const [currentPage = 1, setCurrentPage] = useControllableState<number>({
+    prop: currentPageProp,
+    defaultProp: defaultCurrentPage ?? initialCurrentPage ?? 1,
+    onChange: (page) => {
+      onCurrentPageChange?.(page);
+      onChange?.({ currentPage: page, pageSize });
+    },
+  });
+
+  const maxPage = Math.max(1, Math.ceil(totalItems / pageSize));
+  const isLastPage = currentPage >= maxPage;
+  const isFirstPage = currentPage <= 1;
   const start = (currentPage - 1) * pageSize + 1;
   const end = Math.min(currentPage * pageSize, totalItems);
 
   const next = () => {
     if (isLastPage) return;
-    const newPage = Math.min(currentPage + 1, maxPage);
-    handleNewPage(newPage);
+    setCurrentPage(Math.min(currentPage + 1, maxPage));
   };
 
   const prev = () => {
     if (isFirstPage) return;
-    const newPage = Math.max(currentPage - 1, 1);
-    handleNewPage(newPage);
+    setCurrentPage(Math.max(currentPage - 1, 1));
   };
 
   const goTo = (page: number) => {
-    if (page === 1 && isFirstPage) return;
-    if (page === maxPage && isLastPage) return;
-
-    const pageNumber = Math.max(1, page);
-    const newPage = Math.min(pageNumber, maxPage);
-    handleNewPage(newPage);
-  };
-
-  const handleNewPage = (page: number) => {
-    setCurrentPage(page);
-    onChange?.({ currentPage: page, pageSize });
+    const clamped = Math.min(Math.max(1, page), maxPage);
+    if (clamped === currentPage) return;
+    setCurrentPage(clamped);
   };
 
   return {

package/src/styles/theme.css

@@ -29,7 +29,7 @@
   --color-success-foreground: oklch(98.42% 0.003 247.86);
 
   --color-warning: oklch(79.65% 0.16 70.08);
-  --color-warning-foreground: oklch(17.97% 0.034 59.63);
+  --color-warning-foreground: oklch(98.42% 0.003 247.86);
 
   --color-info: oklch(62.8% 0.152 237.57);
   --color-info-foreground: oklch(98.42% 0.003 247.86);