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

.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.
    */

packages/main/src/webComponents/ShellBar/ShellBar.mdx

@@ -1,5 +1,6 @@
 import { ControlsWithNote, DocsHeader, Footer } from '@sb/components';
 import SubcomponentsSection from '@sb/docs/SubcomponentsSection.md?raw';
+import DesignExamples from '@sb/docs/DesignCompliantExampleSection.md?raw';
 import { ArgTypes, Canvas, Description, Markdown, Meta } from '@storybook/blocks';
 import { ShellBarItem } from '../ShellBarItem/index';
 import { ShellBarSpacer } from '../ShellBarSpacer/index';
@@ -21,13 +22,41 @@ import { excludePropsForAbstract } from '@sb/utils';
 
 <ControlsWithNote of={ComponentStories.Default} />
 
-<br />
+<Markdown>{DesignExamples}</Markdown>
 
-# More Examples
+### All Features
 
-<br />
+A comprehensive ShellBar demonstrating all available features including notifications, search, content items, and profile.
+
+<Canvas of={ComponentStories.AllFeatures} />
+
+### Embedded Back Navigation
+
+ShellBar with embedded back navigation button in the start area.
+
+<Canvas of={ComponentStories.EmbeddedBackNavigation} />
+
+### Trial Example
+
+ShellBar configured for trial environments with trial tags and remaining days indicator.
+
+<Canvas of={ComponentStories.TrialExample} />
+
+### Multiple Productive Instances
+
+ShellBar setup for multiple productive system instances with region indicators.
+
+<Canvas of={ComponentStories.ProductiveInstances} />
+
+### Multiple Non-Productive Instances
+
+ShellBar setup for multiple non-productive system instances with system and region tags.
+
+<Canvas of={ComponentStories.NonProductiveInstances} />
+
+## More examples
 
-## Open a Popover on ShellBarItem click
+### Open a Popover on ShellBarItem click
 
 To open a popover with the `ShellBarItem` you can use the `detail.targetRef` property of the `onClick` event.
 

packages/main/src/webComponents/ShellBar/ShellBar.stories.tsx

@@ -1,9 +1,17 @@
 import image from '@sb/demoImages/Person.png';
 import type { Meta, StoryObj } from '@storybook/react';
-import addIcon from '@ui5/webcomponents-icons/dist/add.js';
-import searchIcon from '@ui5/webcomponents-icons/dist/search.js';
-import { Avatar, Icon, Input, ListItemStandard, ShellBarItem } from '../index';
-import { ShellBar } from './index';
+import menu2Icon from '@ui5/webcomponents-icons/dist/menu2.js';
+import navBackIcon from '@ui5/webcomponents-icons/dist/nav-back.js';
+import sysHelpIcon from '@ui5/webcomponents-icons/dist/sys-help.js';
+import { FlexBox } from '../../components/FlexBox/index.js';
+import { Button } from '../Button/index.js';
+import { Avatar, ShellBarItem, ShellBarSpacer } from '../index.js';
+import { Label } from '../Label/index.js';
+import { ShellBarSearch } from '../ShellBarSearch/index.js';
+import { Switch } from '../Switch/index.js';
+import { Tag } from '../Tag/index.js';
+import { Text } from '../Text/index.js';
+import { ShellBar } from './index.js';
 
 const meta = {
   title: 'Layouts & Floorplans / ShellBar',
@@ -17,30 +25,124 @@ const meta = {
     startButton: { control: { disable: true } },
   },
   args: {
+    primaryTitle: 'Shell Bar',
+    notificationsCount: '10',
+    showNotifications: true,
     logo: <img src="https://sap.github.io/ui5-webcomponents/images/sap-logo-svg.svg" alt="SAP Logo" />,
     profile: (
       <Avatar>
-        <img src={image} />
+        <img src={image} alt="person-placeholder" />
       </Avatar>
     ),
-    menuItems: (
-      <>
-        <ListItemStandard data-key="1" text="Menu Item 1" />
-        <ListItemStandard data-key="2" text="Menu Item 2" />
-        <ListItemStandard data-key="3" text="Menu Item 3" />
-      </>
-    ),
-    searchField: <Input showClearIcon icon={<Icon name={searchIcon} />} />,
-    notificationsCount: '10',
-    primaryTitle: 'Shell Bar',
-    secondaryTitle: 'Secondary Title',
-    showNotifications: true,
-    showProductSwitch: true,
-    children: <ShellBarItem count="3" text={'ShellBarItem'} icon={addIcon} />,
+    startButton: <Button icon={menu2Icon} tooltip="Menu" accessibleName="Menu" />,
+    searchField: <ShellBarSearch showClearIcon placeholder="Search Apps, Products" />,
+    children: <ShellBarItem text={'Help'} icon={sysHelpIcon} />,
   },
   tags: ['package:@ui5/webcomponents-fiori'],
 } satisfies Meta<typeof ShellBar>;
 export default meta;
 type Story = StoryObj<typeof meta>;
 
 export const Default: Story = {};
+
+export const AllFeatures: Story = {
+  args: {
+    showProductSwitch: true,
+    startButton: (
+      <>
+        <Button icon={menu2Icon} tooltip="Menu" accessibleName="Menu" />
+        <Button icon={navBackIcon} tooltip="Back" accessibleName="Back" />
+      </>
+    ),
+    content: (
+      <>
+        <Tag design="Set2" colorScheme="7">
+          Trial
+        </Tag>
+        <Text>30 days remaining</Text>
+        <ShellBarSpacer />
+        <FlexBox gap="0 5px" alignItems="Center">
+          <Switch />
+          <Label>Try Beta Version</Label>
+        </FlexBox>
+      </>
+    ),
+  },
+};
+
+export const EmbeddedBackNavigation: Story = {
+  args: {
+    startButton: <Button icon={navBackIcon} tooltip="Back" accessibleName="Back" />,
+  },
+};
+
+export const TrialExample: Story = {
+  args: {
+    content: (
+      <>
+        <Tag design="Set2" colorScheme="7">
+          Trial
+        </Tag>
+        <Text>30 days remaining</Text>
+      </>
+    ),
+  },
+};
+
+export const ProductiveInstances: Story = {
+  args: {
+    content: (
+      <Tag design="Set2" colorScheme="10">
+        Region EMEA
+      </Tag>
+    ),
+  },
+
+  render(args) {
+    return (
+      <>
+        <ShellBar {...args} />
+        <ShellBar
+          {...args}
+          content={
+            <Tag design="Set2" colorScheme="10">
+              Region APJ
+            </Tag>
+          }
+        />
+      </>
+    );
+  },
+};
+
+export const NonProductiveInstances: Story = {
+  args: {
+    content: (
+      <>
+        <Tag design="Set2" colorScheme="8">
+          Q System
+        </Tag>
+        <Text>Region EMEA</Text>
+      </>
+    ),
+  },
+
+  render(args) {
+    return (
+      <>
+        <ShellBar {...args} />
+        <ShellBar
+          {...args}
+          content={
+            <>
+              <Tag design="Set2" colorScheme="8">
+                Q System
+              </Tag>
+              <Text>Region APJ</Text>
+            </>
+          }
+        />
+      </>
+    );
+  },
+};