native-document 1.0.166 → 1.0.168

package/docs/components/form-fields.md

@@ -0,0 +1,372 @@
+---
+title: Form Fields
+description: Complete form field components with built-in validation - StringField, EmailField, PasswordField, NumberField, TextAreaField, DateField, TimeField, ColorField, RangeField, ImageField, AutocompleteField, HiddenField, FieldCollection, FormControl
+---
+
+# Form Fields
+
+```javascript
+import {
+    Field, FormControl, FieldCollection,
+    StringField, EmailField, PasswordField,
+    NumberField, TelField, UrlField, HiddenField,
+    TextAreaField, ColorField, DateField, TimeField,
+    RangeField, ImageField, AutocompleteField
+} from '@native-document/components';
+```
+
+All form fields extend `Field`, which provides a consistent API for labels, validation, binding, and rendering.
+
+---
+
+## `Field` - Base API
+
+All fields share these methods:
+
+### Binding
+
+```javascript
+.model(observable)  // two-way binding - alias: .bind()
+.default('value')   // 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()   // show clear button
+```
+
+### Slots
+
+```javascript
+.leading(Icon)   // prefix content
+.trailing(Icon)  // suffix content
+.bottom(Div('Helper text'))
+```
+
+### Element props
+
+```javascript
+.wrapperProps({ class: 'form-group' })
+.inputProps({ class: 'form-control', autocomplete: 'off' })
+.labelProps({ class: 'form-label' })
+.errorProps({ class: 'invalid-feedback' })
+.hintProps({ class: 'form-text' })
+```
+
+### Validation
+
+All fields use `HasValidation`:
+
+```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' (default: 'blur')
+.clearErrorOn('focus') // 'focus' | 'input' (default: 'focus')
+.showErrors()
+.hideErrors()
+.setError('Server-side error message')
+.validate(allValues)   // returns true | errors array
+```
+
+### Observables
+
+```javascript
+field.value()               // get current value
+field.setValue('new value')
+field.$description.hasErrors   // Observable<boolean>
+field.$description.errors      // ObservableArray
+field.$description.isDirty     // Observable<boolean>
+field.$description.isTouched   // Observable<boolean>
+field.$description.focus       // Observable<boolean>
+```
+
+---
+
+## Text Fields
+
+### `StringField(name, type?, props?)`
+
+General text input. Type defaults to `'text'`.
+
+```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')
+    .nd
+```
+
+### `EmailField(name)`
+
+```javascript
+EmailField('email').label('Email').model(email).required().nd
+```
+
+### `PasswordField(name)`
+
+```javascript
+PasswordField('password')
+    .label('Password')
+    .model(password)
+    .required()
+    .minLength(8)
+    .showToggle()        // show/hide password button
+    .strengthIndicator() // password strength meter
+    .nd
+```
+
+### `TelField(name)` / `UrlField(name)` / `HiddenField(name)`
+
+```javascript
+TelField('phone').label('Phone').model(phone).nd
+UrlField('website').label('Website').model(url).nd
+HiddenField('csrf').model(csrfToken).nd
+```
+
+---
+
+## `TextAreaField(name)`
+
+```javascript
+TextAreaField('message')
+    .label('Message')
+    .placeholder('Write your message...')
+    .model(message)
+    .required()
+    .minLength(10)
+    .maxLength(500)
+    .rows(5)
+    .autoResize()
+    .nd
+```
+
+---
+
+## `NumberField(name)`
+
+```javascript
+NumberField('quantity')
+    .label('Quantity')
+    .model(quantity)
+    .min(1, 'Minimum 1')
+    .max(100, 'Maximum 100')
+    .step(1)
+    .nd
+```
+
+---
+
+## `DateField(name)` / `TimeField(name)`
+
+```javascript
+DateField('birthdate')
+    .label('Date of birth')
+    .model(birthdate)
+    .min('1900-01-01')
+    .max(new Date())
+    .format('DD/MM/YYYY')
+    .nd
+
+TimeField('appointment')
+    .label('Time')
+    .model(time)
+    .min('09:00')
+    .max('18:00')
+    .clearable()
+    .nd
+```
+
+---
+
+## `ColorField(name)`
+
+```javascript
+ColorField('brandColor')
+    .label('Brand Color')
+    .model(color)
+    .format('hex')  // 'hex' | 'rgb' | 'hsl'
+    .nd
+```
+
+---
+
+## `RangeField(name)`
+
+```javascript
+RangeField('volume')
+    .label('Volume')
+    .model(volume)
+    .min(0)
+    .max(100)
+    .step(5)
+    .showValue()
+    .nd
+```
+
+---
+
+## `ImageField(name)`
+
+Image upload with preview:
+
+```javascript
+ImageField('cover')
+    .label('Cover Image')
+    .model(imageUrl)
+    .accept(['image/jpeg', 'image/png'])
+    .maxSize(5 * 1024 * 1024)
+    .preview()
+    .nd
+```
+
+---
+
+## `AutocompleteField(name)`
+
+```javascript
+AutocompleteField('country')
+    .label('Country')
+    .model(country)
+    .source(Observable.array(countries))
+    .searchKey('name')
+    .valueKey('code')
+    .placeholder('Search country...')
+    .minChars(2)
+    .nd
+```
+
+---
+
+## `FormControl` - Form Container
+
+`FormControl` wraps multiple fields and provides group validation:
+
+```javascript
+FormControl(props?)
+    .field(StringField('name').label('Name').required())
+    .field(EmailField('email').label('Email').required())
+    .field(PasswordField('password').label('Password').required())
+    .onSubmit(async (values) => {
+        const valid = await control.validate();
+        if (valid) {
+            await createUser(values);
+        }
+    })
+    .nd
+```
+
+### Methods
+
+```javascript
+.field(fieldInstance)         // add a field
+.fields([field1, field2])
+.validate()                   // validate all fields, returns true | false
+.reset()                      // reset all fields
+.values()                     // get { name: value } object
+.getField('name')             // get field by name
+.onSubmit((values) => {})
+.onReset(() => {})
+.props({ class: 'form' })
+```
+
+---
+
+## `FieldCollection` - Repeatable Fields
+
+A dynamic list of field groups that the user can add/remove:
+
+```javascript
+FieldCollection('contacts')
+    .fields((group) => {
+        group.add(StringField('name').label('Name').required())
+        group.add(EmailField('email').label('Email'))
+    })
+    .data({ name: '', email: '' })   // default item
+    .model(contacts)
+    .renderAdd(() => Button('+ Add contact').ghost().nd)
+    .renderItem(($item, index, remove) =>
+        HStack([
+            $item.name.nd,
+            $item.email.nd,
+            Button('Remove').danger().small().nd.onClick(() => remove())
+        ]).spacing(8).nd
+    )
+    .nd
+```
+
+
+---
+
+## Theming
+
+Tokens partagés par tous les champs (`StringField`, `NumberField`, `TextAreaField`, etc.) :
+
+```css
+:root {
+    --field-gap:                        var(--space-cozy);
+    --field-font-size:                  var(--description-size);
+    --field-label-size:                 var(--note-size);
+    --field-label-color:                var(--text-color);
+    --field-label-weight:               500;
+    --field-input-height:               36px;
+    --field-input-padding:              0 var(--space-comfortable);
+    --field-input-radius:               var(--radius-button);
+    --field-input-border:               var(--gray-lite-3);
+    --field-input-border-focus:         var(--color-primary);
+    --field-input-bg:                   var(--background);
+    --field-input-color:                var(--text-color);
+    --field-input-placeholder-color:    var(--gray-lite-2);
+    --field-input-disabled-bg:          var(--gray-lite-5);
+    --field-input-disabled-color:       var(--gray-lite-2);
+    --field-error-size:                 var(--note-size);
+    --field-error-color:                var(--color-danger);
+    --field-hint-size:                  var(--note-size);
+    --field-hint-color:                 var(--gray);
+}
+```
+
+Tokens spécifiques au `Slider` / `RangeField` :
+
+```css
+:root {
+    --slider-track-height:      4px;
+    --slider-thumb-size:        18px;
+    --slider-fill-color:        var(--color-primary);
+    --slider-track-color:       var(--gray-lite-4);
+    --slider-thumb-color:       var(--background);
+    --slider-thumb-border:      var(--slider-fill-color);
+    --slider-vertical-height:   200px;
+}
+```
+
+Tokens spécifiques à `FileAvatarMode` :
+
+```css
+:root {
+    --file-avatar-radius-circle: 50%;
+    --file-avatar-radius-square: 12px;
+    --file-avatar-badge-size:    26px;
+}
+```

