npm - @zoyth/simple-site-framework - Versions diffs - 1.0.0 - Mend

@zoyth/simple-site-framework 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (166) hide show

package/LICENSE +21 -0
package/README.md +572 -0
package/bin/create-simple-site.js +390 -0
package/bin/simple-site.js +664 -0
package/dist/client.js +135 -0
package/dist/client.js.map +1 -0
package/dist/client.mjs +107 -0
package/dist/client.mjs.map +1 -0
package/dist/components/index.d.mts +3936 -0
package/dist/components/index.d.ts +3936 -0
package/dist/components/index.js +38265 -0
package/dist/components/index.js.map +1 -0
package/dist/components/index.mjs +38173 -0
package/dist/components/index.mjs.map +1 -0
package/dist/config/index.d.mts +298 -0
package/dist/config/index.d.ts +298 -0
package/dist/config/index.js +19 -0
package/dist/config/index.js.map +1 -0
package/dist/config/index.mjs +1 -0
package/dist/config/index.mjs.map +1 -0
package/dist/index.d.mts +2184 -0
package/dist/index.d.ts +2184 -0
package/dist/index.js +1713 -0
package/dist/index.js.map +1 -0
package/dist/index.mjs +1605 -0
package/dist/index.mjs.map +1 -0
package/dist/lib/i18n/index.js +665 -0
package/dist/lib/i18n/index.js.map +1 -0
package/dist/lib/i18n/index.mjs +621 -0
package/dist/lib/i18n/index.mjs.map +1 -0
package/docs/DOCUMENTATION-STRUCTURE.md +1156 -0
package/docs/EXPORTS.md +125 -0
package/docs/PERFORMANCE.md +757 -0
package/docs/POLICY-PAGES.md +867 -0
package/docs/ROADMAP.md +334 -0
package/docs/SEO.md +455 -0
package/docs/SITEMAP.md +708 -0
package/docs/STRUCTURED-DATA.md +671 -0
package/docs/accessibility/common-patterns.md +529 -0
package/docs/accessibility/keyboard-navigation.md +263 -0
package/docs/accessibility/overview.md +122 -0
package/docs/accessibility/screen-readers.md +311 -0
package/docs/accessibility/wcag-compliance.md +159 -0
package/docs/api/README.md +164 -0
package/docs/api/components/Accessibility.md +356 -0
package/docs/api/components/Button.md +240 -0
package/docs/api/components/HeroSection.md +306 -0
package/docs/architecture/decisions.md +449 -0
package/docs/components/AnalyticsTracker.md +58 -0
package/docs/components/AnimatedCounter.md +48 -0
package/docs/components/AnimatedSection.md +56 -0
package/docs/components/BlogCard.md +42 -0
package/docs/components/Checkbox.md +56 -0
package/docs/components/CodeBlock.md +52 -0
package/docs/components/ComparisonTable.md +40 -0
package/docs/components/ComponentDemo.md +38 -0
package/docs/components/CountdownTimer.md +51 -0
package/docs/components/ExitIntentModal.md +56 -0
package/docs/components/FAQAccordion.md +66 -0
package/docs/components/FeaturesGrid.md +55 -0
package/docs/components/FileUpload.md +54 -0
package/docs/components/I18nMetaTags.md +55 -0
package/docs/components/Icon.md +53 -0
package/docs/components/LazySection.md +46 -0
package/docs/components/LiveProof.md +53 -0
package/docs/components/LoadingSpinner.md +46 -0
package/docs/components/MultiStepForm.md +48 -0
package/docs/components/PolicyLayout.md +55 -0
package/docs/components/PricingTable.md +49 -0
package/docs/components/Radio.md +59 -0
package/docs/components/SEOMetaTags.md +58 -0
package/docs/components/ScriptInjector.md +50 -0
package/docs/components/Select.md +72 -0
package/docs/components/Skeleton.md +47 -0
package/docs/components/StatsSection.md +48 -0
package/docs/components/StickyBar.md +62 -0
package/docs/components/StructuredData.md +99 -0
package/docs/components/StyleGuide.md +46 -0
package/docs/components/TableOfContents.md +47 -0
package/docs/components/TestimonialCarousel.md +42 -0
package/docs/components/Timeline.md +51 -0
package/docs/components/Toast.md +59 -0
package/docs/components/TrackedLink.md +62 -0
package/docs/components/TrustBadges.md +44 -0
package/docs/components/conversion/MobileCTA.md +363 -0
package/docs/components/forms/ContactForm.md +75 -0
package/docs/components/forms/FormField.md +74 -0
package/docs/components/layout/Footer.md +601 -0
package/docs/components/layout/Header.md +549 -0
package/docs/components/layout/LanguageSelector.md +54 -0
package/docs/components/layout/LanguageSwitcher.md +24 -0
package/docs/components/overview.md +447 -0
package/docs/components/sections/AboutSection.md +48 -0
package/docs/components/sections/CTASection.md +596 -0
package/docs/components/sections/CaseStudySection.md +47 -0
package/docs/components/sections/ContactSection.md +599 -0
package/docs/components/sections/FeatureSection.md +44 -0
package/docs/components/sections/HeroSection.md +404 -0
package/docs/components/sections/LogosSection.md +47 -0
package/docs/components/sections/PersonalTaxesSection.md +23 -0
package/docs/components/sections/RecruitingSection.md +23 -0
package/docs/components/sections/SecurePortalSection.md +23 -0
package/docs/components/sections/ServicePageLayout.md +52 -0
package/docs/components/sections/ServicesSection.md +49 -0
package/docs/components/sections/TestimonialSection.md +44 -0
package/docs/components/sections/WhyChooseUsSection.md +54 -0
package/docs/components/ui/Breadcrumb.md +70 -0
package/docs/components/ui/Button.md +514 -0
package/docs/components/ui/Card.md +501 -0
package/docs/components/ui/Input.md +54 -0
package/docs/components/ui/MobileLinks.md +43 -0
package/docs/components/ui/Modal.md +60 -0
package/docs/components/ui/Tabs.md +62 -0
package/docs/components/ui/Textarea.md +52 -0
package/docs/core-concepts/configuration-driven.md +552 -0
package/docs/core-concepts/overview.md +351 -0
package/docs/features/accessibility/README.md +73 -0
package/docs/features/accessibility/aria-support.md +177 -0
package/docs/features/accessibility/color-contrast.md +155 -0
package/docs/features/accessibility/focus-management.md +187 -0
package/docs/features/accessibility/testing.md +196 -0
package/docs/features/analytics/README.md +51 -0
package/docs/features/analytics/ab-testing.md +171 -0
package/docs/features/analytics/conversion-tracking.md +207 -0
package/docs/features/analytics/custom-events.md +219 -0
package/docs/features/analytics/privacy.md +198 -0
package/docs/features/analytics/setup.md +114 -0
package/docs/features/analytics/tracking-events.md +224 -0
package/docs/features/i18n/README.md +51 -0
package/docs/features/i18n/best-practices.md +273 -0
package/docs/features/i18n/configuration.md +84 -0
package/docs/features/i18n/formatting.md +133 -0
package/docs/features/i18n/locale-detection.md +122 -0
package/docs/features/i18n/routing.md +99 -0
package/docs/features/i18n/rtl-support.md +191 -0
package/docs/features/i18n/translations.md +129 -0
package/docs/features/internationalization.md +595 -0
package/docs/features/performance/README.md +77 -0
package/docs/features/performance/bundle-size.md +134 -0
package/docs/features/performance/caching.md +131 -0
package/docs/features/performance/code-splitting.md +121 -0
package/docs/features/performance/image-optimization.md +110 -0
package/docs/features/performance/lazy-loading.md +92 -0
package/docs/features/performance/monitoring.md +148 -0
package/docs/features/seo/README.md +51 -0
package/docs/features/seo/best-practices.md +184 -0
package/docs/features/seo/canonical-urls.md +182 -0
package/docs/features/seo/meta-tags.md +126 -0
package/docs/features/seo/open-graph.md +166 -0
package/docs/features/seo/robots-txt.md +146 -0
package/docs/features/seo/sitemaps.md +162 -0
package/docs/features/seo/structured-data.md +166 -0
package/docs/getting-started/installation.md +292 -0
package/docs/getting-started/introduction.md +195 -0
package/docs/getting-started/quick-start.md +460 -0
package/docs/guides/analytics-setup.md +616 -0
package/docs/i18n/CONFIGURATION.md +353 -0
package/docs/i18n/EXAMPLES.md +402 -0
package/docs/i18n/MIGRATION.md +260 -0
package/docs/i18n/SEO.md +392 -0
package/docs/i18n/STATIC-GENERATION-FIX.md +71 -0
package/docs/migration/changelog.md +136 -0
package/docs/migration/overview.md +233 -0
package/docs/recipes/adding-animations.md +475 -0
package/docs/recipes/forms-with-validation.md +393 -0
package/package.json +152 -0

