[DST-537]: Revising Tooltip page (#4144)

* Start revising tooltip page

* Adding appearance table

* dos and donts

* Adding dos and donts

* Chaning heading

* Adding one more section

* Making the focus-tooltip example more relevant

* Revising examples

* Adding alternative component

* resolving comments

* Resolving messages

* Resolving messages

* Resolving comments

* Adding some missing to description to props

* Deleting controlled tooltip section

* delete unwanted file

* Change heading

* Deleting dont

* Resolving comments

* Resolving comments

* Adding more precise description

* 😃

* Remove unwanted section

* Make the example more meaningfull

docs/content/components/overlay/tooltip/tooltip-appearance.demo.tsx

@@ -0,0 +1,11 @@
+import { Button, Tooltip } from '@marigold/components';
+import { Info } from '@marigold/icons';
+
+export default () => (
+  <Tooltip.Trigger>
+    <Button>
+      <Info color="text-info" />
+    </Button>
+    <Tooltip>Tooltip</Tooltip>
+  </Tooltip.Trigger>
+);

docs/content/components/overlay/tooltip/tooltip-focus.demo.tsx

@@ -2,7 +2,9 @@ import { Button, Tooltip } from '@marigold/components';
 
 export default () => (
   <Tooltip.Trigger trigger="focus">
-    <Button>Hover me!</Button>
-    <Tooltip>Tooltip</Tooltip>
+    <Button>Check Availability</Button>
+    <Tooltip>
+      View available seats for this event before proceeding with your booking.
+    </Tooltip>
   </Tooltip.Trigger>
 );

docs/content/components/overlay/tooltip/tooltip-custom.demo.tsx → docs/content/components/overlay/tooltip/tooltip-placement.demo.tsx

@@ -2,7 +2,7 @@ import { Button, Tooltip } from '@marigold/components';
 
 export default () => (
   <Tooltip.Trigger>
-    <Button>Hover me!</Button>
-    <Tooltip placement="right">Tooltip</Tooltip>
+    <Button>Edit Ticket</Button>
+    <Tooltip placement="right">Make changes to the ticket details.</Tooltip>
   </Tooltip.Trigger>
 );

docs/content/components/overlay/tooltip/tooltip.mdx

@@ -1,54 +1,84 @@
 ---
 title: Tooltip
 caption: Component for displaying short information.
+badge: updated
 ---
 
-The `<Tooltip>` components allows to provide additional information to that user. For that the `<Tooltip>` is divided into a `<Tooltip.Trigger>` and the `<Tooltip>` itself. You need to wrap the trigger around the `<Tooltip>` and a simple button, which is necessary for handle actions.
+The `<Tooltip>` components allow to provide additional description or explanation to the user. For that the `<Tooltip>` is divided into a `<Tooltip.Trigger>` and the `<Tooltip>` itself. You need to wrap the trigger around the `<Tooltip>` and a simple button, which is necessary to trigger open and closing the tooltip.
 
-You should use the `<Tooltip>` if you want to show helpful, short information to the user.
+You should use the `<Tooltip>` to display brief, helpful information that provides additional context or guidance without overwhelming the user.
 
-## Import
+## Anatomy
 
-```tsx
-import { Tooltip } from '@marigold/components';
-```
+<Image
+  src="/tooltip/tooltip-anatomy.jpg"
+  alt="Anatomy of tooltip"
+  width={800}
+  height={550}
+  className="mx-auto block"
+/>
 
-## Appearance
-
-<AppearanceTable component={title} />
+- **Trigger:** Indicator that can be activated on hover or focus.
 
-## Props
-
-### Tooltip
+- **Caret tip:** Closely associates the tooltip to term to be defined.
 
-<PropsTable component={title} />
+- **Tooltip:** Holds the informative text or message.
 
-### Tooltip.Trigger
+## Appearance
 
-<PropsTable component="TooltipTrigger" />
+<AppearanceDemo component={title} />
 
-## Examples
+<AppearanceTable component={title} />
 
-### Default Tooltip
+## Usage
 
-Here you can see a simple `<Tooltip>` use case. You can hover or tab the button to see the tooltip message.
+When using tooltips, it's essential to strike the right balance. While tooltips can provide valuable information or guidance, overloading a page with too many can confuse or overwhelm users. Focus on placing tooltips only on elements where users commonly struggle or need extra help. Limiting the number of tooltips (2-4 at most per page) ensures they remain effective and don't detract from the overall user experience.
 
-<ComponentDemo file="./tooltip-basic.demo.tsx" />
+<Dont>
+  <Dont.Description>Don't user more than 4 tooltips per page.</Dont.Description>
+</Dont>
 
 ### Tooltip with custom placement
 
+Tooltips can appear above, below, and to each side of the UI element depending on screen real estate and intent.
+
 In this example the placement of the `<Tooltip>` is set to the right. By default it is set to the top. If there isn't enough space for the placement it moves to the bottom.
 
-<ComponentDemo file="./tooltip-custom.demo.tsx" />
+<ComponentDemo file="./tooltip-placement.demo.tsx" />
+
+### Interactions with tooltips
+
+Tooltips should provide clear, concise information without including interactive elements. Focus on delivering helpful content that enhances the user experience without requiring additional actions from the user. Simplicity is key to ensuring that tooltips serve their purpose effectively.
+
+<Dont>
+  <Dont.Figure>
+    <Image
+      width={700}
+      height={700}
+      unoptimized
+      src="/tooltip/tooltip-dont-link.jpg"
+      alt="Don't use interactive elements within a tooltip."
+    />
+  </Dont.Figure>
+  <Dont.Description>
+    Don't use interactive elements within a tooltip.
+  </Dont.Description>
+</Dont>
 
 ### Tooltip only shows when focused
 
 You can use the property `trigger` to the `<Tooltip.Trigger>` and setting it to `focus`. With that you can't hover it anymore, you have to tab in with the keyboard.
 
 <ComponentDemo file="./tooltip-focus.demo.tsx" />
 
-### Controlled Tooltip
+## Props
+
+<StorybookHintMessage component={title} />
 
-The open state of the tooltip can be controlled via the `open` and `onOpenChange` props.
+### Tooltip
 
-<ComponentDemo file="./tooltip-pressed.demo.tsx" />
+<PropsTable component={title} />
+
+### Tooltip.Trigger
+
+<PropsTable component="TooltipTrigger" />

packages/components/src/Tooltip/TooltipTrigger.tsx

@@ -1,10 +1,21 @@
+import { ReactNode } from 'react';
 import { TooltipTrigger } from 'react-aria-components';
 import type RAC from 'react-aria-components';
 
-type RemovedProps = 'isDisabled' | 'isOpen';
+type RemovedProps = 'isDisabled' | 'isOpen' | 'children';
 export interface TooltipTriggerProps
   extends Omit<RAC.TooltipTriggerComponentProps, RemovedProps> {
+  /**
+   * The children of the component.
+   */
+  children: ReactNode;
+  /**
+   * Whether the tooltip should be disabled, independent from the trigger.
+   */
   disabled?: RAC.TooltipTriggerComponentProps['isDisabled'];
+  /**
+   * Control the visibility of the tooltip.
+   */
   open?: boolean;
 }