@blocklet/ui-react 3.4.14 → 3.5.0

package/docs/components-utilities.md

@@ -1,136 +0,0 @@
-# Utilities
-
-This section provides documentation for a collection of helper components, Higher-Order Components (HOCs), and utility functions. These tools are designed to simplify common development tasks, manage application themes, and handle complex data structures.
-
-The primary utilities available are:
-
-<x-cards data-columns="2">
-  <x-card data-title="Icon Component" data-icon="lucide:image" data-href="/components/utilities/icon">
-    A versatile component for displaying icons from various sources, including Iconify, image URLs, or as letter avatars.
-  </x-card>
-  <x-card data-title="OverridableThemeProvider" data-icon="lucide:palette">
-    A theme provider that allows developers to supply their own theme object to override the default Blocklet UI theme.
-  </x-card>
-  <x-card data-title="withHideWhenEmbed HOC" data-icon="lucide:eye-off">
-    A Higher-Order Component that conditionally renders a component, hiding it when the application is in an embedded mode.
-  </x-card>
-  <x-card data-title="JavaScript Helpers" data-icon="lucide:function-square">
-    A suite of standalone functions for tasks such as recursive array manipulation, URL validation, and path matching.
-  </x-card>
-</x-cards>
-
-For a detailed guide on the `Icon` component, please see its dedicated documentation page. The other utilities are documented below.
-
-## OverridableThemeProvider
-
-This component is a wrapper around Material-UI's `ThemeProvider`. It allows you to apply a consistent theme to its child components. By default, it uses the standard Blocklet UI theme, but you can provide a custom theme object via the `theme` prop to override the default styles.
-
-### Usage
-
-To apply a custom theme, pass a theme object to the `theme` prop. The component will merge your overrides with the default theme.
-
-```javascript Theme Provider Example icon=logos:javascript
-import OverridableThemeProvider from '@blocklet/ui-react/lib/common/overridable-theme-provider';
-import { Button } from '@mui/material';
-
-const customTheme = {
-  palette: {
-    primary: {
-      main: '#ff5722',
-    },
-  },
-};
-
-function App() {
-  return (
-    <OverridableThemeProvider theme={customTheme}>
-      <Button color="primary" variant="contained">
-        Custom Themed Button
-      </Button>
-    </OverridableThemeProvider>
-  );
-}
-```
-
-## withHideWhenEmbed
-
-`withHideWhenEmbed` is a Higher-Order Component (HOC) that prevents a component from rendering if the application is in "embed mode." It checks a session storage key (`EMBED_MODE_KEY`) to determine the current mode. If the value is `1`, the wrapped component will return `null`.
-
-This is useful for hiding elements like headers or footers in an embedded context where they are not needed.
-
-### Usage
-
-Wrap the component you wish to conditionally hide with the `withHideWhenEmbed` HOC.
-
-```javascript HOC Example icon=logos:javascript
-import withHideWhenEmbed from '@blocklet/ui-react/lib/libs/with-hide-when-embed';
-
-function PageHeader() {
-  return (
-    <header>
-      <h1>My Application</h1>
-    </header>
-  );
-}
-
-const MaybeHiddenHeader = withHideWhenEmbed(PageHeader);
-
-function App() {
-  return (
-    <div>
-      <MaybeHiddenHeader />
-      <main>
-        {/* Main content goes here */}
-      </main>
-    </div>
-  );
-}
-```
-
-## Helper Functions
-
-A set of pure JavaScript functions are available for common data manipulation and validation tasks. These can be imported directly from the library's utility module.
-
-### Array Manipulation
-
-These functions are designed to work with arrays of nested objects, such as navigation menus or file trees.
-
-| Function | Description |
-| --- | --- |
-| `mapRecursive(array, fn, childrenKey = 'children')` | Recursively applies a function to each item in a nested array. |
-| `flatRecursive(array, childrenKey = 'children')` | Flattens a nested array into a single-level array. |
-| `countRecursive(array, childrenKey = 'children')` | Counts the total number of items in a nested array. |
-| `filterRecursive(array, predicate, childrenKey = 'children')` | Recursively filters a nested array based on a predicate function, preserving parent structure if children match. |
-
-### String & URL Validation
-
-Simple helpers for checking string formats.
-
-| Function | Description |
-| --- | --- |
-| `isUrl(str)` | Returns `true` if the string starts with `http://` or `https://`. |
-| `isMailProtocol(str)` | Returns `true` if the string starts with `mailto:`. |
-
-### Routing
-
-Utilities to assist with client-side routing logic.
-
-| Function | Description |
-| --- | --- |
-| `matchPath(path)` | Checks if a given path matches the current `window.location.pathname`. |
-| `matchPaths(paths)` | Finds the best matching path from an array of paths against the current location. |
-
-### Layout
-
-| Function | Description |
-| --- | --- |
-| `splitNavColumns(items, options)` | Splits a list of navigation items into a specified number of columns, useful for creating mega menus. |
-
----
-
-### Summary
-
-This section provided an overview of the general-purpose utilities included in the library. For more powerful, specialized functionality, proceed to the detailed documentation for individual components.
-
-For a comprehensive guide on using the flexible `Icon` component, please refer to the next section.
-- **[Icon](./components-utilities-icon.md)**

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

