one-design-next 0.0.122 → 0.0.123

package/dist/composer/editor.d.ts

@@ -18,6 +18,7 @@
  */
 import React from 'react';
 import type { ChipData } from '../_genui-types';
+import { type ComposerSkillHint } from './segments';
 /** Composer editor 触发态对外信号——告诉父组件该弹浮层选 skill 了。 */
 export interface ComposerEditorTriggerInfo {
     /** 触发字符（@ 或 /） */
@@ -72,6 +73,16 @@ export interface ComposerEditorProps {
     defaultValue?: string;
     /** 值变化回调；参数是 raw string，含 marker。 */
     onChange?: (value: string) => void;
+    /**
+     * 灰字（skill hint）命中状态变化回调：
+     *   - 灰字出现（最后一个 chip 命中结构谓词）→ 传入命中的 chip / 文案
+     *   - 灰字消失（后面有内容 / chip 被删 / hint 已关闭）→ 传入 null
+     *
+     * 只在状态**真的变化**时抛一次；与灰字渲染共用同一份判定（先落 DOM 再抛，
+     * 不会各自算一套）。判定成立但灰字被临时摘掉（IME 合成期）时不跟着抖。
+     * 挂载时会先同步一次当前状态（空内容即 null），业务侧不必自己猜初始值。
+     */
+    onSkillHintChange?: (hint: ComposerSkillHint | null) => void;
     /** 与 defaultValue / 首次受控 value 配套，把 marker 还原成 chip。 */
     defaultChips?: ChipData[];
     placeholder?: string;

package/dist/composer/editor.js

@@ -326,6 +326,7 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
     defaultValue = _ref$defaultValue === void 0 ? '' : _ref$defaultValue,
     defaultChips = _ref.defaultChips,
     onChange = _ref.onChange,
+    onSkillHintChange = _ref.onSkillHintChange,
     placeholder = _ref.placeholder,
     autoSize = _ref.autoSize,
     onPressEnter = _ref.onPressEnter,
@@ -353,6 +354,9 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
   var isComposingRef = useRef(false);
   var onTriggerChangeRef = useRef(onTriggerChange);
   onTriggerChangeRef.current = onTriggerChange;
+  /** 灰字状态回调走 ref：调用方常传内联函数，不能让 fireChange / 挂载同步因此反复重建 */
+  var onSkillHintChangeRef = useRef(onSkillHintChange);
+  onSkillHintChangeRef.current = onSkillHintChange;
   var isControlled = valueProp !== undefined;
   var minRows = (_autoSize$minRows = autoSize === null || autoSize === void 0 ? void 0 : autoSize.minRows) !== null && _autoSize$minRows !== void 0 ? _autoSize$minRows : 1;
   var maxRows = autoSize === null || autoSize === void 0 ? void 0 : autoSize.maxRows;
@@ -587,6 +591,33 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
     }
   }, [removeHintNode]);
 
