material 1.0.4 → 3.0.0-next.0

package/dist/components/search/features/suggestions.js

@@ -0,0 +1,238 @@
+import { SEARCH_CLASSES, SEARCH_KEYS, SEARCH_ICONS } from "../constants.js";
+import { createElement } from "../../../core/dom/create.js";
+export const withSuggestions = () => (component) => {
+    let highlightedIndex = -1;
+    const currentSuggestions = [];
+    const getClass = (className) => {
+        return component.getClass ? component.getClass(className) : className;
+    };
+    const getSuggestions = () => {
+        if (component.input?.getSuggestions) {
+            return component.input.getSuggestions();
+        }
+        return currentSuggestions;
+    };
+    const highlightMatch = (text, query) => {
+        if (!query)
+            return [document.createTextNode(text)];
+        const matchIndex = text.toLowerCase().indexOf(query.toLowerCase());
+        if (matchIndex === -1)
+            return [document.createTextNode(text)];
+        const strong = document.createElement("strong");
+        strong.textContent = text.slice(matchIndex, matchIndex + query.length);
+        return [
+            document.createTextNode(text.slice(0, matchIndex)),
+            strong,
+            document.createTextNode(text.slice(matchIndex + query.length)),
+        ];
+    };
+    const createSuggestionItem = (suggestion, index, query) => {
+        const isHighlighted = index === highlightedIndex;
+        const itemClasses = [getClass(SEARCH_CLASSES.SUGGESTION_ITEM)];
+        if (isHighlighted) {
+            itemClasses.push(getClass(SEARCH_CLASSES.SUGGESTION_ITEM_SELECTED));
+        }
+        const listId = component.structure?.suggestionsList?.id;
+        const item = createElement({
+            tag: "li",
+            className: itemClasses.join(" "),
+            attributes: {
+                ...(listId && { id: `${listId}-${index}` }),
+                role: "option",
+                "aria-selected": isHighlighted ? "true" : "false",
+                "data-index": String(index),
+                "data-value": suggestion.value ?? suggestion.text,
+                tabindex: "-1",
+            },
+        });
+        if (suggestion.icon) {
+            createElement({
+                tag: "span",
+                className: getClass(SEARCH_CLASSES.SUGGESTION_ICON),
+                container: item,
+                html: suggestion.icon,
+            });
+        }
+        else {
+            createElement({
+                tag: "span",
+                className: getClass(SEARCH_CLASSES.SUGGESTION_ICON),
+                container: item,
+                html: SEARCH_ICONS.HISTORY,
+            });
+        }
+        const label = createElement({
+            tag: "span",
+            className: getClass(SEARCH_CLASSES.SUGGESTION_TEXT),
+            container: item,
+        });
+        label.append(...highlightMatch(suggestion.text, query));
+        if (suggestion.supportingText) {
+            item.classList.add(getClass(`${SEARCH_CLASSES.SUGGESTION_ITEM}--two-line`));
+            const supporting = createElement({ tag: "span", className: getClass(SEARCH_CLASSES.SUGGESTION_SUPPORTING), container: label });
+            supporting.textContent = suggestion.supportingText;
+        }
+        return item;
+    };
+    const createDivider = () => {
+        return createElement({
+            tag: "li",
+            className: getClass(SEARCH_CLASSES.SUGGESTION_DIVIDER),
+            attributes: {
+                role: "separator",
+                "aria-hidden": "true",
+            },
+        });
+    };
+    const renderSuggestions = () => {
+        const suggestionsList = component.structure?.suggestionsList;
+        if (!suggestionsList)
+            return;
+        const suggestions = getSuggestions();
+        const query = component.input?.getValue?.() || "";
+        suggestionsList.replaceChildren();
+        highlightedIndex = -1;
+        component.structure?.input.removeAttribute("aria-activedescendant");
+        const status = component.structure?.status;
+        const count = suggestions.length;
+        if (status)
+            status.textContent = count && component.states?.isExpanded() ? `${count} suggestion${count === 1 ? "" : "s"}` : "";
+        if (suggestions.length === 0) {
+            return;
+        }
+        let currentGroup;
+        suggestions.forEach((suggestion, index) => {
+            if (suggestion.group && suggestion.group !== currentGroup) {
+                if (currentGroup !== undefined) {
+                    suggestionsList.appendChild(createDivider());
+                }
+                currentGroup = suggestion.group;
+            }
+            const item = createSuggestionItem(suggestion, index, query);
+            item.addEventListener("click", (e) => {
+                e.preventDefault();
+                e.stopPropagation();
+                selectSuggestion(index);
+            });
+            suggestionsList.appendChild(item);
+        });
+    };
+    const clearRenderedSuggestions = () => {
+        const suggestionsList = component.structure?.suggestionsList;
+        if (suggestionsList) {
+            suggestionsList.replaceChildren();
+        }
+        highlightedIndex = -1;
+        component.structure?.input.removeAttribute("aria-activedescendant");
+        if (component.structure?.status)
+            component.structure.status.textContent = "";
+    };
+    const setHighlightedIndex = (index) => {
+        const suggestionsList = component.structure?.suggestionsList;
+        if (!suggestionsList)
+            return;
+        const suggestions = getSuggestions();
+        if (index < -1)
+            index = suggestions.length - 1;
+        if (index >= suggestions.length)
+            index = -1;
+        if (highlightedIndex >= 0) {
+            const previousItem = suggestionsList.querySelector(`[data-index="${highlightedIndex}"]`);
+            if (previousItem) {
+                previousItem.classList.remove(getClass(SEARCH_CLASSES.SUGGESTION_ITEM_SELECTED));
+                previousItem.setAttribute("aria-selected", "false");
+            }
+        }
+        highlightedIndex = index;
+        const input = component.structure?.input;
+        const newItem = highlightedIndex >= 0 ? suggestionsList.querySelector(`[data-index="${highlightedIndex}"]`) : null;
+        if (newItem?.id)
+            input?.setAttribute("aria-activedescendant", newItem.id);
+        else
+            input?.removeAttribute("aria-activedescendant");
+        if (highlightedIndex >= 0) {
+            if (newItem) {
+                newItem.classList.add(getClass(SEARCH_CLASSES.SUGGESTION_ITEM_SELECTED));
+                newItem.setAttribute("aria-selected", "true");
+                newItem.scrollIntoView({ block: "nearest" });
+            }
+        }
+    };
+    const highlightNext = () => {
+        setHighlightedIndex(highlightedIndex + 1);
+    };
+    const highlightPrevious = () => {
+        setHighlightedIndex(highlightedIndex - 1);
+    };
+    const selectSuggestion = (index) => {
+        const suggestions = getSuggestions();
+        if (index < 0 || index >= suggestions.length)
+            return;
+        const suggestion = suggestions[index];
+        if (component.input?.selectSuggestion) {
+            component.input.selectSuggestion(suggestion);
+        }
+        if (component.states?.collapse) {
+            component.states.collapse();
+        }
+    };
+    const selectHighlighted = () => {
+        if (highlightedIndex >= 0) {
+            selectSuggestion(highlightedIndex);
+            return true;
+        }
+        return false;
+    };
+    const setupKeyboardNavigation = () => {
+        const input = component.structure?.input;
+        if (!input)
+            return;
+        input.addEventListener("keydown", (e) => {
+            const suggestions = getSuggestions();
+            const isExpanded = component.states?.isExpanded?.() || false;
+            if (!isExpanded || suggestions.length === 0)
+                return;
+            switch (e.key) {
+                case SEARCH_KEYS.ARROW_DOWN:
+                    e.preventDefault();
+                    highlightNext();
+                    break;
+                case SEARCH_KEYS.ARROW_UP:
+                    e.preventDefault();
+                    highlightPrevious();
+                    break;
+                case SEARCH_KEYS.ENTER:
+                    if (highlightedIndex >= 0) {
+                        e.preventDefault();
+                        selectHighlighted();
+                    }
+                    break;
+                case SEARCH_KEYS.TAB:
+                    if (highlightedIndex >= 0) {
+                        selectHighlighted();
+                    }
+                    break;
+                case SEARCH_KEYS.ESCAPE:
+                    highlightedIndex = -1;
+                    break;
+            }
+        });
+    };
+    if (getSuggestions().length > 0)
+        renderSuggestions();
+    setTimeout(setupKeyboardNavigation, 0);
+    component.on?.("expand", () => renderSuggestions());
+    return {
+        ...component,
+        suggestions: {
+            render: renderSuggestions,
+            clear: clearRenderedSuggestions,
+            setHighlightedIndex,
+            getHighlightedIndex: () => highlightedIndex,
+            highlightNext,
+            highlightPrevious,
+            select: selectSuggestion,
+            selectHighlighted,
+        },
+    };
+};

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

