@thorprovider/storefront 0.3.1 → 0.4.0-mvp.2

package/assets/templates/app/lib/__STOREFRONT__/shell/content.ts

@@ -0,0 +1,120 @@
+// Thor Commerce shell content: brand accents, surface classes, and footer copy.
+//
+// User-owned shell content — reconcile seeds this file once and never rewrites
+// it, so your edits survive `storefront sync`. Plain data only: no React and no
+// server imports.
+//
+// Neutral defaults only: no delivery, shipping, or promo promise is made here,
+// and footer links point only at routes the generated storefront actually
+// serves (`/`, `/categories`, `/checkout`, and the static pages `/contact`,
+// `/about`, `/terms`, `/privacy`). Brand colors and copy belong
+// in your own content, never in the package.
+//
+// The scaffold ships no newsletter submit callback, so the footer newsletter is
+// omitted by default. A content-only `newsletter` is swallowed by the block
+// (no form renders); wiring a real host callback to enable it is an external
+// integration, out of scope for the scaffold.
+
+export interface ShellAccent {
+  /** Trailing segment of the site-name wordmark to render with the accent. */
+  text: string
+  /** Consumer-supplied classes for the accent span (e.g. a brand color token). */
+  className?: string
+}
+
+export interface ShellLink {
+  label: string
+  /** A route the storefront actually serves. Omit for a non-link label. */
+  href?: string
+}
+
+export interface ShellLinkColumn {
+  title: string
+  links: ShellLink[]
+}
+
+export interface ShellNewsletter {
+  placeholder?: string
+  buttonLabel: string
+}
+
+/**
+ * Optional trailing accent for the navbar wordmark, e.g. the "Cuba" in
+ * "ElectroCuba". Leave `undefined` to render the wordmark in one colour. The
+ * accent only applies when `text` is a trailing segment of the site name.
+ */
+export const logoAccent: ShellAccent | undefined = undefined
+
+/**
+ * Optional trailing accent for the footer brand name. Same trailing-segment
+ * rule as `logoAccent`.
+ */
+export const brandAccent: ShellAccent | undefined = undefined
+
+/**
+ * Optional classes merged onto the navbar's outer surface (e.g.
+ * `bg-brand-nav text-brand-nav-foreground`). Leave `undefined` for the default.
+ */
+export const navbarClassName: string | undefined = undefined
+
+/**
+ * Optional classes merged onto the footer's outer surface. Leave `undefined`
+ * for the default.
+ */
+export const footerClassName: string | undefined = undefined
+
+/** Neutral footer brand description. No delivery/shipping promise. */
+export const brandDescription: string =
+  'Catálogo en línea de productos para tu hogar y tu negocio.'
+
+/**
+ * Optional navbar utility-strip note (e.g. `'Nuevo horario de atención de 9 a
+ * 18 h'`). Empty by default: while it is empty and there are no utility links,
+ * the strip is not rendered, so a fresh storefront shows no note. Set a real
+ * note here to display it.
+ */
+export const shippingNote: string = ''
+
+/** Neutral footer links — only routes the storefront serves; no dead `#` links. */
+export const linkColumns: ShellLinkColumn[] = [
+  {
+    title: 'Comprar',
+    links: [
+      { label: 'Inicio', href: '/' },
+      { label: 'Todas las categorías', href: '/categories' },
+      { label: 'Finalizar compra', href: '/checkout' },
+    ],
+  },
+  {
+    title: 'Información',
+    links: [
+      { label: 'Contacto', href: '/contact' },
+      { label: 'Sobre nosotros', href: '/about' },
+      { label: 'Términos y condiciones', href: '/terms' },
+      { label: 'Política de privacidad', href: '/privacy' },
+    ],
+  },
+]
+
+/**
+ * Footer newsletter content. The scaffold has no working submit handler, so it
+ * is omitted by default (`false`). Setting it without a host-provided callback
+ * renders no form — never a fake one.
+ */
+export const newsletter: false | ShellNewsletter = false
+
+// Primary destinations for the mobile bottom navigation. Only routes the
+// storefront actually serves; the icons come from the shared category icon set.
+export interface ShellBottomNavItem {
+  id?: string
+  label: string
+  href: string
+  icon?: string
+}
+
+export const mobileBottomNavItems: ShellBottomNavItem[] = [
+  { id: 'home', label: 'Inicio', href: '/', icon: 'home' },
+  { id: 'categories', label: 'Categorías', href: '/categories', icon: 'store' },
+  { id: 'cart', label: 'Carrito', href: '/cart', icon: 'boxes' },
+  { id: 'account', label: 'Cuenta', href: '/account', icon: 'shield' },
+]

