# @amset/ui
> Biblioteca de componentes React sin dependencias, accesible y tematizable. Versión 0.17.1.
## Reglas que no se discuten
- No inventes componentes ni props: lo que no está en `api.json` no existe. Ante la duda, consulta `node_modules/@amset/ui/dist/api.json`.
- Importa siempre del índice: `import { Button } from '@amset/ui'`. El formulario conectado, de `@amset/ui/form`.
- Estilos: no hay que importar ninguna hoja, cada componente trae la suya (y no importes `styles.css` además: saldría duplicado). Con Next Pages Router hace falta `transpilePackages: ['@amset/ui']`. Los colores salen de los roles de `tokens.css` (`var(--amset-...)`); no escribas colores a mano.
- El tema va en `data-theme="light|dark"` sobre `` (sin prefijo). La densidad, en `data-density`.
- No depende de Tailwind ni de ningún framework de CSS: funciona con cualquiera o sin ninguno.
- Todos los componentes aceptan los atributos HTML nativos de su elemento raíz (`id`, `aria-*`, `data-*`, `onClick`...).
- Con React 19, `ref` es una prop normal.
- Los textos propios salen del idioma de `LocaleProvider` (español o inglés; otro idioma cae en inglés; sin proveedor, español). Una prop de texto (`closeLabel`, `label`...) manda sobre el catálogo y `messages` en el proveedor cambia un texto en toda la app.
## Ficheros
- `dist/api.json`: props reales de cada componente.
- `dist/llms-full.txt`: lo mismo en texto, con descripciones.
- `dist/docs.json`: cuándo usar cada componente, teclado y accesibilidad.
- `dist/knobs.json`: variables CSS tocables por componente.
- `dist/tokens.css`: los roles de color y el resto de tokens.
## Componentes
- **Accordion** — Secciones plegables una debajo de otra, cada una con su título y, si hace falta, un resumen de lo que hay dentro. Por defecto solo hay una … (props: sections*, allowsMultipleExpanded, className, defaultExpandedKeys, disabled, expandedKeys)
- **ActionMenu** — El menú de los tres puntos: las acciones de una fila, de una tarjeta o de una ficha, recogidas detrás de un botón y abiertas en un panel fl… (props: label*, onSelect*, actions, className, disabledKeys, minWidth)
- **ActivityLog** — El registro de lo que está haciendo un agente: llamadas a herramientas, resultados, razonamiento y respuestas, una fila por evento y con su… (props: events*, className, collapseRepeats, empty, emptyIcon, endedAt)
- **ActivityMap** — La rejilla de días por semanas, como la del perfil de GitHub: cada columna es una semana (de lunes a domingo), cada cuadro un día, y el col… (props: days*, from*, label*, to*, unit*, className)
- **AddressField** — La dirección postal de España en un bloque: calle y número, piso, código postal y población. La provincia no se pregunta: sale de las dos p… (props: onChange*, value*, className, disabled, errors, label)
- **Affix** — Un bloque que se queda pegado al desplazar: el índice de una página larga, un resumen de compra, una barra de acciones. (props: children*, className, offsetBottom, offsetTop, onChange)
- **Alert** — Banda de estado dentro de una pantalla: algo ha ido bien, algo ha fallado, algo vence. Siempre lleva icono Y texto, y cada tono tiene su si… (props: children*, actions, announcement, className, closeLabel, icon)
- **Amount** — Un precio, con su moneda y en el formato del idioma activo: 1234,56 € en español, $1,234.56 en inglés. Con precio anterior lo tacha, escrib… (props: quantity*, before, className, currency, freeText, highlightOffer)
- **AmsetProvider** — Todo lo que la librería necesita alrededor, en una línea: {children}. Por dentro son tres: el idioma (Locale… (props: children*, catalogs, density, locale, messages, notifications)
- **AppliedFilters** — Las fichas de los filtros que están puestos ahora mismo, encima de una tabla o de una lista. Sirven para dos cosas: que se vea por qué falt… (props: filters*, onRemove*, className, clearText, empty, label)
- **AppShell** — El armazón de una aplicación: cabecera, columna lateral, contenido y pie, en una rejilla de CSS y en un solo componente: header, sider, chi… (props: children*, className, footer, header, mainId, sider)
- **AreaChart** — 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 e… (props: categories*, label*, series*, axes, categoryName, className)
- **ArtifactCard** — 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 a… (props: name*, children, className, defaultExpanded, detail, error)
- **ArtifactFrame** (props: title*, className, height, html, src)
- **AspectRatio** — 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… (props: children*, as, className, ratio, style)
- **Attachment** — Un fichero adjunto a un mensaje: su miniatura o icono, el nombre, el tamaño y, mientras sube, una barra de progreso de verdad. (props: name*, className, compact, detail, errorText, icon)
- **AudioPlayer** — 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… (props: src*, title*, className, duration, subtitle)
- **Avatar** — 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 blan… (props: name*, className, content, decorative, onError, shape)
- **AvatarGroup** — 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:… (props: label*, people*, className, max, shape, size)
- **BackToTop** — 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 q… (props: className, corner, focusTarget, from, label, size)
- **Badge** — Insignia sobre otra cosa: el contador de una campana, el punto verde de «en línea», el número del carrito. (props: children*, label*, className, count, dot, max)
- **BarChart** — 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: d… (props: data*, label*, axes, className, format, height)
- **BarGroup** (props: children*, className, label)
- **BarSeparator** (props: className)
- **Blockquote** — 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. (props: children*, cite, className, source)
- **Board** — 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 … (props: columns*, label*, onMove*, className, empty, hint)
- **BoardInner** (props: initial*, label*, className, empty, hint, onMove)
- **Breadcrumbs** — La ruta desde la portada hasta la pantalla en la que estás: «Inicio › Catálogo › Anillos › Anillo Aurelia». Todas las migas son enlaces men… (props: crumbs*, className, label, onNavigate, renderCrumb, size)
- **Button** — El botón de siempre: hace algo en la misma pantalla (guardar, enviar, borrar, abrir un diálogo). (props: children*, className, disabled, endIcon, excludeFromTabOrder, fullWidth)
- **ButtonGroup** — Varios botones pegados que son UN bloque de acciones: «Guardar» y «Guardar y cerrar», «Anterior» y «Siguiente». (props: children*, label*, className, detached, fullWidth, orientation)
- **ButtonLink** — Lo que navega es un enlace, aunque se pinte como un botón. ButtonLink tiene el aspecto de Button (las mismas variantes, tonos y tamaños) y … (props: children*, className, disabled, endIcon, fullWidth, href)
- **Calendar** — El mes a la vista, sin desplegar nada: para elegir el día de una recogida, una cita o un periodo mirando qué días quedan libres. Con range … (props: label*, className, defaultFocusedValue, defaultValue, disabled, error)
- **Card** — Superficie con cabecera (título, subtítulo y un hueco a la derecha), cuerpo, medios a sangre y un pie separado por un divisor. Puede ser es… (props: children, className, disabled, extra, footer, headingLevel)
- **CardField** — Los datos de la tarjeta en un bloque: número, caducidad y código de seguridad, y el titular si se pide. Es un fieldset con su leyenda, porq… (props: onChange*, value*, alert, className, disabled, errors)
- **Carousel** — Una tira de cosas que se recorre: las fotos de un producto o una fila de tarjetas que no cabe. Arriba van el contador y los botones de ante… (props: label*, slides*, automatic, className, index, loop)
- **Cascader** — País > provincia > ciudad en un solo campo, con una columna por nivel. Es lo que hasta ahora se montaba con varios Select encadenados, que … (props: label*, options*, changeOnSelect, className, defaultValue, disabled)
- **Center** — Centra lo que lleva dentro, en horizontal y en vertical. Para el hueco de una carga, un panel todavía vacío o un mensaje en medio de una zo… (props: children*, as, className, minHeight, style, vertical)
- **ChatMessage** — Un mensaje de un chat con un asistente: la burbuja, quién lo dice, su pie y las acciones de siempre -copiar, regenerar, editar-. (props: children*, from*, actions, actionsVisibility, author, avatar)
- **Checkbox** — Una casilla de verificación: sí o no sobre una cosa, o marcar varias de una lista. Se pulsa en toda la etiqueta, no solo en el cuadrado. (props: aria-controls, aria-describedby, aria-details, aria-labelledby, autoFocus, children)
- **CnaeField** — El código CNAE-2009 de la actividad económica: cuatro cifras. (props: back, className, descriptions, disabled, error, front)
- **Code** — Un trozo de código DENTRO de una frase: un nombre de variable, una ruta, un valor, un comando. (props: children*, className)
- **CodeBlock** — Un bloque de código con su cabecera (el nombre del fichero o lo que sea), números de línea si se piden, líneas marcadas y botón de copiar. … (props: code*, className, highlight, language, numberLines, size)
- **CodeField** — El código de un solo uso: el de la verificación en dos pasos, el que llega por SMS o por correo. Una casilla por carácter, porque así se le… (props: label*, autoFocus, checkboxText, className, disabled, error)
- **Collapsible** — Un bloque que se pliega, suelto: «Ver más», «Detalles del envío», un filtro avanzado que no estorba hasta que hace falta. (props: children*, title*, arrowEnd, className, defaultExpanded, disabled)
- **ColorPanel** — Las tripas de ColorPicker, sueltas: el área de saturación y brillo, la tira de tono, la de transparencia si se pide, el campo hexadecimal y… (props: color*, onChange*, alphaChannel, className, samples, size)
- **ColorPicker** — Elegir un color: un botón con la muestra y el valor escrito, y un panel con el área de saturación y brillo, la tira de tono, el campo hexad… (props: label*, alphaChannel, className, disabled, error, hint)
- **Combobox** — Campo con lista de sugerencias que también admite texto libre: se escribe, la lista se filtra y se puede elegir una opción o dejar lo escri… (props: label*, options*, allowsCustomValue, autoFocus, className, defaultInputValue)
- **CommandPalette** — La paleta de comandos, el Ctrl+K de toda la vida: se abre con el teclado desde cualquier sitio, se escribe y se salta a donde sea. Por dent… (props: groups*, onSelect*, className, footer, noResultsMessage, onOpenChange)
- **Comments** — Un hilo de comentarios con respuestas anidadas: las preguntas de un producto, las notas de un pedido, la conversación de una incidencia. Ca… (props: comments*, label*, className, empty, maxDepth, onReply)
- **CompactGroup** — Un campo con su botón, o varios campos, pegados sin huecos y con las esquinas de unión cuadradas: el buscador con «Buscar», el cupón con «A… (props: children*, label*, className, orientation)
- **ConfirmAction** — La pregunta de seguridad pegada al botón que la provoca: «¿Borrar el pedido 1042?» con dos salidas, sin tapar la página. Es el escalón de a… (props: onConfirm*, question*, trigger*, cancelText, className, confirmText)
- **ConfirmProvider** — Preguntar «¿seguro?» desde cualquier componente sin montar un diálogo y su estado en cada pantalla. Se pone una vez, arriba del árbol (Amse… (props: children*)
- **ConnectionStatus** — La cinta de «sin conexión»: aparece cuando el navegador pierde la red y se quita cuando vuelve. Al volver dice «Conexión recuperada» durant… (props: className, offlineText, returnText, warnReturn)
- **Container** — Centra el contenido en horizontal y le pone un ancho máximo de lectura, con un relleno a los lados para que el texto no toque el borde de l… (props: children*, as, bare, className, style, width)
- **ContextMenu** — El menú del clic derecho: una zona que, al pulsarla con el botón secundario, abre una lista de acciones justo en el puntero. Mismas accione… (props: children*, label*, onSelect*, actions, className, disabled)
- **Conversation** — Un hilo de mensajes: un ticket de soporte, un chat con la tienda, las notas de un pedido. Lo propio a un lado, lo ajeno al otro y los aviso… (props: label*, messages*, className, customName, empty, loading)
- **CookieBanner** — La banda de consentimiento de cookies, abajo y sin las trampas de costumbre: aceptar y rechazar pesan lo mismo, con el mismo tamaño y el mi… (props: onDecide*, acceptText, className, configureText, link, onConfigure)
- **Copyable** — Un dato con su botón de copiar al lado: un IBAN, un código de descuento, una clave de API, un número de seguimiento. Al copiar, el icono pa… (props: label*, value*, buttonOnly, children, className, copiedText)
- **Countdown** — Una cuenta atrás en segundos: «Reenviar el código en 29 s», «1:30» a partir del minuto y «1:02:05» a partir de la hora, con las cifras del … (props: label*, seconds*, active, announceEvery, className, endContent)
- **CouponField** — El código de descuento de la cesta. Empieza plegado detrás de «¿Tienes un código de descuento?» porque la mayoría no tiene código, y un cam… (props: applied*, onAccept*, onApply*, onRemove*, className, collapsed)
- **CurrentStep** — «Paso 2 de 4» y el nombre del paso: la versión corta de Steps para pantallas estrechas, donde no caben cuatro columnas de texto. (props: current*, steps*, className, size)
- **DataList** — Pares etiqueta-valor: la ficha de un cliente, el resumen de un pedido, los datos de un producto. En una columna o en varias, con la etiquet… (props: data*, className, columns, dividers, empty, headingLevel)
- **DatePicker** — Una fecha escrita por partes (día, mes y año, en el orden del idioma: en es-ES, 24/09/2026, siempre con dos cifras como el marcador dd/mm/a… (props: label*, className, defaultOpen, defaultValue, disabled, error)
- **DateRangePicker** — Dos fechas que van juntas: «del 1 al 30 de septiembre». Cada extremo se escribe por partes, igual que en DatePicker, y el calendario enseña… (props: label*, className, defaultOpen, defaultValue, disabled, endName)
- **DateTimePicker** — La fecha y la hora juntas, en un solo campo: el calendario de DatePicker y los segmentos de TimeField dentro de un grupo con nombre. El val… (props: label*, className, disabled, error, firstDayOfWeek, granularity)
- **Dialog** — Un diálogo modal: corta el paso hasta que se contesta. Es un