@zoyth/simple-site-framework 1.0.0

package/docs/migration/overview.md

@@ -0,0 +1,233 @@
+# Migration Guide Overview
+
+This guide helps you upgrade between versions of the Simple Site Framework smoothly.
+
+## Version Support Policy
+
+### Current Versions
+- **v0.1.x**: Initial release, active development
+- Future versions will follow semantic versioning
+
+### Support Timeline
+- **Major versions** (v1.x, v2.x): 18 months of support
+- **Minor versions** (v0.1.x, v0.2.x): Supported until next minor release
+- **Patch versions** (v0.1.0, v0.1.1): Immediate upgrade recommended
+
+### Long-Term Support (LTS)
+Starting with v1.0, LTS versions will be designated:
+- Security fixes for 18 months
+- Bug fixes for 12 months
+- New features for 6 months
+
+## Semantic Versioning
+
+We follow [Semantic Versioning 2.0.0](https://semver.org/):
+
+- **Major** (v1.0.0 → v2.0.0): Breaking changes
+- **Minor** (v0.1.0 → v0.2.0): New features, backward compatible
+- **Patch** (v0.1.0 → v0.1.1): Bug fixes, backward compatible
+
+## Before You Upgrade
+
+### 1. Check Current Version
+```bash
+npm list @zoyth/simple-site-framework
+```
+
+### 2. Review Breaking Changes
+Read the migration guide for your target version:
+- [v0.1 → v0.2](./v0.1-to-v0.2.md) (when available)
+- [Changelog](./changelog.md)
+
+### 3. Backup Your Code
+```bash
+git commit -am "Pre-upgrade checkpoint"
+git tag pre-upgrade-v0.2
+```
+
+### 4. Update Dependencies
+```bash
+npm install @zoyth/simple-site-framework@latest
+```
+
+### 5. Run Migration Tool (Optional)
+```bash
+npx simple-site migrate
+```
+
+### 6. Test Thoroughly
+- Run your test suite
+- Manual QA on key pages
+- Check for deprecation warnings
+
+## Migration Tools
+
+### Automated Migration
+The framework includes automated migration tools to help with common upgrade scenarios:
+
+```bash
+# Interactive migration
+npx simple-site migrate
+
+# Dry run (see what would change)
+npx simple-site migrate --dry-run
+
+# Migrate to specific version
+npx simple-site migrate --to=0.2.0
+
+# Skip interactive prompts
+npx simple-site migrate --yes
+```
+
+### What Gets Migrated
+- ✅ Component imports
+- ✅ Prop names and values
+- ✅ Config file structure
+- ✅ Deprecated API usage
+- ⚠️ Custom code (manual review needed)
+
+## Deprecation Policy
+
+### Deprecation Process
+1. **Announce**: Deprecation warning added in minor version
+2. **Maintain**: Deprecated feature still works for one major version
+3. **Remove**: Feature removed in next major version
+
+### Example Timeline
+- v0.5: Feature deprecated, warning shown
+- v0.6-0.9: Feature still works, warning continues
+- v1.0: Feature removed
+
+### Handling Deprecations
+```tsx
+// Deprecated in v0.5 - warning in console
+<Button type="primary">Click</Button>
+
+// New API (works in v0.5+)
+<Button variant="filled">Click</Button>
+
+// Both work in v0.5-0.9
+// Only new API works in v1.0+
+```
+
+## Breaking Changes
+
+Breaking changes are **only** introduced in major versions. Minor and patch versions are always backward compatible.
+
+### Types of Breaking Changes
+- Removed features
+- Changed default behavior
+- Required new dependencies
+- Config structure changes
+- Renamed components/props
+- Changed TypeScript types
+
+### How We Communicate Breaks
+1. **Migration guide**: Detailed upgrade instructions
+2. **Changelog**: Summary of all changes
+3. **Release notes**: Highlights and recommendations
+4. **Deprecation warnings**: In-app notifications before removal
+
+## Getting Help
+
+### Documentation
+- [Migration Guides](./overview.md)
+- [Changelog](./changelog.md)
+- [GitHub Releases](https://github.com/zoyth/simple-site-framework/releases)
+
+### Support
+- **Issues**: [GitHub Issues](https://github.com/zoyth/simple-site-framework/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/zoyth/simple-site-framework/discussions)
+- **Community**: Check for community posts about similar upgrades
+
+### Before Filing an Issue
+1. Read the migration guide
+2. Check existing issues
+3. Run `npx simple-site migrate`
+4. Include version numbers and error messages
+
+## Migration Checklist
+
+Use this checklist for every upgrade:
+
+- [ ] Read migration guide for target version
+- [ ] Review changelog
+- [ ] Backup code (git commit + tag)
+- [ ] Update package.json
+- [ ] Run `npm install`
+- [ ] Run `npx simple-site migrate` (if available)
+- [ ] Fix TypeScript errors
+- [ ] Fix deprecation warnings
+- [ ] Run test suite
+- [ ] Manual QA testing
+- [ ] Check for console warnings
+- [ ] Review bundle size impact
+- [ ] Update documentation
+- [ ] Deploy to staging
+- [ ] Monitor for issues
+
+## Rollback Plan
+
+If upgrade causes issues:
+
+### Quick Rollback
+```bash
+# Revert to previous version
+git reset --hard pre-upgrade-v0.2
+npm install
+```
+
+### Gradual Upgrade
+If full upgrade is risky:
+
+1. **Create feature branch**
+   ```bash
+   git checkout -b upgrade-v0.2
+   ```
+
+2. **Upgrade in stages**
+   - Update framework
+   - Migrate one route/feature at a time
+   - Test between each migration
+
+3. **Merge when stable**
+   ```bash
+   git checkout main
+   git merge upgrade-v0.2
+   ```
+
+## Version-Specific Guides
+
+- [v0.1 → v0.2](./v0.1-to-v0.2.md) (example, create when needed)
+- [Changelog](./changelog.md)
+
+## Best Practices
+
+1. **Upgrade regularly** - Don't fall too far behind
+2. **Read release notes** - Stay informed about changes
+3. **Test in staging first** - Never upgrade production directly
+4. **Use lock files** - Commit package-lock.json
+5. **Monitor deprecations** - Fix warnings before they break
+6. **Keep dependencies updated** - Framework peer dependencies too
+7. **Automated tests** - Catch regressions early
+8. **Document custom code** - Note why you did something unconventional
+
+## FAQ
+
+**Q: Can I skip versions?**
+A: Yes, but read all intermediate migration guides. Run `npx simple-site migrate` to handle multiple version jumps.
+
+**Q: Will my site break on upgrade?**
+A: Minor/patch upgrades are backward compatible. Major upgrades may have breaking changes, but migration tools help.
+
+**Q: How long are versions supported?**
+A: See [Version Support Policy](#version-support-policy) above.
+
+**Q: What if migration tool doesn't work?**
+A: File an issue with details. Manual migration is always an option using the guides.
+
+**Q: Should I upgrade immediately?**
+A: For patches, yes. For minor/major versions, test in staging first.
+
+**Q: Can I stay on old version?**
+A: Yes, but you won't get security fixes after support ends. Plan upgrades accordingly.

package/docs/recipes/adding-animations.md

@@ -0,0 +1,475 @@
+# Recipe: Adding Animations
+
+Guide to adding smooth, professional animations using Framer Motion.
+
+## Overview
+
+The framework uses Framer Motion for animations. This recipe covers:
+- Basic fade and slide animations
+- Stagger effects for lists
+- Scroll-triggered animations
+- Respecting user motion preferences
+- Performance optimization
+
+## Prerequisites
+
+Framer Motion is a peer dependency:
+
+```bash
+npm install framer-motion
+```
+
+## Basic Animations
+
+### Fade In
+
+```tsx
+import { motion } from 'framer-motion'
+
+function FadeInExample() {
+  return (
+    <motion.div
+      initial={{ opacity: 0 }}
+      animate={{ opacity: 1 }}
+      transition={{ duration: 0.5 }}
+    >
+      <h1>This fades in</h1>
+    </motion.div>
+  )
+}
+```
+
+### Slide In
+
+```tsx
+import { motion } from 'framer-motion'
+
+function SlideInExample() {
+  return (
+    <motion.div
+      initial={{ x: -50, opacity: 0 }}
+      animate={{ x: 0, opacity: 1 }}
+      transition={{ duration: 0.5 }}
+    >
+      <h1>This slides in from left</h1>
+    </motion.div>
+  )
+}
+```
+
+### Fade In Up (Most Common)
+
+```tsx
+import { motion } from 'framer-motion'
+
+function FadeInUpExample() {
+  return (
+    <motion.div
+      initial={{ y: 20, opacity: 0 }}
+      animate={{ y: 0, opacity: 1 }}
+      transition={{ duration: 0.6, ease: 'easeOut' }}
+    >
+      <h1>This fades in while moving up</h1>
+    </motion.div>
+  )
+}
+```
+
+## Stagger Animations
+
+Animate lists with staggered timing:
+
+```tsx
+import { motion } from 'framer-motion'
+
+const container = {
+  hidden: { opacity: 0 },
+  show: {
+    opacity: 1,
+    transition: {
+      staggerChildren: 0.1
+    }
+  }
+}
+
+const item = {
+  hidden: { y: 20, opacity: 0 },
+  show: { y: 0, opacity: 1 }
+}
+
+function StaggeredList({ items }) {
+  return (
+    <motion.ul
+      variants={container}
+      initial="hidden"
+      animate="show"
+    >
+      {items.map((item) => (
+        <motion.li key={item.id} variants={item}>
+          {item.name}
+        </motion.li>
+      ))}
+    </motion.ul>
+  )
+}
+```
+
+## Scroll-Triggered Animations
+
+Animate when element enters viewport:
+
+```tsx
+import { motion, useInView } from 'framer-motion'
+import { useRef } from 'react'
+
+function ScrollReveal({ children }) {
+  const ref = useRef(null)
+  const isInView = useInView(ref, { once: true, amount: 0.3 })
+
+  return (
+    <motion.div
+      ref={ref}
+      initial={{ y: 50, opacity: 0 }}
+      animate={isInView ? { y: 0, opacity: 1 } : { y: 50, opacity: 0 }}
+      transition={{ duration: 0.6, ease: 'easeOut' }}
+    >
+      {children}
+    </motion.div>
+  )
+}
+
+// Usage
+<ScrollReveal>
+  <h2>This animates when scrolled into view</h2>
+</ScrollReveal>
+```
+
+## Respecting User Preferences
+
+Always respect `prefers-reduced-motion`:
+
+```tsx
+import { motion, useReducedMotion } from 'framer-motion'
+
+function AccessibleAnimation({ children }) {
+  const shouldReduceMotion = useReducedMotion()
+
+  return (
+    <motion.div
+      initial={{ opacity: 0, y: shouldReduceMotion ? 0 : 20 }}
+      animate={{ opacity: 1, y: 0 }}
+      transition={{
+        duration: shouldReduceMotion ? 0 : 0.6,
+        ease: 'easeOut'
+      }}
+    >
+      {children}
+    </motion.div>
+  )
+}
+```
+
+## Reusable Animation Component
+
+Create a flexible animation wrapper:
+
+```tsx
+import { motion, useReducedMotion, useInView } from 'framer-motion'
+import { useRef } from 'react'
+
+type AnimationType = 'fadeIn' | 'fadeInUp' | 'slideInLeft' | 'slideInRight'
+
+interface AnimatedSectionProps {
+  children: React.ReactNode
+  type?: AnimationType
+  delay?: number
+  duration?: number
+  once?: boolean
+}
+
+const animations: Record<AnimationType, any> = {
+  fadeIn: {
+    hidden: { opacity: 0 },
+    visible: { opacity: 1 }
+  },
+  fadeInUp: {
+    hidden: { y: 20, opacity: 0 },
+    visible: { y: 0, opacity: 1 }
+  },
+  slideInLeft: {
+    hidden: { x: -50, opacity: 0 },
+    visible: { x: 0, opacity: 1 }
+  },
+  slideInRight: {
+    hidden: { x: 50, opacity: 0 },
+    visible: { x: 0, opacity: 1 }
+  }
+}
+
+export function AnimatedSection({
+  children,
+  type = 'fadeInUp',
+  delay = 0,
+  duration = 0.6,
+  once = true
+}: AnimatedSectionProps) {
+  const ref = useRef(null)
+  const isInView = useInView(ref, { once, amount: 0.3 })
+  const shouldReduceMotion = useReducedMotion()
+
+  const animation = animations[type]
+
+  return (
+    <motion.div
+      ref={ref}
+      initial="hidden"
+      animate={isInView ? 'visible' : 'hidden'}
+      variants={shouldReduceMotion ? {} : animation}
+      transition={{
+        duration: shouldReduceMotion ? 0 : duration,
+        delay: shouldReduceMotion ? 0 : delay,
+        ease: 'easeOut'
+      }}
+    >
+      {children}
+    </motion.div>
+  )
+}
+
+// Usage
+<AnimatedSection type="fadeInUp" delay={0.2}>
+  <h1>Animated Heading</h1>
+</AnimatedSection>
+```
+
+## Button Hover Effects
+
+```tsx
+import { motion } from 'framer-motion'
+
+function AnimatedButton({ children, onClick }) {
+  return (
+    <motion.button
+      onClick={onClick}
+      whileHover={{ scale: 1.05 }}
+      whileTap={{ scale: 0.95 }}
+      transition={{ type: 'spring', stiffness: 400, damping: 17 }}
+      className="px-6 py-3 bg-primary text-white rounded"
+    >
+      {children}
+    </motion.button>
+  )
+}
+```
+
+## Card Hover Effects
+
+```tsx
+import { motion } from 'framer-motion'
+
+function Card({ title, description }) {
+  return (
+    <motion.div
+      whileHover={{
+        y: -8,
+        boxShadow: '0 20px 40px rgba(0, 0, 0, 0.15)'
+      }}
+      transition={{ duration: 0.3, ease: 'easeOut' }}
+      className="p-6 bg-white rounded-lg shadow"
+    >
+      <h3>{title}</h3>
+      <p>{description}</p>
+    </motion.div>
+  )
+}
+```
+
+## Page Transitions
+
+```tsx
+import { motion, AnimatePresence } from 'framer-motion'
+import { usePathname } from 'next/navigation'
+
+export function PageTransition({ children }) {
+  const pathname = usePathname()
+
+  return (
+    <AnimatePresence mode="wait">
+      <motion.div
+        key={pathname}
+        initial={{ opacity: 0, y: 20 }}
+        animate={{ opacity: 1, y: 0 }}
+        exit={{ opacity: 0, y: -20 }}
+        transition={{ duration: 0.3 }}
+      >
+        {children}
+      </motion.div>
+    </AnimatePresence>
+  )
+}
+
+// In layout
+<PageTransition>
+  {children}
+</PageTransition>
+```
+
+## Performance Tips
+
+### 1. Animate Transform and Opacity
+
+Prefer `transform` and `opacity` for best performance:
+
+```tsx
+// Good - uses GPU acceleration
+<motion.div
+  animate={{ x: 100, opacity: 0.5 }}
+/>
+
+// Avoid - forces layout recalculation
+<motion.div
+  animate={{ width: 100, marginLeft: 20 }}
+/>
+```
+
+### 2. Use willChange Sparingly
+
+```tsx
+<motion.div
+  style={{ willChange: 'transform' }}
+  animate={{ x: 100 }}
+/>
+```
+
+### 3. Lazy Load Framer Motion
+
+```tsx
+import dynamic from 'next/dynamic'
+
+const AnimatedSection = dynamic(
+  () => import('./AnimatedSection'),
+  { ssr: false }
+)
+```
+
+### 4. Disable Animations on Low-End Devices
+
+```tsx
+const shouldAnimate = !shouldReduceMotion && !isLowEndDevice()
+
+<motion.div
+  animate={shouldAnimate ? { opacity: 1 } : {}}
+>
+  {children}
+</motion.div>
+```
+
+## Common Patterns
+
+### Hero Section Entrance
+
+```tsx
+<motion.div
+  initial={{ opacity: 0, y: 30 }}
+  animate={{ opacity: 1, y: 0 }}
+  transition={{ duration: 0.8, ease: 'easeOut' }}
+>
+  <h1>Welcome</h1>
+</motion.div>
+
+<motion.p
+  initial={{ opacity: 0 }}
+  animate={{ opacity: 1 }}
+  transition={{ delay: 0.3, duration: 0.6 }}
+>
+  Subheadline
+</motion.p>
+
+<motion.div
+  initial={{ opacity: 0, y: 20 }}
+  animate={{ opacity: 1, y: 0 }}
+  transition={{ delay: 0.6, duration: 0.6 }}
+>
+  <Button>Get Started</Button>
+</motion.div>
+```
+
+### Feature Grid
+
+```tsx
+const container = {
+  hidden: {},
+  show: {
+    transition: {
+      staggerChildren: 0.1
+    }
+  }
+}
+
+const item = {
+  hidden: { y: 20, opacity: 0 },
+  show: {
+    y: 0,
+    opacity: 1,
+    transition: { duration: 0.5 }
+  }
+}
+
+<motion.div
+  variants={container}
+  initial="hidden"
+  whileInView="show"
+  viewport={{ once: true }}
+  className="grid grid-cols-3 gap-6"
+>
+  {features.map((feature) => (
+    <motion.div key={feature.id} variants={item}>
+      <FeatureCard {...feature} />
+    </motion.div>
+  ))}
+</motion.div>
+```
+
+## Best Practices
+
+1. **Keep it Subtle**
+   - Duration: 0.3-0.8s
+   - Easing: 'easeOut' or 'easeInOut'
+   - Movement: 20-50px max
+
+2. **Respect Preferences**
+   - Always use `useReducedMotion()`
+   - Provide alternative feedback
+
+3. **Performance**
+   - Animate transform and opacity only
+   - Use `whileInView` for scroll animations
+   - Lazy load when possible
+
+4. **Purpose**
+   - Guide attention
+   - Provide feedback
+   - Establish hierarchy
+   - Don't animate for decoration only
+
+5. **Accessibility**
+   - Don't rely on animation to convey information
+   - Provide text alternatives
+   - Keep animations brief
+   - Test with animations disabled
+
+## Timing Guidelines
+
+- **Micro-interactions**: 100-300ms
+- **Component entrance**: 300-600ms
+- **Page transitions**: 300-500ms
+- **Stagger delay**: 50-150ms between items
+- **Hover effects**: 200-300ms
+
+## Easing Functions
+
+- **easeOut**: Starting fast, ending slow (most common)
+- **easeIn**: Starting slow, ending fast (exits)
+- **easeInOut**: Slow start and end (smooth)
+- **spring**: Bouncy, playful feel
+- **linear**: Robotic, avoid for most cases