@blocklet/ui-react 3.1.47 → 3.1.49

package/docs/components-layout-header.ja.md

@@ -0,0 +1,233 @@
+# Header
+
+`Header` コンポーネントは、Blocklet アプリケーション向けにレスポンシブでカスタマイズ可能なヘッダーを提供します。Blocklet の設定 (`blocklet.yml`) から直接メタデータを読み取ることで、ナビゲーションリンク、アプリケーションのロゴ、およびユーザーセッションコントロールを自動的に設定します。このコンポーネントは、最小限の設定で一貫性のある機能豊富なヘッダーを作成するように設計されています。
+
+## 概要
+
+`Header` コンポーネントは、主要なナビゲーションおよびブランディング要素として機能します。これは `@arcblock/ux` のコンポーネント、`ResponsiveHeader` および `NavMenu` の上に構築されており、ユーザー認証のために DID Connect セッションコンテキストとシームレスに統合されます。
+
+主な機能は次のとおりです。
+- **自動設定**: `blocklet.yml` からアプリのロゴ、タイトル、ナビゲーションリンクを設定します。
+- **レスポンシブデザイン**: さまざまな画面サイズに自動的に適応し、モバイルフレンドリーなナビゲーションメニューを提供します。
+- **セッション管理**: DID Connect と統合し、ユーザー情報、プロフィールメニュー、ログイン/ログアウトボタンを表示します。
+- **カスタマイズ可能なアドオン**: カスタムコンポーネントの挿入や、テーマ切り替え、ロケールセレクターなどのデフォルト要素の変更を可能にします。
+- **組織切り替え**: Blocklet が組織サポートを有効にしている場合、自動的に組織スイッチャーを含みます。
+- **ドメイン警告**: より良いセキュリティのためにカスタムドメインの設定を推奨するため、管理者が一時的なドメイン経由でアプリケーションにアクセスした場合に通知します。
+
+### 仕組み
+
+以下の図は、`Header` のデータフローとコンポーネント構成を示しています。`blocklet.yml` ファイルから設定を読み込み、それを処理して、ロゴ、ナビゲーションリンク、ユーザーセッションコントロールなど、適切な UI 要素をレンダリングします。
+
+```d2
+direction: down
+
+blocklet-yml: {
+  label: "blocklet.yml"
+  shape: rectangle
+}
+
+Header-Component: {
+  label: "Header コンポーネント"
+  shape: rectangle
+
+  Blocklet-Metadata-Parser: {
+    label: "メタデータパーサー"
+  }
+
+  UI-Renderer: {
+    label: "UI レンダラー"
+    shape: rectangle
+
+    Logo
+    Navigation-Menu: {
+      label: "ナビゲーションメニュー"
+    }
+    Header-Addons: {
+      label: "ヘッダーアドオン"
+      shape: rectangle
+      grid-columns: 2
+      Session-Manager: {
+        label: "セッションマネージャー"
+      }
+      Locale-Selector: {
+        label: "ロケールセレクター"
+      }
+      Theme-Toggle: {
+        label: "テーマ切り替え"
+      }
+      Custom-Addons: {
+        label: "カスタムアドオン"
+      }
+    }
+  }
+
+  Blocklet-Metadata-Parser -> UI-Renderer: "データを提供"
+}
+
+blocklet-yml -> Header-Component.Blocklet-Metadata-Parser: "設定を読み込む"
+
+Header-Component.UI-Renderer.Logo
+Header-Component.UI-Renderer.Navigation-Menu
+Header-Component.UI-Renderer.Header-Addons
+
+```
+
+## 基本的な使用法
+
+`Header` を使用するには、インポートしてアプリケーションのレイアウトに配置します。Blocklet のメタデータが必要で、これは通常 `window.blocklet` を介してグローバルに利用可能です。
+
+```javascript "App.js" icon=logos:javascript
+import Header from '@blocklet/ui-react/lib/Header';
+
+function App() {
+  // meta オブジェクトは通常 window.blocklet から取得されます
+  const blockletMeta = window.blocklet || {};
+
+  return (
+    <div>
+      <Header meta={blockletMeta} />
+      <main>
+        {/* アプリケーションのコンテンツ */}
+      </main>
+    </div>
+  );
+}
+
+export default App;
+```
+
+## プロパティ
+
+`Header` コンポーネントは、カスタマイズのためにいくつかのプロパティを受け入れます。
+
+<x-field-group>
+  <x-field data-name="meta" data-type="BlockletMetaProps" data-required="false">
+    <x-field-desc markdown>Blocklet のメタデータオブジェクト、通常は `window.blocklet` から取得します。これには、コンポーネントがレンダリングに使用する `name`、`logo`、`navigation` などの情報が含まれています。</x-field-desc>
+  </x-field>
+  <x-field data-name="addons" data-type="Function | React.ReactNode" data-required="false">
+    <x-field-desc markdown>ヘッダーの右側に追加されるカスタム要素。関数が提供された場合、組み込みのアドオンを引数として受け取り、それらを変更、並べ替え、または補足できます。ノードが提供された場合、すべての組み込みアドオンを置き換えます。</x-field-desc>
+  </x-field>
+  <x-field data-name="sessionManagerProps" data-type="SessionManagerProps" data-required="false" data-default='{ "showRole": true }'>
+    <x-field-desc markdown>基盤となる `SessionUser` コンポーネントに直接渡されるプロパティで、ユーザーのロールの表示など、ユーザーセッション情報の表示を制御します。</x-field-desc>
+  </x-field>
+  <x-field data-name="homeLink" data-type="string | Function" data-required="false" data-default="publicPath">
+    <x-field-desc markdown>ホームリンクの URL で、通常はロゴまたはブランド名をクリックするとトリガーされます。デフォルトは Blocklet の公開パス (`/`) です。JSX 要素を返す関数にすることもできます。</x-field-desc>
+  </x-field>
+  <x-field data-name="theme" data-type="object" data-required="false">
+    <x-field-desc markdown>デフォルトのテーマとマージするための Material-UI のテーマオブジェクトで、色、タイポグラフィ、その他のスタイルを詳細にカスタマイズできます。</x-field-desc>
+  </x-field>
+  <x-field data-name="hideNavMenu" data-type="boolean" data-required="false" data-default="false">
+    <x-field-desc markdown>`true` の場合、`blocklet.yml` から生成されたナビゲーションメニューは、ナビゲーションデータが存在しても非表示になります。</x-field-desc>
+  </x-field>
+  <x-field data-name="bordered" data-type="boolean" data-required="false" data-default="false">
+    <x-field-desc markdown>`true` の場合、視覚的な区分のためにヘッダーに下枠が適用されます。</x-field-desc>
+  </x-field>
+  <x-field data-name="logo" data-type="React.ReactNode" data-required="false">
+    <x-field-desc markdown>Blocklet のメタデータから取得したロゴを上書きするためのカスタムロゴ要素。</x-field-desc>
+  </x-field>
+  <x-field data-name="brand" data-type="React.ReactNode" data-required="false">
+    <x-field-desc markdown>ロゴの隣に表示するカスタムブランド要素 (例: テキストや画像)。</x-field-desc>
+  </x-field>
+  <x-field data-name="showDomainWarningDialog" data-type="boolean" data-required="false" data-default="true">
+    <x-field-desc markdown>`false` の場合、一時的なドメインに関する警告ダイアログは表示されません。</x-field-desc>
+  </x-field>
+</x-field-group>
+
+## 機能
+
+### メタデータからの自動ナビゲーション
+
+`Header` は、`blocklet.yml` ファイルの `navigation` 配列からナビゲーションメニューを自動的に生成します。コンポーネントはこの設定を解析して、プライマリナビゲーションリンクとネストされたドロップダウンメニューを作成します。
+
+以下は、`blocklet.yml` 内の `navigation` 設定の例です。
+
+```yaml "blocklet.yml" icon=mdi:code-braces
+navigation:
+  - title: Features
+    link: /features
+    icon: 'mdi:star'
+  - title: Docs
+    link: /docs
+    icon: 'mdi:book-open'
+  - title: More
+    items:
+      - title: About Us
+        link: /about
+        description: Learn more about our mission.
+      - title: Community
+        link: https://community.example.com
+        description: Join our community forum.
+```
+
+`parseNavigation` ユーティリティはこの構造を処理し、`title` と `description` のローカライゼーションを処理し、現在の URL パスに基づいてアクティブなリンクを決定します。
+
+### セッション管理とアドオン
+
+ヘッダーの右側には「アドオン」が含まれています。これらはセッション管理とアプリケーション設定のためのコントロールのコレクションです。デフォルトでは、これらには以下が含まれます。
+
+- **組織スイッチャー**: Blocklet が組織サポートを有効にしている場合に表示されます。
+- **通知センター**: Blocklet が通知ページを含んでいる場合に表示されます。
+- **ロケールセレクター**: 複数の言語が設定されている場合に表示されます。
+- **テーマモード切り替え**: ライトモードとダークモードを切り替えます。
+- **セッションコントロール**: ログインしているユーザーのアバターと、プロフィール、設定、ログアウトへのリンクを持つメニューを表示します。ゲストには、「ウォレットに接続」ボタンが表示されます。
+
+#### アドオンのカスタマイズ
+
+`addons` プロパティを使用してこれらのアドオンをカスタマイズできます。
+
+**例: カスタムボタンの追加**
+
+`addons` プロパティに関数を指定します。この関数はデフォルトのアドオン要素の配列を受け取り、独自のアドオンを追加できます。
+
+```javascript "HeaderWithCustomAddon.js" icon=logos:javascript
+import Header from '@blocklet/ui-react/lib/Header';
+import Button from '@mui/material/Button';
+
+function HeaderWithCustomAddon() {
+  return (
+    <Header
+      meta={window.blocklet}
+      addons={(builtInAddons) => (
+        <>
+          {builtInAddons}
+          <Button variant="contained" color="primary" sx={{ ml: 1 }}>
+            Upgrade
+          </Button>
+        </>
+      )}
+    />
+  );
+}
+```
+
+**例: すべてのアドオンの置き換え**
+
+React ノードまたはノードの配列を提供して、デフォルトのアドオンを完全に置き換えます。
+
+```javascript "HeaderWithReplacedAddons.js" icon=logos:javascript
+import Header from '@blocklet/ui-react/lib/Header';
+import Button from '@mui/material/Button';
+
+function HeaderWithReplacedAddons() {
+  return (
+    <Header
+      meta={window.blocklet}
+      addons={[
+        <Button key="feedback" variant="outlined" sx={{ ml: 1 }}>
+          Feedback
+        </Button>,
+      ]}
+    />
+  );
+}
+```
+
+### 埋め込みモードでの非表示
+
+`Header` は `withHideWhenEmbed` 高階コンポーネントでラップされています。アプリケーションが埋め込みコンテキストでレンダリングされる場合 (例: `sessionStorage` に `EMBED_MODE_KEY: 1` が含まれる iframe 内)、自動的に非表示になります。これは、Blocklet が別のアプリケーションに統合された際に、よりクリーンな UI を提供するのに役立ちます。
+
+## まとめ
+
+`Header` コンポーネントは、Blocklet アプリケーション全体で一貫したブランディングとナビゲーションを確立するための強力なツールです。Blocklet のメタデータを活用することで、開発を簡素化し、プロパティを通じて広範なカスタマイズを提供します。
+
+関連するレイアウトコンポーネントについては、[Footer](./components-layout-footer.md) のドキュメントを参照してください。

