mtrl 0.5.5 → 0.5.7

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

@@ -2,5 +2,5 @@
  * Button component module
  * @module components/button
  */
-export { default } from './button';
-export { ButtonConfig, ButtonComponent, ButtonVariant } from './types';
+export { default } from "./button";
+export type { ButtonConfig, ButtonComponent, ButtonVariant } from "./types";

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

@@ -0,0 +1,51 @@
+import { ButtonGroupConfig, ButtonGroupComponent } from './types';
+/**
+ * Creates a new Button Group component
+ *
+ * The Button Group component provides a container for grouping related action buttons.
+ * Unlike Segmented Buttons (used for selection), Button Groups are for grouping
+ * related actions where each button triggers an independent action.
+ *
+ * Per Material Design 3 specifications:
+ * - Buttons are visually connected with shared borders
+ * - Only outer corners are rounded
+ * - All buttons share the same variant for visual consistency
+ * - Supports horizontal and vertical orientations
+ * - Supports density scaling
+ *
+ * @param {ButtonGroupConfig} config - Button Group configuration
+ * @returns {ButtonGroupComponent} Button Group component instance
+ *
+ * @example
+ * // Create a horizontal button group for text formatting
+ * const formattingTools = createButtonGroup({
+ *   buttons: [
+ *     { icon: boldIcon, ariaLabel: 'Bold' },
+ *     { icon: italicIcon, ariaLabel: 'Italic' },
+ *     { icon: underlineIcon, ariaLabel: 'Underline' }
+ *   ],
+ *   variant: 'outlined',
+ *   ariaLabel: 'Text formatting options'
+ * });
+ *
+ * // Listen for button clicks
+ * formattingTools.on('click', (event) => {
+ *   console.log('Button clicked:', event.index);
+ * });
+ *
+ * @example
+ * // Create a vertical button group with text labels
+ * const navigationGroup = createButtonGroup({
+ *   buttons: [
+ *     { text: 'Previous', icon: prevIcon },
+ *     { text: 'Play', icon: playIcon },
+ *     { text: 'Next', icon: nextIcon }
+ *   ],
+ *   orientation: 'vertical',
+ *   variant: 'tonal'
+ * });
+ *
+ * @category Components
+ */
+declare const createButtonGroup: (config?: ButtonGroupConfig) => ButtonGroupComponent;
+export default createButtonGroup;

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

@@ -0,0 +1,78 @@
+import { ButtonGroupConfig, ButtonGroupVariant, ButtonGroupOrientation, ButtonGroupDensity } from './types';
+/**
+ * Default configuration values for button groups
+ * @internal
+ */
+export declare const DEFAULT_CONFIG: Partial<ButtonGroupConfig>;
+/**
+ * Creates the base configuration for Button Group component
+ * @param {ButtonGroupConfig} config - User provided configuration
+ * @returns {ButtonGroupConfig} Complete configuration with defaults applied
+ * @internal
+ */
+export declare const createBaseConfig: (config?: ButtonGroupConfig) => ButtonGroupConfig;
+/**
+ * Generates element configuration for the Button Group container
+ * @param {ButtonGroupConfig} config - Button Group configuration
+ * @returns {Object} Element configuration object for withElement
+ * @internal
+ */
+export declare const getContainerConfig: (config: ButtonGroupConfig) => {
+    tag: string;
+    componentName: string;
+    attributes: {
+        role: string;
+        'aria-label': string;
+        'data-variant': ButtonGroupVariant;
+        'data-orientation': ButtonGroupOrientation;
+        'data-density': ButtonGroupDensity;
+    };
+    className: string[];
+    interactive: boolean;
+};
+/**
+ * Gets density-specific sizing values per MD3 specifications
+ * @param {ButtonGroupDensity} density - The density level
+ * @returns {Object} CSS variables with sizing values
+ * @internal
+ */
+export declare const getDensityStyles: (density: ButtonGroupDensity) => Record<string, string>;
+/**
+ * Generates configuration for a button element within the group
+ * @param {Object} buttonConfig - Button configuration
+ * @param {number} index - Button index in the group
+ * @param {number} total - Total number of buttons
+ * @param {ButtonGroupConfig} groupConfig - Parent group configuration
+ * @returns {Object} Button configuration with group-specific settings
+ * @internal
+ */
+export declare const getButtonConfig: (buttonConfig: ButtonGroupConfig["buttons"][number], index: number, total: number, groupConfig: ButtonGroupConfig) => {
+    variant: ButtonGroupVariant;
+    disabled: boolean;
+    ripple: boolean;
+    rippleConfig: {
+        duration?: number;
+        timing?: string;
+        opacity?: [string, string];
+    };
+    class: string;
+    id?: string;
+    text?: string;
+    icon?: string;
+    ariaLabel?: string;
+    value?: string;
+};
+/**
+ * Maps variant name to button variant
+ * @param {ButtonGroupVariant} variant - Group variant
+ * @returns {string} Button variant name
+ * @internal
+ */
+export declare const mapVariantToButton: (variant: ButtonGroupVariant) => string;
+/**
+ * Validates button group configuration
+ * @param {ButtonGroupConfig} config - Configuration to validate
+ * @returns {boolean} Whether configuration is valid
+ * @internal
+ */
+export declare const validateConfig: (config: ButtonGroupConfig) => boolean;

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

