@axenstudio/axen-form 0.1.1

package/README.md

@@ -0,0 +1,665 @@
+# @axenstudio/axen-form
+
+Lightweight, config-driven, enterprise-grade React form library.  
+Zero UI dependency. CSS Modules. A11y-aware. TypeScript strict.
+
+[![npm](https://img.shields.io/npm/v/@axenstudio/axen-form)](https://www.npmjs.com/package/@axenstudio/axen-form)
+[![license](https://img.shields.io/npm/l/@axenstudio/axen-form)](LICENSE)
+[![react](https://img.shields.io/badge/react-%E2%89%A519-blue)](https://react.dev)
+
+---
+
+## Why axen-form?
+
+| Feature       | axen-form                             | Formik + MUI          | React Hook Form  |
+| ------------- | ------------------------------------- | --------------------- | ---------------- |
+| UI Dependency | **None** — native HTML                | MUI (~350KB)          | None             |
+| Form Engine   | **Built-in** reactive store           | Formik rerender-heavy | Ref-based        |
+| Validation    | **Plugin-based** (Yup / Zod / custom) | Yup only              | Resolver pattern |
+| Styling       | **CSS Modules** + design tokens       | Emotion runtime       | BYO              |
+| Config-Driven | **Yes** — one config = one form       | No                    | No               |
+| Bundle Size   | **< 15KB** gzipped                    | ~350KB+ with MUI      | ~10KB            |
+| React Version | **≥ 19**                              | ≥ 16                  | ≥ 16             |
+| TypeScript    | **Strict** end-to-end                 | Partial               | Good             |
+
+---
+
+## Installation
+
+```bash
+npm install @axenstudio/axen-form
+# or
+pnpm add @axenstudio/axen-form
+```
+
+**Peer dependencies:** `react ≥ 19`, `react-dom ≥ 19`
+
+**Optional validation libraries:**
+
+```bash
+# Pick one (or both)
+pnpm add yup        # Yup adapter
+pnpm add zod        # Zod adapter
+```
+
+---
+
+## Quick Start
+
+```tsx
+import { AxenForm, defaultComponentMap } from '@axenstudio/axen-form';
+import '@axenstudio/axen-form/tokens';
+import '@axenstudio/axen-form/reset';
+
+const config = {
+  initialValues: { name: '', email: '', role: 'user' },
+  fields: [
+    { name: 'name', type: 'text', label: 'Full Name', required: true, colSpan: 6 },
+    { name: 'email', type: 'email', label: 'Email', required: true, colSpan: 6 },
+    {
+      name: 'role',
+      type: 'select',
+      label: 'Role',
+      options: [
+        { value: 'user', label: 'User' },
+        { value: 'admin', label: 'Admin' },
+      ],
+    },
+  ],
+};
+
+function App() {
+  return (
+    <AxenForm
+      config={config}
+      components={defaultComponentMap}
+      onSubmit={(values) => console.log(values)}
+    />
+  );
+}
+```
+
+That's it. One config, one component — a full form with validation, layout, and accessibility.
+
+---
+
+## 20 Built-in Field Types
+
+### Text Inputs
+
+| Type       | Component       | Description                        |
+| ---------- | --------------- | ---------------------------------- |
+| `text`     | `TextField`     | Standard text input                |
+| `email`    | `EmailField`    | Email input with `type="email"`    |
+| `password` | `PasswordField` | Password with show/hide toggle     |
+| `phone`    | `PhoneField`    | Phone input with `type="tel"`      |
+| `textarea` | `TextareaField` | Multi-line text, configurable rows |
+
+### Numeric Inputs
+
+| Type       | Component       | Description                                           |
+| ---------- | --------------- | ----------------------------------------------------- |
+| `number`   | `NumberField`   | Locale-aware thousand separator + cursor preservation |
+| `currency` | `CurrencyField` | Intl currency formatting with prefix/suffix           |
+| `slider`   | `SliderField`   | Range slider with value display                       |
+
+### Date & Time
+
+| Type       | Component       | Description                                            |
+| ---------- | --------------- | ------------------------------------------------------ |
+| `date`     | `DateField`     | Date picker — displays locale, stores ISO `YYYY-MM-DD` |
+| `time`     | `TimeField`     | Time picker — 12h/24h, stores ISO `HH:mm`              |
+| `datetime` | `DateTimeField` | Combined date+time, stores ISO `YYYY-MM-DDTHH:mm`      |
+
+### Selection
+
+| Type       | Component       | Description                |
+| ---------- | --------------- | -------------------------- |
+| `select`   | `SelectField`   | Native `<select>` dropdown |
+| `checkbox` | `CheckboxField` | Styled checkbox with label |
+| `radio`    | `RadioField`    | Radio group from `options` |
+| `switch`   | `SwitchField`   | Toggle switch (on/off)     |
+
+### Autocomplete
+
+| Type                   | Component                  | Description                        |
+| ---------------------- | -------------------------- | ---------------------------------- |
+| `autocomplete`         | `AutocompleteField`        | Server-side search with debounce   |
+| `autocomplete-multi`   | `AutocompleteMultiField`   | Multi-select with chip/tag display |
+| `autocomplete-predict` | `AutocompletePredictField` | Ghost text prediction + Tab accept |
+
+### Miscellaneous
+
+| Type    | Component    | Description              |
+| ------- | ------------ | ------------------------ |
+| `color` | `ColorField` | Color swatch + hex input |
+
+---
+
+## Core Concepts
+
+### Config-Driven Forms
+
+Define your entire form with a configuration object:
+
+```typescript
+import type { FormConfig } from '@axenstudio/axen-form';
+
+const config: FormConfig = {
+  initialValues: {
+    name: '',
+    email: '',
+    age: 0,
+    birthday: '',
+    bio: '',
+  },
+  fields: [
+    { name: 'name', type: 'text', label: 'Name', required: true },
+    {
+      name: 'email',
+      type: 'email',
+      label: 'Email',
+      required: true,
+      requiredMessage: 'Email wajib diisi',
+    },
+    { name: 'age', type: 'number', label: 'Age', min: 0, max: 150, locale: 'en-US' },
+    { name: 'birthday', type: 'date', label: 'Birthday' },
+    { name: 'bio', type: 'textarea', label: 'Bio', rows: 4 },
+  ],
+};
+```
+
+### Responsive Grid Layout
+
+Fields are placed in a 12-column CSS Grid. Control column span per breakpoint:
+
+```typescript
+{
+  name: 'firstName',
+  type: 'text',
+  label: 'First Name',
+  colSpan: { xs: 12, sm: 6, md: 4 },  // Full → half → third
+}
+```
+
+Or use a simple number for all breakpoints:
+
+```typescript
+{ name: 'email', type: 'email', label: 'Email', colSpan: 6 }
+```
+
+### Validation Adapters
+
+Bring your own validation library via adapters:
+
+**Yup:**
+
+```typescript
+import { AxenForm, defaultComponentMap } from '@axenstudio/axen-form';
+import { yupAdapter } from '@axenstudio/axen-form/adapters/yup';
+
+<AxenForm
+  config={config}
+  components={defaultComponentMap}
+  validationAdapter={yupAdapter}
+  onSubmit={handleSubmit}
+/>
+```
+
+**Zod:**
+
+```typescript
+import { zodAdapter } from '@axenstudio/axen-form/adapters/zod';
+
+<AxenForm
+  config={config}
+  components={defaultComponentMap}
+  validationAdapter={zodAdapter}
+  onSubmit={handleSubmit}
+/>
+```
+
+**Built-in (zero-dep):**
+
+Without any adapter, axen-form uses `simpleValidator` — validates `required` fields automatically.
+
+---
+
+## Advanced Features
+
+### Conditional Fields
+
+Hide fields dynamically based on form values:
+
+```typescript
+{
+  name: 'companyName',
+  type: 'text',
+  label: 'Company Name',
+  hidden: (values) => values.role !== 'business',
+}
+```
+
+Hidden fields are excluded from the rendered form and validation.
+
+### Array / Repeating Fields
+
+```typescript
+import type { ArrayFieldConfig } from '@axenstudio/axen-form';
+
+const contactFields: ArrayFieldConfig = {
+  name: 'contacts',
+  type: 'text', // base type (unused in array context)
+  isArray: true,
+  label: 'Contacts',
+  addLabel: '+ Add Contact',
+  removeLabel: 'Remove',
+  minItems: 1,
+  maxItems: 5,
+  fields: [
+    { name: 'name', type: 'text', label: 'Name', colSpan: 6 },
+    { name: 'email', type: 'email', label: 'Email', colSpan: 6 },
+  ],
+};
+```
+
+### Imperative Control via Ref
+
+```tsx
+import { useRef } from 'react';
+import type { AxenFormRef } from '@axenstudio/axen-form';
+
+function MyForm() {
+  const formRef = useRef<AxenFormRef>(null);
+
+  const handleExternalSubmit = () => formRef.current?.submit();
+  const handleReset = () => formRef.current?.resetForm();
+
+  return (
+    <>
+      <AxenForm
+        ref={formRef}
+        config={config}
+        components={defaultComponentMap}
+        onSubmit={handleSubmit}
+      />
+      <button onClick={handleExternalSubmit}>Submit from Outside</button>
+      <button onClick={handleReset}>Reset</button>
+    </>
+  );
+}
+```
+
+**Available ref methods:**
+
+| Method               | Return                    | Description                             |
+| -------------------- | ------------------------- | --------------------------------------- |
+| `submit()`           | `void`                    | Trigger form submission                 |
+| `resetForm(values?)` | `void`                    | Reset form (optionally with new values) |
+| `getValues()`        | `Record<string, unknown>` | Get current form values                 |
+| `getErrors()`        | `Record<string, string>`  | Get current validation errors           |
+| `isValid()`          | `boolean`                 | Check if form has no errors             |
+| `isDirty()`          | `boolean`                 | Check if values differ from initial     |
+
+### Payload Whitelist
+
+Control which fields are included in the submit payload:
+
+```tsx
+// Static whitelist
+<AxenForm
+  config={config}
+  components={defaultComponentMap}
+  payloadFields={['name', 'email']}
+  onSubmit={(values) => {
+    // values only contains { name, email }
+  }}
+/>
+
+// Dynamic whitelist based on discriminator field
+<AxenForm
+  config={config}
+  components={defaultComponentMap}
+  payloadFields={{
+    individual: ['firstName', 'lastName', 'ssn'],
+    company: ['companyName', 'taxId'],
+  }}
+  payloadDiscriminator="accountType"
+  onSubmit={handleSubmit}
+/>
+```
+
+### Headless Usage with `useAxenForm`
+
+For full control over rendering, use the headless hook:
+
+```tsx
+import { useAxenForm, useField } from '@axenstudio/axen-form';
+
+function CustomForm() {
+  const { store, formApi } = useAxenForm({
+    initialValues: { name: '' },
+    fields: [{ name: 'name', type: 'text', label: 'Name', required: true }],
+    onSubmit: async (values) => {
+      /* ... */
+    },
+  });
+
+  return (
+    <form onSubmit={formApi.handleSubmit}>
+      <input
+        name="name"
+        value={formApi.values.name as string}
+        onChange={formApi.handleChange}
+        onBlur={formApi.handleBlur}
+      />
+      {formApi.errors.name && <span>{formApi.errors.name}</span>}
+      <button type="submit">Submit</button>
+    </form>
+  );
+}
+```
+
+### Custom Field Components
+
+Override any built-in field by providing a custom component:
+
+```tsx
+import type { FieldComponentProps } from '@axenstudio/axen-form';
+
+function MyCustomSelect({ name, value, onChange, options, label, error, helperText }: FieldComponentProps) {
+  return (
+    <div>
+      <label>{label}</label>
+      {/* Your custom select UI */}
+      {error && <span className="error">{helperText}</span>}
+    </div>
+  );
+}
+
+// Per-field override
+const config = {
+  initialValues: { country: '' },
+  fields: [
+    { name: 'country', type: 'select', label: 'Country', component: MyCustomSelect, options: [...] },
+  ],
+};
+
+// Or type-level override via components prop
+<AxenForm
+  config={config}
+  components={{ ...defaultComponentMap, select: MyCustomSelect }}
+  onSubmit={handleSubmit}
+/>
+```
+
+---
+
+## Layout Components
+
+Built-in layout components with MUI-like API, powered by CSS Grid:
+
+### Grid
+
+12-column responsive grid container:
+
+```tsx
+import { Grid } from '@axenstudio/axen-form';
+
+<Grid container spacing={2}>
+  <Grid size={{ xs: 12, md: 6 }}>
+    <TextField {...props} />
+  </Grid>
+  <Grid size={{ xs: 12, md: 6 }}>
+    <TextField {...props} />
+  </Grid>
+</Grid>;
+```
+
+### Box
+
+Generic flex/block container:
+
+```tsx
+import { Box } from '@axenstudio/axen-form';
+
+<Box display="flex" gap="16px" p="8px">
+  <span>Left</span>
+  <span>Right</span>
+</Box>;
+```
+
+### Stack
+
+Vertical/horizontal stack with gap:
+
+```tsx
+import { Stack } from '@axenstudio/axen-form';
+
+<Stack direction="column" spacing={2}>
+  <div>Item 1</div>
+  <div>Item 2</div>
+</Stack>;
+```
+
+### Divider
+
+Horizontal/vertical divider:
+
+```tsx
+import { Divider } from '@axenstudio/axen-form';
+
+<Stack direction="column" spacing={2}>
+  <div>Above</div>
+  <Divider />
+  <div>Below</div>
+</Stack>;
+```
+
+### Spacer
+
+Invisible spacing element — creates horizontal, vertical, or flex-basis gaps. Uses the same 8px spacing unit as Box/Grid/Stack.
+
+```tsx
+import { Spacer } from '@axenstudio/axen-form';
+
+// Horizontal gap (16px)
+<Stack direction="row">
+  <Button>Save</Button>
+  <Spacer x={2} />
+  <Button>Cancel</Button>
+</Stack>
+
+// Vertical gap (24px)
+<Stack direction="column">
+  <Card>Section A</Card>
+  <Spacer y={3} />
+  <Card>Section B</Card>
+</Stack>
+
+// Push items apart (flex grow)
+<Stack direction="row">
+  <Logo />
+  <Spacer grow />
+  <NavLinks />
+</Stack>
+
+// Fixed flex basis (32px)
+<Spacer basis={4} />
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `x` | `number` | `0` | Horizontal spacing multiplier (width = x × 8px) |
+| `y` | `number` | `0` | Vertical spacing multiplier (height = y × 8px) |
+| `basis` | `number` | `0` | Flex basis multiplier (basis × 8px) |
+| `grow` | `boolean` | `false` | Grow to fill remaining space |
+
+---
+
+## Theming with CSS Custom Properties
+
+axen-form uses CSS Custom Properties (design tokens) for theming. Import the default tokens and override as needed:
+
+```css
+/* Import defaults */
+@import '@axenstudio/axen-form/tokens';
+@import '@axenstudio/axen-form/reset';
+
+/* Override tokens */
+:root {
+  --axen-primary-color: #1a73e8;
+  --axen-error-color: #d32f2f;
+  --axen-focus-color: #1a73e8;
+  --axen-border-radius: 8px;
+  --axen-font-family: 'Inter', sans-serif;
+}
+```
+
+**Key token categories:**
+
+| Category   | Example Tokens                                                     |
+| ---------- | ------------------------------------------------------------------ |
+| Colors     | `--axen-primary-color`, `--axen-error-color`, `--axen-label-color` |
+| Typography | `--axen-font-family`, `--axen-label-font-size`                     |
+| Spacing    | `--axen-field-gap`, `--axen-input-padding`                         |
+| Borders    | `--axen-border-color`, `--axen-border-radius`                      |
+| Focus      | `--axen-focus-color`, `--axen-focus-ring`                          |
+| States     | `--axen-input-disabled-bg`, `--axen-placeholder-color`             |
+
+**Built-in A11y support:**
+
+- Dark mode via `@media (prefers-color-scheme: dark)`
+- High contrast via `@media (prefers-contrast: more)`
+- Reduced motion via `@media (prefers-reduced-motion: reduce)`
+- Focus-visible rings for keyboard navigation
+
+---
+
+## API Reference
+
+### `<AxenForm>`
+
+Main config-driven form component.
+
+| Prop                   | Type                                   | Default           | Description                                 |
+| ---------------------- | -------------------------------------- | ----------------- | ------------------------------------------- |
+| `config`               | `FormConfig`                           | **required**      | Form configuration (fields + initialValues) |
+| `onSubmit`             | `(values, meta) => void`               | **required**      | Submit handler                              |
+| `components`           | `FieldTypeComponentMap`                | `{}`              | Component map (use `defaultComponentMap`)   |
+| `validationAdapter`    | `ValidationAdapter`                    | `simpleValidator` | Validation library adapter                  |
+| `ref`                  | `Ref<AxenFormRef>`                     | —                 | Imperative handle                           |
+| `columns`              | `number`                               | `12`              | Grid columns                                |
+| `gap`                  | `string \| number`                     | —                 | Grid gap                                    |
+| `disabled`             | `boolean`                              | `false`           | Disable all fields                          |
+| `className`            | `string`                               | —                 | Additional CSS class                        |
+| `payloadFields`        | `string[] \| Record<string, string[]>` | —                 | Payload whitelist                           |
+| `payloadDiscriminator` | `string`                               | —                 | Discriminator field for dynamic payload     |
+| `validateOnChange`     | `boolean`                              | `true`            | Validate on field change                    |
+| `validateOnBlur`       | `boolean`                              | `true`            | Validate on field blur                      |
+
+### `FieldConfig`
+
+Configuration for a single field.
+
+| Property             | Type                                    | Description                                        |
+| -------------------- | --------------------------------------- | -------------------------------------------------- |
+| `name`               | `string`                                | Field name (supports nested paths: `address.city`) |
+| `type`               | `BuiltInFieldType \| string`            | Field type identifier                              |
+| `label`              | `string`                                | Field label                                        |
+| `placeholder`        | `string`                                | Input placeholder                                  |
+| `required`           | `boolean`                               | Mark as required                                   |
+| `requiredMessage`    | `string`                                | Custom required error message                      |
+| `disabled`           | `boolean`                               | Disable this field                                 |
+| `readOnly`           | `boolean`                               | Read-only mode                                     |
+| `hidden`             | `boolean \| (values) => boolean`        | Conditional hiding                                 |
+| `component`          | `ComponentType`                         | Override component for this field                  |
+| `options`            | `FieldOption[]`                         | Options for select/radio/autocomplete              |
+| `colSpan`            | `number \| { xs?, sm?, md?, lg?, xl? }` | Grid column span                                   |
+| `helperText`         | `string`                                | Helper text below field                            |
+| `min`, `max`, `step` | `number`                                | Numeric constraints                                |
+| `prefix`, `suffix`   | `string`                                | Display prefix/suffix (currency)                   |
+| `locale`             | `string`                                | Locale for number/date formatting                  |
+| `rows`               | `number`                                | Textarea rows                                      |
+| `fetchOptions`       | `(query, signal?) => Promise<Option[]>` | Async option fetcher (autocomplete)                |
+| `fieldProps`         | `Record<string, unknown>`               | Extra props forwarded to component                 |
+
+### Hooks
+
+| Hook             | Signature                                                                | Description                     |
+| ---------------- | ------------------------------------------------------------------------ | ------------------------------- |
+| `useAxenForm`    | `(config) => { store, formApi }`                                         | Create a headless form instance |
+| `useField`       | `(name) => { value, error, touched, onChange, onBlur }`                  | Subscribe to a single field     |
+| `useFieldArray`  | `(name) => { items, push, remove, swap, insert, replace, move, length }` | Array field operations          |
+| `useFormContext` | `() => FormApi`                                                          | Access form API from context    |
+
+### Utilities
+
+| Utility                                 | Description                             |
+| --------------------------------------- | --------------------------------------- |
+| `mapPayload(values, config, fields)`    | Apply payload whitelist to form values  |
+| `pickFields(values, fieldNames)`        | Pick specific fields from values object |
+| `getStrippedFields(values, fieldNames)` | Get fields that would be stripped       |
+| `get(obj, path, default?)`              | Get nested value by dot path            |
+| `set(obj, path, value)`                 | Immutable set nested value              |
+| `formatNumber(value, locale)`           | Format number with locale               |
+| `formatDateLocale(isoDate, locale)`     | Format ISO date for display             |
+| `cx(...classes)`                        | Conditional class name joiner           |
+
+---
+
+## Architecture
+
+```
+src/
+├── core/                  # Framework-agnostic form engine
+│   ├── formStore.ts       # Reactive state (useSyncExternalStore compatible)
+│   ├── validation.ts      # Adapter interface + simpleValidator
+│   ├── pathUtils.ts       # Nested path get/set/toArray
+│   ├── numberUtils.ts     # Locale-aware number formatting
+│   ├── dateUtils.ts       # ISO ↔ locale date conversion
+│   └── payloadUtils.ts    # Payload whitelist filter
+│
+├── react/                 # React 19+ bindings
+│   ├── AxenForm.tsx       # Main config-driven renderer
+│   ├── AxenField.tsx      # Field wrapper component
+│   ├── AxenArrayField.tsx # Array field renderer
+│   ├── useAxenForm.ts     # Headless form hook
+│   ├── useField.ts        # Single field subscription
+│   ├── useFieldArray.ts   # Array field operations
+│   └── FormContext.ts     # React context provider
+│
+├── fields/                # 20 built-in field components
+│   ├── defaultComponentMap.ts
+│   ├── fieldUtils.ts      # Shared utilities (cx, ariaProps)
+│   ├── fieldBase.module.css   # Shared field styles
+│   ├── TextField/
+│   ├── EmailField/
+│   ├── ...                # 18 more field directories
+│   └── ColorField/
+│
+├── layout/                # Grid, Box, Stack, Divider
+├── tokens/                # CSS Custom Properties + reset
+├── adapters/              # yupAdapter, zodAdapter
+├── types.ts               # All TypeScript definitions
+└── index.ts               # Public API barrel
+```
+
+---
+
+## Browser Support
+
+| Browser | Version         |
+| ------- | --------------- |
+| Chrome  | Last 2 versions |
+| Firefox | Last 2 versions |
+| Safari  | 15.4+           |
+| Edge    | Last 2 versions |
+
+Requires React 19+ and ES2022+ environment.
+
+---
+
+## License
+
+MIT © [Axen Studio](https://github.com/axenstudio)