@heroku/ember-hk-components 0.21.2 → 1.21.3

package/MIGRATION_GUIDE.md

@@ -0,0 +1,287 @@
+# 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.
+

package/Procfile

@@ -0,0 +1 @@
+web: bin/start-nginx-static

package/README.md

@@ -1,20 +1,35 @@
 # Ember HK Components
 
-Reusable Ember components
+Reusable Ember components for Heroku applications.
 
 ## Assumptions
 
 Usage of these components assumes you are using the [Purple3 CSS framework](https://purple3.herokuapp.com/) and [Malibu](https://hk-malibu.herokuapp.com).
 
+## Security
+
+This project maintains high security standards and regularly addresses vulnerabilities through:
+
+- **Automated vulnerability scanning** via `pnpm audit`
+- **Strategic dependency resolutions** to address transitive vulnerabilities
+- **Regular dependency updates** while maintaining compatibility
+- **Comprehensive security documentation** (see `BABEL_TRAVERSE_VULNERABILITY_GUIDE.md`)
+
+For security-related questions or to report vulnerabilities, please follow Heroku's security guidelines.
+
 ## Usage
 
 ### Installation
 
-1. Install `ember-cli-eyeglass` if it's not installed already.
-`ember install --save ember-cli-eyeglass`
+1. Install `ember-cli-eyeglass` if it's not installed already:
+   ```bash
+   ember install ember-cli-eyeglass
+   ```
 
-2. Install `@heroku/ember-hk-components`
-`ember install --save @heroku/ember-hk-components`
+2. Install `@heroku/ember-hk-components`:
+   ```bash
+   ember install @heroku/ember-hk-components
+   ```
 
 #### CSS
 
@@ -39,7 +54,7 @@ See [ember-hk-components.herokuapp.com](https://ember-hk-components.herokuapp.co
 
 * `git clone https://github.com/heroku/ember-hk-components`
 * `cd ember-hk-components`
-* `yarn install`
+* `pnpm install`
 
 ### Running
 
@@ -48,27 +63,69 @@ See [ember-hk-components.herokuapp.com](https://ember-hk-components.herokuapp.co
 
 ### Running Tests
 
-* `yarn test` (Runs `ember try:each` to test your addon against multiple Ember versions)
+* `pnpm test` (Runs `ember try:each` to test your addon against multiple Ember versions)
 * `ember test`
 * `ember test --server`
 
+### Security Auditing
+
+This project uses PNPM for enhanced security and performance:
+
+* `pnpm audit` - Check for security vulnerabilities
+* `pnpm audit --fix` - Automatically fix resolvable vulnerabilities
+
+See `BABEL_TRAVERSE_VULNERABILITY_GUIDE.md` for detailed security resolution strategies.
+
 ### Local Usage in Another Application
 
-The demo app is useful for developing this addon, but it can often be helpful to consume your version of this addon in another application either to more easily develop your changes or to validate that your changes work as you expect.  You can use your local version of `ember-hk-components` in another application that consumes it via yarn's [link](https://yarnpkg.com/lang/en/docs/cli/link/) command.
+The demo app is useful for developing this addon, but it can often be helpful to consume your version of this addon in another application either to more easily develop your changes or to validate that your changes work as you expect. You can use your local version of `ember-hk-components` in another application that consumes it via PNPM's [link](https://pnpm.io/cli/link) command.
 
 ```sh
 // in your ember-hk-components directory
-> yarn link
+> pnpm link --global
 
 // in your consuming app directory
-> yarn link @heroku/ember-hk-components
+> pnpm link --global @heroku/ember-hk-components
 
 // to put consuming app back on the release version
-> yarn unlink @heroku/ember-hk-components
+> pnpm unlink --global @heroku/ember-hk-components
+> pnpm install @heroku/ember-hk-components
 ```
 
 Now, when you make changes in your copy of `ember-hk-components` those changes will be reflected in the consuming application.
 
+### Package Management
+
+This project has migrated from Yarn to PNPM for:
+
+- **Enhanced security** through stricter dependency resolution
+- **Better performance** with content-addressable storage
+- **Improved workspace support** for monorepo scenarios
+- **Advanced resolution strategies** for vulnerability mitigation
+
+All package management commands should use `pnpm` instead of `npm` or `yarn`.
+
+### Recent Security Improvements
+
+This project has recently undergone significant security hardening:
+
+#### Vulnerability Resolution
+- **Critical babel-traverse vulnerability** resolved via strategic package resolutions
+- **High-severity vulnerabilities** in `rollup`, `json5`, `ansi-html` addressed
+- **Transitive dependency vulnerabilities** mitigated through `@ladjs/consolidate` adoption
+
+#### Dependency Updates
+- **ember-a11y-testing** updated to `^5.2.1` for better compatibility
+- **Package resolutions** strategically implemented for security without breaking changes
+- **Comprehensive audit process** documented for future maintenance
+
+#### Security Documentation
+- `BABEL_TRAVERSE_VULNERABILITY_GUIDE.md` - Comprehensive guide for resolving babel-traverse vulnerabilities
+- Detailed troubleshooting and implementation strategies
+- Best practices for maintaining security in Ember CLI projects
+
+For more details on security implementations, see the vulnerability guide and recent changelog entries.
+
 ### Releases
 
 #### Notes
@@ -88,12 +145,12 @@ Once you are ready to make a new release follow these steps:
 * Ensure all merged pull requests are labelled correctly as indicated in the Changelog section
 * Create a new branch
 * Update the version number in `package.json`
-* Run `yarn run changelog --from x.x.x` where `x.x.x` is the _last_ version of this library that was released.  This should generate changelog of changes _since_ that last release.
-* Copy the output of that command into Changelog.md
+* Run `pnpm run changelog --from x.x.x` where `x.x.x` is the _last_ version of this library that was released.  This should generate changelog of changes _since_ that last release.
+* Copy the output of that command into `CHANGELOG.md`
 * Commit your changes and open a PR
 
 Once the PR is approved and merged you can then tag your new version by running `git tag x.x.x` where `x.x.x` is the new version number. Push your tag to GitHub using `git push origin --tags`.
 
-Publish your new version to npm with the command `npm publish` 🎉
+Publish your new version to npm with the command `pnpm publish` 🎉
 
 _Note that you must have publish access to the @heroku npm organization to successfully publish_

package/addon/components/hk-field-validations.js

@@ -1,6 +1,6 @@
 import Component from '@ember/component';
 import { computed, get } from '@ember/object';
-import { alias, and, notEmpty, not } from '@ember/object/computed';
+import { alias, and, not, notEmpty, or } from '@ember/object/computed';
 import { debounce } from '@ember/runloop';
 import layout from '@heroku/ember-hk-components/templates/components/hk-field-validations';
 
@@ -8,92 +8,120 @@ export default Component.extend({
   layout,
   classNameBindings: ['isInvalid:has-validation-errors'],
   debounceValidation: 1000,
+
+  // Use a manual flag for validation state
   isValidating: false,
   isNotValidating: not('isValidating'),
-  hasValidated: false,
+
+  _hasValidatedFlag: false,
+
+  // A field has been validated if it was triggered internally OR
+  // if the changeset is no longer in its initial pristine state.
+  hasValidated: or('_hasValidatedFlag', 'isChangesetAttempted'),
+  isChangesetAttempted: not('changeset.isPristine'),
+
   hasValidationErrors: notEmpty('validationErrors'),
   doesNotHaveValidationErrors: not('hasValidationErrors'),
   isValid: and('isNotValidating', 'hasValidated', 'doesNotHaveValidationErrors'),
   isInvalid: and('isNotValidating', 'hasValidated', 'hasValidationErrors'),
   changesetErrors: alias('changeset.error'),
 
-  validationErrors: computed('changesetErrors', function() {
-    const changesetErrors = this.get('changesetErrors');
-    const property = this.get('property');
-    const errors = get(changesetErrors, property);
-
-    // filter out validations that are promises...
-    // ember changeset seems to put the validation promise as the value for `validation`
-    // before it resolves or rejects.
-    if (!errors || typeof errors.validation === 'object' && errors.validation !== null && typeof errors.validation.then === 'function') {
-      return;
-    }
-    return errors;
+  validationErrors: computed('changeset.error', 'property', function() {
+    return get(this.get('changeset.error'), this.get('property'));
   }),
 
   didReceiveAttrs() {
     this._super(...arguments);
-
     this.cleanUpObservers();
-
-    let changeset = this.get('changeset');
-    let property = this.get('property');
-
+    const changeset = this.get('changeset');
+    const property = this.get('property');
+    
+    // Add observer for the property
     changeset.addObserver(property, this, 'valueDidChange');
-    changeset.on('beforeValidation', this, 'beforeValidation');
-    changeset.on('afterValidation', this, 'afterValidation');
-
-    this._prev = { changeset, property };
+    
+    // Listen for validation state changes on the changeset
+    if (changeset.validate) {
+      const originalValidate = changeset.validate;
+      changeset.validate = (...args) => {
+        this.set('isValidating', true);
+        const result = originalValidate.apply(changeset, args);
+        
+        if (result && typeof result.then === 'function') {
+          return result
+            .then((validationResult) => {
+              if (!this.isDestroyed) {
+                this.set('isValidating', false);
+                this.set('_hasValidatedFlag', true);
+                this.notifyPropertyChange('validationErrors');
+              }
+              return validationResult;
+            })
+            .catch((error) => {
+              if (!this.isDestroyed) {
+                this.set('isValidating', false);
+                this.set('_hasValidatedFlag', true);
+                this.notifyPropertyChange('validationErrors');
+              }
+              throw error;
+            });
+        } else {
+          this.set('isValidating', false);
+          this.set('_hasValidatedFlag', true);
+          this.notifyPropertyChange('validationErrors');
+          return result;
+        }
+      };
+    }
+    
+    this._prev = { 
+      changeset, 
+      property,
+      originalValidate: changeset.validate 
+    };
   },
 
   willDestroyElement() {
+    // Set a flag to prevent any pending validations from updating state
+    this._isDestroyed = true;
     this.cleanUpObservers();
-
     this._super(...arguments);
   },
-
-  beforeValidation(key) {
-    if (key === this.property) {
-      this.set('isValidating', true);
-    }
+  
+  willDestroy() {
+    this._isDestroyed = true;
+    this.cleanUpObservers();
+    this._super(...arguments);
   },
 
-  afterValidation(key) {
-    if (key === this.property) {
-      this.set('hasValidated', true);
-      this.set('isValidating', false);
+  cleanUpObservers() {
+    if (!this._prev) { return; }
+    const { changeset, property, originalValidate } = this._prev;
+    changeset.removeObserver(property, this, 'valueDidChange');
+    
+    // Restore original validate function if we patched it
+    if (originalValidate && changeset.validate) {
+      changeset.validate = originalValidate;
     }
+    
+    this._prev = null;
   },
 
   valueDidChange() {
+    if (this._isDestroyed) { return; }
     const newValue = this.get('changeset').get(this.get('property'));
-
     if (newValue === this._prevValue) { return; }
-
     this._prevValue = newValue;
     this.notifyPropertyChange('value');
     this.scheduleValidation();
   },
 
-  cleanUpObservers() {
-    if (!this._prev) { return; }
-
-    let { changeset, property } = this._prev;
-
-    changeset.removeObserver(property, this, 'valueDidChange');
-    changeset.off('beforeValidation', this, 'beforeValidation');
-    changeset.off('afterValidation', this, 'afterValidation');
-
-    this._prev = null;
-  },
-
   value: computed('changeset', 'property', {
-    get(/* key */) {
-      return this.get('changeset').get(this.get('property'));
+    get() {
+      const property = this.get('property');
+      // This getter now correctly establishes a dependency on the nested property
+      return this.get(`changeset.${property}`);
     },
     set(key, value) {
-      // The `valueDidChange` observer is responsible for invoking
-      // `scheduleValidation` in reaction to this change.
       this.get('changeset').set(this.get('property'), value);
       return value;
     }
@@ -105,10 +133,42 @@ export default Component.extend({
   },
 
   validateProperty() {
-    if (!this.get('isDestroyed')) {
-      const changeset = this.get('changeset');
-      const property = this.get('property');
-      return changeset.validate(property);
+    if (this.isDestroyed || this._isDestroyed) { return; }
+
+    // Manually setting the flag here ensures it's true even if debounce is 0
+    this.set('isValidating', true);
+    const changeset = this.get('changeset');
+    const property = this.get('property');
+    const maybePromise = changeset.validate(property);
+
+    const onFinally = (error) => {
+      if (this.isDestroyed) { return; }
+      
+      this.set('_hasValidatedFlag', true);
+      this.set('isValidating', false);
+      
+      // If there was an error, ensure the error is set on the changeset
+      if (error) {
+        const errorObj = {};
+        errorObj[property] = error.message || error;
+        changeset.set('error', { [property]: [errorObj] });
+      }
+      
+      this.notifyPropertyChange('validationErrors');
+    };
+
+    if (maybePromise && typeof maybePromise.then === 'function') {
+      return maybePromise
+        .then(() => onFinally())
+        .catch(error => onFinally(error))
+        .finally(() => {
+          if (!this.isDestroyed) {
+            this.notifyPropertyChange('validationErrors');
+          }
+        });
+    } else {
+      onFinally();
+      return maybePromise;
     }
   }
-});
+});

package/addon/components/hk-validation-errors-list.js

@@ -1,5 +1,6 @@
 import Component from '@ember/component';
 import { alias, bool } from '@ember/object/computed';
+import { computed } from '@ember/object';
 import layout from '@heroku/ember-hk-components/templates/components/hk-validation-errors-list';
 
 export default Component.extend({
@@ -7,4 +8,7 @@ export default Component.extend({
   tagName: '',
   hasValidationErrors: bool('validationErrors'),
   validationErrorMessages: alias('validationErrors.validation'),
+  errorsListId: computed('property', function() {
+    return `validation-errors-${this.get('property')}`;
+  }),
 });

package/addon/templates/components/hk-field-validations.hbs

@@ -1,8 +1,8 @@
 {{yield (hash
-  value=value
-  isValidating=isValidating
-  isValid=isValid
-  isInvalid=isInvalid
-  errors=validationErrors
-  errorsList=(component 'hk-validation-errors-list' validationErrors=validationErrors property=property)
-)}}
+  value=this.value
+  isValidating=this.isValidating
+  isValid=this.isValid
+  isInvalid=this.isInvalid
+  errors=this.validationErrors
+  errorsList=(component 'hk-validation-errors-list' validationErrors=this.validationErrors property=this.property)
+)}}