@blocklet/ui-react 3.1.47 → 3.1.49

package/docs/components-component-management-blocklet-studio.zh.md

@@ -0,0 +1,194 @@
+# BlockletStudio
+
+`BlockletStudio` 组件提供了一个精简的、可嵌入的用户界面，用于发布和管理 blocklet 资源。它通过渲染一个全页 `iframe` 来运行，该 `iframe` 从指定的 blocklet 服务加载一个专用的发布界面。这使得您的应用程序能够提供一致且强大的资源管理体验，而无需从头开始构建 UI。
+
+主机应用程序与 `BlockletStudio` iframe 之间的通信通过 `window.postMessage` API 进行安全处理，从而可以为上传、发布和连接等事件启用回调。
+
+## 使用示例
+
+要集成 `BlockletStudio`，您需要管理其可见性状态（例如，使用 `useState`）。由于 iframe 可能需要一些时间来加载，建议向用户显示一个加载指示器。`onOpened` 回调可用于表示 iframe 内容已准备就绪，此时可以隐藏加载指示器。
+
+以下示例演示了如何实现一个打开 `BlockletStudio` 对话框并管理加载状态的按钮。
+
+```tsx icon=logos:react title="Exporter.tsx"
+import { Icon } from '@iconify-icon/react';
+import ArrowUp from '@iconify-icons/tabler/arrow-big-up-line';
+import { Box, IconButton, CircularProgress as Spinner, svgIconClasses } from '@mui/material';
+import { useState } from 'react';
+import { BlockletStudio } from '@arcblock/ux-react';
+
+// 提供 studio 服务的 blocklet 的 DID。
+const AI_STUDIO_COMPONENT_DID = 'z8ia1mAXo8ZE7ytGF36L5uBf9kD2kenhqFGp9';
+
+export default function Exporter() {
+  const [showCreateResource, setShowCreateResource] = useState(false);
+  const [opening, setOpening] = useState(false);
+
+  const handleShowDialog = () => {
+    setOpening(true);
+    setShowCreateResource(true);
+  };
+
+  return (
+    <>
+      <IconButton
+        sx={{
+          position: 'relative',
+          minWidth: 40,
+          minHeight: 40,
+          borderRadius: '100%',
+          [`.${svgIconClasses.root}`]: {
+            color: 'text.secondary',
+          },
+        }}
+        onClick={handleShowDialog}>
+        {opening ? <Spinner size={16} /> : <Box component={Icon} icon={ArrowUp} style={{ fontSize: 24 }} />}
+      </IconButton>
+      <BlockletStudio
+        open={showCreateResource}
+        setOpen={setShowCreateResource}
+        onOpened={() => setOpening(false)}
+        componentDid={AI_STUDIO_COMPONENT_DID}
+        mode="dialog"
+        title="Demo Project"
+        description="This is a demo project for the 'aigne' blocklet."
+        note='Please review all resources and components before publishing.'
+        introduction="Welcome to the resource publisher."
+        tenantScope="test-tenant-scope-id-2"
+        resourcesParams={{ name: 'test-project', extra: true }}
+        dependentComponentsMode="readonly"
+        componentsTitle="Required Components"
+        resourcesTitle="Add Project Files"
+        onConnected={() => alert('Connected')}
+        onUploaded={() => alert('Uploaded')}
+        onReleased={() => alert('Released')}
+        components={[
+          { did: 'z8ia3xzq2tMq8CRHfaXj1BTYJyYnEcHbqP8cJ', included: true, required: true },
+          { did: 'z2qZyjnsRffFtn2PDnDwDHTRbAu53RpKqDtFZ', included: true, required: false },
+        ]}
+        resources={{
+          'z8iZpog7mcgcgBZzTiXJCWESvmnRrQmnd3XBB': [
+            'template-448698592710885376',
+            'template-448696391418511360',
+          ],
+        }}
+      />
+    </>
+  );
+}
+```
+
+## Props
+
+`BlockletStudio` 组件接受以下 props 来控制其行为和外观。
+
+<x-field-group>
+  <x-field data-name="open" data-type="boolean" data-required="true">
+    <x-field-desc markdown>控制 `BlockletStudio` iframe 的可见性。设置为 `true` 显示，设置为 `false` 隐藏。</x-field-desc>
+  </x-field>
+  <x-field data-name="setOpen" data-type="(open: boolean) => void" data-required="true">
+    <x-field-desc markdown>一个回调函数，`BlockletStudio` 使用它来请求关闭。通常，此函数会将与 `open` prop 关联的状态变量设置为 `false`。</x-field-desc>
+  </x-field>
+  <x-field data-name="componentDid" data-type="string" data-required="true">
+    <x-field-desc markdown>提供资源发布服务的 blocklet 的去中心化标识符 (DID)。这决定了加载哪个 studio 界面。</x-field-desc>
+  </x-field>
+  <x-field data-name="onOpened" data-type="() => void" data-required="false">
+    <x-field-desc markdown>一个可选的回调函数，当 `BlockletStudio` iframe 加载完成并准备好进行用户交互时执行。</x-field-desc>
+  </x-field>
+  <x-field data-name="onUploaded" data-type="(data: unknown) => void" data-required="false">
+    <x-field-desc markdown>一个可选的回调函数，在用户成功上传新资源后触发。`data` 参数包含有关上传项的元数据。</x-field-desc>
+  </x-field>
+  <x-field data-name="onReleased" data-type="(data: unknown) => void" data-required="false">
+    <x-field-desc markdown>一个可选的回调函数，在用户发布组件的新版本后触发。`data` 参数包含有关新版本的信息。</x-field-desc>
+  </x-field>
+  <x-field data-name="onConnected" data-type="(data: unknown) => void" data-required="false">
+    <x-field-desc markdown>一个可选的回调函数，在用户连接资源或组件后触发。</x-field-desc>
+  </x-field>
+  <x-field data-name="tenantScope" data-type="string" data-required="false">
+    <x-field-desc markdown>一个可选字符串，用于将资源范围限定于特定租户。这可用于确保多租户环境中的数据隔离。</x-field-desc>
+  </x-field>
+  <x-field data-name="resourcesParams" data-type="Record<string, any>" data-required="false" data-default="{}">
+    <x-field-desc markdown>一个包含查询参数的对象，这些参数将传递给 blocklet 的资源获取 API 端点。这允许对资源进行动态过滤。</x-field-desc>
+  </x-field>
+  <x-field data-name="mode" data-type="string" data-required="false" data-default='"dialog"'>
+    <x-field-desc markdown>决定 studio 界面的显示模式。默认为 `'dialog'`。</x-field-desc>
+  </x-field>
+  <x-field data-name="title" data-type="string" data-required="false">
+    <x-field-desc markdown>一个可选的标题，显示在 studio 界面的顶部。</x-field-desc>
+  </x-field>
+  <x-field data-name="logo" data-type="string" data-required="false">
+    <x-field-desc markdown>一个可选的 logo URL，显示在 studio 界面中。</x-field-desc>
+  </x-field>
+  <x-field data-name="description" data-type="string" data-required="false">
+    <x-field-desc markdown>一个可选的字符串，提供简短描述，显示在 studio UI 中。</x-field-desc>
+  </x-field>
+  <x-field data-name="introduction" data-type="string" data-required="false">
+    <x-field-desc markdown>一个可选的字符串，用于更详细的介绍，显示在 studio UI 中。</x-field-desc>
+  </x-field>
+  <x-field data-name="note" data-type="string" data-required="false">
+    <x-field-desc markdown>一个可选的字符串，用于向用户显示注释或重要消息。</x-field-desc>
+  </x-field>
+  <x-field data-name="componentsTitle" data-type="string" data-required="false">
+    <x-field-desc markdown>一个可选的字符串，用于自定义组件部分的标题。</x-field-desc>
+  </x-field>
+  <x-field data-name="resourcesTitle" data-type="string" data-required="false">
+    <x-field-desc markdown>一个可选的字符串，用于自定义资源部分的标题。</x-field-desc>
+  </x-field>
+  <x-field data-name="components" data-type="Record<string, unknown>[]" data-required="false" data-default="[]">
+    <x-field-desc markdown>一个对象数组，代表在 studio 中默认应预先选中的组件。</x-field-desc>
+  </x-field>
+  <x-field data-name="resources" data-type="Record<string, unknown>" data-required="false" data-default="{}">
+    <x-field-desc markdown>一个对象，代表在 studio 中默认应预先选中的资源。</x-field-desc>
+  </x-field>
+  <x-field data-name="dependentComponentsMode" data-type="'auto' | 'readonly'" data-required="false">
+    <x-field-desc markdown>控制依赖组件的行为。在 `'readonly'` 模式下，用户无法取消选择作为所选资源依赖项而自动包含的组件。</x-field-desc>
+  </x-field>
+  <x-field data-name="style" data-type="React.CSSProperties" data-required="false" data-default="{}">
+    <x-field-desc markdown>一个用于将自定义 CSS 样式应用于 `iframe` 元素的对象。</x-field-desc>
+  </x-field>
+  <x-field data-name="zIndex" data-type="number" data-required="false" data-default="9999">
+    <x-field-desc markdown>`iframe` 元素的 z-index CSS 属性，控制其堆叠顺序。</x-field-desc>
+  </x-field>
+</x-field-group>
+
+## 依赖组件
+
+为 `BlockletStudio` 提供资源 API 的 Blocklet 可以直接在资源数据中指定组件依赖项。当用户选择一个列出了 `dependentComponents` 的资源时，`BlockletStudio` 将在 UI 中自动选择这些组件。
+
+此功能通过确保所有必要的依赖项都自动包含进来，从而简化了用户体验。
+
+要实现此功能，您的 blocklet 的资源 API 应返回一个包含所需组件 DID 的 `dependentComponents` 数组。
+
+### API 响应示例
+
+以下是来自资源 API 端点的 JSON 响应示例。"Application" 和 "Tool" 资源声明了它们的组件依赖项。
+
+```json 带有依赖项的 API 响应
+{
+  "resources": [
+    {
+      "id": "application-448698592710885376",
+      "name": "My App (as Application)",
+      "dependentComponents": [
+        "error-did",
+        "z8ia1mAXo8ZE7ytGF36L5uBf9kD2kenhqFGp9",
+        "z2qZyjnsRffFtn2PDnDwDHTRbAu53RpKqDtFZ",
+        "z2qaCNvKMv5GjouKdcDWexv6WqtHbpNPQDnAk"
+      ]
+    },
+    {
+      "id": "tool-448698592710885376",
+      "name": "My App (as Tool)",
+      "dependentComponents": ["error-did", "z2qaCNvKMv5GjouKdcDWexv6WqtHbpNPQDnAk"]
+    },
+    {
+      "id": "template-448698592710885376",
+      "name": "My App (as Template)"
+    }
+  ]
+}
+```
+
+## 总结
+
+`BlockletStudio` 组件提供了一种强大而便捷的方式，可将资源和组件管理直接集成到您的应用程序中。通过利用 `iframe` 和一组清晰的 props，它在简化开发的同时提供了一致的用户体验。有关依赖项管理的相关功能，您可能还想查看 [ComponentInstaller](./components-component-management-component-installer.md) 文档。

