Headless Store UI

Componentes de ecommerce para shadcn/ui

Un superset de shadcn/ui para comercio headless. Importá los componentes desde el workspace compartido @notheadless/ui o usá el registry de código fuente opcional. Están tipados contra @notcommerce/headless-nube-sdk y resuelven reglas de ecommerce que no deberías reescribir en cada tienda.

Principios

Entran datos, salen eventos. Los componentes reciben datos tipados del SDK como props y nunca manejan un token. El fetching se queda en server components y server actions.
Tipos estructurales. Cada componente pide el Pick<Product, …> más acotado que necesita, así que sirve cualquier select que incluya esos campos.
Componibles. Las primitivas (Price, VariantSelector…) leen de ProductProvider cuando está presente, o reciben props cuando las usás sueltas. Bloques como ProductPurchase son solo composiciones de ellas.
Correctos por defecto. “Consultar” en lugar de $0, precios promocionales y de comparación, cantidad limitada a min(99, stock), opciones sin stock deshabilitadas, checkout validado en el servidor y un carrito que sobrevive a los errores.
Nativos de shadcn. Construidos con las primitivas compartidas de @notheadless/ui/primitives/* y los tokens del tema, con atributos data-slot para los estilos y control total de className.

Anatomía de una página de producto

app/products/[handle]/page.tsx

export default async function ProductPage({ params }) {
  const product = await nube.products.findUnique({
    where: { handle: (await params).handle },
    select: { id: true, name: true, handle: true, attributes: true, images: true, variants: true, description: true },
  })
  if (!product) notFound()

  return (
    <ProductProvider product={product}>
      <ProductGallery priority />
      <h1>{product.name}</h1>
      <ProductPurchase>
        <ShippingEstimator quote={quoteShipping} />
      </ProductPurchase>
    </ProductProvider>
  )
}

Componentes

Todos los textos de la UI vienen en español (es-AR) por defecto y se pueden sobrescribir con StoreProvider labels.

Cargando documentación…

Principios

Entran datos, salen eventos. Los componentes reciben datos tipados del SDK como props y nunca manejan un token. El fetching se queda en server components y server actions.

Tipos estructurales. Cada componente pide el Pick<Product, …> más acotado que necesita, así que sirve cualquier select que incluya esos campos.

Componibles. Las primitivas (Price, VariantSelector…) leen de ProductProvider cuando está presente, o reciben props cuando las usás sueltas. Bloques como ProductPurchase son solo composiciones de ellas.

Correctos por defecto. “Consultar” en lugar de $0, precios promocionales y de comparación, cantidad limitada a min(99, stock), opciones sin stock deshabilitadas, checkout validado en el servidor y un carrito que sobrevive a los errores.

Nativos de shadcn. Construidos con las primitivas compartidas de @notheadless/ui/primitives/* y los tokens del tema, con atributos data-slot para los estilos y control total de className.

Anatomía de una página de producto

app/products/[handle]/page.tsx

export default async function ProductPage({ params }) {
  const product = await nube.products.findUnique({
    where: { handle: (await params).handle },
    select: { id: true, name: true, handle: true, attributes: true, images: true, variants: true, description: true },
  })
  if (!product) notFound()

  return (
    <ProductProvider product={product}>
      <ProductGallery priority />
      <h1>{product.name}</h1>
      <ProductPurchase>
        <ShippingEstimator quote={quoteShipping} />
      </ProductPurchase>
    </ProductProvider>
  )
}