@iquji-web/web-component 0.1.6 → 0.1.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -45,6 +45,7 @@ npm install @iquji-web/web-component @iquji-web/web-theme @iquji-web/web-icons
45
45
  - **`IqujiFormDialog`**:支持居中放大展开的沉浸式表单对话框。
46
46
  - **`IqujiSearchDialog`**:跨组过滤、键盘快捷操作的通用全局搜索框。
47
47
  - **`IqujiTooltip` / `IqujiPopover` / `IqujiDropdownMenu`**:轻量定位弹出层。
48
+ - **`IqujiTour`**:受控的新手教程浮层,用聚光遮罩突出真实控件,在目标旁显示当前说明与操作。目标区域保留点击与输入,布局尺寸不变。
48
49
 
49
50
  ### 5. 反馈与通知 (Feedback)
50
51
  - **`IqujiNotificationProvider` & `useIqujiNotification`**:全局非阻塞轻量通知,支持自动关闭、同 key 更新、视觉倒计时进度与鼠标悬停暂停。
@@ -102,6 +103,35 @@ export function Example() {
102
103
 
103
104
  ---
104
105
 
106
+ ## 新手教程
107
+
108
+ `IqujiTour` 沿用 `IqujiOverlayProvider` 和抽屉的浮层范围。每一步以 `target` 返回实际 DOM 元素,组件跟踪挂载、滚动和尺寸变化并避让窗口边缘。目标尚未出现时保留当前说明与退出入口,调用方负责等待目标和业务数据就绪。后开的模态窗口接管交互时,教程暂时隐藏,窗口关闭后恢复当前步骤。
109
+
110
+ ```tsx
111
+ const name = useRef<HTMLInputElement>(null);
112
+ const [guiding, setGuiding] = useState(true);
113
+
114
+ <>
115
+ <IqujiInput ref={name} aria-label="项目名称" />
116
+ <IqujiTour
117
+ open={guiding}
118
+ closeLabel="退出引导"
119
+ onClose={() => setGuiding(false)}
120
+ progress="1 / 3"
121
+ step={{
122
+ id: "name",
123
+ target: () => name.current,
124
+ title: "为项目命名",
125
+ description: "在高亮输入框中填写项目名称,完成后继续。",
126
+ placement: "bottom",
127
+ }}
128
+ actions={<IqujiButton onClick={continueAfterValidation}>下一步</IqujiButton>}
129
+ />
130
+ </>
131
+ ```
132
+
133
+ 调用方通过 `step`、`progress` 和 `actions` 控制流程,保存、发布、校验与失败重试继续使用原业务入口。`onClose` 只结束引导,填写内容由原表单保存。Escape 优先关闭控件自己的菜单,再退出教程。
134
+
105
135
  ## 开发与构建
106
136
 
107
137
  ```bash
package/dist/index.d.ts CHANGED
@@ -135,5 +135,6 @@ export * from "./settings-nav.js";
135
135
  export * from "./settings-rows.js";
136
136
  export * from "./timeline.js";
137
137
  export * from "./tooltip.js";
138
+ export * from "./tour.js";
138
139
  export * from "./workbench.js";
139
140
  export * from "./emoji-picker.js";
package/dist/index.js CHANGED
@@ -4104,14 +4104,261 @@ function IqujiTimeline({
4104
4104
  })
4105
4105
  });
4106
4106
  }
4107
+ // src/tour.tsx
4108
+ import { Popover } from "@base-ui/react/popover";
4109
+ import { IqujiIcon as IqujiIcon15 } from "@iquji-web/web-icons";
4110
+ import {
4111
+ useEffect as useEffect7,
4112
+ useMemo as useMemo7,
4113
+ useRef as useRef12
4114
+ } from "react";
4115
+
4116
+ // src/tour-target.ts
4117
+ import { useEffect as useEffect6, useRef as useRef11, useState as useState13 } from "react";
4118
+ function useTourTarget(open, id, resolve) {
4119
+ const resolver = useRef11(resolve);
4120
+ resolver.current = resolve;
4121
+ const [target, setTarget] = useState13({
4122
+ id,
4123
+ element: null,
4124
+ rect: null,
4125
+ width: typeof window === "undefined" ? 0 : window.innerWidth,
4126
+ height: typeof window === "undefined" ? 0 : window.innerHeight
4127
+ });
4128
+ useEffect6(() => {
4129
+ if (!open)
4130
+ return;
4131
+ let frame = 0;
4132
+ let observed = null;
4133
+ let revealed = null;
4134
+ const resize = new ResizeObserver(() => schedule());
4135
+ const measure = () => {
4136
+ frame = 0;
4137
+ const candidate = resolver.current();
4138
+ const element = candidate?.isConnected && !candidate.closest("[hidden], [inert]") ? candidate : null;
4139
+ if (observed !== element) {
4140
+ resize.disconnect();
4141
+ if (element)
4142
+ resize.observe(element);
4143
+ observed = element;
4144
+ }
4145
+ if (element && revealed !== element) {
4146
+ element.scrollIntoView?.({
4147
+ block: "nearest",
4148
+ inline: "nearest",
4149
+ behavior: "instant"
4150
+ });
4151
+ revealed = element;
4152
+ }
4153
+ const bounds = element?.getBoundingClientRect();
4154
+ const rect = bounds && bounds.width > 0 && bounds.height > 0 ? bounds : null;
4155
+ const width = window.innerWidth;
4156
+ const height = window.innerHeight;
4157
+ setTarget((current) => {
4158
+ if (current.id === id && current.element === element && current.width === width && current.height === height && current.rect?.x === rect?.x && current.rect?.y === rect?.y && current.rect?.width === rect?.width && current.rect?.height === rect?.height)
4159
+ return current;
4160
+ return { id, element, rect, width, height };
4161
+ });
4162
+ };
4163
+ const schedule = () => {
4164
+ if (!frame)
4165
+ frame = requestAnimationFrame(measure);
4166
+ };
4167
+ const mutations = new MutationObserver(schedule);
4168
+ mutations.observe(document.body, {
4169
+ childList: true,
4170
+ subtree: true,
4171
+ attributes: true,
4172
+ attributeFilter: [
4173
+ "hidden",
4174
+ "inert",
4175
+ "style",
4176
+ "class",
4177
+ "data-open",
4178
+ "data-starting-style"
4179
+ ]
4180
+ });
4181
+ window.addEventListener("resize", schedule);
4182
+ document.addEventListener("scroll", schedule, true);
4183
+ document.addEventListener("transitionend", schedule, true);
4184
+ window.visualViewport?.addEventListener("resize", schedule);
4185
+ window.visualViewport?.addEventListener("scroll", schedule);
4186
+ measure();
4187
+ return () => {
4188
+ cancelAnimationFrame(frame);
4189
+ resize.disconnect();
4190
+ mutations.disconnect();
4191
+ window.removeEventListener("resize", schedule);
4192
+ document.removeEventListener("scroll", schedule, true);
4193
+ document.removeEventListener("transitionend", schedule, true);
4194
+ window.visualViewport?.removeEventListener("resize", schedule);
4195
+ window.visualViewport?.removeEventListener("scroll", schedule);
4196
+ };
4197
+ }, [open, id]);
4198
+ return target.id === id ? target : { ...target, element: null, rect: null };
4199
+ }
4200
+
4201
+ // src/tour.tsx
4202
+ import { jsx as jsx33, jsxs as jsxs29 } from "react/jsx-runtime";
4203
+ function IqujiTour({
4204
+ open,
4205
+ step,
4206
+ progress,
4207
+ actions,
4208
+ closeLabel,
4209
+ onClose
4210
+ }) {
4211
+ const scope = useIqujiOverlayContainer();
4212
+ const container = scope && "current" in scope ? scope.current : scope;
4213
+ const topContainer = useIqujiNotificationContainer();
4214
+ const active = open && (!topContainer || container === topContainer);
4215
+ const target = useTourTarget(active, step.id, step.target);
4216
+ const card = useRef12(null);
4217
+ const close = () => {
4218
+ if (card.current?.contains(document.activeElement)) {
4219
+ const selector = "input, textarea, select, button, a[href], [tabindex]";
4220
+ const field = target.element?.matches(selector) ? target.element : target.element?.querySelector(selector);
4221
+ field?.focus({ preventScroll: true });
4222
+ }
4223
+ onClose();
4224
+ };
4225
+ const onCloseRef = useRef12(close);
4226
+ onCloseRef.current = close;
4227
+ useEffect7(() => {
4228
+ if (!active)
4229
+ return;
4230
+ const escape = (event) => {
4231
+ if (event.key !== "Escape" || event.defaultPrevented || event.isComposing)
4232
+ return;
4233
+ const root = container ?? document;
4234
+ if (root.querySelector(".iquji-select__popup[data-open], .iquji-menu-popup[data-open], .iquji-popover-popup[data-open]"))
4235
+ return;
4236
+ event.preventDefault();
4237
+ event.stopImmediatePropagation();
4238
+ onCloseRef.current();
4239
+ };
4240
+ document.addEventListener("keydown", escape, true);
4241
+ return () => document.removeEventListener("keydown", escape, true);
4242
+ }, [active, container]);
4243
+ const anchor = useMemo7(() => ({
4244
+ contextElement: target.element ?? undefined,
4245
+ getBoundingClientRect: () => target.rect ?? new DOMRect(target.width / 2, target.height / 3, 0, 0)
4246
+ }), [target]);
4247
+ if (!active)
4248
+ return null;
4249
+ const padding = 6;
4250
+ const left = Math.max(0, (target.rect?.left ?? 0) - padding);
4251
+ const top = Math.max(0, (target.rect?.top ?? 0) - padding);
4252
+ const right = Math.min(target.width, (target.rect?.right ?? 0) + padding);
4253
+ const bottom = Math.min(target.height, (target.rect?.bottom ?? 0) + padding);
4254
+ const hole = target.rect && right > left && bottom > top;
4255
+ const masks = hole ? [
4256
+ { left: 0, top: 0, width: "100%", height: top },
4257
+ { left: 0, top: bottom, width: "100%", bottom: 0 },
4258
+ { left: 0, top, width: left, height: bottom - top },
4259
+ { left: right, top, right: 0, height: bottom - top }
4260
+ ] : [{ inset: 0 }];
4261
+ return /* @__PURE__ */ jsx33(Popover.Root, {
4262
+ open: true,
4263
+ modal: false,
4264
+ onOpenChange: (_next, details) => details.cancel(),
4265
+ children: /* @__PURE__ */ jsx33(Popover.Portal, {
4266
+ container: container ?? undefined,
4267
+ children: /* @__PURE__ */ jsxs29("div", {
4268
+ className: "iquji-tour",
4269
+ "data-step": step.id,
4270
+ "data-target-missing": !hole || undefined,
4271
+ style: { zIndex: container ? 1 : 1002 },
4272
+ children: [
4273
+ masks.map((style, index) => /* @__PURE__ */ jsx33("div", {
4274
+ className: "iquji-tour__mask",
4275
+ style,
4276
+ "aria-hidden": "true"
4277
+ }, index)),
4278
+ hole && /* @__PURE__ */ jsx33("div", {
4279
+ className: "iquji-tour__spotlight",
4280
+ "aria-hidden": "true",
4281
+ style: {
4282
+ left,
4283
+ top,
4284
+ width: right - left,
4285
+ height: bottom - top
4286
+ }
4287
+ }),
4288
+ /* @__PURE__ */ jsx33(Popover.Positioner, {
4289
+ anchor,
4290
+ side: target.rect ? step.placement ?? "bottom" : "bottom",
4291
+ align: "center",
4292
+ sideOffset: 16,
4293
+ collisionPadding: 16,
4294
+ className: "iquji-tour__positioner",
4295
+ children: /* @__PURE__ */ jsxs29(Popover.Popup, {
4296
+ ref: card,
4297
+ initialFocus: false,
4298
+ finalFocus: false,
4299
+ className: "iquji-tour__card",
4300
+ children: [
4301
+ /* @__PURE__ */ jsxs29("div", {
4302
+ className: "iquji-tour__body",
4303
+ children: [
4304
+ /* @__PURE__ */ jsxs29("div", {
4305
+ className: "iquji-tour__header",
4306
+ children: [
4307
+ /* @__PURE__ */ jsxs29("div", {
4308
+ "aria-live": "polite",
4309
+ children: [
4310
+ progress && /* @__PURE__ */ jsx33("div", {
4311
+ className: "iquji-tour__progress",
4312
+ children: progress
4313
+ }),
4314
+ /* @__PURE__ */ jsx33(Popover.Title, {
4315
+ className: "iquji-tour__title",
4316
+ children: step.title
4317
+ })
4318
+ ]
4319
+ }),
4320
+ /* @__PURE__ */ jsx33(IconButton, {
4321
+ compact: true,
4322
+ label: closeLabel,
4323
+ icon: /* @__PURE__ */ jsx33(IqujiIcon15, {
4324
+ decorative: true,
4325
+ name: "close"
4326
+ }),
4327
+ onClick: close
4328
+ })
4329
+ ]
4330
+ }),
4331
+ /* @__PURE__ */ jsx33(Popover.Description, {
4332
+ render: /* @__PURE__ */ jsx33("div", {}),
4333
+ "aria-live": "polite",
4334
+ className: "iquji-tour__description",
4335
+ children: step.description
4336
+ }),
4337
+ actions && /* @__PURE__ */ jsx33("div", {
4338
+ className: "iquji-tour__actions",
4339
+ children: actions
4340
+ })
4341
+ ]
4342
+ }),
4343
+ hole && /* @__PURE__ */ jsx33(Popover.Arrow, {
4344
+ className: "iquji-tour__arrow"
4345
+ })
4346
+ ]
4347
+ })
4348
+ })
4349
+ ]
4350
+ })
4351
+ })
4352
+ });
4353
+ }
4107
4354
  // src/workbench.tsx
4108
4355
  import {
4109
4356
  useId as useId15,
4110
4357
  useLayoutEffect,
4111
- useRef as useRef11,
4112
- useState as useState13
4358
+ useRef as useRef13,
4359
+ useState as useState14
4113
4360
  } from "react";
4114
- import { jsx as jsx33, jsxs as jsxs29 } from "react/jsx-runtime";
4361
+ import { jsx as jsx34, jsxs as jsxs30 } from "react/jsx-runtime";
4115
4362
  var DEFAULT_LEFT_WIDTH = 240;
4116
4363
  var DEFAULT_LEFT_MIN = 180;
4117
4364
  var DEFAULT_LEFT_MAX = 420;
@@ -4159,19 +4406,19 @@ function IqujiWorkbenchLayout({
4159
4406
  rightClassName
4160
4407
  }) {
4161
4408
  const generatedId = useId15();
4162
- const rootRef = useRef11(null);
4163
- const leftRef = useRef11(null);
4164
- const centerRef = useRef11(null);
4165
- const rightRef = useRef11(null);
4166
- const previousGeometry = useRef11(null);
4167
- const dragRef = useRef11(null);
4168
- const [resizing, setResizing] = useState13(null);
4409
+ const rootRef = useRef13(null);
4410
+ const leftRef = useRef13(null);
4411
+ const centerRef = useRef13(null);
4412
+ const rightRef = useRef13(null);
4413
+ const previousGeometry = useRef13(null);
4414
+ const dragRef = useRef13(null);
4415
+ const [resizing, setResizing] = useState14(null);
4169
4416
  const leftBounds = widthBounds(leftMinWidth ?? DEFAULT_LEFT_MIN, leftMaxWidth ?? DEFAULT_LEFT_MAX);
4170
4417
  const rightBounds = widthBounds(rightMinWidth ?? DEFAULT_RIGHT_MIN, rightMaxWidth ?? DEFAULT_RIGHT_MAX);
4171
4418
  const leftDefault = clampWidth(numberOr(defaultLeftWidth, DEFAULT_LEFT_WIDTH), leftBounds.min, leftBounds.max);
4172
4419
  const rightDefault = clampWidth(numberOr(defaultRightWidth, DEFAULT_RIGHT_WIDTH), rightBounds.min, rightBounds.max);
4173
- const [internalLeftWidth, setInternalLeftWidth] = useState13(leftDefault);
4174
- const [internalRightWidth, setInternalRightWidth] = useState13(rightDefault);
4420
+ const [internalLeftWidth, setInternalLeftWidth] = useState14(leftDefault);
4421
+ const [internalRightWidth, setInternalRightWidth] = useState14(rightDefault);
4175
4422
  const leftValue = clampWidth(numberOr(leftWidth, internalLeftWidth), leftBounds.min, leftBounds.max);
4176
4423
  const rightValue = clampWidth(numberOr(rightWidth, internalRightWidth), rightBounds.min, rightBounds.max);
4177
4424
  const centerMin = Math.max(1, Math.round(numberOr(centerMinWidth, DEFAULT_CENTER_MIN)));
@@ -4303,7 +4550,7 @@ function IqujiWorkbenchLayout({
4303
4550
  const bounds = side === "left" ? leftBounds : rightBounds;
4304
4551
  const value = currentWidth(side);
4305
4552
  const paneId = side === "left" ? `${generatedId}-left` : `${generatedId}-right`;
4306
- return /* @__PURE__ */ jsx33("div", {
4553
+ return /* @__PURE__ */ jsx34("div", {
4307
4554
  "aria-controls": paneId,
4308
4555
  "aria-label": side === "left" ? leftResizeLabel : rightResizeLabel,
4309
4556
  "aria-orientation": "vertical",
@@ -4321,13 +4568,13 @@ function IqujiWorkbenchLayout({
4321
4568
  tabIndex: 0
4322
4569
  });
4323
4570
  };
4324
- return /* @__PURE__ */ jsxs29("div", {
4571
+ return /* @__PURE__ */ jsxs30("div", {
4325
4572
  className: classNames("iquji-workbench", leftCollapsed && "iquji-workbench--left-collapsed", rightCollapsed && "iquji-workbench--right-collapsed", className),
4326
4573
  "data-resizing": resizing ?? undefined,
4327
4574
  ref: rootRef,
4328
4575
  style,
4329
4576
  children: [
4330
- hasLeft ? /* @__PURE__ */ jsxs29("div", {
4577
+ hasLeft ? /* @__PURE__ */ jsxs30("div", {
4331
4578
  "aria-hidden": leftCollapsed || undefined,
4332
4579
  className: classNames("iquji-workbench__pane", "iquji-workbench__pane--left", leftClassName),
4333
4580
  id: `${generatedId}-left`,
@@ -4338,13 +4585,13 @@ function IqujiWorkbenchLayout({
4338
4585
  leftVisible ? renderResizer("left") : null
4339
4586
  ]
4340
4587
  }) : null,
4341
- /* @__PURE__ */ jsx33("div", {
4588
+ /* @__PURE__ */ jsx34("div", {
4342
4589
  className: classNames("iquji-workbench__pane", "iquji-workbench__pane--center", centerClassName),
4343
4590
  id: `${generatedId}-center`,
4344
4591
  ref: centerRef,
4345
4592
  children: center
4346
4593
  }),
4347
- hasRight ? /* @__PURE__ */ jsxs29("div", {
4594
+ hasRight ? /* @__PURE__ */ jsxs30("div", {
4348
4595
  "aria-hidden": rightCollapsed || undefined,
4349
4596
  className: classNames("iquji-workbench__pane", "iquji-workbench__pane--right", rightClassName),
4350
4597
  id: `${generatedId}-right`,
@@ -4359,14 +4606,14 @@ function IqujiWorkbenchLayout({
4359
4606
  });
4360
4607
  }
4361
4608
  // src/emoji-picker.tsx
4362
- import { useId as useId16, useMemo as useMemo7, useRef as useRef12, useState as useState14 } from "react";
4363
- import { jsx as jsx34, jsxs as jsxs30 } from "react/jsx-runtime";
4609
+ import { useId as useId16, useMemo as useMemo8, useRef as useRef14, useState as useState15 } from "react";
4610
+ import { jsx as jsx35, jsxs as jsxs31 } from "react/jsx-runtime";
4364
4611
  function IqujiEmojiPicker({ value, options, onChange, label, searchLabel, emptyLabel, clearLabel, allLabel, disabled, variant = "primary" }) {
4365
- const [open, setOpen] = useState14(false), [search, setSearch] = useState14("");
4366
- const [category, setCategory] = useState14(null), [active, setActive] = useState14(0);
4367
- const id = useId16(), buttons = useRef12(new Map);
4368
- const categories = useMemo7(() => [...new Set(options.flatMap((option) => option.category ? [option.category] : []))], [options]);
4369
- const filtered = useMemo7(() => options.filter((option) => (!category || option.category === category) && `${option.label} ${option.keywords ?? ""} ${option.value}`.toLocaleLowerCase().includes(search.trim().toLocaleLowerCase())), [options, search, category]);
4612
+ const [open, setOpen] = useState15(false), [search, setSearch] = useState15("");
4613
+ const [category, setCategory] = useState15(null), [active, setActive] = useState15(0);
4614
+ const id = useId16(), buttons = useRef14(new Map);
4615
+ const categories = useMemo8(() => [...new Set(options.flatMap((option) => option.category ? [option.category] : []))], [options]);
4616
+ const filtered = useMemo8(() => options.filter((option) => (!category || option.category === category) && `${option.label} ${option.keywords ?? ""} ${option.value}`.toLocaleLowerCase().includes(search.trim().toLocaleLowerCase())), [options, search, category]);
4370
4617
  const navigate = (event) => {
4371
4618
  const offset = { ArrowRight: 1, ArrowLeft: -1, ArrowDown: 6, ArrowUp: -6 }[event.key];
4372
4619
  if (offset === undefined && event.key !== "Home" && event.key !== "End")
@@ -4376,7 +4623,7 @@ function IqujiEmojiPicker({ value, options, onChange, label, searchLabel, emptyL
4376
4623
  setActive(next);
4377
4624
  buttons.current.get(next)?.focus();
4378
4625
  };
4379
- return /* @__PURE__ */ jsx34(IqujiPopover, {
4626
+ return /* @__PURE__ */ jsx35(IqujiPopover, {
4380
4627
  open,
4381
4628
  onOpenChange: (next) => {
4382
4629
  setOpen(next);
@@ -4386,21 +4633,21 @@ function IqujiEmojiPicker({ value, options, onChange, label, searchLabel, emptyL
4386
4633
  setActive(0);
4387
4634
  }
4388
4635
  },
4389
- trigger: /* @__PURE__ */ jsx34(IqujiButton, {
4636
+ trigger: /* @__PURE__ */ jsx35(IqujiButton, {
4390
4637
  variant,
4391
4638
  disabled,
4392
4639
  "aria-label": label,
4393
4640
  children: value ?? label
4394
4641
  }),
4395
- children: /* @__PURE__ */ jsxs30("section", {
4642
+ children: /* @__PURE__ */ jsxs31("section", {
4396
4643
  className: "iquji-emoji-picker",
4397
4644
  "aria-label": label,
4398
4645
  children: [
4399
- /* @__PURE__ */ jsx34("label", {
4646
+ /* @__PURE__ */ jsx35("label", {
4400
4647
  htmlFor: id,
4401
4648
  children: searchLabel
4402
4649
  }),
4403
- /* @__PURE__ */ jsx34(IqujiInput, {
4650
+ /* @__PURE__ */ jsx35(IqujiInput, {
4404
4651
  id,
4405
4652
  value: search,
4406
4653
  onChange: (event) => {
@@ -4414,12 +4661,12 @@ function IqujiEmojiPicker({ value, options, onChange, label, searchLabel, emptyL
4414
4661
  }
4415
4662
  }
4416
4663
  }),
4417
- categories.length > 0 && /* @__PURE__ */ jsxs30("div", {
4664
+ categories.length > 0 && /* @__PURE__ */ jsxs31("div", {
4418
4665
  className: "iquji-emoji-picker__categories",
4419
4666
  role: "group",
4420
4667
  "aria-label": label,
4421
4668
  children: [
4422
- /* @__PURE__ */ jsx34(IqujiButton, {
4669
+ /* @__PURE__ */ jsx35(IqujiButton, {
4423
4670
  compact: true,
4424
4671
  variant: "ghost",
4425
4672
  "aria-pressed": category === null,
@@ -4429,7 +4676,7 @@ function IqujiEmojiPicker({ value, options, onChange, label, searchLabel, emptyL
4429
4676
  },
4430
4677
  children: allLabel ?? searchLabel
4431
4678
  }),
4432
- categories.map((item) => /* @__PURE__ */ jsx34(IqujiButton, {
4679
+ categories.map((item) => /* @__PURE__ */ jsx35(IqujiButton, {
4433
4680
  compact: true,
4434
4681
  variant: "ghost",
4435
4682
  "aria-pressed": category === item,
@@ -4441,12 +4688,12 @@ function IqujiEmojiPicker({ value, options, onChange, label, searchLabel, emptyL
4441
4688
  }, item))
4442
4689
  ]
4443
4690
  }),
4444
- /* @__PURE__ */ jsx34("div", {
4691
+ /* @__PURE__ */ jsx35("div", {
4445
4692
  className: "iquji-emoji-picker__grid",
4446
4693
  role: "group",
4447
4694
  "aria-label": label,
4448
4695
  onKeyDown: navigate,
4449
- children: filtered.map((option, index) => /* @__PURE__ */ jsx34(IqujiButton, {
4696
+ children: filtered.map((option, index) => /* @__PURE__ */ jsx35(IqujiButton, {
4450
4697
  ref: (element) => {
4451
4698
  if (element)
4452
4699
  buttons.current.set(index, element);
@@ -4469,11 +4716,11 @@ function IqujiEmojiPicker({ value, options, onChange, label, searchLabel, emptyL
4469
4716
  children: option.value
4470
4717
  }, option.value))
4471
4718
  }),
4472
- !filtered.length && /* @__PURE__ */ jsx34("p", {
4719
+ !filtered.length && /* @__PURE__ */ jsx35("p", {
4473
4720
  role: "status",
4474
4721
  children: emptyLabel
4475
4722
  }),
4476
- /* @__PURE__ */ jsx34(IqujiButton, {
4723
+ /* @__PURE__ */ jsx35(IqujiButton, {
4477
4724
  variant: "ghost",
4478
4725
  onClick: () => {
4479
4726
  onChange(null);
@@ -4487,24 +4734,24 @@ function IqujiEmojiPicker({ value, options, onChange, label, searchLabel, emptyL
4487
4734
  }
4488
4735
 
4489
4736
  // src/index.tsx
4490
- import { jsx as jsx35, jsxs as jsxs31, Fragment as Fragment9 } from "react/jsx-runtime";
4737
+ import { jsx as jsx36, jsxs as jsxs32, Fragment as Fragment9 } from "react/jsx-runtime";
4491
4738
  var renderNavigationItem = (item) => {
4492
- const content = /* @__PURE__ */ jsxs31(Fragment9, {
4739
+ const content = /* @__PURE__ */ jsxs32(Fragment9, {
4493
4740
  children: [
4494
4741
  item.icon,
4495
- /* @__PURE__ */ jsx35("span", {
4742
+ /* @__PURE__ */ jsx36("span", {
4496
4743
  children: item.label
4497
4744
  })
4498
4745
  ]
4499
4746
  });
4500
- return item.disabled || !item.href ? /* @__PURE__ */ jsx35("button", {
4747
+ return item.disabled || !item.href ? /* @__PURE__ */ jsx36("button", {
4501
4748
  "aria-label": item.label,
4502
4749
  className: "iquji-app-shell__navigation-item",
4503
4750
  "data-disabled": "true",
4504
4751
  disabled: true,
4505
4752
  type: "button",
4506
4753
  children: content
4507
- }, item.id) : /* @__PURE__ */ jsx35("a", {
4754
+ }, item.id) : /* @__PURE__ */ jsx36("a", {
4508
4755
  "aria-label": item.label,
4509
4756
  "aria-current": item.active ? "page" : undefined,
4510
4757
  className: "iquji-app-shell__navigation-item",
@@ -4526,29 +4773,29 @@ function AppShell({
4526
4773
  mainId = "iquji-main-content",
4527
4774
  skipLinkLabel
4528
4775
  }) {
4529
- return /* @__PURE__ */ jsxs31("div", {
4776
+ return /* @__PURE__ */ jsxs32("div", {
4530
4777
  className: "iquji-app-shell",
4531
4778
  children: [
4532
- skipLinkLabel ? /* @__PURE__ */ jsx35("a", {
4779
+ skipLinkLabel ? /* @__PURE__ */ jsx36("a", {
4533
4780
  className: "iquji-skip-link",
4534
4781
  href: `#${mainId}`,
4535
4782
  children: skipLinkLabel
4536
4783
  }) : null,
