use-coordination

A library for coordinated multiple views in React-based visualization systems.

Usage

npm install use-coordination

Quick start

• Define a coordination specification (i.e., representation of the coordinated state of your app) using the declarative or imperative API.
• Get and set coordinated state via the useCoordination hooks within React components (i.e., views).
• Wrap the views with a coordination provider.

Basics

In React components that define views, use the hooks from use-coordination to get and set values in the coordination space. For example, if we want our view to be coordinated on a coordination type called myValue:

import React from 'react';
import { useCoordination } from 'use-coordination';

function SomeViewType(props) {
  const { viewUid } = props;
  const [{
    myValue,
  }, {
    setMyValue,
  }] = useCoordination(viewUid, ['myValue']);

  return (
    <input
      type="number"
      value={myValue}
      onChange={e => setMyValue(e.target.value)}
    />
  );
}

Then, wrap the app (or a parent component of all views you would like to coordinate) in a CoordinationProvider (or ZodCoordinationProvider). Pass a spec to the provider to set the initial state of the coordination space and the view-coordination scope mappings.

import React from 'react';
import { CoordinationProvider, defineSpec } from 'use-coordination';

// ...

// Alternatively, use the object-oriented API.
const initialSpec = defineSpec({
  coordinationSpace: {
    myValue: {
      myValueScope1: 99,
      myValueScope2: 20,
    },
  },
  viewCoordination: {
    v1: {
      coordinationScopes: {
        myValue: 'myValueScope1',
      },
    },
    v2: {
      coordinationScopes: {
        myValue: 'myValueScope1',
      },
    },
    v3: {
      coordinationScopes: {
        myValue: 'myValueScope2',
      },
    },
  },
});

function MyApp(props) {
  return (
    <CoordinationProvider spec={initialSpec}>
      <SomeViewType viewUid="v1" />
      <SomeViewType viewUid="v2" />
      <AnotherViewType viewUid="v3" />
    </CoordinationProvider>
  );
}

To learn more, please visit the documentation:

• List of available hooks
• List of available providers
• JSON schema
• Object-oriented spec API

Development

Install pnpm v8

Setup

git clone 
pnpm install

Run demo

pnpm start

Lint and format

pnpm lint
pnpm format

Build library

pnpm build

Build demo

pnpm build-demo

Monorepo tasks

pnpm meta-updater

Deployment