mtrl 0.3.8 → 0.4.0

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

@@ -0,0 +1,256 @@
+/**
+ * Badge variant types - determines the badge size and appearance
+ * @category Components
+ * @remarks
+ * - small: A 6dp circular dot badge without text (for notification indicators)
+ * - large: A 16dp height badge that can contain text (for counts or short labels)
+ */
+export type BadgeVariant = 'small' | 'large';
+/**
+ * Badge color types - determines the badge's background color
+ * @category Components
+ * @remarks
+ * Based on Material Design 3 color system:
+ * - error: Red color for error states (default)
+ * - primary: Primary theme color
+ * - secondary: Secondary theme color
+ * - tertiary: Tertiary theme color
+ * - success: Green color for success states
+ * - warning: Orange/yellow color for warning states
+ * - info: Blue color for information states
+ */
+export type BadgeColor = 'error' | 'primary' | 'secondary' | 'tertiary' | 'success' | 'warning' | 'info';
+/**
+ * Badge position types - determines where the badge appears relative to its target
+ * @category Components
+ * @remarks
+ * - top-right: Position in the top-right corner (default)
+ * - top-left: Position in the top-left corner
+ * - bottom-right: Position in the bottom-right corner
+ * - bottom-left: Position in the bottom-left corner
+ */
+export type BadgePosition = 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left';
+/**
+ * Configuration interface for the Badge component
+ * @category Components
+ * @description
+ * Defines the appearance and behavior of a badge component.
+ * All properties are optional with sensible defaults.
+ */
+export interface BadgeConfig {
+    /**
+     * Badge variant (small dot or large numbered)
+     * Small badge (6dp) or Large badge (16dp height)
+     * @default 'large'
+     * @example 'small' | 'large'
+     */
+    variant?: BadgeVariant | string;
+    /**
+     * Badge color (follows Material Design 3 color system)
+     * @default 'error'
+     * @example 'error' | 'primary' | 'secondary' | 'tertiary' | 'success' | 'warning' | 'info'
+     */
+    color?: BadgeColor | string;
+    /**
+     * Badge position relative to its container element
+     * @default 'top-right'
+     * @example 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left'
+     */
+    position?: BadgePosition | string;
+    /**
+     * Text label inside the badge (for large badges)
+     * Up to 4 characters, numbers exceeding max will show "{max}+"
+     * @example "3" | "99+" | "New"
+     */
+    label?: string | number;
+    /**
+     * Maximum value to display (shows "{max}+" if label exceeds max)
+     * Usually 999+ for large numbers
+     * @example 99 | 999
+     */
+    max?: number;
+    /**
+     * Whether the badge should be initially visible
+     * @default true
+     */
+    visible?: boolean;
+    /**
+     * Target element to which badge will be attached
+     * When provided, the badge will be positioned relative to this element
+     */
+    target?: HTMLElement;
+    /**
+     * Additional CSS classes to apply to the badge element
+     * @example "custom-badge highlighted-badge"
+     */
+    class?: string;
+    /**
+     * CSS class prefix for all badge classes
+     * @default "mtrl"
+     */
+    prefix?: string;
+    /**
+     * Component name used in CSS class generation
+     * @default "badge"
+     * @internal
+     */
+    componentName?: string;
+}
+/**
+ * Badge component interface
+ * Provides methods for controlling a Material Design 3 badge
+ *
+ * @category Components
+ */
+export interface BadgeComponent {
+    /**
+     * The badge's root DOM element
+     */
+    element: HTMLElement;
+    /**
+     * Badge wrapper element (if badge is attached to target)
+     * This is the parent element that contains both the target and the badge
+     */
+    wrapper?: HTMLElement;
+    /**
+     * Sets the badge's text label
+     * @param label - Text or number to display in the badge
+     * @returns Badge component for method chaining
+     * @example
+     * badge.setLabel(5); // Shows "5"
+     * badge.setLabel("New"); // Shows "New"
+     * badge.setLabel(1250); // With max=999, shows "999+"
+     */
+    setLabel: (label: string | number) => BadgeComponent;
+    /**
+     * Gets the badge's current text label
+     * @returns Current text content of the badge
+     */
+    getLabel: () => string;
+    /**
+     * Sets the badge's content (alias for setLabel)
+     * @param content - Text or number to display in the badge
+     * @returns Badge component for method chaining
+     */
+    setContent: (content: string | number) => BadgeComponent;
+    /**
+     * Gets the badge's current content (alias for getLabel)
+     * @returns Current text content of the badge
+     */
+    getContent: () => string;
+    /**
+     * Shows the badge (makes it visible)
+     * @returns Badge component for method chaining
+     */
+    show: () => BadgeComponent;
+    /**
+     * Hides the badge (makes it invisible)
+     * @returns Badge component for method chaining
+     */
+    hide: () => BadgeComponent;
+    /**
+     * Toggles badge visibility
+     * @param visible - Optional explicit visibility state
+     * @returns Badge component for method chaining
+     * @example
+     * badge.toggle(); // Toggles current state
+     * badge.toggle(true); // Forces visible
+     */
+    toggle: (visible?: boolean) => BadgeComponent;
+    /**
+     * Checks if the badge is currently visible
+     * @returns True if badge is visible, false otherwise
+     */
+    isVisible: () => boolean;
+    /**
+     * Sets maximum value (after which badge shows max+)
+     * @param max - Maximum number to display before showing "+"
+     * @returns Badge component for method chaining
+     * @example
+     * badge.setMax(99); // Shows "99+" for values > 99
+     */
+    setMax: (max: number) => BadgeComponent;
+    /**
+     * Sets badge color
+     * @param color - Badge color from Material Design 3 palette
+     * @returns Badge component for method chaining
+     * @example
+     * badge.setColor('primary');
+     * badge.setColor(BADGE_COLORS.SUCCESS);
+     */
+    setColor: (color: BadgeColor | string) => BadgeComponent;
+    /**
+     * Sets badge variant (size style)
+     * @param variant - Badge variant ('small' or 'large')
+     * @returns Badge component for method chaining
+     * @example
+     * badge.setVariant('small'); // Dot indicator
+     * badge.setVariant(BADGE_VARIANTS.LARGE); // Numbered indicator
+     */
+    setVariant: (variant: BadgeVariant | string) => BadgeComponent;
+    /**
+     * Sets badge position relative to target
+     * @param position - Badge position
+     * @returns Badge component for method chaining
+     * @example
+     * badge.setPosition('bottom-left');
+     */
+    setPosition: (position: BadgePosition | string) => BadgeComponent;
+    /**
+     * Attaches badge to a target element
+     * @param target - Element to attach badge to
+     * @returns Badge component for method chaining
+     * @example
+     * badge.attachTo(document.querySelector('#notification-bell'));
+     */
+    attachTo: (target: HTMLElement) => BadgeComponent;
+    /**
+     * Makes badge standalone (removes from wrapper)
+     * @returns Badge component for method chaining
+     */
+    detach: () => BadgeComponent;
+    /**
+     * Destroys the badge component and cleans up resources
+     * Removes the badge from the DOM and clears event listeners
+     */
+    destroy: () => void;
+    /**
+     * Gets a class name with the component's prefix
+     * @param name - Base class name
+     * @returns Prefixed class name
+     * @internal
+     */
+    getClass: (name: string) => string;
+    /**
+     * Adds CSS classes to the badge element
+     * @param classes - One or more class names to add
+     * @returns Badge component for method chaining
+     * @example
+     * badge.addClass('highlighted', 'animated');
+     */
+    addClass: (...classes: string[]) => BadgeComponent;
+    /**
+     * Removes CSS classes from the badge element
+     * @param classes - One or more class names to remove
+     * @returns Badge component for method chaining
+     * @example
+     * badge.removeClass('highlighted', 'animated');
+     */
+    removeClass: (...classes: string[]) => BadgeComponent;
+    /**
+     * Adds an event listener to the badge
+     * @param event - Event name ('click', 'mouseover', etc.)
+     * @param handler - Event handler function
+     * @returns Badge component for method chaining
+     * @example
+     * badge.on('click', () => console.log('Badge clicked'));
+     */
+    on: (event: string, handler: Function) => BadgeComponent;
+    /**
+     * Removes an event listener from the badge
+     * @param event - Event name
+     * @param handler - Event handler function
+     * @returns Badge component for method chaining
+     */
+    off: (event: string, handler: Function) => BadgeComponent;
+}

