native-document 1.0.15 → 1.0.16-8.2

package/docs/components/form/autocomplete-field.md

@@ -0,0 +1,81 @@
+---
+title: AutocompleteField
+description: Text input with suggestions from a data source, with debounce and async support
+---
+
+# AutocompleteField
+
+```javascript
+import { AutocompleteField } from 'native-document/components';
+
+AutocompleteField(name, props?)
+```
+
+## Default Renderer
+
+```javascript
+import { AutocompleteFieldRender } from 'native-document/ui';
+
+AutocompleteField.use(AutocompleteFieldRender);
+```
+
+## Methods
+
+| Method | Parameters | Description |
+|---|---|---|
+| `.source(dataSource)` | `dataSource: *[] \| ObservableArray \| (query: string) => Promise<*[]>` | Static array, reactive array, or async function |
+| `.labelKey(key)` | `key: string` | Property to display in the suggestion list. Default `'label'` |
+| `.valueKey(key)` | `key: string` | Property to use as the bound value. Default `'id'` |
+| `.minChars(n)` | `n: number` | Minimum characters before triggering source. Default `2` |
+| `.debounce(ms)` | `ms: number` | Wait after typing stops before calling source. Default `300` |
+| `.maxResults(n)` | `n: number` | Maximum number of suggestions shown. Default `10` |
+| `.clearable()` | - | Show a clear button |
+| `.required(message?)` | `message?: string` | Validation - field required |
+| `.oneOf(values, message?)` | `values: *[]`, `message?: string` | Restrict value to a predefined list |
+| `.onSelect(handler)` | `handler: (item) => void` | Fired when a suggestion is selected |
+| `.renderItem(fn)` | `fn: (item) => NdChild` | Custom suggestion item renderer |
+
+## Static source example
+
+```javascript
+const country = Observable(null);
+
+AutocompleteField('country')
+    .label('Country')
+    .model(country)
+    .source(Observable.array(countries))
+    .labelKey('name')
+    .valueKey('code')
+    .placeholder('Search country...')
+    .minChars(1)
+    .required()
+```
+
+## Async source example
+
+```javascript
+const userId = Observable(null);
+
+AutocompleteField('user')
+    .label('Assign to')
+    .model(userId)
+    .source(async (query) => {
+        const res = await fetch(`/api/users?q=${query}`);
+        return res.json();
+    })
+    .labelKey('name')
+    .valueKey('id')
+    .minChars(2)
+    .debounce(300)
+    .maxResults(8)
+    .renderItem(($user) =>
+        HStack([
+            Avatar($user.avatar).small(),
+            VStack([
+                Span($user.name),
+                Span({ class: 'text-sm text-muted' }, $user.email)
+            ]).spacing(2)
+        ]).spacing(8)
+    )
+    .onSelect((item) => console.log('Selected:', item.name))
+```

package/docs/components/form/checkbox-field.md

@@ -0,0 +1,41 @@
+---
+title: CheckboxField
+description: Single checkbox with two-way boolean binding
+---
+
+# CheckboxField
+
+```javascript
+import { CheckboxField } from 'native-document/components';
+
+CheckboxField(name, props?)
+```
+
+## Default Renderer
+
+```javascript
+import { CheckboxFieldRender } from 'native-document/ui';
+
+CheckboxField.use(CheckboxFieldRender);
+```
+
+## Methods
+
+| Method | Parameters | Description |
+|---|---|---|
+| `.model(observable)` | `observable: Observable<boolean>` | Two-way boolean binding |
+| `.label(text)` | `text: NdChild` | Label displayed next to the checkbox |
+| `.disabled(val)` | `val: boolean \| Observable<boolean>` | Disable the field |
+| `.required(message?)` | `message?: string` | Validation - field required |
+| `.checked()` | - | Returns the current checked value (getter) |
+
+## Example
+
+```javascript
+const agreed = Observable(false);
+
+CheckboxField('terms')
+    .label('I agree to the terms and conditions')
+    .model(agreed)
+    .required('You must accept the terms')
+```

package/docs/components/form/checkbox-group-field.md

