@thorprovider/blocks 0.1.0

package/.turbo/turbo-build.log

@@ -0,0 +1,24 @@
+CLI Building entry: {"index":"src/index.ts","contracts":"src/lib/contracts.ts"}
+CLI Using tsconfig: tsconfig.json
+CLI tsup v8.5.1
+CLI Using tsup config: /home/nelson/dev/active/thorprovider/repos/thorcommerce/packages/blocks/tsup.config.ts
+CLI Target: esnext
+CLI Cleaning output folder
+CJS Build start
+ESM Build start
+CJS dist/contracts.js     8.15 KB
+CJS dist/index.js         801.34 KB
+CJS dist/contracts.js.map 12.65 KB
+CJS dist/index.js.map     1.13 MB
+CJS ⚡️ Build success in 801ms
+ESM dist/contracts.mjs     5.12 KB
+ESM dist/index.mjs         708.79 KB
+ESM dist/contracts.mjs.map 12.54 KB
+ESM dist/index.mjs.map     1.14 MB
+ESM ⚡️ Build success in 815ms
+DTS Build start
+DTS ⚡️ Build success in 17297ms
+DTS dist/index.d.ts      86.38 KB
+DTS dist/contracts.d.ts  17.94 KB
+DTS dist/index.d.mts     86.38 KB
+DTS dist/contracts.d.mts 17.94 KB

package/.turbo/turbo-test.log

@@ -0,0 +1,10 @@
+
+ RUN  v3.2.4 /home/nelson/dev/active/thorprovider/repos/thorcommerce/packages/blocks
+
+ ✓ src/blocks/e-commerce/checkout-forms/card-formatting.test.ts (10 tests) 14ms
+
+ Test Files  1 passed (1)
+      Tests  10 passed (10)
+   Start at  16:54:02
+   Duration  1.03s (transform 162ms, setup 0ms, collect 93ms, tests 14ms, environment 0ms, prepare 252ms)
+

package/AGENTS.md

@@ -0,0 +1 @@
+<!-- BLOCKS-AGENTS-MD-START -->[@thorprovider/blocks Docs]|root: ./blocks|Documentation for @thorprovider/blocks. Always read package docs before making changes.|To regenerate: yarn workspace @thorprovider/blocks generate:agent-index|.:{README.md}|docs/standards:{data-contracts.md,theming.md}<!-- BLOCKS-AGENTS-MD-END -->

package/README.md