@@ -0,0 +1,128 @@
+/**
+ * Button group variants
+ * All buttons in the group share the same variant for visual consistency
+ */
+export declare const BUTTON_GROUP_VARIANTS: {
+    /** Primary action buttons with solid background */
+    readonly FILLED: "filled";
+    /** Secondary action buttons with medium emphasis */
+    readonly TONAL: "tonal";
+    /** Buttons with outline border (default for button groups per MD3) */
+    readonly OUTLINED: "outlined";
+    /** Buttons with slight elevation/shadow */
+    readonly ELEVATED: "elevated";
+    /** Text-only buttons without background or border */
+    readonly TEXT: "text";
+};
+/**
+ * Button group orientations
+ */
+export declare const BUTTON_GROUP_ORIENTATIONS: {
+    /** Buttons arranged horizontally (default) */
+    readonly HORIZONTAL: "horizontal";
+    /** Buttons arranged vertically */
+    readonly VERTICAL: "vertical";
+};
+/**
+ * Density levels for button groups
+ * Controls sizing and spacing per MD3 density specifications
+ */
+export declare const BUTTON_GROUP_DENSITY: {
+    /** Default size with standard spacing (40px height) */
+    readonly DEFAULT: "default";
+    /** Reduced size and spacing (36px height) */
+    readonly COMFORTABLE: "comfortable";
+    /** Minimal size and spacing (32px height) */
+    readonly COMPACT: "compact";
+};
+/**
+ * Button group events
+ */
+export declare const BUTTON_GROUP_EVENTS: {
+    /** Fired when any button in the group is clicked */
+    readonly CLICK: "click";
+    /** Fired when a button receives focus */
+    readonly FOCUS: "focus";
+    /** Fired when a button loses focus */
+    readonly BLUR: "blur";
+};
+/**
+ * Default configuration values
+ */
+export declare const BUTTON_GROUP_DEFAULTS: {
+    /** Default variant (outlined per MD3 button group specs) */
+    readonly VARIANT: "outlined";
+    /** Default orientation */
+    readonly ORIENTATION: "horizontal";
+    /** Default density level */
+    readonly DENSITY: "default";
+    /** Whether ripple effect is enabled by default */
+    readonly RIPPLE: true;
+    /** Whether buttons have equal width by default */
+    readonly EQUAL_WIDTH: false;
+    /** Default ripple animation duration in milliseconds */
+    readonly RIPPLE_DURATION: 300;
+    /** Default ripple animation timing function */
+    readonly RIPPLE_TIMING: "cubic-bezier(0.4, 0, 0.2, 1)";
+    /** Default ripple opacity values [start, end] */
+    readonly RIPPLE_OPACITY: [string, string];
+};
+/**
+ * CSS classes for button group elements
+ * Following BEM naming convention
+ */
+export declare const BUTTON_GROUP_CLASSES: {
+    /** Container element */
+    readonly ROOT: "button-group";
+    /** Individual button within group */
+    readonly BUTTON: "button-group__button";
+    /** First button in group */
+    readonly FIRST: "button-group__button--first";
+    /** Last button in group */
+    readonly LAST: "button-group__button--last";
+    /** Middle buttons (neither first nor last) */
+    readonly MIDDLE: "button-group__button--middle";
+    /** Single button (only one in group) */
+    readonly SINGLE: "button-group__button--single";
+    /** Disabled state */
+    readonly DISABLED: "button-group--disabled";
+    /** Horizontal orientation */
+    readonly HORIZONTAL: "button-group--horizontal";
+    /** Vertical orientation */
+    readonly VERTICAL: "button-group--vertical";
+    /** Equal width buttons */
+    readonly EQUAL_WIDTH: "button-group--equal-width";
+    /** Filled variant */
+    readonly FILLED: "button-group--filled";
+    /** Tonal variant */
+    readonly TONAL: "button-group--tonal";
+    /** Outlined variant */
+    readonly OUTLINED: "button-group--outlined";
+    /** Elevated variant */
+    readonly ELEVATED: "button-group--elevated";
+    /** Text variant */
+    readonly TEXT: "button-group--text";
+    /** Default density */
+    readonly DENSITY_DEFAULT: "button-group--density-default";
+    /** Comfortable density */
+    readonly DENSITY_COMFORTABLE: "button-group--density-comfortable";
+    /** Compact density */
+    readonly DENSITY_COMPACT: "button-group--density-compact";
+};
+/**
+ * Density-specific height values per MD3 specifications
+ */
+export declare const BUTTON_GROUP_HEIGHTS: {
+    readonly default: 40;
+    readonly comfortable: 36;
+    readonly compact: 32;
+};
+/**
+ * Border radius values per MD3 specifications
+ * Button groups use full-rounded corners on outer edges
+ */
+export declare const BUTTON_GROUP_RADII: {
+    readonly default: 20;
+    readonly comfortable: 18;
+    readonly compact: 16;
+};

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

