mtrl 0.3.0 → 0.3.2

package/src/components/{chip → chips}/types.ts

@@ -1,4 +1,4 @@
-// src/components/chip/types.ts
+// src/components/chips/types.ts
 
 /**
  * Chip variant types
@@ -6,6 +6,25 @@
  */
 export type ChipVariant = 'filled' | 'outlined' | 'elevated' | 'assist' | 'filter' | 'input' | 'suggestion';
 
+/**
+ * Available chip event types
+ */
+export const CHIP_EVENTS = {
+  CHANGE: 'change',
+  SELECT: 'select',
+  DESELECT: 'deselect',
+  REMOVE: 'remove'
+} as const;
+
+/**
+ * Available chips event types
+ */
+export const CHIPS_EVENTS = {
+  CHANGE: 'change',
+  ADD: 'add',
+  REMOVE: 'remove'
+} as const;
+
 /**
  * Configuration interface for the Chip component
  * @category Components
@@ -111,58 +130,85 @@ export interface ChipConfig {
   
   /**
    * Function called when the chip selection changes
+   * @param {boolean} selected - Whether the chip is selected
+   * @param {ChipComponent} chip - The chip component
    */
-  onChange?: (chip: ChipComponent) => void;
+  onChange?: (selected: boolean, chip: ChipComponent) => void;
 }
 
 /**
- * Icon API interface for managing chip icons
+ * Configuration interface for the Chips component
  * @category Components
  */
-export interface IconAPI {
-  /**
-   * Sets the icon HTML content
-   * @param html - HTML string for the icon
-   * @returns The icon API for chaining
+export interface ChipsConfig {
+  /** 
+   * Array of chip configurations to initialize 
+   * @default []
    */
-  setIcon: (html: string) => IconAPI;
+  chips?: ChipConfig[];
   
-  /**
-   * Gets the current icon HTML content
-   * @returns HTML string for the icon
+  /** 
+   * Whether the chip set is horizontally scrollable 
+   * @default false
    */
-  getIcon: () => string;
+  scrollable?: boolean;
+  
+  /** 
+   * Whether the chip set is vertically stacked 
+   * @default false
+   */
+  vertical?: boolean;
+  
+  /** 
+   * Additional CSS classes 
+   */
+  class?: string;
+  
+  /** 
+   * CSS selector for filtering behavior 
+   */
+  selector?: string | null;
+  
+  /** 
+   * Whether multiple chips can be selected simultaneously 
+   * @default false
+   */
+  multiSelect?: boolean;
+  
+  /** 
+   * Callback function when chip selection changes 
+   */
+  onChange?: (selectedValues: (string | null)[], changedValue: string | null) => void;
   
   /**
-   * Gets the icon DOM element
-   * @returns The icon element or null if not present
+   * Component prefix for class names
+   * @default 'mtrl'
    */
-  getElement: () => HTMLElement | null;
-}
-
-/**
- * Text API interface for managing chip text
- * @category Components
- */
-export interface TextAPI {
+  prefix?: string;
+  
   /**
-   * Sets the text content
-   * @param content - Text content
-   * @returns The text API for chaining
+   * Label text for the chips container
    */
-  setText: (content: string) => TextAPI;
+  label?: string;
   
   /**
-   * Gets the current text content
-   * @returns Chip text content
+   * Position of the label (start or end)
+   * @default 'start'
    */
-  getText: () => string;
+  labelPosition?: 'start' | 'end';
+  
+  /** 
+   * Schema definition for the component structure
+   * @internal
+   */
+  schema?: any;
   
   /**
-   * Gets the text DOM element
-   * @returns The text element or null if not present
+   * Event handlers for component events
    */
-  getElement: () => HTMLElement | null;
+  on?: {
+    [key: string]: Function;
+  };
 }
 
 /**
@@ -173,35 +219,6 @@ 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 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 attribute
    * @returns Chip value
@@ -323,36 +340,130 @@ export interface ChipComponent {
 }
 
 /**
- * API options interface
- * @internal
- */
-export interface ApiOptions {
-  disabled: {
-    enable: () => void;
-    disable: () => void;
-  };
-  lifecycle: {
-    destroy: () => void;
-  };
-}
-
-/**
- * Base component interface
- * @internal
+ * Chips component interface
+ * @category Components
  */
