native-document 1.0.165 → 1.0.168

package/src/components/popover/Popover.js

@@ -1,11 +1,33 @@
-import BaseComponent from "../BaseComponent";
-import HasEventEmitter from "../../core/utils/HasEventEmitter";
-import { Observable } from "../../core/data/Observable";
-import {ElementCreator} from "../../core/wrappers/ElementCreator";
-import {NDElement} from "../../core/wrappers/NDElement";
-import DebugManager from "../../core/utils/debug-manager";
-import HasFullPosition from "../$traits/has-position/HasFullPosition";
-
+import BaseComponent from '../BaseComponent';
+import HasEventEmitter from '../../core/utils/HasEventEmitter';
+import { Observable } from '../../core/data/Observable';
+import {ElementCreator} from '../../core/wrappers/ElementCreator';
+import {NDElement} from '../../core/wrappers/NDElement';
+import DebugManager from '../../core/utils/debug-manager';
+import HasFullPosition from '../$traits/has-position/HasFullPosition';
+
+/**
+ * Floating panel anchored to a trigger element. Supports click/hover/focus interactions, arrow, position, header/footer slots, and focus trap.
+ *
+ *
+ * @example
+ * const popover = new Popover(Div('Popover content'))
+ *     .trigger(myBtn)
+ *     .onClicked()
+ *     .position('bottom')
+ *     .offset(8)
+ *     .arrow(true)
+ *     .closeOnEscape(true)
+ *     .onOpen(() => console.log('open'));
+ *
+ * Popover.use((description, instance) => {
+ *     return Div({ class: 'popover' }, description.header, description.content, description.footer);
+ * });
+ *
+ * @constructor
+ * @param {NdChild} content
+ * @param {GlobalAttributes} [props={}]
+ */
 export default function Popover(content, props = {}) {
     if (!(this instanceof Popover)) {
         return new Popover(content, props);
@@ -55,6 +77,34 @@ BaseComponent.use(Popover, HasEventEmitter, HasFullPosition);
 
 Popover.defaultTemplate = null;
 
+/**
+ * Registers the render template for Popover.
+ * @param {(description: {
+ *     trigger: HTMLElement|null,
+ *     interaction: 'click'|'hover'|'focus',
+ *     content: NdChild,
+ *     header: NdChild|PopoverHeader|null,
+ *     footer: NdChild|PopoverFooter|null,
+ *     isOpen: Observable<boolean>,
+ *     closeOnEscape: boolean,
+ *     closeOnClickOutside: boolean,
+ *     focusTrap: boolean,
+ *     returnFocus: boolean,
+ *     position: string,
+ *     offset: number,
+ *     shift: Record<string, number>,
+ *     arrow: boolean,
+ *     data: *|null,
+ *     renderContent: ((desc: *, instance: Popover) => NdChild)|null,
+ *     renderHeader: ((desc: *, instance: Popover) => NdChild)|null,
+ *     renderFooter: ((desc: *, instance: Popover) => NdChild)|null,
+ *     render: ((desc: *, instance: Popover) => NdChild)|null,
+ *     variant: string|null,
+ *     matchTriggerWidth: boolean|null,
+ *     updatePositionOn: Observable<*>|null,
+ *     props: GlobalAttributes,
+ * }, instance: Popover) => NdChild} template
+ */
 Popover.use = function(template) {
     Popover.defaultTemplate = template;
 
@@ -74,15 +124,17 @@ Popover.use = function(template) {
                 } else {
                     this.ghostDom(Popover(content, props).trigger(this.$element));
                 }
-            })
+            });
             return this;
         };
     }
 
 };
 
