Skip to content

Commit ac34164

Browse files
andrew-boydandrew-boyd
committed
feat: add currency and unit inputs, update changelogs and examples
1 parent e26becf commit ac34164

File tree

162 files changed

+5720
-461
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

162 files changed

+5720
-461
lines changed

‎3.inputs/currency.md‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
---
2+
title: Currency Input
3+
description: The currency input is used to create locale/currency specific parsed content
4+
navigation:
5+
title: 'Currency'
6+
pro: true
7+
---
8+
9+
:InputPageHero
10+
11+
:ProInstallSnippet
12+
13+
## Basic example
14+
15+
The `currency` input allows for restricted input of values based on the provided currency and locale.
16+
17+
## ::Example
18+
19+
name: "Currency input defaults"
20+
file: "\_examples/currency/currency-default.vue"
21+
22+
---
23+
24+
::
25+
26+
## Props
27+
28+
### Currency
29+
30+
The `currency` prop is the three letter currency code and sets the proper formatting for the specified currency. For a full list of supported currency types check: https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes
31+
32+
### Locale
33+
34+
By default, the locale used will be that of what is set in your `formkit.config.ts`. This can be overriden with the `display-locale` prop. For example, `en`, `de`, `en-IN`, `zh-CN`, etc, etc.
35+
36+
## ::Example
37+
38+
name: "Currency and Locale settings"
39+
file: "\_examples/currency/currency-simple-locale.vue"
40+
41+
---
42+
43+
::
44+
45+
## Currency Additional Props
46+
47+
### Decimals
48+
49+
If you would like to prevent decimals from being displayed, set `decimals` to `false` or `0`.
50+
51+
You can also choose to set a minimum number of decimals with the `min-decimals` prop. For example, setting the prop `min-decimals="2"` will always show 2 decimal points.
52+
53+
### Minimum and Maximum Values
54+
55+
Setting the props `min` or `max` will prevent entry of a higher or lower value.
56+
57+
### Step
58+
59+
Values can be incremented and decremented by use of the up/down keys. The degree by which the value changes is determined by the `step` prop.
60+
61+
## ::Example
62+
63+
name: "Currency Prop Exploration"
64+
file: "\_examples/currency/currency-props-explore.vue"
65+
66+
---
67+
68+
::
69+
70+
## Props & Attributes
71+
72+
## ::ReferenceTable
73+
74+
input: "currency"
75+
data: [
76+
{
77+
prop: "currency",
78+
type: "string",
79+
default: "USD",
80+
description: "Set the specified currency to use for this input"
81+
},
82+
{
83+
prop: "displayLocale",
84+
type: "string",
85+
default: "en-US",
86+
description: "Set the desired display locale to use for this input"
87+
},
88+
{
89+
prop: "decimals",
90+
type: "boolean|number",
91+
default: "null",
92+
description: "Choose to either completely disallow decimals or override the maximum number of decimals for the input"
93+
},
94+
{
95+
prop: "minDecimals",
96+
type: "number",
97+
default: "null",
98+
description: "Choose to show a minimum number of decimals should your input require this"
99+
},
100+
{
101+
prop: "min",
102+
type: "number",
103+
default: "null",
104+
description: "Minimum numeric value allowed. If zero or above, negatives will not be allowed"
105+
},
106+
{
107+
prop: "max",
108+
type: "number",
109+
default: "null",
110+
description: "Maximum numeric value allowed for this input"
111+
},
112+
{
113+
prop: "step",
114+
type: "number",
115+
default: "1",
116+
description: "When using the up/down keys, how much to modify the current value."
117+
},
118+
{
119+
prop: "valueFormat",
120+
type: "string",
121+
default: "number",
122+
description: "Choose between <code>number</code> and <code>string</code> whether you want a numeric value or a parsed string value"
123+
},
124+
]
125+
126+
---
127+
128+
::
129+
130+
## Sections
131+
132+
:SectionKeysIntro
133+
134+
### Currency input diagram
135+
136+
:FormKitInputDiagrams
137+
138+
### Keyboard Interactions
139+
140+
## ::KeyboardEventsTable
141+
142+
data: [
143+
{
144+
event: ["up", "down"],
145+
separator: '',
146+
description: "Increments through input value by current step amount.",
147+
},
148+
]
149+
150+
---
151+
152+
::

‎3.inputs/unit.md‎

