@solid-design-system/mcp 0.0.1

package/metadata/packages/components/sd-textarea/stories/max-length.md

@@ -0,0 +1,15 @@
+Use the `maxlength` attribute to set a maximum length for the textarea to be valid.
+
+```html
+<div class="w-[500px]">
+  <sd-textarea
+    value=""
+    size="lg"
+    label="Label"
+    help-text="You are limited to a maximum of 5 characters"
+    rows="4"
+    spellcheck=""
+    maxlength="5"
+  ></sd-textarea>
+</div>
+```

package/metadata/packages/components/sd-textarea/stories/min-length.md

@@ -0,0 +1,15 @@
+Use the `minlength` attribute to set a minimum length for the textarea to be valid.
+
+```html
+<div class="w-[500px]">
+  <sd-textarea
+    value=""
+    size="lg"
+    label="Label"
+    help-text="Please type at least 5 characters"
+    rows="4"
+    spellcheck=""
+    minlength="5"
+  ></sd-textarea>
+</div>
+```

package/metadata/packages/components/sd-textarea/stories/placeholder.md

@@ -0,0 +1,7 @@
+Use the `placeholder` attribute to add a placeholder.
+
+```html
+<div class="w-[500px]">
+  <sd-textarea size="lg" label="Label" placeholder="Placeholder example" rows="4" spellcheck></sd-textarea>
+</div>
+```

package/metadata/packages/components/sd-textarea/stories/readonly.md

@@ -0,0 +1,16 @@
+Use the `readonly` attribute to render a textarea as readonly.
+Interaction is enabled, but the textarea cannot be edited.
+Events will be fired.
+
+```html
+<div class="w-[500px]">
+  <sd-textarea
+    value="Read only example Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod."
+    size="lg"
+    label="Label"
+    rows="4"
+    readonly
+    spellcheck
+  ></sd-textarea>
+</div>
+```

package/metadata/packages/components/sd-textarea/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="w-[500px]">
+  <sd-textarea size="lg" label="Required" rows="4" required spellcheck></sd-textarea>
+</div>
+```

package/metadata/packages/components/sd-textarea/stories/rows.md

@@ -0,0 +1,11 @@
+Use the `rows` attribute to set the number of rows.
+
+```html
+<div class="flex gap-12">
+  <sd-textarea size="lg" label="Label" rows="4" spellcheck></sd-textarea>
+
+  <sd-textarea size="lg" label="Label" rows="8" spellcheck></sd-textarea>
+
+  <sd-textarea size="lg" label="Label" rows="12" spellcheck></sd-textarea>
+</div>
+```

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

@@ -0,0 +1,16 @@
+Use the `size` attribute to change the size:
+
+- `lg` (default)
+- `md`
+- `sm`
+  **Note:** On the `floating-label` variant “sm” size is not available.
+
+```html
+<div class="flex gap-12">
+  <sd-textarea value="Large" size="lg" label="Label" rows="4" spellcheck></sd-textarea>
+
+  <sd-textarea value="Medium" size="md" label="Label" rows="4" spellcheck></sd-textarea>
+
+  <sd-textarea value="Small" size="sm" label="Label" rows="4" spellcheck></sd-textarea>
+</div>
+```

package/metadata/packages/components/sd-textarea/stories/valid.md

@@ -0,0 +1,22 @@
+The component gets `valid` state when the input is valid. Use the `style-on-valid` attribute to automatically indicate and show a valid state.
+
+```html
+<form class="w-[500px]">
+  <sd-textarea
+    id="valid-textarea"
+    value="Input text here"
+    size="lg"
+    label="Label"
+    style-on-valid
+    spellcheck
+  ></sd-textarea>
+</form>
+<script type="module">
+  await Promise.all([customElements.whenDefined('sd-textarea'), customElements.whenDefined('sd-button')]).then(() => {
+    const input = document.getElementById('valid-textarea');
+
+    input.setCustomValidity(''); // Clear custom validity
+    input.reportValidity();
+  });
+</script>
+```

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

@@ -0,0 +1,18 @@
+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-[500px] mt-12">
+  <sd-tooltip content="Visually disabled" trigger="hover focus" size="sm">
+    <sd-textarea
+      size="lg"
+      label="Label"
+      placeholder="Input text visually disabled"
+      rows="4"
+      spellcheck
+      visually-disabled
+    ></sd-textarea>
+  </sd-tooltip>
+</div>
+```

