native-document 1.0.165 → 1.0.166

package/src/components/toast/Toast.js

@@ -1,7 +1,28 @@
-import BaseComponent from "../BaseComponent";
-import HasEventEmitter from "../../core/utils/HasEventEmitter";
-import {Observable} from "../../core/data/Observable";
+import BaseComponent from '../BaseComponent';
+import HasEventEmitter from '../../core/utils/HasEventEmitter';
+import {Observable} from '../../core/data/Observable';
 
+/**
+ * Non-blocking notification toast. Supports type variants, duration, pause-on-hover, actions, and positioning.
+ *
+ * @example
+ * const toast = new Toast(Span('File saved successfully'))
+ *     .success()
+ *     .duration(4000)
+ *     .closable(true)
+ *     .pauseOnHover(true)
+ *     .atTopTrailing()
+ *     .action('View', () => navigate('/files'))
+ *     .onClose(() => console.log('dismissed'));
+ *
+ * Toast.use((description, instance) => {
+ *     return Div({ class: \`toast toast--\${description.type}\` }, description.content);
+ * });
+ *
+ * @constructor
+ * @param {NdChild} content
+ * @param {GlobalAttributes} [props={}]
+ */
 export default function Toast(content, props = {}) {
     if (!(this instanceof Toast)) {
         return new Toast(content, props);
@@ -22,7 +43,7 @@ export default function Toast(content, props = {}) {
         position: 'top-trailing',
         actions: [],
         render: null,
-        props
+        props,
     };
 }
 
@@ -30,91 +51,194 @@ BaseComponent.extends(Toast);
 BaseComponent.use(Toast, HasEventEmitter);
 
 Toast.defaultTemplate = null;
+
+/**
+ * Registers the render template for Toast.
+ * @param {(description: {
+ *     visibility: Observable<boolean>,
+ *     type: 'info'|'success'|'warning'|'error'|string|null,
+ *     title: NdChild|null,
+ *     content: NdChild,
+ *     icon: NdChild|null,
+ *     showIcon: boolean,
+ *     duration: number,
+ *     closable: boolean,
+ *     pauseOnHover: boolean,
+ *     position: 'top-leading'|'top-trailing'|'top-center'|'bottom-leading'|'bottom-trailing'|'bottom-center',
+ *     actions: Array<{ label: NdChild, handler: Function|null, variant: string|null }>,
+ *     render: ((desc: *, instance: Toast) => NdChild)|null,
+ *     props: GlobalAttributes,
+ * }, instance: Toast) => NdChild} template
+ */
 Toast.use = function(template) {
     Toast.defaultTemplate = template;
 };
 
 // Types
+/**
+ * @param {string} type
+ * @returns {this}
+ */
 Toast.prototype.type = function(type) {
     this.$description.type = type;
     return this;
 };
+
+/**
+ * @returns {this}
+ */
 Toast.prototype.info = function() {
     this.$description.type = 'info';
     return this;
 };
+
+/**
+ * @returns {this}
+ */
 Toast.prototype.success = function() {
     this.$description.type = 'success';
     return this;
 };
+
+/**
+ * @returns {this}
+ */
 Toast.prototype.warning = function() {
     this.$description.type = 'warning';
     return this;
 };
+
+/**
+ * @returns {this}
+ */
 Toast.prototype.error = function() {
     this.$description.type = 'error';
     return this;
 };
 
-
+/**
+ * @param {NdChild} title
+ * @returns {this}
+ */
 Toast.prototype.title = function(title) {
     this.$description.title = title;
     return this;
 };
+
+/**
+ * @param {NdChild} content
+ * @returns {this}
+ */
 Toast.prototype.content = function(content) {
     this.$description.content = content;
     return this;
 };
 
+/**
+ * @param {NdChild} icon
+ * @returns {this}
+ */
 Toast.prototype.icon = function(icon) {
     this.$description.icon = icon;
     return this;
 };
+
+/**
+ * @param {boolean} [show]
+ * @returns {this}
+ */
 Toast.prototype.showIcon = function(show = true) {
     this.$description.showIcon = show;
     return this;
 };
 
 // Behavior
+/**
+ * @param {number} ms
+ * @returns {this}
+ */
 Toast.prototype.duration = function(ms) {
     this.$description.duration = ms;
     return this;
 };
+
+/**
+ * @param {boolean} [closable]
+ * @returns {this}
+ */
 Toast.prototype.closable = function(closable = true) {
     this.$description.closable = closable;
     return this;
 };
+
+/**
+ * @param {*} [pauseOnHover]
+ * @returns {this}
+ */
 Toast.prototype.pauseOnHover = function(pauseOnHover = true) {
     this.$description.pauseOnHover = pauseOnHover;
     return this;
 };
 
 // Position
+
+/**
+ * @param {'top-leading'|'top-trailing'|'top-center'|'bottom-leading'|'bottom-trailing'|'bottom-center'} position
+ * @returns {this}
+ */
 Toast.prototype.position = function(position) {
     this.$description.position = position;
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Toast.prototype.atTopLeading = function() {
     return this.position('top-leading');
 };
 
+/**
+ * @returns {this}
+ */
 Toast.prototype.atTopTrailing = function() {
     return this.position('top-trailing');
 };
+
+/**
+ * @returns {this}
+ */
 Toast.prototype.atBottomLeading = function() {
     return this.position('bottom-leading');
 };
+
+/**
+ * @returns {this}
+ */
 Toast.prototype.atBottomTrailing = function() {
     return this.position('bottom-trailing');
 };
+
+/**
+ * @returns {this}
+ */
 Toast.prototype.atTopCenter = function() {
     return this.position('top-center');
 };
+
+/**
+ * @returns {this}
+ */
 Toast.prototype.atBottomCenter = function() {
     return this.position('bottom-center');
 };
 
+/**
+ * @param {NdChild} label
+ * @param {(() => void)} [handler]
+ * @param {string|null} [variant=null]
+ * @returns {this}
+ */
 Toast.prototype.action = function(label, handler, variant = null) {
     handler = handler || (() => this.close());
     this.$description.actions.push({ label, handler, variant });
@@ -126,6 +250,10 @@ Toast.prototype.close = function() {
     this.emit('close');
 };
 
+/**
+ * @param {Function} handler
+ * @returns {this}
+ */
 Toast.prototype.onClose = function(handler) {
     this.on('close', handler);
     return this;

package/src/components/toast/index.js

@@ -1,5 +1,5 @@
-import Toast from './Toast'
+import Toast from './Toast';
 
 export {
-    Toast
-}
+    Toast,
+};

package/src/components/toast/types/Toast.d.ts

@@ -0,0 +1,57 @@
+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 ToastDescription = {
+        visibility: ObservableItem<boolean>;
+        type: 'info' | 'success' | 'warning' | 'error' | string | null;
+        title: ValidChild | null;
+        content: ValidChild;
+        icon: ValidChild | null;
+        showIcon: boolean;
+        duration: number;
+        closable: boolean;
+        pauseOnHover: boolean;
+        position: 'top-leading' | 'top-trailing' | 'top-center' | 'bottom-leading' | 'bottom-trailing' | 'bottom-center';
+        actions: Array<{ label: ValidChild; handler: (() => void) | null; variant: string | null }>;
+        render: ((desc: ToastDescription, instance: ToastInterface) => ValidChild) | null;
+        props: GlobalAttributes;
+    };
+
+export interface ToastInterface extends BaseComponent {
+    type(type: 'info' | 'success' | 'warning' | 'error' | string): this;
+    info(): this;
+    success(): this;
+    warning(): this;
+    error(): this;
+    title(title: ValidChild): this;
+    content(content: ValidChild): this;
+    icon(icon: ValidChild): this;
+    showIcon(show?: boolean): this;
+    duration(ms: number): this;
+    closable(closable?: boolean): this;
+    pauseOnHover(pauseOnHover?: boolean): this;
+    position(position: 'top-leading' | 'top-trailing' | 'top-center' | 'bottom-leading' | 'bottom-trailing' | 'bottom-center'): this;
+    atTopLeading(): this;
+    atTopTrailing(): this;
+    atTopCenter(): this;
+    atBottomLeading(): this;
+    atBottomTrailing(): this;
+    atBottomCenter(): this;
+    render(renderFn: (desc: ToastDescription, instance: ToastInterface) => ValidChild): this;
+    action(label: ValidChild, handler?: () => void, variant?: string | null): this;
+    close(): void;
+    show(): void;
+    onClose(handler: () => void): this;
+}
+
+
+export declare function Toast(content: ValidChild, props?: Record<string, unknown>): ToastInterface;
+export declare namespace Toast {
+
+
+    function use(template: (description: ToastDescription, instance: ToastInterface) => ValidChild): void;
+
+
+}

package/src/components/toast/types/ToastError.d.ts

@@ -0,0 +1,7 @@
+import type { ValidChild } from '../../../../types/elements';
+import type { ToastInterface } from './Toast';
+
+export interface ToastErrorInterface extends ToastInterface {}
+
+
+export declare function ToastError(content: ValidChild, props?: Record<string, unknown>): ToastErrorInterface;

package/src/components/toast/types/ToastInfo.d.ts

@@ -0,0 +1,7 @@
+import type { ValidChild } from '../../../../types/elements';
+import type { ToastInterface } from './Toast';
+
+export interface ToastInfoInterface extends ToastInterface {}
+
+
+export declare function ToastInfo(content: ValidChild, props?: Record<string, unknown>): ToastInfoInterface;

package/src/components/toast/types/ToastSuccess.d.ts

@@ -0,0 +1,7 @@
+import type { ValidChild } from '../../../../types/elements';
+import type { ToastInterface } from './Toast';
+
+export interface ToastSuccessInterface extends ToastInterface {}
+
+
+export declare function ToastSuccess(content: ValidChild, props?: Record<string, unknown>): ToastSuccessInterface;

package/src/components/toast/types/ToastWarning.d.ts

@@ -0,0 +1,7 @@
+import type { ValidChild } from '../../../../types/elements';
+import type { ToastInterface } from './Toast';
+
+export interface ToastWarningInterface extends ToastInterface {}
+
+
+export declare function ToastWarning(content: ValidChild, props?: Record<string, unknown>): ToastWarningInterface;

package/src/components/tooltip/Tooltip.js

@@ -1,12 +1,29 @@
+import {Observable} from '../../core/data/Observable';
+import {NDElement} from '../../core/wrappers/NDElement';
+import BaseComponent from '../BaseComponent';
+import HasEventEmitter from '../../core/utils/HasEventEmitter';
+import DebugManager from '../../core/utils/debug-manager';
+
 /**
- * Tooltip - Interface
+ * Contextual tooltip anchored to a trigger element. Supports hover/click/focus interactions, position, arrow, and interactive mode.
+ *
+ * @example
+ * const tooltip = new Tooltip(Span('This is a helpful hint'))
+ *     .trigger(iconEl)
+ *     .onHovered()
+ *     .position('top')
+ *     .arrow(true)
+ *     .hideDelay(200)
+ *     .info();
+ *
+ * Tooltip.use((description, instance) => {
+ *     return Div({ class: 'tooltip' }, description.title, description.content);
+ * });
+ *
+ * @constructor
+ * @param {NdChild} content
+ * @param {GlobalAttributes} [props={}]
  */
-import {Observable} from "../../core/data/Observable";
-import {NDElement} from "../../core/wrappers/NDElement";
-import BaseComponent from "../BaseComponent";
-import HasEventEmitter from "../../core/utils/HasEventEmitter";
-import DebugManager from "../../core/utils/debug-manager";
-
 export default function Tooltip(content, props = {}) {
     if (!(this instanceof Tooltip)) {
         return new Tooltip(content, props);
@@ -37,6 +54,26 @@ BaseComponent.use(Tooltip, HasEventEmitter);
 
 Tooltip.defaultTemplate = null;
 
+
+/**
+ * Registers the render template for Tooltip.
+ * @param {(description: {
+ *     trigger: HTMLElement|NDElement|null,
+ *     interaction: 'hover'|'click'|'focus',
+ *     content: NdChild,
+ *     position: 'top'|'bottom'|'left'|'right',
+ *     title: NdChild|null,
+ *     isOpen: Observable<boolean>,
+ *     offset: number,
+ *     shift: Record<string, number>,
+ *     hideDelay: number,
+ *     arrow: boolean,
+ *     interactive: boolean,
+ *     variant: string|null,
+ *     updatePositionOn: Observable<*>|null,
+ *     props: GlobalAttributes,
+ * }, instance: Tooltip) => NdChild} template
+ */
 Tooltip.use = function(template) {
     Tooltip.defaultTemplate = template;
     if(!NDElement.prototype.tooltip) {
@@ -61,6 +98,10 @@ Tooltip.use = function(template) {
     }
 };
 
+/**
+ * @param {string} name
+ * @param {(t: Tooltip) => Tooltip} callback
+ */
 Tooltip.preset = function(name, callback) {
     if (Tooltip.prototype[name] || Tooltip[name]) {
         DebugManager.warn(`Warning: the ${name} method already exist in Tooltip.`);
@@ -69,146 +110,249 @@ Tooltip.preset = function(name, callback) {
     Tooltip[name] = (content, props) => callback(new Tooltip(content, props));
 };
 
+/**
+ * @param {Record<string, (t: Tooltip) => Tooltip>} presets
+ */
 Tooltip.presets = function(presets) {
     for (const name in presets) {
         Tooltip.preset(name, presets[name]);
     }
 };
 
+/**
+ * @param {HTMLElement|NDElement} trigger
+ * @returns {this}
+ */
 Tooltip.prototype.trigger = function(trigger) {
     this.$description.trigger = trigger;
     return this;
 };
 
+/**
+ * @param {NdChild} title
+ * @returns {this}
+ */
 Tooltip.prototype.title = function(title) {
     this.$description.title = title;
     return this;
 };
+
+/**
+ * @param {NdChild} content
+ * @returns {this}
+ */
 Tooltip.prototype.content = function(content) {
     this.$description.content = content;
     return this;
 };
+
+/**
+ * @param {string} variant
+ * @returns {this}
+ */
 Tooltip.prototype.variant = function(variant) {
     this.$description.variant = variant;
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Tooltip.prototype.primary = function() {
     this.$description.variant = 'primary';
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Tooltip.prototype.success = function() {
     this.$description.variant = 'success';
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Tooltip.prototype.warning = function() {
     this.$description.variant = 'warning';
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Tooltip.prototype.danger = function() {
     this.$description.variant = 'danger';
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Tooltip.prototype.info = function() {
     this.$description.variant = 'info';
     return this;
 };
 
+/**
+ * @param {'top'|'bottom'|'left'|'right'} position
+ * @returns {this}
+ */
 Tooltip.prototype.position = function(position) {
     this.$description.position = position;
     return this;
 };
+
+/**
+ * @returns {this}
+ */
 Tooltip.prototype.atTop = function() {
     this.$description.position = 'top';
     return this;
 };
+
+/**
+ * @returns {this}
+ */
 Tooltip.prototype.atBottom = function() {
     this.$description.position = 'bottom';
     return this;
 };
+
+/**
+ * @returns {this}
+ */
 Tooltip.prototype.atLeft = function() {
     this.$description.position = 'left';
     return this;
 };
+
+/**
+ * @returns {this}
+ */
 Tooltip.prototype.atRight = function() {
     this.$description.position = 'right';
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Tooltip.prototype.onClicked = function() {
     this.$description.interaction = 'click';
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Tooltip.prototype.onHovered = function() {
     this.$description.interaction = 'hover';
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Tooltip.prototype.onFocused = function() {
     this.$description.interaction = 'focus';
     return this;
 };
 
+/**
+ * @param {number} ms
+ * @returns {this}
+ */
 Tooltip.prototype.hideDelay = function(ms) {
     this.$description.hideDelay = ms;
     return this;
 };
+
+/**
+ * @param {*} [enabled]
+ * @returns {this}
+ */
 Tooltip.prototype.arrow = function(enabled = true) {
     this.$description.arrow = enabled;
     return this;
 };
+
+/**
+ * @param {boolean} [isInteractive=true]
+ * @returns {this}
+ */
 Tooltip.prototype.interactive = function(isInteractive = true) {
     this.$description.interactive = isInteractive;
     return this;
-}
+};
 
+/**
+ * @returns {this}
+ */
 Tooltip.prototype.open = function() {
     this.$description.isOpen.set(true);
     this.emit('open');
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Tooltip.prototype.close = function() {
     this.$description.isOpen.set(false);
     this.emit('close');
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Tooltip.prototype.toggle = function() {
     this.$description.isOpen.val() ? this.close() : this.open();
     return this;
 };
 
+/**
+ * @param {Function} handler
+ * @returns {this}
+ */
 Tooltip.prototype.onOpen = function(handler) {
     this.on('open', handler);
     return this;
 };
 
+/**
+ * @param {Function} handler
+ * @returns {this}
+ */
 Tooltip.prototype.onClose = function(handler) {
     this.on('close', handler);
     return this;
 };
 
-Tooltip.prototype.render = function(renderFn) {
-    this.$description.render = renderFn;
-    return this;
-};
-
+/**
+ * @param {number} offset
+ * @returns {this}
+ */
 Tooltip.prototype.offset = function(offset) {
     this.$description.offset = offset;
     return this;
 };
 
+/**
+ * @param {*} shift
+ * @returns {this}
+ */
 Tooltip.prototype.shift = function(shift) {
     this.$description.shift = shift;
     return this;
 };
 
+/**
+ * @param {*} updatePositionOn
+ * @returns {this}
+ */
 Tooltip.prototype.updatePositionOn = function(updatePositionOn) {
     this.$description.updatePositionOn = updatePositionOn;
     return this;

package/src/components/tooltip/index.js

@@ -1,5 +1,5 @@
 import Tooltip from './Tooltip';
 
 export {
-    Tooltip
-}
+    Tooltip,
+};

package/src/components/tooltip/prototypes.js

@@ -1,5 +1,5 @@
 
-import {NDElement} from "../../core/wrappers/NDElement";
+import {NDElement} from '../../core/wrappers/NDElement';
 
 NDElement.prototype.tooltip = function (tooltip) {
     // TODO: implement tooltip