Usage docs (#75)

* Add usage page to docs with README contents

* Changeset

* Simplify docs

* Fix defineSpec import in examples

.changeset/moody-rings-grow.md

@@ -0,0 +1,5 @@
+---
+"docs": patch
+---
+
+Add usage page to docs.

README.md

@@ -49,7 +49,7 @@ Pass a `spec` to the provider to set the initial state of the coordination space
 
 ```js
 import React from 'react';
-import { CoordinationProvider } from 'use-coordination';
+import { CoordinationProvider, defineSpec } from 'use-coordination';
 
 // ...
 

scripts/vite.config.js

@@ -5,7 +5,7 @@ import { existsSync } from 'fs';
 
 const cwd = process.cwd();
 
-// Need to make vit-s external for dependents (but vit-s is not dependent on itself),
+// Need to make core external for dependents (but core is not dependent on itself),
 // otherwise there will be issues with Zustand stores.
 const moreExternals = basename(cwd) === 'core' ? [] : ['@use-coordination/core'];
 

sites/docs/docs/coordination.mdx

@@ -35,8 +35,3 @@ The container for a particular coordination type and its associated coordination
 ### Coordination Space
 The container for all coordination objects in a visualization system.
 In use-coordination, the coordination space is stored in a serializable JSON format.
-
-### Translation Function
-A function that translates values between the coordination space and a visualization implementation.
-Coordination values may be stored in an abstract format rather than the format required for any particular view. For this reason, coordinated views must define a translation function for each coordination type, which maps coordination values onto the native format used by the view. In the simplest case the identity function may be used.
-

sites/docs/docs/usage.mdx

@@ -0,0 +1,99 @@
+---
+id: usage
+title: Basic usage
+---
+
+## Installation
+
+```sh
+npm install use-coordination
+```
+
+## Quick start
+
+- Define a coordination specification (i.e., representation of the coordinated state of your app) using the [declarative](../spec-json/) or [imperative](../spec-js/) API.
+- Get and set coordinated state via the `useCoordination` [hooks](../view-hooks/) within React components (i.e., views).
+- Wrap the views with a [coordination provider](../provider-components/).
+
+
+## Basics
+
+In React components that define views, use the [hooks](../view-hooks/#usecoordination) 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`:
+
+```js
+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](../provider-components/#coordinationprovider) (or [ZodCoordinationProvider](../provider-components/#zodcoordinationprovider)).
+Pass a `spec` to the provider to set the initial state of the coordination space and the view-coordination scope mappings.
+
+
+```js
+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 see these documentation pages:
+- [List of available hooks](../view-hooks/)
+- [List of available providers](../provider-components/)
+- [JSON schema](../spec-json/)
+- [Object-oriented spec API](../spec-js/)
+

sites/docs/sidebars.js

@@ -4,6 +4,10 @@ module.exports = {
       type: 'doc',
       id: 'introduction',
     },
+    {
+      type: 'doc',
+      id: 'usage',
+    },
     {
       type: 'doc',
       id: 'coordination',