@thorprovider/blocks 0.1.0

package/docs/standards/data-contracts.md

@@ -0,0 +1,70 @@
+---
+title: "Block data contracts"
+purpose: "Warn block authors and hosts about the two boundary data-hygiene rules that prevent empty-src and duplicate-key console errors"
+lastReviewed: "2026-09-27"
+type: standards
+tags: [blocks, contracts, data-boundary, images, react-keys]
+---
+
+# Block data contracts
+
+Blocks receive data via props and render it blindly. Two recurring defects at
+the data boundary — `src=""` and duplicate React keys — are both caused by the
+**host/boundary** emitting invalid values, not by the block. This document
+states the two hygiene rules every boundary (mapper/transform/store spec) must
+follow, and the defensive pattern every block should apply as a second layer.
+
+## Rule 1: Optional fields are never `""` — use `undefined` or a fallback
+
+A field that "may be absent" is a field that is **optional**. Serializing it as
+an empty string is a lie: it looks like data but renders as a broken element
+(`<img src="">` → browser warning, broken layout).
+
+- **Genuinely optional fields** → emit `undefined`. React omits the attribute
+  entirely, so `<img src={undefined}>` never warns.
+- **Fields whose contract requires a string** (e.g. `image: z.string()`) →
+  emit a non-empty **fallback**, never `""`. An `undefined` here would fail Zod
+  validation at the renderer boundary.
+- **Never** reach for `?? ''` in a mapper, transform, or store spec.
+
+Reference pattern — category images in electrostore
+(`projects/electrostore/lib/electrostore/category-mappers.ts`):
+
+```ts
+export const CATEGORY_IMAGE_FALLBACK = 'data:image/svg+xml;utf8,...'
+// image: category.image ?? category.metadata?.image ?? CATEGORY_IMAGE_FALLBACK
+```
+
+The same pattern ships in the blocks library as
+`PRODUCT_IMAGE_FALLBACK` (SVG data-URI) exported from
+`@thorprovider/blocks/contracts`. Hosts may override with a store-specific
+fallback; blocks render it as the last-resort value.
+
+## Rule 2: React keys are unique by contract, not by convention
+
+Never use a data field (href, id, image URL) as a React key unless uniqueness
+is **guaranteed by contract**. Placeholder or repeated hrefs (e.g. two utility
+links pointing at the same route) silently produce duplicate keys.
+
+- **Dedupe at the boundary** when concatenating data from multiple sources
+  (categories + utility links + account link).
+- **Blocks** that receive arrays use composite stable keys
+  (`key={`${item.id}:${item.label}`}`) so a duplicate id from any host cannot
+  collide.
+- Duplicate `href` values in navigation are often a sign of placeholder data —
+  fix the data, don't just silence the warning.
+
+## Second layer: blocks render defensively
+
+Even with correct boundaries, blocks should render
+`src={value || undefined}` for every image prop. This is a cheap invariant
+that makes the whole catalog immune to one misbehaving host.
+
+## Review checklist (boundary code)
+
+- [ ] No `?? ''` or `|| ''` on visual fields (image, avatar, icon) in mappers/transforms.
+- [ ] Required `z.string()` fields always receive a non-empty fallback.
+- [ ] Optional fields emit `undefined`, never `""`.
+- [ ] Arrays passed as React children have unique keys guaranteed by contract or deduped at the boundary.
+- [ ] Concatenated arrays (categories + links) are deduped before render.
+- [ ] Every `<img>`/`<AvatarImage>` in the block uses `src={expr || undefined}`.

package/docs/standards/theming.md

