@bug-on/md3-react 2.0.1 → 2.0.3

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

@@ -0,0 +1,31 @@
+/**
+ * @file bottom-app-bar.tsx
+ * MD3 Expressive Bottom App Bar.
+ *
+ * Fixed to bottom of screen. Contains action icons and optional FAB.
+ * Height: 80px | Background: surface-container | Elevation: Level2 (always)
+ *
+ * @see docs/m3/app-bars/BottomAppBarTokens.kt
+ */
+import type { BottomAppBarProps } from "./app-bar.types";
+/**
+ * MD3 Expressive Bottom App Bar.
+ *
+ * @example
+ * ```tsx
+ * // With FAB
+ * <BottomAppBar
+ *   actions={
+ *     <>
+ *       <IconButton aria-label="Check"><Icon>check_box</Icon></IconButton>
+ *       <IconButton aria-label="Brush"><Icon>brush</Icon></IconButton>
+ *     </>
+ *   }
+ *   floatingActionButton={<FAB aria-label="Compose">...</FAB>}
+ * />
+ *
+ * // Auto-hide on scroll
+ * <BottomAppBar scrollBehavior="hidden" actions={...} />
+ * ```
+ */
+export declare function BottomAppBar({ actions, floatingActionButton, scrollBehavior, scrollElement, className, }: BottomAppBarProps): import("react/jsx-runtime").JSX.Element;

package/dist/ui/app-bar/docked-toolbar.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @file docked-toolbar.tsx
+ * MD3 Expressive Docked Toolbar.
+ *
+ * Secondary navigation component. NOT an App Bar.
+ * Usually appears directly below the main App Bar.
+ * Height: 64px | Background: surface-container
+ * Typical content: chips, segmented buttons, filter actions.
+ *
+ * @see docs/m3/app-bars/DockedToolbarTokens.kt
+ */
+import type { DockedToolbarProps } from "./app-bar.types";
+/**
+ * MD3 Expressive Docked Toolbar.
+ *
+ * @example
+ * ```tsx
+ * <DockedToolbar aria-label="Filter options">
+ *   <Chip label="All" selected onClick={() => setFilter('all')} />
+ *   <Chip label="Unread" onClick={() => setFilter('unread')} />
+ *   <Chip label="Starred" onClick={() => setFilter('starred')} />
+ * </DockedToolbar>
+ * ```
+ */
+export declare function DockedToolbar({ children, "aria-label": ariaLabel, className, }: DockedToolbarProps): import("react/jsx-runtime").JSX.Element;

package/dist/ui/app-bar/hooks/use-app-bar-scroll.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @file use-app-bar-scroll.ts
+ * MD3 Expressive App Bar — Scroll behavior hook.
+ *
+ * Tracks scroll state for App Bar behaviors:
+ * - `pinned`: background color change only
+ * - `enterAlways`: hide/show based on scroll direction
+ * - `exitUntilCollapsed`: drives collapse fraction (0 = expanded, 1 = collapsed)
+ */
+import * as React from "react";
+import type { AppBarScrollBehavior, UseAppBarScrollReturn } from "../app-bar.types";
+interface UseAppBarScrollOptions {
+    /** Ref to the scrollable container. Defaults to `window`. */
+    scrollElement?: React.RefObject<HTMLElement | null>;
+    /** Scroll behavior mode. @default "pinned" */
+    behavior?: AppBarScrollBehavior;
+    /** Collapsed height in px — used for `exitUntilCollapsed`. @default 64 */
+    collapsedHeight?: number;
+    /** Expanded height in px — used for `exitUntilCollapsed`. @default 112 */
+    expandedHeight?: number;
+}
+/**
+ * Tracks scroll position and derives App Bar state for all three behaviors.
+ *
+ * @example
+ * ```tsx
+ * // pinned (color change only)
+ * const { isScrolled } = useAppBarScroll({ behavior: 'pinned' });
+ *
+ * // enterAlways (hide/show)
+ * const { isHidden } = useAppBarScroll({ behavior: 'enterAlways' });
+ *
+ * // exitUntilCollapsed (collapse animation)
+ * const { collapsedFraction } = useAppBarScroll({
+ *   behavior: 'exitUntilCollapsed',
+ *   collapsedHeight: 64,
+ *   expandedHeight: 112,
+ * });
+ * ```
+ */
+export declare function useAppBarScroll({ scrollElement, behavior, collapsedHeight, expandedHeight, }?: UseAppBarScrollOptions): UseAppBarScrollReturn;
+export {};

