` con `id` (`mainId`, `content` por defecto) y `tabindex="-1"` —el destino de «saltar al contenido» del `TopBar` (`skipTo`)—, la cabecera se queda fija (`stickyHeader={false}` para que no), y la columna lateral se queda fija **justo debajo** de ella (mide su alto) con su propio desplazamiento si el menú es más alto que la ventana. **Pantalla estrecha** (menos de 48 rem): la columna pasa encima del contenido y deja de ser fija, salvo si es un `SideNav`: ese ya se queda en su carril de baldosas por debajo de 40 rem y sigue al lado del contenido, fijo y hasta abajo. Un menú que se esconde tras un botón necesita su propio panel (`Drawer`) y eso se monta fuera. **Teclado**: Tab recorre cabecera, columna y contenido en ese orden. Con un `TopBar` que lleve `skipTo`, el primer Tab ofrece «Saltar al contenido». **Aspecto fino**: `--amset-shell-sider-width` (16 rem; también con la prop `siderWidth`) y `--amset-shell-gap` (relleno del contenido). - `children` (obligatoria): `import("react").ReactNode` — El contenido de la pantalla. - `className`: `string | undefined` — Se une a las clases de la biblioteca, no las sustituye. - `footer`: `import("react").ReactNode` — El pie de la pagina, bajo el contenido. - `header`: `import("react").ReactNode` — La barra de arriba: normalmente un `TopBar`. Se queda fija al desplazar. - `mainId`: `string | undefined` — El `id` del contenido principal. A el apunta el enlace «saltar al contenido» del `TopBar` (`skipTo`). Por defecto, `content`. - `sider`: `import("react").ReactNode` — La columna de la izquierda: normalmente un `SideNav`. Se queda fija bajo la cabecera. - `siderWidth`: `string | undefined` — Ancho de la columna de la izquierda. Por defecto, el de `--amset-shell-sider-width` (16 rem). - `stickyHeader`: `boolean | undefined` — La cabecera se queda pegada arriba al desplazar. Por defecto, si. Acepta además los atributos HTML nativos de su elemento raíz. ## AreaChart — Gráfico de áreas (Datos) Lo mismo que `LineChart`, con el área de debajo de cada línea rellena: la evolución de una o varias series sobre las mismas categorías, con el peso de cada una a la vista. Comparte con `LineChart` y `StackedBarChart` los datos, la escala, la leyenda y la tabla. **El dibujo es el adorno y la tabla es el dato**: debajo va una tabla de verdad (una fila por categoría, una columna por serie), oculta a la vista salvo con `tableVisible`. Al pasar el ratón por una categoría salen los valores de todas las series. **Cuándo usarlo** - Un volumen que se acumula en el tiempo: ventas, visitas, horas. - `stacked` apila las series: el borde de arriba es el total y cada capa, lo que aporta cada una. Al apilar, un hueco (`null`) cuenta como cero. Sin `stacked` las áreas se superponen, translúcidas, y conviene que sean dos o tres; un `null` es un hueco y corta el área ahí. - El eje empieza siempre en cero, porque un área que arranca en otro sitio exagera las diferencias; `min` y `max` fijan la escala a mano, para comparar dos gráficos. - `format` escribe los valores (euros, porcentajes) en el eje, al pasar el ratón, en el resumen y en la tabla; `categoryName` es la cabecera de la primera columna de la tabla. **Cuándo no** - Comparar la forma de varias series sin relleno, o con el eje ajustado a los datos: `LineChart`. - Pocas categorías en las que importa el total de cada una: `StackedBarChart`. - Partes de un total en un solo momento: `DonutChart`. **Teclado**: no tiene: no hay nada que pulsar. El dato completo está en la tabla. **Accesibilidad**: el dibujo es una imagen (`role="img"`) con un resumen escrito («2 series, 9 puntos. Tienda: de 4200 € a 7800 €, el máximo, 7800 €, en Sep. …») y la tabla está siempre para el lector de pantalla. El color nunca es la única pista: la leyenda (por defecto, solo con más de una serie) y el resumen llevan el nombre de cada serie. **Aspecto fino**: variables CSS `--amset-series-*`: `-axis`, `-cap`, `-footer`, `-height`, `-label` y `-stroke`. El tamaño mueve el alto (10, 14 o 18 rem); `height` manda si se pasa. El color de cada serie sale de su `tone`, y el relleno es ese color al 22 %. - `categories` (obligatoria): `readonly string[]` — Lo que va en el eje de abajo: los meses, los dias. Una por valor de cada serie. - `label` (obligatoria): `string` — Que se esta midiendo. Obligatoria: un grafico sin titulo no informa. - `series` (obligatoria): `readonly import("./index.js").ChartSeries[]` - `axes`: `boolean | undefined` — Rayas de fondo con su numero. - `categoryName`: `string | undefined` — Como se llama la primera columna de la tabla. Por defecto, «Periodo». - `className`: `string | undefined` — Se une a las clases de la biblioteca, no las sustituye. - `format`: `((value: number) => string) | undefined` - `height`: `number | undefined` — Alto del dibujo en pixeles. Por defecto, el del tamaño. - `legend`: `boolean | undefined` — La leyenda con el nombre de cada serie. Por defecto, solo si hay mas de una. - `max`: `number | undefined` - `min`: `number | undefined` — Minimo y maximo del eje a mano, para comparar dos graficos con la misma escala. - `size`: `"sm" | "md" | "lg" | undefined` - `stacked`: `boolean | undefined` — Las series se suman unas sobre otras: el area total es la suma. Por defecto, `false` (se superponen). - `tableVisible`: `boolean | undefined` — Enseña tambien la tabla. Para el lector de pantalla esta siempre. Acepta además los atributos HTML nativos de su elemento raíz. ## ArtifactCard — Tarjeta de artefacto (IA) Un fichero que ha generado un asistente, con su vista previa a un clic: la miniatura o el icono según el tipo, el nombre, el tamaño y las acciones de abrir y descargar. **Cuándo usarlo** - Debajo de la respuesta de un asistente, para los ficheros que ha creado: informes, páginas, hojas de cálculo, imágenes. - Con una vista previa propia dentro (`ArtifactFrame` para HTML o PDF, markdown ya pintado, un vídeo). **Cuándo no** - Para un fichero que alguien va a adjuntar a un mensaje: es un `Attachment`. - Para una lista de ficheros con fechas y descarga masiva: es una `FileList`. **Teclado**: si hay vista previa, la cabecera es un botón de despliegue (Intro o Espacio); abrir y descargar son botones aparte, hermanos de la cabecera -un botón dentro de otro botón no es HTML válido-. Una imagen con `onView` no despliega: abre el visor. **Accesibilidad**: el botón lleva `aria-expanded` y el cuerpo es una región con nombre. Cargando se anuncia y un fallo es una alerta con su texto. Las acciones llevan el nombre del fichero en su etiqueta («Descargar informe.pdf»). Con `onVisible` se pide el contenido solo de lo que entra en pantalla, y el cuerpo solo se monta mientras está abierto: un `iframe` no carga hasta que alguien lo pide. **Seguridad**: `ArtifactFrame` aísla lo que muestra con `sandbox="allow-scripts"` y **nunca** `allow-same-origin`, así que lo que haya dentro corre pero no toca la página, sus cookies ni su almacenamiento. Es lo que permite enseñar lo que generó un modelo. **Aspecto fino**: variables CSS `--amset-artifact-thumb` (lado de la miniatura) y `--amset-artifact-body-max` (alto máximo de la vista previa antes de desplazarse). - `name` (obligatoria): `string` - `children`: `import("react").ReactNode` — La vista previa. Con esto la cabecera es un botón que despliega; el cuerpo solo se monta mientras está abierto, así que un `iframe` o un vídeo no cargan hasta que alguien los pide. - `className`: `string | undefined` — Se une a las clases de la biblioteca, no las sustituye. - `defaultExpanded`: `boolean | undefined` - `detail`: `import("react").ReactNode` — Más datos junto al tamaño: la fecha, quién lo generó. - `error`: `string | boolean | undefined` — Por qué no se pudo cargar. Sin texto propio, «No se pudo cargar el fichero». - `expanded`: `boolean | undefined` - `loading`: `boolean | undefined` — El contenido se está pidiendo. - `mimeType`: `string | undefined` - `onDownload`: `(() => void) | undefined` — Con esto aparece «Descargar». - `onExpandedChange`: `((expanded: boolean) => void) | undefined` - `onOpen`: `(() => void) | undefined` — Con esto aparece «Abrir». - `onRetry`: `(() => void) | undefined` — Con esto, si la carga ha fallado (`error`), aparece «Reintentar» junto a las demas acciones. - `onView`: `(() => void) | undefined` — Se pulsa para ver una imagen en grande. - `onVisible`: `(() => void) | undefined` — Se llama UNA vez cuando la tarjeta entra en pantalla: para pedir la miniatura solo de lo que se ve. - `size`: `number | undefined` — En bytes. Se escribe en el idioma: «1,5 MB». - `thumbnailUrl`: `string | undefined` — Miniatura de una imagen. Con ella, pulsar la tarjeta llama a `onView` en vez de desplegar. Acepta además los atributos HTML nativos de su elemento raíz. ## ArtifactFrame - `title` (obligatoria): `string` — Qué es, para quien no lo ve: el nombre del fichero. - `className`: `string | undefined` — Se une a las clases de la biblioteca, no las sustituye. - `height`: `string | undefined` — Alto de la vista previa. Por defecto 26 rem. - `html`: `string | undefined` — HTML como texto, o la dirección de un PDF o una página. Uno de los dos. - `src`: `string | undefined` Acepta además los atributos HTML nativos de su elemento raíz. ## AspectRatio — Proporción (Maquetación) Una caja con una proporción fija, ancho entre alto, que ocupa todo el ancho de su hueco. Lo de dentro la llena entera aunque no traiga tamaño propio. **Cuándo usarlo** - Un vídeo incrustado, un mapa o un `iframe`: no traen tamaño propio, y sin una caja que les reserve el sitio la página salta cuando terminan de cargar. - `ratio` es la proporción tal y como se escribe en CSS: `16 / 9` (por defecto), `4 / 3`, `1` para un cuadrado. - `as` pinta el elemento que toque en vez del `div`. **Cuándo no** - Una IMAGEN: `Thumbnail`, que además trae el respaldo si falla, el recorte y la carga diferida. - Una zona que crece con su contenido: lo que no cabe en la proporción se recorta (`overflow: hidden`), así que no vale para texto de largo variable. **Teclado**: no participa: solo da tamaño. Lo de dentro conserva el suyo (un `iframe` o un vídeo se enfocan como siempre). **Accesibilidad**: reservar el sitio antes de que cargue evita que el contenido de debajo se mueva mientras se lee. El nombre de lo de dentro lo pone quien lo pinta: un `iframe` necesita su `title` y un vídeo, sus subtítulos. **Aspecto fino**: `--amset-ratio`, la proporción; la escribe `ratio` en línea. - `children` (obligatoria): `import("react").ReactNode` - `as`: `"article" | "aside" | "div" | "footer" | "header" | "main" | "nav" | "section" | "span" | undefined` - `className`: `string | undefined` — Se une a las clases de la biblioteca, no las sustituye. - `ratio`: `string | undefined` — La proporcion, ancho entre alto: `16 / 9` se escribe `16 / 9`. Por defecto `16 / 9`. - `style`: `import("react").CSSProperties | undefined` Acepta además los atributos HTML nativos de su elemento raíz. ## Attachment — Adjunto (IA) Un fichero adjunto a un mensaje: su miniatura o icono, el nombre, el tamaño y, mientras sube, una barra de progreso de verdad. **Cuándo usarlo** - Encima de la caja de un chat, para lo que se va a enviar con el mensaje. - Dentro de un mensaje ya enviado, para los ficheros que llevaba. **Cuándo no** - Para una lista de ficheros de un proyecto con descarga y fechas: es una `FileList`. - Para elegir ficheros: es un `FileUpload`. **Teclado**: quitarlo es un botón y Tab llega a él. **Accesibilidad**: el estado -subiendo, subido, con error- se dice con texto, no solo con color; la subida es un `` con su nombre y su valor, y un fallo se anuncia como alerta. El botón de quitar lleva el nombre del fichero en su etiqueta («Quitar informe.pdf»). La miniatura es decorativa; con `onPreview` es un botón con el nombre del fichero («Ver informe.png»). Al terminar una subida se anuncia «Subido». El tamaño se escribe en el idioma («1,5 MB»). **Aspecto fino**: variables CSS `--amset-attachment-max` (ancho máximo) y `--amset-attachment-thumb` (lado de la miniatura). - `name` (obligatoria): `string` - `className`: `string | undefined` — Se une a las clases de la biblioteca, no las sustituye. - `compact`: `boolean | undefined` — Mas pequeño, para una barra estrecha: la miniatura de 1,75 rem y el texto en una sola linea. - `detail`: `import("react").ReactNode` — Una linea mas junto al tamaño: «Termina en ••4f2a», «3 paginas». - `errorText`: `string | undefined` — Que ha pasado, si ha fallado: «Pesa mas de 10 MB». Por defecto, «No se ha subido». - `icon`: `import("react").ReactNode` — Un icono propio en lugar del de fichero: una llave para una variable, un enlace. Sin `previewUrl`. - `onPreview`: `(() => void) | undefined` — Con esto la miniatura es un boton -«Ver informe.png»- que abre el visor, el zoom o lo que toque. - `onRemove`: `(() => void) | undefined` — Con esto aparece el boton de quitar. - `previewUrl`: `string | undefined` — Una miniatura, si es una imagen. Sin ella sale el icono de fichero. - `progress`: `number | undefined` — De 0 a 100, mientras sube. Sin esto, la barra no tiene recuento. - `size`: `number | undefined` — En bytes. Se escribe en el idioma: «1,5 MB». - `status`: `import("./index.js").AttachmentStatus | undefined` Acepta además los atributos HTML nativos de su elemento raíz. ## AudioPlayer — Reproductor de audio (Más) Notas de voz, un mensaje grabado, un audio corto: el audio con sus controles. Los controles son propios y no los del navegador, porque esos cambian de uno a otro y en varios no se llega con el teclado a la barra de posición. **Cuándo usarlo** - La nota de voz de un pedido o de un ticket, el mensaje de un cliente, una locución corta. - `src` es el fichero y `subtitle`, la línea pequeña de debajo del título (quién habla, cuándo). - Con `duration` (en segundos) si se sabe de antemano: así no enseña «–:––» ni tiene la barra apagada hasta que llegan los metadatos. **Cuándo no** - Vídeo: esto es solo audio. - Un sonido de aviso que suena solo, sin que nadie lo pida: no necesita reproductor. **Teclado**: Tab pasa por el botón de reproducir, la barra de posición y el botón de velocidad. En la barra, las flechas avanzan y retroceden de segundo en segundo, Re Pág y Av Pág saltan una décima parte de la duración, e Inicio y Fin van al principio y al final. La velocidad da la vuelta: 1×, 1,25×, 1,5× y 2×. **Accesibilidad**: `title` es obligatorio y nombra los controles: «Reproducir Nota de voz de Aitor» (o «Pausar…»), «Posición en Nota de voz de Aitor». La posición se anuncia en segundos, no como un porcentaje sin unidad. Si el audio no carga o el navegador no deja reproducir, se dice con palabras (`role="alert"`) en vez de dejar un botón que no hace nada. **Aspecto fino**: sin variables propias: se ajusta con las clases `amset-audio`, `amset-audio--playing`, `amset-audio__track`, `amset-audio__thumb` y `amset-audio__speed`. - `src` (obligatoria): `string` - `title` (obligatoria): `string` — Que se escucha. Obligatorio: nombra el reproductor y sus botones. - `className`: `string | undefined` — Se une a las clases de la biblioteca, no las sustituye. - `duration`: `number | undefined` — Duracion conocida de antemano, para no enseñar 0:00 hasta que cargue. - `subtitle`: `string | undefined` — Quien habla, cuando: la linea pequeña de debajo. Acepta además los atributos HTML nativos de su elemento raíz. ## Avatar — Avatar (Superficies) La cara, o las iniciales, de una persona. Si no hay foto, si falla al cargar o mientras llega, se ven las iniciales: nunca un hueco en blanco ni un icono roto. Cuando la foto carga, se funde por encima. **Cuándo usarlo** - Junto a quien escribe, firma o tiene algo asignado. Si el nombre ya está escrito al lado, `decorative`, para que no se lea dos veces. - Las iniciales salen solas: la primera del nombre y la del último apellido, saltándose las partículas («María de la Fuente» es MF). Si el nombre no tiene ninguna letra, sale el icono de persona. `content` pone otra cosa en su lugar (un icono). - Sin `tone` (por defecto) sale del nombre un color estable: el mismo nombre sale siempre del mismo color. `tone` lo fija con cualquiera de los ocho tonos comunes. - `variant`: `soft` (fondo claro del tono, por defecto) o `solid` (relleno fuerte con las iniciales en blanco). `shape`: `circle` (por defecto) o `square`. - `state` pinta el punto de presencia: `inline` (en línea), `away`, `busy` u `offline` (un aro hueco, no un punto gris). - `onError` avisa con la dirección de la foto si no se puede cargar. **Cuándo no** - Varias personas juntas: `AvatarGroup`, que las apila con un «+N» que dice quiénes faltan. - La foto de un producto o de un adjunto: `Thumbnail`. **Teclado**: no es enfocable ni interactivo. **Accesibilidad**: es una imagen (`role="img"`) con el nombre como texto alternativo. Con `state`, el estado va en el nombre («Marta Ruiz (ocupado)»), no solo en el color del punto. La foto lleva `alt=""`, porque el nombre ya lo da el contenedor. `decorative` lo saca del árbol accesible (`aria-hidden`). **Aspecto fino**: variables CSS `--amset-avatar-*`: `-size` (el lado: 24, 30, 36, 48 o 64 px según `size`, de `xs` a `xl`), `-text` (el cuerpo de las iniciales), `-radius` (el del `square`) y `-ring`, el color del borde que lo separa de lo de detrás (el punto de estado y los vecinos de un grupo): cámbialo si el avatar va sobre algo que no es la superficie. Los colores del tono, en `--amset-avatar-tone`, `-tone-soft`, `-tone-solid` y `-tone-ink`. - `name` (obligatoria): `string` — De aqui salen las iniciales y el texto alternativo. Obligatorio. - `className`: `string | undefined` — Se une a las clases de la biblioteca, no las sustituye. - `content`: `import("react").ReactNode` — En lugar de las iniciales: un icono, un emoji, una letra propia. - `decorative`: `boolean | undefined` — Cuando el nombre ya esta escrito al lado: el avatar deja de anunciarse y no se repite dos veces lo mismo. - `onError`: `((src: string) => void) | undefined` — Avisa de que la foto de `src` no ha cargado, con su direccion. El avatar ya se queda en iniciales por su cuenta: esto es para quien quiere reintentar con otra direccion o dejar constancia. Una foto nueva vuelve a intentarlo. - `shape`: `import("./index.js").AvatarShape | undefined` - `size`: `"sm" | "md" | "lg" | "xs" | "xl" | undefined` — De 24 a 64 px: `xs`, `sm`, `md` (36, por defecto), `lg` y `xl`. - `src`: `string | undefined` - `state`: `import("./index.js").AvatarStatus | undefined` — Punto de presencia en la esquina. Lleva su texto, no solo el color. - `tone`: `"neutral" | "accent" | "secondary" | "tertiary" | "info" | "success" | "warning" | "error" | undefined` — Sin tono, sale del nombre un color estable (`tonoDeNombre`). - `variant`: `import("./index.js").AvatarVariant | undefined` Acepta además los atributos HTML nativos de su elemento raíz. ## AvatarGroup — Grupo de avatares (Superficies) Varios avatares apilados, con un «+N» al final para los que no caben. Es una lista de verdad, y el «+N» dice quiénes son los que no se ven: un «+3» a secas no informa. **Cuándo usarlo** - Quién está en algo: el equipo de un proyecto, los asistentes a una cita, quién ha visto un documento. - `people` es la lista, cada persona con su `name` (y `src` si hay foto). `max` decide cuántos se ven antes del «+N» (4 por defecto). Siempre se ve al menos uno. - `size`, `shape` y `variant` son los de `Avatar` y valen para todos. **Cuándo no** - Una sola persona: `Avatar`. - Cuando hay que elegir o repartir personas (asignar, quitar): `SelectableList` o `TransferList`, con los nombres escritos. El grupo solo enseña. **Teclado**: no es enfocable ni interactivo. **Accesibilidad**: es una `ul` con nombre (`label`, obligatorio) y un `li` por avatar, que se anuncia con el nombre de la persona. El «+N» se lee con los nombres que faltan: «y 2 más: Jorge Peña, Sara Lima». **Aspecto fino**: las variables de `Avatar` (`--amset-avatar-size`, `--amset-avatar-text`, `--amset-avatar-ring`…) y `--amset-avatars-overlap`, lo que se pisan: 0,5rem (0,375rem en `xs`; 0,75rem en `lg` y `xl`). El aro, del color de la superficie, es lo que los separa: si el grupo va sobre otro fondo, cambia `--amset-avatar-ring`. - `label` (obligatoria): `string` — Que se esta listando: "Equipo del proyecto", "Asistentes". Obligatorio. - `people` (obligatoria): `readonly import("./index.js").AvatarPerson[]` - `className`: `string | undefined` — Se une a las clases de la biblioteca, no las sustituye. - `max`: `number | undefined` — Cuantos se ven antes del "+N". - `shape`: `import("./index.js").AvatarShape | undefined` - `size`: `"sm" | "md" | "lg" | "xs" | "xl" | undefined` - `variant`: `import("./index.js").AvatarVariant | undefined` Acepta además los atributos HTML nativos de su elemento raíz. ## BackToTop — Volver arriba (Acciones) El botón de subir: aparece en una esquina cuando se ha bajado por la página, la sube de vuelta y **lleva el foco** al principio: al primer `h1` que se vea, o al elemento cuyo id diga `focusTarget`. Aparece a partir de los píxeles de bajada que diga `from` (400 por defecto). Mientras no se ve, no está en el DOM, así que tampoco ocupa una parada del Tab. **Cuándo usarlo** - Páginas largas de verdad: un catálogo con muchas filas, una guía, unas condiciones. - Junto a otro botón flotante, dentro de un `FloatingGroup` para que no se pisen. **Cuándo no** - Una página que cabe en dos pantallas: no aporta nada. - Para saltar a una sección concreta: `TableOfContents`, que también se lleva el foco. - Cualquier otra acción flotante: `FloatingButton`. **Teclado**: cuando aparece es un botón en el sitio del DOM donde se ponga: al final, que es donde el teclado lo espera. Intro o Espacio suben la página y dejan el foco arriba, así que el siguiente Tab sigue desde el principio y no desde la mitad. Subir solo el scroll no es volver arriba. **Accesibilidad**: se llama «Volver arriba» (`label`), o lo que diga `text` si se quiere a la vista. El desplazamiento es suave, salvo con movimiento reducido, que salta sin animación. Si el destino no es enfocable, se le pone `tabindex="-1"` mientras tiene el foco y se le quita al salir. **Aspecto fino**: es un `FloatingButton` de contorno: sin variables propias; se ajusta con las `--amset-button-*` sobre `.amset-button-floating`. En esta ficha, baja dentro del marco de cada historia para que aparezca. - `className`: `string | undefined` — Se une a las clases de la biblioteca, no las sustituye. - `corner`: `import("./index.js").FloatingCorner | undefined` - `focusTarget`: `string | undefined` — Id de lo que recibe el foco al subir. Sin el, el primer `h1` de la pagina. Subir solo el scroll deja el foco donde estaba y el siguiente tabulador devuelve a media pagina: eso no es volver arriba. - `from`: `number | undefined` — A partir de cuantos pixeles de bajada aparece. Por defecto 400. - `label`: `string | undefined` — El nombre si no lleva texto visible. - `size`: `"sm" | "md" | "lg" | undefined` - `text`: `string | undefined` — Texto visible: entonces el nombre es este. Acepta además los atributos HTML nativos de su elemento raíz. ## Badge — Insignia (Estado) Insignia sobre otra cosa: el contador de una campana, el punto verde de «en línea», el número del carrito. **Cuándo usarlo** - Cuando el dato va ENCIMA de otro elemento, en una esquina. - `dot` para «hay algo nuevo» sin decir cuánto. - `count` para la cifra: con 0 no se pinta nada, salvo con `showZero`, y pasado `max` (99 por defecto) sale «99+». `tone` (`error` por defecto) y `placement` eligen color y esquina. **Cuándo no** - Para una etiqueta que va SOLA en la línea del texto (un estado, una categoría), `Tag`. - Para un número que es el contenido y no un adorno de otro, `Stat`. **Teclado**: no participa. Lo enfocable es lo que lleva debajo. **Accesibilidad**: lo que se lee es `label`, la frase entera («3 mensajes sin leer»), no la cifra: el globo va marcado como decorativo. Un «3» suelto no dice nada, y además el globo puede haberse recortado a «99+». Ojo con el envoltorio: el globo sale de la caja, así que un ancestro con `overflow: hidden` lo corta — es lo primero que mirar si no se ve. **Aspecto fino**: `--amset-badge-background`, `--amset-badge-color` y `--amset-badge-ring`. - `children` (obligatoria): `import("react").ReactNode` — Lo que lleva la insignia encima: un icono, un avatar, un boton. - `label` (obligatoria): `string` — La frase entera que se lee: «3 mensajes sin leer». Obligatoria, porque un «3» suelto no dice nada, y el numero va marcado como decorativo para que no se lea dos veces. - `className`: `string | undefined` — Se une a las clases de la biblioteca, no las sustituye. - `count`: `number | undefined` — El numero. Con `0` no se pinta nada, salvo que se pida `showZero`. - `dot`: `boolean | undefined` — Solo un punto, sin cifra. Para «hay algo nuevo» sin decir cuanto. - `max`: `number | undefined` — A partir de cuanto pone «+». Por defecto, 99. - `placement`: `"bottom-end" | "bottom-start" | "top-end" | "top-start" | undefined` - `showZero`: `boolean | undefined` - `tone`: `"neutral" | "accent" | "secondary" | "tertiary" | "info" | "success" | "warning" | "error" | undefined` Acepta además los atributos HTML nativos de su elemento raíz. ## BarChart — Gráfico de barras (Datos) Las barras de un cuadro de mando: ventas por categoría, pedidos por día, visitas por canal. El dibujo es el adorno y **la tabla es el dato**: debajo va una tabla de verdad, oculta a la vista salvo que se pida. **Cuándo usarlo** - Para comparar cantidades de unas pocas categorías (de 3 a 12) de un vistazo. - `orientation="rows"` cuando los nombres son largos; `tableVisible` cuando el número exacto importa tanto como la forma. - `max` para que dos gráficos que se comparan tengan la misma escala. - `format` para escribir los valores (euros, unidades); sin él, números en el idioma del `LocaleProvider`. `valueName` es la cabecera de la columna de valores en la tabla («Valor» por defecto). - `markers` para una línea de referencia sobre las barras (la media del grupo, un objetivo): cruza todas a su valor, entra en el techo del eje y en la tabla. - `detail` en una barra para una segunda cifra visible junto a su número («+8 pts»); solo en filas, y en columnas se queda en la tabla. - `tone` colorea las barras; `axes` y `values` quitan o ponen el eje y las cifras. **Cuándo no** - Para la evolución en el tiempo, con muchos puntos: `Trend`. - Para las partes de un total: `DonutChart`. - Para una sola cifra con su variación: `Stat`. **Teclado**: no tiene: no hay nada que pulsar. **Accesibilidad**: el dibujo es una imagen (`role="img"`) con el resumen escrito («5 barras, total 7810 €. La mayor, Anillos con 3240 €. La menor, Relojes con 310 €») y la tabla, con cabeceras de fila y de columna, está siempre para el lector de pantalla. Son cajas con alto en porcentaje, no un SVG: se imprimen y se amplían sin deformarse. El eje sube al número redondo de encima del mayor valor. **Aspecto fino**: variables CSS `--amset-bars-*`: `-axis`, `-bar`, `-cap`, `-figure-slot`, `-footer`, `-gap`, `-height`, `-label`, `-name` (lo que ocupa el nombre en filas), `-thickness`. El tamaño mueve el alto del dibujo (8, 11.25 o 15 rem), el grosor de la barra y el eje; `height` sigue mandando si se pasa. - `data` (obligatoria): `readonly import("./index.js").DataBar[]` - `label` (obligatoria): `string` — Que se esta comparando. Obligatoria: un grafico sin titulo no informa. - `axes`: `boolean | undefined` — Rayas de fondo con su numero. - `className`: `string | undefined` — Se une a las clases de la biblioteca, no las sustituye. - `format`: `((value: number) => string) | undefined` - `height`: `number | undefined` — Alto del dibujo cuando son columnas. - `markers`: `readonly import("./components/bar-chart.js").BarMarker[] | undefined` — Lineas de referencia sobre las barras (la media, un objetivo): entran en el techo del eje y en la tabla. - `max`: `number | undefined` — Techo del eje a mano, para comparar dos graficos con la misma escala. - `orientation`: `"rows" | "columns" | undefined` — `columns` sube desde el suelo; `rows` crece hacia el lado. - `size`: `"sm" | "md" | "lg" | undefined` - `tableVisible`: `boolean | undefined` — Enseña tambien la tabla. Para el lector de pantalla esta siempre. - `tone`: `"neutral" | "accent" | "secondary" | "tertiary" | "info" | "success" | "warning" | "error" | undefined` — El color de la serie, del vocabulario comun (`neutral` para lo secundario). - `valueName`: `string | undefined` — Como se llama la columna de valores en la tabla. - `values`: `boolean | undefined` — El numero encima (o al final) de cada barra. Acepta además los atributos HTML nativos de su elemento raíz. ## BarGroup - `children` (obligatoria): `import("react").ReactNode` — Los botones del grupo: se recorren juntos con las flechas. - `className`: `string | undefined` — Clases CSS propias para el grupo. - `label`: `string | undefined` — Nombre del grupo: "Formato", "Alineación". Se anuncia al entrar. ## BarSeparator - `className`: `string | undefined` — Clases CSS propias para el separador. ## Blockquote — Cita (Tipografía) Una cita en bloque, con una raya a su lado y, si se dice quién lo dijo, la atribución debajo precedida de una raya larga. **Cuándo usarlo** - Lo que dijo un cliente en una reseña, un párrafo de un contrato que se comenta, una frase de alguien con nombre. - `cite` es quién lo dijo, y puede llevar formato o un enlace. `source` es la dirección de donde sale el texto y va al atributo `cite` del elemento. **Cuándo no** - Un aviso o una nota destacada: `Alert`. - Las valoraciones de un producto, con sus estrellas: `RatingSummary`. - Un bloque de código: `CodeBlock`. **Teclado**: no participa. Si `cite` lleva un enlace, ese enlace se enfoca como cualquier otro. **Accesibilidad**: sin `cite` es un `

