@bug-on/md3-react 2.0.1 → 2.0.2

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/snackbar/snackbar.d.ts

@@ -146,6 +146,7 @@ export declare namespace SnackbarHost {
 interface SnackbarContextValue {
     showSnackbar: (visuals: SnackbarVisuals) => Promise<SnackbarResult>;
 }
+export declare const SnackbarContext: React.Context<SnackbarContextValue | null>;
 /**
  * MD3 SnackbarProvider — context provider for imperative snackbar API.
  *

package/dist/ui/theme-provider/index.d.ts

@@ -1,5 +1,7 @@
 import { type ReactNode } from "react";
 import { type ThemeMode } from "../../lib/theme-utils";
+import { Typography } from "../typography/typography";
+import { type FontVariationAxes } from "../typography/typography-tokens";
 interface ThemeContextValue {
     sourceColor: string;
     setSourceColor: (color: string) => void;
@@ -11,8 +13,36 @@ export interface MD3ThemeProviderProps {
     sourceColor?: string;
     defaultMode?: ThemeMode;
     persistToLocalStorage?: boolean;
+    /**
+     * A fully custom `Typography` instance.
+     * When provided, `fontFamily` and `fontVariationAxes` are ignored.
+     */
+    typography?: Typography;
+    /**
+     * Override the CSS `font-family` for all typography styles.
+     * Ignored when `typography` prop is provided.
+     * @example "'Inter', sans-serif"
+     */
+    fontFamily?: string;
+    /**
+     * Variable font axes applied globally via `font-variation-settings`.
+     * Merged on top of defaults (`ROND: 100`). Ignored when `typography` is provided.
+     * @example { ROND: 50 }
+     */
+    fontVariationAxes?: FontVariationAxes;
+    /**
+     * When `true`, mounts `SnackbarHost` inside the provider and exposes
+     * `useSnackbar()` to all descendants — no separate `<SnackbarProvider>` needed.
+     *
+     * Opt-in, default `false`. For advanced usage (e.g., scoped snackbars or
+     * custom host positioning), keep this `false` and use `<SnackbarProvider>`
+     * or `<SnackbarHost>` directly.
+     *
+     * @default false
+     */
+    enableSnackbar?: boolean;
 }
-export declare function MD3ThemeProvider({ children, sourceColor: initialSourceColor, defaultMode, persistToLocalStorage, }: MD3ThemeProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function MD3ThemeProvider({ children, sourceColor: initialSourceColor, defaultMode, persistToLocalStorage, typography: typographyProp, fontFamily, fontVariationAxes, enableSnackbar, }: MD3ThemeProviderProps): import("react/jsx-runtime").JSX.Element;
 export declare function useTheme(): ThemeContextValue;
 export declare function useThemeMode(): Pick<ThemeContextValue, "mode" | "setMode">;
 export {};

package/dist/ui/toc.d.ts

@@ -14,6 +14,7 @@
  *   (~100px) and early deactivation (~80% from bottom) so the active item changes
  *   before the section scrolls off-screen.
  */
+import { type ScrollAreaProps } from "./scroll-area";
 /**
  * A single entry in the Table of Contents.
  *
@@ -45,6 +46,11 @@ export interface TableOfContentsProps {
      * Use this to control positioning (e.g. sticky, fixed) from the consumer.
      */
     className?: string;
+    /**
+     * Configuration for the internal ScrollArea.
+     * @default { type: "hover" }
+     */
+    scrollAreaProps?: Omit<ScrollAreaProps, "children">;
 }
 /**
  * Table of Contents sidebar component.
@@ -71,4 +77,4 @@ export interface TableOfContentsProps {
  *
  * @see https://m3.material.io/foundations/content-design/navigation
  */
-export declare function TableOfContents({ items, className }: TableOfContentsProps): import("react/jsx-runtime").JSX.Element;
+export declare function TableOfContents({ items, className, scrollAreaProps, }: TableOfContentsProps): import("react/jsx-runtime").JSX.Element;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bug-on/md3-react",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "description": "Material Design 3 Expressive React components",
   "author": "Bug Ổn",
   "license": "MIT",