@bug-on/md3-react 2.0.1 → 2.0.3

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

@@ -0,0 +1,50 @@
+/**
+ * @file search.tsx
+ * MD3 Expressive Search — Orchestrator component.
+ *
+ * Composes SearchBar (collapsed) + SearchView (expanded) into a single
+ * developer-facing API. Routes to the correct SearchView variant based on props.
+ *
+ * Developer usage:
+ * ```tsx
+ * const [query, setQuery] = useState("");
+ * const [active, setActive] = useState(false);
+ *
+ * <Search
+ *   query={query}
+ *   onQueryChange={setQuery}
+ *   onSearch={(q) => doSearch(q)}
+ *   active={active}
+ *   onActiveChange={setActive}
+ *   variant="docked"
+ *   styleType="contained"
+ * >
+ *   {results.map((r) => (
+ *     <div key={r.id} id={`${YOUR_LISTBOX_ID}-option-0`} role="option">
+ *       {r.label}
+ *     </div>
+ *   ))}
+ * </Search>
+ * ```
+ */
+import type { SearchProps } from "./search.types";
+import { useSearch } from "./search-context";
+/**
+ * MD3 Expressive Search — Orchestrator component.
+ *
+ * Renders a SearchBar (collapsed pill) and the appropriate SearchView
+ * (docked popup or fullscreen overlay) based on `variant`.
+ *
+ * The component is fully controlled:
+ * - `active` / `onActiveChange` manage open/close state.
+ * - `query` / `onQueryChange` manage input value.
+ *
+ * Shared `searchId` (React.useId) links SearchBar and SearchView via
+ * Framer Motion `layoutId` for seamless animated transitions.
+ */
+declare function SearchComponent({ query, onQueryChange, onSearch, active, onActiveChange, variant, styleType, hasGap, leadingIcon, trailingIcon, placeholder, textAlign, children, id, "aria-label": ariaLabel, className, viewClassName, }: SearchProps): import("react/jsx-runtime").JSX.Element;
+/** MD3 Expressive Search component with `Search.useSearch` context accessor. */
+export declare const Search: typeof SearchComponent & {
+    useSearch: typeof useSearch;
+};
+export {};

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

