@yaoxiu/marketing-dsl 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,430 @@
+/**
+ * DSL 的类型定义。
+ *
+ * 分两组：
+ *   - Dsl* 是运营写的配置，也就是存进数据库的那份 JSON
+ *   - Render* 是 core 算完之后交给框架层的渲染树，纯数据，跟框架无关
+ *
+ * 框架层只认 Render*，永远不该去读 Dsl*——一旦读了，解析逻辑就又漏回渲染层了。
+ */
+type DslViewType = 'popup' | 'banner' | 'notice';
+type DslNodeType = 'box' | 'flex' | 'repeat' | 'image' | 'text' | 'button' | 'tabs' | 'countdown';
+/** 长度：数字按 px，字符串原样交给 CSS，可以带 {{ }} */
+type DslLength = number | string;
+/** rect: [x, y, width, height]，绝对定位容器里用 */
+type DslRect = [DslLength, DslLength, DslLength, DslLength];
+/** 样式对象，键必须在白名单内，值可以带 {{ }} */
+type DslStyle = Record<string, unknown>;
+interface DslActionBase {
+    type: string;
+}
+interface DslNavigateAction extends DslActionBase {
+    type: 'navigate';
+    url: string;
+    target?: '_self' | '_blank';
+}
+interface DslCloseAction extends DslActionBase {
+    type: 'close';
+    reason?: string;
+}
+interface DslCloseAllAction extends DslActionBase {
+    type: 'closeAll';
+    reason?: string;
+}
+interface DslOpenAction extends DslActionBase {
+    type: 'open';
+    view: string;
+    mode?: 'stack' | 'replace';
+}
+interface DslSetStateAction extends DslActionBase {
+    type: 'setState';
+    key: string;
+    value: unknown;
+}
+interface DslTrackAction extends DslActionBase {
+    type: 'track';
+    event: string;
+    params?: Record<string, unknown>;
+}
+/** 调用宿主注册的方法，名字必须在 handlers 白名单内 */
+interface DslCallAction extends DslActionBase {
+    type: 'call';
+    name: string;
+    params?: Record<string, unknown>;
+}
+interface DslSequenceAction extends DslActionBase {
+    type: 'sequence';
+    actions: DslAction[];
+}
+type DslAction = DslNavigateAction | DslCloseAction | DslCloseAllAction | DslOpenAction | DslSetStateAction | DslTrackAction | DslCallAction | DslSequenceAction;
+interface DslNode {
+    id?: string;
+    type: DslNodeType;
+    rect?: DslRect;
+    style?: DslStyle;
+    /** 表达式，为假时整个节点不渲染 */
+    visibleWhen?: string;
+    action?: DslAction;
+    /** box / flex / countdown */
+    children?: DslNode[];
+    /** repeat / tabs：数组来源表达式 */
+    bind?: string;
+    /** repeat */
+    template?: DslNode;
+    itemName?: string;
+    indexName?: string;
+    /** tabs */
+    stateKey?: string;
+    labelField?: string;
+    itemStyle?: DslStyle;
+    activeItemStyle?: DslStyle;
+    /** image */
+    src?: string;
+    /** text */
+    content?: string;
+    /** button */
+    text?: string;
+    /** countdown */
+    to?: string;
+    precision?: 's' | 'cs';
+    as?: string;
+    format?: string;
+    endText?: string;
+    onEnd?: DslAction;
+}
+type DslClosePosition = 'top-right' | 'top-left' | 'top-center' | 'bottom-right' | 'bottom-left' | 'bottom-center';
+interface DslCloseButton {
+    show?: boolean;
+    position?: DslClosePosition;
+    /** [x, y]，负值把按钮移到弹窗外面 */
+    offset?: [DslLength, DslLength];
+    size?: DslLength;
+    icon?: string;
+    image?: string;
+    style?: DslStyle;
+}
+interface DslStage {
+    width?: DslLength;
+    height?: DslLength;
+    /** absolute（默认）子节点用 rect 定位；flow 子节点按 flex 排 */
+    layout?: 'absolute' | 'flow';
+    mask?: boolean;
+    maskClosable?: boolean;
+    closeButton?: DslCloseButton;
+    style?: DslStyle;
+    /** 曝光埋点：数据就绪、视图真正展示时触发一次 */
+    onShow?: DslAction;
+    /** 关闭埋点：点 X、点遮罩、close 动作、被 replace 顶掉都会触发 */
+    onClose?: DslAction;
+}
+interface DslView {
+    type: DslViewType;
+    stage: DslStage;
+    nodes: DslNode[];
+}
+/** 后端数据源引用，名字必须在 sources 白名单内 */
+interface DslSourceRef {
+    $source: string;
+    params?: Record<string, unknown>;
+}
+interface DslDerived {
+    /** data 里的数组字段名 */
+    list: string;
+    /** state 里的下标字段名 */
+    indexBy: string;
+}
+/** 一份完整配置。单视图直接写 type/stage/nodes，多视图写 views + entry */
+interface Dsl extends Partial<DslView> {
+    version: number;
+    meta?: {
+        name?: string;
+        [key: string]: unknown;
+    };
+    data?: Record<string, unknown | DslSourceRef>;
+    state?: Record<string, unknown>;
+    derived?: Record<string, DslDerived>;
+    views?: Record<string, DslView>;
+    entry?: string;
+}
+/** 已经算好的行内样式，键是 CSS 属性名（驼峰），值是最终字符串 */
+type CssStyle = Record<string, string>;
+interface RenderElement {
+    /** 稳定 key，框架层做列表 diff 用 */
+    key: string;
+    /** 画成什么。div 带 text 就是文本节点，带 children 就是容器 */
+    tag: 'div' | 'img';
+    style: CssStyle;
+    text?: string;
+    src?: string;
+    /**
+     * 有值才是可点的，动作和上下文都已经绑好，框架层直接挂上去即可。
+     *
+     * 【框架层必须遵守】挂上去时要阻止冒泡。
+     * 父子都可点是常见排版——公告条整条点开弹窗、行末 × 关闭公告条——
+     * 不阻止的话点 × 会连带触发外层，关掉的瞬间又弹出来。
+     * 没有 onClick 的节点不要绑任何事件，让它正常冒泡到有 onClick 的祖先。
+     */
+    onClick?: () => void;
+    children?: RenderElement[];
+}
+/**
+ * 一个视图层。框架层照着这个结构套四层 div 就行，不需要自带任何 CSS：
+ *
+ *   div(layerStyle)
+ *     div(maskStyle)          ← mask 为 true 时才画
+ *     div(scrollStyle)
+ *       div(stageStyle)
+ *         div(clipStyle)      ← 圆角裁切，关闭按钮留在外面才能溢出
+ *           ...nodes
+ *         closeButton         ← 有配才有
+ */
+interface RenderLayer {
+    /** 视图名，同时用作 key */
+    name: string;
+    type: DslViewType;
+    isTop: boolean;
+    /** 画不画遮罩。只有栈顶的弹窗层才为 true */
+    mask: boolean;
+    onMaskClick?: () => void;
+    layerStyle: CssStyle;
+    maskStyle: CssStyle;
+    scrollStyle: CssStyle;
+    stageStyle: CssStyle;
+    clipStyle: CssStyle;
+    /** 关闭按钮，没配就是 undefined */
+    closeButton?: RenderElement;
+    nodes: RenderElement[];
+}
+interface RenderTree {
+    /** 数据没回来或加载失败时为 false，框架层什么都不画 */
+    ready: boolean;
+    /** 有弹窗层时框架层需要撑满宿主容器 */
+    hasPopup: boolean;
+    /** 根容器样式，已按 hasPopup 算好 */
+    rootStyle: CssStyle;
+    layers: RenderLayer[];
+    /** 这一轮里所有倒计时的结束时间戳，运行时据此决定要不要起定时器 */
+    countdownEndTimes: number[];
+    /** 只要有一个倒计时要厘秒，整体就按厘秒刷 */
+    countdownPrecision: 's' | 'cs';
+}
+type DslSource = (params: Record<string, unknown>, user: Record<string, unknown>) => unknown | Promise<unknown>;
+type DslHandler = (params: Record<string, unknown>) => void;
+interface RuntimeEvents {
+    ready: {
+        keys: string[];
+    };
+    close: {
+        reason: string;
+    };
+    track: {
+        event: string;
+        params: Record<string, unknown>;
+    };
+    navigate: {
+        url: string;
+        target: string;
+    };
+    call: {
+        name: string;
+        params: Record<string, unknown>;
+    };
+    'state-change': Record<string, unknown>;
+    'view-change': {
+        view: string;
+        mode: string;
+        stack: string[];
+        closed?: string;
+    };
+    open: {
+        view: string;
+        mode: string;
+    };
+    error: {
+        type: 'unknown-source';
+        name: string;
+    } | {
+        type: 'unknown-view';
+        name: string;
+    } | {
+        type: 'unknown-handler';
+        name: string;
+    } | {
+        type: 'unknown-action';
+        action: string;
+    } | {
+        type: 'unsafe-url';
+        raw: string;
+    } | {
+        type: 'data-source-failed';
+        message: string;
+    };
+}
+type RuntimeEventName = keyof RuntimeEvents;
+type RuntimeEmit = <K extends RuntimeEventName>(event: K, payload: RuntimeEvents[K]) => void;
+interface RuntimeOptions {
+    /** 宿主注入的用户上下文，配置里用 {{ user.xxx }} 读 */
+    user?: Record<string, unknown>;
+    /** 数据源白名单 */
+    sources?: Record<string, DslSource>;
+    /** call 动作的方法白名单 */
+    handlers?: Record<string, DslHandler>;
+    /** 编辑态：动作只上报不真正执行 */
+    editMode?: boolean;
+    /** 所有事件都从这里出去，宿主自己决定怎么处理 */
+    emit?: RuntimeEmit;
+}
+
+/**
+ * 运行时。
+ *
+ * 持有全部可变状态（state / 数据 / 视图栈），并在状态变化时通知订阅者。
+ * 框架层只做两件事：订阅、拿 getTree() 的结果画出来。
+ *
+ * 这里不碰 DOM，也不认识任何框架——换 Vue3 / React 时这个文件一行都不用改。
+ */
+
+interface DslRuntime {
+    /** 当前渲染树。每次 subscribe 回调后重新取 */
+    getTree: () => RenderTree;
+    /** 状态变化时回调，返回取消订阅的函数 */
+    subscribe: (listener: () => void) => () => void;
+    /** 供调试台等外部读取，正常渲染不需要 */
+    getState: () => Record<string, unknown>;
+    getViewStack: () => string[];
+    /** 卸载时必须调用，否则倒计时定时器不会停 */
+    destroy: () => void;
+}
+declare function createRuntime(dsl: Dsl, options?: RuntimeOptions): DslRuntime;
+
+/**
+ * DSL 校验
+ *
+ * 三层校验里的「编辑器」和「后端保存」两层都应该跑这个逻辑。
+ * 运行时是第三层，走的是「遇到不认识的节点跳过、不崩」的降级策略。
+ *
+ * 这个文件不依赖任何框架和 DOM，后端用 Node 跑校验也可以直接引。
+ */
+
+interface Issue {
+    path: string;
+    message: string;
+}
+interface ValidateResult {
+    valid: boolean;
+    errors: Issue[];
+    warnings: Issue[];
+}
+declare const DSL_VERSION = 1;
+declare const NODE_TYPES: string[];
+declare const ACTION_TYPES: string[];
+declare const CLOSE_POSITIONS: string[];
+declare function validate(dsl: Dsl | unknown): ValidateResult;
+/** 把校验结果拼成可以直接展示的文本 */
+declare function formatIssues(issues: Issue[]): string;
+
+/**
+ * 视图归一化。
+ *
+ * 一份 DSL 有两种写法：
+ *   单视图（也是绝大多数场景）：顶层直接写 type / stage / nodes
+ *   多视图：写 views + entry，用来做「公告条点开弹窗」「二次确认」这类叠加
+ *
+ * 运行时和校验都只认归一化之后的结构，省得到处判断两种形态。
+ */
+
+declare const SINGLE_VIEW_NAME = "main";
+interface NormalizedViews {
+    entry: string;
+    views: Record<string, DslView>;
+    isMulti: boolean;
+}
+declare function normalizeViews(dsl: Dsl | null | undefined): NormalizedViews;
+
+/**
+ * 受限表达式求值器
+ *
+ * 设计原则：配置是数据，永远不能变成可执行代码。
+ * 因此这里手写词法 + 递归下降语法分析，绝不使用 eval / new Function。
+ *
+ * 支持：取值(a.b.c / a[0])、字面量、! - 一元、+ - * / %、比较、&& ||、三元
+ * 不支持：函数调用、赋值、new、正则、对象/数组字面量
+ */
+type Context = Record<string, unknown>;
+/** 求值单个表达式；出错时返回 undefined，不让配置写错把整个弹窗搞崩 */
+declare function evaluate(source: string, context: Context): unknown;
+/** 校验表达式是否合法，供编辑器和保存前校验使用。合法返回空字符串 */
+declare function check(source: string): string;
+/**
+ * 插值。整串只有一个 {{ }} 时返回原始类型（保留数字/布尔），
+ * 否则按字符串拼接。
+ */
+declare function interpolate(input: unknown, context: Context): unknown;
+/** 深度插值：对象/数组里所有字符串都跑一遍插值 */
+declare function interpolateDeep<T>(input: T, context: Context): T;
+
+/**
+ * style 白名单 → CSS
+ *
+ * 只有登记在册的属性才会被输出，运营配置里写别的会被直接丢弃。
+ * 这样能挡住 position:fixed 全屏覆盖、z-index 越权这类通过样式做的坏事。
+ */
+
+/**
+ * 长度值：数字按 px 处理，字符串原样透传，
+ * 这样 "100%" / "auto" / "calc(100% - 24px)" / "2rem" 都能用。
+ */
+declare function toLength(value: unknown): string;
+/** 校验用：判断一个值是否是合法长度 */
+declare function isLength(value: unknown): boolean;
+declare const ALLOWED_STYLE_KEYS: string[];
+/** 把 DSL 的 style 对象转成行内样式对象 */
+declare function toCssStyle(style?: DslStyle): CssStyle;
+
+/**
+ * URL 白名单
+ *
+ * 运营能填的任何链接都要过这里。
+ * 重点是挡掉 javascript: 和 data:text/html —— 否则一个「跳转链接」字段
+ * 就等价于开了 JS 执行权限，前面所有的沙箱设计都白做了。
+ */
+/** 不安全的链接返回空字符串，调用方据此判断是否拦截 */
+declare function safeUrl(input: unknown): string;
+/** 图片额外允许 data:image/*，方便 base64 占位图 */
+declare function safeImageUrl(input: unknown): string;
+
+/**
+ * 倒计时。只负责「算时间」，不负责「长什么样」。
+ *
+ * 时间是运行时数据，DSL 表达不了，所以必须由解释器提供；
+ * 但显示形态（一行文字 / 分格数字 / 带厘秒）是排版，留在 DSL 里。
+ * 所以这里只把时间片段算出来注入上下文，排版由 children 自己决定。
+ *
+ * 剩余时间按「结束时间 − 当前时间」实时算，不是逐帧递减：
+ * 浏览器把后台标签页暂停后再切回来，显示会自动校准，不会走慢。
+ */
+interface CountdownParts {
+    /** 天数 */
+    d: string;
+    /** 小时 0~23，已补零 */
+    h: string;
+    /** 总小时数，用于 143:58:07 这种不按天折算的写法 */
+    hAll: string;
+    /** 分，已补零 */
+    m: string;
+    /** 秒，已补零 */
+    s: string;
+    /** 厘秒，已补零。只在 precision 为 cs 时有意义 */
+    cs: string;
+    /** 是否已结束 */
+    ended: boolean;
+}
+type CountdownPrecision = 's' | 'cs';
+/** 把 to 解析成时间戳。兼容 '2026-09-01 00:00:00' 这种 Safari 不认的格式 */
+declare function parseEndTime(to: unknown): number;
+/** 算出某个时刻的时间片段 */
+declare function computeParts(endTime: number, now?: number): CountdownParts;
+/** 不给 children 时退化成一行文本，占位符 {d} {h} {hAll} {m} {s} {cs} */
+declare function formatParts(parts: CountdownParts, format?: string): string;
+
+export { ACTION_TYPES, ALLOWED_STYLE_KEYS, CLOSE_POSITIONS, type CountdownParts, type CountdownPrecision, type CssStyle, DSL_VERSION, type Dsl, type DslAction, type DslActionBase, type DslCallAction, type DslCloseAction, type DslCloseAllAction, type DslCloseButton, type DslClosePosition, type DslDerived, type DslHandler, type DslLength, type DslNavigateAction, type DslNode, type DslNodeType, type DslOpenAction, type DslRect, type DslRuntime, type DslSequenceAction, type DslSetStateAction, type DslSource, type DslSourceRef, type DslStage, type DslStyle, type DslTrackAction, type DslView, type DslViewType, type Issue, NODE_TYPES, type NormalizedViews, type RenderElement, type RenderLayer, type RenderTree, type RuntimeEmit, type RuntimeEventName, type RuntimeEvents, type RuntimeOptions, SINGLE_VIEW_NAME, type ValidateResult, check, computeParts, createRuntime, evaluate, formatIssues, formatParts, interpolate, interpolateDeep, isLength, normalizeViews, parseEndTime, safeImageUrl, safeUrl, toCssStyle, toLength, validate };