mtrl 0.3.1 → 0.3.2

package/src/components/checkbox/types.ts

@@ -1,111 +1,296 @@
 // src/components/checkbox/types.ts
 
 /**
- * Checkbox variant types
+ * Visual variants for checkbox styling
+ * 
+ * Material Design 3 checkboxes can use different visual styles
+ * while maintaining the same functionality.
+ * 
+ * @category Components
+ */
+export const CHECKBOX_VARIANTS = {
+  /** Checkbox with filled background when checked */
+  FILLED: 'filled',
+  /** Checkbox with outlined style (less prominent) */
+  OUTLINED: 'outlined'
+} as const;
+
+/**
+ * Label position options for the checkbox
+ * 
+ * Controls whether the label appears before or after the checkbox.
+ * 
+ * @category Components
+ */
+export const CHECKBOX_LABEL_POSITION = {
+  /** Label appears before (to the left of) the checkbox */
+  START: 'start',
+  /** Label appears after (to the right of) the checkbox (default) */
+  END: 'end'
+} as const;
+
+/**
+ * Checkbox state classes
+ * 
+ * These classes are applied to the checkbox element to reflect its current state.
+ * They can be used for styling or for selection in tests.
+ * 
+ * @category Components
+ */
+export const CHECKBOX_STATES = {
+  /** Applied when the checkbox is checked */
+  CHECKED: 'checked',
+  /** Applied when the checkbox is in indeterminate state */
+  INDETERMINATE: 'indeterminate',
+  /** Applied when the checkbox is disabled */
+  DISABLED: 'disabled',
+  /** Applied when the checkbox has focus */
+  FOCUSED: 'focused'
+} as const;
+
+/**
+ * Checkbox element classes
+ * 
+ * These classes are applied to different parts of the checkbox component.
+ * They follow the BEM naming convention used throughout the library.
+ * 
+ * @category Components
+ */
+export const CHECKBOX_CLASSES = {
+  /** The main checkbox container element */
+  ROOT: 'checkbox',
+  /** The actual input element (usually hidden) */
+  INPUT: 'checkbox-input',
+  /** The visual checkbox icon */
+  ICON: 'checkbox-icon',
+  /** The text label associated with the checkbox */
+  LABEL: 'checkbox-label'
+} as const;
+
+/**
+ * Checkbox variant types - controls the visual style of the checkbox
+ * 
+ * @category Components
+ * @remarks
+ * - filled: Checkbox with filled background when checked (default)
+ * - outlined: Checkbox with outline only, for less visual emphasis
  */
 export type CheckboxVariant = 'filled' | 'outlined';
 
 /**
- * Checkbox label position types
+ * Checkbox label position types - controls where the label appears
+ * 
+ * @category Components
+ * @remarks
+ * - start: Label appears before (to the left of) the checkbox
+ * - end: Label appears after (to the right of) the checkbox (default)
  */
 export type CheckboxLabelPosition = 'start' | 'end';
 
 /**
  * Configuration interface for the Checkbox component
+ * 
+ * @category Components
+ * @description
+ * Defines the appearance and behavior of a checkbox component.
+ * All properties are optional with sensible defaults.
  */
 export interface CheckboxConfig {
-  /** Input name attribute */
+  /** 
+   * Input name attribute, used for form submission
+   * @example "accept-terms"
+   */
   name?: string;
   
-  /** Initial checked state */
+  /** 
+   * Initial checked state
+   * @default false
+   */
   checked?: boolean;
   
-  /** Initial indeterminate state */
+  /** 
+   * Initial indeterminate state (partially checked)
+   * Used when a checkbox represents a mixed selection state
+   * @default false
+   */
   indeterminate?: boolean;
   
-  /** Whether input is required */
+  /** 
+   * Whether input is required for form validation
+   * @default false
+   */
   required?: boolean;
   
-  /** Whether checkbox is disabled */
+  /** 
+   * Whether checkbox is disabled (non-interactive)
+   * @default false
+   */
   disabled?: boolean;
   
-  /** Input value attribute */
+  /** 
+   * Input value attribute, used for form submission
+   * @example "true" | "selected" | "1"
+   */
   value?: string;
   
-  /** Label text */
+  /** 
+   * Label text displayed next to the checkbox
+   * @example "Accept terms and conditions"
+   */
   label?: string;
   
-  /** Label position (start/end) */
+  /** 
+   * Label position (start/end)
+   * Controls whether the label appears before or after the checkbox
+   * @default "end"
+   */
   labelPosition?: CheckboxLabelPosition | string;
   
-  /** Visual variant */
+  /** 
+   * Visual variant (filled/outlined)
+   * @default "filled"
+   */
   variant?: CheckboxVariant | string;
   
-  /** Additional CSS classes */
+  /** 
+   * Additional CSS classes to apply to the checkbox
+   * @example "terms-checkbox primary-checkbox"
+   */
   class?: string;
   
-  /** Prefix for class names */
+  /** 
+   * CSS class prefix for all checkbox classes
+   * @default "mtrl"
+   */
   prefix?: string;
   
-  /** Component name */
+  /** 
+   * Component name used in CSS class generation
+   * @default "checkbox"
+   * @internal
+   */
   componentName?: string;
 }
 
 /**
  * Checkbox component interface
+ * 
+ * Provides methods for controlling a Material Design 3 checkbox
+ * 
+ * @category Components
  */
 export interface CheckboxComponent {
-  /** The root element of the checkbox */
+  /** 
+   * The checkbox's root DOM element (container)
+   */
   element: HTMLElement;
   
-  /** The input element */
+  /** 
+   * The actual input element (native checkbox)
+   */
   input: HTMLInputElement;
   
-  /** Gets the checkbox's value */
+  /**
+   * Gets the checkbox's current value attribute
+   * @returns Current value of the checkbox
+   */
   getValue: () => string;
   
-  /** Sets the checkbox's value */
+  /**
+   * Sets the checkbox's value attribute
+   * @param value - New value to set
+   * @returns Checkbox component for method chaining
+   */
   setValue: (value: string) => CheckboxComponent;
   
-  /** Checks the checkbox */
+  /**
+   * Checks the checkbox (sets checked=true)
+   * @returns Checkbox component for method chaining
+   */
   check: () => CheckboxComponent;
   
-  /** Unchecks the checkbox */
+  /**
+   * Unchecks the checkbox (sets checked=false)
+   * @returns Checkbox component for method chaining
+   */
   uncheck: () => CheckboxComponent;
   
-  /** Toggles the checkbox's checked state */
+  /**
+   * Toggles the checkbox's checked state
+   * @returns Checkbox component for method chaining
+   */
   toggle: () => CheckboxComponent;
   
-  /** Returns whether the checkbox is checked */
+  /**
+   * Checks if the checkbox is currently checked
+   * @returns True if checkbox is checked, false otherwise
+   */
   isChecked: () => boolean;
   
-  /** Sets the checkbox's indeterminate state */
+  /**
+   * Sets the checkbox's indeterminate state
+   * An indeterminate checkbox appears partially checked
+   * and is used to represent a mixed selection state
+   * 
+   * @param state - Whether to set indeterminate state
+   * @returns Checkbox component for method chaining
+   */
   setIndeterminate: (state: boolean) => CheckboxComponent;
   
-  /** Sets the checkbox's label text */
+  /**
+   * Sets the checkbox's label text
+   * @param text - New label text
+   * @returns Checkbox component for method chaining
+   */
   setLabel: (text: string) => CheckboxComponent;
   
-  /** Gets the checkbox's label text */
+  /**
+   * Gets the checkbox's current label text
+   * @returns Current label text
+   */
   getLabel: () => string;
   
-  /** Adds event listener */
+  /**
+   * Adds an event listener to the checkbox
+   * @param event - Event name ('change', 'click', etc.)
+   * @param handler - Event handler function
+   * @returns Checkbox component for method chaining
+   * @example
+   * checkbox.on('change', (e) => console.log('Checkbox state:', e.target.checked));
+   */
   on: (event: string, handler: Function) => CheckboxComponent;
   
-  /** Removes event listener */
+  /**
+   * Removes an event listener from the checkbox
+   * @param event - Event name
+   * @param handler - Event handler function
+   * @returns Checkbox component for method chaining
+   */
   off: (event: string, handler: Function) => CheckboxComponent;
   
-  /** Enables the checkbox */
+  /**
+   * Enables the checkbox, making it interactive
+   * @returns Checkbox component for method chaining
+   */
   enable: () => CheckboxComponent;
   
-  /** Disables the checkbox */
+  /**
+   * Disables the checkbox, making it non-interactive
+   * @returns Checkbox component for method chaining
+   */
   disable: () => CheckboxComponent;
   
-  /** Destroys the checkbox component and cleans up resources */
+  /**
+   * Destroys the checkbox component and cleans up resources
+   * Removes event listeners and DOM references
+   */
   destroy: () => void;
 }
 
 /**
- * API options interface
+ * API options interface for internal use
+ * @category Components
+ * @internal
  */
 export interface ApiOptions {
   disabled: {
@@ -124,7 +309,9 @@ export interface ApiOptions {
 }
 
 /**
- * Base component interface
+ * Base component interface for internal composition
+ * @category Components
+ * @internal
  */
 export interface BaseComponent {
   element: HTMLElement;

package/src/components/chips/api.ts

@@ -0,0 +1,194 @@
+// src/components/chips/api.ts
+import { ChipsComponent, ChipComponent } from './types';
+
+/**
+ * API options interface - structured by feature area
+ */
+interface ApiOptions {
+  chips: {
+    addChip: (chipConfig: any) => ChipComponent;
+    removeChip: (chipOrIndex: ChipComponent | number) => void;
+    getChips: () => ChipComponent[];
+    getSelectedChips: () => ChipComponent[];
+    getSelectedValues: () => (string | null)[];
+    selectByValue: (values: string | string[], triggerEvent?: boolean) => void;
+    clearSelection: () => void;
+    scrollToChip: (chipOrIndex: ChipComponent | number) => void;
+  };
+  layout: {
+    setScrollable: (isScrollable: boolean) => any;
+    isScrollable: () => boolean;
+    setVertical: (isVertical: boolean) => any;
+    isVertical: () => boolean;
+  };
+  label: {
+    setText: (text: string) => any;
+    getText: () => string;
+    setPosition: (position: 'start' | 'end') => any;
+    getPosition: () => string;
+  };
+  keyboard: {
+    enableKeyboardNavigation: () => void;
+    disableKeyboardNavigation: () => void;
+  };
+  events: {
+    on: (event: string, handler: Function) => void;
+    off: (event: string, handler: Function) => void;
+  };
+  lifecycle: {
+    destroy: () => void;
+  };
+}
+
+/**
+ * Enhances a chips component with a streamlined API
+ * @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 Chips component
+ */
+export const withAPI = (options: ApiOptions) => 
+  (component: { element: HTMLElement }): ChipsComponent => {
+    return {
+      ...component as any,
+      
+      // Element access
+      element: component.element,
+      
+      // Chip management
+      addChip(chipConfig) {
+        if (options.chips && typeof options.chips.addChip === 'function') {
+          options.chips.addChip(chipConfig);
+        }
+        return this;
+      },
+      
+      removeChip(chipOrIndex) {
+        if (options.chips && typeof options.chips.removeChip === 'function') {
+          options.chips.removeChip(chipOrIndex);
+        }
+        return this;
+      },
+      
+      getChips() {
+        if (options.chips && typeof options.chips.getChips === 'function') {
+          return options.chips.getChips();
+        }
+        return [];
+      },
+      
+      getSelectedChips() {
+        if (options.chips && typeof options.chips.getSelectedChips === 'function') {
+          return options.chips.getSelectedChips();
+        }
+        return [];
+      },
+      
+      getSelectedValues() {
+        if (options.chips && typeof options.chips.getSelectedValues === 'function') {
+          return options.chips.getSelectedValues();
+        }
+        return [];
+      },
+      
+      /**
+       * 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, triggerEvent = true) {
+        if (options.chips && typeof options.chips.selectByValue === 'function') {
+          options.chips.selectByValue(values, triggerEvent);
+        }
+        return this;
+      },
+      
+      clearSelection() {
+        if (options.chips && typeof options.chips.clearSelection === 'function') {
+          options.chips.clearSelection();
+        }
+        return this;
+      },
+      
+      // Layout management
+      setScrollable(isScrollable) {
+        if (options.layout && typeof options.layout.setScrollable === 'function') {
+          options.layout.setScrollable(isScrollable);
+        }
+        return this;
+      },
+      
+      setVertical(isVertical) {
+        if (options.layout && typeof options.layout.setVertical === 'function') {
+          options.layout.setVertical(isVertical);
+        }
+        return this;
+      },
+      
+      // Label management
+      setLabel(text) {
+        if (options.label && typeof options.label.setText === 'function') {
+          options.label.setText(text);
+        }
+        return this;
+      },
+      
+      getLabel() {
+        if (options.label && typeof options.label.getText === 'function') {
+          return options.label.getText();
+        }
+        return '';
+      },
+      
+      setLabelPosition(position) {
+        if (options.label && typeof options.label.setPosition === 'function') {
+          options.label.setPosition(position);
+        }
+        return this;
+      },
+      
+      getLabelPosition() {
+        if (options.label && typeof options.label.getPosition === 'function') {
+          return options.label.getPosition();
+        }
+        return 'start';
+      },
+      
+      // Navigation
+      scrollToChip(chipOrIndex) {
+        if (options.chips && typeof options.chips.scrollToChip === 'function') {
+          options.chips.scrollToChip(chipOrIndex);
+        }
+        return this;
+      },
+      
+      enableKeyboardNavigation() {
+        if (options.keyboard && typeof options.keyboard.enableKeyboardNavigation === 'function') {
+          options.keyboard.enableKeyboardNavigation();
+        }
+        return this;
+      },
+      
+      // Event management
+      on(event, handler) {
+        if (options.events && typeof options.events.on === 'function') {
+          options.events.on(event, handler);
+        }
+        return this;
+      },
+      
+      off(event, handler) {
+        if (options.events && typeof options.events.off === 'function') {
+          options.events.off(event, handler);
+        }
+        return this;
+      },
+      
+      // Lifecycle management
+      destroy() {
+        if (options.lifecycle && typeof options.lifecycle.destroy === 'function') {
+          options.lifecycle.destroy();
+        }
+      }
+    };
+  };

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

@@ -27,16 +27,56 @@ export const withAPI = ({ disabled, lifecycle }: ApiOptions) =>
     // Track selected state internally
     let isSelected = component.element.classList.contains(`${component.getClass('chip')}--selected`);
     
+    // Store the value internally as well to ensure reliability
+    let chipValue = component.element.getAttribute('data-value') || null;
+    
     return {
       ...component as any,
       element: component.element,
       
       getValue() {
-        return component.element.getAttribute('data-value') || null;
+        // First try to get from the element's attribute
+        const attrValue = component.element.getAttribute('data-value');
+        
+        // If we have an attribute value, update our internal value and return it
+        if (attrValue !== null) {
+          chipValue = attrValue;
+          return attrValue;
+        }
+        
+        // If we have an internal value, set it on the element and return it
+        if (chipValue !== null) {
+          component.element.setAttribute('data-value', chipValue);
+          return chipValue;
+        }
+        
+        // If we have text content, derive a value from it
+        const textElement = component.element.querySelector(`.${component.getClass('chip')}-text`);
+        if (textElement && textElement.textContent) {
+          // Convert text like "Ocean Theme" to "ocean"
+          const text = textElement.textContent;
+          if (text.includes(' Theme')) {
+            chipValue = text.replace(' Theme', '').toLowerCase();
+          } else {
+            chipValue = text.toLowerCase().replace(/\s+/g, '-');
+          }
+          
+          // Set the derived value on the element
+          component.element.setAttribute('data-value', chipValue);
+          return chipValue;
+        }
+        
+        return null;
       },
       
       setValue(value: string) {
-        component.element.setAttribute('data-value', value || '');
+        if (value !== null && value !== undefined) {
+          chipValue = value;
+          component.element.setAttribute('data-value', value);
+        } else {
+          chipValue = null;
+          component.element.removeAttribute('data-value');
+        }
         return this;
       },