zidane-ui 9.1.1 → 9.1.4

package/src/components/Menu.tsx

@@ -1,435 +0,0 @@
-/**
- * Menu rows and their furniture: one row for every menu, list and picker in
- * the app (`.zg-menu-row` in styles/primitives.css). A row is icon, title (+ optional
- * description), then a trailing slot for a check, a switch, a keycap or a
- * meta value.
- *
- * One picker language:
- *   - single choice: `checked` on the current row (trailing check, medium
- *     title). No leading radio dots.
- *   - on/off option: `toggle` (a trailing `MenuSwitch`).
- *   - a leading `icon` only when the glyph means something (a kind, a folder).
- *   - a description truncates to one line after the title; `size="lg"`
- *     stacks it under the title, clamped to two lines. A compact list
- *     explains its rows with `useRowHint` + a `MenuNote` under it instead.
- *   - notes and empty states: `MenuNote` (sans, muted); `zg-meta` is for values.
- * `active` is the keyboard cursor. `render` draws the row as another element
- * (a router link in a nav list): it receives the row's props to spread; the
- * current page (`aria-current="page"`) shows as the raised chip.
- *
- * Keyboard: a `menu` or `listbox` moves focus between its enabled rows with
- * the arrows (wrapping), Home / End and a first-letter jump. Focus is real
- * DOM focus on the row buttons (roving), so Enter / Space are the buttons'
- * own. A list whose focus stays elsewhere (the composer's suggestions, driven
- * from the editor through `active`) never sees these keys.
- */
-import {
-  createContext,
-  forwardRef,
-  useContext,
-  useId,
-  useState,
-  type ButtonHTMLAttributes,
-  type CSSProperties,
-  type KeyboardEvent,
-  type ReactElement,
-  type ReactNode,
-} from 'react';
-
-import { useLabels } from '../labels';
-import { SwitchGlyph } from './SwitchGlyph';
-
-/** The role a row takes by default, from the list it sits in (a row inside a `menu` is a `menuitem`). */
-const ROW_ROLE = { menu: 'menuitem', listbox: 'option', group: undefined } as const;
-const MenuRoleContext = createContext<keyof typeof ROW_ROLE | null>(null);
-/** Roles whose state is `aria-checked`; an `option` says it with `aria-selected`, a plain item not at all. */
-const CHECKABLE = new Set(['menuitemcheckbox', 'menuitemradio', 'switch', 'checkbox', 'radio']);
-
-/** Props of {@link MenuRow}. It also accepts the attributes of a `button`, except `title`. */
-export interface MenuRowProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'title'> {
-  /**
-   * Leading glyph, drawn muted. Use it only when it means something (a kind, a folder). No icon
-   * slot renders when omitted.
-   */
-  icon?: ReactNode;
-  /** The row's label. */
-  title: ReactNode;
-  /**
-   * Secondary text after the title. Inline it truncates to one line; `size="lg"` stacks it under
-   * the title, clamped to two lines.
-   */
-  description?: ReactNode;
-  /**
-   * Content at the row's end, such as a keycap or a meta value. A check or switch from `checked` or
-   * `toggle` follows it.
-   */
-  trailing?: ReactNode;
-  /** Keyboard cursor / hovered-by-nav row. */
-  active?: boolean;
-  /** The current choice: a check in the trailing slot. */
-  checked?: boolean;
-  /** An on/off option: a switch in the trailing slot (use with `role="menuitemcheckbox"`). */
-  toggle?: boolean;
-  /**
-   * Tones the row as dangerous: the title and glyph take the danger colour.
-   * @default false
-   */
-  destructive?: boolean;
-  /**
-   * Row density. `lg` stacks the description under the title.
-   * @default 'md'
-   */
-  size?: 'sm' | 'md' | 'lg';
-  /** Native tooltip (the row's `title` prop is its label). */
-  hint?: string;
-  /** Applied to the description's own box (e.g. a fade that must hide its ellipsis too). */
-  descriptionClassName?: string;
-  /** Render another element with the row's look (a link). */
-  render?: (props: MenuRowRenderProps) => ReactElement;
-}
-
-/** Props {@link MenuRowProps.render} receives to spread onto the element it renders. */
-export interface MenuRowRenderProps {
-  /** The row's classes, merged with the caller's `className`. */
-  className: string;
-  /** Native tooltip, from the `hint` prop. */
-  title?: string;
-  /** The row's `size`. */
-  'data-size': 'sm' | 'md' | 'lg';
-  /** Set to an empty string while the row is `active`. */
-  'data-active'?: '';
-  /** Set to an empty string while the row is `destructive`. */
-  'data-destructive'?: '';
-  /** The current choice: where focus lands when the menu opens. */
-  'data-checked'?: '';
-  /** The row's content: icon, title, description and trailing slot. */
-  children: ReactNode;
-}
-
-/**
- * Renders one row of a menu, list or picker: icon, title, optional description and a trailing
- * slot. `checked` marks the current choice with a check, `toggle` shows a switch, and `active`
- * marks the keyboard cursor. Use `render` to draw another element with the row's look. The
- * ref goes to the `button`.
- */
-export const MenuRow = forwardRef<HTMLButtonElement, MenuRowProps>(function MenuRow(
-  {
-    icon,
-    title,
-    description,
-    trailing,
-    active = false,
-    checked = false,
-    toggle,
-    destructive = false,
-    size = 'md',
-    hint,
-    descriptionClassName = '',
-    className = '',
-    type = 'button',
-    render,
-    ...rest
-  },
-  ref,
-) {
-  const labels = useLabels();
-  const container = useContext(MenuRoleContext);
-  const role = rest.role ?? (container ? ROW_ROLE[container] : undefined);
-  const stacked = size === 'lg' && description;
-  // The check is the only sign of the current choice unless the role already says it.
-  const stateInRole = role !== undefined && (CHECKABLE.has(role) || role === 'option');
-  const content = (
-    <>
-      {icon !== undefined && (
-        <span
-          // A destructive row's glyph takes the row's colour; others stay muted.
-          className={`shrink-0 inline-flex items-center justify-center w-4 ${destructive ? '' : 'text-[var(--zg-text-muted)]'} ${stacked ? 'mt-0.5' : ''}`}
-        >
-          {icon}
-        </span>
-      )}
-      <span className={`flex-1 min-w-0 flex ${stacked ? 'flex-col gap-0.5' : 'items-baseline gap-2'}`}>
-        {/* Inline, the title stays whole and the description gives way. */}
-        <span
-          className={`${stacked ? 'font-medium' : description ? 'shrink-0 max-w-[65%] truncate' : 'truncate'} ${
-            checked && !stacked ? 'font-medium' : ''
-          }`}
-        >
-          {title}
-        </span>
-        {description && (
-          <span
-            className={`min-w-0 text-zg-meta text-[var(--zg-text-muted)] ${stacked ? 'leading-snug zg-line-clamp-2' : 'truncate'} ${descriptionClassName}`}
-          >
-            {description}
-          </span>
-        )}
-      </span>
-      {(trailing || checked || toggle !== undefined) && (
-        <span className={`shrink-0 inline-flex items-center gap-1.5 ${stacked ? 'mt-0.5' : ''}`}>
-          {trailing}
-          {checked &&
-            (stateInRole ? (
-              <span aria-hidden className="i-ph-check text-zg-ui text-[var(--zg-accent)]" />
-            ) : (
-              <span role="img" className="i-ph-check text-zg-ui text-[var(--zg-accent)]" aria-label={labels.current} />
-            ))}
-          {toggle !== undefined && <MenuSwitch on={toggle} />}
-        </span>
-      )}
-    </>
-  );
-  const look: MenuRowRenderProps = {
-    className: `zg-menu-row zg-press-subtle ${className}`,
-    title: hint,
-    'data-size': size,
-    'data-active': active ? '' : undefined,
-    'data-destructive': destructive ? '' : undefined,
-    'data-checked': checked ? '' : undefined,
-    children: content,
-  };
-  if (render) return render(look);
-  return (
-    <button
-      ref={ref}
-      type={type}
-      aria-checked={role && CHECKABLE.has(role) ? (toggle ?? checked) : undefined}
-      aria-selected={role === 'option' ? checked : undefined}
-      {...look}
-      {...rest}
-      role={role}
-    />
-  );
-});
-
-/** Props for {@link MenuSection}. */
-export interface MenuSectionProps {
-  /** Heading above the rows. It names the group. */
-  label?: ReactNode;
-  /** Content at the end of the heading row, such as a count or an action. */
-  trailing?: ReactNode;
-  /** The rows in the group. */
-  children: ReactNode;
-  /** Extra classes on the group element. */
-  className?: string;
-  /** Inline styles on the root element, merged after the component's own. */
-  style?: CSSProperties;
-}
-
-/**
- * A labelled group of rows.
- *
- * @param props - Component props.
- */
-export function MenuSection({ label, trailing, children, className = '', style }: MenuSectionProps) {
-  const labelId = useId();
-  return (
-    <div role="group" aria-labelledby={label ? labelId : undefined} className={className} style={style}>
-      {label && (
-        <div className="flex items-center justify-between gap-2 px-2 pt-2 pb-1">
-          <span id={labelId} className="zg-section-label">
-            {label}
-          </span>
-          {trailing}
-        </div>
-      )}
-      {children}
-    </div>
-  );
-}
-
-/** Props for {@link MenuSeparator}. */
-export interface MenuSeparatorProps {
-  /** Extra classes on the root element. */
-  className?: string;
-  /** Inline styles on the root element, merged after the component's own. */
-  style?: CSSProperties;
-}
-
-/**
- * Renders a thin rule between groups of rows. In a `listbox` it is drawing only, since a
- * listbox may hold only options and groups.
- *
- * @param props - Component props.
- */
-export function MenuSeparator({ className, style }: MenuSeparatorProps) {
-  const classes = ['zg-menu-sep', className].filter(Boolean).join(' ');
-  // A listbox may only hold options and groups: there the rule is drawing only.
-  if (useContext(MenuRoleContext) === 'listbox') return <div aria-hidden className={classes} style={style} />;
-  return <div role="separator" className={classes} style={style} />;
-}
-
-const ROW = '.zg-menu-row';
-
-function enabledRows(root: HTMLElement): HTMLElement[] {
-  return Array.from(root.querySelectorAll<HTMLElement>(ROW)).filter(
-    (row) => !(row as HTMLButtonElement).disabled && row.getAttribute('aria-disabled') !== 'true',
-  );
-}
-
-function isTyping(el: EventTarget | null) {
-  return (
-    el instanceof HTMLInputElement ||
-    el instanceof HTMLTextAreaElement ||
-    (el instanceof HTMLElement && el.isContentEditable)
-  );
-}
-
-/**
- * Arrow / Home / End / first-letter navigation between the enabled rows
- * under `event.currentTarget`. Handled keys stop here: the surface is portaled,
- * and React would otherwise bubble them into the composer behind it.
- *
- * @param event - The keydown event of the list. Keys typed in a text field, or with Alt, Ctrl or
- * Meta held, are ignored.
- */
-export function handleMenuKeyDown(event: KeyboardEvent<HTMLElement>) {
-  if (event.defaultPrevented || event.altKey || event.ctrlKey || event.metaKey || isTyping(event.target)) return;
-  const rows = enabledRows(event.currentTarget);
-  if (rows.length === 0) return;
-  const focused = document.activeElement instanceof HTMLElement ? document.activeElement.closest(ROW) : null;
-  const at = focused ? rows.indexOf(focused as HTMLElement) : -1;
-  let next: HTMLElement | undefined;
-  if (event.key === 'ArrowDown') next = rows[(at + 1) % rows.length];
-  else if (event.key === 'ArrowUp') next = rows[at < 0 ? rows.length - 1 : (at - 1 + rows.length) % rows.length];
-  else if (event.key === 'Home') next = rows[0];
-  else if (event.key === 'End') next = rows[rows.length - 1];
-  else if (event.key.length === 1 && event.key.trim()) {
-    // Next row (after the focused one, wrapping) whose text starts with the letter.
-    const letter = event.key.toLowerCase();
-    const ordered = [...rows.slice(at + 1), ...rows.slice(0, at + 1)];
-    next = ordered.find((row) => row.textContent?.trim().toLowerCase().startsWith(letter));
-  }
-  if (!next) return;
-  event.preventDefault();
-  event.stopPropagation();
-  next.focus();
-}
-
-/**
- * Focus the row a menu opens on: the current choice, else the first enabled
- * row. Returns false when there is no row to take focus.
- *
- * @param root - The element holding the rows.
- */
-export function focusMenuRow(root: HTMLElement): boolean {
-  const rows = enabledRows(root);
-  const current = rows.find(
-    (row) =>
-      row.hasAttribute('data-checked') ||
-      row.getAttribute('aria-selected') === 'true' ||
-      (row.getAttribute('role') === 'menuitemradio' && row.getAttribute('aria-checked') === 'true'),
-  );
-  const target = current ?? rows[0];
-  target?.focus({ preventScroll: true });
-  return target !== undefined;
-}
-
-/** Props for {@link Menu}. */
-export interface MenuProps {
-  /** The rows, sections and notes. */
-  children: ReactNode;
-  /** Extra classes on the list element. */
-  className?: string;
-  /**
-   * The list's ARIA role. `menu` and `listbox` handle arrow, Home, End and first-letter keys;
-   * `group` does not. Rows take the matching role (`menuitem` or `option`).
-   * @default 'menu'
-   */
-  role?: 'menu' | 'listbox' | 'group';
-  /** Accessible name of the list. */
-  'aria-label'?: string;
-  /** Inline styles on the root element, merged after the component's own. */
-  style?: CSSProperties;
-}
-
-/**
- * Padding + role for a list of rows inside a floating surface; a `menu` / `listbox` handles the
- * arrow keys.
- *
- * @param props - Component props.
- */
-export function Menu({ children, className = '', role = 'menu', style, ...rest }: MenuProps) {
-  return (
-    <MenuRoleContext.Provider value={role}>
-      <div
-        role={role}
-        className={`flex flex-col p-1 ${className}`}
-        style={style}
-        onKeyDown={role === 'group' ? undefined : handleMenuKeyDown}
-        {...rest}
-      >
-        {children}
-      </div>
-    </MenuRoleContext.Provider>
-  );
-}
-
-/** Props for {@link MenuSwitch}. */
-export interface MenuSwitchProps {
-  /** Whether the switch is on. */
-  on: boolean;
-  /** Extra classes on the root element. */
-  className?: string;
-  /** Inline styles on the root element, merged after the component's own. */
-  style?: CSSProperties;
-}
-
-/**
- * The on/off glyph for an option row or a compact toggle button; the control around it owns the
- * state.
- *
- * @param props - Component props.
- */
-export function MenuSwitch({ on, className, style }: MenuSwitchProps) {
-  return <SwitchGlyph on={on} size="sm" className={className} style={style} />;
-}
-
-/** Props for {@link MenuNote}. */
-export interface MenuNoteProps {
-  /** Icon class shown before the text, such as `i-ph-info`. */
-  icon?: string;
-  /** The note text. */
-  children: ReactNode;
-  /** Extra classes on the note. */
-  className?: string;
-  /** Inline styles on the root element, merged after the component's own. */
-  style?: CSSProperties;
-}
-
-/**
- * A note, hint or empty state inside a menu: sans, muted, row-aligned.
- *
- * @param props - Component props.
- */
-export function MenuNote({ icon, children, className = '', style }: MenuNoteProps) {
-  return (
-    <div
-      className={`flex items-start gap-1.5 px-2 py-1.5 text-zg-meta leading-4 text-[var(--zg-text-muted)] ${className}`}
-      style={style}
-    >
-      {icon && <span aria-hidden className={`${icon} text-zg-label shrink-0 mt-px`} />}
-      <span className="min-w-0 zg-pretty">{children}</span>
-    </div>
-  );
-}
-
-/**
- * Explanations for a compact list: the hovered (or focused) row's text, else
- * `fallback` (the current row's). Spread `bind(text)` on each row and render
- * the returned text in a `MenuNote` under the list.
- *
- * @param fallback - The text shown while no row is hovered or focused, usually the current row's.
- * @returns `hint`, the text to show, and `bind(text)`, which returns the hover and focus handlers
- * to spread on a row.
- */
-export function useRowHint(fallback: string | undefined) {
-  const [hovered, setHovered] = useState<string | null>(null);
-  const bind = (text: string | undefined) => ({
-    onMouseEnter: () => setHovered(text ?? null),
-    onMouseLeave: () => setHovered(null),
-    onFocus: () => setHovered(text ?? null),
-    onBlur: () => setHovered(null),
-  });
-  return { hint: hovered ?? fallback, bind };
-}