@@ -1,136 +0,0 @@
-# 工具
-
-本節提供了一系列輔助元件、高階元件 (HOCs) 和工具函式的說明文件。這些工具旨在簡化常見的開發任務、管理應用程式主題以及處理複雜的資料結構。
-
-可用的主要工具有：
-
-<x-cards data-columns="2">
-  <x-card data-title="圖示元件" data-icon="lucide:image" data-href="/components/utilities/icon">
-    一個多功能的元件，可用於顯示來自各種來源的圖示，包括 Iconify、圖片 URL 或字母頭像。
-  </x-card>
-  <x-card data-title="OverridableThemeProvider" data-icon="lucide:palette">
-    一個主題提供者，允許開發人員提供自己的主題物件來覆寫預設的 Blocklet UI 主題。
-  </x-card>
-  <x-card data-title="withHideWhenEmbed HOC" data-icon="lucide:eye-off">
-    一個高階元件，可根據條件渲染元件，當應用程式處於嵌入模式時將其隱藏。
-  </x-card>
-  <x-card data-title="JavaScript 輔助函式" data-icon="lucide:function-square">
-    一套獨立的函式，用於遞迴陣列操作、URL 驗證和路徑匹配等任務。
-  </x-card>
-</x-cards>
-
-有關 `Icon` 元件的詳細指南，請參閱其專門的文件頁面。其他工具的說明文件如下。
-
-## OverridableThemeProvider
-
-此元件是 Material-UI `ThemeProvider` 的一個封裝。它允許您將一致的主題應用於其子元件。預設情況下，它使用標準的 Blocklet UI 主題，但您可以透過 `theme` 屬性提供一個自訂的主題物件來覆寫預設樣式。
-
-### 使用方法
-
-若要應用自訂主題，請將一個主題物件傳遞給 `theme` 屬性。該元件會將您的覆寫與預設主題合併。
-
-```javascript Theme Provider Example icon=logos:javascript
-import OverridableThemeProvider from '@blocklet/ui-react/lib/common/overridable-theme-provider';
-import { Button } from '@mui/material';
-
-const customTheme = {
-  palette: {
-    primary: {
-      main: '#ff5722',
-    },
-  },
-};
-
-function App() {
-  return (
-    <OverridableThemeProvider theme={customTheme}>
-      <Button color="primary" variant="contained">
-        Custom Themed Button
-      </Button>
-    </OverridableThemeProvider>
-  );
-}
-```
-
-## withHideWhenEmbed
-
-`withHideWhenEmbed` 是一個高階元件 (HOC)，如果應用程式處於「嵌入模式」，它會防止元件被渲染。它會檢查一個 session storage 的鍵 (`EMBED_MODE_KEY`) 來確定當前模式。如果該值為 `1`，被封裝的元件將返回 `null`。
-
-這對於在嵌入式情境中隱藏不需要的元素（如頁首或頁尾）非常有用。
-
-### 使用方法
-
-用 `withHideWhenEmbed` HOC 封裝您希望有條件地隱藏的元件。
-
-```javascript HOC Example icon=logos:javascript
-import withHideWhenEmbed from '@blocklet/ui-react/lib/libs/with-hide-when-embed';
-
-function PageHeader() {
-  return (
-    <header>
-      <h1>My Application</h1>
-    </header>
-  );
-}
-
-const MaybeHiddenHeader = withHideWhenEmbed(PageHeader);
-
-function App() {
-  return (
-    <div>
-      <MaybeHiddenHeader />
-      <main>
-        {/* 主要內容放置於此 */}
-      </main>
-    </div>
-  );
-}
-```
-
-## 輔助函式
-
-提供了一組純 JavaScript 函式，用於常見的資料操作和驗證任務。這些函式可以直接從函式庫的工具模組中匯入。
-
-### 陣列操作
-
-這些函式設計用於處理巢狀物件的陣列，例如導覽選單或檔案樹。
-
-| 函式 | 說明 |
-| --- | --- |
-| `mapRecursive(array, fn, childrenKey = 'children')` | 遞迴地將一個函式應用於巢狀陣列中的每個項目。 |
-| `flatRecursive(array, childrenKey = 'children')` | 將巢狀陣列扁平化為單層陣列。 |
-| `countRecursive(array, childrenKey = 'children')` | 計算巢狀陣列中項目的總數。 |
-| `filterRecursive(array, predicate, childrenKey = 'children')` | 根據一個斷言函式遞迴地篩選巢狀陣列，如果子項目匹配，則保留父結構。 |
-
-### 字串與 URL 驗證
-
-用於檢查字串格式的簡單輔助函式。
-
-| 函式 | 說明 |
-| --- | --- |
-| `isUrl(str)` | 如果字串以 `http://` 或 `https://` 開頭，則返回 `true`。 |
-| `isMailProtocol(str)` | 如果字串以 `mailto:` 開頭，則返回 `true`。 |
-
-### 路由
-
-協助客戶端路由邏輯的工具。
-
-| 函式 | 說明 |
-| --- | --- |
-| `matchPath(path)` | 檢查給定路徑是否與當前的 `window.location.pathname` 匹配。 |
-| `matchPaths(paths)` | 從一個路徑陣列中，找到與當前位置最佳匹配的路徑。 |
-
-### 版面配置
-
-| 函式 | 說明 |
-| --- | --- |
-| `splitNavColumns(items, options)` | 將導覽項目列表分割成指定數量的欄，對於建立大型選單很有用。 |
-
----
-
-### 總結
-
-本節概述了函式庫中包含的通用工具。若需更強大、更專業的功能，請繼續閱讀各個元件的詳細文件。
-
-有關使用靈活的 `Icon` 元件的全面指南，請參閱下一節。
-- **[圖示](./components-utilities-icon.md)**

