DIDSpaceConnection

The DIDSpaceConnection component is a versatile UI card designed to display key information about a connected DID Space. It provides a clear and interactive way to present the space's details, including its NFT avatar, name, DID, and current connection status.

This component is highly customizable, allowing you to add custom actions and footer content to tailor the user experience to your application's needs.

Props

endpoint string (required) — The API endpoint URL for the DID Space object. Example: https://example.com/app/api/space/{spaceDid}/app/{appDid}/object/.
selected boolean (default: false) — If true, the card will have a highlight border and display the connection status.
compat boolean — If true, enforces a compact layout. If undefined, it automatically switches to a compact layout on mobile devices.
action React.ReactNode | ((props: DIDSpaceConnectionContext) => React.ReactNode) (default: null) — Custom content or a component to render in the action area of the card.
footer boolean | React.ReactNode | ((props: DIDSpaceConnectionContext & { originalFooter: React.ReactNode }) => React.ReactNode) (default: false) — Custom content for the footer. If set to true, it displays the latest audit log by default.
deps any[] (default: []) — An array of dependencies that, when changed, will trigger a refresh of the DID Space information.

Context Types

When using function props for action or footer, you receive a context object with the following shape:

DIDSpaceConnectionContext

spaceGateway DIDSpaceGateway (required) — Contains essential information about the connected DID Space.
spaceStatus DIDSpaceStatus (required) — The current connection status of the DID Space.
errorCode number (required) — A specific error code if the spaceStatus is 'unavailable'.
selected boolean (required) — The value of the selected prop passed to the component.
compat boolean (required) — Indicates if the component is in compact mode.
refresh () => void (required) — A function to manually trigger a refresh of the space information and status.

DIDSpaceGateway