package/metadata/packages/components/sd-theme-listener/info.md

@@ -0,0 +1,20 @@
+## Overview
+
+`<sd-theme-listener>` — Theme listener is a utility that listens to theme changes and triggers an event.
+
+## API
+
+### Examples
+
+Use the components tool by passing the args `component` and `example` for any of these combinations:
+
+- component: sd-theme-listener, example: default
+
+### Key Properties
+
+- prop.dir: 'ltr'|'rtl'|'auto' — The element's directionality.
+- prop.lang: string — The element's language.
+
+### Events
+
+- event.sd-theme-change: Emitted when the sd-theme changes.

package/metadata/packages/components/sd-theme-listener/stories/default.md

@@ -0,0 +1,31 @@
+```html
+<div id="theme-wrapper" class="sd-theme-ui-light bg-white p-4">
+  <sd-theme-listener id="theme-listener"></sd-theme-listener>
+  <sd-button id="theme-switcher">Toggle Theme</sd-button>
+</div>
+<script type="module">
+  function onThemeChange() {
+    alert('Theme has changed!');
+  }
+
+  const listener = document.querySelector('#theme-listener');
+  listener.addEventListener('sd-theme-change', onThemeChange);
+</script>
+<script type="module">
+  function toggleTheme() {
+    const hasLightTheme = wrapper.classList.contains('sd-theme-ui-light');
+
+    if (hasLightTheme) {
+      wrapper.classList.remove('sd-theme-ui-light');
+      wrapper.classList.add('sd-theme-ui-dark');
+    } else {
+      wrapper.classList.remove('sd-theme-ui-dark');
+      wrapper.classList.add('sd-theme-ui-light');
+    }
+  }
+
+  const wrapper = document.querySelector('#theme-wrapper');
+  const switcher = document.querySelector('#theme-switcher');
+  switcher.addEventListener('click', toggleTheme);
+</script>
+```

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

