@blocklet/ui-react 3.1.48 → 3.1.50

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

@@ -0,0 +1,231 @@
+# Dashboard
+
+`Dashboard` 元件為 blocklet 應用程式提供了一個預先建置、響應式的佈局，通常用於管理介面或以使用者為中心的視圖。它透過解析 blocklet 的元資料，自動建構一個包含側邊欄、頁首和主要內容區域的標準儀表板。此元件顯著減少了建構通用應用程式結構所需的樣板程式碼。
+
+該佈局由三個主要部分組成：一個用於導覽的常駐側邊欄、一個用於全域操作和使用者資訊的頁首，以及一個呈現特定頁面內容的主要內容區域。
+
+```d2
+direction: down
+
+Dashboard-Layout: {
+  label: "Dashboard 元件"
+  shape: rectangle
+  grid-columns: 1
+  style: {
+    stroke: "#888"
+    stroke-width: 2
+    stroke-dash: 4
+  }
+
+  Header: {
+    shape: rectangle
+    Logo: {}
+    HeaderAddons: {
+      label: "頁首附加元件"
+      shape: rectangle
+      grid-columns: 1
+      SessionManager: {}
+      LocaleSelector: {}
+      ThemeToggle: {}
+    }
+  }
+
+  Sidebar: {
+    label: "側邊欄"
+    shape: rectangle
+    Navigation-Links: {
+      label: "導覽連結"
+      shape: rectangle
+    }
+  }
+
+  Content-Area: {
+    label: "內容區域"
+    shape: rectangle
+    "頁面特定內容 (children)"
+  }
+}
+
+Blocklet-Metadata: {
+  label: "blocklet.yml"
+  shape: cylinder
+}
+
+Blocklet-Metadata -> Dashboard-Layout.Sidebar.Navigation-Links: "生成"
+```
+
+## 基本用法
+
+若要使用 `Dashboard` 元件，只需將您的頁面內容包裹在其中即可。該元件將自動在您的內容周圍呈現頁首和側邊欄。
+
+```javascript MyDashboard.jsx icon=logos:react
+import Dashboard from '@arcblock/blocklet-ui-react/lib/Dashboard';
+
+export default function MyDashboardPage() {
+  return (
+    <Dashboard>
+      <h1>Welcome to the Dashboard</h1>
+      <p>This is your main content area.</p>
+    </Dashboard>
+  );
+}
+```
+
+傳遞給 `Dashboard` 元件的 children 將顯示在主要內容區域中。
+
+## 屬性 (Props)
+
+`Dashboard` 元件接受以下屬性 (props) 以自訂其行為和外觀。
+
+<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` 元件的 props。這允許自訂使用者會話選單，例如 `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" />;
+        // Add the custom button before the other addons
+        return [customAddon, ...existingAddons];
+      }}
+    >
+      <p>Dashboard with a custom header button.</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>This dashboard may have dynamic links.</p>
+    </Dashboard>
+  );
+}
+
+```
+
+## 總結
+
+`Dashboard` 元件是快速建構應用程式佈局的強大工具。透過利用 blocklet 元資料，它提供了一個開箱即用的、具備角色感知能力的結構化導覽系統。若需更基礎的佈局元件，請參閱 [Header](./components-layout-header.md) 和 [Footer](./components-layout-footer.md) 的文件。

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

@@ -0,0 +1,231 @@
+# Dashboard
+
+`Dashboard` 组件为 blocklet 应用程序提供了一个预构建的响应式布局，通常用于管理界面或以用户为中心的视图。它通过解析 blocklet 的元数据，自动构建一个包含侧边栏、头部和主内容区域的标准仪表盘。该组件显著减少了构建常见应用程序结构的样板代码。
+
+该布局由三个主要部分组成：一个用于导航的持久侧边栏，一个用于全局操作和用户信息的头部，以及一个渲染特定页面内容的主内容区域。
+
+```d2
+direction: down
+
+Dashboard-Layout: {
+  label: "Dashboard 组件"
+  shape: rectangle
+  grid-columns: 1
+  style: {
+    stroke: "#888"
+    stroke-width: 2
+    stroke-dash: 4
+  }
+
+  Header: {
+    shape: rectangle
+    Logo: {}
+    HeaderAddons: {
+      label: "Header 附加组件"
+      shape: rectangle
+      grid-columns: 1
+      SessionManager: {}
+      LocaleSelector: {}
+      ThemeToggle: {}
+    }
+  }
+
+  Sidebar: {
+    label: "侧边栏"
+    shape: rectangle
+    Navigation-Links: {
+      label: "导航链接"
+      shape: rectangle
+    }
+  }
+
+  Content-Area: {
+    label: "内容区域"
+    shape: rectangle
+    "特定页面的内容 (children)"
+  }
+}
+
+Blocklet-Metadata: {
+  label: "blocklet.yml"
+  shape: cylinder
+}
+
+Blocklet-Metadata -> Dashboard-Layout.Sidebar.Navigation-Links: "生成"
+```
+
+## 基本用法
+
+要使用 `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

@@ -0,0 +1,165 @@
+# 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) を参照してください。