@synergy-design-system/metadata 1.0.0 → 3.0.1

package/data/layers/examples/component/component:syn-drawer.md

@@ -0,0 +1,346 @@
+## Default
+
+Drawers slide in from a container to expose additional options and information.
+
+```html
+<syn-drawer open="" label="Drawer">
+  Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+  <span slot="footer"> </span>
+  <syn-button class="close-icon" slot="footer" variant="filled"
+    >Close</syn-button
+  >
+  <span slot="footer"> </span>
+  <script slot="footer">
+    document.querySelector(".close-icon").addEventListener("click", (e) => {
+      e.target.closest("syn-drawer").hide();
+    });
+  </script>
+  <span slot="footer"> </span>
+</syn-drawer>
+
+<syn-button class="drawer-default-story-opener">Open Drawer</syn-button>
+<script type="module">
+  const openButtons = document.querySelectorAll(".drawer-default-story-opener");
+
+  // Make sure to add each event only once!
+  Array.from(openButtons).forEach((btn) => {
+    if (!btn.classList.contains("story-loaded")) {
+      const drawer = btn.parentElement.querySelector("syn-drawer");
+      const closeButton = drawer.querySelector('syn-button[variant="filled"]');
+
+      btn.addEventListener("click", () => drawer.show());
+      closeButton.addEventListener("click", () => drawer.hide());
+
+      btn.classList.add("story-loaded");
+    }
+  });
+</script>
+```
+
+---
+
+## Slide In From Start
+
+By default, drawers slide in from the end. To make the drawer slide in from the start, set the placement attribute to start.
+
+```html
+<syn-drawer
+  label="Drawer"
+  open=""
+  placement="start"
+  class="drawer-placement-start"
+>
+  This drawer slides in from the start.
+  <syn-button slot="footer" variant="filled">Close</syn-button>
+</syn-drawer>
+
+<syn-button>Open Drawer</syn-button>
+
+<script type="module">
+  const drawer = document.querySelector(".drawer-placement-start");
+  const openButton = drawer.nextElementSibling;
+  const closeButton = drawer.querySelector('syn-button[variant="filled"]');
+
+  openButton.addEventListener("click", () => drawer.show());
+  closeButton.addEventListener("click", () => drawer.hide());
+</script>
+```
+
+---
+
+## Slide In From Top
+
+To make the drawer slide in from the top, set the placement attribute to top.
+
+```html
+<syn-drawer label="Drawer" open="" placement="top" class="drawer-placement-top">
+  This drawer slides in from the top.
+  <syn-button slot="footer" variant="filled">Close</syn-button>
+</syn-drawer>
+
+<syn-button>Open Drawer</syn-button>
+
+<script type="module">
+  const drawer = document.querySelector(".drawer-placement-top");
+  const openButton = drawer.nextElementSibling;
+  const closeButton = drawer.querySelector('syn-button[variant="filled"]');
+
+  openButton.addEventListener("click", () => drawer.show());
+  closeButton.addEventListener("click", () => drawer.hide());
+</script>
+```
+
+---
+
+## Slide In From Bottom
+
+To make the drawer slide in from the bottom, set the placement attribute to bottom.
+
+```html
+<syn-drawer
+  label="Drawer"
+  open=""
+  placement="bottom"
+  class="drawer-placement-bottom"
+>
+  This drawer slides in from the bottom.
+  <syn-button slot="footer" variant="filled">Close</syn-button>
+</syn-drawer>
+
+<syn-button>Open Drawer</syn-button>
+
+<script type="module">
+  const drawer = document.querySelector(".drawer-placement-bottom");
+  const openButton = drawer.nextElementSibling;
+  const closeButton = drawer.querySelector('syn-button[variant="filled"]');
+
+  openButton.addEventListener("click", () => drawer.show());
+  closeButton.addEventListener("click", () => drawer.hide());
+</script>
+```
+
+---
+
+## Contained To An Element
+
+By default, drawers slide out of their containing block, which is usually the viewport. To make a drawer slide out of a parent element, add the contained attribute to the drawer and apply position: relative to its parent.Unlike normal drawers, contained drawers are not modal. This means they do not show an overlay, they do not trap focus, and they are not dismissible with Escape. This is intentional to allow users to interact with elements outside of the drawer.
+
+```html
+<div
+  style="
+    position: relative;
+    border: solid 2px var(--syn-panel-border-color);
+    height: 300px;
+    padding: 1rem;
+    margin-bottom: 1rem;
+  "
+>
+  The drawer will be contained to this box. This content won't shift or be
+  affected in any way when the drawer opens.
+
+  <syn-drawer
+    label="Drawer"
+    open=""
+    contained=""
+    class="drawer-contained"
+    style="--size: 50%"
+  >
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+    <syn-button slot="footer" variant="filled">Close</syn-button>
+  </syn-drawer>
+</div>
+
+<syn-button>Toggle Drawer</syn-button>
+
+<script type="module">
+  const drawer = document.querySelector(".drawer-contained");
+  const openButton = drawer.parentElement.nextElementSibling;
+  const closeButton = drawer.querySelector('syn-button[variant="filled"]');
+
+  openButton.addEventListener("click", () => (drawer.open = !drawer.open));
+  closeButton.addEventListener("click", () => drawer.hide());
+</script>
+```
+
+---
+
+## Custom Size
+
+Use the --size custom property to set the drawer’s size. This will be applied to the drawer’s width or height depending on its placement.
+
+```html
+<syn-drawer
+  label="Drawer"
+  open=""
+  placement="start"
+  class="drawer-custom-size"
+  style="--size: 50vw"
+>
+  This drawer is always 50% of the viewport.
+  <syn-button slot="footer" variant="filled">Close</syn-button>
+</syn-drawer>
+
+<syn-button>Open Drawer</syn-button>
+
+<script type="module">
+  const drawer = document.querySelector(".drawer-custom-size");
+  const openButton = drawer.nextElementSibling;
+  const closeButton = drawer.querySelector('syn-button[variant="filled"]');
+
+  openButton.addEventListener("click", () => drawer.show());
+  closeButton.addEventListener("click", () => drawer.hide());
+</script>
+```
+
+---
+
+## Scrolling
+
+By design, a drawer’s height will never exceed 100% of its container. As such, drawers will not scroll with the page to ensure the header and footer are always accessible to the user.
+
+```html
+<syn-drawer label="Drawer" open="" placement="start" class="drawer-scrolling">
+  <div>
+    <p>Scroll down and give it a try! 👇</p>
+    <p>
+      Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
+      eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam
+      voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet
+      clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit
+      amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam
+      nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed
+      diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum.
+      Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor
+      sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed
+      diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam
+      erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea
+      rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum
+      dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr,
+      sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam
+      erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea
+      rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum
+      dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr,
+      sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam
+      erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea
+      rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum
+      dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr,
+      sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam
+      erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea
+      rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum
+      dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr,
+      sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam
+      erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea
+      rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum
+      dolor sit amet.
+    </p>
+  </div>
+  <syn-button slot="footer" variant="filled">Close</syn-button>
+</syn-drawer>
+
+<syn-button>Open Drawer</syn-button>
+
+<script type="module">
+  const drawer = document.querySelector(".drawer-scrolling");
+  const openButton = drawer.nextElementSibling;
+  const closeButton = drawer.querySelector('syn-button[variant="filled"]');
+
+  openButton.addEventListener("click", () => drawer.show());
+  closeButton.addEventListener("click", () => drawer.hide());
+</script>
+```
+
+---
+
+## Header Actions
+
+The header shows a functional close button by default. You can use the header-actions slot to add additional icon buttons if needed.
+
+```html
+<syn-drawer
+  label="Drawer"
+  open=""
+  placement="start"
+  class="drawer-header-actions"
+>
+  <syn-icon-button
+    class="new-window"
+    slot="header-actions"
+    name="open_in_new"
+    label="Arrow Up"
+  ></syn-icon-button>
+  Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+  <syn-button slot="footer" variant="filled">Close</syn-button>
+</syn-drawer>
+
+<syn-button>Open Drawer</syn-button>
+
+<script type="module">
+  const drawer = document.querySelector(".drawer-header-actions");
+  const openButton = drawer.nextElementSibling;
+  const closeButton = drawer.querySelector('syn-button[variant="filled"]');
+  const newWindowButton = drawer.querySelector(".new-window");
+
+  openButton.addEventListener("click", () => drawer.show());
+  closeButton.addEventListener("click", () => drawer.hide());
+  newWindowButton.addEventListener("click", () => window.open(location.href));
+</script>
+```
+
+---
+
+## Preventing The Drawer From Closing
+
+By default, drawers will close when the user clicks the close button, clicks the overlay, or presses the Escape key. In most cases, the default behavior is the best behavior in terms of UX. However, there are situations where this may be undesirable, such as when data loss will occur.To keep the drawer open in such cases, you can cancel the syn-request-close event. When canceled, the drawer will remain open and pulse briefly to draw the user’s attention to it.You can use event.detail.source to determine what triggered the request to close. This example prevents the drawer from closing when the overlay is clicked, but allows the close button or Escape to dismiss it.
+
+```html
+<syn-drawer label="Drawer" open="" class="drawer-deny-close">
+  This drawer will not close when you click on the overlay.
+  <syn-button slot="footer" variant="filled">Close</syn-button>
+</syn-drawer>
+
+<syn-button>Open Drawer</syn-button>
+
+<script type="module">
+  const drawer = document.querySelector(".drawer-deny-close");
+  const openButton = drawer.nextElementSibling;
+  const closeButton = drawer.querySelector('syn-button[variant="filled"]');
+
+  openButton.addEventListener("click", () => drawer.show());
+  closeButton.addEventListener("click", () => drawer.hide());
+
+  // Prevent the drawer from closing when the user clicks on the overlay
+  drawer.addEventListener("syn-request-close", (event) => {
+    if (event.detail.source === "overlay") {
+      event.preventDefault();
+    }
+  });
+</script>
+```
+
+---
+
+## Customizing Initial Focus
+
+By default, the drawer’s panel will gain focus when opened. This allows a subsequent tab press to focus on the first tabbable element in the drawer. If you want a different element to have focus, add the autofocus attribute to it as shown below.
+
+```html
+<syn-drawer label="Drawer" class="drawer-focus">
+  <syn-input
+    autofocus=""
+    placeholder="I will have focus when the drawer is opened"
+  ></syn-input>
+  <syn-button slot="footer" variant="filled">Close</syn-button>
+</syn-drawer>
+
+<syn-button>Open Drawer</syn-button>
+
+<script type="module">
+  const drawer = document.querySelector(".drawer-focus");
+  const input = drawer.querySelector("syn-input");
+  const openButton = drawer.nextElementSibling;
+  const closeButton = drawer.querySelector('syn-button[variant="filled"]');
+
+  openButton.addEventListener("click", () => drawer.show());
+  closeButton.addEventListener("click", () => drawer.hide());
+</script>
+```

