@dsh-ft/dsh-fft-settings 0.5.1 → 0.6.0

package/lib/client.d.ts

@@ -1,8 +1,15 @@
 import { type ApiKeyCardContext } from './features/api-key/card.js';
 export * from './core/shell.js';
+export { FREE_KEY_NOTICE_ID, FREE_KEY_NOTICE_SLOT, isViewIdle, shouldShowNotice, type FreeKeyNoticeSessionState } from './features/free-key-notice/decision.js';
+export { readNoticeSeen, writeNoticeSeen, type NoticeFlagStorage } from './features/free-key-notice/storage.js';
 /** Browser context this plugin's own client half requires. */
 export type FtshareSettingsClientContext = ApiKeyCardContext;
 export declare const inject: string[];
 export declare function apply(ctx: FtshareSettingsClientContext): void;
-/** Contribute the section shell, then the built-in cards through the slot it declares. */
+/**
+ * Contribute the settings section, its cards, and the frame-wide notice.
+ *
+ * The notice deliberately does not live in the settings page: it has to reach
+ * users who never open settings, so it takes a seat in `shell.overlay`.
+ */
 export declare function registerFtshareSettings(ctx: FtshareSettingsClientContext): void;

package/lib/client.js

@@ -6,6 +6,19 @@ window.__ModuleLoader__.load({
 		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 		let react = require("react");
 		let react_jsx_runtime = require("react/jsx-runtime");
+		/**
+		* 申请／购买 API Key 的页面。`utm_source=dsh-fft` 标记来源为本插件，站点据此归因；
+		* 卡片与一次性提示共用这一条地址，不要在别处另写一份。
+		*/
+		const FTSHARE_API_KEY_APPLY_URL = "https://ftai.chat/me/profile?tab=api-key&utm_source=dsh-fft";
+		/**
+		* 设备级「已看过免费 Key 提示」标记的 localStorage 键。
+		*
+		* 带版本号：改一次文案就把版本加一，让所有用户重新看一次，不需要让用户清缓存。
+		* 设备级语义（重启、升级都保留，跨 workspace／窗口共享）由桌面版主窗口的
+		* `dsh-app://app/` origin 私有存储提供，不写宿主的配置文件。
+		*/
+		const FREE_KEY_NOTICE_STORAGE_KEY = "dsh-fft.free-key-notice.v1";
 		const FTSHARE_CREDENTIAL_EVENTS = ["credentials/reference-updated"];
 		/** Local syntax validation, never an assertion of upstream validity. */
 		function normalizeApiKey(input) {
@@ -363,7 +376,7 @@ window.__ModuleLoader__.load({
 										children: "重新读取状态"
 									}),
 									/* @__PURE__ */ (0, react_jsx_runtime.jsx)("a", {
-										href: "https://ftai.chat/me/profile?tab=api-key",
+										href: FTSHARE_API_KEY_APPLY_URL,
 										target: "_blank",
 										rel: "noreferrer",
 										children: "获取 API Key ↗"
@@ -415,6 +428,306 @@ window.__ModuleLoader__.load({
 				]
 			})] });
 		}