@@ -0,0 +1,2 @@
+export { default } from "./search.js";
+export type { SearchConfig, SearchComponent, SearchEvent, SearchEvents, SearchStateEvent, SearchState, SearchViewMode, SearchVariant, SearchEventType, SearchSuggestion, SearchTrailingItem, } from "./types.js";

package/dist/components/search/index.js

@@ -0,0 +1 @@
+export { default } from "./search.js";

package/dist/components/search/search.d.ts

@@ -0,0 +1,35 @@
+import { SearchConfig, SearchComponent } from "./types.js";
+/**
+ * Creates a new Search component following Material Design 3 specifications
+ *
+ * The Search component provides:
+ * - Search Bar: Collapsed state with pill shape (56dp height)
+ * - Search View: Expanded state with suggestions (docked or fullscreen)
+ *
+ * @example
+ * ```ts
+ * // Basic search bar
+ * const search = createSearch({
+ *   placeholder: 'Search products...',
+ *   onSubmit: (event) => console.log('Search:', event.value)
+ * });
+ *
+ * // Search with suggestions
+ * const search = createSearch({
+ *   placeholder: 'Search...',
+ *   suggestions: ['Apple', 'Banana', 'Cherry'],
+ *   onSuggestionSelect: (event) => console.log('Selected:', event.suggestion)
+ * });
+ *
+ * // Fullscreen search view (mobile)
+ * const search = createSearch({
+ *   viewMode: 'fullscreen',
+ *   expandOnFocus: true
+ * });
+ * ```
+ *
+ * @param config Search configuration object
+ * @returns Search component instance
+ */
+declare const createSearch: (config?: SearchConfig) => SearchComponent;
+export default createSearch;

