@zoyth/simple-site-framework 1.0.0

package/docs/accessibility/wcag-compliance.md

@@ -0,0 +1,159 @@
+# WCAG 2.1 AA Compliance Checklist
+
+Use this checklist when building sites with the Simple Site Framework to ensure WCAG 2.1 Level AA compliance.
+
+## Perceivable
+
+### Text Alternatives (1.1)
+- [ ] All images have alt text
+- [ ] Decorative images use empty alt (`alt=""`)
+- [ ] Icon-only buttons have `aria-label`
+- [ ] Form inputs have associated labels
+
+### Time-based Media (1.2)
+- [ ] Videos have captions
+- [ ] Audio content has transcripts
+- [ ] Video-only content has audio description or transcript
+
+### Adaptable (1.3)
+- [ ] Use semantic HTML elements (`<button>`, `<nav>`, `<main>`, etc.)
+- [ ] Heading hierarchy is logical (h1 → h2 → h3)
+- [ ] Lists use `<ul>`, `<ol>`, `<li>` elements
+- [ ] Tables have proper headers (`<th>`)
+- [ ] Form labels are programmatically associated
+
+### Distinguishable (1.4)
+- [ ] Color is not the only means of conveying information
+- [ ] Text contrast is at least 4.5:1 (3:1 for large text)
+- [ ] UI component contrast is at least 3:1
+- [ ] Text can be resized to 200% without loss of functionality
+- [ ] No background audio that can't be paused
+- [ ] Line height is at least 1.5x font size
+- [ ] Paragraph spacing is at least 2x font size
+
+## Operable
+
+### Keyboard Accessible (2.1)
+- [ ] All functionality available via keyboard
+- [ ] No keyboard traps
+- [ ] Keyboard shortcuts don't conflict with assistive tech
+- [ ] Tab order is logical
+- [ ] Focus is visible on all interactive elements
+
+### Enough Time (2.2)
+- [ ] Time limits can be extended or disabled
+- [ ] Auto-updating content can be paused
+- [ ] Session timeouts are announced in advance
+
+### Seizures and Physical Reactions (2.3)
+- [ ] No content flashes more than 3 times per second
+- [ ] Parallax and motion can be disabled via `prefers-reduced-motion`
+
+### Navigable (2.4)
+- [ ] Skip link to main content
+- [ ] Page titles are descriptive
+- [ ] Focus order is meaningful
+- [ ] Link text describes destination
+- [ ] Multiple ways to find pages (menu, search, sitemap)
+- [ ] Headings and labels are descriptive
+- [ ] Focus is visible
+
+### Input Modalities (2.5)
+- [ ] Touch targets are at least 44x44px
+- [ ] Gestures have keyboard alternatives
+- [ ] Click events don't fire on touch down
+- [ ] Labels match accessible names
+
+## Understandable
+
+### Readable (3.1)
+- [ ] Page language is declared (`lang="en"`)
+- [ ] Language changes are marked (`lang="fr"`)
+
+### Predictable (3.2)
+- [ ] Focus doesn't trigger unexpected context changes
+- [ ] Input doesn't cause unexpected context changes
+- [ ] Navigation is consistent across pages
+- [ ] Components with same functionality have consistent labels
+
+### Input Assistance (3.3)
+- [ ] Form errors are clearly identified
+- [ ] Labels or instructions provided for input
+- [ ] Error messages suggest corrections
+- [ ] Errors can be corrected before final submission
+- [ ] Confirmation for legal/financial transactions
+
+## Robust
+
+### Compatible (4.1)
+- [ ] Valid HTML (no duplicate IDs)
+- [ ] Start and end tags are properly nested
+- [ ] ARIA attributes are valid
+- [ ] Status messages use `role="status"` or `aria-live`
+
+## Framework-Specific Checks
+
+### Components
+- [ ] Use framework components instead of custom elements
+- [ ] Pass `aria-label` to icon-only buttons
+- [ ] Enable `prefers-reduced-motion` support in animations
+- [ ] Use `Toast` for announcements, not console.log
+- [ ] Use `Modal` component's built-in focus trap
+
+### Theme
+- [ ] Color palette meets contrast requirements
+- [ ] Focus ring is visible and high-contrast
+- [ ] Error/success states use more than just color
+
+### Forms
+- [ ] Use `FormField` component for consistent labels
+- [ ] Use `error` prop to display validation messages
+- [ ] Mark required fields with `required` prop
+- [ ] Group related inputs with `fieldset` and `legend`
+
+## Testing Process
+
+1. **Automated Testing**
+   - Use Lighthouse audit
+   - Run axe DevTools browser extension
+   - Integrate axe-core in test suite
+
+2. **Manual Testing**
+   - Navigate entire site with keyboard only
+   - Test with screen reader (NVDA, VoiceOver, JAWS)
+   - Zoom to 200% and verify layout
+   - Test with high contrast mode
+   - Verify with `prefers-reduced-motion` enabled
+
+3. **User Testing**
+   - Test with users who use assistive technology
+   - Get feedback from people with disabilities
+
+## Common Issues to Avoid
+
+❌ **Don't**
+- Use `div` or `span` as buttons
+- Rely on color alone for status
+- Hide focus indicators
+- Use low-contrast colors
+- Autoplay videos with sound
+- Create keyboard traps
+- Use tiny touch targets
+- Skip heading levels
+
+✅ **Do**
+- Use semantic HTML
+- Provide text alternatives
+- Make interactive elements keyboard accessible
+- Ensure sufficient color contrast
+- Support prefers-reduced-motion
+- Test with assistive technology
+- Follow ARIA best practices
+- Keep it simple
+
+## Resources
+
+- [WCAG 2.1 Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)
+- [Framework Component Guides](./components/)
+- [Keyboard Navigation Guide](./keyboard-navigation.md)
+- [Screen Reader Testing](./screen-readers.md)

