@fluentui/react-input 9.2.2 → 9.2.4

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.
Files changed (7) hide show
  1. package/CHANGELOG.json +67 -5
  2. package/CHANGELOG.md +28 -6
  3. package/README.md +1 -3
  4. package/package.json +5 -5
  5. package/Spec-styling.md +0 -125
  6. package/Spec-variants.md +0 -99
  7. package/Spec.md +0 -262
package/CHANGELOG.json CHANGED
@@ -2,7 +2,69 @@
2
2
  "name": "@fluentui/react-input",
3
3
  "entries": [
4
4
  {
5
- "date": "Thu, 20 Oct 2022 08:35:11 GMT",
5
+ "date": "Wed, 02 Nov 2022 11:54:53 GMT",
6
+ "tag": "@fluentui/react-input_v9.2.4",
7
+ "version": "9.2.4",
8
+ "comments": {
9
+ "patch": [
10
+ {
11
+ "author": "olfedias@microsoft.com",
12
+ "package": "@fluentui/react-input",
13
+ "commit": "c619ba066f11a8654e95375314824ba6b81b003e",
14
+ "comment": "chore: Update Griffel to latest version"
15
+ },
16
+ {
17
+ "author": "tristan.watanabe@gmail.com",
18
+ "package": "@fluentui/react-input",
19
+ "commit": "890afd9e53f3ad3afd9820fd3e23dc8b8445cb45",
20
+ "comment": "chore: Migrate to new package structure."
21
+ },
22
+ {
23
+ "author": "beachball",
24
+ "package": "@fluentui/react-input",
25
+ "comment": "Bump @fluentui/react-utilities to v9.2.0",
26
+ "commit": "393a7b169155997a97a6ce1ad36ee3eafc6f461b"
27
+ },
28
+ {
29
+ "author": "beachball",
30
+ "package": "@fluentui/react-input",
31
+ "comment": "Bump @fluentui/react-conformance-griffel to v9.0.0-beta.17",
32
+ "commit": "393a7b169155997a97a6ce1ad36ee3eafc6f461b"
33
+ },
34
+ {
35
+ "author": "beachball",
36
+ "package": "@fluentui/react-input",
37
+ "comment": "Bump @fluentui/react-text to v9.1.5",
38
+ "commit": "393a7b169155997a97a6ce1ad36ee3eafc6f461b"
39
+ }
40
+ ]
41
+ }
42
+ },
43
+ {
44
+ "date": "Tue, 25 Oct 2022 00:35:32 GMT",
45
+ "tag": "@fluentui/react-input_v9.2.3",
46
+ "version": "9.2.3",
47
+ "comments": {
48
+ "none": [
49
+ {
50
+ "author": "miroslav.stastny@microsoft.com",
51
+ "package": "@fluentui/react-input",
52
+ "commit": "6ced976a8d0e6a0e2e207da8fe0eb810e2bd19bc",
53
+ "comment": "Update package readme"
54
+ }
55
+ ],
56
+ "patch": [
57
+ {
58
+ "author": "beachball",
59
+ "package": "@fluentui/react-input",
60
+ "comment": "Bump @fluentui/react-text to v9.1.4",
61
+ "commit": "eef12b9ae58b64ff68576dc2d865b601e46c85b9"
62
+ }
63
+ ]
64
+ }
65
+ },
66
+ {
67
+ "date": "Thu, 20 Oct 2022 08:39:35 GMT",
6
68
  "tag": "@fluentui/react-input_v9.2.2",
7
69
  "version": "9.2.2",
8
70
  "comments": {
@@ -29,25 +91,25 @@
29
91
  "author": "beachball",
30
92
  "package": "@fluentui/react-input",
31
93
  "comment": "Bump @fluentui/react-theme to v9.1.1",
32
- "commit": "be27026d83b8a019bcb945d0f42635ae76c00385"
94
+ "commit": "5ea1372675d910d76cf1b9cbd74d05b7c4e8fcbc"
33
95
  },
34
96
  {
35
97
  "author": "beachball",
36
98
  "package": "@fluentui/react-input",
37
99
  "comment": "Bump @fluentui/react-utilities to v9.1.2",
38
- "commit": "be27026d83b8a019bcb945d0f42635ae76c00385"
100
+ "commit": "5ea1372675d910d76cf1b9cbd74d05b7c4e8fcbc"
39
101
  },
40
102
  {
41
103
  "author": "beachball",
42
104
  "package": "@fluentui/react-input",
43
105
  "comment": "Bump @fluentui/react-conformance-griffel to v9.0.0-beta.16",
44
- "commit": "be27026d83b8a019bcb945d0f42635ae76c00385"
106
+ "commit": "5ea1372675d910d76cf1b9cbd74d05b7c4e8fcbc"
45
107
  },
46
108
  {
47
109
  "author": "beachball",
48
110
  "package": "@fluentui/react-input",
49
111
  "comment": "Bump @fluentui/react-text to v9.1.3",
50
- "commit": "be27026d83b8a019bcb945d0f42635ae76c00385"
112
+ "commit": "5ea1372675d910d76cf1b9cbd74d05b7c4e8fcbc"
51
113
  }
52
114
  ]
53
115
  }
