@blocklet/ui-react 3.1.47 → 3.1.49

package/docs/components-layout-footer.md

@@ -0,0 +1,165 @@
+# 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).

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

@@ -0,0 +1,165 @@
+# Footer
+
+`Footer` 元件為您的應用程式提供一個標準化、回應式的頁尾。它會透過讀取您的 blocklet 的元資料，自動填入其內容——包括品牌、導覽連結、社群媒體圖示和版權資訊。這種資料驅動的方法確保了一致性並簡化了設定。
+
+該元件被設計為回應式，能適應不同螢幕尺寸的版面配置。它還包含內建邏輯，可在應用程式以嵌入模式執行時自動隱藏，確保在整合中擁有乾淨的使用者介面。
+
+## 基本用法
+
+若要為您的應用程式新增頁尾，只需匯入並渲染 `Footer` 元件即可。基本使用時無需任何 props，因為它會自動從全域 `window.blocklet` 物件中取得資料。
+
+```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:
+  # 主要頁尾導覽，支援兩層分組
+  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`。
+
+<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>
+        主要頁尾導覽區域的連結群組陣列。支援兩層的層級結構。
+      </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`) 包裹，當應用程式在嵌入式情境中渲染時，它會自動隱藏頁尾。此行為由一個 session storage 金鑰 `EMBED_MODE_KEY` 控制。如果此金鑰被設定為 `1`，頁尾將不會被渲染。這對於防止您的 blocklet 顯示在另一個應用程式內部時出現多餘的頁尾很有用。
+
+---
+
+關於 header 元件的資訊（該元件也透過 blocklet 元資料進行設定），請參閱 [Header 文件](./components-layout-header.md)。

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

@@ -0,0 +1,165 @@
+# Footer
+
+`Footer` 组件为你的应用提供了一个标准化的、响应式的页脚。它通过读取 blocklet 的元数据来自动填充其内容——包括品牌信息、导航链接、社交媒体图标和版权信息。这种数据驱动的方法确保了一致性并简化了配置。
+
+该组件采用响应式设计，能够适应不同屏幕尺寸的布局。它还内置了逻辑，在应用以嵌入模式运行时自动隐藏，从而确保集成时用户界面的整洁。
+
+## 基本用法
+
+要为你的应用添加页脚，只需导入并渲染 `Footer` 组件即可。在基本使用中，它不需要任何 props，因为它会自动从全局 `window.blocklet` 对象中获取数据。
+
+```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 }}>
+        {/* 你的应用内容放在这里 */}
+      </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:
+  # 主页脚导航，支持两级分组
+  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`。
+
+<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>
+        用于主页脚导航区域的链接组数组。支持两级层次结构。
+      </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 Custom Theme Example 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`）包裹，当应用在嵌入式上下文中渲染时，该组件会自动隐藏 `Footer`。此行为由一个会话存储键 `EMBED_MODE_KEY` 控制。如果此键设置为 `1`，页脚将不会被渲染。这在你的 blocklet 显示在另一个应用内部时，有助于防止出现多余的页脚。
+
+---
+
+有关 `Header` 组件的信息（该组件也通过 blocklet 元数据进行配置），请参阅 [Header 文档](./components-layout-header.md)。