mtrl 0.3.8 → 0.4.0

package/src/components/button/api.ts

@@ -1,172 +0,0 @@
-// src/components/button/api.ts
-import { ButtonComponent } from './types';
-
-/**
- * API configuration options for button component
- * @category Components
- * @internal
- */
-interface ApiOptions {
-  disabled: {
-    enable: () => void;
-    disable: () => void;
-  };
-  lifecycle: {
-    destroy: () => void;
-  };
-}
-
-/**
- * Component with required elements and methods for API enhancement
- * @category Components
- * @internal
- */
-interface ComponentWithElements {
-  element: HTMLElement;
-  text: {
-    setText: (content: string) => any;
-    getText: () => string;
-    getElement: () => HTMLElement | null;
-  };
-  icon: {
-    setIcon: (html: string) => any;
-    getIcon: () => string;
-    getElement: () => HTMLElement | null;
-  };
-  getClass: (name: string) => string;
-}
-
-/**
- * Enhances a button component with API methods.
- * This follows the higher-order function pattern to add public API methods
- * to the component, making them available to the end user.
- * 
- * @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 Button component
- */
-export const withAPI = ({ disabled, lifecycle }: ApiOptions) => 
-  (component: ComponentWithElements): ButtonComponent => ({
-    ...component as any,
-    element: component.element as HTMLButtonElement,
-    
-    /**
-     * Gets the button's value attribute
-     * @returns Current value of the button
-     */
-    getValue: () => component.element.value,
-    
-    /**
-     * Sets the button's value attribute
-     * @param value - New value to set
-     * @returns Button component for method chaining
-     */
-    setValue(value: string) {
-      component.element.value = value;
-      return this;
-    },
-    
-    /**
-     * Enables the button, making it interactive
-     * @returns Button component for method chaining
-     */
-    enable() {
-      disabled.enable();
-      return this;
-    },
-    
-    /**
-     * Disables the button, making it non-interactive
-     * @returns Button component for method chaining
-     */
-    disable() {
-      disabled.disable();
-      return this;
-    },
-    
-    /**
-     * Sets the button's text content
-     * @param content - Text content to display
-     * @returns Button component for method chaining
-     */
-    setText(content: string) {
-      component.text.setText(content);
-      this.updateCircularStyle();
-      return this;
-    },
-    
-    /**
-     * Gets the button's current text content
-     * @returns Current text content
-     */
-    getText() {
-      return component.text.getText();
-    },
-    
-    /**
-     * Sets the button's icon HTML content
-     * @param icon - HTML string for the icon
-     * @returns Button component for method chaining
-     */
-    setIcon(icon: string) {
-      component.icon.setIcon(icon);
-      this.updateCircularStyle();
-      return this;
-    },
-    
-    /**
-     * Gets the button's current icon HTML content
-     * @returns Current icon HTML
-     */
-    getIcon() {
-      return component.icon.getIcon();
-    },
-
-    /**
-     * Sets the active state of the button
-     * Used to visually indicate the button's active state, such as when it has a menu open
-     * 
-     * @param active - Whether the button should appear active
-     * @returns Button component for method chaining
-     */
-    setActive(active: boolean) {
-      if (active) {
-        component.element.classList.add(`${component.getClass('button')}--active`);
-      } else {
-        component.element.classList.remove(`${component.getClass('button')}--active`);
-      }
-      return this;
-    },
-
-    /**
-     * Sets the button's aria-label attribute for accessibility
-     * @param label - Accessible label text
-     * @returns Button component for method chaining
-     */
-    setAriaLabel(label: string) {
-      component.element.setAttribute('aria-label', label);
-      return this;
-    },
-    
-    /**
-     * Destroys the button component and cleans up resources
-     */
-    destroy() {
-      lifecycle.destroy();
-    },
-    
-    /**
-     * Updates the button's circular style based on content.
-     * If the button has an icon but no text, it will be styled as circular.
-     * @internal
-     */
-    updateCircularStyle() {
-      const hasText = component.text.getElement();
-      if (!hasText && component.icon.getElement()) {
-        component.element.classList.add(`${component.getClass('button')}--circular`);
-      } else {
-        component.element.classList.remove(`${component.getClass('button')}--circular`);
-      }
-    }
-  });

package/src/components/button/button.ts

