@synergy-design-system/mcp 0.1.0 → 1.1.0

package/metadata/packages/react/README.md

@@ -0,0 +1,262 @@
+# @synergy-design-system/react
+
+This package provides [React.js](https://react.dev/) wrappers for [Synergy Web Components](https://github.com/synergy-design-system/synergy-design-system/tree/main/packages/components).
+
+This package aims for an improved UX when used in React applications:
+
+- Auto-completion
+- Event handling
+
+> Note that with react@19 and above, react has full support for web-components.
+> For those react versions, this package can be used by loading custom types,
+> you **do not need to use the exported components** anymore.
+
+## Known issues and limitations
+
+Got any problems using our React wrappers? Currently there are no known issues relating to them. But please take a look at [our list of known issues and limitations of the web components](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+), maybe you can find your problem there.
+
+## Getting started
+
+### 1. Usage example
+
+If you want to see a usage example, please check out our [test React repository](https://github.com/synergy-design-system/synergy-design-system/tree/main/packages/_private/react-demo).
+
+### 2. Package installation
+
+Run the following steps to install the required packages.
+
+```bash
+# Install the base library and required css files
+npm install --save @synergy-design-system/react @synergy-design-system/tokens
+
+# Optional: Install the styles utility package
+npm install --save @synergy-design-system/styles
+
+# Only if not already installed
+npm install --save react react-dom
+
+# Optional: if icons shall be used, install the assets package
+npm install --save @synergy-design-system/assets
+```
+
+> ⚠️ Note we do **not** ship React in this package.
+> You will have to install React by yourself first!
+
+### 3. Load the desired theme (required) and utility classes (recommended)
+
+The components will not display correctly without the needed theme and utility classes. Please include either light or dark theme in your application, for example in a newly installed React application:
+
+```tsx
+// main.tsx
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { App } from "./App";
+
+// Add this line to enable the light theme for your application
+import "@synergy-design-system/tokens/themes/light.css";
+import "@synergy-design-system/components/index.css";
+
+// Optional: Import the styles package
+import "@synergy-design-system/styles/index.css";
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);
+```
+
+### 4. Using native Synergy components in react (only for react >= 19.0.0) in Typescript projects
+
+React@19 finally shipped with official support for web components.
+With this version of react, you are free to **use our native web components** directly in your application.
+
+However, you will likely receive errors because our elements are not known to React as available (in react speech `intrinsic`) elements. This will also occur when using typescript. For this reason, we provide **type only wrappers** for all versions of react from version 19.0.0 onward.
+
+Using synergy in a typescript project with React@19 can be easily achieved via one line of code. There is no need to import `@synergy-design-system/react` in your code directly anymore!
+
+Just add the following definition to your projects typescript configuration file (e.g. `tsconfig.json`):
+
+```json
+{
+  "compilerOptions": {
+    "types": ["@synergy-design-system/react/types/latest"]
+  }
+}
+```
+
+This makes sure your project knows about our list of intrinsic elements. This will also enable **automatic type checks and auto completion for properties** for all synergy elements.
+
+You may now use the components by importing them from the `@synergy-design-system/component` package and rendering them in a React component.
+
+```tsx
+// You may also load the complete bundle somewhere in your application,
+// but directly including only needed components leads to smaller bundles.
+import "@synergy-design-system/components/components/button/button.js";
+import "@synergy-design-system/components/components/input/input.js";
+
+export const MyButton = () => <syn-button type="submit">Submit me</syn-button>;
+export const MyInput = () => (
+  <syn-input name="my-input" onsyn-change={e => console.log(e)} required />
+);
+```
+
+#### 4.1. Migrating from synergies react wrappers to native components
+
+1. First make sure you have react@19 or higher installed in your project.
+2. Upgrade `@synergy-design-system/react` to the latest version.
+3. Add the required types to your typescript configuration (`compilerOptions.types=['@synergy-design-system/react/types/latest']`).
+4. Run typescript to verify everything is still fine.
+5. Replace occurrences of the old synergy components with their native counterpart (e.g. `<SynButton>` should be exchanged for `<syn-button>`). When using native synergy components, make sure to double check on event names (e.g. `<SynInput onSynInput={e => null} />` will become `<syn-input onsyn-input={e => null} />`).
+6. When you are done, remove all occurrences of `@synergy-design-system/react` from your code.
+
+---
+
+### 5. Using the lit wrappers (required for react < 19.0.0, optional for react >= 19.0.0)
+
+You may now use the components by importing them from the `@synergy-design-system/react` package and rendering them in a React component.
+
+```tsx
+import { SynButton, SynInput } from "@synergy-design-system/react";
+
+export const MyButton = () => <SynButton type="submit">Submit me</SynButton>;
+export const MyInput = () => (
+  <SynInput name="my-input" onSynChange={e => console.log(e)} required />
+);
+```
+
+### 6. Usage of the components
+
+All information about which components exist as well as the available properties, events and usage of a component, can be found at `components` in our [documentation](https://synergy-design-system.github.io/?path=/docs/components).
+The documentation is written for no specific web framework but only vanilla html and javascript.
+
+An example demo repository with the usage of the React wrapper components can be found [here](https://github.com/synergy-design-system/synergy-design-system/tree/main/packages/_private/react-demo).
+
+The naming of the components for React changes from kebab-case to PascalCase.
+`syn-button` becomes `SynButton`:
+
+```html
+<!-- Webcomponents example -->
+<syn-button> My Button </syn-button>
+```
+
+```tsx
+// React wrapper example
+<SynButton> My Button </SynButton>
+```
+
+### 7. Usage of attributes
+
+The attribute namings of the components are the same as in the documentation.
+
+```html
+<!-- Webcomponents example -->
+<syn-input
+  label="Nickname"
+  help-text="What would you like people to call you?"
+  required
+></syn-input>
+```
+
+```tsx
+// React wrapper example
+<SynInput
+  label="Nickname"
+  help-text="What would you like people to call you?"
+  required
+/>
+```
+
+### 8. Usage of events
+
+Custom events are named in the documentation as following: `syn-change`, `syn-clear`, ...
+
+This library makes use of [@lit/react](https://lit.dev/docs/frameworks/react/) to wrap the existing Synergy Web Components.
+All events will be automatically set up to work without the need to attach event listeners manually.
+Just use them with the default React `onEVENT` prefix, where `EVENT` is the camelCased name of the event:
+
+`syn-change`-> `onSynChange`, `syn-clear`-> `onSynClear`, ...
+
+```tsx
+import { SynButton } from "@synergy-design-system/react";
+
+export const MyButton = () => (
+  <SynButton
+    onSynBlur={e => console.log("button blur event", e)}
+    onSynFocus={e => console.log("button focus event", e)}
+    onSynInvalid={e => console.log("button flagged as invalid", e)}
+  >
+    SynButton Example
+  </SynButton>
+);
+```
+
+If typescript is used, you can get the correct types for components and events from the `@synergy-design-system/components` package.
+
+The components from the React wrapper and the types of the components package are called the same. Therefore there must be a renaming of e.g. the types.
+
+An example for how these types can be used in case of event, is shown below:
+
+```tsx
+import { SynInput } from "@synergy-design-system/react";
+import type {
+  SynInput as SynInputType,
+  SynChangeEvent,
+} from "@synergy-design-system/components";
+
+export const MyComponent = () => (
+  <SynInput
+    label="Surname"
+    onSynChange={(e: SynChangeEvent) => {
+      const input = e.target as SynInputType;
+      // Now we get access to all properties, methods etc. of the syn-input
+      const surname = input.value;
+      doSomething(surname);
+    }}
+  />
+);
+```
+
+### 9. Usage of methods
+
+Components can have methods (like `focus`, `click`, `stepUp`, etc. ), which can trigger an action, if they are called.
+
+An example for calling such a method in a React component is shown here:
+
+```tsx
+import { SynButton, SynInput } from "@synergy-design-system/react";
+import type { SynInput as SynInputType } from "@synergy-design-system/components";
+import { type FC, useRef } from "react";
+
+export const Home: FC = () => {
+  const count = useRef<SynInputType>(null);
+
+  return (
+    <>
+      <SynInput ref={count} label="My count" type="number" value="5" />
+      <SynButton
+        onClick={() => {
+          // Increment the count via calling the method
+          count.current?.stepUp();
+        }}
+      >
+        Increment
+      </SynButton>
+    </>
+  );
+};
+```
+
+---
+
+## Development
+
+To create a new version of this package, proceed in the following way:
+
+1. Check out the [Synergy Design System Repository](https://github.com/synergy-design-system/synergy-design-system).
+2. Run `pnpm i -r` to install all dependencies.
+3. Build the `@synergy-design-system/components` package (or run `pnpm build` in the project root to build everything).
+4. Move to to `packages/_private/react-demo` and use `pnpm start` to spin up a local vite project using react and typescript to validate the build.
+
+> ⚠️ The build process will always try to sync this packages `package.json.version` field with the latest version from `@synergy-design-system/components`!
+> Therefore, it is best to not alter the version string

package/metadata/packages/styles/CHANGELOG.md

@@ -0,0 +1,76 @@
+# [@synergy-design-system/styles-v1.7.2](https://github.com/synergy-design-system/synergy-design-system/compare/styles/1.7.1...styles/1.7.2) (2025-06-20)
+
+
+### Bug Fixes
+
+* 🐛 Upgrade packages to latest versions ([#905](https://github.com/synergy-design-system/synergy-design-system/issues/905)) ([64de3cd](https://github.com/synergy-design-system/synergy-design-system/commit/64de3cd72f7ab3c7eeb727a9de85d9d980b27055))
+
+# [@synergy-design-system/styles-v1.7.1](https://github.com/synergy-design-system/synergy-design-system/compare/styles/1.7.0...styles/1.7.1) (2025-03-31)
+
+
+### Bug Fixes
+
+* 🐛  Upgrade packages to latest versions ([#830](https://github.com/synergy-design-system/synergy-design-system/issues/830)) ([f5fe54f](https://github.com/synergy-design-system/synergy-design-system/commit/f5fe54fb55732b1e3efdf3062d55ee517aef4e81))
+
+# [@synergy-design-system/styles-v1.7.0](https://github.com/synergy-design-system/synergy-design-system/compare/styles/1.6.0...styles/1.7.0) (2025-02-10)
+
+
+### Features
+
+* ✨Update shoelace and deps to latest version ([#769](https://github.com/synergy-design-system/synergy-design-system/issues/769)) ([143d88f](https://github.com/synergy-design-system/synergy-design-system/commit/143d88f0a50c47a996be0cb1527629802266800e))
+
+# [@synergy-design-system/styles-v1.6.0](https://github.com/synergy-design-system/synergy-design-system/compare/styles/1.5.0...styles/1.6.0) (2024-11-28)
+
+
+### Features
+
+* ✨ Update packages to latest versions ([#688](https://github.com/synergy-design-system/synergy-design-system/issues/688)) ([37fd055](https://github.com/synergy-design-system/synergy-design-system/commit/37fd055f0b4d067ea1afecb90a1bd1390de4d382))
+
+# [@synergy-design-system/styles-v1.5.0](https://github.com/synergy-design-system/synergy-design-system/compare/styles/1.4.0...styles/1.5.0) (2024-11-27)
+
+
+### Features
+
+* ✨ Create styles for a syn-link-list ([#678](https://github.com/synergy-design-system/synergy-design-system/issues/678)) ([ca3b99a](https://github.com/synergy-design-system/synergy-design-system/commit/ca3b99a828e2a078b538881f74324d0bee8fde66))
+
+# [@synergy-design-system/styles-v1.4.0](https://github.com/synergy-design-system/synergy-design-system/compare/styles/1.3.0...styles/1.4.0) (2024-10-11)
+
+
+### Features
+
+* ✨ Update Shoelace to 2.17.1 ([#641](https://github.com/synergy-design-system/synergy-design-system/issues/641)) ([86fd83b](https://github.com/synergy-design-system/synergy-design-system/commit/86fd83b528be24abc8dd8427604c7fd62e8c1ff2))
+
+# [@synergy-design-system/styles-v1.3.0](https://github.com/synergy-design-system/synergy-design-system/compare/styles/1.2.0...styles/1.3.0) (2024-08-26)
+
+
+### Features
+
+* ✨ link css ([#589](https://github.com/synergy-design-system/synergy-design-system/issues/589)) ([cdf54fc](https://github.com/synergy-design-system/synergy-design-system/commit/cdf54fcb348cc3b5a41993cff530424bdf6b6802))
+
+# [@synergy-design-system/styles-v1.2.0](https://github.com/synergy-design-system/synergy-design-system/compare/styles/1.1.0...styles/1.2.0) (2024-08-23)
+
+
+### Features
+
+* ✨ Upgrade packages to latest versions ([#592](https://github.com/synergy-design-system/synergy-design-system/issues/592)) ([e43c563](https://github.com/synergy-design-system/synergy-design-system/commit/e43c5630b6c43ef855af6815604c7649376104ee)), closes [#2078](https://github.com/synergy-design-system/synergy-design-system/issues/2078) [#2063](https://github.com/synergy-design-system/synergy-design-system/issues/2063) [#2041](https://github.com/synergy-design-system/synergy-design-system/issues/2041) [#2041](https://github.com/synergy-design-system/synergy-design-system/issues/2041) [#2116](https://github.com/synergy-design-system/synergy-design-system/issues/2116) [#2121](https://github.com/synergy-design-system/synergy-design-system/issues/2121) [#1992](https://github.com/synergy-design-system/synergy-design-system/issues/1992) [#2079](https://github.com/synergy-design-system/synergy-design-system/issues/2079) [#2009](https://github.com/synergy-design-system/synergy-design-system/issues/2009) [#1967](https://github.com/synergy-design-system/synergy-design-system/issues/1967) [#1947](https://github.com/synergy-design-system/synergy-design-system/issues/1947) [#1974](https://github.com/synergy-design-system/synergy-design-system/issues/1974) [#1985](https://github.com/synergy-design-system/synergy-design-system/issues/1985) [#2001](https://github.com/synergy-design-system/synergy-design-system/issues/2001)
+
+# [@synergy-design-system/styles-v1.1.0](https://github.com/synergy-design-system/synergy-design-system/compare/styles/1.0.1...styles/1.1.0) (2024-07-11)
+
+
+### Features
+
+* ✨ add table stylings ([#522](https://github.com/synergy-design-system/synergy-design-system/issues/522)) ([18a030b](https://github.com/synergy-design-system/synergy-design-system/commit/18a030be92344a9f0d038e5518c8347f0fbebb4e))
+
+# [@synergy-design-system/styles-v1.0.1](https://github.com/synergy-design-system/synergy-design-system/compare/styles/1.0.0...styles/1.0.1) (2024-07-08)
+
+
+### Bug Fixes
+
+* 🤔 Styles package uses fixed peerDependency for tokens ([#541](https://github.com/synergy-design-system/synergy-design-system/issues/541)) ([1877291](https://github.com/synergy-design-system/synergy-design-system/commit/1877291490806ff83fb1cca56d8b06a5a831f4e9))
+
+# @synergy-design-system/styles-v1.0.0 (2024-06-18)
+
+
+### Features
+
+* ✨ Styles Package ([#495](https://github.com/synergy-design-system/synergy-design-system/issues/495)) ([5e7b3dc](https://github.com/synergy-design-system/synergy-design-system/commit/5e7b3dc54bc9d94060fafc8119648e9e01bd07b7))

package/metadata/packages/styles/README.md

@@ -0,0 +1,132 @@
+# @synergy-design-system/styles
+
+This package provides easy to use standalone helper classes based on the [Synergy Design Tokens](https://synergy-design-system.github.io/?path=/docs/packages-tokens--docs).
+
+The included styles use CSS features supported by the latest two versions of all major browsers (as defined by browserslist) and is actively linted and tested against those targets.
+
+---
+
+## 1. Installation
+
+Please make sure to install the package as a dependency:
+
+```bash
+npm install --save @synergy-design-system/styles
+
+# Install the required design tokens
+# (only needed if you do not install peerDeps automatically)
+npm install --save @synergy-design-system/tokens
+```
+
+---
+
+## 2. Loading the provided stylesheets
+
+### 2.1 Loading all styles (Recommended)
+
+To load all provided css classes at once, just include the default export into your application.
+It contains all styles found in the `src` directory.
+
+```html
+<!DOCTYPE html>
+  <head>
+    <link rel="stylesheet" href="/node_modules/@synergy-design-system/styles/dist/index.css" />
+  </head>
+  <body>
+  </body>
+</html>
+```
+
+We also provide a default export that points to the created `dist/index.css` file.
+This will be picked up and served when using a bundler (e.g. webpack or vite).
+For this to work, import the module directly in your project like this.
+
+```javascript
+import "@synergy-design-system/styles";
+```
+
+---
+
+### 2.2 Loading single modules
+
+It is also possible to load only parts of the provided css files.
+
+> For a list of available modules, please have a look at the available modules section below.
+
+```html
+<!DOCTYPE html>
+  <head>
+    <!-- Loading typography only -->
+    <link rel="stylesheet" href="/node_modules/@synergy-design-system/styles/dist/typography.css" />
+  </head>
+  <body>
+  </body>
+</html>
+```
+
+```javascript
+// Loading typography only
+import "@synergy-design-system/styles/typography.css";
+```
+
+---
+
+## 3. Available modules
+
+<!-- BEGIN INLINE COMMENT -->
+
+- link-list.css
+- link.css
+- tables.css
+  - table-cell.css
+  - table.css
+- typography.css
+  - body.css
+  - heading.css
+  - weight.css
+
+<!-- END INLINE COMMENT -->
+
+---
+
+## Development
+
+### Building the styles
+
+This package makes use of `postcss` for creating a unified bundle for easier consumption in applications. Please run `pnpm build` in the root of this package to recreate the bundle file `dist/index.css`.
+
+### How it works
+
+1. The build will walk through the `src` directory and process all files named `index.css`. It automatically moves those files to the root `dist` directory, with the name of the folder it resides in. `src/typography/index.css` will automatically become `dist/typography.css`.
+2. All css files **not** named `index.css` will get copied over to the `dist` directory to make them available in the bundle. `src/typography/body.css` will get copied to `dist/typography/body.css`, however `dist/typography/index.css` will get renamed to `dist/typography.css` for easier inclusion.
+
+### Creating new modules
+
+1. Create a new folder `src/[MODULE_NAME]`.
+2. Create a new file `src/[MODULE_NAME]/index.css`.
+3. Add CSS statements to your liking. **Hint**: You may also split your code into multiple css files residing in the `src/[MODULE_NAME]` folder. Make sure to **import them into your `src/[MODULE_NAME]/index.css` file** to make them part of the build.
+4. Add js doc comments to your code to create controls for storybook automatically. This can be done by creating comments, as seen below.
+5. Run `pnpm build`. You should now see the a new file `dist/[MODULE_NAME].css` that holds all your previous code, as well as your created submodules (if you have splitted your code into multiple files).
+
+#### Bonus: Documenting your module with css comments
+
+When adding comments to your modules, please add a list of all variants of your module to your css file. Comments like this will take care that storybooks documentation is automatically updated:
+
+```css
+/**
+ * The "variant" syn-fieldset takes care that two classes will exist in documentation. The first variant value will be the selected one:
+ * - syn-fieldset-small and
+ * - syn-fieldset-large
+ * @variant {small | large } syn-fieldset
+ *
+ * The "variant" syn-shadow takes care that 4 classes will exist in documentation. There will be no default value selected via the NO_DEFAULT option:
+ * @variant { NO_DEFAULT | bottom | top | start | end } syn-shadow
+ *
+ * The "boolean" syn-boolean-false will display as a boolean value in storybook with 'false' as default value
+ * @variant syn-boolean-false This value will also be available as a class.
+ *
+ * The "boolean" syn-boolean-true will display as a boolean value in storybook with 'true' as default value
+ * @boolean { true } syn-boolean-true This value will also be available as a class.
+ * 
+ */
+```