package/dist/components/search/search.js

@@ -0,0 +1,39 @@
+import { pipe } from "../../core/compose/pipe.js";
+import { createBase, withElement } from "../../core/compose/component.js";
+import { withEvents, withLifecycle } from "../../core/compose/features/index.js";
+import { withStructure, withStates, withInput, withSuggestions, } from "./features/index.js";
+import { withAPI } from "./api.js";
+import { createBaseConfig, getElementConfig, getApiConfig } from "./config.js";
+const createSearch = (config = {}) => {
+    const baseConfig = createBaseConfig(config);
+    try {
+        const component = pipe(createBase, withEvents(), withElement(getElementConfig(baseConfig)), withStructure(baseConfig), withStates(baseConfig, () => search), withInput(baseConfig, () => search), withSuggestions(), withLifecycle())(baseConfig);
+        const apiOptions = getApiConfig(component);
+        const search = withAPI(apiOptions)(component);
+        if (baseConfig.onInput)
+            search.on("input", baseConfig.onInput);
+        if (baseConfig.onSubmit)
+            search.on("submit", baseConfig.onSubmit);
+        if (baseConfig.onClear)
+            search.on("clear", baseConfig.onClear);
+        if (baseConfig.onSuggestionSelect)
+            search.on("suggestionSelect", baseConfig.onSuggestionSelect);
+        if (baseConfig.onExpand)
+            search.on("expand", baseConfig.onExpand);
+        if (baseConfig.onCollapse)
+            search.on("collapse", baseConfig.onCollapse);
+        if (baseConfig.on && typeof search.on === "function") {
+            Object.entries(baseConfig.on).forEach(([event, handler]) => {
+                if (typeof handler === "function") {
+                    search.on(event, handler);
+                }
+            });
+        }
+        return search;
+    }
+    catch (error) {
+        console.error("Search creation error:", error);
+        throw new Error(`Failed to create search: ${error.message}`);
+    }
+};
+export default createSearch;

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

