@clicktap/ui 0.40.8 → 0.40.9

package/docs/migrations/2026/01/2026-01-14-external-link-detection.md

@@ -0,0 +1,290 @@
+# External Link Detection Migration
+
+**Date:** 2026-01-14
+**Affects:** `@clicktap/ui`, `apps/frontend`
+**Breaking:** No (additive, but requires provider setup for SSR)
+**Classification:** IMPROVEMENT
+
+
+## Dependencies
+
+*None*
+
+## Summary
+
+The `Link` component from `@clicktap/ui` now automatically detects external URLs and applies `target="_blank"` and `rel="noopener noreferrer"` attributes. This requires setting up `LinkProvider` for proper SSR support.
+
+## Changes
+
+1. `Link` component auto-detects external URLs
+2. New `LinkProvider` for SSR base URL configuration
+3. New `isExternalUrl` utility function
+4. Layout files must pass `baseUrl` from host header
+
+## Setup
+
+### 1. Update Layouts to Pass baseUrl
+
+In your Next.js layout files (Server Components), extract the host header and pass it to Providers:
+
+```tsx
+// app/(base)/layout.tsx
+import { headers } from 'next/headers';
+
+export default function Layout({ children }) {
+  const h = headers();
+  const baseUrl = `https://${h.get('host')}`;
+
+  return (
+    <Providers baseUrl={baseUrl}>
+      {children}
+    </Providers>
+  );
+}
+```
+
+```tsx
+// app/(checkout)/layout.tsx
+import { headers } from 'next/headers';
+
+export default function CheckoutLayout({ children }) {
+  const h = headers();
+  const baseUrl = `https://${h.get('host')}`;
+
+  return (
+    <Providers baseUrl={baseUrl}>
+      {children}
+    </Providers>
+  );
+}
+```
+
+### 2. Update Providers Component
+
+Add the `baseUrl` prop and wrap with `LinkProvider`:
+
+```tsx
+// providers/Providers.tsx
+import { LinkProvider } from '@clicktap/ui/components/Link';
+
+type Props = {
+  baseUrl?: string;
+  children: ReactNode;
+  // ... other props
+};
+
+export function Providers({ baseUrl, children, ...props }: Props) {
+  return (
+    <LinkProvider config={{ baseUrl }}>
+      {/* other providers */}
+      {children}
+    </LinkProvider>
+  );
+}
+```
+
+## How It Works
+
+### Detection Logic
+
+- **Relative URLs** (`/path`, `#anchor`) → Internal (no attributes added)
+- **Absolute URLs** → Compared against current host
+  - Same host → Internal
+  - Different host → External (adds `target="_blank"` and `rel="noopener noreferrer"`)
+
+### Host Detection
+
+- **Client-side:** Uses `window.location.host` automatically
+- **Server-side (SSR):** Uses `baseUrl` from `LinkProvider`
+
+This ensures external links are correctly identified during both SSR and client-side rendering.
+
+## Usage
+
+No changes needed in component code. The `Link` component handles detection automatically:
+
+```tsx
+import { Link } from '@clicktap/ui/components/Link';
+
+// Internal - renders normally
+<Link href="/products">Products</Link>
+
+// External - automatically gets target="_blank" rel="noopener noreferrer"
+<Link href="https://google.com">Google</Link>
+
+// Anchor - renders normally
+<Link href="#section">Jump to section</Link>
+```
+
+### Override Behavior
+
+You can override the automatic behavior if needed:
+
+```tsx
+// Force internal link behavior on external URL
+<Link href="https://subdomain.mysite.com" target="_self">
+  Subdomain
+</Link>
+
+// Force external link behavior on internal URL
+<Link href="/download" target="_blank" rel="noopener noreferrer">
+  Download
+</Link>
+```
+
+## Utility Function
+
+The `isExternalUrl` utility is exported for use outside the Link component:
+
+```tsx
+import { isExternalUrl } from '@clicktap/ui/components/Link';
+
+const external = isExternalUrl('https://google.com', 'mysite.com');
+// true
+
+const internal = isExternalUrl('/products', 'mysite.com');
+// false
+```
+
+## Files Changed
+
+- `libs/ui/src/components/Link/Link.tsx` - Auto-detection logic
+- `libs/ui/src/components/Link/LinkContext.tsx` - New provider
+- `libs/ui/src/components/Link/utils.ts` - `isExternalUrl` utility
+- `libs/ui/src/components/Link/index.ts` - Updated exports
+- `apps/frontend/app/(base)/layout.tsx` - Pass baseUrl
+- `apps/frontend/app/(checkout)/layout.tsx` - Pass baseUrl
+- `apps/frontend/providers/Providers.tsx` - Add LinkProvider
+
+## Migration Checklist
+
+1. [ ] Update `libs/ui` to latest version
+2. [ ] Add `baseUrl` prop to Providers component
+3. [ ] Wrap app with `LinkProvider`
+4. [ ] Update all layout files to pass `baseUrl` from host header
+5. [ ] Test external links open in new tab
+6. [ ] Test internal links work normally
+7. [ ] Verify SSR renders correct attributes
+
+---
+
+# LinkAsButton → @clicktap/ui
+
+**Date:** 2026-02-06
+
+## Summary
+
+`LinkAsButton` has been promoted from `apps/frontend/components/LinkAsButton/` into the shared UI library. `Button` also gains `primary`/`secondary`/`tertiary` variant aliases.
+
+## Changes
+
+### `LinkAsButton` promoted to shared UI library
+
+- **Old import:** `import { LinkAsButton } from '../LinkAsButton/LinkAsButton'` (relative, app-level)
+- **New import:** `import { LinkAsButton } from '@clicktap/ui/components/LinkAsButton'`
+- The `[k: string]: any` catch-all type is removed — proper typing via `LinkProps` + `Pick<ButtonProps, 'variant' | 'size'>`
+- Now supports all Button variants (`solid`, `outline`, `ghost`) plus aliases (`primary`, `secondary`, `tertiary`), `size` prop (`sm`, `md`, `lg`), and `isLoading`
+- `apps/frontend/components/LinkAsButton/` has been deleted
+
+### Breaking: `LinkAsButton` default behavior changed
+
+The old local component had no default variant — it rendered as a transparent link with base layout classes. The new shared component defaults to `variant="solid"` and `size="md"`:
+
+| Property | Old (local) | New (`@clicktap/ui`) |
+|----------|-------------|----------------------|
+| `variant` | none (transparent background, transparent border) | `solid` (dark background, white text) |
+| `size` | none (no height constraint) | `md` (`h-10` = 40px height) |
+
+**Impact:** Any `<LinkAsButton>` without an explicit `variant` prop now renders as a dark solid button with a 40px height constraint. This is especially problematic when wrapping images — the image gets constrained inside a styled button container.
+
+**Fix:** Use `variant="ghost"` for transparent links, or use `<Link>` directly when button styling isn't appropriate (e.g., clickable product images):
+
+```tsx
+// Before: image wrapped in default LinkAsButton (was transparent, now solid)
+<LinkAsButton href={url}>
+  <Image ... />
+</LinkAsButton>
+
+// After: use plain Link for image wrappers
+<Link href={url}>
+  <Image ... />
+</Link>
+
+// After: use ghost variant if button semantics are needed
+<LinkAsButton variant="ghost" href={url}>
+  Text link
+</LinkAsButton>
+```
+
+### Button variant aliases
+
+- `Button` now accepts `primary`, `secondary`, and `tertiary` as variant values
+- `primary` → `solid`, `secondary` → `outline`, `tertiary` → `ghost`
+- Existing `solid`, `outline`, `ghost` values continue to work unchanged
+
+---
+
+# Image Component: Remove `width: 'auto'` Auto-Styling
+
+**Date:** 2026-02-08
+**Affects:** `@clicktap/ui` Image component, all consumers
+**Breaking:** Yes - images using `width`/`height` props may render differently
+
+## Summary
+
+The `@clicktap/ui` Image component previously auto-prepended `{ width: 'auto', height: 'auto' }` to the style prop when `width` and `height` props were provided (not `fill`). The `width: 'auto'` has been removed because it overrides the HTML `width` attribute via CSS, causing images to render at their natural intrinsic size instead of the dimensions specified by the props.
+
+## What Changed
+
+```diff
+  const imageStyle = hasSizedProps
+-   ? { width: 'auto' as const, height: 'auto' as const, ...style }
++   ? { height: 'auto' as const, ...style }
+    : style;
+```
+
+**Before:** Images with `width={100} height={100}` and no explicit `style` rendered at their natural resolution (CSS `width: auto` overrode the HTML attribute).
+
+**After:** Images render at the width specified by the `width` prop. `height: 'auto'` preserves the natural aspect ratio.
+
+## Migration
+
+### Review Image usages without explicit `style` prop
+
+Any `<Image>` that passes `width` and `height` props without a `style` override will now render at the `width` prop size instead of the natural image size. In most cases this is the correct behavior.
+
+If the natural-size behavior was intentional, restore it with an explicit style:
+
+```tsx
+<Image width={100} height={100} style={{ width: 'auto', height: 'auto' }} ... />
+```
+
+### Add aspect ratio control where needed
+
+If the displayed image needs a specific aspect ratio that differs from the source image's natural ratio, add CSS classes. Use the actual source image dimensions to determine the ratio (e.g., 960x1200 images → `aspect-[4/5]`):
+
+```tsx
+// Explicit aspect ratio matching source images (e.g., 960x1200 = 4:5)
+<Image
+  width={100} height={125}
+  className="aspect-[4/5] object-cover"
+  style={{ width: '100%', height: 'auto' }}
+/>
+
+// Fill container width, natural aspect ratio (common pattern, no extra classes needed)
+<Image
+  width={400} height={300}
+  style={{ width: '100%', height: 'auto' }}
+/>
+```
+
+### Affected areas to check
+
+Visually inspect any page that displays product images:
+- Cart drawer (mini-cart)
+- Cart page
+- Checkout order summary
+- Checkout success / order confirmation
+- Category listing pages
+- Product collection components
+- Account order history

