mtrl 0.2.7 → 0.2.9

package/src/components/progress/types.ts

@@ -1,102 +1,255 @@
 // src/components/progress/types.ts
-import { PROGRESS_VARIANTS } from './constants';
+
+/**
+ * Progress variant types
+ * @category Components
+ */
+export type ProgressVariant = 'linear' | 'circular';
+
+/**
+ * Progress component event types
+ * @category Components
+ */
+export type ProgressEvent = 'change' | 'complete';
+
+// /**
+//  * Progress variants object for internal reference
+//  * @internal
+//  */
+// export const PROGRESS_VARIANTS: Record<string, ProgressVariant> = {
+//   LINEAR: 'linear',
+//   CIRCULAR: 'circular'
+// };
+
+// /**
+//  * Progress events object for internal reference
+//  * @internal
+//  */
+// export const PROGRESS_EVENTS: Record<string, ProgressEvent> = {
+//   CHANGE: 'change',
+//   COMPLETE: 'complete'
+// };
 
 /**
  * Configuration interface for the Progress component
+ * @category Components
  */
 export interface ProgressConfig {
-  /** Progress variant (linear, circular) */
-  variant?: keyof typeof PROGRESS_VARIANTS | string;
-  
-  /** Initial progress value (0-100) */
+  /** 
+   * Progress variant that determines visual style
+   * @default 'linear'
+   */
+  variant?: ProgressVariant | string;
+  
+  /** 
+   * Initial progress value (0-100)
+   * @default 0
+   */
   value?: number;
   
-  /** Whether the progress indicator is initially disabled */
+  /** 
+   * Whether the progress indicator is initially disabled
+   * @default false
+   */
   disabled?: boolean;
   
-  /** Maximum value (defaults to 100) */
+  /** 
+   * Maximum value 
+   * @default 100
+   */
   max?: number;
   
-  /** Custom buffer value for linear progress */
+  /** 
+   * Buffer value for linear progress with buffer (like video loading)
+   * @default 0
+   */
   buffer?: number;
   
-  /** Additional CSS classes */
+  /** 
+   * Additional CSS classes to add to the progress component
+   * @example 'page-loader main-progress'
+   */
   class?: string;
   
-  /** Whether to show text label with percentage */
+  /** 
+   * Whether to show text label with percentage
+   * @default false
+   */
   showLabel?: boolean;
   
-  /** Whether progress is indeterminate */
+  /** 
+   * Whether progress is indeterminate (shows animation without specific value)
+   * @default false
+   */
   indeterminate?: boolean;
   
-  /** Custom label format function */
+  /** 
+   * Custom label formatter function
+   * @example (value, max) => `${Math.round((value/max) * 100)}%`
+   */
   labelFormatter?: (value: number, max: number) => string;
+  
+  /**
+   * Component prefix for class names
+   * @default 'mtrl'
+   */
+  prefix?: string;
+  
+  /**
+   * Component name used in class generation
+   * @default 'progress'
+   */
+  componentName?: string;
 }
 
 /**
  * Progress component interface
+ * @category Components
  */
 export interface ProgressComponent {
-  /** The component's root element */
+  /** The component's root DOM element */
   element: HTMLElement;
   
-  /** The track element */
+  /** The track element (background) */
   trackElement: HTMLElement;
   
-  /** The indicator element */
+  /** The indicator element (filled part) */
   indicatorElement: HTMLElement;
   
-  /** The buffer element (for linear variant) */
+  /** The buffer element for linear variant (pre-loaded state) */
   bufferElement?: HTMLElement;
   
-  /** The label element (if enabled) */
+  /** The label element if showLabel is enabled */
   labelElement?: HTMLElement;
   
-  /** Sets the current progress value */
+  /**
+   * Gets a class name with the component's prefix
+   * @param name - Base class name
+   * @returns Prefixed class name
+   */
+  getClass: (name: string) => string;
+  
+  /**
+   * Sets the current progress value
+   * @param value - Progress value (between 0 and max)
+   * @returns The progress component for chaining
+   */
   setValue: (value: number) => ProgressComponent;
   
-  /** Gets the current progress value */
+  /**
+   * Gets the current progress value
+   * @returns Current progress value
+   */
   getValue: () => number;
   
-  /** Sets the buffer value (for linear variant) */
+  /**
+   * Sets the buffer value (for linear variant with buffer indicators)
+   * @param value - Buffer value (between 0 and max)
+   * @returns The progress component for chaining
+   */
   setBuffer: (value: number) => ProgressComponent;
   
-  /** Gets the current buffer value */
+  /**
+   * Gets the current buffer value
+   * @returns Current buffer value
+   */
   getBuffer: () => number;
   
-  /** Enables the progress component */
+  /**
+   * Enables the progress component
+   * @returns The progress component for chaining
+   */
   enable: () => ProgressComponent;
   
-  /** Disables the progress component */
+  /**
+   * Disables the progress component
+   * @returns The progress component for chaining
+   */
   disable: () => ProgressComponent;
   
-  /** Checks if the component is disabled */
+  /**
+   * Checks if the component is disabled
+   * @returns Whether the component is disabled
+   */
   isDisabled: () => boolean;
   
-  /** Shows the label */
+  /**
+   * Shows the label element
+   * @returns The progress component for chaining
+   */
   showLabel: () => ProgressComponent;
   
-  /** Hides the label */
+  /**
+   * Hides the label element
+   * @returns The progress component for chaining
+   */
   hideLabel: () => ProgressComponent;
   
-  /** Sets a custom formatter for the label */
+  /**
+   * Sets a custom formatter for the label
+   * @param formatter - Function that formats the label text
+   * @returns The progress component for chaining
+   */
   setLabelFormatter: (formatter: (value: number, max: number) => string) => ProgressComponent;
   
-  /** Sets the indeterminate state */
+  /**
+   * Sets the indeterminate state
+   * @param indeterminate - Whether progress is indeterminate
+   * @returns The progress component for chaining
+   */
   setIndeterminate: (indeterminate: boolean) => ProgressComponent;
   
-  /** Checks if the component is indeterminate */
+  /**
+   * Checks if the component is in indeterminate state
+   * @returns Whether the component is indeterminate
+   */
   isIndeterminate: () => boolean;
   
-  /** Adds event listener */
+  /**
+   * Adds an event listener to the progress
+   * @param event - Event name ('change', 'complete')
+   * @param handler - Event handler function
+   * @returns The progress component for chaining
+   */
   on: (event: string, handler: Function) => ProgressComponent;
   
-  /** Removes event listener */
+  /**
+   * Removes an event listener from the progress
+   * @param event - Event name
+   * @param handler - Event handler function
+   * @returns The progress component for chaining
+   */
   off: (event: string, handler: Function) => ProgressComponent;
   
-  /** Destroys the component and cleans up resources */
+  /**
+   * Destroys the progress component and cleans up resources
+   */
   destroy: () => void;
   
-  /** Add CSS classes */
+  /**
+   * Adds CSS classes to the progress element
+   * @param classes - One or more class names to add
+   * @returns The progress component for chaining
+   */
   addClass: (...classes: string[]) => ProgressComponent;
+  
+  /**
+   * API for managing disabled state
+   */
+  disabled: {
+    /** Enables the progress */
+    enable: () => void;
+    /** Disables the progress */
+    disable: () => void;
+    /** Checks if the progress is disabled */
+    isDisabled: () => boolean;
+  };
+  
+  /**
+   * API for managing component lifecycle
+   */
+  lifecycle: {
+    /** Destroys the component and cleans up resources */
+    destroy: () => void;
+  };
 }

