@fieldtripjs/react 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Martin Aarhus Gregersen
+
+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,3 +1,9 @@
-# Temporary Holding Version
+# @fieldtripjs/react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Headless React bindings for [@fieldtripjs/core](https://www.npmjs.com/package/@fieldtripjs/core): `useFlow` and `createFlowContext`. State and navigation from fieldtrip, UI from you.
+
+```sh
+pnpm add @fieldtripjs/core @fieldtripjs/react
+```
+
+See the [main README](https://github.com/aarhusgregersen/fieldtrip#readme) for docs.

package/dist/context.d.ts

@@ -0,0 +1,10 @@
+import type { AnyFlow } from "@fieldtripjs/core";
+import { type ReactNode } from "react";
+import { type FlowController, type UseFlowOptions } from "./use-flow.js";
+export interface FlowContext<FL extends AnyFlow> {
+    readonly FlowProvider: (props: UseFlowOptions<FL> & {
+        readonly children: ReactNode;
+    }) => ReactNode;
+    readonly useFlowContext: () => FlowController<FL>;
+}
+export declare function createFlowContext<FL extends AnyFlow>(flow: FL): FlowContext<FL>;

package/dist/context.js

@@ -0,0 +1,17 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
+import { useFlow } from "./use-flow.js";
+// One context per flow, so step components deep in the tree get the flow's own types.
+export function createFlowContext(flow) {
+    const Context = createContext(null);
+    function FlowProvider({ children, ...options }) {
+        return _jsx(Context.Provider, { value: useFlow(flow, options), children: children });
+    }
+    function useFlowContext() {
+        const controller = useContext(Context);
+        if (!controller)
+            throw new Error("useFlowContext must be used inside its FlowProvider");
+        return controller;
+    }
+    return { FlowProvider, useFlowContext };
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { createFlowContext, type FlowContext } from "./context.js";
+export { useFlow, type FieldProps, type FlowController, type UseFlowOptions } from "./use-flow.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { createFlowContext } from "./context.js";
+export { useFlow } from "./use-flow.js";

package/dist/use-flow.d.ts

@@ -0,0 +1,30 @@
+import { type AnyFlow, type FieldIssues, type FieldName, type FlowState, type FlowValues, type StepName } from "@fieldtripjs/core";
+export interface UseFlowOptions<FL extends AnyFlow> {
+    readonly initialState?: FlowState<FL>;
+    readonly onChange?: (state: FlowState<FL>) => void;
+}
+export interface FieldProps<N extends string = string> {
+    readonly name: N;
+    readonly value: unknown;
+    readonly issues: readonly string[];
+    readonly visible: boolean;
+    readonly onChange: (value: unknown) => void;
+}
+export interface FlowController<FL extends AnyFlow> {
+    readonly state: FlowState<FL>;
+    readonly step: StepName<FL>;
+    readonly path: readonly StepName<FL>[];
+    readonly values: FlowValues<FL>;
+    readonly inputs: Readonly<Record<string, unknown>>;
+    readonly issues: FieldIssues;
+    readonly visibleFields: readonly FieldName<FL>[];
+    readonly isComplete: boolean;
+    readonly isPending: boolean;
+    readonly canGoBack: boolean;
+    readonly setInput: (name: FieldName<FL>, value: unknown) => void;
+    readonly field: <N extends FieldName<FL>>(name: N) => FieldProps<N>;
+    readonly next: () => Promise<boolean>;
+    readonly back: () => void;
+    readonly reset: () => void;
+}
+export declare function useFlow<FL extends AnyFlow>(flow: FL, options?: UseFlowOptions<FL>): FlowController<FL>;

package/dist/use-flow.js

@@ -0,0 +1,75 @@
+import { back as backState, next as nextState, path as pathOf, result, setInputs, start, visibleFields as visibleFieldsOf, } from "@fieldtripjs/core";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+export function useFlow(flow, options = {}) {
+    const [state, setState] = useState(() => options.initialState ?? start(flow));
+    const [issues, setIssues] = useState({});
+    const [isPending, setPending] = useState(false);
+    const latest = useRef(state);
+    const onChange = useRef(options.onChange);
+    useEffect(() => {
+        onChange.current = options.onChange;
+    });
+    const commit = useCallback((next) => {
+        latest.current = next;
+        setState(next);
+        onChange.current?.(next);
+    }, []);
+    const setInput = useCallback((name, value) => {
+        commit(setInputs(flow, latest.current, { [name]: value }));
+        setIssues(({ [name]: _cleared, ...rest }) => rest);
+    }, [flow, commit]);
+    const next = useCallback(async () => {
+        const submitted = latest.current;
+        setPending(true);
+        try {
+            const outcome = await nextState(flow, submitted);
+            // Input that arrived while validating would be silently overwritten by the stale result.
+            if (latest.current !== submitted)
+                return false;
+            if (!outcome.ok) {
+                setIssues(outcome.issues);
+                return false;
+            }
+            setIssues({});
+            commit(outcome.state);
+            return true;
+        }
+        finally {
+            setPending(false);
+        }
+    }, [flow, commit]);
+    const back = useCallback(() => {
+        setIssues({});
+        commit(backState(flow, latest.current));
+    }, [flow, commit]);
+    const reset = useCallback(() => {
+        setIssues({});
+        commit(start(flow));
+    }, [flow, commit]);
+    const inputs = state.inputs[state.current] ?? {};
+    const visibleFields = useMemo(() => visibleFieldsOf(flow, state), [flow, state]);
+    const field = useCallback((name) => ({
+        name,
+        value: inputs[name],
+        issues: issues[name] ?? [],
+        visible: visibleFields.includes(name),
+        onChange: (value) => setInput(name, value),
+    }), [inputs, issues, visibleFields, setInput]);
+    return useMemo(() => ({
+        state,
+        step: state.current,
+        path: pathOf(state),
+        values: result(flow, state),
+        inputs,
+        issues,
+        visibleFields,
+        isComplete: state.status === "complete",
+        isPending,
+        canGoBack: state.history.length > 0 || state.status === "complete",
+        setInput,
+        field,
+        next,
+        back,
+        reset,
+    }), [flow, state, inputs, issues, visibleFields, isPending, setInput, field, next, back, reset]);
+}

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@fieldtripjs/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Headless React bindings for @fieldtripjs/core.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Martin Aarhus Gregersen",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aarhusgregersen/fieldtrip.git",
+    "directory": "packages/react"
+  },
+  "homepage": "https://github.com/aarhusgregersen/fieldtrip#readme",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "dependencies": {
+    "@fieldtripjs/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.3",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "jsdom": "^30.1.1",
+    "react": ">=18",
+    "react-dom": "^19.3.0",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.3",
+    "zod": "^4.6.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "forms",
+    "wizard",
+    "multi-step",
+    "state-machine",
+    "typescript",
+    "standard-schema",
+    "react",
+    "hooks"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run --typecheck",
+    "typecheck": "tsc --noEmit"
+  }
 }