@solhun/feedback-kit-web 0.5.0 → 0.6.0

package/dist/index.cjs

@@ -37,8 +37,10 @@ __export(index_exports, {
   ElementPickingController: () => ElementPickingController,
   FLOATING_BUTTON_ID: () => import_feedback_kit_core6.FLOATING_BUTTON_ID,
   FeedbackKit: () => FeedbackKit,
+  HintProvider: () => import_feedback_kit_core7.HintProvider,
   MARKER_KEY_PREFIX: () => MARKER_KEY_PREFIX,
   MAX_MARKERS_PER_PATH: () => MAX_MARKERS_PER_PATH,
+  MODAL_ACTION_HINT_TOGGLE: () => import_feedback_kit_core6.MODAL_ACTION_HINT_TOGGLE,
   MODAL_ACTION_PICK: () => import_feedback_kit_core6.MODAL_ACTION_PICK,
   MarkerStore: () => MarkerStore,
   OWN_UI_ATTR: () => OWN_UI_ATTR,
@@ -59,6 +61,7 @@ __export(index_exports, {
   isOwnUi: () => isOwnUi2,
   normalizePin: () => import_feedback_kit_core6.normalizePin,
   parseSourceAttr: () => import_feedback_kit_core5.parseSourceAttr,
+  rankHints: () => import_feedback_kit_core7.rankHints,
   reactComponentPath: () => reactComponentPath,
   reactComponentSummary: () => reactComponentSummary,
   reencodeWebScreenshot: () => reencodeWebScreenshot,
@@ -72,6 +75,7 @@ module.exports = __toCommonJS(index_exports);
 var import_feedback_kit_core4 = require("@solhun/feedback-kit-core");
 var import_feedback_kit_core5 = require("@solhun/feedback-kit-core");
 var import_feedback_kit_core6 = require("@solhun/feedback-kit-core");
+var import_feedback_kit_core7 = require("@solhun/feedback-kit-core");
 
 // src/react-tree.ts
 var FRAMEWORK_INTERNALS = /* @__PURE__ */ new Set([
@@ -381,6 +385,11 @@ var ElementPickingController = class {
     this.shotGeneration = 0;
     /** 지금 도는 자동 캡처. Enter 가 캡처보다 빨랐을 때 기다릴 대상. */
     this.capturing = null;
+    /**
+     * 사용자가 [제안 ▾] 를 직접 건드렸는가. 한 번이라도 건드리면 이후 타이핑에 의한 자동
+     * 접힘/펼침이 멈춘다 — 모달의 `userToggledHints` 와 같은 규칙. 팝업을 새로 열 때마다 리셋된다.
+     */
+    this.userToggledHints = false;
     this.onClick = (event) => this.handleClick(event);
     this.onMouseOver = (event) => this.handleMouseOver(event);
     this.queue = opts.queue;
@@ -393,6 +402,7 @@ var ElementPickingController = class {
     this.capture = opts.capture ?? null;
     this.reencode = opts.reencode ?? null;
     this.screenshotLimitBytes = opts.screenshotLimitBytes;
+    this.rankHintsFor = opts.rankHintsFor ?? null;
     this.lastPathname = this.getPathname();
     this.markers = this.store.list(this.lastPathname);
     this.unsubscribeQueue = this.queue.subscribe?.(() => {
@@ -507,14 +517,22 @@ var ElementPickingController = class {
       this.onPick(describeElement(element), point);
       return;
     }
+    const info = describeElement(element);
+    this.userToggledHints = false;
+    const hints = this.rankHintsFor ? this.rankHintsFor(info) : [];
     this.popup = {
-      element: describeElement(element),
+      element: info,
       point,
       comment: "",
       canSave: false,
       screenshot: null,
       screenshotStatus: this.capture ? "capturing" : "none",
-      saving: false
+      saving: false,
+      hints,
+      // 코멘트가 비어 있을 때만 펼친다 — 모달과 같은 규칙(계약 원문). 방금 연 팝업은 항상 빈다.
+      hintsExpanded: true,
+      hintsAvailable: hints.length > 0,
+      usedHintIds: []
     };
     this.emit();
     if (this.capture) this.capturing = this.runCapture();
@@ -524,10 +542,48 @@ var ElementPickingController = class {
     this.popup = {
       ...this.popup,
       comment: value,
-      canSave: this.isSavable(value)
+      canSave: this.isSavable(value),
+      ...this.hintsPatchFor(value)
     };
     this.emit();
   }
+  /**
+   * 코멘트가 비었는지에 따라 칩 줄 상태를 갱신하는 조각. `setAnnotationComment`·`applyHint`
+   * 양쪽에서 쓴다 — 모달의 `hintsPatchFor` 와 같은 규칙이다.
+   */
+  hintsPatchFor(nextComment) {
+    if (nextComment.trim().length === 0) {
+      return { hintsExpanded: true, usedHintIds: [] };
+    }
+    return this.userToggledHints ? {} : { hintsExpanded: false };
+  }
+  /**
+   * 칩 누름. 이미 눌린 칩이면 아무 일도 하지 않는다. 코멘트가 비어 있으면 초안으로 치환,
+   * 아니면 줄바꿈 뒤 이어붙인다 — 모달의 `applyHint` 와 동일한 규칙이다.
+   */
+  applyHint(hintId) {
+    if (!this.popup || this.popup.saving) return;
+    if (this.popup.usedHintIds.includes(hintId)) return;
+    const hint = this.popup.hints.find((h) => h.id === hintId);
+    if (!hint) return;
+    const comment = this.popup.comment.length === 0 ? hint.draft : `${this.popup.comment}
+${hint.draft}`;
+    this.popup = {
+      ...this.popup,
+      comment,
+      canSave: this.isSavable(comment),
+      usedHintIds: [...this.popup.usedHintIds, hintId],
+      ...this.hintsPatchFor(comment)
+    };
+    this.emit();
+  }
+  /** [제안 ▾] 토글. 방향과 무관하게 이후 자동 접힘/펼침을 멈춘다. */
+  toggleHints() {
+    if (!this.popup) return;
+    this.userToggledHints = true;
+    this.popup = { ...this.popup, hintsExpanded: !this.popup.hintsExpanded };
+    this.emit();
+  }
   /**
    * 사용자가 붙여넣기(Cmd+V)나 드래그로 넣은 그림. 자동 캡처 결과를 덮는다.
    *
@@ -634,7 +690,9 @@ var ElementPickingController = class {
       priority: "unset",
       screenshot: settled.screenshot,
       pin: settled.point,
-      element: settled.element
+      element: settled.element,
+      // 눌린 칩 기록. 리포트 모달과 같은 필드 — 들어온 문이 달라도 채택 신호는 같은 값으로 쌓인다.
+      hintIds: settled.usedHintIds
     };
     let report;
     try {
@@ -795,11 +853,100 @@ var reencodeWebScreenshot = async (shot, quality) => {
 
 // src/widget.ts
 var import_feedback_kit_core2 = require("@solhun/feedback-kit-core");
+
+// src/storage.ts
+function memoryStorage() {
+  const map = /* @__PURE__ */ new Map();
+  return {
+    getItem: (key) => map.get(key) ?? null,
+    setItem: (key, value) => void map.set(key, value),
+    removeItem: (key) => void map.delete(key)
+  };
+}
+function pickBacking() {
+  try {
+    const ls = globalThis.localStorage;
+    if (!ls) return memoryStorage();
+    const probe = "__feedback_kit_probe__";
+    ls.setItem(probe, "1");
+    ls.removeItem(probe);
+    return ls;
+  } catch {
+    return memoryStorage();
+  }
+}
+function createWebStorage(backing) {
+  const store = backing ?? pickBacking();
+  return {
+    async get(key) {
+      try {
+        return store.getItem(key);
+      } catch {
+        return null;
+      }
+    },
+    async set(key, value) {
+      store.setItem(key, value);
+    },
+    async remove(key) {
+      try {
+        store.removeItem(key);
+      } catch {
+      }
+    }
+  };
+}
+
+// src/widget.ts
+function stripQueryHash(path) {
+  const cut = [path.indexOf("?"), path.indexOf("#")].filter((i) => i >= 0);
+  return cut.length > 0 ? path.slice(0, Math.min(...cut)) : path;
+}
+function defaultPathname2() {
+  const loc = globalThis.location;
+  return loc?.pathname ?? "/";
+}
+function hintSourceFrom(queue) {
+  const adapter = queue.adapter;
+  if (!adapter || typeof adapter.fetchHints !== "function") return null;
+  const cacheKey = adapter.hintsCacheKey ?? "default";
+  return { fetchHints: adapter.fetchHints.bind(adapter), cacheKey };
+}
+function resolveHintProvider(opts) {
+  if (opts.hintProvider) return opts.hintProvider;
+  if (opts.hints) {
+    return new import_feedback_kit_core2.HintProvider({ source: null, staticHints: opts.hints, cacheKey: "static" });
+  }
+  const found = hintSourceFrom(opts.queue);
+  if (!found) return null;
+  return new import_feedback_kit_core2.HintProvider({
+    source: { fetchHints: (etag) => found.fetchHints(etag) },
+    storage: createWebStorage(),
+    cacheKey: found.cacheKey
+  });
+}
+var POPUP_HINT_DISPLAY_MAX = 3;
+function rankFor(hintProvider, opts, element, limitOverride) {
+  const catalog = hintProvider.catalog();
+  if (!catalog) return [];
+  const input = {
+    platform: "web",
+    path: stripQueryHash(opts.getPathname ? opts.getPathname() : defaultPathname2()),
+    element,
+    components: element ? element.attributes["react-components"] ?? null : null
+  };
+  const limit = limitOverride !== void 0 ? Math.min(limitOverride, catalog.maxDisplay) : catalog.maxDisplay;
+  return (0, import_feedback_kit_core2.rankHints)(catalog.hints, input, limit);
+}
 function createWebWidget(opts) {
   const store = opts.store ?? new MarkerStore();
   let widgetRef = null;
   const capture = opts.capture === void 0 ? captureWebScreenshot : opts.capture;
   const reencode = opts.reencode === void 0 ? reencodeWebScreenshot : opts.reencode;
+  const hintProvider = resolveHintProvider(opts);
+  if (hintProvider) {
+    void hintProvider.load().then(() => hintProvider.refresh());
+  }
   const picking = new ElementPickingController({
     queue: opts.queue,
     createReport: opts.createReport,
@@ -815,7 +962,8 @@ function createWebWidget(opts) {
     // 모드는 어느 쪽이든 켜진 채로 둬서 한 번 켜고 여러 요소를 연달아 지목할 수 있다.
     onPick: opts.pickTarget === "modal" ? (element, point) => {
       void widgetRef?.openReport({ element, pin: point });
-    } : void 0
+    } : void 0,
+    rankHintsFor: hintProvider ? (element) => rankFor(hintProvider, opts, element, POPUP_HINT_DISPLAY_MAX) : null
   });
   const widget = new import_feedback_kit_core2.WidgetController({
     ...opts,
@@ -830,6 +978,13 @@ function createWebWidget(opts) {
     }
   });
   widgetRef = widget;
+  const originalOpenReport = widget.openReport.bind(widget);
+  widget.openReport = async (openOpts = {}) => {
+    if (hintProvider) {
+      widget.modal.setHints(rankFor(hintProvider, opts, openOpts.element ?? null));
+    }
+    await originalOpenReport(openOpts);
+  };
   const originalSubmit = widget.submitReport.bind(widget);
   widget.submitReport = async () => {
     const outcome = await originalSubmit();
@@ -854,7 +1009,7 @@ var import_feedback_kit_core3 = require("@solhun/feedback-kit-core");
 var import_react = require("react");
 
 // src/version.ts
-var VERSION = true ? "0.5.0" : "dev";
+var VERSION = true ? "0.6.0" : "dev";
 
 // src/feedback-kit.tsx
 var import_jsx_runtime = require("react/jsx-runtime");
@@ -1116,6 +1271,69 @@ function MarkerStatus({ status }) {
     /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { children: presentation.text })
   ] });
 }
+function HintChips({
+  hints,
+  hintsExpanded,
+  usedHintIds,
+  disabled,
+  onApply,
+  onToggle
+}) {
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { style: { marginBottom: 16 }, children: [
+    hintsExpanded ? /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(import_jsx_runtime.Fragment, { children: [
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", { style: { margin: "0 0 7px", color: TOKENS.muted, fontSize: 12 }, children: "\uC774\uB7F0 \uAC74\uAC00\uC694?" }),
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+        "div",
+        {
+          role: "group",
+          "aria-label": "\uC790\uC8FC \uB098\uC624\uB294 \uC81C\uBCF4 \uC81C\uC548",
+          style: { display: "flex", flexWrap: "wrap", gap: 6, marginBottom: 7 },
+          children: hints.map((hint) => {
+            const used = usedHintIds.includes(hint.id);
+            return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+              "button",
+              {
+                type: "button",
+                "data-fk-focus-id": `hint:${hint.id}`,
+                disabled: used || disabled,
+                "aria-pressed": used,
+                onClick: () => onApply(hint.id),
+                style: {
+                  ...baseButton,
+                  minHeight: 30,
+                  padding: "5px 10px",
+                  fontSize: 12,
+                  fontWeight: 600,
+                  borderRadius: 999,
+                  ...used ? {
+                    background: TOKENS.subtle,
+                    color: TOKENS.muted,
+                    borderColor: TOKENS.line,
+                    cursor: "default"
+                  } : {}
+                },
+                children: hint.label
+              },
+              hint.id
+            );
+          })
+        }
+      )
+    ] }) : null,
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+      "button",
+      {
+        type: "button",
+        "data-fk-focus-id": import_feedback_kit_core3.MODAL_ACTION_HINT_TOGGLE,
+        "aria-expanded": hintsExpanded,
+        disabled,
+        onClick: onToggle,
+        style: { ...baseButton, minHeight: 28, padding: "4px 10px", fontSize: 12 },
+        children: hintsExpanded ? "\uC81C\uC548 \u25B4" : "\uC81C\uC548 \u25BE"
+      }
+    )
+  ] });
+}
 function FeedbackKit(props) {
   const rootRef = (0, import_react.useRef)(null);
   const floatingButtonRef = (0, import_react.useRef)(null);
@@ -1138,7 +1356,10 @@ function FeedbackKit(props) {
     store,
     getPathname,
     doc,
-    getViewport
+    getViewport,
+    pickTarget,
+    hints,
+    hintProvider
   } = props;
   (0, import_react.useEffect)(() => {
     const created = createWebWidget({
@@ -1150,7 +1371,10 @@ function FeedbackKit(props) {
       store,
       getPathname,
       doc,
-      getViewport
+      getViewport,
+      pickTarget,
+      hints,
+      hintProvider
     });
     setKit(created);
     const unsubscribeWidget = created.widget.subscribe(setWidgetState);
@@ -1168,6 +1392,9 @@ function FeedbackKit(props) {
     screenshotLimitBytes,
     store,
     getPathname,
+    pickTarget,
+    hints,
+    hintProvider,
     doc,
     getViewport
   ]);
@@ -1466,6 +1693,17 @@ function FeedbackKit(props) {
                         )
                       ] })
                     ] }),
