@thorprovider/blocks 2.0.0 → 3.0.0

package/dist/ui/toggle.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/ui/toggle.tsx"],"sourcesContent":["\"use client\"\n\nimport * as React from \"react\"\nimport { cva, type VariantProps } from \"class-variance-authority\"\nimport { cn } from \"cn\"\nimport { Toggle as TogglePrimitive } from \"radix-ui\"\n\nconst toggleVariants = cva(\n  \"inline-flex items-center justify-center gap-2 rounded-md text-sm font-medium whitespace-nowrap transition-[color,box-shadow] outline-none hover:bg-muted hover:text-muted-foreground focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 data-[state=on]:bg-accent data-[state=on]:text-accent-foreground dark:aria-invalid:ring-destructive/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4\",\n  {\n    variants: {\n      variant: {\n        default: \"bg-transparent\",\n        outline:\n          \"border border-input bg-transparent shadow-xs hover:bg-accent hover:text-accent-foreground\",\n      },\n      size: {\n        default: \"h-9 min-w-9 px-2\",\n        sm: \"h-8 min-w-8 px-1.5\",\n        lg: \"h-10 min-w-10 px-2.5\",\n      },\n    },\n    defaultVariants: {\n      variant: \"default\",\n      size: \"default\",\n    },\n  }\n)\n\nfunction Toggle({\n  className,\n  variant,\n  size,\n  ...props\n}: React.ComponentProps<typeof TogglePrimitive.Root> &\n  VariantProps<typeof toggleVariants>) {\n  return (\n    <TogglePrimitive.Root\n      data-slot=\"toggle\"\n      className={cn(toggleVariants({ variant, size, className }))}\n      {...props}\n    />\n  )\n}\n\nexport { Toggle, toggleVariants }\n"],"mappings":";AAqCI;AAlCJ,SAAS,WAA8B;AACvC,SAAS,UAAU;AACnB,SAAS,UAAU,uBAAuB;AAE1C,MAAM,iBAAiB;AAAA,EACrB;AAAA,EACA;AAAA,IACE,UAAU;AAAA,MACR,SAAS;AAAA,QACP,SAAS;AAAA,QACT,SACE;AAAA,MACJ;AAAA,MACA,MAAM;AAAA,QACJ,SAAS;AAAA,QACT,IAAI;AAAA,QACJ,IAAI;AAAA,MACN;AAAA,IACF;AAAA,IACA,iBAAiB;AAAA,MACf,SAAS;AAAA,MACT,MAAM;AAAA,IACR;AAAA,EACF;AACF;AAEA,SAAS,OAAO;AAAA,EACd;AAAA,EACA;AAAA,EACA;AAAA,EACA,GAAG;AACL,GACuC;AACrC,SACE;AAAA,IAAC,gBAAgB;AAAA,IAAhB;AAAA,MACC,aAAU;AAAA,MACV,WAAW,GAAG,eAAe,EAAE,SAAS,MAAM,UAAU,CAAC,CAAC;AAAA,MACzD,GAAG;AAAA;AAAA,EACN;AAEJ;","names":[]}

package/dist/ui/tooltip.d.ts

@@ -0,0 +1,8 @@
+import * as React from "react";
+import { Tooltip as TooltipPrimitive } from "radix-ui";
+declare function TooltipProvider({ delayDuration, ...props }: React.ComponentProps<typeof TooltipPrimitive.Provider>): React.JSX.Element;
+declare function Tooltip({ ...props }: React.ComponentProps<typeof TooltipPrimitive.Root>): React.JSX.Element;
+declare function TooltipTrigger({ ...props }: React.ComponentProps<typeof TooltipPrimitive.Trigger>): React.JSX.Element;
+declare function TooltipContent({ className, sideOffset, children, ...props }: React.ComponentProps<typeof TooltipPrimitive.Content>): React.JSX.Element;
+export { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider };
+//# sourceMappingURL=tooltip.d.ts.map

package/dist/ui/tooltip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tooltip.d.ts","sourceRoot":"","sources":["../../src/ui/tooltip.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAE9B,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,UAAU,CAAA;AAEtD,iBAAS,eAAe,CAAC,EACvB,aAAiB,EACjB,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,gBAAgB,CAAC,QAAQ,CAAC,qBAQxD;AAED,iBAAS,OAAO,CAAC,EACf,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,gBAAgB,CAAC,IAAI,CAAC,qBAEpD;AAED,iBAAS,cAAc,CAAC,EACtB,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,gBAAgB,CAAC,OAAO,CAAC,qBAEvD;AAED,iBAAS,cAAc,CAAC,EACtB,SAAS,EACT,UAAc,EACd,QAAQ,EACR,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,gBAAgB,CAAC,OAAO,CAAC,qBAiBvD;AAED,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,eAAe,EAAE,CAAA"}

package/dist/ui/tooltip.js

@@ -0,0 +1,84 @@
+"use strict";
+"use client";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var tooltip_exports = {};
+__export(tooltip_exports, {
+  Tooltip: () => Tooltip,
+  TooltipContent: () => TooltipContent,
+  TooltipProvider: () => TooltipProvider,
+  TooltipTrigger: () => TooltipTrigger
+});
+module.exports = __toCommonJS(tooltip_exports);
+var import_jsx_runtime = require("react/jsx-runtime");
+var import_cn = require("cn");
+var import_radix_ui = require("radix-ui");
+function TooltipProvider({
+  delayDuration = 0,
+  ...props
+}) {
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+    import_radix_ui.Tooltip.Provider,
+    {
+      "data-slot": "tooltip-provider",
+      delayDuration,
+      ...props
+    }
+  );
+}
+function Tooltip({
+  ...props
+}) {
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_radix_ui.Tooltip.Root, { "data-slot": "tooltip", ...props });
+}
+function TooltipTrigger({
+  ...props
+}) {
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_radix_ui.Tooltip.Trigger, { "data-slot": "tooltip-trigger", ...props });
+}
+function TooltipContent({
+  className,
+  sideOffset = 0,
+  children,
+  ...props
+}) {
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_radix_ui.Tooltip.Portal, { children: /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
+    import_radix_ui.Tooltip.Content,
+    {
+      "data-slot": "tooltip-content",
+      sideOffset,
+      className: (0, import_cn.cn)(
+        "z-50 w-fit origin-(--radix-tooltip-content-transform-origin) animate-in rounded-md bg-foreground px-3 py-1.5 text-xs text-balance text-background fade-in-0 zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95",
+        className
+      ),
+      ...props,
+      children: [
+        children,
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_radix_ui.Tooltip.Arrow, { className: "z-50 size-2.5 translate-y-[calc(-50%_-_2px)] rotate-45 rounded-[2px] bg-foreground fill-foreground" })
+      ]
+    }
+  ) });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger
+});
+//# sourceMappingURL=tooltip.js.map

