Component Library

La Nxar Component Library es un sitio público y estático donde podés ver todos los componentes de UI corriendo en vivo, cambiar sus props con controles interactivos, y copiar snippets listos para pegar en tu Custom Component.

Cuándo usarla:

• Estás escribiendo un Visual Custom Component y querés ver qué Nxar.* ya están disponibles antes de inventarlo desde cero.
• Sos parte del equipo Nxar y querés saber si alguna primitive de @crm/ui cubre el caso que estás por buildear.
• Necesitás un snippet copiable para un componente que ya conocés.

Cómo está organizada

Dos secciones — una por package:

Cada componente tiene 4 tabs:

• Preview — la rendered output con controles live a la derecha. Cambiá una prop y el preview se actualiza al instante.
• Props — tabla con el contrato del componente: nombre, tipo, default, descripción.
• Examples — variantes pre-armadas (default, with action, loading, etc.) con código copiable.
• Source — link directo al código del componente en GitHub + lista de tokens (CSS vars / Tailwind classes) que consume.

Inventario

Composites (admin)

Componentes de alto nivel que combinan varias primitives + lógica de UI. Son los que más vas a usar al construir features admin.

• PageCard + PageCardHeader, PageCardHeaderAction, PageCardLoadMore — shell canónico para componentes de Record/App Pages
• SettingsPageHeader — header obligatorio en toda sección de Settings
• SettingsListView — listado tabular con search + acciones — la base de la mayoría de las pantallas de Settings
• Combobox — single-select con search integrado para listas largas
• MultiSelect — multi-pick con badges y search

Primitives (admin)

Bloques chicos. Mismas que shadcn/ui pero con tokens de Nxar (brand color, font, radius).

• Button — 6 variantes × 4 tamaños
• Badge — pill chico para status / counters / labels
• Avatar + AvatarGroup — imagen de perfil con fallback de iniciales
• Tabs — tab switcher in-page (no confundir con la barra de tabs del workspace)
• Kbd — keyboard shortcut hint (⌘K, Esc)

Form

• Input — text input con tokens consistentes
• Select — dropdown nativo estilado para listas cortas
• Combobox / MultiSelect — para listas largas (ver Composites)

Feedback

• Dialog — modal con focus trap + Esc-to-close
• ConfirmDialog + confirm() — modal de confirmación global (Promise<boolean>). Disparable desde Visual Components vía sdk.confirm(...)
• Tooltip — hint on hover/focus, sobre todo para icon-only buttons
• Alert — banner in-page sticky para validation summaries, deprecation warnings, permission denied
• EmptyState — placeholder estandarizado para listas vacías
• Skeleton — placeholder animado para loading states
• Spinner — loading indicator estandarizado (4 sizes, color hereda del contexto)
• Progress — barra de progreso, determinada o indeterminada
• Toaster + toast() — notificaciones flotantes (“Saved”, “Sent”, errors). Disparable desde Visual Components vía sdk.toast(...)

Visual UI (iframe — Custom Components)

Versión de los componentes anteriores que vive dentro del iframe sandbox de tus Visual Custom Components. Sin import — están como globales en window.Nxar. Paridad ~1:1 con @crm/ui (mismos primitives, look idéntico vía CSS vars).

Composites:

• Nxar.PageCard (+ PageCardHeader, PageCardHeaderAction, PageCardLoadMore) y Nxar.Card (+ partes) — las cards de Record/App Pages
• Nxar.SettingsSection + Nxar.SettingsRow — pantallas de configuración de paquetes

Primitives:

• Nxar.Button — botón con variantes y tamaños
• Nxar.Badge — pill chico (7 variantes)
• Nxar.Avatar + AvatarImage + AvatarFallback — imagen con fallback
• Nxar.Kbd — keyboard shortcut hint
• Nxar.Tabs + TabsList + TabsTrigger + TabsContent — tab switcher

Form:

• Nxar.Input, Nxar.Textarea, Nxar.Label
• Nxar.Select — dropdown (listas cortas)
• Nxar.Combobox — single-select con search (listas largas)
• Nxar.MultiSelect — multi-pick con badges

Feedback:

• Nxar.Tooltip — hover/focus tooltip
• Nxar.EmptyState — placeholder para listas vacías
• Nxar.Alert + AlertTitle + AlertDescription — banner in-page
• Nxar.Skeleton — placeholder animado para loading states
• Nxar.Spinner — loading indicator
• Nxar.Progress — barra de progreso (determinada / indeterminada)
• Nxar.Icon — iconos por nombre (set curado)
• Nxar.Dialog, Nxar.Popover — overlays (dentro del iframe)

Bridge al admin (no son componentes):

• sdk.toast(...) → renderiza un toast en el shell admin
• sdk.confirm(...) → renderiza un modal de confirmación en el shell admin (Promise<boolean>)

Para la guía completa de cómo escribir un Visual Component, ver Visual Components; para el catálogo y los iconos del iframe, Nxar UI; para el objeto sdk, el SDK.

Buscando algo que no está

Si necesitás una primitive que todavía no existe (charts dentro del iframe es el pedido más común):

1. Para @crm/ui — abrí un issue describiendo el caso de uso. Algunos componentes existen en el package pero todavía no están documentados en el library — preguntá antes de buildear.
2. Para @nxar/visual-ui — el catálogo es más chico a propósito (cada componente que se agrega aumenta el bundle del iframe). Si encontrás un caso recurrente, abrí un issue con el use case y lo evaluamos.

Convenciones de uso

• Nunca reimplementes un componente que ya está en el library. Si el shape no encaja, ampliá la primitive — no la bypasees con classNames inline. Eso garantiza que cambios futuros (radius, padding, hover states) se propaguen automáticamente a todos los consumidores.
• Usá los tokens que figuran en el tab Source. Las CSS vars (--brand, --brand-soft, etc.) cambian con el tema dark/light y eventualmente con accent override per-tenant. Hardcodear hexes te saca de ese sistema.
• Composables, no monolíticos: los primitives están pensados para componerse (PageCard + PageCardHeader + EmptyState). No esperes “una prop que haga todo”.

Para el equipo Nxar — agregar un componente al library

Si sos contributor del CRM y agregaste un nuevo componente reutilizable a packages/ui o packages/visual-ui, agregalo también al library para que aparezca en este sitio. Consultá al equipo de Nxar por la receta interna de publicación.