native-document 1.0.165 → 1.0.166

package/src/components/accordion/AccordionItem.js

@@ -1,15 +1,28 @@
 import { $ } from '../../core/data/Observable';
-import BaseComponent from "../BaseComponent";
-import HasEventEmitter from "../../core/utils/HasEventEmitter";
-
-/**
- * Represents an individual item within an Accordion component
- * @param {{ id?: string|number, title?: string, icon?: string, collapsible?: boolean, content?: ValidChildren, renderHeader?: Function, renderContent?: Function, render?: Function, expanded?: Observable<boolean>, disabled?: boolean }} config - Configuration object
- * @class
+import BaseComponent from '../BaseComponent';
+import HasEventEmitter from '../../core/utils/HasEventEmitter';
+
+/**
+ * A single collapsible item inside an Accordion. Manages its own expanded/collapsed state.
+ *
+ *
+ * @example
+ * const item = new AccordionItem()
+ *     .title(Span('My title'))
+ *     .icon(SomeIcon())
+ *     .content(Div('Body content'))
+ *     .collapsible(true)
+ *     .disabled(false);
+ *
+ * item.onExpand(() => console.log('expanded'))
+ *     .onCollapse(() => console.log('collapsed'));
+ *
+ * @constructor
+ * @param {GlobalAttributes} [props]
  */
 export default function AccordionItem(props = {}) {
     if(!(this instanceof AccordionItem)){
-        return new AccordionItem()
+        return new AccordionItem();
     }
 
     BaseComponent.call(this, props);
@@ -26,7 +39,7 @@ export default function AccordionItem(props = {}) {
         render: null,
         expanded: $(false),
         disabled: $(false),
-        props
+        props,
     };
 }
 
@@ -34,6 +47,24 @@ BaseComponent.extends(AccordionItem);
 BaseComponent.use(AccordionItem, HasEventEmitter);
 
 AccordionItem.defaultTemplate = null;
+
+/**
+ * Registers the render template for AccordionItem.
+ * @param {(description: {
+ *     id: string|number|null,
+ *     title: NdChild|null,
+ *     icon: NdChild|null,
+ *     collapsible: boolean,
+ *     content: NdChild|null,
+ *     renderHeader: ((desc: *, instance: AccordionItem) => NdChild)|null,
+ *     renderIndicator: ((desc: *, instance: AccordionItem) => NdChild)|null,
+ *     renderContent: ((desc: *, instance: AccordionItem) => NdChild)|null,
+ *     render: ((desc: *, instance: AccordionItem) => NdChild)|null,
+ *     expanded: Observable<boolean>,
+ *     disabled: Observable<boolean>,
+ *     props: GlobalAttributes,
+ * }, instance: AccordionItem) => NdChild} template
+ */
 AccordionItem.use = function(template) {
     AccordionItem.defaultTemplate = template;
 };
