Build v5.0.0

.github/hooks/hooks.json

@@ -0,0 +1,13 @@
+{
+  "version": 1,
+  "hooks": {
+    "postToolUse": [
+      {
+        "type": "command",
+        "bash": "node .github/hooks/scripts/biome-check.mjs",
+        "cwd": ".",
+        "timeoutSec": 60
+      }
+    ]
+  }
+}

.github/hooks/scripts/biome-check.mjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+
+import { execSync } from "node:child_process"
+import { createInterface } from "node:readline"
+
+const SUPPORTED_EXTENSIONS = /\.(ts|tsx|js|jsx|json)$/
+const FILE_TOOLS = new Set(["edit", "create"])
+
+async function readStdin() {
+  return new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, terminal: false })
+    const lines = []
+    rl.on("line", (line) => lines.push(line))
+    rl.on("close", () => resolve(lines.join("\n")))
+  })
+}
+
+const raw = await readStdin()
+const input = JSON.parse(raw)
+
+if (!FILE_TOOLS.has(input.toolName)) process.exit(0)
+
+const toolArgs = JSON.parse(input.toolArgs)
+const filePath = toolArgs.path
+
+if (!filePath || !SUPPORTED_EXTENSIONS.test(filePath)) process.exit(0)
+
+try {
+  execSync(`pnpm biome check "${filePath}"`, {
+    stdio: "inherit",
+  })
+} catch {
+  process.exit(1)
+}

.github/workflows/gh-pages.yaml

@@ -1,11 +1,7 @@
 name: Deploy to Pages
 
 on:
-  # Runs on pushes targeting the default branch
-  push:
-    branches: ["main"]
-
-  # Allows you to run this workflow manually from the Actions tab
+  # Temporarily disabled - re-enable by adding push trigger back
   workflow_dispatch:
 
 # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
@@ -25,17 +21,17 @@ jobs:
 
     steps:
       - name: Checkout 🛎️
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: pnpm 🧰
-        uses: pnpm/action-setup@v3
+        uses: pnpm/action-setup@v6
         with:
-          version: 8
+          version: 10
 
       - name: Node 🧰
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v6
         with:
-          node-version: 'latest'
+          node-version: '20.x'
           cache: "pnpm"
 
       - name: Install 📦

.github/workflows/pgk-pr-new.yaml

@@ -19,26 +19,26 @@ jobs:
 
     steps:
       - name: Checkout 🛎️
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           persist-credentials: false
 
       - name: pnpm 🧰
-        uses: pnpm/action-setup@v3
+        uses: pnpm/action-setup@v6
         with:
-          version: 9.x
+          version: 10
 
       - name: Node 🧰
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
           node-version: 22.x
 
       - name: Install 📦
         run: pnpm install --frozen-lockfile
 
       - name: Build elements 🛠
-        run: pnpm build
+        run: pnpm --filter @commercelayer/core-components --filter @commercelayer/react-hooks-components --filter @commercelayer/react-components build
 
       - name: Publish 🚀 pkg.pr.new
         run: |
-          npx pkg-pr-new publish './packages/react-components' --no-template
+          npx pkg-pr-new publish './packages/react-components' './packages/core-components' './packages/react-hooks-components' --no-template

.github/workflows/publish.yaml

@@ -14,15 +14,15 @@ jobs:
 
     steps:
       - name: Checkout 🛎️
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: pnpm 🧰
-        uses: pnpm/action-setup@v4
+        uses: pnpm/action-setup@v6
         with:
           version: 10
 
       - name: Node 🧰
-        uses: actions/setup-node@v5
+        uses: actions/setup-node@v6
         with:
           node-version: 20.x
           registry-url: https://registry.npmjs.org

.github/workflows/release.yaml

@@ -13,7 +13,7 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Create a draft GitHub release 🎁
-        uses: softprops/action-gh-release@v1
+        uses: softprops/action-gh-release@v2
         with:
           token: ${{ secrets.COMMERCELAYER_CI_TOKEN }}
           draft: true

