mtrl 0.3.0 → 0.3.2

package/src/components/divider/config.ts

@@ -3,62 +3,141 @@ import { createComponentConfig } from '../../core/config/component-config';
 
 /**
  * Configuration options for divider components
+ * 
+ * Controls the appearance, orientation, and behavior of Material Design 3 dividers.
+ * 
+ * @category Components
  */
 export interface DividerConfig {
   /**
    * CSS class prefix (defaults to 'mtrl')
+   * 
+   * Used for generating BEM-style class names for the component
    */
   prefix?: string;
   
   /**
    * CSS class to add to the divider
+   * 
+   * Additional classes for custom styling needs
+   * 
+   * @example 'my-custom-divider'
    */
   class?: string;
   
   /**
-   * Orientation of the divider ('horizontal' or 'vertical')
+   * Orientation of the divider
+   * 
+   * - 'horizontal': Creates a horizontal line (default)
+   * - 'vertical': Creates a vertical line
+   * 
    * @default 'horizontal'
+   * 
+   * @example
+   * ```typescript
+   * // Create a vertical divider
+   * createDivider({ orientation: 'vertical' })
+   * ```
    */
   orientation?: 'horizontal' | 'vertical';
   
   /**
-   * Variant of the divider ('full-width' or 'inset')
+   * Variant of the divider
+   * 
+   * Controls how the divider is inset within its container:
+   * - 'full-width': Spans the entire width/height (default)
+   * - 'inset': Adds space at the start (left for horizontal, top for vertical)
+   * - 'middle-inset': Adds space at both start and end
+   * 
+   * Most commonly used in lists to align dividers with text content.
+   * 
    * @default 'full-width'
+   * 
+   * @example
+   * ```typescript
+   * // Create a list divider with left inset
+   * createDivider({ variant: 'inset' })
+   * ```
    */
   variant?: 'full-width' | 'inset' | 'middle-inset';
   
   /**
    * Custom inset value (left margin for horizontal, top margin for vertical)
-   * @default 16 for 'inset', undefined for 'full-width'
+   * 
+   * Overrides the default inset spacing at the start of the divider.
+   * Only applies when variant is 'inset' or 'middle-inset'.
+   * 
+   * @default 16 for 'inset' and 'middle-inset' variants
+   * 
+   * @example
+   * ```typescript
+   * // Create a divider with 24px left inset
+   * createDivider({ variant: 'inset', insetStart: 24 })
+   * ```
    */
   insetStart?: number;
   
   /**
    * Custom inset end value (right margin for horizontal, bottom margin for vertical)
-   * @default 0 for 'inset', undefined for 'full-width'
+   * 
+   * Overrides the default inset spacing at the end of the divider.
+   * Only applies when variant is 'middle-inset'.
+   * 
+   * @default 0 for 'inset', 16 for 'middle-inset'
+   * 
+   * @example
+   * ```typescript
+   * // Create a divider with custom insets on both sides
+   * createDivider({ variant: 'middle-inset', insetStart: 16, insetEnd: 24 })
+   * ```
    */
   insetEnd?: number;
   
   /**
-   * Color of the divider (uses 'outline-variant' from theme by default)
+   * Color of the divider
+   * 
+   * Sets a custom color for the divider. Accepts any valid CSS color value.
+   * By default, dividers use the 'outline-variant' color from the Material theme.
+   * 
+   * @example
+   * ```typescript
+   * // Create a blue divider
+   * createDivider({ color: '#2196F3' })
+   * 
+   * // Create a divider with a semi-transparent color
+   * createDivider({ color: 'rgba(0, 0, 0, 0.12)' })
+   * ```
    */
   color?: string;
   
   /**
    * Thickness of the divider in pixels
+   * 
+   * Controls the thickness (height for horizontal, width for vertical) of the divider.
+   * Material Design 3 typically uses 1px thickness for dividers.
+   * 
    * @default 1
+   * 
+   * @example
+   * ```typescript
+   * // Create a bold divider
+   * createDivider({ thickness: 2 })
+   * ```
    */
   thickness?: number;
   
   /**
    * Used internally for component composition
-   * @private
+   * 
+   * @internal
    */
   componentName?: string;
 }
 
 /**
  * Default configuration for dividers
+ * 
+ * @internal
  */
 export const defaultConfig: Partial<DividerConfig> = {
   orientation: 'horizontal',
@@ -69,8 +148,13 @@ export const defaultConfig: Partial<DividerConfig> = {
 /**
  * Creates a base configuration object for divider
  * 
+ * Merges user-provided configuration with default values and ensures
+ * all required properties have values.
+ * 
  * @param config - User provided configuration
  * @returns Complete configuration with defaults applied
+ * 
+ * @internal
  */
 export const createBaseConfig = (config: DividerConfig = {}): DividerConfig => {
   return createComponentConfig(

package/src/components/divider/divider.ts

@@ -11,10 +11,40 @@ import { withOrientation, withInset, withStyle } from './features';
 import { DividerComponent } from './types';
 
 /**
- * Creates a divider component
+ * Creates a new Divider component with the specified configuration.
+ * 
+ * Dividers are thin lines that separate content into distinct sections following
+ * Material Design 3 guidelines. They can be horizontal or vertical, and offer
+ * various customization options for inset, thickness, and color.
  * 
  * @param config - Divider configuration options
- * @returns Divider component instance
+ * @returns Divider component instance with methods for managing appearance and behavior
+ * 
+ * @throws {Error} If divider creation fails due to invalid configuration
+ * 
+ * @category Components
+ * 
+ * @example
+ * ```typescript
+ * // Create a basic horizontal divider
+ * const divider = createDivider();
+ * container.appendChild(divider.element);
+ * 
+ * // Create a vertical divider with custom styling
+ * const separator = createDivider({
+ *   orientation: 'vertical',
+ *   thickness: 2,
+ *   color: '#2196F3',
+ *   variant: 'middle-inset',
+ *   insetStart: 8,
+ *   insetEnd: 8
+ * });
+ * 
+ * // Later, change the divider's appearance
+ * divider.setColor('var(--md-sys-color-outline)');
+ * divider.setThickness(1);
+ * divider.setVariant('inset');
+ * ```
  */
 export const createDivider = (config: DividerConfig = {}): DividerComponent => {
   // Process configuration

package/src/components/divider/features.ts

@@ -6,8 +6,14 @@ import { DividerComponent } from './types';
 /**
  * Adds orientation functionality to divider
  * 
+ * Higher-order function that enhances a component with the ability to be
+ * oriented horizontally (default) or vertically. Controls the appropriate
+ * CSS classes and dimensional styling based on orientation.
+ * 
  * @param config - Divider configuration
  * @returns Function that enhances a component with orientation capabilities
+ * 
+ * @internal
  */
 export const withOrientation = (config: DividerConfig) => 
   <C extends ElementComponent & BaseComponent>(component: C): C & Partial<DividerComponent> => {
@@ -66,8 +72,18 @@ export const withOrientation = (config: DividerConfig) =>
 /**
  * Adds inset functionality to divider
  * 
+ * Higher-order function that enhances a component with the ability to have
+ * customized inset spacing. Supports three variants (full-width, inset, middle-inset)
+ * and allows fine-grained control over start and end insets.
+ * 
+ * Insets are applied as margins in the appropriate direction based on orientation:
+ * - For horizontal dividers: left/right margins
+ * - For vertical dividers: top/bottom margins
+ * 
  * @param config - Divider configuration
  * @returns Function that enhances a component with inset capabilities
+ * 
+ * @internal
  */
 export const withInset = (config: DividerConfig) => 
   <C extends ElementComponent & Partial<DividerComponent>>(component: C): C & Partial<DividerComponent> => {
@@ -164,8 +180,18 @@ export const withInset = (config: DividerConfig) =>
 /**
  * Adds style customization to divider
  * 
+ * Higher-order function that enhances a component with visual customization
+ * capabilities, including:
+ * - Custom thickness (height for horizontal, width for vertical dividers)
+ * - Custom colors (background-color CSS property)
+ * 
+ * These styling options allow dividers to be visually adapted to different
+ * design requirements while maintaining Material Design principles.
+ * 
  * @param config - Divider configuration
  * @returns Function that enhances a component with style capabilities
+ * 
+ * @internal
  */
 export const withStyle = (config: DividerConfig) => 
   <C extends ElementComponent & Partial<DividerComponent>>(component: C): C & Partial<DividerComponent> => {

package/src/components/divider/index.ts

@@ -1,5 +1,35 @@
 // src/components/divider/index.ts
 
+/**
+ * @module Divider
+ * 
+ * The Divider component provides horizontal or vertical lines that separate content into distinct sections.
+ * Dividers follow Material Design 3 guidelines for separating content in lists, layouts, and other UI containers.
+ * 
+ * Features:
+ * - Horizontal and vertical orientations
+ * - Multiple inset variants (full-width, inset, middle-inset)
+ * - Customizable thickness and color
+ * - Responsive to parent container
+ * 
+ * @example
+ * ```typescript
+ * // Create a standard horizontal divider
+ * const divider = createDivider();
+ * document.body.appendChild(divider.element);
+ * 
+ * // Create a vertical divider with custom styles
+ * const verticalDivider = createDivider({
+ *   orientation: 'vertical',
+ *   thickness: 2,
+ *   color: '#2196F3',
+ *   variant: 'middle-inset'
+ * });
+ * ```
+ * 
+ * @category Components
+ */
+
 // Use a more explicit export to avoid bundler confusion
 import { createDivider } from './divider';
 export { createDivider };

package/src/components/divider/types.ts

@@ -3,53 +3,130 @@ import { BaseComponent, ElementComponent } from '../../core/compose';
 
 /**
  * Divider component interface
+ * 
+ * Represents a Material Design 3 divider that separates content into distinct sections.
+ * Provides methods for configuring the appearance, orientation, and inset behavior.
+ * 
+ * @category Components
  */
 export interface DividerComponent extends BaseComponent, ElementComponent {
   /**
-   * Gets current orientation
-   * @returns Current orientation
+   * Gets current orientation of the divider
+   * 
+   * @returns Current orientation ('horizontal' or 'vertical')
+   * 
+   * @example
+   * ```typescript
+   * const divider = createDivider();
+   * const orientation = divider.getOrientation(); // Returns 'horizontal' by default
+   * ```
    */
   getOrientation: () => 'horizontal' | 'vertical';
   
   /**
    * Sets orientation of the divider
-   * @param orientation - New orientation
+   * 
+   * Changes the divider's orientation between horizontal (default) and vertical.
+   * This affects the divider's positioning, dimension constraints, and how insets are applied.
+   * 
+   * @param orientation - New orientation ('horizontal' or 'vertical')
    * @returns DividerComponent instance for chaining
+   * 
+   * @example
+   * ```typescript
+   * // Change a divider from horizontal to vertical
+   * divider.setOrientation('vertical');
+   * ```
    */
   setOrientation: (orientation: 'horizontal' | 'vertical') => DividerComponent;
   
   /**
-   * Gets current variant
-   * @returns Current variant
+   * Gets current variant of the divider
+   * 
+   * @returns Current variant ('full-width', 'inset', or 'middle-inset')
+   * 
+   * @example
+   * ```typescript
+   * const variant = divider.getVariant(); // Returns 'full-width' by default
+   * ```
    */
   getVariant: () => 'full-width' | 'inset' | 'middle-inset';
   
   /**
    * Sets variant of the divider
+   * 
+   * Changes how the divider is inset within its container:
+   * - 'full-width': Spans the entire width/height of the container (default)
+   * - 'inset': Adds space at the start (left for horizontal, top for vertical)
+   * - 'middle-inset': Adds space at both start and end
+   * 
    * @param variant - New variant
    * @returns DividerComponent instance for chaining
+   * 
+   * @example
+   * ```typescript
+   * // Create a list divider with left inset
+   * divider.setVariant('inset');
+   * 
+   * // Create a divider with space on both sides
+   * divider.setVariant('middle-inset');
+   * ```
    */
   setVariant: (variant: 'full-width' | 'inset' | 'middle-inset') => DividerComponent;
   
   /**
-   * Sets custom inset values
-   * @param insetStart - Start inset value
-   * @param insetEnd - End inset value
+   * Sets custom inset values for the divider
+   * 
+   * Allows fine-grained control over inset spacing, overriding the default values
+   * applied by the variant. Only applies if variant is 'inset' or 'middle-inset'.
+   * 
+   * @param insetStart - Start inset value in pixels (left for horizontal, top for vertical)
+   * @param insetEnd - End inset value in pixels (right for horizontal, bottom for vertical)
    * @returns DividerComponent instance for chaining
+   * 
+   * @example
+   * ```typescript
+   * // Create a divider with custom insets
+   * const divider = createDivider({ variant: 'inset' });
+   * divider.setInset(24, 8); // 24px from start, 8px from end
+   * ```
    */
   setInset: (insetStart?: number, insetEnd?: number) => DividerComponent;
   
   /**
    * Sets thickness of the divider
+   * 
+   * Changes the divider's thickness (height for horizontal, width for vertical).
+   * The default thickness is 1px, following Material Design 3 guidelines.
+   * 
    * @param thickness - Thickness in pixels
    * @returns DividerComponent instance for chaining
+   * 
+   * @example
+   * ```typescript
+   * // Create a bold divider
+   * divider.setThickness(2);
+   * ```
    */
   setThickness: (thickness: number) => DividerComponent;
   
   /**
    * Sets custom color for the divider
-   * @param color - CSS color value
+   * 
+   * By default, dividers use the 'outline-variant' color from the theme.
+   * This method allows setting a custom color via any valid CSS color value.
+   * 
+   * @param color - CSS color value (hex, rgb, rgba, hsl, etc.)
    * @returns DividerComponent instance for chaining
+   * 
+   * @example
+   * ```typescript
+   * // Create a blue divider
+   * divider.setColor('#2196F3');
+   * 
+   * // Create a semi-transparent divider
+   * divider.setColor('rgba(0, 0, 0, 0.12)');
+   * ```
    */
   setColor: (color: string) => DividerComponent;
 }

package/src/components/extended-fab/api.ts

@@ -1,40 +1,92 @@
 // src/components/extended-fab/api.ts
 import { ExtendedFabComponent } from './types';
 
+/**
+ * API configuration options for the Extended FAB component
+ * 
+ * @category Components
+ * @internal
+ */
 interface ApiOptions {
+  /**
+   * Disabled state management API
+   */
   disabled: {
+    /** Enables the component */
     enable: () => void;
+    /** Disables the component */
     disable: () => void;
   };
+  
+  /**
+   * Lifecycle management API
+   */
   lifecycle: {
+    /** Destroys the component */
     destroy: () => void;
   };
+  
+  /**
+   * Text content management API
+   */
   text: {
+    /** Sets text content */
     setText: (text: string) => any;
+    /** Gets text content */
     getText: () => string;
   };
+  
+  /**
+   * Base class name for the Extended FAB
+   */
   className: string;
 }
 
+/**
+ * Base component with element properties
+ * 
+ * @category Components
+ * @internal
+ */
 interface ComponentWithElements {
+  /** The DOM element */
   element: HTMLElement;
+  
+  /** Icon management */
   icon: {
+    /** Sets icon HTML content */
     setIcon: (html: string) => any;
+    /** Gets icon HTML content */
     getIcon: () => string;
+    /** Gets icon DOM element */
     getElement: () => HTMLElement | null;
   };
+  
+  /** Text management */
   text: {
+    /** Sets text content */
     setText: (text: string) => any;
+    /** Gets text content */
     getText: () => string;
+    /** Gets text DOM element */
     getElement: () => HTMLElement | null;
   };
+  
+  /** Gets a class name with component's prefix */
   getClass: (name: string) => string;
 }
 
 /**
- * Enhances an Extended FAB component with API methods
+ * Enhances an Extended FAB component with public API methods
+ * 
+ * Higher-order function that adds the full public API to the Extended FAB component,
+ * exposing methods for changing appearance, handling state, managing position,
+ * and controlling the collapse/expand behavior.
+ * 
  * @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 Extended FAB component
  */
 export const withAPI = ({ disabled, lifecycle, text, className }: ApiOptions) => 

package/src/components/extended-fab/config.ts

@@ -8,6 +8,12 @@ import { ExtendedFabConfig } from './types';
 
 /**
  * Default configuration for the Extended FAB component
+ * 
+ * Provides reasonable defaults for creating Extended FABs
+ * according to Material Design 3 guidelines.
+ * 
+ * @category Components
+ * @internal
  */
 export const defaultConfig: ExtendedFabConfig = {
   variant: 'primary',
@@ -19,16 +25,31 @@ export const defaultConfig: ExtendedFabConfig = {
 
 /**
  * Creates the base configuration for Extended FAB component
+ * 
+ * Merges user-provided configuration with default values and validates
+ * the configuration to ensure all required properties have values.
+ * 
  * @param {ExtendedFabConfig} config - User provided configuration
  * @returns {ExtendedFabConfig} Complete configuration with defaults applied
+ * 
+ * @category Components
+ * @internal
  */
 export const createBaseConfig = (config: ExtendedFabConfig = {}): ExtendedFabConfig => 
   createComponentConfig(defaultConfig, config, 'extended-fab') as ExtendedFabConfig;
 
 /**
  * Generates element configuration for the Extended FAB component
+ * 
+ * Transforms the user-friendly ExtendedFabConfig into the internal format required
+ * by the withElement function. Creates all the appropriate CSS classes and attributes
+ * needed to properly render the Extended FAB in the DOM.
+ * 
  * @param {ExtendedFabConfig} config - Extended FAB configuration
  * @returns {Object} Element configuration object for withElement
+ * 
+ * @category Components
+ * @internal
  */
 export const getElementConfig = (config: ExtendedFabConfig) => {
   // Create the attributes object
@@ -91,8 +112,15 @@ export const getElementConfig = (config: ExtendedFabConfig) => {
 
 /**
  * Creates API configuration for the Extended FAB component
+ * 
+ * Provides access to various component sub-features like disabled state,
+ * lifecycle management, and text content.
+ * 
  * @param {Object} comp - Component with disabled and lifecycle features
- * @returns {Object} API configuration object
+ * @returns {Object} API configuration object for withAPI
+ * 
+ * @category Components
+ * @internal
  */
 export const getApiConfig = (comp: any) => ({
   disabled: {

package/src/components/extended-fab/extended-fab.ts

@@ -17,9 +17,25 @@ import { createBaseConfig, getElementConfig, getApiConfig } from './config';
 /**
  * Creates a new Extended Floating Action Button (Extended FAB) component
  * 
+ * Extended FABs are a variant of the standard Floating Action Button that include
+ * both an icon and text label. They're designed for primary actions that need
+ * more description than just an icon, and can be positioned in various corners
+ * of the interface.
+ * 
+ * Extended FABs follow Material Design 3 guidelines with support for:
+ * - Multiple color variants (primary, secondary, tertiary, surface)
+ * - Icon and text label configuration
+ * - Fixed or fluid width
+ * - Automatic collapse on scroll
+ * - Various positioning options
+ * 
  * @param {ExtendedFabConfig} config - Extended FAB configuration object
  * @returns {ExtendedFabComponent} Extended FAB component instance
  * 
+ * @throws {Error} If the Extended FAB cannot be created due to invalid configuration
+ * 
+ * @category Components
+ * 
  * @example
  * ```typescript
  * // Create a basic Extended FAB with icon and text
@@ -42,6 +58,18 @@ import { createBaseConfig, getElementConfig, getApiConfig } from './config';
  * extendedFab.on('click', () => {
  *   console.log('Extended FAB clicked');
  * });
+ * 
+ * // Attach to DOM
+ * document.body.appendChild(extendedFab.element);
+ * 
+ * // Programmatically collapse and expand
+ * document.querySelector('#collapseBtn').addEventListener('click', () => {
+ *   extendedFab.collapse();
+ * });
+ * 
+ * document.querySelector('#expandBtn').addEventListener('click', () => {
+ *   extendedFab.expand();
+ * });
  * ```
  */
 const createExtendedFab = (config: ExtendedFabConfig = {}): ExtendedFabComponent => {

package/src/components/extended-fab/index.ts

@@ -1,4 +1,40 @@
 // src/components/extended-fab/index.ts
+
+/**
+ * @module ExtendedFab
+ * 
+ * Extended Floating Action Button (Extended FAB) component following Material Design 3 guidelines.
+ * Extended FABs are wider than standard FABs, containing both an icon and a text label.
+ * They provide a primary action that's prominently displayed and easily accessible.
+ * 
+ * Features:
+ * - Multiple variants (primary, secondary, tertiary, surface)
+ * - Icon and text label combination
+ * - Configurable positioning
+ * - Collapsible behavior on scroll
+ * - Ripple effect on interaction
+ * - Accessibility support
+ * 
+ * @example
+ * ```typescript
+ * // Create a primary Extended FAB with icon and text
+ * const extendedFab = createExtendedFab({
+ *   text: 'Create',
+ *   icon: '<svg>...</svg>',
+ *   position: 'bottom-right',
+ *   collapseOnScroll: true
+ * });
+ * 
+ * // Attach to DOM and add click handler
+ * container.appendChild(extendedFab.element);
+ * extendedFab.on('click', () => {
+ *   console.log('Extended FAB clicked');
+ * });
+ * ```
+ * 
+ * @category Components
+ */
+
 export { default, default as createExtendedFab } from './extended-fab';
 export {
   ExtendedFabConfig,