@jobber/components 7.12.0 → 7.12.1

package/dist/docs/Menu/Menu.md

@@ -212,12 +212,13 @@ Minimum menu item height:
   [Combobox](../Combobox/Combobox.md)
 
 
-## Composable Version (Web Only)
+## Composable Version
 
-The Menu may be invoked with a subcomponent structure enabling a declarative
-style, greater customization and composability with other components.
+The composable API is the preferred way to build Menus. It supports a
+declarative structure, richer customization, and adapts automatically between a
+desktop dropdown and a small-screen bottom sheet.
 
-```
+```tsx
 <Menu>
   <Menu.Trigger>
     <Button>Trigger</Button>
@@ -228,18 +229,10 @@ style, greater customization and composability with other components.
       <Menu.ItemIcon name="email" />
     </Menu.Item>
 
-    <PrivacyMask>
-      <Menu.Item onClick={clickHandler("sensitive")} textValue="Sensitive">
-        <Menu.ItemLabel>Sensitive</Menu.ItemLabel>
-      </Menu.Item>
-    </PrivacyMask>
-
-    <AuthCheck can="viewAdmin">
-      <Menu.Item onClick={clickHandler("admin")} textValue="Admin">
-        <Menu.ItemLabel>Admin</Menu.ItemLabel>
-        <Menu.ItemIcon name="lock" />
-      </Menu.Item>
-    </AuthCheck>
+    <Menu.Item onClick={clickHandler("text")} textValue="Text message">
+      <Menu.ItemLabel>Text message</Menu.ItemLabel>
+      <Menu.ItemIcon name="sms" />
+    </Menu.Item>
   </Menu.Content>
 </Menu>
 ```
@@ -248,210 +241,195 @@ style, greater customization and composability with other components.
 
 ***Menu.Trigger (Required)***
 
-An interactive element that will cause the Menu to open when clicked or
-interacted with via keyboard. The open behavior is handled internally, and no
-`onClick` is required on the provided component. A provided `Button` is purely
-for appearance, however there is still a requirement that whatever is given to
-Menu.Trigger must be an element with an interactive role.
-
-Clicking the trigger again, or clicking anywhere outside the Menu at all will
-close the Menu.
-
-> **NOTICE:** To achieve a full-width Trigger, such as a Button please use UNSAFE\_style or
-> UNSAFE\_className to set the desired display. See example below.
+An interactive element that opens the Menu when clicked, tapped, or activated
+with the keyboard. `Menu.Trigger` handles opening and closing the Menu, so the
+trigger content itself does not need its own `onClick` to open it.
 
-```
-<Menu.Trigger UNSAFE_style={{ display: "block" }}>
-  <Button fullWidth />
-</Menu.Trigger>
-```
+`Menu.Trigger` can render a default Atlantis trigger from simple content, accept
+custom children such as a `Button` or `Chip`, or use a `render` prop when you
+need full control over the trigger element. Whatever you provide must still be
+interactive and accessible.
 
 ***Menu.Content (Required)***
 
-A structural container element for the Menu's content which should consist of
-one or more `Menu.Item`s, and optional additional content.
+A structural container for menu content. It typically contains one or more
+`Menu.Item`s and optional grouping or separation elements such as `Menu.Group`,
+`Menu.GroupLabel`, and `Menu.Separator`.
+
+Use `preferredPlacement` to influence desktop dropdown placement when needed.
 
 ***Menu.Item (Strongly recommended)***
 
-The interactive, main element of a Menu.
+The primary interactive row in a Menu.
 
-Each item must be provided an `onClick`, or a `href`\*. Provide a `textValue`
-for accessibility and type‑ahead behavior.
+Each item should provide an `onClick` or an `href`. Provide `textValue` when the
+visible content is abbreviated, custom, or otherwise not ideal for type-ahead
+matching.
 
-Menu Items support default subcomponents that plug into the Menu grid:
+`Menu.Item` supports:
 
-* **Menu.ItemLabel**: Renders the action label within a Typography (span)
-  component. You MUST supply either a string or a fragment/utility component
-  that renders down to a raw string (e.g. translation helpers). Responds to the
-  `destructive` variation Menu.Item prop.
-* **Menu.ItemIcon**: Renders a leading icon with consistent sizing and spacing.
-  Responds to the `destructive` variation Menu.Item prop.
+* `variation="destructive"` for destructive actions
+* `closeOnClick` to control whether the Menu closes after selection
+* `href`, `target`, and `rel` for link-style items
 
-These defaults are placed in a strict order and align automatically via the
-Menu's parent grid (see “Layout and spacing” below). Using them is the easiest
-way to get correct spacing and alignment.
+Default item subcomponents plug into the shared menu row layout:
 
-If it is necessary to also adjust the *styles of the container*, `UNSAFE` props
-apply to the *container* element. No access is provided to internal markup due
-to accessibility and behavior requirements.
+* `Menu.ItemLabel`: Renders the primary label text.
+* `Menu.ItemIcon`: Renders a leading icon.
+* `Menu.ItemPrefix`: Renders custom leading content.
+* `Menu.ItemSuffix`: Renders custom trailing content.
 
-\*If being used for client side navigation such as TanStack Router, please
-consult with us first.
+Use the built-in item pieces when possible. They align automatically across the
+menu and respond to shared row styling such as destructive state.
 
-***Menu.Section (Optional)***
+If it is necessary to also adjust the *styles of the container*, style props
+apply to the *container* element. No access is provided to internal markup due
+to accessibility and behavior requirements.
 
-A structural/conceptual element to group your related Items together. Provides
-some default spacing that can be overriden with `UNSAFE`.
+***Menu.Group (Optional)***
 
-***Menu.Header (Optional)***
+A structural grouping element for related menu items. Use it to create scannable
+sections or apply an `ariaLabel` to a related set of actions.
 
-A presentational element primarily used to describe a group/section.
+***Menu.GroupLabel (Optional)***
 
-For convenience it includes **Menu.HeaderLabel**, the default way to render
-header text with our standard menu heading typography.
+A presentational label for a `Menu.Group`. Use it to describe the category of
+actions in that group. Prefer `Menu.GroupLabel` over custom text styling so
+group headings stay consistent across menus.
 
 ***Menu.Separator (Optional)***
 
-A presentational element primarily used to create visual separation between the
-groups. Can be used with sections, or with a "flat" Menu.
-
-Comes with a default appearance that can be overriden with `UNSAFE`.
+A visual divider used to separate groups of items or distinct sections of
+content.
 
-### Layout and spacing (subgrid)
+***Menu.RadioGroup and Menu.RadioItem (Optional)***
 
-The Menu uses CSS Grid with `subgrid` on `Menu.Content` to control alignment
-across all rows. This allows us to reserve a leading column for icons only when
-**any item** includes an icon:
+Use radio items for persistent single-select choices such as a view mode,
+sorting option, or filter state.
 
-* If at least one `Menu.Item` uses `Menu.ItemIcon`, the grid creates and aligns
-  a leading icon column for every item.
-* If no items include `Menu.ItemIcon`, the grid collapses that column and all
-  labels move flush left.
+Radio menus remain open by default after selection. Use `closeOnClick` on a
+`Menu.RadioItem` if your experience should close after choosing an option.
 
-This behavior is why the order of the default subcomponents is predetermined and
-why mixing defaults with custom elements can produce unexpected results. This
-also means that the order of the provided default `Menu.ItemLabel` and
-`Menu.ItemIcon` in the JSX is incosequential. They will be placed where they
-belong irrespective of the order.
-
-### Custom content (advanced)
-
-When you need full control over an item's inner content, do not use the default
-subcomponents. There are two recommended approaches depending on scope:
+```tsx
+<Menu.RadioGroup defaultValue="list">
+  <Menu.RadioItem value="list" textValue="List view">
+    <Menu.ItemLabel>List view</Menu.ItemLabel>
+  </Menu.RadioItem>
+  <Menu.RadioItem value="board" textValue="Board view">
+    <Menu.ItemLabel>Board view</Menu.ItemLabel>
+  </Menu.RadioItem>
+</Menu.RadioGroup>
+```
 
-1. Per‑item custom layout (easiest)
+***Menu.Submenu, Menu.SubmenuTrigger, and Menu.SubmenuContent (Optional)***
 
-* Use a text component such as `Typography` directly instead of
-  `Menu.ItemLabel`.
-* Use `Icon` directly instead of `Menu.ItemIcon` (e.g., to place an icon on the
-  right).
-* Apply your layout to the item container using `UNSAFE_style` or
-  `UNSAFE_className`. A simple, high‑success recipe is flex:
+Use submenus when a related set of actions is better surfaced one level deeper.
+On desktop, submenus open adjacent to the parent menu. On small screens, they
+drill into a nested bottom-sheet view.
 
-```
-<Menu.Item
-  textValue="Email"
-  UNSAFE_style={{
-    display: 'flex',
-    alignItems: 'center',
-    justifyContent: 'space-between',
-    gap: 'var(--space-small)'
-  }}
->
-  <Typography element="span" fontWeight="semiBold">Email</Typography>
-  <StatusIndicator status="critical" />
-</Menu.Item>
-```
+Provide a `textValue` on `Menu.SubmenuTrigger` when the submenu label should be
+explicitly defined for typeahead behavior or the small-screen drill-down title.
 
-This breaks the item out of the subgrid layout and lets you arrange content as
-desired.
+### Deprecated wrappers
 
-2. Whole‑menu custom layout (advanced)
+Older Menu code may use `Menu.Section`, `Menu.Header`, and `Menu.HeaderLabel`.
+These wrappers still work for backward compatibility, but new code should use
+`Menu.Group` and `Menu.GroupLabel` instead:
 
-If every item is custom, override the grid on `Menu.Content` and provide your
-own columns. For example, a simple single‑column stack:
+* `Menu.Group` replaces `Menu.Section` as the grouping container.
+* `Menu.GroupLabel` replaces `Menu.Header` as the group heading.
+* Do not use `Menu.HeaderLabel` in new code. Put the heading content directly
+  inside `Menu.GroupLabel`.
 
-```
-<Menu.Content UNSAFE_style={{ display: 'grid', gridTemplateColumns: '1fr' }}>
-  {/* all items use custom content; avoid Menu.ItemLabel/Menu.ItemIcon */}
-</Menu.Content>
+```tsx
+<Menu.Group>
+  <Menu.GroupLabel>Sharing</Menu.GroupLabel>
+  <Menu.Item onClick={clickHandler("email")} textValue="Email">
+    <Menu.ItemLabel>Email</Menu.ItemLabel>
+  </Menu.Item>
+</Menu.Group>
 ```
 
