@fayz-ai/storefront 0.2.0

package/src/sections.ts

@@ -0,0 +1,69 @@
+import type { HeroVariant } from './theme'
+
+// ---------------------------------------------------------------------------
+// Home-page section blueprint — the storefront's PageConfig equivalent.
+// A template (or the Fayz agent) declares the home as an ordered list of
+// typed sections; HomePage renders them. Every recurring block found in the
+// Nuvemshop research maps to one section type.
+// ---------------------------------------------------------------------------
+
+export interface HeroSlide {
+  title: string
+  subtitle?: string
+  cta?: string
+  href?: string
+  /** Image URL; omit for a gradient placeholder derived from `hue` */
+  image?: string
+  hue?: number
+  /** Editorial boxed copy block (Uyuni) instead of free overlay */
+  boxed?: boolean
+}
+
+export type HomeSection =
+  | { type: 'hero'; variant: HeroVariant; slides: HeroSlide[]; height?: 'tall' | 'medium' }
+  | { type: 'categories'; style: 'bubbles' | 'tiles'; title?: string }
+  | {
+      type: 'products'
+      title: string
+      subtitle?: string
+      /** Small-caps label above the title (e.g. 'curadoria') */
+      eyebrow?: string
+      /** 'sale' = compareAtPrice set; 'new' = newest first; 'all' = catalog order */
+      filter?: 'sale' | 'new' | 'all'
+      limit?: number
+    }
+  | { type: 'benefits'; items: Array<{ icon: string; title: string; text?: string }> }
+  | { type: 'banner'; title: string; subtitle?: string; eyebrow?: string; cta?: string; href?: string; image?: string; hue?: number }
+  | { type: 'manifesto'; title?: string; text: string }
+  | { type: 'testimonials'; title?: string; items: Array<{ quote: string; author: string }> }
+  | { type: 'newsletter'; title?: string; subtitle?: string }
+
+export interface HomeConfig {
+  sections: HomeSection[]
+}
+
+export interface NavLink {
+  label: string
+  to: string
+}
+
+export interface FooterConfig {
+  about?: string
+  contact?: { phone?: string; email?: string; address?: string }
+  social?: Array<{ label: string; href: string }>
+}
+
+/** Wide gradient SVG data-URI — deterministic hero/banner art, no network. */
+export function bannerPlaceholder(label: string, hueA: number, hueB: number, w = 1600, h = 700): string {
+  const svg =
+    `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}">` +
+    `<defs><linearGradient id="g" x1="0" y1="0" x2="1" y2="1">` +
+    `<stop offset="0" stop-color="hsl(${hueA},40%,78%)"/>` +
+    `<stop offset="1" stop-color="hsl(${hueB},45%,55%)"/>` +
+    `</linearGradient></defs>` +
+    `<rect width="${w}" height="${h}" fill="url(#g)"/>` +
+    `<circle cx="${w * 0.8}" cy="${h * 0.3}" r="${h * 0.45}" fill="hsla(${hueB},50%,90%,0.25)"/>` +
+    `<circle cx="${w * 0.15}" cy="${h * 0.85}" r="${h * 0.35}" fill="hsla(${hueA},45%,30%,0.12)"/>` +
+    `</svg>`
+  return `data:image/svg+xml;utf8,${encodeURIComponent(svg)}`
+}

package/src/slot-contracts.ts

@@ -0,0 +1,20 @@
+import { TID } from './testids'
+
+/**
+ * Stable selectors that custom storefront slots must preserve.
+ *
+ * Apps can fully customize the visual tree, but catalog/product-rail slots still
+ * need these anchors so checkout smoke tests, QA, and agents can operate stores.
+ */
+export const productCardSlotContract = {
+  root: { 'data-testid': TID.productCard },
+  name: { 'data-testid': TID.productCardName },
+  priceTestId: TID.productCardPrice,
+  addButton: { 'data-testid': TID.productCardAdd },
+} as const
+
+export const storefrontSlotContracts = {
+  productCard: productCardSlotContract,
+} as const
+
+export type ProductCardSlotContract = typeof productCardSlotContract

package/src/stores/cart.store.ts