@@ -45,7 +76,7 @@ AccordionItem.use = function(template) {
 Object.defineProperty(AccordionItem.prototype, 'id', {
     get() {
         return this.$description.id;
-    }
+    },
 });
 
 /**
@@ -60,7 +91,7 @@ AccordionItem.prototype.identifyBy = function(id) {
 
 /**
  * Sets the content of the accordion item
- * @param {ValidChildren} content - The content to display
+ * @param {NdChild} content - The content to display
  * @returns {AccordionItem}
  */
 AccordionItem.prototype.content = function(content) {
@@ -70,7 +101,7 @@ AccordionItem.prototype.content = function(content) {
 
 /**
  * Sets the title of the accordion item
- * @param {ValidChildren} title
+ * @param {NdChild} title
  * @returns {AccordionItem}
  */
 AccordionItem.prototype.title = function(title) {
@@ -80,7 +111,7 @@ AccordionItem.prototype.title = function(title) {
 
 /**
  * Sets the icon for the accordion item
- * @param {ValidChildren} icon - The icon identifier or element
+ * @param {NdChild} icon - The icon identifier or element
  * @returns {AccordionItem}
  */
 AccordionItem.prototype.icon = function(icon) {
@@ -96,7 +127,7 @@ AccordionItem.prototype.icon = function(icon) {
 AccordionItem.prototype.showIndicator = function(show = true) {
     this.$description.showIndicator = show;
     return this;
-}
+};
 
 /**
  * Sets whether the item can be collapsed

package/src/components/accordion/index.js

@@ -3,5 +3,5 @@ import AccordionItem from './AccordionItem';
 
 export {
     Accordion,
-    AccordionItem
-}
+    AccordionItem,
+};

package/src/components/accordion/types/Accordion.d.ts

@@ -0,0 +1,47 @@
+import type { ValidChild } from '../../../../types/elements';
+import type { ObservableItem } from '../../../../types/observable';
+import type { BaseComponent } from '../../BaseComponent';
+import type { AccordionItemInterface, AccordionItemConstructor } from './AccordionItem';
+import type { GlobalAttributes } from '../../../../types/globals';
+
+export type AccordionDescription = {
+        items: AccordionItemInterface[];
+        multiple: boolean | null;
+        variant: string | null;
+        renderContent: ((desc: AccordionDescription, instance: AccordionInterface) => ValidChild) | null;
+        renderIndicator: ((desc: AccordionDescription, instance: AccordionInterface) => ValidChild) | null;
+        props: GlobalAttributes;
+    };
+
+export interface AccordionInterface extends BaseComponent {
+    item(title: ValidChild | AccordionItemInterface, content?: ValidChild, options?: Record<string, unknown> | ((item: AccordionItemInterface) => void)): this;
+    items(items: AccordionItemInterface[]): this;
+    addItem(title: ValidChild | AccordionItemInterface, content?: ValidChild, options?: unknown): this;
+    removeItemById(id: string | number): this;
+    remove(filter: (item: AccordionItemInterface) => boolean): this;
+    multiple(enabled?: boolean): this;
+    variant(name: string): this;
+    bordered(): this;
+    separated(): this;
+    flush(): this;
+    getByKey(key: string): AccordionItemInterface | undefined;
+    expanded(key: string, state?: boolean): this;
+    expandAll(): this;
+    collapseAll(): this;
+    isExpanded(key: string): boolean | undefined;
+    onExpand(handler: (key: string, state: boolean) => void): this;
+    onCollapse(handler: (key: string, state: boolean) => void): this;
+    renderContent(renderFn: (desc: AccordionDescription, instance: AccordionInterface) => ValidChild): this;
+    renderIndicator(renderFn: (desc: AccordionDescription, instance: AccordionInterface) => ValidChild): this;
+    render(template: (description: AccordionDescription, instance: AccordionInterface) => ValidChild): this;
+}
+
+
+export declare function Accordion(props?: Record<string, unknown>): AccordionInterface;
+export declare namespace Accordion {
+
+
+    function use(template: (description: AccordionDescription, instance: AccordionInterface) => ValidChild): void;
+
+
+}

package/src/components/accordion/types/AccordionItem.d.ts

@@ -0,0 +1,48 @@
+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 AccordionItemDescription = {
+        id: string | number | null;
+        title: ValidChild | null;
+        icon: ValidChild | null;
+        collapsible: boolean;
+        content: ValidChild | null;
+        renderHeader: ((desc: AccordionItemDescription, instance: AccordionItemInterface) => ValidChild) | null;
+        renderIndicator: ((desc: AccordionItemDescription, instance: AccordionItemInterface) => ValidChild) | null;
+        renderContent: ((desc: AccordionItemDescription, instance: AccordionItemInterface) => ValidChild) | null;
+        render: ((desc: AccordionItemDescription, instance: AccordionItemInterface) => ValidChild) | null;
+        expanded: ObservableItem<boolean>;
+        disabled: ObservableItem<boolean>;
+        props: GlobalAttributes;
+    };
+
+export interface AccordionItemInterface extends BaseComponent {
+    identifyBy(id: string | number): this;
+    content(content: ValidChild): this;
+    title(title: ValidChild): this;
+    icon(icon: ValidChild): this;
+    showIndicator(show?: boolean): this;
+    collapsible(collapsible?: boolean): this;
+    expanded(expanded?: boolean): this;
+    toggle(): this;
+    disabled(disabled?: boolean): this;
+    isExpanded(): boolean;
+    onExpand(handler: () => void): this;
+    onCollapse(handler: () => void): this;
+    renderHeader(renderFn: (desc: AccordionItemDescription, instance: AccordionItemInterface) => ValidChild): this;
+    renderContent(renderFn: (desc: AccordionItemDescription, instance: AccordionItemInterface) => ValidChild): this;
+    renderIndicator(renderFn: (desc: AccordionItemDescription, instance: AccordionItemInterface) => ValidChild): this;
+    render(template: (description: AccordionItemDescription, instance: AccordionItemInterface) => ValidChild): this;
+}
+
+
+export declare function AccordionItem(props?: Record<string, unknown>): AccordionItemInterface;
+export declare namespace AccordionItem {
+
+
+    function use(template: (description: AccordionItemDescription, instance: AccordionItemInterface) => ValidChild): void;
+
+
+}

package/src/components/alert/Alert.js

@@ -1,12 +1,28 @@
-import BaseComponent from "../BaseComponent";
-import HasEventEmitter from "../../core/utils/HasEventEmitter";
-import DebugManager from "../../core/utils/debug-manager";
+import BaseComponent from '../BaseComponent';
+import HasEventEmitter from '../../core/utils/HasEventEmitter';
+import DebugManager from '../../core/utils/debug-manager';
 
 /**
- * Component for displaying alert messages with various styles and variants
- * @param {ValidChildren} content - The alert message content
- * @param {{ title?: ValidChildren, content?: ValidChildren, outline?: boolean, style?: string, variant?: string, closable?: boolean, autoDismiss?: number, icon?: ValidChildren, showIcon?: boolean }} config - Configuration object
- * @class
+ * Contextual feedback alert. Supports variants (info, success, warning, error), icons, closable/auto-dismiss, and action buttons.
+ *
+ *
+ * @example
+ * const alert = new Alert(Span('Operation completed successfully.'))
+ *     .variant('success')
+ *     .showIcon(true)
+ *     .closable(true)
+ *     .autoDismiss(5000)
+ *     .action('Undo', () => console.log('undo'))
+ *     .onClose(() => console.log('closed'));
+ *
+ * Alert.use((description, instance) => {
+ *     // description.content, description.variant, description.actions...
+ *     return Div({ class: \`alert alert--\${description.variant}\` }, description.content);
+ * });
+ *
+ * @constructor
+ * @param {NdChild} content
+ * @param {GlobalAttributes} [props={}]
  */
 export default function Alert(content, props = {}) {
     if(!(this instanceof Alert)) {
@@ -33,8 +49,20 @@ export default function Alert(content, props = {}) {
 Alert.defaultTemplate = null;
 
 /**
- * Sets the default template for all Alert instances
- * @param {ValidChildren} template - Template object containing alert factory function
+ * Registers the render template for Alert.
+ * @param {(description: {
+ *     title: NdChild|null,
+ *     content: NdChild,
+ *     outline: boolean|null,
+ *     appearance: 'filled'|'bordered'|null,
+ *     variant: 'info'|'success'|'warning'|'error'|'danger'|string,
+ *     closable: boolean,
+ *     autoDismiss: number|null,
+ *     icon: NdChild|null,
+ *     showIcon: boolean,
+ *     actions: Array<{ label: NdChild, handler: Function|null, variant: string|null }>,
+ *     props: GlobalAttributes,
+ * }, instance: Alert) => NdChild} template
  */
 Alert.use = function(template) {
     Alert.defaultTemplate = template;
@@ -43,6 +71,10 @@ Alert.use = function(template) {
 BaseComponent.extends(Alert);
 BaseComponent.use(Alert, HasEventEmitter);
 
+/**
+ * @param {string} name
+ * @param {(a: Alert) => Alert} callback
+ */
 Alert.preset = function(name, callback) {
     if (Alert.prototype[name] || Alert[name]) {
         DebugManager.warn(`Warning: the ${name} method already exist in Alert.`);
@@ -51,6 +83,9 @@ Alert.preset = function(name, callback) {
     Alert[name] = (content, props) => callback(new Alert(content, props));
 };
 
+/**
+ * @param {Record<string, (a: Alert) => Alert>} presets
+ */
 Alert.presets = function(presets) {
     for (const name in presets) {
         Alert.preset(name, presets[name]);
@@ -60,7 +95,7 @@ Alert.presets = function(presets) {
 /**
  * Sets the variant style for the alert
  * @param {string} variant - The variant name (info, success, warning, error, danger)
- * @returns {Alert}
+ * @returns {this}
  */
 Alert.prototype.variant = function(variant) {
     this.$description.variant = variant;
@@ -69,7 +104,7 @@ Alert.prototype.variant = function(variant) {
 
 /**
  * Sets the alert variant to 'info'
- * @returns {Alert}
+ * @returns {this}
  */
 Alert.prototype.info = function() {
     return this.variant('info');
@@ -77,7 +112,7 @@ Alert.prototype.info = function() {
 
 /**
  * Sets the alert variant to 'success'
- * @returns {Alert}
+ * @returns {this}
  */
 Alert.prototype.success = function() {
     return this.variant('success');
@@ -85,7 +120,7 @@ Alert.prototype.success = function() {
 
 /**
  * Sets the alert variant to 'warning'
- * @returns {Alert}
+ * @returns {this}
  */
 Alert.prototype.warning = function() {
     return this.variant('warning');
@@ -93,7 +128,7 @@ Alert.prototype.warning = function() {
 
 /**
  * Sets the alert variant to 'error'
- * @returns {Alert}
+ * @returns {this}
  */
 Alert.prototype.error = function() {
     return this.variant('error');
@@ -101,7 +136,7 @@ Alert.prototype.error = function() {
 
 /**
  * Sets the alert variant to 'danger'
- * @returns {Alert}
+ * @returns {this}
  */
 Alert.prototype.danger = function() {
     return this.variant('danger');
@@ -110,7 +145,7 @@ Alert.prototype.danger = function() {
 /**
  * Sets the appearance type for the alert
  * @param {string} appearance - The style name (filled, bordered, outline)
- * @returns {Alert}
+ * @returns {this}
  */
 Alert.prototype.appearance = function(appearance) {
     this.$description.appearance = appearance;
@@ -119,7 +154,7 @@ Alert.prototype.appearance = function(appearance) {
 
 /**
  * Sets the alert appearance to 'filled'
- * @returns {Alert}
+ * @returns {this}
  */
 Alert.prototype.filled = function() {
     return this.appearance('filled');
@@ -127,7 +162,7 @@ Alert.prototype.filled = function() {
 
 /**
  * Sets the alert appearance to 'bordered'
- * @returns {Alert}
+ * @returns {this}
  */
 Alert.prototype.bordered = function() {
     return this.appearance('bordered');
@@ -136,7 +171,7 @@ Alert.prototype.bordered = function() {
 /**
  * Sets the alert appearance to 'outline'
  * @param {boolean} [outline=true] - Whether to use outline style
- * @returns {Alert}
+ * @returns {this}
  */
 Alert.prototype.outline = function(outline = true) {
     return this.appearance('outline');
@@ -145,7 +180,7 @@ Alert.prototype.outline = function(outline = true) {
 /**
  * Sets the title of the alert
  * @param {ValidChildren} title - The title content
- * @returns {Alert}
+ * @returns {this}
  */
 Alert.prototype.title = function(title) {
     this.$description.title = title;
@@ -155,7 +190,7 @@ Alert.prototype.title = function(title) {
 /**
  * Sets the content of the alert
  * @param {ValidChildren} content - The content to display
- * @returns {Alert}
+ * @returns {this}
  */
 Alert.prototype.content = function(content) {
     this.$description.content = content;
@@ -165,7 +200,7 @@ Alert.prototype.content = function(content) {
 /**
  * Sets the title render function
  * @param {Function} callback - Function to render the title
- * @returns {Alert}
+ * @returns {this}
  */
 Alert.prototype.renderTitle = function(callback) {
     this.$description.renderTitle = callback;
@@ -175,7 +210,7 @@ Alert.prototype.renderTitle = function(callback) {
 /**
  * Sets the content render function
  * @param {Function} callback - Function to render the content
- * @returns {Alert}
+ * @returns {this}
  */
 Alert.prototype.renderContent = function(callback) {
     this.$description.renderContent = callback;
@@ -184,7 +219,7 @@ Alert.prototype.renderContent = function(callback) {
 
 /**
  * Clears all actions from the alert
- * @returns {Alert}
+ * @returns {this}
  */
 Alert.prototype.renderFooter = function(callback) {
     this.$description.renderFooter = callback;
@@ -192,12 +227,9 @@ Alert.prototype.renderFooter = function(callback) {
 };
 
 /**
- * Adds an action button to the alert
- * @param {string} label - The button label
- * @param {Function} handler - The click handler
- * @returns {Alert}
+ * @returns {this}
  */
-Alert.prototype.clearActions = function(label, handler) {
+Alert.prototype.clearActions = function() {
     this.$description.actions = [];
     return this;
 };
@@ -207,7 +239,7 @@ Alert.prototype.clearActions = function(label, handler) {
  * @param {string} label - The button label
  * @param {Function} handler - The click handler
  * @param {?string} variant - The button variant style
- * @returns {Alert}
+ * @returns {this}
  */
 Alert.prototype.action = function(label, handler, variant = null) {
     handler = handler || ((_, instance) => instance.hide());
@@ -218,7 +250,7 @@ Alert.prototype.action = function(label, handler, variant = null) {
 /**
  * Sets the layout function for the alert
  * @param {Function} layoutFn - Function to layout the alert
- * @returns {Alert}
+ * @returns {this}
  */
 Alert.prototype.layout = function(layoutFn) {
     this.$description.layout = layoutFn;
@@ -228,7 +260,7 @@ Alert.prototype.layout = function(layoutFn) {
 /**
  * Sets the icon for the alert
  * @param {ValidChildren} icon - The icon to display
- * @returns {Alert}
+ * @returns {this}
  */
 Alert.prototype.icon = function(icon) {
     this.$description.icon = icon;
@@ -238,7 +270,7 @@ Alert.prototype.icon = function(icon) {
 /**
  * Shows or hides the icon
  * @param {boolean} [show=true] - Whether to show the icon
- * @returns {Alert}
+ * @returns {this}
  */
 Alert.prototype.showIcon = function(show = true) {
     this.$description.showIcon = show;
@@ -247,7 +279,7 @@ Alert.prototype.showIcon = function(show = true) {
 /**
  * Sets whether the alert can be closed
  * @param {boolean} [closable=true] - Whether the alert is closable
- * @returns {Alert}
+ * @returns {this}
  */
 Alert.prototype.closable = function(closable = true) {
     this.$description.closable = !!closable;
@@ -260,7 +292,7 @@ Alert.prototype.closable = function(closable = true) {
 /**
  * Sets whether the alert is dismissible (alias for closable)
  * @param {boolean} [dismissible=true] - Whether the alert is dismissible
- * @returns {Alert}
+ * @returns {this}
  */
 Alert.prototype.dismissible = function(dismissible = true) {
     return this.closable(dismissible);
@@ -269,7 +301,7 @@ Alert.prototype.dismissible = function(dismissible = true) {
 /**
  * Sets auto-dismiss delay for the alert
  * @param {number} delay - Delay in milliseconds before auto-dismissing
- * @returns {Alert}
+ * @returns {this}
  */
 Alert.prototype.autoDismiss = function(delay) {
     this.$description.autoDismiss = delay;
@@ -300,7 +332,7 @@ Alert.prototype.hide = Alert.prototype.close;
 /**
  * Registers a handler for the close event
  * @param {(element: Alert) => void} handler - The event handler
- * @returns {Alert}
+ * @returns {this}
  */
 Alert.prototype.onClose = function(handler) {
     this.on('close', handler);
@@ -310,7 +342,7 @@ Alert.prototype.onClose = function(handler) {
 /**
  * Registers a handler for the show event
  * @param {(element: Alert) => void} handler - The event handler
- * @returns {Alert}
+ * @returns {this}
  */
 Alert.prototype.onShow = function(handler) {
     this.on('show', handler);

package/src/components/alert/index.js

@@ -2,5 +2,5 @@ import Alert from './Alert';
 
 
 export {
-    Alert
-}
+    Alert,
+};

package/src/components/alert/types/Alert.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 AlertDescription = {
+        title: ValidChild | null;
+        content: ValidChild;
+        outline: boolean | null;
+        appearance: 'filled' | 'bordered' | null;
+        variant: 'info' | 'success' | 'warning' | 'error' | 'danger' | string;
+        closable: boolean;
+        autoDismiss: number | null;
+        icon: ValidChild | null;
+        showIcon: boolean;
+        actions: Array<{ label: ValidChild; handler: (() => void) | null; variant: string | null }>;
+        props: GlobalAttributes;
+    };
+
+export interface AlertInterface extends BaseComponent {
+    variant(variant: 'info' | 'success' | 'warning' | 'error' | 'danger' | string): this;
+    info(): this;
+    success(): this;
+    warning(): this;
+    error(): this;
+    danger(): this;
+    appearance(appearance: 'filled' | 'bordered'): this;
+    filled(): this;
+    bordered(): this;
+    outline(outline?: boolean): this;
+    title(title: ValidChild): this;
+    content(content: ValidChild): this;
+    renderTitle(callback: (desc: AlertDescription, instance: AlertInterface) => ValidChild): this;
+    renderContent(callback: (desc: AlertDescription, instance: AlertInterface) => ValidChild): this;
+    renderFooter(callback: (desc: AlertDescription, instance: AlertInterface) => ValidChild): this;
+    clearActions(): this;
+    action(label: ValidChild, handler?: () => void, variant?: string | null): this;
+    layout(layoutFn: (desc: AlertDescription, instance: AlertInterface) => ValidChild): this;
+    icon(icon: ValidChild): this;
+    showIcon(show?: boolean): this;
+    closable(closable?: boolean): this;
+    dismissible(dismissible?: boolean): this;
+    autoDismiss(delay: number): this;
+    close(): this;
+    show(): this;
+    hide(): this;
+    onClose(handler: () => void): this;
+    onShow(handler: () => void): this;
+    render(template: (description: AlertDescription, instance: AlertInterface) => ValidChild): this;
+}
+
+
+export declare function Alert(content: ValidChild, props?: Record<string, unknown>): AlertInterface;
+export declare namespace Alert {
+
+
+    function use(template: (description: AlertDescription, instance: AlertInterface) => ValidChild): void;
+    function preset(name: string, callback: (instance: AlertInterface) => AlertInterface): void;
+    function presets(presets: Record<string, (instance: AlertInterface) => AlertInterface>): void;
+
+
+}