mtrl 0.3.1 → 0.3.2

package/src/components/badge/badge.ts

@@ -18,24 +18,63 @@ import { BadgeConfig, BadgeComponent } from './types';
 import { createBaseConfig, getElementConfig, getApiConfig } from './config';
 
 /**
- * Creates a new Badge component
+ * Creates a new Badge component following Material Design 3 guidelines.
+ * 
+ * The Badge component displays a small circle or numerical indicator to 
+ * draw attention to items requiring user attention, like notifications 
+ * or counts. Badges can be attached to any element.
+ * 
  * @param {BadgeConfig} config - Badge configuration object
- * @returns {BadgeComponent} Badge component instance
+ * @returns {BadgeComponent} Badge component instance with methods for
+ *  managing the badge appearance, content, and visibility
+ * 
+ * @throws {Error} Throws an error if badge creation fails
+ * 
+ * @category Components
  * 
  * @example
- * // Create a small dot badge
+ * // Create a small dot badge (notification indicator)
  * const notificationBadge = createBadge({ 
  *   variant: 'small',
+ *   color: 'error',
  *   target: document.querySelector('.icon-button')
  * });
  * 
  * @example
- * // Create a large badge with a count
+ * // Create a large badge with a count (numbered indicator)
  * const countBadge = createBadge({
  *   variant: 'large',
  *   label: 5,
+ *   color: 'primary',
  *   target: document.querySelector('.notification-icon')
  * });
+ * 
+ * @example
+ * // Create a badge with a maximum value
+ * const messagesBadge = createBadge({
+ *   variant: 'large',
+ *   label: 1250,
+ *   max: 999,  // Will display "999+"
+ *   color: 'info',
+ *   position: 'bottom-right'
+ * });
+ * 
+ * @example
+ * // Control badge visibility programmatically
+ * const toggleBadge = createBadge({
+ *   variant: 'small',
+ *   color: 'success',
+ *   target: document.querySelector('.toggle-button')
+ * });
+ * 
+ * // Toggle badge visibility
+ * function toggleNotification() {
+ *   if (toggleBadge.isVisible()) {
+ *     toggleBadge.hide();
+ *   } else {
+ *     toggleBadge.show();
+ *   }
+ * }
  */
 const createBadge = (config: BadgeConfig = {}): BadgeComponent => {
   const baseConfig = createBaseConfig(config);

package/src/components/badge/config.ts

@@ -7,43 +7,62 @@ import { BadgeConfig } from './types';
 
 /**
  * Maximum character count for badge labels
+ * @category Components
+ * @internal
  */
 export const BADGE_MAX_CHARACTERS = 4;
 
 /**
  * Default configuration for the Badge component
+ * These values will be used when not explicitly specified by the user.
+ * 
+ * @category Components
  */
 export const defaultConfig: BadgeConfig = {
+  /** Default to large badge (with text capability) */
   variant: 'large',
+  /** Default to error (red) color */
   color: 'error',
+  /** Default to top-right corner positioning */
   position: 'top-right',
+  /** Default to empty label */
   label: '',
+  /** Default to visible */
   visible: true
 };
 
 /**
- * Creates the base configuration for Badge component
+ * Creates the base configuration for Badge component by merging user-provided
+ * config with default values.
+ * 
  * @param {BadgeConfig} config - User provided configuration
  * @returns {BadgeConfig} Complete configuration with defaults applied
+ * @category Components
+ * @internal
  */
 export const createBaseConfig = (config: BadgeConfig = {}): BadgeConfig => 
   createComponentConfig(defaultConfig, config, 'badge') as BadgeConfig;
 
 /**
- * Generates element configuration for the Badge component
+ * Generates element configuration for the Badge component.
+ * This function creates the necessary attributes and configuration
+ * for the DOM element creation process.
+ * 
  * @param {BadgeConfig} config - Badge configuration
  * @returns {Object} Element configuration object for withElement
+ * @category Components
+ * @internal
  */
 export const getElementConfig = (config: BadgeConfig) => {
   // Create the attributes object
   const attrs: Record<string, any> = {};
   
-  // For large badges, set appropriate ARIA attributes
+  // For large badges, set appropriate ARIA attributes for screen readers
   if (config.variant !== 'small') {
     attrs.role = 'status';
   }
   
-  // Format the label if needed
+  // Format the label if needed - small badges have no text
   const formattedLabel = config.variant === 'small' 
     ? '' 
     : formatBadgeLabel(config.label || '', config.max);
@@ -57,9 +76,14 @@ export const getElementConfig = (config: BadgeConfig) => {
 };
 
 /**
- * Creates API configuration for the Badge component
+ * Creates API configuration for the Badge component.
+ * This connects the core component features (like visibility)
+ * to the public API methods exposed to users.
+ * 
  * @param {Object} comp - Component with visibility and lifecycle features
  * @returns {Object} API configuration object
+ * @category Components
+ * @internal
  */
 export const getApiConfig = (comp) => ({
   visibility: {
@@ -74,13 +98,21 @@ export const getApiConfig = (comp) => ({
 });
 
 /**
- * Format a label
+ * Format a badge label following Material Design 3 guidelines:
  * - Max 4 characters including "+" for overflow
  * - Add "+" for numeric values exceeding max
  * 
  * @param {string|number} label - Original label
  * @param {number} max - Maximum value before using "+"
- * @returns {string} Formatted label
+ * @returns {string} Formatted label that fits within badge constraints
+ * @category Components
+ * @internal
+ * 
+ * @example
+ * formatBadgeLabel(5) // "5"
+ * formatBadgeLabel(1250, 999) // "999+"
+ * formatBadgeLabel("New") // "New"
+ * formatBadgeLabel("VeryLong") // "Very" (truncated)
  */
 export const formatBadgeLabel = (label: string | number, max?: number): string => {
   // Handle empty or undefined labels
@@ -92,7 +124,7 @@ export const formatBadgeLabel = (label: string | number, max?: number): string =
   
   const numericLabel = Number(label);
 
-  // Apply max value formatting
+  // Apply max value formatting for numbers
   if (max !== undefined && !isNaN(numericLabel) && numericLabel > max) {
     formattedLabel = `${max}+`;
   }

package/src/components/badge/index.ts

@@ -1,29 +1,90 @@
 // src/components/badge/index.ts
+
+/**
+ * Badge component module
+ * @module components/badge
+ * @description A small element that communicates status, shows a count,
+ * or highlights an element requiring attention.
+ */
+
 export { default } from './badge';
-export { BadgeConfig, BadgeComponent, BadgeVariant, BadgeColor, BadgePosition } from './types';
+export type { BadgeConfig, BadgeComponent, BadgeVariant, BadgeColor, BadgePosition } from './types';
 
-// Export common badge constants for convenience and backward compatibility
+/**
+ * Badge size variant constants
+ * Use these instead of string literals for better code completion and type safety.
+ * 
+ * @example
+ * import { createBadge, BADGE_VARIANTS } from 'mtrl';
+ * 
+ * const badge = createBadge({ variant: BADGE_VARIANTS.SMALL });
+ * 
+ * @category Components
+ */
 export const BADGE_VARIANTS = {
+  /** 6dp dot badge (no text content) */
   SMALL: 'small',
+  /** 16dp height badge (can contain text) */
   LARGE: 'large'
 } as const;
 
+/**
+ * Badge color constants
+ * Colors follow Material Design 3 color system.
+ * 
+ * @example
+ * import { createBadge, BADGE_COLORS } from 'mtrl';
+ * 
+ * const badge = createBadge({ color: BADGE_COLORS.ERROR });
+ * 
+ * @category Components
+ */
 export const BADGE_COLORS = {
+  /** Red color for error states */
   ERROR: 'error',
+  /** Primary theme color */
   PRIMARY: 'primary',
+  /** Secondary theme color */
   SECONDARY: 'secondary',
+  /** Tertiary theme color */
   TERTIARY: 'tertiary',
+  /** Green color for success states */
   SUCCESS: 'success',
+  /** Orange/yellow color for warning states */
   WARNING: 'warning',
+  /** Blue color for information states */
   INFO: 'info'
 } as const;
 
+/**
+ * Badge position constants
+ * Defines where the badge appears relative to its target element.
+ * 
+ * @example
+ * import { createBadge, BADGE_POSITIONS } from 'mtrl';
+ * 
+ * const badge = createBadge({ 
+ *   position: BADGE_POSITIONS.BOTTOM_RIGHT,
+ *   target: document.querySelector('#notification-bell')
+ * });
+ * 
+ * @category Components
+ */
 export const BADGE_POSITIONS = {
+  /** Position in the top-right corner (default) */
   TOP_RIGHT: 'top-right',
+  /** Position in the top-left corner */
   TOP_LEFT: 'top-left',
+  /** Position in the bottom-right corner */
   BOTTOM_RIGHT: 'bottom-right',
+  /** Position in the bottom-left corner */
   BOTTOM_LEFT: 'bottom-left'
 } as const;
 
-// Export max characters constant
+/**
+ * Maximum number of characters to display in a badge
+ * When label text exceeds this length, it will be truncated.
+ * 
+ * @category Components
+ */
 export const BADGE_MAX_CHARACTERS = 4;

package/src/components/badge/types.ts

@@ -1,137 +1,279 @@
 // src/components/badge/types.ts
 
 /**
- * Badge variant types
+ * Badge variant types - determines the badge size and appearance
  * @category Components
+ * @remarks
+ * - small: A 6dp circular dot badge without text (for notification indicators)
+ * - large: A 16dp height badge that can contain text (for counts or short labels)
  */
 export type BadgeVariant = 'small' | 'large';
 
 /**
- * Badge color types
+ * Badge color types - determines the badge's background color
  * @category Components
+ * @remarks
+ * Based on Material Design 3 color system:
+ * - error: Red color for error states (default)
+ * - primary: Primary theme color
+ * - secondary: Secondary theme color
+ * - tertiary: Tertiary theme color
+ * - success: Green color for success states
+ * - warning: Orange/yellow color for warning states
+ * - info: Blue color for information states
  */
 export type BadgeColor = 'error' | 'primary' | 'secondary' | 'tertiary' | 'success' | 'warning' | 'info';
 
 /**
- * Badge position types
+ * Badge position types - determines where the badge appears relative to its target
  * @category Components
+ * @remarks
+ * - top-right: Position in the top-right corner (default)
+ * - top-left: Position in the top-left corner
+ * - bottom-right: Position in the bottom-right corner
+ * - bottom-left: Position in the bottom-left corner
  */
 export type BadgePosition = 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left';
 
 /**
  * Configuration interface for the Badge component
- * Following Material Design 3 specifications
+ * @category Components
+ * @description
+ * Defines the appearance and behavior of a badge component.
+ * All properties are optional with sensible defaults.
  */
 export interface BadgeConfig {
   /** 
    * Badge variant (small dot or large numbered)
    * Small badge (6dp) or Large badge (16dp height)
    * @default 'large'
+   * @example 'small' | 'large'
    */
   variant?: BadgeVariant | string;
   
   /** 
-   * Badge color (error is default)
+   * Badge color (follows Material Design 3 color system)
    * @default 'error'
+   * @example 'error' | 'primary' | 'secondary' | 'tertiary' | 'success' | 'warning' | 'info'
    */
   color?: BadgeColor | string;
   
   /** 
-   * Badge position relative to its container
+   * Badge position relative to its container element
    * @default 'top-right' 
+   * @example 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left'
    */
   position?: BadgePosition | string;
   
   /** 
    * Text label inside the badge (for large badges)
-   * Up to 4 characters, with "+" for overflow 
+   * Up to 4 characters, numbers exceeding max will show "{max}+"
+   * @example "3" | "99+" | "New"
    */
   label?: string | number;
   
   /** 
    * Maximum value to display (shows "{max}+" if label exceeds max)
    * Usually 999+ for large numbers
+   * @example 99 | 999
    */
   max?: number;
   
-  /** Whether the badge should be visible */
+  /** 
+   * Whether the badge should be initially visible
+   * @default true
+   */
   visible?: boolean;
   
-  /** Target element to which badge will be attached */
+  /** 
+   * Target element to which badge will be attached
+   * When provided, the badge will be positioned relative to this element
+   */
   target?: HTMLElement;
   
-  /** Additional CSS classes */
+  /** 
+   * Additional CSS classes to apply to the badge element
+   * @example "custom-badge highlighted-badge"
+   */
   class?: string;
   
-  /** CSS class prefix */
+  /** 
+   * CSS class prefix for all badge classes
+   * @default "mtrl"
+   */
   prefix?: string;
   
-  /** Component name */
+  /** 
+   * Component name used in CSS class generation
+   * @default "badge"
+   * @internal
+   */
   componentName?: string;
 }
 
 /**
  * Badge component interface
- * Following Material Design 3 specifications
+ * Provides methods for controlling a Material Design 3 badge
+ * 
+ * @category Components
  */
 export interface BadgeComponent {
-  /** Badge element */
+  /** 
+   * The badge's root DOM element
+   */
   element: HTMLElement;
   
-  /** Badge wrapper element (if badge is attached to target) */
+  /** 
+   * Badge wrapper element (if badge is attached to target)
+   * This is the parent element that contains both the target and the badge
+   */
   wrapper?: HTMLElement;
   
-  /** Sets badge text label */
+  /**
+   * Sets the badge's text label
+   * @param label - Text or number to display in the badge
+   * @returns Badge component for method chaining
+   * @example
+   * badge.setLabel(5); // Shows "5"
+   * badge.setLabel("New"); // Shows "New"
+   * badge.setLabel(1250); // With max=999, shows "999+"
+   */
   setLabel: (label: string | number) => BadgeComponent;
   
-  /** Gets badge text label */
+  /**
+   * Gets the badge's current text label
+   * @returns Current text content of the badge
+   */
   getLabel: () => string;
   
-  /** Shows the badge */
+  /**
+   * Shows the badge (makes it visible)
+   * @returns Badge component for method chaining
+   */
   show: () => BadgeComponent;
   
-  /** Hides the badge */
+  /**
+   * Hides the badge (makes it invisible)
+   * @returns Badge component for method chaining
+   */
   hide: () => BadgeComponent;
   
-  /** Toggles badge visibility */
+  /**
+   * Toggles badge visibility
+   * @param visible - Optional explicit visibility state
+   * @returns Badge component for method chaining
+   * @example
+   * badge.toggle(); // Toggles current state
+   * badge.toggle(true); // Forces visible
+   */
   toggle: (visible?: boolean) => BadgeComponent;
   
-  /** Checks if the badge is visible */
+  /**
+   * Checks if the badge is currently visible
+   * @returns True if badge is visible, false otherwise
+   */
   isVisible: () => boolean;
   
-  /** Sets maximum value (after which badge shows max+) */
+  /**
+   * Sets maximum value (after which badge shows max+)
+   * @param max - Maximum number to display before showing "+"
+   * @returns Badge component for method chaining
+   * @example
+   * badge.setMax(99); // Shows "99+" for values > 99
+   */
   setMax: (max: number) => BadgeComponent;
   
-  /** Sets badge color */
+  /**
+   * Sets badge color
+   * @param color - Badge color from Material Design 3 palette
+   * @returns Badge component for method chaining
+   * @example
+   * badge.setColor('primary');
+   * badge.setColor(BADGE_COLORS.SUCCESS);
+   */
   setColor: (color: BadgeColor | string) => BadgeComponent;
   
-  /** Sets badge variant */
+  /**
+   * Sets badge variant (size style)
+   * @param variant - Badge variant ('small' or 'large')
+   * @returns Badge component for method chaining
+   * @example
+   * badge.setVariant('small'); // Dot indicator
+   * badge.setVariant(BADGE_VARIANTS.LARGE); // Numbered indicator
+   */
   setVariant: (variant: BadgeVariant | string) => BadgeComponent;
   
-  /** Sets badge position */
+  /**
+   * Sets badge position relative to target
+   * @param position - Badge position
+   * @returns Badge component for method chaining
+   * @example
+   * badge.setPosition('bottom-left');
+   */
   setPosition: (position: BadgePosition | string) => BadgeComponent;
   
-  /** Attaches badge to a target element */
+  /**
+   * Attaches badge to a target element
+   * @param target - Element to attach badge to
+   * @returns Badge component for method chaining
+   * @example
+   * badge.attachTo(document.querySelector('#notification-bell'));
+   */
   attachTo: (target: HTMLElement) => BadgeComponent;
   
-  /** Makes badge standalone (removes from wrapper) */
+  /**
+   * Makes badge standalone (removes from wrapper)
+   * @returns Badge component for method chaining
+   */
   detach: () => BadgeComponent;
   
-  /** Destroys the badge component and cleans up resources */
+  /**
+   * Destroys the badge component and cleans up resources
+   * Removes the badge from the DOM and clears event listeners
+   */
   destroy: () => void;
   
-  /** Gets the class with the specified name */
+  /**
+   * Gets a class name with the component's prefix
+   * @param name - Base class name
+   * @returns Prefixed class name
+   * @internal
+   */
   getClass: (name: string) => string;
   
-  /** Add CSS classes */
+  /**
+   * Adds CSS classes to the badge element
+   * @param classes - One or more class names to add
+   * @returns Badge component for method chaining
+   * @example
+   * badge.addClass('highlighted', 'animated');
+   */
   addClass: (...classes: string[]) => BadgeComponent;
   
-  /** Remove CSS classes */
+  /**
+   * Removes CSS classes from the badge element
+   * @param classes - One or more class names to remove
+   * @returns Badge component for method chaining
+   * @example
+   * badge.removeClass('highlighted', 'animated');
+   */
   removeClass: (...classes: string[]) => BadgeComponent;
   
-  /** Add event listener */
+  /**
+   * Adds an event listener to the badge
+   * @param event - Event name ('click', 'mouseover', etc.)
+   * @param handler - Event handler function
+   * @returns Badge component for method chaining
+   * @example
+   * badge.on('click', () => console.log('Badge clicked'));
+   */
   on: (event: string, handler: Function) => BadgeComponent;
   
-  /** Remove event listener */
+  /**
+   * Removes an event listener from the badge
+   * @param event - Event name
+   * @param handler - Event handler function
+   * @returns Badge component for method chaining
+   */
   off: (event: string, handler: Function) => BadgeComponent;
 }