native-document 1.0.166 → 1.0.168

package/src/components/card/Card.js

@@ -1,9 +1,9 @@
 import BaseComponent from '../BaseComponent';
+import HasEventEmitter from '../../core/utils/HasEventEmitter';
 
 /**
  * Versatile content container with optional image, header, footer, actions. Supports clickable, hoverable, loading, and horizontal layouts.
  *
- *
  * @example
  * const card = new Card()
  *     .title(Span('Card title'))
@@ -19,43 +19,80 @@ import BaseComponent from '../BaseComponent';
  * });
  *
  * @constructor
- * @param {GlobalAttributes} [config={}]
+ * @param {GlobalAttributes} [props={}]
  */
-export default function Card(config = {}) {
-    if(!(this instanceof Card)) {
-        return new Card(config);
+export default function Card(props = {}) {
+    if (!(this instanceof Card)) {
+        return new Card(props);
     }
+
     this.$description = {
-        ...config,
+        title:         null,
+        subtitle:      null,
+        image:         null,
+        imagePosition: 'top',
+        content:       null,
+        variant:       null,
+        loading:       null,
+        horizontal:    false,
+        hoverable:     false,
+        actions:       [],
+        renderImage:   null,
+        renderHeader:  null,
+        renderContent: null,
+        renderFooter:  null,
+        renderActions: null,
+        layout:        null,
+        props,
     };
-};
+}
 
 BaseComponent.extends(Card);
+BaseComponent.use(Card, HasEventEmitter);
 
 Card.defaultTemplate = null;
 
 /**
  * Registers the render template for Card.
  * @param {(description: {
- *     [key: string]: unknown,
+ *     title: NdChild|null,
+ *     subtitle: NdChild|null,
+ *     image: string|null,
+ *     imagePosition: 'top'|'bottom'|'left'|'right',
+ *     content: NdChild|null,
+ *     variant: 'elevated'|'outlined'|'flat'|string|null,
+ *     loading: Observable<boolean>|null,
+ *     horizontal: boolean,
+ *     hoverable: boolean,
+ *     actions: { label: NdChild, callback: () => void }[],
+ *     renderImage: ((desc: *, instance: Card) => NdChild)|null,
+ *     renderHeader: ((desc: *, instance: Card) => NdChild)|null,
+ *     renderContent: ((desc: *, instance: Card) => NdChild)|null,
+ *     renderFooter: ((desc: *, instance: Card) => NdChild)|null,
+ *     renderActions: ((desc: *, instance: Card) => NdChild)|null,
+ *     layout: ((slots: { header: NdChild, content: NdChild, footer: NdChild, image: NdChild, actions: NdChild }, instance: Card) => NdChild)|null,
  *     props: GlobalAttributes,
  * }, instance: Card) => NdChild} template
  */
-Card.use = function(template) {};
+Card.use = function(template) {
+    Card.defaultTemplate = template;
+};
 
 /**
  * @param {NdChild} title
  * @returns {this}
  */
 Card.prototype.title = function(title) {
+    this.$description.title = title;
     return this;
 };
 
 /**
- * @param {NdChild} title
+ * @param {NdChild} subtitle
  * @returns {this}
  */
-Card.prototype.subtitle = function(title) {
+Card.prototype.subtitle = function(subtitle) {
+    this.$description.subtitle = subtitle;
     return this;
 };
 
@@ -65,6 +102,8 @@ Card.prototype.subtitle = function(title) {
  * @returns {this}
  */
 Card.prototype.image = function(src, position = 'top') {
+    this.$description.image         = src;
+    this.$description.imagePosition = position;
     return this;
 };
 
@@ -73,6 +112,7 @@ Card.prototype.image = function(src, position = 'top') {
  * @returns {this}
  */
 Card.prototype.content = function(content) {
+    this.$description.content = content;
     return this;
 };
 
@@ -83,51 +123,55 @@ Card.prototype.content = function(content) {
  * @returns {this}
  */
 Card.prototype.variant = function(name) {
+    this.$description.variant = name;
     return this;
 };
 
 /**
  * @returns {this}
  */
-Card.prototype.outlined = function() {
-    return this;
+Card.prototype.elevated = function() {
+    return this.variant('elevated');
 };
 
 /**
  * @returns {this}
  */
-Card.prototype.elevated = function() {
-    return this;
+Card.prototype.outlined = function() {
+    return this.variant('outlined');
 };
 
 /**
  * @returns {this}
  */
 Card.prototype.flat = function() {
-    return this;
+    return this.variant('flat');
 };
 
 // Behavior
+
 /**
  * @param {Function} handler
  * @returns {this}
  */
 Card.prototype.clickable = function(handler) {
-    return this;
+    return this.onClick(handler);
 };
 
 /**
  * @returns {this}
  */
 Card.prototype.hoverable = function() {
+    this.$description.hoverable = true;
     return this;
 };
 
 /**
- * @param {boolean|Observable<boolean>} [isLoading]
+ * @param {boolean|Observable<boolean>} [isLoading=true]
  * @returns {this}
  */
 Card.prototype.loading = function(isLoading = true) {
+    this.$description.loading = BaseComponent.obs(isLoading);
     return this;
 };
 
@@ -137,46 +181,54 @@ Card.prototype.loading = function(isLoading = true) {
  * @returns {this}
  */
 Card.prototype.horizontal = function() {
+    this.$description.horizontal = true;
     return this;
 };
 
-// Events
+// Actions
+
 /**
- * @param {Function} handler
+ * @param {NdChild} label
+ * @param {() => void} callback
  * @returns {this}
  */
-Card.prototype.onClick = function(handler) {
+Card.prototype.action = function(label, callback) {
+    this.$description.actions.push({ label, callback });
     return this;
 };
 
 /**
- * @param {Function} handler
  * @returns {this}
  */
-Card.prototype.onHover = function(handler) {
+Card.prototype.clearActions = function() {
+    this.$description.actions = [];
     return this;
 };
 
+// Events
+
 /**
+ * @param {Function} handler
  * @returns {this}
  */
-Card.prototype.clearActions = function() {
-    this.$description.actions = [];
+Card.prototype.onClick = function(handler) {
+    this.on('click', handler);
     return this;
 };
 
 /**
- * @param {NdChild} label
- * @param {() => void} callback
+ * @param {Function} handler
  * @returns {this}
  */
-Card.prototype.action = function(label, callback) {
-    this.$description.actions.push({ label, callback });
+Card.prototype.onHover = function(handler) {
+    this.on('hover', handler);
     return this;
 };
 
+// Custom renderers
+
 /**
- * @param {(desc: *, instance: *) => NdChild} renderFn
+ * @param {(desc: *, instance: Card) => NdChild} renderFn
  * @returns {this}
  */
 Card.prototype.renderImage = function(renderFn) {
@@ -185,7 +237,7 @@ Card.prototype.renderImage = function(renderFn) {
 };
 
 /**
- * @param {(desc: *, instance: *) => NdChild} renderFn
+ * @param {(desc: *, instance: Card) => NdChild} renderFn
  * @returns {this}
  */
 Card.prototype.renderHeader = function(renderFn) {
@@ -194,7 +246,7 @@ Card.prototype.renderHeader = function(renderFn) {
 };
 
 /**
- * @param {(desc: *, instance: *) => NdChild} renderFn
+ * @param {(desc: *, instance: Card) => NdChild} renderFn
  * @returns {this}
  */
 Card.prototype.renderContent = function(renderFn) {
@@ -203,7 +255,7 @@ Card.prototype.renderContent = function(renderFn) {
 };
 
 /**
- * @param {(desc: *, instance: *) => NdChild} renderFn
+ * @param {(desc: *, instance: Card) => NdChild} renderFn
  * @returns {this}
  */
 Card.prototype.renderFooter = function(renderFn) {
@@ -212,17 +264,19 @@ Card.prototype.renderFooter = function(renderFn) {
 };
 
 /**
- * @param {(desc: *, instance: *) => NdChild} layoutFn
+ * @param {(desc: *, instance: Card) => NdChild} renderFn
  * @returns {this}
  */
-Card.prototype.layout = function(layoutFn) {
-    this.$description.layout = layoutFn;
+Card.prototype.renderActions = function(renderFn) {
+    this.$description.renderActions = renderFn;
     return this;
 };
 
 /**
- * @returns {HTMLElement|DocumentFragment}
+ * @param {(slots: { header: NdChild, content: NdChild, footer: NdChild, image: NdChild, actions: NdChild }, instance: Card) => NdChild} layoutFn
+ * @returns {this}
  */
-Card.prototype.toNdElement = function() {
+Card.prototype.layout = function(layoutFn) {
+    this.$description.layout = layoutFn;
     return this;
-};
+};

package/src/components/card/index.js

@@ -1,5 +1,5 @@
 import Card from './Card';
 
-export default {
+export {
     Card,
 };

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,12 +1,12 @@
-
 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)
@@ -20,27 +20,26 @@ import HasItems from '../$traits/has-items/HasItems';
  * });
  *
  * @constructor
- * @param {GlobalAttributes} [config]
+ * @param {GlobalAttributes} [props]
  */
-export default function List(config = {}) {
-    if(!(this instanceof List)) {
-        return new List(config);
+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;
@@ -48,71 +47,30 @@ 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,
+ *     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;
-};
-
-/**
- * @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;
-};
+BaseComponent.use(List, HasItems, HasEventEmitter, HasListItem);
 
-/**
- * @param {*} [multi]
- * @returns {this}
- */
-List.prototype.multiSelect = function(multi = true) {
-    this.$description.multiSelect = multi;
-    this.$description.selectable = true;
-    return this;
-};
 
 /**
- * @param {Observable<*[]>} observable
+ * @param {ObservableArray<*>|Observable<*[]>} observable
  * @returns {this}
  */
 List.prototype.selectedValuesModel = function(observable) {
@@ -121,41 +79,17 @@ List.prototype.selectedValuesModel = function(observable) {
 };
 
 /**
- * @param {number} [inset]
+ * Inset padding in px applied to all items.
+ * @param {number} [inset=0]
  * @returns {this}
  */
-List.prototype.inset = function(inset = true) {
-    this.$description.inset = inset;
+List.prototype.inset = function(inset = 0) {
+    this.$description.inset.set(inset);
     return this;
 };
 
 /**
- * @returns {this}
- */
-List.prototype.next = function() {
-    // TODO:
-    return this;
-};
-
-/**
- * @returns {this}
- */
-List.prototype.preview = function() {
-    // TODO:
-    return this;
-};
-
-/**
- * @param {*} loopOnKeyboard
- * @returns {this}
- */
-List.prototype.loopOnKeyboard = function(loopOnKeyboard) {
-    this.$description.loopOnKeyboard = loopOnKeyboard;
-    return this;
-};
-
-/**
- * @param {*} [divider]
+ * @param {boolean} [divider=true]
  * @returns {this}
  */
 List.prototype.withDivider = function(divider = true) {
@@ -168,12 +102,12 @@ List.prototype.withDivider = function(divider = true) {
  * @returns {this}
  */
 List.prototype.data = function(data) {
-    this.$description.data = data;
+    this.$description.items = data;
     return this;
 };
 
 /**
- * @param {(item: ListItem, event: MouseEvent) => void} handler
+ * @param {(item: *, event: MouseEvent) => void} handler
  * @returns {this}
  */
 List.prototype.onItemClick = function(handler) {
@@ -182,10 +116,10 @@ List.prototype.onItemClick = function(handler) {
 };
 
 /**
- * @param {(item: ListItem) => void} handler
+ * @param {(item: *) => void} handler
  * @returns {this}
  */
 List.prototype.onItemSelect = function(handler) {
     this.on('itemSelect', handler);
     return this;
-};
+};