@jonmilner/ui 0.8.1 → 0.8.2

package/dist/Menu/Menu.css

@@ -1,2 +1,2 @@
 @layer tokens, reset, atoms, components.box, components.checkbox, components.clickable, components.icon, components.icon-button, components.inline, components.stack, components.text, components.avatar, components.badge, components.button, components.chip, components.field, components.color-field, components.heading, components.dialog, components.alert-dialog, components.menu, components.multiselect, components.search-field, components.tabs, components.tag, components.text-field, components.toast, components.visually-hidden;
-@layer components.menu{._393eil1{border:var(--space-1) solid var(--color-border);transform-origin:var(--transform-origin);transition:opacity var(--duration-fast) var(--easing-standard), scale var(--duration-fast) var(--easing-enter)}._393eil1:focus-visible{outline:var(--space-2) solid var(--color-focus);outline-offset:var(--space-2)}._393eil1[data-starting-style],._393eil1[data-ending-style]{opacity:0;scale:calc(1 - var(--scale-med))}._393eil2{cursor:pointer;touch-action:manipulation;-webkit-tap-highlight-color:transparent;-webkit-user-select:none;user-select:none}._393eil2:focus-visible{outline:var(--space-2) solid var(--color-focus);outline-offset:var(--space-2)}._393eil2[data-highlighted]{background-color:light-dark(var(--color-bg-muted),color-mix(in srgb, var(--color-fg) 10%, var(--color-bg-raised)))}._393eil2[aria-disabled=true]{color:var(--color-fg-muted);cursor:not-allowed}._393eil3{text-decoration:none}._393eil4{border-block-start-color:var(--color-border)}._393eil4:before{content:"";border-block-start:var(--space-1) solid;border-block-start-color:inherit;display:block}@media (forced-colors:active){._393eil2[data-highlighted]:not([aria-disabled=true]){forced-color-adjust:none;color:highlighttext;background-color:highlight}._393eil2[aria-disabled=true]{color:graytext}}}
+@layer components.menu{._393eil1{border:var(--space-1) solid var(--color-border);max-inline-size:var(--available-width);transform-origin:var(--transform-origin);transition:opacity var(--duration-fast) var(--easing-standard), scale var(--duration-fast) var(--easing-enter)}._393eil1:focus-visible{outline:var(--space-2) solid var(--color-focus);outline-offset:var(--space-2)}._393eil1[data-starting-style],._393eil1[data-ending-style]{opacity:0;scale:calc(1 - var(--scale-med))}._393eil2{cursor:pointer;touch-action:manipulation;-webkit-tap-highlight-color:transparent;-webkit-user-select:none;user-select:none}._393eil2:focus-visible{outline:var(--space-2) solid var(--color-focus);outline-offset:calc(-1 * var(--space-2))}._393eil2[data-highlighted]{background-color:light-dark(var(--color-bg-muted),color-mix(in srgb, var(--color-fg) 10%, var(--color-bg-raised)))}._393eil2[aria-disabled=true]{color:var(--color-fg-muted);cursor:not-allowed}._393eil3{color:var(--color-fg-muted)}._393eil4{text-decoration:none}._393eil5{border-block-start-color:var(--color-border)}._393eil5:before{content:"";border-block-start:var(--space-1) solid;border-block-start-color:inherit;display:block}@media (forced-colors:active){._393eil2[data-highlighted]:not([aria-disabled=true]){forced-color-adjust:none;color:highlighttext;background-color:highlight}._393eil2[data-highlighted]:not([aria-disabled=true]):focus-visible{color:canvastext;background-color:canvas}._393eil2[aria-disabled=true]{color:graytext}._393eil3{color:inherit}}}

package/dist/Menu/Menu.css.mjs

@@ -3,6 +3,6 @@ import "./Menu.css";
 /* empty css                               */
 /* empty css                     */
 //#region src/Menu/Menu.css.ts
-var e = "_393eil0", t = "_393eil1", n = "_393eil2", r = "_393eil3", i = "_393eil4";
+var e = "_393eil0", t = "_393eil1", n = "_393eil2", r = "_393eil3", i = "_393eil4", a = "_393eil5";
 //#endregion
-export { n as item, r as linkItem, t as popup, e as positioner, i as separator };
+export { r as description, n as item, i as linkItem, t as popup, e as positioner, a as separator };

package/dist/Menu/client.d.mts