@@ -0,0 +1,161 @@
+---
+title: "@thorprovider/blocks"
+purpose: "Reusable, framework-agnostic storefront blocks built from ShadcnStore UI, decoupled from data and backend"
+lastReviewed: "2026-09-23"
+---
+
+# @thorprovider/blocks
+
+Reusable storefront UI blocks for Thor Commerce, built from [ShadcnStore](https://shadcnstore.com) blocks and transformed into prop-driven, framework-agnostic components.
+
+## Principles
+
+- **Framework-agnostic.** No `next/*`, `react-router`, or `@thorprovider/*` imports. Components render anywhere React runs (Next.js, Vite, json-render).
+- **No data baked in.** Demo content, images, and branding live in the consuming app. Blocks receive data via props.
+- **Single source of primitives.** The vendored shadcn primitives under `src/ui/` are the only copy; consumers import them from this package instead of installing their own.
+- **No over-abstraction.** Values are split into props vs internal detail with judgment. A prop is added only when the value is genuinely content or configuration; layout and decoration stay internal.
+- **Shared contracts only when reused.** A type like `CTA` is promoted to `src/lib/types.ts` only once two blocks share it.
+
+## Structure
+
+```
+src/
+├── index.ts                  # Public API: blocks, primitives, types
+├── lib/
+│   ├── utils.ts              # cn() helper (clsx + tailwind-merge)
+│   └── types.ts              # Shared prop contracts (e.g. CTA)
+├── ui/                       # Vendored shadcn primitives (CLI-managed, single source)
+└── blocks/
+    ├── marketing/
+    │   └── hero-sections/hero-section-1.tsx
+    └── e-commerce/
+        ├── product-list/product-card-1.tsx
+        └── storefront-hero/storefront-hero-1.tsx
+```
+
+Blocks follow `src/blocks/<category>/<section>/<block>.tsx`. Each block co-locates its own prop types unless a contract is shared by two or more blocks.
+
+## Blocks
+
+| Export | Category | Description |
+| --- | --- | --- |
+| `Navbar1` | Marketing | Simple navbar with logo, links, sign-in, CTA and cart count |
+| `Navbar2` | Marketing | Mega-menu navbar with grouped flyouts and featured card |
+| `Navbar3` | Marketing | Floating navbar that condenses into a rounded pill on scroll |
+| `Navbar4` | Marketing | Storefront navbar: utility bar, category links, search, account menu, cart sheet |
+| `Banner1` | Marketing | Announcement banner (bar or pill) with dismiss |
+| `HeroSection1` | Marketing | Hero with badge, headline, CTA, reviewer avatars, rating and image |
+| `CtaSection1` | Marketing | Full-width call-to-action with badge, headline and two CTAs |
+| `Feature1` | Marketing | Icon feature grid |
+| `Feature2` | Marketing | Split features with image |
+| `Testimonial1` | Marketing | Testimonial carousel with rating stars |
+| `Testimonial2` | Marketing | Bento testimonials grid |
+| `FaqBlock1` | Marketing | FAQ accordion (single or multiple open) |
+| `PricingSection1` | Marketing | Pricing tiers with popular badge |
+| `Statistic1` | Marketing | Metrics grid with progress bars |
+| `LogoCloud1` | Marketing | Logo cloud with skeleton fallback |
+| `FooterSection1` | Marketing | Footer with brand, link columns and newsletter |
+| `FooterSection3` | Marketing | Newsletter + six-column footer with social links |
+| `ProductCard1` | E-commerce | Deals grid of product cards with add-to-cart |
+| `ProductCard2` | E-commerce | Clean three-up grid with ratings |
+| `ProductCard3` | E-commerce | Deals grid with badges, low-stock and wishlist |
+| `ProductCard5` | E-commerce | Table-style comparison with sorting and filtering |
+| `ProductOverview1` | E-commerce | Product detail with gallery, variants and add-to-cart |
+| `ProductQuickView` | E-commerce | Quick-view dialog with gallery, variants and quantity |
+| `ReviewRating1` | E-commerce | Review list with rating summary |
+| `ReviewRating2` | E-commerce | Rating summary with distribution and review carousel |
+| `ProductCategory1` | E-commerce | Category grid with view-all |
+| `ProductCategory2` | E-commerce | Image-based category cards |
+| `ProductCategory4` | E-commerce | Icon grid with customer/product counts |
+| `ProductCategory5` | E-commerce | Category list with search and subcategories |
+| `CategoryFilter1` | E-commerce | Category filter bar |
+| `CategoryFilter2` | E-commerce | Filter sidebar with mobile sheet |
+| `ShoppingCart1` | E-commerce | Detailed cart summary |
+| `ShoppingCart2` | E-commerce | Cart with promo code and shipping |
+| `ShoppingCart4` | E-commerce | Collapsible cart drawer with promotion progress |
+| `CheckoutForm1` | E-commerce | Essential checkout fields |
+| `CheckoutForm2` | E-commerce | Single-page checkout with order summary beside |
+| `CheckoutConfirmation` | E-commerce | Order confirmation with fulfilment timeline |
+| `OrderHistory1` | E-commerce | Orders list |
+| `OrderHistory2` | E-commerce | Order cards with carousel items |
+| `StorefrontHero1` | E-commerce | Storefront hero with gradient headline, CTAs and a product grid |
+| `StorefrontHero2` | E-commerce | Search field above a trending product carousel |
+| `StorefrontHero5` | E-commerce | Departments grid with featured deals |
+| `StorefrontHero6` | E-commerce | Rotating deals bar beside category cards |
+| `AppShell1` | Application | Application shell with navigation slots |
+| `LoginPage1` | Application | Login card with remember-me and social buttons |
+| `LoginPage2` | Application | Login with prominent social options |
+| `SignUpPage1` | Application | Registration card with social options |
+| `ForgotPasswordPage1` | Application | Four-step password recovery wizard |
+| `Verify1` | Application | Two-factor verification (OTP or backup code) |
+
+Interactions are exposed as callbacks (e.g. `onAddToCart`, `onBuyNow`, `onSelectColor`). Elements stay in the DOM with no-op behavior when a callback is absent.
+
+## Checkout blocks (controlled)
+
+`CheckoutForm1` (3-step wizard) and `CheckoutForm2` (single page) are **controlled components**: they receive the current form values through a `values` prop and report every edit through `onChange`. They hold no internal form state, so a renderer's validation context can read field values from its own state model. `CheckoutForm3` (4-step wizard) keeps the same contract with internal step state.
+
+- `paymentMethods?: PaymentMethod[]` — available payment methods as data (canonical `@thorprovider/types` `PaymentMethod`). The blocks render a radio list from this prop, show the selected method's name + `description`, and only render the card fields (`cardNumber`, `expiryDate`, `cvv`, `cardName`) when the selected method's `type === 'card'`. No payment method is hardcoded; pass an empty list to trigger the empty state.
+- `values: CheckoutForm1FormData` / `CheckoutForm2Data` — current field values (including `cardNumber`, `expiryDate`, `cvv`, `cardName`, and `paymentMethod` for `CheckoutForm1`/`CheckoutForm3`).
+- `onChange: (field, value) => void` — reported per edit; card grouping and MM/YY masking are applied by the block before the value reaches `onChange` (presentation only, no validation logic in the block).
+- `fieldErrors?: Partial<Record<FieldKey, Array<{ message?: string }>>>` — per-field error messages rendered via `FieldError` (`role="alert"`, `aria-invalid`/`aria-describedby` wiring). The same channel carries async/server errors (e.g. payment decline, invalid promo).
+- `fieldDescriptions?: Partial<Record<FieldKey, string>>` — helper text rendered via `FieldDescription`.
+- `validateStep?: (step: number) => boolean` (wizard only) — the block calls it on "Next"; advance only happens when it returns `true`, and the final submit only fires when every step validates.
+
+Validation itself is **not** implemented in the blocks. Declare checks in your store spec's validation configuration (built-in `required`/`email`/`pattern`/`minLength`/`maxLength`/cross-field `requiredIf`/`equalTo`/`lessThan`/`greaterThan`, plus catalog-registered custom functions like `luhn`/`cvv`/`expiryDate`) and evaluate them with the renderer; the messages live in the spec so they are per-store and per-language. Without a validation provider the blocks render with no inline errors.
+
+## Usage
+
+```tsx
+import { HeroSection1 } from '@thorprovider/blocks'
+
+<HeroSection1
+  title="Welcome to ShadcnStore"
+  description="Discover our premium collection of handcrafted UI blocks"
+  badge="Premium UI Components"
+  cta={{ label: 'Explore Collection' }}
+  reviewers={[{ id: 1, avatarUrl: '...', fallback: 'U1' }]}
+  rating={{ value: 5, count: 15 }}
+  trustedBy="Trusted by 1000+ developers"
+  image={{ src: '/hero.png', alt: 'Hero preview' }}
+/>
+```
+
+## Development
+
+```bash
+yarn workspace @thorprovider/blocks dev      # tsup watch
+yarn workspace @thorprovider/blocks type-check
+yarn workspace @thorprovider/blocks build    # dist/ with .d.ts
+```
+
+The `'use client'` banner is injected at build time (tsup `banner`) so the bundled library is consumed correctly by Next.js.
+
+## Adding a new block
+
+1. Install the raw block as a seed: `npx shadcn@latest add @shadcnstore/<block> --cwd packages/blocks`
+2. Transform it into `src/blocks/<category>/<section>/<block>.tsx`: rewrite `@/...` imports to relative, split hardcoded values into props vs internal detail, expose interactions as callbacks.
+3. Remove the seed file and add the block export to `src/index.ts`.
+4. Add a registry entry + demo data file in `projects/blocks-showcase` (see its README).
+
+See `openspec/changes/add-thorprovider-blocks/design.md` for the full design decisions (D1–D8).
+
+## Block data contracts
+
+Blocks render props blindly, so the **boundary** (mappers/transforms/store
+specs) must follow two hygiene rules: optional fields are never `""` (emit
+`undefined` or a fallback such as `PRODUCT_IMAGE_FALLBACK`), and React keys are
+unique by contract, not by convention. See
+[`docs/standards/data-contracts.md`](docs/standards/data-contracts.md) for the
+rules and the review checklist.
+
+## Block interaction contracts
+
+State and events between a block, its host registry, and the store must follow
+the state-sync hygiene rules: blocks report changes from event handlers, never
+from effects (`isInitialMount` is not a loop breaker); hosts pass identity-stable
+callbacks (`useCallback`); a fresh object literal always notifies a reference-only
+store guard; and every registered action completes its round-trip (handler → set +
+emit → spec `on` → recompute → bind). See
+[`docs/standards/interaction-contracts.md`](docs/standards/interaction-contracts.md)
+for the rules and the review checklist.

package/components.json

@@ -0,0 +1,33 @@
+{
+  "$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}"
+      }
+    }
+  }
+}