+  /* 灰字状态的**上一帧快照**：回调只在真的变化时抛一次。
+   * fireChange 每次输入都会跑，不去重的话业务侧会被同一条状态反复冲刷。
+   * `undefined` = 还没抛过（与「抛过 null」区分），保证挂载时一定会同步一次。 */
+  var lastSkillHintRef = useRef(undefined);
+
+  /**
+   * 把「灰字当前状态」通知给业务方（与 syncHintNode 同一份 target，保证同源）。
+   *
+   * 只在 chipId / refId / 文案任一变化时抛：同一条状态在连续输入里会算很多次。
+   */
+  var notifySkillHint = useCallback(function (target, chips) {
+    var _chips$find, _onSkillHintChangeRef;
+    var next = target ? {
+      chipId: target.chipId,
+      text: target.text,
+      refId: (_chips$find = chips.find(function (chip) {
+        return chip.id === target.chipId;
+      })) === null || _chips$find === void 0 ? void 0 : _chips$find.refId
+    } : null;
+    var prev = lastSkillHintRef.current;
+    if (prev !== undefined && (prev === null || prev === void 0 ? void 0 : prev.chipId) === (next === null || next === void 0 ? void 0 : next.chipId) && (prev === null || prev === void 0 ? void 0 : prev.text) === (next === null || next === void 0 ? void 0 : next.text) && (prev === null || prev === void 0 ? void 0 : prev.refId) === (next === null || next === void 0 ? void 0 : next.refId)) {
+      return;
+    }
+    lastSkillHintRef.current = next;
+    (_onSkillHintChangeRef = onSkillHintChangeRef.current) === null || _onSkillHintChangeRef === void 0 || _onSkillHintChangeRef.call(onSkillHintChangeRef, next);
+  }, []);
+
   /** 把 caret 直接落到 hint 之前（= chip 右侧）；没有 hint 时不动。 */
   var placeCaretBeforeHint = useCallback(function () {
     var el = editorRef.current;
@@ -627,7 +658,12 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
      * 否则「chip 被删」时残留的 hint 文本会让 placeholder 判定与 lite 升格
      * 判定晚一拍。 */
     closeChipHintsRef.current(resolveHintClosedChipIds(raw, chips));
-    syncHintNode(resolveHintTarget(raw, getChipsRef.current()));
+    /* 关闭会改写 chips 快照，谓词必须用关闭后的快照重新取；
+     * 渲染（syncHintNode）与对外回调（notifySkillHint）共用这一份 target，
+     * 业务拿到的是「这一刻灰字该不该在」的同一份判定，不会各算一套。 */
+    var hintChips = getChipsRef.current();
+    var hintTarget = resolveHintTarget(raw, hintChips);
+    syncHintNode(hintTarget);
     var showPlaceholder = shouldShowPlaceholder(el);
     if (forceNonEmptyOnceRef.current && showPlaceholder) {
       setEmpty(false);
@@ -640,7 +676,23 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
     scheduleControlledSync();
     // editor.height 锁定时 RO 不触发，主动同步一次，确保升格判定能拿到 scrollHeight
     syncHeight();
-  }, [onChange, pullCaretBeforeHint, scheduleControlledSync, shouldShowPlaceholder, syncHeight, syncHintNode]);
+    /* 对外回调放在所有内部状态更新之后：业务在里面同步 setState 甚至
+     * updateChipData 都不会插进「DOM 已落、caret / 高度还没收尾」的中间态。 */
+    notifySkillHint(hintTarget, hintChips);
+  }, [notifySkillHint, onChange, pullCaretBeforeHint, scheduleControlledSync, shouldShowPlaceholder, syncHeight, syncHintNode]);
+
+  /* 挂载时同步一次灰字状态。
+   *
+   * 带 chips 的草稿恢复已经在挂载的 layout effect 里走 fireChange 抛过一次，
+   * 这里兜的是「空内容 / 只有纯文本挂载」——否则业务侧上一轮留下的状态没人复位。
+   * 放在 passive effect：晚于 chips 还原，且 notifySkillHint 自带去重，
+   * 与 fireChange 那一次重复时不会再抛。 */
+  useEffect(function () {
+    var el = editorRef.current;
+    if (!el) return;
+    var hintChips = getChipsRef.current();
+    notifySkillHint(resolveHintTarget(getPlainText(el), hintChips), hintChips);
+  }, [notifySkillHint]);
 
   /* ─────────────────────────────────────
    * chip 管理
@@ -785,6 +837,10 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
           onTriggerChange === null || onTriggerChange === void 0 || onTriggerChange(null);
         }
         onChange === null || onChange === void 0 || onChange('');
+        /* 这条路不走 fireChange（清空不是「内容变化」链路的一环），
+         * 灰字状态要在这里手动同步，否则业务侧会一直以为灰字还显示着。
+         * 位置放在 onChange 之后，与 fireChange 的「先 onChange 再灰字」一致。 */
+        notifySkillHint(null, []);
       },
       insertChip: function insertChip(data) {
         var el = editorRef.current;
@@ -881,7 +937,7 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
         return editorRef.current;
       }
     };
