mtrl 0.1.3 → 0.2.1

package/src/core/config/component-config.ts

@@ -0,0 +1,136 @@
+// src/core/config/component-config.ts
+import { PREFIX } from '../config';
+
+/**
+ * Base component configuration interface
+ * Common configuration properties shared by all components
+ */
+export interface BaseComponentConfig {
+  componentName?: string;
+  prefix?: string;
+  class?: string;
+  [key: string]: any;
+}
+
+/**
+ * Creates a base configuration for any component
+ * 
+ * @param {BaseComponentConfig} defaults - Default configuration for the component
+ * @param {BaseComponentConfig} userConfig - User provided configuration
+ * @param {string} componentName - The name of the component
+ * @returns {BaseComponentConfig} Complete configuration with defaults applied
+ * 
+ * @example
+ * // In button/config.ts
+ * export const createBaseConfig = (config: ButtonConfig = {}) => 
+ *   createComponentConfig(defaultConfig, config, 'button');
+ */
+export const createComponentConfig = (
+  defaults: BaseComponentConfig, 
+  userConfig: BaseComponentConfig = {}, 
+  componentName: string
+): BaseComponentConfig => {
+  // Create a new object with defaults and user config
+  const config = {
+    ...defaults,
+    ...userConfig,
+    // Force these values to ensure consistency
+    componentName,
+    prefix: PREFIX
+  };
+
+  return config;
+};
+
+/**
+ * Creates a class name with proper prefixing
+ * 
+ * @param {string} componentName - The name of the component
+ * @param {string} [element] - Optional element name for BEM notation
+ * @param {string} [modifier] - Optional modifier name for BEM notation
+ * @returns {string} Properly formatted class name
+ * 
+ * @example
+ * // Returns 'mtrl-button'
+ * createClassName('button');
+ * 
+ * // Returns 'mtrl-button__icon'
+ * createClassName('button', 'icon');
+ * 
+ * // Returns 'mtrl-button--primary'
+ * createClassName('button', null, 'primary');
+ * 
+ * // Returns 'mtrl-button__icon--small'
+ * createClassName('button', 'icon', 'small');
+ */
+export const createClassName = (
+  componentName: string,
+  element?: string | null,
+  modifier?: string | null
+): string => {
+  let className = `${PREFIX}-${componentName}`;
+  
+  if (element) {
+    className += `__${element}`;
+  }
+  
+  if (modifier) {
+    className += `--${modifier}`;
+  }
+  
+  return className;
+};
+
+/**
+ * Processes class names for an element, handling arrays, nulls and conditional classes
+ * 
+ * @param {string | string[] | null} classNames - Class names to process
+ * @returns {string} Space-separated class names as a string
+ * 
+ * @example
+ * // Returns 'mtrl-card mtrl-card--elevated custom-class'
+ * processClassNames(['mtrl-card', 'mtrl-card--elevated', 'custom-class']);
+ * 
+ * // Returns 'mtrl-card'
+ * processClassNames(['mtrl-card', null, undefined]);
+ */
+export const processClassNames = (classNames: string | string[] | null): string => {
+  if (!classNames) return '';
+  
+  if (typeof classNames === 'string') return classNames;
+  
+  return classNames
+    .filter(Boolean) // Remove null, undefined, empty strings
+    .join(' ');
+};
+
+/**
+ * Creates a configuration object for withElement HOC
+ * 
+ * @param {BaseComponentConfig} config - Component configuration
+ * @param {Object} options - Element options
+ * @returns {Object} Configuration object for withElement
+ */
+export const createElementConfig = (
+  config: BaseComponentConfig,
+  options: {
+    tag: string;
+    attrs?: Record<string, any>;
+    className?: string | string[] | null;
+    html?: string;
+    text?: string;
+    forwardEvents?: Record<string, boolean | Function>;
+    interactive?: boolean;
+  }
+) => {
+  return {
+    tag: options.tag,
+    componentName: config.componentName,
+    attrs: options.attrs || {},
+    className: options.className,
+    html: options.html,
+    text: options.text,
+    forwardEvents: options.forwardEvents || {},
+    interactive: options.interactive
+  };
+};