@@ -0,0 +1,101 @@
+## Overview
+
+`<sd-tooltip>` — Used as a floating and non-actionable text label that explains an element or function of the user interface.
+
+## API
+
+### Examples
+
+Use the components tool by passing the args `component` and `example` for any of these combinations:
+
+- component: sd-tooltip, example: size
+- component: sd-tooltip, example: placement
+- component: sd-tooltip, example: disabled
+- component: sd-tooltip, example: trigger
+- component: sd-tooltip, example: close-trigger
+- component: sd-tooltip, example: hoist
+- component: sd-tooltip, example: custom-trigger
+
+### Key Properties
+
+- prop.size: 'lg'|'sm', default='lg' — Sets the size of the default trigger icon.
+- prop.content: string, default='' — The tooltip's content. If you need to display HTML, use the `content` slot instead.
+- prop.placement: |'top'|'top-start'|'top-end'|'bottom'|'bottom-start'|'bottom-end', default='top' — The preferred placement of the tooltip. Note that the actual placement may vary as needed to keep the tooltip
+  inside of the viewport.
+- prop.disabled: boolean, default=false — Disables the tooltip so it won't show when triggered.
+- prop.open: boolean, default=false — Indicates whether or not the tooltip is open. You can use this in lieu of the show/hide methods.
+- prop.trigger: string, default='click focus' — Controls how the tooltip is activated. Possible options include `click`, `hover`, `focus`, and `manual`. Multiple
+  options can be passed by separating them with a space. When manual is used, the tooltip must be activated
+  programmatically.
+- prop.closeTrigger [attr: close-trigger]: string, default='click focus escape' — Controls how the tooltip is closed.
+  Possible options: `click`, `hover`, `focus`, `escape`, `manual`.
+  Multiple options can be passed with spaces.
+- prop.hoist: boolean, default=false — Enable this option to prevent the tooltip from being clipped when the component is placed inside a container with
+  `overflow: auto|hidden|scroll`. Hoisting uses a fixed positioning strategy that works in many, but not all,
+  scenarios.
+- prop.dir: 'ltr'|'rtl'|'auto' — The element's directionality.
+- prop.lang: string — The element's language.
+
+### Events
+
+- event.sd-show: Emitted when the tooltip begins to show.
+- event.sd-after-show: Emitted after the tooltip has shown and all animations are complete.
+- event.sd-hide: Emitted when the tooltip begins to hide.
+- event.sd-after-hide: Emitted after the tooltip has hidden and all animations are complete.
+
+### Slots
+
+- slot.default: The tooltip's target element. Avoid slotting in more than one element, as subsequent ones will be ignored.
+- slot.anchor: Slot to change the default trigger icon. The default icon is an info circle.
+- slot.content: The content to render in the tooltip. Alternatively, you can use the `content` attribute.
+
+### CSS Parts
+
+- part.base: The component's base wrapper, an `<sd-popup>` element.
+- part.base\_\_popup: The popup's exported `popup` part. Use this to target the tooltip's popup container.
+- part.base\_\_arrow: The popup's exported `arrow` part. Use this to target the tooltip's arrow.
+- part.body: The tooltip's body where its content is rendered.
+
+## Guidelines
+
+### Use Cases
+
+- Provide additional, useful, and non-essential information about form fields.
+- Expand abbreviations or acronyms that might be unfamiliar to users.
+- Offer detailed information about specific data points in charts or graphs.
+- Provide more context for error messages or warnings and anticipate any questions that users may have.
+
+### Rules
+
+### Trigger Element
+
+- Use any interactive element as a tooltip trigger by placing it in the provided slot; the default trigger (info-i) can be replaced based on context or preference.
+
+### Content
+
+- Use short, descriptive text; if a longer explanation is required, consider non-interactive means to convey this information.
+- Avoid jargon or highly technical language; aim to solve questions, not trigger more.
+- Do not use for critical or unique information.
+- Do not place links, buttons, or other interactive elements within the content.
+
+### Behavior and Placement
+
+- Place the tooltip where the floating element does not obscure important content related to the subject.
+- Ensure it disappears when the user interacts with other elements.
+- Avoid tootlips being cropped by other elements of the interface; use appropriate placement for this purpose.
+
+### Styling
+
+- Display a headline by bolding the text if it makes the content easier to understand.
+- Emphasize key information by bolding parts of the text.
+
+### Background
+
+- Use with light background options of white, neutral-100 and primary-100.
+
+### Accessibility
+
+- Avoid placing buttons, links, or other interactive controls inside a tooltip, as it’s designed to be an ephemeral container for supplementary information.
+- On desktop, tooltips open by default on hover over the trigger element, or optionally on click. They close by clicking the trigger again or by moving the pointer away.
+- On touch devices, tooltips open when tapping on the trigger element and close by tapping on the trigger element again.
+- For keyboard navigation, tooltips should open by focusing (Tab) on the trigger element and close by pressing Escape or by moving focus away.

package/metadata/packages/components/sd-tooltip/stories/close-trigger.md

@@ -0,0 +1,19 @@
+Use the `close-trigger` attribute to control how the tooltip is triggered to **close**:
+
+- `click`: Removes the tooltip when the trigger element is clicked
+- `hover`: Removes the tooltip when the trigger element is hovered
+- `focus`: Removes the tooltip when the trigger element is focused
+- `manual`: Removes the tooltip when the `open` attribute is set to `false`
+
+```html
+<div class="h-[100px]">
+  <sd-tooltip
+    content="Lorem ipsum"
+    placement="bottom-start"
+    size="lg"
+    trigger="click"
+    open="true"
+    close-trigger="click"
+  ></sd-tooltip>
+</div>
+```

package/metadata/packages/components/sd-tooltip/stories/custom-trigger.md

@@ -0,0 +1,20 @@
+It is possible to change the tooltip trigger element by defining the new trigger in the default slot.
+However, be aware that this affects the accessibility of the component due to the loss of the aria reference to the trigger element which will be located in the shadow DOM.
+In this example we provide a solution to this problem by using a live region to announce the tooltip content when the trigger element is clicked.
+
+```html
+<sd-tooltip size="lg" content="This tooltip is accessible" placement="bottom" trigger="click" class="custom-tooltip">
+  <sd-button class="custom-button">Custom Trigger</sd-button>
+</sd-tooltip>
+<div aria-live="assertive" class="sr-only live-region"></div>
+<script>
+  const liveRegion = document.querySelector('.live-region');
+  const tooltip = document.querySelector('.custom-tooltip');
+  const tooltipContent = tooltip.getAttribute('content');
+  const tooltipLabel = tooltipContent;
+
+  tooltip.addEventListener('sd-after-show', event => {
+    liveRegion.textContent = liveRegion.textContent === tooltipContent ? tooltipContent + '\\u200B' : tooltipContent;
+  });
+</script>
+```

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

