mtrl 0.3.8 → 0.4.0

package/dist/components/button/types.d.ts

@@ -0,0 +1,265 @@
+/**
+ * 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;
+    /**
+     * Gets the button's current variant
+     * @returns Current variant name ('filled', 'outlined', etc.)
+     */
+    getVariant: () => ButtonVariant | string;
+    /**
+     * Sets the button's variant (visual style)
+     * @param variant - New variant to apply ('filled', 'outlined', 'text', etc.)
+     * @returns The button component for chaining
+     */
+    setVariant: (variant: ButtonVariant | 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;
+    /**
+     * Checks if the button has an icon
+     * @returns True if the button has an icon, false otherwise
+     */
+    hasIcon: () => boolean;
+    /**
+     * Sets the button's icon
+     * If empty string is provided, removes the icon completely
+     * @param icon - Icon HTML content, or empty string to remove
+     * @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;
+}

package/dist/components/card/api.d.ts

@@ -0,0 +1,11 @@
+import { BaseComponent, CardComponent, ApiOptions } from './types';
+/**
+ * Enhances a card 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
+ */
+export declare const withAPI: ({ lifecycle }: ApiOptions) => (component: BaseComponent) => CardComponent;

package/{src/components/card/card.ts → dist/components/card/card.d.ts}

@@ -1,31 +1,11 @@
-// src/components/card/card.ts
-import { pipe } from '../../core/compose';
-import { createBase, withElement } from '../../core/compose/component';
-import {
-  withEvents,
-  withVariant,
-  withRipple,
-  withLifecycle
-} from '../../core/compose/features';
-import { withAPI } from './api';
-import { CardComponent, BaseComponent, CardSchema } from './types';
-import { 
-  createBaseConfig, 
-  getElementConfig, 
-  getApiConfig, 
-  withInteractiveBehavior,
-  processInlineConfig,
-  applyInlineConfiguration
-} from './config';
-import { withElevation } from './features';
-
+import { CardComponent, CardSchema } from './types';
 /**
  * Creates a new Card component following Material Design 3 principles.
- * 
+ *
  * Material Design 3 Cards are surfaces that display content and actions about a single topic.
- * Cards can contain text, media, and UI controls. They provide entry points to more 
+ * Cards can contain text, media, and UI controls. They provide entry points to more
  * detailed information and can include interactive elements.
- * 
+ *
  * @param {CardSchema} config - Card configuration object
  * @returns {CardComponent} Card component instance with the following API methods:
  * - `addContent(contentElement)`: Adds content to the card
@@ -35,7 +15,7 @@ import { withElevation } from './features';
  * - `makeDraggable(dragStartCallback)`: Makes the card draggable
  * - `focus()`: Sets focus to the card
  * - `destroy()`: Destroys the card component and removes event listeners
- * 
+ *
  * @throws {Error} Throws an error if card creation fails
  * @category Components
  * @example
@@ -51,7 +31,7 @@ import { withElevation } from './features';
  *     text: 'Card content goes here.'
  *   }
  * });
- * 
+ *
  * // Create an interactive card with actions
  * const cardWithActions = createCard({
  *   variant: 'filled',
@@ -63,7 +43,7 @@ import { withElevation } from './features';
  *     { text: 'Action 2', variant: 'filled' }
  *   ]
  * });
- * 
+ *
  * // Card with media
  * const mediaCard = createCard({
  *   media: {
@@ -73,7 +53,7 @@ import { withElevation } from './features';
  *   },
  *   header: { title: 'Media Card' }
  * });
- * 
+ *
  * // Using API methods
  * const card = createCard();
  * const content = document.createElement('div');
@@ -83,33 +63,5 @@ import { withElevation } from './features';
  * card.makeDraggable();
  * ```
  */
-const createCard = (config: CardSchema = {}): CardComponent => {
-  // Process inline configuration (map shorthand properties)
-  const processedConfig = processInlineConfig(config);
-  const baseConfig = createBaseConfig(processedConfig);
-
-  try {
-    // Create the core card component
-    const card = pipe(
-      createBase,
-      withEvents(),
-      withElement(getElementConfig(baseConfig)),
-      withVariant(baseConfig),
-      baseConfig.clickable ? withRipple(baseConfig) : (c: BaseComponent) => c,
-      withLifecycle(),
-      withInteractiveBehavior,
-      withElevation,
-      comp => withAPI(getApiConfig(comp))(comp)
-    )(baseConfig) as CardComponent;
-    
-    // Apply any inline configuration
-    applyInlineConfiguration(card, processedConfig);
-    
-    return card;
-  } catch (error) {
-    console.error('Card creation error:', error instanceof Error ? error.message : String(error));
-    throw new Error(`Failed to create card: ${error instanceof Error ? error.message : String(error)}`);
-  }
-};
-
-export default createCard;
+declare const createCard: (config?: CardSchema) => CardComponent;
+export default createCard;

package/dist/components/card/config.d.ts

@@ -0,0 +1,105 @@
+import { CardComponent, CardSchema, BaseComponent } from './types';
+/**
+ * Default configuration for the Card component.
+ * These values are used when no configuration is provided.
+ *
+ * @const {CardSchema}
+ * @category Components
+ */
+export declare const defaultConfig: CardSchema;
+/**
+ * Processes inline configuration options into standard config format.
+ * Maps shorthand properties to their proper config counterparts for ease of use.
+ *
+ * @param {CardSchema} config - Raw card configuration
+ * @returns {CardSchema} Processed configuration
+ * @category Components
+ * @example
+ * ```typescript
+ * // Before processing, these are equivalent:
+ * { header: { title: 'Example' } }
+ * { headerConfig: { title: 'Example' } }
+ * ```
+ */
+export declare const processInlineConfig: (config: CardSchema) => CardSchema;
+/**
+ * Applies inline configuration to a card component.
+ * Adds configured elements to the card in the correct order following
+ * Material Design layout guidelines. Handles media, header, content, and actions placement.
+ *
+ * @param {CardComponent} card - Card component to configure
+ * @param {CardSchema} config - Processed configuration
+ * @category Components
+ */
+export declare const applyInlineConfiguration: (card: CardComponent, config: CardSchema) => void;
+/**
+ * Creates the base configuration for Card component.
+ * Merges user-provided configuration with default values,
+ * ensuring all required properties are set.
+ *
+ * @param {CardSchema} config - User provided configuration
+ * @returns {CardSchema} Complete configuration with defaults applied
+ * @category Components
+ *
+ */
+export declare const createBaseConfig: (config?: CardSchema) => CardSchema;
+/**
+ * Generates element configuration for the Card component.
+ * Sets up DOM attributes, accessibility features, and event forwarding
+ * based on the card's configuration.
+ *
+ * @param {CardSchema} config - Card configuration
+ * @returns {Object} Element configuration object for withElement
+ * @category Components
+ *
+ */
+export declare const getElementConfig: (config: CardSchema) => {
+    tag: string;
+    componentName: string;
+    attributes: Record<string, any>;
+    className: string[];
+    rawClass: string | string[];
+    html: string;
+    text: string;
+    forwardEvents: Record<string, boolean | ((component: any, event: Event) => boolean)>;
+    interactive: boolean;
+};
+/**
+ * Creates API configuration for the Card component.
+ * Prepares the configuration needed for the card's public API methods.
+ *
+ * @param {Object} comp - Component with lifecycle feature
+ * @returns {Object} API configuration object
+ * @category Components
+ *
+ */
+export declare const getApiConfig: (comp: any) => {
+    lifecycle: {
+        destroy: () => any;
+    };
+};
+/**
+ * Card elevation levels in density-independent pixels (dp).
+ * Following Material Design 3 elevation system guidelines.
+ *
+ * @category Components
+ */
+export declare const CARD_ELEVATION_LEVELS: {
+    readonly LEVEL0: 0;
+    readonly LEVEL1: 1;
+    readonly LEVEL2: 2;
+    readonly LEVEL4: 4;
+};
+/**
+ * Adds interactive behavior to card component.
+ * Uses the mtrl elevation system for proper elevation levels according to Material Design 3
+ * guidelines. Implements mouse, keyboard, and touch interactions with appropriate
+ * visual feedback and accessibility support.
+ *
+ * @param {BaseComponent} comp - Card component
+ * @returns {BaseComponent} Enhanced card component
+ * @category Components
+ *
+ */
+export declare const withInteractiveBehavior: (comp: BaseComponent) => BaseComponent;
+export default defaultConfig;

package/dist/components/card/constants.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Card variants following Material Design 3 guidelines
+ * - ELEVATED: Card with shadow elevation (default)
+ * - FILLED: Card with filled background color and no elevation
+ * - OUTLINED: Card with outline border and no elevation
+ */
+export declare const CARD_VARIANTS: {
+    readonly ELEVATED: "elevated";
+    readonly FILLED: "filled";
+    readonly OUTLINED: "outlined";
+};
+/**
+ * Card elevation levels in Material Design 3
+ * Specifies the shadow height in density-independent pixels (dp)
+ */
+export declare const CARD_ELEVATIONS: {
+    readonly LEVEL0: 0;
+    readonly LEVEL1: 1;
+    readonly LEVEL2: 2;
+    readonly LEVEL4: 4;
+};
+/**
+ * Card width constants
+ * Provides standardized card widths based on Material Design
+ */
+export declare const CARD_WIDTHS: {
+    readonly SMALL: "344px";
+    readonly MEDIUM: "480px";
+    readonly LARGE: "624px";
+    readonly FULL: "100%";
+};
+/**
+ * Card corner radius options
+ * Provides standardized corner radius values
+ */
+export declare const CARD_CORNER_RADIUS: {
+    readonly SMALL: "8px";
+    readonly MEDIUM: "12px";
+    readonly LARGE: "16px";
+};
+/**
+ * Card media aspect ratio options
+ */
+export declare const CARD_ASPECT_RATIOS: {
+    readonly SQUARE: "1:1";
+    readonly STANDARD: "4:3";
+    readonly WIDESCREEN: "16:9";
+};
+/**
+ * Card action alignment options
+ */
+export declare const CARD_ACTION_ALIGNMENT: {
+    readonly START: "start";
+    readonly CENTER: "center";
+    readonly END: "end";
+    readonly SPACE_BETWEEN: "space-between";
+};
+/**
+ * Card media position options
+ */
+export declare const CARD_MEDIA_POSITION: {
+    readonly TOP: "top";
+    readonly BOTTOM: "bottom";
+};
+/**
+ * CSS class names used in the card component
+ */
+export declare const CARD_CLASSES: {
+    readonly ROOT: "card";
+    readonly HEADER: "card-header";
+    readonly TITLE: "card-title";
+    readonly SUBTITLE: "card-subtitle";
+    readonly AVATAR: "card-avatar";
+    readonly HEADER_ACTION: "card-header-action";
+    readonly CONTENT: "card-content";
+    readonly MEDIA: "card-media";
+    readonly ACTIONS: "card-actions";
+    readonly DRAGGABLE: "card-draggable";
+    readonly INTERACTIVE: "card-interactive";
+    readonly FULL_WIDTH: "card-full-width";
+    readonly CLICKABLE: "card-clickable";
+    readonly LOADING: "card-loading";
+    readonly EXPANDED: "card-expanded";
+    readonly ELEVATION_PREFIX: "card-elevation-";
+};

package/dist/components/card/content.d.ts

@@ -0,0 +1,92 @@
+import { CardContentConfig, CardHeaderConfig, CardMediaConfig, CardActionsConfig } from './types';
+export declare const CARD_CONTENT_PADDING = true;
+/**
+ * Creates a card content component
+ *
+ * @param {CardContentConfig} config - Content configuration
+ * @returns {HTMLElement} Card content element
+ *
+ * @example
+ * ```typescript
+ * // Create text content
+ * const textContent = createCardContent({ text: 'Simple text content' });
+ *
+ * // Create HTML content with no padding
+ * const htmlContent = createCardContent({
+ *   html: '<p>Formatted <strong>HTML</strong> content</p>',
+ *   padding: false
+ * });
+ * ```
+ */
+export declare const createCardContent: (config?: CardContentConfig) => HTMLElement;
+/**
+ * Creates a card header component
+ *
+ * @param {CardHeaderConfig} config - Header configuration
+ * @returns {HTMLElement} Card header element
+ *
+ * @example
+ * ```typescript
+ * // Create a header with title and subtitle
+ * const header = createCardHeader({
+ *   title: 'Card Title',
+ *   subtitle: 'Supporting text'
+ * });
+ *
+ * // Create a header with an avatar and action
+ * const avatarHeader = createCardHeader({
+ *   title: 'User Profile',
+ *   avatar: '<img src="user.jpg" alt="User avatar">',
+ *   action: createIconButton({ icon: 'more_vert' })
+ * });
+ * ```
+ */
+export declare const createCardHeader: (config?: CardHeaderConfig) => HTMLElement;
+/**
+ * Creates a card actions component
+ *
+ * @param {CardActionsConfig} config - Actions configuration
+ * @returns {HTMLElement} Card actions element
+ *
+ * @example
+ * ```typescript
+ * // Create simple actions container with buttons
+ * const actions = createCardActions({
+ *   actions: [
+ *     createButton({ text: 'Cancel' }),
+ *     createButton({ text: 'OK', variant: 'filled' })
+ *   ],
+ *   align: 'end'
+ * });
+ *
+ * // Create full-bleed actions
+ * const fullBleedActions = createCardActions({
+ *   actions: [createButton({ text: 'View Details', fullWidth: true })],
+ *   fullBleed: true
+ * });
+ * ```
+ */
+export declare const createCardActions: (config?: CardActionsConfig) => HTMLElement;
+/**
+ * Creates a card media component
+ *
+ * @param {CardMediaConfig} config - Media configuration
+ * @returns {HTMLElement} Card media element
+ *
+ * @example
+ * ```typescript
+ * // Create a media component with an image
+ * const media = createCardMedia({
+ *   src: 'image.jpg',
+ *   alt: 'Descriptive alt text',
+ *   aspectRatio: '16:9'
+ * });
+ *
+ * // Create a media component with a custom element
+ * const customMedia = createCardMedia({
+ *   element: videoElement,
+ *   aspectRatio: '4:3'
+ * });
+ * ```
+ */
+export declare const createCardMedia: (config?: CardMediaConfig) => HTMLElement;