package/dist/ui/app-bar/hooks/use-flexible-app-bar.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @file use-flexible-app-bar.ts
+ * Shared animation hook for MediumFlexibleAppBar and LargeFlexibleAppBar.
+ *
+ * Extracts common scroll-driven animation state to avoid duplication.
+ */
+import type { MotionValue } from "motion/react";
+import type { RefObject } from "react";
+import type { AppBarColors } from "../app-bar.types";
+interface UseFlexibleAppBarOptions {
+    collapsedHeight: number;
+    expandedHeight: number;
+    scrollElement?: RefObject<HTMLElement | null>;
+    colors?: AppBarColors;
+    /** [start, end] progress range where large title fades from 1 → 0 */
+    largeTitleFadeRange: [number, number];
+    /** [start, end] progress range where small title fades from 0 → 1 */
+    smallTitleFadeRange: [number, number];
+    /** [start, end] progress range where subtitle fades from 1 → 0 */
+    subtitleFadeRange: [number, number];
+    /** [start, end] progress range where headerContent fades from 1 → 0 */
+    headerContentFadeRange: [number, number];
+    /** [expanded, collapsed] Y offset for large title */
+    largeTitleYRange: [number, number];
+}
+export interface FlexibleAppBarAnimationState {
+    height: MotionValue<number>;
+    currentBg: string;
+    cssTransition: string | undefined;
+    largeTitleOpacity: MotionValue<number>;
+    largeTitleY: MotionValue<number>;
+    smallTitleOpacity: MotionValue<number>;
+    subtitleOpacity: MotionValue<number>;
+    headerContentOpacity: MotionValue<number>;
+}
+export declare function useFlexibleAppBar({ collapsedHeight, expandedHeight, scrollElement, colors, largeTitleFadeRange, smallTitleFadeRange, subtitleFadeRange, headerContentFadeRange, largeTitleYRange, }: UseFlexibleAppBarOptions): FlexibleAppBarAnimationState;
+export {};

package/dist/ui/app-bar/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @file index.ts
+ * MD3 Expressive App Bar — Public API exports.
+ *
+ * Components:
+ * - SmallAppBar: Single-row, 64px height, TitleLarge
+ * - MediumFlexibleAppBar: Collapsible, HeadlineMedium → TitleLarge
+ * - LargeFlexibleAppBar: Collapsible, DisplaySmall → TitleLarge
+ * - SearchAppBar: Pill search bar with layoutId for SearchView transition
+ * - SearchView: Full-screen search overlay
+ * - SearchViewContainer: Wraps SearchView with AnimatePresence
+ * - BottomAppBar: Fixed bottom nav with optional FAB
+ * - DockedToolbar: Secondary navigation bar
+ * - AppBarRow: Horizontal actions with overflow
+ * - AppBarColumn: Vertical actions with overflow
+ * - AppBarOverflowIndicator: More-vert dropdown trigger
+ *
+ * Hook:
+ * - useAppBarScroll: Drives scroll-based behavior (pinned / enterAlways / exitUntilCollapsed)
+ *
+ * Tokens:
+ * - AppBarTokens: Dimensional tokens (heights, spacing)
+ * - appBarTypography: Typography class strings
+ * - APP_BAR_COLORS: CSS custom property color references
+ * - Animation constants (APP_BAR_COLOR_TRANSITION, etc.)
+ */
+export { APP_BAR_BOTTOM_SPRING, APP_BAR_COLOR_TRANSITION, APP_BAR_COLORS, APP_BAR_ENTER_ALWAYS_SPRING, APP_BAR_TITLE_FADE, AppBarTokens, appBarTypography, SEARCH_VIEW_SPRING, } from "./app-bar.tokens";
+export type { AppBarColors, AppBarColumnProps, AppBarItem, AppBarItemType, AppBarMenuState, AppBarOverflowIndicatorProps, AppBarRowProps, AppBarScrollBehavior, BaseAppBarProps, BottomAppBarProps, DockedToolbarProps, FlexibleAppBarProps, SearchAppBarProps, SearchBarVariant, SearchViewProps, SmallAppBarProps, TitleAlignment, UseAppBarScrollReturn, } from "./app-bar.types";
+export { AppBarColumn } from "./app-bar-column";
+export { AppBarOverflowIndicator } from "./app-bar-overflow-indicator";
+export { AppBarRow } from "./app-bar-row";
+export { BottomAppBar } from "./bottom-app-bar";
+export { DockedToolbar } from "./docked-toolbar";
+export { useAppBarScroll } from "./hooks/use-app-bar-scroll";
+export { LargeFlexibleAppBar } from "./large-flexible-app-bar";
+export { MediumFlexibleAppBar } from "./medium-flexible-app-bar";
+export { SearchAppBar } from "./search-app-bar";
+export { SearchView, SearchViewContainer } from "./search-view";
+export { SmallAppBar } from "./small-app-bar";

