@auto-engineer/component-implementor-react 1.98.0 → 1.99.0

package/inputs/model-c/spec-deltas.json

@@ -0,0 +1,1432 @@
+[
+  {
+    "componentId": "credit-card-input",
+    "componentName": "CreditCardInput",
+    "isNew": true,
+    "atomicType": "molecule",
+    "composes": ["ui-components-input", "ui-components-inputotp"],
+    "specDeltas": {
+      "structure": ["Composes inputs for card number (using InputOTP), expiration, CVV, name."],
+      "rendering": ["Shows validation errors inline for each field."],
+      "interaction": ["Validates card number format on change; calls onChange with full details."],
+      "styling": [
+        "Card number uses InputOTP with `space-x-2` for slots, each slot `h-10 w-10 rounded-md border border-input bg-background text-center text-sm focus:border-accent focus:outline-none`.",
+        "Expiry and CVV inputs use `h-10 rounded-md border border-input bg-background px-3 py-2 text-sm` with `focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2`.",
+        "Name input uses `h-10 w-full rounded-md border border-input bg-background px-3 py-2 text-sm`.",
+        "Invalid fields use `border-destructive focus:border-destructive`.",
+        "Error messages use `text-sm text-destructive mt-1`.",
+        "Labels use `text-sm font-medium leading-none`.",
+        "Group layout uses `grid grid-cols-2 gap-4` for expiry and CVV.",
+        "Focus rings use `focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2`.",
+        "Touch targets use `min-h-11` with `touch-action: manipulation`."
+      ]
+    },
+    "props": [
+      {
+        "name": "value",
+        "type": "{ number: string; expiry: string; cvv: string; name: string }",
+        "required": false,
+        "description": "Current card details.",
+        "category": "state"
+      },
+      {
+        "name": "onChange",
+        "type": "(details: { number: string; expiry: string; cvv: string; name: string }) => void",
+        "required": true,
+        "description": "Callback for changes.",
+        "category": "callback"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "Credit card inputs empty.",
+        "args": {
+          "onChange": "fn()"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "Type card number with userEvent.type(getByLabelText('Card Number'), '4111111111111111');"
+      },
+      {
+        "name": "Invalid",
+        "description": "Showing validation errors.",
+        "args": {
+          "onChange": "fn()"
+        }
+      }
+    ],
+    "dataContract": {
+      "source": "local-state",
+      "fields": ["number", "expiry", "cvv", "name"]
+    }
+  },
+  {
+    "componentId": "listing-map",
+    "componentName": "ListingMap",
+    "isNew": true,
+    "atomicType": "organism",
+    "composes": ["ui-components-card"],
+    "specDeltas": {
+      "structure": ["Renders an interactive map with markers for listing locations, composing Card for container."],
+      "rendering": [
+        "In ready state, displays map with markers based on listings data; shows skeleton in loading state.",
+        "In no-results state, shows empty map with message overlay."
+      ],
+      "interaction": ["Clicking a marker calls onMarkerClick with listing ID, navigating to details."],
+      "styling": [
+        "Map container uses `h-[500px] w-full rounded-lg border border-border shadow-sm`.",
+        "Markers use `bg-primary rounded-full h-4 w-4` with hover wrapped in `@media (hover: hover) and (pointer: fine) { hover:scale-125 }` and `transition: transform 150ms ease`.",
+        "Skeleton uses `h-[500px] w-full bg-muted animate-pulse` with shimmer `background: linear-gradient(90deg, hsl(var(--muted)) 0%, hsl(var(--muted)/0.5) 50%, hsl(var(--muted)) 100%); background-size: 200% 100%; animation: shimmer 1.5s linear infinite`.",
+        "Empty message overlay uses `absolute inset-0 flex items-center justify-center bg-background/80 text-muted-foreground text-lg` with react-spring `useTransition(isEmpty, { from: { opacity: 0 }, enter: { opacity: 1 }, leave: { opacity: 0 }, config: { tension: 400, friction: 26 } })`; respects `useReducedMotion()` by setting `immediate: true`.",
+        "Marker click uses CSS `active:scale-[0.97]` with `transition: transform 100ms ease-out`.",
+        "Focus rings on interactive markers use `focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2`.",
+        "Touch targets for markers use `min-h-11 min-w-11` with `touch-action: manipulation`.",
+        "Map zoom transition uses react-spring `useSpring({ scale: zoomLevel, config: { tension: 170, friction: 26 } })`; respects `useReducedMotion()`.",
+        "Info window uses `bg-background p-2 rounded-md shadow-md` with `z-[500]`.",
+        "Hover on info window wrapped in `@media (hover: hover) and (pointer: fine) { hover:shadow-lg }` with `transition: box-shadow 150ms ease`."
+      ]
+    },
+    "props": [
+      {
+        "name": "listings",
+        "type": "Array<{ id: string; lat: number; lng: number }>",
+        "required": true,
+        "description": "List of listings with coordinates.",
+        "category": "data"
+      },
+      {
+        "name": "isLoading",
+        "type": "boolean",
+        "required": false,
+        "default": "false",
+        "description": "Shows skeleton when true.",
+        "category": "state"
+      },
+      {
+        "name": "onMarkerClick",
+        "type": "(id: string) => void",
+        "required": true,
+        "description": "Callback when marker is clicked.",
+        "category": "callback"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "Map with sample markers.",
+        "args": {
+          "listings": [
+            {
+              "id": "1",
+              "lat": 40.7128,
+              "lng": -74.006
+            }
+          ],
+          "onMarkerClick": "fn()"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "Simulate marker click with userEvent.click(getByRole('button', { name: 'Marker 1' }));"
+      },
+      {
+        "name": "Loading",
+        "description": "Map in loading state.",
+        "args": {
+          "isLoading": true,
+          "onMarkerClick": "fn()"
+        }
+      },
+      {
+        "name": "Empty",
+        "description": "Empty map state.",
+        "args": {
+          "listings": [],
+          "onMarkerClick": "fn()"
+        }
+      }
+    ],
+    "dataContract": {
+      "source": "props",
+      "propsFieldName": "listings",
+      "fields": ["id", "lat", "lng"]
+    }
+  },
+  {
+    "componentId": "price-breakdown",
+    "componentName": "PriceBreakdown",
+    "isNew": true,
+    "atomicType": "organism",
+    "composes": ["ui-components-table"],
+    "specDeltas": {
+      "structure": ["Renders a table-like breakdown of prices, composing Table for display."],
+      "rendering": [
+        "Displays rows for base price, fees, taxes, total using Intl.NumberFormat for currency; uses tabular-nums for alignment."
+      ],
+      "interaction": [],
+      "styling": [
+        "Table uses `w-full caption-bottom text-sm`.",
+        "Row uses `border-b transition-colors hover:bg-muted/50 data-[state=selected]:bg-muted`.",
+        "Cell uses `p-4 align-middle font-variant-numeric: tabular-nums`.",
+        "Label cell uses `text-left font-medium`.",
+        "Amount cell uses `text-right font-semibold`.",
+        "Total row uses `font-bold bg-muted`.",
+        "Currency symbols use `text-muted-foreground`.",
+        "Hover wrapped in `@media (hover: hover) and (pointer: fine) { hover:bg-muted/50 }` with `transition: background-color 150ms ease`.",
+        "No borders use `box-shadow: 0 0 0 1px rgba(0,0,0,0.08)` for separators.",
+        "Text wrap for labels uses `text-balance`."
+      ]
+    },
+    "props": [
+      {
+        "name": "breakdown",
+        "type": "Array<{ label: string; amount: number }>",
+        "required": true,
+        "description": "Price items to display.",
+        "category": "data"
+      },
+      {
+        "name": "currency",
+        "type": "string",
+        "required": false,
+        "default": "'USD'",
+        "description": "Currency code for formatting.",
+        "category": "config"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "Price breakdown with sample data.",
+        "args": {
+          "breakdown": [
+            {
+              "label": "Base",
+              "amount": 100
+            },
+            {
+              "label": "Tax",
+              "amount": 10
+            }
+          ]
+        }
+      }
+    ],
+    "dataContract": {
+      "source": "props",
+      "propsFieldName": "breakdown",
+      "fields": ["label", "amount"]
+    }
+  },
+  {
+    "componentId": "listing-card",
+    "componentName": "ListingCard",
+    "isNew": true,
+    "atomicType": "organism",
+    "composes": ["ui-components-card", "ui-components-badge"],
+    "specDeltas": {
+      "structure": ["Composes Card with image, title, rating Badge, price."],
+      "rendering": ["Displays listing data; shows availability Badge."],
+      "interaction": ["Clicking card navigates to details, calling onClick with listing ID."],
+      "styling": [
+        "Card uses `rounded-lg border bg-card text-card-foreground shadow-sm overflow-hidden`.",
+        "Image uses `aspect-[16/10] w-full object-cover` with skeleton `h-40 w-full bg-muted animate-pulse`.",
+        "Title uses `text-lg font-semibold tracking-tight text-balance`.",
+        "Rating badge uses `variant=\"secondary\"` rendering as `bg-secondary text-secondary-foreground rounded-full px-2 py-0.5 text-xs font-semibold`.",
+        "Price uses `text-lg font-bold font-variant-numeric: tabular-nums`.",
+        "Availability badge uses `variant=\"default\"` for available (`bg-green-500 text-white`), `variant=\"destructive\"` for unavailable (`bg-destructive text-destructive-foreground`).",
+        "Hover effect wrapped in `@media (hover: hover) and (pointer: fine) { hover:shadow-md hover:scale-[1.02] }` with `transition: transform 150ms ease, box-shadow 150ms ease`.",
+        "Focus ring uses `focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2`.",
+        "Touch target uses entire card with `touch-action: manipulation`.",
+        "Content padding uses `p-4`."
+      ]
+    },
+    "props": [
+      {
+        "name": "listing",
+        "type": "{ id: string; photo: string; title: string; rating: number; price: number; available: boolean }",
+        "required": true,
+        "description": "Listing data to display.",
+        "category": "data"
+      },
+      {
+        "name": "onClick",
+        "type": "(id: string) => void",
+        "required": true,
+        "description": "Callback for viewing details.",
+        "category": "callback"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "Listing card with data.",
+        "args": {
+          "listing": {
+            "id": "1",
+            "photo": "img.jpg",
+            "title": "Cozy Apartment",
+            "rating": 4.5,
+            "price": 100,
+            "available": true
+          },
+          "onClick": "fn()"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "Click the card with userEvent.click(getByRole('article'));"
+      },
+      {
+        "name": "Unavailable",
+        "description": "Card showing unavailable.",
+        "args": {
+          "listing": {
+            "id": "1",
+            "photo": "img.jpg",
+            "title": "Cozy Apartment",
+            "rating": 4.5,
+            "price": 100,
+            "available": false
+          },
+          "onClick": "fn()"
+        }
+      }
+    ],
+    "dataContract": {
+      "source": "props",
+      "propsFieldName": "listing",
+      "fields": ["id", "photo", "title", "rating", "price", "available"]
+    }
+  },
+  {
+    "componentId": "ui-components-combobox",
+    "componentName": "Combobox",
+    "isNew": false,
+    "specDeltas": {
+      "structure": [
+        "Renders as a text input with a dropdown list of filtered options, using Button for trigger and InputGroup for composition.",
+        "Supports autocomplete for location search by filtering options based on user input."
+      ],
+      "rendering": [
+        "In ready state, displays placeholder text and dropdown trigger.",
+        "When focused or triggered, shows dropdown with filtered options; if no matches, shows emptyMessage.",
+        "Selected value displays in the input field."
+      ],
+      "interaction": [
+        "Typing in the input filters options case-insensitively, trimming whitespace, and calls onValueChange with the selected value on selection.",
+        "Arrow keys navigate through visible options; Enter selects the highlighted option.",
+        "Escape closes the dropdown without selection."
+      ],
+      "styling": [
+        "Combobox input uses `h-10 w-full rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50`.",
+        "Dropdown content uses `mt-1 w-full rounded-md border border-border bg-popover p-1 shadow-md` with react-spring `useTransition(isOpen, { from: { opacity: 0, scale: 0.95 }, enter: { opacity: 1, scale: 1 }, leave: { opacity: 0, scale: 0.95 }, config: { tension: 400, friction: 22 } })`; respects `useReducedMotion()` by setting `immediate: true` when motion is reduced.",
+        "Option items use `flex cursor-pointer items-center rounded-sm px-2 py-1.5 text-sm outline-none focus:bg-accent focus:text-accent-foreground data-[disabled=true]:pointer-events-none data-[disabled=true]:opacity-50` with hover wrapped in `@media (hover: hover) and (pointer: fine) { hover:bg-accent hover:text-accent-foreground }` and `transition: background-color 150ms ease`.",
+        "Selected option uses `bg-accent text-accent-foreground`.",
+        "Trigger button uses `variant=\"ghost\"` rendering as `bg-transparent hover:bg-accent hover:text-accent-foreground` with `min-h-11 min-w-11 touch-action: manipulation`.",
+        "Empty message uses `p-4 text-center text-sm text-muted-foreground`.",
+        "Clear button uses `variant=\"ghost\"` with CSS `active:scale-[0.97]` and `transition: transform 100ms ease-out`.",
+        "Focus rings use `focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2`.",
+        "Touch targets for options use `min-h-11` with `touch-action: manipulation`."
+      ]
+    },
+    "props": [
+      {
+        "name": "options",
+        "type": "Array<{ value: string; label: string }>",
+        "required": true,
+        "description": "List of selectable options for autocomplete.",
+        "category": "data"
+      },
+      {
+        "name": "value",
+        "type": "string",
+        "required": false,
+        "default": "''",
+        "description": "Currently selected value.",
+        "category": "state"
+      },
+      {
+        "name": "onValueChange",
+        "type": "(value: string) => void",
+        "required": true,
+        "description": "Callback fired when a new value is selected.",
+        "category": "callback"
+      },
+      {
+        "name": "placeholder",
+        "type": "string",
+        "required": false,
+        "default": "'Select...'",
+        "description": "Placeholder text when no value is selected.",
+        "category": "config"
+      },
+      {
+        "name": "emptyMessage",
+        "type": "string",
+        "required": false,
+        "default": "'No options found.'",
+        "description": "Message shown when no options match the filter.",
+        "category": "config"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "Combobox in ready state with options.",
+        "args": {
+          "options": [
+            {
+              "value": "nyc",
+              "label": "New York City"
+            },
+            {
+              "value": "la",
+              "label": "Los Angeles"
+            }
+          ],
+          "placeholder": "Search location",
+          "onValueChange": "fn()"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "1. Focus the input with userEvent.click(getByRole('combobox')); 2. Type 'n' with userEvent.type(getByRole('combobox'), 'n'); 3. Await waitFor(() => expect(getByText('New York City')).toBeVisible()); 4. Click the option with userEvent.click(getByText('New York City')); 5. Expect the input value to be 'nyc'."
+      },
+      {
+        "name": "NoResults",
+        "description": "Combobox showing no results message.",
+        "args": {
+          "options": [
+            {
+              "value": "nyc",
+              "label": "New York City"
+            }
+          ],
+          "placeholder": "Search location",
+          "emptyMessage": "No locations found.",
+          "onValueChange": "fn()"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "1. Focus the input with userEvent.click(getByRole('combobox')); 2. Type 'xyz' with userEvent.type(getByRole('combobox'), 'xyz'); 3. Await waitFor(() => expect(getByText('No locations found.')).toBeVisible());"
+      }
+    ],
+    "dataContract": {
+      "source": "props",
+      "propsFieldName": "options",
+      "fields": ["value", "label"]
+    }
+  },
+  {
+    "componentId": "ui-components-calendar",
+    "componentName": "Calendar",
+    "isNew": false,
+    "specDeltas": {
+      "structure": [
+        "Renders a calendar grid with selectable dates, supporting range mode for check-in/check-out selection."
+      ],
+      "rendering": [
+        "In ready state, displays current month with selectable dates; disables past dates and unavailable dates based on disabled prop.",
+        "Shows selected range with from and to dates highlighted; intermediate dates in range get accent styling.",
+        "Disables dates before today by default."
+      ],
+      "interaction": [
+        "Clicking a date selects it in single mode or extends the range in range mode; calls onSelect with the selected date or range.",
+        "Validates that no unavailable dates exist within the selected range, checking every day using eachDayOfInterval.",
+        "Arrow keys navigate between days; Enter selects the focused day."
+      ],
+      "styling": [
+        "Calendar grid uses `w-full border-collapse space-y-1`.",
+        "Day cells use `h-9 w-9 text-center text-sm p-0 relative focus-within:relative focus-within:z-20` with hover wrapped in `@media (hover: hover) and (pointer: fine) { hover:bg-accent }` and `transition: background-color 150ms ease`.",
+        "Selected day uses `bg-primary text-primary-foreground` with react-spring `useTransition(selected, { opacity: 0 to 1, config: { tension: 300, friction: 22 } })`; respects `useReducedMotion()` by setting `immediate: true`.",
+        "Disabled days use `opacity-50 cursor-not-allowed`.",
+        "Range in-between days use `bg-accent text-accent-foreground`.",
+        "Navigation buttons use `variant=\"ghost\"` rendering as `bg-transparent hover:bg-accent hover:text-accent-foreground` with `min-h-11 min-w-11 touch-action: manipulation` and CSS `active:scale-[0.97]` with `transition: transform 100ms ease-out`.",
+        "Today indicator uses `ring-1 ring-accent`.",
+        "Outside days use `text-muted-foreground`.",
+        "Focus rings on days use `focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2`.",
+        "Numbers in cells use `font-variant-numeric: tabular-nums`.",
+        "Month transition uses react-spring `useTransition(month, { from: { opacity: 0 }, enter: { opacity: 1 }, leave: { opacity: 0 }, config: { tension: 400, friction: 26 } })`; respects `useReducedMotion()` by setting `immediate: true`."
+      ]
+    },
+    "props": [
+      {
+        "name": "mode",
+        "type": "'single' | 'multiple' | 'range'",
+        "required": true,
+        "description": "Selection mode for dates.",
+        "category": "config"
+      },
+      {
+        "name": "selected",
+        "type": "Date | Date[] | { from: Date; to?: Date }",
+        "required": false,
+        "description": "Currently selected date(s) or range.",
+        "category": "state"
+      },
+      {
+        "name": "onSelect",
+        "type": "(date: Date | Date[] | { from: Date; to: Date }) => void",
+        "required": true,
+        "description": "Callback fired when a date is selected.",
+        "category": "callback"
+      },
+      {
+        "name": "disabled",
+        "type": "Date[] | ((date: Date) => boolean)",
+        "required": false,
+        "description": "Dates or matcher to disable (e.g., past or unavailable).",
+        "category": "config"
+      },
+      {
+        "name": "size",
+        "type": "\"sm\" | \"md\" | \"lg\"",
+        "required": false,
+        "default": "\"md\"",
+        "description": "Controls calendar size variants.",
+        "category": "visual"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "Calendar in range mode with some disabled dates.",
+        "args": {
+          "mode": "range",
+          "disabled": "[new Date('2023-01-01'), new Date('2023-01-02')]",
+          "onSelect": "fn()",
+          "size": "md"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "1. Click a start date with userEvent.click(getByText('15')); 2. Click an end date with userEvent.click(getByText('20')); 3. Await waitFor(() => expect(getByText('15')).toHaveClass('selected') && expect(getByText('20')).toHaveClass('selected'));"
+      },
+      {
+        "name": "DisabledDates",
+        "description": "Calendar showing disabled past dates.",
+        "args": {
+          "mode": "range",
+          "disabled": "((date) => date < new Date())",
+          "onSelect": "fn()",
+          "size": "md"
+        }
+      }
+    ],
+    "dataContract": {
+      "source": "props",
+      "propsFieldName": "disabled",
+      "fields": ["date"]
+    }
+  },
+  {
+    "componentId": "ui-components-select",
+    "componentName": "Select",
+    "isNew": false,
+    "specDeltas": {
+      "structure": ["Renders a dropdown select for guest count or similar selections."],
+      "rendering": ["In ready state, shows placeholder or selected value; dropdown lists options."],
+      "interaction": ["Selecting an option calls onValueChange with the selected value."],
+      "styling": [
+        "Select trigger uses `flex h-10 w-full items-center justify-between rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background placeholder:text-muted-foreground focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50` with `min-h-11 touch-action: manipulation`.",
+        "Select content uses `w-full rounded-md border bg-popover p-1 text-popover-foreground shadow-md` with react-spring `useTransition(isOpen, { from: { opacity: 0, scale: 0.95 }, enter: { opacity: 1, scale: 1 }, leave: { opacity: 0, scale: 0.95 }, config: { tension: 400, friction: 22 } })`; respects `useReducedMotion()` by setting `immediate: true`.",
+        "Select item uses `relative flex w-full cursor-default select-none items-center rounded-sm py-1.5 px-2 text-sm outline-none focus:bg-accent focus:text-accent-foreground data-[disabled=true]:pointer-events-none data-[disabled=true]:opacity-50` with hover wrapped in `@media (hover: hover) and (pointer: fine) { hover:bg-accent hover:text-accent-foreground }` and `transition: background-color 150ms ease`.",
+        "Selected item indicator uses `absolute right-2 flex h-3.5 w-3.5 items-center justify-center text-primary`.",
+        "Placeholder uses `text-muted-foreground`.",
+        "Focus rings use `focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2`."
+      ]
+    },
+    "props": [
+      {
+        "name": "value",
+        "type": "string",
+        "required": false,
+        "description": "Currently selected value.",
+        "category": "state"
+      },
+      {
+        "name": "onValueChange",
+        "type": "(value: string) => void",
+        "required": true,
+        "description": "Callback fired when value changes.",
+        "category": "callback"
+      },
+      {
+        "name": "placeholder",
+        "type": "string",
+        "required": false,
+        "default": "'Select...'",
+        "description": "Placeholder text.",
+        "category": "config"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "Select with guest count options.",
+        "args": {
+          "placeholder": "Guests",
+          "onValueChange": "fn()"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "1. Click the trigger with userEvent.click(getByRole('button')); 2. Click an option with userEvent.click(getByText('2 guests')); 3. Expect the value to be '2'."
+      }
+    ],
+    "dataContract": {
+      "source": "props",
+      "propsFieldName": "options",
+      "fields": ["value", "label"]
+    }
+  },
+  {
+    "componentId": "ui-components-form",
+    "componentName": "Form",
+    "isNew": false,
+    "specDeltas": {
+      "structure": ["Wraps form fields for booking and payment inputs, using react-hook-form integration."],
+      "rendering": [
+        "In editing-invalid state, shows FormMessage with error text near invalid fields; hides submit button or disables it.",
+        "In ready state, shows all fields without errors."
+      ],
+      "interaction": [
+        "On submit, validates fields and calls onSubmit if valid; transitions to submitting state.",
+        "Real-time validation on blur for each field, showing aria-invalid and error message."
+      ],
+      "styling": [
+        "FormItem uses `flex flex-col space-y-1.5`.",
+        "FormLabel uses `text-sm font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70` with `text-destructive` when invalid.",
+        "FormControl uses `focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2` with `border-destructive` when invalid.",
+        "FormMessage uses `text-sm text-destructive` for errors, visible only when invalid.",
+        "FormDescription uses `text-sm text-muted-foreground`.",
+        "Submit button uses `variant=\"default\"` rendering as `bg-primary text-primary-foreground hover:bg-primary/90` with `min-h-11 touch-action: manipulation` and CSS `active:scale-[0.97]` with `transition: transform 100ms ease-out`.",
+        "Disabled state uses `opacity-50 cursor-not-allowed`.",
+        "Hover on labels wrapped in `@media (hover: hover) and (pointer: fine) { hover:text-accent-foreground }` with `transition: color 150ms ease`."
+      ]
+    },
+    "props": [
+      {
+        "name": "form",
+        "type": "UseFormReturn",
+        "required": true,
+        "description": "react-hook-form instance.",
+        "category": "config"
+      },
+      {
+        "name": "onSubmit",
+        "type": "(data: FormData) => void",
+        "required": true,
+        "description": "Callback on valid form submission.",
+        "category": "callback"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "Form in ready state.",
+        "args": {
+          "onSubmit": "fn()"
+        }
+      },
+      {
+        "name": "Invalid",
+        "description": "Form showing validation errors.",
+        "args": {
+          "onSubmit": "fn()"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "1. Type invalid data in input with userEvent.type(getByLabelText('Card Number'), 'invalid'); 2. Click submit with userEvent.click(getByRole('button', { name: 'Pay' })); 3. Await waitFor(() => expect(getByText('Invalid card number')).toBeVisible());"
+      }
+    ],
+    "dataContract": {
+      "source": "local-state",
+      "fields": ["fieldName", "value", "error"]
+    }
+  },
+  {
+    "componentId": "ui-components-alert",
+    "componentName": "Alert",
+    "isNew": false,
+    "specDeltas": {
+      "structure": ["Renders as a banner for feedback like no-results or errors."],
+      "rendering": [
+        "In no-results state, shows info variant with message 'No listings match your criteria.'; hides results-list content.",
+        "In error state, shows destructive variant with message and retry button; hides other regions."
+      ],
+      "interaction": ["Clicking retry in error banner calls onRetry, transitioning to loading state."],
+      "styling": [
+        "Alert root uses `relative w-full rounded-lg border p-4` with `border-border text-foreground` for default, `border-destructive text-destructive` for destructive.",
+        "AlertTitle uses `mb-1 font-medium`.",
+        "AlertDescription uses `text-sm`.",
+        "Retry button in destructive variant uses `variant=\"destructive\"` rendering as `bg-destructive text-destructive-foreground hover:bg-destructive/90` with `min-h-11 touch-action: manipulation` and CSS `active:scale-[0.97]` with `transition: transform 100ms ease-out`.",
+        "Icon uses `h-4 w-4 text-muted-foreground`.",
+        "Hover on retry button wrapped in `@media (hover: hover) and (pointer: fine) { hover:bg-destructive/90 }` with `transition: background-color 150ms ease`."
+      ]
+    },
+    "props": [
+      {
+        "name": "variant",
+        "type": "'default' | 'destructive'",
+        "required": false,
+        "default": "'default'",
+        "description": "Visual variant for severity.",
+        "category": "config"
+      },
+      {
+        "name": "onRetry",
+        "type": "() => void",
+        "required": false,
+        "description": "Callback for retry action in error state.",
+        "category": "callback"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "Info alert for no results.",
+        "args": {
+          "variant": "default"
+        }
+      },
+      {
+        "name": "Error",
+        "description": "Destructive alert with retry.",
+        "args": {
+          "variant": "destructive",
+          "onRetry": "fn()"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "Click the retry button with userEvent.click(getByRole('button', { name: 'Retry' }));"
+      }
+    ],
+    "dataContract": {
+      "source": "props",
+      "propsFieldName": "message",
+      "fields": ["text"]
+    }
+  },
+  {
+    "componentId": "ui-components-carousel",
+    "componentName": "Carousel",
+    "isNew": false,
+    "specDeltas": {
+      "structure": ["Renders listing photos in a slideshow."],
+      "rendering": ["Displays images in CarouselItem slides."],
+      "interaction": ["Swipe or arrow buttons navigate slides."],
+      "styling": [
+        "Carousel content uses `relative overflow-hidden` with react-spring `useTransition(activeIndex, { from: { transform: 'translateX(100%)' }, enter: { transform: 'translateX(0%)' }, leave: { transform: 'translateX(-100%)' }, config: { tension: 170, friction: 26 } })` for horizontal slides; respects `useReducedMotion()` by setting `immediate: true`.",
+        "Carousel item uses `flex-shrink-0 w-full` with `aspect-ratio` for image containers to prevent layout shift.",
+        "Previous/Next buttons use `variant=\"outline\"` rendering as `border border-input bg-background hover:bg-accent hover:text-accent-foreground` with `min-h-11 min-w-11 touch-action: manipulation` positioned at edges with `z-[500]`.",
+        "Image uses `w-full h-auto object-cover` with skeleton `h-64 w-full bg-muted animate-pulse` for loading.",
+        "Hover on buttons wrapped in `@media (hover: hover) and (pointer: fine) { hover:bg-accent }` with `transition: background-color 150ms ease`.",
+        "Focus rings on buttons use `focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2`.",
+        "Disabled buttons use `opacity-50 cursor-not-allowed`."
+      ]
+    },
+    "props": [
+      {
+        "name": "images",
+        "type": "Array<{ src: string; alt: string }>",
+        "required": true,
+        "description": "List of images to display.",
+        "category": "data"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "Carousel with sample images.",
+        "args": {
+          "images": [
+            {
+              "src": "img1.jpg",
+              "alt": "Listing photo 1"
+            },
+            {
+              "src": "img2.jpg",
+              "alt": "Listing photo 2"
+            }
+          ]
+        },
+        "needsPlayFunction": true,
+        "playDescription": "Click next button with userEvent.click(getByRole('button', { name: 'Next' })); await waitFor(() => expect(getByAltText('Listing photo 2')).toBeVisible());"
+      }
+    ],
+    "dataContract": {
+      "source": "props",
+      "propsFieldName": "images",
+      "fields": ["src", "alt"]
+    }
+  },
+  {
+    "componentId": "ui-components-alertdialog",
+    "componentName": "AlertDialog",
+    "isNew": false,
+    "specDeltas": {
+      "structure": ["Used for unsaved changes confirmation before navigating away."],
+      "rendering": ["Shows when attempting to leave with unsaved changes, displaying warning message."],
+      "interaction": ["Confirm button proceeds with navigation; cancel closes dialog."],
+      "styling": [
+        "AlertDialog content uses `z-[400] fixed top-[50%] left-[50%] max-h-[85vh] w-[90vw] max-w-[450px] translate-x-[-50%] translate-y-[-50%] rounded-md bg-background p-6 shadow-lg` with react-spring `useTransition(isOpen, { from: { opacity: 0, scale: 0.95 }, enter: { opacity: 1, scale: 1 }, leave: { opacity: 0, scale: 0.95 }, config: { tension: 300, friction: 22 } })`; respects `useReducedMotion()` by setting `immediate: true`.",
+        "Overlay uses `z-[300] fixed inset-0 bg-black/80` with same react-spring config as content for paired animation.",
+        "AlertDialogTitle uses `text-lg font-semibold`.",
+        "AlertDialogDescription uses `mt-2 mb-4 text-sm text-muted-foreground`.",
+        "Confirm button uses `variant=\"default\"` rendering as `bg-primary text-primary-foreground hover:bg-primary/90` with `min-h-11 touch-action: manipulation` and CSS `active:scale-[0.97]` with `transition: transform 100ms ease-out`.",
+        "Cancel button uses `variant=\"ghost\"` rendering as `bg-transparent hover:bg-accent hover:text-accent-foreground`.",
+        "Hover on buttons wrapped in `@media (hover: hover) and (pointer: fine) { hover:bg-primary/90 }` for confirm, with `transition: background-color 150ms ease`."
+      ]
+    },
+    "props": [
+      {
+        "name": "open",
+        "type": "boolean",
+        "required": true,
+        "description": "Controls dialog visibility.",
+        "category": "state"
+      },
+      {
+        "name": "onOpenChange",
+        "type": "(open: boolean) => void",
+        "required": true,
+        "description": "Callback for open state change.",
+        "category": "callback"
+      },
+      {
+        "name": "onConfirm",
+        "type": "() => void",
+        "required": true,
+        "description": "Callback to proceed with action.",
+        "category": "callback"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "Confirmation dialog open.",
+        "args": {
+          "open": true,
+          "onOpenChange": "fn()",
+          "onConfirm": "fn()"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "Click confirm with userEvent.click(getByRole('button', { name: 'Confirm' }));"
+      }
+    ],
+    "dataContract": {
+      "source": "local-state",
+      "fields": ["message"]
+    }
+  },
+  {
+    "componentId": "ui-components-card",
+    "componentName": "Card",
+    "isNew": false,
+    "specDeltas": {
+      "structure": ["Used as base for listing previews in results grid."],
+      "rendering": ["Displays photo, title, price in CardContent."],
+      "interaction": [],
+      "styling": [
+        "Card root uses `rounded-lg border bg-card text-card-foreground shadow-sm`.",
+        "CardHeader uses `flex flex-col space-y-1.5 p-6`.",
+        "CardTitle uses `text-2xl font-semibold leading-none tracking-tight text-balance`.",
+        "CardDescription uses `text-sm text-muted-foreground`.",
+        "CardContent uses `p-6 pt-0`.",
+        "Hover effect wrapped in `@media (hover: hover) and (pointer: fine) { hover:shadow-md }` with `transition: box-shadow 150ms ease`."
+      ]
+    },
+    "props": [
+      {
+        "name": "onClick",
+        "type": "() => void",
+        "required": false,
+        "description": "Callback for card click to view details.",
+        "category": "callback"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "Card with sample listing data.",
+        "args": {
+          "onClick": "fn()"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "Click the card with userEvent.click(getByRole('article'));"
+      }
+    ],
+    "dataContract": {
+      "source": "props",
+      "propsFieldName": "listing",
+      "fields": ["photo", "title", "price"]
+    }
+  },
+  {
+    "componentId": "ui-components-pagination",
+    "componentName": "Pagination",
+    "isNew": false,
+    "specDeltas": {
+      "structure": ["Renders pagination controls for results list."],
+      "rendering": ["Shows page links, previous/next based on current page and total."],
+      "interaction": ["Clicking page link calls onPageChange with new page."],
+      "styling": [
+        "Pagination content uses `flex items-center gap-1`.",
+        "Pagination item uses `relative inline-flex items-center`.",
+        "Pagination link uses `variant=\"ghost\"` rendering as `bg-transparent hover:bg-accent hover:text-accent-foreground h-10 px-4` with `min-h-11 min-w-11 touch-action: manipulation` and `transition: background-color 150ms ease`.",
+        "Active page uses `border border-input bg-background`.",
+        "Previous/Next use `variant=\"ghost\"` with icons, disabled `opacity-50 cursor-not-allowed`.",
+        "Ellipsis uses `h-10 w-10 flex items-center justify-center text-muted-foreground`.",
+        "Hover wrapped in `@media (hover: hover) and (pointer: fine) { hover:bg-accent }`.",
+        "Focus rings use `focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2`."
+      ]
+    },
+    "props": [
+      {
+        "name": "currentPage",
+        "type": "number",
+        "required": true,
+        "description": "Current active page.",
+        "category": "state"
+      },
+      {
+        "name": "totalPages",
+        "type": "number",
+        "required": true,
+        "description": "Total number of pages.",
+        "category": "data"
+      },
+      {
+        "name": "onPageChange",
+        "type": "(page: number) => void",
+        "required": true,
+        "description": "Callback for page change.",
+        "category": "callback"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "Pagination with 5 pages, current 2.",
+        "args": {
+          "currentPage": 2,
+          "totalPages": 5,
+          "onPageChange": "fn()"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "Click next with userEvent.click(getByRole('button', { name: 'Next' }));"
+      }
+    ],
+    "dataContract": {
+      "source": "props",
+      "propsFieldName": "totalPages",
+      "fields": ["pageNumber"]
+    }
+  },
+  {
+    "componentId": "ui-components-spinner",
+    "componentName": "Spinner",
+    "isNew": false,
+    "specDeltas": {
+      "structure": [],
+      "rendering": ["Shows in loading and submitting states as progress indicator."],
+      "interaction": [],
+      "styling": [
+        "Spinner uses `h-8 w-8 animate-spin text-muted-foreground`.",
+        "Container uses `flex items-center justify-center h-full`.",
+        "Respects prefers-reduced-motion with `@media (prefers-reduced-motion: reduce) { animation: none }`."
+      ]
+    },
+    "props": [
+      {
+        "name": "isLoading",
+        "type": "boolean",
+        "required": false,
+        "default": "false",
+        "description": "Controls visibility for loading state.",
+        "category": "state"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "Spinner in loading state.",
+        "args": {
+          "isLoading": true
+        }
+      }
+    ],
+    "dataContract": {
+      "source": "local-state",
+      "fields": []
+    }
+  },
+  {
+    "componentId": "search-browse-listings-page",
+    "componentName": "SearchBrowseListingsPage",
+    "isNew": true,
+    "atomicType": "page",
+    "composes": [
+      "ui-components-combobox",
+      "ui-components-calendar",
+      "ui-components-select",
+      "ui-components-pagination",
+      "listing-map",
+      "listing-card",
+      "ui-components-spinner",
+      "ui-components-alert"
+    ],
+    "specDeltas": {
+      "structure": [
+        "<main> with search-filters in header section, results-list in main content as grid of ListingCard, map-view in aside."
+      ],
+      "rendering": [
+        "In loading state, shows Spinner in results-list and map-view regions; hides no-results feedback.",
+        "In ready state, shows search-filters, results-list with ListingCard grid, map-view; hides Spinner.",
+        "In no-results state, shows search-filters, empty state in results-list with Alert info; hides map-view.",
+        "In error state, shows search-filters, Alert destructive in results-list with retry; hides map-view and results."
+      ],
+      "interaction": [
+        "Submitting search calls onSearchSubmit, transitioning to loading; derives from 'Search' label + transitionTo.",
+        "Clearing filters calls onClearFilters, transitioning to loading.",
+        "Viewing listing navigates to select-dates-book."
+      ],
+      "styling": [
+        "Main layout uses `flex flex-col min-h-screen bg-background`.",
+        "Search filters header uses `sticky top-0 z-[200] bg-background border-b border-border p-4 shadow-sm`.",
+        "Results grid uses `grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6 p-6`.",
+        "Map aside uses `sticky top-20 h-[calc(100vh-5rem)] w-full lg:w-1/3 border-l border-border` with `z-[100]`.",
+        "Page enter uses react-spring `useSpring({ opacity: isReady ? 1 : 0, config: { tension: 400, friction: 26 } })`; respects `useReducedMotion()` by setting `immediate: true`.",
+        "Loading skeleton for grid uses `h-64 w-full bg-muted animate-pulse` with explicit dimensions matching ListingCard.",
+        "No-results alert centered with `m-auto max-w-md`.",
+        "Error alert uses `m-6`.",
+        "Search button uses `variant=\"default\"` with `min-h-11`.",
+        "Clear button uses `variant=\"ghost\"`.",
+        "Hover on cards wrapped in `@media (hover: hover) and (pointer: fine) { hover:shadow-md }`.",
+        "Focus rings on inputs use `focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2`.",
+        "Pagination at bottom uses `flex justify-center p-6 border-t border-border`.",
+        "Touch targets for filters use `min-h-11`."
+      ]
+    },
+    "props": [
+      {
+        "name": "isLoading",
+        "type": "boolean",
+        "required": false,
+        "default": "false",
+        "description": "Controls loading state.",
+        "category": "state"
+      },
+      {
+        "name": "error",
+        "type": "string | null",
+        "required": false,
+        "default": "null",
+        "description": "Error message for error state.",
+        "category": "state"
+      },
+      {
+        "name": "onSearchSubmit",
+        "type": "(params: { location: string; dates: { from: Date; to: Date }; guests: number }) => void",
+        "required": true,
+        "description": "Callback for search submission.",
+        "category": "callback"
+      },
+      {
+        "name": "onClearFilters",
+        "type": "() => void",
+        "required": true,
+        "description": "Callback to clear filters.",
+        "category": "callback"
+      },
+      {
+        "name": "onRetry",
+        "type": "() => void",
+        "required": false,
+        "description": "Retry callback in error state.",
+        "category": "callback"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "Page in ready state with results.",
+        "args": {
+          "isLoading": false,
+          "error": null,
+          "onSearchSubmit": "fn()",
+          "onClearFilters": "fn()",
+          "onRetry": "fn()"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "1. Type location with userEvent.type(getByPlaceholderText('Search location'), 'nyc'); 2. Click search with userEvent.click(getByRole('button', { name: 'Search' }));"
+      },
+      {
+        "name": "Loading",
+        "description": "Page in loading state.",
+        "args": {
+          "isLoading": true,
+          "error": null,
+          "onSearchSubmit": "fn()",
+          "onClearFilters": "fn()",
+          "onRetry": "fn()"
+        }
+      },
+      {
+        "name": "NoResults",
+        "description": "Page in no-results state.",
+        "args": {
+          "isLoading": false,
+          "error": null,
+          "onSearchSubmit": "fn()",
+          "onClearFilters": "fn()",
+          "onRetry": "fn()"
+        }
+      },
+      {
+        "name": "Error",
+        "description": "Page in error state with retry.",
+        "args": {
+          "isLoading": false,
+          "error": "Failed to load listings.",
+          "onSearchSubmit": "fn()",
+          "onClearFilters": "fn()",
+          "onRetry": "fn()"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "Click retry with userEvent.click(getByRole('button', { name: 'Retry' }));"
+      }
+    ],
+    "dataContract": {
+      "source": "graphql-query",
+      "operationName": "SearchListings",
+      "fields": [
+        "listings.id",
+        "listings.title",
+        "listings.photo",
+        "listings.price",
+        "listings.location",
+        "listings.availableDates"
+      ]
+    }
+  },
+  {
+    "componentId": "select-dates-book-page",
+    "componentName": "SelectDatesBookPage",
+    "isNew": true,
+    "atomicType": "page",
+    "composes": [
+      "ui-components-calendar",
+      "ui-components-select",
+      "ui-components-carousel",
+      "price-breakdown",
+      "ui-components-form",
+      "ui-components-alert",
+      "ui-components-spinner",
+      "ui-components-alertdialog"
+    ],
+    "specDeltas": {
+      "structure": ["<main> with listing-detail in article, booking-form in section, booking-summary in aside."],
+      "rendering": [
+        "In loading state, shows Spinner in all regions; hides feedback.",
+        "In ready state, shows all regions without errors.",
+        "In editing-invalid state, shows all regions with inline validation errors in booking-form.",
+        "In submitting state, shows listing-detail and booking-summary; shows progress in booking-form region; hides booking-form inputs.",
+        "In error state, shows listing-detail and booking-form; shows Alert destructive with retry in booking-summary; hides booking-summary content."
+      ],
+      "interaction": [
+        "Submitting booking validates guards (no past dates, no overlaps), calls onSubmitBooking if valid, transitioning to submitting; on success navigates to process-payment.",
+        "Canceling navigates back to search-browse-listings.",
+        "Unsaved changes triggers AlertDialog confirmation before navigating."
+      ],
+      "styling": [
+        "Main layout uses `flex flex-col md:flex-row min-h-screen bg-background gap-6 p-6`.",
+        "Listing detail article uses `flex-1`.",
+        "Booking form section uses `w-full md:w-96 sticky top-20 bg-background border border-border rounded-lg p-6 shadow-sm` with `z-[200]`.",
+        "Booking summary aside uses `w-full md:w-80`.",
+        "Page enter uses react-spring `useSpring({ opacity: isReady ? 1 : 0, config: { tension: 400, friction: 26 } })`; respects `useReducedMotion()`.",
+        "Submitting progress uses `h-2 bg-secondary rounded-full` with react-spring `useSpring({ width: '0%' to '100%', config: { tension: 120, friction: 14 } })`; immediate on reduced motion.",
+        "Error alert uses `mb-4`.",
+        "Back button uses `variant=\"ghost\"` with `mb-4`.",
+        "Submit button uses `variant=\"default\"` with `w-full min-h-11`.",
+        "Cancel button uses `variant=\"ghost\"` with `w-full`.",
+        "Hover on buttons wrapped in `@media (hover: hover) and (pointer: fine) { hover:bg-primary/90 }`.",
+        "Focus rings on form elements use `focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2`.",
+        "Image gallery uses `mb-6`.",
+        "Price numbers use `font-variant-numeric: tabular-nums`.",
+        "Touch targets for selects use `min-h-11`."
+      ]
+    },
+    "props": [
+      {
+        "name": "isLoading",
+        "type": "boolean",
+        "required": false,
+        "default": "false",
+        "description": "Controls loading state.",
+        "category": "state"
+      },
+      {
+        "name": "isSubmitting",
+        "type": "boolean",
+        "required": false,
+        "default": "false",
+        "description": "Controls submitting state.",
+        "category": "state"
+      },
+      {
+        "name": "error",
+        "type": "string | null",
+        "required": false,
+        "default": "null",
+        "description": "Error message for error state.",
+        "category": "state"
+      },
+      {
+        "name": "onSubmitBooking",
+        "type": "(data: { dates: { from: Date; to: Date }; guests: number }) => void",
+        "required": true,
+        "description": "Callback for booking submission.",
+        "category": "callback"
+      },
+      {
+        "name": "onCancel",
+        "type": "() => void",
+        "required": true,
+        "description": "Callback for canceling.",
+        "category": "callback"
+      },
+      {
+        "name": "onRetry",
+        "type": "() => void",
+        "required": false,
+        "description": "Retry callback in error state.",
+        "category": "callback"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "Page in ready state.",
+        "args": {
+          "isLoading": false,
+          "isSubmitting": false,
+          "error": null,
+          "onSubmitBooking": "fn()",
+          "onCancel": "fn()",
+          "onRetry": "fn()"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "1. Select dates; 2. Click submit with userEvent.click(getByRole('button', { name: 'Request to book' }));"
+      },
+      {
+        "name": "Loading",
+        "description": "Page in loading state.",
+        "args": {
+          "isLoading": true,
+          "isSubmitting": false,
+          "error": null,
+          "onSubmitBooking": "fn()",
+          "onCancel": "fn()",
+          "onRetry": "fn()"
+        }
+      },
+      {
+        "name": "Submitting",
+        "description": "Page in submitting state.",
+        "args": {
+          "isLoading": false,
+          "isSubmitting": true,
+          "error": null,
+          "onSubmitBooking": "fn()",
+          "onCancel": "fn()",
+          "onRetry": "fn()"
+        }
+      },
+      {
+        "name": "Error",
+        "description": "Page in error state.",
+        "args": {
+          "isLoading": false,
+          "isSubmitting": false,
+          "error": "Booking failed.",
+          "onSubmitBooking": "fn()",
+          "onCancel": "fn()",
+          "onRetry": "fn()"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "Click retry with userEvent.click(getByRole('button', { name: 'Retry' }));"
+      },
+      {
+        "name": "Invalid",
+        "description": "Page in editing-invalid state.",
+        "args": {
+          "isLoading": false,
+          "isSubmitting": false,
+          "error": null,
+          "onSubmitBooking": "fn()",
+          "onCancel": "fn()",
+          "onRetry": "fn()"
+        }
+      }
+    ],
+    "dataContract": {
+      "source": "graphql-mutation",
+      "operationName": "CreateBooking",
+      "fields": ["listingId", "dates.from", "dates.to", "guests"]
+    }
+  },
+  {
+    "componentId": "process-payment-page",
+    "componentName": "ProcessPaymentPage",
+    "isNew": true,
+    "atomicType": "page",
+    "composes": [
+      "credit-card-input",
+      "ui-components-form",
+      "ui-components-select",
+      "price-breakdown",
+      "ui-components-spinner",
+      "ui-components-alert",
+      "ui-components-alertdialog"
+    ],
+    "specDeltas": {
+      "structure": ["<main> with booking-confirmation in section, payment-form in form, payment-summary in aside."],
+      "rendering": [
+        "In loading state, shows Spinner in all regions.",
+        "In ready state, shows all regions without errors.",
+        "In editing-invalid state, shows all regions with inline errors in payment-form.",
+        "In submitting state, shows booking-confirmation and payment-summary; shows progress in payment-form; hides inputs.",
+        "In error state, shows booking-confirmation and payment-form; shows Alert destructive with retry in payment-summary."
+      ],
+      "interaction": [
+        "Submitting payment validates card and address, calls onPay if valid, transitioning to submitting.",
+        "Canceling navigates back to select-dates-book.",
+        "Unsaved changes triggers AlertDialog before navigating."
+      ],
+      "styling": [
+        "Main layout uses `flex flex-col md:flex-row min-h-screen bg-background gap-6 p-6`.",
+        "Booking confirmation section uses `flex-1`.",
+        "Payment form uses `w-full md:w-96 sticky top-20 bg-background border border-border rounded-lg p-6 shadow-sm` with `z-[200]`.",
+        "Payment summary aside uses `w-full md:w-80`.",
+        "Page enter uses react-spring `useSpring({ opacity: isReady ? 1 : 0, config: { tension: 400, friction: 26 } })`; respects `useReducedMotion()`.",
+        "Submitting progress uses `h-2 bg-secondary rounded-full` with react-spring `useSpring({ width: '0%' to '100%', config: { tension: 120, friction: 14 } })`; immediate on reduced motion.",
+        "Error alert uses `mb-4`.",
+        "Pay button uses `variant=\"default\"` with `w-full min-h-11`.",
+        "Cancel button uses `variant=\"ghost\"` with `w-full`.",
+        "Hover on buttons wrapped in `@media (hover: hover) and (pointer: fine) { hover:bg-primary/90 }`.",
+        "Focus rings on inputs use `focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2`.",
+        "Card inputs use `mb-4`.",
+        "Price numbers use `font-variant-numeric: tabular-nums`.",
+        "Touch targets for form fields use `min-h-11`."
+      ]
+    },
+    "props": [
+      {
+        "name": "isLoading",
+        "type": "boolean",
+        "required": false,
+        "default": "false",
+        "description": "Controls loading state.",
+        "category": "state"
+      },
+      {
+        "name": "isSubmitting",
+        "type": "boolean",
+        "required": false,
+        "default": "false",
+        "description": "Controls submitting state.",
+        "category": "state"
+      },
+      {
+        "name": "error",
+        "type": "string | null",
+        "required": false,
+        "default": "null",
+        "description": "Error message.",
+        "category": "state"
+      },
+      {
+        "name": "onPay",
+        "type": "(data: { card: object; address: object }) => void",
+        "required": true,
+        "description": "Callback for payment submission.",
+        "category": "callback"
+      },
+      {
+        "name": "onCancel",
+        "type": "() => void",
+        "required": true,
+        "description": "Callback for canceling.",
+        "category": "callback"
+      },
+      {
+        "name": "onRetry",
+        "type": "() => void",
+        "required": false,
+        "description": "Retry callback.",
+        "category": "callback"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "Page in ready state.",
+        "args": {
+          "isLoading": false,
+          "isSubmitting": false,
+          "error": null,
+          "onPay": "fn()",
+          "onCancel": "fn()",
+          "onRetry": "fn()"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "1. Fill card details; 2. Click pay with userEvent.click(getByRole('button', { name: /Pay/ }));"
+      },
+      {
+        "name": "Loading",
+        "description": "Page in loading state.",
+        "args": {
+          "isLoading": true,
+          "isSubmitting": false,
+          "error": null,
+          "onPay": "fn()",
+          "onCancel": "fn()",
+          "onRetry": "fn()"
+        }
+      },
+      {
+        "name": "Submitting",
+        "description": "Page in submitting state.",
+        "args": {
+          "isLoading": false,
+          "isSubmitting": true,
+          "error": null,
+          "onPay": "fn()",
+          "onCancel": "fn()",
+          "onRetry": "fn()"
+        }
+      },
+      {
+        "name": "Error",
+        "description": "Page in error state.",
+        "args": {
+          "isLoading": false,
+          "isSubmitting": false,
+          "error": "Payment failed.",
+          "onPay": "fn()",
+          "onCancel": "fn()",
+          "onRetry": "fn()"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "Click retry with userEvent.click(getByRole('button', { name: 'Retry' }));"
+      },
+      {
+        "name": "Invalid",
+        "description": "Page in editing-invalid state.",
+        "args": {
+          "isLoading": false,
+          "isSubmitting": false,
+          "error": null,
+          "onPay": "fn()",
+          "onCancel": "fn()",
+          "onRetry": "fn()"
+        }
+      }
+    ],
+    "dataContract": {
+      "source": "graphql-mutation",
+      "operationName": "ProcessPayment",
+      "fields": ["bookingId", "card.number", "card.expiry", "card.cvv", "address.street", "address.city"]
+    }
+  }
+]