native-document 1.0.165 → 1.0.168

package/src/components/list/HasListItem.js

@@ -0,0 +1,171 @@
+import ListDivider from './ListDivider';
+import List from './List';
+import BaseComponent from '../BaseComponent';
+
+const EMPTY_OPTIONS = {};
+
+/**
+ * Trait that adds item/group/divider management to List and ListGroup.
+ * Mirrors the HasMenuItem pattern.
+ *
+ * @constructor
+ */
+export default function HasListItem() {}
+
+HasListItem.components = {
+    ListItem:  null,
+    ListGroup: null,
+};
+
+
+/**
+ * @param {ObservableArray<*>|*[]} list
+ * @returns {this}
+ */
+HasListItem.prototype.selectInto = function(list) {
+    this.$description.selectedValues = list;
+    return this;
+};
+
+/**
+ * @param {boolean|Observable<boolean>} [selectable=true]
+ * @returns {this}
+ */
+HasListItem.prototype.selectable = function(selectable = true) {
+    this.$description.selectable = BaseComponent.obs(selectable);
+    return this;
+};
+
+/**
+ * Select items on click. Mutually exclusive with selectByCheckbox.
+ * @returns {this}
+ */
+HasListItem.prototype.selectByClick = function() {
+    this.$description.selectByClick.set(true);
+    this.$description.selectByCheckbox.set(false);
+    return this;
+};
+
+/**
+ * Select items via a checkbox. Mutually exclusive with selectByClick.
+ * @returns {this}
+ */
+HasListItem.prototype.selectByCheckbox = function() {
+    this.$description.selectByClick.set(false);
+    this.$description.selectByCheckbox.set(true);
+    return this;
+};
+
+/**
+ * @param {boolean|Observable<boolean>} [multi=true]
+ * @returns {this}
+ */
+HasListItem.prototype.multiSelect = function(multi = true) {
+    this.$description.multiSelect = BaseComponent.obs(multi);
+    this.$description.selectable.set(true);
+    return this;
+};
+
+/**
+ * @param {boolean} loopOnKeyboard
+ * @returns {this}
+ */
+HasListItem.prototype.loopOnKeyboard = function(loopOnKeyboard) {
+    this.$description.loopOnKeyboard = loopOnKeyboard;
+    return this;
+};
+
+/**
+ * @param {ListItem|ListGroup|ListDivider} item
+ * @returns {this}
+ */
+HasListItem.prototype.add = function(item) {
+    if (item === this) {
+        return this;
+    }
+    item.$parent = this;
+    this.$description.items.push(item);
+    return this;
+};
+
+/**
+ * @param {NdChild} label
+ * @param {NdChild|((item: ListItem) => void)} [iconOrBuilder]
+ * @param {((item: ListItem) => void)} [builder]
+ * @returns {this}
+ */
+HasListItem.prototype.item = function(label, iconOrBuilder, builder) {
+    const ListItem = HasListItem.components.ListItem;
+    const item = new ListItem();
+    item.$parent = this;
+
+    item.label(label);
+
+    if (typeof iconOrBuilder === 'function') {
+        iconOrBuilder(item);
+    } else if (iconOrBuilder) {
+        item.icon(iconOrBuilder);
+        if (typeof builder === 'function') {
+            builder(item);
+        }
+    }
+
+    this.$description.items.push(item);
+    return this;
+};
+
+/**
+ * @param {NdChild} label
+ * @param {NdChild|((group: ListGroup) => void)} [iconOrBuilder]
+ * @param {((group: ListGroup) => void)} [builder]
+ * @returns {this}
+ */
+HasListItem.prototype.group = function(label, iconOrBuilder, builder) {
+    const ListGroup = HasListItem.components.ListGroup;
+    const group = new ListGroup(label);
+    group.$parent = this;
+
+    if (typeof iconOrBuilder === 'function') {
+        iconOrBuilder(group);
+    } else if (iconOrBuilder) {
+        group.icon(iconOrBuilder);
+        if (typeof builder === 'function') {
+            builder(group);
+        }
+    }
+
+    this.$description.items.push(group);
+    return this;
+};
+
+/**
+ * @returns {this}
+ */
+HasListItem.prototype.divider = function() {
+    const divider = new ListDivider();
+    divider.$parent = this;
+    this.$description.items.push(divider);
+    return this;
+};
+
+
+/**
+ * Populate items from a data source using a builder function.
+ * The builder receives each data item and must return a ListItem or ListGroup.
+ *
+ * @param {ObservableArray<*>|*[]} source
+ * @param {(item: *) => ListItem|ListGroup} builder
+ * @returns {this}
+ */
+HasListItem.prototype.from = function(source, builder) {
+    this.$description.items = source;
+    this.$description.itemBuilder = (...args) => {
+        if(args[0].__$ListInstance) {
+            return args[0];
+        }
+        const item = builder(...args);
+        item.$parent = this;
+        return item;
+    };
+    return this;
+};

