mtrl 0.2.2 → 0.2.4

package/src/components/tooltip/types.ts

@@ -0,0 +1,178 @@
+// src/components/tooltip/types.ts
+import { TOOLTIP_POSITIONS, TOOLTIP_VARIANTS } from './constants';
+
+/**
+ * Configuration interface for the Tooltip component
+ * @category Components
+ */
+export interface TooltipConfig {
+  /** 
+   * Tooltip content text
+   * @example 'Delete item'
+   */
+  text?: string;
+  
+  /** 
+   * HTML element that triggers the tooltip
+   * @example document.querySelector('#my-button')
+   */
+  target?: HTMLElement;
+  
+  /** 
+   * Tooltip position relative to the target
+   * @default 'bottom'
+   */
+  position?: keyof typeof TOOLTIP_POSITIONS | string;
+  
+  /** 
+   * Tooltip variant that determines visual styling
+   * @default 'default'
+   */
+  variant?: keyof typeof TOOLTIP_VARIANTS | string;
+  
+  /** 
+   * Whether the tooltip is initially visible
+   * @default false
+   */
+  visible?: boolean;
+  
+  /** 
+   * Show delay in milliseconds
+   * @default 300
+   */
+  showDelay?: number;
+  
+  /** 
+   * Hide delay in milliseconds
+   * @default 100
+   */
+  hideDelay?: number;
+  
+  /** 
+   * Whether to show the tooltip on focus
+   * @default true
+   */
+  showOnFocus?: boolean;
+  
+  /** 
+   * Whether to show the tooltip on hover
+   * @default true
+   */
+  showOnHover?: boolean;
+  
+  /** 
+   * Additional CSS classes to add to the tooltip
+   */
+  class?: string;
+  
+  /**
+   * Component prefix for class names
+   * @default 'mtrl'
+   */
+  prefix?: string;
+  
+  /**
+   * Component name used in class generation
+   */
+  componentName?: string;
+  
+  /**
+   * Optional z-index for the tooltip
+   */
+  zIndex?: number;
+  
+  /**
+   * Whether to enable rich (HTML) content
+   * @default false
+   */
+  rich?: boolean;
+}
+
+/**
+ * Tooltip component interface
+ * @category Components
+ */
+export interface TooltipComponent {
+  /** The tooltip's DOM element */
+  element: HTMLElement;
+  
+  /** The tooltip's target element */
+  target: HTMLElement | null;
+  
+  /** 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;
+  
+  /**
+   * Sets the tooltip text content
+   * @param text - New text content
+   * @returns The tooltip component for chaining
+   */
+  setText: (text: string) => TooltipComponent;
+  
+  /**
+   * Gets the tooltip text content
+   * @returns Tooltip text content
+   */
+  getText: () => string;
+  
+  /**
+   * Sets the tooltip position
+   * @param position - Position value
+   * @returns The tooltip component for chaining
+   */
+  setPosition: (position: keyof typeof TOOLTIP_POSITIONS | string) => TooltipComponent;
+  
+  /**
+   * Gets the current tooltip position
+   * @returns Current position
+   */
+  getPosition: () => string;
+  
+  /**
+   * Sets the tooltip target element
+   * @param target - Element to attach tooltip to
+   * @returns The tooltip component for chaining
+   */
+  setTarget: (target: HTMLElement) => TooltipComponent;
+  
+  /**
+   * Shows the tooltip
+   * @param immediate - Whether to show immediately (bypassing delay)
+   * @returns The tooltip component for chaining
+   */
+  show: (immediate?: boolean) => TooltipComponent;
+  
+  /**
+   * Hides the tooltip
+   * @param immediate - Whether to hide immediately (bypassing delay)
+   * @returns The tooltip component for chaining
+   */
+  hide: (immediate?: boolean) => TooltipComponent;
+  
+  /**
+   * Checks if the tooltip is currently visible
+   * @returns Whether the tooltip is visible
+   */
+  isVisible: () => boolean;
+  
+  /**
+   * Updates the tooltip's position relative to its target
+   * @returns The tooltip component for chaining
+   */
+  updatePosition: () => TooltipComponent;
+  
+  /**
+   * Destroys the tooltip component and cleans up resources
+   */
+  destroy: () => void;
+}

