@blocklet/ui-react 3.4.15 → 3.5.0

package/docs/core-concepts.md

@@ -1,135 +0,0 @@
-# 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.
-
-The following diagram illustrates this data flow:
-<!-- DIAGRAM_IMAGE_START:flowchart:16:9:1765962229 -->
-![Core Concepts](assets/diagram/core-concepts-diagram-0.jpg)
-<!-- DIAGRAM_IMAGE_END -->
-
-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

@@ -1,134 +0,0 @@
-# 核心概念
-
-本文件說明 Blocklet UI React 函式庫的基本原則。其核心設計理念是**元數據驅動方法**，其中 UI 元件（如 `Header`、`Footer` 和 `Dashboard`）會根據 blocklet 的元數據自動設定和渲染。此策略確保了一致性，減少了樣板程式碼，並實現了能根據使用者角色和語言偏好進行調整的動態 UI。
-
-其中心思想是，單一設定檔（通常是 `blocklet.yml`）作為應用程式整體結構和外觀的唯一事實來源。函式庫會讀取此元數據，對其進行處理，並用它來建構適當的 UI 元素。
-
-## 元數據驅動原則
-
-該函式庫的運作可以視覺化為一個簡單的資料流：blocklet 元數據作為輸入提供給函式庫，函式庫接著透過一個管線對其進行處理，以產生完全渲染的 UI 元件。這免去了開發人員為每個應用程式手動建構和設定通用佈局元素的需要。
-
-<!-- DIAGRAM_IMAGE_START:flowchart:16:9:1765962229 -->
-![Core Concepts](assets/diagram/core-concepts-diagram-0.zh-TW.jpg)
-<!-- DIAGRAM_IMAGE_END -->
-
-這個自動化過程依賴於一個定義良好的元數據結構，下一節將對此進行詳細說明。
-
-## 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

@@ -1,134 +0,0 @@
-# 核心概念
-
-本文档解释了 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.zh.jpg)
-<!-- DIAGRAM_IMAGE_END -->
-
-这个自动化过程依赖于一个明确定义的元数据结构，下一节将详细介绍。
-
-## 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) 部分。

package/docs/getting-started.ja.md