package/docs/migrations/2026/01/2026-01-14-use-route-hook.md

@@ -0,0 +1,142 @@
+# useRoute Hook Migration
+
+**Date:** 2026-01-14
+**Affects:** `@clicktap/ui`, `apps/frontend`
+**Breaking:** No (additive, but recommended migration)
+**Classification:** IMPROVEMENT
+
+
+## Dependencies
+
+*None*
+
+## Summary
+
+Introduces a centralized route configuration system with the `useRoute` hook for generating URLs. Handles dynamic params, protected route redirects, and login-with-return patterns automatically.
+
+## New Files
+
+- `libs/ui/src/hooks/useRoute/` - Hook and RouteProvider
+- `apps/frontend/config/routes.ts` - Centralized route definitions
+
+## Provider Setup
+
+Add `RouteProviderWithAuth` inside your `AuthProvider`:
+
+```tsx
+import { RouteProvider } from '@clicktap/ui/hooks/useRoute';
+import { useAuth } from '../state/auth/AuthProvider';
+
+function RouteProviderWithAuth({ children }: { children: ReactNode }) {
+  const { isLoggedIn } = useAuth();
+  return <RouteProvider config={{ isLoggedIn }}>{children}</RouteProvider>;
+}
+
+// In provider tree:
+<AuthProvider actor={authActor}>
+  <RouteProviderWithAuth>
+    {children}
+  </RouteProviderWithAuth>
+</AuthProvider>
+```
+
+## Migration Patterns
+
+### Static Routes
+
+```tsx
+// Before
+<Link href="/cart">Cart</Link>
+
+// After
+import { useRoute } from '@clicktap/ui/hooks/useRoute';
+import { Routes } from '../config/routes';
+
+const cartUrl = useRoute(Routes.cart.index);
+<Link href={cartUrl}>Cart</Link>
+```
+
+### Dynamic Routes
+
+```tsx
+// Before
+<Link href={`/account/orders/${orderId}`}>View Order</Link>
+
+// After
+const orderUrl = useRoute(Routes.account.orders.view, { orderId });
+<Link href={orderUrl}>View Order</Link>
+```
+
+### Protected Routes
+
+Protected routes automatically redirect through auth when logged out:
+
+```tsx
+// Before
+const ordersUrl = isLoggedIn
+  ? '/account/orders'
+  : `/account/authenticate?redirect=${encodeURIComponent('/account/orders')}`;
+
+// After
+const ordersUrl = useRoute(Routes.account.orders.index);
+// Logged in:  '/account/orders'
+// Logged out: '/account/authenticate?redirect=%2Faccount%2Forders'
+```
+
+### Login with Return
+
+```tsx
+// Before
+const loginUrl = `/account/authenticate?redirect=${encodeURIComponent(pathname)}`;
+const loginUrl = Routes.account.loginAndReturn(Routes.cart.index);
+
+// After
+const loginUrl = useRoute(Routes.account.authenticate, null, { returnHere: true });
+```
+
+### router.push
+
+```tsx
+// Before
+router.push('/checkout');
+router.push(`/checkout/success/${orderId}`);
+
+// After
+const checkoutUrl = useRoute(Routes.checkout.index);
+router.push(checkoutUrl);
+
+const successUrl = useRoute(Routes.checkout.success, { orderId });
+router.push(successUrl);
+```
+
+## Adding New Routes
+
+Add to `apps/frontend/config/routes.ts`:
+
+```tsx
+const RawRoutes = {
+  // Static route
+  newPage: {
+    path: '/new-page',
+    isProtected: false,
+  },
+
+  // Nested with dynamic param
+  feature: {
+    index: {
+      path: '/feature',
+      isProtected: false,
+    },
+    details: {
+      path: '/feature/:featureId',
+      isProtected: true,
+    },
+  },
+} as const;
+```
+
+## Deprecated
+
+- `Routes.account.loginAndReturn()` - Use `useRoute(route, null, { returnHere: true })`
+- `isProtectedRoute(pathname)` - Use `route.isProtected` directly
+- Direct `.path` access - Use `useRoute()` for all URL generation

