diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 603d1dc3..d7029a6b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -105,3 +105,7 @@ Boolean props should _always_ default to `false`, otherwise there's no way for t The Shoelace _source_ is developed using Sass for the convenience of nested selectors, imports, and tedious things such as color palette generation. By design, Sass variables, color functions, and other preprocessor-specific feaures are not used in the source and will not be accepted in a PR. Consumers of the library should never need to worry about preprocessing the library. + +### Positioning Popovers + +Shoelace uses an internal popover utility for dropdowns, tooltips, etc. This is a light abstraction of Popper.js designed to make positioning and transitioning things easy and consistent throughout the library. When possible, use this utility instead of relying on Popper directly. See `src/utilities/popover.ts` for details. diff --git a/docs/components/color-picker.md b/docs/components/color-picker.md index de5a25d7..c3283d7a 100644 --- a/docs/components/color-picker.md +++ b/docs/components/color-picker.md @@ -12,38 +12,28 @@ Color pickers allow the user to select a color. ### Opacity +Use the `opacity` attribute to enable the opacity slider. When this is enabled, the value will be displayed as HEXA, RGBA, or HSLA based on `format`. + ```html preview ``` -### RGB +### Formats + +Set the color picker's format with the `format` attribute. Valid options include `hex`, `rgb`, and `hsl`. Note that the color picker will accept any parsable format (including CSS color names) regardless of this option. ```html preview - -``` - -### RGBA - -```html preview - -``` - -### HSL - -```html preview - -``` - -### HSLA - -```html preview - + + + ``` ### Inline +The color picker can be rendered inline instead of in a dropdown using the `inline` attribute. + ```html preview - + ``` [component-metadata:sl-color-picker] diff --git a/docs/components/details.md b/docs/components/details.md index 4d7c65a8..09b9fc3c 100644 --- a/docs/components/details.md +++ b/docs/components/details.md @@ -15,6 +15,8 @@ Details show a brief summary and expand to show additional content. ### Disabled +Use the `disable` attribute to prevent the details from expanding. + ```html preview Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna @@ -55,7 +57,7 @@ Details are designed to function independently, but you can simulate a group or ``` diff --git a/docs/components/dialog.md b/docs/components/dialog.md index 1c44e097..baf4e18c 100644 --- a/docs/components/dialog.md +++ b/docs/components/dialog.md @@ -32,6 +32,30 @@ Dialogs appear above the page and require the user's immediate attention. ## Examples +### Custom Width + +Use the `--width` custom property to set the dialog's width. + +```html preview + + Lorem ipsum dolor sit amet, consectetur adipiscing elit. + Close + + +Open Dialog + + +``` + ### Scrolling By design, a dialog's height will never exceed that of the viewport. As such, dialogs will not scroll with the page ensuring the header and footer are always accessible to the user. @@ -58,7 +82,7 @@ By design, a dialog's height will never exceed that of the viewport. As such, di ``` -### Ignore Overlay Clicks +### Ignoring Clicks on the Overlay By default, dialogs are closed when the user clicks or taps on the overlay. To prevent this behavior, cancel the `slOverlayDismiss` event. diff --git a/docs/components/drawer.md b/docs/components/drawer.md index ef654e4a..06ff8b91 100644 --- a/docs/components/drawer.md +++ b/docs/components/drawer.md @@ -28,6 +28,8 @@ Drawers slide out from a container to expose additional options and information. ### Placement +Drawers slide out from the right by default. To slide them out from the left, use the `placement` attribute. + ```html preview This drawer slides in from the left. @@ -48,7 +50,7 @@ Drawers slide out from a container to expose additional options and information. ``` -### Contained +### Contained to an Element By default, the drawer slides out of its [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block#Identifying_the_containing_block), which is usually the viewport. To make the drawer slide out of its parent element, set this prop and add `position: relative` to the parent. @@ -78,6 +80,30 @@ By default, the drawer slides out of its [containing block](https://developer.mo ``` +### Custom Width + +Use the `--width` custom property to set the drawer's width. + +```html preview + + This drawer is always 50% of the viewport. + Close + + +Open Drawer + + +``` + ### Scrolling By design, a drawer's height is 100% of its container and will never exceed that of the viewport. As such, drawers will not scroll with the page ensuring the header and footer are always accessible to the user. @@ -104,70 +130,7 @@ By design, a drawer's height is 100% of its container and will never exceed that ``` -### Custom Width - -```html preview - - This drawer is always 50% of the viewport. - Close - - -Open Drawer - - -``` - -### No Header - -```html preview - - This drawer doesn't have a header. - Close - - -Open Drawer - - -``` - -### No Footer - -```html preview - - This drawer doesn't have a footer. - - -Open Drawer - - -``` - -### Ignore Overlay Clicks +### Ignoring Clicks on the Overlay By default, drawers are closed when the user clicks or taps on the overlay. To prevent this behavior, cancel the `slOverlayDismiss` event. diff --git a/docs/components/dropdown.md b/docs/components/dropdown.md index 134bd8ea..d6d21d44 100644 --- a/docs/components/dropdown.md +++ b/docs/components/dropdown.md @@ -4,7 +4,7 @@ Dropdowns expose additional content that "drops down" in a panel. -Dropdowns consist of a trigger and a panel. Activating the trigger will open the panel and interacting outside of the panel will close it. +Dropdowns consist of a trigger and a panel. By default, activating the trigger will expose the panel and interacting outside of the panel will close it. Dropdowns are designed to work well with [menus](/components/menu.md) to provide a list of options the user can select from. However, dropdowns can also be used in lower-level applications (e.g. [color picker](/components/color-picker.md) and [select](/components/select.md)). The API gives you complete control over showing, hiding, and positioning the panel. @@ -35,6 +35,8 @@ Dropdowns are designed to work well with [menus](/components/menu.md) to provide ### Placement +The preferred placement of the dropdown can be set with the `placement` attribute. Note that the actual position may vary to ensure the panel remains in the viewport. + ```html preview Edit @@ -51,6 +53,8 @@ Dropdowns are designed to work well with [menus](/components/menu.md) to provide ### Distance +The distance from the panel to the trigger can be customized using the `distance` attribute. This value is specified in pixels. + ```html preview Edit @@ -67,6 +71,8 @@ Dropdowns are designed to work well with [menus](/components/menu.md) to provide ### Skidding +The offset of the panel along the trigger can be customized using the `skidding` attribute. This value is specified in pixels. + ```html preview Edit @@ -81,34 +87,4 @@ Dropdowns are designed to work well with [menus](/components/menu.md) to provide ``` -### Scrolling Content - -```html preview - - Scrolling Menu - - Item 1 - Item 2 - Item 3 - Item 4 - Item 5 - Item 6 - Item 7 - Item 8 - Item 9 - Item 10 - Item 11 - Item 12 - Item 13 - Item 14 - Item 15 - Item 16 - Item 17 - Item 18 - Item 19 - Item 20 - - -``` - [component-metadata:sl-dropdown] diff --git a/docs/components/form.md b/docs/components/form.md index d79b9b68..2f1978dc 100644 --- a/docs/components/form.md +++ b/docs/components/form.md @@ -4,7 +4,9 @@ Forms collect data that can easily be processed and sent to a server. -All of Shoelace's components make use of the [shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM) to encapsulate markup, style, and behavior. One caveat of this approach is that native `
` elements don't recognize Shoelace form controls. This component solves that problem by serializing _both_ Shoelace form controls and native form controls. +All of Shoelace's components make use of the [shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM) to encapsulate markup, style, and behavior. One caveat of this approach is that native `` elements don't recognize Shoelace form controls. + +This component solves that problem by serializing _both_ Shoelace form controls and native form controls. The resulting form data is exposed in the `slSubmit` event in a [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) object. ```html preview @@ -28,21 +30,21 @@ All of Shoelace's components make use of the [shadow DOM](https://developer.mozi form.addEventListener('slSubmit', event => { const formData = event.detail.formData; - const formControls = event.detail.formControls; let output = ''; - // do something with the form data... + // Do something with the form data for (const entry of formData.entries()) { output += `${entry[0]}: ${entry[1]}\n`; } alert(output); - // ...or do something with the raw form controls - console.log(formControls); + // Tip: you can also access every form control that was serialized, which + // is useful for validation purposes. + console.log(event.detail.formControls); }); ``` -?> Shoelace forms don't make use of `action` and `method` attributes, and they don't submit automatically like native forms. To handle submission, you need to listen for the `slSubmit` event as shown in the example above. +?> Shoelace forms don't make use of `action` and `method` attributes and they don't submit automatically like native forms. To handle submission, you need to listen for the `slSubmit` event as shown in the example above. [component-metadata:sl-form] diff --git a/docs/components/input.md b/docs/components/input.md index e5786273..2cd42bd4 100644 --- a/docs/components/input.md +++ b/docs/components/input.md @@ -5,7 +5,7 @@ Inputs collect data from the user. ```html preview - + ``` ?> This component doesn't work with standard forms. Use [``](/components/form.md) instead. @@ -14,14 +14,26 @@ Inputs collect data from the user. ### Labels +Use the `label` attribute to give the input an accessible label. + ```html preview
``` +### Placeholder + +Use the `placeholder` attribute to add a placeholder. + +```html preview + +``` + ### Size +Use the `size` attribute to change an input's size. + ```html preview
@@ -32,6 +44,8 @@ Inputs collect data from the user. ### Pill +Use the `pill` prop to give inputs rounded edges. + ```html preview
@@ -42,6 +56,8 @@ Inputs collect data from the user. ### Prefix & Suffix Icons +Use the `prefix` and `suffix` slots to add icons. + ```html preview @@ -61,6 +77,8 @@ Inputs collect data from the user. ### Clearable +Add the `clearable` prop to add a clear button when the input has content. + ```html preview
@@ -71,6 +89,8 @@ Inputs collect data from the user. ### Toggle Password +Add the `toggle-password` prop to add a toggle button that will show the password when activated. + ```html preview
@@ -81,6 +101,8 @@ Inputs collect data from the user. ### Disabled +Use the `disabled` attribute to disable an input. + ```html preview
diff --git a/docs/components/menu.md b/docs/components/menu.md index 1fd0c414..0c03a106 100644 --- a/docs/components/menu.md +++ b/docs/components/menu.md @@ -4,6 +4,8 @@ Menus provide a list of options for the user. +Use [menu items](/components/menu-item.md), [menu dividers](/components/menu-divider.md), and [menu labels](/components/menu-label.md) to compose a menu. + ```html preview
-
-
-
- + ``` ## Examples -### Custom Height & Label +### Custom Height + +Use the `--height` custom property to set the progress bar's height. ```html preview -0%
-25%
-50%
-75%
-100% + +``` + +### Labels + +Use the default slot to show a label. + +```html preview +50% + +
+ + + + + ``` [component-metadata:sl-progress-bar] diff --git a/docs/components/progress-ring.md b/docs/components/progress-ring.md index bd34c173..cd7b40d8 100644 --- a/docs/components/progress-ring.md +++ b/docs/components/progress-ring.md @@ -5,25 +5,56 @@ Progress rings are used to show the progress of a determinate operation in a circular fashion. ```html preview -
- 0%
- 25%
- 50%
- 75%
- 100% -
+
``` ## Examples ### Size +Use the `size` attribute to set the diameter of the progress ring. + ```html preview -
- 50%
- 50%
- 50%
-
+
+``` + +### Stroke Width + +Use the `stroke-width` attribute to set the width of the progress ring's indicator. + +```html preview +
+``` + +### Labels + +Use the default slot to show a label. + +```html preview +50% + +
+ + + + + ``` [component-metadata:sl-progress-ring] diff --git a/docs/components/range.md b/docs/components/range.md index 0c03f070..73ee8bab 100644 --- a/docs/components/range.md +++ b/docs/components/range.md @@ -12,7 +12,33 @@ Ranges allow the user to select a single value within a given range using a slid ## Examples -### Custom Formatter +### Disabled + +Use the `disabled` prop to disable a slider. + +```html preview + +``` + +### Tooltip Placement + +By default, the tooltip is shown on top. Set `tooltip` to `bottom` to show it below the slider. + +```html preview + +``` + +### Disable the Tooltip + +To disable the tooltip, set `tooltip` to `none`. + +```html preview + +``` + +### Custom Tooltip Formatter + +You can change the tooltip's content by setting the `tooltipFormatter` prop to a function that accepts the range's value as an argument. ```html preview @@ -23,16 +49,4 @@ Ranges allow the user to select a single value within a given range using a slid ``` -### Without Tooltip - -```html preview - -``` - -### Disabled - -```html preview - -``` - [component-metadata:sl-range] diff --git a/docs/components/select.md b/docs/components/select.md index 7b6ba406..fc44ed58 100644 --- a/docs/components/select.md +++ b/docs/components/select.md @@ -2,9 +2,7 @@ [component-header:sl-select] -Selects... - -Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. +Selects allow you to choose one or more items from a dropdown menu. ```html preview @@ -24,6 +22,8 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i ### Labels +Use the `label` attribute to give the select an accessible label. + ```html preview Option 1 @@ -34,6 +34,8 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i ### Multiple +To allow multiple options to be selected, use the `multiple` attribute. + ```html preview Option 1 @@ -48,6 +50,8 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i ### Size +Use the `size` attribute to change a select's size. + ```html preview Option 1 @@ -72,8 +76,22 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i ``` +### Pill + +Use the `pill` prop to give selects rounded edges. + +```html preview + + Option 1 + Option 2 + Option 3 + +``` + ### Groups +Options can be grouped visually using menu labels and menu dividers. + ```html preview Group 1 @@ -90,6 +108,8 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i ### Disabled +Use the `disabled` prop to disable a select. + ```html preview Option 1 diff --git a/docs/components/tab-group.md b/docs/components/tab-group.md index 29117d45..5852c4cf 100644 --- a/docs/components/tab-group.md +++ b/docs/components/tab-group.md @@ -4,6 +4,8 @@ Tab groups organize content into a container that shows one section at a time. +Tab groups make use of [tabs](/components/tab.md) and [tab panels](/components/tab-panel.md). Each tab must be slotted into the `nav` slot and its `panel` must refer to a tab panel of the same name. + ```html preview General @@ -22,6 +24,8 @@ Tab groups organize content into a container that shows one section at a time. ### Tabs on Bottom +Tabs can be shown on the bottom by setting `placement` to `bottom`. + ```html preview General @@ -38,6 +42,8 @@ Tab groups organize content into a container that shows one section at a time. ### Tabs on Left +Tabs can be shown on the left by setting `placement` to `left`. + ```html preview General @@ -54,6 +60,8 @@ Tab groups organize content into a container that shows one section at a time. ### Tabs on Right +Tabs can be shown on the right by setting `placement` to `right`. + ```html preview General @@ -70,6 +78,8 @@ Tab groups organize content into a container that shows one section at a time. ### Scrolling Tabs +When there are more tabs than horizontal space allows, the nav will be scrollable. + ```html preview Tab 1 diff --git a/docs/components/tag.md b/docs/components/tag.md index 2b3b3f4b..8f719daa 100644 --- a/docs/components/tag.md +++ b/docs/components/tag.md @@ -16,6 +16,8 @@ Tags are used as labels to organize things or to indicate a selection. ### Size +Use the `size` prop to change a tab's size. + ```html preview Primary Success @@ -42,6 +44,8 @@ Tags are used as labels to organize things or to indicate a selection. ### Pill +Use the `pill` prop to give tabs rounded edges. + ```html preview Primary Success @@ -68,6 +72,8 @@ Tags are used as labels to organize things or to indicate a selection. ### Removable +Use the `removable` attribute to add a remove button to the tag. + ```html preview Primary Success diff --git a/docs/components/textarea.md b/docs/components/textarea.md index d6e47bd1..108458e8 100644 --- a/docs/components/textarea.md +++ b/docs/components/textarea.md @@ -5,7 +5,7 @@ Textareas collect data from the user and allow multiple lines of text. ```html preview - + ``` ?> This component doesn't work with standard forms. Use [``](/components/form.md) instead. @@ -14,26 +14,50 @@ Textareas collect data from the user and allow multiple lines of text. ### Labels +Use the `label` attribute to give the textarea an accessible label. + ```html preview ``` -### No Resize +### Rows + +Use the `rows` attribute to change the number of text rows that get shown. ```html preview - + ``` -### Resize to Content +### Placeholders + +Use the `placeholder` attribute to add a placeholder. ```html preview - + ``` ### Disabled +Use the `disabled` attribute to disable an input. + ```html preview ``` +### Prevent Resizing + +By default, textareas can be resized vertically by the user. To prevent resizing, set the `resize` attribute to `none`. + +```html preview + +``` + +### Expand with Content + +Textareas will automatically resize to expand to fit their content when `resize` is set to `auto`. + +```html preview + +``` + [component-metadata:sl-textarea] diff --git a/docs/components/tooltip.md b/docs/components/tooltip.md index 6d7b4732..6d9c5545 100644 --- a/docs/components/tooltip.md +++ b/docs/components/tooltip.md @@ -18,6 +18,8 @@ Tooltip's use `display: contents` so they won't interfere with how elements are ### Placement +Use the `placement` attribute to set the preferred placement of the tooltip. + ```html preview
@@ -109,6 +111,8 @@ Tooltip's use `display: contents` so they won't interfere with how elements are ### Click Trigger +Set the `trigger` attribute to `click` to toggle the tooltip on click instead of hover. + ```html preview Click to Toggle @@ -117,10 +121,12 @@ Tooltip's use `display: contents` so they won't interfere with how elements are ### Manual Trigger +Tooltips can be controller programmatically by setting the `trigger` attribute to `manual`. Use the `open` prop to control when the tooltip is shown. + ```html preview Toggle Manually - + @@ -132,10 +138,12 @@ Tooltip's use `display: contents` so they won't interfere with how elements are ``` -### No Arrows +### Remove Arrows + +You can control the size of tooltip arrows by overriding the `--sl-tooltip-arrow-size` design token. ```html preview -
+
Above @@ -146,4 +154,13 @@ Tooltip's use `display: contents` so they won't interfere with how elements are
``` +To override it globally, set it in a root block in your stylesheet after `shoelace.css` is loaded. + +```css +:root { + --sl-tooltip-arrow-size: 0; +} +``` + + [component-metadata:sl-tooltip]