@@ -0,0 +1,54 @@
+---
+title: CheckboxGroupField
+description: Multiple checkboxes where the value is an array of selected values
+---
+
+# CheckboxGroupField
+
+```javascript
+import { CheckboxGroupField } from 'native-document/components';
+
+CheckboxGroupField(name, props?)
+```
+
+## Default Renderer
+
+```javascript
+import { CheckboxGroupFieldRender } from 'native-document/ui';
+
+CheckboxGroupField.use(CheckboxGroupFieldRender);
+```
+
+## Methods
+
+| Method | Parameters | Description |
+|---|---|---|
+| `.model(observable)` | `observable: Observable<*[]>` | Two-way binding - array of selected values |
+| `.label(text)` | `text: NdChild` | Label for the field group |
+| `.disabled(val)` | `val: boolean \| Observable<boolean>` | Disable the field |
+| `.option(value, label, props?)` | `value: *`, `label: NdChild`, `props?: object` | Add a checkbox option |
+| `.options(items)` | `items: { value, label }[]` | Add multiple options at once |
+| `.layout(type)` | `'vertical' \| 'horizontal' \| 'grid'` | Layout of the checkboxes. Default `'vertical'` |
+| `.vertical()` | - | Shorthand for `.layout('vertical')` |
+| `.horizontal()` | - | Shorthand for `.layout('horizontal')` |
+| `.grid()` | - | Shorthand for `.layout('grid')` |
+| `.required(message?)` | `message?: string` | Validation - at least one must be selected |
+| `.minChecked(n, message?)` | `n: number`, `message?: string` | Minimum number of selections |
+| `.maxChecked(n, message?)` | `n: number`, `message?: string` | Maximum number of selections |
+| `.exactChecked(n, message?)` | `n: number`, `message?: string` | Exact number of selections required |
+
+## Example
+
+```javascript
+const interests = Observable([]);
+
+CheckboxGroupField('interests')
+    .label('Select your interests')
+    .model(interests)
+    .option('frontend', 'Frontend')
+    .option('backend',  'Backend')
+    .option('devops',   'DevOps')
+    .option('mobile',   'Mobile')
+    .grid()
+    .minChecked(1, 'Select at least one interest')
+```

package/docs/components/form/color-field.md

@@ -0,0 +1,64 @@
+---
+title: ColorField
+description: Color picker field with format options and presets
+---
+
+# ColorField
+
+```javascript
+import { ColorField } from 'native-document/components';
+
+ColorField(name, props?)
+```
+
+## Default Renderer
+
+```javascript
+import { ColorFieldRender } from 'native-document/ui';
+
+ColorField.use(ColorFieldRender);
+```
+
+## Methods
+
+All shared Field methods apply, plus:
+
+| Method | Parameters | Description |
+|---|---|---|
+| `.format(type)` | `'hex' \| 'rgb'` | Output format |
+| `.presets(colors)` | `colors: string[]` | Array of preset color strings shown as swatches |
+| `.hex(message?)` | `message?: string` | Validate that the value is a valid hex color |
+| `.rgb(message?)` | `message?: string` | Validate that the value is a valid RGB color |
+
+## Example
+
+```javascript
+ColorField('brandColor')
+    .label('Brand Color')
+    .model(color)
+    .format('hex')
+    .presets(['#3b82f6', '#10b981', '#f59e0b', '#ef4444'])
+```
+
+## Reactive theme example
+
+```javascript
+import { Store } from 'native-document';
+
+const ThemeStore = Store.group('theme', (g) => {
+    g.createPersistent('primary', '#3b82f6');
+    g.createPersistent('accent',  '#10b981');
+});
+
+ColorField('primary')
+    .label('Primary color')
+    .model(ThemeStore.use('primary'))
+    .format('hex')
+    .presets(['#3b82f6', '#6366f1', '#8b5cf6', '#ec4899'])
+
+ColorField('accent')
+    .label('Accent color')
+    .model(ThemeStore.use('accent'))
+    .format('hex')
+    .presets(['#10b981', '#14b8a6', '#22c55e', '#84cc16'])
+```

package/docs/components/form/date-field.md