package/docs/components/getting-started.md

@@ -0,0 +1,264 @@
+---
+title: Components - Getting Started
+description: Set up NativeDocument components with default or custom renderers
+---
+
+# Getting Started with Components
+
+## Import
+
+Components are included in `native-document` - no separate installation needed:
+
+```javascript
+import { Button, Modal, Tabs, Accordion } from 'native-document/components';
+```
+
+To use the default theme and behavioral CSS:
+
+```javascript
+import 'native-document/src/ui/theme.scss';
+```
+
+---
+
+## Option 1 - Use the Default Renderers
+
+The package ships a ready-to-use renderer for every component. Import them from `'native-document/ui'` and register them once at app startup.
+
+Create `src/core/renderers.js`:
+
+```javascript
+import {
+    Button, Alert, Badge, Spinner, Modal, Tabs,
+    Dropdown, DropdownItem, DropdownDivider, DropdownGroup,
+    Menu, MenuItem, MenuGroup, MenuLink, MenuDivider,
+    ContextMenu, Accordion, AccordionItem,
+    // ... all components you use
+} from 'native-document/components';
+
+import {
+    ButtonRender, AlertRender, BadgeRender, SpinnerRender, ModalRender, TabsRender,
+    DropdownRender, DropdownItemRender, DropdownDividerRender, DropdownGroupRender,
+    MenuRender, MenuItemRender, MenuGroupRender, MenuLinkRender, MenuDividerRender,
+    ContextMenuRender, contextMenuHandler,
+    AccordionRender, AccordionItemRender,
+    // ... matching renders
+} from 'native-document/ui';
+
+Button.use(ButtonRender);
+Alert.use(AlertRender);
+Badge.use(BadgeRender);
+Spinner.use(SpinnerRender);
+Modal.use(ModalRender);
+Tabs.use(TabsRender);
+Dropdown.use(DropdownRender);
+DropdownItem.use(DropdownItemRender);
+DropdownDivider.use(DropdownDividerRender);
+DropdownGroup.use(DropdownGroupRender);
+Menu.use(MenuRender);
+MenuItem.use(MenuItemRender);
+MenuGroup.use(MenuGroupRender);
+MenuLink.use(MenuLinkRender);
+MenuDivider.use(MenuDividerRender);
+ContextMenu.use(ContextMenuRender, contextMenuHandler); // note: two arguments
+Accordion.use(AccordionRender);
+AccordionItem.use(AccordionItemRender);
+// ...
+```
+
+Then import it in `main.js` - renderers first, then the rest of the app:
+
+```javascript
+import { Router } from 'native-document/router';
+import './core/renderers.js';
+// ... rest of app setup
+```
+
+---
+
+## Option 2 - Write Your Own Renderers
+
+Skip the defaults entirely and write renderers that match your own design system:
+
+```javascript
+import { Button, Spinner } from 'native-document/components';
+import { NativeButton, ShowIf } from 'native-document/elements';
+
+Button.use(($description) => {
+    const classes = ['btn'];
+
+    if($description.variant) {
+        classes.push(`btn-${$description.variant}`);
+    }
+    if($description.size) {
+        classes.push(`btn-${$description.size}`);
+    }
+    if($description.block) {
+        classes.push('btn-block');
+    }
+    if($description.outline) {
+        classes.push('btn-outline');
+    }
+    if($description.borderRadiusType) {
+        classes.push(`btn-${$description.borderRadiusType}`);
+    }
+
+    return NativeButton({
+        type:     $description.type || 'button',
+        class:    classes.join(' '),
+        disabled: $description.disabled,
+        ...$description.props
+    }, [
+        ShowIf($description.loading, () => Spinner()),
+        $description.label
+    ]);
+});
+```
+
+---
+
+## Option 3 - Mix Both
+
+Use the defaults for most components and override only the ones that need a custom look:
+
+```javascript
+import { ButtonRender, AlertRender } from 'native-document/ui';
+
+Alert.use(AlertRender);
+
+Button.use(($description) => {
+    return NativeButton({
+        class: myTailwindClasses($description),
+        ...$description.props
+    }, $description.label);
+});
+```
+
+---
+
+## Using Components
+
+Once renderers are registered, components work just like HTML elements. Only call `.nd` when you need to chain a specific `.nd` method:
+
+```javascript
+import { Button, Alert } from 'native-document/components';
+
+Div({ class: 'form' }, [
+    Alert('Please fix the errors below').error(),
+    Input({ type: 'text', value: name }),
+    Button('Submit')
+        .primary()
+        .loading(isLoading)
+        .nd
+        .onClick(() => submit())
+])
+```
+
+---
+
+## The `$description` Contract
+
+Every renderer receives a `$description` object describing the component's current state. Here is what a fully configured `Button` looks like:
+
+```javascript
+{
+    label:            'Submit',
+    type:             'submit',          // 'button' | 'submit' | 'reset' | null
+    variant:          'primary',
+    size:             'large',           // 'small' | 'medium' | 'large' | null
+    icon:             SvgIcon,           // DOM element | null
+    iconPosition:     'leading',         // 'leading' | 'trailing' | 'top' | 'bottom'
+    iconOnly:         false,
+    loading:          Observable(false), // reactive
+    disabled:         Observable(false), // reactive
+    outline:          false,
+    block:            false,
+    borderRadiusType: 'rounded',
+    props:            {} // HTML attributes for the root element
+    render:           null               // per-instance renderer override
+}
+```
+
+Each component page documents its own `$description` structure.
+
+---
+
+## Renderer Tips
+
+### Use `$description` not `$d`
+
+Use the full name `$description` in your renderers for clarity:
+
+```javascript
+Button.use(($description) => {
+    return NativeButton({
+        class:    buildClasses($description),
+        disabled: $description.disabled,
+        ...$description.props
+    }, $description.label);
+});
+```
+
+### Spread `$description.props` last
+
+Always spread `$description.props` last so per-instance attributes can override defaults:
+
+```javascript
+NativeButton({
+    type:  'button',
+    class: buildClasses($description),
+    ...$description.props
+}, $description.label)
+```
+
+### Observable values are reactive
+
+Some `$description` values are observables (`loading`, `disabled`, etc.). Pass them directly as attributes - NativeDocument handles the reactive binding:
+
+```javascript
+NativeButton({
+    disabled: $description.disabled,  // Observable<boolean> - reactive
+    class:    buildClasses($description)
+}, $description.label)
+```
+
+### Per-instance override
+
+A component can override the global renderer for a specific instance via `.render()`:
+
+```javascript
+Button('Special')
+    .render(($description) => NativeButton({ class: 'special-btn' }, $description.label))
+    .nd.onClick(() => doSomething())
+```
+
+---
+
+## Presets
+
+Presets create named factory shortcuts for commonly configured variants:
+
+```javascript
+Button.preset('save', (label, props) => {
+    return Button(label || 'Save',   props).primary();
+});
+Button.preset('cancel', (label, props) => {
+    return Button(label || 'Cancel', props).ghost();
+});
+Button.preset('delete', (label, props) => {
+    return Button(label || 'Delete', props).danger().outline();
+});
+
+Button.save()
+Button.cancel('Go back')
+Button.delete('Remove account')
+```
+
+---
+
+## Next Steps
+
+- **[Traits](./traits.md)** - HasEventEmitter, HasDraggable, HasResizable
+- **[Button](./button.md)** - Full Button API
+- **[Layout](./layout.md)** - Stack, Row, Col, Divider
+- **[Components Overview](./index.md)** - Philosophy and BaseComponent API