wizzard-stepper-react 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Aziz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,163 @@
+# wizzard-stepper-react 🧙‍♂️
+
+A flexible, headless, and strictly typed multi-step wizard library for React. Built with adapter patterns in mind to support any form library (React Hook Form, Formik, etc.) and any validation schema (Zod, Yup).
+
+## 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.
+- 🛡️ **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.
+- ⚡ **Auto Validation**: Block navigation until the step is valid.
+
+## Installation
+
+```bash
+npm install wizzard-stepper-react zod
+# or
+yarn add wizzard-stepper-react zod
+```
+
+## Quick Start (Native Forms)
+
+```tsx
+import { WizardProvider, useWizard, IWizardConfig } from 'wizzard-stepper-react';
+
+// 1. Define Config
+const config: IWizardConfig = {
+  steps: [
+    { id: 'personal', label: 'Personal Info' },
+    { id: 'contact', label: 'Contact Details' },
+  ],
+};
+
+// 2. Create Steps
+const Step1 = () => {
+  const { handleStepChange, wizardData } = useWizard<{ name: string }>();
+  return (
+    <input 
+      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 WizardContent = () => {
+  const { currentStep, goToNextStep } = useWizard();
+  if(!currentStep) return null;
+  return (
+    <div>
+      {currentStep.id === 'personal' && <Step1 />}
+      <button onClick={goToNextStep}>Next</button>
+    </div>
+  )
+}
+```
+
+## Integration with React Hook Form + Zod
+
+```tsx
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { z } from 'zod';
+import { ZodAdapter, useWizard } from 'wizzard-stepper-react';
+
+const schema = z.object({ email: z.string().email() });
+
+const MyStep = () => {
+  const { handleStepChange, wizardData } = useWizard();
+  const { register } = useForm({
+    defaultValues: wizardData,
+    resolver: zodResolver(schema),
+    mode: 'onChange' // Important: validate real-time or bind changes
+  });
+
+  return (
+     <input {...register('email', { 
+       onChange: (e) => handleStepChange('email', e.target.value) 
+     })} />
+  );
+}
+
+// In Config:
+const config = {
+  steps: [
+    { 
+      id: 'step1', 
+      label: 'Email', 
+      validationAdapter: new ZodAdapter(schema) // Blocks 'Next' if invalid
+    }
+  ]
+}
+```
+
+## Conditional Steps
+
+Steps can be dynamically included based on the wizard's state.
+
+```tsx
+const config: IWizardConfig = {
+  steps: [
+    { id: 'start', label: 'Start' },
+    { 
+      id: 'bonus', 
+      label: 'Bonus Step', 
+      // Only show if 'wantBonus' is true
+      condition: (data) => !!data.wantBonus 
+    }
+  ]
+}
+```
+
+## Persistence
+
+Save progress automatically to LocalStorage to survive page reloads.
+
+```tsx
+import { LocalStorageAdapter } from 'wizzard-stepper-react';
+
+const config: IWizardConfig = {
+  persistence: {
+    mode: 'onChange', // Save on every keystroke
+    adapter: new LocalStorageAdapter('my_wizard_prefix_')
+  },
+  steps: [...]
+}
+```
+
+## 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.
+- `goToNextStep()`: Validates and moves next.
+- `goToStep(id)`: Jumps to specific step.
+- `allErrors`: Map of validation errors.
+
+## Demos
+
+Check out the [official demo repository](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.
+
+## License
+MIT