@eocrm/design-system 0.0.0-stage → 0.6.18

package/src/components/DropdownMenu/Content.tsx

@@ -0,0 +1,419 @@
+import {
+  forwardRef,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  type HTMLAttributes,
+  type KeyboardEvent as ReactKeyboardEvent,
+} from 'react';
+import { createPortal } from 'react-dom';
+import {
+  autoUpdate,
+  flip,
+  offset,
+  shift,
+  size,
+  useFloating,
+  type Placement,
+} from '@floating-ui/react-dom';
+import clsx from 'clsx';
+import { useDropdownMenuContext } from './context';
+import { isTourHeld, overlayStack } from '../_internal/overlay';
+import { mergeRefs } from '../_internal/refs';
+import styles from './DropdownMenu.module.scss';
+
+/** Which side of the trigger the menu prefers. Floating UI auto-flips if it doesn't fit. */
+export type DropdownMenuSide = 'top' | 'bottom' | 'left' | 'right';
+/** Which edge of the menu aligns to the corresponding trigger edge. */
+export type DropdownMenuAlign = 'start' | 'center' | 'end';
+
+// Focus an item without scrolling the page, then explicitly scroll it into
+// view WITHIN the panel: `.content` is height-clamped by the size middleware
+// and scrolls (#303), and preventScroll suppresses that scroll too.
+// ONLY for the keydown paths, where the panel is already positioned — at
+// open time the panel still sits at the document origin and scrollIntoView
+// would yank the page (the open effect defers to the isPositioned effect
+// instead). Guarded — jsdom has no scrollIntoView.
+const focusItem = (el: HTMLElement | null | undefined) => {
+  el?.focus({ preventScroll: true });
+  el?.scrollIntoView?.({ block: 'nearest' });
+};
+
+/**
+ * Content props.
+ *
+ * Note: the `style` prop from `HTMLAttributes` is reserved — Floating UI sets
+ * inline `position`/`top`/`left` styles to position the menu. A consumer
+ * `style` value is silently overridden. Set `minWidth` via the prop, not via
+ * `style`. Class-based styling (`className` / SCSS module) is the supported
+ * customization surface.
+ */
+export interface DropdownMenuContentProps extends HTMLAttributes<HTMLDivElement> {
+  /** Preferred side. Default `'bottom'`. Auto-flips on collision. */
+  side?: DropdownMenuSide;
+  /** Edge alignment. Default `'start'`. */
+  align?: DropdownMenuAlign;
+  /** Gap in px between trigger and menu. Default `4`. */
+  sideOffset?: number;
+  /**
+   * Preferred minimum width in px or any CSS length. Defaults to the trigger's
+   * width and is reduced when necessary to keep the menu within the viewport.
+   */
+  minWidth?: number | string;
+}
+
+/**
+ * The floating menu panel, rendered only while the menu is open.
+ * @see docs/components/DropdownMenu.md
+ */
+// Owns keyboard handling (Escape, Tab, arrows, Home/End, Enter/Space, typeahead) and outside-click dismissal.
+export const Content = forwardRef<HTMLDivElement, DropdownMenuContentProps>(function Content(
+  { side = 'bottom', align = 'start', sideOffset = 4, minWidth, className, children, ...rest },
+  forwardedRef,
+) {
+  const ctx = useDropdownMenuContext('Content');
+  const inOverlay = ctx.inOverlay;
+
+  const placement: Placement = (align === 'center' ? side : `${side}-${align}`) as Placement;
+
+  const {
+    refs,
+    floatingStyles,
+    isPositioned,
+    placement: resolvedPlacement,
+  } = useFloating({
+    open: ctx.open,
+    placement,
+    transform: false,
+    middleware: [
+      offset(sideOffset),
+      flip(),
+      shift({ padding: 8 }),
+      size({
+        apply({ availableHeight, availableWidth, rects, elements }) {
+          const viewportWidth = Math.max(0, availableWidth);
+          const requestedMinWidth =
+            typeof minWidth === 'number'
+              ? `${minWidth}px`
+              : ((minWidth as string | undefined) ?? `${rects.reference.width}px`);
+          Object.assign(elements.floating.style, {
+            maxHeight: `${availableHeight}px`,
+            maxWidth: `${viewportWidth}px`,
+            minWidth: `min(${requestedMinWidth}, ${viewportWidth}px)`,
+          });
+        },
+        padding: 8,
+      }),
+    ],
+    whileElementsMounted: autoUpdate,
+    elements: { reference: ctx.triggerRef.current },
+  });
+
+  const [resolvedSide, resolvedAlign = 'center'] = resolvedPlacement.split('-') as [
+    DropdownMenuSide,
+    DropdownMenuAlign | undefined,
+  ];
+
+  const setFloatingRef = mergeRefs<HTMLDivElement>(refs.setFloating, forwardedRef);
+
+  const typeaheadRef = useRef<{ buffer: string; timer: ReturnType<typeof setTimeout> | null }>({
+    buffer: '',
+    timer: null,
+  });
+
+  useEffect(() => {
+    const typeahead = typeaheadRef.current;
+    return () => {
+      if (typeahead.timer) clearTimeout(typeahead.timer);
+    };
+  }, []);
+
+  // Outside-click: pointerdown on document, target is neither inside this
+  // Content nor inside the Trigger, AND not inside any other open submenu
+  // panel (recognised by [data-dropdown-menu-content]) OR any open popover
+  // panel (recognised by [data-popover-content]). Excluding the trigger
+  // prevents fighting the trigger's own toggle handler. Excluding popovers
+  // lets a Popover opened from inside a menu item handle its own clicks
+  // (Cancel/Confirm buttons, form controls) without collapsing the menu.
+  useEffect(() => {
+    if (!ctx.open) return;
+    const onPointerDown = (e: globalThis.PointerEvent) => {
+      const target = e.target as Node | null;
+      if (!target) return;
+      const content = refs.floating.current;
+      const trigger = ctx.triggerRef.current;
+      if (content && content.contains(target)) return;
+      if (trigger && trigger.contains(target)) return;
+      // #684: a tour pointing into this menu — its Next/card/blocker press
+      // must not dismiss the surface the next step is about to feature.
+      if (isTourHeld(target, content, trigger)) return;
+      // If the click is inside a deeper submenu panel or any popover panel,
+      // let that surface handle it.
+      const allPanels = document.querySelectorAll(
+        '[data-dropdown-menu-content], [data-popover-content]',
+      );
+      for (const panel of allPanels) {
+        if (panel !== content && panel.contains(target)) return;
+      }
+      ctx.setOpen(false);
+    };
+    document.addEventListener('pointerdown', onPointerDown, true);
+    return () => document.removeEventListener('pointerdown', onPointerDown, true);
+  }, [ctx, refs]);
+
+  // Escape: close from anywhere (focus may be on the trigger or inside the menu).
+  // Tab: close and return focus to trigger when focus is inside the menu.
+  // These use document-level listeners so they fire regardless of which element
+  // currently holds focus.
+  // For subs (depth > 0): stop propagation after handling Escape so the
+  // parent Content's listener does not also close the parent.
+  useEffect(() => {
+    if (!ctx.open) return;
+    const onKeyDown = (e: globalThis.KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        // #280: defer the WHOLE menu to a DEEPER non-menu floating surface —
+        // e.g. a ConfirmationPopover/Select opened from a menu item, which
+        // registers after the menu and is thus innermost. Its own listener
+        // closes it on this press; the menu stays open. (isTopFloating is keyed
+        // on the root's floating id, shared by every Content panel via context.)
+        if (!overlayStack.isTopFloating(ctx.floatingId)) return;
+        e.preventDefault();
+        overlayStack.consumeEscape(e); // hosts yield even if we ran first (#274)
+        // Defer to any DEEPER open dropdown panel: only the single innermost
+        // panel (no deeper panel in the DOM) closes, so one Escape peels exactly
+        // one level. This is purely DOM-based — it does NOT rely on listener
+        // registration order (the keydown effect re-registers every render, so
+        // that order isn't guaranteed). Applies at EVERY depth (#279): a depth-1
+        // sub must defer to a depth-2 sub, not only depth-0 to depth-1.
+        const deeperPanels = document.querySelectorAll(
+          `[data-dropdown-menu-content][data-dropdown-depth]`,
+        );
+        for (const panel of deeperPanels) {
+          const depth = Number(panel.getAttribute('data-dropdown-depth') ?? '0');
+          if (depth > ctx.depth) return;
+        }
+        if (ctx.depth > 0) {
+          // Stop propagation so no later document listener double-handles this
+          // press. Shallower ancestor listeners already fired and deferred.
+          e.stopImmediatePropagation();
+        }
+        ctx.setOpen(false);
+        ctx.triggerRef.current?.focus({ preventScroll: true });
+        return;
+      }
+      if (e.key === 'Tab') {
+        const content = refs.floating.current;
+        const activeEl = document.activeElement as Node | null;
+        // Only intercept Tab when focus is inside the menu.
+        // Do NOT preventDefault — browser continues Tab traversal from the
+        // (now-focused) trigger to the next focusable element (WAI-ARIA menu pattern).
+        if (content && activeEl && content.contains(activeEl)) {
+          ctx.setOpen(false);
+          ctx.triggerRef.current?.focus({ preventScroll: true });
+        }
+      }
+    };
+    document.addEventListener('keydown', onKeyDown, true);
+    return () => document.removeEventListener('keydown', onKeyDown, true);
+  }, [ctx, refs]);
+
+  // When the menu opens, set activeIndex from openIntent and focus the active item.
+  // useLayoutEffect (not useEffect) so this runs after Items' layout effects
+  // have populated itemsRef.current (layout effects fire bottom-up: children first).
+  useLayoutEffect(() => {
+    if (!ctx.open) return;
+
+    if (ctx.openIntent === null) {
+      // Mouse-opened: don't pre-highlight any item. Focus the menu container
+      // itself so subsequent Arrow keys still route through handleKeyDown,
+      // and so Escape works from inside the menu.
+      ctx.setActiveIndex(-1);
+      // preventScroll: the portaled menu starts at the document origin until
+      // Floating UI's autoUpdate computes the real coords. Focusing it without
+      // preventScroll yanks the page to the top.
+      queueMicrotask(() => refs.floating.current?.focus({ preventScroll: true }));
+      return;
+    }
+
+    // Keyboard-opened: focus first/last enabled item per intent.
+    const enabled = ctx.itemsRef.current.filter((x) => !x.disabled);
+    if (enabled.length === 0) return;
+    const target = ctx.openIntent === 'last' ? enabled[enabled.length - 1] : enabled[0];
+    const idx = ctx.itemsRef.current.findIndex((x) => x.id === target.id);
+    ctx.setActiveIndex(idx);
+    queueMicrotask(() => target.ref.current?.focus({ preventScroll: true }));
+    ctx.setOpenIntent(null);
+    // Depend only on ctx.open so this fires exactly when the menu transitions
+    // to open. openIntent is read but not re-fired on its own.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [ctx.open]);
+
+  // #303 (open path): once Floating UI has positioned the panel — and the
+  // size middleware has clamped its maxHeight — bring the active item into
+  // view. The open-intent focus above runs BEFORE positioning, while the
+  // portaled panel still sits at the document origin: scrollIntoView there
+  // would scroll the WINDOW to the top of the document, and the not-yet-
+  // clamped panel has nothing to scroll anyway (ArrowUp-open focuses the
+  // last item, which sits below the fold once the clamp lands). isPositioned
+  // resets to false on close, so this fires once per open.
+  useEffect(() => {
+    if (!ctx.open || !isPositioned) return;
+    if (ctx.activeIndex < 0) return;
+    const active = ctx.itemsRef.current[ctx.activeIndex];
+    active?.ref.current?.scrollIntoView?.({ block: 'nearest' });
+    // Mid-open activeIndex changes are scrolled by focusItem in the keydown
+    // path; this effect only covers the positioning transition.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [ctx.open, isPositioned]);
+
+  const handleKeyDown = (e: ReactKeyboardEvent<HTMLDivElement>) => {
+    // #528: React bubbles events through the REACT tree, so a surface opened
+    // from a menu item — ConfirmationPopover, Popover, Select, and every
+    // SubContent — delivers its key presses here even though its DOM is
+    // portaled outside this panel. Handling them stole the whole menu's
+    // keyboard: Tab closed the menu (unmounting the popover with it), Escape
+    // closed both instead of peeling one level, and Enter/Space were
+    // preventDefault-ed before the popover's own button could activate.
+    // Only keys that really happened inside this panel are ours; the deeper
+    // surface owns the rest (and its own Content, at depth+1, owns its keys).
+    if (!e.currentTarget.contains(e.target as Node)) return;
+
+    if (e.key === 'Escape') {
+      e.preventDefault();
+      ctx.setOpen(false);
+      ctx.triggerRef.current?.focus({ preventScroll: true });
+      return;
+    }
+    if (e.key === 'Tab') {
+      // Close, focus trigger, do NOT preventDefault — browser continues Tab
+      // traversal from the (now-focused) trigger to the next focusable element
+      // (the WAI-ARIA menu pattern).
+      ctx.setOpen(false);
+      ctx.triggerRef.current?.focus({ preventScroll: true });
+      return;
+    }
+
+    if (e.key === 'ArrowLeft' && ctx.depth > 0) {
+      e.preventDefault();
+      ctx.setOpen(false);
+      ctx.triggerRef.current?.focus({ preventScroll: true });
+      return;
+    }
+
+    if (e.key === 'ArrowRight') {
+      const items = ctx.itemsRef.current;
+      if (ctx.activeIndex >= 0 && ctx.activeIndex < items.length) {
+        const target = items[ctx.activeIndex];
+        if (target.openSubmenu) {
+          e.preventDefault();
+          target.openSubmenu();
+        }
+      }
+      return;
+    }
+
+    if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault();
+      const items = ctx.itemsRef.current;
+      if (ctx.activeIndex >= 0 && ctx.activeIndex < items.length) {
+        const target = items[ctx.activeIndex];
+        if (!target.disabled) {
+          if (target.openSubmenu) {
+            target.openSubmenu();
+          } else {
+            target.ref.current?.click();
+          }
+        }
+      }
+      return;
+    }
+
+    const items = ctx.itemsRef.current;
+    const enabledIndices = items.map((it, i) => (it.disabled ? -1 : i)).filter((i) => i !== -1);
+    if (enabledIndices.length === 0) return;
+
+    const currentPos = enabledIndices.indexOf(ctx.activeIndex);
+
+    const focusAt = (registryIndex: number) => {
+      ctx.setActiveIndex(registryIndex);
+      queueMicrotask(() => focusItem(items[registryIndex].ref.current));
+    };
+
+    switch (e.key) {
+      case 'ArrowDown': {
+        e.preventDefault();
+        const nextPos = currentPos === -1 ? 0 : (currentPos + 1) % enabledIndices.length;
+        focusAt(enabledIndices[nextPos]);
+        return;
+      }
+      case 'ArrowUp': {
+        e.preventDefault();
+        const prevPos =
+          currentPos === -1
+            ? enabledIndices.length - 1
+            : (currentPos - 1 + enabledIndices.length) % enabledIndices.length;
+        focusAt(enabledIndices[prevPos]);
+        return;
+      }
+      case 'Home': {
+        e.preventDefault();
+        focusAt(enabledIndices[0]);
+        return;
+      }
+      case 'End': {
+        e.preventDefault();
+        focusAt(enabledIndices[enabledIndices.length - 1]);
+        return;
+      }
+    }
+
+    // Typeahead: printable characters (length 1) with no modifier keys append
+    // to a debounced buffer and jump to the first non-disabled matching item.
+    // This block comes AFTER Enter/Space and Arrow/Home/End so those keys are
+    // not accidentally consumed here (' ' is length 1 but is caught above).
+    if (e.key.length === 1 && !e.altKey && !e.ctrlKey && !e.metaKey) {
+      const ta = typeaheadRef.current;
+      ta.buffer += e.key.toLowerCase();
+      if (ta.timer) clearTimeout(ta.timer);
+      ta.timer = setTimeout(() => {
+        ta.buffer = '';
+        ta.timer = null;
+      }, 500);
+
+      const match = items.findIndex(
+        (it) => !it.disabled && it.label.toLowerCase().startsWith(ta.buffer),
+      );
+      if (match !== -1) {
+        e.preventDefault();
+        focusAt(match);
+      }
+      return;
+    }
+  };
+
+  if (!ctx.open) return null;
+
+  return createPortal(
+    // {...rest} first so consumer-supplied props don't override the menu
+    // ARIA contract or our event wiring.
+    <div
+      {...rest}
+      ref={setFloatingRef}
+      id={ctx.contentId}
+      role="menu"
+      tabIndex={-1}
+      aria-orientation="vertical"
+      data-side={resolvedSide}
+      data-align={resolvedAlign}
+      data-dropdown-menu-content=""
+      data-dropdown-depth={ctx.depth}
+      data-in-overlay={inOverlay ? '' : undefined}
+      style={floatingStyles}
+      className={clsx(styles.content, className)}
+      onKeyDown={handleKeyDown}
+    >
+      {children}
+    </div>,
+    document.body,
+  );
+});

package/src/components/DropdownMenu/DropdownMenu.module.scss

@@ -0,0 +1,280 @@
+@use '../../styles/mixins' as *;
+@use './DropdownMenu.tokens';
+
+// `.content` carries both the visual chrome and the open-only entrance
+// animation. The animation half (transition + @starting-style + per-side
+// transform-origin rules below) relies on Floating UI being in `transform:
+// false` mode (see Content.tsx) so the CSS `transform` property is free for
+// the scale/translate entrance without clobbering placement.
+.content {
+  display: flex;
+  flex-direction: column;
+  gap: var(--dropdown-menu-gap);
+  min-width: var(--dropdown-menu-min-width);
+
+  // #303: Floating UI's size middleware inline-clamps maxHeight to the
+  // available viewport space; without these the clamped panel clips its
+  // items with no way to reach them.
+  overflow-y: auto;
+  overflow-x: hidden;
+
+  // Don't chain wheel/touch scrolling past the panel's edge to the page —
+  // the menu stays open while the page shifts underneath otherwise.
+  overscroll-behavior: contain;
+  padding: var(--dropdown-menu-padding);
+  background: var(--dropdown-menu-bg);
+  border: var(--border-width) solid var(--dropdown-menu-border-color);
+  border-radius: var(--dropdown-menu-radius);
+  box-shadow: var(--dropdown-menu-shadow);
+  z-index: var(--dropdown-menu-z);
+  outline: none;
+
+  // Explicit so each per-side @starting-style transform has a defined
+  // resting target to interpolate to. `none` is the CSS default; declaring
+  // it here prevents a future cleanup PR from removing the "redundant" line.
+  transform: none;
+  transition:
+    opacity var(--dropdown-menu-transition),
+    transform var(--dropdown-menu-transition);
+
+  // Open-only entrance — Content unmounts on close so there is no exit.
+  // @starting-style only applies while a transition is active; the
+  // prefers-reduced-motion override below disables the transition, which
+  // neutralises @starting-style (panel renders directly at its rest style).
+  @starting-style {
+    opacity: var(--opacity-hidden);
+  }
+}
+
+.content[data-in-overlay] {
+  z-index: var(--z-overlay-floating);
+}
+
+// #685: the tour's current target is INSIDE this surface — drop just under the
+// scrim (--z-tour) so only the target is lit, not the whole panel.
+.content[data-in-overlay]:has([data-tour-current-target]) {
+  z-index: calc(var(--z-tour) - 1);
+}
+
+.item {
+  display: flex;
+  align-items: center;
+  gap: var(--dropdown-menu-item-gap);
+  padding: var(--dropdown-menu-item-padding-y) var(--dropdown-menu-item-padding-x);
+  border-radius: var(--dropdown-menu-item-radius);
+  font-size: var(--dropdown-menu-item-font-size);
+  line-height: var(--dropdown-menu-item-line-height);
+  color: var(--dropdown-menu-item-fg);
+  cursor: pointer;
+  user-select: none;
+}
+
+.item:hover:not([aria-disabled='true']),
+.item:focus-visible:not([aria-disabled='true']) {
+  background: var(--dropdown-menu-item-bg-hover);
+}
+
+// Same defect as FileUpload/Slider (#513): the rule above shared its
+// background between :hover and :focus-visible, and the base rule's
+// `outline: none` (removed) suppressed the ring entirely.
+// INSET, but not because an outset ring would clip at rest: --dropdown-menu-
+// padding is 4px and an outset ring extends offset 2px + width 2px = 4px, so
+// at rest it fits exactly inside `.content`'s clip edge (overflow-y: auto;
+// overflow-x: hidden), first and last item included. The real reason is
+// --dropdown-menu-gap defaults to 0 — items are flush, so an OUTSET ring would
+// paint over the item above and below. PillMenu sets a gap; inset is kept
+// there too for one consistent ring and the checked-accent note below. A
+// *scrolled* menu still clips whichever item straddles the scrollport edge,
+// same as any inset call site.
+// What the inset ring covers: a checked item's left accent bar below
+// (box-shadow: inset ...-accent-width-checked, = --border-width-emphasis =
+// 2px) sits in exactly the same outermost 2px the ring occupies, and outline
+// paints above box-shadow — so a focused checked item loses its accent bar
+// completely. Acceptable: the checked background tint and `aria-checked`
+// both survive, so the state is still legible without it.
+.item:focus-visible:not([aria-disabled='true']) {
+  @include focus-ring($offset: calc(-1 * var(--ring-offset)));
+}
+
+.item[data-tone='danger'] {
+  color: var(--dropdown-menu-item-fg-danger);
+}
+
+.item[data-tone='danger']:hover:not([aria-disabled='true']),
+.item[data-tone='danger']:focus-visible:not([aria-disabled='true']) {
+  background: var(--dropdown-menu-item-bg-danger-hover);
+  color: var(--dropdown-menu-item-fg-danger);
+}
+
+.item[aria-disabled='true'] {
+  color: var(--dropdown-menu-item-fg-disabled);
+  cursor: not-allowed;
+}
+
+// Checked state for CheckboxItem / RadioItem: accent-tinted row with a 2px left
+// accent. Replaces the default ✓/● glyphs from earlier versions of the API.
+// Left corners square off so the 2px accent sits flush against a straight edge.
+.item[aria-checked='true'] {
+  background: var(--dropdown-menu-item-bg-checked);
+  color: var(--dropdown-menu-item-fg-checked);
+  box-shadow: inset var(--dropdown-menu-item-accent-width-checked) 0 0
+    var(--dropdown-menu-item-accent-checked);
+  border-top-left-radius: 0;
+  border-bottom-left-radius: 0;
+}
+
+// Hover/focus on a checked item keeps the accent tint instead of falling through
+// to the neutral bg-muted hover. The left accent remains visible.
+// NOTE: `tone="danger"` is not a valid prop on CheckboxItem or RadioItem
+// today. If ever added, re-examine this rule's source-order relationship
+// with `.item[data-tone='danger']:hover` — equal specificity means later
+// rule wins, and this rule would silently suppress the danger color.
+.item[aria-checked='true']:hover:not([aria-disabled='true']),
+.item[aria-checked='true']:focus-visible:not([aria-disabled='true']) {
+  background: var(--dropdown-menu-item-bg-checked);
+  color: var(--dropdown-menu-item-fg-checked);
+}
+
+// Disabled + checked: keep the visual cue but use disabled foreground so the
+// user can still see what was selected, just not interact with it.
+.item[aria-checked='true'][aria-disabled='true'] {
+  color: var(--dropdown-menu-item-fg-disabled);
+}
+
+.icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--dropdown-menu-icon-size);
+  height: var(--dropdown-menu-icon-size);
+  flex-shrink: 0;
+  color: var(--dropdown-menu-icon-fg);
+}
+
+.itemLabel {
+  flex: 1 1 auto;
+  overflow-wrap: anywhere;
+}
+
+// Trailing secondary content about the item itself (region code, count,
+// Badge). Sits between the label and `.shortcut` so a keyboard hint, when
+// both are present, stays rightmost. `flex-shrink: 0` keeps a short
+// qualifier intact — the label (`flex: 1 1 auto`) absorbs the squeeze.
+.meta {
+  display: inline-flex;
+  align-items: center;
+  flex-shrink: 0;
+  color: var(--dropdown-menu-meta-fg);
+  font-size: var(--dropdown-menu-meta-font-size);
+  padding-left: var(--dropdown-menu-meta-padding-left);
+}
+
+.shortcut {
+  color: var(--dropdown-menu-shortcut-fg);
+  font-size: var(--dropdown-menu-shortcut-font-size);
+  padding-left: var(--dropdown-menu-shortcut-padding-left);
+}
+
+.separator {
+  display: flex;
+  align-items: center;
+  height: var(--dropdown-menu-separator-height);
+}
+
+.separator::before {
+  content: '';
+  display: block;
+  width: 100%;
+  height: var(--border-width);
+  background: var(--dropdown-menu-separator-color);
+}
+
+.group {
+  display: flex;
+  flex-direction: column;
+  padding-block: var(--dropdown-menu-group-padding-block);
+}
+
+// Section label: uppercase muted text identifying a group of items.
+.label {
+  padding: var(--dropdown-menu-label-padding-y) var(--dropdown-menu-label-padding-x);
+  font-size: var(--dropdown-menu-label-font-size);
+  font-weight: var(--dropdown-menu-label-font-weight);
+  letter-spacing: var(--dropdown-menu-label-letter-spacing);
+  text-transform: uppercase;
+  color: var(--dropdown-menu-label-fg);
+  user-select: none;
+}
+
+// Optional indicator slot rendered when a custom <ItemIndicator> is provided
+// as a direct child of CheckboxItem/RadioItem. The default checked state has
+// no glyph (the row's tinted background + left accent IS the indicator).
+.indicatorSlot {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--dropdown-menu-indicator-size);
+  height: var(--dropdown-menu-indicator-size);
+  flex-shrink: 0;
+}
+
+.subTrigger {
+  // .subTrigger inherits all .item styles via the className composition.
+  // This class exists so we can target data-state in the rule below.
+  display: flex;
+}
+
+.subTriggerChevron {
+  display: inline-flex;
+  align-items: center;
+  font-size: var(--dropdown-menu-sub-chevron-font-size);
+  line-height: var(--dropdown-menu-sub-chevron-line-height);
+  color: var(--dropdown-menu-sub-chevron-fg);
+  padding-left: var(--dropdown-menu-sub-chevron-padding-left);
+}
+
+.subTrigger[data-state='open'] {
+  background: var(--dropdown-menu-sub-trigger-bg-open);
+}
+
+// --- Open-only entrance: per-side origin + starting-transform -------------
+// Each data-side variant sets transform-origin so the panel appears to grow
+// toward the trigger, and a 4px directional translate in @starting-style for
+// a subtle slide cue layered on top of the scale-fade declared on .content.
+.content[data-side='bottom'] {
+  transform-origin: top center;
+
+  @starting-style {
+    transform: scale(0.96) translateY(-4px);
+  }
+}
+
+.content[data-side='top'] {
+  transform-origin: bottom center;
+
+  @starting-style {
+    transform: scale(0.96) translateY(4px);
+  }
+}
+
+.content[data-side='right'] {
+  transform-origin: left center;
+
+  @starting-style {
+    transform: scale(0.96) translateX(-4px);
+  }
+}
+
+.content[data-side='left'] {
+  transform-origin: right center;
+
+  @starting-style {
+    transform: scale(0.96) translateX(4px);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .content {
+    transition: none;
+  }
+}