package/docs/migrations/2026/01/2026-01-15-input-disable-skeleton.md

@@ -0,0 +1,82 @@
+# Input disableSkeleton Prop
+
+**Date:** 2026-01-15
+**Affects:** `@clicktap/ui`, `apps/frontend`
+**Breaking:** No
+**Classification:** IMPROVEMENT
+
+
+## Dependencies
+
+*None*
+
+## Summary
+
+Added a `disableSkeleton` prop to the Input component that allows consumers to skip the skeleton loading state during hydration. This is useful when you need immediate interactivity (e.g., auto-focus) on page load.
+
+## Background
+
+The Input component uses `useIsClient()` to show a skeleton placeholder during server-side rendering and hydration. This prevents hydration mismatches but causes a brief "flash" where the input appears disabled/skeleton before becoming interactive.
+
+For forms where immediate user interaction is expected (like login/authentication pages), this delay can feel sluggish.
+
+## Changes
+
+### New Prop
+
+```typescript
+interface InputProps extends TextFieldProps {
+  // ... existing props
+
+  /**
+   * When true, renders the input immediately without showing a skeleton during hydration.
+   * Use this when the input doesn't need hydration protection (e.g., simple text inputs
+   * that don't have complex state or need immediate interactivity).
+   */
+  disableSkeleton?: boolean;
+}
+```
+
+## Usage
+
+### Before
+
+```tsx
+<Input
+  name="email"
+  type="email"
+  label="Email"
+  autoFocus  // Won't work - skeleton renders first
+/>
+```
+
+### After
+
+```tsx
+<Input
+  name="email"
+  type="email"
+  label="Email"
+  disableSkeleton  // Renders immediately
+  autoFocus        // Now works as expected
+/>
+```
+
+## When to Use
+
+**Use `disableSkeleton` when:**
+- The input needs to auto-focus on page load
+- Immediate interactivity is important for UX
+- The input is a simple text/email/password field without complex state
+
+**Don't use `disableSkeleton` when:**
+- The input has complex state that could cause hydration mismatches
+- The input relies on client-only data that isn't available during SSR
+- You're unsure - the default skeleton behavior is safer
+
+## Migration Checklist
+
+- [ ] Identify inputs that need immediate interactivity (e.g., login forms)
+- [ ] Add `disableSkeleton` prop to those inputs
+- [ ] Add `autoFocus` if the input should focus on page load
+- [ ] Test that hydration works correctly (no console errors)

