mtrl 0.2.6 → 0.2.8

package/src/components/chip/types.ts

@@ -1,142 +1,330 @@
 // src/components/chip/types.ts
-import { CHIP_VARIANTS } from './constants';
+
+/**
+ * Chip variant types
+ * @category Components
+ */
+export type ChipVariant = 'filled' | 'outlined' | 'elevated' | 'assist' | 'filter' | 'input' | 'suggestion';
 
 /**
  * Configuration interface for the Chip component
+ * @category Components
  */
 export interface ChipConfig {
-  /** Chip variant (filled, outlined, elevated, assist, filter, input, suggestion) */
-  variant?: keyof typeof CHIP_VARIANTS | string;
+  /** 
+   * Chip variant that determines visual styling
+   * @default 'filled'
+   */
+  variant?: ChipVariant | string;
   
-  /** Whether the chip is initially disabled */
+  /** 
+   * Whether the chip is initially disabled
+   * @default false
+   */
   disabled?: boolean;
   
-  /** Whether the chip is initially selected */
+  /** 
+   * Whether the chip is initially selected
+   * @default false
+   */
   selected?: boolean;
   
-  /** Initial chip text content */
+  /** 
+   * Initial chip text content
+   * @example 'Category'
+   */
   text?: string;
   
-  /** Initial chip icon HTML content */
+  /** 
+   * Initial chip icon HTML content (alias for leadingIcon)
+   * @example '<svg>...</svg>'
+   */
   icon?: string;
   
-  /** Optional leading icon HTML content */
+  /** 
+   * Leading icon HTML content
+   * @example '<svg>...</svg>'
+   */
   leadingIcon?: string;
   
-  /** Optional trailing icon HTML content */
+  /** 
+   * Trailing icon HTML content
+   * @example '<svg>...</svg>'
+   */
   trailingIcon?: string;
   
-  /** Additional CSS classes */
+  /** 
+   * Additional CSS classes to add to the chip
+   * @example 'filter-tag category-item'
+   */
   class?: string;
   
-  /** Chip value attribute */
+  /** 
+   * Chip value attribute for identification
+   */
   value?: string;
   
-  /** Whether to enable ripple effect */
+  /** 
+   * Whether to enable ripple effect
+   * @default true
+   */
   ripple?: boolean;
+
+  /**
+   * Component prefix for class names
+   * @default 'mtrl'
+   */
+  prefix?: string;
+  
+  /**
+   * Component name used in class generation
+   */
+  componentName?: string;
   
-  /** Ripple effect configuration */
+  /** 
+   * Ripple effect configuration
+   */
   rippleConfig?: {
+    /** Duration of the ripple animation in milliseconds */
     duration?: number;
+    /** Timing function for the ripple animation */
     timing?: string;
+    /** Opacity values for ripple start and end [start, end] */
     opacity?: [string, string];
   };
   
-  /** Function called when the trailing icon is clicked */
+  /**
+   * Flag to make any chip variant selectable
+   * @default false
+   */
+  selectable?: boolean;
+  
+  /**
+   * Function called when the trailing icon is clicked
+   */
   onTrailingIconClick?: (chip: ChipComponent) => void;
   
-  /** Function called when the chip is selected */
+  /**
+   * Function called when the chip is selected
+   */
   onSelect?: (chip: ChipComponent) => void;
+  
+  /**
+   * Function called when the chip selection changes
+   */
+  onChange?: (chip: ChipComponent) => void;
 }
 
 /**
- * Icon API interface
+ * Icon API interface for managing chip icons
+ * @category Components
  */
 export interface IconAPI {
+  /**
+   * Sets the icon HTML content
+   * @param html - HTML string for the icon
+   * @returns The icon API for chaining
+   */
   setIcon: (html: string) => IconAPI;
+  
+  /**
+   * Gets the current icon HTML content
+   * @returns HTML string for the icon
+   */
   getIcon: () => string;
+  
+  /**
+   * Gets the icon DOM element
+   * @returns The icon element or null if not present
+   */
   getElement: () => HTMLElement | null;
 }
 
 /**
- * Text API interface
+ * Text API interface for managing chip text
+ * @category Components
  */
 export interface TextAPI {
+  /**
+   * Sets the text content
+   * @param content - Text content
+   * @returns The text API for chaining
+   */
   setText: (content: string) => TextAPI;
+  
+  /**
+   * Gets the current text content
+   * @returns Chip text content
+   */
   getText: () => string;
+  
+  /**
+   * Gets the text DOM element
+   * @returns The text element or null if not present
+   */
   getElement: () => HTMLElement | null;
 }
 
 /**
  * Chip component interface
+ * @category Components
  */
 export interface ChipComponent {
+  /** The chip's DOM element */
   element: HTMLElement;
+  
+  /** API for managing chip text */
   text: TextAPI;
+  
+  /** API for managing chip icons */
   icon: IconAPI;
+  
+  /** API for managing disabled state */
   disabled: {
+    /** Enables the chip */
     enable: () => void;
+    /** Disables the chip */
     disable: () => void;
+    /** Checks if the chip is disabled */
     isDisabled: () => boolean;
   };
+  
+  /** API for managing component lifecycle */
   lifecycle: {
+    /** Destroys the component and cleans up resources */
     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
+   */
   getClass: (name: string) => string;
   
-  /** Gets the chip's value */
+  /**
+   * Gets the chip's value attribute
+   * @returns Chip value
+   */
   getValue: () => string | null;
   
-  /** Sets the chip's value */
+  /**
+   * Sets the chip's value attribute
+   * @param value - New value
+   * @returns The chip component for chaining
+   */
   setValue: (value: string) => ChipComponent;
   
-  /** Enables the chip */
+  /**
+   * Enables the chip (removes disabled attribute)
+   * @returns The chip component for chaining
+   */
   enable: () => ChipComponent;
   
-  /** Disables the chip */
+  /**
+   * Disables the chip (adds disabled attribute)
+   * @returns The chip component for chaining
+   */
   disable: () => ChipComponent;
   
-  /** Sets the chip's text content */
+  /**
+   * Checks if the chip is disabled
+   * @returns True if the chip is disabled
+   */
+  isDisabled: () => boolean;
+  
+  /**
+   * Sets the chip's text content
+   * @param content - Text content
+   * @returns The chip component for chaining
+   */
   setText: (content: string) => ChipComponent;
   
-  /** Gets the chip's text content */
+  /**
+   * Gets the chip's text content
+   * @returns Chip text content
+   */
   getText: () => string;
   
-  /** Sets the chip's icon */
+  /**
+   * Sets the chip's icon (alias for setLeadingIcon)
+   * @param icon - Icon HTML content
+   * @returns The chip component for chaining
+   */
   setIcon: (icon: string) => ChipComponent;
   
-  /** Gets the chip's icon */
+  /**
+   * Gets the chip's icon HTML content
+   * @returns Icon HTML
+   */
   getIcon: () => string;
   
-  /** Sets the chip's trailing icon */
-  setTrailingIcon: (icon: string) => ChipComponent;
+  /**
+   * Sets the chip's leading icon
+   * @param icon - Icon HTML content
+   * @returns The chip component for chaining
+   */
+  setLeadingIcon: (icon: string) => ChipComponent;
+  
+  /**
+   * Sets the chip's trailing icon
+   * @param icon - Icon HTML content
+   * @param onClick - Optional click handler for the trailing icon
+   * @returns The chip component for chaining
+   */
+  setTrailingIcon: (icon: string, onClick?: (chip: ChipComponent) => void) => ChipComponent;
   
-  /** Checks if the chip is selected */
+  /**
+   * Checks if the chip is selected
+   * @returns True if the chip is selected
+   */
   isSelected: () => boolean;
   
-  /** Sets the chip's selected state */
+  /**
+   * Sets the chip's selected state
+   * @param selected - Whether the chip should be selected
+   * @returns The chip component for chaining
+   */
   setSelected: (selected: boolean) => ChipComponent;
   
-  /** Toggles the chip's selected state */
+  /**
+   * Toggles the chip's selected state
+   * @returns The chip component for chaining
+   */
   toggleSelected: () => ChipComponent;
   
-  /** Destroys the chip component and cleans up resources */
+  /**
+   * Destroys the chip component and cleans up resources
+   */
   destroy: () => void;
   
-  /** Adds event listener */
+  /**
+   * Adds an event listener to the chip
+   * @param event - Event name ('click', 'focus', etc.)
+   * @param handler - Event handler function
+   * @returns The chip component for chaining
+   */
   on: (event: string, handler: Function) => ChipComponent;
   
-  /** Removes event listener */
+  /**
+   * Removes an event listener from the chip
+   * @param event - Event name
+   * @param handler - Event handler function
+   * @returns The chip component for chaining
+   */
   off: (event: string, handler: Function) => ChipComponent;
   
-  /** Add CSS classes */
+  /**
+   * Adds CSS classes to the chip element
+   * @param classes - One or more class names to add
+   * @returns The chip component for chaining
+   */
   addClass: (...classes: string[]) => ChipComponent;
 }
 
 /**
  * API options interface
+ * @internal
  */
 export interface ApiOptions {
   disabled: {
@@ -150,6 +338,7 @@ export interface ApiOptions {
 
 /**
  * Base component interface
+ * @internal
  */
 export interface BaseComponent {
   element: HTMLElement;

package/src/components/datepicker/api.ts

@@ -0,0 +1,265 @@
+// src/components/datepicker/api.ts
+import { DatePickerComponent, ApiOptions } from './types';
+import { 
+  formatDate, 
+  parseDate,
+  addMonths,
+  addYears 
+} from './utils';
+
+/**
+ * Enhances a datepicker component with API methods
+ * @param {object} state - Current state of the datepicker
+ * @param {ApiOptions} options - API configuration options
+ * @returns {Function} Higher-order function that adds API methods to component
+ * @internal This is an internal utility for the DatePicker component
+ */
+export const withAPI = (state: any, { disabled, lifecycle, events }: ApiOptions) => 
+  (component: any): DatePickerComponent => {
+    // Calendar navigation API
+    const calendar = {
+      goToDate(date: Date): void {
+        const validDate = parseDate(date);
+        if (!validDate) return;
+        
+        state.currentMonth = validDate.getMonth();
+        state.currentYear = validDate.getFullYear();
+        
+        // Update calendar view
+        state.updateCalendar();
+      },
+      
+      nextMonth(): void {
+        const newDate = addMonths(new Date(state.currentYear, state.currentMonth, 1), 1);
+        state.currentMonth = newDate.getMonth();
+        state.currentYear = newDate.getFullYear();
+        
+        // Update calendar view
+        state.updateCalendar();
+      },
+      
+      prevMonth(): void {
+        const newDate = addMonths(new Date(state.currentYear, state.currentMonth, 1), -1);
+        state.currentMonth = newDate.getMonth();
+        state.currentYear = newDate.getFullYear();
+        
+        // Update calendar view
+        state.updateCalendar();
+      },
+      
+      nextYear(): void {
+        state.currentYear += 1;
+        
+        // Update calendar view
+        state.updateCalendar();
+      },
+      
+      prevYear(): void {
+        state.currentYear -= 1;
+        
+        // Update calendar view
+        state.updateCalendar();
+      },
+      
+      showDayView(): void {
+        state.currentView = 'day';
+        state.updateCalendar();
+      },
+      
+      showMonthView(): void {
+        state.currentView = 'month';
+        state.updateCalendar();
+      },
+      
+      showYearView(): void {
+        state.currentView = 'year';
+        state.updateCalendar();
+      },
+      
+      getCurrentView(): string {
+        return state.currentView;
+      }
+    };
+    
+    return {
+      ...component as any,
+      element: component.element,
+      input: state.input,
+      calendar,
+      
+      open(): DatePickerComponent {
+        state.isOpen = true;
+        state.render();
+        events.emit('open', { value: this.getValue() });
+        return this;
+      },
+      
+      close(): DatePickerComponent {
+        state.isOpen = false;
+        state.render();
+        events.emit('close', { value: this.getValue() });
+        return this;
+      },
+      
+      getValue(): Date | [Date, Date] | null {
+        if (!state.selectedDate) return null;
+        
+        // Range selection
+        if (state.selectionMode === 'range' && state.rangeEndDate) {
+          return [new Date(state.selectedDate), new Date(state.rangeEndDate)];
+        }
+        
+        // Single selection
+        return new Date(state.selectedDate);
+      },
+      
+      setValue(value: Date | string | [Date | string, Date | string]): DatePickerComponent {
+        // Handle range selection
+        if (Array.isArray(value) && state.selectionMode === 'range') {
+          const start = parseDate(value[0]);
+          const end = parseDate(value[1]);
+          
+          if (start && end) {
+            state.selectedDate = start;
+            state.rangeEndDate = end;
+            
+            // Ensure start date is before end date
+            if (start > end) {
+              state.selectedDate = end;
+              state.rangeEndDate = start;
+            }
+            
+            // Update input value
+            state.updateInputValue();
+            
+            // Update calendar if it's open
+            if (state.isOpen) {
+              // Set current month/year to the start date's month/year
+              state.currentMonth = state.selectedDate.getMonth();
+              state.currentYear = state.selectedDate.getFullYear();
+              state.updateCalendar();
+            }
+            
+            events.emit('change', { 
+              value: this.getValue(), 
+              formattedValue: this.getFormattedValue() 
+            });
+          }
+          
+          return this;
+        }
+        
+        // Handle single date selection
+        const parsedDate = parseDate(value as Date | string);
+        if (parsedDate) {
+          state.selectedDate = parsedDate;
+          state.rangeEndDate = null;
+          
+          // Update input value
+          state.updateInputValue();
+          
+          // Update calendar if it's open
+          if (state.isOpen) {
+            state.currentMonth = parsedDate.getMonth();
+            state.currentYear = parsedDate.getFullYear();
+            state.updateCalendar();
+          }
+          
+          events.emit('change', { 
+            value: this.getValue(), 
+            formattedValue: this.getFormattedValue() 
+          });
+        }
+        
+        return this;
+      },
+      
+      getFormattedValue(): string {
+        if (!state.selectedDate) return '';
+        
+        // Range selection
+        if (state.selectionMode === 'range' && state.rangeEndDate) {
+          const startStr = formatDate(state.selectedDate, state.dateFormat);
+          const endStr = formatDate(state.rangeEndDate, state.dateFormat);
+          return `${startStr} - ${endStr}`;
+        }
+        
+        // Single selection
+        return formatDate(state.selectedDate, state.dateFormat);
+      },
+      
+      clear(): DatePickerComponent {
+        state.selectedDate = null;
+        state.rangeEndDate = null;
+        state.updateInputValue();
+        
+        if (state.isOpen) {
+          state.updateCalendar();
+        }
+        
+        events.emit('change', { value: null, formattedValue: '' });
+        return this;
+      },
+      
+      enable(): DatePickerComponent {
+        disabled.enable();
+        state.input.disabled = false;
+        return this;
+      },
+      
+      disable(): DatePickerComponent {
+        disabled.disable();
+        state.input.disabled = true;
+        return this;
+      },
+      
+      setMinDate(date: Date | string): DatePickerComponent {
+        const parsedDate = parseDate(date);
+        if (parsedDate) {
+          state.minDate = parsedDate;
+          
+          // Update calendar if it's open
+          if (state.isOpen) {
+            state.updateCalendar();
+          }
+        }
+        return this;
+      },
+      
+      setMaxDate(date: Date | string): DatePickerComponent {
+        const parsedDate = parseDate(date);
+        if (parsedDate) {
+          state.maxDate = parsedDate;
+          
+          // Update calendar if it's open
+          if (state.isOpen) {
+            state.updateCalendar();
+          }
+        }
+        return this;
+      },
+      
+      destroy(): void {
+        // Clean up event listeners
+        document.removeEventListener('click', state.outsideClickHandler);
+        
+        // Remove DOM elements
+        if (state.calendarElement && state.calendarElement.parentNode) {
+          state.calendarElement.parentNode.removeChild(state.calendarElement);
+        }
+        
+        // Call the lifecycle destroy method
+        lifecycle.destroy();
+      },
+      
+      on(event: string, handler: Function): DatePickerComponent {
+        events.on(event, handler);
+        return this;
+      },
+      
+      off(event: string, handler: Function): DatePickerComponent {
+        events.off(event, handler);
+        return this;
+      }
+    };
+  };