@solid-design-system/mcp 0.0.1

package/metadata/packages/components/sd-checkbox/info.md

@@ -0,0 +1,88 @@
+## Overview
+
+`<sd-checkbox>` — Used to toggle an option on or off.
+
+## API
+
+### Examples
+
+Use the components tool by passing the args `component` and `example` for any of these combinations:
+
+- component: sd-checkbox, example: size
+- component: sd-checkbox, example: disabled
+- component: sd-checkbox, example: visually-disabled
+- component: sd-checkbox, example: checked
+- component: sd-checkbox, example: indeterminate
+- component: sd-checkbox, example: required
+- component: sd-checkbox, example: invalid
+
+### Key Properties
+
+- prop.title: string, default='' — The `title` attribute specifies extra information about an element most often as a default browser tooltip text when the mouse moves over the element.
+- prop.name: string, default='' — The name of the checkbox, submitted as a name/value pair with form data.
+- prop.value: string — The current value of the checkbox, submitted as a name/value pair with form data.
+- prop.size: 'sm'|'md'|'lg', default='lg' — The checkbox's size.
+- prop.disabled: boolean, default=false — Disables the checkbox.
+- prop.visuallyDisabled [attr: visually-disabled]: boolean, default=false — Styles the checkbox as if it was disabled and enables aria-disabled
+- prop.checked: boolean, default=false — Draws the checkbox in a checked state.
+- prop.indeterminate: boolean, default=false — 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.
+- prop.defaultChecked: boolean, default=false — The default value of the form control. Primarily used for resetting the form control.
+- prop.form: string, default='' — By default, form controls are associated with the nearest containing `<form>` element. This attribute allows you
+  to place the form control outside of a form and associate it with the form that has this `id`. The form must be in
+  the same document or shadow root for this to work.
+- prop.required: boolean, default=false — Makes the checkbox a required field.
+- prop.validity: — Gets the validity state object
+- prop.dir: 'ltr'|'rtl'|'auto' — The element's directionality.
+- prop.lang: string — The element's language.
+
+### Events
+
+- event.sd-blur: Emitted when the checkbox loses focus.
+- event.sd-change: Emitted when the checked state changes.
+- event.sd-focus: Emitted when the checkbox gains focus.
+- event.sd-input: Emitted when the checkbox receives input.
+
+### Slots
+
+- slot.default: The checkbox's label.
+
+### CSS Parts
+
+- part.base: The component's base wrapper.
+- part.control: The square container that wraps the checkbox's checked state.
+- part.control--checked: Matches the control part when the checkbox is checked.
+- part.control--indeterminate: Matches the control part when the checkbox is indeterminate.
+- part.checked-icon: The checked icon, an `<sd-icon>` element.
+- part.indeterminate-icon: The indeterminate icon, an `<sd-icon>` element.
+- part.label: The container that wraps the checkbox's label.
+
+## Guidelines
+
+### Use Cases
+
+- Used for selections that don’t immediately activate.
+- Selecting an option like "Agree to Terms and Conditions" before submitting a registration form.
+- Opt-in/Opt-out of notifications or subscriptions.
+- Check [sd-checkbox-group](./?path=/docs/components-sd-checkbox-group--docs) for group use cases and usage guidelines.
+
+### Rules
+
+### Content
+
+- Provide a clear, descriptive label for each selection to avoid confusion.
+- Frame labels positively, such as "Enable notifications" instead of "Disable notifications."
+
+### Interaction and Usage
+
+- Ensure each selection operates independently unless used for bulk actions.
+- List selections in a logical order, such as alphabetical or numerical.
+- Refrain from using a single checkbox when the action should take effect immediately — use [sd-switch](./?path=/docs/components-sd-switch--docs) instead.
+
+### Accessibility
+
+- Checkboxes should always look like checkboxes to meet user’s expectations.
+- Nesting other interactive elements like links inside labels should be avoided.
+- An error-text with a warning icon should be placed underneath an invalid checkbox or, if used in a group, underneath the checkbox group. Error messages should always provide hints for solutions.
+- Use the "visually disabled" attribute to keep disabled elements focusable, hoverable, and able to show tooltips, as they’re otherwise removed from the tab order and inaccessible to screen readers.
+- In Figma use an asterisk with a blank before ( \*) at the end of its label when designing a mandatory checkbox. In code use the “required” boolean.

