@zoyth/simple-site-framework 1.0.0

package/docs/features/analytics/privacy.md

@@ -0,0 +1,198 @@
+# Analytics Privacy
+
+GDPR compliance and privacy-respecting analytics.
+
+## Overview
+
+The framework supports privacy-compliant analytics through:
+
+- Consent-based tracking
+- Cookie management
+- Data minimization
+- GTM consent mode
+
+## Consent Management
+
+### Consent Banner
+
+Implement a consent banner before loading analytics:
+
+```typescript
+'use client';
+import { useState, useEffect } from 'react';
+import { AnalyticsTracker } from '@zoyth/simple-site-framework/components';
+
+function Layout({ children }) {
+  const [consent, setConsent] = useState<boolean | null>(null);
+
+  useEffect(() => {
+    const stored = localStorage.getItem('analytics_consent');
+    if (stored !== null) setConsent(stored === 'true');
+  }, []);
+
+  return (
+    <>
+      {consent && <AnalyticsTracker gtmId="GTM-XXXXXXX" />}
+      {consent === null && (
+        <CookieBanner
+          onAccept={() => {
+            localStorage.setItem('analytics_consent', 'true');
+            setConsent(true);
+          }}
+          onDecline={() => {
+            localStorage.setItem('analytics_consent', 'false');
+            setConsent(false);
+          }}
+        />
+      )}
+      {children}
+    </>
+  );
+}
+```
+
+### GTM Consent Mode
+
+Use Google's consent mode for nuanced control:
+
+```typescript
+// Initialize with denied consent
+window.dataLayer = window.dataLayer || [];
+window.dataLayer.push({
+  'consent': 'default',
+  'analytics_storage': 'denied',
+  'ad_storage': 'denied',
+});
+
+// Update when user consents
+function grantConsent() {
+  window.dataLayer.push({
+    'consent': 'update',
+    'analytics_storage': 'granted',
+    'ad_storage': 'granted',
+  });
+}
+```
+
+## GDPR Compliance
+
+### Data Minimization
+
+Only track necessary data:
+
+```typescript
+// ✅ Good - Minimal data
+trackEvent('cta_click', {
+  cta_id: 'hero-signup',
+  page: '/pricing',
+});
+
+// ❌ Bad - Excessive data
+trackEvent('cta_click', {
+  cta_id: 'hero-signup',
+  user_email: user.email,        // PII
+  user_name: user.name,          // PII
+  ip_address: user.ip,           // PII
+  browser_fingerprint: hash,     // Identifying
+});
+```
+
+### Never Track PII
+
+Do not include in events:
+- Email addresses
+- Names
+- Phone numbers
+- IP addresses (handled by GA4 settings)
+- Precise location data
+- User IDs that map to real identities
+
+### Right to Erasure
+
+Support data deletion requests:
+
+1. Use GA4 User Deletion API
+2. Delete user data from GTM server-side
+3. Clear local cookies and storage
+
+### Data Retention
+
+Configure retention in GA4:
+1. GA4 Admin > Data Settings > Data Retention
+2. Set to shortest period needed (2 or 14 months)
+
+## Cookie Management
+
+### Analytics Cookies
+
+Common analytics cookies:
+
+| Cookie | Purpose | Duration |
+|--------|---------|----------|
+| `_ga` | GA4 user identification | 2 years |
+| `_ga_*` | GA4 session | 2 years |
+| `_gid` | GA4 session | 24 hours |
+| `_gat` | GA4 throttle | 1 minute |
+
+### Cookie-Free Tracking
+
+For stricter privacy requirements:
+
+```typescript
+// Use sessionStorage instead of cookies
+<AnalyticsTracker
+  gtmId="GTM-XXXXXXX"
+  cookieless={true}
+/>
+```
+
+## Privacy Regulations
+
+### GDPR (EU)
+
+Requirements:
+- Obtain consent before tracking
+- Provide clear privacy policy
+- Support data access requests
+- Support data deletion requests
+- Minimize data collection
+
+### CCPA (California)
+
+Requirements:
+- Disclose data collection practices
+- Provide opt-out mechanism
+- Do not sell personal information
+- Respond to consumer requests
+
+### PIPEDA (Canada)
+
+Requirements:
+- Obtain meaningful consent
+- Limit collection to necessary data
+- Provide access to personal information
+- Protect personal information
+
+## Privacy Policy
+
+Include in your privacy policy:
+- What data is collected
+- How it's used
+- Third-party services (Google Analytics, GTM)
+- Cookie information
+- User rights and how to exercise them
+- Contact information
+
+## Testing Privacy Compliance
+
+1. Visit site without consenting - verify no tracking fires
+2. Consent to tracking - verify analytics loads
+3. Decline tracking - verify no analytics cookies set
+4. Clear consent - verify banner reappears
+5. Check no PII in tracked events
+
+## See Also
+
+- [Analytics Setup](./setup.md)
+- [Tracking Events](./tracking-events.md)
+- [ScriptInjector Component](../../components/ScriptInjector.md)

