svelte-tel-input 3.2.0 → 3.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE.md +21 -1
- package/README.md +233 -1
- package/package.json +1 -1
package/LICENSE.md
CHANGED
|
@@ -1 +1,21 @@
|
|
|
1
|
-
|
|
1
|
+
The MIT License (MIT)
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2022 - Present Gyorgy Kallai, Budapest, Hungary.
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1 +1,233 @@
|
|
|
1
|
-
|
|
1
|
+
<a name="readme-top"></a>
|
|
2
|
+
|
|
3
|
+
[](https://badge.fury.io/js/svelte-tel-input)
|
|
4
|
+
|
|
5
|
+
# Svelte Tel Input
|
|
6
|
+
|
|
7
|
+
> Lightweight svelte tel/phone input standardizer.
|
|
8
|
+
|
|
9
|
+
<img src="https://raw.githubusercontent.com/gyurielf/svelte-tel-input/main/static/demo.gif" width="600px" align="center">
|
|
10
|
+
|
|
11
|
+
🔥 Check it out live [here](https://svelte-tel-input.vercel.app/)
|
|
12
|
+
|
|
13
|
+
## Installation
|
|
14
|
+
|
|
15
|
+
Svelte Tel Input is distributed via [npm](https://www.npmjs.com/package/svelte-tel-input).
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
npm install --save svelte-tel-input
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
## Features
|
|
22
|
+
|
|
23
|
+
- Parse and validate phone number.You can store one exact format (`E164`), no matter how users type their phone numbers.
|
|
24
|
+
- Format (specified to its country), to make it more readable.
|
|
25
|
+
- Prevent non-digits typing into the input, except the leading `+` sign (and `space` optionally).
|
|
26
|
+
- Handle copy-pasted phone numbers, it's sanitize non-digit characters except the leading `+` sign (and `space` optionally).
|
|
27
|
+
- Automatic placeholder generation for the selected country.
|
|
28
|
+
|
|
29
|
+
## Usage
|
|
30
|
+
|
|
31
|
+
### Advanced
|
|
32
|
+
|
|
33
|
+
_Snippet would be too long_ - [REPL](https://stackblitz.com/edit/svelte-tel-input-repl-1jfaar?file=README.md) (StackBlitz)
|
|
34
|
+
|
|
35
|
+
### Basic
|
|
36
|
+
|
|
37
|
+
[REPL](https://stackblitz.com/edit/svelte-tel-input-repl?file=README.md) (StackBlitz)
|
|
38
|
+
|
|
39
|
+
```html
|
|
40
|
+
<script lang="ts">
|
|
41
|
+
import { TelInput, normalizedCountries } from 'svelte-tel-input';
|
|
42
|
+
import type { DetailedValue, CountryCode, E164Number } from 'svelte-tel-input/types';
|
|
43
|
+
|
|
44
|
+
// Any Country Code Alpha-2 (ISO 3166)
|
|
45
|
+
let selectedCountry: CountryCode | null = 'HU';
|
|
46
|
+
|
|
47
|
+
// You must use E164 number format. It's guarantee the parsing and storing consistency.
|
|
48
|
+
let value: E164Number | null = '+36301234567';
|
|
49
|
+
|
|
50
|
+
// Validity
|
|
51
|
+
let valid = true;
|
|
52
|
+
|
|
53
|
+
// Optional - Extended details about the parsed phone number
|
|
54
|
+
let detailedValue: DetailedValue | null = null;
|
|
55
|
+
</script>
|
|
56
|
+
|
|
57
|
+
<div class="wrapper">
|
|
58
|
+
<select
|
|
59
|
+
class="country-select {!valid && 'invalid'}"
|
|
60
|
+
aria-label="Default select example"
|
|
61
|
+
name="Country"
|
|
62
|
+
bind:value={selectedCountry}
|
|
63
|
+
>
|
|
64
|
+
<option value={null} hidden={selectedCountry !== null}>Please select</option>
|
|
65
|
+
{#each normalizedCountries as country (country.id)}
|
|
66
|
+
<option
|
|
67
|
+
value={country.iso2}
|
|
68
|
+
selected={country.iso2 === selectedCountry}
|
|
69
|
+
aria-selected={country.iso2 === selectedCountry}
|
|
70
|
+
>
|
|
71
|
+
{country.iso2} (+{country.dialCode})
|
|
72
|
+
</option>
|
|
73
|
+
{/each}
|
|
74
|
+
</select>
|
|
75
|
+
<TelInput bind:country={selectedCountry} bind:value bind:valid bind:detailedValue class="basic-tel-input {!isValid && 'invalid'}" />
|
|
76
|
+
</div>
|
|
77
|
+
|
|
78
|
+
<style>
|
|
79
|
+
.wrapper :global(.basic-tel-input) {
|
|
80
|
+
height: 32px;
|
|
81
|
+
padding-left: 12px;
|
|
82
|
+
padding-right: 12px;
|
|
83
|
+
border-radius: 6px;
|
|
84
|
+
border: 1px solid;
|
|
85
|
+
outline: none;
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
.wrapper :global(.country-select) {
|
|
89
|
+
height: 36px;
|
|
90
|
+
padding-left: 12px;
|
|
91
|
+
padding-right: 12px;
|
|
92
|
+
border-radius: 6px;
|
|
93
|
+
border: 1px solid;
|
|
94
|
+
outline: none;
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
.wrapper :global(.invalid) {
|
|
98
|
+
border-color: red;
|
|
99
|
+
}
|
|
100
|
+
</style>
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
<p align="right">(<a href="#readme-top">back to top</a>)</p>
|
|
104
|
+
|
|
105
|
+
## Props
|
|
106
|
+
|
|
107
|
+
The default export of the library is the main TelInput component. It has the following props:
|
|
108
|
+
|
|
109
|
+
| Property name | Type | Default Value | Usage |
|
|
110
|
+
| ------------- | ---------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
111
|
+
| value | `E164Number \| null` | `null` | [E164](https://en.wikipedia.org/wiki/E.164) is the international format of phone.numbers. This is the main entry point to store and/or load an existent phone number. |
|
|
112
|
+
| country | `CountryCode \| null` | `null` | It's accept any Country Code Alpha-2 (ISO 3166). You can set manually (e.g: by the user via a select). The parser will inspect the entered phone number and if it detect a valid country calling code, then it's automatically set the country to according to the detected country calling code. E.g: `+36` -> `HU` |
|
|
113
|
+
| disabled | `boolean` | `false` | It's block the parser and prevent entering input. You must handle its styling on your own. |
|
|
114
|
+
| valid | `boolean` | `true` | Indicates whether the entered tel number validity. |
|
|
115
|
+
| detailedValue | `DetailedValue \|null` | `null` | All of the formatted results of the tel input. |
|
|
116
|
+
| class | `string` | `` | You can pass down any classname to the component |
|
|
117
|
+
| required | `boolean \| null` | `null` | Set the required attribute on the input element |
|
|
118
|
+
| options | `TelInputOptions` | check below | Allow or disallow spaces in the input field |
|
|
119
|
+
|
|
120
|
+
Config options:
|
|
121
|
+
|
|
122
|
+
```javascript
|
|
123
|
+
{
|
|
124
|
+
// Generates country specific placeholder for the selected country.
|
|
125
|
+
autoPlaceholder: true,
|
|
126
|
+
// Allow or disallow spaces in the input field
|
|
127
|
+
spaces: true,
|
|
128
|
+
// If you have a parsed phone number and you change country manually from outside, then it's set the `valid` prop to false.
|
|
129
|
+
invalidateOnCountryChange: false
|
|
130
|
+
}
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
<p align="right">(<a href="#readme-top">back to top</a>)</p>
|
|
134
|
+
|
|
135
|
+
## Dispatched Events
|
|
136
|
+
|
|
137
|
+
The default export of the library is the main TelInput component. It has the following props:
|
|
138
|
+
|
|
139
|
+
| Event name | Type |
|
|
140
|
+
| ------------------- | ---------------------- |
|
|
141
|
+
| updateValue | `E164Number \| null` |
|
|
142
|
+
| updateDetailedValue | `DetailedValue \|null` |
|
|
143
|
+
| updateCountry | `CountryCode \| null` |
|
|
144
|
+
| updateValid | `boolean` |
|
|
145
|
+
| parseError | `string` |
|
|
146
|
+
|
|
147
|
+
## Use case of the event driven behavior
|
|
148
|
+
|
|
149
|
+
```typescript
|
|
150
|
+
<script lang="ts">
|
|
151
|
+
// Imports, etc....
|
|
152
|
+
let value: E164Number | null = null;
|
|
153
|
+
const yourHandler = (e: CustomEvent<E164Number | null>) => {
|
|
154
|
+
value = e.detail //
|
|
155
|
+
// do stuff...
|
|
156
|
+
};
|
|
157
|
+
</script>
|
|
158
|
+
|
|
159
|
+
<TelInput value={cachedValue ?? value} on:updateValue={yourHandler} ... />
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
<p align="right">(<a href="#readme-top">back to top</a>)</p>
|
|
163
|
+
|
|
164
|
+
## Caveats
|
|
165
|
+
|
|
166
|
+
- In order to reset `value` and/or `country` from outside (you must pass (or set if you binded) `null` for the property) have some side-effects:
|
|
167
|
+
|
|
168
|
+
- Reseting the `value` will set (keep the `country` as is):
|
|
169
|
+
- `detailedValue` to `null`
|
|
170
|
+
- dispatch `updateDetailedValue` event
|
|
171
|
+
- Reseting the `country` will set:
|
|
172
|
+
- `value` to `null`
|
|
173
|
+
- `detailedValue` to `null`
|
|
174
|
+
- `valid` to `true` if `invalidateOnCountryChange` config option is false (_@default false_). Otherwise it will be `false`.
|
|
175
|
+
- and dispatch `updateValid`, `updateValue` `updateDetailedValue` events
|
|
176
|
+
- Reseting both `value` and `country` will set:
|
|
177
|
+
- `valid` to `true`
|
|
178
|
+
- `detailedValue` to `null`;
|
|
179
|
+
|
|
180
|
+
- Let's assume you pass a `US` `E164` number, which can be a partial `E164`, but long enough to determine the country and you pass `DE` country directly. The country will be updated to `US`, which is determined from the `E164` in this example. If the `E164` is not long enough to determine its country, then the country will stay what you passed to the component (`DE`).
|
|
181
|
+
|
|
182
|
+
<p align="right">(<a href="#readme-top">back to top</a>)</p>
|
|
183
|
+
|
|
184
|
+
## Goals
|
|
185
|
+
|
|
186
|
+
- Solve the problem that a users can enter the same phone number in different formats.
|
|
187
|
+
- Storing a phone number in a standard format, that can be indexable and searchable in any database.
|
|
188
|
+
- Should be accessible for the the browser. Eg. for a `<a href="tel+36201234567 />`.
|
|
189
|
+
- The stored phone number format can be useable for any SMS gateway(e.g for 2FA) and if somebody can call the number from anywhere, it should work.
|
|
190
|
+
|
|
191
|
+
## Dependencies
|
|
192
|
+
|
|
193
|
+
[svelte](https://svelte.dev/)
|
|
194
|
+
|
|
195
|
+
[libphonenumber-js](https://gitlab.com/catamphetamine/libphonenumber-js)
|
|
196
|
+
|
|
197
|
+
<p align="right">(<a href="#readme-top">back to top</a>)</p>
|
|
198
|
+
|
|
199
|
+
## Changelog
|
|
200
|
+
|
|
201
|
+
| Package | Changelog |
|
|
202
|
+
| ------------------------------ | ------------------------- |
|
|
203
|
+
| [@gyurielf/svelte-tel-input]() | [Changelog](CHANGELOG.md) |
|
|
204
|
+
|
|
205
|
+
<p align="right">(<a href="#readme-top">back to top</a>)</p>
|
|
206
|
+
|
|
207
|
+
## Roadmap
|
|
208
|
+
|
|
209
|
+
- [x] Add Changelog
|
|
210
|
+
- [x] Add CI/CD
|
|
211
|
+
- [x] Integrate libphonenumber
|
|
212
|
+
- [x] Implement parser
|
|
213
|
+
- [x] Add basics docs and examples
|
|
214
|
+
- [x] Add advanced examples
|
|
215
|
+
- [x] Generate placeholders autimatically
|
|
216
|
+
- [x] Move to monorepo
|
|
217
|
+
- [ ] Improve A11Y
|
|
218
|
+
|
|
219
|
+
See the [open issues](https://github.com/gyurielf/svelte-tel-input/issues) for a list of proposed features (and known issues).
|
|
220
|
+
|
|
221
|
+
<p align="right">(<a href="#readme-top">back to top</a>)</p>
|
|
222
|
+
|
|
223
|
+
## Support
|
|
224
|
+
|
|
225
|
+
<a href="https://www.buymeacoffee.com/gyurielf" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" ></a>
|
|
226
|
+
|
|
227
|
+
<p align="right">(<a href="#readme-top">back to top</a>)</p>
|
|
228
|
+
|
|
229
|
+
## License
|
|
230
|
+
|
|
231
|
+
Distributed under the MIT License. See `LICENSE.md` for more information.
|
|
232
|
+
|
|
233
|
+
<p align="right">(<a href="#readme-top">back to top</a>)</p>
|