package/dist/components/bottom-app-bar/bottom-app-bar.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @module components/bottom-app-bar
+ * @description Bottom app bar implementation
+ */
+import { BottomAppBar, BottomAppBarConfig } from './types';
+/**
+ * Creates a bottom app bar component
+ *
+ * @param {BottomAppBarConfig} config - Configuration options
+ * @returns {BottomAppBar} Bottom app bar component instance
+ */
+export declare const createBottomAppBar: (config?: BottomAppBarConfig) => BottomAppBar;

package/dist/components/bottom-app-bar/config.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @module components/bottom-app-bar
+ * @description Configuration for bottom app bar component
+ */
+import { BottomAppBarConfig } from './types';
+/**
+ * Default configuration for bottom app bar
+ */
+export declare const defaultConfig: Partial<BottomAppBarConfig>;
+/**
+ * Creates the configuration for a bottom app bar component
+ *
+ * @param {BottomAppBarConfig} config - User provided configuration
+ * @returns {BottomAppBarConfig} Complete configuration with defaults applied
+ */
+export declare const createConfig: (config?: BottomAppBarConfig) => BottomAppBarConfig;

package/dist/components/bottom-app-bar/constants.d.ts

@@ -0,0 +1,22 @@
+/**
+ * FAB position constants for Bottom App Bar
+ */
+export declare const FAB_POSITIONS: {
+    readonly CENTER: "center";
+    readonly END: "end";
+};
+/**
+ * Default transition duration for show/hide animations
+ */
+export declare const DEFAULT_TRANSITION_DURATION = 300;
+/**
+ * CSS class names used in the bottom app bar component
+ */
+export declare const BOTTOM_APP_BAR_CLASSES: {
+    readonly ROOT: "bottom-app-bar";
+    readonly ACTIONS: "bottom-app-bar-actions";
+    readonly FAB_CONTAINER: "bottom-app-bar-fab";
+    readonly HIDDEN: "bottom-app-bar--hidden";
+    readonly FAB_CENTER: "bottom-app-bar--fab-center";
+    readonly FAB_END: "bottom-app-bar--fab-end";
+};