@@ -1,112 +0,0 @@
-// src/components/button/button.ts
-import { PREFIX } from '../../core/config';
-import { pipe } from '../../core/compose';
-import { createBase, withElement } from '../../core/compose/component';
-import {
-  withEvents,
-  withText,
-  withIcon,
-  withVariant,
-  withRipple,
-  withDisabled,
-  withLifecycle
-} from '../../core/compose/features';
-import { withAPI } from './api';
-import { ButtonConfig } from './types';
-import { createBaseConfig, getElementConfig, getApiConfig } from './config';
-
-/**
- * Creates a new Button component with the specified configuration.
- * 
- * The Button component implements the Material Design 3 Button component guidelines
- * with support for different variants, states, and features. It follows accessibility
- * best practices and provides a rich API for state management.
- * 
- * The Button component is created using a functional composition pattern,
- * applying various features through the pipe function. This approach allows
- * for flexible and modular component construction.
- * 
- * @param {ButtonConfig} config - Configuration options for the button
- *  This can include text content, icon options, variant styling, disabled state, 
- *  and other button properties. See {@link ButtonConfig} for available options.
- * 
- * @returns {ButtonComponent} A fully configured button component instance with
- *  all requested features applied. The returned component has methods for
- *  manipulation, event handling, and lifecycle management.
- * 
- * @throws {Error} Throws an error if button creation fails for any reason
- * 
- * @category Components
- * 
- * @example
- * // Create a simple text button
- * const textButton = createButton({ text: 'Click me' });
- * document.body.appendChild(textButton.element);
- * 
- * @example
- * // Create a filled button with an icon
- * const primaryButton = createButton({ 
- *   text: 'Submit',
- *   variant: 'filled',
- *   icon: '<svg>...</svg>'
- * });
- * 
- * // Add a click event handler
- * primaryButton.on('click', () => {
- *   console.log('Button clicked');
- * });
- * 
- * @example
- * // Create an outlined button with event handling
- * const submitButton = createButton({
- *   text: 'Save',
- *   variant: 'outlined'
- * });
- * 
- * submitButton.on('click', async () => {
- *   submitButton.disable(); // Disable during async operation
- *   await saveData();
- *   submitButton.enable();  // Re-enable when done
- * });
- * 
- * @example
- * // Create an icon-only button (circular)
- * const iconButton = createButton({
- *   icon: '<svg>...</svg>',
- *   ariaLabel: 'Add to favorites', // Important for accessibility
- *   variant: 'filled'
- * });
- * 
- * @example
- * // Create a disabled button
- * const disabledButton = createButton({
- *   text: 'Not available',
- *   disabled: true
- * });
- * 
- * // Later, enable the button when available
- * disabledButton.enable();
- */
-const createButton = (config: ButtonConfig = {}) => {
-  const baseConfig = createBaseConfig(config);
-  try {
-    const button = pipe(
-      createBase,
-      withEvents(),
-      withElement(getElementConfig(baseConfig)),
-      withVariant(baseConfig),
-      withText(baseConfig),
-      withIcon(baseConfig),
-      withDisabled(baseConfig),
-      withRipple(baseConfig),
-      withLifecycle(),
-      comp => withAPI(getApiConfig(comp))(comp)
-    )(baseConfig);
-    return button;
-  } catch (error) {
-    console.error('Button creation error:', error);
-    throw new Error(`Failed to create button: ${(error as Error).message}`);
-  }
-};
-
-export default createButton;

package/src/components/button/config.ts

