@solid-design-system/mcp 0.0.1

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

@@ -0,0 +1,135 @@
+## Overview
+
+`<sd-notification>` — Used to communicate information or status to users, notifications can be displayed inline or as toast messages, either individually or in stacks.
+
+## API
+
+### Examples
+
+Use the components tool by passing the args `component` and `example` for any of these combinations:
+
+- component: sd-notification, example: variants
+- component: sd-notification, example: open
+- component: sd-notification, example: closable
+- component: sd-notification, example: duration
+- component: sd-notification, example: duration-indicator
+- component: sd-notification, example: toast-notification
+- component: sd-notification, example: toast-bottom-center
+
+### Key Properties
+
+- prop.variant: 'info'|'success'|'error'|'warning', default='info' — The sd-notification's theme.
+- prop.open: boolean, default=false — Indicates whether or not sd-notification is open. You can toggle this attribute to show and hide the notification, or you can
+  use the `show()` and `hide()` methods and this attribute will reflect the notifications's open state.
+- prop.closable: boolean, default=false — Enables a close button that allows the user to dismiss the notification.
+  It also allows the user to dismiss the notification using the ESC.
+- prop.duration: default=Infinity — The length of time, in milliseconds, the sd-notification will show before closing itself. If the user interacts with
+  the notification before it closes (e.g. moves the mouse over it), the timer will restart. Defaults to `Infinity`, meaning
+  the notification will not close on its own.
+- prop.durationIndicator [attr: duration-indicator]: boolean, default=false — Enables an animation that visualizes the duration of a notification.
+- prop.toastStack [attr: toast-stack]: 'top-right'|'bottom-center', default='top-right' — The position of the toasted sd-notification.
+- prop.dir: 'ltr'|'rtl'|'auto' — The element's directionality.
+- prop.lang: string — The element's language.
+
+### Events
+
+- event.sd-show: Emitted when the notification opens.
+- event.sd-after-show: Emitted after the notification opens and all animations are complete.
+- event.sd-hide: Emitted when the notification closes.
+- event.sd-after-hide: Emitted after the notification closes and all animations are complete.
+
+### Slots
+
+- slot.default: The sd-notification's main content.
+- slot.icon: An icon to show in the sd-notification. Works best with `<sd-icon>`.
+
+### CSS Parts
+
+- part.base: The component's base wrapper.
+- part.wrapper: The container that wraps all the notification elements.
+- part.icon: The container that wraps the optional icon.
+- part.content: The container that wraps the notifications's main content and the close button.
+- part.message: The container that wraps the notifications's main content.
+- part.duration-indicator\_\_elapsed: The current duration indicator.
+- part.duration-indicator\_\_total: The total duration indicator.
+- part.close-button: The close button, an `<sd-icon-button>`.
+
+## Guidelines
+
+### Use Cases
+
+#### Inline Notification
+
+Provide contextual feedback – that needs to be noted – to users through inline notifications that are directly embedded within the content of a page or form.
+
+- Integrated into the area where the user is already focused to avoid disrupting the user's workflow.
+- Provide feedback on user actions, such as errors, warnings, or confirmations 
(e.g. "Unable to save changes. Check your internet connection and try again.", "You have unsaved changes. Are you sure you want to leave this page?" or "Payment completed. Thank you for your purchase!")
+- Announce important updates or changes within the application 
(e.g. New feature alert! You can now schedule posts directly from the dashboard.", "Maintenance scheduled for January 30th, 2:00 AM - 4:00 AM. The application will be unavailable during this time.")
+- Highlight critical information or display system messages that require user attention
(e.g. "System update required. Please restart your application to apply the latest updates." or "Your account has been temporarily suspended due to suspicious activity. Contact support for assistance.")
+- May contain interactive elements such as links and buttons.
+
+#### Toast Notification
+
+Provide brief, unobtrusive messages to users through toast notifications that overlay the interface and do not necessarily need attention.
+
+- Take the user's attention temporarily away from their current task by appearing on the screen with animations to ensure they are noticed.
+- Provide feedback on user actions, such as errors, warnings, or confirmations. 
(e.g., "Failed to load data", "Your message has been sent", "Your settings have been saved").
+- Announce updates, reminders, or confirmations 
(e.g., "Your settings have been saved").
+- May contain interactive elements such as links and buttons.
+- They can serve as supplementary information for content available on other pages (e.g., a toast notification "Item has been added to the cart" alongside a shopping cart page).
+
+### Rules
+
+### Content
+
+- Provide clear, actionable information or guidance, avoiding vague or overly technical language.
+- Avoid repeating or paraphrasing the title in the body if both are present.
+- Avoid using non-essential information that can be conveyed through other means.
+
+### Behavior
+
+- Allow users to dismiss notifications if they are not critical.
+- Avoid displaying important information in toast notifications that automatically disappear.
+- If a notification has a set duration, include a duration indicator to show how much time remains before it disappears.
+- Avoid overloading users with too many notifications at once.
+- Use sd-dialog for actions that require immediate user response.
+
+### Placement
+
+- Place notifications in consistent locations across the application.
+- Avoid placing notifications where they can be easily overlooked or ignored.
+
+### Styling
+
+- Use appropriate variant to indicate the semantic meaning (e.g., green for success, red for error, etc.).
+- Keep the text style as default; text can be bolded or linked.
+- Keep the provided icon as it cannot be omitted.
+
+### Accessibility
+
+- Screen Reader Support: By using these ARIA roles appropriately, you can ensure that all users, including those who rely on screen readers, receive important notifications in a timely and accessible manner. Use ARIA role "alert" for notifications needing immediate attention, like error messages or critical updates. Screen readers announce these immediately, interrupting ongoing speech. Use ARIA role "status" for less urgent notifications, like informational messages. Screen readers announce these without interrupting ongoing speech.
+- Keyboard Navigation: Notifications should be reachable and dismissible using keyboard shortcuts. For example, use the “Tab” key to navigate to the notification and “Esc” to dismiss it.
+- Accessible Focus Order: Ensure that notifications with actionable items have an accessible focus order.
+- Visibility Duration: Important notifications should not disappear automatically. Users should have enough time to read and understand the message. Supplementary information for content available on other pages can disappear automatically.
+
+#### Toast Notifications
+
+<sd-notification variant="warning" open>
+  <p>**Please be aware of the following accessibility requirements:**</p>
+  <ul>
+    <li>Prefer default (inline) notifications over toast notifications.</li>
+    <li>Don’t use toasts for critical information.</li>
+    <li>Don’t overuse toast notifications.</li>
+    <li>When the page is zoomed in, toasts may obscure large parts of the screen.</li>
+    <li>Only use interactive elements in toast notifications for additional actions.</li>
+    <li>Consider not using buttons in timed toasts.</li>
+  </ul>
+</sd-notification><br>
+
+- Toast messages make use of the role="status" attribute. This will trigger certain assistive devices, such as screen readers, to announce the content at a convenient moment after the toast appears.
+- Hotkey Access: Toast notifications will use an already existing container from the DOM with the ids "sd-toast-stack--top-right" and "sd-toast-stack--bottom-center". The "aria-label" prop should be set to set proper names to the containers. In case these containers are not present, the sd-notification will take care of creating it with default label "Notifications". Landmark regions can be navigated using the keyboard by pressing the F6 key to move forward, and the Shift + F6 key to move backward.
+- Don't trap focus.
+
+<sd-notification variant="warning" open>
+  **Known screen readers issues:** Due to inconsistency between screen readers when announcing the toast notification we recommend using inline notification
+</sd-notification><br>

package/metadata/packages/components/sd-notification/stories/closable.md

@@ -0,0 +1,13 @@
+Use the `closable` attribute to toggle a close button.
+
+```html
+<sd-notification id="closable-example" variant="info" open closable>Lorem ipsum dolor sit</sd-notification>
+<script>
+  var closableNotification = document.querySelector('#closable-example');
+  closableNotification.addEventListener('sd-after-hide', () => {
+    setTimeout(() => {
+      closableNotification.open = true;
+    }, 3000);
+  });
+</script>
+```

package/metadata/packages/components/sd-notification/stories/duration-indicator.md

@@ -0,0 +1,15 @@
+Use the `duration-indicator` attribute to enable an animation that visualizes the duration of a notification.
+
+```html
+<sd-notification id="duration-indicator-attribute" variant="info" open duration-indicator duration="5000">
+  Notification will self close after 5 seconds
+</sd-notification>
+<script>
+  var durationIndicator = document.querySelector('#duration-indicator-attribute');
+  durationIndicator.addEventListener('sd-after-hide', () => {
+    setTimeout(() => {
+      durationIndicator.open = true;
+    }, 3000);
+  });
+</script>
+```

package/metadata/packages/components/sd-notification/stories/duration.md

@@ -0,0 +1,16 @@
+Use the `duration` attribute to set the duration (in milliseconds) of the notification.
+
+```html
+<sd-notification variant="info" open duration="Infinity">Notification will stay open (Infinity)</sd-notification>
+<sd-notification id="duration-example" variant="info" open duration="5000">
+  Notification will self close after 5 seconds
+</sd-notification>
+<script>
+  var notificationDuration = document.querySelector('#duration-example');
+  notificationDuration.addEventListener('sd-after-hide', () => {
+    setTimeout(() => {
+      notificationDuration.open = true;
+    }, 3000);
+  });
+</script>
+```

package/metadata/packages/components/sd-notification/stories/open.md

@@ -0,0 +1,5 @@
+Use the `open` attribute to toggle the visibility of the notification.
+
+```html
+<sd-notification variant="info" open>Lorem ipsum dolor sit</sd-notification>
+```

package/metadata/packages/components/sd-notification/stories/toast-bottom-center.md

@@ -0,0 +1,53 @@
+<h4 class="sd-headline sd-headline--size-lg">Toast placement bottom center</h4>
+Use the `data-notification-position` attribute with the value `bottom-center` to align the toast to the bottom center.
+
+```html
+<div class="flex gap-2">
+  <sd-button variant="secondary" data-notification-type="info" data-notification-position="bottom-center" class="w-24">
+    Info
+  </sd-button>
+  <sd-button
+    variant="secondary"
+    data-notification-type="success"
+    data-notification-position="bottom-center"
+    class="w-24"
+  >
+    Success
+  </sd-button>
+  <sd-button
+    variant="secondary"
+    data-notification-type="warning"
+    data-notification-position="bottom-center"
+    class="w-24"
+    >Warning</sd-button
+  >
+  <sd-button variant="secondary" data-notification-type="error" data-notification-position="bottom-center" class="w-24"
+    >Error</sd-button
+  >
+</div>
+
+<script>
+  var buttons = document.querySelectorAll('[data-notification-position="bottom-center"]');
+
+  function notifyBottomCenter(variant = 'info') {
+    const notification = Object.assign(document.createElement('sd-notification'), {
+      closable: true,
+      variant: variant,
+      toastStack: 'bottom-center',
+      duration: Infinity,
+      innerHTML: 'Lorem ipsum dolor sit amet.'
+    });
+
+    notification.style.width = '250px';
+
+    document.body.append(notification);
+    return notification.toast();
+  }
+
+  buttons.forEach(button => {
+    button.addEventListener('click', () => {
+      notifyBottomCenter(button.getAttribute('data-notification-type'));
+    });
+  });
+</script>
+```

package/metadata/packages/components/sd-notification/stories/toast-notification.md

@@ -0,0 +1,67 @@
+Use the `toastStack` attribute to change the position of the toast notifications:
+
+- `top-right` (default)
+- `bottom-center`
+  **Important:** Some screen readers may occasionally ignore live regions that are added to a page after it has already loaded.
+  Therefore, to make sure the toast stack regions are already present on page load, please make sure to render the following:
+
+```html
+<div
+  role="region"
+  id="sd-toast-stack--top-right"
+  class="sd-toast-stack sd-toast-stack--top-right"
+  aria-label="Top right notifications"
+></div>
+<div
+  role="region"
+  id="sd-toast-stack--bottom-center"
+  class="sd-toast-stack sd-toast-stack--bottom-center"
+  aria-label="Bottom center notifications"
+></div>
+```
+
+**Hints:**
+
+- It requires the use of the `toast` method to work. Click on the `Show code` button to see the JavaScript code responsible for generating the toast notification.
+- Click on one of the buttons below to see the corresponding toast notification.
+<h4 class="sd-headline sd-headline--size-lg">Toast placement top right</h4>
+Use the `data-notification-position` attribute with the value `top-right` to align the toast to the top right.
+
+```html
+<div class="flex gap-2">
+  <sd-button variant="secondary" data-notification-type="info" data-notification-position="top-right" class="w-24">
+    Info
+  </sd-button>
+  <sd-button variant="secondary" data-notification-type="success" data-notification-position="top-right" class="w-24">
+    Success
+  </sd-button>
+  <sd-button variant="secondary" data-notification-type="warning" data-notification-position="top-right" class="w-24"
+    >Warning</sd-button
+  >
+  <sd-button variant="secondary" data-notification-type="error" data-notification-position="top-right" class="w-24"
+    >Error</sd-button
+  >
+</div>
+<script>
+  var buttons = document.querySelectorAll('[data-notification-position="top-right"]');
+
+  function notify(variant = 'info') {
+    const notification = Object.assign(document.createElement('sd-notification'), {
+      closable: true,
+      variant: variant,
+      toastStack: 'top-right',
+      duration: Infinity,
+      innerHTML: 'Lorem ipsum dolor sit amet.'
+    });
+
+    document.body.append(notification);
+    return notification.toast();
+  }
+
+  buttons.forEach(button => {
+    button.addEventListener('click', () => {
+      notify(button.getAttribute('data-notification-type'));
+    });
+  });
+</script>
+```

package/metadata/packages/components/sd-notification/stories/variants.md

@@ -0,0 +1,20 @@
+Use the `variant` attribute to change the theme of the notification:
+
+- `info` (default): suitable for notifications, conveying neutral information about an action
+- `success`: imply a successful or positive outcome of an action
+- `error`: indicate a destructive and irreversible outcome of an action
+- `warning`: alert for possible issues or significant changes that must be considered
+
+```html
+<style>
+  .notification-list > sd-notification::part(base) {
+    margin: 0;
+  }
+</style>
+<div class="flex flex-col gap-12 notification-list">
+  <sd-notification variant="info" open>Info Lorem ipsum dolor sit</sd-notification>
+  <sd-notification variant="success" open>Success Lorem ipsum dolor sit</sd-notification>
+  <sd-notification variant="error" open>Error Lorem ipsum dolor sit</sd-notification>
+  <sd-notification variant="warning" open>Warning Lorem ipsum dolor sit</sd-notification>
+</div>
+```

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

@@ -0,0 +1,55 @@
+## Overview
+
+`<sd-optgroup>` — Used to group `sd-option`components within an `sd-combobox`.
+
+## API
+
+### Examples
+
+Use the components tool by passing the args `component` and `example` for any of these combinations:
+
+- component: sd-optgroup, example: disabled
+
+### Key Properties
+
+- prop.disabled: boolean, default=false — Disables all options in the optgroup.
+- prop.label: string, default='' — The optgroups label. If you need to display HTML, use the `label` slot instead.
+- prop.dir: 'ltr'|'rtl'|'auto' — The element's directionality.
+- prop.lang: string — The element's language.
+
+### Slots
+
+- slot.default: The given options. Must be `<sd-option>` elements.
+- slot.label: The label for the optgroup
+
+### CSS Parts
+
+- part.base: The component's base wrapper.
+- part.label-container: The container that wraps prefix, label and base
+- part.divider: The divider that is displayed above the content
+- part.options: The container that wraps the <sd-option> elements.
+
+## Guidelines
+
+### Use Cases
+
+- Provide options in selects or comboboxes.
+- Allow users to select from a list of predefined choices in forms or settings, where they might choose one or more options.
+- Present filter options in searches or data tables.
+
+### Rules
+
+### Content
+
+- Make sure all items in the list are mutually exclusive and unambiguous to help users understand what they are selecting.
+- Provide a default choice where applicable to guide users.
+- Use the optional grouping label and/or divider attributes to visually identify the groups.
+
+### Behavior
+
+- Use the “checkbox” variant for multi-select and the “default” variant for single-select choices.
+- Provide a reason or alternative if some choice is disabled.
+
+### Accessibility
+
+- Ensure that the group label is short and concise as it may be read out when users enter the group.

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

@@ -0,0 +1,13 @@
+Use the disabled attribute in the <sd-optgroup> to disable the section and prevent it from being selected.
+
+```html
+<div class="h-[260px] w-[400px]">
+  <sd-combobox label="Label">
+    <sd-optgroup label="Section 1" disabled>
+      <sd-option value="1">Option</sd-option>
+      <sd-option value="2">Option</sd-option>
+      <sd-option value="3">Option</sd-option>
+    </sd-optgroup>
+  </sd-combobox>
+</div>
+```

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

@@ -0,0 +1,65 @@
+## Overview
+
+`<sd-option>` — Used to define selectable items within various form controls such as select.
+
+## API
+
+### Examples
+
+Use the components tool by passing the args `component` and `example` for any of these combinations:
+
+- component: sd-option, example: size
+- component: sd-option, example: checkbox
+- component: sd-option, example: selected
+- component: sd-option, example: disabled
+
+### Key Properties
+
+- prop.size: 'lg'|'md'|'sm', default='lg' — The option's size is inherited automatically from the `size` attribute of the parent `sd-select`.
+- prop.checkbox: boolean, default=false — Prefixes a styled checkbox to the option. Enabled automatically in `sd-select` when attribute `checklist` is set to `true`.
+- prop.disabled: boolean, default=false — Draws the option in a disabled state, preventing selection.
+- prop.value: string, default='' — The option's value. When selected, the containing form control will receive this value. The value must be unique
+  from other options in the same group. Values may not contain spaces, as spaces are used as delimiters when listing
+  multiple values.
+- prop.dir: 'ltr'|'rtl'|'auto' — The element's directionality.
+- prop.lang: string — The element's language.
+
+### Slots
+
+- slot.default: The option's label.
+- slot.left: Used to prepend an icon or similar element to the menu item.
+- slot.right: Used to append an icon or similar element to the menu item.
+
+### CSS Parts
+
+- part.checked-icon: The checked icon, an `<sd-icon>` element.
+- part.base: The component's base wrapper.
+- part.label: The option's label.
+- part.left: The container that wraps the left.
+- part.right: The container that wraps the right.
+
+## Guidelines
+
+### Use Cases
+
+- Provide options in selects or comboboxes.
+- Allow users to select from a list of predefined choices in forms or settings, where they might choose one or more options.
+- Present filter options in searches or data tables.
+
+### Rules
+
+### Content
+
+- Make sure all items in the list are mutually exclusive and unambiguous to help users understand what they are selecting.
+- Provide a default choice where applicable to guide users.
+
+### Behavior
+
+- Use the “checkbox” variant for multi-select and the “default” variant for single-select choices.
+- Provide a reason or alternative if some choice is disabled.
+
+### Accessibility
+
+- Long option names can be difficult to understand and perceive, so it’s best to keep them concise.
+- Ensure that the beginning of each option is unique to avoid confusion, especially for screen reader users.
+- Don’t include headings or interactive elements like links, buttons, or checkboxes within dropdown options.

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

@@ -0,0 +1,19 @@
+Use the `checkbox` attribute to make it a checkbox.
+Enabled automatically when using `sd-select` with attribute `checklist` set to `true`.
+
+```html
+<div class="h-[260px]">
+  <sd-select
+    class="max-w-[300px]"
+    label="Checkbox"
+    placeholder="Please select"
+    placement="bottom"
+    max-options-visible="3"
+    multiple
+  >
+    <sd-option value="option-1" checkbox>Checkbox option 1</sd-option>
+    <sd-option value="option-2" checkbox>Checkbox option 2</sd-option>
+    <sd-option value="option-3" checkbox>Checkbox option 3</sd-option>
+  </sd-select>
+</div>
+```

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

@@ -0,0 +1,22 @@
+Use the `disabled` attribute to disable an option.
+
+```html
+<div class="flex flex-row gap-12 h-[260px]">
+  <sd-select label="Disabled options" placeholder="Please select" placement="bottom" max-options-visible="3">
+    <sd-option value="option-1" disabled>option 1</sd-option>
+    <sd-option value="option-2" disabled>option 2</sd-option>
+    <sd-option value="option-3" disabled>option 3</sd-option>
+  </sd-select>
+  <sd-select
+    label="Disabled checkbox options"
+    placeholder="Please select"
+    placement="bottom"
+    max-options-visible="3"
+    multiple
+  >
+    <sd-option value="option-1" disabled checkbox>Checkbox option 1</sd-option>
+    <sd-option value="option-2" disabled checkbox>Checkbox option 2</sd-option>
+    <sd-option value="option-3" disabled checkbox>Checkbox option 3</sd-option>
+  </sd-select>
+</div>
+```

package/metadata/packages/components/sd-option/stories/selected.md

@@ -0,0 +1,23 @@
+Parent component `sd-select` controls state of `sd-option`.
+
+```html
+<div class="flex flex-row gap-12 h-[260px]">
+  <sd-select label="Selected option" placeholder="Please select" placement="bottom" size="lg" max-options-visible="3">
+    <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-select>
+  <sd-select
+    label="Multiple selected option"
+    placeholder="Please select"
+    placement="bottom"
+    size="lg"
+    max-options-visible="3"
+    multiple
+  >
+    <sd-option value="option-1" checkbox>Checkbox option 1</sd-option>
+    <sd-option value="option-2" checkbox>Checkbox option 2</sd-option>
+    <sd-option value="option-3" checkbox>Checkbox option 3</sd-option>
+  </sd-select>
+</div>
+```

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

@@ -0,0 +1,26 @@
+Use the `size` attribute to change the option’s size:
+
+- `lg` (default)
+- `md`
+- `sm`
+  This will be inherited automatically from the size attribute of the parent `sd-select`.
+
+```html
+<div class="flex flex-row gap-4 h-[260px]">
+  <sd-select label="Large" placeholder="Please select" placement="bottom" max-options-visible="3">
+    <sd-option value="option-1" size="lg">option 1</sd-option>
+    <sd-option value="option-2" size="lg">option 2</sd-option>
+    <sd-option value="option-3" size="lg">option 3</sd-option>
+  </sd-select>
+  <sd-select label="Medium" placeholder="Please select" placement="bottom" max-options-visible="3" size="md">
+    <sd-option value="option-1" size="md">option 1</sd-option>
+    <sd-option value="option-2" size="md">option 2</sd-option>
+    <sd-option value="option-3" size="md">option 3</sd-option>
+  </sd-select>
+  <sd-select label="Small" placeholder="Please select" placement="bottom" max-options-visible="3" size="sm">
+    <sd-option value="option-1" size="sm">option 1</sd-option>
+    <sd-option value="option-2" size="sm">option 2</sd-option>
+    <sd-option value="option-3" size="sm">option 3</sd-option>
+  </sd-select>
+</div>
+```

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

@@ -0,0 +1,66 @@
+## Overview
+
+`<sd-popup>` — Popup is a utility that lets you declaratively anchor "popup" containers to another element.
+
+## API
+
+### Key Properties
+
+- prop.anchor: Element|string — The element the popup will be anchored to. If the anchor lives outside of the popup, you can provide its `id` or a
+  reference to it here. If the anchor lives inside the popup, use the `anchor` slot instead.
+- prop.active: boolean, default=false — Activates the positioning logic and shows the popup. When this attribute is removed, the positioning logic is torn
+  down and the popup will be hidden.
+- prop.placement: |'top'|'top-start'|'top-end'|'bottom'|'bottom-start'|'bottom-end'|'right'|'right-start'|'right-end'|'left'|'left-start'|'left-end', default='top' — The preferred placement of the popup. Note that the actual placement will vary as configured to keep the
+  panel inside of the viewport.
+- prop.strategy: 'absolute'|'fixed', default='absolute' — Determines how the popup is positioned. The `absolute` strategy works well in most cases, but if
+  overflow is clipped, using a `fixed` position strategy can often workaround it.
+- prop.distance: number, default=0 — The distance in pixels from which to offset the panel away from its anchor.
+- prop.skidding: number, default=0 — The distance in pixels from which to offset the panel along its anchor.
+- prop.arrow: boolean, default=false — Attaches an arrow to the popup. The arrow's size and color can be customized using the `--arrow-size` and
+  `--arrow-color` custom properties. For additional customizations, you can also target the arrow using
+  `::part(arrow)` in your stylesheet.
+- prop.arrowPlacement [attr: arrow-placement]: |'start'|'end'|'center'|'anchor', default='anchor' — The placement of the arrow. The default is `anchor`, which will align the arrow as close to the center of the
+  anchor as possible, considering available space and `arrow-padding`. A value of `start`, `end`, or `center` will
+  align the arrow to the start, end, or center of the popover instead.
+- prop.arrowPadding [attr: arrow-padding]: number, default=10 — The amount of padding between the arrow and the edges of the popup. If the popup has a border-radius, for example,
+  this will prevent it from overflowing the corners.
+- prop.flip: boolean, default=false — When set, placement of the popup will flip to the opposite site to keep it in view. You can use
+  `flipFallbackPlacements` to further configure how the fallback placement is determined.
+- prop.flipFallbackPlacements [attr: flip-fallback-placements]: string, default='' — If the preferred placement doesn't fit, popup will be tested in these fallback placements until one fits. Must be a
+  string of any number of placements separated by a space, e.g. "top bottom left". If no placement fits, the flip
+  fallback strategy will be used instead.
+- prop.flipFallbackStrategy [attr: flip-fallback-strategy]: 'best-fit'|'initial', default='best-fit' — When neither the preferred placement nor the fallback placements fit, this value will be used to determine whether
+  the popup should be positioned using the best available fit based on available space or as it was initially
+  preferred.
+- prop.flipBoundary: Element|Element[] — The flip boundary describes clipping element(s) that overflow will be checked relative to when flipping. By
+  default, the boundary includes overflow ancestors that will cause the element to be clipped. If needed, you can
+  change the boundary by passing a reference to one or more elements to this property.
+- prop.flipPadding [attr: flip-padding]: number, default=0 — The amount of padding, in pixels, to exceed before the flip behavior will occur.
+- prop.shift: boolean, default=false — Moves the popup along the axis to keep it in view when clipped.
+- prop.shiftBoundary: Element|Element[] — The shift boundary describes clipping element(s) that overflow will be checked relative to when shifting. By
+  default, the boundary includes overflow ancestors that will cause the element to be clipped. If needed, you can
+  change the boundary by passing a reference to one or more elements to this property.
+- prop.shiftPadding [attr: shift-padding]: number, default=0 — The amount of padding, in pixels, to exceed before the shift behavior will occur.
+- prop.autoSize [attr: auto-size]: 'horizontal'|'vertical'|'both' — When set, this will cause the popup to automatically resize itself to prevent it from overflowing.
+- prop.sync: 'width'|'height'|'both' — Syncs the popup's width or height to that of the anchor element.
+- prop.autoSizeBoundary: Element|Element[] — The auto-size boundary describes clipping element(s) that overflow will be checked relative to when resizing. By
+  default, the boundary includes overflow ancestors that will cause the element to be clipped. If needed, you can
+  change the boundary by passing a reference to one or more elements to this property.
+- prop.autoSizePadding [attr: auto-size-padding]: number, default=0 — The amount of padding, in pixels, to exceed before the auto-size behavior will occur.
+- prop.dir: 'ltr'|'rtl'|'auto' — The element's directionality.
+- prop.lang: string — The element's language.
+
+### Events
+
+- event.sd-reposition: Emitted when the popup is repositioned. This event can fire a lot, so avoid putting expensive operations in your listener or consider debouncing it.
+- event.sd-current-placement: Emitted when the popup's placement changes automatically based on screen limitations.
+
+### Slots
+
+- slot.default: The popup's content.
+- slot.anchor: The element the popup will be anchored to. If the anchor lives outside of the popup, you can use the `anchor` attribute or property instead.
+
+### CSS Parts
+
+- part.arrow: The arrow's container. Avoid setting `top|bottom|left|right` properties, as these values are assigned dynamically as the popup moves. This is most useful for applying a background color to match the popup, and maybe a border or box shadow.
+- part.popup: The popup's container. Useful for setting a background color, box shadow, etc.