package/metadata/packages/components/sd-checkbox/stories/checked.md

@@ -0,0 +1,7 @@
+Use the `checked` attribute to activate the checkbox.
+
+```html
+<div class="flex gap-12">
+  <sd-checkbox checked>Checked</sd-checkbox>
+</div>
+```

package/metadata/packages/components/sd-checkbox/stories/disabled.md

@@ -0,0 +1,7 @@
+Use the `disabled` attribute to disable an input checkbox. Clicks will be suppressed until the disabled state is removed.
+
+```html
+<div class="flex gap-12">
+  <sd-checkbox disabled>Disabled</sd-checkbox>
+</div>
+```

package/metadata/packages/components/sd-checkbox/stories/indeterminate.md

@@ -0,0 +1,7 @@
+Use the `indeterminate` attribute to make the checkbox indeterminate.
+
+```html
+<div class="flex gap-12">
+  <sd-checkbox indeterminate>Indeterminate</sd-checkbox>
+</div>
+```

package/metadata/packages/components/sd-checkbox/stories/invalid.md

@@ -0,0 +1,22 @@
+The component gets `invalid` state when the form is not valid.
+For an invalid checkbox an error-text underneath (or if used in a group underneath the checkbox-group) is mandatory.
+
+```html
+<form id="form-example">
+  <sd-checkbox id="checkbox-example" required>Invalid</sd-checkbox>
+  <sd-button class="mt-4" type="submit" hidden>Submit</sd-button>
+</form>
+<script>
+  var checkbox = document.querySelector('#checkbox-example');
+  var form = document.querySelector('#form-example');
+
+  setTimeout(() => {
+    checkbox.setCustomValidity('Error-text');
+    form.reportValidity();
+  }, 500);
+
+  checkbox.addEventListener('sd-change', () => {
+    checkbox.checked ? checkbox.setCustomValidity('') : checkbox.setCustomValidity('Error-text');
+  });
+</script>
+```

package/metadata/packages/components/sd-checkbox/stories/required.md

@@ -0,0 +1,7 @@
+Use the `required` attribute to mark the element as required. This can be used for form validation purposes.
+
+```html
+<div class="flex gap-12">
+  <sd-checkbox required>Required</sd-checkbox>
+</div>
+```

package/metadata/packages/components/sd-checkbox/stories/size.md

@@ -0,0 +1,14 @@
+Use the `size` attribute to change the size of the input checkbox (`md` equals `lg` but added for consistency reason on input elements):
+
+- `lg` (default)
+- `md`
+- `sm`
+  This attribute affects the font-size within the element, while the element itself remains the same size.
+
+```html
+<div class="flex gap-12">
+  <sd-checkbox size="lg">Large</sd-checkbox>
+  <sd-checkbox size="md">Medium</sd-checkbox>
+  <sd-checkbox size="sm">Small</sd-checkbox>
+</div>
+```

package/metadata/packages/components/sd-checkbox/stories/visually-disabled.md

@@ -0,0 +1,11 @@
+Use the `visually-disabled` attribute to style the component as if it was disabled and enable `aria-disabled` to allow it to be reachable by screen readers.
+**Hint:** When using this attribute, make sure to provide ways to inform the user why the element is disabled and how to enable it. This can be done by using the `help-text` attribute or wrapping the element in a sd-tooltip.
+**Accessibility Hint:** Disabling elements is not recommended for accessibility reasons.
+
+```html
+<div class="w-[250px] h-[100px] pt-12">
+  <sd-tooltip content="Visually disabled" trigger="hover focus" size="sm" placement="top">
+    <sd-checkbox visually-disabled>Visually disabled</sd-checkbox>
+  </sd-tooltip>
+</div>
+```

