@neut/ui 0.0.16 → 0.0.18

package/dist/components/message-scroller/message-scroller.measure.js

@@ -0,0 +1,21 @@
+//#region src/components/message-scroller/message-scroller.measure.ts
+function e(e) {
+	let t = Number.parseFloat(e);
+	return Number.isFinite(t) ? t : 0;
+}
+function t(t) {
+	let n = window.getComputedStyle(t);
+	return {
+		start: e(n.paddingBlockStart || n.paddingTop),
+		end: e(n.paddingBlockEnd || n.paddingBottom)
+	};
+}
+function n(t) {
+	if (!t) return 0;
+	let n = window.getComputedStyle(t);
+	return e(n.rowGap === "normal" ? n.gap : n.rowGap);
+}
+//#endregion
+export { t as paddingBox, e as parsePx, n as rowGap };
+
+//# sourceMappingURL=message-scroller.measure.js.map

package/dist/components/message-scroller/message-scroller.measure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-scroller.measure.js","names":["parsePx","parsed","value","paddingBox","style","element","rowGap"],"sources":["../../../src/components/message-scroller/message-scroller.measure.ts"],"sourcesContent":["/**\n * MessageScroller 的 CSS 尺寸测量。\n *\n * 单一职责：把 `getComputedStyle` 的字符串值解析成可运算的数字。\n * 不持有信号、不订阅事件、不做滚动决策，因此可以脱离 jsdom 布局限制直接单测。\n */\n\n/** 一个元素在主轴方向上的内边距 */\nexport interface PaddingBox {\n  /** 逻辑块起始内边距（`padding-block-start`，回退到 `padding-top`） */\n  start: number;\n  /** 逻辑块结束内边距（`padding-block-end`，回退到 `padding-bottom`） */\n  end: number;\n}\n\n/** 把 `\"12px\"` 之类的 CSS 长度解析成数字；非法值一律当 0 */\nexport function parsePx(value: string): number {\n  const parsed = Number.parseFloat(value);\n  return Number.isFinite(parsed) ? parsed : 0;\n}\n\n/**\n * 读取元素的块级内边距。\n * 优先用逻辑属性（`paddingBlockStart`），因为它能正确处理书写方向；\n * 不支持时回退到物理属性（`paddingTop`）。\n */\nexport function paddingBox(element: HTMLElement): PaddingBox {\n  const style = window.getComputedStyle(element);\n  return {\n    start: parsePx(style.paddingBlockStart || style.paddingTop),\n    end: parsePx(style.paddingBlockEnd || style.paddingBottom),\n  };\n}\n\n/**\n * 读取容器的行间距。\n * 显式设置过行间距时 `rowGap` 有值，否则它是 `\"normal\"`——此时应读 `gap`\n * 简写（`gap: 8px` 不会展开到 `rowGap`）。\n */\nexport function rowGap(element: HTMLElement | null): number {\n  if (!element) return 0;\n  const style = window.getComputedStyle(element);\n  return parsePx(style.rowGap === \"normal\" ? style.gap : style.rowGap);\n}\n"],"mappings":";AAgBA,SAAgBA,EAAQ,GAAuB;CAC7C,IAAMC,IAAS,OAAO,WAAWC,CAAK;CACtC,OAAO,OAAO,SAASD,CAAM,IAAIA,IAAS;AAC5C;AAOA,SAAgBE,EAAW,GAAkC;CAC3D,IAAMC,IAAQ,OAAO,iBAAiBC,CAAO;CAC7C,OAAO;EACL,OAAOL,EAAQI,EAAM,qBAAqBA,EAAM,UAAU;EAC1D,KAAKJ,EAAQI,EAAM,mBAAmBA,EAAM,aAAa;CAC3D;AACF;AAOA,SAAgBE,EAAO,GAAqC;CAC1D,IAAI,CAACD,GAAS,OAAO;CACrB,IAAMD,IAAQ,OAAO,iBAAiBC,CAAO;CAC7C,OAAOL,EAAQI,EAAM,WAAW,WAAWA,EAAM,MAAMA,EAAM,MAAM;AACrE"}

package/dist/components/message-scroller/message-scroller.scroll-state.d.ts

@@ -0,0 +1,54 @@
+import { Accessor } from 'solid-js';
+import { MessageScrollerProviderProps } from './message-scroller.types';
+type EngineOptions = Required<Omit<MessageScrollerProviderProps, "children">>;
+/**
+ * 滚动模式。
+ * - `following-bottom`：跟随实时边缘（新内容自动滚到底）
+ * - `free-scrolling`：读者自己控制位置，内容变化不再抢滚动
+ * - `anchored-to-message`：把某个锚点行固定在阅读线上（新回合锚定）
+ * - `settling-jump`：一次显式跳转后的过渡态
+ */
+export type ScrollMode = "following-bottom" | "free-scrolling" | "anchored-to-message" | "settling-jump";
+export interface ScrollStateOptions {
+    viewport: Accessor<HTMLElement | undefined>;
+    options: () => EngineOptions;
+    /** 内容底部（不含 spacer），由 `dom-measure` 提供 */
+    contentBottom: () => number;
+}
+export interface ScrollState {
+    /** 是否处于"跟随实时边缘"（迁移一律走下面的语义化方法，避免散落的直接赋值） */
+    isFollowing: () => boolean;
+    isAnchored: () => boolean;
+    /** 是否可向两侧滚动（注意：跟随时对外把 `end` 强制为 false） */
+    scrollableStart: Accessor<boolean>;
+    scrollableEnd: Accessor<boolean>;
+    autoscrolling: Accessor<boolean>;
+    setFollowing: () => void;
+    setFree: () => void;
+    anchorTo: () => void;
+    settleJump: () => void;
+    /** 立即计算可滚动状态并按当前位置迁移模式 */
+    commit: () => void;
+    /** 分帧提交（滚动热路径） */
+    schedule: () => void;
+    /** 开启「正在自动滚动」态，到期自动复位 */
+    beginAutoScroll: () => void;
+    /** 关闭该状态并清掉计时器 */
+    endAutoScroll: () => void;
+    /** 滚轮/触摸/键盘滚动：立刻把位置交还读者 */
+    releaseFollow: () => void;
+    dispose: () => void;
+}
+/**
+ * 滚动状态机。
+ *
+ * 单一职责：维护滚动模式与"能否向两侧滚动""是否正在自动滚动"这三个对外状态，
+ * 并按测量结果迁移模式。它不写 `scrollTop`、不做锚定决策——那些是 commands /
+ * anchoring 的事；本模块只回答"现在是什么模式"。
+ *
+ * `mode` 的**唯一写入者**是本模块：外部只能通过 `setFollowing` / `setFree` /
+ * `anchorTo` / `settleJump` 表达意图，`releaseFollow` 与滚动事件带来的迁移
+ * 也收在这里，避免"多个模块各自记住模式"的隐性耦合。
+ */
+export declare function createScrollState(options: ScrollStateOptions): ScrollState;
+export {};

package/dist/components/message-scroller/message-scroller.scroll-state.js

