first wokring prototype

src/components/help/FieldLabel.tsx

@@ -0,0 +1,17 @@
+import type { ReactNode } from "react";
+import InlineHelp from "./InlineHelp";
+
+type FieldLabelProps = {
+  children: ReactNode;
+  help?: ReactNode;
+  className?: string;
+};
+
+export default function FieldLabel({ children, help, className = "" }: FieldLabelProps) {
+  return (
+    <span className={`field-label ${className}`.trim()}>
+      <span className="field-label-text">{children}</span>
+      {help && <InlineHelp>{help}</InlineHelp>}
+    </span>
+  );
+}

src/components/help/InlineHelp.tsx

@@ -0,0 +1,186 @@
+import type { CSSProperties, ReactNode } from "react";
+import { useCallback, useEffect, useId, useLayoutEffect, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+
+type InlineHelpProps = {
+  children: ReactNode;
+  className?: string;
+};
+
+type TooltipPosition = {
+  top: number;
+  left: number;
+  arrowLeft: number;
+  placement: "top" | "bottom";
+};
+
+const OPEN_DELAY_MS = 350;
+const VIEWPORT_MARGIN = 12;
+const TRIGGER_GAP = 10;
+
+const tooltipBaseStyle: CSSProperties = {
+  position: "fixed",
+  zIndex: 10000,
+  width: "max-content",
+  maxWidth: "min(320px, calc(100vw - 48px))",
+  border: "1px solid var(--line-dark)",
+  borderRadius: 7,
+  background: "var(--surface)",
+  boxShadow: "var(--shadow-popover)",
+  color: "var(--text)",
+  fontSize: 12,
+  fontWeight: 500,
+  lineHeight: 1.4,
+  padding: "9px 10px",
+  whiteSpace: "normal",
+  pointerEvents: "none"
+};
+
+function clamp(value: number, min: number, max: number) {
+  if (max < min) return min;
+  return Math.min(Math.max(value, min), max);
+}
+
+export default function InlineHelp({ children, className = "" }: InlineHelpProps) {
+  const tooltipId = useId();
+  const triggerRef = useRef<HTMLSpanElement | null>(null);
+  const tooltipRef = useRef<HTMLDivElement | null>(null);
+  const openTimerRef = useRef<number | null>(null);
+  const [isOpen, setIsOpen] = useState(false);
+  const [position, setPosition] = useState<TooltipPosition | null>(null);
+
+  const clearOpenTimer = useCallback(() => {
+    if (openTimerRef.current !== null) {
+      window.clearTimeout(openTimerRef.current);
+      openTimerRef.current = null;
+    }
+  }, []);
+
+  const openWithDelay = useCallback(() => {
+    clearOpenTimer();
+    openTimerRef.current = window.setTimeout(() => {
+      openTimerRef.current = null;
+      setIsOpen(true);
+    }, OPEN_DELAY_MS);
+  }, [clearOpenTimer]);
+
+  const close = useCallback(() => {
+    clearOpenTimer();
+    setIsOpen(false);
+  }, [clearOpenTimer]);
+
+  const updatePosition = useCallback(() => {
+    const trigger = triggerRef.current;
+    const tooltip = tooltipRef.current;
+    if (!trigger || !tooltip) return;
+
+    const triggerRect = trigger.getBoundingClientRect();
+    const tooltipRect = tooltip.getBoundingClientRect();
+    const triggerCenterX = triggerRect.left + triggerRect.width / 2;
+    const preferredLeft = triggerCenterX - tooltipRect.width / 2;
+    const left = clamp(preferredLeft, VIEWPORT_MARGIN, window.innerWidth - tooltipRect.width - VIEWPORT_MARGIN);
+    const topCandidate = triggerRect.top - tooltipRect.height - TRIGGER_GAP;
+    const hasRoomAbove = topCandidate >= VIEWPORT_MARGIN;
+    const bottomCandidate = triggerRect.bottom + TRIGGER_GAP;
+    const top = hasRoomAbove
+      ? topCandidate
+      : clamp(bottomCandidate, VIEWPORT_MARGIN, window.innerHeight - tooltipRect.height - VIEWPORT_MARGIN);
+
+    setPosition({
+      top,
+      left,
+      arrowLeft: clamp(triggerCenterX - left, 12, tooltipRect.width - 12),
+      placement: hasRoomAbove ? "top" : "bottom"
+    });
+  }, []);
+
+  useLayoutEffect(() => {
+    if (!isOpen) {
+      setPosition(null);
+      return;
+    }
+
+    updatePosition();
+    const frame = window.requestAnimationFrame(updatePosition);
+    return () => window.cancelAnimationFrame(frame);
+  }, [isOpen, updatePosition]);
+
+  useEffect(() => {
+    if (!isOpen) return undefined;
+
+    const handleScrollOrResize = () => updatePosition();
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === "Escape") close();
+    };
+
+    window.addEventListener("scroll", handleScrollOrResize, true);
+    window.addEventListener("resize", handleScrollOrResize);
+    window.addEventListener("keydown", handleKeyDown);
+
+    return () => {
+      window.removeEventListener("scroll", handleScrollOrResize, true);
+      window.removeEventListener("resize", handleScrollOrResize);
+      window.removeEventListener("keydown", handleKeyDown);
+    };
+  }, [close, isOpen, updatePosition]);
+
+  useEffect(() => clearOpenTimer, [clearOpenTimer]);
+
+  if (!children) return null;
+
+  const tooltipStyle: CSSProperties = {
+    ...tooltipBaseStyle,
+    top: position?.top ?? -9999,
+    left: position?.left ?? -9999,
+    opacity: position ? 1 : 0
+  };
+
+  const arrowStyle: CSSProperties = position?.placement === "bottom"
+    ? {
+        position: "absolute",
+        left: position.arrowLeft,
+        top: 0,
+        width: 9,
+        height: 9,
+        borderLeft: "1px solid var(--line-dark)",
+        borderTop: "1px solid var(--line-dark)",
+        background: "var(--surface)",
+        transform: "translate(-50%, -5px) rotate(45deg)"
+      }
+    : {
+        position: "absolute",
+        left: position?.arrowLeft ?? 16,
+        top: "100%",
+        width: 9,
+        height: 9,
+        borderRight: "1px solid var(--line-dark)",
+        borderBottom: "1px solid var(--line-dark)",
+        background: "var(--surface)",
+        transform: "translate(-50%, -5px) rotate(45deg)"
+      };
+
+  return (
+    <>
+      <span
+        ref={triggerRef}
+        className={`inline-help ${className}`.trim()}
+        tabIndex={0}
+        aria-label="Show field help"
+        aria-describedby={isOpen ? tooltipId : undefined}
+        onMouseEnter={openWithDelay}
+        onMouseLeave={close}
+        onFocus={openWithDelay}
+        onBlur={close}
+      >
+        <span className="inline-help-mark" aria-hidden="true">?</span>
+      </span>
+      {isOpen && createPortal(
+        <div ref={tooltipRef} id={tooltipId} role="tooltip" style={tooltipStyle}>
+          {children}
+          <span aria-hidden="true" style={arrowStyle} />
+        </div>,
+        document.body
+      )}
+    </>
+  );
+}