package/metadata/packages/components/sd-checkbox-group/info.md

@@ -0,0 +1,71 @@
+## Overview
+
+`<sd-checkbox-group>` — Used to group multiple options from a list of options. Presentational only.
+
+## API
+
+### Examples
+
+Use the components tool by passing the args `component` and `example` for any of these combinations:
+
+- component: sd-checkbox-group, example: size
+- component: sd-checkbox-group, example: orientation
+- component: sd-checkbox-group, example: label
+- component: sd-checkbox-group, example: help-text
+
+### Key Properties
+
+- prop.size: 'lg'|'md'|'sm', default='lg' — The checkbox group's size. This size will be applied to the label, all child checkboxes.
+- prop.orientation: 'horizontal'|'vertical', default='vertical' — The orientation property determines the alignment of the component's content or elements. It accepts two possible
+  values: 'horizontal' and 'vertical'. The default value is 'vertical'.
+  This property allows you to control the visual layout and arrangement of elements within the component, providing
+  flexibility in how the component is displayed based on your specific design needs.
+- prop.label: string, default='' — The checkbox group's label. Required for proper accessibility. If you need to display HTML, use the `label` slot
+  instead.
+- prop.helpText [attr: help-text]: string, default='' — The element help text. If you need to display HTML, use the `help-text` slot instead.
+- prop.dir: 'ltr'|'rtl'|'auto' — The element's directionality.
+- prop.lang: string — The element's language.
+
+### Slots
+
+- slot.default: The default slot where `<sd-checkbox>` elements are placed.
+- slot.label: The checkbox group's label. Required for proper accessibility. Alternatively, you can use the `label` attribute.
+- slot.tooltip: An optional tooltip that helps describe the checkbox-group. Use this slot with the `sd-tooltip` component.
+- slot.help-text: Text that describes how to use the input. Alternatively, you can use the `help-text` attribute.
+
+## Guidelines
+
+### Use Cases
+
+- Allow users to select multiple options from a list in forms.
+- Indicate agreement to terms and conditions.
+- Use a parent option to select or deselect all items in a list.
+- Enable filtering of data on a page, in a menu, or within a component.
+- Check [sd-checkbox](./?path=/docs/components-sd-checkbox--docs) for single usage guidelines.
+
+### Rules
+
+### Labels
+
+- Provide a clear, mutually exclusive label for each option to avoid ambiguity and ensure accessibility.
+- Frame labels positively (e.g., "Enable notifications" instead of "Disable notifications").
+
+### Layout and Structure
+
+- Align options vertically for better readability and user experience.
+- List selections in a logical order, such as alphabetical or numerical.
+- Place selections consistently across the interface.
+
+### Interaction and Functionality
+
+- Ensure each selection works independently unless used for bulk actions.
+- Use a parent option for bulk selection or deselection of all items.
+- Avoid using checkboxes when only one option can be selected; use radio buttons instead.
+- Refrain from using checkboxes for mutually exclusive choices.
+- Don’t use checkboxes for binary actions that take immediate effect; use a switch instead.
+
+### Accessibility
+
+- Ensure that the group label is short and concise as it may be read out with every option or when users enter the group.
+- An error-text with a warning icon should be placed underneath an invalid checkbox or, if used in a group, underneath the checkbox group. Error messages should always provide hints for solutions.
+- Use an asterisk with a blank before ( \*) at the end of its label when designing a mandatory checkbox.

package/metadata/packages/components/sd-checkbox-group/stories/help-text.md

@@ -0,0 +1,13 @@
+Use the `help-text` attribute to add a descriptive “help text”.
+For help texts that contain HTML, use the `help-text` slot instead.
+
+```html
+<div class="flex gap-12">
+  <sd-checkbox-group orientation="vertical" help-text="Help text">
+    <label slot="label">Group label</label>
+    <sd-checkbox value="1">Checkbox 1</sd-checkbox>
+    <sd-checkbox value="2">Checkbox 2</sd-checkbox>
+    <sd-checkbox value="3">Checkbox 3</sd-checkbox>
+  </sd-checkbox-group>
+</div>
+```

