diff --git a/packages/design-system-react-native/MIGRATION.md b/packages/design-system-react-native/MIGRATION.md index fc40c25b4..59757885f 100644 --- a/packages/design-system-react-native/MIGRATION.md +++ b/packages/design-system-react-native/MIGRATION.md @@ -11,6 +11,7 @@ This guide provides detailed instructions for migrating your project from one ve - [BannerBase Component](#bannerbase-component) - [Text Component](#text-component) - [Icon Component](#icon-component) + - [Input Component](#input-component) - [Version Updates](#version-updates) - [From version 0.12.0 to 0.13.0](#from-version-0120-to-0130) - [From version 0.11.0 to 0.12.0](#from-version-0110-to-0120) @@ -644,6 +645,85 @@ import { Icon, IconName, IconSize, IconColor } from '@metamask/design-system-rea - `hitSlop` remains available via inherited `ViewProps` - `twClassName` is available for Tailwind utility overrides in the design system +### Input Component + +The Input component has a mostly aligned API when migrating from the mobile component-library. The largest differences are around value control and default focus behavior. + +#### Breaking Changes + +##### Import Path + +| Mobile Pattern | Design System Migration | +| ------------------------------------------------------------------------ | ------------------------------------------------------------------ | +| `import Input from '.../Form/TextField/foundation/Input'` | `import { Input } from '@metamask/design-system-react-native'` | +| `import { TextVariant } from '.../components/Texts/Text'` | `import { TextVariant } from '@metamask/design-system-react-native'` | + +##### Structured API Mapping + +| Change Type | Mobile API | Design System API | Notes | +| ----------- | ---------- | ----------------- | ----- | +| Type/Behavior Change | `value?: string` from inherited `TextInputProps` | `value: string` (required) | Design system Input is controlled-only; provide a string value. | +| Default Change | `autoFocus = true` | `autoFocus = false` | Inputs no longer focus by default on mount. | +| Unchanged | `isDisabled?: boolean` | `isDisabled?: boolean` | Same meaning; maps to `editable={!isDisabled && !isReadonly}`. | +| Unchanged | `isReadonly?: boolean` | `isReadonly?: boolean` | Same meaning; maps to `editable={!isDisabled && !isReadonly}`. | +| Unchanged | `isStateStylesDisabled?: boolean` | `isStateStylesDisabled?: boolean` | Same behavior for focus/disabled state styling toggles. | +| Unchanged | `textVariant?: TextVariant` | `textVariant?: TextVariant` | Same prop, with `TextVariant.BodyMd` default in both implementations. | +| Added | — | `twClassName?: string` | Tailwind class overrides are now first-class via `twClassName`. | +| Unchanged | `onBlur` / `onFocus` event callbacks | `onBlur` / `onFocus` event callbacks | Same signature; still receive native focus events. | +| Unchanged | `onChangeText` | `onChangeText` | Same callback for text updates. | + +#### Migration Examples + +##### Before (Mobile) + +```tsx +import Input from '../../../component-library/components/Form/TextField/foundation/Input'; +import { TextVariant } from '../../../component-library/components/Texts/Text'; + +; +``` + +##### After (Design System) + +```tsx +import { + Input, + TextVariant, +} from '@metamask/design-system-react-native'; + +; +``` + +##### Default Focus Behavior (If You Relied on Auto-Focus) + +```tsx +import { Input } from '@metamask/design-system-react-native'; + +; +``` + +#### API Differences + +- `value` is now required, so initialize controlled state before rendering. +- `twClassName` is supported for Tailwind utility overrides in addition to `style`. +- Placeholder visibility and input metrics handling are preserved, including iOS placeholder line-height behavior. + ## Version Updates This section covers version-to-version breaking changes within `@metamask/design-system-react-native`. diff --git a/packages/design-system-react-native/src/components/Input/README.md b/packages/design-system-react-native/src/components/Input/README.md index 358eaed8b..da7e720b1 100644 --- a/packages/design-system-react-native/src/components/Input/README.md +++ b/packages/design-system-react-native/src/components/Input/README.md @@ -108,3 +108,7 @@ export const ConditionalExample = ({ isFocused }: { isFocused: boolean }) => { ## References [MetaMask Design System Guides](https://www.notion.so/MetaMask-Design-System-Guides-Design-f86ecc914d6b4eb6873a122b83c12940) + +## Migration from Mobile Component Library + +For detailed migration instructions from the Mobile component-library, see the [Migration Guide](https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react-native/MIGRATION.md#input-component). diff --git a/packages/design-system-react/MIGRATION.md b/packages/design-system-react/MIGRATION.md index 2d42334ce..1d489f0b8 100644 --- a/packages/design-system-react/MIGRATION.md +++ b/packages/design-system-react/MIGRATION.md @@ -12,6 +12,7 @@ This guide provides detailed instructions for migrating your project from one ve - [BannerBase Component](#bannerbase-component) - [Text Component](#text-component) - [Icon Component](#icon-component) + - [Input Component](#input-component) - [Version Updates](#version-updates) - [From version 0.12.0 to 0.13.0](#from-version-0120-to-0130) - [From version 0.10.0 to 0.11.0](#from-version-0100-to-0110) @@ -580,6 +581,92 @@ import { - Icon color values should use `IconColor` enum values from `@metamask/design-system-react` - Use SVG props directly for accessibility and rendering behavior +### Input Component + +The Input component has breaking API changes when migrating from the extension component-library. The extension Input was polymorphic and inherited Box style-utility props, while the design system Input is a standard HTML `` wrapper with an explicit API surface. + +Refer to [General Extension Migration Guidance](#general-extension-migration-guidance) for the shared Box/style-utility migration approach used across all components. + +#### Breaking Changes + +##### Import Path + +| Extension Pattern | Design System Migration | +| ------------------------------------------------------- | ----------------------------------------------------------- | +| `import { Input } from '../../component-library'` | `import { Input } from '@metamask/design-system-react'` | +| `import { InputType } from './input.types'` | Use native input `type` strings (for example `'text'`) | +| `import { TextVariant } from '../../../helpers/...` | `import { TextVariant } from '@metamask/design-system-react'` | + +##### Structured API Mapping + +| Change Type | Extension API | Design System API | Notes | +| ----------- | ------------- | ----------------- | ----- | +| Renamed | `disabled?: boolean` | `isDisabled?: boolean` | Use `isDisabled` to set `disabled` on the underlying ``. | +| Renamed | `readOnly?: boolean` | `isReadonly?: boolean` | Use `isReadonly` to set `readOnly` on the underlying ``. | +| Removed | `disableStateStyles?: boolean` | Removed | Design system Input always applies its state styles; use `className` overrides when needed. | +| Removed | `error?: boolean` | Removed | Pass `aria-invalid` directly when needed. | +| Removed | Polymorphic `as` support via `PolymorphicComponentPropWithRef` | Removed | Design system Input always renders an ``. | +| Removed | Box `StyleUtilityProps` on Input (`margin`, `padding`, etc.) | Removed | Wrap with `Box`/layout primitives or use `className` for spacing/layout. | +| Type/Value Change | `autoComplete?: boolean` | Native `autoComplete?: string` | Migrate `true`/`false` usage to valid HTML autocomplete tokens (`'on'`, `'off'`, `'email'`, etc.). | +| Type/Value Change | `type?: InputType` (`text`, `number`, `password`, `search`) | Native input `type` strings | InputType enum is removed; use plain string values supported by HTML input. | +| Callback Signature Change | `onBlur?: () => void` | `onBlur?: FocusEventHandler` | Event object is now provided. | +| Callback Signature Change | `onFocus?: () => void` | `onFocus?: FocusEventHandler` | Event object is now provided. | +| Callback Signature Change | `onChange?: () => void` | `onChange?: ChangeEventHandler` | Event object is now provided. | +| Default Change | `textVariant = TextVariant.bodyMd` | `textVariant = TextVariant.BodyMd` | Enum member casing changed to PascalCase. | +| Behavior Note | `type` explicitly defaulted to `InputType.Text` in component | Browser default `type="text"` when omitted | Behavior is effectively unchanged when `type` is omitted. | + +#### Migration Examples + +##### Before (Extension) + +```tsx +import { Input } from '../../component-library'; +import { + TextVariant, +} from '../../../helpers/constants/design-system'; + + { + // Legacy callback did not receive the event argument. + }} +/>; +``` + +##### After (Design System) + +```tsx +import { + Input, + TextVariant, +} from '@metamask/design-system-react'; + + { + const nextValue = event.currentTarget.value; + setSearch(nextValue); + }} +/>; +``` + +#### API Differences + +- `className` and `style` remain available for customization. +- `placeholder`, `name`, `id`, `required`, `maxLength`, `value`, and `defaultValue` continue to work via inherited native input props. +- For layout concerns previously handled by Box style props on Input, prefer wrapping with `Box` and using layout props there. + ## Version Updates This section covers version-to-version breaking changes within `@metamask/design-system-react`. diff --git a/packages/design-system-react/src/components/Input/README.mdx b/packages/design-system-react/src/components/Input/README.mdx index 2a6d0882e..2d7eaad6b 100644 --- a/packages/design-system-react/src/components/Input/README.mdx +++ b/packages/design-system-react/src/components/Input/README.mdx @@ -154,6 +154,10 @@ The `style` prop should primarily be used for dynamic inline styles that cannot +## Migration from Extension Component Library + +For detailed migration instructions from the Extension component-library, see the [Migration Guide](https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react/MIGRATION.md#input-component). + ## References [MetaMask Design System Guides](https://www.notion.so/MetaMask-Design-System-Guides-Design-f86ecc914d6b4eb6873a122b83c12940)