@@ -0,0 +1,149 @@
+import { create } from 'zustand'
+import { persist } from 'zustand/middleware'
+import type { Product } from '@fayz-ai/shop/types'
+import { roundCents } from '../format'
+import type { ResolvedStorefrontConfig } from '../config'
+import {
+  formatProductOptionSelection,
+  normalizeProductOptionSelection,
+  productOptionSelectionKey,
+  type ProductOptionSelection,
+} from '../product-options'
+
+export interface CartLine {
+  lineId: string
+  productId: string
+  slug: string
+  name: string
+  sku: string | null
+  options: ProductOptionSelection
+  optionsLabel: string
+  unitPrice: number
+  quantity: number
+  imageUrl: string | null
+  /** inventoryCount at add time — clamps quantity */
+  maxQuantity: number
+}
+
+export interface CartState {
+  lines: CartLine[]
+  discountCode: string | null
+  discountPercent: number
+  isOpen: boolean
+  /** Line most recently added — lets the drawer briefly highlight it. */
+  justAddedLineId: string | null
+  addItem(product: Product, qty?: number, options?: ProductOptionSelection): void
+  setQuantity(lineId: string, qty: number): void
+  removeItem(lineId: string): void
+  applyDiscount(code: string, percent: number): void
+  clearDiscount(): void
+  clear(): void
+  openDrawer(): void
+  closeDrawer(): void
+}
+
+export const useCartStore = create<CartState>()(
+  persist(
+    (set) => ({
+      lines: [],
+      discountCode: null,
+      discountPercent: 0,
+      isOpen: false,
+      justAddedLineId: null,
+
+      addItem: (product, qty = 1, options) =>
+        set((state) => {
+          const normalizedOptions = normalizeProductOptionSelection(options)
+          const optionKey = productOptionSelectionKey(normalizedOptions)
+          const lineId = optionKey ? `${product.id}:${optionKey}` : product.id
+          const existing = state.lines.find((l) => (l.lineId ?? l.productId) === lineId)
+          if (existing) {
+            const nextQty = Math.min(existing.quantity + qty, existing.maxQuantity || Infinity)
+            return {
+              // Auto-open the cart on add — the standard premium "slide-in cart"
+              // signal — and flag the line so the drawer can highlight it.
+              isOpen: true,
+              justAddedLineId: lineId,
+              lines: state.lines.map((l) =>
+                (l.lineId ?? l.productId) === lineId ? { ...l, lineId, quantity: nextQty } : l,
+              ),
+            }
+          }
+          const image = product.images.find((i) => i.isPrimary) ?? product.images[0]
+          const line: CartLine = {
+            lineId,
+            productId: product.id,
+            slug: product.slug,
+            name: product.name,
+            sku: product.sku,
+            options: normalizedOptions,
+            optionsLabel: formatProductOptionSelection(normalizedOptions),
+            unitPrice: product.price,
+            quantity: Math.min(qty, product.inventoryCount || Infinity),
+            imageUrl: image?.url ?? null,
+            maxQuantity: product.inventoryCount,
+          }
+          return { isOpen: true, justAddedLineId: lineId, lines: [...state.lines, line] }
+        }),
+
+      setQuantity: (lineId, qty) =>
+        set((state) => {
+          if (qty <= 0) return { lines: state.lines.filter((l) => (l.lineId ?? l.productId) !== lineId) }
+          return {
+            lines: state.lines.map((l) =>
+              (l.lineId ?? l.productId) === lineId
+                ? { ...l, quantity: Math.min(qty, l.maxQuantity || Infinity) }
+                : l,
+            ),
+          }
+        }),
+
+      removeItem: (lineId) =>
+        set((state) => ({ lines: state.lines.filter((l) => (l.lineId ?? l.productId) !== lineId) })),
+
+      applyDiscount: (code, percent) => set({ discountCode: code, discountPercent: percent }),
+      clearDiscount: () => set({ discountCode: null, discountPercent: 0 }),
+      clear: () => set({ lines: [], discountCode: null, discountPercent: 0 }),
+      openDrawer: () => set({ isOpen: true }),
+      closeDrawer: () => set({ isOpen: false, justAddedLineId: null }),
+    }),
+    {
+      name: 'fayz.storefront.cart.v1',
+      partialize: (state) => ({
+        lines: state.lines,
+        discountCode: state.discountCode,
+        discountPercent: state.discountPercent,
+      }),
+    },
+  ),
+)
+
+// ---------------------------------------------------------------------------
+// Money selectors — the single place cart math happens. Checkout passes these
+// exact values to createOrder so drawer totals always match order totals.
+// ---------------------------------------------------------------------------
+
+export const selectCount = (s: Pick<CartState, 'lines'>): number =>
+  s.lines.reduce((n, l) => n + l.quantity, 0)
+
+export const selectSubtotal = (s: Pick<CartState, 'lines'>): number =>
+  roundCents(s.lines.reduce((sum, l) => sum + l.unitPrice * l.quantity, 0))
+
+export const selectDiscountTotal = (s: Pick<CartState, 'lines' | 'discountPercent'>): number =>
+  roundCents(selectSubtotal(s) * (s.discountPercent / 100))
+
+export const selectShipping = (
+  s: Pick<CartState, 'lines'>,
+  cfg: ResolvedStorefrontConfig,
+): number => {
+  if (s.lines.length === 0) return 0
+  const subtotal = selectSubtotal(s)
+  if (cfg.shipping.freeAbove != null && subtotal >= cfg.shipping.freeAbove) return 0
+  return cfg.shipping.flatRate
+}
+
+export const selectTotal = (
+  s: Pick<CartState, 'lines' | 'discountPercent'>,
+  cfg: ResolvedStorefrontConfig,
+): number =>
+  roundCents(selectSubtotal(s) - selectDiscountTotal(s) + selectShipping(s, cfg))