package/docs/guides/analytics-setup.md ADDED Viewed

@@ -0,0 +1,616 @@
+# Analytics Setup
+Complete guide to setting up analytics tracking with Simple Site Framework.
+## Overview
+The framework provides built-in analytics utilities for:
+- **Page view tracking** - Automatic on route changes
+- **Scroll depth tracking** - Engagement milestones (25%, 50%, 75%, 100%)
+- **CTA click tracking** - Button and link conversions
+- **A/B test events** - Test variant tracking
+- **Custom events** - Flexible event tracking
+All analytics push to `window.dataLayer` for Google Tag Manager compatibility.
+## Quick Start
+### 1. Add Analytics Tracker
+```typescript
+// src/app/layout.tsx
+import { AnalyticsTracker } from '@zoyth/simple-site-framework/client';
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        <AnalyticsTracker />
+        {children}
+      </body>
+    </html>
+  );
+}
+```
+This automatically tracks:
+- Page views on route changes
+- Scroll depth at 25%, 50%, 75%, 100%
+### 2. Add Google Tag Manager
+```typescript
+// src/app/layout.tsx
+import Script from 'next/script';
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <head>
+        <Script id="gtm" strategy="afterInteractive">
+          {`
+            (function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
+            new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
+            j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
+            'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
+            })(window,document,'script','dataLayer','GTM-XXXXXX');
+          `}
+        </Script>
+      </head>
+      <body>
+        <AnalyticsTracker />
+        {children}
+      </body>
+    </html>
+  );
+}
+```
+Replace `GTM-XXXXXX` with your GTM container ID.
+## Page View Tracking
+### Automatic Tracking
+`AnalyticsTracker` automatically tracks page views on route changes:
+```typescript
+// Pushed to dataLayer:
+{
+  event: 'page_view',
+  page_path: '/about',
+  page_title: 'About Us - Your Company'
+}
+```
+### Manual Page View
+```typescript
+import { trackPageView } from '@zoyth/simple-site-framework/lib/analytics';
+trackPageView('/custom-page', 'Custom Page Title');
+```
+### With Metadata
+```typescript
+trackPageView('/product/123', 'Product Details', {
+  product_id: '123',
+  category: 'electronics',
+  price: 99.99
+});
+```
+## Scroll Depth Tracking
+### Automatic Tracking
+`AnalyticsTracker` tracks scroll milestones:
+```typescript
+// Pushed to dataLayer at each milestone:
+{
+  event: 'scroll_depth',
+  event_category: 'engagement',
+  event_label: '25%',
+  scroll_percentage: 25,
+  page_path: '/about'
+}
+```
+Milestones: 25%, 50%, 75%, 100%
+### Manual Scroll Tracking
+```typescript
+import { trackScrollDepth } from '@zoyth/simple-site-framework/lib/analytics';
+trackScrollDepth(50, '/about');  // Track 50% scroll
+```
+### Custom Milestones
+Create your own scroll tracker:
+```typescript
+'use client';
+import { useEffect, useRef } from 'react';
+import { trackScrollDepth } from '@zoyth/simple-site-framework/lib/analytics';
+export function CustomScrollTracker({ milestones = [10, 30, 60, 90] }) {
+  const tracked = useRef(new Set());
+  useEffect(() => {
+    const handleScroll = () => {
+      const windowHeight = window.innerHeight;
+      const documentHeight = document.documentElement.scrollHeight;
+      const scrollTop = window.scrollY;
+      const scrollPercent = (scrollTop / (documentHeight - windowHeight)) * 100;
+      for (const milestone of milestones) {
+        if (scrollPercent >= milestone && !tracked.current.has(milestone)) {
+          tracked.current.add(milestone);
+          trackScrollDepth(milestone, window.location.pathname);
+        }
+      }
+    };
+    window.addEventListener('scroll', handleScroll, { passive: true });
+    return () => window.removeEventListener('scroll', handleScroll);
+  }, [milestones]);
+  return null;
+}
+```
+## CTA Click Tracking
+### Opt-in Click Tracking
+Components support optional `onClick` for tracking:
+```typescript
+<HeroSection
+  heading="Welcome"
+  cta={{
+    text: 'Get Started',
+    href: '/signup',
+    onClick: () => {
+      // Your tracking logic
+      trackCTAClick('hero_cta', { location: 'homepage' });
+    }
+  }}
+/>
+```
+### Track Link Clicks
+Use `TrackedLink` for automatic link tracking:
+```typescript
+import { TrackedLink } from '@zoyth/simple-site-framework';
+<TrackedLink
+  href="/pricing"
+  eventName="pricing_link_click"
+  eventData={{ location: 'footer' }}
+>
+  View Pricing
+</TrackedLink>
+```
+Pushed to dataLayer:
+```typescript
+{
+  event: 'link_click',
+  event_category: 'navigation',
+  event_label: 'pricing_link_click',
+  link_url: '/pricing',
+  ...eventData
+}
+```
+### Track Button Clicks
+```typescript
+import { trackEvent } from '@zoyth/simple-site-framework/lib/analytics';
+<Button
+  onClick={() => {
+    trackEvent('button_click', {
+      button_text: 'Download',
+      button_location: 'hero',
+      file_type: 'pdf'
+    });
+  }}
+>
+  Download PDF
+</Button>
+```
+## A/B Test Tracking
+### Track A/B Test Events
+```typescript
+import { getABTestVariant, trackABTestEvent } from '@zoyth/simple-site-framework/client';
+// Get variant
+const variant = getABTestVariant({
+  testId: 'hero_cta_test',
+  variants: { A: { weight: 50 }, B: { weight: 50 } }
+});
+// Show variant
+const ctaText = variant === 'A' ? 'Get Started' : 'Start Free Trial';
+// Track conversion
+<Button
+  onClick={() => {
+    trackABTestEvent('hero_cta_test', variant, 'conversion', {
+      revenue: 99.99
+    });
+  }}
+>
+  {ctaText}
+</Button>
+```
+Pushed to dataLayer:
+```typescript
+{
+  event: 'ab_test_event',
+  event_category: 'ab_test',
+  event_label: 'hero_cta_test_A_conversion',
+  test_id: 'hero_cta_test',
+  variant: 'A',
+  test_event: 'conversion',
+  revenue: 99.99
+}
+```
+## Custom Events
+### Basic Custom Event
+```typescript
+import { trackEvent } from '@zoyth/simple-site-framework/lib/analytics';
+trackEvent('video_play', {
+  video_title: 'Product Demo',
+  video_duration: 120,
+  video_percent: 0
+});
+```
+### E-commerce Events
+```typescript
+// Add to cart
+trackEvent('add_to_cart', {
+  item_id: 'SKU123',
+  item_name: 'Premium Plan',
+  price: 99.99,
+  currency: 'USD',
+  quantity: 1
+});
+// Begin checkout
+trackEvent('begin_checkout', {
+  value: 99.99,
+  currency: 'USD',
+  items: [{
+    item_id: 'SKU123',
+    item_name: 'Premium Plan',
+    price: 99.99
+  }]
+});
+// Purchase
+trackEvent('purchase', {
+  transaction_id: 'T12345',
+  value: 99.99,
+  currency: 'USD',
+  items: [...]
+});
+```
+### Form Events
+```typescript
+// Form start
+trackEvent('form_start', {
+  form_id: 'contact_form',
+  form_name: 'Contact Us'
+});
+// Form submit
+trackEvent('form_submit', {
+  form_id: 'contact_form',
+  form_name: 'Contact Us',
+  submission_time: Date.now()
+});
+// Form error
+trackEvent('form_error', {
+  form_id: 'contact_form',
+  error_field: 'email',
+  error_message: 'Invalid email format'
+});
+```
+## Google Tag Manager Setup
+### 1. Create GTM Container
+1. Go to [tagmanager.google.com](https://tagmanager.google.com)
+2. Create a new container for your website
+3. Copy the GTM container ID (GTM-XXXXXX)
+### 2. Add GTM Script
+```typescript
+// src/app/layout.tsx
+<Script id="gtm" strategy="afterInteractive">
+  {`
+    (function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
+    new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
+    j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
+    'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
+    })(window,document,'script','dataLayer','${process.env.NEXT_PUBLIC_GTM_ID}');
+  `}
+</Script>
+<!-- GTM noscript (in <body>) -->
+<noscript>
+  <iframe
+    src={`https://www.googletagmanager.com/ns.html?id=${process.env.NEXT_PUBLIC_GTM_ID}`}
+    height="0"
+    width="0"
+    style={{ display: 'none', visibility: 'hidden' }}
+  />
+</noscript>
+```
+### 3. Configure Tags in GTM
+**Page View Tag:**
+1. New Tag → Google Analytics: GA4 Event
+2. Event Name: `page_view`
+3. Trigger: Custom Event → `page_view`
+4. Add Event Parameters from dataLayer variables
+**Scroll Depth Tag:**
+1. New Tag → Google Analytics: GA4 Event
+2. Event Name: `scroll`
+3. Trigger: Custom Event → `scroll_depth`
+4. Add parameters: scroll_percentage, page_path
+**Custom Event Tag:**
+1. New Tag → Google Analytics: GA4 Event
+2. Event Name: `{{Event}}` (use Event variable)
+3. Trigger: All Custom Events
+4. Pass all dataLayer variables as parameters
+## Environment-Specific Tracking
+### Development vs Production
+```typescript
+// src/lib/analytics/config.ts
+export const analyticsConfig = {
+  enabled: process.env.NODE_ENV === 'production',
+  gtmId: process.env.NEXT_PUBLIC_GTM_ID,
+  debug: process.env.NODE_ENV === 'development',
+};
+// Conditional tracking
+import { analyticsConfig } from '@/lib/analytics/config';
+function trackEvent(eventName, data) {
+  if (!analyticsConfig.enabled) {
+    if (analyticsConfig.debug) {
+      console.log('[Analytics Debug]', eventName, data);
+    }
+    return;
+  }
+  // Real tracking
+  pushToDataLayer({ event: eventName, ...data });
+}
+```
+### Multiple Environments
+```env
+# .env.local
+NEXT_PUBLIC_GTM_ID=GTM-DEV123
+# .env.production
+NEXT_PUBLIC_GTM_ID=GTM-PROD456
+```
+## Privacy & GDPR Compliance
+### Cookie Consent Integration
+```typescript
+'use client';
+import { AnalyticsTracker } from '@zoyth/simple-site-framework/client';
+import { useEffect, useState } from 'react';
+export function ConditionalAnalytics() {
+  const [consent, setConsent] = useState(false);
+  useEffect(() => {
+    // Check cookie consent
+    const hasConsent = getCookieConsent();
+    setConsent(hasConsent);
+  }, []);
+  if (!consent) return null;
+  return <AnalyticsTracker />;
+}
+function getCookieConsent() {
+  // Check your consent management platform
+  return localStorage.getItem('cookie_consent') === 'granted';
+}
+```
+### Anonymize IP Addresses
+Configure in GTM:
+1. Open your GA4 Configuration Tag
+2. Add Field: `anonymize_ip` → `true`
+### Disable Tracking
+```typescript
+// Respect Do Not Track
+const dnt = navigator.doNotTrack || window.doNotTrack;
+if (dnt === '1' || dnt === 'yes') {
+  // Don't load AnalyticsTracker
+}
+```
+## Testing & Debugging
+### Enable Debug Mode
+```typescript
+// Development console logs
+if (process.env.NODE_ENV === 'development') {
+  console.log('[Analytics]', {
+    event: 'page_view',
+    page_path: '/about'
+  });
+}
+```
+### GTM Preview Mode
+1. Open GTM
+2. Click "Preview"
+3. Enter your site URL
+4. See all events in real-time
+### Chrome DevTools
+```javascript
+// View dataLayer in console
+window.dataLayer
+// See all pushed events
+// Watch for new events
+window.dataLayer.push = new Proxy(window.dataLayer.push, {
+  apply(target, thisArg, args) {
+    console.log('[DataLayer Push]', args[0]);
+    return target.apply(thisArg, args);
+  }
+});
+```
+### GA4 DebugView
+1. Open GA4 property
+2. Go to DebugView (in Reports)
+3. See real-time events from preview/debug mode
+## Best Practices
+### ✅ Do
+- Track meaningful conversions (signups, purchases, form submits)
+- Use consistent event naming (snake_case recommended)
+- Include relevant context in event data
+- Test tracking before deploying
+- Document your tracking plan
+- Respect user privacy and consent
+- Use server-side tracking for sensitive data
+### ❌ Don't
+- Track personally identifiable information (PII)
+- Send excessive events (rate limits)
+- Track every click/interaction
+- Use inconsistent event naming
+- Forget to test in GTM preview
+- Ignore GDPR/privacy regulations
+- Track user input values directly
+## Common Patterns
+### Track Form Conversions
+```typescript
+<ContactForm
+  fields={[...]}
+  onSubmit={async (data) => {
+    // Track form start
+    trackEvent('form_start', { form_id: 'contact' });
+    try {
+      await submitForm(data);
+      // Track successful submission
+      trackEvent('form_submit', {
+        form_id: 'contact',
+        form_name: 'Contact Form'
+      });
+      // Track as conversion
+      trackEvent('generate_lead', {
+        lead_source: 'contact_form'
+      });
+    } catch (error) {
+      // Track error
+      trackEvent('form_error', {
+        form_id: 'contact',
+        error: error.message
+      });
+    }
+  }}
+/>
+```
+### Track Video Engagement
+```typescript
+<video
+  onPlay={() => trackEvent('video_play', { video_title: 'Demo' })}
+  onPause={() => trackEvent('video_pause', { video_title: 'Demo' })}
+  onEnded={() => trackEvent('video_complete', { video_title: 'Demo' })}
+/>
+```
+### Track Search
+```typescript
+function SearchBar() {
+  const [query, setQuery] = useState('');
+  const handleSearch = () => {
+    trackEvent('search', {
+      search_term: query,
+      search_location: 'header'
+    });
+  };
+  return <input onChange={e => setQuery(e.target.value)} onSubmit={handleSearch} />;
+}
+```
+## Related Documentation
+- **[AnalyticsTracker](../components/utilities/AnalyticsTracker.md)** - Component API
+- **[TrackedLink](../components/utilities/TrackedLink.md)** - Link tracking
+- **[A/B Testing](./ab-testing.md)** - Experimentation setup
+## API Reference
+Full analytics utilities: **[API Reference](../api/utilities.md#analytics)**