material 1.0.4 → 3.0.0-next.1

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

@@ -0,0 +1,607 @@
+import type { TouchEvents } from "../../core/utils/mobile.js";
+import type { IconManager } from "../../core/compose/features/icon.js";
+import type { ForwardedEventPayload } from "../../core/dom/create.js";
+/**
+ * FAB variants following Material Design 3 guidelines
+ *
+ * Material Design 3 offers different color variants for the 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 FabVariant = "primary-container" | "secondary-container" | "tertiary-container" | "primary" | "secondary" | "tertiary";
+/**
+ * FAB size variants
+ *
+ * Material Design 3 defines multiple size options for FABs to accommodate
+ * different use cases and screen sizes.
+ *
+ * @category Components
+ * @remarks
+ * - default: 56px diameter, for standard primary actions (default)
+ * - medium: 80px container, 28px icon
+ * - large: 96px container, 32px icon
+ */
+export type FabSize = "default" | "medium" | "large";
+/**
+ * FAB position options
+ *
+ * Predefined positions for the 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 FabPosition = "top-right" | "top-left" | "bottom-right" | "bottom-left";
+/**
+ * Configuration interface for the FAB component
+ *
+ * Comprehensive options for creating and customizing a Floating Action Button
+ * according to Material Design 3 guidelines.
+ *
+ * @category Components
+ * @see https://m3.material.io/components/floating-action-button/overview
+ */
+export interface FabConfig {
+    /**
+     * FAB variant that determines visual styling
+     *
+     * The color variant affects the FAB's background color, icon color, and elevation.
+     *
+     * @default 'primary-container'
+     *
+     * @example
+     * ```typescript
+     * // Create a tertiary FAB
+     * createFab({ variant: 'tertiary', icon: '<svg>...</svg>' })
+     * ```
+     */
+    variant?: FabVariant | string;
+    /**
+     * FAB size variant
+     *
+     * Controls the diameter of the FAB and the appropriate icon size.
+     *
+     * @default 'default'
+     *
+     * @example
+     * ```typescript
+     * // Create a medium FAB
+     * createFab({ size: 'medium', icon: '<svg>...</svg>' })
+     *
+     * // Create a large FAB for emphasis
+     * createFab({ size: 'large', icon: '<svg>...</svg>' })
+     * ```
+     */
+    size?: FabSize | string;
+    /**
+     * Whether the FAB is initially disabled
+     *
+     * When disabled, the FAB will have a visually muted appearance
+     * and won't respond to user interactions.
+     *
+     * @default false
+     *
+     * @example
+     * ```typescript
+     * // Create a disabled FAB
+     * const fab = createFab({
+     *   icon: '<svg>...</svg>',
+     *   disabled: true
+     * });
+     *
+     * // Later enable it when content is ready
+     * loadContent().then(() => {
+     *   fab.enable();
+     * });
+     * ```
+     */
+    disabled?: boolean;
+    /**
+     * 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 follow Material Design sizing guidelines
+     * (24x24dp for most sizes, scaled appropriately for small or large variants).
+     *
+     * @example
+     * ```typescript
+     * // Using an SVG icon
+     * createFab({
+     *   icon: '<svg viewBox="0 0 24 24"><path d="M19 13h-6v6h-2v-6H5v-2h6V5h2v6h6v2z"/></svg>'
+     * });
+     *
+     * // Using a Material Icons ligature
+     * createFab({
+     *   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 size for the selected FAB size.
+     *
+     * @example
+     * ```typescript
+     * // Create a FAB with a larger icon
+     * createFab({
+     *   icon: '<svg>...</svg>',
+     *   iconSize: '32px'
+     * });
+     * ```
+     */
+    iconSize?: string;
+    /**
+     * Additional CSS classes to add to the FAB
+     *
+     * Custom classes for styling or identifying the FAB.
+     * These classes will be applied in addition to the component's built-in classes.
+     *
+     * @example
+     * ```typescript
+     * createFab({
+     *   icon: '<svg>...</svg>',
+     *   class: 'home-fab pulse-animation'
+     * });
+     * ```
+     */
+    class?: string;
+    /**
+     * Button value attribute
+     *
+     * Sets the HTML value attribute of the button element, useful when using
+     * the FAB in a form context.
+     *
+     * @example
+     * ```typescript
+     * createFab({
+     *   icon: '<svg>...</svg>',
+     *   type: 'submit',
+     *   value: 'form-submitted'
+     * });
+     * ```
+     */
+    value?: string;
+    /**
+     * Position of the FAB on the screen
+     *
+     * Configures the FAB for floating positioning on the screen.
+     * Applies appropriate CSS classes to position the FAB in one of the corners.
+     *
+     * @example
+     * ```typescript
+     * // Position in the bottom-right corner (common for primary actions)
+     * createFab({
+     *   icon: '<svg>...</svg>',
+     *   position: 'bottom-right'
+     * });
+     *
+     * // Position in the top-left corner
+     * createFab({
+     *   icon: '<svg>...</svg>',
+     *   position: 'top-left'
+     * });
+     * ```
+     */
+    position?: FabPosition | string;
+    /**
+     * Button type attribute
+     *
+     * Sets the HTML type attribute of the button element.
+     *
+     * @default 'button'
+     *
+     * @example
+     * ```typescript
+     * // Use as a form submit button
+     * createFab({
+     *   icon: '<svg>...</svg>',
+     *   type: 'submit'
+     * });
+     * ```
+     */
+    type?: "button" | "submit" | "reset";
+    /**
+     * Accessible label for screen readers
+     *
+     * Sets the aria-label attribute for accessibility. Required for FABs since
+     * they typically contain only an icon without visible text.
+     *
+     * @example
+     * ```typescript
+     * createFab({
+     *   icon: '<svg>...</svg>',
+     *   ariaLabel: 'Add new item'
+     * });
+     * ```
+     */
+    /**
+     * Accessible name. Required: an icon-only control has no text for a screen
+     * reader to announce, so without this it is just "button" (WCAG 4.1.2).
+     * FLO-110.
+     */
+    ariaLabel: string;
+    /**
+     * Whether to enable ripple effect
+     *
+     * The ripple effect provides visual feedback when the user interacts
+     * with the FAB. Follows Material Design interaction patterns.
+     *
+     * @default true
+     *
+     * @example
+     * ```typescript
+     * // Disable the ripple effect
+     * createFab({
+     *   icon: '<svg>...</svg>',
+     *   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
+     * createFab({
+     *   icon: '<svg>...</svg>',
+     *   prefix: 'app'
+     * });
+     * // Results in classes like: 'app-fab app-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
+     * createFab({
+     *   icon: '<svg>...</svg>',
+     *   rippleConfig: {
+     *     duration: 400
+     *   }
+     * });
+     * ```
+     */
+    rippleConfig?: {
+        /** How long, in milliseconds, a released wave lingers before it is removed */
+        duration?: number;
+    };
+    /**
+     * Whether to show the FAB with an entrance animation
+     *
+     * When true, the FAB will animate into view when added to the DOM.
+     *
+     * @default false
+     *
+     * @example
+     * ```typescript
+     * // Create an animated entrance FAB
+     * createFab({
+     *   icon: '<svg>...</svg>',
+     *   animate: true
+     * });
+     * ```
+     */
+    animate?: boolean;
+    /**
+     * Index signature for additional configuration options
+     * Required for compatibility with core feature interfaces
+     */
+    [key: string]: unknown;
+}
+/**
+ * FAB component interface
+ *
+ * Provides methods for interacting with and manipulating a Floating Action Button.
+ *
+ * @category Components
+ */
+/**
+ * The events a FAB reports, and what each hands its handler.
+ *
+ * Exactly the three its `forwardEvents` config forwards -- `click`, `focus`
+ * and `blur`, see config.ts. `mount` and `unmount` are deliberately absent:
+ * the lifecycle feature keeps its own emitter and exposes them as
+ * `lifecycle.onMount` / `onUnmount`, so they never arrive through `on`.
+ *
+ * `on` and `off` are generic over these keys, so a misspelled event name is a
+ * compile error rather than a listener that never fires, and the handler's
+ * payload is typed rather than `Function`'s implicit `any`. FLO-114.
+ */
+export interface FabEvents extends TouchEvents {
+    /** The FAB was clicked. Not forwarded while the FAB is disabled. */
+    click: (payload: ForwardedEventPayload<MouseEvent, HTMLButtonElement>) => void;
+    /** The FAB took focus. */
+    focus: (payload: ForwardedEventPayload<FocusEvent, HTMLButtonElement>) => void;
+    /** The FAB lost focus. */
+    blur: (payload: ForwardedEventPayload<FocusEvent, HTMLButtonElement>) => void;
+}
+export interface FabComponent {
+    /**
+     * The FAB's DOM element
+     *
+     * Direct access to the underlying button element for DOM manipulation.
+     */
+    element: HTMLButtonElement;
+    /**
+     * API for managing 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 disabled state
+     *
+     * Access to low-level disabled state methods.
+     */
+    disabled: {
+        /** Enables the FAB */
+        enable: () => void;
+        /** Disables the FAB */
+        disable: () => void;
+        /** Checks if the 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 = createFab({ icon: '<svg>...</svg>' });
+     * const className = fab.getClass('icon'); // Returns 'mtrl-fab__icon'
+     * ```
+     */
+    getClass: (name: string) => string;
+    /**
+     * Gets the FAB's value attribute
+     *
+     * @returns FAB value
+     *
+     * @example
+     * ```typescript
+     * const fab = createFab({
+     *   icon: '<svg>...</svg>',
+     *   value: 'action-button'
+     * });
+     * const value = fab.getValue(); // Returns 'action-button'
+     * ```
+     */
+    getValue: () => string;
+    /**
+     * Sets the FAB's value attribute
+     *
+     * @param value - New value
+     * @returns The FAB component for chaining
+     *
+     * @example
+     * ```typescript
+     * const fab = createFab({ icon: '<svg>...</svg>' });
+     * fab.setValue('complete');
+     * ```
+     */
+    setValue: (value: string) => FabComponent;
+    /**
+     * Enables the FAB (removes disabled attribute)
+     *
+     * Makes the FAB interactive and visually enabled.
+     *
+     * @returns The FAB component for chaining
+     *
+     * @example
+     * ```typescript
+     * // Enable a previously disabled FAB
+     * fab.enable();
+     * ```
+     */
+    enable: () => FabComponent;
+    /**
+     * Disables the FAB (adds disabled attribute)
+     *
+     * Makes the FAB non-interactive and visually disabled.
+     *
+     * @returns The FAB component for chaining
+     *
+     * @example
+     * ```typescript
+     * // Disable the FAB during an async operation
+     * fab.disable();
+     * await saveData();
+     * fab.enable();
+     * ```
+     */
+    disable: () => FabComponent;
+    /** Whether the FAB is disabled (FLO-384) */
+    isDisabled: () => boolean;
+    /**
+     * Sets the FAB's icon
+     *
+     * @param icon - Icon HTML content
+     * @returns The 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) => FabComponent;
+    /**
+     * Gets the FAB's icon HTML content
+     *
+     * @returns Icon HTML
+     *
+     * @example
+     * ```typescript
+     * const iconHtml = fab.getIcon();
+     * ```
+     */
+    getIcon: () => string;
+    /**
+     * Sets the FAB's position
+     *
+     * Positions the FAB in one of the four corners of the viewport.
+     *
+     * @param position - Position value ('top-right', 'bottom-left', etc.)
+     * @returns The FAB component for chaining
+     *
+     * @example
+     * ```typescript
+     * // Move the FAB to the bottom-left corner
+     * fab.setPosition('bottom-left');
+     * ```
+     */
+    setPosition: (position: string) => FabComponent;
+    /**
+     * Gets the current position of the 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 FAB (useful for pressed state)
+     *
+     * Visually lowers the FAB by reducing its elevation,
+     * typically used to indicate a pressed or active state.
+     *
+     * @returns The FAB component for chaining
+     *
+     * @example
+     * ```typescript
+     * // Visually lower the FAB when a long operation starts
+     * fab.lower();
+     * await longOperation();
+     * fab.raise();
+     * ```
+     */
+    lower: () => FabComponent;
+    /**
+     * Raises the FAB back to its default elevation
+     *
+     * Restores the default elevation after it has been lowered.
+     *
+     * @returns The FAB component for chaining
+     *
+     * @example
+     * ```typescript
+     * // Restore normal elevation
+     * fab.raise();
+     * ```
+     */
+    raise: () => FabComponent;
+    /**
+     * Destroys the FAB component and cleans up resources
+     *
+     * Removes event listeners and prepares the component for garbage collection.
+     * Call this method when the 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 FAB
+     *
+     * @param event - Event name ('click', 'focus', etc.)
+     * @param handler - Event handler function
+     * @returns The FAB component for chaining
+     *
+     * @example
+     * ```typescript
+     * // Add click handler
+     * fab.on('click', () => {
+     *   console.log('FAB clicked');
+     * });
+     * ```
+     */
+    on: <K extends keyof FabEvents>(event: K, handler: FabEvents[K]) => FabComponent;
+    /**
+     * Removes an event listener from the FAB
+     *
+     * @param event - Event name
+     * @param handler - Event handler function
+     * @returns The 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 FabEvents>(event: K, handler: FabEvents[K]) => FabComponent;
+    /**
+     * Adds CSS classes to the FAB element
+     *
+     * @param classes - One or more class names to add
+     * @returns The FAB component for chaining
+     *
+     * @example
+     * ```typescript
+     * // Add multiple classes
+     * fab.addClass('highlight', 'pulse-animation');
+     * ```
+     */
+    addClass: (...classes: string[]) => FabComponent;
+}

package/dist/components/fab/types.js

@@ -0,0 +1 @@
+export {};

package/dist/components/fab-menu/config.d.ts

@@ -0,0 +1,11 @@
+import type { FabMenuConfig } from "./types.js";
+import { type FabMenuColor, type FabMenuSize, type FabMenuPresentation, type FabMenuPlacement } from "./constants.js";
+/** Material "close", the close button's default icon (drawn at 20dp) */
+export declare const CLOSE_ICON = "<svg viewBox=\"0 0 24 24\" aria-hidden=\"true\"><path d=\"M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z\"/></svg>";
+export interface ResolvedFabMenuConfig extends FabMenuConfig {
+    color: FabMenuColor;
+    size: FabMenuSize;
+    presentation: FabMenuPresentation;
+    placement: FabMenuPlacement;
+}
+export declare const createConfig: (config: FabMenuConfig) => ResolvedFabMenuConfig;

package/dist/components/fab-menu/config.js

@@ -0,0 +1,15 @@
+import { createComponentConfig } from "../../core/config/component.js";
+import { FAB_MENU_COLORS, FAB_MENU_SIZES, FAB_MENU_PRESENTATIONS, FAB_MENU_PLACEMENTS, } from "./constants.js";
+export const CLOSE_ICON = '<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"/></svg>';
+const oneOf = (values, value, fallback) => Object.values(values).includes(value) ? value : fallback;
+export const createConfig = (config) => {
+    const merged = createComponentConfig({}, config, "fab-menu");
+    return {
+        ...merged,
+        items: merged.items ?? [],
+        color: oneOf(FAB_MENU_COLORS, merged.color, FAB_MENU_COLORS.PRIMARY),
+        size: oneOf(FAB_MENU_SIZES, merged.size, FAB_MENU_SIZES.DEFAULT),
+        presentation: oneOf(FAB_MENU_PRESENTATIONS, merged.presentation, FAB_MENU_PRESENTATIONS.AUTO),
+        placement: oneOf(FAB_MENU_PLACEMENTS, merged.placement, FAB_MENU_PLACEMENTS.NONE),
+    };
+};

package/dist/components/fab-menu/constants.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Colour sets (m3.material.io FAB menu specs): the close button takes the
+ * role, the items its container role. Match the FAB's colour style.
+ */
+export declare const FAB_MENU_COLORS: {
+    readonly PRIMARY: "primary";
+    readonly SECONDARY: "secondary";
+    readonly TERTIARY: "tertiary";
+};
+export type FabMenuColor = (typeof FAB_MENU_COLORS)[keyof typeof FAB_MENU_COLORS];
+/** The FAB sizes a menu opens from: not small, not extended. */
+export declare const FAB_MENU_SIZES: {
+    readonly DEFAULT: "default";
+    readonly MEDIUM: "medium";
+    readonly LARGE: "large";
+};
+export type FabMenuSize = (typeof FAB_MENU_SIZES)[keyof typeof FAB_MENU_SIZES];
+/**
+ * How the menu presents its items:
+ * - list: M3 Expressive's list of pill items above the FAB, which turns into
+ *   a close button (compact windows)
+ * - menu: the baseline menu, opened from the FAB (the site's rule on the web,
+ *   larger windows)
+ * - auto: list below 600px, menu from 600px
+ */
+export declare const FAB_MENU_PRESENTATIONS: {
+    readonly AUTO: "auto";
+    readonly LIST: "list";
+    readonly MENU: "menu";
+};
+export type FabMenuPresentation = (typeof FAB_MENU_PRESENTATIONS)[keyof typeof FAB_MENU_PRESENTATIONS];
+/** Where the menu sits in its positioned container, or in the flow. */
+export declare const FAB_MENU_PLACEMENTS: {
+    readonly NONE: "none";
+    readonly BOTTOM_END: "bottom-end";
+    readonly BOTTOM_START: "bottom-start";
+};
+export type FabMenuPlacement = (typeof FAB_MENU_PLACEMENTS)[keyof typeof FAB_MENU_PLACEMENTS];
+/** The window width, in px, from which `auto` presents the baseline menu (medium windows). */
+export declare const FAB_MENU_MENU_FROM = 600;
+/** The spec's item count: a menu of 2 to 6 related actions. */
+export declare const FAB_MENU_ITEMS: {
+    readonly MIN: 2;
+    readonly MAX: 6;
+};
+/** The space between the list and the close button (FabMenuBaselineTokens.CloseButtonBetweenSpace). */
+export declare const FAB_MENU_LIST_GAP = 8;
+/** The gap between the FAB and a baseline menu (m3.material.io FAB menu specs, web). */
+export declare const FAB_MENU_MENU_GAP = 4;
+/**
+ * How long the items take to leave after the last one starts: FastSpatial,
+ * the longest of an item's transitions.
+ */
+export declare const FAB_MENU_ITEM_EXIT = 425;
+export declare const FAB_MENU_EVENTS: {
+    readonly OPEN: "open";
+    readonly CLOSE: "close";
+    readonly SELECT: "select";
+};