@solhun/feedback-kit-web 0.3.0 → 0.4.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { ElementInfo, FeedbackPin, FeedbackReport, SubmitOutcome, QueueStatus, ReportParts, ScreenshotCapture, ScreenshotReencode, WidgetControllerOpts, WidgetController, FeedbackStorage, ContextProviders } from '@solhun/feedback-kit-core';
+import { ElementInfo, FeedbackPin, FeedbackScreenshot, 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';
 
@@ -76,12 +76,26 @@ interface PickingQueueLike {
     subscribe?(listener: (status: QueueStatus) => void): () => void;
     getOutcome?(clientSubmissionId: string): Pick<SubmitOutcome, "delivered" | "id"> | null;
 }
+/** 퀵 주석의 스크린샷 상태. 모달과 같은 어휘를 쓴다(렌더러가 둘을 같은 방식으로 그린다). */
+type AnnotationShotStatus = "none" | "capturing" | "ready" | "failed";
 interface AnnotationPopupState {
     element: ElementInfo | null;
     /** 클릭한 지점의 뷰포트 상대 좌표(0~1). */
     point: FeedbackPin;
     comment: string;
     canSave: boolean;
+    /**
+     * 이 주석에 실려 갈 그림. 클릭 직후 자동 캡처가 채우고, 사용자가 붙여넣기(Cmd+V)나
+     * 드래그로 덮을 수 있다.
+     *
+     * 왜 퀵 주석에도 그림을 싣나: 이게 없으면 **들어온 문에 따라 정보량이 달라진다.**
+     * 지목으로 남긴 제보만 화면 증거가 비는 일이 실제로 있었고(0.2.0), 그때 얻은 규칙이
+     * "같은 제보는 어느 문으로 들어와도 같은 것을 담는다" 다.
+     */
+    screenshot: FeedbackScreenshot | null;
+    screenshotStatus: AnnotationShotStatus;
+    /** 저장 중인가. 두 번 눌러 같은 주석이 두 번 가는 것을 막는다. */
+    saving: boolean;
 }
 interface PickingState {
     active: boolean;
@@ -106,8 +120,17 @@ interface ElementPickingOpts {
         height: number;
     };
     /**
-     * 요소를 고르면 호출된다. 주면 **인라인 팝업 대신 이걸 부른다** —
-     * 호스트가 리포트 모달을 열어 스크린샷·우선순위까지 받게 하기 위해서다.
+     * 퀵 주석에 붙일 자동 캡처. 없으면 그림 없이 코멘트만 받는다.
+     * 웹 기본 캡처는 위젯 자신의 UI 를 결과에서 빼므로(`ignoreElements`) 팝업이 찍히지 않는다.
+     */
+    capture?: ScreenshotCapture | null;
+    reencode?: ScreenshotReencode | null;
+    screenshotLimitBytes?: number;
+    /**
+     * 요소를 고르면 호출된다. 주면 **퀵 주석 팝업 대신 이걸 부른다** —
+     * 호스트가 전체 리포트 모달을 열어 우선순위까지 받고 싶을 때의 탈출구다.
+     * 기본값은 팝업이다: 지목은 "클릭 → 한 줄 → Enter" 로 끝나는 게 목적이라,
+     * 매번 중앙 모달이 뜨면 흐름이 끊긴다.
      *
      * 모드는 켜진 채로 둔다. 한 번 켜고 여러 요소를 연달아 지목하는 게 이 모드의 목적이라,
      * 요소 하나 고를 때마다 모드가 꺼지면 매번 다시 켜야 한다.
@@ -122,6 +145,9 @@ declare class ElementPickingController {
     private readonly getPathname;
     private readonly doc;
     private readonly getViewport;
+    private readonly capture;
+    private readonly reencode;
+    private readonly screenshotLimitBytes;
     private readonly unsubscribeQueue;
     private readonly listeners;
     private active;
@@ -132,6 +158,10 @@ declare class ElementPickingController {
     private pathWatch;
     private lastPathname;
     private saving;
+    /** 늦게 끝난 캡처가 다음 주석의 그림을 덮지 못하게 하는 세대 번호. */
+    private shotGeneration;
+    /** 지금 도는 자동 캡처. Enter 가 캡처보다 빨랐을 때 기다릴 대상. */
+    private capturing;
     private readonly onClick;
     private readonly onMouseOver;
     constructor(opts: ElementPickingOpts);
@@ -159,8 +189,21 @@ declare class ElementPickingController {
         y: number;
     }): void;
     setAnnotationComment(value: string): void;
+    /**
+     * 사용자가 붙여넣기(Cmd+V)나 드래그로 넣은 그림. 자동 캡처 결과를 덮는다.
+     *
+     * 자동 캡처보다 이게 우선인 이유: 사용자가 굳이 그림을 붙였다면 그건 "지금 화면"이
+     * 아니라 **보여주고 싶은 다른 것**이다(잘라낸 부분, 다른 탭, 기대하는 디자인).
+     */
+    attachAnnotationImage(shot: FeedbackScreenshot): Promise<void>;
+    /** 그림만 뗀다. 코멘트는 그대로 — 그림이 없어도 주석은 성립한다. */
+    removeAnnotationImage(): void;
     /** 취소 — 마커도 제보도 남기지 않는다. 모드는 켜진 채로 둔다. */
     cancelAnnotation(): void;
+    private isSavable;
+    /** 도는 캡처가 있으면 끝나기를 기다린다. 캡처가 던져도 저장을 막지 않는다. */
+    private settleCapture;
+    private runCapture;
     /**
      * 제출된 제보를 마커로 남긴다. 모달 경로에서 쓴다 — 마커 생성이 팝업 저장 안에만
      * 있으면, 리포트 모달로 보낸 지목 제보는 화면에 흔적이 남지 않는다("보냈는지 알 수
@@ -202,6 +245,16 @@ declare function reactComponentPath(node: Element, limit?: number): string[];
 /** 제보 본문에 실을 한 줄. 컴포넌트를 못 찾으면 null(빈 줄을 만들지 않는다). */
 declare function reactComponentSummary(node: Element): string | null;
 
+/**
+ * 요소를 고른 뒤 무엇을 띄우는가.
+ *
+ * - `popup`(기본): 클릭한 자리에 **한 줄 입력창**. Enter 로 바로 보낸다.
+ * - `modal`: 화면 중앙의 전체 리포트 모달(우선순위까지 고른다).
+ *
+ * 기본이 팝업인 이유: 지목은 "여기 이거요" 를 여러 곳에 연달아 남기는 작업이다.
+ * 클릭마다 중앙 모달이 뜨면 시선이 클릭 지점을 떠나고, 어디를 가리켰는지 잊는다.
+ */
+type PickTarget = "popup" | "modal";
 interface WebWidgetOpts extends Omit<WidgetControllerOpts, "platform" | "initialPicking" | "onPickingChange"> {
     /** 지목 모드 플래그와 마커를 담아 둘 저장소. 기본은 `localStorage`. */
     store?: MarkerStore;
@@ -213,6 +266,8 @@ interface WebWidgetOpts extends Omit<WidgetControllerOpts, "platform" | "initial
         width: number;
         height: number;
     };
+    /** 요소를 고른 뒤 띄울 UI. 기본은 `popup`. */
+    pickTarget?: PickTarget;
 }
 interface WebWidget {
     widget: WidgetController;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ElementInfo, FeedbackPin, FeedbackReport, SubmitOutcome, QueueStatus, ReportParts, ScreenshotCapture, ScreenshotReencode, WidgetControllerOpts, WidgetController, FeedbackStorage, ContextProviders } from '@solhun/feedback-kit-core';