package/docs/features/analytics/setup.md

@@ -0,0 +1,114 @@
+# Analytics Setup
+
+Configure analytics tracking for your site.
+
+## Google Tag Manager (GTM)
+
+### 1. Create GTM Account
+
+1. Go to [Google Tag Manager](https://tagmanager.google.com/)
+2. Create new account and container
+3. Copy your GTM ID (format: `GTM-XXXXXXX`)
+
+### 2. Add AnalyticsTracker
+
+Add to your root layout:
+
+```typescript
+// app/layout.tsx
+import { AnalyticsTracker } from '@zoyth/simple-site-framework/components';
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        <AnalyticsTracker gtmId={process.env.NEXT_PUBLIC_GTM_ID} />
+        {children}
+      </body>
+    </html>
+  );
+}
+```
+
+### 3. Environment Variables
+
+Add GTM ID to environment variables:
+
+```bash
+# .env.local
+NEXT_PUBLIC_GTM_ID=GTM-XXXXXXX
+```
+
+## Google Analytics 4 (GA4)
+
+### Via GTM (Recommended)
+
+1. In GTM, create new GA4 Configuration tag
+2. Add your GA4 Measurement ID
+3. Set trigger to "All Pages"
+4. Publish container
+
+### Direct Integration
+
+```typescript
+<AnalyticsTracker
+  gtmId={process.env.NEXT_PUBLIC_GTM_ID}
+  gaId={process.env.NEXT_PUBLIC_GA_ID}
+/>
+```
+
+## Verification
+
+### Check Installation
+
+1. Visit your site
+2. Open browser DevTools > Network tab
+3. Look for requests to `gtm.js` or `analytics.js`
+4. Check GTM Preview mode
+5. Verify events in GA4 Realtime view
+
+### Debug Mode
+
+Enable debug mode in development:
+
+```typescript
+<AnalyticsTracker
+  gtmId={process.env.NEXT_PUBLIC_GTM_ID}
+  debug={process.env.NODE_ENV === 'development'}
+/>
+```
+
+## Configuration Options
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `gtmId` | `string` | Yes* | Google Tag Manager ID |
+| `gaId` | `string` | No | Google Analytics 4 ID |
+| `debug` | `boolean` | No | Enable debug mode |
+| `dataLayer` | `string` | No | Custom dataLayer name (default: 'dataLayer') |
+
+*Either gtmId or gaId required
+
+## Development vs Production
+
+Use different GTM containers:
+
+```typescript
+const gtmId = process.env.NODE_ENV === 'production'
+  ? process.env.NEXT_PUBLIC_GTM_ID_PROD
+  : process.env.NEXT_PUBLIC_GTM_ID_DEV;
+
+<AnalyticsTracker gtmId={gtmId} />
+```
+
+## Next Steps
+
+- [Track custom events](./tracking-events.md)
+- [Set up A/B tests](./ab-testing.md)
+- [Configure conversion tracking](./conversion-tracking.md)
+
+## See Also
+
+- [Analytics Setup Guide](../../guides/analytics-setup.md)
+- [AnalyticsTracker Component](../../components/AnalyticsTracker.md)
+- [Privacy Configuration](./privacy.md)

package/docs/features/analytics/tracking-events.md

@@ -0,0 +1,224 @@
+# Tracking Events
+
+Track user interactions and custom events.
+
+## Event Tracking Functions
+
+### trackEvent
+
+Track generic custom events:
+
+```typescript
+'use client';
+import { trackEvent } from '@zoyth/simple-site-framework/client';
+
+function handleAction() {
+  trackEvent('button_click', {
+    category: 'engagement',
+    label: 'hero_cta',
+    value: 1,
+  });
+}
+```
+
+### trackPageView
+
+Track page views (automatically tracked by AnalyticsTracker):
+
+```typescript
+import { trackPageView } from '@zoyth/simple-site-framework/client';
+
+trackPageView('/about');
+```
+
+### trackCTAClick
+
+Track call-to-action clicks:
+
+```typescript
+import { trackCTAClick } from '@zoyth/simple-site-framework/client';
+
+<button onClick={() => trackCTAClick('signup', 'hero')}>
+  Sign Up
+</button>
+```
+
+## Common Events
+
+### Form Submissions
+
+```typescript
+function handleSubmit(e) {
+  e.preventDefault();
+
+  trackEvent('form_submit', {
+    form_name: 'contact',
+    form_location: 'contact_page',
+  });
+
+  // Handle form...
+}
+```
+
+### Link Clicks
+
+Use TrackedLink component:
+
+```typescript
+import { TrackedLink } from '@zoyth/simple-site-framework/components';
+
+<TrackedLink
+  href="/pricing"
+  eventName="pricing_link_click"
+  eventData={{ location: 'nav' }}
+>
+  View Pricing
+</TrackedLink>
+```
+
+### Video Interactions
+
+```typescript
+function handleVideoPlay() {
+  trackEvent('video_play', {
+    video_title: 'Product Demo',
+    video_duration: 120,
+  });
+}
+
+function handleVideoComplete() {
+  trackEvent('video_complete', {
+    video_title: 'Product Demo',
+  });
+}
+```
+
+### Scroll Depth
+
+```typescript
+'use client';
+import { useEffect } from 'react';
+import { trackEvent } from '@zoyth/simple-site-framework/client';
+
+export function ScrollTracker() {
+  useEffect(() => {
+    const depths = [25, 50, 75, 100];
+    let tracked = new Set();
+
+    function handleScroll() {
+      const scrollPercent =
+        (window.scrollY / (document.body.scrollHeight - window.innerHeight)) * 100;
+
+      depths.forEach(depth => {
+        if (scrollPercent >= depth && !tracked.has(depth)) {
+          trackEvent('scroll_depth', { depth });
+          tracked.add(depth);
+        }
+      });
+    }
+
+    window.addEventListener('scroll', handleScroll);
+    return () => window.removeEventListener('scroll', handleScroll);
+  }, []);
+
+  return null;
+}
+```
+
+## Event Data Structure
+
+Standard event properties:
+
+```typescript
+trackEvent('event_name', {
+  category: 'string',    // Event category
+  label: 'string',       // Event label
+  value: number,         // Numeric value
+  // Custom properties...
+});
+```
+
+## Enhanced E-commerce
+
+### Product Clicks
+
+```typescript
+trackEvent('select_item', {
+  item_list_name: 'Featured Products',
+  items: [{
+    item_id: 'SKU123',
+    item_name: 'Product Name',
+    price: 29.99,
+  }],
+});
+```
+
+### Add to Cart
+
+```typescript
+trackEvent('add_to_cart', {
+  currency: 'USD',
+  value: 29.99,
+  items: [{
+    item_id: 'SKU123',
+    item_name: 'Product Name',
+    price: 29.99,
+    quantity: 1,
+  }],
+});
+```
+
+### Purchase
+
+```typescript
+trackEvent('purchase', {
+  transaction_id: 'T12345',
+  value: 59.98,
+  currency: 'USD',
+  items: [{
+    item_id: 'SKU123',
+    item_name: 'Product Name',
+    price: 29.99,
+    quantity: 2,
+  }],
+});
+```
+
+## User Timing
+
+Track performance metrics:
+
+```typescript
+trackEvent('timing_complete', {
+  name: 'api_request',
+  value: 324, // milliseconds
+  category: 'performance',
+});
+```
+
+## Error Tracking
+
+```typescript
+try {
+  // Code that might fail
+} catch (error) {
+  trackEvent('exception', {
+    description: error.message,
+    fatal: false,
+  });
+}
+```
+
+## Best Practices
+
+- Use consistent event naming (snake_case recommended)
+- Include context in event properties
+- Don't track PII (personally identifiable information)
+- Test events in GTM Preview mode
+- Document your event taxonomy
+
+## See Also
+
+- [Custom Events](./custom-events.md)
+- [Conversion Tracking](./conversion-tracking.md)
+- [TrackedLink Component](../../components/TrackedLink.md)

package/docs/features/i18n/README.md

@@ -0,0 +1,51 @@
+# Internationalization (i18n)
+
+Complete guide to multi-language support in Simple Site Framework.
+
+## Overview
+
+Simple Site Framework provides built-in internationalization (i18n) support for creating multi-language websites with:
+
+- Configurable locale routing (always, as-needed, never)
+- LocalizedString type for content translation
+- Automatic language detection
+- SEO-optimized language alternates
+- RTL language support
+- Locale-aware formatting (dates, numbers, currency)
+
+## Quick Start
+
+```typescript
+// Configure locales
+export const i18nConfig = {
+  locales: ['en', 'fr', 'es'],
+  defaultLocale: 'en',
+  localePrefix: 'as-needed',
+  localeDetection: true,
+};
+
+// Use LocalizedString
+const heading = {
+  en: 'Welcome',
+  fr: 'Bienvenue',
+  es: 'Bienvenido',
+};
+
+<HeroSection heading={heading} locale={locale} />
+```
+
+## Topics
+
+- [Configuration](./configuration.md) - Setting up i18n config
+- [Routing](./routing.md) - Locale routing and URL structure
+- [Translations](./translations.md) - Managing translated content
+- [Locale Detection](./locale-detection.md) - Browser and cookie detection
+- [Formatting](./formatting.md) - Date, number, currency formatting
+- [RTL Support](./rtl-support.md) - Right-to-left language support
+- [Best Practices](./best-practices.md) - i18n patterns and tips
+
+## See Also
+
+- [Internationalization Feature Guide](../internationalization.md)
+- [LanguageSelector Component](../../components/layout/LanguageSelector.md)
+- [I18nMetaTags Component](../../components/I18nMetaTags.md)