@warp-ds/elements 2.10.0-next.2 → 2.10.0-next.20

package/dist/docs/expandable/expandable.md

@@ -4,109 +4,151 @@
 
 Expandable is a layout component used for creating expandable content areas on a page.
 
-[See Storybook for usage examples](https://warp-ds.github.io/elements/?path=/docs/layout-expandable--docs)
-
 ## Usage
 
 ## Accessibility
 
 ## Examples
 
-## `<w-expandable>` API
+<elements-example>
 
-Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).
+```html
+<w-expandable title="I'm expandable" animated>
+  <p>with expanded content</p>
+</w-expandable>
+```
 
-### Properties
+</elements-example>
 
-| Name | Type | Default | Summary |
-|-|-|-|-|
-| _hasTitle | `boolean` | `true` | - |
-| _showChevronUp | `boolean` | `false` | - |
-| animated | `boolean` | `false` | - |
-| bleed | `boolean` | `false` | - |
-| box | `boolean` | `false` | - |
-| button-class | `string` | `-` | - |
-| content-class | `string` | `-` | - |
-| expanded | `boolean` | `false` | - |
-| heading-level | `number` | `-` | - |
-| no-chevron | `boolean` | `false` | - |
-| title | `string` | `-` | - |
+### Expandable box
 
-### Property Details
+<elements-example>
 
-#### _hasTitle
+```html
+<w-expandable title="I'm expandable" animated box>
+  <p>with expanded content</p>
+</w-expandable>
+```
 
+</elements-example>
 
 
-- Type: `boolean`
-- Default: `true`
+### Expandable box with custom title
 
-#### _showChevronUp
+This can be used if more control over styling is needed than the `title` prop allows
 
+<elements-example>
 
+```html
+<w-expandable animated box>
+  <div slot="title" class="flex flex-row items-center">
+    <w-icon-bag-16></w-icon-bag-16>
+    <p class="ml-8 mb-0">This is a title with an icon</p>
+  </div>
+  <p>with expanded content</p>
+</w-expandable>
+```
 
-- Type: `boolean`
-- Default: `false`
+</elements-example>
 
-#### animated
 
+### With expanded prop
+
+<elements-example>
+
+```html
+<w-expandable animated box title="I'm expanded by default" expanded>
+  <p>content should be visible</p>
+</w-expandable>
+```
+
+</elements-example>
+
+## Styling API
+
+## `<w-expandable>` API
+
+Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).
+
+### Properties
+
+| Name | Type | Default | Summary |
+|-|-|-|-|
+| animated | `boolean` | `false` | Will animate the expansion/collapse |
+| bleed | `boolean` | `false` | Will make the expandable full-width on the sm breakpoint size |
+| box | `boolean` | `false` | Will make the expandable a Box |
+| button-class | `string \| undefined` | `-` | **Deprecated**: Probably does not work the way you expect. The class must exist inside the shadow DOM of the component. |
+| content-class | `string \| undefined` | `-` | **Deprecated**: Probably does not work the way you expect. The class must exist inside the shadow DOM of the component. |
+| expanded | `boolean` | `false` | Controls component's expanded state |
+| heading-level | `number \| undefined` | `-` | Wrap the toggle button in a heading element with the specified level. If headingLevel is not specified, the button will not be wrapped by a heading element. |
+| no-chevron | `boolean` | `false` | Controls chevron visibility |
+| title | `string` | `-` | Component title. Used to display the title value which is always present regardless of whether the component is open or closed. |
+
+### Property Details
 
+#### animated
+
+Will animate the expansion/collapse
 
 - Type: `boolean`
 - Default: `false`
 
 #### bleed
 
-
+Will make the expandable full-width on the sm breakpoint size
 
 - Type: `boolean`
 - Default: `false`
 
 #### box
 
-
+Will make the expandable a Box
 
 - Type: `boolean`
 - Default: `false`
 
 #### button-class
 
+**Deprecated**: Probably does not work the way you expect. The class must exist inside the shadow DOM of the component.
 
 
-- Type: `string`
+
+- Type: `string | undefined`
 - Default: `-`
 
 #### content-class
 
