mtrl 0.3.0 → 0.3.2

package/src/components/button/api.ts

@@ -1,6 +1,11 @@
 // src/components/button/api.ts
 import { ButtonComponent } from './types';
 
+/**
+ * API configuration options for button component
+ * @category Components
+ * @internal
+ */
 interface ApiOptions {
   disabled: {
     enable: () => void;
@@ -11,6 +16,11 @@ interface ApiOptions {
   };
 }
 
+/**
+ * Component with required elements and methods for API enhancement
+ * @category Components
+ * @internal
+ */
 interface ComponentWithElements {
   element: HTMLElement;
   text: {
@@ -27,9 +37,13 @@ interface ComponentWithElements {
 }
 
 /**
- * Enhances a button component with API methods
+ * Enhances a button component with API methods.
+ * This follows the higher-order function pattern to add public API methods
+ * to the component, making them available to the end user.
+ * 
  * @param {ApiOptions} options - API configuration options
  * @returns {Function} Higher-order function that adds API methods to component
+ * @category Components
  * @internal This is an internal utility for the Button component
  */
 export const withAPI = ({ disabled, lifecycle }: ApiOptions) => 
@@ -37,52 +51,100 @@ export const withAPI = ({ disabled, lifecycle }: ApiOptions) =>
     ...component as any,
     element: component.element as HTMLButtonElement,
     
+    /**
+     * Gets the button's value attribute
+     * @returns Current value of the button
+     */
     getValue: () => component.element.value,
     
+    /**
+     * Sets the button's value attribute
+     * @param value - New value to set
+     * @returns Button component for method chaining
+     */
     setValue(value: string) {
       component.element.value = value;
       return this;
     },
     
+    /**
+     * Enables the button, making it interactive
+     * @returns Button component for method chaining
+     */
     enable() {
       disabled.enable();
       return this;
     },
     
+    /**
+     * Disables the button, making it non-interactive
+     * @returns Button component for method chaining
+     */
     disable() {
       disabled.disable();
       return this;
     },
     
+    /**
+     * Sets the button's text content
+     * @param content - Text content to display
+     * @returns Button component for method chaining
+     */
     setText(content: string) {
       component.text.setText(content);
       this.updateCircularStyle();
       return this;
     },
     
+    /**
+     * Gets the button's current text content
+     * @returns Current text content
+     */
     getText() {
       return component.text.getText();
     },
     
+    /**
+     * Sets the button's icon HTML content
+     * @param icon - HTML string for the icon
+     * @returns Button component for method chaining
+     */
     setIcon(icon: string) {
       component.icon.setIcon(icon);
       this.updateCircularStyle();
       return this;
     },
     
+    /**
+     * Gets the button's current icon HTML content
+     * @returns Current icon HTML
+     */
     getIcon() {
       return component.icon.getIcon();
     },
 
+    /**
+     * Sets the button's aria-label attribute for accessibility
+     * @param label - Accessible label text
+     * @returns Button component for method chaining
+     */
     setAriaLabel(label: string) {
       component.element.setAttribute('aria-label', label);
       return this;
     },
     
+    /**
+     * Destroys the button component and cleans up resources
+     */
     destroy() {
       lifecycle.destroy();
     },
     
+    /**
+     * Updates the button's circular style based on content.
+     * If the button has an icon but no text, it will be styled as circular.
+     * @internal
+     */
     updateCircularStyle() {
       const hasText = component.text.getElement();
       if (!hasText && component.icon.getElement()) {

package/src/components/button/button.ts

@@ -18,6 +18,10 @@ import { createBaseConfig, getElementConfig, getApiConfig } from './config';
 /**
  * Creates a new Button component with the specified configuration.
  * 
+ * The Button component implements the Material Design 3 Button component guidelines
+ * with support for different variants, states, and features. It follows accessibility
+ * best practices and provides a rich API for state management.
+ * 
  * The Button component is created using a functional composition pattern,
  * applying various features through the pipe function. This approach allows
  * for flexible and modular component construction.
@@ -32,16 +36,45 @@ import { createBaseConfig, getElementConfig, getApiConfig } from './config';
  * 
  * @throws {Error} Throws an error if button creation fails for any reason
  * 
+ * @category Components
+ * 
  * @example
  * // Create a simple text button
  * const textButton = createButton({ text: 'Click me' });
+ * document.body.appendChild(textButton.element);
  * 
  * @example
- * // Create a primary button with an icon
+ * // Create a filled button with an icon
  * const primaryButton = createButton({ 
  *   text: 'Submit',
- *   variant: 'primary',
- *   icon: 'send'
+ *   variant: 'filled',
+ *   icon: '<svg>...</svg>'
+ * });
+ * 
+ * // Add a click event handler
+ * primaryButton.on('click', () => {
+ *   console.log('Button clicked');
+ * });
+ * 
+ * @example
+ * // Create an outlined button with event handling
+ * const submitButton = createButton({
+ *   text: 'Save',
+ *   variant: 'outlined'
+ * });
+ * 
+ * submitButton.on('click', async () => {
+ *   submitButton.disable(); // Disable during async operation
+ *   await saveData();
+ *   submitButton.enable();  // Re-enable when done
+ * });
+ * 
+ * @example
+ * // Create an icon-only button (circular)
+ * const iconButton = createButton({
+ *   icon: '<svg>...</svg>',
+ *   ariaLabel: 'Add to favorites', // Important for accessibility
+ *   variant: 'filled'
  * });
  * 
  * @example
@@ -50,6 +83,9 @@ import { createBaseConfig, getElementConfig, getApiConfig } from './config';
  *   text: 'Not available',
  *   disabled: true
  * });
+ * 
+ * // Later, enable the button when available
+ * disabledButton.enable();
  */
 const createButton = (config: ButtonConfig = {}) => {
   const baseConfig = createBaseConfig(config);

package/src/components/button/config.ts

@@ -7,7 +7,10 @@ import {
 import { ButtonConfig } from './types';
 
 /**
- * Default configuration for the Button component
+ * Default configuration for the Button component.
+ * These values will be used when not explicitly specified by the user.
+ * 
+ * @category Components
  */
 export const defaultConfig: ButtonConfig = {
   variant: 'filled',
@@ -16,17 +19,26 @@ export const defaultConfig: ButtonConfig = {
 };
 
 /**
- * Creates the base configuration for Button component
+ * Creates the base configuration for Button component by merging user-provided
+ * config with default values.
+ * 
  * @param {ButtonConfig} config - User provided configuration
  * @returns {ButtonConfig} Complete configuration with defaults applied
+ * @category Components
+ * @internal
  */
 export const createBaseConfig = (config: ButtonConfig = {}): ButtonConfig => 
   createComponentConfig(defaultConfig, config, 'button') as ButtonConfig;
 
 /**
- * Generates element configuration for the Button component
+ * Generates element configuration for the Button component.
+ * This function creates the necessary attributes and configuration
+ * for the DOM element creation process.
+ * 
  * @param {ButtonConfig} config - Button configuration
  * @returns {Object} Element configuration object for withElement
+ * @category Components
+ * @internal
  */
 export const getElementConfig = (config: ButtonConfig) => {
   // Create the attributes object
@@ -62,9 +74,14 @@ export const getElementConfig = (config: ButtonConfig) => {
 };
 
 /**
- * Creates API configuration for the Button component
+ * Creates API configuration for the Button component.
+ * This connects the core component features (like disabled state)
+ * to the public API methods exposed to users.
+ * 
  * @param {Object} comp - Component with disabled and lifecycle features
  * @returns {Object} API configuration object
+ * @category Components
+ * @internal
  */
 export const getApiConfig = (comp) => ({
   disabled: {

package/src/components/button/index.ts

@@ -1,12 +1,37 @@
 // src/components/button/index.ts
+
+/**
+ * Button component module
+ * @module components/button
+ */
+
 export { default } from './button'
 export { ButtonConfig, ButtonComponent, ButtonVariant } from './types'
 
-// Export common button variants for convenience
+/**
+ * Constants for button variants - use these instead of string literals
+ * for better code completion and type safety.
+ * 
+ * @example
+ * import { createButton, BUTTON_VARIANTS } from 'mtrl';
+ * 
+ * // Create a filled button
+ * const primaryButton = createButton({ 
+ *   text: 'Submit',
+ *   variant: BUTTON_VARIANTS.FILLED 
+ * });
+ * 
+ * @category Components
+ */
 export const BUTTON_VARIANTS = {
+  /** Primary action button with solid background (high emphasis) */
   FILLED: 'filled',
+  /** Secondary action button with medium emphasis */
   TONAL: 'tonal',
+  /** Button with outline border and transparent background */
   OUTLINED: 'outlined',
+  /** Button with slight elevation/shadow */
   ELEVATED: 'elevated',
+  /** Button that appears as text without background or border (low emphasis) */
   TEXT: 'text'
 } as const;

package/src/components/button/types.ts

@@ -1,8 +1,14 @@
 // src/components/button/types.ts
 
 /**
- * Button variant types
+ * Button variant types - controls the visual style of the button
  * @category Components
+ * @remarks
+ * - filled: Primary action button with solid background (high emphasis)
+ * - tonal: Secondary action button with medium emphasis
+ * - outlined: Button with outline border and transparent background
+ * - elevated: Button with slight elevation/shadow
+ * - text: Button that appears as text without background or border (low emphasis)
  */
 export type ButtonVariant = 'filled' | 'tonal' | 'outlined' | 'elevated' | 'text';
 

package/src/components/card/api.ts

@@ -2,21 +2,31 @@
 import { BaseComponent, CardComponent, ApiOptions } from './types';
 
 /**
- * Enhances a card component with API methods
+ * Enhances a card component with API methods.
+ * This follows the higher-order function pattern to add public API methods
+ * to the component, making them available to the end user.
  * 
  * @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 Card component
+ * @category Components
  */
 export const withAPI = ({ lifecycle }: ApiOptions) => (component: BaseComponent): CardComponent => ({
   ...component,
   element: component.element,
 
   /**
-   * Adds content to the card
+   * Adds content to the card.
+   * This method appends content to the card component.
    * 
    * @param {HTMLElement} contentElement - The content element to add
    * @returns {CardComponent} The card instance for chaining
+   * @example
+   * ```typescript
+   * const content = document.createElement('div');
+   * content.className = 'mtrl-card-content';
+   * content.textContent = 'Card content goes here';
+   * card.addContent(content);
+   * ```
    */
   addContent(contentElement: HTMLElement): CardComponent {
     if (contentElement && contentElement.classList.contains(`${component.getClass('card')}-content`)) {
@@ -72,11 +82,24 @@ export const withAPI = ({ lifecycle }: ApiOptions) => (component: BaseComponent)
   },
 
   /**
-   * Adds media to the card
+   * Adds media to the card.
+   * Places media elements at the specified position in the card.
    * 
    * @param {HTMLElement} mediaElement - The media element to add
    * @param {string} [position='top'] - Position to place media ('top', 'bottom')
    * @returns {CardComponent} The card instance for chaining
+   * @example
+   * ```typescript
+   * // Creating media element
+   * const media = document.createElement('div');
+   * media.className = 'mtrl-card-media';
+   * 
+   * // Adding at the top (default)
+   * card.addMedia(media);
+   * 
+   * // Or adding at the bottom
+   * card.addMedia(media, 'bottom');
+   * ```
    */
   addMedia(mediaElement: HTMLElement, position: 'top' | 'bottom' = 'top'): CardComponent {
     if (mediaElement && mediaElement.classList.contains(`${component.getClass('card')}-media`)) {
@@ -90,10 +113,27 @@ export const withAPI = ({ lifecycle }: ApiOptions) => (component: BaseComponent)
   },
 
   /**
-   * Sets the card actions section
+   * Sets the card actions section.
+   * Replaces any existing actions with the provided actions element.
+   * Actions typically contain buttons or other interactive controls,
+   * and are placed at the bottom of the card.
    * 
    * @param {HTMLElement} actionsElement - The actions element to add
    * @returns {CardComponent} The card instance for chaining
+   * @example
+   * ```typescript
+   * // Create actions container
+   * const actions = document.createElement('div');
+   * actions.className = 'mtrl-card-actions';
+   * 
+   * // Add buttons to actions
+   * const button = document.createElement('button');
+   * button.textContent = 'Action';
+   * actions.appendChild(button);
+   * 
+   * // Set actions on card
+   * card.setActions(actions);
+   * ```
    */
   setActions(actionsElement: HTMLElement): CardComponent {
     if (actionsElement && actionsElement.classList.contains(`${component.getClass('card')}-actions`)) {
@@ -110,10 +150,23 @@ export const withAPI = ({ lifecycle }: ApiOptions) => (component: BaseComponent)
   },
 
   /**
-   * Makes the card draggable
+   * Makes the card draggable.
+   * Sets up native HTML5 drag and drop functionality and adds appropriate
+   * accessibility attributes. Automatically updates ARIA attributes during drag.
    * 
    * @param {Function} [dragStartCallback] - Callback for drag start event
    * @returns {CardComponent} The card instance for chaining
+   * @example
+   * ```typescript
+   * // Basic draggable card
+   * card.makeDraggable();
+   * 
+   * // With custom drag start handler
+   * card.makeDraggable((event) => {
+   *   // Set custom data or perform other actions on drag start
+   *   event.dataTransfer.setData('text/plain', 'Card data');
+   * });
+   * ```
    */
   makeDraggable(dragStartCallback?: (event: DragEvent) => void): CardComponent {
     component.element.setAttribute('draggable', 'true');
@@ -134,10 +187,19 @@ export const withAPI = ({ lifecycle }: ApiOptions) => (component: BaseComponent)
   },
 
   /**
-   * Sets focus to the card
-   * Useful for programmatic focus management
+   * Sets focus to the card.
+   * Useful for programmatic focus management, especially in keyboard navigation
+   * scenarios or after dynamic content changes.
    * 
    * @returns {CardComponent} The card instance for chaining
+   * @example
+   * ```typescript
+   * // Focus the card
+   * card.focus();
+   * 
+   * // Can be chained with other methods
+   * card.setHeader(headerElement).focus();
+   * ```
    */
   focus(): CardComponent {
     component.element.focus();
@@ -145,7 +207,14 @@ export const withAPI = ({ lifecycle }: ApiOptions) => (component: BaseComponent)
   },
 
   /**
-   * Destroys the card component and removes event listeners
+   * Destroys the card component and removes event listeners.
+   * Call this method when the card is no longer needed to prevent memory leaks.
+   * 
+   * @example
+   * ```typescript
+   * // Clean up resources when done with the card
+   * card.destroy();
+   * ```
    */
   destroy(): void {
     lifecycle.destroy();

package/src/components/card/card.ts

@@ -20,13 +20,68 @@ import {
 import { withElevation } from './features';
 
 /**
- * Creates a new Card component following Material Design 3 principles
+ * Creates a new Card component following Material Design 3 principles.
  * 
  * Material Design 3 Cards are surfaces that display content and actions about a single topic.
- * Cards can contain text, media, and UI controls.
+ * Cards can contain text, media, and UI controls. They provide entry points to more 
+ * detailed information and can include interactive elements.
  * 
  * @param {CardSchema} config - Card configuration object
- * @returns {CardComponent} Card component instance
+ * @returns {CardComponent} Card component instance with the following API methods:
+ * - `addContent(contentElement)`: Adds content to the card
+ * - `setHeader(headerElement)`: Sets the card header
+ * - `addMedia(mediaElement, position)`: Adds media to the card
+ * - `setActions(actionsElement)`: Sets the card actions section
+ * - `makeDraggable(dragStartCallback)`: Makes the card draggable
+ * - `focus()`: Sets focus to the card
+ * - `destroy()`: Destroys the card component and removes event listeners
+ * 
+ * @throws {Error} Throws an error if card creation fails
+ * @category Components
+ * @example
+ * ```typescript
+ * // Create a basic card
+ * const card = createCard({
+ *   variant: 'elevated',
+ *   header: {
+ *     title: 'Card Title',
+ *     subtitle: 'Secondary text'
+ *   },
+ *   content: {
+ *     text: 'Card content goes here.'
+ *   }
+ * });
+ * 
+ * // Create an interactive card with actions
+ * const cardWithActions = createCard({
+ *   variant: 'filled',
+ *   interactive: true,
+ *   header: { title: 'Interactive Card' },
+ *   content: { text: 'Click the buttons below.' },
+ *   buttons: [
+ *     { text: 'Action 1', variant: 'text' },
+ *     { text: 'Action 2', variant: 'filled' }
+ *   ]
+ * });
+ * 
+ * // Card with media
+ * const mediaCard = createCard({
+ *   media: {
+ *     src: '/path/to/image.jpg',
+ *     alt: 'Descriptive alt text',
+ *     aspectRatio: '16:9'
+ *   },
+ *   header: { title: 'Media Card' }
+ * });
+ * 
+ * // Using API methods
+ * const card = createCard();
+ * const content = document.createElement('div');
+ * content.className = 'mtrl-card-content';
+ * content.textContent = 'Added programmatically';
+ * card.addContent(content);
+ * card.makeDraggable();
+ * ```
  */
 const createCard = (config: CardSchema = {}): CardComponent => {
   // Process inline configuration (map shorthand properties)

package/src/components/card/config.ts

@@ -12,8 +12,11 @@ import {
 import { CardComponent, CardSchema, ButtonConfig, BaseComponent } from './types';
 
 /**
- * Default configuration for the Card component
+ * Default configuration for the Card component.
+ * These values are used when no configuration is provided.
+ * 
  * @const {CardSchema}
+ * @category Components
  */
 export const defaultConfig: CardSchema = {
   variant: 'elevated',
@@ -24,11 +27,18 @@ export const defaultConfig: CardSchema = {
 };
 
 /**
- * Processes inline configuration options into standard config format
- * Maps shorthand properties to their proper config counterparts
+ * Processes inline configuration options into standard config format.
+ * Maps shorthand properties to their proper config counterparts for ease of use.
  * 
  * @param {CardSchema} config - Raw card configuration
  * @returns {CardSchema} Processed configuration
+ * @category Components
+ * @example
+ * ```typescript
+ * // Before processing, these are equivalent:
+ * { header: { title: 'Example' } }
+ * { headerConfig: { title: 'Example' } }
+ * ```
  */
 export const processInlineConfig = (config: CardSchema): CardSchema => {
   const processedConfig: CardSchema = { ...config };
@@ -54,11 +64,13 @@ export const processInlineConfig = (config: CardSchema): CardSchema => {
 };
 
 /**
- * Applies inline configuration to a card component
- * Adds configured elements to the card in the correct order
+ * Applies inline configuration to a card component.
+ * Adds configured elements to the card in the correct order following
+ * Material Design layout guidelines. Handles media, header, content, and actions placement.
  * 
  * @param {CardComponent} card - Card component to configure
  * @param {CardSchema} config - Processed configuration
+ * @category Components
  */
 export const applyInlineConfiguration = (card: CardComponent, config: CardSchema): void => {
   // Add media (top position) if configured
@@ -116,19 +128,27 @@ export const applyInlineConfiguration = (card: CardComponent, config: CardSchema
 };
 
 /**
- * Creates the base configuration for Card component
+ * Creates the base configuration for Card component.
+ * Merges user-provided configuration with default values,
+ * ensuring all required properties are set.
  * 
  * @param {CardSchema} config - User provided configuration
  * @returns {CardSchema} Complete configuration with defaults applied
+ * @category Components
+ * 
  */
 export const createBaseConfig = (config: CardSchema = {}): CardSchema => 
   createComponentConfig(defaultConfig, config, 'card') as CardSchema;
 
 /**
- * Generates element configuration for the Card component
+ * Generates element configuration for the Card component.
+ * Sets up DOM attributes, accessibility features, and event forwarding
+ * based on the card's configuration.
  * 
  * @param {CardSchema} config - Card configuration
  * @returns {Object} Element configuration object for withElement
+ * @category Components
+ * 
  */
 export const getElementConfig = (config: CardSchema) => {
   const isInteractive = config.interactive || config.clickable;
@@ -178,10 +198,13 @@ export const getElementConfig = (config: CardSchema) => {
 };
 
 /**
- * Creates API configuration for the Card component
+ * Creates API configuration for the Card component.
+ * Prepares the configuration needed for the card's public API methods.
  * 
  * @param {Object} comp - Component with lifecycle feature
  * @returns {Object} API configuration object
+ * @category Components
+ * 
  */
 export const getApiConfig = (comp: any) => ({
   lifecycle: {
@@ -190,7 +213,10 @@ export const getApiConfig = (comp: any) => ({
 });
 
 /**
- * Card elevation levels
+ * Card elevation levels in density-independent pixels (dp).
+ * Following Material Design 3 elevation system guidelines.
+ * 
+ * @category Components
  */
 export const CARD_ELEVATION_LEVELS = {
   LEVEL0: 0,
@@ -200,11 +226,15 @@ export const CARD_ELEVATION_LEVELS = {
 };
 
 /**
- * Adds interactive behavior to card component
- * Uses the MTRL elevation system for proper elevation levels
+ * Adds interactive behavior to card component.
+ * Uses the mtrl elevation system for proper elevation levels according to Material Design 3
+ * guidelines. Implements mouse, keyboard, and touch interactions with appropriate
+ * visual feedback and accessibility support.
  * 
  * @param {BaseComponent} comp - Card component
  * @returns {BaseComponent} Enhanced card component
+ * @category Components
+ * 
  */
 export const withInteractiveBehavior = (comp: BaseComponent): BaseComponent => {
   const config = comp.config;