@zoyth/simple-site-framework 1.0.0

package/docs/features/performance/bundle-size.md

@@ -0,0 +1,134 @@
+# Bundle Size
+
+Minimize JavaScript sent to the browser.
+
+## Why Bundle Size Matters
+
+Every kilobyte of JavaScript:
+- Must be downloaded (affects slow connections)
+- Must be parsed and compiled (affects slow devices)
+- Delays interactivity (affects FID/INP metrics)
+
+## Framework Bundle Impact
+
+The framework minimizes client-side JavaScript through Server Components:
+
+| Component Type | Client JS Impact |
+|---------------|-----------------|
+| Server Components (most) | 0 KB |
+| Client Components (interactive) | Varies |
+
+### Zero-JS Components
+
+These ship no JavaScript to the browser:
+- HeroSection, FeaturesGrid, ServicesSection
+- ContactSection, AboutSection, CTASection
+- Header, Footer, Card, Button
+- SEOMetaTags, StructuredData, I18nMetaTags
+
+### Client Components
+
+These add to the bundle:
+- AnalyticsTracker, TrackedLink
+- AnimatedSection, AnimatedCounter
+- ExitIntentModal, CountdownTimer
+- ContactForm (validation, submission)
+- LanguageSelector (interaction)
+
+## Measuring Bundle Size
+
+### Next.js Build Output
+
+```bash
+npm run build
+```
+
+Check the output for page sizes:
+
+```
+Route (app)                    Size     First Load JS
+┌ ○ /                          5.2 kB   89 kB
+├ ○ /about                     1.8 kB   85.6 kB
+├ ○ /services                  3.1 kB   87 kB
+└ ○ /contact                   4.5 kB   88.3 kB
+```
+
+### Bundle Analyzer
+
+```bash
+npm install @next/bundle-analyzer
+
+# Run analysis
+ANALYZE=true npm run build
+```
+
+### Import Cost (VS Code)
+
+Install the "Import Cost" extension to see package sizes inline.
+
+## Reducing Bundle Size
+
+### 1. Audit Imports
+
+```typescript
+// ❌ Bad - imports entire library
+import _ from 'lodash';
+_.debounce(fn, 300);
+
+// ✅ Good - imports only what's needed
+import debounce from 'lodash/debounce';
+debounce(fn, 300);
+```
+
+### 2. Replace Heavy Libraries
+
+| Heavy Library | Lighter Alternative |
+|--------------|-------------------|
+| moment.js (300KB) | date-fns or native Intl |
+| lodash (70KB) | Individual lodash functions |
+| jQuery (90KB) | Native DOM APIs |
+
+### 3. Dynamic Import Heavy Dependencies
+
+```typescript
+// Only load when needed
+const { default: heavyLib } = await import('heavy-library');
+```
+
+### 4. Use Server Components
+
+Move data fetching and rendering to the server:
+
+```typescript
+// ✅ Server Component - no client JS
+export default async function Page() {
+  const data = await fetchData();
+  return <DataDisplay data={data} />;
+}
+```
+
+### 5. Check for Duplicates
+
+Multiple versions of the same package inflate bundles:
+
+```bash
+# Check for duplicates
+npm ls react
+npm ls react-dom
+```
+
+## Budget Guidelines
+
+Suggested bundle size budgets:
+
+| Metric | Budget |
+|--------|--------|
+| Total JS (initial load) | < 100 KB (gzipped) |
+| Per-page JS | < 30 KB (gzipped) |
+| Largest single dependency | < 50 KB (gzipped) |
+
+## See Also
+
+- [Code Splitting](./code-splitting.md)
+- [Monitoring](./monitoring.md)
+- [Existing Performance Documentation](../../PERFORMANCE.md)

package/docs/features/performance/caching.md