package/src/core/build/_ripple.scss

@@ -0,0 +1,79 @@
+// src/components/ripple/_ripple.scss
+@use '../../styles/abstract/base' as base;
+@use '../../styles/abstract/variables' as v;
+@use '../../styles/abstract/functions' as f;
+@use '../../styles/abstract/mixins' as m;
+@use '../../styles/abstract/theme' as t;
+
+$component: '#{base.$prefix}-ripple';
+
+.#{$component} {
+  // Ripple container
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  overflow: hidden;
+  border-radius: inherit;
+  pointer-events: none;
+  z-index: 0;
+  
+  // Ripple element
+  &-wave {
+    position: absolute;
+    border-radius: 50%;
+    background-color: currentColor;
+    transform: scale(0);
+    opacity: 0;
+    pointer-events: none;
+    will-change: transform, opacity;
+    
+    // Animation
+    transition-property: transform, opacity;
+    transition-duration: v.motion('duration-short4');
+    transition-timing-function: v.motion('easing-standard');
+    
+    // Active ripple
+    &.active {
+      transform: scale(1);
+      opacity: v.state('hover-state-layer-opacity');
+    }
+    
+    &.fade-out {
+      opacity: 0;
+    }
+  }
+}
+
+// Standalone utility for adding ripple to any element
+[data-ripple] {
+  position: relative;
+  overflow: hidden;
+  
+  &::after {
+    content: '';
+    position: absolute;
+    top: 0;
+    left: 0;
+    right: 0;
+    bottom: 0;
+    z-index: 0;
+    pointer-events: none;
+  }
+  
+  // Handle ripple color based on data attribute
+  &[data-ripple="light"]::after {
+    background-color: rgba(255, 255, 255, 0.3);
+  }
+  
+  &[data-ripple="dark"]::after {
+    background-color: rgba(0, 0, 0, 0.1);
+  }
+  
+  // Make content appear above ripple
+  > * {
+    position: relative;
+    z-index: 1;
+  }
+}

package/src/core/build/constants.ts

@@ -0,0 +1,48 @@
+// src/core/build/constants.ts
+
+/**
+ * Animation timing functions for ripple effect
+ */
+export enum RIPPLE_TIMING {
+  LINEAR = 'linear',
+  EASE = 'ease',
+  EASE_IN = 'ease-in',
+  EASE_OUT = 'ease-out',
+  EASE_IN_OUT = 'ease-in-out',
+  MATERIAL = 'cubic-bezier(0.4, 0.0, 0.2, 1)'
+}
+
+/**
+ * Default configuration for ripple effect
+ */
+export const RIPPLE_CONFIG = {
+  duration: 375,
+  timing: RIPPLE_TIMING.LINEAR,
+  opacity: ['1', '0.3'] as [string, string]
+};
+
+/**
+ * Validation schema for ripple configuration
+ */
+export const RIPPLE_SCHEMA = {
+  duration: {
+    type: 'number',
+    minimum: 0,
+    default: RIPPLE_CONFIG.duration
+  },
+  timing: {
+    type: 'string',
+    enum: Object.values(RIPPLE_TIMING),
+    default: RIPPLE_CONFIG.timing
+  },
+  opacity: {
+    type: 'array',
+    items: {
+      type: 'string',
+      pattern: '^[0-1](\\.\\d+)?$'
+    },
+    minItems: 2,
+    maxItems: 2,
+    default: RIPPLE_CONFIG.opacity
+  }
+};

package/src/core/build/icon.ts