package/docs/components-layout-header.md

@@ -0,0 +1,233 @@
+# Header
+
+The `Header` component provides a responsive and customizable header for a Blocklet application. It automatically populates navigation links, the application logo, and user session controls by reading metadata directly from the blocklet's configuration (`blocklet.yml`). This component is designed to create a consistent and feature-rich header with minimal configuration.
+
+## Overview
+
+The `Header` component serves as a primary navigation and branding element. It is built on top of `@arcblock/ux` components, including `ResponsiveHeader` and `NavMenu`, and integrates seamlessly with the DID Connect session context for user authentication.
+
+Key features include:
+- **Automatic Configuration**: Populates the app logo, title, and navigation links from `blocklet.yml`.
+- **Responsive Design**: Adapts automatically to different screen sizes, providing a mobile-friendly navigation menu.
+- **Session Management**: Integrates with DID Connect to display user information, profile menus, and login/logout buttons.
+- **Customizable Addons**: Allows for the injection of custom components or modification of default elements like the theme toggle and locale selector.
+- **Organization Switching**: Automatically includes an organization switcher if the blocklet has organization support enabled.
+- **Domain Warnings**: Notifies administrators and users when accessing the application via a temporary domain to encourage custom domain configuration for better security.
+
+### How It Works
+
+The diagram below illustrates the data flow and component composition of the `Header`. It reads configuration from the `blocklet.yml` file, processes it, and renders the appropriate UI elements, including the logo, navigation links, and user session controls.
+
+```d2
+direction: down
+
+blocklet-yml: {
+  label: "blocklet.yml"
+  shape: rectangle
+}
+
+Header-Component: {
+  label: "Header Component"
+  shape: rectangle
+
+  Blocklet-Metadata-Parser: {
+    label: "Metadata Parser"
+  }
+
+  UI-Renderer: {
+    label: "UI Renderer"
+    shape: rectangle
+
+    Logo
+    Navigation-Menu: {
+      label: "Navigation Menu"
+    }
+    Header-Addons: {
+      label: "Header Addons"
+      shape: rectangle
+      grid-columns: 2
+      Session-Manager: {
+        label: "Session Manager"
+      }
+      Locale-Selector: {
+        label: "Locale Selector"
+      }
+      Theme-Toggle: {
+        label: "Theme Toggle"
+      }
+      Custom-Addons: {
+        label: "Custom Addons"
+      }
+    }
+  }
+
+  Blocklet-Metadata-Parser -> UI-Renderer: "Provides data"
+}
+
+blocklet-yml -> Header-Component.Blocklet-Metadata-Parser: "Reads config"
+
+Header-Component.UI-Renderer.Logo
+Header-Component.UI-Renderer.Navigation-Menu
+Header-Component.UI-Renderer.Header-Addons
+
+```
+
+## Basic Usage
+
+To use the `Header`, import it and place it in your application's layout. It requires the blocklet's metadata, which is typically available globally via `window.blocklet`.
+
+```javascript "App.js" icon=logos:javascript
+import Header from '@blocklet/ui-react/lib/Header';
+
+function App() {
+  // The meta object is usually sourced from window.blocklet
+  const blockletMeta = window.blocklet || {};
+
+  return (
+    <div>
+      <Header meta={blockletMeta} />
+      <main>
+        {/* Your application content */}
+      </main>
+    </div>
+  );
+}
+
+export default App;
+```
+
+## Props
+
+The `Header` component accepts several props for customization.
+
+<x-field-group>
+  <x-field data-name="meta" data-type="BlockletMetaProps" data-required="false">
+    <x-field-desc markdown>The blocklet's metadata object, typically from `window.blocklet`. It contains information like `name`, `logo`, and `navigation` that the component uses for rendering.</x-field-desc>
+  </x-field>
+  <x-field data-name="addons" data-type="Function | React.ReactNode" data-required="false">
+    <x-field-desc markdown>Custom elements to be added to the right side of the header. If a function is provided, it receives the built-in addons as an argument, allowing you to modify, reorder, or supplement them. If a node is provided, it replaces all built-in addons.</x-field-desc>
+  </x-field>
+  <x-field data-name="sessionManagerProps" data-type="SessionManagerProps" data-required="false" data-default='{ "showRole": true }'>
+    <x-field-desc markdown>Props passed directly to the underlying `SessionUser` component to control the display of user session information, such as showing the user's role.</x-field-desc>
+  </x-field>
+  <x-field data-name="homeLink" data-type="string | Function" data-required="false" data-default="publicPath">
+    <x-field-desc markdown>The URL for the home link, which is typically triggered by clicking the logo or brand name. It defaults to the blocklet's public path (`/`). Can also be a function that returns a JSX element.</x-field-desc>
+  </x-field>
+  <x-field data-name="theme" data-type="object" data-required="false">
+    <x-field-desc markdown>A Material-UI theme object to merge with the default theme, allowing for deep customization of colors, typography, and other styles.</x-field-desc>
+  </x-field>
+  <x-field data-name="hideNavMenu" data-type="boolean" data-required="false" data-default="false">
+    <x-field-desc markdown>If `true`, the navigation menu generated from `blocklet.yml` will be hidden, even if navigation data exists.</x-field-desc>
+  </x-field>
+  <x-field data-name="bordered" data-type="boolean" data-required="false" data-default="false">
+    <x-field-desc markdown>If `true`, a bottom border will be applied to the header for visual separation.</x-field-desc>
+  </x-field>
+  <x-field data-name="logo" data-type="React.ReactNode" data-required="false">
+    <x-field-desc markdown>A custom logo element to override the one from the blocklet metadata.</x-field-desc>
+  </x-field>
+  <x-field data-name="brand" data-type="React.ReactNode" data-required="false">
+    <x-field-desc markdown>A custom brand element (e.g., text or an image) to display next to the logo.</x-field-desc>
+  </x-field>
+  <x-field data-name="showDomainWarningDialog" data-type="boolean" data-required="false" data-default="true">
+    <x-field-desc markdown>If `false`, the dialog warning about temporary domains will not be shown.</x-field-desc>
+  </x-field>
+</x-field-group>
+
+## Features
+
+### Automatic Navigation from Metadata
+
+The `Header` automatically generates its navigation menu from the `navigation` array in your `blocklet.yml` file. The component parses this configuration to create primary navigation links and nested dropdown menus.
+
+Here is an example of a `navigation` configuration in `blocklet.yml`:
+
+```yaml "blocklet.yml" icon=mdi:code-braces
+navigation:
+  - title: Features
+    link: /features
+    icon: 'mdi:star'
+  - title: Docs
+    link: /docs
+    icon: 'mdi:book-open'
+  - title: More
+    items:
+      - title: About Us
+        link: /about
+        description: Learn more about our mission.
+      - title: Community
+        link: https://community.example.com
+        description: Join our community forum.
+```
+
+The `parseNavigation` utility processes this structure, handles localization for `title` and `description`, and determines the active link based on the current URL path.
+
+### Session Management and Addons
+
+The right side of the header contains "addons," which are a collection of controls for session management and application settings. By default, these include:
+
+- **Organization Switcher**: Appears if the blocklet has organization support enabled.
+- **Notification Center**: Appears if the blocklet includes a notifications page.
+- **Locale Selector**: Appears if multiple languages are configured.
+- **Theme Mode Toggle**: Switches between light and dark modes.
+- **Session Controls**: Displays the logged-in user's avatar and a menu with links for profile, settings, and logout. For guests, it shows a "Connect Wallet" button.
+
+#### Customizing Addons
+
+You can customize these addons using the `addons` prop.
+
+**Example: Appending a custom button**
+
+Provide a function to the `addons` prop. This function receives an array of the default addon elements, allowing you to add your own.
+
+```javascript "HeaderWithCustomAddon.js" icon=logos:javascript
+import Header from '@blocklet/ui-react/lib/Header';
+import Button from '@mui/material/Button';
+
+function HeaderWithCustomAddon() {
+  return (
+    <Header
+      meta={window.blocklet}
+      addons={(builtInAddons) => (
+        <>
+          {builtInAddons}
+          <Button variant="contained" color="primary" sx={{ ml: 1 }}>
+            Upgrade
+          </Button>
+        </>
+      )}
+    />
+  );
+}
+```
+
+**Example: Replacing all addons**
+
+Provide a React node or an array of nodes to replace the default addons entirely.
+
+```javascript "HeaderWithReplacedAddons.js" icon=logos:javascript
+import Header from '@blocklet/ui-react/lib/Header';
+import Button from '@mui/material/Button';
+
+function HeaderWithReplacedAddons() {
+  return (
+    <Header
+      meta={window.blocklet}
+      addons={[
+        <Button key="feedback" variant="outlined" sx={{ ml: 1 }}>
+          Feedback
+        </Button>,
+      ]}
+    />
+  );
+}
+```
+
+### Hiding in Embedded Mode
+
+The `Header` is wrapped with the `withHideWhenEmbed` higher-order component. It will automatically be hidden when the application is rendered in an embedded context (e.g., within an iframe where `sessionStorage` contains `EMBED_MODE_KEY: 1`). This is useful for providing a cleaner UI when your blocklet is integrated into another application.
+
+## Summary
+
+The `Header` component is a powerful tool for establishing consistent branding and navigation across a Blocklet application. By leveraging blocklet metadata, it simplifies development while offering extensive customization through props.
+
+For related layout components, please see the documentation for the [Footer](./components-layout-footer.md).