@synergy-design-system/mcp 0.1.0 → 1.1.0

package/metadata/static/components/syn-validate/docs.md

@@ -0,0 +1,225 @@
+## Default
+
+Validate offers options for convenient error handling in form elements.
+
+```html
+<form id="components-syn-validate--default-validate-demo-form">
+  <syn-validate variant="native" on="">
+    <syn-input
+      label="Invalid input"
+      type="email"
+      value="team(at)synergy.com"
+      title=""
+      size="medium"
+      form=""
+    ></syn-input>
+  </syn-validate>
+
+  <p>
+    <syn-button type="submit" title="" variant="outline" size="medium"
+      >Submit</syn-button
+    >
+  </p>
+</form>
+```
+
+---
+
+## Inline Variant
+
+Set the variant attribute to inline to show the invalid message below the selected element.👨‍💻 Additional developer Information:Per default, syn-validate uses the browser’s built-in validation. This shows only one error at a time and is optimized for accessbility.When using the inline variant, you have to ensure accessibility on your side and have to have in mind it most likely will lead to layout shifts.
+
+```html
+<form id="components-syn-validate--inline-variant-validate-demo-form">
+  <syn-validate class="validation-inline" variant="inline" on="">
+    <syn-input
+      label="Inline Validation"
+      type="email"
+      value="team(at)synergy.com"
+      title=""
+      size="medium"
+      form=""
+    ></syn-input>
+  </syn-validate>
+
+  <p>
+    <syn-button type="submit" title="" variant="outline" size="medium"
+      >Submit</syn-button
+    >
+  </p>
+</form>
+```
+
+---
+
+## Hide Icon
+
+Use hide-icon to hide the icon in inline style. This is especially useful when showing more than one error at a time.
+
+```html
+<form id="components-syn-validate--hide-icon-validate-demo-form">
+  <syn-validate
+    class="validation-hide-icon"
+    hide-icon=""
+    variant="inline"
+    on=""
+  >
+    <syn-input
+      label="Inline Validation"
+      type="email"
+      value="team(at)synergy.com"
+      title=""
+      size="medium"
+      form=""
+    ></syn-input>
+  </syn-validate>
+
+  <p>
+    <syn-button type="submit" title="" variant="outline" size="medium"
+      >Submit</syn-button
+    >
+  </p>
+</form>
+```
+
+---
+
+## Live
+
+Use the live value for the on attribute to validate on every input change (e. g. typing a character or checking a checkbox.) instead of form submit. This will automatically bind to the input and blur events.👨‍💻 Additional developer Information:Please ensure, that you really need live validation for your use case as this can have implications on accessibility.
+
+```html
+<form id="components-syn-validate--live-validate-demo-form">
+  <syn-validate class="validation-live" variant="inline" on="live">
+    <syn-input
+      label="Invalid input"
+      type="email"
+      value="team(at)synergy.com"
+      title=""
+      size="medium"
+      form=""
+    ></syn-input>
+  </syn-validate>
+
+  <p>
+    <syn-button type="submit" title="" variant="outline" size="medium"
+      >Submit</syn-button
+    >
+  </p>
+</form>
+```
+
+---
+
+## Custom Validation Message
+
+Use the custom-validation-message attribute to use whichever error you need as text, overriding the default browser errors.👨‍💻 Additional developer Information:By using the custom-validation-message attribute, you can override the default browser error messages with custom text. However, please note that applying this attribute disables the browser’s native validation functionality. This means the standard error messages will not be displayed until the custom-validation attribute is removed, at which point the native functionality will be restored.
+
+```html
+<form
+  id="components-syn-validate--custom-validation-message-validate-demo-form"
+>
+  <syn-validate
+    class="validation-custom-validation"
+    custom-validation-message='Include an "@" in the email address, otherwise you will never get our marvelous newsletter'
+    variant="inline"
+    on=""
+  >
+    <syn-input
+      label="Custom validation"
+      type="email"
+      value="team(at)synergy.com"
+      title=""
+      size="medium"
+      form=""
+    ></syn-input>
+  </syn-validate>
+
+  <p>
+    <syn-button type="submit" title="" variant="outline" size="medium"
+      >Submit</syn-button
+    >
+  </p>
+</form>
+```
+
+---
+
+## Custom Form Field
+
+Wrap the element around any other form field, that follows browser standards to use all features.
+
+```html
+<form id="components-syn-validate--custom-form-field-validate-demo-form">
+  <h3 style="margin: 0; padding: 0">Choose SICK´s brand color</h3>
+  <syn-validate class="validation-custom-form-field" on="live" variant="inline">
+    <validate-demo-radio name="color"></validate-demo-radio>
+  </syn-validate>
+
+  <p>
+    <syn-button type="submit" title="" variant="outline" size="medium"
+      >Submit</syn-button
+    >
+  </p>
+</form>
+```
+
+---
+
+## Binding To Custom Event Names
+
+Use the on attribute to listen for one or many custom events. This may be useful if you want to validate on keypress or custom events that may be fired by third party web-components.👨‍💻 Additional developer Information:You can provide one or multiple events in the on property. Please use a whitespace separated list of DOM event names. <syn-validate> will make sure to automatically use Synergies custom events. This means <syn-validate on="change click"> will bind to the syn-change and click events for a <syn-input> or change and click events for a regular <input> element.
+
+```html
+<form
+  id="components-syn-validate--binding-to-custom-event-names-validate-demo-form"
+>
+  <syn-validate
+    class="validation-custom-validation"
+    on="mouseover blur"
+    variant="inline"
+  >
+    <syn-input
+      label="Custom validation (triggered on hover and blur)"
+      type="email"
+      value="team(at)synergy.com"
+      title=""
+      size="medium"
+      form=""
+    ></syn-input>
+  </syn-validate>
+
+  <p>
+    <syn-button type="submit" title="" variant="outline" size="medium"
+      >Submit</syn-button
+    >
+  </p>
+</form>
+```
+
+---
+
+## Eager
+
+Use the eager attribute to validate the field when the component is mounted. This may be used to prefill validation messages, e.g. during page loads. Please be aware that when mixed with a variant of native, this will display the error of the last eager element in your <form> only!
+
+```html
+<form id="components-syn-validate--eager-validate-demo-form">
+  <syn-validate eager="" variant="inline" on="">
+    <syn-input
+      label="Eager validation (triggered on page load)"
+      type="email"
+      value="team(at)synergy.com"
+      title=""
+      size="medium"
+      form=""
+    ></syn-input>
+  </syn-validate>
+
+  <p>
+    <syn-button type="submit" title="" variant="outline" size="medium"
+      >Submit</syn-button
+    >
+  </p>
+</form>
+```

