@solhun/feedback-kit-web 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,229 @@
+import { ElementInfo, FeedbackPin, FeedbackReport, SubmitOutcome, QueueStatus, ReportParts, ScreenshotCapture, ScreenshotReencode, WidgetControllerOpts, WidgetController, FeedbackStorage, ContextProviders } from '@solhun/feedback-kit-core';
+export { COMMENT_MAX_CHARS, COMMENT_REQUIRED_MESSAGE, COMMENT_TOO_LONG_MESSAGE, ElementInfo, FLOATING_BUTTON_ID, FeedbackAdapter, FeedbackConfig, FeedbackContext, FeedbackPin, FeedbackReport, FeedbackStorage, FeedbackUser, MODAL_ACTION_PICK, ModalSubmitStatus, ReportModalController, ReportModalState, ResolvedConfig, SCREENSHOT_FAILED_MESSAGE, SOURCE_ATTR, SUBMIT_DONE_MESSAGE, SUBMIT_PENDING_MESSAGE, ScreenshotStatus, SubmitResult, Visibility, VisibilityEnv, VisibilityFn, WidgetController, WidgetPosition, WidgetScreen, WidgetState, denormalizePin, normalizePin, parseSourceAttr, resolveConfig, shouldShowWidget, sourceFromElement } from '@solhun/feedback-kit-core';
+import * as react from 'react';
+
+/** 요소 텍스트를 담을 때의 상한. 본문 전체가 실려 페이로드가 붓는 걸 막는다. */
+declare const ELEMENT_TEXT_MAX_CHARS = 200;
+/** 선택자 경로를 몇 단계까지 거슬러 올라갈지. 너무 깊으면 오히려 잘 깨진다. */
+declare const SELECTOR_MAX_DEPTH = 8;
+/**
+ * 요소까지의 CSS 선택자 경로.
+ *
+ * id 를 만나면 거기서 멈춘다 — 문서에서 유일하다고 가정할 수 있는 지점이라 그 위는 군더더기다.
+ * 클래스는 쓰지 않는다: 유틸리티 클래스(`px-4` 같은 것)가 섞이면 선택자가 길기만 하고
+ * 재현성은 오히려 떨어진다.
+ */
+declare function cssSelectorPath(el: Element | null | undefined): string | null;
+/** 눈에 보이는 텍스트를 한 줄로 눌러 담는다. */
+declare function visibleText(el: Element): string | null;
+/** 지목된 요소를 `ElementInfo` 로 옮긴다. 실패해도 던지지 않는다. */
+declare function describeElement(el: Element | null | undefined): ElementInfo | null;
+
+/** 지목 모드 on/off 플래그. */
+declare const PICKING_MODE_KEY = "feedback-kit:picking-mode";
+/** 경로별 마커 목록. 실제 키는 여기에 pathname 을 이어 붙인다. */
+declare const MARKER_KEY_PREFIX = "feedback-kit:markers:";
+/** 한 경로에 남겨 둘 마커 상한. 넘으면 오래된 것부터 버린다. */
+declare const MAX_MARKERS_PER_PATH = 50;
+/** 마커에 보이는 전송 상태. `sending` → `done`, 실패하면 `pending`. */
+type MarkerStatus = "sending" | "done" | "pending";
+interface StoredMarker {
+    /** 제보의 `clientSubmissionId` 와 같다 — 전송 상태를 되짚어 갱신하려고 맞춰 둔다. */
+    id: string;
+    /** 뷰포트 기준 상대 좌표(0~1). 해상도가 달라도 같은 지점을 가리킨다. */
+    x: number;
+    y: number;
+    selector: string | null;
+    comment: string;
+    status: MarkerStatus;
+    /** 생성 시각(ISO). 상한을 넘겼을 때 무엇을 버릴지 정하는 기준. */
+    at: string;
+}
+/** `localStorage` 가 만족하는 최소 계약. 테스트에서 갈아 끼운다. */
+interface StorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/**
+ * 저장소 접근을 한 곳으로 모은다.
+ *
+ * 저장소가 없거나(SSR) 던지는 환경(프라이빗 모드·용량 초과)에서도 위젯이 죽으면 안 되므로
+ * 모든 접근을 try/catch 로 감싸고 실패는 조용히 흘린다. 저장 실패는 "마커가 안 남는다" 정도의
+ * 불편이지 제보 자체를 막을 이유가 아니다.
+ */
+declare class MarkerStore {
+    private readonly storage;
+    constructor(storage?: StorageLike | null);
+    private read;
+    private write;
+    private drop;
+    isPickingActive(): boolean;
+    setPickingActive(active: boolean): void;
+    list(pathname: string): StoredMarker[];
+    /** 같은 id 가 있으면 덮어쓰고, 없으면 뒤에 붙인다. */
+    upsert(pathname: string, marker: StoredMarker): StoredMarker[];
+    /** 전송 상태만 바꾼다. 없는 id 면 아무것도 하지 않는다. */
+    updateStatus(pathname: string, id: string, status: MarkerStatus): StoredMarker[];
+    clear(pathname: string): void;
+}
+
+/** 위젯 자신의 UI 를 표시하는 속성. 이 안쪽 클릭은 가로채지 않는다. */
+declare const OWN_UI_ATTR = "data-feedback-kit";
+/** 지목 컨트롤러가 큐에게 요구하는 최소 계약. */
+interface PickingQueueLike {
+    submit(report: FeedbackReport): Promise<SubmitOutcome>;
+    subscribe?(listener: (status: QueueStatus) => void): () => void;
+    getOutcome?(clientSubmissionId: string): Pick<SubmitOutcome, "delivered" | "id"> | null;
+}
+interface AnnotationPopupState {
+    element: ElementInfo | null;
+    /** 클릭한 지점의 뷰포트 상대 좌표(0~1). */
+    point: FeedbackPin;
+    comment: string;
+    canSave: boolean;
+}
+interface PickingState {
+    active: boolean;
+    /** 지금 마우스가 올라가 있는 요소. 하이라이트를 그리는 근거. */
+    hovered: ElementInfo | null;
+    popup: AnnotationPopupState | null;
+    /** 현재 경로에 남아 있는 마커들. */
+    markers: readonly StoredMarker[];
+}
+type PickingListener = (state: PickingState) => void;
+interface ElementPickingOpts {
+    queue: PickingQueueLike;
+    createReport: (parts: ReportParts) => Promise<FeedbackReport>;
+    store?: MarkerStore;
+    /** 현재 경로. 마커는 경로별로 나눠 저장한다. */
+    getPathname?: () => string;
+    /** 이벤트를 들을 문서. 기본은 전역 `document`. */
+    doc?: Document | null;
+    /** 좌표를 정규화할 기준 크기. 기본은 현재 뷰포트. */
+    getViewport?: () => {
+        width: number;
+        height: number;
+    };
+}
+declare class ElementPickingController {
+    private readonly queue;
+    private readonly createReport;
+    private readonly store;
+    private readonly getPathname;
+    private readonly doc;
+    private readonly getViewport;
+    private readonly unsubscribeQueue;
+    private readonly listeners;
+    private active;
+    private attached;
+    private hovered;
+    private popup;
+    private markers;
+    private pathWatch;
+    private lastPathname;
+    private saving;
+    private readonly onClick;
+    private readonly onMouseOver;
+    constructor(opts: ElementPickingOpts);
+    getState(): PickingState;
+    get isActive(): boolean;
+    subscribe(listener: PickingListener): () => void;
+    start(): void;
+    /** [지목 종료]. 저장된 플래그까지 지워서 새로고침해도 다시 켜지지 않게 한다. */
+    stop(): void;
+    /**
+     * 저장돼 있던 모드를 되살린다. 새로고침·페이지 이동 직후에 한 번 부른다.
+     * @returns 되살아났으면 true.
+     */
+    restore(): boolean;
+    /** 경로가 바뀌었을 때 그 경로의 마커로 갈아 끼운다. */
+    syncPath(): readonly StoredMarker[];
+    dispose(): void;
+    private attach;
+    private detach;
+    private handleMouseOver;
+    private handleClick;
+    /** 클릭 지점 기준으로 주석 팝업을 연다. 좌표는 해상도 무관한 상대값으로 접어 둔다. */
+    openAnnotation(element: Element | null, clientPoint: {
+        x: number;
+        y: number;
+    }): void;
+    setAnnotationComment(value: string): void;
+    /** 취소 — 마커도 제보도 남기지 않는다. 모드는 켜진 채로 둔다. */
+    cancelAnnotation(): void;
+    /**
+     * 주석 저장. 마커를 먼저 "전송 중"으로 찍고 나서 보낸다 — 사용자는 결과를 기다리지 않고
+     * 다음 요소로 넘어갈 수 있어야 한다.
+     *
+     * @returns 검증에 걸려 아무것도 하지 않았으면 `null`.
+     */
+    saveAnnotation(): Promise<SubmitOutcome | null>;
+    private startPathWatch;
+    private stopPathWatch;
+    /** 전역 pending 수가 아니라 마커와 같은 clientSubmissionId의 확정 성공만 완료로 바꾼다. */
+    private reconcileMarkerOutcomes;
+    private emit;
+}
+
+/** 캡처에서 빼야 할 노드인가(위젯 자신의 UI). 결과에 자기 모달이 찍히면 안 된다. */
+declare function isOwnUi(node: Element): boolean;
+/**
+ * 웹 기본 캡처 — 현재 viewport 를 JPEG 로.
+ *
+ * 실패하면 **null 을 돌려준다**(던지지 않는다). 코어가 "캡처 실패" 상태로 바꾸고
+ * 사용자는 파일로 첨부할 수 있다 — 그림 때문에 제보 자체를 잃지 않는다.
+ */
+declare const captureWebScreenshot: ScreenshotCapture;
+/** 8 MiB 정책이 요구할 때 기존 이미지를 JPEG 품질 단계로 다시 인코딩한다. */
+declare const reencodeWebScreenshot: ScreenshotReencode;
+
+interface WebWidgetOpts extends Omit<WidgetControllerOpts, "platform" | "initialPicking" | "onPickingChange"> {
+    /** 지목 모드 플래그와 마커를 담아 둘 저장소. 기본은 `localStorage`. */
+    store?: MarkerStore;
+    /** 현재 경로. 마커를 경로별로 나눠 담는 기준. */
+    getPathname?: () => string;
+    /** 지목 이벤트를 들을 문서. 기본은 전역 `document`. */
+    doc?: Document | null;
+    getViewport?: () => {
+        width: number;
+        height: number;
+    };
+}
+interface WebWidget {
+    widget: WidgetController;
+    picking: ElementPickingController;
+    store: MarkerStore;
+    dispose(): void;
+}
+declare function createWebWidget(opts: WebWidgetOpts): WebWidget;
+
+type FeedbackKitProps = WebWidgetOpts;
+/**
+ * `createWebWidget`의 헤드리스 상태를 실제 DOM으로 그리는 공개 React 진입점.
+ * 큐·제보 조립·스크린샷 캡처는 모두 props로 주입된 기존 계약을 그대로 사용한다.
+ */
+declare function FeedbackKit(props: FeedbackKitProps): react.JSX.Element;
+
+interface SyncStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/**
+ * 웹 기본 FeedbackStorage.
+ *
+ * 쓰기가 쿼터를 넘기면 그대로 던진다 — 큐가 그 신호를 받아 스크린샷을 떼어내고
+ * 본문만 남기는 축소 경로를 타기 때문에, 여기서 삼키면 안 된다.
+ */
+declare function createWebStorage(backing?: SyncStorage): FeedbackStorage;
+
+/**
+ * 브라우저 전역에서 뽑을 수 있는 기본 제공자들.
+ *
+ * SSR·비브라우저에서 불려도 던지지 않는다(`null` 을 돌려준다) — 위젯이 마운트되기 전
+ * 서버 렌더 단계에서 실행될 수 있기 때문이다.
+ */
+declare function webContextProviders(): ContextProviders;
+
+export { type AnnotationPopupState, ELEMENT_TEXT_MAX_CHARS, ElementPickingController, type ElementPickingOpts, FeedbackKit, type FeedbackKitProps, MARKER_KEY_PREFIX, MAX_MARKERS_PER_PATH, type MarkerStatus, MarkerStore, OWN_UI_ATTR, PICKING_MODE_KEY, type PickingListener, type PickingQueueLike, type PickingState, SELECTOR_MAX_DEPTH, type StorageLike, type StoredMarker, type WebWidget, type WebWidgetOpts, captureWebScreenshot, createWebStorage, createWebWidget, cssSelectorPath, describeElement, isOwnUi, reencodeWebScreenshot, visibleText, webContextProviders };