material 3.2.6 → 3.3.0

package/dist/components/extended-fab/types.d.ts

@@ -2,733 +2,81 @@ import type { TouchEvents } from "../../core/utils/mobile.js";
 import type { IconManager } from "../../core/compose/features/icon.js";
 import type { TextManager } from "../../core/compose/features/text.js";
 import type { ForwardedEventPayload } from "../../core/dom/index.js";
-/**
- * Extended FAB variants following Material Design 3 guidelines
- *
- * Material Design 3 offers different color variants for the Extended FAB
- * to match visual hierarchy and application color schemes.
- *
- * @category Components
- * @remarks
- * - primary-container, secondary-container, tertiary-container: container styles
- * - primary, secondary, tertiary: tone styles
- * - surface: deprecated; use a container or tone style instead
- * Default: primary-container.
- */
 export type ExtendedFabVariant = "primary-container" | "secondary-container" | "tertiary-container" | "primary" | "secondary" | "tertiary";
-/**
- * Expressive extended FAB size: small 56dp, medium 80dp, large 96dp.
- * @category Components
- */
 export type ExtendedFabSize = "small" | "medium" | "large";
-/**
- * Extended FAB width behavior
- *
- * Controls how the Extended FAB's width is calculated.
- *
- * @category Components
- * @remarks
- * - fixed: Maintains a constant width regardless of content (default)
- * - fluid: Adjusts width based on content length
- */
 export type ExtendedFabWidth = "fixed" | "fluid";
-/**
- * Extended FAB position on the screen
- *
- * Predefined positions for the Extended FAB when used as a floating element.
- * These positions automatically apply appropriate margins and positioning.
- *
- * @category Components
- * @remarks
- * Common patterns:
- * - bottom-right: Most common position for primary actions
- * - bottom-left: Alternative position on left-to-right interfaces
- * - top-right: Used for actions related to top content
- * - top-left: Less common but available for special layouts
- */
 export type ExtendedFabPosition = "top-right" | "top-left" | "bottom-right" | "bottom-left";
