@eocrm/design-system 0.0.0-stage → 0.6.17

package/src/components/Button/Button.tsx

@@ -0,0 +1,205 @@
+import {
+  forwardRef,
+  type ComponentPropsWithRef,
+  type ComponentPropsWithoutRef,
+  type CSSProperties,
+  type ElementType,
+  type ForwardedRef,
+  type ReactElement,
+} from 'react';
+import clsx from 'clsx';
+import { paletteTokens, type PaletteColor } from '../../palette/palette';
+import styles from './Button.module.scss';
+
+/** Visual variant. See ButtonProps#variant for when to use each. */
+export type ButtonVariant =
+  | 'primary'
+  | 'secondary'
+  | 'ghost'
+  | 'danger'
+  | 'danger-outline'
+  | 'success';
+
+/** Control height. See ButtonProps#size for when to use each. */
+export type ButtonSize = 'xs' | 'sm' | 'md' | 'lg';
+
+interface ButtonOwnProps {
+  /**
+   * Visual variant.
+   * - `primary` (default) — the section's main action. Use **one** per page section.
+   * - `secondary` — supporting actions like "Cancel", "Export", "Filter".
+   * - `ghost` — tertiary actions in dense UIs (toolbar buttons, row actions).
+   * - `danger` — destructive operations only (Delete, Revoke, Remove). Pair with a confirmation if irreversible.
+   * - `danger-outline` — a destructive action that must not dominate: surface
+   *   fill, danger text and border. For a Remove repeated on every row, or a
+   *   destructive action beside a primary one. Use filled `danger` for the
+   *   confirm step itself.
+   * - `success` — **transient confirmation only**, not an initial state. Flip to
+   *   `success` for ~1.5s after an action resolves (Save → "Saved!"), then
+   *   flip back. Never render a button as `success` on mount — it has no
+   *   action-intent meaning, only post-action feedback. See the `@example`
+   *   below for the timer pattern.
+   */
+  variant?: ButtonVariant;
+  /**
+   * Control height (matches the shared `--size-*` scale used by Input and Avatar).
+   * - `xs` (20px) — icon-only or very dense inline actions (row controls,
+   *   chip-adjacent buttons). Pass `aria-label` when icon-only. Below WCAG
+   *   2.5.5 Level AAA touch-target guidance; reserve for desktop-first surfaces.
+   * - `sm` (24px) — dense toolbars, tables, inline actions.
+   * - `md` (32px, default) — most contexts.
+   * - `lg` (40px) — marketing-style empty states or emphasized primary actions.
+   */
+  size?: ButtonSize;
+  /**
+   * Render the button as a square icon-only target — `aspect-ratio` is forced
+   * to 1 so width tracks the size's `height` token (`xs` → 20×20, `sm` → 24×24,
+   * `md` → 32×32, `lg` → 40×40) and `padding` is tightened to a small inset
+   * (4px) so the icon has breathing room without changing the outer shape.
+   *
+   * **Always pass `aria-label`** when `iconOnly` is set, otherwise the button
+   * has no accessible name. Pass a single icon as `children`.
+   *
+   * Use for inline density (row controls, chip-adjacent actions, toolbar
+   * affordances). For an icon + short text label, leave `iconOnly` off — the
+   * button will lay out as a normal rectangle with the existing gap.
+   */
+  iconOnly?: boolean;
+  /**
+   * Controlled persistent paint for an applied filter or toolbar value.
+   * Selected paint applies only to `secondary` and `ghost` Buttons;
+   * `primary`, `danger`, and `success` retain their intent paint. This prop is
+   * visual only and does not add toggle-button semantics. Pass native
+   * `aria-pressed` explicitly only when activating the Button itself toggles
+   * the selected state; menu and disclosure triggers keep their own semantics.
+   * The consumer owns the state. Not for transient success feedback or for
+   * mutually exclusive `<ButtonGroup>` choices. Defaults to `undefined` (not
+   * selected).
+   */
+  selected?: boolean;
+  /**
+   * Paint the button with a palette color's soft pair
+   * (`--color-palette-<color>-bg` fill, `-fg` text) — the same pair a
+   * palette-colored `<PillMenu>` or `<Badge color>` uses, in both themes.
+   * For a quick action that moves a record to a status and must look like
+   * that status's pill (amber "No show" beside an amber status PillMenu).
+   * Not a decorative stand-in for `danger`/`success`: palette colors carry
+   * no meaning. When set it wins over `variant` and `selected` (like
+   * `<Badge color>` over `tone`). Hover/pressed darken via
+   * `filter: brightness()`. Defaults to `undefined` (use `variant`).
+   */
+  color?: PaletteColor;
+}
+
+/**
+ * Polymorphic props helper. Intersects the component's own props with the
+ * underlying element's props (minus what we own), plus the `as` selector.
+ * Mirrors `<Link>`.
+ */
+type PolymorphicProps<C extends ElementType, P> = P & {
+  /**
+   * Render a different element — the case that matters is `as="a"` with
+   * `href`, for a link that must LOOK like a button (an external console, a
+   * download, an IdP hand-off). The element named here is what actually
+   * renders, and its own attributes are typed: `href` is REQUIRED when
+   * `as="a"` (an anchor without one is neither focusable nor a link) and
+   * rejected otherwise; `target`/`rel`/`download` come through. Never navigate from `onClick`.
+   *
+   * Reach for `<Link>` first. `<Link>` is link-SHAPED navigation — inline text
+   * in a sentence, a table cell, a breadcrumb. `<Button as="a">` is for a
+   * destination that sits in a row of buttons and must carry their weight.
+   * Either way the element is a real anchor, so assistive tech announces a
+   * link and the browser gives middle-click, "open in new tab", and the status
+   * bar preview — none of which a `<button onClick={() => navigate()}>` has.
+   *
+   * `type="button"` is emitted only for a real `<button>`; an anchor never
+   * gets it. Everything else — variant, size, `iconOnly`, `selected`, the
+   * focus ring — is unchanged.
+   *
+   * @default 'button'
+   */
+  as?: C;
+} & Omit<ComponentPropsWithoutRef<C>, keyof P | 'as'> &
+  // `href` is optional on every anchor in the DOM typings, so `as="a"` alone
+  // would compile to an element that is neither focusable nor a link — the
+  // silent shape #530 is about. Required here instead. The conditional is
+  // deferred until `C` is known, so `as={RouterLink}` (which names its URL
+  // prop `to`) and every non-anchor element are untouched.
+  (C extends 'a' ? { href: string } : unknown);
+
+/**
+ * Public Button prop type. Generic `C` defaults to `'button'`, so a Button
+ * with no `as` accepts exactly the `<button>` attributes it always did — and
+ * still rejects `href`. With `as="a"`, the anchor's attributes (`href`,
+ * `target`, `rel`, `download`) become available instead.
+ */
+export type ButtonProps<C extends ElementType = 'button'> = PolymorphicProps<C, ButtonOwnProps>;
+
+/**
+ * Internal generic-preserving signature. React's `forwardRef` strips the
+ * generic from the returned component, so it is re-attached via the cast on
+ * the export below.
+ */
+type ButtonComponent = {
+  <C extends ElementType = 'button'>(
+    props: ButtonProps<C> & { ref?: ComponentPropsWithRef<C>['ref'] },
+  ): ReactElement | null;
+  /** Kept on the type because the cast below would otherwise drop it. */
+  displayName?: string;
+};
+
+/**
+ * Action trigger. Renders a `<button type="button">` and forwards refs and HTML attributes.
+ * @see docs/components/Button.md
+ */
+export const Button = forwardRef(function Button<C extends ElementType = 'button'>(
+  {
+    as,
+    variant = 'primary',
+    size = 'md',
+    iconOnly = false,
+    selected,
+    color,
+    className,
+    style,
+    ...props
+  }: ButtonProps<C>,
+  ref: ForwardedRef<Element>,
+) {
+  const Component = (as || 'button') as ElementType;
+  const palette = color ? paletteTokens(color) : undefined;
+  const paintsSelected = !palette && selected && (variant === 'secondary' || variant === 'ghost');
+
+  // `type="button"` is a <button>-only guarantee — it stops the button
+  // submitting an ancestor form. An anchor's `type` is a MIME hint, so
+  // emitting the default there would be wrong; #530 rendered a <button> with a
+  // dead `href` for the mirror-image reason. A consumer-supplied `type` still
+  // wins: it rides along in {...props}, spread last.
+  const defaultType = Component === 'button' ? { type: 'button' as const } : undefined;
+
+  return (
+    <Component
+      ref={ref}
+      {...defaultType}
+      className={clsx(
+        styles.button,
+        palette ? styles.palette : styles[variant],
+        styles[size],
+        iconOnly && styles.iconOnly,
+        paintsSelected && styles.selected,
+        className,
+      )}
+      style={
+        palette
+          ? ({
+              '--button-palette-bg': palette.bg,
+              '--button-palette-fg': palette.fg,
+              ...style,
+            } as CSSProperties)
+          : style
+      }
+      // {...props} last so consumers can supply native semantics such as aria-pressed.
+      {...props}
+    />
+  );
+}) as ButtonComponent;