@@ -0,0 +1,74 @@
+import { AT_EDGE_TOLERANCE as e } from "./message-scroller.utils.js";
+import { createSignal as t } from "solid-js";
+//#region src/components/message-scroller/message-scroller.scroll-state.ts
+var n = 180;
+function r(r) {
+	let [i, a] = t(!1), [o, s] = t(!1), [c, l] = t(!1), u = r.options().autoScroll ? "following-bottom" : "free-scrolling", d = 0, f = null, p = null, m = () => {
+		let e = r.viewport();
+		if (!e) return {
+			start: !1,
+			end: !1
+		};
+		let t = r.options().scrollEdgeThreshold, n = r.contentBottom();
+		return {
+			start: e.scrollTop > t,
+			end: n - e.scrollTop - e.clientHeight > t
+		};
+	}, h = (t) => {
+		let n = r.viewport();
+		if (!n) return;
+		let i = n.scrollTop, a = i < d - e;
+		d = i, r.options().autoScroll && !t.end && u !== "settling-jump" && u !== "anchored-to-message" ? u = "following-bottom" : u === "following-bottom" && t.end && a && !c() && (u = "free-scrolling");
+	}, g = () => {
+		let e = m();
+		h(e);
+		let t = u === "following-bottom" ? {
+			...e,
+			end: !1
+		} : e;
+		a(t.start), s(t.end);
+	}, _ = () => {
+		p === null && (p = window.requestAnimationFrame(() => {
+			p = null, g();
+		}));
+	}, v = () => {
+		f !== null && (window.clearTimeout(f), f = null), c() && (l(!1), g());
+	};
+	return {
+		isFollowing: () => u === "following-bottom",
+		isAnchored: () => u === "anchored-to-message",
+		scrollableStart: i,
+		scrollableEnd: o,
+		autoscrolling: c,
+		setFollowing() {
+			u = "following-bottom";
+		},
+		setFree() {
+			u = "free-scrolling";
+		},
+		anchorTo() {
+			u = "anchored-to-message";
+		},
+		settleJump() {
+			u = "settling-jump";
+		},
+		commit: g,
+		schedule: _,
+		beginAutoScroll: () => {
+			f !== null && (window.clearTimeout(f), f = null), c() || (l(!0), g()), f = window.setTimeout(() => {
+				f = null, l(!1), g();
+			}, n);
+		},
+		endAutoScroll: v,
+		releaseFollow() {
+			(u === "following-bottom" || u === "anchored-to-message" || u === "settling-jump") && (v(), u = "free-scrolling");
+		},
+		dispose() {
+			f !== null && (window.clearTimeout(f), f = null), p !== null && (window.cancelAnimationFrame(p), p = null);
+		}
+	};
+}
+//#endregion
+export { r as createScrollState };
+
+//# sourceMappingURL=message-scroller.scroll-state.js.map

