gadgets
Version:
Reusable React UI widgets - This is my widget library. There are many like it, but this one is mine...
101 lines (100 loc) • 4.08 kB
TypeScript
/**
* The tag list control is a basic list of strings that act as metadata for
* another control. They are used to categorize information. There are
* two types of `TagList` controls: static and dynamic. With the static
* control the list of string are given when the control is created and
* are never changed. With the dynamic control the list of tags can
* be added or removed from the list. Each operation results in an event
* signalling what occurred (new or delete). The tags from the events
* must them be used to update the parent state and pass the new tags
* back into the component (this is an uncontrolled component)
*
* ## Screen:
* <img src="https://github.com/jmquigley/gadgets/blob/master/images/tagList.png" width="40%" />
*
* ## Examples:
*
* ##### Dynamic TagList
* ```javascript
* import {TagList} from 'gadgets';
*
* <TagList tags={['one', 'two', 'three']} useinput />
* ```
*
* ##### Static TagList
* ```javascript
* import {TagList} from 'gadgets';
*
* <TagList tags={['one', 'two', 'three']} />
* ```
*
* ## API
* #### Events
* - `onBlur` - invoked when the user leaves the control. This event works
* like the escape key (resets the input)
* - `onChange` - invoked as the user presses keys. Receives the a reference
* to the `HTMLInputElement`
* - `onDelete(tag: string, tags: string[])` - invoked when a user removes
* a tag from the list. The tag that is removed is given to the callback as
* the first parameter. The second parameter is the full list.
* - `onKeyDown` - invoked when the user first presses a key. This watches for
* the escape key within the control.
* - `onKeyPress` - invoked whne the user presses a key. This watches for the
* enter key within the control.
* - `onNew(tag: string, tags: string[])` - invoked when the user adds a new
* tag to the list. The tag that is added is given to the callback as the first
* parameter. The second parameter is the full list.
*
* #### Styles
* - `ui-taglist` - style placed on the root div of the control
*
* #### Properties
* - `nosort=false {boolean}` - if set to true, then the tags will not be
* sorted when displayed, otherwise they are sorted.
* - `placeholder="new" {string}` - the string placeholder in the input text
* for new tags.
* - `tags=[] {string[]|string}` - the list of tag strings initially added to
* the control. This is only respected on creation of the control
* - `useinput=false {boolean}` - if set to true, then the user is allowed to
* manipulate the tag list inline, otherwise the list is statically created.
*
* @module TagList
*/
import * as React from "react";
import { BaseComponent, BaseProps, BaseState } from "../shared";
export interface TagListProps extends BaseProps {
nosort?: boolean;
onBlur?: (e: React.FocusEvent<HTMLInputElement>) => void;
onChange?: (e: React.ChangeEvent<HTMLInputElement>) => void;
onDelete?: (tag: string, tags: string[]) => void;
onKeyDown?: (e: React.KeyboardEvent<HTMLInputElement>) => void;
onKeyPress?: (e: React.KeyboardEvent<HTMLInputElement>) => void;
onNew?: (tag: string, tags: string[]) => void;
placeholder?: string;
tags?: string[] | string;
useinput?: boolean;
}
export interface TagListState extends BaseState {
inputText: string;
}
export declare class TagList extends BaseComponent<TagListProps, TagListState> {
static readonly defaultProps: TagListProps;
constructor(props: TagListProps);
/**
* Retrieves a sanitized version of the input tag list. The component can
* accept a string list or an array of strings. This method reads the props
* for the tags and ensures that it is converted to an array of strings.
* all blank tags are removed from the array.
*/
readonly tags: string[];
private buildTags;
private buildTextInputField;
private clearInput;
private handleBlur;
private handleChange;
private handleDelete;
private handleKeyDown;
private handleKeyPress;
render(): JSX.Element;
}
export default TagList;