@dreamworld/dw-input

dw-input

A material input element made with lit-html. For more detail visit https://material.io/develop/web/components/input-controls/text-field/.

Installation

  npm install @dreamworld/dw-input

Usage

  @import '@dreamworld/dw-input/dw-input';

Demo

Features

• It follows material design outlines input style and provides all features of it. know more
• It auto select's text if autoSelect property is true
• Provides a validator property to add custom validations
• Set multiline to true to show input as text area
• Provide type property to set type of input e.g ("text", "email", "number"). List of all input types
• Set icon and iconTrailing to show prefix and suffix icon
• Performs validation on blur. It also performs validation on User type if input is invalid.
• hintInTooltip: way to show hint text in tooltip and tip trigger on info(grey) icon.
• error: Provides a way to show custom error message. It could be either String or Function.
• warning: Provides a way to show warning. It could be either String or Function.`
• errorInTooltip: Way to show error text in tooltip. It trigger on error(red) icon.
• warningInTooltip: Way to show warning text in tooltip. It trigger on warning(orange) icon.
• hintTooltipActions: way to add tip action while hint text in tip. on action click event named action dispatch.
• errorTooltipActions: way to add tip action while error text in tip. on action click event named action dispatch.
• warningTooltipActions: way to add tip action while warning text in tip. on action click event named action dispatch.
• tipPlacement: Tooltip placement for more see tippyJs doc.

tooltipAction

{
  name: string,
  lable: string,
  danger: boolean
}

Value parsing & Text Formatting

By default value property is exactly the text written in the text-field. But, When creating custom input elements by extending dw-input we need to change this behavior. e.g. For we want to create a date-input, whose value will always be in yyyy-mm-dd format. But, allows user to choose input format. e.g. For American user it allows to enter date in mm/dd/yyyy format and for Indian users it allows to enter date in dd/mm/yyyy format. In addition, we need 1 more feature that date input can be done without / or -. And even partial dates can be entered. e.g.

• If I enter 12, then the date will be come 12th of the current month and year. (assumed input format is dd/mmy/yyyy)
• If I enter 125, then the date will become 12th May of the current year. For such features, we need to do custom parsing of value from the input text and when user sets value property, we need to compute corresponding text representation.

This can be easily done by extending this element and then overriding following 2 functions:

• parseValue(text, userEditing):
  • Receives input-text as argument and returns parsed value. e.g. for the above case it receives user inputted string and returns string date in format yyyy-mm-dd.
  • userEditing is Boolean. When user is editing the input (focus is still in), this is true.
• formatText(value), Receives value property as argument and returns formatted text to be shown in the input field. e.g. For the above example, it receives date in yyyy-mm-dd format and it's output is date representation in dd/mm/yyyy format for indian user.

How exactly parseValue and formatText function is used internally?

• formatText: Input text needs to be formatted on 2 events.
  • On change event - blur of the Input & value is changed.
  • Integrate updates value property explicitly.
• parseValue: Value needs to be parsed when user interacts with input text-field and updates text. e.g. input and change both events.
  • When user is typing (input event); On undefined return value, value isn't changed (stays to it's last value). This allows intermediate invalid value handling. In this case input event isn't triggered on this input, because effectively value isn't changed. Please note that, null and Blank String both are used as it is. It's just for undefined.
  • When user is done editing (change event); Anything returned including undefined is set to the value property.

Methods

• focus - Focuses the input

• selectText - Selected input's text

• validate - Call this to validate input. Returns false if value is invalid.

Theme

Configure color of the icon using --dw-icon-color css variable.

Example css to change icon color

dw-input{
--dw-icon-color: green;
}

Custom input

Override dwInput class to create a custom input

class CustomInput extends DwInput {
  static get styles() {
  return [
    DwInput.styles,
    css`
      .mdc-text-field{
        border-radius: 8px;
      }`
    ];
  }
}
customElements.define('custom-input', CustomInput);

<custom-input></custom-input>

Examples

<dw-input label="Name" validator="<VALIDATION_FN>" placeholder="Enter name here" autoSelect required hint="Hint text"></dw-input>

<dw-input label="Number" disabled allowedPattern="[0-9]" value="12"></dw-input>

<dw-input label="Number" readOnly icon='search' iconTrailing='add_comment'></dw-input>

<dw-input noLabel multiline></dw-input>

dw-textarea

• The element provide way to autogrow textarea with non decore style.

Install

npm install @dw/dw-input

Usage

import  '@dreamworld/dw-input/dw-textarea';

Events

• value-changed:
  • It's fired when value property is changed. Either due to user-interaction, or it's changed programatically (by integrator).
  • It's just built for Polymer integration. And consider it as DEPRECATED. Insted use input or change as appropriate for your use-case.
• input: Same as browser default input-event. Dispatched when user changes input value, as user types or on paste.
• change: Same as browser default change-event. Dispatched on-blur if value was changed by the user.
• enter event with input value and event object.
  • Fires this user press enter key on input.
• esc event with input value and event object.
  • Fires this event if user press esc key on input.
• blur event with input value and event object.
  • Fires this event on textarea blur event.

Methods

• focus - Focus in the input
• focusToEnd- Focus in the input at last
• blur - Remove the input focus
• validate - Call this to validate input. Returns false if value is invalid.

Theme

• Configure padding of the textarea --dw-textarea-padding css variable.
• For Borders, direclty apply to dw-textarea element at the time of usage. Default border hasn't provided as it's raw element to be used for the custom purposes/UI.
• It has no (transparent) background-color, so set background-color to dw-textarea as per your need.
• For typo-graphy, set relevant typography class from your theme (e.g. material-styles) to dw-textarea. No default, typography is applied. When used in dw-input, it applies typo graphy as per the input fonts.
• Font colors: --mdc-theme-text-primary, --mdc-theme-text-hint and --mdc-theme-text-disabled are used for the font colors. So, change these css properties as per your need.

Features

• Auto grow input.
• Fixed height input with scroll
• Disabled enter
• Highlight when Updated

Auto grow input.

• Provide auto grow input based on minHeight and maxHeight property.
• Input auto grows from minHeight to maxHeight after that they show scroll.

Example with Auto grow input:

<dw-textarea  .minHeight=${80}  .maxHeight=${200}></dw-textarea>

Fixed height input with scroll

• Provide input with fixed height after that they show scroll.
• Passed to minHeight to input to show fix height

Example Fixed height input with scroll:

<dw-textarea  .minHeight=${70} .maxHeight=${70}></dw-textarea>

Disabled enter

• Provide way enter not allowed in input.
• Set disabledEnter property set as a true.

Example Disabled enter:

<dw-textarea .minHeight=${70} .maxHeight=${70} disabledEnter></dw-textarea>

Highlight when Updated

Many times you want to highlight the input when it's value is changed.

Example use-case is "Edit Form". An Edit Form has most fields with pre-filled values. Here, field whose values are updated can be highlighted. That provides nice User Experience, as user can know what has been updated. This involves both:

• Fields whose value has been changed explicitly by User.
• Fields which are automatically updated, as a result of other field change by the User.

This can be achieved simply by setting 2 properties: highlightChanged and originalValue.

<dw-input value="12" originalValue="12" highlightChanged></dw-input>

It also considers truncateOnBlur property.

As an advance use-case, you might want to change the behaviour of equality-checker (whether value has been updated or not?). This can be achived through setting property valueEqualityChecker.

Other examples

• Read only input

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