@boxcustodia/library 2.0.0-alpha.11 → 2.0.0-alpha.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boxcustodia/library",
-  "version": "2.0.0-alpha.11",
+  "version": "2.0.0-alpha.13",
   "type": "module",
   "main": "dist/index.cjs.js",
   "module": "dist/index.es.js",
@@ -8,7 +8,8 @@
   "style": "dist/index.css",
   "sideEffects": false,
   "files": [
-    "/dist"
+    "/dist",
+    "/src"
   ],
   "publishConfig": {
     "access": "public",
@@ -17,7 +18,7 @@
   "scripts": {
     "format": "biome format --write .",
     "lint": "biome check --write --unsafe .",
-    "build": "tsc && vite build && npm run copy:theme && npm run build:css",
+    "build": "tsc && vite build && npm run copy:theme",
     "copy:theme": "node -e \"const fs=require('fs'); fs.copyFileSync('./src/styles/theme.css','./dist/theme.css'); fs.copyFileSync('./src/styles/library.css','./dist/index.css');\"",
     "build:css": "tailwindcss -i src/styles/components.css -o dist/components.css --minify",
     "test": "vitest run",

package/src/__doc__/Changelog.mdx

@@ -0,0 +1,6 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+import { ChangelogViewer } from "./Examples";
+
+<Meta title="Documentation/Changelog" />
+
+<ChangelogViewer />

package/src/__doc__/Components.mdx

@@ -0,0 +1,73 @@
+import {
+  Canvas,
+  ColorItem,
+  ColorPalette,
+  Meta,
+  Source,
+} from "@storybook/addon-docs/blocks";
+import { BorderRadius, ExampleProps } from "./Examples";
+
+<Meta title="Documentation/Components" />
+
+# Componentes
+
+## Estilos personalizados
+
+Cada componente extiende las propiedades del elemento HTML correspondiente, esto permite pasar clases y estilos.
+Se utiliza la librería `tailwind-merge` para combinar clases, evitar repeticiones y problemas de conflictos
+
+```tsx
+// Agrega el color de fondo. No es necesario hacer un !important
+<Input className="bg-red-400" />
+```
+
+## Creación de variantes y extensión de props
+
+Acá se puede ver un ejemplo de cómo crear un componente personalizado `Input` que incluye un icono "x" para limpiar el valor del campo. Este componente personalizado hereda todas las propiedades y funcionalidades del componente Input de la librería.
+
+<ExampleProps />
+```tsx 
+import {Button, Input} from "../../components";
+// CustomInput.tsx
+import { Button, Input } from "../../components";
+import { ComponentPropsWithoutRef, useState } from "react";
+
+// Extraer Props de componente Input
+type InputProps = ComponentPropsWithoutRef<typeof Input>;
+
+export const CustomInput = (props: InputProps) => {
+  const [value, setValue] = useState<string>("");
+
+  return (
+    <div className="relative">
+      <Input
+        {...props}
+        value={value}
+        onChange={(e) => setValue(e.target.value)}
+        className={cn("pr-12", props.className)}
+      />
+      <Button
+        variant="icon"
+        onClick={() => setValue("")}
+        className={cn(
+          "absolute right-0 top-1/2 -translate-y-1/2",
+          "text-error hover:text-error text-xl font-bold"
+        )}
+      >
+        x
+      </Button>
+    </div>
+  );
+};
+
+```
+
+### Crear un nuevo componente
+Para mantener la consistencia de los componentes y las estructuras se recomienda utilizar el comando `npx create-component`
+
+Va a generar los siguientes cambios
+* Crear el componente en `src/components/NAME.tsx`
+* Crear/actualizar barrels en `src/components/NAME/index.ts` y en `src/components/index.ts`
+* Crear el archivo de storybook con un template en `src/components/NAME/__doc__/NAME.stories.tsx`
+* Crear el archivo de test con un template en `src/components/NAME/__test__/NAME.test.tsx`
+```

package/src/__doc__/Examples.tsx

@@ -0,0 +1,69 @@
+import { X } from "lucide-react";
+import { ComponentPropsWithoutRef, useEffect, useState } from "react";
+import Markdown from "react-markdown";
+import { Button } from "../components/button";
+import { Input } from "../components/input";
+import { cn } from "../lib";
+
+export const BorderRadius = () => {
+  const sizes = [
+    "rounded-sm",
+    "rounded",
+    "rounded-md",
+    "rounded-lg",
+    "rounded-xl",
+  ];
+  return (
+    <div className="flex justify-center gap-4">
+      {sizes.map((size) => (
+        <div
+          key={size}
+          className={`${size} bg-primary text-primary-foreground h-28 w-28 grid place-items-center`}
+        >
+          {size}
+        </div>
+      ))}
+    </div>
+  );
+};
+
+type InputProps = ComponentPropsWithoutRef<typeof Input>;
+
+export const ExampleProps = (props: InputProps) => {
+  const [value, setValue] = useState<string>("");
+
+  return (
+    <div className="relative">
+      <Input
+        {...props}
+        value={value}
+        onChange={setValue}
+        className={cn("pr-12", props.className)}
+      />
+      <Button
+        size="icon"
+        variant="ghost"
+        onClick={(): void => setValue("")}
+        className={cn(
+          "absolute right-0 top-1/2 -translate-y-1/2 ",
+          "text-error hover:text-error text-xl font-bold",
+        )}
+      >
+        <X />
+      </Button>
+    </div>
+  );
+};
+
+export const ChangelogViewer = () => {
+  const [content, setContent] = useState("");
+
+  useEffect(() => {
+    fetch("../CHANGELOG.md")
+      .then((response) => response.text())
+      .then((text) => setContent(text))
+      .catch((error) => console.error("Error loading changelog:", error));
+  }, []);
+
+  return <Markdown>{content}</Markdown>;
+};

package/src/__doc__/Icons.mdx

@@ -0,0 +1,41 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+import React, { useState } from "react";
+import { Dog } from "lucide-react";
+
+<Meta title="Documentation/Icons" />
+
+# Documentación de Iconos
+
+En este proyecto se utiliza la librería de ícono [Lucide Icons](https://github.com/lucide-icons/lucide)
+
+## Instalación
+
+[Documentación de instalación](https://lucide.dev/guide/installation)
+
+```bash
+npm install lucide-react
+```
+
+## Utilización
+
+Basta con importar el ícono y usarlo como elemento JSX. Acá se puede ver el [listado de íconos](https://lucide.dev/icons/)
+
+<Dog />
+
+```jsx
+import { Dog } from "lucide-react";
+
+<Dog />;
+```
+
+## Personalización de los Iconos
+
+Puedes personalizar los íconos utilizando CSS. Por ejemplo, puedes cambiar el tamaño por defecto de los íconos ajustando la variable `--icon-size`
+Para más información, ver la documentación [Global Styles](https://lucide.dev/guide/advanced/global-styling)
+
+```css
+@theme {
+  /* ...Tus variables del theme */
+  --icon-size: 2rem;
+}
+```

package/src/__doc__/Intro.mdx

@@ -0,0 +1,138 @@
+import {
+  Canvas,
+  ColorItem,
+  ColorPalette,
+  Meta,
+  Source,
+} from "@storybook/addon-docs/blocks";
+import { BorderRadius } from "./Examples";
+
+<Meta title="Documentation/Intro" />
+
+# Librería de componentes de 📦
+
+La librería te ofrece una colección de componentes de UI personalizables que se adaptan fácilmente a lo que necesites.  
+Ya sea que estés buscando consistencia o flexibilidad, estos componentes te permiten construir interfaces rápidamente sin perder control sobre el estilo.
+Además, incluye hooks y utilidades que te facilitan la vida al manejar estados y otras tareas comunes, todo pensado para que desarrollar en frontend sea más sencillo y rápido.
+
+![boxcustodia](https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcS87eAzcc4MxVVBZK4hO0SgjOSDBGah5zyO6g&s)
+
+## Instalación
+
+Para empezar, primero debes instalar la librería ejecutando el siguiente comando en tu proyecto:
+
+```ts filename="index.js"
+npm i @boxcustodia/library
+```
+
+Luego, agregá estas dos líneas en tu CSS principal:
+
+```css filename="index.css"
+@import "tailwindcss";
+@import "@boxcustodia/library/dist/index.css";
+```
+
+Un solo import incluye el tema, las variantes y los estilos pre-compilados de todos los componentes. No hace falta `@source` apuntando a `node_modules`.
+
+## Personalización del tema
+
+Para ajustar colores, radios u otras variables a la identidad visual de tu proyecto, sobreescribí los tokens con `@theme` después de los imports:
+
+```css filename="index.css"
+@import "tailwindcss";
+@import "@boxcustodia/library/dist/index.css";
+
+@theme {
+  --color-background: oklch(100% 0 0);
+  --color-foreground: oklch(13.63% 0.036 259.2);
+
+  --color-popover: oklch(100% 0 0);
+  --color-popover-foreground: oklch(13.63% 0.036 259.2);
+
+  --color-primary: oklch(59.5% 0.195 270.48);
+  --color-primary-foreground: oklch(100% 0 0);
+
+  --color-secondary: oklch(96.83% 0.007 247.9);
+  --color-secondary-foreground: oklch(20.77% 0.04 265.75);
+
+  --color-muted: oklch(96.83% 0.007 247.9);
+  --color-muted-foreground: oklch(55.44% 0.041 257.42);
+
+  --color-accent: oklch(96.74% 0.001 286.38);
+  --color-accent-foreground: oklch(19.06% 0.003 247.96);
+
+  --color-error: oklch(63.68% 0.208 25.33);
+  --color-error-foreground: oklch(98.42% 0.003 247.86);
+
+  --color-success: oklch(70.1% 0.146 156.33);
+  --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-info: oklch(62.8% 0.152 237.57);
+  --color-info-foreground: oklch(98.42% 0.003 247.86);
+
+  --color-input: oklch(76.68% 0 0);
+  --color-checkbox: var(--color-primary);
+  --color-ring: oklch(13.63% 0.036 259.2);
+
+  --radius: 0.5rem;
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: calc(var(--radius));
+  --radius-xl: calc(var(--radius) + 4px);
+  --radius-tag: 0.375rem;
+  --radius-checkbox: 0.25rem;
+
+  --icon-size: 1rem;
+
+  --z-overlay: 50;
+  --z-float: 60;
+  --z-toast: 70;
+}
+```
+
+## Configuración del provider
+
+Envolvé tu app una sola vez con `<LibraryProvider>` — **es obligatorio**. Configura toda la infraestructura de la librería en un solo paso:
+
+```tsx
+// app.tsx
+import { LibraryProvider } from "@boxcustodia/library";
+
+export function App() {
+  return (
+    <LibraryProvider>
+      <Router />
+    </LibraryProvider>
+  );
+}
+```
+
+Incluye internamente:
+
+- **`TooltipProvider`** — agrupa el hover intent de todos los tooltips: una vez que uno se abre, los siguientes lo hacen sin delay hasta que el cursor salga.
+- **`ToastProvider`** — habilita la API imperativa `toast.*` desde cualquier parte del árbol.
+
+Props disponibles:
+
+- **`tooltipDelay`** (`number`, default `600`) — tiempo en ms antes de que se abra un tooltip.
+- **`toastManager`** (`ToastManager`, default singleton global) — pasá una instancia aislada para microfrontends o tests.
+
+## Tecnologías utilizadas
+
+- [React](https://reactjs.org/)
+- [Radix](https://www.radix-ui.com/)
+- [Tailwind CSS](https://tailwindcss.com/)
+- [Storybook](https://storybook.js.org/)
+- [Jest](https://jestjs.io/)
+- [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/)
+- [Prettier](https://prettier.io/)
+- [ESLint](https://eslint.org/)
+- [Husky](https://typicode.github.io/husky/#/)
+- [CVA](https://www.npmjs.com/package/class-variance-authority)
+
+## Documentación
+
+- [Netlify (temporal)](https://libreria-box-test.netlify.app)

package/src/__doc__/MCP.mdx

@@ -0,0 +1,71 @@
+import { Meta, Source } from "@storybook/addon-docs/blocks";
+
+<Meta title="Documentation/MCP" />
+
+# MCP — AI Integration
+
+Con este MCP (Model Context Protocol) Claude va a tener acceso directo a la documentación completa de todos los componentes de esta librería: props, variantes, ejemplos reales y patrones de uso.
+
+Sin el MCP, Claude no conoce esta librería. Inventa props, ignora nuestras convenciones y genera código genérico que no funciona. Con el MCP instalado, Claude consulta la documentación en tiempo real y genera código que usa correctamente `@boxcustodia/library` desde el primer intento, sin necesidad de leer el codebase ni darle contexto adicional.
+
+## Requisito previo
+
+El Storybook está hosteado en un proyecto privado de Chromatic. Para poder autenticarte necesitás tener acceso al proyecto.
+
+**Pedile a Franco Baigorria que te agregue como colaborador en Chromatic antes de continuar.**
+
+## Instalación
+
+Ejecutar una sola vez por computadora. Se instala globalmente y funciona en todos los proyectos internos automáticamente.
+
+La URL usa el formato de permalink de Chromatic (`branch--appId`) que siempre apunta al último deploy de la rama `v2`. No uses una URL de build específico — esas cambian con cada deploy.
+
+<Source
+  language="bash"
+  code={`npx mcp-add --type http --url "https://v2--69de51f0642746d263d5c46f.chromatic.com/mcp" --client-id "cdf3737dff9d485485968e50b63fd8b4" --scope global --clients "claude code"`}
+/>
+
+El instalador va a hacer algunas preguntas, respondé así:
+
+- **What is the server name?** → `boxcustodia-library`
+- **HTTP headers?** → dejar vacío, Enter
+- **claude code OAuth client secret?** → dejar vacío, Enter
+
+La primera vez que Claude use el MCP abrirá el browser para autenticarse con Chromatic.
+
+## Instrucción CLAUDE.md
+
+Se recomienda agregar este texto al archivo `CLAUDE.md` para que Claude sepa cuándo usar el MCP.
+
+<Source
+  language="markdown"
+  code={`## @boxcustodia/library
+Este proyecto usa @boxcustodia/library, que exporta componentes de UI y hooks de React.
+Cuando no estés seguro de cómo usar un componente o hook, qué props o parámetros acepta, qué variantes tiene,
+o cuál es el componente/hook correcto para una necesidad específica, consultá el MCP boxcustodia-library antes de escribir código.
+No es necesario consultarlo para usos básicos y evidentes.`}
+/>
+
+Así Claude lo consulta cuando realmente lo necesita — componentes complejos, props no obvias, patrones específicos — sin hacerlo para cada `Button` o `Input`.
+
+## Uso
+
+Una vez instalado, Claude consulta la documentación automáticamente. Algunos ejemplos de lo que podés pedirle:
+
+**Explorar la librería**
+
+<Source
+  language="bash"
+  code={`¿Qué componentes están disponibles en la librería?`}
+/>
+
+**Consultar props y variantes**
+
+<Source language="bash" code={`¿Qué props acepta el componente Combobox?`} />
+
+**Implementar funcionalidades**
+
+<Source
+  language="bash"
+  code={`Implementá un buscador con sugerencias usando el componente AutoComplete de la librería.`}
+/>