@eocrm/design-system 0.0.0-stage → 0.6.17

package/src/components/DropdownMenu/Sub.tsx

@@ -0,0 +1,332 @@
+import {
+  createContext,
+  forwardRef,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type HTMLAttributes,
+  type MouseEvent,
+  type ReactNode,
+} from 'react';
+import clsx from 'clsx';
+import {
+  DropdownMenuContext,
+  SubParentContext,
+  useDropdownMenuContext,
+  type DropdownMenuContextValue,
+  type RegisteredItem,
+} from './context';
+import { mergeRefs, sanitizeId } from '../_internal/refs';
+import styles from './DropdownMenu.module.scss';
+import { Content, type DropdownMenuContentProps } from './Content';
+
+interface SubHoverContextValue {
+  closeTimerRef: React.MutableRefObject<ReturnType<typeof setTimeout> | null>;
+}
+
+const SubHoverContext = createContext<SubHoverContextValue | null>(null);
+
+function useSubHoverContext(component: string) {
+  const ctx = useContext(SubHoverContext);
+  if (!ctx) {
+    throw new Error(`<DropdownMenu.${component}> must be used inside <DropdownMenu.Sub>`);
+  }
+  return ctx;
+}
+
+/**
+ * Props for `<DropdownMenu.Sub>`.
+ *
+ * Supports both controlled (`open` + `onOpenChange`) and uncontrolled
+ * (`defaultOpen`) open-state patterns.
+ */
+export interface DropdownMenuSubProps {
+  /**
+   * The submenu trigger and content to render. Should contain exactly one
+   * `<DropdownMenu.SubTrigger>` and one `<DropdownMenu.SubContent>`.
+   */
+  children: ReactNode;
+  /** Controlled open state. When provided, `defaultOpen` is ignored. */
+  open?: boolean;
+  /** Called when the open state changes (user opens or closes the sub). */
+  onOpenChange?: (open: boolean) => void;
+  /** Initial open state when uncontrolled. Defaults to `false`. */
+  defaultOpen?: boolean;
+}
+
+/**
+ * Submenu container holding one `SubTrigger` and one `SubContent`.
+ * @see docs/components/DropdownMenu.md
+ */
+// Shadows the parent context; `closeAll()` chains to the parent's for cascading close.
+export function Sub({
+  children,
+  open: controlledOpen,
+  onOpenChange,
+  defaultOpen = false,
+}: DropdownMenuSubProps) {
+  const parentCtx = useDropdownMenuContext('Sub');
+
+  const isControlled = controlledOpen !== undefined;
+  const [uncontrolledOpen, setUncontrolledOpen] = useState(defaultOpen);
+  const open = isControlled ? (controlledOpen as boolean) : uncontrolledOpen;
+
+  const setOpen = useCallback(
+    (next: boolean) => {
+      onOpenChange?.(next);
+      if (!isControlled) setUncontrolledOpen(next);
+    },
+    [isControlled, onOpenChange],
+  );
+
+  const sharedCloseTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const triggerRef = useRef<HTMLElement | null>(null);
+  const reactId = useId();
+  const contentId = `dropdown-menu-sub-${sanitizeId(reactId)}`;
+  const [openIntent, setOpenIntent] = useState<'first' | 'last' | null>(null);
+
+  const itemsRef = useRef<RegisteredItem[]>([]);
+  const [activeIndex, setActiveIndex] = useState<number>(-1);
+
+  const registerItem = useCallback((item: RegisteredItem) => {
+    if (!itemsRef.current.some((x) => x.id === item.id)) {
+      itemsRef.current.push(item);
+    }
+    return () => {
+      itemsRef.current = itemsRef.current.filter((x) => x.id !== item.id);
+    };
+  }, []);
+
+  // Reset activeIndex when this sub closes.
+  useEffect(() => {
+    if (!open) setActiveIndex(-1);
+  }, [open]);
+
+  // closeAll: close THIS sub, then walk up via parent.
+  const closeAll = useCallback(() => {
+    setOpen(false);
+    parentCtx.closeAll();
+  }, [setOpen, parentCtx]);
+
+  const value: DropdownMenuContextValue = {
+    open,
+    setOpen,
+    triggerRef,
+    contentId,
+    openIntent,
+    setOpenIntent,
+    registerItem,
+    itemsRef,
+    activeIndex,
+    setActiveIndex,
+    closeAll,
+    depth: parentCtx.depth + 1,
+    inOverlay: parentCtx.inOverlay,
+    floatingId: parentCtx.floatingId,
+  };
+
+  return (
+    <SubParentContext.Provider value={parentCtx}>
+      <SubHoverContext.Provider value={{ closeTimerRef: sharedCloseTimerRef }}>
+        <DropdownMenuContext.Provider value={value}>{children}</DropdownMenuContext.Provider>
+      </SubHoverContext.Provider>
+    </SubParentContext.Provider>
+  );
+}
+
+/**
+ * Props for `<DropdownMenu.SubTrigger>`.
+ *
+ * Extends standard `div` HTML attributes. The ARIA attributes
+ * (`role="menuitem"`, `aria-haspopup`, `aria-expanded`, `aria-controls`,
+ * `aria-disabled`) are always set by the component.
+ */
+export interface DropdownMenuSubTriggerProps extends HTMLAttributes<HTMLDivElement> {
+  /** When `true`, the trigger renders dimmed and pointer/keyboard interaction does not open the sub. */
+  disabled?: boolean;
+  /** Optional leading icon. Rendered in a fixed-size slot, matching `<DropdownMenu.Item>`'s icon slot. */
+  icon?: ReactNode;
+  /** The trigger label text. String children participate in the parent menu's typeahead. */
+  children: ReactNode;
+}
+
+/**
+ * Trigger for a submenu: a menu item in the parent menu with a trailing chevron.
+ * @see docs/components/DropdownMenu.md
+ */
+// Registers in the parent context's item registry for keyboard navigation.
+export const SubTrigger = forwardRef<HTMLDivElement, DropdownMenuSubTriggerProps>(
+  function SubTrigger({ disabled = false, icon, className, children, ...rest }, forwardedRef) {
+    const subCtx = useDropdownMenuContext('SubTrigger');
+    const parentCtx = useContext(SubParentContext);
+    if (!parentCtx) {
+      throw new Error('<DropdownMenu.SubTrigger> must be used inside <DropdownMenu.Sub>');
+    }
+    const hoverCtx = useSubHoverContext('SubTrigger');
+    const closeTimerRef = hoverCtx.closeTimerRef;
+
+    const triggerRefLocal = useRef<HTMLDivElement | null>(null);
+    const openTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+    const id = useId();
+    const labelText = typeof children === 'string' ? children : '';
+
+    // Register with PARENT's registry — SubTrigger IS a menuitem in the parent
+    // menu. openSubmenu lets ArrowRight (Task 12) invoke this from the parent.
+    useLayoutEffect(() => {
+      return parentCtx.registerItem({
+        id,
+        ref: triggerRefLocal,
+        disabled,
+        label: labelText,
+        openSubmenu: () => {
+          subCtx.setOpenIntent('first');
+          subCtx.setOpen(true);
+        },
+      });
+    }, [parentCtx, id, disabled, labelText, subCtx]);
+
+    const index = parentCtx.itemsRef.current.findIndex((x) => x.id === id);
+    const isActive = index !== -1 && index === parentCtx.activeIndex;
+
+    // Also save into subCtx.triggerRef so SubContent (Task 10) positions
+    // against the SubTrigger element.
+    useLayoutEffect(() => {
+      subCtx.triggerRef.current = triggerRefLocal.current;
+    });
+
+    // Cleanup on unmount.
+    useEffect(() => {
+      return () => {
+        if (openTimerRef.current) clearTimeout(openTimerRef.current);
+        if (closeTimerRef.current) clearTimeout(closeTimerRef.current);
+      };
+    }, [closeTimerRef]);
+
+    // Any open-state transition supersedes pending hover intent. Critically:
+    // a CLOSE while the 100ms hover-open timer is still pending (hover →
+    // click-open → pick-close, all inside the window) must cancel that timer,
+    // or it re-opens the sub right after the pick — an intermittent CI
+    // failure and a real-browser bug (fast hover+click+pick). Clearing the
+    // shared close timer on transitions is the symmetric guard (e.g. a
+    // keyboard re-open racing a pending hover-close).
+    useEffect(() => {
+      if (openTimerRef.current) {
+        clearTimeout(openTimerRef.current);
+        openTimerRef.current = null;
+      }
+      if (closeTimerRef.current) {
+        clearTimeout(closeTimerRef.current);
+        closeTimerRef.current = null;
+      }
+    }, [subCtx.open, closeTimerRef]);
+
+    const handlePointerEnter = useCallback(() => {
+      if (disabled) return;
+      // Cancel any pending close.
+      if (closeTimerRef.current) {
+        clearTimeout(closeTimerRef.current);
+        closeTimerRef.current = null;
+      }
+      if (subCtx.open) return;
+      openTimerRef.current = setTimeout(() => {
+        subCtx.setOpen(true);
+        openTimerRef.current = null;
+      }, 100);
+    }, [disabled, subCtx, closeTimerRef]);
+
+    const handlePointerLeave = useCallback(() => {
+      // Cancel pending open.
+      if (openTimerRef.current) {
+        clearTimeout(openTimerRef.current);
+        openTimerRef.current = null;
+      }
+      if (!subCtx.open) return;
+      closeTimerRef.current = setTimeout(() => {
+        subCtx.setOpen(false);
+        closeTimerRef.current = null;
+      }, 200);
+    }, [subCtx, closeTimerRef]);
+
+    const handleClick = (_e: MouseEvent) => {
+      if (disabled) return;
+      subCtx.setOpen(true);
+    };
+
+    return (
+      // {...rest} first so role / aria / event wiring always win.
+      <div
+        {...rest}
+        ref={mergeRefs<HTMLDivElement>(triggerRefLocal, forwardedRef)}
+        role="menuitem"
+        tabIndex={isActive ? 0 : -1}
+        aria-haspopup="menu"
+        aria-expanded={subCtx.open}
+        aria-controls={subCtx.open ? subCtx.contentId : undefined}
+        aria-disabled={disabled || undefined}
+        data-state={subCtx.open ? 'open' : 'closed'}
+        className={clsx(styles.item, styles.subTrigger, className)}
+        onClick={handleClick}
+        onPointerEnter={handlePointerEnter}
+        onPointerLeave={handlePointerLeave}
+      >
+        {icon !== undefined && <span className={styles.icon}>{icon}</span>}
+        <span className={styles.itemLabel}>{children}</span>
+        <span className={styles.subTriggerChevron} aria-hidden="true">
+          ›
+        </span>
+      </div>
+    );
+  },
+);
+
+/**
+ * Props for `<DropdownMenu.SubContent>`.
+ *
+ * Identical to `<DropdownMenu.Content>` props — `side`, `align`,
+ * `sideOffset`, `minWidth`, and standard `div` HTML attributes all apply.
+ */
+export type DropdownMenuSubContentProps = DropdownMenuContentProps;
+
+/**
+ * Floating panel for a submenu.
+ * @see docs/components/DropdownMenu.md
+ */
+// Thin wrapper over `Content` (which handles ArrowLeft at depth > 0); moving from the SubTrigger into it cancels the pending close timer.
+export const SubContent = forwardRef<HTMLDivElement, DropdownMenuSubContentProps>(
+  function SubContent({ side = 'right', ...props }, ref) {
+    const hoverCtx = useSubHoverContext('SubContent');
+    const subCtx = useDropdownMenuContext('SubContent');
+
+    const handlePointerEnter = useCallback(() => {
+      // Cancel pending close — mouse is back inside the chain.
+      if (hoverCtx.closeTimerRef.current) {
+        clearTimeout(hoverCtx.closeTimerRef.current);
+        hoverCtx.closeTimerRef.current = null;
+      }
+    }, [hoverCtx]);
+
+    const handlePointerLeave = useCallback(() => {
+      if (!subCtx.open) return;
+      if (hoverCtx.closeTimerRef.current) clearTimeout(hoverCtx.closeTimerRef.current);
+      hoverCtx.closeTimerRef.current = setTimeout(() => {
+        subCtx.setOpen(false);
+        hoverCtx.closeTimerRef.current = null;
+      }, 200);
+    }, [hoverCtx, subCtx]);
+
+    return (
+      <Content
+        ref={ref}
+        side={side}
+        {...props}
+        onPointerEnter={handlePointerEnter}
+        onPointerLeave={handlePointerLeave}
+      />
+    );
+  },
+);

