@blocklet/ui-react 3.1.48 → 3.1.49

package/docs/components-notifications.ja.md

@@ -0,0 +1,173 @@
+# 通知
+
+このセクションでは、リアルタイムのユーザー通知システムを実装するために利用可能なコンポーネントとユーティリティに関する詳細なガイドを提供します。このシステムは、専用のUIコンポーネントとトーストメッセージを通じて、ユーザーにタイムリーな更新を配信するように設計されています。
+
+通知システムの中心はWebSocket接続を中心に構築されており、サーバーがクライアントに即座に更新をプッシュできるようにします。これにより、ユーザーはアプリケーションをリフレッシュすることなく、常に重要なイベントについて知ることができます。
+
+## アーキテクチャ概要
+
+通知システムは、直接的でイベント駆動型のアーキテクチャに従います。バックエンドで注目すべきイベントが発生すると、通知が生成され、WebSocketチャネルを通じてブロードキャストされます。フロントエンドクライアントはこのチャネルをリッスンし、通知を受信して、UIを適宜更新します。
+
+```d2
+direction: down
+
+User: {
+  shape: c4-person
+}
+
+Backend: {
+  label: "Blocklet バックエンド"
+  shape: rectangle
+
+  Event-Trigger: {
+    label: "イベント発生"
+    shape: oval
+  }
+
+  Notification-Service: {
+    label: "通知サービス"
+  }
+}
+
+WebSocket-Server: {
+  label: "WebSocket サーバー"
+}
+
+Frontend: {
+  label: "フロントエンドアプリケーション"
+  shape: rectangle
+
+  WebSocket-Client: {
+    label: "WebSocket クライアント"
+  }
+
+  NotificationAddon: {
+    label: "NotificationAddon"
+  }
+
+  SnackbarProvider: {
+    label: "SnackbarProvider"
+  }
+}
+
+# Defines the flow of the notification process
+Backend.Event-Trigger -> Backend.Notification-Service: "1. 通知をトリガー"
+Backend.Notification-Service -> WebSocket-Server: "2. メッセージをプッシュ"
+WebSocket-Server -> Frontend.WebSocket-Client: "3. クライアントにブロードキャスト"
+Frontend.WebSocket-Client -> Frontend.NotificationAddon: "4. メッセージを転送"
+Frontend.NotificationAddon -> Frontend.NotificationAddon: "5a. 未読件数を更新"
+Frontend.NotificationAddon -> Frontend.SnackbarProvider: "5b. トースト通知を表示"
+Frontend.SnackbarProvider -> User: "6. ユーザーに表示"
+```
+
+## コアコンポーネント
+
+通知システムは、主に `NotificationAddon` と `NotificationSnackbar` の2つのReactコンポーネントで構成されています。
+
+### NotificationAddon
+
+`NotificationAddon` コンポーネントは、通知の主要なユーザーインターフェース要素として機能します。未読通知の数を示すバッジ付きのベルアイコンをレンダリングします。
+
+#### 機能
+
+-   **未読件数**: 未読通知の数をリアルタイムで表示します。
+-   **WebSocket統合**: 通知用のWebSocketチャネルに自動的に接続し、受信メッセージをリッスンします。
+-   **トースト通知**: 新しいコンポーネントレベルの通知に対してトーストメッセージをトリガーします。
+-   **直接ナビゲーション**: メインの通知ページへのリンクとして機能します。
+
+#### 使用方法
+
+このコンポーネントを使用するには、インポートしてアプリケーションヘッダーなどのレイアウトコンポーネント内に配置します。正しく機能するためには、通常セッションコンテキストから取得される `session` オブジェクトが必要です。
+
+```javascript "title=Example: Integrating NotificationAddon" icon=logos:javascript
+import NotificationAddon from '@arcblock/ux/lib/common/notification-addon';
+import { useSessionContext } from '@arcblock/did-connect-react';
+
+export default function AppHeader() {
+  const { session } = useSessionContext();
+
+  return (
+    <header>
+      {/* 他のヘッダーコンテンツ */}
+      <NotificationAddon session={session} />
+    </header>
+  );
+}
+```
+
+**重要**: トースト通知が機能するためには、アプリケーションが `notistack` ライブラリの `SnackbarProvider` でラップされている必要があります。
+
+```javascript "title=Example: App wrapped in SnackbarProvider" icon=logos:javascript
+import { SnackbarProvider } from 'notistack';
+import App from './App';
+
+function Root() {
+  return (
+    <SnackbarProvider maxSnack={3}>
+      <App />
+    </SnackbarProvider>
+  );
+}
+```
+
+#### Props
+
+<x-field-group>
+  <x-field data-name="session" data-type="object" data-required="true">
+    <x-field-desc markdown>ユーザーおよび通知データを含むセッションオブジェクト。コンポーネントは `session.user`、`session.unReadCount`、および `session.setUnReadCount` に依存します。</x-field-desc>
+  </x-field>
+</x-field-group>
+
+### NotificationSnackbar
+
+このコンポーネントは、トースト通知のためのリッチで標準化されたUIを提供します。`NotificationAddon` によって `notistack` の `enqueueSnackbar` 関数を介して内部的に使用され、直接使用することを意図していません。
+
+#### 機能
+
+-   **重要度に基づくスタイリング**: 通知の重要度レベル（`success`、`info`、`warning`、`error`）に基づいてスナックバーの外観が変わります。
+-   **リッチコンテンツ表示**: 単純なタイトルや説明に加えて、構造化されたアクティビティ通知（例：「ユーザーXがあなたの投稿に「いいね！」しました」）を表示できます。
+-   **インタラクティブリンク**: 説明文中の認識されたパターン（ユーザーDIDやDAppアドレスなど）を自動的にクリック可能なリンクに変換します。
+-   **クリックして開く**: スナックバーをクリックすると、ユーザーは詳細な通知ビューに移動します。
+
+## WebSocket統合
+
+リアルタイム機能は、`useListenWsClient` フックによって管理されるWebSocketクライアントによって提供されます。このフックは、ログインしているユーザーの接続を確立し、特定のイベントをリッスンします。
+
+### `useListenWsClient` フック
+
+このフックは、WebSocket接続の作成と管理の複雑さを抽象化します。現在のユーザーセッションを取得し、指定されたエンドポイントに接続されたクライアントを初期化します。
+
+```javascript "title=Hook Usage" icon=logos:javascript
+const wsClient = useListenWsClient('user');
+```
+
+### イベント
+
+`NotificationAddon` コンポーネントは、`user` チャネルで以下のイベントを購読します。
+
+| Event Name                                       | Description                                                                                                                              |
+| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `notification:blocklet:create`                   | ユーザーに対して新しい通知が作成されたときに発行されます。コンポーネントは未読件数をインクリメントし、トーストメッセージを表示する場合があります。          |
+| `notification:blocklet:read`                     | 1つ以上の通知が既読になったときに発行されます。コンポーネントは既読になった通知の数だけ未読件数をデクリメントします。 |
+
+完全なイベント名は、blockletのDIDとユーザーのDIDを使用して動的に構築されます。例：`{blocklet.did}/{user.did}/notification:blocklet:create`。
+
+## 主要なユーティリティ
+
+いくつかのユーティリティ関数が、通知データを処理およびフォーマットすることで通知システムをサポートしています。
+
+### `mergeAdjacentNotifications`
+
+この関数は、連続する類似の通知を1つの集約されたエントリにまとめます。例えば、ユーザーが異なるユーザーから複数の「いいね！」通知を連続して受け取った場合、この関数はそれらを「アリス、ボブ、他2人があなたの投稿に「いいね！」しました」のような1つの通知にまとめることができます。
+
+### `toClickableSpan`
+
+このユーティリティは、プレーンテキストをリッチでインタラクティブなコンテンツに変換することで、通知の説明を強化する役割を担います。入力文字列を解析し、ユーザーDIDやDAppアドレスなどの特殊なエンティティを識別し、それらをクリック可能なHTMLの `<a>` タグに変換します。これにより、ユーザーは通知内から直接ユーザーのプロフィールやDAppのページに移動できます。
+
+### `sanitize`
+
+`DOMPurify` のラッパーで、レンダリング前にHTMLコンテンツをクリーンアップおよびサニタイズします。これは、ユーザー生成データを含む可能性のある通知コンテンツを表示する際のクロスサイトスクリプティング（XSS）攻撃を防ぐためのセキュリティ対策です。
+
+## まとめ
+
+通知システムは、ユーザーに情報を提供するための堅牢でリアルタイムなソリューションを提供します。`NotificationAddon` コンポーネントを活用し、アプリケーションが `SnackbarProvider` で設定されていることを確認することで、フル機能の通知センターをblockletに簡単に統合できます。基礎となるWebSocketアーキテクチャにより、更新が即座に配信され、ダイナミックで応答性の高いユーザーエクスペリエンスが生まれます。

