mtrl 0.2.6 → 0.2.8

package/src/components/navigation/types.ts

@@ -1,9 +1,49 @@
 // src/components/navigation/types.ts
-import { 
-  NAV_VARIANTS, 
-  NAV_POSITIONS, 
-  NAV_BEHAVIORS 
-} from './constants';
+
+/**
+ * Navigation variants following Material Design 3
+ * @category Components
+ */
+export type NavVariant = 'rail' | 'drawer' | 'bar' | 'modal' | 'standard';
+
+/**
+ * Navigation positions
+ * @category Components
+ */
+export type NavPosition = 'left' | 'right' | 'top' | 'bottom';
+
+/**
+ * Navigation behaviors
+ * @category Components
+ */
+export type NavBehavior = 'fixed' | 'dismissible' | 'modal';
+
+/**
+ * Navigation item state
+ * @category Components
+ */
+export type NavItemState = 'active' | 'disabled' | 'expanded' | 'collapsed' | 'hovered' | 'focused' | 'pressed';
+
+/**
+ * Navigation element class names
+ * Used internally to maintain consistent class names
+ * @internal
+ */
+export const NavClass = {
+  ITEM: 'nav-item',
+  ITEM_CONTAINER: 'nav-item-container',
+  ICON: 'nav-item-icon',
+  LABEL: 'nav-item-label',
+  BADGE: 'nav-item-badge',
+  DIVIDER: 'nav-divider',
+  SCRIM: 'nav-scrim',
+  GROUP: 'nav-group',
+  GROUP_TITLE: 'nav-group-title',
+  SUBTITLE: 'nav-subtitle',
+  NESTED_CONTAINER: 'nav-nested-container',
+  NESTED_ITEM: 'nav-nested-item',
+  EXPAND_ICON: 'nav-expand-icon'
+} as const;
 
 /**
  * Navigation item configuration
@@ -12,13 +52,13 @@ export interface NavItemConfig {
   /** Unique identifier for the item */
   id: string;
   
-  /** HTML content for the icon */
-  icon: string;
+  /** Icon HTML content */
+  icon?: string;
   
-  /** Text label for the item */
-  label: string;
+  /** Text label */
+  label?: string;
   
-  /** Optional badge text (notifications, etc.) */
+  /** Badge text */
   badge?: string;
   
   /** Whether the item is disabled */