package/dist/ui/app-bar/large-flexible-app-bar.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @file large-flexible-app-bar.tsx
+ * MD3 Expressive Large Flexible App Bar.
+ *
+ * Like MediumFlexibleAppBar but with larger typography.
+ * Expanded height: 120px (no subtitle) / 152px (with subtitle)
+ * Collapsed height: 64px
+ * Title crossfade: DisplaySmall (expanded) ↔ TitleLarge (collapsed)
+ *
+ * @see docs/m3/app-bars/AppBarLargeFlexibleTokens.kt
+ */
+import type { FlexibleAppBarProps } from "./app-bar.types";
+/**
+ * MD3 Expressive Large Flexible App Bar.
+ *
+ * @example
+ * ```tsx
+ * <LargeFlexibleAppBar
+ *   title="Discover"
+ *   subtitle="Trending today"
+ *   navigationIcon={<IconButton aria-label="Open menu"><Icon>menu</Icon></IconButton>}
+ *   headerContent={<img src="/banner.jpg" alt="" className="rounded-xl h-20 w-full object-cover" />}
+ * />
+ * ```
+ */
+export declare function LargeFlexibleAppBar({ title, subtitle, titleAlignment, navigationIcon, actions, colors, scrollElement, headerContent, collapsedHeight, expandedHeight, className, }: FlexibleAppBarProps): import("react/jsx-runtime").JSX.Element;

package/dist/ui/app-bar/medium-flexible-app-bar.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @file medium-flexible-app-bar.tsx
+ * MD3 Expressive Medium Flexible App Bar.
+ *
+ * Two-row layout in expanded state, collapses to single row on scroll.
+ * Expanded height: 112px (no subtitle) / 136px (with subtitle)
+ * Collapsed height: 64px
+ * Title crossfade: HeadlineMedium (expanded) ↔ TitleLarge (collapsed)
+ *
+ * Supports `exitUntilCollapsed` scroll behavior only.
+ *
+ * @see docs/m3/app-bars/AppBarMediumFlexibleTokens.kt
+ */
+import type { FlexibleAppBarProps } from "./app-bar.types";
+/**
+ * MD3 Expressive Medium Flexible App Bar.
+ *
+ * @example
+ * ```tsx
+ * <MediumFlexibleAppBar
+ *   title="Settings"
+ *   subtitle="Manage your preferences"
+ *   navigationIcon={<IconButton aria-label="Go back"><Icon>arrow_back</Icon></IconButton>}
+ *   actions={<IconButton aria-label="More options"><Icon>more_vert</Icon></IconButton>}
+ * />
+ * ```
+ */
+export declare function MediumFlexibleAppBar({ title, subtitle, titleAlignment, navigationIcon, actions, colors, scrollElement, headerContent, collapsedHeight, expandedHeight, className, }: FlexibleAppBarProps): import("react/jsx-runtime").JSX.Element;

