native-document 1.0.165 → 1.0.166

package/src/components/avatar/Avatar.js

@@ -1,11 +1,26 @@
-import BaseComponent from "../BaseComponent";
-import DebugManager from "../../core/utils/debug-manager";
-
-/**
- * Component for displaying user avatars with images, initials, or icons
- * @param {Observable<string>|string} source - The avatar source (image URL or observable)
- * @param {*} props - Props object
- * @class
+import BaseComponent from '../BaseComponent';
+import DebugManager from '../../core/utils/debug-manager';
+
+/**
+ * Displays a user avatar with image, initials, or icon fallback. Supports status indicators, badges, shape, and size variants.
+ *
+ *
+ * @example
+ * const avatar = new Avatar('https://example.com/photo.jpg')
+ *     .alt('Jane Doe')
+ *     .name('Jane Doe')
+ *     .size('large')
+ *     .shape('circle')
+ *     .status('online')
+ *     .statusAtTopTrailing();
+ *
+ * Avatar.use((description, instance) => {
+ *     return Img({ src: description.src, alt: description.alt });
+ * });
+ *
+ * @constructor
+ * @param {string|Observable<string>} [source]
+ * @param {GlobalAttributes} [props={}]
  */
 export default function Avatar(source, props = {}) {
     if (!(this instanceof Avatar)) {
@@ -25,7 +40,7 @@ export default function Avatar(source, props = {}) {
         textColor: null,
         status: null,
         render: null,
-        props
+        props,
     };
 }
 
@@ -33,14 +48,33 @@ BaseComponent.extends(Avatar);
 
 Avatar.defaultTemplate = null;
 
+
 /**
- * Sets the default template for all Avatar instances
- * @param {ValidChildren} template - Template object containing avatar factory function
+ * Registers the render template for Avatar.
+ * @param {(description: {
+ *     src: Observable<string>|null,
+ *     alt: string|null,
+ *     name: string|null,
+ *     initials: string|null,
+ *     icon: NdChild|null,
+ *     size: 'extra-small'|'small'|'medium'|'large'|'extra-large'|string|number,
+ *     shape: 'circle'|'square'|'rounded',
+ *     variant: string|null,
+ *     color: string|null,
+ *     textColor: string|null,
+ *     status: Observable<string>|string|null,
+ *     render: ((desc: *, instance: Avatar) => NdChild)|null,
+ *     props: GlobalAttributes,
+ * }, instance: Avatar) => NdChild} template
  */
 Avatar.use = function(template) {
     Avatar.defaultTemplate = template;
 };
 
+/**
+ * @param {string} name
+ * @param {(a: Avatar) => Avatar} callback
+ */
 Avatar.preset = function(name, callback) {
     if (Avatar.prototype[name] || Avatar[name]) {
         DebugManager.warn(`Warning: the ${name} method already exists in Avatar.`);
@@ -49,6 +83,9 @@ Avatar.preset = function(name, callback) {
     Avatar[name] = (label, props) => callback(new Avatar(label, props));
 };
 
+/**
+ * @param {Record<string, (a: Avatar) => Avatar>} presets
+ */
 Avatar.presets = function(presets) {
     for (const name in presets) {
         Avatar.preset(name, presets[name]);
@@ -256,7 +293,7 @@ Avatar.prototype.warning = function() {
  */
 Avatar.prototype.info = function() {
     return this.variant('info');
-}
+};
 
 /**
  * Sets the background color of the avatar

package/src/components/avatar/AvatarGroup.js

@@ -1,6 +1,23 @@
-import BaseComponent from "../BaseComponent";
-
+import BaseComponent from '../BaseComponent';
 
+/**
+ * Renders a group of overlapping Avatar components with a "+N" overflow indicator.
+ *
+ *
+ * @example
+ * const group = new AvatarGroup()
+ *     .items([
+ *         new Avatar('user1.jpg').name('Alice'),
+ *         new Avatar('user2.jpg').name('Bob'),
+ *         new Avatar('user3.jpg').name('Carol'),
+ *     ])
+ *     .max(3)
+ *     .overlap(8)
+ *     .onMoreClick((count) => console.log(\`\${count} more users\`));
+ *
+ * @constructor
+ * @param {GlobalAttributes} [props]
+ */
 export default function AvatarGroup(props = {}) {
     if(!(this instanceof AvatarGroup)) {
         return new AvatarGroup(props);
@@ -19,30 +36,61 @@ export default function AvatarGroup(props = {}) {
 BaseComponent.extends(AvatarGroup);
 
 AvatarGroup.defaultTemplate = null;
+
+/**
+ * Registers the render template for AvatarGroup.
+ * @param {(description: {
+ *     items: Avatar[],
+ *     overlap: number,
+ *     max: number,
+ *     onMoreClick: ((count: number) => void)|null,
+ *     props: GlobalAttributes,
+ * }, instance: AvatarGroup) => NdChild} template
+ */
 AvatarGroup.use = function(template) {
     AvatarGroup.defaultTemplate = template;
 };
 
+/**
+ * @param {Avatar[]} items
+ * @returns {this}
+ */
 AvatarGroup.prototype.items = function(items) {
     this.$description.items = items;
     return this;
 };
 
+/**
+ * @param {Avatar} item
+ * @returns {this}
+ */
 AvatarGroup.prototype.item = function(item) {
     this.$description.items.push(item);
     return this;
 };
 
+/**
+ * @param {number} value
+ * @returns {this}
+ */
 AvatarGroup.prototype.overlap = function(value) {
     this.$description.overlap = value;
     return this;
 };
 
+/**
+ * @param {number} max
+ * @returns {this}
+ */
 AvatarGroup.prototype.max = function(max) {
     this.$description.max = max;
     return this;
 };
 
+/**
+ * @param {(count: number) => void} handler
+ * @returns {this}
+ */
 AvatarGroup.prototype.onMoreClick = function(handler) {
     this.$description.onMoreClick = handler;
     return this;

package/src/components/avatar/index.js

@@ -1,7 +1,7 @@
 import Avatar from './Avatar';
-import AvatarGroup from "./AvatarGroup";
+import AvatarGroup from './AvatarGroup';
 
 export {
     Avatar,
     AvatarGroup,
-}
+};

package/src/components/avatar/types/Avatar.d.ts

@@ -0,0 +1,74 @@
+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 AvatarDescription = {
+        src: ObservableItem<string> | null;
+        alt: string | null;
+        name: string | null;
+        initials: string | null;
+        icon: ValidChild | null;
+        size: 'extra-small' | 'small' | 'medium' | 'large' | 'extra-large' | string | number;
+        shape: 'circle' | 'square' | 'rounded';
+        variant: string | null;
+        color: string | null;
+        textColor: string | null;
+        status: ObservableItem<string> | string | null;
+        render: ((desc: AvatarDescription, instance: AvatarInterface) => ValidChild) | null;
+        props: GlobalAttributes;
+    };
+
+export interface AvatarInterface extends BaseComponent {
+    onError(handler: (error: Error, avatar: AvatarInterface) => void): this;
+    src(src: string | ObservableItem<string>): this;
+    alt(alt: string): this;
+    name(name: string): this;
+    initials(initials: string): this;
+    icon(icon: ValidChild): this;
+    size(size: 'extra-small' | 'small' | 'medium' | 'large' | 'extra-large' | string | number): this;
+    extraSmall(): this;
+    small(): this;
+    medium(): this;
+    large(): this;
+    extraLarge(): this;
+    shape(shape: 'circle' | 'square' | 'rounded'): this;
+    circle(): this;
+    square(): this;
+    rounded(): this;
+    variant(variant: string): this;
+    primary(): this;
+    secondary(): this;
+    success(): this;
+    danger(): this;
+    warning(): this;
+    info(): this;
+    color(color: string): this;
+    textColor(color: string): this;
+    status(status: string | ObservableItem<string>): this;
+    statusPosition(position: 'top-leading' | 'top-trailing' | 'bottom-leading' | 'bottom-trailing'): this;
+    statusAtTopLeading(): this;
+    statusAtBottomLeading(): this;
+    statusAtTopTrailing(): this;
+    statusAtBottomTrailing(): this;
+    showStatus(show?: boolean): this;
+    badge(content: ValidChild): this;
+    badgePosition(position: 'top-leading' | 'top-trailing' | 'bottom-leading' | 'bottom-trailing'): this;
+    badgeAtTopLeading(): this;
+    badgeAtBottomLeading(): this;
+    badgeAtTopTrailing(): this;
+    badgeAtBottomTrailing(): this;
+    render(template: (description: AvatarDescription, instance: AvatarInterface) => ValidChild): this;
+}
+
+
+export declare function Avatar(source?: string | ObservableItem<string>, props?: Record<string, unknown>): AvatarInterface;
+export declare namespace Avatar {
+
+
+    function use(template: (description: AvatarDescription, instance: AvatarInterface) => ValidChild): void;
+    function preset(name: string, callback: (instance: AvatarInterface) => AvatarInterface): void;
+    function presets(presets: Record<string, (instance: AvatarInterface) => AvatarInterface>): void;
+
+
+}

package/src/components/avatar/types/AvatarGroup.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 { AvatarInterface } from './Avatar';
+import type { GlobalAttributes } from '../../../../types/globals';
+
+export type AvatarGroupDescription = {
+        items: AvatarInterface[];
+        overlap: number;
+        max: number;
+        onMoreClick: ((count: number) => void) | null;
+        props: GlobalAttributes;
+    };
+
+export interface AvatarGroupInterface extends BaseComponent {
+    items(items: AvatarInterface[]): this;
+    item(item: AvatarInterface): this;
+    overlap(value: number): this;
+    max(max: number): this;
+    onMoreClick(handler: (count: number) => void): this;
+    render(template: (description: AvatarGroupDescription, instance: AvatarGroupInterface) => ValidChild): this;
+}
+
+
+export declare function AvatarGroup(props?: Record<string, unknown>): AvatarGroupInterface;
+export declare namespace AvatarGroup {
+
+
+    function use(template: (description: AvatarGroupDescription, instance: AvatarGroupInterface) => ValidChild): void;
+
+
+}

package/src/components/badge/Badge.js

@@ -1,7 +1,25 @@
-import BaseComponent from "../BaseComponent";
-import DebugManager from "../../core/utils/debug-manager";
-
-
+import BaseComponent from '../BaseComponent';
+import DebugManager from '../../core/utils/debug-manager';
+
+/**
+ * Small label for status, count, or category. Supports variants, shapes (rounded/pill/circle), and appearance (filled/outline/bordered).
+ *
+ *
+ * @example
+ * const badge = new Badge(Span('New'))
+ *     .variant('primary')
+ *     .pill()
+ *     .filled()
+ *     .onClick((e) => console.log('clicked'));
+ *
+ * Badge.use((description, instance) => {
+ *     return Span({ class: \`badge badge--\${description.variant}\` }, description.content);
+ * });
+ *
+ * @constructor
+ * @param {NdChild} content
+ * @param {GlobalAttributes} [props={}]
+ */
 export default function Badge(content, props = {}) {
     if(!(this instanceof Badge)) {
         return new Badge(content, props);
@@ -16,7 +34,7 @@ export default function Badge(content, props = {}) {
         size: 'medium',
         onClick: null,
         content,
-        props
+        props,
     };
 }
 
@@ -24,10 +42,26 @@ BaseComponent.extends(Badge);
 
 Badge.defaultTemplate = null;
 
+/**
+ * Registers the render template for Badge.
+ * @param {(description: {
+ *     appearance: 'filled'|'outline'|'bordered',
+ *     borderRadiusType: 'pill'|'rounded'|'circle'|null,
+ *     variant: string,
+ *     size: 'small'|'medium'|'large'|string,
+ *     onClick: ((event: MouseEvent) => void)|null,
+ *     content: NdChild,
+ *     props: GlobalAttributes,
+ * }, instance: Badge) => NdChild} template
+ */
 Badge.use = function(template) {
     Badge.defaultTemplate = template;
 };
 
+/**
+ * @param {string} name
+ * @param {(b: Badge) => Badge} callback
+ */
 Badge.preset = function(name, callback) {
     if (Badge.prototype[name] || Badge[name]) {
         DebugManager.warn(`Warning: the ${name} method already exists in Badge.`);
@@ -36,89 +70,175 @@ Badge.preset = function(name, callback) {
     Badge[name] = (content, props) => callback(new Badge(content, props));
 };
 
+/**
+ * @param {Record<string, (b: Badge) => Badge>} presets
+ */
 Badge.presets = function(presets) {
     for (const name in presets) {
         Badge.preset(name, presets[name]);
     }
 };
 
+/**
+ * @param {string} variant
+ * @returns {this}
+ */
 Badge.prototype.variant = function(variant) {
     this.$description.variant = variant;
     return this;
 };
+
+/**
+ * @returns {this}
+ */
 Badge.prototype.primary = function() {
     return this.variant('primary');
 };
+
+/**
+ * @returns {this}
+ */
 Badge.prototype.secondary = function() {
     return this.variant('secondary');
 };
+
+/**
+ * @returns {this}
+ */
 Badge.prototype.success = function() {
     return this.variant('success');
 };
+
+/**
+ * @returns {this}
+ */
 Badge.prototype.danger = function() {
     return this.variant('danger');
 };
+
+/**
+ * @returns {this}
+ */
 Badge.prototype.warning = function() {
     return this.variant('warning');
 };
+
+/**
+ * @returns {this}
+ */
 Badge.prototype.info = function() {
     return this.variant('info');
 };
 
+/**
+ * @param {number} size
+ * @returns {this}
+ */
 Badge.prototype.size = function(size) {
     this.$description.size = size;
     return this;
 };
+
+/**
+ * @returns {this}
+ */
 Badge.prototype.small = function() {
     return this.size('small');
 };
+
+/**
+ * @returns {this}
+ */
 Badge.prototype.medium = function() {
     return this.size('medium');
 };
+
+/**
+ * @returns {this}
+ */
 Badge.prototype.large = function() {
     return this.size('large');
 };
 
+/**
+ * @param {string} shape
+ * @returns {this}
+ */
 Badge.prototype.shape = function(shape) {
     this.$description.borderRadiusType = shape;
     return this;
 };
 
+/**
+ * @returns {this}
+ */
 Badge.prototype.rounded = function() {
     this.$description.borderRadiusType = 'rounded';
     return this;
 };
+
+/**
+ * @returns {this}
+ */
 Badge.prototype.pill = function() {
     this.$description.borderRadiusType = 'pill';
     return this;
 };
+
+/**
+ * @returns {this}
+ */
 Badge.prototype.circle = function() {
     this.$description.borderRadiusType = 'circle';
     return this;
 };
 
+/**
+ * @param {string} appearance
+ * @returns {this}
+ */
 Badge.prototype.appearance = function(appearance) {
     this.$description.appearance = appearance;
     return this;
 };
+
+/**
+ * @returns {this}
+ */
 Badge.prototype.outline = function() {
     this.$description.appearance = 'outline';
     return this;
 };
+
+/**
+ * @returns {this}
+ */
 Badge.prototype.filled = function() {
     this.$description.appearance = 'filled';
     return this;
 };
+
+/**
+ * @returns {this}
+ */
 Badge.prototype.bordered = function() {
     this.$description.appearance = 'bordered';
     return this;
 };
 
+/**
+ * @param {NdChild} content
+ * @returns {this}
+ */
 Badge.prototype.content = function(content) {
     this.$description.content = content;
     return this;
 };
 
+/**
+ * @param {Function} handler
+ * @returns {this}
+ */
 Badge.prototype.onClick = function(handler) {
     this.$description.onClick = handler;
     return this;

package/src/components/badge/index.js

@@ -1,6 +1,6 @@
-import Badge from './Badge'
+import Badge from './Badge';
 
 
 export {
-    Badge
+    Badge,
 };

package/src/components/badge/types/Badge.d.ts

@@ -0,0 +1,51 @@
+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 BadgeDescription = {
+        appearance: 'filled' | 'outline' | 'bordered';
+        borderRadiusType: 'pill' | 'rounded' | 'circle' | null;
+        variant: string;
+        size: 'small' | 'medium' | 'large' | string;
+        onClick: ((event: MouseEvent) => void) | null;
+        content: ValidChild;
+        props: GlobalAttributes;
+    };
+
+export interface BadgeInterface extends BaseComponent {
+    variant(variant: string): this;
+    primary(): this;
+    secondary(): this;
+    success(): this;
+    danger(): this;
+    warning(): this;
+    info(): this;
+    size(size: 'small' | 'medium' | 'large' | string): this;
+    small(): this;
+    medium(): this;
+    large(): this;
+    shape(shape: 'rounded' | 'pill' | 'circle'): this;
+    rounded(): this;
+    pill(): this;
+    circle(): this;
+    appearance(appearance: 'filled' | 'outline' | 'bordered'): this;
+    outline(): this;
+    filled(): this;
+    bordered(): this;
+    content(content: ValidChild): this;
+    onClick(handler: (event: MouseEvent) => void): this;
+    render(template: (description: BadgeDescription, instance: BadgeInterface) => ValidChild): this;
+}
+
+
+export declare function Badge(content: ValidChild, props?: Record<string, unknown>): BadgeInterface;
+export declare namespace Badge {
+
+
+    function use(template: (description: BadgeDescription, instance: BadgeInterface) => ValidChild): void;
+    function preset(name: string, callback: (instance: BadgeInterface) => BadgeInterface): void;
+    function presets(presets: Record<string, (instance: BadgeInterface) => BadgeInterface>): void;
+
+
+}