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

package/src/components/button/button.stories.tsx

@@ -1,22 +1,31 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
-import { cva, VariantProps } from "class-variance-authority";
+import { cva, type VariantProps } from "class-variance-authority";
 import { Flame, SearchIcon } from "lucide-react";
-import { ComponentProps } from "react";
-import { BaseButton, Button, Heading } from "../../components";
+import { type ComponentProps } from "react";
+import { BaseButton, Button, buttonVariants } from "../../components";
 import { cn } from "../../lib";
-import { ThemeProvider } from "../../providers";
 
 /**
- * Componente principal para ejecutar acciones.
+ * Primary action trigger built on the [Base UI Button](https://base-ui.com/react/components/button) primitive.
  *
- * Extendiende al componente `BaseButton` agregándole variantes
+ * **Loading** — pass an async function to `onClick` and loading state is managed automatically.
+ * Control it externally with the `loading` prop. The spinner overlays content while preserving
+ * the button's original dimensions so layout never shifts.
+ *
+ * **Custom elements** — use the `render` prop to swap the underlying element.
+ * For links, apply `buttonVariants` directly to a plain `<a>` — Base UI always sets
+ * `role="button"` which overrides the semantic link role on `<a>` elements rendered via `render`.
+ *
+ * **Extension** — use `BaseButton` to build fully custom variants without inheriting any styles.
  */
 const meta: Meta<typeof Button> = {
-  title: "Data entry/Button",
+  title: "Components/Button",
   component: Button,
   args: {
-    children: "Click me!",
+    children: "Click me",
   },
+  tags: ["beta"],
+  parameters: { layout: "centered" },
 };
 
 export default meta;
@@ -24,161 +33,176 @@ type Story = StoryObj<typeof Button>;
 
 export const Default: Story = {};
 