.gitignore

@@ -136,4 +136,7 @@ dist
 .DS_Store
 
 # Storybook
-storybook-static
+storybook-static
+
+# Blog articles
+episode-*

.husky/pre-commit

@@ -1,4 +1 @@
-#!/usr/bin/env sh
-. "$(dirname -- "$0")/_/husky.sh"
-
-pnpm build
+pnpm build && pnpm test

.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "storybook": {
+      "command": "pnpm",
+      "args": ["--filter", "document", "run", "mcp"]
+    }
+  }
+}

.ncurc.cjs

@@ -1,6 +1,3 @@
 module.exports = {
-  reject: [
-    'pnpm',
-    'iframe-resizer'
-  ]
-}
+  reject: ["pnpm", "iframe-resizer"],
+}

.vscode/settings.json

@@ -1,21 +1,9 @@
 {
-  "typescript.tsdk": "node_modules/typescript/lib",
   "editor.formatOnSave": true,
-  "javascript.format.enable": true,
-  "eslint.workingDirectories": [
-    "packages/react-components",
-    "packages/docs",
-  ],
-  "eslint.validate": [
-    "javascript",
-    "javascriptreact",
-    "typescript",
-    "typescriptreact"
-  ],
-  "css.validate": false,
-  "less.validate": false,
-  "scss.validate": false,
+  "editor.defaultFormatter": "biomejs.biome",
   "editor.codeActionsOnSave": {
-    "source.fixAll": "explicit"
-  }
-}
+    "source.fixAll.biome": "explicit",
+    "source.organizeImports.biome": "explicit"
+  },
+  "biome.configurationPath": "./biome.json"
+}

AGENTS.md