@@ -0,0 +1,5 @@
+Use the `disabled` attribute to disable the tooltip trigger.
+
+```html
+<sd-tooltip content="Lorem ipsum" placement="top" size="lg" disabled></sd-tooltip>
+```

package/metadata/packages/components/sd-tooltip/stories/hoist.md

@@ -0,0 +1,7 @@
+Use the `hoist` attribute to prevent the tooltip from being clipped when it's placed inside a container with `overflow: auto | hidden | scroll`.
+
+```html
+<div class="flex items-end overflow-scroll h-[5em] w-16">
+  <sd-tooltip content="Lorem ipsum" placement="bottom-start" size="lg" hoist></sd-tooltip>
+</div>
+```

package/metadata/packages/components/sd-tooltip/stories/placement.md

@@ -0,0 +1,43 @@
+Use the `placement` attribute to set the placement:
+
+- `top-start`: Displays tooltip above the trigger element and aligns arrow to the start of the tooltip container
+- `top`: Displays tooltip above the trigger element
+- `top-end`: Displays tooltip above the trigger element and aligns arrow to the end of the tooltip container
+- `bottom-start`: Displays tooltip below the trigger element and aligns arrow to the start of the tooltip container
+- `bottom`: Displays tooltip below the trigger element
+- `bottom-end`: Displays tooltip below the trigger element and aligns arrow to the end of the tooltip container
+
+```html
+<div class="grid grid-cols-1 justify-items-center md:grid-cols-3 md:justify-items-start gap-24 p-12">
+  <div>
+    <sd-tooltip content="Top Start Positioning" placement="top-start" open size="lg" trigger="click focus"></sd-tooltip>
+  </div>
+  <div>
+    <sd-tooltip content="Top Positioning" placement="top" open size="lg" trigger="click focus"></sd-tooltip>
+  </div>
+  <div>
+    <sd-tooltip content="Top End Positioning" placement="top-end" open size="lg" trigger="click focus"></sd-tooltip>
+  </div>
+  <div>
+    <sd-tooltip
+      content="Bottom Start Positioning"
+      placement="bottom-start"
+      open
+      size="lg"
+      trigger="click focus"
+    ></sd-tooltip>
+  </div>
+  <div>
+    <sd-tooltip content="Bottom Positioning" placement="bottom" open size="lg" trigger="click focus"></sd-tooltip>
+  </div>
+  <div>
+    <sd-tooltip
+      content="Bottom End Positioning"
+      placement="bottom-end"
+      open
+      size="lg"
+      trigger="click focus"
+    ></sd-tooltip>
+  </div>
+</div>
+```

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

@@ -0,0 +1,11 @@
+Use the `size` attribute to change the tooltip trigger size:
+
+- `lg` (default)
+- `sm`
+
+```html
+<div class="flex items-center gap-12">
+  <sd-tooltip content="Lorem ipsum" placement="bottom-start" size="lg" trigger="click focus"></sd-tooltip>
+  <sd-tooltip content="Lorem ipsum" placement="bottom-start" size="sm" trigger="click focus"></sd-tooltip>
+</div>
+```

package/metadata/packages/components/sd-tooltip/stories/trigger.md

@@ -0,0 +1,10 @@
+Use the `trigger` attribute to control how the tooltip is triggered to **open** :
+
+- `click`: Displays the tooltip when the trigger element is clicked
+- `hover`: Displays the tooltip when the trigger element is hovered
+- `focus`: Displays the tooltip when the trigger element is focused
+- `manual`: Displays the tooltip when the `open` attribute is set to `true`
+
+```html
+<sd-tooltip content="Lorem ipsum" placement="top-start" size="lg" trigger="click"></sd-tooltip>
+```

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

