@box-kite/react 1.0.0 → 2.0.1

package/components/icon.cjs

@@ -1 +1 @@
-Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:`Module`}});const e=require("../react-shared.cjs");let t=require("react"),n=require("react/jsx-runtime"),r=require("@box-kite/react");var i=6;function a(a,o){let{children:s,label:c,size:l,props:u,style:d,...f}=a,p=l===void 0?void 0:{width:l,height:l},{className:m,styles:h}=(0,r.useClassNames)({width:i,height:i,...f,...p},{svg:!0});if(!(0,t.isValidElement)(s))throw Error(`[box-kite] <Icon> takes exactly one element — the icon to style. For SVG of your own, use <Svg> from components/svg.`);let g=e.i(s.type),_=s.props,v=(g?_.props:s.props)??{},y=g&&_.label!==void 0?{...v,"aria-label":_.label}:v,b={...u,...e.r(c,{...y,...u})},x={...g?{props:{...v,...b}}:b,...d?{style:d}:void 0,ref:o,className:s.props.className?`${s.props.className} ${m}`:m};return(0,n.jsxs)(n.Fragment,{children:[h,(0,t.cloneElement)(s,x)]})}var o=(0,t.forwardRef)(a);o.displayName=`Icon`,exports.default=o;
+Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:`Module`}});const e=require("../react-shared.cjs");let t=require("react"),n=require("react/jsx-runtime"),r=require("@box-kite/react");var i=6;function a(a,o){let{children:s,label:c,size:l,props:u,style:d,...f}=a,p=l===void 0?void 0:{width:l,height:l},{className:m,styles:h}=(0,r.useClassNames)({width:i,height:i,...f,...p},{svg:!0});if(!(0,t.isValidElement)(s))throw Error(`[box-kite] <Icon> takes exactly one element — the icon to style. For SVG of your own, use <Svg> from components/svg.`);let g=e.s(s.type),_=s.props,v=(g?_.props:s.props)??{},y=g&&_.label!==void 0?{...v,"aria-label":_.label}:v,b={...u,...e.o(c,{...y,...u})},x={...g?{props:{...v,...b}}:b,...d?{style:d}:void 0,ref:o,className:s.props.className?`${s.props.className} ${m}`:m};return(0,n.jsxs)(n.Fragment,{children:[h,(0,t.cloneElement)(s,x)]})}var o=(0,t.forwardRef)(a);o.displayName=`Icon`,exports.default=o;

package/components/icon.d.ts

@@ -28,7 +28,8 @@ export interface IconProps extends BoxClassNameProps {
     label?: string;
     /** Attributes forwarded to the icon's element, over anything the icon writes for itself. */
     props?: TagPropsType<'svg'>;
-    /** CSSProperties */
+    /** Inline styles forwarded to the icon's element. Box props are the way to style it; this is for a
+     * value that has to be computed per render, which no class can hold. */
     style?: React.CSSProperties;
 }
 /** Box props on an icon somebody else renders — see `IconProps`. */

package/components/icon.mjs

@@ -1,4 +1,4 @@
-import { i as e, r as t } from "../react-shared.mjs";
+import { o as e, s as t } from "../react-shared.mjs";
 import { cloneElement as n, forwardRef as r, isValidElement as i } from "react";
 import { Fragment as a, jsxs as o } from "react/jsx-runtime";
 import { useClassNames as s } from "@box-kite/react";
@@ -15,12 +15,12 @@ function l(r, l) {
 		...g
 	}, { svg: !0 });
 	if (!i(u)) throw Error("[box-kite] <Icon> takes exactly one element — the icon to style. For SVG of your own, use <Svg> from components/svg.");
