LocalizedTextInput

Description

A controlled text input component for localized single-line strings with validation states.

Installation

yarn add @commercetools-uikit/localized-text-input

npm --save install @commercetools-uikit/localized-text-input

Additionally install the peer dependencies (if not present)

yarn add react react-intl

npm --save install react react-intl

Usage

import LocalizedTextInput from '@commercetools-uikit/localized-text-input';

const Example = () => (
  <LocalizedTextInput
    value={{ en: 'House', de: 'House' }}
    onChange={
      (/** event */) => {
        // alert(event.target.name, event.target.value)
      }
    }
  />
);

export default Example;

Properties

| Props | Type | Required | Default | Description | | ------------------------------- | ----------------------------------------------------------------------------------------------------------- | :------: | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | string | | | | | name | string | | | | | autoComplete | string | | | | | aria-invalid | boolean | | | Indicate if the value entered in the input is invalid. | | aria-errormessage | string | | | HTML ID of an element containing an error message related to the input. | | value | Record | ✅ | | then input doesn't accept a "languages" prop, instead all possible languages have to exist (with empty or filled strings) on the value: { en: 'foo', de: '', es: '' } | | onChange | ChangeEventHandler | | | Gets called when any input is changed. Is called with the change event of the changed input. | | selectedLanguage | string | ✅ | | Specifies which language will be shown in case the LocalizedTextInput is collapsed. | | onBlur | FocusEventHandler | | | Called when any field is blurred. Is called with the event of that field. | | onFocus | FocusEventHandler | | | Called when any field is focussed. Is called with the event of that field. | | hideLanguageExpansionControls | boolean | | | Will hide the language expansion controls when set to true. All languages will be shown when set to true. | | defaultExpandLanguages | boolean | | | Controls whether one or all languages are visible by default | | isAutofocussed | boolean | | | Focus the input field on initial render | | isCondensed | boolean | | | Use this property to reduce the paddings of the component for a ui compact variant | | isDisabled | boolean | | | Disables all input fields. | | isReadOnly | boolean | | | Disables all input fields and shows them in read-only mode. | | placeholder | Record | | | Placeholders for each language. Object of the same shape as value. | | horizontalConstraint | unionPossible values:, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 'scale', 'auto' | | 'scale' | Horizontal size limit of the input fields. | | hasError | boolean | | | Will apply the error state to each input without showing any error message. | | hasWarning | boolean | | | Indicates the input field has a warning | | errors | Record | | | Used to show errors underneath the inputs of specific locales. Pass an object whose key is a locale and whose value is the error to show for that key. | | warnings | Record | | | A map of warnings. | | additionalInfo | Record | | | An object mapping locales to additional messages to be rendered below each input element. Example: { en: 'Some value', es: 'Algún valor', } |

data-* props

The component forwards all data attribute props. It further adds a -${language} suffix to the values of the data-test and data-track-component attributes, e.g data-test="foo" will get added to the input for en as data-test="foo-en".

Main Functions and use cases are:

• Receiving localized input from user

Static Properties

createLocalizedString(languages, existingTranslations)

This function creates a localized string. It merges the languages and the language keys of existing translations to form a localized string holding all languages. The existingTranslations argument is optional. If it is not passed, an empty localized field will be created.

const languages = ['en', 'de'];
LocalizedTextInput.createLocalizedString(languages);
// -> { en: '', de: '' }

In case existingTranslations is passed, it will merge an empty localized field with the exisiting translations. Usually this is used to ensure that a localized string contains at least the project's languages.

const languages = ['en', 'de'];
const existingTranslations = { en: 'Tree', ar: 'شجرة' };
LocalizedTextInput.createLocalizedString(languages, existingTranslations);
// -> { en: 'Tree', de: '', ar: 'شجرة' }

isEmpty(localizedField)

Returns true when all values in a localized field are empty.

LocalizedTextInput.isEmpty({});
// -> true

LocalizedTextInput.isEmpty({ en: '', de: '  ' });
// -> true

LocalizedTextInput.isEmpty({ en: 'Tree', de: '' });
// -> false

omitEmptyTranslations(localizedField)

Omits translations with empty values.

LocalizedTextInput.omitEmptyTranslations({ en: '', de: '  ' });
// -> {}

LocalizedTextInput.omitEmptyTranslations({ en: 'Tree', de: '' });
// -> { en: 'Tree' }

isTouched(touched)

Expects to be called with an object or undefined. Returns true when at least one value is truthy.

RequiredValueErrorMessage

This field exports a default error message which can be used when the field is required, but the user provided no value. You can use it as

<LocalizedTextInput hasError={isMissing} />;
{
  isMissing && <LocalizedTextInput.RequiredValueErrorMessage />;
}

getId(idPrefix, language)

Returns the id of the input field of a specific language. This is useful in case you want to create a label for the input field. You can use it as

LocalizedTextInput.getId('name', 'en');
// -> "name.en"

Or as a more complete example:

<label htmlFor={LocalizedTextInput.getId('name', 'en')}>Name</label>
<LocalizedTextInput
  id="name"
  selectedLanguage="en"
  // ...
/>

getName(idPrefix, language)

Returns the name of the input field of a specific language. . You can use it as

LocalizedTextInput.getName('slug', 'en');
// -> "slug.en"