-export interface BaseComponent {
+export interface ChipsComponent {
+  /** The chips container's DOM element */
   element: HTMLElement;
-  getClass: (name?: string) => string;
-  config: any;
-  text?: TextAPI;
-  icon?: IconAPI;
-  disabled?: {
-    enable: () => void;
-    disable: () => void;
-    isDisabled: () => boolean;
-  };
-  lifecycle?: {
-    destroy: () => void;
-  };
-  [key: string]: any;
+  
+  /**
+   * Adds a new chip to the chips container
+   * @param chipConfig - Configuration for the chip
+   * @returns The chips instance for chaining
+   */
+  addChip: (chipConfig: ChipConfig) => ChipsComponent;
+  
+  /**
+   * Removes a chip from the chips container
+   * @param chipOrIndex - Chip instance or index to remove
+   * @returns The chips instance for chaining
+   */
+  removeChip: (chipOrIndex: ChipComponent | number) => ChipsComponent;
+  
+  /**
+   * Gets all chip instances in the set
+   * @returns Array of chip instances
+   */
+  getChips: () => ChipComponent[];
+  
+  /**
+   * Gets currently selected chips
+   * @returns Array of selected chip instances
+   */
+  getSelectedChips: () => ChipComponent[];
+  
+  /**
+   * Gets the values of selected chips
+   * @returns Array of selected chip values
+   */
+  getSelectedValues: () => (string | null)[];
+  
+  /**
+   * Selects chips by their values
+   * @param values - Value or array of values to select
+   * @param triggerEvent - Whether to trigger change event (default: true)
+   * @returns The chips instance for chaining
+   */
+  selectByValue: (values: string | string[], triggerEvent?: boolean) => ChipsComponent;
+  
+  /**
+   * Clears all selections
+   * @returns The chips instance for chaining
+   */
+  clearSelection: () => ChipsComponent;
+  
+  /**
+   * Sets the scrollable state of the chips container
+   * @param isScrollable - Whether the chips container should be scrollable
+   * @returns The chips instance for chaining
+   */
+  setScrollable: (isScrollable: boolean) => ChipsComponent;
+  
+  /**
+   * Sets the vertical layout state
+   * @param isVertical - Whether the chips container should be vertically stacked
+   * @returns The chips instance for chaining
+   */
+  setVertical: (isVertical: boolean) => ChipsComponent;
+  
+  /**
+   * Sets the label text
+   * @param text - Label text
+   * @returns The chips instance for chaining
+   */
+  setLabel: (text: string) => ChipsComponent;
+  
+  /**
+   * Gets the label text
+   * @returns Label text
+   */
+  getLabel: () => string;
+  
+  /**
+   * Sets the label position
+   * @param position - Label position ('start' or 'end')
+   * @returns The chips instance for chaining
+   */
+  setLabelPosition: (position: 'start' | 'end') => ChipsComponent;
+  
+  /**
+   * Gets the label position
+   * @returns Label position
+   */
+  getLabelPosition: () => string;
+  
+  /**
+   * Scrolls to a specific chip
+   * @param chipOrIndex - Chip instance or index to scroll to
+   * @returns The chips instance for chaining 
+   */
+  scrollToChip: (chipOrIndex: ChipComponent | number) => ChipsComponent;
+  
+  /**
+   * Enables keyboard navigation between chips in the set
+   * @returns The chips instance for chaining
+   */
+  enableKeyboardNavigation: () => ChipsComponent;
+  
+  /**
+   * Destroys the chips container and all contained chips
+   */
+  destroy: () => void;
+  
+  /**
+   * Adds an event listener to the chips container
+   * @param event - Event name ('change', etc.)
+   * @param handler - Event handler function
+   * @returns The chips instance for chaining
+   */
+  on: (event: string, handler: Function) => ChipsComponent;
+  
+  /**
+   * Removes an event listener from the chips container
+   * @param event - Event name
+   * @param handler - Event handler function
+   * @returns The chips instance for chaining
+   */
+  off: (event: string, handler: Function) => ChipsComponent;
 }

package/src/components/dialog/dialog.ts

@@ -1,4 +1,22 @@
 // src/components/dialog/dialog.ts
+/**
+ * Dialog Component Implementation
+ * 
+ * This module implements a Material Design 3 dialog component that can be
+ * used for alerts, confirmations, form submissions, and complex interactions.
+ * 
+ * The implementation supports various features including:
+ * - Multiple size variants (small, medium, large, fullwidth, fullscreen)
+ * - Multiple animation styles
+ * - Custom buttons with configurable actions
+ * - Dividers for visual separation
+ * - Confirmation dialog patterns
+ * - Event handling for dialog lifecycle
+ * 
+ * @module components/dialog
+ * @category Components
+ */
+
 import { pipe } from '../../core/compose';
 import { createBase, withElement } from '../../core/compose/component';
 import { withEvents, withLifecycle } from '../../core/compose/features';
@@ -16,28 +34,93 @@ import { DialogConfig, DialogComponent } from './types';
 import { createBaseConfig, getElementConfig, getApiConfig } from './config';
 
 /**
- * Creates a new Dialog component
- * @param {DialogConfig} config - Dialog configuration object
- * @returns {DialogComponent} Dialog component instance
+ * Creates a new Dialog component with the specified configuration.
+ * 
+ * Dialogs are modal windows that appear in front of app content to
+ * provide critical information or ask for decisions. They inform
+ * users about specific tasks and may contain critical information,
+ * require decisions, or involve multiple tasks.
+ * 
+ * @param {DialogConfig} config - Configuration options for the dialog
+ * @returns {DialogComponent} A fully configured dialog component instance
+ * @throws {Error} Throws an error if dialog creation fails
+ * 
+ * @category Components
+ * 
+ * @example
+ * // Create a basic dialog with title and content
+ * const infoDialog = createDialog({
+ *   title: 'Information',
+ *   content: 'Your changes have been saved.',
+ *   size: 'small',
+ *   buttons: [
+ *     { text: 'OK', variant: 'text', closeDialog: true }
+ *   ]
+ * });
+ * 
+ * document.body.appendChild(infoDialog.element);
+ * infoDialog.open();
+ * 
+ * @example
+ * // Create a form dialog with multiple buttons
+ * const formDialog = createDialog({
+ *   title: 'Edit Profile',
+ *   content: '<form id="profile-form">...</form>',
+ *   size: 'medium',
+ *   closeOnEscape: true,
+ *   closeOnOverlayClick: false,
+ *   buttons: [
+ *     { 
+ *       text: 'Save', 
+ *       variant: 'filled', 
+ *       onClick: (event, dialog) => {
+ *         const form = document.getElementById('profile-form');
+ *         if(form.checkValidity()) {
+ *           saveProfile(form);
+ *           dialog.close();
+ *         }
+ *       }
+ *     },
+ *     { text: 'Cancel', variant: 'text', closeDialog: true }
+ *   ]
+ * });
+ * 
+ * @example
+ * // Create a confirmation dialog using the Promise-based API
+ * async function confirmAction() {
+ *   const dialog = createDialog();
+ *   const confirmed = await dialog.confirm({
+ *     title: 'Confirm Action',
+ *     message: 'Are you sure you want to proceed?',
+ *     confirmText: 'Yes, proceed',
+ *     cancelText: 'No, cancel'
+ *   });
+ *   
+ *   if (confirmed) {
+ *     // User clicked the confirm button
+ *     performAction();
+ *   }
+ * }
  */
 const createDialog = (config: DialogConfig = {}): DialogComponent => {
   const baseConfig = createBaseConfig(config);
 
   try {
-    // Maintain original order but setup event-based communication
+    // Create the dialog through functional composition
+    // Each function in the pipe adds specific features to the component
     const dialog = pipe(
-      createBase,
-      withEvents(),
-      withElement(getElementConfig(baseConfig)),
-      withStructure(baseConfig),  // Keep structure first to create overlay
-      withVisibility(),           // Then add visibility features
-      withContent(),
-      withButtons(),
-      withSize(),
-      withDivider(),              // Simplified divider feature
-      withConfirm(),
-      withLifecycle(),
-      comp => withAPI(getApiConfig(comp))(comp)
+      createBase,                                  // Base component
+      withEvents(),                                // Event handling
+      withElement(getElementConfig(baseConfig)),   // DOM element
+      withStructure(baseConfig),                   // Dialog structure (overlay, header, content, footer)
+      withVisibility(),                            // Open/close functionality
+      withContent(),                               // Content management
+      withButtons(),                               // Footer buttons
+      withSize(),                                  // Size variants
+      withDivider(),                               // Header/content divider
+      withConfirm(),                               // Confirmation dialog helpers
+      withLifecycle(),                             // Lifecycle management
+      comp => withAPI(getApiConfig(comp))(comp)    // Public API
     )(baseConfig);
 
     // Register event handlers from config

package/src/components/dialog/index.ts

@@ -1,5 +1,22 @@
 // src/components/dialog/index.ts
+
+/**
+ * Dialog Component Module
+ * 
+ * A Material Design 3 dialog implementation with support for multiple sizes,
+ * animations, content types, and interactive features like confirmation.
+ * 
+ * Dialogs inform users about critical information, require decisions,
+ * or involve multiple tasks.
+ * 
+ * @module components/dialog
+ * @category Components
+ */
+
+// Main factory function
 export { default } from './dialog';
+
+// TypeScript types and interfaces
 export { 
   DialogConfig, 
   DialogComponent, 
@@ -12,34 +29,113 @@ export {
   DialogEventType
 } from './types';
 
-// Export common dialog constants for convenience and backward compatibility
+/**
+ * Dialog size constants
+ * 
+ * These constants define the available dialog size variants,
+ * controlling the width and height of the dialog.
+ * 
+ * @example
+ * import { createDialog, DIALOG_SIZES } from 'mtrl';
+ * 
+ * const dialog = createDialog({
+ *   title: 'Settings',
+ *   size: DIALOG_SIZES.MEDIUM
+ * });
+ * 
+ * @category Components
+ */
 export const DIALOG_SIZES = {
+  /** Small dialog (320px) for simple messages or choices */
   SMALL: 'small',
+  /** Medium dialog (560px) for standard forms or content (default) */
   MEDIUM: 'medium',
+  /** Large dialog (800px) for complex forms or rich content */
   LARGE: 'large',
+  /** Dialog that spans the full width of the viewport with margins */
   FULLWIDTH: 'fullwidth',
+  /** Dialog that takes up the entire viewport (similar to a new page) */
   FULLSCREEN: 'fullscreen'
 } as const;
 
+/**
+ * Dialog animation constants
+ * 
+ * These constants define the available dialog opening and closing animations.
+ * 
+ * @example
+ * import { createDialog, DIALOG_ANIMATIONS } from 'mtrl';
+ * 
+ * const dialog = createDialog({
+ *   animation: DIALOG_ANIMATIONS.SCALE
+ * });
+ * 
+ * @category Components
+ */
 export const DIALOG_ANIMATIONS = {
+  /** Scale up/down animation from center (default) */
   SCALE: 'scale',
+  /** Slide in from bottom, slide out to bottom */
   SLIDE_UP: 'slide-up',
+  /** Slide in from top, slide out to top */
   SLIDE_DOWN: 'slide-down',
+  /** Simple fade in/out animation */
   FADE: 'fade'
 } as const;
 
+/**
+ * Dialog footer alignment constants
+ * 
+ * These constants control how buttons in the footer are aligned.
+ * 
+ * @example
+ * import { createDialog, DIALOG_FOOTER_ALIGNMENTS } from 'mtrl';
+ * 
+ * const dialog = createDialog({
+ *   footerAlignment: DIALOG_FOOTER_ALIGNMENTS.RIGHT
+ * });
+ * 
+ * @category Components
+ */
 export const DIALOG_FOOTER_ALIGNMENTS = {
+  /** Align buttons to the right (default, follows Material Design guidelines) */
   RIGHT: 'right',
+  /** Align buttons to the left */
   LEFT: 'left',
+  /** Center buttons in footer */
   CENTER: 'center',
+  /** Space buttons evenly, with first button at left, last at right */
   SPACE_BETWEEN: 'space-between'
 } as const;
 
+/**
+ * Dialog event constants
+ * 
+ * These events can be used with the dialog's on() method to respond
+ * to changes in the dialog's state.
+ * 
+ * @example
+ * import { createDialog, DIALOG_EVENTS } from 'mtrl';
+ * 
+ * const dialog = createDialog();
+ * 
+ * dialog.on(DIALOG_EVENTS.AFTER_OPEN, () => {
+ *   console.log('Dialog was opened');
+ * });
+ * 
+ * @category Components
+ */
 export const DIALOG_EVENTS = {
+  /** Fired when the dialog begins opening */
   OPEN: 'open',
+  /** Fired when the dialog begins closing */
   CLOSE: 'close',
+  /** Fired before the dialog starts opening (can be prevented) */
   BEFORE_OPEN: 'beforeopen',
+  /** Fired before the dialog starts closing (can be prevented) */
   BEFORE_CLOSE: 'beforeclose',
+  /** Fired after the dialog has fully opened (animation complete) */
   AFTER_OPEN: 'afteropen',
+  /** Fired after the dialog has fully closed (animation complete) */
   AFTER_CLOSE: 'afterclose'
 } as const;