@@ -1,96 +0,0 @@
-// src/components/button/config.ts
-import { 
-  createComponentConfig, 
-  createElementConfig,
-  BaseComponentConfig 
-} from '../../core/config/component-config';
-import { ButtonConfig } from './types';
-
-/**
- * Default configuration for the Button component.
- * These values will be used when not explicitly specified by the user.
- * 
- * @category Components
- */
-export const defaultConfig: ButtonConfig = {
-  variant: 'filled',
-  type: 'button'
-  // Don't set disabled: false as default - it should be undefined by default
-};
-
-/**
- * Creates the base configuration for Button component by merging user-provided
- * config with default values.
- * 
- * @param {ButtonConfig} config - User provided configuration
- * @returns {ButtonConfig} Complete configuration with defaults applied
- * @category Components
- * @internal
- */
-export const createBaseConfig = (config: ButtonConfig = {}): ButtonConfig => 
-  createComponentConfig(defaultConfig, config, 'button') as ButtonConfig;
-
-/**
- * Generates element configuration for the Button component.
- * This function creates the necessary attributes and configuration
- * for the DOM element creation process.
- * 
- * @param {ButtonConfig} config - Button configuration
- * @returns {Object} Element configuration object for withElement
- * @category Components
- * @internal
- */
-export const getElementConfig = (config: ButtonConfig) => {
-  // Create the attributes object
-  const attrs: Record<string, any> = {
-    type: config.type || 'button'
-  };
-  
-  // Only add disabled attribute if it's explicitly true
-  if (config.disabled === true) {
-    attrs.disabled = true;
-  }
-  
-  // Add value attribute only if it exists
-  if (config.value !== undefined) {
-    attrs.value = config.value;
-  }
-  
-  // Add aria-label attribute for accessibility
-  if (config.ariaLabel) {
-    attrs['aria-label'] = config.ariaLabel;
-  }
-  
-  return createElementConfig(config, {
-    tag: 'button',
-    attrs,
-    className: config.class,
-    forwardEvents: {
-      click: (component) => !component.element.disabled,
-      focus: true,
-      blur: true
-    }
-  });
-};
-
-/**
- * Creates API configuration for the Button component.
- * This connects the core component features (like disabled state)
- * to the public API methods exposed to users.
- * 
- * @param {Object} comp - Component with disabled and lifecycle features
- * @returns {Object} API configuration object
- * @category Components
- * @internal
- */
-export const getApiConfig = (comp) => ({
-  disabled: {
-    enable: () => comp.disabled.enable(),
-    disable: () => comp.disabled.disable()
-  },
-  lifecycle: {
-    destroy: () => comp.lifecycle.destroy()
-  }
-});
-
-export default defaultConfig;

package/src/components/button/index.ts

@@ -1,37 +0,0 @@
-// src/components/button/index.ts
-
-/**
- * Button component module
- * @module components/button
- */
-
-export { default } from './button'
-export { ButtonConfig, ButtonComponent, ButtonVariant } from './types'
-
-/**
- * Constants for button variants - use these instead of string literals
- * for better code completion and type safety.
- * 
- * @example
- * import { createButton, BUTTON_VARIANTS } from 'mtrl';
- * 
- * // Create a filled button
- * const primaryButton = createButton({ 
- *   text: 'Submit',
- *   variant: BUTTON_VARIANTS.FILLED 
- * });
- * 
- * @category Components
- */
-export const BUTTON_VARIANTS = {
-  /** Primary action button with solid background (high emphasis) */
-  FILLED: 'filled',
-  /** Secondary action button with medium emphasis */
-  TONAL: 'tonal',
-  /** Button with outline border and transparent background */
-  OUTLINED: 'outlined',
-  /** Button with slight elevation/shadow */
-  ELEVATED: 'elevated',
-  /** Button that appears as text without background or border (low emphasis) */
-  TEXT: 'text'
-} as const;

package/src/components/button/types.ts

