@arcblock/did-connect-react 3.1.40 → 3.1.42

package/docs/ui-components-button.zh-TW.md

@@ -0,0 +1,99 @@
+# 按鈕
+
+`ConnectButton` 元件提供了一個預設樣式且易於識別的按鈕，用於啟動 DID Connect 身份驗證過程。它簡化了為您的應用程式登入流程建立一致使用者體驗的過程。該按鈕採用 DID Connect 官方品牌設計，包括標誌和配色方案，為使用者提供了清晰的行動號召。
+
+## 匯入
+
+若要使用此按鈕，請從函式庫的 `Button` 模組中匯入。
+
+```javascript icon=logos:javascript
+import ConnectButton from '@arcblock/did-connect-react/lib/Button';
+```
+
+## 基本用法
+
+最常見的使用案例是將 `ConnectButton` 與 `useConnect` hook 搭配使用。按鈕的 `onClick` 屬性可以直接對應到 hook 回傳的 `open` 函式，以觸發連線對話框。
+
+```javascript Basic Usage icon=logos:react
+import { useConnect } from '@arcblock/did-connect-react/lib/Connect/use-connect';
+import ConnectButton from '@arcblock/did-connect-react/lib/Button';
+
+export default function MyLoginComponent() {
+  const { open } = useConnect();
+
+  return (
+    <ConnectButton onClick={open} />
+  );
+}
+```
+
+預設情況下，按鈕會顯示文字「Continue With」，後面跟著 DID Connect 標誌。
+
+## 自訂
+
+您可以輕鬆自訂按鈕的外觀和行為。
+
+### 自訂文字
+
+若要變更預設文字，只需將您想要的內容作為 children 傳遞給元件即可。
+
+```javascript Customizing Button Text icon=logos:react
+import { useConnect } from '@arcblock/did-connect-react/lib/Connect/use-connect';
+import ConnectButton from '@arcblock/did-connect-react/lib/Button';
+
+export default function CustomLoginComponent() {
+  const { open } = useConnect();
+
+  return (
+    <ConnectButton onClick={open}>
+      使用 DID 錢包登入
+    </ConnectButton>
+  );
+}
+```
+
+### 額外屬性
+
+`ConnectButton` 是 `@arcblock/ux/lib/Button` 元件（基於 Material-UI 的 Button）的封裝，並接受其所有標準屬性。這允許進行廣泛的自訂，例如禁用按鈕、使其全寬，或使用 `sx` 屬性應用自訂樣式。
+
+```javascript Passing Additional Props icon=logos:react
+import { useConnect } from '@arcblock/did-connect-react/lib/Connect/use-connect';
+import ConnectButton from '@arcblock/did-connect-react/lib/Button';
+
+export default function DisabledButtonComponent() {
+  const { open } = useConnect();
+
+  // 範例：在某個程序執行時禁用按鈕
+  const isLoading = true; 
+
+  return (
+    <ConnectButton
+      onClick={open}
+      disabled={isLoading}
+      fullWidth
+      sx={{ mt: 2, mb: 2 }}
+    >
+      {isLoading ? '連線中...' : '使用 DID 錢包登入'}
+    </ConnectButton>
+  );
+}
+```
+
+## 屬性
+
+<x-field-group>
+  <x-field data-name="children" data-type="React.ReactNode" data-required="false">
+    <x-field-desc markdown>要顯示在按鈕內的內容。如果未提供，預設為 `"Continue With"`。</x-field-desc>
+  </x-field>
+  <x-field data-name="...rest" data-type="ButtonProps" data-required="false">
+    <x-field-desc markdown>`ConnectButton` 接受任何其他對底層 Material-UI `Button` 元件有效的屬性。這包括 `onClick`、`disabled`、`variant`、`color`、`fullWidth` 和 `sx` 等常見屬性。</x-field-desc>
+  </x-field>
+</x-field-group>
+
+## 後續步驟
+
+現在您已經知道如何新增 `ConnectButton`，下一步理所當然是了解為其功能提供支援的 hook。
+
+<x-card data-title="useConnect Hook" data-href="/hooks/use-connect" data-icon="lucide:hook">
+  了解如何使用 useConnect hook 以程式化方式開啟、關閉和管理 DidConnect UI 對話框。
+</x-card>