@@ -0,0 +1,85 @@
+---
+title: "Theme token contract"
+purpose: "Define the theme tokens library blocks may reference and the rules that keep block styling theme-agnostic and AA-conformant"
+lastReviewed: "2026-09-28"
+type: standards
+tags: [blocks, theming, tokens, contrast, a11y]
+---
+
+# Theme token contract
+
+`@thorprovider/blocks` ships **zero CSS**. Block styling resolves against the
+consumer's own theme tokens at build time (Tailwind `@source` points at the
+library source). This document is the contract between the library and every
+theme that renders it: the tokens blocks may reference, the status rule, and
+the documented exceptions.
+
+## Contract tokens
+
+A conformant consumer theme defines **each** token below with its foreground
+pair, in every mode the theme declares (light and dark where dark mode
+exists). Foreground pairs SHALL meet WCAG AA contrast (≥ 4.5:1 normal text,
+≥ 3:1 UI components / large text).
+
+| Token | Foreground | Role |
+| --- | --- | --- |
+| `--background` | `--foreground` | Page surface / body text |
+| `--card` | `--card-foreground` | Card surface |
+| `--popover` | `--popover-foreground` | Popover / dialog surface |
+| `--primary` | `--primary-foreground` | Brand / main CTAs |
+| `--secondary` | `--secondary-foreground` | Secondary surfaces |
+| `--muted` | `--muted-foreground` | De-emphasized surfaces / hints |
+| `--accent` | `--accent-foreground` | Hover / selected surface (neutral) |
+| `--destructive` | `--destructive-foreground` | Errors, removals, danger |
+| `--success` | `--success-foreground` | Positive status (savings, in stock) |
+| `--warning` | `--warning-foreground` | Caution status (low stock, notices) |
+| `--border` | — | Hairlines, dividers |
+| `--input` | — | Input borders / fills |
+| `--ring` | — | Focus rings |
+
+`accent` is a **surface** token, not a brand token. Brand color belongs in
+`--primary`. `accent` SHALL be a neutral, AA-safe surface so hover/selected
+states across nav, links, and menus stay readable.
+
+## Rules
+
+### Rule 1: Blocks reference only contract tokens
+
+A block SHALL NOT hardcode raw Tailwind palette utilities (`bg-orange-500`,
+`text-green-600`, `fill-amber-500`, `bg-green-50`), arbitrary CSS values
+(`bg-[#0070ba]`), or app-only tokens (`bg-promo`). Every color class SHALL
+resolve against a contract token.
+
+### Rule 2: Status has one of two shapes
+
+- **Status chip / badge** → use a `Badge` variant (`secondary`, `outline`,
+  `destructive`) and let the label carry the meaning.
+- **Inline status text, icon, or dot** → use the semantic tokens
+  (`text-success`, `bg-success`, `text-warning`, `bg-warning`).
+
+Rating stars use `fill-foreground` / `fill-current` — rating color carries no
+status semantics.
+
+### Rule 3: Primitives use contract foreground pairs
+
+UI primitives (button, badge, ...) SHALL use `text-destructive-foreground`
+(never `text-white`) on destructive surfaces so the pair resolves against the
+consumer's tokens in light and dark mode.
+
+### Rule 4: Theming.md is the review-time gate
+
+Adding a color class not in this contract is a review-time violation. Theme
+authors verify pairs with `scripts/contrast-check.mjs` in the Thor Commerce
+repo, which asserts every pair in both themes meets AA.
+
+## Documented exceptions
+
+Two cases are legitimate and MUST NOT be converted to theme tokens:
+
+- **Brand colors supplied as data.** Payment-brand chips (e.g. PayPal blue),
+  product swatches, and category icon colors arrive as data props or app-local
+  tokens (`--nav`, `--stock`, `--urgent`, `--promo` in electrostore) and are
+  styled by the app, never referenced by library blocks.
+- **Overlays over imagery.** `bg-black/50 text-white`, `bg-white/90`,
+  photo-count pills, lightbox controls. Contrast is image-dependent and cannot
+  be guaranteed by theme tokens; these stay as raw overlay utilities.

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@thorprovider/blocks",
+  "version": "0.1.0",
+  "description": "Reusable, framework-agnostic React component blocks for Thor Commerce storefronts.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "development": "./dist/index.mjs",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "default": "./dist/index.mjs"
+    },
+    "./contracts": {
+      "types": "./dist/contracts.d.ts",
+      "development": "./dist/contracts.mjs",
+      "import": "./dist/contracts.mjs",
+      "require": "./dist/contracts.js",
+      "default": "./dist/contracts.mjs"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run --config vitest.config.ts",
+    "generate:agent-index": "node ../../scripts/generate-package-agents-index.cjs packages/blocks @thorprovider/blocks"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/thorprovider/thor-commerce",
+    "directory": "packages/blocks"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@base-ui/react": "^1.8.0",
+    "@thorprovider/types": "^5.7.7",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "cn": "^0.4.0",
+    "embla-carousel-react": "^8.6.0",
+    "input-otp": "^1.5.0",
+    "lucide-react": "^1.47.0",
+    "motion": "^13.4.3",
+    "radix-ui": "^1.6.7",
+    "tailwind-merge": "^3.3.1",
+    "vaul": "^1.1.2",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^3.2.4"
+  }
+}

