@blocklet/ui-react 3.1.48 → 3.1.49

package/docs/getting-started.ja.md

@@ -0,0 +1,132 @@
+# はじめに
+
+このガイドでは、`@blocklet/ui-react` ライブラリをインストールし、最初のコンポーネントをレンダリングするための手順をステップバイステップで説明します。目標は、最小限の時間でアプリケーション内に機能する `Header` と `Footer` を実装することです。
+
+## 前提条件
+
+先に進む前に、開発環境に以下がインストールされていることを確認してください：
+*   動作する React プロジェクト。
+*   Node.js とパッケージマネージャー（npm または yarn）。
+
+## インストール
+
+まず、お使いのパッケージマネージャーを使用して、`@blocklet/ui-react` パッケージをプロジェクトに追加します。
+
+npm を使用する場合:
+```bash npm
+npm install @blocklet/ui-react
+```
+
+yarn を使用する場合:
+```bash yarn
+yarn add @blocklet/ui-react
+```
+
+## 基本的な使用法: Header と Footer
+
+`Header` と `Footer` コンポーネントはシンプルに設計されており、初期設定なしでレンダリングできます。これらのコンポーネントは、blocklet のメタデータから自動的にデータを取得します。
+
+1.  `Header` と `Footer` コンポーネントをメインのアプリケーションファイル（例：`App.js`）にインポートします。
+2.  それぞれをアプリケーションのレイアウトの最上部と最下部に配置します。
+
+```jsx App.js icon=logos:react
+import React from 'react';
+import Header from '@blocklet/ui-react/lib/Header';
+import Footer from '@blocklet/ui-react/lib/Footer';
+
+function App() {
+  return (
+    <div>
+      <Header />
+      <main style={{ padding: '20px', minHeight: 'calc(100vh - 128px)' }}>
+        {/* アプリケーションのコンテンツはここに記述します */}
+        <h1>Welcome to My Blocklet</h1>
+      </main>
+      <Footer />
+    </div>
+  );
+}
+
+export default App;
+```
+
+コンポーネントは、アプリケーション名、ロゴ、ナビゲーションリンクなどの設定詳細を、Blocklet Server 環境によって注入される `window.blocklet` メタデータオブジェクトから自動的に取得します。
+
+さらに、`Header` コンポーネントは、状況に応じて追加のコントロールをインテリジェントにレンダリングします：
+*   `SessionContext` が利用可能な場合、**ユーザーセッションマネージャー**が表示されます。
+*   `LocaleContext` が利用可能な場合、**言語セレクター**が表示されます。
+
+## 手動設定
+
+開発、テスト、またはデフォルトのメタデータを上書きする必要がある場合、`blockletMeta` プロパティを使用して設定オブジェクトをコンポーネントに直接渡すことができます。
+
+```jsx App.js icon=logos:react
+import React from 'react';
+import Header from '@blocklet/ui-react/lib/Header';
+
+const customBlockletMeta = {
+  appName: 'My Custom App',
+  appLogo: 'https://path.to/your/logo.png',
+  navigation: [
+    {
+      title: 'Home',
+      link: '/',
+    },
+    {
+      title: 'Documentation',
+      link: '/docs',
+    },
+  ],
+};
+
+function App() {
+  return (
+    <div>
+      <Header blockletMeta={customBlockletMeta} />
+      {/* ... rest of your app */}
+    </div>
+  );
+}
+```
+
+このアプローチにより、グローバルな `window.blocklet` オブジェクトによって提供されるデータを上書きし、コンポーネントの外観と動作を正確に制御できます。
+
+## Header のカスタマイズ
+
+`Header` コンポーネントには右側に `addons` エリアがあり、アクションボタンやカスタムリンクなど、独自のコンポーネントを含めるようにカスタマイズできます。
+
+`addons` プロパティは、デフォルトのアドオンコンポーネントを引数として受け取る関数を受け入れます。これにより、既存のコンポーネントの前に追加したり、後ろに追加したり、完全に置き換えたりすることができます。
+
+```jsx CustomHeader.js icon=logos:react
+import React from 'react';
+import Header from '@blocklet/ui-react/lib/Header';
+import Button from '@mui/material/Button'; // Material-UI を使用した例
+
+function CustomHeader() {
+  return (
+    <Header
+      addons={existingAddons => {
+        return [
+          <Button
+            key="custom-action"
+            variant="contained"
+            color="primary"
+            size="small"
+            style={{ marginRight: 8 }}>
+            Custom Action
+          </Button>,
+          ...existingAddons, // 重要: デフォルトのセッション/ロケールアドオンを保持します
+        ];
+      }}
+    />
+  );
+}
+```
+
+この例では、カスタムボタンが既存のアドオンの前に追加されています。`...existingAddons` を含めることで、デフォルトのセッションおよびロケールコントロールが表示されたままになるようにします。
+
+## まとめ
+
+これで、`@blocklet/ui-react` ライブラリのインストール、デフォルトの `Header` および `Footer` コンポーネントのレンダリング、そしてカスタム設定やアドオンの提供方法を学びました。
+
+これらの基本を理解したことで、ライブラリで利用可能なすべてのコンポーネントを探索する準備が整いました。レイアウト、ユーザー管理、ユーティリティコンポーネントに関する詳細なドキュメントについては、[コンポーネント](./components.md) セクションに進んでください。