+import { ElementInfo, FeedbackPin, FeedbackScreenshot, 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';
 
@@ -76,12 +76,26 @@ interface PickingQueueLike {
     subscribe?(listener: (status: QueueStatus) => void): () => void;
     getOutcome?(clientSubmissionId: string): Pick<SubmitOutcome, "delivered" | "id"> | null;
 }
+/** 퀵 주석의 스크린샷 상태. 모달과 같은 어휘를 쓴다(렌더러가 둘을 같은 방식으로 그린다). */
+type AnnotationShotStatus = "none" | "capturing" | "ready" | "failed";
 interface AnnotationPopupState {
     element: ElementInfo | null;
     /** 클릭한 지점의 뷰포트 상대 좌표(0~1). */
     point: FeedbackPin;
     comment: string;
     canSave: boolean;
+    /**
+     * 이 주석에 실려 갈 그림. 클릭 직후 자동 캡처가 채우고, 사용자가 붙여넣기(Cmd+V)나
+     * 드래그로 덮을 수 있다.
+     *
+     * 왜 퀵 주석에도 그림을 싣나: 이게 없으면 **들어온 문에 따라 정보량이 달라진다.**
+     * 지목으로 남긴 제보만 화면 증거가 비는 일이 실제로 있었고(0.2.0), 그때 얻은 규칙이
+     * "같은 제보는 어느 문으로 들어와도 같은 것을 담는다" 다.
+     */
+    screenshot: FeedbackScreenshot | null;
+    screenshotStatus: AnnotationShotStatus;
+    /** 저장 중인가. 두 번 눌러 같은 주석이 두 번 가는 것을 막는다. */
+    saving: boolean;
 }
 interface PickingState {
     active: boolean;
@@ -106,8 +120,17 @@ interface ElementPickingOpts {
         height: number;
     };
     /**
-     * 요소를 고르면 호출된다. 주면 **인라인 팝업 대신 이걸 부른다** —
-     * 호스트가 리포트 모달을 열어 스크린샷·우선순위까지 받게 하기 위해서다.
+     * 퀵 주석에 붙일 자동 캡처. 없으면 그림 없이 코멘트만 받는다.
+     * 웹 기본 캡처는 위젯 자신의 UI 를 결과에서 빼므로(`ignoreElements`) 팝업이 찍히지 않는다.
+     */
+    capture?: ScreenshotCapture | null;
+    reencode?: ScreenshotReencode | null;
+    screenshotLimitBytes?: number;
+    /**
+     * 요소를 고르면 호출된다. 주면 **퀵 주석 팝업 대신 이걸 부른다** —
+     * 호스트가 전체 리포트 모달을 열어 우선순위까지 받고 싶을 때의 탈출구다.
+     * 기본값은 팝업이다: 지목은 "클릭 → 한 줄 → Enter" 로 끝나는 게 목적이라,
+     * 매번 중앙 모달이 뜨면 흐름이 끊긴다.
      *
      * 모드는 켜진 채로 둔다. 한 번 켜고 여러 요소를 연달아 지목하는 게 이 모드의 목적이라,
      * 요소 하나 고를 때마다 모드가 꺼지면 매번 다시 켜야 한다.
@@ -122,6 +145,9 @@ declare class ElementPickingController {
     private readonly getPathname;
     private readonly doc;
     private readonly getViewport;
+    private readonly capture;
+    private readonly reencode;
+    private readonly screenshotLimitBytes;
     private readonly unsubscribeQueue;
     private readonly listeners;
     private active;
@@ -132,6 +158,10 @@ declare class ElementPickingController {
     private pathWatch;
     private lastPathname;
     private saving;
+    /** 늦게 끝난 캡처가 다음 주석의 그림을 덮지 못하게 하는 세대 번호. */
+    private shotGeneration;
+    /** 지금 도는 자동 캡처. Enter 가 캡처보다 빨랐을 때 기다릴 대상. */
+    private capturing;
     private readonly onClick;
     private readonly onMouseOver;
     constructor(opts: ElementPickingOpts);
@@ -159,8 +189,21 @@ declare class ElementPickingController {
         y: number;
     }): void;
     setAnnotationComment(value: string): void;
+    /**
+     * 사용자가 붙여넣기(Cmd+V)나 드래그로 넣은 그림. 자동 캡처 결과를 덮는다.
+     *
+     * 자동 캡처보다 이게 우선인 이유: 사용자가 굳이 그림을 붙였다면 그건 "지금 화면"이
+     * 아니라 **보여주고 싶은 다른 것**이다(잘라낸 부분, 다른 탭, 기대하는 디자인).
+     */
+    attachAnnotationImage(shot: FeedbackScreenshot): Promise<void>;
+    /** 그림만 뗀다. 코멘트는 그대로 — 그림이 없어도 주석은 성립한다. */
+    removeAnnotationImage(): void;
     /** 취소 — 마커도 제보도 남기지 않는다. 모드는 켜진 채로 둔다. */
     cancelAnnotation(): void;
+    private isSavable;
+    /** 도는 캡처가 있으면 끝나기를 기다린다. 캡처가 던져도 저장을 막지 않는다. */
+    private settleCapture;
+    private runCapture;
     /**
      * 제출된 제보를 마커로 남긴다. 모달 경로에서 쓴다 — 마커 생성이 팝업 저장 안에만
      * 있으면, 리포트 모달로 보낸 지목 제보는 화면에 흔적이 남지 않는다("보냈는지 알 수
@@ -202,6 +245,16 @@ declare function reactComponentPath(node: Element, limit?: number): string[];
 /** 제보 본문에 실을 한 줄. 컴포넌트를 못 찾으면 null(빈 줄을 만들지 않는다). */
 declare function reactComponentSummary(node: Element): string | null;
 
+/**
+ * 요소를 고른 뒤 무엇을 띄우는가.
+ *
+ * - `popup`(기본): 클릭한 자리에 **한 줄 입력창**. Enter 로 바로 보낸다.
+ * - `modal`: 화면 중앙의 전체 리포트 모달(우선순위까지 고른다).
+ *
+ * 기본이 팝업인 이유: 지목은 "여기 이거요" 를 여러 곳에 연달아 남기는 작업이다.
+ * 클릭마다 중앙 모달이 뜨면 시선이 클릭 지점을 떠나고, 어디를 가리켰는지 잊는다.
+ */
+type PickTarget = "popup" | "modal";
 interface WebWidgetOpts extends Omit<WidgetControllerOpts, "platform" | "initialPicking" | "onPickingChange"> {
     /** 지목 모드 플래그와 마커를 담아 둘 저장소. 기본은 `localStorage`. */
     store?: MarkerStore;
@@ -213,6 +266,8 @@ interface WebWidgetOpts extends Omit<WidgetControllerOpts, "platform" | "initial
         width: number;
         height: number;
     };
+    /** 요소를 고른 뒤 띄울 UI. 기본은 `popup`. */
+    pickTarget?: PickTarget;
 }
 interface WebWidget {
     widget: WidgetController;