@@ -0,0 +1,137 @@
+// src/core/build/icon.ts
+/**
+ * @module core/build
+ */
+
+/**
+ * Options for creating an icon element
+ */
+export interface IconElementOptions {
+  /**
+   * CSS class prefix
+   */
+  prefix?: string;
+  
+  /**
+   * Additional CSS class
+   */
+  class?: string;
+  
+  /**
+   * Icon size variant
+   */
+  size?: string;
+}
+
+/**
+ * Configuration for icon manager
+ */
+export interface IconConfig {
+  /**
+   * CSS class prefix
+   */
+  prefix?: string;
+  
+  /**
+   * Component type
+   */
+  type?: string;
+  
+  /**
+   * Icon position ('start' or 'end')
+   */
+  position?: 'start' | 'end';
+  
+  /**
+   * Icon size
+   */
+  iconSize?: string;
+}
+
+/**
+ * Icon manager interface
+ */
+export interface IconManager {
+  /**
+   * Sets icon HTML content
+   * @param html - Icon HTML content
+   * @returns IconManager instance for chaining
+   */
+  setIcon: (html: string) => IconManager;
+  
+  /**
+   * Gets current icon HTML content
+   * @returns Current icon HTML
+   */
+  getIcon: () => string;
+  
+  /**
+   * Gets icon element
+   * @returns Icon element or null if not created
+   */
+  getElement: () => HTMLElement | null;
+}
+
+/**
+ * Creates an icon DOM element
+ * 
+ * @param html - Icon HTML content
+ * @param options - Icon options
+ * @returns Icon element
+ * @private
+ */
+const createIconElement = (html: string, options: IconElementOptions = {}): HTMLElement => {
+  const PREFIX = options.prefix || 'mtrl';
+  const element = document.createElement('span');
+  element.className = `${PREFIX}-icon`;
+
+  if (options.class) {
+    element.classList.add(options.class);
+  }
+  if (options.size) {
+    element.classList.add(`${PREFIX}-icon--${options.size}`);
+  }
+
+  element.innerHTML = html;
+  return element;
+};
+
+/**
+ * Creates an icon manager for a component
+ * 
+ * @param element - Parent element
+ * @param config - Icon configuration
+ * @returns Icon manager interface
+ */
+export const createIcon = (element: HTMLElement, config: IconConfig = {}): IconManager => {
+  let iconElement: HTMLElement | null = null;
+  const PREFIX = config.prefix || 'mtrl';
+
+  return {
+    setIcon(html: string): IconManager {
+      if (!iconElement && html) {
+        iconElement = createIconElement(html, {
+          prefix: PREFIX,
+          class: `${PREFIX}-${config.type || 'component'}-icon`,
+          size: config.iconSize
+        });
+        if (config.position === 'end') {
+          element.appendChild(iconElement);
+        } else {
+          element.insertBefore(iconElement, element.firstChild);
+        }
+      } else if (iconElement && html) {
+        iconElement.innerHTML = html;
+      }
+      return this;
+    },
+
+    getIcon(): string {
+      return iconElement ? iconElement.innerHTML : '';
+    },
+
+    getElement(): HTMLElement | null {
+      return iconElement;
+    }
+  };
+};

package/src/core/build/ripple.ts