package/src/core/config.ts

@@ -0,0 +1,211 @@
+// src/core/config.ts
+
+/**
+ * Library prefix used for all components
+ */
+export const PREFIX = 'mtrl';
+
+/**
+ * Gets a prefixed component class name
+ * @param type - Component type
+ * @returns Prefixed class name
+ */
+export const getComponentClass = (type: string): string => `${PREFIX}-${type}`;
+
+/**
+ * Gets a BEM modifier class name
+ * @param baseClass - Base class name
+ * @param modifier - Modifier name
+ * @returns Modifier class name
+ */
+export const getModifierClass = (baseClass: string, modifier: string): string => `${baseClass}--${modifier}`;
+
+/**
+ * Gets a BEM element class name
+ * @param baseClass - Base class name
+ * @param element - Element name
+ * @returns Element class name
+ */
+export const getElementClass = (baseClass: string, element: string): string => `${baseClass}-${element}`;
+
+/**
+ * Component type identifiers
+ */
+export enum COMPONENTS {
+  BUTTON = 'button',
+  TEXTFIELD = 'textfield',
+  CONTAINER = 'container',
+  SNACKBAR = 'snackbar',
+  SWITCH = 'switch'
+}
+
+/**
+ * Theme configuration interface
+ */
+export interface ThemeConfig {
+  /**
+   * Theme name
+   */
+  name: string;
+  
+  /**
+   * Theme CSS variables
+   */
+  variables: Record<string, string>;
+  
+  /**
+   * Theme variants
+   */
+  variants: Record<string, any>;
+}
+
+/**
+ * Component configuration interface
+ */
+export interface ComponentConfig {
+  prefix: string;
+  type: string;
+  baseClass: string;
+  getClass: () => string;
+  getModifierClass: (modifier: string) => string;
+  getElementClass: (element: string) => string;
+  withTheme: (theme: string) => ThemedComponentConfig;
+  withVariants: (...variants: string[]) => VariantComponentConfig;
+  withStates: (...states: string[]) => StateComponentConfig;
+}
+
+/**
+ * Themed component configuration interface
+ */
+export interface ThemedComponentConfig extends ComponentConfig {
+  theme: string;
+  getThemeClass: (variant: string) => string;
+}
+
+/**
+ * Variant component configuration interface
+ */
+export interface VariantComponentConfig extends ComponentConfig {
+  variants: string[];
+  hasVariant: (variant: string) => boolean;
+  getVariantClass: (variant: string) => string | null;
+}
+
+/**
+ * State component configuration interface
+ */
+export interface StateComponentConfig extends ComponentConfig {
+  states: string[];
+  getStateClass: (state: string) => string | null;
+}
+
+/**
+ * Creates a component configuration object
+ * @param type - Component type
+ * @returns Component configuration interface
+ */
+export const createComponentConfig = (type: string): ComponentConfig => {
+  const baseClass = `${PREFIX}-${type}`;
+
+  // Create the base config object
+  const config: ComponentConfig = {
+    prefix: PREFIX,
+    type,
+    baseClass,
+
+    // Class name generators
+    getClass: () => baseClass,
+    getModifierClass: (modifier) => `${baseClass}--${modifier}`,
+    getElementClass: (element) => `${baseClass}-${element}`,
+
+    // Theme support
+    withTheme: (theme) => ({
+      ...config,
+      theme,
+      getThemeClass: (variant) => `${baseClass}--theme-${theme}-${variant}`
+    }),
+
+    // Variant support
+    withVariants: (...variants) => ({
+      ...config,
+      variants,
+      hasVariant: (variant) => variants.includes(variant),
+      getVariantClass: (variant) =>
+        variants.includes(variant) ? `${baseClass}--${variant}` : null
+    }),
+
+    // State support
+    withStates: (...states) => ({
+      ...config,
+      states,
+      getStateClass: (state) =>
+        states.includes(state) ? `${baseClass}--state-${state}` : null
+    })
+  };
+
+  return config;
+};
+
+/**
+ * Common component states
+ */
+export enum STATES {
+  DISABLED = 'disabled',
+  FOCUSED = 'focused',
+  ACTIVE = 'active',
+  LOADING = 'loading',
+  ERROR = 'error'
+}
+
+/**
+ * CSS class generation utilities
+ */
+export const classNames = {
+  /**
+   * Creates a BEM-style class name
+   * @param block - Block name
+   * @param element - Element name
+   * @param modifier - Modifier name
+   * @returns BEM class name
+   */
+  bem: (block: string, element?: string, modifier?: string): string => {
+    let className = block;
+    if (element) className += `-${element}`;
+    if (modifier) className += `--${modifier}`;
+    return className;
+  },
+
+  /**
+   * Joins class names, filtering out falsy values
+   * @param classes - Class names to join
+   * @returns Joined class names
+   */
+  join: (...classes: (string | undefined | null | false)[]): string => 
+    classes.filter(Boolean).join(' ')
+};
+
+/**
+ * Creates a themed component configuration
+ * @param type - Component type
+ * @param theme - Theme configuration
+ * @returns Themed component configuration
+ */
+export const createThemedComponent = (type: string, theme: ThemeConfig): ThemedComponentConfig => {
+  const config = createComponentConfig(type);
+
+  return {
+    ...config,
+    theme: theme.name,
+
+    // Theme-specific class generators
+    getThemeClass: (variant) =>
+      `${config.getClass()}--theme-${theme.name}${variant ? `-${variant}` : ''}`,
+
+    // Theme CSS variables
+    getCssVariables: () =>
+      Object.entries(theme.variables).reduce((acc, [key, value]) => ({
+        ...acc,
+        [`--${PREFIX}-${type}-${key}`]: value
+      }), {} as Record<string, string>)
+  };
+};