@@ -0,0 +1,131 @@
+# Caching
+
+Caching strategies for faster page delivery.
+
+## Static Generation (Default)
+
+By default, Next.js App Router statically generates pages at build time:
+
+```typescript
+// This page is static - generated once at build time
+export default function AboutPage() {
+  return (
+    <HeroSection heading="About Us" />
+  );
+}
+```
+
+Static pages are served from CDN with no server computation.
+
+## Revalidation
+
+For content that changes periodically:
+
+### Time-Based Revalidation
+
+```typescript
+// Revalidate every hour
+export const revalidate = 3600;
+
+export default async function BlogPage() {
+  const posts = await getPosts();
+  return <BlogList posts={posts} />;
+}
+```
+
+### On-Demand Revalidation
+
+Revalidate when content changes:
+
+```typescript
+// app/api/revalidate/route.ts
+import { revalidatePath } from 'next/cache';
+
+export async function POST(request: Request) {
+  const { path } = await request.json();
+  revalidatePath(path);
+  return Response.json({ revalidated: true });
+}
+```
+
+## Fetch Caching
+
+Next.js caches fetch requests by default:
+
+```typescript
+// Cached indefinitely (static)
+const data = await fetch('https://api.example.com/data');
+
+// Revalidate every 60 seconds
+const data = await fetch('https://api.example.com/data', {
+  next: { revalidate: 60 },
+});
+
+// Never cache
+const data = await fetch('https://api.example.com/data', {
+  cache: 'no-store',
+});
+```
+
+## Browser Caching
+
+### Cache Headers
+
+Configure in next.config.js:
+
+```typescript
+module.exports = {
+  async headers() {
+    return [
+      {
+        source: '/images/:path*',
+        headers: [
+          {
+            key: 'Cache-Control',
+            value: 'public, max-age=31536000, immutable',
+          },
+        ],
+      },
+      {
+        source: '/:path*',
+        headers: [
+          {
+            key: 'Cache-Control',
+            value: 'public, max-age=0, must-revalidate',
+          },
+        ],
+      },
+    ];
+  },
+};
+```
+
+### Asset Caching
+
+Next.js automatically:
+- Hashes static assets (JS, CSS) for cache busting
+- Sets long cache headers on hashed files
+- Serves images through optimized pipeline
+
+## CDN Caching
+
+When deployed to Vercel or similar platforms:
+- Static pages cached at edge globally
+- API routes cached based on headers
+- Images optimized and cached at edge
+
+## Caching Strategy by Content Type
+
+| Content Type | Strategy | Revalidation |
+|-------------|----------|--------------|
+| Static pages (About, Contact) | Static generation | On deploy |
+| Blog posts | ISR | Every 1-24 hours |
+| Dynamic data (prices, stock) | No cache or short ISR | 1-5 minutes |
+| Images | Long cache | On change |
+| JS/CSS bundles | Immutable | On deploy (hashed) |
+
+## See Also
+
+- [Code Splitting](./code-splitting.md)
+- [Monitoring](./monitoring.md)
+- [Next.js Caching Documentation](https://nextjs.org/docs/app/building-your-application/caching)

package/docs/features/performance/code-splitting.md

@@ -0,0 +1,121 @@
+# Code Splitting
+
+Split JavaScript bundles for faster initial page loads.
+
+## Automatic Code Splitting
+
+Next.js automatically splits code by route. Each page only loads the JavaScript it needs.
+
+```
+/              → homepage bundle
+/about         → about bundle
+/services      → services bundle
+```
+
+Users visiting `/about` don't download JavaScript for `/services`.
+
+## Server vs Client Components
+
+The most impactful code splitting is the Server/Client component split:
+
+```typescript
+// Server Component (default) - ZERO client JS
+import { HeroSection } from '@zoyth/simple-site-framework/components';
+
+// Client Component - adds to client bundle
+'use client';
+import { AnalyticsTracker } from '@zoyth/simple-site-framework/client';
+```
+
+Most framework components are Server Components, keeping the client bundle small.
+
+## Dynamic Imports
+
+Load heavy components on demand:
+
+```typescript
+import dynamic from 'next/dynamic';
+
+// Only loaded when rendered
+const HeavyChart = dynamic(() => import('../components/HeavyChart'), {
+  loading: () => <Skeleton height={300} />,
+});
+
+// Only loaded on client (no SSR)
+const InteractiveMap = dynamic(() => import('../components/Map'), {
+  ssr: false,
+  loading: () => <Skeleton height={400} />,
+});
+```
+
+## When to Use Dynamic Imports
+
+**Good candidates:**
+- Charts and data visualizations
+- Rich text editors
+- Maps
+- Video players
+- Code editors
+- Large forms not immediately visible
+
+**Don't dynamically import:**
+- Above-the-fold content
+- Navigation components
+- Small, frequently-used components
+
+## Lazy Loading Routes
+
+For rarely-visited routes, use dynamic routes:
+
+```typescript
+// app/admin/page.tsx - only loaded when visiting /admin
+export default function AdminPage() {
+  // Admin-specific code stays in this bundle
+}
+```
+
+## Analyzing Bundle Size
+
+See what's in your bundles:
+
+```bash
+# Build with bundle analyzer
+ANALYZE=true npm run build
+```
+
+Configure in next.config.js:
+
+```typescript
+const withBundleAnalyzer = require('@next/bundle-analyzer')({
+  enabled: process.env.ANALYZE === 'true',
+});
+
+module.exports = withBundleAnalyzer({
+  // Next.js config...
+});
+```
+
+## Framework Import Patterns
+
+### Specific Imports (Recommended)
+
+```typescript
+// ✅ Only imports what you use
+import { HeroSection } from '@zoyth/simple-site-framework/components';
+import { trackEvent } from '@zoyth/simple-site-framework/client';
+```
+
+### Barrel Imports
+
+```typescript
+// ⚠️ May include unused code if tree-shaking isn't perfect
+import { HeroSection, FeaturesGrid, ContactSection } from '@zoyth/simple-site-framework/components';
+```
+
+The framework supports tree-shaking, but specific imports are safer.
+
+## See Also
+
+- [Bundle Size](./bundle-size.md)
+- [Lazy Loading](./lazy-loading.md)
+- [LazySection Component](../../components/LazySection.md)

package/docs/features/performance/image-optimization.md

@@ -0,0 +1,110 @@
+# Image Optimization
+
+Serve optimized images for faster page loads.
+
+## Next.js Image Component
+
+Use the built-in Image component for automatic optimization:
+
+```typescript
+import Image from 'next/image';
+
+<Image
+  src="/hero-photo.jpg"
+  alt="Team working together"
+  width={1200}
+  height={600}
+  priority        // Load immediately for above-fold images
+/>
+```
+
+## Priority Images
+
+Mark above-the-fold images as priority to preload them:
+
+```typescript
+// ✅ Hero image - above fold
+<Image src="/hero.jpg" alt="..." width={1200} height={600} priority />
+
+// Regular image - below fold (lazy loaded by default)
+<Image src="/team.jpg" alt="..." width={800} height={400} />
+```
+
+## Responsive Images
+
+Serve different sizes based on viewport:
+
+```typescript
+<Image
+  src="/hero.jpg"
+  alt="Hero image"
+  width={1200}
+  height={600}
+  sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 1200px"
+/>
+```
+
+## Image Formats
+
+Next.js automatically serves modern formats (WebP, AVIF) when supported by the browser. No configuration needed.
+
+## External Images
+
+Configure allowed domains for external images:
+
+```typescript
+// next.config.js
+module.exports = {
+  images: {
+    remotePatterns: [
+      {
+        protocol: 'https',
+        hostname: 'images.unsplash.com',
+      },
+      {
+        protocol: 'https',
+        hostname: 'cdn.example.com',
+      },
+    ],
+  },
+};
+```
+
+## Background Images
+
+For CSS background images, optimize manually:
+
+```css
+.hero {
+  background-image: url('/hero-bg.webp');
+  background-size: cover;
+}
+```
+
+Or use a picture element for responsive backgrounds.
+
+## Image Sizing Guidelines
+
+| Usage | Recommended Size | Format |
+|-------|-----------------|--------|
+| Hero banner | 1920 x 1080 | JPEG/WebP |
+| Card thumbnail | 400 x 300 | JPEG/WebP |
+| Logo | 200 x 60 | SVG/PNG |
+| Icon | 24 x 24 to 48 x 48 | SVG |
+| Open Graph | 1200 x 630 | JPEG/PNG |
+| Favicon | 32 x 32 | ICO/PNG |
+
+## Best Practices
+
+- Always set `width` and `height` to prevent layout shift (CLS)
+- Use `priority` for above-fold images only
+- Use `sizes` prop for responsive layouts
+- Prefer SVG for logos and icons
+- Compress images before adding to project
+- Use descriptive alt text for accessibility and SEO
+
+## See Also
+
+- [Lazy Loading](./lazy-loading.md)
+- [Bundle Size](./bundle-size.md)
+- [Next.js Image Documentation](https://nextjs.org/docs/app/api-reference/components/image)

package/docs/features/performance/lazy-loading.md

@@ -0,0 +1,92 @@
+# Lazy Loading
+
+Defer loading of non-critical content for faster initial page load.
+
+## LazySection Component
+
+Wrap sections that appear below the fold:
+
+```typescript
+import { LazySection } from '@zoyth/simple-site-framework/components';
+
+export default function HomePage() {
+  return (
+    <>
+      {/* Above fold - loads immediately */}
+      <HeroSection heading="Welcome" />
+
+      {/* Below fold - lazy loaded on scroll */}
+      <LazySection>
+        <FeaturesGrid features={features} />
+      </LazySection>
+
+      <LazySection>
+        <TestimonialSection testimonials={testimonials} />
+      </LazySection>
+
+      <LazySection>
+        <ContactSection />
+      </LazySection>
+    </>
+  );
+}
+```
+
+## How It Works
+
+LazySection uses Intersection Observer to detect when content enters the viewport. The wrapped content is rendered only when it becomes visible (or is about to become visible).
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | - | Content to lazy load |
+| `threshold` | `number` | `0.1` | Visibility threshold (0-1) before loading |
+| `rootMargin` | `string` | `'200px'` | Margin around viewport to preload |
+| `fallback` | `ReactNode` | `null` | Placeholder while loading |
+
+## With Skeleton Loading
+
+Show placeholder while content loads:
+
+```typescript
+<LazySection fallback={<Skeleton height={400} />}>
+  <TestimonialSection testimonials={testimonials} />
+</LazySection>
+```
+
+## Dynamic Imports
+
+For heavy client components, combine with Next.js dynamic imports:
+
+```typescript
+import dynamic from 'next/dynamic';
+
+const HeavyChart = dynamic(() => import('./HeavyChart'), {
+  loading: () => <Skeleton height={300} />,
+  ssr: false,
+});
+
+<LazySection>
+  <HeavyChart data={data} />
+</LazySection>
+```
+
+## When to Use
+
+**Use LazySection for:**
+- Content below the initial viewport
+- Heavy sections with many images
+- Sections with complex animations
+- Testimonial carousels, image galleries
+
+**Don't use LazySection for:**
+- Hero section (above fold)
+- Critical navigation elements
+- Content needed for SEO (search engines may not scroll)
+
+## See Also
+
+- [LazySection Component](../../components/LazySection.md)
+- [Skeleton Component](../../components/Skeleton.md)
+- [Code Splitting](./code-splitting.md)