+**Deprecated**: Probably does not work the way you expect. The class must exist inside the shadow DOM of the component.
 
 
-- Type: `string`
+
+- Type: `string | undefined`
 - Default: `-`
 
 #### expanded
 
-
+Controls component's expanded state
 
 - Type: `boolean`
 - Default: `false`
 
 #### heading-level
 
+Wrap the toggle button in a heading element with the specified level. If headingLevel is not specified, the button will not be wrapped by a heading element.
 
-
-- Type: `number`
+- Type: `number | undefined`
 - Default: `-`
 
 #### no-chevron
 
-
+Controls chevron visibility
 
 - Type: `boolean`
 - Default: `false`
 
 #### title
 
-
+Component title. Used to display the title value which is always present regardless of whether the component is open or closed.
 
 - Type: `string`
 - Default: `-`

package/dist/docs/expandable/styling.md

@@ -0,0 +1 @@
+## Styling API

package/dist/docs/icon/accessibility.md

@@ -0,0 +1,5 @@
+## Accessibility
+
+Icons ship with a localized descriptive `<title>`.
+
+Note that the description is about the icon itself, not its semantic meaning in every given context. If you for example make an icon button, make sure to include an `aria-label` on your button that describes its action.

package/dist/docs/icon/api.md

@@ -0,0 +1,43 @@
+## `<w-icon>` API
+
+Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).
+
+### Properties
+
+| Name | Type | Default | Summary |
+|-|-|-|-|
+| locale | `string` | `-` | Locale used for `<title>` text. |
+| name | `string` | `-` | Icon filename (without .svg) |
+| size | [`"small" \| "medium" \| "large" \| PixelValue \| undefined`](#small-medium-large-pixelvalue-undefined) | `"medium"` | Size: small, medium, large or pixel value (e.g. "32px"). |
+
+### Property Details
+
+#### locale
+
+Locale used for `<title>` text.
+
+Reads the `lang` attribute from `<html>`, falls back to 'en'.
+
+- Type: `string`
+- Default: `-`
+
+#### name
+
+Icon filename (without .svg)
+
+- Type: `string`
+- Default: `-`
+
+#### size
+
+Size: small, medium, large or pixel value (e.g. "32px").
+
+- Type: [`"small" | "medium" | "large" | PixelValue | undefined`](#small-medium-large-pixelvalue-undefined)
+- Default: `"medium"`
+
+### Types
+
+#### "small" | "medium" | "large" | PixelValue | undefined
+
+`'small' | 'medium' | 'large' | `${number}px` | undefined`
+

package/dist/docs/icon/examples.md

@@ -0,0 +1,45 @@
+## Examples
+
+### Small
+
+<elements-example>
+
+```html
+<w-icon name="Rocket" size="small"></w-icon>
+```
+
+</elements-example>
+
+### Medium
+
+This is the default size.
+
+<elements-example>
+
+```html
+<w-icon name="Rocket" size="medium"></w-icon>
+```
+
+</elements-example>
+
+### Large
+
+<elements-example>
+
+```html
+<w-icon name="Rocket" size="large"></w-icon>
+```
+
+</elements-example>
+
+### Custom size
+
+You can set a pixel size as well if none of the presets fit your needs.
+
+<elements-example>
+
+```html
+<w-icon name="Rocket" size="13.37px"></w-icon>
+```
+
+</elements-example>

package/dist/docs/icon/icon.md

@@ -0,0 +1,115 @@
+# Icon (w-icon)
+
+## Description
+
+See the Icons overview for a list of available icons. Icon names are case sensitive.
+
+## Usage
+
+See the [Icons overview](https://warp-ds.github.io/docs/components/icons/overview) for a list of available icons. Icon names are case sensitive.
+
+<elements-example>
+
+```html
+<w-icon name="Rocket"></w-icon>
+```
+
+</elements-example>
+
+## Accessibility
+
+Icons ship with a localized descriptive `<title>`.
+
+Note that the description is about the icon itself, not its semantic meaning in every given context. If you for example make an icon button, make sure to include an `aria-label` on your button that describes its action.
+
+## Examples
+
+### Small
+
+<elements-example>
+
+```html
+<w-icon name="Rocket" size="small"></w-icon>
+```
+
+</elements-example>
+
+### Medium
+
+This is the default size.
+
+<elements-example>
+
+```html
+<w-icon name="Rocket" size="medium"></w-icon>
+```
+
+</elements-example>
+
+### Large
+
+<elements-example>
+
+```html
+<w-icon name="Rocket" size="large"></w-icon>
+```
+
+</elements-example>
+
+### Custom size
+
+You can set a pixel size as well if none of the presets fit your needs.
+
+<elements-example>
+
+```html
+<w-icon name="Rocket" size="13.37px"></w-icon>
+```
+
+</elements-example>
+
+## Styling API
+
+## `<w-icon>` API
+
+Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).
+
+### Properties
+
+| Name | Type | Default | Summary |
+|-|-|-|-|
+| locale | `string` | `-` | Locale used for `<title>` text. |
+| name | `string` | `-` | Icon filename (without .svg) |
+| size | [`"small" \| "medium" \| "large" \| PixelValue \| undefined`](#small-medium-large-pixelvalue-undefined) | `"medium"` | Size: small, medium, large or pixel value (e.g. "32px"). |
+
+### Property Details
+
+#### locale
+
+Locale used for `<title>` text.
+
+Reads the `lang` attribute from `<html>`, falls back to 'en'.
+
+- Type: `string`
+- Default: `-`
+
+#### name
+
+Icon filename (without .svg)
+
+- Type: `string`
+- Default: `-`
+
+#### size
+
+Size: small, medium, large or pixel value (e.g. "32px").
+
+- Type: [`"small" | "medium" | "large" | PixelValue | undefined`](#small-medium-large-pixelvalue-undefined)
+- Default: `"medium"`
+
+### Types
+
+#### "small" | "medium" | "large" | PixelValue | undefined
+
+`'small' | 'medium' | 'large' | `${number}px` | undefined`
+

package/dist/docs/icon/styling.md

@@ -0,0 +1 @@
+## Styling API

package/dist/docs/icon/usage.md

@@ -0,0 +1,11 @@
+## Usage
+
+See the [Icons overview](https://warp-ds.github.io/docs/components/icons/overview) for a list of available icons. Icon names are case sensitive.
+
+<elements-example>
+
+```html
+<w-icon name="Rocket"></w-icon>
+```
+
+</elements-example>

package/dist/docs/index.md

@@ -0,0 +1,49 @@
+# Warp Elements Component Documentation
+
+Generated by `pnpm build:docs`. This file indexes the Markdown documentation shipped with `@warp-ds/elements`.
+
+- Package export: `@warp-ds/elements/docs`
+- Component docs export pattern: `@warp-ds/elements/docs/<component>/<component>.md`
+
+## Components
+
+| Component | Element / API | Package | Summary | Docs |
+|-|-|-|-|-|
+| Affix | `<w-affix>` | `affix` | This component is usually used in other components like form elements to show a prefix or suffix. See for example `w-textfield`. ## Accessibility Note Due to shadow DOM encapsulation, ARIA attributes (like `aria-describedby`, `aria-labelledby`) cannot reference elements across shadow boundaries. This means: - Non-interactive affixes (text labels, icons) cannot be connected to the parent input via ARIA - Interactive affixes (buttons) must have their own `aria-label` (already implemented) - Do NOT attempt to reference affix content from parent components via ARIA ID references - it won't work For non-interactive labels (e.g., currency symbols), consider including the information in the main label or placeholder instead of relying on ARIA to announce affix content. | [affix.md](./affix/affix.md) |
+| Alert | `<w-alert>` | `alert` | Alert is an inline component used for displaying different types of messages. For accessibility reasons, alert should appear close to the element that triggered it. | [alert.md](./alert/alert.md) |
+| Attention | `<w-attention>` | `attention` | Attention is a versatile component for displaying contextual information and messages. It can be used for a wide range of purposes, such as tooltips, callouts, popovers, and highlights. The component is designed to be anchored to a trigger element, providing contextual information related to that element. It supports various placements and styling options to accommodate different use cases and design needs. Note: attention will soon be split into multiple components (tooltip, callout, popover, highlight) at which time this component will be deprecated. For now, use the `tooltip`, `callout`, `popover`, and `highlight` boolean properties to achieve the desired style and behavior. | [attention.md](./attention/attention.md) |
+| Badge | `<w-badge>` | `badge` | `w-badge` is used for showing a small amount of non-interactive color-categorized metadata, like a status or count. | [badge.md](./badge/badge.md) |
+| Box | `<w-box>` | `box` | Box is a layout component used for separating content areas on a page. | [box.md](./box/box.md) |
+| Breadcrumb Item | `<w-breadcrumb-item>` | `breadcrumb-item` | Represents one item in a `w-breadcrumbs` trail. Renders the slotted label as a link when `href` is set, or as text when it is not, and adds a separator after non-current items. | [breadcrumb-item.md](./breadcrumb-item/breadcrumb-item.md) |
+| Breadcrumbs | `<w-breadcrumbs>` | `breadcrumbs` | Shows the navigation structure for the current page. Renders direct child links and non-link elements as a breadcrumb trail, inserts separators between items, and exposes the trail as navigation. | [breadcrumbs.md](./breadcrumbs/breadcrumbs.md) |
+| Button | `<w-button>` | `button` | Performs an action or renders a link with button styling. Use button variants to match action priority, risk, and context. | [button.md](./button/button.md) |
+| Card | `<w-card>` | `card` | Card is a layout component used for separating content areas on a page. | [card.md](./card/card.md) |
+| Checkbox | `<w-checkbox>` | `checkbox` | Checkbox lets users select one or more options. Use it for independent yes/no choices, multi-select lists, and terms or consent confirmations. | [checkbox.md](./checkbox/checkbox.md) |
+| Checkbox Group | `<w-checkbox-group>` | `checkbox-group` | Checkboxes allow users to select multiple options from a list of choices. Use with `w-checkbox`. ## Architecture Note This component uses a <div> wrapper instead of the more semantic <fieldset> element. Note that w-radio-group uses <fieldset>, which provides better accessibility and follows HTML best practices. This inconsistency exists for historical reasons and may be addressed in a future major version to align both on the more semantic approach. TODO: Align w-checkbox-group to use <fieldset> in a future major version after assessing backwards compatibility implications (CSS selectors, etc.). | [checkbox-group.md](./checkbox-group/checkbox-group.md) |
+| Combobox | `<w-combobox>` | `combobox` | A combobox element for text input with selectable options. | [combobox.md](./combobox/combobox.md) |
+| Datepicker | `<w-datepicker>` | `datepicker` | An input for dates. Uses the `lang` attribute on either the element or on `<html>` to determine the locale options. | [datepicker.md](./datepicker/datepicker.md) |
+| Expandable | `<w-expandable>` | `expandable` | Expandable is a layout component used for creating expandable content areas on a page. | [expandable.md](./expandable/expandable.md) |
+| Icon | `<w-icon>` | `icon` | See the Icons overview for a list of available icons. Icon names are case sensitive. | [icon.md](./icon/icon.md) |
+| Link | `<w-link>` | `link` | Buttons are used to perform actions, with different visuals for different needs. | [link.md](./link/link.md) |
+| Modal | `<w-modal>` | `modal` | Modals (or dialogs) display important information that users need to acknowledge. | [modal.md](./modal/modal.md) |
+| Modal Footer | `<w-modal-footer>` | `modal-footer` | The footer section of a modal, typically where you place actions. | [modal-footer.md](./modal-footer/modal-footer.md) |
+| Modal Header | `<w-modal-header>` | `modal-header` | The header section of a modal, typically where you place the title and a close button. | [modal-header.md](./modal-header/modal-header.md) |
+| Page Indicator | `<w-page-indicator>` | `page-indicator` | A page indicator component that displays a series of dots representing pages. One dot is highlighted to indicate the currently selected page. | [page-indicator.md](./page-indicator/page-indicator.md) |
+| Pagination | `<w-pagination>` | `pagination` | Pagination allows users to navigate through multiple pages of content by providing navigation controls with page numbers and directional arrows. | [pagination.md](./pagination/pagination.md) |
+| Pill | `<w-pill>` | `pill` | Pill is a type of button that is often used as a filter, but can also be used as a rounded button for overlays, etc. | [pill.md](./pill/pill.md) |
+| Radio | `<w-radio>` | `radio` | A radio input typically consists of two components: | [radio.md](./radio/radio.md) |
+| Radio Group | `<w-radio-group>` | `radio-group` | Radios allow users to select a single option from a list of choices. Use with `w-radio`. | [radio-group.md](./radio-group/radio-group.md) |
+| Select | `<w-select>` | `select` | A dropdown component for selecting a single value. | [select.md](./select/select.md) |
+| Slider | `<w-slider>` | `slider` | Parent component for sliders (both single and range sliders). Used in combination with a `<w-slider-thumb>`. | [slider.md](./slider/slider.md) |
+| Slider Thumb | `<w-slider-thumb>` | `slider-thumb` | Component to place inside a `<w-slider>`. | [slider-thumb.md](./slider-thumb/slider-thumb.md) |
+| Snackbar | `<w-snackbar>` | `snackbar` | A Snackbar shows brief user feedback messages that overlay content, with an optional action such as Undo. Include one `<w-snackbar></w-snackbar>` in the document `<body>`. Use the `create` function to create messages. | [snackbar.md](./snackbar/snackbar.md) |
+| Snackbar Item | `<w-snackbar-item>` | `snackbar-item` | An item to show in a `w-snackbar`. See the `create` function on `w-snackbar` for a convenience API which helps you make snackbar items. | [snackbar-item.md](./snackbar-item/snackbar-item.md) |
+| Step | `<w-step>` | `step` | Individual step component that shows a single step in a process | [step.md](./step/step.md) |
+| Step Indicator | `<w-step-indicator>` | `step-indicator` | Steps are used to show progress through a process or to guide users through a multi-step task. | [step-indicator.md](./step-indicator/step-indicator.md) |
+| Switch | `<w-switch>` | `switch` | The Switch component allows users to toggle between two states. | [switch.md](./switch/switch.md) |
+| Tab | `<w-tab>` | `tab` | Individual tab component used within w-tabs container. | [tab.md](./tab/tab.md) |
+| Tab Panel | `<w-tab-panel>` | `tab-panel` | Tab panel component that holds content for individual tabs. Each tab panel should have a name that matches a corresponding tab. | [tab-panel.md](./tab-panel/tab-panel.md) |
+| Tabs | `<w-tabs>` | `tabs` | Tabs are used to organize content by grouping similar information on the same page. | [tabs.md](./tabs/tabs.md) |
+| Textarea | `<w-textarea>` | `textarea` | A multi-line text input with built-in form validation, auto-resizing, and styling support. The component automatically handles: - Form integration - Auto-resizing based on content and row constraints - Built-in validation with customizable error messages - Accessibility attributes and labeling | [textarea.md](./textarea/textarea.md) |
+| Textfield | `<w-textfield>` | `textfield` | A single-line input component used for entering and editing textual or numeric data. | [textfield.md](./textfield/textfield.md) |
+| Toast | `@warp-ds/elements/toast` | `toast` | Toasts are brief user feedback messages that overlay content. | [toast.md](./toast/toast.md) |

package/dist/docs/link/api.md

@@ -6,84 +6,80 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 
 | Name | Type | Default | Summary |
 |-|-|-|-|
-| autofocus | `boolean` | `false` | - |
-| disabled | `boolean` | `false` | - |
-| full-width | `boolean` | `false` | - |
-| href | `string` | `-` | - |
-| rel | `string` | `-` | - |
-| shadowRootOptions (JS only) | `object` | `{ ...LitElement.shadowRootOptions, delegatesFocus: true, }` | - |
-| small | `boolean` | `false` | - |
-| target | `string` | `-` | - |
-| variant | [`ButtonVariant`](#buttonvariant) | `-` | - |
+| autofocus | `boolean` | `false` | Focus the link after it is rendered |
+| disabled | `boolean` | `false` | Applies disabled styling, but you need to disable clicks on your own. |
+| full-width | `boolean` | `false` | Makes the link take up the full width of its parent |
+| href | `string \| undefined` | `-` | The URL the link points to |
+| rel | `string \| undefined` | `-` | Relationship of the linked URL. |
+| small | `boolean` | `false` | Render a smaller version |
+| target | `string \| undefined` | `-` | Where to display the linked URL (e.g. `_blank`) |
+| variant | [`ButtonVariant \| undefined`](#buttonvariant-undefined) | `-` | Visual style for the link/button. |
 
 ### Property Details
 
 #### autofocus
 
-
+Focus the link after it is rendered
 
 - Type: `boolean`
 - Default: `false`
 
 #### disabled
 
+Applies disabled styling, but you need to disable clicks on your own.
 
+The component renders an `<a>` element; `disabled` affects styling, but does not inherently prevent navigation. If you need to fully disable interaction, omit `href` and/or prevent default click behavior.
 
 - Type: `boolean`
 - Default: `false`
 
 #### full-width
 
-
+Makes the link take up the full width of its parent
 
 - Type: `boolean`
 - Default: `false`
 
 #### href
 
+The URL the link points to
 
-
-- Type: `string`
+- Type: `string | undefined`
 - Default: `-`
 
 #### rel
 
+Relationship of the linked URL.
 
+If `target="_blank"` and `rel` is not provided, the component uses `noopener`.
 
-- Type: `string`
+- Type: `string | undefined`
 - Default: `-`
 
-#### shadowRootOptions (JS only)
-
-
-
-- Type: `object`
-- Default: `{ ...LitElement.shadowRootOptions, delegatesFocus: true, }`
-
 #### small
 
-
+Render a smaller version
 
 - Type: `boolean`
 - Default: `false`
 
 #### target
 
+Where to display the linked URL (e.g. `_blank`)
 
-
-- Type: `string`
+- Type: `string | undefined`
 - Default: `-`
 
 #### variant
 
+Visual style for the link/button.
 
-
-- Type: [`ButtonVariant`](#buttonvariant)
+- Type: [`ButtonVariant | undefined`](#buttonvariant-undefined)
 - Default: `-`
 
 ### Types
 
-#### ButtonVariant
+#### ButtonVariant | undefined
 
-`'negative' | 'primary' | 'secondary' | 'negativeQuiet' | 'utility' | 'quiet' | 'utilityQuiet' | 'overlay' | 'overlayInverted' | 'overlayQuiet' | 'overlayInvertedQuiet'`
+`'negative' | 'primary' | 'secondary' | 'negativeQuiet' | 'utility' | 'quiet' | 'utilityQuiet' | 'overlay' | 'overlayInverted' | 'overlayQuiet' | 'overlayInvertedQuiet' | undefined`
 

package/dist/docs/link/examples.md

@@ -1 +1,76 @@
 ## Examples
+
+### Primary
+
+<elements-example>
+
+```html
+<w-link variant="primary" href="#">Go to the top of this page</w-link>
+```
+
+</elements-example>
+
+### Secondary
+
+This is the default appearance.
+
+<elements-example>
+
+```html
+<w-link href="#">Go to the top of this page</w-link>
+```
+
+</elements-example>
+
+### Negative
+
+<elements-example>
+
+```html
+<w-link variant="negative" href="#">Go to the top of this page</w-link>
+```
+
+</elements-example>
+
+### Utility
+
+<elements-example>
+
+```html
+<w-link variant="utility" href="#">Go to the top of this page</w-link>
+```
+
+</elements-example>
+
+### Quiet
+
+<elements-example>
+
+```html
+<w-link variant="quiet" href="#">Go to the top of this page</w-link>
+```
+
+</elements-example>
+
+### Small
+
+All variants can be small.
+
+<elements-example>
+
+```html
+<w-link href="#" small>Go to the top of this page</w-link>
+```
+
+</elements-example>
+
+### Full width
+
+
+<elements-example>
+
+```html
+<w-link href="#" full-width>Go to the top of this page</w-link>
+```
+
+</elements-example>