package/docs/getting-started.md

@@ -0,0 +1,132 @@
+# Getting Started
+
+This guide provides a step-by-step walkthrough to install the `@blocklet/ui-react` library and render your first components. The objective is to have a functional `Header` and `Footer` within your application in a minimal amount of time.
+
+## Prerequisites
+
+Before proceeding, ensure you have the following installed in your development environment:
+*   A functional React project.
+*   Node.js and a package manager (npm or yarn).
+
+## Installation
+
+To begin, add the `@blocklet/ui-react` package to your project using your preferred package manager.
+
+With npm:
+```bash npm
+npm install @blocklet/ui-react
+```
+
+With yarn:
+```bash yarn
+yarn add @blocklet/ui-react
+```
+
+## Basic Usage: Header and Footer
+
+The `Header` and `Footer` components are designed for simplicity and can be rendered without any initial configuration. They automatically source their data from the blocklet's metadata.
+
+1.  Import the `Header` and `Footer` components into your main application file (e.g., `App.js`).
+2.  Place them at the top and bottom of your application's layout, respectively.
+
+```jsx App.js icon=logos:react
+import React from 'react';
+import Header from '@blocklet/ui-react/lib/Header';
+import Footer from '@blocklet/ui-react/lib/Footer';
+
+function App() {
+  return (
+    <div>
+      <Header />
+      <main style={{ padding: '20px', minHeight: 'calc(100vh - 128px)' }}>
+        {/* Your application content goes here */}
+        <h1>Welcome to My Blocklet</h1>
+      </main>
+      <Footer />
+    </div>
+  );
+}
+
+export default App;
+```
+
+The components automatically retrieve configuration details—such as the application name, logo, and navigation links—from the `window.blocklet` metadata object, which is injected by the Blocklet Server environment.
+
+Furthermore, the `Header` component will intelligently render additional controls:
+*   A **user session manager** is displayed if a `SessionContext` is available.
+*   A **language selector** is displayed if a `LocaleContext` is available.
+
+## Manual Configuration
+
+For development, testing, or cases where you need to override the default metadata, you can pass a configuration object directly to the components using the `blockletMeta` prop.
+
+```jsx App.js icon=logos:react
+import React from 'react';
+import Header from '@blocklet/ui-react/lib/Header';
+
+const customBlockletMeta = {
+  appName: 'My Custom App',
+  appLogo: 'https://path.to/your/logo.png',
+  navigation: [
+    {
+      title: 'Home',
+      link: '/',
+    },
+    {
+      title: 'Documentation',
+      link: '/docs',
+    },
+  ],
+};
+
+function App() {
+  return (
+    <div>
+      <Header blockletMeta={customBlockletMeta} />
+      {/* ... rest of your app */}
+    </div>
+  );
+}
+```
+
+This approach gives you precise control over the component's appearance and behavior by overriding any data provided by the global `window.blocklet` object.
+
+## Customizing the Header
+
+The `Header` component includes an `addons` area on the right side, which you can customize to include your own components, such as action buttons or custom links.
+
+The `addons` prop accepts a function that receives the default addon components as an argument. This allows you to prepend, append, or completely replace them.
+
+```jsx CustomHeader.js icon=logos:react
+import React from 'react';
+import Header from '@blocklet/ui-react/lib/Header';
+import Button from '@mui/material/Button'; // Example using Material-UI
+
+function CustomHeader() {
+  return (
+    <Header
+      addons={existingAddons => {
+        return [
+          <Button
+            key="custom-action"
+            variant="contained"
+            color="primary"
+            size="small"
+            style={{ marginRight: 8 }}>
+            Custom Action
+          </Button>,
+          ...existingAddons, // Important: preserves default session/locale addons
+        ];
+      }}
+    />
+  );
+}
+```
+
+In this example, a custom button is prepended to the existing addons. By including `...existingAddons`, you ensure that the default session and locale controls remain visible.
+
+## Summary
+
+You have successfully installed the `@blocklet/ui-react` library, rendered default `Header` and `Footer` components, and learned how to provide custom configurations and addons.
+
+With these fundamentals in place, you are now prepared to explore the full range of components available in the library. For detailed documentation on layout, user management, and utility components, please proceed to the [Components](./components.md) section.