package/dist/ui/app-bar/search-app-bar.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @file search-app-bar.tsx
+ * MD3 Expressive Search App Bar.
+ *
+ * New variant in MD3 Expressive (May 2025).
+ * Replaces the title area with a pill-shaped search bar.
+ * Uses Framer Motion layoutId to enable shared element transition with <SearchView>.
+ *
+ * @see docs/m3/app-bars/AppBar.kt — SearchAppBar
+ */
+import type { SearchAppBarProps } from "./app-bar.types";
+/**
+ * MD3 Expressive Search App Bar.
+ *
+ * When the search bar is clicked, callers should open a `<SearchView>` overlay.
+ * Uses Framer Motion `layoutId` (via `searchBarId`) for a smooth shared-element
+ * transition between this bar and the search view.
+ *
+ * @example
+ * ```tsx
+ * const [searchOpen, setSearchOpen] = useState(false);
+ *
+ * <SearchAppBar
+ *   searchBarId="main-search"
+ *   searchPlaceholder="Search messages..."
+ *   onSearchFocus={() => setSearchOpen(true)}
+ *   trailingSearchActions={
+ *     <IconButton aria-label="Voice search"><Icon>mic</Icon></IconButton>
+ *   }
+ *   externalActions={<Avatar src={user.avatar} />}
+ * />
+ *
+ * <AnimatePresence>
+ *   {searchOpen && (
+ *     <SearchView
+ *       searchBarId="main-search"
+ *       onClose={() => setSearchOpen(false)}
+ *     />
+ *   )}
+ * </AnimatePresence>
+ * ```
+ */
+export declare function SearchAppBar({ searchPlaceholder, searchValue, onSearchFocus, leadingSearchIcon, trailingSearchActions, externalActions, navigationIcon, colors, scrollBehavior, scrollElement, searchBarId, className, }: SearchAppBarProps): import("react/jsx-runtime").JSX.Element;