package/docs/ui-components-button.zh.md

@@ -0,0 +1,99 @@
+# 按钮
+
+`ConnectButton` 组件提供了一个预设样式且易于识别的按钮，用于启动 DID Connect 身份验证过程。它简化了为你的应用程序登录流程创建一致用户体验的过程。该按钮采用官方 DID Connect 品牌风格，包括徽标和配色方案，为用户提供了清晰的操作指引。
+
+## 导入
+
+要使用该按钮，请从库的 `Button` 模块中导入它。
+
+```javascript icon=logos:javascript
+import ConnectButton from '@arcblock/did-connect-react/lib/Button';
+```
+
+## 基本用法
+
+最常见的用例是将 `ConnectButton` 与 `useConnect` 钩子配对使用。按钮的 `onClick` 属性可以直接映射到钩子返回的 `open` 函数，以触发连接模态框。
+
+```javascript Basic Usage icon=logos:react
+import { useConnect } from '@arcblock/did-connect-react/lib/Connect/use-connect';
+import ConnectButton from '@arcblock/did-connect-react/lib/Button';
+
+export default function MyLoginComponent() {
+  const { open } = useConnect();
+
+  return (
+    <ConnectButton onClick={open} />
+  );
+}
+```
+
+默认情况下，按钮会渲染文本“Continue With”，后面跟着 DID Connect 徽标。
+
+## 自定义
+
+你可以轻松自定义按钮的外观和行为。
+
+### 自定义文本
+
+要更改默认文本，只需将你想要的内容作为子元素传递给组件即可。
+
+```javascript Customizing Button Text icon=logos:react
+import { useConnect } from '@arcblock/did-connect-react/lib/Connect/use-connect';
+import ConnectButton from '@arcblock/did-connect-react/lib/Button';
+
+export default function CustomLoginComponent() {
+  const { open } = useConnect();
+
+  return (
+    <ConnectButton onClick={open}>
+      Login with DID Wallet
+    </ConnectButton>
+  );
+}
+```
+
+### 额外属性
+
+`ConnectButton` 是对 `@arcblock/ux/lib/Button` 组件（该组件基于 Material-UI 的 Button）的封装，并接受其所有标准属性。这允许进行广泛的自定义，例如禁用按钮、使其全宽或使用 `sx` 属性应用自定义样式。
+
+```javascript Passing Additional Props icon=logos:react
+import { useConnect } from '@arcblock/did-connect-react/lib/Connect/use-connect';
+import ConnectButton from '@arcblock/did-connect-react/lib/Button';
+
+export default function DisabledButtonComponent() {
+  const { open } = useConnect();
+
+  // Example: disable the button while a process is running
+  const isLoading = true; 
+
+  return (
+    <ConnectButton
+      onClick={open}
+      disabled={isLoading}
+      fullWidth
+      sx={{ mt: 2, mb: 2 }}
+    >
+      {isLoading ? 'Connecting...' : 'Login with DID Wallet'}
+    </ConnectButton>
+  );
+}
+```
+
+## 属性
+
+<x-field-group>
+  <x-field data-name="children" data-type="React.ReactNode" data-required="false">
+    <x-field-desc markdown>要在按钮内部显示的内容。如果未提供，则默认为 `"Continue With"`。</x-field-desc>
+  </x-field>
+  <x-field data-name="...rest" data-type="ButtonProps" data-required="false">
+    <x-field-desc markdown>`ConnectButton` 接受任何对底层 Material-UI `Button` 组件有效的其他属性。这包括 `onClick`、`disabled`、`variant`、`color`、`fullWidth` 和 `sx` 等常见属性。</x-field-desc>
+  </x-field>
+</x-field-group>
+
+## 下一步
+
+既然你已经知道如何添加 `ConnectButton`，下一个合乎逻辑的步骤是了解为其功能提供支持的钩子。
+
+<x-card data-title="useConnect 钩子" data-href="/hooks/use-connect" data-icon="lucide:hook">
+  学习如何使用 useConnect 钩子以编程方式打开、关闭和管理 DidConnect UI 模态框。
+</x-card>

