diff --git a/change/@fluentui-web-components-ec003fd2-a453-4e83-b620-9ec9f3ddffa0.json b/change/@fluentui-web-components-ec003fd2-a453-4e83-b620-9ec9f3ddffa0.json new file mode 100644 index 00000000000000..6f61af5fd35bc7 --- /dev/null +++ b/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" +} diff --git a/packages/web-components/package.json b/packages/web-components/package.json index f3aa9aa4944e37..d5c88a9cf809b8 100644 --- a/packages/web-components/package.json +++ b/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" diff --git a/packages/web-components/src/index.ts b/packages/web-components/src/index.ts index 5207274c046849..b8a598ef4e9d66 100644 --- a/packages/web-components/src/index.ts +++ b/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'; diff --git a/packages/web-components/src/text-input/README.md b/packages/web-components/src/text-input/README.md new file mode 100644 index 00000000000000..f7b1f5b08945e7 --- /dev/null +++ b/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. +>
+ +## **Design Spec** + +[Link to Text Input Design Spec in Figma](https://www.figma.com/file/TvHmWjZYxwtI9Tz6v5BT7E/Input?node-id=2366-657&t=UNSOfCD3St9ffppx-0) + +
+ +## **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. + +
+ +## Class: `TextInput` + +
+ +### **Component Name** + +`` + +
+ +### **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" }` | + +
+ +### **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 | + +
+ +### **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 | | + +
+ +### **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 | + +
+ +### **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 | + +
+ +**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; +} +``` + +
+
+
+ +## **Accessibility** + +[W3C Text Input Spec](https://w3c.github.io/html-reference/input.text.html) + +
+ +### **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). + +
+
+
+ +## **Preparation** + +### **Fluent Web Component v3 v.s Fluent React 9** + +
+ +**Component and Slot Mapping** + +| Fluent UI React 9 | Fluent Web Components 3 | +| ----------------- | ----------------------- | +| `` | `` | +| `contentBefore` | `start` | +| `contentAfter` | `end` | diff --git a/packages/web-components/src/text-input/define.ts b/packages/web-components/src/text-input/define.ts new file mode 100644 index 00000000000000..d211104eff0125 --- /dev/null +++ b/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); diff --git a/packages/web-components/src/text-input/index.ts b/packages/web-components/src/text-input/index.ts new file mode 100644 index 00000000000000..91f1e523895121 --- /dev/null +++ b/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'; diff --git a/packages/web-components/src/text-input/text-input.definition.ts b/packages/web-components/src/text-input/text-input.definition.ts new file mode 100644 index 00000000000000..7b527337b634f7 --- /dev/null +++ b/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: \ + */ +export const definition = TextInput.compose({ + name: `${FluentDesignSystem.prefix}-text-input`, + template, + styles, +}); diff --git a/packages/web-components/src/text-input/text-input.options.ts b/packages/web-components/src/text-input/text-input.options.ts new file mode 100644 index 00000000000000..9a5f3db5fa4c33 --- /dev/null +++ b/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; + +/** + * 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; diff --git a/packages/web-components/src/text-input/text-input.stories.ts b/packages/web-components/src/text-input/text-input.stories.ts new file mode 100644 index 00000000000000..e1ba299ab0470c --- /dev/null +++ b/packages/web-components/src/text-input/text-input.stories.ts @@ -0,0 +1,212 @@ +import { html } from '@microsoft/fast-element'; +import type { Args, Meta } from '@storybook/html'; +import { renderComponent } from '../helpers.stories.js'; +import { colorNeutralBackgroundInverted, colorNeutralForegroundInverted2 } from '../theme/design-tokens.js'; +import type { TextInput as FluentTextInput } from './text-input.js'; +import { TextInputAppearance, TextInputControlSize } from './text-input.options.js'; +import { TextInputType } from './index.js'; +import './define.js'; +import '../text/define.js'; + +type TextInputStoryArgs = Args & FluentTextInput; +type TextInputStoryMeta = Meta; + +const Person20Regular = html``; + +const storyTemplate = html` +
+ x.type} + ?disabled=${x => x.disabled} + placeholder="${x => x.placeholder}" + control-size="${x => x.controlSize}" + appearance="${x => x.appearance}" + > + Sample Input + +
+`; + +export default { + title: 'Components/TextInput', + args: { + type: TextInputType.text, + controlSize: TextInputControlSize.medium, + appearance: TextInputAppearance.outline, + disabled: false, + placeholder: undefined, + }, + argTypes: { + type: { + description: 'Sets the input type', + table: { + defaultValue: { summary: `${TextInputType.text}` }, + }, + options: Object.values(TextInputType), + control: { + type: 'select', + }, + }, + controlSize: { + description: 'Sets the size of the control', + table: { + defaultValue: { summary: `${TextInputControlSize.medium}` }, + }, + control: { + type: 'select', + options: Object.values(TextInputControlSize), + }, + }, + appearance: { + description: 'Sets the visual appearance of the control', + table: { + defaultValue: { summary: `${TextInputAppearance.outline}` }, + }, + control: { + type: 'select', + options: Object.values(TextInputAppearance), + }, + }, + disabled: { + description: 'Sets the disabled state', + table: { + defaultValue: { summary: 'false' }, + }, + control: { + type: 'boolean', + }, + }, + placeholder: { + description: 'Sets the placeholder text', + control: { + type: 'text', + }, + }, + }, +} as TextInputStoryMeta; + +export const TextInput = renderComponent(storyTemplate).bind({}); + +export const ContentStartAfter = renderComponent(html` +
+ + ${Person20Regular} + Content Start + + + ${Person20Regular} + Content After + + + $ + .00 + Content Before + After + +
+`); + +export const Placeholder = renderComponent(html` + + ${Person20Regular} + Disabled Input + +`); + +export const Appearance = renderComponent(html` +
+
+ + ${Person20Regular} + Outline (default) Input + +
+
+ + ${Person20Regular} + Underlined Input + +
+
+ + ${Person20Regular} + Filled Lighter Input + +
+
+ + ${Person20Regular} + Filled Darker Input + +
+
+`); + +export const Size = renderComponent(html` +
+ + ${Person20Regular} + Small Input + + + + ${Person20Regular} + Medium (default) Input + + + + ${Person20Regular} + Large Input + +
+`); + +export const Inline = renderComponent(html` +
+ + ${Person20Regular} + Inline Input + + + This input is an + + with a paragraph of text. + +
+`); + +export const Disabled = renderComponent(html` + + ${Person20Regular} + Disabled Input + +`); + +export const Required = renderComponent(html` + + ${Person20Regular} + Required Input + +`); diff --git a/packages/web-components/src/text-input/text-input.styles.ts b/packages/web-components/src/text-input/text-input.styles.ts new file mode 100644 index 00000000000000..492a01d4089ffe --- /dev/null +++ b/packages/web-components/src/text-input/text-input.styles.ts @@ -0,0 +1,245 @@ +import { css } from '@microsoft/fast-element'; +import { display } from '@microsoft/fast-foundation'; +import { + borderRadiusMedium, + colorCompoundBrandStroke, + colorCompoundBrandStrokePressed, + colorNeutralBackground1, + colorNeutralBackground3, + colorNeutralBackgroundInverted, + colorNeutralForeground1, + colorNeutralForeground3, + colorNeutralForeground4, + colorNeutralForegroundDisabled, + colorNeutralForegroundInverted, + colorNeutralStroke1, + colorNeutralStroke1Hover, + colorNeutralStroke1Pressed, + colorNeutralStrokeAccessible, + colorNeutralStrokeAccessibleHover, + colorNeutralStrokeAccessiblePressed, + colorNeutralStrokeDisabled, + colorTransparentBackground, + colorTransparentStroke, + colorTransparentStrokeInteractive, + curveAccelerateMid, + curveDecelerateMid, + durationNormal, + durationUltraFast, + fontFamilyBase, + fontSizeBase200, + fontSizeBase300, + fontSizeBase400, + fontSizeBase500, + fontSizeBase600, + fontWeightRegular, + lineHeightBase200, + lineHeightBase300, + lineHeightBase400, + shadow2, + spacingHorizontalM, + spacingHorizontalMNudge, + spacingHorizontalS, + spacingHorizontalSNudge, + spacingHorizontalXS, + spacingHorizontalXXS, + spacingVerticalXS, + strokeWidthThin, +} from '../theme/design-tokens.js'; + +/** TextInput styles + * @public + */ +export const styles = css` + ${display('block')} + + :host { + font-family: ${fontFamilyBase}; + font-size: ${fontSizeBase300}; + font-weight: ${fontWeightRegular}; + line-height: ${lineHeightBase300}; + max-width: 400px; + } + .label { + display: flex; + color: ${colorNeutralForeground1}; + padding-bottom: ${spacingVerticalXS}; + flex-shrink: 0; + padding-inline-end: ${spacingHorizontalXS}; + } + .label__hidden { + display: none; + } + .root { + position: relative; + box-sizing: border-box; + height: 32px; + display: inline-flex; + align-items: center; + flex-direction: row; + width: 100%; + padding: 0 ${spacingHorizontalMNudge}; + border: ${strokeWidthThin} solid ${colorNeutralStroke1}; + border-bottom-color: ${colorNeutralStrokeAccessible}; + border-radius: ${borderRadiusMedium}; + gap: ${spacingHorizontalXXS}; + } + .root::after { + box-sizing: border-box; + content: ''; + position: absolute; + left: -1px; + bottom: 0px; + right: -1px; + height: max(2px, ${borderRadiusMedium}); + border-radius: 0 0 ${borderRadiusMedium} ${borderRadiusMedium}; + border-bottom: 2px solid ${colorCompoundBrandStroke}; + clip-path: inset(calc(100% - 2px) 1px 0px); + transform: scaleX(0); + transition-property: transform; + transition-duration: ${durationUltraFast}; + transition-delay: ${curveAccelerateMid}; + } + .control { + width: 100%; + height: 100%; + box-sizing: border-box; + color: ${colorNeutralForeground1}; + border-radius: ${borderRadiusMedium}; + background: ${colorTransparentBackground}; + font-family: ${fontFamilyBase}; + font-weight: ${fontWeightRegular}; + font-size: ${fontSizeBase300}; + border: none; + background: transparent; + vertical-align: center; + } + .control:focus-visible { + outline: 0; + border: 0; + } + .control::placeholder { + color: ${colorNeutralForeground4}; + } + :host ::slotted([slot='start']), + :host ::slotted([slot='end']) { + display: flex; + align-items: center; + justify-content: center; + color: ${colorNeutralForeground3}; + font-size: ${fontSizeBase500}; + } + :host ::slotted([slot='start']) { + padding-right: ${spacingHorizontalXXS}; + } + :host ::slotted([slot='end']) { + padding-left: ${spacingHorizontalXXS}; + gap: ${spacingHorizontalXS}; + } + :host(:hover) .root { + border-color: ${colorNeutralStroke1Hover}; + border-bottom-color: ${colorNeutralStrokeAccessibleHover}; + } + :host(:active) .root { + border-color: ${colorNeutralStroke1Pressed}; + } + :host(:focus-within) .root { + outline: transparent solid 2px; + border-bottom: 0; + } + :host(:focus-within) .root::after { + transform: scaleX(1); + transition-property: transform; + transition-duration: ${durationNormal}; + transition-delay: ${curveDecelerateMid}; + } + :host(:focus-within:active) .root:after { + border-bottom-color: ${colorCompoundBrandStrokePressed}; + } + :host([appearance='outline']:focus-within) .root { + border: ${strokeWidthThin} solid ${colorNeutralStroke1}; + } + :host(:focus-within) .control { + color: ${colorNeutralForeground1}; + } + :host([disabled]) .root { + background: ${colorTransparentBackground}; + border: ${strokeWidthThin} solid ${colorNeutralStrokeDisabled}; + } + :host([disabled]) .control::placeholder, + :host([disabled]) ::slotted([slot='start']), + :host([disabled]) ::slotted([slot='end']) { + color: ${colorNeutralForegroundDisabled}; + } + ::selection { + color: ${colorNeutralForegroundInverted}; + background-color: ${colorNeutralBackgroundInverted}; + } + :host([control-size='small']) .control { + font-size: ${fontSizeBase200}; + font-weight: ${fontWeightRegular}; + line-height: ${lineHeightBase200}; + } + :host([control-size='small']) .root { + height: 24px; + gap: ${spacingHorizontalXXS}; + padding: 0 ${spacingHorizontalSNudge}; + } + :host([control-size='small']) ::slotted([slot='start']), + :host([control-size='small']) ::slotted([slot='end']) { + font-size: ${fontSizeBase400}; + } + :host([control-size='large']) .control { + font-size: ${fontSizeBase400}; + font-weight: ${fontWeightRegular}; + line-height: ${lineHeightBase400}; + } + :host([control-size='large']) .root { + height: 40px; + gap: ${spacingHorizontalS}; + padding: 0 ${spacingHorizontalM}; + } + :host([control-size='large']) ::slotted([slot='start']), + :host([control-size='large']) ::slotted([slot='end']) { + font-size: ${fontSizeBase600}; + } + :host([appearance='underline']) .root { + background: ${colorTransparentBackground}; + border: 0; + border-radius: 0; + border-bottom: ${strokeWidthThin} solid ${colorNeutralStrokeAccessible}; + } + :host([appearance='underline']:hover) .root { + border-bottom-color: ${colorNeutralStrokeAccessibleHover}; + } + :host([appearance='underline']:active) .root { + border-bottom-color: ${colorNeutralStrokeAccessiblePressed}; + } + :host([appearance='underline']:focus-within) .root { + border: 0; + border-bottom-color: ${colorNeutralStrokeAccessiblePressed}; + } + :host([appearance='underline'][disabled]) .root { + border-bottom-color: ${colorNeutralStrokeDisabled}; + } + :host([appearance='filled-lighter']) .root, + :host([appearance='filled-darker']) .root { + border: ${strokeWidthThin} solid ${colorTransparentStroke}; + box-shadow: ${shadow2}; + } + :host([appearance='filled-lighter']) .root { + background: ${colorNeutralBackground1}; + } + :host([appearance='filled-darker']) .root { + background: ${colorNeutralBackground3}; + } + :host([appearance='filled-lighter']:hover) .root, + :host([appearance='filled-darker']:hover) .root { + border-color: ${colorTransparentStrokeInteractive}; + } + :host([appearance='filled-lighter']:active) .root, + :host([appearance='filled-darker']:active) .root { + border-color: ${colorTransparentStrokeInteractive}; + background: ${colorNeutralBackground3}; + } +`; diff --git a/packages/web-components/src/text-input/text-input.template.ts b/packages/web-components/src/text-input/text-input.template.ts new file mode 100644 index 00000000000000..5407488f02289d --- /dev/null +++ b/packages/web-components/src/text-input/text-input.template.ts @@ -0,0 +1,8 @@ +import { ElementViewTemplate } from '@microsoft/fast-element'; +import { textFieldTemplate } from '@microsoft/fast-foundation'; +import type { TextInput } from './text-input.js'; + +/** + * @internal + */ +export const template: ElementViewTemplate = textFieldTemplate(); diff --git a/packages/web-components/src/text-input/text-input.ts b/packages/web-components/src/text-input/text-input.ts new file mode 100644 index 00000000000000..5a69d713c92e4d --- /dev/null +++ b/packages/web-components/src/text-input/text-input.ts @@ -0,0 +1,31 @@ +import { attr } from '@microsoft/fast-element'; +import { FASTTextField } from '@microsoft/fast-foundation'; +import { TextInputAppearance, TextInputControlSize } from './text-input.options.js'; + +/** + * The base class used for constructing a fluent-text-input custom element + * @public + */ +export class TextInput extends FASTTextField { + /** + * Defines TextInput control size + * + * @public + * @default 'medium' + * @remarks + * HTML Attribute: control-size + */ + @attr({ attribute: 'control-size' }) + public controlSize?: TextInputControlSize; + + /** + * Defines TextInput appearance. + * + * @public + * @default 'outline' + * @remarks + * HTML Attribute: appearance + */ + @attr + public appearance?: TextInputAppearance; +}