package/src/stores/catalog.store.ts

@@ -0,0 +1,39 @@
+import { create } from 'zustand'
+
+export type CatalogSort = 'newest' | 'price-asc' | 'price-desc' | 'name'
+
+export interface CatalogState {
+  search: string
+  categoryId: string | null
+  priceMin: number | null
+  priceMax: number | null
+  inStockOnly: boolean
+  sort: CatalogSort
+  setSearch(search: string): void
+  setCategoryId(categoryId: string | null): void
+  setPriceMin(priceMin: number | null): void
+  setPriceMax(priceMax: number | null): void
+  setInStockOnly(inStockOnly: boolean): void
+  setSort(sort: CatalogSort): void
+  reset(): void
+}
+
+const initial = {
+  search: '',
+  categoryId: null,
+  priceMin: null,
+  priceMax: null,
+  inStockOnly: false,
+  sort: 'newest' as CatalogSort,
+}
+
+export const useCatalogStore = create<CatalogState>()((set) => ({
+  ...initial,
+  setSearch: (search) => set({ search }),
+  setCategoryId: (categoryId) => set({ categoryId }),
+  setPriceMin: (priceMin) => set({ priceMin }),
+  setPriceMax: (priceMax) => set({ priceMax }),
+  setInStockOnly: (inStockOnly) => set({ inStockOnly }),
+  setSort: (sort) => set({ sort }),
+  reset: () => set(initial),
+}))

package/src/stores/session.store.ts

@@ -0,0 +1,28 @@
+import { create } from 'zustand'
+import { persist } from 'zustand/middleware'
+
+// Customer session state. Identity is established through the shared
+// @fayz-ai/auth AuthAdapter (see ../auth.ts) — this store only mirrors the
+// linked ShopCustomer for synchronous UI access.
+
+export interface SessionState {
+  customerId: string | null
+  email: string | null
+  name: string | null
+  setSession(session: { customerId: string; email: string; name?: string | null }): void
+  signOut(): void
+}
+
+export const useSessionStore = create<SessionState>()(
+  persist(
+    (set) => ({
+      customerId: null,
+      email: null,
+      name: null,
+      setSession: ({ customerId, email, name }) =>
+        set({ customerId, email, name: name ?? null }),
+      signOut: () => set({ customerId: null, email: null, name: null }),
+    }),
+    { name: 'fayz.storefront.session.v1' },
+  ),
+)

package/src/stores/toast.store.ts