package/src/core/dom/{attributes.js → attributes.ts}

@@ -1,4 +1,4 @@
-// src/core/dom/attributes.js
+// src/core/dom/attributes.ts
 /**
  * @module core/dom
  * @description DOM manipulation utilities
@@ -9,15 +9,15 @@
  * @memberof module:core/dom
  * @function setAttributes
  * @param {HTMLElement} element - Target element
- * @param {Object} attrs - Attributes to set
+ * @param {Record<string, any>} attrs - Attributes to set
  * @returns {HTMLElement} Modified element
  */
-export const setAttributes = (element, attrs = {}) => {
+export const setAttributes = (element: HTMLElement, attrs: Record<string, any> = {}): HTMLElement => {
   Object.entries(attrs).forEach(([key, value]) => {
-    if (value != null) element.setAttribute(key, value)
-  })
-  return element
-}
+    if (value != null) element.setAttribute(key, value.toString());
+  });
+  return element;
+};
 
 /**
  * Removes multiple attributes from an element
@@ -27,7 +27,7 @@ export const setAttributes = (element, attrs = {}) => {
  * @param {string[]} attrs - Attributes to remove
  * @returns {HTMLElement} Modified element
  */
-export const removeAttributes = (element, attrs = []) => {
-  attrs.forEach(attr => element.removeAttribute(attr))
-  return element
-}
+export const removeAttributes = (element: HTMLElement, attrs: string[] = []): HTMLElement => {
+  attrs.forEach(attr => element.removeAttribute(attr));
+  return element;
+};

package/src/core/dom/classes.ts

