kaizen-lib 0.2.5 → 0.2.6

package/README.md

@@ -12,7 +12,7 @@ styled-components con `moduleResolution: "bundler"`, así que lo transpilan ello
 |---|---|---|
 | `kaizen-lib/tokens` | Referencias `var(--kz-*)` tipadas | listo |
 | `kaizen-lib/tokens.css` | Valores por defecto, tema oscuro y claro | listo |
-| `kaizen-lib/ui` | Componentes (`IconButton`, `ReactionButton`, `Medidor`, `Relieve`, `LangSelector`) | en curso |
+| `kaizen-lib/ui` | Componentes (`IconButton`, `ReactionButton`, `Medidor`, `Relieve`, `LangSelector`, `Modal`) | en curso |
 
 ## ¿Qué uso para qué?
 
@@ -28,6 +28,7 @@ alcanza, extendé el componente en vez de bypassearlo (ver `implement.md` del ha
 | Un ícono que cambia de color al reaccionar (me gusta, guardar, favorito) — **sin** fondo teñido | `ReactionButton` | `IconButton` con `active` |
 | El relieve neumórfico (círculo con sombra, sin relleno) alrededor de un `IconButton` | `Relieve` envolviendo el `IconButton` | una prop de `IconButton` — ver por qué en su docblock |
 | Un ciclador de idioma con banderas en la topbar | `LangSelector` | reconstruir el ciclado a mano — ya lo resuelve, con `Relieve` incluido |
+| Un panel flotante que bloquea el resto de la página hasta que se resuelve (formulario, confirmación, contenido a pantalla completa) | `Modal` | un overlay propio — portal, foco atrapado, `Escape`, scroll bloqueado y anidamiento ya están resueltos ahí |
 | Un arco/medidor que muestra cuánto de un total está ocupado | `Medidor` | un `<progress>` o una barra propia |
 | Espaciado, radios, color, tipografía, sombra | `kaizen-lib/tokens` (`space`, `radius`, `fg`, `accent`, `font`, `shadow`, `relief`...) | un valor a mano — cada uno es una referencia `var(--kz-*)` |
 
@@ -217,6 +218,36 @@ English. Cambiar idioma"). `onChange` recibe el código de la opción siguiente;
 con eso (`i18n.changeLanguage`, `next-intl`, lo que sea) es del producto — la librería no
 sabe qué mecanismo de traducción hay atrás.
 
+```tsx
+import { Modal } from 'kaizen-lib/ui';
+
+<Modal
+  open={abierto}
+  onClose={cerrar}
+  title="Eliminar cepa"
+  description="Esta acción no se puede deshacer."
+  footer={<Acciones><Boton onClick={cerrar}>Cancelar</Boton><Boton onClick={eliminar}>Eliminar</Boton></Acciones>}
+>
+  <p>Se van a borrar también sus lotes asociados.</p>
+</Modal>
+```
+
+**`Modal`** es el shell único de un panel flotante: portalea a `document.body`, atrapa el
+foco y lo devuelve a quien lo abrió al cerrar, cierra con `Escape`/click afuera/la X, y
+bloquea el scroll del fondo. Lleva una pila interna para el anidamiento real (un modal de
+confirmación abierto encima de un formulario): sólo el de más arriba atiende `Escape`, y el
+scroll se libera recién cuando se cierra el último.
+
+Sin `title` no hay nombre accesible propio — pasá `ariaLabel`. `size` (`sm`|`md`|`lg`|`xl`)
+fija el ancho máximo del panel; `maxWidth` lo pisa con un valor explícito. `disableClose`
+bloquea la X, el overlay y `Escape` a la vez — para una operación en curso, no para "no
+quiero que cierre nunca". `dismissOnOverlay={false}` sólo desactiva el click afuera, para
+un formulario a medio llenar que sigue queriendo cerrar con la X o `Escape`.
+
+Lo que **no** trae: un `placement` lateral (drawer) y un padding compacto de cuerpo son
+casos de un solo consumidor cada uno (`components/ui/Dialog` de valle-verde) — se resuelven
+ahí con un wrapper local hasta que un segundo consumidor los pida acá.
+
 ## Desarrollo
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaizen-lib",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "Tokens y componentes compartidos entre los fronts de Kaizen.",
   "license": "MIT",
   "author": "Nicolás Sandobal",

package/src/tokens/defaults.css

@@ -139,6 +139,13 @@
      encendido). Lo que necesite otra es una animación, no una transición. */
   --kz-duration-fast: 120ms;
   --kz-ease: cubic-bezier(0.2, 0, 0, 1);