-Notes and caveats
+## Layout and spacing
 
-> **WARNING:** Avoid mixing default subcomponents with custom content within the same item or
-> even menu. The parent grid reserves space based on the presence of default
-> elements and can lead to unexpected spacing or alignment when combined with
-> custom layouts.
->
-> Also remember the mobile bottom‑sheet presentation has different dimensions;
-> test custom layouts on small screens.
+Composable menu rows use a shared grid/subgrid model so labels, icons, prefixes,
+suffixes, radio indicators, and submenu chevrons align consistently across rows.
 
-## Data Hierarchy Version
+If at least one item uses a built-in leading slot such as `Menu.ItemIcon` or
+`Menu.ItemPrefix`, the layout reserves leading space across the menu. If no
+items use a built-in leading slot, the label column shifts flush left.
 
-```
-<Menu
-    items={[
-      {
-        actions: [
-          {
-            label: "Edit",
-            icon: "edit",
-            onClick: () => {
-              alert("✏️");
-            },
-          },
-        ],
-      },
-      {
-        header: "Send as...",
-        actions: [
-          {
-            label: "Text message",
-            icon: "sms",
-            onClick: () => {
-              alert("📱");
-            },
-          },
-          {
-            label: "Email",
-            icon: "email",
-            onClick: () => {
-              alert("📨");
-            },
-          },
-        ],
-      },
-    ]}
-  />
-```
+This is why built-in item slots are the easiest way to get correct alignment and
+spacing.
+
+## Custom content (advanced)
 
