native-document 1.0.166 → 1.0.168

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);
+    })
+```

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

@@ -0,0 +1,90 @@
+---
+title: ImageField
+description: Image upload field with preview, crop, and dimension validation
+---
+
+# ImageField
+
+```javascript
+import { ImageField } from 'native-document/components';
+
+ImageField(name, props?)
+```
+
+`ImageField` extends `FileField` and is pre-configured for single image uploads. It adds image-specific validation (dimensions, aspect ratio) on top of the full `FileField` API.
+
+## Default Renderer
+
+```javascript
+import { FileFieldRender, FileNativeModeRender } from 'native-document/ui';
+
+ImageField.use(FileFieldRender);
+```
+
+## Methods
+
+All `FileField` methods apply (`accept`, `maxSize`, `mode`, `onFileAdd`…). See **[FileField](./file-field.md)** for the full reference. Image-specific additions:
+
+| Method | Parameters | Description |
+|---|---|---|
+| `.maxWidth(px)` | `px: number` | Maximum image width in px |
+| `.maxHeight(px)` | `px: number` | Maximum image height in px |
+| `.crop(enabled?)` | `enabled?: boolean` | Enable image cropping before upload |
+| `.dimensions(w, h, message?)` | `w: number`, `h: number`, `message?: string` | Validate exact dimensions |
+| `.maxDimensions(w, h, message?)` | `w: number`, `h: number`, `message?: string` | Validate maximum dimensions |
+| `.minDimensions(w, h, message?)` | `w: number`, `h: number`, `message?: string` | Validate minimum dimensions |
+| `.aspectRatio(ratio, message?)` | `ratio: string`, `message?: string` | Validate aspect ratio (e.g. `'16:9'`, `'1:1'`) |
+
+## ImageField vs FileField
+
+Use `ImageField` when you need image-specific validation (dimensions, aspect ratio, crop). Use `FileField` when you need multiple file types or multi-file upload.
+
+| | ImageField | FileField |
+|---|---|---|
+| Single image | Yes (default) | Yes (with `.accept`) |
+| Multiple files | No | Yes (`.multiple()`) |
+| Dimension validation | Yes | No |
+| Aspect ratio validation | Yes | No |
+| Crop | Yes | No |
+| All upload modes | Yes (via inheritance) | Yes |
+
+## Example
+
+```javascript
+ImageField('cover')
+    .label('Cover Image')
+    .model(imageUrl)
+    .accept(['image/jpeg', 'image/png'])
+    .maxSize(5 * 1024 * 1024, 'Max 5MB')
+    .maxDimensions(2000, 2000, 'Image too large')
+    .aspectRatio('16:9', 'Must be 16:9')
+    .crop()
+```
+
+## Avatar example
+
+```javascript
+import { FileAvatarMode } from 'native-document/components';
+import { FileAvatarModeRender } from 'native-document/ui';
+
+FileAvatarMode.use(FileAvatarModeRender);
+
+ImageField('avatar')
+    .label('Profile picture')
+    .model(avatarUrl)
+    .accept(['image/jpeg', 'image/png', 'image/webp'])
+    .maxSize(2 * 1024 * 1024, 'Max 2MB')
+    .aspectRatio('1:1', 'Must be square')
+    .crop()
+    .mode(
+        FileAvatarMode()
+            .hoverOverlay()
+            .circle()
+    )
+```
+
+---
+
+## Next Steps
+
+- **[FileField](./file-field.md)** - Full file upload reference