@blocklet/ui-react 3.1.48 → 3.1.50

package/docs/how-to-guides.md

@@ -0,0 +1,413 @@
+# How-to Guides
+
+This section provides practical, step-by-step guides for completing common tasks and implementing specific workflows using the library's components. Each guide is designed to be a self-contained set of instructions to help you achieve a specific outcome efficiently.
+
+<x-cards data-columns="2">
+  <x-card data-title="Add Custom Elements to the Header" data-icon="lucide:layout-template" data-href="#how-to-add-custom-elements-to-the-header">
+    Learn how to use the `addons` render prop to extend the `Header` component with custom buttons, navigation, or other interactive elements.
+  </x-card>
+  <x-card data-title="Handle Optional Component Dependencies" data-icon="lucide:puzzle" data-href="#how-to-handle-optional-component-dependencies">
+    Implement a workflow that prompts administrators to install required components on-demand, ensuring your blocklet's features run smoothly.
+  </x-card>
+  <x-card data-title="Implement Real-time User Notifications" data-icon="lucide:bell-ring" data-href="#how-to-implement-real-time-user-notifications">
+    Set up a real-time notification system using WebSockets to keep users informed of important events within your application.
+  </x-card>
+  <x-card data-title="Publish Resources with BlockletStudio" data-icon="lucide:rocket" data-href="#how-to-publish-resources-with-blockletstudio">
+    Integrate the `BlockletStudio` component to provide a user interface for publishing and managing resources and dependent components.
+  </x-card>
+</x-cards>
+
+---
+
+## How to Add Custom Elements to the Header
+
+The `Header` component is designed to be extensible. You can add custom buttons, search bars, or other React components directly into the header by leveraging the `addons` prop.
+
+### Goal
+
+To add a custom "Chat" button, a search input, and additional action icons to the main application header.
+
+### Prerequisites
+
+- A functional React application with the `@arcblock/ux` library installed.
+- An existing `<Header>` component instance. For more information, see the [Header component documentation](./components-layout-header.md).
+
+### Steps
+
+The `addons` prop accepts a render function. This function receives the default addons (like the session manager) as its first argument, allowing you to decide where to place your custom elements relative to the defaults.
+
+1.  **Define the `addons` Render Prop**
+
+    In your `Header` component, pass a function to the `addons` prop. This function should return the JSX you want to render.
+
+    ```jsx
+    <Header
+      meta={meta}
+      addons={(defaultAddons, { navigation }) => {
+        // Your custom components will go here
+        return (
+          <>
+            {/* Render your custom components */}
+            {defaultAddons}
+          </>
+        );
+      }}
+    />
+    ```
+
+2.  **Add Custom Components**
+
+    Inside the render function, you can add any components you need. In this example, we'll add a standard Material-UI `Button`, a few `AddonButton` components for icons, and a `Divider`.
+
+3.  **Combine with Default Addons**
+
+    It is standard practice to render the `defaultAddons` that are passed into the function. This ensures that essential elements like the locale switcher and session manager are still displayed. You can place your custom components before or after the `defaultAddons`.
+
+### Complete Example
+
+Here is a complete example demonstrating how to add several custom elements to the header. This includes navigation, buttons, and icons, rendered alongside the default session manager.
+
+```javascript How to Add Custom Elements to the Header icon=logos:react
+import { Box, Divider, Button } from '@mui/material';
+import { SessionContext } from '@arcblock/did-connect-react/lib/Session';
+import { AddonButton } from '@arcblock/ux/lib/Header/addon-button';
+import NavMenu from '@arcblock/ux/lib/NavMenu';
+import SessionManager from '@arcblock/ux/lib/SessionManager';
+import Header from '@arcblock/ux/lib/Header';
+import { Icon } from '@iconify/react';
+
+// Mock data for demonstration purposes
+const mockBlockletMeta = {
+  title: 'My App',
+  description: 'A great application',
+  logoUrl: 'https://www.arcblock.io/image-bin/uploads/eb1cf5d60cd85c42362920c49e3768cb.svg'
+};
+
+const mockSessionContextValue = {
+  session: {
+    user: {
+      fullName: 'Demo User',
+      did: 'z1ex...',
+      role: 'admin',
+    },
+    // ... other session properties
+  },
+};
+
+export default function CustomHeaderGuide() {
+  const meta = {
+    ...mockBlockletMeta,
+    enableConnect: true,
+    enableLocale: true,
+  };
+
+  return (
+    <SessionContext.Provider value={mockSessionContextValue}>
+      <Header
+        meta={meta}
+        homeLink="https://www.arcblock.io"
+        addons={(defaultAddons, { navigation }) => (
+          <>
+            {/* 1. Add custom navigation */}
+            {navigation.navItems?.length > 0 && (
+              <NavMenu
+                activeId={navigation.activeId}
+                items={navigation.navItems}
+                className="header-nav"
+              />
+            )}
+            {/* 2. Add a custom button */}
+            <Button variant="contained" color="primary" size="small">
+              Button
+            </Button>
+            {/* 3. Add custom icon buttons */}
+            <AddonButton icon={<Icon icon="tabler:message-circle" />}>Chat</AddonButton>
+            <AddonButton icon={<Icon icon="tabler:bell" />} />
+            <Divider orientation="vertical" flexItem sx={{ height: 12, alignSelf: 'center' }} />
+            {/* 4. Render the default addons (includes session manager) */}
+            {defaultAddons}
+          </>
+        )}
+      />
+    </SessionContext.Provider>
+  );
+}
+```
+
+---
+
+## How to Handle Optional Component Dependencies
+
+Many blocklets rely on other components to provide specific features. The `ComponentInstaller` allows you to build features that depend on optional components, and if they are not installed, it provides a user-friendly way for an administrator to install them.
+
+### Goal
+
+To protect a feature that requires another blocklet component to be installed. If the component is missing, an administrator will be shown an interface to install it, while other users will see nothing.
+
+### Prerequisites
+
+- A feature in your application that depends on another component (e.g., a "Media Manager" that requires the "Media Kit" blocklet).
+- The DID of the component dependency.
+- Familiarity with user roles (`owner`, `admin`).
+
+### Steps
+
+1.  **Import `ComponentInstaller`**
+
+    First, import the component from the library.
+
+    ```javascript
+    import ComponentInstaller from '@arcblock/ux/lib/ComponentInstaller';
+    ```
+
+2.  **Wrap Your Feature**
+
+    Wrap the component or feature that has the dependency with the `ComponentInstaller`.
+
+3.  **Provide the Component DID**
+
+    Pass the DID of the required component to the `did` prop. This can be a single string or an array of strings if there are multiple dependencies.
+
+4.  **Configure Behavior for Non-Admins**
+
+    Use the `noPermissionMute` prop. When set to `true`, users who do not have permission to install components (i.e., non-admins) will not see the installation prompt. You can provide a `fallback` component to show them instead.
+
+### Complete Example
+
+In this scenario, we have a `MyFeatureButton` that should only be rendered if the component with DID `z8ia...` is installed.
+
+```javascript How to Handle Optional Component Dependencies icon=logos:react
+import ComponentInstaller from '@arcblock/ux/lib/ComponentInstaller';
+import { Button } from '@mui/material';
+
+const REQUIRED_COMPONENT_DID = 'z8ia1mAXo8ZE7ytGF36L5uBf9kD2kenhqFGp9'; // Example DID
+
+// This is the component that requires the dependency
+function MyFeatureButton() {
+  return <Button variant="contained">Use Awesome Feature</Button>;
+}
+
+export default function OptionalComponentGuide() {
+  return (
+    <ComponentInstaller
+      // The DID of the component to check for
+      did={REQUIRED_COMPONENT_DID}
+      // A list of roles that are allowed to see the installer UI
+      roles={['owner', 'admin']}
+      // If true, non-admins will not see the installer UI
+      noPermissionMute
+      // Optional: What to show non-admins if the component is not installed
+      fallback={<div>This feature is not available.</div>}
+      // A callback that fires after a successful installation
+      onInstalled={() => console.log('Component was installed successfully!')}
+    >
+      {/* This child will only be rendered if the component is already installed */}
+      <MyFeatureButton />
+    </ComponentInstaller>
+  );
+}
+```
+
+When an admin visits this page and the component is not installed, they will see a pop-up allowing them to install it. A regular user will see the fallback message. Once installed, all users will see the `MyFeatureButton`.
+
+---
+
+## How to Implement Real-time User Notifications
+
+You can provide users with real-time feedback and notifications by listening to WebSocket events from the Blocklet Server. The `NotificationAddon` component is a ready-to-use solution for displaying an unread notification count in the header.
+
+### Goal
+
+To add a notification bell icon to the application header that displays a badge with the count of unread notifications and updates in real-time.
+
+### Prerequisites
+
+- Your blocklet must be running on a Blocklet Server version that supports the notification service (`1.16.42` or higher).
+- A `<Header>` component where the notification icon will be placed.
+- A session context providing user information.
+
+### Key Concepts
+
+- **WebSocket Events**: The Blocklet Server broadcasts events when notifications are created or read.
+- **`useListenWsClient`**: A hook to get a WebSocket client instance for a specific channel (e.g., 'user').
+- **Event Naming**: Events are scoped to the user and blocklet. The format for new notifications is `${blocklet.did}/${user.did}/notification:blocklet:create`.
+
+### Steps
+
+The `NotificationAddon` component encapsulates all the required logic for listening to WebSocket events and displaying the unread count.
+
+1.  **Import `NotificationAddon`**
+
+    ```javascript
+    import NotificationAddon from '@arcblock/ux/lib/common/notification-addon';
+    ```
+
+2.  **Add to Header `addons`**
+
+    The simplest way to use this is to add it inside the `Header`'s `addons` render prop.
+
+3.  **Pass the Session Object**
+
+    The `NotificationAddon` component requires the `session` object to identify the current user and manage the unread count state.
+
+### Complete Example
+
+This example shows how to integrate the `NotificationAddon` into the `Header`. It will automatically connect to the WebSocket, listen for events, and update the badge count.
+
+```javascript How to Implement Real-time User Notifications icon=logos:react
+import { SessionContext } from '@arcblock/did-connect-react/lib/Session';
+import Header from '@arcblock/ux/lib/Header';
+import NotificationAddon from '@arcblock/ux/lib/common/notification-addon';
+
+// Mock data for demonstration purposes
+const mockBlockletMeta = {
+  title: 'My App',
+  description: 'A great application',
+  logoUrl: 'https://www.arcblock.io/image-bin/uploads/eb1cf5d60cd85c42362920c49e3768cb.svg'
+};
+
+const mockSessionContextValue = {
+  session: {
+    user: {
+      fullName: 'Demo User',
+      did: 'z1ex...',
+      role: 'admin',
+    },
+    unReadCount: 3, // Initial unread count
+    setUnReadCount: () => {}, // State setter function
+    // ... other session properties
+  },
+};
+
+export default function NotificationGuide() {
+  const meta = { ...mockBlockletMeta, enableConnect: true };
+
+  return (
+    <SessionContext.Provider value={mockSessionContextValue}>
+      <Header
+        meta={meta}
+        addons={(defaultAddons) => (
+          <>
+            {/* The NotificationAddon will handle real-time updates */}
+            <NotificationAddon session={mockSessionContextValue.session} />
+            {defaultAddons}
+          </>
+        )}
+      />
+    </SessionContext.Provider>
+  );
+}
+```
+
+When a new notification for the logged-in user is created, the badge count on the bell icon will automatically increment. Clicking the icon will navigate the user to their notifications page.
+
+---
+
+## How to Publish Resources with BlockletStudio
+
+The `BlockletStudio` component provides a complete, embeddable UI for publishing resources and components. It handles user connection, resource selection, and the release process, simplifying a complex workflow into a single component.
+
+### Goal
+
+To add a button that opens a dialog, allowing users to select and publish files and dependent components from the blocklet.
+
+### Prerequisites
+
+- An API endpoint in your blocklet that returns a list of available resources.
+- The DID of the component that provides the publishing UI (the "studio" component).
+
+### Steps
+
+1.  **Import `BlockletStudio` and Manage State**
+
+    You'll need to manage the visibility of the studio dialog using component state.
+
+    ```javascript
+    import { useState } from 'react';
+    import { BlockletStudio } from '@arcblock/ux/lib/BlockletStudio';
+    import { Button, CircularProgress } from '@mui/material';
+    ```
+
+2.  **Render the Component**
+
+    Place the `<BlockletStudio />` component in your app and control its visibility with the `open` and `setOpen` props.
+
+3.  **Configure Essential Props**
+
+    - `componentDid`: The DID of the studio blocklet that provides the publishing service.
+    - `title`, `description`: Metadata for the item being published.
+    - `resourcesParams`: An object passed as query parameters to your resource-fetching API.
+    - `components`: An array of components to be pre-selected or required.
+    - `resources`: An object specifying which resources to pre-select.
+
+4.  **Handle Lifecycle Events**
+
+    Use the `onOpened`, `onUploaded`, and `onReleased` callbacks to respond to events in the publishing lifecycle, such as hiding a loading spinner or showing a success message.
+
+### Complete Example
+
+This example shows a button that, when clicked, opens the `BlockletStudio` dialog. It also demonstrates managing a loading state for a better user experience.
+
+```javascript How to Publish Resources with BlockletStudio icon=logos:react
+import { useState } from 'react';
+import { Button, CircularProgress } from '@mui/material';
+import { BlockletStudio } from '@arcblock/ux/lib/BlockletStudio';
+
+// The DID of the blocklet that provides the studio/publishing UI
+const AI_STUDIO_COMPONENT_DID = 'z8ia1mAXo8ZE7ytGF36L5uBf9kD2kenhqFGp9'; // Example DID
+
+export default function PublisherGuide() {
+  const [isStudioOpen, setStudioOpen] = useState(false);
+  const [isOpening, setOpening] = useState(false);
+
+  const handleShowDialog = () => {
+    setOpening(true);
+    setStudioOpen(true);
+  };
+
+  return (
+    <>
+      <Button
+        variant="contained"
+        onClick={handleShowDialog}
+        disabled={isOpening}
+        startIcon={isOpening ? <CircularProgress size={16} /> : null}>
+        Publish to Studio
+      </Button>
+
+      <BlockletStudio
+        // Controls the dialog's visibility
+        open={isStudioOpen}
+        setOpen={setStudioOpen}
+        // Basic information for the published item
+        title="My Demo Project"
+        description="This is a project published from my blocklet."
+        // The DID of the studio service component
+        componentDid={AI_STUDIO_COMPONENT_DID}
+        // Parameters sent to your blocklet's resource API
+        resourcesParams={{ projectId: 'test-project-123' }}
+        // Pre-selected components
+        components={[
+          { did: 'z8ia3xzq2tMq8CRHfaXj1BTYJyYnEcHbqP8cJ', included: true, required: true },
+          { did: 'z2qZyjnsRffFtn2PDnDwDHTRbAu53RpKqDtFZ', included: true, required: false },
+        ]}
+        // Pre-selected resources
+        resources={{
+          // The key is the DID of the resource provider blocklet
+          z8iZpog7mcgcgBZzTiXJCWESvmnRrQmnd3XBB: [
+            'template-448698592710885376',
+            'example-448698592710885376',
+          ],
+        }}
+        // Event handlers
+        onOpened={() => setOpening(false)}
+        onUploaded={() => alert('Upload complete!')}
+        onReleased={() => {
+          alert('Successfully released!');
+          setStudioOpen(false);
+        }}
+      />
+    </>
+  );
+}
+```