decantr 0.9.0

package/reference/form-system.md

@@ -0,0 +1,253 @@
+# Form System Reference
+
+`import { createForm, validators, useFormField } from 'decantr/form';`
+
+## createForm(config)
+
+### Config Shape
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `fields` | `{ [name]: FieldConfig }` | `{}` | Field definitions |
+| `onSubmit` | `async (values, form) => void` | — | Submit handler |
+| `validate` | `(values) => { [name]: string[] }` | — | Cross-field validation |
+| `validateOn` | `'onChange' \| 'onBlur' \| 'onSubmit'` | `'onBlur'` | Validation trigger mode |
+
+### FieldConfig
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `value` | `any` | `''` | Initial value |
+| `validators` | `Function[]` | `[]` | Array of validator functions |
+| `transform` | `(raw) => transformed` | — | Transform applied on every `setValue` |
+
+### FormInstance API
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `field(name)` | `(string) => FieldInstance` | Get/create field by name |
+| `fields` | `Proxy` | Dot-access fields: `form.fields.email.value()` |
+| `values()` | `() => Object` | Memo — all current field + fieldArray values |
+| `errors()` | `() => { [name]: string[] }` | Memo — all fields with errors |
+| `isValid()` | `() => boolean` | Memo — true when all fields have zero errors |
+| `isDirty()` | `() => boolean` | Memo — true when any field differs from initial |
+| `isSubmitting()` | `() => boolean` | Signal — true during `onSubmit` execution |
+| `isSubmitted()` | `() => boolean` | Signal — true after successful submit |
+| `submitCount()` | `() => number` | Signal — number of submit attempts |
+| `submit()` | `() => Promise<void>` | Touch all fields, validate, call `onSubmit` if valid |
+| `reset(values?)` | `(Object?) => void` | Reset all fields; optional new initial values |
+| `setValues(partial)` | `(Object) => void` | Batch-set multiple field values |
+| `setErrors(errs)` | `(Object) => void` | Batch-set errors: `{ name: string \| string[] }` |
+| `validate()` | `() => Promise<boolean>` | Run all field + cross-field validators |
+| `fieldArray(name)` | `(string) => FieldArrayInstance` | Get/create field array |
+| `watch(name, cb)` | `(string, (val, prev) => void) => unsub` | Watch single field changes |
+| `watchAll(cb)` | `((values) => void) => unsub` | Watch any field change |
+
+### Submit Flow
+
+1. Increment `submitCount`
+2. Touch all fields (batch)
+3. Run all field validators (sync + async)
+4. Run `config.validate` cross-field validator (if provided)
+5. If all valid, set `isSubmitting(true)`, call `onSubmit(values, form)`
+6. On completion, set `isSubmitted(true)`, `isSubmitting(false)`
+
+## FieldInstance API
+
+Returned by `form.field(name)` or `form.fields.name`.
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `name` | `string` | Field name |
+| `value()` | `() => any` | Signal — current value |
+| `error()` | `() => string \| null` | Memo — first error or null |
+| `errors()` | `() => string[]` | Signal — all error messages |
+| `touched()` | `() => boolean` | Signal — true after blur |
+| `dirty()` | `() => boolean` | Memo — true when value differs from initial |
+| `valid()` | `() => boolean` | Memo — true when no errors |
+| `setValue(v)` | `(any \| (prev) => any) => void` | Set value (accepts updater fn); triggers validation per `validateOn` |
+| `setTouched()` | `() => void` | Mark as touched; triggers validation if `validateOn: 'onBlur'` |
+| `setError(msg)` | `(string) => void` | Set a single error manually |
+| `reset(val?)` | `(any?) => void` | Reset to initial (or provided) value, clear errors/touched |
+| `validate()` | `() => Promise<boolean>` | Run all validators imperatively |
+| `bind()` | `() => BindProps` | Returns props object for component binding |
+
+### bind() Return Shape
+
+```
+{ value, onchange, onblur, error }
+```
+
+- `value` — signal getter
+- `onchange` — auto-extracts `e.target.value` from DOM events or accepts raw values
+- `onblur` — calls `setTouched()`
+- `error` — signal getter (first error or null)
+
+Spread into any form component: `Input({ ...form.field('email').bind() })`
+
+## validators
+
+All return `(value, allValues) => string|null`. Custom message via last `msg` param.
+
+| Validator | Signature | Default Message |
+|-----------|-----------|-----------------|
+| `required` | `(msg?)` | `'Required'` |
+| `minLength` | `(n, msg?)` | `'Must be at least {n} characters'` |
+| `maxLength` | `(n, msg?)` | `'Must be at most {n} characters'` |
+| `min` | `(n, msg?)` | `'Must be at least {n}'` |
+| `max` | `(n, msg?)` | `'Must be at most {n}'` |
+| `pattern` | `(regex, msg?)` | `'Invalid format'` |
+| `email` | `(msg?)` | `'Invalid email address'` |
+| `match` | `(fieldName, msg?)` | `'Must match {fieldName}'` |
+| `custom` | `(fn, msg?)` | `'Invalid'` |
+| `async` | `(fn, msg?)` | `'Invalid'` |
+
+### Validator behavior
+
+- **Sync validators** run immediately on trigger (`onChange`/`onBlur`/`onSubmit`)
+- **Async validators** (`validators.async()`) auto-debounce at 300ms; only run if all sync validators pass
+- `custom(fn)` — `fn(value, allValues)` returns `true` (valid) or error string
+- `async(fn)` — `fn(value, allValues)` returns `Promise<true|string>`
+- `match(fieldName)` — cross-field equality check via `allValues[fieldName]`
+
+## useFormField(form, name)
+
+Convenience hook — delegates to `form.field(name)`.
+
+| Key | Type | Source |
+|-----|------|--------|
+| `value` | `() => any` | `field.value` |
+| `setValue` | `(any) => void` | `field.setValue` |
+| `error` | `() => string \| null` | `field.error` |
+| `errors` | `() => string[]` | `field.errors` |
+| `touched` | `() => boolean` | `field.touched` |
+| `dirty` | `() => boolean` | `field.dirty` |
+| `valid` | `() => boolean` | `field.valid` |
+| `onBlur` | `() => void` | `field.setTouched` |
+| `bind` | `() => BindProps` | `field.bind` |
+
+## fieldArray(name)
+
+Returned by `form.fieldArray(name)`. Initial value from `config.fields[name].value` (must be array).
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `items()` | `() => any[]` | Signal — current array |
+| `length()` | `() => number` | Memo — item count |
+| `append(value)` | `(any) => void` | Add to end |
+| `prepend(value)` | `(any) => void` | Add to beginning |
+| `remove(index)` | `(number) => void` | Remove at index |
+| `move(from, to)` | `(number, number) => void` | Move item between indices |
+| `swap(a, b)` | `(number, number) => void` | Swap two items |
+| `replace(index, value)` | `(number, any) => void` | Replace item at index |
+
+## Integration Example
+
+```javascript
+import { tags } from 'decantr/tags';
+import { css } from 'decantr/css';
+import { createForm, validators } from 'decantr/form';
+import { Input, Button, Text } from 'decantr/components';
+import { cond, text } from 'decantr/core';
+
+const { form: formEl, div } = tags;
+
+const form = createForm({
+  fields: {
+    email: { value: '', validators: [validators.required(), validators.email()] },
+    password: { value: '', validators: [validators.required(), validators.minLength(8)] },
+  },
+  validateOn: 'onBlur',
+  async onSubmit(values) {
+    await fetch('/api/login', { method: 'POST', body: JSON.stringify(values) });
+  },
+});
+
+formEl({ class: css('_flex _col _gap4 _mw[24rem]'), onsubmit: (e) => { e.preventDefault(); form.submit(); } },
+  div({ class: css('_flex _col _gap1') },
+    Input({ type: 'email', placeholder: 'Email', ...form.field('email').bind() }),
+    cond(() => form.fields.email.touched() && form.fields.email.error(),
+      () => Text({ class: css('_fgdestructive _textSm') }, text(() => form.fields.email.error()))
+    ),
+  ),
+  div({ class: css('_flex _col _gap1') },
+    Input({ type: 'password', placeholder: 'Password', ...form.field('password').bind() }),
+    cond(() => form.fields.password.touched() && form.fields.password.error(),
+      () => Text({ class: css('_fgdestructive _textSm') }, text(() => form.fields.password.error()))
+    ),
+  ),
+  Button({ type: 'submit', disabled: () => form.isSubmitting() }, 'Login'),
+);
+```
+
+## Async Validation
+
+```javascript
+const form = createForm({
+  fields: {
+    username: {
+      value: '',
+      validators: [
+        validators.required(),
+        validators.minLength(3),
+        validators.async(async (value) => {
+          const res = await fetch(`/api/check-username?u=${value}`);
+          const { available } = await res.json();
+          return available ? true : 'Username already taken';
+        }),
+      ],
+    },
+  },
+});
+```
+
+Async validators auto-debounce (300ms). They only execute when all sync validators pass. Pending async validation does not block — errors update reactively when the promise resolves.
+
+## Error Handling
+
+### Server-side errors
+
+```javascript
+const form = createForm({
+  fields: { email: { value: '' }, password: { value: '' } },
+  async onSubmit(values, form) {
+    const res = await fetch('/api/login', { method: 'POST', body: JSON.stringify(values) });
+    if (!res.ok) {
+      const { errors } = await res.json();
+      form.setErrors(errors); // { email: 'Not found', password: 'Incorrect' }
+    }
+  },
+});
+```
+
+### Cross-field validation
+
+```javascript
+const form = createForm({
+  fields: {
+    password: { value: '' },
+    confirm: { value: '' },
+  },
+  validate(values) {
+    const errs = {};
+    if (values.password !== values.confirm) {
+      errs.confirm = ['Passwords do not match'];
+    }
+    return errs;
+  },
+});
+```
+
+Cross-field `validate` runs during `form.validate()` and `form.submit()`, after all per-field validators pass.
+
+### Per-field imperative errors
+
+```javascript
+form.field('email').setError('This email is banned');
+```
+
+Cleared on next `setValue` or `reset`.
+
+---
+
+**See also:** `reference/component-lifecycle.md`, `reference/atoms.md`

