flysoft-react-ui 1.4.0 → 1.4.3

package/README.md

@@ -528,11 +528,11 @@ Las contribuciones son bienvenidas. Por favor, abre un issue o un pull request.
 ## 🔧 Scripts de Mantenimiento
 
 ```bash
-# Actualizar documentación automáticamente
-npm run update-docs
+# Regenerar la referencia de API de la skill desde los tipos
+npm run docs:skill
 
-# Validar que toda la documentación esté sincronizada
-npm run validate-docs
+# Validar que la referencia commiteada esté al día
+npm run docs:skill:check
 
 # Ver ejemplos completos
 npm run dev

package/claude/install-skill.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+
+/**
+ * Copia la skill `flysoft-ui` desde node_modules hacia el .claude/skills/ de la
+ * app consumidora.
+ *
+ * Claude Code no levanta skills desde node_modules, así que hace falta este paso
+ * de copia. La copia es DESTRUCTIVA Y COMPLETA: se borra el destino y se vuelve
+ * a copiar entero. Nunca hay merge. Si alguien editó la copia, esa edición se
+ * pierde — la fuente de verdad es el repo de flysoft-react-ui.
+ *
+ * Si el paquete instalado no trae `claude/` (versión anterior a la 1.4.0), avisa
+ * y sale con 0: no rompe el `update-libraries` de la app.
+ *
+ * Este archivo viaja dentro del paquete. Se puede correr de dos formas:
+ *
+ *   node node_modules/flysoft-react-ui/claude/install-skill.mjs
+ *
+ * o copiándolo al repo de la app (recomendado, ver AGENT_INSTRUCTIONS del repo
+ * de la librería) para que el script exista aunque el paquete no lo traiga:
+ *
+ *   cp node_modules/flysoft-react-ui/claude/install-skill.mjs scripts/
+ *   node scripts/install-skill.mjs
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+const SKILL_NAME = "flysoft-ui";
+const PACKAGE_NAME = "flysoft-react-ui";
+
+// Los scripts de npm corren con el cwd en la raíz del paquete de la app.
+const appRoot = process.cwd();
+const packageRoot = path.join(appRoot, "node_modules", PACKAGE_NAME);
+const source = path.join(packageRoot, "claude", "skills", SKILL_NAME);
+const target = path.join(appRoot, ".claude", "skills", SKILL_NAME);
+
+const label = `${PACKAGE_NAME} → .claude/skills/${SKILL_NAME}`;
+
+if (!fs.existsSync(packageRoot)) {
+  console.warn(
+    `[skill] ${PACKAGE_NAME} no está instalado. Se omite la sincronización de la skill.`
+  );
+  process.exit(0);
+}
+
+if (!fs.existsSync(source)) {
+  let version = "desconocida";
+  try {
+    version = JSON.parse(
+      fs.readFileSync(path.join(packageRoot, "package.json"), "utf8")
+    ).version;
+  } catch {
+    // Sin package.json legible no vale la pena insistir: el aviso alcanza.
+  }
+  console.warn(
+    `[skill] ${PACKAGE_NAME}@${version} no incluye claude/skills/${SKILL_NAME}. ` +
+      `Se omite la sincronización (hace falta 1.4.0 o superior).`
+  );
+  process.exit(0);
+}
+
+let version = "desconocida";
+try {
+  version = JSON.parse(
+    fs.readFileSync(path.join(packageRoot, "package.json"), "utf8")
+  ).version;
+} catch {
+  // Se sigue igual: la versión es informativa.
+}
+
+try {
+  // Destructivo a propósito: cualquier edición local del destino se descarta.
+  fs.rmSync(target, { recursive: true, force: true });
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.cpSync(source, target, { recursive: true });
+} catch (error) {
+  console.error(`[skill] Falló la copia ${label}: ${error.message}`);
+  process.exit(1);
+}
+
+const count = fs
+  .readdirSync(target, { recursive: true, withFileTypes: true })
+  .filter((entry) => entry.isFile()).length;
+
+console.log(`[skill] ${label} — ${count} archivos desde v${version}.`);

package/claude/skills/flysoft-ui/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: flysoft-ui
+description: Catálogo y referencia de API de flysoft-react-ui — componentes React themeados, hooks, providers, apiClient y templates. Usar al construir o modificar cualquier UI (formularios, listados, tablas, diálogos, filtros) en una app que tenga flysoft-react-ui como dependencia, y antes de escribir a mano un control que la librería probablemente ya tenga.
+---
+
+# flysoft-react-ui
+
+Librería de componentes React con tema y densidad centralizados. Todo se importa
+desde el paquete raíz — nunca desde rutas internas:
+
+```tsx
+import { Card, DataTable, Input, Button, useAsyncRequest } from "flysoft-react-ui";
+```
+
+## Cómo entran los estilos
+
+Los estilos entran una sola vez. **Importalos desde el CSS de la app, dentro de
+una capa**, no con un `import "flysoft-react-ui/styles"` en el entry de JS:
+
+```css
+/* index.css de la app — el orden de capas va antes que cualquier @import */
+@layer flysoft, base, components, utilities;
+
+@import "flysoft-react-ui/styles" layer(flysoft);
+@import "tailwindcss";
+```
+
+El motivo importa, porque el modo de fallar es silencioso. La librería importa
+`tailwindcss/theme` y `tailwindcss/utilities` por separado para saltear
+Preflight, y al hacerlo pierde la asignación de capa que Tailwind hace en su
+`index.css`: **sus utilities se publican sin capa**. En CSS, lo que no está en
+ninguna capa le gana a todo lo que sí — así que sin este `layer(flysoft)` los
+estilos de la librería pisan los de la app aunque la app tenga más
+especificidad, y no hay forma de ganarles salvo con `!important`.
+
+Declarando `flysoft` como la primera capa, la librería queda con la prioridad
+más baja y la app la puede sobreescribir normalmente.
+
+Si la app no usa capas para nada, `import "flysoft-react-ui/styles"` en el entry
+alcanza. En cuanto la app pone algo en una capa —lo hace cualquier proyecto con
+Tailwind v4— necesita la forma de arriba.
+
+Los componentes se pintan con variables CSS del tema (`--color-*`, `--radius-*`)
+y escalan con la densidad activa. No lleva colores hardcodeados y no hace falta
+configurarle nada por componente: el tema y la densidad se setean una vez en el
+provider.
+
+## Antes de escribir un componente, fijate si ya existe
+
+Cuando te pidan "un formulario con un buscador de clientes y una fecha", la
+respuesta no es escribir un `<select>` con búsqueda ni un calendario. Casi
+siempre ya hay un componente para eso, y uno hecho a mano queda fuera del tema,
+fuera de la densidad y sin el comportamiento de teclado y accesibilidad que el
+de la librería ya tiene.
+
+| Si necesitás | Usá | No escribas |
+|---|---|---|
+| Un desplegable con búsqueda sobre una lista que ya tenés en memoria | `AutocompleteInput` | `<select>`, combobox propio |
+| Lo mismo pero el dataset es grande y se busca contra el backend | `SearchSelectInput` | fetch + lista propia |
+| Un campo de fecha | `DateInput` | `<input type="date">`, calendario propio |
+| Un calendario suelto, sin input | `DatePicker` | — |
+| Un importe en pesos | `CurrencyInput` | `<input>` + formateo a mano |
+| Una tabla con datos, orden y acciones por fila | `DataTable` | `<table>` |
+| Filtros que viven en la URL | `Filter` | `useSearchParams` + inputs sueltos |
+| Paginación | `Pagination` | controles propios |
+| Un modal | `Dialog` | portal propio |
+| Un toast / notificación | `useSnackbar()` | librería de toasts |
+| Mostrar un par etiqueta-valor | `DataField` | `<div><label>` |
+| Apilar o alinear elementos con separación | `Collection` | `<div className="flex gap-4">` |
+| Un contenedor con título, acciones y footer | `Card` | `<div>` con bordes |
+| Estado de carga | `Loader` o `Skeleton` | spinner propio |
+
+Antes de dar por hecho que algo no existe, buscalo en la referencia de abajo:
+son 33 componentes más 7 templates, y hay bastante más de lo que parece.
+
+Si de verdad no existe, componelo con los que sí (`Card` + `Collection` +
+`Input`) antes de escribir CSS nuevo, y usá siempre las variables del tema
+(`references/theming.md`), nunca colores literales.
+
+## Dónde está cada cosa
+
+Las referencias se cargan sueltas: leé sólo la que necesites.
+
+| Necesitás | Leé |
+|---|---|
+| Inputs, botones, selects, fechas, importes, paginación | `references/forms.md` |
+| Tablas, campos de datos, badges, avatares, loaders, skeletons | `references/display.md` |
+| Cards, layout de página, tabs, acordeones, diálogos, menús, filtros | `references/layout.md` |
+| Providers, hooks y lo que devuelve cada uno | `references/hooks.md` |
+| `apiClient`, helpers, interfaces compartidas | `references/services.md` |
+| Formularios y páginas pre-armadas | `references/templates.md` |
+| Variables CSS de tema y densidad | `references/theming.md` |
+| **Cuándo usar qué, patrones de página, densidad, contratos de los genéricos** | **`patterns.md`** |
+
+Los archivos bajo `references/` se generan desde los tipos de la librería en
+cada build. Si una tabla no coincide con el código, el que está mal es el tipo,
+no la tabla.
+
+`patterns.md` es lo escrito a mano: empezá por ahí si la pregunta es "cómo se
+arma una página de listado" y no "qué props tiene `DataTable`".

package/claude/skills/flysoft-ui/patterns.md

@@ -0,0 +1,352 @@
+# Cómo se usa flysoft-react-ui
+
+Esto es lo que los tipos no dicen: cuándo elegir un componente sobre otro, qué
+forma tiene que tener un genérico, y cómo se arma una página completa. Para
+firmas y props, `references/`.
+
+---
+
+## El sistema de densidad
+
+Es lo que más se malinterpreta, porque no se ve en las props de ningún
+componente.
+
+La densidad es **global y se setea una sola vez**, en el provider:
+
+```tsx
+<AppLayoutProvider density="compact">
+  <App />
+</AppLayoutProvider>
+```
+
+Los valores son `"comfortable" | "compact" | "dense"`. El provider escribe 26
+variables CSS (`--flysoft-density-*`) en el `<html>`, y **todos** los componentes
+de la librería leen de ahí: padding, tipografía, alto de los controles, alto de
+las filas de `DataTable`, radio de los inputs, separación de `Collection`.
+
+La consecuencia práctica es la que importa:
+
+> **No pases `compact` ni `size="sm"` componente por componente para achicar la
+> UI.** Esas props existen y funcionan, pero son overrides puntuales. Si las usás
+> para lograr una UI compacta, terminás con una densidad distinta en cada
+> pantalla, y el día que cambie la densidad global esos componentes no la siguen.
+
+Si toda la app tiene que verse más compacta, se cambia una palabra en el
+provider. Si necesitás densidad distinta sólo en una sección, hay un override
+por subárbol:
+
+```tsx
+<Collection density="dense">
+  {/* estos hijos y sus descendientes usan la escala "dense" */}
+</Collection>
+```
+
+La densidad se persiste en `localStorage` bajo `"flysoft-density"` y se puede
+cambiar en runtime:
+
+```tsx
+const { density, setDensity } = useAppLayout();
+```
+
+Para forzar un valor e ignorar lo guardado, `forceInitialDensity`. Los valores
+concretos de cada token están en `references/theming.md`.
+
+---
+
+## Qué forma tiene que tener `T`
+
+Varios componentes son genéricos sin restricción: el tipo acepta cualquier `T`,
+pero el componente en runtime espera algo. Este es el contrato real.
+
+### `AutocompleteInput<T, K>` y `SearchSelectInput<T, K>`
+
+Sin `getOptionLabel` / `getOptionValue`, el componente lee `item.label` e
+`item.value`. O sea que `T` tiene que ser `{ label: string; value: string }`
+—las interfaces `AutocompleteOption` y `SearchSelectOption` son exactamente eso.
+
+Con tus propios objetos, pasás los dos getters y `T` puede ser lo que quieras:
+
+```tsx
+<AutocompleteInput<Cliente, number>
+  label="Cliente"
+  options={clientes}
+  getOptionLabel={(c) => c.razonSocial}
+  getOptionValue={(c) => c.id}
+/>
+```
+
+Si omitís los getters con un `T` que no tiene `label`, no hay error de
+compilación: la lista se renderiza con todas las etiquetas vacías. Es el modo de
+fallar más común de estos dos componentes.
+
+### `DataTable<T>`
+
+`column.value` acepta un string, que se usa como nombre de propiedad de la fila.
+**Si la propiedad no existe, se renderiza el string tal cual**, como texto
+literal. Un typo en el nombre del campo no rompe: te muestra `"nomrbe"` en la
+celda. El tipo no puede detectarlo porque `value` es `string`, no `keyof T`.
+
+Cuando el dato no sale de una propiedad directa, usá la forma de función, que sí
+está tipada:
+
+```tsx
+{ header: "Total", value: (row) => currencyFormat(row.importe * row.cantidad) }
+```
+
+### `Menu<T>` y `DropdownMenu<T>`
+
+Mismo contrato que `AutocompleteInput`: sin `getOptionLabel`, leen `item.label`.
+
+### `CrudProvider<T>` / `useCrud<T>`
+
+`T` es la entidad. Ojo con la forma de lo que devuelve `useCrud`: las
+operaciones **no son funciones**, son objetos con `execute` e `isLoading`
+propios.
+
+```tsx
+const { list, fetchItems, createItem } = useCrud<Usuario>();
+
+await fetchItems.execute({ pagina: 2 });   // correcto
+await fetchItems();                         // no compila
+```
+
+---
+
+## Cuándo usar qué
+
+**`Card` vs `Collection` vs `DataField`.** `Card` es una superficie con título,
+acciones y footer — un bloque de contenido con identidad. `Collection` no dibuja
+nada: sólo apila o alinea con la separación de la densidad activa; es el
+reemplazo de `<div className="flex gap-4">`. `DataField` es un par
+etiqueta-valor para pantallas de detalle, no un contenedor.
+
+**`AutocompleteInput` vs `SearchSelectInput`.** Si las opciones ya están en
+memoria y son unas pocas decenas, `AutocompleteInput`. Si hay que ir al backend
+a buscarlas, `SearchSelectInput`, que abre un diálogo y recibe dos promesas: una
+para buscar por texto y otra para resolver un valor ya seleccionado
+(`onSingleSearchPromiseFn`, necesaria para poder mostrar el label cuando la
+pantalla carga con un valor preexistente).
+
+**`DataTable` vs `Collection` de `Card`s.** Tabla cuando las filas comparten
+columnas y se comparan entre sí. Cards cuando cada ítem tiene forma propia.
+
+**`Dialog` vs `DropdownPanel`.** `Dialog` bloquea e interrumpe: confirmaciones y
+formularios. `DropdownPanel` es un popover anclado a un disparador, para filtros
+y opciones.
+
+**Template vs composición.** Los templates (`ListPattern`, `FormPattern`,
+`LoginForm`) resuelven un caso entero. Sirven mientras tu caso sea el suyo; en
+cuanto necesitás desviarte, componé con `Card` + `DataTable` + `Filter` en vez
+de pelearle las props. `ListPattern` es el que más rinde porque el listado
+paginado con filtros es siempre igual.
+
+---
+
+## Patrones
+
+### Formulario con guardado async
+
+`useAsyncRequest` envuelve la promesa, maneja el `isLoading` y dispara el
+snackbar de éxito o error. Necesita un `SnackbarProvider` arriba —
+`AppLayoutProvider` ya lo incluye.
+
+```tsx
+const { execute, isLoading } = useAsyncRequest({
+  successMessage: "Guardado exitosamente",
+  errorMessage: (err) => getErrorMessage(err),
+});
+
+const guardar = () =>
+  execute(() => apiClient.post({ url: "/api/usuarios", body: { nombre, email } }));
+
+return (
+  <Card title="Nuevo usuario">
+    <Collection>
+      <Input label="Nombre" value={nombre} onChange={(e) => setNombre(e.target.value)} icon="fa-user" />
+      <Input label="Email" type="email" value={email} onChange={(e) => setEmail(e.target.value)} icon="fa-envelope" />
+      <Button icon="fa-save" loading={isLoading} onClick={guardar}>Guardar</Button>
+    </Collection>
+  </Card>
+);
+```
+
+`execute` devuelve el resultado de la promesa, o `undefined` si falló — así que
+podés encadenar sin try/catch:
+
+```tsx
+const creado = await execute(() => apiClient.post<Usuario>({ url: "/api/usuarios", body }));
+if (creado) navigate(`/usuarios/${creado.id}`);
+```
+
+### Confirmación con Dialog
+
+`isOpen`, `title` y `children` son requeridas. Las acciones van en `footer`.
+
+```tsx
+<Dialog
+  isOpen={mostrarConfirmacion}
+  title="Confirmar eliminación"
+  onClose={() => setMostrarConfirmacion(false)}
+  footer={
+    <>
+      <Button variant="ghost" onClick={() => setMostrarConfirmacion(false)}>Cancelar</Button>
+      <Button color="danger" loading={isLoading} onClick={eliminar}>Eliminar</Button>
+    </>
+  }
+>
+  <p>¿Está seguro? Esta acción no se puede deshacer.</p>
+</Dialog>
+```
+
+Por defecto el click en el overlay **no** cierra el diálogo (`closeOnOverlayClick`
+es `false`), que es lo que querés en una confirmación destructiva.
+
+### Página de listado
+
+Los `Filter` se sincronizan solos con el query string a través de `paramName`, y
+`Pagination` hace lo mismo con `fieldName` (por defecto `"pagina"`). No hace
+falta cablear nada entre ellos: el efecto que dispara la búsqueda escucha los
+search params.
+
+```tsx
+function ListadoUsuarios() {
+  const [searchParams] = useSearchParams();
+  const [usuarios, setUsuarios] = useState<Usuario[]>([]);
+  const [paginacion, setPaginacion] = useState({ page: 1, pages: 1, total: 0 });
+  const [isLoading, setIsLoading] = useState(false);
+  const { showSnackbar } = useSnackbar();
+
+  useEffect(() => {
+    const buscar = async () => {
+      setIsLoading(true);
+      try {
+        const params = Object.fromEntries(searchParams);
+        const data = await apiClient.get<PaginationInterface<Usuario>>({
+          url: "/api/usuarios",
+          params,
+        });
+        setUsuarios(data.list);
+        setPaginacion({ page: data.page, pages: data.pages, total: data.total });
+      } catch (error) {
+        showSnackbar(getErrorMessage(error), "danger");
+      } finally {
+        setIsLoading(false);
+      }
+    };
+    buscar();
+  }, [searchParams]);
+
+  const columns: DataTableColumn<Usuario>[] = [
+    { header: "Nombre", value: "nombre" },
+    { header: "Email", value: "email" },
+    { header: "Alta", value: "fechaAlta", type: "date" },
+    {
+      actions: (row) => [
+        <LinkButton key="ver" to={`/usuarios/${row.id}`} variant="ghost" icon="fa-eye" />,
+      ],
+    },
+  ];
+
+  return (
+    <Collection>
+      <Collection direction="row">
+        <Filter filterType="search" paramName="nombre" label="Nombre" />
+        <Filter
+          filterType="autocomplete"
+          paramName="rol"
+          label="Rol"
+          options={[
+            { label: "Administrador", value: "admin" },
+            { label: "Operador", value: "operador" },
+          ]}
+        />
+      </Collection>
+
+      <Card
+        title="Usuarios"
+        headerActions={<LinkButton to="/usuarios/nuevo" icon="fa-plus">Nuevo</LinkButton>}
+      >
+        <DataTable columns={columns} rows={usuarios} isLoading={isLoading} />
+        <Pagination {...paginacion} isLoading={isLoading} />
+      </Card>
+    </Collection>
+  );
+}
+```
+
+`DataTable` formatea solo según `type`: `"currency"` a miles con dos decimales y
+sin símbolo, `"numeric"` según el `locale` (por defecto `"es-AR"`), `"date"` a
+`DD/MM/YYYY`. Las columnas `currency` y `numeric` además se alinean solas a la
+derecha, no hace falta pasar `align`.
+
+### El mismo listado con ListPattern
+
+Cuando el caso es el estándar, `ListPattern` reemplaza todo el JSX de arriba:
+
+```tsx
+<ListPattern<Usuario>
+  title="Usuarios"
+  columns={columns}
+  rows={usuarios}
+  searchParamName="nombre"
+  addButtonText="Nuevo"
+  onAdd={() => navigate("/usuarios/nuevo")}
+  filtersNode={<Filter filterType="autocomplete" paramName="rol" label="Rol" options={roles} />}
+  page={paginacion.page}
+  pages={paginacion.pages}
+  total={paginacion.total}
+  isLoading={isLoading}
+/>
+```
+
+### Token de autenticación en el apiClient
+
+Se registra una vez, y todas las llamadas lo mandan:
+
+```tsx
+setApiClientTokenProvider(() => user?.token?.accessToken);
+```
+
+Es un *provider*, no un valor: se evalúa en cada request, así que un refresh de
+token se refleja solo sin volver a registrar nada.
+
+### Controlar el drawer desde el contenido
+
+En desktop el drawer está siempre visible; en móvil es un panel con overlay que
+queda abierto después de navegar. Por eso los links del drawer lo cierran:
+
+```tsx
+const { closeLeftDrawer } = useLeftDrawer();
+
+<LinkButton to="/inicio" onClick={closeLeftDrawer}>Inicio</LinkButton>
+```
+
+`useLeftDrawer()` lanza error fuera de un `AppLayout`. Para componentes que se
+usan dentro y fuera, `useOptionalLeftDrawer()` devuelve `undefined`.
+
+---
+
+## Íconos
+
+FontAwesome 5, estilo light. Se pasa sólo el nombre y la librería lo normaliza a
+`fal fa-*`:
+
+```tsx
+<Button icon="fa-save">Guardar</Button>
+```
+
+No mezclar con otras librerías de íconos: no van a heredar el color ni el tamaño
+del tema.
+
+---
+
+## Trampas verificadas
+
+- **`CurrencyInput.onChange` está tipado `(value: any) => void`.** El valor real
+  que recibís es `number`. Tipá tu handler como `number` igual.
+- **`DataTable` con un `value` string que no existe en la fila** renderiza el
+  string como texto, no falla. Revisá los nombres de campo.
+- **`useCrud()` devuelve objetos, no funciones** (`fetchItems.execute()`).
+- **`NavbarInterface.fullWidthNavbar` es requerida**, no opcional.
+- **`Collection` es `direction="column"` por defecto**, no `row`.
+- **`SnackbarContainer` es `position="top-right"` por defecto.**