@@ -0,0 +1,112 @@
+/**
+ * @file search.tokens.ts
+ * MD3 Expressive Search — Design tokens ported from:
+ *   - SearchBarTokens.kt (v0_210)
+ *   - SearchViewTokens.kt (v0_210)
+ *
+ * All dimensional values are in px (1dp = 1px on web).
+ * Colors reference CSS custom properties — do NOT hardcode hex.
+ * @see docs/m3/search/SearchBarTokens.kt
+ * @see docs/m3/search/SearchViewTokens.kt
+ */
+/**
+ * Height and shape tokens for Search variants.
+ * Maps directly from MD3 Kotlin token files.
+ */
+export declare const SearchTokens: {
+    readonly heights: {
+        /** SearchBarTokens.ContainerHeight = 56dp */
+        readonly bar: 56;
+        /** SearchViewTokens.DockedHeaderContainerHeight = 56dp */
+        readonly dockedHeader: 56;
+        /** SearchViewTokens.FullScreenHeaderContainerHeight = 72dp */
+        readonly fullScreenHeader: 72;
+    };
+    /** SearchBarTokens.AvatarSize = 30dp */
+    readonly avatarSize: 30;
+    /** Standard icon size for leading/trailing icons. */
+    readonly iconSize: 20;
+    /** Touch target for interactive icons per MD3 a11y spec. */
+    readonly iconTouchTarget: 48;
+    /** Gap between SearchBar and results list when hasGap=true. */
+    readonly dropdownGap: 2;
+};
+/**
+ * CSS custom property references for Search colors.
+ * Maps to --md-sys-color-* tokens in the MD3 theme system.
+ *
+ * SearchBarTokens.kt:
+ * - ContainerColor → SurfaceContainerHigh
+ * - LeadingIconColor → OnSurface
+ * - TrailingIconColor → OnSurfaceVariant
+ * - InputTextColor → OnSurface
+ * - SupportingTextColor → OnSurfaceVariant (placeholder)
+ *
+ * SearchViewTokens.kt:
+ * - ContainerColor → SurfaceContainerHigh
+ * - DividerColor → Outline
+ */
+export declare const SEARCH_COLORS: {
+    /** SearchBarTokens.ContainerColor → surface-container-high */
+    readonly container: "var(--md-sys-color-surface-container-high)";
+    /** SearchBarTokens.LeadingIconColor → on-surface */
+    readonly leadingIcon: "var(--md-sys-color-on-surface)";
+    /** SearchBarTokens.TrailingIconColor → on-surface-variant */
+    readonly trailingIcon: "var(--md-sys-color-on-surface-variant)";
+    /** SearchBarTokens.InputTextColor → on-surface */
+    readonly inputText: "var(--md-sys-color-on-surface)";
+    /** SearchBarTokens.SupportingTextColor → on-surface-variant (placeholder) */
+    readonly supportingText: "var(--md-sys-color-on-surface-variant)";
+    /** SearchViewTokens.DividerColor → outline */
+    readonly divider: "var(--md-sys-color-outline)";
+    /** Focus indicator → secondary */
+    readonly focusIndicator: "var(--md-sys-color-secondary)";
+};
+/**
+ * SearchBarTokens.InputTextFont = BodyLarge (16sp / 24sp line-height).
+ * SearchBarTokens.SupportingTextFont = BodyLarge.
+ */
+export declare const SEARCH_TYPOGRAPHY: {
+    /** BodyLarge — used for input text and placeholder. */
+    readonly bodyLarge: "text-[16px] leading-6 font-normal tracking-[0.5px]";
+};
+/**
+ * Spring animation for SearchBar width expand (inactive → active).
+ * Matches MD3 FastSpatial motion scheme.
+ */
+export declare const SEARCH_BAR_EXPAND_SPRING: {
+    type: "spring";
+    stiffness: number;
+    damping: number;
+    mass: number;
+};
+/**
+ * Spring animation for Docked SearchView dropdown reveal (slide + fade).
+ * Offset Y: -8px on enter, opacity 0→1.
+ */
+export declare const SEARCH_DOCKED_REVEAL_SPRING: {
+    type: "spring";
+    stiffness: number;
+    damping: number;
+    mass: number;
+};
+/**
+ * Spring animation for FullScreen SearchView shape morphing.
+ * Lower stiffness + mass gives a smoother pill→fullscreen morph.
+ */
+export declare const SEARCH_FULLSCREEN_SPRING: {
+    type: "spring";
+    stiffness: number;
+    damping: number;
+    mass: number;
+};
+/**
+ * Exit transition for SearchBar when mode="popLayout" is used.
+ * Fast fade-out so SearchView can claim the layoutId quickly.
+ */
+export declare const SEARCH_BAR_EXIT_SPRING: {
+    type: "spring";
+    stiffness: number;
+    damping: number;
+    mass: number;
+};

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

