@clicktap/ui 0.40.8 → 0.40.10

package/docs/migrations/2026/05/2026-05-21-button-loading-content.md

@@ -0,0 +1,265 @@
+# `ButtonLoadingContent` helper — standardized right-side spinner for all submit buttons
+
+**Date:** 2026-05-21
+**Affects:** `@clicktap/ui/components/Button` (new `ButtonLoadingContent` export) and every submit-style button in the frontend app.
+**Classification:** IMPROVEMENT
+**Breaking:** No
+
+## Dependencies
+
+*None.*
+
+## Summary
+
+A new `ButtonLoadingContent` helper exported from `@clicktap/ui/components/Button` provides the canonical "label + right-side spinner" layout for any submit button. The spinner fades in via opacity (no layout shift), an invisible spacer on the left keeps the label visually centered in both states, and the label stays visible the whole time. This pattern is now used everywhere a submit button needs to show progress — Place Order, Continue (checkout step actions), Sign in / Sign up / Reset password, Save Address, Update / Remove / Add payment method, PDP Add to cart, etc.
+
+Before this change, submit buttons across the app inconsistently mixed:
+- text swaps (`isSubmitting ? 'Updating…' : 'Update'`),
+- spinner-only (`isSubmitting ? <CircularEasing /> : 'Continue'`),
+- inline copy of the Place-Order span/spacer/spinner pattern (`<span className="inline-flex ..."><span className="w-5" /> Place order <span className={isLoading ? 'opacity-100' : 'opacity-0'}>...`),
+- nothing at all.
+
+They now all use `ButtonLoadingContent`.
+
+## Why
+
+Two reasons converged:
+
+1. **Inconsistent UX.** Some buttons swapped to "Updating…" text; others showed a spinner instead of the label; some did both; some did neither. There was no single canonical pattern, so visitors got different feedback styles depending on which surface they were on.
+
+2. **A real bug behind the inconsistency.** The Continue-to-review button in checkout was set up to show a loader during step submission, but the Cybersource and Auth.Net `NewCardForm` event handlers were flipping `isSubmitting` back to `false` immediately after dispatching the form-submit event. The label stayed visible (or no loader appeared) during the entire save-card mutation; the loader only reappeared when the state machine reached `submittingStepData`. Standardizing on the helper also forced fixing that — the save-card path now keeps the spinner visible from click through save-card → step-submit.
+
+## Changes
+
+| File | Change |
+|---|---|
+| `libs/ui/src/components/Button/ButtonLoadingContent.tsx` | **New.** The helper component (see API below). |
+| `libs/ui/src/components/Button/index.ts` | Adds `ButtonLoadingContent` to the exports. |
+| `apps/frontend/components/Checkout/Step/Payment/Cybersource/NewCardForm.tsx` | Removed the premature `setIsSubmitting(false)` inside the `paymentMethodSubmit` event handler — the spinner now stays visible through the entire save-card + step-submit flow. |
+| `apps/frontend/components/Checkout/Step/Payment/Authorizenet/NewCardForm.tsx` | Same fix as Cybersource. |
+| `apps/frontend/components/Checkout/Step/StepActions.tsx` | `Continue to review` button: replaced spinner-only-when-loading with `<ButtonLoadingContent>{nextLabel}</ButtonLoadingContent>`. |
+| `apps/frontend/components/Checkout/Step/Review/CheckoutButton.tsx` | The three `Place order` buttons (Cybersource / Auth.Net / NO_PAYMENT_REQUIRED) replaced their hand-rolled label+spacer+spinner spans with `<ButtonLoadingContent>`. |
+| `apps/frontend/components/Checkout/Step/Review/CheckoutButton/OfflineCheckoutButton.tsx` | Same. |
+| `apps/frontend/components/Product/components/AddToCart/AddToCart.tsx` | PDP Add-to-cart now wraps its label in `ButtonLoadingContent` with `isLoading={isUpdatingItems}`. |
+| `apps/frontend/components/Checkout/Step/Payment/Cybersource/SavedCardsForm/SavedCard/EditButton/UpdatePayment.tsx`, `.../Authorizenet/...UpdatePayment.tsx`, `.../Account/PaymentMethods/Cybersource/PaymentMethod/EditButton/UpdatePayment.tsx`, `.../Authorizenet/...UpdatePayment.tsx` | `isSubmitting ? 'Updating…' : 'Update'` → `<ButtonLoadingContent isLoading={isSubmitting}>Update</ButtonLoadingContent>`. |
+| `apps/frontend/components/Checkout/Step/Payment/Cybersource/SavedCardsForm/SavedCard/DeleteButton.tsx`, `.../Authorizenet/.../DeleteButton.tsx` | `isRemoving ? 'Removing…' : 'Remove'` → `<ButtonLoadingContent isLoading={isRemoving}>Remove</ButtonLoadingContent>`. |
+| `apps/frontend/components/Account/PaymentMethods/Cybersource/CreateNewPayment.tsx`, `.../Authorizenet/CreateNewPayment.tsx` | `isSubmitting ? 'Adding payment method' : 'Add payment method'` → `<ButtonLoadingContent>`. |
+| `apps/frontend/components/Account/Address/Create.tsx` | `isSubmitting ? <>Saving Address <CircularEasing/></> : 'Save Address'` → `<ButtonLoadingContent isLoading={isSubmitting}>Save Address</ButtonLoadingContent>`. |
+| `apps/frontend/components/Account/Address/Edit.tsx` | `isSubmitting ? 'Updating' : 'Update'` → `<ButtonLoadingContent>`. |
+| `apps/frontend/components/Account/Auth/Authenticate/Signup.tsx` | `isSubmitting ? 'Signing up' : 'Sign up'` → `<ButtonLoadingContent>`. |
+| `apps/frontend/components/Account/Auth/Authenticate/Signin.tsx` | `isSubmitting || isSubmitted ? 'Signing in' : 'Sign in'` → `<ButtonLoadingContent isLoading={isSubmitting || isSubmitted}>Sign in</ButtonLoadingContent>`. |
+| `apps/frontend/components/Account/Auth/Authenticate/ResetPassword.tsx` | `isSubmitting ? 'Resetting password' : 'Reset password'` → `<ButtonLoadingContent>`. |
+
+## API
+
+```ts
+// @clicktap/ui/components/Button
+export function ButtonLoadingContent({
+  isLoading?: boolean,        // default false
+  spinnerStroke?: string,     // default '#FFFFFF' (suits solid dark buttons)
+  children: ReactNode,        // the button's label
+}): JSX.Element;
+```
+
+Renders (semantically):
+
+```tsx
+<span className="inline-flex items-center gap-2">
+  <span className="w-5" aria-hidden="true" />     {/* invisible spacer */}
+  {children}                                       {/* the label */}
+  <span className={isLoading ? 'opacity-100' : 'opacity-0'}>
+    <CircularEasing stroke={spinnerStroke} width={20} />
+  </span>
+</span>
+```
+
+The spacer matches the spinner's 20px width — the label stays visually centered whether the spinner is visible or not. The spinner fades via opacity, so the layout doesn't shift when `isLoading` flips.
+
+## Usage
+
+```tsx
+import {
+  Button,
+  ButtonLoadingContent,
+} from '@clicktap/ui/components/Button';
+
+<Button
+  type="submit"
+  isLoading={isSubmitting}
+  isDisabled={isSubmitting}
+>
+  <ButtonLoadingContent isLoading={isSubmitting}>
+    Save Address
+  </ButtonLoadingContent>
+</Button>
+```
+
+For outline / ghost buttons (dark text, light background), pass `spinnerStroke`:
+
+```tsx
+<Button variant="outline">
+  <ButtonLoadingContent isLoading={isSubmitting} spinnerStroke="#0f172a">
+    Cancel
+  </ButtonLoadingContent>
+</Button>
+```
+
+## The NewCardForm `setIsSubmitting(false)` bug
+
+A separate but related fix in the same PR: the Cybersource and Auth.Net `NewCardForm` `paymentMethodSubmit` event handlers were doing this:
+
+```ts
+// before
+const handleCustomEvent = (event: Event) => {
+  if (detail?.code === paymentMethodCardCode) {
+    formRef.current?.dispatchEvent(
+      new Event('submit', { cancelable: true, bubbles: true }),
+    );
+    setIsSubmitting(false);  // ← bug: kills the loader before the async work even starts
+  }
+};
+```
+
+After dispatching the form submit, the handler flipped `isSubmitting` to false synchronously. The form's `onSubmit` then began the async save-card mutation + step submission, but the Continue-to-review button no longer showed a loader. The loader only reappeared when the checkout state machine reached `submittingStepData` (after the save-card mutation completed).
+
+```ts
+// after
+const handleCustomEvent = (event: Event) => {
+  if (detail?.code === paymentMethodCardCode) {
+    formRef.current?.dispatchEvent(
+      new Event('submit', { cancelable: true, bubbles: true }),
+    );
+    // Do NOT flip isSubmitting back to false here — the save-card
+    // mutation + step submission both run after this dispatch and
+    // we want the Continue button's spinner to stay visible the
+    // whole time. The error paths in onSubmit and the state
+    // machine's submittingStepData transition own the reset-to-false.
+  }
+};
+```
+
+Apply this same change to your local `NewCardForm` for both gateways if your project pulled the earlier version.
+
+## Migration Steps
+
+1. **Update `@clicktap/ui`** to the version that exports `ButtonLoadingContent`.
+
+2. **Find your existing inconsistent submit-button patterns.** Quick search commands:
+
+   ```bash
+   # text-swap pattern
+   grep -rnE "isSubmitting \\? ['\"]" apps/ libs/ | grep -v vendor | grep -v node_modules
+   grep -rnE "isRemoving \\? ['\"]" apps/ libs/ | grep -v vendor | grep -v node_modules
+   grep -rnE "isLoading \\? ['\"]" apps/ libs/ | grep -v vendor | grep -v node_modules
+
+   # spinner-only pattern in Buttons
+   grep -rnE "isSubmitting \\? <CircularEasing" apps/ libs/ | grep -v vendor
+
+   # hand-rolled Place-Order-style pattern
+   grep -rn "inline-flex items-center gap-2" apps/ | grep -B1 -A4 "CircularEasing"
+   ```
+
+3. **Rewrite each to use `ButtonLoadingContent`.** Three common transforms:
+
+   ```tsx
+   // text-swap → helper
+   // before
+   <Button isLoading={isSubmitting}>
+     {isSubmitting ? 'Updating…' : 'Update'}
+   </Button>
+   // after
+   <Button isLoading={isSubmitting}>
+     <ButtonLoadingContent isLoading={isSubmitting}>
+       Update
+     </ButtonLoadingContent>
+   </Button>
+   ```
+
+   ```tsx
+   // spinner-only → helper (the label stays visible now)
+   // before
+   <Button>
+     {isSubmitting ? <CircularEasing stroke="#FFFFFF" width={24} /> : nextLabel}
+   </Button>
+   // after
+   <Button>
+     <ButtonLoadingContent isLoading={isSubmitting}>
+       {nextLabel}
+     </ButtonLoadingContent>
+   </Button>
+   ```
+
+   ```tsx
+   // hand-rolled span pattern → helper (DRY)
+   // before
+   <Button>
+     <span className="inline-flex items-center gap-2">
+       <span className="w-5" aria-hidden="true" />
+       Place order
+       <span className={isSubmitting ? 'opacity-100' : 'opacity-0'}>
+         <CircularEasing stroke="#FFFFFF" width={20} />
+       </span>
+     </span>
+   </Button>
+   // after
+   <Button>
+     <ButtonLoadingContent isLoading={isSubmitting}>
+       Place order
+     </ButtonLoadingContent>
+   </Button>
+   ```
+
+4. **If your checkout uses the Cybersource or Auth.Net `NewCardForm` pattern**, remove the premature `setIsSubmitting(false)` in the `paymentMethodSubmit` event handler (see "The NewCardForm `setIsSubmitting(false)` bug" above). The save-card mutation + step-submit path own the lifecycle now.
+
+5. **Verify.**
+   - Click Place order on the review step: spinner appears on the right of "Place order", label stays put, no layout shift.
+   - Click Continue to review on the checkout payment step with an unsaved card: spinner appears immediately and stays visible through both the save-card mutation and the step submission, with no flash of label-only state in between.
+   - Click Update / Remove on any saved-card modal: spinner on the right, label stays.
+   - Sign in / Sign up / Reset password: same pattern, no "Signing in…" text variants.
+
+## Pattern for Consumers
+
+The right-side spinner with persistent label is now the canonical submit-feedback pattern across the whole frontend. When adding a new submit button:
+
+```tsx
+<Button
+  type="submit"
+  isLoading={isSubmitting}
+  isDisabled={isSubmitting}
+>
+  <ButtonLoadingContent isLoading={isSubmitting}>
+    {/* the static label */}
+  </ButtonLoadingContent>
+</Button>
+```
+
+Don't reach for text-swap variants (`'Saving...'`, `'Updating...'`, `'Signing in'`) — they look inconsistent with the rest of the site and force the visitor to re-read the button. Don't reach for spinner-only-when-loading — same problem in reverse.
+
+For non-submit buttons that just need a spinner overlay (e.g., a loading state on a non-action element), `CircularEasing` is still exported directly and is the right primitive.
+
+## Files Changed
+
+```
+libs/ui/src/components/Button/ButtonLoadingContent.tsx          (new)
+libs/ui/src/components/Button/index.ts
+
+apps/frontend/components/Checkout/Step/Payment/Cybersource/NewCardForm.tsx
+apps/frontend/components/Checkout/Step/Payment/Authorizenet/NewCardForm.tsx
+apps/frontend/components/Checkout/Step/StepActions.tsx
+apps/frontend/components/Checkout/Step/Review/CheckoutButton.tsx
+apps/frontend/components/Checkout/Step/Review/CheckoutButton/OfflineCheckoutButton.tsx
+apps/frontend/components/Product/components/AddToCart/AddToCart.tsx
+apps/frontend/components/Checkout/Step/Payment/Cybersource/SavedCardsForm/SavedCard/DeleteButton.tsx
+apps/frontend/components/Checkout/Step/Payment/Cybersource/SavedCardsForm/SavedCard/EditButton/UpdatePayment.tsx
+apps/frontend/components/Checkout/Step/Payment/Authorizenet/SavedCardsForm/SavedCard/DeleteButton.tsx
+apps/frontend/components/Checkout/Step/Payment/Authorizenet/SavedCardsForm/SavedCard/EditButton/UpdatePayment.tsx
+apps/frontend/components/Account/PaymentMethods/Cybersource/PaymentMethod/EditButton/UpdatePayment.tsx
+apps/frontend/components/Account/PaymentMethods/Authorizenet/PaymentMethod/EditButton/UpdatePayment.tsx
+apps/frontend/components/Account/PaymentMethods/Cybersource/CreateNewPayment.tsx
+apps/frontend/components/Account/PaymentMethods/Authorizenet/CreateNewPayment.tsx
+apps/frontend/components/Account/Address/Create.tsx
+apps/frontend/components/Account/Address/Edit.tsx
+apps/frontend/components/Account/Auth/Authenticate/Signup.tsx
+apps/frontend/components/Account/Auth/Authenticate/Signin.tsx
+apps/frontend/components/Account/Auth/Authenticate/ResetPassword.tsx
+```

