From eabfed2b2177462191dd14cf3a7f053862febe24 Mon Sep 17 00:00:00 2001
From: bruno-sch <163294364+bruno-sch@users.noreply.github.com>
Date: Wed, 10 Apr 2024 08:28:54 +0200
Subject: [PATCH] Docs mention routers for frameworks (#2378)

* docs: usage of router links for frameworks

* fix: route is defined in the wrong place
---
 packages/components/docs/router-usage.md      | 53 +++++++++++++++++++
 showcases/patternhub/.gitignore               |  1 +
 showcases/patternhub/data/routes.ts           |  1 +
 .../pages/components/router-usage/index.mdx   |  6 +++
 4 files changed, 61 insertions(+)
 create mode 100644 packages/components/docs/router-usage.md
 create mode 100644 showcases/patternhub/pages/components/router-usage/index.mdx

diff --git a/packages/components/docs/router-usage.md b/packages/components/docs/router-usage.md
new file mode 100644
index 00000000000..f72c41370f3
--- /dev/null
+++ b/packages/components/docs/router-usage.md
@@ -0,0 +1,53 @@
+# Router usage
+
+> **Note:** At the moment, router links can only be used within the **DBNavigationItem** component!
+
+Unfortunately, the **DBLink** and **DBButton** components do not support router links. Explanation: Router links are usually rendered as anchor tags, which are not permitted within anchor or button tags.
+
+## Supported routers
+
+The following standard routers have been successfully implemented in the corresponding frameworks (Angular, React, Vue). Other routers should work in the same way, but have not yet been tested.
+
+-   [Angular router](https://angular.io/api/router)
+-   [React router](https://reactrouter.com/en/main)
+-   [Vue router](https://v3.router.vuejs.org/)
+
+The routers are installed and used in accordance with the official docs:
+
+## How to use
+
+To create a DB Brand styled router link, place the corresponding router link component in the default slot of **DBNavigationItem**.
+
+[How to use DBNavigationItem](https://db-ui.github.io/mono/review/main/components/navigation-item/overview)
+
+**Angular**
+
+`RouterLink` must be imported from the `@angular/router` package.
+
+```html
+<db-navigation-item>
+	<a [routerLink]="link.path"> {{ link.label }} </a>
+</db-navigation-item>
+```
+
+**React**
+
+`Link` must be imported from the `react-router-dom` package.
+
+```html
+<DBNavigationItem>
+	<Link to={link.path}>
+		{link.label}
+	</Link>
+</DBNavigationItem>
+```
+
+**Vue**
+
+`RouterLink` can be used directly, as it is available globally.
+
+```html
+<DBNavigationItem>
+	<RouterLink :to="link.path"> {{ link.label }} </RouterLink>
+</DBNavigationItem>
+```
diff --git a/showcases/patternhub/.gitignore b/showcases/patternhub/.gitignore
index 977ebb8bae5..45430e702e5 100644
--- a/showcases/patternhub/.gitignore
+++ b/showcases/patternhub/.gitignore
@@ -41,6 +41,7 @@ scripts/generated
 pages/components/
 components/src
 !pages/components/readme.mdx
+!pages/components/router-usage
 !components/src/tsconfig.json
 !components/component-parser
 !components/default-page.tsx
diff --git a/showcases/patternhub/data/routes.ts b/showcases/patternhub/data/routes.ts
index d315c7e90a3..752d3a542cc 100644
--- a/showcases/patternhub/data/routes.ts
+++ b/showcases/patternhub/data/routes.ts
@@ -232,6 +232,7 @@ export const ROUTES: NavigationItem[] = [
 		path: '/components',
 		subNavigation: [
 			{ label: 'Readme', path: '/components/readme' },
+			{ label: 'Router usage', path: '/components/router-usage' },
 			...componentChildren.map((category) => ({
 				...category,
 				subNavigation: category?.subNavigation?.map((component) => ({
diff --git a/showcases/patternhub/pages/components/router-usage/index.mdx b/showcases/patternhub/pages/components/router-usage/index.mdx
new file mode 100644
index 00000000000..33979456931
--- /dev/null
+++ b/showcases/patternhub/pages/components/router-usage/index.mdx
@@ -0,0 +1,6 @@
+import DefaultPage from "../../../components/default-page";
+import RouterUsage from "../../../../../packages/components/docs/router-usage.md";
+
+<RouterUsage />
+
+export default ({ children }) => <DefaultPage>{children}</DefaultPage>;