native-document 1.0.165 → 1.0.168

package/src/components/breadcrumb/BreadCrumb.js

@@ -1,8 +1,14 @@
-import BaseComponent from "../BaseComponent";
-import HasEventEmitter from "../../core/utils/HasEventEmitter";
-import { $ } from "../../core/data/Observable";
-import DebugManager from "../../core/utils/debug-manager";
+import BaseComponent from '../BaseComponent';
+import HasEventEmitter from '../../core/utils/HasEventEmitter';
+import { $ } from '../../core/data/Observable';
+import DebugManager from '../../core/utils/debug-manager';
 
+/**
+ *
+ *
+ * @constructor
+ * @param {GlobalAttributes} [props]
+ */
 export default function Breadcrumb(props = {}) {
     if (!(this instanceof Breadcrumb)) {
         return new Breadcrumb(props);
@@ -21,10 +27,21 @@ BaseComponent.extends(Breadcrumb);
 BaseComponent.use(Breadcrumb, HasEventEmitter);
 
 Breadcrumb.defaultTemplate = null;
+
+/**
+ * Registers the render template for Breadcrumb.
+ * @param {(description: {
+ *     [key: string]: *
+ * }, instance: Breadcrumb) => NdChild} template
+ */
 Breadcrumb.use = function(template) {
     Breadcrumb.defaultTemplate = template;
 };
 
+/**
+ * @param {string} name
+ * @param {(b: Breadcrumb) => Breadcrumb} callback
+ */
 Breadcrumb.preset = function(name, callback) {
     if (Breadcrumb.prototype[name] || Breadcrumb[name]) {
         DebugManager.warn(`Warning: the ${name} method already exist in Breadcrumb.`);
@@ -33,21 +50,39 @@ Breadcrumb.preset = function(name, callback) {
     Breadcrumb[name] = (props) => callback(new Breadcrumb(props));
 };
 
+/**
+ * @param {Record<string, (b: Breadcrumb) => Breadcrumb>} presets
+ */
 Breadcrumb.presets = function(presets) {
     for (const name in presets) {
         Breadcrumb.preset(name, presets[name]);
     }
 };
 
+/**
+ * @param {Observable<Array<{ label: NdChild, href?: string, value?: * }>>|Array<*>} source
+ * @returns {this}
+ */
 Breadcrumb.prototype.bind = function(source) {
     this.$description.items = source.__$Observable ? source : $.array(source);
     return this;
 };
 
+/**
+ * @param {NdChild} label
+ * @param {string} [href]
+ * @param {*} [value]
+ * @returns {this}
+ */
 Breadcrumb.prototype.item = function(label, href, value) {
     this.$description.items.push({ label, href, value: value || href });
     return this;
 };
+
+/**
+ * @param {{ label: NdChild, href?: string, value?: * }[]} items
+ * @returns {this}
+ */
 Breadcrumb.prototype.items = function(items) {
     this.$description.items = [];
     for(const item of items) {
@@ -56,26 +91,47 @@ Breadcrumb.prototype.items = function(items) {
     return this;
 };
 
+/**
+ * @param {number} index
+ * @returns {this}
+ */
 Breadcrumb.prototype.removeItem = function(index) {
     this.$description.items.splice(index, 1);
 };
 
+/**
+ * @param {NdChild} separator
+ * @returns {this}
+ */
 Breadcrumb.prototype.separator = function(separator) {
     this.$description.separator = separator;
     return this;
 };
 
-
+/**
+ * @param {(item: { label: NdChild, href?: string, value?: * }, event: MouseEvent) => void} handler
+ * @returns {this}
+ */
 Breadcrumb.prototype.onItemClick = function(handler) {
     this.on('clickItem', handler);
     return this;
 };
 
 // Render
+
+/**
+ * @param {(desc: *, instance: *) => NdChild} renderFn
+ * @returns {this}
+ */
 Breadcrumb.prototype.renderSeparator = function(renderFn) {
     this.$description.renderSeparator = renderFn;
     return this;
 };
+
+/**
+ * @param {(desc: *, instance: *) => NdChild} renderFn
+ * @returns {this}
+ */
 Breadcrumb.prototype.renderItem = function(renderFn) {
     this.$description.renderItem = renderFn;
     return this;

package/src/components/breadcrumb/index.js

@@ -1,5 +1,5 @@
 import Breadcrumb from './BreadCrumb';
 
 export {
-    Breadcrumb
-}
+    Breadcrumb,
+};

package/src/components/breadcrumb/types/BreadCrumb.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';
+
+interface BreadCrumbItem {
+    label: ValidChild;
+    href?: string;
+    value?: unknown;
+}
+
+export type BreadCrumbDescription = {
+        separator: ValidChild | null;
+        items: ObservableItem<Array<{ label: ValidChild; href?: string; value?: unknown }>>;
+        renderSeparator: ((separator: unknown, instance: BreadCrumbInterface) => ValidChild) | null;
+        renderItem: ((item: { label: ValidChild; href?: string; value?: unknown }, instance: BreadCrumbInterface) => ValidChild) | null;
+        props: GlobalAttributes;
+    };
+
+export interface BreadCrumbInterface extends BaseComponent {
+    bind(source: ObservableItem<BreadCrumbItem[]> | BreadCrumbItem[]): this;
+    item(label: ValidChild, href?: string, value?: unknown): this;
+    items(items: BreadCrumbItem[]): this;
+    removeItem(index: number): this;
+    separator(separator: ValidChild): this;
+    onItemClick(handler: (item: BreadCrumbItem, event: MouseEvent) => void): this;
+    renderSeparator(renderFn: (separator: unknown, instance: BreadCrumbInterface) => ValidChild): this;
+    renderItem(renderFn: (item: BreadCrumbItem, instance: BreadCrumbInterface) => ValidChild): this;
+    render(template: (description: BreadCrumbDescription, instance: BreadCrumbInterface) => ValidChild): this;
+}
+
+
+export declare function BreadCrumb(props?: Record<string, unknown>): BreadCrumbInterface;
+export declare namespace BreadCrumb {
+
+
+    function use(template: (description: BreadCrumbDescription, instance: BreadCrumbInterface) => ValidChild): void;
+    function preset(name: string, callback: (instance: BreadCrumbInterface) => BreadCrumbInterface): void;
+    function presets(presets: Record<string, (instance: BreadCrumbInterface) => BreadCrumbInterface>): void;
+
+
+}

package/src/components/button/Button.js

@@ -1,6 +1,38 @@
-import BaseComponent from "../BaseComponent";
-import DebugManager from "../../core/utils/debug-manager";
+import BaseComponent from '../BaseComponent';
+import DebugManager from '../../core/utils/debug-manager';
 
+/**
+ * Interactive button with variants, sizes, icon placement, loading and disabled states. Use Button.use() to register a custom render template. Use Button.preset() to define named factory shortcuts.
+ *
+ *
+ * @example
+ * const btn = new Button(Span('Save'))
+ *     .variant('primary')
+ *     .size('medium')
+ *     .icon(SaveIcon(), 'leading')
+ *     .loading(isSubmitting)
+ *     .disabled(false)
+ *     .onClick(() => form.submit());
+ *
+ * // Custom render template
+ * Button.use((description, instance) => {
+ *     // description.label, description.variant, description.icon, description.loading...
+ *     return Div(
+ *         { class: \`btn btn--\${description.variant}\` },
+ *         description.loading ? Spinner() : description.label
+ *     );
+ * });
+ *
+ * // Named preset
+ * Button.preset('danger-sm', (instance) =>
+ *     instance.variant('danger').size('small')
+ * );
+ * const deleteBtn = Button.preset('danger-sm')(Span('Delete'));
+ *
+ * @constructor
+ * @param {NdChild} label
+ * @param {GlobalAttributes} [props={}]
+ */
 export default function Button(label, props = {}) {
     if(!(this instanceof Button)) {
         return new Button(label, props);
@@ -21,7 +53,7 @@ export default function Button(label, props = {}) {
         block: null,
         borderRadiusType: null,
         outline: null,
-        props
+        props,
     };
 
     this.$element = null;
@@ -29,12 +61,33 @@ export default function Button(label, props = {}) {
 
 Button.defaultTemplate = null;
 
+/**
+ * Registers the render template for Button.
+ * @param {(description: {
+ *     label: NdChild,
+ *     type: 'button'|'submit'|'reset'|null,
+ *     variant: string|null,
+ *     size: 'small'|'medium'|'large'|string|null,
+ *     icon: NdChild|null,
+ *     iconPosition: 'leading'|'trailing'|'top'|'bottom',
+ *     loading: Observable<boolean>|null,
+ *     disabled: Observable<boolean>|null,
+ *     block: boolean|null,
+ *     borderRadiusType: 'rounded'|'pill'|'circle'|'smooth'|null,
+ *     outline: boolean|null,
+ *     props: GlobalAttributes,
+ * }, instance: Button) => NdChild} template
+ */
 Button.use = function(template = {}) {
     Button.defaultTemplate = template;
 };
 
 BaseComponent.extends(Button);
 
+/**
+ * @param {string} name
+ * @param {(b: Button) => Button} callback
+ */
 Button.preset = function(name, callback) {
     if (Button.prototype[name] || Button[name]) {
         DebugManager.warn(`Warning: the ${name} method already exist in Button.`);
@@ -43,122 +96,224 @@ Button.preset = function(name, callback) {
     Button[name] = (label, props) => callback(new Button(label, props));
 };
 
+/**
+ * @param {Record<string, (b: Button) => Button>} presets
+ */
 Button.presets = function(presets) {
     for (const name in presets) {
         Button.preset(name, presets[name]);
     }
 };
 
+/**
+ * @param {'button'|'submit'|'reset'} type
+ * @returns {this}
+ */
 Button.prototype.type = function(type) {
     this.$description.type = type;
     return this;
 };
 
+/**
+ * @param {string} variant
+ * @returns {this}
+ */
 Button.prototype.variant = function(variant) {
     this.$description.variant = variant;
     return this;
 };
+
+/**
+ * @returns {this}
+ */
 Button.prototype.primary = function() {
     return this.variant('primary');
 };
+
+/**
+ * @returns {this}
+ */
 Button.prototype.secondary = function() {
     return this.variant('secondary');
 };
+
+/**
+ * @returns {this}
+ */
 Button.prototype.danger = function() {
     return this.variant('danger');
 };
+
+/**
+ * @returns {this}
+ */
 Button.prototype.success = function() {
     return this.variant('success');
 };
+
+/**
+ * @returns {this}
+ */
 Button.prototype.warning = function() {
     return this.variant('warning');
 };
+
+/**
+ * @returns {this}
+ */
 Button.prototype.ghost = function() {
     return this.variant('ghost');
 };
+
+/**
+ * @returns {this}
+ */
 Button.prototype.link = function() {
     return this.variant('link');
 };
+
+/**
+ * @returns {this}
+ */
 Button.prototype.outline = function() {
     this.$description.outline = true;
     return this;
 };
 
+/**
+ * @param {'small'|'medium'|'large'|string|null} size
+ * @returns {this}
+ */
 Button.prototype.size = function(size) {
     this.$description.size = size;
     return this;
 };
+
+/**
+ * @returns {this}
+ */
 Button.prototype.small = function() {
     return this.size('small');
 };
+
+/**
+ * @returns {this}
+ */
 Button.prototype.large = function() {
     return this.size('large');
 };
+
+/**
+ * @returns {this}
+ */
 Button.prototype.medium = function() {
     return this.size('medium');
 };
 
+/**
+ * @param {NdChild} icon
+ * @param {'leading'|'trailing'|'top'|'bottom'} [iconPosition='leading']
+ * @returns {this}
+ */
 Button.prototype.icon = function(icon, iconPosition = 'leading') {
     this.$description.icon = icon;
     this.$description.iconPosition = iconPosition;
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Button.prototype.iconAtLeading = function() {
     this.$description.iconPosition = 'leading';
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Button.prototype.iconAtTrailing = function() {
     this.$description.iconPosition = 'trailing';
     return this;
 };
+
+/**
+ * @returns {this}
+ */
 Button.prototype.iconAtTop = function() {
     this.$description.iconPosition = 'top';
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Button.prototype.iconAtBottom = function() {
     this.$description.iconPosition = 'bottom';
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Button.prototype.iconOnly = function() {
     this.$description.iconOnly = true;
     return this;
 };
 
+/**
+ * @param {boolean|Observable<boolean>} [loading=true]
+ * @returns {this}
+ */
 Button.prototype.loading = function(loading = true) {
     this.$description.loading = BaseComponent.obs(loading);
     return this;
-}
+};
 
+/**
+ * @param {boolean|Observable<boolean>} [disabled=true]
+ * @returns {this}
+ */
 Button.prototype.disabled = function(disabled = true) {
     this.$description.disabled = BaseComponent.obs(disabled);
     return this;
 };
 
-Button.prototype.render = function(renderFunction) {
-    this.$description.render = renderFunction;
-    return this;
-};
-
+/**
+ * @returns {this}
+ */
 Button.prototype.rounded = function() {
     this.$description.borderRadiusType = 'rounded';
     return this;
 };
+
+/**
+ * @returns {this}
+ */
 Button.prototype.pill = function() {
     this.$description.borderRadiusType = 'pill';
     return this;
 };
+
+/**
+ * @returns {this}
+ */
 Button.prototype.circle = function() {
     this.$description.borderRadiusType = 'circle';
     return this;
 };
+
+/**
+ * @returns {this}
+ */
 Button.prototype.smooth = function() {
     this.$description.borderRadiusType = 'smooth';
     return this;
 };
+
+/**
+ * @returns {this}
+ */
 Button.prototype.block = function() {
     this.$description.block = true;
     return this;

package/src/components/button/index.js

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

package/src/components/button/types/Button.d.ts

@@ -0,0 +1,62 @@
+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 ButtonDescription = {
+        label: ValidChild;
+        type: 'button' | 'submit' | 'reset' | null;
+        variant: string | null;
+        size: 'small' | 'medium' | 'large' | string | null;
+        icon: ValidChild | null;
+        iconPosition: 'leading' | 'trailing' | 'top' | 'bottom';
+        loading: ObservableItem<boolean> | null;
+        disabled: ObservableItem<boolean> | null;
+        block: boolean | null;
+        borderRadiusType: 'rounded' | 'pill' | 'circle' | 'smooth' | null;
+        outline: boolean | null;
+        props: GlobalAttributes;
+    };
+
+export interface ButtonInterface extends BaseComponent {
+    type(type: 'button' | 'submit' | 'reset'): this;
+    variant(variant: string): this;
+    primary(): this;
+    secondary(): this;
+    danger(): this;
+    success(): this;
+    warning(): this;
+    ghost(): this;
+    link(): this;
+    outline(): this;
+    size(size: 'small' | 'medium' | 'large' | string): this;
+    small(): this;
+    medium(): this;
+    large(): this;
+    icon(icon: ValidChild, iconPosition?: 'leading' | 'trailing' | 'top' | 'bottom'): this;
+    iconAtLeading(): this;
+    iconAtTrailing(): this;
+    iconAtTop(): this;
+    iconAtBottom(): this;
+    iconOnly(): this;
+    loading(loading?: boolean | ObservableItem<boolean>): this;
+    disabled(disabled?: boolean | ObservableItem<boolean>): this;
+    render(renderFunction: (description: ButtonDescription, component: ButtonInterface) => ValidChild): this;
+    rounded(): this;
+    pill(): this;
+    circle(): this;
+    smooth(): this;
+    block(): this;
+}
+
+
+export declare function Button(label: ValidChild, props?: Record<string, unknown>): ButtonInterface;
+export declare namespace Button {
+
+
+    function use(template: (description: ButtonDescription, instance: ButtonInterface) => ValidChild): void;
+    function preset(name: string, callback: (instance: ButtonInterface) => ButtonInterface): void;
+    function presets(presets: Record<string, (instance: ButtonInterface) => ButtonInterface>): void;
+
+
+}