package/src/components/radios/config.ts

@@ -12,7 +12,7 @@ import { RADIO_DIRECTIONS } from './constants';
  */
 export const defaultConfig: RadiosConfig = {
   name: '',
-  direction: RADIO_DIRECTIONS.VERTICAL,
+  direction: 'vertical',
   disabled: false,
   ripple: true,
   options: []

package/src/components/radios/index.ts

@@ -1,4 +1,3 @@
 // src/components/radios/index.ts
 export { default } from './radios';
-export { RADIO_STATES, RADIO_DIRECTIONS } from './constants';
 export { RadiosConfig, RadiosComponent, RadioOptionConfig } from './types';

package/src/components/radios/types.ts

@@ -1,5 +1,4 @@
 // src/components/radios/types.ts
-import { RADIO_DIRECTIONS } from './constants';
 
 /**
  * Configuration for a radio option in the Radios component
@@ -58,12 +57,6 @@ export interface RadiosConfig {
    */
   disabled?: boolean;
   
-  /** 
-   * Group layout direction
-   * @default 'vertical'
-   */
-  direction?: keyof typeof RADIO_DIRECTIONS | string;
-  
   /** 
    * Whether to enable ripple effect
    * @default true

package/src/components/search/config.ts

@@ -4,13 +4,12 @@ import {
   createElementConfig
 } from '../../core/config/component-config';
 import { SearchConfig } from './types';
-import { SEARCH_VARIANTS } from './constants';
 
 /**
  * Default configuration for the Search component
  */
 export const defaultConfig: SearchConfig = {
-  variant: SEARCH_VARIANTS.BAR,
+  variant: 'bar',
   disabled: false,
   placeholder: 'Search',
   value: '',

package/src/components/search/features/search.ts

@@ -1,5 +1,4 @@
 // src/components/search/features/search.ts
-import { SEARCH_EVENTS, SEARCH_VARIANTS } from '../constants';
 import { SearchConfig } from '../types';
 
 /**
@@ -39,7 +38,7 @@ export const withSearch = (config: SearchConfig) => component => {
     placeholder: config.placeholder || 'Search',
     suggestions: config.suggestions || [],
     isFocused: false,
-    isExpanded: config.variant === SEARCH_VARIANTS.VIEW,
+    isExpanded: config.variant === 'view',
     component
   };
   
@@ -95,7 +94,7 @@ export const withSearch = (config: SearchConfig) => component => {
     
     // Trigger input event
     if (triggerEvent) {
-      eventHelpers.triggerEvent(SEARCH_EVENTS.INPUT);
+      eventHelpers.triggerEvent('input');
     }
   };
   
@@ -104,7 +103,7 @@ export const withSearch = (config: SearchConfig) => component => {
    */
   const submitSearch = () => {
     if (state.value) {
-      eventHelpers.triggerEvent(SEARCH_EVENTS.SUBMIT);
+      eventHelpers.triggerEvent('submit');
       
       // Hide suggestions if in bar mode
       if (!state.isExpanded) {
@@ -124,7 +123,7 @@ export const withSearch = (config: SearchConfig) => component => {
     }
     
     if (triggerEvent) {
-      eventHelpers.triggerEvent(SEARCH_EVENTS.CLEAR);
+      eventHelpers.triggerEvent('clear');
     }
   };
   
@@ -308,11 +307,11 @@ export const withSearch = (config: SearchConfig) => component => {
         component.element.classList.add(`${component.getClass('search')}--focused`);
         
         // Expand search bar to view if in bar mode
-        if (!state.isExpanded && config.variant === SEARCH_VARIANTS.BAR) {
+        if (!state.isExpanded && config.variant === 'bar') {
           expandToView();
         }
         
-        eventHelpers.triggerEvent(SEARCH_EVENTS.FOCUS, e);
+        eventHelpers.triggerEvent('focus', e);
       });
       
       // Blur event
@@ -331,13 +330,13 @@ export const withSearch = (config: SearchConfig) => component => {
             hideSuggestions();
             
             // Collapse to bar mode if in expanded state and originally a bar
-            if (state.isExpanded && config.variant === SEARCH_VARIANTS.BAR) {
+            if (state.isExpanded && config.variant === 'bar') {
               collapseToBar();
             }
           }
         }, 200);
         
-        eventHelpers.triggerEvent(SEARCH_EVENTS.BLUR, e);
+        eventHelpers.triggerEvent('blur', e);
       });
       
       // Enter key for submit
@@ -351,7 +350,7 @@ export const withSearch = (config: SearchConfig) => component => {
           // Clear if there's a value, otherwise collapse
           if (state.value) {
             clearSearch();
-          } else if (state.isExpanded && config.variant === SEARCH_VARIANTS.BAR) {
+          } else if (state.isExpanded && config.variant === 'bar') {
             collapseToBar();
           }
         }
@@ -373,7 +372,7 @@ export const withSearch = (config: SearchConfig) => component => {
           expandToView();
         }
         
-        eventHelpers.triggerEvent(SEARCH_EVENTS.ICON_CLICK, e);
+        eventHelpers.triggerEvent('iconClick', e);
       });
       
       // Keyboard access