@@ -0,0 +1,13 @@
+/**
+ * Button Group component exports
+ *
+ * The Button Group component provides a container for grouping related action buttons.
+ * Unlike Segmented Buttons (used for selection), Button Groups are for grouping
+ * related actions where each button triggers an independent action.
+ *
+ * @packageDocumentation
+ */
+export { default as createButtonGroup } from './button-group';
+export { default } from './button-group';
+export type { ButtonGroupConfig, ButtonGroupComponent, ButtonGroupItemConfig, ButtonGroupEvent, ButtonGroupEventType, ButtonGroupVariant, ButtonGroupOrientation, ButtonGroupDensity } from './types';
+export { BUTTON_GROUP_VARIANTS, BUTTON_GROUP_ORIENTATIONS, BUTTON_GROUP_DENSITY, BUTTON_GROUP_EVENTS, BUTTON_GROUP_DEFAULTS, BUTTON_GROUP_CLASSES, BUTTON_GROUP_HEIGHTS, BUTTON_GROUP_RADII } from './constants';

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

@@ -0,0 +1,244 @@
+import type { ButtonConfig, ButtonComponent } from "../button/types";
+/**
+ * Button group orientation
+ * @category Components
+ */
+export type ButtonGroupOrientation = "horizontal" | "vertical";
+/**
+ * Button group variant - applies to all buttons in the group
+ * @category Components
+ */
+export type ButtonGroupVariant = "filled" | "tonal" | "outlined" | "elevated" | "text";
+/**
+ * Button group density options
+ * Controls the overall sizing and spacing of buttons in the group
+ * @category Components
+ */
+export type ButtonGroupDensity = "default" | "comfortable" | "compact";
+/**
+ * Event types for button group
+ */
+export type ButtonGroupEventType = "click" | "focus" | "blur";
+/**
+ * Event data for button group events
+ */
+export interface ButtonGroupEvent {
+    /** The button group component that contains the clicked button */
+    buttonGroup: ButtonGroupComponent;
+    /** The button component that was clicked */
+    button: ButtonComponent;
+    /** Index of the button in the group */
+    index: number;
+    /** Original DOM event */
+    originalEvent: Event;
+}
+/**
+ * Configuration for a single button within a button group
+ * Extends ButtonConfig but omits properties controlled by the group
+ * @category Components
+ */
+export interface ButtonGroupItemConfig extends Omit<ButtonConfig, "variant"> {
+    /**
+     * Unique identifier for the button
+     * If not provided, index will be used
+     */
+    id?: string;
+    /**
+     * Button text content
+     * @example 'Bold'
+     */
+    text?: string;
+    /**
+     * Button icon HTML content
+     * @example '<svg>...</svg>'
+     */
+    icon?: string;
+    /**
+     * Accessible label (required for icon-only buttons)
+     * @example 'Toggle bold'
+     */
+    ariaLabel?: string;
+    /**
+     * Whether this button is disabled
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Value associated with this button
+     */
+    value?: string;
+    /**
+     * Additional CSS class for this button
+     */
+    class?: string;
+}
+/**
+ * Configuration interface for the Button Group component
+ * @category Components
+ */
+export interface ButtonGroupConfig {
+    /**
+     * Array of button configurations
+     */
+    buttons?: ButtonGroupItemConfig[];
+    /**
+     * Visual variant applied to all buttons in the group
+     * @default 'outlined'
+     */
+    variant?: ButtonGroupVariant;
+    /**
+     * Orientation of the button group
+     * @default 'horizontal'
+     */
+    orientation?: ButtonGroupOrientation;
+    /**
+     * Density setting that controls button sizing
+     * @default 'default'
+     */
+    density?: ButtonGroupDensity;
+    /**
+     * Whether the entire button group is disabled
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Whether buttons should have equal width
+     * @default false
+     */
+    equalWidth?: boolean;
+    /**
+     * Component prefix for class names
+     * @default 'mtrl'
+     */
+    prefix?: string;
+    /**
+     * Component name used in class generation
+     */
+    componentName?: string;
+    /**
+     * Additional CSS class for the button group container
+     */
+    class?: string;
+    /**
+     * Whether to enable ripple effect on buttons
+     * @default true
+     */
+    ripple?: boolean;
+    /**
+     * 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 label for the button group
+     * @example 'Text formatting options'
+     */
+    ariaLabel?: string;
+    /**
+     * Event handlers for button group events
+     */
+    on?: {
+        [key in ButtonGroupEventType]?: (event: ButtonGroupEvent) => void;
+    };
+}
+/**
+ * Button Group component interface
+ * @category Components
+ */
+export interface ButtonGroupComponent {
+    /** The component's container DOM element */
+    element: HTMLElement;
+    /** Array of button component instances */
+    buttons: ButtonComponent[];
+    /**
+     * Gets a button by its index
+     * @param index - Button index
+     * @returns The button component or undefined
+     */
+    getButton: (index: number) => ButtonComponent | undefined;
+    /**
+     * Gets a button by its id or value
+     * @param id - Button id or value
+     * @returns The button component or undefined
+     */
+    getButtonById: (id: string) => ButtonComponent | undefined;
+    /**
+     * Gets the current variant
+     * @returns Current variant name
+     */
+    getVariant: () => ButtonGroupVariant;
+    /**
+     * Sets the variant for all buttons in the group
+     * @param variant - New variant to apply
+     * @returns The ButtonGroupComponent for chaining
+     */
+    setVariant: (variant: ButtonGroupVariant) => ButtonGroupComponent;
+    /**
+     * Gets the current orientation
+     * @returns Current orientation
+     */
+    getOrientation: () => ButtonGroupOrientation;
+    /**
+     * Sets the orientation of the button group
+     * @param orientation - New orientation
+     * @returns The ButtonGroupComponent for chaining
+     */
+    setOrientation: (orientation: ButtonGroupOrientation) => ButtonGroupComponent;
+    /**
+     * Gets the current density
+     * @returns Current density
+     */
+    getDensity: () => ButtonGroupDensity;
+    /**
+     * Sets the density of the button group
+     * @param density - New density level
+     * @returns The ButtonGroupComponent for chaining
+     */
+    setDensity: (density: ButtonGroupDensity) => ButtonGroupComponent;
+    /**
+     * Enables the entire button group
+     * @returns The ButtonGroupComponent for chaining
+     */
+    enable: () => ButtonGroupComponent;
+    /**
+     * Disables the entire button group
+     * @returns The ButtonGroupComponent for chaining
+     */
+    disable: () => ButtonGroupComponent;
+    /**
+     * Enables a specific button by index
+     * @param index - Button index
+     * @returns The ButtonGroupComponent for chaining
+     */
+    enableButton: (index: number) => ButtonGroupComponent;
+    /**
+     * Disables a specific button by index
+     * @param index - Button index
+     * @returns The ButtonGroupComponent for chaining
+     */
+    disableButton: (index: number) => ButtonGroupComponent;
+    /**
+     * Adds an event listener to the button group
+     * @param event - Event name
+     * @param handler - Event handler function
+     * @returns The ButtonGroupComponent for chaining
+     */
+    on: (event: ButtonGroupEventType, handler: (event: ButtonGroupEvent) => void) => ButtonGroupComponent;
+    /**
+     * Removes an event listener from the button group
+     * @param event - Event name
+     * @param handler - Event handler function
+     * @returns The ButtonGroupComponent for chaining
+     */
+    off: (event: ButtonGroupEventType, handler: (event: ButtonGroupEvent) => void) => ButtonGroupComponent;
+    /**
+     * Destroys the component and cleans up resources
+     */
+    destroy: () => void;
+}

