@blocklet/ui-react 3.1.48 → 3.1.49

package/docs/components-utilities.ja.md

@@ -0,0 +1,136 @@
+# ユーティリティ
+
+このセクションでは、ヘルパーコンポーネント、高階コンポーネント (HOC)、およびユーティリティ関数のコレクションに関するドキュメントを提供します。これらのツールは、一般的な開発タスクを簡素化し、アプリケーションのテーマを管理し、複雑なデータ構造を処理するように設計されています。
+
+利用可能な主なユーティリティは次のとおりです。
+
+<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 テーマプロバイダーの例 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 の例 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>
+  );
+}
+```
+
+## ヘルパー関数
+
+一般的なデータ操作および検証タスクのために、一連の純粋な 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.md

@@ -0,0 +1,136 @@
+# 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

@@ -0,0 +1,136 @@
+# 工具
+
+本節提供了一系列輔助元件、高階元件 (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

@@ -0,0 +1,136 @@
+# 工具
+
+本节提供了关于一系列辅助组件、高阶组件 (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

@@ -0,0 +1,27 @@
+# コンポーネント
+
+このセクションでは、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

@@ -0,0 +1,27 @@
+# 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

@@ -0,0 +1,27 @@
+# 元件
+
+本節為 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

@@ -0,0 +1,27 @@
+# 组件
+
+本节为 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) 部分。