@@ -413,7 +412,7 @@ export const withSearch = (config: SearchConfig) => component => {
         // If disabled, do nothing
         if (component.disabled?.isDisabled()) return;
         
-        eventHelpers.triggerEvent(SEARCH_EVENTS.ICON_CLICK, e);
+        eventHelpers.triggerEvent('iconClick', e);
       });
       
       // Keyboard access
@@ -433,7 +432,7 @@ export const withSearch = (config: SearchConfig) => component => {
         // If disabled, do nothing
         if (component.disabled?.isDisabled()) return;
         
-        eventHelpers.triggerEvent(SEARCH_EVENTS.ICON_CLICK, e);
+        eventHelpers.triggerEvent('iconClick', e);
       });
       
       // Keyboard access
@@ -451,7 +450,7 @@ export const withSearch = (config: SearchConfig) => component => {
         hideSuggestions();
         
         // Collapse to bar mode if in expanded state and originally a bar
-        if (state.isExpanded && config.variant === SEARCH_VARIANTS.BAR) {
+        if (state.isExpanded && config.variant === 'bar') {
           collapseToBar();
         }
       }
@@ -471,7 +470,7 @@ export const withSearch = (config: SearchConfig) => component => {
         hideSuggestions();
         
         // Collapse to bar mode if in expanded state and originally a bar
-        if (state.isExpanded && config.variant === SEARCH_VARIANTS.BAR) {
+        if (state.isExpanded && config.variant === 'bar') {
           collapseToBar();
         }
       }

package/src/components/search/features/states.ts

@@ -1,7 +1,11 @@
 // src/components/search/features/states.ts
-import { SEARCH_VARIANTS } from '../constants';
 import { SearchConfig } from '../types';
 
+const SEARCH_VARIANTS = {
+  BAR: 'bar',
+  VIEW: 'view'
+}
+
 /**
  * Add state management features to search component
  * 

package/src/components/search/features/structure.ts

@@ -1,5 +1,4 @@
 // src/components/search/features/structure.ts
-import { SEARCH_VARIANTS } from '../constants';
 import { SearchConfig } from '../types';
 import { createElement } from '../../../core/dom/create';
 
@@ -11,8 +10,8 @@ import { createElement } from '../../../core/dom/create';
 export const withStructure = (config: SearchConfig) => component => {
   // Get initial config values
   const isDisabled = config.disabled === true;
-  const variant = config.variant || SEARCH_VARIANTS.BAR;
-  const isViewMode = variant === SEARCH_VARIANTS.VIEW;
+  const variant = config.variant || 'bar';
+  const isViewMode = variant === 'view';
   const placeholder = config.placeholder || 'Search';
   const value = config.value || '';
   
@@ -179,7 +178,7 @@ function applyStyleClasses(component, config, isViewMode, isDisabled) {
   const baseClass = component.getClass('search');
   
   // Apply variant class
-  component.element.classList.add(`${baseClass}--${config.variant || SEARCH_VARIANTS.BAR}`);
+  component.element.classList.add(`${baseClass}--${config.variant || 'bar'}`);
     
   // Apply disabled class if needed
   if (isDisabled) {

package/src/components/search/index.ts

@@ -3,8 +3,5 @@
 // Export main component creator
 export { default } from './search';
 
-// Export constants
-export { SEARCH_VARIANTS, SEARCH_EVENTS } from './constants';
-
 // Export types for TypeScript users
 export type { SearchConfig, SearchComponent, SearchEvent } from './types';

package/src/components/search/types.ts

@@ -1,12 +1,22 @@
 // src/components/search/types.ts
-import { SEARCH_VARIANTS, SEARCH_EVENTS } from './constants';
+
+/**
+ * Navigation variants for the search component
+ */
+export type NavVariant = 'rail' | 'drawer' | 'bar' | 'modal' | 'standard';
+
+/**
+ * Valid event types for search component
+ */
+export type SearchEventType = 'focus' | 'blur' | 'input' | 'submit' | 'clear' | 'iconClick';
 
 /**
  * Configuration options for the search component
+ * @interface SearchConfig
  */
 export interface SearchConfig {
-  /** The variant of the search component (bar or view) */
-  variant?: keyof typeof SEARCH_VARIANTS | typeof SEARCH_VARIANTS[keyof typeof SEARCH_VARIANTS];
+  /** The variant of the search component (rail, drawer, bar, modal, or standard) */
+  variant?: NavVariant | string;
   
   /** Whether the search component is disabled */
   disabled?: boolean;
@@ -61,12 +71,13 @@ export interface SearchConfig {
   
   /** Event handlers for search events */
   on?: {
-    [key in keyof typeof SEARCH_EVENTS | typeof SEARCH_EVENTS[keyof typeof SEARCH_EVENTS]]?: (event: SearchEvent) => void;
+    [key in SearchEventType]?: (event: SearchEvent) => void;
   };
 }
 
 /**
  * Search event data
+ * @interface SearchEvent
  */
 export interface SearchEvent {
   /** The search component that triggered the event */
@@ -87,6 +98,7 @@ export interface SearchEvent {
 
 /**
  * Search component public API interface
+ * @interface SearchComponent
  */
 export interface SearchComponent {
   /** The root element of the search component */
@@ -153,10 +165,10 @@ export interface SearchComponent {
   isDisabled: () => boolean;
   
   /** Adds event listener */
-  on: (event: keyof typeof SEARCH_EVENTS | typeof SEARCH_EVENTS[keyof typeof SEARCH_EVENTS], handler: (event: SearchEvent) => void) => SearchComponent;
+  on: (event: SearchEventType, handler: (event: SearchEvent) => void) => SearchComponent;
   
   /** Removes event listener */
-  off: (event: keyof typeof SEARCH_EVENTS | typeof SEARCH_EVENTS[keyof typeof SEARCH_EVENTS], handler: (event: SearchEvent) => void) => SearchComponent;
+  off: (event: SearchEventType, handler: (event: SearchEvent) => void) => SearchComponent;
   
   /** Destroys the search component and cleans up resources */
   destroy: () => void;

package/src/components/segmented-button/config.ts

@@ -1,7 +1,20 @@
 // src/components/segmented-button/config.ts
 import { createComponentConfig } from '../../core/config/component-config';
 import { SegmentedButtonConfig, SelectionMode } from './types';
-import { DEFAULT_CONFIG, CLASSES } from './constants';
+
+export const DEFAULT_CHECKMARK_ICON = `
+<svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+  <polyline points="20 6 9 17 4 12"></polyline>
+</svg>`;
+
+/**
+ * Default configuration values for segmented buttons
+ * @internal
+ */
+export const DEFAULT_CONFIG = {
+  mode: SelectionMode.SINGLE,
+  ripple: true
+};
 
 /**
  * Creates the base configuration for Segmented Button component
@@ -10,7 +23,7 @@ import { DEFAULT_CONFIG, CLASSES } from './constants';
  * @internal
  */
 export const createBaseConfig = (config: SegmentedButtonConfig = {}): SegmentedButtonConfig => 
-  createComponentConfig(DEFAULT_CONFIG, config, CLASSES.CONTAINER) as SegmentedButtonConfig;
+  createComponentConfig(DEFAULT_CONFIG, config, 'segmented-button') as SegmentedButtonConfig;
 
 /**
  * Generates element configuration for the Segmented Button container
@@ -20,7 +33,7 @@ export const createBaseConfig = (config: SegmentedButtonConfig = {}): SegmentedB
  */
 export const getContainerConfig = (config: SegmentedButtonConfig) => ({
   tag: 'div',
-  componentName: CLASSES.CONTAINER,
+  componentName: 'segmented-button',
   attrs: {
     role: 'group',
     'aria-label': 'Segmented button',
@@ -28,7 +41,7 @@ export const getContainerConfig = (config: SegmentedButtonConfig) => ({
   },
   className: [
     config.class,
-    config.disabled ? `${config.prefix}-${CLASSES.CONTAINER}--disabled` : null
+    config.disabled ? `${config.prefix}-segmented-button--disabled` : null
   ],
   interactive: true
 });
@@ -54,9 +67,9 @@ export const getSegmentConfig = (segment, prefix, groupDisabled = false) => {
       value: segment.value
     },
     className: [
-      `${prefix}-${CLASSES.SEGMENT}`,
-      segment.selected ? `${prefix}-${CLASSES.SEGMENT}--${CLASSES.SELECTED}` : null,
-      isDisabled ? `${prefix}-${CLASSES.SEGMENT}--${CLASSES.DISABLED}` : null,
+      `${prefix}-segment`,
+      segment.selected ? `${prefix}-segment--selected` : null,
+      isDisabled ? `${prefix}-segment--disabled` : null,
       segment.class
     ],
     forwardEvents: {