package/src/components/DropdownMenu/Trigger.tsx

@@ -0,0 +1,76 @@
+import {
+  cloneElement,
+  isValidElement,
+  useCallback,
+  type KeyboardEvent as ReactKeyboardEvent,
+  type PointerEvent,
+  type ReactElement,
+  type Ref,
+} from 'react';
+import { useDropdownMenuContext } from './context';
+import { chain, mergeRefs } from '../_internal/refs';
+
+export interface DropdownMenuTriggerProps {
+  /**
+   * Exactly one React element. The Trigger clones this element to inject a
+   * ref, `aria-haspopup="menu"`, `aria-expanded`, `aria-controls`, and the
+   * pointerdown/keyboard handlers that open the menu. The child must accept
+   * a ref (i.e. use `forwardRef` if it's a custom component); a raw
+   * `<button>` or the library's `<Button>` both qualify.
+   */
+  children: ReactElement;
+}
+
+/**
+ * Clones its single child to inject the open-toggle handlers and ARIA; the child must accept a ref.
+ * @see docs/components/DropdownMenu.md
+ */
+export function Trigger({ children }: DropdownMenuTriggerProps) {
+  const ctx = useDropdownMenuContext('Trigger');
+
+  if (!isValidElement(children)) {
+    throw new Error('<DropdownMenu.Trigger> requires exactly one React element child.');
+  }
+
+  const childProps = children.props as {
+    onPointerDown?: (e: PointerEvent) => void;
+    onKeyDown?: (e: ReactKeyboardEvent<HTMLElement>) => void;
+    ref?: Ref<HTMLElement>;
+  };
+
+  // Toggle on pointerdown rather than click. Keyboard activation (Enter/Space)
+  // fires a synthesized click that would race a keydown-open handler and
+  // double-toggle the menu shut. Pointerdown is mouse/touch only; keyboard
+  // activation routes through onKeyDown below.
+  const handlePointerDown = useCallback(
+    (_e: PointerEvent) => {
+      ctx.setOpen(!ctx.open);
+    },
+    [ctx],
+  );
+
+  const handleKeyDown = useCallback(
+    (e: ReactKeyboardEvent<HTMLElement>) => {
+      if (ctx.open) return;
+      if (e.key === 'Enter' || e.key === ' ' || e.key === 'ArrowDown') {
+        e.preventDefault();
+        ctx.setOpenIntent('first');
+        ctx.setOpen(true);
+      } else if (e.key === 'ArrowUp') {
+        e.preventDefault();
+        ctx.setOpenIntent('last');
+        ctx.setOpen(true);
+      }
+    },
+    [ctx],
+  );
+
+  return cloneElement(children, {
+    ref: mergeRefs(ctx.triggerRef, childProps.ref),
+    'aria-haspopup': 'menu',
+    'aria-expanded': ctx.open,
+    'aria-controls': ctx.open ? ctx.contentId : undefined,
+    onPointerDown: chain(childProps.onPointerDown, handlePointerDown),
+    onKeyDown: chain(childProps.onKeyDown, handleKeyDown),
+  } as Partial<unknown> as object);
+}

