@solhun/feedback-kit-web 0.4.0 → 0.6.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-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 { ElementInfo, FeedbackPin, FeedbackScreenshot, FeedbackHint, FeedbackReport, SubmitOutcome, QueueStatus, ReportParts, ScreenshotCapture, ScreenshotReencode, WidgetControllerOpts, HintProvider, WidgetController, FeedbackStorage, ContextProviders } from '@solhun/feedback-kit-core';
+export { COMMENT_MAX_CHARS, COMMENT_REQUIRED_MESSAGE, COMMENT_TOO_LONG_MESSAGE, ElementInfo, ElementLike, FLOATING_BUTTON_ID, FeedbackAdapter, FeedbackConfig, FeedbackContext, FeedbackHint, FeedbackPin, FeedbackReport, FeedbackStorage, FeedbackUser, HintCatalog, HintElementRule, HintPlatform, HintProvider, HintRankInput, HintScope, MODAL_ACTION_HINT_TOGGLE, 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, rankHints, resolveConfig, shouldShowWidget, sourceFromElement } from '@solhun/feedback-kit-core';
 import * as react from 'react';
 
 /** 요소 텍스트를 담을 때의 상한. 본문 전체가 실려 페이로드가 붓는 걸 막는다. */
@@ -96,6 +96,16 @@ interface AnnotationPopupState {
     screenshotStatus: AnnotationShotStatus;
     /** 저장 중인가. 두 번 눌러 같은 주석이 두 번 가는 것을 막는다. */
     saving: boolean;
+    /**
+     * 자주 나오는 제보 제안 칩. 리포트 모달과 같은 계약(같은 `rankHints` 결과, 같은 접힘 규칙,
+     * 같은 `hintIds` 흐름)이다 — "들어온 문이 달라도 담기는 정보는 같다"가 이 위젯의 약속이고,
+     * 제안 칩도 예외가 아니다. `widget.ts` 가 만든 `HintProvider` 를 그대로 물려 쓴다
+     * (팝업이 자기 카탈로그를 따로 들고 있지 않는다).
+     */
+    hints: readonly FeedbackHint[];
+    hintsExpanded: boolean;
+    hintsAvailable: boolean;
+    usedHintIds: readonly string[];
 }
 interface PickingState {
     active: boolean;
@@ -136,6 +146,11 @@ interface ElementPickingOpts {
      * 요소 하나 고를 때마다 모드가 꺼지면 매번 다시 켜야 한다.
      */
     onPick?: (element: ElementInfo | null, point: FeedbackPin) => void;
+    /**
+     * 힌트 랭킹 계산. `widget.ts` 가 만든 `HintProvider` 의 카탈로그를 그 시점의 경로·요소로
+     * `rankHints` 한 결과를 돌려준다. 없으면(힌트 기능이 꺼져 있으면) 팝업에 칩이 안 뜬다.
+     */
+    rankHintsFor?: ((element: ElementInfo | null) => readonly FeedbackHint[]) | null;
 }
 declare class ElementPickingController {
     private readonly queue;
@@ -149,6 +164,7 @@ declare class ElementPickingController {
     private readonly reencode;
     private readonly screenshotLimitBytes;
     private readonly unsubscribeQueue;
+    private readonly rankHintsFor;
     private readonly listeners;
     private active;
     private attached;
@@ -162,6 +178,11 @@ declare class ElementPickingController {
     private shotGeneration;
     /** 지금 도는 자동 캡처. Enter 가 캡처보다 빨랐을 때 기다릴 대상. */
     private capturing;
+    /**
+     * 사용자가 [제안 ▾] 를 직접 건드렸는가. 한 번이라도 건드리면 이후 타이핑에 의한 자동
+     * 접힘/펼침이 멈춘다 — 모달의 `userToggledHints` 와 같은 규칙. 팝업을 새로 열 때마다 리셋된다.
+     */
+    private userToggledHints;
     private readonly onClick;
     private readonly onMouseOver;
     constructor(opts: ElementPickingOpts);
@@ -189,6 +210,18 @@ declare class ElementPickingController {
         y: number;
     }): void;
     setAnnotationComment(value: string): void;
+    /**
+     * 코멘트가 비었는지에 따라 칩 줄 상태를 갱신하는 조각. `setAnnotationComment`·`applyHint`
+     * 양쪽에서 쓴다 — 모달의 `hintsPatchFor` 와 같은 규칙이다.
+     */
+    private hintsPatchFor;
+    /**
+     * 칩 누름. 이미 눌린 칩이면 아무 일도 하지 않는다. 코멘트가 비어 있으면 초안으로 치환,
+     * 아니면 줄바꿈 뒤 이어붙인다 — 모달의 `applyHint` 와 동일한 규칙이다.
+     */
+    applyHint(hintId: string): void;
+    /** [제안 ▾] 토글. 방향과 무관하게 이후 자동 접힘/펼침을 멈춘다. */
+    toggleHints(): void;
     /**
      * 사용자가 붙여넣기(Cmd+V)나 드래그로 넣은 그림. 자동 캡처 결과를 덮는다.
      *
@@ -268,6 +301,13 @@ interface WebWidgetOpts extends Omit<WidgetControllerOpts, "platform" | "initial
     };
     /** 요소를 고른 뒤 띄울 UI. 기본은 `popup`. */
     pickTarget?: PickTarget;
+    /**
+     * 정적 힌트 목록(설정으로 직접 넘김). 주면 서버에서 받아오지 않는다 — 도입 초기·오프라인
+     * 데모·테스트용이다. 서버 목록과 합치지 않는다(둘을 섞으면 무엇이 보이는지 설명이 안 된다).
+     */
+    hints?: readonly FeedbackHint[];
+    /** 힌트 조회 컨트롤러 주입(테스트용). 주면 큐 어댑터의 fetchHints 를 보지 않는다. */
+    hintProvider?: HintProvider;
 }
 interface WebWidget {
     widget: WidgetController;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-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 { ElementInfo, FeedbackPin, FeedbackScreenshot, FeedbackHint, FeedbackReport, SubmitOutcome, QueueStatus, ReportParts, ScreenshotCapture, ScreenshotReencode, WidgetControllerOpts, HintProvider, WidgetController, FeedbackStorage, ContextProviders } from '@solhun/feedback-kit-core';
+export { COMMENT_MAX_CHARS, COMMENT_REQUIRED_MESSAGE, COMMENT_TOO_LONG_MESSAGE, ElementInfo, ElementLike, FLOATING_BUTTON_ID, FeedbackAdapter, FeedbackConfig, FeedbackContext, FeedbackHint, FeedbackPin, FeedbackReport, FeedbackStorage, FeedbackUser, HintCatalog, HintElementRule, HintPlatform, HintProvider, HintRankInput, HintScope, MODAL_ACTION_HINT_TOGGLE, 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, rankHints, resolveConfig, shouldShowWidget, sourceFromElement } from '@solhun/feedback-kit-core';
 import * as react from 'react';
 
 /** 요소 텍스트를 담을 때의 상한. 본문 전체가 실려 페이로드가 붓는 걸 막는다. */
@@ -96,6 +96,16 @@ interface AnnotationPopupState {
     screenshotStatus: AnnotationShotStatus;
     /** 저장 중인가. 두 번 눌러 같은 주석이 두 번 가는 것을 막는다. */
     saving: boolean;
+    /**
+     * 자주 나오는 제보 제안 칩. 리포트 모달과 같은 계약(같은 `rankHints` 결과, 같은 접힘 규칙,
+     * 같은 `hintIds` 흐름)이다 — "들어온 문이 달라도 담기는 정보는 같다"가 이 위젯의 약속이고,
+     * 제안 칩도 예외가 아니다. `widget.ts` 가 만든 `HintProvider` 를 그대로 물려 쓴다
+     * (팝업이 자기 카탈로그를 따로 들고 있지 않는다).
+     */
+    hints: readonly FeedbackHint[];
+    hintsExpanded: boolean;
+    hintsAvailable: boolean;
+    usedHintIds: readonly string[];
 }
 interface PickingState {
     active: boolean;
@@ -136,6 +146,11 @@ interface ElementPickingOpts {
      * 요소 하나 고를 때마다 모드가 꺼지면 매번 다시 켜야 한다.
      */
     onPick?: (element: ElementInfo | null, point: FeedbackPin) => void;
+    /**
+     * 힌트 랭킹 계산. `widget.ts` 가 만든 `HintProvider` 의 카탈로그를 그 시점의 경로·요소로
+     * `rankHints` 한 결과를 돌려준다. 없으면(힌트 기능이 꺼져 있으면) 팝업에 칩이 안 뜬다.
+     */
+    rankHintsFor?: ((element: ElementInfo | null) => readonly FeedbackHint[]) | null;
 }
 declare class ElementPickingController {
     private readonly queue;
@@ -149,6 +164,7 @@ declare class ElementPickingController {
     private readonly reencode;
     private readonly screenshotLimitBytes;
     private readonly unsubscribeQueue;
+    private readonly rankHintsFor;
     private readonly listeners;
     private active;
     private attached;
@@ -162,6 +178,11 @@ declare class ElementPickingController {
     private shotGeneration;
     /** 지금 도는 자동 캡처. Enter 가 캡처보다 빨랐을 때 기다릴 대상. */
     private capturing;
+    /**
+     * 사용자가 [제안 ▾] 를 직접 건드렸는가. 한 번이라도 건드리면 이후 타이핑에 의한 자동
+     * 접힘/펼침이 멈춘다 — 모달의 `userToggledHints` 와 같은 규칙. 팝업을 새로 열 때마다 리셋된다.
+     */
+    private userToggledHints;
     private readonly onClick;
     private readonly onMouseOver;
     constructor(opts: ElementPickingOpts);
@@ -189,6 +210,18 @@ declare class ElementPickingController {
         y: number;
     }): void;
     setAnnotationComment(value: string): void;
+    /**
+     * 코멘트가 비었는지에 따라 칩 줄 상태를 갱신하는 조각. `setAnnotationComment`·`applyHint`
+     * 양쪽에서 쓴다 — 모달의 `hintsPatchFor` 와 같은 규칙이다.
+     */
+    private hintsPatchFor;
+    /**
+     * 칩 누름. 이미 눌린 칩이면 아무 일도 하지 않는다. 코멘트가 비어 있으면 초안으로 치환,
+     * 아니면 줄바꿈 뒤 이어붙인다 — 모달의 `applyHint` 와 동일한 규칙이다.
+     */
+    applyHint(hintId: string): void;
+    /** [제안 ▾] 토글. 방향과 무관하게 이후 자동 접힘/펼침을 멈춘다. */
+    toggleHints(): void;
     /**
      * 사용자가 붙여넣기(Cmd+V)나 드래그로 넣은 그림. 자동 캡처 결과를 덮는다.
      *
@@ -268,6 +301,13 @@ interface WebWidgetOpts extends Omit<WidgetControllerOpts, "platform" | "initial
     };
     /** 요소를 고른 뒤 띄울 UI. 기본은 `popup`. */
     pickTarget?: PickTarget;
+    /**
+     * 정적 힌트 목록(설정으로 직접 넘김). 주면 서버에서 받아오지 않는다 — 도입 초기·오프라인
+     * 데모·테스트용이다. 서버 목록과 합치지 않는다(둘을 섞으면 무엇이 보이는지 설명이 안 된다).
+     */
+    hints?: readonly FeedbackHint[];
+    /** 힌트 조회 컨트롤러 주입(테스트용). 주면 큐 어댑터의 fetchHints 를 보지 않는다. */
+    hintProvider?: HintProvider;
 }
 interface WebWidget {
     widget: WidgetController;