diff --git a/B09_Estimation/B09_Estimation_UI_Shell.ts b/B09_Estimation/B09_Estimation_UI_Shell.ts index 7147fe004..fbc1cb7a2 100644 --- a/B09_Estimation/B09_Estimation_UI_Shell.ts +++ b/B09_Estimation/B09_Estimation_UI_Shell.ts @@ -20,6 +20,7 @@ import { } from "@ui/ui_template_elements"; import { attachCollapsible } from "@ui/ui_template_collapsible"; import { createDataTable, type DataTable } from "@ui/ui_template_data_table"; +import { attachHoverInfo } from "@ui/ui_template_hover_info"; import { ui_locales, currentLanguageIndex } from "@ui/ui_template_locale"; import { clearState, readState, writeState } from "../A00_Common/b_page_state"; import { workflowSteps } from "../A00_Common/b_page_scaffold"; @@ -227,16 +228,16 @@ export function renderB09Estimation(root: HTMLElement): void { const box = cell.getBoundingClientRect(); openMenuAt(box.left, box.bottom, items); }); - // 157-3 칸 풍선 — 공용 표는 그대로 · 올린 칸에 title + // 157-3 칸 풍선 — 공용 표는 그대로 · 올린 칸에 공용 호버 정보(185-3) if (spec.tip) - made.root.addEventListener("mouseover", (event) => { - const cell = (event.target as Element).closest("tr[data-i] td"); - const row = cell?.parentElement; - const column = cell ? spec.columns[cell.cellIndex] : undefined; - if (!cell || !row || !column) return; - const tip = spec.tip?.(Number(row.dataset.i), column.key); - if (tip) cell.title = tip; - }); + attachHoverInfo( + made.root, + (cell) => { + const column = spec.columns[(cell as HTMLTableCellElement).cellIndex]; + return column && spec.tip?.(Number(cell.parentElement?.dataset.i), column.key); + }, + "tr[data-i] td", + ); return made; }; const hint = spec.hint ? note(spec.hint) : null; diff --git a/resources/tester/test_185_3_hover_info.py b/resources/tester/test_185_3_hover_info.py new file mode 100644 index 000000000..45e900e4c --- /dev/null +++ b/resources/tester/test_185_3_hover_info.py @@ -0,0 +1,187 @@ +"""185-3 공용 호버 정보 양식(`ui_template_hover_info.ts`) — 지연 · 뒤집기 · 초점 · 한 번에 하나 · 토큰. + +Node 로 모듈을 그대로 돌림(작은 가짜 DOM · 타이머 손으로 돌림) · 자리 셈 `placeHoverInfo` 는 함수만. +""" + +import json +import re +import subprocess +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[2] +TS = ROOT / "config" / "node_modules" / "typescript" +MOD = ROOT / "ui_template" / "ui_template_hover_info.ts" +CSS = ROOT / "ui_template" / "ui_template_hover_info.css" + +PRELUDE = f""" +const fs = require("fs"); +const ts = require({json.dumps(str(TS))}); +const js = ts.transpileModule(fs.readFileSync({json.dumps(str(MOD))}, "utf8"), {{ + compilerOptions: {{ module: ts.ModuleKind.CommonJS, target: ts.ScriptTarget.ES2020 }}, +}}).outputText; +class Node {{}} +class Element extends Node {{ + constructor(tag, sel) {{ + super(); this.tag = tag; this.sel = sel; this.parentElement = null; this.children = []; + this.attrs = {{}}; this.on = {{}}; this.style = {{}}; this.hidden = false; this.isConnected = true; + this.offsetWidth = 200; this.offsetHeight = 40; this.textContent = ""; + this.rect = {{ left: 100, top: 100, right: 180, bottom: 120 }}; + const set = new Set(); + this.classList = {{ set, toggle: (c, on) => (on ? set.add(c) : set.delete(c)), contains: (c) => set.has(c) }}; + }} + appendChild(c) {{ c.parentElement = this; this.children.push(c); return c; }} + contains(n) {{ for (let x = n; x; x = x.parentElement) if (x === this) return true; return false; }} + closest(sel) {{ for (let x = this; x; x = x.parentElement) if (x.sel === sel) return x; return null; }} + setAttribute(k, v) {{ this.attrs[k] = String(v); }} + getAttribute(k) {{ return this.attrs[k] ?? null; }} + removeAttribute(k) {{ delete this.attrs[k]; }} + addEventListener(t, f) {{ (this.on[t] ||= []).push(f); }} + removeEventListener(t, f) {{ this.on[t] = (this.on[t] || []).filter((g) => g !== f); }} + getBoundingClientRect() {{ return this.rect; }} + fire(type, extra = {{}}) {{ + const e = {{ type, target: this, ...extra }}; + for (let x = this; x; x = x.parentElement) (x.on[type] || []).forEach((f) => f(e)); + }} +}} +const document = new Element("#document"); +document.body = document.appendChild(new Element("body")); +document.createElement = (t) => new Element(t); +const window = {{ innerWidth: 1000, innerHeight: 800 }}; +let timers = []; +let seq = 0; +const fakeSet = (f, ms) => (timers.push({{ id: ++seq, f, ms }}), seq); +const fakeClear = (id) => (timers = timers.filter((t) => t.id !== id)); +const tick = () => {{ const now = timers; timers = []; now.forEach((t) => t.f()); return now.map((t) => t.ms); }}; +const mod = {{ exports: {{}} }}; +new Function("exports", "module", "require", "document", "window", "Element", "Node", + "setTimeout", "clearTimeout", js)(mod.exports, mod, () => ({{}}), document, window, Element, Node, + fakeSet, fakeClear); +const H = mod.exports; +const box = () => document.body.children.filter((c) => c.attrs.role === "tooltip"); +const out = {{}}; +""" + + +def _node(body: str): + script = PRELUDE + body + "\nconsole.log(JSON.stringify(out));" + got = subprocess.run( + ["node", "-e", script], capture_output=True, text=True, encoding="utf-8", timeout=60 + ) + assert got.returncode == 0, got.stderr + return json.loads(got.stdout) + + +def test_자리_아래가_기본_아래_모자라면_위로_뒤집기_좌우는_화면_안(): + got = _node( + """ +const view = { width: 1000, height: 800 }; +const size = { width: 200, height: 40 }; +const at = (l, t, r, b) => H.placeHoverInfo({ left: l, top: t, right: r, bottom: b }, size, view); +out.below = at(100, 100, 180, 120); +out.bottom = at(100, 760, 180, 780); +out.right = at(950, 100, 990, 120); +out.left = at(-30, 100, 20, 120); +out.tight = at(100, 10, 180, 790); +""" + ) + assert got["below"] == {"x": 100, "y": 126, "above": False} + assert got["bottom"] == {"x": 100, "y": 714, "above": True} # 760 - 6 - 40 + assert got["right"]["x"] == 1000 - 6 - 200 and not got["right"]["above"] + assert got["left"]["x"] == 6 + assert got["tight"]["above"] is False # 위도 모자라면 아래 그대로 + + +def test_마우스_짧은_지연_뒤_뜸_떠나면_닫힘_aria(): + got = _node( + """ +const root = document.body.appendChild(new Element("table")); +const cell = root.appendChild(new Element("td", "td")); +const inner = cell.appendChild(new Element("span")); +H.attachHoverInfo(root, (t) => (t === cell ? "물가정보 · 2026-07 · 670쪽" : null), "td"); +inner.fire("mouseover"); +out.beforeTick = box().length ? !box()[0].hidden : false; +out.delays = tick(); +out.text = box()[0].textContent; +out.shown = !box()[0].hidden; +out.aria = cell.attrs["aria-describedby"] === box()[0].id; +out.pos = [box()[0].style.left, box()[0].style.top]; +inner.fire("mouseout", { relatedTarget: cell }); // 칸 안에서 움직임 = 그대로 +out.stay = !box()[0].hidden; +cell.fire("mouseout", { relatedTarget: root }); +out.gone = box()[0].hidden && !("aria-describedby" in cell.attrs); +""" + ) + assert got["beforeTick"] is False and got["delays"] == [350] + assert got["text"] == "물가정보 · 2026-07 · 670쪽" and got["shown"] and got["aria"] + assert got["pos"] == ["100px", "126px"] + assert got["stay"] and got["gone"] + + +def test_키보드_초점이면_지연_없이_뜸_화면_끝이면_뒤집힘(): + got = _node( + """ +const root = document.body.appendChild(new Element("div")); +const btn = root.appendChild(new Element("button")); +btn.rect = { left: 900, top: 770, right: 990, bottom: 790 }; +H.attachHoverInfo(btn, "단추 설명"); +btn.fire("focusin"); +out.delays = tick(); +const b = box()[0]; +out.text = b.textContent; +out.above = b.classList.contains("is-above"); +out.pos = [b.style.left, b.style.top]; +btn.fire("focusout", { relatedTarget: null }); +out.gone = b.hidden; +""" + ) + assert got["delays"] == [0] and got["text"] == "단추 설명" + assert got["above"] and got["pos"] == ["794px", "724px"] + assert got["gone"] + + +def test_한_번에_하나_빈_글은_안_뜸_Esc_누름_떼기(): + got = _node( + """ +const root = document.body.appendChild(new Element("div")); +const a = root.appendChild(new Element("td", "td")); +const b = root.appendChild(new Element("td", "td")); +const c = root.appendChild(new Element("td", "td")); +const stop = H.attachHoverInfo(root, (t) => (t === a ? "A" : t === b ? "B" : ""), "td"); +a.fire("focusin"); tick(); +b.fire("focusin"); tick(); +out.count = box().length; +out.text = box()[0].textContent; +out.aOff = !("aria-describedby" in a.attrs) && "aria-describedby" in b.attrs; +c.fire("focusin"); tick(); +out.emptyHidden = box()[0].hidden; +a.fire("focusin"); tick(); +document.fire("keydown", { key: "Escape" }); +out.esc = box()[0].hidden; +a.fire("focusin"); tick(); a.fire("focusout", { relatedTarget: null }); +a.fire("mouseover"); tick(); +document.fire("pointerdown"); +out.press = box()[0].hidden; +stop(); +a.fire("mouseover"); +out.afterStop = timers.length; +""" + ) + assert got["count"] == 1 and got["text"] == "B" and got["aOff"] + assert got["emptyHidden"] and got["esc"] and got["press"] + assert got["afterStop"] == 0 + + +def test_모양은_테마_토큰_밝음_어두움_같이_마우스_안_막음(): + css = CSS.read_text(encoding="utf-8") + rule = css[css.index(".ui-hover-info {") :] + assert not re.search(r"#[0-9a-fA-F]{3,8}\b", rule) # 색 글자 박지 않음 + for token in ("--color-surface-raised", "--color-border", "--color-text-body", "--z-toast"): + assert f"var({token})" in rule + assert "pointer-events: none" in rule and "position: fixed" in rule + theme = (ROOT / "ui_template" / "ui_template_theme.css").read_text(encoding="utf-8") + dark = theme[theme.index(':root[data-theme="dark"]') :] + assert "--color-canvas:" in dark and "--color-mist:" in dark # 어두움 = 토큰 바탕이 바뀜 + src = MOD.read_text(encoding="utf-8") + assert ( + 'import "./ui_template_hover_info.css";' in src and 'setAttribute("role", "tooltip")' in src + ) diff --git a/ui_template/ui_template_hover_info.css b/ui_template/ui_template_hover_info.css new file mode 100644 index 000000000..ac71c5d76 --- /dev/null +++ b/ui_template/ui_template_hover_info.css @@ -0,0 +1,25 @@ +/* ============================================================================= + * 호버 정보 상자 공용 모양(`ui_template_hover_info.ts` · PLAN 185-3) — 화면에 하나 · fixed · + * 색 = 테마 토큰(밝음 · 어두움 같이) · 마우스를 안 막음 + * ========================================================================== */ + +.ui-hover-info { + position: fixed; + z-index: var(--z-toast); + max-width: min(320px, calc(100vw - 12px)); + padding: var(--spacing-4) var(--spacing-8); + border: 1px solid var(--color-border); + border-radius: var(--radius-sm); + background: var(--color-surface-raised); + box-shadow: var(--shadow-sm); + color: var(--color-text-body); + font-size: 12px; + line-height: 1.4; + white-space: pre-line; + overflow-wrap: anywhere; + pointer-events: none; +} + +.ui-hover-info[hidden] { + display: none; +} diff --git a/ui_template/ui_template_hover_info.ts b/ui_template/ui_template_hover_info.ts new file mode 100644 index 000000000..8080868ce --- /dev/null +++ b/ui_template/ui_template_hover_info.ts @@ -0,0 +1,135 @@ +/* ============================================================================= + * 호버 정보 — 프로그램 전역 공용 「마우스를 올리면 짧은 추가 정보」 상자(PLAN 185-3) + * + * attachHoverInfo(root, text, selector?) — root 안 selector 에 맞는 것(없으면 root 자신)에 + * 마우스(짧은 지연) · 키보드 초점(바로)이 오면 상자 · 떠나면 · 누름 · Esc · 스크롤이면 닫힘 · 돌려준 함수 = 떼기 + * text = 글 하나 또는 (대상) → 글(빈 값 = 안 띄움) · 표 칸 · 단추 어디나 같은 한 벌 + * 상자 = 화면에 하나(새로 뜨면 앞 것 갈음) · 대상 아래가 기본 · 아래가 모자라면 위로 뒤집고 + * 좌우는 화면 안으로 당김(`placeHoverInfo`) · 색 = 테마 토큰(밝음 · 어두움 같이) + * 옛 title 풍선은 그대로 둠 — 새 자리부터 이 양식(B09 칸 풍선 `tip` 이 첫 사용처) + * ========================================================================== */ + +import "./ui_template_hover_info.css"; + +export type HoverText = string | ((target: HTMLElement) => string | null | undefined); + +/** 뜨기까지 지연(ms) — 지나가는 마우스엔 안 뜸 */ +export const HOVER_DELAY_MS = 350; +/** 대상과 상자 사이 · 화면 끝 여백(px) */ +const GAP = 6; + +interface Box { + left: number; + top: number; + right: number; + bottom: number; +} + +/** 상자 자리 — 대상 아래(왼쪽 맞춤)가 기본 · 아래가 모자라고 위가 넉넉하면 위로 · 좌우 화면 안 */ +export function placeHoverInfo( + anchor: Box, + size: { width: number; height: number }, + view: { width: number; height: number }, +): { x: number; y: number; above: boolean } { + const below = anchor.bottom + GAP; + const above = below + size.height > view.height - GAP && anchor.top - GAP - size.height >= GAP; + const y = above ? anchor.top - GAP - size.height : below; + const x = Math.max(GAP, Math.min(anchor.left, view.width - GAP - size.width)); + return { x, y, above }; +} + +let box: HTMLDivElement | null = null; +let owner: HTMLElement | null = null; +let timer: ReturnType | null = null; +/** 지연 중인 대상 — 같은 대상 안에서 움직여도 지연을 새로 안 셈 */ +let pending: HTMLElement | null = null; +let globalBound = false; + +function shared(): HTMLDivElement { + if (box?.isConnected) return box; + box = document.createElement("div"); + box.className = "ui-hover-info"; + box.id = "ui-hover-info"; + box.setAttribute("role", "tooltip"); + box.hidden = true; + document.body.appendChild(box); + return box; +} + +/** 떠 있는 상자를 닫음(대상이 주면 그 대상 것만) */ +export function hideHoverInfo(target?: HTMLElement): void { + if (target && target !== owner) return; + if (timer) clearTimeout(timer); + timer = null; + pending = null; + owner?.removeAttribute("aria-describedby"); + owner = null; + if (box) box.hidden = true; +} + +function show(target: HTMLElement, text: string): void { + const el = shared(); + owner?.removeAttribute("aria-describedby"); + owner = target; + el.textContent = text; + el.hidden = false; + const r = target.getBoundingClientRect(); + const at = placeHoverInfo( + r, + { width: el.offsetWidth, height: el.offsetHeight }, + { width: window.innerWidth, height: window.innerHeight }, + ); + el.style.left = `${at.x}px`; + el.style.top = `${at.y}px`; + el.classList.toggle("is-above", at.above); + target.setAttribute("aria-describedby", el.id); +} + +function bindGlobal(): void { + if (globalBound) return; + globalBound = true; + document.addEventListener("keydown", (e) => e.key === "Escape" && hideHoverInfo()); + // 누름 = 닫음(누름 뒤 다시 그려져 대상이 사라져도 상자가 안 남음) + document.addEventListener("pointerdown", () => hideHoverInfo(), true); + document.addEventListener("scroll", () => hideHoverInfo(), true); +} + +export function attachHoverInfo(root: HTMLElement, text: HoverText, selector?: string): () => void { + bindGlobal(); + const find = (node: EventTarget | null): HTMLElement | null => { + if (!(node instanceof Element)) return null; + const hit = selector ? node.closest(selector) : root; + return hit && root.contains(hit) ? hit : null; + }; + const enter = (event: Event, delay: number): void => { + const target = find(event.target); + if (!target || target === owner || (timer && target === pending)) return; + if (timer) clearTimeout(timer); + pending = target; + timer = setTimeout(() => { + timer = null; + const value = typeof text === "function" ? text(target) : text; + if (value) show(target, value); + else hideHoverInfo(); + }, delay); + }; + const leave = (event: Event): void => { + const target = find(event.target); + const next = (event as MouseEvent | FocusEvent).relatedTarget; + if (!target || (next instanceof Node && target.contains(next))) return; + if (target === owner || target === pending) hideHoverInfo(); + }; + const over = (e: Event): void => enter(e, HOVER_DELAY_MS); + const focus = (e: Event): void => enter(e, 0); + root.addEventListener("mouseover", over); + root.addEventListener("mouseout", leave); + root.addEventListener("focusin", focus); + root.addEventListener("focusout", leave); + return () => { + root.removeEventListener("mouseover", over); + root.removeEventListener("mouseout", leave); + root.removeEventListener("focusin", focus); + root.removeEventListener("focusout", leave); + if (owner && root.contains(owner)) hideHoverInfo(); + }; +}