package/src/components/DropdownMenu/context.ts

@@ -0,0 +1,65 @@
+import { createContext, useContext, type RefObject } from 'react';
+
+export interface RegisteredItem {
+  id: string;
+  ref: RefObject<HTMLDivElement | null>;
+  disabled: boolean;
+  label: string;
+  /** If this item is a SubTrigger, called when ArrowRight is pressed while it's the active item. Set by SubTrigger in later tasks. */
+  openSubmenu?: () => void;
+}
+
+export interface DropdownMenuContextValue {
+  open: boolean;
+  setOpen: (next: boolean) => void;
+  triggerRef: React.MutableRefObject<HTMLElement | null>;
+  contentId: string;
+  openIntent: 'first' | 'last' | null;
+  setOpenIntent: (intent: 'first' | 'last' | null) => void;
+  registerItem: (item: RegisteredItem) => () => void;
+  itemsRef: React.MutableRefObject<RegisteredItem[]>;
+  activeIndex: number;
+  setActiveIndex: (i: number) => void;
+  /** Walks up the recursive context chain and closes every menu (root + all subs). Submenus override to chain. */
+  closeAll: () => void;
+  /** 0 = root menu, 1 = first-level submenu, etc. */
+  depth: number;
+  /** True when the menu tree is opened inside a Modal/Drawer overlay. Computed at the root from the root trigger, inherited by submenus. */
+  inOverlay: boolean;
+  /** The menu tree's floating-surface id (registered once at the root). Content panels gate their Escape on `overlayStack.isTopFloating(floatingId)` so the whole menu defers to a DEEPER surface — e.g. a ConfirmationPopover opened from an item (#280). Inherited by submenus. */
+  floatingId: string;
+}
+
+export const DropdownMenuContext = createContext<DropdownMenuContextValue | null>(null);
+
+export function useDropdownMenuContext(component: string): DropdownMenuContextValue {
+  const ctx = useContext(DropdownMenuContext);
+  if (!ctx) {
+    throw new Error(`<DropdownMenu.${component}> must be used inside <DropdownMenu>`);
+  }
+  return ctx;
+}
+
+export interface GroupContextValue {
+  labelId: string;
+}
+
+export const GroupContext = createContext<GroupContextValue | null>(null);
+
+export interface RadioGroupContextValue {
+  value: string;
+  onValueChange: (value: string) => void;
+}
+
+export const RadioGroupContext = createContext<RadioGroupContextValue | null>(null);
+
+export function useRadioGroupContext(component: string): RadioGroupContextValue {
+  const ctx = useContext(RadioGroupContext);
+  if (!ctx) {
+    throw new Error(`<DropdownMenu.${component}> must be used inside <DropdownMenu.RadioGroup>`);
+  }
+  return ctx;
+}
+
+/** Provided by `<Sub>` so `<SubTrigger>` can read the PARENT context (where it registers as a menuitem) while still being inside the SUB's DropdownMenuContext provider. */
+export const SubParentContext = createContext<DropdownMenuContextValue | null>(null);

