native-document 1.0.15 → 1.0.16-8.1

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

package/docs/components/form/index.md

@@ -0,0 +1,115 @@
+---
+title: Form Fields
+description: Overview of all form field components and the shared Field API
+---
+
+# Form Fields
+
+NativeDocument provides a complete set of form field components. All fields extend `Field` which provides a consistent API for binding, validation, labels, and rendering.
+
+```javascript
+import { Field } from 'native-document/components';
+import { FieldRender } from 'native-document/ui';
+
+Field.use(FieldRender);
+```
+
+---
+
+## Shared Field API
+
+All form fields share the following methods:
+
+### Binding
+
+```javascript
+.model(observable)
+.bind(observable)  // alias
+.default('value')
+```
+
+### Labels & hints
+
+```javascript
+.label('Email address')
+.placeholder('you@example.com')
+.help('We will never share your email.')
+.hint('Required')
+```
+
+### State
+
+```javascript
+.disabled(Observable(false))
+.readonly(true)
+.clearable()
+```
+
+### Slots
+
+```javascript
+.leading(Icon)        // prefix
+.trailing(Icon)       // suffix
+.bottom(Div('hint'))  // below the input
+```
+
+### HTML attributes
+
+```javascript
+.wrapperProps({ class: 'form-group' })
+.inputProps({ autocomplete: 'off' })
+.labelProps({ class: 'form-label' })
+.errorProps({ class: 'invalid-feedback' })
+.hintProps({ class: 'form-text' })
+```
+
+### Validation
+
+```javascript
+.required('This field is required')
+.requiredIf(condition, 'Required when condition is true')
+.custom((value, allValues) => {
+    if (value.startsWith('bad')) {
+        return 'Value cannot start with "bad"';
+    }
+    return true; // pass
+})
+.validateOn('blur')     // 'blur' | 'input' | 'change'
+.clearErrorOn('focus')  // 'focus' | 'input'
+.setError('Server-side error')
+.showErrors()
+.hideErrors()
+.validate(allValues)    // returns true | false
+```
+
+### Observables on `$description`
+
+```javascript
+field.$description.hasErrors  // Observable<boolean>
+field.$description.errors     // ObservableArray
+field.$description.isDirty    // Observable<boolean>
+field.$description.isTouched  // Observable<boolean>
+field.$description.focus      // Observable<boolean>
+```
+
+---
+
+## Available Fields
+
+| File | Components |
+|---|---|
+| [String Field](./string-field.md) | `StringField`, `EmailField`, `PasswordField`, `TelField`, `UrlField`, `HiddenField` |
+| [Number Field](./number-field.md) | `NumberField`, `RangeField` |
+| [Textarea Field](./textarea-field.md) | `TextAreaField` |
+| [Date Field](./date-field.md) | `DateField`, `TimeField` |
+| [Select Field](./select-field.md) | `SelectField` |
+| [Autocomplete Field](./autocomplete-field.md) | `AutocompleteField` |
+| [Checkbox Field](./checkbox-field.md) | `CheckboxField` |
+| [Checkbox Group Field](./checkbox-group-field.md) | `CheckboxGroupField` |
+| [Radio Field](./radio-field.md) | `RadioField` |
+| [Color Field](./color-field.md) | `ColorField` |
+| [File Field](./file-field.md) | `FileField` + all modes |
+| [Image Field](./image-field.md) | `ImageField` |
+| [Slider](./slider.md) | `Slider` |
+| [Field Collection](./field-collection.md) | `FieldCollection` |
+| [Form Control](./form-control.md) | `FormControl` |

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

@@ -0,0 +1,65 @@
+---
+title: Number Fields
+description: NumberField and RangeField for numeric input
+---
+
+# Number Fields
+
+```javascript
+import { NumberField, RangeField } from 'native-document/components';
+```
+
+## Default Renderers
+
+```javascript
+import { NumberFieldRender, RangeFieldRender } from 'native-document/ui';
+
+NumberField.use(NumberFieldRender);
+RangeField.use(RangeFieldRender);
+```
+
+---
+
+## `NumberField`
+
+```javascript
+NumberField('quantity')
+    .label('Quantity')
+    .model(quantity)
+    .min(1, 'Minimum 1')
+    .max(100, 'Maximum 100')
+    .step(1)
+    .required()
+```
+
+### Additional methods
+
+```javascript
+.min(value, message?)
+.max(value, message?)
+.between(min, max, message?)
+.integer(message?)
+.positive(message?)
+.unsigned(message?)   // alias for positive
+.negative(message?)
+.multipleOf(n, message?)
+.step(value)
+.decimals(count?)
+.prefix(text)
+.suffix(text)
+```
+
+---
+
+## `RangeField`
+
+A range slider bound to a field model.
+
+```javascript
+RangeField('volume')
+    .label('Volume')
+    .model(volume)
+    .min(0)
+    .max(100)
+    .step(5)
+```

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