+                    modal.hintsAvailable ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+                      HintChips,
+                      {
+                        hints: modal.hints,
+                        hintsExpanded: modal.hintsExpanded,
+                        usedHintIds: modal.usedHintIds,
+                        disabled: draftLocked,
+                        onApply: (hintId) => kit.widget.modal.applyHint(hintId),
+                        onToggle: () => kit.widget.modal.toggleHints()
+                      }
+                    ) : null,
                     /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("label", { htmlFor: "feedback-kit-comment", style: { display: "block", fontWeight: 700 }, children: [
                       "\uCF54\uBA58\uD2B8 ",
                       /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { "aria-hidden": "true", children: "*" })
@@ -1722,6 +1960,17 @@ function FeedbackKit(props) {
                         ]
                       }
                     ),
+                    popup.hintsAvailable ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+                      HintChips,
+                      {
+                        hints: popup.hints,
+                        hintsExpanded: popup.hintsExpanded,
+                        usedHintIds: popup.usedHintIds,
+                        disabled: popup.saving,
+                        onApply: (hintId) => kit.picking.applyHint(hintId),
+                        onToggle: () => kit.picking.toggleHints()
+                      }
+                    ) : null,
                     /* @__PURE__ */ (0, import_jsx_runtime.jsx)("label", { htmlFor: "feedback-kit-annotation", style: visuallyHidden, children: "\uC774 \uC694\uC18C\uC5D0 \uB0A8\uAE38 \uC758\uACAC" }),
                     /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
                       "textarea",