package/CHANGELOG.md CHANGED
@@ -1,12 +1,34 @@
1
1
  # Change Log - @fluentui/react-input
2
2
 
3
- This log was last generated on Thu, 20 Oct 2022 08:35:11 GMT and should not be manually modified.
3
+ This log was last generated on Wed, 02 Nov 2022 11:54:53 GMT and should not be manually modified.
4
4
 
5
5
  <!-- Start content -->
6
6
 
7
+ ## [9.2.4](https://github.com/microsoft/fluentui/tree/@fluentui/react-input_v9.2.4)
8
+
9
+ Wed, 02 Nov 2022 11:54:53 GMT
10
+ [Compare changes](https://github.com/microsoft/fluentui/compare/@fluentui/react-input_v9.2.3..@fluentui/react-input_v9.2.4)
11
+
12
+ ### Patches
13
+
14
+ - chore: Update Griffel to latest version ([PR #25412](https://github.com/microsoft/fluentui/pull/25412) by olfedias@microsoft.com)
15
+ - chore: Migrate to new package structure. ([PR #25469](https://github.com/microsoft/fluentui/pull/25469) by tristan.watanabe@gmail.com)
16
+ - Bump @fluentui/react-utilities to v9.2.0 ([PR #25456](https://github.com/microsoft/fluentui/pull/25456) by beachball)
17
+ - Bump @fluentui/react-conformance-griffel to v9.0.0-beta.17 ([PR #25456](https://github.com/microsoft/fluentui/pull/25456) by beachball)
18
+ - Bump @fluentui/react-text to v9.1.5 ([PR #25456](https://github.com/microsoft/fluentui/pull/25456) by beachball)
19
+
20
+ ## [9.2.3](https://github.com/microsoft/fluentui/tree/@fluentui/react-input_v9.2.3)
21
+
22
+ Tue, 25 Oct 2022 00:35:32 GMT
23
+ [Compare changes](https://github.com/microsoft/fluentui/compare/@fluentui/react-input_v9.2.2..@fluentui/react-input_v9.2.3)
24
+
25
+ ### Patches
26
+
27
+ - Bump @fluentui/react-text to v9.1.4 ([PR #25363](https://github.com/microsoft/fluentui/pull/25363) by beachball)
28
+
7
29
  ## [9.2.2](https://github.com/microsoft/fluentui/tree/@fluentui/react-input_v9.2.2)
8
30
 
9
- Thu, 20 Oct 2022 08:35:11 GMT
31
+ Thu, 20 Oct 2022 08:39:35 GMT
10
32
  [Compare changes](https://github.com/microsoft/fluentui/compare/@fluentui/react-input_v9.2.1..@fluentui/react-input_v9.2.2)
11
33
 
12
34
  ### Patches
@@ -14,10 +36,10 @@ Thu, 20 Oct 2022 08:35:11 GMT
14
36
  - chore: Update Griffel to latest version ([PR #25212](https://github.com/microsoft/fluentui/pull/25212) by olfedias@microsoft.com)
15
37
  - feat: Add red border when aria-invalid is set ([PR #25252](https://github.com/microsoft/fluentui/pull/25252) by behowell@microsoft.com)
16
38
  - chore: Bump peer deps to support React 18 ([PR #24972](https://github.com/microsoft/fluentui/pull/24972) by mgodbolt@microsoft.com)
17
- - Bump @fluentui/react-theme to v9.1.1 ([commit](https://github.com/microsoft/fluentui/commit/be27026d83b8a019bcb945d0f42635ae76c00385) by beachball)
18
- - Bump @fluentui/react-utilities to v9.1.2 ([commit](https://github.com/microsoft/fluentui/commit/be27026d83b8a019bcb945d0f42635ae76c00385) by beachball)
19
- - Bump @fluentui/react-conformance-griffel to v9.0.0-beta.16 ([commit](https://github.com/microsoft/fluentui/commit/be27026d83b8a019bcb945d0f42635ae76c00385) by beachball)
20
- - Bump @fluentui/react-text to v9.1.3 ([commit](https://github.com/microsoft/fluentui/commit/be27026d83b8a019bcb945d0f42635ae76c00385) by beachball)
39
+ - Bump @fluentui/react-theme to v9.1.1 ([PR #25265](https://github.com/microsoft/fluentui/pull/25265) by beachball)
40
+ - Bump @fluentui/react-utilities to v9.1.2 ([PR #25265](https://github.com/microsoft/fluentui/pull/25265) by beachball)
41
+ - Bump @fluentui/react-conformance-griffel to v9.0.0-beta.16 ([PR #25265](https://github.com/microsoft/fluentui/pull/25265) by beachball)
42
+ - Bump @fluentui/react-text to v9.1.3 ([PR #25265](https://github.com/microsoft/fluentui/pull/25265) by beachball)
21
43
 
22
44
  ## [9.2.1](https://github.com/microsoft/fluentui/tree/@fluentui/react-input_v9.2.1)
23
45
 
package/README.md CHANGED
@@ -1,8 +1,6 @@
1
1
  # @fluentui/react-input
2
2
 
3
- **React Input components for [Fluent UI React](https://developer.microsoft.com/en-us/fluentui)**
4
-
5
- These are not production-ready components and **should never be used in product**. This space is useful for testing new components whose APIs might change before final release.
3
+ **React Input components for [Fluent UI React](https://react.fluentui.dev)**
6
4
 
7
5
  Inputs give people a way to enter and edit text.
8
6
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fluentui/react-input",
3
- "version": "9.2.2",
3
+ "version": "9.2.4",
4
4
  "description": "Fluent UI React Input component",
5
5
  "main": "lib-commonjs/index.js",
6
6
  "module": "lib/index.js",
@@ -28,14 +28,14 @@
28
28
  "devDependencies": {
29
29
  "@fluentui/eslint-plugin": "*",
30
30
  "@fluentui/react-conformance": "*",
31
- "@fluentui/react-conformance-griffel": "9.0.0-beta.16",
32
- "@fluentui/react-text": "^9.1.3",
31
+ "@fluentui/react-conformance-griffel": "9.0.0-beta.17",
32
+ "@fluentui/react-text": "^9.1.5",
33
33
  "@fluentui/scripts": "^1.0.0"
34
34
  },
35
35
  "dependencies": {
36
36
  "@fluentui/react-theme": "^9.1.1",
37
- "@fluentui/react-utilities": "^9.1.2",
38
- "@griffel/react": "^1.4.1",
37
+ "@fluentui/react-utilities": "^9.2.0",
38
+ "@griffel/react": "^1.4.2",
39
39
  "tslib": "^2.1.0"
40
40
  },
41
41
  "peerDependencies": {
package/Spec-styling.md DELETED
@@ -1,125 +0,0 @@
1
- # `@fluentui/react-input`: Styling implementation notes
2
-
3
- Input has multiple size and appearance variants. These tables were created based on the design spec to assist with initial implementation and help ensure everything is handled.
4
-
5
- General abbreviations used:
6
-
7
- - " = inherit from left
8
- - ^ = inherit from above
9
- - ^^ = inherit from 2 lines above
10
-
11
- ## Sizes
12
-
13
- Notes:
14
-
15
- - padding and gap values are from (theoretical) `spacing.horizontal` unless otherwise specified
16
- - interpretation:
17
- - "spacing between icon before and content"/"spacing between content and icon after 1" => "spacing within root"
18
- - "spacing between icon after 1 and icon after 2" => "spacing within contentBefore/After" because we're not going to have two icon slots
19
- - omitted "focus indicator" b/c that's handled elsewhere
20
-
21
- ### For all field sizes
22
-
23
- | Style | Application | All |
24
- | -------------------------------------- | ------------------------- | ------------------- |
25
- | v-align | root | vertically centered |
26
- | border radius | root (unless underlined) | medium |
27
- | ~~spacing within contentBefore/After~~ | n/a (add later if needed) | xs |
28
-
29
- ### Varying by field size
30
-
31
- | Style | Application | small | medium | large |
32
- | ----------------------------- | ------------------------------ | ------------------- | ---------------- | --------- |
33
- | height | root `minHeight` | 24px | 32px | 40px |
34
- | left/right padding | root | sNudge | mNudge | m |
35
- | left/right padding in content | input | xxs | xxs | sNudge |
36
- | content size | root, input (doesn't inherit) | caption1 (base.200) | body1 (base.300) | base.400 |
37
- | "icon" size | contentBefore/after `> svg` | 16Regular | 20Regular | 24Regular |
38
- | spacing within root | root `display: flex`, flex gap | xxs | xxs | sNudge |
39
-
40
- ## Appearance colors and strokes
41
-
42
- Notes:
43
-
44
- - borders are thin (1px) unless otherwise noted
45
- - "in focus indicator" means the bottom border (applied to `:after`)
46
- - interpreting "compound brand stroke 1 pressed" as compoundBrandStrokePressed
47
- - mouse and keyboard focus styles are the same
48
-
49
- TODO Open questions:
50
-
51
- - What color should the focus indicator be while animating? (pressed or non-pressed color)
52
- - For borderBottom pressed:
53
- - The designs for outline/underline show a thick bottom border in the pressed state as the focus indicator animates in, but this isn't included in the animation demoing the focus border (and I can't tell if Windows 11 uses it).
54
- - This wide border could be added on the root (while maintaining the blue focus border) using `:focus-within:before` + setting the bottom border color on `:focus-within`.
55
-
56
- ### For all appearances
57
-
58
- | Style | Application | All |
59
- | -------------------------- | -------------------------------- | ------------------------- |
60
- | content color | input | neutralForeground1 |
61
- | content color disabled | ^ | neutralForegroundDisabled |
62
- | placeholder color | input `::placeholder` | neutralForeground4 |
63
- | placeholder color disabled | ^ | neutralForegroundDisabled |
64
- | "icon" color | contentBefore/After | neutralForeground3 |
65
- | "icon" color disabled | ^ | neutralForegroundDisabled |
66
- | background disabled | root, input | transparentBackground |
67
- | border disabled | root | neutralStrokeDisabled |
68
- | ~~borderBottom focused~~ | n/a (covered by focus indicator) | |
69
- | in focus indicator | root `:focus-within:after` | thick compoundBrandStroke |
70
- | in focus indicator pressed | root `:after` | thick ^Pressed |
71
- | cursor disabled | root, input | not-allowed |
72
-
73
- ### Varying per appearance
74
-
75
- | Style | Application | outline | underline | filledDarker | filledLighter |
76
- | -------------------- | -------------------- | ----------------------- | --------------------- | ------------------ | ------------------ |
77
- | shadow | root | none | " | shadow2 | " |
78
- | background | root, input | neutralBackground1 | transparentBackground | neutralBackground3 | neutralBackground1 |
79
- | border | root | neutralStroke1 | none | transparentStroke | " |
80
- | border hover | root `:hover` | ^Hover | n/a | ^Interactive | " |
81
- | border pressed | root `:active` | ^^Pressed | n/a | ^ | " |
82
- | border focused | root `:focus-within` | n/a (neutralStroke1) | n/a | ^ | " |
83
- | borderBottom | root | neutralStrokeAccessible | " | n/a | n/a |
84
- | borderBottom hover | root `:hover` | ^Hover | " | n/a | n/a |
85
- | borderBottom pressed | TODO (see ? above) | thick ^^Pressed | " | n/a | n/a |
86
-
87
- ### In focus indicator
88
-
89
- | | focus in | focus out |
90
- | --------- | -------------------------- | ---------------- |
91
- | apply to | root `:focus-within:after` | root `:after` |
92
- | transform | scaleX 0-1 | scaleX 1-0 |
93
- | duration | normal (200ms) | ultraFast (50ms) |
94
- | easing | decelerateMid | accelerateMid |
95
-
96
- ## Bookends (deferred)
97
-
98
- Bookend implementation has been deferred and will likely be handled in a separate component, but leaving these for reference.
99
-
100
- ### Sizes
101
-
102
- | Style | small | medium | large |
103
- | ------------------ | ------------------- | ------ | ----- |
104
- | v-align | vertically centered | " | " |
105
- | border radius | medium | " | " |
106
- | left/right padding | sNudge | s | m |
107
- | spacing within | xs | " | " |
108
-
109
- ### Appearance
110
-
111
- | Style | filled | brand | transparent |
112
- | --------------- | ------------------ | ------------------------ | --------------------- |
113
- | background | neutralBackground6 | brandBackground | transparentBackground |
114
- | content (+icon) | neutralForeground2 | neutralForegroundOnBrand | neutralForeground2 |
115
- | border | transparentStroke | none | transparentStroke |
116
- | inner border | n/a | n/a | neutralStroke3 |
117
-
118
- - Inner border ("border right") color is applied separately to before/after bookends.
119
- - Others are applied in obvious way to both bookends.
120
- - All borders are thin (1px).
121
-
122
- ### Changes to default input appearance
123
-
124
- - Remove rounded corners from input
125
- - For filled inputs with shadow, change the shadow to also encompass the bookends
package/Spec-variants.md DELETED
@@ -1,99 +0,0 @@
1
- # Input Variants
2
-
3
- Input has many variants and additional features. We don't plan to implement any of these immediately, but adding notes here for future reference.
4
-
5
- ## Bookends
6
-
7
- "Bookends" (the naming comes from the design spec) are bits of text on the left or right outside of the field, surrounded by a border or background color.
8
-
9
- Initially, bookends were planned to be included in the main component (as `bookendBefore`/`bookendAfter` slots) but we decided they're not essential and should be split out to simplify the DOM structure and defer some of the related open questions until later.
10
-
11
- If/when a partner needs this feature, it will likely go in some kind of wrapper component.
12
-
13
- Visual variants for the bookends are as follows (note that specific colors are just examples based on the default theme):
14
-
15
- - `filled` (default): bookends have a gray background, black text, and no border
16
- - `brand`: bookends have a brand color (such as blue or purple) background, white text, and no border
17
- - `transparent`: bookends have a transparent background, black text, and only a thin inside border to distinguish them from the field
18
-
19
- ## Multi-line (`textarea`)
20
-
21
- This will tentatively be a separate component, likely sharing some internals with the basic `Input` using hooks (scheduling TBD).
22
-
23
- | Prop/concept | v8 | v0 | Proposal |
24
- | ------------------ | ---------------------------- | --- | -------------------------------------------------------- |
25
- | resizable | `resizable?: boolean` | | via native props |
26
- | auto-adjust height | `autoAdjustHeight?: boolean` | | TBD (common request but has nasty implementation issues) |
27
-
28
- Similar to both v8 and v0, passing other `textarea` native props as top-level component props will be supported.
29
-
30
- ### Possibility: `useTextInput`
31
-
32
- We might want to make a hook and some types to share props and behavior between `Input` and the potential future `TextArea` (which would depend on `react-input` but with some different props and behaviors).
33
-
34
- ```ts
35
- type TextInputSlots<
36
- TInput extends HTMLInputElement | HTMLTextAreaElement,
37
- TInputAttributes = TInput extends HTMLInputElement
38
- ? React.InputHTMLAttributes<TInput>
39
- : React.TextAreaHTMLAttributes<TInput>
40
- > = {
41
- root: ComponentSlotProps<React.HTMLAttributes<HTMLElement>, HTMLElement>;
42
- input: ComponentSlotProps<TInputAttributes, TInput>;
43
- };
44
- ```
45
-
46
- ## Validation
47
-
48
- Validation features and error messages will not be built into the new `Input`. Possible approaches:
49
-
50
- - Hooks and/or a `Field` component to provide visual consistency and proper accessibility behavior across different types of inputs.
51
- - A `Form` component for more complex scenarios involving validation across multiple fields.
52
-
53
- ### In v8
54
-
55
- ```ts
56
- // relevant props only
57
- interface ITextFieldProps {
58
- // static error message
59
- errorMessage?: string | JSX.Element;
60
- // called to determine whether input is valid and show error if not
61
- // (on all changes by default; modified by validateOnFocusIn/Out)
62
- onGetErrorMessage?: (value: string) => string | JSX.Element | PromiseLike<string | JSX.Element> | undefined;
63
- // whether to validate when focus moves into input (NOT on change)
64
- validateOnFocusIn?: boolean;
65
- // whether to validate when focus moves out of input (NOT on change)
66
- validateOnFocusOut?: boolean;
67
- // whether to validate when input is initially rendered
68
- validiateOnLoad?: boolean;
69
- // wait to validate until user stops typing by this ms
70
- deferredValidationTime?: number;
71
- // called after validation completes
72
- onNotifyValidationResult?: (errorMessage: string | JSX.Element, value: string | undefined) => void;
73
- // ...
74
- }
75
- ```
76
-
77
- ### In v0
78
-
79
- TBD
80
-
81
- ## Password
82
-
83
- v8 supports a password field with a custom reveal password button:
84
-
85
- ```tsx
86
- <TextField type="password" canRevealPassword revealPasswordAriaLabel="Show password" />
87
- ```
88
-
89
- v0 does not appear to have a similar feature.
90
-
91
- TBD if/how we want to handle this in converged.
92
-
93
- ## Masking
94
-
95
- "Masking" refers to a text input with some pre-specified format that gets filled in as the user types, like `(___) ___-____`.
96
-
97
- In v8 it's handled by `MaskedTextField`.
98
-
99
- Masking is tricky to implement properly and bad for accessibility, so we don't plan to implement it in converged unless there's a compelling product requirement. At that point we'll also evaluate whether there are any suitable 3rd-party libraries which could handle it.
package/Spec.md DELETED
@@ -1,262 +0,0 @@
1
- # @fluentui/react-input Spec
2
-
3
- **Epic issue** - [Input Convergence](https://github.com/microsoft/fluentui/issues/18131)
4
-
5
- ## Background
6
-
7
- `Input` in its most basic form is a text input field abstracting `<input type="text" />`.
8
-
9
- It can also be used to render other text-based input types, such as `password` or `email`, but **is not intended for non-text input types** such as `checkbox` (those are handled in separate components).
10
-
11
- In some libraries, the equivalent component also abstracts a `textarea` (multi-line text input) and may have features such as a label and start/end slots built in.
12
-
13
- ## Prior Art
14
-
15
- ### In other frameworks
16
-
17
- | Framework | `<input type="text">` | `<textarea>` | Notes |
18
- | -------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
19
- | Ant Design | [`Input`](https://ant.design/components/input/) | `Input.TextArea` | No label. Has both inner and outer prefix/suffix. |
20
- | AtlasKit | [`Textfield`](https://atlassian.design/components/textfield) | [`Textarea`](https://atlassian.design/components/textarea) | No label |
21
- | Carbon | [`TextInput`](https://www.carbondesignsystem.com/components/text-input/usage/) | `TextArea` | Has label prop |
22
- | Evergreen | [`TextInput`](https://evergreen.segment.com/components/text-input) | [`Textarea`](https://evergreen.segment.com/components/textarea) | `TextInputField` and `TextareaField` wrappers provide label etc |
23
- | Lightning | [`input`](https://www.lightningdesignsystem.com/components/input/) | [`textarea`](https://www.lightningdesignsystem.com/components/textarea/) | Not a React library |
24
- | Material UI React | [`Input`](https://material-ui.com/components/text-fields/) | built in to `TextField` | `TextField` is a rollup of functionality: label, appearances, start/end slots, lots of variants |
25
- | `@fluentui/react` (v8) | [`TextField`](https://developer.microsoft.com/en-us/fluentui#/controls/web/textfield) | built in to `TextField` | Has label prop |
26
- | `@fluentui/react-northstar` (v0) | [`Input`](https://fluentsite.z22.web.core.windows.net/0.57.0/components/input/definition) | [`TextArea`](https://fluentsite.z22.web.core.windows.net/0.57.0/components/text-area/definition) | Has label prop |
27
-
28
- ### Comparison of v8 and v0
29
-
30
- Please see the [migration guide](#migration-guide) section.
31
-
32
- ## Sample Code
33
-
34
- See [Structure section](#structure) for the output HTML.
35
-
36
- ```tsx
37
- <Label htmlFor="input1">Label</Label> // note that the label is not built in
38
- <Input
39
- className="rootClass"
40
- input={{ className: 'inputClass' }}
41
- id="input1"
42
- value="something"
43
- onChange={(ev, data) => console.log(data.value)}
44
- contentBefore={<SearchIcon />}
45
- contentAfter={<ClearIcon />}
46
- />
47
- ```
48
-
49
- ## Variants
50
-
51
- ### Visual variants
52
-
53
- Visual variants are as follows:
54
-
55
- - `outline` (default): the field has a full outline, with a slightly darker underline on the bottom
56
- - `underline`: the field has an underline on the bottom only
57
- - `filledDarker`: the field has a gray background and no underline/outline
58
- - `filledLighter`: the field has a white background and no underline/outline (for use on top of gray/colored backgrounds)
59
-
60
- See the design spec for details on each of these. (Note that the actual colors used will follow the theme; white/gray are just examples from the default theme.)
61
-
62
- ### Behavior variants
63
-
64
- In the future we may implement behavior variants, such as a password field with reveal button, but that will be spec'd if/when we need it. See [Spec-variants.md](./Spec-variants.md) for more details.
65
-
66
- ## API
67
-
68
- In this component, `input` is the primary slot. See notes under [Structure](#structure).
69
-
70
- ### Main props
71
-
72
- All native HTML `<input>` props are supported. Since the `input` slot is primary (more on that later), top-level native props except `className` and `style` will go to the input.
73
-
74
- The top-level `ref` prop also points to the `<input>`. This can be used for things like getting the current value or manipulating focus or selection (instead of explicitly exposing an imperative API).
75
-
76
- For the full current props, see the types file:
77
- https://github.com/microsoft/fluentui/blob/master/packages/react-input/src/components/Input/Input.types.ts
78
-
79
- ```ts
80
- // Simplified version of the props (including only summaries of custom props)
81
- type SimplifiedInputProps = {
82
- /** Toggle inline display instead of block */
83
- inline?: boolean;
84
-
85
- /** Controls the colors and borders of the field (default `outline`) */
86
- appearance?: 'outline' | 'underline' | 'filledDarker' | 'filledLighter';
87
-
88
- /** Size of the input (default `medium`) */
89
- size?: 'small' | 'medium' | 'large';
90
-
91
- /** Default value (uncontrolled) */
92
- defaultValue?: string;
93
-
94
- /** Controlled value */
95
- value?: string;
96
-
97
- /** Called when the user changes the value */
98
- onChange?: (ev: React.FormEvent<HTMLInputElement>, data: { value: string }) => void;
99
-
100
- /** Allowed values for the native `type` prop */
101
- type?: 'text' | '...'; // this is an enumeration of all text-like values
102
- };
103
- ```
104
-
105
- Notes on native prop conflicts/overrides:
106
-
107
- - `size` [overlaps with a native prop](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/size) which sets the width of the field in "number of characters." This isn't ideal, but we're going with it since the native prop isn't very useful in practice, and it was hard to find another reasonable/consistent name for the visual size prop. It's also consistent with the approach used by most other libraries which have a prop for setting the visual size. (If anyone needs the native functionality, we could add an `htmlSize` prop in the future.)
108
- - `value` and `defaultValue` are defined in `InputHTMLAttributes` (from `@types/react`) as `string | ReadonlyArray<string> | number` since the same props interface is used for all input element types. To reflect actual usage, we override the types to only accept strings.
109
- - `onChange` is overridden per the [RFC on event handler arguments](https://github.com/microsoft/fluentui/blob/master/rfcs/convergence/event-handlers-arguments.md).
110
- - `type` is defined in `@types/react` as `string`, but for `Input`, I'm restricting it to a list of only the text-like values [listed on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Input#input_types). Making this explicit should help avoid people thinking that Input can handle all the same behaviors as a native `<input>`.
111
-
112
- ### Slots
113
-
114
- Note that the field **does not** include a label, required indicator, description, or error message.
115
-
116
- An overview of the slots is as follows. For the current slot types and full docs, see the types file:
117
- https://github.com/microsoft/fluentui/blob/master/packages/react-input/src/components/Input/Input.types.ts
118
-
119
- - `root` (`span`): Wrapper which visually appears to be the input (needed to position `contentBefore` and `contentAfter` relative to the actual `input`)
120
- - `input` (`input`, primary slot): The actual text input element
121
- - `contentBefore` (`span`): Element before the input text, within the input border (most often used for icons)
122
- - `contentAfter` (`span`): Element after the input text, within the input border (most often used for icons)
123
-
124
- ## Structure
125
-
126
- In this component, `input` is the primary slot. Per the [native element props/primary slot RFC](https://github.com/microsoft/fluentui/blob/master/rfcs/convergence/native-element-props.md), this means that most top-level props will go to `input`, but the top-level `className` and `style` will go to the actual root element.
127
-
128
- ```tsx
129
- // Out of top-level native props, only `className` and `style` go here
130
- <slots.root {...slotProps.root}>
131
- <slots.contentBefore {...slotProps.contentBefore} />
132
- {/* Primary slot. Top-level native props except `className` and `style` go here. */}
133
- <slots.input {...slotProps.input} />
134
- <slots.contentAfter {...slotProps.contentAfter} />
135
- </slots.root>
136
- ```
137
-
138
- Notes on the HTML rendering:
139
-
140
- - Using `span` rather than `div` prevents nesting errors if the Input is rendered inline within a `<p>`.
141
- - The root is visually styled as the input (with borders etc) and the `contentBefore`, `contentAfter`, and actual `input` elements are positioned inside it.
142
-
143
- This example usage:
144
-
145
- ```tsx
146
- <Input
147
- className="rootClass"
148
- style={{ background: 'red' }}
149
- input={{ className: 'inputClass', style: { background: 'blue' } }}
150
- id="input1"
151
- value="something"
152
- onChange={(ev, data) => console.log(data.value)}
153
- contentBefore={<SearchIcon />}
154
- contentAfter={<ClearIcon />}
155
- />
156
- ```
157
-
158
- Gives this HTML:
159
-
160
- ```html
161
- <span className="rootClass" style="background: red">
162
- <span><!-- contentBefore here --></span>
163
- <!-- input: type="text" is applied automatically -->
164
- <input
165
- type="text"
166
- className="inputClass"
167
- style="background: blue"
168
- id="input1"
169
- value="something"
170
- onChange="(function)"
171
- />
172
- <span><!-- contentAfter here --></span>
173
- </span>
174
- ```
175
-
176
- ## Behaviors
177
-
178
- Most of the behavior is inherited from the native `<input>` element, and all we add is styling.
179
-
180
- The component has the following interactive states:
181
-
182
- - Rest
183
- - Hover: change stroke color
184
- - Pressed: apply focus border style as animation
185
- - Focused: currently indicated by a thick brand color stroke on the bottom border only (regardless of whether focus was by keyboard or mouse)
186
-
187
- Keyboard, cursor, touch, and screen reader interaction will be handled automatically by the internal `<input>`.
188
-
189
- ## Accessibility
190
-
191
- - Most interaction and screen reader behavior will be handled automatically by the internal `<input type="text">`.
192
- - The `<input>` is visible and shows the placeholder or value text.
193
- - The component doesn't provide a built-in label, so it's important for the user to pass in appropriate attributes such as `id` (associated with a label using `htmlFor`), `aria-label`, or `aria-labelledby`.
194
- - No features in the initial implementation require manipulation of focus, tab order, or key handling.
195
- - Visual states for focus and hover will be applied to `root` rather than the `<input>` itself (which is rendered without a border and only used to show the text), because the `contentBefore` and `contentAfter` slots need to visually appear to be within the input.
196
-
197
- ## Migration
198
-
199
- > **NOTE**: Props related to multiline, reveal password, validation, and masking are not yet supported and likely to be handled in separate components. See [Spec-variants.md](./Spec-variants.md) for more details.
200
-
201
- ### Props
202
-
203
- | Prop/concept | v8 | v0 | Proposal |
204
- | ---------------------------- | ----------------------------------------------------- | ----------------------------------------------------------- | --------------------------------------- |
205
- | imperative API | `componentRef` | n/a | n/a |
206
- | supported native props | `React.AllHTMLAttributes` (input or textarea) | `SupportedIntrinsicInputProps` (see below) | `React.InputHTMLAttributes` |
207
- | setting native props on root | | ? | `root` slot (mostly, see below) |
208
- | root element access | `elementRef` | ? | `ref` on `root` slot |
209
- | primary element access | not possible | `ref` | top-level `ref` |
210
- | multiline mode | `multiline?: boolean` | separate component (`TextArea`) | separate component |
211
- | underlined | `underlined?: boolean` | | `appearance` |
212
- | borderless | `borderless?: boolean` | | not supported? |
213
- | fluid (full width) | default behavior | `fluid?: boolean` | default behavior |
214
- | inline | n/a (use styling) | `inline?: boolean` | `inline?: boolean` |
215
- | label | `label?: string`, `onRenderLabel` | `label?: ShorthandValue<InputLabelProps>`, | handled by Field |
216
- | label position | n/a (use styling) | `labelPosition?: 'above' \| 'inline' \| 'inside'` | handled by Field |
217
- | description | `description?: string`, `onRenderDescription` | use FormField | handled by Field |
218
- | error message | see [Spec-variants.md](./Spec-variants.md#validation) | use FormField | handled by Field |
219
- | content outside before field | `prefix?: string`, `onRenderPrefix` | n/a | TBD (deferred) |
220
- | content outside after field | `suffix?: string`, `onRenderSuffix` | n/a | TBD (deferred) |
221
- | icon at start of field | n/a | `icon?: ShorthandValue<BoxProps>` + `iconPosition: 'start'` | `contentBefore` slot |
222
- | icon at end of field | `iconProps?: IIconProps` | `icon?: ShorthandValue<BoxProps>` + `iconPosition: 'end'` | `contentAfter` slot |
223
- | value | `value?: string` | `value?: string \| number` | `value?: string` |
224
- | defaultValue | `defaultValue?: string` | `defaultValue?: string \| string[]` | `defaultValue?: string` |
225
- | onChange | `(ev, value) => void` | `(ev, data: { ...props, value }) => void` | `(ev, data: { value: string }) => void` |
226
- | container className | `className?: string` | | top-level `className` |
227
- | input className | `inputClassName?: string` | `input.className?: ` | |
228
- | aria label | `ariaLabel?: string` | `'aria-label'?: string` | `'aria-label'?: string` |
229
- | clearable | n/a | `clearable?: boolean` | TBD (deferred) |
230
- | theme | `theme?: ITheme` | | handled by context |
231
- | style overrides | `styles?: IStyleFunctionOrObject<...>` | `styles?: ComponentSlotStyles<...>` | className, slot classNames |
232
- | accessibility | individual props | `Accessibility<InputBehaviorProps>` (see below) | individual props? |
233
-
234
- ```ts
235
- // packages/fluentui/react-northstar/src/utils/htmlPropsUtils.tsx
236
- type SupportedIntrinsicInputProps = {
237
- [K in HtmlInputProps]?: K extends keyof JSX.IntrinsicElements['input'] ? JSX.IntrinsicElements['input'][K] : any;
238
- };
239
- // HtmlInputProps: a subset of React and HTML native props
240
-
241
- // packages/fluentui/react-northstar/src/components/Box/Box.tsx
242
- interface BoxProps extends UIComponentProps<BoxProps>, ContentComponentProps, ChildrenComponentProps {
243
- /** Accessibility behavior if overridden by the user. */
244
- accessibility?: Accessibility<never>;
245
- }
246
-
247
- // packages/fluentui/accessibility/src/behaviors/Input/inputBehavior.ts
248
- type InputBehaviorProps = { disabled?: boolean; required?: boolean; error?: boolean };
249
- ```
250
-
251
- Native props following standard behavior in both libraries + converged:
252
-
253
- - `disabled?: boolean`
254
- - `readOnly?: boolean`
255
- - `autoComplete?: string`
256
- - and most other native props not specified
257
-
258
- ### Imperative API
259
-
260
- In v8 there's an explicit imperative API, which is accessed via `componentRef` following the [`ITextField` interface](https://github.com/microsoft/fluentui/blob/master/packages/react/src/components/TextField/TextField.types.ts#L9). The methods are used for getting the value and manipulating focus and selection.
261
-
262
- In v0 (and in converged), all these things can be done by calling methods on the `<input>` element itself, exposed via the top-level `ref`.