@solhun/feedback-kit-core 0.1.0

package/src/uuid.ts

@@ -0,0 +1,54 @@
+// UUID v4 생성기 — 폴리필/의존성 없이 자체 구현.
+//
+// 설계 이유:
+// - crypto.randomUUID는 보안 컨텍스트(https/localhost)에서만 있고, 구형 런타임엔 없다.
+//   표준 API가 없어도 멱등 키(clientSubmissionId)를 만들 수 있어야 한다(TC5).
+// - 따라서 getRandomValues를 우선 쓰고, 그마저 없으면 Math.random으로 폴백한다.
+// - 코어는 globalThis.crypto만 참조(document/window 아님) → 플랫폼 무관 유지.
+
+function pickRandomBytes(): (arr: Uint8Array) => Uint8Array {
+  const g: typeof globalThis =
+    typeof globalThis !== "undefined" ? globalThis : ({} as typeof globalThis);
+  // DOM lib에 의존하지 않으려고 Crypto 전역 타입 대신 필요한 모양만 선언한다.
+  // 코어는 lib.dom 없이도 타입체크가 통과해야 한다(플랫폼 무관 요구사항).
+  const crypto = (g as { crypto?: { getRandomValues?(array: Uint8Array): Uint8Array } }).crypto;
+  const getRandomValues = crypto?.getRandomValues;
+  if (typeof getRandomValues === "function") {
+    // crypto에 바인딩해서 호출한다(구현체가 this를 요구한다).
+    return (arr) => getRandomValues.call(crypto, arr);
+  }
+  // 폴백: Math.random. 멱등 키 용도라 충분한 균등분포.
+  return (arr) => {
+    for (let i = 0; i < arr.length; i++) {
+      arr[i] = Math.floor(Math.random() * 256);
+    }
+    return arr;
+  };
+}
+
+/**
+ * RFC 4122 v4 UUID 문자열을 만든다(8-4-4-4-16).
+ * crypto.getRandomValues가 있으면 그것을, 없으면 Math.random을 쓴다.
+ */
+export function uuidv4(): string {
+  const fill = pickRandomBytes();
+  const b = new Uint8Array(16);
+  fill(b);
+
+  // 버전(4)과 변형(10xx) 비트 고정.
+  b[6] = (b[6] & 0x0f) | 0x40;
+  b[8] = (b[8] & 0x3f) | 0x80;
+
+  const h = Array.from(b, (n) => n.toString(16).padStart(2, "0"));
+  return (
+    h.slice(0, 4).join("") +
+    "-" +
+    h.slice(4, 6).join("") +
+    "-" +
+    h.slice(6, 8).join("") +
+    "-" +
+    h.slice(8, 10).join("") +
+    "-" +
+    h.slice(10, 16).join("")
+  );
+}

package/src/widget/controller.ts

