feat(Badge): support a contextual help

apps/docs/src/content/components/status/badge/examples/contextualHelp.tsx

@@ -0,0 +1,16 @@
+import {
+  Badge,
+  ContextualHelp,
+  Label,
+  Text,
+} from "@mittwald/flow-react-components";
+
+<Badge>
+  <Label>Priorität</Label>
+  <Text>Hoch</Text>
+  <ContextualHelp>
+    <Text>
+      Tickets mit hoher Priorität werden zuerst bearbeitet.
+    </Text>
+  </ContextualHelp>
+</Badge>;

apps/docs/src/content/components/status/badge/index.mdx

@@ -80,9 +80,19 @@ Informationen zu öffnen. Es sollte dabei nicht als Ersatz für einen
 
 ---
 
-# Badge entfernen
+# Mit ContextualHelp
 
-Über `onClose` lässt sich ein Badge vom User aus der Oberfläche entfernen.
+Eine [ContextualHelp](/components/overlays/contextual-help) im Badge wird am
+Ende als Button dargestellt. Den Button stellt das Badge selbst.
+
+<LiveCodeEditor example="contextualHelp" editorCollapsed />
+
+---
+
+# Mit onClose
+
+Über `onClose` platzierst du einen X-Button im Badge. Nutze ihn z. B., um das
+Badge entfernbar zu machen.
 
 <LiveCodeEditor example="onClose" editorCollapsed />
 

packages/components/src/components/Badge/Badge.browser.test.tsx

@@ -0,0 +1,42 @@
+import { expect, test } from "vitest";
+import { render } from "vitest-browser-react";
+import { page } from "vitest/browser";
+import { Badge } from "@/components/Badge";
+import { ContextualHelp } from "@/components/ContextualHelp";
+import { Text } from "@/components/Text";
+
+test("A contextual help in the content opens from a button of its own", async () => {
+  await render(
+    <Badge>
+      Value
+      <ContextualHelp>
+        <Text>Every value has a story to tell.</Text>
+      </ContextualHelp>
+    </Badge>,
+  );
+
+  await expect
+    .element(page.getByText("Every value has a story to tell."))
+    .not.toBeInTheDocument();
+
+  await page.getByRole("button", { name: "More information" }).click();
+
+  await expect
+    .element(page.getByText("Every value has a story to tell."))
+    .toBeInTheDocument();
+});
+
+test("A disabled badge disables the contextual help button", async () => {
+  const screen = await render(
+    <Badge isDisabled>
+      Value
+      <ContextualHelp>
+        <Text>Every value has a story to tell.</Text>
+      </ContextualHelp>
+    </Badge>,
+  );
+
+  await expect
+    .element(screen.getByRole("button", { name: "More information" }))
+    .toBeDisabled();
+});

packages/components/src/components/Badge/Badge.module.d.scss.ts

@@ -2,6 +2,7 @@ declare const classNames: {
   readonly badge: "badge";
   readonly content: "content";
   readonly button: "button";
+  readonly action: "action";
   readonly close: "close";
   readonly scope: "scope";
   readonly value: "value";

packages/components/src/components/Badge/Badge.module.scss

@@ -30,19 +30,28 @@
   }
 
   .button,
+  .action,
   .close {
     @include focus.focus;
   }
 
   @extend .neutral;
 
