@synergy-design-system/react 2.17.0 → 2.18.1

package/README.md

@@ -7,6 +7,10 @@ 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.
+
 ## Getting started
 
 ### 1. Package installation
@@ -54,14 +58,63 @@ createRoot(document.getElementById("root")!).render(
 );
 ```
 
-### 3. Importing and rendering components
+### 3. 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 />
+);
+```
+
+#### 3.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.
+
+---
+
+### 4. 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 } from "@synergy-design-system/react";
+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 />
+);
 ```
 
 ### 4. Usage of the components

package/dist/chunks/{chunk.CYZ6F7G6.js → chunk.2JXRC7UA.js}

@@ -20,4 +20,4 @@ var SynSideNav = createComponent({
 export {
   SynSideNav
 };
-//# sourceMappingURL=chunk.CYZ6F7G6.js.map
+//# sourceMappingURL=chunk.2JXRC7UA.js.map

package/dist/chunks/{chunk.CYZ6F7G6.js.map → chunk.2JXRC7UA.js.map}

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/components/side-nav.ts"],
-  "sourcesContent": ["// ---------------------------------------------------------------------\n// \uD83D\uDD12 AUTOGENERATED @synergy-design-system/react wrappers for @synergy-design-system/components\n// Please do not edit this file directly!\n// It will get recreated when running pnpm build.\n// ---------------------------------------------------------------------\nimport * as React from 'react';\nimport { createComponent } from '@lit/react';\nimport Component from '@synergy-design-system/components/components/side-nav/side-nav.component.js';\n\nimport { type EventName } from '@lit/react';\nimport type { SynShowEvent } from '@synergy-design-system/components';\nimport type { SynAfterShowEvent } from '@synergy-design-system/components';\nimport type { SynHideEvent } from '@synergy-design-system/components';\nimport type { SynAfterHideEvent } from '@synergy-design-system/components';\n\nconst tagName = 'syn-side-nav';\nComponent.define('syn-side-nav');\n\n/**\n * @summary The <syn-side-nav /> element contains secondary navigation and fits below the header.\n * It can be used to group multiple navigation items (<syn-nav-item />s) together.\n *\n * @example\n * <syn-side-nav open>\n *  <syn-nav-item >Item 1</syn-nav-item>\n *  <syn-nav-item divider>Item 2</syn-nav-item>\n * </syn-side-nav>\n *\n * @documentation https://synergy-design-system.github.io/?path=/docs/components-syn-side-nav--docs\n * @status stable\n * @since 1.14.0\n *\n * @dependency syn-divider\n * @dependency syn-drawer\n *\n * @slot - The main content of the side-nav. Used for <syn-nav-item /> elements.\n * @slot footer - The footer content of the side-nav. Used for <syn-nav-item /> elements.\n *    Please avoid having to many nav-items as it can massively influence the user experience.\n *\n * @event syn-show - Emitted when the side-nav opens.\n * @event syn-after-show - Emitted after the side-nav opens and all animations are complete.\n * @event syn-hide - Emitted when the side-nav closes.\n * @event syn-after-hide - Emitted after the side-nav closes and all animations are complete.\n *\n * @csspart base - The components base wrapper\n * @csspart drawer - The drawer that is used under the hood for creating the side-nav\n * @csspart content-container - The components main content container\n * @csspart content - The components main content\n * @csspart footer-container - The components footer content container\n * @csspart footer-divider - The components footer divider\n * @csspart footer - The components footer content\n * @csspart overlay - The overlay that covers the screen behind the side-nav.\n *\n * @cssproperty  --side-nav-open-width - The width of the side-nav if in open state\n *\n * @animation sideNav.showNonRail - The animation to use when showing the side-nav in non-rail mode.\n * @animation sideNav.showRail - The animation to use when showing the side-nav in rail mode.\n * @animation sideNav.hideNonRail - The animation to use when hiding the side-nav in non-rail mode.\n * @animation sideNav.hideRail - The animation to use when hiding the side-nav in rail mode.\n * @animation sideNav.overlay.show - The animation to use when showing the side-nav's overlay.\n * @animation sideNav.overlay.hide - The animation to use when hiding the side-nav's overlay.\n */\nexport const SynSideNav = createComponent({\n  displayName: 'SynSideNav',\n  elementClass: Component,\n  events: {\n    onSynShow: 'syn-show' as EventName<SynShowEvent>,\n    onSynAfterShow: 'syn-after-show' as EventName<SynAfterShowEvent>,\n    onSynHide: 'syn-hide' as EventName<SynHideEvent>,\n    onSynAfterHide: 'syn-after-hide' as EventName<SynAfterHideEvent>,\n  },\n  react: React,\n  tagName,\n});\n\nexport type { SynShowEvent } from '@synergy-design-system/components';\nexport type { SynAfterShowEvent } from '@synergy-design-system/components';\nexport type { SynHideEvent } from '@synergy-design-system/components';\nexport type { SynAfterHideEvent } from '@synergy-design-system/components';\n"],
-  "mappings": ";AAKA,YAAY,WAAW;AACvB,SAAS,uBAAuB;AAChC,OAAO,eAAe;AAQtB,IAAM,UAAU;AAChB,UAAU,OAAO,cAAc;AA8CxB,IAAM,aAAa,gBAAgB;AAAA,EACxC,aAAa;AAAA,EACb,cAAc;AAAA,EACd,QAAQ;AAAA,IACN,WAAW;AAAA,IACX,gBAAgB;AAAA,IAChB,WAAW;AAAA,IACX,gBAAgB;AAAA,EAClB;AAAA,EACA,OAAO;AAAA,EACP;AACF,CAAC;",
+  "sourcesContent": ["// ---------------------------------------------------------------------\n// \uD83D\uDD12 AUTOGENERATED @synergy-design-system/react wrappers for @synergy-design-system/components\n// Please do not edit this file directly!\n// It will get recreated when running pnpm build.\n// ---------------------------------------------------------------------\nimport * as React from 'react';\nimport { createComponent } from '@lit/react';\nimport Component from '@synergy-design-system/components/components/side-nav/side-nav.component.js';\n\nimport { type EventName } from '@lit/react';\nimport type { SynShowEvent } from '@synergy-design-system/components';\nimport type { SynAfterShowEvent } from '@synergy-design-system/components';\nimport type { SynHideEvent } from '@synergy-design-system/components';\nimport type { SynAfterHideEvent } from '@synergy-design-system/components';\n\nconst tagName = 'syn-side-nav';\nComponent.define('syn-side-nav');\n\n/**\n * @summary The <syn-side-nav /> element contains secondary navigation and fits below the header.\n * It can be used to group multiple navigation items (<syn-nav-item />s) together.\n *\n * @example\n * <syn-side-nav open>\n *  <syn-nav-item >Item 1</syn-nav-item>\n *  <syn-nav-item divider>Item 2</syn-nav-item>\n * </syn-side-nav>\n *\n * @documentation https://synergy-design-system.github.io/?path=/docs/components-syn-side-nav--docs\n * @status stable\n * @since 1.14.0\n *\n * @dependency syn-divider\n * @dependency syn-drawer\n *\n * @slot - The main content of the side-nav. Used for <syn-nav-item /> elements.\n * @slot footer - The footer content of the side-nav. Used for <syn-nav-item /> elements.\n *    Please avoid having to many nav-items as it can massively influence the user experience.\n *\n * @event syn-show - Emitted when the side-nav opens.\n * @event syn-after-show - Emitted after the side-nav opens and all animations are complete.\n * @event syn-hide - Emitted when the side-nav closes.\n * @event syn-after-hide - Emitted after the side-nav closes and all animations are complete.\n *\n * @csspart base - The components base wrapper\n * @csspart drawer - The drawer that is used under the hood for creating the side-nav\n * @csspart content-container - The components main content container\n * @csspart content - The components main content\n * @csspart footer-container - The components footer content container\n  (where the footer slot content is rendered)\n * @csspart footer-divider - The components footer divider\n * @csspart footer - The components footer content\n * @csspart overlay - The overlay that covers the screen behind the side-nav.\n * @csspart panel - The side-nav's panel (where the whole content is rendered).\n * @csspart body - The side-nav's body (where the default slot content is rendered)\n * @csspart drawer__base - The drawer's base wrapper\n *\n * @cssproperty  --side-nav-open-width - The width of the side-nav if in open state\n *\n * @animation sideNav.showNonRail - The animation to use when showing the side-nav in non-rail mode.\n * @animation sideNav.showRail - The animation to use when showing the side-nav in rail mode.\n * @animation sideNav.hideNonRail - The animation to use when hiding the side-nav in non-rail mode.\n * @animation sideNav.hideRail - The animation to use when hiding the side-nav in rail mode.\n * @animation sideNav.overlay.show - The animation to use when showing the side-nav's overlay.\n * @animation sideNav.overlay.hide - The animation to use when hiding the side-nav's overlay.\n */\nexport const SynSideNav = createComponent({\n  displayName: 'SynSideNav',\n  elementClass: Component,\n  events: {\n    onSynShow: 'syn-show' as EventName<SynShowEvent>,\n    onSynAfterShow: 'syn-after-show' as EventName<SynAfterShowEvent>,\n    onSynHide: 'syn-hide' as EventName<SynHideEvent>,\n    onSynAfterHide: 'syn-after-hide' as EventName<SynAfterHideEvent>,\n  },\n  react: React,\n  tagName,\n});\n\nexport type { SynShowEvent } from '@synergy-design-system/components';\nexport type { SynAfterShowEvent } from '@synergy-design-system/components';\nexport type { SynHideEvent } from '@synergy-design-system/components';\nexport type { SynAfterHideEvent } from '@synergy-design-system/components';\n"],
+  "mappings": ";AAKA,YAAY,WAAW;AACvB,SAAS,uBAAuB;AAChC,OAAO,eAAe;AAQtB,IAAM,UAAU;AAChB,UAAU,OAAO,cAAc;AAkDxB,IAAM,aAAa,gBAAgB;AAAA,EACxC,aAAa;AAAA,EACb,cAAc;AAAA,EACd,QAAQ;AAAA,IACN,WAAW;AAAA,IACX,gBAAgB;AAAA,IAChB,WAAW;AAAA,IACX,gBAAgB;AAAA,EAClB;AAAA,EACA,OAAO;AAAA,EACP;AACF,CAAC;",
   "names": []
 }

package/dist/components/side-nav.d.ts

@@ -35,9 +35,13 @@ import type { SynAfterHideEvent } from '@synergy-design-system/components';
  * @csspart content-container - The components main content container
  * @csspart content - The components main content
  * @csspart footer-container - The components footer content container
+  (where the footer slot content is rendered)
  * @csspart footer-divider - The components footer divider
  * @csspart footer - The components footer content
  * @csspart overlay - The overlay that covers the screen behind the side-nav.
+ * @csspart panel - The side-nav's panel (where the whole content is rendered).
+ * @csspart body - The side-nav's body (where the default slot content is rendered)
+ * @csspart drawer__base - The drawer's base wrapper
  *
  * @cssproperty  --side-nav-open-width - The width of the side-nav if in open state
  *

package/dist/components/side-nav.js

@@ -1,6 +1,6 @@
 import {
   SynSideNav
-} from "../chunks/chunk.CYZ6F7G6.js";
+} from "../chunks/chunk.2JXRC7UA.js";
 export {
   SynSideNav
 };

package/dist/index.js

@@ -36,7 +36,7 @@ import {
 } from "./chunks/chunk.DDVND3A3.js";
 import {
   SynSideNav
-} from "./chunks/chunk.CYZ6F7G6.js";
+} from "./chunks/chunk.2JXRC7UA.js";
 import {
   SynSpinner
 } from "./chunks/chunk.YLB4QDAX.js";