package/docs/components-component-management-component-installer.ja.md

@@ -0,0 +1,256 @@
+# ComponentInstaller
+
+`ComponentInstaller` は、他の Blocklet に依存する機能のゲートキーパーとして機能するユーティリティコンポーネントです。指定されたコンポーネントの依存関係がインストールされているかどうかを検証します。インストールされていない場合、管理者（デフォルトでは `owner` または `admin` ロール）が直接インストールするためのユーザーフレンドリーなインターフェースを提供します。ユーザーが必要な権限を持っていない場合は、管理者に連絡するよう促すメッセージを表示します。
+
+このコンポーネントは、不足しているオプションの依存関係を適切に処理できる堅牢なアプリケーションを作成するために不可欠であり、管理者をインストールプロセスを通じてガイドすることでユーザーエクスペリエンスを向上させます。
+
+## 仕組み
+
+このコンポーネントのロジックは、子コンポーネントをレンダリングする前に依存関係が満たされていることを確認するため、明確で順次的なプロセスに従います。
+
+```d2
+direction: down
+
+start: {
+  label: "開始"
+  shape: oval
+}
+
+check_dependencies: {
+  label: "'did' プロパティで定義された依存関係を確認"
+  shape: rectangle
+}
+
+is_installed: {
+  label: "すべての依存関係はインストール済みか？"
+  shape: diamond
+}
+
+render_children: {
+  label: "子コンポーネントをレンダリング"
+  shape: rectangle
+  style.fill: "#d4edda"
+}
+
+check_permission: {
+  label: "'roles' プロパティに対してユーザーのロールを確認"
+  shape: rectangle
+}
+
+has_permission: {
+  label: "ユーザーに権限があるか？"
+  shape: diamond
+}
+
+display_installer: {
+  label: "インストーラーUIを表示"
+  shape: rectangle
+  style.fill: "#cce5ff"
+}
+
+is_mute: {
+  label: "'noPermissionMute' プロパティは true か？"
+  shape: diamond
+}
+
+display_suggestion: {
+  label: "'管理者に連絡' の提案を表示"
+  shape: rectangle
+  style.fill: "#f8d7da"
+}
+
+render_fallback: {
+  label: "フォールバックコンポーネントまたは null をレンダリング"
+  shape: rectangle
+}
+
+end: {
+  label: "終了"
+  shape: oval
+}
+
+start -> check_dependencies
+check_dependencies -> is_installed
+is_installed -> render_children: "はい"
+is_installed -> check_permission: "いいえ"
+render_children -> end
+
+check_permission -> has_permission
+has_permission -> display_installer: "はい"
+has_permission -> is_mute: "いいえ"
+display_installer -> end
+
+is_mute -> render_fallback: "はい"
+is_mute -> display_suggestion: "いいえ"
+render_fallback -> end
+display_suggestion -> end
+```
+
+1.  **依存関係のチェック**: `did` プロパティを読み取り、Blocklet のメタデータ（`window.blocklet.optionalComponents`）と照合して、必要なコンポーネントがインストールされているかどうかを判断します。
+2.  **権限チェック**: 不足しているコンポーネントがある場合、`SessionPermission` コンポーネントを使用して、現在のユーザーのロールが `roles` プロパティで指定されたものと一致するかどうかを検証します。
+3.  **条件付きレンダリング**:
+    *   すべての依存関係がインストールされている場合、その `children` をレンダリングします。
+    *   依存関係が不足しており、ユーザーに権限がある場合、ポップアップのインストールパネルを表示します。
+    *   依存関係が不足しており、ユーザーに権限がない場合、管理者に連絡するよう提案を表示するか、`noPermissionMute` が有効な場合は `fallback` コンポーネントをレンダリングします。
+
+## 基本的な使い方
+
+オプションの Blocklet に依存するコンポーネントや機能を `ComponentInstaller` でラップします。必要なコンポーネントの DID を提供してください。
+
+```jsx "MyFeature.jsx" icon=logos:react
+import ComponentInstaller from '@arcblock/blocklet-ui-react/lib/ComponentInstaller';
+import MyDependentComponent from './MyDependentComponent';
+
+export default function MyFeature() {
+  // 必要なコンポーネントの実際の DID に置き換えてください
+  const requiredComponentDid = 'z8ia2427634f1e909a304e2b963715a18';
+
+  return (
+    <ComponentInstaller did={requiredComponentDid}>
+      {/* このコンポーネントは依存関係が満たされている場合にのみレンダリングされます */}
+      <MyDependentComponent />
+    </ComponentInstaller>
+  );
+}
+```
+
+## Props
+
+`ComponentInstaller` は、その動作をカスタマイズするために以下の props を受け入れます。
+
+<x-field-group>
+  <x-field data-name="did" data-type="string | string[]" data-required="true">
+    <x-field-desc markdown>チェックするコンポーネントの依存関係の DID（または DID の配列）。これは、必要な Blocklet の主要な識別子です。</x-field-desc>
+  </x-field>
+  <x-field data-name="children" data-type="any" data-required="true">
+    <x-field-desc markdown>すべての依存関係がインストールされていることを確認した後にレンダリングするコンテンツ。標準の React ノードまたはレンダー関数を指定できます。</x-field-desc>
+  </x-field>
+  <x-field data-name="roles" data-type="string[]" data-default='["owner", "admin"]'>
+    <x-field-desc markdown>インストール UI を表示し、不足しているコンポーネントをインストールすることが許可されているユーザーロールの配列。</x-field-desc>
+  </x-field>
+  <x-field data-name="fallback" data-type="React.ReactNode" data-required="false">
+    <x-field-desc markdown>依存関係をチェックしている間、またはインストール権限のないユーザーに対して `noPermissionMute` が有効な場合に表示するフォールバックコンポーネント。</x-field-desc>
+  </x-field>
+  <x-field data-name="noPermissionMute" data-type="boolean" data-default="false">
+    <x-field-desc markdown>`true` の場合、権限のないユーザーには「管理者に連絡」メッセージの代わりに `fallback` コンポーネント（または何も表示しない）が表示されます。</x-field-desc>
+  </x-field>
+  <x-field data-name="disabled" data-type="boolean" data-default="false">
+    <x-field-desc markdown>`true` の場合、コンポーネントはすべてのチェックをバイパスし、即座にその `children` をレンダリングします。</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>依存関係のチェック中にエラーが発生した場合にトリガーされるコールバック関数。エラーの原因となったコンポーネントのリストを受け取ります。</x-field-desc>
+  </x-field>
+  <x-field data-name="onClose" data-type="function" data-required="false">
+    <x-field-desc markdown>インストールのポップアップが閉じられたときに呼び出されるコールバック関数。</x-field-desc>
+  </x-field>
+  <x-field data-name="closeByOutSize" data-type="boolean" data-default="false">
+    <x-field-desc markdown>`true` の場合、ユーザーがポップアップの外側をクリックすると、インストールのポップアップが閉じます。</x-field-desc>
+  </x-field>
+  <x-field data-name="warnIcon" data-type="React.ReactNode" data-required="false">
+    <x-field-desc markdown>インストールのポップアップのデフォルトの警告アイコンを置き換えるためのカスタム React ノード。</x-field-desc>
+  </x-field>
+</x-field-group>
+
+## 高度な使い方
+
+### 複数のコンポーネントのチェック
+
+`did` プロパティに DID の配列を渡すことで、複数の依存関係を一度にチェックできます。指定されたすべてのコンポーネントがインストールされている場合にのみ、子はレンダリングされます。
+
+```jsx "MyDashboard.jsx" icon=logos:react
+import ComponentInstaller from '@arcblock/blocklet-ui-react/lib/ComponentInstaller';
+import AnalyticsWidget from './AnalyticsWidget';
+import CmsWidget from './CmsWidget';
+
+export default function MyDashboard() {
+  const requiredDids = [
+    'z8ia2427634f1e909a304e2b963715a18', // 分析サービス
+    'z8ia3c1f2e4b8e6a1b2c3d4e5f6a7b8c9', // CMS サービス
+  ];
+
+  return (
+    <ComponentInstaller did={requiredDids}>
+      <AnalyticsWidget />
+      <CmsWidget />
+    </ComponentInstaller>
+  );
+}
+```
+
+### ローディング状態のためのフォールバックの使用
+
+依存関係のチェックが進行中の間、`fallback` コンポーネントを提供してユーザーエクスペリエンスを向上させます。これは、`noPermissionMute` と共に使用して、権限のないユーザーにプレースホルダーを表示する場合にも役立ちます。
+
+```jsx "FeatureWithLoading.jsx" icon=logos:react
+import ComponentInstaller from '@arcblock/blocklet-ui-react/lib/ComponentInstaller';
+import CircularProgress from '@mui/material/CircularProgress';
+import Box from '@mui/material/Box';
+import MyDependentComponent from './MyDependentComponent';
+
+export default function FeatureWithLoading() {
+  const LoadingSpinner = (
+    <Box sx={{ display: 'flex', justifyContent: 'center', p: 4 }}>
+      <CircularProgress />
+    </Box>
+  );
+
+  return (
+    <ComponentInstaller
+      did="z8ia2427634f1e909a304e2b963715a18"
+      fallback={LoadingSpinner}
+      noPermissionMute={true}
+    >
+      <MyDependentComponent />
+    </ComponentInstaller>
+  );
+}
+```
+
+### レンダープロップによるカスタム UI
+
+UI を完全に制御するために、`children` として関数を渡すことができます。この関数は `hasPermission`、`optComponents`、および `installStatus` を含むオブジェクトを受け取り、完全にカスタムのインストールインターフェースを構築することができます。
+
+```jsx "CustomInstallerButton.jsx" icon=logos:react
+import ComponentInstaller from '@arcblock/blocklet-ui-react/lib/ComponentInstaller';
+import Button from '@mui/material/Button';
+
+export default function CustomInstallerButton() {
+  const requiredDid = 'z8ia2427634f1e909a304e2b963715a18';
+
+  return (
+    <ComponentInstaller did={requiredDid}>
+      {({ hasPermission, optComponents, installStatus }) => {
+        const isMissing = optComponents.length > 0;
+        const status = installStatus[requiredDid] || 'not_installed';
+
+        if (!isMissing) {
+          return <p>Feature is ready to use!</p>;
+        }
+
+        if (!hasPermission) {
+          return <p>Please ask an admin to install the required component.</p>;
+        }
+
+        return (
+          <Button
+            variant="contained"
+            disabled={status !== 'not_installed'}
+            onClick={() => window.open(optComponents[0].installUrl, '_blank')}
+          >
+            {status === 'not_installed' ? `Install ${optComponents[0].meta.title}` : `Installing... (${status})`}
+          </Button>
+        );
+      }}
+    </ComponentInstaller>
+  );
+}
+```
+
+## まとめ
+
+`ComponentInstaller` は、Blocklet アプリケーション内でオプションの依存関係を管理するための強力なコンポーネントです。必要なコンポーネントが利用可能であることを保証するための構造化されたユーザーフレンドリーな方法を提供し、必要に応じて管理者をインストールプロセスを通じてガイドします。このコンポーネントを使用することで、ユーザーの環境に適応する、より回復力があり機能豊富なアプリケーションを構築できます。
+
+コンポーネントの管理に関する詳細については、リソースとコンポーネント管理のためのより包括的なインターフェースを提供する [BlockletStudio](./components-component-management-blocklet-studio.md) コンポーネントにも興味があるかもしれません。