-  &:has(.close) {
+  &:has(.close),
+  &:has(.action) {
     .button,
     .content {
       padding-inline-end: calc(var(--content-size) + var(--badge--spacing));
     }
   }
 
+  &:has(.action):has(.close) {
+    .button,
+    .content {
+      padding-inline-end: calc(var(--content-size) * 2 + var(--badge--spacing));
+    }
+  }
+
   &:has(.scope) {
     .content,
     .button {
@@ -59,7 +68,8 @@
       flex-shrink: 0;
     }
 
-    &:has(.close) {
+    &:has(.close),
+    &:has(.action) {
       .button,
       .content {
         padding-inline-end: var(--content-size);
@@ -69,20 +79,45 @@
         }
       }
     }
+
+    &:has(.action):has(.close) {
+      .button,
+      .content {
+        padding-inline-end: calc(var(--content-size) * 2);
+      }
+    }
   }
 
+  .action,
   .close {
     height: var(--content-size);
     padding: calc(var(--badge--padding-y) - var(--badge--border-width));
     border-radius: 0;
-    border-end-end-radius: var(--badge-size);
-    border-start-end-radius: var(--badge-size);
     margin-inline-start: calc(
-      (var(--badge-size) - var(--badge--border-width)) * -1
+      (var(--content-size) + var(--badge--border-width)) * -1
     );
     margin-top: var(--badge--border-width);
   }
 
+  /* The trailing button rounds off the badge */
+  .close,
+  &:not(:has(.close)) .action {
+    border-end-end-radius: var(--badge-size);
+    border-start-end-radius: var(--badge-size);
+  }
+
+  &:has(.action):has(.close) {
+    .action {
+      margin-inline-start: calc(
+        (var(--content-size) * 2 + var(--badge--border-width)) * -1
+      );
+    }
+
+    .close {
+      margin-inline-start: 0;
+    }
+  }
+
   /* Colors */
 
   @mixin color($color) {
@@ -135,6 +170,7 @@
       color: var(--badge--disabled-content-color);
     }
 
+    .action,
     .close {
       color: var(--badge--disabled-content-color);
     }
@@ -156,6 +192,7 @@
         color: var(--badge--disabled-#{$color}-content-color);
       }
 
+      .action,
       .close {
         color: var(--badge--disabled-#{$color}-content-color);
       }

packages/components/src/components/Badge/Badge.tsx

@@ -13,6 +13,8 @@ import type { PressEvent } from "@react-types/shared";
 import { Button } from "@/components/Button";
 import { IconClose } from "@/components/Icon/components/icons";
 import { useLocalizedStringFormatter } from "@/components/TranslationProvider/useLocalizedStringFormatter";
+import { UiComponentTunnelExit } from "@/components/UiComponentTunnel/UiComponentTunnelExit";
+import { ContextualHelpButton } from "@/components/Badge/components/ContextualHelpButton";
 import locales from "./locales/*.locale.json";
 
 export const badgeColors = [
@@ -41,6 +43,11 @@ export interface BadgeProps
   isDisabled?: boolean;
 }
 
+const contextualHelpTunnel = {
+  id: "contextualHelp",
+  component: "Badge",
+} as const;
+
 /** @flr-generate all */
 export const Badge = flowComponent("Badge", (props) => {
   const {
@@ -63,6 +70,8 @@ export const Badge = flowComponent("Badge", (props) => {
     className,
   );
 
+  const buttonColor = isAlphaColor(color) ? color : "dark";
+
   const propsContext: PropsContext = {
     Label: {
       elementType: "span",
@@ -84,6 +93,16 @@ export const Badge = flowComponent("Badge", (props) => {
         className: styles.value,
       },
     },
+    ContextualHelp: {
+      tunnel: contextualHelpTunnel,
+      wrapWith: (
+        <ContextualHelpButton
+          className={styles.action}
+          color={buttonColor}
+          isDisabled={isDisabled}
+        />
+      ),
+    },
   };
 
   return (
@@ -101,11 +120,13 @@ export const Badge = flowComponent("Badge", (props) => {
           </Button>
         )}
 
+        <UiComponentTunnelExit id={contextualHelpTunnel.id} component="Badge" />
+
         {onClose && (
           <Button
             className={styles.close}
             size="s"
-            color={isAlphaColor(color) ? color : "dark"}
+            color={buttonColor}
             variant="plain"
             onPress={onClose}
             isDisabled={isDisabled}

packages/components/src/components/Badge/components/ContextualHelpButton/ContextualHelpButton.tsx

@@ -0,0 +1,33 @@
+import type { FC, PropsWithChildren } from "react";
+import type { AlphaColor, PropsWithClassName } from "@/lib/types/props";
+import ButtonView from "@/views/ButtonView";
+import ContextualHelpTriggerView from "@/views/ContextualHelpTriggerView";
+
+interface Props extends PropsWithChildren, PropsWithClassName {
+  color: AlphaColor;
+  isDisabled?: boolean;
+}
+
+/**
+ * Supplies the trigger button for a contextual help placed in a badge, so the
+ * consumer only writes the <ContextualHelp>. Icon and accessibility label come
+ * from the trigger.
+ */
+export const ContextualHelpButton: FC<Props> = (props) => {
+  const { className, color, isDisabled, children } = props;
+
+  return (
+    <ContextualHelpTriggerView>
+      <ButtonView
+        className={className}
+        color={color}
+        variant="plain"
+        size="s"
+        isDisabled={isDisabled}
+      />
+      {children}
+    </ContextualHelpTriggerView>
+  );
+};
+
+export default ContextualHelpButton;

packages/components/src/components/Badge/components/ContextualHelpButton/index.ts

@@ -0,0 +1,2 @@
+export { ContextualHelpButton } from "./ContextualHelpButton";
+export { default } from "./ContextualHelpButton";

packages/components/src/components/Badge/stories/Default.stories.tsx

@@ -7,6 +7,7 @@ import { ContextMenu } from "@/components/ContextMenu";
 import MenuItem from "@/components/MenuItem";
 import { useOverlayController } from "@/lib/controller";
 import { StoryBackground } from "@/lib/dev/StoryBackground";
+import { ContextualHelp } from "@/components/ContextualHelp";
 
 const meta: Meta<typeof Badge> = {
   title: "Status/Badge",
@@ -66,6 +67,20 @@ export const WithActions: Story = {
   ),
 };
 
+export const WithContextualHelp: Story = {
+  render: (props, context) => (
+    <StoryBackground color={props.color} theme={context.globals.theme}>
+      <Badge {...props}>
+        <Label>Scope</Label>
+        <Text>Value</Text>
+        <ContextualHelp>
+          <Text>Every value has a story to tell.</Text>
+        </ContextualHelp>
+      </Badge>
+    </StoryBackground>
+  ),
+};
+
 export const WithContextMenu: Story = {
   render: (props, context) => {
     const controller = useOverlayController("ContextMenu");

packages/remote-react-components/src/tests/visual/Badge.browser.test.tsx

@@ -25,8 +25,14 @@ test.each(testEnvironments)(
   async ({
     testScreenshot,
     render,
-    components: { Badge, Flex, Label, Text, Wrap, AccentBox },
+    components: { AccentBox, Badge, ContextualHelp, Flex, Label, Text, Wrap },
   }) => {
+    const contextualHelp = (
+      <ContextualHelp>
+        <Text>Every value has a story to tell.</Text>
+      </ContextualHelp>
+    );
+
     await render(
       <Flex direction="column" gap="m">
         {colors.map((color) => (
@@ -52,6 +58,14 @@ test.each(testEnvironments)(
                   <Label>Scope</Label>
                   <Text>Value</Text>
                 </Badge>
+                <Badge color={color}>
+                  Value
+                  {contextualHelp}
+                </Badge>
+                <Badge color={color} onClose={() => console.log("onClose")}>
+                  Value
+                  {contextualHelp}
+                </Badge>
               </Flex>
             </AccentBox>
           </Wrap>