AgentHub/client/src/components/Select.tsx

/**
 * @file Select.tsx
 * @description Generic styled dropdown that replaces native `<select>` elements
 * for consistent cross-platform rendering. Native macOS/Chromium selects reserve
 * checkmark space inconsistently; this control aligns labels, flips above the
 * trigger when viewport space is tight, and marks the chosen option with accent
 * color plus a Lucide check.
 *
 * ## Accessibility — WAI-ARIA "listbox button"
 * The trigger is a `<button aria-haspopup="listbox" aria-expanded>`; opening it
 * moves focus to a `role="listbox"` popup that tracks the highlighted
 * `role="option"` through `aria-activedescendant`. Keys: ArrowUp/Down, Home/End,
 * Enter/Space pick, Escape cancels, Tab closes, and a typed character jumps to
 * the next option whose label starts with it. Focus returns to the trigger on
 * every close except Tab.
 *
 * ## Consumers
 * Used on the Run Claude page and webhook settings form wherever a compact
 * enum picker is needed.
 *
 * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
 */
/* =============================================================================
 * MODULE_GUIDE — extended in-file reference (comments only; safe to read, never executed)
 * =============================================================================
 * **Purpose:** Dashboard module consumed by the React client, MCP tools, or desktop shell depending on deployment mode.
 *
 * ## Design constraints
 * - Local-first: no telemetry leaves the machine unless the user configures webhooks.
 * - Fail-safe hooks path on the server must never block Claude Code; UI mirrors that
 *   philosophy by degrading gracefully (empty states, stale badges, reconnect loops).
 * - Destructive flows stay behind explicit confirmation modals and server-side gates.
 * - Internationalization: user-visible strings belong in i18n JSON, not literals here.
 *
 * ## Remote data & SSH
 * Remote Data Sources let operators aggregate multiple machines. SSH entries describe
 * how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
 * scoped GET via `?sources=`. Health checks and import history surface in Settings.
 *
 * ## Public surface
 * - `SelectOption` — exported API; see TSDoc on the symbol for behavior.
 * - `SelectProps` — exported API; see TSDoc on the symbol for behavior.
 * - `Select` — exported API; see TSDoc on the symbol for behavior.
 *
 * ## Testing pointers
 * - Prefer colocated `__tests__` with Vitest + Testing Library for UI.
 * - Server contract changes require `npm run test:server` and OpenAPI sync.
 *
 * ## Related docs
 * - `ARCHITECTURE.md` — hooks → API → SQLite → WebSocket → UI pipeline.
 * - `docs/API.md` — REST reference.
 * - `skills/file-headers/` — mandatory `@author` header policy.
 * ============================================================================= */
/* -----------------------------------------------------------------------------
 * EXPORT CATALOG — quick index of symbols defined below (documentation only).
 * -----------------------------------------------------------------------------
 * **SelectOption**
 *   Part of this module's public contract. Downstream imports should treat
 *   the signature and return type as stable unless release notes say otherwise.
 *   When behavior changes, update the `@file` overview and relevant tests.
 *
 * **SelectProps**
 *   Part of this module's public contract. Downstream imports should treat
 *   the signature and return type as stable unless release notes say otherwise.
 *   When behavior changes, update the `@file` overview and relevant tests.
 *
 * **Select**
 *   Part of this module's public contract. Downstream imports should treat
 *   the signature and return type as stable unless release notes say otherwise.
 *   When behavior changes, update the `@file` overview and relevant tests.
 *
 * ----------------------------------------------------------------------------- */

import { useEffect, useId, useRef, useState, type ReactNode } from "react";
import { ChevronDown, Check } from "lucide-react";

/** Single option in a {@link Select} list. */
export interface SelectOption<T extends string> {
  /** Stored value emitted via `onChange`. */
  value: T;
  /** Primary label shown in the trigger and list. */
  label: string;
  /** Optional secondary line (smaller gray text). */
  hint?: string;
  /** Optional leading icon, shown in the trigger and the list. */
  icon?: ReactNode;
  /** Draw a rule above this option: it starts a group of its own. */
  divider?: boolean;
}

