/** * @file FieldHelp.tsx * @description Contextual "(?)" help trigger for dense settings forms. Opens a * rich popover with title, description, optional example chips, and an optional * footnote — all portaled to `` and repositioned on scroll/resize so the * panel never clips inside scrolling cards. * * ## Interaction model * Opens on hover, focus, or click (toggle). Escape dismisses. The popover uses * `pointer-events-none` so moving the pointer toward it does not accidentally * close the trigger's hover state mid-read. * * @author Nguyễn Ngọc Trí Vĩ */ /* ============================================================================= * 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 * - `FieldHelpProps` — exported API; see TSDoc on the symbol for behavior. * - `FieldHelp` — 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. * - MCP edits: `npm run mcp:typecheck` and `npm run mcp:build`. * * ## Related docs * - `ARCHITECTURE.md` — hooks → API → SQLite → WebSocket → UI pipeline. * - `docs/API.md` — REST reference. * - `.claude/skills/file-headers/` — mandatory `@author` header policy. * ============================================================================= */ /* ----------------------------------------------------------------------------- * EXPORT CATALOG — quick index of symbols defined below (documentation only). * ----------------------------------------------------------------------------- * **FieldHelpProps** * 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. * * **FieldHelp** * 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 { useCallback, useEffect, useRef, useState } from "react"; import { createPortal } from "react-dom"; import { useTranslation } from "react-i18next"; import { HelpCircle } from "lucide-react"; /** Props for {@link FieldHelp}. */ export interface FieldHelpProps { /** Optional bold heading inside the popover. */ title?: string; /** Main explanatory copy. */ description: string; /** Short example values rendered as monospace chips. */ examples?: string[]; /** Secondary note shown below examples. */ note?: string; } /** * Inline help control for form fields. * @param props See {@link FieldHelpProps}. */ export function FieldHelp({ title, description, examples, note }: FieldHelpProps) { const { t } = useTranslation("common"); const [open, setOpen] = useState(false); const btnRef = useRef(null); const popRef = useRef(null); const [pos, setPos] = useState<{ left: number; top: number }>({ left: 0, top: 0 }); const place = useCallback(() => { const btn = btnRef.current; const pop = popRef.current; if (!btn) return; const r = btn.getBoundingClientRect(); const w = pop?.offsetWidth ?? 300; const h = pop?.offsetHeight ?? 120; const pad = 10; let left = r.left + r.width / 2 - w / 2; if (left < pad) left = pad; if (left + w > window.innerWidth - pad) left = window.innerWidth - w - pad; let top = r.bottom + 8; if (top + h > window.innerHeight - pad) top = r.top - h - 8; // flip up setPos({ left, top }); }, []); useEffect(() => { if (!open) return; place(); const onScroll = () => place(); window.addEventListener("scroll", onScroll, true); window.addEventListener("resize", onScroll); const onKey = (e: KeyboardEvent) => e.key === "Escape" && setOpen(false); document.addEventListener("keydown", onKey); return () => { window.removeEventListener("scroll", onScroll, true); window.removeEventListener("resize", onScroll); document.removeEventListener("keydown", onKey); }; }, [open, place]); return ( {open && createPortal( , document.body )} ); }