[DST-518]: Revise "menu" Page (#4124)

* Adding anatomy section

* Adding anatomy slots

* adding appearance example

* Adding usage section

* Adding dos

* revise examples

* revise  section example

* Revising more examples

* Adding changeset

* enhance description

* Resolving comments

* remove unwanted description

* Resolving comments

* Edit image

* Edit image

* Edit anatomy

* Change order

* Edit anatomy image

* Resolving comments

* enhance menu section usage example "Adding more description"

* Edit anatomy picture

* make the anatomy pic bigger

* Enhance multiselect example

* Adding more sections

* Add more explanation for meni item opens dialog section example

* Fixing typo

.changeset/afraid-donuts-search.md

@@ -0,0 +1,5 @@
+---
+'@marigold/docs': patch
+---
+
+[DST-518]: Revise "Menu" Page

docs/content/components/overlay/menu/menu-action-table.demo.tsx

@@ -0,0 +1,78 @@
+import { useState } from 'react';
+import { ActionMenu, Menu, Table } from '@marigold/components';
+
+const rows = [
+  {
+    ticketId: 'TCK-001',
+    eventName: 'Champions League Final',
+    status: 'Confirmed',
+  },
+  {
+    ticketId: 'TCK-002',
+    eventName: 'Rock Concert',
+    status: 'Pending',
+  },
+  {
+    ticketId: 'TCK-003',
+    eventName: 'Broadway Show',
+    status: 'Cancelled',
+  },
+];
+
+interface Ticket {
+  ticketId: string;
+  eventName: string;
+  status: 'Cancelled' | 'Pending' | 'Confirmed';
+}
+
+export default () => {
+  const [tickets, setTickets] = useState(rows);
+
+  const handleViewDetails = (ticket: Ticket) => {
+    alert(
+      `Ticket ID: ${ticket.ticketId}\nEvent: ${ticket.eventName}\nStatus: ${ticket.status}`
+    );
+  };
+
+  return (
+    <Table aria-label="Data Table" size="compact" variant="linedTable" stretch>
+      <Table.Header>
+        <Table.Column>ID</Table.Column>
+        <Table.Column>Event Name</Table.Column>
+        <Table.Column>Status</Table.Column>
+        <Table.Column>Action</Table.Column>
+      </Table.Header>
+      <Table.Body items={rows}>
+        {tickets.map((ticket: Ticket) => (
+          <Table.Row key={ticket.ticketId}>
+            <Table.Cell>{ticket.ticketId}</Table.Cell>
+            <Table.Cell>{ticket.eventName}</Table.Cell>
+            <Table.Cell>{ticket.status}</Table.Cell>
+            <Table.Cell>
+              <ActionMenu>
+                <Menu.Item
+                  onAction={() => handleViewDetails(ticket)}
+                  id="view-details"
+                >
+                  View Details
+                </Menu.Item>
+                <Menu.Item
+                  onAction={() =>
+                    setTickets(
+                      tickets.filter(
+                        ticketItem => ticketItem.ticketId !== ticket.ticketId
+                      )
+                    )
+                  }
+                  id="delete"
+                >
+                  Delete
+                </Menu.Item>
+              </ActionMenu>
+            </Table.Cell>
+          </Table.Row>
+        ))}
+      </Table.Body>
+    </Table>
+  );
+};

docs/content/components/overlay/menu/menu-action.demo.tsx

@@ -3,7 +3,7 @@ import { Menu } from '@marigold/components';
 
 export default () => {
   return (
-    <Menu label="Choose" onAction={action => alert(`Your action: ${action}`)}>
+    <Menu label="Actions" onAction={action => alert(`Your action: ${action}`)}>
       <Menu.Item id="edit">Open in editor</Menu.Item>
       <Menu.Item id="settings">Settings</Menu.Item>
       <Menu.Item id="delete">Delete</Menu.Item>

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

@@ -0,0 +1,14 @@
+import { Menu } from '@marigold/components';
+
+export default () => {
+  return (
+    <Menu
+      label="Ticket Options"
+      onAction={action => alert(`Action: ${action}`)}
+    >
+      <Menu.Item id="view">View Ticket Details</Menu.Item>
+      <Menu.Item id="transfer">Transfer Ticket</Menu.Item>
+      <Menu.Item id="refund">Request Refund</Menu.Item>
+    </Menu>
+  );
+};

docs/content/components/overlay/menu/menu-disabled.demo.tsx

@@ -1,12 +1,13 @@
+import React from 'react';
 import { Menu } from '@marigold/components';
 
 export default () => {
   return (
-    <Menu label="Choose" disabledKeys={['salad', 'pizza']}>
-      <Menu.Item id="burger">🍔 Burger</Menu.Item>
-      <Menu.Item id="pizza">🍕 Pizza</Menu.Item>
-      <Menu.Item id="salad">🥗 Salad</Menu.Item>
-      <Menu.Item id="fries">🍟 Fries</Menu.Item>
+    <Menu label="Ticket Options" disabledKeys={['upgrade', 'resell']}>
+      <Menu.Item id="view">👁️ View Ticket Details</Menu.Item>
+      <Menu.Item id="download">📥 Download Ticket</Menu.Item>
+      <Menu.Item id="upgrade">⬆️ Upgrade Seat</Menu.Item>
+      <Menu.Item id="resell">💸 Resell Ticket</Menu.Item>
     </Menu>
   );
 };

docs/content/components/overlay/menu/menu-section.demo.tsx

@@ -1,17 +1,18 @@
+import React from 'react';
 import { Menu } from '@marigold/components';
 
 export default () => {
   return (
-    <Menu label="Open Menu">
-      <Menu.Section title="Food">
-        <Menu.Item id="burger">🍔 Burger</Menu.Item>
-        <Menu.Item id="pizza">🍕 Pizza</Menu.Item>
-        <Menu.Item id="fries">🍟 Fries</Menu.Item>
+    <Menu label="Ticket Services">
+      <Menu.Section title="Game Day">
+        <Menu.Item id="match_info">📅 View Match Information</Menu.Item>
+        <Menu.Item id="stadium_guide">🏟️ Stadium Guide</Menu.Item>
+        <Menu.Item id="fan_zone">🎉 Fan Zone Activities</Menu.Item>
       </Menu.Section>
-      <Menu.Section title="Fruits">
-        <Menu.Item id="apple">🍎 Apple</Menu.Item>
-        <Menu.Item id="banana">🍌 Banana</Menu.Item>
-        <Menu.Item id="strawberry">🍓 Strawberry</Menu.Item>
+      <Menu.Section title="Support">
+        <Menu.Item id="customer_support">📞 Contact Support</Menu.Item>
+        <Menu.Item id="faq">❓ View FAQs</Menu.Item>
+        <Menu.Item id="feedback">💬 Provide Feedback</Menu.Item>
       </Menu.Section>
     </Menu>
   );

docs/content/components/overlay/menu/menu-selection.demo.tsx

@@ -1,16 +1,22 @@
+import React, { useState } from 'react';
 import { Menu } from '@marigold/components';
 
 export default () => {
+  const [preferences, setPreferences] = useState(['newsletter']);
   return (
-    <Menu
-      label="Hogwarts Houses"
-      selectionMode="single"
-      selectedKeys={['gryffindor']}
-    >
-      <Menu.Item id="gryffindor">🦁 Gryffindor</Menu.Item>
-      <Menu.Item id="hufflepuff">🦡 Hufflepuff</Menu.Item>
-      <Menu.Item id="ravenclaw">🐦‍⬛ Ravenclaw</Menu.Item>
-      <Menu.Item id="slytherin">🐍 Slytherin</Menu.Item>
-    </Menu>
+    <>
+      <Menu
+        label="Select Your Preference"
+        selectionMode="multiple"
+        selectedKeys={preferences}
+        onSelectionChange={setPreferences as (keys: any) => void}
+      >
+        <Menu.Item id="newsletter">📧 Subscribe to Newsletter</Menu.Item>
+        <Menu.Item id="offers">💸 Receive Special Offers</Menu.Item>
+        <Menu.Item id="updates">🔔 Get Product Updates</Menu.Item>
+        <Menu.Item id="events">🎉 Event Invitations</Menu.Item>
+      </Menu>{' '}
+      <pre>Your preferences are : {[...preferences].join(', ')}</pre>
+    </>
   );
 };

docs/content/components/overlay/menu/menu.mdx

@@ -1,51 +1,71 @@
 ---
 title: Menu
-caption: Component for building a menu.
+caption: Flexible component for constructing dynamic and customizable menus.
+badge: updated
 ---
 
 The `<Menu>` component allows you to define a menu element. It's useful when you want a list with options or actions.
 
-It is structured in two parts `<Menu>` and `<Menu.Item>`. The `<Menu>` now contains the trigger and the button per default. You also can use the `<Menu.Section>` which you can use to separate the menu items from each other.
-
-If you want create a variant, you can style different parts of the `<Menu>` separate, there is the `container`, `section` and `item` part.
+It is structured in two parts `<Menu>` and `<Menu.Item>`. The `<Menu>` contains the trigger and the button per default. You also can use the `<Menu.Section>` which you can use to separate the menu items from each other.
 
 There is also a companion component called `<ActionMenu>` which you can use if you want to take some actions. You can have a look on how it works in the examples. It works quiet similar to the normal `<Menu>` component. All you have to add are the `<Menu.Item>`s.
 
-## Import
+## Anatomy
 
-```tsx
-import { Menu } from '@marigold/components';
-```
+<Image
+  src="/menu/menu-anatomy.jpg"
+  alt="Anatomy of menu"
+  width={800}
+  height={550}
+  className="mx-auto block"
+/>
 
-## Apperance
+- **Menu trigger:** The element, such as a button or icon, that opens or activates the menu.
 
-<AppearanceTable component={title} />
+- **Section:** Menus are made up of a section or multiple sections.
 
-## Props
+- **Section header:** Contains a heading to name a section of a group of similar menu items.
 
-### Menu
+- **Menu item:** Represent an individual option or action within a Menu component.
 
-<PropsTable component={title} />
+## Appearance
 
-### Menu.Item
+<AppearanceDemo component={title} />
 
-<PropsTable component="MenuItem" />
+<AppearanceTable component={title} />
 
-### Menu.Section
+## Usage
 
-<PropsTable component="MenuSection" />
+In general, Menus are used to hide less frequently used or advanced options until users specifically need them. This keeps the interface clean and focused on essential elements.
+
+Menus are ideal for interactive UI elements, it is distincit from `<Select>`, which is meant for form inputs and value selection.
+
+Menus can speed up interactions for advanced users who are already familiar with the application. These users often rely on shortcuts and context-specific actions to work more efficiently.
 
-## Examples
+<GuidelineTiles>
+  <Do>
+    <Do.Description>
+      Write menu label that is clear, concise (max. 24 characters) and avoid
+      unnecessary verbs.
+    </Do.Description>
+  </Do>
+  <Do>
+    <Do.Description>
+      Organise your menu items based on priority, and put the most used items at
+      the start of the menu.
+    </Do.Description>
+  </Do>
+</GuidelineTiles>
 
 ### Simple Menu with Action
 
-In this example you can see a simple `<Menu>` with some items to select. After selection an action can be applied.
+In this example you can see a simple `<Menu>` with some items to select. it is used when you need a to provide users with a set of of options that will result in a specific action being performed.
 
 <ComponentDemo file="./menu-action.demo.tsx" />
 
 ### Menu with Sections
 
-To group related MenuItems, you can use `<Menu.Section>` and pass `title` for the group name.
+When you have mutliple menu items that can be categorized under different headings. This is particularly useful in complext menus with many options, you can use `<Menu.Section>` and pass `title` for the group name.
 
 <ComponentDemo file="./menu-section.demo.tsx" />
 
@@ -57,13 +77,15 @@ In this example the `<Menu>` has set its prop `disabeldKeys`. So you can't inter
 
 ### ActionMenu
 
-In this example, an `Icon` has been inserted into the `Button` to serve as a kebab menu.
-As shown here, any type of icon can be used within the menu and there are no restrictions.
-It is very similar to the normal `<Menu>` component.
+The `<ActionMenu>` is typically used to provide quick, context-specific actions related to an item or interface element. It is particularly useful in scenarios where speed and efficiency in selecting an action are crucial.
 
-<ComponentDemo file="./kebab-menu.demo.tsx" />
+In this example, the `<ActionMenu>` is used within a table to allow users to perform actions like viewing details of a ticket or deleting a ticket. When "View Details" is selected, a dialog displays key information about the selected ticket, including its ID, event name, and status. The "Delete" option removes the ticket from the list.
 
-### Menu with onOpenChange property
+The example shows that the `<ActionMenu>` is very similar to the standard `<Menu>` component, offering flexibility and ease of use in various contexts.
+
+<ComponentDemo file="./menu-action-table.demo.tsx" />
+
+### Menu with `onOpenChange` property
 
 Here you can see how the properties `open` and `onOpenChange` are used together with a `<Button>`. A function handles the state for the menu. You just can open the `<Menu>` with the external `<Button>` component, not with the menu button.
 A common use Case is also to open the `<Menu>` with the keyboard.
@@ -72,12 +94,30 @@ A common use Case is also to open the `<Menu>` with the keyboard.
 
 ### Menu item opens Dialog
 
-This Example shows how to open a [`<Dialog>`](/components/dialog/) from a `<Menu.Item>`.
+This Example shows how to open a [`<Dialog>`](/components/dialog/) from a `<Menu.Item>`. It is useful when a menu action requires additional user input or confirmation. Selecting the item opens a `Dialog` where users can provide the necessary information or confirm their choice, making the interaction smooth and efficient.
 
 <ComponentDemo file="./menu-open-dialog.demo.tsx" />
 
 ### Menu selection mode
 
-Here you can see how the `selectionMode` from `<Menu>` works. In this example the `selectionMode` is set to `single`. If you open the items you can see a selected item.
+Use `multiple` selection mode when you want to allow users to select multiple options at once, providing flexibility in situations where multiple choices are valid and necessary.
+
+Here you can see how the `selectionMode` from `<Menu>` works. In this example the `selectionMode` is set to `multiple`. If you open the items you can see a selected item.
 
 <ComponentDemo file="./menu-selection.demo.tsx" />
+
+## Props
+
+<StorybookHintMessage component={title} />
+
+### Menu
+
+<PropsTable component={title} />
+
+### Menu.Item
+
+<PropsTable component="MenuItem" />
+
+### Menu.Section
+
+<PropsTable component="MenuSection" />