native-document 1.0.165 → 1.0.168

package/src/components/list/ListItem.js

@@ -1,103 +1,212 @@
-import BaseComponent from "../BaseComponent";
-import Validator from "../../core/utils/validator";
-
-export default function ListItem(content, config = {}) {
-    if(!(this instanceof ListItem)) {
-        return new ListItem(content, config);
+import BaseComponent from '../BaseComponent';
+import HasEventEmitter from '../../core/utils/HasEventEmitter';
+import HasListItem from './HasListItem';
+
+/**
+ * A single item in a List. Supports icon, label, subtitle, trailing slot,
+ * disabled/selected states, swipe actions (mobile), and custom render.
+ *
+ * @example
+ * ListItem()
+ *     .label('Dashboard')
+ *     .icon(DashboardIcon())
+ *     .subtitle('View your metrics')
+ *     .trailing(Badge('New').primary())
+ *     .value('dashboard')
+ *     .selected(isActive)
+ *     .swipeLeading([Button('Archive').success()])
+ *     .swipeTrailing([Button('Delete').danger()])
+ *     .onClick(() => navigate('/dashboard'));
+ *
+ * ListItem.use((description, instance) => {
+ *     return Li({ class: 'list-item' }, description.label);
+ * });
+ *
+ * @constructor
+ * @param {GlobalAttributes} [props={}]
+ */
+export default function ListItem(props = {}) {
+    if (!(this instanceof ListItem)) {
+        return new ListItem(props);
     }
 
+    BaseComponent.call(this, props);
+
     this.$description = {
-        content: content || null,
-        icon: null,
-        trailing: null,
-        leading: null,
-        disabled: false,
-        selectable: false,
-        selected: false,
-        divider: false,
-        data: null,
-        render: null,
-        ...config
+        label:           null,
+        subtitle:        null,
+        icon:            null,
+        trailing:        null,
+        value:           null,
+        data:            null,
+        key:             null,
+        disabled:        null,
+        selected:        null,
+        visibility:      null,
+        isSelectedIcon:  null,
+        swipeLeading:    [],
+        swipeTrailing:   [],
+        render:          null,
+        props,
     };
 }
 
 BaseComponent.extends(ListItem);
+BaseComponent.use(ListItem, HasEventEmitter);
+
+HasListItem.components.ListItem = ListItem;
 
 ListItem.defaultTemplate = null;
 
+/**
+ * Registers the render template for ListItem.
+ * @param {(description: {
+ *     label:          NdChild|null,
+ *     subtitle:       NdChild|null,
+ *     icon:           NdChild|null,
+ *     trailing:       NdChild|null,
+ *     value:          *,
+ *     data:           *|null,
+ *     key:            string|null,
+ *     disabled:       Observable<boolean>|null,
+ *     selected:       Observable<boolean>|null,
+ *     visibility:     Observable<boolean>|null,
+ *     isSelectedIcon: NdChild|null,
+ *     swipeLeading:   NdChild[],
+ *     swipeTrailing:  NdChild[],
+ *     render:         ((desc: *, instance: ListItem) => NdChild)|null,
+ *     props:          GlobalAttributes,
+ * }, instance: ListItem) => NdChild} template
+ */
 ListItem.use = function(template) {
     ListItem.defaultTemplate = template;
 };
 
-ListItem.prototype.content = function(content) {
-    this.$description.content = content;
+/**
+ * @param {NdChild} label
+ * @returns {this}
+ */
+ListItem.prototype.label = function(label) {
+    this.$description.label = label;
     return this;
 };
 
-ListItem.prototype.label = function(label) {
-    this.$description.content = label;
+/**
+ * @param {NdChild} subtitle
+ * @returns {this}
+ */
+ListItem.prototype.subtitle = function(subtitle) {
+    this.$description.subtitle = subtitle;
     return this;
 };
 
+/**
+ * @param {NdChild} icon
+ * @returns {this}
+ */
 ListItem.prototype.icon = function(icon) {
     this.$description.icon = icon;
     return this;
 };
 
-ListItem.prototype.leading = function(leading) {
-    this.$description.leading = leading;
+/**
+ * @param {NdChild} trailing
+ * @returns {this}
+ */
+ListItem.prototype.trailing = function(trailing) {
+    this.$description.trailing = trailing;
     return this;
 };
 
-ListItem.prototype.trailing = function(trailing) {
-    this.$description.trailing = trailing;
+/**
+ * @param {*} value
+ * @returns {this}
+ */
+ListItem.prototype.value = function(value) {
+    this.$description.value = value;
     return this;
 };
 
-ListItem.prototype.leading = function(leading) {
-    this.$description.leading = leading;
+/**
+ * @param {*} data
+ * @returns {this}
+ */
+ListItem.prototype.data = function(data) {
+    this.$description.data = data;
     return this;
 };
 
-ListItem.prototype.disabled = function(disabled = true) {
-    this.$description.disabled = disabled;
+/**
+ * @param {string} key
+ * @returns {this}
+ */
+ListItem.prototype.key = function(key) {
+    this.$description.key = key;
     return this;
 };
 
-ListItem.prototype.selectable = function() {
-    this.$description.selectable = true;
-    if(Validator.isObservable(this.$description.selected)) {
-        return this;
-    }
-    this.$description.selected = $(false);
+/**
+ * @param {boolean|Observable<boolean>} [disabled=true]
+ * @returns {this}
+ */
+ListItem.prototype.disabled = function(disabled = true) {
+    this.$description.disabled = BaseComponent.obs(disabled);
     return this;
 };
 
+/**
+ * @param {boolean|Observable<boolean>} [selected=true]
+ * @returns {this}
+ */
 ListItem.prototype.selected = function(selected = true) {
-    if(Validator.isObservable(this.$description.selected)) {
-        this.$description.selected.set(selected);
-        return this;
-    }
-    this.$description.selected = selected;
+    this.$description.selected = BaseComponent.obs(selected);
     return this;
 };
 
-ListItem.prototype.divider = function(show = true) {
-    this.$description.divider = show;
+/**
+ * @param {boolean|Observable<boolean>} mode
+ * @returns {this}
+ */
+ListItem.prototype.visibility = function(mode) {
+    this.$description.visibility = BaseComponent.obs(mode);
     return this;
 };
 
-ListItem.prototype.data = function(data) {
-    this.$description.data = data;
+/**
+ * Icon displayed when the item is selected (selectByClick mode).
+ * @param {NdChild} icon
+ * @returns {this}
+ */
+ListItem.prototype.isSelectedIcon = function(icon) {
+    this.$description.isSelectedIcon = icon;
     return this;
 };
 
-ListItem.prototype.render = function(renderFn) {
-    this.$description.render = renderFn;
+/**
+ * Swipe actions revealed on the leading (left) side — mobile swipe gesture.
+ * @param {NdChild[]} actions
+ * @returns {this}
+ */
+ListItem.prototype.swipeLeading = function(actions) {
+    this.$description.swipeLeading = Array.isArray(actions) ? actions : [actions];
     return this;
 };
 
+/**
+ * Swipe actions revealed on the trailing (right) side — mobile swipe gesture.
+ * @param {NdChild[]} actions
+ * @returns {this}
+ */
+ListItem.prototype.swipeTrailing = function(actions) {
+    this.$description.swipeTrailing = Array.isArray(actions) ? actions : [actions];
+    return this;
+};
 
-ListItem.prototype.$build = function() {
-
-};
+/**
+ * @param {Function} handler
+ * @returns {this}
+ */
+ListItem.prototype.onClick = function(handler) {
+    this.on('click', handler);
+    return this;
+};

package/src/components/list/index.js

@@ -1,10 +1,12 @@
-import List from "./List";
-import ListItem from "./ListItem";
-import ListGroup from "./ListGroup";
+import List from './List';
+import ListItem from './ListItem';
+import ListGroup from './ListGroup';
+import ListDivider from './ListDivider';
 
 
-export default {
+export {
     List,
     ListItem,
-    ListGroup
-}
+    ListGroup,
+    ListDivider,
+};

package/src/components/list/types/List.d.ts

@@ -0,0 +1,43 @@
+import type { ValidChild } from '../../../../types/elements';
+import type { ObservableItem } from '../../../../types/observable';
+import type { BaseComponent } from '../../BaseComponent';
+import type { ListItemInterface } from './ListItem';
+import type { GlobalAttributes } from '../../../../types/globals';
+
+export type ListDescription = {
+        selectable: boolean;
+        multiSelect: boolean;
+        selectedValues: ObservableItem<unknown[]> | null;
+        inset: boolean;
+        divider: boolean;
+        data: unknown | null;
+        render: ((desc: ListDescription, instance: ListInterface) => ValidChild) | null;
+        selectByCheckbox: boolean;
+        selectByClick: boolean;
+        loopOnKeyboard: boolean;
+        props: GlobalAttributes;
+    };
+
+export interface ListInterface extends BaseComponent {
+    selectable(selectable?: boolean): this;
+    selectByClick(): void;
+    selectByCheckbox(): void;
+    multiSelect(multi?: boolean): this;
+    selectedValuesModel(observable: ObservableItem<unknown[]>): this;
+    inset(inset?: boolean): this;
+    withDivider(divider?: boolean): this;
+    data(data: unknown): this;
+    onItemClick(handler: (item: ListItemInterface, event: MouseEvent) => void): this;
+    onItemSelect(handler: (item: ListItemInterface) => void): this;
+    render(template: (description: ListDescription, instance: ListInterface) => ValidChild): this;
+}
+
+
+export declare function List(config?: Record<string, unknown>): ListInterface;
+export declare namespace List {
+
+
+    function use(template: (description: ListDescription, instance: ListInterface) => ValidChild): void;
+
+
+}

package/src/components/list/types/ListGroup.d.ts

@@ -0,0 +1,37 @@
+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 ListGroupDescription = {
+        header: ValidChild | null;
+        footer: ValidChild | null;
+        items: unknown[];
+        inset: boolean;
+        data: unknown | null;
+        renderHeader: ((desc: ListGroupDescription, instance: ListGroupInterface) => ValidChild) | null;
+        renderFooter: ((desc: ListGroupDescription, instance: ListGroupInterface) => ValidChild) | null;
+        render: ((desc: ListGroupDescription, instance: ListGroupInterface) => ValidChild) | null;
+        props: GlobalAttributes;
+    };
+
+export interface ListGroupInterface extends BaseComponent {
+    header(header: ValidChild): this;
+    title(title: ValidChild): this;
+    footer(footer: ValidChild): this;
+    inset(inset?: boolean): this;
+    data(data: unknown): this;
+    renderHeader(renderFn: (desc: ListGroupDescription, instance: ListGroupInterface) => ValidChild): this;
+    renderFooter(renderFn: (desc: ListGroupDescription, instance: ListGroupInterface) => ValidChild): this;
+    render(renderFn: (desc: ListGroupDescription, instance: ListGroupInterface) => ValidChild): this;
+}
+
+
+export declare function ListGroup(label?: ValidChild, config?: Record<string, unknown>): ListGroupInterface;
+export declare namespace ListGroup {
+
+
+    function use(template: (description: ListGroupDescription, instance: ListGroupInterface) => ValidChild): void;
+
+
+}

package/src/components/list/types/ListItem.d.ts

@@ -0,0 +1,53 @@
+import { GlobalAttributes, Observable } from '../../../../types/globals';
+import { ValidChild } from '../../../../types/elements';
+import { ObservableArray } from '../../../../types/observable';
+
+export interface ListItemDescription {
+    label:          ValidChild | null;
+    subtitle:       ValidChild | null;
+    icon:           ValidChild | null;
+    trailing:       ValidChild | null;
+    value:          unknown;
+    data:           unknown | null;
+    key:            string | null;
+    disabled:       Observable<boolean> | null;
+    selected:       Observable<boolean> | null;
+    visibility:     Observable<boolean> | null;
+    isSelectedIcon: ValidChild | null;
+    swipeLeading:   ValidChild[];
+    swipeTrailing:  ValidChild[];
+    render:         ((desc: ListItemDescription, instance: ListItem) => ValidChild) | null;
+    props:          GlobalAttributes;
+}
+
+export declare class ListItem {
+    $description: ListItemDescription;
+    $parent: unknown;
+
+    constructor(props?: GlobalAttributes);
+
+    static use(template: (description: ListItemDescription, instance: ListItem) => ValidChild): void;
+    static defaultTemplate: ((description: ListItemDescription, instance: ListItem) => ValidChild) | null;
+
+    label(label: ValidChild): this;
+    subtitle(subtitle: ValidChild): this;
+    icon(icon: ValidChild): this;
+    trailing(trailing: ValidChild): this;
+    value(value: unknown): this;
+    data(data: unknown): this;
+    key(key: string): this;
+    disabled(disabled?: boolean | Observable<boolean>): this;
+    selected(selected?: boolean | Observable<boolean>): this;
+    visibility(mode: boolean | Observable<boolean>): this;
+    isSelectedIcon(icon: ValidChild): this;
+    swipeLeading(actions: ValidChild | ValidChild[]): this;
+    swipeTrailing(actions: ValidChild | ValidChild[]): this;
+    onClick(handler: (item: ListItem, event: MouseEvent) => void): this;
+
+    // HasEventEmitter
+    on(event: string, handler: (...args: unknown[]) => void): this;
+    emit(event: string, ...args: unknown[]): void;
+    hasListeners(event: string): boolean;
+}
+
+export declare function ListItem(props?: GlobalAttributes): ListItem;

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) {