package/{src/components/bottom-app-bar/index.ts → dist/components/bottom-app-bar/index.d.ts}

@@ -1,17 +1,8 @@
-// src/components/bottom-app-bar/index.ts
 /**
  * @module components/bottom-app-bar
  * @description Bottom app bar component for mobile interfaces
  */
-
 import { createBottomAppBar } from './bottom-app-bar';
-
 export default createBottomAppBar;
 export { createBottomAppBar };
 export type { BottomAppBarConfig, BottomAppBar } from './types';
-
-// Export position constants for convenience and backward compatibility
-export const FAB_POSITIONS = {
-  CENTER: 'center',
-  END: 'end'
-} as const;

package/dist/components/bottom-app-bar/types.d.ts

@@ -0,0 +1,96 @@
+/**
+ * @module components/bottom-app-bar
+ * @description Type definitions for Bottom App Bar component
+ */
+import { ElementComponent } from '../../core/compose';
+/**
+ * FAB position type for Bottom App Bar
+ * @category Components
+ */
+export type FabPosition = 'center' | 'end';
+/**
+ * Configuration options for Bottom App Bar component
+ * @category Components
+ */
+export interface BottomAppBarConfig {
+    /**
+     * Element to use for the container
+     * @default 'div'
+     */
+    tag?: string;
+    /**
+     * Whether to show FAB in the bottom bar
+     * @default false
+     */
+    hasFab?: boolean;
+    /**
+     * FAB position in bottom bar
+     * @default 'end'
+     */
+    fabPosition?: FabPosition;
+    /**
+     * Additional CSS classes to apply
+     */
+    class?: string;
+    /**
+     * Whether to enable auto-hide on scroll
+     * @default false
+     */
+    autoHide?: boolean;
+    /**
+     * Transition duration for show/hide in ms
+     * @default 300
+     */
+    transitionDuration?: number;
+    /**
+     * Optional callback when scrolling shows/hides the bar
+     */
+    onVisibilityChange?: (visible: boolean) => void;
+    /**
+     * Component prefix for class names
+     * @default 'mtrl'
+     */
+    prefix?: string;
+    /**
+     * Component name for class generation
+     */
+    componentName?: string;
+}
+/**
+ * Bottom App Bar component interface
+ * @category Components
+ */
+export interface BottomAppBar extends ElementComponent {
+    /**
+     * Adds an action button to the bottom bar
+     * @param {HTMLElement} button - Button element to add
+     * @returns {BottomAppBar} BottomAppBar instance for chaining
+     */
+    addAction: (button: HTMLElement) => BottomAppBar;
+    /**
+     * Adds a floating action button to the bottom bar
+     * @param {HTMLElement} fab - FAB element to add
+     * @returns {BottomAppBar} BottomAppBar instance for chaining
+     */
+    addFab: (fab: HTMLElement) => BottomAppBar;
+    /**
+     * Shows the bottom bar
+     * @returns {BottomAppBar} BottomAppBar instance for chaining
+     */
+    show: () => BottomAppBar;
+    /**
+     * Hides the bottom bar
+     * @returns {BottomAppBar} BottomAppBar instance for chaining
+     */
+    hide: () => BottomAppBar;
+    /**
+     * Checks if the bottom bar is visible
+     * @returns {boolean} Whether the bottom bar is visible
+     */
+    isVisible: () => boolean;
+    /**
+     * Get the actions container element
+     * @returns {HTMLElement} Actions container element
+     */
+    getActionsContainer: () => HTMLElement;
+}

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