Lines changed: 239 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,239 @@
1+
---
2+
title: Unit Input
3+
description: The unit input allows for restricted input of values based on the provided unit (distance, weight, temperature, etc.) and locale.
4+
navigation:
5+
title: 'Unit'
6+
pro: true
7+
---
8+
9+
:InputPageHero
10+
11+
:ProInstallSnippet
12+
13+
## Unit Input
14+
15+
The `unit` input allows for restricted input of values based on the provided unit (distance, weight, temperature, etc.) and locale.
16+
17+
## ::Example
18+
19+
name: "Unit input defaults"
20+
file: "\_examples/unit/unit.vue"
21+
22+
---
23+
24+
::
25+
26+
## Props
27+
28+
### Unit
29+
30+
The `unit` prop is the type of unit you want to display. A full list of allowed unit types are listed below:
31+
32+
## ::ColumnList
33+
34+
## listItems: ['acre', 'bit', 'byte', 'celsius', 'centimeter', 'day', 'degree', 'fahrenheit', 'fluid-ounce', 'foot', 'gallon', 'gigabit', 'gigabyte', 'gram', 'hectare', 'hour', 'inch', 'kilobit', 'kilobyte', 'kilogram', 'kilometer', 'liter', 'megabit', 'megabyte', 'meter', 'microsecond', 'mile', 'mile-scandinavian', 'milliliter', 'millimeter', 'millisecond', 'minute', 'month', 'nanosecond', 'ounce', 'percent', 'petabyte', 'pound', 'second', 'stone', 'terabit', 'terabyte', 'week', 'yard', 'year']
35+
36+
::
37+
38+
### Unit display
39+
40+
The display length can be modified by the `unitDisplay` property. Accepted values are `short`, `narrow`, and `long`.
41+
42+
## ::Example
43+
44+
name: "Unit input defaults"
45+
file: "\_examples/unit/unit-display.vue"
46+
47+
---
48+
49+
::
50+
51+
### Locale
52+
53+
By default the locale will use what you have set in your `formkit.config.ts` as the desired locale. However you can override this with the `displayLocale` prop. For example, `en-US`, `de-DE`, `en-IN`, `zh-CN`, etc, etc.
54+
55+
## ::Example
56+
57+
name: "Unit input defaults"
58+
file: "\_examples/unit/unit-locale.vue"
59+
60+
---
61+
62+
::
63+
64+
### Decimals
65+
66+
By default the decimals will display when the value contains the unit/locale decimal separator and will show default formatting decimal places to display for the given unit, however you can override this. By setting `decimals` to `false` or `0`, the value will not allow decimals or setting decimals to a numeric value will limit the maximum decimal places to that value.
67+
68+
You can also choose to set a minimum number of decimals with the `minDecimals` prop. For example, you always want to show 2 decimal places you would set `minDecimals="2"`.
69+
70+
## ::Example
71+
72+
name: "Unit input defaults"
73+
file: "\_examples/unit/unit-decimals.vue"
74+
75+
---
76+
77+
::
78+
79+
### Minimum and Maximum Values
80+
81+
Similar to a number input, you can set a `min` and `max` value.
82+
83+
## ::Example
84+
85+
name: "Unit input defaults"
86+
file: "\_examples/unit/unit-min-max.vue"
87+
88+
---
89+
90+
::
91+
92+
### Step
93+
94+
Again, similar to a number input you can use the up/down keys to step the value. By default the step is `1` but you can override that with this prop.
95+
96+
## ::Example
97+
98+
name: "Unit input defaults"
99+
file: "\_examples/unit/unit-step.vue"
100+
101+
---
102+
103+
::
104+
105+
### Value Formatting
106+
107+
The value of the input itself defaults to a number but can be formatted as a string to include information about the unit itself.
108+
109+
## ::Example
110+
111+
name: "Unit input defaults"
112+
file: "\_examples/unit/unit-value-format.vue"
113+
114+
---
115+
116+
::
117+
118+
### Value unit
119+
120+
The unit input also allows for first-party conversion of one unit type to another. In this example, we will use `unit` of type `mile`, but the value
121+
itself will be converted to `kilometers` when setting `value-unit` to `kilometer`.
122+
123+
## ::Example
124+
125+
name: "Unit type examples"
126+
file: "\_examples/unit/value-unit.vue"
127+
128+
---
129+
130+
::
131+
132+
### Unitless
133+
134+
The `unit` prop is optional, allowing for unitless values.
135+
136+
## ::Example
137+
138+
name: "Unit type examples"
139+
file: "\_examples/unit/unitless.vue"
140+
141+
---
142+
143+
::
144+
145+
## ::Callout
146+
147+
type: "warning"
148+
label: "Mixed unit types"
149+
150+
---
151+
152+
In order to convert one unit to another, they must be in the same taxonomy (so for example, you can not convert kilometers to liters).
153+
::
154+
155+
## Props & Attributes
156+
157+
## ::ReferenceTable
158+
159+
input: "unit"
160+
data: [
161+
{
162+
prop: "unit",
163+
type: "string | undefined",
164+
description: "Set the specified unit to use for this input. If undefined, will
165+
allow for unitless values."
166+
},
167+
{
168+
prop: "displayLocale",
169+
type: "string",
170+
default: "en-US",
171+
description: "Set the desired display locale to use for this input"
172+
},
173+
{
174+
prop: "decimals",
175+
type: "boolean|number",
176+
default: "null",
177+
description: "Choose to either completely disallow decimals or override the maximum number of decimals for the input"
178+
},
179+
{
180+
prop: "minDecimals",
181+
type: "number",
182+
default: "null",
183+
description: "Choose to show a minimum number of decimals should your input require this"
184+
},
185+
{
186+
prop: "min",
187+
type: "number",
188+
default: "null",
189+
description: "Minimum numeric value allowed. If zero or above, negatives will not be allowed"
190+
},
191+
{
192+
prop: "max",
193+
type: "number",
194+
default: "null",
195+
description: "Maximum numeric value allowed for this input"
196+
},
197+
{
198+
prop: "step",
199+
type: "number",
200+
default: "1",
201+
description: "When using the up/down keys, how much to modify the current value."
202+
},
203+
{
204+
prop: "valueDecimals",
205+
type: "string | number",
206+
default: undefined,
207+
description: "Determines the allowed number of decimals for the valueUnit."
208+
},
209+
{
210+
prop: "valueFormat",
211+
type: "string",
212+
default: "number",
213+
description: "Choose between <code>number</code> and <code>string</code> whether you want a numeric value or a parsed string value"
214+
},
215+
{
216+
prop: "valueUnit",
217+
type: "string",
218+
default: "undefined",
219+
description: "Used to convert the user-inputted value from one unit to another"
220+
},
221+
{
222+
prop: "unitDisplay",
223+
type: "string ('narrow' | 'short' | 'long')",
224+
default: "short",
225+
description: "Determines the length of the how the unit is represented."
226+
},
227+
]
228+
229+
---
230+
231+
::
232+
233+
## Sections
234+
235+
:SectionKeysIntro
236+
237+
### Unit input diagram
238+
239+
:FormKitInputDiagrams

0 commit comments

Comments
 (0)