Workspace agent

Ask questions about this workspace or preview add-only changes.

Organigram React

Organigram React provides the React components and hooks of Organigram.ai: diagrams of organizations built on the Organigram Protocol, the screens to propose and decide through procedures, and the chat panel of the workspace agent. It builds on @organigram/js, which reads and writes the contracts.

Installation


pnpm add @organigram/react @organigram/js viem recoil react-flow-renderer @mui/material @mui/icons-material react-i18next

The components use MUI for their styles and Recoil for the state they share, so wrap your application in a RecoilRoot and, to get the Organigram look, in a MUI ThemeProvider with theme. The theme expects its fonts at /fonts/*.woff2: copy node_modules/@organigram/react/dist/fonts to the public assets of your application.

How it works

Drawing an organigram

Diagram draws an organigram as an interactive graph: organs, procedures and assets are nodes, and the permissions they hold on each other are links. Users can move the nodes, and onNodePositionsChange lets you save their positions. ClassicOrgChart draws the same organigram as a classic tree, where an organ sits below the organ whose members decide on its membership.

Both take an organigram as plain JSON, from organigram.toJson(). Layers, defined by your application, let users show only part of a large organigram: useLayers filters the organigram for either view and remembers the active layers.

Proposals and decisions

procedures holds the screens of each procedure type, by type name: Component describes a procedure, and Proposal shows a proposal with the actions the connected account may take, such as voting or blocking it.

The workspace agent

AgentPanel is the chat panel of the workspace agent, including the preview of the changes the agent proposes, which the user confirms or cancels. They only render: your application sends the messages to its agent and stores the conversations. Every text can be replaced through the labels props, to translate them.

Usage


import { RecoilRoot } from 'recoil'
import { ThemeProvider, createTheme, type ThemeOptions } from '@mui/material/styles'
import { Diagram, theme, useOrganigramClient } from '@organigram/react'
import { Organigram, getTemplate } from '@organigram/js'
import { createPublicClient, http } from 'viem'
import { sepolia } from 'viem/chains'
const publicClient = createPublicClient({ chain: sepolia, transport: http() })
const OrganigramView = () => {
  const client = useOrganigramClient(publicClient, null, sepolia.id)
  const organigram = new Organigram(getTemplate('nonProfit', client?.chainId ?? String(sepolia.id)))
  return <Diagram organigram={organigram.toJson()} controls style={{ height: 600 }} />
}
export const App = () => (
  <RecoilRoot>
    <ThemeProvider theme={createTheme(theme as ThemeOptions)}>
      <OrganigramView />
    </ThemeProvider>
  </RecoilRoot>
)

Contributing

We are looking for React developers and testers to keep this project secure and up to date. Please open issues on GitHub, fork the repository and send pull requests.

Diagrams

Diagram draws an organigram as a graph of organs, procedures and assets, linked by the permissions they hold on each other. ClassicOrgChart draws it as a tree of organs and their members. Both take the organigram as plain JSON, from organigram.toJson(), and the node components can be used on their own.

Diagram

Draw an organigram as an interactive diagram: organs, procedures and assets, linked by the permissions they hold on each other.


<Diagram organigram={organigram.toJson()} onClickOrgan={organ => open(organ)} controls />

Definition


const Diagram: React.FC<DiagramProps>

DiagramProps

Props accepted by the default Diagram component.

Property	Type	Description
`controls`	`boolean`	Whether to show the zoom controls.
`direction`	`string`	Layout direction: `TB` from top to bottom, or `LR` from left to right.
`displayOptions`	`DiagramDisplayOptions`	Which permission links to draw.
`edgeType`	`OrganigramEdgeType`	Line style of the links.
`entryUsers`	`Record<string, DiagramEntryUser>`	Names and avatars of the members, by address.
`isTabletOrAbove`	`boolean`	Whether the screen is at least tablet-sized, to place the controls.
`nodeTypes`	`NodeTypes`	React Flow node components, by node type. Defaults to `defaultNodeTypes`.
`options`	`ReactFlowProps`	Extra props passed to React Flow.
`organigram`	`OrganigramJson \| null`	Organigram to draw, or `null` while it loads.
`style`	`Record<string, unknown>`	Style of the diagram container.

DiagramProps.onClickAsset

Called when the user clicks an asset.

Signature


onClickAsset?: (asset: AssetJson) => void;

DiagramProps.onClickOrgan

Called when the user clicks an organ.

Signature


onClickOrgan?: (organ: OrganJson) => void;

DiagramProps.onClickProcedure

Called when the user clicks a procedure.

Signature


onClickProcedure?: (procedure: ProcedureJson) => void;

DiagramProps.onNodePositionsChange

Called when the user moves nodes, to save their positions.

Signature


onNodePositionsChange?: (nodePositions: OrganigramNodePositions) => void;

DiagramProps.translateLabel

Translation function for the labels.

Signature


translateLabel?: (label: string) => string;

ClassicOrgChart

Draw an organigram as a classic tree of organs and their members, as most people picture an organization chart.

Definition


const ClassicOrgChart: React.FC<ClassicOrgChartProps>

ClassicOrgChartProps

Props of ClassicOrgChart.

Property	Type	Description
`controls`	`boolean`	Whether to show the zoom controls.
`isTabletOrAbove`	`boolean`	Whether the screen is at least tablet-sized, to place the controls.
`organigram`	`OrganigramJson \| null`	Organigram to draw, or `null` while it loads.
`style`	`Record<string, unknown>`	Style of the chart container.
`testIdPrefix`	`string`	Prefix of the test identifiers of the nodes.

ClassicOrgChartProps.onClickOrgan

Called when the user clicks an organ.

Signature


onClickOrgan?: (organ: OrganJson) => void;

ClassicOrgChartProps.translateLabel

Translation function for the labels.

Signature


translateLabel?: (label: string) => string;

OrganNode

Default React Flow node used to display one organ inside a diagram.

Definition


const OrganNode: React.FC<Partial<NodeProps> & OrganNodeProps>

OrganNodeProps

Props accepted by the default organ node renderer.

Property	Type	Description
`data`	`{ organ: Organ; entryUsers?: Record<string, DiagramEntryUser>; position?: { x: number; y: number; }; isMaster?: boolean; onClick?: () => void; translateLabel?: (label: string) => string; }`	The organ, its members' names and avatars, and the click handler.
`hideHandles`	`boolean`	Whether to hide the connection handles, to show the node on its own.

DiagramEntryUser

Name and avatar shown for a member address.

Definition


export type DiagramEntryUser = {
    image?: string | null;
    name?: string | null;
};

ProcedureNode

Default React Flow node used to display one procedure inside a diagram.

Definition


const ProcedureNode: React.FC<Partial<NodeProps<{
    procedure: ProcedureJson;
    onClick?: (procedure: ProcedureJson) => void;
    organigram?: OrganigramJson;
    translateLabel?: (label: string) => string;
}>> & ProcedureNodeProps>

ProcedureNodeProps

Props accepted by the default procedure node renderer.

Property	Type	Description
`hideHandles`	`boolean`	Whether to hide the connection handles, to show the node on its own.
`organigram`	`OrganigramJson`	Organigram the procedure belongs to, to name the organs it links.

DiagramDisplayOptions

Which permission links a diagram draws.

Property	Type	Description
`showAdminPermissions`	`boolean`	Draw the permissions to manage permissions.
`showAssetsPermissions`	`boolean`	Draw the permissions to move funds.
`showEntriesPermissions`	`boolean`	Draw the permissions to change members and documents.

useDiagramDisplayOptions

Read and change the diagram display options, shared across the app.

Signature


useDiagramDisplayOptions: () => [DiagramDisplayOptions, SetterOrUpdater<DiagramDisplayOptions>]

ProcedureIcon

Procedure icon.

Signature


Procedure: (props: React.SVGProps<SVGSVGElement>) => import("react/jsx-runtime").JSX.Element

Layers

Layers are subsets of an organigram defined by your application, such as departments. useLayers filters the organigram for either view according to the layers the user selects, and remembers the selection in a storage you provide.

DiagramLayer

A named subset of an organigram, such as a department, that users can show or hide.

Property	Type	Description
`assets`	`ReadonlyArray<{ assetAddress: string; }>`	Assets in the layer.
`id`	`string`	Layer identifier.
`organs`	`ReadonlyArray<{ organAddress: string; }>`	Organs in the layer.
`procedures`	`ReadonlyArray<{ procedureAddress: string; }>`	Procedures in the layer.

DiagramLayerStorage

A key-value storage for the active layers, such as localStorage.

DiagramLayerStorage.getItem

Read a value.

Signature


getItem: (key: string) => string | null;

DiagramLayerStorage.setItem

Write a value.

Signature


setItem: (key: string, value: string) => void;

LayersState

The layers state returned by useLayers.

Property	Type	Description
`activeLayerIds`	`string[]`	Layers currently shown. Empty means everything is shown.
`classicVisibleOrganigram`	`OrganigramJson`	The organigram filtered for `ClassicOrgChart`.
`visibleOrganigram`	`OrganigramJson`	The organigram filtered for `Diagram`.

LayersState.showAll

Show every layer.

Signature


showAll: () => void;

LayersState.toggleLayer

Show or hide one layer.

Signature


toggleLayer: (layerId: string) => void;

UseLayersOptions

Options of useLayers.

Property	Type	Description
`storage`	`DiagramLayerStorage \| null`	Where to remember the active layers, such as `localStorage`. Without it, the selection is not kept.

UseLayersOptions.onStorageError

Called when the storage cannot be read or written.

Signature


onStorageError?: () => void;

useLayers

Applies user-selected visual layers to an organigram without owning layer persistence or editing. Applications provide their persisted definitions.

Signature


useLayers: (organigram: OrganigramJson, layers: ReadonlyArray<DiagramLayer>, options?: UseLayersOptions) => LayersState

Procedures

Screens to follow and decide on proposals. procedures gives, for each procedure type, a Component that describes the procedure and a Proposal that shows a proposal with the actions the connected account may take.

ElectionComponentProps

Props of the vote components.

Property	Type	Description
`accountInOrgans`	`{ proposers?: boolean; moderators?: boolean; deciders?: boolean; }`	Roles of the connected account in the procedure.
`compact`	`boolean`	Whether to use the condensed layout of lists.
`procedure`	`ERC20VoteProcedure \| VoteProcedure`	Vote procedure the proposal belongs to.
`proposal`	`ProcedureProposal`	Proposal being voted on.
`publicClient`	`PublicClient \| null`	Client used for reads, when the procedure has none.
`voterAddress`	`string`	Address whose vote is shown, by default the connected wallet.
`walletClient`	`WalletClient \| null`	Client that signs the vote, when the procedure has none.
`wrapTransaction`	`TransactionOptions['onTransaction']`	Called with each transaction as soon as it is sent, for example to show its progress.

ElectionComponentProps.t

Translation function for the labels.

Signature


t: (key: string) => string;

NominationProposalProps

Props of the proposal screen of a nomination procedure.

Property	Type	Description
`accountInOrgans`	`{ proposers?: boolean; moderators?: boolean; deciders?: boolean; }`	Roles of the connected account in the procedure.
`compact`	`boolean`	Whether to use the condensed layout of lists.
`procedure`	`NominationProcedure`	Nomination procedure the proposal belongs to.
`proposal`	`ProcedureProposal`	Proposal shown.
`publicClient`	`PublicClient \| null`	Client used for reads, when the procedure has none.
`walletClient`	`WalletClient \| null`	Client that signs the decision, when the procedure has none.
`wrapTransaction`	`TransactionOptions['onTransaction']`	Called with each transaction as soon as it is sent, for example to show its progress.

NominationProposalProps.t

Translation function for the labels.

Signature


t: (key: string, options?: any) => string;

procedures

UI of each procedure type: Component describes the procedure, Proposal shows a proposal and its decision.


const { Proposal } = procedures[procedure.typeName]

Workspace agent

The chat panel of the workspace agent, with the preview of the changes it proposes. These components only render: your application sends the messages to its agent and stores the conversations. Every text can be replaced through the labels props.

AgentPanel

Chat panel of the workspace agent: conversations, messages, document upload and proposed changes.

The panel only renders: the application sends the messages and stores the conversations.

Animated

Fade and slide its content in and out.

Definition


const Animated: React.FC<AnimatedProps>

AgentResponse

An answer of the workspace agent.

Definition


export type AgentResponse = {
    threadId?: string;
    message: string;
    citations: Citation[];
    preview?: OrganigramPreview;
};

AnimatedProps

Props of Animated.

Definition


export type AnimatedProps = {
    visible?: boolean;
    delay?: number;
    children: ReactNode;
    translateY?: number;
    cursor?: CSSProperties['cursor'];
    unmountOnExit?: boolean;
};

Citation

A workspace object the agent refers to in an answer.

Definition


export type Citation = {
    type: 'workspace' | 'organigram' | 'organ' | 'procedure' | 'asset' | 'notification' | 'file';
    id: string;
    label: string;
};

MergeOrganigramPreview

Changes the agent proposes to an existing organigram, added to it once confirmed.

Definition


export type MergeOrganigramPreview = {
    type: 'organigram';
    organigramId: string;
    persistence: 'merge-additive';
    summary: string[];
    organigram: OrganigramJson;
};

Message

A message of a conversation with the workspace agent.

Definition


export type Message = {
    role: 'user' | 'assistant';
    content: string;
};

NewOrganigramPreview

A new organigram the agent proposes, created once confirmed.

Definition


export type NewOrganigramPreview = {
    type: 'new-organigram';
    persistence: 'create';
    summary: string[];
    organigram: OrganigramJson;
};

OrganigramPreview

Changes the agent proposes, which the user confirms or cancels.

Definition


export type OrganigramPreview = MergeOrganigramPreview | NewOrganigramPreview;

PanelLabels

Texts of the agent panel, to translate it.

Definition


export type PanelLabels = PreviewLabels & {
    title: string;
    close: string;
    threads: string;
    newChat: string;
    noConversationsYet: string;
    thinking: string;
    askPlaceholder: string;
    attachDocument: string;
    selectedDocument: string;
    removeDocument: string;
    sourceHero: string;
    sourceWorkspace: string;
};

PanelMessage

A message shown in the agent panel, possibly still streaming.

Definition


export type PanelMessage = Message & {
    id?: string;
    response?: AgentResponse;
    streaming?: boolean;
};

PreviewLabels

Texts of the change preview, to translate it.

Definition


export type PreviewLabels = {
    preview: string;
    confirmationNotice: string;
    organ: string;
    newOrgan: string;
    newProcedure: string;
    newAsset: string;
    newEntry: string;
    entry: string;
    organType: string;
    procedureType: string;
    assetType: string;
    cancel: string;
    confirm: string;
};

StoredMessage

A saved message of a conversation.

Definition


export type StoredMessage = Message & {
    id: string;
    createdAt: string;
    response?: AgentResponse;
};

Thread

A conversation with the workspace agent.

Definition


export type Thread = {
    id: string;
    title: string;
    source: ThreadSource;
    workspace?: ThreadWorkspace | null;
    currentOrganigramId?: string | null;
    createdAt: string;
    updatedAt: string;
    messages: StoredMessage[];
};

ThreadSource

Where a conversation started: in a workspace or on the home page.

Definition


export type ThreadSource = 'workspace' | 'hero';

ThreadWorkspace

The workspace a conversation belongs to.

Definition


export type ThreadWorkspace = {
    id: string;
    name?: string | null;
};

Client and shared state

useOrganigramClient creates an OrganigramClient from your viem clients. The other hooks share state through Recoil, so your application must be wrapped in a RecoilRoot.

useOrganigramClient

Create an OrganigramClient from viem clients, or return null until a public client is available.

The client is created synchronously with the procedure types known for the chain. Use OrganigramClient.load() to read them from chain instead.


const client = useOrganigramClient(publicClient, walletClient, chainId)

Signature


useOrganigramClient: (publicClient?: PublicClient | null, walletClient?: WalletClient | null, chainId?: string | number | null) => OrganigramClient | null

ModalType

React element currently mounted inside the shared modal slot.

Definition


export type ModalType = null | JSX.Element;

SetModal

React state setter signature for the shared modal slot.

Definition


export type SetModal = Dispatch<SetStateAction<ModalType>>;

useSetModal

Update the current modal content.

Signature


useSetModal: () => SetterOrUpdater<ModalType>

modalState

Global recoil state storing the currently opened modal.

Definition


const modalState: import('recoil').RecoilState<JSX.Element | null>

ProposalFilter

Named filters used by proposal list UIs.

Definition


export type ProposalFilter = 'current' | 'drafts' | 'passed' | 'blocked' | '';

isUserInSourceOrgan

Check whether the current user belongs to the organ assigned to one procedure role.

Signature


isUserInSourceOrgan: (roleType: ProcedureRoleTypeName, organs: OrganJson[], deployedProcedure?: ProcedureJson, userAddress?: string) => boolean

Parameters

Name	Type	Description
`roleType`	`ProcedureRoleTypeName`	Procedure role to inspect.
`organs`	`OrganJson[]`	Hydrated organs available in the current organigram.
`deployedProcedure`	`ProcedureJson`	Procedure whose role organ should be checked.
`userAddress`	`string`	Connected user address.