@@ -0,0 +1,92 @@
+---
+title: Date & Time Fields
+description: DateField and TimeField for date and time input
+---
+
+# Date & Time Fields
+
+```javascript
+import { DateField, TimeField } from 'native-document/components';
+```
+
+## Default Renderers
+
+```javascript
+import { DateFieldRender, TimeFieldRender } from 'native-document/ui';
+
+DateField.use(DateFieldRender);
+TimeField.use(TimeFieldRender);
+```
+
+---
+
+## `DateField`
+
+```javascript
+DateField('birthdate')
+    .label('Date of birth')
+    .model(birthdate)
+    .minDate(new Date('1900-01-01'))
+    .maxDate(new Date())
+    .format('DD/MM/YYYY')
+    .required()
+```
+
+### Additional methods
+
+```javascript
+.format(formatString)
+.minDate(date)
+.maxDate(date)
+.min(date, message?)
+.max(date, message?)
+.between(start, end, message?)
+.disabledDates(dates)
+.withTime()
+.range()
+.modelStart(observable)
+.modelEnd(observable)
+.rangeSeparator(string)
+.mondayAsFirstDay()
+.sundayAsFirstDay()
+.locale(locale)
+.timezone(tz)
+.useLocalTimezone()
+.timeStep(seconds)
+.fromToday()
+.untilToday()
+.onChange(handler)
+.onClear(handler)
+```
+
+---
+
+## `TimeField`
+
+```javascript
+TimeField('appointment')
+    .label('Appointment time')
+    .model(time)
+    .min('09:00', 'Too early')
+    .max('18:00', 'Too late')
+    .clearable()
+```
+
+### Additional methods
+
+```javascript
+.format(formatString)
+.step(seconds)
+.clearable()
+.range()
+.modelStart(observable)
+.modelEnd(observable)
+.rangeSeparator(string)
+.min(time, message?)
+.max(time, message?)
+.between(start, end, message?)
+.after(time, message?)
+.before(time, message?)
+.onChange(handler)
+.onClear(handler)
+```

package/docs/components/form/field-collection.md

@@ -0,0 +1,63 @@
+---
+title: FieldCollection
+description: Dynamic list of repeatable field groups with add, remove, and validation
+---
+
+# FieldCollection
+
+```javascript
+import { FieldCollection } from 'native-document/components';
+```
+
+## Default Renderer
+
+```javascript
+import { FieldCollectionRender } from 'native-document/ui';
+
+FieldCollection.use(FieldCollectionRender);
+```
+
+## Methods
+
+```javascript
+// Fields definition
+.fields((group) => {
+    return {
+        name: StringField('name').label('Name').required(),
+        email: EmailField('email').label('Email')
+    }
+})
+
+// Default item value
+.data({ name: '', email: '' })
+
+// Binding
+.model(contacts)
+
+// Render
+.renderItem((fields, index, remove) => element)
+.renderAdd(() => element)
+
+// Animation
+.transition('fade')
+
+// Programmatic
+.add()
+.remove(item)
+.clear()
+.reset()
+.value()     // get all values
+.count()
+.isEmpty()
+
+// Validation
+.min(count, message?)
+.max(count, message?)
+.validate(allValues?)
+
+// Events
+.onChange((items) => console.log(items))
+.onAdd((item) => console.log('Added'))
+.onRemove((item) => console.log('Removed'))
+```
+

package/docs/components/form/file-field.md