package/dist/components/index.d.ts

@@ -11,12 +11,15 @@
 export { LIST_DEFAULTS, LIST_TYPES, LIST_SELECTION_MODES, LIST_EVENTS, LIST_SCROLL_POSITIONS, LIST_CLASSES, } from "./list/constants";
 export type { ListConfig, ListComponent, SelectEvent as ListSelectEvent, // Rename to avoid collision
 LoadEvent, } from "./list/types";
+export { BUTTON_GROUP_VARIANTS, BUTTON_GROUP_ORIENTATIONS, BUTTON_GROUP_DENSITY, BUTTON_GROUP_EVENTS, BUTTON_GROUP_DEFAULTS, BUTTON_GROUP_CLASSES, BUTTON_GROUP_HEIGHTS, BUTTON_GROUP_RADII, } from "./button-group/constants";
+export type { ButtonGroupConfig, ButtonGroupComponent, ButtonGroupItemConfig, ButtonGroupEvent, ButtonGroupEventType, ButtonGroupVariant, ButtonGroupOrientation, ButtonGroupDensity, } from "./button-group/types";
 export { SELECT_VARIANTS, SELECT_PLACEMENT, SELECT_INTERACTION, SELECT_EVENTS, SELECT_ICONS, SELECT_DEFAULTS, SELECT_CLASSES, } from "./select/constants";
 export type { SelectConfig, SelectComponent, SelectOption, SelectEvent, // Keep the original name since select is more commonly used
 SelectChangeEvent, } from "./select/types";
 export * from "./badge";
 export * from "./bottom-app-bar";
 export * from "./button";