-  }, [onChange, _insertChip, insertSerializedAtRange, requestScrollCaretIntoView, removeChip, resetChips, onTriggerChange, getChips, updateChipData, getChipHost]);
+  }, [onChange, _insertChip, insertSerializedAtRange, notifySkillHint, requestScrollCaretIntoView, removeChip, resetChips, onTriggerChange, getChips, updateChipData, getChipHost]);
 
   /* ─────────────────────────────────────
    * 监听 selection 变化：方向键 / 鼠标点击移位都要重算 trigger
@@ -1037,6 +1093,8 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
       }
       removeHintNode();
       resetChips();
+      /* 同 clear()：外部改写 value 不走 fireChange，灰字状态在这里手动同步 */
+      notifySkillHint(null, []);
       setEmpty(shouldShowPlaceholder(el));
       if (triggerRef.current) {
         var _onTriggerChangeRef$c;
@@ -1045,7 +1103,7 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
       }
       syncHeight();
     }
-  }, [controlledSyncTick, valueProp, isControlled, resetChips, shouldShowPlaceholder, syncHeight]);
+  }, [controlledSyncTick, valueProp, isControlled, notifySkillHint, resetChips, shouldShowPlaceholder, syncHeight]);
 
   /* ─────────────────────────────────────
    * 输入事件

package/dist/composer/index.d.ts

@@ -4,9 +4,11 @@ import type { IconName } from '../icon';
 import { type SkillSlotProps } from '../skill-slot';
 import { type ComposerInsertOptions, type ComposerInsertPart, type ComposerInsertResult } from './insert';
 import type { ComposerParamPanelContext } from './param-panel';
+import { type ComposerSkillHint } from './segments';
 import './style';
 export type { ComposerInsertOptions, ComposerInsertPart, ComposerInsertResult, } from './insert';
 export type { ComposerParamPanelContext } from './param-panel';
+export type { ComposerHintTarget, ComposerSkillHint } from './segments';
 export type ComposerTool = 'attachment' | 'webSearch' | 'skill';
 export type ComposerVariant = 'full' | 'lite';
 export type SubmitType = 'enter' | 'shiftEnter';
@@ -105,6 +107,22 @@ export interface ComposerProps {
     defaultChips?: ChipData[];
     /** 输入框值变化回调。第二参是当前 chip 快照，旧调用方忽略即可。 */
     onChange?: (value: string, chips?: ChipData[]) => void;
