native-document 1.0.165 → 1.0.166

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;
+
+
+}

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

@@ -0,0 +1,19 @@
+import type { ValidChild } from '../../../../types/elements';
+import type { BaseComponent } from '../../BaseComponent';
+import type { GlobalAttributes } from '../../../../types/globals';
+
+export type MenuDividerDescription = { props: GlobalAttributes; };
+
+export interface MenuDividerInterface extends BaseComponent {
+    render(template: (description: MenuDividerDescription, instance: MenuDividerInterface) => ValidChild): this;
+}
+
+
+export declare function MenuDivider(props?: Record<string, unknown>): MenuDividerInterface;
+export declare namespace MenuDivider {
+
+
+    function use(template: (description: MenuDividerDescription, instance: MenuDividerInterface) => ValidChild): void;
+
+
+}

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

@@ -0,0 +1,44 @@
+import type { ValidChild } from '../../../../types/elements';
+import type { ObservableItem } from '../../../../types/observable';
+import type { BaseComponent } from '../../BaseComponent';
+import type { MenuItemInterface } from './MenuItem';
+import type { MenuDividerInterface } from './MenuDivider';
+import type { GlobalAttributes } from '../../../../types/globals';
+
+export type MenuGroupDescription = {
+        icon: ValidChild | null;
+        label: ValidChild;
+        data: unknown | null;
+        items: ObservableItem<Array<MenuItemInterface | MenuDividerInterface>>;
+        render: ((desc: MenuGroupDescription, instance: MenuGroupInterface) => ValidChild) | null;
+        collapsable: boolean;
+        collapsed: boolean | null;
+        visibility: ObservableItem<boolean>;
+        collapsableOpenedIcon: ValidChild | null;
+        collapsableClosedIcon: ValidChild | null;
+        props: GlobalAttributes;
+    };
+
+export interface MenuGroupInterface extends BaseComponent {
+    data(data: unknown): this;
+    icon(icon: ValidChild): this;
+    collapsable(mode?: boolean, openedIcon?: ValidChild, closedIcon?: ValidChild): this;
+    collapsed(mode?: boolean): this;
+    divider(): this;
+    visibility(mode: boolean | ObservableItem<boolean>): this;
+    item(label: ValidChild, ...args: unknown[]): this;
+    link(label: ValidChild, ...args: unknown[]): this;
+    separator(): this;
+    add(item: MenuItemInterface | MenuDividerInterface): this;
+    render(template: (description: MenuGroupDescription, instance: MenuGroupInterface) => ValidChild): this;
+}
+
+
+export declare function MenuGroup(label: ValidChild, props?: Record<string, unknown>): MenuGroupInterface;
+export declare namespace MenuGroup {
+
+
+    function use(template: (description: MenuGroupDescription, instance: MenuGroupInterface) => ValidChild): void;
+
+
+}

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

@@ -0,0 +1,46 @@
+import type { ValidChild } from '../../../../types/elements';
+import type { ObservableItem } from '../../../../types/observable';
+import type { BaseComponent } from '../../BaseComponent';
+import type { GlobalAttributes } from '../../../../types/globals';
+
+export type MenuItemDescription = {
+        key: string | null;
+        action: string | Record<string, unknown> | null;
+        label: ValidChild | null;
+        icon: ValidChild | null;
+        shortcut: ValidChild | null;
+        disabled: ObservableItem<boolean> | boolean | null;
+        selected: ObservableItem<boolean> | boolean | null;
+        value: unknown;
+        data: unknown | null;
+        render: ((desc: MenuItemDescription, instance: MenuItemInterface) => ValidChild) | null;
+        trailing: ValidChild | null;
+        visibility: ObservableItem<boolean> | null;
+        props: GlobalAttributes;
+    };
+
+export interface MenuItemInterface extends BaseComponent {
+    label(label: ValidChild): this;
+    icon(icon: ValidChild): this;
+    trailing(trailing: ValidChild): this;
+    shortcut(shortcut: ValidChild): this;
+    disabled(disabled?: boolean | ObservableItem<boolean>): this;
+    selected(selected?: boolean | ObservableItem<boolean>): this;
+    value(value: unknown): this;
+    action(action: string | Record<string, unknown>): this;
+    data(data: unknown): this;
+    divider(): this;
+    key(key: string): this;
+    visibility(mode: boolean | ObservableItem<boolean>): this;
+    render(template: (description: MenuItemDescription, instance: MenuItemInterface) => ValidChild): this;
+}
+
+
+export declare function MenuItem(props?: Record<string, unknown>): MenuItemInterface;
+export declare namespace MenuItem {
+
+
+    function use(template: (description: MenuItemDescription, instance: MenuItemInterface) => ValidChild): void;
+
+
+}

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

@@ -0,0 +1,16 @@
+import type { ValidChild } from '../../../../types/elements';
+import type { MenuItemInterface, MenuItemDescription } from './MenuItem';
+
+export interface MenuLinkInterface extends MenuItemInterface {
+    target(target: '_blank' | '_self' | '_parent' | '_top' | string): this;
+}
+
+
+export declare function MenuLink(props?: Record<string, unknown>): MenuLinkInterface;
+export declare namespace MenuLink {
+
+
+    function use(template: (description: MenuItemDescription, instance: MenuLinkInterface) => ValidChild): void;
+
+
+}