@@ -0,0 +1,70 @@
+## Overview
+
+`<sd-video>` — Used to wrap videos to provide basic styling.
+
+## API
+
+### Examples
+
+Use the components tool by passing the args `component` and `example` for any of these combinations:
+
+- component: sd-video, example: video-element-with-poster-slot
+- component: sd-video, example: playing
+
+### Key Properties
+
+- prop.playing: boolean, default=false — Set to `true` to hide the play icon.
+- prop.isBelowBreakpoint: boolean, default=false — Reactive property to trigger breakpoint re-renders.
+- prop.dir: 'ltr'|'rtl'|'auto' — The element's directionality.
+- prop.lang: string — The element's language.
+
+### Events
+
+- event.sd-play: Event emitted when clicking the `play-icon`. Listen for this event and use it to play the wrapped video.
+
+### Slots
+
+- slot.default: The default slot used to pass a video player element.
+- slot.play-icon: The video's play icon.
+- slot.poster: Specifies an image to be shown before initial play of the wrapped video. Acts like the `poster` attribute on the native video tag.
+
+### CSS Parts
+
+- part.base: The component's base wrapper.
+- part.play-button: The `<button>` element wrapper around the play-icon slot (full screen to field all click events).
+- part.play-button-bg: The `<div>` element wrapper around the play-button that defines the circular background.
+- part.poster-wrapper: The `<div>` element wrapper around the poster slot.
+
+## Guidelines
+
+### Use Cases
+
+- Promote new products, services, or events.
+- Embed instructional content to guide users through complex processes or tutorials.
+- Display educational clips in e-learning applications.
+
+### Rules
+
+### Content
+
+- Include a description of the content.
+- Use the “poster” slot to display a descriptive image before playback, giving users a preview of the content.
+- Use the “&--copyright” property to display a copyright.
+
+### Behavior and Interaction
+
+- Provide controls to allow users to play and pause.
+- Avoid autoplaying content with sound, as it can be disruptive; if autoplay is necessary, consider muting the audio.
+- Ensure users have control over playback to prevent unexpected starts.
+
+### Performance and Loading
+
+- Use appropriate formats and compress video files without significant quality loss to optimize loading times and performance.
+- Limit the number of media items on a single page to prevent slowing down page load times.
+
+### Accessibility
+
+- Disable or limit autoplay features. Unsolicited audio can disorient or overwhelm users, particularly screen reader users.
+- Provide captions or subtitles for video content to support users who are deaf or hard of hearing.
+- Offer a transcript (text version) if the video contains spoken dialogue or other critical audio elements.
+- Make status announcements (e.g., “Video paused,” “Video started”) if needed, via aria-live or a similar approach.

package/metadata/packages/components/sd-video/stories/playing.md

@@ -0,0 +1,11 @@
+Use the `playing` attribute to show/hide the play-button.
+
+```html
+<sd-video playing>
+  <img
+    alt="Video highlighting Union Investment's digital transformation through a design system named Solid that enhances accessibility, sustainability, and efficiency."
+    class="w-[854px] aspect-video cover"
+    src="./placeholders/images/union-investment.png"
+  />
+</sd-video>
+```

package/metadata/packages/components/sd-video/stories/video-element-with-poster-slot.md

@@ -0,0 +1,24 @@
+- Use in combination with a viewer component (e. g. from Moving Image) or a bare `<video>`-Tag.
+- Use the `poster` slot to add a preview image.
+
+```html
+<sd-video>
+  <video controls="" id="video-example" class="w-[854px] aspect-video">
+    <source src="./placeholders/videos/sds-placeholder-video/sds-placeholder-video.webm" type="video/webm" />
+    <track
+      label="English"
+      kind="subtitles"
+      srclang="en"
+      src="./placeholders/videos/sds-placeholder-video/sds-placeholder-video.vtt"
+      default
+    />
+    Your browser does not support the video tag.
+  </video>
+  <img
+    slot="poster"
+    alt="Video highlighting Union Investment's digital transformation through a design system named Solid that enhances accessibility, sustainability, and efficiency."
+    class="w-[854px] aspect-video cover"
+    src="./placeholders/images/union-investment.png"
+  />
+</sd-video>
+```