@solhun/feedback-kit-web 0.1.0

package/src/picking.ts

@@ -0,0 +1,370 @@
+// 요소 지목 모드 (웹 전용).
+//
+// 켜져 있는 동안 페이지의 아무 요소나 클릭하면 그 자리에 주석을 남긴다. 리포트 모달과 달리
+// "열고 → 쓰고 → 닫는" 절차가 없다 — 한 번 켜 두고 여러 곳을 연달아 지목하는 게 이 모드의 전부다.
+// 그래서 주석을 저장해도 모드는 꺼지지 않고, 페이지를 옮겨도 살아남는다.
+//
+// 페이지의 원래 클릭(링크 이동·버튼 동작)은 막아야 한다. 지목하려고 누른 링크가 실제로 이동해
+// 버리면 주석을 달 화면이 사라진다.
+
+import {
+  COMMENT_MAX_CHARS,
+  normalizePin,
+  type ElementInfo,
+  type FeedbackPin,
+  type FeedbackReport,
+  type ReportParts,
+  type QueueStatus,
+  type SubmitOutcome,
+} from "@solhun/feedback-kit-core";
+import { describeElement } from "./element-info.js";
+import { MarkerStore, type StoredMarker } from "./marker-store.js";
+
+/** 위젯 자신의 UI 를 표시하는 속성. 이 안쪽 클릭은 가로채지 않는다. */
+export const OWN_UI_ATTR = "data-feedback-kit";
+
+/** 지목 컨트롤러가 큐에게 요구하는 최소 계약. */
+export interface PickingQueueLike {
+  submit(report: FeedbackReport): Promise<SubmitOutcome>;
+  subscribe?(listener: (status: QueueStatus) => void): () => void;
+  getOutcome?(clientSubmissionId: string): Pick<SubmitOutcome, "delivered" | "id"> | null;
+}
+
+export interface AnnotationPopupState {
+  element: ElementInfo | null;
+  /** 클릭한 지점의 뷰포트 상대 좌표(0~1). */
+  point: FeedbackPin;
+  comment: string;
+  canSave: boolean;
+}
+
+export interface PickingState {
+  active: boolean;
+  /** 지금 마우스가 올라가 있는 요소. 하이라이트를 그리는 근거. */
+  hovered: ElementInfo | null;
+  popup: AnnotationPopupState | null;
+  /** 현재 경로에 남아 있는 마커들. */
+  markers: readonly StoredMarker[];
+}
+
+export type PickingListener = (state: PickingState) => void;
+
+export interface ElementPickingOpts {
+  queue: PickingQueueLike;
+  createReport: (parts: ReportParts) => Promise<FeedbackReport>;
+  store?: MarkerStore;
+  /** 현재 경로. 마커는 경로별로 나눠 저장한다. */
+  getPathname?: () => string;
+  /** 이벤트를 들을 문서. 기본은 전역 `document`. */
+  doc?: Document | null;
+  /** 좌표를 정규화할 기준 크기. 기본은 현재 뷰포트. */
+  getViewport?: () => { width: number; height: number };
+}
+
+function defaultDocument(): Document | null {
+  return (globalThis as { document?: Document }).document ?? null;
+}
+
+function defaultPathname(): string {
+  const loc = (globalThis as { location?: { pathname?: string } }).location;
+  return loc?.pathname ?? "/";
+}
+
+function defaultViewport(): { width: number; height: number } {
+  const w = globalThis as { innerWidth?: number; innerHeight?: number };
+  return { width: w.innerWidth ?? 0, height: w.innerHeight ?? 0 };
+}
+
+/** 위젯 자신의 UI 안에서 일어난 일인가. */
+function isOwnUi(target: EventTarget | null): boolean {
+  const el = target as Element | null;
+  if (!el || typeof el.closest !== "function") return false;
+  return el.closest(`[${OWN_UI_ATTR}]`) !== null;
+}
+
+export class ElementPickingController {
+  private readonly queue: PickingQueueLike;
+  private readonly createReport: (parts: ReportParts) => Promise<FeedbackReport>;
+  private readonly store: MarkerStore;
+  private readonly getPathname: () => string;
+  private readonly doc: Document | null;
+  private readonly getViewport: () => { width: number; height: number };
+  private readonly unsubscribeQueue: () => void;
+
+  private readonly listeners = new Set<PickingListener>();
+
+  private active = false;
+  private attached = false;
+  private hovered: ElementInfo | null = null;
+  private popup: AnnotationPopupState | null = null;
+  private markers: StoredMarker[] = [];
+  private pathWatch: ReturnType<typeof setInterval> | null = null;
+  private lastPathname: string;
+  private saving = false;
+
+  private readonly onClick = (event: Event) => this.handleClick(event);
+  private readonly onMouseOver = (event: Event) => this.handleMouseOver(event);
+
+  constructor(opts: ElementPickingOpts) {
+    this.queue = opts.queue;
+    this.createReport = opts.createReport;
+    this.store = opts.store ?? new MarkerStore();
+    this.getPathname = opts.getPathname ?? defaultPathname;
+    this.doc = opts.doc === undefined ? defaultDocument() : opts.doc;
+    this.getViewport = opts.getViewport ?? defaultViewport;
+    this.lastPathname = this.getPathname();
+    this.markers = this.store.list(this.lastPathname);
+    this.unsubscribeQueue =
+      this.queue.subscribe?.(() => {
+        if (this.reconcileMarkerOutcomes()) this.emit();
+      }) ?? (() => undefined);
+  }
+
+  // ── 조회 ──────────────────────────────────────────────────────────────────
+
+  getState(): PickingState {
+    return {
+      active: this.active,
+      hovered: this.hovered,
+      popup: this.popup,
+      markers: this.markers,
+    };
+  }
+
+  get isActive(): boolean {
+    return this.active;
+  }
+
+  subscribe(listener: PickingListener): () => void {
+    this.listeners.add(listener);
+    listener(this.getState());
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  // ── 모드 on/off ───────────────────────────────────────────────────────────
+
+  start(): void {
+    if (this.active) return;
+    this.active = true;
+    this.store.setPickingActive(true);
+    this.attach();
+    this.startPathWatch();
+    this.markers = this.store.list(this.getPathname());
+    this.emit();
+  }
+
+  /** [지목 종료]. 저장된 플래그까지 지워서 새로고침해도 다시 켜지지 않게 한다. */
+  stop(): void {
+    this.active = false;
+    this.store.setPickingActive(false);
+    this.detach();
+    this.stopPathWatch();
+    this.hovered = null;
+    this.popup = null;
+    this.emit();
+  }
+
+  /**
+   * 저장돼 있던 모드를 되살린다. 새로고침·페이지 이동 직후에 한 번 부른다.
+   * @returns 되살아났으면 true.
+   */
+  restore(): boolean {
+    if (!this.store.isPickingActive()) {
+      this.markers = this.store.list(this.getPathname());
+      this.emit();
+      return false;
+    }
+    this.start();
+    return true;
+  }
+
+  /** 경로가 바뀌었을 때 그 경로의 마커로 갈아 끼운다. */
+  syncPath(): readonly StoredMarker[] {
+    this.lastPathname = this.getPathname();
+    this.markers = this.store.list(this.lastPathname);
+    this.reconcileMarkerOutcomes();
+    this.popup = null;
+    this.hovered = null;
+    this.emit();
+    return this.markers;
+  }
+
+  dispose(): void {
+    this.detach();
+    this.stopPathWatch();
+    this.unsubscribeQueue();
+    this.listeners.clear();
+  }
+
+  // ── DOM 이벤트 ────────────────────────────────────────────────────────────
+
+  private attach(): void {
+    if (this.attached || !this.doc) return;
+    // 캡처 단계에서 잡아야 페이지의 핸들러보다 먼저 막을 수 있다.
+    this.doc.addEventListener("click", this.onClick, true);
+    this.doc.addEventListener("mouseover", this.onMouseOver, true);
+    this.attached = true;
+  }
+
+  private detach(): void {
+    if (!this.attached || !this.doc) return;
+    this.doc.removeEventListener("click", this.onClick, true);
+    this.doc.removeEventListener("mouseover", this.onMouseOver, true);
+    this.attached = false;
+  }
+
+  private handleMouseOver(event: Event): void {
+    if (!this.active || isOwnUi(event.target)) return;
+    this.hovered = describeElement(event.target as Element | null);
+    this.emit();
+  }
+
+  private handleClick(event: Event): void {
+    if (!this.active) return;
+    if (isOwnUi(event.target)) return;
+
+    // 페이지가 이 클릭을 보지 못하게 한다 — 링크 이동·버튼 동작을 전부 막는다.
+    event.preventDefault();
+    event.stopPropagation();
+    if (typeof event.stopImmediatePropagation === "function") {
+      event.stopImmediatePropagation();
+    }
+
+    const mouse = event as MouseEvent;
+    this.openAnnotation(event.target as Element | null, {
+      x: mouse.clientX ?? 0,
+      y: mouse.clientY ?? 0,
+    });
+  }
+
+  // ── 주석 팝업 ─────────────────────────────────────────────────────────────
+
+  /** 클릭 지점 기준으로 주석 팝업을 연다. 좌표는 해상도 무관한 상대값으로 접어 둔다. */
+  openAnnotation(element: Element | null, clientPoint: { x: number; y: number }): void {
+    const point = normalizePin(clientPoint, this.getViewport());
+    this.popup = {
+      element: describeElement(element),
+      point,
+      comment: "",
+      canSave: false,
+    };
+    this.emit();
+  }
+
+  setAnnotationComment(value: string): void {
+    if (!this.popup) return;
+    this.popup = {
+      ...this.popup,
+      comment: value,
+      canSave: value.trim().length > 0 && value.length <= COMMENT_MAX_CHARS,
+    };
+    this.emit();
+  }
+
+  /** 취소 — 마커도 제보도 남기지 않는다. 모드는 켜진 채로 둔다. */
+  cancelAnnotation(): void {
+    this.popup = null;
+    this.emit();
+  }
+
+  /**
+   * 주석 저장. 마커를 먼저 "전송 중"으로 찍고 나서 보낸다 — 사용자는 결과를 기다리지 않고
+   * 다음 요소로 넘어갈 수 있어야 한다.
+   *
+   * @returns 검증에 걸려 아무것도 하지 않았으면 `null`.
+   */
+  async saveAnnotation(): Promise<SubmitOutcome | null> {
+    const popup = this.popup;
+    if (!popup || !popup.canSave || this.saving) return null;
+    this.saving = true;
+
+    const pathname = this.getPathname();
+    const parts: ReportParts = {
+      kind: "annotation",
+      comment: popup.comment,
+      priority: "unset",
+      screenshot: null,
+      pin: popup.point,
+      element: popup.element,
+    };
+
+    let report: FeedbackReport;
+    try {
+      report = await this.createReport(parts);
+    } catch {
+      // 조립이 실패하면 남길 마커의 id 도 없다. 팝업만 닫고 조용히 물러난다.
+      this.popup = null;
+      this.emit();
+      this.saving = false;
+      return null;
+    }
+
+    const marker: StoredMarker = {
+      id: report.clientSubmissionId,
+      x: popup.point.x,
+      y: popup.point.y,
+      selector: popup.element?.selector ?? null,
+      comment: popup.comment,
+      status: "sending",
+      at: report.createdAt,
+    };
+    this.markers = this.store.upsert(pathname, marker);
+    this.popup = null; // 모드는 그대로 — 다음 요소를 바로 지목할 수 있다.
+    this.emit();
+
+    let outcome: SubmitOutcome;
+    try {
+      outcome = await this.queue.submit(report);
+    } catch {
+      outcome = { delivered: false, id: null, queued: true };
+    }
+
+    const next = this.store.updateStatus(
+      pathname,
+      marker.id,
+      outcome.delivered ? "done" : "pending",
+    );
+    // 저장 중에 경로가 바뀌었으면 화면에 보이는 목록은 건드리지 않는다.
+    if (pathname === this.getPathname()) this.markers = next;
+    this.emit();
+
+    this.saving = false;
+    return outcome;
+  }
+
+  private startPathWatch(): void {
+    if (this.pathWatch !== null || typeof setInterval !== "function") return;
+    this.lastPathname = this.getPathname();
+    this.pathWatch = setInterval(() => {
+      const pathname = this.getPathname();
+      if (pathname !== this.lastPathname) this.syncPath();
+    }, 200);
+  }
+
+  private stopPathWatch(): void {
+    if (this.pathWatch === null) return;
+    clearInterval(this.pathWatch);
+    this.pathWatch = null;
+  }
+
+  /** 전역 pending 수가 아니라 마커와 같은 clientSubmissionId의 확정 성공만 완료로 바꾼다. */
+  private reconcileMarkerOutcomes(): boolean {
+    if (!this.queue.getOutcome) return false;
+    let changed = false;
+    for (const marker of this.markers) {
+      const outcome = this.queue.getOutcome(marker.id);
+      if (marker.status !== "done" && outcome?.delivered) {
+        this.markers = this.store.updateStatus(this.lastPathname, marker.id, "done");
+        changed = true;
+      }
+    }
+    return changed;
+  }
+
+  private emit(): void {
+    const state = this.getState();
+    for (const listener of this.listeners) listener(state);
+  }
+}

package/src/providers.ts

@@ -0,0 +1,43 @@
+// 웹 기본 컨텍스트 제공자.
+//
+// 왜 패키지가 주나: `getUrl` 을 호스트가 깜빡하면 제보의 url 이 빈 문자열로 나가고,
+// 수집 서버는 그걸 400 으로 거절한다. 400 은 재시도 불가라 **제보가 조용히 버려진다.**
+// 실제로 e-fm 첫 배선에서 이 일이 났다 — 화면에는 "보내지 못했습니다"만 뜨고,
+// 원인(빈 url)은 네트워크를 까 봐야 알 수 있었다.
+//
+// 기본값을 패키지가 쥐고 있으면 붙이는 쪽이 잊을 수 없다. 필요하면 덮어쓰면 된다.
+
+import type { ContextProviders, WebContextInput } from "@solhun/feedback-kit-core";
+
+/**
+ * 브라우저 전역에서 뽑을 수 있는 기본 제공자들.
+ *
+ * SSR·비브라우저에서 불려도 던지지 않는다(`null` 을 돌려준다) — 위젯이 마운트되기 전
+ * 서버 렌더 단계에서 실행될 수 있기 때문이다.
+ */
+export function webContextProviders(): ContextProviders {
+  return {
+    getUrl: () => {
+      const loc = (globalThis as { location?: { href?: string } }).location;
+      return typeof loc?.href === "string" && loc.href.length > 0 ? loc.href : null;
+    },
+    getWebContext: (): WebContextInput | null => {
+      const g = globalThis as {
+        location?: unknown;
+        navigator?: { userAgent?: string };
+        innerWidth?: number;
+        innerHeight?: number;
+        devicePixelRatio?: number;
+      };
+      if (!g.location) return null;
+      return {
+        userAgent: g.navigator?.userAgent ?? null,
+        viewport: {
+          width: typeof g.innerWidth === "number" ? g.innerWidth : null,
+          height: typeof g.innerHeight === "number" ? g.innerHeight : null,
+          devicePixelRatio: typeof g.devicePixelRatio === "number" ? g.devicePixelRatio : null,
+        },
+      };
+    },
+  };
+}