package/metadata/packages/components/sd-checkbox-group/stories/label.md

@@ -0,0 +1,10 @@
+Use the `label` attribute to add a label on top.
+
+```html
+<sd-checkbox-group orientation="vertical">
+  <label slot="label">Group label</label>
+  <sd-checkbox value="1">Checkbox 1</sd-checkbox>
+  <sd-checkbox value="2">Checkbox 2</sd-checkbox>
+  <sd-checkbox value="3">Checkbox 3</sd-checkbox>
+</sd-checkbox-group>
+```

package/metadata/packages/components/sd-checkbox-group/stories/orientation.md

@@ -0,0 +1,19 @@
+Use the `orientation` attribute to set the axis of the checkboxes:
+
+- `vertical` (default)
+- `horizontal`
+
+```html
+<div class="flex gap-12">
+  <sd-checkbox-group orientation="vertical" label="Group label">
+    <sd-checkbox value="1">Checkbox 1</sd-checkbox>
+    <sd-checkbox value="2">Checkbox 2</sd-checkbox>
+    <sd-checkbox value="3">Checkbox 3</sd-checkbox>
+  </sd-checkbox-group>
+  <sd-checkbox-group orientation="horizontal" label="Group label">
+    <sd-checkbox value="1">Checkbox 1</sd-checkbox>
+    <sd-checkbox value="2">Checkbox 2</sd-checkbox>
+    <sd-checkbox value="3">Checkbox 3</sd-checkbox>
+  </sd-checkbox-group>
+</div>
+```

package/metadata/packages/components/sd-checkbox-group/stories/size.md

@@ -0,0 +1,21 @@
+Use the `size` attribute to change the size (`md` equals `lg` but added for consistency reason on input elements):
+
+- `lg` (default)
+- `md`
+- `sm`
+
+```html
+<div class="flex gap-12">
+  <sd-checkbox-group size="lg" label="Group label">
+    <sd-checkbox value="1">Checkbox 1</sd-checkbox>
+    <sd-checkbox value="2">Checkbox 2</sd-checkbox>
+    <sd-checkbox value="3">Checkbox 3</sd-checkbox>
+  </sd-checkbox-group>
+
+  <sd-checkbox-group size="sm" label="Group label">
+    <sd-checkbox value="1">Checkbox 1</sd-checkbox>
+    <sd-checkbox value="2">Checkbox 2</sd-checkbox>
+    <sd-checkbox value="3">Checkbox 3</sd-checkbox>
+  </sd-checkbox-group>
+</div>
+```

package/metadata/packages/components/sd-combobox/info.md