-/**
- * Configuration interface for the Extended FAB component
- *
- * Comprehensive options for creating and customizing an Extended Floating Action Button
- * according to Material Design 3 guidelines.
- *
- * @category Components
- * @see https://m3.material.io/components/extended-fab/overview
- */
+export type ExtendedFabPlacement = "none" | "top-start" | "top-end" | "bottom-start" | "bottom-end";
 export interface ExtendedFabConfig {
-    /** Expressive container, icon and label size. @default 'small' */
     size?: ExtendedFabSize;
-    /**
-     * Extended FAB variant that determines visual styling
-     *
-     * The color variant affects the Extended FAB's background color, text color, and elevation.
-     *
-     * @default 'primary-container'
-     *
-     * @example
-     * ```typescript
-     * // Create a tertiary Extended FAB
-     * createExtendedFab({ variant: 'tertiary', text: 'Archive' })
-     * ```
-     */
     variant?: ExtendedFabVariant | string;
-    /**
-     * Whether the Extended FAB is initially disabled
-     *
-     * When disabled, the Extended FAB will have a visually muted appearance
-     * and won't respond to user interactions.
-     *
-     * @default false
-     *
-     * @example
-     * ```typescript
-     * // Create a disabled Extended FAB
-     * const fab = createExtendedFab({ text: 'Submit', disabled: true });
-     *
-     * // Later enable it when form is valid
-     * validateForm().then(isValid => {
-     *   if (isValid) fab.enable();
-     * });
-     * ```
-     */
     disabled?: boolean;
-    /**
-     * Extended FAB icon HTML content.
-     * Markup (HTML). Not sanitized by default: see Markup and sanitizing.
-     *
-     * The icon content can be any valid HTML, but typically contains an SVG icon
-     * or a Material Icons ligature. Icons should be 24x24dp following Material guidelines.
-     *
-     * @example
-     * ```typescript
-     * // Using an SVG icon
-     * createExtendedFab({
-     *   text: 'Add',
-     *   icon: '<svg width="24" height="24" viewBox="0 0 24 24"><path d="M19 13h-6v6h-2v-6H5v-2h6V5h2v6h6v2z"/></svg>'
-     * });
-     *
-     * // Using a Material Icons ligature
-     * createExtendedFab({
-     *   text: 'Add',
-     *   icon: '<span class="material-icons">add</span>'
-     * });
-     * ```
-     */
     icon?: string;
-    /**
-     * Icon size in pixels or other CSS units
-     *
-     * Allows customizing the icon size beyond the default 24px size.
-     *
-     * @example
-     * ```typescript
-     * // Create an Extended FAB with larger icon
-     * createExtendedFab({
-     *   text: 'Edit',
-     *   icon: '<svg>...</svg>',
-     *   iconSize: '32px'
-     * });
-     * ```
-     */
     iconSize?: string;
-    /**
-     * Position of the icon relative to the text
-     *
-     * Controls whether the icon appears before or after the text label.
-     * Material Design 3 guidelines typically recommend the icon at the start position.
-     *
-     * @default 'start'
-     *
-     * @example
-     * ```typescript
-     * // Create an Extended FAB with icon after text
-     * createExtendedFab({
-     *   text: 'Next',
-     *   icon: '<span class="material-icons">arrow_forward</span>',
-     *   iconPosition: 'end'
-     * });
-     * ```
-     */
     iconPosition?: "start" | "end";
-    /**
-     * Text label for the Extended FAB
-     *
-     * The text should be short, typically one or two words describing the primary action.
-     * Material Design guidelines recommend action verbs that clearly describe the action.
-     *
-     * @example
-     * ```typescript
-     * // Good text labels for Extended FABs
-     * createExtendedFab({ text: 'Create' });
-     * createExtendedFab({ text: 'Add Task' });
-     * createExtendedFab({ text: 'Submit' });
-     * ```
-     */
     text?: string;
-    /**
-     * Additional CSS classes to add to the Extended FAB
-     *
-     * Custom classes for styling or identifying the Extended FAB.
-     * These classes will be applied in addition to the component's built-in classes.
-     *
-     * @example
-     * ```typescript
-     * createExtendedFab({
-     *   text: 'Create',
-     *   class: 'home-page-fab custom-shadow'
-     * });
-     * ```
-     */
     class?: string;
-    /**
-     * Button value attribute
-     *
-     * Sets the HTML value attribute of the button element, useful when using
-     * the Extended FAB in a form context.
-     *
-     * @example
-     * ```typescript
-     * createExtendedFab({
-     *   text: 'Submit',
-     *   type: 'submit',
-     *   value: 'form-submitted'
-     * });
-     * ```
-     */
     value?: string;
-    /**
-     * Position of the Extended FAB on the screen
-     *
-     * Configures the Extended FAB for floating positioning on the screen.
-     * Applies appropriate CSS classes to position the Extended FAB in one of the corners.
-     *
-     * @example
-     * ```typescript
-     * // Position in the bottom-right corner (common for primary actions)
-     * createExtendedFab({
-     *   text: 'Create',
-     *   position: 'bottom-right'
-     * });
-     *
-     * // Position in the top-left corner
-     * createExtendedFab({
-     *   text: 'Go back',
-     *   position: 'top-left'
-     * });
-     * ```
-     */
     position?: ExtendedFabPosition | string;
-    /**
-     * Button type attribute
-     *
-     * Sets the HTML type attribute of the button element.
-     *
-     * @default 'button'
-     *
-     * @example
-     * ```typescript
-     * // Use as a form submit button
-     * createExtendedFab({
-     *   text: 'Submit',
-     *   type: 'submit'
-     * });
-     * ```
-     */
+    placement?: ExtendedFabPlacement;
     type?: "button" | "submit" | "reset";
-    /**
-     * Accessible label for screen readers
-     *
-     * Sets the aria-label attribute. The visible text already names the
-     * Extended FAB, so set this only when the name should differ from it or
-     * there is no text. Nothing is derived from `text` or `icon` (#232).
-     *
-     * @example
-     * ```typescript
-     * createExtendedFab({
-     *   text: 'Create',
-     *   icon: '<svg>...</svg>',
-     *   ariaLabel: 'Create new document'
-     * });
-     * ```
-     */
     ariaLabel?: string;
-    /**
-     * Whether to enable ripple effect
-     *
-     * The ripple effect provides visual feedback when the user interacts
-     * with the Extended FAB. Follows Material Design interaction patterns.
-     *
-     * @default true
-     *
-     * @example
-     * ```typescript
-     * // Disable the ripple effect
-     * createExtendedFab({
-     *   text: 'Create',
-     *   ripple: false
-     * });
-     * ```
-     */
     ripple?: boolean;
-    /**
-     * Component prefix for class names
-     *
-     * The prefix used for BEM-style class names.
-     *
-     * @default 'mtrl'
-     *
-     * @example
-     * ```typescript
-     * // Use a custom prefix for class names
-     * createExtendedFab({
-     *   text: 'Create',
-     *   prefix: 'app'
-     * });
-     * // Results in classes like: 'app-extended-fab app-extended-fab--primary'
-     * ```
-     */
     prefix?: string;
-    /**
-     * Component name used in class generation
-     *
-     * @internal
-     */
     componentName?: string;
-    /**
-     * Ripple effect configuration
-     *
-     * Fine-grained control over the ripple effect appearance and behavior.
-     *
-     * @example
-     * ```typescript
-     * // Customize ripple effect
-     * createExtendedFab({
-     *   text: 'Create',
-     *   rippleConfig: {
-     *     duration: 400
-     *   }
-     * });
-     * ```
-     */
     rippleConfig?: {
-        /** How long, in milliseconds, a released wave lingers before it is removed */
         duration?: number;
     };
-    /**
-     * Whether to show the Extended FAB with an entrance animation
-     *
-     * When true, the Extended FAB will animate into view when added to the DOM.
-     *
-     * @default false
-     *
-     * @example
-     * ```typescript
-     * // Create an animated entrance Extended FAB
-     * createExtendedFab({
-     *   text: 'Create',
-     *   animate: true
-     * });
-     * ```
-     */
     animate?: boolean;
-    /**
-     * Width behavior of the Extended FAB
-     *
-     * Controls how the Extended FAB's width is calculated:
-     * - 'fixed': Maintains a constant width regardless of content (default)
-     * - 'fluid': Adjusts width based on content length
-     *
-     * @default 'fixed'
-     *
-     * @example
-     * ```typescript
-     * // Create an Extended FAB that adjusts width based on text length
-     * createExtendedFab({
-     *   text: 'Add to favorites',
-     *   width: 'fluid'
-     * });
-     * ```
-     */
     width?: ExtendedFabWidth | string;
-    /**
-     * Whether the Extended FAB should collapse to a standard FAB on scroll
-     *
-     * When true, the Extended FAB will automatically shrink to a circular FAB
-     * (hiding the text) when the user scrolls down, and expand back to the Extended FAB
-     * when scrolling up.
-     *
-     * @default false
-     *
-     * @example
-     * ```typescript
-     * // Create a collapsible Extended FAB
-     * createExtendedFab({
-     *   text: 'Create',
-     *   icon: '<svg>...</svg>',
-     *   collapseOnScroll: true
-     * });
-     * ```
-     */
     collapseOnScroll?: boolean;
-    /**
-     * Index signature for additional configuration options
-     * Required for compatibility with core feature interfaces
-     */
     [key: string]: unknown;
 }