package/dist/components/message-scroller/message-scroller.scroll-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-scroller.scroll-state.js","names":["AUTO_SCROLLING_TIMEOUT_MS","createScrollState","scrollableStart","setScrollableStart","createSignal","scrollableEnd","setScrollableEnd","autoscrolling","setAutoscrolling","mode","options","lastScrollTop","autoscrollingTimer","stateFrame","computeScrollable","viewport","threshold","bottom","updateModeFromScroll","top","movedUp","AT_EDGE_TOLERANCE","state","commit","exposed","schedule","endAutoScroll"],"sources":["../../../src/components/message-scroller/message-scroller.scroll-state.ts"],"sourcesContent":["import { createSignal, type Accessor } from \"solid-js\";\nimport type { MessageScrollerProviderProps } from \"./message-scroller.types\";\nimport { AT_EDGE_TOLERANCE } from \"./message-scroller.utils\";\n\ntype EngineOptions = Required<Omit<MessageScrollerProviderProps, \"children\">>;\n\n/**\n * 滚动模式。\n * - `following-bottom`：跟随实时边缘（新内容自动滚到底）\n * - `free-scrolling`：读者自己控制位置，内容变化不再抢滚动\n * - `anchored-to-message`：把某个锚点行固定在阅读线上（新回合锚定）\n * - `settling-jump`：一次显式跳转后的过渡态\n */\nexport type ScrollMode =\n  | \"following-bottom\"\n  | \"free-scrolling\"\n  | \"anchored-to-message\"\n  | \"settling-jump\";\n\n/** 「滚动到最新」后 data-autoscrolling 的持续时间（ms） */\nconst AUTO_SCROLLING_TIMEOUT_MS = 180;\n\nexport interface ScrollStateOptions {\n  viewport: Accessor<HTMLElement | undefined>;\n  options: () => EngineOptions;\n  /** 内容底部（不含 spacer），由 `dom-measure` 提供 */\n  contentBottom: () => number;\n}\n\nexport interface ScrollState {\n  /** 是否处于\"跟随实时边缘\"（迁移一律走下面的语义化方法，避免散落的直接赋值） */\n  isFollowing: () => boolean;\n  isAnchored: () => boolean;\n  /** 是否可向两侧滚动（注意：跟随时对外把 `end` 强制为 false） */\n  scrollableStart: Accessor<boolean>;\n  scrollableEnd: Accessor<boolean>;\n  autoscrolling: Accessor<boolean>;\n\n  setFollowing: () => void;\n  setFree: () => void;\n  anchorTo: () => void;\n  settleJump: () => void;\n\n  /** 立即计算可滚动状态并按当前位置迁移模式 */\n  commit: () => void;\n  /** 分帧提交（滚动热路径） */\n  schedule: () => void;\n  /** 开启「正在自动滚动」态，到期自动复位 */\n  beginAutoScroll: () => void;\n  /** 关闭该状态并清掉计时器 */\n  endAutoScroll: () => void;\n  /** 滚轮/触摸/键盘滚动：立刻把位置交还读者 */\n  releaseFollow: () => void;\n  dispose: () => void;\n}\n\n/**\n * 滚动状态机。\n *\n * 单一职责：维护滚动模式与\"能否向两侧滚动\"\"是否正在自动滚动\"这三个对外状态，\n * 并按测量结果迁移模式。它不写 `scrollTop`、不做锚定决策——那些是 commands /\n * anchoring 的事；本模块只回答\"现在是什么模式\"。\n *\n * `mode` 的**唯一写入者**是本模块：外部只能通过 `setFollowing` / `setFree` /\n * `anchorTo` / `settleJump` 表达意图，`releaseFollow` 与滚动事件带来的迁移\n * 也收在这里，避免\"多个模块各自记住模式\"的隐性耦合。\n */\nexport function createScrollState(options: ScrollStateOptions): ScrollState {\n  const [scrollableStart, setScrollableStart] = createSignal(false);\n  const [scrollableEnd, setScrollableEnd] = createSignal(false);\n  const [autoscrolling, setAutoscrolling] = createSignal(false);\n\n  let mode: ScrollMode = options.options().autoScroll\n    ? \"following-bottom\"\n    : \"free-scrolling\";\n  let lastScrollTop = 0;\n  let autoscrollingTimer: number | null = null;\n  let stateFrame: number | null = null;\n\n  const computeScrollable = () => {\n    const viewport = options.viewport();\n    if (!viewport) return { start: false, end: false };\n\n    const threshold = options.options().scrollEdgeThreshold;\n    const bottom = options.contentBottom();\n    return {\n      start: viewport.scrollTop > threshold,\n      end: bottom - viewport.scrollTop - viewport.clientHeight > threshold,\n    };\n  };\n\n  /** 按当前位置与内容状态迁移模式（滚轮/触摸等意图由 releaseFollow 处理） */\n  const updateModeFromScroll = (state: { start: boolean; end: boolean }) => {\n    const viewport = options.viewport();\n    if (!viewport) return;\n\n    const top = viewport.scrollTop;\n    const movedUp = top < lastScrollTop - AT_EDGE_TOLERANCE;\n    lastScrollTop = top;\n\n    if (\n      options.options().autoScroll &&\n      !state.end &&\n      mode !== \"settling-jump\" &&\n      mode !== \"anchored-to-message\"\n    ) {\n      mode = \"following-bottom\";\n    } else if (\n      mode === \"following-bottom\" &&\n      state.end &&\n      movedUp &&\n      !autoscrolling()\n    ) {\n      // 读者主动往回滚：交出控制权\n      mode = \"free-scrolling\";\n    }\n  };\n\n  const commit = () => {\n    const state = computeScrollable();\n    updateModeFromScroll(state);\n    // 跟随输出时对 UI 隐藏「还能向下滚」——按钮不出现，直到读者回到实时边缘\n    const exposed =\n      mode === \"following-bottom\" ? { ...state, end: false } : state;\n    setScrollableStart(exposed.start);\n    setScrollableEnd(exposed.end);\n  };\n\n  const schedule = () => {\n    if (stateFrame !== null) return;\n    stateFrame = window.requestAnimationFrame(() => {\n      stateFrame = null;\n      commit();\n    });\n  };\n\n  const endAutoScroll = () => {\n    if (autoscrollingTimer !== null) {\n      window.clearTimeout(autoscrollingTimer);\n      autoscrollingTimer = null;\n    }\n    // 与 beginAutoScroll 对称：值真的变了才提交一次状态\n    if (autoscrolling()) {\n      setAutoscrolling(false);\n      commit();\n    }\n  };\n\n  const beginAutoScroll = () => {\n    if (autoscrollingTimer !== null) {\n      window.clearTimeout(autoscrollingTimer);\n      autoscrollingTimer = null;\n    }\n    if (!autoscrolling()) {\n      setAutoscrolling(true);\n      commit();\n    }\n    autoscrollingTimer = window.setTimeout(() => {\n      autoscrollingTimer = null;\n      setAutoscrolling(false);\n      commit();\n    }, AUTO_SCROLLING_TIMEOUT_MS);\n  };\n\n  return {\n    isFollowing: () => mode === \"following-bottom\",\n    isAnchored: () => mode === \"anchored-to-message\",\n    scrollableStart,\n    scrollableEnd,\n    autoscrolling,\n    setFollowing() {\n      mode = \"following-bottom\";\n    },\n    setFree() {\n      mode = \"free-scrolling\";\n    },\n    anchorTo() {\n      mode = \"anchored-to-message\";\n    },\n    settleJump() {\n      mode = \"settling-jump\";\n    },\n    commit,\n    schedule,\n    beginAutoScroll,\n    endAutoScroll,\n    releaseFollow() {\n      // 只有\"还在跟随/锚定/过渡\"时才需要让位；已经自由滚动就不动\n      if (\n        mode === \"following-bottom\" ||\n        mode === \"anchored-to-message\" ||\n        mode === \"settling-jump\"\n      ) {\n        endAutoScroll();\n        mode = \"free-scrolling\";\n      }\n    },\n    dispose() {\n      if (autoscrollingTimer !== null) {\n        window.clearTimeout(autoscrollingTimer);\n        autoscrollingTimer = null;\n      }\n      if (stateFrame !== null) {\n        window.cancelAnimationFrame(stateFrame);\n        stateFrame = null;\n      }\n    },\n  };\n}\n"],"mappings":";;;AAoBA,IAAMA,IAA4B;AA+ClC,SAAgBC,EAAkB,GAA0C;CAC1E,IAAM,CAACC,GAAiBC,KAAsBC,EAAa,EAAK,GAC1D,CAACC,GAAeC,KAAoBF,EAAa,EAAK,GACtD,CAACG,GAAeC,KAAoBJ,EAAa,EAAK,GAExDK,IAAmBC,EAAQ,QAAQ,CAAC,CAAC,aACrC,qBACA,kBACAC,IAAgB,GAChBC,IAAoC,MACpCC,IAA4B,MAE1BC,UAA0B;EAC9B,IAAMC,IAAWL,EAAQ,SAAS;EAClC,IAAI,CAACK,GAAU,OAAO;GAAE,OAAO;GAAO,KAAK;EAAM;EAEjD,IAAMC,IAAYN,EAAQ,QAAQ,CAAC,CAAC,qBAC9BO,IAASP,EAAQ,cAAc;EACrC,OAAO;GACL,OAAOK,EAAS,YAAYC;GAC5B,KAAKC,IAASF,EAAS,YAAYA,EAAS,eAAeC;EAC7D;CACF,GAGME,KAAwB,MAA4C;EACxE,IAAMH,IAAWL,EAAQ,SAAS;EAClC,IAAI,CAACK,GAAU;EAEf,IAAMI,IAAMJ,EAAS,WACfK,IAAUD,IAAMR,IAAgBU;EAGtC,AAFA,IAAgBF,GAGdT,EAAQ,QAAQ,CAAC,CAAC,cAClB,CAACY,EAAM,OACPb,MAAS,mBACTA,MAAS,wBAET,IAAO,qBAEPA,MAAS,sBACTa,EAAM,OACNF,KACA,CAACb,EAAc,MAGf,IAAO;CAEX,GAEMgB,UAAe;EACnB,IAAMD,IAAQR,EAAkB;EAChC,EAAqBQ,CAAK;EAE1B,IAAME,IACJf,MAAS,qBAAqB;GAAE,GAAGa;GAAO,KAAK;EAAM,IAAIA;EAE3D,AADAnB,EAAmBqB,EAAQ,KAAK,GAChClB,EAAiBkB,EAAQ,GAAG;CAC9B,GAEMC,UAAiB;EACrB,AAAIZ,MAAe,SACnB,IAAa,OAAO,4BAA4B;GAE9C,AADA,IAAa,MACbU,EAAO;EACT,CAAC;CACH,GAEMG,UAAsB;EAM1B,AALId,MAAuB,SACzB,OAAO,aAAaA,CAAkB,GACtC,IAAqB,OAGnBL,EAAc,MAChBC,EAAiB,EAAK,GACtBe,EAAO;CAEX;CAkBA,OAAO;EACL,mBAAmBd,MAAS;EAC5B,kBAAkBA,MAAS;EAC3B;EACA;EACA;EACA,eAAe;GACb,IAAO;EACT;EACA,UAAU;GACR,IAAO;EACT;EACA,WAAW;GACT,IAAO;EACT;EACA,aAAa;GACX,IAAO;EACT;EACA;EACA;EACA,uBApC4B;GAS5B,AARIG,MAAuB,SACzB,OAAO,aAAaA,CAAkB,GACtC,IAAqB,OAElBL,EAAc,MACjBC,EAAiB,EAAI,GACrBe,EAAO,IAET,IAAqB,OAAO,iBAAiB;IAG3C,AAFA,IAAqB,MACrBf,EAAiB,EAAK,GACtBe,EAAO;GACT,GAAGvB,CAAyB;EAC9B;EAuBE;EACA,gBAAgB;GAEd,CACES,MAAS,sBACTA,MAAS,yBACTA,MAAS,qBAETiB,EAAc,GACd,IAAO;EAEX;EACA,UAAU;GAKR,AAJId,MAAuB,SACzB,OAAO,aAAaA,CAAkB,GACtC,IAAqB,OAEnBC,MAAe,SACjB,OAAO,qBAAqBA,CAAU,GACtC,IAAa;EAEjB;CACF;AACF"}

package/dist/components/message-scroller/message-scroller.scroll-target.d.ts

