wizzard-stepper-react 1.3.1 → 1.5.0

package/README.md

@@ -5,7 +5,8 @@ A flexible, headless, and strictly typed multi-step wizard library for React. Bu
 ## Features
 
 - 🧠 **Headless Architecture**: Full control over UI. You bring the components, we provide the logic.
-- 🔌 **Adapter Pattern**: Built-in adapters for **Zod**, **Yup** validation, and **LocalStorage/URL/Memory** persistence.
+- 🔌 **Adapter Pattern**: Zero-dependency adapters for **Zod**, **Yup** validation. No hard dependencies on these libraries in the core.
+- 🏗️ **Complex Data**: Built-in support for nested objects and arrays using dot notation (`users[0].name`).
 - 🛡️ **Strictly Typed**: Built with TypeScript generics for type safety across steps.
 - 🔀 **Conditional Steps**: Dynamic pipelines where steps can be skipped based on data.
 - 💾 **Persistence**: Auto-save progress to LocalStorage or custom stores.
@@ -21,51 +22,61 @@ yarn add wizzard-stepper-react
 pnpm add wizzard-stepper-react
 ```
 
-## Quick Start (Native Forms)
+## Usage
 
-```tsx
-import { WizardProvider, useWizard, IWizardConfig } from 'wizzard-stepper-react';
+### 1. Basic Usage (Compatible & Simple)
 
-// 1. Define Config
-const config: IWizardConfig = {
-  steps: [
-    { id: 'personal', label: 'Personal Info' },
-    { id: 'contact', label: 'Contact Details' },
-  ],
-};
+The quickest way to get started. Types are flexible (`any`).
+
+```tsx
+import { WizardProvider, useWizard } from 'wizzard-stepper-react';
 
-// 2. Create Steps
 const Step1 = () => {
-  const { handleStepChange, wizardData } = useWizard<{ name: string }>();
+  const { wizardData, handleStepChange } = useWizard();
   return (
     <input 
-      value={wizardData.name || ''} 
-      onChange={e => handleStepChange('name', e.target.value)} 
+      value={wizardData.name} 
+      onChange={(e) => handleStepChange('name', e.target.value)} 
     />
   );
 };
 
-// 3. Wrap in Provider
-export default function App() {
-  return (
-    <WizardProvider config={config}>
-       <WizardContent />
-    </WizardProvider>
-  );
+const App = () => (
+  <WizardProvider>
+    <Step1 />
+  </WizardProvider>
+);
+```
+
+### 2. Strict Usage (Factory Pattern 🏭)
+
+For production apps, use the factory pattern to get perfect type inference.
+
+**`wizards/my-wizard.ts`**
+```typescript
+import { createWizardFactory } from 'wizzard-stepper-react';
+
+interface MySchema {
+  name: string;
+  age: number;
 }
 
-const WizardContent = () => {
-  const { currentStep, goToNextStep } = useWizard();
-  if(!currentStep) return null;
-  return (
-    <div>
-      {currentStep.id === 'personal' && <Step1 />}
-      <button onClick={goToNextStep}>Next</button>
-    </div>
-  )
+export const { WizardProvider, useWizard } = createWizardFactory<MySchema>();
+```
+
+**`components/MyForm.tsx`**
+```tsx
+import { useWizard } from '../wizards/my-wizard';
+
+const Step1 = () => {
+  const { wizardData } = useWizard();
+  // ✅ wizardData is strictly typed as MySchema
+  // ✅ Autocomplete works for wizardData.name
 }
 ```
 
+See [MIGRATION.md](./MIGRATION.md) for details on switching to strict mode.
+
 ## Integration with React Hook Form + Zod
 
 ```tsx
@@ -97,12 +108,94 @@ const config = {
     { 
       id: 'step1', 
       label: 'Email', 
-      validationAdapter: new ZodAdapter(schema) // Blocks 'Next' if invalid
+      // Zero-dependency: works with any Zod version
+      validationAdapter: new ZodAdapter(schema) 
     }
   ]
 }
 ```
 
