@zoyth/simple-site-framework 1.0.0

package/docs/features/performance/monitoring.md

@@ -0,0 +1,148 @@
+# Performance Monitoring
+
+Measure, track, and improve site performance.
+
+## Core Web Vitals
+
+The three metrics Google uses for page experience ranking:
+
+### LCP (Largest Contentful Paint)
+
+Time until the largest visible content element renders.
+
+| Rating | Threshold |
+|--------|-----------|
+| Good | < 2.5s |
+| Needs Improvement | 2.5s - 4.0s |
+| Poor | > 4.0s |
+
+**Improve LCP:**
+- Use `priority` on hero images
+- Preload critical fonts
+- Minimize render-blocking resources
+
+### FID / INP (First Input Delay / Interaction to Next Paint)
+
+Time from user interaction to browser response.
+
+| Rating | Threshold |
+|--------|-----------|
+| Good | < 100ms (FID) / < 200ms (INP) |
+| Needs Improvement | 100-300ms / 200-500ms |
+| Poor | > 300ms / > 500ms |
+
+**Improve FID/INP:**
+- Minimize client-side JavaScript
+- Use Server Components
+- Break up long tasks
+
+### CLS (Cumulative Layout Shift)
+
+Visual stability - how much content shifts during load.
+
+| Rating | Threshold |
+|--------|-----------|
+| Good | < 0.1 |
+| Needs Improvement | 0.1 - 0.25 |
+| Poor | > 0.25 |
+
+**Improve CLS:**
+- Set explicit width/height on images
+- Reserve space for dynamic content
+- Avoid inserting content above existing content
+
+## Measurement Tools
+
+### Google PageSpeed Insights
+
+Test any URL:
+- [PageSpeed Insights](https://pagespeed.web.dev/)
+- Provides both lab and field data
+- Actionable recommendations
+
+### Chrome DevTools Lighthouse
+
+1. Open DevTools (F12)
+2. Go to Lighthouse tab
+3. Select "Performance"
+4. Run audit
+
+### Google Search Console
+
+Monitor real-user data:
+1. Search Console > Core Web Vitals
+2. See URL-level performance
+3. Track improvements over time
+
+### Chrome DevTools Performance Tab
+
+Detailed analysis:
+1. Open DevTools > Performance
+2. Click Record
+3. Interact with page
+4. Stop recording
+5. Analyze flame chart
+
+## Web Vitals in Code
+
+Track Core Web Vitals programmatically:
+
+```typescript
+// app/layout.tsx
+import { useReportWebVitals } from 'next/web-vitals';
+
+export function WebVitalsReporter() {
+  useReportWebVitals((metric) => {
+    // Send to analytics
+    trackEvent('web_vital', {
+      name: metric.name,       // CLS, FID, LCP, etc.
+      value: metric.value,
+      rating: metric.rating,   // good, needs-improvement, poor
+    });
+  });
+
+  return null;
+}
+```
+
+## Performance Budgets
+
+Set budgets and alert when exceeded:
+
+```typescript
+// next.config.js
+module.exports = {
+  experimental: {
+    // Warn when page JS exceeds budget
+    largePageDataBytes: 128 * 1000, // 128KB
+  },
+};
+```
+
+## Monitoring Checklist
+
+### Weekly
+
+- [ ] Check Core Web Vitals in Search Console
+- [ ] Review PageSpeed Insights for key pages
+- [ ] Check build output for bundle size changes
+
+### Per Release
+
+- [ ] Run Lighthouse on key pages
+- [ ] Compare bundle sizes with previous build
+- [ ] Test on slow network (Chrome DevTools > Network > Slow 3G)
+- [ ] Test on low-end device simulation
+
+### Monthly
+
+- [ ] Review real-user performance data
+- [ ] Identify pages with poor metrics
+- [ ] Plan performance improvements
+- [ ] Update performance budgets if needed
+
+## See Also
+
+- [Bundle Size](./bundle-size.md)
+- [Lazy Loading](./lazy-loading.md)
+- [Existing Performance Documentation](../../PERFORMANCE.md)

package/docs/features/seo/README.md

@@ -0,0 +1,51 @@
+# SEO
+
+Search engine optimization tools and components.
+
+## Overview
+
+Simple Site Framework provides built-in SEO support:
+
+- Meta tag management
+- Structured data (Schema.org)
+- XML sitemap generation
+- Open Graph / social media previews
+- Canonical URL management
+- Multi-language SEO (hreflang)
+
+## Quick Start
+
+```typescript
+import { SEOMetaTags, StructuredData } from '@zoyth/simple-site-framework/components';
+
+<SEOMetaTags
+  title="My Page"
+  description="Page description for search results"
+  canonical="https://example.com/page"
+/>
+
+<StructuredData
+  data={{
+    '@type': 'Organization',
+    name: 'My Company',
+    url: 'https://example.com',
+  }}
+/>
+```
+
+## Topics
+
+- [Meta Tags](./meta-tags.md) - Title, description, and meta tags
+- [Structured Data](./structured-data.md) - Schema.org JSON-LD markup
+- [Sitemaps](./sitemaps.md) - XML sitemap generation
+- [Open Graph](./open-graph.md) - Social media preview cards
+- [Robots.txt](./robots-txt.md) - Search engine crawl rules
+- [Canonical URLs](./canonical-urls.md) - Canonical URL management
+- [Best Practices](./best-practices.md) - SEO optimization tips
+
+## See Also
+
+- [SEO Optimization Guide](../../guides/seo-optimization.md)
+- [SEOMetaTags Component](../../components/SEOMetaTags.md)
+- [StructuredData Component](../../components/StructuredData.md)
+- [Existing SEO Documentation](../../SEO.md)

package/docs/features/seo/best-practices.md

@@ -0,0 +1,184 @@
+# SEO Best Practices
+
+Optimization guidelines for search engine visibility.
+
+## Technical SEO Checklist
+
+### Must Have
+
+- [ ] Unique title and description per page
+- [ ] Canonical URLs on all pages
+- [ ] XML sitemap submitted to Search Console
+- [ ] robots.txt configured
+- [ ] HTTPS enabled
+- [ ] Mobile-responsive design
+- [ ] Fast page load times
+
+### Recommended
+
+- [ ] Structured data (Schema.org) on key pages
+- [ ] Open Graph tags for social sharing
+- [ ] hreflang tags for multi-language sites
+- [ ] Breadcrumb navigation with structured data
+- [ ] Image alt text on all images
+- [ ] Internal linking between related pages
+
+## Page Speed
+
+Search engines favor fast sites. Use framework performance features:
+
+```typescript
+import { LazySection } from '@zoyth/simple-site-framework/components';
+
+// Lazy-load below-the-fold sections
+<LazySection>
+  <TestimonialSection testimonials={testimonials} />
+</LazySection>
+```
+
+Key metrics:
+- **LCP** (Largest Contentful Paint): < 2.5s
+- **FID** (First Input Delay): < 100ms
+- **CLS** (Cumulative Layout Shift): < 0.1
+
+## Content Optimization
+
+### Headings
+
+Use proper heading hierarchy:
+
+```tsx
+<h1>Main Page Title</h1>        {/* One per page */}
+  <h2>Section Title</h2>        {/* Major sections */}
+    <h3>Sub-section</h3>         {/* Sub-sections */}
+```
+
+### Internal Linking
+
+Link related content to distribute page authority:
+
+```typescript
+<TrackedLink href="/services/tax-preparation">
+  Learn about our tax services
+</TrackedLink>
+```
+
+### Image SEO
+
+Always include descriptive alt text:
+
+```tsx
+<img
+  src="/team-photo.jpg"
+  alt="Our accounting team in the Montreal office"
+  width={800}
+  height={600}
+/>
+```
+
+## URL Structure
+
+### Clean URLs
+
+```
+✅ /services/tax-preparation
+✅ /about
+✅ /blog/getting-started-guide
+
+❌ /page?id=123
+❌ /services/tax_preparation_page_v2
+❌ /p/123/svc
+```
+
+### Locale URLs
+
+```
+✅ /fr/services/preparation-impots   (French)
+✅ /services/tax-preparation          (English default)
+```
+
+## Multi-Language SEO
+
+### Required Tags
+
+```typescript
+// On every localized page
+<SEOMetaTags
+  title={localizedTitle}
+  description={localizedDescription}
+  canonical={canonicalUrl}
+/>
+
+<I18nMetaTags
+  currentLocale={locale}
+  pathname={pathname}
+  baseUrl="https://example.com"
+/>
+```
+
+### Separate Content
+
+Each locale should have unique, translated content - not machine-translated copies.
+
+### Localized URLs
+
+Use translated slugs when possible:
+
+```
+/en/services/tax-preparation
+/fr/services/preparation-impots
+```
+
+## Common SEO Mistakes
+
+### Duplicate Content
+
+- Missing canonical tags
+- Same content on multiple URLs
+- HTTP and HTTPS both accessible
+- www and non-www both accessible
+
+### Missing Meta Tags
+
+- No meta description (search engine generates one)
+- Generic titles ("Home", "Page 1")
+- Same title on every page
+
+### Poor Mobile Experience
+
+- Non-responsive layouts
+- Small tap targets
+- Content wider than viewport
+- Interstitials blocking content
+
+### Slow Performance
+
+- Large unoptimized images
+- Blocking JavaScript
+- No lazy loading for below-the-fold content
+- Missing caching headers
+
+## Monitoring
+
+### Google Search Console
+
+- Monitor indexing status
+- Check for crawl errors
+- Review search performance
+- Submit sitemaps
+- Test URLs
+
+### Core Web Vitals
+
+Monitor in:
+- Google Search Console > Core Web Vitals
+- PageSpeed Insights
+- Chrome DevTools > Lighthouse
+
+## See Also
+
+- [Meta Tags](./meta-tags.md)
+- [Structured Data](./structured-data.md)
+- [Sitemaps](./sitemaps.md)
+- [Performance Features](../performance/README.md)
+- [Existing SEO Documentation](../../SEO.md)

package/docs/features/seo/canonical-urls.md

@@ -0,0 +1,182 @@
+# Canonical URLs
+
+Prevent duplicate content issues with canonical URL management.
+
+## Overview
+
+Canonical URLs tell search engines which version of a page is the "official" one, preventing duplicate content penalties when the same content is accessible at multiple URLs.
+
+## Setting Canonical URLs
+
+### Via SEOMetaTags
+
+```typescript
+import { SEOMetaTags } from '@zoyth/simple-site-framework/components';
+
+<SEOMetaTags
+  title="About Us"
+  description="Learn about our company"
+  canonical="https://example.com/about"
+/>
+```
+
+### Via Next.js Metadata
+
+```typescript
+// app/about/page.tsx
+export const metadata = {
+  alternates: {
+    canonical: 'https://example.com/about',
+  },
+};
+```
+
+## When Canonicals Matter
+
+### Trailing Slashes
+
+```
+https://example.com/about
+https://example.com/about/
+```
+
+Set canonical to one version consistently.
+
+### Query Parameters
+
+```
+https://example.com/products
+https://example.com/products?sort=price
+https://example.com/products?page=2
+```
+
+Canonical should point to the base URL (without parameters) unless the parameter creates unique content.
+
+### HTTP vs HTTPS
+
+```
+http://example.com/about
+https://example.com/about
+```
+
+Always canonicalize to HTTPS.
+
+### WWW vs Non-WWW
+
+```
+https://www.example.com/about
+https://example.com/about
+```
+
+Pick one and canonicalize consistently.
+
+## Multi-Language Canonicals
+
+Each locale should have its own canonical:
+
+```typescript
+// English page
+<SEOMetaTags
+  canonical="https://example.com/about"
+/>
+
+// French page
+<SEOMetaTags
+  canonical="https://example.com/fr/about"
+/>
+```
+
+Combined with hreflang tags:
+
+```typescript
+import { I18nMetaTags } from '@zoyth/simple-site-framework/components';
+
+<I18nMetaTags
+  currentLocale={locale}
+  pathname="/about"
+  baseUrl="https://example.com"
+/>
+```
+
+This generates:
+```html
+<link rel="alternate" hreflang="en" href="https://example.com/about" />
+<link rel="alternate" hreflang="fr" href="https://example.com/fr/about" />
+<link rel="alternate" hreflang="x-default" href="https://example.com/about" />
+```
+
+## Dynamic Canonical URLs
+
+Generate canonicals from route parameters:
+
+```typescript
+// app/[locale]/services/[slug]/page.tsx
+export default function ServicePage({ params }) {
+  const { locale, slug } = params;
+  const baseUrl = 'https://example.com';
+  const canonical = locale === 'en'
+    ? `${baseUrl}/services/${slug}`
+    : `${baseUrl}/${locale}/services/${slug}`;
+
+  return (
+    <SEOMetaTags
+      title={service.title}
+      description={service.description}
+      canonical={canonical}
+    />
+  );
+}
+```
+
+## Common Mistakes
+
+### Self-Referencing Canonicals
+
+Every page should have a canonical pointing to itself (this is correct, not a mistake):
+
+```typescript
+// ✅ Good - self-referencing canonical
+<SEOMetaTags canonical="https://example.com/about" />
+// on the page https://example.com/about
+```
+
+### Missing Canonicals
+
+Pages without canonicals may confuse search engines:
+
+```typescript
+// ❌ Bad - no canonical
+<SEOMetaTags title="About" description="..." />
+
+// ✅ Good - always include canonical
+<SEOMetaTags
+  title="About"
+  description="..."
+  canonical="https://example.com/about"
+/>
+```
+
+### Relative URLs
+
+Always use absolute URLs:
+
+```typescript
+// ❌ Bad
+<SEOMetaTags canonical="/about" />
+
+// ✅ Good
+<SEOMetaTags canonical="https://example.com/about" />
+```
+
+## Verification
+
+Check canonical tags in:
+1. Page source (View Source)
+2. Google Search Console > URL Inspection
+3. Browser DevTools > Elements > `<head>`
+
+## See Also
+
+- [Meta Tags](./meta-tags.md)
+- [Sitemaps](./sitemaps.md)
+- [I18nMetaTags Component](../../components/I18nMetaTags.md)

package/docs/features/seo/meta-tags.md

@@ -0,0 +1,126 @@
+# Meta Tags
+
+Configure page titles, descriptions, and meta tags for search engines.
+
+## SEOMetaTags Component
+
+```typescript
+import { SEOMetaTags } from '@zoyth/simple-site-framework/components';
+
+<SEOMetaTags
+  title="About Us | My Company"
+  description="Learn about our team and mission"
+  canonical="https://example.com/about"
+  keywords={['company', 'about', 'team']}
+  robots="index, follow"
+/>
+```
+
+## Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `title` | `string` | Yes | Page title (displayed in browser tab and search results) |
+| `description` | `string` | Yes | Meta description (displayed in search result snippets) |
+| `canonical` | `string` | No | Canonical URL for the page |
+| `keywords` | `string[]` | No | Meta keywords (low SEO value but still used) |
+| `robots` | `string` | No | Robots directive (default: 'index, follow') |
+| `openGraph` | `OpenGraphProps` | No | Open Graph metadata |
+| `twitter` | `TwitterProps` | No | Twitter Card metadata |
+
+## Page Titles
+
+### Format
+
+Follow consistent title patterns:
+
+```typescript
+// Page title | Site name
+<SEOMetaTags title="About Us | My Company" />
+
+// For homepage
+<SEOMetaTags title="My Company - Professional Services" />
+```
+
+### Guidelines
+
+- 50-60 characters maximum
+- Include primary keyword
+- Place important words first
+- Include brand name
+
+## Meta Descriptions
+
+### Guidelines
+
+- 150-160 characters maximum
+- Include target keywords naturally
+- Write compelling copy that encourages clicks
+- Unique per page
+
+```typescript
+<SEOMetaTags
+  description="Get professional accounting services tailored to small businesses. Free consultation available."
+/>
+```
+
+## Robots Directives
+
+Control search engine behavior:
+
+```typescript
+// Default - index and follow links
+<SEOMetaTags robots="index, follow" />
+
+// Don't index but follow links
+<SEOMetaTags robots="noindex, follow" />
+
+// Don't index or follow
+<SEOMetaTags robots="noindex, nofollow" />
+
+// No archive/cache
+<SEOMetaTags robots="index, follow, noarchive" />
+```
+
+## Localized Meta Tags
+
+Use with i18n:
+
+```typescript
+const title = {
+  en: 'About Us | My Company',
+  fr: 'À propos | Mon Entreprise',
+};
+
+const description = {
+  en: 'Learn about our team',
+  fr: 'Découvrez notre équipe',
+};
+
+<SEOMetaTags
+  title={getLocalizedString(title, locale)}
+  description={getLocalizedString(description, locale)}
+/>
+```
+
+## Next.js Metadata API
+
+The framework is compatible with Next.js Metadata:
+
+```typescript
+// app/about/page.tsx
+import type { Metadata } from 'next';
+
+export const metadata: Metadata = {
+  title: 'About Us | My Company',
+  description: 'Learn about our team',
+};
+```
+
+Use whichever approach fits your project. SEOMetaTags provides more dynamic control; Next.js Metadata is static and simpler.
+
+## See Also
+
+- [Open Graph](./open-graph.md)
+- [Canonical URLs](./canonical-urls.md)
+- [SEOMetaTags Component](../../components/SEOMetaTags.md)