mtrl 0.2.5 → 0.2.7

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

@@ -0,0 +1,141 @@
+// src/components/extended-fab/api.ts
+import { ExtendedFabComponent } from './types';
+
+interface ApiOptions {
+  disabled: {
+    enable: () => void;
+    disable: () => void;
+  };
+  lifecycle: {
+    destroy: () => void;
+  };
+  text: {
+    setText: (text: string) => any;
+    getText: () => string;
+  };
+  className: string;
+}
+
+interface ComponentWithElements {
+  element: HTMLElement;
+  icon: {
+    setIcon: (html: string) => any;
+    getIcon: () => string;
+    getElement: () => HTMLElement | null;
+  };
+  text: {
+    setText: (text: string) => any;
+    getText: () => string;
+    getElement: () => HTMLElement | null;
+  };
+  getClass: (name: string) => string;
+}
+
+/**
+ * Enhances an Extended FAB component with API methods
+ * @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 Extended FAB component
+ */
+export const withAPI = ({ disabled, lifecycle, text, className }: ApiOptions) => 
+  (component: ComponentWithElements): ExtendedFabComponent => ({
+    ...component as any,
+    element: component.element as HTMLButtonElement,
+    
+    getValue: () => component.element.value,
+    
+    setValue(value: string) {
+      component.element.value = value;
+      return this;
+    },
+    
+    enable() {
+      disabled.enable();
+      return this;
+    },
+    
+    disable() {
+      disabled.disable();
+      return this;
+    },
+    
+    setIcon(icon: string) {
+      component.icon.setIcon(icon);
+      return this;
+    },
+    
+    getIcon() {
+      return component.icon.getIcon();
+    },
+    
+    setText(newText: string) {
+      text.setText(newText);
+      return this;
+    },
+    
+    getText() {
+      return text.getText();
+    },
+    
+    setPosition(position: string) {
+      // First remove any existing position classes
+      const positions = ['top-right', 'top-left', 'bottom-right', 'bottom-left'];
+      positions.forEach(pos => {
+        component.element.classList.remove(`${className}--${pos}`);
+      });
+      
+      // Add new position class
+      component.element.classList.add(`${className}--${position}`);
+      return this;
+    },
+    
+    getPosition() {
+      const positions = ['top-right', 'top-left', 'bottom-right', 'bottom-left'];
+      for (const pos of positions) {
+        if (component.element.classList.contains(`${className}--${pos}`)) {
+          return pos;
+        }
+      }
+      return null;
+    },
+    
+    lower() {
+      component.element.classList.add(`${className}--lowered`);
+      return this;
+    },
+    
+    raise() {
+      component.element.classList.remove(`${className}--lowered`);
+      return this;
+    },
+    
+    collapse() {
+      component.element.classList.add(`${className}--collapsed`);
+      
+      // Emit a custom event that can be listened to
+      const event = new CustomEvent('collapse', { 
+        bubbles: true, 
+        cancelable: true 
+      });
+      component.element.dispatchEvent(event);
+      
+      return this;
+    },
+    
+    expand() {
+      component.element.classList.remove(`${className}--collapsed`);
+      
+      // Emit a custom event that can be listened to
+      const event = new CustomEvent('expand', { 
+        bubbles: true, 
+        cancelable: true 
+      });
+      component.element.dispatchEvent(event);
+      
+      return this;
+    },
+    
+    destroy() {
+      lifecycle.destroy();
+    }
+  });

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

