@arcanejs/react-toolkit 0.12.5 → 0.14.0

package/README.md

@@ -2,309 +2,389 @@
 
 [![NPM Version](https://img.shields.io/npm/v/%40arcanejs%2Freact-toolkit)](https://www.npmjs.com/package/@arcanejs/react-toolkit)
 
-`@arcanejs/react-toolkit` Allows you to quickly create real-time control panels
-for your single-process Node.js apps,
-using a custom react renderer, and WebSockets.
+React renderer for ArcaneJS server-side control panels.
 
-Control panels can be accessed by any number of
-browsers / devices / clients simultaneously,
-and changes caused by any client will be immediately propagated to all other
-clients.
-
-The UI has also been designed primarily with touch devices in mind,
-but also works well with a cursor and keyboard.
+This package lets you build toolkit component trees using React state/hooks on the server, then synchronize them to connected browser clients in real time.
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/ArcaneWizards/arcanejs/main/packages/react-toolkit/docs/architecture.svg" alt="Architecture Diagram">
 </p>
 
-## What
+## Why Use `@arcanejs/react-toolkit`
 
-- Easily create controller UIs for Node.js processes
+This package is useful when you want a control panel for a long-running Node.js process without building a full web app stack.
 
-- Uses server-side **React** for state management and UI composition
+It gives you:
 
-  - This is not SSR, you can use `useState()` hooks etc...
+- server-side React state/hooks for control logic
+- realtime multi-client sync over WebSockets
+- a ready set of control-oriented UI components (switches, sliders, groups, tabs, timelines)
+- an extension path for custom components when core components are not enough
 
-- Instantly updates all clients using WebSockets
+Typical use cases:
 
-- Collection of 9+ components to build your UIs
+- home/lab automation control surfaces
+- AV/lighting/operations dashboards on a local network
+- internal tooling for stateful services/scripts that need live operator controls
 
-## Why
+## When It Fits (And When It Doesn't)
 
-Sometimes you're working on relatively simple local applications or scripts,
-and would like to have a way to interact with the state or configuration
-of these applications in real-time,
-for example:
+Good fit:
 
-- Lighting control or AV systems
-- Home-Automation or Office building management and operation
+- single-process Node.js apps with in-memory state
+- trusted/internal networks where operators need live controls
+- projects where React composition is preferred over manual tree mutation
 
-### Why Not
+Not a fit:
 
-This project is not designed to be a general-purpose application framework,
-in particular, it's not suitable for any project / application that:
+- internet-exposed apps requiring built-in auth/authz
+- horizontally scaled/multi-process architectures needing shared state coordination
+- general-purpose public web apps that need standard React DOM/SSR patterns
 
-- Needs to scale beyond a single Node.js process
-- Is stateless _(It's explicitly designed to manage in-memory state)_
-- Will be exposed over the internet _(no authentication has been implemented)_
+## Install
 
-## Usage
+```bash
+npm install react@^19.2.0 @arcanejs/toolkit @arcanejs/react-toolkit
+```
 
-Install the following packages:
+Version compatibility:
 
-```
-npm install --save react@^18 @arcanejs/toolkit @arcanejs/react-toolkit
-```
+- `@arcanejs/react-toolkit` is tested against React 19 and `react-reconciler` 0.33.x.
 
-Note:
+Optional helper dependencies:
 
-- We explicitly require `react` version 18
-- We don't need `react-dom` or any react native libraries,
-  `@arcanejs/react-toolkit` is the react renderer.
+- `zod` is required if you use `@arcanejs/react-toolkit/data`
 
-Then you can then create control panels using react to manage the
-server-side state like this:
+## Quick Start
 
-```ts
+```tsx
 import { useState } from 'react';
 import { Toolkit } from '@arcanejs/toolkit';
-import { ToolkitRenderer, Group, Switch, SliderButton } from '@arcanejs/react-toolkit';
+import {
+  ToolkitRenderer,
+  Group,
+  Switch,
+  SliderButton,
+} from '@arcanejs/react-toolkit';
 
 const toolkit = new Toolkit();
+toolkit.start({ mode: 'automatic', port: 3000 });
 
-// Expose the toolkit control panel on HTTP port 3000
-// Navigate to http://localhost:3000 to access the control panel
-// this will be printed in your console
-toolkit.start({
-  mode: 'automatic',
-  port: 3000,
-});
-
-const ControlPanel = () => {
-  const [switchState, setSwitchState] = useState<'off' | 'on'>('off');
-  const [sliderValue, setSliderValue] = useState(50);
+function App() {
+  const [enabled, setEnabled] = useState<'on' | 'off'>('off');
+  const [level, setLevel] = useState(50);
 
   return (
-    <Group direction='vertical'>
+    <Group direction="vertical" title="Controller">
       <Group>
-        {`Switch State: ${switchState}`}
-        <Switch
-            value={switchState}
-            onChange={setSwitchState}
-          />
+        {`Enabled: ${enabled}`}
+        <Switch value={enabled} onChange={setEnabled} />
       </Group>
       <Group>
-        {`Slider Value: ${sliderValue}`}
-        <SliderButton
-          value={sliderValue}
-          onChange={setSliderValue}
-          min={0}
-          max={100}
-          />
+        {`Level: ${level}`}
+        <SliderButton value={level} onChange={setLevel} min={0} max={100} />
       </Group>
     </Group>
   );
-};
+}
 
-// Start rendering the control panel with @arcanejs/react-toolkit
-ToolkitRenderer.render(<ControlPanel />, toolkit);
+ToolkitRenderer.render(<App />, toolkit);
 ```
 
-You would then be able to access the following control panel
-from [localhost:3000](http://localhost:3000):
+## Core Exports
 
-![Control Panel Screenshot](https://raw.githubusercontent.com/ArcaneWizards/arcanejs/main/packages/react-toolkit/docs/example-controller.png)
+### From `@arcanejs/react-toolkit`
 
-Please note:
+- `ToolkitRenderer`
+  - `render(element, toolkit, rootGroupProps?, config?)`
+  - `renderGroup(element, group, config?)`
+- Core React components:
+  - `Button`, `Group`, `GroupHeader`, `Label`, `Rect`, `SliderButton`, `Switch`, `Tab`, `Tabs`, `TextInput`, `Timeline`
+- Extension helpers:
+  - `prepareComponents(namespace, components)`
+  - `CoreComponents`
 
-- You can not use normal `react-dom` / HTML elements in these applications
-  or components, only `@arcanejs` components are supported.
+Core component props/events map directly to the corresponding classes in `@arcanejs/toolkit`.
 
-- You are welcome to abstract / componentize your application as you like,
-  in the same manner that you would any `react-dom` or `react-native` project.
+## Core Component API
 
-  _See the [counter example](https://github.com/ArcaneWizards/arcanejs/blob/main/examples/react/src/counter.tsx)._
+These are the React components most users consume directly from `@arcanejs/react-toolkit`.
 
-- This react / component-tree / state is managed server-side,
-  and does not accurately represent the HTML used on the frontend.
-  Your `@arcanejs` tree is converted to a JSON representation,
-  and then sent to clients / browsers over a WebSocket.
-  There is then a separate `react-dom` application
-  that is loaded in the browser,
-  and then used to render the JSON representation of the `@arcanejs` tree.
-
-- It's possible to define your own custom components,
-  however this functionality is not documented.
-
-  You can see code examples of this functionality here in the
-  [custom components example app](https://github.com/ArcaneWizards/arcanejs/tree/main/examples/custom-components).
+### `Button`
 
-## Components
+Props:
 
-For full example usage all of our components in applications that are
-ready-to-run, we recommend that you check-out the
-[examples directory](https://github.com/ArcaneWizards/arcanejs/tree/main/examples/react).
+- `text?: string | null`
+- `icon?: string | null` (Material Symbols Outlined icon name)
+- `mode?: 'normal' | 'pressed'`
+- `error?: string | null`
+- `onClick?: (connection) => void | Promise<void>`
 
-### `Button`
+Notes:
 
-**Properties:**
+- `onClick` uses request/response semantics and can be async.
+- Throwing (or rejecting) in `onClick` surfaces an error state in the UI.
 
-- `text: string` (optional)
+```tsx
+<Button
+  text="Run"
+  icon="play_arrow"
+  onClick={async () => {
+    await runTask();
+  }}
+/>
+```
 
-  Text to display on the button
+### `Group`
 
-- `icon: string` (optional)
+Props:
 
-  In icon name from [Material Icons](https://fonts.google.com/icons) to include
-  on the button.
+- `direction?: 'horizontal' | 'vertical'`
+- `wrap?: boolean`
+- `border?: true`
+- `title?: string | null`
+- `labels?: Array<{ text: string }> | null`
+- `editableTitle?: boolean`
+- `defaultCollapsibleState?: 'open' | 'closed' | 'auto'`
+- `onTitleChanged?: (title, connection) => void`
 
-- `error: string` (optional)
+Use `Group` as the primary layout primitive and nest groups freely.
 
-  When set, highlight the button in a way to indicate an error,
-  and expose the given text as a tooltip upon user hover.
+```tsx
+<Group
+  direction="vertical"
+  title="Fixture Settings"
+  border
+  editableTitle
+  onTitleChanged={(title) => setPanelTitle(title)}
+>
+  <Label text="Master Intensity" />
+  <SliderButton value={master} min={0} max={100} onChange={setMaster} />
+</Group>
+```
 
-- `mode: 'normal' | 'pressed'` (default: `'normal'`)
+### `GroupHeader`
 
-  Should the button display as pressed or not.
+`GroupHeader` lets you place controls in a group's header area.
 
-- `onClick: () => void | Promise<void>`
+```tsx
+<Group title="Playlist">
+  <GroupHeader>
+    <Button text="Add" onClick={addItem} />
+    <Button text="Shuffle" onClick={shuffle} />
+  </GroupHeader>
+  <Label text="Current Queue" />
+</Group>
+```
 
-  Set an event listener for when the button is pressed.
+### `Label`
 
-  The listener can throw an exception, or return a promise that rejects,
-  to indicate an error and propagate an error message to the user,
-  similar to setting the `error` property.
+Props:
 
-e.g.:
+- `text: string | null`
+- `bold?: boolean`
 
 ```tsx
-const MyComponent = () => (
-  <Button text="Stop" onClick={() => doAThing()} icon="close" />
-);
+<Label text={`Connected: ${isConnected ? 'yes' : 'no'}`} bold />
 ```
 
-### `Group`
+### `Rect`
+
+Props:
 
-This component is the primary building block when it comes to creating layouts,
-you generally have many groups,
-and nest them to achieve the desired layout.
+- `color?: string`
+- `grow?: boolean`
 
-You can think of a group as similar to a `<div>` or `<section>` in HTML.
+Useful for color/state swatches.
+
+```tsx
+<Group>
+  <Label text="Current Color" />
+  <Rect color={`hsl(${hue}deg 100% 50%)`} grow />
+</Group>
+```
 
-**Properties:**
+### `SliderButton`
 
-- `direction: 'horizontal' | 'vertical'` (default: `'horizontal'`)
+Props:
 
-  Whether to arrange the children of this group in a row or column.
+- `value: number` (required)
+- `min?: number` (default `0`)
+- `max?: number` (default `255`)
+- `step?: number` (default `5`)
+- `defaultValue?: number` (for uncontrolled style workflows)
+- `gradient?: Array<{ color: string; position: number }>`
+- `grow?: boolean`
+- `onChange?: (value, connection) => void | Promise<void>`
 
-- `wrap: boolean` (default: false)
+```tsx
+<SliderButton
+  value={temperature}
+  min={2700}
+  max={6500}
+  step={100}
+  onChange={setTemperature}
+/>
+```
 
-  If true, when the group runs out of vertical or horizontal space, child
-  components will be wrapped, and start to be arranged on additional columns
-  or rows.
+### `Switch`
 
-- `border: boolean` (default: false)
+Props:
 
-  If true, this group will have a border and a different color background
-  to its parent.
+- `value?: 'on' | 'off'`
+- `defaultValue?: 'on' | 'off'`
+- `onChange?: (state, connection) => void | Promise<void>`
 
-  This allows you to add a distinctive border between components,
-  without needing to set a header, add header components,
-  or make it collapsible.
+```tsx
+<Switch value={enabled} onChange={setEnabled} />
+```
 
-- `title: string` (optional)
+### `Tabs` and `Tab`
 
-  If set, will display a title as a header at the top of the group.
+`Tabs` only accepts `Tab` children. Each `Tab` should contain one child component subtree.
 
-- `editableTitle: boolean` (default: false)
+```tsx
+<Tabs>
+  <Tab name="Input">
+    <Group>
+      <TextInput value={input} onChange={setInput} />
+    </Group>
+  </Tab>
+  <Tab name="Output">
+    <Group>
+      <Label text={output} />
+    </Group>
+  </Tab>
+</Tabs>
+```
 
-  If true,
-  will allow the user to click on the title to change it,
-  which will trigger a callback to the listener `onTitleChanged`.
+### `TextInput`
 
-- `defaultCollapsibleState: 'open' | 'closed' | 'auto'`
-  (optional, default: `undefined`)
+Props:
 
-  If set,
-  will allow the user to expand / collapse the given group,
-  by default set to the given state.
+- `value?: string | null`
+- `onChange?: (value, connection) => void | Promise<void>`
 
-  Whether a group is open or closed is independent on a per-client basis,
-  and a fresh page reload will set the collapsible state to the default set here.
+```tsx
+<TextInput value={name} onChange={setName} />
+```
 
-- `labels: { text: string }[] | null` (default: null)
+### `Timeline`
 
-  Adds labels next to the title in the group header.
+Props:
 
-**Special Child Components**
+- `state?`:
+  - `{ state: 'playing'; totalTimeMillis; effectiveStartTime; speed }`
+  - `{ state: 'stopped'; totalTimeMillis; currentTimeMillis }`
+- `title?: string | null`
+- `subtitles?: string[] | null`
+- `source?: { name: string } | null`
 
-- `GroupHeader`
+```tsx
+<Timeline
+  title="Show Timeline"
+  subtitles={[`Cue ${cue}`, `BPM ${bpm}`]}
+  source={{ name: activeTrack }}
+  state={
+    playing
+      ? {
+          state: 'playing',
+          totalTimeMillis: duration,
+          effectiveStartTime: startedAt,
+          speed: 1,
+        }
+      : {
+          state: 'stopped',
+          totalTimeMillis: duration,
+          currentTimeMillis: pausedAt,
+        }
+  }
+/>
+```
 
-  You can add components to the header of a group by wrapping them in a
-  `<GroupHeader/>` component directly under the `<Group/>`.
+## Helper Modules
 
-  You can add as many separate `GroupHeader` components as needed throughout
-  a `<Group>` component's direct children,
-  and all nested components will be placed in the header.
+### `@arcanejs/react-toolkit/connections`
 
-  Currently `GroupHeader` only supports rendering the following children:
+Connection-awareness for server-side React trees:
 
-  - `Button`
+- `ConnectionsContext`
+- `ConnectionsContextProvider`
 
-TODO: example
+Use this to render connection-specific UI or track per-connection state.
 
-### `Label`
+### `@arcanejs/react-toolkit/data`
 
-TODO
+JSON file persistence helpers backed by Zod validation:
 
-### `Rect`
+- `createDataFileDefinition`
+- `useDataFileContext`
+- `useDataFileData`
+- `useDataFileUpdater`
+- `useDataFile`
+- `useDataFileCore`
 
-TODO
+Supports:
 
-### `SliderButton`
+- lazy file creation with defaults
+- schema validation on load
+- throttled disk writes
+- path switching behavior (`onPathChange: 'transfer' | 'defaultValue'`)
 
-TODO
+### `@arcanejs/react-toolkit/colors`
 
-### `Switch`
+- `HslColor` type
+- `HslColorPicker` component
 
-TODO
+### `@arcanejs/react-toolkit/logging`
 
-### `Tabs`
+- `LoggerContext`
+- `useLogger()`
 
-TODO
+## Custom Component Namespaces
 
-### `TextInput`
+Use `prepareComponents(...)` + `ToolkitRenderer` config to add custom namespaces:
 
-TODO
+```tsx
+import {
+  prepareComponents,
+  CoreComponents,
+  ToolkitRenderer,
+} from '@arcanejs/react-toolkit';
+
+const Custom = prepareComponents('custom', {
+  MyComponent,
+});
 
-### `Timeline`
+ToolkitRenderer.render(
+  <App />,
+  toolkit,
+  {},
+  {
+    componentNamespaces: [CoreComponents, Custom],
+  },
+);
+```
 
-TODO
+You must also implement matching protocol/backend/frontend layers. See:
 
-## [Examples](https://github.com/ArcaneWizards/arcanejs/tree/main/examples/react)
+- <https://github.com/ArcaneWizards/arcanejs/tree/main/examples/custom-components>
 
-For a comprehensive list of examples,
-please see the example directory in the arcane monorepo:
-<https://github.com/ArcaneWizards/arcanejs/tree/main/examples/react>
+## Important Constraints
 
-### [Example Philips Hue App](https://github.com/arcanejs/hue-example)
+- This is a custom renderer, not React DOM. Standard HTML elements are not supported.
+- React state/hooks run on the server process.
+- Toolkit root can only be set once.
+- Architecture is single-process and intentionally stateful.
+- No built-in authentication/authorization.
 
-Check out this example repository that uses `@arcanejs/react-toolkit`
-to create an app that can be used to control a Philips Hue Bridge
-on your local network.
+## Stability / Suitability
 
-## Status / Suitability / Security Disclaimer
+ArcaneJS uses `react-reconciler` APIs and is considered experimental. It is best suited for trusted-network/internal control applications.
 
-This project is **experimental**,
-and takes advantage of unstable `react` APIs exposed via `react-render`.
-It's not suitable for production or commercial projects yet,
-especially those that rely on regular updates of dependencies
-for security reasons,
-as usage of this project may make it difficult to keep `react` up-to-date
-(that being said, the license does not prohibit this,
-so feel free to at-your-own-risk).
+## Examples
 
-There are also no authentication mechanisms implemented yet,
-so be careful when exposing your control panels over the network,
-as this will allow anyone to interact with your processes.
+- React examples: <https://github.com/ArcaneWizards/arcanejs/tree/main/examples/react>
+- Main readme example: <https://github.com/ArcaneWizards/arcanejs/blob/main/examples/react/src/readme.tsx>
+- Connections example: <https://github.com/ArcaneWizards/arcanejs/blob/main/examples/react/src/connections.tsx>
+- Data file example: <https://github.com/ArcaneWizards/arcanejs/blob/main/examples/react/src/data-file.tsx>