@myriadcodelabs/uiflow 0.1.0 → 0.1.2

package/README.md

@@ -1,190 +1,338 @@
 # UIFlow
 
-Explicit, code-first UI flow orchestration for React. UIFlow lets you define flows as plain objects with named steps, mix UI and logic steps, and move between them by returning the next step name. It’s useful when you want predictable, testable multi‑step experiences without wiring up routers, wizards, or state machines by hand.
+Code-first flow orchestration for React.
 
-## Why it matters
+UIFlow helps you build multi-step UI without scattering state and transition logic across many components. You define steps in one place, and each step decides what comes next.
 
-- **Clarity:** Flows are defined in one place with explicit step names and transitions.
-- **Flexibility:** Combine UI steps and async logic steps in the same flow.
-- **Reusability:** Share cross‑flow state through event channels.
+## Why UIFlow
 
-## Quick example
+- Keep flow logic explicit: step names + transitions are centralized.
+- Mix UI and async logic naturally: both are first-class steps.
+- Share state across independent flows with channels.
+- Stay in plain TypeScript objects, not custom DSLs.
+
+## Mental model (60 seconds)
+
+A flow is:
+- `steps`: a map of step names to step definitions
+- `start`: first step name
+
+A step is either:
+- UI step: `input`, `view`, `onOutput`
+- Action step: `input`, `action`, `onOutput`
+
+Transition rule:
+- `onOutput` returns next step name (string) to move forward
+- returning `void` keeps the same step and re-renders
+
+## Install
+
+```bash
+pnpm add @myriadcodelabs/uiflow
+# or
+npm i @myriadcodelabs/uiflow
+# or
+yarn add @myriadcodelabs/uiflow
+```
+
+## Imports
+
+```ts
+import { FlowRunner, defineFlow, createFlowChannel, type OutputHandle } from "@myriadcodelabs/uiflow";
+```
+
+Use package-root imports only.
+
+## Quick start (minimal runnable example)
 
 ```tsx
-import React from "react";
-import { FlowRunner, defineFlow, createFlowChannel } from "@myriadcodelabs/uiflow";
+"use client";
 
-type StudyData = {
-  deckId: string;
-  cards: CardWithState[];
-  activeCardId: string | null;
-};
+import { FlowRunner, defineFlow, type OutputHandle } from "@myriadcodelabs/uiflow";
 
-type CardWithState = {
-  id: string;
-  question: string;
-  answer: string;
-  flipped: boolean;
-  rating: "easy" | "medium" | "hard" | null;
-};
+type Data = { name: string };
+type AskNameOutput = { action: "setName"; value: string } | { action: "submit" };
 
-export type ShowCardOutput =
-    | { action: "flip"; cardId: string }
-    | { action: "rate"; rating: Rating; cardId: string }
-    | { action: "next"; cardId: string };
+function AskNameView(props: {
+  input: { name: string };
+  output: OutputHandle<AskNameOutput>;
+}) {
+  return (
+    <div>
+      <input
+        value={props.input.name}
+        onChange={(e) => props.output.emit({ action: "setName", value: e.target.value })}
+        placeholder="Your name"
+      />
+      <button onClick={() => props.output.emit({ action: "submit" })}>Continue</button>
+    </div>
+  );
+}
 
-const studiedCounter = createFlowChannel<number>(0);
+function DoneView(props: { input: { message: string }; output: OutputHandle<never> }) {
+  return <h2>{props.input.message}</h2>;
+}
 
+const onboardingFlow = defineFlow<Data>(
+  {
+    askName: {
+      input: (data) => ({ name: data.name }),
+      view: AskNameView,
+      onOutput: (data, output) => {
+        if (output.action === "setName") {
+          data.name = output.value;
+          return;
+        }
+        if (output.action === "submit") {
+          return "done";
+        }
+      },
+    },
+
+    done: {
+      input: (data) => ({ message: `Welcome, ${data.name || "friend"}!` }),
+      view: DoneView,
+      onOutput: () => {},
+    },
+  },
+  { start: "askName" }
+);
+
+export function App() {
+  return <FlowRunner flow={onboardingFlow} initialData={{ name: "" }} />;
+}
+```
+
+## Practical pattern: study/review flow (real-world)
+
+This pattern is taken from practical flashcards usage.
+
+```ts
+import { defineFlow } from "@myriadcodelabs/uiflow";
+
+type Data = {
+  deckId: string;
+  flowData: {
+    cards: Array<{ id: string; flipped: boolean; rating: "easy" | "good" | "hard" | "again" | null }>;
+    activeCardId: string | null;
+  };
+};
 
-const studyFlow = defineFlow<StudyData>(
+type StudyOutput =
+  | { action: "flip"; cardId: string }
+  | { action: "rate"; cardId: string; rating: "easy" | "good" | "hard" | "again" }
+  | { action: "next"; cardId: string };
+
+export const studyFlow = defineFlow<Data>(
   {
-    // step 1
     fetchCards: {
       input: (data) => ({ deckId: data.deckId }),
       action: async ({ deckId }, data) => {
-        const cards = await fakeFetchCards(deckId);
-        data.cards = cards.map((card) => ({ ...card, flipped: false, rating: null }));
-        data.activeCardId = null;
+        const cards = await fetchCardsListAction(deckId);
+        data.flowData.cards = (cards ?? []).map((c) => ({ id: c.id, flipped: false, rating: null }));
+        data.flowData.activeCardId = null;
         return { ok: true };
       },
       onOutput: () => "decide",
     },
 
-    // step 2
     decide: {
-      input: (data) => ({ hasCards: data.cards.length > 0 }),
+      input: (data) => ({ hasCards: data.flowData.cards.length > 0 }),
       action: ({ hasCards }) => hasCards,
-      onOutput: (_, exists) => (exists ? "study" : "noCard"),
+      onOutput: (_, hasCards) => (hasCards ? "study" : "empty"),
     },
-    // if no card present
-    noCard: {
-      input: () => ({}),
-      view: NoCardView,
-      onOutput: () => {},
-    },
-    // step 3
-    study: {
-      input: (data) => ({ cards: data.cards }),
-      view: CardView,
-      onOutput: (data, output, events) => {
-        const card = data.cards.find((c) => c.id === output.cardId);
-        if (!card) return "study";
 
+    study: {
+      input: (data) => ({ cards: data.flowData.cards, activeCardId: data.flowData.activeCardId }),
+      view: StudyCardsView,
+      onOutput: (data, output: StudyOutput, events) => {
         if (output.action === "flip") {
-          data.activeCardId = card.id;
-          card.flipped = true;
+          data.flowData.activeCardId = output.cardId;
+          const card = data.flowData.cards.find((c) => c.id === output.cardId);
+          if (card) card.flipped = true;
           return "study";
         }
 
         if (output.action === "rate") {
-          data.activeCardId = card.id;
-          card.rating = output.rating ?? null;
+          data.flowData.activeCardId = output.cardId;
+          const card = data.flowData.cards.find((c) => c.id === output.cardId);
+          if (card) card.rating = output.rating;
           return "review";
         }
 
         if (output.action === "next") {
-          events?.studiedCounter.emit((c) => c + 1);
-          data.activeCardId = null;
+          events?.studiedCounter.emit((n: number) => n + 1);
+          data.flowData.activeCardId = null;
           return "fetchCards";
         }
       },
     },
 
-    // step 4: if user does review
     review: {
       input: (data) => ({
         deckId: data.deckId,
-        cardId: data.activeCardId!,
-        rating: data.cards.find((c) => c.id === data.activeCardId)?.rating!,
+        cardId: data.flowData.activeCardId,
+        rating: data.flowData.cards.find((c) => c.id === data.flowData.activeCardId)?.rating,
       }),
       action: async ({ deckId, cardId, rating }) => {
-        await fakeReviewCard(deckId, cardId, rating);
+        await reviewCard(deckId, cardId, rating);
         return { ok: true };
       },
       onOutput: (data, _, events) => {
-        events?.studiedCounter.emit((c) => c + 1);
-        data.activeCardId = null;
+        events?.studiedCounter.emit((n: number) => n + 1);
+        data.flowData.activeCardId = null;
         return "fetchCards";
       },
     },
+
+    empty: {
+      input: () => ({}),
+      view: EmptyView,
+      onOutput: () => {},
+    },
   },
   { start: "fetchCards" }
 );
 ```
 