+## Complex Data (Arrays & Objects)
+
+The library provides `setData` and `getData` helpers that support deep paths using dot notation and array brackets.
+
+```tsx
+const { setData, wizardData } = useWizard<MyData>();
+
+// Set nested object property
+setData('user.profile.name', 'John');
+
+// Set array item property
+setData('items[0].value', 'New Value');
+
+// Get with default value
+const name = getData('user.profile.name', 'Anonymous');
+
+// 🆕 Bulk Update (Autofill)
+const autoFillParams = () => {
+  // Merges into existing data
+  updateData({ 
+    name: 'John Doe',
+    email: 'john@example.com' 
+  });
+};
+```
+
+## Performance & Optimization 🚀
+
+For large forms (e.g., 50+ array items), using `useWizard` context can cause performance issues because it triggers a re-render on every keystroke. To solve this, we provide **granular hooks** that allow components to subscribe only to the specific data they need.
+
+### 1. Use `useWizardValue` for Granular Updates
+
+Instead of reading the whole `wizardData`, subscribe to a single field. The component will only re-render when *that specific field* changes.
+
+```tsx
+// ✅ FAST: Only re-renders when "users[0].name" changes
+const NameInput = () => {
+  // Subscribe to specific path
+  const name = useWizardValue('users[0].name'); 
+  const { setData } = useWizardActions(); // Component actions don't trigger re-renders
+  
+  return <input value={name} onChange={e => setData('users[0].name', e.target.value)} />;
+}
+
+// ❌ SLOW: Re-renders on ANY change in the form
+const NameInputSlow = () => {
+  const { wizardData, setData } = useWizard();
+  return <input value={wizardData.users[0].name} ... />;
+}
+```
+
+### 2. Use `useWizardSelector` for Lists
+
+When rendering lists, avoid passing the whole `children` array to the parent component. Instead, select only IDs and let child components fetch their own data.
+
+```tsx
+const ChildrenList = () => {
+  // ✅ Only re-renders when the list LENGTH changes or IDs change
+  const childIds = useWizardSelector(state => state.children.map(c => c.id));
+  
+  return (
+    <div>
+      {childIds.map((id, index) => (
+         // Pass ID/Index, NOT the data object
+        <ChildRow key={id} index={index} />
+      ))}
+    </div>
+  );
+}
+```
+
+### 3. Debounced Validation
+
+For heavy validation schemas, you can debounce validation to keep the UI responsive.
+
+```tsx
+setData('field.path', value, { 
+  debounceValidation: 300 // Wait 300ms before running Zod/Yup validation
+});
+```
+
 ## Conditional Steps
 
 Steps can be dynamically included based on the wizard's state.
