zigmini 1.0.0-beta.3 → 1.1.0-beta.1

package/web/tour.js

@@ -0,0 +1,450 @@
+import { getLanguage, onLanguageChange, registerStrings, t } from "./i18n.js";
+import strings from "./i18n/tour.js";
+import { TIP_QUIET_ATTR } from "./tooltip.js";
+
+registerStrings(strings);
+
+// Plan agent-ux todo 23: the first-run tour of the whole app, an interactive walkthrough of seven steps in the
+// operator's order. Each step frames one real element in a hole of a dimmed overlay and the user acts on that element to
+// go on: typing in the composer (nothing is sent), a click on a sidebar row, a header button or "+ 에이전트". Only the
+// 새 세션 step ends with a 다음 button, because the real click would start a new engine session. Esc skips the rest.
+// A target behind a dialog, or the sidebar a phone never shows, is revealed first (dialogs closed, the sidebar opened
+// as a drawer) and the page is put back when the step ends; a target that does not exist is skipped. While the tour
+// runs it marks the body (F3 V2), so the page draws no hover or focus tip over the bubble (web/tooltip.js).
+// The tour starts once per browser (localStorage zgw.tour.done=1, no server record) and again from the settings
+// button 안내 투어 다시 보기.
+// The decisions (progress, done flag, hole and bubble geometry, advance mode) are pure functions below; installTour
+// binds them to the page.
+
+export const TOUR_DONE_KEY = "zgw.tour.done";
+export const TOUR_ID = "zgw-tour";
+export const HOLE_PAD = 6;
+export const BUBBLE_GAP = 12;
+export const BUBBLE_MARGIN = 8;
+
+/**
+ * The steps. `target`: the selector the hole frames (comma-separated selectors frame their union); `advance`: how the
+ * step ends - "input" (the user types in the target), "click" (a click on `hit`, by default the target, after the page
+ * handled it) or "next" (the 다음 button). `drawer`: the sidebar step, which opens the sidebar as a drawer where it is
+ * hidden. `opens`: the dialog the step needs open. `within`: where app.js draws a target that index.html does not hold.
+ */
+export const TOUR_STEPS = Object.freeze([
+	Object.freeze({ id: "input", target: "#input", advance: "input" }),
+	Object.freeze({ id: "sidebar", target: "#conv-list, #agent-group", hit: "#conv-list li, #agent-list li[data-conv]", advance: "click", drawer: true }),
+	Object.freeze({ id: "newSession", target: "#rotate-session", advance: "next" }),
+	Object.freeze({ id: "inbox", target: "#toggle-inbox", advance: "click" }),
+	Object.freeze({ id: "agents", target: "#toggle-agents", advance: "click" }),
+	Object.freeze({ id: "agentCreate", target: "#pe-new", within: "#agents-body", advance: "click", opens: "agents" }),
+	Object.freeze({ id: "settings", target: "#toggle-settings", advance: "click" }),
+]);
+
+/** The dialogs the tour closes to uncover a target, outermost first, each with the control that closes it. */
+export const COVERS = Object.freeze([
+	Object.freeze({ id: "settings", open: "#settings:not([hidden])", close: "#settings-close" }),
+	Object.freeze({ id: "manual", open: "#manual:not([hidden])", close: "#manual-close" }),
+	Object.freeze({ id: "agents", open: "#agents:not([hidden])", close: "#agents-close" }),
+	Object.freeze({ id: "inbox", open: '#toggle-inbox[aria-expanded="true"]', close: "#inbox-close" }),
+	Object.freeze({ id: "status", open: ".app.status-open", close: "#status-back" }),
+]);
+
+export function readTourDone(storage) {
+	return storage.getItem(TOUR_DONE_KEY) === "1";
+}
+
+export function writeTourDone(storage) {
+	storage.setItem(TOUR_DONE_KEY, "1");
+}
+
+/** The tour starts by itself only while this browser has never finished or skipped it. */
+export function autoStartWanted(storage) {
+	return !readTourDone(storage);
+}
+
+export function startState() {
+	return { at: 0, done: false, reason: "running" };
+}
+
+/** "advance" moves to the next step and finishes after the last one; "skip" ends the tour where it is. */
+export function tourTransition(state, action, count = TOUR_STEPS.length) {
+	if (state.done) return state;
+	if (action === "skip") return { at: state.at, done: true, reason: "skipped" };
+	const next = state.at + 1;
+	if (next >= count) return { at: count, done: true, reason: "finished" };
+	return { at: next, done: false, reason: "running" };
+}
+
+export function stepLabel(at, count = TOUR_STEPS.length) {
+	return t("tour.count", { n: at + 1, total: count });
+}
+
+/** A click or input step whose element is missing or disabled (an empty list, an offline composer) falls back to 다음. */
+export function advanceMode(step, hasHit) {
+	return step.advance !== "next" && !hasHit ? "next" : step.advance;
+}
+
+export function hintKey(mode) {
+	return mode === "input" ? "tour.hint.input" : mode === "next" ? "tour.hint.next" : "tour.hint.click";
+}
+
+/**
+ * What a key does while the tour runs. `place` is where the key landed: "shielded" (on the 다음 step's real element),
+ * "input" (in the composer step's textarea), "row" (on an element the tour made focusable for its click) or "other".
+ * "skip" (Esc), "tab" (move inside the focus cycle), "block" (an activation the step must not let through), "activate"
+ * (Enter or Space does the row's click), null (left to the page).
+ */
+export function keyAction(mode, key, place, shift = false) {
+	if (key === "Escape") return "skip";
+	if (key === "Tab") return "tab";
+	const activation = key === "Enter" || key === " " || key === "Spacebar";
+	if (!activation) return null;
+	if (mode === "next" && place === "shielded") return "block";
+	if (mode === "input" && key === "Enter" && !shift && place === "input") return "block";
+	if (mode === "click" && place === "row") return "activate";
+	return null;
+}
+
+/** The next position in the focus cycle: Tab moves forward, Shift+Tab backward, a focus outside the cycle enters at an end. */
+export function cycleIndex(length, at, shift) {
+	if (at < 0) return shift ? length - 1 : 0;
+	return (at + (shift ? length - 1 : 1)) % length;
+}
+
+/** The Korean subject form of the agent's name: 이 after a final consonant, 가 otherwise (and for any other script). */
+export function subjectName(name, lang = getLanguage()) {
+	if (lang !== "ko") return name;
+	const last = name.codePointAt(name.length - 1);
+	const hangul = last >= 0xac00 && last <= 0xd7a3;
+	return `${name}${hangul && (last - 0xac00) % 28 !== 0 ? "이" : "가"}`;
+}
+
+/** The padded union of the target boxes, clamped to the view; null when no target has a size. */
+export function holeBox(rects, view, pad = HOLE_PAD) {
+	const boxes = rects.filter((box) => box.right > box.left && box.bottom > box.top);
+	if (boxes.length === 0) return null;
+	return {
+		left: Math.max(0, Math.min(...boxes.map((box) => box.left)) - pad),
+		top: Math.max(0, Math.min(...boxes.map((box) => box.top)) - pad),
+		right: Math.min(view.width, Math.max(...boxes.map((box) => box.right)) + pad),
+		bottom: Math.min(view.height, Math.max(...boxes.map((box) => box.bottom)) + pad),
+	};
+}
+
+/** The four shade panels around the hole; clicks land only inside the hole. */
+export function shadeRects(hole, view) {
+	return {
+		top: { left: 0, top: 0, right: view.width, bottom: hole.top },
+		bottom: { left: 0, top: hole.bottom, right: view.width, bottom: view.height },
+		left: { left: 0, top: hole.top, right: hole.left, bottom: hole.bottom },
+		right: { left: hole.right, top: hole.top, right: view.width, bottom: hole.bottom },
+	};
+}
+
+/** The bubble sits below the hole, centred and clamped to the view; above when below does not fit. */
+export function placeBubble(hole, size, view) {
+	const left = Math.max(BUBBLE_MARGIN, Math.min((hole.left + hole.right) / 2 - size.width / 2, view.width - size.width - BUBBLE_MARGIN));
+	const below = hole.bottom + BUBBLE_GAP;
+	const above = hole.top - BUBBLE_GAP - size.height;
+	if (below + size.height <= view.height - BUBBLE_MARGIN) return { left, top: below, side: "below" };
+	if (above >= BUBBLE_MARGIN) return { left, top: above, side: "above" };
+	return { left, top: Math.max(BUBBLE_MARGIN, Math.min(below, view.height - size.height - BUBBLE_MARGIN)), side: "below" };
+}
+
+function setBox(el, box) {
+	el.style.left = `${Math.round(box.left)}px`;
+	el.style.top = `${Math.round(box.top)}px`;
+	el.style.width = `${Math.max(0, Math.round(box.right - box.left))}px`;
+	el.style.height = `${Math.max(0, Math.round(box.bottom - box.top))}px`;
+}
+
+function firstSelector(step) {
+	return step.target.split(",")[0].trim();
+}
+
+function visibleBoxes(doc, selector) {
+	return [...doc.querySelectorAll(selector)].map((el) => el.getBoundingClientRect()).filter((box) => box.width > 0 && box.height > 0);
+}
+
+const FOCUSABLE = "button, textarea, input, select, a[href], [tabindex]";
+
+export function installTour(doc, win, storage) {
+	const root = doc.createElement("div");
+	root.id = TOUR_ID;
+	root.className = "tour";
+	root.setAttribute("role", "dialog");
+	root.setAttribute("aria-modal", "true");
+	root.hidden = true;
+	const shades = {};
+	for (const side of ["top", "right", "bottom", "left"]) {
+		const shade = doc.createElement("div");
+		shade.className = "tour-shade";
+		shade.dataset.side = side;
+		shades[side] = shade;
+		root.append(shade);
+	}
+	const shield = doc.createElement("div");
+	shield.className = "tour-shield";
+	const ring = doc.createElement("div");
+	ring.className = "tour-ring";
+	const bubble = doc.createElement("div");
+	bubble.className = "tour-bubble";
+	bubble.tabIndex = -1;
+	const text = doc.createElement("p");
+	text.className = "tour-text";
+	text.id = `${TOUR_ID}-text`;
+	const hint = doc.createElement("p");
+	hint.className = "tour-hint";
+	const foot = doc.createElement("div");
+	foot.className = "tour-foot";
+	const count = doc.createElement("span");
+	count.className = "tour-count";
+	const next = doc.createElement("button");
+	next.type = "button";
+	next.className = "text-btn tour-next";
+	const skip = doc.createElement("button");
+	skip.type = "button";
+	skip.className = "text-btn tour-skip";
+	foot.append(count, next, skip);
+	bubble.append(text, hint, foot);
+	root.setAttribute("aria-labelledby", text.id);
+	root.append(shield, ring, bubble);
+	doc.body.append(root);
+
+	let state = null;
+	let mode = "click";
+	let step = null;
+	let returnFocus = null;
+	let frame = 0;
+
+	const app = () => doc.querySelector(".app");
+	const view = () => ({ width: win.innerWidth, height: win.innerHeight });
+	const agentName = () => doc.querySelector(".agent-name")?.textContent?.trim() || "Zig";
+
+	const covered = (selector) => {
+		const el = doc.querySelector(selector);
+		if (!el) return true;
+		const box = el.getBoundingClientRect();
+		if (box.width === 0 || box.height === 0) return true;
+		const hit = doc.elementFromPoint(Math.min(win.innerWidth - 1, box.left + box.width / 2), Math.min(win.innerHeight - 1, box.top + box.height / 2));
+		return !(hit && (hit === el || el.contains(hit)));
+	};
+
+	const closeCovers = (keep, selector) => {
+		for (const cover of COVERS) {
+			if (cover.id === keep || !covered(selector) || !doc.querySelector(cover.open)) continue;
+			doc.querySelector(cover.close)?.click();
+		}
+	};
+
+	/** Brings the step's target on screen: opens the dialog it needs, closes the ones over it, opens the phone's sidebar drawer. */
+	const reveal = (current) => {
+		root.hidden = true;
+		if (current.opens === "agents") {
+			if (!doc.querySelector("#agents:not([hidden])")) doc.querySelector("#toggle-agents")?.click();
+			if (!doc.querySelector(current.target)) doc.querySelector("#agents-nav-list")?.click();
+		}
+		const first = firstSelector(current);
+		closeCovers(current.opens, first);
+		if (current.drawer && covered(first)) app()?.classList.add("tour-drawer");
+		doc.querySelector(first)?.scrollIntoView?.({ block: "nearest", inline: "nearest" });
+		return !covered(first);
+	};
+
+	const hits = () => (step ? [...doc.querySelectorAll(step.hit ?? step.target)] : []);
+	const shown = (el) => {
+		const box = el.getBoundingClientRect();
+		return box.width > 0 && box.height > 0;
+	};
+
+	/** A click step's rows get a tab stop for the tour's keyboard path; a 다음 step's real element is made inert. */
+	const prepareHits = () => {
+		if (mode === "click") {
+			for (const el of hits()) {
+				if (el.disabled || el.matches(FOCUSABLE)) continue;
+				el.setAttribute("tabindex", "0");
+				el.setAttribute("data-tour-focus", "");
+			}
+		}
+		if (mode === "next") {
+			for (const el of doc.querySelectorAll(step.target)) {
+				if (el.hasAttribute("data-tour-inert")) continue;
+				el.setAttribute("inert", "");
+				el.setAttribute("data-tour-inert", "");
+			}
+		}
+	};
+	const releaseHits = () => {
+		for (const el of doc.querySelectorAll("[data-tour-focus]")) {
+			el.removeAttribute("tabindex");
+			el.removeAttribute("data-tour-focus");
+		}
+		for (const el of doc.querySelectorAll("[data-tour-inert]")) {
+			el.removeAttribute("inert");
+			el.removeAttribute("data-tour-inert");
+		}
+	};
+
+	const restore = () => {
+		app()?.classList.remove("tour-drawer");
+		releaseHits();
+	};
+
+	/** The step's real elements the keyboard can act on, then 다음 (when shown), then 건너뛰기; a shielded element is never in it. */
+	const focusCycle = () => {
+		const list = mode === "next" ? [] : hits().filter((el) => !el.disabled && el.matches(FOCUSABLE) && shown(el));
+		if (!next.hidden) list.push(next);
+		list.push(skip);
+		return list;
+	};
+	const placeOf = (el) => {
+		if (!el) return "other";
+		return mode === "next" && el.closest(step.target) ? "shielded"
+			: mode === "input" && el.matches(step.target) ? "input"
+			: mode === "click" && el.closest("[data-tour-focus]") ? "row"
+			: "other";
+	};
+
+	const hitMode = () => advanceMode(step, [...doc.querySelectorAll(step.hit ?? step.target)].some((el) => !el.disabled));
+	const sentence = () => t(`tour.step.${step.id}`, { name: subjectName(agentName()) });
+
+	/** A step whose element became usable or unusable changes mode: every mark of the old mode goes before the new one is drawn. */
+	const switchMode = (wanted) => {
+		releaseHits();
+		mode = wanted;
+		render();
+		if (!focusCycle().includes(doc.activeElement)) focusCycle()[0].focus({ preventScroll: true });
+	};
+
+	const paint = () => {
+		frame = 0;
+		const wanted = hitMode();
+		if (wanted !== mode) return switchMode(wanted);
+		if (text.textContent !== sentence()) text.textContent = sentence();
+		prepareHits();
+		const hole = holeBox(visibleBoxes(doc, step.target), view());
+		if (!hole) return;
+		const panels = shadeRects(hole, view());
+		for (const side of Object.keys(panels)) setBox(shades[side], panels[side]);
+		setBox(ring, hole);
+		setBox(shield, hole);
+		shield.hidden = mode !== "next";
+		const place = placeBubble(hole, bubble.getBoundingClientRect(), view());
+		bubble.style.left = `${Math.round(place.left)}px`;
+		bubble.style.top = `${Math.round(place.top)}px`;
+		bubble.dataset.side = place.side;
+	};
+	const schedulePaint = () => {
+		if (!step || frame) return;
+		frame = win.requestAnimationFrame(paint);
+	};
+
+	const render = () => {
+		if (!step) return;
+		text.textContent = sentence();
+		hint.textContent = t(hintKey(mode));
+		count.textContent = stepLabel(state.at);
+		next.textContent = t("tour.next");
+		skip.textContent = t("tour.skip");
+		root.setAttribute("aria-label", t("tour.label"));
+		next.hidden = mode !== "next";
+		paint();
+	};
+
+	const finish = () => {
+		if (!state) return;
+		writeTourDone(storage);
+		root.hidden = true;
+		doc.body.removeAttribute(TIP_QUIET_ATTR);
+		step = null;
+		state = null;
+		if (frame) win.cancelAnimationFrame(frame);
+		frame = 0;
+		const back = returnFocus;
+		returnFocus = null;
+		if (back && back !== doc.body && doc.contains(back) && !doc.activeElement?.closest(".settings")) back.focus({ preventScroll: true });
+	};
+
+	const show = () => {
+		for (;;) {
+			if (state.done) return finish();
+			step = TOUR_STEPS[state.at];
+			if (reveal(step)) break;
+			restore();
+			state = tourTransition(state, "advance");
+		}
+		mode = hitMode();
+		root.hidden = false;
+		render();
+		focusCycle()[0].focus({ preventScroll: true });
+	};
+
+	const advance = () => {
+		if (!state || state.done) return;
+		restore();
+		state = tourTransition(state, "advance");
+		show();
+	};
+
+	const start = () => {
+		if (!state) returnFocus = doc.activeElement;
+		restore();
+		state = startState();
+		doc.body.setAttribute(TIP_QUIET_ATTR, "");
+		show();
+	};
+
+	const skipTour = () => {
+		if (!state) return;
+		state = tourTransition(state, "skip");
+		restore();
+		finish();
+	};
+
+	next.addEventListener("click", () => {
+		if (mode === "next") advance();
+	});
+	skip.addEventListener("click", skipTour);
+
+	doc.addEventListener("click", (event) => {
+		if (!state || mode !== "click" || !(event.target instanceof win.Element)) return;
+		if (!event.target.closest(step.hit ?? step.target)) return;
+		win.setTimeout(advance, 0);
+	}, true);
+	doc.addEventListener("input", (event) => {
+		if (!state || mode !== "input" || !(event.target instanceof win.Element) || !event.target.matches(step.target)) return;
+		if (String(event.target.value ?? "").length === 0) return;
+		win.setTimeout(advance, 0);
+	}, true);
+	doc.addEventListener("keydown", (event) => {
+		if (!state) return;
+		const el = event.target instanceof win.Element ? event.target : null;
+		const action = keyAction(mode, event.key, placeOf(el), event.shiftKey);
+		if (action === null) return;
+		event.preventDefault();
+		event.stopPropagation();
+		if (action === "skip") skipTour();
+		else if (action === "activate") el.closest("[data-tour-focus]").click();
+		else if (action === "tab") {
+			const cycle = focusCycle();
+			cycle[cycleIndex(cycle.length, cycle.indexOf(doc.activeElement), event.shiftKey)].focus({ preventScroll: true });
+		}
+	}, true);
+	doc.addEventListener("keyup", (event) => {
+		if (!state || mode !== "next" || !(event.target instanceof win.Element) || !event.target.closest(step.target)) return;
+		if (event.key === "Enter" || event.key === " " || event.key === "Spacebar") {
+			event.preventDefault();
+			event.stopPropagation();
+		}
+	}, true);
+	doc.addEventListener("focusin", (event) => {
+		if (!state || mode !== "next" || !(event.target instanceof win.Element) || !event.target.closest(step.target)) return;
+		next.focus({ preventScroll: true });
+	}, true);
+	win.addEventListener("resize", schedulePaint);
+	win.addEventListener("scroll", schedulePaint, true);
+	new win.MutationObserver((records) => {
+		if (records.some((record) => !root.contains(record.target))) schedulePaint();
+	}).observe(doc.body, { subtree: true, childList: true, attributes: true });
+	onLanguageChange(render);
+
+	return { start, skip: skipTour, active: () => state !== null, step: () => (state ? state.at : -1) };
+}