one-design-next 0.0.113 → 0.0.114

package/dist/_genui-types.d.ts

@@ -120,7 +120,8 @@ export interface MentionData {
 }
 /**
  * Composer 编辑器内 chip 实例数据（DOM host + Portal 渲染用）。
- * 发送时经 `rawValueToSegments` 转为 `ComposerSegment` 的 invocation / mention。
+ * 发送时经 `rawValueToSegments` 转为 `ComposerSegment` 的 invocation / mention，
+ * 并在命中结构谓词时追加一段 `hint`（见 `ChipData.hint`）。
  */
 export interface ChipData {
     /** chip 实例唯一 id（与 value marker 中的 id 对应） */
@@ -136,12 +137,30 @@ export interface ChipData {
     kind?: 'invocation' | 'mention' | (string & NonNullable<unknown>);
     state?: InlineRefState;
     payload?: Record<string, unknown>;
+    /**
+     * 提示文本快照（插入时由 `SkillItem.hint` 拷贝进来）。
+     *
+     * **不是正文内容**：既不进 `value`（无 marker），也不进剪贴板；只在
+     * 「结构谓词成立」时作为派生的只读视觉渲染在 chip 之后——即该 chip 是
+     * 最后一个内容、且其后**一个字符都没有**（空格 / 换行都算内容；详见
+     * `resolveHintTarget`）。
+     * 发送时由 `rawValueToSegments` 按同一谓词追加为 `ComposerHintSegment`。
+     */
+    hint?: string;
 }
 export interface SkillItem {
     id: string;
     label: string;
     icon: string;
     description?: string;
+    /**
+     * skill 的提示文本（如「根据近期投放数据生成复盘报告…」这类模板文案）。
+     *
+     * 选中插入后，只要该 skill chip 是输入框里最后一个内容且其后没有其它内容
+     * （空格 / 换行都算内容），就会以只读灰字形式渲染在 chip 后面；用户在其后
+     * 输入任何字符或换行即自动隐藏。与光标位置无关。
+     */
+    hint?: string;
     /**
      * 插入后的默认视觉态。`'pending'` 时若 Composer 提供 `renderParamPanel`，
      * 插入后会自动打开参数面板。
@@ -166,8 +185,11 @@ export interface SkillGroup {
  * 这是 `onSend` 的**主出口**：业务按此数组顺序自定义拼后端（可选用
  * `segmentsToReadableText` 工具函数兜底拼成一句话）。
  *
- * 三种分支拆成命名 interface 导出，业务可直接 `import` 单一形态，
+ * 各分支拆成命名 interface 导出，业务可直接 `import` 单一形态，
  * 无需再写 `Extract<ComposerSegment, { type: 'xxx' }>`。
+ *
+ * 其中 `hint` 段是**派生**的（非用户输入），仅在最后一个 skill chip 之后无内容时
+ * 由 Composer 追加；其余三种都来自用户输入。
  */
 /** Composer 文本片段携带的数据。 */
 export interface TextData {
@@ -184,6 +206,8 @@ export declare const ComposerSegmentType: {
     readonly Text: "text";
     readonly Invocation: "invocation";
     readonly Mention: "mention";
+    /** 派生的 skill 提示文本；发送时按结构谓词追加，见 `ComposerHintSegment` */
+    readonly Hint: "hint";
 };
 export type ComposerSegmentType = (typeof ComposerSegmentType)[keyof typeof ComposerSegmentType];
 export interface ComposerTextSegment {
@@ -198,7 +222,22 @@ export interface ComposerMentionSegment {
     type: typeof ComposerSegmentType.Mention;
     data: MentionData;
 }
-export type ComposerSegment = ComposerTextSegment | ComposerInvocationSegment | ComposerMentionSegment;
+/**
+ * 派生的 skill 提示段：**不是用户输入的内容**，而是「最后一个 skill chip + 其后
+ * 无内容」这一结构谓词成立时，由 Composer 在发送瞬间追加的模板文案。
+ *
+ * 只在 `onSend` 的 segments 里出现；不出现在 `value` / `chips` / 剪贴板里。
+ * 需要忽略它的业务可以直接 filter，或用 `isHintSegment` 收窄。
+ */
+export interface ComposerHintSegment {
+    type: typeof ComposerSegmentType.Hint;
+    data: HintData;
+}
+/** Composer 派生 hint 段携带的数据。 */
+export interface HintData {
+    text: string;
+}
+export type ComposerSegment = ComposerTextSegment | ComposerInvocationSegment | ComposerMentionSegment | ComposerHintSegment;
 /** `onSend(segments, meta?)` 第二参数：非正文的附加数据。 */
 export interface SendMeta {
     attachments?: Attachment[];

package/dist/_genui-types.js

@@ -16,7 +16,8 @@
 
 /**
  * Composer 编辑器内 chip 实例数据（DOM host + Portal 渲染用）。
- * 发送时经 `rawValueToSegments` 转为 `ComposerSegment` 的 invocation / mention。
+ * 发送时经 `rawValueToSegments` 转为 `ComposerSegment` 的 invocation / mention，
+ * 并在命中结构谓词时追加一段 `hint`（见 `ChipData.hint`）。
  */
 
 /** 技能分组，用于在 SkillSlot menu 变体中按组名分隔展示。 */
@@ -27,8 +28,11 @@
  * 这是 `onSend` 的**主出口**：业务按此数组顺序自定义拼后端（可选用
  * `segmentsToReadableText` 工具函数兜底拼成一句话）。
  *
- * 三种分支拆成命名 interface 导出，业务可直接 `import` 单一形态，
+ * 各分支拆成命名 interface 导出，业务可直接 `import` 单一形态，
  * 无需再写 `Extract<ComposerSegment, { type: 'xxx' }>`。
+ *
+ * 其中 `hint` 段是**派生**的（非用户输入），仅在最后一个 skill chip 之后无内容时
+ * 由 Composer 追加；其余三种都来自用户输入。
  */
 
 /** Composer 文本片段携带的数据。 */
@@ -43,9 +47,21 @@
 export var ComposerSegmentType = {
   Text: 'text',
   Invocation: 'invocation',
-  Mention: 'mention'
+  Mention: 'mention',
+  /** 派生的 skill 提示文本；发送时按结构谓词追加，见 `ComposerHintSegment` */
+  Hint: 'hint'
 };
 // 同名 type 供 `seg.type === ComposerSegmentType.Invocation` 收窄，与 const 对象并存。
 // eslint-disable-next-line @typescript-eslint/no-redeclare -- 有意的 const + type 同名
 
+/**
+ * 派生的 skill 提示段：**不是用户输入的内容**，而是「最后一个 skill chip + 其后
+ * 无内容」这一结构谓词成立时，由 Composer 在发送瞬间追加的模板文案。
+ *
+ * 只在 `onSend` 的 segments 里出现；不出现在 `value` / `chips` / 剪贴板里。
+ * 需要忽略它的业务可以直接 filter，或用 `isHintSegment` 收窄。
+ */
+
+/** Composer 派生 hint 段携带的数据。 */
+
 /** `onSend(segments, meta?)` 第二参数：非正文的附加数据。 */

package/dist/collapse/primitive.d.ts

@@ -25,7 +25,7 @@ type CollapsibleContentProps = Omit<HTMLMotionProps<'div'>, 'children' | 'ref' |
     children?: React.ReactNode;
     transition?: Transition;
 };
-declare const CollapsibleContent: React.ForwardRefExoticComponent<Omit<HTMLMotionProps<"div">, "children" | "ref" | "transition"> & {
+declare const CollapsibleContent: React.ForwardRefExoticComponent<Omit<HTMLMotionProps<"div">, "ref" | "children" | "transition"> & {
     children?: React.ReactNode;
     transition?: Transition | undefined;
 } & React.RefAttributes<HTMLDivElement>>;

package/dist/composer/caret.d.ts

@@ -1,3 +1,8 @@
+/** hint 左侧的落点：优先用紧邻的文本节点尾，否则退化为「hint 之前的元素偏移」。 */
+export declare function getCaretBeforeHint(hint: HTMLElement): {
+    node: Node;
+    offset: number;
+} | null;
 export declare function getCurrentLine(node: Node | null | undefined, editor: HTMLElement): HTMLDivElement | null;
 export declare function findChipHostBeforeCaret(range: Range): HTMLElement | null;
 export declare function findChipHostAfterCaret(range: Range): HTMLElement | null;
@@ -5,6 +10,75 @@ export declare function normalizeCollapsedCaretAtChipBoundary(range: Range, edit
     node: Node;
     offset: number;
 } | null;
+/**
+ * 给定插入点是否位于 hint「之后」（含落在 hint 内部）。
+ * mousedown 拦截、caret 归位都要用它，因此不含任何 selection 依赖。
+ *
+ * 必须处理**祖先节点**：点在线 / 编辑器留白处时，`caretRangeFromPoint` 常返回
+ * (行容器, n) 甚至 (editor, n)；对这些节点 `compareDocumentPosition` 只会给
+ * CONTAINS / PRECEDING，判断不出「在 hint 之后」。
+ */
+export declare function isPositionAfterHint(node: Node, offset: number, hint: HTMLElement): boolean;
+/**
+ * 点击坐标是否落在 hint 的任一视觉行上（hint 折行时每行一个 rect）。
+ *
+ * hint 是 `pointer-events: none` 的只读派生文本，原生对「点在不可编辑内联元素上」
+ * 的 caret 解析没有稳定契约：可能给到 hint 内部、行首、hint 之后……只要给的不是
+ * 「hint 之后」，就会漏掉拦截，先画一帧错位置再被 selectionchange 拉回。
+ * 坐标命中不依赖这套启发式，是「用户就是想点 hint」最直接的判据。
+ *
+ * 容差 1px：rect 是小数，点击坐标是整数，贴着边缘点也算命中。
+ */
+export declare function isPointOnHint(x: number, y: number, hint: HTMLElement): boolean;
+/** 取点击坐标对应的插入点。Chrome / Safari 用 `caretRangeFromPoint`，Firefox 用 `caretPositionFromPoint`。 */
+export declare function caretRangeFromPoint(x: number, y: number): Range | null;
+/**
+ * caret 是否已经「贴在 hint 左侧」——caret 到 hint 之间除了 chip / 光标锚点
+ * （ZWSP）之外没有别的内容。
+ *
+ * 用于拦截 ArrowRight：再往右一步就会跨到 hint 之后（哪怕只是一帧也会闪），
+ * 所以这里不能只认「紧邻 hint 的文本末尾」，要认「右侧已无正文」的所有位置。
+ */
+export declare function isCaretBeforeHint(range: Range, editor: HTMLElement): boolean;
+/**
+ * 派生 hint 之后不是合法插入点：hint 是只读派生文本，caret 停在它后面会让用户
+ * 误以为能在提示文案末尾继续输入（且视觉上离 chip 很远）。
+ *
+ * 命中时把 caret 拉回 hint 之前 —— 也就是「chip 右侧」这个唯一正确的落点。
+ * 覆盖点击末尾、End、ArrowRight / ArrowDown 落到行尾等所有路径。
+ */
+export declare function normalizeCollapsedCaretBeforeHint(range: Range, editor: HTMLElement): {
+    node: Node;
+    offset: number;
+} | null;
+/**
+ * 查找 caret 所在行的「下一行」是否就是 hint 所在行 —— 用于拦截 ArrowDown：
+ * 该行除 chip + hint 外没有别的内容，唯二落点里只有 hint 之前合法，
+ * 所以直接落到那里，避免原生移动先跳到行尾（hint 之后）再被拉回的一帧闪烁。
+ */
+export declare function isHintOnNextLine(range: Range, editor: HTMLElement): boolean;
+/** caret 是否已经在 hint 所在行上（End 会跳到该行行尾 = hint 之后）。 */
+export declare function isCaretOnHintLine(range: Range, editor: HTMLElement): boolean;
+/**
+ * 上下方向键的落点是否会跑到 hint 上 / 之后。
+ *
+ * 两种形态都要覆盖：
+ * 1. hint 在相邻的 line div（↓ 时判定下一行，↑ 时判定上一行）；
+ * 2. hint 与自己**同一个 line div 内软换行**（长文案折行，demo 的常态）→
+ *    按几何判定：hint 的任一视觉行落在「caret 上/下方一行」的区间里，
+ *    方向键就必然落进提示文案区域（那里没有可编辑落点，浏览器会给到 hint 之后）。
+ *
+ * 不用 `caretRangeFromPoint` 探测：hint 是 contentEditable=false，浏览器会把
+ * 该点解析成它前面最近的编辑位，探测结果反过来是「没越界」，靠不住。
+ *
+ * ↑ 只在 caret **不在** hint 所在行时才判定：同一条上按 ↑ 是正常上移。
+ */
+export declare function wouldArrowCrossHint(range: Range, editor: HTMLElement, direction: 'up' | 'down'): boolean;
+/** 直接取当前 hint 元素的左侧落点（调用方负责写入 selection）。 */
+export declare function caretBeforeHintIn(editor: HTMLElement): {
+    node: Node;
+    offset: number;
+} | null;
 export declare function resolveCaretMove(range: Range, direction: 'left' | 'right' | 'up' | 'down', editor: HTMLElement): {
     node: Node;
     offset: number;

package/dist/composer/caret.js

@@ -1,4 +1,4 @@
-import { createLineRoot, ensureLineRoots as ensureLineRootsInUtils, getCurrentLineRoot, isLineRoot, LINE_ATTR_NAME, stripInvisibleChars, ZWSP } from "./utils";
+import { COMPOSER_HINT_SELECTOR, createLineRoot, ensureLineRoots as ensureLineRootsInUtils, getCurrentLineRoot, isLineRoot, LINE_ATTR_NAME, stripInvisibleChars, ZWSP } from "./utils";
 var CHIP_SELECTOR = '[data-odn-composer-chip-host],[data-mention-id]';
 var isChipHost = function isChipHost(node) {
   return !!node && node.nodeType === Node.ELEMENT_NODE && node instanceof HTMLElement && (node.hasAttribute('data-odn-composer-chip-host') || node.dataset.mentionId !== undefined);
@@ -120,10 +120,38 @@ var caretAfterNode = function caretAfterNode(target) {
   var idx = childIndex(target);
   return createTextCaretAtBoundary(parent, idx + 1, 'right');
 };
+
+/** hint 左侧的落点：优先用紧邻的文本节点尾，否则退化为「hint 之前的元素偏移」。 */
+export function getCaretBeforeHint(hint) {
+  var _parent$childNodes2;
+  var parent = hint.parentNode;
+  if (!parent) return null;
+  var idx = childIndex(hint);
+  var prev = (_parent$childNodes2 = parent.childNodes[idx - 1]) !== null && _parent$childNodes2 !== void 0 ? _parent$childNodes2 : null;
+  if (prev && prev.nodeType === Node.TEXT_NODE) {
+    var _prev$textContent;
+    return {
+      node: prev,
+      offset: ((_prev$textContent = prev.textContent) !== null && _prev$textContent !== void 0 ? _prev$textContent : '').length
+    };
+  }
+  return {
+    node: parent,
+    offset: idx
+  };
+}
 var lineStartCaret = function lineStartCaret(line) {
   return createTextCaretAtBoundary(line, 0, 'right');
 };
 var lineEndCaret = function lineEndCaret(line) {
+  /* 行尾是派生 hint 时，「行尾」不是合法落点：hint 之后不允许停 caret。
+   * 若直接走 createTextCaretAtBoundary，会因为行尾没有 text 节点而在 hint
+   * 之后新建锚点 —— 跨行移动（← 从下一行行首回来）正好命中这条路径。 */
+  var hint = line.querySelector(COMPOSER_HINT_SELECTOR);
+  if (hint && hint.parentElement === line) {
+    var beforeHint = getCaretBeforeHint(hint);
+    if (beforeHint) return beforeHint;
+  }
   return createTextCaretAtBoundary(line, line.childNodes.length, 'left');
 };
 var hasContentBeforeCaretInLine = function hasContentBeforeCaretInLine(range, line) {
@@ -231,6 +259,184 @@ export function normalizeCollapsedCaretAtChipBoundary(range, editor) {
   var prefer = leftChip && !rightChip ? 'right' : 'left';
   return createTextCaretAtBoundary(node, safeOffset, prefer);
 }
+
+/**
+ * 给定插入点是否位于 hint「之后」（含落在 hint 内部）。
+ * mousedown 拦截、caret 归位都要用它，因此不含任何 selection 依赖。
+ *
+ * 必须处理**祖先节点**：点在线 / 编辑器留白处时，`caretRangeFromPoint` 常返回
+ * (行容器, n) 甚至 (editor, n)；对这些节点 `compareDocumentPosition` 只会给
+ * CONTAINS / PRECEDING，判断不出「在 hint 之后」。
+ */
+export function isPositionAfterHint(node, offset, hint) {
+  if (node === hint) return offset > 0;
+  if (hint.contains(node)) return true;
+  if (node.contains(hint)) {
+    var child = hint;
+    while (child.parentNode && child.parentNode !== node) {
+      child = child.parentNode;
+    }
+    if (child.parentNode !== node) return false;
+    return offset > childIndex(child);
+  }
+  return !!(hint.compareDocumentPosition(node) & Node.DOCUMENT_POSITION_FOLLOWING);
+}
+
+/**
+ * 点击坐标是否落在 hint 的任一视觉行上（hint 折行时每行一个 rect）。
+ *
+ * hint 是 `pointer-events: none` 的只读派生文本，原生对「点在不可编辑内联元素上」
+ * 的 caret 解析没有稳定契约：可能给到 hint 内部、行首、hint 之后……只要给的不是
+ * 「hint 之后」，就会漏掉拦截，先画一帧错位置再被 selectionchange 拉回。
+ * 坐标命中不依赖这套启发式，是「用户就是想点 hint」最直接的判据。
+ *
+ * 容差 1px：rect 是小数，点击坐标是整数，贴着边缘点也算命中。
+ */
+export function isPointOnHint(x, y, hint) {
+  return Array.from(hint.getClientRects()).some(function (rect) {
+    return x >= rect.left - 1 && x <= rect.right + 1 && y >= rect.top - 1 && y <= rect.bottom + 1;
+  });
+}
+
+/** 取点击坐标对应的插入点。Chrome / Safari 用 `caretRangeFromPoint`，Firefox 用 `caretPositionFromPoint`。 */
+export function caretRangeFromPoint(x, y) {
+  var _doc$caretPositionFro;
+  var doc = document;
+  if (typeof doc.caretRangeFromPoint === 'function') {
+    return doc.caretRangeFromPoint(x, y);
+  }
+  var pos = (_doc$caretPositionFro = doc.caretPositionFromPoint) === null || _doc$caretPositionFro === void 0 ? void 0 : _doc$caretPositionFro.call(doc, x, y);
+  if (!pos) return null;
+  var range = document.createRange();
+  range.setStart(pos.offsetNode, pos.offset);
+  range.collapse(true);
+  return range;
+}
+
+/**
+ * caret 是否已经「贴在 hint 左侧」——caret 到 hint 之间除了 chip / 光标锚点
+ * （ZWSP）之外没有别的内容。
+ *
+ * 用于拦截 ArrowRight：再往右一步就会跨到 hint 之后（哪怕只是一帧也会闪），
+ * 所以这里不能只认「紧邻 hint 的文本末尾」，要认「右侧已无正文」的所有位置。
+ */
+export function isCaretBeforeHint(range, editor) {
+  if (!range.collapsed) return false;
+  var hint = editor.querySelector(COMPOSER_HINT_SELECTOR);
+  if (!hint || !editor.contains(range.startContainer)) return false;
+  if (isPositionAfterHint(range.startContainer, range.startOffset, hint)) {
+    return false;
+  }
+  var between = document.createRange();
+  between.setStart(range.startContainer, range.startOffset);
+  between.setEndBefore(hint);
+  var hasVisibleText = stripInvisibleChars(between.toString()).replace(/\n/g, '') !== '';
+  if (hasVisibleText) return false;
+  return between.cloneContents().querySelector(CHIP_SELECTOR) === null;
+}
+
+/**
+ * 派生 hint 之后不是合法插入点：hint 是只读派生文本，caret 停在它后面会让用户
+ * 误以为能在提示文案末尾继续输入（且视觉上离 chip 很远）。
+ *
+ * 命中时把 caret 拉回 hint 之前 —— 也就是「chip 右侧」这个唯一正确的落点。
+ * 覆盖点击末尾、End、ArrowRight / ArrowDown 落到行尾等所有路径。
+ */
+export function normalizeCollapsedCaretBeforeHint(range, editor) {
+  var _hint$parentElement;
+  if (!range.collapsed) return null;
+  if (!editor.contains(range.startContainer)) return null;
+  var hint = editor.querySelector(COMPOSER_HINT_SELECTOR);
+  var hintLine = (_hint$parentElement = hint === null || hint === void 0 ? void 0 : hint.parentElement) !== null && _hint$parentElement !== void 0 ? _hint$parentElement : null;
+  if (!hint || !hintLine) return null;
+  /* 只处理「hint 所在行」上的 caret。chip 之后允许存在空行（用户按 Enter
+   * 留了一行又把内容删光），那种情况下 caret 在别的行上，绝不能被拽回
+   * hint 这一行。 */
+  if (getCurrentLine(range.startContainer, editor) !== hintLine) return null;
+  if (!isPositionAfterHint(range.startContainer, range.startOffset, hint)) {
+    return null;
+  }
+  return getCaretBeforeHint(hint);
+}
+
+/**
+ * 查找 caret 所在行的「下一行」是否就是 hint 所在行 —— 用于拦截 ArrowDown：
+ * 该行除 chip + hint 外没有别的内容，唯二落点里只有 hint 之前合法，
+ * 所以直接落到那里，避免原生移动先跳到行尾（hint 之后）再被拉回的一帧闪烁。
+ */
+export function isHintOnNextLine(range, editor) {
+  var _hint$parentElement2;
+  var hint = editor.querySelector(COMPOSER_HINT_SELECTOR);
+  var hintLine = (_hint$parentElement2 = hint === null || hint === void 0 ? void 0 : hint.parentElement) !== null && _hint$parentElement2 !== void 0 ? _hint$parentElement2 : null;
+  if (!hint || !hintLine) return false;
+  var currentLine = getCurrentLine(range.startContainer, editor);
+  return !!currentLine && currentLine.nextElementSibling === hintLine;
+}
+
+/** caret 是否已经在 hint 所在行上（End 会跳到该行行尾 = hint 之后）。 */
+export function isCaretOnHintLine(range, editor) {
+  var _hint$parentElement3;
+  var hint = editor.querySelector(COMPOSER_HINT_SELECTOR);
+  var hintLine = (_hint$parentElement3 = hint === null || hint === void 0 ? void 0 : hint.parentElement) !== null && _hint$parentElement3 !== void 0 ? _hint$parentElement3 : null;
+  if (!hint || !hintLine) return false;
+  return getCurrentLine(range.startContainer, editor) === hintLine;
+}
+
+/**
+ * 上下方向键的落点是否会跑到 hint 上 / 之后。
+ *
+ * 两种形态都要覆盖：
+ * 1. hint 在相邻的 line div（↓ 时判定下一行，↑ 时判定上一行）；
+ * 2. hint 与自己**同一个 line div 内软换行**（长文案折行，demo 的常态）→
+ *    按几何判定：hint 的任一视觉行落在「caret 上/下方一行」的区间里，
+ *    方向键就必然落进提示文案区域（那里没有可编辑落点，浏览器会给到 hint 之后）。
+ *
+ * 不用 `caretRangeFromPoint` 探测：hint 是 contentEditable=false，浏览器会把
+ * 该点解析成它前面最近的编辑位，探测结果反过来是「没越界」，靠不住。
+ *
+ * ↑ 只在 caret **不在** hint 所在行时才判定：同一条上按 ↑ 是正常上移。
+ */
+export function wouldArrowCrossHint(range, editor, direction) {
+  var _getCurrentLine$getBo, _getCurrentLine;
+  if (!range.collapsed) return false;
+  var hint = editor.querySelector(COMPOSER_HINT_SELECTOR);
+  if (!hint) return false;
+  if (direction === 'down' && isHintOnNextLine(range, editor)) return true;
+  if (direction === 'up' && isCaretOnHintLine(range, editor)) return false;
+  var hintRects = Array.from(hint.getClientRects());
+  if (hintRects.length === 0) return false;
+
+  /* 空行 / 元素偏移处的 collapsed range，getBoundingClientRect 可能全 0，
+   * 这时退化用所在行的盒子作为参照。 */
+  var rangeRect = range.getBoundingClientRect();
+  var lineRect = rangeRect.height ? null : (_getCurrentLine$getBo = (_getCurrentLine = getCurrentLine(range.startContainer, editor)) === null || _getCurrentLine === void 0 ? void 0 : _getCurrentLine.getBoundingClientRect()) !== null && _getCurrentLine$getBo !== void 0 ? _getCurrentLine$getBo : null;
+  var rect = rangeRect.height || !lineRect ? {
+    top: rangeRect.top,
+    bottom: rangeRect.bottom
+  } : {
+    top: lineRect.top,
+    bottom: lineRect.bottom
+  };
+  var lineHeight = rangeRect.height || (lineRect === null || lineRect === void 0 ? void 0 : lineRect.height) || 0 || parseFloat(getComputedStyle(editor).lineHeight) || 24;
+  if (direction === 'down') {
+    var _bandTop = rect.bottom;
+    var _bandBottom = rect.bottom + lineHeight;
+    return hintRects.some(function (r) {
+      return r.top <= _bandBottom + 1 && r.bottom > _bandTop + 1;
+    });
+  }
+  var bandTop = rect.top - lineHeight;
+  var bandBottom = rect.top;
+  return hintRects.some(function (r) {
+    return r.top <= bandBottom && r.bottom >= bandTop + 1;
+  });
+}
+
+/** 直接取当前 hint 元素的左侧落点（调用方负责写入 selection）。 */
+export function caretBeforeHintIn(editor) {
+  var hint = editor.querySelector(COMPOSER_HINT_SELECTOR);
+  return hint ? getCaretBeforeHint(hint) : null;
+}
 export function resolveCaretMove(range, direction, editor) {
   if (!editor.contains(range.startContainer)) return null;
   if (direction === 'left') {

package/dist/composer/editor.d.ts

@@ -73,10 +73,11 @@ export interface ComposerEditorProps {
      * 仅当 trigger 处于活动态（triggerRef.current 非空）时调用：
      * 把 ↑↓ Enter Esc Tab 等导航键先丢给父组件让它驱动浮层选择。
      * - 返回 `true` → editor 视为父已处理，不再走自身换行 / 提交逻辑
-     * - 返回 `false / undefined` → editor 走原默认（onPressEnter / 换行 / 删 chip 等）
+     * - 返回 `false / undefined` → editor 走原默认（onPressEnter / 换行 / 删 chip / Tab 采纳 hint 等）
      *
-     * 父组件如需 preventDefault，请在 handler 内自己调用——editor 不会替父代劳，
-     * 避免某些导航键（如 Tab）在父决定让默认通过时误吃。
+     * 带修饰键的 `Tab`（Shift+Tab 反向焦点、Ctrl/Cmd+Tab 切窗口）不转发，
+     * 保持浏览器默认。父组件如需 preventDefault，请在 handler 内自己调用——
+     * editor 不会替父代劳。
      */
     onTriggerKeyDown?: (e: React.KeyboardEvent<HTMLDivElement>) => boolean | void;
     /**