@ai-digital-factory/state-flow 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,18 @@
+Copyright (c) 2026 coupleaddagaming@gmail.com. All rights reserved.
+
+State Flow is proprietary software. No license is granted by downloading,
+accessing, or receiving this software or its documentation. All third-party
+use, including personal, noncommercial and commercial use, requires prior
+written permission from the copyright holder. Copying, modifying, distributing,
+sublicensing or incorporating this software into another product also requires
+prior written permission. Request permission at coupleaddagaming@gmail.com.
+
+Any permission granted separately is governed by its written terms. This notice
+does not alter the licenses of third-party dependencies or bundled third-party
+materials; their respective licenses continue to apply.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO MERCHANTABILITY, FITNESS FOR A PARTICULAR
+PURPOSE AND NONINFRINGEMENT. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW,
+THE COPYRIGHT HOLDER IS NOT LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY
+ARISING FROM THE SOFTWARE OR ITS USE.

package/README.md

@@ -1,3 +1,127 @@
-# Temporary Holding Version
+# @ai-digital-factory/state-flow
 
-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.
+React library for flow-style state (states, transitions, and related UI). See repository `CONTEXT.md` for domain vocabulary.
+
+## Flow authoring (TSX, no React app)
+
+Flow-only projects declare flows as `.tsx` modules using `Flow`, `State`, `FinalState`, `Transition` and `To`, plus `ParallelState`, `Region` and `FlowList` for composition. They do not install `react` or `@types/react`.
+
+A Flow is a static graph (ADR 0087). Each Transition lists its allowed destinations as `<To>` children, each describing when that destination is selected:
+
+```tsx
+import {
+  FinalState,
+  Flow,
+  State,
+  To,
+  Transition,
+} from "@ai-digital-factory/state-flow";
+
+export default function PlaceOrder() {
+  return (
+    <Flow name="place-order" description="One broker order." default="idle">
+      <State name="idle" description="Not yet submitted.">
+        <Transition name="submit-order" description="Send the order.">
+          <To state="placed" description="The broker accepted it." />
+          <To state="rejected" description="The broker rejected it." />
+        </Transition>
+      </State>
+      <State name="placed" description="Open at the broker.">
+        <Transition name="record-fill" description="The order filled.">
+          <To state="filled" description="Always." />
+        </Transition>
+      </State>
+      <FinalState name="rejected" description="Refused by the broker." />
+      <FinalState name="filled" description="Filled." />
+    </Flow>
+  );
+}
+```
+
+- One `<To>` makes a fixed destination; its `onTransition` handler is optional. Several make the Transition branch; its handler module must export `onTransition` returning one of the destination names.
+- `<FinalState>` has no outgoing Transitions and no handlers. Reaching it completes the instance.
+- Flow check and the `state-flow/flow-module` ESLint rule reject Transitions without a `<To>`, unknown or repeated destinations, empty To descriptions, Transitions on a FinalState, and graphs that are not static JSX (conditional children, `.map(...)`, computed props or elements built outside the Flow).
+- The diagram draws a branching Transition as one named segment into a split, with one branch per `<To>` labelled by its description. Final states use a distinct colour and a `FINAL` tag.
+
+### Composition: compound, parallel and FlowList (ADR 0095, 0096)
+
+Larger lifecycles compose Flows declaratively. Nested States, regions and placed Flows are all part of the static graph; handlers never start child Flows.
+
+```tsx
+<State name="signed-in" description="A user is signed in." default="dashboard">
+  <State name="dashboard" description="Overview.">
+    <Transition name="start-upload-batch" description="Upload files.">
+      <To state="uploading" description="Always." />
+    </Transition>
+  </State>
+  <State name="uploading" description="Each file uploads independently.">
+    <FlowList name="uploads" flow="file-upload" description="One per file." />
+    <Transition name="batch-finished" description="All done." trigger="done">
+      <To state="dashboard" description="Always." />
+    </Transition>
+  </State>
+  <ParallelState name="order-desk" description="Order and watchlist together.">
+    <Region name="order" description="One order." flow="place-order" />
+    <Region name="watchlist" description="Prices." default="watching">
+      <State name="watching" description="Live prices." />
+    </Region>
+  </ParallelState>
+  <Transition name="sign-out" description="Busy while work runs.">
+    <To state="signed-out" description="Always." />
+  </Transition>
+  <Transition
+    name="force-sign-out"
+    description="Interrupt work."
+    childWork="interrupt"
+  >
+    <To state="signed-out" description="Always." />
+  </Transition>
+</State>
+```
+
+- A `<State>` with nested States and a `default` is compound; `<State flow="x">` places one execution of Flow `x` from the same flows package. A `<ParallelState>` activates every `<Region>` and `<FlowList>` it contains.
+- Transitions reach only siblings in their own region. Declare a Transition that leaves a containing State on that State; it is available from every nested configuration.
+- `childWork="block"` (default) answers `busy` while descendant work is running or unresolved; `childWork="interrupt"` cancels it and proceeds. Neither undoes an external effect.
+- `trigger="done"` fires once every region completes, with each region's FinalState (and each FlowList member's) as payload. Completing a child never completes the root.
+- State and Transition names are unique across the whole flow file. The diagram tags composite States `COMPOUND` or `PARALLEL`, lists placed Flows and FlowList templates, and brackets nested States under their parent.
+
+In the handlers package, a child Flow declares its input in `src/<flow-id>/input.ts` (`export const inputSchema = z.strictObject({...})`), read as `context.input`. A composite State's handler exports `children: { run, recovery }`, which receives the entering Transition's payload and returns child inputs and FlowList members (`{ uploads: [{ key, input }] }`). Generated `ChildInputs_<state>` and `Completion_<state>` types describe both.
+
+### Migrating from the `to` prop
+
+The `to` prop on `Transition` has been removed. Move the target into a `<To>` child and describe when it applies:
+
+```diff
+-<Transition to="present" name="unlock-succeeds" description="Correct credentials." />
++<Transition name="unlock-succeeds" description="Correct credentials.">
++  <To state="present" description="Always." />
++</Transition>
+```
+
+Recompile the flows package and its handlers package together: compiled flow artifacts move to schema version 2, generated `TransitionContext` types expose `destinations` instead of `toState`, and callback contexts expose `dependencies` instead of `config`. In each handlers package, rename `src/<flow-id>/config.ts` to `dependencies.ts` and its `Config` type to `Dependencies`; services import `Dependencies` instead of `FlowConfig` from the compiled module. Runtime types also lose their `Durable` prefix (ADR 0089), for example `TransitionCallback` instead of `DurableTransitionCallback`. Durable definition identities of flows without branching or final states are unchanged, so existing instances reopen.
+
+The same release (ADRs 0089 and 0090) also renames and removes, without aliases:
+
+- `@ai-digital-factory/state-flow-chart` is now `@ai-digital-factory/state-flow-definition`; update dependencies and imports.
+- Presets: extend `@ai-digital-factory/state-flow/tsconfig.flows.json` and import `eslint.flows.config.js` (formerly `tsconfig.charts.json`, `eslint.charts.config.js`). The ESLint rule is `state-flow/flow-module`.
+- Rule IDs in `state-flow.rules.json`: `state-chart.*` is `flow.*`, `application-hook.*` is `handler.*`, and `transition.name-unique-across-chart` is `transition.name-unique-across-flow`.
+- Identifiers drop `Application` and use Flow/Handler, for example `FlowDefinition`, `defineFlow`, `HandlerContext`; data fields `chartName`/`chartId` are `flowName`/`flowId`, and compile output is under `dist/flows/`.
+- Services: `await runtime.createFlow(compiled, dependencies)`, `await flow.ensureInstance({ instanceId })`, then `when(state).handle(outcomes).dispatch(input)`. The builder `.handleFailure(...).run()`, `runtime.flow`, `handleCreate`/`handleOpen`/`handleEnsure`, direct `when(state).dispatch` and `DispatchError`/`OperationError` are gone.
+
+Extend the flow preset (TypeScript requires `jsx` for `.tsx`; the preset supplies it):
+
+```json
+{
+  "extends": "@ai-digital-factory/state-flow/tsconfig.flows.json",
+  "include": ["src/**/*.tsx"]
+}
+```
+
+Or set the same options yourself, including `"types": ["@ai-digital-factory/state-flow/types"]` and `"jsx": "react-jsx"`.
+
+Preview and in-app rendering supply React at runtime via the State Flow CLI or your React consumer.
+
+## License
+
+Proprietary software. All third-party use requires prior written permission from
+coupleaddagaming@gmail.com. See LICENSE.

