mtrl 0.2.7 → 0.2.9

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

@@ -1,29 +1,11 @@
 // src/components/datepicker/api.ts
-import { DatePickerComponent } from './types';
+import { DatePickerComponent, ApiOptions } from './types';
 import { 
   formatDate, 
   parseDate,
-  isSameDay,
-  generateCalendarDates,
   addMonths,
   addYears 
 } from './utils';
-import { DATEPICKER_VIEWS, DATEPICKER_SELECTION_MODES } from './constants';
-
-interface ApiOptions {
-  disabled: {
-    enable: () => void;
-    disable: () => void;
-  };
-  lifecycle: {
-    destroy: () => void;
-  };
-  events: {
-    on: (event: string, handler: Function) => any;
-    off: (event: string, handler: Function) => any;
-    emit: (event: string, data: any) => any;
-  };
-}
 
 /**
  * Enhances a datepicker component with API methods
@@ -80,17 +62,17 @@ export const withAPI = (state: any, { disabled, lifecycle, events }: ApiOptions)
       },
       
       showDayView(): void {
-        state.currentView = DATEPICKER_VIEWS.DAY;
+        state.currentView = 'day';
         state.updateCalendar();
       },
       
       showMonthView(): void {
-        state.currentView = DATEPICKER_VIEWS.MONTH;
+        state.currentView = 'month';
         state.updateCalendar();
       },
       
       showYearView(): void {
-        state.currentView = DATEPICKER_VIEWS.YEAR;
+        state.currentView = 'year';
         state.updateCalendar();
       },
       
@@ -123,7 +105,7 @@ export const withAPI = (state: any, { disabled, lifecycle, events }: ApiOptions)
         if (!state.selectedDate) return null;
         
         // Range selection
-        if (state.selectionMode === DATEPICKER_SELECTION_MODES.RANGE && state.rangeEndDate) {
+        if (state.selectionMode === 'range' && state.rangeEndDate) {
           return [new Date(state.selectedDate), new Date(state.rangeEndDate)];
         }
         
@@ -133,7 +115,7 @@ export const withAPI = (state: any, { disabled, lifecycle, events }: ApiOptions)
       
       setValue(value: Date | string | [Date | string, Date | string]): DatePickerComponent {
         // Handle range selection
-        if (Array.isArray(value) && state.selectionMode === DATEPICKER_SELECTION_MODES.RANGE) {
+        if (Array.isArray(value) && state.selectionMode === 'range') {
           const start = parseDate(value[0]);
           const end = parseDate(value[1]);
           
@@ -196,7 +178,7 @@ export const withAPI = (state: any, { disabled, lifecycle, events }: ApiOptions)
         if (!state.selectedDate) return '';
         
         // Range selection
-        if (state.selectionMode === DATEPICKER_SELECTION_MODES.RANGE && state.rangeEndDate) {
+        if (state.selectionMode === 'range' && state.rangeEndDate) {
           const startStr = formatDate(state.selectedDate, state.dateFormat);
           const endStr = formatDate(state.rangeEndDate, state.dateFormat);
           return `${startStr} - ${endStr}`;
@@ -221,11 +203,13 @@ export const withAPI = (state: any, { disabled, lifecycle, events }: ApiOptions)
       
       enable(): DatePickerComponent {
         disabled.enable();
+        state.input.disabled = false;
         return this;
       },
       
       disable(): DatePickerComponent {
         disabled.disable();
+        state.input.disabled = true;
         return this;
       },
       
@@ -256,6 +240,15 @@ export const withAPI = (state: any, { disabled, lifecycle, events }: ApiOptions)
       },
       
       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();
       },
       

package/src/components/datepicker/config.ts

@@ -4,21 +4,18 @@ import {
   createElementConfig,
   BaseComponentConfig 
 } from '../../core/config/component-config';
-import { DatePickerConfig } from './types';
 import { 
-  DATEPICKER_VARIANTS, 
-  DATEPICKER_VIEWS, 
-  DATEPICKER_SELECTION_MODES,
-  DEFAULT_DATE_FORMAT
-} from './constants';
+  DatePickerConfig, 
+  DEFAULT_DATE_FORMAT 
+} from './types';
 
 /**
  * Default configuration for the DatePicker component
  */
 export const defaultConfig: DatePickerConfig = {
-  variant: DATEPICKER_VARIANTS.DOCKED,
-  initialView: DATEPICKER_VIEWS.DAY,
-  selectionMode: DATEPICKER_SELECTION_MODES.SINGLE,
+  variant: 'docked',
+  initialView: 'day',
+  selectionMode: 'single',
   dateFormat: DEFAULT_DATE_FORMAT,
   animate: true
 };