@@ -0,0 +1,203 @@
+---
+title: FileField
+description: File upload component with multiple modes - native, dropzone, button, wall, and avatar
+---
+
+# FileField
+
+```javascript
+import {
+    FileField,
+    FileNativeMode, FileDropzoneMode,
+    FileUploadButtonMode, FileWallMode, FileAvatarMode
+} from 'native-document/components';
+```
+
+## Default Renderers
+
+```javascript
+import {
+    FileFieldRender,
+    FileNativeModeRender, FileDropzoneModeRender,
+    FileUploadButtonModeRender, FileWallModeRender, FileAvatarModeRender
+} from 'native-document/ui';
+
+FileField.use(FileFieldRender);
+FileNativeMode.use(FileNativeModeRender);
+FileDropzoneMode.use(FileDropzoneModeRender);
+FileUploadButtonMode.use(FileUploadButtonModeRender);
+FileWallMode.use(FileWallModeRender);
+FileAvatarMode.use(FileAvatarModeRender);
+```
+
+## Methods
+
+### Mode & Accept
+
+| Method | Parameters | Description |
+|---|---|---|
+| `.mode(modeInstance)` | `modeInstance: FileMode` | Set the upload mode |
+| `.accept(mimeTypes)` | `mimeTypes: string[]` | Accepted MIME types |
+| `.mimeTypes(types, message?)` | `types: string[]`, `message?: string` | Validate MIME types |
+| `.extensions(exts, message?)` | `exts: string[]`, `message?: string` | Validate file extensions |
+
+### Limits
+
+| Method | Parameters | Description |
+|---|---|---|
+| `.multiple(enabled?)` | `enabled?: boolean` | Allow multiple files |
+| `.maxFiles(n, message?)` | `n: number`, `message?: string` | Maximum number of files |
+| `.minFiles(n, message?)` | `n: number`, `message?: string` | Minimum number of files |
+| `.maxSize(bytes, message?)` | `bytes: number`, `message?: string` | Maximum file size in bytes |
+| `.minSize(bytes, message?)` | `bytes: number`, `message?: string` | Minimum file size in bytes |
+
+### File management
+
+| Method | Parameters | Description |
+|---|---|---|
+| `.addFile(file)` | `file: File` | Add a single file programmatically |
+| `.addFiles(files)` | `files: File[]` | Add multiple files |
+| `.setFiles(files)` | `files: File[]` | Replace all files |
+| `.removeFile(file)` | `file: File` | Remove a specific file |
+| `.getFiles()` | - | Returns the current file list |
+| `.reset()` | - | Clear all files |
+| `.fileIcon(desc)` | `desc: { type: string, icon: element }` | Icon for a specific MIME type |
+| `.fileIcons(descs)` | `descs: { type, icon }[]` | Icons for multiple MIME types |
+
+### Events
+
+| Method | Parameters | Description |
+|---|---|---|
+| `.onFileAdd(handler)` | `handler: (file, files) => void` | Fires when a file is added |
+| `.onFileRemove(handler)` | `handler: (file, files) => void` | Fires when a file is removed |
+| `.onReset(handler)` | `handler: () => void` | Fires when files are cleared |
+
+## Modes
+
+### `FileNativeMode`
+
+Standard browser file picker. No extra methods.
+
+```javascript
+FileField('document')
+    .accept(['application/pdf'])
+    .mode(FileNativeMode())
+```
+
+### `FileDropzoneMode`
+
+Drag-and-drop area.
+
+| Method | Parameters | Description |
+|---|---|---|
+| `.icon(element)` | `element: NdChild` | Icon displayed in the zone |
+| `.text(text)` | `text: string` | Main label |
+| `.hint(text)` | `text: string` | Secondary hint text |
+| `.height(px)` | `px: number` | Zone height in px |
+| `.removeIcon(element)` | `element: NdChild` | Icon for the remove button |
+| `.renderZone(fn)` | `fn: ($description) => NdChild` | Custom zone renderer |
+
+```javascript
+FileField('files')
+    .multiple()
+    .mode(
+        FileDropzoneMode()
+            .text('Drop files here or click to browse')
+            .hint('PDF, PNG, JPG up to 10MB')
+            .icon(UploadIcon)
+            .height(200)
+    )
+```
+
+### `FileUploadButtonMode`
+
+A button that opens the file picker, with a list of selected files below it.
+
+| Method | Parameters | Description |
+|---|---|---|
+| `.buttonLabel(text)` | `text: string` | Button label |
+| `.buttonIcon(element)` | `element: NdChild` | Button icon |
+| `.showProgress(enabled?)` | `enabled?: boolean` | Show upload progress |
+| `.renderItem(fn)` | `fn: ($file) => NdChild` | Custom file item renderer |
+| `.renderButton(fn)` | `fn: ($description) => NdChild` | Custom button renderer |
+| `.renderList(fn)` | `fn: ($files) => NdChild` | Custom file list renderer |
+
+```javascript
+FileField('attachment')
+    .mode(
+        FileUploadButtonMode()
+            .buttonLabel('Upload File')
+            .buttonIcon(UploadIcon)
+            .showProgress()
+    )
+```
+
+### `FileWallMode`
+
+Grid of file previews with remove buttons.
+
+| Method | Parameters | Description |
+|---|---|---|
+| `.cellSize(px)` | `px: number` | Cell size in px |
+| `.addLabel(text)` | `text: string` | Label on the add button |
+| `.addIcon(element)` | `element: NdChild` | Icon on the add button |
+| `.renderCell(fn)` | `fn: ($file) => NdChild` | Custom file cell renderer |
+| `.renderAdd(fn)` | `fn: () => NdChild` | Custom add button renderer |
+
+```javascript
+FileField('gallery')
+    .multiple()
+    .accept(['image/*'])
+    .mode(
+        FileWallMode()
+            .cellSize(120)
+            .addLabel('Add image')
+            .addIcon(PlusIcon)
+    )
+```
+
+### `FileAvatarMode`
+
+Single image upload styled as a circular avatar.
+
+| Method | Parameters | Description |
+|---|---|---|
+| `.hoverOverlay()` | - | Show edit overlay on hover |
+| `.cornerBadge()` | - | Show a badge in the corner |
+| `.actionButtons()` | - | Show action buttons |
+| `.circle()` | - | Circular shape (default) |
+| `.square()` | - | Square shape |
+| `.size(size)` | `size: string \| number` | Avatar size |
+| `.placeholderIcon(element)` | `element: NdChild` | Icon shown when no image |
+| `.overlayIcon(element)` | `element: NdChild` | Icon shown on hover overlay |
+| `.editImageIcon(element)` | `element: NdChild` | Edit icon |
+| `.changeLabel(text)` | `text: string` | Label for the change action |
+
+```javascript
+FileField('avatar')
+    .accept(['image/*'])
+    .mode(
+        FileAvatarMode()
+            .hoverOverlay()
+            .circle()
+    )
+```
+
+## Example
+
+```javascript
+FileField('documents')
+    .multiple()
+    .maxFiles(10)
+    .accept(['application/pdf'])
+    .maxSize(5 * 1024 * 1024, 'Max 5MB per file')
+    .mode(
+        FileDropzoneMode()
+            .text('Drop PDFs here')
+            .icon(PdfIcon)
+    )
+    .onFileAdd(async (file) => {
+        const url = await uploadFile(file);
+        console.log('Uploaded:', url);
+    })
+```

