@blocklet/ui-react 3.0.36 → 3.0.38

package/lib/Dashboard/index.js

@@ -1,52 +1,52 @@
 import { jsx as i } from "react/jsx-runtime";
 import "iconify-icon";
-import { use as I, useMemo as v, useLayoutEffect as w } from "react";
+import { use as I, useMemo as b, useLayoutEffect as v } from "react";
 import t from "prop-types";
 import { SessionContext as R } from "@arcblock/did-connect/lib/Session";
 import { useLocaleContext as T } from "@arcblock/ux/lib/Locale/context";
-import z from "@arcblock/ux/lib/Img";
-import A from "@arcblock/ux/lib/Layout/dashboard";
-import C from "@arcblock/ux/lib/hooks/use-blocklet-logo";
-import { SessionManagerProps as D, BlockletMetaProps as M } from "../types.js";
-import { mapRecursive as O, flatRecursive as j, matchPaths as H } from "../utils.js";
-import { formatBlockletInfo as S, getLocalizedNavigation as _, filterNavByRole as E, publicPath as m } from "../blocklets.js";
-import U from "../common/header-addons.js";
-import { useWalletHiddenTopbar as q } from "../common/wallet-hidden-topbar.js";
-function F({
+import C from "@arcblock/ux/lib/Img";
+import D from "@arcblock/ux/lib/Layout/dashboard";
+import M from "@arcblock/ux/lib/hooks/use-blocklet-logo";
+import { SessionManagerProps as A, BlockletMetaProps as O } from "../types.js";
+import { mapRecursive as j, flatRecursive as H, matchPaths as S } from "../utils.js";
+import { formatBlockletInfo as E, getLocalizedNavigation as U, filterNavByRole as _, publicPath as h } from "../blocklets.js";
+import q from "../common/header-addons.js";
+import { useWalletHiddenTopbar as F } from "../common/wallet-hidden-topbar.js";
+function G({
   meta: s = {},
-  fallbackUrl: a = m,
+  fallbackUrl: a = h,
   invalidPathFallback: l = null,
   headerAddons: k = void 0,
   sessionManagerProps: L = {
     showRole: !0,
     // dashboard 默认退出登录行为: 跳转到 (root) blocklet 首页
     onLogout: () => {
-      window.location.href = m;
+      window.location.href = h;
     }
   },
   links: c = [],
-  showDomainWarningDialog: N = !0,
-  ...h
+  showDomainWarningDialog: P = !0,
+  ...d
 }) {
-  q();
-  const d = I(R)?.session?.user, g = d?.role, { locale: x } = T() || {}, r = v(() => {
+  F();
+  const f = I(R)?.session?.user, g = f?.role, { locale: x } = T() || {}, r = b(() => {
     const e = Object.assign({}, window.blocklet, s);
     try {
-      return S(e);
+      return E(e);
     } catch (n) {
       return console.error("Failed to format blocklet info", n, e), e;
     }
-  }, [s]), { localizedNav: y, flattened: f, matchedIndex: b } = v(() => {
-    let e = _(r?.navigation?.dashboard, x) || [];
-    e = E(e, g), e = O(
+  }, [s]), { localizedNav: w, flattened: p, matchedIndex: y } = b(() => {
+    let e = U(r?.navigation?.dashboard, x) || [];
+    e = _(e, g), e = j(
       e,
       (o) => {
-        let u = null;
-        return o.icon && (o.icon.startsWith("http") || o.icon.startsWith("data:") ? u = /* @__PURE__ */ i(z, { src: o.icon }) : u = /* @__PURE__ */ i("iconify-icon", { height: "100%", width: "100%", icon: o.icon })), {
+        let m = null;
+        return o.icon && (o.icon.startsWith("http") || o.icon.startsWith("data:") ? m = /* @__PURE__ */ i(C, { src: o.icon }) : m = /* @__PURE__ */ i("iconify-icon", { height: "100%", width: "100%", icon: o.icon })), {
           id: o.id,
           title: o.title,
           url: o.link,
-          icon: u,
+          icon: m,
           // https://github.com/ArcBlock/ux/issues/755#issuecomment-1208692620
           external: !0,
           children: o.items
@@ -54,55 +54,56 @@ function F({
       },
       "items"
     );
-    const n = j(e).filter((o) => !!o.url), p = H(n.map((o) => o.url));
-    return p !== -1 && (n[p].active = !0), { localizedNav: e, flattened: n, matchedIndex: p };
-  }, [r, x, g]), P = typeof c == "function" ? c(y) : [...y, ...c], W = C({
+    const n = H(e).filter((o) => !!o.url), u = S(n.map((o) => o.url));
+    return u !== -1 && (n[u].active = !0), { localizedNav: e, flattened: n, matchedIndex: u };
+  }, [r, x, g]), W = typeof c == "function" ? c(w) : [...w, ...c], N = M({
     meta: s
   });
-  if (w(() => {
-    d && !f?.length && a && (window.location.href = a);
-  }, [a]), w(() => {
-    d && f?.length && b === -1 && l && l();
-  }, [l, f, b]), !r.appName)
+  if (v(() => {
+    f && !p?.length && a && (window.location.href = a);
+  }, [a]), v(() => {
+    f && p?.length && y === -1 && l && l();
+  }, [l, p, y]), !r.appName)
     return null;
-  const { appName: B } = r;
+  const { appName: z } = r, B = /* @__PURE__ */ i(
+    q,
+    {
+      formattedBlocklet: r,
+      addons: k,
+      sessionManagerProps: L,
+      showDomainWarningDialog: P,
+      showWizard: d.headerProps?.showWizard
+    }
+  );
   return /* @__PURE__ */ i(
-    A,
+    D,
     {
-      title: B,
+      title: z,
       fullWidth: !0,
       sidebarWidth: 128,
       legacy: !1,
-      links: P,
-      ...h,
+      links: W,
+      ...d,
       headerProps: {
-        homeLink: m,
-        logo: /* @__PURE__ */ i("img", { src: W, alt: "logo" }),
-        addons: /* @__PURE__ */ i(
-          U,
-          {
-            formattedBlocklet: r,
-            addons: k,
-            sessionManagerProps: L,
-            showDomainWarningDialog: N
-          }
-        ),
-        ...h.headerProps
+        homeLink: h,
+        logo: /* @__PURE__ */ i("img", { src: N, alt: "logo" }),
+        addons: B,
+        ...d.headerProps
       }
     }
   );
 }
-F.propTypes = {
-  meta: M,
+G.propTypes = {
+  meta: O,
   // 如果当前用户没有权限访问任何导航菜单, 则自动跳转到 fallbackUrl, 默认值为 publicPath, 设置为 null 表示禁用自动跳转
   fallbackUrl: t.string,
   // 当前路径未匹配任何 nav links 时的 fallback, 默认行为跳转到首个可用的 nav link
   invalidPathFallback: t.func,
   headerAddons: t.oneOfType([t.func, t.node]),
-  sessionManagerProps: D,
+  sessionManagerProps: A,
   links: t.oneOfType([t.array, t.func]),
   showDomainWarningDialog: t.bool
 };
 export {
-  F as default
+  G as default
 };

package/lib/Header/index.d.ts

@@ -18,6 +18,7 @@ type HeaderProps = {
     align?: 'left' | 'right';
     maxWidth?: false | Breakpoint;
     showDomainWarningDialog?: boolean;
+    showWizard?: boolean;
 };
 declare const _default: import('react').ComponentType<HeaderProps & Omit<BoxProps, keyof HeaderProps>>;
 export default _default;

package/lib/Header/index.js

@@ -1,41 +1,41 @@
 import { jsx as n } from "react/jsx-runtime";
-import { useMemo as k } from "react";
-import { useMemoizedFn as $ } from "ahooks";
-import { withErrorBoundary as N } from "react-error-boundary";
-import { ErrorFallback as H } from "@arcblock/ux/lib/ErrorBoundary";
-import { styled as y, useTheme as C, deepmerge as T, ThemeProvider as _ } from "@arcblock/ux/lib/Theme";
-import { ResponsiveHeader as E } from "@arcblock/ux/lib/Header";
-import B, { Products as F } from "@arcblock/ux/lib/NavMenu";
-import { useLocaleContext as L } from "@arcblock/ux/lib/Locale/context";
-import { translate as P } from "@arcblock/ux/lib/Locale/util";
-import R from "@arcblock/ux/lib/hooks/use-blocklet-logo";
-import z from "lodash/omit";
-import A from "lodash/isFinite";
-import M from "clsx";
-import W from "../Icon/index.js";
-import { mapRecursive as j, flatRecursive as S, matchPaths as U } from "../utils.js";
-import { formatBlockletInfo as K, getLocalizedNavigation as O, publicPath as q } from "../blocklets.js";
-import D from "../common/header-addons.js";
-import { useWalletHiddenTopbar as G } from "../common/wallet-hidden-topbar.js";
-import J from "../libs/with-hide-when-embed.js";
-const Q = {
+import { useMemo as v } from "react";
+import { useMemoizedFn as N } from "ahooks";
+import { withErrorBoundary as H } from "react-error-boundary";
+import { ErrorFallback as y } from "@arcblock/ux/lib/ErrorBoundary";
+import { styled as C, useTheme as T, deepmerge as _, ThemeProvider as E } from "@arcblock/ux/lib/Theme";
+import { ResponsiveHeader as B } from "@arcblock/ux/lib/Header";
+import F, { Products as L } from "@arcblock/ux/lib/NavMenu";
+import { useLocaleContext as P } from "@arcblock/ux/lib/Locale/context";
+import { translate as R } from "@arcblock/ux/lib/Locale/util";
+import z from "@arcblock/ux/lib/hooks/use-blocklet-logo";
+import A from "lodash/omit";
+import M from "lodash/isFinite";
+import W from "clsx";
+import j from "../Icon/index.js";
+import { mapRecursive as S, flatRecursive as U, matchPaths as K } from "../utils.js";
+import { formatBlockletInfo as O, getLocalizedNavigation as q, publicPath as D } from "../blocklets.js";
+import G from "../common/header-addons.js";
+import { useWalletHiddenTopbar as J } from "../common/wallet-hidden-topbar.js";
+import Q from "../libs/with-hide-when-embed.js";
+const V = {
   en: {
     products: "Products"
   },
   zh: {
     products: "产品"
   }
-}, V = (e) => {
+}, X = (e) => {
   if (!e?.length)
     return { navItems: [], activeId: null };
   let r = 1;
-  const s = j(e, (o) => {
-    const i = o.icon ? /* @__PURE__ */ n(W, { icon: o.icon }) : null;
+  const i = S(e, (o) => {
+    const d = o.icon ? /* @__PURE__ */ n(j, { icon: o.icon }) : null;
     if (o.items)
       return {
         id: `${r++}`,
         label: o.title,
-        icon: i,
+        icon: d,
         children: o.items
       };
     let l = {};
@@ -45,72 +45,74 @@ const Q = {
     }), {
       id: `${r++}`,
       label: /* @__PURE__ */ n("a", { href: o.link, ...l, children: o.title }),
-      icon: i,
+      icon: d,
       description: o.description,
       link: o.link
     };
-  }, "items"), a = S(s), d = U(a.map((o) => o.link));
-  return { navItems: s, activeId: d >= 0 ? a[d].id : null };
+  }, "items"), a = U(i), s = K(a.map((o) => o.link));
+  return { navItems: i, activeId: s >= 0 ? a[s].id : null };
 };
-function X({
+function Y({
   meta: e = {},
   addons: r = void 0,
   sessionManagerProps: u = {
     showRole: !0
   },
-  homeLink: s = q,
+  homeLink: i = D,
   theme: a = void 0,
-  hideNavMenu: d = !1,
+  hideNavMenu: s = !1,
   showDomainWarningDialog: o = !0,
-  ...i
+  showWizard: d = !1,
+  ...l
 }) {
-  G();
-  const l = C(), { locale: h } = L() || {}, v = $((t, f = {}) => P(Q, t, h, "en", f)), m = k(() => {
+  J();
+  const h = T(), { locale: b } = P() || {}, x = N((t, f = {}) => R(V, t, b, "en", f)), m = v(() => {
     const t = Object.assign({}, window.blocklet, e);
     try {
-      return K(t);
+      return O(t);
     } catch (f) {
       return console.error("Failed to format blocklet info", f, t), t;
     }
-  }, [e]), c = k(() => T(l, a), [l, a]), x = R({
+  }, [e]), c = v(() => _(h, a), [h, a]), I = z({
     meta: e,
     theme: a
   });
   if (!m.appName)
     return null;
-  const I = O(m?.navigation?.header, h), b = V(I), { navItems: p, activeId: w } = b, g = parseInt(window.blocklet?.USE_ARCBLOCK_THEME, 10);
-  return A(g) && p.splice(g, 0, {
-    label: v("products"),
+  const w = q(m?.navigation?.header, b), g = X(w), { navItems: p, activeId: $ } = g, k = parseInt(window.blocklet?.USE_ARCBLOCK_THEME, 10);
+  return M(k) && p.splice(k, 0, {
+    label: x("products"),
     // eslint-disable-next-line react/no-unstable-nested-components
-    children: ({ isOpen: t }) => /* @__PURE__ */ n(F, { isOpen: t })
-  }), /* @__PURE__ */ n(_, { theme: c, children: /* @__PURE__ */ n(
-    Y,
+    children: ({ isOpen: t }) => /* @__PURE__ */ n(L, { isOpen: t })
+  }), /* @__PURE__ */ n(E, { theme: c, children: /* @__PURE__ */ n(
+    Z,
     {
-      homeLink: s,
-      logo: /* @__PURE__ */ n("img", { src: x, alt: "logo" }),
+      homeLink: i,
+      logo: /* @__PURE__ */ n("img", { src: I, alt: "logo" }),
       addons: (
         // @ts-ignore
         /* @__PURE__ */ n(
-          D,
+          G,
           {
             formattedBlocklet: m,
-            addons: typeof r == "function" ? (t) => r(t, { navigation: b }) : r,
+            addons: typeof r == "function" ? (t) => r(t, { navigation: g }) : r,
             sessionManagerProps: u,
-            showDomainWarningDialog: o
+            showDomainWarningDialog: o,
+            showWizard: d
           }
         )
       ),
-      ...z(i, ["bordered"]),
-      $bordered: i?.bordered,
+      ...A(l, ["bordered"]),
+      $bordered: l?.bordered,
       $bgcolor: c.palette.background.default,
-      className: M("blocklet__header", i.className),
-      children: d || !p?.length ? null : ({ isMobile: t }) => (
+      className: W("blocklet__header", l.className),
+      children: s || !p?.length ? null : ({ isMobile: t }) => (
         // @ts-ignore
         /* @__PURE__ */ n(
-          B,
+          F,
           {
             mode: t ? "inline" : "horizontal",
-            activeId: w,
+            activeId: $,
             items: p,
             className: "header-nav",
             bgColor: "transparent",
@@ -122,7 +124,7 @@ function X({
     }
   ) });
 }
-const Y = y(E)`
+const Z = C(B)`
   ${({ $bgcolor: e }) => `background-color: ${e || "#fff"};`}
   .header-logo {
     min-width: 44px;
@@ -133,9 +135,9 @@ const Y = y(E)`
       min-width: 32px;
     }
   }
-`, wo = N(J(X), {
-  FallbackComponent: H
+`, $o = H(Q(Y), {
+  FallbackComponent: y
 });
 export {
-  wo as default
+  $o as default
 };

package/lib/common/header-addons.d.ts

@@ -1,12 +1,13 @@
 import { default as PropTypes } from 'prop-types';
 import { SessionManagerProps } from '../types';
-declare function HeaderAddons({ formattedBlocklet, addons, showDomainWarningDialog, sessionManagerProps, }: {
+declare function HeaderAddons({ formattedBlocklet, addons, showDomainWarningDialog, sessionManagerProps, showWizard, }: {
     formattedBlocklet: any;
     addons?: null | undefined;
     showDomainWarningDialog?: boolean | undefined;
     sessionManagerProps?: {
         showRole: boolean;
     } | undefined;
+    showWizard?: boolean | undefined;
 }): import('react').FunctionComponentElement<import('react').FragmentProps>;
 declare namespace HeaderAddons {
     namespace propTypes {
@@ -14,6 +15,7 @@ declare namespace HeaderAddons {
         export let addons: PropTypes.Requireable<NonNullable<((...args: any[]) => any) | PropTypes.ReactNodeLike>>;
         export { SessionManagerProps as sessionManagerProps };
         export let showDomainWarningDialog: PropTypes.Requireable<boolean>;
+        export let showWizard: PropTypes.Requireable<boolean>;
     }
 }
 export default HeaderAddons;

package/lib/common/header-addons.js

@@ -1,71 +1,132 @@
-import { jsx as s, Fragment as v } from "react/jsx-runtime";
+import { jsx as e, Fragment as x } from "react/jsx-runtime";
 import "iconify-icon";
-import { use as b, createElement as k } from "react";
-import r from "prop-types";
-import { SessionContext as w } from "@arcblock/did-connect/lib/Session";
-import L from "@arcblock/ux/lib/SessionUser";
-import N from "@arcblock/ux/lib/SessionBlocklet";
-import T from "@arcblock/ux/lib/Locale/selector";
-import { useLocaleContext as C } from "@arcblock/ux/lib/Locale/context";
-import R from "@arcblock/ux/lib/Config/theme-mode-toggle";
-import { SessionManagerProps as S } from "../types.js";
-import { getLocalizedNavigation as M, filterNavByRole as B } from "../blocklets.js";
-import D from "./notification-addon.js";
-import P from "./domain-warning.js";
-const j = () => !!(window?.blocklet?.navigation ?? []).find((o) => o.id === "/userCenter/notification");
-function x({
-  formattedBlocklet: l,
-  addons: o = null,
-  showDomainWarningDialog: m = !0,
-  sessionManagerProps: u = { showRole: !0 }
+import { useState as h, useEffect as L, use as N, createElement as W } from "react";
+import s from "prop-types";
+import { Tooltip as M, IconButton as R } from "@mui/material";
+import B from "@iconify-icons/tabler/wand";
+import { SessionContext as D } from "@arcblock/did-connect/lib/Session";
+import E from "@arcblock/ux/lib/SessionUser";
+import O from "@arcblock/ux/lib/SessionBlocklet";
+import P from "@arcblock/ux/lib/Locale/selector";
+import { useLocaleContext as g } from "@arcblock/ux/lib/Locale/context";
+import j from "@arcblock/ux/lib/Config/theme-mode-toggle";
+import { SessionManagerProps as F } from "../types.js";
+import { getLocalizedNavigation as I, filterNavByRole as q } from "../blocklets.js";
+import H from "./notification-addon.js";
+import U from "./domain-warning.js";
+import V from "./wizard-modal.js";
+const $ = () => !!(window?.blocklet?.navigation ?? []).find((i) => i.id === "/userCenter/notification");
+function G({
+  formattedBlocklet: m,
+  addons: i = null,
+  showDomainWarningDialog: y = !0,
+  sessionManagerProps: w = { showRole: !0 },
+  showWizard: T = !1
 }) {
-  const n = b(w), { locale: i, languages: p } = C() || {}, { enableConnect: g = !0, enableLocale: d = !0 } = l, h = !!n?.session?.user;
-  let a = M(l?.navigation?.sessionManager, i) || [];
-  a = B(a, n?.session?.user?.role);
-  const c = (() => {
-    if (o && typeof o != "function")
-      return Array.isArray(o) ? o : [o];
-    let e = [];
-    if (j() && e.push(/* @__PURE__ */ s(D, { session: n.session }, "notification-addon")), d && i && p.length > 1 && e.push(/* @__PURE__ */ s(T, { showText: !1 }, "locale-selector")), e.push(/* @__PURE__ */ s(R, {}, "theme-mode-toggle")), g && n) {
-      const f = [];
-      h && (a ? a.slice(0, 5) : []).forEach((t) => {
-        f.push({
-          label: t.title,
-          icon: t.icon ? /* @__PURE__ */ s("iconify-icon", { icon: t.icon, height: 24, style: { marginRight: 8 } }) : null,
+  const [d, p] = h(!1), [t, c] = h(!1), { t: b } = g();
+  L(() => {
+    let o;
+    return t && (o = setTimeout(() => {
+      c(!1);
+    }, 3e3)), () => {
+      o && clearTimeout(o);
+    };
+  }, [t]);
+  const n = N(D), { locale: r, languages: z } = g() || {}, { enableConnect: A = !0, enableLocale: k = !0 } = m, v = !!n?.session?.user;
+  let f = I(m?.navigation?.sessionManager, r) || [];
+  f = q(f, n?.session?.user?.role);
+  const u = (() => {
+    if (i && typeof i != "function")
+      return Array.isArray(i) ? i : [i];
+    let o = [];
+    if ($() && o.push(/* @__PURE__ */ e(H, { session: n.session }, "notification-addon")), k && r && z.length > 1 && o.push(/* @__PURE__ */ e(P, { showText: !1 }, "locale-selector")), o.push(/* @__PURE__ */ e(j, {}, "theme-mode-toggle")), T && o.push(
+      /* @__PURE__ */ e(
+        M,
+        {
+          title: b("setup.wizardTooltip"),
+          open: t,
+          placement: "bottom",
+          arrow: !0,
+          children: /* @__PURE__ */ e(
+            R,
+            {
+              size: "small",
+              onClick: () => {
+                p(!0), c(!1);
+              },
+              sx: {
+                display: { xs: "none", md: "flex" },
+                color: "text.secondary",
+                ...t && {
+                  backgroundColor: "action.hover",
+                  "@keyframes pulse": {
+                    "0%": { opacity: 0.8 },
+                    "50%": { opacity: 0.5 },
+                    "100%": { opacity: 0.8 }
+                  },
+                  animation: "pulse 2s infinite"
+                }
+              },
+              children: /* @__PURE__ */ e("iconify-icon", { icon: B, height: 20 })
+            }
+          )
+        },
+        `wizard-toggle-${t}`
+      ),
+      /* @__PURE__ */ e(
+        V,
+        {
+          show: d,
+          onChangeVisible: (a) => {
+            p(a), !a && d && c(!0);
+          },
+          onFinished: () => {
+            p(!1), c(!1);
+          }
+        },
+        "wizard-modal"
+      )
+    ), A && n) {
+      const a = [];
+      v && (f ? f.slice(0, 5) : []).forEach((l) => {
+        a.push({
+          label: l.title,
+          icon: l.icon ? /* @__PURE__ */ e("iconify-icon", { icon: l.icon, height: 24, style: { marginRight: 8 } }) : null,
           component: "a",
-          href: t.link,
-          key: t.link
+          href: l.link,
+          key: l.link
         });
-      }), e.push(/* @__PURE__ */ s(N, { session: n.session, locale: i }, "session-blocklet")), e.push(
-        /* @__PURE__ */ s(
-          L,
+      }), o.push(/* @__PURE__ */ e(O, { session: n.session, locale: r }, "session-blocklet")), o.push(
+        /* @__PURE__ */ e(
+          E,
           {
             session: n.session,
-            locale: i,
-            menu: f,
+            locale: r,
+            menu: a,
             showRole: !0,
-            ...u
+            ...w
           },
           "session-user"
         )
       );
     }
-    return typeof o == "function" && (e = o(e) || []), e;
-  })(), y = Array.isArray(c) ? c : [c], A = [
-    m ? /* @__PURE__ */ s(P, { session: n?.session, locale: i }) : null,
-    ...y
+    return typeof i == "function" && (o = i(o) || []), o;
+  })(), C = Array.isArray(u) ? u : [u], S = [
+    y ? /* @__PURE__ */ e(U, { session: n?.session, locale: r }) : null,
+    ...C
   ].filter(Boolean);
-  return k(v, null, ...A);
+  return W(x, null, ...S);
 }
-x.propTypes = {
-  formattedBlocklet: r.object.isRequired,
+G.propTypes = {
+  formattedBlocklet: s.object.isRequired,
   // 需要考虑 定制的 addons 与内置的 连接钱包/选择语言 addons 共存的情况
   // - PropTypes.func: 可以把自定义 addons 插在 session-manager 或 locale-selector (如果存在的话) 前/中/后
   // - PropTypes.node: 将 addons 原样传给 UX Header 组件
-  addons: r.oneOfType([r.func, r.node]),
-  sessionManagerProps: S,
-  showDomainWarningDialog: r.bool
+  addons: s.oneOfType([s.func, s.node]),
+  sessionManagerProps: F,
+  showDomainWarningDialog: s.bool,
+  showWizard: s.bool
 };
 export {
-  x as default
+  G as default
 };

package/lib/common/wizard-modal.d.ts

@@ -0,0 +1,14 @@
+import { default as PropTypes } from 'prop-types';
+declare function WizardModal({ onFinished, show, onChangeVisible }: {
+    onFinished?: (() => void) | undefined;
+    show?: boolean | undefined;
+    onChangeVisible?: (() => void) | undefined;
+}): import("react/jsx-runtime").JSX.Element | null;
+declare namespace WizardModal {
+    namespace propTypes {
+        let onFinished: PropTypes.Requireable<(...args: any[]) => any>;
+        let show: PropTypes.Requireable<boolean>;
+        let onChangeVisible: PropTypes.Requireable<(...args: any[]) => any>;
+    }
+}
+export default WizardModal;

package/lib/common/wizard-modal.js

@@ -0,0 +1,132 @@
+import { jsxs as I, jsx as m } from "react/jsx-runtime";
+import { useLocaleContext as U } from "@arcblock/ux/lib/Locale/context";
+import { useTheme as W, useMediaQuery as P, Dialog as T, Box as j, CircularProgress as E } from "@mui/material";
+import p from "prop-types";
+import { useState as w, useRef as g, useEffect as a } from "react";
+import { withQuery as M, joinURL as A } from "ufo";
+const h = "/.well-known/service/wizard/bind-account";
+function D({ onFinished: b = () => {
+}, show: o = !1, onChangeVisible: x = () => {
+} }) {
+  const [r, n] = w(o), [i, s] = w(!1), [y, l] = w(() => localStorage.getItem("wizard-current-url") || h), z = g(b), c = g(), d = g(null), { locale: R } = U(), C = W(), u = P(C.breakpoints.down("sm"));
+  if (z.current = b, c.current = () => {
+    if (d.current?.contentWindow)
+      try {
+        const t = new URL(d.current.contentWindow.location.href).pathname;
+        localStorage.setItem("wizard-current-url", t), l(t);
+      } catch (e) {
+        l(h), console.warn("Failed to save wizard URL:", e);
+      }
+    localStorage.setItem("wizard-completed", "true"), n(!1), x(!1);
+  }, a(() => {
+    o !== r && n(o);
+  }, [o]), a(() => {
+    !r && i && s(!1);
+  }, [r]), a(() => {
+    const e = (t) => {
+      if (t.origin !== window.location.origin)
+        return;
+      const { type: L, data: S } = t.data || {};
+      switch (L) {
+        case "wizard.loaded":
+          s(!0);
+          break;
+        case "wizard.finished": {
+          n(!1), l(h), localStorage.removeItem("wizard-current-url"), localStorage.setItem("wizard-completed", "true");
+          const f = z.current?.(S);
+          f instanceof Promise ? f.then((k) => {
+            k !== !1 && window.location.reload();
+          }) : f !== !1 && window.location.reload();
+          break;
+        }
+        case "wizard.close": {
+          c.current();
+          break;
+        }
+      }
+    };
+    return window.addEventListener("message", e), () => {
+      window.removeEventListener("message", e);
+    };
+  }, []), a(() => {
+    localStorage.getItem("wizard-completed") || n(!0);
+  }, []), !r)
+    return null;
+  const v = M(A(window.location.origin, y), {
+    locale: R
+  });
+  return /* @__PURE__ */ I(
+    T,
+    {
+      open: r,
+      onClose: () => c.current(),
+      fullWidth: !0,
+      maxWidth: u ? !1 : "md",
+      fullScreen: u,
+      slotProps: {
+        paper: {
+          sx: {
+            margin: 0,
+            borderRadius: 0,
+            position: "relative",
+            overflow: "hidden",
+            ...u ? { borderRadius: 0 } : {
+              borderRadius: 1,
+              height: "max(800px, 80vh)"
+            }
+          }
+        }
+      },
+      sx: {
+        "& .MuiBackdrop-root": {
+          backgroundColor: "rgba(0, 0, 0, 0.5)"
+        }
+      },
+      children: [
+        /* @__PURE__ */ m(
+          "iframe",
+          {
+            ref: d,
+            src: v,
+            title: "Setup Wizard",
+            style: {
+              width: "100%",
+              height: "100%",
+              border: 0,
+              padding: 0,
+              margin: 0,
+              opacity: i ? 1 : 0,
+              transition: "opacity 0.3s ease-in-out"
+            },
+            onLoad: () => s(!0)
+          }
+        ),
+        i ? null : /* @__PURE__ */ m(
+          j,
+          {
+            sx: {
+              position: "absolute",
+              top: 0,
+              left: 0,
+              right: 0,
+              bottom: 0,
+              display: "flex",
+              justifyContent: "center",
+              alignItems: "center",
+              bgcolor: "background.paper"
+            },
+            children: /* @__PURE__ */ m(E, {})
+          }
+        )
+      ]
+    }
+  );
+}
+D.propTypes = {
+  onFinished: p.func,
+  show: p.bool,
+  onChangeVisible: p.func
+};
+export {
+  D as default
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blocklet/ui-react",
-  "version": "3.0.36",
+  "version": "3.0.38",
   "description": "Some useful front-end web components that can be used in Blocklets.",
   "keywords": [
     "react",
@@ -35,12 +35,12 @@
   "dependencies": {
     "@abtnode/constant": "^1.16.46",
     "@abtnode/util": "^1.16.46",
-    "@arcblock/bridge": "3.0.36",
-    "@arcblock/icons": "3.0.36",
-    "@arcblock/react-hooks": "3.0.36",
+    "@arcblock/bridge": "3.0.38",
+    "@arcblock/icons": "3.0.38",
+    "@arcblock/react-hooks": "3.0.38",
     "@arcblock/ws": "^1.21.0",
     "@blocklet/constant": "^1.16.46",
-    "@blocklet/did-space-react": "^1.1.10",
+    "@blocklet/did-space-react": "^1.1.11",
     "@iconify-icons/logos": "^1.2.36",
     "@iconify-icons/material-symbols": "^1.2.58",
     "@iconify-icons/tabler": "^1.2.95",
@@ -91,5 +91,5 @@
     "jest": "^29.7.0",
     "unbuild": "^2.0.0"
   },
-  "gitHead": "8d2ee041615e72c57199253d5425b50872642e6e"
+  "gitHead": "643c8e01d5f5cb421b3315d4625177d1ccfa1ea1"
 }

package/src/Dashboard/index.jsx

@@ -129,6 +129,7 @@ function Dashboard({
       addons={headerAddons}
       sessionManagerProps={sessionManagerProps}
       showDomainWarningDialog={showDomainWarningDialog}
+      showWizard={rest.headerProps?.showWizard}
     />
   );
 

package/src/Header/index.tsx

@@ -93,6 +93,7 @@ type HeaderProps = {
   align?: 'left' | 'right';
   maxWidth?: false | Breakpoint;
   showDomainWarningDialog?: boolean;
+  showWizard?: boolean;
 };
 
 /**
@@ -110,6 +111,7 @@ function Header({
   theme: themeOverrides = undefined,
   hideNavMenu = false,
   showDomainWarningDialog = true,
+  showWizard = false,
   ...rest
 }: HeaderProps & Omit<BoxProps, keyof HeaderProps>) {
   useWalletHiddenTopbar();
@@ -164,6 +166,7 @@ function Header({
       // @ts-ignore
       sessionManagerProps={sessionManagerProps}
       showDomainWarningDialog={showDomainWarningDialog}
+      showWizard={showWizard}
     />
   );
 

package/src/common/header-addons.jsx

@@ -1,7 +1,10 @@
 import 'iconify-icon';
 
-import { use, createElement } from 'react';
+import { use, createElement, useState, useEffect } from 'react';
 import PropTypes from 'prop-types';
+import { IconButton, Tooltip } from '@mui/material';
+import WandIcon from '@iconify-icons/tabler/wand';
+
 // FIXME: 直接从 react 中 import  Fragment 可能会在 vite 下出错，先暂时从 react/jsx-runtime 导入 Fragment 来跳过这个问题
 import { Fragment } from 'react/jsx-runtime';
 import { SessionContext } from '@arcblock/did-connect/lib/Session';
@@ -15,6 +18,7 @@ import { SessionManagerProps } from '../types';
 import { getLocalizedNavigation, filterNavByRole } from '../blocklets';
 import NotificationAddon from './notification-addon';
 import DomainWarning from './domain-warning';
+import WizardModal from './wizard-modal';
 
 const hasNotification = () => {
   const navigations = window?.blocklet?.navigation ?? [];
@@ -27,7 +31,25 @@ export default function HeaderAddons({
   addons = null,
   showDomainWarningDialog = true,
   sessionManagerProps = { showRole: true },
+  showWizard = false,
 }) {
+  const [wizardOpen, setWizardOpen] = useState(false);
+  const [showTooltip, setShowTooltip] = useState(false);
+  const { t } = useLocaleContext();
+
+  // 处理 tooltip 倒计时
+  useEffect(() => {
+    let timer;
+    if (showTooltip) {
+      timer = setTimeout(() => {
+        setShowTooltip(false);
+      }, 3000); // 3秒后自动隐藏
+    }
+    return () => {
+      if (timer) clearTimeout(timer);
+    };
+  }, [showTooltip]);
+
   const sessionCtx = use(SessionContext);
   const { locale, languages } = useLocaleContext() || {};
   const { enableConnect = true, enableLocale = true } = formattedBlocklet;
@@ -55,6 +77,54 @@ export default function HeaderAddons({
     // 切换明暗主题
     addonsArray.push(<ThemeModeToggle key="theme-mode-toggle" />);
 
+    // Wizard 开关
+    if (showWizard) {
+      addonsArray.push(
+        <Tooltip
+          key={`wizard-toggle-${showTooltip}`}
+          title={t('setup.wizardTooltip')}
+          open={showTooltip}
+          placement="bottom"
+          arrow>
+          <IconButton
+            size="small"
+            onClick={() => {
+              setWizardOpen(true);
+              setShowTooltip(false); // 点击后隐藏 tooltip
+            }}
+            sx={{
+              display: { xs: 'none', md: 'flex' },
+              color: 'text.secondary',
+              ...(showTooltip && {
+                backgroundColor: 'action.hover',
+                '@keyframes pulse': {
+                  '0%': { opacity: 0.8 },
+                  '50%': { opacity: 0.5 },
+                  '100%': { opacity: 0.8 },
+                },
+                animation: 'pulse 2s infinite',
+              }),
+            }}>
+            <iconify-icon icon={WandIcon} height={20} />
+          </IconButton>
+        </Tooltip>,
+        <WizardModal
+          key="wizard-modal"
+          show={wizardOpen}
+          onChangeVisible={(visible) => {
+            setWizardOpen(visible);
+            if (!visible && wizardOpen) {
+              setShowTooltip(true);
+            }
+          }}
+          onFinished={() => {
+            setWizardOpen(false);
+            setShowTooltip(false);
+          }}
+        />
+      );
+    }
+
     // 启用了连接钱包并且检测到了 session context
     if (enableConnect && sessionCtx) {
       const menu = [];
@@ -110,4 +180,5 @@ HeaderAddons.propTypes = {
   addons: PropTypes.oneOfType([PropTypes.func, PropTypes.node]),
   sessionManagerProps: SessionManagerProps,
   showDomainWarningDialog: PropTypes.bool,
+  showWizard: PropTypes.bool,
 };

package/src/common/wizard-example.md

@@ -0,0 +1,168 @@
+# WizardModal 使用示例
+
+WizardModal 是一个自动弹窗的 iframe 组件，用于在页面加载时显示向导界面。
+
+## 基本用法
+
+### 在 Header 组件中使用
+
+```jsx
+import { Header } from '@arcblock/blocklet-ui-react';
+
+function App() {
+  return (
+    <Header
+      meta={blockletMeta}
+      // 默认不显示 wizard 按钮，设置为 true 启用
+      showWizard={true}
+    />
+  );
+}
+```
+
+### 默认行为
+
+```jsx
+// 默认不显示 wizard 按钮
+<Header meta={blockletMeta} />
+
+// 显示 wizard 按钮
+<Header meta={blockletMeta} showWizard={true} />
+```
+
+### 重置向导状态
+
+```javascript
+// 清除已完成标记，下次刷新页面时会重新显示向导
+localStorage.removeItem('wizard-completed');
+window.location.reload();
+```
+
+### 启用向导
+
+```jsx
+<Header
+  meta={blockletMeta}
+  showWizard={true} // 设置为 true 显示向导按钮
+/>
+```
+
+### 自定义向导 URL
+
+```jsx
+<Header
+  meta={blockletMeta}
+  wizardUrl="/.well-known/service/wizard/custom-setup"
+  onWizardFinished={(data) => {
+    console.log('自定义向导完成:', data);
+  }}
+/>
+```
+
+### 使用外部 URL
+
+```jsx
+<Header
+  meta={blockletMeta}
+  wizardUrl="https://external-wizard.example.com/setup"
+  onWizardFinished={(data) => {
+    console.log('外部向导完成:', data);
+  }}
+/>
+```
+
+## 直接使用 WizardModal 组件
+
+```jsx
+import { WizardModal } from '@arcblock/blocklet-ui-react/lib/common/wizard-modal';
+
+function MyComponent() {
+  const [showWizard, setShowWizard] = useState(false);
+
+  return (
+    <div>
+      <button onClick={() => setShowWizard(true)}>打开向导</button>
+
+      <WizardModal
+        open={showWizard}
+        wizardUrl="/.well-known/service/wizard/bind-account"
+        onFinished={(data) => {
+          console.log('向导完成:', data);
+          setShowWizard(false);
+        }}
+      />
+    </div>
+  );
+}
+```
+
+## 向导页面消息通信
+
+向导页面可以通过 postMessage 与父页面通信：
+
+### 向导页面发送消息
+
+```javascript
+// 通知父页面向导已加载完成
+window.parent.postMessage(
+  {
+    type: 'wizard.loaded',
+  },
+  window.location.origin
+);
+
+// 通知父页面向导已完成
+window.parent.postMessage(
+  {
+    type: 'wizard.finished',
+    data: { success: true, result: 'setup-complete' },
+  },
+  window.location.origin
+);
+
+// 通知父页面关闭向导
+window.parent.postMessage(
+  {
+    type: 'wizard.close',
+  },
+  window.location.origin
+);
+```
+
+## Props 说明
+
+### Header 组件新增 Props
+
+| 属性       | 类型    | 默认值 | 说明             |
+| ---------- | ------- | ------ | ---------------- |
+| showWizard | boolean | false  | 是否显示向导按钮 |
+
+### WizardModal 组件 Props
+
+| 属性            | 类型     | 默认值    | 说明                                 |
+| --------------- | -------- | --------- | ------------------------------------ |
+| show            | boolean  | false     | 控制弹窗显示状态                     |
+| onFinished      | function | undefined | 向导完成回调函数                     |
+| onChangeVisible | function | undefined | 弹窗显示状态变化回调                 |
+| onClose         | function | undefined | 弹窗关闭回调（isCompleted: boolean） |
+
+## 新增功能特性
+
+### 1. 智能提示系统
+
+- 点击遮罩关闭时显示 tooltip 提示："想要再次打开 wizard 可以点击这里"
+- Tooltip 显示 5 秒后自动消失
+- 完成向导后不显示 tooltip
+- 按钮在提示期间有闪烁动画效果
+
+### 2. URL 状态保存
+
+- 关闭 wizard 时自动保存当前 iframe 的 URL 到 localStorage
+- 下次打开时直接加载上次的位置，继续之前的进度
+- 完成向导后重置为默认 URL
+
+### 3. 交互优化
+
+- 点击遮罩或 ESC 键可以关闭弹窗
+- 关闭时会保存当前进度
+- 完成后自动清理临时状态

package/src/common/wizard-modal.jsx

@@ -0,0 +1,183 @@
+import { useLocaleContext } from '@arcblock/ux/lib/Locale/context';
+import { Box, CircularProgress, Dialog, useMediaQuery, useTheme } from '@mui/material';
+import PropTypes from 'prop-types';
+import { useEffect, useRef, useState } from 'react';
+import { joinURL, withQuery } from 'ufo';
+
+const DEFAULT_WIZARD_PATH = '/.well-known/service/wizard/bind-account';
+
+export default function WizardModal({ onFinished = () => {}, show = false, onChangeVisible = () => {} }) {
+  const [open, setOpen] = useState(show);
+  const [loaded, setLoaded] = useState(false);
+  const [currentUrl, setCurrentUrl] = useState(() => {
+    // 从 localStorage 恢复上次的 URL
+    return localStorage.getItem('wizard-current-url') || DEFAULT_WIZARD_PATH;
+  });
+  const onFinishedRef = useRef(onFinished);
+  const handleCloseRef = useRef();
+  const iframeRef = useRef(null);
+  const { locale } = useLocaleContext();
+  const theme = useTheme();
+  const isMobile = useMediaQuery(theme.breakpoints.down('sm'));
+  onFinishedRef.current = onFinished;
+
+  handleCloseRef.current = () => {
+    if (iframeRef.current?.contentWindow) {
+      try {
+        const url = new URL(iframeRef.current.contentWindow.location.href);
+        const savedUrl = url.pathname;
+        localStorage.setItem('wizard-current-url', savedUrl);
+        setCurrentUrl(savedUrl);
+      } catch (e) {
+        setCurrentUrl(DEFAULT_WIZARD_PATH);
+        console.warn('Failed to save wizard URL:', e);
+      }
+    }
+    localStorage.setItem('wizard-completed', 'true');
+    setOpen(false);
+    onChangeVisible(false);
+  };
+
+  useEffect(() => {
+    if (show !== open) {
+      setOpen(show);
+    }
+  }, [show]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  useEffect(() => {
+    if (!open && loaded) {
+      setLoaded(false);
+    }
+  }, [open]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  // 处理 iframe 消息
+  useEffect(() => {
+    const listener = (event) => {
+      // 只处理来自同源的消息
+      if (event.origin !== window.location.origin) {
+        return;
+      }
+
+      const { type, data } = event.data || {};
+
+      switch (type) {
+        case 'wizard.loaded':
+          setLoaded(true);
+          break;
+        case 'wizard.finished': {
+          setOpen(false);
+          // 完成后重置为默认 URL
+          setCurrentUrl(DEFAULT_WIZARD_PATH);
+          localStorage.removeItem('wizard-current-url');
+          localStorage.setItem('wizard-completed', 'true');
+          const result = onFinishedRef.current?.(data);
+          if (result instanceof Promise) {
+            result.then((reload) => {
+              if (reload !== false) {
+                window.location.reload();
+              }
+            });
+          } else if (result !== false) {
+            window.location.reload();
+          }
+          break;
+        }
+        case 'wizard.close': {
+          handleCloseRef.current();
+          break;
+        }
+        default:
+          break;
+      }
+    };
+
+    window.addEventListener('message', listener);
+    return () => {
+      window.removeEventListener('message', listener);
+    };
+  }, []);
+
+  // 控制弹窗显示
+  useEffect(() => {
+    const wizardCompleted = localStorage.getItem('wizard-completed');
+    if (!wizardCompleted) {
+      setOpen(true);
+    }
+  }, []);
+
+  if (!open) {
+    return null;
+  }
+
+  const src = withQuery(joinURL(window.location.origin, currentUrl), {
+    locale,
+  });
+
+  return (
+    <Dialog
+      open={open}
+      onClose={() => handleCloseRef.current()}
+      fullWidth
+      maxWidth={isMobile ? false : 'md'}
+      fullScreen={isMobile}
+      slotProps={{
+        paper: {
+          sx: {
+            margin: 0,
+            borderRadius: 0,
+            position: 'relative',
+            overflow: 'hidden',
+            ...(isMobile
+              ? { borderRadius: 0 }
+              : {
+                  borderRadius: 1,
+                  height: 'max(800px, 80vh)',
+                }),
+          },
+        },
+      }}
+      sx={{
+        '& .MuiBackdrop-root': {
+          backgroundColor: 'rgba(0, 0, 0, 0.5)',
+        },
+      }}>
+      <iframe
+        ref={iframeRef}
+        src={src}
+        title="Setup Wizard"
+        style={{
+          width: '100%',
+          height: '100%',
+          border: 0,
+          padding: 0,
+          margin: 0,
+          opacity: loaded ? 1 : 0,
+          transition: 'opacity 0.3s ease-in-out',
+        }}
+        onLoad={() => setLoaded(true)}
+      />
+      {loaded ? null : (
+        <Box
+          sx={{
+            position: 'absolute',
+            top: 0,
+            left: 0,
+            right: 0,
+            bottom: 0,
+            display: 'flex',
+            justifyContent: 'center',
+            alignItems: 'center',
+            bgcolor: 'background.paper',
+          }}>
+          <CircularProgress />
+        </Box>
+      )}
+    </Dialog>
+  );
+}
+
+WizardModal.propTypes = {
+  onFinished: PropTypes.func,
+  show: PropTypes.bool,
+  onChangeVisible: PropTypes.func,
+};