@@ -27,17 +67,17 @@ export interface NavItemConfig {
   /** Whether the item is active */
   active?: boolean;
   
-  /** Optional subtitle (for drawer variant) */
+  /** Whether nested items are expanded */
+  expanded?: boolean;
+  
+  /** Subtitle text (for drawer items) */
   subtitle?: string;
   
-  /** ID of the group this item belongs to */
+  /** Group ID this item belongs to */
   groupId?: string;
   
   /** Nested navigation items */
   items?: NavItemConfig[];
-  
-  /** Whether nested items are expanded */
-  expanded?: boolean;
 }
 
 /**
@@ -55,10 +95,10 @@ export interface NavGroupConfig {
 }
 
 /**
- * Stored item data
+ * Navigation item data
  */
 export interface NavItemData {
-  /** DOM element for the item */
+  /** The item's DOM element */
   element: HTMLElement;
   
   /** Item configuration */
@@ -69,14 +109,14 @@ export interface NavItemData {
  * Navigation change event data
  */
 export interface NavChangeEvent {
-  /** ID of the active item */
+  /** ID of the selected item */
   id: string;
   
-  /** Item data */
+  /** Selected item data */
   item: NavItemData;
   
-  /** Previously active item */
-  previousItem: NavItemData | null;
+  /** Previously selected item data */
+  previousItem?: NavItemData | null;
   
   /** Path of parent item IDs */
   path: string[];
@@ -87,15 +127,15 @@ export interface NavChangeEvent {
  */
 export interface NavigationConfig {
   /** Navigation variant */
-  variant?: keyof typeof NAV_VARIANTS | string;
+  variant?: NavVariant | string;
   
   /** Navigation position */
-  position?: keyof typeof NAV_POSITIONS | string;
+  position?: NavPosition | string;
   
   /** Navigation behavior */
-  behavior?: keyof typeof NAV_BEHAVIORS | string;
+  behavior?: NavBehavior | string;
   
-  /** Initial navigation items */
+  /** Navigation items */
   items?: NavItemConfig[];
   
   /** Navigation groups */
@@ -104,22 +144,22 @@ export interface NavigationConfig {
   /** Whether the navigation is disabled */
   disabled?: boolean;
   
-  /** Whether drawer is initially expanded */
+  /** Whether the navigation is expanded (for drawer) */
   expanded?: boolean;
   
-  /** Whether to show labels */
+  /** Whether to show item labels */
   showLabels?: boolean;
   
-  /** Whether backdrop scrim is enabled */
+  /** Whether to enable background scrim (for modal drawer) */
   scrimEnabled?: boolean;
   
-  /** ARIA label for accessibility */
-  ariaLabel?: string;
-  
   /** Additional CSS classes */
   class?: string;
   
-  /** Prefix for class names */
+  /** Accessibility label */
+  ariaLabel?: string;
+  
+  /** Component prefix for class names */
   prefix?: string;
   
   /** Component name */
@@ -130,83 +170,90 @@ export interface NavigationConfig {
  * Navigation component interface
  */
 export interface NavigationComponent {
-  /** The root element of the navigation */
+  /** The navigation's DOM element */
   element: HTMLElement;
   
-  /** Map of all navigation items */
+  /** Map of navigation items */
   items: Map<string, NavItemData>;
   
-  /** Adds a new navigation item */
-  addItem: (itemConfig: NavItemConfig) => NavigationComponent;
+  /** Adds a navigation item */
+  addItem: (config: NavItemConfig) => NavigationComponent;
   
-  /** Removes a navigation item by ID */
+  /** Removes a navigation item */
   removeItem: (id: string) => NavigationComponent;
   
-  /** Retrieves a navigation item by ID */
+  /** Gets a navigation item by ID */
   getItem: (id: string) => NavItemData | undefined;
   
-  /** Retrieves all navigation items */
+  /** Gets all navigation items */
   getAllItems: () => NavItemData[];
   
-  /** Gets the currently active item */
+  /** Gets the active navigation item */
   getActive: () => NavItemData | null;
   
   /** Gets the path to an item (parent IDs) */
   getItemPath: (id: string) => string[];
   
-  /** Sets an item as active by ID */
+  /** Sets the active navigation item */
   setActive: (id: string) => NavigationComponent;
   
-  /** Adds event listener */
-  on: (event: string, handler: Function) => NavigationComponent;
-  
-  /** Removes event listener */
-  off: (event: string, handler: Function) => NavigationComponent;
-  
   /** Enables the navigation */
   enable: () => NavigationComponent;
   
   /** Disables the navigation */
   disable: () => NavigationComponent;
   
-  /** Destroys the navigation component and cleans up resources */
+  /** Expands the navigation (for drawer) */
+  expand: () => NavigationComponent;
+  
+  /** Collapses the navigation (for drawer) */
+  collapse: () => NavigationComponent;
+  
+  /** Checks if the navigation is expanded */
+  isExpanded: () => boolean;
+  
+  /** Toggles the navigation expansion state */
+  toggle: () => NavigationComponent;
+  
+  /** Adds an event listener */
+  on: (event: string, handler: Function) => NavigationComponent;
+  
+  /** Removes an event listener */
+  off: (event: string, handler: Function) => NavigationComponent;
+  
+  /** Destroys the navigation component */
   destroy: () => void;
 }
 
-/**
- * API options interface
- */
-export interface ApiOptions {
-  disabled: {
-    enable: () => any;
-    disable: () => any;
-  };
-  lifecycle: {
-    destroy: () => void;
-  };
-}
-
 /**
  * Base component interface
  */
 export interface BaseComponent {
   element: HTMLElement;
+  prefix?: string;
+  items?: Map<string, NavItemData>;
   emit?: (event: string, data: any) => void;
   on?: (event: string, handler: Function) => any;
   off?: (event: string, handler: Function) => any;
-  addItem?: (itemConfig: NavItemConfig) => any;
-  removeItem?: (id: string) => any;
-  getItem?: (id: string) => NavItemData | undefined;
-  getAllItems?: () => NavItemData[];
-  getActive?: () => NavItemData | null;
-  getItemPath?: (id: string) => string[];
-  setActive?: (id: string) => any;
+  lifecycle?: {
+    destroy: () => void;
+  };
   disabled?: {
     enable: () => any;
     disable: () => any;
   };
-  lifecycle?: {
+  [key: string]: any;
+}
+
+/**
+ * API options interface
+ */
+export interface ApiOptions {
+  disabled: {
+    enable: () => void;
+    disable: () => void;
+  };
+  lifecycle: {
     destroy: () => void;
   };
-  [key: string]: any;
 }

package/src/components/progress/api.ts

@@ -1,7 +1,6 @@
 // src/components/progress/api.ts
 
 import { ProgressComponent } from './types';
-import { PROGRESS_EVENTS } from './constants';
 
 interface ApiOptions {
   value: {
@@ -80,7 +79,7 @@ export const withAPI = (options: ApiOptions) =>
         component.labelElement.textContent = formatter(value, options.value.getMax());
       }
       
-      component.emit(PROGRESS_EVENTS.VALUE_CHANGE, { value });
+      component.emit('valueChange', { value });
       return this;
     },
     
@@ -163,7 +162,7 @@ export const withAPI = (options: ApiOptions) =>
       }
       
       if (wasIndeterminate !== indeterminate) {
-        component.emit(PROGRESS_EVENTS.STATE_CHANGE, { indeterminate });
+        component.emit('stateChange', { indeterminate });
       }
       
       return this;

package/src/components/progress/config.ts

@@ -5,13 +5,12 @@ import {
   BaseComponentConfig 
 } from '../../core/config/component-config';
 import { ProgressConfig } from './types';
-import { PROGRESS_VARIANTS } from './constants';
 
 /**
  * Default configuration for the Progress component
  */
 export const defaultConfig: ProgressConfig = {
-  variant: PROGRESS_VARIANTS.LINEAR,
+  variant: 'linear',
   value: 0,
   max: 100,
   buffer: 0,
@@ -52,7 +51,7 @@ export const getElementConfig = (config: ProgressConfig) => {
     attrs['aria-disabled'] = 'true';
   }
   
-  const isCircular = config.variant === PROGRESS_VARIANTS.CIRCULAR;
+  const isCircular = config.variant === 'circular';
   
   return createElementConfig(config, {
     tag: 'div',

package/src/components/progress/index.ts

@@ -1,5 +1,4 @@
 // src/components/progress/index.ts
 
 export { default } from './progress';
-export { PROGRESS_VARIANTS, PROGRESS_EVENTS } from './constants';
 export { ProgressConfig, ProgressComponent } from './types';

package/src/components/progress/progress.ts

@@ -11,7 +11,6 @@ import {
 } from '../../core/compose/features';
 import { withAPI } from './api';
 import { ProgressConfig, ProgressComponent } from './types';
-import { PROGRESS_VARIANTS, PROGRESS_EVENTS } from './constants';
 import { createBaseConfig, getElementConfig, getApiConfig } from './config';
 
 // Helper functions
@@ -104,7 +103,7 @@ const createProgress = (config: ProgressConfig = {}): ProgressComponent => {
       // Add DOM structure based on variant
       (component) => {
         const baseClass = component.getClass('progress');
-        const isCircular = baseConfig.variant === PROGRESS_VARIANTS.CIRCULAR;
+        const isCircular = baseConfig.variant === 'circular';
         
         if (isCircular) {
           const { track, indicator, svg } = createCircularProgressDOM(baseClass);

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';