# Migration Guide

This guide helps you migrate from the previous version of `ember-hk-components` to the latest version. Please read through all sections carefully as there are several important changes that may affect your application.

## Overview

This update includes significant improvements to validation handling, dependency upgrades, and package management changes. The most notable changes are:

- Enhanced validation state management in `hk-field-validations`
- Major dependency upgrades (`ember-changeset-validations` v2 → v4)
- Migration from Yarn to pnpm
- Improved accessibility and modern Ember template syntax

## Breaking Changes

### 1. Dependency Updates

#### ember-changeset-validations (v2.2.1 → v4.0.0)

**Impact**: Major version upgrade with potential breaking changes.

**Action Required**:
1. Review the [ember-changeset-validations v4 changelog](https://github.com/poteto/ember-changeset-validations/releases)
2. Update your validation schemas if needed
3. Test all form validation thoroughly

#### ember-a11y-testing (v4.4.0 → v5.2.1)

**Impact**: Major version upgrade affecting accessibility testing.

**Action Required**:
1. Review the [ember-a11y-testing v5 migration guide](https://github.com/ember-a11y/ember-a11y-testing/releases)
2. Update your test files if using this addon directly

### 2. Package Manager Migration (Yarn → pnpm)

**Impact**: The project now enforces pnpm usage and removes yarn.lock.

**Action Required**:
```bash
# Remove yarn.lock if present
rm yarn.lock

# Install pnpm if not already installed
npm install -g pnpm

# Install dependencies
pnpm install
```

**Note**: The addon now includes a preinstall hook that enforces pnpm usage.

### 3. Node.js Engine Requirements

**Impact**: Removed explicit Node.js engine constraints (previously required `14.x || 16.x`).

**Action Required**: Ensure you're using a supported Node.js version for your Ember CLI version.

## Component Behavior Changes

### hk-field-validations Component

The validation logic has been significantly refactored to provide more reliable validation state management.

#### Key Changes

1. **Validation State Tracking**
   - New internal `_hasValidatedFlag` for precise validation tracking
   - `hasValidated` now considers both manual validation and changeset pristine state
   - Improved handling of async validation promises

2. **Enhanced Validation Timing**
   - Better debounced validation with improved error handling
   - More robust cleanup of observers and validation state
   - Improved handling of component destruction during validation

3. **Changeset Integration**
   - `hasValidated` now returns `true` when changeset is no longer pristine
   - This means validation errors may appear earlier than before
   - Better integration with changeset lifecycle events

#### Migration Steps

1. **Test Validation Behavior**
   ```javascript
   // Before: Validation only triggered after explicit user interaction
   // After: Validation may trigger when changeset becomes non-pristine
   
   // Test these scenarios:
   // - Initial form load
   // - First field interaction
   // - Async validation timing
   // - Form reset behavior
   ```

2. **Review Validation Timing**
   If your application relies on specific validation timing, you may need to adjust:
   ```javascript
   // If you need the old behavior, you can check the internal flag:
   // component.get('_hasValidatedFlag') // true only after explicit validation
   
   // New behavior considers changeset state:
   // component.get('hasValidated') // true when validated OR changeset not pristine
   ```

### hk-validation-errors-list Component

#### New Features

- Added `errorsListId` computed property for better accessibility
- Generates IDs like `validation-errors-${property}`

#### Migration Steps

**No action required** - this is a backward-compatible addition.

## Template Syntax Updates

All component templates now use modern Ember syntax with `this.` prefix.

**Before**:
```handlebars
{{yield (hash
  value=value
  isValidating=isValidating
  isValid=isValid
  isInvalid=isInvalid
  errors=validationErrors
)}}
```

**After**:
```handlebars
{{yield (hash
  value=this.value
  isValidating=this.isValidating
  isValid=this.isValid
  isInvalid=this.isInvalid
  errors=this.validationErrors
)}}
```

**Impact**: No breaking changes for consumers, but improves consistency with modern Ember practices.

## Development Environment Changes

### ESLint Configuration

- Updated to use `@babel/eslint-parser`
- Removed `babel-eslint` dependency

### Removed Dependencies

- `ember-cli-chai` - removed from devDependencies
- `npm-run-all` - replaced with direct pnpm commands

### Security Updates

Added package resolutions for security vulnerabilities:
```json
{
  "resolutions": {
    "lodash.template": "npm:lodash@^4.17.21",
    "braces": "npm:braces@^3.0.3",
    "rollup": "^4.50.1",
    "json5": "^2.2.3",
    "ansi-html": "^0.0.8",
    "consolidate": "npm:@ladjs/consolidate@^1.0.0",
    "validated-changeset": "1.4.1"
  }
}
```

## Testing Recommendations

### 1. Validation Testing

Create comprehensive tests for validation behavior:

```javascript
import { module, test } from 'qunit';
import { setupRenderingTest } from 'ember-qunit';
import { render, fillIn, blur } from '@ember/test-helpers';
import { hbs } from 'ember-cli-htmlbars';

module('Integration | Component | your-form', function(hooks) {
  setupRenderingTest(hooks);

  test('validation timing works correctly', async function(assert) {
    // Test initial state
    await render(hbs`{{your-form-component}}`);
    
    // Test validation on changeset modification
    await fillIn('input', 'invalid-value');
    // Assert validation state
    
    // Test validation on blur
    await blur('input');
    // Assert validation state
    
    // Test async validation
    await fillIn('input', 'async-validation-trigger');
    // Wait for validation to complete
    // Assert final state
  });
});
```

### 2. Accessibility Testing

If using `ember-a11y-testing`, update your tests:

```javascript
// Update import if needed
import a11yAudit from 'ember-a11y-testing/test-support/audit';

test('accessibility compliance', async function(assert) {
  await render(hbs`{{your-component}}`);
  await a11yAudit(this.element);
  assert.ok(true, 'no a11y errors found');
});
```

### 3. Integration Testing

Test the complete validation flow:

```javascript
test('complete validation flow', async function(assert) {
  // Test initial pristine state
  // Test first interaction
  // Test validation errors display
  // Test error clearing
  // Test form submission with errors
  // Test successful validation
});
```

## Troubleshooting

### Common Issues

1. **Validation errors appear too early**
   - This is likely due to the new `hasValidated` logic
   - Review your form initialization and changeset setup
   - Consider if the new behavior is actually more user-friendly

2. **Async validation issues**
   - The component now has better handling of async validation
   - Check that your validation functions return promises correctly
   - Ensure proper error handling in your validators

3. **Package installation issues**
   - Make sure you're using pnpm, not npm or yarn
   - Clear node_modules and reinstall if needed: `rm -rf node_modules && pnpm install`

4. **ESLint errors**
   - Update your ESLint configuration if you have custom rules
   - The addon now uses `@babel/eslint-parser`

### Getting Help

If you encounter issues during migration:

1. Check the component documentation
2. Review the test files for usage examples
3. Open an issue with a minimal reproduction case

## Rollback Plan

If you need to rollback:

1. Revert to the previous version in package.json
2. Run `pnpm install` (or your package manager)
3. Restore any custom validation logic you may have modified

## Summary

This update significantly improves the reliability and user experience of form validation while maintaining backward compatibility for most use cases. The main areas requiring attention are:

- Validation timing behavior (may show errors sooner)
- Package manager migration to pnpm
- Testing of async validation scenarios
- Dependency compatibility (especially ember-changeset-validations v4)

Take time to thoroughly test your forms after upgrading, particularly focusing on validation timing and error display behavior.