@@ -1,132 +0,0 @@
-# はじめに
-
-このガイドでは、`@blocklet/ui-react` ライブラリをインストールし、最初のコンポーネントをレンダリングするための手順をステップバイステップで説明します。目標は、最小限の時間でアプリケーション内に機能する `Header` と `Footer` を実装することです。
-
-## 前提条件
-
-先に進む前に、開発環境に以下がインストールされていることを確認してください：
-*   動作する React プロジェクト。
-*   Node.js とパッケージマネージャー（npm または yarn）。
-
-## インストール
-
-まず、お使いのパッケージマネージャーを使用して、`@blocklet/ui-react` パッケージをプロジェクトに追加します。
-
-npm を使用する場合:
-```bash npm
-npm install @blocklet/ui-react
-```
-
-yarn を使用する場合:
-```bash yarn
-yarn add @blocklet/ui-react
-```
-
-## 基本的な使用法: Header と Footer
-
-`Header` と `Footer` コンポーネントはシンプルに設計されており、初期設定なしでレンダリングできます。これらのコンポーネントは、blocklet のメタデータから自動的にデータを取得します。
-
-1.  `Header` と `Footer` コンポーネントをメインのアプリケーションファイル（例：`App.js`）にインポートします。
-2.  それぞれをアプリケーションのレイアウトの最上部と最下部に配置します。
-
-```jsx App.js icon=logos:react
-import React from 'react';
-import Header from '@blocklet/ui-react/lib/Header';
-import Footer from '@blocklet/ui-react/lib/Footer';
-
-function App() {
-  return (
-    <div>
-      <Header />
-      <main style={{ padding: '20px', minHeight: 'calc(100vh - 128px)' }}>
-        {/* アプリケーションのコンテンツはここに記述します */}
-        <h1>Welcome to My Blocklet</h1>
-      </main>
-      <Footer />
-    </div>
-  );
-}
-
-export default App;
-```
-
-コンポーネントは、アプリケーション名、ロゴ、ナビゲーションリンクなどの設定詳細を、Blocklet Server 環境によって注入される `window.blocklet` メタデータオブジェクトから自動的に取得します。
-
-さらに、`Header` コンポーネントは、状況に応じて追加のコントロールをインテリジェントにレンダリングします：
-*   `SessionContext` が利用可能な場合、**ユーザーセッションマネージャー**が表示されます。
-*   `LocaleContext` が利用可能な場合、**言語セレクター**が表示されます。
-
-## 手動設定
-
-開発、テスト、またはデフォルトのメタデータを上書きする必要がある場合、`blockletMeta` プロパティを使用して設定オブジェクトをコンポーネントに直接渡すことができます。
-
-```jsx App.js icon=logos:react
-import React from 'react';
-import Header from '@blocklet/ui-react/lib/Header';
-
-const customBlockletMeta = {
-  appName: 'My Custom App',
-  appLogo: 'https://path.to/your/logo.png',
-  navigation: [
-    {
-      title: 'Home',
-      link: '/',
-    },
-    {
-      title: 'Documentation',
-      link: '/docs',
-    },
-  ],
-};
-
-function App() {
-  return (
-    <div>
-      <Header blockletMeta={customBlockletMeta} />
-      {/* ... rest of your app */}
-    </div>
-  );
-}
-```
-
-このアプローチにより、グローバルな `window.blocklet` オブジェクトによって提供されるデータを上書きし、コンポーネントの外観と動作を正確に制御できます。
-
-## Header のカスタマイズ
-
-`Header` コンポーネントには右側に `addons` エリアがあり、アクションボタンやカスタムリンクなど、独自のコンポーネントを含めるようにカスタマイズできます。
-
-`addons` プロパティは、デフォルトのアドオンコンポーネントを引数として受け取る関数を受け入れます。これにより、既存のコンポーネントの前に追加したり、後ろに追加したり、完全に置き換えたりすることができます。
-
-```jsx CustomHeader.js icon=logos:react
-import React from 'react';
-import Header from '@blocklet/ui-react/lib/Header';
-import Button from '@mui/material/Button'; // Material-UI を使用した例
-
-function CustomHeader() {
-  return (
-    <Header
-      addons={existingAddons => {
-        return [
-          <Button
-            key="custom-action"
-            variant="contained"
-            color="primary"
-            size="small"
-            style={{ marginRight: 8 }}>
-            Custom Action
-          </Button>,
-          ...existingAddons, // 重要: デフォルトのセッション/ロケールアドオンを保持します
-        ];
-      }}
-    />
-  );
-}
-```
-
-この例では、カスタムボタンが既存のアドオンの前に追加されています。`...existingAddons` を含めることで、デフォルトのセッションおよびロケールコントロールが表示されたままになるようにします。
-
-## まとめ
-
-これで、`@blocklet/ui-react` ライブラリのインストール、デフォルトの `Header` および `Footer` コンポーネントのレンダリング、そしてカスタム設定やアドオンの提供方法を学びました。
-
-これらの基本を理解したことで、ライブラリで利用可能なすべてのコンポーネントを探索する準備が整いました。レイアウト、ユーザー管理、ユーティリティコンポーネントに関する詳細なドキュメントについては、[コンポーネント](./components.md) セクションに進んでください。

package/docs/getting-started.md

