Adds TextInput as a new web component

change/@fluentui-web-components-ec003fd2-a453-4e83-b620-9ec9f3ddffa0.json

@@ -0,0 +1,7 @@
+{
+  "type": "prerelease",
+  "comment": "feat(text-input): add TextInput as a new web component",
+  "packageName": "@fluentui/web-components",
+  "email": "brianbrady@microsoft.com",
+  "dependentChangeType": "patch"
+}

packages/web-components/package.json

@@ -120,6 +120,10 @@
       "types": "./dist/esm/text/define.d.ts",
       "default": "./dist/esm/text/define.js"
     },
+    "./text-input": {
+      "types": "./dist/esm/text-input/define.d.ts",
+      "default": "./dist/esm/text-input/define.js"
+    },
     "./toggle-button": {
       "types": "./dist/esm/toggle-button/define.d.ts",
       "default": "./dist/esm/toggle-button/define.js"

packages/web-components/src/index.ts

@@ -22,6 +22,7 @@ export * from './tabs/index.js';
 export * from './tab/index.js';
 export * from './tab-panel/index.js';
 export * from './text/index.js';
+export * from './text-input/index.js';
 export * from './toggle-button/index.js';
 
 export * from './theme/index.js';

packages/web-components/src/text-input/README.md

@@ -0,0 +1,155 @@
+# TextInput
+
+> An implementation of a [text input](https://w3c.github.io/html-reference/input.text.html) as a form-connected web-component.
+> <br />
+
+## **Design Spec**
+
+[Link to Text Input Design Spec in Figma](https://www.figma.com/file/TvHmWjZYxwtI9Tz6v5BT7E/Input?node-id=2366-657&t=UNSOfCD3St9ffppx-0)
+
+<br />
+
+## **Engineering Spec**
+
+Fluent WC3 Text Input extends from the [FAST Text Field](https://explore.fast.design/components/fast-text-field) and is intended to be as close to the Fluent UI React 9 Input implementation as possible. However, due to the nature of web components there will not be 100% parity between the two.
+
+<br />
+
+## Class: `TextInput`
+
+<br />
+
+### **Component Name**
+
+`<fluent-text-input>`
+
+<br />
+
+### **Variables**
+
+| Name                   | Description                          | Type                                                                                                             |
+| ---------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
+| `TextInputControlSize` | Size variations for text input       | `{ small: "small", medium: "medium", large: "large" }`                                                           |
+| `TextInputAppearance`  | Appearance variations for text input | `{ outline: "outline", underline: "underline", filledLighter: "filled-lighter", filledDarker: "filled-darker" }` |
+| `TextInputType`        | Text input types                     | `{ email: "email", password: "password", tel: "tel", text: "text", url: "url" }`                                 |
+
+<br />
+
+### **Fields**
+
+| Name            | Privacy | Type                   | Default                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| --------------- | ------- | ---------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `appearance`    | public  | `TextInputAppearance`  | `TextInputAppearance.outline` | Sets appearance of text input.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `autofocus`     | public  | `boolean`              | `false`                       | Indicates element should get focus after the page finishes loading..                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `disabled`      | public  | `boolean`              | `false`                       | Disables text input                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `list`          | public  | `string`               |                               | Allows associating a `datalist` to an element by `id`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `maxlength`     | public  | `number`               |                               | The maximum number of characters a user can enter                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `minlength`     | public  | `number`               |                               | The minimum number of characters a user can enter                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `name`          | public  | `string`               |                               | The name of the control                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `pattern`       | public  | `string`               |                               | A regular expression the text input's contents must match in order to be valid                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `placeholder`   | public  | `string`               |                               | An exemplar value to display in the text input field whenever it is empty                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `readonly`      | public  | `boolean`              | `false`                       | The text input should be submitted with the form but should not be editable                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `required`      | public  | `boolean`              | `false`                       | Sets the text input as required                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `size`          | public  | `number`               |                               | A number indicating how many characters wide the input field should be                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `spellcheck`    | public  | `boolean`              | `false`                       | Controls whether or not to enable spell checking for the text input, or if the default spell checking configuration should be used                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `type`          | public  | `TextInputType`        | `TextInputType.text`          | Sets the size of the text input                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `current-value` | public  |                        |                               | Stores the current value of an input element. This attribute is commonly used in web development frameworks like Angular and React, where the value of the input element is managed by the framework. By using the current-value attribute, you can ensure that the input element always displays the correct value, even if it is changed by the framework or another JavaScript code. This attribute can also be used to set the initial value of an input element. [link: `current-value` RFC](https://github.com/microsoft/fast/issues/5119) |
+| `control-size`  | public  | `TextInputControlSize` | `TextInputControlSize.medium` | Sets the size of the component                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+
+<br />
+
+### **Methods**
+
+| Name       | Privacy | Description                                       |
+| ---------- | ------- | ------------------------------------------------- |
+| `select`   | public  | Selects all the text in the text field            |
+| `validate` | public  | {@inheritDoc (FormAssociated:interface).validate} |
+
+### **Events**
+
+| Name     | Type | Description                 | Inherited From |
+| -------- | ---- | --------------------------- | -------------- |
+| `change` |      | Fires a custom change event |                |
+
+<br />
+
+### **Attributes**
+
+| Name           | Field       |
+| -------------- | ----------- |
+| `appearance`   | appearance  |
+| `autofocus`    | autofocus   |
+| `list`         | list        |
+| `maxlength`    | maxlength   |
+| `minlength`    | minlength   |
+| `pattern`      | pattern     |
+| `placeholder`  | placeholder |
+| `readonly `    | readonly    |
+| `size`         | size        |
+| `spellcheck`   | spellcheck  |
+| `type`         | type        |
+| `control-size` | type        |
+
+<br />
+
+### **Slots**
+
+| Name    | Description                                                                  |
+| ------- | ---------------------------------------------------------------------------- |
+| `start` | used to place content at the start of the text input within the input border |
+| `end`   | used to place content at the end of the text input within the input border   |
+|         | The default slot for text input content                                      |
+
+<br />
+
+**Block v.s Inline**
+
+The Fluent UI `TextInput` component design spec offers two appearance variations for the display property - block (default) and inline. To achieve the inline variation, users should apply their own custom CSS.
+
+```css
+/* all instances */
+
+fluent-text-input {
+  display: inline-flex;
+  align-items: center;
+}
+
+/* class instances */
+
+fluent-text-input.inline {
+  display: inline-flex;
+  align-items: center;
+}
+```
+
+<br />
+<hr />
+<br />
+
+## **Accessibility**
+
+[W3C Text Input Spec](https://w3c.github.io/html-reference/input.text.html)
+
+<br />
+
+### **WAI-ARIA Roles, States, and Properties**
+
+This component supports ARIA attributes that inherit from the [ARIA Global States and Properties](https://www.w3.org/TR/wai-aria-1.2/#global_states).
+
+<br />
+<hr />
+<br />
+
+## **Preparation**
+
+### **Fluent Web Component v3 v.s Fluent React 9**
+
+<br />
+
+**Component and Slot Mapping**
+
+| Fluent UI React 9 | Fluent Web Components 3 |
+| ----------------- | ----------------------- |
+| `<Input>`         | `<fluent-text-input>`   |
+| `contentBefore`   | `start`                 |
+| `contentAfter`    | `end`                   |

packages/web-components/src/text-input/define.ts

@@ -0,0 +1,4 @@
+import { FluentDesignSystem } from '../fluent-design-system.js';
+import { definition } from './text-input.definition.js';
+
+definition.define(FluentDesignSystem.registry);

packages/web-components/src/text-input/index.ts

@@ -0,0 +1,6 @@
+export * from './text-input.js';
+export * from './text-input.options.js';
+export { template as TextInputTemplate } from './text-input.template.js';
+export { styles as TextInputStyles } from './text-input.styles.js';
+export { definition as TextInputDefinition } from './text-input.definition.js';
+export { TextFieldType as TextInputType } from '@microsoft/fast-foundation';

packages/web-components/src/text-input/text-input.definition.ts

@@ -0,0 +1,18 @@
+import { FluentDesignSystem } from '../fluent-design-system.js';
+import { TextInput } from './text-input.js';
+import { styles } from './text-input.styles.js';
+import { template } from './text-input.template.js';
+
+/**
+ * The Fluent TextInput Element.
+ *
+ *
+ * @public
+ * @remarks
+ * HTML Element: \<fluent-text-input\>
+ */
+export const definition = TextInput.compose({
+  name: `${FluentDesignSystem.prefix}-text-input`,
+  template,
+  styles,
+});

packages/web-components/src/text-input/text-input.options.ts

@@ -0,0 +1,34 @@
+import { ValuesOf } from '@microsoft/fast-foundation';
+
+/**
+ * TextInput size constants
+ * @public
+ */
+export const TextInputControlSize = {
+  small: 'small',
+  medium: 'medium',
+  large: 'large',
+} as const;
+
+/**
+ * Applies size styling to TextInput
+ * @public
+ */
+export type TextInputControlSize = ValuesOf<typeof TextInputControlSize>;
+
+/**
+ * TextInput appearance constants
+ * @public
+ */
+export const TextInputAppearance = {
+  outline: 'outline',
+  underline: 'underline',
+  filledLighter: 'filled-lighter',
+  filledDarker: 'filled-darker',
+} as const;
+
+/**
+ * Applies appearance styling to TextInput
+ * @public
+ */
+export type TextInputAppearance = ValuesOf<typeof TextInputAppearance>;