react-wizard-engine 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# react-wizard-engine
+
+## 0.1.0
+
+### Minor Changes
+
+- f824dd0: Initial release. Extracted from the perks.loca.us monorepo as a standalone package.
+
+  - Framework-agnostic engine (`core/`): steps, categories, branches, pluggable strategies, listeners, initializers, async navigation with cancellation.
+  - Headless React adapter (`react-wizard-engine`): `WizardProvider`, hooks (`useWizard`, `useWizardStep`, `useWizardEvent`), structural components.
+  - Styled adapter (`react-wizard-engine/shadcn`): `WizardTopBar`, `WizardLayout`, opinionated Radix + Tailwind that match shadcn defaults.
+  - Dual ESM + CJS builds, full `.d.ts` types, `"use client"` preserved.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nazarii Kovtun
+
+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,100 @@
+# react-wizard-engine
+
+[![npm version](https://img.shields.io/npm/v/react-wizard-engine.svg)](https://www.npmjs.com/package/react-wizard-engine)
+[![license](https://img.shields.io/npm/l/react-wizard-engine.svg)](https://github.com/knazark/react-wizard-engine/blob/main/LICENSE)
+
+Multi-step flow engine for React. Steps, categories, branches. Pluggable strategies, listeners, initializers. Resolver hooks. Async navigation with cancellation. Headless core plus an opinionated Radix + Tailwind styled adapter.
+
+## Install
+
+```sh
+pnpm add react-wizard-engine lucide-react
+# only if you also use the styled /shadcn adapter:
+pnpm add @radix-ui/react-dialog @radix-ui/react-slot
+```
+
+## Quickstart
+
+```tsx
+import {
+  WizardProvider,
+  WizardCategory,
+  WizardStep,
+  WizardBack,
+  WizardNext,
+} from 'react-wizard-engine';
+
+const initial = [
+  { id: 'name',  categoryId: 'profile', htmlIndex: 0, branches: ['main'], isActive: true,  isShow: true, isCompleted: false, isSkipped: false },
+  { id: 'email', categoryId: 'profile', htmlIndex: 1, branches: ['main'], isActive: false, isShow: true, isCompleted: false, isSkipped: false },
+  { id: 'done',  categoryId: 'confirm', htmlIndex: 2, branches: ['main'], isActive: false, isShow: true, isCompleted: false, isSkipped: false },
+];
+
+export function SignupWizard() {
+  return (
+    <WizardProvider state={initial}>
+      <WizardCategory categoryId="profile">
+        <WizardStep id="name">...name form...</WizardStep>
+        <WizardStep id="email">...email form...</WizardStep>
+      </WizardCategory>
+      <WizardCategory categoryId="confirm">
+        <WizardStep id="done">...review...</WizardStep>
+      </WizardCategory>
+      <WizardBack />
+      <WizardNext />
+    </WizardProvider>
+  );
+}
+```
+
+## Styled adapter
+
+The `/shadcn` subpath ships an opinionated styled `WizardTopBar` and `WizardLayout` built on Radix + Tailwind utility classes that match shadcn defaults.
+
+```tsx
+import { WizardLayout, WizardTopBar, WizardComponentsProviderWithDefaults } from 'react-wizard-engine/shadcn';
+
+<WizardComponentsProviderWithDefaults>
+  <WizardProvider state={initial}>
+    <WizardLayout
+      topBar={<WizardTopBar onClose={onClose} />}
+      rail={<MyRail />}
+    >
+      {/* steps */}
+    </WizardLayout>
+  </WizardProvider>
+</WizardComponentsProviderWithDefaults>
+```
+
+To use your own button:
+
+```tsx
+import { WizardComponentsProvider } from 'react-wizard-engine';
+import { Button } from '@/components/ui/button';
+
+<WizardComponentsProvider Button={Button}>
+  <WizardProvider state={initial}>{}</WizardProvider>
+</WizardComponentsProvider>
+```
+
+## Concepts
+
+- **Step** — one screen the user sees. `id`, `categoryId`, `htmlIndex` (declaration order), `branches[]`, plus four flags (`isActive`/`isShow`/`isCompleted`/`isSkipped`).
+- **Category** — a group of steps sharing a header tab.
+- **Branch** — a named path through categories.
+
+See `src/core/` for full type definitions.
+
+## Hooks
+
+- `useWizard()` — engine: `next`, `back`, `go`, `showStep`, `hideStep`, `goToCategory`, `nextCategory`, `backCategory`, `skipCategory`, `resetWizard`, `exitWizard`, `completeWizard`, snapshot fields `tree` / `steps` / `lastActiveStep` / `shapeId`. All control methods return `Promise<boolean>`.
+- `useWizardStep(id)` — subscribes to one step's slice; re-renders only when its flags flip.
+- `useWizardEvent('*' | type, handler)` — subscribes to engine events.
+
+## Strategies (pluggable)
+
+`composeWizardProviders(withBackStrategy(...), withScrollStrategy(...), ...)`. Back, visibility, progress, and scroll strategies all overridable. See `src/core/strategies/`.
+
+## License
+
+MIT (c) Nazarii Kovtun

package/dist/components-provider-bC3_zfyb.d.cts

@@ -0,0 +1,29 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode, ComponentType } from 'react';
+
+interface IWizardButtonProps {
+    asChild?: boolean;
+    children?: ReactNode;
+    className?: string;
+    disabled?: boolean;
+    onClick?: () => void;
+    type?: 'button' | 'submit';
+    variant?: 'default' | 'ghost';
+    size?: 'default' | 'icon-sm';
+    'aria-label'?: string;
+}
+interface IWizardBackArrowIconProps {
+    className?: string;
+}
+interface IWizardComponents {
+    Button: ComponentType<IWizardButtonProps>;
+    BackArrowIcon: ComponentType<IWizardBackArrowIconProps>;
+}
+declare function WizardComponentsProvider(props: {
+    Button?: ComponentType<IWizardButtonProps>;
+    BackArrowIcon?: ComponentType<IWizardBackArrowIconProps>;
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+declare function useWizardComponents(): IWizardComponents;
+
+export { type IWizardBackArrowIconProps as I, WizardComponentsProvider as W, type IWizardButtonProps as a, type IWizardComponents as b, useWizardComponents as u };

package/dist/components-provider-bC3_zfyb.d.ts

@@ -0,0 +1,29 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode, ComponentType } from 'react';
+
+interface IWizardButtonProps {
+    asChild?: boolean;
+    children?: ReactNode;
+    className?: string;
+    disabled?: boolean;
+    onClick?: () => void;
+    type?: 'button' | 'submit';
+    variant?: 'default' | 'ghost';
+    size?: 'default' | 'icon-sm';
+    'aria-label'?: string;
+}
+interface IWizardBackArrowIconProps {
+    className?: string;
+}
+interface IWizardComponents {
+    Button: ComponentType<IWizardButtonProps>;
+    BackArrowIcon: ComponentType<IWizardBackArrowIconProps>;
+}
+declare function WizardComponentsProvider(props: {
+    Button?: ComponentType<IWizardButtonProps>;
+    BackArrowIcon?: ComponentType<IWizardBackArrowIconProps>;
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+declare function useWizardComponents(): IWizardComponents;
+
+export { type IWizardBackArrowIconProps as I, WizardComponentsProvider as W, type IWizardButtonProps as a, type IWizardComponents as b, useWizardComponents as u };