@@ -0,0 +1,284 @@
+/**
+ * Search component state
+ * - 'bar': Collapsed search bar (default)
+ * - 'view': Expanded search view with suggestions
+ */
+export type SearchState = "bar" | "view";
+/**
+ * Search view display mode
+ * - 'docked': Inline expanded view (360-720dp width, max 2/3 screen height)
+ * - 'fullscreen': Full-screen overlay (mobile-first)
+ */
+export type SearchViewMode = "docked" | "fullscreen";
+/**
+ * Search variant, M3's style (FLO-287)
+ * - 'contained': M3 Expressive. The bar keeps its pill and filled container
+ *   when focused, and the results sit in their own container
+ * - 'divided': the baseline. The bar squares off and a divider separates the
+ *   results
+ */
+export type SearchVariant = "contained" | "divided";
+/**
+ * Valid event types for search component per MD3 spec: the names in {@link SearchEvents}
+ */
+export type SearchEventType = keyof SearchEvents;
+/**
+ * Trailing content item configuration
+ */
+export interface SearchTrailingItem {
+    /** Unique identifier for the item */
+    id: string;
+    /**
+     * HTML content (icon SVG or avatar image).
+     * Markup (HTML). Not sanitized by default: see Markup and sanitizing.
+     * An avatar is not a person's name or an image URL.
+     */
+    content: string;
+    /** Type of trailing content */
+    type: "icon" | "avatar";
+    /** Accessible label for the item */
+    ariaLabel?: string;
+    /** Click handler */
+    onClick?: (event: MouseEvent) => void;
+}
+/**
+ * Search suggestion item
+ */
+export interface SearchSuggestion {
+    /** Display text */
+    text: string;
+    /** Value to use when selected (defaults to text) */
+    value?: string;
+    /** Optional leading icon HTML. Markup (HTML). Not sanitized by default: see Markup and sanitizing. */
+    icon?: string;
+    /** A second line under the text: a two-line list item (FLO-291) */
+    supportingText?: string;
+    /** Optional group identifier for dividers */
+    group?: string;
+}
+/**
+ * Search event data
+ */
+export interface SearchEvent {
+    /** The search component instance */
+    component: SearchComponent;
+    /** Current search value */
+    value: string;
+    /** Original DOM event if available */
+    originalEvent: Event | null;
+    /** Selected suggestion (for suggestionSelect event) */
+    suggestion?: SearchSuggestion;
+    /** Prevents default behavior */
+    preventDefault: () => void;
+    /** Whether default was prevented */
+    defaultPrevented: boolean;
+}
+/**
+ * What `expand` and `collapse` carry: the search after the change. Not a
+ * {@link SearchEvent}: there is no value, no DOM event and nothing to prevent.
+ */
+export interface SearchStateEvent {
+    /** The search component instance */
+    component: SearchComponent;
+    /** The state after the change: `view` on expand, `bar` on collapse */
+    state: SearchState;
+    /** The view mode the search has */
+    viewMode: SearchViewMode;
+}
+/**
+ * The search's events and what each hands its listener. A config `on*` option
+ * is the same listener, registered at creation.
+ */
+export interface SearchEvents {
+    focus: (event: SearchEvent) => void;
+    blur: (event: SearchEvent) => void;
+    input: (event: SearchEvent) => void;
+    submit: (event: SearchEvent) => void;
+    clear: (event: SearchEvent) => void;
+    suggestionSelect: (event: SearchEvent) => void;
+    expand: (event: SearchStateEvent) => void;
+    collapse: (event: SearchStateEvent) => void;
+}
+/**
+ * Configuration options for the Search component
+ * Aligned with Material Design 3 specifications
+ */
+export interface SearchConfig {
+    /** Initial state: 'bar' (collapsed) or 'view' (expanded). Default: 'bar' */
+    initialState?: SearchState;
+    /** View mode when expanded: 'docked' or 'fullscreen'. Default: 'docked' */
+    viewMode?: SearchViewMode;
+    /** 'contained' (M3 Expressive) or 'divided' (baseline). Default: 'contained' */
+    variant?: SearchVariant;
+    /** Whether the search component is disabled */
+    disabled?: boolean;
+    /** Placeholder/supporting text. Default: 'Search' */
+    placeholder?: string;
+    /** Initial input value */
+    value?: string;
+    /**
+     * Form field name. Set on the text input itself, so the search takes part
+     * in a surrounding form and its value appears in `FormData`. Without it the
+     * search submits nothing.
+     */
+    name?: string;
+    /** Custom leading icon HTML (replaces default search icon). Markup (HTML). Not sanitized by default: see Markup and sanitizing. */
+    leadingIcon?: string;
+    /** Trailing content items (icons, avatar) */
+    trailingItems?: SearchTrailingItem[];
+    /** Suggestions to display in view mode */
+    suggestions?: SearchSuggestion[] | string[];
+    /** Show clear button when input has value. Default: true */
+    showClearButton?: boolean;
+    /** Auto-expand to view on focus. Default: true */
+    expandOnFocus?: boolean;
+    /** Auto-collapse on blur (with delay). Default: true */
+    collapseOnBlur?: boolean;
+    /** Collapse delay in ms when collapseOnBlur is true. Default: 150 */
+    collapseDelay?: number;
+    /** Minimum width in pixels. Default: 360 */
+    minWidth?: number;
+    /** Maximum width in pixels. Default: 720 */
+    maxWidth?: number;
+    /** Full width mode (ignores min/max width) */
+    fullWidth?: boolean;
+    /** Additional CSS classes */
+    class?: string;
+    /** Component prefix for class names */
+    prefix?: string;
+    /** `submit` listener registered at creation. */
+    onSubmit?: SearchEvents["submit"];
+    /** `input` listener registered at creation. */
+    onInput?: SearchEvents["input"];
+    /** `clear` listener registered at creation. */
+    onClear?: SearchEvents["clear"];
+    /** `expand` listener registered at creation. */
+    onExpand?: SearchEvents["expand"];
+    /** `collapse` listener registered at creation. */
+    onCollapse?: SearchEvents["collapse"];
+    /** `suggestionSelect` listener registered at creation. */
+    onSuggestionSelect?: SearchEvents["suggestionSelect"];
+    /** Event handlers map */
+    on?: Partial<SearchEvents>;
+}
+/**
+ * Search component public API interface
+ * Aligned with Material Design 3 specifications
+ */
+export interface SearchComponent {
+    /** The root element of the search component */
+    element: HTMLElement;
+    /** Sets the search input value. Silent unless `triggerEvent` is true (FLO-328). */
+    setValue: (value: string, triggerEvent?: boolean) => SearchComponent;
+    /** Gets the current search input value */
+    getValue: () => string;
+    /** Sets the placeholder/supporting text */
+    setPlaceholder: (text: string) => SearchComponent;
+    /** Gets the current placeholder text */
+    getPlaceholder: () => string;
+    /** Expands to search view */
+    expand: () => SearchComponent;
+    /** Collapses to search bar */
+    collapse: () => SearchComponent;
+    /** Gets the current state ('bar' or 'view') */
+    getState: () => SearchState;
+    /** Checks if currently expanded */
+    isExpanded: () => boolean;
+    /** Sets the view mode ('docked' or 'fullscreen') */
+    setViewMode: (mode: SearchViewMode) => SearchComponent;
+    /** Gets the current view mode */
+    getViewMode: () => SearchViewMode;
+    /** Sets the variant ('contained' or 'divided') */
+    setVariant: (variant: SearchVariant) => SearchComponent;
+    /** Gets the current variant */
+    getVariant: () => SearchVariant;
+    /** Focuses the search input */
+    focus: () => SearchComponent;
+    /** Blurs the search input */
+    blur: () => SearchComponent;
+    /** Clears the search input. Silent: only the clear button emits `input` and `clear`. */
+    clear: () => SearchComponent;
+    /** Submits the current search value */
+    submit: () => SearchComponent;
+    /** Sets the leading icon HTML */
+    setLeadingIcon: (iconHtml: string) => SearchComponent;
+    /** Adds a trailing item */
+    addTrailingItem: (item: SearchTrailingItem) => SearchComponent;
+    /** Removes a trailing item by id */
+    removeTrailingItem: (id: string) => SearchComponent;
+    /** Sets all trailing items */
+    setTrailingItems: (items: SearchTrailingItem[]) => SearchComponent;
+    /** Sets the suggestions list */
+    setSuggestions: (suggestions: SearchSuggestion[] | string[]) => SearchComponent;
+    /** Gets the current suggestions */
+    getSuggestions: () => SearchSuggestion[];
+    /** Clears all suggestions */
+    clearSuggestions: () => SearchComponent;
+    /** Enables the search component */
+    enable: () => SearchComponent;
+    /** Disables the search component */
+    disable: () => SearchComponent;
+    /** Checks if the component is disabled */
+    isDisabled: () => boolean;
+    /** Adds an event listener */
+    on: <K extends keyof SearchEvents>(event: K, handler: SearchEvents[K]) => SearchComponent;
+    /** Removes an event listener */
+    off: <K extends keyof SearchEvents>(event: K, handler: SearchEvents[K]) => SearchComponent;
+    /** Destroys the component and cleans up resources */
+    destroy: () => void;
+}
+/**
+ * Internal component structure references
+ * @internal
+ */
+export interface SearchStructure {
+    /**
+     * The bar and, when expanded, its results: what shows in the top layer while
+     * the view is open (FLO-285)
+     */
+    surface: HTMLElement;
+    /** Main container element */
+    container: HTMLElement;
+    /** Input element */
+    input: HTMLInputElement;
+    /** Input wrapper element */
+    inputWrapper: HTMLElement;
+    /** Leading icon container */
+    leadingIcon: HTMLElement;
+    /** Clear button element */
+    clearButton: HTMLElement | null;
+    /** Trailing items container */
+    trailingContainer: HTMLElement | null;
+    /** Header divider (view mode) */
+    divider: HTMLElement | null;
+    /** Suggestions container (view mode) */
+    suggestionsContainer: HTMLElement | null;
+    /** Suggestions list element */
+    suggestionsList: HTMLElement | null;
+    /** The live region that announces the suggestion count (FLO-286) */
+    status: HTMLElement;
+}
+/**
+ * Internal search state
+ * @internal
+ */
+export interface SearchInternalState {
+    /** Current component state */
+    state: SearchState;
+    /** Current view mode */
+    viewMode: SearchViewMode;
+    /** Current input value */
+    value: string;
+    /** Current placeholder */
+    placeholder: string;
+    /** Whether input is focused */
+    isFocused: boolean;
+    /** Whether component is disabled */
+    isDisabled: boolean;
+    /** Current suggestions */
+    suggestions: SearchSuggestion[];
+    /** Currently highlighted suggestion index (-1 = none) */
+    highlightedIndex: number;
+    /** Trailing items */
+    trailingItems: SearchTrailingItem[];
+}

package/dist/components/search/types.js

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

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

@@ -0,0 +1,8 @@
+import { SelectComponent, ApiOptions, BaseComponent } from "./types.js";
+/**
+ * Enhances a select component with API methods
+ * @param options - API configuration options
+ * @returns Higher-order function that adds API methods to component
+ * @internal
+ */
+export declare const withAPI: (options: ApiOptions) => (component: BaseComponent) => SelectComponent;