native-document 1.0.165 → 1.0.166

package/src/components/dropdown/Dropdown.js

@@ -1,13 +1,34 @@
-import BaseComponent from "../BaseComponent";
-import HasEventEmitter from "../../core/utils/HasEventEmitter";
-import DropdownGroup from "./DropdownGroup";
-import DropdownDivider from "./DropdownDivider";
-import DebugManager from "../../core/utils/debug-manager";
-import HasFullPosition from "../$traits/has-position/HasFullPosition";
-import { $ } from "../../core/data/Observable";
-import {normalizeDropdownItem} from "./helpers";
-import {NDElement} from "../../core/wrappers/NDElement";
-
+import BaseComponent from '../BaseComponent';
+import HasEventEmitter from '../../core/utils/HasEventEmitter';
+import DropdownGroup from './DropdownGroup';
+import DropdownDivider from './DropdownDivider';
+import DebugManager from '../../core/utils/debug-manager';
+import HasFullPosition from '../$traits/has-position/HasFullPosition';
+import { $ } from '../../core/data/Observable';
+import {normalizeDropdownItem} from './helpers';
+import {NDElement} from '../../core/wrappers/NDElement';
+
+/**
+ * Floating dropdown list anchored to a trigger element. Supports searchable, multiple selection, reactive data binding, grouping, and item rendering.
+ *
+ *
+ * @example
+ * const dropdown = new Dropdown()
+ *     .trigger(triggerEl)
+ *     .from(items, (item) => new DropdownItem().value(item.id).content(Span(item.name)))
+ *     .searchable(true)
+ *     .closeOnSelect(true)
+ *     .onOpen(() => console.log('opened'))
+ *     .onChange((value, item) => console.log(value));
+ *
+ * Dropdown.use((description, instance) => {
+ *     // description.items, description.isOpen, description.searchable...
+ *     return Div({ class: 'dropdown' });
+ * });
+ *
+ * @constructor
+ * @param {GlobalAttributes} [props]
+ */
 export default function Dropdown(props = {}) {
     if (!(this instanceof Dropdown)) {
         return new Dropdown(props);
@@ -52,6 +73,31 @@ BaseComponent.use(Dropdown, HasEventEmitter, HasFullPosition);
 
 Dropdown.defaultTemplate = null;
 
+/**
+ * Registers the render template for Dropdown.
+ * @param {(description: {
+ *     trigger: HTMLElement|null,
+ *     items: Observable<DropdownItem[]>,
+ *     interaction: 'click'|'hover'|'focus',
+ *     disabled: Observable<boolean>,
+ *     isOpen: Observable<boolean>,
+ *     maxHeight: string|number|null,
+ *     searchable: boolean,
+ *     searchValue: Observable<string>|null,
+ *     searchPlaceholder: string,
+ *     loopOnKeyboard: boolean,
+ *     renderItem: ((item: DropdownItem, instance: Dropdown) => NdChild)|null,
+ *     renderHeader: ((desc: *, instance: Dropdown) => NdChild)|null,
+ *     renderFooter: ((desc: *, instance: Dropdown) => NdChild)|null,
+ *     render: ((desc: *, instance: Dropdown) => NdChild)|null,
+ *     filter: ((item: DropdownItem, query: string) => boolean)|null,
+ *     mapper: ((item: *) => DropdownItem)|null,
+ *     matchTriggerWidth: boolean|null,
+ *     updatePositionOn: Observable<*>|null,
+ *     includeTriggerIntoGhost: boolean,
+ *     props: GlobalAttributes,
+ * }, instance: Dropdown) => NdChild} template
+ */
 Dropdown.use = function(template) {
     Dropdown.defaultTemplate = template;
 
@@ -73,11 +119,15 @@ Dropdown.use = function(template) {
                 this.ghostDom(dropdown.trigger(this.$element));
             });
             return this;
-        }
+        };
     }
 
 };
 
