mtrl 0.3.1 → 0.3.3

package/src/components/fab/api.ts

@@ -1,32 +1,72 @@
 // src/components/fab/api.ts
 import { FabComponent } from './types';
 
+/**
+ * API configuration options for the 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;
   };
+  
+  /**
+   * Base class name for the 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;
   };
+  
+  /** Gets a class name with component's prefix */
   getClass: (name: string) => string;
 }
 
 /**
- * Enhances a FAB component with API methods
+ * Enhances a FAB component with public API methods
+ * 
+ * Higher-order function that adds the full public API to the FAB component,
+ * exposing methods for changing appearance, handling state, and managing position.
+ * 
  * @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 FAB component
+ * 
+ * @category Components
+ * @internal
  */
 export const withAPI = ({ disabled, lifecycle, className }: ApiOptions) => 
   (component: ComponentWithElements): FabComponent => ({

package/src/components/fab/config.ts

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

@@ -16,14 +16,23 @@ import { createBaseConfig, getElementConfig, getApiConfig } from './config';
 /**
  * Creates a new Floating Action Button (FAB) component
  * 
+ * Floating Action Buttons (FABs) represent the primary action in an application.
+ * They're circular buttons that float above the UI, and typically contain an icon.
+ * FABs follow Material Design 3 guidelines with support for multiple variants,
+ * sizes, and positioning options.
+ * 
  * @param {FabConfig} config - FAB configuration object
  * @returns {FabComponent} FAB component instance
  * 
+ * @throws {Error} If the FAB cannot be created due to invalid configuration
+ * 
+ * @category Components
+ * 
  * @example
  * ```typescript
  * // Create a default FAB with a plus icon
  * const fab = createFab({
- *   icon: '<svg>...</svg>',
+ *   icon: '<svg viewBox="0 0 24 24"><path d="M19 13h-6v6h-2v-6H5v-2h6V5h2v6h6v2z"/></svg>',
  *   ariaLabel: 'Add new item'
  * });
  * 
@@ -35,10 +44,15 @@ import { createBaseConfig, getElementConfig, getApiConfig } from './config';
  *   position: 'bottom-right'
  * });
  * 
- * // Add click handler
+ * // Add click handler and attach to DOM
  * fab.on('click', () => {
  *   console.log('FAB clicked');
  * });
+ * document.body.appendChild(fab.element);
+ * 
+ * // Later, update the FAB's appearance
+ * fab.setIcon('<span class="material-icons">edit</span>');
+ * fab.setPosition('bottom-left');
  * ```
  */
 const createFab = (config: FabConfig = {}): FabComponent => {

package/src/components/fab/index.ts

@@ -1,4 +1,39 @@
 // src/components/fab/index.ts
+
+/**
+ * @module Fab
+ * 
+ * Floating Action Button (FAB) component following Material Design 3 guidelines.
+ * FABs are circular buttons that represent the primary action in an application.
+ * They are prominently displayed, typically in a fixed position overlaid on the UI.
+ * 
+ * Features:
+ * - Multiple variants (primary, secondary, tertiary, surface)
+ * - Three size options (small, default, large)
+ * - Configurable positioning
+ * - Icon support with customization
+ * - Ripple effect on interaction
+ * - Accessibility support
+ * 
+ * @example
+ * ```typescript
+ * // Create a primary FAB with a plus icon
+ * const fab = createFab({
+ *   icon: '<svg viewBox="0 0 24 24"><path d="M19 13h-6v6h-2v-6H5v-2h6V5h2v6h6v2z"/></svg>',
+ *   position: 'bottom-right',
+ *   ariaLabel: 'Add new item'
+ * });
+ * 
+ * // Attach to DOM and add click handler
+ * container.appendChild(fab.element);
+ * fab.on('click', () => {
+ *   console.log('FAB clicked');
+ * });
+ * ```
+ * 
+ * @category Components
+ */
+
 export { default, default as createFab } from './fab';
 export {
   FabConfig,