package/assets/templates/app/lib/__STOREFRONT__/shell/props.ts

@@ -0,0 +1,38 @@
+// Thor Commerce shell props: the shell chrome element props composed from the
+// user-owned shell content. Reconcile seeds this file once and never rewrites
+// it; the derived spec (../spec/index.ts) imports these objects and binds them
+// into the shell element tree, so edits here survive `storefront sync`.
+// Plain data only: no React and no server imports.
+
+import {
+  brandAccent,
+  brandDescription,
+  footerClassName,
+  linkColumns,
+  logoAccent,
+  navbarClassName,
+  newsletter,
+  shippingNote,
+} from './content'
+
+export const navbarShellProps = {
+  logoAccent,
+  className: navbarClassName,
+  // Optional utility-strip note. Empty by default, so the strip renders only
+  // once a real note (or a utility link) is configured.
+  shippingNote,
+  // Global navigation search is held until a verified backend search contract
+  // exists (E2 task 5.4), so the generated storefront presents NO search
+  // control. A merchant may set this to `true` to opt in once the contract is
+  // verified; the `Navbar4` block still defaults to visible for legacy
+  // consumers that do not set this prop.
+  showSearch: false,
+}
+
+export const footerShellProps = {
+  brandAccent,
+  brandDescription,
+  linkColumns,
+  className: footerClassName,
+  ...(newsletter ? { newsletter } : {}),
+}

package/assets/templates/app/lib/__STOREFRONT__/spec/index.ts

@@ -3,23 +3,133 @@
 // Routes are derived from the view barrel; adding a view never edits this file.
 
 import type { NextAppSpec } from '@json-render/next'
+import { storefrontInitialState } from '../state'
 import { views } from '../views'
+import { footerShellProps, navbarShellProps } from '../shell/props'
+import { mobileBottomNavItems } from '../shell/content'
+import { mountedFeatureConfigs, mountedFeatureNames } from '../composition'
 import type { StorefrontElement } from './types'
 
 export type { StorefrontElement }
 
+// The spec's state is a plain record; spreading the typed initial state keeps
+// the single source of truth in ../state while satisfying the index signature.
+const initialState: Record<string, unknown> = { ...storefrontInitialState }
+
 const routes = Object.fromEntries(
-  views.map((view) => [
-    view.route.path,
-    {
-      layout: view.route.layout,
-      loader: view.route.loaderName,
-      metadata: view.route.metadata,
-      ...view.route.entry,
-    },
-  ]),
+  views.flatMap((view) => {
+    // A view declares one route or several; normalise to an array and flatten so
+    // a multi-route view (content-driven static pages) contributes one page per
+    // declared route while a single-route view is unchanged.
+    const viewRoutes = Array.isArray(view.route) ? view.route : [view.route]
+    return viewRoutes.map((route) => [
+      route.path,
+      {
+        layout: route.layout,
+        loader: route.loaderName,
+        metadata: route.metadata,
+        ...route.entry,
+      },
+    ])
+  }),
 )
 