@@ -0,0 +1,60 @@
+// src/core/dom/classes.ts
+/**
+ * @module core/dom
+ * @description DOM manipulation utilities
+ */
+
+import { normalizeClasses } from '../utils';
+
+/**
+ * Adds multiple classes to an element
+ * @param {HTMLElement} element - Target element
+ * @param {...(string | string[])} classes - Classes to add
+ * @returns {HTMLElement} Modified element
+ */
+export const addClass = (element: HTMLElement, ...classes: (string | string[])[]): HTMLElement => {
+  const normalizedClasses = normalizeClasses(...classes);
+  if (normalizedClasses.length) {
+    element.classList.add(...normalizedClasses);
+  }
+  return element;
+};
+
+/**
+ * Removes multiple classes from an element
+ * @param {HTMLElement} element - Target element
+ * @param {...(string | string[])} classes - Classes to remove
+ * @returns {HTMLElement} Modified element
+ */
+export const removeClass = (element: HTMLElement, ...classes: (string | string[])[]): HTMLElement => {
+  const normalizedClasses = normalizeClasses(...classes);
+  if (normalizedClasses.length) {
+    element.classList.remove(...normalizedClasses);
+  }
+  return element;
+};
+
+/**
+ * Toggles multiple classes on an element
+ * @param {HTMLElement} element - Target element
+ * @param {...(string | string[])} classes - Classes to toggle
+ * @returns {HTMLElement} Modified element
+ */
+export const toggleClass = (element: HTMLElement, ...classes: (string | string[])[]): HTMLElement => {
+  const normalizedClasses = normalizeClasses(...classes);
+  normalizedClasses.forEach(cls => {
+    element.classList.toggle(cls);
+  });
+  return element;
+};
+
+/**
+ * Checks if an element has all specified classes
+ * @param {HTMLElement} element - Target element
+ * @param {...(string | string[])} classes - Classes to check
+ * @returns {boolean} True if element has all specified classes
+ */
+export const hasClass = (element: HTMLElement, ...classes: (string | string[])[]): boolean => {
+  const normalizedClasses = normalizeClasses(...classes);
+  return normalizedClasses.every(cls => element.classList.contains(cls));
+};

package/src/core/dom/create.ts