package/docs/ui-components-logo.ja.md

@@ -0,0 +1,52 @@
+# ロゴ
+
+`Logo`コンポーネントは、アプリケーション内に公式のDID Connectロゴをシンプルかつ一貫して表示する方法を提供します。これはブランド表現のために設計された単純なビジュアルコンポーネントであり、ユーザーがおなじみの分散型ID接続方法を認識できるようにします。
+
+## 使用方法
+
+コンポーネントを使用するには、インポートしてJSXに含めるだけです。`size`プロップを使用してサイズを制御できます。
+
+```jsx MyHeader.js icon=logos:react
+import React from 'react';
+import Logo from '@arcblock/did-connect-react/lib/Logo';
+
+export default function AppHeader() {
+  return (
+    <header style={{ display: 'flex', alignItems: 'center', padding: '16px', borderBottom: '1px solid #eee' }}>
+      <Logo size={40} />
+      <h1 style={{ marginLeft: '12px', fontSize: '24px' }}>My Application</h1>
+    </header>
+  );
+}
+```
+
+## プロップ
+
+`Logo`コンポーネントはSVG要素のラッパーであり、以下のプロップを受け付けます：
+
+<x-field-group>
+  <x-field data-name="size" data-type="number" data-default="24" data-desc="ロゴの幅と高さをピクセル単位で設定します。"></x-field>
+  <x-field data-name="...rest" data-type="any" data-desc="その他のプロップは、基になるSVG要素に直接渡され、`className`や`style`などの属性でカスタマイズできます。"></x-field>
+</x-field-group>
+
+## 使用する場面
+
+- アプリケーションのヘッダーまたはフッターに表示して、DID Connectを利用していることを示します。
+- ログイン画面や接続画面で、ブランドの一貫性を保つために`Button`の近くや`DidConnect`モーダル内に配置します。
+- 利用可能な認証方法を説明する情報ページや「About」ページに表示します。
+
+## 次のステップ
+
+`Logo`を追加した後、他のUIコンポーネントを調べてユーザーインターフェースを完成させてください：
+
+<x-cards>
+  <x-card data-title="Button" data-href="/ui-components/button" data-icon="lucide:mouse-pointer-click">
+    事前にスタイル設定されたButtonコンポーネントを使用して、DID Connectフローをトリガーします。
+  </x-card>
+  <x-card data-title="Avatar" data-href="/ui-components/avatar" data-icon="lucide:user-circle">
+    ユーザーが正常にログインした後、そのプロフィール写真を表示します。
+  </x-card>
+  <x-card data-title="Address" data-href="/ui-components/address" data-icon="lucide:fingerprint">
+    ユーザーの分散型識別子（DID）を整形された読みやすい方法で表示します。
+  </x-card>
+</x-cards>

package/docs/ui-components-logo.md

