@dreamworld/dw-input

A Material Design outlined text-field and auto-grow textarea library implemented as LitElement Web Components, providing full validation, tooltip messaging, value formatting hooks, and rich icon support.

Exports: <dw-input>, <dw-textarea>, <dw-email-input>

1. User Guide

Installation & Setup

yarn add @dreamworld/dw-input

This package is an ES module. Import each component as needed:

// Core input (Material Design outlined text field)
import '@dreamworld/dw-input/dw-input.js';

// Auto-grow undecorated textarea
import '@dreamworld/dw-input/dw-textarea.js';

// Email-specialized input
import '@dreamworld/dw-input/dw-email-input.js';

To extend the class directly:

import { DwInput } from '@dreamworld/dw-input/dw-input.js';
import { DwTextarea } from '@dreamworld/dw-input/dw-textarea.js';
import { DwEmailInput } from '@dreamworld/dw-input/dw-email-input.js';

Basic Usage

<!-- Simple labeled input -->
<dw-input label="Full Name" placeholder="Enter your name" required></dw-input>

<!-- Number input with bounds -->
<dw-input label="Age" type="number" .minNumber=${1} .maxNumber=${120}></dw-input>

<!-- Disabled input with pre-filled value -->
<dw-input label="Account ID" value="12345" disabled></dw-input>

<!-- Read-only input with icons -->
<dw-input label="Search" readOnly icon="search" iconTrailing="close"></dw-input>

<!-- Input with hint and validation -->
<dw-input
  label="Username"
  required
  hint="Letters and numbers only"
  pattern="[a-zA-Z0-9]+"
  error="Invalid characters"
></dw-input>

<!-- Multiline (textarea) mode -->
<dw-input label="Notes" multiline .minHeight=${80} .maxHeight=${200}></dw-input>

<!-- Auto-grow undecorated textarea -->
<dw-textarea .minHeight=${80} .maxHeight=${200} placeholder="Type here..."></dw-textarea>

<!-- Email input -->
<dw-email-input label="Email Address" required></dw-email-input>

API Reference — <dw-input>

Props

