# Proration Preview

## Objective

Show the exact money effect of a plan change before the user confirms it.

An itemised preview of the credits, charges, tax and timing that result from switching plan, interval, or seat count.

## Before You Begin

This feature is being added to an application that already exists and already
works. Do not scaffold a new project, and do not assume a blank slate.

Inspect the codebase first and establish:

- The existing application structure and where code of this kind already lives.
- The framework and version in use.
- The existing design system — colours, spacing, typography, and component conventions.
- Existing UI components you can reuse instead of writing new ones.
- The existing database structure, if this feature needs to persist anything.
- The existing authentication and authorization system, if this feature is user-scoped.
- Dependencies already installed, so you don't add a library that duplicates one.
- The existing test setup and conventions.

Only start writing code once you understand the above. If the application
already implements part of this feature, extend it rather than replacing it.

## Implementation Instructions

1. Ask the billing provider for the preview. Do not reimplement proration arithmetic — the provider's rounding, day-counting and tax rules are the ones that will appear on the invoice, and yours will drift from them.
2. Show the line items, not just a total: credit for the unused portion, charge for the new plan, tax, discounts, and what is due today versus at the next renewal.
3. Cover seat-count changes as well as plan changes. Seat counting rules and the invite-blocking behaviour are owned by Seat Management; extend that rather than building a second seat model — this entry only prices the change it hands you.
4. Bind every preview to the exact inputs that produced it, and re-fetch when any of them change.
5. State plainly when the amount due today is zero and why — a blank preview reads as a broken page.

## UI and UX Requirements

Match the application's existing design system exactly. Reuse its components,
spacing, and typography. This feature should look like it was always there.

## Responsive Requirements

Works on mobile, tablet, and desktop. Touch targets are large enough to hit on a
phone, and nothing overflows horizontally at 320px.

## Accessibility Requirements

- Fully keyboard navigable.
- Correct semantic elements and ARIA roles.
- Visible focus states.
- Meets WCAG AA contrast.
- Dynamic changes are announced to screen readers.
- Respects prefers-reduced-motion.

## Edge Cases

- A preview goes stale the moment quantity, plan, coupon or the clock moves past the period boundary. Expire it and re-fetch rather than charging against an old quote.
- The result can be a credit rather than a charge. Say where that credit goes — balance or refund — because those are very different to a customer.
- Downgrades mid-period often produce no immediate invoice at all. Show when the change takes effect instead of showing nothing.
- Switching between monthly and annual changes the period length, not just the price. Show the new renewal date.
- An existing credit balance can absorb the whole charge. The preview must show the balance applied and what remains.
- Provider preview calls fail or time out. Block confirmation with an honest message; never fall back to a locally-guessed number.

## Testing

Exercise the feature end to end in the running application. Cover every edge case
above, then run the existing test suite and confirm nothing regressed.

## Acceptance Criteria

- [ ] Every preview figure comes from the billing provider's preview endpoint, not local arithmetic.
- [ ] Credits, charges, discounts and tax are itemised separately from the total due today.
- [ ] Changing any input invalidates the current preview before the user can confirm against it.
- [ ] Zero-charge, credit-producing and deferred outcomes each have their own explicit copy.
- [ ] The amount actually charged matches the previewed amount for an unchanged input set.
- [ ] A failed preview prevents confirmation rather than showing a stale or estimated figure.
- [ ] The feature matches the existing design system.
- [ ] No existing functionality is broken.

## Adaptation Rules

- Match the existing design system. Do not introduce a new colour palette,
  spacing scale, or component library.
- Reuse existing components and utilities wherever they fit.
- Follow the naming, file layout, and code style already present.
- Do not upgrade, replace, or remove existing dependencies to make this
  feature fit. Adapt the feature to the app, not the app to the feature.
- Do not break existing functionality. If a change is genuinely required in
  existing code, make the smallest one that works and say so.
- If something in these instructions conflicts with how the application is
  built, follow the application and explain the deviation.

## Final Verification

Before you report the work as done:

1. Re-read the acceptance criteria above and check each one against what you
   actually built.
2. Run the application and exercise the feature end to end.
3. Run the existing test suite and confirm you have broken nothing.
4. Check the feature on mobile, tablet, and desktop widths.
5. Check keyboard navigation and focus handling.
6. Summarize what changed: files added, files modified, and anything you
   deliberately did differently because of how this application is built.

If any acceptance criterion is unmet, fix it before reporting completion.