@zoyth/simple-site-framework 1.1.0 → 1.1.1

package/docs/components/NewsletterSignup.md

@@ -0,0 +1,275 @@
+# NewsletterSignup
+
+Email capture form with multiple layout variants, size options, client-side validation, honeypot spam protection, and bilingual support (EN/FR).
+
+## Import
+
+```typescript
+import { NewsletterSignup } from '@zoyth/simple-site-framework';
+```
+
+**Type:** Client Component (`'use client'`)
+
+## Basic Usage
+
+```typescript
+<NewsletterSignup
+  onSubmit={async (data) => {
+    const res = await fetch('/api/subscribe', {
+      method: 'POST',
+      body: JSON.stringify(data),
+    });
+    const json = await res.json();
+    return { success: json.ok };
+  }}
+/>
+```
+
+## Props
+
+### Required Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `onSubmit` | `(data: NewsletterSubmitData) => Promise<NewsletterResponse>` | Async handler called on form submission. Receives `{ email: string; name?: string }` and must return `{ success: boolean; message?: string; error?: string }` |
+
+### Optional Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `'inline' \| 'stacked' \| 'minimal' \| 'card'` | `'stacked'` | Layout variant (see Variants below) |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Controls text size and input/button padding |
+| `showName` | `boolean` | `false` | Show a name input field (hidden in `minimal` variant) |
+| `showPrivacy` | `boolean` | `false` | Show a privacy policy checkbox that must be accepted |
+| `privacyUrl` | `string` | `'/privacy'` | URL the privacy policy link points to |
+| `locale` | `string` | `'en'` | Current locale. Controls all default labels and validation messages |
+| `buttonText` | `LocalizedString \| string` | `'Subscribe'` / `'S'abonner'` | Custom submit button text |
+| `emailPlaceholder` | `LocalizedString \| string` | `'you@example.com'` / `'vous@exemple.com'` | Custom email placeholder |
+| `namePlaceholder` | `LocalizedString \| string` | `'Your name'` / `'Votre nom'` | Custom name field placeholder |
+| `successMessage` | `LocalizedString \| string` | `'Thank you for subscribing!'` / `'Merci pour votre inscription !'` | Custom success message |
+| `className` | `string` | - | Additional CSS classes on the outer container |
+
+### Type Definitions
+
+```typescript
+interface NewsletterSubmitData {
+  email: string;
+  name?: string;
+}
+
+interface NewsletterResponse {
+  success: boolean;
+  message?: string;
+  error?: string;
+}
+```
+
+## Variants
+
+### Stacked (Default)
+
+Fields and button arranged vertically with full-width inputs and labels:
+
+```typescript
+<NewsletterSignup
+  onSubmit={handleSubscribe}
+  variant="stacked"
+/>
+```
+
+**Use for:** Sidebar widgets, dedicated signup sections, anywhere with limited horizontal space.
+
+### Inline
+
+Fields and button arranged horizontally in a single row:
+
+```typescript
+<NewsletterSignup
+  onSubmit={handleSubscribe}
+  variant="inline"
+/>
+```
+
+**Use for:** Footer bars, hero sections, compact horizontal layouts. Labels are replaced with `aria-label` attributes for accessibility.
+
+### Minimal
+
+Email field and button only, no labels displayed:
+
+```typescript
+<NewsletterSignup
+  onSubmit={handleSubscribe}
+  variant="minimal"
+/>
+```
+
+The `showName` prop is ignored in this variant. Accessibility labels are provided via `aria-label`.
+
+**Use for:** Compact spaces, inline CTAs, anywhere a lightweight form is needed.
+
+### Card
+
+Wrapped in a bordered card with padding and subtle shadow:
+
+```typescript
+<NewsletterSignup
+  onSubmit={handleSubscribe}
+  variant="card"
+/>
+```
+
+**Use for:** Standalone signup blocks, sidebar cards, visually distinct callouts.
+
+## Sizes
+
+| Size | Text | Input Padding | Button Padding |
+|------|------|---------------|----------------|
+| `sm` | `text-sm` | `px-3 py-1.5` | `px-4 py-1.5` |
+| `md` | `text-base` | `px-4 py-2` | `px-6 py-2` |
+| `lg` | `text-lg` | `px-5 py-3` | `px-8 py-3` |
+
+```typescript
+<NewsletterSignup onSubmit={handleSubscribe} size="lg" />
+```
+
+## Localization
+
+All default labels adapt based on the `locale` prop:
+
+| Label | English (`'en'`) | French (`'fr'`) |
+|-------|-------------------|------------------|
+| Subscribe button | "Subscribe" | "S'abonner" |
+| Email label | "Email address" | "Adresse courriel" |
+| Name label | "Name" | "Nom" |
+| Email placeholder | "you@example.com" | "vous@exemple.com" |
+| Name placeholder | "Your name" | "Votre nom" |
+| Email required error | "Please enter your email address." | "Veuillez entrer votre adresse courriel." |
+| Email invalid error | "Please enter a valid email address." | "Veuillez entrer une adresse courriel valide." |
+| Privacy required error | "You must accept the privacy policy." | "Vous devez accepter la politique de confidentialite." |
+| Privacy text | "I agree to the" | "J'accepte la" |
+| Privacy link | "privacy policy" | "politique de confidentialite" |
+| Success message | "Thank you for subscribing!" | "Merci pour votre inscription !" |
+| Generic error | "Something went wrong. Please try again." | "Une erreur est survenue. Veuillez reessayer." |
+| Submitting state | "Subscribing..." | "Inscription..." |
+
+## Examples
+
+### With Name Field
+
+```typescript
+<NewsletterSignup
+  onSubmit={handleSubscribe}
+  showName={true}
+/>
+```
+
+### With Privacy Checkbox
+
+```typescript
+<NewsletterSignup
+  onSubmit={handleSubscribe}
+  showPrivacy={true}
+  privacyUrl="/en/privacy-policy"
+/>
+```
+
+The form will not submit until the checkbox is checked.
+
+### French Locale
+
+```typescript
+<NewsletterSignup
+  onSubmit={handleSubscribe}
+  locale="fr"
+  variant="card"
+/>
+```
+
+### Custom Text
+
+```typescript
+<NewsletterSignup
+  onSubmit={handleSubscribe}
+  buttonText={{ en: 'Join the list', fr: 'Rejoindre la liste' }}
+  emailPlaceholder="enter@your.email"
+  successMessage={{ en: 'You are in!', fr: 'Vous etes inscrit !' }}
+/>
+```
+
+### Inline in Footer
+
+```typescript
+<footer className="bg-gray-900 text-white py-12">
+  <div className="max-w-4xl mx-auto">
+    <h3 className="text-lg font-semibold mb-4">Stay updated</h3>
+    <NewsletterSignup
+      onSubmit={handleSubscribe}
+      variant="inline"
+      size="sm"
+    />
+  </div>
+</footer>
+```
+
+### Card with All Options
+
+```typescript
+<NewsletterSignup
+  onSubmit={handleSubscribe}
+  variant="card"
+  size="lg"
+  showName={true}
+  showPrivacy={true}
+  privacyUrl="/privacy"
+  locale="en"
+  buttonText="Get Updates"
+  emailPlaceholder="your@email.com"
+  namePlaceholder="First name"
+  successMessage="Welcome aboard!"
+/>
+```
+
+## Validation
+
+The component performs client-side validation before calling `onSubmit`:
+
+1. **Empty email** - shows "Please enter your email address."
+2. **Invalid email format** - uses the regex `/^[^\s@]+@[^\s@]+\.[^\s@]+$/` and shows "Please enter a valid email address."
+3. **Privacy checkbox** - if `showPrivacy` is `true` and unchecked, shows "You must accept the privacy policy."
+
+Validation messages are localized based on the `locale` prop.
+
+## Spam Protection
+
+The component includes a hidden honeypot field. If a bot fills it in, the form silently does nothing on submit (no error, no API call). The honeypot field is:
+
+- Hidden via CSS (`className="hidden"`)
+- Marked with `aria-hidden="true"`
+- Uses `tabIndex={-1}` to prevent keyboard focus
+- Has `autoComplete="off"` to prevent browser autofill
+
+## Form States
+
+The component manages four internal states:
+
+| State | Behavior |
+|-------|----------|
+| `idle` | Default state. Form is interactive |
+| `submitting` | Inputs and button are disabled. Button text changes to "Subscribing..." |
+| `success` | Form is replaced with the success message (rendered as a `role="status"` paragraph) |
+| `error` | Error message appears below the form as a `role="alert"` paragraph |
+
+## Accessibility
+
+- Email input has `required` attribute
+- Labels are rendered for `stacked` and `card` variants
+- `aria-label` attributes are used for `inline` and `minimal` variants where visual labels are omitted
+- Error messages use `role="alert"` for screen reader announcement
+- Success message uses `role="status"`
+- All inputs respect `disabled` state during submission
+
+## See Also
+
+- **[Button](./ui/Button.md)** - Button component used throughout the framework
+- **[ContactSection](./sections/ContactSection.md)** - Full contact form section (for more complex form needs)
+- **[BlogIndex](./BlogIndex.md)** - Blog listing page where a newsletter signup might be placed