package/docs/migrations/2026/02/2026-02-16-env-utils-from-clicktap-ui.md

@@ -0,0 +1,94 @@
+# Environment Utilities from @clicktap/ui
+
+**Date:** 2026-02-16
+**Affects:** All files importing `isDevelopment` / `isProduction` from local `utils/env`
+**Classification:** IMPROVEMENT
+**Breaking:** No
+
+## Dependencies
+
+- [Payment Method Error Handling](../../../../../../apps/frontend/docs/migrations/2026/01/2026-01-14-payment-error-handling.md) — introduced the local `utils/env.ts`
+
+## Summary
+
+The `isDevelopment` and `isProduction` boolean constants have been moved from the frontend's local `utils/env.ts` into `@clicktap/ui/utils/env`, making them available to all apps consuming `@clicktap/ui`. The local file has been deleted.
+
+## Problem
+
+The `isDevelopment` / `isProduction` utility was defined locally in `apps/frontend/utils/env.ts`. Other apps (admin, future storefronts) that need the same pattern would have to duplicate it. Moving it into the shared UI library centralises the definition.
+
+Additionally, the `@clicktap/ui` Vite build was replacing `process.env.NODE_ENV` with `"production"` at library build time, which meant any `NODE_ENV`-based guards inside the UI library (e.g., `console.warn` in the Image component) were dead-code-eliminated before consumers ever saw them. A `define` override in `libs/ui/vite.config.ts` now preserves `process.env.NODE_ENV` so the **consuming app's** bundler handles the replacement.
+
+## Changes
+
+### Vite library build fix
+
+The `@clicktap/ui` Vite config now includes:
+
+```ts
+define: {
+  'process.env.NODE_ENV': 'process.env.NODE_ENV',
+},
+```
+
+This prevents Vite from baking `"production"` into the published bundle, so environment-guarded code (like dev-only `console.warn`) works correctly at the consumer's build time.
+
+**Source:** `libs/ui/vite.config.ts`
+
+### New shared utility
+
+```ts
+// @clicktap/ui/utils/env
+export const isDevelopment = process.env.NODE_ENV === 'development';
+export const isProduction = process.env.NODE_ENV === 'production';
+```
+
+**Source:** `libs/ui/src/utils/env.ts`
+
+### Import change
+
+**Before:**
+```ts
+import { isDevelopment } from '../utils/env';
+import { isDevelopment } from '../../../utils/env';
+import { isDevelopment } from '../../../../../utils/env';
+```
+
+**After:**
+```ts
+import { isDevelopment } from '@clicktap/ui/utils/env';
+```
+
+### Files changed
+
+| File | Change |
+|------|--------|
+| `apps/frontend/utils/env.ts` | Deleted |
+| `providers/CybersourceMicroformV2Provider.tsx` | Import updated |
+| `components/Checkout/ExpressCheckout/PaypalButton.tsx` | Import updated |
+| `components/Checkout/ExpressCheckout/GooglePayButton.tsx` | Import updated |
+| `components/Checkout/ExpressCheckout/ApplePayButton.tsx` | Import updated |
+| `components/Checkout/ExpressCheckout/AmazonPayButton.tsx` | Import updated |
+| `components/Checkout/Step/Review/CheckoutButton/ApplePayCheckoutButton.tsx` | Import updated |
+| `components/Checkout/Step/Review/CheckoutButton/GooglePayCheckoutButton.tsx` | Import updated |
+| `components/Checkout/Step/Review/CheckoutButton/PaypalCheckoutButton.tsx` | Import updated |
+| `components/Checkout/Step/Review/CheckoutButton/AmazonCheckoutButton.tsx` | Import updated |
+| `components/Checkout/Step/Payment/Authorizenet/AuthorizenetPaymentMethod.tsx` | Import updated |
+
+## Migration Steps
+
+1. Update `@clicktap/ui` to the version containing this change.
+2. Find all imports from the local `utils/env`:
+   ```bash
+   grep -r "from.*utils/env" apps/frontend/
+   ```
+3. Replace each import path with `@clicktap/ui/utils/env`.
+4. Delete `apps/frontend/utils/env.ts`.
+5. Run typecheck to confirm no broken imports.
+
+## Migration Checklist
+
+- [ ] Update `@clicktap/ui` to latest
+- [ ] Replace all `utils/env` imports with `@clicktap/ui/utils/env`
+- [ ] Delete `apps/frontend/utils/env.ts`
+- [ ] Run typecheck: `nx run frontend:typecheck`