package/src/blocks/application/app-shells/app-shell-1-sidebar.tsx

@@ -0,0 +1,198 @@
+'use client'
+
+import {
+  BarChart3,
+  ChevronsUpDown,
+  FolderKanban,
+  Home,
+  LayoutDashboard,
+  Package,
+  Settings,
+  ShoppingCart,
+  User,
+  Users,
+} from 'lucide-react'
+import type { ComponentType } from 'react'
+
+import { Avatar, AvatarFallback } from '../../../ui/avatar'
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuGroup,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuTrigger,
+} from '../../../ui/dropdown-menu'
+import { Input } from '../../../ui/input'
+import {
+  Sidebar,
+  SidebarContent,
+  SidebarFooter,
+  SidebarGroup,
+  SidebarGroupContent,
+  SidebarGroupLabel,
+  SidebarHeader,
+  SidebarMenu,
+  SidebarMenuButton,
+  SidebarMenuItem,
+  useSidebar,
+} from '../../../ui/sidebar'
+
+export type AppShell1NavIcon =
+  | 'layout-dashboard'
+  | 'package'
+  | 'user'
+  | 'settings'
+  | 'home'
+  | 'shopping-cart'
+  | 'bar-chart-3'
+  | 'users'
+  | 'folder-kanban'
+
+export interface AppShell1NavItem {
+  label: string
+  href: string
+  icon: AppShell1NavIcon
+  active?: boolean
+}
+
+export interface AppShell1User {
+  name: string
+  email: string
+  initials: string
+}
+
+const appShell1NavIcons: Record<AppShell1NavIcon, ComponentType> = {
+  'layout-dashboard': LayoutDashboard,
+  package: Package,
+  user: User,
+  settings: Settings,
+  home: Home,
+  'shopping-cart': ShoppingCart,
+  'bar-chart-3': BarChart3,
+  users: Users,
+  'folder-kanban': FolderKanban,
+}
+
+// SidebarInset must remain a direct sibling of Sidebar. The sidebar primitive persists open state in the `sidebar_state` cookie.
+function BrandMark() {
+  return (
+    <svg width="32" height="32" viewBox="0 0 32 32" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
+      <path
+        d="M26 24.75C26.4142 24.75 26.75 24.4142 26.75 24C26.75 23.5858 26.4142 23.25 26 23.25V24.75ZM26 23.25H11V24.75H26V23.25ZM8.75 21V15H7.25V21H8.75ZM11 23.25C9.75736 23.25 8.75 22.2426 8.75 21H7.25C7.25 23.0711 8.92893 24.75 11 24.75V23.25Z"
+        fill="currentColor"
+      />
+      <path
+        d="M1.5 3.25C1.08579 3.25 0.75 3.58579 0.75 4C0.75 4.41421 1.08579 4.75 1.5 4.75V3.25ZM1.5 4.75H6V3.25H1.5V4.75ZM7.25 6V21H8.75V6H7.25ZM6 4.75C6.69036 4.75 7.25 5.30964 7.25 6H8.75C8.75 4.48122 7.51878 3.25 6 3.25V4.75Z"
+        fill="currentColor"
+      />
+      <path
+        d="M22 21.75C22.4142 21.75 22.75 21.4142 22.75 21C22.75 20.5858 22.4142 20.25 22 20.25V21.75ZM22 20.25H11V21.75H22V20.25ZM8.75 18V12H7.25V18H8.75ZM11 20.25C9.75736 20.25 8.75 19.2426 8.75 18H7.25C7.25 20.0711 8.92893 21.75 11 21.75V20.25Z"
+        fill="currentColor"
+      />
+      <path
+        d="M27.2057 19.754C27.0654 20.1438 26.6357 20.346 26.246 20.2057C25.8562 20.0654 25.654 19.6357 25.7943 19.246L27.2057 19.754ZM30.0361 9.67744L29.3305 9.4234L29.3305 9.4234L30.0361 9.67744ZM25.7943 19.246L29.3305 9.4234L30.7418 9.93148L27.2057 19.754L25.7943 19.246ZM28.1543 7.75L8 7.75V6.25L28.1543 6.25V7.75ZM29.3305 9.4234C29.6237 8.60882 29.0201 7.75 28.1543 7.75V6.25C30.059 6.25 31.3869 8.13941 30.7418 9.93148L29.3305 9.4234Z"
+        fill="currentColor"
+      />
+      <path
+        d="M13.5 21.75C13.0858 21.75 12.75 21.4142 12.75 21C12.75 20.5858 13.0858 20.25 13.5 20.25V21.75ZM26.7111 19.009L27.4174 19.2613L27.4174 19.2613L26.7111 19.009ZM13.5 20.25H23.8858V21.75H13.5V20.25ZM26.0048 18.7568L27.7937 13.7477L29.2063 14.2523L27.4174 19.2613L26.0048 18.7568ZM23.8858 20.25C24.8367 20.25 25.6849 19.6522 26.0048 18.7568L27.4174 19.2613C26.8843 20.7537 25.4706 21.75 23.8858 21.75V20.25Z"
+        fill="currentColor"
+      />
+      <path d="M21.1694 10.5806L14.5651 17.1849" stroke="currentColor" />
+      <path d="M22.1694 14.5806L18.5632 18.1868" stroke="currentColor" />
+      <circle cx="13.1" cy="26.1" r="1.7" stroke="currentColor" />
+      <circle cx="22.1" cy="26.1" r="1.7" stroke="currentColor" />
+    </svg>
+  )
+}
+
+export interface AppShell1SidebarProps {
+  brandName?: string
+  navGroupLabel?: string
+  navItems?: AppShell1NavItem[]
+  user?: AppShell1User
+}
+
+export function AppShell1Sidebar({
+  brandName,
+  navGroupLabel = 'Workspace',
+  navItems = [],
+  user,
+}: AppShell1SidebarProps) {
+  const { setOpenMobile } = useSidebar()
+
+  return (
+    <Sidebar>
+      <SidebarHeader>
+        <a
+          href="#resumen"
+          className="flex min-h-11 items-center gap-2 rounded-lg px-2 font-semibold"
+          onClick={() => setOpenMobile(false)}
+        >
+          <BrandMark />
+          {brandName}
+        </a>
+      </SidebarHeader>
+      <SidebarContent>
+        <SidebarGroup>
+          <SidebarGroupLabel>{navGroupLabel}</SidebarGroupLabel>
+          <SidebarGroupContent>
+            <nav aria-label={navGroupLabel}>
+              <SidebarMenu>
+                {navItems.map(item => {
+                  const Icon = appShell1NavIcons[item.icon]
+                  return (
+                    <SidebarMenuItem key={item.label}>
+                      <SidebarMenuButton isActive={item.active} asChild>
+                        <a
+                          href={item.href}
+                          aria-current={item.active ? 'page' : undefined}
+                          aria-label={item.label}
+                          onClick={() => setOpenMobile(false)}
+                        >
+                          <Icon />
+                          <span>{item.label}</span>
+                        </a>
+                      </SidebarMenuButton>
+                    </SidebarMenuItem>
+                  )
+                })}
+              </SidebarMenu>
+            </nav>
+          </SidebarGroupContent>
+        </SidebarGroup>
+        <div className="px-2 md:hidden">
+          <Input aria-label="Buscar en el espacio de trabajo" placeholder="Buscar…" />
+        </div>
+      </SidebarContent>
+      {user ? (
+        <SidebarFooter>
+          <SidebarMenu>
+            <SidebarMenuItem>
+              <DropdownMenu>
+                <DropdownMenuTrigger asChild>
+                  <SidebarMenuButton className="min-h-11">
+                    <Avatar className="size-7">
+                      <AvatarFallback>{user.initials}</AvatarFallback>
+                    </Avatar>
+                    <span className="truncate">{user.name}</span>
+                    <ChevronsUpDown className="ml-auto" />
+                  </SidebarMenuButton>
+                </DropdownMenuTrigger>
+                <DropdownMenuContent side="top">
+                  <DropdownMenuGroup>
+                    <DropdownMenuLabel>{user.email}</DropdownMenuLabel>
+                    <DropdownMenuItem>Configuración de la cuenta</DropdownMenuItem>
+                    <DropdownMenuItem>Cerrar sesión</DropdownMenuItem>
+                  </DropdownMenuGroup>
+                </DropdownMenuContent>
+              </DropdownMenu>
+            </SidebarMenuItem>
+          </SidebarMenu>
+        </SidebarFooter>
+      ) : null}
+    </Sidebar>
+  )
+}
+
+export default AppShell1Sidebar