@@ -0,0 +1,170 @@
+## Overview
+
+`<sd-combobox>` — Used to select one or multiple options from a list of options or to enter a search string and choose from a list of suggestions.
+
+## API
+
+### Examples
+
+Use the components tool by passing the args `component` and `example` for any of these combinations:
+
+- component: sd-combobox, example: size
+- component: sd-combobox, example: placement
+- component: sd-combobox, example: label
+- component: sd-combobox, example: floating-label
+- component: sd-combobox, example: placeholder
+- component: sd-combobox, example: disabled
+- component: sd-combobox, example: visually-disabled
+- component: sd-combobox, example: help-text
+- component: sd-combobox, example: focus
+- component: sd-combobox, example: suggestion-container-height
+- component: sd-combobox, example: clearable
+- component: sd-combobox, example: icons
+- component: sd-combobox, example: search
+- component: sd-combobox, example: multiple
+- component: sd-combobox, example: max-options-visible
+- component: sd-combobox, example: required
+- component: sd-combobox, example: valid
+- component: sd-combobox, example: invalid
+- component: sd-combobox, example: async-options
+- component: sd-combobox, example: custom-filter
+
+### Key Properties
+
+- prop.name: string, default='' — The name of the combobox, submitted as a name/value pair with form data.
+- prop.value: string|string[], default='' — The current value of the combobox, submitted as a name/value pair with form data.
+- prop.defaultValue: string, default='' — The default value of the form control. Primarily used for resetting the form control.
+- prop.size: 'lg'|'md'|'sm', default='lg' — The combobox's size.
+- prop.placeholder: string, default='' — Placeholder text to show as a hint when the combobox is empty.
+- prop.maxOptionsTagLabel [attr: max-options-tag-label]: string, default='' — Label text shown on tag if max-options-visible is reached.
+- prop.disabled: boolean, default=false — Disables the combobox control.
+- prop.visuallyDisabled [attr: visually-disabled]: boolean, default=false — Styles the combobox as if it was disabled and enables aria-disabled
+- prop.clearable: boolean, default=false — Adds a clear button when the combobox is not empty.
+- prop.open: boolean, default=false — Indicates whether or not the combobox is open.
+  You can toggle this attribute to show and hide the listbox, or you can use the `show()`
+  and `hide()` methods and this attribute will reflect the combobox's open state.
+- prop.hoist: boolean, default=false — Enable this option to prevent the listbox from being clipped,
+  when the component is placed inside a container with `overflow: auto|scroll`.
+  Hoisting uses a fixed positioning strategy that works in many, but not all, scenarios.
+- prop.label: string, default='' — The combobox's label. If you need to display HTML, use the `label` slot instead.
+- prop.placement: 'top'|'bottom', default='bottom' — The preferred placement of the combobox's menu.
+  Note that the actual placement may vary as needed to keep the listbox inside of the viewport.
+- prop.helpText [attr: help-text]: string, default='' — The combobox's help text. If you need to display HTML, use the `help-text` slot instead.
+- prop.form: string, default='' — By default, form controls are associated with the nearest containing `<form>` element.
+  This attribute allows you to place the form control outside of a form and associate it
+  with the form that has this `id`.
+  The form must be in the same document or shadow root for this to work.
+- prop.required: boolean, default=false — The combobox's required attribute.
+- prop.floatingLabel [attr: floating-label]: boolean, default=false — Enables the floating label behavior for the input.
+- prop.type: 'search'|'text', default='text' — The type of input. Works the same as a native `<input>` element, but only a subset of types are supported. Defaults
+  to `text`.
+- prop.getOption: OptionRenderer, default=defaultOptionRenderer — A function that customizes the rendered option. The first argument is the option, the second
+  is the query string, which is typed into the combobox.
+  The function should return either a Lit TemplateResult or a string containing trusted HTML
+  to render in the shown list of filtered options.
+  If the query string should be highlighted use the `highlightOptionRenderer` function.
+- prop.multiple: boolean, default=false — Allows more than one option to be selected.
+- prop.useTags: boolean, default=true — Uses interactive `sd-tag` elements representing individual options in the display input when `multiple` is `true`. It cannot be opted out.
+- prop.maxOptionsVisible [attr: max-options-visible]: number, default=3 — The maximum number of selected options to show when `multiple` and `useTags` are `true`. After the maximum, "+n" will be shown to
+  indicate the number of additional items that are selected. Set to 0 to remove the limit.
+- prop.styleOnValid [attr: style-on-valid]: boolean, default=false — Shows success styles if the validity of the input is valid.
+- prop.filter: (option: SdOption, queryString: string) => boolean — A function used to filter options in the combobox component.
+  The default filter method is a case- and diacritic-insensitive string comparison.
+- prop.validity: — Gets the validity state object
+- prop.validationMessage: — Gets the validation message
+- prop.dir: 'ltr'|'rtl'|'auto' — The element's directionality.
+- prop.lang: string — The element's language.
+
+### Events
+
+- event.sd-change: Emitted when the control's value changes.
+- event.sd-clear: Emitted when the control's value is cleared.
+- event.sd-input: Emitted when the control receives input.
+- event.sd-search: Emitted when the search button is activated.
+- event.sd-focus: Emitted when the control gains focus.
+- event.sd-blur: Emitted when the control loses focus.
+- event.sd-show: Emitted when the combobox's menu opens.
+- event.sd-after-show: Emitted after the combobox's menu opens and all animations are complete.
+- event.sd-hide: Emitted when the combobox's menu closes.
+- event.sd-after-hide: Emitted after the combobox's menu closes and all animations are complete.
+- event.sd-invalid: Emitted when the form control has been checked for validity and its constraints aren't satisfied.
+- event.sd-error: Emitted when the combobox menu fails to open.
+
+### Slots
+
+- slot.default: The listbox options. Must be `<sd-option>` elements. You can use `<sd-optgroup>`'s to group items visually.
+- slot.label: The combobox's label. Alternatively, you can use the `label` attribute.
+- slot.help-text: Text that describes how to use the combobox. Alternatively, you can use the `help-text` attribute.
+- slot.left: Used to prepend a presentational icon or similar element to the combobox.
+- slot.right: Used to append a presentational icon or similar element to the combobox.
+- slot.clear-icon: An icon to use in lieu of the default clear icon.
+- slot.expand-icon: The icon to show when the control is expanded and collapsed. Rotates on open and close.
+
+### CSS Parts
+
+- part.form-control: The form control that wraps the label, combobox, and help text.
+- part.form-control-label: The label's wrapper.
+- part.form-control-input: The combobox's wrapper.
+- part.form-control-help-text: The help text's wrapper.
+- part.combobox: The container that wraps the prefix, combobox, clear icon, and expand button.
+- part.left: The container that wraps the left icon slot.
+- part.right: The container that wraps the right icon slot.
+- part.display-input: The element that displays the selected option's label, an `<input>` element.
+- part.listbox: The listbox container where the options are slotted and the filtered options list exists.
+- part.filtered-listbox: The container that wraps the filtered options.
+- part.clear-button: The clear button.
+- part.expand-icon: The container that wraps the expand icon.
+
+## Guidelines
+
+### Use Cases
+
+- Allow users to select one or more options from a potentially large list by typing a search string and filtering suggestions.
+- Provide an autocomplete feature in forms where specific or complex entries benefit from quick lookup.
+- Implement in search fields or filter panels when users may not recall the exact option name but can approximate it.
+
+#### Default Combobox
+
+Use the “default” variant when clarity, scannability, and accessibility are your primary concerns.
+
+- Long or descriptive labels, helper text, or units are needed.
+- Forms with many fields that users must scan quickly.
+- Complex fields with adornments, counters, or tooltips.
+
+#### Floating Label Combobox
+
+Use the “floating-label” variant to conserve vertical space and streamline simple forms, while still keeping the label visible.
+
+- Compact layouts and simple fields.
+- Short labels (1–3 words); minimal helper text.
+- You want a clean look without duplicate placeholder text.
+
+### Rules
+
+### Variant Consistency
+
+Do not mix the two variants (default / floating label) within the same product, flow or form. Read the use cases above to know when to use each type.
+
+### Content and Labels
+
+- Keep option labels concise so that suggestions are easy to scan and select.
+- Provide a clear, descriptive placeholder (e.g., “Search or select an option…”) to help users understand they can type and choose from suggestions.
+- Avoid repeating the same initial word in multiple suggestions to reduce scanning difficulty.
+
+### Searching Behavior
+
+- Filter available options in real time as the user types; highlight or bold matching text to indicate relevance.
+- Show a message (e.g., “No matches found”) when no options align with the user’s input.
+- Consider limiting the maximum number of displayed suggestions to avoid overwhelming users. We recommend displaying 6-8 (with scrolling for additional results).
+
+### Background
+
+- Use light backgrounds such as white, neutral-100, or primary-100 for clarity and consistency across different layouts.
+- Keep focus styles clearly visible when the user navigates through suggestions with a keyboard or screen reader.
+
+### Accessibility
+
+- To ensure screenreader compatibility, consider including a statement such as "Fields marked with an asterisk (\*) are required" at the start of the form.
+- A visible label may be omitted for search input fields within a combobox if an associated button—complete with a clear search icon and an appropriate accessible name (e.g., aria-label="Search")—is provided.
+- Be aware that group labels will be neglected by most assistive devices.
+- Use the "visually disabled" attribute to keep disabled elements focusable, hoverable, and able to show tooltips, as they’re otherwise removed from the tab order and inaccessible to screen readers.