package/src/components/DropdownMenu/index.ts

@@ -0,0 +1,20 @@
+export { DropdownMenu } from './DropdownMenu';
+export type {
+  DropdownMenuProps,
+  DropdownMenuTriggerProps,
+  DropdownMenuContentProps,
+  DropdownMenuItemProps,
+  DropdownMenuSeparatorProps,
+  DropdownMenuSide,
+  DropdownMenuAlign,
+  DropdownMenuItemTone,
+  DropdownMenuGroupProps,
+  DropdownMenuLabelProps,
+  DropdownMenuItemIndicatorProps,
+  DropdownMenuCheckboxItemProps,
+  DropdownMenuRadioGroupProps,
+  DropdownMenuRadioItemProps,
+  DropdownMenuSubProps,
+  DropdownMenuSubTriggerProps,
+  DropdownMenuSubContentProps,
+} from './DropdownMenu';

package/src/components/EmojiPicker/EmojiPicker.module.scss

@@ -0,0 +1,84 @@
+@use '../../styles/mixins' as *;
+@use './EmojiPicker.tokens';
+
+.root {
+  display: flex;
+  flex-direction: column;
+  gap: var(--emoji-picker-section-gap);
+}
+
+.search {
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+}
+
+.searchIcon {
+  flex-shrink: 0;
+  color: var(--emoji-picker-search-icon-fg);
+}
+
+// Rule 4 note: internal flex layout — the public component is the picker
+// panel, not the search input. The picker owns the search row's arrangement
+// (mirrors OptionsPicker's `.searchInput`).
+.searchInput {
+  flex: 1;
+  border: none;
+  background: transparent;
+}
+
+// The scrollable grid surface. Width is the picker's own intrinsic size
+// (see EmojiPicker.tokens.scss) — not consumer layout.
+.panel {
+  display: flex;
+  flex-direction: column;
+  gap: var(--emoji-picker-section-gap);
+  width: var(--emoji-picker-width);
+  max-height: var(--emoji-picker-max-height);
+  overflow-y: auto;
+}
+
+.section {
+  display: flex;
+  flex-direction: column;
+  gap: var(--emoji-picker-grid-gap);
+}
+
+.sectionLabel {
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+
+.grid {
+  display: grid;
+  grid-template-columns: repeat(8, 1fr);
+  gap: var(--emoji-picker-grid-gap);
+}
+
+// Button reset + square-ish cell. Width comes from the grid track (1fr
+// stretch), so no explicit width is set (Rule 4).
+.cell {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  height: var(--emoji-picker-cell-size);
+  padding: 0;
+  border: none;
+  border-radius: var(--emoji-picker-radius);
+  background: none;
+  font-size: var(--emoji-picker-emoji-size);
+  line-height: 1;
+  cursor: pointer;
+
+  &:hover {
+    background: var(--emoji-picker-cell-hover-bg);
+  }
+
+  &:focus-visible {
+    @include focus-ring;
+  }
+}
+
+.noResults {
+  text-align: center;
+}

package/src/components/EmojiPicker/EmojiPicker.tokens.scss

@@ -0,0 +1,24 @@
+// EmojiPicker.tokens.scss — component-scoped tokens for <EmojiPicker>.
+:root {
+  // Panel sizing — the picker owns its own intrinsic panel size (mirrors how
+  // OptionsPicker sizes its own panel with literal px). width/max-height are
+  // NOT covered by stylelint's strict-value set, but no existing size token
+  // fits these values, so literals are used deliberately here.
+  --emoji-picker-width: 320px;
+  --emoji-picker-max-height: 280px;
+
+  // Cell (one emoji button) + the emoji glyph inside it
+  --emoji-picker-cell-size: var(--size-md);
+  --emoji-picker-emoji-size: var(--font-size-lg);
+
+  // Spacing
+  --emoji-picker-grid-gap: var(--space-1);
+  --emoji-picker-section-gap: var(--space-3);
+
+  // Cell affordances
+  --emoji-picker-radius: var(--radius-sm);
+  --emoji-picker-cell-hover-bg: var(--color-bg-muted);
+
+  // Search row
+  --emoji-picker-search-icon-fg: var(--color-fg-subtle);
+}