@blocklet/ui-react 3.1.47 → 3.1.49

package/docs/core-concepts.ja.md

@@ -0,0 +1,164 @@
+# コアコンセプト
+
+このドキュメントでは、Blocklet UI React ライブラリの基本原則について説明します。中心的な設計思想は**メタデータ駆動アプローチ**であり、`Header`、`Footer`、`Dashboard` などの UI コンポーネントは、blocklet のメタデータに基づいて自動的に設定・レンダリングされます。この戦略により、一貫性が確保され、定型的なコードが削減され、ユーザーの役割や言語設定に適応する動的な UI が可能になります。
+
+中心的な考え方は、単一の設定ファイル（通常は `blocklet.yml`）が、アプリケーションの全体的な構造と外観に関する信頼できる唯一の情報源として機能するということです。ライブラリはこのメタデータを読み取り、処理し、それを使用して適切な UI 要素を構築します。
+
+## メタデータ駆動の原則
+
+ライブラリの動作は、単純なデータフローとして視覚化できます。blocklet のメタデータがライブラリへの入力として提供され、ライブラリはそれをパイプラインを通じて処理し、完全にレンダリングされた UI コンポーネントを生成します。これにより、開発者がアプリケーションごとに共通のレイアウト要素を手動で構築・設定する必要がなくなります。
+
+```d2
+direction: down
+
+blocklet-metadata: {
+  label: "Blocklet メタデータ\n(blocklet.yml から)"
+  shape: rectangle
+}
+
+blocklet-ui-library: {
+  label: "Blocklet UI ライブラリ\n(データ処理パイプライン)"
+  shape: rectangle
+
+  parse: { label: "1. パースとセクション分割" }
+  localize: { label: "2. ローカライズ (i18n)" }
+  filter: { label: "3. ロールによるフィルタリング" }
+
+  parse -> localize
+  localize -> filter
+}
+
+rendered-components: {
+  label: "自動レンダリングされるコンポーネント"
+  shape: rectangle
+  grid-columns: 3
+
+  Header: {}
+  Footer: {}
+  Dashboard: {}
+}
+
+blocklet-metadata -> blocklet-ui-library: "入力"
+blocklet-ui-library -> rendered-components: "出力"
+```
+
+この自動化されたプロセスは、明確に定義されたメタデータ構造に依存しており、それについては次のセクションで詳しく説明します。
+
+## 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)セクションを参照してください。

package/docs/core-concepts.md

