@plurid/plurid-react 0.0.0-34 → 0.0.0-35

package/README.md

@@ -5,7 +5,7 @@
     <a target="_blank" href="https://www.npmjs.com/package/@plurid/plurid-react">
         <img src="https://img.shields.io/npm/v/@plurid/plurid-react.svg?logo=npm&colorB=1380C3&style=for-the-badge" alt="Version">
     </a>
-    <a target="_blank" href="https://github.com/plurid/plurid-react/blob/master/LICENSE">
+    <a target="_blank" href="https://github.com/plurid/plurid/blob/master/LICENSE">
         <img src="https://img.shields.io/badge/license-DEL-blue.svg?colorB=1380C3&style=for-the-badge" alt="License: DEL">
     </a>
 </p>
@@ -17,144 +17,96 @@
 </h1>
 
 
-`React` implementation of [plurid'](https://github.com/plurid/plurid) to view and explore information as a 3D structure.
-
-
-<p align="center">
-    <img src="https://raw.githubusercontent.com/plurid/plurid/master/about/demo/plurid-com-example.png" height="600px">
-</p>
+The **React** render adapter for [plurid'](https://github.com/plurid/plurid) — render content as **planes**
+in a navigable **3D space**. A plane is a component; the space is a CSS-3D scene you orbit, pan, and zoom.
 
 
 
 # Install
 
-The simplest manner to setup a "batteries included" `plurid'` web application is to use [@plurid/generate-plurid-app](https://github.com/plurid/plurid/tree/master/packages/generate-plurid-app)
+The quickest way to a batteries-included app is the scaffolder:
 
 ``` bash
 npx @plurid/generate-plurid-app
 ```
 
-In order to setup a plurid' web application in a more specific manner, given a standard setup for a React-based web application (recommended [create-react-app](https://github.com/facebook/create-react-app) template), add the plurid' package
-
-``` bash
-npm install @plurid/plurid-react
-```
-
-or
-
-``` bash
-yarn add @plurid/plurid-react
-```
-
-
-add the peer dependencies
+To add plurid' to an existing **React 19** app, install the adapter with its `@plurid/*` and library peers:
 
 ``` bash
 npm install \
-    @plurid/elementql \
-    @plurid/elementql-client-react \
+    @plurid/plurid-react \
     @plurid/plurid-data \
     @plurid/plurid-engine \
+    @plurid/plurid-pubsub \
     @plurid/plurid-functions \
     @plurid/plurid-functions-react \
     @plurid/plurid-icons-react \
-    @plurid/plurid-pubsub \
     @plurid/plurid-themes \
     @plurid/plurid-ui-components-react \
     @plurid/plurid-ui-state-react \
-    @reduxjs/toolkit \
-    cross-fetch \
-    hammerjs \
-    react \
-    react-dom \
-    react-redux \
-    styled-components
-```
-
-or
-
-``` bash
-yarn add \
     @plurid/elementql \
     @plurid/elementql-client-react \
-    @plurid/plurid-data \
-    @plurid/plurid-engine \
-    @plurid/plurid-functions \
-    @plurid/plurid-functions-react \
-    @plurid/plurid-icons-react \
-    @plurid/plurid-pubsub \
-    @plurid/plurid-themes \
-    @plurid/plurid-ui-components-react \
-    @plurid/plurid-ui-state-react \
     @reduxjs/toolkit \
-    cross-fetch \
-    hammerjs \
+    react-redux \
     react \
     react-dom \
-    react-redux \
-    styled-components
+    styled-components \
+    cross-fetch
 ```
 
-add the types (if it is a TypeScript project)
+For a TypeScript project, add the dev types:
 
 ``` bash
 npm install -D \
-    @types/hammerjs \
     @types/react \
-    @types/react-dom \
-    @types/react-redux \
-    @types/styled-components
+    @types/react-dom
 ```
 
-or
+> `react` / `react-dom` must be **≥ 19**, `@reduxjs/toolkit` ≥ 2, `react-redux` ≥ 9, `styled-components` ≥ 6.
+> (Gestures use native Pointer Events — there is no `hammerjs` dependency.)
+
 
-``` bash
-yarn add -D \
-    @types/hammerjs \
-    @types/react \
-    @types/react-dom \
-    @types/react-redux \
-    @types/styled-components
-```
 
+# Usage
 
-A simple, rendering-test application component, could look like
+A plane is a `route` + a `component`; the `view` is which routes to show first.
 
 ``` tsx
-/** imports */
 import React from 'react';
-
 import {
     PluridApplication,
-    PluridPlane,
+    PluridReactPlane,
 } from '@plurid/plurid-react';
 
 
+const planes: PluridReactPlane[] = [
+    { route: '/',     component: () => <div>Home plane</div> },
+    { route: '/about', component: () => <div>About plane</div> },
+];
 
-/** React Functional Component */
-const Application: React.FC<any> = () => {
-    /** plurid' planes */
-    const pluridPlanes: PluridPlane[] = [
-        [
-            '/',
-            () => (<div>Plurid' Application Plane</div>),
-        ],
-    ];
+const view = ['/', '/about'];
 
-    /** plurid' view */
-    const pluridView: string[] = [
-        '/',
-    ];
 
-    /** render */
-    return (
-        <PluridApplication
-            planes={pluridPlanes}
-            view={pluridView}
-        />
-    );
-}
+const Application: React.FC = () => (
+    <PluridApplication
+        planes={planes}
+        view={view}
+    />
+);
 
 
 export default Application;
 ```
+
+Drag to orbit, scroll to zoom, hold **G** to grab-pan.
+
+
+
+# Going further
+
+- **[Getting started](https://github.com/plurid/plurid/blob/master/GETTING_STARTED.md)** — planes, views,
+  links, configuration, persistence, the control surface.
+- **[Control surface](https://github.com/plurid/plurid/blob/master/docs/CONTROL_SURFACE.md)** — `onReady`,
+  pub/sub control & observe topics, `storageAdapter`, gestures, shortcuts, UI render-slots.
+- **[Examples](https://github.com/plurid/plurid/tree/master/examples)** — a minimal hello-world and a
+  full control-surface reference.