package/docs/components/accessibility/SkipLink.md

@@ -0,0 +1,146 @@
+# SkipLink
+
+Accessible skip navigation link for keyboard users. Hidden by default, it appears when focused via Tab and allows users to bypass repetitive navigation elements and jump directly to the main content area.
+
+## Import
+
+```typescript
+import { SkipLink } from '@zoyth/simple-site-framework';
+```
+
+**Type:** Client Component (`'use client'`)
+
+**Source:** `src/components/a11y/SkipLink.tsx`
+
+## Basic Usage
+
+```typescript
+// In your root layout, before the header
+<SkipLink href="#main-content">Skip to main content</SkipLink>
+<Header />
+<main id="main-content" tabIndex={-1}>
+  {children}
+</main>
+```
+
+## Props
+
+### Required Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `href` | `string` | CSS selector for the target element to skip to (e.g., `"#main-content"`) |
+| `children` | `ReactNode` | Link text displayed when the component is focused |
+
+### Optional Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Additional CSS classes merged with the default styles |
+
+## How It Works
+
+1. The link is positioned absolutely at the top-left of the page and translated off-screen (`-translate-y-full`).
+2. When a keyboard user presses Tab, the link receives focus and transitions into view (`focus:translate-y-0`).
+3. On click, the component prevents the default anchor behavior and instead:
+   - Finds the target element using `document.querySelector(href)`
+   - Calls `.focus()` on the target element
+   - Scrolls the target into view with `{ behavior: 'smooth', block: 'start' }`
+
+This approach works even when the target element is not natively focusable, as long as it has `tabIndex={-1}`.
+
+## Examples
+
+### Standard Layout Integration
+
+```typescript
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        <SkipLink href="#main-content">Skip to main content</SkipLink>
+        <Header />
+        <main id="main-content" tabIndex={-1}>
+          {children}
+        </main>
+        <Footer />
+      </body>
+    </html>
+  );
+}
+```
+
+### French Label
+
+```typescript
+<SkipLink href="#contenu-principal">
+  Aller au contenu principal
+</SkipLink>
+```
+
+### Multiple Skip Links
+
+For pages with complex navigation, you can provide multiple skip links:
+
+```typescript
+<div>
+  <SkipLink href="#main-content">Skip to main content</SkipLink>
+  <SkipLink href="#sidebar">Skip to sidebar</SkipLink>
+</div>
+
+{/* Later in the page */}
+<main id="main-content" tabIndex={-1}>...</main>
+<aside id="sidebar" tabIndex={-1}>...</aside>
+```
+
+### Custom Styling
+
+```typescript
+<SkipLink
+  href="#main-content"
+  className="text-lg rounded-br-lg"
+>
+  Skip to main content
+</SkipLink>
+```
+
+## Default Styles
+
+The component applies these styles by default:
+
+| State | Styles |
+|-------|--------|
+| Hidden (default) | `absolute left-0 top-0 z-50 -translate-y-full` |
+| Visible (focused) | `focus:translate-y-0` with `transition-transform` |
+| Visual | `bg-primary text-white px-4 py-2 font-medium` |
+| Focus ring | `focus:ring-2 focus:ring-offset-2 focus:ring-primary` with `focus:outline-none` |
+
+Custom classes passed via `className` are merged using the `cn()` utility, so they can override any default.
+
+## Target Element Setup
+
+The target element must:
+
+1. Have an `id` that matches the `href` value (without the `#`)
+2. Have `tabIndex={-1}` so it can receive programmatic focus
+
+```typescript
+{/* Correct */}
+<main id="main-content" tabIndex={-1}>
+
+{/* The href must include the # */}
+<SkipLink href="#main-content">Skip to main content</SkipLink>
+```
+
+## Accessibility
+
+- Meets WCAG 2.1 Success Criterion 2.4.1 (Bypass Blocks)
+- Only visible to keyboard users (hidden from mouse/touch users)
+- Uses semantic `<a>` element
+- Focus ring provides clear visual indication
+- Smooth scroll provides orientation context after the skip
+
+## See Also
+
+- **[Header](./layout/Header.md)** - Site header that the skip link typically bypasses
+- **[PageLayout](./layout/PageLayout.md)** - Standard page wrapper where skip links are commonly placed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zoyth/simple-site-framework",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "A configuration-driven framework for building professional service websites",
   "keywords": [
     "framework",