package/src/components/Button/index.ts

@@ -0,0 +1,2 @@
+export { Button } from './Button';
+export type { ButtonProps, ButtonVariant, ButtonSize } from './Button';

package/src/components/ButtonGroup/ButtonGroup.module.scss

@@ -0,0 +1,134 @@
+@use '../../styles/mixins' as *;
+@use './ButtonGroup.tokens';
+
+// ─── Visual mode ────────────────────────────────────────────────────────
+// Joined Button children: flatten inner borders, round outer corners.
+// Targets the native `> button` element so we don't have to know Button's
+// CSS Module hash.
+
+.group[data-mode='visual'] {
+  display: inline-flex;
+
+  // Don't stretch to fill cross-axis when placed inside a flex/grid parent
+  // (e.g. Stack with default align="stretch"). A joined button group is an
+  // intrinsically compact UI control — like Button itself, like Tabs — and
+  // should not expand to container width. Rule 4 disallows align-self in
+  // general; this is the documented exception for inline-shaped UI controls.
+  // stylelint-disable-next-line property-disallowed-list -- inline control intrinsic shrink
+  align-self: flex-start;
+}
+
+.group[data-mode='visual'] > button {
+  border-radius: 0;
+
+  // -1px margin pulls each adjacent border into a single line. Rule 4 normally
+  // disallows margin on components, but this is the canonical border-collapse
+  // technique for joined buttons — transform: translateX doesn't work because
+  // it leaves the cumulative seam-to-seam gap uncollapsed past the first pair.
+  // stylelint-disable-next-line property-disallowed-list -- border-collapse for joined siblings
+  margin-left: calc(var(--border-width) * -1);
+}
+
+.group[data-mode='visual'] > button:first-child {
+  // stylelint-disable-next-line property-disallowed-list -- counterpart to the join above
+  margin-left: 0;
+  border-top-left-radius: var(--button-group-radius);
+  border-bottom-left-radius: var(--button-group-radius);
+}
+
+.group[data-mode='visual'] > button:last-child {
+  border-top-right-radius: var(--button-group-radius);
+  border-bottom-right-radius: var(--button-group-radius);
+}
+
+// Lift on hover/focus. NOT for the ring — an outline paints after every
+// descendant background in its stacking context, so it already draws over a
+// joined sibling unlifted, and the segmented lift added on that false premise
+// was removed. This is for the BORDER: these children collapse their borders
+// with `margin-left: -1px`, so without the lift the later sibling's left border
+// paints over the hovered button's right one.
+.group[data-mode='visual'] > button:hover,
+.group[data-mode='visual'] > button:focus-visible {
+  position: relative;
+  z-index: 1;
+}
+
+// ─── Segmented mode ─────────────────────────────────────────────────────
+// Pill-inset look matching iOS / Material precedent. Owns its own styling
+// — items are NOT Buttons, they're internal radio-role <button>s.
+
+.group[data-mode='segmented'] {
+  background: var(--button-group-segmented-bg);
+  border-radius: var(--button-group-segmented-radius);
+  padding: var(--button-group-segmented-padding);
+  display: inline-flex;
+  gap: var(--button-group-segmented-gap);
+
+  // Shrink-to-content inside flex/grid parents (e.g. Stack with align=stretch).
+  // Documented Rule-4 exception for intrinsically compact inline controls.
+  // stylelint-disable-next-line property-disallowed-list -- inline control intrinsic shrink
+  align-self: flex-start;
+}
+
+.item {
+  border: none;
+  background: transparent;
+  color: var(--button-group-item-fg);
+  cursor: pointer;
+  font: inherit;
+  white-space: nowrap;
+  border-radius: calc(var(--button-group-segmented-radius) - var(--button-group-segmented-padding));
+  transition:
+    background var(--transition-fast),
+    color var(--transition-fast);
+}
+
+.item[data-selected] {
+  background: var(--button-group-item-bg-selected);
+  color: var(--button-group-item-fg-selected);
+  box-shadow: var(--button-group-item-shadow-selected);
+}
+
+.item:hover:not([data-selected], [aria-disabled]) {
+  color: var(--button-group-item-fg-hover);
+}
+
+.item[aria-disabled] {
+  cursor: not-allowed;
+  opacity: var(--button-group-item-opacity-disabled);
+}
+
+.item:focus-visible {
+  @include focus-ring;
+}
+
+// Size variants — the TRACK matches Button's --size-* height, so a segmented
+// control lines up with a same-size Button. Items give back the track's
+// padding on both sides.
+.sizeXs {
+  height: calc(var(--button-group-item-height-xs) - 2 * var(--button-group-segmented-padding));
+  padding: 0 var(--button-group-item-padding-x-xs);
+  font-size: var(--button-group-item-font-size-xs);
+
+  // 16px item: pin the line box so an inherited taller line-height (e.g.
+  // 1.5 × 11px = 16.5px from a consumer ancestor) can't overflow it.
+  line-height: var(--line-height-none);
+}
+
+.sizeSm {
+  height: calc(var(--button-group-item-height-sm) - 2 * var(--button-group-segmented-padding));
+  padding: 0 var(--button-group-item-padding-x-sm);
+  font-size: var(--button-group-item-font-size-sm);
+}
+
+.sizeMd {
+  height: calc(var(--button-group-item-height-md) - 2 * var(--button-group-segmented-padding));
+  padding: 0 var(--button-group-item-padding-x-md);
+  font-size: var(--button-group-item-font-size-md);
+}
+
+.sizeLg {
+  height: calc(var(--button-group-item-height-lg) - 2 * var(--button-group-segmented-padding));
+  padding: 0 var(--button-group-item-padding-x-lg);
+  font-size: var(--button-group-item-font-size-lg);
+}

