@ai-digital-factory/state-flow 0.1.0 → 0.1.1

package/README.md

@@ -2,15 +2,117 @@
 
 React library for flow-style state (states, transitions, and related UI). See repository `CONTEXT.md` for domain vocabulary.
 
-## Application chart authoring (TSX, no React app)
+## Flow authoring (TSX, no React app)
 
-Chart-only projects declare flows as `.tsx` modules using `Flow`, `State`, and `Transition`. They do not install `react` or `@types/react`.
+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`.
 
-Extend the chart preset (TypeScript requires `jsx` for `.tsx`; the preset supplies it):
+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.charts.json",
+  "extends": "@ai-digital-factory/state-flow/tsconfig.flows.json",
   "include": ["src/**/*.tsx"]
 }
 ```

package/dist/index.d.ts

@@ -1,11 +1,11 @@
 import { ReactElement, ReactNode } from 'react';
-import { ApplicationChartDefinition } from '@ai-digital-factory/state-flow-chart';
-export { ApplicationHookContext, DEFAULT_TRANSITION_NAME, DefaultTransitionName, STATE_APPLICATION_HOOK_EXPORT_NAMES, TRANSITION_APPLICATION_HOOK_EXPORT_NAMES, TransitionHookContext } from '@ai-digital-factory/state-flow-chart';
+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 chart identifier (e.g. `visitor-access`). Enforced by chart check. */
+    /** Lowercase kebab-case flow identifier (e.g. `visitor-access`). Enforced by flow check. */
     name: string;
     description: string;
     default: string;
@@ -20,6 +20,17 @@ 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. */
@@ -28,54 +39,125 @@ declare namespace State {
     var displayName: string;
 }
 
-type TransitionProps = {
-    to: string;
+type ParallelStateProps = {
+    id?: string;
     name: string;
     description: string;
+    /** `<Region>` and `<FlowList>` children, all active together, plus Transitions. */
     children?: ReactNode;
 };
-/** Declares an allowed transition; rendered by `Flow`, not directly. */
-declare function Transition(_props: TransitionProps): null;
-declare namespace Transition {
+/**
+ * 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 ApplicationChartRendererProps = {
-    chart: ApplicationChartDefinition;
+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;
 };
-declare function ApplicationChartRenderer({ chart, }: ApplicationChartRendererProps): ReactElement;
+/** One region of a `ParallelState`; rendered by `Flow`, not directly. */
+declare function Region(_props: RegionProps): null;
+declare namespace Region {
+    var displayName: string;
+}
 
-type ChartPageHeaderProps = {
-    title: string;
+type FlowListProps = {
+    /** Lowercase kebab-case region name. */
+    name: string;
     description: string;
-    /** Lowercase kebab-case chart id; picks a header icon when set. */
-    chartId?: string;
+    /** The reusable child Flow every member executes, from the same flows package. */
+    flow: string;
 };
-declare function ChartPageHeader({ title, description, chartId, }: ChartPageHeaderProps): ReactElement;
-
-declare function ChartHeaderIcon({ chartId, }: {
-    chartId?: string;
-}): ReactElement;
-declare function chartNavIcon(chartId: string): 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 ParsedTransition = {
-    fromId: string;
-    fromName: string;
-    toId: string;
-    toName: string;
+type FinalStateProps = {
+    id?: string;
     name: string;
     description: string;
 };
-type ParsedState = {
-    id: 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;
 };
-type ParsedChart = {
-    states: ParsedState[];
-    edges: ParsedTransition[];
-    initialId: string;
+/** 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;
@@ -93,14 +175,14 @@ type DiagramOverviewProps = {
 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(chart: ParsedChart, title: string, instanceId: string): string;
+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 extractApplicationChartDefinition(node: ReactNode): ApplicationChartDefinition;
-type ApplicationChartComponent = () => ReactNode;
-declare function extractApplicationChartDefinitionFromComponent(component: ApplicationChartComponent): ApplicationChartDefinition;
+declare function extractFlowDefinition(node: ReactNode): FlowDefinition;
+type FlowComponent = () => ReactNode;
+declare function extractFlowDefinitionFromComponent(component: FlowComponent): FlowDefinition;
 
-export { type ApplicationChartComponent, ApplicationChartRenderer, type ApplicationChartRendererProps, ChartHeaderIcon, ChartPageHeader, type ChartPageHeaderProps, DiagramOverview, type DiagramOverviewProps, Flow, type FlowProps, State, StateFlowPlaceholder, type StateProps, Transition, type TransitionProps, chartNavIcon, diagramSvg, extractApplicationChartDefinition, extractApplicationChartDefinitionFromComponent, mergeScrollYIntoSearch, parseScrollYFromSearch, replaceBrowserUrlSearch };
+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 };