package/metadata/packages/components/sd-combobox/stories/async-options.md

@@ -0,0 +1,27 @@
+It is possible to add options dynamically to the combobox e.g. if the option values need to be fetched asynchronously from a remote server or API.
+
+```html
+<div class="h-[400px] min-w-[200px] md:min-w-0 max-w-[400px]">
+  <sd-combobox label="Async options" class="async-combobox">
+    <sd-option class="option" value="option-1">Option 1</sd-option>
+    <sd-option class="option" value="option-2">Option 2</sd-option>
+    <sd-option class="option" value="option-3">Option 3</sd-option>
+  </sd-combobox>
+</div>
+<script type="module">
+  const comboboxes = document.querySelectorAll('.async-combobox');
+  comboboxes.forEach(combobox => {
+    // After api request the options are added async
+    let index = 4;
+    let timeout = setInterval(() => {
+      const option = document.createElement('sd-option');
+      const value = 'Option ' + index++;
+      option.textContent = value;
+      combobox.appendChild(option);
+      if (index > 10) {
+        clearInterval(timeout);
+      }
+    }, 4000);
+  });
+</script>
+```

package/metadata/packages/components/sd-combobox/stories/clearable.md

@@ -0,0 +1,13 @@
+Use the `clearable` attribute to add a clear button that removes the selected value.
+
+```html
+<div class="h-[400px] min-w-[200px] md:min-w-0 max-w-[400px]">
+  <sd-combobox size="lg" label="Label" placement="bottom" clearable value="option-1">
+    <sd-option value="option-1">Option 1</sd-option>
+    <sd-option value="option-2">Option 2</sd-option>
+    <sd-option value="option-3">Option 3</sd-option>
+    <sd-option value="option-4">Option 4</sd-option>
+    <sd-option value="option-5">Option 5</sd-option>
+  </sd-combobox>
+</div>
+```

