shared-components v2.0.0 & v3.0.0 Migration Guide

Breaking Changes Prototype Created: 2026-10-20

Overview

Breaking changes are split across two major versions to minimize disruption:

v2.0.0 Low Risk

Remove Validation System

Internal validators not used by consumers. No deprecation cycle needed.

v3.0.0 Medium Risk

Remove Legacy Composables

Touch tracking, change tracking, screen reader system. Deprecation warnings first.

Related Jira Tickets

v2.0.0

v3.0.0

v2.0.0

Validation System Removal

Expected consumer impact: None

All consuming apps use external validation (VeeValidate, Vuelidate, TanStack Form) via the errors and invalid props.

What's Being Removed

From useFormField

Item Type
validatorsOption
asyncValidatorsOption
validationDebounceMsOption
validatorErrorsRef
checkValidity()Method
cancelValidation()Method
waitForValidation()Method

From useForm

Item Type
checkValidity()Method
waitForValidation()Method

Files to Delete

  • lib/composables/formField/validation.ts
  • test/.../validation.test.ts
v3.0.0

Legacy Composables Cleanup

Requires deprecation cycle

Consumers may be using these features. Deprecation warnings must ship before removal.

1. Touch Tracking (useTouch)

Removed

  • touched ref
  • touchCount ref
  • touch() method
  • resetTouches() method

Migration

Use your form library's touch tracking:

  • VeeValidate: meta.touched
  • Vuelidate: $dirty
  • TanStack: field.state.meta.isTouched

2. Change Tracking (changeTracker)

Removed

  • dirty ref
  • Related change detection logic

Migration

Use your form library's dirty tracking:

  • VeeValidate: meta.dirty
  • Vuelidate: $dirty
  • TanStack: field.state.meta.isDirty

3. Screen Reader Announcements

Removed

  • screenReaderAnnouncement ref
  • announceToScreenReaders() method
  • ScreenReaderAnnouncement component

Migration

Use role="alert" on error containers:

<span v-if="errors.length" role="alert">
  {{ errors[0] }}
</span>

4. Other Removals

Item Migration
committed ref Not needed with external validation
errorsCleared ref Not needed with external validation
form ref Access form context directly if needed
convertValue() Use your own type conversion

Implementation Order

1

Deprecation Warnings

Ship in current version. Dev-mode console warnings for all features being removed in v3.0.0.

[shared-components] useTouch is deprecated and will be removed in v3.0.0...
2

v2.0.0 Release

  • Remove validation system
  • Update types
  • Update documentation
3

v3.0.0 Release

  • Remove useTouch composable
  • Remove changeTracker composable
  • Remove screen reader announcement system
  • Add role="alert" to error containers
  • Simplify useForm
  • Update types and documentation

Testing Checklist

v2.0.0 Before Release

  • Verify no consuming app uses internal validation
  • Search for validators prop usage in platform-frontend
  • Search for checkValidity() calls
  • Run all consuming app test suites

v3.0.0 Before Release

  • Deprecation warnings shipped for at least one release
  • Search for touched/touch() usage
  • Search for dirty ref usage
  • Verify role="alert" works with screen readers
  • Run all consuming app test suites

Files Affected

v2.0.0

File Change
lib/composables/formField/validation.ts Delete
lib/composables/formField/index.ts Modify
lib/types/formFields.ts Modify
test/.../validation.test.ts Delete

v3.0.0

File Change
lib/composables/touch/index.ts Delete
lib/composables/formField/index.ts Simplify
lib/composables/form/index.ts Simplify
lib/components/ScreenReaderAnnouncement.vue Delete
Field components Add role="alert"

Last updated: 2026-10-20