package/docs/components-utilities.zh.md

@@ -1,136 +0,0 @@
-# 工具
-
-本节提供了关于一系列辅助组件、高阶组件 (HOC) 和实用函数的文档。这些工具旨在简化常见的开发任务、管理应用程序主题和处理复杂的数据结构。
-
-可用的主要工具有：
-
-<x-cards data-columns="2">
-  <x-card data-title="Icon 组件" data-icon="lucide:image" data-href="/components/utilities/icon">
-    一个多功能组件，用于显示来自各种来源的图标，包括 Iconify、图片 URL 或字母头像。
-  </x-card>
-  <x-card data-title="OverridableThemeProvider" data-icon="lucide:palette">
-    一个主题提供程序，允许开发者提供自己的主题对象来覆盖默认的 Blocklet UI 主题。
-  </x-card>
-  <x-card data-title="withHideWhenEmbed HOC" data-icon="lucide:eye-off">
-    一个高阶组件，可有条件地渲染组件，在应用程序处于嵌入模式时将其隐藏。
-  </x-card>
-  <x-card data-title="JavaScript 辅助函数" data-icon="lucide:function-square">
-    一套用于执行递归数组操作、URL 验证和路径匹配等任务的独立函数。
-  </x-card>
-</x-cards>
-
-有关 `Icon` 组件的详细指南，请参阅其专门的文档页面。其他工具的文档如下。
-
-## OverridableThemeProvider
-
-该组件是 Material-UI `ThemeProvider` 的一个包装器。它允许您将一致的主题应用于其子组件。默认情况下，它使用标准的 Blocklet UI 主题，但您可以通过 `theme` 属性提供一个自定义主题对象来覆盖默认样式。
-
-### 用法
-
-要应用自定义主题，请将一个主题对象传递给 `theme` 属性。该组件会将您的覆盖项与默认主题合并。
-
-```javascript Theme Provider Example icon=logos:javascript
-import OverridableThemeProvider from '@blocklet/ui-react/lib/common/overridable-theme-provider';
-import { Button } from '@mui/material';
-
-const customTheme = {
-  palette: {
-    primary: {
-      main: '#ff5722',
-    },
-  },
-};
-
-function App() {
-  return (
-    <OverridableThemeProvider theme={customTheme}>
-      <Button color="primary" variant="contained">
-        Custom Themed Button
-      </Button>
-    </OverridableThemeProvider>
-  );
-}
-```
-
-## withHideWhenEmbed
-
-`withHideWhenEmbed` 是一个高阶组件 (HOC)，如果应用程序处于“嵌入模式”，它会阻止组件渲染。它会检查一个会话存储键 (`EMBED_MODE_KEY`) 来确定当前模式。如果值为 `1`，被包装的组件将返回 `null`。
-
-这在嵌入式上下文中非常有用，可以隐藏不需要的元素，如页眉或页脚。
-
-### 用法
-
-用 `withHideWhenEmbed` HOC 包装您希望有条件隐藏的组件。
-
-```javascript HOC Example icon=logos:javascript
-import withHideWhenEmbed from '@blocklet/ui-react/lib/libs/with-hide-when-embed';
-
-function PageHeader() {
-  return (
-    <header>
-      <h1>My Application</h1>
-    </header>
-  );
-}
-
-const MaybeHiddenHeader = withHideWhenEmbed(PageHeader);
-
-function App() {
-  return (
-    <div>
-      <MaybeHiddenHeader />
-      <main>
-        {/* 主内容放在这里 */}
-      </main>
-    </div>
-  );
-}
-```
-
-## 辅助函数
-
-提供了一组纯 JavaScript 函数，用于常见的数据操作和验证任务。这些函数可以直接从库的实用工具模块中导入。
-
-### 数组操作
-
-这些函数设计用于处理嵌套对象的数组，例如导航菜单或文件树。
-
-| 函数 | 描述 |
-| --- | --- |
-| `mapRecursive(array, fn, childrenKey = 'children')` | 递归地将一个函数应用于嵌套数组中的每一项。 |
-| `flatRecursive(array, childrenKey = 'children')` | 将嵌套数组扁平化为单层数组。 |
-| `countRecursive(array, childrenKey = 'children')` | 计算嵌套数组中项目的总数。 |
-| `filterRecursive(array, predicate, childrenKey = 'children')` | 根据谓词函数递归过滤嵌套数组，如果子项匹配，则保留父结构。 |
-
-### 字符串和 URL 验证
-
-用于检查字符串格式的简单辅助函数。
-
-| 函数 | 描述 |
-| --- | --- |
-| `isUrl(str)` | 如果字符串以 `http://` 或 `https://` 开头，则返回 `true`。 |
-| `isMailProtocol(str)` | 如果字符串以 `mailto:` 开头，则返回 `true`。 |
-
-### 路由
-
-用于辅助客户端路由逻辑的工具。
-
-| 函数 | 描述 |
-| --- | --- |
-| `matchPath(path)` | 检查给定路径是否与当前的 `window.location.pathname` 匹配。 |
-| `matchPaths(paths)` | 从一个路径数组中找到与当前位置最佳匹配的路径。 |
-
-### 布局
-
-| 函数 | 描述 |
-| --- | --- |
-| `splitNavColumns(items, options)` | 将导航项列表拆分为指定数量的列，可用于创建大型菜单。 |
-
----
-
-### 总结
-
-本节概述了库中包含的通用工具。要了解更强大、更专业的功能，请继续阅读各个组件的详细文档。
-
-有关使用灵活的 `Icon` 组件的全面指南，请参阅下一节。
-- **[Icon](./components-utilities-icon.md)**