+/**
+ * @param {string} name
+ * @param {(d: Dropdown) => Dropdown} callback
+ */
 Dropdown.preset = function(name, callback) {
     if (Dropdown.prototype[name] || Dropdown[name]) {
         DebugManager.warn(`Warning: the ${name} method already exist in Dropdown.`);
@@ -86,58 +136,106 @@ Dropdown.preset = function(name, callback) {
     Dropdown[name] = (props) => callback(new Dropdown(props));
 };
 
+/**
+ * @param {Record<string, (d: Dropdown) => Dropdown>} presets
+ */
 Dropdown.presets = function(presets) {
     for (const name in presets) {
         Dropdown.preset(name, presets[name]);
     }
 };
 
+/**
+ * @returns {this}
+ */
 Dropdown.prototype.open = function() {
     this.$description.isOpen.set(true);
     return this;
 };
 
+/**
+ * @param {Observable<*[]>|*[]} source
+ * @param {((item: *) => DropdownItem)|null} [mapper]
+ * @returns {this}
+ */
 Dropdown.prototype.bind = function(source, mapper) {
     this.$description.items = source.__$Observable ? source : $.array(source);
     this.$description.mapper = mapper;
     return this;
 };
+
+/**
+ * Alias for {@link Dropdown.prototype.bind}
+ */
 Dropdown.prototype.source = Dropdown.prototype.bind;
+/**
+ * Alias for {@link Dropdown.prototype.bind}
+ */
 Dropdown.prototype.from = Dropdown.prototype.bind;
 
+/**
+ * @returns {this}
+ */
 Dropdown.prototype.close = function() {
     this.$description.isOpen.set(false);
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Dropdown.prototype.toggle = function() {
     return this.$description.isOpen.val() ? this.close() : this.open();
 };
 
+/**
+ * @param {boolean|Observable<boolean>} [disabled]
+ * @returns {this}
+ */
 Dropdown.prototype.disabled = function(disabled = true) {
     this.$description.disabled = BaseComponent.obs(disabled);
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Dropdown.prototype.enable = function() {
     this.$description.disabled.set(false);
     return this;
 };
+
+/**
+ * @returns {this}
+ */
 Dropdown.prototype.disable = function() {
     this.$description.disabled.set(true);
     return this;
-}
+};
 
+/**
+ * @param {number} value
+ * @returns {*}
+ */
 Dropdown.prototype.value = function(value) {
     this.$description.value = value;
     return this;
 };
 
+/**
+ * @param {*} placeholder
+ * @returns {this}
+ */
 Dropdown.prototype.placeholder = function(placeholder) {
     this.$description.placeholder = placeholder;
     return this;
 };
 
+/**
+ * @param {*} [searchable]
+ * @param {*} [placeholder]
+ * @returns {this}
+ */
 Dropdown.prototype.searchable = function(searchable = true, placeholder = null) {
     this.$description.searchable = searchable;
     if (placeholder) {
@@ -147,44 +245,87 @@ Dropdown.prototype.searchable = function(searchable = true, placeholder = null)
     return this;
 };
 
+/**
+ * @param {*} placeholder
+ * @returns {this}
+ */
 Dropdown.prototype.searchPlaceholder = function(placeholder) {
     this.$description.searchPlaceholder = placeholder;
     return this;
 };
 
+/**
+ * @param {*} closeOnClickOutside
+ * @returns {this}
+ */
 Dropdown.prototype.closeOnClickOutside = function(closeOnClickOutside) {
     this.$description.closeOnClickOutside = closeOnClickOutside;
     return this;
 };
 
+/**
+ * @param {*} closeOnEscape
+ * @returns {this}
+ */
 Dropdown.prototype.closeOnEscape = function(closeOnEscape) {
     this.$description.closeOnEscape = closeOnEscape;
     return this;
 };
 
+/**
+ * @param {*} closeOnSelect
+ * @returns {this}
+ */
 Dropdown.prototype.closeOnSelect = function(closeOnSelect) {
     this.$description.closeOnSelect = closeOnSelect;
     return this;
 };
 
+/**
+ * @param {*} maxHeight
+ * @returns {this}
+ */
 Dropdown.prototype.maxHeight = function(maxHeight) {
     this.$description.maxHeight = maxHeight;
     return this;
 };
 
+/**
+ * @param {HTMLElement|NDElement} trigger
+ * @param {boolean} [includeTriggerIntoGhost=true]
+ * @returns {this}
+ */
 Dropdown.prototype.trigger = function(trigger, includeTriggerIntoGhost = true) {
     this.$description.trigger = trigger;
     this.$description.includeTriggerIntoGhost = includeTriggerIntoGhost;
     return this;
 };
 
+/**
+ * @param {DropdownItem|NdChild|*} item
+ * @param {GlobalAttributes} [props={}]
+ * @returns {this}
+ */
 Dropdown.prototype.add = function(item, props = {}) {
     this.$description.items.push(normalizeDropdownItem(item, null, props));
     return this;
 };
+
+/**
+ * Alias for {@link Dropdown.prototype.add}
+ */
 Dropdown.prototype.menu = Dropdown.prototype.add;
+
+/**
+ * Alias for {@link Dropdown.prototype.add}
+ */
 Dropdown.prototype.item = Dropdown.prototype.add;
 
+/**
+ * @param {*[]} items
+ * @param {((item: *) => DropdownItem)|null} [mapper=null]
+ * @returns {this}
+ */
 Dropdown.prototype.from = function(items, mapper = null) {
     if(items.__$isObservableArray) {
         this.$description.items.set(items.map((item) => normalizeDropdownItem(item, mapper)));
@@ -198,6 +339,10 @@ Dropdown.prototype.from = function(items, mapper = null) {
     return this;
 };
 
+/**
+ * @param {(group: DropdownGroup) => void} groupBuilder
+ * @returns {this}
+ */
 Dropdown.prototype.group = function(groupBuilder) {
     const group = new DropdownGroup();
     groupBuilder && groupBuilder(group);
@@ -205,24 +350,43 @@ Dropdown.prototype.group = function(groupBuilder) {
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Dropdown.prototype.divider = function() {
     this.$description.items.push(new DropdownDivider());
     return this;
 };
 
+/**
+ * @param {number} value
+ * @returns {this}
+ */
 Dropdown.prototype.select = function(value) {
     this.$description.value?.set(value);
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Dropdown.prototype.next = function() {
-
+    // TODO : to implement
+    return this;
 };
 
+/**
+ * @returns {this}
+ */
 Dropdown.prototype.preview = function() {
-
+    // TODO : to implement
+    return this;
 };
 
+/**
+ * @param {*} loopOnKeyboard
+ * @returns {this}
+ */
 Dropdown.prototype.loopOnKeyboard = function(loopOnKeyboard) {
     this.$description.loopOnKeyboard = loopOnKeyboard;
     return this;
@@ -233,75 +397,134 @@ Dropdown.prototype.onChange= function(handler) {
     return this;
 };
 
+/**
+ * @param {Function} handler
+ * @returns {this}
+ */
 Dropdown.prototype.onOpen = function(handler) {
     this.on('open', handler);
     return this;
 };
 
+/**
+ * @param {Function} handler
+ * @returns {this}
+ */
 Dropdown.prototype.onClose = function(handler) {
     this.on('close', handler);
     return this;
 };
 
+/**
+ * @param {(desc: *, instance: *) => NdChild} renderFn
+ * @returns {this}
+ */
 Dropdown.prototype.renderSearch = function(renderFn) {
     this.$description.renderSearch = renderFn;
     return this;
 };
 
-
+/**
+ * @param {'click'|'hover'|'focus'} interaction
+ * @returns {this}
+ */
 Dropdown.prototype.interaction = function(interaction) {
     this.$description.interaction = interaction;
     return this;
 };
 
-
+/**
+ * @param {(item: DropdownItem, query: string) => boolean} filter
+ * @param {Observable<*>[]} [dependencies]
+ * @returns {this}
+ */
 Dropdown.prototype.filter = function(filter, dependencies) {
     this.$description.filter = filter;
     this.$description.filterDependencies = dependencies;
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Dropdown.prototype.onClicked = function() {
     this.$description.interaction = 'click';
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Dropdown.prototype.onHovered = function() {
     this.$description.interaction = 'hover';
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Dropdown.prototype.onFocused = function() {
     this.$description.interaction = 'focus';
     return this;
 };
 
+/**
+ * @param {(desc: *, instance: *) => NdChild} renderFn
+ * @returns {this}
+ */
 Dropdown.prototype.renderHeader = function(renderFn) {
     this.$description.renderHeader = renderFn;
     return this;
 };
 
+/**
+ * @param {(desc: *, instance: *) => NdChild} renderFn
+ * @returns {this}
+ */
 Dropdown.prototype.renderFooter = function(renderFn) {
     this.$description.renderFooter = renderFn;
     return this;
 };
 
+/**
+ * @param {(desc: *, instance: *) => NdChild} renderFn
+ * @returns {this}
+ */
 Dropdown.prototype.renderContent = function(renderFn) {
     this.$description.renderContent = renderFn;
     return this;
 };
+
+/**
+ * @returns {this}
+ */
 Dropdown.prototype.matchTriggerWidth = function() {
     this.$description.matchTriggerWidth = true;
     return this;
 };
+
+/**
+ * @param {HTMLElement|NDElement} target
+ * @returns {this}
+ */
 Dropdown.prototype.matchTargetWidth = function(target) {
     this.$description.matchTargetWidth = target;
     return this;
 };
+
+/**
+ * @param {Function} callback
+ * @returns {this}
+ */
 Dropdown.prototype.renderItem = function(callback) {
     this.$description.renderItem = callback;
     return this;
 };
+
+/**
+ * @param {*} updatePositionOn
+ * @returns {this}
+ */
 Dropdown.prototype.updatePositionOn = function(updatePositionOn) {
     this.$description.updatePositionOn = updatePositionOn;
     return this;

package/src/components/dropdown/DropdownDivider.js

@@ -1,12 +1,22 @@
-import BaseComponent from "../BaseComponent";
+import BaseComponent from '../BaseComponent';
 
+/**
+ * Visual separator between groups or items inside a Dropdown.
+ *
+ *
+ * @example
+ * dropdown.add(item1).divider().add(item2);
+ *
+ * @constructor
+ * @param {GlobalAttributes} [props]
+ */
 export default function DropdownDivider(props = {}) {
     if(!(this instanceof DropdownDivider)) {
         return new DropdownDivider();
     }
     this.$description  = {
         type: 'divider',
-        props
+        props,
     };
 }
 
@@ -14,11 +24,21 @@ BaseComponent.extends(DropdownDivider);
 
 DropdownDivider.defaultTemplate = null;
 
+/**
+ * Registers the render template for DropdownDivider.
+ * @param {(description: {
+ *     [key: string]: *
+ * }, instance: DropdownDivider) => NdChild} template
+ */
 DropdownDivider.use = function(template) {
     DropdownDivider.defaultTemplate = template;
 };
 
 
+/**
+ * @param {(desc: *, instance: *) => NdChild} renderFn
+ * @returns {this}
+ */
 DropdownDivider.prototype.render = function(renderFn) {
     this.$description.render = renderFn;
     return this;

package/src/components/dropdown/DropdownGroup.js

@@ -1,9 +1,22 @@
-import DropdownItem from "./DropdownItem";
-import BaseComponent from "../BaseComponent";
-import DropdownDivider from "./DropdownDivider";
-import { $ } from "../../core/data/Observable";
-import {normalizeDropdownItem} from "./helpers";
+import DropdownItem from './DropdownItem';
+import BaseComponent from '../BaseComponent';
+import DropdownDivider from './DropdownDivider';
+import { $ } from '../../core/data/Observable';
+import {normalizeDropdownItem} from './helpers';
 
+/**
+ * Groups DropdownItem instances under a heading inside a Dropdown.
+ *
+ *
+ * @example
+ * dropdown.group((group) => {
+ *     group.add(new DropdownItem().value('en').content(Span('English')))
+ *          .add(new DropdownItem().value('fr').content(Span('French')));
+ * });
+ *
+ * @constructor
+ * @param {GlobalAttributes} [props]
+ */
 export default function DropdownGroup(props) {
     if(!(this instanceof DropdownGroup)) {
         return new DropdownGroup(props);
@@ -19,18 +32,41 @@ export default function DropdownGroup(props) {
 BaseComponent.extends(DropdownGroup, DropdownItem);
 
 DropdownGroup.defaultTemplate = null;
+
+/**
+ * Registers the render template for DropdownGroup.
+ * @param {(description: {
+ *     [key: string]: *
+ * }, instance: DropdownGroup) => NdChild} template
+ */
 DropdownGroup.use = function(template) {
     DropdownGroup.defaultTemplate = template;
 };
 
+/**
+ * @param {DropdownItem|NdChild|*} item
+ * @param {GlobalAttributes} [props]
+ * @returns {this}
+ */
 DropdownGroup.prototype.add = function(item, props) {
     this.$description.items.push(normalizeDropdownItem(item, null, props));
     return this;
 };
 
+/**
+ * Alias for {@link DropdownGroup.prototype.add}
+ */
 DropdownGroup.prototype.menu = DropdownGroup.prototype.add;
+
+/**
+ * Alias for {@link DropdownGroup.prototype.add}
+ */
 DropdownGroup.prototype.item = DropdownGroup.prototype.add;
 
+/**
+ * @param {(group: DropdownGroup) => void} groupBuilder
+ * @returns {this}
+ */
 DropdownGroup.prototype.group = function(groupBuilder) {
     const item = new DropdownGroup();
     groupBuilder && groupBuilder(item);
@@ -38,6 +74,9 @@ DropdownGroup.prototype.group = function(groupBuilder) {
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 DropdownGroup.prototype.divider = function() {
     this.$description.items.push(new DropdownDivider());
     return this;