{"id":29584336,"url":"https://github.com/xraph/smartform","last_synced_at":"2025-07-20T00:33:10.368Z","repository":{"id":287284074,"uuid":"964224752","full_name":"xraph/smartform","owner":"xraph","description":null,"archived":false,"fork":false,"pushed_at":"2025-05-29T15:27:53.000Z","size":532,"stargazers_count":4,"open_issues_count":8,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-06T17:17:51.418Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xraph.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-10T22:04:54.000Z","updated_at":"2025-07-04T14:55:17.000Z","dependencies_parsed_at":"2025-04-10T23:24:07.438Z","dependency_job_id":"2dee6008-e45d-4f66-a9bf-6dee48c63f87","html_url":"https://github.com/xraph/smartform","commit_stats":null,"previous_names":["juicycleff/smartform","xraph/smartform"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/xraph/smartform","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xraph%2Fsmartform","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xraph%2Fsmartform/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xraph%2Fsmartform/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xraph%2Fsmartform/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xraph","download_url":"https://codeload.github.com/xraph/smartform/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xraph%2Fsmartform/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264764086,"owners_count":23660323,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-20T00:33:08.979Z","updated_at":"2025-07-20T00:33:10.328Z","avatar_url":"https://github.com/xraph.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SmartForm\n\nSmartForm is a powerful, flexible, and performance-optimized dynamic form framework for building complex, interactive forms with conditional logic, field dependencies, and advanced validation. Built with Go on the backend and React/TypeScript for the frontend, SmartForm provides a comprehensive solution for creating sophisticated form experiences without writing custom code.\n\n[![Go Reference](https://pkg.go.dev/badge/github.com/juicycleff/smartform/v1.svg)](https://pkg.go.dev/github.com/juicycleff/smartform/v1)\n[![Go Report Card](https://goreportcard.com/badge/github.com/juicycleff/smartform/v1)](https://goreportcard.com/report/github.com/juicycleff/smartform/v1)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n\n## Features\n\n- **Fluent Builder API**: Construct complex forms with an intuitive, chainable API\n- **Conditional Rendering**: Show or hide fields based on values of other fields\n- **Dynamic Field Enablement**: Enable or disable fields conditionally\n- **Advanced Validation**: Built-in and custom validation rules with dependency support\n- **Dynamic Options**: Load options from API endpoints or custom functions\n- **Field Dependencies**: Create cascading select fields and other dependent fields\n- **Rich Field Types**: Support for over 25 field types, from basic inputs to complex components\n- **Form Grouping**: Organize forms with nested fields, arrays, and conditional branches\n- **Authentication Integration**: Built-in support for various auth strategies\n- **API Integration**: Connect forms directly to API endpoints\n- **Extensible Architecture**: Add custom field types, validation rules, and functions\n- **Performance Optimized**: Efficient rendering and validation with proper caching\n\n## Structure\n\n- Go library (root): Main Go package\n- `frontend/core`: TypeScript core library\n- `frontend/react`: React components library\n\n\n## Installation\n\n### Backend (Go)\n\n```bash\ngo get github.com/juicycleff/smartform/v1\n```\n\n### Frontend (React/TypeScript)\n\n```bash\nnpm install @xraph/smartform-react\n# or\nyarn add @xraph/smartform-react\n```\n\n## Quick Start\n\n### Backend (Go)\n\n```go\npackage main\n\nimport (\n\t\"net/http\"\n\n\t\"github.com/juicycleff/smartform/v1\"\n)\n\nfunc main() {\n\t// Create an API handler\n\thandler := smartform.NewAPIHandler()\n\n\t// Create a simple contact form\n\tcontactForm := smartform.NewForm(\"contact\", \"Contact Us\")\n\t\t.Description(\"Send us your questions or feedback\")\n\t\t.TextField(\"name\", \"Your Name\")\n\t\t\t.Required(true)\n\t\t\t.Placeholder(\"John Doe\")\n\t\t\t.Build()\n\t\t.EmailField(\"email\", \"Email Address\")\n\t\t\t.Required(true)\n\t\t\t.ValidateEmail(\"Please enter a valid email address\")\n\t\t\t.Build()\n\t\t.TextareaField(\"message\", \"Message\")\n\t\t\t.Required(true)\n\t\t\t.ValidateMinLength(10, \"Message must be at least 10 characters long\")\n\t\t\t.Build()\n\t\t.Build()\n\n\t// Register the form props\n\thandler.RegisterSchema(contactForm)\n\n\t// Set up routes\n\tmux := http.NewServeMux()\n\thandler.SetupRoutes(mux)\n\n\t// Start the server\n\thttp.ListenAndServe(\":8080\", mux)\n}\n```\n\n### Frontend (React/TypeScript)\n\n```tsx\nimport React, { useState, useEffect } from 'react';\nimport { SmartForm, useSmartForm } from '@xraph/smartform-react';\n\nfunction ContactFormPage() {\n  const [formSchema, setFormSchema] = useState(null);\n  const { formState, errors, handleSubmit } = useSmartForm();\n\n  useEffect(() =\u003e {\n    // Fetch the form props from the server\n    fetch('/api/forms/contact')\n      .then(res =\u003e res.json())\n      .then(props =\u003e setFormSchema(props));\n  }, []);\n\n  const onSubmit = async (data) =\u003e {\n    // Submit the form data to the server\n    const response = await fetch('/api/submit/contact', {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/json' },\n      body: JSON.stringify(data)\n    });\n    \n    const result = await response.json();\n    console.log(result);\n  };\n\n  if (!formSchema) return \u003cdiv\u003eLoading form...\u003c/div\u003e;\n\n  return (\n    \u003cdiv className=\"container\"\u003e\n      \u003ch1\u003eContact Us\u003c/h1\u003e\n      \u003cSmartForm \n        props={formSchema} \n        onSubmit={handleSubmit(onSubmit)} \n        errors={errors}\n      /\u003e\n    \u003c/div\u003e\n  );\n}\n\nexport default ContactFormPage;\n```\n\n## Core Concepts\n\n### Form Schema\n\nA form props defines the structure and behavior of a form, including its fields, validation rules, and conditional logic.\n\n### Fields\n\nFields are the building blocks of forms. SmartForm provides a wide variety of field types:\n\n- Basic fields: text, textarea, number, email, password, etc.\n- Selection fields: select, multiselect, checkbox, radio, switch, etc.\n- Date/time fields: date, time, datetime\n- Media fields: file, image\n- Complex fields: group, array, oneOf, anyOf\n- Special fields: rich text, color picker, rating, slider\n- Integration fields: API, authentication, workflow branches\n- Layout fields: section, hidden\n- Custom fields: extend with your own components\n\n### Conditions\n\nConditions control the visibility and enablement of fields based on the values of other fields or custom expressions.\n\n### Validation\n\nValidation rules ensure data integrity and provide immediate feedback to users.\n\n### Options\n\nOptions define the available choices for selection fields, with support for static, dynamic, and dependent options.\n\n## Examples\n\n### Conditional Form\n\n```go\n// Create a form with conditional fields\nregistrationForm := smartform.NewForm(\"registration\", \"Registration Form\")\n    .TextField(\"name\", \"Full Name\")\n        .Required(true)\n        .Build()\n    .EmailField(\"email\", \"Email Address\")\n        .Required(true)\n        .ValidateEmail(\"Please enter a valid email address\")\n        .Build()\n    .RadioField(\"accountType\", \"Account Type\")\n        .Required(true)\n        .AddOption(\"personal\", \"Personal Account\")\n        .AddOption(\"business\", \"Business Account\")\n        .Build()\n    .TextField(\"companyName\", \"Company Name\")\n        .VisibleWhenEquals(\"accountType\", \"business\")\n        .Required(true)\n        .Build()\n    .TextField(\"taxId\", \"Tax ID\")\n        .VisibleWhenEquals(\"accountType\", \"business\")\n        .Build()\n    .Build()\n```\n\n### Dynamic Options\n\n```go\n// Create a form with dynamic dependent options\naddressForm := smartform.NewForm(\"address\", \"Address Information\")\n    .SelectField(\"country\", \"Country\")\n        .Required(true)\n        .WithOptionsFromAPI(\"/api/countries\", \"GET\", \"id\", \"name\")\n        .Build()\n    .SelectField(\"state\", \"State/Province\")\n        .Required(true)\n        .WithOptionsFromAPI(\"/api/states/${country}\", \"GET\", \"id\", \"name\")\n        .WithOptionsRefreshingOn(\"country\")\n        .Build()\n    .SelectField(\"city\", \"City\")\n        .Required(true)\n        .WithOptionsFromAPI(\"/api/cities/${state}\", \"GET\", \"id\", \"name\")\n        .WithOptionsRefreshingOn(\"state\")\n        .Build()\n    .Build()\n```\n\n### Advanced Validation\n\n```go\n// Create a form with advanced validation\npaymentForm := smartform.NewForm(\"payment\", \"Payment Information\")\n    .TextField(\"cardNumber\", \"Card Number\")\n        .Required(true)\n        .ValidatePattern(\"^[0-9]{16}$\", \"Card number must be 16 digits\")\n        .Formatter(\"formatCardNumber\")\n            .WithArgument(\"format\", \"xxxx-xxxx-xxxx-xxxx\")\n            .End()\n        .Build()\n    .TextField(\"cardHolder\", \"Cardholder Name\")\n        .Required(true)\n        .Build()\n    .TextField(\"expiryMonth\", \"Expiry Month (MM)\")\n        .Required(true)\n        .ValidatePattern(\"^(0[1-9]|1[0-2])$\", \"Month must be between 01-12\")\n        .Build()\n    .TextField(\"expiryYear\", \"Expiry Year (YY)\")\n        .Required(true)\n        .ValidatePattern(\"^[0-9]{2}$\", \"Year must be 2 digits\")\n        .Build()\n    .TextField(\"cvv\", \"CVV\")\n        .Required(true)\n        .ValidatePattern(\"^[0-9]{3,4}$\", \"CVV must be 3 or 4 digits\")\n        .Build()\n    .DynamicValidation(\"validateExpiry\", \"Card is expired\")\n        .WithArgument(\"month\", \"${expiryMonth}\")\n        .WithArgument(\"year\", \"${expiryYear}\")\n        .End()\n    .Build()\n```\n\n## API Documentation\n\nFor detailed API documentation, please refer to the [official documentation](https://github.com/juicycleff/smartform/v1/docs).\n\n\n### TypeScript Core\n\n```bash\n# Install the core library\nnpm install @xraph/smartform-core\n```\n\n### React Components\n\n```bash\n# Install the React library\nnpm install @xraph/smartform-react\n```\n\n## Development\n\n### Prerequisites\n\n- Go 1.20 or higher\n- Node.js 18 or higher\n- npm or yarn\n\n### Setup\n\n1. Clone the repository\n2. Install Go dependencies: `go mod download`\n3. Install frontend dependencies:\n   - `cd frontend/core \u0026\u0026 npm install`\n   - `cd frontend/react \u0026\u0026 npm install`\n\n### Build\n\n- Go: `make build`\n- TypeScript Core: `cd frontend/core \u0026\u0026 npm run build`\n- React: `cd frontend/react \u0026\u0026 npm run build`\n\n### Test\n\n- Go: `make test`\n- TypeScript Core: `cd frontend/core \u0026\u0026 npm test`\n- React: `cd frontend/react \u0026\u0026 npm test`\n\n\n\n## Releasing\n\nThis project uses GitHub Actions for releases:\n\n1. Update version numbers in Go code and package.json files\n2. Create and push a new tag: `git tag v1.0.0 \u0026\u0026 git push origin v1.0.0`\n3. GitHub Actions will automatically:\n   - Create a GitHub release with Go binaries\n   - Publish the TypeScript and React packages to npm\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxraph%2Fsmartform","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxraph%2Fsmartform","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxraph%2Fsmartform/lists"}