did string (required) — The DID of the space.
name string (required) — The name of the space.
url string (required) — The base URL of the DID Space gateway (e.g., https://spaces.arcblock.io).
endpoint string (required) — The full object endpoint URL.
ownerDid string (required) — The DID of the space owner.

DIDSpaceStatus

DIDSpaceStatus enum — An enum representing the connection status. Possible values include: loading, connected, disconnected, unavailable.

Basic Usage

To display a DID Space, you only need to provide the endpoint prop. The component will handle fetching and displaying the necessary information.

Basic DIDSpaceConnection Example

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

export default function Demo() {
  const endpoint = 'https://arcblock.net/app/api/space/z8iZufAgx4Z1y5tA5y5Q4z4a5y5Q4z4a5y5Q/app/zNKd5QmRt3h5VX8u4J4egJkA4xQaDKwM2n5D/object/';

  return <DIDSpaceConnection endpoint={endpoint} />;
}

Usage Scenarios

Selected State and Status

Set the selected prop to true to apply a highlight border and display the connection status. This is useful for indicating the currently active or selected DID Space in a list.

Selected DIDSpaceConnection

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

export default function Demo() {
  const endpoint = 'https://arcblock.net/app/api/space/z8iZufAgx4Z1y5tA5y5Q4z4a5y5Q4z4a5y5Q/app/zNKd5QmRt3h5VX8u4J4egJkA4xQaDKwM2n5D/object/';

  return <DIDSpaceConnection endpoint={endpoint} selected />;
}

Compact Layout

Use the compat prop to render a more condensed version of the card, which is ideal for lists or mobile views.

Compact DIDSpaceConnection

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

export default function Demo() {
  const endpoint = 'https://arcblock.net/app/api/space/z8iZufAgx4Z1y5tA5y5Q4z4a5y5Q4z4a5y5Q/app/zNKd5QmRt3h5VX8u4J4egJkA4xQaDKwM2n5D/object/';

  return <DIDSpaceConnection endpoint={endpoint} selected compat />;
}

Custom Actions

You can add custom interactive elements like buttons or links using the action prop. Pass a function to access the connection context, including the spaceGateway details and the refresh function.

Example 1: Reconnect a Disconnected Space

A common use case is to provide a way for users to reconnect if their session becomes disconnected. You can check the spaceStatus and render a DIDSpaceConnect component to initiate the reconnection flow. The DIDSpaceConnect component renders a button by default.

DIDSpaceConnection with Reconnect Action

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

export default function Demo() {
  const endpoint = 'https://arcblock.net/app/api/space/z8iZufAgx4Z1y5tA5y5Q4z4a5y5Q4z4a5y5Q/app/zNKd5QmRt3h5VX8u4J4egJkA4xQaDKwM2n5D/object/';

  return (
    <DIDSpaceConnection
      endpoint={endpoint}
      selected
      action={({ spaceStatus, spaceGateway, refresh }) => {
        if (spaceStatus === DIDSpaceStatus.DISCONNECTED) {
          return (
            <DIDSpaceConnect
              reconnect
              spaceDid={spaceGateway.did}
              spaceGatewayUrl={spaceGateway.url}
              onSuccess={refresh} // Refresh the card after successful reconnection
            />
          );
        }
        return null;
      }}
    />
  );
}

Example 2: Open DID Space Site

This example adds an icon button that links to the DID Space's public page.

DIDSpaceConnection with Custom Action

import { DIDSpaceConnection } from '@blocklet/did-space-react';
import { IconButton, Link } from '@mui/material';
import OpenInNewIcon from '@mui/icons-material/OpenInNew';

export default function Demo() {
  const endpoint = 'https://arcblock.net/app/api/space/z8iZufAgx4Z1y5tA5y5Q4z4a5y5Q4z4a5y5Q/app/zNKd5QmRt3h5VX8u4J4egJkA4xQaDKwM2n5D/object/';

  return (
    <DIDSpaceConnection
      endpoint={endpoint}
      selected
      action={({ spaceGateway }) => (
        <IconButton
          size="small"
          component={Link}
          href={`${spaceGateway.url}/space/${spaceGateway.did}`}
          target="_blank"
        >
          <OpenInNewIcon />
        </IconButton>
      )}
    />
  );
}

Custom Footer

The footer prop allows for powerful customization. You can enable the default audit log display or render completely custom content.

Displaying Default Audit Log

Set footer to true to automatically fetch and display the latest audit log entry for the application within that DID Space.

DIDSpaceConnection with Audit Log Footer

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

export default function Demo() {
  const endpoint = 'https://arcblock.net/app/api/space/z8iZufAgx4Z1y5tA5y5Q4z4a5y5Q4z4a5y5Q/app/zNKd5QmRt3h5VX8u4J4egJkA4xQaDKwM2n5D/object/';

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

Adding Custom Footer Content

Provide a function to the footer prop to render custom components. The function receives the connection context and the originalFooter (the default audit log bar), allowing you to compose your own layout.

DIDSpaceConnection with Custom Footer Content

import { DIDSpaceConnection } from '@blocklet/did-space-react';
import { Box, Typography } from '@mui/material';

export default function Demo() {
  const endpoint = 'https://arcblock.net/app/api/space/z8iZufAgx4Z1y5tA5y5Q4z4a5y5Q4z4a5y5Q/app/zNKd5QmRt3h5VX8u4J4egJkA4xQaDKwM2n5D/object/';

  return (
    <DIDSpaceConnection
      endpoint={endpoint}
      selected
      footer={({ spaceGateway, originalFooter }) => (
        <>
          {/* Display the default audit log */}
          {originalFooter}
          {/* Display additional custom info */}
          <Box display="flex" alignItems="center" mt={1}>
            <Typography variant="caption">Owner: {spaceGateway.ownerDid}</Typography>
          </Box>
        </>
      )}
    />
  );
}

Connection Statuses

The component visually represents the state of the connection to the DID Space. Understanding these statuses can help in debugging and providing better user feedback.

Loading: The component is initially in a loading state while it fetches information about the DID Space. Skeleton loaders are displayed during this phase.
Connected: Indicates a successful and active connection. The application has the necessary permissions and the DID Space is fully operational. It is displayed with a 'Connected' tag and a success icon.
Disconnected: The application is not authorized to access the DID Space. This typically means the user needs to go through a connection flow to grant permissions. It is displayed with a 'Disconnected' tag and a neutral icon.
Unavailable: The DID Space cannot be reached or used due to an issue. This status is shown with an error tag and icon. When unavailable, a tooltip provides more details on hover. Common reasons include:
- Subscription Expired/Past Due: The subscription for the DID Space has expired.
- Usage Limit Exceeded: The DID Space has reached its usage limits.
- Incompatible Version: The DID Space version is not compatible with the component library's requirements.
- CORS Blocked: A Cross-Origin Resource Sharing (CORS) error is preventing the connection. This usually requires a configuration change on the DID Space host.
- Network Error: The component could not reach the DID Space endpoint due to a network issue like a timeout or DNS failure.

Now that you know how to display DID Space information, you may want to dive deeper into the data structures used by the components. For more details, please see the API Reference for Types.