@@ -0,0 +1,251 @@
+// src/core/dom/create.ts
+/**
+ * @module core/dom
+ * @description DOM manipulation utilities
+ */
+
+import { setAttributes } from './attributes';
+import { normalizeClasses } from '../utils';
+
+/**
+ * Options for element creation
+ */
+export interface CreateElementOptions {
+  /**
+   * HTML tag name
+   */
+  tag?: string;
+  
+  /**
+   * Container to append element to
+   */
+  container?: HTMLElement | null;
+  
+  /**
+   * Inner HTML content
+   */
+  html?: string;
+  
+  /**
+   * Text content
+   */
+  text?: string;
+  
+  /**
+   * Element ID
+   */
+  id?: string;
+  
+  /**
+   * Dataset attributes
+   */
+  data?: Record<string, string>;
+  
+  /**
+   * CSS classes
+   */
+  className?: string | string[] | null;
+  
+  /**
+   * HTML attributes
+   */
+  attrs?: Record<string, any>;
+  
+  /**
+   * Events to forward when component has emit method
+   */
+  forwardEvents?: Record<string, boolean | ((context: any, event: Event) => boolean)>;
+  
+  /**
+   * Callback after element creation
+   */
+  onCreate?: (element: HTMLElement, context?: any) => void;
+  
+  /**
+   * Component context
+   */
+  context?: any;
+  
+  /**
+   * Additional attributes
+   */
+  [key: string]: any;
+}
+
+/**
+ * Event handler storage to facilitate cleanup
+ */
+export interface EventHandlerStorage {
+  [eventName: string]: EventListener;
+}
+
+/**
+ * Creates a DOM element with the specified options
+ *
+ * @param {CreateElementOptions} options - Element creation options
+ * @returns {HTMLElement} Created element
+ */
+export const createElement = (options: CreateElementOptions = {}): HTMLElement => {
+  const {
+    tag = 'div',
+    container = null,
+    html = '',
+    text = '',
+    id = '',
+    data = {},
+    className,
+    attrs = {},
+    forwardEvents = {},
+    onCreate,
+    context,
+    ...rest
+  } = options;
+
+  const element = document.createElement(tag);
+
+  // Handle content
+  if (html) element.innerHTML = html;
+  if (text) element.textContent = text;
+  if (id) element.id = id;
+
+  // Handle classes
+  if (className) {
+    const normalizedClasses = normalizeClasses(className);
+    if (normalizedClasses.length) {
+      element.classList.add(...normalizedClasses);
+    }
+  }
+
+  // Handle data attributes
+  Object.entries(data).forEach(([key, value]) => {
+    element.dataset[key] = value;
+  });
+
+  // Handle all other attributes
+  const allAttrs = { ...attrs, ...rest };
+  Object.entries(allAttrs).forEach(([key, value]) => {
+    if (value != null) element.setAttribute(key, String(value));
+  });
+
+  // Initialize event handler storage if not present
+  if (!element.__eventHandlers) {
+    element.__eventHandlers = {};
+  }
+
+  // Handle event forwarding if context has emit method or is a component with on method
+  if (forwardEvents && (context?.emit || context?.on)) {
+    Object.entries(forwardEvents).forEach(([nativeEvent, eventConfig]) => {
+      // Create a wrapper handler function to evaluate condition and forward event
+      const handler = (event: Event) => {
+        // Determine if the event should be forwarded
+        let shouldForward = true;
+        
+        if (typeof eventConfig === 'function') {
+          try {
+            // If it's a function, call with component context and event
+            shouldForward = eventConfig({ ...context, element }, event);
+          } catch (error) {
+            console.warn(`Error in event condition for ${nativeEvent}:`, error);
+            shouldForward = false;
+          }
+        } else {
+          // If it's a boolean, use directly
+          shouldForward = Boolean(eventConfig);
+        }
+        
+        // Forward the event if condition passes
+        if (shouldForward) {
+          if (context.emit) {
+            context.emit(nativeEvent, { event, element, originalEvent: event });
+          } else if (context.on) {
+            // This is a component with on method but no emit method
+            // Dispatch a custom event that can be listened to
+            const customEvent = new CustomEvent(nativeEvent, {
+              detail: { event, element, originalEvent: event },
+              bubbles: true,
+              cancelable: true
+            });
+            element.dispatchEvent(customEvent);
+          }
+        }
+      };
+      
+      // Store the handler for future removal
+      element.__eventHandlers[nativeEvent] = handler;
+      
+      // Add the actual event listener
+      element.addEventListener(nativeEvent, handler);
+    });
+  }
+
+  // Append to container if provided
+  if (container) {
+    container.appendChild(element);
+  }
+
+  if (typeof onCreate === 'function') {
+    onCreate(element, context);
+  }
+
+  return element;
+};
+
+/**
+ * Removes event handlers from an element
+ * @param element - Element to cleanup
+ */
+export const removeEventHandlers = (element: HTMLElement): void => {
+  if (element.__eventHandlers) {
+    Object.entries(element.__eventHandlers).forEach(([eventName, handler]) => {
+      element.removeEventListener(eventName, handler);
+    });
+    delete element.__eventHandlers;
+  }
+};
+
+/**
+ * Higher-order function to add attributes to an element
+ * @param {Record<string, any>} attrs - Attributes to add
+ * @returns {(element: HTMLElement) => HTMLElement} Element transformer
+ */
+export const withAttributes = (attrs: Record<string, any>) => 
+  (element: HTMLElement): HTMLElement => {
+    setAttributes(element, attrs);
+    return element;
+  };
+
+/**
+ * Higher-order function to add classes to an element
+ * @param {...(string | string[])} classes - Classes to add
+ * @returns {(element: HTMLElement) => HTMLElement} Element transformer
+ */
+export const withClasses = (...classes: (string | string[])[]) => 
+  (element: HTMLElement): HTMLElement => {
+    const normalizedClasses = normalizeClasses(...classes);
+    if (normalizedClasses.length) {
+      element.classList.add(...normalizedClasses);
+    }
+    return element;
+  };
+
+/**
+ * Higher-order function to add content to an element
+ * @param {Node|string} content - Content to add
+ * @returns {(element: HTMLElement) => HTMLElement} Element transformer
+ */
+export const withContent = (content: Node | string) => 
+  (element: HTMLElement): HTMLElement => {
+    if (content instanceof Node) {
+      element.appendChild(content);
+    } else {
+      element.textContent = content;
+    }
+    return element;
+  };
+
+// Extend HTMLElement interface to add eventHandlers property
+declare global {
+  interface HTMLElement {
+    __eventHandlers?: EventHandlerStorage;
+  }
+}