@@ -0,0 +1,224 @@
+// 화면 지도.
+//
+// 위젯이 가질 수 있는 화면은 넷뿐이다: 플로팅 버튼 / 리포트 모달 / 핀 지정 / 요소 지목.
+// 어느 화면에서 어느 화면으로 갈 수 있는지를 여기 한 곳에 모아 둔다 — 흩어지면
+// "취소했는데 이전 좌표가 날아간다" 같은 사고가 화면마다 따로 생긴다.
+
+import type { FeedbackPin } from "../types.js";
+import type { SubmitOutcome } from "../queue.js";
+import {
+  ReportModalController,
+  type ReportModalOpts,
+  type ReportModalState,
+  type WidgetPlatform,
+} from "./modal.js";
+import { PinController, type PixelPoint, type PixelSize } from "./pin.js";
+
+/** 위젯이 보여줄 수 있는 화면. */
+export type WidgetScreen = "button" | "modal" | "pin" | "picking";
+
+export interface WidgetControllerOpts extends ReportModalOpts {
+  /** 저장돼 있던 요소 지목 모드를 복원할 때 쓴다(새로고침·페이지 이동 후). */
+  initialPicking?: boolean;
+  /** 지목 모드가 켜지고 꺼질 때 호출. 호스트가 저장소에 기록한다. */
+  onPickingChange?: (active: boolean) => void;
+}
+
+export interface WidgetState {
+  screen: WidgetScreen;
+  modal: ReportModalState;
+  /** 핀 지정 화면에서 만지는 중인 좌표. */
+  pinDraft: FeedbackPin | null;
+  /** 모달로 돌아간 확정 좌표. */
+  pinConfirmed: FeedbackPin | null;
+  pickingActive: boolean;
+}
+
+export type WidgetListener = (state: WidgetState) => void;
+
+export class WidgetController {
+  readonly modal: ReportModalController;
+  readonly pin: PinController;
+
+  private readonly platform: WidgetPlatform;
+  private readonly onPickingChange: ((active: boolean) => void) | null;
+  private readonly listeners = new Set<WidgetListener>();
+  private readonly unsubscribeModal: () => void;
+
+  private screen: WidgetScreen;
+  private picking: boolean;
+
+  constructor(opts: WidgetControllerOpts) {
+    this.platform = opts.platform;
+    this.onPickingChange = opts.onPickingChange ?? null;
+    this.modal = new ReportModalController(opts);
+    this.pin = new PinController(null);
+    opts.queue.start?.();
+    this.picking = opts.initialPicking ?? false;
+    this.screen = this.picking ? "picking" : "button";
+
+    // 모달이 스스로 닫히는 경로(전송 성공, 큐 자동 배출)도 화면 지도에 반영해야 한다.
+    this.unsubscribeModal = this.modal.subscribe((state) => {
+      // 스크린샷을 제거하거나 모달을 새로 열면 그 이미지에 속했던 확정 핀도 함께 폐기한다.
+      // modal.pin만 비우면 PinController의 confirmed 값이 다음 핀 화면에서 되살아난다.
+      if (state.pin === null && this.pin.confirmed !== null) this.pin.reset();
+      if (!state.open && (this.screen === "modal" || this.screen === "pin")) {
+        this.screen = this.picking ? "picking" : "button";
+      }
+      this.emit();
+    });
+  }
+
+  // ── 조회 ──────────────────────────────────────────────────────────────────
+
+  getScreen(): WidgetScreen {
+    return this.screen;
+  }
+
+  getState(): WidgetState {
+    return {
+      screen: this.screen,
+      modal: this.modal.getState(),
+      pinDraft: this.pin.draft,
+      pinConfirmed: this.pin.confirmed,
+      pickingActive: this.picking,
+    };
+  }
+
+  get isPicking(): boolean {
+    return this.picking;
+  }
+
+  subscribe(listener: WidgetListener): () => void {
+    this.listeners.add(listener);
+    listener(this.getState());
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  dispose(): void {
+    this.unsubscribeModal();
+    this.modal.dispose();
+    this.modal.stopQueue();
+    this.listeners.clear();
+  }
+
+  // ── 플로팅 버튼 ↔ 모달 ────────────────────────────────────────────────────
+
+  async openReport(): Promise<void> {
+    this.screen = "modal";
+    await this.modal.open();
+    this.emit();
+  }
+
+  /** 모달 닫기 요청. 쓰던 내용이 있으면 확인부터 받는다(화면은 그대로 모달). */
+  closeReport(): "closed" | "confirm" {
+    const result = this.modal.requestClose();
+    if (result === "closed") {
+      this.pin.reset();
+      this.screen = this.picking ? "picking" : "button";
+    }
+    this.emit();
+    return result;
+  }
+
+  confirmCloseReport(): void {
+    this.modal.confirmClose();
+    this.pin.reset();
+    this.screen = this.picking ? "picking" : "button";
+    this.emit();
+  }
+
+  cancelCloseReport(): void {
+    this.modal.cancelClose();
+    this.emit();
+  }
+
+  async submitReport(): Promise<SubmitOutcome | null> {
+    const outcome = await this.modal.submit();
+    if (outcome?.delivered) this.pin.reset();
+    this.emit();
+    return outcome;
+  }
+
+  async retryReport(): Promise<void> {
+    await this.modal.retry();
+    this.emit();
+  }
+
+  // ── 핀 지정 ───────────────────────────────────────────────────────────────
+
+  /**
+   * 핀 지정 화면 열기. 스크린샷이 없으면 좌표가 가리킬 대상이 없으므로 열지 않는다.
+   * @returns 열렸으면 true.
+   */
+  openPinScreen(): boolean {
+    if (!this.modal.getState().canPin) return false;
+    this.pin.open();
+    this.screen = "pin";
+    this.emit();
+    return true;
+  }
+
+  /** 핀 지정 화면에서 탭. 기존 핀이 있으면 그 자리로 옮긴다. */
+  placePin(point: PixelPoint, size: PixelSize): FeedbackPin | null {
+    if (this.screen !== "pin") return null;
+    const placed = this.pin.place(point, size);
+    this.emit();
+    return placed;
+  }
+
+  /** 확정 — 모달로 돌아가고 좌표가 제출에 실린다. */
+  confirmPin(): FeedbackPin | null {
+    if (this.screen !== "pin") return this.pin.confirmed;
+    const confirmed = this.pin.confirm();
+    this.modal.setPin(confirmed);
+    this.screen = "modal";
+    this.emit();
+    return confirmed;
+  }
+
+  /** 취소 — 이전 확정 좌표를 그대로 두고 모달로 돌아간다. */
+  cancelPin(): FeedbackPin | null {
+    if (this.screen !== "pin") return this.pin.confirmed;
+    const previous = this.pin.cancel();
+    this.modal.setPin(previous);
+    this.screen = "modal";
+    this.emit();
+    return previous;
+  }
+
+  // ── 요소 지목 (웹 전용) ───────────────────────────────────────────────────
+
+  /**
+   * 요소 지목 모드 시작. 모달에서 넘어오는 흐름이라 닫기 확인을 묻지 않는다
+   * (사용자가 이미 "지목하러 가겠다"고 밝힌 상태다).
+   */
+  startPicking(): boolean {
+    if (this.platform !== "web") return false;
+    this.modal.dismiss();
+    this.setPicking(true);
+    this.screen = "picking";
+    this.emit();
+    return true;
+  }
+
+  /** [지목 종료]. 플로팅 버튼 화면으로 돌아가고 저장된 모드 표시도 지운다. */
+  stopPicking(): void {
+    this.setPicking(false);
+    if (this.screen === "picking") this.screen = "button";
+    this.emit();
+  }
+
+  private setPicking(active: boolean): void {
+    if (this.picking === active) return;
+    this.picking = active;
+    this.onPickingChange?.(active);
+  }
+
+  private emit(): void {
+    const state = this.getState();
+    for (const listener of this.listeners) listener(state);
+  }
+}

package/src/widget/focus.ts

@@ -0,0 +1,66 @@
+// 모달 포커스 순서.
+//
+// DOM 없이도 검증할 수 있도록 "포커스 가능한 것들의 순서"를 문자열 id 목록으로 들고 돈다.
+// 실제 렌더러는 이 id 를 자기 노드에 매달아 두고 focus() 를 걸면 된다.
+
+/** 위젯 플로팅 버튼의 고정 id. 모달을 닫으면 여기로 포커스를 되돌린다. */
+export const FLOATING_BUTTON_ID = "feedback-kit-floating-button";
+
+/**
+ * 순환하는 포커스 링. 끝에서 Tab 하면 처음으로 돌아온다 = 포커스가 모달 밖으로 새지 않는다.
+ */
+export class FocusRing {
+  private items: string[];
+  private index: number;
+
+  constructor(items: readonly string[] = []) {
+    this.items = [...items];
+    this.index = this.items.length > 0 ? 0 : -1;
+  }
+
+  get order(): readonly string[] {
+    return this.items;
+  }
+
+  get current(): string | null {
+    return this.index >= 0 && this.index < this.items.length ? this.items[this.index]! : null;
+  }
+
+  /**
+   * 항목 목록을 바꾼다. 지금 포커스된 항목이 새 목록에도 있으면 그 자리를 유지한다
+   * (스크린샷을 지웠다고 포커스가 처음으로 튀면 키보드 사용자가 길을 잃는다).
+   */
+  setItems(items: readonly string[]): void {
+    const focused = this.current;
+    this.items = [...items];
+    if (this.items.length === 0) {
+      this.index = -1;
+      return;
+    }
+    const keep = focused === null ? -1 : this.items.indexOf(focused);
+    this.index = keep >= 0 ? keep : 0;
+  }
+
+  focus(id: string): boolean {
+    const at = this.items.indexOf(id);
+    if (at < 0) return false;
+    this.index = at;
+    return true;
+  }
+
+  next(): string | null {
+    if (this.items.length === 0) return null;
+    this.index = (this.index + 1) % this.items.length;
+    return this.current;
+  }
+
+  prev(): string | null {
+    if (this.items.length === 0) return null;
+    this.index = (this.index - 1 + this.items.length) % this.items.length;
+    return this.current;
+  }
+
+  contains(id: string): boolean {
+    return this.items.includes(id);
+  }
+}

package/src/widget/index.ts

@@ -0,0 +1,59 @@
+// 위젯 헤드리스 계층 진입점.
+//
+// 여기 있는 것들은 전부 순수 TS다 — DOM 도 React Native API 도 참조하지 않는다.
+// 웹/앱 패키지가 이 상태기계를 자기 렌더러에 얹는다.
+
+export {
+  captureWithinLimit,
+  SCREENSHOT_FAILED_MESSAGE,
+  SCREENSHOT_MAX_BASE64_BYTES,
+  SCREENSHOT_QUALITY_STEPS,
+  screenshotBytes,
+} from "./screenshot.js";
+export type {
+  CaptureWithinLimitOpts,
+  ScreenshotCapture,
+  ScreenshotOutcome,
+  ScreenshotReencode,
+} from "./screenshot.js";
+
+export { denormalizePin, normalizePin, PinController } from "./pin.js";
+export type { PixelPoint, PixelSize } from "./pin.js";
+
+export { FLOATING_BUTTON_ID, FocusRing } from "./focus.js";
+
+export {
+  COMMENT_MAX_CHARS,
+  COMMENT_REQUIRED_MESSAGE,
+  COMMENT_TOO_LONG_MESSAGE,
+  MODAL_ACTION_ATTACH,
+  MODAL_ACTION_CANCEL,
+  MODAL_ACTION_PICK,
+  MODAL_ACTION_PIN,
+  MODAL_ACTION_REMOVE_SCREENSHOT,
+  MODAL_ACTION_RETRY,
+  MODAL_ACTION_SEND,
+  MODAL_FIELD_COMMENT,
+  MODAL_FIELD_PRIORITY,
+  ReportModalController,
+  SUBMIT_DONE_MESSAGE,
+  SUBMIT_FAILED_MESSAGE,
+  SUBMIT_PENDING_MESSAGE,
+} from "./modal.js";
+export type {
+  ModalQueueLike,
+  ModalSubmitStatus,
+  ReportModalListener,
+  ReportModalOpts,
+  ReportModalState,
+  ScreenshotStatus,
+  WidgetPlatform,
+} from "./modal.js";
+
+export { WidgetController } from "./controller.js";
+export type {
+  WidgetControllerOpts,
+  WidgetListener,
+  WidgetScreen,
+  WidgetState,
+} from "./controller.js";