@synergy-design-system/mcp 0.1.0 → 1.1.0

package/metadata/packages/components/static/LIMITATIONS.md

@@ -0,0 +1,269 @@
+# Known issues and limitations - Components
+
+This file lists known issues and limitations of Synergy Web Components and useful information with working on web-components.
+
+---
+
+## Layout issues with dynamic content in `<syn-button>`
+
+### Meta Information
+
+- Framework version: ALL
+- Synergy version: ALL
+- Issues: [#388](https://github.com/synergy-design-system/synergy-design-system/issues/388)
+
+### Description
+
+Synergies `<syn-button>` may get drawn without inner paddings when inserting content async.
+
+### Cause
+
+The `<syn-button>` element uses a [slotchange](https://github.com/synergy-design-system/synergy-design-system/blob/main/packages/components/src/components/button/button.component.ts#L202C17-L202C27) listener to dynamically apply classes that effect the layout of the component.
+
+As stated via [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLSlotElement/slotchange_event) `slotchange` events are fired when the **nodes** of a slot change. As most frameworks are reusing instances of `Text` nodes, those events will not trigger when the framework does not fully redraw the components content.
+
+### Proposed Solution
+
+Rendering is a crucial task of current frontend frameworks. Most frameworks will try to reuse created `Text` nodes. However, for most frameworks it is enough to wrap the slot contents with any `HTMLElement`.
+
+#### Problem
+
+```html
+<syn-button>DYNAMIC_TEXT</syn-button>
+```
+
+#### Solution
+
+```html
+<syn-button>
+  <span>DYNAMIC_TEXT</span>
+</syn-button>
+```
+
+---
+
+## `<syn-dialog>` closes itself when interacting with certain elements
+
+### Meta Information
+
+- Framework version: ALL
+- Synergy version: ALL
+- Issues: [#530](https://github.com/synergy-design-system/synergy-design-system/issues/530), [#572](https://github.com/synergy-design-system/synergy-design-system/issues/572), [sl#2020](https://github.com/shoelace-style/shoelace/issues/2020), [sl#1956](https://github.com/shoelace-style/shoelace/issues/1956)
+
+### Description
+
+A `<syn-dialog>` element may close itself unexpectedly when interacting with elements like `<syn-select>`, `<syn-accordion>` or `<syn-details>` and having a listener attached on the `syn-hide` event.
+
+### Cause
+
+Synergy uses shared `CustomEvents` for all of its components. Per default, all of those events are bubbling. When a `<syn-select>`, `<syn-accordion>` or `<syn-details>` element is closed, it fires its own `syn-hide` event. This event bubbles to `<syn-dialog>` and closes it.
+
+### Proposed Solution
+
+If you want to close the dialog only, listen to its `syn-request-close` event instead of `syn-hide`.
+In other cases, make sure to suppress the other elements emitted `syn-hide` events or filter the events target to just listen for the wanted instance of the `<syn-dialog>`.
+
+#### Problem
+
+```html
+<!-- Before -->
+<syn-dialog open>
+  <syn-details open summary="Example"></syn-details>
+</syn-dialog>
+
+<script type="module">
+  // This listener is also fired when the syn-details is closed!
+  document.querySelector("syn-dialog").addEventListener("syn-hide", e => {
+    const { target } = e;
+    target.close();
+  });
+</script>
+```
+
+#### Solution 1
+
+```html
+<syn-dialog open>
+  <syn-details open summary="Example"></syn-details>
+</syn-dialog>
+
+<script type="module">
+  // This listener will only work on syn-dialog!
+  document
+    .querySelector("syn-dialog")
+    .addEventListener("syn-request-close", e => {
+      const { target } = e;
+      target.close();
+    });
+</script>
+```
+
+#### Solution 2:
+
+```html
+<syn-dialog open>
+  <syn-details open summary="Example"></syn-details>
+</syn-dialog>
+
+<script type="module">
+  // This listener is not fired when the syn-details is closed!
+  document.querySelector("syn-dialog").addEventListener("syn-hide", e => {
+    const { target } = e;
+    if (target.tagName !== "SYN-DIALOG") {
+      return;
+    }
+    target.close();
+  });
+</script>
+```
+
+#### Solution 3:
+
+```html
+<syn-dialog open>
+  <syn-details open summary="Example"></syn-details>
+</syn-dialog>
+
+<script type="module">
+  // Suppress the bubbling of the syn-hide event of the details element
+  document.querySelector("syn-details").addEventListener("syn-hide", e => {
+    e.stopPropagation();
+  });
+
+  document.querySelector("syn-dialog").addEventListener("syn-hide", e => {
+    const { target } = e;
+    target.close();
+  });
+</script>
+```
+
+## Click events for `syn-nav-item` are not fired when clicking slotted items (e.g. icons)
+
+### Meta Information
+
+- Framework version: ALL
+- Synergy version: ALL
+- Issues: [#562](https://github.com/synergy-design-system/synergy-design-system/issues/530), [sl#2020](https://github.com/shoelace-style/shoelace/issues/562)
+
+### Description
+
+When adding a `click` listener to a `<syn-nav-item>` that has content in the `prefix` or `suffix` slot, the `event.target` is the slotted element instead of the instance of the `<syn-nav-item>`.
+
+### Cause
+
+Synergy components make heavy use of [ShadowDOM](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM). When using the ShadowDOM, all internal events will get [**retargeted** to the events instance](https://lit.dev/docs/components/events/#shadowdom-retargeting). However, slotted elements are still part of the LightDOM and are not part of this retargetting. Therefore, when clicking a slotted `<syn-icon>`, the `event.target` will reference the slotted `<syn-icon>`.
+
+### Proposed Solution
+
+Try to match on the next `<syn-nav-item>` with the closest selector. This will also match for slotted elements.
+
+#### Problem
+
+```html
+<syn-side-nav>
+  <syn-nav-item href="/">
+    Home
+    <syn-icon name="home" slot="prefix"></syn-icon>
+  </syn-nav-item>
+  <syn-side-nav>
+    <script type="module">
+      // This listener will only work when "Home" is clicked
+      // It will display a runtime error (unknown property "href") when the syn-icon is clicked
+      document.querySelector("syn-nav-item").addEventListener("click", e => {
+        const { target } = e;
+        document.location = target.ref;
+      });
+    </script></syn-side-nav
+  ></syn-side-nav
+>
+```
+
+#### Solution
+
+```html
+<script type="module">
+  // This listener will work when any part of the syn-button is clicked
+  document.querySelector("syn-side-nav").addEventListener("click", e => {
+    const { target } = e;
+    document.location = target.closest("syn-nav-item").ref;
+  });
+</script>
+```
+
+---
+
+## Wrong rendering order with container-type set on parent for `<syn-select>`, `<syn-combobox`, `<syn-dropdown>`, `<syn-tooltip>`
+
+### Meta Information
+
+- Framework version: ALL
+- Synergy version: ALL
+- Browsers: safari, older chrome and older firefox versions
+- Issues: [#612](https://github.com/synergy-design-system/synergy-design-system/issues/612)
+
+### Description
+
+Parts of Synergies `<syn-select>`, `<syn-combobox>`, `<syn-dropdown>`, `<syn-tooltip>` may get drawn behind other elements, if the `container-type` css property of a parent element is set to something different than `normal`.
+
+### Cause
+
+Older chrome and firefox browser versions as well as current safari browser have a special handling for container queries, which was declared as a "design mistake". For this reason the browsers are already having or getting an updated handling for this and also the specification should be updated in the future.
+The old handling was that `container-type: inline-size` or `container-type: size`:
+
+- created a containing block
+- created a new stacking context
+
+For further information have a look at [this article](https://dev.to/michaelcharles/chrome-129s-container-query-change-2i77)
+
+This old behavior results in e.g. open `<syn-select>` options list not being rendered above other elements (e.g. like `<syn-checkbox>`) but behind it.
+
+### Proposed Solution
+
+To work around this problem, add a `position: relative` and a `z-index` to the element with `container-type`.
+
+#### Problem
+
+```html
+<div class="container">
+  <syn-select>
+    <syn-option value="opt1">Option 1</syn-option>
+    <syn-option value="opt2">Option 2</syn-option>
+    <syn-option value="opt3">Option 3</syn-option>
+  </syn-select>
+</div>
+
+<syn-checkbox>This is a checkbox</syn-checkbox>
+
+<style>
+  .container {
+    container-type: inline-size;
+    margin-bottom: 30px;
+  }
+</style>
+```
+
+#### Solution
+
+```html
+<div class="container">
+  <syn-select>
+    <syn-option value="opt1">Option 1</syn-option>
+    <syn-option value="opt2">Option 2</syn-option>
+    <syn-option value="opt3">Option 3</syn-option>
+  </syn-select>
+</div>
+
+<syn-checkbox>This is a checkbox</syn-checkbox>
+
+<style>
+  .container {
+    container-type: inline-size;
+    margin-bottom: 30px;
+
+    position: relative;
+    z-index: 1;
+  }
+</style>
+```
+
+---

package/metadata/packages/components/static/README.md

@@ -0,0 +1,248 @@
+# @synergy-design-system/components
+
+This package provides the base of the Synergy Design System as native web components.
+It uses [lit](https://www.lit.dev) and parts of [shoelace](https://shoelace.style/). Synergy officially supports the latest two versions of all major browsers (as defined by browserslist) and is actively linted and integration tested against those targets.
+
+## Known issues and limitations
+
+Got any problems using our components? Please take a look at [our list of known issues and limitations](https://synergy-design-system.github.io/?path=/docs/limitations-known-issues-and-limitations--docs) before [creating a ticket](https://github.com/synergy-design-system/synergy-design-system/issues/new?assignees=&labels=&projects=&template=generic-bug.md&title=fix%3A+%F0%9F%90%9B+).
+
+## Getting started
+
+### 1. Usage example
+
+If you want to see a usage example, please check out our [test Web Components repository](https://github.com/synergy-design-system/synergy-design-system/tree/main/packages/_private/vanilla-demo).
+
+### 2. Package installation
+
+Run the following steps to install the required packages.
+
+```bash
+# Install the base library
+npm install --save @synergy-design-system/components
+
+# Install the required design tokens
+# (only needed if you do not install peerDeps automatically)
+npm install --save @synergy-design-system/tokens
+
+# Optional: Install the styles utility package
+npm install --save @synergy-design-system/styles
+
+# Optional: if icons shall be used, install the assets package
+npm install --save @synergy-design-system/assets
+```
+
+---
+
+### 3. Load the desired theme (required) and utility classes (recommended)
+
+The shipped components make heavy use of design tokens, which are provided via [@synergy-design-system/tokens](https://github.com/synergy-design-system/synergy-design-system/tree/main/packages/tokens). Make sure to follow the installation steps there for help on setting the tokens up. Usually it is enough to load the light or dark theme included there.
+
+This package also comes with css utilities that are required to make synergy work.
+You may either load all of them in one bundle (recommended) or just include the bits that you need.
+
+> When loading custom bits, please make sure to always include `dist/styles/utility.css`!
+> Without these utilities, fullscreen components **will** not work as intended!
+
+##### List of available css utilities
+
+| Utility | Required? | Path                      | Description                                                                                                                                                                                                                                                   |
+| :------ | :-------: | :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| fouc    |           | `dist/styles/fouc.css`    | Defaults for handling [Flash of Undefined Components (FOUC)](https://www.abeautifulsite.net/posts/flash-of-undefined-custom-elements/). Scoped to only target Synergy Components to make sure it does not overlap with other custom elements already defined. |
+| utility |    ✔     | `dist/styles/utility.css` | Utilities that have to be in the light DOM to make Synergy work. For example, these include scroll locking for fullscreen components. **This is required, your application layout may break if not available**!                                               |
+
+##### 2.1. Loading all css utilities (recommended)
+
+```html
+<!-- Example 1: Loading all utility functions -->
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link
+      rel="stylesheet"
+      src="../node_modules/@synergy-design-system/components/dist/styles/index.css"
+    />
+  </head>
+  <body></body>
+</html>
+```
+
+##### 2.2. Load only parts of the utilities
+
+```html
+<!-- Example 2: Loading only the required utility functions -->
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link
+      rel="stylesheet"
+      src="../node_modules/@synergy-design-system/components/dist/styles/utility.css"
+    />
+  </head>
+  <body></body>
+</html>
+```
+
+---
+
+### 4. Importing and rendering components
+
+There are multiple ways to load the components:
+
+#### Loading all available components
+
+To make all components available, just load the main package file. It will make sure that all components and needed dependencies are loaded and available directly.
+
+> Please keep in mind that this way of loading the components will create larger bundle sizes!
+
+```html
+<!-- Example 1: Loading via script type module -->
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+  </head>
+  <body>
+    <div id="root">
+      <syn-button variant="text">Button</syn-button>
+      <syn-input></syn-input>
+    </div>
+    <!-- As we are loading all modules, syn-button and syn-input will render correctly -->
+    <script
+      type="module"
+      src="../node_modules/@synergy-design-system/components/dist/synergy.js"
+    ></script>
+  </body>
+</html>
+```
+
+When using a build system, you should load the bundle in JavaScript or TypeScript directly, for example when using vite:
+
+```typescript
+// main.ts
+
+// Do not forget to load the design tokens!
+import "@synergy-design-system/tokens/themes/light.css";
+
+// Add the css utility functions.
+import "@synergy-design-system/components/index.css";
+
+// This will load synergy.js via the exports map
+import "@synergy-design-system/components";
+```
+
+#### Loading selected components only
+
+Use this when you need complete control about which components are loaded. This will usually lead to smaller bundle sizes, which might be preferable for your application. As a downside, you will have to remember adding missing components to your bundle.
+
+```html
+<!-- Example 1: Loading via script type module -->
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+  </head>
+  <body>
+    <div id="root">
+      <syn-button variant="text">Button</syn-button>
+      <syn-input></syn-input>
+    </div>
+    <!-- We are only loading the button, syn-input will render as an empty div! -->
+    <script
+      type="module"
+      src="../node_modules/@synergy-design-system/components/dist/components/button/button.js"
+    ></script>
+  </body>
+</html>
+```
+
+When using a build system, you may also load the bundle in JavaScript or TypeScript directly, for example when using vite:
+
+```typescript
+// main.ts
+
+// Do not forget to load the design tokens!
+import "@synergy-design-system/tokens/themes/light.css";
+
+// Add the css utility functions.
+import "@synergy-design-system/components/index.css";
+
+// This will only load and define the button itself
+import "@synergy-design-system/components/components/button/button.js";
+```
+
+---
+
+### 5. Using the provided types
+
+The components are built using typescript and provide types for elements and events out of the box. These can be used for working with the dom when working in a typescript environment. You may use them by importing the needed types and using them for elements, like shown in this example:
+
+```typescript
+// main.ts
+
+// Do not forget to load the design tokens!
+import "@synergy-design-system/tokens/themes/light.css";
+
+// Example 1: Load the type for syn-button from the root:
+import type {
+  SynButton,
+  SynInvalidEvent,
+} from "@synergy-design-system/components";
+
+// Example 2: Load the type from the syn-button dir directly.
+// In this case you will have to load the event type from another file!
+import type { SynButton } from "@synergy-design-system/components/components/button/button.component";
+import type { SynInvalidEvent } from "@synergy-design-system/components/events/events";
+
+document.addEventListener("load", () => {
+  const loadedSynButtons = document.querySelectorAll<SynButton>("syn-button");
+
+  // Attach a syn-invalid event that is fired every time a button becomes invalid
+  Array.from(loadedSynButtons) // Type: SynButton[]
+    .addEventListener("syn-invalid", (e: SynInvalidEvent) => {
+      console.log("Button is now invalid!", e);
+    });
+});
+```
+
+---
+
+### 6. Add html autocompletion to VSCode (optional)
+
+This package ships with a [custom-elements-manifest](https://github.com/webcomponents/custom-elements-manifest) that may be used to provide typings for tags. To enable code completion, please proceed the following way:
+
+1. Install the `@synergy-design-system/components` package.
+2. If you do **not** have a `.vscode/settings.json` file yet, create it.
+3. Add support for [vscode-custom-data](https://github.com/microsoft/vscode-custom-data) by adding the following setting to your `.vscode/settings.json`: `"html.customData": ["./node_modules/@synergy-design-system/components/dist/vscode.html-custom-data.json"]`
+4. Restart VSCode.
+5. Switch to an html (or similar) file and type `<syn`. Auto-complete now provides a list of available components along with its attributes.
+
+> Note the path above is valid for installations using npm.
+> When using another package manager, make sure to set the proper path to `vscode.html-custom-data.json`!
+
+---
+
+### 7. Breaking changes between major versions
+
+Please have a look at the official [breaking changes list](https://synergy-design-system.github.io/?path=/docs/packages-components-breaking-changes--docs) for information how to update to new major versions of Synergy.
+
+---
+
+## Local setup
+
+### Using the vendor cli
+
+The vendor cli is taking care about updating our code base according to a new version of shoelace.
+
+To change the shoelace version, that should be downloaded, change the version in the config of `./scripts/vendorism.js`.
+To download it use the command `pnpm vendor.get`.
+If code in our components library should be updated to this new shoelace version use `pnpm vendor.set`.
+
+All shoelace files are per default readonly and are disabled from being changed. To change this files can be ejected. This can be done via:
+`pnpm vendor.eject "src/declaration.d.ts"`.
+
+### Adding events to the output
+
+To add events to the component output, make sure to add them to `src/scripts/vendorism.js` into the `events` array that is defined there. After a new build run `via pnpm build`, you will see the new event files and the `events/events.ts` file will be regenerated.

package/metadata/packages/react/LIMITATIONS.md

@@ -0,0 +1,31 @@
+# Known Issues and limitations - React
+
+> ⚠️ This file includes all known issues and limitations when using the react wrappers.
+> There may be other interesting bits of information in the [components limitation documentation](https://synergy-design-system.github.io/?path=/docs/limitations-components--docs).
+
+## Why is there a react wrapper package in the first place?
+
+### Meta information
+
+- Framework version: React < 19.0.0
+- Synergy version: < 2.16.0
+
+### Description
+
+React did historically not ship with web components in mind. This means that is not possible to use all features of web components out of the box when using React until version 19.0.0.
+
+### Cause
+
+Unfortunately it seems that web components never got traction for react developers in the first place, so they where ignored for a long time.
+
+### Proposed Solution
+
+#### Solution 1: For react < 19.0.0
+
+When using react version 18 and below, you may use our `@synergy-design-system/react` wrapper components.
+They allow seamless use of our components as automatically wrapped react elements.
+
+#### Solution 2: For react >= 19.0.0
+
+React 19 comes with official support for web components. This means you are able to use synergies web components directly in React applications now.
+We support this by providing a custom typescript module that may be installed in your react project that provides typechecking and autocompletion support for the native components in react. Please see `@synergy-design-system/react` installation instructions for using this.