@blocklet/ui-react/docs/core-concepts.ja.md

Some useful front-end web components that can be used in Blocklets.

# コアコンセプト

このドキュメントでは、Blocklet UI React ライブラリの基本原則について説明します。中心的な設計思想は**メタデータ駆動アプローチ**であり、`Header`、`Footer`、`Dashboard` などの UI コンポーネントは、blocklet のメタデータに基づいて自動的に設定・レンダリングされます。この戦略により、一貫性が確保され、定型的なコードが削減され、ユーザーの役割や言語設定に適応する動的な UI が可能になります。

中心的な考え方は、単一の設定ファイル（通常は `blocklet.yml`）が、アプリケーションの全体的な構造と外観に関する信頼できる唯一の情報源として機能するということです。ライブラリはこのメタデータを読み取り、処理し、それを使用して適切な UI 要素を構築します。

## メタデータ駆動の原則

ライブラリの動作は、単純なデータフローとして視覚化できます。blocklet のメタデータがライブラリへの入力として提供され、ライブラリはそれをパイプラインを通じて処理し、完全にレンダリングされた UI コンポーネントを生成します。これにより、開発者がアプリケーションごとに共通のレイアウト要素を手動で構築・設定する必要がなくなります。

<!-- DIAGRAM_IMAGE_START:flowchart:16:9:1765962229 -->
![Core Concepts](assets/diagram/core-concepts-diagram-0.ja.jpg)
<!-- DIAGRAM_IMAGE_END -->

この自動化されたプロセスは、明確に定義されたメタデータ構造に依存しており、それについては次のセクションで詳しく説明します。

## Blocklet メタデータの構造

ライブラリは、UI のレンダリングに必要なすべての情報を含む `BlockletMetaProps` と呼ばれる特定のオブジェクト構造を想定しています。以下に、この構造の詳細な内訳を示します。

<x-field-group>
  <x-field data-name="appName" data-type="string" data-required="false" data-desc="アプリケーション名。通常は Header に表示されます。"></x-field>
  <x-field data-name="appLogo" data-type="React.ReactNode" data-required="false" data-desc="アプリケーションのロゴ用の React ノード。これも Header に表示されます。"></x-field>
  <x-field data-name="enableConnect" data-type="boolean" data-required="false" data-desc="DID Connect ボタンを表示するかどうかを決定します。"></x-field>
  <x-field data-name="enableLocale" data-type="boolean" data-required="false" data-desc="言語選択コンポーネントを表示するかどうかを決定します。"></x-field>
  <x-field data-name="theme" data-type="object" data-required="false">
    <x-field-desc markdown>アプリケーションレイアウトのカラースキームを定義します。</x-field-desc>
    <x-field data-name="background" data-type="string" data-required="false" data-desc="Header や Footer などのレイアウトコンポーネントの背景色を設定します。"></x-field>
  </x-field>
  <x-field data-name="navigation" data-type="array" data-required="false">
    <x-field-desc markdown>アプリケーション全体のリンクとメニューを定義するナビゲーション項目オブジェクトの配列です。</x-field-desc>
    <x-field data-name="title" data-type="string | object" data-required="true" data-desc="ナビゲーション項目の表示テキスト。i18n のためにオブジェクトにすることも可能です。"></x-field>
    <x-field data-name="link" data-type="string | object" data-required="false" data-desc="ナビゲーション項目の URL。i18n のためにオブジェクトにすることも可能です。"></x-field>
    <x-field data-name="icon" data-type="string" data-required="false" data-desc="タイトルの横に表示するアイコン用の Iconify 互換文字列です。"></x-field>
    <x-field data-name="section" data-type="string | array" data-required="false" data-desc="項目が表示される場所を指定します。例：'header'、'footer'、'dashboard'。"></x-field>
    <x-field data-name="role" data-type="string | array" data-required="false" data-desc="この項目を閲覧できるユーザーロールを定義します。例：'admin'、'guest'。"></x-field>
    <x-field data-name="items" data-type="array" data-required="false" data-desc="ドロップダウンメニューやサブメニューを作成するための、ネストされたナビゲーション項目の配列です。"></x-field>
  </x-field>
</x-field-group>

### ナビゲーション設定の例

`navigation` 配列は、メタデータの最も重要な部分です。すべてのリンク、メニュー、およびその配置を構造化された方法で定義する手段を提供します。

