From 2c0fafd3d8c45779330c948d44921b9b396fd564 Mon Sep 17 00:00:00 2001 From: Elliott Marquez <5981958+e111077@users.noreply.github.com> Date: Tue, 4 Jun 2024 21:57:37 -0700 Subject: [PATCH] docs: update analyzer and update docs --- docs/components/button.md | 110 ++++++++--------- docs/components/checkbox.md | 42 ++++--- docs/components/chip.md | 129 +++++++++++++------- docs/components/dialog.md | 38 +++--- docs/components/divider.md | 10 +- docs/components/fab.md | 30 ++--- docs/components/focus-ring.md | 30 +++-- docs/components/icon-button.md | 157 +++++++++++++++--------- docs/components/list.md | 32 ++--- docs/components/menu.md | 131 ++++++++++---------- docs/components/progress.md | 26 ++-- docs/components/radio.md | 34 ++++-- docs/components/ripple.md | 18 +-- docs/components/select.md | 182 ++++++++++++++------------- docs/components/slider.md | 68 +++++++---- docs/components/switch.md | 40 +++--- docs/components/tabs.md | 54 ++++----- docs/components/text-field.md | 216 ++++++++++++++++++--------------- package-lock.json | 18 +-- package.json | 2 +- 20 files changed, 759 insertions(+), 608 deletions(-) diff --git a/docs/components/button.md b/docs/components/button.md index 9028282fc7..49cdf4706f 100644 --- a/docs/components/button.md +++ b/docs/components/button.md @@ -710,17 +710,17 @@ Token | Default value -Property | Attribute | Type | Default | Description ---- | --- | --- | --- | --- -`disabled` | `disabled` | `boolean` | `false` | Whether or not the button is disabled. -`href` | `href` | `string` | `''` | The URL that the link button points to. -`target` | `target` | `string` | `''` | Where to display the linked `href` URL for a link button. Common options include `_blank` to open in a new tab. -`trailingIcon` | `trailing-icon` | `boolean` | `false` | Whether to render the icon at the inline end of the label rather than the inline start.
_Note:_ Link buttons cannot have trailing icons. -`hasIcon` | `has-icon` | `boolean` | `false` | Whether to display the icon or not. -`type` | `type` | `string` | `'submit'` | -`value` | `value` | `string` | `''` | -`name` | | `string` | `undefined` | -`form` | | `HTMLFormElement` | `undefined` | +| Property | Attribute | Type | Default | Description | +| --- | --- | --- | --- | --- | +| `disabled` | `disabled` | `boolean` | `false` | Whether or not the button is disabled. | +| `href` | `href` | `string` | `''` | The URL that the link button points to. | +| `target` | `target` | `string` | `''` | Where to display the linked `href` URL for a link button. Common options include `_blank` to open in a new tab. | +| `trailingIcon` | `trailing-icon` | `boolean` | `false` | Whether to render the icon at the inline end of the label rather than the inline start.
_Note:_ Link buttons cannot have trailing icons. | +| `hasIcon` | `has-icon` | `boolean` | `false` | Whether to display the icon or not. | +| `type` | `type` | `string` | `'submit'` | The default behavior of the button. May be "text", "reset", or "submit" (default). | +| `value` | `value` | `string` | `''` | The value added to a form with the button's name when the button submits a form. | +| `name` | | `string` | `undefined` | | +| `form` | | `HTMLFormElement` | `undefined` | | @@ -730,17 +730,17 @@ Property | Attribute | Type | Default | Description -Property | Attribute | Type | Default | Description ---- | --- | --- | --- | --- -`disabled` | `disabled` | `boolean` | `false` | Whether or not the button is disabled. -`href` | `href` | `string` | `''` | The URL that the link button points to. -`target` | `target` | `string` | `''` | Where to display the linked `href` URL for a link button. Common options include `_blank` to open in a new tab. -`trailingIcon` | `trailing-icon` | `boolean` | `false` | Whether to render the icon at the inline end of the label rather than the inline start.
_Note:_ Link buttons cannot have trailing icons. -`hasIcon` | `has-icon` | `boolean` | `false` | Whether to display the icon or not. -`type` | `type` | `string` | `'submit'` | -`value` | `value` | `string` | `''` | -`name` | | `string` | `undefined` | -`form` | | `HTMLFormElement` | `undefined` | +| Property | Attribute | Type | Default | Description | +| --- | --- | --- | --- | --- | +| `disabled` | `disabled` | `boolean` | `false` | Whether or not the button is disabled. | +| `href` | `href` | `string` | `''` | The URL that the link button points to. | +| `target` | `target` | `string` | `''` | Where to display the linked `href` URL for a link button. Common options include `_blank` to open in a new tab. | +| `trailingIcon` | `trailing-icon` | `boolean` | `false` | Whether to render the icon at the inline end of the label rather than the inline start.
_Note:_ Link buttons cannot have trailing icons. | +| `hasIcon` | `has-icon` | `boolean` | `false` | Whether to display the icon or not. | +| `type` | `type` | `string` | `'submit'` | The default behavior of the button. May be "text", "reset", or "submit" (default). | +| `value` | `value` | `string` | `''` | The value added to a form with the button's name when the button submits a form. | +| `name` | | `string` | `undefined` | | +| `form` | | `HTMLFormElement` | `undefined` | | @@ -750,17 +750,17 @@ Property | Attribute | Type | Default | Description -Property | Attribute | Type | Default | Description ---- | --- | --- | --- | --- -`disabled` | `disabled` | `boolean` | `false` | Whether or not the button is disabled. -`href` | `href` | `string` | `''` | The URL that the link button points to. -`target` | `target` | `string` | `''` | Where to display the linked `href` URL for a link button. Common options include `_blank` to open in a new tab. -`trailingIcon` | `trailing-icon` | `boolean` | `false` | Whether to render the icon at the inline end of the label rather than the inline start.
_Note:_ Link buttons cannot have trailing icons. -`hasIcon` | `has-icon` | `boolean` | `false` | Whether to display the icon or not. -`type` | `type` | `string` | `'submit'` | -`value` | `value` | `string` | `''` | -`name` | | `string` | `undefined` | -`form` | | `HTMLFormElement` | `undefined` | +| Property | Attribute | Type | Default | Description | +| --- | --- | --- | --- | --- | +| `disabled` | `disabled` | `boolean` | `false` | Whether or not the button is disabled. | +| `href` | `href` | `string` | `''` | The URL that the link button points to. | +| `target` | `target` | `string` | `''` | Where to display the linked `href` URL for a link button. Common options include `_blank` to open in a new tab. | +| `trailingIcon` | `trailing-icon` | `boolean` | `false` | Whether to render the icon at the inline end of the label rather than the inline start.
_Note:_ Link buttons cannot have trailing icons. | +| `hasIcon` | `has-icon` | `boolean` | `false` | Whether to display the icon or not. | +| `type` | `type` | `string` | `'submit'` | The default behavior of the button. May be "text", "reset", or "submit" (default). | +| `value` | `value` | `string` | `''` | The value added to a form with the button's name when the button submits a form. | +| `name` | | `string` | `undefined` | | +| `form` | | `HTMLFormElement` | `undefined` | | @@ -770,17 +770,17 @@ Property | Attribute | Type | Default | Description -Property | Attribute | Type | Default | Description ---- | --- | --- | --- | --- -`disabled` | `disabled` | `boolean` | `false` | Whether or not the button is disabled. -`href` | `href` | `string` | `''` | The URL that the link button points to. -`target` | `target` | `string` | `''` | Where to display the linked `href` URL for a link button. Common options include `_blank` to open in a new tab. -`trailingIcon` | `trailing-icon` | `boolean` | `false` | Whether to render the icon at the inline end of the label rather than the inline start.
_Note:_ Link buttons cannot have trailing icons. -`hasIcon` | `has-icon` | `boolean` | `false` | Whether to display the icon or not. -`type` | `type` | `string` | `'submit'` | -`value` | `value` | `string` | `''` | -`name` | | `string` | `undefined` | -`form` | | `HTMLFormElement` | `undefined` | +| Property | Attribute | Type | Default | Description | +| --- | --- | --- | --- | --- | +| `disabled` | `disabled` | `boolean` | `false` | Whether or not the button is disabled. | +| `href` | `href` | `string` | `''` | The URL that the link button points to. | +| `target` | `target` | `string` | `''` | Where to display the linked `href` URL for a link button. Common options include `_blank` to open in a new tab. | +| `trailingIcon` | `trailing-icon` | `boolean` | `false` | Whether to render the icon at the inline end of the label rather than the inline start.
_Note:_ Link buttons cannot have trailing icons. | +| `hasIcon` | `has-icon` | `boolean` | `false` | Whether to display the icon or not. | +| `type` | `type` | `string` | `'submit'` | The default behavior of the button. May be "text", "reset", or "submit" (default). | +| `value` | `value` | `string` | `''` | The value added to a form with the button's name when the button submits a form. | +| `name` | | `string` | `undefined` | | +| `form` | | `HTMLFormElement` | `undefined` | | @@ -790,17 +790,17 @@ Property | Attribute | Type | Default | Description -Property | Attribute | Type | Default | Description ---- | --- | --- | --- | --- -`disabled` | `disabled` | `boolean` | `false` | Whether or not the button is disabled. -`href` | `href` | `string` | `''` | The URL that the link button points to. -`target` | `target` | `string` | `''` | Where to display the linked `href` URL for a link button. Common options include `_blank` to open in a new tab. -`trailingIcon` | `trailing-icon` | `boolean` | `false` | Whether to render the icon at the inline end of the label rather than the inline start.
_Note:_ Link buttons cannot have trailing icons. -`hasIcon` | `has-icon` | `boolean` | `false` | Whether to display the icon or not. -`type` | `type` | `string` | `'submit'` | -`value` | `value` | `string` | `''` | -`name` | | `string` | `undefined` | -`form` | | `HTMLFormElement` | `undefined` | +| Property | Attribute | Type | Default | Description | +| --- | --- | --- | --- | --- | +| `disabled` | `disabled` | `boolean` | `false` | Whether or not the button is disabled. | +| `href` | `href` | `string` | `''` | The URL that the link button points to. | +| `target` | `target` | `string` | `''` | Where to display the linked `href` URL for a link button. Common options include `_blank` to open in a new tab. | +| `trailingIcon` | `trailing-icon` | `boolean` | `false` | Whether to render the icon at the inline end of the label rather than the inline start.
_Note:_ Link buttons cannot have trailing icons. | +| `hasIcon` | `has-icon` | `boolean` | `false` | Whether to display the icon or not. | +| `type` | `type` | `string` | `'submit'` | The default behavior of the button. May be "text", "reset", or "submit" (default). | +| `value` | `value` | `string` | `''` | The value added to a form with the button's name when the button submits a form. | +| `name` | | `string` | `undefined` | | +| `form` | | `HTMLFormElement` | `undefined` | | diff --git a/docs/components/checkbox.md b/docs/components/checkbox.md index 67408ceb52..2ae0332224 100644 --- a/docs/components/checkbox.md +++ b/docs/components/checkbox.md @@ -168,25 +168,21 @@ Token | Default value ## API + ### MdCheckbox <md-checkbox> #### Properties -Property | Attribute | Type | Default | Description ---- | --- | --- | --- | --- -`checked` | `checked` | `boolean` | `false` | Whether or not the checkbox is selected. -`disabled` | `disabled` | `boolean` | `false` | Whether or not the checkbox is disabled. -`indeterminate` | `indeterminate` | `boolean` | `false` | Whether or not the checkbox is indeterminate.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#indeterminate_state_checkboxes -`required` | `required` | `boolean` | `false` | When true, require the checkbox to be selected when participating in form submission.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#validation -`value` | `value` | `string` | `'on'` | The value of the checkbox that is submitted with a form when selected.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#value -`name` | | `string` | `undefined` | -`form` | | `HTMLFormElement` | `undefined` | -`labels` | | `NodeList` | `undefined` | -`validity` | | `ValidityState` | `undefined` | -`validationMessage` | | `string` | `undefined` | -`willValidate` | | `boolean` | `undefined` | +| Property | Attribute | Type | Default | Description | +| --- | --- | --- | --- | --- | +| `checked` | `checked` | `boolean` | `false` | Whether or not the checkbox is selected. | +| `indeterminate` | `indeterminate` | `boolean` | `false` | Whether or not the checkbox is indeterminate.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#indeterminate_state_checkboxes | +| `required` | `required` | `boolean` | `false` | When true, require the checkbox to be selected when participating in form submission.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#validation | +| `value` | `value` | `string` | `'on'` | The value of the checkbox that is submitted with a form when selected.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#value | +| `disabled` | | `boolean` | `undefined` | | +| `name` | | `string` | `undefined` | | @@ -194,11 +190,21 @@ Property | Attribute | Type | Default | Description -Method | Parameters | Returns | Description ---- | --- | --- | --- -`checkValidity` | _None_ | `boolean` | Checks the checkbox's native validation and returns whether or not the element is valid.
If invalid, this method will dispatch the `invalid` event.
https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/checkValidity -`reportValidity` | _None_ | `boolean` | Checks the checkbox's native validation and returns whether or not the element is valid.
If invalid, this method will dispatch the `invalid` event.
The `validationMessage` is reported to the user by the browser. Use `setCustomValidity()` to customize the `validationMessage`.
https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/reportValidity -`setCustomValidity` | `error` | `void` | Sets the checkbox's native validation error message. This is used to customize `validationMessage`.
When the error is not an empty string, the checkbox is considered invalid and `validity.customError` will be true.
https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setCustomValidity +| Method | Parameters | Returns | Description | +| --- | --- | --- | --- | +| `formResetCallback` | _None_ | `void` | | +| `formStateRestoreCallback` | `state` | `void` | | + + + +#### Events + + + +| Event | Type | [Bubbles](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/composed) | Description | +| --- | --- | --- | --- | --- | +| `change` | `Event` | Yes | No | The native `change` event on [``](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event) | +| `input` | `InputEvent` | Yes | Yes | The native `input` event on [``](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event) | diff --git a/docs/components/chip.md b/docs/components/chip.md index 6b83a6d936..2e372711f8 100644 --- a/docs/components/chip.md +++ b/docs/components/chip.md @@ -492,9 +492,9 @@ Token | Default value -Property | Attribute | Type | Default | Description ---- | --- | --- | --- | --- -`chips` | | `Chip[]` | `undefined` | +| Property | Attribute | Type | Default | Description | +| --- | --- | --- | --- | --- | +| `chips` | | `Chip[]` | `undefined` | | @@ -504,14 +504,25 @@ Property | Attribute | Type | Default | Description -Property | Attribute | Type | Default | Description ---- | --- | --- | --- | --- -`elevated` | `elevated` | `boolean` | `false` | -`href` | `href` | `string` | `''` | -`target` | `target` | `string` | `''` | -`disabled` | `disabled` | `boolean` | `false` | Whether or not the chip is disabled.
Disabled chips are not focusable, unless `always-focusable` is set. -`alwaysFocusable` | `always-focusable` | `boolean` | `false` | When true, allow disabled chips to be focused with arrow keys.
Add this when a chip needs increased visibility when disabled. See https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_disabled_controls for more guidance on when this is needed. -`label` | `label` | `string` | `''` | The label of the chip. +| Property | Attribute | Type | Default | Description | +| --- | --- | --- | --- | --- | +| `elevated` | `elevated` | `boolean` | `false` | | +| `href` | `href` | `string` | `''` | | +| `target` | `target` | `string` | `''` | | +| `disabled` | `disabled` | `boolean` | `false` | Whether or not the chip is disabled.
Disabled chips are not focusable, unless `always-focusable` is set. | +| `alwaysFocusable` | `always-focusable` | `boolean` | `false` | When true, allow disabled chips to be focused with arrow keys.
Add this when a chip needs increased visibility when disabled. See https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_disabled_controls for more guidance on when this is needed. | +| `label` | `label` | `string` | `''` | The label of the chip. | +| `hasIcon` | `has-icon` | `boolean` | `false` | Only needed for SSR.
Add this attribute when a chip has a `slot="icon"` to avoid a Flash Of Unstyled Content. | + + + +#### Events + + + +| Event | Type | [Bubbles](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/composed) | Description | +| --- | --- | --- | --- | --- | +| `update-focus` | `Event` | Yes | No | Dispatched when `disabled` is toggled. | @@ -521,16 +532,29 @@ Property | Attribute | Type | Default | Description -Property | Attribute | Type | Default | Description ---- | --- | --- | --- | --- -`elevated` | `elevated` | `boolean` | `false` | -`removable` | `removable` | `boolean` | `false` | -`selected` | `selected` | `boolean` | `false` | -`disabled` | `disabled` | `boolean` | `false` | Whether or not the chip is disabled.
Disabled chips are not focusable, unless `always-focusable` is set. -`alwaysFocusable` | `always-focusable` | `boolean` | `false` | When true, allow disabled chips to be focused with arrow keys.
Add this when a chip needs increased visibility when disabled. See https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_disabled_controls for more guidance on when this is needed. -`label` | `label` | `string` | `''` | The label of the chip. -`handleTrailingActionFocus` | | `() => void` | `undefined` | -`ariaLabelRemove` | | `string` | `undefined` | +| Property | Attribute | Type | Default | Description | +| --- | --- | --- | --- | --- | +| `elevated` | `elevated` | `boolean` | `false` | | +| `removable` | `removable` | `boolean` | `false` | | +| `selected` | `selected` | `boolean` | `false` | | +| `hasSelectedIcon` | `has-selected-icon` | `boolean` | `false` | Only needed for SSR.
Add this attribute when a filter chip has a `slot="selected-icon"` to avoid a Flash Of Unstyled Content. | +| `disabled` | `disabled` | `boolean` | `false` | Whether or not the chip is disabled.
Disabled chips are not focusable, unless `always-focusable` is set. | +| `alwaysFocusable` | `always-focusable` | `boolean` | `false` | When true, allow disabled chips to be focused with arrow keys.
Add this when a chip needs increased visibility when disabled. See https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_disabled_controls for more guidance on when this is needed. | +| `label` | `label` | `string` | `''` | The label of the chip. | +| `hasIcon` | `has-icon` | `boolean` | `false` | Only needed for SSR.
Add this attribute when a chip has a `slot="icon"` to avoid a Flash Of Unstyled Content. | +| `handleTrailingActionFocus` | | `() => void` | `undefined` | | +| `ariaLabelRemove` | | `string` | `undefined` | | + + + +#### Events + + + +| Event | Type | [Bubbles](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/composed) | Description | +| --- | --- | --- | --- | --- | +| `remove` | `Event` | No | No | Dispatched when the remove button is clicked. | +| `update-focus` | `Event` | Yes | No | Dispatched when `disabled` is toggled. | @@ -540,18 +564,30 @@ Property | Attribute | Type | Default | Description -Property | Attribute | Type | Default | Description ---- | --- | --- | --- | --- -`avatar` | `avatar` | `boolean` | `false` | -`href` | `href` | `string` | `''` | -`target` | `target` | `string` | `''` | -`removeOnly` | `remove-only` | `boolean` | `false` | -`selected` | `selected` | `boolean` | `false` | -`disabled` | `disabled` | `boolean` | `false` | Whether or not the chip is disabled.
Disabled chips are not focusable, unless `always-focusable` is set. -`alwaysFocusable` | `always-focusable` | `boolean` | `false` | When true, allow disabled chips to be focused with arrow keys.
Add this when a chip needs increased visibility when disabled. See https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_disabled_controls for more guidance on when this is needed. -`label` | `label` | `string` | `''` | The label of the chip. -`handleTrailingActionFocus` | | `() => void` | `undefined` | -`ariaLabelRemove` | | `string` | `undefined` | +| Property | Attribute | Type | Default | Description | +| --- | --- | --- | --- | --- | +| `avatar` | `avatar` | `boolean` | `false` | | +| `href` | `href` | `string` | `''` | | +| `target` | `target` | `string` | `''` | | +| `removeOnly` | `remove-only` | `boolean` | `false` | | +| `selected` | `selected` | `boolean` | `false` | | +| `disabled` | `disabled` | `boolean` | `false` | Whether or not the chip is disabled.
Disabled chips are not focusable, unless `always-focusable` is set. | +| `alwaysFocusable` | `always-focusable` | `boolean` | `false` | When true, allow disabled chips to be focused with arrow keys.
Add this when a chip needs increased visibility when disabled. See https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_disabled_controls for more guidance on when this is needed. | +| `label` | `label` | `string` | `''` | The label of the chip. | +| `hasIcon` | `has-icon` | `boolean` | `false` | Only needed for SSR.
Add this attribute when a chip has a `slot="icon"` to avoid a Flash Of Unstyled Content. | +| `handleTrailingActionFocus` | | `() => void` | `undefined` | | +| `ariaLabelRemove` | | `string` | `undefined` | | + + + +#### Events + + + +| Event | Type | [Bubbles](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/composed) | Description | +| --- | --- | --- | --- | --- | +| `remove` | `Event` | No | No | Dispatched when the remove button is clicked. | +| `update-focus` | `Event` | Yes | No | Dispatched when `disabled` is toggled. | @@ -561,14 +597,25 @@ Property | Attribute | Type | Default | Description -Property | Attribute | Type | Default | Description ---- | --- | --- | --- | --- -`elevated` | `elevated` | `boolean` | `false` | -`href` | `href` | `string` | `''` | -`target` | `target` | `string` | `''` | -`disabled` | `disabled` | `boolean` | `false` | Whether or not the chip is disabled.
Disabled chips are not focusable, unless `always-focusable` is set. -`alwaysFocusable` | `always-focusable` | `boolean` | `false` | When true, allow disabled chips to be focused with arrow keys.
Add this when a chip needs increased visibility when disabled. See https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_disabled_controls for more guidance on when this is needed. -`label` | `label` | `string` | `''` | The label of the chip. +| Property | Attribute | Type | Default | Description | +| --- | --- | --- | --- | --- | +| `elevated` | `elevated` | `boolean` | `false` | | +| `href` | `href` | `string` | `''` | | +| `target` | `target` | `string` | `''` | | +| `disabled` | `disabled` | `boolean` | `false` | Whether or not the chip is disabled.
Disabled chips are not focusable, unless `always-focusable` is set. | +| `alwaysFocusable` | `always-focusable` | `boolean` | `false` | When true, allow disabled chips to be focused with arrow keys.
Add this when a chip needs increased visibility when disabled. See https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_disabled_controls for more guidance on when this is needed. | +| `label` | `label` | `string` | `''` | The label of the chip. | +| `hasIcon` | `has-icon` | `boolean` | `false` | Only needed for SSR.
Add this attribute when a chip has a `slot="icon"` to avoid a Flash Of Unstyled Content. | + + + +#### Events + + + +| Event | Type | [Bubbles](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/composed) | Description | +| --- | --- | --- | --- | --- | +| `update-focus` | `Event` | Yes | No | Dispatched when `disabled` is toggled. | diff --git a/docs/components/dialog.md b/docs/components/dialog.md index f81b40aa5b..06d499c766 100644 --- a/docs/components/dialog.md +++ b/docs/components/dialog.md @@ -222,13 +222,15 @@ Token | Default value -Property | Attribute | Type | Default | Description ---- | --- | --- | --- | --- -`returnValue` | | `string` | `''` | Gets or sets the dialog's return value, usually to indicate which button a user pressed to close it.
https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/returnValue -`type` | `type` | `string` | `undefined` | The type of dialog for accessibility. Set this to `alert` to announce a dialog as an alert dialog. -`open` | `open` | `boolean` | `undefined` | -`getOpenAnimation` | | `() => DialogAnimation` | `function { ... }` | Gets the opening animation for a dialog. Set to a new function to customize the animation. -`getCloseAnimation` | | `() => DialogAnimation` | `function { ... }` | Gets the closing animation for a dialog. Set to a new function to customize the animation. +| Property | Attribute | Type | Default | Description | +| --- | --- | --- | --- | --- | +| `quick` | `quick` | `boolean` | `false` | Skips the opening and closing animations. | +| `returnValue` | | `string` | `''` | Gets or sets the dialog's return value, usually to indicate which button a user pressed to close it.
https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/returnValue | +| `type` | `type` | `string` | `undefined` | The type of dialog for accessibility. Set this to `alert` to announce a dialog as an alert dialog. | +| `noFocusTrap` | `no-focus-trap` | `boolean` | `false` | Disables focus trapping, which by default keeps keyboard Tab navigation within the dialog.
When disabled, after focusing the last element of a dialog, pressing Tab again will release focus from the window back to the browser (such as the URL bar).
Focus trapping is recommended for accessibility, and should not typically be disabled. Only turn this off if the use case of a dialog is more accessible without focus trapping. | +| `open` | `open` | `boolean` | `undefined` | | +| `getOpenAnimation` | | `() => DialogAnimation` | `function { ... }` | Gets the opening animation for a dialog. Set to a new function to customize the animation. | +| `getCloseAnimation` | | `() => DialogAnimation` | `function { ... }` | Gets the closing animation for a dialog. Set to a new function to customize the animation. | @@ -236,10 +238,10 @@ Property | Attribute | Type | Default | Description -Method | Parameters | Returns | Description ---- | --- | --- | --- -`show` | _None_ | `Promise` | Opens the dialog and fires a cancelable `open` event. After a dialog's animation, an `opened` event is fired.
Add an `autofocus` attribute to a child of the dialog that should receive focus after opening. -`close` | `returnValue` | `Promise` | Closes the dialog and fires a cancelable `close` event. After a dialog's animation, a `closed` event is fired. +| Method | Parameters | Returns | Description | +| --- | --- | --- | --- | +| `show` | _None_ | `Promise` | Opens the dialog and fires a cancelable `open` event. After a dialog's animation, an `opened` event is fired.
Add an `autofocus` attribute to a child of the dialog that should receive focus after opening. | +| `close` | `returnValue` | `Promise` | Closes the dialog and fires a cancelable `close` event. After a dialog's animation, a `closed` event is fired. | @@ -247,13 +249,13 @@ Method | Parameters | Returns | Description -Event | Description ---- | --- -`open` | Dispatched when the dialog is opening before any animations. -`opened` | Dispatched when the dialog has opened after any animations. -`close` | Dispatched when the dialog is closing before any animations. -`closed` | Dispatched when the dialog has closed after any animations. -`cancel` | Dispatched when the dialog has been canceled by clicking on the scrim or pressing Escape. +| Event | Type | [Bubbles](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/composed) | Description | +| --- | --- | --- | --- | --- | +| `open` | `Event` | No | No | Dispatched when the dialog is opening before any animations. | +| `opened` | `Event` | No | No | Dispatched when the dialog has opened after any animations. | +| `close` | `Event` | No | No | Dispatched when the dialog is closing before any animations. | +| `closed` | `Event` | No | No | Dispatched when the dialog has closed after any animations. | +| `cancel` | `Event` | No | No | Dispatched when the dialog has been canceled by clicking on the scrim or pressing Escape. | diff --git a/docs/components/divider.md b/docs/components/divider.md index 0185c0235f..8a89fc24b3 100644 --- a/docs/components/divider.md +++ b/docs/components/divider.md @@ -129,11 +129,11 @@ Token | Default value -Property | Attribute | Type | Default | Description ---- | --- | --- | --- | --- -`inset` | `inset` | `boolean` | `false` | Indents the divider with equal padding on both sides. -`insetStart` | `inset-start` | `boolean` | `false` | Indents the divider with padding on the leading side. -`insetEnd` | `inset-end` | `boolean` | `false` | Indents the divider with padding on the trailing side. +| Property | Attribute | Type | Default | Description | +| --- | --- | --- | --- | --- | +| `inset` | `inset` | `boolean` | `false` | Indents the divider with equal padding on both sides. | +| `insetStart` | `inset-start` | `boolean` | `false` | Indents the divider with padding on the leading side. | +| `insetEnd` | `inset-end` | `boolean` | `false` | Indents the divider with padding on the trailing side. | diff --git a/docs/components/fab.md b/docs/components/fab.md index 84822585ea..ca904f6af9 100644 --- a/docs/components/fab.md +++ b/docs/components/fab.md @@ -485,12 +485,12 @@ Add with a different theme applied](images/fab/theming-branded.webp) -Property | Attribute | Type | Default | Description ---- | --- | --- | --- | --- -`variant` | `variant` | `string` | `'surface'` | The FAB color variant to render. -`size` | `size` | `string` | `'medium'` | The size of the FAB.
NOTE: Branded FABs cannot be sized to `small`, and Extended FABs do not have different sizes. -`label` | `label` | `string` | `''` | The text to display on the FAB. -`lowered` | `lowered` | `boolean` | `false` | Lowers the FAB's elevation. +| Property | Attribute | Type | Default | Description | +| --- | --- | --- | --- | --- | +| `variant` | `variant` | `string` | `'surface'` | The FAB color variant to render. | +| `size` | `size` | `string` | `'medium'` | The size of the FAB.
NOTE: Branded FABs cannot be sized to `small`, and Extended FABs do not have different sizes. | +| `label` | `label` | `string` | `''` | The text to display on the FAB. | +| `lowered` | `lowered` | `boolean` | `false` | Lowers the FAB's elevation. | @@ -500,12 +500,12 @@ Property | Attribute | Type | Default | Description -Property | Attribute | Type | Default | Description ---- | --- | --- | --- | --- -`variant` | `variant` | `string` | `'surface'` | The FAB color variant to render. -`size` | `size` | `string` | `'medium'` | The size of the FAB.
NOTE: Branded FABs cannot be sized to `small`, and Extended FABs do not have different sizes. -`label` | `label` | `string` | `''` | The text to display on the FAB. -`lowered` | `lowered` | `boolean` | `false` | Lowers the FAB's elevation. +| Property | Attribute | Type | Default | Description | +| --- | --- | --- | --- | --- | +| `variant` | `variant` | `string` | `'surface'` | The FAB color variant to render. | +| `size` | `size` | `string` | `'medium'` | The size of the FAB.
NOTE: Branded FABs cannot be sized to `small`, and Extended FABs do not have different sizes. | +| `label` | `label` | `string` | `''` | The text to display on the FAB. | +| `lowered` | `lowered` | `boolean` | `false` | Lowers the FAB's elevation. | @@ -513,9 +513,9 @@ Property | Attribute | Type | Default | Description -Method | Parameters | Returns | Description ---- | --- | --- | --- -`getRenderClasses` | _None_ | `{ primary: boolean; secondary: boolean; tertiary: boolean; small: boolean; lowered: boolean; large: boolean; extended: boolean; }` | +| Method | Parameters | Returns | Description | +| --- | --- | --- | --- | +| `getRenderClasses` | _None_ | `{ primary: boolean; secondary: boolean; tertiary: boolean; small: boolean; lowered: boolean; large: boolean; extended: boolean; }` | | diff --git a/docs/components/focus-ring.md b/docs/components/focus-ring.md index 7afda86feb..561da23e71 100644 --- a/docs/components/focus-ring.md +++ b/docs/components/focus-ring.md @@ -141,12 +141,12 @@ md-focus-ring { -Property | Attribute | Type | Default | Description ---- | --- | --- | --- | --- -`visible` | `visible` | `boolean` | `false` | Makes the focus ring visible. -`inward` | `inward` | `boolean` | `false` | Makes the focus ring animate inwards instead of outwards. -`htmlFor` | | `string` | `undefined` | -`control` | | `HTMLElement` | `undefined` | +| Property | Attribute | Type | Default | Description | +| --- | --- | --- | --- | --- | +| `visible` | `visible` | `boolean` | `false` | Makes the focus ring visible. | +| `inward` | `inward` | `boolean` | `false` | Makes the focus ring animate inwards instead of outwards. | +| `htmlFor` | | `string` | `undefined` | | +| `control` | | `HTMLElement` | `undefined` | | @@ -154,10 +154,20 @@ Property | Attribute | Type | Default | Description -Method | Parameters | Returns | Description ---- | --- | --- | --- -`attach` | `control` | `void` | -`detach` | _None_ | `void` | +| Method | Parameters | Returns | Description | +| --- | --- | --- | --- | +| `attach` | `control` | `void` | | +| `detach` | _None_ | `void` | | + + + +#### Events + + + +| Event | Type | [Bubbles](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/composed) | Description | +| --- | --- | --- | --- | --- | +| `visibility-changed` | `Event` | No | No | Fired whenever `visible` changes. | diff --git a/docs/components/icon-button.md b/docs/components/icon-button.md index 7c2f581b3e..f28a4a4240 100644 --- a/docs/components/icon-button.md +++ b/docs/components/icon-button.md @@ -428,26 +428,38 @@ Token | Default value ## API + ### MdIconButton <md-icon-button> #### Properties -Property | Attribute | Type | Default | Description ---- | --- | --- | --- | --- -`disabled` | `disabled` | `boolean` | `false` | Disables the icon button and makes it non-interactive. -`flipIconInRtl` | `flip-icon-in-rtl` | `boolean` | `false` | Flips the icon if it is in an RTL context at startup. -`href` | `href` | `string` | `''` | Sets the underlying `HTMLAnchorElement`'s `href` resource attribute. -`target` | `target` | `string` | `''` | Sets the underlying `HTMLAnchorElement`'s `target` attribute. -`ariaLabelSelected` | `aria-label-selected` | `string` | `''` | The `aria-label` of the button when the button is toggleable and selected. -`toggle` | `toggle` | `boolean` | `false` | When true, the button will toggle between selected and unselected states -`selected` | `selected` | `boolean` | `false` | Sets the selected state. When false, displays the default icon. When true, displays the selected icon, or the default icon If no `slot="selected"` icon is provided. -`type` | `type` | `string` | `'submit'` | -`value` | `value` | `string` | `''` | -`name` | | `string` | `undefined` | -`form` | | `HTMLFormElement` | `undefined` | -`labels` | | `NodeList` | `undefined` | +| Property | Attribute | Type | Default | Description | +| --- | --- | --- | --- | --- | +| `disabled` | `disabled` | `boolean` | `false` | Disables the icon button and makes it non-interactive. | +| `flipIconInRtl` | `flip-icon-in-rtl` | `boolean` | `false` | Flips the icon if it is in an RTL context at startup. | +| `href` | `href` | `string` | `''` | Sets the underlying `HTMLAnchorElement`'s `href` resource attribute. | +| `target` | `target` | `string` | `''` | Sets the underlying `HTMLAnchorElement`'s `target` attribute. | +| `ariaLabelSelected` | `aria-label-selected` | `string` | `''` | The `aria-label` of the button when the button is toggleable and selected. | +| `toggle` | `toggle` | `boolean` | `false` | When true, the button will toggle between selected and unselected states | +| `selected` | `selected` | `boolean` | `false` | Sets the selected state. When false, displays the default icon. When true, displays the selected icon, or the default icon If no `slot="selected"` icon is provided. | +| `type` | `type` | `string` | `'submit'` | The default behavior of the button. May be "text", "reset", or "submit" (default). | +| `value` | `value` | `string` | `''` | The value added to a form with the button's name when the button submits a form. | +| `name` | | `string` | `undefined` | | +| `form` | | `HTMLFormElement` | `undefined` | | +| `labels` | | `NodeList` | `undefined` | | + + + +#### Events + + + +| Event | Type | [Bubbles](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/composed) | Description | +| --- | --- | --- | --- | --- | +| `input` | `InputEvent` | Yes | Yes | Dispatched when a toggle button toggles | +| `change` | `Event` | Yes | No | Dispatched when a toggle button toggles | @@ -457,20 +469,31 @@ Property | Attribute | Type | Default | Description -Property | Attribute | Type | Default | Description ---- | --- | --- | --- | --- -`disabled` | `disabled` | `boolean` | `false` | Disables the icon button and makes it non-interactive. -`flipIconInRtl` | `flip-icon-in-rtl` | `boolean` | `false` | Flips the icon if it is in an RTL context at startup. -`href` | `href` | `string` | `''` | Sets the underlying `HTMLAnchorElement`'s `href` resource attribute. -`target` | `target` | `string` | `''` | Sets the underlying `HTMLAnchorElement`'s `target` attribute. -`ariaLabelSelected` | `aria-label-selected` | `string` | `''` | The `aria-label` of the button when the button is toggleable and selected. -`toggle` | `toggle` | `boolean` | `false` | When true, the button will toggle between selected and unselected states -`selected` | `selected` | `boolean` | `false` | Sets the selected state. When false, displays the default icon. When true, displays the selected icon, or the default icon If no `slot="selected"` icon is provided. -`type` | `type` | `string` | `'submit'` | -`value` | `value` | `string` | `''` | -`name` | | `string` | `undefined` | -`form` | | `HTMLFormElement` | `undefined` | -`labels` | | `NodeList` | `undefined` | +| Property | Attribute | Type | Default | Description | +| --- | --- | --- | --- | --- | +| `disabled` | `disabled` | `boolean` | `false` | Disables the icon button and makes it non-interactive. | +| `flipIconInRtl` | `flip-icon-in-rtl` | `boolean` | `false` | Flips the icon if it is in an RTL context at startup. | +| `href` | `href` | `string` | `''` | Sets the underlying `HTMLAnchorElement`'s `href` resource attribute. | +| `target` | `target` | `string` | `''` | Sets the underlying `HTMLAnchorElement`'s `target` attribute. | +| `ariaLabelSelected` | `aria-label-selected` | `string` | `''` | The `aria-label` of the button when the button is toggleable and selected. | +| `toggle` | `toggle` | `boolean` | `false` | When true, the button will toggle between selected and unselected states | +| `selected` | `selected` | `boolean` | `false` | Sets the selected state. When false, displays the default icon. When true, displays the selected icon, or the default icon If no `slot="selected"` icon is provided. | +| `type` | `type` | `string` | `'submit'` | The default behavior of the button. May be "text", "reset", or "submit" (default). | +| `value` | `value` | `string` | `''` | The value added to a form with the button's name when the button submits a form. | +| `name` | | `string` | `undefined` | | +| `form` | | `HTMLFormElement` | `undefined` | | +| `labels` | | `NodeList` | `undefined` | | + + + +#### Events + + + +| Event | Type | [Bubbles](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/composed) | Description | +| --- | --- | --- | --- | --- | +| `input` | `InputEvent` | Yes | Yes | Dispatched when a toggle button toggles | +| `change` | `Event` | Yes | No | Dispatched when a toggle button toggles | @@ -480,20 +503,31 @@ Property | Attribute | Type | Default | Description -Property | Attribute | Type | Default | Description ---- | --- | --- | --- | --- -`disabled` | `disabled` | `boolean` | `false` | Disables the icon button and makes it non-interactive. -`flipIconInRtl` | `flip-icon-in-rtl` | `boolean` | `false` | Flips the icon if it is in an RTL context at startup. -`href` | `href` | `string` | `''` | Sets the underlying `HTMLAnchorElement`'s `href` resource attribute. -`target` | `target` | `string` | `''` | Sets the underlying `HTMLAnchorElement`'s `target` attribute. -`ariaLabelSelected` | `aria-label-selected` | `string` | `''` | The `aria-label` of the button when the button is toggleable and selected. -`toggle` | `toggle` | `boolean` | `false` | When true, the button will toggle between selected and unselected states -`selected` | `selected` | `boolean` | `false` | Sets the selected state. When false, displays the default icon. When true, displays the selected icon, or the default icon If no `slot="selected"` icon is provided. -`type` | `type` | `string` | `'submit'` | -`value` | `value` | `string` | `''` | -`name` | | `string` | `undefined` | -`form` | | `HTMLFormElement` | `undefined` | -`labels` | | `NodeList` | `undefined` | +| Property | Attribute | Type | Default | Description | +| --- | --- | --- | --- | --- | +| `disabled` | `disabled` | `boolean` | `false` | Disables the icon button and makes it non-interactive. | +| `flipIconInRtl` | `flip-icon-in-rtl` | `boolean` | `false` | Flips the icon if it is in an RTL context at startup. | +| `href` | `href` | `string` | `''` | Sets the underlying `HTMLAnchorElement`'s `href` resource attribute. | +| `target` | `target` | `string` | `''` | Sets the underlying `HTMLAnchorElement`'s `target` attribute. | +| `ariaLabelSelected` | `aria-label-selected` | `string` | `''` | The `aria-label` of the button when the button is toggleable and selected. | +| `toggle` | `toggle` | `boolean` | `false` | When true, the button will toggle between selected and unselected states | +| `selected` | `selected` | `boolean` | `false` | Sets the selected state. When false, displays the default icon. When true, displays the selected icon, or the default icon If no `slot="selected"` icon is provided. | +| `type` | `type` | `string` | `'submit'` | The default behavior of the button. May be "text", "reset", or "submit" (default). | +| `value` | `value` | `string` | `''` | The value added to a form with the button's name when the button submits a form. | +| `name` | | `string` | `undefined` | | +| `form` | | `HTMLFormElement` | `undefined` | | +| `labels` | | `NodeList` | `undefined` | | + + + +#### Events + + + +| Event | Type | [Bubbles](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/composed) | Description | +| --- | --- | --- | --- | --- | +| `input` | `InputEvent` | Yes | Yes | Dispatched when a toggle button toggles | +| `change` | `Event` | Yes | No | Dispatched when a toggle button toggles | @@ -503,20 +537,31 @@ Property | Attribute | Type | Default | Description -Property | Attribute | Type | Default | Description ---- | --- | --- | --- | --- -`disabled` | `disabled` | `boolean` | `false` | Disables the icon button and makes it non-interactive. -`flipIconInRtl` | `flip-icon-in-rtl` | `boolean` | `false` | Flips the icon if it is in an RTL context at startup. -`href` | `href` | `string` | `''` | Sets the underlying `HTMLAnchorElement`'s `href` resource attribute. -`target` | `target` | `string` | `''` | Sets the underlying `HTMLAnchorElement`'s `target` attribute. -`ariaLabelSelected` | `aria-label-selected` | `string` | `''` | The `aria-label` of the button when the button is toggleable and selected. -`toggle` | `toggle` | `boolean` | `false` | When true, the button will toggle between selected and unselected states -`selected` | `selected` | `boolean` | `false` | Sets the selected state. When false, displays the default icon. When true, displays the selected icon, or the default icon If no `slot="selected"` icon is provided. -`type` | `type` | `string` | `'submit'` | -`value` | `value` | `string` | `''` | -`name` | | `string` | `undefined` | -`form` | | `HTMLFormElement` | `undefined` | -`labels` | | `NodeList` | `undefined` | +| Property | Attribute | Type | Default | Description | +| --- | --- | --- | --- | --- | +| `disabled` | `disabled` | `boolean` | `false` | Disables the icon button and makes it non-interactive. | +| `flipIconInRtl` | `flip-icon-in-rtl` | `boolean` | `false` | Flips the icon if it is in an RTL context at startup. | +| `href` | `href` | `string` | `''` | Sets the underlying `HTMLAnchorElement`'s `href` resource attribute. | +| `target` | `target` | `string` | `''` | Sets the underlying `HTMLAnchorElement`'s `target` attribute. | +| `ariaLabelSelected` | `aria-label-selected` | `string` | `''` | The `aria-label` of the button when the button is toggleable and selected. | +| `toggle` | `toggle` | `boolean` | `false` | When true, the button will toggle between selected and unselected states | +| `selected` | `selected` | `boolean` | `false` | Sets the selected state. When false, displays the default icon. When true, displays the selected icon, or the default icon If no `slot="selected"` icon is provided. | +| `type` | `type` | `string` | `'submit'` | The default behavior of the button. May be "text", "reset", or "submit" (default). | +| `value` | `value` | `string` | `''` | The value added to a form with the button's name when the button submits a form. | +| `name` | | `string` | `undefined` | | +| `form` | | `HTMLFormElement` | `undefined` | | +| `labels` | | `NodeList` | `undefined` | | + + + +#### Events + + + +| Event | Type | [Bubbles](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/composed) | Description | +| --- | --- | --- | --- | --- | +| `input` | `InputEvent` | Yes | Yes | Dispatched when a toggle button toggles | +| `change` | `Event` | Yes | No | Dispatched when a toggle button toggles | diff --git a/docs/components/list.md b/docs/components/list.md index 4dd9621511..d625d6df5e 100644 --- a/docs/components/list.md +++ b/docs/components/list.md @@ -385,9 +385,9 @@ Token | Default value -Property | Attribute | Type | Default | Description ---- | --- | --- | --- | --- -`items` | | `ListItem[]` | `undefined` | +| Property | Attribute | Type | Default | Description | +| --- | --- | --- | --- | --- | +| `items` | | `ListItem[]` | `undefined` | | @@ -395,10 +395,10 @@ Property | Attribute | Type | Default | Description -Method | Parameters | Returns | Description ---- | --- | --- | --- -`activateNextItem` | _None_ | `ListItem` | Activates the next item in the list. If at the end of the list, the first item will be activated. -`activatePreviousItem` | _None_ | `ListItem` | Activates the previous item in the list. If at the start of the list, the last item will be activated. +| Method | Parameters | Returns | Description | +| --- | --- | --- | --- | +| `activateNextItem` | _None_ | `ListItem` | Activates the next item in the list. If at the end of the list, the first item will be activated. | +| `activatePreviousItem` | _None_ | `ListItem` | Activates the previous item in the list. If at the start of the list, the last item will be activated. | @@ -408,12 +408,12 @@ Method | Parameters | Returns | Description -Property | Attribute | Type | Default | Description ---- | --- | --- | --- | --- -`disabled` | `disabled` | `boolean` | `false` | Disables the item and makes it non-selectable and non-interactive. -`type` | `type` | `string` | `'text'` | Sets the behavior of the list item, defaults to "text". Change to "link" or "button" for interactive items. -`href` | `href` | `string` | `''` | Sets the underlying `HTMLAnchorElement`'s `href` resource attribute. -`target` | `target` | `string` | `''` | Sets the underlying `HTMLAnchorElement`'s `target` attribute when `href` is set. +| Property | Attribute | Type | Default | Description | +| --- | --- | --- | --- | --- | +| `disabled` | `disabled` | `boolean` | `false` | Disables the item and makes it non-selectable and non-interactive. | +| `type` | `type` | `string` | `'text'` | Sets the behavior of the list item, defaults to "text". Change to "link" or "button" for interactive items. | +| `href` | `href` | `string` | `''` | Sets the underlying `HTMLAnchorElement`'s `href` resource attribute. | +| `target` | `target` | `string` | `''` | Sets the underlying `HTMLAnchorElement`'s `target` attribute when `href` is set. | @@ -421,9 +421,9 @@ Property | Attribute | Type | Default | Description -Event | Description ---- | --- -`request-activation` | +| Event | Type | [Bubbles](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/composed) | Description | +| --- | --- | --- | --- | --- | +| `request-activation` | `Event` | Yes | Yes | Requests the list to set `tabindex=0` on the item and focus it. | diff --git a/docs/components/menu.md b/docs/components/menu.md index 65d5e19254..10a60af3ca 100644 --- a/docs/components/menu.md +++ b/docs/components/menu.md @@ -508,32 +508,34 @@ a sharp 0px border radius.](images/menu/theming.webp) ## API + ### MdMenu <md-menu> #### Properties -Property | Attribute | Type | Default | Description ---- | --- | --- | --- | --- -`anchor` | `anchor` | `string` | `''` | The ID of the element in the same root node in which the menu should align to. Overrides setting `anchorElement = elementReference`.
__NOTE__: anchor or anchorElement must either be an HTMLElement or resolve to an HTMLElement in order for menu to open. -`positioning` | `positioning` | `string` | `'absolute'` | Whether the positioning algorithm should calculate relative to the parent of the anchor element (absolute) or relative to the window (fixed).
Examples for `position = 'fixed'`:
- If there is no `position:relative` in the given parent tree and the surface is `position:absolute` - If the surface is `position:fixed` - If the surface is in the "top layer" - The anchor and the surface do not share a common `position:relative` ancestor
When using positioning = fixed, in most cases, the menu should position itself above most other `position:absolute` or `position:fixed` elements when placed inside of them, e.g. using a menu inside of an `md-dialog`.
__NOTE__: Fixed menus will not scroll with the page and will be fixed to the window instead. -`quick` | `quick` | `boolean` | `false` | Skips the opening and closing animations. -`hasOverflow` | `has-overflow` | `boolean` | `false` | Displays overflow content like a submenu.
__NOTE__: This may cause adverse effects if you set `md-menu {max-height:...}` and have items overflowing items in the "y" direction. -`open` | `open` | `boolean` | `false` | Opens the menu and makes it visible. Alternative to the `.show()` and `.close()` methods -`xOffset` | `x-offset` | `number` | `0` | Offsets the menu's inline alignment from the anchor by the given number in pixels. This value is direction aware and will follow the LTR / RTL direction.
e.g. LTR: positive -> right, negative -> left RTL: positive -> left, negative -> right -`yOffset` | `y-offset` | `number` | `0` | Offsets the menu's block alignment from the anchor by the given number in pixels.
e.g. positive -> down, negative -> up -`typeaheadDelay` | `typeahead-delay` | `number` | `200` | The max time between the keystrokes of the typeahead menu behavior before it clears the typeahead buffer. -`anchorCorner` | `anchor-corner` | `string` | `Corner.END_START` | The corner of the anchor which to align the menu in the standard logical property style of - e.g. `'end-start'`.
NOTE: This value may not be respected by the menu positioning algorithm if the menu would render outisde the viewport. -`menuCorner` | `menu-corner` | `string` | `Corner.START_START` | The corner of the menu which to align the anchor in the standard logical property style of - e.g. `'start-start'`.
NOTE: This value may not be respected by the menu positioning algorithm if the menu would render outisde the viewport. -`stayOpenOnOutsideClick` | `stay-open-on-outside-click` | `boolean` | `false` | Keeps the user clicks outside the menu.
NOTE: clicking outside may still cause focusout to close the menu so see `stayOpenOnFocusout`. -`stayOpenOnFocusout` | `stay-open-on-focusout` | `boolean` | `false` | Keeps the menu open when focus leaves the menu's composed subtree.
NOTE: Focusout behavior will stop propagation of the focusout event. Set this property to true to opt-out of menu's focusout handling altogether. -`skipRestoreFocus` | `skip-restore-focus` | `boolean` | `false` | After closing, does not restore focus to the last focused element before the menu was opened. -`defaultFocus` | `default-focus` | `string` | `FocusState.FIRST_ITEM` | The element that should be focused by default once opened.
NOTE: When setting default focus to 'LIST_ROOT', remember to change `tabindex` to `0` and change md-menu's display to something other than `display: contents` when necessary. -`isSubmenu` | | `boolean` | `false` | Whether or not the current menu is a submenu and should not handle specific navigation keys. -`typeaheadController` | | `TypeaheadController` | `function { ... }` | Handles typeahead navigation through the menu. -`anchorElement` | | `HTMLElement & Partial` | `undefined` | -`items` | | `MenuItem[]` | `undefined` | +| Property | Attribute | Type | Default | Description | +| --- | --- | --- | --- | --- | +| `anchor` | `anchor` | `string` | `''` | The ID of the element in the same root node in which the menu should align to. Overrides setting `anchorElement = elementReference`.
__NOTE__: anchor or anchorElement must either be an HTMLElement or resolve to an HTMLElement in order for menu to open. | +| `positioning` | `positioning` | `string` | `'absolute'` | Whether the positioning algorithm should calculate relative to the parent of the anchor element (`absolute`), relative to the window (`fixed`), or relative to the document (`document`). `popover` will use the popover API to render the menu in the top-layer. If your browser does not support the popover API, it will fall back to `fixed`.
__Examples for `position = 'fixed'`:__
- If there is no `position:relative` in the given parent tree and the surface is `position:absolute` - If the surface is `position:fixed` - If the surface is in the "top layer" - The anchor and the surface do not share a common `position:relative` ancestor
When using `positioning=fixed`, in most cases, the menu should position itself above most other `position:absolute` or `position:fixed` elements when placed inside of them. e.g. using a menu inside of an `md-dialog`.
__NOTE__: Fixed menus will not scroll with the page and will be fixed to the window instead.
__Examples for `position = 'document'`:__
- There is no parent that creates a relative positioning context e.g. `position: relative`, `position: absolute`, `transform: translate(x, y)`, etc. - You put the effort into hoisting the menu to the top of the DOM like the end of the `` to render over everything or in a top-layer. - You are reusing a single `md-menu` element that dynamically renders content.
__Examples for `position = 'popover'`:__
- Your browser supports `popover`. - Most cases. Once popover is in browsers, this will become the default. | +| `quick` | `quick` | `boolean` | `false` | Skips the opening and closing animations. | +| `hasOverflow` | `has-overflow` | `boolean` | `false` | Displays overflow content like a submenu. Not required in most cases when using `positioning="popover"`.
__NOTE__: This may cause adverse effects if you set `md-menu {max-height:...}` and have items overflowing items in the "y" direction. | +| `open` | `open` | `boolean` | `false` | Opens the menu and makes it visible. Alternative to the `.show()` and `.close()` methods | +| `xOffset` | `x-offset` | `number` | `0` | Offsets the menu's inline alignment from the anchor by the given number in pixels. This value is direction aware and will follow the LTR / RTL direction.
e.g. LTR: positive -> right, negative -> left RTL: positive -> left, negative -> right | +| `yOffset` | `y-offset` | `number` | `0` | Offsets the menu's block alignment from the anchor by the given number in pixels.
e.g. positive -> down, negative -> up | +| `typeaheadDelay` | `typeahead-delay` | `number` | `200` | The max time between the keystrokes of the typeahead menu behavior before it clears the typeahead buffer. | +| `anchorCorner` | `anchor-corner` | `string` | `Corner.END_START` | The corner of the anchor which to align the menu in the standard logical property style of - e.g. `'end-start'`.
NOTE: This value may not be respected by the menu positioning algorithm if the menu would render outisde the viewport. | +| `menuCorner` | `menu-corner` | `string` | `Corner.START_START` | The corner of the menu which to align the anchor in the standard logical property style of - e.g. `'start-start'`.
NOTE: This value may not be respected by the menu positioning algorithm if the menu would render outisde the viewport. | +| `stayOpenOnOutsideClick` | `stay-open-on-outside-click` | `boolean` | `false` | Keeps the user clicks outside the menu.
NOTE: clicking outside may still cause focusout to close the menu so see `stayOpenOnFocusout`. | +| `stayOpenOnFocusout` | `stay-open-on-focusout` | `boolean` | `false` | Keeps the menu open when focus leaves the menu's composed subtree.
NOTE: Focusout behavior will stop propagation of the focusout event. Set this property to true to opt-out of menu's focusout handling altogether. | +| `skipRestoreFocus` | `skip-restore-focus` | `boolean` | `false` | After closing, does not restore focus to the last focused element before the menu was opened. | +| `defaultFocus` | `default-focus` | `string` | `FocusState.FIRST_ITEM` | The element that should be focused by default once opened.
NOTE: When setting default focus to 'LIST_ROOT', remember to change `tabindex` to `0` and change md-menu's display to something other than `display: contents` when necessary. | +| `noNavigationWrap` | `no-navigation-wrap` | `boolean` | `false` | Turns off navigation wrapping. By default, navigating past the end of the menu items will wrap focus back to the beginning and vice versa. Use this for ARIA patterns that do not wrap focus, like combobox. | +| `isSubmenu` | | `boolean` | `false` | Whether or not the current menu is a submenu and should not handle specific navigation keys. | +| `typeaheadController` | | `TypeaheadController` | `function { ... }` | Handles typeahead navigation through the menu. | +| `anchorElement` | | `HTMLElement & Partial` | `undefined` | | +| `items` | | `MenuItem[]` | `undefined` | | @@ -541,12 +543,15 @@ Property | Attribute | Type | Default | Description -Method | Parameters | Returns | Description ---- | --- | --- | --- -`close` | _None_ | `void` | -`show` | _None_ | `void` | -`activateNextItem` | _None_ | `MenuItem` | Activates the next item in the menu. If at the end of the menu, the first item will be activated. -`activatePreviousItem` | _None_ | `MenuItem` | Activates the previous item in the menu. If at the start of the menu, the last item will be activated. +| Method | Parameters | Returns | Description | +| --- | --- | --- | --- | +| `getBoundingClientRect` | _None_ | `DOMRect` | | +| `getClientRects` | _None_ | `DOMRectList` | | +| `close` | _None_ | `void` | | +| `show` | _None_ | `void` | | +| `activateNextItem` | _None_ | `MenuItem` | Activates the next item in the menu. If at the end of the menu, the first item will be activated. | +| `activatePreviousItem` | _None_ | `MenuItem` | Activates the previous item in the menu. If at the start of the menu, the last item will be activated. | +| `reposition` | _None_ | `void` | Repositions the menu if it is open.
Useful for the case where document or window-positioned menus have their anchors moved while open. | @@ -554,12 +559,12 @@ Method | Parameters | Returns | Description -Event | Description ---- | --- -`opening` | Fired before the opening animation begins -`opened` | Fired once the menu is open, after any animations -`closing` | Fired before the closing animation begins -`closed` | Fired once the menu is closed, after any animations +| Event | Type | [Bubbles](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/composed) | Description | +| --- | --- | --- | --- | --- | +| `opening` | `Event` | No | No | Fired before the opening animation begins | +| `opened` | `Event` | No | No | Fired once the menu is open, after any animations | +| `closing` | `Event` | No | No | Fired before the closing animation begins | +| `closed` | `Event` | No | No | Fired once the menu is closed, after any animations | @@ -569,15 +574,15 @@ Event | Description -Property | Attribute | Type | Default | Description ---- | --- | --- | --- | --- -`disabled` | `disabled` | `boolean` | `false` | Disables the item and makes it non-selectable and non-interactive. -`type` | `type` | `string` | `'menuitem'` | Sets the behavior and role of the menu item, defaults to "menuitem". -`href` | `href` | `string` | `''` | Sets the underlying `HTMLAnchorElement`'s `href` resource attribute. -`target` | `target` | `string` | `''` | Sets the underlying `HTMLAnchorElement`'s `target` attribute when `href` is set. -`keepOpen` | `keep-open` | `boolean` | `false` | Keeps the menu open if clicked or keyboard selected. -`selected` | `selected` | `boolean` | `false` | Sets the item in the selected visual state when a submenu is opened. -`typeaheadText` | | `string` | `undefined` | +| Property | Attribute | Type | Default | Description | +| --- | --- | --- | --- | --- | +| `disabled` | `disabled` | `boolean` | `false` | Disables the item and makes it non-selectable and non-interactive. | +| `type` | `type` | `string` | `'menuitem'` | Sets the behavior and role of the menu item, defaults to "menuitem". | +| `href` | `href` | `string` | `''` | Sets the underlying `HTMLAnchorElement`'s `href` resource attribute. | +| `target` | `target` | `string` | `''` | Sets the underlying `HTMLAnchorElement`'s `target` attribute when `href` is set. | +| `keepOpen` | `keep-open` | `boolean` | `false` | Keeps the menu open if clicked or keyboard selected. | +| `selected` | `selected` | `boolean` | `false` | Sets the item in the selected visual state when a submenu is opened. | +| `typeaheadText` | | `string` | `undefined` | | @@ -585,9 +590,9 @@ Property | Attribute | Type | Default | Description -Event | Description ---- | --- -`close-menu` | +| Event | Type | [Bubbles](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/composed) | Description | +| --- | --- | --- | --- | --- | +| `close-menu` | `CustomEvent<{initiator: SelectOption, reason: Reason, itemPath: SelectOption[]}>` | Yes | Yes | Closes the encapsulating menu on closable interaction. | @@ -597,15 +602,15 @@ Event | Description -Property | Attribute | Type | Default | Description ---- | --- | --- | --- | --- -`anchorCorner` | `anchor-corner` | `string` | `Corner.START_END` | The anchorCorner to set on the submenu. -`menuCorner` | `menu-corner` | `string` | `Corner.START_START` | The menuCorner to set on the submenu. -`hoverOpenDelay` | `hover-open-delay` | `number` | `400` | The delay between mouseenter and submenu opening. -`hoverCloseDelay` | `hover-close-delay` | `number` | `400` | The delay between ponterleave and the submenu closing. -`isSubMenu` | `md-sub-menu` | `boolean` | `true` | READONLY: self-identifies as a menu item and sets its identifying attribute -`item` | | `MenuItem` | `undefined` | -`menu` | | `Menu` | `undefined` | +| Property | Attribute | Type | Default | Description | +| --- | --- | --- | --- | --- | +| `anchorCorner` | `anchor-corner` | `string` | `Corner.START_END` | The anchorCorner to set on the submenu. | +| `menuCorner` | `menu-corner` | `string` | `Corner.START_START` | The menuCorner to set on the submenu. | +| `hoverOpenDelay` | `hover-open-delay` | `number` | `400` | The delay between mouseenter and submenu opening. | +| `hoverCloseDelay` | `hover-close-delay` | `number` | `400` | The delay between ponterleave and the submenu closing. | +| `isSubMenu` | `md-sub-menu` | `boolean` | `true` | READONLY: self-identifies as a menu item and sets its identifying attribute | +| `item` | | `MenuItem` | `undefined` | | +| `menu` | | `Menu` | `undefined` | | @@ -613,10 +618,10 @@ Property | Attribute | Type | Default | Description -Method | Parameters | Returns | Description ---- | --- | --- | --- -`show` | _None_ | `Promise` | Shows the submenu. -`close` | _None_ | `Promise` | Closes the submenu. +| Method | Parameters | Returns | Description | +| --- | --- | --- | --- | +| `show` | _None_ | `Promise` | Shows the submenu. | +| `close` | _None_ | `Promise` | Closes the submenu. | @@ -624,12 +629,12 @@ Method | Parameters | Returns | Description -Event | Description ---- | --- -`deactivate-items` | Requests the parent menu to deselect other items when a submenu opens -`request-activation` | Requests the parent to make the slotted item focusable and focus the item -`deactivate-typeahead` | Requests the parent menu to deactivate the typeahead functionality when a submenu opens -`activate-typeahead` | Requests the parent menu to activate the typeahead functionality when a submenu closes +| Event | Type | [Bubbles](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/composed) | Description | +| --- | --- | --- | --- | --- | +| `deactivate-items` | `Event` | Yes | Yes | Requests the parent menu to deselect other items when a submenu opens. | +| `request-activation` | `Event` | Yes | Yes | Requests the parent to make the slotted item focusable and focus the item. | +| `deactivate-typeahead` | `Event` | Yes | Yes | Requests the parent menu to deactivate the typeahead functionality when a submenu opens. | +| `activate-typeahead` | `Event` | Yes | Yes | Requests the parent menu to activate the typeahead functionality when a submenu closes. | diff --git a/docs/components/progress.md b/docs/components/progress.md index 8e43c3dcc0..5577090247 100644 --- a/docs/components/progress.md +++ b/docs/components/progress.md @@ -386,13 +386,13 @@ Token | Default value -Property | Attribute | Type | Default | Description ---- | --- | --- | --- | --- -`buffer` | `buffer` | `number` | `1` | Buffer amount to display, a fraction between 0 and `max`. -`value` | `value` | `number` | `0` | Progress to display, a fraction between 0 and `max`. -`max` | `max` | `number` | `1` | Maximum progress to display, defaults to 1. -`indeterminate` | `indeterminate` | `boolean` | `false` | Whether or not to display indeterminate progress, which gives no indication to how long an activity will take. -`fourColor` | `four-color` | `boolean` | `false` | Whether or not to render indeterminate mode using 4 colors instead of one. +| Property | Attribute | Type | Default | Description | +| --- | --- | --- | --- | --- | +| `buffer` | `buffer` | `number` | `0` | Buffer amount to display, a fraction between 0 and `max`. If the value is 0 or negative, the buffer is not displayed. | +| `value` | `value` | `number` | `0` | Progress to display, a fraction between 0 and `max`. | +| `max` | `max` | `number` | `1` | Maximum progress to display, defaults to 1. | +| `indeterminate` | `indeterminate` | `boolean` | `false` | Whether or not to display indeterminate progress, which gives no indication to how long an activity will take. | +| `fourColor` | `four-color` | `boolean` | `false` | Whether or not to render indeterminate mode using 4 colors instead of one. | @@ -402,12 +402,12 @@ Property | Attribute | Type | Default | Description -Property | Attribute | Type | Default | Description ---- | --- | --- | --- | --- -`value` | `value` | `number` | `0` | Progress to display, a fraction between 0 and `max`. -`max` | `max` | `number` | `1` | Maximum progress to display, defaults to 1. -`indeterminate` | `indeterminate` | `boolean` | `false` | Whether or not to display indeterminate progress, which gives no indication to how long an activity will take. -`fourColor` | `four-color` | `boolean` | `false` | Whether or not to render indeterminate mode using 4 colors instead of one. +| Property | Attribute | Type | Default | Description | +| --- | --- | --- | --- | --- | +| `value` | `value` | `number` | `0` | Progress to display, a fraction between 0 and `max`. | +| `max` | `max` | `number` | `1` | Maximum progress to display, defaults to 1. | +| `indeterminate` | `indeterminate` | `boolean` | `false` | Whether or not to display indeterminate progress, which gives no indication to how long an activity will take. | +| `fourColor` | `four-color` | `boolean` | `false` | Whether or not to render indeterminate mode using 4 colors instead of one. | diff --git a/docs/components/radio.md b/docs/components/radio.md index 01db253334..db1ad3039d 100644 --- a/docs/components/radio.md +++ b/docs/components/radio.md @@ -175,14 +175,24 @@ Token | Default value -Property | Attribute | Type | Default | Description ---- | --- | --- | --- | --- -`disabled` | `disabled` | `boolean` | `false` | Whether or not the radio is disabled. -`value` | `value` | `string` | `'on'` | The element value to use in form submission when checked. -`checked` | `checked` | `boolean` | `undefined` | -`name` | | `string` | `undefined` | -`form` | | `HTMLFormElement` | `undefined` | -`labels` | | `NodeList` | `undefined` | +| Property | Attribute | Type | Default | Description | +| --- | --- | --- | --- | --- | +| `required` | `required` | `boolean` | `false` | Whether or not the radio is required. If any radio is required in a group, all radios are implicitly required. | +| `value` | `value` | `string` | `'on'` | The element value to use in form submission when checked. | +| `checked` | `checked` | `boolean` | `undefined` | | +| `disabled` | | `boolean` | `undefined` | | +| `name` | | `string` | `undefined` | | + + + +#### Methods + + + +| Method | Parameters | Returns | Description | +| --- | --- | --- | --- | +| `formResetCallback` | _None_ | `void` | | +| `formStateRestoreCallback` | `state` | `void` | | @@ -190,10 +200,10 @@ Property | Attribute | Type | Default | Description -Event | Description ---- | --- -`input` | Dispatched when the value changes from user interaction. -`change` | Dispatched when the value changes from user interaction. +| Event | Type | [Bubbles](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/composed) | Description | +| --- | --- | --- | --- | --- | +| `input` | `InputEvent` | Yes | No | Dispatched when the value changes from user interaction. | +| `change` | `Event` | Yes | Yes | Dispatched when the value changes from user interaction. | diff --git a/docs/components/ripple.md b/docs/components/ripple.md index 01f1196e54..70dc756203 100644 --- a/docs/components/ripple.md +++ b/docs/components/ripple.md @@ -230,11 +230,11 @@ Token | Default value -Property | Attribute | Type | Default | Description ---- | --- | --- | --- | --- -`disabled` | `disabled` | `boolean` | `false` | Disables the ripple. -`htmlFor` | | `string` | `undefined` | -`control` | | `HTMLElement` | `undefined` | +| Property | Attribute | Type | Default | Description | +| --- | --- | --- | --- | --- | +| `disabled` | `disabled` | `boolean` | `false` | Disables the ripple. | +| `htmlFor` | | `string` | `undefined` | | +| `control` | | `HTMLElement` | `undefined` | | @@ -242,10 +242,10 @@ Property | Attribute | Type | Default | Description -Method | Parameters | Returns | Description ---- | --- | --- | --- -`attach` | `control` | `void` | -`detach` | _None_ | `void` | +| Method | Parameters | Returns | Description | +| --- | --- | --- | --- | +| `attach` | `control` | `void` | | +| `detach` | _None_ | `void` | | diff --git a/docs/components/select.md b/docs/components/select.md index e6d48b24c9..9c3402d3fc 100644 --- a/docs/components/select.md +++ b/docs/components/select.md @@ -217,29 +217,27 @@ md-outlined-select::part(menu) { -Property | Attribute | Type | Default | Description ---- | --- | --- | --- | --- -`quick` | `quick` | `boolean` | `false` | Opens the menu synchronously with no animation. -`required` | `required` | `boolean` | `false` | Whether or not the select is required. -`disabled` | `disabled` | `boolean` | `false` | Disables the select. -`errorText` | `error-text` | `string` | `''` | The error message that replaces supporting text when `error` is true. If `errorText` is an empty string, then the supporting text will continue to show.
This error message overrides the error message displayed by `reportValidity()`. -`label` | `label` | `string` | `''` | The floating label for the field. -`supportingText` | `supporting-text` | `string` | `''` | Conveys additional information below the select, such as how it should be used. -`error` | `error` | `boolean` | `false` | Gets or sets whether or not the select is in a visually invalid state.
This error state overrides the error state controlled by `reportValidity()`. -`menuPositioning` | `menu-positioning` | `string` | `'absolute'` | Whether or not the underlying md-menu should be position: fixed to display in a top-level manner, or position: absolute.
position:fixed is useful for cases where select is inside of another element with stacking context and hidden overflows such as `md-dialog`. -`typeaheadDelay` | `typeahead-delay` | `number` | `DEFAULT_TYPEAHEAD_BUFFER_TIME` | The max time between the keystrokes of the typeahead select / menu behavior before it clears the typeahead buffer. -`hasLeadingIcon` | `has-leading-icon` | `boolean` | `false` | Whether or not the text field has a leading icon. Used for SSR. -`displayText` | `display-text` | `string` | `''` | Text to display in the field. Only set for SSR. -`value` | `value` | `string` | `undefined` | -`selectedIndex` | `selected-index` | `number` | `undefined` | -`options` | | `SelectOption[]` | `undefined` | -`selectedOptions` | | `SelectOption[]` | `undefined` | -`name` | | `string` | `undefined` | -`form` | | `HTMLFormElement` | `undefined` | -`labels` | | `NodeList` | `undefined` | -`validity` | | `ValidityState` | `undefined` | -`validationMessage` | | `string` | `undefined` | -`willValidate` | | `boolean` | `undefined` | +| Property | Attribute | Type | Default | Description | +| --- | --- | --- | --- | --- | +| `quick` | `quick` | `boolean` | `false` | Opens the menu synchronously with no animation. | +| `required` | `required` | `boolean` | `false` | Whether or not the select is required. | +| `errorText` | `error-text` | `string` | `''` | The error message that replaces supporting text when `error` is true. If `errorText` is an empty string, then the supporting text will continue to show.
This error message overrides the error message displayed by `reportValidity()`. | +| `label` | `label` | `string` | `''` | The floating label for the field. | +| `noAsterisk` | `no-asterisk` | `boolean` | `false` | Disables the asterisk on the floating label, when the select is required. | +| `supportingText` | `supporting-text` | `string` | `''` | Conveys additional information below the select, such as how it should be used. | +| `error` | `error` | `boolean` | `false` | Gets or sets whether or not the select is in a visually invalid state.
This error state overrides the error state controlled by `reportValidity()`. | +| `menuPositioning` | `menu-positioning` | `string` | `'popover'` | Whether or not the underlying md-menu should be position: fixed to display in a top-level manner, or position: absolute.
position:fixed is useful for cases where select is inside of another element with stacking context and hidden overflows such as `md-dialog`. | +| `clampMenuWidth` | `clamp-menu-width` | `boolean` | `false` | Clamps the menu-width to the width of the select. | +| `typeaheadDelay` | `typeahead-delay` | `number` | `DEFAULT_TYPEAHEAD_BUFFER_TIME` | The max time between the keystrokes of the typeahead select / menu behavior before it clears the typeahead buffer. | +| `hasLeadingIcon` | `has-leading-icon` | `boolean` | `false` | Whether or not the text field has a leading icon. Used for SSR. | +| `displayText` | `display-text` | `string` | `''` | Text to display in the field. Only set for SSR. | +| `menuAlign` | `menu-align` | `string` | `'start'` | Whether the menu should be aligned to the start or the end of the select's textbox. | +| `value` | `value` | `string` | `undefined` | | +| `selectedIndex` | `selected-index` | `number` | `undefined` | | +| `disabled` | | `boolean` | `undefined` | | +| `name` | | `string` | `undefined` | | +| `options` | | `SelectOption[]` | `undefined` | | +| `selectedOptions` | | `SelectOption[]` | `undefined` | | @@ -247,15 +245,15 @@ Property | Attribute | Type | Default | Description -Method | Parameters | Returns | Description ---- | --- | --- | --- -`select` | `value` | `void` | Selects an option given the value of the option, and updates MdSelect's value. -`selectIndex` | `index` | `void` | Selects an option given the index of the option, and updates MdSelect's value. -`reset` | _None_ | `void` | Reset the select to its default value. -`checkValidity` | _None_ | `boolean` | Checks the select's native validation and returns whether or not the element is valid.
If invalid, this method will dispatch the `invalid` event.
https://developer.mozilla.org/en-US/docs/Web/API/HTMLSelectElement/checkValidity -`reportValidity` | _None_ | `boolean` | Checks the select's native validation and returns whether or not the element is valid.
If invalid, this method will dispatch the `invalid` event.
This method will display or clear an error text message equal to the select's `validationMessage`, unless the invalid event is canceled.
Use `setCustomValidity()` to customize the `validationMessage`.
This method can also be used to re-announce error messages to screen readers. -`setCustomValidity` | `error` | `void` | Sets the select's native validation error message. This is used to customize `validationMessage`.
When the error is not an empty string, the select is considered invalid and `validity.customError` will be true.
https://developer.mozilla.org/en-US/docs/Web/API/HTMLSelectElement/setCustomValidity -`getUpdateComplete` | _None_ | `Promise` | +| Method | Parameters | Returns | Description | +| --- | --- | --- | --- | +| `select` | `value` | `void` | Selects an option given the value of the option, and updates MdSelect's value. | +| `selectIndex` | `index` | `void` | Selects an option given the index of the option, and updates MdSelect's value. | +| `reset` | _None_ | `void` | Reset the select to its default value. | +| `getUpdateComplete` | _None_ | `Promise` | | +| `formResetCallback` | _None_ | `void` | | +| `formStateRestoreCallback` | `state` | `void` | | +| `click` | _None_ | `void` | | @@ -263,14 +261,14 @@ Method | Parameters | Returns | Description -Event | Description ---- | --- -`input` | Fired when a selection is made by the user via mouse or keyboard interaction. -`change` | Fired when a selection is made by the user via mouse or keyboard interaction. -`opening` | Fired when the select's menu is about to open. -`opened` | Fired when the select's menu has finished animations and opened. -`closing` | Fired when the select's menu is about to close. -`closed` | Fired when the select's menu has finished animations and closed. +| Event | Type | [Bubbles](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/composed) | Description | +| --- | --- | --- | --- | --- | +| `change` | `Event` | Yes | No | The native `change` event on [``](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event) | +| `input` | `InputEvent` | Yes | Yes | The native `input` event on [``](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event) | +| `opening` | `Event` | No | No | Fired when the select's menu is about to open. | +| `opened` | `Event` | No | No | Fired when the select's menu has finished animations and opened. | +| `closing` | `Event` | No | No | Fired when the select's menu is about to close. | +| `closed` | `Event` | No | No | Fired when the select's menu has finished animations and closed. | @@ -280,29 +278,27 @@ Event | Description -Property | Attribute | Type | Default | Description ---- | --- | --- | --- | --- -`quick` | `quick` | `boolean` | `false` | Opens the menu synchronously with no animation. -`required` | `required` | `boolean` | `false` | Whether or not the select is required. -`disabled` | `disabled` | `boolean` | `false` | Disables the select. -`errorText` | `error-text` | `string` | `''` | The error message that replaces supporting text when `error` is true. If `errorText` is an empty string, then the supporting text will continue to show.
This error message overrides the error message displayed by `reportValidity()`. -`label` | `label` | `string` | `''` | The floating label for the field. -`supportingText` | `supporting-text` | `string` | `''` | Conveys additional information below the select, such as how it should be used. -`error` | `error` | `boolean` | `false` | Gets or sets whether or not the select is in a visually invalid state.
This error state overrides the error state controlled by `reportValidity()`. -`menuPositioning` | `menu-positioning` | `string` | `'absolute'` | Whether or not the underlying md-menu should be position: fixed to display in a top-level manner, or position: absolute.
position:fixed is useful for cases where select is inside of another element with stacking context and hidden overflows such as `md-dialog`. -`typeaheadDelay` | `typeahead-delay` | `number` | `DEFAULT_TYPEAHEAD_BUFFER_TIME` | The max time between the keystrokes of the typeahead select / menu behavior before it clears the typeahead buffer. -`hasLeadingIcon` | `has-leading-icon` | `boolean` | `false` | Whether or not the text field has a leading icon. Used for SSR. -`displayText` | `display-text` | `string` | `''` | Text to display in the field. Only set for SSR. -`value` | `value` | `string` | `undefined` | -`selectedIndex` | `selected-index` | `number` | `undefined` | -`options` | | `SelectOption[]` | `undefined` | -`selectedOptions` | | `SelectOption[]` | `undefined` | -`name` | | `string` | `undefined` | -`form` | | `HTMLFormElement` | `undefined` | -`labels` | | `NodeList` | `undefined` | -`validity` | | `ValidityState` | `undefined` | -`validationMessage` | | `string` | `undefined` | -`willValidate` | | `boolean` | `undefined` | +| Property | Attribute | Type | Default | Description | +| --- | --- | --- | --- | --- | +| `quick` | `quick` | `boolean` | `false` | Opens the menu synchronously with no animation. | +| `required` | `required` | `boolean` | `false` | Whether or not the select is required. | +| `errorText` | `error-text` | `string` | `''` | The error message that replaces supporting text when `error` is true. If `errorText` is an empty string, then the supporting text will continue to show.
This error message overrides the error message displayed by `reportValidity()`. | +| `label` | `label` | `string` | `''` | The floating label for the field. | +| `noAsterisk` | `no-asterisk` | `boolean` | `false` | Disables the asterisk on the floating label, when the select is required. | +| `supportingText` | `supporting-text` | `string` | `''` | Conveys additional information below the select, such as how it should be used. | +| `error` | `error` | `boolean` | `false` | Gets or sets whether or not the select is in a visually invalid state.
This error state overrides the error state controlled by `reportValidity()`. | +| `menuPositioning` | `menu-positioning` | `string` | `'popover'` | Whether or not the underlying md-menu should be position: fixed to display in a top-level manner, or position: absolute.
position:fixed is useful for cases where select is inside of another element with stacking context and hidden overflows such as `md-dialog`. | +| `clampMenuWidth` | `clamp-menu-width` | `boolean` | `false` | Clamps the menu-width to the width of the select. | +| `typeaheadDelay` | `typeahead-delay` | `number` | `DEFAULT_TYPEAHEAD_BUFFER_TIME` | The max time between the keystrokes of the typeahead select / menu behavior before it clears the typeahead buffer. | +| `hasLeadingIcon` | `has-leading-icon` | `boolean` | `false` | Whether or not the text field has a leading icon. Used for SSR. | +| `displayText` | `display-text` | `string` | `''` | Text to display in the field. Only set for SSR. | +| `menuAlign` | `menu-align` | `string` | `'start'` | Whether the menu should be aligned to the start or the end of the select's textbox. | +| `value` | `value` | `string` | `undefined` | | +| `selectedIndex` | `selected-index` | `number` | `undefined` | | +| `disabled` | | `boolean` | `undefined` | | +| `name` | | `string` | `undefined` | | +| `options` | | `SelectOption[]` | `undefined` | | +| `selectedOptions` | | `SelectOption[]` | `undefined` | | @@ -310,15 +306,15 @@ Property | Attribute | Type | Default | Description -Method | Parameters | Returns | Description ---- | --- | --- | --- -`select` | `value` | `void` | Selects an option given the value of the option, and updates MdSelect's value. -`selectIndex` | `index` | `void` | Selects an option given the index of the option, and updates MdSelect's value. -`reset` | _None_ | `void` | Reset the select to its default value. -`checkValidity` | _None_ | `boolean` | Checks the select's native validation and returns whether or not the element is valid.
If invalid, this method will dispatch the `invalid` event.
https://developer.mozilla.org/en-US/docs/Web/API/HTMLSelectElement/checkValidity -`reportValidity` | _None_ | `boolean` | Checks the select's native validation and returns whether or not the element is valid.
If invalid, this method will dispatch the `invalid` event.
This method will display or clear an error text message equal to the select's `validationMessage`, unless the invalid event is canceled.
Use `setCustomValidity()` to customize the `validationMessage`.
This method can also be used to re-announce error messages to screen readers. -`setCustomValidity` | `error` | `void` | Sets the select's native validation error message. This is used to customize `validationMessage`.
When the error is not an empty string, the select is considered invalid and `validity.customError` will be true.
https://developer.mozilla.org/en-US/docs/Web/API/HTMLSelectElement/setCustomValidity -`getUpdateComplete` | _None_ | `Promise` | +| Method | Parameters | Returns | Description | +| --- | --- | --- | --- | +| `select` | `value` | `void` | Selects an option given the value of the option, and updates MdSelect's value. | +| `selectIndex` | `index` | `void` | Selects an option given the index of the option, and updates MdSelect's value. | +| `reset` | _None_ | `void` | Reset the select to its default value. | +| `getUpdateComplete` | _None_ | `Promise` | | +| `formResetCallback` | _None_ | `void` | | +| `formStateRestoreCallback` | `state` | `void` | | +| `click` | _None_ | `void` | | @@ -326,14 +322,14 @@ Method | Parameters | Returns | Description -Event | Description ---- | --- -`input` | Fired when a selection is made by the user via mouse or keyboard interaction. -`change` | Fired when a selection is made by the user via mouse or keyboard interaction. -`opening` | Fired when the select's menu is about to open. -`opened` | Fired when the select's menu has finished animations and opened. -`closing` | Fired when the select's menu is about to close. -`closed` | Fired when the select's menu has finished animations and closed. +| Event | Type | [Bubbles](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/composed) | Description | +| --- | --- | --- | --- | --- | +| `change` | `Event` | Yes | No | The native `change` event on [``](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event) | +| `input` | `InputEvent` | Yes | Yes | The native `input` event on [``](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event) | +| `opening` | `Event` | No | No | Fired when the select's menu is about to open. | +| `opened` | `Event` | No | No | Fired when the select's menu has finished animations and opened. | +| `closing` | `Event` | No | No | Fired when the select's menu is about to close. | +| `closed` | `Event` | No | No | Fired when the select's menu has finished animations and closed. | @@ -343,14 +339,14 @@ Event | Description -Property | Attribute | Type | Default | Description ---- | --- | --- | --- | --- -`disabled` | `disabled` | `boolean` | `false` | Disables the item and makes it non-selectable and non-interactive. -`selected` | `selected` | `boolean` | `false` | Sets the item in the selected visual state when a submenu is opened. -`value` | `value` | `string` | `''` | Form value of the option. -`type` | | `string` | `'option' as const` | -`typeaheadText` | | `string` | `undefined` | -`displayText` | | `string` | `undefined` | +| Property | Attribute | Type | Default | Description | +| --- | --- | --- | --- | --- | +| `disabled` | `disabled` | `boolean` | `false` | Disables the item and makes it non-selectable and non-interactive. | +| `selected` | `selected` | `boolean` | `false` | Sets the item in the selected visual state when a submenu is opened. | +| `value` | `value` | `string` | `''` | Form value of the option. | +| `type` | | `string` | `'option' as const` | | +| `typeaheadText` | | `string` | `undefined` | | +| `displayText` | | `string` | `undefined` | | @@ -358,11 +354,11 @@ Property | Attribute | Type | Default | Description -Event | Description ---- | --- -`close-menu` | Closes the encapsulating menu on -`request-selection` | Requests the parent md-select to select this element (and deselect others if single-selection) when `selected` changed to `true`. -`request-deselection` | Requests the parent md-select to deselect this element when `selected` changed to `false`. +| Event | Type | [Bubbles](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/composed) | Description | +| --- | --- | --- | --- | --- | +| `close-menu` | `CustomEvent<{initiator: SelectOption, reason: Reason, itemPath: SelectOption[]}>` | Yes | Yes | Closes the encapsulating menu on closable interaction. | +| `request-selection` | `Event` | Yes | Yes | Requests the parent md-select to select this element (and deselect others if single-selection) when `selected` changed to `true`. | +| `request-deselection` | `Event` | Yes | Yes | Requests the parent md-select to deselect this element when `selected` changed to `false`. | diff --git a/docs/components/slider.md b/docs/components/slider.md index a6bc233974..4f34d2e1ab 100644 --- a/docs/components/slider.md +++ b/docs/components/slider.md @@ -167,30 +167,50 @@ Token | Default value -Property | Attribute | Type | Default | Description ---- | --- | --- | --- | --- -`disabled` | `disabled` | `boolean` | `false` | Whether or not the slider is disabled. -`min` | `min` | `number` | `0` | The slider minimum value -`max` | `max` | `number` | `100` | The slider maximum value -`value` | `value` | `number` | `undefined` | The slider value displayed when range is false. -`valueStart` | `value-start` | `number` | `undefined` | The slider start value displayed when range is true. -`valueEnd` | `value-end` | `number` | `undefined` | The slider end value displayed when range is true. -`valueLabel` | `value-label` | `string` | `''` | An optional label for the slider's value displayed when range is false; if not set, the label is the value itself. -`valueLabelStart` | `value-label-start` | `string` | `''` | An optional label for the slider's start value displayed when range is true; if not set, the label is the valueStart itself. -`valueLabelEnd` | `value-label-end` | `string` | `''` | An optional label for the slider's end value displayed when range is true; if not set, the label is the valueEnd itself. -`ariaLabelStart` | `aria-label-start` | `string` | `''` | Aria label for the slider's start handle displayed when range is true. -`ariaValueTextStart` | `aria-valuetext-start` | `string` | `''` | Aria value text for the slider's start value displayed when range is true. -`ariaLabelEnd` | `aria-label-end` | `string` | `''` | Aria label for the slider's end handle displayed when range is true. -`ariaValueTextEnd` | `aria-valuetext-end` | `string` | `''` | Aria value text for the slider's end value displayed when range is true. -`step` | `step` | `number` | `1` | The step between values. -`ticks` | `ticks` | `boolean` | `false` | Whether or not to show tick marks. -`labeled` | `labeled` | `boolean` | `false` | Whether or not to show a value label when activated. -`range` | `range` | `boolean` | `false` | Whether or not to show a value range. When false, the slider displays a slideable handle for the value property; when true, it displays slideable handles for the valueStart and valueEnd properties. -`name` | | `string` | `undefined` | -`nameStart` | | `string` | `undefined` | -`nameEnd` | | `string` | `undefined` | -`form` | | `HTMLFormElement` | `undefined` | -`labels` | | `NodeList` | `undefined` | +| Property | Attribute | Type | Default | Description | +| --- | --- | --- | --- | --- | +| `min` | `min` | `number` | `0` | The slider minimum value | +| `max` | `max` | `number` | `100` | The slider maximum value | +| `value` | `value` | `number` | `undefined` | The slider value displayed when range is false. | +| `valueStart` | `value-start` | `number` | `undefined` | The slider start value displayed when range is true. | +| `valueEnd` | `value-end` | `number` | `undefined` | The slider end value displayed when range is true. | +| `valueLabel` | `value-label` | `string` | `''` | An optional label for the slider's value displayed when range is false; if not set, the label is the value itself. | +| `valueLabelStart` | `value-label-start` | `string` | `''` | An optional label for the slider's start value displayed when range is true; if not set, the label is the valueStart itself. | +| `valueLabelEnd` | `value-label-end` | `string` | `''` | An optional label for the slider's end value displayed when range is true; if not set, the label is the valueEnd itself. | +| `ariaLabelStart` | `aria-label-start` | `string` | `''` | Aria label for the slider's start handle displayed when range is true. | +| `ariaValueTextStart` | `aria-valuetext-start` | `string` | `''` | Aria value text for the slider's start value displayed when range is true. | +| `ariaLabelEnd` | `aria-label-end` | `string` | `''` | Aria label for the slider's end handle displayed when range is true. | +| `ariaValueTextEnd` | `aria-valuetext-end` | `string` | `''` | Aria value text for the slider's end value displayed when range is true. | +| `step` | `step` | `number` | `1` | The step between values. | +| `ticks` | `ticks` | `boolean` | `false` | Whether or not to show tick marks. | +| `labeled` | `labeled` | `boolean` | `false` | Whether or not to show a value label when activated. | +| `range` | `range` | `boolean` | `false` | Whether or not to show a value range. When false, the slider displays a slideable handle for the value property; when true, it displays slideable handles for the valueStart and valueEnd properties. | +| `disabled` | | `boolean` | `undefined` | | +| `name` | | `string` | `undefined` | | +| `nameStart` | | `string` | `undefined` | | +| `nameEnd` | | `string` | `undefined` | | + + + +#### Methods + + + +| Method | Parameters | Returns | Description | +| --- | --- | --- | --- | +| `formResetCallback` | _None_ | `void` | | +| `formStateRestoreCallback` | `state` | `void` | | + + + +#### Events + + + +| Event | Type | [Bubbles](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/composed) | Description | +| --- | --- | --- | --- | --- | +| `change` | `Event` | Yes | No | The native `change` event on [``](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event) | +| `input` | `InputEvent` | Yes | Yes | The native `input` event on [``](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event) | diff --git a/docs/components/switch.md b/docs/components/switch.md index 4bdc9e2c61..9e510273c0 100644 --- a/docs/components/switch.md +++ b/docs/components/switch.md @@ -183,20 +183,15 @@ Token | Default value -Property | Attribute | Type | Default | Description ---- | --- | --- | --- | --- -`disabled` | `disabled` | `boolean` | `false` | Disables the switch and makes it non-interactive. -`selected` | `selected` | `boolean` | `false` | Puts the switch in the selected state and sets the form submission value to the `value` property. -`icons` | `icons` | `boolean` | `false` | Shows both the selected and deselected icons. -`showOnlySelectedIcon` | `show-only-selected-icon` | `boolean` | `false` | Shows only the selected icon, and not the deselected icon. If `true`, overrides the behavior of the `icons` property. -`required` | `required` | `boolean` | `false` | When true, require the switch to be selected when participating in form submission.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#validation -`value` | `value` | `string` | `'on'` | The value associated with this switch on form submission. `null` is submitted when `selected` is `false`. -`name` | | `string` | `undefined` | -`form` | | `HTMLFormElement` | `undefined` | -`labels` | | `NodeList` | `undefined` | -`validity` | | `ValidityState` | `undefined` | -`validationMessage` | | `string` | `undefined` | -`willValidate` | | `boolean` | `undefined` | +| Property | Attribute | Type | Default | Description | +| --- | --- | --- | --- | --- | +| `selected` | `selected` | `boolean` | `false` | Puts the switch in the selected state and sets the form submission value to the `value` property. | +| `icons` | `icons` | `boolean` | `false` | Shows both the selected and deselected icons. | +| `showOnlySelectedIcon` | `show-only-selected-icon` | `boolean` | `false` | Shows only the selected icon, and not the deselected icon. If `true`, overrides the behavior of the `icons` property. | +| `required` | `required` | `boolean` | `false` | When true, require the switch to be selected when participating in form submission.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#validation | +| `value` | `value` | `string` | `'on'` | The value associated with this switch on form submission. `null` is submitted when `selected` is `false`. | +| `disabled` | | `boolean` | `undefined` | | +| `name` | | `string` | `undefined` | | @@ -204,11 +199,10 @@ Property | Attribute | Type | Default | Description -Method | Parameters | Returns | Description ---- | --- | --- | --- -`checkValidity` | _None_ | `boolean` | Checks the switch's native validation and returns whether or not the element is valid.
If invalid, this method will dispatch the `invalid` event.
https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/checkValidity -`reportValidity` | _None_ | `boolean` | Checks the switch's native validation and returns whether or not the element is valid.
If invalid, this method will dispatch the `invalid` event.
The `validationMessage` is reported to the user by the browser. Use `setCustomValidity()` to customize the `validationMessage`.
https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/reportValidity -`setCustomValidity` | `error` | `void` | Sets the switch's native validation error message. This is used to customize `validationMessage`.
When the error is not an empty string, the switch is considered invalid and `validity.customError` will be true.
https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setCustomValidity +| Method | Parameters | Returns | Description | +| --- | --- | --- | --- | +| `formResetCallback` | _None_ | `void` | | +| `formStateRestoreCallback` | `state` | `void` | | @@ -216,10 +210,10 @@ Method | Parameters | Returns | Description -Event | Description ---- | --- -`input` | Fired whenever `selected` changes due to user interaction (bubbles and composed). -`change` | Fired whenever `selected` changes due to user interaction (bubbles). +| Event | Type | [Bubbles](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/composed) | Description | +| --- | --- | --- | --- | --- | +| `input` | `InputEvent` | No | No | Fired whenever `selected` changes due to user interaction (bubbles and composed). | +| `change` | `Event` | No | No | Fired whenever `selected` changes due to user interaction (bubbles). | diff --git a/docs/components/tabs.md b/docs/components/tabs.md index 2c509225b1..11497d80b1 100644 --- a/docs/components/tabs.md +++ b/docs/components/tabs.md @@ -377,12 +377,12 @@ Token | Default value -Property | Attribute | Type | Default | Description ---- | --- | --- | --- | --- -`autoActivate` | `auto-activate` | `boolean` | `false` | Whether or not to automatically select a tab when it is focused. -`tabs` | | `Tab[]` | `undefined` | The tabs of this tab bar. -`activeTab` | | `Tab` | `undefined` | -`activeTabIndex` | | `number` | `undefined` | +| Property | Attribute | Type | Default | Description | +| --- | --- | --- | --- | --- | +| `autoActivate` | `auto-activate` | `boolean` | `false` | Whether or not to automatically select a tab when it is focused. | +| `activeTabIndex` | `active-tab-index` | `number` | `undefined` | | +| `tabs` | | `Tab[]` | `undefined` | The tabs of this tab bar. | +| `activeTab` | | `Tab` | `undefined` | | @@ -390,9 +390,9 @@ Property | Attribute | Type | Default | Description -Method | Parameters | Returns | Description ---- | --- | --- | --- -`scrollToTab` | `tabToScrollTo` | `Promise` | Scrolls the toolbar, if overflowing, to the active tab, or the provided tab. +| Method | Parameters | Returns | Description | +| --- | --- | --- | --- | +| `scrollToTab` | `tabToScrollTo` | `Promise` | Scrolls the toolbar, if overflowing, to the active tab, or the provided tab. | @@ -400,9 +400,9 @@ Method | Parameters | Returns | Description -Event | Description ---- | --- -`change` | Fired when the selected tab changes. The target's `activeTabIndex` or `activeTab` provide information about the selection change. The change event is fired when a user interaction like a space/enter key or click cause a selection change. The tab selection based on these actions can be cancelled by calling preventDefault on the triggering `keydown` or `click` event. +| Event | Type | [Bubbles](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/composed) | Description | +| --- | --- | --- | --- | --- | +| `change` | `Event` | Yes | No | Fired when the selected tab changes. The target's `activeTabIndex` or `activeTab` provide information about the selection change. The change event is fired when a user interaction like a space/enter key or click cause a selection change. The tab selection based on these actions can be cancelled by calling preventDefault on the triggering `keydown` or `click` event. | @@ -412,14 +412,14 @@ Event | Description -Property | Attribute | Type | Default | Description ---- | --- | --- | --- | --- -`inlineIcon` | `inline-icon` | `boolean` | `false` | Whether or not the icon renders inline with label or stacked vertically. -`isTab` | `md-tab` | `boolean` | `true` | The attribute `md-tab` indicates that the element is a tab for the parent element, ``. Make sure if you're implementing your own `md-tab` component that you have an `md-tab` attribute set. -`active` | `active` | `boolean` | `false` | Whether or not the tab is selected. -`hasIcon` | `has-icon` | `boolean` | `false` | In SSR, set this to true when an icon is present. -`iconOnly` | `icon-only` | `boolean` | `false` | In SSR, set this to true when there is no label and only an icon. -`selected` | `selected` | `boolean` | `undefined` | +| Property | Attribute | Type | Default | Description | +| --- | --- | --- | --- | --- | +| `inlineIcon` | `inline-icon` | `boolean` | `false` | Whether or not the icon renders inline with label or stacked vertically. | +| `isTab` | `md-tab` | `boolean` | `true` | The attribute `md-tab` indicates that the element is a tab for the parent element, ``. Make sure if you're implementing your own `md-tab` component that you have an `md-tab` attribute set. | +| `active` | `active` | `boolean` | `false` | Whether or not the tab is selected. | +| `hasIcon` | `has-icon` | `boolean` | `false` | In SSR, set this to true when an icon is present. | +| `iconOnly` | `icon-only` | `boolean` | `false` | In SSR, set this to true when there is no label and only an icon. | +| `selected` | `selected` | `boolean` | `undefined` | | @@ -429,13 +429,13 @@ Property | Attribute | Type | Default | Description -Property | Attribute | Type | Default | Description ---- | --- | --- | --- | --- -`isTab` | `md-tab` | `boolean` | `true` | The attribute `md-tab` indicates that the element is a tab for the parent element, ``. Make sure if you're implementing your own `md-tab` component that you have an `md-tab` attribute set. -`active` | `active` | `boolean` | `false` | Whether or not the tab is selected. -`hasIcon` | `has-icon` | `boolean` | `false` | In SSR, set this to true when an icon is present. -`iconOnly` | `icon-only` | `boolean` | `false` | In SSR, set this to true when there is no label and only an icon. -`selected` | `selected` | `boolean` | `undefined` | +| Property | Attribute | Type | Default | Description | +| --- | --- | --- | --- | --- | +| `isTab` | `md-tab` | `boolean` | `true` | The attribute `md-tab` indicates that the element is a tab for the parent element, ``. Make sure if you're implementing your own `md-tab` component that you have an `md-tab` attribute set. | +| `active` | `active` | `boolean` | `false` | Whether or not the tab is selected. | +| `hasIcon` | `has-icon` | `boolean` | `false` | In SSR, set this to true when an icon is present. | +| `iconOnly` | `icon-only` | `boolean` | `false` | In SSR, set this to true when there is no label and only an icon. | +| `selected` | `selected` | `boolean` | `undefined` | | diff --git a/docs/components/text-field.md b/docs/components/text-field.md index 0524711de2..0b2c110635 100644 --- a/docs/components/text-field.md +++ b/docs/components/text-field.md @@ -486,45 +486,42 @@ Token | Default value -Property | Attribute | Type | Default | Description ---- | --- | --- | --- | --- -`disabled` | `disabled` | `boolean` | `false` | -`error` | `error` | `boolean` | `false` | Gets or sets whether or not the text field is in a visually invalid state.
This error state overrides the error state controlled by `reportValidity()`. -`errorText` | `error-text` | `string` | `''` | The error message that replaces supporting text when `error` is true. If `errorText` is an empty string, then the supporting text will continue to show.
This error message overrides the error message displayed by `reportValidity()`. -`label` | `label` | `string` | `''` | -`required` | `required` | `boolean` | `false` | -`value` | `value` | `string` | `''` | The current value of the text field. It is always a string. -`prefixText` | `prefix-text` | `string` | `''` | An optional prefix to display before the input value. -`suffixText` | `suffix-text` | `string` | `''` | An optional suffix to display after the input value. -`hasLeadingIcon` | `has-leading-icon` | `boolean` | `false` | Whether or not the text field has a leading icon. Used for SSR. -`hasTrailingIcon` | `has-trailing-icon` | `boolean` | `false` | Whether or not the text field has a trailing icon. Used for SSR. -`supportingText` | `supporting-text` | `string` | `''` | Conveys additional information below the text field, such as how it should be used. -`textDirection` | `text-direction` | `string` | `''` | Override the input text CSS `direction`. Useful for RTL languages that use LTR notation for fractions. -`rows` | `rows` | `number` | `2` | The number of rows to display for a `type="textarea"` text field. Defaults to 2. -`cols` | `cols` | `number` | `20` | The number of cols to display for a `type="textarea"` text field. Defaults to 20. -`inputMode` | `inputmode` | `string` | `''` | -`max` | `max` | `string` | `''` | Defines the greatest value in the range of permitted values.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#max -`maxLength` | `maxlength` | `number` | `-1` | The maximum number of characters a user can enter into the text field. Set to -1 for none.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#maxlength -`min` | `min` | `string` | `''` | Defines the most negative value in the range of permitted values.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#min -`minLength` | `minlength` | `number` | `-1` | The minimum number of characters a user can enter into the text field. Set to -1 for none.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#minlength -`pattern` | `pattern` | `string` | `''` | A regular expression that the text field's value must match to pass constraint validation.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#pattern -`placeholder` | `placeholder` | `string` | `''` | -`readOnly` | `readonly` | `boolean` | `false` | Indicates whether or not a user should be able to edit the text field's value.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#readonly -`multiple` | `multiple` | `boolean` | `false` | Indicates that input accepts multiple email addresses.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/email#multiple -`step` | `step` | `string` | `''` | Returns or sets the element's step attribute, which works with min and max to limit the increments at which a numeric or date-time value can be set.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#step -`type` | `type` | `string` | `'text'` | The `` type to use, defaults to "text". The type greatly changes how the text field behaves.
Text fields support a limited number of `` types:
- text - textarea - email - number - password - search - tel - url
See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#input_types for more details on each input type. -`autocomplete` | `autocomplete` | `string` | `''` | Describes what, if any, type of autocomplete functionality the input should provide.
https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete -`form` | | `HTMLFormElement` | `undefined` | -`labels` | | `NodeList` | `undefined` | -`name` | | `string` | `undefined` | -`selectionDirection` | | `string` | `undefined` | -`selectionEnd` | | `number` | `undefined` | -`selectionStart` | | `number` | `undefined` | -`validationMessage` | | `string` | `undefined` | -`validity` | | `ValidityState` | `undefined` | -`valueAsNumber` | | `number` | `undefined` | -`valueAsDate` | | `Date` | `undefined` | -`willValidate` | | `boolean` | `undefined` | +| Property | Attribute | Type | Default | Description | +| --- | --- | --- | --- | --- | +| `error` | `error` | `boolean` | `false` | Gets or sets whether or not the text field is in a visually invalid state.
This error state overrides the error state controlled by `reportValidity()`. | +| `errorText` | `error-text` | `string` | `''` | The error message that replaces supporting text when `error` is true. If `errorText` is an empty string, then the supporting text will continue to show.
This error message overrides the error message displayed by `reportValidity()`. | +| `label` | `label` | `string` | `''` | The floating Material label of the textfield component. It informs the user about what information is requested for a text field. It is aligned with the input text, is always visible, and it floats when focused or when text is entered into the textfield. This label also sets accessibilty labels, but the accessible label is overriden by `aria-label`.
Learn more about floating labels from the Material Design guidelines: https://m3.material.io/components/text-fields/guidelines | +| `noAsterisk` | `no-asterisk` | `boolean` | `false` | Disables the asterisk on the floating label, when the text field is required. | +| `required` | `required` | `boolean` | `false` | Indicates that the user must specify a value for the input before the owning form can be submitted and will render an error state when `reportValidity()` is invoked when value is empty. Additionally the floating label will render an asterisk `"*"` when true.
https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/required | +| `value` | `value` | `string` | `''` | The current value of the text field. It is always a string. | +| `prefixText` | `prefix-text` | `string` | `''` | An optional prefix to display before the input value. | +| `suffixText` | `suffix-text` | `string` | `''` | An optional suffix to display after the input value. | +| `hasLeadingIcon` | `has-leading-icon` | `boolean` | `false` | Whether or not the text field has a leading icon. Used for SSR. | +| `hasTrailingIcon` | `has-trailing-icon` | `boolean` | `false` | Whether or not the text field has a trailing icon. Used for SSR. | +| `supportingText` | `supporting-text` | `string` | `''` | Conveys additional information below the text field, such as how it should be used. | +| `textDirection` | `text-direction` | `string` | `''` | Override the input text CSS `direction`. Useful for RTL languages that use LTR notation for fractions. | +| `rows` | `rows` | `number` | `2` | The number of rows to display for a `type="textarea"` text field. Defaults to 2. | +| `cols` | `cols` | `number` | `20` | The number of cols to display for a `type="textarea"` text field. Defaults to 20. | +| `inputMode` | `inputmode` | `string` | `''` | | +| `max` | `max` | `string` | `''` | Defines the greatest value in the range of permitted values.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#max | +| `maxLength` | `maxlength` | `number` | `-1` | The maximum number of characters a user can enter into the text field. Set to -1 for none.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#maxlength | +| `min` | `min` | `string` | `''` | Defines the most negative value in the range of permitted values.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#min | +| `minLength` | `minlength` | `number` | `-1` | The minimum number of characters a user can enter into the text field. Set to -1 for none.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#minlength | +| `noSpinner` | `no-spinner` | `boolean` | `false` | When true, hide the spinner for `type="number"` text fields. | +| `pattern` | `pattern` | `string` | `''` | A regular expression that the text field's value must match to pass constraint validation.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#pattern | +| `placeholder` | `placeholder` | `string` | `''` | Defines the text displayed in the textfield when it has no value. Provides a brief hint to the user as to the expected type of data that should be entered into the control. Unlike `label`, the placeholder is not visible and does not float when the textfield has a value.
https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/placeholder | +| `readOnly` | `readonly` | `boolean` | `false` | Indicates whether or not a user should be able to edit the text field's value.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#readonly | +| `multiple` | `multiple` | `boolean` | `false` | Indicates that input accepts multiple email addresses.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/email#multiple | +| `step` | `step` | `string` | `''` | Returns or sets the element's step attribute, which works with min and max to limit the increments at which a numeric or date-time value can be set.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#step | +| `type` | `type` | `string` | `'text'` | The `` type to use, defaults to "text". The type greatly changes how the text field behaves.
Text fields support a limited number of `` types:
- text - textarea - email - number - password - search - tel - url
See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#input_types for more details on each input type. | +| `autocomplete` | `autocomplete` | `string` | `''` | Describes what, if any, type of autocomplete functionality the input should provide.
https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete | +| `disabled` | | `boolean` | `undefined` | | +| `name` | | `string` | `undefined` | | +| `selectionDirection` | | `string` | `undefined` | | +| `selectionEnd` | | `number` | `undefined` | | +| `selectionStart` | | `number` | `undefined` | | +| `valueAsNumber` | | `number` | `undefined` | | +| `valueAsDate` | | `Date` | `undefined` | | @@ -532,17 +529,28 @@ Property | Attribute | Type | Default | Description -Method | Parameters | Returns | Description ---- | --- | --- | --- -`checkValidity` | _None_ | `boolean` | Checks the text field's native validation and returns whether or not the element is valid.
If invalid, this method will dispatch the `invalid` event.
https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/checkValidity -`reportValidity` | _None_ | `boolean` | Checks the text field's native validation and returns whether or not the element is valid.
If invalid, this method will dispatch the `invalid` event.
This method will display or clear an error text message equal to the text field's `validationMessage`, unless the invalid event is canceled.
Use `setCustomValidity()` to customize the `validationMessage`.
This method can also be used to re-announce error messages to screen readers.
https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/reportValidity -`select` | _None_ | `void` | Selects all the text in the text field.
https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/select -`setCustomValidity` | `error` | `void` | Sets a custom validation error message for the text field. Use this for custom error message.
When the error is not an empty string, the text field is considered invalid and `validity.customError` will be true.
https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setCustomValidity -`setRangeText` | `args` | `void` | -`setSelectionRange` | `start`, `end`, `direction` | `void` | Sets the start and end positions of a selection in the text field.
https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setSelectionRange -`stepDown` | `stepDecrement` | `void` | Decrements the value of a numeric type text field by `step` or `n` `step` number of times.
https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/stepDown -`stepUp` | `stepIncrement` | `void` | Increments the value of a numeric type text field by `step` or `n` `step` number of times.
https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/stepUp -`reset` | _None_ | `void` | Reset the text field to its default value. +| Method | Parameters | Returns | Description | +| --- | --- | --- | --- | +| `select` | _None_ | `void` | Selects all the text in the text field.
https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/select | +| `setRangeText` | `args` | `void` | | +| `setSelectionRange` | `start`, `end`, `direction` | `void` | Sets the start and end positions of a selection in the text field.
https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setSelectionRange | +| `stepDown` | `stepDecrement` | `void` | Decrements the value of a numeric type text field by `step` or `n` `step` number of times.
https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/stepDown | +| `stepUp` | `stepIncrement` | `void` | Increments the value of a numeric type text field by `step` or `n` `step` number of times.
https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/stepUp | +| `reset` | _None_ | `void` | Reset the text field to its default value. | +| `formResetCallback` | _None_ | `void` | | +| `formStateRestoreCallback` | `state` | `void` | | + + + +#### Events + + + +| Event | Type | [Bubbles](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/composed) | Description | +| --- | --- | --- | --- | --- | +| `select` | `Event` | Yes | No | The native `select` event on [``](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/select_event) | +| `change` | `Event` | Yes | No | The native `change` event on [``](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event) | +| `input` | `InputEvent` | Yes | Yes | The native `input` event on [``](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event) | @@ -552,45 +560,42 @@ Method | Parameters | Returns | Description -Property | Attribute | Type | Default | Description ---- | --- | --- | --- | --- -`disabled` | `disabled` | `boolean` | `false` | -`error` | `error` | `boolean` | `false` | Gets or sets whether or not the text field is in a visually invalid state.
This error state overrides the error state controlled by `reportValidity()`. -`errorText` | `error-text` | `string` | `''` | The error message that replaces supporting text when `error` is true. If `errorText` is an empty string, then the supporting text will continue to show.
This error message overrides the error message displayed by `reportValidity()`. -`label` | `label` | `string` | `''` | -`required` | `required` | `boolean` | `false` | -`value` | `value` | `string` | `''` | The current value of the text field. It is always a string. -`prefixText` | `prefix-text` | `string` | `''` | An optional prefix to display before the input value. -`suffixText` | `suffix-text` | `string` | `''` | An optional suffix to display after the input value. -`hasLeadingIcon` | `has-leading-icon` | `boolean` | `false` | Whether or not the text field has a leading icon. Used for SSR. -`hasTrailingIcon` | `has-trailing-icon` | `boolean` | `false` | Whether or not the text field has a trailing icon. Used for SSR. -`supportingText` | `supporting-text` | `string` | `''` | Conveys additional information below the text field, such as how it should be used. -`textDirection` | `text-direction` | `string` | `''` | Override the input text CSS `direction`. Useful for RTL languages that use LTR notation for fractions. -`rows` | `rows` | `number` | `2` | The number of rows to display for a `type="textarea"` text field. Defaults to 2. -`cols` | `cols` | `number` | `20` | The number of cols to display for a `type="textarea"` text field. Defaults to 20. -`inputMode` | `inputmode` | `string` | `''` | -`max` | `max` | `string` | `''` | Defines the greatest value in the range of permitted values.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#max -`maxLength` | `maxlength` | `number` | `-1` | The maximum number of characters a user can enter into the text field. Set to -1 for none.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#maxlength -`min` | `min` | `string` | `''` | Defines the most negative value in the range of permitted values.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#min -`minLength` | `minlength` | `number` | `-1` | The minimum number of characters a user can enter into the text field. Set to -1 for none.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#minlength -`pattern` | `pattern` | `string` | `''` | A regular expression that the text field's value must match to pass constraint validation.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#pattern -`placeholder` | `placeholder` | `string` | `''` | -`readOnly` | `readonly` | `boolean` | `false` | Indicates whether or not a user should be able to edit the text field's value.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#readonly -`multiple` | `multiple` | `boolean` | `false` | Indicates that input accepts multiple email addresses.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/email#multiple -`step` | `step` | `string` | `''` | Returns or sets the element's step attribute, which works with min and max to limit the increments at which a numeric or date-time value can be set.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#step -`type` | `type` | `string` | `'text'` | The `` type to use, defaults to "text". The type greatly changes how the text field behaves.
Text fields support a limited number of `` types:
- text - textarea - email - number - password - search - tel - url
See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#input_types for more details on each input type. -`autocomplete` | `autocomplete` | `string` | `''` | Describes what, if any, type of autocomplete functionality the input should provide.
https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete -`form` | | `HTMLFormElement` | `undefined` | -`labels` | | `NodeList` | `undefined` | -`name` | | `string` | `undefined` | -`selectionDirection` | | `string` | `undefined` | -`selectionEnd` | | `number` | `undefined` | -`selectionStart` | | `number` | `undefined` | -`validationMessage` | | `string` | `undefined` | -`validity` | | `ValidityState` | `undefined` | -`valueAsNumber` | | `number` | `undefined` | -`valueAsDate` | | `Date` | `undefined` | -`willValidate` | | `boolean` | `undefined` | +| Property | Attribute | Type | Default | Description | +| --- | --- | --- | --- | --- | +| `error` | `error` | `boolean` | `false` | Gets or sets whether or not the text field is in a visually invalid state.
This error state overrides the error state controlled by `reportValidity()`. | +| `errorText` | `error-text` | `string` | `''` | The error message that replaces supporting text when `error` is true. If `errorText` is an empty string, then the supporting text will continue to show.
This error message overrides the error message displayed by `reportValidity()`. | +| `label` | `label` | `string` | `''` | The floating Material label of the textfield component. It informs the user about what information is requested for a text field. It is aligned with the input text, is always visible, and it floats when focused or when text is entered into the textfield. This label also sets accessibilty labels, but the accessible label is overriden by `aria-label`.
Learn more about floating labels from the Material Design guidelines: https://m3.material.io/components/text-fields/guidelines | +| `noAsterisk` | `no-asterisk` | `boolean` | `false` | Disables the asterisk on the floating label, when the text field is required. | +| `required` | `required` | `boolean` | `false` | Indicates that the user must specify a value for the input before the owning form can be submitted and will render an error state when `reportValidity()` is invoked when value is empty. Additionally the floating label will render an asterisk `"*"` when true.
https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/required | +| `value` | `value` | `string` | `''` | The current value of the text field. It is always a string. | +| `prefixText` | `prefix-text` | `string` | `''` | An optional prefix to display before the input value. | +| `suffixText` | `suffix-text` | `string` | `''` | An optional suffix to display after the input value. | +| `hasLeadingIcon` | `has-leading-icon` | `boolean` | `false` | Whether or not the text field has a leading icon. Used for SSR. | +| `hasTrailingIcon` | `has-trailing-icon` | `boolean` | `false` | Whether or not the text field has a trailing icon. Used for SSR. | +| `supportingText` | `supporting-text` | `string` | `''` | Conveys additional information below the text field, such as how it should be used. | +| `textDirection` | `text-direction` | `string` | `''` | Override the input text CSS `direction`. Useful for RTL languages that use LTR notation for fractions. | +| `rows` | `rows` | `number` | `2` | The number of rows to display for a `type="textarea"` text field. Defaults to 2. | +| `cols` | `cols` | `number` | `20` | The number of cols to display for a `type="textarea"` text field. Defaults to 20. | +| `inputMode` | `inputmode` | `string` | `''` | | +| `max` | `max` | `string` | `''` | Defines the greatest value in the range of permitted values.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#max | +| `maxLength` | `maxlength` | `number` | `-1` | The maximum number of characters a user can enter into the text field. Set to -1 for none.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#maxlength | +| `min` | `min` | `string` | `''` | Defines the most negative value in the range of permitted values.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#min | +| `minLength` | `minlength` | `number` | `-1` | The minimum number of characters a user can enter into the text field. Set to -1 for none.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#minlength | +| `noSpinner` | `no-spinner` | `boolean` | `false` | When true, hide the spinner for `type="number"` text fields. | +| `pattern` | `pattern` | `string` | `''` | A regular expression that the text field's value must match to pass constraint validation.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#pattern | +| `placeholder` | `placeholder` | `string` | `''` | Defines the text displayed in the textfield when it has no value. Provides a brief hint to the user as to the expected type of data that should be entered into the control. Unlike `label`, the placeholder is not visible and does not float when the textfield has a value.
https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/placeholder | +| `readOnly` | `readonly` | `boolean` | `false` | Indicates whether or not a user should be able to edit the text field's value.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#readonly | +| `multiple` | `multiple` | `boolean` | `false` | Indicates that input accepts multiple email addresses.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/email#multiple | +| `step` | `step` | `string` | `''` | Returns or sets the element's step attribute, which works with min and max to limit the increments at which a numeric or date-time value can be set.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#step | +| `type` | `type` | `string` | `'text'` | The `` type to use, defaults to "text". The type greatly changes how the text field behaves.
Text fields support a limited number of `` types:
- text - textarea - email - number - password - search - tel - url
See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#input_types for more details on each input type. | +| `autocomplete` | `autocomplete` | `string` | `''` | Describes what, if any, type of autocomplete functionality the input should provide.
https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete | +| `disabled` | | `boolean` | `undefined` | | +| `name` | | `string` | `undefined` | | +| `selectionDirection` | | `string` | `undefined` | | +| `selectionEnd` | | `number` | `undefined` | | +| `selectionStart` | | `number` | `undefined` | | +| `valueAsNumber` | | `number` | `undefined` | | +| `valueAsDate` | | `Date` | `undefined` | | @@ -598,17 +603,28 @@ Property | Attribute | Type | Default | Description -Method | Parameters | Returns | Description ---- | --- | --- | --- -`checkValidity` | _None_ | `boolean` | Checks the text field's native validation and returns whether or not the element is valid.
If invalid, this method will dispatch the `invalid` event.
https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/checkValidity -`reportValidity` | _None_ | `boolean` | Checks the text field's native validation and returns whether or not the element is valid.
If invalid, this method will dispatch the `invalid` event.
This method will display or clear an error text message equal to the text field's `validationMessage`, unless the invalid event is canceled.
Use `setCustomValidity()` to customize the `validationMessage`.
This method can also be used to re-announce error messages to screen readers.
https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/reportValidity -`select` | _None_ | `void` | Selects all the text in the text field.
https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/select -`setCustomValidity` | `error` | `void` | Sets a custom validation error message for the text field. Use this for custom error message.
When the error is not an empty string, the text field is considered invalid and `validity.customError` will be true.
https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setCustomValidity -`setRangeText` | `args` | `void` | -`setSelectionRange` | `start`, `end`, `direction` | `void` | Sets the start and end positions of a selection in the text field.
https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setSelectionRange -`stepDown` | `stepDecrement` | `void` | Decrements the value of a numeric type text field by `step` or `n` `step` number of times.
https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/stepDown -`stepUp` | `stepIncrement` | `void` | Increments the value of a numeric type text field by `step` or `n` `step` number of times.
https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/stepUp -`reset` | _None_ | `void` | Reset the text field to its default value. +| Method | Parameters | Returns | Description | +| --- | --- | --- | --- | +| `select` | _None_ | `void` | Selects all the text in the text field.
https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/select | +| `setRangeText` | `args` | `void` | | +| `setSelectionRange` | `start`, `end`, `direction` | `void` | Sets the start and end positions of a selection in the text field.
https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setSelectionRange | +| `stepDown` | `stepDecrement` | `void` | Decrements the value of a numeric type text field by `step` or `n` `step` number of times.
https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/stepDown | +| `stepUp` | `stepIncrement` | `void` | Increments the value of a numeric type text field by `step` or `n` `step` number of times.
https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/stepUp | +| `reset` | _None_ | `void` | Reset the text field to its default value. | +| `formResetCallback` | _None_ | `void` | | +| `formStateRestoreCallback` | `state` | `void` | | + + + +#### Events + + + +| Event | Type | [Bubbles](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/composed) | Description | +| --- | --- | --- | --- | --- | +| `select` | `Event` | Yes | No | The native `select` event on [``](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/select_event) | +| `change` | `Event` | Yes | No | The native `change` event on [``](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event) | +| `input` | `InputEvent` | Yes | Yes | The native `input` event on [``](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event) | diff --git a/package-lock.json b/package-lock.json index 7039934579..c1710c1158 100644 --- a/package-lock.json +++ b/package-lock.json @@ -16,7 +16,7 @@ "tslib": "^2.4.0" }, "devDependencies": { - "@lit-labs/analyzer": "^0.9.2", + "@lit-labs/analyzer": "^0.12.1", "@rollup/plugin-multi-entry": "^6.0.1", "@rollup/plugin-node-resolve": "^15.2.3", "@rollup/plugin-terser": "^0.4.4", @@ -809,26 +809,26 @@ } }, "node_modules/@lit-labs/analyzer": { - "version": "0.9.2", - "resolved": "https://registry.npmjs.org/@lit-labs/analyzer/-/analyzer-0.9.2.tgz", - "integrity": "sha512-1jaBJWziySwoqS2ZpIcCMufgBvmyPGsCJONitqj3Z9VzKiZzErJjcp/kJv4TiWdYKQWU++K2zsEXtktQxJ4soQ==", + "version": "0.12.1", + "resolved": "https://registry.npmjs.org/@lit-labs/analyzer/-/analyzer-0.12.1.tgz", + "integrity": "sha512-V3bp3jSZAfsCCMRAp0JdiScyWbJgnmArgSdiNHS3jfV9WGf6IFckrOV3zsKj0OZlP0QJAmsgDno2AP4niCYjBg==", "dev": true, "dependencies": { "package-json-type": "^1.0.3", - "typescript": "~5.0.0" + "typescript": "~5.3.3" } }, "node_modules/@lit-labs/analyzer/node_modules/typescript": { - "version": "5.0.4", - "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.0.4.tgz", - "integrity": "sha512-cW9T5W9xY37cc+jfEnaUvX91foxtHkza3Nw3wkoF4sSlKn0MONdkdEndig/qPBWXNkmplh3NzayQzCiHM4/hqw==", + "version": "5.3.3", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.3.3.tgz", + "integrity": "sha512-pXWcraxM0uxAS+tN0AG/BF2TyqmHO014Z070UsJ+pFvYuRSq8KH8DmWpnbXe0pEPDHXZV3FcAbJkijJ5oNEnWw==", "dev": true, "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" }, "engines": { - "node": ">=12.20" + "node": ">=14.17" } }, "node_modules/@lit-labs/eleventy-plugin-lit": { diff --git a/package.json b/package.json index 412ea1ed6e..7d949c5288 100644 --- a/package.json +++ b/package.json @@ -60,7 +60,7 @@ "tslib": "^2.4.0" }, "devDependencies": { - "@lit-labs/analyzer": "^0.9.2", + "@lit-labs/analyzer": "^0.12.1", "@rollup/plugin-multi-entry": "^6.0.1", "@rollup/plugin-node-resolve": "^15.2.3", "@rollup/plugin-terser": "^0.4.4",