@@ -1,132 +0,0 @@
-# Getting Started
-
-This guide provides a step-by-step walkthrough to install the `@blocklet/ui-react` library and render your first components. The objective is to have a functional `Header` and `Footer` within your application in a minimal amount of time.
-
-## Prerequisites
-
-Before proceeding, ensure you have the following installed in your development environment:
-*   A functional React project.
-*   Node.js and a package manager (npm or yarn).
-
-## Installation
-
-To begin, add the `@blocklet/ui-react` package to your project using your preferred package manager.
-
-With npm:
-```bash npm
-npm install @blocklet/ui-react
-```
-
-With yarn:
-```bash yarn
-yarn add @blocklet/ui-react
-```
-
-## Basic Usage: Header and Footer
-
-The `Header` and `Footer` components are designed for simplicity and can be rendered without any initial configuration. They automatically source their data from the blocklet's metadata.
-
-1.  Import the `Header` and `Footer` components into your main application file (e.g., `App.js`).
-2.  Place them at the top and bottom of your application's layout, respectively.
-
-```jsx App.js icon=logos:react
-import React from 'react';
-import Header from '@blocklet/ui-react/lib/Header';
-import Footer from '@blocklet/ui-react/lib/Footer';
-
-function App() {
-  return (
-    <div>
-      <Header />
-      <main style={{ padding: '20px', minHeight: 'calc(100vh - 128px)' }}>
-        {/* Your application content goes here */}
-        <h1>Welcome to My Blocklet</h1>
-      </main>
-      <Footer />
-    </div>
-  );
-}
-
-export default App;
-```
-
-The components automatically retrieve configuration details—such as the application name, logo, and navigation links—from the `window.blocklet` metadata object, which is injected by the Blocklet Server environment.
-
-Furthermore, the `Header` component will intelligently render additional controls:
-*   A **user session manager** is displayed if a `SessionContext` is available.
-*   A **language selector** is displayed if a `LocaleContext` is available.
-
-## Manual Configuration
-
-For development, testing, or cases where you need to override the default metadata, you can pass a configuration object directly to the components using the `blockletMeta` prop.
-
-```jsx App.js icon=logos:react
-import React from 'react';
-import Header from '@blocklet/ui-react/lib/Header';
-
-const customBlockletMeta = {
-  appName: 'My Custom App',
-  appLogo: 'https://path.to/your/logo.png',
-  navigation: [
-    {
-      title: 'Home',
-      link: '/',
-    },
-    {
-      title: 'Documentation',
-      link: '/docs',
-    },
-  ],
-};
-
-function App() {
-  return (
-    <div>
-      <Header blockletMeta={customBlockletMeta} />
-      {/* ... rest of your app */}
-    </div>
-  );
-}
-```
-
-This approach gives you precise control over the component's appearance and behavior by overriding any data provided by the global `window.blocklet` object.
-
-## Customizing the Header
-
-The `Header` component includes an `addons` area on the right side, which you can customize to include your own components, such as action buttons or custom links.
-
-The `addons` prop accepts a function that receives the default addon components as an argument. This allows you to prepend, append, or completely replace them.
-
-```jsx CustomHeader.js icon=logos:react
-import React from 'react';
-import Header from '@blocklet/ui-react/lib/Header';
-import Button from '@mui/material/Button'; // Example using Material-UI
-
-function CustomHeader() {
-  return (
-    <Header
-      addons={existingAddons => {
-        return [
-          <Button
-            key="custom-action"
-            variant="contained"
-            color="primary"
-            size="small"
-            style={{ marginRight: 8 }}>
-            Custom Action
-          </Button>,
-          ...existingAddons, // Important: preserves default session/locale addons
-        ];
-      }}
-    />
-  );
-}
-```
-
-In this example, a custom button is prepended to the existing addons. By including `...existingAddons`, you ensure that the default session and locale controls remain visible.
-
-## Summary
-
-You have successfully installed the `@blocklet/ui-react` library, rendered default `Header` and `Footer` components, and learned how to provide custom configurations and addons.
-
-With these fundamentals in place, you are now prepared to explore the full range of components available in the library. For detailed documentation on layout, user management, and utility components, please proceed to the [Components](./components.md) section.