@yaoxiu/marketing-dsl 2.3.0 → 2.4.0

package/dist/{types-Bj0xyWnx.d.cts → types-8FNxDXp0.d.cts}

@@ -15,6 +15,40 @@ type DslLength = number | string;
 type DslRect = [DslLength, DslLength, DslLength, DslLength];
 /** 样式对象，键必须在白名单内，值可以带 {{ }} */
 type DslStyle = Record<string, unknown>;
+/**
+ * 动画声明。
+ *
+ * 只描述「播哪一组 keyframes、怎么播」，关键帧本身写在 `Dsl.keyframes` 里。
+ * 解释器把它落成**行内** `animation` 简写，keyframes 定义才进 `RenderTree.css`——
+ * 这样同一份配置在页面上出现多次也不会互相污染（keyframes 名带作用域前缀）。
+ */
+interface DslAnimate {
+    /** keyframes 名：必须在 `dsl.keyframes` 里定义过 */
+    name: string;
+    /** 时长，毫秒 */
+    duration: number;
+    /** 延迟，毫秒，默认 0。交错入场就靠它错开 */
+    delay?: number;
+    /**
+     * 缓动函数。白名单：
+     * linear / ease / ease-in / ease-out / ease-in-out / step-start / step-end /
+     * cubic-bezier(x, x, x, x)。默认 `ease`
+     */
+    easing?: string;
+    /** 播放次数，默认 1；`'infinite'` 表示无限循环（呼吸、扫光这类） */
+    iteration?: number | 'infinite';
+    /** 播放方向，默认 `normal` */
+    direction?: 'normal' | 'reverse' | 'alternate' | 'alternate-reverse';
+    /** 填充模式，默认 `both`（入场动画必须保留终态，否则播完会弹回初始值） */
+    fill?: 'none' | 'forwards' | 'backwards' | 'both';
+}
+/**
+ * 一组关键帧：偏移量 → 样式。
+ *
+ * 偏移量只接受 `'from'` / `'to'` / `'0%'` 这三种写法；
+ * 样式仍要过 style 白名单，写了白名单外的属性会被丢弃。
+ */
+type DslKeyframe = Record<string, DslStyle>;
 interface DslActionBase {
     type: string;
 }
