redesign the homepage

apps/homepage/RentalDriveGo_Pricing_Section_Modularization_Plan_v1.0.md

@@ -0,0 +1,322 @@
+# RentalDriveGo Pricing Section and Homepage Modularization Plan
+
+**Version:** 1.0  
+**Date:** June 26, 2026  
+**Product:** RentalDriveGo  
+**Scope:** Localized public homepage for English, French, and Arabic
+
+## 1. Objective
+
+Refactor the homepage into independently maintainable sections and replace the existing quote-only pricing placeholder with a hybrid pricing section that can support transparent starting prices for standard plans and custom pricing for enterprise accounts.
+
+The implementation must let a developer update one section without editing the primary page composition or accidentally changing unrelated sections.
+
+## 2. Commercial decision
+
+RentalDriveGo should use a hybrid model:
+
+- Public starting prices for standard small and mid-market plans after finance approval.
+- A fleet-size selector to help visitors self-qualify.
+- Monthly and annual billing presentation.
+- Custom pricing for large fleets, franchises, migrations, and complex integrations.
+- A sales or demonstration CTA for every plan.
+
+Prices must not be invented in presentation components. All commercial amounts and approval state live in one configuration file.
+
+## 3. Homepage architecture
+
+The route component remains a thin composition layer:
+
+`src/app/[locale]/page.tsx`
+
+It renders these independent sections in order:
+
+1. `HeroSection`
+2. `TrustSection`
+3. `ComparisonSection`
+4. `WorkflowSection`
+5. `RolesSection`
+6. `ModulesSection`
+7. `ResultsSection`
+8. `IntegrationsSection`
+9. `SecuritySection`
+10. `PricingSection`
+11. `FaqSection`
+12. `FinalCtaSection`
+
+Each section lives in:
+
+`src/components/homepage/sections/`
+
+Section-specific CSS stays beside the section in its own CSS module. Shared tokens and generic components remain in the existing design system.
+
+## 3.1 Application shell preservation
+
+Homepage modularization must not remove, replace, or weaken the shared application shell. The following elements remain independent of homepage sections and must be preserved across future section updates:
+
+- RentalDriveGo brand link
+- Product, Workflow, Modules, Pricing, and FAQ navigation destinations
+- English, French, and Arabic locale controls
+- Light, dark, and system theme controls
+- Log in and account-creation actions
+- Mobile navigation drawer containing the same primary destinations
+- Shared footer navigation
+
+The full primary navigation remains visible at common laptop widths. At narrower widths, the same destinations move into the mobile drawer rather than being removed.
+
+## 4. Pricing section structure
+
+### 4.1 Header
+
+- Eyebrow: simple, scalable pricing.
+- Headline: pricing built around the fleet.
+- Supporting copy: explains that fleet size drives plan recommendations and that public values are controlled centrally.
+
+### 4.2 Fleet-size selector
+
+Four radio-button ranges:
+
+- 1–25 vehicles
+- 26–75 vehicles
+- 76–200 vehicles
+- 200+ vehicles
+
+The selected range changes the recommended plan and, after commercial approval, the displayed starting price.
+
+### 4.3 Billing selector
+
+- Monthly
+- Annual
+- Annual savings label only after the discount is financially approved
+
+Annual pricing is shown as a monthly equivalent and must be calculated from the approved annual discount in the commercial configuration.
+
+### 4.4 Plan cards
+
+#### Launch
+
+For independent rental companies moving away from fragmented manual processes.
+
+Core capabilities:
+
+- Reservations and availability
+- Fleet and vehicle records
+- Rental agreements
+- Customer records
+- Basic operational reporting
+- Standard support
+
+#### Growth
+
+For growing fleets coordinating more vehicles, users, and locations.
+
+Core capabilities:
+
+- Everything in Launch
+- Multiple locations
+- Online booking workflows
+- Digital signatures and deposits
+- Maintenance workflows
+- Advanced reporting and automation
+- Priority support
+
+#### Enterprise
+
+For large fleets, franchise operations, and complex integration requirements.
+
+Core capabilities:
+
+- Everything in Growth
+- Custom integrations and API access
+- Advanced permissions
+- Migration planning
+- Custom onboarding
+- Service-level agreement options
+- Dedicated account support
+
+### 4.5 Supporting commercial information
+
+The section also shows:
+
+- Factors that affect final price
+- Optional modules
+- Commercial assurances
+- A link back to product modules
+- A configuration note while prices remain unapproved
+
+## 5. Commercial configuration
+
+All financial values are stored in:
+
+`src/content/pricing-config.ts`
+
+The configuration controls:
+
+- Currency
+- Annual discount percentage
+- Public-price approval state
+- Monthly prices by plan and fleet band
+- Recommended plan by fleet band
+
+### Publishing prices
+
+Before setting `publicPricesApproved` to `true`, finance and product must approve:
+
+1. Monthly prices
+2. Included active vehicles
+3. Included locations and users
+4. Additional-vehicle rules
+5. Annual discount
+6. Onboarding charges
+7. Migration charges
+8. Taxes and currency presentation
+9. Optional-module pricing
+10. Enterprise qualification threshold
+
+Until approval, the UI displays a localized “starting price pending approval” state rather than fabricated numbers.
+
+## 6. Localization
+
+Pricing copy is stored in:
+
+- `src/content/locales/en/homepage.json`
+- `src/content/locales/fr/homepage.json`
+- `src/content/locales/ar/homepage.json`
+
+Rules:
+
+- All three locales must preserve the same data structure.
+- Arabic remains true document-level RTL.
+- Prices use `Intl.NumberFormat` with the active locale.
+- Monetary values use bidirectional isolation in Arabic.
+- Plan IDs and fleet-band IDs remain stable, non-translated identifiers.
+
+## 7. Accessibility requirements
+
+- Fleet and billing selectors use native radio inputs and fieldsets.
+- Every control has a visible label.
+- Keyboard focus is visible.
+- The recommended plan is not communicated by color alone.
+- Price updates use an `aria-live` region.
+- CTA controls retain minimum touch-target sizing.
+- Layout supports forced colors and reduced motion.
+- Mobile presentation does not require horizontal scrolling.
+
+## 8. Responsive behavior
+
+### Desktop
+
+- Three plan cards in one row.
+- Recommended card receives stronger visual emphasis.
+- Fleet and billing controls share one row.
+
+### Tablet
+
+- Two cards on the first row.
+- Enterprise spans the second row.
+- Controls collapse when necessary.
+
+### Mobile
+
+- Controls stack.
+- Plan cards stack.
+- The recommended plan moves first.
+- CTAs use full width.
+- No pricing comparison table is forced into horizontal scrolling.
+
+## 9. Analytics
+
+The pricing section introduces these events:
+
+- `pricing_fleet_band_selected`
+- `pricing_billing_period_changed`
+- `pricing_plan_cta_clicked`
+
+Safe event properties:
+
+- Locale
+- Direction
+- Theme
+- Fleet band
+- Billing period
+- Plan ID
+- Source
+
+No name, email, company, phone number, or free-text form data is included.
+
+## 10. Testing
+
+Required checks:
+
+- All locales build the same pricing model.
+- Four fleet bands exist.
+- Three plans exist.
+- Public prices remain blocked until approval.
+- The recommended plan changes with fleet selection.
+- Annual billing selection works.
+- RTL layout remains valid.
+- Homepage still contains exactly twelve sections.
+- Navigation hashes still resolve.
+- Pricing controls are keyboard-accessible.
+
+## 11. Files added or changed
+
+### Added
+
+- `src/components/homepage/Homepage.module.css`
+- `src/components/homepage/README.md`
+- `src/components/homepage/sections/*.tsx`
+- Section-specific CSS modules
+- `src/content/pricing-config.ts`
+- `tests/unit/pricing.test.ts`
+
+### Changed
+
+- `src/app/[locale]/page.tsx`
+- `src/content/homepage-model.ts`
+- English, French, and Arabic homepage resources
+- Analytics event contract
+- Demo source contract
+- Homepage unit and browser tests
+
+### Removed
+
+- `src/app/[locale]/page.module.css`
+
+Its rules were moved into section-owned CSS modules so unrelated sections no longer share one page stylesheet.
+
+## 12. Definition of done
+
+The work is complete when:
+
+- The route page only composes section components.
+- Each section can be edited independently.
+- Pricing is fully localized and responsive.
+- Commercial values are centralized and guarded.
+- No unapproved prices are published.
+- Type checking, linting, unit tests, and browser tests pass.
+- The updated repository archive includes this plan and implementation.
+
+## 13. Implementation status
+
+Completed in this package:
+
+- The homepage route is reduced to section composition.
+- Twelve homepage sections are independently editable.
+- Section-specific CSS is colocated with each section.
+- The interactive pricing section is implemented.
+- English, French, and Arabic pricing content is implemented.
+- RTL, dark theme, responsive layout, forced colors, and reduced motion are covered.
+- Pricing analytics events and the pricing demo source are registered.
+- Commercial amounts and discount values remain blocked pending approval.
+- The package was made standalone by removing an unused workspace-only dependency and its pre-scripts.
+- The missing `@axe-core/playwright` test dependency was added.
+
+Validation completed:
+
+- TypeScript strict check: passed.
+- ESLint with zero warnings: passed.
+- Unit and component tests: 51 passed.
+- Next.js production build: passed with an explicit local `SITE_ORIGIN`.
+
+Browser test files were updated, but full Playwright execution could not be completed in the build container. The managed system Chromium blocks loopback navigation, while downloading Playwright Chromium was prevented by unavailable DNS access to the Playwright CDN. This is an environment restriction, not a passing test result. Run the browser suite in the project CI environment before release.