package/metadata/packages/components/sd-combobox/stories/custom-filter.md

@@ -0,0 +1,20 @@
+A custom filter can be applied by passing a filter function to the filter property. This filter() function will be called for each option. The first argument is an element and the second argument is the query string.
+
+```html
+<div class="h-[400px] min-w-[200px] md:min-w-0 max-w-[400px]">
+  <sd-combobox label="Custom filter" class="filter-combobox"> ${createColorOptionsHtml()} </sd-combobox>
+</div>
+<script type="module">
+  const comboboxes = document.querySelectorAll('.filter-combobox');
+  comboboxes.forEach(combobox => {
+    const oldFilter = combobox.filter;
+    combobox.filter = (option, queryString) => {
+      // only show options for more than 2 characters on text input
+      if (queryString && queryString.length > 2) {
+        return oldFilter(option, queryString);
+      }
+      return false;
+    };
+  });
+</script>
+```

package/metadata/packages/components/sd-combobox/stories/disabled.md

@@ -0,0 +1,13 @@
+Use the `disabled` attribute to disable the combobox.
+
+```html
+<div class="min-w-[200px] md:min-w-0 max-w-[400px]">
+  <sd-combobox size="lg" label="Label" placeholder="Disabled" placement="bottom" value="" disabled>
+    <sd-option value="option-1">Option 1</sd-option>
+    <sd-option value="option-2">Option 2</sd-option>
+    <sd-option value="option-3">Option 3</sd-option>
+    <sd-option value="option-4">Option 4</sd-option>
+    <sd-option value="option-5">Option 5</sd-option>
+  </sd-combobox>
+</div>
+```

