Adopción de Lit — <plt-variant-picker> y grupos de componentes¶

Estado: piloto mergeado (#35); grupos de componentes implementados, pendientes de revisión humana. Base auditada: plt-design-system@c8cae0b, plt-frontend-liquid@6755975, plt-astro-storefront@eb628dd, tina-hydrogen-frontstore@379dfa5.

Resumen¶

• Un único Web Component Lit, <plt-variant-picker>, en un paquete nuevo @playlovetoys/web-components. La lógica de selección vive en un módulo puro (resolve.ts) que no depende de Lit, del DOM ni de ninguna plataforma.
• Tres adaptadores mínimos — Liquid (snippet), Astro (componente) y React (wrapper de ~130 líneas) — que solo normalizan datos, pasan propiedades y escuchan el evento DOM plt:variant-change. Ninguno reimplementa la selección.
• Light DOM: el componente usa las clases d- de daisyUI, theme-* y los tokens --plt-* ya existentes; no trae CSS propio salvo seis reglas de patrón añadidas a patterns.css.
• Validado en Chromium real contra tres demos construidas desde la misma implementación (Liquid renderizado con liquidjs, astro build real, React SSR
• hidratación): 23 pruebas de navegador, 26 unitarias/SSR, axe-core sin violaciones, render idéntico píxel a píxel y árbol de accesibilidad idéntico en los tres frontends.
• Coste: 8,4 KB gzip el bundle autocontenido (6,3 KB son el runtime de Lit, que se amortiza entre componentes); 2,3 KB gzip el componente con Lit compartido.
• Fase 2: diez elementos en cuatro grupos (producto, carrito, colección, navegación), con el mismo patrón. Se validaron con 68 pruebas unitarias/SSR y 49 de navegador en los tres frontends: axe sin violaciones, respaldos sin JS, y paridad de píxeles y de árbol de accesibilidad. Todo junto pesa 14,9 KB gzip, Lit incluido.

Fase 2 — Grupos de componentes¶

Tras el piloto se pasaron a Lit cuatro grupos, con el mismo patrón: una sola implementación, adaptadores Liquid/Astro/React mínimos y pruebas en los tres frontends.

Decisiones adicionales¶

1. Dos tipos de elemento. Los que renderizan (selector, cantidad, carrito, colección) generan su anatomía desde datos y sustituyen un respaldo sin JS (data-plt-fallback). Los que mejoran (galería, quick view, navbar) añaden comportamiento al marcado de los renderers del DS y no renderizan nada: su contrato es el de los CE vanilla, que se eliminan (gallery.js, quick-view.js, navbar-toggle.js). Sus 11 pruebas jsdom se trasladaron sin cambios y pasan contra la versión Lit.
2. Eventos de colección cancelables. Por defecto el control envía su formulario GET o sigue su enlace, lo que funciona en cualquier frontend, Liquid incluido. Un frontend con enrutado en cliente llama a preventDefault() y navega él mismo. Los filtros vacíos se omiten de la URL.
3. El carrito informa intenciones, no muta. plt:cart-line-change y plt:cart-line-remove llevan el id de línea. El frontend hace la mutación en Shopify, marca busy mientras tanto y vuelve a pasar lines y subtotal. Los precios llegan ya formateados: los componentes nunca calculan dinero.
4. Drawer sobre <dialog> modal: foco contenido, Escape, retorno del foco y bloqueo de scroll compartido con el quick view (contador de referencias).
5. Megamenú centralizado en <plt-navbar>: hover con retardo de cierre, foco, ArrowDown, Escape y un solo panel abierto. Los renderers Navbar (Astro y Liquid) generan la anatomía MegaMenu desde links[].columns, y el renderer Liquid ahora incluye <plt-navbar>, que antes no tenía.
6. Un puente React genérico (createComponent): cada adaptador es solo configuración (propiedades, atributos, eventos, respaldo). Son 1,9 KB gzip para los diez.
7. Un bundle conjunto plt-web-components.bundle.js para temas Shopify, que incluye Lit una sola vez. Se mantiene el bundle del piloto.
8. Estilos en src/components/web-components.css (hoja lateral, chips, foco), con fallback a variables de daisyUI como la del selector.

Hallazgos durante la implementación¶

• Bug corregido. Lit añade su contenido después de los hijos existentes, así que :scope > form encontraba el formulario de respaldo deshabilitado: en Liquid el filtro navegaba a ? vacío. Lo detectó la prueba de navegador; ahora el selector excluye [data-plt-fallback] y hay prueba de regresión.
• Contraste. .theme-meta (texto al 60 % de opacidad, global en el DS) no llega a AA sobre fondos claros. El componente de línea de carrito usa contraste completo; la corrección global de .theme-meta queda propuesta aparte porque afecta a todos los temas.
• liquidjs ≠ Shopify. liquidjs serializa nil | json como {} y Shopify como null. Los adaptadores escriben null explícito.

Fase 1 — Auditoría¶

plt-design-system¶

• Monorepo npm workspaces: @playlovetoys/design-system (CSS, tokens, contratos, renderers Liquid/Astro), @playlovetoys/editorial, @playlovetoys/astro.
• Contrato OptionPicker (contracts/components.md): name, options[] con { label, value, selected?, disabled? }; "Variant resolution and form wiring stay outside the contract". Renderers option-picker.liquid y commerce/OptionPicker.astro estáticos. No existe contrato VariantPicker.
• Hallazgo de accesibilidad: ambos renderers ocultan el radio con class="hidden" (display: none), por lo que el selector no es operable por teclado. El piloto usa el patrón correcto (radio visualmente oculto pero enfocable); corregir los renderers existentes queda fuera de alcance para no cambiar su contrato en este PR.
• Custom Elements existentes: plt-product-gallery (commerce/gallery.js), plt-product-quick-view (commerce/quick-view.js) y navbar-toggle.js, en JavaScript nativo, light DOM, registro con if (!customElements.get(...)), probados con Vitest + jsdom. No se exponen en exports del paquete.
• Distribución: los consumidores instalan el repo como dependencia git fijada a un commit (Hydrogen: "@playlovetoys/platform": "github:aavendano/plt-design-system#<sha>"). No hay publicación en npm ni paso de build de JS.
• Pruebas: npm run check (conformidad daisyUI, seguridad de renderers, contratos commerce, Vitest, stylelint, build del demo y de temas). CI con Node 20.

Selección de variantes en los frontends¶

Tres implementaciones distintas de la misma interacción, con semánticas de accesibilidad distintas (radios, botones aria-pressed, radios Alpine).

Responsabilidades que permanecen fuera del Design System¶

Obtención de datos de Shopify, precios y moneda, inventario, mutaciones de carrito, rutas/URL, persistencia, reglas de mercado y locale (incluidas las traducciones, que el frontend pasa en labels). El componente solo recibe available como snapshot: el frontend debe reconciliar con Shopify antes de permitir la compra (coherente con la regla de plt-astro-storefront).

Decisiones¶

1. Paquete separado @playlovetoys/web-components. Mantiene @playlovetoys/design-system libre de JavaScript de runtime y de Lit; quien solo consume CSS no instala ni descarga Lit. Lit es dependency del paquete nuevo; React es peerDependency opcional (solo para el adaptador React).
2. Light DOM (createRenderRoot() { return this; }). Las clases de daisyUI y Tailwind son globales; con Shadow DOM habría que duplicar o inyectar la hoja de estilos en cada instancia. Light DOM además permite que el <input hidden> del id de variante participe en el <form> del consumidor sin ElementInternals. Contrapartida: sin encapsulación de estilos (aceptable: es el modelo del DS).
3. Lógica pura separada (resolve.ts): normalización, búsqueda exacta, estado por valor (available/sold-out/unavailable) y resolución al variante más cercano. Es lo único que decide qué variante corresponde a una selección; el elemento Lit y los adaptadores la reutilizan.
4. API pública por propiedades, atributos y eventos DOM. Datos complejos como propiedades (React/JS) o atributos JSON (Liquid/Astro, escapados por la plataforma; JSON inválido se ignora con aviso). selected-variant-id se refleja. Un único evento estable plt:variant-change, CustomEvent, bubbles: true, composed: true, emitido solo por interacción del usuario.
5. Valores nunca deshabilitados. Las combinaciones inexistentes se marcan pero siguen siendo seleccionables; al elegirlas se conserva el valor y las demás opciones se mueven al variante existente más cercano (disponibles primero). Así se alcanza cualquier valor (p. ej. Green solo existe en S).
6. SSR por mejora progresiva, sin Lit SSR. Cada adaptador renderiza en servidor el elemento con su estado inicial y un <select> de respaldo (data-plt-fallback) que funciona sin JavaScript. Al actualizarse, el componente oculta y deshabilita el respaldo. @lit-labs/ssr (Declarative Shadow DOM) se descartó: es labs, no aplica a Liquid y no aporta con light DOM.
7. Registro idempotente. define no hace nada sin customElements (servidor) ni si la etiqueta ya está registrada. El adaptador React importa define de forma diferida en un efecto, por lo que SSR nunca toca el DOM y la hidratación ve el mismo marcado que produjo el servidor.
8. dist/ versionado. Los consumidores usan dependencia git y el tema Shopify copia el bundle a assets/; npm run check:dist falla si dist/ no coincide con las fuentes.
9. Selección visible sin depender del color. El valor seleccionado usa d-btn-primary (relleno) y el resto d-btn-outline, en lugar de la combinación d-btn-outline d-btn-primary del renderer OptionPicker (solo cambia el color del texto). Agotado: tachado; inexistente: borde discontinuo.

Contrato público¶

Documentado en packages/web-components/README.md y resumido en contracts/components.md (sección VariantPicker).

<plt-variant-picker
  name="id"
  selected-variant-id="40001"
  options='[{"name":"Color","values":[{"value":"Red","swatch":{"color":"#c0392b"}}]},{"name":"Size","values":["S","M","L"]}]'
  variants='[{"id":"40001","options":["Red","S"],"available":true,"title":"Red / S"}]'
  labels='{"soldOut":"Agotado","unavailable":"No disponible"}'
>
  <div data-plt-fallback><select name="id">…</select></div>
</plt-variant-picker>

picker.addEventListener("plt:variant-change", ({ detail }) => {
  // detail: { variantId, variant, available, selectedOptions, previousVariantId }
});
picker.variants = refreshedVariants;     // actualización desde el consumidor
picker.selectedVariantId = "40005";      // no emite evento

Adaptadores por plataforma¶

fromStorefrontProduct() reúne variantes de variants, adjacentVariants, selectedOrFirstAvailableVariant y optionValues[].firstSelectableVariant, de modo que la consulta por defecto de Hydrogen basta sin cambiarla.

Fase 5 — Validación¶

npm run check (raíz) ejecuta ahora también el paquete nuevo: typecheck → check:dist → test (Vitest) → test:browser (Playwright).

Validación visual¶

Liquid	Astro	Hydrogen React

Agotado (Liquid, tras elegir Blue / L)	Combinación inexistente (Astro, Green)	Teclado (React, foco en M)

Grupos de la fase 2:

Tienda completa (Liquid)	Carrito (Liquid; idéntico en Astro y React)

Megamenú (Astro)	Filtros activos (React, enrutado en cliente)

Árbol de accesibilidad (igual en los tres): aria-snapshot.yml. Las capturas se regeneran con npm run test:browser -w @playlovetoys/web-components (packages/web-components/examples/.out/screenshots/).

Comparativa Lit vs. implementación existente¶

Medido con npm run size -w @playlovetoys/web-components (esbuild, minificado). Los CE vanilla eliminados se miden desde c8cae0b.

Toda la interactividad compartida (10 elementos, Lit incluido) pesa 14,9 KB gzip, menos que solo el runtime de Alpine (16,2 KB) que hoy carga el tema Liquid. Galería, quick view y navbar pesan más que sus versiones vanilla (≈ 2,9 KB gzip frente a 1,5 KB), pero comparten el runtime con el resto y el navbar incorpora el megamenú que antes reimplementaba cada plataforma.

Conclusión: un CE vanilla aislado y sin estado (galería, toggle) sigue siendo más ligero. Pero una vez que la página carga Lit para los componentes con estado (selector, carrito, filtros), migrar los pequeños cuesta ~1 KB gzip cada uno y unifica el ciclo de vida, el registro, las pruebas y los adaptadores. Por eso este PR los incluye.

Coste de incorporar Lit¶

• Peso: 6,9 KB gzip de runtime de Lit por página. Se comparte entre todos los componentes en el build ESM (un único lit) y en el bundle conjunto (14,9 KB gzip con los 10 elementos).
• Dependencias: lit (runtime). Desarrollo: esbuild, TypeScript, liquidjs, astro, react/react-dom, Playwright, axe-core. npm audit informa de vulnerabilidades solo en dependencias de desarrollo (vitest, stylelint/braces, sharp vía astro), varias previas a este PR.
• CI: Node 22 (requerido por Astro 7; el storefront ya exige ≥ 22.12) y descarga de Chromium. test:browser (49 pruebas en 3 frontends) tarda ~25 s; construir las demos ~3 s.
• Proceso: dist/ versionado y verificado; convención de eventos plt:*; revisar versión única de Lit por página (Lit avisa en modo dev si hay varias).
• Conocimiento: ciclo de vida reactivo de Lit (willUpdate, live, propiedades declaradas con declare y useDefineForClassFields: false).

Riesgos y limitaciones¶

1. Regla Alpine-only en plt-astro-storefront — resuelta. Decisión del 13-10-2026: Lit está permitido en el frontend Astro y Alpine puede sustituirse donde haga falta para dar paso a Web Components. La PDP del storefront adopta <plt-variant-picker> en un PR propio.
2. Validación fuera de producción. Las demos reproducen cada plataforma pero no sustituyen a un tema Shopify real, Oxygen ni el storefront desplegado. liquidjs no es Shopify Liquid: asset_url e image_url están simulados y swatch.color.rgb se asume según la API de Shopify.
3. Límite de variantes en Liquid. product.variants devuelve como máximo 250 variantes; productos mayores necesitan otra fuente de datos.
4. Cambio de diseño al actualizar. Entre el HTML de servidor y la carga del módulo se ve el <select> de respaldo; reservar altura o cargar el módulo pronto para limitar CLS.
5. React 18. El adaptador usa solo APIs comunes a 18 y 19, pero las pruebas corren con React 19; Hydrogen (tina-hydrogen-frontstore) usa React 18.3.
6. Duplicación de Lit si un consumidor mezcla el bundle autocontenido con el build ESM; el registro idempotente evita el error, no el peso.
7. Renderers Astro con comportamiento. Navbar, ProductDetail y ProductQuickView (Astro) importan ../web-components/dist/* en lugar del antiguo JS vanilla del propio paquete. Con npm (dependencia git del repo completo) y con el workspace funciona. Un consumidor pnpm que instale solo path:/packages/design-system (el repo donante keystatic-astro-shopify-hydrogen, hoy fijado a un commit anterior) tendría que instalar también packages/web-components al actualizar el pin. Los renderers Liquid y los consumidores que solo usan CSS no se ven afectados.

Próximos pasos¶

1. Decidir sobre la regla Alpine-only (aceptado: Lit permitido en Astro). La PDP de plt-astro-storefront usa <plt-variant-picker> (aavendano/plt-astro-storefront#7). Siguientes candidatos en ese repo: el CartDrawer (hoy Alpine/fetch), los filtros de colección y el navbar.
2. PR en plt-frontend-liquid sustituyendo el selector Alpine por los snippets y cargando plt-web-components.bundle.js, manteniendo variant:changed como puente durante la transición.
3. PR en tina-hydrogen-frontstore (rama desde ai-dev) sustituyendo OptionPicker/useMegaMenu/QuantitySelector por los adaptadores React y actualizando el pin del DS.
4. Corregir el patrón display:none de los renderers OptionPicker existentes y el contraste de .theme-meta.

Reproducir¶

npm install
npx playwright install chromium   # si no hay Chromium disponible
npm run check                     # todo el workspace
npm run test:browser -w @playlovetoys/web-components
npm run size -w @playlovetoys/web-components