` y nada más. Con `cite`, la raíz pasa a ser un `
` con la cita dentro y la atribución en su `
`: es la única forma de que el nombre quede unido a la cita sin formar parte de lo citado, que es lo que pasaría dentro del `
`. Los atributos que se le pasen van siempre a la raíz, sea cual sea. El atributo `cite` que escribe `source` no lo enseña ningún navegador ni lo lee ningún lector: si la fuente importa a quien lee, va también a la vista, en `cite`. **Aspecto fino**: `--amset-quote-rule` (el color de la raya; por defecto, el acento) y `--amset-quote-color` (el del texto). - `children` (obligatoria): `import("react").ReactNode` - `cite`: `import("react").ReactNode` — Quien lo dijo. Se pinta debajo, precedido de una raya. - `className`: `string | undefined` — Se une a las clases de la biblioteca, no las sustituye. - `source`: `string | undefined` — La direccion de la fuente. Va al atributo `cite` del elemento. Acepta además los atributos HTML nativos de su elemento raíz. ## Board — Tablero (Datos) Un tablero tipo kanban: columnas de tarjetas que pasan de una a otra (pendiente, en curso, en revisión, hecho). Se mueve arrastrando **y** con el teclado, que es la mitad que falta en casi todos los tableros. **Cuándo usarlo** - Para trabajo que avanza por fases y se reparte a la vista: los encargos del taller, las tareas de la tienda. - `limit` en una columna para el trabajo a la vez que admite: pasarse avisa con texto («Por encima del límite»), no bloquea. - `Board` es controlado: recibe `columns` y avisa con `onMove`, con el tablero entero ya movido y el movimiento (`key`, `target`, `position`). `BoardInner` lleva el orden por dentro (parte de `initial`), para una demo o un panel; con `onMove` (opcional) avisa igual de cada movimiento, para guardarlo sin tener que llevar el estado. **Cuándo no** - Para reordenar una sola lista: `SortableList`. - Para repartir elementos entre dos listas (permisos, categorías): `TransferList`. - Para el estado de un único proceso: `Steps`. **Teclado**: la primera tarjeta de cada columna es una parada de Tab; desde ahí, las flechas arriba y abajo recorren las tarjetas de la columna, izquierda y derecha pasan a la de al lado (al mismo puesto o a la última), e Inicio y Fin van a la primera y a la última. Con una tarjeta enfocada, **Control (o Cmd) y las flechas** la mueven: izquierda y derecha la cambian de columna, arriba y abajo de puesto. El foco se va con la tarjeta. En el borde no se mueve ni se pierde el foco. **Accesibilidad**: es una sección con nombre obligatorio (`label`) y cada columna se llama por su título y su cuenta («En curso, 2 tarjetas»). Después de cada movimiento se anuncia dónde ha caído («Pulir el collar Luna, a En revisión, puesto 2 de 2»): sin el puesto y el total, mover con el teclado es a ciegas. La línea de ayuda de arriba explica las teclas, y el agarre de puntos es un dibujo, no un botón. **Aspecto fino**: variables CSS `--amset-board-*`: `-card-padding`, `-column`, `-description`, `-detail`, `-gap`, `-name`, `-padding`, `-radius`, `-title`. El tamaño mueve el ancho de la columna (12, 15 o 18 rem), el relleno de la tarjeta y los cuerpos de letra. - `columns` (obligatoria): `readonly import("./index.js").BoardColumn[]` - `label` (obligatoria): `string` — De que es el tablero. Obligatoria: nombra la region entera. - `onMove` (obligatoria): `(columns: readonly import("./index.js").BoardColumn[], move: import("./index.js").BoardMove) => void` - `className`: `string | undefined` — Se une a las clases de la biblioteca, no las sustituye. - `empty`: `string | undefined` - `hint`: `string | undefined` — La linea de instrucciones. Cambiala si tu app usa otras teclas. - `size`: `"sm" | "md" | "lg" | undefined` Acepta además los atributos HTML nativos de su elemento raíz. ## BoardInner - `initial` (obligatoria): `readonly import("./index.js").BoardColumn[]` — Las columnas y tarjetas de partida. A partir de ahi, el orden lo guarda el propio tablero. - `label` (obligatoria): `string` — De que es el tablero. Obligatorio: es su nombre para el lector de pantalla. - `className`: `string | undefined` — Clases CSS propias para el tablero. - `empty`: `string | undefined` — Lo que se ve en una columna sin tarjetas. - `hint`: `string | undefined` — Como se mueven las tarjetas, encima del tablero. - `onMove`: `((columns: readonly import("./index.js").BoardColumn[], move: import("./index.js").BoardMove) => void) | undefined` — Avisa de cada movimiento, con el tablero ya cambiado y lo que se ha movido: para guardarlo. Solo avisa: el orden lo sigue llevando el propio tablero. ## Breadcrumbs — Migas (Navegación) La ruta desde la portada hasta la pantalla en la que estás: «Inicio › Catálogo › Anillos › Anillo Aurelia». Todas las migas son enlaces menos la última, que es donde estás. **Cuándo usarlo** - En pantallas que cuelgan de otras (la ficha de un producto dentro de una categoría, una factura dentro de un cliente), para subir a cualquier nivel de un salto. - Con `onNavigate` cuando la navegación la lleva el enrutador del proyecto: se llama con la `key` de la miga pulsada **en lugar de** seguir el `href` (el clic del navegador se cancela). Con Ctrl, Cmd, Mayúsculas o Alt, o con el botón central, la miga se abre en otra pestaña o ventana y `onNavigate` no se llama. Por eso las migas llevan `href` también con enrutador: sin él no se pueden abrir aparte ni copiar. Si la aplicación ya registra su enrutador en la raíz con el proveedor de enrutado de la biblioteca, las migas navegan con él y `onNavigate` sobra. - `renderCrumb` para pintar cada miga a tu manera (un icono delante); se sigue anunciando por su `label`. **Cuándo no** - En la portada o en una pantalla de primer nivel: una miga sola no orienta a nadie. - Encima del título de una pantalla con sus acciones: `PageHeader` ya las pinta con su `crumbs`. - Para las fases de un proceso (compra, alta): eso es `Steps`. **Teclado**: Tab recorre las migas que son enlace e Intro las sigue (con `onNavigate`, Intro también lo lleva el enrutador). La última no es un enlace y no coge el foco. **Accesibilidad**: es un `nav` con nombre («Ruta de navegación», o lo que diga `label`), así que es un punto de referencia al que se puede saltar. La miga actual lleva `aria-current="page"`: el lector de pantalla dice «página actual» en vez de leer un enlace más. Los separadores son iconos decorativos. **Aspecto fino**: variables CSS `--amset-crumbs-*`: `-font`, `-gap`, `-padding`, `-radius`, `-separator`. El tamaño mueve el cuerpo de letra, el hueco y el separador. - `crumbs` (obligatoria): `readonly import("./index.js").Crumb[]` - `className`: `string | undefined` — Se une a las clases de la biblioteca, no las sustituye. - `label`: `string | undefined` — Lo que se anuncia al llegar. Por defecto, "Ruta de navegación". - `onNavigate`: `((key: string) => void) | undefined` — Para que navegue el enrutador del proyecto y no el navegador. Si se pasa, el clic normal y el Intro en una miga llaman aquí con su `key` **en lugar de** seguir el `href`: el clic del navegador se cancela. Con Ctrl, Cmd, Mayúsculas o Alt, o con el botón central, la miga se abre en otra pestaña o ventana y aquí no se llama. Una miga sin `href` solo avisa. - `renderCrumb`: `((crumb: import("./index.js").Crumb, state: { readonly current: boolean; }) => import("react").ReactNode) | undefined` — Pinta cada miga: un icono delante, un nombre con un distintivo. La miga sigue llamandose por su `label` para el lector de pantalla. `current` es la ultima, la pagina en la que se esta. - `size`: `"sm" | "md" | "lg" | undefined` — El cuerpo de letra y el hueco entre migas: xs, sm (por defecto) o base. Acepta además los atributos HTML nativos de su elemento raíz. ## Button — Botón (Acciones) El botón de siempre: hace algo en la misma pantalla (guardar, enviar, borrar, abrir un diálogo). **Cuándo usarlo** - Para una acción. Si lo que hace es llevar a otra página, es un `ButtonLink`: se abre en otra pestaña y el lector de pantalla dice «enlace». - Un solo botón `solid` por pantalla o por diálogo: es la acción principal. El resto, `outline`, `soft` o `ghost`. - `tone="error"` para lo que borra o da de baja, mejor dentro de un `ConfirmAction`. - `startIcon` y `endIcon` para acompañar el texto; `fullWidth` para que ocupe todo el ancho; `shape="pill"` para las esquinas redondas. **Cuándo no** - Solo con icono: `IconButton`, que obliga a ponerle nombre. - Varias acciones que pesan lo mismo: `SplitButton` o `ActionMenu`. **Teclado**: es un `