@@ -1,290 +0,0 @@
-// src/components/button/types.ts
-
-/**
- * Button variant types - controls the visual style of the button
- * @category Components
- * @remarks
- * - filled: Primary action button with solid background (high emphasis)
- * - tonal: Secondary action button with medium emphasis
- * - outlined: Button with outline border and transparent background
- * - elevated: Button with slight elevation/shadow
- * - text: Button that appears as text without background or border (low emphasis)
- */
-export type ButtonVariant = 'filled' | 'tonal' | 'outlined' | 'elevated' | 'text';
-
-/**
- * Configuration interface for the Button component
- * @category Components
- */
-export interface ButtonConfig {
-  /** 
-   * Button variant that determines visual styling
-   * @default 'filled'
-   */
-  variant?: ButtonVariant | string;
-  
-  /** 
-   * Whether the button is initially disabled
-   * @default false
-   */
-  disabled?: boolean;
-  
-  /** 
-   * Initial button text content
-   * @example 'Submit'
-   */
-  text?: string;
-  
-  /** 
-   * Initial button icon HTML content
-   * @example '<svg>...</svg>'
-   */
-  icon?: string;
-  
-  /** 
-   * Icon size in pixels or other CSS units
-   * @example '18px'
-   */
-  iconSize?: string;
-  
-  /** 
-   * Additional CSS classes to add to the button
-   * @example 'form-submit header-action'
-   */
-  class?: string;
-  
-  /** 
-   * Button value attribute
-   */
-  value?: string;
-  
-  /** 
-   * Button type attribute
-   * @default 'button'
-   */
-  type?: 'button' | 'submit' | 'reset';
-  
-  /** 
-   * 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];
-  };
-
-  /**
-   * Accessible name for the button (aria-label)
-   * Required for icon-only buttons without text
-   */
-  ariaLabel?: string;
-}
-
-/**
- * Icon API interface for managing button icons
- * @category Components
- */
-export interface IconAPI {
-  /**
-   * Sets the icon HTML content
-   * @param html - HTML string for the icon
-   * @returns The icon API for chaining
-   */
-  setIcon: (html: string) => IconAPI;
-  
-  /**
-   * Gets the current icon HTML content
-   * @returns HTML string for the icon
-   */
-  getIcon: () => string;
-  
-  /**
-   * Gets the icon DOM element
-   * @returns The icon element or null if not present
-   */
-  getElement: () => HTMLElement | null;
-}
-
-/**
- * Text API interface for managing button text
- * @category Components
- */
-export interface TextAPI {
-  /**
-   * Sets the text content
-   * @param content - Text content
-   * @returns The text API for chaining
-   */
-  setText: (content: string) => TextAPI;
-  
-  /**
-   * Gets the current text content
-   * @returns Button text content
-   */
-  getText: () => string;
-  
-  /**
-   * Gets the text DOM element
-   * @returns The text element or null if not present
-   */
-  getElement: () => HTMLElement | null;
-}
-
-/**
- * Button component interface
- * @category Components
- */
-export interface ButtonComponent {
-  /** The button's DOM element */
-  element: HTMLButtonElement;
-  
-  /** API for managing button text */
-  text: TextAPI;
-  
-  /** API for managing button icons */
-  icon: IconAPI;
-  
-  /** API for managing disabled state */
-  disabled: {
-    /** Enables the button */
-    enable: () => void;
-    /** Disables the button */
-    disable: () => void;
-    /** Checks if the button 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 button's value attribute
-   * @returns Button value
-   */
-  getValue: () => string;
-  
-  /**
-   * Sets the button's value attribute
-   * @param value - New value
-   * @returns The button component for chaining
-   */
-  setValue: (value: string) => ButtonComponent;
-  
-  /**
-   * Enables the button (removes disabled attribute)
-   * @returns The button component for chaining
-   */
-  enable: () => ButtonComponent;
-  
-  /**
-   * Disables the button (adds disabled attribute)
-   * @returns The button component for chaining
-   */
-  disable: () => ButtonComponent;
-  
-  /**
-   * Sets the button's text content
-   * @param content - Text content
-   * @returns The button component for chaining
-   */
-  setText: (content: string) => ButtonComponent;
-  
-  /**
-   * Gets the button's text content
-   * @returns Button text content
-   */
-  getText: () => string;
-  
-  /**
-   * Sets the button's icon
-   * @param icon - Icon HTML content
-   * @returns The button component for chaining
-   */
-  setIcon: (icon: string) => ButtonComponent;
-  
-  /**
-   * Gets the button's icon HTML content
-   * @returns Icon HTML
-   */
-  getIcon: () => string;
-  
-  /**
-   * Destroys the button component and cleans up resources
-   */
-  destroy: () => void;
-  
-  /**
-   * Updates the button's circular style based on content
-   * Internal method used when changing content
-   */
-  updateCircularStyle: () => void;
-  
-  /**
-   * Sets the active state of the button
-   * Used to visually indicate the button's active state, such as when it has a menu open
-   * 
-   * @param active - Whether the button should appear active
-   * @returns The button component for chaining
-   */
-  setActive: (active: boolean) => ButtonComponent;
-  
-  /**
-   * Adds an event listener to the button
-   * @param event - Event name ('click', 'focus', etc.)
-   * @param handler - Event handler function
-   * @returns The button component for chaining
-   */
-  on: (event: string, handler: Function) => ButtonComponent;
-  
-  /**
-   * Removes an event listener from the button
-   * @param event - Event name
-   * @param handler - Event handler function
-   * @returns The button component for chaining
-   */
-  off: (event: string, handler: Function) => ButtonComponent;
-  
-  /**
-   * Adds CSS classes to the button element
-   * @param classes - One or more class names to add
-   * @returns The button component for chaining
-   */
-  addClass: (...classes: string[]) => ButtonComponent;
-
-  /**
-   * Sets the aria-label attribute for accessibility
-   * @param label - Aria label text
-   * @returns The button component for chaining
-   */
-  setAriaLabel: (label: string) => ButtonComponent;
-}