package/data/layers/examples/component/component:syn-dropdown.md

@@ -0,0 +1,165 @@
+## Default
+
+Dropdowns expose additional content that “drops down” in a panel.Dropdowns consist of a trigger and a panel. By default, activating the trigger will expose the panel and interacting outside of the panel will close it.Dropdowns are designed to work well with menus to provide a list of options the user can select from. However, dropdowns can also be used in lower-level applications (e.g. color picker). The API gives you complete control over showing, hiding, and positioning the panel.
+
+```html
+<div style="position: relative">
+  <syn-dropdown>
+    <syn-button slot="trigger" caret="">Dropdown</syn-button>
+    <syn-menu style="min-width: 240px">
+      <syn-menu-item>Dropdown Item 1</syn-menu-item>
+      <syn-menu-item>Dropdown Item 2</syn-menu-item>
+      <syn-menu-item>Dropdown Item 3</syn-menu-item>
+      <syn-divider></syn-divider>
+      <syn-menu-item type="checkbox" checked="">Checkbox</syn-menu-item>
+      <syn-menu-item disabled="">Disabled</syn-menu-item>
+      <syn-divider></syn-divider>
+      <syn-menu-item>
+        Prefix
+        <syn-icon slot="prefix" name="wallpaper"></syn-icon>
+      </syn-menu-item>
+      <syn-menu-item>
+        Suffix Icon
+        <syn-icon slot="suffix" name="wallpaper"></syn-icon>
+      </syn-menu-item>
+    </syn-menu>
+  </syn-dropdown>
+</div>
+```
+
+---
+
+## Getting The Selected Item
+
+When dropdowns are used with menus, you can listen for the syn-select event to determine which menu item was selected. The menu item element will be exposed in event.detail.item. You can set value props to make it easier to identify commands. DEV: Alternatively, you can listen for the click event on individual menu items. Note that, using this approach, disabled menu items will still emit a click event.
+
+```html
+<div style="position: relative">
+  <div class="dropdown-selection">
+    <syn-dropdown>
+      <syn-button slot="trigger" caret="">Edit</syn-button>
+      <syn-menu style="min-width: 240px">
+        <syn-menu-item value="cut">Cut</syn-menu-item>
+        <syn-menu-item value="copy">Copy</syn-menu-item>
+        <syn-menu-item value="paste">Paste</syn-menu-item>
+      </syn-menu>
+    </syn-dropdown>
+  </div>
+</div>
+
+<script type="module">
+  const container = document.querySelector(".dropdown-selection");
+  const dropdown = container.querySelector("syn-dropdown");
+
+  dropdown.addEventListener("syn-select", (event) => {
+    const selectedItem = event.detail.item;
+    console.log(selectedItem.value);
+  });
+</script>
+```
+
+---
+
+## Placement
+
+The preferred placement of the dropdown can be set with the placement attribute. Note that the actual position may vary to ensure the panel remains in the viewport.
+
+```html
+<div style="position: relative">
+  <syn-dropdown placement="right-start">
+    <syn-button slot="trigger" caret="">Edit</syn-button>
+    <syn-menu style="min-width: 240px">
+      <syn-menu-item>Cut</syn-menu-item>
+      <syn-menu-item>Copy</syn-menu-item>
+      <syn-menu-item>Paste</syn-menu-item>
+      <syn-divider></syn-divider>
+      <syn-menu-item>Find</syn-menu-item>
+      <syn-menu-item>Replace</syn-menu-item>
+    </syn-menu>
+  </syn-dropdown>
+</div>
+```
+
+---
+
+## Distance
+
+The distance from the panel to the trigger can be customized using the distance attribute. This value is specified in pixels.
+
+```html
+<div style="position: relative">
+  <syn-dropdown distance="30">
+    <syn-button slot="trigger" caret="">Edit</syn-button>
+    <syn-menu style="min-width: 240px">
+      <syn-menu-item>Cut</syn-menu-item>
+      <syn-menu-item>Copy</syn-menu-item>
+      <syn-menu-item>Paste</syn-menu-item>
+      <syn-divider></syn-divider>
+      <syn-menu-item>Find</syn-menu-item>
+      <syn-menu-item>Replace</syn-menu-item>
+    </syn-menu>
+  </syn-dropdown>
+</div>
+```
+
+---
+
+## Skidding
+
+The offset of the panel along the trigger can be customized using the skidding attribute. This value is specified in pixels.
+
+```html
+<div style="position: relative">
+  <syn-dropdown skidding="30">
+    <syn-button slot="trigger" caret="">Edit</syn-button>
+    <syn-menu style="min-width: 240px">
+      <syn-menu-item>Cut</syn-menu-item>
+      <syn-menu-item>Copy</syn-menu-item>
+      <syn-menu-item>Paste</syn-menu-item>
+      <syn-divider></syn-divider>
+      <syn-menu-item>Find</syn-menu-item>
+      <syn-menu-item>Replace</syn-menu-item>
+    </syn-menu>
+  </syn-dropdown>
+</div>
+```
+
+---
+
+## Submenus
+
+To create a submenu, nest an <syn-menu slot="submenu"> element in a menu item.
+
+```html
+<div style="position: relative">
+  <syn-dropdown>
+    <syn-button slot="trigger" caret="">Edit</syn-button>
+
+    <syn-menu style="min-width: 240px">
+      <syn-menu-item value="undo">Undo</syn-menu-item>
+      <syn-menu-item value="redo">Redo</syn-menu-item>
+      <syn-divider></syn-divider>
+      <syn-menu-item value="cut">Cut</syn-menu-item>
+      <syn-menu-item value="copy">Copy</syn-menu-item>
+      <syn-menu-item value="paste">Paste</syn-menu-item>
+      <syn-divider></syn-divider>
+      <syn-menu-item>
+        Find
+        <syn-menu slot="submenu">
+          <syn-menu-item value="find">Find…</syn-menu-item>
+          <syn-menu-item value="find-previous">Find Next</syn-menu-item>
+          <syn-menu-item value="find-next">Find Previous</syn-menu-item>
+        </syn-menu>
+      </syn-menu-item>
+      <syn-menu-item>
+        Transformations
+        <syn-menu slot="submenu">
+          <syn-menu-item value="uppercase">Make uppercase</syn-menu-item>
+          <syn-menu-item value="lowercase">Make lowercase</syn-menu-item>
+          <syn-menu-item value="capitalize">Capitalize</syn-menu-item>
+        </syn-menu>
+      </syn-menu-item>
+    </syn-menu>
+  </syn-dropdown>
+</div>
+```

