@windmorph/react 0.0.0-stage → 0.1.1

package/dist/composites/button-group/ButtonGroup.js

@@ -0,0 +1,270 @@
+"use client";
+import { cn } from "../../utils/cn.js";
+import { ToggleGroupStateContext } from "../../primitives/ButtonBase.js";
+import { ButtonContext } from "../../components/button/ButtonContext.js";
+import { Button } from "../../components/button/Button.js";
+import { useWarnOnce } from "../../utils/warn-once.js";
+import { IconButton } from "../../components/icon-button/IconButton.js";
+import { buttonGroupStyles } from "./button-group-styles.js";
+import { MenuTrigger } from "../../components/menu/menu-trigger.js";
+import { DomDirectionLocale } from "../../primitives/DomDirectionLocale.js";
+import { focusCheckedRadio, notePointerDown, radioGroupKeyDown } from "../../utils/radio-group-keys.js";
+import { toolbarKeyDown } from "../../utils/toolbar-keys.js";
+import { LazyOverflowMenuList } from "./lazy-overflow-menu.js";
+import { useOverflow } from "./use-overflow.js";
+import { usePressExpansion } from "./use-press-expansion.js";
+import { Children, isValidElement, useContext, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { mergeProps, mergeRefs, useObjectRef, useToggleButtonGroup, useToolbar } from "react-aria";
+import { useToggleGroupState } from "react-stately";
+//#region src/composites/button-group/ButtonGroup.tsx
+/** Material Symbols `more_vert` (Apache-2.0), the overflow indicator's icon. */
+function MoreVertIcon() {
+	return /* @__PURE__ */ jsx("svg", {
+		viewBox: "0 -960 960 960",
+		fill: "currentColor",
+		children: /* @__PURE__ */ jsx("path", { d: "M480-160q-33 0-56.5-23.5T400-240q0-33 23.5-56.5T480-320q33 0 56.5 23.5T560-240q0 33-23.5 56.5T480-160Zm0-240q-33 0-56.5-23.5T400-480q0-33 23.5-56.5T480-560q33 0 56.5 23.5T560-480q0 33-23.5 56.5T480-400Zm0-240q-33 0-56.5-23.5T400-720q0-33 23.5-56.5T480-800q33 0 56.5 23.5T560-720q0 33-23.5 56.5T480-640Z" })
+	});
+}
+const DEFAULT_LABELS = { more: "More options" };
+const ICON_BUTTON_VARIANTS = [
+	"filled",
+	"tonal",
+	"outlined"
+];
+/** The icon button variant a group's `buttonVariant` implies, if it exists for icon buttons. */
+function iconVariantOf(variant) {
+	return variant && ICON_BUTTON_VARIANTS.includes(variant) ? variant : void 0;
+}
+function positionOf(index, count) {
+	if (count < 2) return void 0;
+	if (index === 0) return "leading";
+	if (index === count - 1) return "trailing";
+	return "middle";
+}
+/** The group's ref, also reporting its element to `DomDirectionLocale`. */
+function useGroupRef(ref, directionRef) {
+	const merged = useMemo(() => mergeRefs(ref, directionRef), [ref, directionRef]);
+	return useObjectRef(merged);
+}
+/**
+* M3 Expressive button group. Shares size, shape, variant and disabled with its `Button`
+* and `IconButton` children. A standard group grows a pressed button while its neighbours
+* shrink; a `connected` group joins the buttons with shared inner corners and, by default,
+* only changes the pressed button's shape (`expandedRatio` opts it into the bump). Tab reaches the group and the arrow keys move
+* between its buttons, wrapping, with Home and End (a `toolbar`). With `selectionMode`, toggle
+* buttons that have a `value` form a single or multiple selection; a single selection is a
+* radio group, whose arrow keys select as they move.
+*
+* Children must be direct `Button` / `IconButton` elements so each gets its position.
+*
+* @example
+* <ButtonGroup variant="connected" selectionMode="single" defaultSelectedKeys={['week']}
+*   aria-label="Calendar view">
+*   <Button toggle value="day">Day</Button>
+*   <Button toggle value="week">Week</Button>
+*   <Button toggle value="month">Month</Button>
+* </ButtonGroup>
+*/
+function ButtonGroup(props) {
+	return /* @__PURE__ */ jsx(DomDirectionLocale, { children: (directionRef) => /* @__PURE__ */ jsx(ButtonGroupRoot, {
+		...props,
+		directionRef
+	}) });
+}
+function ButtonGroupRoot({ variant = "standard", size, shape, buttonVariant, disabled, selectionMode = "none", selectedKeys, defaultSelectedKeys, onSelectionChange, deselectable = true, expandedRatio, overflow = false, labels, className, classNames, children, ref, directionRef, ...props }) {
+	const domRef = useGroupRef(ref, directionRef);
+	const parent = useContext(ButtonContext);
+	const hasSelection = selectionMode !== "none";
+	const currentKeys = useRef(/* @__PURE__ */ new Set());
+	const handleSelectionChange = (keys) => {
+		const previous = currentKeys.current;
+		if (keys.size === previous.size && [...keys].every((key) => previous.has(key))) return;
+		onSelectionChange?.(keys);
+	};
+	const state = useToggleGroupState({
+		selectionMode: hasSelection ? selectionMode : "single",
+		selectedKeys,
+		defaultSelectedKeys,
+		onSelectionChange: handleSelectionChange,
+		disallowEmptySelection: !deselectable,
+		isDisabled: disabled
+	});
+	const { groupProps } = useToggleButtonGroup({
+		...props,
+		isDisabled: disabled,
+		orientation: "horizontal"
+	}, state, domRef);
+	const { toolbarProps } = useToolbar({
+		...props,
+		orientation: "horizontal"
+	}, domRef);
+	const groupAria = withGroupKeys(hasSelection ? groupProps : toolbarProps, selectionMode === "single");
+	useLayoutEffect(() => {
+		currentKeys.current = state.selectedKeys;
+	});
+	usePressExpansion(domRef, expandedRatio ?? (variant === "standard" ? .15 : 0));
+	const groupSize = size ?? parent.size ?? "sm";
+	const iconButtonVariant = iconVariantOf(buttonVariant);
+	const shared = useMemo(() => ({
+		variant: buttonVariant ?? parent.variant,
+		size: size ?? parent.size,
+		shape: shape ?? parent.shape,
+		disabled: disabled ?? parent.disabled,
+		iconButtonVariant: iconButtonVariant ?? parent.iconButtonVariant,
+		density: parent.density
+	}), [
+		buttonVariant,
+		iconButtonVariant,
+		size,
+		shape,
+		disabled,
+		parent
+	]);
+	const items = Children.toArray(children).filter(isValidElement);
+	const visible = useOverflow(domRef, overflow, items.length);
+	const overflowing = overflow && visible < items.length;
+	useGroupWarnings(variant, items, buttonVariant, iconButtonVariant);
+	const shown = overflowing ? visible + 1 : items.length;
+	const contextFor = (index) => variant === "connected" ? {
+		...shared,
+		connected: positionOf(index, shown)
+	} : shared;
+	const content = items.map((child, index) => /* @__PURE__ */ jsx(ButtonContext, {
+		value: contextFor(Math.min(index, shown - 1)),
+		children: child
+	}, child.key ?? index));
+	if (overflow) content.push(/* @__PURE__ */ jsx(ButtonContext, {
+		value: contextFor(shown - 1),
+		children: /* @__PURE__ */ jsx(OverflowMenu, {
+			groupRef: domRef,
+			hidden: items.slice(visible),
+			offset: visible,
+			label: labels?.more ?? DEFAULT_LABELS.more,
+			selectionMode,
+			selectedKeys: state.selectedKeys,
+			disabled: Boolean(disabled ?? parent.disabled),
+			classNames
+		})
+	}, "overflow"));
+	return /* @__PURE__ */ jsx("div", {
+		...mergeProps(props, groupAria),
+		ref: domRef,
+		"data-variant": variant,
+		"data-size": groupSize,
+		className: cn(buttonGroupStyles({
+			variant,
+			size: groupSize,
+			overflow
+		}), classNames?.root, className),
+		children: hasSelection ? /* @__PURE__ */ jsx(ToggleGroupStateContext, {
+			value: state,
+			children: content
+		}) : content
+	});
+}
+/**
+* The group's arrow keys. React Aria's toolbar keys (kept for Tab, which enters and leaves
+* the group as one stop) are replaced: a toolbar's arrows wrap and Home and End reach its
+* ends (WAI-ARIA APG toolbar), and a single selection is a radio group whose arrows also
+* select (APG radio group, as `RadioGroup` does) and which Tab enters at the selected
+* button. A group nested in a toolbar leaves its keys to the toolbar, as React Aria does.
+*/
+function withGroupKeys(aria, single) {
+	const ariaKeyDown = aria.onKeyDownCapture;
+	if (!ariaKeyDown) return aria;
+	return {
+		...aria,
+		onKeyDownCapture: (event) => {
+			if (event.key === "Tab") ariaKeyDown(event);
+			else if (single) radioGroupKeyDown(event);
+			else toolbarKeyDown(event, "horizontal");
+		},
+		onFocus: single ? (event) => void focusCheckedRadio(event) : void 0,
+		onPointerDownCapture: single ? notePointerDown : void 0
+	};
+}
+/**
+* Development warnings, once per group, for what the M3 button group guidelines advise
+* against: standard icon buttons and text buttons in a group ("they have no container
+* treatment"), and a connected group with nothing to select ("Avoid using a connected
+* group when none of the buttons can be toggled"). Only the variants the group or the
+* buttons set count: a toolbar's standard default doesn't.
+*/
+function useGroupWarnings(variant, items, buttonVariant, iconButtonVariant) {
+	const containerless = items.some((child) => child.type === IconButton ? (child.props.variant ?? iconButtonVariant) === "standard" : child.type === Button && (child.props.variant ?? buttonVariant) === "text");
+	const nothingToSelect = variant === "connected" && items.length > 0 && !items.some((child) => child.props.toggle);
+	useWarnOnce(containerless, "[@windmorph/react] Avoid standard icon buttons and text buttons in a ButtonGroup (M3): they have no container, so the group has nothing to shape.");
+	useWarnOnce(nothingToSelect, "[@windmorph/react] A connected ButtonGroup is for selection (M3): use toggle buttons in it, or a standard group for actions.");
+}
+/**
+* The overflow indicator (Compose `ButtonGroupDefaults.OverflowIndicator`: a filled icon
+* button with `more_vert` and a "More options" tooltip, here the group's icon button
+* variant) and its menu. Choosing an item clicks the folded button itself, so its own
+* press handler, link, toggle or group selection runs as if it had been pressed. The menu's
+* code loads once a button folds (see `LazyOverflowMenuList`); the indicator is always
+* rendered, so the group can measure it.
+*/
+function OverflowMenu({ groupRef, hidden, offset, label, selectionMode, selectedKeys, disabled, classNames }) {
+	const [pressed, setPressed] = useState(/* @__PURE__ */ new Set());
+	const elementAt = (key) => groupRef.current?.children[Number(key)];
+	const keyOf = (index) => String(offset + index);
+	const readPressed = () => setPressed(new Set(hidden.map((_, index) => keyOf(index)).filter((key) => elementAt(key)?.getAttribute("aria-pressed") === "true")));
+	const indicator = useRef(null);
+	const keepFocus = () => requestAnimationFrame(() => {
+		const active = document.activeElement;
+		if (!active || active === document.body || active.closest("[role=\"menu\"]")) indicator.current?.focus({ preventScroll: true });
+	});
+	const grouped = selectionMode !== "none";
+	const hasToggles = hidden.some((child) => child.props.toggle);
+	const menuSelectionMode = grouped ? selectionMode : hasToggles ? "multiple" : "none";
+	const selected = hidden.map((child, index) => ({
+		child,
+		key: keyOf(index)
+	})).filter(({ child, key }) => grouped ? child.props.value !== void 0 && selectedKeys.has(child.props.value) : pressed.has(key)).map(({ key }) => key);
+	const disabledKeys = hidden.map((child, index) => ({
+		child,
+		key: keyOf(index)
+	})).filter(({ child }) => disabled || child.props.disabled).map(({ key }) => key);
+	return /* @__PURE__ */ jsxs(MenuTrigger, {
+		onOpenChange: (open) => open ? readPressed() : keepFocus(),
+		children: [/* @__PURE__ */ jsx(IconButton, {
+			icon: /* @__PURE__ */ jsx(MoreVertIcon, {}),
+			"aria-label": label,
+			className: classNames?.overflowButton,
+			onPressStart: (event) => {
+				indicator.current = event.target;
+			}
+		}), hidden.length > 0 && /* @__PURE__ */ jsx(LazyOverflowMenuList, {
+			items: hidden.map((child, index) => ({
+				key: keyOf(index),
+				...describe(child, selected.includes(keyOf(index))),
+				checkable: grouped ? child.props.value !== void 0 : Boolean(child.props.toggle)
+			})),
+			selectionMode: menuSelectionMode,
+			selectedKeys: selected,
+			disabledKeys,
+			classNames: { panel: classNames?.overflowMenu },
+			onAction: (key) => {
+				elementAt(String(key))?.click();
+				setTimeout(readPressed);
+			}
+		})]
+	});
+}
+/** A folded button's menu label and icon. */
+function describe(child, isSelected) {
+	const { props } = child;
+	if (child.type === IconButton) return {
+		label: props["aria-label"],
+		icon: isSelected && props.selectedIcon || props.icon
+	};
+	return {
+		label: props.children,
+		icon: isSelected && props.selectedLeadingIcon || props.leadingIcon
+	};
+}
+//#endregion
+export { ButtonGroup };
+
+//# sourceMappingURL=ButtonGroup.js.map

package/dist/composites/button-group/ButtonGroup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ButtonGroup.js","names":[],"sources":["../../../src/composites/button-group/ButtonGroup.tsx"],"sourcesContent":["'use client';\n\nimport {\n  Children,\n  isValidElement,\n  useContext,\n  useLayoutEffect,\n  useMemo,\n  useRef,\n  useState,\n  type ComponentPropsWithRef,\n  type HTMLAttributes,\n  type Key,\n  type ReactElement,\n  type ReactNode,\n  type Ref,\n  type RefCallback,\n  type RefObject,\n} from 'react';\nimport { mergeProps, mergeRefs, useObjectRef, useToggleButtonGroup, useToolbar } from 'react-aria';\nimport { useToggleGroupState } from 'react-stately';\nimport { Button } from '../../components/button/Button';\nimport type { ButtonShape, ButtonSize, ButtonVariant } from '../../components/button/button-styles';\nimport {\n  ButtonContext,\n  ToggleGroupStateContext,\n  type ButtonContextValue,\n} from '../../components/button/ButtonContext';\nimport { IconButton } from '../../components/icon-button/IconButton';\nimport type { IconButtonVariant } from '../../components/icon-button/icon-button-styles';\nimport { MenuTrigger } from '../../components/menu/menu-trigger';\nimport { DomDirectionLocale } from '../../primitives/DomDirectionLocale';\nimport { cn } from '../../utils/cn';\nimport {\n  focusCheckedRadio,\n  notePointerDown,\n  radioGroupKeyDown,\n} from '../../utils/radio-group-keys';\nimport { toolbarKeyDown } from '../../utils/toolbar-keys';\nimport type { VariantProps } from '../../utils/tv';\nimport { useWarnOnce } from '../../utils/warn-once';\nimport { buttonGroupStyles } from './button-group-styles';\nimport { LazyOverflowMenuList } from './lazy-overflow-menu';\nimport { useOverflow } from './use-overflow';\nimport { usePressExpansion } from './use-press-expansion';\n\n/** Material Symbols `more_vert` (Apache-2.0), the overflow indicator's icon. */\nfunction MoreVertIcon() {\n  return (\n    <svg viewBox=\"0 -960 960 960\" fill=\"currentColor\">\n      <path d=\"M480-160q-33 0-56.5-23.5T400-240q0-33 23.5-56.5T480-320q33 0 56.5 23.5T560-240q0 33-23.5 56.5T480-160Zm0-240q-33 0-56.5-23.5T400-480q0-33 23.5-56.5T480-560q33 0 56.5 23.5T560-480q0 33-23.5 56.5T480-400Zm0-240q-33 0-56.5-23.5T400-720q0-33 23.5-56.5T480-800q33 0 56.5 23.5T560-720q0 33-23.5 56.5T480-640Z\" />\n    </svg>\n  );\n}\n\nexport type ButtonGroupVariant = NonNullable<VariantProps<typeof buttonGroupStyles>['variant']>;\nexport type ButtonGroupSelectionMode = 'none' | 'single' | 'multiple';\n\n/** Text the group adds for assistive tech and its tooltip; translate it for your locale. */\nexport interface ButtonGroupLabels {\n  /** The overflow indicator's name and tooltip. @default \"More options\" */\n  more: string;\n}\n\nconst DEFAULT_LABELS: ButtonGroupLabels = { more: 'More options' };\n\nexport interface ButtonGroupClassNames {\n  /** The group's outer element; `className` is merged here too. */\n  root?: string;\n  /** The overflow indicator, the \"More options\" icon button (`overflow`). */\n  overflowButton?: string;\n  /** The overflow indicator's menu of folded buttons (`overflow`). */\n  overflowMenu?: string;\n}\n\nexport interface ButtonGroupProps extends Omit<\n  ComponentPropsWithRef<'div'>,\n  'onChange' | 'defaultValue'\n> {\n  /**\n   * `standard` spaces the buttons apart (18 / 12 / 8px by size); `connected` joins them 2px\n   * apart with shared inner corners across the container's width (the M3 Expressive\n   * replacement for segmented buttons). A standard group grows a pressed button into its\n   * neighbours' space; a connected one only changes its shape unless `expandedRatio` is set.\n   * @default \"standard\"\n   */\n  variant?: ButtonGroupVariant;\n  /**\n   * Size shared by every button and icon button in the group; it also sets the spacing.\n   * Unset, the buttons keep their own (or an enclosing toolbar's) size.\n   * @default \"sm\"\n   */\n  size?: ButtonSize;\n  /**\n   * Shape shared by the buttons. A `square` connected group gives its outer corners the\n   * size of its inner ones (4 / 8 / 8 / 16 / 20px). Unset, the buttons keep their own.\n   * @default \"round\"\n   */\n  shape?: ButtonShape;\n  /**\n   * Variant shared by every `Button` in the group. `filled`, `tonal` and `outlined` reach\n   * the `IconButton`s too, so a group never mixes colour styles; a button's own `variant`\n   * wins. Unset, the buttons keep their own.\n   * @default \"filled\"\n   */\n  buttonVariant?: ButtonVariant;\n  /** Disables every button in the group. @default false */\n  disabled?: boolean;\n  /**\n   * Lets toggle buttons with a `value` act as one selection. `single` behaves like\n   * radio buttons, `multiple` like checkboxes. @default \"none\"\n   */\n  selectionMode?: ButtonGroupSelectionMode;\n  /** Controlled selection: the `value`s of the selected toggle buttons. */\n  selectedKeys?: Iterable<string>;\n  /** Initial selection when uncontrolled. */\n  defaultSelectedKeys?: Iterable<string>;\n  /** Called with the selected toggle buttons' `value`s when the selection changes. */\n  onSelectionChange?: (keys: Set<string>) => void;\n  /**\n   * The last selected button can be deselected, leaving none. `false` keeps at least one\n   * selected. @default true\n   */\n  deselectable?: boolean;\n  /**\n   * How much a pressed button grows, as a fraction of its width; its neighbours shrink by the\n   * same amount and the group keeps its width. `0` turns it off. Standard groups default to\n   * 0.15. Connected groups default to 0 (the spec: they \"don't affect adjacent buttons\", as\n   * in Compose's connected sample); set a ratio to opt in, as Compose can by combining a\n   * button group's `animateWidth` with the connected shapes. Under reduced motion there's\n   * no bump. @default 0.15, or 0 when `variant` is \"connected\"\n   */\n  expandedRatio?: number;\n  /**\n   * Folds the trailing buttons that don't fit into a menu behind a trailing \"More options\"\n   * icon button (M3: \"Buttons at the trailing edge of the button group can be customized to\n   * collapse into an overflow menu at smaller breakpoints\"). The group then fills its\n   * container's width and re-measures as it resizes. Each folded button becomes a menu\n   * item with its label (an icon button's `aria-label`) and icon; disabled buttons stay\n   * disabled, and toggles show their selection. Choosing an item presses the button.\n   * @default false\n   */\n  overflow?: boolean;\n  /**\n   * Text for assistive tech, e.g. the overflow indicator's name.\n   * @default { more: \"More options\" }\n   */\n  labels?: Partial<ButtonGroupLabels>;\n  /** Classes for each part. `classNames.root` is merged with `className`. */\n  classNames?: ButtonGroupClassNames;\n  children?: ReactNode;\n}\n\n/** The props the group reads from its children for the overflow menu and warnings. */\ninterface ChildProps {\n  variant?: string;\n  toggle?: boolean;\n  value?: string;\n  disabled?: boolean;\n  children?: ReactNode;\n  leadingIcon?: ReactElement;\n  selectedLeadingIcon?: ReactElement;\n  icon?: ReactElement;\n  selectedIcon?: ReactElement;\n  'aria-label'?: string;\n}\n\nconst ICON_BUTTON_VARIANTS: readonly string[] = ['filled', 'tonal', 'outlined'];\n\n/** The icon button variant a group's `buttonVariant` implies, if it exists for icon buttons. */\nfunction iconVariantOf(variant: ButtonVariant | undefined): IconButtonVariant | undefined {\n  return variant && ICON_BUTTON_VARIANTS.includes(variant)\n    ? (variant as IconButtonVariant)\n    : undefined;\n}\n\ntype Position = NonNullable<ButtonContextValue['connected']>;\n\nfunction positionOf(index: number, count: number): Position | undefined {\n  if (count < 2) return undefined;\n  if (index === 0) return 'leading';\n  if (index === count - 1) return 'trailing';\n  return 'middle';\n}\n\n/** The group's ref, also reporting its element to `DomDirectionLocale`. */\nfunction useGroupRef(ref: Ref<HTMLDivElement> | undefined, directionRef: RefCallback<HTMLElement>) {\n  // Arrow keys follow the laid-out direction, which React Aria reads from its locale.\n  const merged = useMemo(\n    () => mergeRefs<HTMLDivElement>(ref, directionRef as RefCallback<HTMLDivElement>),\n    [ref, directionRef],\n  );\n  return useObjectRef<HTMLDivElement>(merged);\n}\n\n/**\n * M3 Expressive button group. Shares size, shape, variant and disabled with its `Button`\n * and `IconButton` children. A standard group grows a pressed button while its neighbours\n * shrink; a `connected` group joins the buttons with shared inner corners and, by default,\n * only changes the pressed button's shape (`expandedRatio` opts it into the bump). Tab reaches the group and the arrow keys move\n * between its buttons, wrapping, with Home and End (a `toolbar`). With `selectionMode`, toggle\n * buttons that have a `value` form a single or multiple selection; a single selection is a\n * radio group, whose arrow keys select as they move.\n *\n * Children must be direct `Button` / `IconButton` elements so each gets its position.\n *\n * @example\n * <ButtonGroup variant=\"connected\" selectionMode=\"single\" defaultSelectedKeys={['week']}\n *   aria-label=\"Calendar view\">\n *   <Button toggle value=\"day\">Day</Button>\n *   <Button toggle value=\"week\">Week</Button>\n *   <Button toggle value=\"month\">Month</Button>\n * </ButtonGroup>\n */\nexport function ButtonGroup(props: ButtonGroupProps) {\n  return (\n    <DomDirectionLocale>\n      {(directionRef) => <ButtonGroupRoot {...props} directionRef={directionRef} />}\n    </DomDirectionLocale>\n  );\n}\n\nfunction ButtonGroupRoot({\n  variant = 'standard',\n  size,\n  shape,\n  buttonVariant,\n  disabled,\n  selectionMode = 'none',\n  selectedKeys,\n  defaultSelectedKeys,\n  onSelectionChange,\n  deselectable = true,\n  expandedRatio,\n  overflow = false,\n  labels,\n  className,\n  classNames,\n  children,\n  ref,\n  directionRef,\n  ...props\n}: ButtonGroupProps & { directionRef: RefCallback<HTMLElement> }) {\n  const domRef = useGroupRef(ref, directionRef);\n  const parent = useContext(ButtonContext);\n  const hasSelection = selectionMode !== 'none';\n\n  // React Stately reports a change even when the selection is unchanged (e.g. clicking\n  // the only selected button of a group that isn't `deselectable`); only real changes reach callers.\n  const currentKeys = useRef<ReadonlySet<Key>>(new Set());\n  const handleSelectionChange = (keys: Set<Key>) => {\n    const previous = currentKeys.current;\n    if (keys.size === previous.size && [...keys].every((key) => previous.has(key))) return;\n    onSelectionChange?.(keys as Set<string>);\n  };\n\n  const state = useToggleGroupState({\n    selectionMode: hasSelection ? selectionMode : 'single',\n    selectedKeys,\n    defaultSelectedKeys,\n    onSelectionChange: handleSelectionChange,\n    disallowEmptySelection: !deselectable,\n    isDisabled: disabled,\n  });\n  const { groupProps } = useToggleButtonGroup(\n    { ...props, isDisabled: disabled, orientation: 'horizontal' },\n    state,\n    domRef,\n  );\n  // Without a selection the group is a React Aria toolbar: Tab enters and leaves it as one\n  // stop, and the arrow keys move between its buttons.\n  const { toolbarProps } = useToolbar({ ...props, orientation: 'horizontal' }, domRef);\n  const groupAria = withGroupKeys(\n    hasSelection ? groupProps : toolbarProps,\n    selectionMode === 'single',\n  );\n\n  useLayoutEffect(() => {\n    currentKeys.current = state.selectedKeys;\n  });\n\n  usePressExpansion(domRef, expandedRatio ?? (variant === 'standard' ? 0.15 : 0));\n\n  const groupSize = size ?? parent.size ?? 'sm';\n  const iconButtonVariant = iconVariantOf(buttonVariant);\n  const shared = useMemo<ButtonContextValue>(\n    () => ({\n      variant: buttonVariant ?? parent.variant,\n      size: size ?? parent.size,\n      shape: shape ?? parent.shape,\n      disabled: disabled ?? parent.disabled,\n      iconButtonVariant: iconButtonVariant ?? parent.iconButtonVariant,\n      density: parent.density,\n    }),\n    [buttonVariant, iconButtonVariant, size, shape, disabled, parent],\n  );\n\n  const items = Children.toArray(children).filter(isValidElement) as ReactElement<ChildProps>[];\n  const visible = useOverflow(domRef, overflow, items.length);\n  const overflowing = overflow && visible < items.length;\n\n  useGroupWarnings(variant, items, buttonVariant, iconButtonVariant);\n\n  // Connected corners follow the buttons that show, the overflow indicator last.\n  const shown = overflowing ? visible + 1 : items.length;\n  const contextFor = (index: number): ButtonContextValue =>\n    variant === 'connected' ? { ...shared, connected: positionOf(index, shown) } : shared;\n  const content = items.map((child, index) => (\n    <ButtonContext key={child.key ?? index} value={contextFor(Math.min(index, shown - 1))}>\n      {child}\n    </ButtonContext>\n  ));\n  if (overflow) {\n    content.push(\n      <ButtonContext key=\"overflow\" value={contextFor(shown - 1)}>\n        <OverflowMenu\n          groupRef={domRef}\n          hidden={items.slice(visible)}\n          offset={visible}\n          label={labels?.more ?? DEFAULT_LABELS.more}\n          selectionMode={selectionMode}\n          selectedKeys={state.selectedKeys}\n          disabled={Boolean(disabled ?? parent.disabled)}\n          classNames={classNames}\n        />\n      </ButtonContext>,\n    );\n  }\n\n  return (\n    <div\n      {...mergeProps(props, groupAria)}\n      ref={domRef}\n      // Public styling hooks for apps, as on Button: the group's variant and the size it spaces\n      // its buttons for (its own, an enclosing toolbar's, or `sm`).\n      data-variant={variant}\n      data-size={groupSize}\n      className={cn(\n        buttonGroupStyles({ variant, size: groupSize, overflow }),\n        classNames?.root,\n        className,\n      )}\n    >\n      {hasSelection ? (\n        <ToggleGroupStateContext value={state}>{content}</ToggleGroupStateContext>\n      ) : (\n        content\n      )}\n    </div>\n  );\n}\n\n/**\n * The group's arrow keys. React Aria's toolbar keys (kept for Tab, which enters and leaves\n * the group as one stop) are replaced: a toolbar's arrows wrap and Home and End reach its\n * ends (WAI-ARIA APG toolbar), and a single selection is a radio group whose arrows also\n * select (APG radio group, as `RadioGroup` does) and which Tab enters at the selected\n * button. A group nested in a toolbar leaves its keys to the toolbar, as React Aria does.\n */\nfunction withGroupKeys(\n  aria: HTMLAttributes<HTMLElement>,\n  single: boolean,\n): HTMLAttributes<HTMLElement> {\n  const ariaKeyDown = aria.onKeyDownCapture;\n  if (!ariaKeyDown) return aria;\n  return {\n    ...aria,\n    onKeyDownCapture: (event) => {\n      if (event.key === 'Tab') ariaKeyDown(event);\n      else if (single) radioGroupKeyDown(event);\n      else toolbarKeyDown(event, 'horizontal');\n    },\n    onFocus: single ? (event) => void focusCheckedRadio(event) : undefined,\n    onPointerDownCapture: single ? notePointerDown : undefined,\n  };\n}\n\n/**\n * Development warnings, once per group, for what the M3 button group guidelines advise\n * against: standard icon buttons and text buttons in a group (\"they have no container\n * treatment\"), and a connected group with nothing to select (\"Avoid using a connected\n * group when none of the buttons can be toggled\"). Only the variants the group or the\n * buttons set count: a toolbar's standard default doesn't.\n */\nfunction useGroupWarnings(\n  variant: ButtonGroupVariant,\n  items: ReactElement<ChildProps>[],\n  buttonVariant: ButtonVariant | undefined,\n  iconButtonVariant: IconButtonVariant | undefined,\n) {\n  const containerless = items.some((child) =>\n    child.type === IconButton\n      ? (child.props.variant ?? iconButtonVariant) === 'standard'\n      : child.type === Button && (child.props.variant ?? buttonVariant) === 'text',\n  );\n  const nothingToSelect =\n    variant === 'connected' && items.length > 0 && !items.some((child) => child.props.toggle);\n  useWarnOnce(\n    containerless,\n    '[@windmorph/react] Avoid standard icon buttons and text buttons in a ButtonGroup (M3): they have no container, so the group has nothing to shape.',\n  );\n  useWarnOnce(\n    nothingToSelect,\n    '[@windmorph/react] A connected ButtonGroup is for selection (M3): use toggle buttons in it, or a standard group for actions.',\n  );\n}\n\ninterface OverflowMenuProps {\n  groupRef: RefObject<HTMLDivElement | null>;\n  /** The folded buttons, in order. */\n  hidden: ReactElement<ChildProps>[];\n  /** The index of the first folded button among the group's children. */\n  offset: number;\n  label: string;\n  selectionMode: ButtonGroupSelectionMode;\n  selectedKeys: ReadonlySet<Key>;\n  disabled: boolean;\n  classNames: ButtonGroupClassNames | undefined;\n}\n\n/**\n * The overflow indicator (Compose `ButtonGroupDefaults.OverflowIndicator`: a filled icon\n * button with `more_vert` and a \"More options\" tooltip, here the group's icon button\n * variant) and its menu. Choosing an item clicks the folded button itself, so its own\n * press handler, link, toggle or group selection runs as if it had been pressed. The menu's\n * code loads once a button folds (see `LazyOverflowMenuList`); the indicator is always\n * rendered, so the group can measure it.\n */\nfunction OverflowMenu({\n  groupRef,\n  hidden,\n  offset,\n  label,\n  selectionMode,\n  selectedKeys,\n  disabled,\n  classNames,\n}: OverflowMenuProps) {\n  // Folded standalone toggles keep their state inside them: read it when the menu opens\n  // and after each choice.\n  const [pressed, setPressed] = useState<ReadonlySet<string>>(new Set());\n  const elementAt = (key: string) =>\n    groupRef.current?.children[Number(key)] as HTMLElement | undefined;\n  const keyOf = (index: number) => String(offset + index);\n  const readPressed = () =>\n    setPressed(\n      new Set(\n        hidden\n          .map((_, index) => keyOf(index))\n          .filter((key) => elementAt(key)?.getAttribute('aria-pressed') === 'true'),\n      ),\n    );\n\n  // A choice made with the mouse closed the menu with focus still on its item, which then\n  // left with the menu and dropped focus on <body>. Once the menu has closed, focus still in\n  // it (or on the page) goes back to the indicator, as after a keyboard choice (2026-10-15).\n  const indicator = useRef<HTMLElement | null>(null);\n  const keepFocus = () =>\n    requestAnimationFrame(() => {\n      const active = document.activeElement;\n      if (!active || active === document.body || active.closest('[role=\"menu\"]')) {\n        indicator.current?.focus({ preventScroll: true });\n      }\n    });\n\n  const grouped = selectionMode !== 'none';\n  const hasToggles = hidden.some((child) => child.props.toggle);\n  const menuSelectionMode = grouped ? selectionMode : hasToggles ? 'multiple' : 'none';\n  const selected = hidden\n    .map((child, index) => ({ child, key: keyOf(index) }))\n    .filter(({ child, key }) =>\n      grouped\n        ? child.props.value !== undefined && selectedKeys.has(child.props.value)\n        : pressed.has(key),\n    )\n    .map(({ key }) => key);\n  const disabledKeys = hidden\n    .map((child, index) => ({ child, key: keyOf(index) }))\n    .filter(({ child }) => disabled || child.props.disabled)\n    .map(({ key }) => key);\n\n  return (\n    <MenuTrigger onOpenChange={(open) => (open ? readPressed() : keepFocus())}>\n      <IconButton\n        icon={<MoreVertIcon />}\n        aria-label={label}\n        className={classNames?.overflowButton}\n        onPressStart={(event) => {\n          indicator.current = event.target as HTMLElement;\n        }}\n      />\n      {hidden.length > 0 && (\n        <LazyOverflowMenuList\n          items={hidden.map((child, index) => ({\n            key: keyOf(index),\n            ...describe(child, selected.includes(keyOf(index))),\n            // Only a toggle (or a button in the group's selection) is checkable; an action\n            // stays a plain item even when the menu is selectable.\n            checkable: grouped ? child.props.value !== undefined : Boolean(child.props.toggle),\n          }))}\n          selectionMode={menuSelectionMode}\n          selectedKeys={selected}\n          disabledKeys={disabledKeys}\n          classNames={{ panel: classNames?.overflowMenu }}\n          onAction={(key) => {\n            elementAt(String(key))?.click();\n            // The button updates once this event is handled.\n            setTimeout(readPressed);\n          }}\n        />\n      )}\n    </MenuTrigger>\n  );\n}\n\n/** A folded button's menu label and icon. */\nfunction describe(child: ReactElement<ChildProps>, isSelected: boolean) {\n  const { props } = child;\n  if (child.type === IconButton) {\n    return {\n      label: props['aria-label'],\n      icon: (isSelected && props.selectedIcon) || props.icon,\n    };\n  }\n  return {\n    label: props.children,\n    icon: (isSelected && props.selectedLeadingIcon) || props.leadingIcon,\n  };\n}\n"],"mappings":"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"}

package/dist/composites/button-group/button-group-styles.d.ts

@@ -0,0 +1,73 @@
+//#region src/composites/button-group/button-group-styles.d.ts
+/**
+ * Variant definitions for `ButtonGroup`, from the M3 Expressive button group specs
+ * (2026-10-13). Standard groups space their buttons 18 / 12 / 8 / 8 / 8px apart (XS–XL), so
+ * the XS and S buttons' 48px targets don't overlap. Connected groups are 2px apart at every
+ * size, and span their container with the buttons sharing the extra width ("The connected
+ * button group should span the width of the page or surface it's placed on"); a consumer
+ * `w-fit` (or a `max-w-*`) narrows it. Connected buttons are equally wide (2026-10-13, as
+ * Compose's connected sample gives each `weight(1f)`): the group is a grid of `1fr` columns
+ * (2026-10-15), so a definite width is shared equally, and a group sized by its content gives
+ * every button the widest one's natural width, never squeezing a longer label into its
+ * padding. The columns are `minmax(auto, 1fr)`, so with too little room a button shrinks no
+ * further than its own minimum width, as in a flex row. `auto-cols-auto` on the group sizes
+ * them by their content instead. While the press
+ * bump pins the buttons' widths (`data-pinned`), the group lays them out as a flex row of the
+ * same widths, so the bump can animate their `flex-basis`.
+ *
+ * With `overflow`, a standard group fills its container's width too, so it can measure the
+ * room it has; its buttons stay at the start. Buttons folded into the overflow menu carry
+ * `data-overflow-hidden`; while measuring, the group is a flex row of its content's width
+ * and no button grows.
+ */
+export declare const buttonGroupStyles: import("tailwind-variants").TVReturnType<{
+  variant: {
+    standard: "inline-flex";
+    connected: "grid w-full grid-flow-col auto-cols-[1fr] gap-[2px] data-pinned:flex";
+  };
+  size: {
+    xs: "";
+    sm: "";
+    md: "";
+    lg: "";
+    xl: "";
+  };
+  overflow: {
+    true: "w-full min-w-0 *:data-overflow-hidden:hidden data-measuring:flex data-measuring:w-max data-measuring:*:grow-0";
+    false: "";
+  };
+}, undefined, "items-center", {
+  variant: {
+    standard: "inline-flex";
+    connected: "grid w-full grid-flow-col auto-cols-[1fr] gap-[2px] data-pinned:flex";
+  };
+  size: {
+    xs: "";
+    sm: "";
+    md: "";
+    lg: "";
+    xl: "";
+  };
+  overflow: {
+    true: "w-full min-w-0 *:data-overflow-hidden:hidden data-measuring:flex data-measuring:w-max data-measuring:*:grow-0";
+    false: "";
+  };
+}, undefined, import("tailwind-variants").TVReturnTypeLike<{
+  variant: {
+    standard: "inline-flex";
+    connected: "grid w-full grid-flow-col auto-cols-[1fr] gap-[2px] data-pinned:flex";
+  };
+  size: {
+    xs: "";
+    sm: "";
+    md: "";
+    lg: "";
+    xl: "";
+  };
+  overflow: {
+    true: "w-full min-w-0 *:data-overflow-hidden:hidden data-measuring:flex data-measuring:w-max data-measuring:*:grow-0";
+    false: "";
+  };
+}, undefined>>;
+//#endregion
+//# sourceMappingURL=button-group-styles.d.ts.map

package/dist/composites/button-group/button-group-styles.js

@@ -0,0 +1,87 @@
+import { tv } from "../../utils/tv.js";
+//#region src/composites/button-group/button-group-styles.ts
+/**
+* Variant definitions for `ButtonGroup`, from the M3 Expressive button group specs
+* (2026-10-13). Standard groups space their buttons 18 / 12 / 8 / 8 / 8px apart (XS–XL), so
+* the XS and S buttons' 48px targets don't overlap. Connected groups are 2px apart at every
+* size, and span their container with the buttons sharing the extra width ("The connected
+* button group should span the width of the page or surface it's placed on"); a consumer
+* `w-fit` (or a `max-w-*`) narrows it. Connected buttons are equally wide (2026-10-13, as
+* Compose's connected sample gives each `weight(1f)`): the group is a grid of `1fr` columns
+* (2026-10-15), so a definite width is shared equally, and a group sized by its content gives
+* every button the widest one's natural width, never squeezing a longer label into its
+* padding. The columns are `minmax(auto, 1fr)`, so with too little room a button shrinks no
+* further than its own minimum width, as in a flex row. `auto-cols-auto` on the group sizes
+* them by their content instead. While the press
+* bump pins the buttons' widths (`data-pinned`), the group lays them out as a flex row of the
+* same widths, so the bump can animate their `flex-basis`.
+*
+* With `overflow`, a standard group fills its container's width too, so it can measure the
+* room it has; its buttons stay at the start. Buttons folded into the overflow menu carry
+* `data-overflow-hidden`; while measuring, the group is a flex row of its content's width
+* and no button grows.
+*/
+const buttonGroupStyles = tv({
+	base: "items-center",
+	variants: {
+		variant: {
+			standard: "inline-flex",
+			connected: "grid w-full grid-flow-col auto-cols-[1fr] gap-[2px] data-pinned:flex"
+		},
+		size: {
+			xs: "",
+			sm: "",
+			md: "",
+			lg: "",
+			xl: ""
+		},
+		overflow: {
+			true: "w-full min-w-0 *:data-overflow-hidden:hidden data-measuring:flex data-measuring:w-max data-measuring:*:grow-0",
+			false: ""
+		}
+	},
+	compoundVariants: [
+		{
+			variant: "standard",
+			overflow: true,
+			class: "flex"
+		},
+		{
+			variant: "standard",
+			size: "xs",
+			class: [
+				"gap-(--m3-button-group-gap)",
+				"[--m3-button-group-gap:max(18px,calc(48px-max(24px,calc(32px+var(--md-sys-density,0)*4px))))]",
+				"has-[[data-tokens~=md-comp-icon-button][data-width=narrow]]:[--m3-button-group-gap:max(18px,calc(48px-max(24px,calc(28px+var(--md-sys-density,0)*4px))))]"
+			]
+		},
+		{
+			variant: "standard",
+			size: "sm",
+			class: [
+				"gap-(--m3-button-group-gap)",
+				"[--m3-button-group-gap:max(12px,calc(8px-var(--md-sys-density,0)*4px))]",
+				"has-[[data-tokens~=md-comp-icon-button][data-width=narrow]]:[--m3-button-group-gap:max(12px,calc(48px-max(28px,calc(32px+var(--md-sys-density,0)*4px))))]"
+			]
+		},
+		{
+			variant: "standard",
+			size: "md",
+			class: ["gap-(--m3-button-group-gap) [--m3-button-group-gap:8px]", "has-[[data-tokens~=md-comp-icon-button][data-width=narrow]]:[--m3-button-group-gap:max(8px,calc(var(--md-sys-density,0)*-4px))]"]
+		},
+		{
+			variant: "standard",
+			size: ["lg", "xl"],
+			class: "gap-[8px]"
+		}
+	],
+	defaultVariants: {
+		variant: "standard",
+		size: "sm",
+		overflow: false
+	}
+});
+//#endregion
+export { buttonGroupStyles };
+
+//# sourceMappingURL=button-group-styles.js.map

package/dist/composites/button-group/button-group-styles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"button-group-styles.js","names":[],"sources":["../../../src/composites/button-group/button-group-styles.ts"],"sourcesContent":["import { tv } from '../../utils/tv';\n\n/**\n * Variant definitions for `ButtonGroup`, from the M3 Expressive button group specs\n * (2026-10-13). Standard groups space their buttons 18 / 12 / 8 / 8 / 8px apart (XS–XL), so\n * the XS and S buttons' 48px targets don't overlap. Connected groups are 2px apart at every\n * size, and span their container with the buttons sharing the extra width (\"The connected\n * button group should span the width of the page or surface it's placed on\"); a consumer\n * `w-fit` (or a `max-w-*`) narrows it. Connected buttons are equally wide (2026-10-13, as\n * Compose's connected sample gives each `weight(1f)`): the group is a grid of `1fr` columns\n * (2026-10-15), so a definite width is shared equally, and a group sized by its content gives\n * every button the widest one's natural width, never squeezing a longer label into its\n * padding. The columns are `minmax(auto, 1fr)`, so with too little room a button shrinks no\n * further than its own minimum width, as in a flex row. `auto-cols-auto` on the group sizes\n * them by their content instead. While the press\n * bump pins the buttons' widths (`data-pinned`), the group lays them out as a flex row of the\n * same widths, so the bump can animate their `flex-basis`.\n *\n * With `overflow`, a standard group fills its container's width too, so it can measure the\n * room it has; its buttons stay at the start. Buttons folded into the overflow menu carry\n * `data-overflow-hidden`; while measuring, the group is a flex row of its content's width\n * and no button grows.\n */\nexport const buttonGroupStyles = tv({\n  base: 'items-center',\n  variants: {\n    variant: {\n      standard: 'inline-flex',\n      connected: 'grid w-full grid-flow-col auto-cols-[1fr] gap-[2px] data-pinned:flex',\n    },\n    size: { xs: '', sm: '', md: '', lg: '', xl: '' },\n    overflow: {\n      true: 'w-full min-w-0 *:data-overflow-hidden:hidden data-measuring:flex data-measuring:w-max data-measuring:*:grow-0',\n      false: '',\n    },\n  },\n  compoundVariants: [\n    { variant: 'standard', overflow: true, class: 'flex' },\n    // XS and S: the spec's 18 / 12px, growing as density shrinks the icon buttons (their\n    // default widths: XS max(24px, 32px + 4px a step), S 40px + 4px a step), so neighbouring\n    // centres stay 48px apart and their 48px touch targets never overlap (2026-10-15). A\n    // group holding a narrow icon button spaces by the narrow width instead (XS max(24px,\n    // 28px + 4px a step), S max(28px, 32px + 4px a step), M 48px + 4px a step), so the gap is\n    // max(spec, 48px − narrow width) (2026-10-17). The gap is a variable, so a consumer `gap-*`\n    // still replaces it.\n    {\n      variant: 'standard',\n      size: 'xs',\n      class: [\n        'gap-(--m3-button-group-gap)',\n        '[--m3-button-group-gap:max(18px,calc(48px-max(24px,calc(32px+var(--md-sys-density,0)*4px))))]',\n        'has-[[data-tokens~=md-comp-icon-button][data-width=narrow]]:[--m3-button-group-gap:max(18px,calc(48px-max(24px,calc(28px+var(--md-sys-density,0)*4px))))]',\n      ],\n    },\n    {\n      variant: 'standard',\n      size: 'sm',\n      class: [\n        'gap-(--m3-button-group-gap)',\n        '[--m3-button-group-gap:max(12px,calc(8px-var(--md-sys-density,0)*4px))]',\n        'has-[[data-tokens~=md-comp-icon-button][data-width=narrow]]:[--m3-button-group-gap:max(12px,calc(48px-max(28px,calc(32px+var(--md-sys-density,0)*4px))))]',\n      ],\n    },\n    {\n      variant: 'standard',\n      size: 'md',\n      class: [\n        'gap-(--m3-button-group-gap) [--m3-button-group-gap:8px]',\n        'has-[[data-tokens~=md-comp-icon-button][data-width=narrow]]:[--m3-button-group-gap:max(8px,calc(var(--md-sys-density,0)*-4px))]',\n      ],\n    },\n    { variant: 'standard', size: ['lg', 'xl'], class: 'gap-[8px]' },\n  ],\n  defaultVariants: { variant: 'standard', size: 'sm', overflow: false },\n});\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAuBA,MAAa,oBAAoB,GAAG;CAClC,MAAM;CACN,UAAU;EACR,SAAS;GACP,UAAU;GACV,WAAW;EACb;EACA,MAAM;GAAE,IAAI;GAAI,IAAI;GAAI,IAAI;GAAI,IAAI;GAAI,IAAI;EAAG;EAC/C,UAAU;GACR,MAAM;GACN,OAAO;EACT;CACF;CACA,kBAAkB;EAChB;GAAE,SAAS;GAAY,UAAU;GAAM,OAAO;EAAO;EAQrD;GACE,SAAS;GACT,MAAM;GACN,OAAO;IACL;IACA;IACA;GACF;EACF;EACA;GACE,SAAS;GACT,MAAM;GACN,OAAO;IACL;IACA;IACA;GACF;EACF;EACA;GACE,SAAS;GACT,MAAM;GACN,OAAO,CACL,2DACA,iIACF;EACF;EACA;GAAE,SAAS;GAAY,MAAM,CAAC,MAAM,IAAI;GAAG,OAAO;EAAY;CAChE;CACA,iBAAiB;EAAE,SAAS;EAAY,MAAM;EAAM,UAAU;CAAM;AACtE,CAAC"}

package/dist/composites/button-group/lazy-overflow-menu.js

@@ -0,0 +1,43 @@
+"use client";
+import { onDemand } from "../../utils/load-on-demand.js";
+import { MenuTriggerContext } from "../../components/menu/menu-trigger.js";
+import { useContext, useEffect, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/composites/button-group/lazy-overflow-menu.tsx
+const menu = onDemand(() => import("./overflow-menu-list.js").then((module) => module.OverflowMenuList));
+menu.preload;
+/**
+* `ButtonGroup`'s overflow menu, whose code loads only once a button folds: a group without
+* `overflow`, or whose buttons all fit, never carries `Menu`. It sits inside the indicator's
+* `MenuTrigger` and is rendered only while something is folded. Rendering it starts the
+* load, so the menu is usually ready long before the indicator is pressed, and then opens in
+* the same pass as the press (it never suspends, see `onDemand`). It mounts once loaded, or
+* when the menu opens if that comes first, and shows nothing until then. A failed load is
+* tried again when the pointer moves over the indicator, focus enters it, or the menu opens.
+*/
+function LazyOverflowMenuList(props) {
+	const trigger = useContext(MenuTriggerContext);
+	const isOpen = trigger?.state.isOpen === true;
+	const [ready, setReady] = useState(isOpen);
+	if (isOpen && !ready) setReady(true);
+	const triggerRef = trigger?.triggerRef;
+	useEffect(() => {
+		let mounted = true;
+		const preload = () => void menu.preload().then(() => mounted && setReady(true), () => void 0);
+		preload();
+		const element = triggerRef?.current;
+		element?.addEventListener("pointerover", preload);
+		element?.addEventListener("focusin", preload);
+		return () => {
+			mounted = false;
+			element?.removeEventListener("pointerover", preload);
+			element?.removeEventListener("focusin", preload);
+		};
+	}, [triggerRef]);
+	if (!ready) return null;
+	return /* @__PURE__ */ jsx(menu.Component, { ...props });
+}
+//#endregion
+export { LazyOverflowMenuList };
+
+//# sourceMappingURL=lazy-overflow-menu.js.map

package/dist/composites/button-group/lazy-overflow-menu.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lazy-overflow-menu.js","names":[],"sources":["../../../src/composites/button-group/lazy-overflow-menu.tsx"],"sourcesContent":["'use client';\n\nimport { useContext, useEffect, useState } from 'react';\nimport { MenuTriggerContext } from '../../components/menu/menu-trigger';\nimport { onDemand } from '../../utils/load-on-demand';\nimport type { OverflowMenuListProps } from './overflow-menu-list';\n\nconst menu = onDemand<OverflowMenuListProps>(() =>\n  import('./overflow-menu-list').then((module) => module.OverflowMenuList),\n);\n\n/**\n * Starts loading the overflow menu's module (and `Menu` with it), once; later calls return\n * the same promise.\n */\nexport const preloadOverflowMenu = menu.preload;\n\n/**\n * `ButtonGroup`'s overflow menu, whose code loads only once a button folds: a group without\n * `overflow`, or whose buttons all fit, never carries `Menu`. It sits inside the indicator's\n * `MenuTrigger` and is rendered only while something is folded. Rendering it starts the\n * load, so the menu is usually ready long before the indicator is pressed, and then opens in\n * the same pass as the press (it never suspends, see `onDemand`). It mounts once loaded, or\n * when the menu opens if that comes first, and shows nothing until then. A failed load is\n * tried again when the pointer moves over the indicator, focus enters it, or the menu opens.\n */\nexport function LazyOverflowMenuList(props: OverflowMenuListProps) {\n  const trigger = useContext(MenuTriggerContext);\n  const isOpen = trigger?.state.isOpen === true;\n  const [ready, setReady] = useState(isOpen);\n  // Set during render, so an open before the load ends renders the menu in the same pass.\n  if (isOpen && !ready) setReady(true);\n\n  const triggerRef = trigger?.triggerRef;\n  useEffect(() => {\n    let mounted = true;\n    // A failed preload is left to the next hover, focus or open, which loads again.\n    const preload = () =>\n      void menu.preload().then(\n        () => mounted && setReady(true),\n        () => undefined,\n      );\n    preload();\n    const element = triggerRef?.current;\n    element?.addEventListener('pointerover', preload);\n    element?.addEventListener('focusin', preload);\n    return () => {\n      mounted = false;\n      element?.removeEventListener('pointerover', preload);\n      element?.removeEventListener('focusin', preload);\n    };\n  }, [triggerRef]);\n\n  if (!ready) return null;\n  return <menu.Component {...props} />;\n}\n"],"mappings":";;;;;;AAOA,MAAM,OAAO,eACX,OAAO,0BAAuB,CAAC,MAAM,WAAW,OAAO,gBAAgB,CACzE;AAMmC,KAAK;;;;;;;;;;AAWxC,SAAgB,qBAAqB,OAA8B;CACjE,MAAM,UAAU,WAAW,kBAAkB;CAC7C,MAAM,SAAS,SAAS,MAAM,WAAW;CACzC,MAAM,CAAC,OAAO,YAAY,SAAS,MAAM;CAEzC,IAAI,UAAU,CAAC,OAAO,SAAS,IAAI;CAEnC,MAAM,aAAa,SAAS;CAC5B,gBAAgB;EACd,IAAI,UAAU;EAEd,MAAM,gBACJ,KAAK,KAAK,QAAQ,CAAC,CAAC,WACZ,WAAW,SAAS,IAAI,SACxB,KAAA,CACR;EACF,QAAQ;EACR,MAAM,UAAU,YAAY;EAC5B,SAAS,iBAAiB,eAAe,OAAO;EAChD,SAAS,iBAAiB,WAAW,OAAO;EAC5C,aAAa;GACX,UAAU;GACV,SAAS,oBAAoB,eAAe,OAAO;GACnD,SAAS,oBAAoB,WAAW,OAAO;EACjD;CACF,GAAG,CAAC,UAAU,CAAC;CAEf,IAAI,CAAC,OAAO,OAAO;CACnB,OAAO,oBAAC,KAAK,WAAN,EAAgB,GAAI,MAAQ,CAAA;AACrC"}

package/dist/composites/button-group/overflow-menu-list.js

@@ -0,0 +1,26 @@
+"use client";
+import { CheckableMenuItem, Menu } from "../../components/menu/Menu.js";
+import { jsx } from "react/jsx-runtime";
+//#region src/composites/button-group/overflow-menu-list.tsx
+/**
+* The overflow indicator's menu: one item per folded button, opening at the indicator's
+* end. In a selectable menu only toggles (and buttons in the group's selection) are
+* checkable; actions stay plain items. `ButtonGroup` loads this module (and `Menu` with it) only once a button folds,
+* through `LazyOverflowMenuList`.
+*/
+function OverflowMenuList({ items, ...props }) {
+	return /* @__PURE__ */ jsx(Menu, {
+		...props,
+		placement: "bottom-end",
+		children: items.map(({ key, label, icon, checkable }) => /* @__PURE__ */ jsx(CheckableMenuItem, {
+			leadingIcon: icon,
+			checkable,
+			textValue: typeof label === "string" ? label : void 0,
+			children: label
+		}, key))
+	});
+}
+//#endregion
+export { OverflowMenuList };
+
+//# sourceMappingURL=overflow-menu-list.js.map

package/dist/composites/button-group/overflow-menu-list.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"overflow-menu-list.js","names":[],"sources":["../../../src/composites/button-group/overflow-menu-list.tsx"],"sourcesContent":["'use client';\n\nimport type { ReactNode } from 'react';\nimport { CheckableMenuItem, Menu, type MenuProps } from '../../components/menu/Menu';\n\n/** A folded button as a menu item. */\nexport interface OverflowMenuItem {\n  /** The button's index among the group's children, as a string. */\n  key: string;\n  label: ReactNode;\n  icon: ReactNode;\n  /**\n   * Whether the item shows and announces a checked state: a toggle button, or a button in\n   * the group's selection. Actions stay plain menu items in a selectable menu.\n   */\n  checkable: boolean;\n}\n\nexport interface OverflowMenuListProps extends Pick<\n  MenuProps,\n  'selectionMode' | 'selectedKeys' | 'disabledKeys' | 'onAction' | 'classNames'\n> {\n  /** The folded buttons, in order. */\n  items: OverflowMenuItem[];\n}\n\n/**\n * The overflow indicator's menu: one item per folded button, opening at the indicator's\n * end. In a selectable menu only toggles (and buttons in the group's selection) are\n * checkable; actions stay plain items. `ButtonGroup` loads this module (and `Menu` with it) only once a button folds,\n * through `LazyOverflowMenuList`.\n */\nexport function OverflowMenuList({ items, ...props }: OverflowMenuListProps) {\n  return (\n    <Menu {...props} placement=\"bottom-end\">\n      {items.map(({ key, label, icon, checkable }) => (\n        <CheckableMenuItem\n          key={key}\n          leadingIcon={icon}\n          checkable={checkable}\n          textValue={typeof label === 'string' ? label : undefined}\n        >\n          {label}\n        </CheckableMenuItem>\n      ))}\n    </Menu>\n  );\n}\n"],"mappings":";;;;;;;;;;AAgCA,SAAgB,iBAAiB,EAAE,OAAO,GAAG,SAAgC;CAC3E,OACE,oBAAC,MAAD;EAAM,GAAI;EAAO,WAAU;EACxB,UAAA,MAAM,KAAK,EAAE,KAAK,OAAO,MAAM,gBAC9B,oBAAC,mBAAD;GAEE,aAAa;GACF;GACX,WAAW,OAAO,UAAU,WAAW,QAAQ,KAAA;GAE9C,UAAA;EACgB,GANZ,GAMY,CACpB;CACG,CAAA;AAEV"}