@blockprotocol/hook

Block Protocol – Hook Module

This package implements the Block Protocol Hook module for blocks and embedding applications.

To get started:

1. yarn add @blockprotocol/hook or npm install @blockprotocol/hook
2. Follow the instructions to use the hook module as a block or an embedding application

Blocks

To create a HookBlockHandler, pass the constructor an element in your block, along with any callbacks you wish to register to handle incoming messages.

To send a hook message, you call the hook function.

import { HookBlockHandler } from "@blockprotocol/hook";

const handler = new HookBlockHandler({ element });

handler.hook({
  data: {
    hookId: null, // the embedding application will provide a hookId in response to use in future messages
    node, // a reference to the DOM node to render into
    type: "text", // the type of hook
    entityId: "entity1", // the id of the entity this hook will show/edit data for
    path: ["http://example.com/property-type/text/"], // the path in the entity's properties data will be taken from/saved to
  },
});

React example

For React, we provide a useHookBlockModule hook, which accepts a ref to an element. This will return an object with the shape of { hookModule: HookBlockHandler | null } which you can use to send hook messages.

We also provide a useHook hook to make sending hook messages easier.

import { useHook } from "@blockprotocol/hook/react";

useHook(
  hookModule,
  nodeRef,
  "text",
  ["http://example.com/property-type/text/"],
  (node) => {
    node.innerText = "hook fallback";

    return () => {
      node.innerText = "";
    };
  },
);

Where nodeRef is a RefObject containing the DOM node you'd like to pass to the embedding application.

Custom element example

You can use the firstUpdate Lit lifecycle hook to request that the embedding application take over control of a DOM node.

export class MyBlock extends BlockElementBase {
  private hookModule?: HookBlockHandler;

  firstUpdated() {
    if (!this.hookModule || this.hookModule.destroyed) {
      this.hookModule = new HookBlockHandler({
        element: this,
      });
    }

    const paragraph = this.renderRoot.querySelector(`#my-hook-paragraph`);
    if (!paragraph || !(paragraph instanceof HTMLParagraphElement)) {
      throw new Error("No paragraph element for hook module found in element DOM");
    }

    void this.hookModule.hook({
      data: {
        node: paragraph,
        entityId: this.getBlockEntity()?.metadata.recordId.entityId,
        hookId: null,
        path: [extractBaseUrl(propertyTypes.description.$id)],
        type: "text",
      },
    });
  }

  render() {
    return html`
      <p id="my-hook-paragraph"></p>
    `;
  }

Embedding applications

To create a HookEmbedderHandler, pass the constructor:

1. An element wrapping your block
2. callbacks to respond to messages from the block
3. The starting values for any of the following messages you implement:

• hook

import { HookEmbedderHandler } from "@blockprotocol/hook";

const hookIds = new WeakMap<HTMLElement, string>();
const nodes = new Map<string, HTMLElement>();

const generateId = () => (Math.random() + 1).toString(36).substring(7);

const hookModule = new HookEmbedderHandler({
  callbacks: {
    hook({ data }) {
      if (data.hookId) {
        const node = nodes.get(data.hookId);

        if (node) node.innerText = "";
        nodes.delete(data.hookId);
      }

      const hookId = data.hookId ?? generateId();

      if (data.node) {
        nodes.set(hookId, data.node);
        data.node.innerText = `Hook of type ${data.type} for path ${data.path}`;
      }

      return { hookId };
    },
  },
  element: elementWrappingTheBlock,
});

React

For React embedding applications, we provide a useHookEmbedderModule hook, which accepts a ref to an element, and optionally any additional constructor arguments you wish to pass.

import { useHookEmbedderModule } from "@blockprotocol/hook/react";
import { useRef } from "react";

export const App = () => {
  const wrappingRef = useRef<HTMLDivElement>(null);

  useHookEmbedderModule(blockRef, {
    hook({ data }) {
      // As above
    },
  });

  return (
    <div ref={wrappingRef}>
      <Block />
    </div>
  );
};