@@ -0,0 +1,43 @@
+import { create } from 'zustand'
+
+export type ToastVariant = 'success' | 'error' | 'info'
+
+export interface Toast {
+  id: string
+  title: string
+  description?: string
+  variant: ToastVariant
+  durationMs: number
+}
+
+interface ToastState {
+  toasts: Toast[]
+  push(input: { title: string; description?: string; variant?: ToastVariant; durationMs?: number }): string
+  dismiss(id: string): void
+}
+
+let seq = 0
+
+export const useToastStore = create<ToastState>((set) => ({
+  toasts: [],
+  push: (input) => {
+    const id = `toast-${++seq}-${Date.now()}`
+    const toast: Toast = {
+      id,
+      title: input.title,
+      description: input.description,
+      variant: input.variant ?? 'info',
+      durationMs: input.durationMs ?? 3400,
+    }
+    set((s) => ({ toasts: [...s.toasts, toast] }))
+    return id
+  },
+  dismiss: (id) => set((s) => ({ toasts: s.toasts.filter((t) => t.id !== id) })),
+}))
+
+/** Imperative toast API — callable from components, store actions, or workflows. */
+export const toast = {
+  success: (title: string, description?: string) => useToastStore.getState().push({ title, description, variant: 'success' }),
+  error: (title: string, description?: string) => useToastStore.getState().push({ title, description, variant: 'error' }),
+  info: (title: string, description?: string) => useToastStore.getState().push({ title, description, variant: 'info' }),
+}

package/src/testids.ts

@@ -0,0 +1,103 @@
+// Single source of truth for e2e selectors. Components import from here;
+// Playwright specs assert against the same constants — they cannot drift.
+export const TID = {
+  // header
+  headerSearch: 'header-search',
+  cartButton: 'cart-button',
+  cartCount: 'cart-count',
+  accountLink: 'account-link',
+  accountDropdown: 'account-dropdown',
+  announcementBar: 'announcement-bar',
+  navLink: (label: string) => `nav-${label.toLowerCase().replace(/\s+/g, '-')}`,
+  navCategory: (slug: string) => `nav-cat-${slug}`,
+  accountName: 'account-name',
+  // home sections
+  hero: 'home-hero',
+  heroPrev: 'hero-prev',
+  heroNext: 'hero-next',
+  categoryShowcase: 'category-showcase',
+  productRail: 'product-rail',
+  benefits: 'benefits-row',
+  promoBanner: 'promo-banner',
+  manifesto: 'manifesto',
+  testimonials: 'testimonials',
+  newsletter: 'newsletter',
+  newsletterEmail: 'newsletter-email',
+  newsletterSubmit: 'newsletter-submit',
+  newsletterDone: 'newsletter-done',
+  // catalog
+  productGrid: 'product-grid',
+  productCard: 'product-card',
+  productCardName: 'product-card-name',
+  productCardPrice: 'product-card-price',
+  productCardAdd: 'product-card-add',
+  badgeSale: 'badge-sale',
+  badgeSoldout: 'badge-soldout',
+  // filters
+  filterCategory: (slug: string) => `filter-category-${slug}`,
+  filterPriceMin: 'filter-price-min',
+  filterPriceMax: 'filter-price-max',
+  filterInstock: 'filter-instock',
+  sortSelect: 'sort-select',
+  filtersClear: 'filters-clear',
+  // product detail
+  pdpName: 'pdp-name',
+  pdpPrice: 'pdp-price',
+  pdpComparePrice: 'pdp-compare-price',
+  pdpDescription: 'pdp-description',
+  productOptionGroup: (id: string) => `product-option-${id.toLowerCase().replace(/\s+/g, '-')}`,
+  productOptionValue: (id: string, value: string) => `product-option-${id.toLowerCase().replace(/\s+/g, '-')}-${value.toLowerCase().replace(/\s+/g, '-')}`,
+  pdpQtyInput: 'pdp-qty-input',
+  pdpAddToCart: 'pdp-add-to-cart',
+  // cart
+  cartDrawer: 'cart-drawer',
+  cartLine: 'cart-line',
+  lineQty: 'line-qty',
+  lineInc: 'line-inc',
+  lineDec: 'line-dec',
+  lineRemove: 'line-remove',
+  cartSubtotal: 'cart-subtotal',
+  discountInput: 'discount-input',
+  discountApply: 'discount-apply',
+  discountRow: 'discount-row',
+  discountError: 'discount-error',
+  cartShipping: 'cart-shipping',
+  shippingProgress: 'shipping-progress',
+  cartTotal: 'cart-total',
+  goCheckout: 'go-checkout',
+  cartEmpty: 'cart-empty',
+  // checkout
+  checkoutEmail: 'checkout-email',
+  checkoutName: 'checkout-name',
+  checkoutStreet: 'checkout-street',
+  checkoutCity: 'checkout-city',
+  checkoutZip: 'checkout-zip',
+  checkoutCard: 'checkout-card',
+  checkoutExpiry: 'checkout-expiry',
+  checkoutCvc: 'checkout-cvc',
+  placeOrder: 'place-order',
+  checkoutError: 'checkout-error',
+  checkoutProcessing: 'checkout-processing',
+  // confirmation
+  orderNumber: 'order-number',
+  orderStatus: 'order-status',
+  orderTracking: 'order-tracking',
+  orderTrackingStep: (step: string) => `order-tracking-step-${step}`,
+  orderTotal: 'order-total',
+  viewPurchases: 'view-purchases',
+  // account
+  customerAccountShell: 'customer-account-shell',
+  customerAccountMenu: 'customer-account-menu',
+  orderDetail: 'order-detail',
+  authTabSignin: 'auth-tab-signin',
+  authTabSignup: 'auth-tab-signup',
+  signinEmail: 'signin-email',
+  signinPassword: 'signin-password',
+  signinName: 'signin-name',
+  signinSubmit: 'signin-submit',
+  authError: 'auth-error',
+  purchasesList: 'purchases-list',
+  purchaseItem: 'purchase-item',
+  purchasesEmpty: 'purchases-empty',
+  signout: 'signout',
+} as const

