@secmia/openui-flow 4.0.1 → 4.2.0

package/dist/index.d.ts

@@ -1,6 +1,9 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as React from 'react';
 
+/**
+ * Built-in requirement keys that cover the default flow states supported by the package.
+ */
 declare const DefaultAppRequirements: {
     readonly HAS_EMAIL: "has_email";
     readonly EMAIL_VERIFIED: "email_verified";
@@ -10,6 +13,9 @@ declare const DefaultAppRequirements: {
     readonly ACCEPTED_TOS: "accepted_tos";
     readonly HAS_JOB_TITLE: "has_job_title";
 };
+/**
+ * Built-in step keys used by the default flow UI and default requirement resolvers.
+ */
 declare const DefaultAdaptiveSteps: {
     readonly COLLECT_EMAIL: "COLLECT_EMAIL";
     readonly VERIFY_OTP: "VERIFY_OTP";
@@ -18,10 +24,15 @@ declare const DefaultAdaptiveSteps: {
     readonly COLLECT_TOS: "COLLECT_TOS";
     readonly COMPLETE: "COMPLETE";
 };
+/** Requirement key from the built-in default requirement set. */
 type DefaultAppRequirement = (typeof DefaultAppRequirements)[keyof typeof DefaultAppRequirements];
+/** Step key from the built-in default step set. */
 type DefaultAdaptiveStep = (typeof DefaultAdaptiveSteps)[keyof typeof DefaultAdaptiveSteps];
+/** Requirement key used by the engine, including custom app-specific requirements. */
 type AppRequirement = DefaultAppRequirement | (string & {});
+/** Step key used by the engine, including custom app-specific steps. */
 type AdaptiveStep = DefaultAdaptiveStep | (string & {});
+/** Base context shape managed by the default flow helpers and UI. */
 type AdaptiveContextBase = {
     email: string | null;
     isVerified: boolean;
@@ -33,14 +44,23 @@ type AdaptiveContextBase = {
     };
     agreedToTos: boolean;
 };
+/** Alias for the default context shape used by the built-in component and hook. */
 type AdaptiveContext = AdaptiveContextBase;
+/** Default set of requirements used when a flow does not provide its own list. */
 declare const defaultRequirements: DefaultAppRequirement[];
+/** Default initial context used by the component and hook when no initialValue is provided. */
 declare const initialContext: AdaptiveContextBase;
+/** Utility type for APIs that may return either a synchronous or asynchronous value. */
 type MaybePromise<T> = T | Promise<T>;
+/** Resolver contract that maps one requirement to the step shown when it is unmet. */
 type RequirementResolver<TContext = AdaptiveContextBase, TStep extends string = AdaptiveStep> = {
     isMet: (context: TContext) => MaybePromise<boolean>;
     step: TStep;
 };
+/**
+ * Single requirement node in the requirement graph.
+ * The engine evaluates nodes by priority, dependency readiness, and custom conditions.
+ */
 type RequirementGraphNode<TContext, TRequirement extends string, TStep extends string> = {
     requirement: TRequirement;
     step: TStep;
@@ -49,13 +69,24 @@ type RequirementGraphNode<TContext, TRequirement extends string, TStep extends s
     priority?: number;
     dependsOn?: readonly TRequirement[];
 };
+/** Ordered requirement graph consumed by the engine evaluation helpers. */
 type RequirementGraph<TContext, TRequirement extends string, TStep extends string> = readonly RequirementGraphNode<TContext, TRequirement, TStep>[];
+/** Default requirement-to-step resolvers used by the built-in flow UI. */
 declare const defaultRequirementResolvers: Record<DefaultAppRequirement, RequirementResolver<AdaptiveContextBase, AdaptiveStep>>;
+/**
+ * Build a requirement graph from a requirement list, resolver map, and optional graph metadata.
+ *
+ * The function validates that dependencies refer to known resolver-backed requirements and
+ * rejects circular dependency chains at graph creation time.
+ */
 declare function createRequirementGraph<TContext, TRequirement extends string, TStep extends string>(requirements: readonly TRequirement[], resolvers: Partial<Record<TRequirement, RequirementResolver<TContext, TStep>>>, options?: {
     priorities?: Partial<Record<TRequirement, number>>;
     conditions?: Partial<Record<TRequirement, (context: TContext) => MaybePromise<boolean>>>;
     dependencies?: Partial<Record<TRequirement, readonly TRequirement[]>>;
 }): RequirementGraph<TContext, TRequirement, TStep>;
+/**
+ * Build a requirement graph using the built-in default resolvers plus any app-specific overrides.
+ */
 declare function createDefaultRequirementGraph<TContext extends AdaptiveContextBase = AdaptiveContextBase, TRequirement extends string = DefaultAppRequirement, TStep extends string = AdaptiveStep>(options?: {
     requirements?: readonly TRequirement[];
     resolvers?: Partial<Record<TRequirement, RequirementResolver<TContext, TStep>>>;
@@ -63,10 +94,25 @@ declare function createDefaultRequirementGraph<TContext extends AdaptiveContextB
     conditions?: Partial<Record<TRequirement, (context: TContext) => MaybePromise<boolean>>>;
     dependencies?: Partial<Record<TRequirement, readonly TRequirement[]>>;
 }): RequirementGraph<TContext, TRequirement, TStep>;
+/**
+ * Evaluate the graph against the current context and return the next unmet step.
+ *
+ * Nodes are evaluated in dependency-aware order with deterministic tie-breaking.
+ */
 declare function evaluateNextStep<TContext, TRequirement extends string, TStep extends string>(context: TContext, graph: RequirementGraph<TContext, TRequirement, TStep>, completeStep: TStep): Promise<TStep>;
+/**
+ * Return every unmet requirement for the current context in graph evaluation order.
+ */
 declare function getMissingRequirements<TContext, TRequirement extends string, TStep extends string>(context: TContext, graph: RequirementGraph<TContext, TRequirement, TStep>): Promise<TRequirement[]>;
 
-type OAuthProvider = "google" | "apple";
+/** Supported OAuth provider identifiers accepted by the adapter and default UI. */
+type OAuthProvider = "google" | "apple" | (string & {});
+/** Configurable OAuth provider label/id pair used by the default footer buttons. */
+type AdaptiveFlowOAuthProvider = {
+    id: OAuthProvider | (string & {});
+    label: string;
+};
+/** Result returned by lookupByEmail to seed the flow with backend identity state. */
 type IdentityResolution = {
     accountExists: boolean;
     hasPassword?: boolean;
@@ -74,6 +120,7 @@ type IdentityResolution = {
     agreedToTos?: boolean;
     profile?: Partial<AdaptiveContextBase["profile"]>;
 };
+/** Backend adapter contract used by the flow to delegate all side effects. */
 type AdaptiveFlowAdapter<TContext extends AdaptiveContextBase = AdaptiveContextBase> = {
     lookupByEmail?: (email: string) => Promise<IdentityResolution | null>;
     requestOtp?: (email: string) => Promise<void>;
@@ -85,47 +132,100 @@ type AdaptiveFlowAdapter<TContext extends AdaptiveContextBase = AdaptiveContextB
     startOAuth?: (provider: OAuthProvider, context: TContext) => Promise<void>;
     completeOAuth?: (provider: OAuthProvider | null, context: TContext) => Promise<Partial<TContext> | void>;
 };
+/** Named style slots used by the built-in component shell and step renderers. */
 type AdaptiveFlowStyleSlot = "shell" | "headerRow" | "eyebrow" | "title" | "badge" | "success" | "error" | "info" | "caption" | "formRow" | "formColumn" | "input" | "button" | "checkboxRow" | "complete" | "footer" | "oauthButton";
+/** Inline style overrides keyed by the built-in style slots. */
 type AdaptiveFlowStyles = Partial<Record<AdaptiveFlowStyleSlot, React.CSSProperties>>;
+/** CSS class overrides keyed by the built-in style slots. */
 type AdaptiveFlowClassNames = Partial<Record<AdaptiveFlowStyleSlot, string>>;
+/** Minimal storage interface used by persistence drivers. */
 type AdaptiveFlowStorageDriver = Pick<Storage, "getItem" | "setItem" | "removeItem">;
+/** Persistence settings for storing and restoring flow state across reloads. */
 type AdaptiveFlowPersistence<TContext extends AdaptiveContextBase = AdaptiveContextBase> = {
     key: string;
     storage?: "session" | "local" | AdaptiveFlowStorageDriver;
     serialize?: (state: PersistedAdaptiveFlowState<TContext>) => string;
     deserialize?: (value: string) => PersistedAdaptiveFlowState<TContext>;
     clearOnComplete?: boolean;
+    onError?: (error: Error, phase: "read" | "write" | "clear") => void;
 };
+/** Persisted flow payload written to session/local/custom storage. */
 type PersistedAdaptiveFlowState<TContext extends AdaptiveContextBase = AdaptiveContextBase> = {
     context: TContext;
     oauthPendingProvider: OAuthProvider | null;
 };
+/** Context wrapper passed into validators so they can inspect the current flow state. */
 type AdaptiveFlowValidationContext<TContext extends AdaptiveContextBase = AdaptiveContextBase> = {
     context: TContext;
 };
+/** Validator failure payload that can target a specific field or the whole form. */
+type AdaptiveFlowValidationIssue = {
+    message: string;
+    field?: string;
+};
+/** Validator return type supported by the component and hook. */
+type AdaptiveFlowValidationResult = string | AdaptiveFlowValidationIssue | void | Promise<string | AdaptiveFlowValidationIssue | void>;
+/** Schema adapter contract used for optional Zod-friendly validation. */
+type AdaptiveFlowSchema<TValue> = {
+    safeParse?: (value: TValue) => {
+        success: boolean;
+        error?: {
+            message?: string;
+            issues?: Array<{
+                message?: string;
+                path?: Array<string | number>;
+            }>;
+        };
+    };
+    parse?: (value: TValue) => unknown;
+};
+/** Optional schema map for built-in step fields. */
+type AdaptiveFlowSchemas = {
+    email?: AdaptiveFlowSchema<string>;
+    otp?: AdaptiveFlowSchema<string>;
+    password?: AdaptiveFlowSchema<string>;
+    profile?: AdaptiveFlowSchema<AdaptiveContextBase["profile"]>;
+    tos?: AdaptiveFlowSchema<boolean>;
+};
+/** Backoff settings used to retry transient adapter calls and OAuth completion. */
+type AdaptiveFlowRetryPolicy = {
+    maxAttempts?: number;
+    initialDelayMs?: number;
+    factor?: number;
+    maxDelayMs?: number;
+    jitter?: boolean;
+    shouldRetry?: (error: Error, attempt: number) => boolean;
+    delay?: (attempt: number) => number;
+};
+/** Field error bag keyed by field path or logical field name. */
+type AdaptiveFlowFieldErrors = Partial<Record<string, string>>;
+/** Validator map for the built-in flow fields. */
 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;
 };
+/** Transition record emitted whenever the evaluated step changes. */
 type AdaptiveStepTransition<TStep extends string = AdaptiveStep> = {
     from: TStep | null;
     to: TStep;
     at: number;
     attempt: number;
 };
+/** Arguments supplied to a stepRegistry renderer for a specific step. */
 type AdaptiveStepRendererArgs<TContext extends AdaptiveContextBase, TRequirement extends string, TStep extends string> = {
     step: TStep;
     context: TContext;
     busy: boolean;
     message: string | null;
     errorMessage: string | null;
+    fieldErrors: AdaptiveFlowFieldErrors;
     missingRequirements: TRequirement[];
     requirements: readonly TRequirement[];
     setContextPatch: (patch: Partial<TContext>) => void;
@@ -133,13 +233,16 @@ type AdaptiveStepRendererArgs<TContext extends AdaptiveContextBase, TRequirement
     adapter?: AdaptiveFlowAdapter<TContext>;
     transitions: AdaptiveStepTransition<TStep>[];
 };
+/** Registry that overrides the UI for selected steps. */
 type AdaptiveStepRegistry<TContext extends AdaptiveContextBase, TRequirement extends string, TStep extends string> = Partial<Record<TStep, (args: AdaptiveStepRendererArgs<TContext, TRequirement, TStep>) => React.ReactNode>>;
+/** Arguments supplied to renderStep for full step-body customization. */
 type AdaptiveStepRenderArgs<TContext extends AdaptiveContextBase = AdaptiveContextBase, TRequirement extends string = AppRequirement, TStep extends string = AdaptiveStep> = {
     step: TStep;
     context: TContext;
     busy: boolean;
     message: string | null;
     errorMessage: string | null;
+    fieldErrors: AdaptiveFlowFieldErrors;
     missingRequirements: TRequirement[];
     requirements: readonly TRequirement[];
     defaultView: React.ReactNode;
@@ -148,6 +251,7 @@ type AdaptiveStepRenderArgs<TContext extends AdaptiveContextBase = AdaptiveConte
     adapter?: AdaptiveFlowAdapter<TContext>;
     transitions: AdaptiveStepTransition<TStep>[];
 };
+/** Props accepted by the AdaptiveFlow component. */
 type AdaptiveFlowProps<TContext extends AdaptiveContextBase = AdaptiveContext, TRequirement extends string = AppRequirement, TStep extends string = AdaptiveStep> = {
     adapter?: AdaptiveFlowAdapter<TContext>;
     requirements?: readonly TRequirement[];
@@ -172,7 +276,36 @@ type AdaptiveFlowProps<TContext extends AdaptiveContextBase = AdaptiveContext, T
     unstyled?: boolean;
     persistence?: AdaptiveFlowPersistence<TContext>;
     validators?: AdaptiveFlowValidators<TContext>;
+    schemas?: AdaptiveFlowSchemas;
+    oauthProviders?: readonly AdaptiveFlowOAuthProvider[];
+    retryPolicy?: AdaptiveFlowRetryPolicy;
+};
+/** Options accepted by the headless useAdaptiveFlow hook. */
+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">;
+/** Result object returned by useAdaptiveFlow. */
+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;
+/** Headless flow hook that owns state, evaluation, persistence, retries, and adapter wiring. */
+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, oauthProviders, retryPolicy, }: UseAdaptiveFlowOptions<TContext, TRequirement, TStep>): UseAdaptiveFlowResult<TContext, TRequirement, TStep>;
+/** Default UI wrapper around useAdaptiveFlow that renders the built-in flow shell and step UI. */
+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, oauthProviders, retryPolicy, }: 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 AdaptiveFlowOAuthProvider, type AdaptiveFlowPersistence, type AdaptiveFlowProps, type AdaptiveFlowRetryPolicy, 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 };