@kapiuara/ui 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,765 @@
-# Temporary Holding Version
+# @kapiuara/ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Design system extraído del v2 de `ucugestionfront`. React 19 + TypeScript + Vite.
+CSS nativo propio scopeado bajo `.kapi` (tokens como custom properties). Sin Radix / Bootstrap /
+Tailwind / Mantine. Iconos: sólo `lucide-react`. Fuente: Nunito.
+
+> Paquete privado del monorepo `kapiuara`. Todavía no se publica: es `private: true` y no hay nada publicado en el scope `@kapiuara` de npm. Ver `BRANDING.md` en la raíz del repo.
+
+## Comandos
+
+| Comando                         | Qué hace                                                                               |
+| ------------------------------- | -------------------------------------------------------------------------------------- |
+| `pnpm dev`                      | Playground (demo/) en dev server, usa `src/` directo vía alias `@kapiuara/ui`          |
+| `pnpm build`                    | Build de la LIBRERÍA: un `.js` + `.d.ts` por módulo (`dist/index.js`), `dist/kapi.css` |
+| `pnpm build:demo`               | Build estático del playground → `dist-demo/`                                           |
+| `pnpm test` / `pnpm test:watch` | Vitest (lógica pura, no markup)                                                        |
+| `pnpm typecheck`                | `tsc --noEmit` sobre src + demo + configs                                              |
+| `pnpm test:visual`              | Regresión visual del catálogo (Playwright, en Docker); ver abajo                       |
+| `pnpm test:visual:update`       | Regenera las baselines de la regresión visual (en Docker)                              |
+
+### Regresión visual
+
+`pnpm test:visual` compara capturas del demo compilado (`build:demo` + `vite preview`) contra las
+baselines de `visual/__screenshots__/`: Chromium, viewport 1280×800, tema claro en cada sección del
+catálogo (`demo/catalog.tsx`, una sección nueva entra sola) y oscuro en la cáscara, inputs, tabla,
+diálogos y feedback. Reloj fijo, sin animaciones y con las fuentes cargadas. Tolerancia: ningún píxel
+distinto (`maxDiffPixels: 0`) con umbral por píxel `0.005`, que alcanza para ver un gris corrido 2–3
+niveles; `0` no es estable (el antialiasing varía entre corridas).
+
+- Corre **siempre dentro de la imagen** `mcr.microsoft.com/playwright:v1.63.0-noble` (la misma del
+  job `visual` del CI). `visual/run.sh` la levanta con Docker con tu uid, instala las dependencias
+  dentro del contenedor y devuelve el reporte a `playwright-report/` (gitignored). Requiere Docker.
+- Si un cambio visual es intencional, `pnpm test:visual:update` regenera las baselines; revisá los
+  PNG en el diff y commitealos junto al cambio. Borra las baselines huérfanas (de secciones que ya
+  no existen), reescribe solo las que cambiaron y, si Playwright falla, no toca las del repo. El
+  script no acepta otros argumentos. **Nunca** las regeneres fuera de la imagen (otro SO
+  rasteriza distinto y el CI fallaría).
+- No forma parte de `pnpm check`. Si el job `visual` falla, el artefacto `visual-report` trae el
+  reporte con las diferencias. Un test de vitest (`visual/catalogRoutes.test.ts`) verifica que la
+  lista de rutas leída de `demo/catalog.tsx` coincida con `CATALOG`.
+
+## Estructura
+
+```
+src/components/{inputs,overlays,data,feedback,navigation,layout}/   # un index.ts por tema
+src/hooks/        # mecánicas: drag-scroll, click derecho global, tema, media query
+src/styles/       # kapi.css (componentes; importa los tokens de @kapiuara/tokens), shell.css, fonts.css
+src/index.ts      # barrel: re-exporta todo
+demo/             # playground: index.html, main.tsx, App.tsx, catalog.tsx, views/
+```
+
+## Convenciones
+
+- Props tipadas explícitas (`XxxProps` exportado: los tipos SON el contrato). Defaults en los parámetros.
+- Cada prop pública lleva una línea de JSDoc (con `@default` si el default no se ve en la desestructuración):
+  es la fuente de la [referencia de props](#referencia-de-props).
+- JSX runtime automático: no hace falta `import React`.
+- Nada hardcodeado inline: clases `.kapi-*` en `src/styles/` usando tokens `--kapi-*`. Inline sólo si es dinámico
+  (p. ej. la posición `left/top` del menú contextual).
+- Componentes de comportamiento sobre `<dialog>` nativo cuando aplique.
+- Tests: lógica pura exportada (ej. `buttonClasses`), colocados como `Xxx.test.ts`.
+- Todo CSS nuevo va anidado bajo `.kapi { … }`. Es CSS plano: comentarios `/* */` (nunca `//`).
+- Los overlays se montan DENTRO de `.kapi` (hijos del `KapiShell` o vía su prop `overlays`) para heredar tokens.
+- Overlays controlados: `open` + `onClose()` (Escape, fondo, X y Cancelar piden cierre); paneles plegables:
+  `collapsed`/`defaultCollapsed`/`onCollapsedChange`. Ej.: `<KapiModal open={open} onClose={() => setOpen(false)}>…</KapiModal>`.
+- `.kapi-row` ya existe (space-between); para filas con gap usá `.kapi-cluster`.
+- Para sumar un componente al playground: una sección en `demo/catalog.tsx`.
+
+## Referencia de props
+
+El playground trae una vista **Referencia → Referencia de props** (`#/referencia/props/KapiButton`): elige un
+componente y ves la tabla de sus props (nombre, tipo, si es requerida, valor por defecto y descripción) más un
+resumen de los atributos nativos que pasa al elemento.
+
+La tabla se genera desde el código TypeScript en cada `pnpm dev` / `pnpm build:demo` (`scripts/propsDoc.mjs`,
+servido como módulo virtual `virtual:kapi-props-doc` por `scripts/vitePropsDoc.mjs`); no hay nada generado en
+el repo, así que no se desactualiza. **La fuente es el JSDoc de cada prop** en el tipo `XxxProps`:
+
+```ts
+export type KapiFooProps = {
+  /** Escala del control. */
+  size?: "sm" | "md" | "lg";
+  /**
+   * Cuántos ítems se muestran antes de "Ver más".
+   * @default 5
+   */
+  limit?: number;
+  /** @deprecated Usa `size`. */
+  compact?: boolean;
+};
+```
+
+- El valor por defecto sale de `@default` o, si no hay, del default en la desestructuración del componente.
+- `@deprecated` marca la prop como obsoleta en la tabla.
+- Las props que vienen de `HTMLAttributes` y compañía no se listan una por una: se resumen en una línea.
+- El JSDoc tiene que ir en un tipo de varias líneas: TypeScript no asocia el comentario a miembros de un tipo
+  escrito en una sola línea (`{ /** … */ a: string }`).
+
+## Consumo de estilos
+
+Todo el CSS (los tokens de `@kapiuara/tokens`, el shell y el CSS co-locado de cada componente:
+`KapiSelect.css`, `overlays.css`, `KapiOffcanvas.css`, `feedback.css`, `navigation.css`, `KapiTable.css`,
+etc.) se emite en UN solo archivo: `dist/kapi.css`, expuesto como `@kapiuara/ui/styles.css`. El build
+inlinea el `@import` de los tokens, así que la app host **no** instala `@kapiuara/tokens`. Se importa
+una vez en la app host:
+
+```ts
+import "@kapiuara/ui/styles.css";
+import "@fontsource-variable/nunito"; // opcional: la fuente NO viene en la lib (ver "Fuente")
+```
+
+Los componentes también importan su CSS (por eso `sideEffects: ["**/*.css"]`), pero en modo lib Vite lo
+extrae a `kapi.css`; los `.js` de `dist/` no contienen imports de CSS.
+
+## React Server Components
+
+Cada módulo que usa React abre con `"use client"` en `dist`, así que los componentes se pueden importar desde un Server Component (Next.js App Router) sin envolverlos. La lógica pura (`*Logic`, helpers de clases) no lleva la directiva y se puede usar en el servidor. El build falla si un módulo que importa `react` queda sin ella.
+
+## Tree-shaking
+
+El build de la librería emite un módulo por archivo fuente (`preserveModules`, raíz `src/`), con su `.d.ts`
+al lado. El bundler de la app descarta lo que no importa: una app que sólo usa `KapiButton` suma ~0,6 kB
+minificados en lugar de ~11 kB con el archivo único anterior.
+
+## Shell composable (con y sin rail)
+
+`KapiShell` es la raíz `.kapi` (tema, acento, fuente, click derecho global) y compone
+`[rail?] [panel?] <main.kapi-content>`. Rail y panel son props OPCIONALES e independientes.
+
+```tsx
+import { KapiShell, KapiRail, KapiContextSlot, KapiPanelItem, KapiPanelList } from "@kapiuara/ui";
+import "@kapiuara/ui/styles.css";            // + importá la fuente: @fontsource-variable/nunito
+
+// 1) Con rail + panel contextual
+<KapiShell
+  rail={<KapiRail brand="S" items={items} activeId={activeId} onSelect={go} />}
+  panel={
+    <KapiContextSlot title="Personas">
+      <KapiPanelList><KapiPanelItem active>Listado</KapiPanelItem></KapiPanelList>
+    </KapiContextSlot>
+  }
+>
+  <Pagina />
+</KapiShell>
+
+// 2) Sin rail, con panel (otra navegación va en el contenido)
+<KapiShell panel={<KapiContextSlot title="Sección">…</KapiContextSlot>}>
+  <MiTopNav />
+  <Pagina />
+</KapiShell>
+
+// 3) Sólo contenido
+<KapiShell><Pagina /></KapiShell>
+```
+
+- `KapiRail` es presentacional: la app le pasa `activeId` + `onSelect` (deriva el activo de su router). `footer` para cuenta/tema.
+- Zonas fijas del rail: `brand` (arriba) y `footer` (abajo) no se mueven nunca. Cada ítem decide con `pinned`:
+  `"start"` lo fija arriba bajo la marca, `"end"` abajo sobre el footer, y sin `pinned` va a la zona del medio, la
+  única que scrollea cuando no entra en el alto (en móvil, la barra inferior scrollea de costado con las fijas en
+  los extremos). Los divisores (`{ separator: true, pinned }`) siguen la misma regla.
+
+  ```tsx
+  <KapiRail
+    brand="S"
+    items={[
+      { id: "inicio", label: "Inicio", icon: <Home size={21} />, pinned: "start" },
+      { id: "tramites", label: "Trámites", icon: <Inbox size={21} /> },
+      { id: "config", label: "Configuración", icon: <Settings size={21} />, pinned: "end" }
+    ]}
+    activeId={activeId}
+    onSelect={go}
+    footer={<AccountButton />}
+  />
+  ```
+
+- `KapiContextSlot`: plegable. Controlado (`open`/`onOpenChange`) o no (`defaultOpen`; por defecto abierto en desktop y cerrado en móvil).
+  Animación: el ancho colapsa 258px ↔ 44px (`.kapi-ctxslot`), el panel entra con `kapi-slide-in`.
+- `contextMenuItems` en `KapiShell` habilita el menú del sistema (doble click derecho). El arrastre con click derecho scrollea siempre.
+- Avisos de atención (vencimientos, pendientes): `KapiRailItem`, `KapiPanelItem`, los ítems de
+  `KapiContextSections` y `KapiPanelGroup` (cabecera y subítems) aceptan `badge` (número o `"dot"`), `badgeTone`
+  (variantes de `KapiBadge`: `danger` para vencidos, `warning` para por vencer) y `badgeLabel` (lo que lee un lector
+  de pantalla: "3 trámites vencidos"). Un 0 no dibuja nada; en el rail es una burbuja sobre el ícono (tope "99+") y
+  en los paneles va al final (tope "999+"). En `KapiPanelGroup` convive con `count`, que es el total neutro. La
+  pieza suelta es `KapiNavBadge`.
+- Integración de los avisos: el rail y el panel son presentacionales, ninguna vista los muta. Los avisos salen de
+  una sola fuente compartida (un hook o store al nivel del shell que lee el backend) y los ítems se derivan de ella,
+  igual que `activeId` sale del router. Una vista que resuelve algo cambia esa fuente (o invalida su consulta) y la
+  navegación se recalcula sola:
+
+  ```tsx
+  const avisos = useAvisos(); // { tramites: { demorados: 3 } }, del backend, compartido por contexto
+  const items = BASE_ITEMS.map((i) =>
+    i.id === "tramites"
+      ? {
+          ...i,
+          badge: avisos.tramites.demorados,
+          badgeTone: "danger",
+          badgeLabel: `${avisos.tramites.demorados} vencidos`
+        }
+      : i
+  );
+  ```
+
+  Ejemplo armado en el demo de Trámites (`demo/views/screens/tramites/avisos.ts`): el rail, el panel y "Mi
+  trabajo" muestran el mismo número.
+
+- Panel plegado en modo mini: `KapiContextSlot` y `KapiContextPanel` aceptan `collapsedMode="mini"` (default
+  `"hidden"`). Plegado en desktop, el panel queda como una tira de íconos: cada `KapiPanelItem`, ítem de
+  `KapiContextSections` y cabecera de `KapiPanelGroup` muestra sólo su ícono (o sus iniciales, o la inicial de la
+  etiqueta), el aviso como burbuja en la esquina y un tooltip con el título y el aviso al pasar el mouse o llegar con
+  Tab. El clic navega sin desplegar; la cabecera de un grupo despliega el panel y abre el grupo. Se ocultan el
+  título, las etiquetas de sección, el buscador, la ayuda y el contenido propio de la app (lo que no sea una pieza
+  de navegación de kapi). Un componente propio dentro del panel puede leer el estado con `useKapiPanelMini()`. En
+  móvil el panel sigue siendo un drawer.
+
+  ```tsx
+  <KapiContextSlot title="Trámites" collapsedMode="mini">
+    <KapiPanelList>
+      <KapiPanelItem icon={<Inbox size={15} />} badge={22} badgeLabel="22 esperando tu acción">
+        Mi trabajo
+      </KapiPanelItem>
+    </KapiPanelList>
+  </KapiContextSlot>
+  ```
+
+- Responsive: ≤ 1024px reduce padding; ≤ 768px el rail pasa a barra inferior y el panel a drawer con backdrop
+  (botón flotante para reabrirlo). Sin rail el drawer funciona igual. Breakpoint en `shell.css` y `SHELL_MOBILE_QUERY`.
+
+## Selección e ids tipados
+
+- Estado controlado con nombre: `X` / `defaultX` / `onXChange(x)` (`KapiTree`: `selected`/`onSelectedChange`,
+  `expanded`/`onExpandedChange`; `KapiTable`: `selectedIds`/`onSelectedIdsChange`,
+  `expandedIds`/`onExpandedIdsChange`; `KapiAccordion`: `openIds`/`defaultOpenIds`/`onOpenIdsChange`).
+- El valor principal de un control de elección es `value` / `onChange(value)` (`KapiTabs`, `KapiSegmented`,
+  `KapiFilterChips`, `KapiSelect`…).
+- Las listas de navegación reciben `activeId` + `onSelect(id)` (`KapiRail`, `KapiPanelGroup`,
+  `KapiContextPanel`): la app es dueña del activo, normalmente desde el router.
+- Los ids son genéricos y se infieren de los ítems: con un setter tipado, un id ajeno no compila.
+
+```tsx
+type View = "list" | "grid";
+const tabs: KapiTabItem<View>[] = [
+  { id: "list", label: "Lista" },
+  { id: "grid", label: "Grilla" }
+];
+const [view, setView] = useState<View>("list");
+
+<KapiTabs tabs={tabs} value={view} onChange={setView} aria-label="Vista" />;
+
+// `data` vuelve tipado en los callbacks del árbol.
+const nodes: KapiTreeNode<{ code: number }>[] = [{ id: "fcye", label: "FCyE", data: { code: 12 } }];
+<KapiTree nodes={nodes} onSelectedChange={(ids, node) => console.log(ids, node.data?.code)} />;
+
+// Sin `render`, `key` tiene que ser una propiedad de la fila.
+type Persona = { id: number; nombre: string };
+const columns: KapiTableColumn<Persona>[] = [
+  { key: "nombre", label: "Nombre" },
+  { key: "acciones", label: "", render: (p) => <KapiButton>Ver {p.nombre}</KapiButton> }
+];
+```
+
+## Diálogos imperativos
+
+Para el flujo "preguntar y seguir" (lo que en otros sistemas resuelve SweetAlert) no hace falta estado
+`open` en cada pantalla: monta `KapiDialogHost` una vez (junto a `KapiToastContainer`) y llama a las
+funciones desde cualquier handler.
+
+```tsx
+import { KapiDialogHost, kapiAlert, kapiCloseDialogs, kapiConfirm, kapiLoading } from "@kapiuara/ui";
+
+// Una vez, en la raíz de la app (dentro de `.kapi`):
+<KapiDialogHost />;
+
+const eliminar = async (persona: Persona) => {
+  if (!(await kapiConfirm({ title: `¿Eliminar a ${persona.nombre}?`, message: "No se puede deshacer." })))
+    return;
+  await kapiLoading.run(api.eliminar(persona.id), "Eliminando…");
+  await kapiAlert({ title: "Eliminado", variant: "success" });
+};
+```
+
+- `kapiConfirm(options)` → `Promise<boolean>`: `true` al confirmar, `false` ante Cancelar, X, Escape o fondo.
+  Mismas opciones que `KapiConfirm` (`title`, `message`, `variant` `danger` · `warning` · `success` · `info` ·
+  `question`, `confirmLabel`, `cancelLabel`).
+- `onConfirm` (opcional, en `kapiConfirm`): acción que corre al confirmar, como `preConfirm` de SweetAlert. Mientras
+  corre, el botón de confirmar muestra un spinner, los dos botones quedan deshabilitados y Escape/fondo/X no cierran.
+  Si resuelve, el diálogo se cierra y la promesa da `true`; si rechaza, el diálogo sigue abierto con el error adentro
+  (`role="alert"`: `error.message`, o `labels.error` de `confirm`, "No se pudo completar la acción") y se puede
+  reintentar o cancelar (`false`). Un rechazo que no es `Error` ni string muestra el texto por defecto. La promesa
+  tiene que terminar: mientras corre no hay forma de cerrar el diálogo; `kapiCloseDialogs()` lo cierra igual
+  (resuelve `false`) pero la acción ya iniciada sigue.
+
+```tsx
+const ok = await kapiConfirm({
+  title: "¿Enviar la solicitud?",
+  variant: "question",
+  onConfirm: () => api.enviar(solicitud) // si falla, el mensaje queda en el diálogo
+});
+```
+
+- `kapiAlert(options)` → `Promise<void>`: aviso con un solo botón (`title`, `message`, `variant` `success` ·
+  `error` · `info` · `warning`, `acceptLabel`, default `labels.accept`: "Aceptar").
+- `kapiLoading(message?)` → `{ update, close }`: carga bloqueante (sin Escape ni fondo). Varias abiertas a la vez
+  se muestran como una sola con el mensaje de la más reciente. `kapiLoading.run(promesa | fn, message?)` la cierra
+  en el `finally`.
+- Abrir una confirmación o un aviso **cierra las cargas abiertas con `kapiLoading()`** (como SweetAlert, que muestra
+  uno por vez): `kapiLoading(); api().then(() => kapiAlert({ variant: "success", … }))` no deja ninguna carga
+  detrás, y los handles de esas cargas quedan sin efecto. La de `kapiLoading.run` no se cierra (la cierra su
+  `finally`): se oculta mientras haya un diálogo y vuelve al responderlo, así
+  `kapiLoading.run(async () => { if (await kapiConfirm(…)) await guardar(); })` sigue cubriendo `guardar()`.
+  Toda carga abierta con un diálogo visible tampoco se dibuja (quedaría encima y no se podría responder): aparece
+  al vaciarse la cola.
+- `kapiCloseDialogs()`: cierra todo. Resuelve los diálogos en cola como cerrados (`kapiConfirm` → `false`,
+  `kapiAlert` → `undefined`) y cierra todas las cargas (p. ej. al cambiar de ruta o cerrar sesión).
+- Las confirmaciones y avisos se encolan y se muestran de a uno; los pedidos hechos antes de montar el host esperan.
+  Si se encola sin ningún host montado, la consola avisa una vez (`console.warn`) para que la promesa no quede
+  colgada en silencio.
+- Textos: clave `dialog` (`accept`, `loading`) y, para la confirmación, la clave `confirm` de `KapiConfirm`.
+
+## Select async y creatable
+
+`KapiSelect` cubre los modos de react-select sin dependencias: grupos (`{ label, options }`), búsqueda remota y
+creación de opciones.
+
+```tsx
+<KapiSelect
+  aria-label="Ciudad"
+  value={ciudad}
+  onChange={setCiudad}
+  loadOptions={(query, { signal }) => api.ciudades(query, { signal })}
+/>
+
+<KapiSelect multiple value={tags} onChange={setTags} options={opciones} onCreate={(text) => crearTag(text)} />
+```
+
+- `loadOptions(query, { signal })`: se llama tras `loadDelay` ms sin tipear (default 300); el pedido anterior se
+  aborta y una respuesta vieja nunca pisa a una nueva. `options` pasa a ser la lista inicial (query vacía). Si falla
+  (rechazo o `throw`), el menú muestra `labels.loadError`; al cerrar y reabrir se vuelve a cargar.
+- Los resultados quedan asociados a su búsqueda: pasar otra identidad de `loadOptions` (p. ej. una función inline)
+  no los invalida ni recarga. Para forzar una recarga, remonta el select con otra `key`.
+- Las opciones elegidas conservan su label aunque ya no estén en la lista cargada.
+- `onCreate(text)`: ofrece `Crear "texto"` cuando ninguna opción coincide exactamente. Si devuelve (o resuelve) una
+  opción, queda elegida; si no devuelve nada, el padre actualiza `options`/`value`. Mientras una promesa de
+  `onCreate` corre, la fila se oculta (no hay duplicados) y el control queda `aria-busy`; lo tipeado mientras tanto se
+  conserva. Si la promesa se rechaza, el menú muestra `labels.createError` y se puede reintentar.
+
+## Archivos: visor y descarga
+
+`KapiFileViewer` muestra un archivo a partir de una URL o de un Blob (la respuesta de una API), sin dependencias:
+
+```tsx
+<KapiFileViewer src={blob} fileName="constancia.pdf" />
+<KapiFileViewer src="/archivos/foto.jpg" title="Foto del DNI" height="240px" />
+```
+
+- PDF → `<object>`; si el navegador no tiene visor (p. ej. en móviles) se ve un aviso con la descarga. Imágenes →
+  `<img>` (alt = `title` o el nombre); texto plano y JSON → `<iframe sandbox>`; el resto (CSV, Excel, ZIP…) → una
+  tarjeta con el nombre y el botón de descarga.
+- El tipo sale de `type`, del tipo del Blob o de la extensión del nombre/URL. Un Blob recibe una URL temporal que se
+  revoca al cambiarlo o al desmontar. `downloadable={false}` quita la descarga; con una URL hay además un enlace
+  para abrirla en otra pestaña. Textos: clave `fileViewer`.
+- Solo acepta URLs relativas, `http(s):`, `blob:` o `data:` de imagen/PDF; otra (`javascript:`…) muestra el aviso
+  sin enlaces. El PDF por URL va en un `<object>` sin sandbox: si la URL es del mismo origen y el servidor devuelve
+  HTML (un archivo subido con un Content-Type errado), ese HTML corre en el origen de la app. Para archivos subidos
+  por usuarios, pasa un Blob con su `type`.
+
+Para descargar sin mostrar, los helpers de `hooks` reemplazan a `file-saver` y al `<a download>` manual:
+
+```ts
+const res = await fetch(url);
+const name = fileNameFromContentDisposition(res.headers.get("Content-Disposition")) ?? "reporte.xlsx";
+downloadBlob(await res.blob(), name);
+```
+
+`fileNameFromContentDisposition` sigue la RFC 6266 (`filename*=UTF-8''…` gana sobre `filename`) y descarta rutas;
+`fileKind(mimeOrName)` devuelve `"pdf" | "image" | "text" | "other"`; `useObjectUrl(blob)` devuelve una URL temporal
+para usar en tu propio markup.
+
+### Adjuntos en lista
+
+`KapiFileList` (`<ul>`) y `KapiFileItem` (`<li>`) muestran una fila por adjunto: ícono según el tipo (MIME o
+extensión), nombre recortado, metadatos («detalles · tamaño · fecha»), un `status` (badge) y `actions`. Con
+`onOpen`, el nombre es un botón (p. ej. para abrir la previa en un `KapiFileViewer`).
+
+```tsx
+<KapiFileList aria-label="Adjuntos">
+  <KapiFileItem
+    name="nota.pdf"
+    size={248320}
+    date={fecha}
+    details={["Nota", "Ana Pérez"]}
+    status={
+      <KapiBadge variant="success" size="sm">
+        Verificado
+      </KapiBadge>
+    }
+    onOpen={verPrevia}
+    actions={<KapiIconButton aria-label="Descargar nota.pdf" icon={<Download />} />}
+  />
+</KapiFileList>
+```
+
+Formateo sin dependencias (en `hooks`): `formatFileSize(1536)` → "1,5 KB" (base 1024, un decimal como máximo);
+`formatRelativeTime(fecha, ahora?, locale?)` → "hace 5 minutos" (trunca, nunca "hace 60 minutos");
+`formatDate(fecha)` → "12 mar 2026"; `isoDateTime(fecha)` da el valor de `<time dateTime>`. Una fecha inválida
+devuelve "" (o `null` en `isoDateTime`).
+
+## Comentarios
+
+`KapiComment` es un comentario de un hilo: avatar, autor, fecha relativa (con la fecha completa en el `title`),
+`body`, `meta` («editado»), `actions` y respuestas como `children` (se indentan un solo nivel). `now` fija la hora
+de referencia. `KapiCommentComposer` es la caja para escribir: `onSubmit(texto)` recibe el texto recortado (si devuelve una promesa, el compositor queda ocupado y se vacía solo si resuelve: un rechazo conserva el borrador),
+Ctrl/⌘ + Enter envía, Enter solo agrega un salto de línea y el botón queda deshabilitado con el texto vacío. Cumple
+el contrato de campo (`name`, `onBlur`, `ref` al textarea, `invalid`/`required`); textos en la clave
+`commentComposer`.
+
+```tsx
+<KapiComment author="Ana Pérez" date={fecha} body="Falta la firma." meta="editado">
+  <KapiComment author="Bruno Díaz" date={otra} body="Ya la pedí." />
+</KapiComment>
+<KapiCommentComposer onSubmit={(texto) => agregar(texto)} />
+```
+
+### Toasts con acción
+
+`kapiToast.success|error|info|warning(mensaje, opciones?)` acepta `{ duration, action: { label, onClick } }`
+(sigue aceptando un número como duración). La acción es un botón dentro del toast: ejecuta y lo cierra, sin mover
+el foco. Con acción y sin `duration`, el toast dura 6 s (`TOAST_ACTION_DURATION`).
+
+```ts
+kapiToast.success("Trámite creado", { action: { label: "Ver trámite", onClick: () => abrir(id) } });
+```
+
+## Campana de notificaciones
+
+`KapiNotificationBell` (layout) es la campana de la barra superior: badge con las no leídas y un panel con la
+lista. Los datos y el "leído" son de la app; la campana solo avisa.
+
+```tsx
+<KapiNotificationBell
+  items={notificaciones} // { id, title, description?, date?, read?, icon?, href? }
+  onItemSelect={(item) => marcarLeida(item.id)}
+  onMarkAllRead={marcarTodas}
+  onViewAll={() => navigate("/notificaciones")}
+  loading={cargando}
+/>
+```
+
+- Todo ítem sin `read: true` cuenta como no leído: va resaltado y suma al badge (`max`, default 9, muestra "9+").
+  El nombre accesible de la campana lleva el conteo real: "Notificaciones, 3 sin leer".
+- `date` (`Date` o ISO) se muestra relativa con `Intl.RelativeTimeFormat` ("hace 5 minutos", "ayer") en el
+  `locale` del provider (`es` sin provider).
+- Un ítem con `href` es un enlace; `onItemSelect(item, event)` recibe el evento para hacer `preventDefault` y
+  navegar con el router. Elegir un ítem o "Ver todas" cierra el panel.
+- Teclado: al abrir enfoca la primera notificación; flechas, Home y End recorren la lista; Escape cierra y devuelve
+  el foco a la campana. Apertura `open`/`defaultOpen`/`onOpenChange`. Textos: clave `notificationBell`.
+
+## Pasos de un circuito
+
+`KapiSteps` muestra el avance de un circuito de solo lectura (por ejemplo, los estados de un trámite). Para un
+formulario por pasos usa `KapiWizard`. Con `current`, los pasos anteriores quedan completos y los siguientes
+pendientes; un `status` explícito (`complete` · `current` · `upcoming` · `error`) siempre gana. El paso actual lleva
+`aria-current="step"` y cada estado se anuncia con un texto oculto (clave de textos `steps`). En horizontal se
+acomoda en varias líneas si no entra.
+
+```tsx
+<KapiSteps
+  aria-label="Circuito del trámite"
+  current="revision"
+  steps={[
+    { id: "iniciado", label: "Iniciado", description: "Mesa de Entradas" },
+    { id: "revision", label: "En revisión" },
+    { id: "firma", label: "A la firma" }
+  ]}
+/>
+```
+
+## Menús, pestañas y modales
+
+- **Ítem de menú deshabilitado:** `disabled` en un `KapiMenuItem` lo atenúa, lo anuncia con `aria-disabled`, no
+  ejecuta su acción y las flechas lo saltean. Vale para `KapiMenuButton`, `KapiContextMenu` y el menú de fila de
+  `KapiTable`.
+- **Contador en pestañas:** `count` en un `KapiTabItem` muestra una píldora tras el label (también el `0`); el
+  nombre accesible queda «Adjuntos 3».
+- **Nombre accesible de modales:** `KapiModal` y `KapiSplitModal` aceptan `aria-label` y `aria-labelledby`
+  nativos, que van al `<dialog>`. Precedencia: `aria-labelledby` > `aria-label` > título visible.
+
+```tsx
+<KapiMenuButton
+  label="Acciones"
+  items={[
+    { label: "Derivar", onClick: derivar },
+    { label: "Anular", disabled: !puedeAnular, onClick: anular }
+  ]}
+/>
+<KapiTabs
+  aria-label="Secciones"
+  value={tab}
+  onChange={setTab}
+  tabs={[{ id: "datos", label: "Datos" }, { id: "adjuntos", label: "Adjuntos", count: 3 }]}
+/>
+```
+
+## Búsqueda facetada y tabla paginada en el cliente
+
+`KapiFacetedSearch` se maneja con `chips` y el `apply` de cada faceta. Cada opción puede mostrar cuántos
+resultados tiene con `count` («Pendiente, 4»). Una faceta `kind: "dateRange"` pide desde/hasta en un solo
+calendario y entrega `yyyy-mm-dd/yyyy-mm-dd` (se lee con `parseDateRangeValue`). Con `onClearAll`, la barra
+muestra «Limpiar todo» mientras haya filtros activos.
+
+```tsx
+const facets: KapiFacet[] = [
+  {
+    key: "estado",
+    label: "Estado",
+    kind: "list",
+    options: [{ value: "pend", label: "Pendiente", count: 4 }],
+    apply: (v) => set({ estado: v })
+  },
+  { key: "creado", label: "Creado", kind: "dateRange", apply: (v) => set({ creado: parseDateRangeValue(v) }) }
+];
+<KapiFacetedSearch facets={facets} chips={chips} onText={(t) => set({ texto: t })} onClearAll={limpiar} />;
+```
+
+La `pagination` de `KapiTable` solo dibuja el pie: los datos los recorta quien la usa (sirve igual para paginar
+en el servidor). Para paginar en el cliente, `sortRowsByColumn` ordena con la misma lógica que la tabla y
+`paginateRows` recorta la página. `exportCsv.rows` (arreglo o función) exporta el conjunto completo, no solo la
+página visible.
+
+```tsx
+const ordenadas = sortRowsByColumn(filas, columnas, sort);
+<KapiTable
+  columns={columnas}
+  rows={paginateRows(ordenadas, page, pageSize)}
+  manualSort
+  sort={sort}
+  onSortChange={setSort}
+  exportCsv={{ fileName: "tramites.csv", rows: () => ordenadas }}
+  pagination={{ page, pageSize, total: filas.length, onPageChange: setPage }}
+/>;
+```
+
+## Tarjetas radio y atajos de teclado
+
+`KapiCheckCard type="radio"` es un radio nativo con forma de tarjeta: las que comparten `name` forman un grupo y
+las flechas mueven la elección. `KapiInput shortcut="/"` muestra la tecla como `<kbd>` mientras el campo está
+vacío y la anuncia con `aria-keyshortcuts`; la tecla la registra la app (por ejemplo con `useHotkey`).
+
+```tsx
+<div role="radiogroup" aria-label="Tipo de trámite">
+  {tipos.map((t) => (
+    <KapiCheckCard
+      key={t.id}
+      type="radio"
+      name="tipo"
+      value={t.id}
+      label={t.nombre}
+      checked={tipo === t.id}
+      onChange={(e) => setTipo(e.target.value)}
+    />
+  ))}
+</div>;
+
+const ref = useRef<HTMLInputElement>(null);
+useHotkey("/", () => ref.current?.focus());
+<KapiInput ref={ref} type="search" aria-label="Buscar" shortcut="/" clearable />;
+```
+
+`KapiNotificationBell now={fecha}` fija la hora de referencia de las fechas relativas (tests y capturas).
+`KapiPanelItem icon={<Inbox size={15} />}` suma un ícono decorativo antes del texto.
+
+## Tema y color de marca
+
+Todos los colores salen de tokens `--kapi-*` en `.kapi`; el tema oscuro es `data-theme="dark"` en esa
+raíz. Para usar el color de la marca alcanza con un solo token, `--kapi-primary`:
+
+```tsx
+const { setAccent } = useKapiThemeState(); // KapiShell lo aplica en su raíz (y lo guarda en kapi:accent)
+setAccent("#0f766e");
+```
+
+```css
+.kapi {
+  --kapi-primary: #0f766e;
+} /* o directo en CSS, sobre la misma raíz */
+```
+
+- `--kapi-primary-ink` (texto), `--kapi-primary-soft` / `--kapi-primary-bg` (fondos tonales),
+  `--kapi-primary-border`, el anillo de foco `--kapi-ring` y las sombras teñidas (`--kapi-shadow-primary`,
+  `-fab`, `-shape`…) se derivan de `--kapi-primary` con `color-mix`, en claro y en oscuro: no hace falta
+  pisarlos. Con el violeta por defecto se ven igual que antes.
+- `--kapi-primary-fg` (texto sobre el primario) no se deriva: si el acento es claro, pisalo con un color
+  oscuro para mantener el contraste.
+- Los derivados se resuelven en `.kapi`: redefinir `--kapi-primary` en un elemento interno no los
+  recolorea. El acento va en la raíz.
+- Un mismo acento sirve para los dos temas; para afinar el oscuro, redefiní `--kapi-primary` en
+  `.kapi[data-theme="dark"]`.
+
+## Preferencias guardadas (namespace)
+
+Las preferencias del design system van a `localStorage` con namespace: `kapi:theme`, `kapi:accent`, `kapi:font`,
+`kapi:motion` y `kapi:tour-seen`. Si dos apps del design system comparten origen, cada una pasa el suyo para no pisarse:
+
+```tsx
+<KapiShell storageNamespace="tramites">…</KapiShell>          // tramites:theme, tramites:font…
+useKapiThemeState({ namespace: "tramites" });                 // si armás tu propia raíz
+<KapiTour markSeen="tramites:tour-seen" … />
+usePersistentState("table-cols", {}, { namespace: "tramites" }); // tramites:table-cols
+```
+
+- Las claves viejas sin prefijo (`v2_theme`, `v2_accent`, `v2_font`, `v2_motion`, `v2_tour_seen`) se migran solas en la
+  primera lectura (se copian a la clave nueva y se borran): nadie pierde su tema.
+- `usePersistentState` sin `namespace` sigue usando la clave tal cual (compatible con lo ya guardado).
+
+## Sin conexión
+
+`useOnlineStatus()` devuelve `{ online, since }` (eventos `online`/`offline` de la ventana; en SSR, conectado).
+`KapiOfflineBanner` lo usa para mostrar un aviso flotante mientras no hay conexión y uno breve al volver;
+con conexión no renderiza nada. Textos por `labels`, `forceOffline` para simular o para una verificación propia.
+
+```tsx
+<KapiShell overlays={<KapiOfflineBanner />}>…</KapiShell>
+```
+
+## Formularios
+
+El DS no trae motor de validación: la validación es del host (react-hook-form o estado propio). Lo que
+garantiza es un **contrato de campo** común, para cablear cualquier control sin adaptadores:
+
+- `name`: llega al envío nativo del `<form>`. Los controles nativos lo llevan en su `<input>`; los de
+  valor que no lo son (`KapiSegmented`, `KapiRating`, `KapiSelect`) renderizan un `<input type="hidden">`.
+- `onBlur` y `ref` al elemento enfocable (para que la librería marque `touched` y enfoque el primer error).
+- `invalid`/`required` por prop o desde el `KapiField` que envuelve al control. Precedencia: `aria-*`
+  propios > prop > `KapiField`. Los inputs de texto (`KapiInput`, `KapiTextarea`, `KapiAutocomplete`)
+  usan `status="err"` en vez de `invalid`; `KapiSelect`, `KapiDatePicker` y `KapiDateRangePicker` toman
+  el estado solo del `KapiField`.
+- `onChange`: los wrappers nativos (`KapiInput`, `KapiTextarea`, `KapiCheckbox`, `KapiSwitch`, `KapiRadio`)
+  pasan el evento; los de valor (`KapiSelect`, `KapiDatePicker`, `KapiSlider`, `KapiSegmented`,
+  `KapiRating`, `KapiFileUpload`) pasan el valor ya tipado.
+
+### `KapiField`
+
+Envuelve un control y le conecta label, ayuda y estado sin cablear ids: el control toma del contexto su id
+(o `aria-labelledby` si no es etiquetable), `aria-describedby` hacia la ayuda, `aria-invalid` con
+`status="err"` y `aria-required` con `required`.
+
+```tsx
+<KapiField label="Turno" help="Elige un turno" status="err" required>
+  <KapiSegmented name="turno" items={turnos} value={turno} onChange={setTurno} />
+</KapiField>
+```
+
+Los radios sueltos dentro de un `KapiField` toman ayuda e `invalid`, pero no el id (un grupo comparte el
+campo): cada uno se nombra con su `label`.
+
+### Con react-hook-form
+
+`react-hook-form` no es dependencia del DS; estos son los dos patrones del lado del host.
+
+**Wrappers nativos → `register`.** `register` devuelve `name`, `onChange(event)`, `onBlur` y `ref`, que es
+justo lo que aceptan:
+
+```tsx
+const { register, formState: { errors } } = useForm<Alta>();
+
+<KapiField label="Email" help={errors.email?.message} status={errors.email ? "err" : undefined} required>
+  <KapiInput type="email" {...register("email", { required: "Ingresa tu email" })} />
+</KapiField>
+
+<KapiField label="Acepto los términos" help={errors.terms?.message} status={errors.terms ? "err" : undefined}>
+  <KapiCheckbox {...register("terms", { required: "Tienes que aceptarlos" })} />
+</KapiField>
+```
+
+**Controles de valor → `Controller`.** Se mapea `field` (`value`, `onChange`, `onBlur`, `ref`, `name`) y
+`fieldState.error` al `KapiField`:
+
+```tsx
+<Controller
+  control={control}
+  name="sede"
+  rules={{ required: "Elige una sede" }}
+  render={({ field, fieldState }) => (
+    <KapiField label="Sede" help={fieldState.error?.message} status={fieldState.error ? "err" : undefined} required>
+      <KapiSelect
+        name={field.name}
+        ref={field.ref}
+        value={field.value ?? null}
+        onChange={field.onChange}
+        options={sedes}
+      />
+    </KapiField>
+  )}
+/>
+
+<Controller
+  control={control}
+  name="volumen"
+  render={({ field, fieldState }) => (
+    <KapiField label="Volumen" help={fieldState.error?.message} status={fieldState.error ? "err" : undefined}>
+      <KapiSlider {...field} />
+    </KapiField>
+  )}
+/>
+```
+
+`KapiDatePicker` sigue el mismo molde que `KapiSelect` (`value: Date | null`). `onBlur` de `KapiSelect`,
+`KapiDatePicker` y `KapiDateRangePicker` se dispara solo cuando el foco sale del control: pasar a su menú
+o calendario no cuenta. `KapiFileUpload` sincroniza su `<input type="file">` con la lista vía
+`DataTransfer`; donde no exista, arma el `FormData` con lo que emite `onChange`.
+
+**Qué envía cada control con `name`** (inputs ocultos salvo los nativos):
+
+| Control                                     | Valor en el `FormData`                                                            |
+| ------------------------------------------- | --------------------------------------------------------------------------------- |
+| `KapiSelect`                                | el `value` elegido (vacío sin valor); con `multiple`, un input por valor          |
+| `KapiDatePicker`                            | `yyyy-mm-dd`, `hh:mm` o `yyyy-mm-ddThh:mm` según `mode` (como los inputs nativos) |
+| `KapiDateRangePicker`                       | `name.from` y `name.to`, cada uno `yyyy-mm-dd` (vacíos sin rango)                 |
+| `KapiSlider` / `KapiRating`                 | el número                                                                         |
+| `KapiSegmented`                             | el `id` elegido, siempre (no tiene `disabled`)                                    |
+| `KapiCheckbox` / `KapiSwitch` / `KapiRadio` | `value` (o `on`) solo si está marcado                                             |
+
+## Textos y locale
+
+Cada componente con copy propio trae defaults en español y acepta `labels` (parcial, por clave).
+`KapiLocaleProvider` pone el copy de toda una app en un solo lugar. Precedencia por clave:
+defaults del componente < provider < prop `labels`. Una clave en `undefined` no borra el valor anterior.
+Sin provider no cambia nada (costo cero).
+
+```tsx
+// Fuera del render, o memoizado: un objeto nuevo por render re-renderiza a todos.
+const EN: KapiLabelOverrides = {
+  pagination: { of: "of", nextPage: "Next page" },
+  calendar: { pickStart: "Pick a start date" } // lo comparten KapiDatePicker y KapiDateRangePicker
+};
+
+<KapiLocaleProvider locale="en" labels={EN}>
+  <App />
+</KapiLocaleProvider>;
+```
+
+- `link` es una clave compartida: el aviso "(se abre en una pestaña nueva)" de los enlaces con `newTab`
+  (`KapiPanelGroup`, `KapiContextPanel`, `KapiRail`, `KapiAccessCard`).
+- Las props de texto sueltas que ya existían (`cancelLabel` de `KapiWizard`, `label` de `KapiFab`, `aria-label`,
+  `invalidMessage` de `KapiCuitInput`…) siguen ganando sobre `labels` y el provider. En las de contenido
+  (`ReactNode`, como `emptyMessage` de `KapiTable` o `footerHint` de `KapiCommandPalette`) solo `undefined` cae
+  al provider: `null` no muestra nada.
+- `canvasForm` y `unsavedGuard` se configuran solo desde el provider (`KapiCanvasForm` ya usa `labels` para su
+  `KapiOffcanvas`; el hook tiene sus `options`).
+- Las claves están en `KapiLabelRegistry` (una `interface`: una app puede sumar las suyas por module augmentation).
+- `useLabels(key, defaults, labels)` resuelve los textos en un componente; `useKapiLocale()` devuelve el locale
+  (`undefined` = el del runtime). `KapiTable` lo usa para ordenar textos.
+- `KapiTable` le pasa sus textos ya resueltos a su barra de filtro: adentro de una tabla manda la clave `table`.
+- Fuera de alcance por ahora: la pluralización de `formatDuration` (countdown) sigue en español.
+
+## Fuente
+
+`src/styles/fonts.css` importa `@fontsource-variable/nunito` (familia `'Nunito Variable'`, token `--kapi-font`).
+El CSS de la librería NO la incluye (en modo lib Vite inlinea los woff2 en base64 → 240 kB): la app consumidora
+importa `@fontsource-variable/nunito` (o `fonts.css` desde el código fuente).
+
+- Es una `peerDependency` **opcional** (y `devDependency` para el demo): `@kapiuara/ui` no la instala. Para usar
+  Nunito, la app la agrega (`pnpm add @fontsource-variable/nunito`) y la importa una vez.
+- Sin ella, `--kapi-font` cae a `system-ui`. Otra fuente: cargarla en la app y pisar `--kapi-font` en la raíz
+  (`setFont` de `useKapiThemeState` elige entre las pilas predefinidas de `FONTS`).