docs: introduce (UXC) "patterns" section & add design examples for ShellBar (#7411)

Author: Lukas742

.github/renovate.json

@@ -72,21 +72,21 @@
       ]
     },
     {
-      "description": "Example & Template dependencies",
+      "description": "Example,Template & Pattern dependencies",
       "extends": ["schedule:weekly"],
-      "matchFileNames": ["examples/**", "templates/**"],
+      "matchFileNames": ["examples/**", "templates/**", "patterns/**"],
       "semanticCommitType": "chore",
-      "groupName": "all non-major dependencies (examples & templates)",
+      "groupName": "all non-major dependencies (examples, templates & patterns)",
       "groupSlug": "examples-all-minor-patch",
       "matchUpdateTypes": ["minor", "patch"],
       "matchBaseBranches": ["main"],
       "matchPackageNames": ["*", "!/^@ui5//"]
     },
     {
-      "description": "UI5 Web Components (for React) in all examples & templates",
-      "groupName": "UI5 Web Components React (examples & templates)",
+      "description": "UI5 Web Components (for React) in all examples, templates & patterns",
+      "groupName": "UI5 Web Components React (examples, templates & patterns)",
       "groupSlug": "examples-ui5-webcomponents-react",
-      "matchFileNames": ["examples/**", "templates/**"],
+      "matchFileNames": ["examples/**", "templates/**", "patterns/**"],
       "semanticCommitType": "chore",
       "matchBaseBranches": ["main"],
       "matchSourceUrls": [

.github/workflows/examples.yml

@@ -7,10 +7,12 @@ on:
     paths:
       - 'examples/**/*'
       - 'templates/**/*'
+      - 'patterns/navigation-layout/**/*'
   pull_request:
     paths:
       - 'examples/**/*'
       - 'templates/**/*'
+      - 'patterns/navigation-layout/**/*'
 
 jobs:
   examples:
@@ -77,3 +79,33 @@ jobs:
       - name: ESLint
         run: npm run lint --if-present
         working-directory: templates/${{ matrix.path }}
+
+  patterns:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        path:
+          - navigation-layout
+      fail-fast: false
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4.4.0
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install
+        run: npm ci
+        working-directory: patterns/${{ matrix.path }}
+
+      - name: Build
+        run: npm run build
+        working-directory: patterns/${{ matrix.path }}
+
+      - name: Test
+        run: npm run test --if-present
+        working-directory: patterns/${{ matrix.path }}
+
+      - name: ESLint
+        run: npm run lint --if-present
+        working-directory: patterns/${{ matrix.path }}

.storybook/docs/DesignCompliantExampleSection.md

@@ -0,0 +1,3 @@
+## Design-Compliant Examples
+
+These examples demonstrate the implementation of design specifications. They primarily illustrate design concepts and mostly do not provide additional functionality. You can reference them to select the appropriate design patterns.

.storybook/preview.tsx

@@ -144,6 +144,7 @@ const preview: Preview = {
           'Knowledge Base',
           'Testing with Cypress',
           ['Setup', 'Commands', 'Queries'],
+          'Patterns',
           'Charts',
           ['Docs'],
           'Data Display',

docs/EmbeddedStackBlitz.tsx

@@ -0,0 +1,34 @@
+import sdk from '@stackblitz/sdk';
+import { useEffect, useRef } from 'react';
+
+interface EmbeddedStackBlitzProps {
+  repoPath: string;
+}
+
+export function EmbeddedStackBlitz({ repoPath }: EmbeddedStackBlitzProps) {
+  const containerRef = useRef<HTMLDivElement | null>(null);
+
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) {
+      return;
+    }
+    sdk.embedGithubProject(container, repoPath, {
+      openFile: 'src/App.tsx',
+      view: 'editor',
+      height: '90%',
+      hideDevTools: true,
+      terminalHeight: 0,
+    });
+
+    return () => {
+      if (container) {
+        container.innerHTML = '';
+      }
+    };
+  }, [repoPath]);
+
+  return <div ref={containerRef} />;
+}
+
+EmbeddedStackBlitz.displayName = 'EmbeddedStackBlitz';

docs/Patterns.mdx

@@ -0,0 +1,11 @@
+import {Footer} from '@sb/components';
+import {Meta} from '@storybook/blocks';
+import UXCIntegration from "./UXCIntegration.js"
+
+<Meta title="Patterns / UXC Integration"/>
+
+# UXC Integration
+
+<UXCIntegration/>
+
+<Footer/>

docs/UXCIntegration.tsx

@@ -0,0 +1,26 @@
+import { MessageStrip, ThemeProvider } from '@ui5/webcomponents-react';
+import UXCIntegrationApp from '../patterns/navigation-layout/src/App.js';
+import '../patterns/navigation-layout/src/index.css';
+import { EmbeddedStackBlitz } from '@/docs/EmbeddedStackBlitz.js';
+
+function UXCIntegration() {
+  return (
+    <div style={{ height: '80vh', position: 'relative' }}>
+      <ThemeProvider>
+        <UXCIntegrationApp
+          content={
+            <>
+              <MessageStrip hideCloseButton style={{ marginBlockEnd: '0.25rem' }}>
+                For a full-page view of this pattern, click <b>&#34;Fork on StackBlitz&#34;</b> below to open it in the
+                standalone StackBlitz editor.
+              </MessageStrip>
+              <EmbeddedStackBlitz repoPath="SAP/ui5-webcomponents-react/tree/main/patterns/navigation-layout" />
+            </>
+          }
+        />
+      </ThemeProvider>
+    </div>
+  );
+}
+
+export default UXCIntegration;

eslint.config.mjs

@@ -30,6 +30,7 @@ const ignorePatterns = {
     '**/out/**',
     '**/examples',
     '**/templates',
+    '**/patterns/navigation-layout',
   ],
 };
 

package.json

@@ -35,6 +35,7 @@
     "create-theming-parameters": "node scripts/generate-theming-parameters.js"
   },
   "dependencies": {
+    "@stackblitz/sdk": "^1.11.0",
     "@storybook/addon-a11y": "8.6.14",
     "@storybook/addon-essentials": "8.6.14",
     "@storybook/blocks": "8.6.14",

packages/main/src/components/MessageBox/index.tsx

@@ -49,6 +49,7 @@ export interface MessageBoxPropTypes
    * Flag whether the Message Box should be opened or closed
    */
   open?: DialogPropTypes['open'];
+  // todo: add headerText prop and deprecate `titleText`
   /**
    * A custom title for the MessageBox. If not present, it will be derived from the `MessageBox` type.
    */