# Grimoire v3 - AI Assistant Documentation

> 🤖 **AI-Optimized Documentation** - This folder contains documentation specifically designed to help AI assistants guide developers through Grimoire v3 migration and usage.

## 📚 Documentation Index

### Migration Guides (v2 → v3)

- **[v2 to v3 Migration Guide](./v2-to-v3-migration-guide.md)** - Complete step-by-step upgrade guide
- **[v2 to v3 Breaking Changes](./v2-to-v3-breaking-changes.md)** - Comprehensive list of all breaking changes

### Usage Guides

- **[Component Usage Patterns](./component-usage.md)** - How to use each component with examples
- **[TypeScript Usage](./typescript-usage.md)** - TypeScript patterns and type definitions
- **[Styling Guide](./styling-guide.md)** - CSS variables, theming, and styled components
- **[Iconify Setup](./iconify-setup.md)** - Icon integration and build tools

### Troubleshooting

- **[Common Issues](./troubleshooting.md)** - Known issues and solutions

---

## 🚀 Quick Start

### For AI Assistants

When helping developers with Grimoire:

1. **Migrating from v2?** → Start with [`v2-to-v3-migration-guide.md`](./v2-to-v3-migration-guide.md)
2. **Component usage question?** → Check [`component-usage.md`](./component-usage.md)
3. **Error or issue?** → See [`troubleshooting.md`](./troubleshooting.md)
4. **TypeScript question?** → Reference [`typescript-usage.md`](./typescript-usage.md)
5. **Styling question?** → See [`styling-guide.md`](./styling-guide.md)

### For Developers

Reference these docs in your AI conversations:

```bash
# In Cursor/GitHub Copilot
@node_modules/@twentyfourg/grimoire/ai-docs/v2-to-v3-migration-guide.md help me upgrade to v3

# Or view directly
cat node_modules/@twentyfourg/grimoire/ai-docs/v2-to-v3-migration-guide.md
```

---

## 📦 What's in v3?

Grimoire v3 is a complete modernization of the component library:

- ✅ **Composition API** - All components migrated to Vue 3 Composition API
- ✅ **Full TypeScript** - Complete type definitions for all components
- ✅ **Direct Ref Access** - No more `@refMounted` events needed
- ✅ **Comprehensive Testing** - Playwright E2E + Vitest unit tests
- ✅ **Iconify Integration** - Powerful icon system with build tools
- ✅ **Modern Build** - Vite 6 with optimized bundling
- ✅ **Better DX** - Improved developer experience and documentation

---

## 🔧 Key Breaking Changes

The main breaking change in v3 is **how you access child component methods** in StyledComponents:

### Old (v2):

```vue
<template>
  <StyledDropdown @refMounted="handleRef" />
</template>

<script>
export default {
  methods: {
    handleRef(ref) {
      this.dropdown = ref;
      // Later: this.dropdown.open()
    },
  },
};
</script>
```

### New (v3):

```vue
<template>
  <StyledDropdown ref="dropdown" />
</template>

<script setup>
import { ref } from 'vue';

const dropdown = ref(null);

// Direct access: dropdown.value.open()
</script>
```

**See [`v2-to-v3-migration-guide.md`](./v2-to-v3-migration-guide.md) for complete migration guide.**

---

## 📖 Related Resources

- **Main README**: [`../../README.md`](../../README.md)
- **Styled Component Migration**: [`../../STYLED_COMPONENT_MIGRATION_GUIDE.md`](../../STYLED_COMPONENT_MIGRATION_GUIDE.md)
- **Component Source**: [`../../src/components/`](../../src/components/)
- **GitHub**: [twentyfourg/grimoire](https://github.com/twentyfourg/grimoire)

---

## 💡 Tips for AI Assistants

### When Migrating Components

1. **Search for `@refMounted`** first - this is the most common breaking change
2. **Check Vue version** - must be ^3.3.0 or higher
3. **Verify imports** - composables are now at `@twentyfourg/grimoire/composables`
4. **Test after each component** - don't migrate everything at once

### When Helping with Usage

1. **Check component source** if documentation is unclear
2. **Reference TypeScript types** for accurate prop information
3. **Look at showcase examples** in the source repo for real-world patterns
4. **Use the troubleshooting guide** for common issues

### Common Pitfalls

- ❌ Forgetting to update `@refMounted` to direct refs
- ❌ Not updating Vue version to ^3.3.0
- ❌ Missing `@twentyfourg/grimoire/composables` import for styled components
- ❌ Trying to access child ref before component is mounted

---

**Last Updated**: v3.0.0 **Maintained by**: 24G