@@ -0,0 +1,13 @@
+## Agent skills
+
+### Issue tracker
+
+Issues live in GitHub Issues at `commercelayer/commercelayer-react-components`. See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+Default five-role vocabulary (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`). See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+Single-context repo: one `CONTEXT.md` + `docs/adr/` at the root. See `docs/agents/domain.md`.

CONTEXT.md

@@ -0,0 +1,36 @@
+# React Components — Payment
+
+This context covers the React components and state that let a storefront select a payment method and attach a payment source to an order during checkout.
+
+## Language
+
+**Payment Method**:
+A selectable payment option on an order (a configured gateway option, e.g. "Stripe"). Backed by the `payment_method` resource.
+_Avoid_: gateway (as a synonym), payment type
+
+**Payment Source**:
+The concrete payment instrument record attached to a single order (e.g. `stripe_payment`, `adyen_payment`, `wire_transfer`). Created per order from the selected Payment Method.
+_Avoid_: payment, card, token
+
+**Customer Payment Source**:
+A Payment Source saved to a Customer for reuse across orders (a stored card). Selected via the order's `_customer_payment_source_id`.
+_Avoid_: saved card (informal), wallet
+
+**Payment Gateway**:
+In this codebase, the React component that wires a specific gateway's UI/SDK and drives Payment Source creation for that gateway (e.g. `StripeGateway`, `AdyenGateway`).
+_Avoid_: using "gateway" to mean the Payment Method
+
+## Relationships
+
+- An **Order** has at most one **Payment Method** and one **Payment Source**
+- A **Payment Source** is created from the selected **Payment Method**
+- A **Customer Payment Source** belongs to a **Customer**; selecting one sets the **Order**'s Payment Source
+
+## Example dialogue
+
+> **Dev:** "When the shopper picks Stripe, do we create the **Payment Source** in the `StripePayment` component?"
+> **Domain expert:** "No — Stripe has no dedicated creation component. The `StripeGateway`/`PaymentGateway` effect creates the **Payment Source** once the **Payment Method** is selected. Adyen and Braintree, by contrast, create it inside their own components."
+
+## Flagged ambiguities
+
+- "set payment source" was used to mean both the async operation that creates/attaches a Payment Source *and* the reducer action that stores it in state — resolved: the operation is `setPaymentSource(...)`, the reducer action is `dispatch({ type: "setPaymentSource" })`.

biome.json

@@ -1,41 +1,63 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.3.11/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.4.15/schema.json",
   "vcs": {
-    "enabled": false,
+    "enabled": true,
     "clientKind": "git",
-    "useIgnoreFile": false
+    "useIgnoreFile": true
   },
   "files": {
-    "ignoreUnknown": false,
-    "includes": ["**"]
+    "ignoreUnknown": true,
+    "includes": [
+      "**",
+      "!dist",
+      "!coverage",
+      "!*.min.js",
+      "!**/mocks/resources/orders/customer-orders-full.ts"
+    ]
   },
   "formatter": {
     "enabled": true,
-    "indentStyle": "space"
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 100
+  },
+  "assist": {
+    "enabled": true,
+    "actions": {
+      "source": {
+        "organizeImports": "on"
+      }
+    }
   },
-  "assist": { "actions": { "source": { "organizeImports": "on" } } },
   "linter": {
     "enabled": true,
     "rules": {
-      "recommended": true,
-      "style": {
-        "noParameterAssign": "error",
-        "useAsConstAssertion": "error",
-        "useDefaultParameterLast": "error",
-        "useEnumInitializers": "error",
-        "useSelfClosingElements": "error",
-        "useSingleVarDeclarator": "error",
-        "noUnusedTemplateLiteral": "error",
-        "useNumberNamespace": "error",
-        "noInferrableTypes": "error",
-        "noUselessElse": "error"
-      }
+      "recommended": true
     }
   },
   "javascript": {
     "formatter": {
       "quoteStyle": "double",
+      "trailingCommas": "es5",
       "semicolons": "asNeeded"
     }
+  },
+  "json": {
+    "formatter": {
+      "enabled": true,
+      "trailingCommas": "none"
+    },
+    "linter": {
+      "enabled": true
+    }
+  },
+  "css": {
+    "formatter": {
+      "enabled": true,
+      "quoteStyle": "double"
+    },
+    "linter": {
+      "enabled": true
+    }
   }
 }

docs/adr/0001-coalesce-payment-source-requests.md

@@ -0,0 +1,19 @@
+# Coalesce concurrent payment-source requests
+
+## Context
+
+`setPaymentSource` (in `PaymentMethodReducer.ts`) is a plain async function driven by React effects — notably the `PaymentGateway` effect, which fires it fire-and-forget from a 23-dependency effect. Before the first `create`/`update`/`updateOrder` request resolves, both `paymentSource` (context state) and `order.payment_source` are still null, so any dependency change re-runs the effect and fires a **second** request. On the Stripe / single-payment-method / new-source flow this produced two `stripe_payments.create` calls and two payment source records.
+
+## Decision
+
+De-duplicate genuinely-concurrent calls with a module-level `Map<string, Promise>` keyed by `` `${order.id}:${paymentResource}:${customerPaymentSourceId ?? paymentSourceId ?? 'create'}` ``. The first call stores its in-flight promise; concurrent calls with the same key return that same promise; the entry is deleted in a `finally` once it settles. This coalesces duplicates within a burst without permanently memoizing, so a later legitimate re-create still runs. It backs up the narrower in-flight `useRef` guard in the `PaymentGateway` effect and protects every gateway, not just Stripe.
+
+## Considered options
+
+- **Effect-only `useRef` guard** — kept as the first line of defense, but too narrow: only protects the `PaymentGateway` caller, not other gateways or future callers.
+- **Idempotency check against `order.payment_source`** — unreliable: the order is stale until `getOrder` refreshes after the first request.
+- **Hashing `attributes` into the key** — rejected as fragile; attributes are effectively constant for a given order + resource + path within a burst.
+
+## Consequences
+
+The reducer module now holds mutable global state, which reads as surprising for an otherwise-stateless function — this ADR is the "why." The key deliberately separates the create, update/retrieve, and saved-source (`updateOrder`) paths so coalescing never merges semantically different operations.