@secmia/openui-flow 4.0.0 → 4.1.0

package/AGENTS.md

@@ -35,9 +35,12 @@ Core evaluation APIs:
 Primary component and types:
 
 - AdaptiveFlow
+- useAdaptiveFlow
 - AdaptiveFlowProps
 - AdaptiveFlowAdapter
 - AdaptiveFlowValidators
+- AdaptiveFlowSchemas
+- AdaptiveFlowFieldErrors
 - AdaptiveFlowPersistence
 - AdaptiveFlowStyles
 - AdaptiveFlowClassNames
@@ -117,6 +120,8 @@ Validation:
 - Configure via validators prop
 - Supports email, otp, password, profile, tos validators
 - Validators may be sync or async
+- Validators can return string or { field, message } for field-level error mapping
+- Optional schemas prop supports schema objects with safeParse/parse (Zod-friendly)
 
 ## Recommended Agent Workflow
 

package/README.md

@@ -489,7 +489,97 @@ Use `renderStep` for full step-body ownership. You can still reuse `defaultView`
 
 ### Level 4: fully custom UI for everything (headless mode)
 
-If you want total control over shell, header, footer, button layout, and every interaction, use engine APIs directly.
+If you want total control over shell, header, footer, button layout, and every interaction, use `useAdaptiveFlow` (or engine APIs directly).
+
+### Headless hook (`useAdaptiveFlow`)
+
+`useAdaptiveFlow` exposes the flow lifecycle without rendering any UI.
+
+```tsx
+'use client';
+
+import { useAdaptiveFlow, type AdaptiveContextBase } from '@secmia/openui-flow';
+
+type Ctx = AdaptiveContextBase & {
+  selectedPlan: 'starter' | 'pro' | null;
+};
+
+export default function FullyCustomFlow() {
+  const {
+    step,
+    context,
+    missingRequirements,
+    busy,
+    fieldErrors,
+    handleEmail,
+    handleOtp,
+    handlePassword,
+    handleProfile,
+    handleTos,
+    setContextPatch,
+  } = useAdaptiveFlow<Ctx>({
+    requirements: ['has_email', 'email_verified', 'has_password', 'has_first_name', 'accepted_tos', 'selected_plan'],
+    completeStep: 'COMPLETE',
+    initialValue: { selectedPlan: null },
+  });
+
+  return (
+    <div>
+      <h2>Step: {step}</h2>
+      <p>Pending: {missingRequirements.length}</p>
+      {fieldErrors.email ? <p>{fieldErrors.email}</p> : null}
+
+      <button disabled={busy} onClick={() => handleEmail('user@company.com')}>Submit Email</button>
+      <button disabled={busy} onClick={() => handleOtp('123456')}>Submit OTP</button>
+      <button disabled={busy} onClick={() => handlePassword('secure-password')}>Submit Password</button>
+      <button disabled={busy} onClick={() => handleProfile({ firstName: 'A', lastName: 'B', jobTitle: null })}>Save Profile</button>
+      <button disabled={busy} onClick={() => handleTos()}>Accept TOS</button>
+      <button onClick={() => setContextPatch({ selectedPlan: 'pro' })}>Select Plan</button>
+      <pre>{JSON.stringify(context, null, 2)}</pre>
+    </div>
+  );
+}
+```
+
+You can still bypass the hook and use pure engine APIs if you need lower-level control.
+
+### Optional schema validation (Zod-friendly)
+
+`AdaptiveFlow` and `useAdaptiveFlow` accept a `schemas` object. Any schema with `safeParse` or `parse` is supported (including Zod schemas).
+
+```tsx
+import { z } from 'zod';
+
+const emailSchema = z.string().email();
+const profileSchema = z.object({
+  firstName: z.string().min(1),
+  lastName: z.string().min(1),
+  jobTitle: z.string().nullable(),
+});
+
+<AdaptiveFlow
+  schemas={{
+    email: emailSchema,
+    profile: profileSchema,
+  }}
+/>
+```
+
+### Field-level validation errors
+
+Validators can return either a string or `{ field, message }`.
+
+```ts
+const validators = {
+  password: (value: string) => {
+    if (value.length < 12) {
+      return { field: 'password', message: 'Password must be at least 12 characters.' };
+    }
+  },
+};
+```
+
+Default UI now binds field errors to the matching input and sets `aria-invalid` automatically.
 
 ```tsx
 'use client';
@@ -749,6 +839,7 @@ Evaluation loop:
 
 Primary exports:
 - `AdaptiveFlow`
+- `useAdaptiveFlow`
 - `defaultRequirements`
 - `initialContext`
 - `defaultRequirementResolvers`
@@ -762,7 +853,14 @@ Primary exports:
 Important types:
 - `AdaptiveFlowProps`
 - `AdaptiveFlowAdapter`
+- `UseAdaptiveFlowOptions`
+- `UseAdaptiveFlowResult`
 - `AdaptiveFlowValidators`
+- `AdaptiveFlowValidationResult`
+- `AdaptiveFlowValidationIssue`
+- `AdaptiveFlowFieldErrors`
+- `AdaptiveFlowSchemas`
+- `AdaptiveFlowSchema`
 - `AdaptiveFlowPersistence`
 - `AdaptiveStepRegistry`
 - `AdaptiveStepRendererArgs`

package/dist/index.d.mts

@@ -103,16 +103,42 @@ type PersistedAdaptiveFlowState<TContext extends AdaptiveContextBase = AdaptiveC
 type AdaptiveFlowValidationContext<TContext extends AdaptiveContextBase = AdaptiveContextBase> = {
     context: TContext;
 };
+type AdaptiveFlowValidationIssue = {
+    message: string;
+    field?: string;
+};
+type AdaptiveFlowValidationResult = string | AdaptiveFlowValidationIssue | void | Promise<string | AdaptiveFlowValidationIssue | void>;
+type AdaptiveFlowSchema<TValue> = {
+    safeParse?: (value: TValue) => {
+        success: boolean;
+        error?: {
+            message?: string;
+            issues?: Array<{
+                message?: string;
+                path?: Array<string | number>;
+            }>;
+        };
+    };
+    parse?: (value: TValue) => unknown;
+};
+type AdaptiveFlowSchemas = {
+    email?: AdaptiveFlowSchema<string>;
+    otp?: AdaptiveFlowSchema<string>;
+    password?: AdaptiveFlowSchema<string>;
+    profile?: AdaptiveFlowSchema<AdaptiveContextBase["profile"]>;
+    tos?: AdaptiveFlowSchema<boolean>;
+};
+type AdaptiveFlowFieldErrors = Partial<Record<string, string>>;
 type AdaptiveFlowValidators<TContext extends AdaptiveContextBase = AdaptiveContextBase> = {
-    email?: (input: string, payload: AdaptiveFlowValidationContext<TContext>) => string | void | Promise<string | void>;
+    email?: (input: string, payload: AdaptiveFlowValidationContext<TContext>) => AdaptiveFlowValidationResult;
     otp?: (input: string, payload: AdaptiveFlowValidationContext<TContext> & {
         email: string;
-    }) => string | void | Promise<string | void>;
+    }) => AdaptiveFlowValidationResult;
     password?: (input: string, payload: AdaptiveFlowValidationContext<TContext> & {
         hasPassword: boolean;
-    }) => string | void | Promise<string | void>;
-    profile?: (input: AdaptiveContextBase["profile"], payload: AdaptiveFlowValidationContext<TContext>) => string | void | Promise<string | void>;
-    tos?: (accepted: boolean, payload: AdaptiveFlowValidationContext<TContext>) => string | void | Promise<string | void>;
+    }) => AdaptiveFlowValidationResult;
+    profile?: (input: AdaptiveContextBase["profile"], payload: AdaptiveFlowValidationContext<TContext>) => AdaptiveFlowValidationResult;
+    tos?: (accepted: boolean, payload: AdaptiveFlowValidationContext<TContext>) => AdaptiveFlowValidationResult;
 };
 type AdaptiveStepTransition<TStep extends string = AdaptiveStep> = {
     from: TStep | null;
@@ -126,6 +152,7 @@ type AdaptiveStepRendererArgs<TContext extends AdaptiveContextBase, TRequirement
     busy: boolean;
     message: string | null;
     errorMessage: string | null;
+    fieldErrors: AdaptiveFlowFieldErrors;
     missingRequirements: TRequirement[];
     requirements: readonly TRequirement[];
     setContextPatch: (patch: Partial<TContext>) => void;
@@ -140,6 +167,7 @@ type AdaptiveStepRenderArgs<TContext extends AdaptiveContextBase = AdaptiveConte
     busy: boolean;
     message: string | null;
     errorMessage: string | null;
+    fieldErrors: AdaptiveFlowFieldErrors;
     missingRequirements: TRequirement[];
     requirements: readonly TRequirement[];
     defaultView: React.ReactNode;
@@ -172,7 +200,30 @@ type AdaptiveFlowProps<TContext extends AdaptiveContextBase = AdaptiveContext, T
     unstyled?: boolean;
     persistence?: AdaptiveFlowPersistence<TContext>;
     validators?: AdaptiveFlowValidators<TContext>;
+    schemas?: AdaptiveFlowSchemas;
+};
+type UseAdaptiveFlowOptions<TContext extends AdaptiveContextBase = AdaptiveContext, TRequirement extends string = AppRequirement, TStep extends string = AdaptiveStep> = Omit<AdaptiveFlowProps<TContext, TRequirement, TStep>, "stepTitles" | "renderStep" | "stepRegistry" | "className" | "classNames" | "styles" | "unstyled">;
+type UseAdaptiveFlowResult<TContext extends AdaptiveContextBase, TRequirement extends string, TStep extends string> = {
+    context: TContext;
+    step: TStep;
+    completeStep: TStep;
+    requirements: readonly TRequirement[];
+    missingRequirements: TRequirement[];
+    transitions: AdaptiveStepTransition<TStep>[];
+    busy: boolean;
+    message: string | null;
+    errorMessage: string | null;
+    fieldErrors: AdaptiveFlowFieldErrors;
+    setContextPatch: (patch: Partial<TContext>) => void;
+    run: (job: () => Promise<void>) => Promise<void>;
+    handleEmail: (emailInput: string) => void;
+    handleOtp: (code: string) => void;
+    handlePassword: (password: string) => void;
+    handleProfile: (profile: AdaptiveContextBase["profile"]) => void;
+    handleTos: () => void;
+    handleOAuth: (provider: OAuthProvider) => void;
 };
-declare function AdaptiveFlow<TContext extends AdaptiveContextBase = AdaptiveContext, TRequirement extends string = AppRequirement, TStep extends string = AdaptiveStep>({ adapter, requirements, requirementGraph, requirementGraphConfig, requirementResolvers, completeStep, stepTitles, renderStep, stepRegistry, initialValue, onComplete, onError, onStepTransition, className, classNames, styles, unstyled, persistence, validators, }: AdaptiveFlowProps<TContext, TRequirement, TStep>): react_jsx_runtime.JSX.Element;
+declare function useAdaptiveFlow<TContext extends AdaptiveContextBase = AdaptiveContext, TRequirement extends string = AppRequirement, TStep extends string = AdaptiveStep>({ adapter, requirements, requirementGraph, requirementGraphConfig, requirementResolvers, completeStep, initialValue, onComplete, onError, onStepTransition, persistence, validators, schemas, }: UseAdaptiveFlowOptions<TContext, TRequirement, TStep>): UseAdaptiveFlowResult<TContext, TRequirement, TStep>;
+declare function AdaptiveFlow<TContext extends AdaptiveContextBase = AdaptiveContext, TRequirement extends string = AppRequirement, TStep extends string = AdaptiveStep>({ adapter, requirements, requirementGraph, requirementGraphConfig, requirementResolvers, completeStep, stepTitles, renderStep, stepRegistry, initialValue, onComplete, onError, onStepTransition, className, classNames, styles, unstyled, persistence, validators, schemas, }: AdaptiveFlowProps<TContext, TRequirement, TStep>): react_jsx_runtime.JSX.Element;
 
-export { type AdaptiveContext, type AdaptiveContextBase, AdaptiveFlow, type AdaptiveFlowAdapter, type AdaptiveFlowClassNames, type AdaptiveFlowPersistence, type AdaptiveFlowProps, type AdaptiveFlowStorageDriver, type AdaptiveFlowStyleSlot, type AdaptiveFlowStyles, type AdaptiveFlowValidationContext, type AdaptiveFlowValidators, type AdaptiveStep, type AdaptiveStepRegistry, type AdaptiveStepRenderArgs, type AdaptiveStepRendererArgs, type AdaptiveStepTransition, type AppRequirement, type DefaultAdaptiveStep, DefaultAdaptiveSteps, type DefaultAppRequirement, DefaultAppRequirements, type IdentityResolution, type MaybePromise, type OAuthProvider, type PersistedAdaptiveFlowState, type RequirementGraph, type RequirementGraphNode, type RequirementResolver, createDefaultRequirementGraph, createRequirementGraph, defaultRequirementResolvers, defaultRequirements, evaluateNextStep, getMissingRequirements, initialContext };
+export { type AdaptiveContext, type AdaptiveContextBase, AdaptiveFlow, type AdaptiveFlowAdapter, type AdaptiveFlowClassNames, type AdaptiveFlowFieldErrors, type AdaptiveFlowPersistence, type AdaptiveFlowProps, type AdaptiveFlowSchema, type AdaptiveFlowSchemas, type AdaptiveFlowStorageDriver, type AdaptiveFlowStyleSlot, type AdaptiveFlowStyles, type AdaptiveFlowValidationContext, type AdaptiveFlowValidationIssue, type AdaptiveFlowValidationResult, type AdaptiveFlowValidators, type AdaptiveStep, type AdaptiveStepRegistry, type AdaptiveStepRenderArgs, type AdaptiveStepRendererArgs, type AdaptiveStepTransition, type AppRequirement, type DefaultAdaptiveStep, DefaultAdaptiveSteps, type DefaultAppRequirement, DefaultAppRequirements, type IdentityResolution, type MaybePromise, type OAuthProvider, type PersistedAdaptiveFlowState, type RequirementGraph, type RequirementGraphNode, type RequirementResolver, type UseAdaptiveFlowOptions, type UseAdaptiveFlowResult, createDefaultRequirementGraph, createRequirementGraph, defaultRequirementResolvers, defaultRequirements, evaluateNextStep, getMissingRequirements, initialContext, useAdaptiveFlow };

package/dist/index.d.ts

@@ -103,16 +103,42 @@ type PersistedAdaptiveFlowState<TContext extends AdaptiveContextBase = AdaptiveC
 type AdaptiveFlowValidationContext<TContext extends AdaptiveContextBase = AdaptiveContextBase> = {
     context: TContext;
 };
+type AdaptiveFlowValidationIssue = {
+    message: string;
+    field?: string;
+};
+type AdaptiveFlowValidationResult = string | AdaptiveFlowValidationIssue | void | Promise<string | AdaptiveFlowValidationIssue | void>;
+type AdaptiveFlowSchema<TValue> = {
+    safeParse?: (value: TValue) => {
+        success: boolean;
+        error?: {
+            message?: string;
+            issues?: Array<{
+                message?: string;
+                path?: Array<string | number>;
+            }>;
+        };
+    };
+    parse?: (value: TValue) => unknown;
+};
+type AdaptiveFlowSchemas = {
+    email?: AdaptiveFlowSchema<string>;
+    otp?: AdaptiveFlowSchema<string>;
+    password?: AdaptiveFlowSchema<string>;
+    profile?: AdaptiveFlowSchema<AdaptiveContextBase["profile"]>;
+    tos?: AdaptiveFlowSchema<boolean>;
+};
+type AdaptiveFlowFieldErrors = Partial<Record<string, string>>;
 type AdaptiveFlowValidators<TContext extends AdaptiveContextBase = AdaptiveContextBase> = {
-    email?: (input: string, payload: AdaptiveFlowValidationContext<TContext>) => string | void | Promise<string | void>;
+    email?: (input: string, payload: AdaptiveFlowValidationContext<TContext>) => AdaptiveFlowValidationResult;
     otp?: (input: string, payload: AdaptiveFlowValidationContext<TContext> & {
         email: string;
-    }) => string | void | Promise<string | void>;
+    }) => AdaptiveFlowValidationResult;
     password?: (input: string, payload: AdaptiveFlowValidationContext<TContext> & {
         hasPassword: boolean;
-    }) => string | void | Promise<string | void>;
-    profile?: (input: AdaptiveContextBase["profile"], payload: AdaptiveFlowValidationContext<TContext>) => string | void | Promise<string | void>;
-    tos?: (accepted: boolean, payload: AdaptiveFlowValidationContext<TContext>) => string | void | Promise<string | void>;
+    }) => AdaptiveFlowValidationResult;
+    profile?: (input: AdaptiveContextBase["profile"], payload: AdaptiveFlowValidationContext<TContext>) => AdaptiveFlowValidationResult;
+    tos?: (accepted: boolean, payload: AdaptiveFlowValidationContext<TContext>) => AdaptiveFlowValidationResult;
 };
 type AdaptiveStepTransition<TStep extends string = AdaptiveStep> = {
     from: TStep | null;
@@ -126,6 +152,7 @@ type AdaptiveStepRendererArgs<TContext extends AdaptiveContextBase, TRequirement
     busy: boolean;
     message: string | null;
     errorMessage: string | null;
+    fieldErrors: AdaptiveFlowFieldErrors;
     missingRequirements: TRequirement[];
     requirements: readonly TRequirement[];
     setContextPatch: (patch: Partial<TContext>) => void;
@@ -140,6 +167,7 @@ type AdaptiveStepRenderArgs<TContext extends AdaptiveContextBase = AdaptiveConte
     busy: boolean;
     message: string | null;
     errorMessage: string | null;
+    fieldErrors: AdaptiveFlowFieldErrors;
     missingRequirements: TRequirement[];
     requirements: readonly TRequirement[];
     defaultView: React.ReactNode;
@@ -172,7 +200,30 @@ type AdaptiveFlowProps<TContext extends AdaptiveContextBase = AdaptiveContext, T
     unstyled?: boolean;
     persistence?: AdaptiveFlowPersistence<TContext>;
     validators?: AdaptiveFlowValidators<TContext>;
+    schemas?: AdaptiveFlowSchemas;
+};
+type UseAdaptiveFlowOptions<TContext extends AdaptiveContextBase = AdaptiveContext, TRequirement extends string = AppRequirement, TStep extends string = AdaptiveStep> = Omit<AdaptiveFlowProps<TContext, TRequirement, TStep>, "stepTitles" | "renderStep" | "stepRegistry" | "className" | "classNames" | "styles" | "unstyled">;
+type UseAdaptiveFlowResult<TContext extends AdaptiveContextBase, TRequirement extends string, TStep extends string> = {
+    context: TContext;
+    step: TStep;
+    completeStep: TStep;
+    requirements: readonly TRequirement[];
+    missingRequirements: TRequirement[];
+    transitions: AdaptiveStepTransition<TStep>[];
+    busy: boolean;
+    message: string | null;
+    errorMessage: string | null;
+    fieldErrors: AdaptiveFlowFieldErrors;
+    setContextPatch: (patch: Partial<TContext>) => void;
+    run: (job: () => Promise<void>) => Promise<void>;
+    handleEmail: (emailInput: string) => void;
+    handleOtp: (code: string) => void;
+    handlePassword: (password: string) => void;
+    handleProfile: (profile: AdaptiveContextBase["profile"]) => void;
+    handleTos: () => void;
+    handleOAuth: (provider: OAuthProvider) => void;
 };
-declare function AdaptiveFlow<TContext extends AdaptiveContextBase = AdaptiveContext, TRequirement extends string = AppRequirement, TStep extends string = AdaptiveStep>({ adapter, requirements, requirementGraph, requirementGraphConfig, requirementResolvers, completeStep, stepTitles, renderStep, stepRegistry, initialValue, onComplete, onError, onStepTransition, className, classNames, styles, unstyled, persistence, validators, }: AdaptiveFlowProps<TContext, TRequirement, TStep>): react_jsx_runtime.JSX.Element;
+declare function useAdaptiveFlow<TContext extends AdaptiveContextBase = AdaptiveContext, TRequirement extends string = AppRequirement, TStep extends string = AdaptiveStep>({ adapter, requirements, requirementGraph, requirementGraphConfig, requirementResolvers, completeStep, initialValue, onComplete, onError, onStepTransition, persistence, validators, schemas, }: UseAdaptiveFlowOptions<TContext, TRequirement, TStep>): UseAdaptiveFlowResult<TContext, TRequirement, TStep>;
+declare function AdaptiveFlow<TContext extends AdaptiveContextBase = AdaptiveContext, TRequirement extends string = AppRequirement, TStep extends string = AdaptiveStep>({ adapter, requirements, requirementGraph, requirementGraphConfig, requirementResolvers, completeStep, stepTitles, renderStep, stepRegistry, initialValue, onComplete, onError, onStepTransition, className, classNames, styles, unstyled, persistence, validators, schemas, }: AdaptiveFlowProps<TContext, TRequirement, TStep>): react_jsx_runtime.JSX.Element;
 
-export { type AdaptiveContext, type AdaptiveContextBase, AdaptiveFlow, type AdaptiveFlowAdapter, type AdaptiveFlowClassNames, type AdaptiveFlowPersistence, type AdaptiveFlowProps, type AdaptiveFlowStorageDriver, type AdaptiveFlowStyleSlot, type AdaptiveFlowStyles, type AdaptiveFlowValidationContext, type AdaptiveFlowValidators, type AdaptiveStep, type AdaptiveStepRegistry, type AdaptiveStepRenderArgs, type AdaptiveStepRendererArgs, type AdaptiveStepTransition, type AppRequirement, type DefaultAdaptiveStep, DefaultAdaptiveSteps, type DefaultAppRequirement, DefaultAppRequirements, type IdentityResolution, type MaybePromise, type OAuthProvider, type PersistedAdaptiveFlowState, type RequirementGraph, type RequirementGraphNode, type RequirementResolver, createDefaultRequirementGraph, createRequirementGraph, defaultRequirementResolvers, defaultRequirements, evaluateNextStep, getMissingRequirements, initialContext };
+export { type AdaptiveContext, type AdaptiveContextBase, AdaptiveFlow, type AdaptiveFlowAdapter, type AdaptiveFlowClassNames, type AdaptiveFlowFieldErrors, type AdaptiveFlowPersistence, type AdaptiveFlowProps, type AdaptiveFlowSchema, type AdaptiveFlowSchemas, type AdaptiveFlowStorageDriver, type AdaptiveFlowStyleSlot, type AdaptiveFlowStyles, type AdaptiveFlowValidationContext, type AdaptiveFlowValidationIssue, type AdaptiveFlowValidationResult, type AdaptiveFlowValidators, type AdaptiveStep, type AdaptiveStepRegistry, type AdaptiveStepRenderArgs, type AdaptiveStepRendererArgs, type AdaptiveStepTransition, type AppRequirement, type DefaultAdaptiveStep, DefaultAdaptiveSteps, type DefaultAppRequirement, DefaultAppRequirements, type IdentityResolution, type MaybePromise, type OAuthProvider, type PersistedAdaptiveFlowState, type RequirementGraph, type RequirementGraphNode, type RequirementResolver, type UseAdaptiveFlowOptions, type UseAdaptiveFlowResult, createDefaultRequirementGraph, createRequirementGraph, defaultRequirementResolvers, defaultRequirements, evaluateNextStep, getMissingRequirements, initialContext, useAdaptiveFlow };