```yaml blocklet.yml でのナビゲーション設定 icon=mdi:code-braces
# blocklet.yml
navigation:
  - title: 機能
    link: /features
  - title:
      en: About Us
      ja: 私たちについて
    link:
      en: /about
      ja: /about-us
    section: footer
  - title: 管理ダッシュボード
    link: /admin
    section: dashboard
    role: admin
  - title: ソーシャル
    section: social
    items:
      - title: Twitter
        link: https://twitter.com/arcblock
        icon: mdi:twitter
      - title: GitHub
        link: https://github.com/arcblock
        icon: mdi:github
```

この例は、いくつかの主要な機能を示しています：
- シンプルなヘッダーリンク（「機能」）。
- 多言語対応のフッターリンク（「私たちについて」）。
- ダッシュボード用の管理者専用リンク。
- フッター向けのソーシャルメディアリンクのグループ。

## データ処理パイプライン

レンダリングの前に、ライブラリは生のメタデータを一連のステップで処理し、UI コンポーネント用に準備します。

### 1. パースとセクション分割

最初のステップは、`navigation` 配列をパースし、項目を `section` プロパティに基づいてグループ化することです。単一のナビゲーション項目は、`section` の値に配列を使用することで、複数のセクションに割り当てることができます。

`parseNavigation` ユーティリティは、各項目を事前に定義されたセクションに分類します：
- `header`: メインアプリケーションのヘッダー用。
- `footer`: フッターの主要なリンク用。
- `social`: 通常はフッターに配置されるソーシャルメディアアイコン用。
- `bottom`: フッターの最下部にある法的または二次的なリンク用。
- `dashboard`: ダッシュボードレイアウトのサイドバーナビゲーション用。
- `sessionManager`: ユーザーセッションコンポーネント内のメニュー用。
- `userCenter`: ユーザープロファイルエリア内のタブまたはリンク用。

項目に `section` プロパティがない場合、デフォルトで `header` になります。

### 2. 国際化 (i18n)

ライブラリは、複数の言語を組み込みでサポートしています。ナビゲーション項目の `title` または `link` プロパティが言語キー（例：`en`、`ja`）を持つオブジェクトである場合、`getLocalizedNavigation` 関数はユーザーの現在のロケールに基づいて正しい文字列を自動的に選択します。

```javascript i18n オブジェクトの例 icon=logos:javascript
// 多言語サポートを持つナビゲーション項目
{
  title: {
    en: 'Home',
    ja: 'ホームページ'
  },
  link: {
    en: '/home',
    ja: '/ja/home'
  }
}
```

### 3. ロールベースのフィルタリング

動的なユーザーエクスペリエンスを作成するために、ナビゲーション項目を特定のユーザーロールに制限することができます。`filterNavByRole` 関数は、各項目の `role` プロパティを現在のセッションの `user.role` と比較してナビゲーションリストをフィルタリングします。

- 項目に `role` プロパティがない場合、それは全員に表示されます。
- 項目に `role` プロパティ（例：`['admin', 'editor']`）がある場合、そのロールが配列に含まれるユーザーにのみ表示されます。
- `guest` ロールは、未認証のユーザーに適用される特別な値です。

このメカニズムにより、メタデータで包括的なナビゲーション構造を定義し、ログインしているユーザーの権限に基づいて UI を自動的に適応させることができます。

## まとめ

Blocklet UI React ライブラリのコアコンセプトは、一元化されたメタデータオブジェクトを活用して、共通の UI コンポーネントの設定とレンダリングを駆動することです。このメタデータ駆動アプローチは、いくつかの利点を提供します：

- **信頼できる唯一の情報源**：アプリケーションの構造、ブランディング、ナビゲーションが 1 か所で定義されます。
- **一貫性**：アプリケーションのさまざまな部分で一貫したルックアンドフィールを保証します。
- **ボイラープレートの削減**：ヘッダーやフッターのような共通のレイアウト要素を手動でコーディングする必要がなくなります。
- **動的 UI**：国際化とロールベースのアクセス制御をネイティブでサポートし、UI がユーザーとその権限に応じて動的に適応できるようにします。

これらの原則を明確に理解することで、ライブラリのコンポーネントを効果的に活用できます。特定のコンポーネントとその使用方法に関する詳細については、[コンポーネント](./components.md)セクションを参照してください。