@@ -0,0 +1,27 @@
+import { MessageScrollerScrollOptions } from './message-scroller.types';
+import { PaddingBox } from './message-scroller.measure';
+/** 计算滚动目标所需的输入（都是测量好的数字，便于单独测试各分支） */
+export interface TargetTopInput {
+    /** 行相对滚动内容顶部的偏移 */
+    itemTop: number;
+    /** 行自身高度 */
+    itemHeight: number;
+    /** 视口可视高度 */
+    viewportHeight: number;
+    /** 当前 `scrollTop`（`align: "nearest"` 需要） */
+    scrollTop: number;
+    /** 内容区上下内边距 */
+    padding: PaddingBox;
+    /** 额外留白（scrollMargin + peek） */
+    margin: number;
+}
+/**
+ * 按 `align` 计算目标 `scrollTop`：
+ * - `start`（默认）：行顶对齐可视区顶部（减内边距与留白）
+ * - `center`：行居中于可视区
+ * - `end`：行底对齐可视区底部
+ * - `nearest`：完全可见则不动，否则滚到最近的一侧
+ */
+export declare function computeTargetTop(align: MessageScrollerScrollOptions["align"], { itemTop, itemHeight, viewportHeight, scrollTop, padding, margin, }: TargetTopInput): number;
+/** 便捷包装：直接从元素读取尺寸（引擎的热路径用这个） */
+export declare function targetTopFor(element: HTMLElement, command: MessageScrollerScrollOptions | undefined, margin: number, viewport: HTMLElement, content: HTMLElement | undefined, itemOffsetTop: (el: HTMLElement) => number): number;

package/dist/components/message-scroller/message-scroller.scroll-target.js

@@ -0,0 +1,33 @@
+import { paddingBox as e } from "./message-scroller.measure.js";
+//#region src/components/message-scroller/message-scroller.scroll-target.ts
+function t(e, { itemTop: t, itemHeight: n, viewportHeight: r, scrollTop: i, padding: a, margin: o }) {
+	switch (e ?? "start") {
+		case "center": {
+			let e = Math.max(0, r - a.start - a.end);
+			return t - a.start - (e - n) / 2 - o;
+		}
+		case "end": return t - r + n + a.end + o;
+		case "nearest": {
+			let e = t + n, s = i + a.start, c = i + r - a.end;
+			return t >= s && e <= c ? i : t < s ? t - a.start - o : e - r + a.end + o;
+		}
+		default: return t - a.start - o;
+	}
+}
+function n(n, r, i, a, o, s) {
+	return t(r?.align, {
+		itemTop: s(n),
+		itemHeight: n.getBoundingClientRect().height,
+		viewportHeight: a.clientHeight,
+		scrollTop: a.scrollTop,
+		padding: o ? e(o) : {
+			start: 0,
+			end: 0
+		},
+		margin: i
+	});
+}
+//#endregion
+export { t as computeTargetTop, n as targetTopFor };
+
+//# sourceMappingURL=message-scroller.scroll-target.js.map

package/dist/components/message-scroller/message-scroller.scroll-target.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-scroller.scroll-target.js","names":["computeTargetTop","align","visible","viewportHeight","padding","itemTop","itemHeight","margin","bottom","viewTop","scrollTop","viewBottom","targetTopFor","command","itemOffsetTop","element","viewport","content","paddingBox"],"sources":["../../../src/components/message-scroller/message-scroller.scroll-target.ts"],"sourcesContent":["/**\n * MessageScroller 的滚动目标计算。\n *\n * 单一职责：已知行与视口的测量值时，算出应该滚到的 `scrollTop`。\n * 纯函数（不读信号、不写 DOM），因此四种 `align` 的每个分支都能单独断言。\n */\n\nimport type { MessageScrollerScrollOptions } from \"./message-scroller.types\";\nimport { type PaddingBox, paddingBox } from \"./message-scroller.measure\";\n\n/** 计算滚动目标所需的输入（都是测量好的数字，便于单独测试各分支） */\nexport interface TargetTopInput {\n  /** 行相对滚动内容顶部的偏移 */\n  itemTop: number;\n  /** 行自身高度 */\n  itemHeight: number;\n  /** 视口可视高度 */\n  viewportHeight: number;\n  /** 当前 `scrollTop`（`align: \"nearest\"` 需要） */\n  scrollTop: number;\n  /** 内容区上下内边距 */\n  padding: PaddingBox;\n  /** 额外留白（scrollMargin + peek） */\n  margin: number;\n}\n\n/**\n * 按 `align` 计算目标 `scrollTop`：\n * - `start`（默认）：行顶对齐可视区顶部（减内边距与留白）\n * - `center`：行居中于可视区\n * - `end`：行底对齐可视区底部\n * - `nearest`：完全可见则不动，否则滚到最近的一侧\n */\nexport function computeTargetTop(\n  align: MessageScrollerScrollOptions[\"align\"],\n  {\n    itemTop,\n    itemHeight,\n    viewportHeight,\n    scrollTop,\n    padding,\n    margin,\n  }: TargetTopInput,\n): number {\n  switch (align ?? \"start\") {\n    case \"center\": {\n      const visible = Math.max(0, viewportHeight - padding.start - padding.end);\n      return itemTop - padding.start - (visible - itemHeight) / 2 - margin;\n    }\n    case \"end\":\n      return itemTop - viewportHeight + itemHeight + padding.end + margin;\n    case \"nearest\": {\n      const bottom = itemTop + itemHeight;\n      const viewTop = scrollTop + padding.start;\n      const viewBottom = scrollTop + viewportHeight - padding.end;\n      if (itemTop >= viewTop && bottom <= viewBottom) return scrollTop;\n      if (itemTop < viewTop) return itemTop - padding.start - margin;\n      return bottom - viewportHeight + padding.end + margin;\n    }\n    default:\n      return itemTop - padding.start - margin;\n  }\n}\n\n/** 便捷包装：直接从元素读取尺寸（引擎的热路径用这个） */\nexport function targetTopFor(\n  element: HTMLElement,\n  command: MessageScrollerScrollOptions | undefined,\n  margin: number,\n  viewport: HTMLElement,\n  content: HTMLElement | undefined,\n  itemOffsetTop: (el: HTMLElement) => number,\n): number {\n  return computeTargetTop(command?.align, {\n    itemTop: itemOffsetTop(element),\n    itemHeight: element.getBoundingClientRect().height,\n    viewportHeight: viewport.clientHeight,\n    scrollTop: viewport.scrollTop,\n    padding: content ? paddingBox(content) : { start: 0, end: 0 },\n    margin,\n  });\n}\n"],"mappings":";;AAiCA,SAAgBA,EACd,GACA,EACE,YACA,eACA,mBACA,cACA,YACA,aAEM;CACR,QAAQC,KAAS,SAAjB;EACE,KAAK,UAAU;GACb,IAAMC,IAAU,KAAK,IAAI,GAAGC,IAAiBC,EAAQ,QAAQA,EAAQ,GAAG;GACxE,OAAOC,IAAUD,EAAQ,SAASF,IAAUI,KAAc,IAAIC;EAChE;EACA,KAAK,OACH,OAAOF,IAAUF,IAAiBG,IAAaF,EAAQ,MAAMG;EAC/D,KAAK,WAAW;GACd,IAAMC,IAASH,IAAUC,GACnBG,IAAUC,IAAYN,EAAQ,OAC9BO,IAAaD,IAAYP,IAAiBC,EAAQ;GAGxD,OAFIC,KAAWI,KAAWD,KAAUG,IAAmBD,IACnDL,IAAUI,IAAgBJ,IAAUD,EAAQ,QAAQG,IACjDC,IAASL,IAAiBC,EAAQ,MAAMG;EACjD;EACA,SACE,OAAOF,IAAUD,EAAQ,QAAQG;CACrC;AACF;AAGA,SAAgBK,EACd,GACA,GACA,GACA,GACA,GACA,GACQ;CACR,OAAOZ,EAAiBa,GAAS,OAAO;EACtC,SAASC,EAAcC,CAAO;EAC9B,YAAYA,EAAQ,sBAAsB,CAAC,CAAC;EAC5C,gBAAgBC,EAAS;EACzB,WAAWA,EAAS;EACpB,SAASC,IAAUC,EAAWD,CAAO,IAAI;GAAE,OAAO;GAAG,KAAK;EAAE;EAC5D;CACF,CAAC;AACH"}