@@ -0,0 +1,52 @@
+# Logo
+
+The `Logo` component provides a simple and consistent way to display the official DID Connect logo within your application. It's a straightforward visual component designed for brand representation, ensuring your users recognize the familiar decentralized identity connection method.
+
+## Usage
+
+To use the component, simply import it and include it in your JSX. You can control its size using the `size` prop.
+
+```jsx MyHeader.js icon=logos:react
+import React from 'react';
+import Logo from '@arcblock/did-connect-react/lib/Logo';
+
+export default function AppHeader() {
+  return (
+    <header style={{ display: 'flex', alignItems: 'center', padding: '16px', borderBottom: '1px solid #eee' }}>
+      <Logo size={40} />
+      <h1 style={{ marginLeft: '12px', fontSize: '24px' }}>My Application</h1>
+    </header>
+  );
+}
+```
+
+## Props
+
+The `Logo` component is a wrapper around an SVG element and accepts the following props:
+
+<x-field-group>
+  <x-field data-name="size" data-type="number" data-default="24" data-desc="Sets both the width and height of the logo in pixels."></x-field>
+  <x-field data-name="...rest" data-type="any" data-desc="Any other props are passed directly to the underlying SVG element, allowing for customization with attributes like `className` or `style`."></x-field>
+</x-field-group>
+
+## When to Use
+
+- In the header or footer of your application to show that it's powered by DID Connect.
+- On login or connection screens, often placed near the `Button` or within the `DidConnect` modal for brand consistency.
+- On informational or "About" pages that describe the authentication methods available.
+
+## Next Steps
+
+After adding the `Logo`, explore other UI components to complete your user interface:
+
+<x-cards>
+  <x-card data-title="Button" data-href="/ui-components/button" data-icon="lucide:mouse-pointer-click">
+    Use the pre-styled Button component to trigger the DID Connect flow.
+  </x-card>
+  <x-card data-title="Avatar" data-href="/ui-components/avatar" data-icon="lucide:user-circle">
+    Display a user's profile picture after they have successfully logged in.
+  </x-card>
+  <x-card data-title="Address" data-href="/ui-components/address" data-icon="lucide:fingerprint">
+    Show the user's decentralized identifier (DID) in a formatted and readable way.
+  </x-card>
+</x-cards>

package/docs/ui-components-logo.zh-TW.md

@@ -0,0 +1,52 @@
+# Logo
+
+`Logo` 組件提供了一種簡單且一致的方式，在您的應用程式中顯示官方的 DID Connect 標誌。它是一個專為品牌形象設計的直觀視覺組件，確保您的用戶能識別出這種熟悉的去中心化身份連接方式。
+
+## 使用方式
+
+若要使用此組件，只需匯入並將其包含在您的 JSX 中。您可以使用 `size` prop 控制其大小。
+
+```jsx MyHeader.js icon=logos:react
+import React from 'react';
+import Logo from '@arcblock/did-connect-react/lib/Logo';
+
+export default function AppHeader() {
+  return (
+    <header style={{ display: 'flex', alignItems: 'center', padding: '16px', borderBottom: '1px solid #eee' }}>
+      <Logo size={40} />
+      <h1 style={{ marginLeft: '12px', fontSize: '24px' }}>My Application</h1>
+    </header>
+  );
+}
+```
+
+## 屬性
+
+`Logo` 組件是 SVG 元素的封裝，可接受以下屬性：
+
+<x-field-group>
+  <x-field data-name="size" data-type="number" data-default="24" data-desc="設定標誌的寬度和高度（以像素為單位）。"></x-field>
+  <x-field data-name="...rest" data-type="any" data-desc="任何其他屬性都會直接傳遞給底層的 SVG 元素，允許使用 `className` 或 `style` 等屬性進行自訂。"></x-field>
+</x-field-group>
+
+## 何時使用
+
+- 在您的應用程式的頁首或頁尾，用以顯示其由 DID Connect 提供支援。
+- 在登入或連接畫面上，通常放置在 `Button` 附近或 `DidConnect` 彈出視窗內，以保持品牌一致性。
+- 在描述可用身份驗證方法的資訊頁或「關於」頁面。
+
+## 後續步驟
+
+新增 `Logo` 後，您可以探索其他 UI 組件來完善您的使用者介面：
+
+<x-cards>
+  <x-card data-title="Button" data-href="/ui-components/button" data-icon="lucide:mouse-pointer-click">
+    使用預先設定樣式的按鈕組件來觸發 DID Connect 流程。
+  </x-card>
+  <x-card data-title="Avatar" data-href="/ui-components/avatar" data-icon="lucide:user-circle">
+    在使用者成功登入後，顯示其個人資料圖片。
+  </x-card>
+  <x-card data-title="Address" data-href="/ui-components/address" data-icon="lucide:fingerprint">
+    以格式化且易於閱讀的方式顯示使用者的去中心化識別碼 (DID)。
+  </x-card>
+</x-cards>