@@ -33,7 +30,7 @@ export const createBaseConfig = (config: DatePickerConfig = {}): DatePickerConfi
   
   // Set closeOnSelect default based on variant
   if (baseConfig.closeOnSelect === undefined) {
-    baseConfig.closeOnSelect = baseConfig.variant !== DATEPICKER_VARIANTS.DOCKED;
+    baseConfig.closeOnSelect = baseConfig.variant !== 'docked';
   }
   
   return baseConfig;
@@ -106,12 +103,12 @@ export const getCalendarConfig = (config: DatePickerConfig) => {
     tag: 'div',
     attrs: {
       role: 'dialog',
-      'aria-modal': config.variant !== DATEPICKER_VARIANTS.DOCKED ? 'true' : 'false'
+      'aria-modal': config.variant !== 'docked' ? 'true' : 'false'
     },
     className: [
       `${config.prefix}-datepicker-calendar`,
       `${config.prefix}-datepicker-${config.variant}`,
-      config.selectionMode === DATEPICKER_SELECTION_MODES.RANGE ? 
+      config.selectionMode === 'range' ? 
         `${config.prefix}-datepicker-range` : ''
     ],
     forwardEvents: {

package/src/components/datepicker/datepicker.ts

@@ -9,12 +9,7 @@ import {
 } from '../../core/compose/features';
 
 import { withAPI } from './api';
-import { DatePickerConfig } from './types';
-import { 
-  DATEPICKER_VARIANTS, 
-  DATEPICKER_VIEWS, 
-  DATEPICKER_SELECTION_MODES 
-} from './constants';
+import { DatePickerConfig, DatePickerComponent } from './types';
 import { 
   createBaseConfig, 
   getContainerConfig, 
@@ -37,7 +32,7 @@ import { createElement } from '../../core/dom/create';
  * @param {DatePickerConfig} config - DatePicker configuration object
  * @returns {DatePickerComponent} DatePicker component instance
  */
-const createDatePicker = (config: DatePickerConfig = {}) => {
+const createDatePicker = (config: DatePickerConfig = {}): DatePickerComponent => {
   const baseConfig = createBaseConfig(config);
 
   try {
@@ -68,7 +63,7 @@ const createDatePicker = (config: DatePickerConfig = {}) => {
         }
         
         // Format for range selection
-        if (this.selectionMode === DATEPICKER_SELECTION_MODES.RANGE && this.rangeEndDate) {
+        if (this.selectionMode === 'range' && this.rangeEndDate) {
           const startStr = formatDate(this.selectedDate, this.dateFormat);
           const endStr = formatDate(this.rangeEndDate, this.dateFormat);
           this.input.value = `${startStr} - ${endStr}`;
@@ -94,13 +89,13 @@ const createDatePicker = (config: DatePickerConfig = {}) => {
               
             case 'monthSelected':
               this.currentMonth = data.month;
-              this.currentView = DATEPICKER_VIEWS.DAY;
+              this.currentView = 'day';
               this.updateCalendar();
               break;
               
             case 'yearSelected':
               this.currentYear = data.year;
-              this.currentView = DATEPICKER_VIEWS.MONTH;
+              this.currentView = 'month';
               this.updateCalendar();
               break;
               
@@ -152,7 +147,7 @@ const createDatePicker = (config: DatePickerConfig = {}) => {
       
       handleDateSelection(date: Date): void {
         // Range selection
-        if (this.selectionMode === DATEPICKER_SELECTION_MODES.RANGE) {
+        if (this.selectionMode === 'range') {
           // If no date is selected yet or both dates are already selected, start a new range
           if (!this.selectedDate || (this.selectedDate && this.rangeEndDate)) {
             this.selectedDate = date;
@@ -248,7 +243,7 @@ const createDatePicker = (config: DatePickerConfig = {}) => {
     
     // Initialize with provided value if any
     if (baseConfig.value) {
-      if (Array.isArray(baseConfig.value) && baseConfig.selectionMode === DATEPICKER_SELECTION_MODES.RANGE) {
+      if (Array.isArray(baseConfig.value) && baseConfig.selectionMode === 'range') {
         const start = parseDate(baseConfig.value[0]);
         const end = parseDate(baseConfig.value[1]);
         

package/src/components/datepicker/index.ts

@@ -1,9 +1,12 @@
 // src/components/datepicker/index.ts
 export { default } from './datepicker'
-export {
-  DATEPICKER_VARIANTS,
-  DATEPICKER_VIEWS,
-  DATEPICKER_SELECTION_MODES,
-  DEFAULT_DATE_FORMAT
-} from './constants'
-export { DatePickerConfig, DatePickerComponent } from './types'
+export type { 
+  DatePickerConfig, 
+  DatePickerComponent,
+  DatePickerVariant,
+  DatePickerView,
+  DatePickerSelectionMode
+} from './types'
+export { 
+  DEFAULT_DATE_FORMAT 
+} from './types'