/** Props for {@link Select}. */
export interface SelectProps<T extends string> {
  /** Currently selected value. */
  value: T;
  /** Called when the user picks a new option. */
  onChange: (v: T) => void;
  /** All choices; must be non-empty for sensible rendering. */
  options: SelectOption<T>[];
  /** Disables opening the list. */
  disabled?: boolean;
  /** `ghost`: a borderless, content-wide trigger for a composer's toolbar. */
  variant?: "field" | "ghost";
  /** Accessible name and tooltip of the trigger (a ghost one has no label). */
  label?: string;
}

/**
 * Accessible custom select control.
 * @typeParam T - string union of allowed option values.
 */
export function Select<T extends string>({
  value,
  onChange,
  options,
  disabled,
  variant = "field",
  label,
}: SelectProps<T>) {
  const ghost = variant === "ghost";
  const [open, setOpen] = useState(false);
  const [active, setActive] = useState(0);
  const [openUp, setOpenUp] = useState(false);
  const containerRef = useRef<HTMLDivElement | null>(null);
  const buttonRef = useRef<HTMLButtonElement | null>(null);
  const listRef = useRef<HTMLDivElement | null>(null);
  const typed = useRef({ text: "", at: 0 });
  const id = useId();
  const optionId = (idx: number) => `${id}-opt-${idx}`;

  useEffect(() => {
    if (!open) return;
    const onClick = (e: MouseEvent) => {
      if (!containerRef.current) return;
      if (!containerRef.current.contains(e.target as Node)) setOpen(false);
    };
    document.addEventListener("mousedown", onClick);
    return () => document.removeEventListener("mousedown", onClick);
  }, [open]);

  // On open: highlight the chosen option, decide whether the popover goes
  // above the trigger (288 px = `max-h-72`), and move focus into the list.
  useEffect(() => {
    if (!open) return;
    const idx = options.findIndex((o) => o.value === value);
    setActive(idx >= 0 ? idx : 0);
    if (buttonRef.current) {
      const rect = buttonRef.current.getBoundingClientRect();
      const below = window.innerHeight - rect.bottom;
      setOpenUp(below < 288 && rect.top > below);
    }
    listRef.current?.focus({ preventScroll: true });
    // eslint-disable-next-line react-hooks/exhaustive-deps -- only on open
  }, [open]);

  useEffect(() => {
    if (open) document.getElementById(optionId(active))?.scrollIntoView?.({ block: "nearest" });
    // eslint-disable-next-line react-hooks/exhaustive-deps -- id is stable
  }, [open, active]);

  const close = (refocus = true) => {
    setOpen(false);
    if (refocus) buttonRef.current?.focus();
  };

  const choose = (opt: SelectOption<T>) => {
    onChange(opt.value);
    close();
  };

  const onButtonKey = (e: React.KeyboardEvent<HTMLButtonElement>) => {
    if (["ArrowDown", "ArrowUp", "Enter", " "].includes(e.key)) {
      e.preventDefault();
      setOpen(true);
    }
  };

  const onListKey = (e: React.KeyboardEvent<HTMLDivElement>) => {
    const last = options.length - 1;
    const move: Record<string, (a: number) => number> = {
      ArrowDown: (a) => Math.min(last, a + 1),
      ArrowUp: (a) => Math.max(0, a - 1),
      Home: () => 0,
      End: () => last,
      PageDown: (a) => Math.min(last, a + 10),
      PageUp: (a) => Math.max(0, a - 10),
    };
    if (move[e.key]) {
      e.preventDefault();
      setActive(move[e.key]!);
    } else if (e.key === "Enter" || e.key === " ") {
      e.preventDefault();
      const opt = options[active];
      if (opt) choose(opt);
    } else if (e.key === "Escape") {
      // Stop here: a Select inside a dialog must not close the dialog too.
      e.preventDefault();
      e.stopPropagation();
      close();
    } else if (e.key === "Tab") {
      close(false);
    } else if (e.key.length === 1 && !e.ctrlKey && !e.metaKey && !e.altKey) {
      // Type-ahead: keys typed within 500 ms build one prefix; a repeated single
      // character cycles through the options that start with it.
      const now = Date.now();
      const t = typed.current;
      t.text = now - t.at > 500 ? e.key.toLowerCase() : t.text + e.key.toLowerCase();
      t.at = now;
      const cycling = t.text.length > 1 && [...t.text].every((c) => c === t.text[0]);
      const prefix = cycling ? t.text[0]! : t.text;
      const start = cycling || t.text.length === 1 ? active + 1 : active;
      for (let i = 0; i < options.length; i++) {
        const idx = (start + i) % options.length;
        if (options[idx]!.label.toLowerCase().startsWith(prefix)) {
          setActive(idx);
          break;
        }
      }
    }
  };

  const current = options.find((o) => o.value === value) || options[0];

  return (
    <div ref={containerRef} className={ghost ? "relative inline-block max-w-[11rem]" : "relative"}>
      <button
        ref={buttonRef}
        type="button"
        disabled={disabled}
        aria-label={label}
        aria-haspopup="listbox"
        aria-expanded={open}
        aria-controls={open ? `${id}-list` : undefined}
        title={label}
        onClick={() => (open ? close() : setOpen(true))}
        onKeyDown={onButtonKey}
        className={
          ghost
            ? "flex max-w-full items-center gap-1.5 rounded-md px-2 py-1 text-xs text-fg-secondary hover:bg-surface-3 hover:text-fg-primary focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/60 transition-colors disabled:opacity-60 disabled:cursor-not-allowed"
            : "w-full flex items-center justify-between gap-2 bg-surface-2 border border-border rounded-md px-3 py-1.5 text-[11px] text-fg-primary focus:outline-none focus:border-accent focus-visible:ring-2 focus-visible:ring-accent/40 hover:bg-surface-3 transition-colors disabled:opacity-60 disabled:cursor-not-allowed"
        }
      >
        <span className="flex min-w-0 items-center gap-2">
          {current?.icon}
          <span className="truncate">{current?.label ?? "-"}</span>
        </span>
        <ChevronDown className="w-3.5 h-3.5 text-fg-muted flex-shrink-0" aria-hidden />
      </button>
      {open && (
        <div
          ref={listRef}
          id={`${id}-list`}
          role="listbox"
          tabIndex={-1}
          aria-label={label}
          aria-activedescendant={options[active] ? optionId(active) : undefined}
          onKeyDown={onListKey}
          onBlur={(e) => {
            if (!containerRef.current?.contains(e.relatedTarget as Node | null)) setOpen(false);
          }}
          className={`absolute z-30 left-0 ${ghost ? "w-max min-w-[12rem] max-w-[20rem]" : "right-0"} rounded-md border border-border bg-surface-1 shadow-lg shadow-black/40 max-h-72 overflow-auto py-1 outline-none ${
            openUp ? "bottom-full mb-1" : "top-full mt-1"
          }`}
        >
          {options.map((opt, idx) => {
            const isSelected = opt.value === value;
            const isActive = idx === active;
            return (
              <div
                key={opt.value || "__default__"}
                id={optionId(idx)}
                role="option"
                aria-selected={isSelected}
                onMouseDown={(e) => e.preventDefault()}
                onClick={() => choose(opt)}
                onMouseEnter={() => setActive(idx)}
                className={`w-full cursor-pointer text-left px-3 py-1.5 transition-colors ${
                  opt.divider ? "mt-1 border-t border-border pt-2" : ""
                } ${
                  isActive ? "bg-accent/15" : isSelected ? "bg-surface-3" : "hover:bg-surface-3"
                }`}
              >
                <div className="flex items-center gap-2">
                  {opt.icon}
                  <span
                    className={`text-[11px] flex-1 truncate ${
                      isSelected ? "text-accent font-medium" : "text-fg-secondary"
                    }`}
                  >
                    {opt.label}
                  </span>
                  {isSelected && (
                    <Check className="w-3 h-3 text-accent flex-shrink-0" aria-hidden />
                  )}
                </div>
                {opt.hint && (
                  <div className="text-[10px] text-fg-muted truncate mt-0.5">{opt.hint}</div>
                )}
              </div>
            );
          })}
        </div>
      )}
    </div>
  );
}