package/dist/components/message-scroller/message-scroller.types.d.ts

@@ -0,0 +1,92 @@
+import { Accessor, ParentProps } from 'solid-js';
+import { BaseProps, PolymorphicProps } from '../../types';
+export type MessageScrollerDefaultScrollPosition = "start" | "end" | "last-anchor";
+export type MessageScrollerButtonDirection = "start" | "end";
+export type MessageScrollerScrollAlign = "start" | "center" | "end" | "nearest";
+/** 命令选项：对齐方式、原生滚动行为、本次命令覆盖的 scrollMargin */
+export interface MessageScrollerScrollOptions {
+    align?: MessageScrollerScrollAlign;
+    behavior?: ScrollBehavior;
+    scrollMargin?: number;
+}
+/** useMessageScrollerScrollable 的取值形态 */
+export interface MessageScrollerScrollable {
+    start: boolean;
+    end: boolean;
+}
+/** useMessageScrollerVisibility 的取值形态 */
+export interface MessageScrollerVisibilityState {
+    currentAnchorId: string | null;
+    visibleMessageIds: string[];
+}
+export interface MessageScrollerProviderProps extends ParentProps {
+    /** 读者位于实时边缘时，内容增长自动跟随（滚动离开后自动让位），默认 false */
+    autoScroll?: boolean;
+    /** 打开时停在何处，默认 "end"；"last-anchor" 无锚点或该回合放得下时回退到 "end" */
+    defaultScrollPosition?: MessageScrollerDefaultScrollPosition;
+    /** 距任一边缘多少像素仍算「在起点/终点」，默认 8 */
+    scrollEdgeThreshold?: number;
+    /** 新回合锚定时在 scrollMargin 之外额外保留的上一项高度（像素），默认 64 */
+    scrollPreviousItemPeek?: number;
+    /** scrollToMessage / 可见性 / 程序化目标的对齐边距（像素），默认 0 */
+    scrollMargin?: number;
+}
+export interface MessageScrollerItemEntry {
+    id?: string;
+    element: HTMLElement;
+}
+export interface MessageScrollerContextValue {
+    viewport: Accessor<HTMLElement | undefined>;
+    setViewport: (el: HTMLElement | undefined) => void;
+    content: Accessor<HTMLElement | undefined>;
+    setContent: (el: HTMLElement | undefined) => void;
+    setSpacer: (el: HTMLElement | undefined) => void;
+    registerItem: (entry: MessageScrollerItemEntry) => () => void;
+    /** 上方插入历史时是否保持可见行（Viewport 的 prop） */
+    preserveScrollOnPrepend: Accessor<boolean>;
+    setPreserveScrollOnPrepend: (value: boolean) => void;
+    /** 是否还能向上/向下滚动（供滚动控件与自定义 UI） */
+    scrollableStart: Accessor<boolean>;
+    scrollableEnd: Accessor<boolean>;
+    /** 正在执行「滚动到最新消息」的程序化滚动（对应 data-autoscrolling） */
+    autoscrolling: Accessor<boolean>;
+    /** 初始定位尚未应用（对应 data-pending-scroll） */
+    pendingScroll: Accessor<boolean>;
+    scrollToStart: (options?: MessageScrollerScrollOptions) => boolean;
+    scrollToEnd: (options?: MessageScrollerScrollOptions) => boolean;
+    /** 目标未挂载且可排队（会话为空）时返回 true，其余失败返回 false */
+    scrollToMessage: (messageId: string, options?: MessageScrollerScrollOptions) => boolean;
+    /** 当前锚定的回合 id（阅读行之上最后一个 scrollAnchor），无则 null */
+    currentAnchorId: Accessor<string | null>;
+    /** 当前可见的消息 id（文档顺序） */
+    visibleMessageIds: Accessor<string[]>;
+    /** 订阅可见性；首个订阅者开启 IntersectionObserver，最后一个移除时断开 */
+    subscribeVisibility: () => () => void;
+    options: Accessor<Required<Omit<MessageScrollerProviderProps, "children">>>;
+}
+export interface MessageScrollerVisibilityValue {
+    currentAnchorId: Accessor<string | null>;
+    visibleMessageIds: Accessor<string[]>;
+}
+export type MessageScrollerProps = PolymorphicProps<"div", BaseProps, false>;
+export type MessageScrollerViewportProps = PolymorphicProps<"div", BaseProps & {
+    "aria-label"?: string;
+    /** 上方插入历史时保持可见行，默认 true */
+    preserveScrollOnPrepend?: boolean;
+}, false>;
+export type MessageScrollerContentProps = PolymorphicProps<"div", BaseProps & {
+    "aria-busy"?: boolean;
+    /** 内部 spacer 的类名（仅为锚定行腾出可视空间，aria-hidden） */
+    spacerClassName?: string;
+}, false>;
+export type MessageScrollerItemProps = PolymorphicProps<"div", BaseProps & {
+    messageId?: string;
+    scrollAnchor?: boolean;
+}, false>;
+export type MessageScrollerButtonProps = PolymorphicProps<"button", BaseProps & {
+    direction?: MessageScrollerButtonDirection;
+    /** 原生滚动行为，默认 "smooth" */
+    behavior?: ScrollBehavior;
+    variant?: string;
+    size?: string;
+}>;

package/dist/components/message-scroller/message-scroller.utils.d.ts

@@ -0,0 +1,14 @@
+import { Accessor } from 'solid-js';
+/**
+ * 滚动位置比较容差（0.5px）。
+ *
+ * 用于"是否已到达某个位置""锚点是否越过阅读线"这类比较：浏览器的小数滚动位置
+ * 不可能精确相等，需要一个统一的容差，否则会出现"差 0.3px 算没到"的抖动。
+ */
+export declare const AT_EDGE_TOLERANCE = 0.5;
+/**
+ * `data-scrollable` 的取值：可向哪个边缘滚动，空格分隔的 token 列表
+ * （`"start"` / `"end"` / `"start end"`），都不可滚时为 `undefined`
+ * （可用 `[data-scrollable~="end"]` 查询单个方向，缺失表示内容放得下）。
+ */
+export declare function scrollableData(start: Accessor<boolean>, end: Accessor<boolean>): string | undefined;

package/dist/components/message-scroller/message-scroller.utils.js

@@ -0,0 +1,10 @@
+//#region src/components/message-scroller/message-scroller.utils.ts
+var e = .5;
+function t(e, t) {
+	let n = [];
+	return e() && n.push("start"), t() && n.push("end"), n.length > 0 ? n.join(" ") : void 0;
+}
+//#endregion
+export { e as AT_EDGE_TOLERANCE, t as scrollableData };
+
+//# sourceMappingURL=message-scroller.utils.js.map

package/dist/components/message-scroller/message-scroller.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-scroller.utils.js","names":["AT_EDGE_TOLERANCE","scrollableData","tokens","start","end"],"sources":["../../../src/components/message-scroller/message-scroller.utils.ts"],"sourcesContent":["import type { Accessor } from \"solid-js\";\n\n/**\n * 滚动位置比较容差（0.5px）。\n *\n * 用于\"是否已到达某个位置\"\"锚点是否越过阅读线\"这类比较：浏览器的小数滚动位置\n * 不可能精确相等，需要一个统一的容差，否则会出现\"差 0.3px 算没到\"的抖动。\n */\nexport const AT_EDGE_TOLERANCE = 0.5;\n\n/**\n * `data-scrollable` 的取值：可向哪个边缘滚动，空格分隔的 token 列表\n * （`\"start\"` / `\"end\"` / `\"start end\"`），都不可滚时为 `undefined`\n * （可用 `[data-scrollable~=\"end\"]` 查询单个方向，缺失表示内容放得下）。\n */\nexport function scrollableData(\n  start: Accessor<boolean>,\n  end: Accessor<boolean>,\n): string | undefined {\n  const tokens: string[] = [];\n  if (start()) tokens.push(\"start\");\n  if (end()) tokens.push(\"end\");\n  return tokens.length > 0 ? tokens.join(\" \") : undefined;\n}\n"],"mappings":";AAQA,IAAaA,IAAoB;AAOjC,SAAgBC,EACd,GACA,GACoB;CACpB,IAAMC,IAAmB,CAAC;CAG1B,OAFIC,EAAM,KAAGD,EAAO,KAAK,OAAO,GAC5BE,EAAI,KAAGF,EAAO,KAAK,KAAK,GACrBA,EAAO,SAAS,IAAIA,EAAO,KAAK,GAAG,IAAI,KAAA;AAChD"}