package/src/components/ButtonGroup/ButtonGroup.tokens.scss

@@ -0,0 +1,42 @@
+// ButtonGroup.tokens.scss — component-scoped tokens for <ButtonGroup>. Visual mode joins Button children; segmented mode owns its own pill-inset styling.
+:root {
+  // Visual mode — outer-corner radius applied to first/last children
+  --button-group-radius: var(--radius-md);
+
+  // Segmented mode — track surface + shape
+  --button-group-segmented-bg: var(--color-bg-muted);
+  --button-group-segmented-radius: var(--radius-md);
+  --button-group-segmented-padding: var(--space-05);
+  --button-group-segmented-gap: var(--space-05);
+
+  // Segmented item — base appearance
+  --button-group-item-fg: var(--color-fg-muted);
+  --button-group-item-fg-hover: var(--color-fg);
+
+  // Segmented item — selected state
+  --button-group-item-bg-selected: var(--color-bg);
+  --button-group-item-fg-selected: var(--color-fg);
+
+  // --shadow-xs has never existed; the scale is sm/md/lg, so this resolved to
+  // nothing and the selected item rendered with no shadow at all. sm is the
+  // smallest step and what "xs" was reaching for.
+  --button-group-item-shadow-selected: var(--shadow-sm);
+
+  // Segmented item — disabled
+  --button-group-item-opacity-disabled: var(--opacity-disabled);
+
+  // Segmented — sizes. Height = the outer TRACK (matches Button --size-*);
+  // each item renders at this minus 2 × --button-group-segmented-padding.
+  --button-group-item-height-xs: var(--size-xs);
+  --button-group-item-height-sm: var(--size-sm);
+  --button-group-item-height-md: var(--size-md);
+  --button-group-item-height-lg: var(--size-lg);
+  --button-group-item-padding-x-xs: var(--space-2);
+  --button-group-item-padding-x-sm: var(--space-3);
+  --button-group-item-padding-x-md: var(--space-3);
+  --button-group-item-padding-x-lg: var(--space-4);
+  --button-group-item-font-size-xs: var(--font-size-xs);
+  --button-group-item-font-size-sm: var(--font-size-sm);
+  --button-group-item-font-size-md: var(--font-size-md);
+  --button-group-item-font-size-lg: var(--font-size-md);
+}