@@ -0,0 +1,108 @@
+// src/components/extended-fab/config.ts
+import { 
+  createComponentConfig, 
+  createElementConfig,
+  BaseComponentConfig 
+} from '../../core/config/component-config';
+import { ExtendedFabConfig } from './types';
+import { FAB_VARIANTS, EXTENDED_FAB_WIDTH } from './constants';
+
+/**
+ * Default configuration for the Extended FAB component
+ */
+export const defaultConfig: ExtendedFabConfig = {
+  variant: FAB_VARIANTS.PRIMARY,
+  type: 'button',
+  ripple: true,
+  iconPosition: 'start',
+  width: 'fixed'
+};
+
+/**
+ * Creates the base configuration for Extended FAB component
+ * @param {ExtendedFabConfig} config - User provided configuration
+ * @returns {ExtendedFabConfig} Complete configuration with defaults applied
+ */
+export const createBaseConfig = (config: ExtendedFabConfig = {}): ExtendedFabConfig => 
+  createComponentConfig(defaultConfig, config, 'extended-fab') as ExtendedFabConfig;
+
+/**
+ * Generates element configuration for the Extended FAB component
+ * @param {ExtendedFabConfig} config - Extended FAB configuration
+ * @returns {Object} Element configuration object for withElement
+ */
+export const getElementConfig = (config: ExtendedFabConfig) => {
+  // Create the attributes object
+  const attrs: Record<string, any> = {
+    type: config.type || 'button',
+    'aria-label': config.ariaLabel || config.text || (config.icon ? 'action' : undefined)
+  };
+  
+  // Build class list
+  let classNames = [`${config.prefix}-extended-fab`];
+  
+  // Add width class
+  if (config.width) {
+    classNames.push(`${config.prefix}-extended-fab--${config.width}`);
+  }
+  
+  // Add animation class if specified
+  if (config.animate) {
+    classNames.push(`${config.prefix}-extended-fab--animate-enter`);
+  }
+  
+  // Add position class if specified
+  if (config.position) {
+    classNames.push(`${config.prefix}-extended-fab--${config.position}`);
+  }
+  
+  // Add collapse-on-scroll class if specified
+  if (config.collapseOnScroll) {
+    classNames.push(`${config.prefix}-extended-fab--collapsible`);
+  }
+  
+  // Add user classes
+  if (config.class) {
+    classNames.push(config.class);
+  }
+  
+  // Only add disabled attribute if it's explicitly true
+  if (config.disabled === true) {
+    attrs.disabled = true;
+    classNames.push(`${config.prefix}-extended-fab--disabled`);
+  }
+  
+  return createElementConfig(config, {
+    tag: 'button',
+    attrs,
+    className: classNames,
+    forwardEvents: {
+      click: (component) => !component.element.disabled,
+      focus: true,
+      blur: true
+    },
+    interactive: true
+  });
+};
+
+/**
+ * Creates API configuration for the Extended FAB component
+ * @param {Object} comp - Component with disabled and lifecycle features
+ * @returns {Object} API configuration object
+ */
+export const getApiConfig = (comp: any) => ({
+  disabled: {
+    enable: () => comp.disabled.enable(),
+    disable: () => comp.disabled.disable()
+  },
+  lifecycle: {
+    destroy: () => comp.lifecycle.destroy()
+  },
+  className: comp.getClass('extended-fab'),
+  text: {
+    setText: (text: string) => comp.text.setText(text),
+    getText: () => comp.text.getText()
+  }
+});
+
+export default defaultConfig;

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

@@ -0,0 +1,36 @@
+// src/components/extended-fab/constants.ts
+import { FAB_VARIANTS, FAB_POSITIONS } from '../fab/constants'
+
+/**
+ * Re-export FAB variants for styling
+ */
+export { FAB_VARIANTS }
+
+/**
+ * Re-export FAB positions for fixed positioning
+ */
+export { FAB_POSITIONS }
+
+/**
+ * Extended FAB width behavior options
+ */
+export const EXTENDED_FAB_WIDTH = {
+  /** Fixed width based on content */
+  FIXED: 'fixed',
+  /** Fluid width that can adapt to container */
+  FLUID: 'fluid'
+}
+
+/**
+ * Extended FAB dimensions
+ */
+export const EXTENDED_FAB_DIMENSIONS = {
+  /** Standard height - 56dp */
+  HEIGHT: 56,
+  /** Minimum width - 80dp */
+  MIN_WIDTH: 80,
+  /** Padding - 16dp */
+  PADDING: 16,
+  /** Icon size - 24dp */
+  ICON_SIZE: 24
+}

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