package/docs/migrations/2026/02/2026-02-17-select-popover-portal-container-restored.md

@@ -0,0 +1,84 @@
+# Select popoverPortalContainer Restored
+
+**Date:** 2026-02-17
+**Affects:** `@clicktap/ui` Select component, any consumer using Select inside Dialog or Modal
+**Classification:** BUGFIX
+**Breaking:** No
+
+## Dependencies
+
+*None*
+
+## Summary
+
+The `popoverPortalContainer` prop was incorrectly removed from the Select component on 2026-01-30 during the react-aria upgrade refactor. This prop controls where the Popover is portalled, which is essential when Select is used inside a Dialog — without it, the Popover renders into `document.body`, causing incorrect width calculation because both Dialog and Popover use react-aria's Modal internals. The prop has been restored using `UNSAFE_PortalProvider` from `react-aria`.
+
+## Problem
+
+The react-aria upgrade (commits `7c27599` and `93ae6b3` on 2026-01-30) removed `popoverPortalContainer` in two steps:
+
+1. Commit `7c27599` correctly migrated from `UNSTABLE_portalContainer` (on Popover) to `UNSAFE_PortalProvider` (wrapper), preserving the feature
+2. Commit `93ae6b3` then removed the feature entirely — deleting the prop from types, removing the `UNSAFE_PortalProvider` import and conditional rendering
+
+The migration guide in [Checkout Fixes — Section 6](../../../../../../apps/frontend/docs/migrations/2026/01/2026-01-14-checkout-fixes.md) was updated to document this removal as intentional. It was not — `popoverPortalContainer` was a working feature, not a deprecated one.
+
+**If your codebase was updated following that migration guide**, you may have removed `popoverPortalContainer` usage from Select instances. Review git history around 2026-01-30 for removals:
+
+```bash
+git log --all --oneline --after="2026-01-28" --before="2026-02-01" -- '*.tsx' '*.ts' | head -20
+git log --all -p --after="2026-01-28" --before="2026-02-01" -S "popoverPortalContainer" -- '*.tsx'
+```
+
+## Changes
+
+| File | What changed |
+|------|-------------|
+| `libs/ui/src/components/Select/Select.tsx` | Restored `UNSAFE_PortalProvider` import from `react-aria`; restored conditional portal wrapping |
+| `libs/ui/src/components/Select/Select.types.ts` | Restored `popoverPortalContainer?: () => HTMLElement | null` prop |
+
+### Restored behavior
+
+When `popoverPortalContainer` is provided, the Popover is wrapped in `UNSAFE_PortalProvider` which controls where the portal renders. When omitted, default react-aria behavior applies (portal to `document.body`).
+
+```tsx
+// Select.tsx — restored conditional
+{popoverPortalContainer ? (
+  <UNSAFE_PortalProvider getContainer={popoverPortalContainer}>
+    {popoverContent}
+  </UNSAFE_PortalProvider>
+) : (
+  popoverContent
+)}
+```
+
+**Source:** `libs/ui/src/components/Select/Select.tsx:209`
+
+## Migration Steps
+
+1. **If you removed `popoverPortalContainer` from Select usage** following the previous migration guide, restore it:
+
+   ```tsx
+   // Restore this where Select is used inside Dialog/Modal
+   <Select popoverPortalContainer={() => dialogRef.current}>
+   ```
+
+2. **Note the type change from the original API** — this was correctly updated during the react-aria upgrade and remains changed:
+
+   ```tsx
+   // Old (pre-upgrade)
+   popoverPortalContainer?: Element;
+
+   // Current (restored)
+   popoverPortalContainer?: () => HTMLElement | null;
+   ```
+
+   The prop now takes a **getter function** instead of a direct element reference.
+
+3. **The `UNSAFE_PortalProvider` import is from `react-aria`**, not `react-aria-components`. If you have custom components that also need portal control, import from the correct package.
+
+## Migration Checklist
+
+- [ ] Search git history for removed `popoverPortalContainer` usage around 2026-01-30
+- [ ] Restore `popoverPortalContainer` on any Select used inside Dialog, Modal, or other overlay contexts
+- [ ] Update prop value from `Element` to `() => HTMLElement | null` getter if restoring pre-upgrade code
+- [ ] Verify Select popover width matches trigger width when rendered inside Dialog