@@ -0,0 +1,51 @@
+---
+title: RadioField
+description: Group of radio buttons where only one can be selected
+---
+
+# RadioField
+
+```javascript
+import { RadioField } from 'native-document/components';
+
+RadioField(name, props?)
+```
+
+## Default Renderer
+
+```javascript
+import { RadioFieldRender } from 'native-document/ui';
+
+RadioField.use(RadioFieldRender);
+```
+
+## Methods
+
+| Method | Parameters | Description |
+|---|---|---|
+| `.model(observable)` | `observable: Observable` | Two-way binding - value of the selected option |
+| `.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 radio option |
+| `.options(items)` | `items: { value, label }[]` | Add multiple options at once |
+| `.layout(type)` | `'vertical' \| 'horizontal' \| 'grid'` | Layout of the radio buttons. Default `'vertical'` |
+| `.vertical()` | - | Shorthand for `.layout('vertical')` |
+| `.horizontal()` | - | Shorthand for `.layout('horizontal')` |
+| `.grid()` | - | Shorthand for `.layout('grid')` |
+| `.required(message?)` | `message?: string` | Validation - field required |
+| `.checked()` | - | Returns the current checked value (getter) |
+
+## Example
+
+```javascript
+const plan = Observable('monthly');
+
+RadioField('plan')
+    .label('Choose a plan')
+    .model(plan)
+    .option('monthly',  'Monthly - $9/mo')
+    .option('yearly',   'Yearly - $99/yr')
+    .option('lifetime', 'Lifetime - $299')
+    .horizontal()
+    .required('Please select a plan')
+```

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

@@ -0,0 +1,123 @@
+---
+title: SelectField
+description: Select dropdown with search, multiple selection, groups, and custom item rendering
+---
+
+# SelectField
+
+```javascript
+import { SelectField } from 'native-document/components';
+
+SelectField(name, props?)
+```
+
+## Default Renderer
+
+```javascript
+import { SelectFieldRender } from 'native-document/ui';
+
+SelectField.use(SelectFieldRender);
+```
+
+## Methods
+
+### Options
+
+```javascript
+.option(value, label, props?)
+.option('fr', 'France')
+.option('de', 'Germany', { disabled: true })
+.options([
+    { value: 'fr', label: 'France' },
+    { value: 'de', label: 'Germany' }
+])
+.options(Observable.array([...]))  // reactive
+```
+
+### Groups
+
+```javascript
+.groups([
+    {
+        label: 'Europe',
+        options: [
+            { value: 'fr', label: 'France' },
+            { value: 'de', label: 'Germany' }
+        ]
+    },
+    {
+        label: 'Africa',
+        options: [
+            { value: 'sn', label: 'Senegal' }
+        ]
+    }
+])
+```
+
+### Multiple selection
+
+```javascript
+.multiple()
+.multipleDisplayAsText()          // "France, Germany"
+.multipleDisplayAsTags()          // tag chips
+.multipleDisplayAsCount()         // "3 selected"
+.multipleDisplayAsTruncate(2)     // "France, Germany +1"
+.removeSelected()                 // hide selected options from the list
+```
+
+### Binding & behavior
+
+```javascript
+.model(Observable(null))          // single selection
+.model(Observable([]))            // multiple selection
+.searchable()
+.searchable(true, 'Search...')
+.clearable()
+.disabled(Observable(false))
+.onChange((value) => console.log(value))
+```
+
+### Custom rendering
+
+```javascript
+.renderItem(($option) =>
+    HStack([
+        Img({ src: `/flags/${$option.value}.svg`, width: 20 }),
+        Span($option.label)
+    ]).spacing(8)
+)
+.selectedLabelRender(($option) => `${$option.label} (${$option.value})`)
+.countRender((count) => `${count} countries selected`)
+.truncateRender((visible, hidden) => `${visible} +${hidden} more`)
+```
+
+## Example
+
+```javascript
+SelectField('country')
+    .label('Country')
+    .model(country)
+    .searchable()
+    .clearable()
+    .options(countriesList)
+    .required('Please select a country')
+    .onChange((value) => loadRegions(value))
+```
+
+## Multiple selection example
+
+```javascript
+const selected = Observable([]);
+
+SelectField('tags')
+    .label('Tags')
+    .model(selected)
+    .multiple()
+    .multipleDisplayAsTags()
+    .removeSelected()
+    .options([
+        { value: 'js',  label: 'JavaScript' },
+        { value: 'ts',  label: 'TypeScript' },
+        { value: 'py',  label: 'Python' },
+    ])
+```

package/docs/components/form/slider.md

@@ -0,0 +1,136 @@
+---
+title: Slider
+description: Range input component with single value, range mode, marks, and tooltips
+---
+
+# Slider
+
+```javascript
+import { Slider } from 'native-document/components';
+
+Slider(name, props?)
+```
+
+## Default Renderer
+
+```javascript
+import { SliderFieldRender } from 'native-document/ui';
+
+Slider.use(SliderFieldRender);
+```
+
+## Methods
+
+### Value
+
+| Method | Parameters | Description |
+|---|---|---|
+| `.model(observable)` | `observable: Observable<number>` | Two-way binding for single value |
+| `.modelStart(observable)` | `observable: Observable<number>` | Two-way binding for range start |
+| `.modelEnd(observable)` | `observable: Observable<number>` | Two-way binding for range end |
+| `.defaultValue(value)` | `value: number` | Initial value |
+| `.range(enabled?)` | `enabled?: boolean` | Enable range mode (two handles) |
+| `.min(value)` | `value: number` | Minimum value |
+| `.max(value)` | `value: number` | Maximum value |
+| `.step(value)` | `value: number` | Step increment |
+
+### Display
+
+| Method | Parameters | Description |
+|---|---|---|
+| `.showValue(enabled?)` | `enabled?: boolean` | Display the current value |
+| `.showTooltip(enabled?)` | `enabled?: boolean` | Show tooltip on the handle |
+| `.tooltipFormat(fn)` | `fn: (value) => string` | Format the tooltip value |
+| `.renderTooltip(fn)` | `fn: ($description) => NdChild` | Custom tooltip renderer |
+| `.renderThumb(fn)` | `fn: ($description) => NdChild` | Custom thumb renderer |
+| `.renderCursor(fn)` | `fn: ($description) => NdChild` | Custom cursor renderer |
+
+### Marks
+
+| Method | Parameters | Description |
+|---|---|---|
+| `.marks(marks)` | `marks: { value, label }[]` | Define tick marks |
+| `.showMarks(enabled?)` | `enabled?: boolean` | Show tick marks |
+| `.snapToMarks(enabled?)` | `enabled?: boolean` | Snap handle to nearest mark |
+
+### Style
+
+| Method | Parameters | Description |
+|---|---|---|
+| `.primary()` | - | Primary color variant |
+| `.secondary()` | - | Secondary color variant |
+| `.success()` | - | Success color variant |
+| `.warning()` | - | Warning color variant |
+| `.danger()` | - | Danger color variant |
+| `.info()` | - | Info color variant |
+| `.color(hex)` | `hex: string` | Custom handle color |
+| `.trackColor(hex)` | `hex: string` | Custom track color |
+| `.fillColor(hex)` | `hex: string` | Custom fill color |
+| `.fullColor(hex)` | `hex: string` | Color for the full track |
+
+### Layout
+
+| Method | Parameters | Description |
+|---|---|---|
+| `.vertical(enabled?)` | `enabled?: boolean` | Vertical orientation |
+| `.height(px)` | `px: number` | Height in px (vertical mode) |
+| `.reverse(enabled?)` | `enabled?: boolean` | Reverse the track direction |
+
+### State
+
+| Method | Parameters | Description |
+|---|---|---|
+| `.disabled(condition?)` | `condition?: boolean \| Observable<boolean>` | Disable the slider |
+| `.readonly(condition?)` | `condition?: boolean` | Read-only mode |
+
+### Events
+
+| Method | Parameters | Description |
+|---|---|---|
+| `.onChange(handler)` | `handler: (value) => void` | Fires on every value change |
+| `.onComplete(handler)` | `handler: (value) => void` | Fires when the user releases the handle |
+
+## Example
+
+```javascript
+// Single value
+const volume = Observable(70);
+
+Slider('volume')
+    .model(volume)
+    .min(0)
+    .max(100)
+    .step(5)
+    .showTooltip()
+    .tooltipFormat((v) => `${v}%`)
+    .primary()
+
+// Range
+const priceMin = Observable(100);
+const priceMax = Observable(500);
+
+Slider('price')
+    .range()
+    .modelStart(priceMin)
+    .modelEnd(priceMax)
+    .min(0)
+    .max(1000)
+    .step(50)
+    .showValue()
+
+// Vertical with marks
+Slider('temperature')
+    .model(Observable(20))
+    .min(-10)
+    .max(40)
+    .vertical()
+    .height(200)
+    .marks([
+        { value: -10, label: '-10' },
+        { value: 0,   label: '0'   },
+        { value: 20,  label: '20'  },
+        { value: 40,  label: '40'  }
+    ])
+    .showMarks()
+    .snapToMarks()
+```

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

@@ -0,0 +1,134 @@
+---
+title: String Fields
+description: StringField, EmailField, PasswordField, TelField, UrlField, HiddenField
+---
+
+# String Fields
+
+```javascript
+import {
+    StringField, EmailField, PasswordField,
+    TelField, UrlField, HiddenField
+} from 'native-document/components';
+```
+
+## Default Renderers
+
+```javascript
+import {
+    StringFieldRender, EmailFieldRender, PasswordFieldRender,
+    TelFieldRender, UrlFieldRender, HiddenFieldRender
+} from 'native-document/ui';
+
+StringField.use(StringFieldRender);
+EmailField.use(EmailFieldRender);
+PasswordField.use(PasswordFieldRender);
+TelField.use(TelFieldRender);
+UrlField.use(UrlFieldRender);
+HiddenField.use(HiddenFieldRender);
+```
+
+---
+
+## `StringField`
+
+```javascript
+StringField('username')
+    .label('Username')
+    .placeholder('Choose a username')
+    .model(username)
+    .required()
+    .minLength(3, 'At least 3 characters')
+    .maxLength(20)
+    .pattern(/^[a-z0-9_]+$/, 'Lowercase, numbers, underscores only')
+```
+
+### Additional methods
+
+```javascript
+.minLength(min, message?)
+.maxLength(max, message?)
+.length(exact, message?)
+.pattern(regex, message?)
+.alphaOnly(message?)
+.numericOnly(message?)
+.alphaNumeric(message?)
+.noSpaces(message?)
+.lowercase(message?)
+.uppercase(message?)
+```
+
+---
+
+## `EmailField`
+
+```javascript
+EmailField('email')
+    .label('Email')
+    .model(email)
+    .required()
+    .allowedDomain(['company.com'], 'Only company emails allowed')
+```
+
+### Additional methods
+
+```javascript
+.email(message?)
+.allowedDomain(domains, message?)
+.notAllowedDomain(domains, message?)
+```
+
+---
+
+## `PasswordField`
+
+```javascript
+PasswordField('password')
+    .label('Password')
+    .model(password)
+    .required()
+    .minLength(8)
+    .strong('Password is too weak')
+    .visibilityToggle()
+    .showStrengthMeter()
+```
+
+### Additional methods
+
+```javascript
+.strong(message?)
+.containsNumber(message?)
+.containsUppercase(message?)
+.containsLowercase(message?)
+.containsSpecialChar(message?)
+.visibilityToggle(enabled?, icons?)
+.visibilityIcons(showIcon, hideIcon)
+.showStrengthMeter()
+.strengthLabels({ weak, fair, good, strong })
+.same(fieldName, message?)      // must match another field
+.different(fieldName, message?) // must differ from another field
+```
+
+---
+
+## `TelField`
+
+```javascript
+TelField('phone').label('Phone').model(phone)
+```
+
+---
+
+## `UrlField`
+
+```javascript
+UrlField('website').label('Website').model(url)
+```
+
+---
+
+## `HiddenField`
+
+```javascript
+HiddenField('csrf').model(csrfToken)
+```