@secmia/openui-flow 3.0.0

package/README.md

@@ -0,0 +1,804 @@
+# @secmia/openui-flow
+
+Production-ready adaptive workflow and onboarding flow engine for React.
+
+If you are evaluating quickly, you can get first success in under 3 minutes.
+
+## 3-minute onboarding path
+
+1. Install package.
+2. Paste the starter component.
+3. Confirm `onComplete` fires.
+
+```bash
+npm install @secmia/openui-flow
+```
+
+```tsx
+'use client';
+
+import {
+  AdaptiveFlow,
+  DefaultAppRequirements,
+  type AdaptiveFlowAdapter,
+} from '@secmia/openui-flow';
+
+type AppRequirement =
+  | (typeof DefaultAppRequirements)[keyof typeof DefaultAppRequirements]
+  | 'selected_plan';
+
+const requirements: AppRequirement[] = [
+  DefaultAppRequirements.HAS_EMAIL,
+  DefaultAppRequirements.EMAIL_VERIFIED,
+  DefaultAppRequirements.HAS_PASSWORD,
+  DefaultAppRequirements.HAS_FIRST_NAME,
+  DefaultAppRequirements.ACCEPTED_TOS,
+  'selected_plan',
+];
+
+const adapter: AdaptiveFlowAdapter = {
+  async lookupByEmail(email) {
+    const exists = email.endsWith('@company.com');
+    return {
+      accountExists: exists,
+      hasPassword: exists,
+      isVerified: false,
+      agreedToTos: false,
+      profile: { firstName: null, lastName: null, jobTitle: null },
+    };
+  },
+  async requestOtp(email) {
+    console.log('request otp', email);
+  },
+  async verifyOtp(email, code) {
+    console.log('verify otp', email, code);
+  },
+};
+
+export default function FlowPage() {
+  return (
+    <AdaptiveFlow
+      requirements={requirements}
+      adapter={adapter}
+      persistence={{ key: 'flow-state:v1', storage: 'session' }}
+      onComplete={(context) => {
+        console.log('flow complete', context);
+      }}
+    />
+  );
+}
+```
+
+Expected result:
+- User progresses through required steps.
+- Flow ends at complete state.
+- `onComplete` receives final context.
+
+Peer dependencies:
+- `react` `^18 || ^19`
+- `react-dom` `^18 || ^19`
+
+---
+
+## Quick answers
+
+Can users add their own flows?
+- Yes. This is first-class.
+- Define your own requirements, graph, step keys, resolver logic, and UI rendering.
+
+When should I use requirements vs requirementGraph?
+- Use `requirements` for the fastest start.
+- Use `requirementGraph` when you need priorities, conditions, or dependencies.
+
+How do I keep onboarding logic local to my app?
+- Create an app-specific requirement union near your flow module.
+- Include defaults and your custom requirements in one list.
+
+---
+
+## First customization: local requirement contract
+
+```ts
+import { DefaultAppRequirements } from '@secmia/openui-flow';
+
+type DefaultRequirement =
+  (typeof DefaultAppRequirements)[keyof typeof DefaultAppRequirements];
+
+type ProductRequirement =
+  | DefaultRequirement
+  | 'selected_plan'
+  | 'connected_slack'
+  | 'has_workspace_name';
+
+export const requirements: ProductRequirement[] = [
+  DefaultAppRequirements.HAS_EMAIL,
+  DefaultAppRequirements.EMAIL_VERIFIED,
+  DefaultAppRequirements.HAS_PASSWORD,
+  DefaultAppRequirements.HAS_FIRST_NAME,
+  DefaultAppRequirements.ACCEPTED_TOS,
+  'selected_plan',
+  'connected_slack',
+];
+```
+
+---
+
+## Next level: graph mode
+
+Use this when you need priority routing, conditional activation, dependency gates, or async resolvers.
+
+```tsx
+import {
+  AdaptiveFlow,
+  DefaultAdaptiveSteps,
+  createRequirementGraph,
+  type AdaptiveContextBase,
+  type RequirementResolver,
+} from '@secmia/openui-flow';
+
+type AppContext = AdaptiveContextBase & {
+  riskLevel: 'low' | 'high';
+  useSso: boolean;
+  selectedPlan: 'starter' | 'pro' | null;
+};
+
+type Req =
+  | 'has_email'
+  | 'email_verified'
+  | 'has_password'
+  | 'accepted_tos'
+  | 'selected_plan';
+
+type Step =
+  | 'COLLECT_EMAIL'
+  | 'VERIFY_OTP'
+  | 'COLLECT_PASSWORD'
+  | 'COLLECT_TOS'
+  | 'SELECT_PLAN'
+  | 'COMPLETE';
+
+const requirements: Req[] = [
+  'has_email',
+  'email_verified',
+  'has_password',
+  'accepted_tos',
+  'selected_plan',
+];
+
+const resolvers: Partial<Record<Req, RequirementResolver<AppContext, Step>>> = {
+  has_email: { step: 'COLLECT_EMAIL', isMet: (ctx) => Boolean(ctx.email) },
+  email_verified: { step: 'VERIFY_OTP', isMet: async (ctx) => ctx.isVerified },
+  has_password: { step: 'COLLECT_PASSWORD', isMet: (ctx) => ctx.hasPassword },
+  accepted_tos: { step: 'COLLECT_TOS', isMet: (ctx) => ctx.agreedToTos },
+  selected_plan: { step: 'SELECT_PLAN', isMet: (ctx) => Boolean(ctx.selectedPlan) },
+};
+
+const graph = createRequirementGraph(requirements, resolvers, {
+  priorities: {
+    email_verified: 20,
+    has_password: 10,
+    selected_plan: 5,
+  },
+  conditions: {
+    has_password: (ctx) => !ctx.useSso,
+    email_verified: (ctx) => ctx.riskLevel === 'high',
+  },
+  dependencies: {
+    selected_plan: ['accepted_tos'],
+  },
+});
+
+<AdaptiveFlow<AppContext, Req, Step>
+  requirementGraph={graph}
+  completeStep={DefaultAdaptiveSteps.COMPLETE}
+/>;
+```
+
+---
+
+## Advanced: maximum configuration
+
+This demonstrates almost every major capability in one setup.
+
+```tsx
+'use client';
+
+import {
+  AdaptiveFlow,
+  DefaultAdaptiveSteps,
+  createDefaultRequirementGraph,
+  type AdaptiveContextBase,
+  type AdaptiveFlowAdapter,
+  type AdaptiveFlowValidators,
+  type RequirementResolver,
+} from '@secmia/openui-flow';
+
+type ProductContext = AdaptiveContextBase & {
+  selectedPlan: 'starter' | 'pro' | null;
+  workspaceName: string | null;
+  riskScore: number;
+  useSso: boolean;
+};
+
+type ProductRequirement =
+  | 'has_email'
+  | 'email_verified'
+  | 'has_password'
+  | 'has_first_name'
+  | 'accepted_tos'
+  | 'selected_plan'
+  | 'has_workspace_name';
+
+type ProductStep =
+  | 'COLLECT_EMAIL'
+  | 'VERIFY_OTP'
+  | 'COLLECT_PASSWORD'
+  | 'COLLECT_PROFILE'
+  | 'COLLECT_TOS'
+  | 'SELECT_PLAN'
+  | 'COLLECT_WORKSPACE'
+  | 'COMPLETE';
+
+const resolvers: Partial<Record<ProductRequirement, RequirementResolver<ProductContext, ProductStep>>> = {
+  selected_plan: {
+    step: 'SELECT_PLAN',
+    isMet: (ctx) => Boolean(ctx.selectedPlan),
+  },
+  has_workspace_name: {
+    step: 'COLLECT_WORKSPACE',
+    isMet: (ctx) => Boolean(ctx.workspaceName),
+  },
+};
+
+const graph = createDefaultRequirementGraph<ProductContext, ProductRequirement, ProductStep>({
+  requirements: [
+    'has_email',
+    'email_verified',
+    'has_password',
+    'has_first_name',
+    'accepted_tos',
+    'selected_plan',
+    'has_workspace_name',
+  ],
+  resolvers,
+  priorities: {
+    email_verified: 50,
+    has_password: 40,
+    selected_plan: 30,
+  },
+  conditions: {
+    has_password: (ctx) => !ctx.useSso,
+    email_verified: (ctx) => ctx.riskScore >= 70,
+  },
+  dependencies: {
+    has_workspace_name: ['selected_plan'],
+  },
+});
+
+const adapter: AdaptiveFlowAdapter<ProductContext> = {
+  async lookupByEmail(email) {
+    const response = await fetch('/api/identity/lookup', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ email }),
+    });
+    if (!response.ok) {
+      throw new Error('Lookup failed.');
+    }
+    return response.json();
+  },
+  async requestOtp(email) {
+    await fetch('/api/identity/request-otp', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ email }),
+    });
+  },
+  async verifyOtp(email, code) {
+    await fetch('/api/identity/verify-otp', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ email, code }),
+    });
+  },
+  async saveProfile(context) {
+    await fetch('/api/profile', {
+      method: 'PATCH',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(context.profile),
+    });
+  },
+  async acceptTos() {
+    await fetch('/api/legal/accept', { method: 'POST' });
+  },
+  async startOAuth(provider) {
+    window.location.href = `/api/identity/${provider}`;
+  },
+  async completeOAuth() {
+    return {
+      isVerified: true,
+      hasPassword: true,
+    };
+  },
+};
+
+const validators: AdaptiveFlowValidators<ProductContext> = {
+  email: (value) => {
+    if (!value.endsWith('@company.com')) {
+      return 'Company email is required.';
+    }
+  },
+  password: (value, { hasPassword }) => {
+    if (!hasPassword && value.length < 12) {
+      return 'Password must be at least 12 characters.';
+    }
+  },
+};
+
+export default function EnterpriseFlow() {
+  return (
+    <AdaptiveFlow<ProductContext, ProductRequirement, ProductStep>
+      requirementGraph={graph}
+      completeStep={DefaultAdaptiveSteps.COMPLETE}
+      adapter={adapter}
+      validators={validators}
+      persistence={{
+        key: 'enterprise-flow-state:v1',
+        storage: 'session',
+        clearOnComplete: true,
+      }}
+      stepTitles={{
+        SELECT_PLAN: 'Choose your plan',
+        COLLECT_WORKSPACE: 'Name your workspace',
+      }}
+      stepRegistry={{
+        SELECT_PLAN: ({ setContextPatch }) => (
+          <button onClick={() => setContextPatch({ selectedPlan: 'pro' })}>Select Pro Plan</button>
+        ),
+        COLLECT_WORKSPACE: ({ setContextPatch }) => (
+          <button onClick={() => setContextPatch({ workspaceName: 'Acme HQ' })}>Set Workspace</button>
+        ),
+      }}
+      renderStep={({ defaultView, transitions }) => (
+        <div>
+          <p>Transitions so far: {transitions.length}</p>
+          {defaultView}
+        </div>
+      )}
+      onStepTransition={(transition) => {
+        console.log('transition', transition);
+      }}
+      onError={(error) => {
+        console.error('flow error', error);
+      }}
+      onComplete={(context) => {
+        console.log('complete context', context);
+      }}
+      classNames={{
+        shell: 'rounded-xl border p-6 bg-white',
+        title: 'text-xl font-semibold',
+      }}
+      styles={{
+        shell: { maxWidth: 720 },
+      }}
+      unstyled={false}
+      initialValue={{
+        selectedPlan: null,
+        workspaceName: null,
+        riskScore: 80,
+        useSso: false,
+      }}
+    />
+  );
+}
+```
+
+---
+
+## Custom UI: full control options
+
+You have 4 UI customization levels, from quick theming to complete headless control.
+
+### Level 1: style and class overrides
+
+Keep built-in UI structure, but override styles/classes for all slots.
+
+```tsx
+<AdaptiveFlow
+  classNames={{
+    shell: 'rounded-2xl border border-zinc-200 p-8',
+    title: 'text-2xl font-bold tracking-tight',
+    oauthButton: 'h-11 rounded-lg border px-4',
+    error: 'text-sm text-red-700 bg-red-50 rounded p-3',
+  }}
+  styles={{
+    shell: { maxWidth: 680, margin: '0 auto' },
+    title: { letterSpacing: '-0.01em' },
+  }}
+/>
+```
+
+Use `unstyled` to disable built-in inline defaults.
+
+```tsx
+<AdaptiveFlow unstyled classNames={{ shell: 'my-own-layout-root' }} />
+```
+
+### Level 2: custom UI for specific steps
+
+Use `stepRegistry` to replace selected steps with your own components while leaving other steps on defaults.
+
+```tsx
+<AdaptiveFlow
+  stepRegistry={{
+    SELECT_PLAN: ({ setContextPatch, run }) => (
+      <div>
+        <h3>Choose a plan</h3>
+        <button
+          onClick={() => {
+            void run(async () => {
+              setContextPatch({ selectedPlan: 'starter' });
+            });
+          }}
+        >
+          Starter
+        </button>
+        <button
+          onClick={() => {
+            void run(async () => {
+              setContextPatch({ selectedPlan: 'pro' });
+            });
+          }}
+        >
+          Pro
+        </button>
+      </div>
+    ),
+  }}
+/>
+```
+
+### Level 3: custom renderer for all steps
+
+Use `renderStep` for full step-body ownership. You can still reuse `defaultView` when useful.
+
+```tsx
+<AdaptiveFlow
+  renderStep={({ step, defaultView, transitions, context, setContextPatch }) => (
+    <section>
+      <header>
+        <h2>Current step: {step}</h2>
+        <p>Transitions: {transitions.length}</p>
+      </header>
+
+      <aside>
+        <button onClick={() => setContextPatch({ locale: 'en-US' } as Partial<typeof context>)}>
+          Set locale
+        </button>
+      </aside>
+
+      <main>{defaultView}</main>
+    </section>
+  )}
+/>
+```
+
+### 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.
+
+```tsx
+'use client';
+
+import { useEffect, useMemo, useState } from 'react';
+import {
+  createRequirementGraph,
+  evaluateNextStep,
+  getMissingRequirements,
+  DefaultAdaptiveSteps,
+  type AdaptiveContextBase,
+  type RequirementResolver,
+} from '@secmia/openui-flow';
+
+type Ctx = AdaptiveContextBase & {
+  selectedPlan: 'starter' | 'pro' | null;
+};
+
+type Req = 'has_email' | 'email_verified' | 'selected_plan';
+type Step = 'COLLECT_EMAIL' | 'VERIFY_OTP' | 'SELECT_PLAN' | 'COMPLETE';
+
+const resolvers: Partial<Record<Req, RequirementResolver<Ctx, Step>>> = {
+  has_email: { step: 'COLLECT_EMAIL', isMet: (ctx) => Boolean(ctx.email) },
+  email_verified: { step: 'VERIFY_OTP', isMet: (ctx) => ctx.isVerified },
+  selected_plan: { step: 'SELECT_PLAN', isMet: (ctx) => Boolean(ctx.selectedPlan) },
+};
+
+export default function FullyCustomAuth() {
+  const [context, setContext] = useState<Ctx>({
+    email: null,
+    isVerified: false,
+    hasPassword: false,
+    agreedToTos: false,
+    profile: null,
+    selectedPlan: null,
+  });
+  const [step, setStep] = useState<Step>('COLLECT_EMAIL');
+  const [missing, setMissing] = useState<Req[]>([]);
+
+  const graph = useMemo(
+    () => createRequirementGraph<Ctx, Req, Step>(['has_email', 'email_verified', 'selected_plan'], resolvers),
+    [],
+  );
+
+  useEffect(() => {
+    void (async () => {
+      const [nextStep, missingReqs] = await Promise.all([
+        evaluateNextStep(context, graph, DefaultAdaptiveSteps.COMPLETE as Step),
+        getMissingRequirements(context, graph),
+      ]);
+      setStep(nextStep);
+      setMissing(missingReqs);
+    })();
+  }, [context, graph]);
+
+  return (
+    <div>
+      <header>
+        <h1>My Brand Auth</h1>
+        <p>
+          Progress: {3 - missing.length}/3
+        </p>
+      </header>
+
+      {step === 'COLLECT_EMAIL' ? (
+        <button onClick={() => setContext((prev) => ({ ...prev, email: 'user@company.com' }))}>
+          Mock email submit
+        </button>
+      ) : null}
+
+      {step === 'VERIFY_OTP' ? (
+        <button onClick={() => setContext((prev) => ({ ...prev, isVerified: true }))}>
+          Mock verify
+        </button>
+      ) : null}
+
+      {step === 'SELECT_PLAN' ? (
+        <button onClick={() => setContext((prev) => ({ ...prev, selectedPlan: 'pro' }))}>
+          Choose Pro
+        </button>
+      ) : null}
+
+      {step === 'COMPLETE' ? <p>All done.</p> : null}
+    </div>
+  );
+}
+```
+
+Precedence rule inside `AdaptiveFlow`:
+- `renderStep` wins first.
+- If `renderStep` is not provided, `stepRegistry[step]` is used.
+- If neither is provided, built-in default step UI is rendered.
+
+This gives you a clean path from quick defaults to complete custom UI ownership.
+
+---
+
+## Integration recipes
+
+### Next.js App Router
+
+```tsx
+'use client';
+
+import { useRouter } from 'next/navigation';
+import {
+  AdaptiveFlow,
+  DefaultAppRequirements,
+  type AdaptiveFlowAdapter,
+} from '@secmia/openui-flow';
+
+type AppRequirement =
+  | (typeof DefaultAppRequirements)[keyof typeof DefaultAppRequirements]
+  | 'has_workspace_name';
+
+const requirements: AppRequirement[] = [
+  DefaultAppRequirements.HAS_EMAIL,
+  DefaultAppRequirements.EMAIL_VERIFIED,
+  DefaultAppRequirements.HAS_PASSWORD,
+  DefaultAppRequirements.HAS_FIRST_NAME,
+  DefaultAppRequirements.ACCEPTED_TOS,
+];
+
+const adapter: AdaptiveFlowAdapter = {
+  async lookupByEmail(email) {
+    const response = await fetch('/api/identity/lookup', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ email }),
+    });
+    if (!response.ok) {
+      throw new Error('Lookup failed.');
+    }
+    return response.json();
+  },
+};
+
+export default function SignInClient() {
+  const router = useRouter();
+
+  return (
+    <AdaptiveFlow
+      adapter={adapter}
+      requirements={requirements}
+      persistence={{ key: 'next-flow-state:v1', storage: 'session' }}
+      onComplete={() => router.replace('/dashboard')}
+    />
+  );
+}
+```
+
+### Supabase
+
+```tsx
+'use client';
+
+import { createClient } from '@supabase/supabase-js';
+import { AdaptiveFlow, type AdaptiveFlowAdapter } from '@secmia/openui-flow';
+
+const supabase = createClient(
+  process.env.NEXT_PUBLIC_SUPABASE_URL!,
+  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
+);
+
+const adapter: AdaptiveFlowAdapter = {
+  async requestOtp(email) {
+    const { error } = await supabase.auth.signInWithOtp({ email });
+    if (error) {
+      throw new Error(error.message);
+    }
+  },
+  async verifyOtp(email, code) {
+    const { error } = await supabase.auth.verifyOtp({ email, token: code, type: 'email' });
+    if (error) {
+      throw new Error(error.message);
+    }
+  },
+  async startOAuth(provider) {
+    const { error } = await supabase.auth.signInWithOAuth({
+      provider,
+      options: { redirectTo: `${window.location.origin}/auth/callback` },
+    });
+    if (error) {
+      throw new Error(error.message);
+    }
+  },
+};
+
+export default function SupabaseAuth() {
+  return <AdaptiveFlow adapter={adapter} persistence={{ key: 'supabase-auth:v1' }} />;
+}
+```
+
+### Firebase
+
+```tsx
+'use client';
+
+import { getAuth, GoogleAuthProvider, OAuthProvider, signInWithPopup } from 'firebase/auth';
+import { AdaptiveFlow, type AdaptiveFlowAdapter } from '@secmia/openui-flow';
+import { app } from './firebase';
+
+const auth = getAuth(app);
+
+const adapter: AdaptiveFlowAdapter = {
+  async startOAuth(provider) {
+    if (provider === 'google') {
+      await signInWithPopup(auth, new GoogleAuthProvider());
+      return;
+    }
+    await signInWithPopup(auth, new OAuthProvider('apple.com'));
+  },
+};
+
+export default function FirebaseAuth() {
+  return <AdaptiveFlow adapter={adapter} persistence={{ key: 'firebase-auth:v1' }} />;
+}
+```
+
+---
+
+## Engine-only usage
+
+```ts
+import {
+  createRequirementGraph,
+  evaluateNextStep,
+  getMissingRequirements,
+  DefaultAdaptiveSteps,
+} from '@secmia/openui-flow';
+
+const nextStep = await evaluateNextStep(context, graph, DefaultAdaptiveSteps.COMPLETE);
+const missing = await getMissingRequirements(context, graph);
+```
+
+---
+
+## Core concepts
+
+- Context: current auth and profile state.
+- Requirement: business condition that must be satisfied.
+- Resolver: checker function for one requirement.
+- Step: current UI state for unmet requirement.
+- RequirementGraph: graph nodes with optional priority, condition, and dependency metadata.
+
+Evaluation loop:
+1. Build graph.
+2. Evaluate active nodes.
+3. Select highest-priority unmet node.
+4. Render mapped step.
+5. Update context.
+6. Repeat until complete step.
+
+---
+
+## API reference
+
+Primary exports:
+- `AdaptiveFlow`
+- `defaultRequirements`
+- `initialContext`
+- `defaultRequirementResolvers`
+- `createDefaultRequirementGraph`
+- `createRequirementGraph`
+- `evaluateNextStep`
+- `getMissingRequirements`
+- `DefaultAdaptiveSteps`
+- `DefaultAppRequirements`
+
+Important types:
+- `AdaptiveFlowProps`
+- `AdaptiveFlowAdapter`
+- `AdaptiveFlowValidators`
+- `AdaptiveFlowPersistence`
+- `AdaptiveStepRegistry`
+- `AdaptiveStepRendererArgs`
+- `AdaptiveStepRenderArgs`
+- `AdaptiveStepTransition`
+- `RequirementResolver`
+- `RequirementGraph`
+- `RequirementGraphNode`
+- `AdaptiveContext`
+- `AdaptiveContextBase`
+
+---
+
+## Release checklist
+
+- Ensure adapter methods return clear, user-safe errors.
+- Version persistence keys (example: `flow-state:v1`).
+- Track analytics with `onStepTransition`.
+- Keep requirements and graph definitions local to each product module.
+- Add integration tests for all flow branches.
+- Run `npm run typecheck` and `npm run build` before every publish.
+
+---
+
+## Troubleshooting
+
+Step not appearing:
+- Cause: priority, condition, or dependency suppresses node activation.
+- Fix: inspect graph `priorities`, `conditions`, and `dependencies`.
+
+State resets on refresh:
+- Cause: persistence missing or wrong key.
+- Fix: set `persistence.key` and chosen storage.
+
+OAuth return does not resume:
+- Cause: missing `completeOAuth` or persistence disabled.
+- Fix: implement `completeOAuth` and enable persistence.
+
+---
+
+## License
+
+MIT