package/dist/components/message-scroller/message-scroller.visibility.d.ts

@@ -0,0 +1,43 @@
+import { Accessor } from 'solid-js';
+import { MessageScrollerProviderProps } from './message-scroller.types';
+/**
+ * MessageScroller 的可见性与阅读锚点。
+ *
+ * 单一职责：回答"哪些行当前可见""读者的阅读行是哪个锚点"。
+ * 观察器按需建立（首个订阅者创建、最后一个撤销时断开），不支持
+ * `IntersectionObserver` 时退化为逐帧按矩形测量。
+ *
+ * 本模块不碰 scrollTop、不决定锚定——那是 commands / anchoring 的事。
+ * 行注册表留在引擎（见 REFACTOR-PLAN.md §D4），因此这里只接收
+ * "把某个元素纳入/移出观察"的通知。
+ */
+type EngineOptions = Required<Omit<MessageScrollerProviderProps, "children">>;
+export interface VisibilityOptions {
+    viewport: Accessor<HTMLElement | undefined>;
+    content: Accessor<HTMLElement | undefined>;
+    /** 会话里的行（按 DOM 顺序，已排除 spacer），来自 `dom-measure` */
+    items: () => HTMLElement[];
+    options: () => EngineOptions;
+    /** 已注册行的元素（建立观察器时逐个 observe） */
+    registeredElements: () => Iterable<HTMLElement>;
+}
+export interface Visibility {
+    /** 阅读行：视口顶部 + scrollMargin + peek 之上最后一个锚点 */
+    currentAnchorId: Accessor<string | null>;
+    /** 当前可见的消息 id（有 IO 时来自回调集合，否则按矩形判定） */
+    visibleMessageIds: Accessor<string[]>;
+    /** 把行纳入观察（挂载时调用） */
+    observe: (element: HTMLElement) => void;
+    /** 停止观察并从可见集合里移除（卸载时调用） */
+    unobserve: (id: string, element: HTMLElement) => void;
+    /** 分帧同步一次（滚动、内容变化、IO 回调之后调用） */
+    schedule: () => void;
+    /** 订阅计数大于 0 但观察器还没建立时补建（view 挂载后调用） */
+    ensureObserver: () => void;
+    /** 订阅可见性；返回撤销函数（可重复调用） */
+    subscribe: () => () => void;
+    /** 引擎卸载清理：取消未执行的帧、断开观察器 */
+    dispose: () => void;
+}
+export declare function createVisibility(options: VisibilityOptions): Visibility;
+export {};

package/dist/components/message-scroller/message-scroller.visibility.js

@@ -0,0 +1,82 @@
+import "./message-scroller.utils.js";
+import { createSignal as e } from "solid-js";
+//#region src/components/message-scroller/message-scroller.visibility.ts
+function t(t) {
+	let [n, r] = e(null), [i, a] = e([]), o = /* @__PURE__ */ new Set(), s = null, c = null, l = 0, u = () => {
+		c === null && (c = window.requestAnimationFrame(() => {
+			c = null, l > 0 && d();
+		}));
+	}, d = () => {
+		let e = t.viewport(), n = t.content();
+		if (!e || !n) {
+			a([]), r(null);
+			return;
+		}
+		let i = e.getBoundingClientRect(), s = i.top + t.options().scrollMargin + t.options().scrollPreviousItemPeek, c = typeof IntersectionObserver > "u", l = [], u = null;
+		for (let e of t.items()) {
+			let t = e.dataset.messageId;
+			if (!t) continue;
+			let n = e.dataset.scrollAnchor === "true", r = n || c ? e.getBoundingClientRect() : null;
+			(c && r ? r.bottom > s && r.top < i.bottom : o.has(t)) && l.push(t), n && r && r.top <= s + .5 && (u = t);
+		}
+		if (l.length === 0 && u === null) {
+			a([]), r(null);
+			return;
+		}
+		a(l), r(u);
+	}, f = () => {
+		if (typeof IntersectionObserver > "u") {
+			u();
+			return;
+		}
+		let e = t.viewport();
+		!s && e && (s = new IntersectionObserver((e) => {
+			for (let t of e) {
+				let e = t.target.dataset.messageId;
+				e && (t.isIntersecting ? o.add(e) : o.delete(e));
+			}
+			u();
+		}, {
+			root: e,
+			rootMargin: `${-(t.options().scrollMargin + t.options().scrollPreviousItemPeek)}px 0px 0px 0px`,
+			threshold: [
+				0,
+				.01,
+				.5,
+				1
+			]
+		}));
+		for (let e of t.registeredElements()) s?.observe(e);
+		u();
+	}, p = () => {
+		c !== null && (window.cancelAnimationFrame(c), c = null), s?.disconnect(), s = null, o.clear(), a([]), r(null);
+	};
+	return {
+		currentAnchorId: n,
+		visibleMessageIds: i,
+		schedule: u,
+		ensureObserver() {
+			l > 0 && !s && f();
+		},
+		observe(e) {
+			s?.observe(e);
+		},
+		unobserve(e, t) {
+			o.delete(e), s?.unobserve(t);
+		},
+		subscribe() {
+			l += 1, l === 1 && f(), u();
+			let e = !1;
+			return () => {
+				e || (e = !0, --l, l === 0 && p());
+			};
+		},
+		dispose() {
+			c !== null && (window.cancelAnimationFrame(c), c = null), s?.disconnect(), s = null;
+		}
+	};
+}
+//#endregion
+export { t as createVisibility };
+
+//# sourceMappingURL=message-scroller.visibility.js.map

