@blocklet/ui-react 3.1.47 → 3.1.49

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

@@ -0,0 +1,256 @@
+# ComponentInstaller
+
+The `ComponentInstaller` is a utility component that acts as a gatekeeper for features that depend on other blocklets. It verifies whether specified component dependencies are installed. If they are not, it provides a user-friendly interface for administrators (`owner` or `admin` roles by default) to install them directly. If the user lacks the necessary permissions, it displays a message advising them to contact an administrator.
+
+This component is essential for creating robust applications that can gracefully handle missing optional dependencies, improving the user experience by guiding administrators through the installation process.
+
+## How It Works
+
+The component's logic follows a clear, sequential process to ensure dependencies are met before rendering its child components.
+
+```d2
+direction: down
+
+start: {
+  label: "Start"
+  shape: oval
+}
+
+check_dependencies: {
+  label: "Check dependencies defined in 'did' prop"
+  shape: rectangle
+}
+
+is_installed: {
+  label: "Are all dependencies installed?"
+  shape: diamond
+}
+
+render_children: {
+  label: "Render child components"
+  shape: rectangle
+  style.fill: "#d4edda"
+}
+
+check_permission: {
+  label: "Check user's role against 'roles' prop"
+  shape: rectangle
+}
+
+has_permission: {
+  label: "Does user have permission?"
+  shape: diamond
+}
+
+display_installer: {
+  label: "Display Installer UI"
+  shape: rectangle
+  style.fill: "#cce5ff"
+}
+
+is_mute: {
+  label: "Is 'noPermissionMute' prop true?"
+  shape: diamond
+}
+
+display_suggestion: {
+  label: "Display 'Contact Admin' suggestion"
+  shape: rectangle
+  style.fill: "#f8d7da"
+}
+
+render_fallback: {
+  label: "Render fallback component or null"
+  shape: rectangle
+}
+
+end: {
+  label: "End"
+  shape: oval
+}
+
+start -> check_dependencies
+check_dependencies -> is_installed
+is_installed -> render_children: "Yes"
+is_installed -> check_permission: "No"
+render_children -> end
+
+check_permission -> has_permission
+has_permission -> display_installer: "Yes"
+has_permission -> is_mute: "No"
+display_installer -> end
+
+is_mute -> render_fallback: "Yes"
+is_mute -> display_suggestion: "No"
+render_fallback -> end
+display_suggestion -> end
+```
+
+1.  **Dependency Check**: It reads the `did` prop and checks against the blocklet's metadata (`window.blocklet.optionalComponents`) to determine if the required components are installed.
+2.  **Permission Check**: If any components are missing, it uses the `SessionPermission` component to verify if the current user's role matches those specified in the `roles` prop.
+3.  **Conditional Rendering**:
+    *   If all dependencies are installed, it renders its `children`.
+    *   If dependencies are missing and the user has permission, it displays a pop-up installation panel.
+    *   If dependencies are missing and the user lacks permission, it either shows a suggestion to contact an admin or renders a `fallback` component if `noPermissionMute` is enabled.
+
+## Basic Usage
+
+Wrap any component or feature that relies on an optional blocklet with `ComponentInstaller`. Provide the DID of the required component.
+
+```jsx "MyFeature.jsx" icon=logos:react
+import ComponentInstaller from '@arcblock/blocklet-ui-react/lib/ComponentInstaller';
+import MyDependentComponent from './MyDependentComponent';
+
+export default function MyFeature() {
+  // Replace with the actual DID of the required component
+  const requiredComponentDid = 'z8ia2427634f1e909a304e2b963715a18';
+
+  return (
+    <ComponentInstaller did={requiredComponentDid}>
+      {/* This component will only be rendered if the dependency is met */}
+      <MyDependentComponent />
+    </ComponentInstaller>
+  );
+}
+```
+
+## Props
+
+The `ComponentInstaller` accepts the following props to customize its behavior.
+
+<x-field-group>
+  <x-field data-name="did" data-type="string | string[]" data-required="true">
+    <x-field-desc markdown>The DID (or an array of DIDs) of the component dependencies to check. This is the primary identifier for the blocklet(s) you need.</x-field-desc>
+  </x-field>
+  <x-field data-name="children" data-type="any" data-required="true">
+    <x-field-desc markdown>The content to render once all dependencies are confirmed to be installed. Can be a standard React node or a render function.</x-field-desc>
+  </x-field>
+  <x-field data-name="roles" data-type="string[]" data-default='["owner", "admin"]'>
+    <x-field-desc markdown>An array of user roles that are permitted to see the installation UI and install missing components.</x-field-desc>
+  </x-field>
+  <x-field data-name="fallback" data-type="React.ReactNode" data-required="false">
+    <x-field-desc markdown>A fallback component to display while checking for dependencies or when `noPermissionMute` is active for a user without installation rights.</x-field-desc>
+  </x-field>
+  <x-field data-name="noPermissionMute" data-type="boolean" data-default="false">
+    <x-field-desc markdown>If `true`, users without permission will see the `fallback` component (or nothing) instead of the "contact admin" message.</x-field-desc>
+  </x-field>
+  <x-field data-name="disabled" data-type="boolean" data-default="false">
+    <x-field-desc markdown>If `true`, the component bypasses all checks and immediately renders its `children`.</x-field-desc>
+  </x-field>
+  <x-field data-name="onInstalled" data-type="function" data-required="false">
+    <x-field-desc markdown>A callback function that is triggered after the dependency check is complete. It receives the list of installed components.</x-field-desc>
+  </x-field>
+  <x-field data-name="onError" data-type="function" data-required="false">
+    <x-field-desc markdown>A callback function that is triggered if an error occurs during the dependency check. It receives the list of components that caused the error.</x-field-desc>
+  </x-field>
+  <x-field data-name="onClose" data-type="function" data-required="false">
+    <x-field-desc markdown>A callback function invoked when the installation pop-up is closed.</x-field-desc>
+  </x-field>
+  <x-field data-name="closeByOutSize" data-type="boolean" data-default="false">
+    <x-field-desc markdown>If `true`, the installation pop-up will close when the user clicks outside of it.</x-field-desc>
+  </x-field>
+  <x-field data-name="warnIcon" data-type="React.ReactNode" data-required="false">
+    <x-field-desc markdown>A custom React node to replace the default warning icon in the installation pop-up.</x-field-desc>
+  </x-field>
+</x-field-group>
+
+## Advanced Usage
+
+### Checking Multiple Components
+
+You can pass an array of DIDs to the `did` prop to check for multiple dependencies at once. The children will only render if all specified components are installed.
+
+```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', // Analytics Service
+    'z8ia3c1f2e4b8e6a1b2c3d4e5f6a7b8c9', // CMS Service
+  ];
+
+  return (
+    <ComponentInstaller did={requiredDids}>
+      <AnalyticsWidget />
+      <CmsWidget />
+    </ComponentInstaller>
+  );
+}
+```
+
+### Using a Fallback for Loading States
+
+Provide a `fallback` component to improve the user experience while the dependency check is in progress. This is also useful with `noPermissionMute` to display a placeholder for unauthorized users.
+
+```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>
+  );
+}
+```
+
+### Custom UI with Render Props
+
+For full control over the UI, you can pass a function as `children`. This function receives an object with `hasPermission`, `optComponents`, and `installStatus`, allowing you to build a completely custom installation interface.
+
+```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>
+  );
+}
+```
+
+## Summary
+
+The `ComponentInstaller` is a powerful component for managing optional dependencies within a blocklet application. It provides a structured and user-friendly way to ensure that required components are available, guiding administrators through the installation process when necessary. By using this component, you can build more resilient and feature-rich applications that adapt to the user's environment.
+
+For further details on managing components, you may also be interested in the [BlockletStudio](./components-component-management-blocklet-studio.md) component, which offers a more comprehensive interface for resource and component management.