package/docs/components.ja.md

@@ -1,27 +0,0 @@
-# コンポーネント
-
-このセクションでは、Blocklet UI React ライブラリで利用可能なすべてのUIコンポーネントに関する包括的なリファレンスを提供します。各コンポーネントには、アプリケーションへのスムーズな統合を保証するために、そのプロパティ（props）、実践的な使用例、およびベストプラクティスが記載されています。
-
-コンポーネントは、ナビゲーションと検索を容易にするために、論理的なカテゴリに分類されています。以下のカテゴリを選択して、その中のコンポーネントをご覧ください。
-
-<x-cards data-columns="3">
-  <x-card data-title="レイアウト" data-icon="lucide:layout-template" data-href="/components/layout">
-    Header、Footer、Dashboard のような、blocklet アプリケーションの主要な構造を形成するプライマリコンポーネント。
-  </x-card>
-  <x-card data-title="ユーザー管理" data-icon="lucide:users" data-href="/components/user-management">
-    ユーザープロファイル、セッション管理、組織の切り替えを処理するための一連のコンポーネント。
-  </x-card>
-  <x-card data-title="コンポーネント管理" data-icon="lucide:package" data-href="/components/component-management">
-    アプリケーション内で blocklet コンポーネントを動的にインストール、公開、管理するためのツール。
-  </x-card>
-  <x-card data-title="通知" data-icon="lucide:bell" data-href="/components/notifications">
-    リアルタイムのユーザー通知システムを実装するためのコンポーネントとユーティリティを提供します。
-  </x-card>
-  <x-card data-title="ユーティリティ" data-icon="lucide:wrench" data-href="/components/utilities">
-    多用途なアイコンコンポーネントやテーマプロバイダーなど、ヘルパーコンポーネントとユーティリティのコレクション。
-  </x-card>
-</x-cards>
-
----
-
-アプリケーションの構造の構築を開始するには、[レイアウトコンポーネント](./components-layout.md) セクションに進んでください。

