Getting Started

This package provides React components designed to help you seamlessly integrate and interact with DID Space. With these components, you can easily enable users to connect to and display information about their DID Space.

# install
npm install @blocklet/did-space-react

Core Components

This package includes two key components:

1. DIDSpaceConnect: A button for connecting or reconnecting to DID Space.
2. DIDSpaceConnection: A display card showcasing details of the connected DID Space.

How to use

DIDSpaceConnect

The DIDSpaceConnect component enables users to establish a connection with DID Space. Here are the main usage scenarios:

Connecting to a Specific DID Space

This component allows you to easily create a button on the page to connect to a DID Space. After clicking the button and successfully connecting to the DID Space, the system will return a spaceGateway object, which contains information such as the DID Space's name, DID, and site URL. You can choose how to store this object based on your needs.

Example:

import Toast from '@arcblock/ux/lib/Toast';
import { DIDSpaceConnect, type DIDSpaceGateway } from '@blocklet/did-space-react';

export default function Demo() {
  const onSuccess = async ({ spaceGateway }: { spaceGateway: DIDSpaceGateway }) => {
    try {
      // do something with spaceGateway
    } catch (error) {
      console.error(error);
      Toast.error(formatError(error));
    }
  };

  return <DIDSpaceConnect {...rest} onSuccess={onSuccess} />;
}

Connecting DID Space for Users

When users connect to DID Space for the first time, the DIDSpaceConnect component will automatically save the spaceGateway to their account. This data can later be retrieved through session.user.didSpace.

Example:

import { DIDSpaceConnect } from '@blocklet/did-space-react';

export default function Demo() {
  const session = useSessionContext();

  return <DIDSpaceConnect session={session} />;
}

Reconnecting to a Specific DID Space

If the user needs to reconnect to a previously linked DID Space, you need to set reconnect to true and provide spaceDid and spaceGatewayUrl props. This turns the component into a reconnect button that triggers a reconnection request.

Example:

import { DIDSpaceConnect } from '@blocklet/did-space-react';

export default function Demo() {
  const session = useSessionContext();
  const { did, url } = session.user?.didSpace ?? {};

  if (did && url) {
    return <DIDSpaceConnect reconnect spaceDid={did} spaceGatewayUrl={url} />;
  }

  return null;
}

DIDSpaceConnection

The DIDSpaceConnection component is a versatile UI element designed to display key information about the connected DID Space. It enhances the user experience by providing context and interactivity.

Key Features:

1. Display Information: Shows details like the DID Space name, DID, and URL.
2. Connection Status: If the selected attribute is provided, it also displays the connection status and action buttons.
3. Responsive Design: Adapts to various screen sizes, ensuring usability on mobile and desktop devices.
4. Compact Mode: Use the compat attribute to enforce a compact layout.

Example:

import { DIDSpaceConnection } from '@blocklet/did-space-react';

export default function Demo() {
  // This is just a sample template, the actual endpoint address can be obtained from `spaceGateway.endpoint`
  const endpoint = 'https://${spaceDomain}/app/api/space/${spaceDid}/app/${appDid}/object/';

  return (
    <>
      {/* basic use */}
      <DIDSpaceConnection endpoint={endpoint} selected />
      {/* enforce compat layout */}
      <DIDSpaceConnection endpoint={endpoint} selected compat />
    </>
  );
}

Custom Actions

You can enhance the DIDSpaceConnection by customizing the action buttons through the action attribute. This allows you to tailor the functionality to your specific application needs.

Example:

import { DIDSpaceConnection } from '@blocklet/did-space-react';

export default function Demo() {
  const endpoint = 'https://${spaceDomain}/app/api/space/${spaceDid}/app/${appDid}/object/';

  return (
    <DIDSpaceConnection
      endpoint={x.endpoint}
      selected
      action={({ spaceGateway, selected, refresh }) => (
        // open DID Space site
        <IconButton
          size="small"
          LinkComponent={Link}
          href={`${spaceGateway.url}/space/${spaceGateway.did}`}
          target="_blank"
        >
          <OpenInNewIcon />
        </IconButton>
      )}
    />
  );
}

Custom Footer

You can customize the footer content of DIDSpaceConnection through the footer attribute. By default, when footer is set to true, it displays the latest audit log information. You can also provide your own custom footer content.

Example 1: Display the latest audit log by default

import { DIDSpaceConnection } from '@blocklet/did-space-react';

export default function Demo() {
  const endpoint = 'https://${spaceDomain}/app/api/space/${spaceDid}/app/${appDid}/object/';

  return <DIDSpaceConnection endpoint={x.endpoint} selected footer />;
}

Example 2: Custom Footer Content

import { DIDSpaceConnection } from '@blocklet/did-space-react';

export default function Demo() {
  const endpoint = 'https://${spaceDomain}/app/api/space/${spaceDid}/app/${appDid}/object/';

  return (
    <DIDSpaceConnection
      endpoint={x.endpoint}
      selected
      footer={({ spaceGateway, selected, refresh, originalFooter }) => (
        <>
          {/* display the latest audit log */}
          {originalFooter}
          {/* display DID Space version number */}
          <Box display="flex" alignItems="center">
            <Typography>{spaceGateway.version}</Typography>
          </Box>
        </>
      )}
    />
  );
}