native-document 1.0.189 → 1.0.191

package/CHANGELOG.md

@@ -247,7 +247,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Data**: `DataTable` + `Column` + `ColumnGroup`, `SimpleTable`, `Accordion` + `AccordionItem`, `List`
 - **Interaction**: `Button`, `Switch`, `Slider`
 - **Media**: `Avatar`, `AvatarGroup`, `Card`
-- **Forms**: `FormControl`, `FieldCollection`, `StringField`, `EmailField`, `PasswordField`, `TelField`, `UrlField`, `HiddenField`, `NumberField`, `RangeField`, `TextAreaField`, `CheckboxField`, `CheckboxGroupField`, `RadioField`, `SelectField`, `AutocompleteField`, `DateField`, `TimeField`, `ColorField`, `SliderField`, `ImageField`, `FileField` (with `FileNativeMode`, `FileDropzoneMode`, `FileUploadButtonMode`, `FileWallMode`, `FileAvatarMode`)
+- **Forms**: `FormControl`, `FieldCollection`, `StringField`, `EmailField`, `PasswordField`, `TelField`, `UrlField`, `HiddenField`, `NumberField`, `RangeField`, `TextAreaField`, `CheckboxField`, `CheckboxGroupField`, `RadioField`, `SelectField`, `AutocompleteField`, `DateField`, `TimeField`, `ColorField`, `SliderField`, `ImageField`, `FileField` (with `FileNativeMode`, `FileDropzoneMode`, `FileUploadButtonMode`, `FileWallMode`, `FileImagePreviewMode`)
 - **Traits**: `HasEventEmitter`, `HasDraggable`, `HasResizable`, `HasItems`, `HasPosition`, `HasFullPosition`, `HasValidation`
 
 #### CLI (`@native-document/cli`)

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

@@ -9,7 +9,7 @@ description: File upload component with multiple modes - native, dropzone, butto
 import {
     FileField,
     FileNativeMode, FileDropzoneMode,
-    FileUploadButtonMode, FileWallMode, FileAvatarMode
+    FileUploadButtonMode, FileWallMode, FileImagePreviewMode
 } from 'native-document/components';
 ```
 
@@ -19,7 +19,7 @@ import {
 import {
     FileFieldRender,
     FileNativeModeRender, FileDropzoneModeRender,
-    FileUploadButtonModeRender, FileWallModeRender, FileAvatarModeRender
+    FileUploadButtonModeRender, FileWallModeRender, FileImagePreviewModeRender
 } from 'native-document/ui';
 
 FileField.use(FileFieldRender);
@@ -27,7 +27,7 @@ FileNativeMode.use(FileNativeModeRender);
 FileDropzoneMode.use(FileDropzoneModeRender);
 FileUploadButtonMode.use(FileUploadButtonModeRender);
 FileWallMode.use(FileWallModeRender);
-FileAvatarMode.use(FileAvatarModeRender);
+FileImagePreviewMode.use(FileImagePreviewModeRender);
 ```
 
 ## Methods
@@ -66,11 +66,11 @@ FileAvatarMode.use(FileAvatarModeRender);
 
 ### 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 |
+| Method                   | Parameters | Description |
+|--------------------------|---|---|
+| `.onAddFile(handler)`    | `handler: (file, files) => void` | Fires when a file is added |
+| `.onRemoveFile(handler)` | `handler: (file, files) => void` | Fires when a file is removed |
+| `.onReset(handler)`      | `handler: () => void` | Fires when files are cleared |
 
 ## Modes
 
