framepexls-ui-lib

v2.4.0

Published

6 hours ago

Componentes UI de Framepexls para React/Next.

0High
0Medium
0Low

Framepexls UI Lib

Sistema de diseño compartido para productos React y Next.js del ecosistema Heliip. La librería concentra componentes accesibles, iconografía propia, tokens de tema y animaciones optimizadas para evitar que cada proyecto vuelva a resolver los mismos patrones.

Inicio rápido

import "framepexls-ui-lib/theme.css";
import { Button, FormField, Input, MotionProvider } from "framepexls-ui-lib/core";

export default function App() {
  return (
    <MotionProvider>
      <FormField label="Correo" required hint="Usaremos este correo para avisos importantes.">
        <Input type="email" name="email" autoComplete="email" />
      </FormField>
      <Button type="submit">Guardar</Button>
    </MotionProvider>
  );
}

MotionProvider debe montarse una sola vez cerca de la raíz. Respeta automáticamente prefers-reduced-motion y carga únicamente el paquete de características de Motion elegido.

Imports optimizados

El import raíz se conserva por compatibilidad, pero el código nuevo debe usar la entrada más pequeña que cubra la tarea. Así Next.js puede resolver menos módulos y el bundle final conserva únicamente los componentes, iconos y proveedores que sí se usan.

Cuando una pantalla necesita un solo componente especializado también puede usar su entrada directa:

import DataTable from "framepexls-ui-lib/components/DataTable";
import DateTimeField from "framepexls-ui-lib/components/DateTimeField";

