js/webawesome
1
0
Fork 0
mirror of https://github.com/shoelace-style/webawesome.git synced 2026-01-12 12:09:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

improve documentation

Browse Source
This commit is contained in:
Cory LaViska
2022-12-06 11:18:14 -05:00
parent 2dd57956d5
commit f2efa73e20
62 changed files with 553 additions and 475 deletions
Download Patch File Download Diff File Expand all files Collapse all files

60
docs/components/button-group.md
View File

@@ -3,7 +3,7 @@
[component-header:sl-button-group]
```html preview
<sl-button-group>
<sl-button-group label="Alignment">
<sl-button>Left</sl-button>
<sl-button>Center</sl-button>
<sl-button>Right</sl-button>
@@ -14,7 +14,7 @@
import { SlButton, SlButtonGroup } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlButtonGroup>
<SlButtonGroup label="Alignment">
<SlButton>Left</SlButton>
<SlButton>Center</SlButton>
<SlButton>Right</SlButton>
@@ -29,7 +29,7 @@ const App = () => (
All button sizes are supported, but avoid mixing sizes within the same button group.
```html preview
<sl-button-group>
<sl-button-group label="Alignment">
<sl-button size="small">Left</sl-button>
<sl-button size="small">Center</sl-button>
<sl-button size="small">Right</sl-button>
@@ -37,7 +37,7 @@ All button sizes are supported, but avoid mixing sizes within the same button gr
<br /><br />
<sl-button-group>
<sl-button-group label="Alignment">
<sl-button size="medium">Left</sl-button>
<sl-button size="medium">Center</sl-button>
<sl-button size="medium">Right</sl-button>
@@ -45,7 +45,7 @@ All button sizes are supported, but avoid mixing sizes within the same button gr
<br /><br />
<sl-button-group>
<sl-button-group label="Alignment">
<sl-button size="large">Left</sl-button>
<sl-button size="large">Center</sl-button>
<sl-button size="large">Right</sl-button>
@@ -57,7 +57,7 @@ import { SlButton, SlButtonGroup } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlButtonGroup>
<SlButtonGroup label="Alignment">
<SlButton size="small">Left</SlButton>
<SlButton size="small">Center</SlButton>
<SlButton size="small">Right</SlButton>
@@ -66,7 +66,7 @@ const App = () => (
<br />
<br />
<SlButtonGroup>
<SlButtonGroup label="Alignment">
<SlButton size="medium">Left</SlButton>
<SlButton size="medium">Center</SlButton>
<SlButton size="medium">Right</SlButton>
@@ -75,7 +75,7 @@ const App = () => (
<br />
<br />
<SlButtonGroup>
<SlButtonGroup label="Alignment">
<SlButton size="large">Left</SlButton>
<SlButton size="large">Center</SlButton>
<SlButton size="large">Right</SlButton>
@@ -89,7 +89,7 @@ const App = () => (
Theme buttons are supported through the button's `variant` attribute.
```html preview
<sl-button-group>
<sl-button-group label="Alignment">
<sl-button variant="primary">Left</sl-button>
<sl-button variant="primary">Center</sl-button>
<sl-button variant="primary">Right</sl-button>
@@ -97,7 +97,7 @@ Theme buttons are supported through the button's `variant` attribute.
<br /><br />
<sl-button-group>
<sl-button-group label="Alignment">
<sl-button variant="success">Left</sl-button>
<sl-button variant="success">Center</sl-button>
<sl-button variant="success">Right</sl-button>
@@ -105,7 +105,7 @@ Theme buttons are supported through the button's `variant` attribute.
<br /><br />
<sl-button-group>
<sl-button-group label="Alignment">
<sl-button variant="neutral">Left</sl-button>
<sl-button variant="neutral">Center</sl-button>
<sl-button variant="neutral">Right</sl-button>
@@ -113,7 +113,7 @@ Theme buttons are supported through the button's `variant` attribute.
<br /><br />
<sl-button-group>
<sl-button-group label="Alignment">
<sl-button variant="warning">Left</sl-button>
<sl-button variant="warning">Center</sl-button>
<sl-button variant="warning">Right</sl-button>
@@ -121,7 +121,7 @@ Theme buttons are supported through the button's `variant` attribute.
<br /><br />
<sl-button-group>
<sl-button-group label="Alignment">
<sl-button variant="danger">Left</sl-button>
<sl-button variant="danger">Center</sl-button>
<sl-button variant="danger">Right</sl-button>
@@ -133,7 +133,7 @@ import { SlButton, SlButtonGroup } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlButtonGroup>
<SlButtonGroup label="Alignment">
<SlButton variant="primary">Left</SlButton>
<SlButton variant="primary">Center</SlButton>
<SlButton variant="primary">Right</SlButton>
@@ -142,7 +142,7 @@ const App = () => (
<br />
<br />
<SlButtonGroup>
<SlButtonGroup label="Alignment">
<SlButton variant="success">Left</SlButton>
<SlButton variant="success">Center</SlButton>
<SlButton variant="success">Right</SlButton>
@@ -151,7 +151,7 @@ const App = () => (
<br />
<br />
<SlButtonGroup>
<SlButtonGroup label="Alignment">
<SlButton variant="neutral">Left</SlButton>
<SlButton variant="neutral">Center</SlButton>
<SlButton variant="neutral">Right</SlButton>
@@ -160,7 +160,7 @@ const App = () => (
<br />
<br />
<SlButtonGroup>
<SlButtonGroup label="Alignment">
<SlButton variant="warning">Left</SlButton>
<SlButton variant="warning">Center</SlButton>
<SlButton variant="warning">Right</SlButton>
@@ -169,7 +169,7 @@ const App = () => (
<br />
<br />
<SlButtonGroup>
<SlButtonGroup label="Alignment">
<SlButton variant="danger">Left</SlButton>
<SlButton variant="danger">Center</SlButton>
<SlButton variant="danger">Right</SlButton>
@@ -183,7 +183,7 @@ const App = () => (
Pill buttons are supported through the button's `pill` attribute.
```html preview
<sl-button-group>
<sl-button-group label="Alignment">
<sl-button size="small" pill>Left</sl-button>
<sl-button size="small" pill>Center</sl-button>
<sl-button size="small" pill>Right</sl-button>
@@ -191,7 +191,7 @@ Pill buttons are supported through the button's `pill` attribute.
<br /><br />
<sl-button-group>
<sl-button-group label="Alignment">
<sl-button size="medium" pill>Left</sl-button>
<sl-button size="medium" pill>Center</sl-button>
<sl-button size="medium" pill>Right</sl-button>
@@ -199,7 +199,7 @@ Pill buttons are supported through the button's `pill` attribute.
<br /><br />
<sl-button-group>
<sl-button-group label="Alignment">
<sl-button size="large" pill>Left</sl-button>
<sl-button size="large" pill>Center</sl-button>
<sl-button size="large" pill>Right</sl-button>
@@ -211,7 +211,7 @@ import { SlButton, SlButtonGroup } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlButtonGroup>
<SlButtonGroup label="Alignment">
<SlButton size="small" pill>
Left
</SlButton>
@@ -226,7 +226,7 @@ const App = () => (
<br />
<br />
<SlButtonGroup>
<SlButtonGroup label="Alignment">
<SlButton size="medium" pill>
Left
</SlButton>
@@ -241,7 +241,7 @@ const App = () => (
<br />
<br />
<SlButtonGroup>
<SlButtonGroup label="Alignment">
<SlButton size="large" pill>
Left
</SlButton>
@@ -261,7 +261,7 @@ const App = () => (
Dropdowns can be placed inside button groups as long as the trigger is an `<sl-button>` element.
```html preview
<sl-button-group>
<sl-button-group label="Example Button Group">
<sl-button>Button</sl-button>
<sl-button>Button</sl-button>
<sl-dropdown>
@@ -279,7 +279,7 @@ Dropdowns can be placed inside button groups as long as the trigger is an `<sl-b
import { SlButton, SlButtonGroup, SlDropdown, SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlButtonGroup>
<SlButtonGroup label="Example Button Group">
<SlButton>Button</SlButton>
<SlButton>Button</SlButton>
<SlDropdown>
@@ -301,7 +301,7 @@ const App = () => (
Create a split button using a button and a dropdown. Use a [visually hidden](/components/visually-hidden) label to ensure the dropdown is accessible to users with assistive devices.
```html preview
<sl-button-group>
<sl-button-group label="Example Button Group">
<sl-button variant="primary">Save</sl-button>
<sl-dropdown placement="bottom-end">
<sl-button slot="trigger" variant="primary" caret>
@@ -320,7 +320,7 @@ Create a split button using a button and a dropdown. Use a [visually hidden](/co
import { SlButton, SlButtonGroup, SlDropdown, SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlButtonGroup>
<SlButtonGroup label="Example Button Group">
<SlButton variant="primary">Save</SlButton>
<SlDropdown placement="bottom-end">
<SlButton slot="trigger" variant="primary" caret></SlButton>
@@ -339,7 +339,7 @@ const App = () => (
Buttons can be wrapped in tooltips to provide more detail when the user interacts with them.
```html preview
<sl-button-group>
<sl-button-group label="Alignment">
<sl-tooltip content="I'm on the left">
<sl-button>Left</sl-button>
</sl-tooltip>
@@ -359,7 +359,7 @@ import { SlButton, SlButtonGroup, SlTooltip } from '@shoelace-style/shoelace/dis
const App = () => (
<>
<SlButtonGroup>
<SlButtonGroup label="Alignment">
<SlTooltip content="I'm on the left">
<SlButton>Left</SlButton>
</SlTooltip>

2
docs/components/button.md
View File

@@ -134,7 +134,7 @@ const App = () => (
### Circle Buttons
Use the `circle` attribute to create circular icon buttons.
Use the `circle` attribute to create circular icon buttons. When this attribute is set, the button expects a single `<sl-icon>` in the default slot.
```html preview
<sl-button variant="default" size="small" circle>

2
docs/components/popup.md
View File

@@ -6,7 +6,7 @@ This component's name is inspired by [`<popup>`](https://github.com/MicrosoftEdg
Popup doesn't provide any styles — just positioning! The popup's preferred placement, distance, and skidding (offset) can be configured using attributes. An arrow that points to the anchor can be shown and customized to your liking. Additional positioning options are available and described in more detail below.
!> Popup is a low-level utility built specifically for positioning elements. Do not mistake it for a [tooltip](/components/tooltip) or similar because _it does not facilitate an accessible experience!_ Almost every correct usage of `<sl-popup>` will involve building other components. It should rarely, if ever, occur in your own HTML.
!> Popup is a low-level utility built specifically for positioning elements. Do not mistake it for a [tooltip](/components/tooltip) or similar because _it does not facilitate an accessible experience!_ Almost every correct usage of `<sl-popup>` will involve building other components. It should rarely, if ever, occur directly in your HTML.
```html preview
<div class="popup-overview">

4
docs/components/visually-hidden.md
View File

@@ -7,7 +7,7 @@ According to [The A11Y Project](https://www.a11yproject.com/posts/2013-01-11-how
Since visually hidden content can receive focus when tabbing, the element will become visible when something inside receives focus. This behavior is intentional, as sighted keyboards user won't be able to determine where the focus indicator is without it.
```html preview
<div style="min-height: 100px;">
<div style="min-height: 1.875rem;">
<sl-visually-hidden>
<a href="#">Skip to main content</a>
</sl-visually-hidden>
@@ -30,7 +30,7 @@ In this example, the link will open a new window. Screen readers will announce "
### Content Conveyed By Context
Adding a title or label may seem redundant at times, but they're very helpful for unsighted users. Rather than omit them, you can provide context to unsighted users with visually hidden content.
Adding a label may seem redundant at times, but they're very helpful for unsighted users. Rather than omit them, you can provide context to unsighted users with visually hidden content that will be announced by assistive devices such as screen readers.
```html preview
<sl-card style="width: 100%; max-width: 360px;">

4
docs/getting-started/usage.md
View File

@@ -4,7 +4,7 @@ Shoelace components are just regular HTML elements, or [custom elements](https:/
If you're new to custom elements, often referred to as "web components," this section will familiarize you with how to use them.
## Properties
## Attributes & Properties
Many components have properties that can be set using attributes. For example, buttons accept a `size` attribute that maps to the `size` property which dictates the button's size.
@@ -18,7 +18,7 @@ Some properties are boolean, so they only have true/false values. To activate a
<sl-button disabled>Click me</sl-button>
```
In rare cases, a property may require an array, an object, or a function. For example, to customize the color picker's list of preset swatches, you set the `swatches` property to an array of colors. This can be done with JavaScript.
In rare cases, a property may require an array, an object, or a function. For example, to customize the color picker's list of preset swatches, you set the `swatches` property to an array of colors. This must be done with JavaScript.
```html
<sl-color-picker></sl-color-picker>

5
docs/resources/changelog.md
View File

@@ -10,10 +10,14 @@ New versions of Shoelace are released as-needed and generally occur when a criti
## Next
- 🚨 BREAKING: changed the default value of `date` in `<sl-relative-time>` to the current date instead of the Unix epoch
- 🚨 BREAKING: removed the `handle-icon` part and slot from `<sl-image-comparer>` (use `handle` instead)
- 🚨 BREAKING: removed the `handle` slot from `<sl-split-panel>` (use the `divider` slot instead)
- 🚨 BREAKING: removed the `--box-shadow` custom property from `<sl-alert>` (apply a box shadow to `::part(base)` instead)
- 🚨 BREAKING: removed the `play-icon` and `pause-icon` parts (use the `play-icon` and `pause-icon` slots instead)
- Added `header-actions` slot to `<sl-dialog>` and `<sl-drawer>`
- Added the `expand-icon` and `collapse-icon` slots to `<sl-details>` and refactored the icon animation [#1046](https://github.com/shoelace-style/shoelace/discussions/1046)
- Added the `play-icon` and `pause-icon` slots to `<sl-animated-image>` so you can customize the default icons
- Fixed a bug in `<sl-tree-item>` where `sl-selection-change` was emitted when the selection didn't change [#1030](https://github.com/shoelace-style/shoelace/pull/1030)
- Fixed a bug in `<sl-button-group>` that caused the border to render incorrectly when hovering over icons inside buttons [#1035](https://github.com/shoelace-style/shoelace/issues/1035)
- Fixed an incorrect default for `flip-fallback-strategy` in `<sl-popup>` that caused the fallback strategy to be `initial` instead of `best-fit`, which is inconsistent with Floating UI's default [#1036](https://github.com/shoelace-style/shoelace/issues/1036)
@@ -24,6 +28,7 @@ New versions of Shoelace are released as-needed and generally occur when a criti
- Fixed the border radius in `<sl-dropdown>` so it matches with nested `<sl-menu>` elements
- Improved IntelliSense in VS Code, courtesy of [Burton's amazing CEM Analyzer plugin](https://github.com/break-stuff/cem-plugin-vs-code-custom-data-generator)
- Improved accessibility of `<sl-alert>` so the alert is announced and the close button has a label
- Improved accessibility of `<sl-progress-ring>` so slotted labels are announced along with visually hidden labels
- Refactored all styles and animations to use `translate`, `rotate`, and `scale` instead of `transform`
- Removed slot wrappers from many components, allowing better control over user-applied styles
- Removed unused aria attributes from `<sl-skeleton>`

2
scripts/plop/templates/component/component.hbs
View File

@@ -19,7 +19,7 @@ import type { CSSResultGroup } from 'lit';
* @slot - The default slot.
* @slot example - An example slot.
*
* @csspart base - The component's internal wrapper.
* @csspart base - The component's base wrapper.
*
* @cssproperty --example - An example CSS custom property.
*/

1
src/components/alert/alert.styles.ts
View File

@@ -19,7 +19,6 @@ export default css`
border: solid var(--sl-panel-border-width) var(--sl-panel-border-color);
border-top-width: calc(var(--sl-panel-border-width) * 3);
border-radius: var(--sl-border-radius-medium);
box-shadow: var(--box-shadow);
font-family: var(--sl-font-sans);
font-size: var(--sl-font-size-small);
font-weight: var(--sl-font-weight-normal);

28
src/components/alert/alert.ts
View File

@@ -22,21 +22,19 @@ const toastStack = Object.assign(document.createElement('div'), { className: 'sl
*
* @dependency sl-icon-button
*
* @slot - The alert's content.
* @slot icon - An icon to show in the alert.
* @slot - The alert's main content.
* @slot icon - An icon to show in the alert. Works best with `<sl-icon>`.
*
* @event sl-show - Emitted when the alert opens.
* @event sl-after-show - Emitted after the alert opens and all animations are complete.
* @event sl-hide - Emitted when the alert closes.
* @event sl-after-hide - Emitted after the alert closes and all animations are complete.
*
* @csspart base - The component's internal wrapper.
* @csspart icon - The container that wraps the alert icon.
* @csspart message - The alert message.
* @csspart close-button - The close button.
* @csspart close-button__base - The close button's `base` part.
*
* @cssproperty --box-shadow - The alert's box shadow.
* @csspart base - The component's base wrapper.
* @csspart icon - The container that wraps the optional icon.
* @csspart message - The container that wraps the alert's main content.
* @csspart close-button - The close button, an `<sl-icon-button>`.
* @csspart close-button__base - The close button's exported `base` part.
*
* @animation alert.show - The animation to use when showing the alert.
* @animation alert.hide - The animation to use when hiding the alert.
@@ -52,18 +50,22 @@ export default class SlAlert extends ShoelaceElement {
@query('[part~="base"]') base: HTMLElement;
/** Indicates whether or not the alert is open. You can use this in lieu of the show/hide methods. */
/**
* Indicates whether or not the alert is open. You can toggle this attribute to show and hide the alert, or you can
* use the `show()` and `hide()` methods and this attribute will reflect the alert's open state.
*/
@property({ type: Boolean, reflect: true }) open = false;
/** Makes the alert closable. */
/** Enables a close button that allows the user to dismiss the alert. */
@property({ type: Boolean, reflect: true }) closable = false;
/** The alert's variant. */
/** The alert's theme variant. */
@property({ reflect: true }) variant: 'primary' | 'success' | 'neutral' | 'warning' | 'danger' = 'primary';
/**
* The length of time, in milliseconds, the alert will show before closing itself. If the user interacts with
* the alert before it closes (e.g. moves the mouse over it), the timer will restart. Defaults to `Infinity`.
* the alert before it closes (e.g. moves the mouse over it), the timer will restart. Defaults to `Infinity`, meaning
* the alert will not close on its own.
*/
@property({ type: Number }) duration = Infinity;

6
src/components/animated-image/animated-image.styles.ts
View File

@@ -7,6 +7,7 @@ export default css`
:host {
--control-box-size: 3rem;
--icon-size: calc(var(--control-box-size) * 0.625);
display: inline-flex;
position: relative;
cursor: pointer;
@@ -48,4 +49,9 @@ export default css`
:host([play]:not(:hover)) .animated-image__control-box {
opacity: 0;
}
:host([play]) slot[name='pause-icon'],
:host(:not([play])) slot[name='play-icon'] {
display: none;
}
`;

16
src/components/animated-image/animated-image.ts
View File

@@ -17,9 +17,10 @@ import type { CSSResultGroup } from 'lit';
* @event sl-load - Emitted when the image loads successfully.
* @event sl-error - Emitted when the image fails to load.
*
* @slot play-icon - Optional play icon to use instead of the default. Works best with `<sl-icon>`.
* @slot pause-icon - Optional pause icon to use instead of the default. Works best with `<sl-icon>`.
*
* @part - control-box - The container that surrounds the pause/play icons and provides their background.
* @part - play-icon - The icon to use for the play button.
* @part - pause-icon - The icon to use for the pause button.
*
* @cssproperty --control-box-size - The size of the icon box.
* @cssproperty --icon-size - The size of the play/pause icons.
@@ -33,13 +34,13 @@ export default class SlAnimatedImage extends ShoelaceElement {
@query('.animated-image__animated') animatedImage: HTMLImageElement;
/** The image's src attribute. */
/** The path to the image to load. */
@property() src: string;
/** The image's alt attribute. */
/** A description of the image used by assistive devices. */
@property() alt: string;
/** When set, the image will animate. Otherwise, it will be paused. */
/** Plays the animation. When this attribute is remove, the animation will pause. */
@property({ type: Boolean, reflect: true }) play: boolean;
handleClick() {
@@ -104,9 +105,8 @@ export default class SlAnimatedImage extends ShoelaceElement {
/>
<div part="control-box" class="animated-image__control-box">
${this.play
? html`<sl-icon part="pause-icon" name="pause-fill" library="system"></sl-icon>`
: html`<sl-icon part="play-icon" name="play-fill" library="system"></sl-icon>`}
<slot name="play-icon"><sl-icon name="play-fill" library="system"></sl-icon></slot>
<slot name="pause-icon"><sl-icon name="pause-fill" library="system"></sl-icon></slot>
</div>
`
: ''}

11
src/components/animation/animation.ts
View File

@@ -16,8 +16,8 @@ import type { CSSResultGroup } from 'lit';
* @event sl-finish - Emitted when the animation finishes.
* @event sl-start - Emitted when the animation starts or restarts.
*
* @slot - The element to animate. If multiple elements are to be animated, wrap them in a single container or use
* multiple animation elements.
* @slot - The element to animate. Avoid slotting in more than one element, as subsequent ones will be ignored. To
* animate multiple elements, either wrap them in a single container or use multiple `<sl-animation>` elements.
*/
@customElement('sl-animation')
export default class SlAnimation extends ShoelaceElement {
@@ -40,7 +40,10 @@ export default class SlAnimation extends ShoelaceElement {
/** The number of milliseconds to delay the start of the animation. */
@property({ type: Number }) delay = 0;
/** Determines the direction of playback as well as the behavior when reaching the end of an iteration. */
/**
* Determines the direction of playback as well as the behavior when reaching the end of an iteration.
* [Learn more](https://developer.mozilla.org/en-US/docs/Web/CSS/animation-direction)
*/
@property() direction: PlaybackDirection = 'normal';
/** The number of milliseconds each iteration of the animation takes to complete. */
@@ -202,7 +205,7 @@ export default class SlAnimation extends ShoelaceElement {
}
}
/** Clears all KeyframeEffects caused by this animation and aborts its playback. */
/** Clears all keyframe effects caused by this animation and aborts its playback. */
cancel() {
this.animation?.cancel();
}

10
src/components/avatar/avatar.ts
View File

@@ -15,12 +15,12 @@ import type { CSSResultGroup } from 'lit';
*
* @dependency sl-icon
*
* @slot icon - The default icon to use when no image or initials are present.
* @slot icon - The default icon to use when no image or initials are present. Works best with `<sl-icon>`.
*
* @csspart base - The component's internal wrapper.
* @csspart icon - The container that wraps the avatar icon.
* @csspart initials - The container that wraps the avatar initials.
* @csspart image - The avatar image.
* @csspart base - The component's base wrapper.
* @csspart icon - The container that wraps the avatar's icon.
* @csspart initials - The container that wraps the avatar's initials.
* @csspart image - The avatar image. Only shown when the `image` attribute is set.
*
* @cssproperty --size - The size of the avatar.
*/

4
src/components/badge/badge.ts
View File

@@ -13,13 +13,13 @@ import type { CSSResultGroup } from 'lit';
*
* @slot - The badge's content.
*
* @csspart base - The component's internal wrapper.
* @csspart base - The component's base wrapper.
*/
@customElement('sl-badge')
export default class SlBadge extends ShoelaceElement {
static styles: CSSResultGroup = styles;
/** The badge's variant. */
/** The badge's theme variant. */
@property({ reflect: true }) variant: 'primary' | 'success' | 'neutral' | 'warning' | 'danger' = 'primary';
/** Draws a pill-style badge with rounded edges. */

8
src/components/breadcrumb-item/breadcrumb-item.ts
View File

@@ -19,11 +19,11 @@ import type { CSSResultGroup } from 'lit';
* @slot separator - The separator to use for the breadcrumb item. This will only change the separator for this item. If
* you want to change it for all items in the group, set the separator on `<sl-breadcrumb>` instead.
*
* @csspart base - The component's internal wrapper.
* @csspart base - The component's base wrapper.
* @csspart label - The breadcrumb item's label.
* @csspart prefix - The container that wraps the prefix slot.
* @csspart suffix - The container that wraps the suffix slot.
* @csspart separator - The container that wraps the separator slot.
* @csspart prefix - The container that wraps the prefix.
* @csspart suffix - The container that wraps the suffix.
* @csspart separator - The container that wraps the separator.
*/
@customElement('sl-breadcrumb-item')
export default class SlBreadcrumbItem extends ShoelaceElement {

10
src/components/breadcrumb/breadcrumb.ts
View File

@@ -14,11 +14,11 @@ import type { CSSResultGroup } from 'lit';
* @status stable
*
* @slot - One or more breadcrumb items to display.
* @slot separator - The separator to use between breadcrumb items.
* @slot separator - The separator to use between breadcrumb items. Works best with `<sl-icon>`.
*
* @dependency sl-icon
*
* @csspart base - The component's internal wrapper.
* @csspart base - The component's base wrapper.
*/
@customElement('sl-breadcrumb')
export default class SlBreadcrumb extends ShoelaceElement {
@@ -31,10 +31,10 @@ export default class SlBreadcrumb extends ShoelaceElement {
private separatorDir = this.localize.dir();
/**
* The label to use for the breadcrumb control. This will not be shown, but it will be announced by screen readers and
* other assistive devices.
* The label to use for the breadcrumb control. This will not be shown on the screen, but it will be announced by
* screen readers and other assistive devices to provide more context for users.
*/
@property() label = 'Breadcrumb';
@property() label = '';
// Generates a clone of the separator element to use for each breadcrumb item
private getSeparator() {

7
src/components/button-group/button-group.ts
View File

@@ -12,7 +12,7 @@ import type { CSSResultGroup } from 'lit';
*
* @slot - One or more `<sl-button>` elements to display in the button group.
*
* @csspart base - The component's internal wrapper.
* @csspart base - The component's base wrapper.
*/
@customElement('sl-button-group')
export default class SlButtonGroup extends ShoelaceElement {
@@ -22,7 +22,10 @@ export default class SlButtonGroup extends ShoelaceElement {
@state() disableRole = false;
/** A label to use for the button group's `aria-label` attribute. */
/**
* A label to use for the button group. This won't be displayed on the screen, but it will be announced by assistive
* devices when interacting with the control and is strongly recommended.
*/
@property() label = '';
handleFocus(event: CustomEvent) {

39
src/components/button/button.ts
View File

@@ -26,14 +26,14 @@ import type { CSSResultGroup } from 'lit';
* @event sl-focus - Emitted when the button gains focus.
*
* @slot - The button's label.
* @slot prefix - Used to prepend an icon or similar element to the button.
* @slot suffix - Used to append an icon or similar element to the button.
* @slot prefix - A presentational prefix icon or similar element.
* @slot suffix - A presentational suffix icon or similar element.
*
* @csspart base - The component's internal wrapper.
* @csspart prefix - The prefix slot's container.
* @csspart base - The component's base wrapper.
* @csspart prefix - The container that wraps the prefix.
* @csspart label - The button's label.
* @csspart suffix - The suffix slot's container.
* @csspart caret - The button's caret icon.
* @csspart suffix - The container that wraps the suffix.
* @csspart caret - The button's caret icon, an `<sl-icon>` element.
*/
@customElement('sl-button')
export default class SlButton extends ShoelaceElement implements ShoelaceFormControl {
@@ -62,14 +62,14 @@ export default class SlButton extends ShoelaceElement implements ShoelaceFormCon
@state() invalid = false;
@property() title = ''; // make reactive to pass through
/** The button's variant. */
/** The button's theme variant. */
@property({ reflect: true }) variant: 'default' | 'primary' | 'success' | 'neutral' | 'warning' | 'danger' | 'text' =
'default';
/** The button's size. */
@property({ reflect: true }) size: 'small' | 'medium' | 'large' = 'medium';
/** Draws the button with a caret for use with dropdowns, popovers, etc. */
/** Draws the button with a caret. Used to indicate that the button triggers a dropdown menu or similar behavior. */
@property({ type: Boolean, reflect: true }) caret = false;
/** Disables the button. */
@@ -84,28 +84,37 @@ export default class SlButton extends ShoelaceElement implements ShoelaceFormCon
/** Draws a pill-style button with rounded edges. */
@property({ type: Boolean, reflect: true }) pill = false;
/** Draws a circle button. */
/**
* Draws a circular icon button. When this attribute is present, the button expects a single `<sl-icon>` in the
* default slot.
*/
@property({ type: Boolean, reflect: true }) circle = false;
/**
* The type of button. When the type is `submit`, the button will submit the surrounding form. Note that the default
* value is `button` instead of `submit`, which is opposite of how native `<button>` elements behave.
* The type of button. Note that the default value is `button` instead of `submit`, which is opposite of how native
* `<button>` elements behave. When the type is `submit`, the button will submit the surrounding form.
*/
@property() type: 'button' | 'submit' | 'reset' = 'button';
/** An optional name for the button. Ignored when `href` is set. */
/**
* The name of the button, submitted as a name/value pair with form data. This attribute is ignored when `href` is
* present.
*/
@property() name = '';
/** An optional value for the button. Ignored when `href` is set. */
/**
* The value of the button, submitted as a pair with the button's name as part of the form data. This attribute is
* ignored when `href` is present.
*/
@property() value = '';
/** When set, the underlying button will be rendered as an `<a>` with this `href` instead of a `<button>`. */
@property() href = '';
/** Tells the browser where to open the link. Only used when `href` is set. */
/** Tells the browser where to open the link. Only used when `href` is present. */
@property() target: '_blank' | '_parent' | '_self' | '_top';
/** Tells the browser to download the linked file as this filename. Only used when `href` is set. */
/** Tells the browser to download the linked file as this filename. Only used when `href` is present. */
@property() download?: string;
/**

24
src/components/card/card.ts
View File

@@ -12,21 +12,21 @@ import type { CSSResultGroup } from 'lit';
* @since 2.0
* @status stable
*
* @slot - The card's body.
* @slot header - The card's header.
* @slot footer - The card's footer.
* @slot image - The card's image.
* @slot - The card's main content.
* @slot header - An optional header for the card.
* @slot footer - An optional footer for the card.
* @slot image - An optional image to render at the start of the card.
*
* @csspart base - The component's internal wrapper.
* @csspart image - The card's image, if present.
* @csspart header - The card's header, if present.
* @csspart body - The card's body.
* @csspart footer - The card's footer, if present.
* @csspart base - The component's base wrapper.
* @csspart image - The container that wraps the card's image.
* @csspart header - The container that wraps the card's header.
* @csspart body - The container that wraps the card's main content.
* @csspart footer - The container that wraps the card's footer.
*
* @cssproperty --border-color - The card's border color, including borders that occur inside the card.
* @cssproperty --border-radius - The border radius for card edges.
* @cssproperty --border-width - The width of card borders.
* @cssproperty --padding - The padding to use for card sections.*
* @cssproperty --border-radius - The border radius for the card's edges.
* @cssproperty --border-width - The width of the card's borders.
* @cssproperty --padding - The padding to use for the card's sections.
*/
@customElement('sl-card')
export default class SlCard extends ShoelaceElement {

40
src/components/checkbox/checkbox.ts
View File

@@ -22,15 +22,17 @@ import type { CSSResultGroup } from 'lit';
*
* @slot - The checkbox's label.
*
* @event sl-blur - Emitted when the control loses focus.
* @event sl-change - Emitted when the control's checked state changes.
* @event sl-focus - Emitted when the control gains focus.
* @event sl-blur - Emitted when the checkbox loses focus.
* @event sl-change - Emitted when the checked state changes.
* @event sl-focus - Emitted when the checkbox gains focus.
*
* @csspart base - The component's internal wrapper.
* @csspart control - The checkbox control.
* @csspart checked-icon - The checked icon.
* @csspart indeterminate-icon - The indeterminate icon.
* @csspart label - The checkbox label.
* @csspart base - The component's base wrapper.
* @csspart control - The square container that wraps the checkbox's checked state.
* @csspart control--checked - Matches the control part when the checkbox is checked.
* @csspart control--indeterminate - Matches the control part when the checkbox is indeterminate.
* @csspart checked-icon - The checked icon, an `<sl-icon>` element.
* @csspart indeterminate-icon - The indeterminate icon, an `<sl-icon>` element.
* @csspart label - The container that wraps the checkbox's label.
*/
@customElement('sl-checkbox')
export default class SlCheckbox extends ShoelaceElement implements ShoelaceFormControl {
@@ -49,13 +51,13 @@ export default class SlCheckbox extends ShoelaceElement implements ShoelaceFormC
@state() invalid = false;
@property() title = ''; // make reactive to pass through
/** Name of the HTML form control. Submitted with the form as part of a name/value pair. */
/** The name of the checkbox, submitted as a name/value pair with form data. */
@property() name = '';
/** Value of the HTML form control. Primarily used to differentiate a list of related checkboxes that have the same name. */
/** The current value of the checkbox, submitted as a name/value pair with form data. */
@property() value: string;
/** Disables the checkbox (so the user can't check / uncheck it). */
/** Disables the checkbox. */
@property({ type: Boolean, reflect: true }) disabled = false;
/** Makes the checkbox a required field. */
@@ -64,10 +66,13 @@ export default class SlCheckbox extends ShoelaceElement implements ShoelaceFormC
/** Draws the checkbox in a checked state. */
@property({ type: Boolean, reflect: true }) checked = false;
/** Draws the checkbox in an indeterminate state. Usually applies to a checkbox that represents "select all" or "select none" when the items to which it applies are a mix of selected and unselected. */
/**
* Draws the checkbox in an indeterminate state. This is usually applied to checkboxes that represents a "select
* all/none" behavior when associated checkboxes have a mix of checked and unchecked states.
*/
@property({ type: Boolean, reflect: true }) indeterminate = false;
/** Gets or sets the default value used to reset this element. The initial value corresponds to the one originally specified in the HTML that created this element. */
/** The default value of the form control. Primarily used for resetting the form control. */
@defaultValue('checked') defaultChecked = false;
firstUpdated() {
@@ -89,17 +94,20 @@ export default class SlCheckbox extends ShoelaceElement implements ShoelaceFormC
this.input.blur();
}
/** Checks for validity but does not show the browser's validation message. */
/** Checks for validity but does not show a validation message. Returns true when valid and false when invalid. */
checkValidity() {
return this.input.checkValidity();
}
/** Checks for validity and shows the browser's validation message if the control is invalid. */
/** Checks for validity and shows a validation message if the control is invalid. */
reportValidity() {
return this.input.reportValidity();
}
/** Sets a custom validation message. If `message` is not empty, the field will be considered invalid. */
/**
* Sets a custom validation message. The value provided will be shown to the user when the form is submitted. To clear
* the custom validation message, call this method with an empty string.
*/
setCustomValidity(message: string) {
this.input.setCustomValidity(message);
this.invalid = !this.input.checkValidity();

51
src/components/color-picker/color-picker.ts
View File

@@ -48,13 +48,13 @@ declare const EyeDropper: EyeDropperConstructor;
* @dependency sl-input
* @dependency sl-visually-hidden
*
* @slot label - The color picker's label. Alternatively, you can use the `label` attribute.
* @slot label - The color picker's form label. Alternatively, you can use the `label` attribute.
*
* @event sl-change Emitted when the color picker's value changes.
*
* @csspart base - The component's internal wrapper.
* @csspart base - The component's base wrapper.
* @csspart trigger - The color picker's dropdown trigger.
* @csspart swatches - The container that holds swatches.
* @csspart swatches - The container that holds the swatches.
* @csspart swatch - Each individual swatch.
* @csspart grid - The color grid.
* @csspart grid-handle - The color grid's handle.
@@ -65,17 +65,17 @@ declare const EyeDropper: EyeDropperConstructor;
* @csspart preview - The preview color.
* @csspart input - The text input.
* @csspart eye-dropper-button - The eye dropper button.
* @csspart eye-dropper-button__button - The eye dropper button's `button` part.
* @csspart eye-dropper-button__prefix - The eye dropper button's `prefix` part.
* @csspart eye-dropper-button__label - The eye dropper button's `label` part.
* @csspart eye-dropper-button__button-suffix - The eye dropper button's `suffix` part.
* @csspart eye-dropper-button__caret - The eye dropper button's `caret` part.
* @csspart eye-dropper-button__button - The eye dropper button's exported `button` part.
* @csspart eye-dropper-button__prefix - The eye dropper button's exported `prefix` part.
* @csspart eye-dropper-button__label - The eye dropper button's exported `label` part.
* @csspart eye-dropper-button__button-suffix - The eye dropper button's exported `suffix` part.
* @csspart eye-dropper-button__caret - The eye dropper button's exported `caret` part.
* @csspart format-button - The format button.
* @csspart format-button__button - The format button's `button` part.
* @csspart format-button__prefix - The format button's `prefix` part.
* @csspart format-button__label - The format button's `label` part.
* @csspart format-button__button-suffix - The format button's `suffix` part.
* @csspart format-button__caret - The format button's `caret` part.
* @csspart format-button__button - The format button's exported `button` part.
* @csspart format-button__prefix - The format button's exported `prefix` part.
* @csspart format-button__label - The format button's exported `label` part.
* @csspart format-button__button-suffix - The format button's exported `suffix` part.
* @csspart format-button__caret - The format button's exported `caret` part.
*
* @cssproperty --grid-width - The width of the color grid.
* @cssproperty --grid-height - The height of the color grid.
@@ -108,10 +108,14 @@ export default class SlColorPicker extends ShoelaceElement implements ShoelaceFo
@state() private alpha = 100;
@state() invalid = false;
/** The current color. */
/**
* The current value of the color picker. The value's format will vary based the `format` attribute. To get the value
* in a specific format, use the `getFormattedValue()` method. The value is submitted as a name/value pair with form
* data.
*/
@property() value = '';
/** Gets or sets the default value used to reset this element. The initial value corresponds to the one originally specified in the HTML that created this element. */
/** The default value of the form control. Primarily used for resetting the form control. */
@defaultValue() defaultValue = '';
/**
@@ -121,22 +125,21 @@ export default class SlColorPicker extends ShoelaceElement implements ShoelaceFo
@property() label = '';
/**
* The format to use for the display value. If opacity is enabled, these will translate to HEXA, RGBA, and HSLA
* respectively. The color picker will always accept user input in any format (including CSS color names) and convert
* it to the desired format.
* The format to use. If opacity is enabled, these will translate to HEXA, RGBA, and HSLA respectively. The color
* picker will accept user input in any format (including CSS color names) and convert it to the desired format.
*/
@property() format: 'hex' | 'rgb' | 'hsl' = 'hex';
/** Renders the color picker inline rather than inside a dropdown. */
/** Renders the color picker inline rather than in a dropdown. */
@property({ type: Boolean, reflect: true }) inline = false;
/** Determines the size of the color picker's trigger. This has no effect on inline color pickers. */
@property() size: 'small' | 'medium' | 'large' = 'medium';
/** Removes the format toggle. */
/** Removes the button that lets users toggle between format. */
@property({ attribute: 'no-format-toggle', type: Boolean }) noFormatToggle = false;
/** The input's name attribute. */
/** The name of the form control, submitted as a name/value pair with form data. */
@property() name = '';
/** Disables the color picker. */
@@ -144,14 +147,14 @@ export default class SlColorPicker extends ShoelaceElement implements ShoelaceFo
/**
* Enable this option to prevent the panel from being clipped when the component is placed inside a container with
* `overflow: auto|scroll`.
* `overflow: auto|scroll`. Hoisting uses a fixed positioning strategy that works in many, but not all, scenarios.
*/
@property({ type: Boolean }) hoist = false;
/** Whether to show the opacity slider. */
/** Shows the opacity slider. Enabling this will cause the formatted value to be HEXA, RGBA, or HSLA. */
@property({ type: Boolean }) opacity = false;
/** By default, the value will be set in lowercase. Set this to true to set it in uppercase instead. */
/** By default, values are lowercase. With this attribute, values will be uppercase instead. */
@property({ type: Boolean }) uppercase = false;
/**

21
src/components/details/details.ts
View File

@@ -19,20 +19,20 @@ import type { CSSResultGroup } from 'lit';
*
* @dependency sl-icon
*
* @slot - The details' content.
* @slot - The details' main content.
* @slot summary - The details' summary. Alternatively, you can use the `summary` attribute.
* @slot expand-icon - The expand icon's `<slot>`.
* @slot collapse-icon - The collapse icon's `<slot>`.
* @slot expand-icon - Optional expand icon to use instead of the default. Works best with `<sl-icon>`.
* @slot collapse-icon - Optional collapse icon to use instead of the default. Works best with `<sl-icon>`.
*
* @event sl-show - Emitted when the details opens.
* @event sl-after-show - Emitted after the details opens and all animations are complete.
* @event sl-hide - Emitted when the details closes.
* @event sl-after-hide - Emitted after the details closes and all animations are complete.
*
* @csspart base - The component's internal wrapper.
* @csspart header - The summary header.
* @csspart summary - The details summary.
* @csspart summary-icon - The container that houses the expand and collapse icons.
* @csspart base - The component's base wrapper.
* @csspart header - The header that wraps both the summary and the expand/collapse icon.
* @csspart summary - The container that wraps the summary.
* @csspart summary-icon - The container that wraps the expand/collapse icons.
* @csspart content - The details content.
*
* @animation details.show - The animation to use when showing details. You can use `height: auto` with this animation.
@@ -49,10 +49,13 @@ export default class SlDetails extends ShoelaceElement {
private readonly localize = new LocalizeController(this);
/** Indicates whether or not the details is open. You can use this in lieu of the show/hide methods. */
/**
* Indicates whether or not the details is open. You can toggle this attribute to show and hide the details, or you
* can use the `show()` and `hide()` methods and this attribute will reflect the details' open state.
*/
@property({ type: Boolean, reflect: true }) open = false;
/** The summary to show in the details header. If you need to display HTML, use the `summary` slot instead. */
/** The summary to show in the header. If you need to display HTML, use the `summary` slot instead. */
@property() summary: string;
/** Disables the details so it can't be toggled. */

28
src/components/dialog/dialog.ts
View File

@@ -23,7 +23,7 @@ import type { CSSResultGroup } from 'lit';
*
* @dependency sl-icon-button
*
* @slot - The dialog's content.
* @slot - The dialog's main content.
* @slot label - The dialog's label. Alternatively, you can use the `label` attribute.
* @slot footer - The dialog's footer, usually one or more buttons representing various options.
*
@@ -38,16 +38,16 @@ import type { CSSResultGroup } from 'lit';
* `event.preventDefault()` will keep the dialog open. Avoid using this unless closing the dialog will result in
* destructive behavior such as data loss.
*
* @csspart base - The component's internal wrapper.
* @csspart overlay - The overlay.
* @csspart panel - The dialog panel (where the dialog and its content is rendered).
* @csspart header - The dialog header.
* @csspart base - The component's base wrapper.
* @csspart overlay - The overlay that covers the screen behind the dialog.
* @csspart panel - The dialog's panel (where the dialog and its content are rendered).
* @csspart header - The dialog's header. This element wraps the title and header actions.
* @csspart header-actions - Optional actions to add to the header. Works best with `<sl-icon-button>`.
* @csspart title - The dialog title.
* @csspart close-button - The close button.
* @csspart close-button__base - The close button's `base` part.
* @csspart body - The dialog body.
* @csspart footer - The dialog footer.
* @csspart title - The dialog's title.
* @csspart close-button - The close button, an `<sl-icon-button>`.
* @csspart close-button__base - The close button's exported `base` part.
* @csspart body - The dialog's body.
* @csspart footer - The dialog's footer.
*
* @cssproperty --width - The preferred width of the dialog. Note that the dialog will shrink to accommodate smaller screens.
* @cssproperty --header-spacing - The amount of padding to use for the header.
@@ -73,13 +73,15 @@ export default class SlDialog extends ShoelaceElement {
private modal: Modal;
private originalTrigger: HTMLElement | null;
/** Indicates whether or not the dialog is open. You can use this in lieu of the show/hide methods. */
/**
* Indicates whether or not the dialog is open. You can toggle this attribute to show and hide the dialog, or you can
* use the `show()` and `hide()` methods and this attribute will reflect the dialog's open state.
*/
@property({ type: Boolean, reflect: true }) open = false;
/**
* The dialog's label as displayed in the header. You should always include a relevant label even when using
* `no-header`, as it is required for proper accessibility. If you need to display HTML, you can use the `label` slot
* instead.
* `no-header`, as it is required for proper accessibility. If you need to display HTML, use the `label` slot instead.
*/
@property({ reflect: true }) label = '';

28
src/components/drawer/drawer.ts
View File

@@ -24,7 +24,7 @@ import type { CSSResultGroup } from 'lit';
*
* @dependency sl-icon-button
*
* @slot - The drawer's content.
* @slot - The drawer's main content.
* @slot label - The drawer's label. Alternatively, you can use the `label` attribute.
* @slot footer - The drawer's footer, usually one or more buttons representing various options.
*
@@ -39,16 +39,16 @@ import type { CSSResultGroup } from 'lit';
* `event.preventDefault()` will keep the drawer open. Avoid using this unless closing the drawer will result in
* destructive behavior such as data loss.
*
* @csspart base - The component's internal wrapper.
* @csspart overlay - The overlay.
* @csspart panel - The drawer panel (where the drawer and its content is rendered).
* @csspart header - The drawer header.
* @csspart base - The component's base wrapper.
* @csspart overlay - The overlay that covers the screen behind the drawer.
* @csspart panel - The drawer's panel (where the drawer and its content are rendered).
* @csspart header - The drawer's header. This element wraps the title and header actions.
* @csspart header-actions - Optional actions to add to the header. Works best with `<sl-icon-button>`.
* @csspart title - The drawer title.
* @csspart close-button - The close button.
* @csspart close-button__base - The close button's `base` part.
* @csspart body - The drawer body.
* @csspart footer - The drawer footer.
* @csspart title - The drawer's title.
* @csspart close-button - The close button, an `<sl-icon-button>`.
* @csspart close-button__base - The close button's exported `base` part.
* @csspart body - The drawer's body.
* @csspart footer - The drawer's footer.
*
* @cssproperty --size - The preferred size of the drawer. This will be applied to the drawer's width or height
* depending on its `placement`. Note that the drawer will shrink to accommodate smaller screens.
@@ -81,13 +81,15 @@ export default class SlDrawer extends ShoelaceElement {
private modal: Modal;
private originalTrigger: HTMLElement | null;
/** Indicates whether or not the drawer is open. You can use this in lieu of the show/hide methods. */
/**
* Indicates whether or not the drawer is open. You can toggle this attribute to show and hide the drawer, or you can
* use the `show()` and `hide()` methods and this attribute will reflect the drawer's open state.
*/
@property({ type: Boolean, reflect: true }) open = false;
/**
* The drawer's label as displayed in the header. You should always include a relevant label even when using
* `no-header`, as it is required for proper accessibility. If you need to display HTML, you can use the `label` slot
* instead.
* `no-header`, as it is required for proper accessibility. If you need to display HTML, use the `label` slot instead.
*/
@property({ reflect: true }) label = '';

18
src/components/dropdown/dropdown.ts
View File

@@ -26,7 +26,7 @@ import type { CSSResultGroup } from 'lit';
*
* @dependency sl-popup
*
* @slot - The dropdown's content.
* @slot - The dropdown's main content.
* @slot trigger - The dropdown's trigger, usually a `<sl-button>` element.
*
* @event sl-show - Emitted when the dropdown opens.
@@ -34,7 +34,7 @@ import type { CSSResultGroup } from 'lit';
* @event sl-hide - Emitted when the dropdown closes.
* @event sl-after-hide - Emitted after the dropdown closes and all animations are complete.
*
* @csspart base - The component's internal wrapper.
* @csspart base - The component's base wrapper.
* @csspart trigger - The container that wraps the trigger.
* @csspart panel - The panel that gets shown when the dropdown is open.
*
@@ -51,7 +51,10 @@ export default class SlDropdown extends ShoelaceElement {
private readonly localize = new LocalizeController(this);
/** Indicates whether or not the dropdown is open. You can use this in lieu of the show/hide methods. */
/**
* Indicates whether or not the dropdown is open. You can toggle this attribute to show and hide the dropdown, or you
* can use the `show()` and `hide()` methods and this attribute will reflect the dropdown's open state.
*/
@property({ type: Boolean, reflect: true }) open = false;
/**
@@ -77,11 +80,14 @@ export default class SlDropdown extends ShoelaceElement {
/**
* By default, the dropdown is closed when an item is selected. This attribute will keep it open instead. Useful for
* controls that allow multiple selections.
* dropdowns that allow for multiple interactions.
*/
@property({ attribute: 'stay-open-on-select', type: Boolean, reflect: true }) stayOpenOnSelect = false;
/** The dropdown will close when the user interacts outside of this element (e.g. clicking). */
/**
* The dropdown will close when the user interacts outside of this element (e.g. clicking). Useful for composing other
* components that use a dropdown internally.
*/
@property({ attribute: false }) containingElement?: HTMLElement;
/** The distance in pixels from which to offset the panel away from its trigger. */
@@ -92,7 +98,7 @@ export default class SlDropdown extends ShoelaceElement {
/**
* Enable this option to prevent the panel from being clipped when the component is placed inside a container with
* `overflow: auto|scroll`.
* `overflow: auto|scroll`. Hoisting uses a fixed positioning strategy that works in many, but not all, scenarios.
*/
@property({ type: Boolean }) hoist = false;

2
src/components/format-bytes/format-bytes.ts
View File

@@ -15,7 +15,7 @@ export default class SlFormatBytes extends ShoelaceElement {
/** The number to format in bytes. */
@property({ type: Number }) value = 0;
/** The unit to display. */
/** The type of unit to display. */
@property() unit: 'byte' | 'bit' = 'byte';
/** Determines how to display the result, e.g. "100 bytes", "100 b", or "100b". */

8
src/components/format-date/format-date.ts
View File

@@ -13,7 +13,11 @@ import { LocalizeController } from '../../utilities/localize';
export default class SlFormatDate extends ShoelaceElement {
private readonly localize = new LocalizeController(this);
/** The date/time to format. If not set, the current date and time will be used. */
/**
* The date/time to format. If not set, the current date and time will be used. When passing a string, it's strongly
* recommended to use the ISO 8601 format to ensure timezones are handled correctly. To convert a date to this format
* in JavaScript, use [`date.toISOString()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString).
*/
@property() date: Date | string = new Date();
/** The format for displaying the weekday. */
@@ -46,7 +50,7 @@ export default class SlFormatDate extends ShoelaceElement {
/** The time zone to express the time in. */
@property({ attribute: 'time-zone' }) timeZone: string;
/** When set, 24 hour time will always be used. */
/** The format for displaying the hour. */
@property({ attribute: 'hour-format' }) hourFormat: 'auto' | '12' | '24' = 'auto';
render() {

12
src/components/format-number/format-number.ts
View File

@@ -21,25 +21,25 @@ export default class SlFormatNumber extends ShoelaceElement {
/** Turns off grouping separators. */
@property({ attribute: 'no-grouping', type: Boolean }) noGrouping = false;
/** The currency to use when formatting. Must be an ISO 4217 currency code such as `USD` or `EUR`. */
/** The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code to use when formatting. */
@property() currency = 'USD';
/** How to display the currency. */
@property({ attribute: 'currency-display' }) currencyDisplay: 'symbol' | 'narrowSymbol' | 'code' | 'name' = 'symbol';
/** The minimum number of integer digits to use. Possible values are 1 - 21. */
/** The minimum number of integer digits to use. Possible values are 1-21. */
@property({ attribute: 'minimum-integer-digits', type: Number }) minimumIntegerDigits: number;
/** The minimum number of fraction digits to use. Possible values are 0 - 20. */
/** The minimum number of fraction digits to use. Possible values are 0-20. */
@property({ attribute: 'minimum-fraction-digits', type: Number }) minimumFractionDigits: number;
/** The maximum number of fraction digits to use. Possible values are 0 - 20. */
/** The maximum number of fraction digits to use. Possible values are 0-0. */
@property({ attribute: 'maximum-fraction-digits', type: Number }) maximumFractionDigits: number;
/** The minimum number of significant digits to use. Possible values are 1 - 21. */
/** The minimum number of significant digits to use. Possible values are 1-21. */
@property({ attribute: 'minimum-significant-digits', type: Number }) minimumSignificantDigits: number;
/** The maximum number of significant digits to use,. Possible values are 1 - 21. */
/** The maximum number of significant digits to use,. Possible values are 1-21. */
@property({ attribute: 'maximum-significant-digits', type: Number }) maximumSignificantDigits: number;
render() {

13
src/components/icon-button/icon-button.ts
View File

@@ -18,7 +18,7 @@ import type { CSSResultGroup } from 'lit';
* @event sl-blur - Emitted when the icon button loses focus.
* @event sl-focus - Emitted when the icon button gains focus.
*
* @csspart base - The component's internal wrapper.
* @csspart base - The component's base wrapper.
*/
@customElement('sl-icon-button')
export default class SlIconButton extends ShoelaceElement {
@@ -28,13 +28,16 @@ export default class SlIconButton extends ShoelaceElement {
@query('.icon-button') button: HTMLButtonElement | HTMLLinkElement;
/** The name of the icon to draw. */
/** The name of the icon to draw. Available names depend on the icon library being used. */
@property() name?: string;
/** The name of a registered custom icon library. */
@property() library?: string;
/** An external URL of an SVG file. */
/**
* An external URL of an SVG file. Be sure you trust the content you are including, as it will be executed as code and
* can result in XSS attacks.
*/
@property() src?: string;
/** When set, the underlying button will be rendered as an `<a>` with this `href` instead of a `<button>`. */
@@ -47,8 +50,8 @@ export default class SlIconButton extends ShoelaceElement {
@property() download?: string;
/**
* A description that gets read by screen readers and other assistive devices. For optimal accessibility, you should
* always include a label that describes what the icon button does.
* A description that gets read by assistive devices. For optimal accessibility, you should always include a label
* that describes what the icon button does.
*/
@property() label = '';

14
src/components/icon/icon.ts
View File

@@ -25,17 +25,19 @@ export default class SlIcon extends ShoelaceElement {
@state() private svg = '';
/** The name of the icon to draw. */
/** The name of the icon to draw. Available names depend on the icon library being used. */
@property({ reflect: true }) name?: string;
/**
* An external URL of an SVG file.
*
* WARNING: Be sure you trust the content you are including as it will be executed as code and can result in XSS attacks.
* An external URL of an SVG file. Be sure you trust the content you are including, as it will be executed as code and
* can result in XSS attacks.
*/
@property() src?: string;
/** An alternate description to use for accessibility. If omitted, the icon will be ignored by assistive devices. */
/**
* An alternate description to use for assistive devices. If omitted, the icon will be considered presentational and
* ignored by assistive devices.
*/
@property() label = '';
/** The name of a registered custom icon library. */
@@ -63,7 +65,7 @@ export default class SlIcon extends ShoelaceElement {
return this.src;
}
/** @internal Fetches the icon and redraws it. Used to handle library registrations. */
// Fetches the icon and redraws it. Used to handle library registrations.
redraw() {
this.setIcon();
}

6
src/components/image-comparer/image-comparer.ts
View File

@@ -25,9 +25,9 @@ import type { CSSResultGroup } from 'lit';
*
* @event sl-change - Emitted when the position changes.
*
* @csspart base - The component's internal wrapper.
* @csspart before - The container that holds the "before" image.
* @csspart after - The container that holds the "after" image.
* @csspart base - The component's base wrapper.
* @csspart before - The container that wraps the before image.
* @csspart after - The container that wraps the after image.
* @csspart divider - The divider that separates the images.
* @csspart handle - The handle that the user drags to expose the after image.
*

9
src/components/include/include.ts
View File

@@ -20,9 +20,8 @@ export default class SlInclude extends ShoelaceElement {
static styles: CSSResultGroup = styles;
/**
* The location of the HTML file to include.
*
* WARNING: Be sure you trust the content you are including as it will be executed as code and can result in XSS attacks.
* The location of the HTML file to include. Be sure you trust the content you are including as it will be executed as
* code and can result in XSS attacks.
*/
@property() src: string;
@@ -30,8 +29,8 @@ export default class SlInclude extends ShoelaceElement {
@property() mode: 'cors' | 'no-cors' | 'same-origin' = 'cors';
/**
* Allows included scripts to be executed. You must ensure the content you're including is trusted, otherwise this
* option can lead to XSS vulnerabilities in your app!
* Allows included scripts to be executed. Be sure you trust the content you are including as it will be executed as
* code and can result in XSS attacks.
*/
@property({ attribute: 'allow-scripts', type: Boolean }) allowScripts = false;

78
src/components/input/input.ts
View File

@@ -34,12 +34,12 @@ const isFirefox = isChromium ? false : navigator.userAgent.includes('Firefox');
* @dependency sl-icon
*
* @slot label - The input's label. Alternatively, you can use the `label` attribute.
* @slot prefix - Used to prepend an icon or similar element to the input.
* @slot suffix - Used to append an icon or similar element to the input.
* @slot prefix - Used to prepend a presentational icon or similar element to the input.
* @slot suffix - Used to append a presentational icon or similar element to the input.
* @slot clear-icon - An icon to use in lieu of the default clear icon.
* @slot show-password-icon - An icon to use in lieu of the default show password icon.
* @slot hide-password-icon - An icon to use in lieu of the default hide password icon.
* @slot help-text - Help text that describes how to use the input. Alternatively, you can use the `help-text` attribute.
* @slot help-text - Text that describes how to use the input. Alternatively, you can use the `help-text` attribute.
*
* @event sl-change - Emitted when an alteration to the control's value is committed by the user.
* @event sl-clear - Emitted when the clear button is activated.
@@ -47,16 +47,16 @@ const isFirefox = isChromium ? false : navigator.userAgent.includes('Firefox');
* @event sl-focus - Emitted when the control gains focus.
* @event sl-blur - Emitted when the control loses focus.
*
* @csspart form-control - The form control that wraps the label, input, and help-text.
* @csspart form-control - The form control that wraps the label, input, and help text.
* @csspart form-control-label - The label's wrapper.
* @csspart form-control-input - The input's wrapper.
* @csspart form-control-help-text - The help text's wrapper.
* @csspart base - The component's internal wrapper.
* @csspart input - The input control.
* @csspart prefix - The input prefix container.
* @csspart base - The component's base wrapper.
* @csspart input - The internal `<input>` control.
* @csspart prefix - The container that wraps the prefix.
* @csspart clear-button - The clear button.
* @csspart password-toggle-button - The password toggle button.
* @csspart suffix - The input suffix container.
* @csspart suffix - The container that wraps the suffix.
*/
@customElement('sl-input')
export default class SlInput extends ShoelaceElement implements ShoelaceFormControl {
@@ -72,7 +72,10 @@ export default class SlInput extends ShoelaceElement implements ShoelaceFormCont
@state() invalid = false;
@property() title = ''; // make reactive to pass through
/** The input's type. */
/**
* The type of input. Works the same as a native `<input>` element, but only a subset of types are supported. Defaults
* to `text`.
*/
@property({ reflect: true }) type:
| 'date'
| 'datetime-local'
@@ -88,13 +91,13 @@ export default class SlInput extends ShoelaceElement implements ShoelaceFormCont
/** The input's size. */
@property({ reflect: true }) size: 'small' | 'medium' | 'large' = 'medium';
/** The input's name attribute. */
/** The name of the input, submitted as a name/value pair with form data. */
@property() name = '';
/** The input's value attribute. */
/** The current value of the input, submitted as a name/value pair with form data. */
@property() value = '';
/** Gets or sets the default value used to reset this element. The initial value corresponds to the one originally specified in the HTML that created this element. */
/** The default value of the form control. Primarily used for resetting the form control. */
@defaultValue() defaultValue = '';
/** Draws a filled input. */
@@ -103,25 +106,25 @@ export default class SlInput extends ShoelaceElement implements ShoelaceFormCont
/** Draws a pill-style input with rounded edges. */
@property({ type: Boolean, reflect: true }) pill = false;
/** The input's label. If you need to display HTML, you can use the `label` slot instead. */
/** The input's label. If you need to display HTML, use the `label` slot instead. */
@property() label = '';
/** The input's help text. If you need to display HTML, you can use the `help-text` slot instead. */
/** The input's help text. If you need to display HTML, use the `help-text` slot instead. */
@property({ attribute: 'help-text' }) helpText = '';
/** Adds a clear button when the input is populated. */
/** Adds a clear button when the input is not empty. */
@property({ type: Boolean }) clearable = false;
/** Adds a password toggle button to password inputs. */
/** Adds a button to toggle the password's visibility. Only applies to password types. */
@property({ attribute: 'password-toggle', type: Boolean }) passwordToggle = false;
/** Determines whether or not the password is currently visible. Only applies to password inputs. */
/** Determines whether or not the password is currently visible. Only applies to password input types. */
@property({ attribute: 'password-visible', type: Boolean }) passwordVisible = false;
/** Hides the browser's built-in increment/decrement spin buttons for number inputs. */
@property({ attribute: 'no-spin-buttons', type: Boolean }) noSpinButtons = false;
/** The input's placeholder text. */
/** Placeholder text to show as a hint when the input is empty. */
@property() placeholder = '';
/** Disables the input. */
@@ -136,49 +139,52 @@ export default class SlInput extends ShoelaceElement implements ShoelaceFormCont
/** The maximum length of input that will be considered valid. */
@property({ type: Number }) maxlength: number;
/** The input's minimum value. */
/** The input's minimum value. Only applies to date and number input types. */
@property() min: number;
/** The input's maximum value. */
/** The input's maximum value. Only applies to date and number input types. */
@property() max: number;
/**
* Specifies the granularity that the value must adhere to, or the special value `any` which means no stepping is
* implied, allowing any numeric value.
* implied, allowing any numeric value. Only applies to date and number input types.
*/
@property() step: number | 'any';
/** A pattern to validate input against. */
/** A regular expression pattern to validate input against. */
@property() pattern: string;
/** Makes the input a required field. */
@property({ type: Boolean, reflect: true }) required = false;
/** The input's autocapitalize attribute. */
/** Controls whether and how text input is automatically capitalized as it is entered by the user. */
@property() autocapitalize: 'off' | 'none' | 'on' | 'sentences' | 'words' | 'characters';
/** The input's autocorrect attribute. */
@property() autocorrect: string;
/** The input's autocomplete attribute. */
@property() autocomplete: string;
/** The input's autofocus attribute. */
@property({ type: Boolean }) autofocus: boolean;
/** Indicates whether the browser's autocorrect feature is on or off. */
@property() autocorrect: 'off' | 'on';
/**
* The input's enterkeyhint attribute. This can be used to customize the label or icon of the Enter key on virtual
* keyboards.
* Specifies what permission the browser has to provide assistance in filling out form field values. Refer to
* [this page on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete) for available values.
*/
@property() autocomplete: string;
/** Indicates that the input should receive focus on page load. */
@property({ type: Boolean }) autofocus: boolean;
/** Used to customize the label or icon of the Enter key on virtual keyboards. */
@property() enterkeyhint: 'enter' | 'done' | 'go' | 'next' | 'previous' | 'search' | 'send';
/** Enables spell checking on the input. */
@property({ type: Boolean }) spellcheck: boolean;
/** The input's inputmode attribute. */
/**
* Tells the browser what type of data will be entered by the user, allowing it to display the appropriate virtual
* keyboard on supportive devices.
*/
@property() inputmode: 'none' | 'text' | 'decimal' | 'numeric' | 'tel' | 'search' | 'email' | 'url';
/** Gets or sets the current value as a `Date` object. Only valid when `type` is `date`. */
/** Gets or sets the current value as a `Date` object. Returns `null` if the value can't be converted. */
get valueAsDate() {
return this.input?.valueAsDate ?? null;
}
@@ -191,7 +197,7 @@ export default class SlInput extends ShoelaceElement implements ShoelaceFormCont
this.value = input.value;
}
/** Gets or sets the current value as a number. */
/** Gets or sets the current value as a number. Returns `NaN` if the value can't be converted. */
get valueAsNumber() {
return this.input?.valueAsNumber ?? parseFloat(this.value);
}

2
src/components/menu-item/menu-item.ts
View File

@@ -23,7 +23,7 @@ import type { CSSResultGroup } from 'lit';
* @slot prefix - Used to prepend an icon or similar element to the menu item.
* @slot suffix - Used to append an icon or similar element to the menu item.
*
* @csspart base - The component's internal wrapper.
* @csspart base - The component's base wrapper.
* @csspart checked-icon - The checked icon, which is only visible when the menu item is checked.
* @csspart prefix - The prefix container.
* @csspart label - The menu item label.

2
src/components/menu-label/menu-label.ts
View File

@@ -12,7 +12,7 @@ import type { CSSResultGroup } from 'lit';
*
* @slot - The menu label's content.
*
* @csspart base - The component's internal wrapper.
* @csspart base - The component's base wrapper.
*/
@customElement('sl-menu-label')
export default class SlMenuLabel extends ShoelaceElement {

4
src/components/mutation-observer/mutation-observer.ts
View File

@@ -11,7 +11,7 @@ import type { CSSResultGroup } from 'lit';
* @since 2.0
* @status stable
*
* @event sl-mutation - Emitted when a mutation occurs.
* @event {{ mutationList: MutationRecord[] }} sl-mutation - Emitted when a mutation occurs.
*
* @slot - The content to watch for mutations.
*/
@@ -23,7 +23,7 @@ export default class SlMutationObserver extends ShoelaceElement {
/**
* Watches for changes to attributes. To watch only specific attributes, separate them by a space, e.g.
* `class id title`. To watch all attributes, use `*`.
* `attr="class id title"`. To watch all attributes, use `*`.
*/
@property({ reflect: true }) attr: string;

2
src/components/popup/popup.ts
View File

@@ -272,7 +272,7 @@ export default class SlPopup extends ShoelaceElement {
}
}
/** Recalculate and repositions the popup. */
/** Forces the popup to recalculate and reposition itself. */
reposition() {
// Nothing to do if the popup is inactive or the anchor doesn't exist
if (!this.active || !this.anchorEl) {

18
src/components/progress-bar/progress-bar.ts
View File

@@ -14,29 +14,29 @@ import type { CSSResultGroup } from 'lit';
* @since 2.0
* @status stable
*
* @slot - A label to show inside the indicator.
* @slot - A label to show inside the progress indicator.
*
* @csspart base - The component's internal wrapper.
* @csspart indicator - The progress bar indicator.
* @csspart label - The progress bar label.
* @csspart base - The component's base wrapper.
* @csspart indicator - The progress bar's indicator.
* @csspart label - The progress bar's label.
*
* @cssproperty --height - The progress bar's height.
* @cssproperty --track-color - The track color.
* @cssproperty --indicator-color - The indicator color.
* @cssproperty --label-color - The label color.
* @cssproperty --track-color - The color of the track.
* @cssproperty --indicator-color - The color of the indicator.
* @cssproperty --label-color - The color of the label.
*/
@customElement('sl-progress-bar')
export default class SlProgressBar extends ShoelaceElement {
static styles: CSSResultGroup = styles;
private readonly localize = new LocalizeController(this);
/** The current progress, 0 to 100. */
/** The current progress as a percentage, 0 to 100. */
@property({ type: Number, reflect: true }) value = 0;
/** When true, percentage is ignored, the label is hidden, and the progress bar is drawn in an indeterminate state. */
@property({ type: Boolean, reflect: true }) indeterminate = false;
/** A custom label for the progress bar's aria label. */
/** A custom label for assistive devices. */
@property() label = '';
render() {

11
src/components/progress-ring/progress-ring.ts
View File

@@ -13,14 +13,14 @@ import type { CSSResultGroup } from 'lit';
*
* @slot - A label to show inside the ring.
*
* @csspart base - The component's internal wrapper.
* @csspart base - The component's base wrapper.
* @csspart label - The progress ring label.
*
* @cssproperty --size - The diameter of the progress ring (cannot be a percentage).
* @cssproperty --track-width - The width of the track.
* @cssproperty --track-color - The color of the track.
* @cssproperty --indicator-width - The width of the indicator. Defaults to the track width.
* @cssproperty --indicator-color - The indicator color.
* @cssproperty --indicator-color - The color of the indicator.
* @cssproperty --indicator-transition-duration - The duration of the indicator's transition when the value changes.
*/
@customElement('sl-progress-ring')
@@ -32,10 +32,10 @@ export default class SlProgressRing extends ShoelaceElement {
@state() indicatorOffset: string;
/** The current progress, 0 to 100. */
/** The current progress as a percentage, 0 to 100. */
@property({ type: Number, reflect: true }) value = 0;
/** A custom label for the progress ring's aria label. */
/** A custom label for assistive devices. */
@property() label = '';
updated(changedProps: Map<string, unknown>) {
@@ -62,6 +62,7 @@ export default class SlProgressRing extends ShoelaceElement {
class="progress-ring"
role="progressbar"
aria-label=${this.label.length > 0 ? this.label : this.localize.term('progress')}
aria-describedby="label"
aria-valuemin="0"
aria-valuemax="100"
aria-valuenow="${this.value}"
@@ -72,7 +73,7 @@ export default class SlProgressRing extends ShoelaceElement {
<circle class="progress-ring__indicator" style="stroke-dashoffset: ${this.indicatorOffset}"></circle>
</svg>
<slot part="label" class="progress-ring__label"></slot>
<slot id="label" part="label" class="progress-ring__label"></slot>
</div>
`;
}

12
src/components/qr-code/qr-code.styles.ts
View File

@@ -7,16 +7,4 @@ export default css`
:host {
display: inline-block;
}
.qr-code {
position: relative;
}
canvas {
position: absolute;
top: 0;
left: 0;
width: 100%;
height: 100%;
}
`;

26
src/components/qr-code/qr-code.ts
View File

@@ -11,7 +11,7 @@ import type { CSSResultGroup } from 'lit';
* @since 2.0
* @status stable
*
* @csspart base - The component's internal wrapper.
* @csspart base - The component's base wrapper.
*/
@customElement('sl-qr-code')
export default class SlQrCode extends ShoelaceElement {
@@ -22,22 +22,22 @@ export default class SlQrCode extends ShoelaceElement {
/** The QR code's value. */
@property() value = '';
/** The label used when screen readers announce the code. If unspecified, the value will be used. */
/** The label for assistive devices to announce. If unspecified, the value will be used instead. */
@property() label = '';
/** The size of the code's overall square in pixels. */
/** The size of the QR code, in pixels. */
@property({ type: Number }) size = 128;
/** The fill color. This can be any valid CSS color, but not a CSS custom property. */
@property() fill = '#000';
@property() fill = 'black';
/** The background color. This can be any valid CSS color or `transparent`, but not a CSS custom property. */
@property() background = '#fff';
/** The background color. This can be any valid CSS color or `transparent`. It cannot be a CSS custom property. */
@property() background = 'white';
/** The edge radius of each module. Must be between 0 and 0.5. */
@property({ type: Number }) radius = 0;
/** The level of error correction to use. */
/** The level of error correction to use. [Learn more](https://www.qrcode.com/en/about/error_correction.html) */
@property({ attribute: 'error-correction' }) errorCorrection: 'L' | 'M' | 'Q' | 'H' = 'H';
firstUpdated() {
@@ -61,7 +61,7 @@ export default class SlQrCode extends ShoelaceElement {
radius: this.radius,
ecLevel: this.errorCorrection,
fill: this.fill,
background: this.background === 'transparent' ? null : this.background,
background: null,
// We draw the canvas larger and scale its container down to avoid blurring on high-density displays
size: this.size * 2
},
@@ -71,16 +71,16 @@ export default class SlQrCode extends ShoelaceElement {
render() {
return html`
<div
class="qr-code"
<canvas
part="base"
class="qr-code"
role="img"
aria-label=${this.label.length > 0 ? this.label : this.value}
style=${styleMap({
width: `${this.size}px`,
height: `${this.size}px`
})}
>
<canvas role="img" aria-label=${this.label.length > 0 ? this.label : this.value}></canvas>
</div>
></canvas>
`;
}
}

30
src/components/radio-button/radio-button.ts
View File

@@ -14,19 +14,19 @@ import type { CSSResultGroup } from 'lit';
* @since 2.0
* @status stable
*
* @slot - The button's label.
* @slot prefix - Used to prepend an icon or similar element to the button.
* @slot suffix - Used to append an icon or similar element to the button.
* @slot - The radio button's label.
* @slot prefix - A presentational prefix icon or similar element.
* @slot suffix - A presentational suffix icon or similar element.
*
* @event sl-blur - Emitted when the button loses focus.
* @event sl-focus - Emitted when the button gains focus.
*
* @csspart base - The component's internal wrapper.
* @csspart button - The internal button element.
* @csspart button--checked - The internal button element if checked
* @csspart prefix - The prefix slot's container.
* @csspart label - The button's label.
* @csspart suffix - The suffix slot's container.
* @csspart base - The component's base wrapper.
* @csspart button - The internal `<button>` element.
* @csspart button--checked - The internal button element when the radio button is checked.
* @csspart prefix - The container that wraps the prefix.
* @csspart label - The container that wraps the radio button's label.
* @csspart suffix - The container that wraps the suffix.
*/
@customElement('sl-radio-button')
export default class SlRadioButton extends ShoelaceElement {
@@ -40,16 +40,16 @@ export default class SlRadioButton extends ShoelaceElement {
@state() protected hasFocus = false;
@state() checked = false;
/** The radio's value attribute. */
/** The radio's value. When selected, the radio group will receive this value. */
@property() value: string;
/** Disables the radio. */
/** Disables the radio button. */
@property({ type: Boolean, reflect: true }) disabled = false;
/** The button's size. */
/** The radio button's size. */
@property({ reflect: true }) size: 'small' | 'medium' | 'large' = 'medium';
/** Draws a pill-style button with rounded edges. */
/** Draws a pill-style radio button with rounded edges. */
@property({ type: Boolean, reflect: true }) pill = false;
connectedCallback(): void {
@@ -57,12 +57,12 @@ export default class SlRadioButton extends ShoelaceElement {
this.setAttribute('role', 'presentation');
}
/** Sets focus on the button. */
/** Sets focus on the radio button. */
focus(options?: FocusOptions) {
this.input.focus(options);
}
/** Removes focus from the button. */
/** Removes focus from the radio button. */
blur() {
this.input.blur();
}

19
src/components/radio-group/radio-group.ts
View File

@@ -20,12 +20,13 @@ import type { CSSResultGroup } from 'lit';
*
* @dependency sl-button-group
*
* @slot - The default slot where radio controls are placed.
* @slot label - The radio group label. Required for proper accessibility. Alternatively, you can use the `label` attribute.
* @slot - The default slot where `<sl-radio>` or `<sl-radio-button>` elements are placed.
* @slot label - The radio group's label. Required for proper accessibility. Alternatively, you can use the `label`
* attribute.
*
* @event sl-change - Emitted when the radio group's selected value changes.
*
* @csspart form-control - The form control that wraps the label, input, and help-text.
* @csspart form-control - The form control that wraps the label, input, and help text.
* @csspart form-control-label - The label's wrapper.
* @csspart form-control-input - The input's wrapper.
* @csspart form-control-help-text - The help text's wrapper.
@@ -51,20 +52,20 @@ export default class SlRadioGroup extends ShoelaceElement implements ShoelaceFor
@state() invalid = false;
/**
* The radio group label. Required for proper accessibility. If you need to display HTML, you can use the `label` slot
* The radio group's label. Required for proper accessibility. If you need to display HTML, use the `label` slot
* instead.
*/
@property() label = '';
/** The input's help text. If you need to display HTML, you can use the `help-text` slot instead. */
/** The radio groups's help text. If you need to display HTML, use the `help-text` slot instead. */
@property({ attribute: 'help-text' }) helpText = '';
/** The selected value of the control. */
@property({ reflect: true }) value = '';
/** The name assigned to the radio controls. */
/** The name of the radio group, submitted as a name/value pair with form data. */
@property() name = 'option';
/** The current value of the radio group, submitted as a name/value pair with form data. */
@property({ reflect: true }) value = '';
/** Ensures a child radio is checked before allowing the containing form to submit. */
@property({ type: Boolean, reflect: true }) required = false;

12
src/components/radio/radio.ts
View File

@@ -20,11 +20,11 @@ import type { CSSResultGroup } from 'lit';
* @event sl-blur - Emitted when the control loses focus.
* @event sl-focus - Emitted when the control gains focus.
*
* @csspart base - The component's internal wrapper.
* @csspart control - The radio control.
* @csspart control--checked - The radio control if radio is checked.
* @csspart checked-icon - The checked icon.
* @csspart label - The radio label.
* @csspart base - The component's base wrapper.
* @csspart control - The circular container that wraps the radio's checked state.
* @csspart control--checked - The radio control when the radio is checked.
* @csspart checked-icon - The checked icon, an `<sl-icon>` element.
* @csspart label - The container that wraps the radio's label.
*/
@customElement('sl-radio')
export default class SlRadio extends ShoelaceElement {
@@ -33,7 +33,7 @@ export default class SlRadio extends ShoelaceElement {
@state() checked = false;
@state() protected hasFocus = false;
/** The radio's value attribute. */
/** The radio's value. When selected, the radio group will receive this value. */
@property() value: string;
/** Disables the radio. */

43
src/components/range/range.ts
View File

@@ -19,20 +19,20 @@ import type { CSSResultGroup } from 'lit';
* @since 2.0
* @status stable
*
* @slot label - The input's label. Alternatively, you can use the `label` attribute.
* @slot help-text - Help text that describes how to use the input. Alternatively, you can use the `help-text` attribute.
* @slot label - The range's label. Alternatively, you can use the `label` attribute.
* @slot help-text - Text that describes how to use the input. Alternatively, you can use the `help-text` attribute.
*
* @event sl-change - Emitted when the control's value changes.
* @event sl-blur - Emitted when the control loses focus.
* @event sl-focus - Emitted when the control gains focus.
*
* @csspart form-control - The form control that wraps the label, input, and help-text.
* @csspart form-control - The form control that wraps the label, input, and help text.
* @csspart form-control-label - The label's wrapper.
* @csspart form-control-input - The range's wrapper.
* @csspart form-control-help-text - The help text's wrapper.
* @csspart base - The component's internal wrapper.
* @csspart input - The native range input.
* @csspart tooltip - The range tooltip.
* @csspart base - The component's base wrapper.
* @csspart input - The internal `<input>` element.
* @csspart tooltip - The range's tooltip.
*
* @cssproperty --thumb-size - The size of the thumb.
* @cssproperty --tooltip-offset - The vertical distance the tooltip is offset from the track.
@@ -59,37 +59,40 @@ export default class SlRange extends ShoelaceElement implements ShoelaceFormCont
@state() invalid = false;
@property() title = ''; // make reactive to pass through
/** The range's name attribute. */
/** The name of the range, submitted as a name/value pair with form data. */
@property() name = '';
/** The range's value attribute. */
/** The current value of the range, submitted as a name/value pair with form data. */
@property({ type: Number }) value = 0;
/** The range's label. If you need to display HTML, you can use the `label` slot instead. */
/** The range's label. If you need to display HTML, use the `label` slot instead. */
@property() label = '';
/** The range's help text. If you need to display HTML, you can use the help-text slot instead. */
/** The range's help text. If you need to display HTML, use the help-text slot instead. */
@property({ attribute: 'help-text' }) helpText = '';
/** Disables the range. */
@property({ type: Boolean, reflect: true }) disabled = false;
/** The range's min attribute. */
/** The minimum acceptable value of the range. */
@property({ type: Number }) min = 0;
/** The range's max attribute. */
/** The maximum acceptable value of the range. */
@property({ type: Number }) max = 100;
/** The range's step attribute. */
/** The interval at which the range will increase and decrease. */
@property({ type: Number }) step = 1;
/** The preferred placement of the tooltip. */
/** The preferred placement of the range's tooltip. */
@property() tooltip: 'top' | 'bottom' | 'none' = 'top';
/** A function used to format the tooltip's value. */
/**
* A function used to format the tooltip's value. The range's value is passed as the first and only argument. The
* function should return a string to display in the tooltip.
*/
@property({ attribute: false }) tooltipFormatter: (value: number) => string = (value: number) => value.toString();
/** Gets or sets the default value used to reset this element. The initial value corresponds to the one originally specified in the HTML that created this element. */
/** The default value of the form control. Primarily used for resetting the form control. */
@defaultValue() defaultValue = 0;
connectedCallback() {
@@ -114,17 +117,17 @@ export default class SlRange extends ShoelaceElement implements ShoelaceFormCont
this.resizeObserver.unobserve(this.input);
}
/** Sets focus on the input. */
/** Sets focus on the range. */
focus(options?: FocusOptions) {
this.input.focus(options);
}
/** Removes focus from the input. */
/** Removes focus from the range. */
blur() {
this.input.blur();
}
/** Increments the value of the input by the value of the step attribute. */
/** Increments the value of the range by the value of the step attribute. */
stepUp() {
this.input.stepUp();
if (this.value !== Number(this.input.value)) {
@@ -133,7 +136,7 @@ export default class SlRange extends ShoelaceElement implements ShoelaceFormCont
}
}
/** Decrements the value of the input by the value of the step attribute. */
/** Decrements the value of the range by the value of the step attribute. */
stepDown() {
this.input.stepDown();
if (this.value !== Number(this.input.value)) {

15
src/components/rating/rating.ts
View File

@@ -21,7 +21,7 @@ import type { CSSResultGroup } from 'lit';
*
* @event sl-change - Emitted when the rating's value changes.
*
* @csspart base - The component's internal wrapper.
* @csspart base - The component's base wrapper.
*
* @cssproperty --symbol-color - The inactive color for symbols.
* @cssproperty --symbol-color-active - The active color for symbols.
@@ -39,7 +39,7 @@ export default class SlRating extends ShoelaceElement {
@state() private hoverValue = 0;
@state() private isHovering = false;
/** A label to describe the rating to assistive devices. */
/** A label that describes the rating to assistive devices. */
@property() label = '';
/** The current rating. */
@@ -48,7 +48,10 @@ export default class SlRating extends ShoelaceElement {
/** The highest rating to show. */
@property({ type: Number }) max = 5;
/** The minimum increment value allowed by the control. */
/**
* The precision at which the rating will increase and decrease. For example, to allow half-star ratings, set this
* attribute to `0.5`.
*/
@property({ type: Number }) precision = 1;
/** Makes the rating readonly. */
@@ -57,7 +60,11 @@ export default class SlRating extends ShoelaceElement {
/** Disables the rating. */
@property({ type: Boolean, reflect: true }) disabled = false;
/** The name of the icon to display as the symbol. */
/**
* A function that customizes the symbol to be rendered. The first and only argument is the rating's current value.
* The function should return a string containing trusted HTML of the symbol to render at the specified value. Works
* well with `<sl-icon>` elements.
*/
@property() getSymbol: (value: number) => string = () => '<sl-icon name="star-fill" library="system"></sl-icon>';
/** Sets focus on the rating. */

8
src/components/relative-time/relative-time.ts
View File

@@ -33,8 +33,12 @@ export default class SlRelativeTime extends ShoelaceElement {
@state() private relativeTime = '';
@state() private titleTime = '';
/** The date from which to calculate time from. */
@property() date: Date | string;
/**
* The date from which to calculate time from. If not set, the current date and time will be used. When passing a
* string, it's strongly recommended to use the ISO 8601 format to ensure timezones are handled correctly. To convert
* a date to this format in JavaScript, use [`date.toISOString()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString).
*/
@property() date: Date | string = new Date();
/** The formatting style to use. */
@property() format: 'long' | 'short' | 'narrow' = 'long';

54
src/components/select/select.ts
View File

@@ -34,11 +34,11 @@ import type { TemplateResult, CSSResultGroup } from 'lit';
* @dependency sl-tag
*
* @slot - The select's options in the form of menu items.
* @slot prefix - Used to prepend an icon or similar element to the select.
* @slot suffix - Used to append an icon or similar element to the select.
* @slot clear-icon - An icon to use in lieu of the default clear icon.
* @slot prefix - A presentational icon or similar element to prepend to the select's label.
* @slot suffix - A presentational icon or similar element to append to the select's label.
* @slot clear-icon - An icon to use in lieu of the default clear icon. Works best with `<sl-icon>`.
* @slot label - The select's label. Alternatively, you can use the `label` attribute.
* @slot help-text - Help text that describes how to use the select. Alternatively, you can use the `help-text` attribute.
* @slot help-text - Text that describes how to use the select. Alternatively, you can use the `help-text` attribute.
*
* @event sl-clear - Emitted when the clear button is activated.
* @event sl-change - Emitted when the control's value changes.
@@ -46,23 +46,23 @@ import type { TemplateResult, CSSResultGroup } from 'lit';
* @event sl-focus - Emitted when the control gains focus.
* @event sl-blur - Emitted when the control loses focus.
*
* @csspart form-control - The form control that wraps the label, input, and help-text.
* @csspart form-control - The form control that wraps the label, input, and help text.
* @csspart form-control-label - The label's wrapper.
* @csspart form-control-input - The select's wrapper.
* @csspart form-control-help-text - The help text's wrapper.
* @csspart base - The component's internal wrapper.
* @csspart base - The component's base wrapper.
* @csspart clear-button - The clear button.
* @csspart control - The container that holds the prefix, label, and suffix.
* @csspart display-label - The label that displays the current selection. Not available when used with `multiple`.
* @csspart icon - The select's icon.
* @csspart prefix - The select's prefix.
* @csspart suffix - The select's suffix.
* @csspart menu - The select menu, an `<sl-menu>` element.
* @csspart tag - The multi select option, an `<sl-tag>` element.
* @csspart tag__base - The tag's `base` part.
* @csspart tag__content - The tag's `content` part.
* @csspart tag__remove-button - The tag's `remove-button` part.
* @csspart tags - The container in which multi select options are rendered.
* @csspart icon - The select's expand/collapse icon.
* @csspart prefix - The container that wraps the prefix.
* @csspart suffix - The container that wraps the suffix.
* @csspart menu - The select's menu, an `<sl-menu>` element.
* @csspart tags - The container that wraps tags when using `multiple`.
* @csspart tag - Tags that represent selected options when using `multiple`.
* @csspart tag__base - The tag's exported `base` part.
* @csspart tag__content - The tag's exported `content` part.
* @csspart tag__remove-button - The tag's exported `remove-button` part.
*/
@customElement('sl-select')
export default class SlSelect extends ShoelaceElement implements ShoelaceFormControl {
@@ -86,7 +86,7 @@ export default class SlSelect extends ShoelaceElement implements ShoelaceFormCon
@state() private displayTags: TemplateResult[] = [];
@state() invalid = false;
/** Enables multi select. With this enabled, value will be an array. */
/** Enables multiselect. With this enabled, value will be an array. */
@property({ type: Boolean, reflect: true }) multiple = false;
/**
@@ -98,10 +98,13 @@ export default class SlSelect extends ShoelaceElement implements ShoelaceFormCon
/** Disables the select control. */
@property({ type: Boolean, reflect: true }) disabled = false;
/** The select's name. */
/** The name of the select, submitted as a name/value pair with form data. */
@property() name = '';
/** The select's placeholder text. */
/** The current value of the select, submitted as a name/value pair with form data. */
@property() value: string | string[] = '';
/** Placeholder text to show as a hint when the input is empty. */
@property() placeholder = '';
/** The select's size. */
@@ -109,20 +112,17 @@ export default class SlSelect extends ShoelaceElement implements ShoelaceFormCon
/**
* Enable this option to prevent the panel from being clipped when the component is placed inside a container with
* `overflow: auto|scroll`.
* `overflow: auto|scroll`. Hoisting uses a fixed positioning strategy that works in many, but not all, scenarios.
*/
@property({ type: Boolean }) hoist = false;
/** The value of the control. This will be a string or an array depending on `multiple`. */
@property() value: string | string[] = '';
/** Draws a filled select. */
@property({ type: Boolean, reflect: true }) filled = false;
/** Draws a pill-style select with rounded edges. */
@property({ type: Boolean, reflect: true }) pill = false;
/** The select's label. If you need to display HTML, you can use the `label` slot instead. */
/** The select's label. If you need to display HTML, use the `label` slot instead. */
@property() label = '';
/**
@@ -131,16 +131,16 @@ export default class SlSelect extends ShoelaceElement implements ShoelaceFormCon
*/
@property() placement: 'top' | 'bottom' = 'bottom';
/** The select's help text. If you need to display HTML, you can use the `help-text` slot instead. */
/** The select's help text. If you need to display HTML, use the `help-text` slot instead. */
@property({ attribute: 'help-text' }) helpText = '';
/** The select's required attribute. */
@property({ type: Boolean, reflect: true }) required = false;
/** Adds a clear button when the select is populated. */
/** Adds a clear button when the select is not empty. */
@property({ type: Boolean }) clearable = false;
/** Gets or sets the default value used to reset this element. The initial value corresponds to the one originally specified in the HTML that created this element. */
/** The default value of the form control. Primarily used for resetting the form control. */
@defaultValue() defaultValue = '';
connectedCallback() {
@@ -179,7 +179,7 @@ export default class SlSelect extends ShoelaceElement implements ShoelaceFormCon
}
getValueAsArray() {
// Single selects use '' as an empty selection value, so convert this to [] for an empty multi select
// Single selects use '' as an empty selection value, so convert this to [] for an empty multiselect
if (this.multiple && this.value === '') {
return [];
}

2
src/components/skeleton/skeleton.ts
View File

@@ -11,7 +11,7 @@ import type { CSSResultGroup } from 'lit';
* @since 2.0
* @status stable
*
* @csspart base - The component's internal wrapper.
* @csspart base - The component's base wrapper.
* @csspart indicator - The skeleton's indicator which is responsible for its color and animation.
*
* @cssproperty --border-radius - The skeleton's border radius.

4
src/components/spinner/spinner.ts
View File

@@ -11,11 +11,11 @@ import type { CSSResultGroup } from 'lit';
* @since 2.0
* @status stable
*
* @csspart base - The component's internal wrapper.
* @csspart base - The component's base wrapper.
*
* @cssproperty --track-width - The width of the track.
* @cssproperty --track-color - The color of the track.
* @cssproperty --indicator-color - The color of the indicator.
* @cssproperty --indicator-color - The color of the spinner's indicator.
* @cssproperty --speed - The time it takes for the spinner to complete one animation cycle.
*/
@customElement('sl-spinner')

12
src/components/split-panel/split-panel.ts
View File

@@ -17,15 +17,15 @@ import type { CSSResultGroup } from 'lit';
*
* @event sl-reposition - Emitted when the divider's position changes.
*
* @slot start - Content to place in the start panel.
* @slot end - Content to place in the end panel.
* @slot divider - The divider. Useful for slotting in a custom icon that renders as a handle.
*
* @csspart start - The start panel.
* @csspart end - The end panel.
* @csspart panel - Targets both the start and end panels.
* @csspart divider - The divider that separates the start and end panels.
*
* @slot start - The start panel.
* @slot end - The end panel.
* @slot divider - The divider. Useful for slotting in a custom icon that renders as a handle in the divider.
*
* @cssproperty [--divider-width=4px] - The width of the visible divider.
* @cssproperty [--divider-hit-area=12px] - The invisible region around the divider where dragging can occur. This is
* usually wider than the divider to facilitate easier dragging.
@@ -49,9 +49,7 @@ export default class SlSplitPanel extends ShoelaceElement {
*/
@property({ type: Number, reflect: true }) position = 50;
/**
* The current position of the divider from the primary panel's edge in pixels.
*/
/** The current position of the divider from the primary panel's edge in pixels. */
@property({ attribute: 'position-in-pixels', type: Number }) positionInPixels: number;
/** Draws the split panel in a vertical orientation with the start and end panels stacked. */

14
src/components/switch/switch.ts
View File

@@ -23,10 +23,10 @@ import type { CSSResultGroup } from 'lit';
* @event sl-change - Emitted when the control's checked state changes.
* @event sl-focus - Emitted when the control gains focus.
*
* @csspart base - The component's internal wrapper.
* @csspart control - The switch control.
* @csspart thumb - The switch position indicator.
* @csspart label - The switch label.
* @csspart base - The component's base wrapper.
* @csspart control - The control that houses the switch's thumb.
* @csspart thumb - The switch's thumb.
* @csspart label - The switch's label.
*
* @cssproperty --width - The width of the switch.
* @cssproperty --height - The height of the switch.
@@ -49,10 +49,10 @@ export default class SlSwitch extends ShoelaceElement implements ShoelaceFormCon
@state() invalid = false;
@property() title = ''; // make reactive to pass through
/** The switch's name attribute. */
/** The name of the switch, submitted as a name/value pair with form data. */
@property() name = '';
/** The switch's value attribute. */
/** The current value of the switch, submitted as a name/value pair with form data. */
@property() value: string;
/** Disables the switch. */
@@ -64,7 +64,7 @@ export default class SlSwitch extends ShoelaceElement implements ShoelaceFormCon
/** Draws the switch in a checked state. */
@property({ type: Boolean, reflect: true }) checked = false;
/** Gets or sets the default value used to reset this element. The initial value corresponds to the one originally specified in the HTML that created this element. */
/** The default value of the form control. Primarily used for resetting the form control. */
@defaultValue('checked') defaultChecked = false;
firstUpdated() {

24
src/components/tab-group/tab-group.ts
View File

@@ -19,24 +19,24 @@ import type { CSSResultGroup } from 'lit';
*
* @dependency sl-icon-button
*
* @slot - Used for grouping tab panels in the tab group.
* @slot nav - Used for grouping tabs in the tab group.
* @slot - Used for grouping tab panels in the tab group. Must be `<sl-tab-panel>` elements.
* @slot nav - Used for grouping tabs in the tab group. Must be `<sl-tab>` elements.
*
* @event {{ name: String }} sl-tab-show - Emitted when a tab is shown.
* @event {{ name: String }} sl-tab-hide - Emitted when a tab is hidden.
*
* @csspart base - The component's internal wrapper.
* @csspart nav - The tab group navigation container.
* @csspart tabs - The container that wraps the slotted tabs.
* @csspart active-tab-indicator - An element that displays the currently selected tab. This is a child of the tabs container.
* @csspart body - The tab group body where tab panels are slotted in.
* @csspart scroll-button - The previous and next scroll buttons that appear when tabs are scrollable.
* @csspart scroll-button--start - Targets the starting scroll button.
* @csspart scroll-button--end - Targets the ending scroll button.
* @csspart scroll-button__base - The scroll button's `base` part.
* @csspart base - The component's base wrapper.
* @csspart nav - The tab group's navigation container where tabs are slotted in.
* @csspart tabs - The container that wraps the tabs.
* @csspart active-tab-indicator - The line that highlights the currently selected tab.
* @csspart body - The tab group's body where tab panels are slotted in.
* @csspart scroll-button - The previous/next scroll buttons that show when tabs are scrollable, an `<sl-icon-button>`.
* @csspart scroll-button--start - The starting scroll button.
* @csspart scroll-button--end - The ending scroll button.
* @csspart scroll-button__base - The scroll button's exported `base` part.
*
* @cssproperty --indicator-color - The color of the active tab indicator.
* @cssproperty --track-color - The color of the indicator's track (i.e. the line that separates tabs from panels).
* @cssproperty --track-color - The color of the indicator's track (the line that separates tabs from panels).
* @cssproperty --track-width - The width of the indicator's track (the line that separates tabs from panels).
*/
@customElement('sl-tab-group')

2
src/components/tab-panel/tab-panel.ts
View File

@@ -15,7 +15,7 @@ import type { CSSResultGroup } from 'lit';
*
* @slot - The tab panel's content.
*
* @csspart base - The component's internal wrapper.
* @csspart base - The component's base wrapper.
*
* @cssproperty --padding - The tab panel's padding.
*/

12
src/components/tab/tab.ts
View File

@@ -21,9 +21,9 @@ import type { CSSResultGroup } from 'lit';
*
* @event sl-close - Emitted when the tab is closable and the close button is activated.
*
* @csspart base - The component's internal wrapper.
* @csspart close-button - The close button.
* @csspart close-button__base - The close button's `base` part.
* @csspart base - The component's base wrapper.
* @csspart close-button - The close button, an `<sl-icon-button>`.
* @csspart close-button__base - The close button's exported `base` part.
*/
@customElement('sl-tab')
export default class SlTab extends ShoelaceElement {
@@ -35,16 +35,16 @@ export default class SlTab extends ShoelaceElement {
private readonly attrId = autoIncrement();
private readonly componentId = `sl-tab-${this.attrId}`;
/** The name of the tab panel the tab will control. The panel must be located in the same tab group. */
/** The name of the tab panel this tab is associated with. The panel must be located in the same tab group. */
@property({ reflect: true }) panel = '';
/** Draws the tab in an active state. */
@property({ type: Boolean, reflect: true }) active = false;
/** Makes the tab closable and shows a close icon. */
/** Makes the tab closable and shows a close button. */
@property({ type: Boolean }) closable = false;
/** Draws the tab in a disabled state. */
/** Disables the tab and prevents selection. */
@property({ type: Boolean, reflect: true }) disabled = false;
connectedCallback() {

12
src/components/tag/tag.ts
View File

@@ -19,17 +19,17 @@ import type { CSSResultGroup } from 'lit';
*
* @event sl-remove - Emitted when the remove button is activated.
*
* @csspart base - The component's internal wrapper.
* @csspart content - The tag content.
* @csspart remove-button - The remove button.
* @csspart remove-button__base - The remove button's `base` part.
* @csspart base - The component's base wrapper.
* @csspart content - The tag's content.
* @csspart remove-button - The tag's remove button, an `<sl-icon-button>`.
* @csspart remove-button__base - The remove button's exported `base` part.
*/
@customElement('sl-tag')
export default class SlTag extends ShoelaceElement {
static styles: CSSResultGroup = styles;
private readonly localize = new LocalizeController(this);
/** The tag's variant. */
/** The tag's theme variant. */
@property({ reflect: true }) variant: 'primary' | 'success' | 'neutral' | 'warning' | 'danger' | 'text' = 'neutral';
/** The tag's size. */
@@ -38,7 +38,7 @@ export default class SlTag extends ShoelaceElement {
/** Draws a pill-style tag with rounded edges. */
@property({ type: Boolean, reflect: true }) pill = false;
/** Makes the tag removable. */
/** Makes the tag removable and shows a remove button. */
@property({ type: Boolean }) removable = false;
handleRemoveClick() {

47
src/components/textarea/textarea.ts
View File

@@ -19,19 +19,19 @@ import type { CSSResultGroup } from 'lit';
* @status stable
*
* @slot label - The textarea's label. Alternatively, you can use the `label` attribute.
* @slot help-text - Help text that describes how to use the input. Alternatively, you can use the `help-text` attribute.
* @slot help-text - Text that describes how to use the input. Alternatively, you can use the `help-text` attribute.
*
* @event sl-change - Emitted when an alteration to the control's value is committed by the user.
* @event sl-input - Emitted when the control receives input and its value changes.
* @event sl-focus - Emitted when the control gains focus.
* @event sl-blur - Emitted when the control loses focus.
*
* @csspart form-control - The form control that wraps the label, input, and help-text.
* @csspart form-control - The form control that wraps the label, input, and help text.
* @csspart form-control-label - The label's wrapper.
* @csspart form-control-input - The input's wrapper.
* @csspart form-control-help-text - The help text's wrapper.
* @csspart base - The component's internal wrapper.
* @csspart textarea - The textarea control.
* @csspart base - The component's base wrapper.
* @csspart textarea - The internal `<textarea>` control.
*/
@customElement('sl-textarea')
export default class SlTextarea extends ShoelaceElement implements ShoelaceFormControl {
@@ -48,25 +48,25 @@ export default class SlTextarea extends ShoelaceElement implements ShoelaceFormC
@state() invalid = false;
@property() title = ''; // make reactive to pass through
/** The textarea's size. */
@property({ reflect: true }) size: 'small' | 'medium' | 'large' = 'medium';
/** The textarea's name attribute. */
/** The name of the textarea, submitted as a name/value pair with form data. */
@property() name = '';
/** The textarea's value attribute. */
/** The current value of the textarea, submitted as a name/value pair with form data. */
@property() value = '';
/** The textarea's size. */
@property({ reflect: true }) size: 'small' | 'medium' | 'large' = 'medium';
/** Draws a filled textarea. */
@property({ type: Boolean, reflect: true }) filled = false;
/** The textarea's label. If you need to display HTML, you can use the `label` slot instead. */
/** The textarea's label. If you need to display HTML, use the `label` slot instead. */
@property() label = '';
/** The textarea's help text. If you need to display HTML, you can use the `help-text` slot instead. */
/** The textarea's help text. If you need to display HTML, use the `help-text` slot instead. */
@property({ attribute: 'help-text' }) helpText = '';
/** The textarea's placeholder text. */
/** Placeholder text to show as a hint when the input is empty. */
@property() placeholder = '';
/** The number of rows to display by default. */
@@ -90,31 +90,34 @@ export default class SlTextarea extends ShoelaceElement implements ShoelaceFormC
/** Makes the textarea a required field. */
@property({ type: Boolean, reflect: true }) required = false;
/** The textarea's autocapitalize attribute. */
/** Controls whether and how text input is automatically capitalized as it is entered by the user. */
@property() autocapitalize: 'off' | 'none' | 'on' | 'sentences' | 'words' | 'characters';
/** The textarea's autocorrect attribute. */
/** Indicates whether the browser's autocorrect feature is on or off. */
@property() autocorrect: string;
/** The textarea's autocomplete attribute. */
/**
* Specifies what permission the browser has to provide assistance in filling out form field values. Refer to
* [this page on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete) for available values.
*/
@property() autocomplete: string;
/** The textarea's autofocus attribute. */
/** Indicates that the input should receive focus on page load. */
@property({ type: Boolean }) autofocus: boolean;
/**
* The input's enterkeyhint attribute. This can be used to customize the label or icon of the Enter key on virtual
* keyboards.
*/
/** Used to customize the label or icon of the Enter key on virtual keyboards. */
@property() enterkeyhint: 'enter' | 'done' | 'go' | 'next' | 'previous' | 'search' | 'send';
/** Enables spell checking on the textarea. */
@property({ type: Boolean }) spellcheck: boolean;
/** The textarea's inputmode attribute. */
/**
* Tells the browser what type of data will be entered by the user, allowing it to display the appropriate virtual
* keyboard on supportive devices.
*/
@property() inputmode: 'none' | 'text' | 'decimal' | 'numeric' | 'tel' | 'search' | 'email' | 'url';
/** Gets or sets the default value used to reset this element. The initial value corresponds to the one originally specified in the HTML that created this element. */
/** The default value of the form control. Primarily used for resetting the form control. */
@defaultValue() defaultValue = '';
connectedCallback() {

15
src/components/tooltip/tooltip.ts
View File

@@ -20,8 +20,8 @@ import type { CSSResultGroup } from 'lit';
*
* @dependency sl-popup
*
* @slot - The tooltip's target element. Only the first element will be used as the target.
* @slot content - The tooltip's content. Alternatively, you can use the `content` attribute.
* @slot - The tooltip's target element. Avoid slotting in more than one element, as subsequent ones will be ignored.
* @slot content - The content to render in the tooltip. Alternatively, you can use the `content` attribute.
*
* @event sl-show - Emitted when the tooltip begins to show.
* @event sl-after-show - Emitted after the tooltip has shown and all animations are complete.
@@ -29,9 +29,9 @@ import type { CSSResultGroup } from 'lit';
* @event sl-after-hide - Emitted after the tooltip has hidden and all animations are complete.
*
* @csspart base - The component's base wrapper, an `<sl-popup>` element.
* @csspart base__popup - The popup's `popup` part. Use this to target the tooltip's popup container.
* @csspart base__arrow - The popup's `arrow` part. Use this to target the tooltip's arrow.
* @csspart body - The tooltip's body.
* @csspart base__popup - The popup's exported `popup` part. Use this to target the tooltip's popup container.
* @csspart base__arrow - The popup's exported `arrow` part. Use this to target the tooltip's arrow.
* @csspart body - The tooltip's body where its content is rendered.
*
* @cssproperty --max-width - The maximum width of the tooltip before its content will wrap.
* @cssproperty --hide-delay - The amount of time to wait before hiding the tooltip when hovering.
@@ -51,7 +51,7 @@ export default class SlTooltip extends ShoelaceElement {
private hoverTimeout: number;
private readonly localize = new LocalizeController(this);
/** The tooltip's content. If you need to display HTML, you can use the `content` slot instead. */
/** The tooltip's content. If you need to display HTML, use the `content` slot instead. */
@property() content = '';
/**
@@ -93,7 +93,8 @@ export default class SlTooltip extends ShoelaceElement {
/**
* Enable this option to prevent the tooltip from being clipped when the component is placed inside a container with
* `overflow: auto|hidden|scroll`.
* `overflow: auto|hidden|scroll`. Hoisting uses a fixed positioning strategy that works in many, but not all,
* scenarios.
*/
@property({ type: Boolean }) hoist = false;

32
src/components/tree-item/tree-item.ts
View File

@@ -28,29 +28,29 @@ export function isTreeItem(node: Node) {
* @dependency sl-icon
* @dependency sl-spinner
*
* @event sl-expand - Emitted when the item expands.
* @event sl-after-expand - Emitted after the item expands and all animations are complete.
* @event sl-collapse - Emitted when the item collapses.
* @event sl-after-collapse - Emitted after the item collapses and all animations are complete.
* @event sl-lazy-change - Emitted when the item's lazy state changes.
* @event sl-expand - Emitted when the tree item expands.
* @event sl-after-expand - Emitted after the tree item expands and all animations are complete.
* @event sl-collapse - Emitted when the tree item collapses.
* @event sl-after-collapse - Emitted after the tree item collapses and all animations are complete.
* @event sl-lazy-change - Emitted when the tree item's lazy state changes.
* @event sl-lazy-load - Emitted when a lazy item is selected. Use this event to asynchronously load data and append
* items to the tree before expanding. After appending new items, remove the `lazy` attribute to remove the loading
* state and update the tree.
*
* @slot - The default slot.
* @slot expand-icon - The icon to show when the item is expanded.
* @slot collapse-icon - The icon to show when the item is collapsed.
* @slot expand-icon - The icon to show when the tree item is expanded.
* @slot collapse-icon - The icon to show when the tree item is collapsed.
*
* @csspart base - The component's internal wrapper.
* @csspart item - The item's main container.
* @csspart item--disabled - Applied when the item is disabled.
* @csspart item--expanded - Applied when the item is expanded.
* @csspart base - The component's base wrapper.
* @csspart item - The tree item's container. This element wraps everything except slotted tree item children.
* @csspart item--disabled - Applied when the tree item is disabled.
* @csspart item--expanded - Applied when the tree item is expanded.
* @csspart item--indeterminate - Applied when the selection is indeterminate.
* @csspart item--selected - Applied when the item is selected.
* @csspart indentation - The item's indentation container.
* @csspart expand-button - The item's expand button.
* @csspart label - The item's label.
* @csspart children - The item's children container.
* @csspart item--selected - Applied when the tree item is selected.
* @csspart indentation - The tree item's indentation container.
* @csspart expand-button - The container that wraps the tree item's expand button and spinner.
* @csspart label - The tree item's label.
* @csspart children - The container that wraps the tree item's nested children.
*/
@customElement('sl-tree-item')
export default class SlTreeItem extends ShoelaceElement {

16
src/components/tree/tree.ts
View File

@@ -42,17 +42,18 @@ function syncCheckboxes(changedTreeItem: SlTreeItem) {
* @since 2.0
* @status experimental
*
* @event {{ selection: TreeItem[] }} sl-selection-change - Emitted when an item gets selected or deselected
* @event {{ selection: TreeItem[] }} sl-selection-change - Emitted when a tree item is selected or deselected.
*
* @slot - The default slot.
* @slot expand-icon - The icon to show when the tree item is expanded.
* @slot collapse-icon - The icon to show when the tree item is collapsed.
* @slot expand-icon - The icon to show when the tree item is expanded. Works best with `<sl-icon>`.
* @slot collapse-icon - The icon to show when the tree item is collapsed. Works best with `<sl-icon>`.
*
* @csspart base - The component's internal wrapper.
* @csspart base - The component's base wrapper.
*
* @cssproperty [--indent-size=var(--sl-spacing-medium)] - The size of the indentation for nested items.
* @cssproperty [--indent-guide-color=var(--sl-color-neutral-200)] - The color of the indentation line.
* @cssproperty [--indent-guide-offset=0] - The amount of vertical spacing to leave between the top and bottom of the indentation line's starting position.
* @cssproperty [--indent-guide-offset=0] - The amount of vertical spacing to leave between the top and bottom of the
* indentation line's starting position.
* @cssproperty [--indent-guide-style=solid] - The style of the indentation line, e.g. solid, dotted, dashed.
* @cssproperty [--indent-guide-width=0] - The width of the indentation line.
*/
@@ -64,7 +65,10 @@ export default class SlTree extends ShoelaceElement {
@query('slot[name=expand-icon]') expandedIconSlot: HTMLSlotElement;
@query('slot[name=collapse-icon]') collapsedIconSlot: HTMLSlotElement;
/** Specifies the selection behavior of the Tree */
/**
* The selection behavior of the tree. Single selection allows only one node to be selected at a time. Multiple
* displays checkboxes and allows more than one node to be selected. Leaf allows only leaf nodes to be selected.
*/
@property() selection: 'single' | 'multiple' | 'leaf' = 'single';
//

2
src/components/visually-hidden/visually-hidden.ts
View File

@@ -10,7 +10,7 @@ import type { CSSResultGroup } from 'lit';
* @since 2.0
* @status stable
*
* @slot - The content you'd like to be visually hidden.
* @slot - The content to be visually hidden.
*/
@customElement('sl-visually-hidden')
export default class SlVisuallyHidden extends ShoelaceElement {

5
src/themes/_utility.css
View File

@@ -20,6 +20,9 @@
}
.sl-toast-stack sl-alert {
--box-shadow: var(--sl-shadow-large);
margin: var(--sl-spacing-medium);
}
.sl-toast-stack sl-alert::part(base) {
box-shadow: var(--sl-shadow-large);
}