package/docs/ui-components-logo.zh.md

@@ -0,0 +1,52 @@
+# Logo
+
+`Logo` 组件提供了一种简单且一致的方式，在您的应用程序中显示官方的 DID Connect 徽标。它是一个专为品牌展示而设计的直观视觉组件，确保您的用户能够识别这种熟悉的去中心化身份连接方式。
+
+## 用法
+
+要使用该组件，只需导入它并将其包含在您的 JSX 中。您可以使用 `size` 属性来控制其大小。
+
+```jsx MyHeader.js icon=logos:react
+import React from 'react';
+import Logo from '@arcblock/did-connect-react/lib/Logo';
+
+export default function AppHeader() {
+  return (
+    <header style={{ display: 'flex', alignItems: 'center', padding: '16px', borderBottom: '1px solid #eee' }}>
+      <Logo size={40} />
+      <h1 style={{ marginLeft: '12px', fontSize: '24px' }}>我的应用</h1>
+    </header>
+  );
+}
+```
+
+## 属性
+
+`Logo` 组件是 SVG 元素的包装器，接受以下属性：
+
+<x-field-group>
+  <x-field data-name="size" data-type="number" data-default="24" data-desc="设置徽标的宽度和高度，单位为像素。"></x-field>
+  <x-field data-name="...rest" data-type="any" data-desc="任何其他属性都会直接传递给底层的 SVG 元素，从而允许使用 `className` 或 `style` 等属性进行自定义。"></x-field>
+</x-field-group>
+
+## 何时使用
+
+- 在应用程序的页眉或页脚中，以表明它由 DID Connect 提供支持。
+- 在登录或连接屏幕上，通常放置在 `Button` 附近或 `DidConnect` 模态框内，以保持品牌一致性。
+- 在描述可用身份验证方法的信息性或“关于”页面上。
+
+## 后续步骤
+
+添加 `Logo` 后，探索其他 UI 组件以完善您的用户界面：
+
+<x-cards>
+  <x-card data-title="Button" data-href="/ui-components/button" data-icon="lucide:mouse-pointer-click">
+    使用预设样式的 Button 组件来触发 DID Connect 流程。
+  </x-card>
+  <x-card data-title="Avatar" data-href="/ui-components/avatar" data-icon="lucide:user-circle">
+    在用户成功登录后，显示其个人资料图片。
+  </x-card>
+  <x-card data-title="Address" data-href="/ui-components/address" data-icon="lucide:fingerprint">
+    以格式化且易于阅读的方式显示用户的去中心化标识符（DID）。
+  </x-card>
+</x-cards>

package/docs/ui-components.ja.md

