NotificationMarker docs page (#1999)

apps/react-workshop/src/NotificationMarker.stories.tsx

@@ -33,17 +33,16 @@ export const Basic = () => {
   return (
     <>
       <NotificationMarker status='primary'>
-        <SvgNotification width={16} height={16} fill='currentColor' />
+        <SvgNotification fill='currentColor' />
       </NotificationMarker>
-      <NotificationMarker status='primary'>Normal</NotificationMarker>
     </>
   );
 };
 
 export const WithButtons = () => {
   return (
     <>
-      <IconButton styleType='borderless'>
+      <IconButton label='Notifications' styleType='borderless'>
         <NotificationMarker status='primary'>
           <SvgNotification />
         </NotificationMarker>
@@ -59,58 +58,54 @@ export const WithButtons = () => {
 export const Pulsing = () => {
   return (
     <>
-      <IconButton styleType='borderless'>
+      <IconButton label='Notifications' styleType='borderless'>
         <NotificationMarker status='negative' pulsing>
           <SvgNotification />
         </NotificationMarker>
       </IconButton>
-
-      <NotificationMarker status='negative' pulsing>
-        <Text style={{ fontWeight: '700' }}>URGENT</Text>
-      </NotificationMarker>
     </>
   );
 };
 
 export const Status = () => {
   return (
     <>
-      <NotificationMarker status='primary'>Primary</NotificationMarker>
-      <IconButton styleType='borderless'>
+      <Text>Primary</Text>
+      <IconButton label='Notifications' styleType='borderless'>
         <NotificationMarker status='primary'>
           <SvgNotification />
         </NotificationMarker>
       </IconButton>
 
-      <NotificationMarker status='positive'>Positive</NotificationMarker>
-      <IconButton styleType='borderless'>
+      <Text>Positive</Text>
+      <IconButton label='Notifications' styleType='borderless'>
         <NotificationMarker status='positive'>
           <SvgNotification />
         </NotificationMarker>
       </IconButton>
 
-      <NotificationMarker status='warning'>Warning</NotificationMarker>
-      <IconButton styleType='borderless'>
+      <Text>Warning</Text>
+      <IconButton label='Notifications' styleType='borderless'>
         <NotificationMarker status='warning'>
           <SvgNotification />
         </NotificationMarker>
       </IconButton>
 
-      <NotificationMarker status='negative'>Negative</NotificationMarker>
-      <IconButton styleType='borderless'>
+      <Text>Negative</Text>
+      <IconButton label='Notifications' styleType='borderless'>
         <NotificationMarker status='negative'>
           <SvgNotification />
         </NotificationMarker>
       </IconButton>
 
-      <NotificationMarker status='white'>White</NotificationMarker>
+      <Text>White</Text>
       <div style={{ display: 'flex', columnGap: '10px' }}>
-        <IconButton styleType='high-visibility'>
+        <IconButton label='Notifications' styleType='high-visibility'>
           <NotificationMarker status='white'>
             <SvgNotification />
           </NotificationMarker>
         </IconButton>
-        <IconButton styleType='cta'>
+        <IconButton label='Notifications' styleType='cta'>
           <NotificationMarker status='white'>
             <SvgNotification />
           </NotificationMarker>

apps/website/src/content/docs/inputwithdecorations.mdx

@@ -18,7 +18,7 @@ Add icons, buttons and other various subcomponents to input.
 
 ### Status
 
-InputWithDecorations can have positive, warning and negative status.
+InputWithDecorations can have positive, warning, or negative statuses.
 
 <LiveExample src='InputWithDecorations.status.jsx'>
   <AllExamples.InputWithDecorationsStatusExample client:load />

apps/website/src/content/docs/notificationmarker.mdx

@@ -0,0 +1,63 @@
+---
+title: NotificationMarker
+description: Shows a notification marker dot at the top right of the component.
+thumbnail: #TODO
+---
+
+<p>{frontmatter.description}</p>
+
+<LiveExample src='NotificationMarker.main.jsx'>
+  <AllExamples.NotificationMarkerMainExample client:load />
+</LiveExample>
+
+## Usage
+
+The `NotificationMarker` component should be wrapped around the content which needs a marker/dot. This content is usually an icon, and is often used within an [`IconButton`](button#iconbutton).
+
+```jsx {2, 4}
+<IconButton label='Notifications' styleType='borderless'>
+  <NotificationMarker>
+    <SvgNotification />
+  </NotificationMarker>
+</IconButton>
+```
+
+### Conditional rendering
+
+There are many situations when the notification marker needs to appear/disappear depending on the application lifetime. Instead of conditionally rendering the `NotificationMarker` in such situations, the `enabled` prop can be used.
+
+```jsx
+<NotificationMarker enabled={notifications.length > 0}>…</NotificationMarker>
+```
+
+When `enabled` is set to `false`, the DOM element will still be present, but the notification marker will not be displayed visually.
+
+### Status
+
+`NotificationMarker`s can have the follow statuses:
+
+- `primary` (default)
+- `positive`
+- `warning`
+- `negative`
+- `white`
+
+<LiveExample src='NotificationMarker.statuses.jsx'>
+  <AllExamples.NotificationMarkerStatusesExample client:load />
+</LiveExample>
+
+The `white` status is used on colored backgrounds, such as when using it in the [high visibility](button#high-visibility) or the [call-to-action](button#call-to-action) buttons.
+
+### Pulsing
+
+To give a higher importance to the notification, you can use the `pulsing` prop to show a pulse effect around the marker.
+
+**Note**: This prop should be used sparingly as it can be distracting to the user.
+
+<LiveExample src='NotificationMarker.pulsing.jsx'>
+  <AllExamples.NotificationMarkerPulsingExample client:load />
+</LiveExample>
+
+## Props
+
+<PropsTable path={'@itwin/itwinui-react/esm/core/NotificationMarker/NotificationMarker.d.ts'} />

apps/website/src/content/docs/searchbox.mdx

@@ -2,7 +2,7 @@
 title: SearchBox
 description: A search input component
 propsPath: '@itwin/itwinui-react/esm/core/SearchBox/SearchBox.d.ts'
-thumbnail:
+thumbnail: #TODO
 ---
 
 <p>{frontmatter.description}</p>

examples/NotificationMarker.main.jsx

@@ -0,0 +1,15 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+import * as React from 'react';
+import { NotificationMarker } from '@itwin/itwinui-react';
+import { SvgNotification } from '@itwin/itwinui-icons-react';
+
+export default () => {
+  return (
+    <NotificationMarker status='primary'>
+      <SvgNotification />
+    </NotificationMarker>
+  );
+};

examples/NotificationMarker.pulsing.jsx

@@ -0,0 +1,17 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+import * as React from 'react';
+import { NotificationMarker, IconButton, Text } from '@itwin/itwinui-react';
+import { SvgNotification } from '@itwin/itwinui-icons-react';
+
+export default () => {
+  return (
+    <IconButton label='Notifications' styleType='borderless'>
+      <NotificationMarker status='negative' pulsing>
+        <SvgNotification />
+      </NotificationMarker>
+    </IconButton>
+  );
+};

examples/NotificationMarker.statuses.css

@@ -0,0 +1,4 @@
+.demo-container {
+  display: flex;
+  column-gap: 10px;
+}

examples/NotificationMarker.statuses.jsx

@@ -0,0 +1,49 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+import * as React from 'react';
+import { NotificationMarker, IconButton, Text } from '@itwin/itwinui-react';
+import { SvgNotification } from '@itwin/itwinui-icons-react';
+
+export default () => {
+  return (
+    <div className='demo-container'>
+      <IconButton label='Primary' styleType='borderless'>
+        <NotificationMarker status='primary'>
+          <SvgNotification />
+        </NotificationMarker>
+      </IconButton>
+
+      <IconButton label='Positive' styleType='borderless'>
+        <NotificationMarker status='positive'>
+          <SvgNotification />
+        </NotificationMarker>
+      </IconButton>
+
+      <IconButton label='Warning' styleType='borderless'>
+        <NotificationMarker status='warning'>
+          <SvgNotification />
+        </NotificationMarker>
+      </IconButton>
+
+      <IconButton label='Negative' styleType='borderless'>
+        <NotificationMarker status='negative'>
+          <SvgNotification />
+        </NotificationMarker>
+      </IconButton>
+
+      <IconButton label='White' styleType='high-visibility'>
+        <NotificationMarker status='white'>
+          <SvgNotification />
+        </NotificationMarker>
+      </IconButton>
+
+      <IconButton label='White' styleType='cta'>
+        <NotificationMarker status='white'>
+          <SvgNotification />
+        </NotificationMarker>
+      </IconButton>
+    </div>
+  );
+};

examples/index.tsx

@@ -823,6 +823,26 @@ export { NonIdealStateErrorExample };
 
 // ----------------------------------------------------------------------------
 
+import { default as NotificationMarkerMainExampleRaw } from './NotificationMarker.main';
+const NotificationMarkerMainExample = withThemeProvider(
+  NotificationMarkerMainExampleRaw,
+);
+export { NotificationMarkerMainExample };
+
+import { default as NotificationMarkerStatusesExampleRaw } from './NotificationMarker.statuses';
+const NotificationMarkerStatusesExample = withThemeProvider(
+  NotificationMarkerStatusesExampleRaw,
+);
+export { NotificationMarkerStatusesExample };
+
+import { default as NotificationMarkerPulsingExampleRaw } from './NotificationMarker.pulsing';
+const NotificationMarkerPulsingExample = withThemeProvider(
+  NotificationMarkerPulsingExampleRaw,
+);
+export { NotificationMarkerPulsingExample };
+
+// ----------------------------------------------------------------------------
+
 import { default as OverlayMainExampleRaw } from './Overlay.main';
 const OverlayMainExample = withThemeProvider(OverlayMainExampleRaw);
 export { OverlayMainExample };

packages/itwinui-react/src/core/NotificationMarker/NotificationMarker.tsx

@@ -31,14 +31,15 @@ type NotificationMarkerProps = {
    */
   pulsing?: boolean;
   /**
-   * Set this programmatically to false when you just want to render the passed children without the notification
-   * @default true
+   * Instead of conditionally rendering the `NotificationMarker`, the `enabled` prop can be used.
+   *
+   * When `enabled` is set to `false`, the DOM element will still be present, but the notification marker will not be displayed visually.
+   *
    * @example
-   * let [newMessagesCount, ...] = useState(0);
-   * ...
-   * <NotificationMarker enabled={newMessagesCount > 0}>
-   *   <SvgNotification />
+   * <NotificationMarker enabled={notifications.length > 0}>
+   *  …
    * </NotificationMarker>
+   * @default true
    */
   enabled?: boolean;
 };