native-document 1.0.165 → 1.0.166

package/src/components/list/List.js

@@ -1,9 +1,27 @@
 
-import BaseComponent from "../BaseComponent";
-import HasEventEmitter from "../../core/utils/HasEventEmitter";
-import HasItems from "../$traits/has-items/HasItems";
-import Dropdown from "../dropdown/Dropdown";
-
+import BaseComponent from '../BaseComponent';
+import HasEventEmitter from '../../core/utils/HasEventEmitter';
+import HasItems from '../$traits/has-items/HasItems';
+
+/**
+ * Flexible list container supporting single/multi selection, checkbox or click-to-select modes, dividers, and inset styling.
+ *
+ *
+ * @example
+ * const list = new List()
+ *     .selectable(true)
+ *     .multiSelect(true)
+ *     .withDivider(true)
+ *     .onItemClick((item, e) => console.log(item))
+ *     .onItemSelect((item) => console.log('selected', item));
+ *
+ * List.use((description, instance) => {
+ *     return Ul({ class: 'list' });
+ * });
+ *
+ * @constructor
+ * @param {GlobalAttributes} [config]
+ */
 export default function List(config = {}) {
     if(!(this instanceof List)) {
         return new List(config);
@@ -20,13 +38,29 @@ export default function List(config = {}) {
         selectByCheckbox: false,
         selectByClick: false,
         loopOnKeyboard: true,
-        ...config
+        ...config,
     };
 
 }
 
 List.defaultTemplate = null;
 
+/**
+ * Registers the render template for List.
+ * @param {(description: {
+ *     selectable: boolean,
+ *     multiSelect: boolean,
+ *     selectedValues: Observable<*[]>|null,
+ *     inset: boolean,
+ *     divider: boolean,
+ *     data: *|null,
+ *     render: ((desc: *, instance: List) => NdChild)|null,
+ *     selectByCheckbox: boolean,
+ *     selectByClick: boolean,
+ *     loopOnKeyboard: boolean,
+ *     props: GlobalAttributes,
+ * }, instance: List) => NdChild} template
+ */
 List.use = function(template) {
     List.defaultTemplate = template.list;
 };
@@ -40,68 +74,118 @@ List.use = function(template) {
     List.defaultTemplate = template.list;
 };
 
+/**
+ * @param {*} [selectable]
+ * @returns {this}
+ */
 List.prototype.selectable = function(selectable = true) {
     this.$description.selectable = selectable;
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 List.prototype.selectByClick = function() {
     this.$description.selectByClick = true;
     this.$description.selectByCheckbox = false;
+    return this;
 };
+
+/**
+ * @returns {this}
+ */
 List.prototype.selectByCheckbox = function() {
     this.$description.selectByClick = false;
     this.$description.selectByCheckbox = true;
+    return this;
 };
 
+/**
+ * @param {*} [multi]
+ * @returns {this}
+ */
 List.prototype.multiSelect = function(multi = true) {
     this.$description.multiSelect = multi;
     this.$description.selectable = true;
     return this;
 };
 
+/**
+ * @param {Observable<*[]>} observable
+ * @returns {this}
+ */
 List.prototype.selectedValuesModel = function(observable) {
     this.$description.selectedValues = observable;
     return this;
 };
 
+/**
+ * @param {number} [inset]
+ * @returns {this}
+ */
 List.prototype.inset = function(inset = true) {
     this.$description.inset = inset;
     return this;
 };
 
-Dropdown.prototype.next = function() {
-
+/**
+ * @returns {this}
+ */
+List.prototype.next = function() {
+    // TODO:
+    return this;
 };
 
-Dropdown.prototype.preview = function() {
-
+/**
+ * @returns {this}
+ */
+List.prototype.preview = function() {
+    // TODO:
+    return this;
 };
-Dropdown.prototype.loopOnKeyboard = function(loopOnKeyboard) {
+
+/**
+ * @param {*} loopOnKeyboard
+ * @returns {this}
+ */
+List.prototype.loopOnKeyboard = function(loopOnKeyboard) {
     this.$description.loopOnKeyboard = loopOnKeyboard;
     return this;
 };
 
+/**
+ * @param {*} [divider]
+ * @returns {this}
+ */
 List.prototype.withDivider = function(divider = true) {
     this.$description.divider = divider;
     return this;
 };
 
+/**
+ * @param {*} data
+ * @returns {this}
+ */
 List.prototype.data = function(data) {
     this.$description.data = data;
     return this;
 };
 
+/**
+ * @param {(item: ListItem, event: MouseEvent) => void} handler
+ * @returns {this}
+ */
 List.prototype.onItemClick = function(handler) {
     this.on('itemClick', handler);
     return this;
 };
 
+/**
+ * @param {(item: ListItem) => void} handler
+ * @returns {this}
+ */
 List.prototype.onItemSelect = function(handler) {
     this.on('itemSelect', handler);
     return this;
-};
-
-List.prototype.$build = function() {
-
 };

package/src/components/list/ListGroup.js

@@ -1,6 +1,19 @@
-import BaseComponent from "../BaseComponent";
-import HasItems from "../$traits/has-items/HasItems";
+import BaseComponent from '../BaseComponent';
+import HasItems from '../$traits/has-items/HasItems';
 
+/**
+ * Groups ListItem instances under a header/footer inside a List.
+ *
+ *
+ * @example
+ * const group = new ListGroup(Span('Favourites'))
+ *     .inset(true)
+ *     .renderHeader((desc, instance) => H3(desc.header));
+ *
+ * @constructor
+ * @param {NdChild} [label]
+ * @param {GlobalAttributes} [config={}]
+ */
 export default function ListGroup(label, config = {}) {
     if(!(this instanceof ListGroup)) {
         return new ListGroup(label, config);
@@ -15,7 +28,7 @@ export default function ListGroup(label, config = {}) {
         renderHeader: null,
         renderFooter: null,
         render: null,
-        ...config
+        ...config,
     };
 }
 
@@ -24,45 +37,82 @@ BaseComponent.use(ListGroup, HasItems);
 
 ListGroup.defaultTemplate = null;
 
+/**
+ * Registers the render template for ListGroup.
+ * @param {(description: {
+ *     header: NdChild|null,
+ *     footer: NdChild|null,
+ *     items: *[],
+ *     inset: boolean,
+ *     data: *|null,
+ *     renderHeader: ((desc: *, instance: ListGroup) => NdChild)|null,
+ *     renderFooter: ((desc: *, instance: ListGroup) => NdChild)|null,
+ *     render: ((desc: *, instance: ListGroup) => NdChild)|null,
+ *     props: GlobalAttributes,
+ * }, instance: ListGroup) => NdChild} template
+ */
 ListGroup.use = function(template) {
     ListGroup.defaultTemplate = template;
 };
 
+/**
+ * @param {NdChild} header
+ * @returns {this}
+ */
 ListGroup.prototype.header = function(header) {
     this.$description.header = header;
     return this;
 };
 
+/**
+ * @param {NdChild} title
+ * @returns {this}
+ */
 ListGroup.prototype.title = function(title) {
     return this.header(title);
 };
 
+/**
+ * @param {NdChild} footer
+ * @returns {this}
+ */
 ListGroup.prototype.footer = function(footer) {
     this.$description.footer = footer;
     return this;
 };
 
+/**
+ * @param {number} [inset]
+ * @returns {this}
+ */
 ListGroup.prototype.inset = function(inset = true) {
     this.$description.inset = inset;
     return this;
 };
 
+/**
+ * @param {*} data
+ * @returns {this}
+ */
 ListGroup.prototype.data = function(data) {
     this.$description.data = data;
     return this;
 };
 
+/**
+ * @param {(desc: *, instance: *) => NdChild} renderFn
+ * @returns {this}
+ */
 ListGroup.prototype.renderHeader = function(renderFn) {
     this.$description.renderHeader = renderFn;
     return this;
 };
 
+/**
+ * @param {(desc: *, instance: *) => NdChild} renderFn
+ * @returns {this}
+ */
 ListGroup.prototype.renderFooter = function(renderFn) {
     this.$description.renderFooter = renderFn;
     return this;
-};
-
-
-ListGroup.prototype.$build = function() {
-
 };

package/src/components/list/ListItem.js

@@ -1,6 +1,26 @@
-import BaseComponent from "../BaseComponent";
-import Validator from "../../core/utils/validator";
-
+import BaseComponent from '../BaseComponent';
+import Validator from '../../core/utils/validator';
+import {$ } from '../../core/data/Observable';
+
+/**
+ * A single row inside a List. Supports leading/trailing slots, icon, selection, divider, and disabled state.
+ *
+ *
+ * @example
+ * const item = new ListItem(Span('Item label'))
+ *     .icon(StarIcon())
+ *     .trailing(Span('chevron >'))
+ *     .selectable()
+ *     .divider(true);
+ *
+ * ListItem.use((description, instance) => {
+ *     return Li(description.leading, description.content, description.trailing);
+ * });
+ *
+ * @constructor
+ * @param {NdChild} [content]
+ * @param {GlobalAttributes} [config={}]
+ */
 export default function ListItem(content, config = {}) {
     if(!(this instanceof ListItem)) {
         return new ListItem(content, config);
@@ -17,7 +37,7 @@ export default function ListItem(content, config = {}) {
         divider: false,
         data: null,
         render: null,
-        ...config
+        ...config,
     };
 }
 
@@ -25,45 +45,84 @@ BaseComponent.extends(ListItem);
 
 ListItem.defaultTemplate = null;
 
+/**
+ * Registers the render template for ListItem.
+ * @param {(description: {
+ *     content: NdChild|null,
+ *     icon: NdChild|null,
+ *     trailing: NdChild|null,
+ *     leading: NdChild|null,
+ *     disabled: boolean,
+ *     selectable: boolean,
+ *     selected: boolean|Observable<boolean>,
+ *     divider: boolean,
+ *     data: *|null,
+ *     render: ((desc: *, instance: ListItem) => NdChild)|null,
+ *     props: GlobalAttributes,
+ * }, instance: ListItem) => NdChild} template
+ */
 ListItem.use = function(template) {
     ListItem.defaultTemplate = template;
 };
 
+/**
+ * @param {NdChild} content
+ * @returns {this}
+ */
 ListItem.prototype.content = function(content) {
     this.$description.content = content;
     return this;
 };
 
+/**
+ * @param {NdChild} label
+ * @returns {this}
+ */
 ListItem.prototype.label = function(label) {
     this.$description.content = label;
     return this;
 };
 
+/**
+ * @param {NdChild} icon
+ * @returns {this}
+ */
 ListItem.prototype.icon = function(icon) {
     this.$description.icon = icon;
     return this;
 };
 
+/**
+ * @param {NdChild} leading
+ * @returns {this}
+ */
 ListItem.prototype.leading = function(leading) {
     this.$description.leading = leading;
     return this;
 };
 
+/**
+ * @param {NdChild} trailing
+ * @returns {this}
+ */
 ListItem.prototype.trailing = function(trailing) {
     this.$description.trailing = trailing;
     return this;
 };
 
-ListItem.prototype.leading = function(leading) {
-    this.$description.leading = leading;
-    return this;
-};
 
+/**
+ * @param {boolean|Observable<boolean>} [disabled=true]
+ * @returns {this}
+ */
 ListItem.prototype.disabled = function(disabled = true) {
     this.$description.disabled = disabled;
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 ListItem.prototype.selectable = function() {
     this.$description.selectable = true;
     if(Validator.isObservable(this.$description.selected)) {
@@ -73,6 +132,10 @@ ListItem.prototype.selectable = function() {
     return this;
 };
 
+/**
+ * @param {boolean|Observable<boolean>} [selected]
+ * @returns {this}
+ */
 ListItem.prototype.selected = function(selected = true) {
     if(Validator.isObservable(this.$description.selected)) {
         this.$description.selected.set(selected);
@@ -82,22 +145,20 @@ ListItem.prototype.selected = function(selected = true) {
     return this;
 };
 
+/**
+ * @param {NdChild} [show]
+ * @returns {this}
+ */
 ListItem.prototype.divider = function(show = true) {
     this.$description.divider = show;
     return this;
 };
 
+/**
+ * @param {*} data
+ * @returns {this}
+ */
 ListItem.prototype.data = function(data) {
     this.$description.data = data;
     return this;
 };
-
-ListItem.prototype.render = function(renderFn) {
-    this.$description.render = renderFn;
-    return this;
-};
-
-
-ListItem.prototype.$build = function() {
-
-};

package/src/components/list/index.js

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

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,42 @@
+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 ListItemDescription = {
+        content: ValidChild | null;
+        icon: ValidChild | null;
+        trailing: ValidChild | null;
+        leading: ValidChild | null;
+        disabled: boolean;
+        selectable: boolean;
+        selected: boolean | ObservableItem<boolean>;
+        divider: boolean;
+        data: unknown | null;
+        render: ((desc: ListItemDescription, instance: ListItemInterface) => ValidChild) | null;
+        props: GlobalAttributes;
+    };
+
+export interface ListItemInterface extends BaseComponent {
+    content(content: ValidChild): this;
+    label(label: ValidChild): this;
+    icon(icon: ValidChild): this;
+    leading(leading: ValidChild): this;
+    trailing(trailing: ValidChild): this;
+    disabled(disabled?: boolean): this;
+    selectable(): this;
+    selected(selected?: boolean | ObservableItem<boolean>): this;
+    divider(show?: boolean): this;
+    data(data: unknown): this;
+    render(renderFn: (desc: ListItemDescription, instance: ListItemInterface) => ValidChild): this;
+}
+
+
+export declare function ListItem(content?: ValidChild, config?: Record<string, unknown>): ListItemInterface;
+export declare namespace ListItem {
+
+
+    function use(template: (description: ListItemDescription, instance: ListItemInterface) => ValidChild): void;
+
+
+}