package/data/layers/examples/component/component:syn-file.md

@@ -0,0 +1,192 @@
+## Default
+
+File control is a component with which a user can select a local file. It shows the value of the selected file.
+
+```html
+<syn-file></syn-file>
+```
+
+---
+
+## Label
+
+Use the label attribute to give the file selector an accessible label. For labels that contain HTML, use the label slot instead.
+
+```html
+<syn-file label="This is a label"></syn-file>
+```
+
+---
+
+## Help Text
+
+Add descriptive help text to a switch with the help-text attribute. For help texts that contain HTML, use the help-text slot instead.The help-text attribute should not be used to display error messages. To handle validation and error messaging, use syn-validate for proper error management.
+
+```html
+<syn-file help-text="This is a help text." label="This is a label"></syn-file>
+```
+
+---
+
+## Multiple
+
+Use the multiple attribute to allow the selection of multiple files.Figma only: Override the button/droparea and value text directly, to indicate that multiple files are selected (“file” -> “files”)
+
+```html
+<syn-file label="Multiple file input" multiple=""></syn-file>
+```
+
+---
+
+## Hide Value
+
+There might be situations, where you don’t want to show the selected value (e. g. when something is automatically uploading).
+
+```html
+<syn-file hide-value="" label="This is a label"></syn-file>
+```
+
+---
+
+## Focus
+
+The focus event gives the user feedback that the Dropzone has been focused by the keyboard interaction and that the syn-file component is ready for use.
+
+```html
+<div style="padding: 5px">
+  <syn-file
+    label="This is a label"
+    help-text="This is a help text"
+    droparea=""
+  ></syn-file>
+</div>
+```
+
+---
+
+## Disabled
+
+Use the disabled attribute to disable a file input.
+
+```html
+<div style="display: flex; flex-direction: column; gap: 1rem">
+  <syn-file disabled="" label="This is a label"></syn-file>
+  <syn-file disabled="" droparea="" label="This is a label"></syn-file>
+</div>
+```
+
+---
+
+## Readonly
+
+Use the readonly attribute to set a file input to a readonly state.
+
+```html
+<div style="display: flex; flex-direction: column; gap: 1rem">
+  <syn-file readonly="" label="This is a label"></syn-file>
+  <syn-file readonly="" droparea="" label="This is a label"></syn-file>
+</div>
+```
+
+---
+
+## Sizes
+
+Use the size attribute to change the component's size.
+
+```html
+<div
+  style="display: flex; flex-direction: column; gap: var(--syn-spacing-large)"
+>
+  <syn-file size="small" label="Small"></syn-file>
+  <syn-file size="medium" label="Medium"></syn-file>
+  <syn-file size="large" label="Large"></syn-file>
+</div>
+```
+
+---
+
+## Invalid
+
+The invalid status is used to warn the user that the syn-file is invalid. For example, if the entry of text is mandatory and nothing has been entered or if a text has been entered that does not have the correct format.
+
+```html
+<form class="custom-validity">
+  <syn-file
+    class="syn-file-invalid"
+    droparea=""
+    help-text="This is an error text."
+    label="This is a label"
+  ></syn-file>
+  <syn-button type="submit" variant="filled">Submit</syn-button>
+</form>
+<script type="module">
+  const files = document.querySelectorAll(".syn-file-invalid");
+  files.forEach((file) => {
+    file.setCustomValidity("This is an error text");
+  });
+</script>
+<style>
+  .custom-validity {
+    display: flex;
+    flex-direction: column;
+    gap: 1rem;
+  }
+
+  syn-button {
+    align-self: flex-start;
+  }
+</style>
+```
+
+---
+
+## Droparea
+
+Use the droparea attribute to switch to a full-width button with a drop area.
+
+```html
+<div
+  style="display: flex; flex-direction: column; gap: var(--syn-spacing-large)"
+>
+  <syn-file
+    accept="text/plain,image/*"
+    droparea=""
+    help-text="This is a help text"
+    label="Small"
+    multiple=""
+    size="small"
+  ></syn-file>
+  <syn-file
+    accept="text/plain,image/*"
+    droparea=""
+    help-text="This is a help text"
+    label="Medium"
+    multiple=""
+    size="medium"
+  ></syn-file>
+  <syn-file
+    accept="text/plain,image/*"
+    droparea=""
+    help-text="This is a help text"
+    label="Large"
+    multiple=""
+    size="large"
+  ></syn-file>
+</div>
+```
+
+---
+
+## Directory
+
+The webkitdirectory setting allows users to select entire directories instead of individual files. When a directory is chosen, all files inside (including those in sub-directories) are selected. Although this feature is not part of the official HTML specification, it is widely supported across major browsers.
+
+```html
+<div
+  style="display: flex; flex-direction: column; gap: var(--syn-spacing-large)"
+>
+  <syn-file label="Button" webkitdirectory=""></syn-file>
+  <syn-file droparea="" label="Droparea" webkitdirectory=""></syn-file>
+</div>
+```