@@ -0,0 +1,164 @@
+# Core Concepts
+
+This document explains the fundamental principles of the Blocklet UI React library. The core design philosophy is a **metadata-driven approach**, where UI components such as the `Header`, `Footer`, and `Dashboard` are automatically configured and rendered based on the blocklet's metadata. This strategy ensures consistency, reduces boilerplate code, and enables dynamic UIs that adapt to user roles and language preferences.
+
+The central idea is that a single configuration file, typically `blocklet.yml`, serves as the single source of truth for the application's overall structure and appearance. The library reads this metadata, processes it, and uses it to construct the appropriate UI elements.
+
+## The Metadata-Driven Principle
+
+The library's operation can be visualized as a simple data flow: the blocklet metadata is provided as input to the library, which then processes it through a pipeline to produce fully rendered UI components. This eliminates the need for developers to manually build and configure common layout elements for each application.
+
+```d2
+direction: down
+
+blocklet-metadata: {
+  label: "Blocklet Metadata\n(from blocklet.yml)"
+  shape: rectangle
+}
+
+blocklet-ui-library: {
+  label: "Blocklet UI Library\n(Data Processing Pipeline)"
+  shape: rectangle
+
+  parse: { label: "1. Parse & Section" }
+  localize: { label: "2. Localize (i18n)" }
+  filter: { label: "3. Filter by Role" }
+
+  parse -> localize
+  localize -> filter
+}
+
+rendered-components: {
+  label: "Automatically Rendered Components"
+  shape: rectangle
+  grid-columns: 3
+
+  Header: {}
+  Footer: {}
+  Dashboard: {}
+}
+
+blocklet-metadata -> blocklet-ui-library: "Input"
+blocklet-ui-library -> rendered-components: "Output"
+```
+
+This automated process relies on a well-defined metadata structure, which is detailed in the following section.
+
+## Anatomy of Blocklet Metadata
+
+The library expects a specific object structure, referred to as `BlockletMetaProps`, which contains all the necessary information for rendering the UI. Below is a detailed breakdown of this structure.
+
+<x-field-group>
+  <x-field data-name="appName" data-type="string" data-required="false" data-desc="The name of the application, typically displayed in the Header."></x-field>
+  <x-field data-name="appLogo" data-type="React.ReactNode" data-required="false" data-desc="A React node for the application's logo, also displayed in the Header."></x-field>
+  <x-field data-name="enableConnect" data-type="boolean" data-required="false" data-desc="Determines whether to display a DID Connect button."></x-field>
+  <x-field data-name="enableLocale" data-type="boolean" data-required="false" data-desc="Determines whether to display the language selection component."></x-field>
+  <x-field data-name="theme" data-type="object" data-required="false">
+    <x-field-desc markdown>Defines the color scheme for the application layout.</x-field-desc>
+    <x-field data-name="background" data-type="string" data-required="false" data-desc="Sets the background color for layout components like the Header and Footer."></x-field>
+  </x-field>
+  <x-field data-name="navigation" data-type="array" data-required="false">
+    <x-field-desc markdown>An array of navigation item objects that define the links and menus throughout the application.</x-field-desc>
+    <x-field data-name="title" data-type="string | object" data-required="true" data-desc="The display text for the navigation item. Can be an object for i18n."></x-field>
+    <x-field data-name="link" data-type="string | object" data-required="false" data-desc="The URL for the navigation item. Can be an object for i18n."></x-field>
+    <x-field data-name="icon" data-type="string" data-required="false" data-desc="An Iconify-compatible string for an icon to display next to the title."></x-field>
+    <x-field data-name="section" data-type="string | array" data-required="false" data-desc="Specifies where the item should appear, e.g., 'header', 'footer', 'dashboard'."></x-field>
+    <x-field data-name="role" data-type="string | array" data-required="false" data-desc="Defines which user roles can see this item, e.g., 'admin', 'guest'."></x-field>
+    <x-field data-name="items" data-type="array" data-required="false" data-desc="An array of nested navigation items to create dropdown menus or sub-menus."></x-field>
+  </x-field>
+</x-field-group>
+
+### Navigation Configuration Example
+
+The `navigation` array is the most critical part of the metadata. It provides a structured way to define all links, menus, and their placement.
+
+```yaml Navigation Configuration in blocklet.yml icon=mdi:code-braces
+# blocklet.yml
+navigation:
+  - title: Features
+    link: /features
+  - title:
+      en: About Us
+      zh: 关于我们
+    link:
+      en: /about
+      zh: /about-us
+    section: footer
+  - title: Admin Dashboard
+    link: /admin
+    section: dashboard
+    role: admin
+  - title: Social
+    section: social
+    items:
+      - title: Twitter
+        link: https://twitter.com/arcblock
+        icon: mdi:twitter
+      - title: GitHub
+        link: https://github.com/arcblock
+        icon: mdi:github
+```
+
+This example illustrates several key features:
+- A simple header link ("Features").
+- A multi-language footer link ("About Us").
+- An admin-only link for the dashboard.
+- A group of social media links intended for the footer.
+
+## The Data Processing Pipeline
+
+Before rendering, the library processes the raw metadata through a series of steps to prepare it for the UI components.
+
+### 1. Parsing and Sectioning
+
+The first step is to parse the `navigation` array and group items based on their `section` property. A single navigation item can be assigned to multiple sections by using an array for the `section` value.
+
+The `parseNavigation` utility categorizes each item into predefined sections:
+- `header`: For the main application header.
+- `footer`: For primary links in the footer.
+- `social`: For social media icons, typically in the footer.
+- `bottom`: For legal or secondary links at the very bottom of the footer.
+- `dashboard`: For the sidebar navigation in a dashboard layout.
+- `sessionManager`: For menus within the user session component.
+- `userCenter`: For tabs or links within the user profile area.
+
+If an item has no `section` property, it defaults to `header`.
+
+### 2. Internationalization (i18n)
+
+The library provides built-in support for multiple languages. If a `title` or `link` property in a navigation item is an object with language keys (e.g., `en`, `zh`), the `getLocalizedNavigation` function automatically selects the correct string based on the user's current locale.
+
+```javascript i18n Object Example icon=logos:javascript
+// A navigation item with multi-language support
+{
+  title: {
+    en: 'Home',
+    zh: '首页'
+  },
+  link: {
+    en: '/home',
+    zh: '/zh/home'
+  }
+}
+```
+
+### 3. Role-Based Filtering
+
+To create a dynamic user experience, navigation items can be restricted to specific user roles. The `filterNavByRole` function filters the navigation list by comparing the `role` property of each item against the `user.role` from the current session.
+
+- If an item has no `role` property, it is visible to everyone.
+- If an item has a `role` property (e.g., `['admin', 'editor']`), it is only visible to users whose role is in that array.
+- The `guest` role is a special value that applies to unauthenticated users.
+
+This mechanism allows you to define a comprehensive navigation structure in your metadata and have the UI automatically adapt based on the logged-in user's permissions.
+
+## Summary
+
+The core concept of the Blocklet UI React library is to leverage a centralized metadata object to drive the configuration and rendering of common UI components. This metadata-driven approach offers several advantages:
+
+- **Single Source of Truth**: Application structure, branding, and navigation are defined in one place.
+- **Consistency**: Ensures a consistent look and feel across different parts of the application.
+- **Reduced Boilerplate**: Eliminates the need to manually code common layout elements like headers and footers.
+- **Dynamic UI**: Natively supports internationalization and role-based access control, allowing the UI to adapt dynamically to the user and their permissions.
+
+With a clear understanding of these principles, you can effectively utilize the library's components. For more information on specific components and their usage, please refer to the [Components](./components.md) section.

