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/getting-started/installation.md ADDED Viewed

@@ -0,0 +1,292 @@
+# Installation
+This guide covers adding Simple Site Framework to an existing Next.js project or creating a new project from scratch.
+## Prerequisites
+Before installing, ensure you have:
+- **Node.js** 18.x or later
+- **npm** 9.x or later (or yarn/pnpm equivalent)
+- **Next.js** 14.x or later with App Router
+- **React** 18.x or 19.x
+- **TypeScript** 5.x (recommended but not required)
+## Quick Install (New Project)
+The fastest way to start is with the CLI scaffolding tool:
+```bash
+npx @zoyth/simple-site-framework create my-site
+cd my-site
+npm install
+npm run dev
+```
+This creates a complete Next.js project with all framework dependencies configured, sample configs, and example pages.
+Skip to **[Quick Start Guide](./quick-start.md)** if you used this method.
+## Manual Installation (Existing Project)
+### 1. Install the Framework
+```bash
+npm install @zoyth/simple-site-framework
+```
+### 2. Install Peer Dependencies
+The framework requires these peer dependencies:
+```bash
+npm install next@14 react@19 react-dom@19
+npm install tailwindcss@4 @tailwindcss/postcss
+```
+**Tailwind CSS:** Both v3.4+ and v4.x are fully supported. The framework uses standard utility classes that work across versions.
+### 3. Install Optional Dependencies
+For full functionality, install these recommended packages:
+```bash
+# For forms with validation
+npm install react-hook-form @hookform/resolvers zod
+# For animations (optional)
+npm install framer-motion
+# For analytics tracking (optional)
+npm install @vercel/analytics
+```
+## Configure Tailwind CSS
+### 1. Initialize Tailwind (if not already done)
+```bash
+npx tailwindcss init -p --ts
+```
+### 2. Update `tailwind.config.ts`
+Your Tailwind config **must** include the framework components in the `content` array:
+```typescript
+import type { Config } from 'tailwindcss';
+const config: Config = {
+  content: [
+    './src/**/*.{js,ts,jsx,tsx,mdx}',
+    // ⚠️ REQUIRED: Include framework components
+    './node_modules/@zoyth/simple-site-framework/dist/**/*.{js,mjs}',
+  ],
+  theme: {
+    extend: {
+      colors: {
+        // Define colors that match your theme config
+        primary: '#F16531',
+        'primary-hover': '#D9551C',
+        secondary: '#2D3748',
+        'secondary-hover': '#1A202C',
+        accent: '#F59E0B',
+        'warm-gray': '#F8FAFC',
+      },
+      fontFamily: {
+        heading: ['var(--font-heading)', 'serif'],
+        body: ['var(--font-body)', 'sans-serif'],
+      },
+      backgroundImage: {
+        'brand-gradient-light': 'linear-gradient(to bottom, #F8FAFC, #FFFFFF)',
+        'hero-gradient': 'linear-gradient(135deg, #2D3748, #1A202C)',
+        'footer-gradient-orange': 'linear-gradient(135deg, #F37840, #D85620)',
+      },
+    },
+  },
+};
+export default config;
+```
+**Important:** The framework's components use custom theme tokens. If you skip this step, your site will render but look unstyled. See **[Troubleshooting](../../TROUBLESHOOTING.md)** for details.
+### 3. Configure Fonts (Optional but Recommended)
+Use Next.js's `next/font` for optimal font loading:
+```typescript
+// src/app/layout.tsx
+import { Playfair_Display, Inter } from 'next/font/google';
+const playfair = Playfair_Display({
+  subsets: ['latin'],
+  variable: '--font-heading',
+  display: 'swap',
+});
+const inter = Inter({
+  subsets: ['latin'],
+  variable: '--font-body',
+  display: 'swap',
+});
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en" className={`${playfair.variable} ${inter.variable}`}>
+      <body className="font-body">{children}</body>
+    </html>
+  );
+}
+```
+## Setup Internationalization (Optional)
+If you need multi-language support, create an i18n configuration:
+### 1. Create i18n Config
+```typescript
+// src/config/i18n.ts
+import type { I18nConfig } from '@zoyth/simple-site-framework';
+export const i18nConfig: I18nConfig = {
+  locales: ['en', 'fr'], // Your supported languages
+  defaultLocale: 'en',
+  localePrefix: 'as-needed', // Default locale has no prefix in URL
+  localeDetection: true, // Auto-detect browser language
+  localeNames: {
+    en: 'English',
+    fr: 'Français',
+  },
+};
+```
+### 2. Create Middleware
+```typescript
+// src/middleware.ts
+import { createI18nMiddleware } from '@zoyth/simple-site-framework/lib/i18n';
+import { i18nConfig } from './config/i18n';
+export default createI18nMiddleware(i18nConfig);
+export const config = {
+  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
+};
+```
+### 3. Update App Structure
+For multi-language sites, use Next.js dynamic routing:
+```
+src/app/
+  [locale]/
+    layout.tsx
+    page.tsx
+    about/
+      page.tsx
+```
+See **[Internationalization Guide](../features/internationalization.md)** for complete setup instructions.
+## Verify Installation
+Create a test page to ensure everything works:
+```typescript
+// src/app/page.tsx
+import { HeroSection } from '@zoyth/simple-site-framework';
+export default function HomePage() {
+  return (
+    <HeroSection
+      heading="Welcome to My Site"
+      description="Built with Simple Site Framework"
+      cta={{
+        text: 'Get Started',
+        href: '/contact'
+      }}
+      variant="centered"
+    />
+  );
+}
+```
+Run the development server:
+```bash
+npm run dev
+```
+Visit `http://localhost:3000` - you should see a styled hero section.
+## Troubleshooting
+### Components Render Without Styling
+**Cause:** Tailwind CSS isn't scanning the framework's components, or custom theme tokens are missing.
+**Solution:**
+1. Verify `tailwind.config.ts` includes the framework in `content` array
+2. Define required theme tokens (colors, fonts, gradients)
+3. Restart dev server after config changes
+See **[TROUBLESHOOTING.md](../../TROUBLESHOOTING.md)** for detailed debugging.
+### TypeScript Errors
+**Cause:** Missing type definitions or incompatible versions.
+**Solution:**
+1. Ensure TypeScript 5.x is installed: `npm install -D typescript@5`
+2. Check Next.js is v14+: `npm list next`
+3. Restart TypeScript server in your editor
+### Build Errors with "use client" Directives
+**Cause:** Importing client-only components from server components.
+**Solution:**
+- Import analytics/client-only utilities from `/client`:
+  ```typescript
+  import { AnalyticsTracker } from '@zoyth/simple-site-framework/client';
+  ```
+- Server-safe components come from main export:
+  ```typescript
+  import { HeroSection } from '@zoyth/simple-site-framework';
+  ```
+See **[Server/Client Split](../core-concepts/server-client-split.md)** for details.
+## Next Steps
+Now that installation is complete:
+- **[Quick Start →](./quick-start.md)** - Build your first page in 5 minutes
+- **[First Project →](./first-project.md)** - Complete tutorial
+- **[Configuration →](../core-concepts/configuration-driven.md)** - Learn the configuration approach
+- **[Components →](../components/overview.md)** - Explore available components
+## Package Information
+```json
+{
+  "name": "@zoyth/simple-site-framework",
+  "version": "0.1.0",
+  "peerDependencies": {
+    "next": "^14.0.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "tailwindcss": "^3.4.0 || ^4.0.0"
+  },
+  "dependencies": {
+    "clsx": "^2.1.1",
+    "tailwind-merge": "^3.4.0",
+    "rehype-slug": "^6.0.0"
+  }
+}
+```
+**Note:** The framework has minimal dependencies. Heavy packages like `framer-motion`, `react-hook-form`, and `zod` are peer dependencies - install only what you need.