@@ -137,29 +230,141 @@ const config: IWizardConfig = {
 }
 ```
 
+## Advanced Features 🌟
+
+### 1. Step Renderer (Declarative UI)
+
+Instead of manual switch statements with `currentStep.id`, trust the renderer!
+
+```typescript
+// Define component in config
+const steps = [
+  { id: 'step1', label: 'Start', component: Step1Component },
+  { id: 'step2', label: 'End', component: Step2Component },
+];
+
+// Render
+const App = () => (
+  <WizardProvider config={{ steps }}>
+    <WizardStepRenderer 
+       wrapper={({ children }) => (
+         <motion.div initial={{ opacity: 0 }} animate={{ opacity: 1 }}>
+           {children}
+         </motion.div>
+       )} 
+    />
+  </WizardProvider>
+);
+```
+
+### 2. Routing Integration
+
+Sync wizard state with URL using `onStepChange`.
+
+```tsx
+const navigate = useNavigate();
+
+const config: IWizardConfig = {
+  // 1. Sync State -> URL
+  onStepChange: (prev, next, data) => {
+    navigate(`/wizard/${next}`);
+    // Optional: Send event to Analytics
+    trackEvent('wizard_step', { step: next });
+  },
+  steps: [...]
+};
+
+// 2. Sync URL -> State (Initial Load)
+const { stepId } = useParams();
+
+return <WizardProvider config={config} initialStepId={stepId}>...</WizardProvider>;
+```
+
+### 3. Granular Persistence
+
+By default, the wizard uses `MemoryAdapter` (RAM only). You can enable `LocalStorage` globally, but override it for sensitive steps.
+
+```tsx
+const config: IWizardConfig = {
+  // Global: Persist everything to LocalStorage
+  persistence: { adapter: new LocalStorageAdapter('wizard_') },
+  steps: [
+    { 
+      id: 'public', 
+      label: 'Public Info',
+      // Inherits global adapter (LocalStorage)
+    },
+    { 
+      id: 'sensitive', 
+      label: 'Credit Card',
+      // Override: Store strictly in memory (cleared on refresh)
+      persistenceAdapter: new MemoryAdapter() 
+    }
+  ]
+};
+```
+
 ## API Reference
 
 ### `IWizardConfig<T>`
+
 - `steps`: Array of step configurations.
 - `persistence`: Configuration for state persistence.
 - `autoValidate`: (obj) Global validation setting.
 
 ### `useWizard<T>()`
+
 - `activeSteps`: Steps that match conditions.
 - `currentStep`: The currently active step object.
-- `wizardData`: The global state object.
-- `handleStepChange(key, value)`: Helper to update state.
+- `wizardData`: The global state object (subscribe cautiously!).
+- `setData(path, value, options?)`: Update state. Options: `{ debounceValidation: number }`.
+- `getData(path, defaultValue?)`: Retrieve nested data.
+- `handleStepChange(key, value)`: simple helper to update top-level state.
 - `goToNextStep()`: Validates and moves next.
 - `goToStep(id)`: Jumps to specific step.
 - `allErrors`: Map of validation errors.
 
+### New Performance Hooks
+
+#### `useWizardValue<T>(path: string)`
+
+Subscribes to a specific data path. Re-renders **only** when that value changes.
+
+#### `useWizardError(path: string)`
+
+Subscribes to validation errors for a specific path. Highly recommended for individual inputs.
+
+#### `useWizardSelector<T>(selector: (state: T) => any)`
+
+Create a custom subscription to the wizard state. Ideal for derived state or lists.
+
+#### `useWizardActions()`
+
+Returns object with actions (`setData`, `goToNextStep`, etc.) **without** subscribing to state changes. Use this in components that trigger updates but don't need to render data.
+
 ## Demos
 
 Check out the [Live Demo](https://ZizzX.github.io/wizzard-stepper-react/), [NPM](https://www.npmjs.com/package/wizzard-stepper-react) or the [source code](https://github.com/ZizzX/wizzard-stepper-react-demo) for a complete implementation featuring:
+
 - **Tailwind CSS v4** UI overhaul.
 - **React Hook Form + Zod** integration.
 - **Formik + Yup** integration.
 - **Conditional Routing** logic.
+- **Advanced Features Demo**: (`/advanced`) showcasing:
+  - **Autofill**: `updateData` global merge.
+  - **Declarative Rendering**: `<WizardStepRenderer />`.
+  - **Granular Persistence**: Hybrid Memory/LocalStorage.
+
+## Advanced Demo Guide 🧪
+
+Visit `/advanced` in the demo to try:
+
+1.  **Autofill**: Click "Magic Autofill" to test `updateData()`. It instantly populates the form (merged with existing data).
+2.  **Hybrid Persistence**:
+    *   **Step 1 (Identity)**: Refreshes persist (LocalStorage).
+    *   **Step 2 (Security)**: Refreshes CLEAR data (MemoryAdapter).
+3.  **Declarative UI**: The steps are rendered using `<WizardStepRenderer />` with Framer Motion animations, defined in the config!
 
 ## License
+
 MIT