package/docs/core-concepts.zh-TW.md

@@ -0,0 +1,164 @@
+# 核心概念
+
+本文件說明 Blocklet UI React 函式庫的基本原則。其核心設計理念是**元數據驅動方法**，其中 UI 元件（如 `Header`、`Footer` 和 `Dashboard`）會根據 blocklet 的元數據自動設定和渲染。此策略確保了一致性，減少了樣板程式碼，並實現了能根據使用者角色和語言偏好進行調整的動態 UI。
+
+其中心思想是，單一設定檔（通常是 `blocklet.yml`）作為應用程式整體結構和外觀的唯一事實來源。函式庫會讀取此元數據，對其進行處理，並用它來建構適當的 UI 元素。
+
+## 元數據驅動原則
+
+該函式庫的運作可以視覺化為一個簡單的資料流：blocklet 元數據作為輸入提供給函式庫，函式庫接著透過一個管線對其進行處理，以產生完全渲染的 UI 元件。這免去了開發人員為每個應用程式手動建構和設定通用佈局元素的需要。
+
+```d2
+direction: down
+
+blocklet-metadata: {
+  label: "Blocklet 元數據\n(來自 blocklet.yml)"
+  shape: rectangle
+}
+
+blocklet-ui-library: {
+  label: "Blocklet UI 函式庫\n(資料處理管線)"
+  shape: rectangle
+
+  parse: { label: "1. 解析與分區" }
+  localize: { label: "2. 本地化 (i18n)" }
+  filter: { label: "3. 依角色篩選" }
+
+  parse -> localize
+  localize -> filter
+}
+
+rendered-components: {
+  label: "自動渲染的元件"
+  shape: rectangle
+  grid-columns: 3
+
+  Header: {}
+  Footer: {}
+  Dashboard: {}
+}
+
+blocklet-metadata -> blocklet-ui-library: "輸入"
+blocklet-ui-library -> rendered-components: "輸出"
+```
+
+這個自動化過程依賴於一個定義良好的元數據結構，下一節將對此進行詳細說明。
+
+## Blocklet 元數據剖析
+
+該函式庫期望一個特定的物件結構，稱為 `BlockletMetaProps`，其中包含渲染 UI 所需的所有資訊。以下是此結構的詳細分解。
+
+<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: Features
+    link: /features
+  - title:
+      en: About Us
+      zh: 关于我们
+    link:
+      en: /about
+      zh: /about-us
+    section: footer
+  - title: Admin Dashboard
+    link: /admin
+    section: dashboard
+    role: admin
+  - title: Social
+    section: social
+    items:
+      - title: Twitter
+        link: https://twitter.com/arcblock
+        icon: mdi:twitter
+      - title: GitHub
+        link: https://github.com/arcblock
+        icon: mdi:github
+```
+
+此範例說明了幾個關鍵功能：
+- 一個簡單的 header 連結（「Features」）。
+- 一個多語言的 footer 連結（「About Us」）。
+- 一個僅限管理員的 dashboard 連結。
+- 一組用於 footer 的社群媒體連結。
+
+## 資料處理管線
+
+在渲染之前，函式庫會透過一系列步驟處理原始元數據，為 UI 元件做好準備。
+
+### 1. 解析與分區
+
+第一步是解析 `navigation` 陣列，並根據其 `section` 屬性將項目分組。透過為 `section` 值使用陣列，可以將單個導覽項目分配到多個區塊。
+
+`parseNavigation` 工具程式會將每個項目分類到預定義的區塊中：
+- `header`：用於主應用程式的 header。
+- `footer`：用於 footer 中的主要連結。
+- `social`：用於社群媒體圖示，通常在 footer 中。
+- `bottom`：用於 footer 最底部的法律或次要連結。
+- `dashboard`：用於 dashboard 佈局中的側邊欄導覽。
+- `sessionManager`：用於使用者會話元件中的選單。
+- `userCenter`：用於使用者個人資料區域中的標籤或連結。
+
+如果項目沒有 `section` 屬性，則預設為 `header`。
+
+### 2. 國際化 (i18n)
+
+該函式庫內建支援多種語言。如果導覽項目中的 `title` 或 `link` 屬性是帶有語言鍵（例如 `en`、`zh`）的物件，`getLocalizedNavigation` 函式會根據使用者當前的語系自動選擇正確的字串。
+
+```javascript i18n 物件範例 icon=logos:javascript
+// 一個支援多語言的導覽項目
+{
+  title: {
+    en: 'Home',
+    zh: '首页'
+  },
+  link: {
+    en: '/home',
+    zh: '/zh/home'
+  }
+}
+```
+
+### 3. 基於角色的篩選
+
+為了創造動態的使用者體驗，可以將導覽項目限制給特定的使用者角色。`filterNavByRole` 函式會透過比較每個項目的 `role` 屬性與當前會話中的 `user.role` 來篩選導覽列表。
+
+- 如果項目沒有 `role` 屬性，則對所有人可見。
+- 如果項目有 `role` 屬性（例如 `['admin', 'editor']`），則僅對角色在該陣列中的使用者可見。
+- `guest` 角色是一個特殊值，適用於未經驗證的使用者。
+
+此機制讓您可以在元數據中定義一個全面的導覽結構，並讓 UI 根據登入使用者的權限自動調整。
+
+## 總結
+
+Blocklet UI React 函式庫的核心概念是利用一個集中的元數據物件來驅動通用 UI 元件的設定與渲染。這種元數據驅動的方法提供了幾個優點：
+
+- **單一事實來源**：應用程式的結構、品牌和導覽都在一個地方定義。
+- **一致性**：確保應用程式不同部分之間具有一致的外觀和風格。
+- **減少樣板程式碼**：無需手動編寫像 header 和 footer 這樣的通用佈局元素。
+- **動態 UI**：原生支援國際化和基於角色的存取控制，讓 UI 能夠根據使用者及其權限動態調整。
+
+清楚了解這些原則後，您就能有效地利用該函式庫的元件。有關特定元件及其用法的更多資訊，請參閱 [元件](./components.md) 部分。

package/docs/core-concepts.zh.md

@@ -0,0 +1,164 @@
+# 核心概念
+
+本文档解释了 Blocklet UI React 库的基本原则。其核心设计理念是**元数据驱动方法**，即 `Header`、`Footer` 和 `Dashboard` 等 UI 组件会根据 blocklet 的元数据自动配置和渲染。这种策略确保了一致性，减少了样板代码，并实现了能适应用户角色和语言偏好的动态 UI。
+
+其中心思想是，单个配置文件（通常是 `blocklet.yml`）作为应用程序整体结构和外观的单一事实来源。该库读取、处理此元数据，并用其构建相应的 UI 元素。
+
+## 元数据驱动原则
+
+该库的运作可以看作一个简单的数据流：blocklet 元数据作为输入提供给库，库通过一个管道处理它，最终生成完全渲染的 UI 组件。这免去了开发者为每个应用程序手动构建和配置通用布局元素的需求。
+
+```d2
+direction: down
+
+blocklet-metadata: {
+  label: "Blocklet 元数据\n(来自 blocklet.yml)"
+  shape: rectangle
+}
+
+blocklet-ui-library: {
+  label: "Blocklet UI 库\n(数据处理管道)"
+  shape: rectangle
+
+  parse: { label: "1. 解析与分段" }
+  localize: { label: "2. 本地化 (i18n)" }
+  filter: { label: "3. 按角色过滤" }
+
+  parse -> localize
+  localize -> filter
+}
+
+rendered-components: {
+  label: "自动渲染的组件"
+  shape: rectangle
+  grid-columns: 3
+
+  Header: {}
+  Footer: {}
+  Dashboard: {}
+}
+
+blocklet-metadata -> blocklet-ui-library: "输入"
+blocklet-ui-library -> rendered-components: "输出"
+```
+
+这个自动化过程依赖于一个明确定义的元数据结构，下一节将详细介绍。
+
+## Blocklet 元数据剖析
+
+该库期望一个特定的对象结构，称为 `BlockletMetaProps`，其中包含渲染 UI 所需的所有信息。以下是该结构的详细分解。
+
+<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: Features
+    link: /features
+  - title:
+      en: About Us
+      zh: 关于我们
+    link:
+      en: /about
+      zh: /about-us
+    section: footer
+  - title: Admin Dashboard
+    link: /admin
+    section: dashboard
+    role: admin
+  - title: Social
+    section: social
+    items:
+      - title: Twitter
+        link: https://twitter.com/arcblock
+        icon: mdi:twitter
+      - title: GitHub
+        link: https://github.com/arcblock
+        icon: mdi:github
+```
+
+此示例说明了几个关键功能：
+- 一个简单的页眉链接（“Features”）。
+- 一个多语言页脚链接（“About Us”）。
+- 一个仅限管理员的仪表盘链接。
+- 一组用于页脚的社交媒体链接。
+
+## 数据处理管道
+
+在渲染之前，该库会通过一系列步骤处理原始元数据，为 UI 组件做准备。
+
+### 1. 解析与分段
+
+第一步是解析 `navigation` 数组，并根据其 `section` 属性对项目进行分组。通过为 `section` 值使用数组，可以将单个导航项分配到多个区域。
+
+`parseNavigation` 工具将每个项目分类到预定义的区域中：
+- `header`：用于主应用程序页眉。
+- `footer`：用于页脚中的主要链接。
+- `social`：用于社交媒体图标，通常在页脚中。
+- `bottom`：用于页脚最底部的法律或次要链接。
+- `dashboard`：用于仪表盘布局中的侧边栏导航。
+- `sessionManager`：用于用户会话组件内的菜单。
+- `userCenter`：用于用户个人资料区域内的选项卡或链接。
+
+如果一个项目没有 `section` 属性，它默认被归为 `header`。
+
+### 2. 国际化 (i18n)
+
+该库内置了对多种语言的支持。如果导航项中的 `title` 或 `link` 属性是一个带有语言键（例如 `en`、`zh`）的对象，`getLocalizedNavigation` 函数会根据用户当前的区域设置自动选择正确的字符串。
+
+```javascript i18n 对象示例 icon=logos:javascript
+// 一个支持多语言的导航项
+{
+  title: {
+    en: 'Home',
+    zh: '首页'
+  },
+  link: {
+    en: '/home',
+    zh: '/zh/home'
+  }
+}
+```
+
+### 3. 基于角色的过滤
+
+为了创建动态的用户体验，导航项可以限制于特定的用户角色。`filterNavByRole` 函数通过将每个项目的 `role` 属性与当前会话中的 `user.role` 进行比较来过滤导航列表。
+
+- 如果一个项目没有 `role` 属性，它对所有人可见。
+- 如果一个项目有 `role` 属性（例如 `['admin', 'editor']`），它仅对角色在该数组中的用户可见。
+- `guest` 角色是一个特殊值，适用于未经身份验证的用户。
+
+这种机制允许您在元数据中定义一个全面的导航结构，并让 UI 根据登录用户的权限自动适应。
+
+## 总结
+
+Blocklet UI React 库的核心概念是利用一个集中的元数据对象来驱动通用 UI 组件的配置和渲染。这种元数据驱动方法具有以下几个优点：
+
+- **单一事实来源**：应用程序的结构、品牌和导航都在一个地方定义。
+- **一致性**：确保应用程序不同部分具有一致的外观和感觉。
+- **减少样板代码**：无需手动编码像页眉和页脚这样的通用布局元素。
+- **动态 UI**：原生支持国际化和基于角色的访问控制，允许 UI 根据用户及其权限动态调整。
+
+清楚地理解了这些原则后，您就可以有效地利用该库的组件。有关特定组件及其用法的更多信息，请参阅 [组件](./components.md) 部分。