@yaoxiu/marketing-dsl 1.5.2 → 2.1.0

package/dist/index.cjs

@@ -327,13 +327,13 @@ function safeImageUrl(input) {
 // src/actions.ts
 function createDispatcher(options) {
   const { setState, emit, openView, closeTop, closeAll } = options;
-  function dispatch(action, context) {
+  function run(action, context, interaction) {
     if (!action || !action.type) return;
     const handlers = options.handlers || {};
     const editMode = !!options.editMode;
     switch (action.type) {
       case "sequence":
-        (action.actions || []).forEach((item) => dispatch(item, context));
+        (action.actions || []).forEach((item) => run(item, context, interaction));
         return;
       case "navigate": {
         const url = safeUrl(interpolate(action.url, context));
@@ -343,6 +343,7 @@ function createDispatcher(options) {
         }
         const target = action.target || "_blank";
         emit("navigate", { url, target });
+        if (!interaction.navigate) interaction.navigate = { url, target };
         if (editMode) return;
         if (typeof window === "undefined") return;
         if (target === "_self") window.location.href = url;
@@ -356,20 +357,25 @@ function createDispatcher(options) {
         return;
       // 关掉栈顶那层；只剩一层时就是整体关闭
       case "close":
+        interaction.closes = true;
         closeTop(action.reason);
         return;
       case "closeAll":
+        interaction.closes = true;
         closeAll(action.reason);
         return;
       case "setState":
         setState(action.key, interpolate(action.value, context));
         return;
-      case "track":
-        emit("track", {
+      case "track": {
+        const payload = {
           event: String(interpolate(action.event, context)),
           params: interpolateDeep(action.params || {}, context)
-        });
+        };
+        emit("track", payload);
+        if (!interaction.track) interaction.track = payload;
         return;
+      }
       case "call": {
         const handler = handlers[action.name];
         if (typeof handler !== "function") {
@@ -389,6 +395,13 @@ function createDispatcher(options) {
         });
     }
   }
+  function dispatch(action, context, meta) {
+    if (!action || !action.type) return;
+    const interaction = { trigger: (meta == null ? void 0 : meta.trigger) || "action" };
+    if ((meta == null ? void 0 : meta.reason) !== void 0) interaction.reason = meta.reason;
+    run(action, context, interaction);
+    emit("interaction", interaction);
+  }
   return dispatch;
 }
 
@@ -619,9 +632,7 @@ function resolveNodeStyle(node, layout) {
 function resolveTree(input) {
   const { normalized, viewStack, ready } = input;
   const layers = viewStack.map((name) => ({ name, view: normalized.views[name] })).filter((item) => !!item.view);
-  const hasPopup = Object.keys(normalized.views).some(
-    (name) => normalized.views[name].type === "popup"
-  );
+  const hasPopup = layers.some((item) => item.view.type === "popup");
   const countdowns = { endTimes: [], precision: "s" };
   const renderLayers = ready ? layers.map(
     (item, index) => resolveLayer(
@@ -635,8 +646,10 @@ function resolveTree(input) {
   return {
     ready: ready && layers.length > 0,
     hasPopup,
-    // 配置里有弹窗视图时，根容器要撑满宿主容器，弹窗层才有地方铺
-    rootStyle: hasPopup ? { position: "absolute", top: "0", right: "0", bottom: "0", left: "0" } : { position: "relative" },
+    // 根容器恒为 relative：它要待在宿主给的位置上（banner / 公告坑位是流式的普通 div，
+    // 根容器一脱流坑位就塌成 0、内容按最近定位祖先飘走）。弹窗铺满视口由弹窗层自己
+    // `position: fixed` 完成，不再靠根容器撑开，见 layerStyle。
+    rootStyle: { position: "relative" },
     layers: renderLayers,
     countdownEndTimes: countdowns.endTimes,
     countdownPrecision: countdowns.precision
@@ -682,7 +695,15 @@ function resolveLayer(name, view, isTop, input, countdowns) {
   };
 }
 function layerStyle(isPopup, isTop) {
-  const style = isPopup ? { position: "absolute", top: "0", right: "0", bottom: "0", left: "0" } : {};
+  const style = isPopup ? {
+    position: "fixed",
+    top: "0",
+    right: "0",
+    bottom: "0",
+    left: "0",
+    // 弹窗层可能挂在页面中段的坑位里，不提层会被后面的内容盖住
+    zIndex: "1000"
+  } : {};
   if (!isTop) style.pointerEvents = "none";
   return style;
 }
@@ -710,7 +731,7 @@ function resolveStageStyle(stage, isPopup, context) {
     base.margin = "auto";
     base.flex = "none";
   }
-  return Object.assign(
+  const style = Object.assign(
     base,
     {
       // width / height 支持数字（px）、'100%' / 'auto' / calc(...) 等相对单位，也支持 {{ }}
@@ -724,6 +745,11 @@ function resolveStageStyle(stage, isPopup, context) {
     // stage.style 也走一遍插值，这样切 tab 时弹窗本身的背景能跟着变
     toCssStyle(interpolateDeep(stage.style, context))
   );
+  if (!isPopup && style.maxWidth !== void 0 && style.margin === void 0) {
+    style.marginLeft = "auto";
+    style.marginRight = "auto";
+  }
+  return style;
 }
 function resolveCloseButton(config, layerName, closeTop) {
   if (!config || config.show === false) return void 0;
@@ -1187,7 +1213,11 @@ function createRuntime(dsl, options = {}) {
     const view = normalized.views[viewName];
     const action = view && view.stage && view.stage[hook];
     if (!action) return;
-    dispatch(action, Object.assign({}, buildContext(), extra));
+    const reason = extra && extra.closeReason;
+    dispatch(action, Object.assign({}, buildContext(), extra), {
+      trigger: hook === "onShow" ? "show" : "close",
+      reason: typeof reason === "string" ? reason : void 0
+    });
   }
   function loadData() {
     const data = dsl.data || {};
@@ -1218,8 +1248,8 @@ function createRuntime(dsl, options = {}) {
       resolvedData = resolved;
       loading = false;
       notify();
-      emit("ready", { keys: Object.keys(resolved) });
       fireLifecycle(normalized.entry, "onShow");
+      emit("ready", { keys: Object.keys(resolved) });
     }).catch((error) => {
       if (destroyed) return;
       loading = false;
@@ -1266,6 +1296,120 @@ function createRuntime(dsl, options = {}) {
   };
 }
 
+// src/user-fields.ts
+var DEFAULT_USER_FIELDS = [
+  "shopId",
+  "shopName",
+  "collectCount",
+  "albbCollectCount",
+  "isNewUser",
+  "levelId",
+  "levelName",
+  "serviceExpireTime",
+  "remainDays",
+  "userTypeNew",
+  "serviceInfo"
+];
+var USER_FIELD_LABELS = {
+  shopId: "\u5E97\u94FA ID",
+  shopName: "\u5E97\u94FA\u540D\u79F0",
+  collectCount: "\u5269\u4F59\u91C7\u96C6\u6B21\u6570",
+  albbCollectCount: "\u5269\u4F59 1688 \u91C7\u96C6\u6B21\u6570",
+  isNewUser: "\u662F\u5426\u65B0\u7528\u6237\uFF080 / 1\uFF0C\u53EF\u76F4\u63A5\u7528\u4E8E visibleWhen\uFF09",
+  levelId: "\u7248\u672C ID",
+  levelName: "\u7248\u672C\u540D\u79F0\uFF0C\u5982\u300C\u4E13\u4E1A\u7248\u300D",
+  serviceExpireTime: "\u670D\u52A1\u5230\u671F\u65F6\u95F4\uFF0C\u53EF\u76F4\u63A5\u5582\u7ED9 countdown \u7684 to",
+  remainDays: "\u670D\u52A1\u5269\u4F59\u5929\u6570",
+  userTypeNew: "\u65B0\u5546\u7528\u6237\u7C7B\u578B\uFF080 \u672A\u8BBE\u7F6E / 1 \u6709\u8D27\u6E90 / 2 \u65E0\u8D27\u6E90 / 3 \u4E24\u8005\u517C\u5907\uFF09",
+  serviceInfo: "\u5BA2\u670D\u4E0E\u793E\u7FA4\u4FE1\u606F\uFF08\u5BF9\u8C61\uFF0C\u6309\u9700\u53D6\u5B50\u5B57\u6BB5\uFF09"
+};
+var USER_FIELD_RE = /\buser\s*\.\s*([A-Za-z_$][A-Za-z0-9_$]*)/g;
+var INTERPOLATION_RE2 = /\{\{([\s\S]*?)\}\}/g;
+var RAW_EXPRESSION_KEYS = ["visibleWhen"];
+function editDistance(a, b) {
+  const prev = [];
+  for (let j = 0; j <= b.length; j++) prev[j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    let diagonal = prev[0];
+    prev[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const temp = prev[j];
+      prev[j] = Math.min(
+        prev[j] + 1,
+        prev[j - 1] + 1,
+        diagonal + (a[i - 1] === b[j - 1] ? 0 : 1)
+      );
+      diagonal = temp;
+    }
+  }
+  return prev[b.length];
+}
+function closestField(name, allowed) {
+  const lower = name.toLowerCase();
+  let best = "";
+  let bestScore = Infinity;
+  allowed.forEach((field) => {
+    const score = editDistance(lower, field.toLowerCase());
+    if (score < bestScore) {
+      bestScore = score;
+      best = field;
+    }
+  });
+  return bestScore <= Math.max(3, Math.ceil(name.length / 2)) ? best : "";
+}
+function collectFromExpression(source, into) {
+  USER_FIELD_RE.lastIndex = 0;
+  let matched = USER_FIELD_RE.exec(source);
+  while (matched) {
+    into.push(matched[1]);
+    matched = USER_FIELD_RE.exec(source);
+  }
+}
+function collectFromValue(value, key, into) {
+  if (RAW_EXPRESSION_KEYS.indexOf(key) > -1) {
+    collectFromExpression(value, into);
+    return;
+  }
+  INTERPOLATION_RE2.lastIndex = 0;
+  let matched = INTERPOLATION_RE2.exec(value);
+  while (matched) {
+    collectFromExpression(matched[1], into);
+    matched = INTERPOLATION_RE2.exec(value);
+  }
+}
+function validateUserFields(dsl, allowed) {
+  const issues = [];
+  const seen = [];
+  const walk = (node, path, key) => {
+    if (typeof node === "string") {
+      const names = [];
+      collectFromValue(node, key, names);
+      names.forEach((name) => {
+        if (allowed.indexOf(name) > -1) return;
+        const guess = closestField(name, allowed);
+        issues.push({
+          path,
+          message: `\u7528\u6237\u4FE1\u606F\u91CC\u6CA1\u6709 "user.${name}" \u8FD9\u4E2A\u5B57\u6BB5` + (guess ? `\uFF0C\u662F\u4E0D\u662F\u60F3\u5199 "user.${guess}"\uFF1F` : "") + `\u3002\u53EF\u7528\u5B57\u6BB5\uFF1A${allowed.join(" / ")}`
+        });
+      });
+      return;
+    }
+    if (!node || typeof node !== "object") return;
+    if (seen.indexOf(node) > -1) return;
+    seen.push(node);
+    if (Array.isArray(node)) {
+      node.forEach((item, index) => walk(item, `${path}[${index}]`, key));
+      return;
+    }
+    Object.keys(node).forEach((childKey) => {
+      const childPath = path ? `${path}.${childKey}` : childKey;
+      walk(node[childKey], childPath, childKey);
+    });
+  };
+  walk(dsl, "", "");
+  return issues;
+}
+
 // src/validate.ts
 var LENGTH_STYLE_KEYS = [
   "width",
@@ -1317,7 +1461,7 @@ var CLOSE_POSITIONS = [
   "bottom-center"
 ];
 var CONTAINER_TYPES = ["box", "flex"];
-function validate(dsl) {
+function validate(dsl, options) {
   const errors = [];
   const warnings = [];
   const add = (path, message) => errors.push({ path, message });
@@ -1347,6 +1491,11 @@ function validate(dsl) {
   viewNames.forEach((name) => {
     validateView(views[name], isMulti ? `views.${name}` : "", ctx);
   });
+  if (options && options.userFields) {
+    validateUserFields(doc, options.userFields).forEach(
+      (issue) => add(issue.path, issue.message)
+    );
+  }
   return { valid: errors.length === 0, errors, warnings };
 }
 function validateMultiView(dsl, add) {
@@ -1379,6 +1528,7 @@ function validateView(view, prefix, ctx) {
   if (["popup", "banner", "notice"].indexOf(view.type) === -1) {
     add(at("type"), "type \u5FC5\u987B\u662F popup / banner / notice \u4E4B\u4E00");
   }
+  ctx.viewType = view.type;
   validateStage(
     view.stage,
     (path, message) => add(prefix ? `${prefix}.${path}` : path, message),
@@ -1402,6 +1552,16 @@ function checkLength(value) {
   if (isLength(value)) return true;
   return value.trim().split(/\s+/).every(isLength);
 }
+var BANNER_MIN_ASPECT_RATIO = 12;
+function parseAspectRatio(value) {
+  if (typeof value === "number") return isFinite(value) && value > 0 ? value : null;
+  if (typeof value !== "string" || value.indexOf("{{") > -1) return null;
+  const parts = value.split("/");
+  const width = Number(parts[0]);
+  const height = parts.length > 1 ? Number(parts[1]) : 1;
+  if (!isFinite(width) || !isFinite(height) || width <= 0 || height <= 0) return null;
+  return width / height;
+}
 function checkAspectRatio(value) {
   if (typeof value === "string" && value.indexOf("{{") > -1) return true;
   if (typeof value === "number") return isFinite(value) && value > 0;
@@ -1569,11 +1729,21 @@ function validateNode(node, path, layout, ctx) {
           `"${node.style[key]}" \u4E0D\u662F\u5408\u6CD5\u957F\u5EA6\uFF0C\u652F\u6301\u6570\u5B57(px) / '100%' / 'auto' \u7B49`
         );
       }
-      if (key === "aspectRatio" && !checkAspectRatio(node.style[key])) {
-        add(
-          `${path}.style.aspectRatio`,
-          "aspectRatio \u8981\u5199\u6210 '750 / 200' \u6216 1.5 \u8FD9\u6837\u7684\u5BBD\u9AD8\u6BD4"
-        );
+      if (key === "aspectRatio") {
+        if (!checkAspectRatio(node.style[key])) {
+          add(
+            `${path}.style.aspectRatio`,
+            "aspectRatio \u8981\u5199\u6210 '750 / 200' \u6216 1.5 \u8FD9\u6837\u7684\u5BBD\u9AD8\u6BD4"
+          );
+        } else if (ctx.viewType === "banner") {
+          const ratio = parseAspectRatio(node.style[key]);
+          if (ratio !== null && ratio < BANNER_MIN_ASPECT_RATIO) {
+            add(
+              `${path}.style.aspectRatio`,
+              `banner \u7684\u5BBD\u9AD8\u6BD4\u4E0D\u80FD\u5C0F\u4E8E ${BANNER_MIN_ASPECT_RATIO}:1\uFF08\u5F53\u524D\u7EA6 ${ratio.toFixed(1)}:1\uFF09\u3002banner \u5751\u4F4D\u5E38\u9A7B\u9875\u9762\u9876\u90E8\uFF0C\u6BD4\u4F8B\u8D8A\u65B9\u5728\u5BBD\u5C4F\u4E0A\u8D8A\u9AD8 \u2014\u2014 1800px \u5BBD\u7684\u5751\u4F4D\u91CC\uFF0C${ratio.toFixed(1)}:1 \u4F1A\u7B97\u51FA ${Math.round(1800 / ratio)}px \u9AD8\uFF0C\u5403\u6389\u9996\u5C4F\u4E00\u5927\u5757`
+            );
+          }
+        }
       }
     });
   }
@@ -1706,11 +1876,14 @@ function formatIssues(issues) {
 
 exports.ACTION_TYPES = ACTION_TYPES;
 exports.ALLOWED_STYLE_KEYS = ALLOWED_STYLE_KEYS;
+exports.BANNER_MIN_ASPECT_RATIO = BANNER_MIN_ASPECT_RATIO;
 exports.CLOSE_POSITIONS = CLOSE_POSITIONS;
+exports.DEFAULT_USER_FIELDS = DEFAULT_USER_FIELDS;
 exports.DSL_VERSION = DSL_VERSION;
 exports.NODE_TYPES = NODE_TYPES;
 exports.SINGLE_VIEW_NAME = SINGLE_VIEW_NAME;
 exports.TRACK_EVENT_PATTERN = TRACK_EVENT_PATTERN;
+exports.USER_FIELD_LABELS = USER_FIELD_LABELS;
 exports.check = check;
 exports.computeParts = computeParts;
 exports.createRuntime = createRuntime;
@@ -1728,3 +1901,4 @@ exports.safeUrl = safeUrl;
 exports.toCssStyle = toCssStyle;
 exports.toLength = toLength;
 exports.validate = validate;
+exports.validateUserFields = validateUserFields;

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { D as Dsl, R as RuntimeOptions, a as RenderTree, b as DslView, c as DslStyle, C as CssStyle } from './types-BgUaJUAu.cjs';
-export { q as DslAction, h as DslActionBase, o as DslCallAction, j as DslCloseAction, k as DslCloseAllAction, t as DslCloseButton, s as DslClosePosition, w as DslDerived, A as DslHandler, f as DslLength, i as DslNavigateAction, r as DslNode, e as DslNodeType, l as DslOpenAction, g as DslRect, p as DslSequenceAction, m as DslSetStateAction, z as DslSource, v as DslSourceRef, u as DslStage, n as DslTrackAction, d as DslViewType, x as RenderElement, y as RenderLayer, F as RuntimeEmit, E as RuntimeEventName, B as RuntimeEvents } from './types-BgUaJUAu.cjs';
+import { D as Dsl, R as RuntimeOptions, a as RenderTree, b as DslView, c as DslStyle, C as CssStyle } from './types-Bj0xyWnx.cjs';
+export { q as DslAction, h as DslActionBase, o as DslCallAction, j as DslCloseAction, k as DslCloseAllAction, t as DslCloseButton, s as DslClosePosition, w as DslDerived, A as DslHandler, E as DslInteractionEvent, B as DslInteractionTrigger, f as DslLength, i as DslNavigateAction, r as DslNode, e as DslNodeType, l as DslOpenAction, g as DslRect, p as DslSequenceAction, m as DslSetStateAction, z as DslSource, v as DslSourceRef, u as DslStage, n as DslTrackAction, d as DslViewType, x as RenderElement, y as RenderLayer, H as RuntimeEmit, G as RuntimeEventName, F as RuntimeEvents } from './types-Bj0xyWnx.cjs';
 
 /**
  * 运行时。
@@ -46,6 +46,17 @@ interface Issue {
     path: string;
     message: string;
 }
+/** 校验选项，全部可选；不传时行为与旧版完全一致 */
+interface ValidateOptions {
+    /**
+     * 允许出现在 `{{ user.xxx }}` 里的字段白名单。
+     *
+     * **不传就不校验**（宿主注入什么字段由宿主决定，核心包不该替它们写死）。
+     * 传了则所有插值位置里引用的 `user` 字段都必须在表内，否则报 error。
+     * 默认可用的一套见 `DEFAULT_USER_FIELDS`。
+     */
+    userFields?: string[];
+}
 interface ValidateResult {
     valid: boolean;
     errors: Issue[];
@@ -62,10 +73,70 @@ declare const ACTION_TYPES: string[];
  */
 declare const TRACK_EVENT_PATTERN: RegExp;
 declare const CLOSE_POSITIONS: string[];
-declare function validate(dsl: Dsl | unknown): ValidateResult;
+/**
+ * 校验一份 DSL。
+ *
+ * @param dsl 待校验的配置
+ * @param options 可选项；不传时与旧版行为完全一致
+ */
+declare function validate(dsl: Dsl | unknown, options?: ValidateOptions): ValidateResult;
+/** 宽高比：'750 / 200'、'16/9' 或纯数字 */
+/**
+ * banner 允许的最小宽高比（宽 ÷ 高）。
+ *
+ * banner 坑位常驻页面顶部、不跟随内容滚动，比例越方在宽屏上越高：
+ * 同样 1800px 宽的坑位，17:1 算出来是 105px，4:1（1200×300 那种大图）直接 451px，
+ * 首屏一眼看过去全是广告。所以比例必须够扁——**这是坑位的设计尺寸，不是配置的自由度**。
+ *
+ * 约束比例而不是约束固定高度，是因为整图 banner 必须靠 aspectRatio 维持等比：
+ * 写死高度的话坑位一宽，图就被横向拉变形了。
+ */
+declare const BANNER_MIN_ASPECT_RATIO = 12;
 /** 把校验结果拼成可以直接展示的文本 */
 declare function formatIssues(issues: Issue[]): string;
 
+/**
+ * `{{ user.xxx }}` 字段白名单校验
+ *
+ * `user` 是宿主注入的登录用户信息对象，字段集由宿主决定、前端 DSL 只能读。
+ * 运营写错字段名（`user.expireDays` 而不是 `user.remainDays`）时，
+ * 运行时只会求值为空——页面上就是一处空白 / 倒计时归零，
+ * 投到线上才发现。所以在保存前就按白名单拦一道。
+ *
+ * 白名单本身是**可选**的：`validate(dsl)` 不传就完全不查（向后兼容），
+ * 调用方（后台调试台 / 后端保存）自己决定用哪套字段。
+ */
+/** 一条校验问题，结构与 `validate.ts` 的 `Issue` 一致（避免两个文件循环依赖类型） */
+interface FieldIssue {
+    /** 出问题的位置，如 `views.main.nodes[0].content` */
+    path: string;
+    /** 给运营看的中文说明 */
+    message: string;
+}
+/**
+ * 默认可用的 `user` 字段白名单。
+ *
+ * 取自各平台统一的登录用户信息模型（`UserInfo`），这套字段名是全平台通用契约。
+ * 刻意排除两个字段：
+ *   - `sourceData`：后端原始响应整包，结构随平台漂移，不对运营开放
+ *   - `mcToken`：令牌，不该出现在运营配置里，更不该渲染到页面上
+ */
+declare const DEFAULT_USER_FIELDS: string[];
+/** 白名单字段的中文含义，文档和编辑器提示共用一份，避免说明各写各的 */
+declare const USER_FIELD_LABELS: Record<string, string>;
+/**
+ * 深度遍历整份 DSL，校验所有 `{{ user.xxx }}` 引用的字段是否在白名单内。
+ *
+ * 遍历的是**全部字符串值**而不是某几个已知字段（content / to / src …），
+ * 因为能写插值的位置太多（样式值、动作 params、stage 尺寸…），
+ * 正向列举必漏；反过来「凡是字符串就查一遍 `{{ }}`」不会漏。
+ *
+ * @param dsl 待校验的 DSL（任意结构，坏数据交给主校验流程报错，这里只负责不崩）
+ * @param allowed 允许的字段名列表
+ * @returns 每个非法引用一条 error 级问题
+ */
+declare function validateUserFields(dsl: unknown, allowed: string[]): FieldIssue[];
+
 /**
  * 视图归一化。
  *
@@ -177,4 +248,4 @@ 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, CssStyle, DSL_VERSION, Dsl, type DslRuntime, DslStyle, DslView, type Issue, NODE_TYPES, type NormalizedViews, RenderTree, RuntimeOptions, SINGLE_VIEW_NAME, TRACK_EVENT_PATTERN, type ValidateResult, check, computeParts, createRuntime, evaluate, formatIssues, formatParts, interpolate, interpolateDeep, isLength, isValidEndTime, normalizeViews, parseEndTime, safeImageUrl, safeUrl, toCssStyle, toLength, validate };
+export { ACTION_TYPES, ALLOWED_STYLE_KEYS, BANNER_MIN_ASPECT_RATIO, CLOSE_POSITIONS, type CountdownParts, type CountdownPrecision, CssStyle, DEFAULT_USER_FIELDS, DSL_VERSION, Dsl, type DslRuntime, DslStyle, DslView, type Issue, NODE_TYPES, type NormalizedViews, RenderTree, RuntimeOptions, SINGLE_VIEW_NAME, TRACK_EVENT_PATTERN, USER_FIELD_LABELS, type ValidateOptions, type ValidateResult, check, computeParts, createRuntime, evaluate, formatIssues, formatParts, interpolate, interpolateDeep, isLength, isValidEndTime, normalizeViews, parseEndTime, safeImageUrl, safeUrl, toCssStyle, toLength, validate, validateUserFields };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { D as Dsl, R as RuntimeOptions, a as RenderTree, b as DslView, c as DslStyle, C as CssStyle } from './types-BgUaJUAu.js';
-export { q as DslAction, h as DslActionBase, o as DslCallAction, j as DslCloseAction, k as DslCloseAllAction, t as DslCloseButton, s as DslClosePosition, w as DslDerived, A as DslHandler, f as DslLength, i as DslNavigateAction, r as DslNode, e as DslNodeType, l as DslOpenAction, g as DslRect, p as DslSequenceAction, m as DslSetStateAction, z as DslSource, v as DslSourceRef, u as DslStage, n as DslTrackAction, d as DslViewType, x as RenderElement, y as RenderLayer, F as RuntimeEmit, E as RuntimeEventName, B as RuntimeEvents } from './types-BgUaJUAu.js';
+import { D as Dsl, R as RuntimeOptions, a as RenderTree, b as DslView, c as DslStyle, C as CssStyle } from './types-Bj0xyWnx.js';
+export { q as DslAction, h as DslActionBase, o as DslCallAction, j as DslCloseAction, k as DslCloseAllAction, t as DslCloseButton, s as DslClosePosition, w as DslDerived, A as DslHandler, E as DslInteractionEvent, B as DslInteractionTrigger, f as DslLength, i as DslNavigateAction, r as DslNode, e as DslNodeType, l as DslOpenAction, g as DslRect, p as DslSequenceAction, m as DslSetStateAction, z as DslSource, v as DslSourceRef, u as DslStage, n as DslTrackAction, d as DslViewType, x as RenderElement, y as RenderLayer, H as RuntimeEmit, G as RuntimeEventName, F as RuntimeEvents } from './types-Bj0xyWnx.js';
 
 /**
  * 运行时。
@@ -46,6 +46,17 @@ interface Issue {
     path: string;
     message: string;
 }
+/** 校验选项，全部可选；不传时行为与旧版完全一致 */
+interface ValidateOptions {
+    /**
+     * 允许出现在 `{{ user.xxx }}` 里的字段白名单。
+     *
+     * **不传就不校验**（宿主注入什么字段由宿主决定，核心包不该替它们写死）。
+     * 传了则所有插值位置里引用的 `user` 字段都必须在表内，否则报 error。
+     * 默认可用的一套见 `DEFAULT_USER_FIELDS`。
+     */
+    userFields?: string[];
+}
 interface ValidateResult {
     valid: boolean;
     errors: Issue[];
@@ -62,10 +73,70 @@ declare const ACTION_TYPES: string[];
  */
 declare const TRACK_EVENT_PATTERN: RegExp;
 declare const CLOSE_POSITIONS: string[];
-declare function validate(dsl: Dsl | unknown): ValidateResult;
+/**
+ * 校验一份 DSL。
+ *
+ * @param dsl 待校验的配置
+ * @param options 可选项；不传时与旧版行为完全一致
+ */
+declare function validate(dsl: Dsl | unknown, options?: ValidateOptions): ValidateResult;
+/** 宽高比：'750 / 200'、'16/9' 或纯数字 */
+/**
+ * banner 允许的最小宽高比（宽 ÷ 高）。
+ *
+ * banner 坑位常驻页面顶部、不跟随内容滚动，比例越方在宽屏上越高：
+ * 同样 1800px 宽的坑位，17:1 算出来是 105px，4:1（1200×300 那种大图）直接 451px，
+ * 首屏一眼看过去全是广告。所以比例必须够扁——**这是坑位的设计尺寸，不是配置的自由度**。
+ *
+ * 约束比例而不是约束固定高度，是因为整图 banner 必须靠 aspectRatio 维持等比：
+ * 写死高度的话坑位一宽，图就被横向拉变形了。
+ */
+declare const BANNER_MIN_ASPECT_RATIO = 12;
 /** 把校验结果拼成可以直接展示的文本 */
 declare function formatIssues(issues: Issue[]): string;
 
+/**
+ * `{{ user.xxx }}` 字段白名单校验
+ *
+ * `user` 是宿主注入的登录用户信息对象，字段集由宿主决定、前端 DSL 只能读。
+ * 运营写错字段名（`user.expireDays` 而不是 `user.remainDays`）时，
+ * 运行时只会求值为空——页面上就是一处空白 / 倒计时归零，
+ * 投到线上才发现。所以在保存前就按白名单拦一道。
+ *
+ * 白名单本身是**可选**的：`validate(dsl)` 不传就完全不查（向后兼容），
+ * 调用方（后台调试台 / 后端保存）自己决定用哪套字段。
+ */
+/** 一条校验问题，结构与 `validate.ts` 的 `Issue` 一致（避免两个文件循环依赖类型） */
+interface FieldIssue {
+    /** 出问题的位置，如 `views.main.nodes[0].content` */
+    path: string;
+    /** 给运营看的中文说明 */
+    message: string;
+}
+/**
+ * 默认可用的 `user` 字段白名单。
+ *
+ * 取自各平台统一的登录用户信息模型（`UserInfo`），这套字段名是全平台通用契约。
+ * 刻意排除两个字段：
+ *   - `sourceData`：后端原始响应整包，结构随平台漂移，不对运营开放
+ *   - `mcToken`：令牌，不该出现在运营配置里，更不该渲染到页面上
+ */
+declare const DEFAULT_USER_FIELDS: string[];
+/** 白名单字段的中文含义，文档和编辑器提示共用一份，避免说明各写各的 */
+declare const USER_FIELD_LABELS: Record<string, string>;
+/**
+ * 深度遍历整份 DSL，校验所有 `{{ user.xxx }}` 引用的字段是否在白名单内。
+ *
+ * 遍历的是**全部字符串值**而不是某几个已知字段（content / to / src …），
+ * 因为能写插值的位置太多（样式值、动作 params、stage 尺寸…），
+ * 正向列举必漏；反过来「凡是字符串就查一遍 `{{ }}`」不会漏。
+ *
+ * @param dsl 待校验的 DSL（任意结构，坏数据交给主校验流程报错，这里只负责不崩）
+ * @param allowed 允许的字段名列表
+ * @returns 每个非法引用一条 error 级问题
+ */
+declare function validateUserFields(dsl: unknown, allowed: string[]): FieldIssue[];
+
 /**
  * 视图归一化。
  *
@@ -177,4 +248,4 @@ 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, CssStyle, DSL_VERSION, Dsl, type DslRuntime, DslStyle, DslView, type Issue, NODE_TYPES, type NormalizedViews, RenderTree, RuntimeOptions, SINGLE_VIEW_NAME, TRACK_EVENT_PATTERN, type ValidateResult, check, computeParts, createRuntime, evaluate, formatIssues, formatParts, interpolate, interpolateDeep, isLength, isValidEndTime, normalizeViews, parseEndTime, safeImageUrl, safeUrl, toCssStyle, toLength, validate };
+export { ACTION_TYPES, ALLOWED_STYLE_KEYS, BANNER_MIN_ASPECT_RATIO, CLOSE_POSITIONS, type CountdownParts, type CountdownPrecision, CssStyle, DEFAULT_USER_FIELDS, DSL_VERSION, Dsl, type DslRuntime, DslStyle, DslView, type Issue, NODE_TYPES, type NormalizedViews, RenderTree, RuntimeOptions, SINGLE_VIEW_NAME, TRACK_EVENT_PATTERN, USER_FIELD_LABELS, type ValidateOptions, type ValidateResult, check, computeParts, createRuntime, evaluate, formatIssues, formatParts, interpolate, interpolateDeep, isLength, isValidEndTime, normalizeViews, parseEndTime, safeImageUrl, safeUrl, toCssStyle, toLength, validate, validateUserFields };