@@ -156,7 +156,7 @@ FileField('gallery')
     )
 ```
 
-### `FileAvatarMode`
+### `FileImagePreviewMode`
 
 Single image upload styled as a circular avatar.
 
@@ -177,7 +177,7 @@ Single image upload styled as a circular avatar.
 FileField('avatar')
     .accept(['image/*'])
     .mode(
-        FileAvatarMode()
+        FileImagePreviewMode()
             .hoverOverlay()
             .circle()
     )
@@ -196,7 +196,7 @@ FileField('documents')
             .text('Drop PDFs here')
             .icon(PdfIcon)
     )
-    .onFileAdd(async (file) => {
+    .onAddFile(async (file) => {
         const url = await uploadFile(file);
         console.log('Uploaded:', url);
     })

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

@@ -23,7 +23,7 @@ ImageField.use(FileFieldRender);
 
 ## Methods
 
-All `FileField` methods apply (`accept`, `maxSize`, `mode`, `onFileAdd`…). See **[FileField](./file-field.md)** for the full reference. Image-specific additions:
+All `FileField` methods apply (`accept`, `maxSize`, `mode`, `onAddFile`…). See **[FileField](./file-field.md)** for the full reference. Image-specific additions:
 
 | Method | Parameters | Description |
 |---|---|---|
@@ -64,10 +64,10 @@ ImageField('cover')
 ## Avatar example
 
 ```javascript
-import { FileAvatarMode } from 'native-document/components';
-import { FileAvatarModeRender } from 'native-document/ui';
+import { FileImagePreviewMode } from 'native-document/components';
+import { FileImagePreviewModeRender } from 'native-document/ui';
 
-FileAvatarMode.use(FileAvatarModeRender);
+FileImagePreviewMode.use(FileImagePreviewModeRender);
 
 ImageField('avatar')
     .label('Profile picture')
@@ -77,7 +77,7 @@ ImageField('avatar')
     .aspectRatio('1:1', 'Must be square')
     .crop()
     .mode(
-        FileAvatarMode()
+        FileImagePreviewMode()
             .hoverOverlay()
             .circle()
     )

package/docs/components/form-fields.md

