formstack-ui 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,206 @@
+# Changelog
+
+All notable changes to FormEngine will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [3.1.0] - 2026-01-17
+
+### 🎉 New Features & Breakthroughs
+
+#### **Themed Variant System**
+
+- **Unified Variants**: Full support for `outline`, `filled`, `standard`, and `floating` variants across all input components.
+- **Animated Notches**: Precision-engineered floating labels with a solid background notch effect.
+- **Enhanced Date/Time Pickers**: `DatePicker`, `DateRangePicker`, `DateTimePicker`, and `TimePicker` now support the full variant system natively.
+
+#### **CLI 3.0 Power Tools**
+
+- **Dynamic Package Names**: Users can now specify a custom `packageName` during `init` for highly tailored local installations.
+- **Component Tracking**: The new `r-form.json` config tracks every component installed in `copy` mode.
+- **`update` Command**: Introduced a powerful `update` command to automatically synchronize your local component source files with the latest upstream library versions.
+- **Intelligent Dependency Resolution**: The `add` and `update` commands now recursively manage internal dependencies (like `theme-core` and `date-utils`).
+
+#### **Core Enhancements**
+
+- **Native Implementation**: Fully transitioned from external UI libraries to high-performance, tailored native components for all Date/Time operations.
+- **Floating Labels for Selects**: Integrated floating label animations into `Select` and `Autocomplete` components.
+- **Library Exports**: Expanded the public API to export the complete suite of themed components.
+
+### 🔧 Technical Details
+
+- **Dependencies**: React 19.2, Tailwind CSS 4.1, Zod 4.3, date-fns 4.1.
+- **CLI Utilities**: Chalk, Commander, Execa, Fs-extra, Ora, Prompts.
+
+## [3.0.2] - 2026-01-13
+
+### 🎉 Initial Release
+
+#### Added
+
+**Core Features**
+
+- Schema-driven form rendering with 17 field types
+- Visual form builder with drag-and-drop
+- Comprehensive validation system (20+ validation types)
+- Conditional field visibility with AND/OR rules
+- Responsive 12-column grid layout
+- Dark mode support
+- TypeScript support
+
+**Field Types**
+
+- Text inputs: text, email, url, tel, password
+- Number input with min/max/step
+- Textarea with auto-grow and character count
+- Autocomplete with async support and multi-select
+- Native select with multi-select
+- Checkbox, Switch, Radio groups
+- File upload with preview modes
+- Date/Time pickers (Kendo UI integration)
+
+**Form Builder**
+
+- 60+ configurable properties per field
+- Smart field defaults by type
+- Schema import/export (JSON)
+- Copy to clipboard functionality
+- Real-time preview
+- Organized property panels
+- Icon-only button design
+
+**Validation**
+
+- Required, email, URL validation
+- Min/max length for text
+- Min/max value for numbers
+- Pattern/regex validation
+- File size and type validation
+- Date range validation
+- Custom validation functions
+- Debounced validation
+- Validate on blur/change
+
+**UI/UX**
+
+- Floating labels with notch effect
+- Error tooltips
+- Icon adornments (start/end)
+- Responsive design (mobile/tablet/desktop)
+- Accessibility (ARIA, keyboard navigation)
+- Premium animations and transitions
+
+**States Gallery**
+
+- Component state showcase
+- Smart state filtering by component type
+- Responsive grid layout (4-2-1 columns)
+- All field types with 7 states each
+
+**Developer Experience**
+
+- TypeScript definitions
+- Comprehensive documentation
+- Example schemas
+- Theme customization
+- Zod integration
+
+### 🔧 Technical Details
+
+**Dependencies**
+
+- React 19.2+
+- Tailwind CSS 4.1
+- Zod 4.3+
+- Kendo React UI 13.2 (optional)
+
+**Browser Support**
+
+- Chrome 90+
+- Firefox 88+
+- Safari 14+
+- Edge 90+
+
+### 📚 Documentation
+
+- README with quick start guide
+- API documentation
+- Contributing guidelines
+- MIT License
+- Changelog
+
+---
+
+## [Unreleased]
+
+### Planned Features
+
+- [ ] Multi-step forms/wizard
+- [ ] Form templates library
+- [ ] Advanced file upload (drag-and-drop, crop)
+- [ ] Rich text editor field
+- [ ] Signature pad field
+- [ ] Geolocation field
+- [ ] Rating/star field
+- [ ] Color picker field
+- [ ] Slider/range field
+- [ ] Form analytics
+- [ ] A/B testing support
+- [ ] Internationalization (i18n)
+- [ ] Form versioning
+- [ ] Collaboration features
+- [ ] API integration templates
+- [ ] Webhook support
+- [ ] PDF export
+- [ ] Email notifications
+- [ ] Conditional sections
+- [ ] Repeatable field groups
+- [ ] Calculation fields
+- [ ] Lookup fields
+- [ ] Matrix/grid questions
+
+---
+
+## Version History
+
+- **3.0.2** - Initial public release (2026-01-13)
+
+---
+
+## Migration Guides
+
+### From 2.x to 3.0
+
+No migration needed - this is the initial public release!
+
+---
+
+## Breaking Changes
+
+None yet - this is version 1.0.0!
+
+---
+
+## Deprecations
+
+None yet.
+
+---
+
+## Security
+
+### Reporting Security Issues
+
+Please report security vulnerabilities to adarshatl03@gmail.com
+
+### Security Updates
+
+- All dependencies are kept up-to-date
+- Regular security audits
+- Zod validation prevents injection attacks
+- XSS protection built-in
+
+---
+
+**Note**: For detailed commit history, see [GitHub Releases](https://github.com/yourusername/form-engine/releases)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adarsh
+
+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,341 @@
+# 🚀 FormStack UI
+
+[![npm version](https://img.shields.io/npm/v/formstack-ui.svg)](https://www.npmjs.com/package/formstack-ui)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/)
+[![React](https://img.shields.io/badge/React-19.2-61dafb.svg)](https://reactjs.org/)
+
+**A powerful, schema-driven form engine for React with a visual builder, comprehensive validation, and enterprise-grade features.**
+
+## ✨ Features
+
+### 🎨 **Visual Form Builder**
+
+- Drag-and-drop field arrangement
+- 60+ configurable properties per field
+- Real-time preview
+- Schema import/export (JSON)
+- Smart field defaults
+- **Component Playground**: Interactive gallery for all UI components
+
+### 📝 **17 Field Types**
+
+- Text inputs (text, email, url, tel, password)
+- Number input with constraints
+- Textarea with auto-grow
+- Autocomplete with async support
+- Native select & multi-select
+- Checkbox, Switch, Radio groups
+- File upload with preview
+- Date, Time, DateTime, DateRange pickers (Native components)
+
+### ✅ **Advanced Validation**
+
+- 20+ validation types
+- Zod integration
+- Custom validation functions
+
+## ✨ Features (v3.2.0)
+
+- **Framework Agnostic State**: Choose between Native `useForm`, **Formik**, or **React Hook Form**.
+- **Multi-Validation Support**: First-class support for **Zod** and **Yup**.
+- **Themed Variant System**: Default, Outlined, and Covered variants for all inputs.
+- **Smart CLI 3.0**: Select your stack (`npx formstack-ui init`) and we'll configure your validation and state management automatically.
+- Dark mode support
+- Fully responsive (12-column grid)
+- Tailwind CSS 4.1
+
+### 🛠️ **CLI 3.0 Power Tools**
+
+Detailed instructions can be found in the [CLI Guide](CLI_GUIDE.md).
+
+- **`init`**: Comprehensive setup with custom package name support
+- **`add`**: Install specific components locally with dependency tracking
+- **`update`**: Keep your local components up-to-date with a single command
+- **`create`**: Scaffold a new project from scratch (`npx formstack-ui create`)
+
+### 🌐 **Accessibility**
+
+- ARIA labels
+- Keyboard navigation
+- Screen reader support
+- Semantic HTML
+
+## 📦 Installation
+
+```bash
+npm install formstack-ui
+```
+
+### Peer Dependencies
+
+```bash
+npm install react react-dom tailwindcss zod formik yup
+```
+
+## 🚀 Quick Start
+
+### 1. Basic Form
+
+```tsx
+import { SchemaForm } from "formstack-ui";
+import type { FormSchema } from "formstack-ui";
+
+const schema: FormSchema = {
+  title: "Contact Form",
+  description: "Get in touch with us",
+  fields: [
+    {
+      id: "name",
+      name: "name",
+      label: "Full Name",
+      type: "text",
+      placeholder: "John Doe",
+      validation: [{ type: "required", message: "Name is required" }],
+      grid: { colSpan: 12, xs: 12, sm: 6 },
+    },
+    {
+      id: "email",
+      name: "email",
+      label: "Email",
+      type: "email",
+      placeholder: "john@example.com",
+      validation: [{ type: "required" }, { type: "email", message: "Invalid email" }],
+      grid: { colSpan: 12, xs: 12, sm: 6 },
+    },
+    {
+      id: "message",
+      name: "message",
+      label: "Message",
+      type: "textarea",
+      rows: 4,
+      grid: { colSpan: 12 },
+    },
+  ],
+};
+
+function App() {
+  return (
+    <SchemaForm
+      schema={schema}
+      onSubmit={(values) => {
+        console.log("Form submitted:", values);
+      }}
+    />
+  );
+}
+```
+
+### 2. Form Builder
+
+```tsx
+import { FormBuilder } from "formstack-ui";
+
+function App() {
+  return <FormBuilder />;
+}
+```
+
+### 3. Advanced Features
+
+```tsx
+import { SchemaForm } from "formstack-ui";
+import { useRef } from "react";
+import type { SchemaFormHandle } from "formstack-ui";
+
+function App() {
+  const formRef = useRef<SchemaFormHandle>(null);
+
+  return (
+    <>
+      <SchemaForm
+        ref={formRef}
+        schema={schema}
+        debug // Show debug panel
+        onValidate={(values) => {
+          // Custom cross-field validation
+          const errors: Record<string, string> = {};
+          if (values.password !== values.confirmPassword) {
+            errors.confirmPassword = "Passwords don't match";
+          }
+          return errors;
+        }}
+        onSubmit={(values) => {
+          console.log("Submitted:", values);
+        }}
+      />
+
+      <button onClick={() => formRef.current?.submit()}>Submit Form</button>
+      <button onClick={() => formRef.current?.reset()}>Reset Form</button>
+    </>
+  );
+}
+```
+
+## 📚 Documentation
+
+### Field Types
+
+| Type           | Description       | Special Props                                  |
+| -------------- | ----------------- | ---------------------------------------------- |
+| `text`         | Single-line text  | `minLength`, `maxLength`, `pattern`            |
+| `email`        | Email input       | Auto email validation                          |
+| `url`          | URL input         | Auto URL validation                            |
+| `tel`          | Phone number      | `pattern` for format                           |
+| `password`     | Password input    | Masked input                                   |
+| `number`       | Numeric input     | `min`, `max`, `step`                           |
+| `textarea`     | Multi-line text   | `rows`, `autoGrow`, `showCharCount`            |
+| `autocomplete` | Searchable select | `options`, `multiple`, `asyncUrl`, `creatable` |
+| `select`       | Native select     | `options`, `multiple`                          |
+| `checkbox`     | Checkbox          | `checkboxLabel`                                |
+| `switch`       | Toggle switch     | Boolean value                                  |
+| `radio`        | Radio group       | `options`, `direction`                         |
+| `file`         | File upload       | `accept`, `maxSize`, `maxFiles`                |
+| `date`         | Date picker       | `minDate`, `maxDate`, `dateFormat`             |
+| `time`         | Time picker       | `timeFormat`                                   |
+| `datetime`     | Date + Time       | `dateFormat`, `timeFormat`                     |
+| `daterange`    | Date range        | `minDate`, `maxDate`                           |
+
+### Validation Types
+
+```typescript
+type ValidationRule =
+  | { type: "required"; message?: string }
+  | { type: "email"; message?: string }
+  | { type: "url"; message?: string }
+  | { type: "minLength"; value: number; message?: string }
+  | { type: "maxLength"; value: number; message?: string }
+  | { type: "min"; value: number; message?: string }
+  | { type: "max"; value: number; message?: string }
+  | { type: "pattern"; value: string; message?: string }
+  | { type: "regex"; value: RegExp; message?: string }
+  | { type: "fileSize"; value: number; message?: string }
+  | { type: "fileType"; value: string[]; message?: string }
+  | { type: "minDate"; value: Date; message?: string }
+  | { type: "maxDate"; value: Date; message?: string }
+  | { type: "integer"; message?: string }
+  | { type: "positive"; message?: string }
+  | { type: "negative"; message?: string }
+  | { type: "custom"; validate: (value: any) => boolean; message?: string };
+```
+
+### Conditional Visibility
+
+```typescript
+{
+  id: "other-role",
+  name: "otherRole",
+  label: "Specify Role",
+  type: "text",
+  visibilityRules: [
+    { field: "role", operator: "eq", value: "other" }
+  ],
+  reserveSpace: true // Keeps layout stable
+}
+```
+
+### Grid Layout
+
+```typescript
+{
+  grid: {
+    colSpan: 6,    // Desktop (default)
+    xs: 12,        // Mobile (<640px)
+    sm: 6,         // Tablet (640px+)
+    lg: 4          // Large desktop (1024px+)
+  }
+}
+```
+
+## 🎨 Theming
+
+FormStack UI uses Tailwind CSS 4.1 with CSS variables for theming:
+
+```css
+@theme {
+  --color-primary: oklch(0.6 0.2 250);
+  --color-background: oklch(1 0 0);
+  --color-foreground: oklch(0.2 0 0);
+  /* ... more variables */
+}
+```
+
+Toggle dark mode:
+
+```tsx
+import { ThemeProvider, ThemeSwitcher } from "formstack-ui";
+
+function App() {
+  return (
+    <ThemeProvider defaultTheme="system">
+      <ThemeSwitcher />
+      {/* Your forms */}
+    </ThemeProvider>
+  );
+}
+```
+
+## 🔧 Configuration
+
+### TypeScript
+
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  }
+}
+```
+
+### Tailwind CSS
+
+```js
+// tailwind.config.js
+export default {
+  content: [
+    "./index.html",
+    "./src/**/*.{js,ts,jsx,tsx}",
+    "./node_modules/formstack-ui/**/*.{js,ts,jsx,tsx}",
+  ],
+};
+```
+
+## 📖 Examples
+
+Check out the `/examples` directory for:
+
+- Basic form
+- Multi-step wizard
+- Dynamic fields
+- File upload
+- Async autocomplete
+- Conditional logic
+- Custom validation
+
+## 🤝 Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.
+
+## 📄 License
+
+MIT © Adarsh A
+
+## 🙏 Acknowledgments
+
+- Built with [React](https://reactjs.org/)
+- Styled with [Tailwind CSS](https://tailwindcss.com/)
+- Date pickers powered by Custom Native Components
+- Validation with [Zod](https://zod.dev/)
+
+## 🔗 Links
+
+- [Documentation](https://adarshatl03.github.io/formstack-ui/)
+- [GitHub](https://github.com/adarshatl03/formstack-ui)
+- [NPM](https://www.npmjs.com/package/formstack-ui)
+- [Demo](https://adarshatl03.github.io/formstack-ui/)
+
+---
+
+**Made with ❤️ by the FormStack UI team**