| Name | Type | Default | Required | Description | |------|------|---------|----------|-------------| | name | String | '' | No | The name attribute of the underlying input element | | value | String | '' | No | Current value of the input field | | type | String | 'text' | No | Input type (e.g. text, email, number, password) | | inputmode | String | undefined | No | HTML inputmode attribute (e.g. numeric, email) | | maxNumber | Number | undefined | No | Maximum value when type="number" | | minNumber | Number | undefined | No | Minimum value when type="number" | | step | Number | 'any' | No | Step interval for legal numbers when type="number" | | label | String | undefined | No | Floating label text | | placeholder | String | '' | No | Placeholder text shown inside the field | | disabled | Boolean | false | No | Disables the input | | readOnly | Boolean | false | No | Makes the input read-only | | required | Boolean | false | No | Marks input as required; validated on validate() | | pattern | String | '(.*?)' | No | Regex pattern validated during validate() | | allowedPattern | String | undefined | No | Regex pattern checked on each keystroke; disallows non-matching characters | | minLength | Number | 0 | No | Minimum number of characters | | maxLength | Number | 524288 | No | Maximum number of characters accepted | | charCounter | Boolean | false | No | Shows character counter; requires maxLength to be set | | hint | String | undefined | No | Helper text shown below the field (only while focused by default) | | hintPersistent | Boolean | false | No | Always show hint text regardless of focus state | | hintInTooltip | Boolean | false | No | Show hint in a tooltip triggered by a trailing info icon instead of below the field | | hintTooltipActions | Array | undefined | No | Array of tooltipAction objects shown as buttons inside the hint tooltip | | error | String\|Function\|Object | '' | No | Error message shown when invalid. Can be a string, or a Function(value) => string | | errorInTooltip | Boolean | false | No | Show error in a tooltip triggered by a trailing error icon | | errorTooltipActions | Array | undefined | No | Array of tooltipAction objects shown as buttons inside the error tooltip | | warning | String\|Function\|Object | undefined | No | Warning message. Can be a string or Function(value) => string | | warningInTooltip | Boolean | false | No | Show warning in a tooltip triggered by a trailing warning icon | | warningTooltipActions | Array | undefined | No | Array of tooltipAction objects shown as buttons inside the warning tooltip | | tipPlacement | String | 'bottom-end' | No | Tooltip placement; see Tippy.js placement docs | | tipExtraOptions | Object | undefined | No | Additional options passed directly to the Tippy.js tooltip instance | | icon | String | undefined | No | Leading (prefix) icon name | | iconTrailing | String | undefined | No | Trailing (suffix) icon name | | iconSize | Number | 24 | No | Size in px for both leading and trailing icons | | iconButtonSize | Number | 24 | No | Size in px for icon buttons (when clickableIcon=true) | | iconFont | String | undefined | No | Icon font variant: 'FILLED' or 'OUTLINED' | | symbol | Boolean | false | No | When true, uses Material Symbols icon set | | clickableIcon | Boolean | false | No | Makes the trailing icon interactive (rendered as icon button) | | autoSelect | Boolean | false | No | Auto-selects all text when the field receives focus | | multiline | Boolean | false | No | Renders the input as a textarea | | minHeight | Number | 42 | No | Minimum height in px when multiline=true | | maxHeight | Number | undefined | No | Maximum height in px when multiline=true; enables scroll beyond this | | disabledEnter | Boolean | false | No | Prevents newline insertion on Enter key when multiline=true | | dense | Boolean | false | No | Applies dense (compact) field style | | showAsFilled | Boolean | false | No | Renders field in Material Design filled style instead of outlined | | noHintWrap | Boolean | false | No | Forces hint text to render on a single line (no wrapping) | | prefixText | String | '' | No | Static prefix text rendered inside the field before the input | | suffixText | String | undefined | No | Static suffix text rendered inside the field after the input | | truncateOnBlur | Boolean | false | No | Trims whitespace from value when the field loses focus | | originalValue | String | undefined | No | Reference value used to detect changes when highlightChanged=true | | highlightChanged | Boolean | false | No | Highlights the field when value !== originalValue | | highlightedValue | Boolean | false | No | When true, displays value in highlighted style unconditionally | | valueEqualityChecker | Function | undefined | No | Custom equality function (val1, val2) => Boolean used by highlightChanged logic | | errorMessages | Object | (internal defaults) | No | Map of validity-key → error string overrides (e.g. { typeMismatch: '...' }) | | validity | Object | undefined | No | The ValidityState object of the underlying input element | | autocomplete | String | 'off' | No | Maps to the HTML autocomplete attribute |

Events

| Event | When Fired | detail | |-------|-----------|---------| | value-changed | When the user types and the value changes | { value: String } | | change | On blur after the user has modified the value | none | | enter | When the Enter key is pressed | { value: String, event: KeyboardEvent } | | esc | When the Escape key is pressed | { value: String, event: KeyboardEvent } | | show-password | When the user clicks the visibility icon to reveal password | none | | hide-password | When the user clicks the visibility icon to hide password | none | | action | When a tooltip action button is clicked | action name (String) |

Methods

| Method | Signature | Returns | Description | |--------|-----------|---------|-------------| | focus | focus() | void | Sets focus to the input | | setCaretPosition | setCaretPosition(caretPos: Number) | void | Moves caret to the specified character position | | selectText | selectText() | void | Selects all text in the input | | checkValidity | checkValidity() | Boolean | Runs validation; returns true if valid | | setCustomValidity | setCustomValidity(msg: String) | void | Sets a custom validity message (empty string clears it) | | reportValidity | reportValidity() | Boolean | Runs validation and reports result; returns true if valid | | validate | validate() | Boolean | Legacy alias for checkValidity(); returns false if invalid | | layout | layout() | void | Triggers MDC layout recalculation (use after dynamic show/hide) | | parseValue | parseValue(text: String) => String | String | Override in subclasses to parse raw input text into a structured value | | formatText | formatText(value: String) => String | String | Override in subclasses to format a structured value into display text | | showPassword | showPassword() | void | Switches type to 'text' to reveal password | | hidePassword | hidePassword() | void | Switches type back to 'password' | | DwInput.setErrorMessages (static) | DwInput.setErrorMessages(messages: Object) | void | Sets default error messages at the application level for all instances |