package/dist/index.d.ts

@@ -0,0 +1,188 @@
+import { ReactElement, ReactNode } from 'react';
+import { FlowDefinition, ParsedState, ParsedTransition, ParsedFlow } from '@ai-digital-factory/state-flow-definition';
+export { DEFAULT_TRANSITION_NAME, DefaultTransitionName, HandlerContext, STATE_HANDLER_EXPORT_NAMES, TRANSITION_HANDLER_EXPORT_NAMES, TransitionHandlerContext } from '@ai-digital-factory/state-flow-definition';
+
+declare function StateFlowPlaceholder(): ReactElement;
+
+type FlowProps = {
+    /** Lowercase kebab-case flow identifier (e.g. `visitor-access`). Enforced by flow check. */
+    name: string;
+    description: string;
+    default: string;
+    children?: ReactNode;
+};
+declare function Flow({ name, description, default: defaultStateName, children, }: FlowProps): ReactElement;
+declare namespace Flow {
+    var displayName: string;
+}
+
+type StateProps = {
+    id?: string;
+    name: string;
+    description: string;
+    /**
+     * Compound State (ADR 0095, 0096): the nested child State entered with this State. Required
+     * when the State contains nested `<State>` / `<FinalState>` children.
+     */
+    default?: string;
+    /**
+     * Compound State whose child is one placement of a reusable Flow of the same flows package.
+     * Its completion fires this State's `trigger="done"` Transition.
+     */
+    flow?: string;
+    /** Transitions, nested States, or one `<FlowList>`. */
+    children?: ReactNode;
+};
+/** Declares a flow state; rendered by `Flow`, not directly. */
+declare function State(_props: StateProps): null;
+declare namespace State {
+    var displayName: string;
+}
+
+type ParallelStateProps = {
+    id?: string;
+    name: string;
+    description: string;
+    /** `<Region>` and `<FlowList>` children, all active together, plus Transitions. */
+    children?: ReactNode;
+};
+/**
+ * Declares a parallel State (ADR 0095, 0096): entering it activates every declared region.
+ * It completes, firing its `trigger="done"` Transition, when every region completes.
+ */
+declare function ParallelState(_props: ParallelStateProps): null;
+declare namespace ParallelState {
+    var displayName: string;
+}
+
+type RegionProps = {
+    /** Lowercase kebab-case; addressed as `state:region` from the parallel State. */
+    name: string;
+    description: string;
+    /** For nested States: the child entered with the region. */
+    default?: string;
+    /** Instead of nested States: one placement of a reusable Flow of the same flows package. */
+    flow?: string;
+    /** Nested `<State>` / `<FinalState>` children of an inline region. */
+    children?: ReactNode;
+};
+/** One region of a `ParallelState`; rendered by `Flow`, not directly. */
+declare function Region(_props: RegionProps): null;
+declare namespace Region {
+    var displayName: string;
+}
+
+type FlowListProps = {
+    /** Lowercase kebab-case region name. */
+    name: string;
+    description: string;
+    /** The reusable child Flow every member executes, from the same flows package. */
+    flow: string;
+};
+/**
+ * Declares a FlowList (ADR 0095, 0096): one keyed execution of a reusable Flow per member. The
+ * containing State's `children` handler returns the members when the State is entered; the
+ * membership is fixed for that activation. Use inside a `<State>` or a `<ParallelState>`.
+ */
+declare function FlowList(_props: FlowListProps): null;
+declare namespace FlowList {
+    var displayName: string;
+}
+
+type FinalStateProps = {
+    id?: string;
+    name: string;
+    description: string;
+};
+/**
+ * Declares a terminal State: no outgoing Transitions and no callbacks. Reaching it completes the
+ * flow instance (ADR 0087). Rendered by `Flow`, not directly.
+ */
+declare function FinalState(_props: FinalStateProps): null;
+declare namespace FinalState {
+    var displayName: string;
+}
+
+type TransitionProps = {
+    name: string;
+    description: string;
+    /**
+     * When this Transition leaves a composite State while descendant work is running or
+     * unresolved (ADR 0095): `block` (default) answers `busy`; `interrupt` cancels that work
+     * cooperatively and proceeds without waiting for it.
+     */
+    childWork?: "block" | "interrupt";
+    /**
+     * `done`: fired by the runtime when the State's children complete, with their completion
+     * result as payload. Allowed once per composite State. Omitted: dispatched by the application.
+     */
+    trigger?: "dispatch" | "done";
+    /**
+     * One or more `<To state="..." description="..." />` children. A single destination is fixed;
+     * several make the Transition branch, and its `onTransition` selects one (ADR 0087).
+     */
+    children?: ReactNode;
+};
+/** Declares an allowed transition; rendered by `Flow`, not directly. */
+declare function Transition(_props: TransitionProps): null;
+declare namespace Transition {
+    var displayName: string;
+}
+
+type ToProps = {
+    /** Destination State name. */
+    state: string;
+    /** When this destination is selected, for example "Broker accepted the order." */
+    description: string;
+};
+/** Declares one allowed destination of its parent `Transition`; rendered by `Flow`, not directly. */
+declare function To(_props: ToProps): null;
+declare namespace To {
+    var displayName: string;
+}
+
+type FlowRendererProps = {
+    flow: FlowDefinition;
+};
+declare function FlowRenderer({ flow }: FlowRendererProps): ReactElement;
+
+type FlowPageHeaderProps = {
+    title: string;
+    description: string;
+    /** Lowercase kebab-case flow id; picks a header icon when set. */
+    flowId?: string;
+};
+declare function FlowPageHeader({ title, description, flowId, }: FlowPageHeaderProps): ReactElement;
+
+declare function FlowHeaderIcon({ flowId }: {
+    flowId?: string;
+}): ReactElement;
+declare function flowNavIcon(flowId: string): string;
+
+type DiagramOverviewProps = {
+    svgHtml: string;
+    states: ParsedState[];
+    edges: ParsedTransition[];
+    /** When set, sync zoom, pan, and diagram focus to the page URL query string. */
+    viewPersistenceKey?: string;
+    /** Highlight a transition edge after a guard blocks (simulate). */
+    guardBlockedEdgeIndex?: number | null;
+    /** Stack detail below the diagram, or show state/transition aside (tool viewers). */
+    detailLayout?: "inline" | "split";
+    /** When set with `detailLayout="split"`, pre-select this state in the aside. */
+    initialStateId?: string;
+};
+declare function DiagramOverview({ svgHtml, states, edges, viewPersistenceKey, guardBlockedEdgeIndex, detailLayout, initialStateId, }: DiagramOverviewProps): ReactElement;
+
+/** Forward edges run above the states; return edges run below them. */
+declare function diagramSvg(flow: ParsedFlow, title: string, instanceId: string): string;
+
+declare function parseScrollYFromSearch(search: string): number | null;
+declare function mergeScrollYIntoSearch(search: string, scrollY: number): string;
+declare function replaceBrowserUrlSearch(search: string): void;
+
+declare function extractFlowDefinition(node: ReactNode): FlowDefinition;
+type FlowComponent = () => ReactNode;
+declare function extractFlowDefinitionFromComponent(component: FlowComponent): FlowDefinition;
+
+export { DiagramOverview, type DiagramOverviewProps, FinalState, type FinalStateProps, Flow, type FlowComponent, FlowHeaderIcon, FlowList, type FlowListProps, FlowPageHeader, type FlowPageHeaderProps, type FlowProps, FlowRenderer, type FlowRendererProps, ParallelState, type ParallelStateProps, Region, type RegionProps, State, StateFlowPlaceholder, type StateProps, To, type ToProps, Transition, type TransitionProps, diagramSvg, extractFlowDefinition, extractFlowDefinitionFromComponent, flowNavIcon, mergeScrollYIntoSearch, parseScrollYFromSearch, replaceBrowserUrlSearch };