package/dist/components/message-scroller/message-scroller.visibility.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-scroller.visibility.js","names":["createVisibility","currentAnchorId","setCurrentAnchorId","createSignal","visibleMessageIds","setVisibleMessageIds","visibleIds","observer","visibilityFrame","visibilitySubscribers","schedule","computeVisibility","viewport","options","content","viewportRect","readingLine","withoutObserver","visible","anchorId","item","id","isAnchor","rect","startObserver","entry","entries","element","stopObserver","released"],"sources":["../../../src/components/message-scroller/message-scroller.visibility.ts"],"sourcesContent":["import { createSignal, type Accessor } from \"solid-js\";\nimport type { MessageScrollerProviderProps } from \"./message-scroller.types\";\nimport { AT_EDGE_TOLERANCE } from \"./message-scroller.utils\";\n\n/**\n * MessageScroller 的可见性与阅读锚点。\n *\n * 单一职责：回答\"哪些行当前可见\"\"读者的阅读行是哪个锚点\"。\n * 观察器按需建立（首个订阅者创建、最后一个撤销时断开），不支持\n * `IntersectionObserver` 时退化为逐帧按矩形测量。\n *\n * 本模块不碰 scrollTop、不决定锚定——那是 commands / anchoring 的事。\n * 行注册表留在引擎（见 REFACTOR-PLAN.md §D4），因此这里只接收\n * \"把某个元素纳入/移出观察\"的通知。\n */\n\ntype EngineOptions = Required<Omit<MessageScrollerProviderProps, \"children\">>;\n\nexport interface VisibilityOptions {\n  viewport: Accessor<HTMLElement | undefined>;\n  content: Accessor<HTMLElement | undefined>;\n  /** 会话里的行（按 DOM 顺序，已排除 spacer），来自 `dom-measure` */\n  items: () => HTMLElement[];\n  options: () => EngineOptions;\n  /** 已注册行的元素（建立观察器时逐个 observe） */\n  registeredElements: () => Iterable<HTMLElement>;\n}\n\nexport interface Visibility {\n  /** 阅读行：视口顶部 + scrollMargin + peek 之上最后一个锚点 */\n  currentAnchorId: Accessor<string | null>;\n  /** 当前可见的消息 id（有 IO 时来自回调集合，否则按矩形判定） */\n  visibleMessageIds: Accessor<string[]>;\n  /** 把行纳入观察（挂载时调用） */\n  observe: (element: HTMLElement) => void;\n  /** 停止观察并从可见集合里移除（卸载时调用） */\n  unobserve: (id: string, element: HTMLElement) => void;\n  /** 分帧同步一次（滚动、内容变化、IO 回调之后调用） */\n  schedule: () => void;\n  /** 订阅计数大于 0 但观察器还没建立时补建（view 挂载后调用） */\n  ensureObserver: () => void;\n  /** 订阅可见性；返回撤销函数（可重复调用） */\n  subscribe: () => () => void;\n  /** 引擎卸载清理：取消未执行的帧、断开观察器 */\n  dispose: () => void;\n}\n\nexport function createVisibility(options: VisibilityOptions): Visibility {\n  const [currentAnchorId, setCurrentAnchorId] = createSignal<string | null>(\n    null,\n  );\n  const [visibleMessageIds, setVisibleMessageIds] = createSignal<string[]>([]);\n\n  const visibleIds = new Set<string>();\n  let observer: IntersectionObserver | null = null;\n  let visibilityFrame: number | null = null;\n  let visibilitySubscribers = 0;\n\n  const schedule = () => {\n    if (visibilityFrame !== null) return;\n    visibilityFrame = window.requestAnimationFrame(() => {\n      visibilityFrame = null;\n      if (visibilitySubscribers > 0) computeVisibility();\n    });\n  };\n\n  const computeVisibility = () => {\n    const viewport = options.viewport();\n    const content = options.content();\n    if (!viewport || !content) {\n      setVisibleMessageIds([]);\n      setCurrentAnchorId(null);\n      return;\n    }\n\n    const viewportRect = viewport.getBoundingClientRect();\n    const readingLine =\n      viewportRect.top +\n      options.options().scrollMargin +\n      options.options().scrollPreviousItemPeek;\n    // 没有 IO 时只能自己量；有 IO 时\"可见\"由回调投递的集合决定\n    const withoutObserver = typeof IntersectionObserver === \"undefined\";\n    const visible: string[] = [];\n    let anchorId: string | null = null;\n\n    for (const item of options.items()) {\n      const id = item.dataset.messageId;\n      if (!id) continue;\n\n      const isAnchor = item.dataset.scrollAnchor === \"true\";\n      const rect =\n        isAnchor || withoutObserver ? item.getBoundingClientRect() : null;\n      const isVisible =\n        withoutObserver && rect\n          ? rect.bottom > readingLine && rect.top < viewportRect.bottom\n          : visibleIds.has(id);\n\n      if (isVisible) visible.push(id);\n      // 阅读行取\"已经越过阅读线的最后一个锚点\"\n      if (isAnchor && rect && rect.top <= readingLine + AT_EDGE_TOLERANCE) {\n        anchorId = id;\n      }\n    }\n\n    if (visible.length === 0 && anchorId === null) {\n      setVisibleMessageIds([]);\n      setCurrentAnchorId(null);\n      return;\n    }\n    setVisibleMessageIds(visible);\n    setCurrentAnchorId(anchorId);\n  };\n\n  const startObserver = () => {\n    if (typeof IntersectionObserver === \"undefined\") {\n      schedule();\n      return;\n    }\n    const viewport = options.viewport();\n    if (!observer && viewport) {\n      observer = new IntersectionObserver(\n        (entries) => {\n          for (const entry of entries) {\n            const id = (entry.target as HTMLElement).dataset.messageId;\n            if (!id) continue;\n            if (entry.isIntersecting) visibleIds.add(id);\n            else visibleIds.delete(id);\n          }\n          schedule();\n        },\n        {\n          root: viewport,\n          rootMargin: `${-(options.options().scrollMargin + options.options().scrollPreviousItemPeek)}px 0px 0px 0px`,\n          threshold: [0, 0.01, 0.5, 1],\n        },\n      );\n    }\n    for (const element of options.registeredElements()) {\n      observer?.observe(element);\n    }\n    schedule();\n  };\n\n  const stopObserver = () => {\n    if (visibilityFrame !== null) {\n      window.cancelAnimationFrame(visibilityFrame);\n      visibilityFrame = null;\n    }\n    observer?.disconnect();\n    observer = null;\n    visibleIds.clear();\n    setVisibleMessageIds([]);\n    setCurrentAnchorId(null);\n  };\n\n  return {\n    currentAnchorId,\n    visibleMessageIds,\n    schedule,\n    ensureObserver() {\n      if (visibilitySubscribers > 0 && !observer) startObserver();\n    },\n    observe(element) {\n      observer?.observe(element);\n    },\n    unobserve(id, element) {\n      visibleIds.delete(id);\n      observer?.unobserve(element);\n    },\n    subscribe() {\n      visibilitySubscribers += 1;\n      if (visibilitySubscribers === 1) startObserver();\n      schedule();\n\n      let released = false;\n      return () => {\n        if (released) return;\n        released = true;\n        visibilitySubscribers -= 1;\n        if (visibilitySubscribers === 0) stopObserver();\n      };\n    },\n    dispose() {\n      if (visibilityFrame !== null) {\n        window.cancelAnimationFrame(visibilityFrame);\n        visibilityFrame = null;\n      }\n      observer?.disconnect();\n      observer = null;\n    },\n  };\n}\n"],"mappings":";;;AA+CA,SAAgBA,EAAiB,GAAwC;CACvE,IAAM,CAACC,GAAiBC,KAAsBC,EAC5C,IACF,GACM,CAACC,GAAmBC,KAAwBF,EAAuB,CAAC,CAAC,GAErEG,oBAAa,IAAI,IAAY,GAC/BC,IAAwC,MACxCC,IAAiC,MACjCC,IAAwB,GAEtBC,UAAiB;EACrB,AAAIF,MAAoB,SACxB,IAAkB,OAAO,4BAA4B;GAEnD,AADA,IAAkB,MACdC,IAAwB,KAAGE,EAAkB;EACnD,CAAC;CACH,GAEMA,UAA0B;EAC9B,IAAMC,IAAWC,EAAQ,SAAS,GAC5BC,IAAUD,EAAQ,QAAQ;EAChC,IAAI,CAACD,KAAY,CAACE,GAAS;GAEzB,AADAT,EAAqB,CAAC,CAAC,GACvBH,EAAmB,IAAI;GACvB;EACF;EAEA,IAAMa,IAAeH,EAAS,sBAAsB,GAC9CI,IACJD,EAAa,MACbF,EAAQ,QAAQ,CAAC,CAAC,eAClBA,EAAQ,QAAQ,CAAC,CAAC,wBAEdI,IAAkB,OAAO,uBAAyB,KAClDC,IAAoB,CAAC,GACvBC,IAA0B;EAE9B,KAAK,IAAMC,KAAQP,EAAQ,MAAM,GAAG;GAClC,IAAMQ,IAAKD,EAAK,QAAQ;GACxB,IAAI,CAACC,GAAI;GAET,IAAMC,IAAWF,EAAK,QAAQ,iBAAiB,QACzCG,IACJD,KAAYL,IAAkBG,EAAK,sBAAsB,IAAI;GAQ/D,CANEH,KAAmBM,IACfA,EAAK,SAASP,KAAeO,EAAK,MAAMR,EAAa,SACrDT,EAAW,IAAIe,CAAE,MAERH,EAAQ,KAAKG,CAAE,GAE1BC,KAAYC,KAAQA,EAAK,OAAOP,IAAA,OAClC,IAAWK;EAEf;EAEA,IAAIH,EAAQ,WAAW,KAAKC,MAAa,MAAM;GAE7C,AADAd,EAAqB,CAAC,CAAC,GACvBH,EAAmB,IAAI;GACvB;EACF;EAEA,AADAG,EAAqBa,CAAO,GAC5BhB,EAAmBiB,CAAQ;CAC7B,GAEMK,UAAsB;EAC1B,IAAI,OAAO,uBAAyB,KAAa;GAC/C,EAAS;GACT;EACF;EACA,IAAMZ,IAAWC,EAAQ,SAAS;EAClC,AAAI,CAACN,KAAYK,MACf,IAAW,IAAI,sBACZ,MAAY;GACX,KAAK,IAAMa,KAASC,GAAS;IAC3B,IAAML,IAAMI,EAAM,OAAuB,QAAQ;IACjD,AAAKJ,MACDI,EAAM,iBAAgBnB,EAAW,IAAIe,CAAE,IACtCf,EAAW,OAAOe,CAAE;GAC3B;GACA,EAAS;EACX,GACA;GACE,MAAMT;GACN,YAAY,GAAG,EAAEC,EAAQ,QAAQ,CAAC,CAAC,eAAeA,EAAQ,QAAQ,CAAC,CAAC,wBAAwB;GAC5F,WAAW;IAAC;IAAG;IAAM;IAAK;GAAC;EAC7B,CACF;EAEF,KAAK,IAAMc,KAAWd,EAAQ,mBAAmB,GAC/C,GAAU,QAAQc,CAAO;EAE3B,EAAS;CACX,GAEMC,UAAqB;EASzB,AARIpB,MAAoB,SACtB,OAAO,qBAAqBA,CAAe,GAC3C,IAAkB,OAEpBD,GAAU,WAAW,GACrB,IAAW,MACXD,EAAW,MAAM,GACjBD,EAAqB,CAAC,CAAC,GACvBH,EAAmB,IAAI;CACzB;CAEA,OAAO;EACL;EACA;EACA;EACA,iBAAiB;GACf,AAAIO,IAAwB,KAAK,CAACF,KAAUiB,EAAc;EAC5D;EACA,QAAQ,GAAS;GACf,GAAU,QAAQG,CAAO;EAC3B;EACA,UAAU,GAAI,GAAS;GAErB,AADArB,EAAW,OAAOe,CAAE,GACpBd,GAAU,UAAUoB,CAAO;EAC7B;EACA,YAAY;GAGV,AAFA,KAAyB,GACrBlB,MAA0B,KAAGe,EAAc,GAC/Cd,EAAS;GAET,IAAImB,IAAW;GACf,aAAa;IACX,AAAIA,MACJ,IAAW,IACX,KACIpB,MAA0B,KAAGmB,EAAa;GAChD;EACF;EACA,UAAU;GAMR,AALIpB,MAAoB,SACtB,OAAO,qBAAqBA,CAAe,GAC3C,IAAkB,OAEpBD,GAAU,WAAW,GACrB,IAAW;EACb;CACF;AACF"}