package/src/components/ButtonGroup/ButtonGroup.tsx

@@ -0,0 +1,278 @@
+import {
+  Children,
+  cloneElement,
+  isValidElement,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type CSSProperties,
+  type HTMLAttributes,
+  type KeyboardEvent,
+  type ReactElement,
+} from 'react';
+import clsx from 'clsx';
+import { Button, type ButtonProps } from '../Button';
+import { ButtonGroupContext, type ButtonGroupContextValue, type ButtonGroupSize } from './context';
+import { ButtonGroupItem } from './ButtonGroupItem';
+import styles from './ButtonGroup.module.scss';
+
+export type { ButtonGroupSize } from './context';
+export type { ButtonGroupItemProps } from './ButtonGroupItem';
+
+interface ButtonGroupBase {
+  /**
+   * Size propagated to children. Per-child `size` (Button or Item) wins
+   * when explicitly set. In visual mode this happens via cloneElement on
+   * Button children. In segmented mode, `<ButtonGroup.Item>` reads from
+   * context.
+   */
+  size?: ButtonGroupSize;
+  /**
+   * Disabled state for the whole group. In segmented mode this is
+   * authoritative (all items become aria-disabled, clicks no-op). In
+   * visual mode this is a no-op — pass `disabled` per `<Button>` instead.
+   */
+  disabled?: boolean;
+  /**
+   * Segmented mode: `aria-invalid` on the radiogroup. Visual mode: consumed
+   * and ignored. Field / SettingRow inject it — it used to leak onto the
+   * group div as a stray attribute (#568). @default false
+   */
+  invalid?: boolean;
+  /**
+   * Segmented mode: `aria-required` on the radiogroup. Visual mode: consumed
+   * and ignored. Field / SettingRow inject it (#568). @default false
+   */
+  required?: boolean;
+  className?: string;
+  style?: CSSProperties;
+}
+
+interface ButtonGroupVisualProps
+  extends ButtonGroupBase, Omit<HTMLAttributes<HTMLDivElement>, 'onChange'> {
+  /** Visual mode marker. Never set; absence flips to visual. */
+  value?: never;
+  onValueChange?: never;
+  /** Accessible name for the group landmark. Optional but recommended. */
+  'aria-label'?: string;
+}
+
+interface ButtonGroupSegmentedProps
+  extends ButtonGroupBase, Omit<HTMLAttributes<HTMLDivElement>, 'onChange'> {
+  /** Currently-selected item value. Triggers segmented mode. */
+  value: string;
+  /**
+   * Fired when a different Item is selected.
+   *
+   * Consumers wanting literal-union narrowing can cast the setter:
+   * `onValueChange={(v) => setView(v as 'grid' | 'list')}`.
+   */
+  onValueChange: (next: string) => void;
+  /** Required in segmented mode (radiogroup needs a label). */
+  'aria-label': string;
+  /** Alternative to aria-label: id of an external labelling element. */
+  'aria-labelledby'?: string;
+}
+
+export type ButtonGroupProps = ButtonGroupVisualProps | ButtonGroupSegmentedProps;
+
+/**
+ * Compound. Visual mode joins Buttons; segmented mode (`value` + `onValueChange`) is a single-select radiogroup.
+ * @see docs/components/ButtonGroup.md
+ */
+export function ButtonGroupRoot(props: ButtonGroupProps) {
+  const isSegmented = 'value' in props && props.value !== undefined;
+  return isSegmented ? (
+    <Segmented {...(props as ButtonGroupSegmentedProps)} />
+  ) : (
+    <Visual {...(props as ButtonGroupVisualProps)} />
+  );
+}
+
+function Visual({
+  size = 'md',
+  disabled: _disabled,
+  // Consumed so Field-injected props never reach the div (#568).
+  invalid: _invalid,
+  required: _required,
+  children,
+  className,
+  style,
+  'aria-label': ariaLabel,
+  ...rest
+}: ButtonGroupVisualProps) {
+  // Inject size into Button children whose size isn't already set.
+  const processed = Children.map(children, (child) => {
+    if (!isValidElement(child)) return child;
+    if (child.type !== Button) return child;
+    const childProps = child.props as ButtonProps;
+    if (childProps.size !== undefined) return child;
+    return cloneElement(child as ReactElement<ButtonProps>, { size });
+  });
+
+  return (
+    <div
+      {...rest}
+      // {...rest} first so the ARIA contract (role, aria-label, data-mode)
+      // can't be silently broken by a stray consumer prop.
+      role="group"
+      aria-label={ariaLabel}
+      data-mode="visual"
+      className={clsx(styles.group, className)}
+      style={style}
+    >
+      {processed}
+    </div>
+  );
+}
+
+function Segmented({
+  size = 'md',
+  disabled = false,
+  value,
+  onValueChange,
+  children,
+  className,
+  style,
+  'aria-label': ariaLabel,
+  'aria-labelledby': ariaLabelledBy,
+  invalid = false,
+  required = false,
+  ...rest
+}: ButtonGroupSegmentedProps) {
+  // groupRef enables DOM-order querying for keyboard nav so that consumer-
+  // reordered children are always walked in their actual visual order.
+  const groupRef = useRef<HTMLDivElement | null>(null);
+
+  // Dev warning: aria-label or aria-labelledby required in segmented mode.
+  useEffect(() => {
+    if (process.env.NODE_ENV === 'production') return;
+    let cancelled = false;
+    queueMicrotask(() => {
+      if (cancelled) return;
+      if (!ariaLabel && !ariaLabelledBy) {
+        console.warn(
+          '<ButtonGroup> in segmented mode requires an `aria-label` or `aria-labelledby` prop for screen readers.',
+        );
+      }
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [ariaLabel, ariaLabelledBy]);
+
+  // Which item holds the tab stop when nothing is selected. Read from the DOM
+  // after each commit so consumer-reordered children resolve in visual order,
+  // exactly like handleItemKeyDown below. Runs unconditionally but only sets
+  // state when the answer actually changes, so it cannot loop.
+  const [rovingFallbackValue, setRovingFallbackValue] = useState<string | null>(null);
+  // eslint-disable-next-line react-hooks/exhaustive-deps -- runs after every commit by design; the setter bails out when unchanged
+  useEffect(() => {
+    const root = groupRef.current;
+    if (!root) return;
+    const items = [...root.querySelectorAll<HTMLButtonElement>('button[role="radio"]')];
+    const anySelected = items.some((el) => el.getAttribute('aria-checked') === 'true');
+    const firstEnabled = items.find((el) => el.getAttribute('aria-disabled') !== 'true');
+    // `?? items[0]` for the all-disabled group. Items carry `aria-disabled`,
+    // not the native `disabled`, precisely so they STAY focusable — a user can
+    // tab to them and hear why the choice is unavailable. Falling back to null
+    // here left every item at `tabIndex={-1}`, so the group vanished from the
+    // tab order entirely, which is the behaviour `aria-disabled` was chosen to
+    // avoid.
+    const next = anySelected ? null : ((firstEnabled ?? items[0])?.dataset.value ?? null);
+    setRovingFallbackValue((prev) => (prev === next ? prev : next));
+  });
+
+  const handleItemKeyDown = useCallback(
+    (e: KeyboardEvent<HTMLButtonElement>, currentValue: string) => {
+      const root = groupRef.current;
+      if (!root) return;
+      // Query DOM order so reordered children are walked correctly.
+      const allButtons = Array.from(
+        root.querySelectorAll<HTMLButtonElement>('button[role="radio"]'),
+      );
+      const enabledButtons = allButtons.filter(
+        (btn) => btn.getAttribute('aria-disabled') !== 'true',
+      );
+      if (enabledButtons.length === 0) return;
+
+      // Find the focused button in the enabled list. If the currently-selected
+      // item is itself disabled (per-item disabled), fall back to the active
+      // element so Arrow nav still works from wherever focus is.
+      let idx = enabledButtons.findIndex((btn) => btn.dataset.value === currentValue);
+      if (idx === -1) {
+        // Selected item is disabled — use whichever enabled button is focused.
+        idx = enabledButtons.findIndex((btn) => btn === document.activeElement);
+      }
+      if (idx === -1) return;
+
+      let nextIdx: number | null = null;
+      switch (e.key) {
+        case 'ArrowRight':
+        case 'ArrowDown':
+          nextIdx = (idx + 1) % enabledButtons.length;
+          break;
+        case 'ArrowLeft':
+        case 'ArrowUp':
+          nextIdx = (idx - 1 + enabledButtons.length) % enabledButtons.length;
+          break;
+        case 'Home':
+          nextIdx = 0;
+          break;
+        case 'End':
+          nextIdx = enabledButtons.length - 1;
+          break;
+        default:
+          return;
+      }
+
+      e.preventDefault();
+      const next = enabledButtons[nextIdx]!;
+      if (!disabled) onValueChange(next.dataset.value!);
+      next.focus();
+    },
+    [disabled, onValueChange],
+  );
+
+  const contextValue = useMemo<ButtonGroupContextValue>(
+    () => ({
+      value,
+      onValueChange,
+      size,
+      disabled,
+      handleItemKeyDown,
+      rovingFallbackValue,
+    }),
+    [value, onValueChange, size, disabled, handleItemKeyDown, rovingFallbackValue],
+  );
+
+  return (
+    <ButtonGroupContext.Provider value={contextValue}>
+      <div
+        ref={groupRef}
+        {...rest}
+        // {...rest} first so the ARIA contract (role, aria-label, data-mode)
+        // can't be silently broken by a stray consumer prop.
+        role="radiogroup"
+        aria-label={ariaLabel}
+        aria-labelledby={ariaLabelledBy}
+        aria-disabled={disabled || undefined}
+        aria-invalid={invalid || undefined}
+        aria-required={required || undefined}
+        data-mode="segmented"
+        className={clsx(styles.group, className)}
+        style={style}
+      >
+        {children}
+      </div>
+    </ButtonGroupContext.Provider>
+  );
+}
+
+/**
+ * Compound: `<ButtonGroup>` with `<ButtonGroup.Item>` attached.
+ * @see docs/components/ButtonGroup.md
+ */
+export const ButtonGroup = Object.assign(ButtonGroupRoot, { Item: ButtonGroupItem });