native-document 1.0.165 → 1.0.166

package/src/components/menu/HasMenuItem.js

@@ -1,9 +1,18 @@
-import MenuDivider from "./MenuDivider";
+import MenuDivider from './MenuDivider';
 
 const EMPTY_OPTIONS = {};
 
+/**
+ *
+ *
+ * @constructor
+ */
 export default function HasMenuItem() {}
 
+/**
+ * @param {*} parent
+ * @returns {this}
+ */
 HasMenuItem.prototype.setParent = function(parent) {
     this.$parent = parent;
     return this;
@@ -11,7 +20,7 @@ HasMenuItem.prototype.setParent = function(parent) {
 
 HasMenuItem.components = {
     MenuItem: null,
-    MenuLink: null
+    MenuLink: null,
 };
 
 const getParams = (options, configBuilder, props) => {
@@ -25,9 +34,14 @@ const getParams = (options, configBuilder, props) => {
         options = EMPTY_OPTIONS;
     }
 
-    return { options, configBuilder, props }
-}
+    return { options, configBuilder, props };
+};
 
+/**
+ * @param {NdChild} label
+ * @param {Record<GlobalAttributes|((item: MenuLink) => void)>} args
+ * @returns {this}
+ */
 HasMenuItem.prototype.link = function(label, ...args) {
     const { options, configBuilder, props } = getParams(...args);
     const MenuLink = HasMenuItem.components.MenuLink;
@@ -48,6 +62,11 @@ HasMenuItem.prototype.link = function(label, ...args) {
     return this;
 };
 
+/**
+ * @param {NdChild} label
+ * @param {Record<GlobalAttributes|((item: MenuLink) => void)>} args
+ * @returns {this}
+ */
 HasMenuItem.prototype.linkTo = function(label, ...args) {
     const { options, configBuilder, props } = getParams(...args);
     return this.link(label, { ...options, href: {isRoute: true, to: options.href} }, configBuilder, props);
@@ -55,6 +74,11 @@ HasMenuItem.prototype.linkTo = function(label, ...args) {
 
 
 
+/**
+ * @param {NdChild} label
+ * @param {GlobalAttributes|((item: MenuItem) => void)} args
+ * @returns {this}
+ */
 HasMenuItem.prototype.item = function(label, ...args) {
     const { options, configBuilder, props } = getParams(...args);
     const MenuItem = HasMenuItem.components.MenuItem;
@@ -74,6 +98,11 @@ HasMenuItem.prototype.item = function(label, ...args) {
     return this;
 };
 
+/**
+ * @param {NdChild} label
+ * @param {(group: MenuGroup) => void} builder
+ * @returns {this}
+ */
 HasMenuItem.prototype.group = function(label, builder) {
     const MenuGroup = HasMenuItem.components.MenuGroup;
     const group = new MenuGroup(label);
@@ -81,14 +110,22 @@ HasMenuItem.prototype.group = function(label, builder) {
     return this.add(group);
 };
 
+/**
+ * @returns {this}
+ */
 HasMenuItem.prototype.separator = function() {
     return this.add(new MenuDivider());
 };
 
+/**
+ * Alias for {@link HasMenuItem.prototype.separator}
+ */
 HasMenuItem.prototype.divider = HasMenuItem.prototype.separator;
 
-
-
+/**
+ * @param {MenuItem|MenuGroup|MenuLink|MenuDivider} item
+ * @returns {this}
+ */
 HasMenuItem.prototype.add = function(item) {
     if(item === this) {
         return this;
@@ -102,6 +139,9 @@ HasMenuItem.prototype.add = function(item) {
     return this;
 };
 
+/**
+ * @returns {number}
+ */
 HasMenuItem.prototype.getDepth = function() {
     let depth = 0;
     let current = this.$parent;
@@ -114,16 +154,25 @@ HasMenuItem.prototype.getDepth = function() {
     return depth;
 };
 
+/**
+ * @returns {this}
+ */
 HasMenuItem.prototype.onClicked = function() {
     this.$description.interaction = 'click';
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 HasMenuItem.prototype.onHovered = function() {
     this.$description.interaction = 'hover';
     return this;
 };
 
+/**
+ * @returns {*}
+ */
 HasMenuItem.prototype.getRoot = function() {
     let current = this;
     while(current.$parent) {

package/src/components/menu/Menu.js

@@ -1,14 +1,38 @@
-import BaseComponent from "../BaseComponent";
-import HasEventEmitter from "../../core/utils/HasEventEmitter";
-import HasItems from "../$traits/has-items/HasItems";
-import MenuGroup from "./MenuGroup";
-import HasMenuItem from "./HasMenuItem";
-import { $ } from '../../core/data/Observable'
-
+import BaseComponent from '../BaseComponent';
+import HasEventEmitter from '../../core/utils/HasEventEmitter';
+import HasItems from '../$traits/has-items/HasItems';
+import MenuGroup from './MenuGroup';
+import HasMenuItem from './HasMenuItem';
+import { $ } from '../../core/data/Observable';
+
+/**
+ * Navigation or action menu. Supports horizontal/vertical/inline orientation, keyboard navigation, nested groups, active item tracking.
+ *
+ *
+ * @example
+ * const menu = new Menu()
+ *     .vertical()
+ *     .closeOnSelect(true)
+ *     .keyboardLoop(true)
+ *     .item('Dashboard', () => navigate('/dashboard'))
+ *     .item('Settings', () => navigate('/settings'))
+ *     .separator()
+ *     .group('Reports', ReportIcon(), (group) => {
+ *         group.item('Monthly').item('Annual');
+ *     })
+ *     .onItemClick((item, e) => console.log(item));
+ *
+ * Menu.use((description, instance) => {
+ *     return Nav({ class: 'menu' }, description.items);
+ * });
+ *
+ * @constructor
+ * @param {GlobalAttributes} [props]
+ */
 export default function Menu(props = {}) {
 
     if(!(this instanceof Menu)) {
-        return new Menu(props)
+        return new Menu(props);
     }
 
     BaseComponent.call(this, props);
@@ -26,7 +50,7 @@ export default function Menu(props = {}) {
         menuActive: $(null),
         isMenuActivated: $(false),
         compact: $(null),
-        props
+        props,
     };
 
 }
@@ -36,82 +60,137 @@ BaseComponent.use(Menu, HasItems, HasEventEmitter, HasMenuItem);
 
 Menu.defaultTemplate = null;
 
+/**
+ * Registers the render template for Menu.
+ * @param {(description: {
+ *     items: Observable<Array<MenuItem|MenuGroup|MenuDivider>>,
+ *     render: ((desc: *, instance: Menu) => NdChild)|null,
+ *     orientation: 'horizontal'|'vertical'|'inline',
+ *     closeOnSelect: boolean,
+ *     keyboardLoop: boolean,
+ *     activeItem: Observable<MenuItem|null>,
+ *     active: ((item: MenuItem) => boolean)|null,
+ *     compactThreshold: number,
+ *     clickFirst: boolean,
+ *     props: GlobalAttributes,
+ * }, instance: Menu) => NdChild} template
+ */
 Menu.use = function(template) {
     Menu.defaultTemplate = template;
 };
 
-// Menu.prototype.$originalBuild = Menu.prototype.$build;
-// Menu.prototype.$build = function() {
-//     const activeSource = (typeof this.$description.active === 'function') ? this.$description.active() : this.$description.active;
-//     if(activeSource.__$Observable) {
-//         activeSource.subscribe((a) => {
-//             console.log('Subscribe', a);
-//             // Todo: update active element
-//         });
-//     }
-//     return this.$originalBuild();
-// };
-
+/**
+ * @param {(data: *) => *} resolver
+ * @returns {this}
+ */
 Menu.prototype.dataResolver = function(resolver) {
     this.$description.dataResolver = resolver;
     return this;
 };
 
+/**
+ * @param {NdChild} title
+ * @returns {this}
+ */
 Menu.prototype.title = function(title) {
     this.$description.title = title;
     return this;
 };
 
+/**
+ * @param {string} orientation
+ * @returns {this}
+ */
 Menu.prototype.orientation = function(orientation) {
     this.$description.orientation = orientation;
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Menu.prototype.horizontal = function() {
     this.$description.orientation = 'horizontal';
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Menu.prototype.vertical = function() {
     this.$description.orientation = 'vertical';
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Menu.prototype.inline = function() {
     this.$description.orientation = 'inline';
     return this;
 };
 
+/**
+ * @param {*} [close]
+ * @returns {this}
+ */
 Menu.prototype.closeOnSelect = function(close = true) {
     this.$description.closeOnSelect = close;
     return this;
 };
 
+/**
+ * @param {*} [keyboardLoop]
+ * @returns {this}
+ */
 Menu.prototype.keyboardLoop = function(keyboardLoop = true) {
     this.$description.keyboardLoop = keyboardLoop;
     return this;
 };
 
+/**
+ * @param {*} data
+ * @returns {this}
+ */
 Menu.prototype.data = function(data) {
     this.$description.data = data;
     return this;
 };
 
+/**
+ * @param {(item: MenuItem) => boolean} callback
+ * @returns {this}
+ */
 Menu.prototype.active = function(callback) {
     this.$description.active = callback;
     return this;
 };
 
+/**
+ * @param {(item: MenuItem, event: MouseEvent) => void} handler
+ * @returns {this}
+ */
 Menu.prototype.onItemClick = function(handler) {
     this.on('itemClick', handler);
     return this;
 };
 
+/**
+ * @param {(item: MenuItem) => void} handler
+ * @returns {this}
+ */
 Menu.prototype.onItemSelect = function(handler) {
     this.on('itemSelect', handler);
     return this;
 };
 
+/**
+ * @param {NdChild} label
+ * @param {NdChild} icon
+ * @param {(group: MenuGroup) => void} builder
+ * @param {GlobalAttributes} [props={}]
+ * @returns {this}
+ */
 Menu.prototype.group = function(label, icon, builder, props = {}) {
     const group = new MenuGroup(label, props);
     group.icon(icon);
@@ -119,17 +198,29 @@ Menu.prototype.group = function(label, icon, builder, props = {}) {
     return this.add(group);
 };
 
+/**
+ * @param {string} key
+ * @returns {MenuItem|undefined}
+ */
 Menu.prototype.getItem = function(key) {
     return this.$description.items.find(
-        item => item.$description.key === key || item.$description.label === key
+        item => item.$description.key === key || item.$description.label === key,
     );
 };
 
+/**
+ * @param {number} [width]
+ * @returns {this}
+ */
 Menu.prototype.compactThreshold = function(width = 60) {
     this.$description.compactThreshold = width;
     return this;
 };
 
+/**
+ * @param {*} [mode]
+ * @returns {this}
+ */
 Menu.prototype.clickFirst = function(mode = true) {
     this.$description.clickFirst = mode;
     return this;

package/src/components/menu/MenuDivider.js

@@ -1,13 +1,23 @@
-import BaseComponent from "../BaseComponent";
+import BaseComponent from '../BaseComponent';
 
 
+/**
+ * Visual separator between items or groups in a Menu.
+ *
+ *
+ * @example
+ * menu.item('Edit').separator().item('Delete');
+ *
+ * @constructor
+ * @param {GlobalAttributes} [props]
+ */
 export default function MenuDivider(props = {}) {
     if(!(this instanceof MenuDivider)) {
         return new MenuDivider(props);
     }
 
     this.$description = {
-        props
+        props,
     };
 }
 
@@ -16,6 +26,12 @@ BaseComponent.extends(MenuDivider);
 
 MenuDivider.defaultTemplate = null;
 
+/**
+ * Registers the render template for MenuDivider.
+ * @param {(description: {
+ *     props: GlobalAttributes,
+ * }, instance: MenuDivider) => NdChild} template
+ */
 MenuDivider.use = function(template) {
     MenuDivider.defaultTemplate = template;
 };

package/src/components/menu/MenuGroup.js

@@ -1,10 +1,24 @@
-import BaseComponent from "../BaseComponent";
-import HasItems from "../$traits/has-items/HasItems";
-import MenuDivider from "./MenuDivider";
-import HasMenuItem from "./HasMenuItem";
+import BaseComponent from '../BaseComponent';
+import HasItems from '../$traits/has-items/HasItems';
+import MenuDivider from './MenuDivider';
+import HasMenuItem from './HasMenuItem';
 import { $ } from '../../core/data/Observable';
 
-
+/**
+ * A collapsible group of MenuItems inside a Menu. Can hold items, dividers, and nested groups.
+ *
+ *
+ * @example
+ * const group = new MenuGroup(Span('Settings'))
+ *     .icon(SettingsIcon())
+ *     .collapsable(true)
+ *     .collapsed(false)
+ *     .item('Profile').item('Security').divider().item('Billing');
+ *
+ * @constructor
+ * @param {NdChild} label
+ * @param {GlobalAttributes} [props={}]
+ */
 export default function MenuGroup(label, props = {}) {
     if(!(this instanceof MenuGroup)) {
         return new MenuGroup(label, props);
@@ -23,7 +37,7 @@ export default function MenuGroup(label, props = {}) {
         visibility: $(true),
         collapsableOpenedIcon: null,
         collapsableClosedIcon: null,
-        props
+        props,
     };
 }
 
@@ -31,6 +45,22 @@ HasMenuItem.components.MenuGroup = MenuGroup;
 
 MenuGroup.defaultTemplate = null;
 
+/**
+ * Registers the render template for MenuGroup.
+ * @param {(description: {
+ *     icon: NdChild|null,
+ *     label: NdChild,
+ *     data: *|null,
+ *     items: Observable<Array<MenuItem|MenuDivider>>,
+ *     render: ((desc: *, instance: MenuGroup) => NdChild)|null,
+ *     collapsable: boolean,
+ *     collapsed: boolean|null,
+ *     visibility: Observable<boolean>,
+ *     collapsableOpenedIcon: NdChild|null,
+ *     collapsableClosedIcon: NdChild|null,
+ *     props: GlobalAttributes,
+ * }, instance: MenuGroup) => NdChild} template
+ */
 MenuGroup.use = function(template) {
     MenuGroup.defaultTemplate = template;
 };
@@ -38,16 +68,30 @@ MenuGroup.use = function(template) {
 BaseComponent.extends(MenuGroup);
 BaseComponent.use(MenuGroup, HasItems, HasMenuItem);
 
+/**
+ * @param {*} data
+ * @returns {this}
+ */
 MenuGroup.prototype.data = function(data) {
     this.$description.data = data;
     return this;
 };
 
+/**
+ * @param {NdChild} icon
+ * @returns {this}
+ */
 MenuGroup.prototype.icon = function(icon) {
     this.$description.icon = icon;
     return this;
 };
 
+/**
+ * @param {boolean} [mode=true]
+ * @param {NdChild} [openedIcon]
+ * @param {NdChild} [closedIcon]
+ * @returns {this}
+ */
 MenuGroup.prototype.collapsable = function(mode = true, openedIcon, closedIcon) {
     this.$description.collapsable = mode;
     this.$description.collapsed = this.$description.collapsed || $(true);
@@ -56,15 +100,26 @@ MenuGroup.prototype.collapsable = function(mode = true, openedIcon, closedIcon)
     return this;
 };
 
+/**
+ * @param {*} [mode]
+ * @returns {this}
+ */
 MenuGroup.prototype.collapsed = function(mode = true) {
     this.$description.collapsed.set(mode);
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 MenuGroup.prototype.divider = function() {
     return this.item(new MenuDivider());
 };
 
+/**
+ * @param {boolean|Observable<boolean>} mode
+ * @returns {this}
+ */
 MenuGroup.prototype.visibility = function(mode) {
     this.$description.visibility = BaseComponent.obs(mode);
     return this;