package/docs/components-notifications.md

@@ -0,0 +1,173 @@
+# Notifications
+
+This section provides a detailed guide to the components and utilities available for implementing a real-time user notification system. The system is designed to deliver timely updates to users through a dedicated UI component and toast messages.
+
+The core of the notification system is built around a WebSocket connection, enabling the server to push updates to the client instantly. This ensures that users are always informed of important events without needing to refresh the application.
+
+## Architecture Overview
+
+The notification system follows a straightforward, event-driven architecture. When a notable event occurs in the backend, a notification is generated and broadcasted through a WebSocket channel. The frontend client listens on this channel, receives the notification, and updates the UI accordingly.
+
+```d2
+direction: down
+
+User: {
+  shape: c4-person
+}
+
+Backend: {
+  label: "Blocklet Backend"
+  shape: rectangle
+
+  Event-Trigger: {
+    label: "Event Occurs"
+    shape: oval
+  }
+
+  Notification-Service: {
+    label: "Notification Service"
+  }
+}
+
+WebSocket-Server: {
+  label: "WebSocket Server"
+}
+
+Frontend: {
+  label: "Frontend Application"
+  shape: rectangle
+
+  WebSocket-Client: {
+    label: "WebSocket Client"
+  }
+
+  NotificationAddon: {
+    label: "NotificationAddon"
+  }
+
+  SnackbarProvider: {
+    label: "SnackbarProvider"
+  }
+}
+
+# Defines the flow of the notification process
+Backend.Event-Trigger -> Backend.Notification-Service: "1. Triggers notification"
+Backend.Notification-Service -> WebSocket-Server: "2. Pushes message"
+WebSocket-Server -> Frontend.WebSocket-Client: "3. Broadcasts to client"
+Frontend.WebSocket-Client -> Frontend.NotificationAddon: "4. Forwards message"
+Frontend.NotificationAddon -> Frontend.NotificationAddon: "5a. Updates unread count"
+Frontend.NotificationAddon -> Frontend.SnackbarProvider: "5b. Shows toast notification"
+Frontend.SnackbarProvider -> User: "6. Displays to user"
+```
+
+## Core Components
+
+The notification system is primarily composed of two React components: `NotificationAddon` and `NotificationSnackbar`.
+
+### NotificationAddon
+
+The `NotificationAddon` component serves as the main user interface element for notifications. It renders a bell icon that displays a badge indicating the number of unread notifications.
+
+#### Features
+
+-   **Unread Count**: Displays a real-time count of unread notifications.
+-   **WebSocket Integration**: Automatically connects to the notification WebSocket channel and listens for incoming messages.
+-   **Toast Notifications**: Triggers toast messages for new component-level notifications.
+-   **Direct Navigation**: Functions as a link to the main notifications page.
+
+#### Usage
+
+To use this component, import it and place it within a layout component, such as an application header. It requires a `session` object, typically obtained from a session context, to function correctly.
+
+```javascript "title=Example: Integrating NotificationAddon" icon=logos:javascript
+import NotificationAddon from '@arcblock/ux/lib/common/notification-addon';
+import { useSessionContext } from '@arcblock/did-connect-react';
+
+export default function AppHeader() {
+  const { session } = useSessionContext();
+
+  return (
+    <header>
+      {/* Other header content */}
+      <NotificationAddon session={session} />
+    </header>
+  );
+}
+```
+
+**Important**: For the toast notifications to work, your application must be wrapped in a `SnackbarProvider` from the `notistack` library.
+
+```javascript "title=Example: App wrapped in SnackbarProvider" icon=logos:javascript
+import { SnackbarProvider } from 'notistack';
+import App from './App';
+
+function Root() {
+  return (
+    <SnackbarProvider maxSnack={3}>
+      <App />
+    </SnackbarProvider>
+  );
+}
+```
+
+#### Props
+
+<x-field-group>
+  <x-field data-name="session" data-type="object" data-required="true">
+    <x-field-desc markdown>The session object containing user and notification data. The component relies on `session.user`, `session.unReadCount`, and `session.setUnReadCount`.</x-field-desc>
+  </x-field>
+</x-field-group>
+
+### NotificationSnackbar
+
+This component provides a rich, standardized UI for toast notifications. It is used internally by `NotificationAddon` via `notistack`'s `enqueueSnackbar` function and is not intended for direct use.
+
+#### Features
+
+-   **Severity-Based Styling**: The appearance of the snackbar changes based on the notification's severity level (`success`, `info`, `warning`, `error`).
+-   **Rich Content Display**: Capable of displaying structured activity notifications (e.g., "User X liked your post") in addition to simple titles and descriptions.
+-   **Interactive Links**: Automatically converts recognized patterns in the description (like user DIDs or DApp addresses) into clickable links.
+-   **Click-to-Open**: Clicking the snackbar navigates the user to the detailed notification view.
+
+## WebSocket Integration
+
+Real-time functionality is powered by a WebSocket client managed by the `useListenWsClient` hook. This hook establishes a connection for the logged-in user and listens for specific events.
+
+### `useListenWsClient` Hook
+
+This hook abstracts the complexity of creating and managing the WebSocket connection. It retrieves the current user session and initializes a client connected to a specified endpoint.
+
+```javascript "title=Hook Usage" icon=logos:javascript
+const wsClient = useListenWsClient('user');
+```
+
+### Events
+
+The `NotificationAddon` component subscribes to the following events on the `user` channel:
+
+| Event Name                                       | Description                                                                                                                              |
+| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `notification:blocklet:create`                   | Fired when a new notification is created for the user. The component increments the unread count and may display a toast message.          |
+| `notification:blocklet:read`                     | Fired when one or more notifications have been read. The component decrements the unread count by the number of notifications that were read. |
+
+The full event name is dynamically constructed using the blocklet's DID and the user's DID, for example: `{blocklet.did}/{user.did}/notification:blocklet:create`.
+
+## Key Utilities
+
+Several utility functions support the notification system by processing and formatting notification data.
+
+### `mergeAdjacentNotifications`
+
+This function groups consecutive, similar notifications into a single, aggregated entry. For example, if a user receives multiple "like" notifications in a row from different users, this function can merge them into a single notification like "Alice, Bob, and 2 others liked your post."
+
+### `toClickableSpan`
+
+This utility is responsible for enhancing notification descriptions by converting plain text into rich, interactive content. It parses the input string, identifies special entities like user DIDs or DApp addresses, and transforms them into clickable HTML `<a>` tags. This allows users to navigate directly to a user's profile or a DApp's page from within a notification.
+
+### `sanitize`
+
+A wrapper around `DOMPurify` that cleans and sanitizes HTML content before it is rendered. This is a security measure to prevent cross-site scripting (XSS) attacks when displaying notification content that may contain user-generated data.
+
+## Summary
+
+The notification system provides a robust and real-time solution for keeping users informed. By leveraging the `NotificationAddon` component and ensuring your application is configured with the `SnackbarProvider`, you can easily integrate a full-featured notification center into your blocklet. The underlying WebSocket architecture ensures that updates are delivered instantly, creating a dynamic and responsive user experience.

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