@@ -0,0 +1,125 @@
+// src/components/extended-fab/extended-fab.ts
+import { pipe } from '../../core/compose';
+import { createBase, withElement } from '../../core/compose/component';
+import {
+  withEvents,
+  withIcon,
+  withVariant,
+  withRipple,
+  withDisabled,
+  withLifecycle,
+  withText
+} from '../../core/compose/features';
+import { withAPI } from './api';
+import { ExtendedFabConfig, ExtendedFabComponent } from './types';
+import { createBaseConfig, getElementConfig, getApiConfig } from './config';
+
+/**
+ * Creates a new Extended Floating Action Button (Extended FAB) component
+ * 
+ * @param {ExtendedFabConfig} config - Extended FAB configuration object
+ * @returns {ExtendedFabComponent} Extended FAB component instance
+ * 
+ * @example
+ * ```typescript
+ * // Create a basic Extended FAB with icon and text
+ * const extendedFab = createExtendedFab({
+ *   icon: '<svg>...</svg>',
+ *   text: 'Create',
+ *   ariaLabel: 'Create new item'
+ * });
+ * 
+ * // Create a tertiary Extended FAB with a custom position
+ * const customExtendedFab = createExtendedFab({
+ *   text: 'Add to cart',
+ *   icon: '<svg>...</svg>',
+ *   variant: 'tertiary',
+ *   position: 'bottom-right',
+ *   collapseOnScroll: true
+ * });
+ * 
+ * // Add click handler
+ * extendedFab.on('click', () => {
+ *   console.log('Extended FAB clicked');
+ * });
+ * ```
+ */
+const createExtendedFab = (config: ExtendedFabConfig = {}): ExtendedFabComponent => {
+  const fabConfig = createBaseConfig(config);
+
+  // Set up scroll collapse handler if needed
+  const setupScrollCollapse = (component: ExtendedFabComponent): void => {
+    if (fabConfig.collapseOnScroll) {
+      let lastScrollY = window.scrollY;
+      let ticking = false;
+      const scrollThreshold = 10; // Minimum scroll amount to trigger collapse/expand
+      
+      const handleScroll = () => {
+        if (!ticking) {
+          window.requestAnimationFrame(() => {
+            const currentScrollY = window.scrollY;
+            const scrollDelta = currentScrollY - lastScrollY;
+            
+            // If scrolling down beyond threshold, collapse
+            if (scrollDelta > scrollThreshold) {
+              component.collapse();
+            } 
+            // If scrolling up beyond threshold, expand
+            else if (scrollDelta < -scrollThreshold) {
+              component.expand();
+            }
+            // If at the top of the page, ensure expanded
+            if (currentScrollY <= 0) {
+              component.expand();
+            }
+            
+            lastScrollY = currentScrollY;
+            ticking = false;
+          });
+          
+          ticking = true;
+        }
+      };
+      
+      // Add scroll listener
+      window.addEventListener('scroll', handleScroll, { passive: true });
+      
+      // Ensure it's expanded by default
+      requestAnimationFrame(() => {
+        component.expand();
+      });
+      
+      // Clean up on destroy
+      const originalDestroy = component.destroy;
+      component.destroy = () => {
+        window.removeEventListener('scroll', handleScroll);
+        originalDestroy.call(component);
+      };
+    }
+  };
+
+  try {
+    const extendedFab = pipe(
+      createBase,
+      withEvents(),
+      withElement(getElementConfig(fabConfig)),
+      withVariant(fabConfig),
+      withIcon(fabConfig),
+      withText(fabConfig),
+      withDisabled(fabConfig),
+      withRipple(fabConfig),
+      withLifecycle(),
+      comp => withAPI(getApiConfig(comp))(comp)
+    )(fabConfig);
+    
+    // Set up scroll collapse after component is created
+    setupScrollCollapse(extendedFab);
+    
+    return extendedFab;
+  } catch (error) {
+    console.error('Extended FAB creation error:', error);
+    throw new Error(`Failed to create Extended FAB: ${(error as Error).message}`);
+  }
+};
+
+export default createExtendedFab;

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