-### Component customization
+Prefer the built-in Menu item pieces whenever possible. They provide the most
+consistent alignment and behavior across menus.
 
-### UNSAFE\_ props (advanced usage)
+Custom item layouts are an escape hatch for exceptional cases, not a preferred
+authoring pattern.
 
-General information for using `UNSAFE_` props can be found
-[here](../customizing-components/customizing-components.md).
+> **WARNING:** Avoid mixing built-in slots with unrelated custom layout patterns unless you
+> have tested carefully. The shared grid reserves space based on the presence of
+> built-in slot content, which can lead to unexpected spacing or alignment. Also
+> test custom layouts on small screens, where the Menu is presented in a bottom
+> sheet.
 
-**Note**: Use of `UNSAFE_` props is **at your own risk** and should be
-considered a **last resort**. Future Menu updates may lead to unintended
-breakages.
+## Component customization
 
-Menu has multiple elements that can be targeted with classes or styles:
+For the composable API, prefer `style` and `className` on the specific Menu
+piece you are customizing.
 
-* `menu`: The actual menu element containing the actions
-* `header`: The container for each section
-* `action`: The container for each individual action
+* Use `Menu.Trigger` to style the trigger wrapper.
+* Use `Menu.Content` to control the menu panel.
+* Use `Menu.Group`, `Menu.GroupLabel`, `Menu.Item`, and related subcomponents to
+  style individual structural pieces.
 
-#### UNSAFE\_className (web)
+Deprecated `UNSAFE_*` props still exist for backward compatibility, but should
+not be used in new code.
 
-Use `UNSAFE_className` to apply custom classes to the Menu. This can be useful
-for applying styles via CSS Modules.
+## Deprecated: `items` API
 
-#### UNSAFE\_style (web)
+The `items` API still exists for backward compatibility, but it is deprecated
+and should not be used for new implementations.
 
-The `UNSAFE_style` prop provides granular control over the Menu's appearance
-through inline styles.
+```tsx
+<Menu
+  items={[
+    {
+      actions: [
+        {
+          label: "Edit",
+          icon: "edit",
+          onClick: () => {
+            alert("edit");
+          },
+        },
+      ],
+    },
+    {
+      header: "Send as...",
+      actions: [
+        {
+          label: "Text message",
+          icon: "sms",
+          onClick: () => {
+            alert("text");
+          },
+        },
+        {
+          label: "Email",
+          icon: "email",
+          onClick: () => {
+            alert("email");
+          },
+        },
+      ],
+    },
+  ]}
+/>
+```
 
 
 ## Props

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jobber/components",
-  "version": "7.12.0",
+  "version": "7.12.1",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.cjs",
@@ -583,5 +583,5 @@
     "> 1%",
     "IE 10"
   ],
-  "gitHead": "a74a5ff8148ca6a6103aef333e6ed60caae37e6f"
+  "gitHead": "64b5115b33b7aa2a3a949a9ae7ad89575adbcb5a"
 }