package/dist/ui/tooltip.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/ui/tooltip.tsx"],"sourcesContent":["\"use client\"\n\nimport * as React from \"react\"\nimport { cn } from \"cn\"\nimport { Tooltip as TooltipPrimitive } from \"radix-ui\"\n\nfunction TooltipProvider({\n  delayDuration = 0,\n  ...props\n}: React.ComponentProps<typeof TooltipPrimitive.Provider>) {\n  return (\n    <TooltipPrimitive.Provider\n      data-slot=\"tooltip-provider\"\n      delayDuration={delayDuration}\n      {...props}\n    />\n  )\n}\n\nfunction Tooltip({\n  ...props\n}: React.ComponentProps<typeof TooltipPrimitive.Root>) {\n  return <TooltipPrimitive.Root data-slot=\"tooltip\" {...props} />\n}\n\nfunction TooltipTrigger({\n  ...props\n}: React.ComponentProps<typeof TooltipPrimitive.Trigger>) {\n  return <TooltipPrimitive.Trigger data-slot=\"tooltip-trigger\" {...props} />\n}\n\nfunction TooltipContent({\n  className,\n  sideOffset = 0,\n  children,\n  ...props\n}: React.ComponentProps<typeof TooltipPrimitive.Content>) {\n  return (\n    <TooltipPrimitive.Portal>\n      <TooltipPrimitive.Content\n        data-slot=\"tooltip-content\"\n        sideOffset={sideOffset}\n        className={cn(\n          \"z-50 w-fit origin-(--radix-tooltip-content-transform-origin) animate-in rounded-md bg-foreground px-3 py-1.5 text-xs text-balance text-background fade-in-0 zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95\",\n          className\n        )}\n        {...props}\n      >\n        {children}\n        <TooltipPrimitive.Arrow className=\"z-50 size-2.5 translate-y-[calc(-50%_-_2px)] rotate-45 rounded-[2px] bg-foreground fill-foreground\" />\n      </TooltipPrimitive.Content>\n    </TooltipPrimitive.Portal>\n  )\n}\n\nexport { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider }\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAWI;AARJ,gBAAmB;AACnB,sBAA4C;AAE5C,SAAS,gBAAgB;AAAA,EACvB,gBAAgB;AAAA,EAChB,GAAG;AACL,GAA2D;AACzD,SACE;AAAA,IAAC,gBAAAA,QAAiB;AAAA,IAAjB;AAAA,MACC,aAAU;AAAA,MACV;AAAA,MACC,GAAG;AAAA;AAAA,EACN;AAEJ;AAEA,SAAS,QAAQ;AAAA,EACf,GAAG;AACL,GAAuD;AACrD,SAAO,4CAAC,gBAAAA,QAAiB,MAAjB,EAAsB,aAAU,WAAW,GAAG,OAAO;AAC/D;AAEA,SAAS,eAAe;AAAA,EACtB,GAAG;AACL,GAA0D;AACxD,SAAO,4CAAC,gBAAAA,QAAiB,SAAjB,EAAyB,aAAU,mBAAmB,GAAG,OAAO;AAC1E;AAEA,SAAS,eAAe;AAAA,EACtB;AAAA,EACA,aAAa;AAAA,EACb;AAAA,EACA,GAAG;AACL,GAA0D;AACxD,SACE,4CAAC,gBAAAA,QAAiB,QAAjB,EACC;AAAA,IAAC,gBAAAA,QAAiB;AAAA,IAAjB;AAAA,MACC,aAAU;AAAA,MACV;AAAA,MACA,eAAW;AAAA,QACT;AAAA,QACA;AAAA,MACF;AAAA,MACC,GAAG;AAAA,MAEH;AAAA;AAAA,QACD,4CAAC,gBAAAA,QAAiB,OAAjB,EAAuB,WAAU,sGAAqG;AAAA;AAAA;AAAA,EACzI,GACF;AAEJ;","names":["TooltipPrimitive"]}

package/dist/ui/tooltip.mjs

@@ -0,0 +1,57 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { cn } from "cn";
+import { Tooltip as TooltipPrimitive } from "radix-ui";
+function TooltipProvider({
+  delayDuration = 0,
+  ...props
+}) {
+  return /* @__PURE__ */ jsx(
+    TooltipPrimitive.Provider,
+    {
+      "data-slot": "tooltip-provider",
+      delayDuration,
+      ...props
+    }
+  );
+}
+function Tooltip({
+  ...props
+}) {
+  return /* @__PURE__ */ jsx(TooltipPrimitive.Root, { "data-slot": "tooltip", ...props });
+}
+function TooltipTrigger({
+  ...props
+}) {
+  return /* @__PURE__ */ jsx(TooltipPrimitive.Trigger, { "data-slot": "tooltip-trigger", ...props });
+}
+function TooltipContent({
+  className,
+  sideOffset = 0,
+  children,
+  ...props
+}) {
+  return /* @__PURE__ */ jsx(TooltipPrimitive.Portal, { children: /* @__PURE__ */ jsxs(
+    TooltipPrimitive.Content,
+    {
+      "data-slot": "tooltip-content",
+      sideOffset,
+      className: cn(
+        "z-50 w-fit origin-(--radix-tooltip-content-transform-origin) animate-in rounded-md bg-foreground px-3 py-1.5 text-xs text-balance text-background fade-in-0 zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95",
+        className
+      ),
+      ...props,
+      children: [
+        children,
+        /* @__PURE__ */ jsx(TooltipPrimitive.Arrow, { className: "z-50 size-2.5 translate-y-[calc(-50%_-_2px)] rotate-45 rounded-[2px] bg-foreground fill-foreground" })
+      ]
+    }
+  ) });
+}
+export {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger
+};
+//# sourceMappingURL=tooltip.mjs.map

