native-document 1.0.16 → 1.0.17-1.2

package/src/components/menu/Menu.js

@@ -0,0 +1,230 @@
+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);
+    }
+
+    BaseComponent.call(this, props);
+
+    this.$description = {
+        items: $.array(),
+        render: null,
+        orientation: 'horizontal',
+        closeOnSelect: true,
+        keyboardLoop: true,
+        activeItem: $(null),
+        active: null,
+        compactThreshold: 60,
+        clickFirst: false,
+        menuActive: $(null),
+        isMenuActivated: $(false),
+        compact: $(null),
+        props,
+    };
+
+
+    this.aria = { 'role': 'menu' };
+
+}
+
+BaseComponent.extends(Menu);
+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;
+};
+
+/**
+ * @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);
+    builder && builder(group);
+    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,
+    );
+};
+
+/**
+ * @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

@@ -0,0 +1,38 @@
+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,
+    };
+    this.aria = { 'role': 'separator' };
+}
+
+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

@@ -0,0 +1,127 @@
+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);
+    }
+
+    BaseComponent.call(this, props);
+
+    this.$description = {
+        icon: null,
+        label,
+        data: null,
+        items: $.array(),
+        render: null,
+        collapsable: false,
+        collapsed: null,
+        visibility: $(true),
+        collapsableOpenedIcon: null,
+        collapsableClosedIcon: null,
+        props,
+    };
+    this.aria = { 'role': 'group' };
+}
+
+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;
+};
+
+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);
+    this.$description.collapsableOpenedIcon = openedIcon;
+    this.$description.collapsableClosedIcon = 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

@@ -0,0 +1,191 @@
+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 = {};
+
+/**
+ * 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);
+    }
+
+    BaseComponent.call(this, props || EMPTY_PROPS);
+
+    this.$description = {
+        items: $.array(),
+        key: null,
+        action: null,
+        label: null,
+        icon: null,
+        shortcut: null,
+        disabled: null,
+        selected: null,
+        value: null,
+        data: null,
+        render: null,
+        trailing: null,
+        visibility: null,
+        props,
+    };
+    this.aria = { 'role': 'menuitem', 'tabindex': '-1' };
+
+}
+
+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;
+};
+
+BaseComponent.extends(MenuItem);
+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

@@ -0,0 +1,52 @@
+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);
+    }
+    MenuItem.call(this, props);
+    this.aria = { 'role': 'menuitem' };
+}
+
+MenuLink.prototype = Object.create(MenuItem.prototype);
+MenuLink.prototype.constructor = MenuLink;
+
+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

@@ -0,0 +1,14 @@
+import Menu from './Menu';
+import MenuItem from './MenuItem';
+import MenuGroup from './MenuGroup';
+import MenuDivider from './MenuDivider';
+import MenuLink from './MenuLink';
+
+
+export {
+    Menu,
+    MenuItem,
+    MenuGroup,
+    MenuDivider,
+    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;
+
+
+}