4537
- /* @__PURE__ */ jsxs31("aside", {
4784
+ /* @__PURE__ */ jsxs32("aside", {
4538
4785
  className: "iquji-app-shell__sidebar",
4539
4786
  children: [
4540
- /* @__PURE__ */ jsx35("div", {
4787
+ /* @__PURE__ */ jsx36("div", {
4541
4788
  className: "iquji-app-shell__brand",
4542
4789
  children: brand
4543
4790
  }),
4544
- /* @__PURE__ */ jsx35("nav", {
4791
+ /* @__PURE__ */ jsx36("nav", {
4545
4792
  "aria-label": navigationLabel,
4546
4793
  className: "iquji-app-shell__navigation",
4547
- children: navigationGroups?.length ? navigationGroups.map((group) => /* @__PURE__ */ jsxs31("section", {
4794
+ children: navigationGroups?.length ? navigationGroups.map((group) => /* @__PURE__ */ jsxs32("section", {
4548
4795
  "aria-labelledby": `${group.id}-navigation-heading`,
4549
4796
  className: "iquji-app-shell__navigation-group",
4550
4797
  children: [
4551
- /* @__PURE__ */ jsx35("h2", {
4798
+ /* @__PURE__ */ jsx36("h2", {
4552
4799
  className: "iquji-app-shell__navigation-heading",
4553
4800
  id: `${group.id}-navigation-heading`,
4554
4801
  children: group.label
@@ -4559,14 +4806,14 @@ function AppShell({
4559
4806
  })
4560
4807
  ]
4561
4808
  }),
4562
- /* @__PURE__ */ jsxs31("div", {
4809
+ /* @__PURE__ */ jsxs32("div", {
4563
4810
  className: "iquji-app-shell__workspace",
4564
4811
  children: [
4565
- /* @__PURE__ */ jsx35("header", {
4812
+ /* @__PURE__ */ jsx36("header", {
4566
4813
  className: "iquji-app-shell__header",
4567
4814
  children: header
4568
4815
  }),
4569
- /* @__PURE__ */ jsx35("main", {
4816
+ /* @__PURE__ */ jsx36("main", {
4570
4817
  className: "iquji-app-shell__main",
4571
4818
  id: mainId,
4572
4819
  tabIndex: -1,
@@ -4594,7 +4841,7 @@ var IconButton = forwardRef3(function IconButton2({
4594
4841
  compact ? "iquji-icon-button--compact" : null,
4595
4842
  className
4596
4843
  ].filter(Boolean).join(" ");
4597
- return /* @__PURE__ */ jsx35("button", {
4844
+ return /* @__PURE__ */ jsx36("button", {
4598
4845
  ...buttonProps,
4599
4846
  "aria-busy": loading || undefined,
4600
4847
  "aria-label": label,
@@ -4603,10 +4850,10 @@ var IconButton = forwardRef3(function IconButton2({
4603
4850
  ref,
4604
4851
  title: label,
4605
4852
  type,
4606
- children: loading ? /* @__PURE__ */ jsx35("span", {
4853
+ children: loading ? /* @__PURE__ */ jsx36("span", {
4607
4854
  "aria-hidden": "true",
4608
4855
  className: "iquji-button__spinner"
4609
- }) : /* @__PURE__ */ jsx35("span", {
4856
+ }) : /* @__PURE__ */ jsx36("span", {
4610
4857
  "aria-hidden": "true",
4611
4858
  className: "iquji-icon-button__icon",
4612
4859
  children: icon
@@ -4619,7 +4866,7 @@ function StatusBadge({
4619
4866
  ...props
4620
4867
  }) {
4621
4868
  const names = ["iquji-status-badge", className].filter(Boolean).join(" ");
4622
- return /* @__PURE__ */ jsx35("span", {
4869
+ return /* @__PURE__ */ jsx36("span", {
4623
4870
  className: names,
4624
4871
  "data-tone": tone,
4625
4872
  ...props
@@ -4647,11 +4894,11 @@ var IqujiButton = forwardRef3(function IqujiButton2({
4647
4894
  allowLabelWrap ? "iquji-button--allow-label-wrap" : null,
4648
4895
  className
4649
4896
  ].filter(Boolean).join(" ");
4650
- const content = typeof children === "string" || typeof children === "number" ? /* @__PURE__ */ jsx35("span", {
4897
+ const content = typeof children === "string" || typeof children === "number" ? /* @__PURE__ */ jsx36("span", {
4651
4898
  className: "iquji-button__label",
4652
4899
  children
4653
4900
  }) : children;
4654
- return /* @__PURE__ */ jsxs31("button", {
4901
+ return /* @__PURE__ */ jsxs32("button", {
4655
4902
  ...buttonProps,
4656
4903
  "aria-busy": loading || undefined,
4657
4904
  className: names,
@@ -4659,16 +4906,16 @@ var IqujiButton = forwardRef3(function IqujiButton2({
4659
4906
  ref,
4660
4907
  type,
4661
4908
  children: [
4662
- loading ? /* @__PURE__ */ jsx35("span", {
4909
+ loading ? /* @__PURE__ */ jsx36("span", {
4663
4910
  className: "iquji-button__spinner",
4664
4911
  "aria-hidden": "true"
4665
- }) : iconStart ? /* @__PURE__ */ jsx35("span", {
4912
+ }) : iconStart ? /* @__PURE__ */ jsx36("span", {
4666
4913
  className: "iquji-button__icon",
4667
4914
  "aria-hidden": "true",
4668
4915
  children: iconStart
4669
4916
  }) : null,
4670
4917
  content,
4671
- !loading && iconEnd ? /* @__PURE__ */ jsx35("span", {
4918
+ !loading && iconEnd ? /* @__PURE__ */ jsx36("span", {
4672
4919
  className: "iquji-button__icon",
4673
4920
  "aria-hidden": "true",
4674
4921
  children: iconEnd
@@ -4702,11 +4949,11 @@ function IqujiButtonLink({
4702
4949
  allowLabelWrap ? "iquji-button-link--allow-label-wrap" : null,
4703
4950
  className
4704
4951
  ].filter(Boolean).join(" ");
4705
- const content = typeof children === "string" || typeof children === "number" ? /* @__PURE__ */ jsx35("span", {
4952
+ const content = typeof children === "string" || typeof children === "number" ? /* @__PURE__ */ jsx36("span", {
4706
4953
  className: "iquji-button__label",
4707
4954
  children
4708
4955
  }) : children;
4709
- return /* @__PURE__ */ jsxs31("a", {
4956
+ return /* @__PURE__ */ jsxs32("a", {
4710
4957
  ...anchorProps,
4711
4958
  "aria-busy": loading || undefined,
4712
4959
  "aria-disabled": blocked || undefined,
@@ -4724,16 +4971,16 @@ function IqujiButtonLink({
4724
4971
  },
4725
4972
  tabIndex: blocked ? -1 : tabIndex,
4726
4973
  children: [
4727
- loading ? /* @__PURE__ */ jsx35("span", {
4974
+ loading ? /* @__PURE__ */ jsx36("span", {
4728
4975
  className: "iquji-button__spinner",
4729
4976
  "aria-hidden": "true"
4730
- }) : iconStart ? /* @__PURE__ */ jsx35("span", {
4977
+ }) : iconStart ? /* @__PURE__ */ jsx36("span", {
4731
4978
  className: "iquji-button__icon",
4732
4979
  "aria-hidden": "true",
4733
4980
  children: iconStart
4734
4981
  }) : null,
4735
4982
  content,
4736
- !loading && iconEnd ? /* @__PURE__ */ jsx35("span", {
4983
+ !loading && iconEnd ? /* @__PURE__ */ jsx36("span", {
4737
4984
  className: "iquji-button__icon",
4738
4985
  "aria-hidden": "true",
4739
4986
  children: iconEnd
@@ -4748,11 +4995,11 @@ function IqujiPanel({
4748
4995
  ...sectionProps
4749
4996
  }) {
4750
4997
  const names = ["iquji-panel", className].filter(Boolean).join(" ");
4751
- return /* @__PURE__ */ jsxs31("section", {
4998
+ return /* @__PURE__ */ jsxs32("section", {
4752
4999
  className: names,
4753
5000
  ...sectionProps,
4754
5001
  children: [
4755
- header ? /* @__PURE__ */ jsx35("header", {
5002
+ header ? /* @__PURE__ */ jsx36("header", {
4756
5003
  className: "iquji-panel__header",
4757
5004
  children: header
4758
5005
  }) : null,
@@ -4769,20 +5016,20 @@ function IqujiPageHeading({
4769
5016
  titleId
4770
5017
  }) {
4771
5018
  const names = ["iquji-page-heading", className].filter(Boolean).join(" ");
4772
- return /* @__PURE__ */ jsxs31("div", {
5019
+ return /* @__PURE__ */ jsxs32("div", {
4773
5020
  className: names,
4774
5021
  children: [
4775
- /* @__PURE__ */ jsxs31("div", {
5022
+ /* @__PURE__ */ jsxs32("div", {
4776
5023
  children: [
4777
- kicker ? /* @__PURE__ */ jsx35("p", {
5024
+ kicker ? /* @__PURE__ */ jsx36("p", {
4778
5025
  className: "iquji-page-heading__kicker",
4779
5026
  children: kicker
4780
5027
  }) : null,
4781
- /* @__PURE__ */ jsx35("h1", {
5028
+ /* @__PURE__ */ jsx36("h1", {
4782
5029
  id: titleId,
4783
5030
  children: title
4784
5031
  }),
4785
- summary ? /* @__PURE__ */ jsx35("p", {
5032
+ summary ? /* @__PURE__ */ jsx36("p", {
4786
5033
  className: "iquji-page-heading__summary",
4787
5034
  children: summary
4788
5035
  }) : null
@@ -4803,24 +5050,24 @@ function IqujiEmptyState({
4803
5050
  ...sectionProps
4804
5051
  }) {
4805
5052
  const names = ["iquji-empty-state", className].filter(Boolean).join(" ");
4806
- return /* @__PURE__ */ jsxs31("section", {
5053
+ return /* @__PURE__ */ jsxs32("section", {
4807
5054
  className: names,
4808
5055
  ...sectionProps,
4809
5056
  children: [
4810
- icon ? /* @__PURE__ */ jsx35("span", {
5057
+ icon ? /* @__PURE__ */ jsx36("span", {
4811
5058
  className: "iquji-empty-state__icon",
4812
5059
  "aria-hidden": "true",
4813
5060
  children: icon
4814
5061
  }) : null,
4815
- title ? /* @__PURE__ */ jsx35("h2", {
5062
+ title ? /* @__PURE__ */ jsx36("h2", {
4816
5063
  id: titleId,
4817
5064
  children: title
4818
5065
  }) : null,
4819
- body ? /* @__PURE__ */ jsx35("p", {
5066
+ body ? /* @__PURE__ */ jsx36("p", {
4820
5067
  children: body
4821
5068
  }) : null,
4822
5069
  children,
4823
- action ? /* @__PURE__ */ jsx35("div", {
5070
+ action ? /* @__PURE__ */ jsx36("div", {
4824
5071
  className: "iquji-empty-state__action",
4825
5072
  children: action
4826
5073
  }) : null
@@ -4833,18 +5080,18 @@ function IqujiLoadingState({
4833
5080
  ...divProps
4834
5081
  }) {
4835
5082
  const names = ["iquji-loading-state", className].filter(Boolean).join(" ");
4836
- return /* @__PURE__ */ jsxs31("div", {
5083
+ return /* @__PURE__ */ jsxs32("div", {
4837
5084
  "aria-busy": "true",
4838
5085
  "aria-live": "polite",
4839
5086
  className: names,
4840
5087
  role: "status",
4841
5088
  ...divProps,
4842
5089
  children: [
4843
- /* @__PURE__ */ jsx35("span", {
5090
+ /* @__PURE__ */ jsx36("span", {
4844
5091
  className: "iquji-loading-state__spinner",
4845
5092
  "aria-hidden": "true"
4846
5093
  }),
4847
- /* @__PURE__ */ jsx35("span", {
5094
+ /* @__PURE__ */ jsx36("span", {
4848
5095
  children: label
4849
5096
  })
4850
5097
  ]
@@ -4858,6 +5105,7 @@ export {
4858
5105
  formatCalendarDate,
4859
5106
  StatusBadge,
4860
5107
  IqujiWorkbenchLayout,
5108
+ IqujiTour,
4861
5109
  IqujiTooltip,
4862
5110
  IqujiTimeline,
4863
5111
  IqujiTextarea,
package/dist/styles.css CHANGED
@@ -3837,6 +3837,139 @@
3837
3837
  height: 1px;
3838
3838
  }
3839
3839
 
3840
+ /* src/tour.css */
3841
+ .iquji-tour {
3842
+ position: fixed;
3843
+ pointer-events: none;
3844
+ inset: 0;
3845
+ }
3846
+
3847
+ .iquji-tour__mask {
3848
+ position: fixed;
3849
+ background: var(--iquji-color-overlay);
3850
+ pointer-events: auto;
3851
+ }
3852
+
3853
+ .iquji-tour__spotlight {
3854
+ position: fixed;
3855
+ box-sizing: border-box;
3856
+ border: 2px solid var(--iquji-color-accent);
3857
+ border-radius: var(--iquji-radius-control);
3858
+ box-shadow: 0 0 0 3px color-mix(in srgb, var(--iquji-color-accent) 18%, transparent);
3859
+ pointer-events: none;
3860
+ }
3861
+
3862
+ .iquji-tour__positioner {
3863
+ pointer-events: auto;
3864
+ z-index: 1;
3865
+ }
3866
+
3867
+ .iquji-tour__card {
3868
+ box-sizing: border-box;
3869
+ color: var(--iquji-color-text);
3870
+ background: var(--iquji-color-surface);
3871
+ border: 1px solid var(--iquji-color-border);
3872
+ border-radius: var(--iquji-radius-overlay);
3873
+ box-shadow: var(--iquji-shadow-modal);
3874
+ outline: none;
3875
+ animation: iquji-tour-appear var(--iquji-motion-overlay) var(--iquji-ease-enter);
3876
+ width: min(328px, 100vw - 32px);
3877
+ max-height: min(440px, 100dvh - 32px);
3878
+ }
3879
+
3880
+ .iquji-tour__body {
3881
+ box-sizing: border-box;
3882
+ max-height: inherit;
3883
+ overflow-y: auto;
3884
+ padding: var(--iquji-space-4);
3885
+ border-radius: inherit;
3886
+ }
3887
+
3888
+ .iquji-tour__header {
3889
+ display: flex;
3890
+ justify-content: space-between;
3891
+ align-items: flex-start;
3892
+ gap: var(--iquji-space-3);
3893
+ }
3894
+
3895
+ .iquji-tour__progress {
3896
+ color: var(--iquji-color-muted);
3897
+ font-size: var(--iquji-font-size-caption);
3898
+ margin-bottom: var(--iquji-space-1);
3899
+ line-height: 1.4;
3900
+ }
3901
+
3902
+ .iquji-tour__title {
3903
+ font-size: var(--iquji-font-size-title-sm);
3904
+ overflow-wrap: anywhere;
3905
+ margin: 0;
3906
+ font-weight: 600;
3907
+ line-height: 1.4;
3908
+ }
3909
+
3910
+ .iquji-tour__description {
3911
+ margin: var(--iquji-space-3) 0 0;
3912
+ color: var(--iquji-color-muted);
3913
+ font-size: var(--iquji-font-size-body-sm);
3914
+ overflow-wrap: anywhere;
3915
+ line-height: 1.6;
3916
+ }
3917
+
3918
+ .iquji-tour__description p {
3919
+ margin: 0;
3920
+ }
3921
+
3922
+ .iquji-tour__description p + p {
3923
+ margin-top: var(--iquji-space-2);
3924
+ }
3925
+
3926
+ .iquji-tour__actions {
3927
+ display: flex;
3928
+ justify-content: flex-end;
3929
+ gap: var(--iquji-space-2);
3930
+ margin-top: var(--iquji-space-4);
3931
+ flex-wrap: wrap;
3932
+ }
3933
+
3934
+ .iquji-tour__arrow {
3935
+ background: var(--iquji-color-surface);
3936
+ width: 10px;
3937
+ height: 10px;
3938
+ transform: rotate(45deg);
3939
+ }
3940
+
3941
+ .iquji-tour__arrow[data-side="bottom"] {
3942
+ top: -5px;
3943
+ }
3944
+
3945
+ .iquji-tour__arrow[data-side="top"] {
3946
+ bottom: -5px;
3947
+ }
3948
+
3949
+ .iquji-tour__arrow[data-side="right"] {
3950
+ left: -5px;
3951
+ }
3952
+
3953
+ .iquji-tour__arrow[data-side="left"] {
3954
+ right: -5px;
3955
+ }
3956
+
3957
+ @keyframes iquji-tour-appear {
3958
+ from {
3959
+ opacity: 0;
3960
+ }
3961
+
3962
+ to {
3963
+ opacity: 1;
3964
+ }
3965
+ }
3966
+
3967
+ @media (prefers-reduced-motion: reduce) {
3968
+ .iquji-tour__card {
3969
+ animation: none;
3970
+ }
3971
+ }
3972
+
3840
3973
  /* src/color-picker.css */
3841
3974
  .iquji-color-picker {
3842
3975
  box-sizing: border-box;
@@ -0,0 +1,10 @@
1
+ type TourTarget = {
2
+ id: string;
3
+ element: HTMLElement | null;
4
+ rect: DOMRect | null;
5
+ width: number;
6
+ height: number;
7
+ };
8
+ /** 只读取真实目标,延迟挂载和抽屉切换时保留当前教程步骤。 */
9
+ export declare function useTourTarget(open: boolean, id: string, resolve: () => HTMLElement | null): TourTarget;
10
+ export {};
package/dist/tour.d.ts ADDED
@@ -0,0 +1,18 @@
1
+ import { type ReactNode } from "react";
2
+ export type IqujiTourStep = {
3
+ id: string;
4
+ target: () => HTMLElement | null;
5
+ title: ReactNode;
6
+ description: ReactNode;
7
+ placement?: "top" | "right" | "bottom" | "left";
8
+ };
9
+ export type IqujiTourProps = {
10
+ open: boolean;
11
+ step: IqujiTourStep;
12
+ progress?: ReactNode;
13
+ actions?: ReactNode;
14
+ closeLabel: string;
15
+ onClose: () => void;
16
+ };
17
+ /** 教程只管理目标与提示浮层,业务状态和下一步授权由调用方控制。 */
18
+ export declare function IqujiTour({ open, step, progress, actions, closeLabel, onClose, }: IqujiTourProps): import("react/jsx-runtime").JSX.Element | null;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@iquji-web/web-component",
3
- "version": "0.1.6",
3
+ "version": "0.1.8",
4
4
  "license": "MIT",
5
5
  "type": "module",
6
6
  "files": [
@@ -24,8 +24,8 @@
24
24
  "react": "19.2.4"
25
25
  },
26
26
  "dependencies": {
27
- "@iquji-web/web-icons": "0.1.6",
28
- "@iquji-web/web-theme": "0.1.6",
27
+ "@iquji-web/web-icons": "0.1.8",
28
+ "@iquji-web/web-theme": "0.1.8",
29
29
  "@tanstack/react-table": "8.21.3"
30
30
  },
31
31
  "description": "React 通用交互组件与布局。",