-	let y = e(u.type), b = u.props, x = (y ? b.props : u.props) ?? {}, S = y && b.label !== void 0 ? {
+	let y = t(u.type), b = u.props, x = (y ? b.props : u.props) ?? {}, S = y && b.label !== void 0 ? {
 		...x,
 		"aria-label": b.label
 	} : x, C = {
 		...p,
-		...t(d, {
+		...e(d, {
 			...S,
 			...p
 		})

package/components/menu.cjs

@@ -0,0 +1 @@
+"use client";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:`Module`}});const e=require("../platform.cjs"),t=require("../effects.cjs"),n=require("../box.cjs"),r=require("../behavior.cjs"),i=require("../identity.cjs"),a=require("../keyboard.cjs"),o=require("../placement.cjs"),s=require("./overlay.cjs"),c=require("../layer.cjs");let l=require("react"),u=require("react/jsx-runtime");var d;(function(e){let t=e.ITEM_SELECTOR=`[role="menuitem"],[role="menuitemcheckbox"],[role="menuitemradio"]`;function n(e,t){return t instanceof Element&&t.closest(`[role="menu"]`)===e}e.owns=n;function r(e){return[...e.querySelectorAll(t)].filter(t=>n(e,t))}e.items=r;function i(e){return e.getAttribute(`aria-disabled`)===`true`}e.isDisabled=i;function o(e){return e.getAttribute(`aria-haspopup`)===`menu`}e.isSubTrigger=o;function s(e,t,n){if(e.length!==0)return e[t<0?n>0?0:e.length-1:((t+n)%e.length+e.length)%e.length]}e.step=s;function c(e,t,n){let r=a.t.target(t,n,e.length,t=>e[t].textContent??``);return r<0?void 0:e[r]}e.typeaheadTarget=c})(d||={});var f=d,p=(0,l.createContext)(null);function m(e){let t=(0,l.useContext)(p);if(!t)throw Error(`<${e}> must be rendered inside a <Menu>.`);return t}function h(e){let[t,n]=(0,l.useState)([]);return{panels:t,registerLayer:(0,l.useCallback)(t=>{n(e=>[...e,t]);let r=e?.(t);return()=>{n(e=>e.filter(e=>e!==t)),r?.()}},[e])}}var g=(0,l.createContext)(null);function _(e){let{trigger:t,children:n,open:i,defaultOpen:a=!1,onOpenChange:o,label:s,labelledBy:d,side:m=`bottom`,align:g=`start`,offset:_=1,flip:y=!0,matchWidth:b=!1,props:x,...S}=e,C=(0,l.useRef)(`first`),w=r.a(e=>{let t=f.items(e),n=C.current===`last`?t[t.length-1]:t[0];C.current=`first`,(n??e).focus()}),{panels:T,registerLayer:E}=h(),D=c.t({haspopup:`menu`,idPrefix:`menu`,id:S.id,open:i,defaultOpen:a,onOpenChange:o,onOpened:w,inside:T}),O=r.a(e=>{(e.key===`ArrowDown`||e.key===`ArrowUp`)&&(e.preventDefault(),C.current=e.key===`ArrowUp`?`last`:`first`,D.isOpen&&D.panelElement?w(D.panelElement):D.setOpen(!0,{reason:`trigger`,event:e}))}),k=(0,l.useMemo)(()=>({ref:D.trigger.ref,props:{...D.trigger.props,onKeyDown:O}}),[O,D.trigger]),A=r.a(e=>D.setOpen(!1,e)),j=(0,l.useMemo)(()=>({open:D.isOpen,closeAll:A,registerLayer:E}),[A,D.isOpen,E]);return(0,u.jsxs)(u.Fragment,{children:[t(k),(0,u.jsx)(p.Provider,{value:j,children:(0,u.jsx)(v,{layer:D,side:m,align:g,offset:_,flip:y,matchWidth:b,label:s,labelledBy:d??(s?void 0:D.triggerId),contentProps:x,...S,children:n})})]})}function v(t){let{layer:i,side:c,align:d,offset:p,flip:h,matchWidth:g,label:_,labelledBy:v,contentProps:y,closeSelf:b,children:x,...S}=t,{platform:C,isOpen:w,id:T,triggerElement:E,setPanel:D}=i,O=m(`Menu`),k=(0,l.useRef)({query:``,at:0}),A=o.t({side:c,align:d,offset:p,flip:h,matchWidth:g,anchor:E}),j={role:`menu`,"aria-label":_,"aria-labelledby":v,tabIndex:-1,onKeyDown:r.a(t=>{let n=t.currentTarget;if(!f.owns(n,t.target))return;let r=f.items(n),i=r.indexOf(document.activeElement),o=e=>{e&&(t.preventDefault(),e.focus())},s=e.u(n)?`ArrowRight`:`ArrowLeft`;switch(t.key){case`ArrowDown`:return o(f.step(r,i,1));case`ArrowUp`:return o(f.step(r,i,-1));case`Home`:return o(r[0]);case`End`:return o(r[r.length-1]);case`Tab`:return O.closeAll({reason:`tab`,event:t});case s:return b?(t.preventDefault(),b({reason:`trigger`,event:t})):void 0}if(a.t.isPrintable(t)){let e=a.t.push(k.current,t.key,t.timeStamp);o(f.typeaheadTarget(r,e,i))}}),onPointerOver:r.a(e=>{let t=e.currentTarget,n=e.target?.closest(f.ITEM_SELECTOR);!n||!f.owns(t,n)||n===document.activeElement||n.focus()}),...y};return C?(0,u.jsx)(n.default,{ref:D,component:`menu`,...S,variant:[S.variant,{topLayer:!0}],...A.layerProps,id:T,props:{popover:`auto`,...j},children:x}):w?(0,u.jsx)(s.default,{contentRef:D,anchor:E,side:c,align:d,offset:p,flip:h,matchWidth:g,component:`menu`,...S,id:T,props:j,children:x}):null}function y(a){let{label:o,children:s,disabled:d,side:g=`end`,align:_=`start`,offset:y=0,flip:b=!0,itemProps:x,props:S,...C}=a,w=m(`Menu.Sub`),T=i.t(`menu-sub`),E=r.a(e=>{(f.items(e)[0]??e).focus()}),D=r.a((e,t)=>{e&&t?.focus()}),{panels:O,registerLayer:k}=h(w.registerLayer),A=c.t({haspopup:`menu`,idPrefix:`menu-sub`,id:C.id,onOpened:E,onClosing:D,inside:O});t.n(()=>{if(!(!A.isOpen||!A.panelElement))return w.registerLayer(A.panelElement)},[A.isOpen,A.panelElement,w.registerLayer]),t.n(()=>{w.open||A.setOpen(!1,{reason:`imperative`})},[w.open,A.setOpen]),t.n(()=>{if(!A.isOpen)return;let t=new AbortController;return document.addEventListener(`focusin`,t=>{e.l(t,[A.panelElement,A.triggerElement])||A.setOpen(!1,{reason:`imperative`,event:t})},{signal:t.signal}),()=>t.abort()},[A.isOpen,A.panelElement,A.triggerElement,A.setOpen]);let j=r.a(t=>{let n=e.u(t.currentTarget)?`ArrowLeft`:`ArrowRight`;d||t.key!==n||(t.preventDefault(),A.setOpen(!0,{reason:`trigger`,event:t}))}),M=r.a(e=>{d||A.setOpen(!0,{reason:`trigger`,event:e})}),N=(0,l.useMemo)(()=>({open:A.isOpen,closeAll:w.closeAll,registerLayer:k}),[A.isOpen,w.closeAll,k]);return(0,u.jsxs)(u.Fragment,{children:[(0,u.jsxs)(n.default,{tag:`button`,ref:d?void 0:A.trigger.ref,component:`menu.item`,variant:{sub:!0},id:T,props:{type:`button`,role:`menuitem`,tabIndex:-1,"aria-disabled":d||void 0,...A.trigger.props,...x,onKeyDown:j,onPointerEnter:M},children:[o,(0,u.jsx)(n.default,{component:`menu.arrow`})]}),!d&&(0,u.jsx)(p.Provider,{value:N,children:(0,u.jsx)(v,{layer:A,side:g,align:_,offset:y,flip:b,matchWidth:!1,labelledBy:T,contentProps:S,closeSelf:e=>A.setOpen(!1,e),...C,children:s})})]})}function b(e){let{onSelect:t,disabled:i,closeOnSelect:a=!0,props:o,children:s,...c}=e,l=m(`Menu.Item`),d=r.a(e=>{i||(t?.(e),a&&l.closeAll({reason:`select`,event:e}))});return(0,u.jsx)(n.default,{tag:`button`,component:`menu.item`,...c,props:{type:`button`,role:`menuitem`,tabIndex:-1,"aria-disabled":i||void 0,...o,onClick:d},children:s})}function x(e){let{checked:t,defaultChecked:i=!1,onCheckedChange:a,disabled:o,closeOnSelect:s=!1,props:c,children:l,...d}=e,f=m(`Menu.CheckboxItem`),[p,h]=r.i({value:t,defaultValue:i,onChange:a}),g=r.a(e=>{o||(h(!p,{reason:`select`,event:e}),s&&f.closeAll({reason:`select`,event:e}))});return(0,u.jsxs)(n.default,{tag:`button`,component:`menu.item`,...d,props:{type:`button`,role:`menuitemcheckbox`,tabIndex:-1,"aria-checked":p,"aria-disabled":o||void 0,...c,onClick:g},children:[(0,u.jsx)(n.default,{component:`menu.indicator`,children:p&&(0,u.jsx)(n.default,{component:`menu.check`})}),l]})}function S(e){let{label:t,value:n,defaultValue:i=``,onValueChange:a,children:o,...s}=e,[c,d]=r.i({value:n,defaultValue:i,onChange:a}),f=r.a((e,t)=>d(e,{reason:`select`,event:t})),p=(0,l.useMemo)(()=>({value:c,select:f}),[c,f]);return(0,u.jsx)(g.Provider,{value:p,children:(0,u.jsx)(w,{label:t,...s,children:o})})}function C(e){let{value:t,disabled:i,closeOnSelect:a=!1,props:o,children:s,...c}=e,d=m(`Menu.RadioItem`),f=(0,l.useContext)(g);if(!f)throw Error(`<Menu.RadioItem> must be rendered inside a <Menu.RadioGroup>.`);let p=f.value===t,h=r.a(e=>{i||(f.select(t,e),a&&d.closeAll({reason:`select`,event:e}))});return(0,u.jsxs)(n.default,{tag:`button`,component:`menu.item`,...c,props:{type:`button`,role:`menuitemradio`,tabIndex:-1,"aria-checked":p,"aria-disabled":i||void 0,...o,onClick:h},children:[(0,u.jsx)(n.default,{component:`menu.indicator`,children:p&&(0,u.jsx)(n.default,{component:`menu.dot`})}),s]})}function w(e){let{label:t,props:r,children:a,...o}=e,s=i.t(`menu-group`);return(0,u.jsxs)(n.default,{component:`menu.group`,...o,props:{role:`group`,"aria-labelledby":t?s:void 0,...r},children:[t&&(0,u.jsx)(n.default,{component:`menu.label`,id:s,props:{role:`presentation`},children:t}),a]})}function T(e){let{props:t,...r}=e;return(0,u.jsx)(n.default,{component:`menu.separator`,...r,props:{role:`separator`,...t}})}b.displayName=`Menu.Item`,x.displayName=`Menu.CheckboxItem`,S.displayName=`Menu.RadioGroup`,C.displayName=`Menu.RadioItem`,w.displayName=`Menu.Group`,T.displayName=`Menu.Separator`,y.displayName=`Menu.Sub`;var E=Object.assign(_,{Item:b,CheckboxItem:x,RadioGroup:S,RadioItem:C,Group:w,Separator:T,Sub:y});_.displayName=`Menu`,exports.default=E;

package/components/menu.d.ts

@@ -0,0 +1,234 @@
+import { BoxProps } from '../box';
+import { ChangeHandler } from '../react/a11y/useControllableState';
+import { PopoverReason, PopoverTrigger as LayerTrigger, PopoverTriggerAttributes as LayerTriggerAttributes } from '../react/popover/usePopoverLayer';
+import { ComponentsAndVariants } from '@box-kite/core/types';
+import { AnchorAlign, AnchorSide } from '../utils/anchor/anchorUtils';
+/**
+ * Why the menu opened or closed. The four a layer always reports, plus the two only a menu has: `select`
+ * is an item being chosen — the transition a consumer most often wants to tell apart — and `tab` is focus
+ * leaving the menu, which APG asks should close it.
+ */
+export type MenuReason = PopoverReason | 'select' | 'tab';
+/** The DOM attributes the trigger has to carry, `onKeyDown` included: the arrow keys open a menu too. */
+export interface MenuTriggerAttributes extends LayerTriggerAttributes<'menu'> {
+    onKeyDown(event: React.KeyboardEvent): void;
+}
+/**
+ * What the trigger has to carry: spread it onto the control itself, not a wrapper. The `ref` is what the
+ * menu is anchored to, so it is not optional decoration.
+ *
+ * ```tsx
+ * {(trigger) => <Button {...trigger}>Actions</Button>}          // a Box component
+ * {(trigger) => <button ref={trigger.ref} {...trigger.props}>}  // a plain element
+ * ```
+ *
+ * It must be a **button**: `popovertarget` is what the browser toggles on, and it only reads it off one.
+ */
+export interface MenuTrigger extends Omit<LayerTrigger<'menu'>, 'props'> {
+    props: MenuTriggerAttributes;
+}
+type MenuBoxProps<TKey extends keyof ComponentsAndVariants> = Omit<BoxProps<'div', TKey>, 'open' | 'flip'>;
+export interface MenuProps<TKey extends keyof ComponentsAndVariants = 'menu'> extends MenuBoxProps<TKey> {
+    /** The trigger, handed the ref and props that wire it to the menu. It has to be a button. */
+    trigger: (trigger: MenuTrigger) => React.ReactNode;
+    /** The items: `Menu.Item`, `Menu.CheckboxItem`, `Menu.RadioGroup`, `Menu.Group`, `Menu.Separator`, `Menu.Sub`. */
+    children?: React.ReactNode;
+    /** Controlled open state. Leave it out and the menu owns it. */
+    open?: boolean;
+    /** Whether it starts open, when the menu owns its own state. */
+    defaultOpen?: boolean;
+    /**
+     * Fires with the new state and why it changed — `'select'`, `'trigger'`, `'escape'`, `'outside-pointer'`,
+     * `'tab'` or `'imperative'`. A close cannot be refused: the browser has already done it by then.
+     */
+    onOpenChange?: ChangeHandler<boolean, MenuReason>;
+    /** The menu's accessible name. Left out, it takes its trigger's, which is what APG asks for. */
+    label?: string;
+    /** Names the menu after an element already on the page, instead of `label`. */
+    labelledBy?: string;
+    /**
+     * Which side of the trigger the menu sits on — `top`/`bottom` are the block axis, `start`/`end` the
+     * inline one, so a menu beside its trigger mirrors in a right-to-left page. Default `'bottom'`.
+     */
+    side?: AnchorSide;
+    /** Which of the trigger's edges to line the menu up with along the other axis. Default `'start'`. */
+    align?: AnchorAlign;
+    /** The gap between trigger and menu, on the ÷4 spacing scale. Default 1 — 4px. */
+    offset?: number;
+    /** Whether a side with no room may be swapped for its opposite. Default `true`. */
+    flip?: boolean;
+    /** Whether the menu is at least as wide as its trigger. Default `false` — a menu sizes to its content. */
+    matchWidth?: boolean;
+}
+/** Every Box prop, on the `<button>` that is one item. */
+export interface MenuItemProps<TKey extends keyof ComponentsAndVariants = 'menu.item'> extends Omit<BoxProps<'button', TKey>, 'disabled' | 'children'> {
+    /** The item's content. */
+    children?: React.ReactNode;
+    /** The item was chosen — by a press, or by Enter or Space, which the browser turns into one. */
+    onSelect?(event: React.MouseEvent): void;
+    /**
+     * Focusable, announced, and not activatable. `aria-disabled` rather than the `disabled` attribute,
+     * because APG asks that a disabled item stay reachable: a keyboard user has to be able to find out it
+     * is there at all.
+     */
+    disabled?: boolean;
+    /** Whether choosing it closes the whole menu. Default `true`. */
+    closeOnSelect?: boolean;
+}
+/** Every Box prop, on the `<button>` that is one checkbox item. */
+export interface MenuCheckboxItemProps<TKey extends keyof ComponentsAndVariants = 'menu.item'> extends Omit<MenuItemProps<TKey>, 'onSelect' | 'checked'> {
+    /** Controlled checked state. Leave it out and the item owns it. */
+    checked?: boolean;
+    /** Whether it starts checked, when the item owns its own state. */
+    defaultChecked?: boolean;
+    /** Fires with the new state, and the press behind it. */
+    onCheckedChange?: ChangeHandler<boolean, 'select'>;
+    /** Whether toggling it closes the menu. Default `false`, so several boxes can be ticked in one visit. */
+    closeOnSelect?: boolean;
+}
+/** Every Box prop, on the `role="group"` holding a set of radio items. */
+export interface MenuRadioGroupProps<TKey extends keyof ComponentsAndVariants = 'menu.group'> extends Omit<BoxProps<'div', TKey>, 'children'> {
+    /** The radio items. */
+    children?: React.ReactNode;
+    /** The group's heading. It names the group, so a screen reader reads the items as a set. */
+    label?: React.ReactNode;
+    /** Controlled value — the `value` of whichever item is checked. */
+    value?: string;
+    /** The value checked to start with, when the group owns its own state. */
+    defaultValue?: string;
+    /** Fires with the value chosen, and the press behind it. */
+    onValueChange?: ChangeHandler<string, 'select'>;
+}
+/** Every Box prop, on the `<button>` that is one radio item. */
+export interface MenuRadioItemProps<TKey extends keyof ComponentsAndVariants = 'menu.item'> extends Omit<MenuItemProps<TKey>, 'onSelect' | 'checked'> {
+    /** What this item stands for, compared against the group's `value`. */
+    value: string;
+    /** Whether choosing it closes the menu. Default `false`, the way a checkbox item behaves. */
+    closeOnSelect?: boolean;
+}
+/** Every Box prop, on the `role="group"` around a titled section of the menu. */
+export interface MenuGroupProps<TKey extends keyof ComponentsAndVariants = 'menu.group'> extends Omit<BoxProps<'div', TKey>, 'children'> {
+    /** The items in the section. */
+    children?: React.ReactNode;
+    /**
+     * The section's heading. It names the group rather than standing alone: a heading nothing is labelled by
+     * is read as a stray line of text, which is why there is no separate label part.
+     */
+    label?: React.ReactNode;
+}
+/** Every Box prop, on the `role="separator"` between two sections. */
+export type MenuSeparatorProps<TKey extends keyof ComponentsAndVariants = 'menu.separator'> = BoxProps<'div', TKey>;
+export interface MenuSubProps<TKey extends keyof ComponentsAndVariants = 'menu'> extends MenuBoxProps<TKey> {
+    /** The item's own content — what the submenu is called. */
+    label: React.ReactNode;
+    /** The submenu's items. */
+    children?: React.ReactNode;
+    /** Focusable, announced, and it opens nothing. `aria-disabled`, for the reason `Menu.Item` gives. */
+    disabled?: boolean;
+    /** Which side of its item the submenu sits on. Default `'end'` — beside it, on the side the text runs towards. */
+    side?: AnchorSide;
+    /** Which of the item's edges to line the submenu up with. Default `'start'`. */
+    align?: AnchorAlign;
+    /** The gap between item and submenu, on the ÷4 spacing scale. Default 0 — a submenu abuts its menu. */
+    offset?: number;
+    /** Whether a side with no room may be swapped for its opposite. Default `true`. */
+    flip?: boolean;
+    /** Attributes for the item that opens it — the submenu's own go in `props`. */
+    itemProps?: React.ButtonHTMLAttributes<HTMLButtonElement>;
+}
+/**
+ * A menu button and its menu, on the platform's own Popover API: `<Menu>` is the button's menu, and every
+ * `Menu.Sub` inside it is another popover nested in that one.
+ *
+ * ```tsx
+ * <Menu trigger={(t) => <Button {...t}>Actions</Button>}>
+ *   <Menu.Item onSelect={duplicate}>Duplicate</Menu.Item>
+ *   <Menu.Item disabled>Move</Menu.Item>
+ *   <Menu.Separator />
+ *   <Menu.CheckboxItem checked={compact} onCheckedChange={setCompact}>Compact rows</Menu.CheckboxItem>
+ *   <Menu.Sub label="Share">
+ *     <Menu.Item onSelect={copyLink}>Copy link</Menu.Item>
+ *   </Menu.Sub>
+ * </Menu>
+ * ```
+ *
+ * **What the platform owns**, measured in Chrome 152: the top layer, so the menu paints over every
+ * stacking context and outside every clipped ancestor with no portal and no `z-index`; light dismiss, so
+ * Escape and a press outside close it — Escape closing the innermost submenu first, one layer per press;
+ * the toggle from the trigger, including the press that closes an open menu from its own button; and
+ * focus return to whatever had focus before the menu opened. A submenu is a popover nested inside its
+ * menu, so opening one leaves its parent open, and closing the menu closes every submenu with it.
+ *
+ * **What is written here** is the ARIA, the arrow keys, typeahead, and the focus the platform does not
+ * move: into the first item on open, and back onto a submenu's own item when that submenu closes — the
+ * platform returns focus for the outermost layer only.
+ *
+ * **The menu is always rendered**, and closed means `display: none`, which is what lets the browser own
+ * show and hide; the exit is therefore a CSS transition rather than a `<Presence>`. A menu whose items are
+ * expensive should be gated by the consumer: `{open && <Items />}`.
+ *
+ * **The menu keeps the side it chose when it opened**, since Chrome never re-evaluates
+ * `position-try-fallbacks` for an element in the top layer (measured in 152) — so a menu left open while
+ * the page scrolls does not flip. Every open picks the right side.
+ *
+ * Where the browser has no Popover API each layer is an `Overlay` — a portal — with `useDismiss` and
+ * `useFocusReturn` supplying what the platform otherwise would.
+ *
+ * @a11y `role="menu"` on the panel, named by `label`, `labelledBy` or its trigger; `menuitem`,
+ * `menuitemcheckbox` and `menuitemradio` on the items, with `aria-checked` on the last two, `role="group"`
+ * around a titled section and `role="separator"` between them.
+ * @a11y The trigger carries `aria-haspopup="menu"`, `aria-expanded` and `aria-controls`; a submenu's item
+ * carries the same three, which is what says it opens another menu.
+ * @a11y A disabled item is `aria-disabled` and stays focusable, as APG asks — the `disabled` attribute
+ * would take it out of the keyboard's reach and silence it.
+ * @keyboard Enter / Space — On the trigger, opens the menu with the first item focused. On an item,
+ * chooses it. On a submenu's item, opens the submenu.
+ * @keyboard Down / Up — On the trigger, opens the menu at its first or last item. Inside, moves between
+ * items and wraps at the ends.
+ * @keyboard Home / End — The first or the last item.
+ * @keyboard Right / Left — Opens the submenu of the item that has focus, and closes the submenu focus is
+ * in — the other way round in a right-to-left menu, which is APG's rule and the reading order's.
+ * @keyboard Escape — Closes the innermost menu and puts focus back on what opened it.
+ * @keyboard Tab — Closes the menu and moves focus on, as APG asks.
+ * @keyboard A printable character — Typeahead: jumps to the item whose text starts with what was typed,
+ * and the same letter again cycles through the items starting with it.
+ * @pattern https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/
+ */
+declare function MenuImpl<TKey extends keyof ComponentsAndVariants = 'menu'>(props: MenuProps<TKey>): import("react").JSX.Element;
+/**
+ * A submenu: an item that opens a menu of its own. The panel is declared beside its item, *inside* the
+ * menu it belongs to, which is what makes it a nested popover — so opening it leaves the parent menu open
+ * and a press inside it is a press inside the parent (measured in Chrome 152).
+ *
+ * @a11y The item carries `role="menuitem"`, `aria-haspopup="menu"` and `aria-expanded`, and the submenu is
+ * named after it.
+ * @keyboard Right / Enter / Space — Opens it and focuses its first item. Left in a right-to-left menu,
+ * which is the reading order rather than the key.
+ * @keyboard Left / Escape — Closes it and puts focus back on the item that opened it.
+ */
+declare function MenuSub<TKey extends keyof ComponentsAndVariants = 'menu'>(props: MenuSubProps<TKey>): import("react").JSX.Element;
+/** One command in the menu. A `<button>`, so Enter and Space are the browser's. */
+declare function MenuItem<TKey extends keyof ComponentsAndVariants = 'menu.item'>(props: MenuItemProps<TKey>): import("react").JSX.Element;
+/** An item that carries a state of its own: `role="menuitemcheckbox"` and a tick. */
+declare function MenuCheckboxItem<TKey extends keyof ComponentsAndVariants = 'menu.item'>(props: MenuCheckboxItemProps<TKey>): import("react").JSX.Element;
+/** A set of items of which one is chosen: `role="group"`, and `menuitemradio` inside it. */
+declare function MenuRadioGroup<TKey extends keyof ComponentsAndVariants = 'menu.group'>(props: MenuRadioGroupProps<TKey>): import("react").JSX.Element;
+/** One of a radio group's choices. Checked when its `value` is the group's. */
+declare function MenuRadioItem<TKey extends keyof ComponentsAndVariants = 'menu.item'>(props: MenuRadioItemProps<TKey>): import("react").JSX.Element;
+/**
+ * A titled section. The heading names the group through `aria-labelledby`, so the items inside are read
+ * as a set rather than as a run of unrelated commands.
+ */
+declare function MenuGroup<TKey extends keyof ComponentsAndVariants = 'menu.group'>(props: MenuGroupProps<TKey>): import("react").JSX.Element;
+/** The line between two sections. `role="separator"`, which a menu is allowed to own. */
+declare function MenuSeparator<TKey extends keyof ComponentsAndVariants = 'menu.separator'>(props: MenuSeparatorProps<TKey>): import("react").JSX.Element;
+declare const Menu: typeof MenuImpl & {
+    Item: typeof MenuItem;
+    CheckboxItem: typeof MenuCheckboxItem;
+    RadioGroup: typeof MenuRadioGroup;
+    RadioItem: typeof MenuRadioItem;
+    Group: typeof MenuGroup;
+    Separator: typeof MenuSeparator;
+    Sub: typeof MenuSub;
+};
+export default Menu;