@yaoxiu/marketing-dsl 1.2.0 → 1.4.0

package/dist/types-BgUaJUAu.d.cts

@@ -0,0 +1,293 @@
+/**
+ * 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 就是容器。
+     * svg / line 用来画矢量图标（如默认的关闭 ×），形状与尺寸都由 core 算好。
+     */
+    tag: 'div' | 'img' | 'svg' | 'line';
+    /**
+     * 类名，如 "dsl-node dsl-text is-clickable"。
+     * 不参与样式（样式全在 style 里），纯粹是留给调试和宿主微调的钩子。
+     * 由 core 统一生成，不让各框架壳各拼一套，否则 DOM 结构会慢慢跑偏。
+     */
+    className: string;
+    style: CssStyle;
+    text?: string;
+    src?: string;
+    /**
+     * 直接落到 DOM 上的属性（`viewBox`、`stroke-width` 这类带连字符的 SVG 属性）。
+     * 框架层必须用 setAttribute 语义写入（Vue 2 里就是 `attrs`），不能走 domProps——
+     * SVG 元素上没有对应的 JS 属性，写 property 不生效。
+     */
+    attrs?: Record<string, 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;
+}
+
+export type { DslHandler as A, RuntimeEvents as B, CssStyle as C, Dsl as D, RuntimeEventName as E, RuntimeEmit as F, RuntimeOptions as R, RenderTree as a, DslView as b, DslStyle as c, DslViewType as d, DslNodeType as e, DslLength as f, DslRect as g, DslActionBase as h, DslNavigateAction as i, DslCloseAction as j, DslCloseAllAction as k, DslOpenAction as l, DslSetStateAction as m, DslTrackAction as n, DslCallAction as o, DslSequenceAction as p, DslAction as q, DslNode as r, DslClosePosition as s, DslCloseButton as t, DslStage as u, DslSourceRef as v, DslDerived as w, RenderElement as x, RenderLayer as y, DslSource as z };

package/dist/types-BgUaJUAu.d.ts

@@ -0,0 +1,293 @@
+/**
+ * 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 就是容器。
+     * svg / line 用来画矢量图标（如默认的关闭 ×），形状与尺寸都由 core 算好。
+     */
+    tag: 'div' | 'img' | 'svg' | 'line';
+    /**
+     * 类名，如 "dsl-node dsl-text is-clickable"。
+     * 不参与样式（样式全在 style 里），纯粹是留给调试和宿主微调的钩子。
+     * 由 core 统一生成，不让各框架壳各拼一套，否则 DOM 结构会慢慢跑偏。
+     */
+    className: string;
+    style: CssStyle;
+    text?: string;
+    src?: string;
+    /**
+     * 直接落到 DOM 上的属性（`viewBox`、`stroke-width` 这类带连字符的 SVG 属性）。
+     * 框架层必须用 setAttribute 语义写入（Vue 2 里就是 `attrs`），不能走 domProps——
+     * SVG 元素上没有对应的 JS 属性，写 property 不生效。
+     */
+    attrs?: Record<string, 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;
+}
+
+export type { DslHandler as A, RuntimeEvents as B, CssStyle as C, Dsl as D, RuntimeEventName as E, RuntimeEmit as F, RuntimeOptions as R, RenderTree as a, DslView as b, DslStyle as c, DslViewType as d, DslNodeType as e, DslLength as f, DslRect as g, DslActionBase as h, DslNavigateAction as i, DslCloseAction as j, DslCloseAllAction as k, DslOpenAction as l, DslSetStateAction as m, DslTrackAction as n, DslCallAction as o, DslSequenceAction as p, DslAction as q, DslNode as r, DslClosePosition as s, DslCloseButton as t, DslStage as u, DslSourceRef as v, DslDerived as w, RenderElement as x, RenderLayer as y, DslSource as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaoxiu/marketing-dsl",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "type": "module",
   "description": "营销弹窗 DSL 解释器核心，纯逻辑无框架依赖",
   "license": "MIT",
@@ -16,6 +16,11 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
+    },
+    "./docs": {
+      "types": "./dist/docs/index.d.ts",
+      "import": "./dist/docs/index.js",
+      "require": "./dist/docs/index.cjs"
     }
   },
   "files": [