package/dist/components/message-scroller/useMessageScroller.d.ts

@@ -0,0 +1,6 @@
+/** 在 Provider 内部任意位置驱动滚动（含 MessageScroller 框架之外的自定义控件） */
+export declare function useMessageScroller(): {
+    scrollToStart: (options?: import('./message-scroller.types').MessageScrollerScrollOptions) => boolean;
+    scrollToEnd: (options?: import('./message-scroller.types').MessageScrollerScrollOptions) => boolean;
+    scrollToMessage: (messageId: string, options?: import('./message-scroller.types').MessageScrollerScrollOptions) => boolean;
+};

package/dist/components/message-scroller/useMessageScroller.js

@@ -0,0 +1,14 @@
+import { useMessageScrollerContext as e } from "./message-scroller.context.js";
+//#region src/components/message-scroller/useMessageScroller.ts
+function t() {
+	let t = e("useMessageScroller");
+	return {
+		scrollToStart: t.scrollToStart,
+		scrollToEnd: t.scrollToEnd,
+		scrollToMessage: t.scrollToMessage
+	};
+}
+//#endregion
+export { t as useMessageScroller };
+
+//# sourceMappingURL=useMessageScroller.js.map

package/dist/components/message-scroller/useMessageScroller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useMessageScroller.js","names":["useMessageScroller","ctx","useMessageScrollerContext"],"sources":["../../../src/components/message-scroller/useMessageScroller.ts"],"sourcesContent":["import { useMessageScrollerContext } from \"./message-scroller.context\";\n\n/** 在 Provider 内部任意位置驱动滚动（含 MessageScroller 框架之外的自定义控件） */\nexport function useMessageScroller() {\n  const ctx = useMessageScrollerContext(\"useMessageScroller\");\n  return {\n    scrollToStart: ctx.scrollToStart,\n    scrollToEnd: ctx.scrollToEnd,\n    scrollToMessage: ctx.scrollToMessage,\n  };\n}\n"],"mappings":";;AAGA,SAAgBA,IAAqB;CACnC,IAAMC,IAAMC,EAA0B,oBAAoB;CAC1D,OAAO;EACL,eAAeD,EAAI;EACnB,aAAaA,EAAI;EACjB,iBAAiBA,EAAI;CACvB;AACF"}

package/dist/components/message-scroller/useMessageScrollerEngine.d.ts

@@ -0,0 +1,15 @@
+import { MessageScrollerContextValue, MessageScrollerProviderProps } from './message-scroller.types';
+/**
+ * MessageScroller 的滚动引擎（headless，行为对齐 `@shadcn/react`）：
+ * - 滚动状态（能否向上/下）由 content 的**非 spacer** 内容底部计算，spacer 不计入；
+ * - `autoScroll` 只在模式为 `following-bottom` 时跟随；滚轮/触摸/键盘滚动与显式跳转
+ *   都会立刻让位（`free-scrolling`）；
+ * - 新回合锚定：新增 scrollAnchor 行时用 `scrollToElement(keepPreviousPeek)` 将其放到
+ *   顶部并保留上一项；同时把该行记为 `streamingTurn`，回复生长时原地重锚定；
+ * - `scrollToElement` 会按需设置尾部 spacer，让目标行即使靠近会话末尾也能滚到顶部；
+ * - `defaultScrollPosition`：首次非空渲染定位一次；`last-anchor` 无锚点或放得下时回退 end；
+ * - `preserveScrollOnPrepend`：记录首个可见行及其视口位置，上方插入历史后按差值补偿；
+ * - 可见性：IntersectionObserver 按需订阅（rootMargin 用 scrollMargin + peek），无 IO 时退化为
+ *   逐帧测量；`currentAnchorId` 是阅读行之上最后一个锚点。
+ */
+export declare function useMessageScrollerEngine(options: () => Required<Omit<MessageScrollerProviderProps, "children">>): MessageScrollerContextValue;