@signalsafe/tree-spec-editor-react 0.1.1 → 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SignalSafe Software
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,43 +1,140 @@
 # @signalsafe/tree-spec-editor-react
 
-Headless React layer for the SignalSafe TreeSpec graph editor. Renders the
-React Flow canvas, owns React state plumbing, and exposes the editor as a
-single React component — without depending on any specific UI library.
+Headless **React + React Flow** layer for the SignalSafe TreeSpec graph editor: canvas component, orchestration hook, and wiring to `@signalsafe/tree-spec-editor-core`.
 
-This is the React-specific sibling to **[`@signalsafe/tree-spec-editor-core`](../tree-spec-editor-core/README.md)**. The core package owns model + helpers (zero UI deps); this package owns React rendering. UI shells (e.g. `@signalsafe/tree-spec-editor` for React + Bootstrap, planned `@signalsafe/tree-spec-editor-react-mui` for React + Material) layer on top.
+| | |
+|---|---|
+| **npm** | `@signalsafe/tree-spec-editor-react` |
+| **GitHub** | [SignalSafeSoftware/tree-spec-editor-react](https://github.com/SignalSafeSoftware/tree-spec-editor-react) |
+| **Peer deps** | `react`, `react-dom`, `reactflow` (^18 / ^11) |
 
-## What this package owns
+## What this package does
 
-- **`TreeSpecGraphEditor`** — the React Flow canvas (Background, Controls, MiniMap, custom node renderer, transition edges, selection wiring, focus/fit-view).
-- **`TreeSpecGraphEditorProps`** — props type.
-- Future: framework-shaped headless hooks (e.g. `useTreeSpecEditorState`,
-  `useGraphSelection`) that wrap the framework-agnostic helpers from
-  `tree-spec-editor-core`.
+- Renders **`TreeSpecGraphEditor`** (React Flow canvas, custom nodes/edges, selection).
+- Exposes **`useTreeSpecEditor`** for load/validate/autosave/publish orchestration (host injects adapter callbacks).
+- Re-exports core editor types used by the hook.
 
-## What lives elsewhere
+## What this package does not do
 
-| Concern | Package |
-|--------|---------|
-| Editor model, tree operations, layout, autosave/keyboard helpers, constants | `@signalsafe/tree-spec-editor-core` |
-| Sidebar panels, inspector, modals, toolbar (Bootstrap-styled) | `@signalsafe/tree-spec-editor` |
-| Material-styled UI shells (planned) | `@signalsafe/tree-spec-editor-react-mui` |
-| Angular implementation (planned) | `@signalsafe/tree-spec-editor-angular` |
+- Sidebar panels, modals, toolbars, or Bootstrap chrome — use `@signalsafe/tree-spec-editor` or your own UI shell.
+- Routing, HTTP, authentication, or persistence — host app provides adapter implementations.
+- Wire compile/publish to a backend without your adapter code.
 
 ## Install
 
 ```bash
-npm install @signalsafe/tree-spec-editor-react react react-dom reactflow
+npm install @signalsafe/tree-spec-editor-react @signalsafe/tree-spec-editor-core @signalsafe/tree-spec react react-dom reactflow
 ```
 
-`reactflow` is a peer dependency; you must install it (and ship its CSS,
-e.g. `import 'reactflow/dist/style.css';`) in the consuming app. The
-package itself imports the CSS file from its source, so bundlers that
-resolve module references will pick it up automatically.
+### React Flow CSS (required)
 
-## Why a separate package?
+This package imports `reactflow/dist/style.css` from source. Bundlers treat it as a side effect (`sideEffects: ["**/*.css"]` in `package.json`).
 
-This layer is React-specific but **UI-library-agnostic**. Hosts that want
-to ship a Material-styled editor only need to publish their own UI shell
-(panels, modals, toolbar) — they reuse the canvas and the editor model
-unchanged. This also keeps `@signalsafe/tree-spec-editor` (the
-Bootstrap variant) from being the sole React entry point.
+Ensure your app loads React Flow styles, for example:
+
+```ts
+import "reactflow/dist/style.css";
+```
+
+If you use `@signalsafe/tree-spec-editor` (Bootstrap shell), the canvas still comes from this package — consumers may need the CSS import in the app entry when tree-shaking.
+
+## Quick start
+
+```tsx
+import { useState } from "react";
+import TreeSpecGraphEditor from "@signalsafe/tree-spec-editor-react";
+import {
+    END_NODE_ID,
+    type EditorTree,
+} from "@signalsafe/tree-spec-editor-core";
+
+const initialTree: EditorTree = {
+    start_node: "start",
+    nodes: {
+        start: {
+            id: "start",
+            type: "prompt",
+            prompt: "Example prompt",
+            choices: [{ id: "done", label: "Finish" }],
+            position: { x: 40, y: 120 },
+        },
+    },
+    transitions: [
+        {
+            id: "t1",
+            fromNodeId: "start",
+            fromChoiceId: "done",
+            toNodeId: END_NODE_ID,
+            outcome: "safe",
+        },
+    ],
+};
+
+export function ExampleCanvas() {
+    const [tree, setTree] = useState(initialTree);
+    return (
+        <TreeSpecGraphEditor
+            tree={tree}
+            onChange={setTree}
+            className="h-[60vh] border rounded"
+        />
+    );
+}
+```
+
+For full authoring flows (load/save/validate), compose **`useTreeSpecEditor`** with your adapter — see tests and `@signalsafe/tree-spec-editor` for a reference shell.
+
+## Public exports
+
+| Export | Purpose |
+|---|---|
+| `default` / `TreeSpecGraphEditor` | React Flow canvas |
+| `TreeSpecGraphEditorProps` | Canvas props |
+| `useTreeSpecEditor` | Stateful editor orchestration |
+| `TreeSpecEditorAdapter`, `UseTreeSpecEditorResult`, … | Adapter and hook types |
+
+Import from `@signalsafe/tree-spec-editor-react` only (no subpath exports).
+
+## Package boundaries
+
+| Layer | Package |
+|---|---|
+| Wire | `@signalsafe/tree-spec` |
+| Editor model | `@signalsafe/tree-spec-editor-core` |
+| **React canvas (this package)** | `@signalsafe/tree-spec-editor-react` |
+| Bootstrap shell | `@signalsafe/tree-spec-editor` |
+
+## Canvas selection behavior
+
+| Selection | Inspector context | Contextual zoom (default on) |
+|---|---|---|
+| Node | selected node | fits node in viewport |
+| Edge | source node + focused choice | viewport unchanged |
+| Choice | `focusChoiceId` set | fits parent node when selected |
+
+Pass `contextualZoom={false}` to disable automatic viewport fitting.
+
+## Development
+
+`yarn build` uses `tsconfig.build.json` and resolves `@signalsafe/*` from `node_modules`. Ecosystem sibling `paths` in `tsconfig.json` apply to local typecheck/tests only.
+
+```bash
+yarn install
+yarn build
+yarn test
+yarn typecheck
+```
+
+## Security
+
+See [SECURITY.md](./SECURITY.md). Host applications must authenticate users, authorize edits, and validate TreeSpec JSON server-side before publish.
+
+## Changelog and releases
+
+- [CHANGELOG.md](./CHANGELOG.md)
+- [RELEASING.md](./RELEASING.md)
+
+## Related packages
+
+- [`@signalsafe/tree-spec-editor-core`](https://github.com/SignalSafeSoftware/tree-spec-editor-core) — framework-agnostic editor helpers.
+- [`@signalsafe/tree-spec-editor`](https://github.com/SignalSafeSoftware/tree-spec-editor) — full Bootstrap UI shell.

package/README.standalone.md

@@ -0,0 +1,14 @@
+# Standalone export
+
+This tree was generated by `scripts/export-standalone-npm-package.sh tree-spec-editor-react` from the DeliveryPlus monorepo.
+
+```bash
+git init
+git branch -M main
+git add .
+git commit -m "Sync tree-spec-editor-react from DeliveryPlus"
+git remote add origin git@github.com:SignalSafeSoftware/tree-spec-editor-react.git
+git push -u origin main
+```
+
+See `RELEASING.md` for npm publish steps.

package/dist/GraphEditorCanvasContext.d.ts

@@ -0,0 +1,26 @@
+export type ChoiceDropTarget = {
+    nodeId: string;
+    index: number;
+};
+export type ChoiceDragState = {
+    sourceNodeId: string;
+    choiceId: string;
+};
+export type GraphEditorCanvasContextValue = {
+    readOnly: boolean;
+    onDuplicateNode: (nodeId: string) => void;
+    onDeleteNode: (nodeId: string) => void;
+    onResizeNode: (nodeId: string, width: number, height: number) => void;
+    /** Lock the node box height when a resize drag begins (prevents wrap reflow jumps). */
+    onResizeNodeStart: (nodeId: string, width: number, height: number) => void;
+    onSelectChoice: (nodeId: string, choiceId: string) => void;
+    choiceDrag: ChoiceDragState | null;
+    choiceDropTarget: ChoiceDropTarget | null;
+    onChoiceDragStart: (nodeId: string, choiceId: string) => void;
+    onChoiceDragEnd: () => void;
+    onChoiceDragOver: (nodeId: string, index: number) => void;
+    onChoiceDrop: (nodeId: string, index: number) => void;
+};
+export declare const GraphEditorCanvasContext: import("react").Context<GraphEditorCanvasContextValue>;
+export declare function useGraphEditorCanvas(): GraphEditorCanvasContextValue;
+//# sourceMappingURL=GraphEditorCanvasContext.d.ts.map

package/dist/GraphEditorCanvasContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GraphEditorCanvasContext.d.ts","sourceRoot":"","sources":["../src/GraphEditorCanvasContext.tsx"],"names":[],"mappings":"AAEA,MAAM,MAAM,gBAAgB,GAAG;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,6BAA6B,GAAG;IACxC,QAAQ,EAAE,OAAO,CAAC;IAClB,eAAe,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1C,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACtE,uFAAuF;IACvF,iBAAiB,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3E,cAAc,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3D,UAAU,EAAE,eAAe,GAAG,IAAI,CAAC;IACnC,gBAAgB,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAC1C,iBAAiB,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9D,eAAe,EAAE,MAAM,IAAI,CAAC;IAC5B,gBAAgB,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1D,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACzD,CAAC;AAmBF,eAAO,MAAM,wBAAwB,wDAA8B,CAAC;AAEpE,wBAAgB,oBAAoB,IAAI,6BAA6B,CAEpE"}

package/dist/GraphEditorCanvasContext.js

@@ -0,0 +1,20 @@
+import { createContext, useContext } from 'react';
+const noop = () => undefined;
+const defaultValue = {
+    readOnly: true,
+    onDuplicateNode: noop,
+    onDeleteNode: noop,
+    onResizeNode: noop,
+    onResizeNodeStart: noop,
+    onSelectChoice: noop,
+    choiceDrag: null,
+    choiceDropTarget: null,
+    onChoiceDragStart: noop,
+    onChoiceDragEnd: noop,
+    onChoiceDragOver: noop,
+    onChoiceDrop: noop,
+};
+export const GraphEditorCanvasContext = createContext(defaultValue);
+export function useGraphEditorCanvas() {
+    return useContext(GraphEditorCanvasContext);
+}

package/dist/TreeSpecGraphEditor.d.ts

@@ -7,10 +7,31 @@ export type TreeSpecGraphEditorProps = {
     showMiniMap?: boolean;
     selected?: GraphSelection;
     onSelect?: (sel: GraphSelection) => void;
+    /** Called when a choice row is clicked on the canvas (after `onSelect` for the parent node). */
+    onChoiceSelect?: (nodeId: string, choiceId: string) => void;
+    /** Called when a choice is dropped after drag (reorder or move to another node). */
+    onRepositionChoice?: (fromNodeId: string, choiceId: string, toNodeId: string, toIndex: number) => void;
     focusNodeId?: string | null;
+    /** Focused choice on the currently selected node (canvas + inspector sync). */
+    focusChoiceId?: string | null;
     fitViewNonce?: number;
     /** Optional class for the outer container (default includes h-70vh border rounded). */
     className?: string;
+    /** When true, disables canvas editing affordances (toolbar, resize, context menu). */
+    readOnly?: boolean;
+    /** Duplicate a prompt node from the canvas toolbar or context menu. */
+    onDuplicateNode?: (nodeId: string) => void;
+    /** Delete a prompt node from the canvas toolbar or context menu. */
+    onDeleteNode?: (nodeId: string) => void;
+    /** Run auto-layout from the pane context menu. */
+    onAutoLayout?: () => void;
+    /**
+     * When true (default), zooms the viewport to fit the current node/edge selection.
+     * Skipped when `focusNodeId` already targets the same node.
+     */
+    contextualZoom?: boolean;
+    /** Canvas chrome mode — host should pass Bootstrap `colorScheme` (`light` / `dark`). */
+    colorMode?: 'light' | 'dark';
 };
-export default function TreeSpecGraphEditor(props: Readonly<TreeSpecGraphEditorProps>): import("react/jsx-runtime").JSX.Element;
+export default function TreeSpecGraphEditor(props: Readonly<TreeSpecGraphEditorProps>): import("react").JSX.Element;
 //# sourceMappingURL=TreeSpecGraphEditor.d.ts.map

package/dist/TreeSpecGraphEditor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TreeSpecGraphEditor.d.ts","sourceRoot":"","sources":["../src/TreeSpecGraphEditor.tsx"],"names":[],"mappings":"AAkBA,OAAO,0BAA0B,CAAC;AAIlC,OAAO,EAKH,KAAK,UAAU,EAEf,KAAK,cAAc,EACnB,KAAK,gBAAgB,EAGxB,MAAM,mCAAmC,CAAC;AAE3C,MAAM,MAAM,wBAAwB,GAAG;IACnC,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,IAAI,CAAC;IACrC,MAAM,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC5B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,IAAI,CAAC;IACzC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uFAAuF;IACvF,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAsZF,MAAM,CAAC,OAAO,UAAU,mBAAmB,CAAC,KAAK,EAAE,QAAQ,CAAC,wBAAwB,CAAC,2CAMpF"}
+{"version":3,"file":"TreeSpecGraphEditor.d.ts","sourceRoot":"","sources":["../src/TreeSpecGraphEditor.tsx"],"names":[],"mappings":"AAYA,OAAO,0BAA0B,CAAC;AAElC,OAAO,EAKH,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACxB,MAAM,mCAAmC,CAAC;AAsB3C,MAAM,MAAM,wBAAwB,GAAG;IACnC,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,IAAI,CAAC;IACrC,MAAM,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC5B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,IAAI,CAAC;IACzC,gGAAgG;IAChG,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5D,oFAAoF;IACpF,kBAAkB,CAAC,EAAE,CACjB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,KACd,IAAI,CAAC;IACV,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,+EAA+E;IAC/E,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uFAAuF;IACvF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sFAAsF;IACtF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,uEAAuE;IACvE,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3C,oEAAoE;IACpE,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,kDAAkD;IAClD,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,wFAAwF;IACxF,SAAS,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CAChC,CAAC;AA4PF,MAAM,CAAC,OAAO,UAAU,mBAAmB,CAAC,KAAK,EAAE,QAAQ,CAAC,wBAAwB,CAAC,+BAMpF"}