native-document 1.0.165 → 1.0.168

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;

package/src/components/menu/MenuItem.js

@@ -1,13 +1,33 @@
-import BaseComponent from "../BaseComponent";
-import HasItems from "../$traits/has-items/HasItems";
-import MenuDivider from "./MenuDivider";
-import MenuGroup from "./MenuGroup";
-import HasMenuItem from "./HasMenuItem";
+import BaseComponent from '../BaseComponent';
+import HasItems from '../$traits/has-items/HasItems';
+import MenuDivider from './MenuDivider';
+import MenuGroup from './MenuGroup';
+import HasMenuItem from './HasMenuItem';
 import { $ } from '../../core/data/Observable';
-import HasEventEmitter from "../../core/utils/HasEventEmitter";
-
-const EMPTY_PROPS = {}
-
+import HasEventEmitter from '../../core/utils/HasEventEmitter';
+
+const EMPTY_PROPS = {};
+
+/**
+ * A single clickable or selectable item in a Menu. Supports icon, label, shortcut, trailing slot, disabled and selected states.
+ *
+ *
+ * @example
+ * const item = new MenuItem()
+ *     .label(Span('Delete'))
+ *     .icon(TrashIcon())
+ *     .shortcut(Span('Del'))
+ *     .disabled(false)
+ *     .value('delete')
+ *     .divider();
+ *
+ * MenuItem.use((description, instance) => {
+ *     return Li(description.icon, description.label, description.shortcut);
+ * });
+ *
+ * @constructor
+ * @param {GlobalAttributes} [props]
+ */
 export default function MenuItem(props = {}) {
     if(!(this instanceof MenuItem)) {
         return new MenuItem(props || EMPTY_PROPS);
@@ -29,13 +49,31 @@ export default function MenuItem(props = {}) {
         render: null,
         trailing: null,
         visibility: null,
-        props
+        props,
     };
 
 }
 
 MenuItem.defaultTemplate = null;
 
+/**
+ * Registers the render template for MenuItem.
+ * @param {(description: {
+ *     key: string|null,
+ *     action: string|Record<string, *>|null,
+ *     label: NdChild|null,
+ *     icon: NdChild|null,
+ *     shortcut: NdChild|null,
+ *     disabled: Observable<boolean>|boolean|null,
+ *     selected: Observable<boolean>|boolean|null,
+ *     value: *,
+ *     data: *|null,
+ *     render: ((desc: *, instance: MenuItem) => NdChild)|null,
+ *     trailing: NdChild|null,
+ *     visibility: Observable<boolean>|null,
+ *     props: GlobalAttributes,
+ * }, instance: MenuItem) => NdChild} template
+ */
 MenuItem.use = function(template) {
     MenuItem.defaultTemplate = template;
 };
@@ -45,61 +83,107 @@ BaseComponent.use(MenuItem, HasItems, HasEventEmitter, HasMenuItem);
 
 HasMenuItem.components.MenuItem = MenuItem;
 
-
+/**
+ * @param {NdChild} label
+ * @returns {this}
+ */
 MenuItem.prototype.label = function(label) {
     this.$description.label = label;
     return this;
 };
 
+/**
+ * @param {NdChild} icon
+ * @returns {this}
+ */
 MenuItem.prototype.icon = function(icon) {
     this.$description.icon = icon;
     return this;
 };
 
+/**
+ * @param {NdChild} trailing
+ * @returns {this}
+ */
 MenuItem.prototype.trailing = function(trailing) {
     this.$description.trailing = trailing;
     return this;
 };
 
+/**
+ * @param {NdChild} shortcut
+ * @returns {this}
+ */
 MenuItem.prototype.shortcut = function(shortcut) {
     this.$description.shortcut = shortcut;
     return this;
 };
 
+/**
+ * @param {boolean|Observable<boolean>} [disabled=true]
+ * @returns {this}
+ */
 MenuItem.prototype.disabled = function(disabled = true) {
     this.$description.disabled = BaseComponent.obs(disabled);
     return this;
 };
 
+/**
+ * @param {boolean|Observable<boolean>} [selected=true]
+ * @returns {this}
+ */
 MenuItem.prototype.selected = function(selected = true) {
     this.$description.selected = BaseComponent.obs(selected);
     return this;
 };
 
+/**
+ * @param {number} value
+ * @returns {*}
+ */
 MenuItem.prototype.value = function(value) {
     this.$description.value = value;
     return this;
 };
 
+/**
+ * @param {*} action
+ * @returns {this}
+ */
 MenuItem.prototype.action = function(action) {
     this.$description.action = action;
     return this;
 };
 
+/**
+ * @param {*} data
+ * @returns {this}
+ */
 MenuItem.prototype.data = function(data) {
     this.$description.data = data;
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 MenuItem.prototype.divider = function() {
     return this.item(new MenuDivider());
 };
 
+/**
+ * @param {string} key
+ * @returns {this}
+ */
 MenuItem.prototype.key = function(key) {
     this.$description.key = key;
     return this;
 };
 
+/**
+ * @param {boolean|Observable<boolean>} mode
+ * @returns {this}
+ */
 MenuItem.prototype.visibility = function(mode) {
     this.$description.visibility = BaseComponent.obs(mode);
     return this;

package/src/components/menu/MenuLink.js

@@ -1,7 +1,21 @@
-import MenuItem from "./MenuItem";
-import HasMenuItem from "./HasMenuItem";
+import MenuItem from './MenuItem';
+import HasMenuItem from './HasMenuItem';
 
 
+/**
+ * A MenuItem that renders as an anchor (<a>). Inherits all MenuItem methods and adds target control.
+ *
+ *
+ * @example
+ * const link = new MenuLink()
+ *     .label(Span('Docs'))
+ *     .href('https://docs.example.com')
+ *     .target('_blank')
+ *     .icon(ExternalLinkIcon());
+ *
+ * @constructor
+ * @param {GlobalAttributes} [props]
+ */
 export default function MenuLink(props = {}) {
     if(!(this instanceof MenuLink)) {
         return new MenuLink(props);
@@ -16,10 +30,21 @@ HasMenuItem.components.MenuLink = MenuLink;
 
 MenuLink.defaultTemplate = null;
 
+/**
+ * Registers the render template for MenuLink.
+ * @param {(description: {
+ *     [key: string]: *
+ * }, instance: MenuLink) => NdChild} template
+ */
 MenuLink.use = function(template) {
     MenuLink.defaultTemplate = template;
 };
 
+/**
+ *
+ * @param {*} target
+ * @returns {this}
+ */
 MenuLink.prototype.target = function (target) {
     this.$description.target = target;
     return this;

package/src/components/menu/index.js

@@ -1,8 +1,8 @@
-import Menu from "./Menu";
-import MenuItem from "./MenuItem";
-import MenuGroup from "./MenuGroup";
-import MenuDivider from "./MenuDivider";
-import MenuLink from "./MenuLink";
+import Menu from './Menu';
+import MenuItem from './MenuItem';
+import MenuGroup from './MenuGroup';
+import MenuDivider from './MenuDivider';
+import MenuLink from './MenuLink';
 
 
 export {
@@ -10,5 +10,5 @@ export {
     MenuItem,
     MenuGroup,
     MenuDivider,
-    MenuLink
+    MenuLink,
 };

package/src/components/menu/types/Menu.d.ts

@@ -0,0 +1,60 @@
+import type { ValidChild } from '../../../../types/elements';
+import type { ObservableItem } from '../../../../types/observable';
+import type { BaseComponent } from '../../BaseComponent';
+import type { MenuItemInterface } from './MenuItem';
+import type { MenuGroupInterface } from './MenuGroup';
+import type { MenuLinkInterface } from './MenuLink';
+import type { MenuDividerInterface } from './MenuDivider';
+import type { GlobalAttributes } from '../../../../types/globals';
+
+export type MenuDescription = {
+        items: ObservableItem<Array<MenuItemInterface | MenuGroupInterface | MenuDividerInterface>>;
+        render: ((desc: MenuDescription, instance: MenuInterface) => ValidChild) | null;
+        orientation: 'horizontal' | 'vertical' | 'inline';
+        closeOnSelect: boolean;
+        keyboardLoop: boolean;
+        activeItem: ObservableItem<MenuItemInterface | null>;
+        active: ((item: MenuItemInterface) => boolean) | null;
+        compactThreshold: number;
+        clickFirst: boolean;
+        props: GlobalAttributes;
+    };
+
+export interface MenuInterface extends BaseComponent {
+    dataResolver(resolver: (data: unknown) => unknown): this;
+    title(title: ValidChild): this;
+    orientation(orientation: 'horizontal' | 'vertical' | 'inline'): this;
+    horizontal(): this;
+    vertical(): this;
+    inline(): this;
+    closeOnSelect(close?: boolean): this;
+    keyboardLoop(keyboardLoop?: boolean): this;
+    data(data: unknown): this;
+    active(callback: (item: MenuItemInterface) => boolean): this;
+    onItemClick(handler: (item: MenuItemInterface, event: MouseEvent) => void): this;
+    onItemSelect(handler: (item: MenuItemInterface) => void): this;
+    group(label: ValidChild, icon: ValidChild, builder: (group: MenuGroupInterface) => void, props?: Record<string, unknown>): this;
+    getItem(key: string): MenuItemInterface | undefined;
+    compactThreshold(width?: number): this;
+    clickFirst(mode?: boolean): this;
+    item(label: ValidChild, ...args: unknown[]): this;
+    link(label: ValidChild, ...args: unknown[]): this;
+    separator(): this;
+    divider(): this;
+    add(item: MenuItemInterface | MenuGroupInterface | MenuLinkInterface | MenuDividerInterface): this;
+    getDepth(): number;
+    getRoot(): unknown;
+    onClicked(): this;
+    onHovered(): this;
+    render(template: (description: MenuDescription, instance: MenuInterface) => ValidChild): this;
+}
+
+
+export declare function Menu(props?: Record<string, unknown>): MenuInterface;
+export declare namespace Menu {
+
+
+    function use(template: (description: MenuDescription, instance: MenuInterface) => ValidChild): void;
+
+
+}