-/**
- * Native events forwarded through the Extended FAB's emitter.
- * Collapse and expand are DOM-only events; listen on `element` for those.
- * Lifecycle callbacks are registered through the lifecycle API.
- */
 export interface ExtendedFabEvents extends TouchEvents {
-    /** Clicks are not forwarded while the button is disabled. */
     click: (payload: ForwardedEventPayload<MouseEvent, HTMLButtonElement>) => void;
-    /** The button took focus. */
     focus: (payload: ForwardedEventPayload<FocusEvent, HTMLButtonElement>) => void;
-    /** The button lost focus. */
     blur: (payload: ForwardedEventPayload<FocusEvent, HTMLButtonElement>) => void;
-    /** `collapse()` ran, by call or on scroll */
     collapse: () => void;
-    /** `expand()` ran, by call or on scroll */
     expand: () => void;
 }
-/**
- * Extended FAB component interface
- *
- * Provides methods for interacting with and manipulating an Extended Floating Action Button.
- *
- * @category Components
- */
 export interface ExtendedFabComponent {
-    /**
-     * The Extended FAB's DOM element
-     *
-     * Direct access to the underlying button element for DOM manipulation.
-     */
     element: HTMLButtonElement;
-    /**
-     * API for managing Extended FAB icons
-     *
-     * Access to low-level icon methods and elements.
-     */
     icon: {
-        /** Sets the icon HTML content */
         setIcon: (html: string) => IconManager;
-        /** Gets the current icon HTML content */
         getIcon: () => string;
-        /** Gets the icon DOM element */
         getElement: () => HTMLElement | null;
     };
-    /**
-     * API for managing text content
-     *
-     * Access to low-level text methods and elements.
-     */
     text: {
-        /** Sets the text content */
         setText: (text: string) => TextManager;
-        /** Gets the current text content */
         getText: () => string;
-        /** Gets the text DOM element */
         getElement: () => HTMLElement | null;
     };
-    /**
-     * API for managing disabled state
-     *
-     * Access to low-level disabled state methods.
-     */
     disabled: {
-        /** Enables the Extended FAB */
         enable: () => void;
-        /** Disables the Extended FAB */
         disable: () => void;
-        /** Checks if the Extended FAB is disabled */
         isDisabled: () => boolean;
     };
-    /**
-     * API for managing component lifecycle
-     *
-     * Access to low-level lifecycle methods.
-     */
     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
-     *
-     * @example
-     * ```typescript
-     * const fab = createExtendedFab({ text: 'Create' });
-     * const className = fab.getClass('icon'); // Returns 'mtrl-extended-fab__icon'
-     * ```
-     */
     getClass: (name: string) => string;
-    /**
-     * Gets the Extended FAB's value attribute
-     *
-     * @returns Extended FAB value
-     *
-     * @example
-     * ```typescript
-     * const fab = createExtendedFab({ text: 'Submit', value: 'form-data' });
-     * const value = fab.getValue(); // Returns 'form-data'
-     * ```
-     */
     getValue: () => string;
-    /**
-     * Sets the Extended FAB's value attribute
-     *
-     * @param value - New value
-     * @returns The Extended FAB component for chaining
-     *
-     * @example
-     * ```typescript
-     * const fab = createExtendedFab({ text: 'Submit' });
-     * fab.setValue('completed');
-     * ```
-     */
     setValue: (value: string) => ExtendedFabComponent;
-    /**
-     * Enables the Extended FAB (removes disabled attribute)
-     *
-     * Makes the Extended FAB interactive and visually enabled.
-     *
-     * @returns The Extended FAB component for chaining
-     *
-     * @example
-     * ```typescript
-     * // Enable a previously disabled Extended FAB
-     * fab.enable();
-     * ```
-     */
     enable: () => ExtendedFabComponent;
-    /**
-     * Disables the Extended FAB (adds disabled attribute)
-     *
-     * Makes the Extended FAB non-interactive and visually disabled.
-     *
-     * @returns The Extended FAB component for chaining
-     *
-     * @example
-     * ```typescript
-     * // Disable the Extended FAB during an async operation
-     * fab.disable();
-     * await saveData();
-     * fab.enable();
-     * ```
-     */
     disable: () => ExtendedFabComponent;
-    /** Whether the extended FAB is disabled */
     isDisabled: () => boolean;
-    /**
-     * Sets the Extended FAB's icon
-     *
-     * @param icon - Icon HTML content
-     * @returns The Extended FAB component for chaining
-     *
-     * @example
-     * ```typescript
-     * // Change the icon dynamically
-     * fab.setIcon('<svg>...</svg>');
-     *
-     * // Change to a Material Icons ligature
-     * fab.setIcon('<span class="material-icons">edit</span>');
-     * ```
-     */
     setIcon: (icon: string) => ExtendedFabComponent;
-    /**
-     * Gets the Extended FAB's icon HTML content
-     *
-     * @returns Icon HTML
-     *
-     * @example
-     * ```typescript
-     * const iconHtml = fab.getIcon();
-     * ```
-     */
     getIcon: () => string;
-    /**
-     * Sets the Extended FAB's text content
-     *
-     * @param text - Text content
-     * @returns The Extended FAB component for chaining
-     *
-     * @example
-     * ```typescript
-     * // Change text dynamically based on state
-     * if (isEditing) {
-     *   fab.setText('Save');
-     * } else {
-     *   fab.setText('Edit');
-     * }
-     * ```
-     */
     setText: (text: string) => ExtendedFabComponent;
-    /**
-     * Gets the Extended FAB's text content
-     *
-     * @returns Text content
-     *
-     * @example
-     * ```typescript
-     * const currentText = fab.getText();
-     * ```
-     */
     getText: () => string;
-    /**
-     * Sets the Extended FAB's position
-     *
-     * Positions the Extended FAB in one of the four corners of the viewport.
-     *
-     * @param position - Position value ('top-right', 'bottom-left', etc.)
-     * @returns The Extended FAB component for chaining
-     *
-     * @example
-     * ```typescript
-     * // Move the Extended FAB to the bottom-left corner
-     * fab.setPosition('bottom-left');
-     * ```
-     */
     setPosition: (position: string) => ExtendedFabComponent;
-    /**
-     * Gets the current position of the Extended FAB
-     *
-     * @returns Current position or null if not positioned
-     *
-     * @example
-     * ```typescript
-     * const position = fab.getPosition(); // Returns 'bottom-right', 'top-left', etc.
-     * ```
-     */
     getPosition: () => string | null;
-    /**
-     * Lowers the Extended FAB (useful for pressed state)
-     *
-     * Visually lowers the Extended FAB by reducing its elevation,
-     * typically used to indicate a pressed or active state.
-     *
-     * @returns The Extended FAB component for chaining
-     *
-     * @example
-     * ```typescript
-     * // Visually lower the Extended FAB when a long operation starts
-     * fab.lower();
-     * await longOperation();
-     * fab.raise();
-     * ```
-     */
     lower: () => ExtendedFabComponent;
-    /**
-     * Raises the Extended FAB back to its default elevation
-     *
-     * Restores the default elevation after it has been lowered.
-     *
-     * @returns The Extended FAB component for chaining
-     *
-     * @example
-     * ```typescript
-     * // Restore normal elevation
-     * fab.raise();
-     * ```
-     */
     raise: () => ExtendedFabComponent;
-    /**
-     * Collapses the Extended FAB into a standard FAB
-     *
-     * Hides the text label, showing only the icon in a circular container.
-     * Useful for saving space or to emphasize other content.
-     *
-     * @returns The Extended FAB component for chaining
-     *
-     * @example
-     * ```typescript
-     * // Collapse the Extended FAB programmatically
-     * fab.collapse();
-     * ```
-     */
     collapse: () => ExtendedFabComponent;
-    /**
-     * Expands a collapsed Extended FAB back to its full size
-     *
-     * Shows the text label alongside the icon.
-     *
-     * @returns The Extended FAB component for chaining
-     *
-     * @example
-     * ```typescript
-     * // Expand the Extended FAB programmatically
-     * fab.expand();
-     * ```
-     */
     expand: () => ExtendedFabComponent;
-    /**
-     * Destroys the Extended FAB component and cleans up resources
-     *
-     * Removes event listeners and prepares the component for garbage collection.
-     * Call this method when the Extended FAB is no longer needed.
-     *
-     * @example
-     * ```typescript
-     * // Clean up when the component is no longer needed
-     * fab.destroy();
-     * ```
-     */
     destroy: () => void;
-    /**
-     * Adds an event listener to the Extended FAB
-     *
-     * @param event - Forwarded event name: 'click', 'focus', or 'blur'
-     * @param handler - Receives the native event and the button root in a payload
-     * @returns The Extended FAB component for chaining
-     *
-     * @example
-     * ```typescript
-     * // Add click handler
-     * fab.on('click', () => {
-     *   console.log('Extended FAB clicked');
-     * });
-     *
-     * // Collapse and expand reach both the emitter and the DOM element
-     * fab.on('collapse', () => {
-     *   console.log('Extended FAB collapsed');
-     * });
-     * ```
-     */
     on: <K extends keyof ExtendedFabEvents>(event: K, handler: ExtendedFabEvents[K]) => ExtendedFabComponent;
-    /**
-     * Removes an event listener from the Extended FAB
-     *
-     * @param event - Event name
-     * @param handler - Event handler function
-     * @returns The Extended FAB component for chaining
-     *
-     * @example
-     * ```typescript
-     * // Remove a previously added event handler
-     * const handler = () => console.log('Clicked');
-     * fab.on('click', handler);
-     * // Later...
-     * fab.off('click', handler);
-     * ```
-     */
     off: <K extends keyof ExtendedFabEvents>(event: K, handler: ExtendedFabEvents[K]) => ExtendedFabComponent;
-    /**
-     * Adds CSS classes to the Extended FAB element
-     *
-     * @param classes - One or more class names to add
-     * @returns The Extended FAB component for chaining
-     *
-     * @example
-     * ```typescript
-     * // Add multiple classes
-     * fab.addClass('highlight', 'pulse-animation');
-     * ```
-     */
     addClass: (...classes: string[]) => ExtendedFabComponent;
 }