-The example components are defined here.
+## Cross-flow communication with channels
+
+Use channels when two independent flows need shared reactive state.
 
 ```tsx
-const CardView: React.FC<{
-  input: { cards: CardWithState[] };
-  output: OutputHandle<ShowCardOutput>;
-}> = ({ input, output }) => (
-  <div>
-    {input.cards.map((card) => (
-      <div key={card.id}>
-        <div>{card.question}</div>
-        {card.flipped ? <div>{card.answer}</div> : null}
-        <button onClick={() => output.emit({ cardId: card.id, action: "flip" })}>Show Answer</button>
-        <button onClick={() => output.emit({ cardId: card.id, action: "rate", rating: "easy" })}>Easy</button>
-        <button onClick={() => output.emit({ cardId: card.id, action: "rate", rating: "medium" })}>Medium</button>
-        <button onClick={() => output.emit({ cardId: card.id, action: "rate", rating: "hard" })}>Hard</button>
-        <button onClick={() => output.emit({ cardId: card.id, action: "next" })}>Next</button>
-      </div>
-    ))}
-  </div>
-);
+"use client";
 
-const NoCardView: React.FC<{ input: {}; output: { emit: () => void } }> = () => (
-  <div>No cards available.</div>
-);
-```
-The FlowRunner is used to call the flow and set initial data and channels.
+import { useMemo } from "react";
+import { createFlowChannel, FlowRunner } from "@myriadcodelabs/uiflow";
+
+export function FlashcardsScreen({ deckId }: { deckId: string }) {
+  const studiedCounter = useMemo(() => createFlowChannel<number>(0), []);
+  const channels = useMemo(() => ({ studiedCounter }), [studiedCounter]);
 
-```tsx
-export function App() {
   return (
-    <FlowRunner
-      flow={studyFlow}
-      initialData={{ deckId: "deck-1", cards: [], activeCardId: null }}
-      eventChannels={{ studiedCounter }}
-    />
+    <>
+      <FlowRunner flow={counterFlow} initialData={{}} eventChannels={channels} />
+      <FlowRunner
+        flow={studyFlow}
+        initialData={{ deckId, flowData: { cards: [], activeCardId: null } }}
+        eventChannels={channels}
+      />
+    </>
   );
 }
 ```
 
-## API Reference (exported only)
+## API reference
+
+### `defineFlow(steps, { start })`
+- Validates `start` exists in `steps`.
+- Supports optional `channelTransitions` mapping (`channelKey -> resolver`).
+- A resolver receives `{ data, currentStep, events, channelKey }` and returns `nextStep | void` (sync/async).
+- Returns flow definition consumed by `FlowRunner`.
+
+Example:
 
-### 1) Where the flow is called
+```ts
+const flow = defineFlow(
+  {
+    fetchList: { /* ... */ },
+    showList: { /* ... */ },
+  },
+  {
+    start: "fetchList",
+    channelTransitions: {
+      refresh: ({ events, currentStep }) => {
+        const refreshCount = events?.refresh.get() ?? 0;
+        if (refreshCount > 0 && currentStep !== "fetchList") return "fetchList";
+        return;
+      },
+    },
+  }
+);
+```
 
-#### `FlowRunner` (React component)
-Runs a flow and renders UI steps.
+### `FlowRunner`
 
 ```tsx
 <FlowRunner flow={flow} initialData={initialData} eventChannels={channels} />
 ```
 
-- `flow: FlowDefinition<D>` — created by `defineFlow`.
-- `initialData: D` — shared mutable data for this flow instance.
-- `eventChannels?: EventChannels` — optional shared channels; emitting causes re-render.
+Props:
+- `flow`: flow definition
+- `initialData`: mutable per-flow data object
+- `eventChannels?`: optional channels map
+- `eventChannelsStrategy?`: `"sticky"` (default) or `"replace"`
+
+### `createFlowChannel(initial)`
+Creates channel with:
+- `get()`
+- `emit(update)`
+- `subscribe(listener)`
+
+### `OutputHandle<O>`
+UI steps emit events with:
+- `output.emit(payload)`
+
+## How to keep flows manageable
+
+1. Keep views dumb: render from `input`, emit intent via `output.emit`.
+2. Keep transition logic in `onOutput` only.
+3. Use discriminated unions for UI output types.
+4. Co-locate domain state (example: card + flipped + rating in one structure).
+5. Use helper functions for repeated state ops.
+6. Split long flows into focused steps (`fetch`, `decide`, `view`, `commit`).
+
+## Important runtime behavior
+
+1. A step is treated as action step when it has `action` and does not have `view`.
+2. Action step runs automatically when it becomes current.
+3. `FlowRunner` normalizes channels before subscribing:
+   - `"sticky"` (default): keeps first-seen channel instance per key.
+   - `"replace"`: uses the latest incoming channel instances.
+4. Channel emissions trigger re-render for subscribed runners.
+5. If `channelTransitions[channelKey]` exists, channel `emit` runs that resolver and transitions when a valid step is returned.
+6. Errors in `onOutput`, action steps, or channel transition resolvers are logged (`console.error`) and not rethrown.
+7. Returning unknown step or `void` does not change current step.
+8. `initialData` is shallow-copied at runner initialization.
+
+## Pitfalls to avoid
+
+1. Creating channel instances directly in render can reset channel value if keys change or if using `"replace"` strategy.
+2. Rebuilding `eventChannels` object each render is safe; `FlowRunner` deduplicates equivalent maps internally.
+3. Using `output.done(...)` instead of `output.emit(...)`.
+4. Mixing `view` and `action` in the same step.
+5. Returning transition targets that do not exist.
+6. Using static values in `channelTransitions`; each channel entry must be a resolver function.
+
+## Next.js notes
+
+- `FlowRunner` and UI step views should be in client components.
+- Add `"use client"` at the top where needed.
+- Server actions can be called inside action steps.
+
+## FAQ
+
+### Why not just `useState` + `useEffect`?
 
-### 2) Where the flow is defined
+You can for simple screens. UIFlow is useful when screens become multi-step and transitions/side-effects spread across components.
 
-#### `defineFlow<D>(steps: FlowSteps<D>, options: DefineFlowOptions): FlowDefinition<D>`
-Creates a flow definition from a steps map and a required `start` step name.
+### Is flow data immutable?
 
-- `DefineFlowOptions.start: string` — name of the first step.
+No. Flow data is mutable by design inside step handlers.
 
-#### `createFlowChannel<T>(initial: T): FlowChannel<T>`
-Creates a shared channel for cross‑flow communication.
+### Can I have multiple flows on one page?
 
-- `FlowChannel.get(): T` — read the current value.
-- `FlowChannel.emit(update: T | (prev: T) => T): void` — update value and notify subscribers.
-- `FlowChannel.subscribe(listener: () => void): () => void` — listen for changes.
+Yes. Use channels when they need to communicate.
 
+## Complete checklist before shipping
 
-### 3) A UI component
+1. `start` exists and all transitions target valid step keys.
+2. UI outputs are typed unions.
+3. Views only emit intent.
+4. Async work is in action steps.
+5. Channels are stable and reused.
+6. No internal-path imports.
 
-#### `OutputHandle<O>`
-Used by UI steps to emit output back into the flow.
+## License
 
-- `OutputHandle.emit(output: O): void`
+MIT

package/dist/flow.d.ts

@@ -12,9 +12,16 @@ export declare function createFlowChannel<T>(initial: T): FlowChannel<T>;
  * You can refine this to a generic later, e.g. <D>.
  */
 export type FlowData = Record<string, any>;
+export interface ChannelTransitionContext<D extends FlowData = FlowData> {
+    data: D;
+    currentStep: string;
+    events?: EventChannels;
+    channelKey: string;
+}
+export type ChannelTransitionResolver<D extends FlowData = FlowData> = (context: ChannelTransitionContext<D>) => string | void | Promise<string | void>;
 /**
  * Output handle given to UI components.
- * They call output.done(...) when they're finished.
+ * They call output.emit(...) when they're finished.
  */
 export interface OutputHandle<O = any> {
     emit: (output: O) => void;
@@ -23,7 +30,7 @@ export interface OutputHandle<O = any> {
  * UI step:
  * - Prepares `input` from `data`
  * - Renders `view`
- * - Receives `output` from the component via output.done()
+ * - Receives `output` from the component via output.emit()
  * - `onOutput` decides next step and can mutate data
  */
 export interface UiStep<D extends FlowData = FlowData, I = any, O = any> {
@@ -63,21 +70,34 @@ export type FlowSteps<D extends FlowData = FlowData> = Record<string, FlowStep<D
 export interface FlowDefinition<D extends FlowData = FlowData> {
     steps: FlowSteps<D>;
     start: string;
+    channelTransitions?: Record<string, ChannelTransitionResolver<D>>;
 }
 /**
  * Options when defining a flow.
  */
-export interface DefineFlowOptions {
+export interface DefineFlowOptions<D extends FlowData = FlowData> {
     start: string;
+    /**
+     * Optional channel transition mapping.
+     * Each channel key maps to a resolver function with conditional logic
+     * that returns target step name (or void to stay).
+     */
+    channelTransitions?: Record<string, ChannelTransitionResolver<D>>;
 }
 /**
  * Main entry point to define a flow.
  */
-export declare function defineFlow<D extends FlowData = FlowData>(steps: FlowSteps<D>, options: DefineFlowOptions): FlowDefinition<D>;
+export declare function defineFlow<D extends FlowData = FlowData>(steps: FlowSteps<D>, options: DefineFlowOptions<D>): FlowDefinition<D>;
 export interface FlowRunnerProps<D extends FlowData = FlowData> {
     flow: FlowDefinition<D>;
     initialData: D;
     eventChannels?: EventChannels;
+    /**
+     * How FlowRunner treats incoming eventChannels across parent re-renders.
+     * - "sticky" (default): keep first-seen channel instance per key; ignore replacements for existing keys.
+     * - "replace": accept incoming channels as source of truth.
+     */
+    eventChannelsStrategy?: "sticky" | "replace";
 }
 /**
  * FlowRunner:

package/dist/flow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flow.d.ts","sourceRoot":"","sources":["../src/flow.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"flow.d.ts","sourceRoot":"","sources":["../src/flow.tsx"],"names":[],"mappings":"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"}

package/dist/flow.js

@@ -30,6 +30,7 @@ export function defineFlow(steps, options) {
     return {
         steps,
         start: options.start,
+        channelTransitions: options.channelTransitions,
     };
 }
 /**
@@ -39,10 +40,38 @@ export function defineFlow(steps, options) {
  * - renders UI steps
  */
 export function FlowRunner(props) {
-    const eventChannelsRef = useRef(undefined);
-    eventChannelsRef.current ?? (eventChannelsRef.current = props.eventChannels);
-    const eventChannels = eventChannelsRef.current;
-    const { flow, initialData } = props;
+    const { flow, initialData, eventChannels, eventChannelsStrategy = "sticky", } = props;
+    const resolvedChannelsRef = useRef(undefined);
+    const getResolvedChannels = () => {
+        const prev = resolvedChannelsRef.current;
+        const incoming = eventChannels;
+        if (!incoming) {
+            resolvedChannelsRef.current = undefined;
+            return undefined;
+        }
+        const incomingEntries = Object.entries(incoming);
+        let candidate;
+        if (eventChannelsStrategy === "sticky") {
+            candidate = {};
+            for (const [key, channel] of incomingEntries) {
+                candidate[key] = prev?.[key] ?? channel;
+            }
+        }
+        else {
+            candidate = incoming;
+        }
+        if (prev) {
+            const prevKeys = Object.keys(prev);
+            const candidateKeys = Object.keys(candidate);
+            if (prevKeys.length === candidateKeys.length &&
+                candidateKeys.every((k) => prev[k] === candidate[k])) {
+                return prev;
+            }
+        }
+        resolvedChannelsRef.current = candidate;
+        return candidate;
+    };
+    const resolvedEventChannels = getResolvedChannels();
     // We keep data and currentStep in state so React re-renders on change.
     const [state, setState] = useState({
         currentStep: flow.start,
@@ -54,15 +83,6 @@ export function FlowRunner(props) {
     // This state is never used directly.
     // It only exists to force a re-render when event channels change.
     const [_tick, setTick] = useState(0);
-    // NEW:
-    // Subscribe to every provided channel.
-    // When any channel emits, we trigger a re-render of this FlowRunner.
-    useEffect(() => {
-        if (!eventChannels)
-            return;
-        const unsubs = Object.values(eventChannels).map((ch) => ch.subscribe(() => setTick((x) => x + 1)));
-        return () => unsubs.forEach((u) => u());
-    }, []);
     const { currentStep, data } = state;
     const applyTransition = (nextStepName) => {
         if (!isMountedRef.current)
@@ -82,6 +102,43 @@ export function FlowRunner(props) {
             }));
         }
     };
+    const runChannelTransition = async (channelKey) => {
+        const transition = flow.channelTransitions?.[channelKey];
+        if (!transition) {
+            setTick((x) => x + 1);
+            return;
+        }
+        try {
+            const nextStep = await transition({
+                data,
+                currentStep,
+                events: resolvedEventChannels,
+                channelKey,
+            });
+            if (nextStep) {
+                applyTransition(nextStep);
+                return;
+            }
+            setTick((x) => x + 1);
+        }
+        catch (e) {
+            console.error("FlowRunner channel transition error:", e);
+            setTick((x) => x + 1);
+        }
+    };
+    // Subscribe to every provided channel and keep subscriptions in sync
+    // with the current eventChannels prop.
+    useEffect(() => {
+        if (!resolvedEventChannels)
+            return;
+        const unsubs = Object.entries(resolvedEventChannels).map(([channelKey, ch]) => ch.subscribe(() => {
+            void runChannelTransition(channelKey);
+        }));
+        return () => unsubs.forEach((u) => u());
+        // applyTransition and runChannelTransition are recreated each render;
+        // subscription identity is driven by channels map.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [flow.channelTransitions, resolvedEventChannels]);
     useEffect(() => {
         return () => {
             isMountedRef.current = false;
@@ -97,9 +154,9 @@ export function FlowRunner(props) {
         (async () => {
             try {
                 setBusy(true);
-                const input = actionStep.input(state.data, eventChannels);
-                const output = await actionStep.action(input, state.data, eventChannels);
-                const next = await actionStep.onOutput(state.data, output, eventChannels);
+                const input = actionStep.input(state.data, resolvedEventChannels);
+                const output = await actionStep.action(input, state.data, resolvedEventChannels);
+                const next = await actionStep.onOutput(state.data, output, resolvedEventChannels);
                 applyTransition(next);
             }
             catch (e) {
@@ -132,11 +189,11 @@ export function FlowRunner(props) {
     // -----------------------
     const uiStep = step;
     const ViewComponent = uiStep.view;
-    const input = uiStep.input(data, eventChannels);
+    const input = uiStep.input(data, resolvedEventChannels);
     const outputHandle = {
         emit: async (output) => {
             try {
-                const next = await uiStep.onOutput(data, output, eventChannels);
+                const next = await uiStep.onOutput(data, output, resolvedEventChannels);
                 applyTransition(next);
             }
             catch (e) {

package/dist/flow.js.map

@@ -1 +1 @@
-{"version":3,"file":"flow.js","sourceRoot":"","sources":["../src/flow.tsx"],"names":[],"mappings":";AAAA,uDAAuD;AACvD,gDAAgD;AAEhD,eAAe;AACf,OAAO,KAAK,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AA0B3D,wCAAwC;AACxC,6EAA6E;AAC7E,MAAM,UAAU,iBAAiB,CAAI,OAAU;IAC3C,IAAI,KAAK,GAAG,OAAO,CAAC;IACpB,MAAM,SAAS,GAAG,IAAI,GAAG,EAAc,CAAC;IAExC,OAAO;QACH,GAAG,EAAE,GAAG,EAAE,CAAC,KAAK;QAEhB,IAAI,EAAE,CAAC,MAAkB,EAAE,EAAE;YACzB,KAAK,GAAG,OAAO,MAAM,KAAK,UAAU,CAAC,CAAC,CAAE,MAAsB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;YAC/E,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,yBAAyB;QAC5D,CAAC;QAED,SAAS,EAAE,CAAC,QAAoB,EAAE,EAAE;YAChC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YACxB,OAAO,GAAG,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC5C,CAAC;KACJ,CAAC;AACN,CAAC;AA+ED;;GAEG;AACH,MAAM,UAAU,UAAU,CACtB,KAAmB,EACnB,OAA0B;IAE1B,IAAI,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CACX,iEAAiE,OAAO,CAAC,KAAK,IAAI,CACrF,CAAC;IACN,CAAC;IACD,OAAO;QACH,KAAK;QACL,KAAK,EAAE,OAAO,CAAC,KAAK;KACvB,CAAC;AACN,CAAC;AA8BD;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CACtB,KAAmC;IAGnC,MAAM,gBAAgB,GAAG,MAAM,CAA4B,SAAS,CAAC,CAAC;IAEtE,gBAAgB,CAAC,OAAO,KAAxB,gBAAgB,CAAC,OAAO,GAAK,KAAK,CAAC,aAAa,EAAC;IAEjD,MAAM,aAAa,GAAG,gBAAgB,CAAC,OAAO,CAAC;IAG/C,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,KAAK,CAAC;IAEpC,uEAAuE;IACvE,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAiB;QAC/C,WAAW,EAAE,IAAI,CAAC,KAAK;QACvB,IAAI,EAAE,EAAE,GAAG,WAAW,EAAE;KAC3B,CAAC,CAAC;IAEH,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,mBAAmB;IAC5D,MAAM,YAAY,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IAElC,OAAO;IACP,qCAAqC;IACrC,kEAAkE;IAClE,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;IAErC,OAAO;IACP,uCAAuC;IACvC,qEAAqE;IACrE,SAAS,CAAC,GAAG,EAAE;QACX,IAAI,CAAC,aAAa;YAAE,OAAO;QAE3B,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CACnD,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAC5C,CAAC;QAEF,OAAO,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;IAC5C,CAAC,EAAE,EAAE,CAAC,CAAC;IAGP,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,GAAG,KAAK,CAAC;IAEpC,MAAM,eAAe,GAAG,CAAC,YAA4B,EAAE,EAAE;QACrD,IAAI,CAAC,YAAY,CAAC,OAAO;YAAE,OAAO;QAElC,IAAI,YAAY,IAAI,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,EAAE,CAAC;YAC3C,QAAQ,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;gBAChB,GAAG,IAAI;gBACP,WAAW,EAAE,YAAY;gBACzB,IAAI,EAAE,EAAE,GAAG,IAAI,CAAC,IAAI,EAAE,EAAE,qDAAqD;aAChF,CAAC,CAAC,CAAC;QACR,CAAC;aAAM,CAAC;YACJ,wDAAwD;YACxD,QAAQ,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;gBAChB,GAAG,IAAI;gBACP,IAAI,EAAE,EAAE,GAAG,IAAI,CAAC,IAAI,EAAE;aACzB,CAAC,CAAC,CAAC;QACR,CAAC;IACL,CAAC,CAAC;IAEF,SAAS,CAAC,GAAG,EAAE;QACX,OAAO,GAAG,EAAE;YACR,YAAY,CAAC,OAAO,GAAG,KAAK,CAAC;QACjC,CAAC,CAAC;IACN,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IAErC,2DAA2D;IAC3D,MAAM,YAAY,GAAI,IAAY,CAAC,MAAM,IAAI,CAAE,IAAY,CAAC,IAAI,CAAC;IAEjE,SAAS,CAAC,GAAG,EAAE;QACX,IAAI,CAAC,YAAY;YAAE,OAAO;QAE1B,MAAM,UAAU,GAAG,IAA+B,CAAC;QAEnD,CAAC,KAAK,IAAI,EAAE;YACR,IAAI,CAAC;gBACD,OAAO,CAAC,IAAI,CAAC,CAAC;gBACd,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;gBAC1D,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;gBACzE,MAAM,IAAI,GAAG,MAAM,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,aAAa,CAAC,CAAC;gBAC1E,eAAe,CAAC,IAAI,CAAC,CAAC;YAC1B,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACT,OAAO,CAAC,KAAK,CAAC,+BAA+B,EAAE,CAAC,CAAC,CAAC;gBAClD,qEAAqE;YACzE,CAAC;oBAAS,CAAC;gBACP,IAAI,YAAY,CAAC,OAAO;oBAAE,OAAO,CAAC,KAAK,CAAC,CAAC;YAC7C,CAAC;QACL,CAAC,CAAC,EAAE,CAAC;QACL,6EAA6E;QAC7E,uDAAuD;IAC3D,CAAC,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC;IAIlB,IAAI,CAAC,IAAI,EAAE,CAAC;QACR,uCAAuC;QACvC,OAAO,CACH,0BACI,iDAAkC,sBAAgB,WAAW,WAC3D,CACT,CAAC;IACN,CAAC;IAED,wEAAwE;IAExE,0BAA0B;IAC1B,uBAAuB;IACvB,0BAA0B;IAI1B,gEAAgE;IAChE,IAAI,YAAY,EAAE,CAAC;QACf,kDAAkD;QAClD,OAAO,wBAAM,IAAI,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,IAAI,GAAO,CAAC;IACtD,CAAC;IAED,0BAA0B;IAC1B,mBAAmB;IACnB,0BAA0B;IAE1B,MAAM,MAAM,GAAG,IAA2B,CAAC;IAC3C,MAAM,aAAa,GAAG,MAAM,CAAC,IAAI,CAAC;IAClC,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;IAEhD,MAAM,YAAY,GAAsB;QACpC,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE;YACnB,IAAI,CAAC;gBACD,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,aAAa,CAAC,CAAC;gBAChE,eAAe,CAAC,IAAI,CAAC,CAAC;YAC1B,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACT,OAAO,CAAC,KAAK,CAAC,oCAAoC,EAAE,CAAC,CAAC,CAAC;YAC3D,CAAC;QACL,CAAC;KACJ,CAAC;IAEF,OAAO,KAAC,aAAa,IAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,GAAI,CAAC;AACjE,CAAC"}
+{"version":3,"file":"flow.js","sourceRoot":"","sources":["../src/flow.tsx"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myriadcodelabs/uiflow",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Explicit, code-first UI flow orchestration for React.",
   "keywords": [],
   "author": "Muhammad Ismail Khan",
@@ -9,8 +9,16 @@
     "react": ">=18"
   },
   "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
     "@types/react": "^19.2.10",
-    "typescript": "^5.9.3"
+    "@types/react-dom": "^19.2.3",
+    "jsdom": "^28.0.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
   },
   "type": "module",
   "files": [
@@ -25,7 +33,8 @@
     }
   },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "clean": "rimraf dist",
     "build": "pnpm run clean && tsc"
   }