package/src/components/list/List.js

@@ -1,107 +1,125 @@
-
-import BaseComponent from "../BaseComponent";
-import HasEventEmitter from "../../core/utils/HasEventEmitter";
-import HasItems from "../$traits/has-items/HasItems";
-import Dropdown from "../dropdown/Dropdown";
-
-export default function List(config = {}) {
-    if(!(this instanceof List)) {
-        return new List(config);
+import BaseComponent from '../BaseComponent';
+import HasEventEmitter from '../../core/utils/HasEventEmitter';
+import HasItems from '../$traits/has-items/HasItems';
+import { $ } from '../../core/data/Observable';
+import HasListItem from './HasListItem';
+
+/**
+ * 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} [props]
+ */
+export default function List(props = {}) {
+    if (!(this instanceof List)) {
+        return new List(props);
     }
 
     this.$description = {
-        selectable: false,
-        multiSelect: false,
-        selectedValues: null,
-        inset: false,
-        divider: false,
-        data: null,
-        render: null,
-        selectByCheckbox: false,
-        selectByClick: false,
-        loopOnKeyboard: true,
-        ...config
+        selectable:       $(false),
+        multiSelect:      $(false),
+        selectedValues:   $.array(),
+        inset:            $(0),
+        divider:          false,
+        items:            $.array(),
+        render:           null,
+        selectByCheckbox: $(false),
+        selectByClick:    $(false),
+        loopOnKeyboard:   $(false),
+        props,
     };
-
 }
 
 List.defaultTemplate = null;
 
+/**
+ * Registers the render template for List.
+ * @param {(description: {
+ *     selectable:       ObservableItem<boolean>,
+ *     multiSelect:      ObservableItem<boolean>,
+ *     selectedValues:   ObservableArray<*>,
+ *     inset:            ObservableItem<number>,
+ *     divider:          boolean,
+ *     data:             *|null,
+ *     render:           ((desc: *, instance: List) => NdChild)|null,
+ *     selectByCheckbox: ObservableItem<boolean>,
+ *     selectByClick:    ObservableItem<boolean>,
+ *     loopOnKeyboard:   ObservableItem<boolean>,
+ *     items:            ObservableArray<*>,
+ *     props:            GlobalAttributes,
+ * }, instance: List) => NdChild} template
+ */
 List.use = function(template) {
-    List.defaultTemplate = template.list;
+    List.defaultTemplate = template;
 };
 
 BaseComponent.extends(List);
-BaseComponent.use(List, HasItems, HasEventEmitter);
-
-List.defaultTemplate = null;
-
-List.use = function(template) {
-    List.defaultTemplate = template.list;
-};
-
-List.prototype.selectable = function(selectable = true) {
-    this.$description.selectable = selectable;
-    return this;
-};
-
-List.prototype.selectByClick = function() {
-    this.$description.selectByClick = true;
-    this.$description.selectByCheckbox = false;
-};
-List.prototype.selectByCheckbox = function() {
-    this.$description.selectByClick = false;
-    this.$description.selectByCheckbox = true;
-};
+BaseComponent.use(List, HasItems, HasEventEmitter, HasListItem);
 
-List.prototype.multiSelect = function(multi = true) {
-    this.$description.multiSelect = multi;
-    this.$description.selectable = true;
-    return this;
-};
 
+/**
+ * @param {ObservableArray<*>|Observable<*[]>} observable
+ * @returns {this}
+ */
 List.prototype.selectedValuesModel = function(observable) {
     this.$description.selectedValues = observable;
     return this;
 };
 
-List.prototype.inset = function(inset = true) {
-    this.$description.inset = inset;
-    return this;
-};
-
-Dropdown.prototype.next = function() {
-
-};
-
-Dropdown.prototype.preview = function() {
-
-};
-Dropdown.prototype.loopOnKeyboard = function(loopOnKeyboard) {
-    this.$description.loopOnKeyboard = loopOnKeyboard;
+/**
+ * Inset padding in px applied to all items.
+ * @param {number} [inset=0]
+ * @returns {this}
+ */
+List.prototype.inset = function(inset = 0) {
+    this.$description.inset.set(inset);
     return this;
 };
 
+/**
+ * @param {boolean} [divider=true]
+ * @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;
+    this.$description.items = data;
     return this;
 };
 
+/**
+ * @param {(item: *, event: MouseEvent) => void} handler
+ * @returns {this}
+ */
 List.prototype.onItemClick = function(handler) {
     this.on('itemClick', handler);
     return this;
 };
 
+/**
+ * @param {(item: *) => void} handler
+ * @returns {this}
+ */
 List.prototype.onItemSelect = function(handler) {
     this.on('itemSelect', handler);
     return this;
 };
-
-List.prototype.$build = function() {
-
-};

package/src/components/list/ListDivider.js

@@ -0,0 +1,39 @@
+import BaseComponent from '../BaseComponent';
+
+/**
+ * Visual separator between items in a List.
+ *
+ * @example
+ * List()
+ *     .item('Dashboard')
+ *     .divider()
+ *     .item('Settings')
+ *
+ * ListDivider.use((description, instance) => {
+ *     return Li({ class: 'list-divider', role: 'separator' });
+ * });
+ *
+ * @constructor
+ * @param {GlobalAttributes} [props={}]
+ */
+export default function ListDivider(props = {}) {
+    if (!(this instanceof ListDivider)) {
+        return new ListDivider(props);
+    }
+
+    BaseComponent.call(this, props);
+
+    this.$description = { props };
+}
+
+BaseComponent.extends(ListDivider);
+
+ListDivider.defaultTemplate = null;
+
+/**
+ * Registers the render template for ListDivider.
+ * @param {(description: { props: GlobalAttributes }, instance: ListDivider) => NdChild} template
+ */
+ListDivider.use = function(template) {
+    ListDivider.defaultTemplate = template;
+};

package/src/components/list/ListGroup.js

@@ -1,68 +1,135 @@
-import BaseComponent from "../BaseComponent";
-import HasItems from "../$traits/has-items/HasItems";
+import BaseComponent from '../BaseComponent';
+import HasEventEmitter from '../../core/utils/HasEventEmitter';
+import HasItems from '../$traits/has-items/HasItems';
+import HasListItem from './HasListItem';
+import { $ } from '../../core/data/Observable';
 
-export default function ListGroup(label, config = {}) {
-    if(!(this instanceof ListGroup)) {
-        return new ListGroup(label, config);
+/**
+ * A collapsible group of ListItems inside a List. Can hold items, dividers, and nested groups.
+ *
+ * @example
+ * ListGroup('Workspace')
+ *     .icon(FolderIcon())
+ *     .collapsable()
+ *     .item('Dashboard', DashboardIcon())
+ *     .item('Analytics', ChartIcon());
+ *
+ * // From data
+ * ListGroup('Reports')
+ *     .from(reports, (report) =>
+ *         ListItem().label(report.name).value(report.id)
+ *     );
+ *
+ * ListGroup.use((description, instance) => {
+ *     return Div({ class: 'list-group' });
+ * });
+ *
+ * @constructor
+ * @param {NdChild} label
+ * @param {GlobalAttributes} [props={}]
+ */
+export default function ListGroup(label, props = {}) {
+    if (!(this instanceof ListGroup)) {
+        return new ListGroup(label, props);
     }
 
+    BaseComponent.call(this, props);
+
     this.$description = {
-        header: label || null,
-        footer: null,
-        items: [],
-        inset: false,
-        data: null,
-        renderHeader: null,
-        renderFooter: null,
-        render: null,
-        ...config
+        selectable:       $(false),
+        multiSelect:      $(false),
+        selectedValues:   $.array(),
+        label:       label,
+        icon:        null,
+        items:       $.array(),
+        render:      null,
+        collapsable: false,
+        collapsed:   null,
+        visibility:  $(true),
+        selectByCheckbox: $(false),
+        selectByClick:    $(false),
+        loopOnKeyboard:   $(false),
+        props,
     };
 }
 
 BaseComponent.extends(ListGroup);
-BaseComponent.use(ListGroup, HasItems);
+BaseComponent.use(ListGroup, HasItems, HasEventEmitter, HasListItem);
+
+HasListItem.components.ListGroup = ListGroup;
 
 ListGroup.defaultTemplate = null;
+ListGroup.prototype.__$ListInstance = true;
 
+/**
+ * Registers the render template for ListGroup.
+ * @param {(description: {
+ *     label:       NdChild,
+ *     icon:        NdChild|null,
+ *     items:       ObservableArray<ListItem|ListGroup|ListDivider>,
+ *     itemBuilder: (item: *) => ListItem|ListGroup|ListDivider,
+ *     data:        *|null,
+ *     render:      ((desc: *, instance: ListGroup) => NdChild)|null,
+ *     collapsable: boolean,
+ *     collapsed:   ObservableItem<boolean>|null,
+ *     visibility:  ObservableItem<boolean>,
+ *     props:       GlobalAttributes,
+ * }, instance: ListGroup) => NdChild} template
+ */
 ListGroup.use = function(template) {
     ListGroup.defaultTemplate = template;
 };
 
-ListGroup.prototype.header = function(header) {
-    this.$description.header = header;
+/**
+ * @param {NdChild} icon
+ * @returns {this}
+ */
+ListGroup.prototype.icon = function(icon) {
+    this.$description.icon = icon;
     return this;
 };
 
-ListGroup.prototype.title = function(title) {
-    return this.header(title);
+/**
+ * @param {boolean} [mode=true]
+ * @param {NdChild} [openedIcon]
+ * @param {NdChild} [closedIcon]
+ * @returns {this}
+ */
+ListGroup.prototype.collapsable = function(mode = true, openedIcon, closedIcon) {
+    this.$description.collapsable = mode;
+    this.$description.collapsed   = this.$description.collapsed || $(false);
+    this.$description.collapsableOpenedIcon = openedIcon || null;
+    this.$description.collapsableClosedIcon = closedIcon || null;
+    return this;
 };
 
-ListGroup.prototype.footer = function(footer) {
-    this.$description.footer = footer;
+/**
+ * @param {boolean} [mode=true]
+ * @returns {this}
+ */
+ListGroup.prototype.collapsed = function(mode = true) {
+    if (!this.$description.collapsed) {
+        this.$description.collapsed = $(mode);
+    } else {
+        this.$description.collapsed.set(mode);
+    }
     return this;
 };
 
-ListGroup.prototype.inset = function(inset = true) {
-    this.$description.inset = inset;
+/**
+ * @param {boolean|Observable<boolean>} mode
+ * @returns {this}
+ */
+ListGroup.prototype.visibility = function(mode) {
+    this.$description.visibility = BaseComponent.obs(mode);
     return this;
 };
 
+/**
+ * @param {*} data
+ * @returns {this}
+ */
 ListGroup.prototype.data = function(data) {
     this.$description.data = data;
     return this;
 };
-
-ListGroup.prototype.renderHeader = function(renderFn) {
-    this.$description.renderHeader = renderFn;
-    return this;
-};
-
-ListGroup.prototype.renderFooter = function(renderFn) {
-    this.$description.renderFooter = renderFn;
-    return this;
-};
-
-
-ListGroup.prototype.$build = function() {
-
-};