@@ -0,0 +1,57 @@
+# UIコンポーネント
+
+`@arcblock/did-connect-react`ライブラリには、DID関連情報を一貫性があり、美しく表示するのに役立つように設計された、事前にスタイル設定された補助的なUIコンポーネントのセットが含まれています。これらのコンポーネントは、コア接続フローとシームレスに連携し、堅牢な`@arcblock/ux`および`@mui/material`ライブラリ上に構築されており、アプリケーションにまとまりのあるルックアンドフィールを保証します。
+
+このセクションでは、これらのコンポーネントの概要を説明します。いずれかのカードをクリックすると、プロパティや使用例を含む詳細なドキュメントが表示されます。
+
+<x-cards data-columns="2">
+  <x-card data-title="Avatar" data-href="/ui-components/avatar" data-icon="lucide:user-circle-2">
+    ユーザーのアバターを表示するために設計されたコンポーネントで、DIDから自動的に派生します。
+  </x-card>
+  <x-card data-title="Address" data-href="/ui-components/address" data-icon="lucide:key-round">
+    ユーザーのDIDアドレスを、読みやすさを向上させるためにフォーマットされ、オプションで短縮された形式で表示するために使用されます。
+  </x-card>
+  <x-card data-title="Button" data-href="/ui-components/button" data-icon="lucide:mouse-pointer-click">
+    一貫したデザインでDID Connectフローを開始するための、事前にスタイル設定されたボタン、具体的には`ConnectButton`。
+  </x-card>
+  <x-card data-title="Logo" data-href="/ui-components/logo" data-icon="lucide:hexagon">
+    公式のDID Connectロゴを表示するためのシンプルなコンポーネントで、ブランディングとUIの一貫性に役立ちます。
+  </x-card>
+</x-cards>
+
+## 組み合わせた使用例
+
+これらのコンポーネントは、ユーザーインターフェースを構築するために組み合わせて使用できるように設計されています。`Avatar`、`Address`、`ConnectButton`を使用して簡単なユーザープロフィール表示を作成する方法の例を次に示します。
+
+```javascript Combined UI Example icon=logos:react
+import Avatar from '@arcblock/did-connect-react/lib/Avatar';
+import Address from '@arcblock/did-connect-react/lib/Address';
+import ConnectButton from '@arcblock/did-connect-react/lib/Button';
+import { Box, Typography, Paper } from '@mui/material';
+
+function UserDisplay({ userDid, userName }) {
+  if (!userDid) {
+    return <ConnectButton />;
+  }
+
+  return (
+    <Paper elevation={2} sx={{ padding: '16px', display: 'flex', alignItems: 'center', gap: '16px' }}>
+      <Avatar size={60} did={userDid} />
+      <Box>
+        <Typography variant="h6" component="div">{userName || 'Anonymous'}</Typography>
+        <Address variant="body2" color="text.secondary">{userDid}</Address>
+      </Box>
+    </Paper>
+  );
+}
+
+// 使用例:
+// <UserDisplay userDid="z123..." userName="Alice" />
+// <UserDisplay userDid={null} />
+```
+
+この例は、提供されているコンポーネントを使用して、ログイン状態とログアウト状態の一般的なUIパターンをいかに簡単に構築できるかを示しています。
+
+### 次のステップ
+
+UIコンポーネントに慣れたら、認証フローとセッションデータをよりプログラム的に制御するために、ライブラリの[Hooks](./hooks.md)を調べてみるとよいでしょう。

package/docs/ui-components.md

@@ -0,0 +1,57 @@
+# UI Components
+
+The `@arcblock/did-connect-react` library includes a set of pre-styled, supplementary UI components designed to help you display DID-related information consistently and beautifully. These components work seamlessly with the core connection flow and are built upon the robust `@arcblock/ux` and `@mui/material` libraries, ensuring a cohesive look and feel in your application.
+
+This section provides an overview of these components. Click on any card to view detailed documentation, including properties and usage examples.
+
+<x-cards data-columns="2">
+  <x-card data-title="Avatar" data-href="/ui-components/avatar" data-icon="lucide:user-circle-2">
+    A component designed to display a user's avatar, which is automatically derived from their DID.
+  </x-card>
+  <x-card data-title="Address" data-href="/ui-components/address" data-icon="lucide:key-round">
+    Used for displaying a user's DID address in a formatted and optionally shortened manner for better readability.
+  </x-card>
+  <x-card data-title="Button" data-href="/ui-components/button" data-icon="lucide:mouse-pointer-click">
+    A pre-styled button, specifically the `ConnectButton`, for initiating the DID Connect flow with a consistent design.
+  </x-card>
+  <x-card data-title="Logo" data-href="/ui-components/logo" data-icon="lucide:hexagon">
+    A simple component to display the official DID Connect logo, useful for branding and UI consistency.
+  </x-card>
+</x-cards>
+
+## Combined Usage Example
+
+These components are designed to be composed together to build user interfaces. Here is an example of how you might use `Avatar`, `Address`, and `ConnectButton` to create a simple user profile display.
+
+```javascript Combined UI Example icon=logos:react
+import Avatar from '@arcblock/did-connect-react/lib/Avatar';
+import Address from '@arcblock/did-connect-react/lib/Address';
+import ConnectButton from '@arcblock/did-connect-react/lib/Button';
+import { Box, Typography, Paper } from '@mui/material';
+
+function UserDisplay({ userDid, userName }) {
+  if (!userDid) {
+    return <ConnectButton />;
+  }
+
+  return (
+    <Paper elevation={2} sx={{ padding: '16px', display: 'flex', alignItems: 'center', gap: '16px' }}>
+      <Avatar size={60} did={userDid} />
+      <Box>
+        <Typography variant="h6" component="div">{userName || 'Anonymous'}</Typography>
+        <Address variant="body2" color="text.secondary">{userDid}</Address>
+      </Box>
+    </Paper>
+  );
+}
+
+// Example usage:
+// <UserDisplay userDid="z123..." userName="Alice" />
+// <UserDisplay userDid={null} />
+```
+
+This example demonstrates how easily you can construct a common UI pattern for logged-in and logged-out states using the provided components.
+
+### Next Steps
+
+After familiarizing yourself with the UI components, you may want to explore the library's [Hooks](./hooks.md) for more programmatic control over the authentication flow and session data.

