@reformer/ui 1.0.0-beta.1

package/dist/form-navigation/index.d.ts

@@ -0,0 +1,12 @@
+export { FormNavigation } from './FormNavigation';
+export { FormNavigationStep } from './FormNavigationStep';
+export { FormNavigationIndicator } from './FormNavigationIndicator';
+export { FormNavigationActions } from './FormNavigationActions';
+export { FormNavigationProgress } from './FormNavigationProgress';
+export { useFormNavigation, FormNavigationContext } from './FormNavigationContext';
+export type { FormNavigationHandle, FormNavigationProps, FormNavigationConfig } from './types';
+export type { FormNavigationStepProps } from './FormNavigationStep';
+export type { FormNavigationContextValue } from './FormNavigationContext';
+export type { FormNavigationIndicatorProps, FormNavigationIndicatorStep, FormNavigationIndicatorStepWithState, FormNavigationIndicatorRenderProps, } from './FormNavigationIndicator';
+export type { FormNavigationActionsProps, FormNavigationActionsRenderProps, FormNavigationButtonProps, FormNavigationSubmitProps, } from './FormNavigationActions';
+export type { FormNavigationProgressProps, FormNavigationProgressRenderProps, } from './FormNavigationProgress';

package/dist/form-navigation/types.d.ts

@@ -0,0 +1,52 @@
+import type { ReactNode } from 'react';
+import type { GroupNodeWithControls, ValidationSchemaFn } from '@reformer/core';
+/**
+ * Configuration for multi-step form navigation
+ * Note: totalSteps is inferred from children count
+ */
+export interface FormNavigationConfig<T extends Record<string, any>> {
+    /** Validation schemas per step (1-based indexing) */
+    stepValidations: Record<number, ValidationSchemaFn<T>>;
+    /** Full validation schema for submit */
+    fullValidation: ValidationSchemaFn<T>;
+}
+/**
+ * Handle for external access to FormNavigation methods via ref
+ */
+export interface FormNavigationHandle<T extends Record<string, any>> {
+    /** Current step (1-based) */
+    currentStep: number;
+    /** Completed steps */
+    completedSteps: number[];
+    /** Validate current step */
+    validateCurrentStep: () => Promise<boolean>;
+    /** Go to next step (with validation) */
+    goToNextStep: () => Promise<boolean>;
+    /** Go to previous step */
+    goToPreviousStep: () => void;
+    /** Go to specific step */
+    goToStep: (step: number) => boolean;
+    /** Submit form (with full validation) */
+    submit: <R>(onSubmit: (values: T) => Promise<R> | R) => Promise<R | null>;
+    /** Is this the first step */
+    isFirstStep: boolean;
+    /** Is this the last step */
+    isLastStep: boolean;
+    /** Is validation in progress */
+    isValidating: boolean;
+}
+/**
+ * Props for FormNavigation component
+ */
+export interface FormNavigationProps<T extends Record<string, any>> {
+    /** Form instance */
+    form: GroupNodeWithControls<T>;
+    /** Step configuration (validation schemas) */
+    config: FormNavigationConfig<T>;
+    /** Children (Step components, Indicator, Actions, Progress, or any ReactNode) */
+    children: ReactNode;
+    /** Callback when step changes */
+    onStepChange?: (step: number) => void;
+    /** Scroll to top on step change */
+    scrollToTop?: boolean;
+}

package/dist/form-navigation.d.ts

@@ -0,0 +1,2 @@
+export * from './form-navigation/index'
+export {}

package/dist/form-navigation.js

@@ -0,0 +1,10 @@
+import { F as i, c as t, e as r, b as s, d as n, a as g, u as m } from "./FormNavigation-3rg4tJyl.js";
+export {
+  i as FormNavigation,
+  t as FormNavigationActions,
+  r as FormNavigationContext,
+  s as FormNavigationIndicator,
+  n as FormNavigationProgress,
+  g as FormNavigationStep,
+  m as useFormNavigation
+};

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { FormArray, FormArrayList, FormArrayAddButton, FormArrayRemoveButton, FormArrayEmpty, FormArrayCount, FormArrayItemIndex, useFormArray, FormArrayContext, FormArrayItemContext, useFormArrayContext, useFormArrayItemContext, } from './form-array';
+export type { FormArrayHandle, FormArrayItem, UseFormArrayReturn, FormArrayRootProps, FormArrayListProps, FormArrayItemRenderProps, FormArrayAddButtonProps, FormArrayRemoveButtonProps, FormArrayEmptyProps, FormArrayCountProps, FormArrayItemIndexProps, FormArrayContextValue, FormArrayItemContextValue, } from './form-array';
+export { FormNavigation, FormNavigationStep, FormNavigationIndicator, FormNavigationActions, FormNavigationProgress, useFormNavigation, FormNavigationContext, } from './form-navigation';
+export type { FormNavigationHandle, FormNavigationProps, FormNavigationConfig, FormNavigationStepProps, FormNavigationContextValue, FormNavigationIndicatorProps, FormNavigationIndicatorStep, FormNavigationIndicatorStepWithState, FormNavigationIndicatorRenderProps, FormNavigationActionsProps, FormNavigationActionsRenderProps, FormNavigationButtonProps, FormNavigationSubmitProps, FormNavigationProgressProps, FormNavigationProgressRenderProps, } from './form-navigation';