+// The default layout is the storefront chrome shared by every page: the
+// system notice region sits in the notices slot (always first, above the
+// header), the announcement banner and navbar live in the header slot, and the
+// footer in the footer slot. The cart is a lateral panel owned by the navbar
+// (opened by the navbar icon or a successful add), never an inline element of
+// the shell, so page content is never followed by a duplicated cart. This
+// mirrors the reference app so a fresh scaffold ships a real storefront, not a
+// bare page.
+// The navigability feature contributes its chrome only when it is installed.
+// `mountedFeatureNames` is the general presence seam (unfiltered by the catalog
+// boundary), so a removed feature leaves no dangling skip link, back-to-top, or
+// bottom navigation behind.
+const hasNavigability = mountedFeatureNames.includes('navigability')
+const navigabilityConfig = (mountedFeatureConfigs['navigability'] ?? {}) as {
+  showBackToTop?: boolean
+}
+const showBackToTop = navigabilityConfig.showBackToTop !== false
+
+const shellElements: Record<string, StorefrontElement> = {
+  // Navigability chrome, present only when the feature is installed. The skip
+  // link is the first focusable element (rendered before the notices); the
+  // back-to-top and mobile bottom navigation are fixed-position aids.
+  ...(hasNavigability
+    ? {
+        skipToContent: {
+          type: 'SkipToContent',
+          props: { targetId: 'main-content' },
+        },
+        ...(showBackToTop
+          ? {
+              backToTop: {
+                type: 'BackToTop',
+                props: { label: 'Volver arriba' },
+              },
+            }
+          : {}),
+        mobileBottomNav: {
+          type: 'MobileBottomNav',
+          props: {
+            items: mobileBottomNavItems,
+            ariaLabel: 'Navegación principal',
+          },
+        },
+      }
+    : {}),
+  // Reserved top region for system/status messages. Only the shell layout
+  // references it, so it renders once and always as the first element.
+  notice: {
+    type: 'SystemNotice',
+    props: {},
+  },
+  banner: {
+    type: 'Banner',
+    props: {
+      badge: 'Novedades',
+      message: 'Descubre el catálogo de __SITE_NAME__.',
+      href: '/categories',
+      linkLabel: 'Ver catálogo',
+    },
+    visible: { $state: '/bannerDismissed', not: true },
+    on: { dismissBanner: { action: 'dismissBanner' } },
+  },
+  navbar: {
+    type: 'StorefrontNavbar',
+    props: {
+      storeCategories: { $state: '/navCategories' },
+      // No shipping/delivery/COD note is shipped by default; the note comes
+      // from the user-owned shell seam (`...navbarShellProps` below) and is
+      // empty unless the merchant sets one, so no placeholder strip renders.
+      utilityLinks: [],
+      logoText: '__SITE_NAME__',
+      logoHref: '/',
+      // Optional wordmark accent and surface classes, configured in the
+      // user-owned shell seam. Spread last so merchant edits win.
+      ...navbarShellProps,
+    },
+    on: {
+      openCart: { action: 'openCart' },
+      goToCart: { action: 'goToCart' },
+      goToCheckout: { action: 'goToCheckout' },
+      applyQuantityDelta: { action: 'applyQuantityDelta' },
+      removeFromCart: { action: 'removeFromCart' },
+    },
+  },
+  footer: {
+    type: 'Footer',
+    props: {
+      brandName: '__SITE_NAME__',
+      // Footer brand description, links, accent, and surface classes all come
+      // from the user-owned shell seam. Spread last so merchant edits win; no
+      // delivery/shipping promise and no dead `#` link is shipped by default.
+      ...footerShellProps,
+    },
+  },
+}
+
 export const __STOREFRONT_CAMEL__Spec: NextAppSpec = {
   metadata: {
     title: {
@@ -28,7 +138,7 @@ export const __STOREFRONT_CAMEL__Spec: NextAppSpec = {
     },
     description: 'Tienda online de __SITE_NAME__.',
   },
-  state: {},
+  state: initialState,
   layouts: {
     default: {
       root: 'layout',
@@ -36,11 +146,20 @@ export const __STOREFRONT_CAMEL__Spec: NextAppSpec = {
         layout: {
           type: 'Layout',
           props: {},
+          slots: {
+            ...(hasNavigability
+              ? { chrome: ['skipToContent', 'backToTop', 'mobileBottomNav'] }
+              : {}),
+            notices: ['notice'],
+            header: ['banner', 'navbar'],
+            footer: ['footer'],
+          },
           children: ['slot'],
         },
         // The page content is injected at the Slot element by @json-render/next.
         // Without it the rendered layout drops the page and the store looks empty.
         slot: { type: 'Slot', props: {}, children: [] },
+        ...shellElements,
       },
     },
   },

package/assets/templates/app/lib/__STOREFRONT__/spec/page-root.ts

@@ -19,7 +19,11 @@ export const pageRoot = (
   page: {
     root: id,
     elements: {
-      [id]: { type: 'Layout', props: {}, children },
+      // `Page` is a neutral container, not the shell `Layout`: the shell is
+      // already rendered by the route's layoutSpec, so nesting another Layout
+      // here would duplicate chrome (header/footer/main) and any shell-only
+      // notices.
+      [id]: { type: 'Page', props: {}, children },
       ...elements,
     },
   },

package/assets/templates/app/lib/__STOREFRONT__/spec/seo.ts

@@ -0,0 +1,191 @@
+// Generated by Thor Commerce storefront (template: assets/templates/app/lib/__STOREFRONT__/spec/seo.ts)
+// Pure SEO helpers shared by the seeded-once `app/sitemap.ts` and `app/robots.ts`
+// host files. Kept free of Next.js, React, and env imports so the logic is
+// testable at the source and the host files stay thin.
+
+import type { EntitySeo } from '@thorprovider/runtime/contracts'
+import {
+  mapCategoryEntityToSeo,
+  mapProductEntityToSeo,
+} from '@thorprovider/runtime/contracts'
+
+/** The routes the storefront can serve as fixed pages (no dynamic `[` segment). */
+export function fixedRoutePaths(routes: Record<string, unknown>): string[] {
+  return Object.keys(routes).filter((path) => !path.includes('['))
+}
+
+/**
+ * Absolute sitemap URLs for the fixed routes. Emits nothing when no site URL is
+ * configured, so no canonical URL is invented.
+ */
+export function sitemapUrls(
+  routes: Record<string, unknown>,
+  siteUrl: string | undefined,
+): string[] {
+  if (!siteUrl) return []
+  return fixedRoutePaths(routes).map((path) => new URL(path, siteUrl).toString())
+}
+
+/** Absolute URL of the sitemap for `robots.txt`, or undefined without a site URL. */
+export function robotsSitemapUrl(siteUrl: string | undefined): string | undefined {
+  return siteUrl ? new URL('/sitemap.xml', siteUrl).toString() : undefined
+}
+
+/**
+ * Surfaces that are never public: they require a shopper session or hold
+ * checkout state and must not be indexed or listed in the sitemap.
+ */
+export const PRIVATE_ROUTE_PREFIXES = ['/account', '/checkout'] as const
+
+/** True when a path is (or is nested under) a private surface. */
+export function isPrivatePath(path: string): boolean {
+  return PRIVATE_ROUTE_PREFIXES.some(
+    (prefix) => path === prefix || path.startsWith(`${prefix}/`),
+  )
+}
+
+/**
+ * The paths `robots.txt` disallows: the fixed private surfaces plus any private
+ * path the known route set declares. Public routes are never returned.
+ */
+export function robotsDisallowPaths(routes: Record<string, unknown>): string[] {
+  const paths = new Set<string>(PRIVATE_ROUTE_PREFIXES)
+  for (const path of Object.keys(routes)) {
+    if (isPrivatePath(path)) paths.add(path)
+  }
+  return [...paths]
+}
+
+/**
+ * Per-route entity-SEO extractors keyed by the route's loader name. Each runs
+ * after the same request-scoped loader as the page and maps the real loaded
+ * entity through the pure `@thorprovider/runtime/contracts` mappers. The route
+ * prefix is supplied here because the runtime stays route-agnostic.
+ */
+export const entitySeoExtractors: Record<
+  string,
+  (data: Record<string, unknown>) => EntitySeo | undefined
+> = {
+  product: (data) =>
+    mapProductEntityToSeo(data.selectedProduct, { pathPrefix: '/products' }),
+  category: (data) =>
+    mapCategoryEntityToSeo(data.categoryEntity, { pathPrefix: '/categories' }),
+}
+
+/** A public catalog entity referenced by its stable id and public path. */
+export interface PublicEntityRef {
+  id: string
+  path: string
+}
+
+/** One page of public entities plus the cursor for the next page, if any. */
+export interface PublicEntityPage {
+  items: PublicEntityRef[]
+  nextCursor?: string
+}
+
+/** A page-fetching callback for the bounded entity enumeration. */
+export type PublicEntityPageFetcher = (
+  cursor: string | undefined,
+) => Promise<PublicEntityPage>
+
+/** Explicit reason an enumeration did not complete. */
+export type SitemapEnumerationFailure =
+  | { kind: 'enumeration'; message: string }
+  | { kind: 'bound'; maxPages: number }
+  | { kind: 'cycle'; id: string }
+
+export type SitemapEnumerationResult =
+  | { ok: true; entities: PublicEntityRef[] }
+  | { ok: false; failure: SitemapEnumerationFailure }
+
+/** The traversal bound: an enumeration that exceeds it fails, never truncates. */
+export const DEFAULT_SITEMAP_MAX_PAGES = 100
+
+/**
+ * Enumerate public entities across pagination, de-duplicated by id, with a
+ * visited-id cycle guard and a maximum-page bound. A fetch failure, a bound hit,
+ * or a repeated id/cursor returns an explicit typed failure instead of an
+ * apparently-complete or truncated list.
+ */
+export async function enumeratePublicEntities(
+  fetchPage: PublicEntityPageFetcher,
+  options: { maxPages?: number } = {},
+): Promise<SitemapEnumerationResult> {
+  const maxPages = options.maxPages ?? DEFAULT_SITEMAP_MAX_PAGES
+  const seenIds = new Set<string>()
+  const seenCursors = new Set<string>()
+  const entities: PublicEntityRef[] = []
+  let cursor: string | undefined
+
+  for (let pages = 0; ; pages += 1) {
+    if (pages >= maxPages) {
+      return { ok: false, failure: { kind: 'bound', maxPages } }
+    }
+
+    let page: PublicEntityPage
+    try {
+      page = await fetchPage(cursor)
+    } catch (error) {
+      return {
+        ok: false,
+        failure: {
+          kind: 'enumeration',
+          message: error instanceof Error ? error.message : String(error),
+        },
+      }
+    }
+
+    for (const item of page.items) {
+      if (seenIds.has(item.id)) {
+        return { ok: false, failure: { kind: 'cycle', id: item.id } }
+      }
+      seenIds.add(item.id)
+      entities.push(item)
+    }
+
+    const next = page.nextCursor
+    if (next === undefined || next === '') {
+      return { ok: true, entities }
+    }
+    if (seenCursors.has(next)) {
+      return { ok: false, failure: { kind: 'cycle', id: next } }
+    }
+    seenCursors.add(next)
+    cursor = next
+  }
+}
+
+/**
+ * Raised by `app/sitemap.ts` when enumeration fails, so the route responds with
+ * a non-success instead of an apparently-complete sitemap.
+ */
+export class SitemapEnumerationError extends Error {
+  readonly failure: SitemapEnumerationFailure
+  constructor(failure: SitemapEnumerationFailure) {
+    super(`Sitemap enumeration failed (${failure.kind})`)
+    this.name = 'SitemapEnumerationError'
+    this.failure = failure
+  }
+}
+
+/**
+ * Combine the fixed public routes with the enumerated public entities into
+ * de-duplicated absolute sitemap entries. Private surfaces are never listed.
+ */
+export function buildSitemapEntries(input: {
+  routes: Record<string, unknown>
+  siteUrl: string
+  entities: readonly PublicEntityRef[]
+}): { url: string }[] {
+  const urls = new Set<string>()
+  for (const path of fixedRoutePaths(input.routes)) {
+    if (!isPrivatePath(path)) urls.add(new URL(path, input.siteUrl).toString())
+  }
+  for (const entity of input.entities) {
+    if (!isPrivatePath(entity.path)) {
+      urls.add(new URL(entity.path, input.siteUrl).toString())
+    }
+  }
+  return [...urls].map((url) => ({ url }))
+}