{"id":16332849,"url":"https://github.com/eight04/custom-input","last_synced_at":"2025-03-22T23:31:56.048Z","repository":{"id":57741927,"uuid":"76846377","full_name":"eight04/custom-input","owner":"eight04","description":"A library which can help you create custom input elements in the browser. Add mask and validation to input[text]!","archived":false,"fork":false,"pushed_at":"2019-06-28T07:30:54.000Z","size":125,"stargazers_count":7,"open_issues_count":1,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-01T19:22:20.459Z","etag":null,"topics":["inputmask","js","text-parser"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eight04.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-12-19T09:10:53.000Z","updated_at":"2020-12-01T09:10:27.000Z","dependencies_parsed_at":"2022-09-10T22:50:49.747Z","dependency_job_id":null,"html_url":"https://github.com/eight04/custom-input","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eight04%2Fcustom-input","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eight04%2Fcustom-input/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eight04%2Fcustom-input/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eight04%2Fcustom-input/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eight04","download_url":"https://codeload.github.com/eight04/custom-input/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244249330,"owners_count":20422952,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["inputmask","js","text-parser"],"created_at":"2024-10-10T23:33:16.361Z","updated_at":"2025-03-22T23:31:55.748Z","avatar_url":"https://github.com/eight04.png","language":"JavaScript","readme":"Custom Input\n============\n\n[![Build Status](https://travis-ci.com/eight04/custom-input.svg?branch=master)](https://travis-ci.com/eight04/custom-input)\n[![codecov](https://codecov.io/gh/eight04/custom-input/branch/master/graph/badge.svg)](https://codecov.io/gh/eight04/custom-input)\n[![Codacy Badge](https://api.codacy.com/project/badge/Grade/4e3a7cbd57cc4241950c12256c7cac34)](https://www.codacy.com/app/eight04/custom-input?utm_source=github.com\u0026utm_medium=referral\u0026utm_content=eight04/custom-input\u0026utm_campaign=badger)\n\nA library helping you create custom input elements in the browser. Add mask and validation to *input[text]*! Originally included in [angular-datetime](https://github.com/eight04/angular-datetime).\n\nInstallation\n------------\n\nVia npm:\n\n```\nnpm install custom-input\n```\n\n```javascript\nvar {InputMask, TextParser} = require(\"custom-input\");\n```\n\nThere is also a pre-built dist which can be used in the browser:\n\n```html\n\u003c!-- export cusomInput into global --\u003e\n\u003cscript src=\"https://unpkg.com/custom-input@0.3.1/dist/custom-input.js\"\u003e\u003c/script\u003e\n```\n```javascript\nvar {InputMask, TextParser} = customInput;\n```\n\nThe pre-built dist is compatible with IE 8, but you have to polyfill missing APIs by including [@babel/polyfill](https://babeljs.io/docs/en/babel-polyfill).\n\t\nDemo\n----\n\nA small example showing how it works:\nhttps://rawgit.com/eight04/custom-input/master/demo.html\n\nAPI reference\n-------------\n\nThis module exports following members:\n\n* `TextParser` - a parser which can parse text into model value.\n* `InputMask` - bind a parser with an `input` element and create a nice input mask.\n* `utils` - a set of utilities used by the library.\n\n### TextParser\n\n```js\nnew TextParser({\n  tokens: Array\u003cToken\u003e,\n  value: any,\n  copyValue: value =\u003e clonedValue\n})\n  =\u003e parser\n```\n\nCreate a stateful parser which can convert a model value to a string and vise versa. The parser uses a series of `Token` to construct a template. For example, the IP address: `xxx.xxx.xxx.xxx` can be represented with 7 tokens, which are *Number{1,3}*, *String \".\"*, *Number{1,3}*, *String \".\"*, *Number{1,3}*, *String \".\"*, *Number{1,3}*. The parser will try to parse text along the tokens, extract the value from text and store the value in the model.\n\n* `tokens` is a list of [Token](#token).\n* `value` is the initial model value.\n* `copyValue` is a function which can clone the model.\n\n#### parser.parse\n\n```js\nparser.parse(text: String) =\u003e parser\n```\n\nParse a string and store the value in the parser.\n\nThis method returns the parser itself.\n\n#### parser.setValue\n\n```js\nparser.setValue(value, preserveEmpty? = false) =\u003e parser\n```\n\nSet a new model value and format text according to the new value.\n\nIf `preserveEmpty` is `false`, parser will the reset empty flag of all nodes.\n\nThis method returns the parser itself.\n\n#### parser.getValue\n\n```js\nparser.getValue() =\u003e value\n```\n\nGet the model value.\n\n#### parser.getText\n\n```js\nparser.getText() =\u003e text: String\n```\n\nGet formatted text.\n\n#### parser.isEmpty\n\n```js\nparser.isEmpty(text?: String) =\u003e Boolean\n```\n\nIf `text` is supplied, parse the text without saving data and check if nodes contains empty node.\n\nIf some nodes are set, return `false`.\n\n#### parser.isInit\n\n```js\nparser.isInit() =\u003e Boolean\n```\n\nIf some nodes are empty, return `false`.\n\n\u003e **Note**: it is possible that `parser.isEmpty()` and `parser.isInit()` both returns `true`, which means all nodes are static.\n\n#### parser.unset\n\n```js\nparser.unset() =\u003e parser\n```\n\nUnset every node. Mark them as empty.\n\n#### parser.getNodes\n\n```js\nparser.getNodes(name?: String) =\u003e Array\u003cNode\u003e\n```\n\nGet a list of nodes. If `name` is provided, return the nodes having the same name.\n\n#### parser events\n\n* `change` - Emit when the model value is changed.\n\n### Token\n\nA token is an object that contains special information for parsing. Each token may represents a static string, a number, or a choice list.\n\n#### Static token\n\n```js\n{\n  type: \"static\",\n  value: String\n}\n```\n\nSet `type` to `\"static\"` to create a static token. It represent a static string.\n\n`value` is the static string value.\n\n#### Mutable token\n\nMutable tokens includes `number` token and `select` token. Some properties are shared with all types of mutable tokens:\n\n```js\n{\n  name?: String,\n  placeholder: String,\n  prior?: Number,\n  extract: (modelValue) =\u003e nodeValue,\n  restore: (modelValue, nodeValue) =\u003e void,\n  add: (modelValue, increment) =\u003e void\n}\n```\n\n* `name` property should be used with `parser.getNodes()`. There is no need to set a name if you are not going to retrieve the node.\n\n* `placeholder` is a string, which is displayed when the node is empty e.g. after calling `parser.unset()`.\n\n* `prior` controls which node should be evaluated first. If there are two nodes whose value has been changed in the same time (via `parser.parse`), the node having higher prior will apply the change to the model first.\n\n  Usually, it doesn't matter which node is evaluated first because the model value stores node values independently. But if you want to create a date string parser, you may have to decide the order carefully since each node will affect each other (e.g. the month may change when the day is changed/overflowed).\n  \n* `extract`, `restore`, and `add` are three hooks. The parser will call them when it want to perform corresponded operation to the model value.\n\n  `nodeValue` is always a number. For `number` node, it is the node value. For `select` node, it is the index starting from 1.\n  \n  `increment` is an integer, can be negative.\n  \n##### number\n\n```js\n{\n  type: \"number\",\n  minLength?: Number,\n  maxLength?: Number,\n  min?: Number,\n  max?: Number\n}\n```\n\n* `minLength` and `maxLength` controls how the number should be represented. The formatter will zero-pad the value when the length is shorter than `minLength`, and will trim the text when the length is longer than `maxLength`.\n\n* `min` and `max` controls the bounding of the number. You may want to set `min` to `0` so it won't become negative. It also affect the input mask. If the node value hits the limit, up/down arrow keys will be disabled.\n\n##### select\n\n```js\n{\n  type: \"select\",\n  select: Array\u003coption: String\u003e\n}\n```\n\n* `select` is a list of string that the text should match one of them.\n\n  When converting text to model value, the parser will find the index of matched text, plus 1, then save it as node value (store it via the `restore` hook).\n\n\n### InputMask\n\nInputMask is built with an `\u003cinput\u003e` element and a `TextParser`. It handles most of the HTML stuff like listening to events, tracking selection range of the input element, etc.\n\nAfter the mask is applied, users can only edit part of the text that is not defined as \"static\". Users can also press left/right arrow keys or tab to navigate between each mutable node. Use up/down arrow keys to increase/decrease node value. If it is a \"select\" node, it will act like a typeahead component. If the user tries to delete the node, it will be replaced by the placeholder.\n\n```js\nnew InputMask(element: Element, parser: TextParser, separators: String = \"\") =\u003e mask\n```\n\n* `element` is an object implementing [Element interface](#element-interface).\n* `parser` is a parser object.\n* `separators` - apart from tab key, add other keys that can navigate through nodes.\n\n#### mask.digest\n\n```js\nmask.digest(node: Node | void, text: String, fixError?: Boolean = false)\n```\n\nThe mask will try to parse the text. If an error occurs, try fixing it and parse it again.\n\n* `node` - can be `null`\n\n\tIf `node` is `null`, the mask will parse the text along with all nodes.\n  \n\tIf `node` is a node object, the mask will treat the text as the view value of the node.\n\n* `text` is the text which should be parsed.\n\n* `fixError`\n\n\tIf `fixError` is `true`, the mask will try hardest to fix the error, even revert back the text to the previous state.\n\n\tIf `fixError` is `false`, it will fix fatal errors, but leave `NUMBER_TOOSHORT`, `LEADING_ZERO`, etc.\n\t\n#### mask events\n\n* `digest` - emit when an digest error occurs. It may fire multiple times during one digest.\n\n### Element interface\n\nThe Element interface wraps native input element and exposes some methods similar to jQuery.\n\n#### Element.on\n\n```js\nElement.on(eventType: String, callback: (event) =\u003e void) =\u003e void\n```\n\nWrap `addEventListener`. `InputMask` will listen to `input` event for text update, you might want to proxy it for cross browser compatibility.\n\n`InputMask` uses following events:\n\n* mousedown\n* click\n* focus\n* input\n* keydown\n* keypress\n* blur\n\n#### Element.getSelection\n\n```js\nElement.getSelection() =\u003e Range | void\n```\n\nGet the current selection from the input element. Return `null` if the element is not focused/selected.\n\n\n`Range` has following shape:\n\n```js\n{\n  start: Number,\n  end: Number\n}\n```\n\n#### Element.setSelection\n\n```js\nElement.setSelection(start: Number, end: Number) =\u003e void\n```\n\nSet selection on the input. You may need to check if the input is active or some browsers will try to focus the input element when the selection changed.\n\n#### Element.val\n\n```js\nElement.val() =\u003e String\nElement.val(text: String) =\u003e void\n```\n\nGet or set the value of the input element. Like jQuery.\n\t\n### utils\n\nA set of utilities.\n\n#### utils.num2str\n\n```js\nutils.num2str(number, minLength, maxLength) =\u003e String\n```\n\nConvert a number to a string. Pad the text with zero and trim the text if needed.\n\t\nChangelog\n---------\n\n* 0.4.0 (Jun 27, 2019)\n\n  - Some changes to `InputMask`:\n  \n    - **Breaking: deleting the entire node will reset the node now.**\n    - **Breaking: prefer the node with lower index when finding the nearest node.**\n    \n  - Bump dependencies.\n\n* 0.3.1 (Sep 17, 2017)\n\n\t- Fix: use unpkg field in package.json.\n  \n* 0.3.0 (Sep 17, 2017)\n\n\t- **Change: replace node's events with event-lite.**\n  \n* 0.2.1 (Jul 24, 2017)\n\n\t- Add `textParser` arg to `token.add` and `token.restore`.\n\t- Add `name` attribute to `Node`.\n\t- Add `name` arg to `TextParser.getNodes`.\n  \n* 0.2.0 (Mar 9, 2017)\n\n\t- Allow using empty string as placeholder\n\t- The \"change\" event of TextParser now sends model value to listener.\n\t- **Drop utils.Emitter. Use node's [events](https://nodejs.org/api/events.html).**\n\t- **Change the event name of InputMask: error -\u003e digest.**\n\t- **Drop angular module, always use window.customInput.**\n  \n* 0.1.0 (Dec 19, 2016)\n\n\t- First release.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feight04%2Fcustom-input","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feight04%2Fcustom-input","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feight04%2Fcustom-input/lists"}