@@ -0,0 +1,174 @@
+# 通知
+
+本節詳細介紹了可用於實作即時使用者通知系統的元件和工具。該系統旨在透過專用的 UI 元件和快顯訊息，向使用者及時傳遞更新。
+
+通知系統的核心圍繞 WebSocket 連線建構，使伺服器能夠即時向用戶端推送更新。這確保了使用者無需刷新應用程式即可隨時了解重要事件。
+
+## 架構概覽
+
+通知系統遵循一個直接的、事件驅動的架構。當後端發生值得注意的事件時，會產生一則通知並透過 WebSocket 通道廣播。前端用戶端會監聽此通道，接收通知，並相應地更新 UI。
+
+```d2
+direction: down
+
+User: {
+  label: "使用者"
+  shape: c4-person
+}
+
+Backend: {
+  label: "Blocklet 後端"
+  shape: rectangle
+
+  Event-Trigger: {
+    label: "事件發生"
+    shape: oval
+  }
+
+  Notification-Service: {
+    label: "通知服務"
+  }
+}
+
+WebSocket-Server: {
+  label: "WebSocket 伺服器"
+}
+
+Frontend: {
+  label: "前端應用程式"
+  shape: rectangle
+
+  WebSocket-Client: {
+    label: "WebSocket 客戶端"
+  }
+
+  NotificationAddon: {
+    label: "NotificationAddon"
+  }
+
+  SnackbarProvider: {
+    label: "SnackbarProvider"
+  }
+}
+
+# 定義通知流程
+Backend.Event-Trigger -> Backend.Notification-Service: "1. 觸發通知"
+Backend.Notification-Service -> WebSocket-Server: "2. 推送訊息"
+WebSocket-Server -> Frontend.WebSocket-Client: "3. 廣播至客戶端"
+Frontend.WebSocket-Client -> Frontend.NotificationAddon: "4. 轉發訊息"
+Frontend.NotificationAddon -> Frontend.NotificationAddon: "5a. 更新未讀計數"
+Frontend.NotificationAddon -> Frontend.SnackbarProvider: "5b. 顯示快顯通知"
+Frontend.SnackbarProvider -> User: "6. 向使用者顯示"
+```
+
+## 核心元件
+
+通知系統主要由兩個 React 元件組成：`NotificationAddon` 和 `NotificationSnackbar`。
+
+### NotificationAddon
+
+`NotificationAddon` 元件是通知的主要使用者介面元素。它會渲染一個鈴鐺圖示，並帶有一個徽章，顯示未讀通知的數量。
+
+#### 功能
+
+-   **未讀計數**：即時顯示未讀通知的數量。
+-   **WebSocket 整合**：自動連線到通知 WebSocket 通道並監聽傳入的訊息。
+-   **快顯通知**：針對新的元件級別通知觸發快顯訊息。
+-   **直接導覽**：作為連結，可導向主通知頁面。
+
+#### 用法
+
+若要使用此元件，請將其匯入並放置在佈局元件中，例如應用程式的標頭。它需要一個 `session` 物件才能正常運作，該物件通常從 session context 中獲取。
+
+```javascript "title=範例：整合 NotificationAddon" icon=logos:javascript
+import NotificationAddon from '@arcblock/ux/lib/common/notification-addon';
+import { useSessionContext } from '@arcblock/did-connect-react';
+
+export default function AppHeader() {
+  const { session } = useSessionContext();
+
+  return (
+    <header>
+      {/* 其他標頭內容 */}
+      <NotificationAddon session={session} />
+    </header>
+  );
+}
+```
+
+**重要**：為了讓快顯通知正常運作，您的應用程式必須被 `notistack` 函式庫的 `SnackbarProvider` 包裹。
+
+```javascript "title=範例：被 SnackbarProvider 包裹的 App" icon=logos:javascript
+import { SnackbarProvider } from 'notistack';
+import App from './App';
+
+function Root() {
+  return (
+    <SnackbarProvider maxSnack={3}>
+      <App />
+    </SnackbarProvider>
+  );
+}
+```
+
+#### Props
+
+<x-field-group>
+  <x-field data-name="session" data-type="object" data-required="true">
+    <x-field-desc markdown>包含使用者和通知資料的 session 物件。該元件依賴 `session.user`、`session.unReadCount` 和 `session.setUnReadCount`。</x-field-desc>
+  </x-field>
+</x-field-group>
+
+### NotificationSnackbar
+
+此元件為快顯通知提供了一個豐富且標準化的 UI。它由 `NotificationAddon` 透過 `notistack` 的 `enqueueSnackbar` 函式在內部使用，不適合直接使用。
+
+#### 功能
+
+-   **基於嚴重性等級的樣式**：快顯通知的外觀會根據通知的嚴重性等級（`success`、`info`、`warning`、`error`）而改變。
+-   **豐富的內容顯示**：除了簡單的標題和描述外，還能顯示結構化的活動通知（例如，「使用者 X 喜歡了您的貼文」）。
+-   **互動式連結**：自動將描述中可識別的模式（如使用者 DID 或 DApp 地址）轉換為可點擊的連結。
+-   **點擊開啟**：點擊快顯通知可將使用者導覽至詳細的通知檢視。
+
+## WebSocket 整合
+
+即時功能由 `useListenWsClient` hook 管理的 WebSocket 用戶端提供支援。此 hook 為登入的使用者建立連線，並監聽特定事件。
+
+### `useListenWsClient` Hook
+
+此 hook 抽象化了建立和管理 WebSocket 連線的複雜性。它會獲取目前的使用者 session，並初始化一個連線到指定端點的用戶端。
+
+```javascript "title=Hook 用法" icon=logos:javascript
+const wsClient = useListenWsClient('user');
+```
+
+### 事件
+
+`NotificationAddon` 元件在 `user` 通道上訂閱以下事件：
+
+| Event Name | Description |
+| --- | --- |
+| `notification:blocklet:create` | 當為使用者建立新通知時觸發。該元件會增加未讀計數，並可能顯示一則快顯訊息。 |
+| `notification:blocklet:read` | 當一則或多則通知被讀取時觸發。該元件會將未讀計數減去已讀通知的數量。 |
+
+完整的事件名稱是使用 blocklet 的 DID 和使用者的 DID 動態建構的，例如：`{blocklet.did}/{user.did}/notification:blocklet:create`。
+
+## 關鍵工具
+
+幾個工具函式透過處理和格式化通知資料來支援通知系統。
+
+### `mergeAdjacentNotifications`
+
+此函式將連續的、相似的通知分組為一個單一的、聚合的條目。例如，如果一位使用者連續收到來自不同使用者的多個「喜歡」通知，此函式可以將它們合併為一則通知，如「Alice、Bob 和另外 2 人喜歡了您的貼文」。
+
+### `toClickableSpan`
+
+此工具負責透過將純文字轉換為豐富的互動式內容來增強通知描述。它會解析輸入的字串，識別如使用者 DID 或 DApp 地址等特殊實體，並將它們轉換為可點擊的 HTML `<a>` 標籤。這允許使用者從通知內部直接導覽至使用者的個人資料頁面或 DApp 的頁面。
+
+### `sanitize`
+
+一個圍繞 `DOMPurify` 的封裝函式，用於在渲染 HTML 內容之前對其進行清理和消毒。這是一項安全措施，旨在防止在顯示可能包含使用者生成資料的通知內容時發生跨站腳本（XSS）攻擊。
+
+## 總結
+
+通知系統為保持使用者資訊同步提供了一個強大且即時的解決方案。透過利用 `NotificationAddon` 元件並確保您的應用程式已配置 `SnackbarProvider`，您可以輕鬆地將一個功能齊全的通知中心整合到您的 blocklet 中。底層的 WebSocket 架構確保了更新的即時傳遞，創造出一個動態且反應迅速的使用者體驗。