package/docs/api/README.md

@@ -0,0 +1,164 @@
+# API Reference - Component Discovery Index
+
+Quick reference for all 35+ framework components with their key capabilities.
+
+## Layout Components (6)
+
+| Component | Purpose | Key Features |
+|-----------|---------|--------------|
+| `Header` | Site header with navigation | Mobile menu, language switcher, sticky header, logo display |
+| `Footer` | Site footer | Multi-column layout, social links, copyright, newsletter |
+| `LanguageSwitcher` | Language toggle | French/English switching with flags |
+| `PageLayout` | Standard page wrapper | Consistent spacing, responsive containers |
+| `ServicePageLayout` | Service detail pages | Hero, content sections, sidebar CTA |
+| `LazySection` | Lazy-loading wrapper | Intersection observer, loading states, performance optimization |
+
+## Section Components (15)
+
+| Component | Purpose | Key Features |
+|-----------|---------|--------------|
+| `HeroSection` | Above-fold hero banner | **Animations** (fadeInUp, slideInLeft), **sticky CTA**, **video backgrounds**, **parallax**, **trust badges**, scroll indicator |
+| `AboutSection` | Company/service overview | Rich content, timeline, team grid, image gallery |
+| `ServicesSection` | Service offerings grid | Hover effects, filtering, card layouts |
+| `FeaturesGrid` | Feature showcase | Icons, descriptions, grid/list layouts |
+| `TestimonialsSection` | Customer testimonials | Ratings, rotation, avatar display |
+| `FAQSection` | Frequently asked questions | **Searchable**, **expandable accordion**, categories |
+| `TeamSection` | Team member profiles | Bios, photos, social links, grid layout |
+| `ContactSection` | Contact form and info | **Full form validation**, **multiple locations**, **maps**, **office hours**, file uploads, spam protection |
+| `CTASection` | Call-to-action prompts | Banner, split, card variants |
+| `WhyChooseUsSection` | Differentiators | Icon + text grid, visual emphasis |
+| `SecurePortalSection` | Secure portal CTA | Login link, security badges |
+| `PersonalTaxesSection` | Service-specific CTA | Tax service promotion |
+| `RecruitingSection` | Recruitment CTA | Job listings link, company culture |
+| `PricingSection` | Pricing tables | Feature comparison, highlights, CTAs |
+| `StatsSection` | Statistics showcase | Counter animations, grid layout |
+| `LogosSection` | Client/partner logos | Responsive grid, grayscale/color variants |
+| `TimelineSection` | Company/process timeline | Vertical timeline with milestones |
+| `ProcessSection` | Step-by-step process | Numbered steps, visual flow |
+
+## UI Components (14)
+
+| Component | Purpose | Key Features |
+|-----------|---------|--------------|
+| `Button` | Action buttons | **6 variants** (outlined, filled, text, ghost, link, destructive), **5 sizes**, **loading/success states**, **icons**, **ripple effect**, **tooltips** |
+| `Card` | Content containers | Variants, hover effects, flexible layout |
+| `Badge` | Status/category indicators | Color variants, sizes |
+| `Icon` | Type-safe icons | **1000+ Lucide icons**, autocomplete, presets |
+| `Input` | Text input fields | Validation states, labels, errors |
+| `Textarea` | Multi-line text input | Auto-resize, character count |
+| `Select` | Dropdown selection | Radix UI powered, keyboard navigation |
+| `Checkbox` | Boolean input | Indeterminate state, labels |
+| `Radio` | Single choice input | Radio groups, labels |
+| `FormField` | Form field wrapper | Label, error display, required indicator |
+| `Breadcrumb` | Breadcrumb navigation | Auto-generated from route, custom items |
+| `Tabs` | Tab navigation | Radix UI powered, keyboard accessible |
+| `Accordion` | Collapsible content | Radix UI powered, single/multiple open |
+| `Dialog` | Modal dialogs | Radix UI powered, focus trap, backdrop |
+| `Tooltip` | Hover tooltips | Radix UI powered, positioning |
+| `Toast` | Toast notifications | Success, error, info variants |
+
+## Development Tools (4)
+
+| Component | Purpose | Key Features |
+|-----------|---------|--------------|
+| `StyleGuide` | Interactive brand reference | **All colors**, **typography**, **components**, **spacing**, perfect for design reviews |
+| `CodeBlock` | Syntax-highlighted code | **Copy button**, line numbers, 100+ languages |
+| `ComponentDemo` | Live component previews | Code + preview, interactive examples |
+| `HeadScripts` | Document head injection | Meta tags, structured data, scripts |
+| `BodyEndScripts` | Body end injection | Analytics, chat widgets, deferred scripts |
+
+## Key Type Exports
+
+### Component Props
+- `ButtonProps` - Enhanced button configuration (loading, success, icons, ripple)
+- `HeroSectionProps` - Hero configuration including animations
+- `ContactSectionProps` - Contact form and location configuration
+- `IconProps` - Icon component props with type-safe names
+
+### Configuration Types
+- `ThemeConfig` - Complete theme configuration
+- `SiteContent` - Site content structure
+- `NavigationConfig` - Header/footer navigation
+- `LocalizedString` - Bilingual text (`{ fr: string, en: string }`)
+
+### Feature-Specific Types
+- `HeroAnimations` - Animation configuration for hero section
+  ```typescript
+  {
+    headline?: 'fadeInUp' | 'fadeIn' | 'slideInLeft' | 'none'
+    cta?: 'fadeInUp' | 'fadeIn' | 'none'
+    stagger?: number
+    scrollIndicator?: boolean
+  }
+  ```
+
+- `ContactFormConfig` - Form field and validation configuration
+  ```typescript
+  {
+    enabled?: boolean
+    fields?: Array<'name' | 'email' | 'phone' | 'subject' | 'message' | 'attachment'>
+    requiredFields?: Array<'name' | 'email' | 'phone' | 'subject' | 'message'>
+    onSubmit?: (data: ContactFormData) => Promise<void>
+    spamProtection?: SpamProtection
+    integration?: FormIntegration
+  }
+  ```
+
+- `Badge` - Trust badge/logo configuration
+- `Location` - Office location with maps and hours
+- `FormIntegration` - Third-party form integrations (email services, CRMs)
+
+## Utility Functions
+
+| Function | Purpose | Example |
+|----------|---------|---------|
+| `getLocalizedString(str, locale)` | Get text for current locale | `getLocalizedString(content.title, 'fr')` |
+| `cn(...classes)` | Merge Tailwind classes | `cn('px-4', 'py-2', className)` |
+| `generateThemeCSS(theme)` | Generate CSS variables | Used internally by framework |
+
+## Import Patterns
+
+```typescript
+// Components
+import { HeroSection, Button, Icon } from '@zoyth/simple-site-framework'
+
+// Types
+import type { HeroAnimations, ContactFormConfig } from '@zoyth/simple-site-framework'
+
+// Utilities
+import { getLocalizedString, cn } from '@zoyth/simple-site-framework'
+
+// Icon presets
+import { Icons } from '@zoyth/simple-site-framework'
+```
+
+## Most Commonly Used Components
+
+For a typical professional services site:
+
+1. **HeroSection** - with animations and sticky CTA
+2. **ServicesSection** - showcase offerings
+3. **ContactSection** - with working form
+4. **AboutSection** - company story
+5. **TestimonialsSection** - social proof
+6. **FAQSection** - answer common questions
+7. **Button** - CTAs throughout
+8. **Icon** - visual elements
+
+## Advanced Features to Explore
+
+- **Button loading/success states** - Automatic state management for forms
+- **Hero sticky CTA** - CTA button that appears on scroll
+- **Hero animations** - Coordinated entrance animations
+- **Contact multi-location** - Support multiple offices with maps
+- **Icon type safety** - Autocomplete for 1000+ icons
+- **LazySection** - Performance optimization for below-fold content
+- **StyleGuide** - Interactive brand reference for stakeholders
+
+## Next Steps
+
+- See **[Full API Reference](./components/)** for detailed prop documentation (coming soon - issue #46)
+- See **[Examples](../examples/)** for usage patterns (coming soon - issue #46)
+- See **[Recipes](../recipes/)** for common patterns (coming soon - issue #46)
+- See **[README.md](../../README.md)** for quick start guide
+- See **[QUICKSTART.md](../../QUICKSTART.md)** for step-by-step tutorial

package/docs/api/components/Accessibility.md

@@ -0,0 +1,356 @@
+# Accessibility Components & Hooks
+
+Comprehensive accessibility utilities for building WCAG 2.1 AA compliant applications.
+
+## Components
+
+### SkipLink
+
+Allows keyboard users to skip repetitive navigation and jump directly to main content.
+
+#### Import
+
+```typescript
+import { SkipLink } from '@zoyth/simple-site-framework'
+import type { SkipLinkProps } from '@zoyth/simple-site-framework'
+```
+
+#### Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `href` | `string` | ✅ | Target element ID (e.g., "#main-content") |
+| `children` | `ReactNode` | ✅ | Link text |
+| `className` | `string` | - | Additional CSS classes |
+
+#### Usage
+
+```tsx
+// In your layout, before header
+<SkipLink href="#main-content">
+  Skip to main content
+</SkipLink>
+
+// In your main content area
+<main id="main-content" tabIndex={-1}>
+  {/* Your content */}
+</main>
+```
+
+The link is hidden by default and appears only when focused with Tab key.
+
+---
+
+### A11yAnnouncer
+
+Screen reader announcement component for dynamic content changes.
+
+#### Import
+
+```typescript
+import { A11yAnnouncer, GlobalA11yAnnouncer } from '@zoyth/simple-site-framework'
+import type { A11yAnnouncerProps, AnnouncementPriority } from '@zoyth/simple-site-framework'
+```
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `message` | `string` | - | Message to announce |
+| `priority` | `'polite' \| 'assertive'` | `'polite'` | Announcement priority |
+| `clearAfter` | `number` | `3000` | Clear message after ms |
+
+#### Priority Levels
+
+- **polite**: Waits for user to pause before announcing (default)
+- **assertive**: Interrupts screen reader immediately (use sparingly)
+
+#### Local Announcer
+
+```tsx
+const [message, setMessage] = useState('')
+
+// Trigger announcement
+<button onClick={() => setMessage('Item added to cart')}>
+  Add to Cart
+</button>
+
+// Announcer component
+<A11yAnnouncer message={message} priority="polite" />
+```
+
+#### Global Announcer
+
+Place once in your root layout for app-wide announcements:
+
+```tsx
+// app/layout.tsx
+import { GlobalA11yAnnouncer } from '@zoyth/simple-site-framework'
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        <GlobalA11yAnnouncer />
+        {children}
+      </body>
+    </html>
+  )
+}
+```
+
+Then announce from anywhere:
+
+```typescript
+import { announce } from '@zoyth/simple-site-framework'
+
+// Polite announcement
+announce('Form submitted successfully', 'polite')
+
+// Assertive announcement (errors, urgent)
+announce('Error: Please fix the form errors', 'assertive')
+```
+
+## Hooks
+
+### useA11y
+
+Convenience hook for accessibility utilities.
+
+#### Import
+
+```typescript
+import { useA11y } from '@zoyth/simple-site-framework'
+```
+
+#### Usage
+
+```tsx
+function MyComponent() {
+  const { announce } = useA11y()
+
+  const handleSubmit = async () => {
+    await submitForm()
+    announce('Form submitted successfully!', 'polite')
+  }
+
+  return <button onClick={handleSubmit}>Submit</button>
+}
+```
+
+Requires `<GlobalA11yAnnouncer />` in your layout.
+
+---
+
+### useFocusTrap
+
+Trap keyboard focus within a container (for modals, dialogs).
+
+#### Import
+
+```typescript
+import { useFocusTrap } from '@zoyth/simple-site-framework'
+import type { UseFocusTrapOptions } from '@zoyth/simple-site-framework'
+```
+
+#### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | `boolean` | `true` | Whether focus trap is active |
+| `initialFocus` | `HTMLElement \| null` | - | Element to focus on activation |
+| `allowTabEscape` | `boolean` | `false` | Allow Tab to escape the trap |
+
+#### Usage
+
+```tsx
+function Modal({ isOpen, onClose }) {
+  const modalRef = useRef<HTMLDivElement>(null)
+
+  useFocusTrap(modalRef, { enabled: isOpen })
+
+  if (!isOpen) return null
+
+  return (
+    <div ref={modalRef} role="dialog">
+      <h2>Modal Title</h2>
+      <button onClick={onClose}>Close</button>
+      <input type="text" />
+    </div>
+  )
+}
+```
+
+Focus automatically moves to first focusable element and cycles within the modal.
+
+---
+
+### useFocusReturn
+
+Return focus to previous element when component unmounts.
+
+#### Import
+
+```typescript
+import { useFocusReturn } from '@zoyth/simple-site-framework'
+import type { UseFocusReturnOptions } from '@zoyth/simple-site-framework'
+```
+
+#### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | `boolean` | `true` | Whether to return focus |
+| `returnTo` | `HTMLElement \| null` | - | Custom element to focus |
+
+#### Usage
+
+```tsx
+function Modal({ isOpen, onClose }) {
+  useFocusReturn({ enabled: isOpen })
+
+  if (!isOpen) return null
+
+  return (
+    <div role="dialog">
+      <h2>Modal Title</h2>
+      <button onClick={onClose}>Close</button>
+    </div>
+  )
+}
+```
+
+Focus returns to the element that triggered the modal when it closes.
+
+---
+
+### useModalFocus
+
+Combined hook for complete modal focus management (trap + return).
+
+#### Import
+
+```typescript
+import { useModalFocus } from '@zoyth/simple-site-framework'
+```
+
+#### Usage
+
+```tsx
+function Modal({ isOpen, onClose }) {
+  const modalRef = useRef<HTMLDivElement>(null)
+
+  useModalFocus(modalRef, { enabled: isOpen })
+
+  if (!isOpen) return null
+
+  return (
+    <div ref={modalRef} role="dialog">
+      <h2>Modal Title</h2>
+      <button onClick={onClose}>Close</button>
+      <input type="text" />
+    </div>
+  )
+}
+```
+
+Handles both focus trapping and focus return automatically.
+
+## Complete Modal Example
+
+```tsx
+import { useRef } from 'react'
+import { useModalFocus, useA11y } from '@zoyth/simple-site-framework'
+
+function DeleteConfirmModal({ isOpen, onClose, onConfirm }) {
+  const modalRef = useRef<HTMLDivElement>(null)
+  const { announce } = useA11y()
+
+  useModalFocus(modalRef, { enabled: isOpen })
+
+  const handleConfirm = () => {
+    onConfirm()
+    announce('Item deleted', 'polite')
+    onClose()
+  }
+
+  if (!isOpen) return null
+
+  return (
+    <div
+      ref={modalRef}
+      role="dialog"
+      aria-labelledby="modal-title"
+      aria-modal="true"
+      className="fixed inset-0 z-50 flex items-center justify-center bg-black/50"
+    >
+      <div className="bg-white p-6 rounded-lg max-w-md">
+        <h2 id="modal-title" className="text-xl font-bold mb-4">
+          Confirm Delete
+        </h2>
+        <p className="mb-6">
+          Are you sure you want to delete this item? This action cannot be undone.
+        </p>
+        <div className="flex gap-4">
+          <button
+            onClick={handleConfirm}
+            className="px-4 py-2 bg-red-600 text-white rounded"
+          >
+            Delete
+          </button>
+          <button
+            onClick={onClose}
+            className="px-4 py-2 bg-gray-200 rounded"
+          >
+            Cancel
+          </button>
+        </div>
+      </div>
+    </div>
+  )
+}
+```
+
+## Best Practices
+
+### SkipLink
+- Place before all other content (first element in body)
+- Use clear, concise text ("Skip to main content")
+- Target main content area with `id` attribute
+- Make target focusable with `tabIndex={-1}`
+
+### Announcements
+- Use `'polite'` for most announcements
+- Use `'assertive'` only for errors or urgent information
+- Keep messages concise and clear
+- Don't announce every tiny change
+- Clear messages after a few seconds
+
+### Focus Management
+- Always trap focus in modals/dialogs
+- Return focus when closing modals
+- Focus first interactive element by default
+- Provide visual focus indicators
+- Test with keyboard only
+
+### Testing
+- Test with keyboard navigation (Tab, Shift+Tab)
+- Test with screen readers (NVDA, VoiceOver, JAWS)
+- Verify announcements are read correctly
+- Ensure focus trap doesn't break navigation
+- Check focus return works as expected
+
+## Accessibility Checklist
+
+When using these components:
+
+- [ ] SkipLink is first element in document
+- [ ] Main content has unique `id` attribute
+- [ ] GlobalA11yAnnouncer in root layout
+- [ ] Modals use focus trap
+- [ ] Modals return focus on close
+- [ ] Announcements use appropriate priority
+- [ ] All interactive elements are keyboard accessible
+- [ ] Focus indicators are visible
+- [ ] Tested with keyboard only
+- [ ] Tested with screen reader