lumen-tour 0.2.0 → 0.3.0

package/README.md

@@ -70,7 +70,7 @@ tour.start();
 | `steps` | `TourStep[]` | （必填） | 引导步骤列表 |
 | `texts` | `Partial<ButtonTexts>` | 见下 | 覆盖按钮文案 |
 | `overlayColor` | `string` | `rgba(0,0,0,0.5)` | 遮罩颜色 |
-| `padding` | `number \| [number, number]` | `8` | 挖孔相对目标元素的内边距（px）；传 `number` 四周等距，传 `[x, y]` 则水平 `x`、垂直 `y` 分别控制 |
+| `padding` | `number \| number[]` | `8` | 挖孔相对目标元素的内边距（px），CSS 风格简写：`number`/`[v]` 四周等距，`[t, h]` 上下 `t`、左右 `h`，`[t, h, b]` 上 `t`、左右 `h`、下 `b`，`[t, r, b, l]` 上/右/下/左独立控制 |
 | `hideSkipOnLast` | `boolean` | `false` | 到达最后一步时是否隐藏"跳过"按钮 |
 | `keyboard` | `boolean` | `true` | 是否启用键盘导航（→ 下一步、← 上一步、Esc 跳过） |
 | `onNext` | `(ctx) => void \| boolean \| Promise<void \| boolean>` | — | 点击"下一步"时触发；返回 `false` 可阻止前进（支持异步校验） |

package/dist/overlay.d.ts

@@ -7,10 +7,12 @@ export declare class Overlay {
     readonly el: HTMLElement;
     private color;
     constructor(root: HTMLElement, color?: string);
-    /** 按目标元素矩形（视口坐标）+ padding 更新挖孔位置 */
+    /** 按目标元素矩形（视口坐标）+ 四方向 padding 更新挖孔位置 */
     update(rect: Rect, padding: {
-        x: number;
-        y: number;
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
     }): void;
     hide(): void;
     destroy(): void;

package/dist/types.d.ts

@@ -7,9 +7,20 @@ export interface StepContext {
     /** 当前步骤配置 */
     step: TourStep;
 }
+/**
+ * padding 取值，CSS 风格简写（数组语义与 CSS margin/padding 一致）：
+ * number → 四周等距；
+ * [v] → 四周等距 v；
+ * [t, h] → 上下 t、左右 h；
+ * [t, h, b] → 上 t、左右 h、下 b；
+ * [t, r, b, l] → 上、右、下、左各方向独立。
+ */
+export type PaddingInput = number | number[];
 export interface TourStep {
     /** 必填：目标元素选择器或元素本身 */
     target: string | HTMLElement;
+    /** 挖孔相对目标元素的内边距（CSS 风格简写），设置后整体覆盖全局 padding */
+    padding?: PaddingInput;
     /** 卡片相对目标的方向，默认自动（下方优先，放不下翻转到上方） */
     placement?: import('./position').Placement;
     /** 卡片标题，支持受限 HTML（白名单清洗：剥离 script/事件处理器/危险协议） */
@@ -35,11 +46,8 @@ export interface TourOptions {
     texts?: Partial<ButtonTexts>;
     /** 遮罩颜色，默认 rgba(0,0,0,0.5) */
     overlayColor?: string;
-    /**
-     * 挖孔相对目标元素的内边距，默认 8。
-     * 传 number 则四周等距；传 [x, y] 则水平 x、垂直 y。
-     */
-    padding?: number | [number, number];
+    /** 挖孔相对目标元素的内边距，默认 8；CSS 风格简写（见 PaddingInput） */
+    padding?: PaddingInput;
     /** 到达最后一步时是否隐藏"跳过"按钮，默认 false（保留显示） */
     hideSkipOnLast?: boolean;
     /** 键盘导航（→ 下一步、← 上一步、Esc 跳过），默认 true */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lumen-tour",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Lightweight zero-dependency product tour / onboarding guide. TypeScript + native CSS.",
   "author": "felixfjing",
   "private": false,