package/docs/ui-components.zh-TW.md

@@ -0,0 +1,57 @@
+# UI 元件
+
+`@arcblock/did-connect-react` 函式庫包含一組預先設計樣式的輔助 UI 元件，旨在幫助您以一致且美觀的方式顯示 DID 相關資訊。這些元件與核心連接流程無縫協作，並建立在強大的 `@arcblock/ux` 和 `@mui/material` 函式庫之上，確保您的應用程式具有一致的外觀和風格。
+
+本節提供這些元件的概述。點擊任何卡片以查看詳細文件，包括屬性和使用範例。
+
+<x-cards data-columns="2">
+  <x-card data-title="Avatar" data-href="/ui-components/avatar" data-icon="lucide:user-circle-2">
+    一個用於顯示使用者頭像的元件，頭像會根據其 DID 自動產生。
+  </x-card>
+  <x-card data-title="Address" data-href="/ui-components/address" data-icon="lucide:key-round">
+    用於以格式化且可選縮短的方式顯示使用者的 DID 位址，以提高可讀性。
+  </x-card>
+  <x-card data-title="Button" data-href="/ui-components/button" data-icon="lucide:mouse-pointer-click">
+    一個預先設計樣式的按鈕，特別是 `ConnectButton`，用於以一致的設計啟動 DID Connect 流程。
+  </x-card>
+  <x-card data-title="Logo" data-href="/ui-components/logo" data-icon="lucide:hexagon">
+    一個用於顯示官方 DID Connect 標誌的簡單元件，有助於品牌推廣和 UI 一致性。
+  </x-card>
+</x-cards>
+
+## 組合使用範例
+
+這些元件設計用於組合在一起以建構使用者介面。以下是如何使用 `Avatar`、`Address` 和 `ConnectButton` 建立簡單使用者個人資料顯示的範例。
+
+```javascript 組合 UI 範例 icon=logos:react
+import Avatar from '@arcblock/did-connect-react/lib/Avatar';
+import Address from '@arcblock/did-connect-react/lib/Address';
+import ConnectButton from '@arcblock/did-connect-react/lib/Button';
+import { Box, Typography, Paper } from '@mui/material';
+
+function UserDisplay({ userDid, userName }) {
+  if (!userDid) {
+    return <ConnectButton />;
+  }
+
+  return (
+    <Paper elevation={2} sx={{ padding: '16px', display: 'flex', alignItems: 'center', gap: '16px' }}>
+      <Avatar size={60} did={userDid} />
+      <Box>
+        <Typography variant="h6" component="div">{userName || 'Anonymous'}</Typography>
+        <Address variant="body2" color="text.secondary">{userDid}</Address>
+      </Box>
+    </Paper>
+  );
+}
+
+// Example usage:
+// <UserDisplay userDid="z123..." userName="Alice" />
+// <UserDisplay userDid={null} />
+```
+
+此範例展示了如何使用提供的元件輕鬆建構登入和登出狀態的常見 UI 模式。
+
+### 後續步驟
+
+熟悉 UI 元件後，您可能想探索該函式庫的 [Hooks](./hooks.md)，以對身份驗證流程和會話資料進行更多程式化控制。