@@ -1822,49 +2071,6 @@ function FeedbackKit(props) {
   );
 }
 
-// src/storage.ts
-function memoryStorage() {
-  const map = /* @__PURE__ */ new Map();
-  return {
-    getItem: (key) => map.get(key) ?? null,
-    setItem: (key, value) => void map.set(key, value),
-    removeItem: (key) => void map.delete(key)
-  };
-}
-function pickBacking() {
-  try {
-    const ls = globalThis.localStorage;
-    if (!ls) return memoryStorage();
-    const probe = "__feedback_kit_probe__";
-    ls.setItem(probe, "1");
-    ls.removeItem(probe);
-    return ls;
-  } catch {
-    return memoryStorage();
-  }
-}
-function createWebStorage(backing) {
-  const store = backing ?? pickBacking();
-  return {
-    async get(key) {
-      try {
-        return store.getItem(key);
-      } catch {
-        return null;
-      }
-    },
-    async set(key, value) {
-      store.setItem(key, value);
-    },
-    async remove(key) {
-      try {
-        store.removeItem(key);
-      } catch {
-      }
-    }
-  };
-}
-
 // src/providers.ts
 function webContextProviders() {
   return {
@@ -1895,8 +2101,10 @@ function webContextProviders() {
   ElementPickingController,
   FLOATING_BUTTON_ID,
   FeedbackKit,
+  HintProvider,
   MARKER_KEY_PREFIX,
   MAX_MARKERS_PER_PATH,
+  MODAL_ACTION_HINT_TOGGLE,
   MODAL_ACTION_PICK,
   MarkerStore,
   OWN_UI_ATTR,
@@ -1917,6 +2125,7 @@ function webContextProviders() {
   isOwnUi,
   normalizePin,
   parseSourceAttr,
+  rankHints,
   reactComponentPath,
   reactComponentSummary,
   reencodeWebScreenshot,