@@ -0,0 +1,47 @@
+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;
+    componentName?: 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 declare const withAPI: ({ disabled, lifecycle }: ApiOptions) => (component: ComponentWithElements) => ButtonComponent;
+export {};

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

@@ -0,0 +1,25 @@
+import { ButtonConfig } from './types';
+/**
+ * Creates a new Button component with the specified configuration.
+ *
+ * The Button component implements 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
+ */
+declare const createButton: (config?: ButtonConfig) => any;
+export default createButton;

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

@@ -0,0 +1,59 @@
+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 declare const defaultConfig: ButtonConfig;
+/**
+ * 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 declare const createBaseConfig: (config?: ButtonConfig) => 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 declare const getElementConfig: (config: ButtonConfig) => {
+    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 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 declare const getApiConfig: (comp: any) => {
+    disabled: {
+        enable: () => any;
+        disable: () => any;
+    };
+    lifecycle: {
+        destroy: () => any;
+    };
+};
+export default defaultConfig;

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

@@ -0,0 +1,43 @@
+/**
+ * Button variants
+ */
+export declare const BUTTON_VARIANTS: {
+    /** Primary action button with solid background (high emphasis) */
+    readonly FILLED: "filled";
+    /** Secondary action button with medium emphasis */
+    readonly TONAL: "tonal";
+    /** Button with outline border and transparent background */
+    readonly OUTLINED: "outlined";
+    /** Button with slight elevation/shadow */
+    readonly ELEVATED: "elevated";
+    /** Button that appears as text without background or border (low emphasis) */
+    readonly TEXT: "text";
+};
+/**
+ * Default button types
+ */
+export declare const BUTTON_TYPES: {
+    readonly BUTTON: "button";
+    readonly SUBMIT: "submit";
+    readonly RESET: "reset";
+};
+/**
+ * CSS classes used by the button component
+ */
+export declare const BUTTON_CLASSES: {
+    readonly ROOT: "button";
+    readonly ICON: "button-icon";
+    readonly TEXT: "button-text";
+    readonly CIRCULAR: "button-circular";
+    readonly ACTIVE: "button-active";
+    readonly DISABLED: "button-disabled";
+};
+/**
+ * Default ripple effect configuration
+ * Enhanced for better visibility
+ */
+export declare const DEFAULT_RIPPLE_CONFIG: {
+    readonly DURATION: 450;
+    readonly TIMING: "cubic-bezier(0.4, 0.0, 0.2, 1)";
+    readonly OPACITY: readonly ["0.7", "0"];
+};

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

@@ -0,0 +1,6 @@
+/**
+ * Button component module
+ * @module components/button
+ */
+export { default } from './button';
+export { ButtonConfig, ButtonComponent, ButtonVariant } from './types';