@@ -65,6 +99,15 @@ interface DslNode {
     /** 表达式，为假时整个节点不渲染 */
     visibleWhen?: string;
     action?: DslAction;
+    /** 入场 / 循环动画 */
+    animate?: DslAnimate;
+    /**
+     * 鼠标悬停时叠加的样式。
+     *
+     * **只会生成 CSS 规则，不进行内联**——行内样式没有 `:hover` 这个东西，
+     * 想在行内做只能靠 JS 监听鼠标事件，那既要框架壳配合、又天然丢触屏。
+     */
+    hoverStyle?: DslStyle;
     /** box / flex / countdown */
     children?: DslNode[];
     /** repeat / tabs：数组来源表达式 */
@@ -86,6 +129,14 @@ interface DslNode {
     text?: string;
     /** countdown */
     to?: string;
+    /**
+     * countdown 的相对时长（毫秒）。
+     *
+     * 从**该视图展示那一刻**起算，「每次打开重新倒 5 分钟」这类写法用它。
+     * 与 `to` 同时存在时 `to` 优先（绝对时间更明确）。
+     * 起算时间戳钉在运行时里，重算渲染树不会把剩余时间刷回去。
+     */
+    duration?: number;
     precision?: 's' | 'cs';
     as?: string;
     format?: string;
@@ -95,6 +146,15 @@ interface DslNode {
 type DslClosePosition = 'top-right' | 'top-left' | 'top-center' | 'bottom-right' | 'bottom-left' | 'bottom-center';
 interface DslCloseButton {
     show?: boolean;
+    /**
+     * 点它做什么。
+     *
+     * 不配就是默认行为「关掉当前这一层」（多视图里等于弹栈退回上一层，单视图即整体关闭）。
+     * 配了就**只**执行这个动作、不再自动关层 —— 「点 ✕ 先弹二次挽留」正是靠它：
+     * `{ "type": "open", "view": "confirm", "mode": "stack" }`。
+     * 想在动作里顺带关掉，自己写 `close` / `closeAll` 进去。
+     */
+    action?: DslAction;
     position?: DslClosePosition;
     /** [x, y]，负值把按钮移到弹窗外面 */
     offset?: [DslLength, DslLength];
@@ -102,6 +162,10 @@ interface DslCloseButton {
     icon?: string;
     image?: string;
     style?: DslStyle;
+    /** 悬停样式，只生成 CSS 规则 */
+    hoverStyle?: DslStyle;
+    /** 关闭按钮自己的动画（如延迟淡入，先让用户看内容） */
+    animate?: DslAnimate;
 }
 interface DslStage {
     width?: DslLength;
@@ -110,8 +174,30 @@ interface DslStage {
     layout?: 'absolute' | 'flow';
     mask?: boolean;
     maskClosable?: boolean;
+    /**
+     * 点遮罩做什么。
+     *
+     * 不配就是默认行为「关掉当前这一层」。配了就执行这个动作而不关层
+     * （原页面点遮罩弹二次挽留就是这么来的）。
+     *
+     * 与 `maskClosable` 各管一件事、不冲突：`maskClosable: false` 时遮罩根本不响应点击，
+     * 这个动作也不会执行；`maskAction` 只决定「点了之后做什么」。
+     */
+    maskAction?: DslAction;
     closeButton?: DslCloseButton;
+    /**
+     * 遮罩自身样式，走 style 白名单。
+     *
+     * 内置默认是 `rgba(0, 0, 0, 0.55)` 纯色，这里配的会**覆盖**默认值
+     * （常用 `background` 改深浅、`backdropFilter: 'blur(4px)'` 加毛玻璃）。
+     * `maskAnimate` 生成的 `animation` 仍排在最后，不会被这里的配置盖掉。
+     */
+    maskStyle?: DslStyle;
     style?: DslStyle;
+    /** 舞台入场动画（弹窗主体的弹入 / 放大） */
+    animate?: DslAnimate;
+    /** 遮罩入场动画（一般是淡入，和舞台分开配才能各走各的时长） */
+    maskAnimate?: DslAnimate;
     /** 曝光埋点：数据就绪、视图真正展示时触发一次 */
     onShow?: DslAction;
     /** 关闭埋点：点 X、点遮罩、close 动作、被 replace 顶掉都会触发 */
@@ -145,6 +231,13 @@ interface Dsl extends Partial<DslView> {
     derived?: Record<string, DslDerived>;
     views?: Record<string, DslView>;
     entry?: string;
+    /**
+     * 关键帧库，`{ 名字: { 偏移量: 样式 } }`。
+     *
+     * 全配置共用一份（多视图之间也共用），`animate.name` 引用这里的名字。
+     * 名字只能是 `^[a-zA-Z][a-zA-Z0-9_-]{0,31}$`——它会被拼进 CSS 文本，必须可控。
+     */
+    keyframes?: Record<string, DslKeyframe>;
 }
 /** 已经算好的行内样式，键是 CSS 属性名（驼峰），值是最终字符串 */
 type CssStyle = Record<string, string>;
@@ -198,8 +291,15 @@ interface RenderLayer {
     name: string;
     type: DslViewType;
     isTop: boolean;
-    /** 画不画遮罩。只有栈顶的弹窗层才为 true */
+    /**
+     * 画不画遮罩元素。弹窗层恒为 true（`stage.mask: false` 除外），**包括非栈顶的层**。
+     *
+     * 遮挡效果由 `maskStyle` 控制：非栈顶层的底色是 transparent，实际遮挡永远只有栈顶那层
+     * （两层实心遮罩叠加会明显变黑）。元素本身常驻是刻意的 —— 按 isTop 增删这个 DOM 节点，
+     * 会让下层的 `maskAnimate` 在退回栈顶时重播一遍，表现为「关掉二次挽留层，背景闪了一下」。
+     */
     mask: boolean;
+    /** 点遮罩的回调。只有栈顶那层才有：非栈顶层整层 pointerEvents: none，点不到 */
     onMaskClick?: () => void;
     layerStyle: CssStyle;
     maskStyle: CssStyle;
@@ -227,6 +327,20 @@ interface RenderTree {
     countdownEndTimes: number[];
     /** 只要有一个倒计时要厘秒，整体就按厘秒刷 */
     countdownPrecision: 's' | 'cs';
+    /**
+     * 这份配置要注入页面的全部 CSS 文本（keyframes 定义 + hover 规则 + reduced-motion 兜底）。
+     *
+     * 没有动画也没有 hover 时是**空串**，此时框架壳不该建 `<style>` 元素。
+     * 内容已经过安全过滤，壳直接塞进 `<style>` 即可，**不得在壳里做任何生成或判断**。
+     */
+    css: string;
+    /**
+     * 根容器类名，形如 `dsl-renderer dsl-r3`。
+     *
+     * 后半截是这个运行时实例的作用域前缀，`css` 里的每条规则都挂在它下面——
+     * 同一个页面上出现多份物料时，各自的 hover 规则不会串台。
+     */
+    rootClassName: string;
 }
 type DslSource = (params: Record<string, unknown>, user: Record<string, unknown>) => unknown | Promise<unknown>;
 type DslHandler = (params: Record<string, unknown>) => void;
@@ -342,4 +456,4 @@ interface RuntimeOptions {
     emit?: RuntimeEmit;
 }
 
-export type { DslHandler as A, DslInteractionTrigger as B, CssStyle as C, Dsl as D, DslInteractionEvent as E, RuntimeEvents as F, RuntimeEventName as G, RuntimeEmit as H, 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 };
+export type { RenderLayer as A, DslSource as B, CssStyle as C, Dsl as D, DslHandler as E, DslInteractionTrigger as F, DslInteractionEvent as G, RuntimeEvents as H, RuntimeEventName as I, RuntimeEmit as J, RuntimeOptions as R, RenderTree as a, DslView as b, DslStyle as c, DslViewType as d, DslNodeType as e, DslLength as f, DslRect as g, DslAnimate as h, DslKeyframe as i, DslActionBase as j, DslNavigateAction as k, DslCloseAction as l, DslCloseAllAction as m, DslOpenAction as n, DslSetStateAction as o, DslTrackAction as p, DslCallAction as q, DslSequenceAction as r, DslAction as s, DslNode as t, DslClosePosition as u, DslCloseButton as v, DslStage as w, DslSourceRef as x, DslDerived as y, RenderElement as z };

package/dist/{types-Bj0xyWnx.d.ts → types-8FNxDXp0.d.ts}

@@ -15,6 +15,40 @@ type DslLength = number | string;
 type DslRect = [DslLength, DslLength, DslLength, DslLength];
 /** 样式对象，键必须在白名单内，值可以带 {{ }} */
 type DslStyle = Record<string, unknown>;
+/**
+ * 动画声明。
+ *
+ * 只描述「播哪一组 keyframes、怎么播」，关键帧本身写在 `Dsl.keyframes` 里。
+ * 解释器把它落成**行内** `animation` 简写，keyframes 定义才进 `RenderTree.css`——
+ * 这样同一份配置在页面上出现多次也不会互相污染（keyframes 名带作用域前缀）。
+ */
+interface DslAnimate {
+    /** keyframes 名：必须在 `dsl.keyframes` 里定义过 */
+    name: string;
+    /** 时长，毫秒 */
+    duration: number;
+    /** 延迟，毫秒，默认 0。交错入场就靠它错开 */
+    delay?: number;
+    /**
+     * 缓动函数。白名单：
+     * linear / ease / ease-in / ease-out / ease-in-out / step-start / step-end /
+     * cubic-bezier(x, x, x, x)。默认 `ease`
+     */
+    easing?: string;
+    /** 播放次数，默认 1；`'infinite'` 表示无限循环（呼吸、扫光这类） */
+    iteration?: number | 'infinite';
+    /** 播放方向，默认 `normal` */
+    direction?: 'normal' | 'reverse' | 'alternate' | 'alternate-reverse';
+    /** 填充模式，默认 `both`（入场动画必须保留终态，否则播完会弹回初始值） */
+    fill?: 'none' | 'forwards' | 'backwards' | 'both';
+}
+/**
+ * 一组关键帧：偏移量 → 样式。
+ *
+ * 偏移量只接受 `'from'` / `'to'` / `'0%'` 这三种写法；
+ * 样式仍要过 style 白名单，写了白名单外的属性会被丢弃。
+ */
+type DslKeyframe = Record<string, DslStyle>;
 interface DslActionBase {
     type: string;
 }
@@ -65,6 +99,15 @@ interface DslNode {
     /** 表达式，为假时整个节点不渲染 */
     visibleWhen?: string;
     action?: DslAction;
+    /** 入场 / 循环动画 */
+    animate?: DslAnimate;
+    /**
+     * 鼠标悬停时叠加的样式。
+     *
+     * **只会生成 CSS 规则，不进行内联**——行内样式没有 `:hover` 这个东西，
+     * 想在行内做只能靠 JS 监听鼠标事件，那既要框架壳配合、又天然丢触屏。
+     */
+    hoverStyle?: DslStyle;
     /** box / flex / countdown */
     children?: DslNode[];
     /** repeat / tabs：数组来源表达式 */
@@ -86,6 +129,14 @@ interface DslNode {
     text?: string;
     /** countdown */
     to?: string;
+    /**
+     * countdown 的相对时长（毫秒）。
+     *
+     * 从**该视图展示那一刻**起算，「每次打开重新倒 5 分钟」这类写法用它。
+     * 与 `to` 同时存在时 `to` 优先（绝对时间更明确）。
+     * 起算时间戳钉在运行时里，重算渲染树不会把剩余时间刷回去。
+     */
+    duration?: number;
     precision?: 's' | 'cs';
     as?: string;
     format?: string;
@@ -95,6 +146,15 @@ interface DslNode {
 type DslClosePosition = 'top-right' | 'top-left' | 'top-center' | 'bottom-right' | 'bottom-left' | 'bottom-center';
 interface DslCloseButton {
     show?: boolean;
+    /**
+     * 点它做什么。
+     *
+     * 不配就是默认行为「关掉当前这一层」（多视图里等于弹栈退回上一层，单视图即整体关闭）。
+     * 配了就**只**执行这个动作、不再自动关层 —— 「点 ✕ 先弹二次挽留」正是靠它：
+     * `{ "type": "open", "view": "confirm", "mode": "stack" }`。
+     * 想在动作里顺带关掉，自己写 `close` / `closeAll` 进去。
+     */
+    action?: DslAction;
     position?: DslClosePosition;
     /** [x, y]，负值把按钮移到弹窗外面 */
     offset?: [DslLength, DslLength];
@@ -102,6 +162,10 @@ interface DslCloseButton {
     icon?: string;
     image?: string;
     style?: DslStyle;
+    /** 悬停样式，只生成 CSS 规则 */
+    hoverStyle?: DslStyle;
+    /** 关闭按钮自己的动画（如延迟淡入，先让用户看内容） */
+    animate?: DslAnimate;
 }
 interface DslStage {
     width?: DslLength;
@@ -110,8 +174,30 @@ interface DslStage {
     layout?: 'absolute' | 'flow';
     mask?: boolean;
     maskClosable?: boolean;
+    /**
+     * 点遮罩做什么。
+     *
+     * 不配就是默认行为「关掉当前这一层」。配了就执行这个动作而不关层
+     * （原页面点遮罩弹二次挽留就是这么来的）。
+     *
+     * 与 `maskClosable` 各管一件事、不冲突：`maskClosable: false` 时遮罩根本不响应点击，
+     * 这个动作也不会执行；`maskAction` 只决定「点了之后做什么」。
+     */
+    maskAction?: DslAction;
     closeButton?: DslCloseButton;
+    /**
+     * 遮罩自身样式，走 style 白名单。
+     *
+     * 内置默认是 `rgba(0, 0, 0, 0.55)` 纯色，这里配的会**覆盖**默认值
+     * （常用 `background` 改深浅、`backdropFilter: 'blur(4px)'` 加毛玻璃）。
+     * `maskAnimate` 生成的 `animation` 仍排在最后，不会被这里的配置盖掉。
+     */
+    maskStyle?: DslStyle;
     style?: DslStyle;
+    /** 舞台入场动画（弹窗主体的弹入 / 放大） */
+    animate?: DslAnimate;
+    /** 遮罩入场动画（一般是淡入，和舞台分开配才能各走各的时长） */
+    maskAnimate?: DslAnimate;
     /** 曝光埋点：数据就绪、视图真正展示时触发一次 */
     onShow?: DslAction;
     /** 关闭埋点：点 X、点遮罩、close 动作、被 replace 顶掉都会触发 */
@@ -145,6 +231,13 @@ interface Dsl extends Partial<DslView> {
     derived?: Record<string, DslDerived>;
     views?: Record<string, DslView>;
     entry?: string;
+    /**
+     * 关键帧库，`{ 名字: { 偏移量: 样式 } }`。
+     *
+     * 全配置共用一份（多视图之间也共用），`animate.name` 引用这里的名字。
+     * 名字只能是 `^[a-zA-Z][a-zA-Z0-9_-]{0,31}$`——它会被拼进 CSS 文本，必须可控。
+     */
+    keyframes?: Record<string, DslKeyframe>;
 }
 /** 已经算好的行内样式，键是 CSS 属性名（驼峰），值是最终字符串 */
 type CssStyle = Record<string, string>;
@@ -198,8 +291,15 @@ interface RenderLayer {
     name: string;
     type: DslViewType;
     isTop: boolean;
-    /** 画不画遮罩。只有栈顶的弹窗层才为 true */
+    /**
+     * 画不画遮罩元素。弹窗层恒为 true（`stage.mask: false` 除外），**包括非栈顶的层**。
+     *
+     * 遮挡效果由 `maskStyle` 控制：非栈顶层的底色是 transparent，实际遮挡永远只有栈顶那层
+     * （两层实心遮罩叠加会明显变黑）。元素本身常驻是刻意的 —— 按 isTop 增删这个 DOM 节点，
+     * 会让下层的 `maskAnimate` 在退回栈顶时重播一遍，表现为「关掉二次挽留层，背景闪了一下」。
+     */
     mask: boolean;
+    /** 点遮罩的回调。只有栈顶那层才有：非栈顶层整层 pointerEvents: none，点不到 */
     onMaskClick?: () => void;
     layerStyle: CssStyle;
     maskStyle: CssStyle;
@@ -227,6 +327,20 @@ interface RenderTree {
     countdownEndTimes: number[];
     /** 只要有一个倒计时要厘秒，整体就按厘秒刷 */
     countdownPrecision: 's' | 'cs';
+    /**
+     * 这份配置要注入页面的全部 CSS 文本（keyframes 定义 + hover 规则 + reduced-motion 兜底）。
+     *
+     * 没有动画也没有 hover 时是**空串**，此时框架壳不该建 `<style>` 元素。
+     * 内容已经过安全过滤，壳直接塞进 `<style>` 即可，**不得在壳里做任何生成或判断**。
+     */
+    css: string;
+    /**
+     * 根容器类名，形如 `dsl-renderer dsl-r3`。
+     *
+     * 后半截是这个运行时实例的作用域前缀，`css` 里的每条规则都挂在它下面——
+     * 同一个页面上出现多份物料时，各自的 hover 规则不会串台。
+     */
+    rootClassName: string;
 }
 type DslSource = (params: Record<string, unknown>, user: Record<string, unknown>) => unknown | Promise<unknown>;
 type DslHandler = (params: Record<string, unknown>) => void;
@@ -342,4 +456,4 @@ interface RuntimeOptions {
     emit?: RuntimeEmit;
 }
 
-export type { DslHandler as A, DslInteractionTrigger as B, CssStyle as C, Dsl as D, DslInteractionEvent as E, RuntimeEvents as F, RuntimeEventName as G, RuntimeEmit as H, 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 };
+export type { RenderLayer as A, DslSource as B, CssStyle as C, Dsl as D, DslHandler as E, DslInteractionTrigger as F, DslInteractionEvent as G, RuntimeEvents as H, RuntimeEventName as I, RuntimeEmit as J, RuntimeOptions as R, RenderTree as a, DslView as b, DslStyle as c, DslViewType as d, DslNodeType as e, DslLength as f, DslRect as g, DslAnimate as h, DslKeyframe as i, DslActionBase as j, DslNavigateAction as k, DslCloseAction as l, DslCloseAllAction as m, DslOpenAction as n, DslSetStateAction as o, DslTrackAction as p, DslCallAction as q, DslSequenceAction as r, DslAction as s, DslNode as t, DslClosePosition as u, DslCloseButton as v, DslStage as w, DslSourceRef as x, DslDerived as y, RenderElement as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaoxiu/marketing-dsl",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "type": "module",
   "description": "营销弹窗 DSL 解释器核心，纯逻辑无框架依赖",
   "license": "MIT",