@cyber-zen/form-core

A comprehensive form solution for React applications, extracted and optimized from ant-design-mobile. Provides powerful form validation, flexible layouts, and excellent TypeScript support.

✨ Features

• 🚀 Lightweight & Fast: Optimized bundle size with tree-shaking support
• 🎯 Rich Components: Form, FormItem, List, Popover, and more
• 🔧 TypeScript First: Full TypeScript support with comprehensive type definitions
• 📱 Mobile Optimized: Designed for mobile applications with touch-friendly interactions
• 🎨 Highly Customizable: Easy to customize styles, themes, and behaviors
• 🌍 Internationalization: Built-in i18n support with multiple locales
• ♿ Accessibility: ARIA attributes and keyboard navigation support

📦 Installation

# npm
npm install @cyber-zen/form-core

# yarn
yarn add @cyber-zen/form-core

# pnpm
pnpm add @cyber-zen/form-core

🚀 Quick Start

Basic Form Usage

import React from 'react';
import { Form, FormItem } from '@cyber-zen/form-core';
import '@cyber-zen/form-core/style';

const LoginForm = () => {
  const [form] = Form.useForm();

  const onFinish = (values: any) => {
    console.log('Form submitted:', values);
  };

  return (
    <Form form={form} onFinish={onFinish}>
      <FormItem
        name="username"
        label="Username"
        rules={[{ required: true, message: 'Please input username!' }]}
      >
        <input placeholder="Enter your username" />
      </FormItem>
      
      <FormItem
        name="password"
        label="Password"
        rules={[{ required: true, message: 'Please input password!' }]}
      >
        <input type="password" placeholder="Enter your password" />
      </FormItem>
      
      <button type="submit">Login</button>
    </Form>
  );
};

Advanced Form with Validation

import React from 'react';
import { Form, FormItem, List, ListItem } from '@cyber-zen/form-core';

const RegistrationForm = () => {
  const [form] = Form.useForm();

  return (
    <Form form={form} layout="vertical">
      <List>
        <ListItem>
          <FormItem
            name="email"
            label="Email Address"
            rules={[
              { required: true, message: 'Email is required!' },
              { type: 'email', message: 'Please enter a valid email!' }
            ]}
          >
            <input type="email" placeholder="[email protected]" />
          </FormItem>
        </ListItem>
        
        <ListItem>
          <FormItem
            name="phone"
            label="Phone Number"
            rules={[
              { required: true, message: 'Phone number is required!' },
              { pattern: /^1[3-9]\d{9}$/, message: 'Please enter a valid phone number!' }
            ]}
          >
            <input placeholder="13800138000" />
          </FormItem>
        </ListItem>
        
        <ListItem>
          <FormItem
            name="age"
            label="Age"
            rules={[
              { required: true, message: 'Age is required!' },
              { type: 'number', min: 18, message: 'Must be at least 18 years old!' }
            ]}
          >
            <input type="number" placeholder="25" />
          </FormItem>
        </ListItem>
      </List>
    </Form>
  );
};

Using Popover Component

import React from 'react';
import { Popover, PopoverMenu } from '@cyber-zen/form-core';

const PopoverExample = () => {
  const [visible, setVisible] = React.useState(false);

  return (
    <Popover
      visible={visible}
      onVisibleChange={setVisible}
      content={
        <PopoverMenu
          actions={[
            { text: 'Option 1', key: '1' },
            { text: 'Option 2', key: '2' },
            { text: 'Option 3', key: '3' }
          ]}
          onAction={(action) => {
            console.log('Selected:', action);
            setVisible(false);
          }}
        />
      }
    >
      <button>Click to show menu</button>
    </Popover>
  );
};

📚 API Reference

Form Component

| Property | Type | Default | Description | |----------|------|---------|-------------| | form | FormInstance | - | Form instance created by Form.useForm() | | layout | 'horizontal' \| 'vertical' | 'horizontal' | Form layout direction | | onFinish | (values: any) => void | - | Callback when form is successfully submitted | | onFinishFailed | (errorInfo: any) => void | - | Callback when form submission fails | | initialValues | object | - | Initial form values | | validateTrigger | string \| string[] | 'onChange' | When to validate form fields |

FormItem Component

| Property | Type | Default | Description | |----------|------|---------|-------------| | name | string | - | Field name for form data binding | | label | ReactNode | - | Field label text | | rules | Rule[] | - | Validation rules array | | required | boolean | false | Whether field is required | | validateTrigger | string \| string[] | - | When to validate this field | | help | ReactNode | - | Additional help text | | extra | ReactNode | - | Extra content below field |

List & ListItem Components

| Property | Type | Default | Description | |----------|------|---------|-------------| | header | ReactNode | - | List header content | | mode | 'default' \| 'card' | 'default' | List display mode | | children | ReactNode | - | List items |

Popover Component

| Property | Type | Default | Description | |----------|------|---------|-------------| | visible | boolean | false | Whether popover is visible | | content | ReactNode | - | Popover content | | placement | Placement | 'top' | Popover placement | | onVisibleChange | (visible: boolean) => void | - | Visibility change callback |

🛠️ Development

# Install dependencies
npm install

# Start development mode with watch
npm run dev

# Build for production
npm run build

# Run tests
npm test

# Run linting
npm run lint

# Type checking
npm run type-check

# Clean build directory
npm run clean

📦 Build & Publish

# Quick publish (latest tag)
npm run publish

# Publish beta version
npm run publish:beta

# Publish alpha version
npm run publish:alpha

# Full release with version bump (patch)
npm run release

🤝 Contributing

We welcome contributions! Please see our contributing guidelines for details.

📄 License

MIT License - see the LICENSE file for details.