# Breaking Changes: v2 to v3

Complete list of all breaking changes when upgrading from Grimoire v2 to v3.

---

## 🔴 Critical Breaking Changes

### 1. StyledComponent Ref Access Pattern

**Impact**: 🔴 **HIGH** - Affects all projects using StyledComponents

**What Changed**:

- The `@refMounted` event has been **removed**
- Use direct template refs instead

**OLD (v2):**

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

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

**NEW (v3):**

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

<script setup>
import { ref } from 'vue';
const dropdown = ref(null);

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

**Migration Guide**: See [`v2-to-v3-migration-guide.md`](./v2-to-v3-migration-guide.md#step-3-migrate-refmounted-to-direct-refs)

**Automated Detection**:

```bash
grep -r "@refMounted" src/
```

---

## 🟡 Medium Breaking Changes

### 2. Vue Version Requirement

**Impact**: 🟡 **MEDIUM** - May require updating Vue

**What Changed**:

- Minimum Vue version increased from `^3.0.0` to `^3.3.0`

**Reason**: v3 uses newer Composition API features available in Vue 3.3+

**Fix**:

```bash
pnpm update vue@^3.3.0
# or
npm install vue@^3.3.0
```

**Check Current Version**:

```bash
npm list vue
```

---

### 3. Plugin Export Format

**Impact**: 🟡 **MEDIUM** - Only if using the Grimoire plugin

**What Changed**:

- Plugin export changed from default export to named export
- Plugin file extension changed from `.js` to `.ts`

**OLD (v2):**

```javascript
import GrimoirePlugin from '@twentyfourg/grimoire/plugin';

app.use(GrimoirePlugin, {
  icons: {...}
});
```

**NEW (v3):**

```javascript
import { GrimoirePlugin } from '@twentyfourg/grimoire/plugin';

app.use(GrimoirePlugin, {
  icons: {...}
});
```

**Note**: The plugin is **only** for registering Iconify icon collections, not for global component registration.

---

## 🟢 Minor Breaking Changes

### 4. Iconify Build Tools

**Impact**: 🟢 **LOW** - Only if building custom icon bundles from SVGs

**What Changed**:

- Pre-built icon bundles removed
- New build tools available for creating bundles from source

**OLD (v2):**

```javascript
// Direct imports of pre-built bundles
import '@twentyfourg/grimoire/icons/app';
import '@twentyfourg/grimoire/icons/custom';
```

**NEW (v3):**

```javascript
// Use Vite plugin to build bundles from SVG sources
// See ai-docs/iconify-setup.md for setup
import { viteIconBundlePlugin } from '@twentyfourg/grimoire/build-tools';
```

**If you're NOT building custom icons**, this doesn't affect you.

**Migration Guide**: See [`iconify-setup.md`](./iconify-setup.md)

---

### 5. Package Export Paths

**Impact**: 🟢 **LOW** - Only affects direct imports

**What Changed**:

- New export paths added for better organization
- All exports now properly typed

**NEW in v3**:

```javascript
// Composables (for styled component creation)
import { useStyledComponent, useExposeForwarding } from '@twentyfourg/grimoire/composables';

// Build tools (for icon bundling)
import { viteIconBundlePlugin } from '@twentyfourg/grimoire/build-tools';

// Plugin (for icon registration)
import { GrimoirePlugin } from '@twentyfourg/grimoire/plugin';
```

**Component imports unchanged**:

```javascript
// Still works the same
import { GButton, GInput } from '@twentyfourg/grimoire';
```

---

## 📦 Internal Changes (Non-Breaking for Consumers)

These changes are internal and **should not affect** consumer applications:

### ✅ Composition API Migration

- All components migrated from Options API to Composition API
- **No external API changes** - props, events, and slots remain the same

### ✅ TypeScript Migration

- Full TypeScript support added
- **No migration needed** for JavaScript users
- Better autocomplete for TypeScript users

### ✅ Build Infrastructure

- Upgraded from Vite 4 to Vite 6
- **No changes needed** in consumer projects

### ✅ Test Coverage

- Added Playwright E2E and Vitest unit tests
- **No impact** on consumers

---

## 🐛 Bug Fixes That May Affect Behavior

### GRadio: Fixed Return Value Logic

**Impact**: 🟢 **LOW** - Edge case fix for radio groups

**What Changed**:

- Fixed radio button to return `undefined` (instead of `false`) when unchecked in a radio group

**OLD (v2):**

```javascript
// Radio group with value="option1"
// When unchecked: returns false ❌
```

**NEW (v3):**

```javascript
// Radio group with value="option1"
// When unchecked: returns undefined ✅
```

**Impact**: Only affects edge cases where you were explicitly checking for `false`. Most consumers won't notice.

---

### GButton: Fixed inheritAttrs Behavior

**Impact**: 🟢 **LOW** - May affect unit tests with duplicate classes

**What Changed**:

- `GButton` now properly sets `inheritAttrs: false` to prevent class duplication
- Previously, classes were being applied to both the wrapper and the button element

**OLD (v2):**

```vue
<GButton class="my-button" />
<!-- Resulted in: -->
<!-- <div class="my-button">          ← Wrapper -->
<!--   <button class="my-button">     ← Button (duplicate) -->
```

**NEW (v3):**

```vue
<GButton class="my-button" />
<!-- Results in: -->
<!-- <div>                            ← Wrapper (no class) -->
<!--   <button class="my-button">     ← Button (correct) -->
```

**Impact on Tests**:

If you had unit tests that relied on duplicate classes, they will fail:

```javascript
// ❌ OLD test (will fail in v3)
expect(wrapper.find('.my-button').exists()).toBe(true); // Wrapper
expect(wrapper.find('button.my-button').exists()).toBe(true); // Button

// ✅ NEW test (v3)
expect(wrapper.find('button.my-button').exists()).toBe(true); // Button only
```

**Migration**: Update any tests that check for classes on the wrapper element. The class will only exist on the `<button>` element in v3.

---

## 🔧 Deprecation Warnings

v3 does not include deprecation warnings (since breaking changes are immediate). However, if you're still on v2 and see these patterns, they will break in v3:

| Pattern                | Status           | Action           |
| ---------------------- | ---------------- | ---------------- |
| `@refMounted`          | ❌ Removed in v3 | Use direct refs  |
| Pre-built icon bundles | ❌ Removed in v3 | Use build tools  |
| Default plugin export  | ❌ Changed in v3 | Use named export |

---

## 📊 Breaking Change Impact Matrix

| Change                | Who's Affected               | Migration Difficulty | Time Estimate |
| --------------------- | ---------------------------- | -------------------- | ------------- |
| `@refMounted` removal | All StyledComponent users    | 🟢 Easy              | 10-60 min     |
| Vue 3.3+ requirement  | Projects on Vue < 3.3        | 🟢 Easy              | 5 min         |
| Plugin export format  | Projects using plugin        | 🟢 Easy              | 2 min         |
| Icon build tools      | Projects with custom icons   | 🟡 Medium            | 30-60 min     |
| Package exports       | Projects with direct imports | 🟢 Easy              | 5 min         |

---

## ✅ What's NOT Breaking

These things **did NOT change** and work exactly the same:

✅ **Component props** - All props remain the same ✅ **Component events** - All events remain the same ✅ **Component slots** - All slots remain the same ✅ **Component imports** - Main imports still work ✅ **CSS classes** - Class names unchanged ✅ **Component behavior** - Functionality unchanged

---

## 🎯 Quick Migration Path

Most projects only need to:

1. Update package: `npm install @twentyfourg/grimoire@^3.0.0`
2. Find `@refMounted`: `grep -r "@refMounted" src/`
3. Replace with refs (see [`v2-to-v3-migration-guide.md`](./v2-to-v3-migration-guide.md))
4. Update plugin import (if used)
5. Test and deploy

**Estimated time**: 30 minutes - 2 hours

---

## 📚 Additional Resources

- **[Migration Guide](./v2-to-v3-migration-guide.md)** - Step-by-step migration instructions
- **[Troubleshooting](./troubleshooting.md)** - Common issues and fixes
- **[Component Usage](./component-usage.md)** - Updated usage patterns
- **[GitHub Changelog](../../CHANGELOG.md)** - Full changelog (if exists)

---

## 🆘 Need Help?

If you encounter issues not covered here:

1. Check [`troubleshooting.md`](./troubleshooting.md)
2. Search [GitHub Issues](https://github.com/twentyfourg/grimoire/issues)
3. Open a new issue with the `v3-migration` label

---

**Last Updated**: v3.0.0