-
-
+/**
+ * @param {string} name
+ * @param {Function} callback
+ */
 Popover.preset = function(name, callback) {
     if (Popover.prototype[name] || Popover[name]) {
         DebugManager.warn(`Warning: the ${name} method already exist in Popover.`);
@@ -91,181 +143,316 @@ Popover.preset = function(name, callback) {
     Popover[name] = (content, props) => callback(new Popover(content, props));
 };
 
+/**
+ * @param {*} presets
+ */
 Popover.presets = function(presets) {
     for (const name in presets) {
         Popover.preset(name, presets[name]);
     }
 };
 
+/**
+ * @param {HTMLElement|NDElement} trigger
+ * @returns {this}
+ */
 Popover.prototype.trigger = function(trigger) {
     this.$description.trigger = ElementCreator.getChild(trigger);
     return this;
 };
 
+/**
+ * @param {'click'|'hover'|'focus'} interaction
+ * @returns {this}
+ */
 Popover.prototype.interaction = function(interaction) {
     this.$description.interaction = interaction;
 };
 
+/**
+ * @returns {this}
+ */
 Popover.prototype.onClicked = function() {
     this.$description.interaction = 'click';
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Popover.prototype.onHovered = function() {
     this.$description.interaction = 'hover';
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Popover.prototype.onFocused = function() {
     this.$description.interaction = 'focus';
     return this;
 };
 
+/**
+ * @param {NdChild} content
+ * @returns {this}
+ */
 Popover.prototype.content = function(content) {
     this.$description.content = content;
     return this;
 };
 
+/**
+ * @param {NdChild|PopoverHeader} header
+ * @returns {this}
+ */
 Popover.prototype.header = function(header) {
     this.$description.header = header;
     return this;
 };
 
+/**
+ * @param {NdChild|PopoverFooter} footer
+ * @returns {this}
+ */
 Popover.prototype.footer = function(footer) {
     this.$description.footer = footer;
     return this;
 };
 
+/**
+ * @param {*} [closeOnEscape]
+ * @returns {this}
+ */
 Popover.prototype.closeOnEscape = function(closeOnEscape = true) {
     this.$description.closeOnEscape = closeOnEscape;
     return this;
 };
 
+/**
+ * @param {*} [closeOnClickOutside]
+ * @returns {this}
+ */
 Popover.prototype.closeOnClickOutside = function(closeOnClickOutside = true) {
     this.$description.closeOnClickOutside = closeOnClickOutside;
     return this;
 };
 
+/**
+ * @param {*} [trap]
+ * @returns {this}
+ */
 Popover.prototype.focusTrap = function(trap = true) {
     this.$description.focusTrap = trap;
     return this;
 };
 
+/**
+ * @param {*} [returnFocus]
+ * @returns {this}
+ */
 Popover.prototype.returnFocus = function(returnFocus = true) {
     this.$description.returnFocus = returnFocus;
     return this;
 };
 
+/**
+ * @param {string} position
+ * @returns {this}
+ */
 Popover.prototype.position = function(position) {
     this.$description.position = position;
     return this;
 };
 
+/**
+ * @param {number} offset
+ * @returns {this}
+ */
 Popover.prototype.offset = function(offset) {
     this.$description.offset = offset;
     return this;
 };
 
+/**
+ * @param {*} [arrow]
+ * @returns {this}
+ */
 Popover.prototype.arrow = function(arrow = true) {
     this.$description.arrow = arrow;
     return this;
 };
 
+/**
+ * @param {*} shift
+ * @returns {this}
+ */
 Popover.prototype.shift = function(shift) {
     this.$description.shift = shift;
     return this;
 };
 
+/**
+ * @param {Observable<boolean>} observable
+ * @returns {this}
+ */
 Popover.prototype.bindOpen = function(observable) {
     this.$description.isOpen = observable;
     return this;
 };
 
+/**
+ * @param {*} data
+ * @returns {this}
+ */
 Popover.prototype.data = function(data) {
     this.$description.data = data;
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Popover.prototype.open = function() {
     this.$description.isOpen.set(true);
     this.emit('open');
     return this;
 };
 
+
+/**
+ * @returns {this}
+ */
 Popover.prototype.close = function() {
     this.$description.isOpen.set(false);
     this.emit('close');
     return this;
 };
 
+
+/**
+ * @returns {this}
+ */
 Popover.prototype.toggle = function() {
     this.$description.isOpen.val() ? this.close() : this.open();
     return this;
 };
 
+/**
+ * @param {Function} handler
+ * @returns {this}
+ */
 Popover.prototype.onOpen = function(handler) {
     this.on('open', handler);
     return this;
 };
 
+/**
+ * @param {Function} handler
+ * @returns {this}
+ */
 Popover.prototype.onClose = function(handler) {
     this.on('close', handler);
     return this;
 };
 
+/**
+ * @param {(desc: *, instance: *) => NdChild} renderFn
+ * @returns {this}
+ */
 Popover.prototype.renderTrigger = function(renderFn) {
     this.$description.renderTrigger = renderFn;
     return this;
 };
 
+/**
+ * @param {(desc: *, instance: *) => NdChild} renderFn
+ * @returns {this}
+ */
 Popover.prototype.renderContent = function(renderFn) {
     this.$description.renderContent = renderFn;
     return this;
 };
 
+/**
+ * @param {(desc: *, instance: *) => NdChild} renderFn
+ * @returns {this}
+ */
 Popover.prototype.renderHeader = function(renderFn) {
     this.$description.renderHeader = renderFn;
     return this;
 };
 
+/**
+ * @param {(desc: *, instance: *) => NdChild} renderFn
+ * @returns {this}
+ */
 Popover.prototype.renderFooter = function(renderFn) {
     this.$description.renderFooter = renderFn;
     return this;
 };
 
+/**
+ * @param {string} variant
+ * @returns {this}
+ */
 Popover.prototype.variant = function(variant) {
     this.$description.variant = variant;
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Popover.prototype.primary = function() {
     this.$description.variant = 'primary';
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Popover.prototype.success = function() {
     this.$description.variant = 'success';
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Popover.prototype.warning = function() {
     this.$description.variant = 'warning';
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Popover.prototype.danger = function() {
     this.$description.variant = 'danger';
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Popover.prototype.info = function() {
     this.$description.variant = 'info';
     return this;
 };
+
+/**
+ * @returns {this}
+ */
 Popover.prototype.matchTriggerWidth = function() {
     this.$description.matchTriggerWidth = true;
     return this;
 };
+
+/**
+ * @param {*} updatePositionOn
+ * @returns {this}
+ */
 Popover.prototype.updatePositionOn = function(updatePositionOn) {
     this.$description.updatePositionOn = updatePositionOn;
     return this;

package/src/components/popover/PopoverFooter.js

@@ -1,5 +1,18 @@
-import BaseComponent from "../BaseComponent";
-
+import BaseComponent from '../BaseComponent';
+
+/**
+ * Optional footer slot for a Popover.
+ *
+ *
+ * @example
+ * const footer = new PopoverFooter(
+ *     HStack(Button(Span('Cancel')), Button(Span('Apply')))
+ * );
+ *
+ * @constructor
+ * @param {NdChild} [content]
+ * @param {GlobalAttributes} [config={}]
+ */
 export default function PopoverFooter(content, config = {}) {
     if(!(this instanceof PopoverFooter)) {
         return new PopoverFooter(content, config);
@@ -9,7 +22,7 @@ export default function PopoverFooter(content, config = {}) {
         content: content || null,
         data: null,
         render: null,
-        ...config
+        ...config,
     };
 }
 
@@ -17,21 +30,32 @@ BaseComponent.extends(PopoverFooter);
 
 PopoverFooter.defaultTemplate = null;
 
+/**
+ * Registers the render template for PopoverFooter.
+ * @param {(description: {
+ *     content: NdChild|null,
+ *     data: *|null,
+ *     render: ((desc: *, instance: PopoverFooter) => NdChild)|null,
+ * }, instance: PopoverFooter) => NdChild} template
+ */
 PopoverFooter.use = function(template) {
     PopoverFooter.defaultTemplate = template.popoverFooter;
 };
 
+/**
+ * @param {NdChild} content
+ * @returns {this}
+ */
 PopoverFooter.prototype.content = function(content) {
     this.$description.content = content;
     return this;
 };
 
+/**
+ * @param {*} data
+ * @returns {this}
+ */
 PopoverFooter.prototype.data = function(data) {
     this.$description.data = data;
     return this;
-};
-
-PopoverFooter.prototype.render = function(renderFn) {
-    this.$description.render = renderFn;
-    return this;
-};
+};

package/src/components/popover/PopoverHeader.js

@@ -1,5 +1,18 @@
-import BaseComponent from "../BaseComponent";
+import BaseComponent from '../BaseComponent';
 
+/**
+ * Optional header slot for a Popover, with an optional close button.
+ *
+ *
+ * @example
+ * const header = new PopoverHeader(Span('Filter options'))
+ *     .showClose(true)
+ *     .render((desc, instance) => H4(desc.content));
+ *
+ * @constructor
+ * @param {NdChild} [content]
+ * @param {GlobalAttributes} [config={}]
+ */
 export default function PopoverHeader(content, config = {}) {
     if(!(this instanceof PopoverHeader)) {
         return new PopoverHeader(content, config);
@@ -10,7 +23,7 @@ export default function PopoverHeader(content, config = {}) {
         showClose: false,
         data: null,
         render: null,
-        ...config
+        ...config,
     };
 }
 
@@ -18,10 +31,23 @@ BaseComponent.extends(PopoverHeader);
 
 PopoverHeader.defaultTemplate = null;
 
+/**
+ * Registers the render template for PopoverHeader.
+ * @param {(description: {
+ *     content: NdChild|null,
+ *     showClose: boolean,
+ *     data: *|null,
+ *     render: ((desc: *, instance: PopoverHeader) => NdChild)|null,
+ * }, instance: PopoverHeader) => NdChild} template
+ */
 PopoverHeader.use = function(template) {
     PopoverHeader.defaultTemplate = template.popoverHeader;
 };
 
+/**
+ * @param {NdChild} content
+ * @returns {this}
+ */
 PopoverHeader.prototype.content = function(content) {
     this.$description.content = content;
     return this;
@@ -32,12 +58,11 @@ PopoverHeader.prototype.showClose = function(show = true) {
     return this;
 };
 
+/**
+ * @param {*} data
+ * @returns {this}
+ */
 PopoverHeader.prototype.data = function(data) {
     this.$description.data = data;
     return this;
-};
-
-PopoverHeader.prototype.render = function(renderFn) {
-    this.$description.render = renderFn;
-    return this;
-};
+};

package/src/components/popover/index.js

@@ -1,10 +1,10 @@
-import Popover from "./Popover";
-import PopoverHeader from "./PopoverHeader";
-import PopoverFooter from "./PopoverFooter";
+import Popover from './Popover';
+import PopoverHeader from './PopoverHeader';
+import PopoverFooter from './PopoverFooter';
 
 
 export {
     Popover,
     PopoverHeader,
-    PopoverFooter
+    PopoverFooter,
 };

package/src/components/popover/types/Popover.d.ts

@@ -0,0 +1,83 @@
+import type { ValidChild } from '../../../../types/elements';
+import type { ObservableItem } from '../../../../types/observable';
+import type { BaseComponent } from '../../BaseComponent';
+import type { PopoverHeaderInterface } from './PopoverHeader';
+import type { PopoverFooterInterface } from './PopoverFooter';
+import type { GlobalAttributes } from '../../../../types/globals';
+
+export type PopoverDescription = {
+        trigger: HTMLElement | null;
+        interaction: 'click' | 'hover' | 'focus';
+        content: ValidChild;
+        header: ValidChild | PopoverHeaderInterface | null;
+        footer: ValidChild | PopoverFooterInterface | null;
+        isOpen: ObservableItem<boolean>;
+        closeOnEscape: boolean;
+        closeOnClickOutside: boolean;
+        focusTrap: boolean;
+        returnFocus: boolean;
+        position: string;
+        offset: number;
+        shift: Record<string, number>;
+        arrow: boolean;
+        data: unknown | null;
+        renderContent: ((desc: PopoverDescription, instance: PopoverInterface) => ValidChild) | null;
+        renderHeader: ((desc: PopoverDescription, instance: PopoverInterface) => ValidChild) | null;
+        renderFooter: ((desc: PopoverDescription, instance: PopoverInterface) => ValidChild) | null;
+        render: ((desc: PopoverDescription, instance: PopoverInterface) => ValidChild) | null;
+        variant: string | null;
+        matchTriggerWidth: boolean | null;
+        updatePositionOn: ObservableItem<unknown> | null;
+        props: GlobalAttributes;
+    };
+
+export interface PopoverInterface extends BaseComponent {
+    trigger(trigger: HTMLElement): this;
+    interaction(interaction: 'click' | 'hover' | 'focus'): this;
+    onClicked(): this;
+    onHovered(): this;
+    onFocused(): this;
+    content(content: ValidChild): this;
+    header(header: ValidChild | PopoverHeaderInterface): this;
+    footer(footer: ValidChild | PopoverFooterInterface): this;
+    closeOnEscape(closeOnEscape?: boolean): this;
+    closeOnClickOutside(closeOnClickOutside?: boolean): this;
+    focusTrap(trap?: boolean): this;
+    returnFocus(returnFocus?: boolean): this;
+    position(position: string): this;
+    offset(offset: number): this;
+    arrow(arrow?: boolean): this;
+    shift(shift: Record<string, number>): this;
+    bindOpen(observable: ObservableItem<boolean>): this;
+    data(data: unknown): this;
+    open(): this;
+    close(): this;
+    toggle(): this;
+    onOpen(handler: () => void): this;
+    onClose(handler: () => void): this;
+    renderTrigger(renderFn: (desc: PopoverDescription, instance: PopoverInterface) => ValidChild): this;
+    renderContent(renderFn: (desc: PopoverDescription, instance: PopoverInterface) => ValidChild): this;
+    renderHeader(renderFn: (desc: PopoverDescription, instance: PopoverInterface) => ValidChild): this;
+    renderFooter(renderFn: (desc: PopoverDescription, instance: PopoverInterface) => ValidChild): this;
+    variant(variant: string): this;
+    primary(): this;
+    success(): this;
+    warning(): this;
+    danger(): this;
+    info(): this;
+    matchTriggerWidth(): this;
+    updatePositionOn(obs: ObservableItem<unknown> | unknown): this;
+    render(template: (description: PopoverDescription, instance: PopoverInterface) => ValidChild): this;
+}
+
+
+export declare function Popover(content: ValidChild, props?: Record<string, unknown>): PopoverInterface;
+export declare namespace Popover {
+
+
+    function use(template: (description: PopoverDescription, instance: PopoverInterface) => ValidChild): void;
+    function preset(name: string, callback: (instance: PopoverInterface) => PopoverInterface): void;
+    function presets(presets: Record<string, (instance: PopoverInterface) => PopoverInterface>): void;
+
+
+}

package/src/components/popover/types/PopoverFooter.d.ts

@@ -0,0 +1,24 @@
+import type { ValidChild } from '../../../../types/elements';
+import type { BaseComponent } from '../../BaseComponent';
+
+export type PopoverFooterDescription = {
+        content: ValidChild | null;
+        data: unknown | null;
+        render: ((desc: PopoverFooterDescription, instance: PopoverFooterInterface) => ValidChild) | null;
+    };
+
+export interface PopoverFooterInterface extends BaseComponent {
+    content(content: ValidChild): this;
+    data(data: unknown): this;
+    render(renderFn: (desc: PopoverFooterDescription, instance: PopoverFooterInterface) => ValidChild): this;
+}
+
+
+export declare function PopoverFooter(content?: ValidChild, config?: Record<string, unknown>): PopoverFooterInterface;
+export declare namespace PopoverFooter {
+
+
+    function use(template: (description: PopoverFooterDescription, instance: PopoverFooterInterface) => ValidChild): void;
+
+
+}

package/src/components/popover/types/PopoverHeader.d.ts

@@ -0,0 +1,26 @@
+import type { ValidChild } from '../../../../types/elements';
+import type { BaseComponent } from '../../BaseComponent';
+
+export type PopoverHeaderDescription = {
+        content: ValidChild | null;
+        showClose: boolean;
+        data: unknown | null;
+        render: ((desc: PopoverHeaderDescription, instance: PopoverHeaderInterface) => ValidChild) | null;
+    };
+
+export interface PopoverHeaderInterface extends BaseComponent {
+    content(content: ValidChild): this;
+    showClose(show?: boolean): this;
+    data(data: unknown): this;
+    render(renderFn: (desc: PopoverHeaderDescription, instance: PopoverHeaderInterface) => ValidChild): this;
+}
+
+
+export declare function PopoverHeader(content?: ValidChild, config?: Record<string, unknown>): PopoverHeaderInterface;
+export declare namespace PopoverHeader {
+
+
+    function use(template: (description: PopoverHeaderDescription, instance: PopoverHeaderInterface) => ValidChild): void;
+
+
+}