native-document 1.0.165 → 1.0.168

package/src/components/card/Card.js

@@ -1,110 +1,282 @@
-import BaseComponent from "../BaseComponent";
+import BaseComponent from '../BaseComponent';
+import HasEventEmitter from '../../core/utils/HasEventEmitter';
 
-export default function Card(config = {}) {
-    if(!(this instanceof Card)) {
-        return new Card(config);
+/**
+ * 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'))
+ *     .subtitle(Span('Subtitle'))
+ *     .image('cover.jpg', 'top')
+ *     .content(P('Main content goes here.'))
+ *     .action('View more', () => navigate('/detail'))
+ *     .elevated()
+ *     .clickable((e) => console.log('card clicked'));
+ *
+ * Card.use((description, instance) => {
+ *     return Div({ class: 'card' }, description.title, description.content);
+ * });
+ *
+ * @constructor
+ * @param {GlobalAttributes} [props={}]
+ */
+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;
 
-Card.use = function(template) {};
+/**
+ * Registers the render template for Card.
+ * @param {(description: {
+ *     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.defaultTemplate = template;
+};
 
+/**
+ * @param {NdChild} title
+ * @returns {this}
+ */
 Card.prototype.title = function(title) {
+    this.$description.title = title;
     return this;
 };
-Card.prototype.subtitle = function(title) {
+
+/**
+ * @param {NdChild} subtitle
+ * @returns {this}
+ */
+Card.prototype.subtitle = function(subtitle) {
+    this.$description.subtitle = subtitle;
     return this;
 };
+
+/**
+ * @param {string} src
+ * @param {'top'|'bottom'|'left'|'right'} [position='top']
+ * @returns {this}
+ */
 Card.prototype.image = function(src, position = 'top') {
+    this.$description.image         = src;
+    this.$description.imagePosition = position;
     return this;
 };
+
+/**
+ * @param {NdChild} content
+ * @returns {this}
+ */
 Card.prototype.content = function(content) {
+    this.$description.content = content;
     return this;
 };
 
 // Appearance
+
+/**
+ * @param {string} name
+ * @returns {this}
+ */
 Card.prototype.variant = function(name) {
+    this.$description.variant = name;
     return this;
 };
-Card.prototype.outlined = function() {
-    return this;
-};
+
+/**
+ * @returns {this}
+ */
 Card.prototype.elevated = function() {
-    return this;
+    return this.variant('elevated');
+};
+
+/**
+ * @returns {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=true]
+ * @returns {this}
+ */
 Card.prototype.loading = function(isLoading = true) {
+    this.$description.loading = BaseComponent.obs(isLoading);
     return this;
 };
 
 // Layout
+
+/**
+ * @returns {this}
+ */
 Card.prototype.horizontal = function() {
+    this.$description.horizontal = true;
     return this;
 };
 
-// Events
-Card.prototype.onClick = function(handler) {
-    return this;
-};
-Card.prototype.onHover = function(handler) {
+// Actions
+
+/**
+ * @param {NdChild} label
+ * @param {() => void} callback
+ * @returns {this}
+ */
+Card.prototype.action = function(label, callback) {
+    this.$description.actions.push({ label, callback });
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Card.prototype.clearActions = function() {
     this.$description.actions = [];
     return this;
 };
 
-Card.prototype.action = function(label, callback) {
-    this.$description.actions.push({ label, callback });
+// Events
+
+/**
+ * @param {Function} handler
+ * @returns {this}
+ */
+Card.prototype.onClick = function(handler) {
+    this.on('click', handler);
+    return this;
+};
+
+/**
+ * @param {Function} handler
+ * @returns {this}
+ */
+Card.prototype.onHover = function(handler) {
+    this.on('hover', handler);
     return this;
 };
 
+// Custom renderers
+
+/**
+ * @param {(desc: *, instance: Card) => NdChild} renderFn
+ * @returns {this}
+ */
 Card.prototype.renderImage = function(renderFn) {
     this.$description.renderImage = renderFn;
     return this;
 };
+
+/**
+ * @param {(desc: *, instance: Card) => NdChild} renderFn
+ * @returns {this}
+ */
 Card.prototype.renderHeader = function(renderFn) {
     this.$description.renderHeader = renderFn;
     return this;
 };
+
+/**
+ * @param {(desc: *, instance: Card) => NdChild} renderFn
+ * @returns {this}
+ */
 Card.prototype.renderContent = function(renderFn) {
     this.$description.renderContent = renderFn;
     return this;
 };
+
+/**
+ * @param {(desc: *, instance: Card) => NdChild} renderFn
+ * @returns {this}
+ */
 Card.prototype.renderFooter = function(renderFn) {
     this.$description.renderFooter = renderFn;
     return this;
 };
-Card.prototype.layout = function(layoutFn) {
-    this.$description.layout = layoutFn;
-    return this;
-};
 
-Card.prototype.render = function(renderFn) {
-    this.$description.render = renderFn;
+/**
+ * @param {(desc: *, instance: Card) => NdChild} renderFn
+ * @returns {this}
+ */
+Card.prototype.renderActions = function(renderFn) {
+    this.$description.renderActions = renderFn;
     return this;
 };
 
-Card.prototype.$build = function() {
-
-};
-Card.prototype.toNdElement = function() {
+/**
+ * @param {(slots: { header: NdChild, content: NdChild, footer: NdChild, image: NdChild, actions: NdChild }, instance: Card) => NdChild} layoutFn
+ * @returns {this}
+ */
+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'
+import Card from './Card';
 
-export default {
-    Card
-}
+export {
+    Card,
+};

package/src/components/card/types/Card.d.ts

@@ -0,0 +1,42 @@
+import type { ValidChild } from '../../../../types/elements';
+import type { ObservableItem } from '../../../../types/observable';
+import type { BaseComponent } from '../../BaseComponent';
+
+export type CardDescription = {
+        [key: string]: unknown;
+    };
+
+export interface CardInterface extends BaseComponent {
+    title(title: ValidChild): this;
+    subtitle(subtitle: ValidChild): this;
+    image(src: string, position?: 'top' | 'bottom' | 'left' | 'right'): this;
+    content(content: ValidChild): this;
+    variant(name: string): this;
+    outlined(): this;
+    elevated(): this;
+    flat(): this;
+    clickable(handler: (event: MouseEvent) => void): this;
+    hoverable(): this;
+    loading(isLoading?: boolean | ObservableItem<boolean>): this;
+    horizontal(): this;
+    onClick(handler: (event: MouseEvent) => void): this;
+    onHover(handler: (event: MouseEvent) => void): this;
+    clearActions(): this;
+    action(label: ValidChild, callback: () => void): this;
+    renderImage(renderFn: (desc: CardDescription, instance: CardInterface) => ValidChild): this;
+    renderHeader(renderFn: (desc: CardDescription, instance: CardInterface) => ValidChild): this;
+    renderContent(renderFn: (desc: CardDescription, instance: CardInterface) => ValidChild): this;
+    renderFooter(renderFn: (desc: CardDescription, instance: CardInterface) => ValidChild): this;
+    layout(layoutFn: (desc: CardDescription, instance: CardInterface) => ValidChild): this;
+    render(renderFn: (desc: CardDescription, instance: CardInterface) => ValidChild): this;
+}
+
+
+export declare function Card(config?: Record<string, unknown>): CardInterface;
+export declare namespace Card {
+
+
+    function use(template: (description: CardDescription, instance: CardInterface) => ValidChild): void;
+
+
+}

package/src/components/context-menu/ContextMenu.js

@@ -1,8 +1,25 @@
-import Menu from "../menu/Menu";
-import BaseComponent from "../BaseComponent";
-import {NDElement} from "../../core/wrappers/NDElement";
+import Menu from '../menu/Menu';
+import BaseComponent from '../BaseComponent';
+import {NDElement} from '../../core/wrappers/NDElement';
 import { $ } from '../../core/data/Observable';
 
+/**
+ * Floating context menu triggered by right-click or custom trigger element. Wraps a Menu component.
+ *
+ *
+ * @example
+ * const ctxMenu = new ContextMenu()
+ *     .trigger(myElement)
+ *     .menu((menu) => {
+ *         menu.item('Edit', () => edit())
+ *             .item('Delete', () => remove())
+ *             .separator()
+ *             .item('Copy link', () => copy());
+ *     });
+ *
+ * @constructor
+ * @param {GlobalAttributes} [props]
+ */
 export default function ContextMenu(props = {}) {
     if(!(this instanceof ContextMenu)) {
         return new ContextMenu(props);
@@ -25,13 +42,20 @@ BaseComponent.extends(ContextMenu);
 ContextMenu.defaultTemplate = null;
 ContextMenu.defaultHandler = null;
 
+/**
+ * Registers the render template and interaction handler for ContextMenu.
+ * @param {(description: {
+ *     props: GlobalAttributes,
+ * }, instance: ContextMenu) => NdChild} template
+ * @param {Function} handler
+ */
 ContextMenu.use = function(template, handler) {
     ContextMenu.defaultTemplate = template;
     if(!handler) {
         return;
     }
     if(ContextMenu.defaultHandler === handler) {
-        return
+        return;
     };
     ContextMenu.defaultHandler = handler;
 
@@ -51,17 +75,31 @@ ContextMenu.use = function(template, handler) {
     }
 };
 
+/**
+ * @param {number} x
+ * @param {number} y
+ * @returns {this}
+ */
 ContextMenu.prototype.position = function(x, y) {
     this.$description.positionX.set(x);
     this.$description.positionY.set(y);
     return this;
 };
 
+/**
+ * @param {HTMLElement|NDElement} trigger
+ * @returns {this}
+ */
 ContextMenu.prototype.trigger = function(trigger) {
     this.$description.trigger = trigger;
     return this;
-}
+};
 
+/**
+ * @param {(menu: Menu) => void} callback
+ * @param {GlobalAttributes} [props={}]
+ * @returns {this}
+ */
 ContextMenu.prototype.menu = function(callback, props = {}) {
     const menu = new Menu(props);
     menu.dataResolver(() => this.$description.data);
@@ -72,11 +110,17 @@ ContextMenu.prototype.menu = function(callback, props = {}) {
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 ContextMenu.prototype.hide = function() {
     this.$description.isOpen.set(false);
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 ContextMenu.prototype.show = function() {
     this.$description.isOpen.set(true);
     return this;

package/src/components/context-menu/ContextMenuGroup.js

@@ -1,5 +1,12 @@
-import MenuGroup from "../menu/MenuGroup";
+import MenuGroup from '../menu/MenuGroup';
 
+/**
+ *
+ *
+ * @constructor
+ * @param {NdChild} label
+ * @param {GlobalAttributes} [config]
+ */
 export default function ContextMenuGroup(label, config) {
     if(!(this instanceof ContextMenuGroup)) {
         return new ContextMenuGroup(label, config);
@@ -11,6 +18,12 @@ export default function ContextMenuGroup(label, config) {
 
 ContextMenuGroup.defaultTemplate = null;
 
+/**
+ * Registers the render template for ContextMenuGroup.
+ * @param {(description: {
+ *     [key: string]: *
+ * }, instance: ContextMenuGroup) => NdChild} template
+ */
 ContextMenuGroup.use = function(template) {
-    ContextMenuGroup.defaultTemplate = template.contextMenuGroup;
+    ContextMenuGroup.defaultTemplate = template;
 };

package/src/components/context-menu/ContextMenuItem.js

@@ -1,5 +1,11 @@
-import MenuItem from "../menu/MenuItem";
+import MenuItem from '../menu/MenuItem';
 
+/**
+ *
+ *
+ * @constructor
+ * @param {GlobalAttributes} [config]
+ */
 export default function ContextMenuItem(config) {
     if(!(this instanceof ContextMenuItem)) {
         return new ContextMenuItem(config);
@@ -11,6 +17,12 @@ export default function ContextMenuItem(config) {
 
 ContextMenuItem.defaultTemplate = null;
 
+/**
+ * Registers the render template for ContextMenuItem.
+ * @param {(description: {
+ *     [key: string]: *
+ * }, instance: ContextMenuItem) => NdChild} template
+ */
 ContextMenuItem.use = function(template) {
-    ContextMenuItem.defaultTemplate = template.contextMenuItem;
+    ContextMenuItem.defaultTemplate = template;
 };

package/src/components/context-menu/index.js

@@ -1,10 +1,10 @@
-import ContextMenu from "./ContextMenu";
-import ContextMenuItem from "./ContextMenuItem";
-import ContextMenuGroup from "./ContextMenuGroup";
+import ContextMenu from './ContextMenu';
+import ContextMenuItem from './ContextMenuItem';
+import ContextMenuGroup from './ContextMenuGroup';
 
 
 export {
     ContextMenu,
     ContextMenuItem,
-    ContextMenuGroup
-}
+    ContextMenuGroup,
+};

package/src/components/context-menu/types/ContextMenu.d.ts

@@ -0,0 +1,30 @@
+import type { ValidChild } from '../../../../types/elements';
+import type { ObservableItem } from '../../../../types/observable';
+import type { BaseComponent } from '../../BaseComponent';
+import type { MenuInterface } from '../../menu/types/Menu';
+import type { GlobalAttributes } from '../../../../types/globals';
+
+export type ContextMenuDescription = { props: GlobalAttributes; };
+
+export interface ContextMenuInterface extends BaseComponent {
+    position(x: number, y: number): this;
+    trigger(trigger: HTMLElement): this;
+    menu(callback: (menu: MenuInterface) => void, props?: Record<string, unknown>): this;
+    hide(): this;
+    show(): this;
+
+    render(renderFn: (description: ContextMenuDescription, instance: ContextMenuInterface) => ValidChild): this;
+}
+
+
+export declare function ContextMenu(props?: Record<string, unknown>): ContextMenuInterface;
+export declare namespace ContextMenu {
+
+
+    function use(
+    function template: (description: ContextMenuDescription, instance: ContextMenuInterface) => ValidChild,
+    handler: Function
+    ): void;
+
+
+}

package/src/components/context-menu/types/ContextMenuGroup.d.ts

@@ -0,0 +1,18 @@
+import type { ValidChild } from '../../../../types/elements';
+import type { ObservableItem } from '../../../../types/observable';
+import type { MenuGroupInterface, MenuGroupDescription } from '../../menu/types/MenuGroup';
+
+
+export interface ContextMenuGroupInterface extends MenuGroupInterface {
+    render(renderFn: (description: MenuGroupDescription, instance: ContextMenuGroupInterface) => ValidChild): this;
+}
+
+
+export declare function ContextMenuGroup(label: ValidChild, config?: Record<string, unknown>): ContextMenuGroupInterface;
+export declare namespace ContextMenuGroup {
+
+
+    function use(template: (description: MenuGroupDescription, instance: ContextMenuGroupInterface) => ValidChild): void;
+
+
+}

package/src/components/context-menu/types/ContextMenuItem.d.ts

@@ -0,0 +1,18 @@
+import type { ValidChild } from '../../../../types/elements';
+import type { ObservableItem } from '../../../../types/observable';
+import type { MenuItemInterface, MenuItemDescription } from '../../menu/types/MenuItem';
+
+
+export interface ContextMenuItemInterface extends MenuItemInterface {
+    render(renderFn: (description: MenuItemDescription, instance: ContextMenuItemInterface) => ValidChild): this;
+}
+
+
+export declare function ContextMenuItem(config?: Record<string, unknown>): ContextMenuItemInterface;
+export declare namespace ContextMenuItem {
+
+
+    function use(template: (description: MenuItemDescription, instance: ContextMenuItemInterface) => ValidChild): void;
+
+
+}