package/dist/ui/tooltip.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/ui/tooltip.tsx"],"sourcesContent":["\"use client\"\n\nimport * as React from \"react\"\nimport { cn } from \"cn\"\nimport { Tooltip as TooltipPrimitive } from \"radix-ui\"\n\nfunction TooltipProvider({\n  delayDuration = 0,\n  ...props\n}: React.ComponentProps<typeof TooltipPrimitive.Provider>) {\n  return (\n    <TooltipPrimitive.Provider\n      data-slot=\"tooltip-provider\"\n      delayDuration={delayDuration}\n      {...props}\n    />\n  )\n}\n\nfunction Tooltip({\n  ...props\n}: React.ComponentProps<typeof TooltipPrimitive.Root>) {\n  return <TooltipPrimitive.Root data-slot=\"tooltip\" {...props} />\n}\n\nfunction TooltipTrigger({\n  ...props\n}: React.ComponentProps<typeof TooltipPrimitive.Trigger>) {\n  return <TooltipPrimitive.Trigger data-slot=\"tooltip-trigger\" {...props} />\n}\n\nfunction TooltipContent({\n  className,\n  sideOffset = 0,\n  children,\n  ...props\n}: React.ComponentProps<typeof TooltipPrimitive.Content>) {\n  return (\n    <TooltipPrimitive.Portal>\n      <TooltipPrimitive.Content\n        data-slot=\"tooltip-content\"\n        sideOffset={sideOffset}\n        className={cn(\n          \"z-50 w-fit origin-(--radix-tooltip-content-transform-origin) animate-in rounded-md bg-foreground px-3 py-1.5 text-xs text-balance text-background fade-in-0 zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95\",\n          className\n        )}\n        {...props}\n      >\n        {children}\n        <TooltipPrimitive.Arrow className=\"z-50 size-2.5 translate-y-[calc(-50%_-_2px)] rotate-45 rounded-[2px] bg-foreground fill-foreground\" />\n      </TooltipPrimitive.Content>\n    </TooltipPrimitive.Portal>\n  )\n}\n\nexport { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider }\n"],"mappings":";AAWI,cA4BE,YA5BF;AARJ,SAAS,UAAU;AACnB,SAAS,WAAW,wBAAwB;AAE5C,SAAS,gBAAgB;AAAA,EACvB,gBAAgB;AAAA,EAChB,GAAG;AACL,GAA2D;AACzD,SACE;AAAA,IAAC,iBAAiB;AAAA,IAAjB;AAAA,MACC,aAAU;AAAA,MACV;AAAA,MACC,GAAG;AAAA;AAAA,EACN;AAEJ;AAEA,SAAS,QAAQ;AAAA,EACf,GAAG;AACL,GAAuD;AACrD,SAAO,oBAAC,iBAAiB,MAAjB,EAAsB,aAAU,WAAW,GAAG,OAAO;AAC/D;AAEA,SAAS,eAAe;AAAA,EACtB,GAAG;AACL,GAA0D;AACxD,SAAO,oBAAC,iBAAiB,SAAjB,EAAyB,aAAU,mBAAmB,GAAG,OAAO;AAC1E;AAEA,SAAS,eAAe;AAAA,EACtB;AAAA,EACA,aAAa;AAAA,EACb;AAAA,EACA,GAAG;AACL,GAA0D;AACxD,SACE,oBAAC,iBAAiB,QAAjB,EACC;AAAA,IAAC,iBAAiB;AAAA,IAAjB;AAAA,MACC,aAAU;AAAA,MACV;AAAA,MACA,WAAW;AAAA,QACT;AAAA,QACA;AAAA,MACF;AAAA,MACC,GAAG;AAAA,MAEH;AAAA;AAAA,QACD,oBAAC,iBAAiB,OAAjB,EAAuB,WAAU,sGAAqG;AAAA;AAAA;AAAA,EACzI,GACF;AAEJ;","names":[]}

package/package.json

