@formitiva/react 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 yanggmtl
+
+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.full.md

@@ -0,0 +1,456 @@
+# Formitiva
+
+> **Build dynamic React forms visually — no JSX, no boilerplate.**
+
+**Formitiva is a dynamic, schema-driven form platform for React, built for visual workflows.**
+
+Design forms using JSON schemas or a visual builder, render them instantly, and scale complex configurable UIs across multiple applications.
+
+✨ Visual Builder included
+✨ Schema-first, no JSX
+✨ Fully extendable (components, themes, validation, i18n)  
+✨ TypeScript-first  
+✨ Optimized for large, dynamic forms
+
+🌐 **Documentation & Demos**  
+- **Doc:** https://formitiva.vercel.app
+- **Playground & Demos:** https://formitiva.vercel.app
+- **Builder:** https://formitiva.vercel.app/builder
+
+![Formitiva Example](https://raw.githubusercontent.com/formitiva/master/docs/assets/images/formitiva_example.gif)
+
+---
+
+## Table of Contents
+
+- [What is Formitiva?](#what-is-formitiva)
+- [Why Formitiva?](#why-formitiva)
+- [Extensibility](#extensibility)
+- [Formitiva Builder](#formitiva-builder)
+- [Key Features](#key-features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Conditional Logic](#conditional-logic)
+- [Validation and Validators](#validation-and-validators)
+- [Documentation](#documentation)
+- [Who Is Formitiva For?](#target-customer)
+- [Roadmap](#roadmap)
+- [Contributing](#contributing)
+- [Learn More](#learn-more)
+- [License](#license)
+
+
+## <a id="what-is-formitiva"></a> 🤔 What is-Formitiva?
+
+Formitiva is not a traditional React form library.
+
+Instead of writing forms in JSX, Formitiva treats forms as data:
+
+- Defined using JSON schemas
+- Stored in databases or CMSs
+- Rendered dynamically at runtime
+- Editable visually by non-developers
+
+This makes Formitiva ideal for applications where forms are configurable, shared, or owned by the backend.
+
+---
+
+## <a id="why-formitiva"></a> 🤔 Why Formitiva?
+
+### Most React form libraries assume:
+
+- The form structure is static
+- Developers write every field in JSX
+- Changes require code edits and redeploys
+
+### Formitiva is built for cases where forms are:
+- Generated from backend data
+- Configurable at runtime
+- Built visually (low-code / no-code)
+- Shared across multiple apps
+- Highly customizable and themeable
+
+### Comparison
+⚠️ Important context
+
+Not all form libraries solve the same problem.
+
+Libraries like React Hook Form, Formik, and Final Form are code-first form state managers.
+They assume forms are authored in JSX at build time.
+
+Formitiva belongs to a different category:
+👉 schema-driven, runtime-configurable form engines.
+
+Formitiva vs Schema-Driven Form Libraries
+| Feature	| Formitiva	| RJSF	| JSON Forms	| Uniforms	| Form.io |
+|------|------|------|------|------|------|
+| Form definition	| Custom JSON schema	| JSON Schema	| JSON Schema + UI schema	| Multiple schemas	| Platform schema | 
+| JSX required	| ❌	| ❌	| ❌	| ❌	| ❌  |
+| Runtime-configurable	| ✔	| ⚠️	| ⚠️	| ⚠️	| ✔ |
+| Conditional logic	| ✔ Native	| ⚠️	| ⚠️	| ⚠️	| ✔ |
+| Visual builder	| ✔	| ❌	| ❌	| ❌	| ✔ |
+| Backend-driven forms	| ✔ First-class	| ⚠️	| ⚠️	| ⚠️	| ✔ |
+| Plugin architecture	| ✔	| ⚠️	| ⚠️	| ✔	| ✔ |
+| Built-in theming	| ✔	| ⚠️	| ✔	| ⚠️	| ✔ |
+| Low-code friendly	| ✔	| ❌	| ❌	| ❌	| ✔ |
+
+---
+
+## <a id="extensibility"></a> 🏗 Extensibility
+
+Formitiva is designed as an extendable platform, not just a renderer.
+
+| Area                        | Support                                    |
+| --------------------------- | ------------------------------------------ |
+| Field components            | ✔ Custom components                        |
+| Layout & grouping           | ✔ Groups, sections (more planned)          |
+| Validation logic            | ✔ Field, form, and field-type validators   |
+| Submission workflows        | ✔ Pluggable submission handlers            |
+| Themes                      | ✔ CSS-variable-based theme registry        |
+| Internationalization (i18n) | ✔ Custom dictionaries & per-form overrides |
+| Schema model                | ✔ Custom field types & metadata            |
+
+---
+
+## <a id="formitiva-builder"></a> 🏗 Formitiva Builder
+
+Formitiva includes a drag-and-drop visual builder:
+
+- Build forms visually
+- Configure validation & conditional logic
+- Preview instantly
+- Export production-ready JSON schemas
+
+<img src="./docs/assets/images/form_builder_ui.png" alt="Formitiva Builder Screenshot" width="900" style="max-width:80%;height:auto;display:block;margin:0.5rem auto;" />
+👉 https://formitiva.vercel.app/builder
+
+## <a id="key-features"></a> ✨ Key Features
+
+### 🔧 Core Concepts
+| Concept | Description |
+|------|------|
+| Schema-driven | Forms are defined using JSON, not JSX |
+| Runtime rendering | Forms can change without redeploying  |
+| Visual-first  | Optional drag-and-drop builder  |
+| Extendable  | Components, themes, validation, and i18n are pluggable  |
+| Backend-friendly  | Schemas can live in APIs or databases |
+
+### 🎨 Theming
+- CSS-variable-based themes
+- Light & dark modes
+- 20+ built-in themes
+
+### 🧠 Logic & Validation
+- Conditional visibility
+- Custom validators
+- Custom submission handlers
+
+### 🔌 Extensibility
+- Component registry
+- Plugin system
+- Custom fields and workflows
+
+### 🌍 i18n
+- Built-in multi-language support
+- Per-form/Per-app translation dictionaries
+- Translation caching
+
+### ⚡ Performance & Accessibility
+- Incremental (chunked) mounting.
+- Efficient updates using requestAnimationFrame batching and targeted visibility recomputation.
+- Reduced input overhead with debounced callbacks for expensive handlers.
+- ARIA-compliant by default
+
+---
+
+## <a id="installation"></a> 📦 Installation
+
+```bash
+npm install formitiva
+```
+
+**Peer Dependencies**
+- React ^18 || ^19
+- React-DOM ^18 || ^19
+
+---
+
+## <a id="quick-start"></a> 🚀 Quick Start
+
+```tsx
+import { Formitiva } from 'formitiva';
+
+const definition = {
+  name: "simpleForm",
+  displayName: "Simple Form",
+  properties: [
+    { name: "email", type: "email", required: true }
+  ]
+};
+
+export default function App() {
+  return <Formitiva definitionData={definition} />;
+}
+```
+
+## <a id="conditional-logic"></a> 🎭 Conditional Logic
+
+Dynamically show or hide individual fields or groups based on parent–child rules or group conditions.
+
+Parent–child example (schema fragment):
+Parents are defined in the parents field by specifying the parent field name and the corresponding values.
+
+```json
+{
+  "properties": [
+    {
+      "name": "country",
+      "displayName": "Country",
+      "type": "dropdown",
+      "options": [
+        { "label": "United States", "value": "US" },
+        { "label": "Canada", "value": "CA" }
+      ]
+    },
+    {
+      "name": "state",
+      "displayName": "State",
+      "type": "dropdown",
+      "parents": { "country": ["US"] }
+    },
+    {
+      "name": "province",
+      "displayName": "Province",
+      "type": "dropdown",
+      "parents": { "country": ["CA"] }
+    }
+  ]
+}
+```
+
+### Group support
+
+Groups let you treat multiple fields as a unit and control the group's visibility with group name defined in field. Consecutive fields with same group name will be grouped while non consecutive fields with same group name are treated as different groups.
+
+Example — `Address` group contains `address1` and `address2` 
+
+```json
+{
+  {
+    "type": "text",
+    "name": "address1",
+    "displayName": "Address Line 1",
+    "defaultValue": "",
+    "group": "Address"
+  },
+  {
+    "type": "text",
+    "name": "address2",
+    "displayName": "Address Line 2",
+    "defaultValue": "",
+    "group": "Address"
+  }
+}
+```
+
+---
+
+## <a id="validation-and-validators"></a> 🔒 Validation and Validators
+
+Formitiva supports both field-level and form-level validation.
+
+- Field-level: validation for a single field; can happen while editing, on blur, or on submission.
+- Form-level: cross-field validation performed during submission.
+
+### Field validation modes
+
+`FieldValidationMode`:
+- `onEdit`: Runs validation while the user edits a field.
+- `onBlur`: Runs validation when the field loses focus.
+- `onSubmission`: Runs validation only when the form is submitted.
+- `realTime`: Deprecated. Same behavior as `onEdit`.
+
+### Validators
+
+- Field custom validator — register a handler for individual-field logic.
+- Form custom validator — register a handler for cross-field logic (runs during submission).
+- Field type validator — define validation for a custom field/component type.
+---
+
+## Submission Handler
+
+Formitiva provide two ways for submission process:
+
+- Direct submission callback in Formitiva props
+- Since Formitiva is a dynamic form system, it provides a registration submission mechanism that allows you to define and plug in custom submission logic. This can provide you flexible submission process for different submission logics.
+
+Note: In bubmission proces, onSubmit callback will be used if it is provided. Otherwise if submissionHandler in defintion is spcified, the registration handler will be invoked.
+
+**How It Works**
+
+### Direct submission callback
+
+```ts
+async function submitFunction(definition, instanceName, valuesMap, t) => {
+  // send valuesMap to your API
+  const res = await fetch('/api/save', { method: 'POST', body: JSON.stringify(valuesMap), headers: { 'Content-Type': 'application/json' } });
+  if (!res.ok) return [t('Server error while submitting form')];
+  return undefined; // returning undefined (or falsy) means success
+});
+```
+
+Then in your app, when call Formitiva, pass submitFunction to onSubmit:
+```ts
+  <Formitiva
+    definition={userDefintion}
+    onSubmit= {submitFunction}
+  />
+```
+
+### Submission registration handling is configured in two steps:
+
+1. Define and Register a Submission Handler
+
+```ts
+import { registerSubmissionHandler } from 'formitiva';
+
+registerSubmissionHandler('api:saveForm', async (definition, instanceName, valuesMap, t) => {
+  // send valuesMap to your API
+  const res = await fetch('/api/save', { method: 'POST', body: JSON.stringify(valuesMap), headers: { 'Content-Type': 'application/json' } });
+  if (!res.ok) return [t('Server error while submitting form')];
+  return undefined; // returning undefined (or falsy) means success
+});
+```
+
+2. Reference the Registered Handler in the Form Definition
+
+    Schema example (Reference a registered handler using the submitHandlerName property):
+
+```json
+{
+  "name": "contactForm",
+  "version": "1.0",
+  "displayName": "Contact",
+  "submitHandlerName": "api:saveForm",
+  "properties": [ /* ... */ ]
+}
+```
+
+## <a id="documentation"></a> 📚 Documentation
+
+👉 https://formitiva.vercel.app/docs
+
+---
+
+## 👥 <a id="target-customer"></a>Who Is Formitiva For?
+
+- SaaS settings pages
+- Admin dashboards
+- Product configurators
+- CMS-driven forms
+- Low-code tools
+- Enterprise dynamic UIs
+
+---
+
+## <a id="roadmap"></a> 🗺️ Roadmap
+Status Legend:
+- 🟢 Current — available or actively shipping
+- 🔵 Planned — designed and scheduled
+- 🟡 Experimental — under research or prototyping
+
+### Core & Standards
+- 🟡 Accessibility certification (WCAG 2.2 AA)
+- 🔵 Performance & accessibility audit tooling
+- 🔵 Schema versioning & migration tools
+- 🔵 Backward-compatible schema evolution
+- 🔵 Form definition linting & diagnostics
+- 🔵 Runtime schema validation & error reporting
+
+### Conditional Logic
+- 🟢 Parent–child conditional visibility
+- 🟢 Field grouping
+- 🔵 Logical operators (AND / OR / NOT)
+- 🔵 Multi-field conditions
+- 🔵 Expression-based rules
+
+### Layout & Structure
+- 🟢 Collapsible sections - Group
+- 🔵 Multi-step / wizard forms
+- 🔵 Tabbed layouts
+- 🔵 Navigation sections / anchors
+- 🔵 Grid & column layouts
+
+### Visual Builders
+- 🟢 Drag-and-drop form builder
+- 🔵 Advanced conditional logic editor
+- 🔵 Validation rule designer
+- 🔵 Submission workflow editor
+- 🔵 Layout editor (nav, tabs, steps, groups)
+- 🔵 Schema version history & rollback
+- 🟡 Builder extensibility API
+
+### Theme System
+- 🟢 CSS-variable-based theming
+- 🟢 Light & dark mode support
+- 🟢 Per-form theme customization
+- 🔵 Visual theme builder
+- 🔵 CSS variable editor
+- 🔵 Exportable & versioned theme packages
+- 🔵 Tailwind-compatible themes
+
+### Plugin System
+- 🟢 Component registry
+- 🟢 Submission handler registration
+- 🟢 Validation handler registrytion
+- 🔵 Plugin scaffolding CLI
+- 🔵 Custom field plugin builder
+- 🔵 Validator plugin builder
+- 🔵 Submission handler plugins
+
+Internationalization (i18n)
+
+Current: built-in i18n with per-form dictionaries
+- 🟢 Built-in i18n support
+- 🟢 Per-form translation dictionaries
+- 🔵 Visual translation editor
+- 🔵 Translation key discovery
+- 🔵 Missing translation detection
+- 🔵 Locale fallback strategies
+- 🟡 Async translation loaders
+
+### Ecosystem & Marketplace
+- 🟡 Definition templates (community-driven)
+- 🟡 Plugin marketplace (community-driven)
+- 🟡 Theme sharing & presets gallery
+- 🟡 Official plugin & theme collections
+
+### Enterprise
+- 🔵 Form analytics & submission insights
+- 🔵 Role-based builder permissions
+- 🔵 Hosted schema & asset management
+- 🔵 Enterprise integrations
+
+---
+
+## <a id="contributing"></a> 🤝 Contributing
+
+Contributions are welcome!  
+Open an issue or submit a pull request.
+
+---
+
+## <a id="learn-more"></a> 📘 Learn more
+
+- [Full README](https://github.com/formitiva/blob/master/README.full.md) 
+- [Formitiva Official Site](http://formitiva.vercel.app)
+- [Documentation](https://formitiva.vercel.app/docs)
+- [Demos](http://formitiva.vercel.app/features#Demos)
+- [Visual Builder](https://formitiva.vercel.app/builder)
+- [Examples](https://github.com/formitiva/tree/master/examples)
+
+---
+
+## <a id="license"></a> 📄 License
+
+MIT

package/README.md

@@ -0,0 +1,114 @@
+# Formitiva
+
+Build dynamic React forms visually ??no JSX, no boilerplate.
+
+Formitiva is a schema-driven, extendable form platform for React. Define forms as JSON (or visually), render them at runtime, and scale complex, configurable UIs without rewriting JSX.
+
+- Visual Form Builder
+- Forms as data (JSON, not JSX)
+- Fully extendable (components, themes, validation, i18n)
+- TypeScript-first
+- Optimized for large, dynamic forms
+
+![Formitiva Example](https://raw.githubusercontent.com/Formitiva/react/master/docs/assets/images/formitiva_example.gif)
+
+## Why Formitiva?
+
+Most React form libraries are code-first:
+
+- Forms are written in JSX
+- Changes require code edits and redeploys
+
+Formitiva is different:
+
+- Forms are schema-driven
+- Stored in APIs, databases, or CMSs
+- Editable visually (low-code / no-code)
+- Rendered dynamically at runtime
+
+If your forms change often or are backend-owned, Formitiva fits naturally.
+
+## Use Cases
+
+- SaaS settings & configuration pages
+- Admin dashboards
+- CMS-driven forms
+- Product configurators
+- Low-code / no-code platforms
+- Enterprise dynamic UIs
+
+## Quick example
+
+```tsx
+import { Formitiva } from 'formitiva';
+
+const definition = {
+  name: 'contactForm',
+  displayName: 'Contact',
+  properties: [
+    { name: 'email', type: 'email', required: true }
+  ]
+};
+
+export default function App() {
+  return <Formitiva definitionData={definition} />;
+}
+```
+
+No JSX fields. No wiring. Just render.
+
+## Key features
+
+- Schema-driven rendering (JSON, not JSX)
+- Visual drag-and-drop form builder
+- Runtime-configurable forms
+- Conditional logic & grouping
+- Pluggable validation & submission
+- Themeable via CSS variables
+- Built-in i18n
+- High-performance rendering
+- ARIA-compliant by default
+
+## Extensible by design
+
+Formitiva is a platform, not just a renderer. You can extend:
+
+- Field components
+- Validation logic (field, form, type)
+- Submission workflows
+- Themes & design systems
+- Languages & translations
+- Custom field types & metadata
+
+No forks. No hacks.
+
+## How it compares
+
+- Formik / React Hook Form ??code-first, JSX-based
+- Formitiva ??schema-first, runtime-driven
+
+Formitiva doesn��t replace form state libraries ??it replaces hand-coding forms when forms are dynamic.
+
+## Installation
+
+```bash
+npm install formitiva
+```
+
+### Peer dependencies
+
+- React ^18 || ^19
+- React DOM ^18 || ^19
+
+## Learn more
+
+- [Full README](https://github.com/Formitiva/react/blob/master/README.full.md) 
+- [Formitiva Official Site](http://formitiva.vercel.app)
+- [Documentation](https://formitiva.vercel.app/docs)
+- [Demos](http://formitiva.vercel.app/features#Demos)
+- [Visual Builder](https://formitiva.vercel.app/builder)
+- [Examples](https://github.com/formitiva/react/tree/master/examples)
+
+## License
+
+MIT

package/dist/components/fields/advanced/ColorInput.d.ts

@@ -0,0 +1,5 @@
+import * as React from "react";
+import type { BaseInputProps, DefinitionPropertyField } from "../../../core/formitivaTypes";
+export type ColorInputProps = BaseInputProps<string, DefinitionPropertyField>;
+declare const _default: React.NamedExoticComponent<ColorInputProps>;
+export default _default;

package/dist/components/fields/advanced/EmailInput.d.ts

@@ -0,0 +1,6 @@
+import * as React from "react";
+import type { DefinitionPropertyField, BaseInputProps } from "../../../core/formitivaTypes";
+export type EmailInputProps = BaseInputProps<string, DefinitionPropertyField>;
+export declare const EmailInput: React.FC<EmailInputProps>;
+declare const _default: React.NamedExoticComponent<EmailInputProps>;
+export default _default;

package/dist/components/fields/advanced/FileInput.d.ts

@@ -0,0 +1,5 @@
+import * as React from "react";
+import type { BaseInputProps, DefinitionPropertyField } from "../../../core/formitivaTypes";
+export type FileInputProps = BaseInputProps<File | File[] | null, DefinitionPropertyField>;
+declare const _default: React.NamedExoticComponent<FileInputProps>;
+export default _default;

package/dist/components/fields/advanced/PasswordInput.d.ts

@@ -0,0 +1,6 @@
+import * as React from "react";
+import type { DefinitionPropertyField } from "../../../core/formitivaTypes";
+import type { BaseInputProps } from "../../../core/formitivaTypes";
+type PasswordInputProps = BaseInputProps<string, DefinitionPropertyField>;
+declare const _default: React.NamedExoticComponent<PasswordInputProps>;
+export default _default;

package/dist/components/fields/advanced/PhoneInput.d.ts

@@ -0,0 +1,7 @@
+import * as React from "react";
+import type { DefinitionPropertyField } from "../../../core/formitivaTypes";
+import type { BaseInputProps } from "../../../core/formitivaTypes";
+export type PhoneInputProps = BaseInputProps<string, DefinitionPropertyField>;
+export declare const PhoneInput: React.FC<PhoneInputProps>;
+declare const _default: React.NamedExoticComponent<PhoneInputProps>;
+export default _default;

package/dist/components/fields/advanced/RatingInput.d.ts

@@ -0,0 +1,9 @@
+import * as React from "react";
+import type { BaseInputProps, DefinitionPropertyField } from "../../../core/formitivaTypes";
+type RatingField = DefinitionPropertyField & {
+    max?: number;
+    icon?: string;
+};
+export type RatingInputProps = BaseInputProps<number, RatingField>;
+declare const _default: React.NamedExoticComponent<RatingInputProps>;
+export default _default;

package/dist/components/fields/advanced/SliderInput.d.ts

@@ -0,0 +1,5 @@
+import * as React from "react";
+import type { BaseInputProps, DefinitionPropertyField } from "../../../core/formitivaTypes";
+type SliderInputProps = BaseInputProps<string | number, DefinitionPropertyField>;
+declare const _default: React.NamedExoticComponent<SliderInputProps>;
+export default _default;

package/dist/components/fields/advanced/UnitValueInput.d.ts

@@ -0,0 +1,5 @@
+import * as React from "react";
+import type { BaseInputProps, DefinitionPropertyField } from "../../../core/formitivaTypes";
+type UnitValueInputProps = BaseInputProps<[string | number, string], DefinitionPropertyField>;
+declare const _default: React.NamedExoticComponent<UnitValueInputProps>;
+export default _default;

package/dist/components/fields/advanced/UrlInput.d.ts

@@ -0,0 +1,9 @@
+import * as React from "react";
+import type { DefinitionPropertyField } from "../../../core/formitivaTypes";
+import type { BaseInputProps } from "../../../core/formitivaTypes";
+/**
+ * UrlInput component
+ */
+export type UrlInputProps = BaseInputProps<string, DefinitionPropertyField>;
+declare const _default: React.NamedExoticComponent<UrlInputProps>;
+export default _default;

package/dist/components/fields/base/PopupOptionMenu.d.ts

@@ -0,0 +1,16 @@
+import * as React from "react";
+export type PopupOptionMenuPosition = {
+    x: number;
+    y: number;
+};
+export interface PopupOption {
+    label: string;
+}
+export interface PopupOptionMenuProps<T extends PopupOption> {
+    pos: PopupOptionMenuPosition | null;
+    options: T[];
+    onClose: () => void;
+    onClickOption: (option: T) => void;
+}
+export declare function PopupOptionMenu<T extends PopupOption>({ pos, options, onClose, onClickOption }: PopupOptionMenuProps<T>): React.ReactPortal | null;
+export default PopupOptionMenu;

package/dist/components/fields/base/Tooltip.d.ts

@@ -0,0 +1,8 @@
+import * as React from "react";
+type TooltipProps = {
+    content: string;
+    size?: "small" | "medium" | "large";
+    animation?: boolean;
+};
+declare const Tooltip: React.FC<TooltipProps>;
+export default Tooltip;