-export const Outline: Story = {
-  args: {
-    variant: "outline",
-  },
-};
-
-export const Secondary: Story = {
-  args: {
-    variant: "secondary",
-  },
-};
-
-export const Ghost: Story = {
-  args: {
-    variant: "ghost",
-  },
-};
-
-export const Link: Story = {
-  args: {
-    variant: "link",
-  },
+export const Variants: Story = {
+  render: (args) => (
+    <div className="flex flex-wrap items-center gap-3">
+      {(
+        [
+          "default",
+          "outline",
+          "secondary",
+          "ghost",
+          "link",
+          "error",
+          "success",
+          "warning",
+        ] as const
+      ).map((variant) => (
+        <Button key={variant} {...args} variant={variant}>
+          {variant}
+        </Button>
+      ))}
+    </div>
+  ),
 };
 
-export const Error: Story = {
-  args: {
-    variant: "error",
-  },
-};
+export const Sizes: Story = {
+  render: () => {
+    const textSizes = ["xs", "sm", "default", "lg"] as const;
+    const iconSizes = ["icon-xs", "icon-sm", "icon", "icon-lg"] as const;
 
-export const Success: Story = {
-  args: {
-    variant: "success",
+    return (
+      <div className="space-y-6">
+        <div className="flex flex-wrap items-end gap-4">
+          {textSizes.map((size) => (
+            <div key={size} className="flex flex-col items-center gap-2">
+              <p className="text-xs text-muted-foreground">{size}</p>
+              <Button size={size}>Click me</Button>
+            </div>
+          ))}
+        </div>
+        <div className="flex flex-wrap items-end gap-4">
+          {iconSizes.map((size) => (
+            <div key={size} className="flex flex-col items-center gap-2">
+              <p className="text-xs text-muted-foreground">{size}</p>
+              <Button size={size}>
+                <Flame />
+              </Button>
+            </div>
+          ))}
+        </div>
+      </div>
+    );
   },
 };
 
 /**
- * Se puede agregar un ícono al botón con la prop `icon`.
+ * Pass any icon element to the `icon` prop. It renders before the label by default
+ * (`inline-start`). Add `data-icon="inline-end"` to the icon element to move it after
+ * the label. Use an icon-only size (`icon`, `icon-sm`, etc.) for square icon buttons.
  */
-export const Icon: Story = {
-  args: {
-    icon: <SearchIcon />,
-  },
-};
+export const WithIcon: Story = {
+  render: (args) => (
+    <div className="flex flex-wrap items-center gap-4">
+      <Button {...args} icon={<SearchIcon />}>
+        Search
+      </Button>
+      <Button {...args} icon={<SearchIcon data-icon="inline-end" />}>
+        Search
+      </Button>
+      <Button icon={<SearchIcon />} size="icon" />
+    </div>
+  ),
+  parameters: {
+    docs: {
+      source: {
+        code: `<Button icon={<SearchIcon />}>Search</Button>
 
-/**
- * Se puede cambiar la posición del ícono con la prop `iconPosition`.
- *
- * Los valores posibles son `start` y `end`.
- */
-export const IconPosition: Story = {
-  args: {
-    icon: <SearchIcon />,
-    iconPosition: "end",
+<Button icon={<SearchIcon data-icon="inline-end" />}>Search</Button>
+
+<Button icon={<SearchIcon />} size="icon" />`,
+      },
+    },
   },
 };
 
 /**
- * El button recibe la propieda `loading` que permite controlar el estado de carga del botón.
- * Se puede cambiar la forma en la que se muestra el loader con la prop `loaderReplace`.
- * Si `loaderReplace` es `true`, el loader reemplaza todo el contenido manteniendo el ancho original del botón.
- * Por defecto, el loader se agrega al contenido existente o reemplaza al ícono en caso de que exista.
+ * When `onClick` returns a `Promise`, loading activates automatically and stops when
+ * the Promise settles — no external state needed. Pass `loading` directly to control it
+ * from outside (e.g., from a form submission handler or mutation hook).
+ *
+ * While loading, the button is non-interactive (`pointer-events-none`, `aria-busy`)
+ * and the spinner overlays content without changing the button's dimensions.
  */
 export const Loading: Story = {
   render: () => {
-    const sleep = (): Promise<void> => {
-      return new Promise((resolve) => setTimeout(resolve, 2000));
-    };
+    const sleep = (): Promise<void> =>
+      new Promise((resolve) => setTimeout(resolve, 2000));
 
     return (
-      <div className="space-y-8">
-        {/* Modo Append (default) */}
-        <section>
-          <Heading as="h2" className="mb-4">
-            Modo Append (default)
-          </Heading>
-          <p className="text-sm text-muted-foreground mb-4">
-            En este modo, el loader se agrega al contenido existente. Si hay un
-            ícono, el loader lo reemplaza.
+      <div className="space-y-10">
+        <section className="space-y-3">
+          <h2 className="text-sm font-semibold">Auto — async onClick</h2>
+          <p className="text-sm text-muted-foreground">
+            Click any button. Loading starts when the Promise begins and stops
+            when it resolves.
           </p>
-          <div className="flex flex-wrap items-center gap-4">
-            <Button onClick={sleep}>Por izquierda</Button>
-            <Button onClick={sleep} iconPosition="end">
-              Por derecha
-            </Button>
+          <div className="flex flex-wrap items-center gap-3">
+            <Button onClick={sleep}>Save</Button>
             <Button onClick={sleep} icon={<SearchIcon />}>
-              Ícono inicio
-            </Button>
-            <Button onClick={sleep} icon={<SearchIcon />} iconPosition="end">
-              Ícono final
+              Search
             </Button>
             <Button onClick={sleep} icon={<SearchIcon />} size="icon" />
           </div>
         </section>
 
-        {/* Modo Replace */}
-        <section>
-          <Heading as="h2" className="mb-4">
-            Modo Replace (loaderReplace = true)
-          </Heading>
-          <p className="text-sm text-muted-foreground mb-4">
-            En este modo, el loader reemplaza todo el contenido manteniendo el
-            ancho original del botón.
+        <section className="space-y-3">
+          <h2 className="text-sm font-semibold">Controlled</h2>
+          <p className="text-sm text-muted-foreground">
+            Pass the <code>loading</code> prop directly to control state
+            externally.
           </p>
-          <div className="flex flex-wrap items-center gap-4">
-            <Button onClick={sleep} loaderReplace>
-              Solo texto
+          <div className="flex flex-wrap items-center gap-3">
+            <Button loading>Save</Button>
+            <Button loading icon={<SearchIcon />}>
+              Search
             </Button>
-            <Button onClick={sleep} loaderReplace icon={<SearchIcon />}>
-              Ícono inicio
-            </Button>
-            <Button
-              onClick={sleep}
-              loaderReplace
-              icon={<SearchIcon />}
-              iconPosition="end"
-            >
-              Ícono final
-            </Button>
-            <Button
-              onClick={sleep}
-              loaderReplace
-              icon={<SearchIcon />}
-              size="icon"
-            />
+            <Button loading icon={<SearchIcon />} size="icon" />
           </div>
         </section>
 
-        {/* Variantes */}
-        <section>
-          <Heading as="h2" className="mb-4">
-            Variantes
-          </Heading>
-          <p className="text-sm text-muted-foreground mb-4">
-            El loader funciona con todas las variantes de botón.
-          </p>
-          <div className="flex flex-wrap items-center gap-4">
-            <Button onClick={sleep} variant="outline" icon={<SearchIcon />}>
-              Outline
-            </Button>
-            <Button onClick={sleep} variant="secondary" icon={<SearchIcon />}>
-              Secondary
-            </Button>
-            <Button onClick={sleep} variant="ghost" icon={<SearchIcon />}>
-              Ghost
-            </Button>
-            <Button onClick={sleep} variant="link" icon={<SearchIcon />}>
-              Link
-            </Button>
-            <Button onClick={sleep} variant="error" icon={<SearchIcon />}>
-              Error
-            </Button>
-            <Button onClick={sleep} variant="success" icon={<SearchIcon />}>
-              Success
-            </Button>
+        <section className="space-y-3">
+          <h2 className="text-sm font-semibold">All sizes</h2>
+          <div className="flex flex-wrap items-end gap-4">
+            {(["xs", "sm", "default", "lg"] as const).map((size) => (
+              <div key={size} className="flex flex-col items-center gap-2">
+                <p className="text-xs text-muted-foreground">{size}</p>
+                <Button loading size={size}>
+                  Save
+                </Button>
+              </div>
+            ))}
+            {(["icon-xs", "icon-sm", "icon", "icon-lg"] as const).map(
+              (size) => (
+                <div key={size} className="flex flex-col items-center gap-2">
+                  <p className="text-xs text-muted-foreground">{size}</p>
+                  <Button loading size={size}>
+                    <SearchIcon />
+                  </Button>
+                </div>
+              ),
+            )}
+          </div>
+        </section>
+
+        <section className="space-y-3">
+          <h2 className="text-sm font-semibold">All variants</h2>
+          <div className="flex flex-wrap items-center gap-3">
+            {(
+              [
+                "default",
+                "outline",
+                "secondary",
+                "ghost",
+                "error",
+                "success",
+                "warning",
+              ] as const
+            ).map((variant) => (
+              <Button key={variant} onClick={sleep} variant={variant}>
+                {variant}
+              </Button>
+            ))}
           </div>
         </section>
       </div>
@@ -187,83 +211,55 @@ export const Loading: Story = {
 };
 
 /**
- * Al setear `asChild` a `true`, puedes renderizar cualquier elemento con los estilos, props y referencias del `Button`.
+ * Use the `render` prop to render the button as any element while keeping all styles
+ * and behavior. For navigation links, use `buttonVariants` on a plain `<a>` tag instead —
+ * Base UI always applies `role="button"` which overrides the semantic `<a>` role.
  *
- * En este caso, se usa un elemento `a` que hereda los estilos, props y referencias del `Button`.
- * Esto es útil para aplicar los mismos estilos y garantizar consistencia en la interfaz de usuario de su aplicación.
- * Se puede verificar abriendo la consola del navegador.
- */
-export const AsChild: Story = {
-  args: {
-    children: <a href="#">Click me</a>,
-    variant: "error",
-    asChild: true,
-  },
-};
-
-/**
- * El componente recibe todas las propiedades de `button`, por lo que se puede customizar los estilos, accesibilidad, referencias, eventos, etc
- */
-export const Custom: Story = {
-  args: {
-    className: "bg-amber-500 hover:bg-amber-600",
-  },
-};
-
-/**
- * Estos son los tamanos disponibles para el `Button`.
+ * ```tsx
+ * // Render as a different element
+ * <Button render={<div />}>Custom element</Button>
+ *
+ * // Link styled as a button — correct pattern for navigation
+ * <a href="/dashboard" className={buttonVariants({ variant: "outline" })}>
+ *   Go to dashboard
+ * </a>
+ * ```
  */
-export const Sizes: Story = {
-  render: () => {
-    const sizes = ["default", "sm", "lg", "icon"] as const;
-
-    return (
-      <>
-        {sizes.map((size) => (
-          <div key={size} className="mb-1">
-            <p className="font-semibold">{`size: ${size}`}</p>
-            <Button size={size} key={size}>
-              {size === "icon" ? <Flame /> : "Click me"}
-            </Button>
-          </div>
-        ))}
-      </>
-    );
-  },
-};
-
-export const Shapes: Story = {
-  render: () => {
-    const shapes = ["rounded", "square", "circle"] as const;
+export const Render: Story = {
+  render: (args) => (
+    <div className="flex flex-wrap items-center gap-4">
+      <Button {...args} render={<div />}>
+        Rendered as div
+      </Button>
+      <a href="#" className={buttonVariants({ variant: "outline" })}>
+        Link as button
+      </a>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      source: {
+        code: `<Button render={<div />}>Rendered as div</Button>
 
-    return (
-      <div className="flex flex-wrap items-center gap-4">
-        {shapes.map((shape) => (
-          <div key={shape} className="flex flex-col gap-2">
-            <p className="font-semibold capitalize">{shape}</p>
-            <Button shape={shape} key={shape} size="icon" icon={<Flame />} />
-            <Button shape={shape} key={shape}>
-              {shape}
-            </Button>
-          </div>
-        ))}
-      </div>
-    );
+<a href="/dashboard" className={buttonVariants({ variant: "outline" })}>
+  Link as button
+</a>`,
+      },
+    },
   },
 };
 
-const buttonVariants = cva(
+const customButtonVariants = cva(
   [
-    "flex items-center justify-center gap-2 px-4 py-2",
-    "text-sm font-medium transition-all",
-    "rounded ring-offset-background",
-    "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
+    "inline-flex items-center justify-center gap-2 rounded-lg px-4 py-2",
+    "text-sm font-medium transition-all outline-none select-none",
+    "focus-visible:ring-3 focus-visible:ring-ring/50",
     "disabled:pointer-events-none disabled:opacity-50",
   ],
   {
     variants: {
       variant: {
-        white: "bg-white text-primary border",
+        white: "border border-border bg-white text-primary",
         black: "bg-black text-white",
       },
     },
@@ -274,123 +270,52 @@ const buttonVariants = cva(
 );
 
 type BaseButtonProps = ComponentProps<typeof BaseButton>;
-interface Props extends BaseButtonProps, VariantProps<typeof buttonVariants> {}
+interface CustomButtonProps
+  extends BaseButtonProps,
+    VariantProps<typeof customButtonVariants> {}
 
-const CustomButton = ({ variant, ...props }: Props) => {
-  return <BaseButton className={cn(buttonVariants({ variant }))} {...props} />;
-};
+const CustomButton = ({ variant, className, ...props }: CustomButtonProps) => (
+  <BaseButton
+    className={cn(customButtonVariants({ variant }), className)}
+    {...props}
+  />
+);
 
 /**
- * #### Crea tus propias variantes
- * En caso de que necesites customizar demasiado a tu componente, lo mejor es crear tus propias variantes.
- * Para esto se puede importar el componente `BaseButton` el cuál no incluye estilos por defecto y se puede extender para crear variantes personalizadas.
- *
- * A continuación, se definen las variantes de botón que puedes extender o modificar a tus necesidades.
+ * `BaseButton` is an unstyled wrapper around the Base UI primitive. Use it to build
+ * fully custom button variants without inheriting any library styles.
+ * It supports all native button props plus `loading` and the `render` prop.
  *
  * ```tsx
- * import { ComponentProps } from 'react';
+ * import { type ComponentProps } from 'react';
  * import { cva, type VariantProps } from 'class-variance-authority';
  * import { BaseButton, cn } from '@boxcustodia/library';
  *
- * export const buttonVariants = cva(
- *   [
- *     'flex items-center justify-center gap-2',
- *     'text-sm font-medium transition-all',
- *     'rounded-md ring-offset-background',
- *     'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2',
- *     'disabled:pointer-events-none disabled:opacity-50',
- *     'hover:brightness-105',
- *   ],
+ * const myVariants = cva(
+ *   'inline-flex items-center justify-center gap-2 rounded-lg px-4 py-2 text-sm font-medium transition-all outline-none disabled:pointer-events-none disabled:opacity-50',
  *   {
  *     variants: {
  *       variant: {
- *         default: "bg-primary text-primary-foreground",
- *         error: "bg-error text-error-foreground",
- *         success: "bg-success text-success-foreground",
- *         outline: "border border-input bg-background hover:bg-accent hover:text-accent-foreground",
- *         secondary: "bg-secondary text-secondary-foreground hover:brightness-100 hover:bg-secondary/80",
- *         ghost: "hover:bg-accent hover:brightness-100 hover:text-accent-foreground",
- *         link: "text-primary underline-offset-4 hover:underline",
- *         white: 'bg-white text-primary', <-- Nueva variante
- *         black: 'bg-black text-white', <-- Nueva variante
- *       },
- *       size: {
- *         default: "h-10 px-4 py-2",
- *         sm: "h-9 rounded-md px-3",
- *         lg: "h-11 rounded-md px-8",
- *         icon: "w-10 aspect-square",
+ *         white: 'border border-border bg-white text-primary',
+ *         black: 'bg-black text-white',
  *       },
  *     },
- *     defaultVariants: {
- *       variant: 'default',
- *       size: 'default',
- *     },
+ *     defaultVariants: { variant: 'white' },
  *   },
  * );
  *
- * type BaseButtonProps = ComponentProps<typeof BaseButton>;
- * typer Props = BaseButtonProps, VariantProps<typeof buttonVariants>
- *
- * export const Button = ({ className, variant, size, ...props }: Props) => {
- *   return (
- *     <BaseButton
- *       {...props}
- *       className={cn(buttonVariants({ variant, size }), className)}
- *     />
- *   );
- * };
+ * type Props = ComponentProps<typeof BaseButton> & VariantProps<typeof myVariants>;
  *
+ * export const CustomButton = ({ variant, className, ...props }: Props) => (
+ *   <BaseButton className={cn(myVariants({ variant }), className)} {...props} />
+ * );
  * ```
- *
  */
-
 export const CustomVariants: Story = {
   render: () => (
-    <div className="space-y-4">
-      <CustomButton variant="black">Default Button</CustomButton>
-      <CustomButton variant="white">Error Button</CustomButton>
+    <div className="flex flex-wrap items-center gap-4">
+      <CustomButton variant="white">White button</CustomButton>
+      <CustomButton variant="black">Black button</CustomButton>
     </div>
   ),
 };
-
-/**
- * ThemeProvider permite customizar de manera global las propiedades del componente
- *
- * Ejemplo:
- * ```tsx
- * <ThemeProvider
- *   theme={{
- *     Button: {
- *       className: "bg-red-500",
- *       icon: <SearchIcon />,
- *       iconPosition: "end",
- *       loaderReplace: true,
- *     },
- *   }}
- * >
- *   <Button>Default Button</Button>
- * </ThemeProvider>
- * ```
- */
-export const Theme: Story = {
-  render: () => {
-    const sleep = (): Promise<void> => {
-      return new Promise((resolve) => setTimeout(resolve, 2000));
-    };
-
-    return (
-      <ThemeProvider
-        theme={{
-          Button: {
-            className: "bg-red-500",
-            icon: <SearchIcon />,
-            iconPosition: "end",
-            loaderReplace: true,
-          },
-        }}
-      >
-        <Button onClick={sleep}>Default Button</Button>
-      </ThemeProvider>
-    );
-  },
-};

package/src/components/button/button.test.tsx

@@ -18,21 +18,14 @@ describe("Button component", () => {
     expect(button).toHaveTextContent("Click me");
   });
 
-  it("should render as child correctly", () => {
-    render(
-      <Button asChild>
-        <a href="#">Click me</a>
-      </Button>,
-    );
-
-    // No debe renderizarse como un button
-    const button = screen.queryByRole("button");
-    expect(button).not.toBeInTheDocument();
-
-    // Debe renderizarse como un link
-    const link = screen.getByRole("link");
-    expect(link).toBeInTheDocument();
-    expect(link).toHaveTextContent("Click me");
+  it("should render as custom element via render prop", () => {
+    render(<Button render={<a href="#">Click me</a>}>Click me</Button>);
+
+    // Base UI always applies role="button" even on custom elements
+    const button = screen.getByRole("button");
+    expect(button).toBeInTheDocument();
+    expect(button).toHaveTextContent("Click me");
+    expect(button.tagName.toLowerCase()).toBe("a");
   });
 
   it("should accept className prop", () => {
@@ -51,8 +44,8 @@ describe("Button component", () => {
     expect(ref.current).toBeInstanceOf(HTMLButtonElement);
   });
 
-  it("should show loader", () => {
+  it("should set data-loading when loading", () => {
     render(<Button loading />);
-    expect(screen.getByTestId("btn-loader")).toBeInTheDocument();
+    expect(screen.getByRole("button")).toHaveAttribute("data-loading");
   });
 });