package/docs/components.md

@@ -1,27 +0,0 @@
-# Components
-
-This section provides a comprehensive reference for all available UI components in the Blocklet UI React library. Each component is documented with its properties (props), practical usage examples, and best practices to ensure seamless integration into your application.
-
-The components are organized into logical categories to facilitate navigation and discovery. Select a category below to explore the components within it.
-
-<x-cards data-columns="3">
-  <x-card data-title="Layout" data-icon="lucide:layout-template" data-href="/components/layout">
-    Primary components like Header, Footer, and Dashboard that form the main structure of a blocklet application.
-  </x-card>
-  <x-card data-title="User Management" data-icon="lucide:users" data-href="/components/user-management">
-    A suite of components for handling user profiles, session management, and organization switching.
-  </x-card>
-  <x-card data-title="Component Management" data-icon="lucide:package" data-href="/components/component-management">
-    Tools for dynamically installing, publishing, and managing blocklet components within an application.
-  </x-card>
-  <x-card data-title="Notifications" data-icon="lucide:bell" data-href="/components/notifications">
-    Provides components and utilities for implementing a real-time user notification system.
-  </x-card>
-  <x-card data-title="Utilities" data-icon="lucide:wrench" data-href="/components/utilities">
-    A collection of helper components and utilities, such as a versatile Icon component and theme providers.
-  </x-card>
-</x-cards>
-
----
-
-To begin building your application's structure, proceed to the [Layout Components](./components-layout.md) section.

