From f2efa73e20cc80dc725b4055608baa1df2bd7d02 Mon Sep 17 00:00:00 2001 From: Cory LaViska Date: Tue, 6 Dec 2022 11:18:14 -0500 Subject: [PATCH] improve documentation --- docs/components/button-group.md | 60 +++++++------- docs/components/button.md | 2 +- docs/components/popup.md | 2 +- docs/components/visually-hidden.md | 4 +- docs/getting-started/usage.md | 4 +- docs/resources/changelog.md | 5 ++ .../plop/templates/component/component.hbs | 2 +- src/components/alert/alert.styles.ts | 1 - src/components/alert/alert.ts | 28 +++---- .../animated-image/animated-image.styles.ts | 6 ++ .../animated-image/animated-image.ts | 16 ++-- src/components/animation/animation.ts | 11 ++- src/components/avatar/avatar.ts | 10 +-- src/components/badge/badge.ts | 4 +- .../breadcrumb-item/breadcrumb-item.ts | 8 +- src/components/breadcrumb/breadcrumb.ts | 10 +-- src/components/button-group/button-group.ts | 7 +- src/components/button/button.ts | 39 ++++++---- src/components/card/card.ts | 24 +++--- src/components/checkbox/checkbox.ts | 40 ++++++---- src/components/color-picker/color-picker.ts | 51 ++++++------ src/components/details/details.ts | 21 ++--- src/components/dialog/dialog.ts | 28 +++---- src/components/drawer/drawer.ts | 28 +++---- src/components/dropdown/dropdown.ts | 18 +++-- src/components/format-bytes/format-bytes.ts | 2 +- src/components/format-date/format-date.ts | 8 +- src/components/format-number/format-number.ts | 12 +-- src/components/icon-button/icon-button.ts | 13 ++-- src/components/icon/icon.ts | 14 ++-- .../image-comparer/image-comparer.ts | 6 +- src/components/include/include.ts | 9 +-- src/components/input/input.ts | 78 ++++++++++--------- src/components/menu-item/menu-item.ts | 2 +- src/components/menu-label/menu-label.ts | 2 +- .../mutation-observer/mutation-observer.ts | 4 +- src/components/popup/popup.ts | 2 +- src/components/progress-bar/progress-bar.ts | 18 ++--- src/components/progress-ring/progress-ring.ts | 11 +-- src/components/qr-code/qr-code.styles.ts | 12 --- src/components/qr-code/qr-code.ts | 26 +++---- src/components/radio-button/radio-button.ts | 30 +++---- src/components/radio-group/radio-group.ts | 19 ++--- src/components/radio/radio.ts | 12 +-- src/components/range/range.ts | 43 +++++----- src/components/rating/rating.ts | 15 +++- src/components/relative-time/relative-time.ts | 8 +- src/components/select/select.ts | 54 ++++++------- src/components/skeleton/skeleton.ts | 2 +- src/components/spinner/spinner.ts | 4 +- src/components/split-panel/split-panel.ts | 12 ++- src/components/switch/switch.ts | 14 ++-- src/components/tab-group/tab-group.ts | 24 +++--- src/components/tab-panel/tab-panel.ts | 2 +- src/components/tab/tab.ts | 12 +-- src/components/tag/tag.ts | 12 +-- src/components/textarea/textarea.ts | 47 +++++------ src/components/tooltip/tooltip.ts | 15 ++-- src/components/tree-item/tree-item.ts | 32 ++++---- src/components/tree/tree.ts | 16 ++-- .../visually-hidden/visually-hidden.ts | 2 +- src/themes/_utility.css | 5 +- 62 files changed, 553 insertions(+), 475 deletions(-) diff --git a/docs/components/button-group.md b/docs/components/button-group.md index fd99a8e1..841d8bd1 100644 --- a/docs/components/button-group.md +++ b/docs/components/button-group.md @@ -3,7 +3,7 @@ [component-header:sl-button-group] ```html preview - + Left Center Right @@ -14,7 +14,7 @@ import { SlButton, SlButtonGroup } from '@shoelace-style/shoelace/dist/react'; const App = () => ( - + Left Center Right @@ -29,7 +29,7 @@ const App = () => ( All button sizes are supported, but avoid mixing sizes within the same button group. ```html preview - + Left Center Right @@ -37,7 +37,7 @@ All button sizes are supported, but avoid mixing sizes within the same button gr

- + Left Center Right @@ -45,7 +45,7 @@ All button sizes are supported, but avoid mixing sizes within the same button gr

