mirror of
https://github.com/material-components/material-web.git
synced 2026-01-09 07:21:09 +08:00
docs: auto-generate API docs
Updates API docs in our markdown files with Lit Analyzer by manually running `npm run update-docs` COPYBARA_INTEGRATE_REVIEW=https://github.com/material-components/material-web/pull/4946 from material-components:api-docs 1322ca962041a4b1f30ef7ad3ef2c7eb9087f42b PiperOrigin-RevId: 566834596
This commit is contained in:
Elliott Marquez
Copybara-Service
parent
6132f1ed5c
commit
9f3e55d79a
@ -80,6 +80,10 @@ main > details > summary {
|
||||
margin-inline: auto;
|
||||
}
|
||||
|
||||
main > table {
|
||||
max-width: max-content;
|
||||
}
|
||||
|
||||
table {
|
||||
border-spacing: 0;
|
||||
}
|
||||
|
||||
@ -698,3 +698,110 @@ Token | Default value
|
||||
|
||||
<md-text-button>Text</md-text-button>
|
||||
```
|
||||
|
||||
<!-- auto-generated API docs start -->
|
||||
|
||||
## API
|
||||
|
||||
|
||||
### MdElevatedButton
|
||||
|
||||
#### Properties
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
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<br>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<br>inline start.<br><br>_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` | The associated form element with which this element's value will submit.
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
### MdFilledButton
|
||||
|
||||
#### Properties
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
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<br>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<br>inline start.<br><br>_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` | The associated form element with which this element's value will submit.
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
### MdFilledTonalButton
|
||||
|
||||
#### Properties
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
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<br>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<br>inline start.<br><br>_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` | The associated form element with which this element's value will submit.
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
### MdOutlinedButton
|
||||
|
||||
#### Properties
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
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<br>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<br>inline start.<br><br>_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` | The associated form element with which this element's value will submit.
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
### MdTextButton
|
||||
|
||||
#### Properties
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
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<br>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<br>inline start.<br><br>_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` | The associated form element with which this element's value will submit.
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
<!-- auto-generated API docs end -->
|
||||
|
||||
@ -159,3 +159,44 @@ Token | Default value
|
||||
<md-checkbox touch-target="wrapper"></md-checkbox>
|
||||
<md-checkbox touch-target="wrapper" checked></md-checkbox>
|
||||
```
|
||||
|
||||
<!-- auto-generated API docs start -->
|
||||
|
||||
## API
|
||||
|
||||
|
||||
### MdCheckbox
|
||||
|
||||
#### Properties
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
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.<br><br>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<br>form submission.<br><br>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.<br><br>https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#value
|
||||
`name` | | `string` | `undefined` | The HTML name to use in form submission.
|
||||
`form` | | `HTMLFormElement` | `undefined` | The associated form element with which this element's value will submit.
|
||||
`labels` | | `NodeList` | `undefined` | The labels this element is associated with.
|
||||
`validity` | | `ValidityState` | `undefined` | Returns a ValidityState object that represents the validity states of the<br>checkbox.<br><br>Note that checkboxes will only set `valueMissing` if `required` and not<br>checked.<br><br>https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#validation
|
||||
`validationMessage` | | `string` | `undefined` | Returns the native validation error message.<br><br>https://developer.mozilla.org/en-US/docs/Web/HTML/Constraint_validation#constraint_validation_process
|
||||
`willValidate` | | `boolean` | `undefined` | Returns whether an element will successfully validate based on forms<br>validation rules and constraints.<br><br>https://developer.mozilla.org/en-US/docs/Web/HTML/Constraint_validation#constraint_validation_process
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
#### Methods
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
Method | Parameters | Returns | Description
|
||||
--- | --- | --- | ---
|
||||
`checkValidity` | _None_ | `boolean` | Checks the checkbox's native validation and returns whether or not the<br>element is valid.<br><br>If invalid, this method will dispatch the `invalid` event.<br><br>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<br>element is valid.<br><br>If invalid, this method will dispatch the `invalid` event.<br><br>The `validationMessage` is reported to the user by the browser. Use<br>`setCustomValidity()` to customize the `validationMessage`.<br><br>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<br>customize `validationMessage`.<br><br>When the error is not an empty string, the checkbox is considered invalid<br>and `validity.customError` will be true.<br><br>https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setCustomValidity
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
<!-- auto-generated API docs end -->
|
||||
|
||||
@ -480,3 +480,96 @@ Token | Default value
|
||||
|
||||
<md-suggestion-chip label="Suggestion"></md-suggestion-chip>
|
||||
```
|
||||
|
||||
<!-- auto-generated API docs start -->
|
||||
|
||||
## API
|
||||
|
||||
|
||||
### MdChipSet
|
||||
|
||||
#### Properties
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
Property | Attribute | Type | Default | Description
|
||||
--- | --- | --- | --- | ---
|
||||
`chips` | | `Chip[]` | `undefined` |
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
### MdAssistChip
|
||||
|
||||
#### Properties
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
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.<br><br>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.<br><br>Add this when a chip needs increased visibility when disabled. See<br>https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_disabled_controls<br>for more guidance on when this is needed.
|
||||
`label` | `label` | `string` | `''` | The label of the chip.
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
### MdFilterChip
|
||||
|
||||
#### Properties
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
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.<br><br>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.<br><br>Add this when a chip needs increased visibility when disabled. See<br>https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_disabled_controls<br>for more guidance on when this is needed.
|
||||
`label` | `label` | `string` | `''` | The label of the chip.
|
||||
`handleTrailingActionFocus` | | `() => void` | `undefined` |
|
||||
`ariaLabelRemove` | | `string` | `undefined` |
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
### MdInputChip
|
||||
|
||||
#### Properties
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
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.<br><br>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.<br><br>Add this when a chip needs increased visibility when disabled. See<br>https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_disabled_controls<br>for more guidance on when this is needed.
|
||||
`label` | `label` | `string` | `''` | The label of the chip.
|
||||
`handleTrailingActionFocus` | | `() => void` | `undefined` |
|
||||
`ariaLabelRemove` | | `string` | `undefined` |
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
### MdSuggestionChip
|
||||
|
||||
#### Properties
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
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.<br><br>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.<br><br>Add this when a chip needs increased visibility when disabled. See<br>https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_disabled_controls<br>for more guidance on when this is needed.
|
||||
`label` | `label` | `string` | `''` | The label of the chip.
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
<!-- auto-generated API docs end -->
|
||||
|
||||
@ -238,3 +238,51 @@ Token | Default value
|
||||
<div slot="content">Dialog content</div>
|
||||
</md-dialog>
|
||||
```
|
||||
|
||||
<!-- auto-generated API docs start -->
|
||||
|
||||
## API
|
||||
|
||||
|
||||
### MdDialog
|
||||
|
||||
#### Properties
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
Property | Attribute | Type | Default | Description
|
||||
--- | --- | --- | --- | ---
|
||||
`returnValue` | | `string` | `''` | Gets or sets the dialog's return value, usually to indicate which button<br>a user pressed to close it.<br><br>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<br>dialog as an alert dialog.
|
||||
`open` | `open` | `boolean` | `undefined` | Opens the dialog when set to `true` and closes it when set to `false`.
|
||||
`getOpenAnimation` | | `() => DialogAnimation` | `function { ... }` | Gets the opening animation for a dialog. Set to a new function to customize<br>the animation.
|
||||
`getCloseAnimation` | | `() => DialogAnimation` | `function { ... }` | Gets the closing animation for a dialog. Set to a new function to customize<br>the animation.
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
#### Methods
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
Method | Parameters | Returns | Description
|
||||
--- | --- | --- | ---
|
||||
`show` | _None_ | `Promise<void>` | Opens the dialog and fires a cancelable `open` event. After a dialog's<br>animation, an `opened` event is fired.<br><br>Add an `autocomplete` attribute to a child of the dialog that should<br>receive focus after opening.
|
||||
`close` | `returnValue` | `Promise<void>` | Closes the dialog and fires a cancelable `close` event. After a dialog's<br>animation, a `closed` event is fired.
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
#### Events
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
Event | Type | Description
|
||||
--- | --- | ---
|
||||
`open` | `undefined` | Dispatched when the dialog is opening before any animations.
|
||||
`opened` | `undefined` | Dispatched when the dialog has opened after any animations.
|
||||
`close` | `undefined` | Dispatched when the dialog is closing before any animations.
|
||||
`closed` | `undefined` | Dispatched when the dialog has closed after any animations.
|
||||
`cancel` | `undefined` | Dispatched when the dialog has been canceled by clicking on the<br>scrim or pressing Escape.
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
<!-- auto-generated API docs end -->
|
||||
|
||||
@ -117,3 +117,24 @@ Token | Default value
|
||||
<p>Lorem ipsum...</p>
|
||||
</section>
|
||||
```
|
||||
|
||||
<!-- auto-generated API docs start -->
|
||||
|
||||
## API
|
||||
|
||||
|
||||
### MdDivider
|
||||
|
||||
#### Properties
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
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.
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
<!-- auto-generated API docs end -->
|
||||
|
||||
@ -120,3 +120,6 @@ Token | Default value
|
||||
<!-- Content -->
|
||||
</div>
|
||||
```
|
||||
|
||||
<!-- auto-generated API docs start -->
|
||||
<!-- auto-generated API docs end -->
|
||||
|
||||
@ -472,3 +472,62 @@ Add with a different theme applied](images/fab/theming-branded.webp)
|
||||
</svg>
|
||||
</md-branded-fab>
|
||||
```
|
||||
|
||||
<!-- auto-generated API docs start -->
|
||||
|
||||
## API
|
||||
|
||||
|
||||
### MdFab
|
||||
|
||||
#### Properties
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
Property | Attribute | Type | Default | Description
|
||||
--- | --- | --- | --- | ---
|
||||
`variant` | `variant` | `string` | `'surface'` | The FAB color variant to render.
|
||||
`size` | `size` | `string` | `'medium'` | The size of the FAB.<br><br>NOTE: Branded FABs cannot be sized to `small`, and Extended FABs do not<br>have different sizes.
|
||||
`label` | `label` | `string` | `''` | The text to display on the FAB.
|
||||
`lowered` | `lowered` | `boolean` | `false` | Lowers the FAB's elevation.
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
#### Methods
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
Method | Parameters | Returns | Description
|
||||
--- | --- | --- | ---
|
||||
`getRenderClasses` | _None_ | `{ primary: boolean; secondary: boolean; tertiary: boolean; lowered: boolean; small: boolean; large: boolean; extended: boolean; }` |
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
### MdBrandedFab
|
||||
|
||||
#### Properties
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
Property | Attribute | Type | Default | Description
|
||||
--- | --- | --- | --- | ---
|
||||
`variant` | `variant` | `string` | `'surface'` | The FAB color variant to render.
|
||||
`size` | `size` | `string` | `'medium'` | The size of the FAB.<br><br>NOTE: Branded FABs cannot be sized to `small`, and Extended FABs do not<br>have different sizes.
|
||||
`label` | `label` | `string` | `''` | The text to display on the FAB.
|
||||
`lowered` | `lowered` | `boolean` | `false` | Lowers the FAB's elevation.
|
||||
`variant` | | `string` | `undefined` | Branded FABs have no variants
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
#### Methods
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
Method | Parameters | Returns | Description
|
||||
--- | --- | --- | ---
|
||||
`getRenderClasses` | _None_ | `{ primary: boolean; secondary: boolean; tertiary: boolean; small: boolean; lowered: boolean; large: boolean; extended: boolean; }` |
|
||||
`getRenderClasses` | _None_ | `{ primary: boolean; secondary: boolean; tertiary: boolean; lowered: boolean; small: boolean; large: boolean; extended: boolean; }` |
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
<!-- auto-generated API docs end -->
|
||||
|
||||
@ -130,3 +130,36 @@ md-focus-ring {
|
||||
<md-focus-ring></md-focus-ring>
|
||||
</button>
|
||||
```
|
||||
|
||||
<!-- auto-generated API docs start -->
|
||||
|
||||
## API
|
||||
|
||||
|
||||
### MdFocusRing
|
||||
|
||||
#### Properties
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
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` |
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
#### Methods
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
Method | Parameters | Returns | Description
|
||||
--- | --- | --- | ---
|
||||
`attach` | `control` | `void` |
|
||||
`detach` | _None_ | `void` |
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
<!-- auto-generated API docs end -->
|
||||
|
||||
@ -424,3 +424,102 @@ Token | Default value
|
||||
<md-icon>check</md-icon>
|
||||
</md-outlined-icon-button>
|
||||
```
|
||||
|
||||
<!-- auto-generated API docs start -->
|
||||
|
||||
## API
|
||||
|
||||
|
||||
### MdIconButton
|
||||
|
||||
#### Properties
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
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<br>states
|
||||
`selected` | `selected` | `boolean` | `false` | Sets the selected state. When false, displays the default icon. When true,<br>displays the selected icon, or the default icon If no `slot="selected"`<br>icon is provided.
|
||||
`type` | `type` | `string` | `'submit'` |
|
||||
`value` | `value` | `string` | `''` |
|
||||
`name` | | `string` | `undefined` |
|
||||
`form` | | `HTMLFormElement` | `undefined` | The associated form element with which this element's value will submit.
|
||||
`labels` | | `NodeList` | `undefined` | The labels this element is associated with.
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
### MdFilledIconButton
|
||||
|
||||
#### Properties
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
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<br>states
|
||||
`selected` | `selected` | `boolean` | `false` | Sets the selected state. When false, displays the default icon. When true,<br>displays the selected icon, or the default icon If no `slot="selected"`<br>icon is provided.
|
||||
`type` | `type` | `string` | `'submit'` |
|
||||
`value` | `value` | `string` | `''` |
|
||||
`name` | | `string` | `undefined` |
|
||||
`form` | | `HTMLFormElement` | `undefined` | The associated form element with which this element's value will submit.
|
||||
`labels` | | `NodeList` | `undefined` | The labels this element is associated with.
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
### MdFilledTonalIconButton
|
||||
|
||||
#### Properties
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
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<br>states
|
||||
`selected` | `selected` | `boolean` | `false` | Sets the selected state. When false, displays the default icon. When true,<br>displays the selected icon, or the default icon If no `slot="selected"`<br>icon is provided.
|
||||
`type` | `type` | `string` | `'submit'` |
|
||||
`value` | `value` | `string` | `''` |
|
||||
`name` | | `string` | `undefined` |
|
||||
`form` | | `HTMLFormElement` | `undefined` | The associated form element with which this element's value will submit.
|
||||
`labels` | | `NodeList` | `undefined` | The labels this element is associated with.
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
### MdOutlinedIconButton
|
||||
|
||||
#### Properties
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
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<br>states
|
||||
`selected` | `selected` | `boolean` | `false` | Sets the selected state. When false, displays the default icon. When true,<br>displays the selected icon, or the default icon If no `slot="selected"`<br>icon is provided.
|
||||
`type` | `type` | `string` | `'submit'` |
|
||||
`value` | `value` | `string` | `''` |
|
||||
`name` | | `string` | `undefined` |
|
||||
`form` | | `HTMLFormElement` | `undefined` | The associated form element with which this element's value will submit.
|
||||
`labels` | | `NodeList` | `undefined` | The labels this element is associated with.
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
<!-- auto-generated API docs end -->
|
||||
|
||||
@ -204,3 +204,6 @@ md-icon[filled] {
|
||||
<md-icon filled>house</md-icon>
|
||||
</span>
|
||||
```
|
||||
|
||||
<!-- auto-generated API docs start -->
|
||||
<!-- auto-generated API docs end -->
|
||||
|
||||
@ -542,3 +542,67 @@ Token | Default value
|
||||
</md-list-item>
|
||||
</md-list>
|
||||
```
|
||||
|
||||
<!-- auto-generated API docs start -->
|
||||
|
||||
## API
|
||||
|
||||
|
||||
### MdList
|
||||
|
||||
#### Properties
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
Property | Attribute | Type | Default | Description
|
||||
--- | --- | --- | --- | ---
|
||||
`items` | | `ListItem[]` | `undefined` | An array of activatable and disableable list items. Queries every assigned<br>element that has the `md-list-item` attribute.<br><br>_NOTE:_ This is a shallow, flattened query via<br>`HTMLSlotElement.queryAssignedElements` and thus will _only_ include direct<br>children / directly slotted elements.
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
#### Methods
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
Method | Parameters | Returns | Description
|
||||
--- | --- | --- | ---
|
||||
`activateNextItem` | _None_ | `ListItem` | Activates the next item in the list. If at the end of the list, the first<br>item will be activated.
|
||||
`activatePreviousItem` | _None_ | `ListItem` | Activates the previous item in the list. If at the start of the list, the<br>last item will be activated.
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
### MdListItem
|
||||
|
||||
#### Properties
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
Property | Attribute | Type | Default | Description
|
||||
--- | --- | --- | --- | ---
|
||||
`noninteractive` | `noninteractive` | `boolean` | `false` | Removes the hover and click ripples from the item when true.
|
||||
`headline` | `headline` | `string` | `''` | The primary, headline text of the list item.
|
||||
`supportingText` | `supporting-text` | `string` | `''` | The one-line supporting text below the headline. Set<br>`multiLineSupportingText` to `true` to support multiple lines in the<br>supporting text.
|
||||
`multiLineSupportingText` | `multi-line-supporting-text` | `boolean` | `false` | Modifies `supportingText` to support multiple lines.
|
||||
`trailingSupportingText` | `trailing-supporting-text` | `string` | `''` | The supporting text placed at the end of the item. Overridden by elements<br>slotted into the `end` slot.
|
||||
`disabled` | `disabled` | `boolean` | `false` | Disables the item and makes it non-selectable and non-interactive.
|
||||
`type` | `type` | `string` | `'listitem'` | Sets the role of the list item. Set to 'nothing' to clear the role. This<br>property will be ignored if `href` is set since the underlying element will<br>be a native anchor tag.
|
||||
`href` | `href` | `string` | `''` | Sets the underlying `HTMLAnchorElement`'s `href` resource attribute.
|
||||
`target` | `target` | `string` | `''` | Sets the underlying `HTMLAnchorElement`'s `target` attribute when `href` is<br>set.
|
||||
`tabIndex` | `tabindex` | `number` | `0` |
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
#### Methods
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
Method | Parameters | Returns | Description
|
||||
--- | --- | --- | ---
|
||||
`getRenderClasses` | _None_ | `{ noninteractive: boolean; 'with-one-line': boolean; 'with-two-line': boolean; 'with-three-line': boolean; disabled: boolean; }` |
|
||||
`renderRipple` | _None_ | `unique symbol \| TemplateResult` |
|
||||
`renderFocusRing` | _None_ | `unique symbol \| TemplateResult` |
|
||||
`onFocus` | _None_ | `void` |
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
<!-- auto-generated API docs end -->
|
||||
|
||||
@ -346,3 +346,150 @@ a sharp 0px border radius.](images/menu/theming.webp)
|
||||
});
|
||||
</script>
|
||||
```
|
||||
|
||||
<!-- auto-generated API docs start -->
|
||||
|
||||
## API
|
||||
|
||||
|
||||
### MdMenu
|
||||
|
||||
#### Properties
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
Property | Attribute | Type | Default | Description
|
||||
--- | --- | --- | --- | ---
|
||||
`anchor` | `anchor` | `string` | `''` | The ID of the element in the same root node in which the menu should align<br>to. Overrides setting `anchorElement = elementReference`.<br><br>__NOTE__: anchor or anchorElement must either be an HTMLElement or resolve<br>to an HTMLElement in order for menu to open.
|
||||
`fixed` | `fixed` | `boolean` | `false` | Makes the element use `position:fixed` instead of `position:absolute`. In<br>most cases, the menu should position itself above most other<br>`position:absolute` or `position:fixed` elements when placed inside of<br>them. e.g. using a menu inside of an `md-dialog`.<br><br>__NOTE__: Fixed menus will not scroll with the page and will be fixed to<br>the window instead.
|
||||
`quick` | `quick` | `boolean` | `false` | Skips the opening and closing animations.
|
||||
`hasOverflow` | `has-overflow` | `boolean` | `false` | Displays overflow content like a submenu.<br><br>__NOTE__: This may cause adverse effects if you set<br>`md-menu {max-height:...}`<br>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<br>`.close()` methods
|
||||
`xOffset` | `x-offset` | `number` | `0` | Offsets the menu's inline alignment from the anchor by the given number in<br>pixels. This value is direction aware and will follow the LTR / RTL<br>direction.<br><br>e.g. LTR: positive -> right, negative -> left<br> RTL: positive -> left, negative -> right
|
||||
`yOffset` | `y-offset` | `number` | `0` | Offsets the menu's block alignment from the anchor by the given number in<br>pixels.<br><br>e.g. positive -> down, negative -> up
|
||||
`listTabIndex` | `list-tabindex` | `number` | `-1` | The tabindex of the underlying list element.
|
||||
`type` | `type` | `string` | `'menu'` | The role of the underlying list element.
|
||||
`typeaheadDelay` | `typeahead-delay` | `number` | `200` | The max time between the keystrokes of the typeahead menu behavior before<br>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<br>property style of <block>-<inline> e.g. `'end-start'`.<br><br>NOTE: This value may not be respected by the menu positioning algorithm<br>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<br>property style of <block>-<inline> e.g. `'start-start'`.<br><br>NOTE: This value may not be respected by the menu positioning algorithm<br>if the menu would render outisde the viewport.
|
||||
`stayOpenOnOutsideClick` | `stay-open-on-outside-click` | `boolean` | `false` | Keeps the user clicks outside the menu.<br><br>NOTE: clicking outside may still cause focusout to close the menu so see<br>`stayOpenOnFocusout`.
|
||||
`stayOpenOnFocusout` | `stay-open-on-focusout` | `boolean` | `false` | Keeps the menu open when focus leaves the menu's composed subtree.<br><br>NOTE: Focusout behavior will stop propagation of the focusout event. Set<br>this property to true to opt-out of menu's focuout handling altogether.
|
||||
`skipRestoreFocus` | `skip-restore-focus` | `boolean` | `false` | After closing, does not restore focus to the last focused element before<br>the menu was opened.
|
||||
`defaultFocus` | `default-focus` | `string` | `FocusState.FIRST_ITEM` | The element that should be focused by default once opened.<br><br>NOTE: When setting default focus to 'LIST_ROOT', remember to change<br>`list-tabindex` to `0` when necessary.
|
||||
`typeaheadController` | | `TypeaheadController` | `function { ... }` | Handles typeahead navigation through the menu.
|
||||
`anchorElement` | | `HTMLElement & Partial<SurfacePositionTarget>` | `undefined` | The element which the menu should align to. If `anchor` is set to a<br>non-empty idref string, then `anchorEl` will resolve to the element with<br>the given id in the same root node. Otherwise, `null`.
|
||||
`items` | | `MenuItem[]` | `undefined` | The menu items associated with this menu. The items must be `MenuItem`s and<br>have both the `md-menu-item` and `md-list-item` attributes.
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
#### Methods
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
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<br>item will be activated.
|
||||
`activatePreviousItem` | _None_ | `MenuItem` | Activates the previous item in the menu. If at the start of the menu, the<br>last item will be activated.
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
#### Events
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
Event | Type | Description
|
||||
--- | --- | ---
|
||||
`opening` | `undefined` | Fired before the opening animation begins
|
||||
`opened` | `undefined` | Fired once the menu is open, after any animations
|
||||
`closing` | `undefined` | Fired before the closing animation begins
|
||||
`closed` | `undefined` | Fired once the menu is closed, after any animations
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
### MdMenuItem
|
||||
|
||||
#### Properties
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
Property | Attribute | Type | Default | Description
|
||||
--- | --- | --- | --- | ---
|
||||
`keepOpen` | `keep-open` | `boolean` | `false` | Keeps the menu open if clicked or keyboard selected.
|
||||
`headline` | `headline` | `string` | `''` | The primary, headline text of the list item.
|
||||
`supportingText` | `supporting-text` | `string` | `''` | The one-line supporting text below the headline. Set<br>`multiLineSupportingText` to `true` to support multiple lines in the<br>supporting text.
|
||||
`multiLineSupportingText` | `multi-line-supporting-text` | `boolean` | `false` | Modifies `supportingText` to support multiple lines.
|
||||
`trailingSupportingText` | `trailing-supporting-text` | `string` | `''` | The supporting text placed at the end of the item. Overridden by elements<br>slotted into the `end` slot.
|
||||
`disabled` | `disabled` | `boolean` | `false` | Disables the item and makes it non-selectable and non-interactive.
|
||||
`type` | `type` | `string` | `'listitem'` | Sets the role of the list item. Set to 'nothing' to clear the role. This<br>property will be ignored if `href` is set since the underlying element will<br>be a native anchor tag.
|
||||
`href` | `href` | `string` | `''` | Sets the underlying `HTMLAnchorElement`'s `href` resource attribute.
|
||||
`target` | `target` | `string` | `''` | Sets the underlying `HTMLAnchorElement`'s `target` attribute when `href` is<br>set.
|
||||
`tabIndex` | `tabindex` | `number` | `0` |
|
||||
`type` | | `string` | `'menuitem'` |
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
#### Events
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
Event | Type | Description
|
||||
--- | --- | ---
|
||||
`close-menu` | `CloseMenuEvent` |
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
### MdSubMenuItem
|
||||
|
||||
#### Properties
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
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.
|
||||
`selected` | `selected` | `boolean` | `false` | Sets the item in the selected visual state when a submenu is opened.
|
||||
`keepOpen` | `keep-open` | `boolean` | `false` | Keeps the menu open if clicked or keyboard selected.
|
||||
`headline` | `headline` | `string` | `''` | The primary, headline text of the list item.
|
||||
`supportingText` | `supporting-text` | `string` | `''` | The one-line supporting text below the headline. Set<br>`multiLineSupportingText` to `true` to support multiple lines in the<br>supporting text.
|
||||
`multiLineSupportingText` | `multi-line-supporting-text` | `boolean` | `false` | Modifies `supportingText` to support multiple lines.
|
||||
`trailingSupportingText` | `trailing-supporting-text` | `string` | `''` | The supporting text placed at the end of the item. Overridden by elements<br>slotted into the `end` slot.
|
||||
`disabled` | `disabled` | `boolean` | `false` | Disables the item and makes it non-selectable and non-interactive.
|
||||
`type` | `type` | `string` | `'listitem'` | Sets the role of the list item. Set to 'nothing' to clear the role. This<br>property will be ignored if `href` is set since the underlying element will<br>be a native anchor tag.
|
||||
`href` | `href` | `string` | `''` | Sets the underlying `HTMLAnchorElement`'s `href` resource attribute.
|
||||
`target` | `target` | `string` | `''` | Sets the underlying `HTMLAnchorElement`'s `target` attribute when `href` is<br>set.
|
||||
`tabIndex` | `tabindex` | `number` | `0` |
|
||||
`type` | | `string` | `'menuitem'` |
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
#### Methods
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
Method | Parameters | Returns | Description
|
||||
--- | --- | --- | ---
|
||||
`show` | `onOpened` | `void` | Shows the submenu.
|
||||
`close` | `onClosed` | `void` | Closes the submenu.
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
#### Events
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
Event | Type | Description
|
||||
--- | --- | ---
|
||||
`deactivate-items` | `undefined` | Requests the parent menu to deselect other items when<br>a submenu opens
|
||||
`request-activation` | `undefined` | Requests the parent make the element focusable and<br>focuses the item.
|
||||
`deactivate-typeahead` | `undefined` | Requests the parent menu to deactivate the<br>typeahead functionality when a submenu opens
|
||||
`activate-typeahead` | `undefined` | Requests the parent menu to activate the typeahead<br>functionality when a submenu closes
|
||||
`close-menu` | `CloseMenuEvent` |
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
<!-- auto-generated API docs end -->
|
||||
|
||||
@ -374,3 +374,41 @@ Token | Default value
|
||||
|
||||
<md-linear-progress value="0.5"></md-linear-progress>
|
||||
```
|
||||
|
||||
<!-- auto-generated API docs start -->
|
||||
|
||||
## API
|
||||
|
||||
|
||||
### MdLinearProgress
|
||||
|
||||
#### Properties
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
Property | Attribute | Type | Default | Description
|
||||
--- | --- | --- | --- | ---
|
||||
`buffer` | `buffer` | `number` | `1` | Buffer amount to display, a fraction between 0 and 1.
|
||||
`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<br>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.
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
### MdCircularProgress
|
||||
|
||||
#### Properties
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
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<br>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.
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
<!-- auto-generated API docs end -->
|
||||
|
||||
@ -205,3 +205,27 @@ Token | Default value
|
||||
<md-radio name="group" checked></md-radio>
|
||||
<md-radio name="group"></md-radio>
|
||||
```
|
||||
|
||||
<!-- auto-generated API docs start -->
|
||||
|
||||
## API
|
||||
|
||||
|
||||
### MdRadio
|
||||
|
||||
#### Properties
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
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` | Whether or not the radio is selected.
|
||||
`name` | | `string` | `undefined` | The HTML name to use in form submission.
|
||||
`form` | | `HTMLFormElement` | `undefined` | The associated form element with which this element's value will submit.
|
||||
`labels` | | `NodeList` | `undefined` | The labels this element is associated with.
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
<!-- auto-generated API docs end -->
|
||||
|
||||
@ -260,3 +260,35 @@ Token | Default value
|
||||
<md-ripple></md-ripple>
|
||||
</button>
|
||||
```
|
||||
|
||||
<!-- auto-generated API docs start -->
|
||||
|
||||
## API
|
||||
|
||||
|
||||
### MdRipple
|
||||
|
||||
#### Properties
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
Property | Attribute | Type | Default | Description
|
||||
--- | --- | --- | --- | ---
|
||||
`disabled` | `disabled` | `boolean` | `false` | Disables the ripple.
|
||||
`htmlFor` | | `string` | `undefined` |
|
||||
`control` | | `HTMLElement` | `undefined` |
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
#### Methods
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
Method | Parameters | Returns | Description
|
||||
--- | --- | --- | ---
|
||||
`attach` | `control` | `void` |
|
||||
`detach` | _None_ | `void` |
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
<!-- auto-generated API docs end -->
|
||||
|
||||
@ -155,3 +155,43 @@ Token | Default value
|
||||
step="5"
|
||||
></md-slider>
|
||||
```
|
||||
|
||||
<!-- auto-generated API docs start -->
|
||||
|
||||
## API
|
||||
|
||||
|
||||
### MdSlider
|
||||
|
||||
#### Properties
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
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<br>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<br>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<br>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<br>range is true.
|
||||
`ariaValueTextStart` | `aria-valuetext-start` | `string` | `''` | Aria value text for the slider's start value displayed when<br>range is true.
|
||||
`ariaLabelEnd` | `aria-label-end` | `string` | `''` | Aria label for the slider's end handle displayed when<br>range is true.
|
||||
`ariaValueTextEnd` | `aria-valuetext-end` | `string` | `''` | Aria value text for the slider's end value displayed when<br>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<br>a slideable handle for the value property; when true, it displays<br>slideable handles for the valueStart and valueEnd properties.
|
||||
`name` | | `string` | `undefined` | The HTML name to use in form submission.
|
||||
`nameStart` | | `string` | `undefined` | The HTML name to use in form submission for a range slider's starting<br>value. Use `name` instead if both the start and end values should use the<br>same name.
|
||||
`nameEnd` | | `string` | `undefined` | The HTML name to use in form submission for a range slider's ending value.<br>Use `name` instead if both the start and end values should use the same<br>name.
|
||||
`form` | | `HTMLFormElement` | `undefined` | The associated form element with which this element's value will submit.
|
||||
`labels` | | `NodeList` | `undefined` | The labels this element is associated with.
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
<!-- auto-generated API docs end -->
|
||||
|
||||
@ -227,3 +227,56 @@ Token | Default value
|
||||
<md-switch></md-switch>
|
||||
<md-switch selected></md-switch>
|
||||
```
|
||||
|
||||
<!-- auto-generated API docs start -->
|
||||
|
||||
## API
|
||||
|
||||
|
||||
### MdSwitch
|
||||
|
||||
#### Properties
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
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<br>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`,<br>overrides the behavior of the `icons` property.
|
||||
`required` | `required` | `boolean` | `false` | When true, require the switch to be selected when participating in<br>form submission.<br><br>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<br>submitted when `selected` is `false`.
|
||||
`name` | | `string` | `undefined` | The HTML name to use in form submission.
|
||||
`form` | | `HTMLFormElement` | `undefined` | The associated form element with which this element's value will submit.
|
||||
`labels` | | `NodeList` | `undefined` | The labels this element is associated with.
|
||||
`validity` | | `ValidityState` | `undefined` | Returns a ValidityState object that represents the validity states of the<br>switch.<br><br>Note that switches will only set `valueMissing` if `required` and not<br>selected.<br><br>https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#validation
|
||||
`validationMessage` | | `string` | `undefined` | Returns the native validation error message.<br><br>https://developer.mozilla.org/en-US/docs/Web/HTML/Constraint_validation#constraint_validation_process
|
||||
`willValidate` | | `boolean` | `undefined` | Returns whether an element will successfully validate based on forms<br>validation rules and constraints.<br><br>https://developer.mozilla.org/en-US/docs/Web/HTML/Constraint_validation#constraint_validation_process
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
#### Methods
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
Method | Parameters | Returns | Description
|
||||
--- | --- | --- | ---
|
||||
`checkValidity` | _None_ | `boolean` | Checks the switch's native validation and returns whether or not the<br>element is valid.<br><br>If invalid, this method will dispatch the `invalid` event.<br><br>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<br>element is valid.<br><br>If invalid, this method will dispatch the `invalid` event.<br><br>The `validationMessage` is reported to the user by the browser. Use<br>`setCustomValidity()` to customize the `validationMessage`.<br><br>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<br>customize `validationMessage`.<br><br>When the error is not an empty string, the switch is considered invalid<br>and `validity.customError` will be true.<br><br>https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setCustomValidity
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
#### Events
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
Event | Type | Description
|
||||
--- | --- | ---
|
||||
`input` | `InputEvent` | Fired whenever `selected` changes due to user<br>interaction (bubbles and composed).
|
||||
`change` | `Event` | Fired whenever `selected` changes due to user<br>interaction (bubbles).
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
<!-- auto-generated API docs end -->
|
||||
|
||||
@ -369,3 +369,96 @@ Token | Default value
|
||||
<md-secondary-tab>Tab 3</md-secondary-tab>
|
||||
</md-tabs>
|
||||
```
|
||||
|
||||
<!-- auto-generated API docs start -->
|
||||
|
||||
## API
|
||||
|
||||
|
||||
### MdTabs
|
||||
|
||||
#### Properties
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
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` | The currently selected tab, `null` only when there are no tab children.
|
||||
`activeTabIndex` | | `number` | `undefined` | The index of the currently selected tab.
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
#### Methods
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
Method | Parameters | Returns | Description
|
||||
--- | --- | --- | ---
|
||||
`scrollToTab` | `tabToScrollTo` | `Promise<void>` | Scrolls the toolbar, if overflowing, to the active tab, or the provided<br>tab.
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
#### Events
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
Event | Type | Description
|
||||
--- | --- | ---
|
||||
`change` | `undefined` | Fired when the selected tab changes. The target's selected or<br>selectedItem and previousSelected or previousSelectedItem provide information<br>about the selection change. The change event is fired when a user interaction<br>like a space/enter key or click cause a selection change. The tab selection<br>based on these actions can be cancelled by calling preventDefault on the<br>triggering `keydown` or `click` event.
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
### MdPrimaryTab
|
||||
|
||||
#### Properties
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
Property | Attribute | Type | Default | Description
|
||||
--- | --- | --- | --- | ---
|
||||
`inlineIcon` | `inline-icon` | `boolean` | `false` | Whether or not the icon renders inline with label or stacked vertically.
|
||||
`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` | TODO(b/293476210): remove after migrating
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
#### Methods
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
Method | Parameters | Returns | Description
|
||||
--- | --- | --- | ---
|
||||
`[ANIMATE_INDICATOR]` | `previousTab` | `void` |
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
### MdSecondaryTab
|
||||
|
||||
#### Properties
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
Property | Attribute | Type | Default | Description
|
||||
--- | --- | --- | --- | ---
|
||||
`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` | TODO(b/293476210): remove after migrating
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
#### Methods
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
Method | Parameters | Returns | Description
|
||||
--- | --- | --- | ---
|
||||
`[ANIMATE_INDICATOR]` | `previousTab` | `void` |
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
<!-- auto-generated API docs end -->
|
||||
|
||||
@ -474,3 +474,138 @@ Token | Default value
|
||||
|
||||
<md-outlined-text-field label="Outlined" value="Value"></md-outlined-text-field>
|
||||
```
|
||||
|
||||
<!-- auto-generated API docs start -->
|
||||
|
||||
## API
|
||||
|
||||
|
||||
### MdFilledTextField
|
||||
|
||||
#### Properties
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
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.<br><br>This error state overrides the error state controlled by<br>`reportValidity()`.
|
||||
`errorText` | `error-text` | `string` | `''` | The error message that replaces supporting text when `error` is true. If<br>`errorText` is an empty string, then the supporting text will continue to<br>show.<br><br>This error message overrides the error message displayed by<br>`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<br>be used.
|
||||
`textDirection` | `text-direction` | `string` | `''` | Override the input text CSS `direction`. Useful for RTL languages that use<br>LTR notation for fractions.
|
||||
`rows` | `rows` | `number` | `2` | The number of rows to display for a `type="textarea"` text field.<br>Defaults to 2.
|
||||
`inputMode` | `inputmode` | `string` | `''` |
|
||||
`max` | `max` | `string` | `''` | Defines the greatest value in the range of permitted values.<br><br>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<br>to -1 for none.<br><br>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.<br><br>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<br>to -1 for none.<br><br>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<br>constraint validation.<br><br>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<br>value.<br><br>https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#readonly
|
||||
`step` | `step` | `string` | `''` | Returns or sets the element's step attribute, which works with min and max<br>to limit the increments at which a numeric or date-time value can be set.<br><br>https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#step
|
||||
`type` | `type` | `string` | `'text'` | The `<input>` type to use, defaults to "text". The type greatly changes how<br>the text field behaves.<br><br>Text fields support a limited number of `<input>` types:<br><br>- text<br>- textarea<br>- email<br>- number<br>- password<br>- search<br>- tel<br>- url<br><br>See<br>https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#input_types<br>for more details on each input type.
|
||||
`autocomplete` | `autocomplete` | `string` | `''` | Describes what, if any, type of autocomplete functionality the input<br>should provide.<br><br>https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete
|
||||
`form` | | `HTMLFormElement` | `undefined` | The associated form element with which this element's value will submit.
|
||||
`labels` | | `NodeList` | `undefined` | The labels this element is associated with.
|
||||
`name` | | `string` | `undefined` | The HTML name to use in form submission.
|
||||
`selectionDirection` | | `string` | `undefined` | Gets or sets the direction in which selection occurred.
|
||||
`selectionEnd` | | `number` | `undefined` | Gets or sets the end position or offset of a text selection.
|
||||
`selectionStart` | | `number` | `undefined` | Gets or sets the starting position or offset of a text selection.
|
||||
`validationMessage` | | `string` | `undefined` | Returns the text field's validation error message.<br><br>https://developer.mozilla.org/en-US/docs/Web/HTML/Constraint_validation
|
||||
`validity` | | `ValidityState` | `undefined` | Returns a `ValidityState` object that represents the validity states of the<br>text field.<br><br>https://developer.mozilla.org/en-US/docs/Web/API/ValidityState
|
||||
`valueAsNumber` | | `number` | `undefined` | The text field's value as a number.
|
||||
`valueAsDate` | | `Date` | `undefined` | The text field's value as a Date.
|
||||
`willValidate` | | `boolean` | `undefined` | Returns whether an element will successfully validate based on forms<br>validation rules and constraints.<br><br>https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/willValidate
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
#### Methods
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
Method | Parameters | Returns | Description
|
||||
--- | --- | --- | ---
|
||||
`checkValidity` | _None_ | `boolean` | Checks the text field's native validation and returns whether or not the<br>element is valid.<br><br>If invalid, this method will dispatch the `invalid` event.<br><br>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<br>element is valid.<br><br>If invalid, this method will dispatch the `invalid` event.<br><br>This method will display or clear an error text message equal to the text<br>field's `validationMessage`, unless the invalid event is canceled.<br><br>Use `setCustomValidity()` to customize the `validationMessage`.<br><br>This method can also be used to re-announce error messages to screen<br>readers.<br><br>https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/reportValidity
|
||||
`select` | _None_ | `void` | Selects all the text in the text field.<br><br>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<br>custom error message.<br><br>When the error is not an empty string, the text field is considered invalid<br>and `validity.customError` will be true.<br><br>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.<br><br>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`<br>number of times.<br><br>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`<br>number of times.<br><br>https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/stepUp
|
||||
`reset` | _None_ | `void` | Reset the text field to its default value.
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
### MdOutlinedTextField
|
||||
|
||||
#### Properties
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
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.<br><br>This error state overrides the error state controlled by<br>`reportValidity()`.
|
||||
`errorText` | `error-text` | `string` | `''` | The error message that replaces supporting text when `error` is true. If<br>`errorText` is an empty string, then the supporting text will continue to<br>show.<br><br>This error message overrides the error message displayed by<br>`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<br>be used.
|
||||
`textDirection` | `text-direction` | `string` | `''` | Override the input text CSS `direction`. Useful for RTL languages that use<br>LTR notation for fractions.
|
||||
`rows` | `rows` | `number` | `2` | The number of rows to display for a `type="textarea"` text field.<br>Defaults to 2.
|
||||
`inputMode` | `inputmode` | `string` | `''` |
|
||||
`max` | `max` | `string` | `''` | Defines the greatest value in the range of permitted values.<br><br>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<br>to -1 for none.<br><br>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.<br><br>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<br>to -1 for none.<br><br>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<br>constraint validation.<br><br>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<br>value.<br><br>https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#readonly
|
||||
`step` | `step` | `string` | `''` | Returns or sets the element's step attribute, which works with min and max<br>to limit the increments at which a numeric or date-time value can be set.<br><br>https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#step
|
||||
`type` | `type` | `string` | `'text'` | The `<input>` type to use, defaults to "text". The type greatly changes how<br>the text field behaves.<br><br>Text fields support a limited number of `<input>` types:<br><br>- text<br>- textarea<br>- email<br>- number<br>- password<br>- search<br>- tel<br>- url<br><br>See<br>https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#input_types<br>for more details on each input type.
|
||||
`autocomplete` | `autocomplete` | `string` | `''` | Describes what, if any, type of autocomplete functionality the input<br>should provide.<br><br>https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete
|
||||
`form` | | `HTMLFormElement` | `undefined` | The associated form element with which this element's value will submit.
|
||||
`labels` | | `NodeList` | `undefined` | The labels this element is associated with.
|
||||
`name` | | `string` | `undefined` | The HTML name to use in form submission.
|
||||
`selectionDirection` | | `string` | `undefined` | Gets or sets the direction in which selection occurred.
|
||||
`selectionEnd` | | `number` | `undefined` | Gets or sets the end position or offset of a text selection.
|
||||
`selectionStart` | | `number` | `undefined` | Gets or sets the starting position or offset of a text selection.
|
||||
`validationMessage` | | `string` | `undefined` | Returns the text field's validation error message.<br><br>https://developer.mozilla.org/en-US/docs/Web/HTML/Constraint_validation
|
||||
`validity` | | `ValidityState` | `undefined` | Returns a `ValidityState` object that represents the validity states of the<br>text field.<br><br>https://developer.mozilla.org/en-US/docs/Web/API/ValidityState
|
||||
`valueAsNumber` | | `number` | `undefined` | The text field's value as a number.
|
||||
`valueAsDate` | | `Date` | `undefined` | The text field's value as a Date.
|
||||
`willValidate` | | `boolean` | `undefined` | Returns whether an element will successfully validate based on forms<br>validation rules and constraints.<br><br>https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/willValidate
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
#### Methods
|
||||
|
||||
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
Method | Parameters | Returns | Description
|
||||
--- | --- | --- | ---
|
||||
`checkValidity` | _None_ | `boolean` | Checks the text field's native validation and returns whether or not the<br>element is valid.<br><br>If invalid, this method will dispatch the `invalid` event.<br><br>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<br>element is valid.<br><br>If invalid, this method will dispatch the `invalid` event.<br><br>This method will display or clear an error text message equal to the text<br>field's `validationMessage`, unless the invalid event is canceled.<br><br>Use `setCustomValidity()` to customize the `validationMessage`.<br><br>This method can also be used to re-announce error messages to screen<br>readers.<br><br>https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/reportValidity
|
||||
`select` | _None_ | `void` | Selects all the text in the text field.<br><br>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<br>custom error message.<br><br>When the error is not an empty string, the text field is considered invalid<br>and `validity.customError` will be true.<br><br>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.<br><br>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`<br>number of times.<br><br>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`<br>number of times.<br><br>https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/stepUp
|
||||
`reset` | _None_ | `void` | Reset the text field to its default value.
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||||
|
||||
<!-- auto-generated API docs end -->
|
||||
|
||||
@ -149,7 +149,7 @@ export abstract class Menu extends LitElement {
|
||||
typeaheadDelay = DEFAULT_TYPEAHEAD_BUFFER_TIME;
|
||||
/**
|
||||
* The corner of the anchor which to align the menu in the standard logical
|
||||
* property style of <block>_<inline>.
|
||||
* property style of <block>-<inline> e.g. `'end-start'`.
|
||||
*
|
||||
* NOTE: This value may not be respected by the menu positioning algorithm
|
||||
* if the menu would render outisde the viewport.
|
||||
@ -158,7 +158,7 @@ export abstract class Menu extends LitElement {
|
||||
anchorCorner: Corner = Corner.END_START;
|
||||
/**
|
||||
* The corner of the menu which to align the anchor in the standard logical
|
||||
* property style of <block>_<inline>.
|
||||
* property style of <block>-<inline> e.g. `'start-start'`.
|
||||
*
|
||||
* NOTE: This value may not be respected by the menu positioning algorithm
|
||||
* if the menu would render outisde the viewport.
|
||||
|
||||
92
package.json
92
package.json
@ -28,7 +28,9 @@
|
||||
"build:css-to-ts": "wireit",
|
||||
"build:sass": "wireit",
|
||||
"test": "wireit",
|
||||
"build:catalog": "wireit"
|
||||
"build:catalog": "wireit",
|
||||
"build:analyzer": "wireit",
|
||||
"update-docs": "wireit"
|
||||
},
|
||||
"type": "module",
|
||||
"files": [
|
||||
@ -42,16 +44,16 @@
|
||||
"!**/testing/**",
|
||||
"!**/*_test.*",
|
||||
"!.wireit/**",
|
||||
"!catalog"
|
||||
],
|
||||
"workspaces": [
|
||||
"catalog"
|
||||
"!catalog",
|
||||
"!scripts/"
|
||||
],
|
||||
"workspaces": ["catalog"],
|
||||
"dependencies": {
|
||||
"lit": "^2.7.4 || ^3.0.0",
|
||||
"tslib": "^2.4.0"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@lit-labs/analyzer": "^0.9.2",
|
||||
"@types/jasmine": "^4.0.3",
|
||||
"@web/test-runner": "^0.15.0",
|
||||
"@web/test-runner-playwright": "^0.9.0",
|
||||
@ -64,9 +66,7 @@
|
||||
},
|
||||
"wireit": {
|
||||
"build": {
|
||||
"dependencies": [
|
||||
"build:ts"
|
||||
]
|
||||
"dependencies": ["build:ts"]
|
||||
},
|
||||
"build:ts": {
|
||||
"command": "tsc --pretty",
|
||||
@ -75,7 +75,8 @@
|
||||
"**/*.ts",
|
||||
"!**/*.d.ts",
|
||||
"!**/*.css.ts",
|
||||
"!catalog"
|
||||
"!catalog",
|
||||
"!scripts/"
|
||||
],
|
||||
"output": [
|
||||
".tsbuildinfo",
|
||||
@ -85,52 +86,61 @@
|
||||
"!css-to-ts.js",
|
||||
"!web-test-runner.config.js",
|
||||
"!types/",
|
||||
"!catalog"
|
||||
"!catalog",
|
||||
"!scripts/"
|
||||
],
|
||||
"clean": "if-file-deleted",
|
||||
"dependencies": [
|
||||
"build:css-to-ts"
|
||||
]
|
||||
"dependencies": ["build:css-to-ts"]
|
||||
},
|
||||
"build:css-to-ts": {
|
||||
"command": "find . \\( -path ./.wireit -o -path ./node_modules -o -path ./catalog \\) -prune -o -name '*.css' -print | xargs node css-to-ts.js",
|
||||
"files": [
|
||||
"css-to-ts.js"
|
||||
],
|
||||
"output": [
|
||||
"**/*.css.ts",
|
||||
"!catalog"
|
||||
],
|
||||
"dependencies": [
|
||||
"build:sass"
|
||||
]
|
||||
"files": ["css-to-ts.js", "!scripts/"],
|
||||
"output": ["**/*.css.ts", "!catalog", "!scripts/"],
|
||||
"dependencies": ["build:sass"]
|
||||
},
|
||||
"build:sass": {
|
||||
"command": "sass --style=compressed --load-path=node_modules --load-path=node_modules/sass-true/sass $(ls -d */ | grep -vE 'node_modules|catalog')",
|
||||
"files": [
|
||||
"**/*.scss",
|
||||
"!catalog"
|
||||
],
|
||||
"output": [
|
||||
"**/*.css",
|
||||
"**/*.css.map",
|
||||
"!catalog"
|
||||
]
|
||||
"files": ["**/*.scss", "!catalog", "!scripts/"],
|
||||
"output": ["**/*.css", "**/*.css.map", "!catalog", "!scripts/"]
|
||||
},
|
||||
"test": {
|
||||
"command": "wtr",
|
||||
"dependencies": [
|
||||
"build:ts"
|
||||
],
|
||||
"files": [
|
||||
"web-test-runner.config.js"
|
||||
],
|
||||
"dependencies": ["build:ts"],
|
||||
"files": ["web-test-runner.config.js"],
|
||||
"output": []
|
||||
},
|
||||
"build:catalog": {
|
||||
"dependencies": [
|
||||
"./catalog:build:prod"
|
||||
]
|
||||
"dependencies": ["./catalog:build:prod"]
|
||||
},
|
||||
"build:analyzer": {
|
||||
"command": "tsc -b scripts/analyzer/tsconfig.json --pretty",
|
||||
"files": [
|
||||
"scripts/tsconfig.json",
|
||||
"scripts/analyzer/**/*.ts",
|
||||
"!**/*.d.ts",
|
||||
"!**/*.css.ts"
|
||||
],
|
||||
"output": [
|
||||
"scripts/.tsbuildinfo",
|
||||
"scripts/analyzer/**/*.js",
|
||||
"scripts/analyzer/**/*.js.map",
|
||||
"scripts/analyzer/**/*.d.ts"
|
||||
],
|
||||
"clean": "if-file-deleted"
|
||||
},
|
||||
"update-docs": {
|
||||
"command": "node scripts/analyzer/update-docs.js",
|
||||
"files": [
|
||||
"docs/components/*.md",
|
||||
"**/*.ts",
|
||||
"!**/*.d.ts",
|
||||
"!**/*.css.ts",
|
||||
"!catalog",
|
||||
"!scripts/",
|
||||
"scripts/analyzer/update-docs.js"
|
||||
],
|
||||
"output": [],
|
||||
"dependencies": ["build:analyzer"]
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
342
scripts/analyzer/analyze-element.ts
Normal file
342
scripts/analyzer/analyze-element.ts
Normal file
@ -0,0 +1,342 @@
|
||||
/**
|
||||
* @license
|
||||
* Copyright 2023 Google LLC
|
||||
* SPDX-License-Identifier: Apache-2.0
|
||||
*/
|
||||
|
||||
import {AbsolutePath, Analyzer, LitElementDeclaration, LitElementExport, Module,} from '@lit-labs/analyzer/package-analyzer.js';
|
||||
import * as path from 'path';
|
||||
import type ts from 'typescript';
|
||||
|
||||
/**
|
||||
* Represents a module that exports a custom element and links its superclasses
|
||||
* via the superClass property up to the `LitElement` superclass.
|
||||
*/
|
||||
export interface MdModuleInfo {
|
||||
customElementName?: string;
|
||||
className: string;
|
||||
classPath: string;
|
||||
summary?: string;
|
||||
description?: string;
|
||||
properties: MdPropertyInfo[];
|
||||
reactiveProperties: MdPropertyInfo[];
|
||||
methods: MdMethodInfo[];
|
||||
superClass?: MdModuleInfo;
|
||||
events: MdEventInfo[];
|
||||
}
|
||||
|
||||
/**
|
||||
* Describes an event that a material design custom element can dispatch.
|
||||
*/
|
||||
export interface MdEventInfo {
|
||||
name: string;
|
||||
description?: string;
|
||||
type?: string;
|
||||
bubbles: boolean;
|
||||
composed: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* Describes a material design element's property
|
||||
*/
|
||||
export interface MdPropertyInfo {
|
||||
name: string;
|
||||
attribute?: string;
|
||||
description?: string;
|
||||
type?: string;
|
||||
privacy?: string;
|
||||
default?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Describes a material design element's method
|
||||
*/
|
||||
export interface MdMethodInfo {
|
||||
name: string;
|
||||
description?: string;
|
||||
privacy?: string;
|
||||
parameters: MdMethodParameterInfo[];
|
||||
returns?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Describes a material design element's method parameters
|
||||
*/
|
||||
export interface MdMethodParameterInfo {
|
||||
name: string;
|
||||
description?: string;
|
||||
type?: string;
|
||||
default?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Analyzes a material design custom element and its superclass chain and
|
||||
* formats the data into a Module info object that describes the Material web
|
||||
* custom element and its superclass chain with data useful for API
|
||||
* documentation.
|
||||
*
|
||||
* @param analyzer An instance of the lit analyzer for the material-web project
|
||||
* @param elementEntrypoint The entrypoint of the custom elemenr or superclass
|
||||
* to analyze.
|
||||
* @param superClassName (optional) The name of the superclass we are currently
|
||||
* analyzing.
|
||||
* @returns A Module info object that describes the Material web custom element
|
||||
* and its superclass chain with data useful for API documentation.
|
||||
*/
|
||||
export function analyzeElementApi(
|
||||
analyzer: Analyzer, elementEntrypoint: string, superClassName = '') {
|
||||
// The description of the module
|
||||
const elementModule = analyzer.getModule(elementEntrypoint as AbsolutePath);
|
||||
// The description of the custom element / superclass
|
||||
const customElementModule = elementModule.getCustomElementExports()[0] ||
|
||||
(elementModule.getDeclaration(superClassName) as LitElementDeclaration);
|
||||
|
||||
const {properties, reactiveProperties} =
|
||||
analyzeFields(customElementModule, elementModule);
|
||||
const methods = analyzeMethods(customElementModule);
|
||||
const events = analyzeEvents(customElementModule);
|
||||
const superclass = customElementModule.heritage.superClass;
|
||||
|
||||
const elementDocModule: MdModuleInfo = {
|
||||
customElementName: customElementModule.tagname,
|
||||
className: customElementModule.name,
|
||||
classPath: elementEntrypoint,
|
||||
summary: makeMarkdownFriendly(customElementModule.summary),
|
||||
description: makeMarkdownFriendly(customElementModule.description),
|
||||
properties,
|
||||
reactiveProperties,
|
||||
methods,
|
||||
events,
|
||||
};
|
||||
|
||||
// If there is no superclass or we've gotten to the LitElement superclass,
|
||||
// we're done. Stop analyzing. Otherwise, analyze the superclass.
|
||||
if (superclass !== undefined && superclass.name !== 'LitElement') {
|
||||
// Get the typescript source path of the superclass since we use js imports
|
||||
const superClassLocation = superclass.module.replace(/\.js$/, '.ts');
|
||||
const absolutePath = path.resolve(
|
||||
elementEntrypoint,
|
||||
path.relative(elementEntrypoint, superClassLocation));
|
||||
const superClassModule =
|
||||
analyzeElementApi(analyzer, absolutePath, superclass.name);
|
||||
elementDocModule.superClass = superClassModule;
|
||||
}
|
||||
|
||||
return elementDocModule;
|
||||
}
|
||||
|
||||
/**
|
||||
* These are fields we do not want to expose on the API docs.
|
||||
*/
|
||||
const FIELDS_TO_IGNORE = new Set(['isListItem', 'isMenuItem']);
|
||||
|
||||
/**
|
||||
* Analyzes the fields of a LitElement class and returns information about the
|
||||
* properties and reactive properties of the LitElement class in a format
|
||||
* useful for API documentation generation.
|
||||
*
|
||||
* @param classDeclaration The LitElement class declaration from which to
|
||||
* analyze and formatthe property fields.
|
||||
* @param module The analyzer module descriptor used to resolve default value
|
||||
* variable values.
|
||||
* @returns The information about the properties and reactive properties of the
|
||||
* LitElement class.
|
||||
*/
|
||||
export function analyzeFields(
|
||||
classDeclaration: LitElementExport|LitElementDeclaration, module: Module):
|
||||
{properties: MdPropertyInfo[]; reactiveProperties: MdPropertyInfo[];} {
|
||||
const properties: MdPropertyInfo[] = [];
|
||||
const reactiveProperties: MdPropertyInfo[] = [];
|
||||
|
||||
for (const field of classDeclaration.fields) {
|
||||
// skip certain fields and symbols
|
||||
if (FIELDS_TO_IGNORE.has(field.name) || field.name.includes('[')) {
|
||||
continue;
|
||||
}
|
||||
|
||||
const reactiveProp = classDeclaration.reactiveProperties.get(field.name);
|
||||
let defaultVal = field.default;
|
||||
|
||||
// Check the module and see if the default value is a variable declared in
|
||||
// the same file.
|
||||
if (module.declarations.find((dec) => dec.name === field.default)) {
|
||||
// Check if the default value is a variable declared in the same file.
|
||||
const variableDeclaration = module.getDeclaration(field.default);
|
||||
|
||||
if (variableDeclaration.isVariableDeclaration()) {
|
||||
const node =
|
||||
variableDeclaration.node as unknown as ts.VariableDeclaration;
|
||||
|
||||
// attempt to get the default value. If it's not a string, just use the
|
||||
// variable name.
|
||||
defaultVal = node.initializer?.getText() ?? defaultVal;
|
||||
}
|
||||
}
|
||||
|
||||
let attribute: string|undefined = undefined;
|
||||
let propertyArray = properties;
|
||||
|
||||
// If it is a reactive property, put it in the reactive properties array
|
||||
// and add the attribute name.
|
||||
if (reactiveProp) {
|
||||
propertyArray = reactiveProperties;
|
||||
// If the attribute is true, try to convert the name to an attribute.
|
||||
if (reactiveProp.attribute === true) {
|
||||
attribute = nameToAttribute(reactiveProp.name);
|
||||
// If it is a string, use that as the attribute name.
|
||||
} else if (reactiveProp.attribute !== false) {
|
||||
attribute = reactiveProp.attribute;
|
||||
}
|
||||
}
|
||||
|
||||
propertyArray.push({
|
||||
name: field.name,
|
||||
attribute,
|
||||
description: makeMarkdownFriendly(field.description),
|
||||
type: makeMarkdownFriendly(field.type.text),
|
||||
privacy: field.privacy,
|
||||
default: makeMarkdownFriendly(defaultVal),
|
||||
});
|
||||
}
|
||||
return {properties, reactiveProperties};
|
||||
}
|
||||
|
||||
/**
|
||||
* These are substrings that we do not want to convert to kebab case. For
|
||||
* example, we want to keep tabIndex as tabindex attribute and not convert it to
|
||||
* tab-index.
|
||||
*/
|
||||
const SUBSTRINGS_TO_NOT_KEBAB = new Set(['tabIndex']);
|
||||
|
||||
/**
|
||||
* Converts a snakeCase property name to a kebab-case attribute name.
|
||||
*
|
||||
* @param propertyName The snakeCase property name to convert to an attribute
|
||||
* @returns A kebab case attribute name.
|
||||
*/
|
||||
function nameToAttribute(propertyName: string) {
|
||||
for (const substring of SUBSTRINGS_TO_NOT_KEBAB) {
|
||||
propertyName.replace(substring, substring.toLowerCase());
|
||||
}
|
||||
|
||||
// Camel case to kebab case taken from Polymer source
|
||||
// https://github.com/Polymer/polymer/blob/1e8b246d01ea99adba305ea04c45d26da31f68f1/lib/utils/case-map.js#L45
|
||||
return propertyName.replace(/([A-Z])/g, '-$1').toLowerCase();
|
||||
}
|
||||
|
||||
/**
|
||||
* These are methods we do not want to expose on the API docs.
|
||||
*/
|
||||
const METHODS_TO_IGNORE = new Set([
|
||||
'attributeChangedCallback',
|
||||
'connectedCallback',
|
||||
'disconnectedCallback',
|
||||
'update',
|
||||
'render',
|
||||
'firstUpdated',
|
||||
'updated',
|
||||
'focus',
|
||||
'blur',
|
||||
]);
|
||||
|
||||
/**
|
||||
* Analyzes the methods of a LitElement class and returns information about the
|
||||
* methods of the LitElement class in a format useful for API documentation
|
||||
* generation.
|
||||
*
|
||||
* @param classDeclaration The LitElement class declaration from which to
|
||||
* analyze and format the method data.
|
||||
* @returns The information about the methods of the LitElement class.
|
||||
*/
|
||||
export function analyzeMethods(classDeclaration: LitElementExport|
|
||||
LitElementDeclaration) {
|
||||
const methods: MdMethodInfo[] = [];
|
||||
for (const method of classDeclaration.methods) {
|
||||
// Skip methods we decided to skip and symbols
|
||||
if (METHODS_TO_IGNORE.has(method.name) || method.name.includes('[')) {
|
||||
continue;
|
||||
}
|
||||
|
||||
methods.push({
|
||||
name: method.name,
|
||||
description: makeMarkdownFriendly(method.description),
|
||||
privacy: method.privacy,
|
||||
parameters: method.parameters.map(
|
||||
(parameter) => ({
|
||||
name: parameter.name,
|
||||
summary: makeMarkdownFriendly(parameter.summary),
|
||||
description: makeMarkdownFriendly(parameter.description),
|
||||
type: makeMarkdownFriendly(parameter.type.text),
|
||||
default: parameter.default,
|
||||
})),
|
||||
returns: makeMarkdownFriendly(method.return?.type.text),
|
||||
});
|
||||
}
|
||||
|
||||
return methods;
|
||||
}
|
||||
|
||||
/**
|
||||
* Analyzes the events dispatched by a LitElement class and returns information
|
||||
* about the events dispatched by the LitElement class in a format useful for
|
||||
* API documentation generation. NOTE if --buubbles or --composed is in the
|
||||
* event description, it will be removed from the description and the bubbles
|
||||
* and composed properties will be set to true.
|
||||
*
|
||||
* @param classDeclaration The LitElement class declaration from which to
|
||||
* analyze and format the event data.
|
||||
* @returns The information about the events dispatched by the LitElement class.
|
||||
*/
|
||||
export function analyzeEvents(classDeclaration: LitElementExport|
|
||||
LitElementDeclaration): MdEventInfo[] {
|
||||
const events: MdEventInfo[] = [];
|
||||
const eventsKeys = classDeclaration.events.keys();
|
||||
|
||||
for (const eventName of eventsKeys) {
|
||||
const event = classDeclaration.events.get(eventName);
|
||||
let description = event.description;
|
||||
const bubbles = description?.includes('--bubbles') || false;
|
||||
const composed = description?.includes('--composed') || false;
|
||||
|
||||
// Remove the --bubbles and --composed from the description
|
||||
description = description?.replace(/\s*\-\-bubbles\s*/g, '');
|
||||
description = description?.replace(/\s*\-\-composed\s*/g, '');
|
||||
description = makeMarkdownFriendly(description);
|
||||
|
||||
events.push({
|
||||
name: eventName,
|
||||
description,
|
||||
bubbles,
|
||||
composed,
|
||||
type: makeMarkdownFriendly(event?.type?.text),
|
||||
});
|
||||
}
|
||||
return events;
|
||||
}
|
||||
|
||||
/**
|
||||
* Attempts to make a string to be friendly to be inserted into a markdown
|
||||
* table. This includes replacing newlines with `<br>`, replacing | with \\| and
|
||||
* replacing multiple spaces with a single space.
|
||||
*
|
||||
* @param text The text to make markdown friendly.
|
||||
* @returns The text transformed to friendly to markdown tables, or undefined if
|
||||
* the text is undefined.
|
||||
*/
|
||||
export function makeMarkdownFriendly(text?: string) {
|
||||
if (!text) return undefined;
|
||||
|
||||
text = text.trim();
|
||||
// create a newline marker so i don't have to deal with regex flags
|
||||
text = text.replaceAll('\n', '<newline>');
|
||||
// keep double newlines
|
||||
text = text.replaceAll(/<newline>\s*<newline>/g, '<br>');
|
||||
// replace single newlines with a space
|
||||
text = text.replaceAll('<newline>', ' ');
|
||||
text = text.replaceAll('|', '\\|');
|
||||
text = text.replaceAll(/\s+/g, ' ');
|
||||
// remove any newly created newline spaces at the start and end
|
||||
text = text.trim();
|
||||
|
||||
return text;
|
||||
}
|
||||
50
scripts/analyzer/element-docs-map.ts
Normal file
50
scripts/analyzer/element-docs-map.ts
Normal file
@ -0,0 +1,50 @@
|
||||
/**
|
||||
* @license
|
||||
* Copyright 2023 Google LLC
|
||||
* SPDX-License-Identifier: Apache-2.0
|
||||
*/
|
||||
|
||||
/**
|
||||
* A map of Markdown documentation file name to element entrypoints associated
|
||||
* with that documentation.
|
||||
*/
|
||||
export const docsToElementMapping: {[key: string]: string[]} = {
|
||||
'button.md': [
|
||||
'button/elevated-button.ts',
|
||||
'button/filled-button.ts',
|
||||
'button/filled-tonal-button.ts',
|
||||
'button/outlined-button.ts',
|
||||
'button/text-button.ts',
|
||||
],
|
||||
'checkbox.md': ['checkbox/checkbox.ts'],
|
||||
'chip.md': [
|
||||
'chips/chip-set.ts',
|
||||
'chips/assist-chip.ts',
|
||||
'chips/filter-chip.ts',
|
||||
'chips/input-chip.ts',
|
||||
'chips/suggestion-chip.ts',
|
||||
],
|
||||
'dialog.md': ['dialog/dialog.ts'],
|
||||
'divider.md': ['divider/divider.ts'],
|
||||
'elevation.md': ['elevation/elevation.ts'],
|
||||
'fab.md': ['fab/fab.ts', 'fab/branded-fab.ts'],
|
||||
'focus-ring.md': ['focus/md-focus-ring.ts'],
|
||||
'icon-button.md': [
|
||||
'iconbutton/icon-button.ts',
|
||||
'iconbutton/filled-icon-button.ts',
|
||||
'iconbutton/filled-tonal-icon-button.ts',
|
||||
'iconbutton/outlined-icon-button.ts',
|
||||
],
|
||||
'icon.md': ['icon/icon.ts'],
|
||||
'list.md': ['list/list.ts', 'list/list-item.ts'],
|
||||
'menu.md': ['menu/menu.ts', 'menu/menu-item.ts', 'menu/sub-menu-item.ts'],
|
||||
'progress.md':
|
||||
['progress/linear-progress.ts', 'progress/circular-progress.ts'],
|
||||
'radio.md': ['radio/radio.ts'],
|
||||
'ripple.md': ['ripple/ripple.ts'],
|
||||
'slider.md': ['slider/slider.ts'],
|
||||
'switch.md': ['switch/switch.ts'],
|
||||
'tabs.md': ['tabs/tabs.ts', 'tabs/primary-tab.ts', 'tabs/secondary-tab.ts'],
|
||||
'text-field.md':
|
||||
['textfield/filled-text-field.ts', 'textfield/outlined-text-field.ts'],
|
||||
};
|
||||
67
scripts/analyzer/markdown-tree-builder.ts
Normal file
67
scripts/analyzer/markdown-tree-builder.ts
Normal file
@ -0,0 +1,67 @@
|
||||
/**
|
||||
* @license
|
||||
* Copyright 2023 Google LLC
|
||||
* SPDX-License-Identifier: Apache-2.0
|
||||
*/
|
||||
|
||||
/**
|
||||
* A class that represents a markown table as column titles and rows. The
|
||||
* `toString()` method outputs a markdown-compatible table.
|
||||
*/
|
||||
export class MarkdownTable {
|
||||
private readonly rowsInternal: string[][] = [];
|
||||
|
||||
/**
|
||||
* @param columnsInternal The column titles of the table.
|
||||
*/
|
||||
constructor(private readonly columnsInternal: string[]) {}
|
||||
|
||||
/**
|
||||
* The columns of the table.
|
||||
*/
|
||||
get columns() {
|
||||
return this.columnsInternal;
|
||||
}
|
||||
|
||||
/**
|
||||
* The rows of the table. (add rows with the `addRow()` method)
|
||||
*/
|
||||
get rows() {
|
||||
return this.rowsInternal;
|
||||
}
|
||||
|
||||
/**
|
||||
* Adds a row to the table. The row must be the same length as the number of
|
||||
* columns and be in order of the provided columns.
|
||||
*
|
||||
* @param row The row to add to the table. Must be the same length as the
|
||||
* number of columns.
|
||||
*/
|
||||
addRow(row: string[]) {
|
||||
if (row.length !== this.columnsInternal.length) {
|
||||
throw new Error(`Row length (${row.length}) must match column length (${
|
||||
this.columnsInternal.length})`);
|
||||
}
|
||||
|
||||
this.rowsInternal.push(row);
|
||||
}
|
||||
|
||||
/**
|
||||
* Generates a markdown-compatible table from the columns and rows provided.
|
||||
*
|
||||
* @returns A markdown-compatible table.
|
||||
*/
|
||||
toString() {
|
||||
const headerRow = this.columnsInternal.join(' | ');
|
||||
const dividerRow = this.columnsInternal.map(() => '---').join(' | ');
|
||||
const rows =
|
||||
this.rowsInternal.map((row) => `${row.join(' | ')}`).join('\n');
|
||||
return `<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||||
|
||||
${headerRow}
|
||||
${dividerRow}
|
||||
${rows}
|
||||
|
||||
<!-- mdformat on(autogenerated might break rendering in catalog) -->`;
|
||||
}
|
||||
}
|
||||
479
scripts/analyzer/update-docs.ts
Normal file
479
scripts/analyzer/update-docs.ts
Normal file
@ -0,0 +1,479 @@
|
||||
/**
|
||||
* @license
|
||||
* Copyright 2023 Google LLC
|
||||
* SPDX-License-Identifier: Apache-2.0
|
||||
*/
|
||||
|
||||
import {AbsolutePath, Analyzer, createPackageAnalyzer,} from '@lit-labs/analyzer/package-analyzer.js';
|
||||
import * as fs from 'fs/promises.js';
|
||||
import * as path from 'path';
|
||||
|
||||
import {analyzeElementApi, MdModuleInfo, MdPropertyInfo,} from './analyze-element.js';
|
||||
import {docsToElementMapping} from './element-docs-map.js';
|
||||
import {MarkdownTable} from './markdown-tree-builder.js';
|
||||
|
||||
type DocFileName = keyof typeof docsToElementMapping;
|
||||
|
||||
interface MarkdownTableSection {
|
||||
name: string;
|
||||
table: MarkdownTable;
|
||||
}
|
||||
|
||||
interface ElementTableSection {
|
||||
className: string;
|
||||
customElementName: string;
|
||||
summary: string;
|
||||
description: string;
|
||||
tables: Array<{name: string; table: MarkdownTable}>;
|
||||
}
|
||||
|
||||
/**
|
||||
* The main side-effect function of this module.
|
||||
*
|
||||
* It will analyze the element files in `element-docs-map.ts` and update the
|
||||
* markdown file's API section with the latest API information. It will replace
|
||||
* the code in between the `<!-- auto-generated API docs start -->` and
|
||||
* `<!-- auto-generated API docs end -->` comments.
|
||||
*/
|
||||
async function updateApiDocs() {
|
||||
const packagePath = path.resolve('.');
|
||||
// Analyzes the entire material-web repository.
|
||||
const analyzer = createPackageAnalyzer(packagePath as AbsolutePath);
|
||||
const documentationFileNames =
|
||||
Object.keys(docsToElementMapping) as DocFileName[];
|
||||
|
||||
const filesWritten: Array<Promise<void>> = [];
|
||||
|
||||
// Update all the documentation files in parallel
|
||||
for (const docFileName of documentationFileNames) {
|
||||
filesWritten.push(
|
||||
updateDocFileApiSection(docFileName, analyzer, packagePath));
|
||||
}
|
||||
|
||||
// Wait for all the files to be written
|
||||
await Promise.all(filesWritten);
|
||||
}
|
||||
|
||||
/**
|
||||
* Updates the API section of an individual documentation file with the latest
|
||||
* API information of the related elements in the `element-docs-map.ts` file.
|
||||
*
|
||||
* @param docFileName The name of the documentation file to update.
|
||||
* @param analyzer The instance of the package analyzer from which to pull
|
||||
* module information.
|
||||
* @param packagePath The path of the package root.
|
||||
*
|
||||
* @returns A promise that resolves when the file has been updated.
|
||||
*/
|
||||
async function updateDocFileApiSection(
|
||||
docFileName: DocFileName, analyzer: Analyzer, packagePath: string) {
|
||||
const elementEntrypoints = docsToElementMapping[docFileName];
|
||||
// This is a data structure that describes an element and its associated API
|
||||
// tables. e.g. a single section for MdFilledButton represents MdFilledButton
|
||||
// and it's associated Property, Methods, and Events tables.
|
||||
const elementTableSections: ElementTableSection[] = [];
|
||||
|
||||
for (const elementEntrypoint of elementEntrypoints) {
|
||||
elementTableSections.push(
|
||||
generateTableSection(elementEntrypoint, packagePath, analyzer));
|
||||
}
|
||||
|
||||
const documentationFileContents = await fs.readFile(
|
||||
path.resolve(packagePath, 'docs', 'components', docFileName));
|
||||
|
||||
const updatedFileContents = insertMarkdownTables(
|
||||
documentationFileContents.toString(), elementTableSections);
|
||||
|
||||
await fs.writeFile(
|
||||
path.resolve(packagePath, 'docs', 'components', docFileName),
|
||||
updatedFileContents);
|
||||
}
|
||||
|
||||
/**
|
||||
* Generates the API table section for a single element.
|
||||
*
|
||||
* @param elementEntrypoint The file path of where an element is defined.
|
||||
* @param packagePath The path of the package root.
|
||||
* @param analyzer An instance of the package analyzer from which to pull module
|
||||
* information.
|
||||
*
|
||||
* @returns The table section of an element. e.g. MdFilledButton's table section
|
||||
* would be the element class name, summary, description, and the API tables
|
||||
* associated with this element's section e.g. Properties, Methods, and Events.
|
||||
*/
|
||||
function generateTableSection(
|
||||
elementEntrypoint: string, packagePath: string,
|
||||
analyzer: Analyzer): ElementTableSection {
|
||||
const elementDoc =
|
||||
analyzeElementApi(analyzer, path.resolve(packagePath, elementEntrypoint));
|
||||
const tables: MarkdownTableSection[] = [];
|
||||
|
||||
const propertiesTable = generateFieldMarkdownTable(elementDoc);
|
||||
const methodsTable = generateMethodMarkdownTable(elementDoc);
|
||||
const eventsTable = generateEventsMarkdownTable(elementDoc);
|
||||
|
||||
if (propertiesTable.rows.length > 0) {
|
||||
tables.push({name: 'Properties', table: propertiesTable});
|
||||
}
|
||||
|
||||
if (methodsTable.rows.length > 0) {
|
||||
tables.push({name: 'Methods', table: methodsTable});
|
||||
}
|
||||
|
||||
if (eventsTable.rows.length > 0) {
|
||||
tables.push({name: 'Events', table: eventsTable});
|
||||
}
|
||||
|
||||
return {
|
||||
className: elementDoc.className,
|
||||
customElementName: elementDoc.customElementName || '',
|
||||
summary: elementDoc.summary ?? '',
|
||||
description: elementDoc.description ?? '',
|
||||
tables,
|
||||
};
|
||||
}
|
||||
|
||||
|
||||
|
||||
/**
|
||||
* Given an object that represents a row in a markdown table, and another object
|
||||
* that represents the same row in the table but for the superclass, this
|
||||
* function will update the subclass row with the values of the superclass row
|
||||
* if they are not defined in the subclass row.
|
||||
*
|
||||
* @param subclassRow The row object that will be updated with the values of the
|
||||
* superClassRow.
|
||||
* @param superClassRow The row object of the superclass that will be used to
|
||||
* update the subclassRow.
|
||||
* @returns The mutated subclass row object.
|
||||
*/
|
||||
function updateRow<T extends {[key: string]: unknown}>(
|
||||
subclassRow: T, superClassRow: T) {
|
||||
const keys = Object.keys(superClassRow) as Array<keyof T>;
|
||||
// update the row values if they are not defined
|
||||
for (const key of keys) {
|
||||
if (subclassRow[key] === undefined) {
|
||||
subclassRow[key] = superClassRow[key];
|
||||
}
|
||||
}
|
||||
|
||||
return subclassRow;
|
||||
}
|
||||
|
||||
/**
|
||||
* Generates a markdown table of all the public properties of an element.
|
||||
*
|
||||
* @param element The analyzed element documentation module from which to
|
||||
* generate the properties table.
|
||||
* @returns A Markdown table where the rows are thepubli properties of the
|
||||
* element. It is organized by inheritance order and with all reactive
|
||||
* properties listed first, then all other properties.
|
||||
*/
|
||||
function generateFieldMarkdownTable(element: MdModuleInfo): MarkdownTable {
|
||||
const propertiesTable = new MarkdownTable([
|
||||
'Property',
|
||||
'Attribute',
|
||||
'Type',
|
||||
'Default',
|
||||
'Description',
|
||||
]);
|
||||
const fieldNameOrder: string[] = [];
|
||||
const fieldToRow = new Map < string, {
|
||||
name: string;
|
||||
attribute?: string;
|
||||
type?: string;
|
||||
default:
|
||||
string;
|
||||
description?: string;
|
||||
}
|
||||
> ();
|
||||
|
||||
/**
|
||||
* Adds rows to the fieldToRow map and fieldNameOrder array but deduplicates
|
||||
* overriden fields and updates the info for the row only if it's not defined
|
||||
* in the subclass.
|
||||
*/
|
||||
const generateRow = (property: MdPropertyInfo) => {
|
||||
if (property.privacy !== 'public') {
|
||||
return;
|
||||
}
|
||||
|
||||
let defaultVal = property.default;
|
||||
if (defaultVal && property.default.includes('=>')) {
|
||||
defaultVal = 'function { ... }';
|
||||
}
|
||||
|
||||
const row = {
|
||||
name: property.name,
|
||||
attribute: property.attribute,
|
||||
type: property.type,
|
||||
default: defaultVal,
|
||||
description: property.description,
|
||||
};
|
||||
|
||||
const isPropertyInSubclass = fieldToRow.has(property.name);
|
||||
|
||||
if (isPropertyInSubclass) {
|
||||
const subclassRow = fieldToRow.get(property.name);
|
||||
updateRow(subclassRow, row);
|
||||
return;
|
||||
}
|
||||
|
||||
fieldToRow.set(property.name, row);
|
||||
fieldNameOrder.push(property.name);
|
||||
};
|
||||
|
||||
let currentClass = element;
|
||||
|
||||
// Append reactive properties first in inheritance order
|
||||
while (currentClass) {
|
||||
for (const property of currentClass.reactiveProperties) {
|
||||
generateRow(property);
|
||||
}
|
||||
|
||||
currentClass = currentClass.superClass;
|
||||
}
|
||||
|
||||
// Reset and append the non-reactive properties in inheritance order.
|
||||
currentClass = element;
|
||||
|
||||
while (currentClass) {
|
||||
for (const property of currentClass.properties) {
|
||||
generateRow(property);
|
||||
}
|
||||
|
||||
currentClass = currentClass.superClass;
|
||||
}
|
||||
|
||||
for (const property of fieldNameOrder) {
|
||||
const rowObj = fieldToRow.get(property);
|
||||
propertiesTable.addRow([
|
||||
`\`${rowObj.name}\``,
|
||||
rowObj.attribute ? `\`${rowObj.attribute}\`` : '',
|
||||
rowObj.type ? `\`${rowObj.type}\`` : '',
|
||||
`\`${rowObj.default}\``,
|
||||
rowObj.description ?? '',
|
||||
]);
|
||||
}
|
||||
|
||||
return propertiesTable;
|
||||
}
|
||||
|
||||
/**
|
||||
* Generates a markdown table of all the public methods of an element.
|
||||
*
|
||||
* @param element The analyzed element documentation module from which to
|
||||
* generate the methods table.
|
||||
* @returns A Markdown table where the rows are the public methods of the
|
||||
* element.
|
||||
*/
|
||||
function generateMethodMarkdownTable(element: MdModuleInfo): MarkdownTable {
|
||||
const methodsTable = new MarkdownTable([
|
||||
'Method',
|
||||
'Parameters',
|
||||
'Returns',
|
||||
'Description',
|
||||
]);
|
||||
const methodNameOrder: string[] = [];
|
||||
const methodToRow = new Map < string, {
|
||||
name: string;
|
||||
parameters: MdMethodParameterInfo[];
|
||||
returns?: string;
|
||||
description?: string;
|
||||
}
|
||||
> ();
|
||||
|
||||
let currentClass = element;
|
||||
while (currentClass) {
|
||||
for (const method of currentClass.methods) {
|
||||
if (method.privacy !== 'public') {
|
||||
continue;
|
||||
}
|
||||
|
||||
const row = {
|
||||
name: method.name,
|
||||
parameters: method.parameters,
|
||||
returns: method.returns,
|
||||
description: method.description,
|
||||
};
|
||||
|
||||
const isMethodInSubclass = methodToRow.has(method.name);
|
||||
|
||||
if (isMethodInSubclass) {
|
||||
const subclassRow = methodToRow.get(method.name);
|
||||
updateRow(subclassRow, row);
|
||||
continue;
|
||||
}
|
||||
|
||||
methodToRow.set(method.name, row);
|
||||
methodNameOrder.push(method.name);
|
||||
}
|
||||
|
||||
currentClass = currentClass.superClass;
|
||||
}
|
||||
|
||||
for (const methodName of methodNameOrder) {
|
||||
const rowObj = methodToRow.get(methodName);
|
||||
methodsTable.addRow([
|
||||
`\`${rowObj.name}\``,
|
||||
rowObj.parameters.map((p) => `\`${p.name}\``).join(', ') || '_None_',
|
||||
`\`${rowObj.returns}\`` ?? '`void`',
|
||||
rowObj.description ?? '',
|
||||
]);
|
||||
}
|
||||
|
||||
return methodsTable;
|
||||
}
|
||||
|
||||
/**
|
||||
* Generates a markdown table of all the __documented__ events of an element.
|
||||
*
|
||||
* @param element The analyzed element documentation module from which to
|
||||
* generate the events table.
|
||||
* @returns A Markdown table where the rows are the events of the element.
|
||||
*/
|
||||
function generateEventsMarkdownTable(element: MdModuleInfo): MarkdownTable {
|
||||
const eventsTable = new MarkdownTable([
|
||||
'Event',
|
||||
// TODO reenable these once we update our docs to support them
|
||||
// 'Type',
|
||||
// 'Bubbles',
|
||||
// 'Composed',
|
||||
'Description',
|
||||
]);
|
||||
const eventNameOrder: string[] = [];
|
||||
const eventToRow = new Map < string, {
|
||||
name: string;
|
||||
// TODO reenable these once we update our docs to support them
|
||||
// type?: string;
|
||||
// bubbles: boolean;
|
||||
// composed: boolean;
|
||||
description?: string;
|
||||
}
|
||||
> ();
|
||||
|
||||
let currentClass = element;
|
||||
|
||||
while (currentClass) {
|
||||
for (const event of currentClass.events) {
|
||||
const row = {
|
||||
name: event.name,
|
||||
// TODO reenable these once we update our docs to support them
|
||||
// type: event.type,
|
||||
// bubbles: event.bubbles,
|
||||
// composed: event.composed,
|
||||
description: event.description,
|
||||
};
|
||||
|
||||
const isEventInSubclass = eventToRow.has(event.name);
|
||||
|
||||
if (isEventInSubclass) {
|
||||
const subclassRow = eventToRow.get(event.name);
|
||||
updateRow(subclassRow, row);
|
||||
continue;
|
||||
}
|
||||
|
||||
eventToRow.set(event.name, row);
|
||||
eventNameOrder.push(event.name);
|
||||
}
|
||||
|
||||
currentClass = currentClass.superClass;
|
||||
}
|
||||
|
||||
for (const eventName of eventNameOrder) {
|
||||
const rowObj = eventToRow.get(eventName);
|
||||
eventsTable.addRow([
|
||||
`\`${rowObj.name}\``,
|
||||
// TODO reenable these once we update our docs to support them
|
||||
// `\`${rowObj.type}\`` ?? '',
|
||||
// rowObj.bubbles ? 'Yes' : 'No',
|
||||
// rowObj.composed ? 'Yes' : 'No',
|
||||
rowObj.description ?? '',
|
||||
]);
|
||||
}
|
||||
|
||||
return eventsTable;
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns the updated documentation file contents with the API section filled
|
||||
* with the _Markdownified_ API table sections.
|
||||
*
|
||||
* @param fileContents The stringified contents of a documentation file.
|
||||
* @param elementTableSections An array of elements and their associated
|
||||
* API tables to insert into the documentation file.
|
||||
* @returns The updated documentation file contents with the API section.
|
||||
*/
|
||||
function insertMarkdownTables(
|
||||
fileContents: string, elementTableSections: ElementTableSection[]) {
|
||||
// A file that has no tables to insert should have its API section cleared.
|
||||
const hasContent = elementTableSections.reduce((hasContent, element) => {
|
||||
return hasContent || element.tables.length > 0;
|
||||
}, false);
|
||||
|
||||
// If there is no content, clear the api section.
|
||||
if (!hasContent) {
|
||||
return replaceFileContents(fileContents);
|
||||
}
|
||||
|
||||
const tablesStrings = stringifyMarkdownTableSections(elementTableSections);
|
||||
|
||||
return replaceFileContents(fileContents, tablesStrings);
|
||||
}
|
||||
|
||||
/**
|
||||
* Replaces the fileContents' API section with the provided tablesStrings. If
|
||||
* tablesStrings is not provided, the API section will be cleared.
|
||||
*
|
||||
* @param fileContents The stringified contents of a documentation file.
|
||||
* @param tablesStrings The stringified markdown tables to insert into the
|
||||
* documentation file. If not provided, the API section will be cleared.
|
||||
* @returns The updated documentation file contents with the API section.
|
||||
*/
|
||||
function replaceFileContents(fileContents: string, tablesStrings?: string) {
|
||||
const injectionPointRegex =
|
||||
/<!-- auto-generated API docs start -->.*<!-- auto-generated API docs end -->/s;
|
||||
|
||||
if (!tablesStrings) {
|
||||
return fileContents.replace(
|
||||
injectionPointRegex, `<!-- auto-generated API docs start -->
|
||||
<!-- auto-generated API docs end -->`);
|
||||
}
|
||||
|
||||
return fileContents.replace(
|
||||
injectionPointRegex, `<!-- auto-generated API docs start -->
|
||||
|
||||
## API
|
||||
|
||||
${tablesStrings}
|
||||
<!-- auto-generated API docs end -->`);
|
||||
}
|
||||
|
||||
/**
|
||||
* Stringifies the markdown table sections of all the elements and their
|
||||
* associated API tables in markdown.
|
||||
*
|
||||
* @param elements The element classes and their associated API tables to
|
||||
* stringify into markdown.
|
||||
* @returns A stringified markdown table section of all the elements and their
|
||||
* associated API tables.
|
||||
*/
|
||||
function stringifyMarkdownTableSections(elements: ElementTableSection[]) {
|
||||
let tablesStrings = '';
|
||||
|
||||
for (const element of elements) {
|
||||
const {className, tables, customElementName} = element;
|
||||
tablesStrings += `
|
||||
### ${className}${customElementName ? ` <${customElementName}>` : ''}
|
||||
${tables.map(({name, table}) => `
|
||||
#### ${name}
|
||||
|
||||
${table.toString()}
|
||||
`).join('')}`;
|
||||
}
|
||||
|
||||
return tablesStrings;
|
||||
}
|
||||
|
||||
// Run the main script
|
||||
await updateApiDocs();
|
||||
14
scripts/tsconfig.json
Normal file
14
scripts/tsconfig.json
Normal file
@ -0,0 +1,14 @@
|
||||
{
|
||||
"extends": "../tsconfig.json",
|
||||
"compilerOptions": {
|
||||
"types": ["node"],
|
||||
"allowSyntheticDefaultImports": true,
|
||||
"target": "ES2022",
|
||||
"module": "ES2022"
|
||||
},
|
||||
"exclude": [
|
||||
"catalog",
|
||||
"**/demo"
|
||||
],
|
||||
"include": ["**/*"]
|
||||
}
|
||||
@ -28,6 +28,7 @@
|
||||
},
|
||||
"exclude": [
|
||||
"catalog",
|
||||
"**/demo"
|
||||
"**/demo",
|
||||
"scripts/"
|
||||
]
|
||||
}
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user