package/src/theme.ts

@@ -0,0 +1,160 @@
+import React, { useEffect } from 'react'
+
+// ---------------------------------------------------------------------------
+// StorefrontTheme — the storefront counterpart of SaasTheme.
+// Personalizes colors (HSL token triplets), typography (Google Fonts pairing),
+// radius and layout properties via CSS custom properties, so every @fayz-ai/ui
+// token class (bg-background, text-primary, ...) picks the brand up for free.
+//
+// Derived from the Nuvemshop template research (docs/storefront-templates-research.md):
+// the personalization axes are palette, font pairing, radius, header treatment,
+// hero style and product-card style.
+// ---------------------------------------------------------------------------
+
+export type StorefrontRadius = 'none' | 'soft' | 'round' | 'pill'
+export type HeaderVariant = 'classic' | 'centered' | 'search' | 'minimal'
+export type HeroVariant = 'banner' | 'split' | 'slider'
+export type CardStyle = 'card' | 'editorial'
+
+export interface StorefrontThemeColors {
+  /** HSL triplets, e.g. '40 20% 94%' — same convention as SaasTheme */
+  background?: string
+  foreground?: string
+  primary?: string
+  primaryForeground?: string
+  card?: string
+  cardForeground?: string
+  muted?: string
+  mutedForeground?: string
+  border?: string
+  /** Header treatment — dark headers (Brasília) set these */
+  headerBackground?: string
+  headerForeground?: string
+  /** Announcement bar */
+  announcementBackground?: string
+  announcementForeground?: string
+}
+
+export interface StorefrontThemeFont {
+  /** Display font for headings, e.g. 'Marcellus' */
+  heading: string
+  /** Body font, e.g. 'Rubik' */
+  body: string
+  /** Google Fonts families to load (defaults to heading+body) */
+  googleFonts?: string[]
+  /** Fallback stack — default sans-serif; use 'serif' for editorial themes */
+  fallback?: 'sans-serif' | 'serif'
+}
+
+export interface StorefrontTheme {
+  name: string
+  colors?: StorefrontThemeColors
+  font?: StorefrontThemeFont
+  radius?: StorefrontRadius
+  /** Layout personality */
+  header?: {
+    variant?: HeaderVariant
+    /** Uppercase nav links (premium retail tone) */
+    uppercaseNav?: boolean
+  }
+  productCard?: {
+    style?: CardStyle
+    imageAspect?: 'square' | 'portrait'
+  }
+  /** Uppercase CTA buttons with letter-spacing (Uyuni/Flex tone) */
+  uppercaseButtons?: boolean
+}
+
+const RADIUS_MAP: Record<StorefrontRadius, { button: string; card: string; input: string }> = {
+  none: { button: '0px', card: '0px', input: '0px' },
+  soft: { button: '6px', card: '10px', input: '6px' },
+  round: { button: '10px', card: '16px', input: '10px' },
+  pill: { button: '999px', card: '20px', input: '999px' },
+}
+
+const COLOR_VAR_MAP: Record<keyof StorefrontThemeColors, string> = {
+  background: '--background',
+  foreground: '--foreground',
+  primary: '--primary',
+  primaryForeground: '--primary-foreground',
+  card: '--card',
+  cardForeground: '--card-foreground',
+  muted: '--muted',
+  mutedForeground: '--muted-foreground',
+  border: '--border',
+  headerBackground: '--sf-header-bg',
+  headerForeground: '--sf-header-fg',
+  announcementBackground: '--sf-announcement-bg',
+  announcementForeground: '--sf-announcement-fg',
+}
+
+export function themeToCss(theme: StorefrontTheme): string {
+  const lines: string[] = []
+
+  for (const [key, cssVar] of Object.entries(COLOR_VAR_MAP) as [keyof StorefrontThemeColors, string][]) {
+    const value = theme.colors?.[key]
+    if (value) lines.push(`${cssVar}: ${value};`)
+  }
+  // Header defaults to the page background unless the theme sets one
+  if (!theme.colors?.headerBackground && theme.colors?.background) {
+    lines.push(`--sf-header-bg: ${theme.colors.background};`)
+  }
+  if (!theme.colors?.headerForeground && theme.colors?.foreground) {
+    lines.push(`--sf-header-fg: ${theme.colors.foreground};`)
+  }
+
+  if (theme.font) {
+    const fallback = theme.font.fallback ?? 'sans-serif'
+    lines.push(`--font-family: '${theme.font.body}', ${fallback};`)
+    lines.push(`--sf-font-heading: '${theme.font.heading}', ${fallback};`)
+  }
+
+  const radius = RADIUS_MAP[theme.radius ?? 'soft']
+  lines.push(`--button-radius: ${radius.button};`)
+  lines.push(`--card-radius: ${radius.card};`)
+  lines.push(`--input-radius: ${radius.input};`)
+  lines.push(`--sf-radius-button: ${radius.button};`)
+  lines.push(`--sf-radius-card: ${radius.card};`)
+  lines.push(`--sf-radius-input: ${radius.input};`)
+
+  let css = `:root {\n  ${lines.join('\n  ')}\n}\n`
+  css += `body { font-family: var(--font-family); }\n`
+  css += `h1, h2, h3, h4, .sf-heading { font-family: var(--sf-font-heading, var(--font-family)); }\n`
+  if (theme.uppercaseButtons) {
+    css += `.sf-cta { text-transform: uppercase; letter-spacing: 0.08em; }\n`
+  }
+  if (theme.header?.uppercaseNav) {
+    css += `.sf-nav-link { text-transform: uppercase; letter-spacing: 0.06em; font-size: 0.8rem; }\n`
+  }
+  return css
+}
+
+function googleFontsHref(theme: StorefrontTheme): string | null {
+  if (!theme.font) return null
+  const families = theme.font.googleFonts ?? [theme.font.heading, theme.font.body]
+  const unique = [...new Set(families)]
+  const params = unique
+    .map((f) => `family=${encodeURIComponent(f).replace(/%20/g, '+')}:wght@300;400;500;600;700`)
+    .join('&')
+  return `https://fonts.googleapis.com/css2?${params}&display=swap`
+}
+
+/** Injects theme CSS variables + Google Fonts. Mount once inside the app root. */
+export function StorefrontThemeStyle({ theme }: { theme: StorefrontTheme }) {
+  const fontsHref = googleFontsHref(theme)
+
+  useEffect(() => {
+    if (!fontsHref) return
+    const id = 'sf-theme-fonts'
+    let link = document.getElementById(id) as HTMLLinkElement | null
+    if (!link) {
+      link = document.createElement('link')
+      link.id = id
+      link.rel = 'stylesheet'
+      document.head.appendChild(link)
+    }
+    link.href = fontsHref
+  }, [fontsHref])
+
+  return React.createElement('style', { 'data-sf-theme': theme.name }, themeToCss(theme))
+}