@@ -0,0 +1,131 @@
+/**
+ * @file search.types.ts
+ * MD3 Expressive Search — TypeScript prop definitions.
+ * Spec: https://m3.material.io/components/search/overview
+ * Reference: docs/m3/search/SearchBar.kt (MD3 Expressive)
+ */
+import type * as React from "react";
+/**
+ * Display variant for the expanded SearchView.
+ *
+ * - `docked`: Popup dropdown below the SearchBar. For medium/large screens.
+ * - `fullscreen`: Full-screen dialog overlay. For compact/mobile screens.
+ */
+export type SearchVariant = "docked" | "fullscreen";
+/**
+ * Visual style type for the SearchView.
+ *
+ * - `contained`: No divider between the input area and results.
+ *   The container background is preserved continuously (recommended).
+ * - `divided`: A HorizontalDivider separates the input area from results.
+ */
+export type SearchStyleType = "contained" | "divided";
+/**
+ * Internal props shared between SearchBar and SearchView sub-components.
+ * Not part of the public API.
+ * @internal
+ */
+export interface SearchInternalProps {
+    /** Unique ID generated by useId(), used as Framer Motion layoutId. */
+    searchId: string;
+    /** Unique ID for the results listbox, used for aria-controls. */
+    listboxId: string;
+}
+/**
+ * Props for the `<Search>` component (orchestrator).
+ *
+ * @example
+ * ```tsx
+ * const [query, setQuery] = useState("");
+ * const [active, setActive] = useState(false);
+ *
+ * <Search
+ *   query={query}
+ *   onQueryChange={setQuery}
+ *   onSearch={(q) => console.log("search:", q)}
+ *   active={active}
+ *   onActiveChange={setActive}
+ *   variant="docked"
+ *   styleType="contained"
+ * >
+ *   <SearchResultsList />
+ * </Search>
+ * ```
+ */
+export interface SearchProps {
+    /** Current search query value (controlled). */
+    query: string;
+    /** Called when user types in the search input. */
+    onQueryChange: (query: string) => void;
+    /** Called when user submits search (Enter key or suggestion click). */
+    onSearch: (query: string) => void;
+    /** Whether the SearchView is expanded/open (controlled). */
+    active: boolean;
+    /** Called when the Search open/close state should change. */
+    onActiveChange: (active: boolean) => void;
+    /**
+     * Display variant for the expanded state.
+     * @default "docked"
+     */
+    variant?: SearchVariant;
+    /**
+     * Visual style for the SearchView container.
+     * @default "contained"
+     */
+    styleType?: SearchStyleType;
+    /**
+     * Whether to add a 2dp gap between the input header and the results list.
+     * Only applies when `variant="docked"`.
+     * @default false
+     */
+    hasGap?: boolean;
+    /**
+     * Icon rendered at the leading edge of the search input.
+     * Defaults to a built-in search icon.
+     */
+    leadingIcon?: React.ReactNode;
+    /**
+     * Icon or action rendered at the trailing edge of the search input.
+     * Common examples: mic, camera, QR code.
+     */
+    trailingIcon?: React.ReactNode;
+    /** Placeholder text shown when the input is empty. @default "Search" */
+    placeholder?: string;
+    /**
+     * Align the placeholder text to left, center, or right.
+     * Typed text will always remain left-aligned.
+     * @default "left"
+     */
+    textAlign?: "left" | "center" | "right";
+    /**
+     * Search results or suggestions rendered inside the SearchView.
+     * Use `role="option"` on each item for accessibility.
+     */
+    children?: React.ReactNode;
+    /**
+     * Override the auto-generated input element ID.
+     * Auto-generated via React.useId() if not provided.
+     */
+    id?: string;
+    /**
+     * Accessible label for the search landmark.
+     * @default "Search"
+     */
+    "aria-label"?: string;
+    /** Additional CSS classes for the SearchBar root element. */
+    className?: string;
+    /** Additional CSS classes for the SearchView container. */
+    viewClassName?: string;
+}
+/**
+ * Return type for `useSearchKeyboard`.
+ * @internal
+ */
+export interface UseSearchKeyboardReturn {
+    /** Currently highlighted suggestion index. -1 = none. */
+    activeIndex: number;
+    /** KeyDown handler — attach to the search input. */
+    handleKeyDown: (e: React.KeyboardEvent) => void;
+    /** Reset activeIndex (e.g., when query changes). */
+    resetActiveIndex: () => void;
+}

package/dist/ui/search/trailing-action.d.ts

@@ -0,0 +1,9 @@
+import type * as React from "react";
+interface TrailingActionProps {
+    query: string;
+    trailingIcon?: React.ReactNode;
+    onClear: () => void;
+}
+/** Clear button when query is non-empty, otherwise the trailing icon slot. */
+export declare function TrailingAction({ query, trailingIcon, onClear, }: TrailingActionProps): import("react/jsx-runtime").JSX.Element | null;
+export {};

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.3",
   "description": "Material Design 3 Expressive React components",
   "author": "Bug Ổn",
   "license": "MIT",
@@ -68,6 +68,7 @@
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "@vitejs/plugin-react": "^6.0.1",
+    "@vitest/coverage-v8": "4.1.4",
     "jsdom": "^29.0.0",
     "tsup": "^8.4.0",
     "typescript": "5.8.3",