package/docs/migrations/2026/05/2026-05-21-password-check-hide-on-empty.md

@@ -0,0 +1,50 @@
+# `PasswordCheck` `requirements` variant hides until the visitor types
+
+**Date:** 2026-05-21
+**Affects:** `libs/ui/src/components/PasswordCheck/PasswordCheck.tsx`
+**Classification:** IMPROVEMENT
+**Breaking:** No
+
+## Dependencies
+
+*None.*
+
+## Summary
+
+The `requirements` variant of `PasswordCheck` previously rendered all four unchecked bullet-points and a 0% strength bar as soon as the password field was mounted. Before the visitor had typed a single character, this read as a list of demands rather than as live feedback — pre-emptive shouting. Now `PasswordCheck` returns `null` from its `requirements` branch when `value` is empty, and reveals the rules + strength bar on the first keystroke.
+
+This matches the spirit of the existing pattern: feedback that reflects what the visitor is doing right now, not feedback that runs ahead of them.
+
+## Changes
+
+```tsx
+// PasswordCheck.tsx — requirements branch
+if (variant === 'requirements') {
+  if (!value) {
+    return null;
+  }
+
+  return (
+    <div className="mt-4 flex flex-col gap-2">
+      {/* requirements list + strength bar */}
+    </div>
+  );
+}
+```
+
+The `default` variant is unchanged.
+
+## Migration Steps
+
+1. **Pull the latest `@clicktap/ui`** (or merge the equivalent change in your local copy). No public API changed; the only difference is render output for the `requirements` variant.
+
+2. **Verify.**
+   - On the signup form (`/account/authenticate` or in checkout), open the page with the password field unfocused. The previous list of four unchecked requirements should no longer appear; the area below the password input should be empty.
+   - Focus the password input. Type one character. The requirements list and strength bar should reveal, with the rule that's now satisfied (or the first-character rule, if you have one) ticking checked as appropriate.
+   - Clear the field — the requirements should disappear again.
+
+## Files Changed
+
+```
+libs/ui/src/components/PasswordCheck/PasswordCheck.tsx
+```