package/reference/i18n.md

@@ -0,0 +1,336 @@
+# Internationalization (i18n)
+
+Decantr's i18n module provides reactive locale management, translation with interpolation, pluralization via `Intl.PluralRules`, RTL/LTR direction control, and runtime message merging. Zero external dependencies.
+
+## Quick Start
+
+```js
+import { createI18n } from 'decantr/i18n';
+
+const { t, setLocale, setDirection } = createI18n({
+  locale: 'en',
+  fallbackLocale: 'en',
+  messages: {
+    en: {
+      nav: { home: 'Home', about: 'About' },
+      greeting: 'Hello, {name}!',
+      items_one: '{count} item',
+      items_other: '{count} items'
+    },
+    fr: {
+      nav: { home: 'Accueil', about: 'A propos' },
+      greeting: 'Bonjour, {name} !',
+      items_one: '{count} article',
+      items_other: '{count} articles'
+    }
+  }
+});
+
+t('nav.home');                        // "Home"
+t('greeting', { name: 'Alice' });    // "Hello, Alice!"
+t('items', { count: 3 });            // "3 items"
+
+setLocale('fr');
+t('nav.home');                        // "Accueil"
+```
+
+## API
+
+### `createI18n(config): I18nInstance`
+
+Creates a reactive i18n instance.
+
+**Config:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `locale` | `string` | Yes | Initial locale (e.g. `'en'`, `'fr'`, `'ar'`) |
+| `messages` | `Record<string, Record<string, any>>` | Yes | Messages keyed by locale |
+| `fallbackLocale` | `string` | No | Locale to use when key is missing in the active locale |
+
+**Returns:**
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `t` | `(key: string, params?: Record<string, any>) => string` | Translate a key |
+| `locale` | `() => string` | Signal getter for current locale |
+| `setLocale` | `(locale: string) => void` | Set the active locale |
+| `setDirection` | `(dir: 'ltr' \| 'rtl') => void` | Set `dir` attribute on `<html>` |
+| `addMessages` | `(locale: string, messages: Record<string, any>) => void` | Merge messages into a locale |
+
+## Translation Keys
+
+### Dot Notation
+
+Keys use dot-delimited paths to navigate nested message objects:
+
+```js
+const messages = {
+  en: {
+    nav: {
+      home: 'Home',
+      settings: {
+        profile: 'Profile',
+        security: 'Security'
+      }
+    }
+  }
+};
+
+t('nav.home');                  // "Home"
+t('nav.settings.profile');     // "Profile"
+```
+
+### Interpolation
+
+Use `{param}` placeholders. Values are converted to strings automatically:
+
+```js
+const messages = {
+  en: {
+    welcome: 'Welcome, {name}!',
+    stats: '{count} views in {days} days'
+  }
+};
+
+t('welcome', { name: 'Alice' });           // "Welcome, Alice!"
+t('stats', { count: 1200, days: 7 });      // "1200 views in 7 days"
+```
+
+Unmatched placeholders are left as-is:
+
+```js
+t('welcome');                               // "Welcome, {name}!"
+t('welcome', {});                           // "Welcome, {name}!"
+```
+
+### Pluralization
+
+Pass a `count` parameter to trigger pluralization. The system appends a suffix to the key using `Intl.PluralRules`:
+
+| Suffix | English Example |
+|--------|----------------|
+| `_zero` | count = 0 (some languages) |
+| `_one` | count = 1 |
+| `_two` | count = 2 (Arabic, Welsh, etc.) |
+| `_few` | count = 2-4 (Slavic languages) |
+| `_many` | count = 5-20 (Slavic languages) |
+| `_other` | Everything else |
+
+```js
+const messages = {
+  en: {
+    items_one: '{count} item',
+    items_other: '{count} items'
+  }
+};
+
+t('items', { count: 0 });     // "0 items"    (_other in English)
+t('items', { count: 1 });     // "1 item"     (_one)
+t('items', { count: 42 });    // "42 items"   (_other)
+```
+
+If the plural-suffixed key is not found, the base key is used:
+
+```js
+const messages = { en: { items: 'Items' } };
+
+t('items', { count: 5 });     // "Items" (base key fallback)
+```
+
+Pluralization works with interpolation:
+
+```js
+const messages = {
+  en: {
+    cart_one: 'Your cart has {count} item ({total})',
+    cart_other: 'Your cart has {count} items ({total})'
+  }
+};
+
+t('cart', { count: 3, total: '$45.00' });
+// "Your cart has 3 items ($45.00)"
+```
+
+## Fallback Chain
+
+When a key is not found in the current locale, the system tries:
+
+1. Current locale messages
+2. Fallback locale messages (if configured)
+3. The raw key string
+
+```js
+const { t, setLocale } = createI18n({
+  locale: 'de',
+  fallbackLocale: 'en',
+  messages: {
+    en: { save: 'Save', cancel: 'Cancel' },
+    de: { save: 'Speichern' }
+  }
+});
+
+t('save');     // "Speichern"  (found in de)
+t('cancel');   // "Cancel"     (fallback to en)
+t('missing');  // "missing"    (key returned)
+```
+
+## Reactivity
+
+The `t()` function reads the internal locale signal, so it integrates with Decantr's reactive system:
+
+```js
+import { createEffect, createMemo } from 'decantr/state';
+
+const { t, setLocale } = createI18n({ ... });
+
+// Effect re-runs when locale changes
+createEffect(() => {
+  document.title = t('page.title');
+});
+
+// Memo derives from t()
+const greeting = createMemo(() => t('welcome', { name: userName() }));
+
+// Locale change triggers all reactive consumers
+setLocale('fr');
+```
+
+The `locale()` getter is also a signal:
+
+```js
+createEffect(() => {
+  console.log('Locale changed to:', locale());
+});
+```
+
+## RTL Support
+
+Use `setDirection()` to set the `dir` attribute on the `<html>` element:
+
+```js
+const { setLocale, setDirection } = createI18n({ ... });
+
+function switchToArabic() {
+  setLocale('ar');
+  setDirection('rtl');
+}
+
+function switchToEnglish() {
+  setLocale('en');
+  setDirection('ltr');
+}
+```
+
+Combine with Decantr's RTL logical property atoms (`_mis`, `_mie`, `_pis`, `_pie`) for layout adaptation:
+
+```js
+import { css } from 'decantr/css';
+
+// These atoms use CSS logical properties, so they automatically
+// flip in RTL mode when dir="rtl" is set on <html>
+div({ class: css('_flex _gap4 _pis4 _pie4') }, ...children);
+```
+
+## Runtime Message Loading
+
+Use `addMessages()` to load translations lazily:
+
+```js
+const { t, setLocale, addMessages } = createI18n({
+  locale: 'en',
+  fallbackLocale: 'en',
+  messages: { en: { loading: 'Loading...' } }
+});
+
+// Load locale on demand
+async function loadLocale(locale) {
+  const res = await fetch(`/locales/${locale}.json`);
+  const messages = await res.json();
+  addMessages(locale, messages);
+  setLocale(locale);
+}
+```
+
+`addMessages()` deep-merges into existing messages, so you can load partial translations:
+
+```js
+// Initial load
+addMessages('en', { common: { save: 'Save' } });
+
+// Later: add page-specific translations
+addMessages('en', { dashboard: { title: 'Dashboard' } });
+
+// Both work:
+t('common.save');       // "Save"
+t('dashboard.title');   // "Dashboard"
+```
+
+## Usage with Components
+
+```js
+import { createI18n } from 'decantr/i18n';
+import { Button, Input } from 'decantr/components';
+import { tags } from 'decantr/tags';
+import { text } from 'decantr/core';
+
+const { t } = createI18n({
+  locale: 'en',
+  messages: {
+    en: {
+      form: {
+        email: 'Email address',
+        password: 'Password',
+        submit: 'Sign In',
+        forgot: 'Forgot password?'
+      }
+    }
+  }
+});
+
+const { div, h2, a } = tags;
+
+function LoginForm() {
+  return div(
+    h2({}, text(() => t('form.submit'))),
+    Input({ placeholder: t('form.email'), type: 'email' }),
+    Input({ placeholder: t('form.password'), type: 'password' }),
+    Button({}, text(() => t('form.submit'))),
+    a({ href: '#' }, text(() => t('form.forgot')))
+  );
+}
+```
+
+## Message File Organization
+
+Recommended structure for larger apps:
+
+```
+src/
+  locales/
+    en/
+      common.json     # Shared keys (nav, buttons, errors)
+      dashboard.json  # Dashboard page
+      settings.json   # Settings page
+    fr/
+      common.json
+      dashboard.json
+      settings.json
+```
+
+Load and merge at startup:
+
+```js
+import common from './locales/en/common.json' with { type: 'json' };
+import dashboard from './locales/en/dashboard.json' with { type: 'json' };
+
+const { t } = createI18n({
+  locale: 'en',
+  messages: {
+    en: { common, dashboard }
+  }
+});
+
+t('common.save');        // "Save"
+t('dashboard.title');    // "Dashboard"
+```