@synergy-design-system/react 1.16.0 → 1.17.0

package/README.md

@@ -19,14 +19,17 @@ npm install --save @synergy-design-system/react @synergy-design-system/tokens
 
 # 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.
+> ⚠️ Note we do **not** ship React in this package.
 > You will have to install React by yourself first!
 
-### 2. Add the wanted theme to your application
+### 2. Add the desired theme to your application
 
-The components will not display correctly without the needed theme. Please include either light or dark theme in your application, for example in a newly installed vite React application:
+The components will not display correctly without the needed theme. Please include either light or dark theme in your application, for example in a newly installed React application:
 
 ```tsx
 // main.tsx
@@ -46,23 +49,65 @@ createRoot(document.getElementById("root")!).render(
 
 ### 3. Importing and rendering components
 
-You may now use the components by importing them from the `@synergy-design-system/react` package and rendering them in a react component.
+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 } from "@synergy-design-system/react";
 
-export const MyButton = () => (
-  <SynButton type="button" variant="filled">
-    SynButton Example
-  </SynButton>
-);
+export const MyButton = () => <SynButton type="submit">Submit me</SynButton>;
+```
+
+### 4. 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>
+```
+
+### 5. 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>
 ```
 
-## 4. Using component events
+```tsx
+// React wrapper example
+<SynInput
+  label="Nickname"
+  help-text="What would you like people to call you?"
+  required
+/>
+```
+
+### 6. 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.
+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";
@@ -78,6 +123,62 @@ export const MyButton = () => (
 );
 ```
 
+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);
+    }}
+  />
+);
+```
+
+### 7. 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

package/package.json

@@ -5,7 +5,7 @@
   },
   "dependencies": {
     "@lit/react": "^1.0.3",
-    "@synergy-design-system/components": "^1.16.0"
+    "@synergy-design-system/components": "^1.17.0"
   },
   "description": "React wrappers for the Synergy Design System",
   "exports": {
@@ -40,7 +40,7 @@
     "directory": "packages/react"
   },
   "type": "module",
-  "version": "1.16.0",
+  "version": "1.17.0",
   "devDependencies": {
     "@types/react": "^18.2.55",
     "react": "^18.2.0"