native-document 1.0.165 → 1.0.168

package/src/components/$traits/has-items/HasItems.js

@@ -1,4 +1,4 @@
-import {$} from "../../../core/data/Observable";
+import {$} from '../../../core/data/Observable';
 
 /**
  * Mixin for managing a collection of items with manipulation methods
@@ -7,12 +7,12 @@ import {$} from "../../../core/data/Observable";
 export default function HasItems() {}
 
 
-HasItems.prototype.trailing = () => {}
+HasItems.prototype.trailing = () => {};
 
 /**
  * Sets a dynamic observable array to store items
  * @param {ObservableArray?} [observableArray=null] - Observable array to use, or creates a new one if null
- * @returns {HasItems}
+ * @returns {this}
  */
 HasItems.prototype.dynamic = function(observableArray = null) {
     this.$description.items = observableArray || $.array([]);
@@ -23,7 +23,7 @@ HasItems.prototype.bind = HasItems.prototype.dynamic;
 /**
  * Replaces all existing items with a new array of items
  * @param {Array} items - Array of new items
- * @returns {HasItems}
+ * @returns {this}
  */
 HasItems.prototype.items = function(items) {
     this.$description.items.splice(0, this.$description.items.length, ...items);
@@ -33,7 +33,7 @@ HasItems.prototype.items = function(items) {
 
 /**
  * Clears all items from the collection
- * @returns {HasItems}
+ * @returns {this}
  */
 HasItems.prototype.clear = function() {
     const items = this.$description.items;
@@ -48,7 +48,7 @@ HasItems.prototype.clear = function() {
 /**
  * Removes a specific item from the collection
  * @param {*} item - The item to remove
- * @returns {HasItems}
+ * @returns {this}
  */
 HasItems.prototype.removeItem = function(item) {
     const items = this.$description.items;

package/src/components/$traits/has-position/HasFullPosition.d.ts

@@ -0,0 +1,14 @@
+export interface HasFullPosition {
+    atTop(): this;
+    atBottom(): this;
+    atLeft(): this;
+    atRight(): this;
+    atTopLeading(): this;
+    atTopTrailing(): this;
+    atTopCenter(): this;
+    atBottomLeading(): this;
+    atBottomTrailing(): this;
+    atBottomCenter(): this;
+    atLeadingCenter(): this;
+    atTrailingCenter(): this;
+}

package/src/components/$traits/has-position/HasFullPosition.js

@@ -5,46 +5,90 @@ HasFullPosition.prototype.atTop = function() {
     this.$description.position = 'top';
     return this;
 };
+
+/**
+ * @returns {this}
+ */
 HasFullPosition.prototype.atBottom = function() {
     this.$description.position = 'bottom';
     return this;
 };
+
+/**
+ * @returns {this}
+ */
 HasFullPosition.prototype.atLeft = function() {
     this.$description.position = 'left';
     return this;
 };
+
+/**
+ * @returns {this}
+ */
 HasFullPosition.prototype.atRight = function() {
     this.$description.position = 'right';
     return this;
 };
+
+/**
+ * @returns {this}
+ */
 HasFullPosition.prototype.atTopLeading = function() {
     this.$description.position = 'top-leading';
     return this;
 };
+
+/**
+ * @returns {this}
+ */
 HasFullPosition.prototype.atTopTrailing = function() {
     this.$description.position = 'top-trailing';
     return this;
 };
+
+/**
+ * @returns {this}
+ */
 HasFullPosition.prototype.atTopCenter = function() {
     this.$description.position = 'top-center';
     return this;
 };
+
+/**
+ * @returns {this}
+ */
 HasFullPosition.prototype.atBottomLeading = function() {
     this.$description.position = 'bottom-leading';
     return this;
 };
+
+/**
+ * @returns {this}
+ */
 HasFullPosition.prototype.atBottomTrailing = function() {
     this.$description.position = 'bottom-trailing';
     return this;
 };
+
+/**
+ * @returns {this}
+ */
 HasFullPosition.prototype.atBottomCenter = function() {
     this.$description.position = 'bottom-center';
     return this;
 };
+
+/**
+ * @returns {this}
+ */
 HasFullPosition.prototype.atLeadingCenter = function() {
     this.$description.position = 'leading-center';
     return this;
 };
+
+/**
+ * @returns {this}
+ */
 HasFullPosition.prototype.atTrailingCenter = function() {
     this.$description.position = 'trailing-center';
     return this;

package/src/components/$traits/has-position/HasPosition.d.ts

@@ -0,0 +1,7 @@
+export interface HasPosition {
+    atTop(): this;
+    atBottom(): this;
+    atLeft(): this;
+    atRight(): this;
+    atCenter(): this;
+}

package/src/components/$traits/has-position/HasPosition.js

@@ -1,22 +1,44 @@
-
+/**
+ *
+ * @class
+ */
 export default function HasPosition() {}
 
+/**
+ * @returns {this}
+ */
 HasPosition.prototype.atTop = function() {
     this.$description.position = 'top';
     return this;
 };
+
+/**
+ * @returns {this}
+ */
 HasPosition.prototype.atBottom = function() {
     this.$description.position = 'bottom';
     return this;
 };
+
+/**
+ * @returns {this}
+ */
 HasPosition.prototype.atLeft = function() {
     this.$description.position = 'left';
     return this;
 };
+
+/**
+ * @returns {this}
+ */
 HasPosition.prototype.atRight = function() {
     this.$description.position = 'right';
     return this;
 };
+
+/**
+ * @returns {this}
+ */
 HasPosition.prototype.atCenter = function() {
     this.$description.position = 'center';
     return this;

package/src/components/$traits/has-resizable/HasResizable.d.ts

@@ -0,0 +1,13 @@
+interface ResizableOptions {
+    directions?: string[];
+    size?: {
+        minWidth?: number;
+        maxWidth?: number;
+        minHeight?: number;
+        maxHeight?: number;
+    };
+}
+
+export interface HasResizable {
+    makeResizable(parent: HTMLElement, options?: ResizableOptions): () => void;
+}

package/src/components/$traits/has-resizable/HasResizable.js

@@ -1,8 +1,17 @@
 
 import './has-resizable.css';
 
+/**
+ *
+ * @constructor
+ */
 export default function HasResizable() {}
 
+/**
+ * @param {HTMLElement} parent
+ * @param {{ directions?: string[], size?: { minWidth?: number, maxWidth?: number, minHeight?: number, maxHeight?: number } }} [options={}]
+ * @returns {() => void}
+ */
 HasResizable.prototype.makeResizable = function(parent, options = {}) {
     if(!this.emit) {
         throw new Error('HasResizable requires HasEventEmitter — add it via BaseComponent.use(Component, HasEventEmitter).');

package/src/components/$traits/has-validation/HasValidation.d.ts

@@ -0,0 +1,17 @@
+import type { ObservableItem } from '../../../../types/observable';
+
+export interface HasValidation {
+    required(message?: string): this;
+    custom(validatorFn: (value: unknown, allValues?: Record<string, unknown>) => boolean, message?: string): this;
+    addRule(validationFn: Function, params?: unknown[], message?: string): this;
+    requiredIf(
+        condition: ObservableItem<boolean> | boolean | string | ((v: Record<string, unknown>) => boolean),
+        message?: string
+    ): this;
+    clearErrorOn(event: string): this;
+    validateOn(event: string): this;
+    showErrors(show?: boolean | ObservableItem<boolean>): this;
+    hideErrors(): this;
+    setError(error: string | string[]): this;
+    validate(allValues?: Record<string, unknown>): { key: string; errors: string[] };
+}

package/src/components/$traits/has-validation/HasValidation.js

@@ -1,63 +1,110 @@
-import {resolveParams} from "../../form/utils";
-import BaseComponent from "../../BaseComponent";
-import {Validation} from "../../form/validation/Validation";
-
+import {resolveParams} from '../../form/utils';
+import BaseComponent from '../../BaseComponent';
+import {Validation} from '../../form/validation/Validation';
+
+/**
+ *
+ * @constructor
+ */
 export default function HasValidation() {}
 
+/**
+ * @param {string} message
+ * @returns {this}
+ */
 HasValidation.prototype.required = function(message) {
     this.$description.rules.push({
         fn:      Validation.required,
-        message: message || `${this.$description.label || this.$description.name} is required`
+        message: message || `${this.$description.label || this.$description.name} is required`,
     });
     return this;
 };
 
+/**
+ * @param {(value: *, allValues?: Record<string, *>) => boolean} validatorFn
+ * @param {string} [message]
+ * @returns {this}
+ */
 HasValidation.prototype.custom = function(validatorFn, message) {
     this.$description.rules.push({
         validate: validatorFn,
-        message:  message || 'Validation failed'
+        message:  message || 'Validation failed',
     });
     return this;
 };
 
+/**
+ * @param {Function} validationFn
+ * @param {*[]} params
+ * @param {string} [message]
+ * @returns {this}
+ */
 HasValidation.prototype.addRule = function(validationFn, params, message) {
     this.$description.rules.push({
         fn:      validationFn,
         params:  params || [],
-        message
+        message,
     });
     return this;
 };
 
+/**
+ * @param {Observable<boolean>|boolean|string|((v: Record<string, *>) => boolean)} condition
+ * @param {string} [message]
+ * @returns {this}
+ */
 HasValidation.prototype.requiredIf = function(condition, message) {
     return this.addRule(Validation.requiredIf, [condition], message);
 };
 
+/**
+ * @param {string} event
+ * @returns {this}
+ */
 HasValidation.prototype.clearErrorOn = function(event) {
     this.$description.clearErrorOn = event;
     return this;
 };
 
+/**
+ * @param {string} event
+ * @returns {this}
+ */
 HasValidation.prototype.validateOn = function(event) {
     this.$description.validateOn = event;
     return this;
 };
 
+/**
+ * @param {boolean|Observable<boolean>} [show=true]
+ * @returns {this}
+ */
 HasValidation.prototype.showErrors = function(show = true) {
     this.$description.showErrors = BaseComponent.obs(show);
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 HasValidation.prototype.hideErrors = function() {
     this.$description.showErrors.set(false);
     return this;
 };
 
+/**
+ * @param {string|string[]} error
+ * @returns {this}
+ */
 HasValidation.prototype.setError = function(error) {
     this.$description.errors?.set?.(error);
     return this;
 };
 
+/**
+ * @param {Record<string, *>} [allValues={}]
+ * @returns {{ key: string, errors: string[] }}
+ */
 HasValidation.prototype.validate = function(allValues = {}) {
     if(!this.$description.rules || this.$description.rules.length === 0) {
         this.$description.errors.clear();

package/src/components/BaseComponent.d.ts

@@ -0,0 +1,32 @@
+import type { ValidChild, GlobalAttributes, NdStyleMap } from '../../types/elements';
+import type { ObservableItem } from '../../types/observable';
+import type { CssPropertyAccumulator, ClassPropertyAccumulator } from '../../types/property-accumulator';
+
+export type EditableProps = Omit<GlobalAttributes, 'class' | 'style'> & {
+    class: ClassPropertyAccumulator;
+    style: CssPropertyAccumulator;
+};
+
+export interface BaseComponent {
+    setDescription(description: Record<string, unknown>): this;
+    postBuild(callback: (element: HTMLElement) => void): this;
+    refSelf(target: Record<string, unknown>, name: string): this;
+    toNdElement(): HTMLElement | DocumentFragment;
+    node(): HTMLElement | DocumentFragment;
+    toJSON(): Record<string, unknown>;
+    getEditableProps(): EditableProps;
+    resolveProps(): GlobalAttributes;
+    props(props: GlobalAttributes): this;
+    style(style: NdStyleMap): this;
+    showIf(condition: boolean | ObservableItem<boolean>): this;
+    visibility(condition: boolean | ObservableItem<boolean>): this;
+    context(context: unknown): this;
+    ghostDom(element: ValidChild): this;
+}
+
+export declare namespace BaseComponent {
+
+    function use(Component: Function, ...traits: Function[]): void;
+    function obs<T>(value: T | ObservableItem<T>): ObservableItem<T>;
+
+}

package/src/components/BaseComponent.js

@@ -1,7 +1,7 @@
-import {classPropertyAccumulator, cssPropertyAccumulator} from "../core/utils/property-accumulator";
-import {Observable} from "../core/data/Observable";
-import {ShowIf} from "../core/elements/control/show-if";
-import {NDElement} from "../core/wrappers/NDElement";
+import {classPropertyAccumulator, cssPropertyAccumulator} from '../core/utils/property-accumulator';
+import {Observable} from '../core/data/Observable';
+import {ShowIf} from '../core/elements/control/show-if';
+import {NDElement} from '../core/wrappers/NDElement';
 
 /**
  *
@@ -28,9 +28,13 @@ Object.defineProperty( BaseComponent.prototype, 'nd', {
             nd.$attachements = this.$attachements;
         }
         return nd;
-    }
+    },
 });
 
+/**
+ * @param {Function} Component
+ * @param {...Function} parents
+ */
 BaseComponent.extends = function(Component, ...parents) {
     const MainParent = parents[0] || BaseComponent;
     Component.prototype = Object.create(MainParent.prototype);
@@ -55,6 +59,10 @@ BaseComponent.obs = (value) => {
     return value.__$Observable ? value : Observable(value);
 };
 
+/**
+ * @param {Record<string, *>} description
+ * @returns {this}
+ */
 BaseComponent.prototype.setDescription = function(description) {
     for(const key in description) {
         if(this.$description[key]?.__$Observable) {
@@ -64,21 +72,30 @@ BaseComponent.prototype.setDescription = function(description) {
         this.$description[key] = description[key];
     }
     return this;
-}
+};
 
 BaseComponent.prototype.$storeElement = function(element) {
     this.$element = element;
     return this;
 };
 
+/**
+ * @param {(element: HTMLElement) => void} callback
+ * @returns {this}
+ */
 BaseComponent.prototype.postBuild = function(callback) {
     this.$postBuild = this.$postBuild || [];
     this.$postBuild.push(callback);
     return this;
-}
+};
 
 BaseComponent.prototype.ghostDom = NDElement.prototype.ghostDom;
 
+/**
+ * @param {Record<string, *>} target
+ * @param {string} name
+ * @returns {this}
+ */
 BaseComponent.prototype.refSelf = function(target, name) {
     target[name] = this;
     return this;
@@ -98,6 +115,9 @@ BaseComponent.prototype.$build = function() {
     return renderer(this.$description, this);
 };
 
+/**
+ * @returns {HTMLElement|DocumentFragment}
+ */
 BaseComponent.prototype.toNdElement = function() {
     if (this.$element) {
         return this.$element;
@@ -124,6 +144,9 @@ BaseComponent.prototype.toNdElement = function() {
 
 BaseComponent.prototype.node = BaseComponent.prototype.toNdElement;
 
+/**
+ * @returns {Record<string, *>}
+ */
 BaseComponent.prototype.toJSON = function() {
     if(!this.$description) {
         return {};
@@ -131,6 +154,10 @@ BaseComponent.prototype.toJSON = function() {
     return { ...this.$description };
 };
 
+/**
+ * @param {(description: *, component: *) => NdChild} renderFn
+ * @returns {this}
+ */
 BaseComponent.prototype.render = function(renderFn) {
     if (typeof renderFn !== 'function') {
         throw new Error('Custom renderer must be a function');
@@ -139,19 +166,31 @@ BaseComponent.prototype.render = function(renderFn) {
     return this;
 };
 
+/**
+ * Returns the internal editable props object for this component.
+ * The `class` and `style` properties are wrapped in reactive accumulators
+ * ({@link ClassPropertyAccumulatorType} and {@link CssPropertyAccumulatorType})
+ * instead of plain strings, to allow incremental reactive updates.
+ * @returns {Omit<GlobalAttributes, "class"|"style"> & { class: ClassPropertyAccumulatorType, style: CssPropertyAccumulatorType }}
+ */
 BaseComponent.prototype.getEditableProps = function() {
     if(!this.$editableProps) {
         const rawProps = this.$description.props || {};
         this.$editableProps = {
             ...rawProps,
             class: classPropertyAccumulator(rawProps.class || {}),
-            style: cssPropertyAccumulator(rawProps.style || {})
+            style: cssPropertyAccumulator(rawProps.style || {}),
         };
     }
 
     return this.$editableProps;
 };
 
+/**
+ * Returns a plain snapshot of the resolved props, with class and style
+ * unwrapped from their reactive accumulators to their current values.
+ * @returns {GlobalAttributes}
+ */
 BaseComponent.prototype.resolveProps = function() {
     if(!this.$editableProps) {
         return this.$description.props ? { ...this.$description.props } : {};
@@ -167,25 +206,42 @@ BaseComponent.prototype.resolveProps = function() {
     return props;
 };
 
+/**
+ * @param {GlobalAttributes} props
+ * @returns {this}
+ */
 BaseComponent.prototype.props = function(props) {
     this.$description.props = props;
     return this;
 };
 
+
+/**
+ * @param {NdStyleMap} style
+ * @returns {this}
+ */
 BaseComponent.prototype.style = function(style) {
     const props = this.getEditableProps();
     props.style.add(style);
     return this;
 };
 
+/**
+ * @param {boolean|Observable<boolean>} condition
+ * @returns {this}
+ */
 BaseComponent.prototype.showIf = function(condition) {
     this.$description.showIf = BaseComponent.obs(condition);
     return this;
 };
 
+/**
+ * @param {*} context
+ * @returns {this}
+ */
 BaseComponent.prototype.context = function(context) {
     this.$description.$context = context;
     return this;
-}
+};
 
 BaseComponent.prototype.visibility = BaseComponent.prototype.showIf;

package/src/components/accordion/Accordion.js

@@ -1,18 +1,25 @@
-import BaseComponent from "../BaseComponent";
-import HasEventEmitter from "../../core/utils/HasEventEmitter";
-import AccordionItem from "./AccordionItem";
-
+import BaseComponent from '../BaseComponent';
+import HasEventEmitter from '../../core/utils/HasEventEmitter';
+import AccordionItem from './AccordionItem';
 
 /**
- * Valid children types that can be rendered in the DOM
- * @typedef {HTMLElement|Text|DocumentFragment|string|Array<ValidChildren>} ValidChildren
- */
-
-/**
- * Component for creating accordion interfaces with expandable/collapsible items
- * @param {{ items?: Array<AccordionItem>, multiple?: boolean, variant?: string, renderContent?: (field: Accordion) => HTMLElement }} config
- * @returns {Accordion}
- * @class
+ * Collapsible accordion component. Manages a list of AccordionItem instances with expand/collapse behaviour.
+ *
+ *
+ * @example
+ * const accordion = new Accordion()
+ *     .item('Section 1', Div('Content of section 1'))
+ *     .item('Section 2', Div('Content of section 2'))
+ *     .multiple(true)
+ *     .variant('bordered');
+ *
+ * Accordion.use((description, instance) => {
+ *     // description.$items, description.multiple, description.variant...
+ *     return Div({ class: 'my-accordion' }, description.items);
+ * });
+ *
+ * @constructor
+ * @param {GlobalAttributes} [props]
  */
 export default function Accordion(props = {}) {
     if (!(this instanceof Accordion)) {
@@ -27,7 +34,7 @@ export default function Accordion(props = {}) {
         variant: null,
         renderContent: null,
         renderIndicator: null,
-        props
+        props,
     };
 }
 
@@ -35,11 +42,29 @@ BaseComponent.extends(Accordion);
 BaseComponent.use(Accordion, HasEventEmitter);
 
 Accordion.defaultTemplate = null;
+
+/**
+ * Registers the render template for Accordion.
+ * @param {(description: {
+ *     items: AccordionItem[],
+ *     multiple: boolean|null,
+ *     variant: string|null,
+ *     renderContent: ((desc: *, instance: Accordion) => NdChild)|null,
+ *     renderIndicator: ((desc: *, instance: Accordion) => NdChild)|null,
+ *     props: GlobalAttributes,
+ * }, instance: Accordion) => NdChild} template
+ */
 Accordion.use = function(template) {
     Accordion.defaultTemplate = template;
 };
 
 
+/**
+ * @param {NdChild|AccordionItem} title
+ * @param {NdChild} [content]
+ * @param {GlobalAttributes|((item: AccordionItem) => void)} [options]
+ * @returns {this}
+ */
 Accordion.prototype.item = function(title, content, options) {
     let item = null;