package/docs/components.zh-TW.md

@@ -1,27 +0,0 @@
-# 元件
-
-本節為 Blocklet UI React 函式庫中所有可用的 UI 元件提供了詳盡的參考文件。每個元件都附有其屬性（props）、實際用法範例和最佳實踐的說明，以確保能順利地整合到您的應用程式中。
-
-元件被組織成邏輯分類，以便於導覽和查找。請在下方選擇一個類別，以探索其中的元件。
-
-<x-cards data-columns="3">
-  <x-card data-title="版面配置" data-icon="lucide:layout-template" data-href="/components/layout">
-    像 Header、Footer 和 Dashboard 這樣構成 blocklet 應用程式主要結構的核心元件。
-  </x-card>
-  <x-card data-title="使用者管理" data-icon="lucide:users" data-href="/components/user-management">
-    一套用於處理使用者個人資料、會話管理和組織切換的元件。
-  </x-card>
-  <x-card data-title="元件管理" data-icon="lucide:package" data-href="/components/component-management">
-    用於在應用程式中動態安裝、發布和管理 blocklet 元件的工具。
-  </x-card>
-  <x-card data-title="通知" data-icon="lucide:bell" data-href="/components/notifications">
-    提供用於實作即時使用者通知系統的元件和工具程式。
-  </x-card>
-  <x-card data-title="工具程式" data-icon="lucide:wrench" data-href="/components/utilities">
-    一系列輔助元件和工具程式，例如多功能的圖示元件和主題提供者。
-  </x-card>
-</x-cards>
-
----
-
-若要開始建構您的應用程式結構，請前往 [版面配置元件](./components-layout.md) 章節。

package/docs/components.zh.md

@@ -1,27 +0,0 @@
-# 组件
-
-本节为 Blocklet UI React 库中所有可用的 UI 组件提供了全面的参考文档。每个组件都附有其属性 (props)、实际使用示例和最佳实践的文档，以确保能无缝集成到您的应用程序中。
-
-这些组件按逻辑类别进行组织，以方便导航和查找。请在下方选择一个类别，以浏览其中的组件。
-
-<x-cards data-columns="3">
-  <x-card data-title="布局" data-icon="lucide:layout-template" data-href="/components/layout">
-    构成 Blocklet 应用主要结构的主要组件，例如 Header、Footer 和 Dashboard。
-  </x-card>
-  <x-card data-title="用户管理" data-icon="lucide:users" data-href="/components/user-management">
-    一套用于处理用户个人资料、会话管理和组织切换的组件。
-  </x-card>
-  <x-card data-title="组件管理" data-icon="lucide:package" data-href="/components/component-management">
-    用于在应用程序内动态安装、发布和管理 Blocklet 组件的工具。
-  </x-card>
-  <x-card data-title="通知" data-icon="lucide:bell" data-href="/components/notifications">
-    提供用于实现实时用户通知系统的组件和实用工具。
-  </x-card>
-  <x-card data-title="实用工具" data-icon="lucide:wrench" data-href="/components/utilities">
-    一系列辅助组件和实用工具，例如多功能的图标组件和主题提供程序。
-  </x-card>
-</x-cards>
-
----
-
-要开始构建您的应用结构，请前往 [布局组件](./components-layout.md) 部分。

package/docs/core-concepts.ja.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.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)セクションを参照してください。