native-document 1.0.165 → 1.0.168

package/src/components/dropdown/DropdownItem.js

@@ -1,6 +1,24 @@
-import BaseComponent from "../BaseComponent";
-
+import BaseComponent from '../BaseComponent';
 
+/**
+ * Individual selectable item inside a Dropdown. Supports value, icon, shortcut, disabled/selected states.
+ *
+ *
+ * @example
+ * const item = new DropdownItem()
+ *     .value('fr')
+ *     .icon(FlagIcon())
+ *     .content(Span('French'))
+ *     .shortcut(Span('Ctrl+F'))
+ *     .disabled(false);
+ *
+ * DropdownItem.use((description, instance) => {
+ *     return Li(description.icon, description.content, description.shortcut);
+ * });
+ *
+ * @constructor
+ * @param {GlobalAttributes} [props]
+ */
 export default function DropdownItem(props = {}) {
     if(!(this instanceof DropdownItem)) {
         return new DropdownItem(props);
@@ -18,59 +36,114 @@ export default function DropdownItem(props = {}) {
         data: null,
         render: null,
         renderContent: null,
-        props
+        props,
     };
 };
 
 BaseComponent.extends(DropdownItem);
 
 DropdownItem.defaultTemplate = null;
+
+/**
+ * Registers the render template for DropdownItem.
+ * @param {(description: {
+ *     icon: NdChild|null,
+ *     content: NdChild|null,
+ *     shortcut: NdChild|null,
+ *     value: *,
+ *     disabled: boolean|Observable<boolean>,
+ *     selected: boolean|Observable<boolean>,
+ *     data: *,
+ *     render: ((desc: *, instance: DropdownItem) => NdChild)|null,
+ *     renderContent: ((item: DropdownItem) => NdChild)|null,
+ *     props: GlobalAttributes,
+ * }, instance: DropdownItem) => NdChild} template
+ */
 DropdownItem.use = function(template) {
     DropdownItem.defaultTemplate = template;
 };
 
+/**
+ * @param {*} value
+ * @returns {this}
+ */
 DropdownItem.prototype.value = function(value) {
     this.$description.value = value;
     return this;
 };
 
+/**
+ * @returns {*}
+ */
 DropdownItem.prototype.getValue = function() {
     return this.$description.value;
 };
 
+/**
+ * @param {boolean|Observable<boolean>} [disabled=true]
+ * @returns {this}
+ */
 DropdownItem.prototype.disabled = function(disabled = true) {
     this.$description.disabled = BaseComponent.obs(disabled);
     return this;
 };
 
+/**
+ * @param {boolean|Observable<boolean>} [selected=true]
+ * @returns {this}
+ */
 DropdownItem.prototype.selected = function(selected = true) {
     this.$description.selected = BaseComponent.obs(selected);
     return this;
 };
 
+/**
+ * @param {NdChild} icon
+ * @returns {this}
+ */
 DropdownItem.prototype.icon = function(icon) {
     this.$description.icon = icon;
     return this;
 };
 
+/**
+ * @param {NdChild} content
+ * @returns {this}
+ */
 DropdownItem.prototype.content = function(content) {
     this.$description.content = content;
     return this;
 };
 
+/**
+ * @param {*} data
+ * @returns {this}
+ */
 DropdownItem.prototype.data = function(data) {
     this.$description.data = data;
     return this;
 };
 
+/**
+ * @returns {*}
+ */
 DropdownItem.prototype.getData = function() {
     return this.$description.data;
 };
 
+/**
+ * @param {NdChild} shortcut
+ * @returns {this}
+ */
 DropdownItem.prototype.shortcut = function(shortcut) {
     this.$description.shortcut = shortcut;
     return this;
 };
+
+/**
+ * @param {Function} callback
+ * @returns {this}
+ */
 DropdownItem.prototype.renderContent = function(callback) {
     this.$description.renderContent = callback;
     return this;

package/src/components/dropdown/DropdownTrigger.js

@@ -1,5 +1,19 @@
-import BaseComponent from "../BaseComponent";
-
+import BaseComponent from '../BaseComponent';
+
+/**
+ * Custom trigger element for a Dropdown that reacts to the open/closed state.
+ *
+ *
+ * @example
+ * const trigger = new DropdownTrigger()
+ *     .content(Span('Select option'))
+ *     .icon(ChevronIcon())
+ *     .stateOpenIcon(ChevronUpIcon())
+ *     .stateClosedIcon(ChevronDownIcon());
+ *
+ * @constructor
+ * @param {GlobalAttributes} [config]
+ */
 export default function DropdownTrigger(config) {
     if(!(this instanceof DropdownTrigger)) {
         return new DropdownTrigger(config);
@@ -10,7 +24,7 @@ export default function DropdownTrigger(config) {
         stateOpenIcon: null,
         render: null,
         isOpen: null,
-        ...config
+        ...config,
     };
 }
 
@@ -18,47 +32,62 @@ BaseComponent.extends(DropdownTrigger);
 
 DropdownTrigger.defaultTemplate = null;
 
+/**
+ * Registers the render template for DropdownTrigger.
+ * @param {(description: {
+ *     icon: NdChild|null,
+ *     content: NdChild|null,
+ *     stateOpenIcon: NdChild|null,
+ *     render: ((desc: *, instance: DropdownTrigger) => NdChild)|null,
+ *     isOpen: Observable<boolean>|null,
+ *     props: GlobalAttributes,
+ * }, instance: DropdownTrigger) => NdChild} template
+ */
 DropdownTrigger.use = function(template) {
-
+    DropdownTrigger.template = template;
 };
 
+/**
+ * @param {Observable<boolean>} isOpenObservable
+ * @returns {this}
+ */
 DropdownTrigger.prototype.setIsOpen = function(isOpenObservable) {
     this.$description.isOpen = isOpenObservable;
     return this;
 };
 
-
+/**
+ * @param {NdChild} content
+ * @returns {this}
+ */
 DropdownTrigger.prototype.content = function(content) {
     this.$description.content = content;
     return this;
 };
 
+/**
+ * @param {NdChild} icon
+ * @returns {this}
+ */
 DropdownTrigger.prototype.icon = function(icon) {
     this.$description.icon = icon;
     return this;
 };
 
+/**
+ * @param {NdChild} openIcon
+ * @returns {this}
+ */
 DropdownTrigger.prototype.stateOpenIcon = function(openIcon) {
     this.$description.stateOpenIcon = openIcon;
     return this;
 };
 
+/**
+ * @param {NdChild} closedIcon
+ * @returns {this}
+ */
 DropdownTrigger.prototype.stateClosedIcon = function(closedIcon) {
     this.$description.stateClosedIcon = closedIcon;
     return this;
 };
-
-
-DropdownTrigger.prototype.render = function(renderFn) {
-    this.$description.render = renderFn;
-    return this;
-}
-
-
-DropdownTrigger.prototype.$build = function() {
-
-};
-
-DropdownTrigger.prototype.toNdElement = function() {
-
-};

package/src/components/dropdown/helpers.js

@@ -1,4 +1,4 @@
-import DropdownItem from "./DropdownItem";
+import DropdownItem from './DropdownItem';
 
 const resolveField = (raw, mapperField, fallbackKeys) => {
     if(!mapperField) {

package/src/components/dropdown/index.js

@@ -1,13 +1,13 @@
-import DropdownDivider from "./DropdownDivider";
-import Dropdown from "./Dropdown";
-import DropdownGroup from "./DropdownGroup";
-import DropdownItem from "./DropdownItem";
-import DropdownTrigger from "./DropdownTrigger";
+import DropdownDivider from './DropdownDivider';
+import Dropdown from './Dropdown';
+import DropdownGroup from './DropdownGroup';
+import DropdownItem from './DropdownItem';
+import DropdownTrigger from './DropdownTrigger';
 
 export {
     Dropdown,
     DropdownDivider,
     DropdownGroup,
     DropdownItem,
-    DropdownTrigger
+    DropdownTrigger,
 };

package/src/components/dropdown/types/Dropdown.d.ts

@@ -0,0 +1,88 @@
+import type { ValidChild } from '../../../../types/elements';
+import type { ObservableItem } from '../../../../types/observable';
+import type { BaseComponent } from '../../BaseComponent';
+import type { DropdownItemInterface } from './DropdownItem';
+import type { DropdownGroupInterface } from './DropdownGroup';
+import type { GlobalAttributes } from '../../../../types/globals';
+
+export type DropdownDescription = {
+        trigger: HTMLElement | null;
+        items: ObservableItem<DropdownItemInterface[]>;
+        interaction: 'click' | 'hover' | 'focus';
+        disabled: ObservableItem<boolean>;
+        isOpen: ObservableItem<boolean>;
+        maxHeight: string | number | null;
+        searchable: boolean;
+        searchValue: ObservableItem<string> | null;
+        searchPlaceholder: string;
+        loopOnKeyboard: boolean;
+        renderItem: ((item: DropdownItemInterface, instance: DropdownInterface) => ValidChild) | null;
+        renderHeader: ((desc: DropdownDescription, instance: DropdownInterface) => ValidChild) | null;
+        renderFooter: ((desc: DropdownDescription, instance: DropdownInterface) => ValidChild) | null;
+        render: ((desc: DropdownDescription, instance: DropdownInterface) => ValidChild) | null;
+        filter: ((item: DropdownItemInterface, query: string) => boolean) | null;
+        mapper: ((item: unknown) => DropdownItemInterface) | null;
+        matchTriggerWidth: boolean | null;
+        updatePositionOn: ObservableItem<unknown> | null;
+        includeTriggerIntoGhost: boolean;
+        props: GlobalAttributes;
+    };
+
+export interface DropdownInterface extends BaseComponent {
+    open(): this;
+    close(): this;
+    toggle(): this;
+    bind(source: ObservableItem<unknown[]> | unknown[], mapper?: ((item: unknown) => DropdownItemInterface) | null): this;
+    source(source: ObservableItem<unknown[]> | unknown[], mapper?: ((item: unknown) => DropdownItemInterface) | null): this;
+    from(items: unknown[], mapper?: ((item: unknown) => DropdownItemInterface) | null): this;
+    disabled(disabled?: boolean | ObservableItem<boolean>): this;
+    enable(): this;
+    disable(): this;
+    value(value: unknown): this;
+    placeholder(placeholder: ValidChild): this;
+    searchable(searchable?: boolean, placeholder?: string | null): this;
+    searchPlaceholder(placeholder: string): this;
+    closeOnClickOutside(v: boolean): this;
+    closeOnEscape(v: boolean): this;
+    closeOnSelect(v: boolean): this;
+    maxHeight(maxHeight: string | number): this;
+    trigger(trigger: HTMLElement, includeTriggerIntoGhost?: boolean): this;
+    add(item: DropdownItemInterface | ValidChild | unknown, props?: Record<string, unknown>): this;
+    item(item: DropdownItemInterface | ValidChild | unknown, props?: Record<string, unknown>): this;
+    from(items: unknown[], mapper?: ((item: unknown) => DropdownItemInterface) | null): this;
+    group(groupBuilder: (group: DropdownGroupInterface) => void): this;
+    divider(): this;
+    select(value: unknown): this;
+    next(): this;
+    preview(): this;
+    loopOnKeyboard(v: boolean): this;
+    onChange(handler: (value: unknown, item: DropdownItemInterface) => void): this;
+    onOpen(handler: () => void): this;
+    onClose(handler: () => void): this;
+    renderSearch(renderFn: (desc: DropdownDescription, instance: DropdownInterface) => ValidChild): this;
+    interaction(interaction: 'click' | 'hover' | 'focus'): this;
+    filter(filter: (item: DropdownItemInterface, query: string) => boolean, dependencies?: ObservableItem<unknown>[]): this;
+    onClicked(): this;
+    onHovered(): this;
+    onFocused(): this;
+    renderHeader(renderFn: (desc: DropdownDescription, instance: DropdownInterface) => ValidChild): this;
+    renderFooter(renderFn: (desc: DropdownDescription, instance: DropdownInterface) => ValidChild): this;
+    renderContent(renderFn: (desc: DropdownDescription, instance: DropdownInterface) => ValidChild): this;
+    matchTriggerWidth(): this;
+    matchTargetWidth(target: HTMLElement): this;
+    renderItem(callback: (item: DropdownItemInterface, instance: DropdownInterface) => ValidChild): this;
+    updatePositionOn(obs: ObservableItem<unknown> | unknown): this;
+    render(template: (description: DropdownDescription, instance: DropdownInterface) => ValidChild): this;
+}
+
+
+export declare function Dropdown(props?: Record<string, unknown>): DropdownInterface;
+export declare namespace Dropdown {
+
+
+    function use(template: (description: DropdownDescription, instance: DropdownInterface) => ValidChild): void;
+    function preset(name: string, callback: (instance: DropdownInterface) => DropdownInterface): void;
+    function presets(presets: Record<string, (instance: DropdownInterface) => DropdownInterface>): void;
+
+
+}

package/src/components/dropdown/types/DropdownDivider.d.ts

@@ -0,0 +1,20 @@
+import type { ValidChild } from '../../../../types/elements';
+import type { BaseComponent } from '../../BaseComponent';
+
+export type DropdownDividerDescription = {
+    props: Record<string, unknown>;
+};
+
+export interface DropdownDividerInterface extends BaseComponent {
+    render(renderFn: (desc: unknown, instance: DropdownDividerInterface) => ValidChild): this;
+}
+
+
+export declare function DropdownDivider(props?: Record<string, unknown>): DropdownDividerInterface;
+export declare namespace DropdownDivider {
+
+
+    function use(template: (description: DropdownDividerDescription, instance: DropdownDividerInterface) => ValidChild): void;
+
+
+}

package/src/components/dropdown/types/DropdownGroup.d.ts

@@ -0,0 +1,25 @@
+import type { ValidChild } from '../../../../types/elements';
+import type { BaseComponent } from '../../BaseComponent';
+import type { DropdownItemInterface } from './DropdownItem';
+
+export type DropdownGroupDescription = {
+    props: Record<string, unknown>;
+};
+
+export interface DropdownGroupInterface extends BaseComponent {
+    add(item: DropdownItemInterface | ValidChild | unknown, props?: Record<string, unknown>): this;
+    item(item: DropdownItemInterface | ValidChild | unknown, props?: Record<string, unknown>): this;
+    group(groupBuilder: (group: DropdownGroupInterface) => void): this;
+    divider(): this;
+    render(template: (description: DropdownGroupDescription, instance: DropdownGroupInterface) => ValidChild): this;
+}
+
+
+export declare function DropdownGroup(props?: Record<string, unknown>): DropdownGroupInterface;
+export declare namespace DropdownGroup {
+
+
+    function use(template: (description: DropdownGroupDescription, instance: DropdownGroupInterface) => ValidChild): void;
+
+
+}

package/src/components/dropdown/types/DropdownItem.d.ts

@@ -0,0 +1,41 @@
+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 DropdownItemDescription = {
+        icon: ValidChild | null;
+        content: ValidChild | null;
+        shortcut: ValidChild | null;
+        value: unknown;
+        disabled: boolean | ObservableItem<boolean>;
+        selected: boolean | ObservableItem<boolean>;
+        data: unknown;
+        render: ((desc: DropdownItemDescription, instance: DropdownItemInterface) => ValidChild) | null;
+        renderContent: ((item: DropdownItemInterface) => ValidChild) | null;
+        props: GlobalAttributes;
+    };
+
+export interface DropdownItemInterface extends BaseComponent {
+    value(value: unknown): this;
+    getValue(): unknown;
+    disabled(disabled?: boolean | ObservableItem<boolean>): this;
+    selected(selected?: boolean | ObservableItem<boolean>): this;
+    icon(icon: ValidChild): this;
+    content(content: ValidChild): this;
+    data(data: unknown): this;
+    getData(): unknown;
+    shortcut(shortcut: ValidChild): this;
+    render(template: (description: DropdownItemDescription, instance: DropdownItemInterface) => ValidChild): this;
+    renderContent(callback: (item: DropdownItemInterface) => ValidChild): this;
+}
+
+
+export declare function DropdownItem(props?: Record<string, unknown>): DropdownItemInterface;
+export declare namespace DropdownItem {
+
+
+    function use(template: (description: DropdownItemDescription, instance: DropdownItemInterface) => ValidChild): void;
+
+
+}

package/src/components/dropdown/types/DropdownTrigger.d.ts

@@ -0,0 +1,32 @@
+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 DropdownTriggerDescription = {
+        icon: ValidChild | null;
+        content: ValidChild | null;
+        stateOpenIcon: ValidChild | null;
+        render: ((desc: DropdownTriggerDescription, instance: DropdownTriggerInterface) => ValidChild) | null;
+        isOpen: ObservableItem<boolean> | null;
+        props: GlobalAttributes;
+    };
+
+export interface DropdownTriggerInterface extends BaseComponent {
+    setIsOpen(isOpenObservable: ObservableItem<boolean>): this;
+    content(content: ValidChild): this;
+    icon(icon: ValidChild): this;
+    stateOpenIcon(openIcon: ValidChild): this;
+    stateClosedIcon(closedIcon: ValidChild): this;
+    render(renderFn: (desc: DropdownTriggerDescription, instance: DropdownTriggerInterface) => ValidChild): this;
+}
+
+
+export declare function DropdownTrigger(config?: Record<string, unknown>): DropdownTriggerInterface;
+export declare namespace DropdownTrigger {
+
+
+    function use(template: (description: DropdownTriggerDescription, instance: DropdownTriggerInterface) => ValidChild): void;
+
+
+}