@multiplatform.one/components 6.1.0 → 6.4.0

package/src/DropdownMenu/index.tsx

@@ -0,0 +1,696 @@
+/**
+ * DropdownMenu — the canonical MP1 action menu.
+ *
+ * Trigger + elevated overlay of action rows. Wraps tamagui Popover and adds
+ * MP1 anatomy: SF-OVERLAY surface via the elevatedSurface knob recipe,
+ * SP-EDGE rows (container owns only its 1px border — zero padding on all
+ * four sides; items own ALL padding, so the first/last row highlights touch
+ * the top/bottom border, full-width, flat row corners), and a full
+ * keyboard layer (ArrowUp/Down + Home/End roving focus, Enter/Space
+ * selects, Escape closes and restores focus to the trigger, typeahead).
+ *
+ * Composable parts (DropdownMenu.Trigger/Content/Item/CheckboxItem/
+ * Separator/Label) plus a convenience `items=[]` prop for the common
+ * row-actions case.
+ */
+
+import {
+  createContext,
+  forwardRef,
+  isValidElement,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  type ReactNode,
+  type RefObject,
+} from "react";
+import {
+  Intent,
+  hairline,
+  menuRowFrame,
+  useResolvedKnobs,
+  warnBareDisabled,
+} from "@multiplatform.one/theme";
+import { CheckIcon } from "@phosphor-icons/react";
+import type { GetProps, PopoverContentProps, PopoverProps, TamaguiElement } from "tamagui";
+import {
+  Popover,
+  Text,
+  View,
+  XStack,
+  YStack,
+  isWeb,
+  styled,
+  useComposedRefs,
+  useControllableState,
+  useTheme,
+  withStaticProperties,
+} from "tamagui";
+import { componentColors } from "../componentColors";
+
+// ── Types ─────────────────────────────────────────────────────
+
+export type DropdownMenuPlacement = PopoverProps["placement"];
+
+export interface DropdownMenuItemSpec {
+  /** Stable key (defaults to index). */
+  key?: string;
+  label: ReactNode;
+  /** Leading icon node (phosphor icons inherit currentColor on web). */
+  icon?: ReactNode;
+  /** Trailing shortcut hint, e.g. "⌘C". */
+  shortcut?: string;
+  disabled?: boolean;
+  /**
+   * DG-ST-03 — explains why the item is disabled; renders inline under the
+   * label (no hover needed). Bare `disabled` DEV-warns `bare-disabled`.
+   */
+  disabledReason?: string;
+  /** Error-intent row (destructive action). */
+  destructive?: boolean;
+  /** Present ⇒ renders as a checkable item (menuitemcheckbox). */
+  checked?: boolean;
+  onCheckedChange?: (checked: boolean) => void;
+  onSelect?: () => void;
+}
+
+export type DropdownMenuEntry = DropdownMenuItemSpec | { separator: true };
+
+export interface DropdownMenuProps {
+  /**
+   * Composable children (Trigger + Content), or — when `items` is given —
+   * the trigger element itself.
+   */
+  children?: ReactNode;
+  /** Convenience declarative items; children become the trigger. */
+  items?: DropdownMenuEntry[];
+  /** Controlled open state. */
+  open?: boolean;
+  /** Uncontrolled initial open state. */
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  placement?: DropdownMenuPlacement;
+  /** Max menu height before the list scrolls (convenience `items` path). */
+  maxHeight?: number;
+}
+
+// ── Context ───────────────────────────────────────────────────
+
+interface DropdownMenuContextValue {
+  open: boolean;
+  setOpen: (open: boolean) => void;
+  triggerRef: RefObject<TamaguiElement | null>;
+  close: () => void;
+}
+
+const DropdownMenuContext = createContext<DropdownMenuContextValue | null>(null);
+
+function useDropdownMenuContext(part: string): DropdownMenuContextValue {
+  const ctx = useContext(DropdownMenuContext);
+  if (!ctx) throw new Error(`DropdownMenu.${part} must be used inside <DropdownMenu>`);
+  return ctx;
+}
+
+// ── Styled parts ──────────────────────────────────────────────
+
+// SP-EDGE geometry comes from the shared LC-16 `menuRowFrame` recipe (theme):
+// full-width row, own horizontal padding, flat corners, no focus outline —
+// the same frame Select options and MentionInput suggestions use. Menu-only
+// concerns stay local: cursor, gap, and the interactive color ramp.
+const ItemRow = styled(XStack, {
+  name: "DropdownMenuItem",
+  ...menuRowFrame,
+  gap: "$2.5",
+  cursor: "pointer",
+  hoverStyle: { backgroundColor: componentColors.interactive.hover },
+  pressStyle: { backgroundColor: componentColors.interactive.active },
+  // Focus highlight doubles as the roving-focus indicator (full-width row).
+  focusStyle: { backgroundColor: componentColors.interactive.hover, outlineStyle: "none" as any },
+  focusVisibleStyle: {
+    backgroundColor: componentColors.interactive.hover,
+    outlineStyle: "none" as any,
+  },
+  variants: {
+    disabled: {
+      true: {
+        cursor: "default",
+        opacity: 0.5,
+        hoverStyle: { backgroundColor: "transparent" },
+        pressStyle: { backgroundColor: "transparent" },
+        focusStyle: { backgroundColor: "transparent" },
+      },
+    },
+  } as const,
+});
+
+const SeparatorLine = styled(View, {
+  name: "DropdownMenuSeparator",
+  height: 1,
+  width: "100%",
+  backgroundColor: componentColors.divider,
+  marginVertical: "$1.5",
+});
+
+const MENU_ITEM_ATTR = "data-mp1-menu-item";
+
+// ── Root ──────────────────────────────────────────────────────
+
+function DropdownMenuRoot({
+  children,
+  items,
+  open: openProp,
+  defaultOpen = false,
+  onOpenChange,
+  placement = "bottom-start",
+  maxHeight,
+}: DropdownMenuProps) {
+  const [open, setOpen] = useControllableState({
+    prop: openProp,
+    defaultProp: defaultOpen,
+    onChange: onOpenChange,
+  });
+  const triggerRef = useRef<TamaguiElement | null>(null);
+
+  const close = useCallback(() => {
+    setOpen(false);
+    // Restore focus to the trigger after programmatic close (item select);
+    // Escape/outside-press restores are handled by the Popover focus scope.
+    if (isWeb) {
+      const node = triggerRef.current as unknown as HTMLElement | null;
+      if (node && typeof node.focus === "function") node.focus();
+    }
+  }, [setOpen]);
+
+  const ctx = useMemo<DropdownMenuContextValue>(
+    () => ({ open, setOpen, triggerRef, close }),
+    [open, setOpen, close],
+  );
+
+  return (
+    <DropdownMenuContext.Provider value={ctx}>
+      <Popover
+        open={open}
+        onOpenChange={setOpen}
+        placement={placement}
+        offset={4}
+        stayInFrame
+        allowFlip
+      >
+        {items ? (
+          <>
+            <DropdownMenuTrigger asChild={isValidElement(children)}>{children}</DropdownMenuTrigger>
+            <DropdownMenuContent maxHeight={maxHeight}>
+              {items.map((entry, index) =>
+                "separator" in entry && entry.separator ? (
+                  <DropdownMenuSeparator key={`separator-${index}`} />
+                ) : "checked" in entry && (entry as DropdownMenuItemSpec).checked !== undefined ? (
+                  <DropdownMenuCheckboxItem
+                    key={(entry as DropdownMenuItemSpec).key ?? index}
+                    checked={(entry as DropdownMenuItemSpec).checked!}
+                    onCheckedChange={(entry as DropdownMenuItemSpec).onCheckedChange}
+                    disabled={(entry as DropdownMenuItemSpec).disabled}
+                    disabledReason={(entry as DropdownMenuItemSpec).disabledReason}
+                    shortcut={(entry as DropdownMenuItemSpec).shortcut}
+                  >
+                    {(entry as DropdownMenuItemSpec).label}
+                  </DropdownMenuCheckboxItem>
+                ) : (
+                  <DropdownMenuItem
+                    key={(entry as DropdownMenuItemSpec).key ?? index}
+                    icon={(entry as DropdownMenuItemSpec).icon}
+                    shortcut={(entry as DropdownMenuItemSpec).shortcut}
+                    disabled={(entry as DropdownMenuItemSpec).disabled}
+                    disabledReason={(entry as DropdownMenuItemSpec).disabledReason}
+                    destructive={(entry as DropdownMenuItemSpec).destructive}
+                    onSelect={(entry as DropdownMenuItemSpec).onSelect}
+                  >
+                    {(entry as DropdownMenuItemSpec).label}
+                  </DropdownMenuItem>
+                ),
+              )}
+            </DropdownMenuContent>
+          </>
+        ) : (
+          children
+        )}
+      </Popover>
+    </DropdownMenuContext.Provider>
+  );
+}
+
+// ── Trigger ───────────────────────────────────────────────────
+
+export interface DropdownMenuTriggerProps extends GetProps<typeof Popover.Trigger> {}
+
+const DropdownMenuTrigger = forwardRef<TamaguiElement, DropdownMenuTriggerProps>(
+  function DropdownMenuTrigger({ onKeyDown, ...props }, forwardedRef) {
+    const ctx = useDropdownMenuContext("Trigger");
+    const composedRef = useComposedRefs(ctx.triggerRef, forwardedRef);
+    // Menu-button pattern (APG): activation keys open on KEYDOWN with
+    // preventDefault. Without this, a native-button trigger opens via its
+    // synthesized click and the same key sequence's KEYUP press-completion
+    // toggles the menu straight back closed — racing the open-auto-focus and
+    // ghost-activating the first item (Enter on "Actions" ran "Edit").
+    // preventDefault alone does not cancel that keyup press, so the pending
+    // keyup is swallowed with a one-shot capture listener.
+    const swallowNextKeyUp = (key: string) => {
+      const kill = (ue: globalThis.KeyboardEvent) => {
+        if (ue.key === key) {
+          ue.preventDefault();
+          ue.stopImmediatePropagation();
+        }
+        document.removeEventListener("keyup", kill, true);
+      };
+      document.addEventListener("keyup", kill, true);
+    };
+    const handleKeyDown = (e: globalThis.KeyboardEvent) => {
+      (onKeyDown as unknown as ((e: globalThis.KeyboardEvent) => void) | undefined)?.(e);
+      if (e.repeat) return;
+      if (e.key === "Enter" || e.key === " " || e.key === "ArrowDown") {
+        swallowNextKeyUp(e.key);
+        if (e.defaultPrevented) return; // composed trigger already activated
+        e.preventDefault();
+        if (e.key === "ArrowDown") {
+          if (!ctx.open) ctx.setOpen(true);
+        } else {
+          ctx.setOpen(!ctx.open);
+        }
+      }
+    };
+    return (
+      <Popover.Trigger
+        ref={composedRef}
+        aria-haspopup="menu"
+        aria-expanded={ctx.open}
+        {...(isWeb ? { onKeyDown: handleKeyDown as unknown as () => void } : undefined)}
+        {...props}
+      />
+    );
+  },
+);
+
+// ── Content ───────────────────────────────────────────────────
+
+export interface DropdownMenuContentProps extends PopoverContentProps {
+  /** Max height before the item list scrolls. */
+  maxHeight?: number;
+  /** Minimum menu width. */
+  minWidth?: number;
+}
+
+const DropdownMenuContent = forwardRef<TamaguiElement, DropdownMenuContentProps>(
+  function DropdownMenuContent({ children, maxHeight, minWidth = 200, ...props }, forwardedRef) {
+    const ctx = useDropdownMenuContext("Content");
+    const { knobProps } = useResolvedKnobs();
+    const innerRef = useRef<TamaguiElement | null>(null);
+    const composedRef = useComposedRefs(innerRef, forwardedRef);
+    const typeahead = useRef({ buffer: "", at: 0 });
+
+    const getItems = useCallback((): HTMLElement[] => {
+      const node = innerRef.current as unknown as HTMLElement | null;
+      if (!node) return [];
+      return Array.from(
+        node.querySelectorAll<HTMLElement>(`[${MENU_ITEM_ATTR}]:not([aria-disabled="true"])`),
+      );
+    }, []);
+
+    const focusItem = useCallback((el: HTMLElement | undefined) => {
+      el?.focus();
+    }, []);
+
+    // Menu pattern: focus lands on the first item when the menu opens.
+    const handleOpenAutoFocus = useCallback(
+      (event: Event) => {
+        event.preventDefault();
+        requestAnimationFrame(() => focusItem(getItems()[0]));
+      },
+      [focusItem, getItems],
+    );
+
+    // The Popover focus scope does not restore focus to the trigger on its
+    // own here, so do it explicitly on every close path.
+    const handleCloseAutoFocus = useCallback(
+      (event: Event) => {
+        event.preventDefault();
+        const node = ctx.triggerRef.current as unknown as HTMLElement | null;
+        if (node && typeof node.focus === "function") node.focus();
+      },
+      [ctx],
+    );
+
+    // Roving focus via a native listener on the content node — keydown from
+    // focused rows bubbles here (prop-level onKeyDown is not reliably
+    // forwarded through Popover.Content).
+    useEffect(() => {
+      if (!isWeb) return;
+      const node = innerRef.current as unknown as HTMLElement | null;
+      if (!node) return;
+      const handler = (event: globalThis.KeyboardEvent) => {
+        const items = getItems();
+        if (!items.length) return;
+        const index = items.indexOf(document.activeElement as HTMLElement);
+        switch (event.key) {
+          case "ArrowDown":
+            event.preventDefault();
+            focusItem(items[(index + 1) % items.length]);
+            break;
+          case "ArrowUp":
+            event.preventDefault();
+            focusItem(items[(index - 1 + items.length) % items.length]);
+            break;
+          case "Home":
+            event.preventDefault();
+            focusItem(items[0]);
+            break;
+          case "End":
+            event.preventDefault();
+            focusItem(items[items.length - 1]);
+            break;
+          case "Enter":
+          case " ":
+            // Fallback activation: click the focused row (the row-level
+            // React handler stops propagation when it handles this first).
+            if (index >= 0) {
+              event.preventDefault();
+              items[index].click();
+            }
+            break;
+          case "Escape":
+            event.preventDefault();
+            event.stopPropagation();
+            ctx.close();
+            break;
+          case "Tab":
+            // Menus are not tab-traversable: close instead.
+            ctx.close();
+            break;
+          default: {
+            // Typeahead: printable characters accumulate for 600ms.
+            if (event.key.length === 1 && !event.ctrlKey && !event.metaKey && !event.altKey) {
+              const now = Date.now();
+              const state = typeahead.current;
+              state.buffer = now - state.at > 600 ? event.key : state.buffer + event.key;
+              state.at = now;
+              const query = state.buffer.toLowerCase();
+              const start = index >= 0 ? index : 0;
+              const ordered = [...items.slice(start + 1), ...items.slice(0, start + 1)];
+              const match = ordered.find((el) =>
+                (el.textContent ?? "").trim().toLowerCase().startsWith(query),
+              );
+              if (match) focusItem(match);
+            }
+          }
+        }
+      };
+      node.addEventListener("keydown", handler);
+      return () => node.removeEventListener("keydown", handler);
+    }, [ctx, focusItem, getItems]);
+
+    return (
+      <Popover.Content
+        ref={composedRef}
+        role="menu"
+        {...knobProps.elevatedSurface}
+        // SP-EDGE: the container owns only its border — zero padding on all
+        // four sides. Rows reach every edge; the first/last row highlight
+        // touches the top/bottom border. overflow hidden clips full-width
+        // row highlights to the radius knob.
+        padding={0}
+        overflow="hidden"
+        minWidth={minWidth}
+        transition={knobProps.transition}
+        enterStyle={{ opacity: 0, y: -4, scale: 0.97 }}
+        exitStyle={{ opacity: 0, y: -4, scale: 0.97 }}
+        onOpenAutoFocus={handleOpenAutoFocus}
+        onCloseAutoFocus={handleCloseAutoFocus}
+        {...props}
+      >
+        <YStack
+          // SP-EDGE: no container padding — items own all their padding.
+          paddingVertical={0}
+          width="100%"
+          {...(maxHeight
+            ? { maxHeight, ...(isWeb ? { style: { overflowY: "auto" } as any } : {}) }
+            : {})}
+        >
+          {children}
+        </YStack>
+      </Popover.Content>
+    );
+  },
+);
+
+// ── Item ──────────────────────────────────────────────────────
+
+export interface DropdownMenuItemProps extends Omit<
+  GetProps<typeof ItemRow>,
+  "children" | "onSelect"
+> {
+  children: ReactNode;
+  /** Leading icon node. */
+  icon?: ReactNode;
+  /** Trailing shortcut hint, e.g. "⌘C". */
+  shortcut?: string;
+  disabled?: boolean;
+  /**
+   * DG-ST-03 — explains why the item is disabled; renders inline under the
+   * label (no hover needed). Bare `disabled` DEV-warns `bare-disabled`.
+   */
+  disabledReason?: string;
+  /** Error-intent row (destructive action). */
+  destructive?: boolean;
+  onSelect?: () => void;
+  /** Close the menu after selecting (default true). */
+  closeOnSelect?: boolean;
+}
+
+interface ItemBodyProps extends DropdownMenuItemProps {
+  leading?: ReactNode;
+}
+
+const DropdownMenuItemBody = forwardRef<TamaguiElement, ItemBodyProps>(
+  function DropdownMenuItemBody(
+    {
+      children,
+      icon,
+      shortcut,
+      disabled = false,
+      disabledReason,
+      destructive = false,
+      onSelect,
+      closeOnSelect = true,
+      role = "menuitem",
+      leading,
+      ...props
+    },
+    forwardedRef,
+  ) {
+    const ctx = useDropdownMenuContext("Item");
+    const { knobProps } = useResolvedKnobs();
+    const theme = useTheme();
+    // DG-ST-03: disabled menu items explain inline or DEV-warn.
+    warnBareDisabled({
+      component: "DropdownMenu.Item",
+      id: typeof children === "string" ? children : undefined,
+      disabled,
+      disabledReason,
+    });
+    const explainedDisable = disabled && Boolean(disabledReason?.trim());
+    // Resolved so phosphor icons pick it up via currentColor on web.
+    const iconColor = (destructive ? theme.red11?.get() : theme.color12?.get()) as
+      | string
+      | undefined;
+
+    const handleSelect = () => {
+      if (disabled) return;
+      onSelect?.();
+      if (closeOnSelect) ctx.close();
+    };
+
+    // Destructive rows ride the error sub-theme: step-11 text on the neutral
+    // overlay, hover highlight from the same hue's ramp.
+    const textColor = destructive ? "$red11" : componentColors.text.primary;
+
+    return (
+      <ItemRow
+        ref={forwardedRef}
+        role={role}
+        disabled={disabled}
+        aria-disabled={disabled || undefined}
+        minHeight={knobProps.sizeToken}
+        transition={knobProps.transition}
+        onPress={handleSelect}
+        {...(isWeb
+          ? ({
+              tabIndex: -1,
+              [MENU_ITEM_ATTR]: "",
+              // Enter/Space activation is handled by the menu-level native
+              // keydown listener in Content (single source, no double-fire).
+            } as any)
+          : {})}
+        {...(destructive && !disabled
+          ? {
+              hoverStyle: { backgroundColor: "$red3" },
+              pressStyle: { backgroundColor: "$red4" },
+              focusStyle: { backgroundColor: "$red3" },
+              focusVisibleStyle: { backgroundColor: "$red3" },
+            }
+          : {})}
+        {...(explainedDisable ? { paddingVertical: "$1.5" } : {})}
+        {...(props as any)}
+      >
+        {leading}
+        {icon ? (
+          <View
+            flexShrink={0}
+            alignItems="center"
+            justifyContent="center"
+            width={18}
+            {...(isWeb ? ({ style: { color: iconColor } } as any) : {})}
+          >
+            {icon}
+          </View>
+        ) : null}
+        {explainedDisable ? (
+          // DG-ST-03: the reason renders inline under the label — visible
+          // without hover (DG-OVL-05) and read as part of the item.
+          <YStack flexGrow={1} flexShrink={1} gap="$0.5">
+            <Text {...knobProps.body} color={textColor} fontSize="$3" numberOfLines={1}>
+              {children}
+            </Text>
+            <Text
+              {...knobProps.body}
+              color={componentColors.text.muted}
+              fontSize="$1"
+              data-mp-disabled-reason="true"
+            >
+              {disabledReason}
+            </Text>
+          </YStack>
+        ) : (
+          <Text
+            {...knobProps.body}
+            color={textColor}
+            fontSize="$3"
+            numberOfLines={1}
+            flexGrow={1}
+            flexShrink={1}
+          >
+            {children}
+          </Text>
+        )}
+        {shortcut ? (
+          <Text
+            {...knobProps.body}
+            color={componentColors.text.muted}
+            fontSize="$1"
+            flexShrink={0}
+            marginInlineStart="$4"
+            opacity={0.9}
+          >
+            {shortcut}
+          </Text>
+        ) : null}
+      </ItemRow>
+    );
+  },
+);
+
+const DropdownMenuItem = forwardRef<TamaguiElement, DropdownMenuItemProps>(
+  function DropdownMenuItem(props, ref) {
+    if (props.destructive) {
+      return (
+        <Intent name="error">
+          <DropdownMenuItemBody ref={ref} {...props} />
+        </Intent>
+      );
+    }
+    return <DropdownMenuItemBody ref={ref} {...props} />;
+  },
+);
+
+// ── CheckboxItem ──────────────────────────────────────────────
+
+export interface DropdownMenuCheckboxItemProps extends Omit<
+  DropdownMenuItemProps,
+  "destructive" | "icon" | "onSelect"
+> {
+  checked: boolean;
+  onCheckedChange?: (checked: boolean) => void;
+}
+
+const DropdownMenuCheckboxItem = forwardRef<TamaguiElement, DropdownMenuCheckboxItemProps>(
+  function DropdownMenuCheckboxItem(
+    { checked, onCheckedChange, closeOnSelect = false, ...props },
+    ref,
+  ) {
+    return (
+      <DropdownMenuItemBody
+        ref={ref}
+        role={"menuitemcheckbox" as any}
+        aria-checked={checked}
+        closeOnSelect={closeOnSelect}
+        onSelect={() => onCheckedChange?.(!checked)}
+        leading={
+          <View
+            width={18}
+            flexShrink={0}
+            alignItems="center"
+            justifyContent="center"
+            opacity={checked ? 1 : 0}
+          >
+            <CheckIcon size={14} weight="bold" />
+          </View>
+        }
+        {...props}
+      />
+    );
+  },
+);
+
+// ── Separator & Label ─────────────────────────────────────────
+
+export interface DropdownMenuSeparatorProps extends GetProps<typeof SeparatorLine> {}
+
+function DropdownMenuSeparator(props: DropdownMenuSeparatorProps) {
+  // Hairline: menu separators are dividers — one device pixel on high-DPI
+  // (Axiom 15), overridable by explicit consumer height.
+  return <SeparatorLine role="separator" {...hairline.height} {...props} />;
+}
+
+export interface DropdownMenuLabelProps extends GetProps<typeof Text> {
+  children: ReactNode;
+}
+
+function DropdownMenuLabel({ children, ...props }: DropdownMenuLabelProps) {
+  const { knobProps } = useResolvedKnobs();
+  return (
+    <Text
+      {...knobProps.body}
+      fontWeight="600"
+      fontSize="$1"
+      color={componentColors.text.muted}
+      paddingHorizontal="$3"
+      paddingVertical="$1.5"
+      userSelect="none"
+      {...props}
+    >
+      {children}
+    </Text>
+  );
+}
+
+// ── Export ────────────────────────────────────────────────────
+
+export const DropdownMenu = withStaticProperties(DropdownMenuRoot, {
+  Trigger: DropdownMenuTrigger,
+  Content: DropdownMenuContent,
+  Item: DropdownMenuItem,
+  CheckboxItem: DropdownMenuCheckboxItem,
+  Separator: DropdownMenuSeparator,
+  Label: DropdownMenuLabel,
+});
+
+export type DropdownMenuRowProps = GetProps<typeof ItemRow>;