@@ -361,7 +361,7 @@ Tokens spécifiques au `Slider` / `RangeField` :
 }
 ```
 
-Tokens spécifiques à `FileAvatarMode` :
+Tokens spécifiques à `FileImagePreviewMode` :
 
 ```css
 :root {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "native-document",
-  "version": "1.0.189",
+  "version": "1.0.191",
   "description": "A reactive JavaScript framework that preserves native DOM simplicity without sacrificing modern features",
   "author": "AfroCodeur <https://github.com/afrocodeur>",
   "license": "MIT",

package/src/components/form/field/types/FileField.js

@@ -14,8 +14,8 @@ import FileItemPreview from '../../field/types/file-field-mode/FileItemPreview';
  *     .maxSize(5 * 1024 * 1024, 'Max 5MB per file')
  *     .maxFiles(3, 'Max 3 files')
  *     .mode(FileDropzoneMode())
- *     .onFileAdd((file) => console.log('added', file.name))
- *     .onFileRemove((file) => console.log('removed', file.name));
+ *     .onAddFile((file) => console.log('added', file.name))
+ *     .onRemoveFile((file) => console.log('removed', file.name));
  *
  * FileField.use((description, instance) => {
  *     // description.accept, description.multiple, description.mode,
@@ -54,7 +54,7 @@ FileField.defaultTemplate = null;
  *     label: NdChild|null,
  *     accept: string|null,
  *     multiple: boolean,
- *     mode: FileNativeMode|FileAvatarMode|FileDropzoneMode|FileUploadButtonMode|FileWallMode|null,
+ *     mode: FileNativeMode|FileImagePreviewMode|FileDropzoneMode|FileUploadButtonMode|FileWallMode|null,
  *     files: Observable<FileItemPreview[]>,
  *     fileIcons: Array<(file: File) => NdChild>,
  *     disabled: boolean|Observable<boolean>,
@@ -91,7 +91,7 @@ FileField.prototype.multiple = function(enabled = true) {
 };
 
 /**
- * @param {FileNativeMode|FileAvatarMode|FileDropzoneMode|FileUploadButtonMode|FileWallMode|null} mode
+ * @param {FileNativeMode|FileImagePreviewMode|FileDropzoneMode|FileUploadButtonMode|FileWallMode|null} mode
  * @returns {this}
  */
 FileField.prototype.mode = function(mode) {
@@ -154,14 +154,23 @@ FileField.prototype.minFiles = function(min, message) {
 };
 
 /**
- * @param {(file: File) => void} handler
+ * @param {(file: FileItemPreview) => void} handler
  * @returns {this}
  */
-FileField.prototype.onFileAdd = function(handler) {
+FileField.prototype.onAddFile = function(handler) {
     this.on('fileAdd', handler);
     return this;
 };
 
+/**
+ * @param {(file: File) => void} handler
+ * @returns {this}
+ */
+FileField.prototype.onSelectFile = function(handler) {
+    this.on('selectFile', handler);
+    return this;
+};
+
 /**
  * @param {() => void} handler
  * @returns {this}
@@ -175,7 +184,7 @@ FileField.prototype.onReset = function(handler) {
  * @param {(file: File) => void} handler
  * @returns {this}
  */
-FileField.prototype.onFileRemove = function(handler) {
+FileField.prototype.onRemoveFile = function(handler) {
     this.on('fileRemove', handler);
     return this;
 };
@@ -189,6 +198,7 @@ FileField.prototype.onFileRemove = function(handler) {
 FileField.prototype.addFile = function(file, update = true) {
     const item = new FileItemPreview(file);
     this.$description.files.push(item);
+    this.emit('selectFile', file);
     this.emit('fileAdd', item);
     update && this.$update();
     return this;
@@ -222,7 +232,7 @@ FileField.prototype.addFiles = function(files) {
 
 FileField.prototype.$update = function() {
     const files = this.$description.files.val();
-    this.$description.value.set(this.$description.multiple ? files.map(i => i.file()) : files[0]?.file() || null);
+    this.$description.value?.set(this.$description.multiple ? files.map(i => i.file()) : files[0]?.file() || null);
     this.validate();
 };
 

package/src/components/form/field/types/file-field-mode/FileImagePreviewMode.js

@@ -0,0 +1,274 @@
+import BaseComponent from '../../../../BaseComponent';
+import HasEventEmitter from '../../../../../core/utils/HasEventEmitter';
+
+/**
+ * Avatar-style single file upload mode for FileField.
+ * Displays a circular or square avatar with hover/badge/button interaction variants.
+ * Ideal for profile picture uploads.
+ * @example
+ * new FileField('avatar')
+ *     .mode('avatar');
+ *
+ * FileImagePreviewMode.use((description, instance) => {
+ *     // description.variant — 'hover-overlay' | 'corner-badge' | 'action-buttons'
+ *     // description.shape   — 'circle' | 'square'
+ *     // description.size, description.placeholderIcon, description.overlayIcon,
+ *     // description.editImageIcon, description.changeLabel, description.removeLabel,
+ *     // description.renderAvatar, description.renderOverlay, description.renderActions
+ *     return Div({ class: \`avatar-upload avatar-upload--\${description.variant}\`,
+ *                  style: { width: description.size, height: description.size } });
+ * });
+ *
+ * @constructor
+ * @param {GlobalAttributes} [props={}]
+ */
+export default function FileImagePreviewMode(props = {}) {
+    if(!(this instanceof FileImagePreviewMode)) {
+        return new FileImagePreviewMode(props);
+    }
+
+    BaseComponent.call(this, props);
+
+    this.$description = {
+        variant: 'hover-overlay',
+        shape: 'circle',
+        size: null,
+        placeholderIcon: null,
+        overlayIcon: null,
+        editImageIcon: null,
+        changeLabel: 'Change photo',
+        removeLabel: 'Remove',
+        renderAvatar: null,
+        renderOverlay: null,
+        renderActions: null,
+        mode: 'avatar',
+        ratio: null,
+        props,
+    };
+}
+
+BaseComponent.extends(FileImagePreviewMode);
+BaseComponent.use(FileImagePreviewMode, HasEventEmitter);
+
+FileImagePreviewMode.defaultTemplate = null;
+
+/**
+ * Registers the render template for FileImagePreviewMode.
+ * @param {(description: {
+ *     variant: 'hover-overlay'|'corner-badge'|'action-buttons',
+ *     shape: 'circle'|'square',
+ *     size: number|string,
+ *     placeholderIcon: NdChild|null,
+ *     overlayIcon: NdChild|null,
+ *     editImageIcon: NdChild|null,
+ *     changeLabel: NdChild,
+ *     removeLabel: NdChild,
+ *     renderAvatar: ((desc: *, instance: FileImagePreviewMode) => NdChild)|null,
+ *     renderOverlay: ((desc: *, instance: FileImagePreviewMode) => NdChild)|null,
+ *     renderActions: ((desc: *, instance: FileImagePreviewMode) => NdChild)|null,
+ *     props: GlobalAttributes
+ * }, instance: FileImagePreviewMode) => NdChild} template
+ */
+FileImagePreviewMode.use = function(template) {
+    FileImagePreviewMode.defaultTemplate = template;
+};
+
+/** @returns {this} */
+FileImagePreviewMode.prototype.hoverOverlay = function() {
+    this.$description.variant = 'hover-overlay';
+    return this;
+};
+
+/** @returns {this} */
+FileImagePreviewMode.prototype.cornerBadge = function() {
+    this.$description.variant = 'corner-badge';
+    return this;
+};
+
+/** @returns {this} */
+FileImagePreviewMode.prototype.actionButtons = function() {
+    this.$description.variant = 'action-buttons';
+    return this;
+};
+
+/** @returns {this} */
+FileImagePreviewMode.prototype.circle = function() {
+    this.$description.shape = 'circle';
+    return this;
+};
+
+/** @returns {this} */
+FileImagePreviewMode.prototype.square = function() {
+    this.$description.shape = 'square';
+    return this;
+};
+
+/**
+ * @param {number|string} size - Size in pixels or CSS value
+ * @returns {this}
+ */
+FileImagePreviewMode.prototype.size = function(size) {
+    this.$description.size = size;
+    return this;
+};
+
+/**
+ * @param {NdChild} icon
+ * @returns {this}
+ */
+FileImagePreviewMode.prototype.placeholderIcon = function(icon) {
+    this.$description.placeholderIcon = icon;
+    return this;
+};
+
+/**
+ * @param {NdChild} icon
+ * @returns {this}
+ */
+FileImagePreviewMode.prototype.overlayIcon = function(icon) {
+    this.$description.overlayIcon = icon;
+    return this;
+};
+
+/**
+ * @param {NdChild} icon
+ * @returns {this}
+ */
+FileImagePreviewMode.prototype.editImageIcon = function(icon) {
+    this.$description.editImageIcon = icon;
+    return this;
+};
+
+/**
+ * @param {NdChild} label
+ * @returns {this}
+ */
+FileImagePreviewMode.prototype.changeLabel = function(label) {
+    this.$description.changeLabel = label;
+    return this;
+};
+
+/**
+ * @param {NdChild} label
+ * @returns {this}
+ */
+FileImagePreviewMode.prototype.removeLabel = function(label) {
+    this.$description.removeLabel = label;
+    return this;
+};
+
+/**
+ * @param {(desc: *, instance: FileImagePreviewMode) => NdChild} fn
+ * @returns {this}
+ */
+FileImagePreviewMode.prototype.renderAvatar = function(fn) {
+    this.$description.renderAvatar = fn;
+    return this;
+};
+
+/**
+ * @param {(desc: *, instance: FileImagePreviewMode) => NdChild} fn
+ * @returns {this}
+ */
+FileImagePreviewMode.prototype.renderOverlay = function(fn) {
+    this.$description.renderOverlay = fn;
+    return this;
+};
+
+/**
+ * @param {(desc: *, instance: FileImagePreviewMode) => NdChild} fn
+ * @returns {this}
+ */
+FileImagePreviewMode.prototype.renderActions = function(fn) {
+    this.$description.renderActions = fn;
+    return this;
+};
+
+/**
+ * Configures the component specifically for avatar preset (circular default).
+ * @returns {this}
+ */
+FileImagePreviewMode.prototype.asAvatar = function() {
+    this.$description.mode = 'avatar';
+    return this;
+};
+/**
+ * Configures the component specifically for banner/cover preset (square default).
+ * @returns {this}
+ */
+FileImagePreviewMode.prototype.asCover = function() {
+    this.$description.mode = 'cover';
+    this.square();
+    return this;
+};
+
+/**
+ * Sets CSS aspect-ratio or ratio string (e.g. '16/9', '3/1', 1.77)
+ * @param {string|number} ratio
+ * @returns {this}
+ */
+FileImagePreviewMode.prototype.ratio = function(ratio) {
+    this.$description.ratio = ratio;
+    return this;
+};
+
+/**
+ * Sets aspect ratio to 1:1 (Square).
+ * Ideal for avatars, product thumbnails, or Instagram feed items.
+ * @returns {this}
+ */
+FileImagePreviewMode.prototype.squareRatio = function() {
+    this.$description.ratio = '1/1';
+    return this;
+};
+
+/**
+ * Sets aspect ratio to 16:9 (Widescreen).
+ * Ideal for video previews, event covers, and standard web banners.
+ * @returns {this}
+ */
+FileImagePreviewMode.prototype.widescreenRatio = function() {
+    this.$description.ratio = '16/9';
+    return this;
+};
+
+/**
+ * Sets aspect ratio to an ultra-wide banner format (defaults to 3:1).
+ * Ideal for profile headers (e.g., Twitter, LinkedIn) or hero banners.
+ * @param {string} [customRatio='3/1'] - Custom ratio string if different from '3/1' (e.g., '4/1')
+ * @returns {this}
+ */
+FileImagePreviewMode.prototype.bannerRatio = function(customRatio = '3/1') {
+    this.$description.ratio = customRatio;
+    return this;
+};
+
+/**
+ * Sets aspect ratio to 4:3 (Landscape).
+ * Ideal for traditional photography, blog thumbnails, or product cards.
+ * @returns {this}
+ */
+FileImagePreviewMode.prototype.landscapeRatio = function() {
+    this.$description.ratio = '4/3';
+    return this;
+};
+
+/**
+ * Sets aspect ratio to 9:16 (Story / Full Mobile).
+ * Ideal for mobile-first vertical media (Instagram Stories, Reels, TikTok).
+ * @returns {this}
+ */
+FileImagePreviewMode.prototype.storyRatio = function() {
+    this.$description.ratio = '9/16';
+    return this;
+};
+
+/**
+ * Sets aspect ratio to 4:5 (Social Portrait).
+ * Ideal for Instagram or Facebook feed posts optimized for mobile screen height.
+ * @returns {this}
+ */
+FileImagePreviewMode.prototype.portraitRatio = function() {
+    this.$description.ratio = '4/5';
+    return this;
+};

package/src/components/form/index.js

@@ -24,7 +24,7 @@ import FileNativeMode from './field/types/file-field-mode/FileNativeMode';
 import FileDropzoneMode from './field/types/file-field-mode/FileDropzoneMode';
 import FileUploadButtonMode from './field/types/file-field-mode/FileUploadButtonMode';
 import FileWallMode from './field/types/file-field-mode/FileWallMode';
-import FileAvatarMode from './field/types/file-field-mode/FileAvatarMode';
+import FileImagePreviewMode from './field/types/file-field-mode/FileImagePreviewMode';
 
 // import './field/FieldFactory';
 
@@ -53,7 +53,7 @@ export {
     FieldCollection,
 
     FileNativeMode,
-    FileAvatarMode,
+    FileImagePreviewMode,
     FileWallMode,
     FileUploadButtonMode,
     FileDropzoneMode,

package/src/components/form/types/fields/FileField.d.ts

@@ -31,10 +31,10 @@ export interface FileFieldInterface extends Omit<FieldInterface, 'render' | 'res
     extensions(extensions: string[], message?: string): this;
     maxFiles(max: number, message?: string): this;
     minFiles(min: number, message?: string): this;
-    onFileAdd(handler: (file: File) => void): this;
+    onAddFile(handler: (file: File) => void): this;
     onReset(handler: () => void): this;
-    onFileRemove(handler: (file: File) => void): this;
-    addFile(file: File, update?: boolean): this;
+    onRemoveFile(handler: (file: File) => void): this;
+    addFile(file: FileItemPreviewInterface, update?: boolean): this;
     setFiles(files: File[]): this;
     addFiles(files: File[]): this;
     removeFile(file: File): this;

package/src/components/form/types/fields/FileImagePreviewMode.d.ts

@@ -0,0 +1,57 @@
+import type { ValidChild } from '../../../../../types/elements';
+import type { GlobalAttributes } from '../../../../../types/globals';
+import type { BaseComponent } from '../../../BaseComponent';
+
+export type FileImagePreviewModeDescription = {
+    variant: 'hover-overlay' | 'corner-badge' | 'action-buttons';
+    shape: 'circle' | 'square';
+    size: number | string;
+    placeholderIcon: ValidChild | null;
+    overlayIcon: ValidChild | null;
+    editImageIcon: ValidChild | null;
+    changeLabel: ValidChild;
+    removeLabel: ValidChild;
+    renderAvatar: ((desc: unknown, instance: FileImagePreviewModeInterface) => ValidChild) | null;
+    renderOverlay: ((desc: unknown, instance: FileImagePreviewModeInterface) => ValidChild) | null;
+    renderActions: ((desc: unknown, instance: FileImagePreviewModeInterface) => ValidChild) | null;
+    props: GlobalAttributes;
+};
+
+export interface FileImagePreviewModeInterface extends BaseComponent {
+    render(renderFn: (description: FileImagePreviewModeDescription, instance: FileImagePreviewModeInterface) => ValidChild): this;
+    hoverOverlay(): this;
+    cornerBadge(): this;
+    actionButtons(): this;
+    circle(): this;
+    square(): this;
+    asAvatar(): this;
+    asCover(): this;
+    ratio(ratio: string): this;
+
+    ratio(ratio: string | number): this;
+
+    squareRatio(): this;
+    widescreenRatio(): this;
+    bannerRatio(customRatio?: string): this;
+    landscapeRatio(): this;
+    storyRatio(): this;
+    portraitRatio(): this;
+
+    size(size: number | string): this;
+    placeholderIcon(icon: ValidChild): this;
+    overlayIcon(icon: ValidChild): this;
+    editImageIcon(icon: ValidChild): this;
+    changeLabel(label: ValidChild): this;
+    removeLabel(label: ValidChild): this;
+    renderAvatar(fn: (desc: unknown, instance: FileImagePreviewModeInterface) => ValidChild): this;
+    renderOverlay(fn: (desc: unknown, instance: FileImagePreviewModeInterface) => ValidChild): this;
+    renderActions(fn: (desc: unknown, instance: FileImagePreviewModeInterface) => ValidChild): this;
+}
+
+
+export declare function FileImagePreviewMode(props?: GlobalAttributes): FileImagePreviewModeInterface;
+export declare namespace FileImagePreviewMode {
+
+    function use(template: (description: FileImagePreviewModeDescription, instance: FileImagePreviewModeInterface) => ValidChild): void;
+
+}

package/src/components/index.d.ts

@@ -78,7 +78,7 @@ export type { RangeField, RangeFieldInterface } from './form/types/fields/RangeF
 export type { SearchField, SearchFieldInterface } from './form/types/fields/SearchField';
 export type { FileField, FileFieldInterface } from './form/types/fields/FileField';
 export type { ImageField, ImageFieldInterface } from './form/types/fields/ImageField';
-export type { FileAvatarMode, FileAvatarModeInterface, FileAvatarModeDescription } from './form/types/fields/FileAvatarMode';
+export type { FileImagePreviewMode, FileImagePreviewModeInterface, FileImagePreviewModeDescription } from './form/types/fields/FileImagePreviewMode';
 export type { FileDropzoneMode, FileDropzoneModeInterface, FileDropzoneModeDescription } from './form/types/fields/FileDropzoneMode';
 export type { FileItemPreview, FileItemPreviewInterface, FileItemPreviewDescription } from './form/types/fields/FileItemPreview';
 export type { FileNativeMode, FileNativeModeInterface, FileNativeModeDescription } from './form/types/fields/FileNativeMode';

package/src/core/data/Observable.js

@@ -176,6 +176,19 @@ Observable.computed = function(callback, dependencies = []) {
 };
 ObservableItem.computed = Observable.computed;
 
+Observable.auto = (value) => {
+    if(value == null) {
+        return new ObservableItem(value);
+    }
+    if(Validator.isArray(value)) {
+        return new ObservableArray(value);
+    } else if(typeof value === 'object') {
+        return new ObservableObject(value);
+    }
+    return new ObservableItem(value);
+};
+ObservableItem.auto = Observable.auto;
+
 
 Observable.init = function(initialValue, configs = null) {
     return new ObservableObject(initialValue, configs);

package/src/core/data/ObservableItem.js

@@ -59,6 +59,7 @@ Object.defineProperty(ObservableItem.prototype, '$value', {
 ObservableItem.prototype.__$Observable = true;
 ObservableItem.prototype.__$isObservable = true;
 ObservableItem.computed = () => {};
+ObservableItem.auto = () => {};
 
 const DEFAULT_OPERATIONS = {};
 const noneTrigger = function() {};

package/src/core/data/ObservableObject.js

@@ -22,16 +22,7 @@ export const ObservableObject = function(target, configs) {
     this.configs = configs;
 
     for(const key in target) {
-        if(!Object.hasOwn(this, key)) {
-            Object.defineProperty(this, key, {
-                get: () => this.$observables[key],
-                set: (value) => {
-                    this.$observables[key].set(value);
-                },
-                configurable: true,
-                enumerable: true,
-            });
-        }
+        this.$addKey(key);
     }
 
     this.$load(target);
@@ -60,6 +51,32 @@ Object.defineProperty(ObservableObject, '$value', {
 ObservableObject.prototype.__$isObservableObject = true;
 ObservableObject.prototype.__isProxy__ = true;
 
+ObservableObject.prototype.$addKey = function(key) {
+    if(!Object.hasOwn(this, key)) {
+        Object.defineProperty(this, key, {
+            get: () => this.$observables[key],
+            set: (value) => {
+                this.$observables[key].set(value);
+            },
+            configurable: true,
+            enumerable: true,
+        });
+    }
+};
+
+
+/**
+ *
+ * @param {String[]} properties
+ */
+ObservableObject.prototype.only = function(properties) {
+    const result = {};
+    for(const key in properties) {
+        result[key] = this.$observables[key]?.val();
+    }
+    return result;
+};
+
 /**
  * Initialises (or reinitialize) the internal observables map from a plain object.
  * Called automatically in the constructor.
@@ -182,7 +199,7 @@ ObservableObject.prototype.set = function(newData) {
                     if(firstElementFromOriginalValue.__$isObservableObject) {
                         return new ObservableObject(item, configs);
                     }
-                    return ObservableItem(item, configs);
+                    return new ObservableItem(item, configs);
                 });
                 targetItem.set(newValues);
                 continue;
@@ -190,7 +207,9 @@ ObservableObject.prototype.set = function(newData) {
             targetItem.set([...newValue]);
             continue;
         }
-        this[key] = newValue;
+        const value = ObservableItem.auto(newValue);
+        this.$observables[key] = value;
+        this.$addKey(key);
     }
 };
 ObservableObject.prototype.$set = ObservableObject.prototype.set;