package/docs/getting-started.zh-TW.md

@@ -0,0 +1,132 @@
+# 入門指南
+
+本指南提供逐步教學，引導您安裝 `@blocklet/ui-react` 函式庫並渲染您的第一個元件。目標是在最短的時間內，讓您的應用程式中能正常運作 `Header` 和 `Footer`。
+
+## 先決條件
+
+在繼續之前，請確保您的開發環境中已安裝以下項目：
+*   一個可運作的 React 專案。
+*   Node.js 和一個套件管理器（npm 或 yarn）。
+
+## 安裝
+
+首先，使用您偏好的套件管理器將 `@blocklet/ui-react` 套件新增至您的專案中。
+
+使用 npm：
+```bash npm
+npm install @blocklet/ui-react
+```
+
+使用 yarn：
+```bash yarn
+yarn add @blocklet/ui-react
+```
+
+## 基本用法：Header 與 Footer
+
+`Header` 和 `Footer` 元件的設計旨在簡化使用，無需任何初始設定即可渲染。它們會自動從 blocklet 的元資料中獲取資料。
+
+1.  將 `Header` 和 `Footer` 元件匯入到您的主應用程式檔案中（例如 `App.js`）。
+2.  將它們分別放置在應用程式佈局的頂部和底部。
+
+```jsx App.js icon=logos:react
+import React from 'react';
+import Header from '@blocklet/ui-react/lib/Header';
+import Footer from '@blocklet/ui-react/lib/Footer';
+
+function App() {
+  return (
+    <div>
+      <Header />
+      <main style={{ padding: '20px', minHeight: 'calc(100vh - 128px)' }}>
+        {/* 您的應用程式內容放在這裡 */}
+        <h1>Welcome to My Blocklet</h1>
+      </main>
+      <Footer />
+    </div>
+  );
+}
+
+export default App;
+```
+
+這些元件會自動從 `window.blocklet` 元資料物件中檢索設定詳情，例如應用程式名稱、標誌和導覽連結。該物件由 Blocklet Server 環境注入。
+
+此外，`Header` 元件會智慧地渲染額外的控制項：
+*   如果 `SessionContext` 可用，將會顯示**使用者會話管理器**。
+*   如果 `LocaleContext` 可用，將會顯示**語言選擇器**。
+
+## 手動設定
+
+在開發、測試或需要覆寫預設元資料的情況下，您可以使用 `blockletMeta` 屬性將設定物件直接傳遞給元件。
+
+```jsx App.js icon=logos:react
+import React from 'react';
+import Header from '@blocklet/ui-react/lib/Header';
+
+const customBlockletMeta = {
+  appName: 'My Custom App',
+  appLogo: 'https://path.to/your/logo.png',
+  navigation: [
+    {
+      title: 'Home',
+      link: '/',
+    },
+    {
+      title: 'Documentation',
+      link: '/docs',
+    },
+  ],
+};
+
+function App() {
+  return (
+    <div>
+      <Header blockletMeta={customBlockletMeta} />
+      {/* ... rest of your app */}
+    </div>
+  );
+}
+```
+
+這種方法讓您能透過覆寫全域 `window.blocklet` 物件提供的任何資料，來精確控制元件的外觀和行為。
+
+## 自訂 Header
+
+`Header` 元件在右側包含一個 `addons` 區域，您可以自訂該區域以包含您自己的元件，例如操作按鈕或自訂連結。
+
+`addons` 屬性接受一個函式，該函式接收預設的附加元件作為參數。這讓您可以將新元件加到現有元件的前面、後面，或是完全取代它們。
+
+```jsx CustomHeader.js icon=logos:react
+import React from 'react';
+import Header from '@blocklet/ui-react/lib/Header';
+import Button from '@mui/material/Button'; // 使用 Material-UI 的範例
+
+function CustomHeader() {
+  return (
+    <Header
+      addons={existingAddons => {
+        return [
+          <Button
+            key="custom-action"
+            variant="contained"
+            color="primary"
+            size="small"
+            style={{ marginRight: 8 }}>
+            Custom Action
+          </Button>,
+          ...existingAddons, // 重要：保留預設的 session/locale 附加元件
+        ];
+      }}
+    />
+  );
+}
+```
+
+在此範例中，一個自訂按鈕被加到現有的附加元件前面。透過包含 `...existingAddons`，您可以確保預設的會話和地區設定控制項仍然可見。
+
+## 總結
+
+您已成功安裝 `@blocklet/ui-react` 函式庫，渲染了預設的 `Header` 和 `Footer` 元件，並學會了如何提供自訂設定和附加元件。
+
+掌握了這些基礎知識後，您現在可以開始探索此函式庫中提供的所有元件了。關於佈局、使用者管理和工具程式元件的詳細文件，請前往 [元件](./components.md) 部分。