@@ -1,9 +1,24 @@
+import { IconProps } from "../Icon/index.mjs";
 import { TriggerElementProps, TriggerLookProps } from "../popup/client.mjs";
 import "./index.mjs";
+import { ComponentType, ReactNode } from "react";
 import { Menu } from "@base-ui/react/menu";
 //#region src/Menu/client.d.ts
 type TriggerOwnProps = Omit<Menu.Trigger.Props, "render" | "className" | "style" | "nativeButton">;
-export type MenuTriggerProps = TriggerOwnProps & TriggerLookProps & Omit<TriggerElementProps, keyof TriggerLookProps | keyof TriggerOwnProps>;
-export declare function MenuTrigger({ disabled, openOnHover, delay, closeDelay, handle, payload, ...props }: MenuTriggerProps): import("react").JSX.Element;
+type TriggerIconForm = {
+  "aria-label"?: never;
+  "aria-labelledby"?: never;
+  children?: never;
+  icon: ComponentType<IconProps>;
+  iconEnd?: never;
+  iconStart?: never;
+  label: string;
+};
+type TriggerTextForm = {
+  icon?: never;
+  label?: never;
+};
+export type MenuTriggerProps = TriggerOwnProps & TriggerLookProps & Omit<TriggerElementProps, keyof TriggerLookProps | keyof TriggerOwnProps> & (TriggerIconForm | TriggerTextForm);
+export declare function MenuTrigger({ disabled, openOnHover, delay, closeDelay, handle, payload, icon, label, ...props }: MenuTriggerProps): import("react").JSX.Element;
 //#endregion
 export {};

package/dist/Menu/client.mjs

@@ -2,47 +2,90 @@
 import { join as e } from "../styles/join.mjs";
 import { splitStyleProps as t } from "../styles/split-style-props.mjs";
 import { Box as n } from "../Box/index.mjs";
-import { PopupScope as r, triggerElement as i, useClosingRule as a, usePopupScope as o, useRecordOpenChange as s } from "../popup/client.mjs";
-import { positioner as c } from "./Menu.css.mjs";
-import { jsx as l } from "react/jsx-runtime";
-import { Menu as u } from "@base-ui/react/menu";
+import { Text as r } from "../Text/index.mjs";
+import { PopupScope as i, triggerElement as a, useClosingRule as o, usePopupScope as s, useRecordOpenChange as c } from "../popup/client.mjs";
+import { IconButton as l } from "../IconButton/index.mjs";
+import { description as u, positioner as d } from "./Menu.css.mjs";
+import { Fragment as f, jsx as p, jsxs as m } from "react/jsx-runtime";
+import { useId as h } from "react";
+import { Menu as g } from "@base-ui/react/menu";
 //#region src/Menu/client.tsx