package/src/blocks/application/app-shells/app-shell-1.tsx

@@ -0,0 +1,196 @@
+'use client'
+
+import { Bell, Plus, Search } from 'lucide-react'
+import type { ReactNode } from 'react'
+
+import type { CTA } from '../../../lib/types'
+import {
+  Breadcrumb,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbList,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+} from '../../../ui/breadcrumb'
+import { Button } from '../../../ui/button'
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '../../../ui/card'
+import { Input } from '../../../ui/input'
+import { Separator } from '../../../ui/separator'
+import { SidebarInset, SidebarProvider, SidebarTrigger } from '../../../ui/sidebar'
+import AppShell1Sidebar from './app-shell-1-sidebar'
+import type { AppShell1NavItem, AppShell1User } from './app-shell-1-sidebar'
+
+export interface AppShell1BreadcrumbItem {
+  label: string
+  href?: string
+}
+
+export interface AppShell1Stat {
+  label: string
+  value: string
+}
+
+export interface AppShell1Props {
+  brandName?: string
+  navGroupLabel?: string
+  navItems?: AppShell1NavItem[]
+  user?: AppShell1User
+  breadcrumb?: AppShell1BreadcrumbItem[]
+  pageTitle?: string
+  pageDescription?: string
+  action?: CTA
+  stats?: AppShell1Stat[]
+  children?: ReactNode
+  className?: string
+}
+
+function AppHeader({ breadcrumb }: { breadcrumb?: AppShell1BreadcrumbItem[] }) {
+  return (
+    <header className="flex h-14 shrink-0 items-center gap-3 border-b px-4 sm:px-6">
+      <SidebarTrigger aria-label="Toggle navigation" className="min-h-11 min-w-11" />
+      <Separator orientation="vertical" className="data-vertical:h-5 data-vertical:self-center" />
+      {breadcrumb && breadcrumb.length > 0 ? (
+        <Breadcrumb>
+          <BreadcrumbList>
+            {breadcrumb.map((item, index) => {
+              const isLast = index === breadcrumb.length - 1
+              return (
+                <div key={item.label} className="contents">
+                  <BreadcrumbItem className={isLast ? undefined : 'hidden sm:flex'}>
+                    {isLast ? (
+                      <BreadcrumbPage>{item.label}</BreadcrumbPage>
+                    ) : item.href ? (
+                      <BreadcrumbLink href={item.href}>{item.label}</BreadcrumbLink>
+                    ) : (
+                      <span>{item.label}</span>
+                    )}
+                  </BreadcrumbItem>
+                  {!isLast ? (
+                    <BreadcrumbSeparator className="hidden sm:flex" />
+                  ) : null}
+                </div>
+              )
+            })}
+          </BreadcrumbList>
+        </Breadcrumb>
+      ) : null}
+      <div className="ml-auto hidden w-56 md:block">
+        <div className="relative">
+          <Search className="pointer-events-none absolute left-2.5 top-1/2 size-4 -translate-y-1/2 text-muted-foreground" />
+          <Input
+            aria-label="Buscar en el espacio de trabajo"
+            placeholder="Buscar…"
+            className="h-9 pl-9"
+          />
+        </div>
+      </div>
+      <Button variant="ghost" size="icon" aria-label="Notifications, 3 unread">
+        <Bell />
+        <span className="sr-only">3 unread</span>
+      </Button>
+    </header>
+  )
+}
+
+function AppContent({
+  pageTitle,
+  pageDescription,
+  action,
+  stats,
+  children,
+}: {
+  pageTitle?: string
+  pageDescription?: string
+  action?: CTA
+  stats?: AppShell1Stat[]
+  children?: ReactNode
+}) {
+  return (
+    <main className="flex flex-1 flex-col gap-6 p-4 sm:p-6">
+      {pageTitle || pageDescription || action ? (
+        <div className="flex items-center justify-between gap-4">
+          <div>
+            {pageTitle ? (
+              <h1 className="text-2xl font-semibold tracking-tight">{pageTitle}</h1>
+            ) : null}
+            {pageDescription ? (
+              <p className="text-sm text-muted-foreground">{pageDescription}</p>
+            ) : null}
+          </div>
+          {action ? (
+            <Button asChild>
+              <a href={action.href}>
+                <Plus data-icon="inline-start" />
+                {action.label}
+              </a>
+            </Button>
+          ) : null}
+        </div>
+      ) : null}
+      {stats && stats.length > 0 ? (
+        <div className="grid gap-6 sm:grid-cols-2 lg:grid-cols-3">
+          {stats.map(stat => (
+            <Card key={stat.label}>
+              <CardHeader>
+                <CardDescription>{stat.label}</CardDescription>
+                <CardTitle className="text-3xl">{stat.value}</CardTitle>
+              </CardHeader>
+            </Card>
+          ))}
+        </div>
+      ) : null}
+      <Card className="min-h-72">
+        <CardHeader>
+          <CardTitle>Project activity</CardTitle>
+          <CardDescription>Your product content goes inside this shell.</CardDescription>
+        </CardHeader>
+        <CardContent className="flex flex-1">
+          {children ?? (
+            <div className="flex flex-1 items-center justify-center rounded-lg border border-dashed text-sm text-muted-foreground">
+              <Search className="mr-2 size-4" />
+              Replace with your screen
+            </div>
+          )}
+        </CardContent>
+      </Card>
+    </main>
+  )
+}
+
+export function AppShell1({
+  brandName,
+  navGroupLabel,
+  navItems,
+  user,
+  breadcrumb,
+  pageTitle,
+  pageDescription,
+  action,
+  stats,
+  children,
+  className,
+}: AppShell1Props) {
+  return (
+    <SidebarProvider className={className}>
+      <AppShell1Sidebar
+        brandName={brandName}
+        navGroupLabel={navGroupLabel}
+        navItems={navItems}
+        user={user}
+      />
+      <SidebarInset>
+        <AppHeader breadcrumb={breadcrumb} />
+        <AppContent
+          pageTitle={pageTitle}
+          pageDescription={pageDescription}
+          action={action}
+          stats={stats}
+        >
+          {children}
+        </AppContent>
+      </SidebarInset>
+    </SidebarProvider>
+  )
+}
+
+export default AppShell1