native-document 1.0.165 → 1.0.168

package/src/components/skeleton/Skeleton.js

@@ -1,8 +1,29 @@
-import BaseComponent from "../BaseComponent";
-import DebugManager from "../../core/utils/debug-manager";
-import { HStack, VStack } from "../stacks/index";
-import {Div} from "../../core/elements/index";
-
+import BaseComponent from '../BaseComponent';
+import DebugManager from '../../core/utils/debug-manager';
+
+/**
+ * Loading placeholder skeleton. Supports text, circle, rect, avatar, and image types, plus pulse/wave animations.
+ *
+ *
+ * @example
+ * // Single skeleton
+ * const skel = new Skeleton()
+ *     .text(3)
+ *     .wave()
+ *     .width('100%');
+ *
+ * // Static factories
+ * const cardSkel = Skeleton.card('horizontal');
+ * const listSkel = Skeleton.list(5);
+ * const tableSkel = Skeleton.table(10, 4);
+ *
+ * Skeleton.use((description, instance) => {
+ *     return Div({ class: \`skeleton skeleton--\${description.type}\` });
+ * });
+ *
+ * @constructor
+ * @param {GlobalAttributes} [props]
+ */
 export default function Skeleton(props = {}) {
     if (!(this instanceof Skeleton)) {
         return new Skeleton(props);
@@ -19,7 +40,7 @@ export default function Skeleton(props = {}) {
         height: null,
         loading: null,
         repeat: null,
-        props
+        props,
     };
 }
 
@@ -27,10 +48,28 @@ BaseComponent.extends(Skeleton);
 
 Skeleton.defaultTemplate = null;
 
+/**
+ * Registers the render template for Skeleton.
+ * @param {(description: {
+ *     type: 'rect'|'circle'|'text'|'avatar'|'image',
+ *     variant: 'pulse'|'wave',
+ *     borderRadiusType: 'rounded'|'pill'|'smooth'|null,
+ *     lines: number|null,
+ *     width: string|number|null,
+ *     height: string|number|null,
+ *     loading: Observable<boolean>|boolean|null,
+ *     repeat: number|null,
+ *     props: GlobalAttributes,
+ * }, instance: Skeleton) => NdChild} template
+ */
 Skeleton.use = function(template) {
     Skeleton.defaultTemplate = template;
 };
 
+/**
+ * @param {string} name
+ * @param {(s: Skeleton) => Skeleton} callback
+ */
 Skeleton.preset = function(name, callback) {
     if (Skeleton.prototype[name] || Skeleton[name]) {
         DebugManager.warn(`Warning: the ${name} method already exists in Skeleton.`);
@@ -39,122 +78,151 @@ Skeleton.preset = function(name, callback) {
     Skeleton[name] = (props) => callback(new Skeleton(props));
 };
 
+/**
+ * @param {Record<string, (s: Skeleton) => Skeleton>} presets
+ */
 Skeleton.presets = function(presets) {
     for (const name in presets) {
         Skeleton.preset(name, presets[name]);
     }
 };
 
+/**
+ * @param {string} type
+ * @returns {this}
+ */
 Skeleton.prototype.type = function(type) {
     this.$description.type = type;
     return this;
 };
+
+/**
+ * @param {number} [lines]
+ * @returns {this}
+ */
 Skeleton.prototype.text = function(lines = 1) {
     this.$description.lines = lines;
     return this.type('text');
 };
+
+/**
+ * @returns {this}
+ */
 Skeleton.prototype.circle = function() {
     return this.type('circle');
 };
+
+/**
+ * @returns {this}
+ */
 Skeleton.prototype.rect = function() {
     return this.type('rect');
 };
+
+/**
+ * @returns {this}
+ */
 Skeleton.prototype.avatar = function() {
     return this.type('avatar');
 };
+
+/**
+ * @returns {this}
+ */
 Skeleton.prototype.image = function() {
     return this.type('image');
 };
 
+/**
+ * @returns {this}
+ */
 Skeleton.prototype.rounded = function() {
     this.$description.borderRadiusType = 'rounded';
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Skeleton.prototype.pill = function() {
     this.$description.borderRadiusType = 'pill';
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Skeleton.prototype.smooth = function() {
     this.$description.borderRadiusType = 'smooth';
     return this;
 };
 
+/**
+ * @param {number} width
+ * @returns {this}
+ */
 Skeleton.prototype.width = function(width) {
     this.$description.width = width;
     return this;
 };
+
+/**
+ * @param {number} height
+ * @returns {this}
+ */
 Skeleton.prototype.height = function(height) {
     this.$description.height = height;
     return this;
 };
+
+/**
+ * @param {number} width
+ * @param {number} height
+ * @returns {this}
+ */
 Skeleton.prototype.size = function(width, height) {
     this.width(width);
     this.height(height);
     return this;
 };
 
+/**
+ * @param {string} name
+ * @returns {this}
+ */
 Skeleton.prototype.variant = function(name) {
     this.$description.variant = name;
     return this;
 };
+
+/**
+ * @returns {this}
+ */
 Skeleton.prototype.wave = function() {
     return this.variant('wave');
 };
+
+/**
+ * @returns {this}
+ */
 Skeleton.prototype.pulse = function() {
     return this.variant('pulse');
 };
 
+/**
+ * @param {boolean|Observable<boolean>} isLoading
+ * @returns {this}
+ */
 Skeleton.prototype.loading = function(isLoading) {
     this.$description.loading = isLoading;
     return this;
 };
-Skeleton.prototype.show = function() {};
-Skeleton.prototype.hide = function() {};
 
+/**
+ * @param {number} times
+ * @returns {this}
+ */
 Skeleton.prototype.repeat = function(times) {
     this.$description.repeat = times;
     return this;
 };
-
-
-Skeleton.card = function(type) {
-    return VStack([
-        Skeleton().type('image').height(200),
-        VStack([
-            Skeleton().text(1),
-            Skeleton().text(2),
-        ]).spacing('cozy')
-    ], { class: 'skeleton-card '+type }).spacing('cozy');
-};
-
-Skeleton.list = function(items = 3) {
-    return VStack(
-        Array.from({length: items}, () =>
-            HStack([
-                Div({ class: 'skeleton-list-item-avatar' }, Skeleton().circle().size(40, 40)),
-                Div({ class: 'skeleton-list-item-text' }, Skeleton().text(2)),
-            ], { class: 'skeleton-list-item' }).spacing('comfortable').alignCenter()
-        )
-    ).spacing('comfortable');
-};
-
-Skeleton.table = function(rows = 5, cols = 4) {
-    const buildRow = () =>
-        HStack(
-            Array.from({length: cols}, () =>
-                Div({ class: 'skeleton-table-col' }, Skeleton().rect().height(16))
-            ),
-            { class: 'skeleton-table-row' }
-        ).spacing('comfortable').alignCenter();
-
-    return VStack([
-        buildRow(),
-        ...Array.from({length: rows}, () => buildRow())
-    ]).spacing('cozy');
-};
-
-Skeleton.paragraph = function(lines = 3) {
-    return Skeleton().text(lines);
-};

package/src/components/skeleton/index.js

@@ -1,6 +1,6 @@
-import Skeleton from './Skeleton'
+import Skeleton from './Skeleton';
 
 
 export {
-    Skeleton
-}
+    Skeleton,
+};

package/src/components/skeleton/types/Skeleton.d.ts

@@ -0,0 +1,55 @@
+import type { ValidChild } from '../../../../types/elements';
+import type { ObservableItem } from '../../../../types/observable';
+import type { BaseComponent } from '../../BaseComponent';
+import type { GlobalAttributes } from '../../../../types/globals';
+
+export type SkeletonDescription = {
+        type: 'rect' | 'circle' | 'text' | 'avatar' | 'image';
+        variant: 'pulse' | 'wave';
+        borderRadiusType: 'rounded' | 'pill' | 'smooth' | null;
+        lines: number | null;
+        width: string | number | null;
+        height: string | number | null;
+        loading: ObservableItem<boolean> | boolean | null;
+        repeat: number | null;
+        props: GlobalAttributes;
+    };
+
+export interface SkeletonInterface extends BaseComponent {
+    type(type: 'rect' | 'circle' | 'text' | 'avatar' | 'image'): this;
+    text(lines?: number): this;
+    circle(): this;
+    rect(): this;
+    avatar(): this;
+    image(): this;
+    rounded(): this;
+    pill(): this;
+    smooth(): this;
+    width(width: string | number): this;
+    height(height: string | number): this;
+    size(width: string | number, height: string | number): this;
+    variant(name: 'pulse' | 'wave'): this;
+    wave(): this;
+    pulse(): this;
+    loading(isLoading: boolean | ObservableItem<boolean>): this;
+    show(): this;
+    hide(): this;
+    repeat(times: number): this;
+    render(renderFn: (description: SkeletonDescription, instance: SkeletonInterface) => ValidChild): this;
+}
+
+
+export declare function Skeleton(props?: Record<string, unknown>): SkeletonInterface;
+export declare namespace Skeleton {
+
+
+    function use(template: (description: SkeletonDescription, instance: SkeletonInterface) => ValidChild): void;
+    function preset(name: string, callback: (instance: SkeletonInterface) => SkeletonInterface): void;
+    function presets(presets: Record<string, (instance: SkeletonInterface) => SkeletonInterface>): void;
+    function card(type?: string): SkeletonInterface;
+    function list(items?: number): SkeletonInterface;
+    function table(rows?: number, cols?: number): SkeletonInterface;
+    function paragraph(lines?: number): SkeletonInterface;
+
+
+}

package/src/components/slider/Slider.js

@@ -1,5 +1,28 @@
-import Field from "../form/field/Field";
-
+import Field from '../form/field/Field';
+
+/**
+ * Range input slider. Supports single value, range mode (two handles), marks, tooltip, vertical orientation, and reactive binding.
+ *
+ *
+ * @example
+ * const slider = new Slider('volume')
+ *     .min(0)
+ *     .max(100)
+ *     .step(5)
+ *     .model(volumeObs)
+ *     .showTooltip(true)
+ *     .tooltipFormat((v) => \`\${v}%\`)
+ *     .marks([0, 25, 50, 75, 100])
+ *     .onChange((value) => console.log(value));
+ *
+ * Slider.use((description, instance) => {
+ *     return Div({ class: 'slider' });
+ * });
+ *
+ * @constructor
+ * @param {string} name
+ * @param {GlobalAttributes} [props={}]
+ */
 export default function Slider(name, props = {}) {
     if(!(this instanceof Slider)) {
         return new Slider(props);
@@ -36,7 +59,7 @@ export default function Slider(name, props = {}) {
         snapToMarks:   false,
         renderCursor:  null,
         renderThumb:   null,
-        props
+        props,
     };
 }
 
@@ -45,164 +68,338 @@ Slider.prototype.constructor = Slider;
 
 
 Slider.defaultTemplate = null;
+
+/**
+ * Registers the render template for Slider.
+ * @param {(description: {
+ *     name: string,
+ *     id: string|null,
+ *     value: Observable<number>|null,
+ *     defaultValue: number|null,
+ *     valueStart: Observable<number>|null,
+ *     valueEnd: Observable<number>|null,
+ *     range: boolean,
+ *     min: number,
+ *     max: number,
+ *     step: number,
+ *     showValue: boolean|null,
+ *     showTooltip: boolean|null,
+ *     tooltipFormat: ((value: number) => string)|null,
+ *     renderTooltip: ((value: number) => NdChild)|null,
+ *     marks: number[]|Array<{ value: number, label?: NdChild }>|null,
+ *     showMarks: boolean|null,
+ *     variant: string|null,
+ *     color: string|null,
+ *     trackColor: string|null,
+ *     fillColor: string|null,
+ *     vertical: boolean,
+ *     height: string|number|null,
+ *     disabled: Observable<boolean>|boolean|null,
+ *     readonly: Observable<boolean>|boolean|null,
+ *     reverse: boolean,
+ *     snapToMarks: boolean,
+ *     renderCursor: ((value: number) => NdChild)|null,
+ *     renderThumb: ((value: number) => NdChild)|null,
+ *     props: GlobalAttributes,
+ * }, instance: Slider) => NdChild} template
+ */
 Slider.use = function(template) {
     Slider.defaultTemplate = template;
 };
 
+/**
+ * @param {Observable<number>} observable
+ * @returns {this}
+ */
 Slider.prototype.model = function(observable) {
     this.$description.value = observable;
     return this;
 };
 
+/**
+ * @param {Observable<number>} observable
+ * @returns {this}
+ */
 Slider.prototype.modelStart = function(observable) {
     this.$description.valueStart = observable;
     return this;
 };
 
+/**
+ * @param {Observable<number>} observable
+ * @returns {this}
+ */
 Slider.prototype.modelEnd = function(observable) {
     this.$description.valueEnd = observable;
     return this;
 };
 
+/**
+ * @param {number} value
+ * @returns {this}
+ */
 Slider.prototype.defaultValue = function(value) {
     this.$description.defaultValue = value;
     return this;
 };
 
+/**
+ * @param {number} value
+ * @returns {this}
+ */
 Slider.prototype.setCurrentStep = function(value) {
     this.$description.value?.set(value);
     this.emit('change', value);
     return this;
 };
 
+/**
+ * @param {*} [enabled]
+ * @returns {this}
+ */
 Slider.prototype.range = function(enabled = true) {
     this.$description.range = enabled;
     return this;
 };
 
+/**
+ * @param {number} min
+ * @returns {this}
+ */
 Slider.prototype.min = function(min) {
     this.$description.min = min;
     return this;
 };
 
+/**
+ * @param {number} max
+ * @returns {this}
+ */
 Slider.prototype.max = function(max) {
     this.$description.max = max;
     return this;
 };
 
+/**
+ * @param {number} step
+ * @returns {this}
+ */
 Slider.prototype.step = function(step) {
     this.$description.step = step;
     return this;
 };
 
+/**
+ * @param {*} [enabled]
+ * @returns {this}
+ */
 Slider.prototype.showValue = function(enabled = true) {
     this.$description.showValue = enabled;
     return this;
 };
 
+/**
+ * @param {*} [enabled]
+ * @returns {this}
+ */
 Slider.prototype.showTooltip = function(enabled = true) {
     this.$description.showTooltip = enabled;
     return this;
 };
 
+/**
+ * @param {(value: number) => string} formatFn
+ * @returns {this}
+ */
 Slider.prototype.tooltipFormat = function(formatFn) {
     this.$description.tooltipFormat = formatFn;
     return this;
 };
 
+/**
+ * @param {(value: number) => NdChild} renderFn
+ * @returns {this}
+ */
 Slider.prototype.renderTooltip = function(renderFn) {
     this.$description.renderTooltip = renderFn;
     return this;
 };
 
+/**
+ * @param {number[]|{ value: number, label?: NdChild }[]} marks
+ * @returns {this}
+ */
 Slider.prototype.marks = function(marks) {
     this.$description.marks = marks;
     return this;
 };
 
+/**
+ * @param {*} [enabled]
+ * @returns {this}
+ */
 Slider.prototype.showMarks = function(enabled = true) {
     this.$description.showMarks = enabled;
     return this;
 };
 
+/**
+ * @param {*} [enabled]
+ * @returns {this}
+ */
 Slider.prototype.snapToMarks = function(enabled = true) {
     this.$description.snapToMarks = enabled;
     return this;
 };
 
+/**
+ * @param {string} name
+ * @returns {this}
+ */
 Slider.prototype.variant = function(name) {
     this.$description.variant = name;
     return this;
 };
 
-Slider.prototype.primary   = function() { return this.variant('primary');   };
-Slider.prototype.secondary = function() { return this.variant('secondary'); };
-Slider.prototype.success   = function() { return this.variant('success');   };
-Slider.prototype.warning   = function() { return this.variant('warning');   };
-Slider.prototype.danger    = function() { return this.variant('danger');    };
-Slider.prototype.info      = function() { return this.variant('info');      };
+Slider.prototype.primary   = function() {
+    return this.variant('primary');
+};
+
+/**
+ * @returns {this}
+ */
+Slider.prototype.secondary = function() {
+    return this.variant('secondary');
+};
+
+Slider.prototype.success   = function() {
+    return this.variant('success');
+};
+
+Slider.prototype.warning   = function() {
+    return this.variant('warning');
+};
+
+Slider.prototype.danger    = function() {
+    return this.variant('danger');
+};
 
+Slider.prototype.info      = function() {
+    return this.variant('info');
+};
+
+/**
+ * @param {string} color
+ * @returns {this}
+ */
 Slider.prototype.color = function(color) {
     this.$description.color = color;
     return this;
 };
 
+/**
+ * @param {string} color
+ * @returns {this}
+ */
 Slider.prototype.trackColor = function(color) {
     this.$description.trackColor = color;
     return this;
 };
 
+/**
+ * @param {string} color
+ * @returns {this}
+ */
 Slider.prototype.fillColor = function(color) {
     this.$description.fillColor = color;
     return this;
 };
 
-
+/**
+ * @param {string} color
+ * @returns {this}
+ */
 Slider.prototype.fullColor = function(color) {
     this.color(color).fillColor(color);
     return this;
 };
 
+/**
+ * @param {*} [enabled]
+ * @returns {this}
+ */
 Slider.prototype.vertical = function(enabled = true) {
     this.$description.vertical = enabled;
     return this;
 };
 
+/**
+ * @param {number} height
+ * @returns {this}
+ */
 Slider.prototype.height = function(height) {
     this.$description.height = height;
     return this;
 };
 
+/**
+ * @param {boolean|Observable<boolean>} [condition=true]
+ * @returns {this}
+ */
 Slider.prototype.disabled = function(condition = true) {
     this.$description.disabled = condition;
     return this;
 };
 
+/**
+ * @param {boolean|Observable<boolean>} [condition=true]
+ * @returns {this}
+ */
 Slider.prototype.readonly = function(condition = true) {
     this.$description.readonly = condition;
     return this;
 };
 
+/**
+ * @param {*} [enabled]
+ * @returns {this}
+ */
 Slider.prototype.reverse = function(enabled = true) {
     this.$description.reverse = enabled;
     return this;
 };
 
+/**
+ * @param {(value: number) => NdChild} renderFn
+ * @returns {this}
+ */
 Slider.prototype.renderThumb = function(renderFn) {
     this.$description.renderThumb = renderFn;
     return this;
 };
 
+/**
+ * @param {(value: number) => NdChild} renderFn
+ * @returns {this}
+ */
 Slider.prototype.renderCursor = function(renderFn) {
     this.$description.renderCursor = renderFn;
     return this;
 };
 
+/**
+ * @param {(value: number) => void} handler
+ * @returns {this}
+ */
 Slider.prototype.onChange = function(handler) {
     this.on('change', handler);
     return this;
 };
 
+/**
+ * @param {Function} handler
+ * @returns {this}
+ */
 Slider.prototype.onComplete = function(handler) {
     this.on('complete', handler);
     return this;