+    /**
+     * 技能灰字（`SkillItem.hint`）的出现 / 消失回调。
+     *
+     * 入参与输入框里那行灰字共用**同一份判定**（`resolveHintTarget`）：命中时给
+     * `{ chipId, text, refId }`，消失时给 `null`。因此业务不需要自己解析
+     * value / chips，也不会出现「库里觉得有、业务觉得没有」的分歧。
+     *
+     * 语义要点：
+     * - 只在状态真的变化时抛一次，同一条状态不会因为连续输入重复抛；
+     * - 判定成立但灰字被临时摘掉（IME 合成期避开候选串）时不跟着抖；
+     * - 挂载时先同步一次当前状态（首屏没有灰字即 `null`），便于业务复位上一轮状态；
+     * - 灰字一次性：收起后即使把内容删回空串也不会再抛命中；
+     * - 卸载不会再补一次 `null`：需要清理时由业务在自己的卸载路径处理；
+     * - 与 `hint`（底部快捷键提示开关）无关。
+     */
+    onSkillHintChange?: (hint: ComposerSkillHint | null) => void;
     /**
      * 发送回调。
      *

package/dist/composer/index.js

@@ -94,6 +94,7 @@ export var Composer = /*#__PURE__*/forwardRef(function Composer(_ref, ref) {
     defaultValue = _ref$defaultValue === void 0 ? '' : _ref$defaultValue,
     defaultChips = _ref.defaultChips,
     onChangeProp = _ref.onChange,
+    onSkillHintChange = _ref.onSkillHintChange,
     onSend = _ref.onSend,
     onStop = _ref.onStop,
     _ref$isGenerating = _ref.isGenerating,
@@ -1235,6 +1236,7 @@ export var Composer = /*#__PURE__*/forwardRef(function Composer(_ref, ref) {
     value: text,
     defaultChips: defaultChips,
     onChange: updateText,
+    onSkillHintChange: onSkillHintChange,
     disabled: disabled,
     paramEditChipId: (_paramEdit$chipId = paramEdit === null || paramEdit === void 0 ? void 0 : paramEdit.chipId) !== null && _paramEdit$chipId !== void 0 ? _paramEdit$chipId : null,
     onInlineRefClick: renderParamPanel ? handleInlineRefClick : undefined

package/dist/composer/segments.d.ts

@@ -29,6 +29,17 @@ export interface ComposerHintTarget {
     /** 提示文本（skill 模板文案，发送时原样作为 hint 段的 data.text） */
     text: string;
 }
+/**
+ * 灰字当前状态的对外快照（`ComposerProps.onSkillHintChange` 的入参）。
+ *
+ * 在 `ComposerHintTarget` 基础上补 chip 的业务标识：业务拿到回调时通常只想
+ * 知道「哪一块技能正在展示灰字」，不必再去 onChange 的 chips 快照里反查——
+ * 尤其 chip 插入与注册是两条异步链路，反查可能还没就绪。
+ */
+export interface ComposerSkillHint extends ComposerHintTarget {
+    /** 命中 chip 的业务侧资源 id（`ChipData.refId`，skill chip 即 `SkillItem.id`）；自定义 chip 可能没有 */
+    refId?: string;
+}
 /**
  * 判定当前内容是否命中 hint：
  * 1. `value` 里存在 marker（即至少有一个 chip）

package/dist/composer/segments.js

@@ -61,6 +61,14 @@ export var isHintSegment = function isHintSegment(s) {
 
 /** hint 命中结果。 */
 
+/**
+ * 灰字当前状态的对外快照（`ComposerProps.onSkillHintChange` 的入参）。
+ *
+ * 在 `ComposerHintTarget` 基础上补 chip 的业务标识：业务拿到回调时通常只想
+ * 知道「哪一块技能正在展示灰字」，不必再去 onChange 的 chips 快照里反查——
+ * 尤其 chip 插入与注册是两条异步链路，反查可能还没就绪。
+ */
+
 /**
  * 最后一个 marker 的 chip id 与它之后的尾串；没有 chip 时返回 null。
  *

package/dist/index.d.ts

@@ -83,4 +83,4 @@ export { default as Welcome, type WelcomeProps } from './welcome';
 export { ComposerSegmentType } from './_genui-types';
 export type { AgentEvent, Attachment, ChatMessage, ChipData, ComposerHintSegment, ComposerInvocationSegment, ComposerMentionSegment, ComposerSegment, ComposerTextSegment, Conversation, HintData, InlineRefState, InvocationData, MentionData, MessageSnapshot, PreviewTab, PreviewTarget, SendMeta, SkillItem, Source, TextData, ToolCall, ToolStatus, } from './_genui-types';
 export type { InterruptBase, InterruptIntent, InterruptStatus, } from './_interrupt-types';
-export { isHintSegment, isInvocationSegment, isMentionSegment, isTextSegment, rawValueToSegments, resolveHintTarget, segmentsHasContent, segmentsToReadableText, type ComposerHintTarget, type SegmentsToReadableTextOptions, } from './composer/segments';
+export { isHintSegment, isInvocationSegment, isMentionSegment, isTextSegment, rawValueToSegments, resolveHintTarget, segmentsHasContent, segmentsToReadableText, type ComposerHintTarget, type ComposerSkillHint, type SegmentsToReadableTextOptions, } from './composer/segments';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "one-design-next",
-  "version": "0.0.122",
+  "version": "0.0.123",
   "description": "One Design Next from TAD@tencent.com",
   "license": "MIT",
   "type": "module",