CSS Custom Properties

| Property | Default | Controls | |----------|---------|---------| | --dw-input-outlined-idle-border-color | rgba(0,0,0,0.38) | Outlined border color in idle state | | --dw-input-outlined-hover-border-color | rgba(0,0,0,0.87) | Outlined border color on hover | | --dw-input-outlined-disabled-border-color | rgba(0,0,0,0.06) | Outlined border color when disabled | | --dw-input-outlined-readonly-idle-border-color | — | Outlined border color when read-only | | --dw-input-text-field-color | var(--mdc-theme-text-primary, rgba(0,0,0,0.87)) | Input text color | | --dw-input-fill-color | whitesmoke | Background fill when showAsFilled=true | | --dw-input-filled-bottom-border-color | rgba(0,0,0,0.42) | Bottom border color for filled style | | --dw-input-filled-hover-bottom-border-color | rgba(0,0,0,0.87) | Hover bottom border color for filled style | | --dw-input-value-updated-color | var(--mdc-theme-primary, #02afcd) | Text color when value is changed (highlightChanged) | | --dw-input-outlined-updated-bg-color | var(--mdc-theme-primary, #02afcd) | Background overlay when value is changed | | --dw-input-helper-line-position | relative | CSS position of the hint/error helper line | | --dw-input-white-space | — | white-space property of input text when not focused | | --dw-input-text-overflow | — | text-overflow property when not focused | | --dw-input-overflow | — | overflow property when not focused | | --dw-input-direction | — | Text direction (ltr/rtl) when not focused | | --dw-input-text-align | — | Text alignment when not focused | | --dw-icon-color | rgba(0,0,0,0.54) | Icon color | | --dw-icon-color-disabled | rgba(0,0,0,0.38) | Icon color when disabled | | --mdc-theme-primary | rgba(98,0,238,0.87) | Material Design primary color (focus ring, active state) | | --mdc-theme-text-primary | rgba(0,0,0,0.87) | Primary text color | | --mdc-theme-text-secondary | rgba(0,0,0,0.6) | Secondary/label text color | | --mdc-theme-text-disabled | rgba(0,0,0,0.38) | Disabled text color | | --mdc-theme-error | #b00020 | Error state color | | --mdc-theme-text-warning | #ffa726 | Warning state color |

API Reference — <dw-textarea>

Props

| Name | Type | Default | Required | Description | |------|------|---------|----------|-------------| | value | String | '' | No | Current textarea value | | minHeight | Number | 42 | No | Minimum height in px; textarea auto-grows from this value | | maxHeight | Number | undefined | No | Maximum height in px; vertical scroll activates beyond this | | maxLength | Number | 524288 | No | Maximum number of characters | | minLength | Number | 0 | No | Minimum number of characters | | readOnly | Boolean | false | No | Makes the textarea read-only | | disabled | Boolean | false | No | Disables the textarea | | required | Boolean | false | No | Marks the textarea as required | | placeholder | String | '' | No | Placeholder text | | disabledEnter | Boolean | false | No | Prevents newline insertion on Enter key | | undecorated | Boolean | false | No | Hides the border when true | | showPlaceholderOnFocusOnly | Boolean | false | No | Hides placeholder until the element is focused | | autocomplete | String | 'off' | No | HTML autocomplete attribute |

Events

| Event | When Fired | detail | |-------|-----------|---------| | value-changed | When the value changes (user input or programmatic) | { value: String } | | change | On blur after value was modified by the user | none | | input | As the user types (mirrors native input event) | none | | enter | When Enter key is pressed | { value: String, event: KeyboardEvent } | | esc | When Escape key is pressed | { value: String, event: KeyboardEvent } | | blur | When the textarea loses focus | { value: String, event: FocusEvent } |

Methods

| Method | Signature | Returns | Description | |--------|-----------|---------|-------------| | focus | focus() | void | Sets focus and moves caret to end of text | | focusToEnd | focusToEnd() | void | Alias for focus() (backward compatibility) | | moveToEnd | moveToEnd() | void | Moves caret to end of text and resizes the textarea | | moveToStart | moveToStart() | void | Moves caret to start of text and resizes the textarea | | blur | blur() | void | Removes focus from the textarea | | validate | validate() | Boolean | Validates the textarea; returns false if invalid | | checkValidity | checkValidity() | Boolean | Checks validity; returns true if valid | | setCustomValidity | setCustomValidity(msg: String) | void | Sets a custom validity message (empty string clears it) | | validity (getter) | get validity() | ValidityState | Returns the ValidityState of the underlying <textarea> |

CSS Custom Properties

| Property | Default | Controls | |----------|---------|---------| | --dw-textarea-padding | 0px | Internal padding of the textarea | | --mdc-theme-text-primary | rgba(0,0,0,0.87) | Text color | | --mdc-theme-text-hint-on-background | rgba(0,0,0,0.38) | Placeholder/hint text color | | --mdc-theme-secondary | — | Focused border/outline color | | --divider-color | — | Border color |

Note: dw-textarea has no default border or background color. Apply border and background directly to the dw-textarea element at the usage site. Apply a typography class (e.g. from @dreamworld/material-styles) to control font styles — no default typography is applied.

API Reference — <dw-email-input>

<dw-email-input> extends <dw-input> with no additional props, events, or CSS variables. It differs only in its constructor defaults:

| Property | Value set in constructor | |----------|--------------------------| | type | 'email' | | errorMessages.typeMismatch | 'Invalid Email' |

All props, methods, events, and CSS custom properties from <dw-input> are inherited.

<dw-email-input label="Email Address" required></dw-email-input>

Configuration Options

Application-Level Error Messages

Override default error messages for all <dw-input> instances in your application:

import { DwInput } from '@dreamworld/dw-input/dw-input.js';

DwInput.setErrorMessages({
  valueMissing: 'This field is required.',
  typeMismatch: 'Please enter a valid value.',
  patternMismatch: 'The format is incorrect.',
  tooShort: 'Too short.',
  tooLong: 'Too long.',
  rangeUnderflow: 'Value is too low.',
  rangeOverflow: 'Value is too high.',
});

Tooltip Action Object Shape

Used with hintTooltipActions, errorTooltipActions, and warningTooltipActions:

{
  name: String,    // Identifier emitted with the `action` event
  label: String,   // Button label displayed in the tooltip
  danger: Boolean  // When true, renders the button in a danger/destructive style
}

Advanced Usage

Value Parsing & Text Formatting

Override parseValue and formatText in a subclass to decouple the internal value from the displayed text. This enables custom input formats (e.g. locale-formatted numbers, date inputs).

• formatText(value) — receives value (the structured property value), returns the string to display in the text field.
• parseValue(text, userEditing) — receives the raw input text and a Boolean indicating whether the user is still editing. Returns the parsed value to assign to value.
  • Returning undefined during userEditing=true leaves value unchanged, enabling intermediate invalid state handling.
  • Returning any value (including undefined) on blur (userEditing=false) sets value.

Example — locale-formatted number input:

import { DwInput } from '@dreamworld/dw-input/dw-input.js';

class FormattedInput extends DwInput {
  formatText(value) {
    value = value.toString().replace(/,/g, '').replace(/ /g, '');
    return Number(value).toLocaleString();
  }

  parseValue(text) {
    text = text.replace(/,/g, '').replace(/ /g, '');
    return Number(text);
  }
}

customElements.define('formatted-input', FormattedInput);

<formatted-input label="Amount" value="1000000"></formatted-input>
<!-- Displays: 1,000,000 -->

Custom Styling via Subclass

import { DwInput } from '@dreamworld/dw-input/dw-input.js';
import { css } from 'lit';

class RoundedInput extends DwInput {
  static get styles() {
    return [
      DwInput.styles,
      css`
        .mdc-text-field {
          border-radius: 8px;
        }
      `
    ];
  }
}

customElements.define('rounded-input', RoundedInput);

Highlight Changed Value

Highlight a field when its current value differs from a reference value — useful in edit forms:

<dw-input
  label="Username"
  value="john_new"
  originalValue="john_old"
  highlightChanged
></dw-input>

For custom equality logic:

document.querySelector('dw-input').valueEqualityChecker = (val1, val2) => {
  return String(val1).trim() === String(val2).trim();
};

Tooltip-Based Hint, Error, and Warning

<dw-input
  label="Password"
  hintInTooltip
  hint="Must be at least 8 characters"
  errorInTooltip
  error="Password is too weak"
  .errorTooltipActions=${[{ name: 'reset', label: 'Reset Password', danger: false }]}
></dw-input>

Listen for action events:

document.querySelector('dw-input').addEventListener('action', (e) => {
  console.log('Tooltip action clicked:', e.detail); // e.g. 'reset'
});

Password Field

<dw-input type="password" label="Password"></dw-input>

The visibility toggle icon is shown automatically. Listen to show/hide events:

const input = document.querySelector('dw-input');
input.addEventListener('show-password', () => console.log('Password revealed'));
input.addEventListener('hide-password', () => console.log('Password hidden'));

// Or control programmatically:
input.showPassword();
input.hidePassword();

Auto-Grow Textarea Examples

<!-- Grows from 80px to 200px, then scrolls -->
<dw-textarea .minHeight=${80} .maxHeight=${200}></dw-textarea>

<!-- Fixed height with scroll -->
<dw-textarea .minHeight=${70} .maxHeight=${70}></dw-textarea>

<!-- Prevent newline on Enter -->
<dw-textarea .minHeight=${70} .maxHeight=${70} disabledEnter></dw-textarea>

<!-- Read-only -->
<dw-textarea .minHeight=${80} .maxHeight=${200} .readOnly=${true}></dw-textarea>

2. Developer Guide / Architecture

Architecture Overview

Design Patterns

| Pattern | Where Applied | Purpose | |---------|--------------|---------| | Mixin / Composition | DwFormElement(LitElement) base class | Injects form-integration behavior (validity reporting, form participation) without inheritance conflicts | | Template Method | parseValue() and formatText() hooks | Defines the algorithm skeleton in DwInput; subclasses override specific steps to customize value serialization | | Adapter / Facade | MDCTextField instance management (_textFieldInstance) | Wraps the Material Components Web imperative API behind a reactive LitElement property model | | Strategy | valueEqualityChecker prop | Allows the equality-check algorithm to be swapped at runtime without subclassing | | Thin Specialization | DwEmailInput extends DwInput | Reuses the full DwInput implementation; only constructor defaults differ |

Module Responsibilities

| File | Responsibility | |------|----------------| | dw-input.js | Core input component — rendering, validation, MDC lifecycle, tooltip integration, value formatting hooks, icon/password handling | | mdc-text-field-css.js | Exports TextfieldStyle — the full Material Design text field CSS as a Lit css tagged template literal; imported and composed into DwInput.styles | | dw-textarea.js | Standalone auto-grow undecorated textarea; minimal styling, no MDC dependency, exposes its own props/events/methods API | | dw-email-input.js | Extends DwInput; sets type='email' and errorMessages.typeMismatch in the constructor |

Runtime Dependencies

| Package | Role | |---------|------| | lit (via LitElement) | Declarative reactive rendering and DOM update scheduling | | @material/textfield | MDCTextField imperative instance — manages floating label, ripple, and outline animations | | @dreamworld/dw-form | DwFormElement mixin — hooks the component into native <form> participation and validation lifecycles | | @dreamworld/dw-tooltip | Renders hint / error / warning tooltip overlays | | @dreamworld/dw-icon | Renders leading and trailing icons | | @dreamworld/dw-icon-button | Renders clickable trailing icon buttons (when clickableIcon=true or for password visibility) | | @dreamworld/dw-button | Renders tooltip action buttons | | @dreamworld/device-info | Detects virtual keyboard presence to conditionally adjust layout behavior | | lodash-es | Utility functions (debounce, equality checks) |