package/metadata/static/migration/index.md

@@ -0,0 +1,16 @@
+# Rules for chatbots and llms
+
+As an llm, I want you to obey to the following rules:
+
+- The migration is available as a markdown document
+
+The following formatting rules are used for the list of breaking changes:
+
+- Each headline 2 (`##`) defines a major version of the new major release
+- Each headline 3 (`###`) describes a component or feature that was changed
+
+Migration from Synergy 2.0 to Synergy 3.0 (a.k.a. Brand Update):
+
+- There are handwritten lists of changes that highlight the differences between Synergy V2 and Synergy V3.
+- The document is structured as a list of breaking changes.
+- The list of breaking changes is structured into blocks that define the change and a list of migration steps.

package/metadata/static/react/index.md

@@ -0,0 +1,8 @@
+# Rules for chatbots and llms
+
+As an llm, I want you to obey to the following rules:
+
+- Always check which react version is used in the project.
+- If the project uses react 18, make sure to tell the user that react 19 has some serious advantages when it comes to using synergy.
+- If the project uses react 19, prefer to use the react 19 setup for synergy using native web-components and type only setups. Information about this can be obtained via the framework-info endpoint of this mcp server.
+- If the user still choses to use the synergy wrappers, tell him that they may get deprecated in the future as the native support is the way forward and highlight the advantages of having a type only setup again. Do this only once as we do not want to annoy our users.

