@spark-web/text-input 1.0.3 → 1.2.0
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/README.md +110 -13
- package/dist/declarations/src/InputAdornment.d.ts +46 -0
- package/dist/declarations/src/InputContainer.d.ts +10 -0
- package/dist/declarations/src/TextInput.d.ts +952 -941
- package/dist/declarations/src/childrenToAdornments.d.ts +12 -0
- package/dist/declarations/src/index.d.ts +4 -0
- package/dist/spark-web-text-input.cjs.dev.js +224 -37
- package/dist/spark-web-text-input.cjs.prod.js +224 -37
- package/dist/spark-web-text-input.esm.js +224 -39
- package/package.json +12 -9
- package/CHANGELOG.md +0 -75
- package/src/TextInput.stories.tsx +0 -35
- package/src/TextInput.tsx +0 -95
- package/src/index.ts +0 -5
package/README.md
CHANGED
|
@@ -7,23 +7,120 @@ Text input provides a way for inputting text. The component must be nested
|
|
|
7
7
|
within a [`Field`](/package/field). See [`Field`](/package/field) for more
|
|
8
8
|
details.
|
|
9
9
|
|
|
10
|
+
## Text Input
|
|
11
|
+
|
|
12
|
+
### Controlled
|
|
13
|
+
|
|
14
|
+
A `TextInput` can be either controlled or uncontrolled. To control a `TextInput`
|
|
15
|
+
provide a `value`, as well as an `onChange` function to set the new value when
|
|
16
|
+
the select is updated.
|
|
17
|
+
|
|
18
|
+
```jsx live
|
|
19
|
+
const [value, setValue] = React.useState(1000000.101);
|
|
20
|
+
|
|
21
|
+
return (
|
|
22
|
+
<Stack gap="large">
|
|
23
|
+
<Field label="Example controlled">
|
|
24
|
+
<TextInput value={value} onChange={e => setValue(e.target.value)} />
|
|
25
|
+
</Field>
|
|
26
|
+
<Text>The current value is: {value}</Text>
|
|
27
|
+
</Stack>
|
|
28
|
+
);
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
### Uncontrolled
|
|
32
|
+
|
|
33
|
+
A `TextInput` can also be uncontrolled, managing it's own internal state. To
|
|
34
|
+
access the value, instead of writing an onChange handler, you would use a ref to
|
|
35
|
+
get form values from the DOM.
|
|
36
|
+
|
|
37
|
+
```jsx live
|
|
38
|
+
const inputRef = React.useRef(null);
|
|
39
|
+
const [value, setValue] = React.useState('');
|
|
40
|
+
const showValueHandler = React.useCallback(() => {
|
|
41
|
+
setValue(inputRef.current?.value);
|
|
42
|
+
}, [setValue]);
|
|
43
|
+
|
|
44
|
+
return (
|
|
45
|
+
<Stack gap="large">
|
|
46
|
+
<Field label="Example uncontrolled">
|
|
47
|
+
<FloatInput ref={inputRef} />
|
|
48
|
+
</Field>
|
|
49
|
+
<Button onClick={showValueHandler}>Show input value</Button>
|
|
50
|
+
<Text>The input value is: {value}</Text>
|
|
51
|
+
</Stack>
|
|
52
|
+
);
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
### Input Adornments
|
|
56
|
+
|
|
57
|
+
You can also add adornments to the `TextInput` component (at the start or end).
|
|
58
|
+
|
|
10
59
|
```jsx live
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
60
|
+
const [value, setValue] = React.useState(10000.101);
|
|
61
|
+
|
|
62
|
+
return (
|
|
63
|
+
<Stack gap="large">
|
|
64
|
+
<Field label="Example">
|
|
65
|
+
<TextInput type="numeric" onChange={e => setValue(e.target.value)}>
|
|
66
|
+
<InputAdornment placement="start">
|
|
67
|
+
<Text>~</Text>
|
|
68
|
+
</InputAdornment>
|
|
69
|
+
<InputAdornment placement="end">
|
|
70
|
+
<Text>%</Text>
|
|
71
|
+
</InputAdornment>
|
|
72
|
+
</TextInput>
|
|
73
|
+
</Field>
|
|
74
|
+
<Text>The current value is: {value}</Text>
|
|
75
|
+
</Stack>
|
|
76
|
+
);
|
|
14
77
|
```
|
|
15
78
|
|
|
79
|
+
## InputContainer
|
|
80
|
+
|
|
81
|
+
The `InputContainer` is used internally to handle some shared styling between
|
|
82
|
+
components that are wrapped in the `Field` component.
|
|
83
|
+
|
|
84
|
+
Typically input adornments (icons or buttons that _appear_ to be inside the
|
|
85
|
+
input) will be absolutely positioning on above it and padding is applied to make
|
|
86
|
+
sure that text does not get obscured below the adornments.
|
|
87
|
+
|
|
88
|
+
On top of this, password managers will insert buttons above the input which can
|
|
89
|
+
get in the way of our adornments.
|
|
90
|
+
|
|
91
|
+
To get around these problems, we wrap the input and adornments with the
|
|
92
|
+
`InputContainer` and apply our own focus styles to an absolutely positioned
|
|
93
|
+
element that is an adjacent sibling of the input (when the input is focused).
|
|
94
|
+
|
|
95
|
+
The `InputContainer` also provides the border and background styles and has
|
|
96
|
+
slots to place the start and end adornments.
|
|
97
|
+
|
|
16
98
|
## Props
|
|
17
99
|
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
|
21
|
-
|
|
|
22
|
-
|
|
|
23
|
-
|
|
|
24
|
-
|
|
|
25
|
-
|
|
|
26
|
-
|
|
|
100
|
+
### TextInput
|
|
101
|
+
|
|
102
|
+
| Prop | Type | Default | Description |
|
|
103
|
+
| ------------ | ----------------------------------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------- |
|
|
104
|
+
| data? | [DataAttributeMap][data-attribute-map] | | Sets data attributes for the component. |
|
|
105
|
+
| type? | 'text' \| 'password' \| 'email' \| 'search' \| 'number' \| 'tel' \| 'url' | 'text' | Sets the type attribute for the component. |
|
|
106
|
+
| mode? | 'none' \| 'text' \| 'tel' \| 'url' \| 'email' \| 'numeric' \| 'decimal' \| 'search' | | Sets the input mode attribute for the component. |
|
|
107
|
+
| onBlur? | React.FocusEventHandler\<HTMLInputElement\> | | Callback function when input field component loses focuses. |
|
|
108
|
+
| onFocus? | React.FocusEventHandler\<HTMLInputElement\> | | Callback function when the input field component is in focus. |
|
|
109
|
+
| onChange? | React.FormEventHandler\<HTMLInputElement\> | | Callback function when value of the input field has been changed. |
|
|
110
|
+
| placeholder? | string | | Specifies a short hint that describes the expected value (type of value) of the input field. |
|
|
111
|
+
| value? | string \| number \| readonly string[] | | Specifies the value of the input field. |
|
|
112
|
+
| children? | [AdornmentChildren][adornment-children] | | Allows setting of adornments at the start and/or end of the input component. |
|
|
27
113
|
|
|
28
114
|
[data-attribute-map]:
|
|
29
|
-
https://
|
|
115
|
+
https://github.com/brighte-labs/spark-web/blob/e7f6f4285b4cfd876312cc89fbdd094039aa239a/packages/utils/src/internal/buildDataAttributes.ts#L1
|
|
116
|
+
[adornment-children]:
|
|
117
|
+
https://github.com/brighte-labs/spark-web/blob/d4da46200f2d6e5e9291d3c650eaaff7e53f411b/packages/text-input/src/childrenToAdornments.tsx#L12
|
|
118
|
+
|
|
119
|
+
### InputContainer
|
|
120
|
+
|
|
121
|
+
| Prop | Type | Default | Description |
|
|
122
|
+
| --------------- | ----------------------------------- | ------- | ------------------------------- |
|
|
123
|
+
| startAdornment? | ReactElement\<InputAdornmentProps\> | | Slot to start render adornment. |
|
|
124
|
+
| endAdornment? | ReactElement\<InputAdornmentProps\> | | Slot to end render adornment. |
|
|
125
|
+
|
|
126
|
+
Extra props are passed into the underlying [`Box`](/package/box) component.
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
import type { ReactElement } from 'react';
|
|
2
|
+
declare type InputAdornmentContextType = {
|
|
3
|
+
placement: PlacementType;
|
|
4
|
+
};
|
|
5
|
+
export declare const useInputAdornmentContext: () => InputAdornmentContextType | null;
|
|
6
|
+
declare const placementToPadding: {
|
|
7
|
+
readonly start: {
|
|
8
|
+
readonly paddingLeft: "medium";
|
|
9
|
+
readonly paddingRight: "xsmall";
|
|
10
|
+
};
|
|
11
|
+
readonly end: {
|
|
12
|
+
readonly paddingLeft: "xsmall";
|
|
13
|
+
readonly paddingRight: "medium";
|
|
14
|
+
};
|
|
15
|
+
};
|
|
16
|
+
declare type PlacementType = keyof typeof placementToPadding;
|
|
17
|
+
export declare type InputAdornmentProps = {
|
|
18
|
+
children: ReactElement;
|
|
19
|
+
/**
|
|
20
|
+
* When using another input component as an adornment, you may optionally
|
|
21
|
+
* override the parent field label.
|
|
22
|
+
*/
|
|
23
|
+
fieldLabel?: string;
|
|
24
|
+
/** Where to place the adornment. */
|
|
25
|
+
placement: PlacementType;
|
|
26
|
+
/**
|
|
27
|
+
* By default, the adornment element will be wrapped to provide alignment and
|
|
28
|
+
* spacing, use the "raw" property to opt-out of this behaviour.
|
|
29
|
+
*/
|
|
30
|
+
raw?: boolean;
|
|
31
|
+
};
|
|
32
|
+
/**
|
|
33
|
+
* Places an element at the "start" or "end" of the input, only one adornment
|
|
34
|
+
* may be provided for each placement. By default, the adornment element will be
|
|
35
|
+
* wrapped to provide alignment and spacing, use the "raw" property to opt-out
|
|
36
|
+
* of this behaviour.
|
|
37
|
+
*
|
|
38
|
+
* @example
|
|
39
|
+
* <TextInput>
|
|
40
|
+
* <InputAdornment placement="start">
|
|
41
|
+
* <Text tone="placeholder">$</Text>
|
|
42
|
+
* </InputAdornment>
|
|
43
|
+
* </TextInput>
|
|
44
|
+
*/
|
|
45
|
+
export declare const InputAdornment: ({ children, fieldLabel, placement, raw, }: InputAdornmentProps) => JSX.Element;
|
|
46
|
+
export {};
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import type { BoxProps } from '@spark-web/box';
|
|
2
|
+
import type { ReactElement } from 'react';
|
|
3
|
+
import type { InputAdornmentProps } from './InputAdornment';
|
|
4
|
+
export declare type InputContainerProps = {
|
|
5
|
+
/** Slot to start render adornment. */
|
|
6
|
+
startAdornment?: ReactElement<InputAdornmentProps> | null;
|
|
7
|
+
/** Slot to end render adornment. */
|
|
8
|
+
endAdornment?: ReactElement<InputAdornmentProps> | null;
|
|
9
|
+
} & Omit<BoxProps, 'background' | 'position'>;
|
|
10
|
+
export declare const InputContainer: ({ children, startAdornment, endAdornment, ...boxProps }: InputContainerProps) => JSX.Element;
|