package/dist/index.js

@@ -0,0 +1,23 @@
+import { F as o, b as t, g as s, e as m, d as e, h as F, f as i, a as n, c as A, u as y, i as g, j as u } from "./FormArray-K2YVvq1u.js";
+import { F as x, c as N, e as d, b as C, d as I, a as c, u as p } from "./FormNavigation-3rg4tJyl.js";
+export {
+  o as FormArray,
+  t as FormArrayAddButton,
+  s as FormArrayContext,
+  m as FormArrayCount,
+  e as FormArrayEmpty,
+  F as FormArrayItemContext,
+  i as FormArrayItemIndex,
+  n as FormArrayList,
+  A as FormArrayRemoveButton,
+  x as FormNavigation,
+  N as FormNavigationActions,
+  d as FormNavigationContext,
+  C as FormNavigationIndicator,
+  I as FormNavigationProgress,
+  c as FormNavigationStep,
+  y as useFormArray,
+  g as useFormArrayContext,
+  u as useFormArrayItemContext,
+  p as useFormNavigation
+};

package/llms.txt

@@ -0,0 +1,343 @@
+# @reformer/ui - LLM Integration Guide
+
+Headless UI components for @reformer/core forms.
+
+# Overview
+
+`@reformer/ui` provides headless UI components for `@reformer/core` forms.
+
+## Key Concepts
+
+- **Headless**: No default UI or styles - you build the interface
+- **Compound Components**: Composable, declarative API
+- **Render Props**: Children as function for full control
+- **Context-based**: State shared via React Context
+
+## Components
+
+| Component | Purpose |
+|-----------|---------|
+| `FormArray` | Manage dynamic form arrays |
+| `FormNavigation` | Multi-step form wizard |
+
+## Installation
+
+```bash
+npm install @reformer/ui @reformer/core
+```
+
+## Import Patterns
+
+```typescript
+// All components
+import { FormArray, FormNavigation } from '@reformer/ui';
+
+// Tree-shaking (recommended)
+import { FormArray, useFormArray } from '@reformer/ui/form-array';
+import { FormNavigation, useFormNavigation } from '@reformer/ui/form-navigation';
+```
+
+# FormArray
+
+Headless compound component for managing form arrays.
+
+## Basic Usage
+
+```tsx
+import { FormArray } from '@reformer/ui/form-array';
+
+<FormArray.Root control={form.items}>
+  <FormArray.Empty>
+    <p>No items added</p>
+  </FormArray.Empty>
+
+  <FormArray.List>
+    {({ control, index, remove }) => (
+      <div key={control.id}>
+        <h4>Item #{index + 1}</h4>
+        <ItemForm control={control} />
+        <button onClick={remove}>Remove</button>
+      </div>
+    )}
+  </FormArray.List>
+
+  <FormArray.AddButton>Add Item</FormArray.AddButton>
+</FormArray.Root>
+```
+
+## Sub-components
+
+| Component | Props | Purpose |
+|-----------|-------|---------|
+| `FormArray.Root` | `control: ArrayNode<T>` | Context provider |
+| `FormArray.List` | `children: (item) => ReactNode` | Iterates items (render props) |
+| `FormArray.AddButton` | `initialValue?: Partial<T>` | Adds new item |
+| `FormArray.RemoveButton` | - | Removes current item (inside List) |
+| `FormArray.Empty` | `children: ReactNode` | Shows when array is empty |
+| `FormArray.Count` | `render?: (count) => ReactNode` | Displays item count |
+| `FormArray.ItemIndex` | `render?: (index) => ReactNode` | Displays current index |
+
+## List Render Props
+
+```typescript
+interface FormArrayItemRenderProps<T> {
+  control: GroupNodeWithControls<T>;  // Form control for item
+  index: number;                       // Zero-based index
+  id: string | number;                 // Unique key
+  remove: () => void;                  // Remove this item
+}
+```
+
+## External Control via Ref
+
+```tsx
+import { useRef } from 'react';
+import { FormArray, FormArrayHandle } from '@reformer/ui/form-array';
+
+const arrayRef = useRef<FormArrayHandle<ItemType>>(null);
+
+// Control from outside
+arrayRef.current?.add({ name: 'New' });
+arrayRef.current?.removeAt(0);
+arrayRef.current?.clear();
+
+<FormArray.Root ref={arrayRef} control={form.items}>
+  ...
+</FormArray.Root>
+```
+
+## FormArrayHandle API
+
+```typescript
+interface FormArrayHandle<T> {
+  add: (value?: Partial<T>) => void;
+  clear: () => void;
+  insert: (index: number, value?: Partial<T>) => void;
+  removeAt: (index: number) => void;
+  length: number;
+  isEmpty: boolean;
+  at: (index: number) => GroupNodeWithControls<T> | undefined;
+}
+```
+
+## useFormArray Hook
+
+For full customization without compound components:
+
+```tsx
+import { useFormArray } from '@reformer/ui/form-array';
+
+function CustomList() {
+  const { items, add, isEmpty, length } = useFormArray(form.items);
+
+  return (
+    <div>
+      <span>Total: {length}</span>
+      {items.map(({ control, id, remove }) => (
+        <div key={id}>
+          <ItemForm control={control} />
+          <button onClick={remove}>X</button>
+        </div>
+      ))}
+      {isEmpty && <p>Empty</p>}
+      <button onClick={() => add()}>Add</button>
+    </div>
+  );
+}
+```
+
+# FormNavigation
+
+Headless compound component for multi-step form wizards.
+
+## Basic Usage
+
+```tsx
+import { FormNavigation } from '@reformer/ui/form-navigation';
+
+const config = {
+  stepValidations: {
+    1: step1Schema,
+    2: step2Schema,
+  },
+  fullValidation: fullFormSchema,
+};
+
+<FormNavigation form={form} config={config}>
+  <FormNavigation.Step component={Step1Form} control={form} />
+  <FormNavigation.Step component={Step2Form} control={form} />
+
+  <FormNavigation.Actions onSubmit={handleSubmit}>
+    {({ prev, next, submit, isFirstStep, isLastStep }) => (
+      <div>
+        {!isFirstStep && <button {...prev}>Back</button>}
+        {!isLastStep ? (
+          <button {...next}>Next</button>
+        ) : (
+          <button {...submit}>Submit</button>
+        )}
+      </div>
+    )}
+  </FormNavigation.Actions>
+</FormNavigation>
+```
+
+## Sub-components
+
+| Component | Purpose |
+|-----------|---------|
+| `FormNavigation` | Root provider |
+| `FormNavigation.Step` | Renders component when step is current |
+| `FormNavigation.Indicator` | Headless step indicator (render props) |
+| `FormNavigation.Actions` | Headless navigation buttons (render props) |
+| `FormNavigation.Progress` | Headless progress display (render props) |
+
+## FormNavigation.Indicator
+
+```tsx
+<FormNavigation.Indicator steps={STEPS}>
+  {({ steps, goToStep, currentStep }) => (
+    <nav>
+      {steps.map((step) => (
+        <button
+          key={step.number}
+          onClick={() => goToStep(step.number)}
+          disabled={!step.canNavigate}
+          aria-current={step.isCurrent ? 'step' : undefined}
+        >
+          {step.isCompleted ? '✓' : step.number} {step.title}
+        </button>
+      ))}
+    </nav>
+  )}
+</FormNavigation.Indicator>
+```
+
+### Step Definition
+
+```typescript
+interface FormNavigationIndicatorStep {
+  number: number;   // 1-based step number
+  title: string;
+  icon?: string;
+}
+```
+
+### Render Props
+
+```typescript
+interface FormNavigationIndicatorRenderProps {
+  steps: FormNavigationIndicatorStepWithState[];
+  goToStep: (step: number) => boolean;
+  currentStep: number;
+  totalSteps: number;
+  completedSteps: number[];
+}
+
+interface FormNavigationIndicatorStepWithState {
+  number: number;
+  title: string;
+  icon?: string;
+  isCurrent: boolean;
+  isCompleted: boolean;
+  canNavigate: boolean;
+}
+```
+
+## FormNavigation.Actions
+
+```tsx
+<FormNavigation.Actions onSubmit={handleSubmit}>
+  {({ prev, next, submit, isFirstStep, isLastStep, isValidating }) => (
+    <div>
+      {!isFirstStep && (
+        <button onClick={prev.onClick} disabled={prev.disabled}>
+          Back
+        </button>
+      )}
+      {!isLastStep ? (
+        <button onClick={next.onClick} disabled={next.disabled}>
+          {isValidating ? 'Validating...' : 'Next'}
+        </button>
+      ) : (
+        <button onClick={submit.onClick} disabled={submit.disabled}>
+          {submit.isSubmitting ? 'Submitting...' : 'Submit'}
+        </button>
+      )}
+    </div>
+  )}
+</FormNavigation.Actions>
+```
+
+### Render Props
+
+```typescript
+interface FormNavigationActionsRenderProps {
+  prev: { onClick: () => void; disabled: boolean };
+  next: { onClick: () => void; disabled: boolean };
+  submit: { onClick: () => void; disabled: boolean; isSubmitting: boolean };
+  isFirstStep: boolean;
+  isLastStep: boolean;
+  isValidating: boolean;
+  isSubmitting: boolean;
+}
+```
+
+## FormNavigation.Progress
+
+```tsx
+<FormNavigation.Progress>
+  {({ current, total, percent }) => (
+    <div>
+      Step {current} of {total} ({percent}%)
+      <div style={{ width: `${percent}%` }} />
+    </div>
+  )}
+</FormNavigation.Progress>
+```
+
+### Render Props
+
+```typescript
+interface FormNavigationProgressRenderProps {
+  current: number;
+  total: number;
+  percent: number;
+  completedCount: number;
+  isFirstStep: boolean;
+  isLastStep: boolean;
+}
+```
+
+## External Control via Ref
+
+```tsx
+const navRef = useRef<FormNavigationHandle<FormType>>(null);
+
+// Programmatic navigation
+navRef.current?.goToStep(2);
+navRef.current?.goToNextStep();
+navRef.current?.goToPreviousStep();
+
+// Submit with validation
+const result = await navRef.current?.submit(async (values) => {
+  return api.submit(values);
+});
+
+<FormNavigation ref={navRef} form={form} config={config}>
+  ...
+</FormNavigation>
+```
+
+## Configuration
+
+```typescript
+interface FormNavigationConfig<T> {
+  stepValidations: Record<number, ValidationSchemaFn<T>>;
+  fullValidation: ValidationSchemaFn<T>;
+}
+```
+
+Validation happens automatically:
+- On `next.onClick`: validates current step
+- On `submit.onClick`: validates entire form

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@reformer/ui",
+  "version": "1.0.0-beta.1",
+  "description": "Headless UI components for @reformer/core - form arrays, multi-step wizards, and more",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./form-array": {
+      "types": "./dist/form-array.d.ts",
+      "import": "./dist/form-array.js"
+    },
+    "./form-navigation": {
+      "types": "./dist/form-navigation.d.ts",
+      "import": "./dist/form-navigation.js"
+    }
+  },
+  "sideEffects": false,
+  "scripts": {
+    "generate:llms": "npx tsx scripts/generate-llms.ts",
+    "build": "npm run generate:llms && vite build && tsc -p tsconfig.json",
+    "dev": "vite",
+    "test": "vitest",
+    "test:watch": "vitest watch"
+  },
+  "keywords": [
+    "react",
+    "forms",
+    "headless-ui",
+    "compound-components",
+    "form-array",
+    "multi-step-form",
+    "wizard",
+    "reformer",
+    "typescript"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "author": "Alexandr Bukhtatyy",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AlexandrBukhtatyy/ReFormer.git",
+    "directory": "packages/reformer-ui"
+  },
+  "homepage": "https://alexandrbukhtatyy.github.io/ReFormer/",
+  "bugs": {
+    "url": "https://github.com/AlexandrBukhtatyy/ReFormer/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "llms.txt"
+  ],
+  "peerDependencies": {
+    "@reformer/core": "^1.0.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@reformer/core": "*",
+    "@types/node": "^24.10.1",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.0",
+    "@vitest/utils": "^4.0.8",
+    "react": "^19.2.1",
+    "react-dom": "^19.2.1",
+    "tsx": "^4.19.2",
+    "typescript": "^5.9.3",
+    "vite": "^7.2.2",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^4.0.8"
+  }
+}