@@ -1,9 +1,14 @@
 {
   "name": "@thorprovider/blocks",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "Reusable, framework-agnostic React component blocks for Thor Commerce storefronts.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "styles.css",
+    "README.md"
+  ],
   "sideEffects": [
     "**/*.css",
     "./styles.css"
@@ -34,9 +39,11 @@
   },
   "scripts": {
     "build": "tsup && tsc -p tsconfig.build.json && node scripts/fix-esm-extensions.mjs",
+    "prepack": "yarn build",
     "dev": "tsup --watch",
     "type-check": "tsc --noEmit",
     "test": "vitest run --config vitest.config.ts",
+    "pretest": "yarn build",
     "generate:agent-index": "node ../../scripts/generate-package-agents-index.cjs packages/blocks @thorprovider/blocks"
   },
   "peerDependencies": {

package/AGENTS.md

@@ -1 +0,0 @@
-<!-- BLOCKS-AGENTS-MD-START -->[@thorprovider/blocks Docs]|root: ./blocks|Electrostore MVP: see director roadmap.|To regenerate: yarn workspace @thorprovider/blocks generate:agent-index|.:{README.md}|docs/standards:{data-contracts.md,theming.md}<!-- BLOCKS-AGENTS-MD-END -->

package/CHANGELOG.md

@@ -1,155 +0,0 @@
-# @thorprovider/blocks
-
-## 2.0.0
-
-### Major Changes
-
-- dc82f71: Consolidate the category filter family into one canonical `CategoryListing` block.
-
-  - Adds `CategoryListing` (export + `CategoryListingProps` and the `CategoryListing*` option, facet, status, filter and active-filter types). It is the single controlled listing controller: products, pagination and the selected query are props; `on*Change` / `onClearFilters` / `onRepair` / `onRetry` report intent; the block never fetches, parses the URL, or keeps a private query.
-  - Two bounded presentations share one contract: `sidebar` (default; persistent desktop panel plus mobile sheet) and `toolbar` (sticky mobile toolbar, filter/sort drawers and chip rail). Presentation changes chrome only.
-  - Results render through the canonical `ProductCard` (`minimal`), so the listing owns no card markup. Facets are generic option-only groups supplied by the host; a group renders only from real metadata, a real `0` count is displayed, and an absent/invalid count is omitted. Price renders only from a real finite range, sort only from advertised options, and no result total is fabricated.
-  - `ProductCard` gains `hideAddToCart` for listing cells and renders `data-slot='product-image-placeholder'` instead of an image with an empty source.
-  - Runtime: `toFilterProduct` → `toListingProduct` (returns canonical `ProductPresentation` with `Money`), `CategoryFilterPresentation(Input)` → `CategoryListingPresentation(Input)`, `mapCatalogResultsToFilterProps` → `mapCatalogResultsToCategoryListing`, and `resolveFilterPresentationSupport` → `resolveCategoryListingSupport` plus a separate `resolveCategoryFacetSupport`. The old numbered presentation metadata is gone.
-
-  BREAKING: removes the `CategoryFilter1`, `CategoryFilter2` and `CategoryFilter4` exports, their types, and the `category-filter-4-*` helpers. Consumers must migrate to `CategoryListing`:
-
-  | Removed           | Migration                                                                                                                                                                                     |
-  | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-  | `CategoryFilter1` | `CategoryListing` with `presentation='sidebar'`; replace counted categories/price bands with real `categories` / `priceRange` metadata.                                                       |
-  | `CategoryFilter2` | `CategoryListing` with `presentation='sidebar'` (the default). Products become canonical `ProductPresentation` items with `Money` prices; `filterPrice` string prices are no longer accepted. |
-  | `CategoryFilter4` | `CategoryListing` with `presentation='toolbar'`; replace bike-specific facets/frame/model fields with generic `facets` groups and remove its private grid/state.                              |
-
-- 28a3bd7: Consolidate the numbered checkout-form family into one canonical page-level `Checkout` block.
-
-  - Adds `Checkout` (export plus `CheckoutProps`, `CheckoutValues`, `CheckoutPresentation`, `CheckoutStepId`, `CheckoutLabels`, `CheckoutValuesFieldErrors`, `CheckoutFieldDescriptions`, `CheckoutChangeHandler`, `CheckoutOrderSummary`, `CheckoutOrderLine`, `CheckoutTotals`, `CheckoutTotalsState`, `CheckoutCountryOption`, `CheckoutShippingOption`) with a required bounded `presentation` (`single-page` | `stepper`) and an orthogonal `showReviewStep` flow option. `single-page` is the former `CheckoutForm2` structure; `stepper` is the former `CheckoutForm1` wizard; `stepper` plus the review option is the former `CheckoutForm3`. Field values are controlled (`values` + `onChange`), the step index is ephemeral block state, and `validateStep(step: CheckoutStepId)` is injected — the block contains no validation logic.
-  - Totals are canonical `Money` only and render verbatim from the host; the legacy numeric `price`/`shipping`/`tax`/`discount`/`promoDiscount` fields and their fallback summation are removed. A missing or malformed required total renders as unavailable with recovery, never as zero.
-  - Removes raw card capture: `cardNumber`, `expiryDate`, `cvv`, `cardName`, the `collectCardFields` escape hatch, the CVV visibility toggle, and `card-formatting.ts`. Payment methods remain data (`PaymentMethod[]`); card collection belongs to the host payment-provider surface.
-  - Removes the numbered exports `CheckoutForm1`, `CheckoutForm2`, `CheckoutForm3` and their `CheckoutForm1*`, `CheckoutForm2*`, `CheckoutForm3*` types.
-
-  BREAKING: consumers importing a numbered checkout must migrate to `Checkout` with the `presentation` prop (and `showReviewStep` for the review flow). Values lose the card fields and `sameAsBilling`; totals must be supplied as backend `Money`; `validateStep` now receives a `CheckoutStepId` instead of a step number.
-
-- 06333a8: Consolidate the navigation family into two canonical components and retire the numbered navbars.
-
-  - `Navbar` is the canonical page-level header with bounded `bar`, `mega`, and `floating` presentations. Content is serializable (`links`, `items`, `featured`, `signIn`, `cta`, `logoText`, `logoHref`, `currentPath`); icons resolve through a host-bound `iconMap`; `floating` uses `sticky` so it reserves its own space.
-  - `StorefrontNavbar` is the canonical commerce shell (formerly `Navbar4`) and keeps its full storefront contract: utility strip, category navigation, optional search, account states, and the controlled cart sheet with canonical `Money`.
-  - Removed identifiers: `Navbar1`, `Navbar2`, `Navbar3`, `Navbar4`, `navbar4PropsSchema`, `Navbar4SpecProps`, `Navbar4LikeButton`, `Navbar4ProductGrid`, and the `navbar-4-*` helper modules (now `storefront-navbar-cart-sheet`, `storefront-navbar-account-menu`, `storefront-navbar-search-bar`, `storefront-navbar-mobile-nav`).
-  - The page-level header no longer owns cart state: `cartCount` and `onOpenCart` are gone. Use the commerce shell for the cart affordance.
-
-- 65fac4b: Remove the numbered compatibility adapters `Testimonial1`, `Testimonial2`, `LoginPage1`, `LoginPage2`, `FooterSection1`, `FooterSection3`, and `FooterSection4`, including their deep module paths and legacy prop types. Migrate testimonials to `TestimonialSection` with `carousel` or `bento`, login pages to `LoginPage` with `card` or `social`, and footers to `FooterSection` with `brand-columns`, `newsletter-grid`, or `contact`. Select native footer link behavior explicitly where browser navigation is intended.
-
-### Minor Changes
-
-- 5d32763: The auth blocks render into the host page instead of owning it.
-
-  `LoginPage` (both `card` and `social`), `SignUpPage1`, `ForgotPasswordPage1` and `Verify1` no longer paint a full-viewport surface. They drop the `min-h-dvh` canvas, the page landmark (the `social` presentation no longer renders a root `<main>`), the `bg-linear-to-br` backdrop with `isolate`/`overflow-hidden`, the vertical centring and the page-level padding. Each block now renders a neutral, content-sized root that keeps its width cap (`max-w-md` for login and recovery, `max-w-lg` for registration) and its card styling, including the shadow.
-
-  Why: a generated storefront mounts these blocks inside the default chrome (notice + banner + navbar + footer). A viewport-height canvas inside that chrome centres the form roughly 100 px low and, for the `social` presentation, emits a second `<main>` landmark inside the page's own `<main>`.
-
-  No prop, type or export changed, so existing call sites keep compiling. What changes is visual ownership: a host that relied on the block's canvas must now supply one (a route shell, a modal, a split screen, or a template the host owns), using the same theme tokens. `@thorprovider/storefront` does exactly that for the generated `account` view, which keeps the shopper-visible result unchanged.
-
-## 1.0.0
-
-### Major Changes
-
-- f011717: Consolidate the `home.benefits` feature family into one canonical `Feature` block.
-
-  - Adds `Feature` (export + `featurePropsSchema` / `FeatureProps` in the contracts surface) with a bounded `presentation` prop (`cards` | `split`, default `cards`). `cards` is the former header-badge card grid with per-item learn-more and an optional section CTA; `split` is the former split layout with the optional grayscale image column. `split` deliberately ignores `badge` and per-item learn-more; an absent or empty image `src` renders no image column (never a blank `src`).
-  - The storefront catalog declares the two presentations as the `home.benefits` variants with `legacyAliases` (`Feature1` → `cards`, `Feature2` → `split`), so existing manifests storing the numbered names keep regenerating to the same presentation; the benefits feature's `compact` / `detailed` configuration values are unchanged and map onto `cards` / `split`.
-
-  BREAKING: removes the `Feature1` and `Feature2` exports (components and their `Feature1Props`/`Feature1Item`/`Feature2Props`/`Feature2Item` types) that this canonical block supersedes. Consumers must migrate to `Feature` with the `presentation` prop.
-
-- f011717: Consolidate the product-card family into one canonical `ProductCard` block.
-
-  - Adds `ProductCard` (export + `productCardPropsSchema` / `ProductCardSpecProps` in the contracts surface) with a bounded `presentation` prop (`classic` | `minimal` | `rich`, default `classic`). `classic` is the former `ProductCard1` structure (badge, optional rating, compare-at, add-to-cart footer, reduced-motion-safe motion); `minimal` is the former `ProductCard2` lean look; `rich` is the former `ProductCard3` overlay actions (wishlist heart with host-owned controlled state or uncontrolled visual fallback, and view-similar rendered only when a handler is supplied). The comparison-table surface of the former `ProductCard5` is deliberately retired (a listing controller, not an item cell).
-  - Items are the canonical `ProductPresentation` contract only (identity, title, optional image with alt, canonical `Money` price, optional `compareAtPrice`/`rating`/`badge`). An unresolved price renders an unavailable state with add-to-cart disabled — never a zero. Ratings, badges and crossed-out prices render only from host-supplied data; the block invents no evidence. Prices render through the canonical `formatMoney` path (no hardcoded currency symbol) and all user-facing copy is overridable with the previous Spanish defaults.
-  - Removes the numbered exports `ProductCard1`, `ProductCard2`, `ProductCard3`, `ProductCard5`, their types `ProductCard1Product` / `ProductCard1Props`, the contracts surface `productCard1PropsSchema` / `ProductCard1SpecProps`, and the `product-card-3-reaction-toggle` / `product-card-5-reaction-toggle` / `product-card-5-checkbox-check` subcomponents.
-  - Migration: supply item data in the canonical presentation contract (canonical `Money` amounts as decimal major-unit strings plus `currencyCode`). The former numeric-price props (`price: number`, `originalPrice?: number`, mandatory demo merchandising fields) are not retained; map them to `Money` at your boundary. Consumer code importing a numbered card selects the equivalent bounded presentation (`1` → `classic`, `2` → `minimal`, `3` → `rich`); the former comparison table has no replacement in this block.
-
-- f011717: Consolidate the `home.categories` family into one canonical `ProductCategory` block.
-
-  - Adds `ProductCategory` (export + `productCategoryPropsSchema` / `ProductCategoryProps`) built on the canonical `CategoryCard` shape. It exposes a bounded `presentation` prop (`grid` | `icons` | `list`); optional per-category data (`icon` as a serializable key, `subcategories`, `featured`, `itemCount`) degrades gracefully when absent.
-  - Interaction is controlled: `onBrowse` / `onViewAll` / `onQueryChange` report from handlers with no private query state; a category count is omitted when absent or invalid and a real zero is preserved; a missing image renders a neutral placeholder, never `src=""`; no copy, currency, or demo metrics are hardcoded.
-
-  BREAKING: removes the `ProductCategory1`, `ProductCategory2`, `ProductCategory4`, and `ProductCategory5` exports (and the `product-categories/avatar-group` helper) that this canonical block supersedes. Consumers must migrate to `ProductCategory` with the `presentation` prop.
-
-- ece154d: Consolidate the `product.overview` family into one canonical `ProductOverview` block.
-
-  - Adds `ProductOverview` (export + `productOverviewPropsSchema` / `ProductOverviewProps`) built on the canonical `ProductDetailProduct` projection and canonical `Money`. It exposes a bounded `presentation` prop (`standard` | `gallery` | `rich`); `rich` accepts optional `specifications` / `features` / `reviews` props and degrades gracefully when they are absent.
-  - Selection and quantity are controlled; `onAddToCart` emits the explicitly selected backend variant id and quantity and never substitutes the first variant. Missing price renders as unavailable, never `$0`; currency is never hardcoded.
-
-  BREAKING: removes the `ProductOverview1`, `ProductOverview2`, and `ProductOverview5` exports (and the `product-overview-5-*` subcomponents) that this canonical block supersedes. Consumers must migrate to `ProductOverview` with the `presentation` prop.
-
-- b41cc50: Consolidate the numbered shopping-cart family into one canonical `ShoppingCart` block.
-
-  - Adds `ShoppingCart` (export + `shoppingCartPropsSchema` / `ShoppingCartSpecProps` in the contracts surface) with a bounded `presentation` prop (`compact` | `page`). `compact` is the former `ShoppingCart4` review card; `page` is the same contract with the page-level structure. The optional promo-entry affordance reports the entered code via `onApplyPromo(code)` and renders only authoritative promotion/discount data — it is hidden when the callback is absent, and the block never validates promotion codes itself. Host-supplied `recentlyViewed` suggestions replace the former `ShoppingCart2` recommendations, priced with canonical `Money`.
-  - Items are the canonical contract only: identity, title, quantity, optional image (omitted when absent, never `src=""`), and canonical `Money` amounts. Each line carries the backend-authoritative `lineTotal` (rendered verbatim; a malformed amount renders as unavailable — never a zero or free-shipping claim) and an optional `unitPrice` carried verbatim but never used for local arithmetic. `totals` come from the backend and are rendered verbatim; no local tax/shipping/threshold math, no fabricated merchandising, no hardcoded currency.
-  - Removes the numbered exports `ShoppingCart1`, `ShoppingCart2`, `ShoppingCart3`, `ShoppingCart4` (and their `ShoppingCart1CartItem`, `ShoppingCart2Props`/`ShoppingCart2Item`, `ShoppingCart3Props`/`ShoppingCart3CartItem`, `ShoppingCart4Props`/`ShoppingCart4Item` types), the contracts surface `shoppingCart4PropsSchema` / `ShoppingCart4SpecProps`, and the `shopping-cart-{1,2,3,4}-spinning-counter`, `shopping-cart-2-recommendations`, and `shopping-cart-2-item-row` subcomponents.
-
-  BREAKING: consumers importing a numbered cart must migrate to `ShoppingCart` with the `presentation` prop. The former numeric-price props (`price: number`, local `taxRate`/shipping-threshold arithmetic) are not retained; map item amounts to canonical `Money` (`{ amount, currencyCode }`) at your boundary and pass backend `totals` verbatim.
-
-- f011717: Consolidate the `home.hero` family into one canonical `StorefrontHero` block.
-
-  - Adds `StorefrontHero` (export + `storefrontHeroPropsSchema` / `StorefrontHeroProps` / `StorefrontHeroProduct` in the contracts surface) with a bounded `presentation` prop (`compact` | `showcase` | `editorial` | `promotional`) reusing the registry's archetype intent vocabulary. `compact` is the former `StorefrontHero1` text-forward hero with product grid and editorial image seam; `showcase` the former `StorefrontHero2` search + rotating product carousel (the search input renders only when `onSearch` is supplied); `editorial` the former `StorefrontHero5` department grid with optional featured deals and store locator; `promotional` the former `StorefrontHero6` deals bar + category grid.
-  - Truthful evidence only: ratings, review counts, category/department counts, deal descriptions, and countdowns render only from host-supplied data; discount treatments render only from a real `originalPrice > price` pair (`isOnSale` is dropped); `currency` (ISO 4217) formats all amounts via `Intl.NumberFormat` — no hardcoded `$`. Rotation respects reduced motion and is presentation-internal.
-  - The storefront catalog declares `StorefrontHero` as the single `home.hero` variant with `legacyAliases` (`StorefrontHero1`/`2`/`5`/`6` → the canonical), so existing manifests storing the numbered names keep regenerating to a working composition; `archetypes.json` intents map each intent to its matching presentation.
-
-  BREAKING: removes the `StorefrontHero1`, `StorefrontHero2`, `StorefrontHero5`, and `StorefrontHero6` exports (and the `StorefrontHero1Props` type) that this canonical block supersedes. The `FeaturedProduct` type is now exported from the canonical source and its evidence fields (`brand`, `colors`, `rating`, `reviewCount`, `originalPrice`) are optional. Consumers must migrate to `StorefrontHero` with the `presentation` prop.
-
-- dc2b11b: Split the category collection into an item cell and a listing.
-
-  - `CategoryCard` is the item cell: one `category` at a time, with the existing `grid`, `icons` and `list` presentations. It renders no section, heading, search, CTA or empty state.
-  - `CategoryGrid` is the listing: it owns the collection, `maxItems`, section copy, controlled search (list presentation), loading skeletons and the empty state, and renders `CategoryCard` for every item.
-  - BREAKING: `ProductCategory` (collection) is replaced by `CategoryGrid`; the single-item surface is `CategoryCard`. `ProductCategoryProps` is replaced by `CategoryGridProps` / `CategoryCardProps`.
-
-  Migration: replace `<ProductCategory categories={items} ... />` with `<CategoryGrid categories={items} ... />`. For a single category, render `<CategoryCard category={item} ... />`.
-
-- 3e43eb0: BREAKING: `ProductCard` is now an item cell and a new `ProductGrid` listing owns the collection.
-
-  - `ProductCard` (`packages/blocks/src/blocks/e-commerce/product-list/product-card.tsx`) now takes a single `item: ProductPresentation` (plus `presentation?` and `wishlisted?`) and renders exactly one cell — no section wrapper, no section heading, no grid, and no item cap. The `items`, `heading`, and `maxItems` props and the `wishlistedIds` collection prop are removed; `wishlisted` is now a single host-resolved boolean.
-  - The serializable contract `productCardPropsSchema` / `ProductCardSpecProps` changes accordingly (`{ item, presentation?, wishlisted? }`), still without callbacks or label strings.
-  - Adds `ProductGrid` (export + `productGridPropsSchema` / `ProductGridSpecProps`) as the canonical listing: it takes `items: ProductPresentation[]`, an optional `presentation`, `heading`, `maxItems`, `wishlistedIds`, and owns the `loading` (skeletons), `empty` (overridable copy), and ready states. It renders `ProductCard` cells (single source of cell markup) and reports actions through the same callbacks. `error` remains the host's responsibility.
-  - Migration: pass a listing's data to `ProductGrid` with `items`, `heading`, and `maxItems`; pass a single item to `ProductCard` via `item`. Resolve rich-presentation wishlist state per cell through `wishlistedIds` on the grid or `wishlisted` on the cell. The delimited showcase `ProductShowcase1` is unchanged.
-
-- b41cc50: Require an image for the `Feature` block's `split` presentation.
-
-  - `featureSplitSpecSchema` now requires `presentation: 'split'` and a non-empty, trimmed `image.src`; `featureCardsSpecSchema` keeps `image` out of its contract. `featurePropsSchema` is the union of both branches, so TypeScript narrows `image` only after checking `presentation`.
-  - The component throws a configuration error when an untyped caller renders `split` without a non-empty image, instead of silently dropping the media column. `cards` is unchanged.
-  - Editorial fallbacks belong to the consumer, not the block library. The showcase now owns `public/demo/editorial-fallback.svg`; the storefront template seeds a neutral image in user-owned `content.ts`.
-
-  Migration: pass `{ image: { src, alt } }` when using `presentation="split"`, or switch to `presentation="cards"` if the section is icon-only. Replace the storefront's neutral seed with real editorial imagery.
-
-### Minor Changes
-
-- 80d4137: Add optional, backward-compatible brand customization to existing surfaces (M5):
-
-  - `@thorprovider/blocks`: `Navbar4` and `FooterSection1` accept an optional wordmark accent `{ text, className }` (trailing segment of the brand name) and an optional surface `className`; a supplied surface `className` overrides the default surface paint (default background/backdrop not emitted) so a branded surface paints correctly. `StorefrontHero1` accepts an optional editorial `heroImage { src, alt }` rendered with a native, guarded image. `ProductCategory2` accepts an optional `itemCount`: an unknown count is omitted (no fabricated `0`), a real `0` is preserved, and non-finite/negative values render no count. All props are optional and omit to the current rendering, so existing consumers are unchanged; no new block type or variant is added, and the blocks stay framework-, backend-, and data-free.
-  - `@thorprovider/storefront`: the scaffold generates a user-owned `lib/<name>/shell/{content,props}.ts` seam (brand accents, surface classes, footer description/links, newsletter) that the derived spec composes last, so `storefront sync` regenerates only derived wiring and preserves user-owned edits. The scaffold ships no newsletter submit callback, so the newsletter is omitted by default rather than rendering a fake form; default footer copy makes no delivery/shipping promise and links only to routes the storefront serves (no assumed route). No new identity CLI command is added — `create --site-name` already covers the site name.
-
-  This changeset adds release metadata only; it does not bump versions or publish packages.
-
-- 3b3c24c: Add validated single-store commerce contracts, explicit real/mock policy, directed variant pricing, persistent guest carts, backend-authoritative totals, manual TEST checkout, and capability-authorized receipt reconciliation in generated storefronts.
-
-  Breaking migration: `@thorprovider/types` is now entirely type-only. Import `SupportedProviderType`, `PROVIDER_METADATA`, `isSupportedProviderType`, `getProviderMetadata`, and `StorefrontConfigError` from `@thorprovider/adapters` instead. The pre-1.0 curated blocks/runtime APIs also change: product detail uses canonical options/variants/Money and explicit variant selection; confirmation totals and lines use Money; `formatMoney` returns `null` for unavailable values. Real-mode failures no longer silently return mock data.
-
-  The local packed MVP candidate retains its exact current version pins until a separate release updates the compatible toolset. This changeset does not publish packages or establish public-sales readiness.
-
-- b41cc50: Deliver the global shopper account experience (M5, change `storefront-navbar-account-menu`):
-
-  - `@thorprovider/blocks`: `Navbar4` renders a session-driven account affordance from consumer props only. An authenticated `user` (optional `avatar`) with `accountMenuItems` gets an account menu (identity + configured items + consumer-supplied sign-out); no `user` with a configured `accountHref` gets a signed-out entry point on desktop and mobile; neither configured renders no account affordance or empty container. Optional `accountPending`/`accountUnavailable` drive a pending/disabled state and an accessible unavailable/retry state (`onAccountRetry`) without presenting either as anonymous, and sign-out is suppressed while pending. Absent avatar uses the initials fallback (no empty image `src`). All callbacks stay consumer bindings outside the serializable JSON prop schema; the block never authenticates.
-  - `@thorprovider/storefront`: a mounted `customer-auth` resolves the shopper server-side per request and seeds an allowlisted display identity (`id`, `email`, `firstName`, `lastName`; the auth token stays in its httpOnly cookie). One shared client lifecycle (`account-lifecycle.client.tsx`) owns identity, guarded claims, login/register/logout, and retry with no identity fetch on mount or navigation; it reconciles same-store tabs through non-secret store-scoped signals (`BroadcastChannel` with a storage-event fallback) and on foreground/resume, discards stale generations, and shows a neutral pending state instead of stale identity/orders or a fake sign-out. `/account` is the only account surface — sign-in, registration, identity, sign-out, and real paginated orders + detail (route-scoped commerce, no direct HTTP); no address book/profile/wishlist/social/recovery/cart-merge. Account wiring is delivered through derived files (`account-session*.ts`, `account-lifecycle/account-boundary/account-mutation/account-reconcile.client.*`, `account-private.core.ts`, `account-user.core.ts`, `projection-ownership*.ts`, `registry.tsx`, `schema.ts`, `spec/index.ts`); user-owned files (`views/*/{schema,content,props,data}.ts`, `mappers.ts`, `icon-map.ts`, `shell/**`) survive `sync`. `storefront feature add|remove customer-auth` toggles the `/account` route, session reads, listeners, and navbar chrome together; without the feature the generated registry carries no account-lifecycle/account-reconcile reference and reads no session.
-  - `@thorprovider/adapters`: `getCurrentCustomer()` resolves `null` only for a confirmed unauthenticated response (HTTP 401 / `"Unauthorized"`) and throws a typed `ProviderAPIError` (`GET_CURRENT_CUSTOMER_FAILED`) on operational failures (network, timeout, 5xx), so a host can distinguish an anonymous shopper from a backend outage and render the unavailable state instead of a false sign-out. `isAuthenticated()` delegates to it and can reject. Signature and framework-agnostic boundary are unchanged.
-
-  This changeset adds release metadata only; it does not bump versions or publish packages.
-
-- ece154d: Gate the `ProductOverview` wishlist affordance on a wired handler.
-
-  - `ProductOverview` renders its wishlist button only when `onToggleWishlist` is supplied; an unwired button is a dead control and is no longer rendered in any presentation (`standard`, `gallery`, `rich`).
-  - The storefront product template and the demo/electrostore registries drop their no-op `onToggleWishlist` wiring, so a storefront without wishlist backend support no longer shows a non-functional heart.
-
-### Patch Changes
-
-- ece154d: Align the `Breadcrumb` block with the page content: the trail now renders inside the shared responsive container (`mx-auto w-full max-w-7xl px-4 py-4 sm:px-6 lg:px-8`) that sibling blocks use, instead of sitting flush against the viewport edge. The container is merged with the incoming `className` via `cn`, so a custom `className` can still override it.
-- Updated dependencies [23f876f]
-- Updated dependencies [3b3c24c]
-  - @thorprovider/types@6.0.0

package/components.json

@@ -1,33 +0,0 @@
-{
-  "$schema": "https://ui.shadcn.com/schema.json",
-  "style": "new-york",
-  "rsc": true,
-  "tsx": true,
-  "tailwind": {
-    "config": "",
-    "css": "",
-    "baseColor": "neutral",
-    "cssVariables": true,
-    "prefix": ""
-  },
-  "aliases": {
-    "components": "@/_seed",
-    "utils": "@/lib/utils",
-    "ui": "@/ui",
-    "lib": "@/lib",
-    "hooks": "@/hooks"
-  },
-  "iconLibrary": "lucide",
-  "registries": {
-    "@shadcnstore": "https://shadcnstore.com/r/{name}.json",
-    "@shadcnstore-pro": {
-      "url": "https://shadcnstore.com/r/{name}.json",
-      "params": {
-        "token": "${SHADCNSTORE_TOKEN}"
-      },
-      "headers": {
-        "Authorization": "Bearer ${SHADCNSTORE_TOKEN}"
-      }
-    }
-  }
-}

package/docs/standards/data-contracts.md

@@ -1,81 +0,0 @@
----
-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-10-17"
-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.
-
-## Canonical product card: evidence comes from the host
-
-`ProductCard` renders ratings, badges, discount labels, and stock claims only
-from host-supplied data (`rating`, `badge` copy, `compareAtPrice`); it never
-invents stars, chips, scarcity copy, or crossed-out prices, and a compare-at
-price renders only when it is valid and strictly higher. Boundaries must not
-compensate by fabricating evidence: if the host lacks a rating, the card
-renders none — do not serialize a default `5` or a stock-urgency string to
-"fill" the UI.
-
-## 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}`.
-- [ ] No fabricated ratings, badges, stock claims, or crossed-out prices are serialized to fill absent evidence.

package/docs/standards/theming.md

@@ -1,112 +0,0 @@
----
-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 **no component CSS** — the package declares no
-design and defines no `:root` tokens. Block classes are utility classes that
-resolve against the consumer's own theme tokens at build time. What the package
-does ship is a **one-line Tailwind source-registration entry** so the consumer's
-build scans the library's compiled class names. Register it from the consumer
-stylesheet:
-
-```css
-@import "@thorprovider/blocks/styles.css";
-```
-
-The entry contains only `@source "./dist";` (a path relative to the entry file,
-so it resolves in any install layout — monorepo, pnpm, npm). This is the
-canonical Tailwind v4 pattern for a UI library: `@source` registers the files the
-consumer's Tailwind scans, and it survives the package manager because it never
-assumes the consumer's filesystem layout.
-
-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.
-
-### Rule 5: The consumer registers the library source, and declares dark mode
-
-A conformant theme:
-
-- imports the package registration entry (`@import "@thorprovider/blocks/styles.css";`)
-  so block classes compile — never a monorepo-relative `@source "../../../packages/blocks/src"`;
-- defines the `dark` custom variant (`@custom-variant dark (&:is(.dark *));`) so
-  the library's `dark:` utilities activate.
-
-The scaffold template shipped by `@thorprovider/create-storefront` already does
-both; a hand-rolled theme MUST add them.
-
-## 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.