package/dist/ui/app-bar/search-view.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @file search-view.tsx
+ * MD3 Expressive Search View.
+ *
+ * Full-screen overlay activated when a SearchAppBar's search bar is clicked.
+ * Shares a Framer Motion `layoutId` with the SearchAppBar search bar for a
+ * smooth shared element transition.
+ *
+ * Usage pattern:
+ * ```tsx
+ * const [open, setOpen] = useState(false);
+ *
+ * // In render:
+ * <SearchAppBar searchBarId="main" onSearchFocus={() => setOpen(true)} />
+ * <AnimatePresence>
+ *   {open && <SearchView searchBarId="main" onClose={() => setOpen(false)} />}
+ * </AnimatePresence>
+ * ```
+ *
+ * Design notes:
+ * - The SearchView is intentionally separate from SearchAppBar to allow consumers
+ *   to customize the results/suggestions content without coupling.
+ * - The `searchBarId` prop must match between SearchAppBar and SearchView to
+ *   enable the shared element transition.
+ * - Focus is moved to the search input when the view opens.
+ * - Escape key closes the view and returns focus to the search bar.
+ */
+import type { SearchViewProps } from "./app-bar.types";
+/**
+ * MD3 Expressive Search View.
+ *
+ * Renders a full-screen search overlay with a shared element transition
+ * from the triggering `<SearchAppBar>` search bar.
+ *
+ * Mount/unmount this component via `<AnimatePresence>` in the consumer.
+ */
+export declare function SearchView({ searchBarId, value, onChange, onClose, placeholder, children, leadingIcon, trailingAction, className, }: SearchViewProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Convenience wrapper that handles the AnimatePresence + open state.
+ *
+ * @example
+ * ```tsx
+ * <SearchBar
+ *   isOpen={searchOpen}
+ *   onClose={() => setSearchOpen(false)}
+ *   searchBarId="main-search"
+ * >
+ *   <SearchResultsList results={results} />
+ * </SearchBar>
+ * ```
+ */
+export declare function SearchViewContainer({ isOpen, ...props }: SearchViewProps & {
+    isOpen: boolean;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/ui/app-bar/small-app-bar.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @file small-app-bar.tsx
+ * MD3 Expressive Small App Bar.
+ *
+ * Single-row layout: [navigationIcon][title + subtitle][actions]
+ * Height: 64px | Title: TitleLarge (22sp) | Subtitle: LabelMedium (12sp)
+ *
+ * Scroll behaviors:
+ * - pinned: changes background color surface → surface-container
+ * - enterAlways: slides up when scrolling down, slides down when scrolling up
+ *
+ * @see docs/m3/app-bars/AppBarSmallTokens.kt
+ */
+import type { SmallAppBarProps } from "./app-bar.types";
+/**
+ * MD3 Expressive Small App Bar.
+ *
+ * @example
+ * ```tsx
+ * // Left-aligned (default)
+ * <SmallAppBar
+ *   title="Inbox"
+ *   navigationIcon={<IconButton aria-label="Go back"><Icon>arrow_back</Icon></IconButton>}
+ *   actions={<IconButton aria-label="Search"><Icon>search</Icon></IconButton>}
+ *   scrollBehavior="pinned"
+ * />
+ *
+ * // Center-aligned with subtitle
+ * <SmallAppBar
+ *   title="Profile"
+ *   subtitle="@username"
+ *   titleAlignment="center"
+ *   scrollBehavior="enterAlways"
+ * />
+ * ```
+ */
+export declare function SmallAppBar({ title, subtitle, titleAlignment, navigationIcon, actions, colors, scrollBehavior, scrollElement, className, }: SmallAppBarProps): import("react/jsx-runtime").JSX.Element;

package/dist/ui/search/animated-placeholder.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @file animated-placeholder.tsx
+ * MD3 Expressive Search — Animated placeholder overlay.
+ *
+ * Replaces the native `::placeholder` with a GPU-accelerated `translateX`
+ * animation so the placeholder text can smoothly slide from its alignment
+ * position (center / right) to left when the search input is focused.
+ *
+ * Implementation notes:
+ * - Only `transform: translateX` is animated → no layout triggers, no paint.
+ * - Container width is measured once via `useLayoutEffect` (before paint) to
+ *   avoid a first-render flash, then kept fresh via `ResizeObserver`.
+ * - xOffset is stored in `useState` so Framer Motion picks up changes and
+ *   re-animates smoothly on container resize.
+ * - The span is never unmounted — only opacity-toggled — to preserve the
+ *   measurement ref between renders.
+ */
+import * as React from "react";
+interface AnimatedPlaceholderProps {
+    /** Placeholder text to display. */
+    text: string;
+    /** Alignment of the placeholder when idle (not focused). @default "left" */
+    textAlign: "left" | "center" | "right";
+    /**
+     * Whether the placeholder should be visible.
+     * Pass `!query` — hide when the user has typed something.
+     */
+    visible: boolean;
+    /**
+     * Whether the search is in an active/focused state.
+     * When `true`, the placeholder snaps to `left` regardless of `textAlign`.
+     */
+    focused: boolean;
+    /**
+     * The `<input>` element that this component wraps.
+     * It should have `w-full` instead of `flex-1` since this wrapper
+     * takes over the `flex-1` role in the parent flex layout.
+     */
+    children: React.ReactNode;
+    /** Extra className forwarded to the wrapper div. */
+    className?: string;
+}
+/**
+ * Wraps a search `<input>` with an animated placeholder overlay.
+ *
+ * The wrapper div occupies `flex-1` so it fits seamlessly in the
+ * horizontal flex layout used by search bar headers. The children
+ * (the `<input>`) should use `w-full` to fill the wrapper.
+ *
+ * Accessibility: `aria-label` on the `<input>` carries the placeholder
+ * text for screen readers; this span is `aria-hidden="true"`.
+ */
+export declare function AnimatedPlaceholder({ text, textAlign, visible, focused, children, className, }: AnimatedPlaceholderProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/ui/search/hooks/use-search-keyboard.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @file use-search-keyboard.ts
+ * Keyboard navigation hook for the MD3 Search component.
+ *
+ * Handles:
+ * - ArrowDown / ArrowUp → navigate through suggestions (role="option")
+ * - Enter → submit search or select active suggestion
+ * - Escape → close the SearchView
+ */
+import type { UseSearchKeyboardReturn } from "../search.types";
+interface UseSearchKeyboardOptions {
+    /** Whether the SearchView is currently open. */
+    active: boolean;
+    /** Callback to close the SearchView. */
+    onActiveChange: (active: boolean) => void;
+    /** Callback for search submission. */
+    onSearch: (query: string) => void;
+    /** Current search query. */
+    query: string;
+    /** Total number of suggestion items in the listbox. */
+    itemCount: number;
+    /** Called when user selects a specific suggestion by index. */
+    onSelectSuggestion?: (index: number) => void;
+}
+/**
+ * Manages keyboard navigation for the Search component.
+ *
+ * Complies with WAI-ARIA Combobox pattern:
+ * @see https://www.w3.org/WAI/ARIA/apg/patterns/combobox/
+ */
+export declare function useSearchKeyboard({ active, onActiveChange, onSearch, query, itemCount, onSelectSuggestion, }: UseSearchKeyboardOptions): UseSearchKeyboardReturn;
+export {};

package/dist/ui/search/hooks/use-search-view-focus.d.ts

@@ -0,0 +1,6 @@
+import * as React from "react";
+/**
+ * Focuses `inputRef` when `active` becomes true, using a double-rAF
+ * to wait for Framer Motion's layout animation to finish painting.
+ */
+export declare function useSearchViewFocus(inputRef: React.RefObject<HTMLInputElement | null>, active: boolean): void;

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

@@ -0,0 +1,27 @@
+/**
+ * @file index.ts
+ * MD3 Expressive Search — Public API exports.
+ *
+ * Components:
+ * - Search: Orchestrator (SearchBar + SearchView)
+ * - SearchBar: Collapsed pill state (standalone use)
+ * - SearchViewDocked: Expanded docked popup (standalone use)
+ * - SearchViewFullScreen: Expanded full-screen overlay (standalone use)
+ *
+ * Hook:
+ * - useSearchKeyboard: WAI-ARIA combobox keyboard navigation
+ *
+ * Tokens:
+ * - SearchTokens: Dimensional tokens (heights, sizes)
+ * - SEARCH_COLORS: CSS custom property color references
+ * - SEARCH_TYPOGRAPHY: Typography class strings
+ * - Animation constants
+ */
+export { useSearchKeyboard } from "./hooks/use-search-keyboard";
+export { Search } from "./search";
+export { SEARCH_BAR_EXIT_SPRING, SEARCH_BAR_EXPAND_SPRING, SEARCH_COLORS, SEARCH_DOCKED_REVEAL_SPRING, SEARCH_FULLSCREEN_SPRING, SEARCH_TYPOGRAPHY, SearchTokens, } from "./search.tokens";
+export type { SearchProps, SearchStyleType, SearchVariant, } from "./search.types";
+export { SearchBar } from "./search-bar";
+export { useSearch } from "./search-context";
+export { SearchViewDocked } from "./search-view-docked";
+export { SearchViewFullScreen } from "./search-view-fullscreen";

package/dist/ui/search/search-bar.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @file search-bar.tsx
+ * MD3 Expressive SearchBar — Collapsed state.
+ *
+ * Renders a pill-shaped search bar (CornerFull, h-56px).
+ * When focused/clicked → calls onActiveChange(true) to open SearchView.
+ *
+ * Option B (MD3 morphing): SearchBar is wrapped in its own AnimatePresence
+ * with mode="popLayout". When SearchView opens, SearchBar plays an exit
+ * animation (opacity → 0, scale → 0.95) before unmounting, releasing the
+ * shared layoutId so SearchView can claim it and morph from the same origin.
+ *
+ * Role: combobox (WAI-ARIA Search Combobox pattern).
+ * @see https://www.w3.org/WAI/ARIA/apg/patterns/combobox/
+ */
+import * as React from "react";
+import type { SearchInternalProps, SearchProps } from "./search.types";
+type SearchBarProps = Pick<SearchProps, "query" | "onQueryChange" | "onSearch" | "active" | "onActiveChange" | "leadingIcon" | "trailingIcon" | "placeholder" | "textAlign" | "className" | "aria-label"> & SearchInternalProps & {
+    /** KeyDown handler from useSearchKeyboard. */
+    onKeyDown: (e: React.KeyboardEvent) => void;
+    /** Currently highlighted suggestion index (-1 = none). */
+    activeIndex: number;
+};
+/**
+ * SearchBar — collapsed state of the MD3 Search component.
+ *
+ * Uses Framer Motion `layout` + shared `layoutId` to morph into
+ * SearchView when active. Wrapped in AnimatePresence with mode="popLayout"
+ * so it exits (fades/scales out) before SearchView claims the layoutId.
+ */
+export declare function SearchBar({ query, onQueryChange, onSearch, active, onActiveChange, leadingIcon, trailingIcon, placeholder, textAlign, className, "aria-label": ariaLabel, searchId, listboxId, onKeyDown, activeIndex, }: SearchBarProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/ui/search/search-context.d.ts

@@ -0,0 +1,24 @@
+import * as React from "react";
+/**
+ * MD3 Expressive Search Context
+ * Shared state for the Search orchestrator and its children.
+ */
+interface SearchContextValue {
+    /** Unique ID for the results listbox, used for aria-controls. */
+    listboxId: string;
+    /** Currently highlighted suggestion index. -1 = none. */
+    activeIndex: number;
+}
+/**
+ * Provider for Search component state.
+ * Internal use only within the library.
+ */
+export declare function SearchProvider({ children, value, }: {
+    children: React.ReactNode;
+    value: SearchContextValue;
+}): import("react/jsx-runtime").JSX.Element;
+/**
+ * Hook to access Search state from children (e.g., search items).
+ */
+export declare function useSearch(): SearchContextValue;
+export {};

package/dist/ui/search/search-view-docked.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @file search-view-docked.tsx
+ * MD3 Expressive SearchView — Docked variant.
+ *
+ * Displays as a popup dropdown below the SearchBar.
+ * Recommended for medium and large screens (tablets, desktops).
+ *
+ * Shape: CornerExtraLarge (rounded-[28px]) per SearchViewTokens.DockedContainerShape.
+ * Header height: 56dp per SearchViewTokens.DockedHeaderContainerHeight.
+ *
+ * Animation (Option B — MD3 morphing):
+ * - Shares `layoutId` with SearchBar. After SearchBar exits via its own
+ *   AnimatePresence (mode="popLayout"), this view claims the layoutId and
+ *   Framer Motion morphs the pill shape → rounded-[28px] container.
+ * - Uses mode="popLayout" so SearchBar can re-enter after this exits.
+ * - Focus: double-rAF pattern syncs focus with layout animation frame.
+ */
+import * as React from "react";
+import type { SearchInternalProps, SearchProps } from "./search.types";
+type SearchViewDockedProps = Pick<SearchProps, "query" | "onQueryChange" | "onSearch" | "active" | "onActiveChange" | "leadingIcon" | "trailingIcon" | "placeholder" | "textAlign" | "styleType" | "hasGap" | "children" | "viewClassName" | "aria-label"> & SearchInternalProps & {
+    onKeyDown: (e: React.KeyboardEvent) => void;
+    activeIndex: number;
+};
+export declare function SearchViewDocked({ query, onQueryChange, onSearch, active, onActiveChange, leadingIcon, trailingIcon, placeholder, textAlign, styleType, hasGap, children, viewClassName, "aria-label": ariaLabel, searchId, listboxId, onKeyDown, activeIndex, }: SearchViewDockedProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/ui/search/search-view-fullscreen.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @file search-view-fullscreen.tsx
+ * MD3 Expressive SearchView — FullScreen variant.
+ *
+ * Renders a full-screen overlay via React Portal.
+ * Using Portal avoids z-index stacking context issues and ensures
+ * the overlay always covers the entire viewport correctly.
+ *
+ * Animation (Option B — MD3 morphing):
+ * - Shares `layoutId` with SearchBar. After SearchBar exits via its own
+ *   AnimatePresence (mode="popLayout"), this view claims the layoutId and
+ *   Framer Motion morphs the pill shape → full-screen rect (CornerFull → CornerNone).
+ * - mode="popLayout" on this AnimatePresence enables SearchBar to re-enter
+ *   after this view exits.
+ * - Focus: double-rAF pattern syncs focus with layout animation frame.
+ *
+ * Header height: 72dp per SearchViewTokens.FullScreenHeaderContainerHeight.
+ * ESC key closes the view (handled by useSearchKeyboard).
+ */
+import * as React from "react";
+import type { SearchInternalProps, SearchProps } from "./search.types";
+type SearchViewFullScreenProps = Pick<SearchProps, "query" | "onQueryChange" | "onSearch" | "active" | "onActiveChange" | "leadingIcon" | "trailingIcon" | "placeholder" | "textAlign" | "styleType" | "children" | "viewClassName" | "aria-label"> & SearchInternalProps & {
+    onKeyDown: (e: React.KeyboardEvent) => void;
+    activeIndex: number;
+};
+/**
+ * SearchView FullScreen — full-screen overlay via React Portal.
+ *
+ * The `layoutId` shared with SearchBar enables Framer Motion to animate
+ * the shape morphing from the pill (rounded-full) to a full-screen rect.
+ *
+ * Contained style: no divider, background preserved.
+ * Divided style: HorizontalDivider between header and results.
+ */
+export declare function SearchViewFullScreen({ query, onQueryChange, onSearch, active, onActiveChange, leadingIcon, trailingIcon, placeholder, textAlign, styleType, children, viewClassName, "aria-label": ariaLabel, searchId, listboxId, onKeyDown, activeIndex, }: SearchViewFullScreenProps): React.ReactPortal | null;
+export {};