@synergy-design-system/metadata 1.0.0 → 3.0.1

package/data/layers/full/setup/setup:react-package/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/data/layers/full/setup/setup:react-package/react/index.ts

@@ -0,0 +1,53 @@
+// ---------------------------------------------------------------------
+// 🔒 AUTOGENERATED @synergy-design-system/react wrappers for @synergy-design-system/components
+// Please do not edit this file directly!
+// It will get recreated when running pnpm build.
+// ---------------------------------------------------------------------
+export { SynAccordion } from './components/accordion.js';
+export { SynAlert } from './components/alert.js';
+export { SynBadge } from './components/badge.js';
+export { SynBreadcrumb } from './components/breadcrumb.js';
+export { SynBreadcrumbItem } from './components/breadcrumb-item.js';
+export { SynButton } from './components/button.js';
+export { SynButtonGroup } from './components/button-group.js';
+export { SynCard } from './components/card.js';
+export { SynCheckbox } from './components/checkbox.js';
+export { SynCombobox } from './components/combobox.js';
+export { SynDetails } from './components/details.js';
+export { SynDialog } from './components/dialog.js';
+export { SynDivider } from './components/divider.js';
+export { SynDrawer } from './components/drawer.js';
+export { SynDropdown } from './components/dropdown.js';
+export { SynFile } from './components/file.js';
+export { SynHeader } from './components/header.js';
+export { SynIcon } from './components/icon.js';
+export { SynIconButton } from './components/icon-button.js';
+export { SynInput } from './components/input.js';
+export { SynMenu } from './components/menu.js';
+export { SynMenuItem } from './components/menu-item.js';
+export { SynMenuLabel } from './components/menu-label.js';
+export { SynNavItem } from './components/nav-item.js';
+export { SynOptgroup } from './components/optgroup.js';
+export { SynOption } from './components/option.js';
+export { SynPagination } from './components/pagination.js';
+export { SynPopup } from './components/popup.js';
+export { SynPrioNav } from './components/prio-nav.js';
+export { SynProgressBar } from './components/progress-bar.js';
+export { SynProgressRing } from './components/progress-ring.js';
+export { SynRadio } from './components/radio.js';
+export { SynRadioButton } from './components/radio-button.js';
+export { SynRadioGroup } from './components/radio-group.js';
+export { SynRange } from './components/range.js';
+export { SynRangeTick } from './components/range-tick.js';
+export { SynSelect } from './components/select.js';
+export { SynSideNav } from './components/side-nav.js';
+export { SynSpinner } from './components/spinner.js';
+export { SynSwitch } from './components/switch.js';
+export { SynTab } from './components/tab.js';
+export { SynTabGroup } from './components/tab-group.js';
+export { SynTabPanel } from './components/tab-panel.js';
+export { SynTag } from './components/tag.js';
+export { SynTagGroup } from './components/tag-group.js';
+export { SynTextarea } from './components/textarea.js';
+export { SynTooltip } from './components/tooltip.js';
+export { SynValidate } from './components/validate.js';

package/data/layers/full/setup/setup:react-package/react/package.json

@@ -0,0 +1,54 @@
+{
+  "author": {
+    "name": "SICK Global UX Foundation",
+    "url": "https://www.sick.com"
+  },
+  "dependencies": {
+    "@lit/react": "^1.0.8",
+    "@synergy-design-system/components": "workspace:*"
+  },
+  "description": "React wrappers for the Synergy Design System",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./components/*": "./dist/components/*",
+    "./types/latest": {
+      "types": "./dist/types/syn-jsx-elements.d.ts"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "README.md"
+  ],
+  "homepage": "https://synergy-design-system.github.io",
+  "keywords": [
+    "React Web Component Wrapper",
+    "React Components",
+    "React Design System",
+    "Design System",
+    "SDS",
+    "Synergy Design System",
+    "SICK",
+    "SICK Design System"
+  ],
+  "license": "MIT",
+  "name": "@synergy-design-system/react",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/synergy-design-system/synergy-design-system.git",
+    "directory": "packages/react"
+  },
+  "type": "module",
+  "version": "3.12.1",
+  "devDependencies": {
+    "@types/react": "^19.2.14",
+    "react": "^19.2.5"
+  },
+  "peerDependencies": {
+    "@synergy-design-system/tokens": "workspace:*"
+  }
+}