+
+  /* ---- Velo ---------------------------------------------------------------
+     Fondo del overlay de un `Modal`. Negro semitransparente en los dos temas
+     a propósito: no es una superficie de la escala (no tiene texto encima
+     directo, va detrás del panel) y un velo claro en tema claro no separa el
+     panel del contenido que tapa. */
+  --kz-scrim: rgba(0, 0, 0, 0.5);
 }
 
 /*

package/src/tokens/index.ts

@@ -57,6 +57,9 @@ export const hairline = {
 /** Anillo de foco. Elemento no textual: el mínimo de contraste es 3:1. */
 export const ring = 'var(--kz-ring)';
 
+/** Velo detrás del panel de un `Modal`. Va fijo, no cambia con el tema. */
+export const scrim = 'var(--kz-scrim)';
+
 /**
  * Acento de marca. `soft` es el fondo lavado de chips y estados
  * seleccionados; encima de `soft` va el acento mismo, no `fg`.

package/src/ui/Modal.tsx

@@ -0,0 +1,342 @@
+'use client';
+
+import { useEffect, useId, useRef, useState } from 'react';
+import type { KeyboardEvent as ReactKeyboardEvent, MouseEvent as ReactMouseEvent, ReactNode } from 'react';
+import { createPortal } from 'react-dom';
+import styled, { css } from 'styled-components';
+import { fg, font, radius, ring, scrim, shadow, space, surface } from '../tokens';
+
+/** Anchos del panel. `maxWidth` los pisa cuando un modal necesita otra medida. */
+const ANCHOS = {
+  sm: '420px',
+  md: '560px',
+  lg: '760px',
+  xl: '980px',
+} as const;
+
+export type ModalSize = keyof typeof ANCHOS;
+
+const FOCUSABLE = [
+  'a[href]',
+  'button:not([disabled])',
+  'textarea:not([disabled])',
+  'input:not([disabled]):not([type="hidden"])',
+  'select:not([disabled])',
+  '[tabindex]:not([tabindex="-1"])',
+].join(',');
+
+/**
+ * El contenido de un modal suele ser condicional (pasos, listas que cargan por
+ * fetch), así que se recalcula en cada Tab en vez de cachearse al montar — con
+ * eso cacheado el trap queda desincronizado apenas cambia el cuerpo.
+ */
+const focusablesDe = (root: HTMLElement): HTMLElement[] =>
+  Array.from(root.querySelectorAll<HTMLElement>(FOCUSABLE)).filter(
+    (el) => !el.hasAttribute('hidden') && el.getAttribute('aria-hidden') !== 'true',
+  );
+
+/**
+ * Pila de modales abiertos. Hace falta por el anidamiento real (un modal de
+ * confirmación abierto encima de un formulario): sólo el de más arriba
+ * atiende `Escape`, y el scroll del fondo se libera cuando se cierra el
+ * último, no el primero que se desmonte.
+ */
+const pila: string[] = [];
+let overflowPrevio: string | null = null;
+
+const bloquearScroll = () => {
+  if (pila.length === 1 && typeof document !== 'undefined') {
+    overflowPrevio = document.body.style.overflow;
+    document.body.style.overflow = 'hidden';
+  }
+};
+
+const liberarScroll = () => {
+  if (pila.length === 0 && typeof document !== 'undefined') {
+    document.body.style.overflow = overflowPrevio ?? '';
+    overflowPrevio = null;
+  }
+};
+
+const Overlay = styled.div`
+  position: fixed;
+  inset: 0;
+  z-index: 2147483000;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: ${space[4]};
+  background: ${scrim};
+`;
+
+const Panel = styled.div<{ $maxWidth: string }>`
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  max-width: ${({ $maxWidth }) => $maxWidth};
+  max-height: 90vh;
+  background: ${surface[3]};
+  color: ${fg.DEFAULT};
+  /* Portalea a document.body, fuera de cualquier contenedor con su propia
+     tipografía — sin esto hereda la fuente del body, no la del producto. */
+  font-family: ${font.family};
+  border-radius: ${radius.lg};
+  box-shadow: ${shadow.xl};
+  outline: none;
+`;
+
+const Header = styled.header<{ $conCierre: boolean }>`
+  display: flex;
+  align-items: flex-start;
+  padding: ${space[6]} ${space[6]} ${space[4]};
+  ${({ $conCierre }) => $conCierre && css`padding-right: ${space[10]};`}
+`;
+
+const Titulos = styled.div`
+  min-width: 0;
+`;
+
+const Titulo = styled.h2`
+  margin: 0;
+  font-size: ${font.lg};
+  font-weight: 600;
+  line-height: 1.3;
+  color: ${fg.DEFAULT};
+`;
+
+const Descripcion = styled.p`
+  margin: ${space[1]} 0 0;
+  font-size: ${font.sm};
+  color: ${fg.muted};
+`;
+
+const Body = styled.div<{ $flush: boolean }>`
+  flex: 1 1 auto;
+  min-height: 0;
+  overflow-y: auto;
+  padding: ${({ $flush }) => ($flush ? space[6] : `0 ${space[6]} ${space[2]}`)};
+`;
+
+const Footer = styled.footer`
+  flex: 0 0 auto;
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  gap: ${space[3]};
+  padding: ${space[4]} ${space[6]} ${space[6]};
+`;
+
+const Cerrar = styled.button`
+  position: absolute;
+  top: ${space[3]};
+  right: ${space[3]};
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 32px;
+  height: 32px;
+  padding: 0;
+  border: none;
+  border-radius: ${radius.sm};
+  background: none;
+  color: ${fg.muted};
+  font-size: 1.25rem;
+  line-height: 1;
+  cursor: pointer;
+
+  &:hover:not(:disabled) {
+    background: ${surface.hover};
+    color: ${fg.DEFAULT};
+  }
+
+  &:focus-visible {
+    outline: 2px solid ${ring};
+    outline-offset: 2px;
+  }
+
+  &:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+`;
+
+type Props = {
+  open: boolean;
+  onClose: () => void;
+  /** Título visible, y nombre accesible cuando no se pasa `ariaLabel`. */
+  title?: ReactNode;
+  /** Subtítulo del encabezado. Sin `title` no se dibuja: es su acompañante. */
+  description?: ReactNode;
+  children: ReactNode;
+  /** Zona de acciones al pie. */
+  footer?: ReactNode;
+  size?: ModalSize;
+  /** Ancho máximo explícito (pisa `size`). */
+  maxWidth?: string;
+  /** Botón de cierre en la esquina. Default `true`. */
+  showClose?: boolean;
+  /** Click afuera del panel cierra. Default `true`. */
+  dismissOnOverlay?: boolean;
+  /** Operación en curso: ni la X, ni el overlay, ni Escape cierran. */
+  disableClose?: boolean;
+  /** Nombre accesible cuando no hay `title` visible. */
+  ariaLabel?: string;
+  className?: string;
+};
+
+/**
+ * Shell único de modal: portal a `document.body`, foco atrapado y devuelto,
+ * cierre por `Escape`/overlay/X, scroll de fondo bloqueado, pila para
+ * anidamiento real (un modal de confirmación sobre un formulario abierto).
+ *
+ * No escribas un overlay propio: si falta una variante, se agrega acá.
+ *
+ * ```tsx
+ * <Modal open={abierto} onClose={cerrar} title="Eliminar cepa" footer={<Acciones />}>
+ *   <p>Esta acción no se puede deshacer.</p>
+ * </Modal>
+ * ```
+ */
+export function Modal({
+  open,
+  onClose,
+  title,
+  description,
+  children,
+  footer,
+  size = 'md',
+  maxWidth,
+  showClose = true,
+  dismissOnOverlay = true,
+  disableClose = false,
+  ariaLabel,
+  className,
+}: Props) {
+  const panelRef = useRef<HTMLDivElement>(null);
+  const devolverFocoA = useRef<HTMLElement | null>(null);
+  const empezoEnOverlay = useRef(false);
+  const [mounted, setMounted] = useState(false);
+  const id = useId();
+  const tituloId = `${id}-titulo`;
+
+  useEffect(() => {
+    setMounted(true);
+  }, []);
+
+  useEffect(() => {
+    if (!open) return undefined;
+
+    devolverFocoA.current = document.activeElement as HTMLElement | null;
+    pila.push(id);
+    bloquearScroll();
+
+    return () => {
+      const i = pila.lastIndexOf(id);
+      if (i >= 0) pila.splice(i, 1);
+      liberarScroll();
+      devolverFocoA.current?.focus?.();
+    };
+  }, [open, id]);
+
+  useEffect(() => {
+    if (!open || !mounted) return;
+    const panel = panelRef.current;
+    if (!panel) return;
+    const [primero] = focusablesDe(panel);
+    (primero ?? panel).focus?.();
+  }, [open, mounted]);
+
+  useEffect(() => {
+    if (!open) return undefined;
+    const alTeclear = (event: KeyboardEvent) => {
+      if (event.key !== 'Escape') return;
+      if (pila[pila.length - 1] !== id) return;
+      if (disableClose) return;
+      event.stopPropagation();
+      onClose();
+    };
+    document.addEventListener('keydown', alTeclear, true);
+    return () => document.removeEventListener('keydown', alTeclear, true);
+  }, [open, id, disableClose, onClose]);
+
+  const manejarTab = (event: ReactKeyboardEvent<HTMLDivElement>) => {
+    if (event.key !== 'Tab') return;
+    const panel = panelRef.current;
+    if (!panel) return;
+    const focusables = focusablesDe(panel);
+    if (focusables.length === 0) {
+      event.preventDefault();
+      panel.focus();
+      return;
+    }
+    const primero = focusables[0] as HTMLElement;
+    const ultimo = focusables[focusables.length - 1] as HTMLElement;
+    const activo = document.activeElement;
+
+    if (event.shiftKey && (activo === primero || activo === panel || !panel.contains(activo))) {
+      event.preventDefault();
+      ultimo.focus();
+      return;
+    }
+    if (!event.shiftKey && (activo === ultimo || !panel.contains(activo))) {
+      event.preventDefault();
+      primero.focus();
+    }
+  };
+
+  /**
+   * Un click cuyo mousedown ocurrió dentro del panel (seleccionar texto y
+   * soltar afuera) burbujea igual hasta el overlay. Sólo cierra si el gesto
+   * *empezó* en el overlay.
+   */
+  const manejarClickOverlay = (event: ReactMouseEvent<HTMLDivElement>) => {
+    const empezoAfuera = empezoEnOverlay.current;
+    empezoEnOverlay.current = false;
+    if (!empezoAfuera || event.target !== event.currentTarget) return;
+    if (dismissOnOverlay && !disableClose) onClose();
+  };
+
+  if (!open || !mounted) return null;
+
+  return createPortal(
+    <Overlay
+      onMouseDown={(event) => {
+        empezoEnOverlay.current = event.target === event.currentTarget;
+      }}
+      onClick={manejarClickOverlay}
+    >
+      <Panel
+        ref={panelRef}
+        className={className}
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby={title ? tituloId : undefined}
+        aria-label={title ? undefined : ariaLabel}
+        tabIndex={-1}
+        $maxWidth={maxWidth ?? ANCHOS[size]}
+        onKeyDown={manejarTab}
+      >
+        {showClose ? (
+          <Cerrar type="button" onClick={onClose} disabled={disableClose} aria-label="Cerrar">
+            ×
+          </Cerrar>
+        ) : null}
+
+        {title ? (
+          <Header $conCierre={showClose}>
+            <Titulos>
+              <Titulo id={tituloId}>{title}</Titulo>
+              {description ? <Descripcion>{description}</Descripcion> : null}
+            </Titulos>
+          </Header>
+        ) : null}
+
+        <Body $flush={!title}>{children}</Body>
+
+        {footer ? <Footer>{footer}</Footer> : null}
+      </Panel>
+    </Overlay>,
+    document.body,
+  );
+}

package/src/ui/index.ts

@@ -7,3 +7,5 @@ export { ReactionButton } from './ReactionButton';
 export type { ReactionTone } from './ReactionButton';
 export { LangSelector } from './LangSelector';
 export type { OpcionDeIdioma } from './LangSelector';
+export { Modal } from './Modal';
+export type { ModalSize } from './Modal';