@algodomain/smart-forms 0.1.0

package/README.md

@@ -0,0 +1,313 @@
+# @algodomain/smart-forms
+
+A powerful, flexible React form framework with smart fields, multi-tab support, built-in validation, and seamless API integration. Built with TypeScript, Tailwind CSS, and shadcn/ui components.
+
+📚 **[Complete User Guide](./USER_GUIDE.md)** | 🚀 **[Quick Reference](./QUICK_REFERENCE.md)** | 📖 **[API Reference](./API_REFERENCE.md)**
+
+## Features
+
+- 🎯 **Smart Fields**: Pre-built, validated form fields with consistent UX
+- 📑 **Multi-Tab Forms**: Create complex forms with tabbed navigation and progress tracking
+- ✅ **Built-in Validation**: Powered by Zod for type-safe validation
+- 🔄 **API Integration**: Automatic form submission with authentication support
+- 💾 **Auto-Save**: LocalStorage support for draft saving
+- 🎨 **Customizable**: Full theme control via CSS variables
+- 🌙 **Dark Mode**: Built-in support for light and dark themes
+- ♿ **Accessible**: Built on Radix UI primitives
+- 📦 **Tree-Shakeable**: Import only what you need
+
+## Installation
+
+```bash
+npm install @algodomain/smart-forms
+# or
+pnpm add @algodomain/smart-forms
+# or
+yarn add @algodomain/smart-forms
+```
+
+### Peer Dependencies
+
+Make sure you have these installed:
+
+```bash
+npm install react react-dom tailwindcss zod react-toastify date-fns lucide-react
+```
+
+## Quick Start
+
+### 1. Import the CSS
+
+Add this to your main entry file (e.g., `main.tsx` or `index.tsx`):
+
+```tsx
+import '@algodomain/smart-forms/style.css'
+import './index.css' // Your Tailwind CSS
+```
+
+### 2. Create Your First Form
+
+```tsx
+import { SmartForm } from '@algodomain/smart-forms'
+import { SmartInput } from '@algodomain/smart-forms/fields'
+import { FieldEmail, FieldPassword } from '@algodomain/smart-forms/opinionated'
+
+function RegistrationForm() {
+  return (
+    <SmartForm
+      api="/api/register"
+      method="POST"
+      submitButtonText="Sign Up"
+      onSuccess={(data) => console.log('User created:', data)}
+      onError={(error) => console.error('Error:', error)}
+      authentication={{ enable: true }}
+    >
+      <SmartInput field="name" label="Full Name" required />
+      <FieldEmail field="email" required />
+      <FieldPassword field="password" required />
+      <SmartSelect
+        field="role"
+        label="Role"
+        options={[
+          { value: 'user', label: 'User' },
+          { value: 'admin', label: 'Admin' }
+        ]}
+      />
+    </SmartForm>
+  )
+}
+```
+
+### 3. Multi-Tab Form Example
+
+```tsx
+import { MultiTabSmartForm, Tab } from '@algodomain/smart-forms'
+import { SmartInput, SmartRadioGroup, SmartTags } from '@algodomain/smart-forms/fields'
+import { z } from 'zod'
+
+function CreateJobForm() {
+  return (
+    <MultiTabSmartForm
+      api="/api/jobs"
+      method="POST"
+      showProgressBar={true}
+      showTabNumbers={true}
+      authentication={{ enable: true }}
+      onSuccess={(data) => console.log('Job created:', data)}
+    >
+      <Tab title="Basic Info">
+        <SmartInput 
+          field="jobTitle" 
+          label="Job Title" 
+          validation={z.string().min(3)}
+          required 
+        />
+        <SmartRadioGroup
+          field="jobType"
+          label="Job Type"
+          options={[
+            { value: 'FULL_TIME', label: 'Full Time' },
+            { value: 'PART_TIME', label: 'Part Time' }
+          ]}
+          required
+        />
+      </Tab>
+      
+      <Tab title="Requirements">
+        <SmartTags 
+          field="skills" 
+          label="Required Skills"
+          validation={z.array(z.string()).min(1)}
+          required 
+        />
+        <SmartInput 
+          field="experience" 
+          label="Years of Experience"
+          type="number"
+        />
+      </Tab>
+    </MultiTabSmartForm>
+  )
+}
+```
+
+## Available Components
+
+### Core Forms
+
+- **SmartForm**: Single-page form with API integration
+- **MultiTabSmartForm**: Multi-step tabbed form with progress tracking
+- **BaseSmartForm**: Low-level form component for custom layouts
+
+### Smart Fields
+
+Import from `@algodomain/smart-forms/fields`:
+
+- `SmartInput` - Text, email, password, number, textarea inputs
+- `SmartSelect` - Dropdown select
+- `SmartCheckbox` - Checkbox with label
+- `SmartRadioGroup` - Radio button group
+- `SmartCombobox` - Searchable select
+- `SmartDatePicker` - Date picker with calendar
+- `SmartFileUpload` - File upload with preview
+- `SmartSlider` - Single value slider
+- `SmartDualRangeSlider` - Min/max range slider
+- `SmartTags` - Tag input field
+- `SmartAutoSuggestTags` - Tags with autocomplete
+- `SmartBasicRichTextbox` - Basic rich text editor
+
+### Opinionated Fields
+
+Import from `@algodomain/smart-forms/opinionated`:
+
+Pre-configured fields with built-in validation:
+
+- `FieldEmail` - Email field with validation
+- `FieldPassword` / `FieldConfirmPassword` - Password fields
+- `FieldPhone` - Phone number field
+- `FieldFirstName` / `FieldLastName` / `FieldFullName` - Name fields
+- `FieldAge` - Age field with validation
+- `FieldStreetAddress` / `FieldCity` / `FieldZipCode` / `FieldState` - Address fields
+- `FieldMessage` / `FieldComments` - Message/comment fields
+
+## Configuration
+
+### Form Props
+
+```tsx
+<SmartForm
+  api="/api/endpoint"                    // API endpoint
+  method="POST"                          // HTTP method (POST, PUT, PATCH)
+  submitButtonText="Submit"              // Custom button text
+  onSuccess={(data) => {}}               // Success callback
+  onError={(error) => {}}                // Error callback
+  authentication={{ enable: true }}      // Add Bearer token
+  enableLocalStorage={true}              // Enable draft saving
+  storageKey="my-form-draft"            // LocalStorage key
+  initialData={{ name: "John" }}        // Pre-fill data
+  transformData={(data) => data}         // Transform before submit
+/>
+```
+
+### Field Props
+
+All smart fields support these common props:
+
+- `field` (required): Field name
+- `label`: Display label
+- `required`: Make field required
+- `validation`: Zod schema for validation
+- `defaultValue`: Initial value
+- `placeholder`: Placeholder text
+- `className`: Custom CSS class
+- `info`: Info tooltip text
+- `subLabel`: Additional label text
+
+## Theme Customization
+
+### Override CSS Variables
+
+Add this to your CSS file:
+
+```css
+:root {
+  --primary: oklch(0.5 0.2 250);        /* Custom primary color */
+  --radius: 1rem;                        /* Border radius */
+  --background: oklch(1 0 0);           /* Background color */
+  --foreground: oklch(0.145 0 0);       /* Text color */
+}
+
+/* Dark mode */
+.dark {
+  --background: oklch(0.145 0 0);
+  --foreground: oklch(0.985 0 0);
+}
+```
+
+### Full Tailwind Support (Optional)
+
+For complete Tailwind utility support, add to your `index.css`:
+
+```css
+@source "../node_modules/@algodomain/smart-forms/dist/index.js";
+@source "../node_modules/@algodomain/smart-forms/dist/index.cjs";
+```
+
+This ensures Tailwind generates utilities used inside the library.
+
+## Authentication
+
+Enable authentication to automatically include Bearer tokens:
+
+```tsx
+<SmartForm
+  authentication={{
+    enable: true,
+    refreshTokenEndpoint: "/api/auth/refresh",  // Optional
+    accessTokenKey: "accessToken",              // Default
+    refreshTokenKey: "refreshToken"             // Default
+  }}
+/>
+```
+
+The library will:
+1. Get the access token from localStorage
+2. Include it as `Authorization: Bearer <token>`
+3. Automatically refresh if refresh endpoint is provided
+4. Retry the request with the new token
+
+## Validation
+
+Use Zod schemas for validation:
+
+```tsx
+import { z } from 'zod'
+
+<SmartInput
+  field="email"
+  label="Email"
+  validation={z
+    .string()
+    .email("Invalid email")
+    .min(5, "Too short")
+  }
+  required
+/>
+```
+
+## TypeScript Support
+
+Fully typed with TypeScript. Import types:
+
+```tsx
+import type { 
+  SmartFormProps, 
+  FormConfig,
+  SmartInputProps 
+} from '@algodomain/smart-forms'
+```
+
+## Examples
+
+Check out the examples directory for more use cases:
+
+- Simple contact form
+- Multi-step registration
+- Job posting form
+- User profile form
+- Complex validation scenarios
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions welcome! Please open an issue or PR on GitHub.
+
+## Support
+
+For issues and questions:
+- GitHub Issues: [github.com/algodomain/smart-forms](https://github.com/algodomain/smart-forms)
+- Documentation: [docs.algodomain.com](https://docs.algodomain.com)
+

package/dist/SmartFormProvider-B-BTl4wO.d.cts

@@ -0,0 +1,94 @@
+import React__default, { ReactNode } from 'react';
+
+/**
+ * Authentication configuration for SmartForm
+ *
+ * @interface AuthenticationConfig
+ * @property {boolean} enable - Enable authentication (sends Bearer token in Authorization header)
+ * @property {string} [refreshTokenEndpoint] - Optional endpoint for token refresh when accessToken expires
+ * @property {string} [accessTokenKey] - localStorage key for access token (default: 'accessToken')
+ * @property {string} [refreshTokenKey] - localStorage key for refresh token (default: 'refreshToken')
+ *
+ * @example
+ * ```typescript
+ * // Basic authentication without token refresh
+ * authentication={{ enable: true }}
+ *
+ * // Authentication with token refresh
+ * authentication={{
+ *   enable: true,
+ *   refreshTokenEndpoint: "/api/auth/refresh"
+ * }}
+ *
+ * // Custom token keys
+ * authentication={{
+ *   enable: true,
+ *   refreshTokenEndpoint: "/api/auth/refresh",
+ *   accessTokenKey: "myAccessToken",
+ *   refreshTokenKey: "myRefreshToken"
+ * }}
+ * ```
+ */
+interface AuthenticationConfig {
+    enable: boolean;
+    refreshTokenEndpoint?: string;
+    accessTokenKey?: string;
+    refreshTokenKey?: string;
+}
+interface FormConfig {
+    showProgressBar?: any;
+    api?: string;
+    method?: 'POST' | 'PUT' | 'PATCH';
+    submitButtonText?: string;
+    submitButtonIcon?: ReactNode;
+    allowSaveDraft?: boolean;
+    saveDraftApi?: string;
+    onSuccess?: (data: any) => void;
+    onError?: (error: any) => void;
+    transformData?: (data: any) => any;
+    className?: string;
+    title?: string;
+    subTitle?: string;
+    storageKey?: string;
+    enableLocalStorage?: boolean;
+    logFormData?: boolean;
+    showReset?: boolean;
+    showTabNumbers?: boolean;
+    authentication?: AuthenticationConfig;
+}
+interface FormContextType {
+    formData: any;
+    errors: any;
+    isLoading: boolean;
+    isDraftSaving: boolean;
+    updateField: (field: string, value: any) => void;
+    validateField: (field: string, value: any) => boolean;
+    validateFields: (fields: string[]) => boolean;
+    submitForm: () => Promise<void>;
+    validateFormAndGetResult: () => boolean;
+    saveDraft: () => Promise<void>;
+    resetForm: () => void;
+    fieldRefs: React__default.MutableRefObject<any>;
+    registerValidation: (field: string, validation: any) => void;
+    validationRegistry: any;
+    config: FormConfig;
+    setErrors: (errors: any) => void;
+    registerSubmitHook: (key: string, hook: () => Promise<void>) => void;
+    unregisterSubmitHook: (key: string) => void;
+}
+interface SmartFormProviderProps {
+    children: ReactNode;
+    config: FormConfig;
+    initialData?: any;
+}
+declare const SmartFormProvider: React__default.FC<SmartFormProviderProps>;
+declare const useSmartForm: () => FormContextType;
+declare const useFormField: (field: string) => {
+    value: any;
+    error: any;
+    onChange: (value: any) => void;
+    fieldRef: (el: any) => any;
+    registerValidation: (field: string, validation: any) => void;
+};
+
+export { type AuthenticationConfig as A, type FormContextType as F, SmartFormProvider as S, useFormField as a, type FormConfig as b, useSmartForm as u };

package/dist/SmartFormProvider-B-BTl4wO.d.ts

@@ -0,0 +1,94 @@
+import React__default, { ReactNode } from 'react';
+
+/**
+ * Authentication configuration for SmartForm
+ *
+ * @interface AuthenticationConfig
+ * @property {boolean} enable - Enable authentication (sends Bearer token in Authorization header)
+ * @property {string} [refreshTokenEndpoint] - Optional endpoint for token refresh when accessToken expires
+ * @property {string} [accessTokenKey] - localStorage key for access token (default: 'accessToken')
+ * @property {string} [refreshTokenKey] - localStorage key for refresh token (default: 'refreshToken')
+ *
+ * @example
+ * ```typescript
+ * // Basic authentication without token refresh
+ * authentication={{ enable: true }}
+ *
+ * // Authentication with token refresh
+ * authentication={{
+ *   enable: true,
+ *   refreshTokenEndpoint: "/api/auth/refresh"
+ * }}
+ *
+ * // Custom token keys
+ * authentication={{
+ *   enable: true,
+ *   refreshTokenEndpoint: "/api/auth/refresh",
+ *   accessTokenKey: "myAccessToken",
+ *   refreshTokenKey: "myRefreshToken"
+ * }}
+ * ```
+ */
+interface AuthenticationConfig {
+    enable: boolean;
+    refreshTokenEndpoint?: string;
+    accessTokenKey?: string;
+    refreshTokenKey?: string;
+}
+interface FormConfig {
+    showProgressBar?: any;
+    api?: string;
+    method?: 'POST' | 'PUT' | 'PATCH';
+    submitButtonText?: string;
+    submitButtonIcon?: ReactNode;
+    allowSaveDraft?: boolean;
+    saveDraftApi?: string;
+    onSuccess?: (data: any) => void;
+    onError?: (error: any) => void;
+    transformData?: (data: any) => any;
+    className?: string;
+    title?: string;
+    subTitle?: string;
+    storageKey?: string;
+    enableLocalStorage?: boolean;
+    logFormData?: boolean;
+    showReset?: boolean;
+    showTabNumbers?: boolean;
+    authentication?: AuthenticationConfig;
+}
+interface FormContextType {
+    formData: any;
+    errors: any;
+    isLoading: boolean;
+    isDraftSaving: boolean;
+    updateField: (field: string, value: any) => void;
+    validateField: (field: string, value: any) => boolean;
+    validateFields: (fields: string[]) => boolean;
+    submitForm: () => Promise<void>;
+    validateFormAndGetResult: () => boolean;
+    saveDraft: () => Promise<void>;
+    resetForm: () => void;
+    fieldRefs: React__default.MutableRefObject<any>;
+    registerValidation: (field: string, validation: any) => void;
+    validationRegistry: any;
+    config: FormConfig;
+    setErrors: (errors: any) => void;
+    registerSubmitHook: (key: string, hook: () => Promise<void>) => void;
+    unregisterSubmitHook: (key: string) => void;
+}
+interface SmartFormProviderProps {
+    children: ReactNode;
+    config: FormConfig;
+    initialData?: any;
+}
+declare const SmartFormProvider: React__default.FC<SmartFormProviderProps>;
+declare const useSmartForm: () => FormContextType;
+declare const useFormField: (field: string) => {
+    value: any;
+    error: any;
+    onChange: (value: any) => void;
+    fieldRef: (el: any) => any;
+    registerValidation: (field: string, validation: any) => void;
+};
+
+export { type AuthenticationConfig as A, type FormContextType as F, SmartFormProvider as S, useFormField as a, type FormConfig as b, useSmartForm as u };

package/dist/SmartTags-HmvmCJPT.d.cts

@@ -0,0 +1,111 @@
+import React__default from 'react';
+
+interface SmartInputProps {
+    field: string;
+    label?: string;
+    type?: 'text' | 'email' | 'password' | 'tel' | 'number' | 'textarea';
+    placeholder?: string;
+    validation?: any;
+    className?: string;
+    required?: boolean;
+    defaultValue?: any;
+    info?: string;
+    subLabel?: string;
+}
+declare const SmartInput: React__default.FC<SmartInputProps>;
+
+interface SmartCheckboxProps {
+    field: string;
+    label?: string;
+    className?: string;
+    validation?: any;
+    required?: boolean;
+    defaultValue?: boolean;
+    info?: string;
+    subLabel?: string;
+}
+declare const SmartCheckbox: React__default.FC<SmartCheckboxProps>;
+
+interface SmartRadioGroupOption {
+    value: string;
+    label: string;
+}
+interface SmartRadioGroupProps {
+    field: string;
+    label?: string;
+    options: SmartRadioGroupOption[];
+    name?: string;
+    alignment?: 'vertical' | 'horizontal';
+    className?: string;
+    validation?: any;
+    required?: boolean;
+    defaultValue?: string;
+    info?: string;
+    subLabel?: string;
+}
+declare const SmartRadioGroup: React__default.FC<SmartRadioGroupProps>;
+
+interface SmartSelectOption {
+    value: string;
+    label: string;
+}
+interface SmartSelectProps {
+    field: string;
+    label?: string;
+    options: SmartSelectOption[];
+    className?: string;
+    placeholder?: string;
+    validation?: any;
+    required?: boolean;
+    defaultValue?: string;
+    info?: string;
+    subLabel?: string;
+}
+declare const SmartSelect: React__default.FC<SmartSelectProps>;
+
+interface SmartDatePickerProps {
+    field: string;
+    label?: string;
+    className?: string;
+    placeholder?: string;
+    validation?: any;
+    required?: boolean;
+    allowPast?: boolean;
+    allowFuture?: boolean;
+    /**
+     * When true, value will be stored/returned as ISO string (yyyy-MM-dd).
+     * Otherwise the underlying form value will be a Date instance.
+     */
+    valueAsString?: boolean;
+    /** Optional minimum selectable date */
+    minDate?: Date;
+    /** Optional maximum selectable date */
+    maxDate?: Date;
+    /** Default value for the date picker (can be Date or string depending on valueAsString) */
+    defaultValue?: Date | string;
+    info?: string;
+    subLabel?: string;
+}
+declare const SmartDatePicker: React__default.FC<SmartDatePickerProps>;
+
+interface SmartTagsProps {
+    field: string;
+    label?: string;
+    className?: string;
+    placeholder?: string;
+    validation?: any;
+    required?: boolean;
+    maxTags?: number;
+    defaultValue?: string[];
+    maxLength?: number;
+    minLength?: number;
+    allowDuplicates?: boolean;
+    disabled?: boolean;
+    onTagAdd?: (tagText: string) => void;
+    onTagRemove?: (tagText: string) => void;
+    info?: string;
+    subLabel?: string;
+}
+declare const SmartTags: React__default.FC<SmartTagsProps>;
+
+export { SmartInput as S, SmartCheckbox as a, SmartRadioGroup as b, SmartSelect as c, SmartDatePicker as d, SmartTags as e, type SmartInputProps as f, type SmartTagsProps as g };