- + Left Center Right @@ -57,7 +57,7 @@ import { SlButton, SlButtonGroup } from '@shoelace-style/shoelace/dist/react'; const App = () => ( <> - + Left Center Right @@ -66,7 +66,7 @@ const App = () => (

- + Left Center Right @@ -75,7 +75,7 @@ const App = () => (

- + Left Center Right @@ -89,7 +89,7 @@ const App = () => ( Theme buttons are supported through the button's `variant` attribute. ```html preview - + Left Center Right @@ -97,7 +97,7 @@ Theme buttons are supported through the button's `variant` attribute.

- + Left Center Right @@ -105,7 +105,7 @@ Theme buttons are supported through the button's `variant` attribute.

- + Left Center Right @@ -113,7 +113,7 @@ Theme buttons are supported through the button's `variant` attribute.

- + Left Center Right @@ -121,7 +121,7 @@ Theme buttons are supported through the button's `variant` attribute.

- + Left Center Right @@ -133,7 +133,7 @@ import { SlButton, SlButtonGroup } from '@shoelace-style/shoelace/dist/react'; const App = () => ( <> - + Left Center Right @@ -142,7 +142,7 @@ const App = () => (

- + Left Center Right @@ -151,7 +151,7 @@ const App = () => (

- + Left Center Right @@ -160,7 +160,7 @@ const App = () => (

- + Left Center Right @@ -169,7 +169,7 @@ const App = () => (

- + Left Center Right @@ -183,7 +183,7 @@ const App = () => ( Pill buttons are supported through the button's `pill` attribute. ```html preview - + Left Center Right @@ -191,7 +191,7 @@ Pill buttons are supported through the button's `pill` attribute.

- + Left Center Right @@ -199,7 +199,7 @@ Pill buttons are supported through the button's `pill` attribute.

- + Left Center Right @@ -211,7 +211,7 @@ import { SlButton, SlButtonGroup } from '@shoelace-style/shoelace/dist/react'; const App = () => ( <> - + Left @@ -226,7 +226,7 @@ const App = () => (

- + Left @@ -241,7 +241,7 @@ const App = () => (

- + Left @@ -261,7 +261,7 @@ const App = () => ( Dropdowns can be placed inside button groups as long as the trigger is an `` element. ```html preview - + Button Button @@ -279,7 +279,7 @@ Dropdowns can be placed inside button groups as long as the trigger is an ` ( - + Button Button @@ -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 - + Save @@ -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 = () => ( - + Save @@ -339,7 +339,7 @@ const App = () => ( Buttons can be wrapped in tooltips to provide more detail when the user interacts with them. ```html preview - + Left @@ -359,7 +359,7 @@ import { SlButton, SlButtonGroup, SlTooltip } from '@shoelace-style/shoelace/dis const App = () => ( <> - + Left diff --git a/docs/components/button.md b/docs/components/button.md index d023e1f7..649d928f 100644 --- a/docs/components/button.md +++ b/docs/components/button.md @@ -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 `` in the default slot. ```html preview diff --git a/docs/components/popup.md b/docs/components/popup.md index 54755865..33da2eab 100644 --- a/docs/components/popup.md +++ b/docs/components/popup.md @@ -6,7 +6,7 @@ This component's name is inspired by [``](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 `` 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 `` will involve building other components. It should rarely, if ever, occur directly in your HTML. ```html preview
diff --git a/docs/components/visually-hidden.md b/docs/components/visually-hidden.md index 80b80b10..e78714f7 100644 --- a/docs/components/visually-hidden.md +++ b/docs/components/visually-hidden.md @@ -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 -
+
Skip to main content @@ -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 diff --git a/docs/getting-started/usage.md b/docs/getting-started/usage.md index 9836762e..cc90e9b4 100644 --- a/docs/getting-started/usage.md +++ b/docs/getting-started/usage.md @@ -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 Click me ``` -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 diff --git a/docs/resources/changelog.md b/docs/resources/changelog.md index eaf00159..c80941ec 100644 --- a/docs/resources/changelog.md +++ b/docs/resources/changelog.md @@ -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 `` to the current date instead of the Unix epoch - 🚨 BREAKING: removed the `handle-icon` part and slot from `` (use `handle` instead) - 🚨 BREAKING: removed the `handle` slot from `` (use the `divider` slot instead) +- 🚨 BREAKING: removed the `--box-shadow` custom property from `` (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 `` and `` - Added the `expand-icon` and `collapse-icon` slots to `` and refactored the icon animation [#1046](https://github.com/shoelace-style/shoelace/discussions/1046) +- Added the `play-icon` and `pause-icon` slots to `` so you can customize the default icons - Fixed a bug in `` 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 `` 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 `` 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 `` so it matches with nested `` 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 `` so the alert is announced and the close button has a label +- Improved accessibility of `` 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 `` diff --git a/scripts/plop/templates/component/component.hbs b/scripts/plop/templates/component/component.hbs index 4c671edb..7bb28a0d 100644 --- a/scripts/plop/templates/component/component.hbs +++ b/scripts/plop/templates/component/component.hbs @@ -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. */ diff --git a/src/components/alert/alert.styles.ts b/src/components/alert/alert.styles.ts index 1881cdff..c8096d8e 100644 --- a/src/components/alert/alert.styles.ts +++ b/src/components/alert/alert.styles.ts @@ -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); diff --git a/src/components/alert/alert.ts b/src/components/alert/alert.ts index c94a3bbb..9c06f160 100644 --- a/src/components/alert/alert.ts +++ b/src/components/alert/alert.ts @@ -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 ``. * * @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 ``. + * @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; diff --git a/src/components/animated-image/animated-image.styles.ts b/src/components/animated-image/animated-image.styles.ts index cb75917d..9d2944e0 100644 --- a/src/components/animated-image/animated-image.styles.ts +++ b/src/components/animated-image/animated-image.styles.ts @@ -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; + } `; diff --git a/src/components/animated-image/animated-image.ts b/src/components/animated-image/animated-image.ts index f6eb345b..db76fdb1 100644 --- a/src/components/animated-image/animated-image.ts +++ b/src/components/animated-image/animated-image.ts @@ -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 ``. + * @slot pause-icon - Optional pause icon to use instead of the default. Works best with ``. + * * @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 { />
- ${this.play - ? html`` - : html``} + +
` : ''} diff --git a/src/components/animation/animation.ts b/src/components/animation/animation.ts index b86aabc5..13311860 100644 --- a/src/components/animation/animation.ts +++ b/src/components/animation/animation.ts @@ -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 `` 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(); } diff --git a/src/components/avatar/avatar.ts b/src/components/avatar/avatar.ts index a3559346..78c529df 100644 --- a/src/components/avatar/avatar.ts +++ b/src/components/avatar/avatar.ts @@ -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 ``. * - * @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. */ diff --git a/src/components/badge/badge.ts b/src/components/badge/badge.ts index b0ea10a3..17b97926 100644 --- a/src/components/badge/badge.ts +++ b/src/components/badge/badge.ts @@ -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. */ diff --git a/src/components/breadcrumb-item/breadcrumb-item.ts b/src/components/breadcrumb-item/breadcrumb-item.ts index 238eaf48..5d26fdf9 100644 --- a/src/components/breadcrumb-item/breadcrumb-item.ts +++ b/src/components/breadcrumb-item/breadcrumb-item.ts @@ -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 `` 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 { diff --git a/src/components/breadcrumb/breadcrumb.ts b/src/components/breadcrumb/breadcrumb.ts index ad39d9a8..ccf9d6eb 100644 --- a/src/components/breadcrumb/breadcrumb.ts +++ b/src/components/breadcrumb/breadcrumb.ts @@ -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 ``. * * @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() { diff --git a/src/components/button-group/button-group.ts b/src/components/button-group/button-group.ts index e693f11c..1d89cc65 100644 --- a/src/components/button-group/button-group.ts +++ b/src/components/button-group/button-group.ts @@ -12,7 +12,7 @@ import type { CSSResultGroup } from 'lit'; * * @slot - One or more `` 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) { diff --git a/src/components/button/button.ts b/src/components/button/button.ts index ce2e9adf..314eeced 100644 --- a/src/components/button/button.ts +++ b/src/components/button/button.ts @@ -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 `` 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 `` 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 `
`; } diff --git a/src/components/qr-code/qr-code.styles.ts b/src/components/qr-code/qr-code.styles.ts index 99a10c06..ec928598 100644 --- a/src/components/qr-code/qr-code.styles.ts +++ b/src/components/qr-code/qr-code.styles.ts @@ -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%; - } `; diff --git a/src/components/qr-code/qr-code.ts b/src/components/qr-code/qr-code.ts index 70486f46..5229ab52 100644 --- a/src/components/qr-code/qr-code.ts +++ b/src/components/qr-code/qr-code.ts @@ -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` - + > `; } } diff --git a/src/components/radio-button/radio-button.ts b/src/components/radio-button/radio-button.ts index 78a937c5..0acee6ee 100644 --- a/src/components/radio-button/radio-button.ts +++ b/src/components/radio-button/radio-button.ts @@ -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 `