@@ -0,0 +1,4 @@
+// src/components/extended-fab/index.ts
+export { default, default as createExtendedFab } from './extended-fab';
+export { FAB_VARIANTS, FAB_POSITIONS, EXTENDED_FAB_WIDTH } from './constants';
+export { ExtendedFabConfig, ExtendedFabComponent } from './types';

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

@@ -0,0 +1,287 @@
+// src/components/extended-fab/types.ts
+import { FAB_VARIANTS } from '../fab/constants';
+
+/**
+ * Configuration interface for the Extended FAB component
+ * @category Components
+ */
+export interface ExtendedFabConfig {
+  /** 
+   * Extended FAB variant that determines visual styling
+   * @default 'primary'
+   */
+  variant?: keyof typeof FAB_VARIANTS | string;
+  
+  /** 
+   * Whether the Extended FAB is initially disabled
+   * @default false
+   */
+  disabled?: boolean;
+  
+  /** 
+   * Extended FAB icon HTML content
+   * @example '<svg>...</svg>'
+   */
+  icon?: string;
+  
+  /** 
+   * Icon size in pixels or other CSS units
+   * @example '24px'
+   */
+  iconSize?: string;
+  
+  /**
+   * Position of the icon relative to the text
+   * @default 'start'
+   */
+  iconPosition?: 'start' | 'end';
+  
+  /**
+   * Text label for the Extended FAB
+   * @example 'Create'
+   */
+  text?: string;
+  
+  /** 
+   * Additional CSS classes to add to the Extended FAB
+   * @example 'home-fab bottom-right'
+   */
+  class?: string;
+  
+  /** 
+   * Button value attribute
+   */
+  value?: string;
+  
+  /**
+   * Position of the Extended FAB on the screen
+   * @example 'bottom-right'
+   */
+  position?: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' | string;
+  
+  /** 
+   * Button type attribute
+   * @default 'button'
+   */
+  type?: 'button' | 'submit' | 'reset';
+  
+  /**
+   * Accessible label for screen readers
+   */
+  ariaLabel?: string;
+  
+  /** 
+   * Whether to enable ripple effect
+   * @default true
+   */
+  ripple?: boolean;
+
+  /**
+   * Component prefix for class names
+   * @default 'mtrl'
+   */
+  prefix?: string;
+  
+  /**
+   * Component name used in class generation
+   */
+  componentName?: string;
+  
+  /** 
+   * Ripple effect configuration
+   */
+  rippleConfig?: {
+    /** Duration of the ripple animation in milliseconds */
+    duration?: number;
+    /** Timing function for the ripple animation */
+    timing?: string;
+    /** Opacity values for ripple start and end [start, end] */
+    opacity?: [string, string];
+  };
+
+  /**
+   * Whether to show the Extended FAB with an entrance animation
+   * @default false
+   */
+  animate?: boolean;
+  
+  /**
+   * Width behavior of the Extended FAB
+   * @default 'fixed'
+   */
+  width?: 'fixed' | 'fluid';
+  
+  /**
+   * Whether the Extended FAB should collapse to a standard FAB on scroll
+   * @default false
+   */
+  collapseOnScroll?: boolean;
+}
+
+/**
+ * Extended FAB component interface
+ * @category Components
+ */
+export interface ExtendedFabComponent {
+  /** The Extended FAB's DOM element */
+  element: HTMLButtonElement;
+  
+  /** API for managing Extended FAB icons */
+  icon: {
+    /** Sets the icon HTML content */
+    setIcon: (html: string) => any;
+    /** Gets the current icon HTML content */
+    getIcon: () => string;
+    /** Gets the icon DOM element */
+    getElement: () => HTMLElement | null;
+  };
+  
+  /** API for managing text content */
+  text: {
+    /** Sets the text content */
+    setText: (text: string) => any;
+    /** Gets the current text content */
+    getText: () => string;
+    /** Gets the text DOM element */
+    getElement: () => HTMLElement | null;
+  };
+  
+  /** API for managing disabled state */
+  disabled: {
+    /** Enables the Extended FAB */
+    enable: () => void;
+    /** Disables the Extended FAB */
+    disable: () => void;
+    /** Checks if the Extended FAB 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 Extended FAB's value attribute
+   * @returns Extended FAB value
+   */
+  getValue: () => string;
+  
+  /**
+   * Sets the Extended FAB's value attribute
+   * @param value - New value
+   * @returns The Extended FAB component for chaining
+   */
+  setValue: (value: string) => ExtendedFabComponent;
+  
+  /**
+   * Enables the Extended FAB (removes disabled attribute)
+   * @returns The Extended FAB component for chaining
+   */
+  enable: () => ExtendedFabComponent;
+  
+  /**
+   * Disables the Extended FAB (adds disabled attribute)
+   * @returns The Extended FAB component for chaining
+   */
+  disable: () => ExtendedFabComponent;
+  
+  /**
+   * Sets the Extended FAB's icon
+   * @param icon - Icon HTML content
+   * @returns The Extended FAB component for chaining
+   */
+  setIcon: (icon: string) => ExtendedFabComponent;
+  
+  /**
+   * Gets the Extended FAB's icon HTML content
+   * @returns Icon HTML
+   */
+  getIcon: () => string;
+  
+  /**
+   * Sets the Extended FAB's text content
+   * @param text - Text content
+   * @returns The Extended FAB component for chaining
+   */
+  setText: (text: string) => ExtendedFabComponent;
+  
+  /**
+   * Gets the Extended FAB's text content
+   * @returns Text content
+   */
+  getText: () => string;
+  
+  /**
+   * Sets the Extended FAB's position
+   * @param position - Position value ('top-right', 'bottom-left', etc.)
+   * @returns The Extended FAB component for chaining
+   */
+  setPosition: (position: string) => ExtendedFabComponent;
+  
+  /**
+   * Gets the current position of the Extended FAB
+   * @returns Current position
+   */
+  getPosition: () => string | null;
+
+  /**
+   * Lowers the Extended FAB (useful for pressed state)
+   * @returns The Extended FAB component for chaining
+   */
+  lower: () => ExtendedFabComponent;
+  
+  /**
+   * Raises the Extended FAB back to its default elevation
+   * @returns The Extended FAB component for chaining
+   */
+  raise: () => ExtendedFabComponent;
+  
+  /**
+   * Collapses the Extended FAB into a standard FAB
+   * @returns The Extended FAB component for chaining
+   */
+  collapse: () => ExtendedFabComponent;
+  
+  /**
+   * Expands a collapsed Extended FAB back to its full size
+   * @returns The Extended FAB component for chaining
+   */
+  expand: () => ExtendedFabComponent;
+  
+  /**
+   * Destroys the Extended FAB component and cleans up resources
+   */
+  destroy: () => void;
+  
+  /**
+   * Adds an event listener to the Extended FAB
+   * @param event - Event name ('click', 'focus', etc.)
+   * @param handler - Event handler function
+   * @returns The Extended FAB component for chaining
+   */
+  on: (event: string, handler: Function) => ExtendedFabComponent;
+  
+  /**
+   * Removes an event listener from the Extended FAB
+   * @param event - Event name
+   * @param handler - Event handler function
+   * @returns The Extended FAB component for chaining
+   */
+  off: (event: string, handler: Function) => ExtendedFabComponent;
+  
+  /**
+   * Adds CSS classes to the Extended FAB element
+   * @param classes - One or more class names to add
+   * @returns The Extended FAB component for chaining
+   */
+  addClass: (...classes: string[]) => ExtendedFabComponent;
+}