feat(components): add close button on <SectionMessage> (#4204)

.changeset/warm-worms-obey.md

@@ -0,0 +1,11 @@
+---
+"@marigold/docs": patch
+"@marigold/components": patch
+"@marigold/theme-b2b": patch
+"@marigold/theme-core": patch
+---
+
+docs([DST-582]): revise `<SectionMessage>` page according to new component page structure
+feat(components): add close button on `<SectionMessage>`
+
+Revised the `<SectionMessage>` documentation page to our new layout of component pages. And added a close button to allow the user to dismiss the `<SectionMessage>` this is now aligned with our feedback message pattern.

docs/content/components/content/section-message/section-message-action.demo.tsx

@@ -0,0 +1,17 @@
+import { Inline, Link, SectionMessage, Stack } from '@marigold/components';
+
+export default () => (
+  <SectionMessage closeButton>
+    <SectionMessage.Title>This page is read-only.</SectionMessage.Title>
+    <SectionMessage.Content>
+      <Stack space={2}>
+        You don't have permission to edit this page. If you think you should
+        have editing rights, contact your group administrator.
+        <Inline space={4}>
+          <Link href="#">View team roles</Link>
+          <Link href="#">About permission</Link>
+        </Inline>
+      </Stack>
+    </SectionMessage.Content>
+  </SectionMessage>
+);

docs/content/components/content/section-message/section-message-dismissable.demo.tsx

@@ -0,0 +1,13 @@
+import { SectionMessage } from '@marigold/components';
+
+export default () => (
+  <SectionMessage closeButton>
+    <SectionMessage.Title>
+      Configuration of the hardware key
+    </SectionMessage.Title>
+    <SectionMessage.Content>
+      Activating the function allows you to change the scanning direction. Keep
+      in mind to have the correct settings set to "changeable".
+    </SectionMessage.Content>
+  </SectionMessage>
+);

docs/content/components/content/section-message/section-message.mdx

@@ -1,56 +1,162 @@
 ---
 title: SectionMessage
-caption: Display a short message with important informations.
+caption: Display important informations in a section of a screen.
+badge: updated
 ---
 
-The `<SectionMessage>` component is used to capture the users atention to provide information. It is meant to show only very relevant information. The title should contain the most relevant information about the message.
+The `<SectionMessage>` component is a block-level element designed to alert users about specific content in a designated section on the page. It is positioned close to the relevant content to clearly indicate its connection. Section messages provide contextual feedback within a section of the page and are persistent, non-modal elements.
 
-This component should not be added on a dynymic way.
+## Anatomy
 
-There are currently three different variants of the `<SectionMessage>` component. The `info` variant is set as default. Inside the `<SectionMessage>` it lends itself to using the [`<Text>`](/componentss/text/) component.
+The section message consists of a container which includes an optional icon to support the message and a title. The actual content of section messages is located under the title.
 
-## Import
+Optionally, you can add a button to dismiss the message.
 
-To import the component you just have to use this code below.
-
-```tsx
-import { SectionMessage } from '@marigold/components';
-```
+<Image
+  src="/sectionmessage/sectionmessage-anatomy.jpg"
+  alt="Anatomy of a SectionMessage"
+  width={800}
+  height={550}
+  className="mx-auto block"
+/>
 
 ## Appearance
 
+<AppearanceDemo component={title} />
+
 <AppearanceTable component={title} />
 
+## Usage
+
+Section messages are ideal for displaying important feedback related to a specific section of the page.
+
+Unlike modal dialogs, which interrupt the user's workflow, section messages remain visible without blocking interaction with other parts of the interface.
+
+<Do>
+  <Do.Description>
+    <ul>
+      <li>
+        The section message title should make the topic or purpose of the
+        message clear.
+      </li>
+      <li>
+        The content provides a brief description of the event that has occurred
+        on the page
+      </li>
+    </ul>
+  </Do.Description>
+</Do>
+
+### Position
+
+They should be positioned close to the relevant content, typically directly above, to ensure users can easily identify the relationship between the message and the affected area.
+
+<GuidelineTiles>
+  <Do>
+    <Do.Figure>
+      <Image
+        width={700}
+        height={700}
+        unoptimized
+        src="/sectionmessage/sectionmessage-do-placement.png"
+        alt="Place section messages near the affected content."
+      />
+    </Do.Figure>
+    <Do.Description>
+      Place section message near the affected content.
+    </Do.Description>
+  </Do>
+  <Dont>
+    <Dont.Figure>
+      <Image
+        width={700}
+        height={700}
+        unoptimized
+        src="/sectionmessage/sectionmessage-dont-placement.png"
+        alt="Don't place section messages in unaffected sections."
+      />
+    </Dont.Figure>
+    <Dont.Description>
+      Don't place section messages in unaffected sections.
+    </Dont.Description>
+  </Dont>
+</GuidelineTiles>
+
+### Dismissable message
+
+Dismissable messages are used to provide temporary feedback or notifications that the user can manually close or dismiss when they no longer need the information. They are generally used when feedback is helpful but doesn't need to stay on screen permanently.
+
+To provide this, you have to use the `closeButton` property on the `<SectionMessage>`.
+
+<ComponentDemo file="./section-message-dismissable.demo.tsx" />
+
+### Actions
+
+Actions, such as buttons or links, should be placed near the message content to make the next steps intuitive for users. Clear, accessible options help users easily respond to the feedback provided, allowing them to address the issue without disrupting their workflow.
+
+<ComponentDemo file="section-message-action.demo.tsx" />
+
+<GuidelineTiles>
+  <Do>
+    <Do.Description>
+      Use section messages for providing non-disruptive feedback or
+      notifications, allowing users to address the message when convenient.
+    </Do.Description>
+  </Do>
+  <Dont>
+    <Dont.Description>
+      Don't use the section message if you need to interact with it to procced
+      with a task or a flow.
+    </Dont.Description>
+  </Dont>
+</GuidelineTiles>
+
 ## Props
 
+<StorybookHintMessage component={title} />
+
 ### SectionMessage
 
 <PropsTable component={title} />
 
-#### SectionMessage.Title
+### SectionMessage.Title
 
 <PropsTable component="SectionMessageTitle" />
 
-#### SectionMessage.Content
+### SectionMessage.Content
 
 <PropsTable component="SectionMessageContent" />
 
-## Examples
-
-### Info Section Message
-
-This is the default info `<SectionMessage>`. The color is in a blue tone and contains the [`<Info>`](/foundations/icons/#info) icon.
-
-<ComponentDemo file="./section-message-info.demo.tsx" />
-
-### Warning Section Message
-
-Here you can see the warning `<SectionMessage>`. The color is in a yellow tone and contains the[`<Notification>`](/foundations/icons/#info) icon.
-
-<ComponentDemo file="./section-message-warn.demo.tsx" />
-
-### Error Section Message
-
-The error `<SectionMessage>` is colored in a red tone and contains the [`<Exclamation>`](/foundations/icons/#info) icon.
-
-<ComponentDemo file="./section-message-error.demo.tsx" />
+## Alternative components
+
+- **[Dialog](/components/overlay/dialog)**: If you need to interact with messages to procced with a task or a flow you should use a dialog.
+
+- **[Form components](/patterns/building-forms)**: When you need to inform the users of a status from a form field, you can use the help text/ validation message which comes with our form components.
+
+## Related
+
+<TeaserList
+  items={[
+    {
+      title: 'Feedback Messages',
+      href: '/patterns/feedback-messages',
+      caption: 'Learn when to use which message.',
+      icon: (
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          fill="none"
+          viewBox="0 0 24 24"
+          strokeWidth={1.5}
+          stroke="currentColor"
+          className="size-6"
+        >
+          <path
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            d="M2.25 12.76c0 1.6 1.123 2.994 2.707 3.227 1.087.16 2.185.283 3.293.369V21l4.076-4.076a1.526 1.526 0 0 1 1.037-.443 48.282 48.282 0 0 0 5.68-.494c1.584-.233 2.707-1.626 2.707-3.228V6.741c0-1.602-1.123-2.995-2.707-3.228A48.394 48.394 0 0 0 12 3c-2.392 0-4.744.175-7.043.513C3.373 3.746 2.25 5.14 2.25 6.741v6.018Z"
+          />
+        </svg>
+      ),
+    },
+  ]}
+/>

docs/content/components/content/section-message/sectionmessage-appearance.demo.tsx

@@ -0,0 +1,11 @@
+import { SectionMessage, SectionMessageProps } from '@marigold/components';
+
+export default (props: SectionMessageProps) => (
+  <SectionMessage {...props}>
+    <SectionMessage.Title>This page is read-only!</SectionMessage.Title>
+    <SectionMessage.Content>
+      You don't have permission to edit this page. If you think you should have
+      editing rights, contact your group administrator.
+    </SectionMessage.Content>
+  </SectionMessage>
+);

docs/content/patterns/feedback-messages/feedback-messages.mdx

@@ -167,12 +167,36 @@ A [section message](/components/section-message) is a block-level component that
 
 <ComponentDemo file="./sectionmessage-info.demo.tsx" />
 
-<Image
-  width="900"
-  height="500"
-  src="/dosAndDonts_message_position.png"
-  alt="Do and donts clarity"
-/>
+<GuidelineTiles>
+  <Do>
+    <Do.Figure>
+      <Image
+        width={700}
+        height={700}
+        unoptimized
+        src="/sectionmessage/sectionmessage-do-placement.png"
+        alt="Place section messages near the affected content."
+      />
+    </Do.Figure>
+    <Do.Description>
+      Place section message near the affected content.
+    </Do.Description>
+  </Do>
+  <Dont>
+    <Dont.Figure>
+      <Image
+        width={700}
+        height={700}
+        unoptimized
+        src="/sectionmessage/sectionmessage-dont-placement.png"
+        alt="Don't place section messages in unaffected sections."
+      />
+    </Dont.Figure>
+    <Dont.Description>
+      Don't place section messages in unaffected sections.
+    </Dont.Description>
+  </Dont>
+</GuidelineTiles>
 
 ## Placement and Appearance
 

packages/components/src/SectionMessage/SectionMessage.stories.tsx

@@ -13,6 +13,12 @@ const meta = {
       options: ['success', 'info', 'warning', 'error'],
       description: 'The variants of the message',
     },
+    closeButton: {
+      control: {
+        type: 'boolean',
+      },
+      description: 'makes the message dismissable.',
+    },
   },
 } satisfies Meta<typeof SectionMessage>;
 
@@ -21,7 +27,7 @@ type Story = StoryObj<typeof meta>;
 
 export const Basic: Story = {
   render: args => (
-    <SectionMessage {...args}>
+    <SectionMessage closeButton {...args}>
       <SectionMessage.Title>Danger Zone!</SectionMessage.Title>
       <SectionMessage.Content>
         <Text>Hello, I am a simple message.</Text>

packages/components/src/SectionMessage/SectionMessage.test.tsx

@@ -1,4 +1,5 @@
 import { screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 import { Theme, ThemeProvider, cva } from '@marigold/system';
 import { setup } from '../test.utils';
 import { SectionMessage } from './SectionMessage';
@@ -45,6 +46,7 @@ const theme: Theme = {
 };
 
 const { render } = setup({ theme });
+const user = userEvent.setup();
 
 test('message container supports base styling and themeSection', () => {
   render(
@@ -136,3 +138,24 @@ test('set alert role if variant is "error"', () => {
 
   expect(message).toHaveAttribute('role', 'alert');
 });
+
+test('allow to close message with button in message', async () => {
+  render(
+    <ThemeProvider theme={theme}>
+      <SectionMessage data-testid="messages" variant="error" closeButton>
+        <SectionMessage.Title>messages</SectionMessage.Title>
+        <SectionMessage.Content>default</SectionMessage.Content>
+      </SectionMessage>
+    </ThemeProvider>
+  );
+  const message = screen.getByTestId(/messages/);
+  const button = screen.getByRole('button');
+
+  expect(message).toBeInTheDocument();
+  expect(button).toBeInTheDocument();
+  expect(button).toHaveAttribute('aria-label');
+
+  await user.click(button);
+
+  expect(message).not.toBeInTheDocument();
+});