package/docs/migrations/2026/05/2026-05-29-password-check-requirements-variant.md

@@ -0,0 +1,63 @@
+# `PasswordCheck` — the `requirements` variant (adoption guide for forks)
+
+**Date:** 2026-05-29 (retroactive — the variant already ships in `@clicktap/ui`)
+**Affects:** `libs/ui/src/components/PasswordCheck/PasswordCheck.tsx`, `libs/ui/src/components/PasswordCheck/PasswordCheck.types.ts`
+**Classification:** IMPROVEMENT
+**Breaking:** No (the variant is additive; `default` is unchanged)
+
+## Dependencies
+
+- [`PasswordCheck` `requirements` variant hides until the visitor types](./2026-05-21-password-check-hide-on-empty.md) — the hide-on-empty refinement to this same variant.
+
+## Summary
+
+This guide documents the `requirements` variant of `PasswordCheck` so forked UI libraries (brand-specific `*-ui` packages) have a canonical surface to audit against. A forked library that branched before this variant landed only inherits what's written up — without a guide it stays on the meter-only `default` output and never picks up the per-rule checklist.
+
+`PasswordCheck` renders a live ✓/○ checklist of password-policy rules plus a 5-bar strength meter when `variant="requirements"`. Reach for it on any complexity-enforcing form (signup, password reset, change password) — it surfaces each rule as the visitor types instead of waiting for zod's first-failing-rule message after blur.
+
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `value` | `string` | — | The current password value. |
+| `variant` | `'default' \| 'short' \| 'requirements'` | `'default'` | `requirements` renders the checklist + meter. `default` renders the meter + "Password Strength" text. |
+| `requirements` | `PasswordRequirement[]` | 8 chars / uppercase / digit / special | Override the rule list. Each rule is `{ label: string; test: (value: string) => boolean }`. |
+
+## Behavior
+
+- **Hides when `value` is empty** — showing four unchecked bullets before any input reads as a list of demands rather than live feedback. (See the [hide-on-empty guide](./2026-05-21-password-check-hide-on-empty.md).)
+- Each rule transitions from `○` (slate) to `✓` (green) as it's met.
+- The 5-bar strength meter colors match the `default` variant's meter (red → yellow → green → blue by strength).
+- The component is stateless and pure — strength is derived from `value` via `checkStrength`.
+
+## Usage
+
+```tsx
+<PasswordCheck value={password} variant="requirements" />
+```
+
+With a custom rule list:
+
+```tsx
+<PasswordCheck
+  value={password}
+  variant="requirements"
+  requirements={[
+    { label: 'At least 12 characters', test: (v) => v.length >= 12 },
+    { label: 'No common words', test: (v) => !COMMON.has(v.toLowerCase()) },
+  ]}
+/>
+```
+
+## Forks — what to copy
+
+If you forked `PasswordCheck` into a brand-specific UI library before this variant existed:
+
+1. Copy the `variant === 'requirements'` branch and the `defaultRequirements` list verbatim, then re-skin colors to your palette (e.g. `brand-secondary-*` / `brand-error-*` / `brand-grayscale-*` in place of the raw Tailwind palette).
+2. Add `'requirements'` to your `PasswordCheckProps['variant']` union and the `PasswordRequirement` type.
+3. Switch your complexity-enforcing forms (`Signup`, `ResetPassword`, `Account/.../UpdatePassword`) to `variant="requirements"`.
+4. **While you're in there — check for a stray `y: -10` translate.** Some forks carry a `motion.div initial={{ y: -10 }} animate={{ y: -10 }}` on the legacy text that leaves the strength text permanently shifted off the baseline. `@clicktap/ui` does **not** have this — its `default` variant positions the strength text with `translate-y-2/4` (intentional layout), not a framer-motion translate. If your fork has the `y: -10`, drop it.
+
+## Why retroactive
+
+A new variant on a shared component can only propagate to forks that know it exists. **Broader pattern:** when adding a variant or non-trivial prop to a `libs/ui` component, write a short migration guide noting (a) what's new, (b) when to reach for it, (c) what to copy if a downstream library forked. The cost is minutes; it closes the silent-drift gap.