+export * from "./button-group";
 export * from "./card";
 export * from "./carousel";
 export * from "./checkbox";
@@ -48,6 +51,7 @@ export { createCardContent, createCardHeader, createCardActions, createCardMedia
 export { default as createBadge } from "./badge";
 export { default as createBottomAppBar } from "./bottom-app-bar";
 export { default as createButton } from "./button";
+export { default as createButtonGroup } from "./button-group";
 export { default as createCard } from "./card";
 export { default as createCarousel } from "./carousel";
 export { default as createCheckbox } from "./checkbox";

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

@@ -175,6 +175,12 @@ export interface MenuConfig {
      * @default false
      */
     visible?: boolean;
+    /**
+     * Container element to append the menu to
+     * If not provided, menu will be appended to document.body
+     * Use this when the menu needs to stay within a specific container (e.g., inside a dialog)
+     */
+    container?: HTMLElement | null;
     /**
      * Additional CSS classes to add to the menu
      */

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

@@ -42,13 +42,16 @@ export declare const SEGMENTED_BUTTON_DEFAULTS: {
     /** Default ripple opacity values [start, end] */
     readonly RIPPLE_OPACITY: readonly ["0.2", "0"];
 };
-export declare const DEFAULT_CHECKMARK_ICON = "\n<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"18\" height=\"18\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\">\n  <polyline points=\"20 6 9 17 4 12\"></polyline>\n</svg>";
 /**
- * Default checkmark icon for selected segments
+ * Default checkmark icon for selected segments (MD3 filled style)
+ */
+export declare const DEFAULT_CHECKMARK_ICON = "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"18\" height=\"18\" viewBox=\"0 0 24 24\" fill=\"currentColor\"><path d=\"M9 16.17L4.83 12l-1.42 1.41L9 19 21 7l-1.41-1.41z\"/></svg>";
+/**
+ * Segmented button icons
  */
 export declare const SEGMENTED_BUTTON_ICONS: {
-    /** Default checkmark icon */
-    readonly CHECKMARK: "<svg xmlns=\"http://www.w3.org/2000/svg\" height=\"24\" viewBox=\"0 0 24 24\" width=\"24\"><path d=\"M0 0h24v24H0z\" fill=\"none\"/><path d=\"M9 16.17L4.83 12l-1.42 1.41L9 19 21 7l-1.41-1.41z\"/></svg>";
+    /** Default checkmark icon (filled) */
+    readonly CHECKMARK: "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"18\" height=\"18\" viewBox=\"0 0 24 24\" fill=\"currentColor\"><path d=\"M9 16.17L4.83 12l-1.42 1.41L9 19 21 7l-1.41-1.41z\"/></svg>";
 };
 /**
  * CSS classes for segmented button elements

package/dist/components/segmented-button/segment.d.ts

@@ -1,6 +1,12 @@
-import { SegmentConfig, Segment } from './types';
+import { SegmentConfig, Segment } from "./types";
 /**
  * Creates a segment for the segmented button using the button component
+ *
+ * Per MD3 specifications:
+ * - Text-only segments: Show checkmark BEFORE text when selected
+ * - Icon + text segments: Replace icon with checkmark when selected
+ * - Icon-only segments: Do NOT show checkmark (icon remains unchanged)
+ *
  * @param {SegmentConfig} config - Segment configuration
  * @param {HTMLElement} container - Container element
  * @param {string} prefix - Component prefix