+		// src/features/free-key-notice/storage.ts
+		/**
+		* 取浏览器存储；拿不到（没有 window、被禁用）时返回 undefined。
+		* @returns 可用存储，或 undefined。
+		*/
+		function browserNoticeStorage() {
+			try {
+				const storage = globalThis.localStorage;
+				return storage === void 0 ? void 0 : {
+					getItem: (key) => storage.getItem(key),
+					setItem: (key, value) => {
+						storage.setItem(key, value);
+					}
+				};
+			} catch (_blocked) {
+				return;
+			}
+		}
+		/**
+		* 读标记。任何异常与空值都算「没看过」。
+		* @param storage - 目标存储；缺失视为没看过。
+		* @param key - 标记键。
+		* @returns 是否已看过。
+		*/
+		function readNoticeSeen(storage, key) {
+			if (storage === void 0) return false;
+			try {
+				return storage.getItem(key) === "1";
+			} catch (_blocked) {
+				return false;
+			}
+		}
+		/**
+		* 写标记。写失败不抛：提示已经显示过了，这次没记下来只是下次会再弹一次。
+		* @param storage - 目标存储；缺失时什么都不做。
+		* @param key - 标记键。
+		* @returns 是否写入成功。
+		*/
+		function writeNoticeSeen(storage, key) {
+			if (storage === void 0) return false;
+			try {
+				storage.setItem(key, "1");
+				return true;
+			} catch (_blocked) {
+				return false;
+			}
+		}
+		// src/features/free-key-notice/decision.ts
+		/**
+		* 「这条一次性提示该不该弹」的判定。
+		*
+		* 与渲染分开：判定是纯函数、零依赖，能在 Node 测试里直接钉住；渲染层只管把
+		* 模态框摆出去。三条输入里任何一条没准备好都按「不弹」处理——这是刻意的，
+		* 一次没弹只是少一次提醒，弹错一次就是打扰。
+		*/
+		/** 宿主 `shell.overlay` 槽名；这个 feature 只往这一个座位贡献。 */
+		const FREE_KEY_NOTICE_SLOT = "shell.overlay";
+		/** 条目 id：必须自己的，占用宿主的会顶掉别人的浮层。 */
+		const FREE_KEY_NOTICE_ID = "ftshare.free-key-notice";
+		/**
+		* 主视图是否停在一个空会话上（没有内容会被弹窗挡住）。
+		* @param state - 会话列表快照。
+		* @returns 是否可以安全地弹出模态框。
+		*/
+		function isViewIdle(state) {
+			if (state.phase !== "ready") return false;
+			const main = Object.values(state.byId).find((session) => (session.retainedBy?.mainView ?? 0) > 0);
+			return main === void 0 || main.blank;
+		}
+		/**
+		* 是否应当显示提示。
+		* - 已看过：不弹（设备级一次）；
+		* - Key 已配置、或状态还读不到：不弹（读不到时宁可少弹）；
+		* - 主视图被有内容的会话占着：不弹，等它空下来。
+		* @param facts - 三个输入。
+		* @returns 是否显示。
+		*/
+		function shouldShowNotice(facts) {
+			if (facts.seen) return false;
+			if (facts.configured !== false) return false;
+			return facts.viewIdle;
+		}
+		// src/features/free-key-notice/styles.ts
+		/**
+		* 一次性提示的样式：固定在左下角的非阻塞卡片。
+		*
+		* 不盖遮罩、不抢焦点——这一层（宿主的 `shell.overlay`）本身可穿透点击，
+		* 条目只有在这张卡片范围内才接收指针事件，所以卡片以外的界面照常可用。
+		* 位置用 `fixed` 而不是依赖外层布局：浮层是 `inset:0` 的绝对定位层，
+		* 条目自己决定停在哪里。
+		*
+		* 颜色全走 `--dsw-alias-*` 与 `--ft-*` 变量，深色／浅色两套调色板共用一份。
+		*/
+		const FREE_KEY_NOTICE_CSS = `
+.ftshare-free-key-notice { position:fixed; left:24px; bottom:24px; z-index:20; box-sizing:border-box; width:min(320px, calc(100vw - 48px)); padding:16px; border:0.5px solid var(--dsw-alias-border-l2,rgba(0,0,0,.1)); border-radius:var(--dsw-radius-xl,20px); background:var(--dsw-alias-bg-layer-2,#fff); color:var(--dsw-alias-label-primary,#0f1115); box-shadow:var(--dsw-elevation-prominent,0 3px 8px rgba(0,0,0,.04), 0 0 20px rgba(0,0,0,.05)); animation:ftshareNoticeIn .2s ease; }
+.ftshare-free-key-notice * { box-sizing:border-box; }
+.ftshare-free-key-notice .ftshare-free-key-head { display:flex; align-items:flex-start; justify-content:space-between; gap:8px; }
+.ftshare-free-key-notice strong { font-size:14px; font-weight:500; line-height:22px; }
+.ftshare-free-key-notice .ftshare-free-key-close { flex:none; width:22px; height:22px; display:inline-flex; align-items:center; justify-content:center; border:none; border-radius:var(--dsw-radius-sm,8px); background:transparent; color:var(--dsw-alias-label-secondary,#61666b); font:inherit; font-size:12px; line-height:1; cursor:pointer; }
+.ftshare-free-key-notice .ftshare-free-key-close:hover { background:var(--dsw-alias-bg-layer-3,#f9fafb); }
+.ftshare-free-key-notice p { margin:6px 0 14px; font-size:13px; line-height:1.6; color:var(--dsw-alias-label-secondary,#61666b); }
+.ftshare-free-key-notice .ftshare-free-key-actions { display:flex; gap:8px; }
+.ftshare-free-key-notice .ftshare-free-key-actions :is(button,a) { min-height:30px; display:inline-flex; align-items:center; justify-content:center; border-radius:var(--dsw-radius-md,12px); border:0.5px solid var(--dsw-alias-border-l4,rgba(0,0,0,.16)); padding:0 12px; font:inherit; font-size:13px; background:transparent; color:inherit; text-decoration:none; cursor:pointer; }
+/* 主入口用品牌黄的半透明底：保留 FT 的色，又不至于在左下角变成一块醒目的亮黄。
+   文字仍取正文主色（不是压在上面的深黑字），70% 在深浅两套调色板下都能读。 */
+.ftshare-free-key-notice .ftshare-free-key-actions .primary { flex:1; background:color-mix(in srgb,var(--ft-accent,#f0c433) 70%,transparent); border-color:var(--ft-accent,#f0c433); color:var(--dsw-alias-label-primary,#0f1115); font-weight:500; }
+.ftshare-free-key-notice .ftshare-free-key-actions .primary:hover { background:color-mix(in srgb,var(--ft-accent,#f0c433) 82%,transparent); }
+@keyframes ftshareNoticeIn { from { opacity:0; transform:translateY(6px); } to { opacity:1; transform:none; } }
+@media (prefers-reduced-motion: reduce) { .ftshare-free-key-notice { animation:none; } }
+`;
+		// src/features/free-key-notice/card.tsx
+		/**
+		* 一次性提示：还没配置 API Key 的用户，去获取免费的 FTShare Key。
+		*
+		* 三个设计决定：
+		*
+		* 1. **左下角、不阻塞**。它是提示，不是必须处理的阻断：不盖遮罩、不抢焦点、
+		*    不打断正在发生的事，12 秒后自己淡出（鼠标悬停时暂停计时）。用 `Modal`
+		*    会遮住整个界面，代价太大。
+		* 2. **只在确认「没配 Key」时出现**。凭据状态异步读来，没读到时一律不出现，
+		*    否则配了 Key 的用户每次启动都会被闪一下。
+		* 3. **设备级只出现一次**。首次出现就写 `localStorage` 标记（见 `./storage.ts`），
+		*    不等用户点按钮——否则自动消失后标记不落盘，下次启动又会打扰。
+		*
+		* 挂载在宿主框架级的 `shell.overlay` 槽上（`ui-layout` 的 AppFrame 常驻渲染），
+		* 不在设置页里：要触达的恰恰是从不打开设置的用户。该图层本身可穿透点击，
+		* 条目只在自己的卡片范围内接收指针事件。
+		*/
+		/** 停留时长：足够读完一句话并决定要不要去获取，又不至于一直挂在界面上。 */
+		const FREE_KEY_NOTICE_AUTO_DISMISS_MS = 12e3;
+		/**
+		* 把异步的 `configured` 摊成 uSES 快照。只在有订阅者时读一次，订阅清理时停止。
+		* @param deps - 读函数与订阅函数。
+		* @returns uSES 快照源。
+		*/
+		function useConfigured(deps) {
+			const source = (0, react.useMemo)(() => {
+				let value;
+				let stop;
+				const listeners = /* @__PURE__ */ new Set();
+				const publish = () => {
+					for (const listener of [...listeners]) listener();
+				};
+				const load = () => {
+					deps.readConfigured().then((next) => {
+						value = next;
+						publish();
+					}, () => {});
+				};
+				return {
+					getSnapshot: () => value,
+					subscribe: (listener) => {
+						listeners.add(listener);
+						if (stop === void 0) {
+							load();
+							const off = deps.subscribeConfigured(load);
+							stop = () => {
+								off();
+							};
+						}
+						return () => {
+							listeners.delete(listener);
+							if (listeners.size === 0) {
+								stop?.();
+								stop = void 0;
+							}
+						};
+					}
+				};
+			}, [deps]);
+			return (0, react.useSyncExternalStore)(source.subscribe, source.getSnapshot, source.getSnapshot);
+		}
+		/**
+		* 提示本体。
+		* @param props - 依赖注入，以及宿主通过槽位交给每个条目的标准份额。
+		* @returns 左下角卡片，或 null。
+		*/
+		function FreeKeyNotice({ deps, useSessions }) {
+			const [seen, setSeen] = (0, react.useState)(() => readNoticeSeen(deps.storage, FREE_KEY_NOTICE_STORAGE_KEY));
+			const [visible, setVisible] = (0, react.useState)(true);
+			const configured = useConfigured(deps);
+			const viewIdle = useSessions(isViewIdle);
+			const show = visible && shouldShowNotice({
+				seen,
+				configured,
+				viewIdle
+			});
+			(0, react.useEffect)(() => {
+				if (!show || seen) return;
+				writeNoticeSeen(deps.storage, FREE_KEY_NOTICE_STORAGE_KEY);
+				setSeen(true);
+			}, [
+				show,
+				seen,
+				deps.storage
+			]);
+			const deadline = (0, react.useRef)(void 0);
+			const timer = (0, react.useRef)(void 0);
+			const dismiss = (0, react.useCallback)(() => {
+				setVisible(false);
+			}, []);
+			const hold = (0, react.useCallback)(() => {
+				if (timer.current !== void 0) clearTimeout(timer.current);
+				timer.current = void 0;
+				deadline.current = void 0;
+			}, []);
+			const resume = (0, react.useCallback)(() => {
+				if (deadline.current === void 0) return;
+				const remaining = Math.max(0, deadline.current - Date.now());
+				timer.current = setTimeout(dismiss, remaining);
+			}, [dismiss]);
+			(0, react.useEffect)(() => {
+				if (!show) return;
+				deadline.current = Date.now() + FREE_KEY_NOTICE_AUTO_DISMISS_MS;
+				timer.current = setTimeout(dismiss, FREE_KEY_NOTICE_AUTO_DISMISS_MS);
+				return () => {
+					if (timer.current !== void 0) clearTimeout(timer.current);
+					timer.current = void 0;
+					deadline.current = void 0;
+				};
+			}, [show, dismiss]);
+			if (!show) return null;
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("style", { children: FREE_KEY_NOTICE_CSS }), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("aside", {
+				className: "ftshare-free-key-notice",
+				role: "status",
+				"aria-live": "polite",
+				onMouseEnter: hold,
+				onMouseLeave: resume,
+				children: [
+					/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+						className: "ftshare-free-key-head",
+						children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("strong", { children: "免费获取 Key" }), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+							type: "button",
+							className: "ftshare-free-key-close",
+							"aria-label": "关闭",
+							onClick: dismiss,
+							children: "✕"
+						})]
+					}),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", { children: "海量金融数据，一次配置长期使用" }),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+						className: "ftshare-free-key-actions",
+						children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("a", {
+							className: "primary",
+							href: deps.applyUrl,
+							target: "_blank",
+							rel: "noreferrer",
+							onClick: dismiss,
+							children: "去获取"
+						}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+							type: "button",
+							onClick: dismiss,
+							children: "知道了"
+						})]
+					})
+				]
+			})] });
+		}
+		/**
+		* 浏览器侧装配：把凭据通道、真实 localStorage 接到组件上。
+		* `useSessions` 是宿主交给 `shell.overlay` 条目的标准份额，从 props 透传而不是自造。
+		* @param ctx - 卡片那套上下文（slots + 凭据失效事件）。
+		* @returns 槽位组件工厂。
+		*/
+		function createFreeKeyNotice(ctx) {
+			const api = createApiKeyClient(createSettingsTransport());
+			const subscribeConfigured = (listener) => {
+				const disposers = FTSHARE_CREDENTIAL_EVENTS.map((event) => ctx.remote.$on(event, (ref) => {
+					if (ref === "FTSHARE_API_KEY") listener();
+				}));
+				disposers.push(ctx.on("connection/reset", listener));
+				return () => {
+					for (const dispose of disposers) dispose();
+				};
+			};
+			const deps = {
+				readConfigured: async () => (await api.describe()).configured,
+				subscribeConfigured,
+				storage: browserNoticeStorage(),
+				applyUrl: FTSHARE_API_KEY_APPLY_URL
+			};
+			return ({ useSessions }) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)(FreeKeyNotice, {
+				deps,
+				useSessions
+			});
+		}
+		// src/features/free-key-notice/index.ts
+		/**
+		* 注册一次性提示。
+		* @param ctx - 客户端上下文，需带 `slots` 服务。
+		* @returns 幂等 disposer。
+		*/
+		function registerFreeKeyNotice(ctx) {
+			const component = createFreeKeyNotice(ctx);
+			return ctx.slots.inject(FREE_KEY_NOTICE_SLOT, () => ctx.slots.register({
+				name: FREE_KEY_NOTICE_SLOT,
+				id: FREE_KEY_NOTICE_ID,
+				order: 100
+			}, component));
+		}
 		// src/features/logs/contract.ts
 		/**
 		* `logs` 命名空间的共享契约：只有常量与类型，浏览器半边可以安全导入。
@@ -788,17 +1101,29 @@ window.__ModuleLoader__.load({
 			registerFtshareSettings(ctx);
 			applyBrandTokens(ctx);
 		}
-		/** Contribute the section shell, then the built-in cards through the slot it declares. */
+		/**
+		* Contribute the settings section, its cards, and the frame-wide notice.
+		*
+		* The notice deliberately does not live in the settings page: it has to reach
+		* users who never open settings, so it takes a seat in `shell.overlay`.
+		*/
 		function registerFtshareSettings(ctx) {
 			registerSettingsSection(ctx);
 			registerApiKeyCard(ctx);
 			registerLogsCard(ctx);
+			registerFreeKeyNotice(ctx);
 		}
+		exports.FREE_KEY_NOTICE_ID = FREE_KEY_NOTICE_ID;
+		exports.FREE_KEY_NOTICE_SLOT = FREE_KEY_NOTICE_SLOT;
 		exports.FtshareSettingsSection = FtshareSettingsSection;
 		exports.apply = apply;
 		exports.inject = inject;
+		exports.isViewIdle = isViewIdle;
+		exports.readNoticeSeen = readNoticeSeen;
 		exports.registerFtshareSettings = registerFtshareSettings;
 		exports.registerSettingsSection = registerSettingsSection;
+		exports.shouldShowNotice = shouldShowNotice;
+		exports.writeNoticeSeen = writeNoticeSeen;
 		return module.exports;
 	}
 });