package/docs/components-component-management-component-installer.zh-TW.md

@@ -0,0 +1,256 @@
+# ComponentInstaller
+
+`ComponentInstaller` 是一個實用工具元件，對於依賴其他 blocklet 的功能扮演著守門員的角色。它會驗證指定的元件相依性是否已安裝。如果尚未安裝，它會為管理員（預設為 `owner` 或 `admin` 角色）提供一個使用者友善的介面，讓他們可以直接安裝。如果使用者缺乏必要的權限，它會顯示一則訊息，建議他們聯絡管理員。
+
+此元件對於建立穩健的應用程式至關重要，能夠優雅地處理缺失的選用相依性，並透過引導管理員完成安裝過程來改善使用者體驗。
+
+## 運作方式
+
+該元件的邏輯遵循一個清晰的順序流程，以確保在渲染其子元件之前滿足所有相依性。
+
+```d2
+direction: down
+
+start: {
+  label: "開始"
+  shape: oval
+}
+
+check_dependencies: {
+  label: "檢查 'did' prop 中定義的相依性"
+  shape: rectangle
+}
+
+is_installed: {
+  label: "是否所有相依性都已安裝？"
+  shape: diamond
+}
+
+render_children: {
+  label: "渲染子元件"
+  shape: rectangle
+  style.fill: "#d4edda"
+}
+
+check_permission: {
+  label: "根據 'roles' prop 檢查使用者角色"
+  shape: rectangle
+}
+
+has_permission: {
+  label: "使用者是否有權限？"
+  shape: diamond
+}
+
+display_installer: {
+  label: "顯示安裝程式 UI"
+  shape: rectangle
+  style.fill: "#cce5ff"
+}
+
+is_mute: {
+  label: "'noPermissionMute' prop 是否為 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` prop，並對照 blocklet 的元資料（`window.blocklet.optionalComponents`）進行檢查，以確定所需元件是否已安裝。
+2.  **權限檢查**：如果有任何元件缺失，它會使用 `SessionPermission` 元件來驗證目前使用者的角色是否與 `roles` prop 中指定的角色相符。
+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` prop，以一次性檢查多個相依性。只有在所有指定的元件都已安裝的情況下，子元件才會被渲染。
+
+```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', // 內容管理系統服務
+  ];
+
+  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>
+  );
+}
+```
+
+### 使用渲染屬性 (Render Props) 自訂 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>功能已準備就緒！</p>;
+        }
+
+        if (!hasPermission) {
+          return <p>請要求管理員安裝所需元件。</p>;
+        }
+
+        return (
+          <Button
+            variant="contained"
+            disabled={status !== 'not_installed'}
+            onClick={() => window.open(optComponents[0].installUrl, '_blank')}
+          >
+            {status === 'not_installed' ? `安裝 ${optComponents[0].meta.title}` : `安裝中... (${status})`}
+          </Button>
+        );
+      }}
+    </ComponentInstaller>
+  );
+}
+```
+
+## 總結
+
+`ComponentInstaller` 是一個強大的元件，用於管理 blocklet 應用程式中的選用相依性。它提供了一種結構化且使用者友善的方式，以確保所需元件可用，並在必要時引導管理員完成安裝過程。透過使用此元件，您可以建立更具彈性、功能更豐富且能適應使用者環境的應用程式。
+
+有關管理元件的更多詳細資訊，您可能也會對 [BlockletStudio](./components-component-management-blocklet-studio.md) 元件感興趣，它為資源和元件管理提供了更全面的介面。