@@ -0,0 +1,216 @@
+// src/core/build/ripple.ts
+
+import { RIPPLE_CONFIG, RIPPLE_TIMING } from './constants';
+
+/**
+ * Ripple animation configuration
+ */
+export interface RippleConfig {
+  /**
+   * Animation duration in milliseconds
+   */
+  duration?: number;
+  
+  /**
+   * Animation timing function
+   */
+  timing?: string;
+  
+  /**
+   * Opacity start and end values
+   */
+  opacity?: [string, string];
+}
+
+/**
+ * End coordinates for ripple animation
+ */
+interface EndCoordinates {
+  size: string;
+  top: string;
+  left: string;
+}
+
+/**
+ * Document event listener
+ */
+interface DocumentListener {
+  event: string;
+  handler: EventListener;
+}
+
+/**
+ * Ripple controller interface
+ */
+export interface RippleController {
+  /**
+   * Attaches ripple effect to an element
+   * @param element - Target element
+   */
+  mount: (element: HTMLElement) => void;
+  
+  /**
+   * Removes ripple effect from an element
+   * @param element - Target element
+   */
+  unmount: (element: HTMLElement) => void;
+}
+
+/**
+ * Creates a ripple effect instance
+ * 
+ * @param config - Ripple configuration
+ * @returns Ripple controller instance
+ */
+export const createRipple = (config: RippleConfig = {}): RippleController => {
+  // Make sure we fully merge the config options
+  const options = {
+    ...RIPPLE_CONFIG,
+    ...config,
+    // Handle nested objects like opacity array
+    opacity: config.opacity || RIPPLE_CONFIG.opacity
+  };
+
+  const getEndCoordinates = (bounds: DOMRect): EndCoordinates => {
+    const size = Math.max(bounds.width, bounds.height);
+    const top = bounds.height > bounds.width
+      ? -bounds.height / 2
+      : -(bounds.width - bounds.height / 2);
+
+    return {
+      size: `${size * 2}px`,
+      top: `${top}px`,
+      left: `${size / -2}px`
+    };
+  };
+
+  const createRippleElement = (): HTMLDivElement => {
+    const ripple = document.createElement('div');
+    ripple.className = 'ripple';
+    // Initial styles already set in CSS
+    ripple.style.transition = `all ${options.duration}ms ${options.timing}`;
+    return ripple;
+  };
+
+  // Store document event listeners for cleanup
+  let documentListeners: DocumentListener[] = [];
+
+  // Safe document event handling
+  const addDocumentListener = (event: string, handler: EventListener): void => {
+    if (typeof document.addEventListener === 'function') {
+      document.addEventListener(event, handler);
+      documentListeners.push({ event, handler });
+    }
+  };
+
+  const removeDocumentListener = (event: string, handler: EventListener): void => {
+    if (typeof document.removeEventListener === 'function') {
+      document.removeEventListener(event, handler);
+      documentListeners = documentListeners.filter(
+        listener => !(listener.event === event && listener.handler === handler)
+      );
+    }
+  };
+
+  const animate = (event: MouseEvent, container: HTMLElement): void => {
+    if (!container) return;
+
+    const bounds = container.getBoundingClientRect();
+    const ripple = createRippleElement();
+
+    // Set initial position and state
+    Object.assign(ripple.style, {
+      left: `${event.offsetX || bounds.width / 2}px`,
+      top: `${event.offsetY || bounds.height / 2}px`,
+      transform: 'scale(0)',
+      opacity: options.opacity[0]
+    });
+
+    container.appendChild(ripple);
+
+    // Force reflow
+    // eslint-disable-next-line no-unused-expressions
+    ripple.offsetHeight;
+
+    // Animate to end position
+    const end = getEndCoordinates(bounds);
+    Object.assign(ripple.style, {
+      ...end,
+      transform: 'scale(1)',
+      opacity: options.opacity[1]
+    });
+
+    const cleanup = () => {
+      ripple.style.opacity = '0';
+
+      // Use setTimeout to remove element after animation
+      setTimeout(() => {
+        if (ripple.parentNode) {
+          ripple.parentNode.removeChild(ripple);
+        }
+      }, options.duration);
+
+      removeDocumentListener('mouseup', cleanup);
+      removeDocumentListener('mouseleave', cleanup);
+    };
+
+    addDocumentListener('mouseup', cleanup);
+    addDocumentListener('mouseleave', cleanup);
+  };
+
+  return {
+    mount: (element: HTMLElement): void => {
+      if (!element) return;
+
+      // Ensure proper positioning context
+      const currentPosition = window.getComputedStyle(element).position;
+      if (currentPosition === 'static') {
+        element.style.position = 'relative';
+      }
+      element.style.overflow = 'hidden';
+
+      // Store the mousedown handler to be able to remove it later
+      const mousedownHandler = (e: MouseEvent) => animate(e, element);
+
+      // Store handler reference on the element
+      if (!element.__rippleHandlers) {
+        element.__rippleHandlers = [];
+      }
+      element.__rippleHandlers.push(mousedownHandler);
+
+      element.addEventListener('mousedown', mousedownHandler);
+    },
+
+    unmount: (element: HTMLElement): void => {
+      if (!element) return;
+
+      // Clear document event listeners
+      documentListeners.forEach(({ event, handler }) => {
+        removeDocumentListener(event, handler);
+      });
+      documentListeners = [];
+
+      // Remove event listeners
+      if (element.__rippleHandlers) {
+        element.__rippleHandlers.forEach(handler => {
+          element.removeEventListener('mousedown', handler);
+        });
+        element.__rippleHandlers = [];
+      }
+
+      // Remove all ripple elements
+      const ripples = element.querySelectorAll('.ripple');
+      ripples.forEach(ripple => {
+        // Call remove directly to match the test expectation
+        ripple.remove();
+      });
+    }
+  };
+};
+
+// Extend the HTMLElement interface to add rippleHandlers property
+declare global {
+  interface HTMLElement {
+    __rippleHandlers?: Array<(e: MouseEvent) => void>;
+  }
+}