package/metadata/static/setup/icon-usage.md

@@ -0,0 +1,276 @@
+Icons are small standard symbols that are primarily used in screen design.
+Due to their intended use, the icons must be recognizable min size of 16 x 16 pixels.
+
+> 👩‍💻 **Looking for a specific icon?**<br />
+> Use our [icon search](https://synergy-design-system.github.io/?path=/docs/icon-search--docs) to find a matching icon for your need!
+
+## Package installation
+
+In order for the `syn-icon` component to work, the `@synergy-design-system/assets` package has to be installed.
+
+Run the following command to install the required package.
+
+```bash
+# Install the assets library
+npm install --save @synergy-design-system/assets
+```
+
+## Libraries
+
+You can register additional icons to use with the <syn-icon> component through icon libraries.
+Icon files can exist locally or on a CORS-enabled endpoint (e.g. a CDN).
+There is no limit to how many icon libraries you can register and there is no cost associated with registering them, as individual icons are only requested when they're used.
+The default icon library contains all of the icons by Synergy Design System, which are based on the [Material Icons](https://fonts.google.com/icons).
+
+### How to use the Synergy Design System icons
+
+The default base path of the icon library is set to **assets/icons/**.
+To make the <syn-icon> work out of the box, without configuring anything, the used icons can be copied to this path in you application.
+This can either be done manually or with the help of the bundler.
+
+### Differences in icon usage between Synergy 2.0 and Synergy 3.0
+
+With the upgrade to Synergy 3.0, new icons will be used.
+Those icons are already available as assets in the \`@synergy-design-system/assets\` package.
+When using the new icons, you have to make sure that the icons are available in the \`assets/icons/\` directory of your project as outlined below.
+
+System icons come bundled with the \`@synergy-design-system/components\` package. You may switch to the new icons with the new \`setSystemIconLibrary\` utility provided.
+Please have a look at the following example to see how to switch the icon library.
+Note that if you do not call this function, it will default to the 2018 icon library, which is used in Synergy 2.0 until Synergy 3.0 is released.
+
+```javascript
+import { setSystemIconLibrary } from "@synergy-design-system/components";
+
+// Switch to the 2025 icon library
+setDefaultIconLibrary("sick2025");
+
+// Switch back to the 2018 icon library
+setDefaultIconLibrary("sick2018");
+
+// Switch to the default icon library (2018 for Synergy 2.0, 2025 for Synergy 3.0)
+setDefaultIconLibrary();
+```
+
+#### Angular + Webpack
+
+Including assets from another library can be achieved in angular via configuring the assets configuration in the angular.json file.
+For more information have a look at the [angular documentation](https://angular.io/guide/workspace-config#asset-config).
+
+Here's an example that copies the Synergy icons to the path **assets/icons/** of an angular project:
+
+```json
+"assets": [
+  {
+    "glob": "**/*",
+    "input": "./node_modules/@synergy-design-system/assets/src/icons",
+    "output": "/assets/icons"
+  }
+],
+```
+
+#### Vite
+
+Including assets from another library in vite project can be achieved via using the [vite-plugin-static-copy plugin](https://www.npmjs.com/package/vite-plugin-static-copy).
+Here's an example with adapted vite.config.ts that copies the Synergy icons to the path **assets/icons/** of a vite project:
+
+```js
+import { defineConfig } from "vite";
+import { viteStaticCopy } from "vite-plugin-static-copy";
+
+export default defineConfig({
+  plugins: [
+    viteStaticCopy({
+      targets: [
+        {
+          src: "node_modules/@synergy-design-system/assets/src/icons/*",
+          dest: "./assets/icons/",
+        },
+      ],
+    }),
+  ],
+});
+```
+
+### How to use a custom icon library
+
+To register an additional icon library, use the `registerIconLibrary()` function that's exported from `utilities/icon-library.js`.
+At a minimum, you must provide a name and a resolver function. The resolver function translates an icon name to a URL where the corresponding SVG file exists.
+Refer to the examples below to better understand how it works.
+
+If necessary, a mutator function can be used to mutate the SVG element before rendering. This is necessary for some libraries due to the many possible ways SVGs are crafted.
+For example, icons should ideally inherit the current text color via currentColor, so you may need to apply fill="currentColor" or stroke="currentColor" to the SVG element using this function.
+
+#### Custom icon library provided locally
+
+Here's an example that registers an icon library located in the /assets/icons directory.
+
+```html
+<script type="module">
+  import { registerIconLibrary } from "@synergy-design-system/components";
+
+  registerIconLibrary("my-icons", {
+    resolver: name => `/assets/icons/\${name}.svg`,
+    mutator: svg => svg.setAttribute("fill", "currentColor"),
+  });
+</script>
+```
+
+To display an icon, set the library and name attributes of an syn-icon element.
+
+```html
+<!-- This will show the icon located at /assets/icons/smile.svg -->
+<syn-icon library="my-icons" name="smile"></syn-icon>
+```
+
+## Referencing Assets
+
+Most of the magic behind assets is handled internally by Synergy, but if you need to reference the base path for any reason, there is an exported function called getBasePath(). An optional string argument can be passed, allowing you to get the full path to any asset.
+
+```html
+<script type="module">
+  import { getBasePath, setBasePath } from "@synergy-design-system/components";
+
+  setBasePath("/path/to/assets");
+
+  // ...
+
+  // Get the base path, e.g. /path/to/assets
+  const basePath = getBasePath();
+
+  // Get the path to an asset, e.g. /path/to/assets/file.ext
+  const assetPath = getBasePath("file.ext");
+</script>
+```
+
+---
+
+## Creating a custom spritesheet
+
+For performance reasons, it may be beneficial to create a spritesheet from multiple icons.
+This can be done in multiple ways:
+
+### 1. Using the `createSpriteSheet` function
+
+The `createSpriteSheet` function is provided by the `@synergy-design-system/assets` package.
+It takes an array of icon keys and returns a string representation of the SVG sprite sheet, intended to be saved into the file system.
+You may also provide an optional second argument to specify the icon set to use, either `sick2018` or `sick2025`. If not provided, it will default to `sick2018` for Synergy V2 and `sick2025` for Synergy V3.
+As we do not know how exactly you want to use the spritesheet, we will just print it to the console in the following example.
+
+```typescript
+import { createSpriteSheet } from "@synergy-design-system/assets";
+
+const icons = [
+  "warning",
+  "inventory",
+  "battery_charging_full",
+  "notifications",
+];
+
+// V2 iconsheet
+const sheet = createSpriteSheet(icons, "sick2018");
+
+// V3 iconsheet
+const sheet = createSpriteSheet(icons, "sick2025");
+
+// Automatically chooses the default, depending on the version of Synergy you are using
+const sheet = createSpriteSheet(icons);
+
+console.log(sheet);
+```
+
+### 2. Using the the `syn-create-spritesheet` command line utility
+
+```bash
+# Move to the root of your project
+cd my-project
+
+# Create the spritesheet on the command line.
+# You will need to provide a list of icons to include in the spritesheet.
+# Provide the wanted iconset with the --iconset flag.
+# The following command will make sure to save the spritesheet to the file icons.svg
+
+# Generates the icons from the 2025 iconset
+npx syn-create-spritesheet --icons=warning,inventory,battery_charging_full,notifications --iconset=sick2025 > public/icons.svg
+
+npx syn-create-spritesheet --icons=warning,inventory,battery_charging_full,notifications > public/icons.svg
+```
+
+### 3. Directly generating the spritesheet in vite
+
+The following example demonstrates how to generate a spritesheet directly in a vite project, running on every start of the development server.
+
+```typescript
+import fs from "node:fs";
+import { defineConfig } from "vite";
+import { createSpriteSheet } from "@synergy-design-system/assets";
+
+type SynSpriteSheetOptions = {
+  /**
+   * The output file name. Make sure the path exists
+   */
+  outFileName: string;
+
+  /**
+   * List of icons to include in the sprite sheet
+   */
+  icons: Parameters<typeof createSpriteSheet>[0];
+};
+
+const defaultOptions: SynSpriteSheetOptions = {
+  icons: [],
+  outFileName: "./public/synergy-icon-sprites.svg",
+};
+
+const synSpriteSheetCreator = (
+  options: Partial<SynSpriteSheetOptions> = {},
+) => ({
+  buildStart: () => {
+    const finalOptions = {
+      ...defaultOptions,
+      ...options,
+    };
+    const { icons, outFileName } = finalOptions;
+
+    const sheet = createSpriteSheet(icons);
+
+    // Create the output file
+    fs.writeFileSync(outFileName, sheet);
+  },
+  name: "syn-sprite-sheet-creator",
+});
+
+// https://vitejs.dev/config/
+export default defineConfig({
+  plugins: [
+    synSpriteSheetCreator({
+      icons: ["warning", "inventory", "battery_charging_full", "notifications"],
+    }),
+  ],
+  server: {
+    port: 5173,
+  },
+});
+```
+
+### 4. Creating sprites for angular usage
+
+In an angular project, you can use the following code to create a spritesheet.
+
+```typescript
+// Save this to a file called create-spritesheet.ts in your angular project
+import fs from "node:fs";
+import { createSpriteSheet } from "@synergy-design-system/assets";
+
+const icons = [
+  "warning",
+  "inventory",
+  "battery_charging_full",
+  "notifications",
+];
+const sheet = createSpriteSheet(icons);
+
+// Everything in the src/assets dir will be copied by angular per default.
+// Please refer to https://angular.io/guide/workspace-config#assets-configuration
+// for more information about how to configure this setting.
+fs.writeFileSync("src/assets/icons.svg", sheet);
+```

package/metadata/static/setup/prerequisites.md

@@ -0,0 +1,171 @@
+# Prerequisites
+
+## Fonts
+
+The Synergy Design System makes use of the `Open Sans` typeface.
+Because there are various ways of loading fonts, depending on used bundler, pre- and postprocessors and usage of a CDN, Synergy does **not provide** this font.
+You need to include it into your own project.
+
+The following information may be helpful to get you started including your own copy of `Open Sans` in your project for quicker bootstrapping:
+
+### Local Installation
+
+1. Download the `Open Sans` font from the [SICK Brand Portal](https://brand.sick.com/document/49#/-/resources-1).
+2. Extract the ZIP file to a destination reachable by your project (e.g. a `public` folder).
+3. Include the font in your project by adding the following CSS to your project (where `PUBLIC_PATH` is the path to the folder containing the font files).
+
+```css
+@font-face {
+  font-display: swap;
+  font-family: "Open Sans";
+  font-style: normal;
+  font-weight: 400;
+  src: url("/PUBLIC_PATH/Regular/OpenSans-Regular.woff2") format("woff2");
+}
+
+@font-face {
+  font-display: swap;
+  font-family: "Open Sans";
+  font-style: italic;
+  font-weight: 400;
+  src: url("/PUBLIC_PATH/Italic/OpenSans-Italic.woff2") format("woff2");
+}
+
+@font-face {
+  font-display: swap;
+  font-family: "Open Sans";
+  font-style: normal;
+  font-weight: 600;
+  src: url("/PUBLIC_PATH/SemiBold/OpenSans-SemiBold.woff2") format("woff2");
+}
+
+@font-face {
+  font-display: swap;
+  font-family: "Open Sans";
+  font-style: italic;
+  font-weight: 600;
+  src: url("/PUBLIC_PATH/SemiBoldItalic/OpenSans-SemiBoldItalic.woff2")
+    format("woff2");
+}
+
+@font-face {
+  font-display: swap;
+  font-family: "Open Sans";
+  font-style: normal;
+  font-weight: 700;
+  src: url("/PUBLIC_PATH/Bold/OpenSans-Bold.woff2") format("woff2");
+}
+
+@font-face {
+  font-display: swap;
+  font-family: "Open Sans";
+  font-style: italic;
+  font-weight: 700;
+  src: url("/PUBLIC_PATH/BoldItalic/OpenSans-BoldItalic.woff2") format("woff2");
+}
+```
+
+### Installing via local npm package (e.g. for vite or webpack based setups)
+
+1. Install the `@fontsource/open-sans` package into your project.
+2. Include the font in your project by adding the following import statements to your project:
+
+```js
+import "@fontsource/open-sans/400.css";
+import "@fontsource/open-sans/400-italic.css";
+import "@fontsource/open-sans/600.css";
+import "@fontsource/open-sans/600-italic.css";
+import "@fontsource/open-sans/700.css";
+import "@fontsource/open-sans/700-italic.css";
+```
+
+### Installing via local npm package (angular)
+
+1. Install the `@fontsource/open-sans` package into your project.
+2. Adjust your `angular.json` file to include the needed stylesheets (where project_name is the name of your project):
+
+```json
+{
+  "projects": {
+    "project_name": {
+      "architect": {
+        "build": {
+          "options": {
+            "styles": [
+              "@fontsource/open-sans/400.css",
+              "@fontsource/open-sans/400-italic.css",
+              "@fontsource/open-sans/600.css",
+              "@fontsource/open-sans/600-italic.css",
+              "@fontsource/open-sans/700.css",
+              "@fontsource/open-sans/700-italic.css"
+            ]
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Using the SICK CDN
+
+This is the simplest default font behavior. The `Open Sans` font is loaded from the SICK CDN.
+
+```css
+/* Regular */
+@font-face {
+  font-display: swap;
+  font-family: "Open Sans";
+  font-style: normal;
+  font-weight: 400;
+  src:
+    url("https://cdn.sick.com/media/fonts/opensans-v1/Regular/OpenSans-Regular.woff2")
+      format("woff2"),
+    url("https://cdn.sick.com/media/fonts/opensans-v1/Regular/OpenSans-Regular.woff")
+      format("woff"),
+    url("https://cdn.sick.com/media/fonts/opensans-v1/Regular/OpenSans-Regular.ttf")
+      format("truetype");
+}
+
+/* Semi Bold */
+@font-face {
+  font-display: swap;
+  font-family: "Open Sans";
+  font-style: normal;
+  font-weight: 600;
+  src:
+    url("https://cdn.sick.com/media/fonts/opensans-v1/SemiBold/OpenSans-SemiBold.woff2")
+      format("woff2"),
+    url("https://cdn.sick.com/media/fonts/opensans-v1/SemiBold/OpenSans-SemiBold.woff")
+      format("woff"),
+    url("https://cdn.sick.com/media/fonts/opensans-v1/SemiBold/OpenSans-SemiBold.ttf")
+      format("truetype");
+}
+
+/* Bold */
+@font-face {
+  font-display: swap;
+  font-family: "Open Sans";
+  font-style: normal;
+  font-weight: 700;
+  src:
+    url("https://cdn.sick.com/media/fonts/opensans-v1/Bold/OpenSans-Bold.woff2")
+      format("woff2"),
+    url("https://cdn.sick.com/media/fonts/opensans-v1/Bold/OpenSans-Bold.woff")
+      format("woff"),
+    url("https://cdn.sick.com/media/fonts/opensans-v1/Bold/OpenSans-Bold.ttf")
+      format("truetype");
+}
+```
+
+For better performance, you may also add the following statement to your HTML:
+
+```html
+<link
+  rel="preload"
+  href="https://cdn.sick.com/media/fonts/opensans-v1/Regular/OpenSans-Regular.woff2"
+  as="font"
+  type="font/woff2"
+  crossorigin
+/>
+```