@jzg223/design-runtime 0.0.1 → 0.1.0-rc.2

package/dist/types/board/theme-host.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 看板主题的**宿主侧**（DOM 相关，所以不在引擎里）
+ *
+ * 分工（见方案文档 §3 与 `board-engine/theme-manifest.ts`）：
+ * - 引擎只做纯解析与令牌登记（`parseManifest` / `setThemeTokens` / `themeOf`）；
+ * - 本文件负责"把主题 CSS 弄进页面、再把它里面的那几个值读出来交给引擎"。
+ *
+ * 为什么主题是**外部 CSS 文件**而不是库里的样式：
+ * 47 套主题共 651 KB，且发布后要能替换/新增（运维丢个 css 进去就换主题）。
+ * 所以库里只留兜底（`theme-fallback`）+ 3 套内置，其余从 `themeBaseUrl` 按需取。
+ *
+ * 为什么要**读计算样式**：ECharts 的调色板是 JS 参数，CSS 给不了。
+ * 不读的话"文件主题"就换得了壳、换不了图（图表还是内置色）。
+ */
+import { type BoardThemeEntry } from '../board-engine';
+/** 缺省主题目录（宿主没注入时的同源约定） */
+export declare const DEFAULT_THEME_BASE = "/board/theme/";
+/**
+ * 主题目录（优先级：宿主注入 > design-ui 的 `window._CONFIG` 口径 > 同源缺省）。
+ * 第二条只为"同一份代码将来在设计端也跑"准备，不要在本库里新增对 `_CONFIG` 的依赖。
+ */
+export declare function themeBaseUrl(): string;
+/**
+ * 从 CSS 里读 JS 需要的那几个令牌。
+ * 做法：临时插一个带 `data-board-theme="code"` 的探针元素读计算样式，读完立刻删
+ * （样式表本身已经由 `<link>` 加载好，所以这里是**同步**的、没有网络等待）。
+ */
+export declare function readThemeTokens(code: string): Record<string, any> | null;
+/** 读取并登记某主题的令牌（幂等），返回合并后的主题对象 */
+export declare function ensureTheme(code?: string | null): Record<string, any>;
+/**
+ * 按需加载主题 CSS（几十套主题全量静态加载就是白下几百 KB）。
+ *
+ * 已插过（含入口里静态加载的）直接可用；否则插 `<link>` 等 load，**3s 超时也 resolve** ——
+ * 应用自带 `:root` 级兜底变量，界面不会崩，只是观感回落内置主题。
+ */
+export declare function ensureThemeCss(code?: string | null): Promise<boolean>;
+/** 读主题清单（只给设计器的下拉用；运行端不需要，失败返回空清单、不抛） */
+export declare function loadManifest(): Promise<BoardThemeEntry[]>;
+/** 测试/调试用：清缓存 */
+export declare function resetThemeFileCache(): void;

package/dist/types/board-engine/asset.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 素材引用（`asset:` 前缀）—— 让看板配置里的图片/视频「换部署环境不用改配置」。
+ *
+ * 【为什么不在配置里直接存完整 URL】
+ * 看板配置要能导出/导入/复制到别的项目。如果存的是
+ * `http://120.70.96.85/server/design/board/asset/file?path=202609/ab.png`，
+ * 换域名、换上下文、换成 https 之后那份配置里的每一个图片部件都会坏掉。
+ * 所以配置里只存**与部署无关的引用**：
+ *
+ *     asset:202609/ab12cd34.png      ← 素材模块自己的（相对 storage 根）
+ *     http://x.y/logo.png            ← 外部地址，原样使用
+ *     /static/img/logo.png           ← 站点内绝对路径，原样使用
+ *     data:image/png;base64,...      ← 内联图片，原样使用
+ *
+ * 渲染时再用 {@link assetUrl} 拼成当前部署下的真实地址 ⇒ 同一份配置在任何环境都能显示。
+ *
+ * ⚠ 本文件**不读任何全局**（`window._CONFIG` 那套是 design-ui 的口径）：
+ * base 由调用方传（运行端从 `installDesignPlatform({ board: { assetBaseUrl } })` 取），
+ * 这样引擎才能在设计端、运行端、node 测试里跑出同一结果。
+ */
+export declare const ASSET_PREFIX = "asset:";
+/** 是不是本模块的素材引用 */
+export declare function isAssetRef(v: unknown): boolean;
+/** 素材相对路径（不是 asset: 引用则返回空串） */
+export declare function assetPath(v: unknown): string;
+/** 把上传接口返回的 path 包成 asset: 引用 */
+export declare function toAssetRef(path: unknown): string;
+/** 展示用文件名 */
+export declare function assetName(v: unknown): string;
+/**
+ * 配置值 → 可用于 `src` 的地址。
+ *
+ * @param v    配置里的值（`asset:` 引用 / 普通 URL / 空）
+ * @param base 接口前缀（例如 `''` 或 `/server`）；末尾斜杠会被忽略
+ * @returns 空值返回空串（调用方据此显示占位）
+ */
+export declare function assetUrl(v: unknown, base?: string): string;