package/docs/components/form/form-control.md

@@ -0,0 +1,87 @@
+---
+title: FormControl
+description: Form container with group validation, error handling, and submit management
+---
+
+# FormControl
+
+```javascript
+import { FormControl } from 'native-document/components';
+```
+
+## Default Renderer
+
+```javascript
+import { FormControlRender } from 'native-document/ui';
+
+FormControl.use(FormControlRender);
+```
+
+## Methods
+
+```javascript
+// Fields
+.fields((group) => {
+    group.add(StringField('name').label('Name').required())
+    group.add(EmailField('email').label('Email').required())
+})
+.get(fieldName)          // get a field instance by name
+
+// Layout
+.layout(($description) => Div($description.fields))
+
+// Validation
+.validate(allValues?)    // returns Promise<boolean>
+.trigger(...fieldNames)  // trigger specific fields
+.errorsMode('inline')    // 'inline' | 'summary' | 'both'
+.errorsAtTop()
+.errorsAtBottom()
+.errorsPosition(position)
+.renderErrors(($description) => element)
+.dispatchErrors(mapper?)
+.summarizeErrors()
+.dispatchAndSummarize(mapper?)
+.dispatchServerErrors(error)
+
+// State
+.disable(fieldName?)    // disable all or specific field
+.enable(fieldName?)
+.reset()
+.resetField(name)
+
+// Values
+.values()               // returns { name: value } object
+
+// Watch
+.watch(fieldName, (value) => console.log(value))
+
+// Submit
+.onSubmit((values) => {})
+.onPreventSubmit((values) => {})
+.onDebouncedSubmit((values) => {}, delay?)
+.onSuccess((values) => {})
+.onError((error) => {})
+.onChange((values) => {})
+.onReset(() => {})
+.submit(event?)
+```
+
+## Example
+
+```javascript
+const control = FormControl()
+    .fields((group) => {
+        group.add(StringField('name').label('Name').required())
+        group.add(EmailField('email').label('Email').required())
+        group.add(PasswordField('password').label('Password').required().minLength(8))
+    })
+    .onSubmit(async (values) => {
+        const valid = await control.validate();
+        if (valid) {
+            await createUser(values);
+        }
+    })
+    .onError((error) => {
+        control.dispatchErrors(error);
+    })
+```