package/metadata/packages/components/sd-combobox/stories/floating-label.md

@@ -0,0 +1,14 @@
+Use the `floating-label` attribute to enable a floating label on the combobox.
+**Note:** Floating labels only work with the `label` attribute. The `label` slot is not supported. Only the `lg` and `md` sizes are available.
+
+```html
+<div class="flex gap-12 h-[400px] min-w-[200px] md:min-w-0 max-w-[400px]">
+  <sd-combobox size="lg" label="Floating Label" floating-label placement="bottom" value="">
+    <sd-option value="option-1">Option 1</sd-option>
+    <sd-option value="option-2">Option 2</sd-option>
+    <sd-option value="option-3">Option 3</sd-option>
+    <sd-option value="option-4">Option 4</sd-option>
+    <sd-option value="option-5">Option 5</sd-option>
+  </sd-combobox>
+</div>
+```

package/metadata/packages/components/sd-combobox/stories/focus.md

@@ -0,0 +1,11 @@
+The focus attribute provides feedback to the users, informing them that the combobox component is ready for use.
+
+```html
+<div class="h-[260px] min-w-[200px] md:min-w-0 max-w-[400px]">
+  <sd-combobox label="Label">
+    <sd-option value="option-1">Option 1</sd-option>
+    <sd-option value="option-2">Option 2</sd-option>
+    <sd-option value="option-3">Option 3</sd-option>
+  </sd-combobox>
+</div>
+```

package/metadata/packages/components/sd-combobox/stories/help-text.md

@@ -0,0 +1,36 @@
+Use the `help-text` attribute to provide additional context or instructions.
+For help texts that contain HTML, use the `help-text` slot instead.
+
+```html
+<div class="flex flex-wrap md:flex-nowrap gap-12 h-[400px]">
+  <sd-combobox
+    class="flex-1 min-w-[200px] md:min-w-0 max-w-[400px]"
+    size="lg"
+    label="Label"
+    placement="bottom"
+    value=""
+    help-text="Help text attribute"
+  >
+    <sd-option value="option-1">Option 1</sd-option>
+    <sd-option value="option-2">Option 2</sd-option>
+    <sd-option value="option-3">Option 3</sd-option>
+    <sd-option value="option-4">Option 4</sd-option>
+    <sd-option value="option-5">Option 5</sd-option>
+  </sd-combobox>
+
+  <sd-combobox
+    class="flex-1 min-w-[200px] md:min-w-0 max-w-[400px]"
+    size="lg"
+    label="Label"
+    placement="bottom"
+    value=""
+  >
+    <div slot="help-text" class="text-lg">Help text slot</div>
+    <sd-option value="option-1">Option 1</sd-option>
+    <sd-option value="option-2">Option 2</sd-option>
+    <sd-option value="option-3">Option 3</sd-option>
+    <sd-option value="option-4">Option 4</sd-option>
+    <sd-option value="option-5">Option 5</sd-option>
+  </sd-combobox>
+</div>
+```

package/metadata/packages/components/sd-combobox/stories/icons.md

@@ -0,0 +1,15 @@
+Use the “left” and “right” slots to add system icons.
+Show the search icon in either the left slot or right icon slot instead of the chevron icon (don’t show two icons on the right-hand side).
+**Accessibility hint**: The label can be omitted for search input fields if a button (e.g., aria-label="Search") with a search icon is present.
+
+```html
+<div class="h-[400px] min-w-[200px] md:min-w-0 max-w-[400px]">
+  <sd-combobox size="lg" clearable label="Label">
+    <sd-icon slot="left" name="system/image" aria-hidden="true" color="currentColor"></sd-icon>
+    ${createColorOptionsHtml()}
+    <button slot="right" aria-label="Search" class="sd-interactive flex">
+      <sd-icon name="system/magnifying-glass" aria-hidden="true" color="currentColor"></sd-icon>
+    </button>
+  </sd-combobox>
+</div>
+```