package/docs/ui-components.zh.md

@@ -0,0 +1,57 @@
+# UI 组件
+
+`@arcblock/did-connect-react` 库包含一组预设样式、辅助性的 UI 组件，旨在帮助你以一致且美观的方式显示 DID 相关信息。这些组件与核心连接流程无缝协作，并基于强大的 `@arcblock/ux` 和 `@mui/material` 库构建，确保在你的应用程序中拥有一致的外观和感觉。
+
+本节提供了这些组件的概述。点击任一卡片即可查看详细文档，包括属性和使用示例。
+
+<x-cards data-columns="2">
+  <x-card data-title="Avatar" data-href="/ui-components/avatar" data-icon="lucide:user-circle-2">
+    一个旨在显示用户头像的组件，该头像根据用户的 DID 自动派生。
+  </x-card>
+  <x-card data-title="Address" data-href="/ui-components/address" data-icon="lucide:key-round">
+    用于以格式化且可选缩短的方式显示用户的 DID 地址，以提高可读性。
+  </x-card>
+  <x-card data-title="Button" data-href="/ui-components/button" data-icon="lucide:mouse-pointer-click">
+    一个预设样式的按钮，特别是 `ConnectButton`，用于以一致的设计启动 DID Connect 流程。
+  </x-card>
+  <x-card data-title="Logo" data-href="/ui-components/logo" data-icon="lucide:hexagon">
+    一个用于显示官方 DID Connect 徽标的简单组件，有助于品牌推广和 UI 一致性。
+  </x-card>
+</x-cards>
+
+## 组合使用示例
+
+这些组件旨在组合在一起以构建用户界面。以下是一个示例，说明如何使用 `Avatar`、`Address` 和 `ConnectButton` 创建一个简单的用户个人资料展示。
+
+```javascript Combined UI Example icon=logos:react
+import Avatar from '@arcblock/did-connect-react/lib/Avatar';
+import Address from '@arcblock/did-connect-react/lib/Address';
+import ConnectButton from '@arcblock/did-connect-react/lib/Button';
+import { Box, Typography, Paper } from '@mui/material';
+
+function UserDisplay({ userDid, userName }) {
+  if (!userDid) {
+    return <ConnectButton />;
+  }
+
+  return (
+    <Paper elevation={2} sx={{ padding: '16px', display: 'flex', alignItems: 'center', gap: '16px' }}>
+      <Avatar size={60} did={userDid} />
+      <Box>
+        <Typography variant="h6" component="div">{userName || 'Anonymous'}</Typography>
+        <Address variant="body2" color="text.secondary">{userDid}</Address>
+      </Box>
+    </Paper>
+  );
+}
+
+// 用法示例：
+// <UserDisplay userDid="z123..." userName="Alice" />
+// <UserDisplay userDid={null} />
+```
+
+此示例演示了如何使用提供的组件轻松构建适用于登录和登出状态的通用 UI 模式。
+
+### 后续步骤
+
+熟悉 UI 组件后，你可能希望探索该库的 [Hooks](./hooks.md) 以便对身份验证流程和会话数据进行更多编程控制。

package/glossary.md

@@ -0,0 +1 @@
+Federated: Means Federated Login Group, zh translation should be '统一登录站点群', don't translate to other words

package/lib/package.json.js

@@ -1,4 +1,4 @@
-const o = "3.1.40", s = {
+const o = "3.1.42", s = {
   version: o
 };
 export {