-function d({ disabled: e = !1, openOnHover: t, delay: n, closeDelay: r, handle: a, payload: s, ...c }) {
-	let { ref: d } = o();
-	return /* @__PURE__ */ l(u.Trigger, {
+function _({ disabled: e = !1, openOnHover: t, delay: n, closeDelay: r, handle: i, payload: o, icon: c, label: u, ...d }) {
+	let { ref: f } = s();
+	return /* @__PURE__ */ p(g.Trigger, {
 		disabled: e,
 		openOnHover: t,
 		delay: n,
 		closeDelay: r,
-		handle: a,
-		payload: s,
-		ref: d,
-		render: i(c)
+		handle: i,
+		payload: o,
+		ref: f,
+		render: c ? /* @__PURE__ */ p(l, {
+			...d,
+			icon: c,
+			label: u
+		}) : a(d)
 	});
 }
-function f({ children: e }) {
-	let { container: t } = o();
-	return /* @__PURE__ */ l(u.Portal, {
+function v(e, t, i) {
+	let a = h();
+	return t === void 0 ? { content: e } : {
+		aria: { "aria-describedby": i ? `${a} ${i}` : a },
+		content: /* @__PURE__ */ m(f, { children: [/* @__PURE__ */ p(n, {
+			alignItems: "center",
+			as: "span",
+			display: "flex",
+			gap: "8",
+			children: e
+		}), /* @__PURE__ */ p(r, {
+			"aria-hidden": !0,
+			as: "span",
+			className: u,
+			id: a,
+			size: "xs",
+			children: t
+		})] })
+	};
+}
+function y({ description: e, children: t, ...n }) {
+	let { aria: r, content: i } = v(t, e, n["aria-describedby"]);
+	return /* @__PURE__ */ p(g.Item, {
+		...n,
+		...r,
+		children: i
+	});
+}
+function b({ description: e, children: t, ...n }) {
+	let { aria: r, content: i } = v(t, e, n["aria-describedby"]);
+	return /* @__PURE__ */ p(g.LinkItem, {
+		...n,
+		...r,
+		children: i
+	});
+}
+function x({ children: e }) {
+	let { container: t } = s();
+	return /* @__PURE__ */ p(g.Portal, {
 		container: t,
 		children: e
 	});
 }
-function p(e) {
-	return /* @__PURE__ */ l(r, { children: /* @__PURE__ */ l(m, { ...e }) });
+function S(e) {
+	return /* @__PURE__ */ p(i, { children: /* @__PURE__ */ p(C, { ...e }) });
 }
-function m({ onOpenChange: e, ...t }) {
-	return /* @__PURE__ */ l(u.Root, {
+function C({ onOpenChange: e, ...t }) {
+	return /* @__PURE__ */ p(g.Root, {
 		...t,
-		onOpenChange: s(e)
+		onOpenChange: c(e)
 	});
 }
-function h({ finalFocus: e, ...n }) {
-	return /* @__PURE__ */ l(u.Positioner, {
+function w({ finalFocus: e, ...n }) {
+	return /* @__PURE__ */ p(g.Positioner, {
 		...n,
 		collisionPadding: 8,
 		render: (n, { open: r }) => {
 			let [, i] = t(n);
-			return /* @__PURE__ */ l(g, {
+			return /* @__PURE__ */ p(T, {
 				...i,
 				finalFocus: e,
 				open: r
@@ -51,16 +94,16 @@ function h({ finalFocus: e, ...n }) {
 		sideOffset: 4
 	});
 }
-function g({ open: t, finalFocus: r, ref: i, className: o, ...s }) {
-	return /* @__PURE__ */ l(n, {
+function T({ open: t, finalFocus: r, ref: i, className: a, ...s }) {
+	return /* @__PURE__ */ p(n, {
 		...s,
-		...a(i, {
+		...o(i, {
 			finalFocus: r,
 			open: t
 		}),
-		className: e(c, o),
+		className: e(d, a),
 		zIndex: "popover"
 	});
 }
 //#endregion
-export { f as MenuPortal, h as MenuPositioner, p as MenuRootScope, d as MenuTrigger };
+export { y as MenuItemPart, b as MenuLinkItemPart, x as MenuPortal, w as MenuPositioner, S as MenuRootScope, _ as MenuTrigger };

package/dist/Menu/index.d.mts

@@ -11,10 +11,13 @@ export type MenuProps = Pick<Menu$1.Root.Props, "open" | "defaultOpen" | "onOpen
   children?: ReactNode;
 };
 export type MenuPopupProps = PartProps<Menu$1.Popup.Props> & Pick<Menu$1.Positioner.Props, "side" | "align">;
-export type MenuItemProps = PartProps<Menu$1.Item.Props> & {
+type ItemDescription = {
+  description?: ReactNode;
+};
+export type MenuItemProps = PartProps<Menu$1.Item.Props> & ItemDescription & {
   variant?: "neutral" | "danger";
 };
-export type MenuLinkItemProps = PartProps<Menu$1.LinkItem.Props> & {
+export type MenuLinkItemProps = PartProps<Menu$1.LinkItem.Props> & ItemDescription & {
   disabled?: boolean;
   href: string;
 };
@@ -24,8 +27,8 @@ export type MenuGroupProps = PartProps<Menu$1.Group.Props> & {
 };
 declare function MenuRoot(props: MenuProps): import("react").JSX.Element;
 declare function MenuPopup({ side, align, backgroundColor, borderRadius, boxShadow, padding, className, style, ...props }: MenuPopupProps): import("react").JSX.Element;
-declare function MenuItem({ variant, display, alignItems, gap, minBlockSize, paddingInline, borderRadius, color, className, style, children, ...props }: MenuItemProps): import("react").JSX.Element;
-declare function MenuLinkItem({ href, disabled, closeOnClick, onClick, display, alignItems, gap, minBlockSize, paddingInline, borderRadius, color, className, style, children, ...props }: MenuLinkItemProps): import("react").JSX.Element;
+declare function MenuItem({ variant, description, display, minBlockSize, paddingInline, borderRadius, color, className, style, children, ...props }: MenuItemProps): import("react").JSX.Element;
+declare function MenuLinkItem({ href, disabled, closeOnClick, onClick, description, display, minBlockSize, paddingInline, borderRadius, color, className, style, children, ...props }: MenuLinkItemProps): import("react").JSX.Element;
 declare function MenuSeparator({ paddingBlock, paddingInline, className, style, ...props }: MenuSeparatorProps): import("react").JSX.Element;
 declare function MenuGroup({ label, className, style, children, ...props }: MenuGroupProps): import("react").JSX.Element;
 export declare const Menu: typeof MenuRoot & {

package/dist/Menu/index.mjs

@@ -3,90 +3,102 @@ import { splitStyleProps as t } from "../styles/split-style-props.mjs";
 import { Box as n } from "../Box/index.mjs";
 import { Text as r } from "../Text/index.mjs";
 import { item as i, linkItem as a, popup as o, separator as s } from "./Menu.css.mjs";
-import { MenuPortal as c, MenuPositioner as l, MenuRootScope as u, MenuTrigger as d } from "./client.mjs";
-import { jsx as f, jsxs as p } from "react/jsx-runtime";
-import { Children as m } from "react";
-import { Menu as h } from "@base-ui/react/menu";
+import { MenuItemPart as c, MenuLinkItemPart as l, MenuPortal as u, MenuPositioner as d, MenuRootScope as f, MenuTrigger as p } from "./client.mjs";
+import { jsx as m, jsxs as h } from "react/jsx-runtime";
+import { Children as g } from "react";
+import { Menu as _ } from "@base-ui/react/menu";
 //#region src/Menu/index.tsx
-function g(e) {
-	return /* @__PURE__ */ f(u, { ...e });
+function v(e) {
+	return /* @__PURE__ */ m(f, { ...e });
 }
-function _({ side: r = "bottom", align: i = "start", backgroundColor: a = "bgRaised", borderRadius: s = "med", boxShadow: u = "med", padding: d = "4", className: p, style: m, ...g }) {
-	let [_, v] = t(g);
-	return /* @__PURE__ */ f(c, { children: /* @__PURE__ */ f(l, {
+function y({ side: r = "bottom", align: i = "start", backgroundColor: a = "bgRaised", borderRadius: s = "med", boxShadow: c = "med", padding: l = "4", className: f, style: p, ...h }) {
+	let [g, v] = t(h);
+	return /* @__PURE__ */ m(u, { children: /* @__PURE__ */ m(d, {
 		align: i,
 		finalFocus: v.finalFocus !== void 0 && v.finalFocus !== !0,
 		side: r,
-		children: /* @__PURE__ */ f(h.Popup, {
+		children: /* @__PURE__ */ m(_.Popup, {
 			...v,
-			render: /* @__PURE__ */ f(n, {
+			render: /* @__PURE__ */ m(n, {
 				backgroundColor: a,
 				borderRadius: s,
-				boxShadow: u,
-				padding: d,
-				..._,
-				className: e(o, p),
-				style: m
+				boxShadow: c,
+				padding: l,
+				...g,
+				className: e(o, f),
+				style: p
 			})
 		})
 	}) });
 }
-function v(e) {
-	return m.map(e, (e) => typeof e == "string" || typeof e == "number" ? /* @__PURE__ */ f(r, {
+function b(e) {
+	return g.map(e, (e) => typeof e == "string" || typeof e == "number" ? /* @__PURE__ */ m(r, {
 		as: "span",
 		font: "label",
 		size: "sm",
 		children: e
 	}) : e);
 }
-function y({ variant: r = "neutral", display: a = "flex", alignItems: o = "center", gap: s = "8", minBlockSize: c = "sm", paddingInline: l = "12", borderRadius: u = "sm", color: d = r === "danger" ? "danger" : "fg", className: p, style: m, children: g, ..._ }) {
-	let [y, b] = t(_);
-	return /* @__PURE__ */ f(h.Item, {
-		...b,
-		render: /* @__PURE__ */ f(n, {
-			display: a,
-			alignItems: o,
-			gap: s,
-			minBlockSize: c,
+var x = (e) => e == null || e === !1 || e === "" ? void 0 : e, S = (e, t) => t !== void 0 && (typeof e == "string" || typeof e == "number") ? String(e) : void 0, C = (e) => e ? {
+	flexDirection: "column",
+	alignItems: "stretch",
+	justifyContent: "center",
+	gap: "4",
+	paddingBlock: "8"
+} : {
+	alignItems: "center",
+	gap: "8"
+};
+function w({ variant: r = "neutral", description: a, display: o = "flex", minBlockSize: s = "sm", paddingInline: l = "12", borderRadius: u = "sm", color: d = r === "danger" ? "danger" : "fg", className: f, style: p, children: h, ...g }) {
+	let [_, v] = t(g), y = x(a);
+	return /* @__PURE__ */ m(c, {
+		label: S(h, y),
+		...v,
+		description: y,
+		render: /* @__PURE__ */ m(n, {
+			...C(y !== void 0),
+			display: o,
+			minBlockSize: s,
 			paddingInline: l,
 			borderRadius: u,
 			color: d,
-			...y,
-			className: e(i, p),
-			style: m
+			..._,
+			className: e(i, f),
+			style: p
 		}),
-		children: v(g)
+		children: b(h)
 	});
 }
-function b({ href: r, disabled: o = !1, closeOnClick: s = !0, onClick: c, display: l = "flex", alignItems: u = "center", gap: d = "8", minBlockSize: p = "sm", paddingInline: m = "12", borderRadius: g = "sm", color: _ = "fg", className: y, style: b, children: x, ...S }) {
-	let [C, w] = t(S);
-	return /* @__PURE__ */ f(h.LinkItem, {
-		...w,
+function T({ href: r, disabled: o = !1, closeOnClick: s = !0, onClick: c, description: u, display: d = "flex", minBlockSize: f = "sm", paddingInline: p = "12", borderRadius: h = "sm", color: g = "fg", className: _, style: v, children: y, ...w }) {
+	let [T, E] = t(w), D = x(u);
+	return /* @__PURE__ */ m(l, {
+		label: S(y, D),
+		...E,
 		"aria-disabled": o || void 0,
 		closeOnClick: !o && s,
+		description: D,
 		href: o ? void 0 : r,
 		onClick: o ? void 0 : c,
-		render: /* @__PURE__ */ f(n, {
+		render: /* @__PURE__ */ m(n, {
 			as: "a",
-			display: l,
-			alignItems: u,
-			gap: d,
-			minBlockSize: p,
-			paddingInline: m,
-			borderRadius: g,
-			color: _,
-			...C,
-			className: e(i, a, y),
-			style: b
+			...C(D !== void 0),
+			display: d,
+			minBlockSize: f,
+			paddingInline: p,
+			borderRadius: h,
+			color: g,
+			...T,
+			className: e(i, a, _),
+			style: v
 		}),
-		children: v(x)
+		children: b(y)
 	});
 }
-function x({ paddingBlock: r = "4", paddingInline: i = "8", className: a, style: o, ...c }) {
+function E({ paddingBlock: r = "4", paddingInline: i = "8", className: a, style: o, ...c }) {
 	let [l, u] = t(c);
-	return /* @__PURE__ */ f(h.Separator, {
+	return /* @__PURE__ */ m(_.Separator, {
 		...u,
-		render: /* @__PURE__ */ f(n, {
+		render: /* @__PURE__ */ m(n, {
 			paddingBlock: r,
 			paddingInline: i,
 			...l,
@@ -95,17 +107,17 @@ function x({ paddingBlock: r = "4", paddingInline: i = "8", className: a, style:
 		})
 	});
 }
-function S({ label: e, className: i, style: a, children: o, ...s }) {
+function D({ label: e, className: i, style: a, children: o, ...s }) {
 	let [c, l] = t(s);
-	return /* @__PURE__ */ p(h.Group, {
+	return /* @__PURE__ */ h(_.Group, {
 		...l,
-		render: /* @__PURE__ */ f(n, {
+		render: /* @__PURE__ */ m(n, {
 			...c,
 			className: i,
 			style: a
 		}),
-		children: [/* @__PURE__ */ f(h.GroupLabel, {
-			render: /* @__PURE__ */ f(r, {
+		children: [/* @__PURE__ */ m(_.GroupLabel, {
+			render: /* @__PURE__ */ m(r, {
 				as: "div",
 				color: "fgMuted",
 				font: "label",
@@ -117,13 +129,13 @@ function S({ label: e, className: i, style: a, children: o, ...s }) {
 		}), o]
 	});
 }
-var C = Object.assign(g, {
-	Trigger: d,
-	Popup: _,
-	Item: y,
-	LinkItem: b,
-	Separator: x,
-	Group: S
+var O = Object.assign(v, {
+	Trigger: p,
+	Popup: y,
+	Item: w,
+	LinkItem: T,
+	Separator: E,
+	Group: D
 });
 //#endregion
-export { C as Menu };
+export { O as Menu };

package/dist/docs/Menu.md

@@ -20,12 +20,14 @@ A list of actions that opens from a button: a row's "Edit, Duplicate, Delete", a
 ## Rules
 
 - Compose the parts: `Menu` > `Menu.Trigger` + `Menu.Popup` > `Menu.Item`, `Menu.LinkItem`, `Menu.Separator`, `Menu.Group`. `Menu` holds the open state and renders no element, so it takes no `className` or `style`; every other part does, plus style props.
-- `Menu.Trigger` is a bare `Clickable`: give it its look with style props (or your own class), and an accessible name. An icon-only trigger needs `aria-label`.
+- `Menu.Trigger` is a bare `Clickable`: give it its look with style props (or your own class), and an accessible name.
+- For an icon-only trigger ("More actions"), pass `icon` and `label`: it renders an `IconButton`, the same square as one at each `size` (`sm`, `med`, `lg`; `med` by default), named by `label`, with IconButton's `variant` (`secondary` by default) and the open look below. It takes no children, `iconStart`, `iconEnd` or `aria-label` (ADR 0123). Never build one from `iconStart` and `aria-label`: Button's padding makes it wider than the IconButtons beside it.
 - For a trigger that reads as a button ("Actions", "New"), pass Button's `variant`, `size`, `iconStart` or `iconEnd` (a `ChevronDownIcon` for "Actions ▾"): it renders a `Button`, with its fill, border and height, and keeps the trigger's behavior and `aria-disabled`. While the menu is open it shows Button's open look, a held tint and an inset ring (ADR 0063); a bare trigger has none, so style it yourself off `aria-expanded`. Style props still override the defaults.
 - `Menu.Item` runs its `onClick` on click, Enter and Space, then the menu closes. Pass `closeOnClick={false}` to keep it open.
 - `Menu.LinkItem` is a real `<a role="menuitem">` for an entry that goes somewhere. `href` is required; `target`, `rel` and `download` pass through. Hover shows the URL, Cmd/Ctrl-click and middle-click open a new tab, and a click, Enter or Space follows it and closes the menu. Never navigate from a `Menu.Item`'s `onClick` (`location.assign`, a router's `navigate`): it loses all of that. Router-aware (client-side) links are not offered. It takes no `variant`.
 - `variant="danger"` marks a destructive item. It still runs on one click, so open a confirm dialog from it (Cancel focused first) before anything irreversible happens.
 - `disabled` on an item renders `aria-disabled`: it stays announced and reachable with the arrow keys, and does nothing. A disabled `Menu.LinkItem` also drops its `href`, so no click or context menu reaches the URL. On the trigger it keeps the button focusable and stops it opening.
+- `description` on `Menu.Item` or `Menu.LinkItem` puts a short line of muted text below the label, such as why a disabled item cannot act ("Already running"). The item grows to fit both lines. Put secondary text there, never as a second line in the children, which overlaps the label and joins its name.
 - `Menu.Group` takes a `label` that is shown and names the group. Separate groups with `Menu.Separator`.
 - `Menu.Separator` draws a line inside its own padding (`paddingBlock="4"`, `paddingInline="8"`) and sets no margin. Change its spacing with `paddingBlock` and `paddingInline` (the `padding` shorthand loses to these defaults, decision 0065); a `margin*` prop adds space outside the padding. `style={{ borderBlockStartColor }}` recolours the line.
 - The popup portals into the trigger's nearest `ThemeProvider`, so it keeps the brand and mode. That provider must not clip or stack its content: wrap the app root, and keep a nested provider off elements with `overflow: hidden`, a `transform` or their own `z-index`, or the popup is clipped or drawn under siblings. It sits on `zIndex` `popover`. A menu opened only through `open`, with no `Menu.Trigger`, has no provider to find and portals to `<body>`.
@@ -38,9 +40,7 @@ A list of actions that opens from a button: a row's "Edit, Duplicate, Delete", a
 
 ```tsx
 <Menu>
-  <Menu.Trigger aria-label="Actions for Invoice 42" paddingInline="8" borderRadius="sm">
-    <MoreIcon />
-  </Menu.Trigger>
+  <Menu.Trigger icon={EllipsisIcon} label="Actions for Invoice 42" />
   <Menu.Popup>
     <Menu.Item onClick={edit}>Edit</Menu.Item>
     <Menu.Item onClick={duplicate}>Duplicate</Menu.Item>
@@ -61,6 +61,20 @@ A list of actions that opens from a button: a row's "Edit, Duplicate, Delete", a
 </Menu.Popup>
 ```
 
+```tsx
+<Menu>
+  <Menu.Trigger icon={EllipsisIcon} label="More actions" size="sm" />
+  <Menu.Popup>
+    <Menu.Item onClick={retry} description="Runs it again from the start">
+      Retry
+    </Menu.Item>
+    <Menu.Item disabled description="Already running">
+      Unqueue
+    </Menu.Item>
+  </Menu.Popup>
+</Menu>
+```
+
 ```tsx
 <Menu>
   <Menu.Trigger variant="secondary" size="sm">
@@ -93,6 +107,19 @@ A list of actions that opens from a button: a row's "Edit, Duplicate, Delete", a
 </Menu.Item>
 ```
 
+```tsx
+// Button's padding makes this wider than an IconButton. Use icon={EllipsisIcon} label="More actions".
+<Menu.Trigger iconStart={EllipsisIcon} aria-label="More actions" size="sm" />
+```
+
+```tsx
+// The second line overlaps the label and joins the item's name. Use description="Already running".
+<Menu.Item disabled>
+  Unqueue
+  <Text size="xs">Already running</Text>
+</Menu.Item>
+```
+
 ```tsx
 // Base UI already moves focus with the arrow keys; this fights it.
 <Menu.Item onKeyDown={(event) => event.key === "ArrowDown" && next()}>Edit</Menu.Item>
@@ -116,7 +143,10 @@ A list of actions that opens from a button: a row's "Edit, Duplicate, Delete", a
 - The trigger has `aria-haspopup="menu"` and `aria-expanded`; the popup is `role="menu"` labelled by the trigger, items and link items are `role="menuitem"` (a link item is an `<a>` with an `href`, so the browser treats it as a link), groups are `role="group"` named by their label.
 - Opening from the keyboard focuses the first item; from the pointer, the popup. Focus stays in the menu until it closes. Closed by Esc, an item or `open={false}`, focus returns at once to the trigger that opened it, so a Tab pressed while it fades goes on to the control after the trigger. A press outside, a Tab out, a hover menu the pointer left, or a popup with `finalFocus` leaves focus to Base UI, which places it when the fade ends.
 - A closed menu stays on the page while it fades out, but is `inert` and `aria-hidden` from the moment it closes, so a menu opened during the fade (the next row's) is the only one a screen reader or a role query finds, and nothing in the fading one takes focus or a click.
-- The highlighted item gets a fill (`bgMuted` in light mode; in dark mode `bgRaised` with 10% `fg` mixed in, since `bgMuted` sits too close to the popup there), and the shared focus ring when reached from the keyboard. Under forced colors it is `Highlight` with `HighlightText`, disabled items are `GrayText` on the page's fill even when highlighted (`GrayText` pairs with `Canvas` only), and the popup keeps its border.
+- The icon trigger's name is its `label`, as `aria-label`.
+- An item's `description` is its accessible description (`aria-describedby`), read after its name; the name stays the label alone. An `aria-describedby` of the item's own is kept, read after the description. With plain-text children, typeahead matches the label alone, not the description; otherwise pass `label`.
+- The popup is never wider than the viewport beside its trigger, so at 320 px and 200% text a long item wraps inside it (WCAG 1.4.10).
+- The highlighted item gets a fill (`bgMuted` in light mode; in dark mode `bgRaised` with 10% `fg` mixed in, since `bgMuted` sits too close to the popup there), the same from the pointer and the keyboard. From the keyboard it also gets the shared focus ring, drawn inside the item so it never meets the popup's edge; the fill alone is under 3:1 on the popup, the ring passes 3:1 on the fill (`Menu.test.tsx` checks it). Under forced colors it is `Highlight` with `HighlightText`; from the keyboard the fill drops to `Canvas` so the `Highlight` ring alone marks the item; disabled items are `GrayText` on the page's fill even when highlighted (`GrayText` pairs with `Canvas` only) and marked by the ring, and the popup keeps its border.
 - The danger item's `danger` color passes 4.5:1 on the popup and on the highlight fill in every preset (`Menu.test.tsx` checks it, with `fg` and `fgMuted`); the word ("Delete") carries the meaning, not the color.
 
 ## Props
@@ -152,6 +182,7 @@ Also accepts the style props (see `manifest.json` `styleProps`).
 | --- | --- | --- | --- |
 | `className` | `string` | no |  |
 | `closeOnClick` | `boolean` | no | Whether to close the menu when the item is clicked. |
+| `description` | `ReactNode` | no |  |
 | `disabled` | `boolean` | no | Whether the component should ignore user interaction. |
 | `id` | `string` | no |  |
 | `label` | `string` | no | Overrides the text used for keyboard text navigation and filtering. Falls back to the rendered text when not provided. |
@@ -168,6 +199,7 @@ Also accepts the style props (see `manifest.json` `styleProps`).
 | --- | --- | --- | --- |
 | `className` | `string` | no |  |
 | `closeOnClick` | `boolean` | no | Whether to close the menu when the item is clicked. |
+| `description` | `ReactNode` | no |  |
 | `disabled` | `boolean` | no |  |
 | `href` | `string` | yes |  |
 | `id` | `string` | no |  |
@@ -204,13 +236,17 @@ Also accepts the style props (see `manifest.json` `styleProps`).
 
 | Prop | Type | Required | Description |
 | --- | --- | --- | --- |
+| `aria-label` | `string` | no | Defines a string value that labels the current element. |
+| `aria-labelledby` | `string` | no | Identifies the element (or elements) that labels the current element. |
 | `children` | `ReactNode` | no |  |
 | `closeDelay` | `number` | no | How long to wait before closing the menu that was opened on hover. Specified in milliseconds.  Requires the `openOnHover` prop. |
 | `delay` | `number` | no | How long to wait before the menu may be opened on hover. Specified in milliseconds.  Requires the `openOnHover` prop. |
 | `disabled` | `boolean` | no | Whether the component should ignore user interaction. |
 | `handle` | `MenuHandle<unknown>` | no | A handle to associate the trigger with a menu. |
+| `icon` | `ComponentType` | no |  |
 | `iconEnd` | `ComponentType` | no |  |
 | `iconStart` | `ComponentType` | no |  |
+| `label` | `string` | no |  |
 | `openOnHover` | `boolean` | no | Whether the menu should also open when the trigger is hovered. |
 | `payload` | `unknown` | no | A payload to pass to the menu when it is opened. |
 | `size` | `"lg" \| "med" \| "sm"` | no |  |

package/dist/docs/manifest.json

@@ -1,7 +1,7 @@
 {
   "$schema": "./manifest.schema.json",
   "package": "@jonmilner/ui",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "components": [
     {
       "name": "AlertDialog",
@@ -1301,6 +1301,11 @@
               "required": false,
               "description": "Whether to close the menu when the item is clicked."
             },
+            {
+              "name": "description",
+              "type": "ReactNode",
+              "required": false
+            },
             {
               "name": "disabled",
               "type": "boolean",
@@ -1361,6 +1366,11 @@
               "required": false,
               "description": "Whether to close the menu when the item is clicked."
             },
+            {
+              "name": "description",
+              "type": "ReactNode",
+              "required": false
+            },
             {
               "name": "disabled",
               "type": "boolean",
@@ -1476,6 +1486,18 @@
           "name": "Menu.Trigger",
           "styleProps": true,
           "props": [
+            {
+              "name": "aria-label",
+              "type": "string",
+              "required": false,
+              "description": "Defines a string value that labels the current element."
+            },
+            {
+              "name": "aria-labelledby",
+              "type": "string",
+              "required": false,
+              "description": "Identifies the element (or elements) that labels the current element."
+            },
             {
               "name": "children",
               "type": "ReactNode",
@@ -1505,6 +1527,11 @@
               "required": false,
               "description": "A handle to associate the trigger with a menu."
             },
+            {
+              "name": "icon",
+              "type": "ComponentType",
+              "required": false
+            },
             {
               "name": "iconEnd",
               "type": "ComponentType",
@@ -1515,6 +1542,11 @@
               "type": "ComponentType",
               "required": false
             },
+            {
+              "name": "label",
+              "type": "string",
+              "required": false
+            },
             {
               "name": "openOnHover",
               "type": "boolean",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jonmilner/ui",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "files": [
     "dist",
     "THIRD_PARTY_NOTICES.md"