@blocklet/ui-react 3.4.14 → 3.5.0

package/docs/components-layout-dashboard.zh.md

@@ -1,185 +0,0 @@
-# Dashboard
-
-`Dashboard` 组件为 blocklet 应用程序提供了一个预构建的响应式布局，通常用于管理界面或以用户为中心的视图。它通过解析 blocklet 的元数据，自动构建一个包含侧边栏、头部和主内容区域的标准仪表盘。该组件显著减少了构建常见应用程序结构的样板代码。
-
-该布局由三个主要部分组成：一个用于导航的持久侧边栏，一个用于全局操作和用户信息的头部，以及一个渲染特定页面内容的主内容区域。
-
-<!-- DIAGRAM_IMAGE_START:architecture:16:9:1765962229 -->
-![Dashboard](assets/diagram/dashboard-diagram-0.zh.jpg)
-<!-- DIAGRAM_IMAGE_END -->
-
-## 基本用法
-
-要使用 `Dashboard` 组件，只需用它包裹页面内容即可。该组件将自动在您的内容周围渲染头部和侧边栏。
-
-```javascript MyDashboard.jsx icon=logos:react
-import Dashboard from '@arcblock/blocklet-ui-react/lib/Dashboard';
-
-export default function MyDashboardPage() {
-  return (
-    <Dashboard>
-      <h1>欢迎来到 Dashboard</h1>
-      <p>这是您的主内容区域。</p>
-    </Dashboard>
-  );
-}
-```
-
-传递给 `Dashboard` 组件的子元素将显示在主内容区域。
-
-## 属性
-
-`Dashboard` 组件接受以下属性以自定义其行为和外观。
-
-<x-field-group>
-  <x-field data-name="children" data-type="React.ReactNode" data-required="true">
-    <x-field-desc markdown>要在仪表盘布局的主内容区域内渲染的内容。</x-field-desc>
-  </x-field>
-  <x-field data-name="meta" data-type="object" data-required="false">
-    <x-field-desc markdown>一个 blocklet 元数据对象。如果提供，它将与默认的 `window.blocklet` 元数据合并并覆盖后者。这对于测试或动态更改 blocklet 信息非常有用。</x-field-desc>
-  </x-field>
-  <x-field data-name="fallbackUrl" data-type="string" data-required="false" data-default="publicPath">
-    <x-field-desc markdown>如果当前已认证用户根据其角色无权访问任何导航链接，则重定向到此 URL。设置为 `null` 可禁用此自动重定向。</x-field-desc>
-  </x-field>
-  <x-field data-name="invalidPathFallback" data-type="function" data-required="false">
-    <x-field-desc markdown>当当前 URL 路径与任何可用的导航链接都不匹配时执行的回调函数。默认行为是重定向到第一个可用的链接。</x-field-desc>
-  </x-field>
-  <x-field data-name="headerAddons" data-type="React.ReactNode | function" data-required="false">
-    <x-field-desc markdown>允许自定义头部右侧的附加组件。如果提供一个节点，它将替换所有默认的附加组件。如果提供一个函数，它会接收默认附加组件数组作为参数，允许您添加、删除或重新排序它们。</x-field-desc>
-  </x-field>
-  <x-field data-name="sessionManagerProps" data-type="object" data-required="false">
-    <x-field-desc markdown>要直接传递给头部底层 `SessionUser` 组件的属性。这允许自定义用户会话菜单，例如 `showRole` 或定义自定义的 `onLogout` 处理程序。</x-field-desc>
-  </x-field>
-  <x-field data-name="links" data-type="array | function" data-required="false">
-    <x-field-desc markdown>允许以编程方式修改侧边栏导航链接。如果提供一个数组，其项目将附加到从元数据生成的链接后面。如果提供一个函数，它将接收元数据生成的链接作为参数，并应返回一个新的链接数组。</x-field-desc>
-  </x-field>
-  <x-field data-name="showDomainWarningDialog" data-type="boolean" data-required="false" data-default="true">
-    <x-field-desc markdown>如果为 `true`，当应用程序从不受信任的域访问时，将显示一个警告对话框。</x-field-desc>
-  </x-field>
-</x-field-group>
-
-## 工作原理
-
-`Dashboard` 组件被设计为“配置驱动”，其结构和内容主要来源于 blocklet 的元数据文件（`blocklet.yml`）。
-
-### 从元数据生成导航
-
-侧边栏导航是根据 `blocklet.yml` 中的 `navigation` 数组自动生成的。该组件专门查找其 `section` 属性中包含 `dashboard` 的导航项。
-
-以下是如何定义仪表盘导航的示例：
-
-```yaml blocklet.yml icon=mdi:file-document
-navigation:
-  - title: 'Home'
-    link: '/'
-    section: 'dashboard'
-    icon: 'mdi:home'
-    role: ['owner', 'admin', 'guest']
-  - title: 'Analytics'
-    link: '/analytics'
-    section: 'dashboard'
-    icon: 'mdi:chart-bar'
-    role: ['owner', 'admin']
-  - title: 'Settings'
-    link: '/settings'
-    section: 'dashboard'
-    icon: 'mdi:cog'
-    role: ['owner']
-    items:
-      - title: 'Profile'
-        link: '/settings/profile'
-      - title: 'Billing'
-        link: '/settings/billing'
-```
-
-### 基于角色的访问控制
-
-`Dashboard` 组件对导航链接实施基于角色的访问控制（RBAC）。每个导航项可以有一个 `role` 属性，这是一个允许查看该链接的角色数组。
-
-- 如果导航项没有 `role` 属性，则对所有人可见。
-- 如果当前用户未认证，他们只能看到包含 `guest` 角色的项目。
-- 如果当前用户已认证，组件会将其 `user.role` 与每个导航项的 `role` 数组进行比较。只有在匹配的情况下，该项目才会显示。
-- 只有当父导航项至少有一个子项可见时，父导航项本身才可见。
-
-使用上面的 `blocklet.yml` 示例：
-- 具有 `guest` 角色的用户将只看到“Home”链接。
-- 具有 `admin` 角色的用户将看到“Home”和“Analytics”。
-- 具有 `owner` 角色的用户将看到所有链接，包括“Settings”下的嵌套链接“Profile”和“Billing”。
-
-### 图标
-
-导航项的 `icon` 属性应该是一个字符串，对应于 [Iconify](https://icon-sets.iconify.design/) 库中的图标名称（例如，`mdi:home`）。您也可以提供一个指向图像文件的完整 URL。
-
-## 自定义
-
-虽然 `Dashboard` 被设计为可以与元数据开箱即用，但它也提供了几个属性用于更高级的自定义。
-
-### 自定义头部附加组件
-
-您可以使用 `headerAddons` 属性修改默认的头部附加组件（例如，主题切换器、区域设置选择器、会话管理器）。通过传递一个函数，您可以添加新元素或重新排列现有元素。
-
-```javascript CustomHeader.jsx icon=logos:react
-import Dashboard from '@arcblock/blocklet-ui-react/lib/Dashboard';
-import Button from '@mui/material/Button';
-
-function MyCustomButton() {
-  return <Button color="inherit" onClick={() => alert('Help!')}>Help</Button>;
-}
-
-export default function CustomDashboard() {
-  return (
-    <Dashboard
-      headerAddons={(existingAddons) => {
-        const customAddon = <MyCustomButton key="custom-help" />;
-        // 将自定义按钮添加到其他附加组件之前
-        return [customAddon, ...existingAddons];
-      }}
-    >
-      <p>带有自定义头部按钮的 Dashboard。</p>
-    </Dashboard>
-  );
-}
-```
-
-### 以编程方式添加链接
-
-`links` 属性允许您通过代码动态添加或修改侧边栏导航链接。这对于依赖于应用程序状态的链接非常有用。
-
-```javascript DynamicLinks.jsx icon=logos:react
-import Dashboard from '@arcblock/blocklet-ui-react/lib/Dashboard';
-import Icon from '@arcblock/ux/lib/Icon';
-
-const useFeatureFlag = () => {
-  // 在实际应用中，这里会检查功能开关服务
-  return true;
-};
-
-export default function DynamicDashboard() {
-  const isBetaFeatureEnabled = useFeatureFlag();
-
-  return (
-    <Dashboard
-      links={(existingLinks) => {
-        if (isBetaFeatureEnabled) {
-          const betaLink = {
-            id: 'beta-feature',
-            title: 'Beta Feature',
-            url: '/beta',
-            icon: <Icon name="mdi:test-tube" />,
-            external: true, // 客户端路由所需
-          };
-          return [...existingLinks, betaLink];
-        }
-        return existingLinks;
-      }}
-    >
-      <p>此仪表盘可能包含动态链接。</p>
-    </Dashboard>
-  );
-}
-
-```
-
-## 总结
-
-`Dashboard` 组件是快速搭建应用程序布局的强大工具。通过利用 blocklet 元数据，它提供了一个结构化、具备角色感知能力的开箱即用的导航系统。有关更基础的布局组件，请参阅 [Header](./components-layout-header.md) 和 [Footer](./components-layout-footer.md) 的文档。

package/docs/components-layout-footer.ja.md

@@ -1,165 +0,0 @@
-# Footer
-
-`Footer` コンポーネントは、アプリケーションに標準化されたレスポンシブなフッターを提供します。blocklet のメタデータを読み取ることで、ブランディング、ナビゲーションリンク、ソーシャルメディアアイコン、著作権情報などのコンテンツを自動的に入力します。このデータ駆動型のアプローチにより、一貫性が確保され、設定が簡素化されます。
-
-このコンポーネントはレスポンシブに設計されており、さまざまな画面サイズに合わせてレイアウトを調整します。また、アプリケーションが埋め込みモードで実行されている場合に自身を非表示にするロジックが組み込まれており、統合時にクリーンなユーザーインターフェースを保証します。
-
-## 基本的な使用方法
-
-アプリケーションにフッターを追加するには、`Footer` コンポーネントをインポートしてレンダリングするだけです。グローバルな `window.blocklet` オブジェクトから自動的にデータを取得するため、基本的な使用には props は必要ありません。
-
-```jsx 使用例 icon=logos:react
-import React from 'react';
-import { Footer } from '@blocklet/ui-react';
-
-export default function App() {
-  return (
-    <div style={{ minHeight: '100vh', display: 'flex', flexDirection: 'column' }}>
-      <main style={{ flex: 1 }}>
-        {/* ここにアプリケーションのコンテンツを記述します */}
-      </main>
-      <Footer />
-    </div>
-  );
-}
-```
-
-## Props
-
-`Footer` コンポーネントは、以下の props を通じてカスタマイズできます。
-
-<x-field-group>
-  <x-field data-name="meta" data-type="object" data-required="false">
-    <x-field-desc markdown>
-      blocklet のメタデータを含むオブジェクト。この prop を使用して、デフォルトの `window.blocklet` 設定を上書きしたり、グローバルオブジェクトが利用できない環境でデータを提供したりします。構造は blocklet のメタデータ形式と一致する必要があります。
-    </x-field-desc>
-  </x-field>
-  <x-field data-name="theme" data-type="object" data-required="false">
-    <x-field-desc markdown>
-      フッターの外観をカスタマイズするためのテーマオブジェクト。このオブジェクトはアプリケーションのデフォルトテーマと深くマージされ、色、フォント、スペーシングなどの特定のスタイルを上書きできます。
-    </x-field-desc>
-  </x-field>
-</x-field-group>
-
-## メタデータの設定
-
-`Footer` のコンテンツは、主に blocklet のメタデータファイル (`blocklet.yml`) を通じて設定されます。コンポーネントは、このファイルから特定のフィールドを読み取り、さまざまなセクションをレンダリングします。
-
-以下は、フッターのすべてのセクションにデータを入力する `blocklet.yml` 設定の例です。
-
-```yaml blocklet.yml
-name: my-app
-title: My App
-description: A detailed description of my application that appears in the footer.
-copyright: 'My Company Inc.'
-
-# ナビゲーションリンクはグループに構造化されています
-navigation:
-  # メインフッターナビゲーション、グルーピングのために2つのレベルをサポート
-  footer:
-    - title: 'Products'
-      items:
-        - title: 'Product A'
-          link: '/products/a'
-        - title: 'Product B'
-          link: '/products/b'
-    - title: 'Resources'
-      items:
-        - title: 'Documentation'
-          link: '/docs'
-        - title: 'Blog'
-          link: '/blog'
-
-  # ソーシャルメディアリンク
-  social:
-    - title: 'twitter' # アイコンはタイトルから推測されます（例：'twitter'、'github'）
-      link: 'https://twitter.com/your-handle'
-    - title: 'github'
-      icon: 'mdi:github' # Iconify のアイコン名を指定することもできます
-      link: 'https://github.com/your-org'
-
-  # ボトムリンク、通常は法的情報やプライバシー情報用
-  bottom:
-    - title: 'Privacy Policy'
-      link: '/privacy'
-    - title: 'Terms of Service'
-      link: '/terms'
-```
-
-### データ構造
-
-メタデータ内の `navigation` オブジェクトは、フッターに表示されるリンクを定義します。これは `footer`、`social`、`bottom` の3つの異なるセクションに整理されています。
-
-<x-field-group>
-  <x-field data-name="navigation" data-type="object">
-    <x-field-desc markdown>
-      アプリケーションのすべてのナビゲーション構造を含みます。
-    </x-field-desc>
-    <x-field data-name="footer" data-type="array">
-      <x-field-desc markdown>
-        メインフッターナビゲーションエリアのリンクグループの配列。2階層の階層をサポートします。
-      </x-field-desc>
-      <x-field data-name="[].title" data-type="string" data-required="true" data-desc="ナビゲーショングループのタイトル（例：'Products'）。"></x-field>
-      <x-field data-name="[].link" data-type="string" data-required="false" data-desc="グループタイトル自体のためのオプションのリンク。"></x-field>
-      <x-field data-name="[].items" data-type="array" data-required="false" data-desc="子ナビゲーションリンクの配列。">
-        <x-field data-name="[].title" data-type="string" data-required="true" data-desc="リンクの表示テキスト。"></x-field>
-        <x-field data-name="[].link" data-type="string" data-required="true" data-desc="ナビゲーションリンクのURL。"></x-field>
-      </x-field>
-    </x-field>
-    <x-field data-name="social" data-type="array">
-      <x-field-desc markdown>
-        ソーシャルメディアプロフィールへのリンクの配列。
-      </x-field-desc>
-      <x-field data-name="[].title" data-type="string" data-required="true" data-desc="ソーシャルメディアプラットフォームの名前。アイコンを推測するために使用されます（例：'twitter'）。"></x-field>
-      <x-field data-name="[].icon" data-type="string" data-required="false" data-desc="Iconify 文字列（例：`mdi:github`）を使用してアイコンを明示的に指定します。推測されたアイコンを上書きします。"></x-field>
-      <x-field data-name="[].link" data-type="string" data-required="true" data-desc="ソーシャルメディアプロフィールへのURL。"></x-field>
-    </x-field>
-    <x-field data-name="bottom" data-type="array">
-      <x-field-desc markdown>
-        フッターの最下部に表示されるリンクの配列。通常は法的通知用です。
-      </x-field-desc>
-      <x-field data-name="[].title" data-type="string" data-required="true" data-desc="リンクの表示テキスト（例：'Privacy Policy'）。"></x-field>
-      <x-field data-name="[].link" data-type="string" data-required="true" data-desc="リンクのURL。"></x-field>
-    </x-field>
-  </x-field>
-</x-field-group>
-
-## レイアウト
-
-`Footer` コンポーネントは、提供されたデータに基づいて最も適切なレイアウトを賢く選択します。これにより、さまざまなユースケースでクリーンで機能的な表示が保証されます。
-
--   **標準レイアウト**: このレイアウトは、メタデータに `footer` ナビゲーションリンクまたは `social` メディアリンクが定義されている場合に自動的に有効になります。ブランド情報、ソーシャルアイコン、ナビゲーションカラムをエレガントに整理するマルチセクションデザインが特徴です。モバイルデバイスでは、ナビゲーショングループは折りたたみ可能なアコーディオンになり、より良いユーザーエクスペリエンスを提供します。
-
--   **プレーンレイアウト**: `footer` または `social` リンクが提供されていない場合、コンポーネントは簡素化された単一行のレイアウトにフォールバックします。これは、「利用規約」や「プライバシーポリシー」などの著作権表示といくつかの必須リンクのみを必要とするアプリケーションに最適です。
-
-## テーマ設定
-
-`theme` オブジェクトを渡すことで、フッターの外観をカスタマイズできます。このオブジェクトは既存のテーマと深くマージされ、特定のオーバーライドが可能です。
-
-```jsx カスタムテーマの例 icon=logos:react
-import { Footer } from '@blocklet/ui-react';
-
-const customTheme = {
-  palette: {
-    background: {
-      default: '#2c3e50', // フッター用のより暗い背景
-    },
-    text: {
-      primary: '#ecf0f1',
-      secondary: '#bdc3c7',
-    },
-    divider: '#34495e',
-  },
-};
-
-// ... コンポーネントの render メソッド内
-<Footer theme={customTheme} bordered />;
-```
-
-## 埋め込みモードでの動作
-
-`Footer` コンポーネントは、アプリケーションが埋め込みコンテキストでレンダリングされる際に自動的に非表示にする高階コンポーネント (`withHideWhenEmbed`) でラップされています。この動作は、セッションストレージキー `EMBED_MODE_KEY` によって制御されます。このキーが `1` に設定されている場合、フッターはレンダリングされません。これは、blocklet が別のアプリケーション内で表示される際に、冗長なフッターを防ぐのに役立ちます。
-
----
-
-blocklet メタデータを通じて設定されるヘッダーコンポーネントに関する情報については、[Header ドキュメント](./components-layout-header.md) を参照してください。

package/docs/components-layout-footer.md

@@ -1,165 +0,0 @@
-# Footer
-
-The `Footer` component provides a standardized, responsive footer for your application. It automatically populates its content—including branding, navigation links, social media icons, and copyright information—by reading your blocklet's metadata. This data-driven approach ensures consistency and simplifies configuration.
-
-The component is designed to be responsive, adapting its layout for different screen sizes. It also includes built-in logic to hide itself when the application is running in an embedded mode, ensuring a clean user interface in integrations.
-
-## Basic Usage
-
-To add a footer to your application, simply import and render the `Footer` component. It requires no props for basic use, as it automatically sources data from the global `window.blocklet` object.
-
-```jsx Usage Example icon=logos:react
-import React from 'react';
-import { Footer } from '@blocklet/ui-react';
-
-export default function App() {
-  return (
-    <div style={{ minHeight: '100vh', display: 'flex', flexDirection: 'column' }}>
-      <main style={{ flex: 1 }}>
-        {/* Your application content goes here */}
-      </main>
-      <Footer />
-    </div>
-  );
-}
-```
-
-## Props
-
-The `Footer` component can be customized through the following props.
-
-<x-field-group>
-  <x-field data-name="meta" data-type="object" data-required="false">
-    <x-field-desc markdown>
-      An object containing blocklet metadata. Use this prop to override the default `window.blocklet` configuration or to provide data in environments where the global object is not available. The structure should match the blocklet metadata format.
-    </x-field-desc>
-  </x-field>
-  <x-field data-name="theme" data-type="object" data-required="false">
-    <x-field-desc markdown>
-      A theme object to customize the footer's appearance. This object is deeply merged with the application's default theme, allowing you to override specific styles like colors, fonts, and spacing.
-    </x-field-desc>
-  </x-field>
-</x-field-group>
-
-## Metadata Configuration
-
-The content of the `Footer` is primarily configured through the blocklet's metadata file (`blocklet.yml`). The component reads specific fields from this file to render its different sections.
-
-Below is an example of a `blocklet.yml` configuration that populates all sections of the footer.
-
-```yaml blocklet.yml
-name: my-app
-title: My App
-description: A detailed description of my application that appears in the footer.
-copyright: 'My Company Inc.'
-
-# Navigation links are structured into groups
-navigation:
-  # Main footer navigation, supports two levels for grouping
-  footer:
-    - title: 'Products'
-      items:
-        - title: 'Product A'
-          link: '/products/a'
-        - title: 'Product B'
-          link: '/products/b'
-    - title: 'Resources'
-      items:
-        - title: 'Documentation'
-          link: '/docs'
-        - title: 'Blog'
-          link: '/blog'
-
-  # Social media links
-  social:
-    - title: 'twitter' # Icon is inferred from the title (e.g., 'twitter', 'github')
-      link: 'https://twitter.com/your-handle'
-    - title: 'github'
-      icon: 'mdi:github' # You can also specify an Iconify icon name
-      link: 'https://github.com/your-org'
-
-  # Bottom links, typically for legal and privacy information
-  bottom:
-    - title: 'Privacy Policy'
-      link: '/privacy'
-    - title: 'Terms of Service'
-      link: '/terms'
-```
-
-### Data Structure
-
-The `navigation` object in your metadata defines the links displayed in the footer. It is organized into three distinct sections: `footer`, `social`, and `bottom`.
-
-<x-field-group>
-  <x-field data-name="navigation" data-type="object">
-    <x-field-desc markdown>
-      Contains all navigation structures for the application.
-    </x-field-desc>
-    <x-field data-name="footer" data-type="array">
-      <x-field-desc markdown>
-        An array of link groups for the main footer navigation area. Supports a two-level hierarchy.
-      </x-field-desc>
-      <x-field data-name="[].title" data-type="string" data-required="true" data-desc="The title of the navigation group (e.g., 'Products')."></x-field>
-      <x-field data-name="[].link" data-type="string" data-required="false" data-desc="An optional link for the group title itself."></x-field>
-      <x-field data-name="[].items" data-type="array" data-required="false" data-desc="An array of child navigation links.">
-        <x-field data-name="[].title" data-type="string" data-required="true" data-desc="The display text for the link."></x-field>
-        <x-field data-name="[].link" data-type="string" data-required="true" data-desc="The URL for the navigation link."></x-field>
-      </x-field>
-    </x-field>
-    <x-field data-name="social" data-type="array">
-      <x-field-desc markdown>
-        An array of links to social media profiles.
-      </x-field-desc>
-      <x-field data-name="[].title" data-type="string" data-required="true" data-desc="The name of the social media platform, used to infer the icon (e.g., 'twitter')."></x-field>
-      <x-field data-name="[].icon" data-type="string" data-required="false" data-desc="Explicitly specify an icon using an Iconify string (e.g., `mdi:github`). Overrides the inferred icon."></x-field>
-      <x-field data-name="[].link" data-type="string" data-required="true" data-desc="The URL to the social media profile."></x-field>
-    </x-field>
-    <x-field data-name="bottom" data-type="array">
-      <x-field-desc markdown>
-        An array of links displayed at the very bottom of the footer, typically for legal notices.
-      </x-field-desc>
-      <x-field data-name="[].title" data-type="string" data-required="true" data-desc="The display text for the link (e.g., 'Privacy Policy')."></x-field>
-      <x-field data-name="[].link" data-type="string" data-required="true" data-desc="The URL for the link."></x-field>
-    </x-field>
-  </x-field>
-</x-field-group>
-
-## Layouts
-
-The `Footer` component intelligently selects the most appropriate layout based on the provided data. This ensures a clean and functional presentation across different use cases.
-
--   **Standard Layout**: This layout is automatically activated when `footer` navigation links or `social` media links are defined in your metadata. It features a multi-section design that elegantly organizes the brand information, social icons, and navigation columns. On mobile devices, the navigation groups become collapsible accordions for a better user experience.
-
--   **Plain Layout**: If no `footer` or `social` links are provided, the component falls back to a simplified, single-row layout. This is ideal for applications that only require a copyright notice and a few essential links, such as "Terms of Service" or "Privacy Policy".
-
-## Theming
-
-You can customize the footer's appearance by passing a `theme` object. This object is deeply merged with the existing theme, allowing for targeted overrides.
-
-```jsx Custom Theme Example icon=logos:react
-import { Footer } from '@blocklet/ui-react';
-
-const customTheme = {
-  palette: {
-    background: {
-      default: '#2c3e50', // A darker background for the footer
-    },
-    text: {
-      primary: '#ecf0f1',
-      secondary: '#bdc3c7',
-    },
-    divider: '#34495e',
-  },
-};
-
-// ... in your component's render method
-<Footer theme={customTheme} bordered />;
-```
-
-## Behavior in Embedded Mode
-
-The `Footer` component is wrapped in a higher-order component (`withHideWhenEmbed`) that automatically hides it when the application is rendered in an embedded context. This behavior is controlled by a session storage key, `EMBED_MODE_KEY`. If this key is set to `1`, the footer will not be rendered. This is useful for preventing redundant footers when your blocklet is displayed inside another application.
-
----
-
-For information on the header component, which is also configured via blocklet metadata, please see the [Header documentation](./components-layout-header.md).