@secmia/openui-flow 3.0.0 → 4.0.0

package/AGENTS.md

@@ -0,0 +1,156 @@
+# AGENTS.md
+
+This document gives AI coding agents a complete debrief of this package.
+
+## Package Identity
+
+- Name: @secmia/openui-flow
+- Version line: 4.x
+- Runtime: React 18 or 19
+- Build: tsup (CJS + ESM + d.ts)
+- Core purpose: adaptive, requirement-driven multi-step flow orchestration
+
+This package is not restricted to authentication. It can power onboarding, compliance, setup wizards, risk gates, and any conditional step flow.
+
+## Fast Mental Model
+
+Think in this order:
+
+1. Context: current user/session/product state
+2. Requirements: conditions that must be met
+3. Resolvers: check whether each requirement is met and map failures to steps
+4. Graph: requirement ordering with priority, dependencies, and conditions
+5. Step selection: evaluate graph and return next step
+6. UI: render built-in, custom step UI, or fully headless UI
+
+Core evaluation APIs:
+
+- evaluateNextStep(context, graph, completeStep)
+- getMissingRequirements(context, graph)
+- createRequirementGraph(...)
+- createDefaultRequirementGraph(...)
+
+## Public API Surface (Current)
+
+Primary component and types:
+
+- AdaptiveFlow
+- AdaptiveFlowProps
+- AdaptiveFlowAdapter
+- AdaptiveFlowValidators
+- AdaptiveFlowPersistence
+- AdaptiveFlowStyles
+- AdaptiveFlowClassNames
+- AdaptiveStepRegistry
+- AdaptiveStepRenderArgs
+
+Engine and model exports:
+
+- createRequirementGraph
+- createDefaultRequirementGraph
+- evaluateNextStep
+- getMissingRequirements
+- defaultRequirements
+- defaultRequirementResolvers
+- initialContext
+- DefaultAdaptiveSteps
+- DefaultAppRequirements
+- RequirementGraph
+- RequirementGraphNode
+- RequirementResolver
+
+Source of truth for exports: src/index.ts.
+
+## UI Customization Levels
+
+Level 1: style/class slot overrides
+
+- Use styles and classNames
+- Use unstyled to disable built-in inline style defaults
+
+Level 2: per-step custom rendering
+
+- Use stepRegistry to override selected steps
+
+Level 3: full step-body control
+
+- Use renderStep
+- Precedence in component: renderStep first, then stepRegistry[step], then defaultView
+
+Level 4: full headless UI
+
+- Do not use AdaptiveFlow component UI
+- Use engine APIs directly and render your own shell/header/footer/actions
+
+## Adapter Contract Notes
+
+Adapter methods are optional by design. Implement only what your flow requires.
+
+Common methods:
+
+- lookupByEmail
+- requestOtp
+- verifyOtp
+- signInWithPassword
+- createPassword
+- saveProfile
+- acceptTos
+- startOAuth
+- completeOAuth
+
+Best practice for agents generating adapters:
+
+- Throw clear Error instances for failed backend calls
+- Keep sensitive token/session storage out of this UI package logic
+- Normalize backend responses into stable context patches
+
+## Persistence and Validation
+
+Persistence:
+
+- Configure via persistence prop
+- Supports session, local, or custom storage driver
+- Use versioned keys (example: flow-state:v1)
+
+Validation:
+
+- Configure via validators prop
+- Supports email, otp, password, profile, tos validators
+- Validators may be sync or async
+
+## Recommended Agent Workflow
+
+When an agent adds or edits a flow implementation:
+
+1. Define app-local requirement union (include defaults + custom requirements)
+2. Decide between requirements (simple) or requirementGraph (advanced)
+3. Implement/adjust adapter methods
+4. Add or update custom UI strategy (stepRegistry/renderStep/headless)
+5. Validate with npm run typecheck and npm run build
+6. Update README examples if API usage changes
+
+## Naming and Migration Context
+
+This package was intentionally shifted from auth-centric naming to flow-centric naming.
+
+- Current package name: @secmia/openui-flow
+- Current component/type prefix: AdaptiveFlow*
+
+Agents should prefer flow-centric terminology in generated code and docs unless explicitly asked to use auth-specific wording.
+
+## Non-Goals
+
+- Not an identity provider
+- Not a token/session authority
+- Not a backend SDK replacement
+
+It orchestrates front-end adaptive flow logic and delegates side effects to adapters.
+
+## Release Checks For Agents
+
+Before finalizing changes:
+
+1. Confirm exports remain aligned with src/index.ts
+2. Run npm run typecheck
+3. Run npm run build
+4. Ensure README snippets use current package name and symbols

package/README.md

@@ -4,6 +4,10 @@ Production-ready adaptive workflow and onboarding flow engine for React.
 
 If you are evaluating quickly, you can get first success in under 3 minutes.
 
+## For AI agents
+
+Use [AGENTS.md](AGENTS.md) for a complete package debrief, API map, customization levels, and recommended implementation workflow.
+
 ## 3-minute onboarding path
 
 1. Install package.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@secmia/openui-flow",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "description": "Backend-agnostic adaptive flow engine for React apps",
   "license": "MIT",
   "author": "",
@@ -15,7 +15,8 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "AGENTS.md"
   ],
   "scripts": {
     "build": "tsup",