package/docs/getting-started.zh.md

@@ -0,0 +1,132 @@
+# 快速入门
+
+本指南将引导你逐步安装 @blocklet/ui-react 库并渲染你的第一个组件。目标是在最短的时间内在你的应用程序中拥有一个功能完备的 `Header` 和 `Footer`。
+
+## 前提条件
+
+在继续之前，请确保你的开发环境中已安装以下内容：
+*   一个可正常工作的 React 项目。
+*   Node.js 和一个包管理器（npm 或 yarn）。
+
+## 安装
+
+首先，使用你偏好的包管理器将 `@blocklet/ui-react` 包添加到你的项目中。
+
+使用 npm:
+```bash npm
+npm install @blocklet/ui-react
+```
+
+使用 yarn:
+```bash yarn
+yarn add @blocklet/ui-react
+```
+
+## 基本用法：Header 和 Footer
+
+`Header` 和 `Footer` 组件的设计旨在简化使用，无需任何初始配置即可渲染。它们会自动从 blocklet 的元数据中获取数据。
+
+1.  将 `Header` 和 `Footer` 组件导入到你的主应用程序文件（例如 `App.js`）中。
+2.  将它们分别放置在应用程序布局的顶部和底部。
+
+```jsx App.js icon=logos:react
+import React from 'react';
+import Header from '@blocklet/ui-react/lib/Header';
+import Footer from '@blocklet/ui-react/lib/Footer';
+
+function App() {
+  return (
+    <div>
+      <Header />
+      <main style={{ padding: '20px', minHeight: 'calc(100vh - 128px)' }}>
+        {/* 你的应用程序内容放在这里 */}
+        <h1>Welcome to My Blocklet</h1>
+      </main>
+      <Footer />
+    </div>
+  );
+}
+
+export default App;
+```
+
+这些组件会自动从 `window.blocklet` 元数据对象中检索配置详情（如应用名称、徽标和导航链接），该对象由 Blocklet Server 环境注入。
+
+此外，`Header` 组件还会智能地渲染额外的控件：
+*   如果 `SessionContext` 可用，则会显示**用户会话管理器**。
+*   如果 `LocaleContext` 可用，则会显示**语言选择器**。
+
+## 手动配置
+
+在开发、测试或需要覆盖默认元数据的情况下，你可以使用 `blockletMeta` 属性直接向组件传递一个配置对象。
+
+```jsx App.js icon=logos:react
+import React from 'react';
+import Header from '@blocklet/ui-react/lib/Header';
+
+const customBlockletMeta = {
+  appName: 'My Custom App',
+  appLogo: 'https://path.to/your/logo.png',
+  navigation: [
+    {
+      title: 'Home',
+      link: '/',
+    },
+    {
+      title: 'Documentation',
+      link: '/docs',
+    },
+  ],
+};
+
+function App() {
+  return (
+    <div>
+      <Header blockletMeta={customBlockletMeta} />
+      {/* ... 你的应用程序的其余部分 */}
+    </div>
+  );
+}
+```
+
+这种方法允许你覆盖全局 `window.blocklet` 对象提供的任何数据，从而精确控制组件的外观和行为。
+
+## 自定义 Header
+
+`Header` 组件右侧包含一个 `addons` 区域，你可以对其进行自定义，以包含你自己的组件，例如操作按钮或自定义链接。
+
+`addons` 属性接受一个函数作为参数，该函数接收默认的附加组件。这允许你在现有组件前后添加新组件或完全替换它们。
+
+```jsx CustomHeader.js icon=logos:react
+import React from 'react';
+import Header from '@blocklet/ui-react/lib/Header';
+import Button from '@mui/material/Button'; // 使用 Material-UI 的示例
+
+function CustomHeader() {
+  return (
+    <Header
+      addons={existingAddons => {
+        return [
+          <Button
+            key="custom-action"
+            variant="contained"
+            color="primary"
+            size="small"
+            style={{ marginRight: 8 }}>
+            Custom Action
+          </Button>,
+          ...existingAddons, // 重要：保留默认的 session/locale 附加组件
+        ];
+      }}
+    />
+  );
+}
+```
+
+在此示例中，一个自定义按钮被添加到了现有附加组件的前面。通过包含 `...existingAddons`，你可以确保默认的会话和语言区域控件保持可见。
+
+## 总结
+
+你已成功安装 `@blocklet/ui-react` 库，渲染了默认的 `Header` 和 `Footer` 组件，并学会了如何提供自定义配置和附加组件。
+
+掌握了这些基础知识后，你现在可以开始探索该库中提供的全部组件了。有关布局、用户管理和实用工具组件的详细文档，请继续阅读 [组件](./components.md) 部分。