| Entrada | Úsala para | | --- | --- | | framepexls-ui-lib/core | Controles, formularios, overlays, feedback, navegación básica y movimiento | | framepexls-ui-lib/icons | Iconografía compartida | | framepexls-ui-lib/data | Tablas, páginas de datos, números y fechas relativas | | framepexls-ui-lib/charts | Gráficas y visualización financiera | | framepexls-ui-lib/color | Selector de color; requiere react-colorful | | framepexls-ui-lib/diagrams | Adaptador Mermaid para el editor Markdown | | framepexls-ui-lib/editors | Markdown, documentos, cotizaciones y Word | | framepexls-ui-lib/media | Carga, biblioteca y selección de medios | | framepexls-ui-lib/support | Chat, chatbot, notificaciones y conocimiento | | framepexls-ui-lib/theme | Tema y accesibilidad sin selector de color avanzado | | framepexls-ui-lib/map | Mapas; acompáñalo con framepexls-ui-lib/map.css | | framepexls-ui-lib/qr | Generación de códigos QR | | framepexls-ui-lib/components/* | Un componente concreto con el menor grafo posible |

La distribución es ESM, apunta a ES2022 y deja React, Next, Motion y Recharts como contratos compartidos con la aplicación para evitar runtimes duplicados. El catálogo de iconos se publica con exports estáticos y fábricas puras: importar un icono o un componente no arrastra los otros 1,510 SVG.

Colores propios del proyecto

Un proyecto puede ampliar los colores incluidos sin modificar theme.css. Define el arreglo una sola vez y entrégalo a ThemeScript y ThemeProvider; ThemeController lo obtiene del contexto y lo incorpora al selector. Si solo se proporciona color, la librería calcula un texto legible y un anillo de foco consistente.

import {
  ThemeController,
  ThemeProvider,
  ThemeScript,
  type ThemeAccentDefinition,
} from "framepexls-ui-lib/theme";

const projectAccents = [
  { value: "brand", label: "Marca", color: "#7c3aed" },
  {
    value: "brand-gold",
    label: "Dorado",
    color: "#facc15",
    foreground: "#111827",
  },
] as const satisfies readonly ThemeAccentDefinition[];

// En <head>, evita un cambio de color durante la hidratación.
<ThemeScript strategy="before-hydration" customAccents={projectAccents} defaultAccent="brand" />

<ThemeProvider customAccents={projectAccents} defaultAccent="brand">
  <ThemeController accentOptions={["blue", "brand", "brand-gold"]} />
</ThemeProvider>

value es el identificador persistido y debe comenzar con una letra minúscula; puede contener números, guiones y guiones bajos. Los nombres predefinidos están reservados. Para una marca con requisitos específicos se pueden indicar también foreground y ring mediante cualquier color CSS seguro.

Capacidades opcionales

Mapas, diagramas, QR y selección avanzada de color no se instalan con el núcleo. Agrega únicamente el paquete de la capacidad que realmente use la aplicación:

| Capacidad | Instalar | Importar | | --- | --- | --- | | Mapas | pnpm add maplibre-gl | framepexls-ui-lib/map | | Diagramas Mermaid | pnpm add mermaid | framepexls-ui-lib/diagrams | | Códigos QR | pnpm add qrcode | framepexls-ui-lib/qr | | Selector de color | pnpm add react-colorful | framepexls-ui-lib/color |

El editor Markdown funciona sin Mermaid y conserva el diagrama como un bloque de código legible. Para renderizarlo visualmente, conecta el adaptador opcional:

import { mermaidDiagramRenderer } from "framepexls-ui-lib/diagrams";
import { MarkdownEditor } from "framepexls-ui-lib/editors";

<MarkdownEditor
  value={value}
  onChange={setValue}
  diagramRenderer={mermaidDiagramRenderer}
/>

El import raíz continúa disponible para código existente, pero las aplicaciones nuevas deben preferir las entradas modulares. De esta forma, una aplicación que solo usa core no instala ni resuelve estas capacidades.

Catálogo por nivel

| Nivel | Responsabilidad | Componentes principales | | --- | --- | --- | | Fundamentos | Tema, color, tipografía, foco, espacio, radios, sombra y movimiento | theme.css, MotionProvider, Animations, iconos | | Átomos | Una función clara y composición libre | Button, ActionIconButton, Input, Textarea, Checkbox, Switch, RadioGroup, Badge, Spinner, Skeleton, Progress, Separator, VisuallyHidden | | Moléculas | Átomos conectados por una tarea | FormField, FormGroup, Alert, Collapsible, Accordion, DescriptionList, CopyableField, CodeBlock, Select, ComboSelect, DateTimeField, SearchInput, PasswordField, Pagination, Breadcrumb, SegmentedTabs | | Organismos | Flujos completos reutilizables | Dialog, Drawer, DataTable, PageScaffold, Sidebar, AppTopbar, PeoplePicker, RepeatableFieldset, PricingCard, ProcessShowcase, UsageMeter, CalendarBoard, SelectionTree, GroupedView, KnowledgeBase, MediaLibraryLayout, SupportChatWidget |

El inventario y las reglas completas viven en DESIGN_SYSTEM.md. Las mejoras futuras, su prioridad y sus criterios de aceptación se mantienen en ROADMAP.md.

Formularios

FormField enlaza automáticamente etiqueta, ayuda y error mediante id, aria-describedby, aria-invalid y aria-required.

<FormField
  label="Dominio permitido"
  hint="Escribe el dominio sin rutas adicionales."
  error={errors.domain}
  required
>
  <Input name="domain" placeholder="ejemplo.com" />
</FormField>

Para grupos de controles usa FormGroup; para una opción binaria usa Switch; para una sola elección dentro de una lista usa RadioGroup; para varias elecciones independientes usa Checkbox.

Estados de interfaz

<Alert tone="warning" title="Cuota por terminar" actions={<Button size="sm">Ver planes</Button>}>
  Te quedan 12 solicitudes. La cuota se reinicia el 31 de julio.
</Alert>

<Progress value={88} tone="warning" label="Uso mensual" showValue />
<Skeleton shape="text" lines={3} />

Skeleton reserva el espacio del contenido que todavía no existe.
Spinner acompaña acciones breves cuyo tamaño no cambia.
Progress comunica avance conocido o indeterminado.
Alert comunica información persistente y accesible; los Toast son para confirmaciones efímeras.

Patrones de producto

La primera colección de patrones compartidos evita repetir estructura, estados y accesibilidad en las aplicaciones:

| Necesidad | Componente | | --- | --- | | Mostrar atributos de un registro | DescriptionList y DescriptionItem | | Colapsar secciones relacionadas | Accordion y Accordion.Item | | Seleccionar una o varias personas | PeoplePicker | | Editar colecciones repetibles | RepeatableFieldset | | Mostrar y copiar claves o URLs | CopyableField | | Presentar código, JSON o scripts | CodeBlock | | Construir páginas de suscripción | PricingCard, PricingGrid, FeatureList, BillingIntervalSelector y SubscriptionSummary | | Explicar un flujo conectado | ProcessShowcase | | Comunicar cuota o consumo | UsageMeter | | Organizar eventos por año, mes, semana o día | CalendarBoard | | Seleccionar permisos u opciones jerárquicas | SelectionTree o su alias PermissionTree | | Presentar tablas o listas por grupos colapsables | GroupedView y GroupedViewSection |

import {
  BillingIntervalSelector,
  PeoplePicker,
  PricingCard,
  PricingGrid,
  UsageMeter,
} from "framepexls-ui-lib/core";

<PeoplePicker
  label="Responsables"
  options={team}
  value={assigneeIds}
  onChange={setAssigneeIds}
/>

<UsageMeter
  title="Solicitudes mensuales"
  used={820}
  limit={1000}
  resetsAt="el 1 de agosto"
/>

<PricingGrid>
  <PricingCard
    name="Heliip Support"
    price="$999 MXN"
    interval="al mes"
    features={["1,000 solicitudes", "30 solicitudes por minuto"]}
  />
</PricingGrid>

Accordion, PeoplePicker, ProcessShowcase y los controles de planes admiten uso controlado. Los textos predeterminados pueden reemplazarse mediante props cuando el producto necesita otro idioma o vocabulario.

Principios de uso

Usa primero un componente existente y compón antes de crear una variante local.
Los colores provienen de variables del tema; evita hexadecimales en componentes de producto.
Los iconos compartidos se importan exclusivamente desde framepexls-ui-lib y se implementan en src/iconos.
Toda interacción debe funcionar con teclado, foco visible y lectores de pantalla.
El movimiento explica un cambio de estado; no debe retrasar una tarea ni mover contenido de forma brusca.
Los estados loading, vacío, error, deshabilitado y modo oscuro forman parte del componente, no son detalles posteriores.

Calidad

pnpm typecheck
pnpm lint
pnpm test:unit
pnpm test:coverage
pnpm test:hydration
pnpm check:design
pnpm build
pnpm api:check
pnpm size:check
pnpm compat:smoke
pnpm storybook
pnpm test:interactions
pnpm test:a11y
pnpm test:visual
pnpm check:stories
pnpm check:all

lint aplica reglas modernas de TypeScript, hooks y accesibilidad sin permitir que aumente la deuda heredada; los módulos nuevos de lógica usan revisión tipada estricta. test:coverage protege calendario, paginación, documentos, contraseñas, Sidebar, árboles de selección, políticas de ShareAccess, transformaciones de gráficas y formatos numéricos con cobertura V8 y umbrales verificables. test:hydration construye una aplicación Next real y valida en Chromium y WebKit el HTML del servidor, Strict Mode, foco, portales, bloqueo de scroll y controles hidratados. api:check compara las firmas TypeScript y las subrutas públicas con reportes versionados. size:check construye consumidores mínimos con tree-shaking y bloquea aumentos fuera del presupuesto para la raíz, entradas temáticas, un componente directo, un icono y las hojas CSS. check:design protege exports esenciales, tokens, entradas modulares, capacidades opcionales, el sistema de iconos y el uso válido de SVG. pnpm build genera declaraciones, valida el paquete con publint y comprueba sus tipos con Are the Types Wrong. Storybook documenta los estados reales y ejecuta sus flujos de interacción en navegador. La accesibilidad se valida con axe en tema claro, oscuro y colores forzados, además de una matriz de Firefox, WebKit, móvil, inglés y movimiento reducido. test:visual compara el catálogo completo en claro y oscuro, y una selección crítica en 320 px, 390 px, tablet, horizontal, colores forzados, inglés, Firefox y WebKit; todas las capturas verifican que no haya desbordamiento horizontal. test:visual:update renueva explícitamente todas las referencias. La lista de revisión humana está en ACCESSIBILITY.md. compat:smoke renderiza el núcleo con la versión activa de React y valida Next 16. El CI ejecuta además la matriz Node 22/24 con React 18/19. pnpm check valida tipos, lint, cobertura, diseño, API, tamaño, distribución y catálogo; pnpm check:all agrega las pruebas de interacción, hidratación, accesibilidad y regresión visual.