@blockprotocol/graph
v0.3.4
Published
Implementation of the Block Protocol Graph service specification for blocks and embedding applications
Downloads
102,385
Readme
Block Protocol – Graph module
This package implements the Block Protocol Graph module for blocks and embedding applications.
Getting started
If you are a block author, we have several block templates available which use this package
npx create-block-app@latest --help
The best way to get started is to read the docs.
stdlib
The package exports a standard library of helper functions for interacting with a Subgraph
, available from "@blockprotocol/graph/stdlib"
. For example
import { getOutgoingLinkAndTargetEntities } from "@blockprotocol/graph/stdlib";
// find the outgoing links and target entities for a given entity
const linkAndTargetEntities = getOutgoingLinkAndTargetEntities(
subgraph,
"entity-123",
);
for (const { linkEntity, rightEntity } of linkAndTargetEntities) {
// do something with each link and the entity it points to
}
For a full list of available functions see src/stdlib.ts
Initializing a graph module handler
If you want to roll your own block template or embedding application, you can use this package to construct a handler for graph module messages.
yarn add @blockprotocol/graph
ornpm install @blockprotocol/graph
- Follow the instructions to use the graph module as a block or an embedding application
Blocks
To create a GraphBlockHandler
, pass the constructor an element in your block, along with any callbacks you wish to register to handle incoming messages.
React
For React, we provide a useGraphBlockModule
hook, which accepts a ref
to an element, and optionally any callbacks
you wish to provide on initialization.
See npx create-block-app@latest my-block --template react
for an example.
Custom elements
For custom elements, this package exports a BlockElementBase
class
which uses the Lit framework, and sets graphModule
on the instance for sending graph-related messages to the embedding application.
See npx create-block-app@latest my-block --template custom-element
for an example.
Embedding applications
You should construct one GraphEmbedderHandler
per block.
It is not currently possible to wrap multiple blocks with a single handler.
To create a GraphEmbedderHandler
, pass the constructor:
- An
element
wrapping your block callbacks
to respond to messages from the block- The starting values for the following messages:
blockEntitySubgraph
: the graph rooted at the block entityreadonly
: whether or not the block should be in 'readonly' mode
These starting values should also be passed in a graph
property object, if the block can be passed or assigned properties.
See the here or check the TypeScript types for message signatures.
import { GraphEmbedderHandler } from "@blockprotocol/graph";
const graphModule = new GraphEmbedderHandler({
blockEntitySubgraph: { ... }, // subgraph containing vertices, edges, and 'roots' which should be a reference to the block entity
readonly: false,
callbacks: {
updateEntity: ({ data }) => updateEntityInYourDatastore(data),
},
element: elementWrappingTheBlock,
});
React
For React embedding applications, we provide a useGraphEmbedderModule
hook, which accepts a ref
to an element, and optionally any additional constructor arguments you wish to pass.
import { useGraphEmbedderModule } from "@blockprotocol/graph";
import { useRef } from "react";
export const App = () => {
const wrappingRef = useRef<HTMLDivElement>(null);
const blockEntitySubgraph = { ... }; // subgraph containing vertices, edges, and 'roots' which should be a reference to the block entity
const { graphModule } = useGraphEmbedderModule(blockRef, {
blockEntitySubgraph,
});
return (
<div ref={wrappingRef}>
<Block graph={{ blockEntitySubgraph }} />
</div>
);
};