package/docs/getting-started/introduction.md ADDED Viewed

@@ -0,0 +1,195 @@
+# Introduction to Simple Site Framework
+Simple Site Framework is a configuration-driven React framework built on Next.js, designed specifically for professional service websites, SaaS landing pages, and marketing sites that need to convert visitors into customers.
+## What is Simple Site Framework?
+Unlike traditional component libraries that give you isolated pieces, Simple Site Framework provides:
+- **Complete page sections** ready to use (Hero, Services, Testimonials, Contact, etc.)
+- **Configuration-first approach** - define your content and theme in simple config files
+- **Built-in internationalization** - support any number of languages with minimal setup
+- **Production-ready components** - battle-tested on real commercial websites
+- **Type-safe everything** - full TypeScript support with comprehensive type definitions
+- **Accessibility by default** - WCAG 2.1 AA compliant out of the box
+- **Performance optimized** - lazy loading, code splitting, and efficient animations
+## Who Is This For?
+This framework is ideal for:
+- **Agencies** building multiple professional service websites
+- **SaaS companies** creating high-converting landing pages
+- **Solo developers** who want to ship faster without sacrificing quality
+- **Teams** needing consistent, maintainable site architecture
+- **Projects** requiring multi-language support from day one
+## Philosophy
+### Configuration Over Code
+Instead of writing component markup repeatedly, you define your site in configuration files:
+```typescript
+// src/config/site.ts
+export const siteConfig = {
+  name: 'Acme Corp',
+  description: 'Professional consulting services',
+  theme: {
+    primaryColor: '#F16531',
+    fontHeading: 'Playfair Display',
+    fontBody: 'Inter',
+  }
+};
+```
+The framework handles rendering, responsive design, accessibility, and performance automatically.
+### Progressive Enhancement
+Start simple, add complexity only when needed:
+1. **Level 1:** Use pre-built sections with default styling
+2. **Level 2:** Customize with your own content and theme
+3. **Level 3:** Override individual component props for specific needs
+4. **Level 4:** Create custom variants while keeping the framework's benefits
+### Type Safety First
+Every configuration option, prop, and utility function is fully typed:
+```typescript
+import type { SiteConfig, ThemeConfig, LocalizedString } from '@zoyth/simple-site-framework';
+const content: LocalizedString = {
+  en: 'Get Started',
+  fr: 'Commencer'
+};
+```
+TypeScript catches configuration errors at build time, not at runtime.
+## Core Features
+### 35+ Production-Ready Components
+- **Layout:** Header, Footer, LanguageSelector
+- **Sections:** Hero, About, Services, Testimonials, Contact, CTA
+- **UI:** Button, Card, Input, Modal, Tabs, Breadcrumb
+- **Forms:** ContactForm, FormField, validation with React Hook Form + Zod
+- **Conversion:** MobileCTA, CTASection, LiveProof
+- **Accessibility:** SkipLink, A11yAnnouncer, ARIA-enhanced form components
+### Flexible Internationalization
+Support 1, 2, or 20+ languages with the same code:
+```typescript
+// Single language - no routing overhead
+{ locales: ['en'], defaultLocale: 'en' }
+// Bilingual with simple toggle
+{ locales: ['en', 'fr'], defaultLocale: 'en' }
+// Multi-language with dropdown selector
+{ locales: ['en', 'fr', 'es', 'de', 'ja'], defaultLocale: 'en' }
+```
+The framework automatically handles:
+- URL routing based on locale
+- Language detection from browser preferences
+- Cookie persistence of user's choice
+- SEO meta tags (hreflang, canonical, etc.)
+### Theme System
+Define your brand once, apply it everywhere:
+```typescript
+export const themeConfig: ThemeConfig = {
+  colors: {
+    primary: '#F16531',
+    secondary: '#2D3748',
+  },
+  fonts: {
+    heading: 'Playfair Display',
+    body: 'Inter',
+  },
+  animations: {
+    hero: 'fade-up',
+    sections: 'slide-in',
+  }
+};
+```
+All components automatically use your theme tokens, ensuring consistency.
+### Built for Next.js 14+
+The framework is specifically optimized for Next.js App Router:
+- **Server Components** by default for better performance
+- **Client Components** where needed (forms, animations, analytics)
+- **Proper exports** - server-safe code in main export, client-only in `/client`
+- **Streaming-friendly** - no blocking JavaScript requirements
+- **SEO optimized** - server-rendered content with proper meta tags
+## What Sets This Apart?
+### Not Just Components
+Most frameworks give you `<Button>` and `<Card>` and leave you to figure out layout, content structure, and responsive design. Simple Site Framework gives you complete, production-ready sections:
+```typescript
+<HeroSection
+  heading={{ en: 'Transform Your Business', fr: 'Transformez votre entreprise' }}
+  description={{ en: 'Professional consulting...', fr: 'Services de conseil...' }}
+  cta={{
+    text: { en: 'Get Started', fr: 'Commencer' },
+    href: '/contact'
+  }}
+  backgroundImage="/hero-bg.jpg"
+  variant="centered"
+  locale={locale}
+/>
+```
+### Battle-Tested in Production
+Every component and pattern in this framework has been used in real commercial websites:
+- **MobileCTA** - Improved mobile conversions on courrielleur.com
+- **CTASection** - Used across 5+ pages with proven conversion patterns
+- **LiveProof** - Social proof notifications that build trust
+- **ContactForm** - Handles thousands of leads with validation and accessibility
+### Configuration-Driven Consistency
+When you have multiple pages or multiple projects, consistency matters. With configuration files, you can't accidentally use the wrong font or color:
+```typescript
+// All buttons automatically use your theme
+<Button variant="filled" /> // Uses theme.colors.primary
+// All headings use your font
+<h1 className="font-heading"> // Uses theme.fonts.heading
+```
+## Next Steps
+Ready to get started? Choose your path:
+- **[Installation →](./installation.md)** - Add to an existing Next.js project
+- **[Quick Start →](./quick-start.md)** - Create a new project in 5 minutes
+- **[First Project →](./first-project.md)** - Step-by-step tutorial
+- **[Core Concepts →](../core-concepts/overview.md)** - Understand the architecture
+## Community and Support
+- **GitHub Issues:** Bug reports and feature requests
+- **Documentation:** Comprehensive guides and API reference
+- **Examples:** Real-world usage patterns and templates
+---
+**Note:** This framework is actively developed and used in production. While the API is stable, we're continuously adding features and improvements based on real-world usage.