Webframe UI Inputs

Webframe's Universal Input API allows the use of a single unified Input component for all user inputs.

Input Components

Input

Universal Input API

Webframe UI Inputs follow a set of standardized props, component behaviors and UI design patterns in order to provide both end users and application developers with a consistent, predictable and intuitive user experience.

In order to support Universal Input API, an input control should comply with UX design best practices, common attributes, input states, event handlers and value functions listed below.

Common Attributes

compact - whether to use the minimum width required to fit input content
defaultValue - the initial value to use when input has no value
label - a text or custom UI that clearly describes the input and appears in all input states
placeholder - a text or custom UI that only appears when input is unfilled or partially filled
tooltip - Tooltip props (or content) to display as popup on interaction with input
type - this attribute is reserved as identifier key for dynamic import of input controls
value - the internal input value (maybe different from the displayed value) via value functions.

The remaining attributes are listed in the next sections.

Input States

`disabled`

All user interactions with the input is blocked, with at least two visual cues. Example: fade and prevent focus on disabled input

`readonly`

User can read and select input value, but cannot edit it. Example: user can select and copy readonly input

`loading`

Similar to disabled state, but in addition, has a loading progress indicator. Example: user cannot interact with loading input

Event Handlers

`onChange`

The on change event should fire whenever internal input value changes.

`onFocus`

The on focus event should fire whenever the input field capturing user actions receives focus.

`onBlur`

The on blur event should fire whenever the input field capturing user actions loses focus.

Function Signature

// `onFocus` and `onBlur` event handlers have the same signature
function onChange (
  // Browser or native app event object
  event: Event,
  // Internal input value
  value: any,
  // Input `name` attribute
  name: string | undefined,
  // Input control instance (with interface like React Class Component instance)
  self: object,
  // Optional callback that needs to be fired manually when setting `event.preventDefault()`
  callback?: Function
) {}

Value Functions

`format`

A function that receives internal input value and returns the displayed value. Example: format internal Date object into human readable date string

Function Signature

function format (
  // Internal input value
  value: any,
  // Input `name` attribute
  name: string | undefined,
  // Input control instance (with interface like React Class Component instance)
  self: object
): any {}

`parse`

A function that receives internal input value and returns new value for onChange, onFocus and onBlur event handlers without modifying internal state. Example: parse a numerical string with locale aware formatting typed in by users into Number type

Function Signature

function parse (
  // Internal input value
  value: any,
  // Input `name` attribute
  name: string | undefined,
  // Input control instance (with interface like React Class Component instance)
  self: object,
  // Browser or native app event object
  event: Event,
): any {}

`normalize`

A function that receives user inputted value, sanitizes it, and returns internal input value. Example: sanitize a phone number typed in by the user to remove invalid characters

Function Signature

function normalize (
  // User inputted value
  value: any,
  // Input `name` attribute
  name: string | undefined,
  // Input control instance (with interface like React Class Component instance)
  self: object,
  // Browser or native app event object
  event: Event,
): any {}

Virtuallist Input