@blocklet/ui-react 3.4.15 → 3.5.0

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

@@ -1,132 +0,0 @@
-# 入門指南
-
-本指南提供逐步教學，引導您安裝 `@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

@@ -1,132 +0,0 @@
-# 快速入门
-
-本指南将引导你逐步安装 @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) 部分。

package/docs/hooks-api.ja.md

@@ -1,214 +0,0 @@
-# Hooks API
-
-このセクションでは、ライブラリ内で利用可能なカスタム React Hook の詳細なリファレンスを提供します。これらのフックは、ステートフルなロジックをカプセル化して再利用するように設計されており、Blocklet 環境内での一般的なタスクやインタラクションを簡素化します。
-
-## useComponentInstalled
-
-このフックは、指定された1つ以上のオプションコンポーネント（DID によって識別される）がインストールされているかどうかをチェックします。これは、他の Blocklet を依存関係として利用する機能を実装するために不可欠です。このフックは、インストールのステータスと、必要に応じてユーザーにインストールを促すために必要な URL を提供します。
-
-### パラメータ
-
-このフックは、以下のプロパティを持つ単一のオブジェクトを受け入れます：
-
-<x-field-group>
-  <x-field data-name="did" data-type="string | string[]" data-required="true">
-    <x-field-desc markdown>チェックするコンポーネントの分散型識別子（DID）または DID の配列。単一の文字列には `;;` で区切られた複数の DID を含めることができます。</x-field-desc>
-  </x-field>
-  <x-field data-name="onInstalled" data-type="function" data-required="false">
-    <x-field-desc markdown>指定されたすべてのコンポーネントがすでにインストールされている場合にトリガーされるオプションのコールバック関数。</x-field-desc>
-  </x-field>
-  <x-field data-name="onError" data-type="function" data-required="false">
-    <x-field-desc markdown>指定された1つ以上のコンポーネントがインストールされていない場合にトリガーされるオプションのコールバック関数。</x-field-desc>
-  </x-field>
-</x-field-group>
-
-### 戻り値
-
-インストールの状態と関連データを含むオブジェクトを返します：
-
-<x-field-group>
-  <x-field data-name="optComponents" data-type="array">
-    <x-field-desc markdown>インストールされていないコンポーネントオブジェクトの配列。各オブジェクトには `meta.did`、`storeUrl`、`installUrl` などのメタデータが含まれます。</x-field-desc>
-  </x-field>
-  <x-field data-name="installed" data-type="boolean">
-    <x-field-desc markdown>指定されたすべてのコンポーネントがインストールされ、`blocklet.yml` で定義されている場合は `true`、そうでない場合は `false` となるブール値。</x-field-desc>
-  </x-field>
-  <x-field data-name="installStatus" data-type="object">
-    <x-field-desc markdown>キーがコンポーネントの DID で、値が現在のインストールステータス（例: 'waiting', 'installing'）であるオブジェクト。この状態は `window.postMessage` イベントを介して更新されます。</x-field-desc>
-  </x-field>
-  <x-field data-name="setInstallStatus" data-type="function">
-    <x-field-desc markdown>`installStatus` オブジェクトを手動で更新するためのステートセッター関数。</x-field-desc>
-  </x-field>
-  <x-field data-name="definedInBlockletYML" data-type="boolean">
-    <x-field-desc markdown>コンポーネントが blocklet の設定（`blocklet.yml`）で定義されているかどうかを示すブール値。</x-field-desc>
-  </x-field>
-</x-field-group>
-
-### 使用例
-
-以下の例は、依存関係が欠落している場合に `useComponentInstalled` を使用して、機能または `ComponentInstaller` コンポーネントを条件付きでレンダリングする方法を示しています。
-
-```javascript "ComponentFeature.js" icon=logos:javascript
-import React from 'react';
-import { useComponentInstalled, ComponentInstaller } from '@blocklet/ui-react';
-
-const REQUIRED_DID = 'z8ia24z55nve2TSF5m1aZ5322d9f48a43D4a'; // DID の例
-
-function ComponentFeature() {
-  const { installed, optComponents } = useComponentInstalled({ did: REQUIRED_DID });
-
-  if (!installed) {
-    // コンポーネントが存在しない場合は、インストーラー UI をレンダリングします
-    return <ComponentInstaller components={optComponents} />;
-  }
-
-  // インストールされたコンポーネントに依存する機能をレンダリングします
-  return (
-    <div>
-      <h2>My Feature</h2>
-      <p>This feature requires the component with DID: {REQUIRED_DID}</p>
-      {/* ... 機能の実装 ... */}
-    </div>
-  );
-}
-
-export default ComponentFeature;
-```
-
-## useFollow
-
-このフックは、現在認証されているユーザーと、その DID によって指定された別のユーザーとの間のフォロー関係を管理します。フォローおよびアンフォローのための API 呼び出しを処理し、現在のフォロー状況を提供します。
-
-### パラメータ
-
-<x-field-group>
-  <x-field data-name="userDid" data-type="string" data-required="true">
-    <x-field-desc markdown>フォロー状況を確認する対象のユーザープロファイルの DID。</x-field-desc>
-  </x-field>
-  <x-field data-name="t" data-type="function" data-required="true">
-    <x-field-desc markdown>成功またはエラーメッセージを表示するために使用される翻訳関数（例: `react-i18next` 由来のもの）。</x-field-desc>
-  </x-field>
-  <x-field data-name="isMySelf" data-type="boolean" data-required="true">
-    <x-field-desc markdown>`userDid` が現在ログインしているユーザーのものである場合に `true` に設定されるべきブール値。</x-field-desc>
-  </x-field>
-</x-field-group>
-
-### 戻り値
-
-以下のプロパティを持つオブジェクトを返します：
-
-<x-field-group>
-  <x-field data-name="followed" data-type="boolean">
-    <x-field-desc markdown>現在のユーザーが `userDid` で指定されたユーザーをフォローしているかどうかを示します。フォローしている場合は `true`、そうでない場合は `false` です。</x-field-desc>
-  </x-field>
-  <x-field data-name="followUser" data-type="function">
-    <x-field-desc markdown>ユーザーをフォローするために呼び出す安定した関数。API リクエストを処理し、成功時に `followed` ステートを更新します。</x-field-desc>
-  </x-field>
-  <x-field data-name="unfollowUser" data-type="function">
-    <x-field-desc markdown>ユーザーのフォローを解除するために呼び出す安定した関数。API リクエストを処理し、成功時に `followed` ステートを更新します。</x-field-desc>
-  </x-field>
-</x-field-group>
-
-### 使用例
-
-この例では、関係ステータスに基づいて「フォロー」または「アンフォロー」アクションを表示する `FollowButton` コンポーネントを作成する方法を示します。
-
-```javascript "FollowButton.js" icon=logos:javascript
-import React from 'react';
-import Button from '@mui/material/Button';
-import { useTranslation } from 'react-i18next';
-import { useFollow } from '@blocklet/ui-react/hooks';
-import { useSession } from '@blocklet/did-connect-react';
-
-function FollowButton({ profileDid }) {
-  const { session } = useSession();
-  const { t } = useTranslation();
-  const isMySelf = session?.user?.did === profileDid;
-
-  const { followed, followUser, unfollowUser } = useFollow({
-    userDid: profileDid,
-    t,
-    isMySelf,
-  });
-
-  if (isMySelf) {
-    return null; // 自身のプロフィールにはボタンを表示しない
-  }
-
-  const handleClick = () => {
-    if (followed) {
-      unfollowUser();
-    } else {
-      followUser();
-    }
-  };
-
-  return (
-    <Button variant="contained" onClick={handleClick}>
-      {followed ? t('profile.unfollow') : t('profile.follow')}
-    </Button>
-  );
-}
-
-export default FollowButton;
-```
-
-## useMobile
-
-レスポンシブコンポーネントを作成するためのシンプルなユーティリティフックです。Material-UI の `useMediaQuery` を利用して、現在のビューポートの幅が指定されたブレークポイント未満であるかどうかを判断します。
-
-### パラメータ
-
-<x-field-group>
-  <x-field data-name="key" data-type="number | Breakpoint" data-default="'sm'" data-required="false">
-    <x-field-desc markdown>Material-UI のブレークポイントキー（例: `'xs'`、`'sm'`、`'md'`）または比較対象のピクセル値。画面幅がこの値より小さい場合にフックは `true` を返します。</x-field-desc>
-  </x-field>
-</x-field-group>
-
-### 戻り値
-
-`boolean` 値を返します。ビューポートが指定されたブレークポイントより小さい場合は `true`、そうでない場合は `false` です。
-
-### 使用例
-
-このフックは、Material-UI の `ThemeProvider` でラップされたコンポーネントツリー内で使用する必要があります。
-
-```javascript "ResponsiveComponent.js" icon=logos:javascript
-import React from 'react';
-import Typography from '@mui/material/Typography';
-import { ThemeProvider, createTheme } from '@mui/material/styles';
-import { useMobile } from '@blocklet/ui-react/hooks';
-
-// フックを使用するコンポーネント
-function ResponsiveComponent() {
-  const isMobile = useMobile({ key: 'md' }); // 'md' ブレークポイントに対してチェック
-
-  return (
-    <div>
-      {isMobile ? (
-        <Typography variant="h6">Mobile View</Typography>
-      ) : (
-        <Typography variant="h4">Desktop View</Typography>
-      )}
-      <p>Resize your browser window to see the content change.</p>
-    </div>
-  );
-}
-
-// コンポーネントは ThemeProvider でラップする必要があります
-const theme = createTheme();
-
-function App() {
-  return (
-    <ThemeProvider theme={theme}>
-      <ResponsiveComponent />
-    </ThemeProvider>
-  );
-}
-
-export default App;
-```
-
----
-
-これらのフックを使用することで、最小限のボイラープレートコードで複雑な機能を効率的に実装できます。これらのフックを使用する可能性のあるコンポーネントの詳細については、[コンポーネント](./components.md) のドキュメントを参照してください。