@bug-on/m3-expressive 1.1.0 → 1.2.0

package/dist/core-D4048_K5.d.mts

@@ -0,0 +1,497 @@
+import * as React$1 from 'react';
+import { ReactNode } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ClassValue } from 'clsx';
+import './md3-Dty-Qcad.mjs';
+import { a as Typography, F as FontVariationAxes } from './typography-339RV6v7.mjs';
+
+/**
+ * useMediaQuery — SSR-safe responsive hook.
+ *
+ * Prevents hydration mismatch by initializing with `false`.
+ *
+ * @example
+ * ```tsx
+ * const isMobile = useMediaQuery('(max-width: 768px)');
+ * ```
+ */
+declare function useMediaQuery(query: string): boolean;
+
+interface RippleOptions {
+    /** Ripple animation duration (ms). Default: 600 */
+    duration?: number;
+    /** Ripple color. Default: 'currentColor' */
+    color?: string;
+    /** Opacity. Default: 0.12 (MD3 standard) */
+    opacity?: number;
+    /** Disable ripple (e.g. when component is disabled) */
+    disabled?: boolean;
+}
+/**
+ * useRipple — Material Design 3 Expressive Ripple Effect
+ *
+ * Pure DOM hook with zero external animation dependencies.
+ * Note: Requires element to have `position: relative` and `overflow: hidden`.
+ *
+ * @example
+ * ```tsx
+ * const { rippleRef, onPointerDown } = useRipple();
+ * <button ref={rippleRef} onPointerDown={onPointerDown}>Click me</button>
+ * ```
+ */
+declare function useRipple$1<T extends HTMLElement = HTMLElement>(options?: RippleOptions): {
+    rippleRef: React$1.RefObject<T | null>;
+    onPointerDown: (event: React.PointerEvent<T>) => void;
+};
+
+type ThemeMode = "light" | "dark" | "system";
+/**
+ * Color scheme variants from Material Design 3.
+ * - `expressive` — MD3 Expressive 2025: high-chroma, intentionally detached from
+ *   source color. **Default for this library.**
+ * - `tonal_spot` — Standard Android 12+ theme: low-to-medium colorfulness.
+ * - `vibrant` — More colorful than tonal_spot, hue from source.
+ * - `fidelity` — Stays close to the source color's hue and chroma.
+ * - `content` — Similar to fidelity, optimised for image-based content.
+ * - `monochrome` — No hue; all grays.
+ * - `neutral` — Near-neutral colors with subtle tint.
+ */
+type SchemeVariant = "expressive" | "tonal_spot" | "vibrant" | "fidelity" | "content" | "monochrome" | "neutral";
+/**
+ * Contrast level for the generated scheme.
+ * - `-1` — Minimum contrast (accessibility not guaranteed)
+ * - `0`  — Standard (design as spec'd)
+ * - `0.5` — Medium contrast
+ * - `1`  — Maximum contrast (WCAG AAA)
+ */
+type ContrastLevel = -1 | 0 | 0.5 | 1;
+/**
+ * Resolves the effective color scheme from a ThemeMode.
+ * When mode is "system", reads the OS preference via matchMedia.
+ * Returns "light" as the safe default in SSR environments.
+ */
+declare function resolveMode(mode: ThemeMode): "light" | "dark";
+interface MD3ColorScheme {
+    primary: string;
+    onPrimary: string;
+    primaryContainer: string;
+    onPrimaryContainer: string;
+    inversePrimary: string;
+    primaryFixed: string;
+    primaryFixedDim: string;
+    onPrimaryFixed: string;
+    onPrimaryFixedVariant: string;
+    /** Expressive dim tone for primary (v0.4.0+) */
+    primaryDim: string;
+    secondary: string;
+    onSecondary: string;
+    secondaryContainer: string;
+    onSecondaryContainer: string;
+    secondaryFixed: string;
+    secondaryFixedDim: string;
+    onSecondaryFixed: string;
+    onSecondaryFixedVariant: string;
+    /** Expressive dim tone for secondary (v0.4.0+) */
+    secondaryDim: string;
+    tertiary: string;
+    onTertiary: string;
+    tertiaryContainer: string;
+    onTertiaryContainer: string;
+    tertiaryFixed: string;
+    tertiaryFixedDim: string;
+    onTertiaryFixed: string;
+    onTertiaryFixedVariant: string;
+    /** Expressive dim tone for tertiary (v0.4.0+) */
+    tertiaryDim: string;
+    error: string;
+    onError: string;
+    errorContainer: string;
+    onErrorContainer: string;
+    surface: string;
+    onSurface: string;
+    surfaceVariant: string;
+    onSurfaceVariant: string;
+    surfaceTint: string;
+    /** Dimmed surface — darker than surface, lighter than surface-container. */
+    surfaceDim: string;
+    /** Brightened surface — lighter than surface. */
+    surfaceBright: string;
+    surfaceContainerLowest: string;
+    surfaceContainerLow: string;
+    surfaceContainer: string;
+    surfaceContainerHigh: string;
+    surfaceContainerHighest: string;
+    inverseSurface: string;
+    inverseOnSurface: string;
+    background: string;
+    onBackground: string;
+    outline: string;
+    outlineVariant: string;
+    shadow: string;
+    scrim: string;
+}
+interface GenerateM3ThemeOptions {
+    variant?: SchemeVariant;
+    contrastLevel?: ContrastLevel;
+}
+/**
+ * Generate a complete MD3 Expressive color scheme from a seed hex string.
+ *
+ * Uses Material Color Utilities v0.4.0 with SpecVersion 2025 by default.
+ *
+ * @param sourceColorHex - Seed color in hex format (e.g. `"#6750A4"`).
+ * @param mode - Light or dark scheme. Defaults to `"light"`.
+ * @param options - Optional variant + contrast overrides.
+ *   - `variant` — defaults to `"expressive"` (MD3 Expressive 2025)
+ *   - `contrastLevel` — defaults to `0` (standard)
+ *
+ * @example
+ * // Backward-compatible call (no options required)
+ * generateM3Theme("#6750A4")
+ *
+ * @example
+ * // Expressive with high contrast
+ * generateM3Theme("#6750A4", "dark", { contrastLevel: 1 })
+ */
+declare function generateM3Theme(sourceColorHex: string, mode?: "light" | "dark", options?: GenerateM3ThemeOptions): MD3ColorScheme;
+/**
+ * Apply an MD3 Expressive dynamic color scheme to the document root as CSS
+ * custom properties.
+ *
+ * Sets `--md-sys-color-*` tokens (used by components) and
+ * `--color-m3-*` tokens (used by Tailwind). Also sets the `data-theme`
+ * attribute for dark mode CSS selectors.
+ *
+ * @param sourceColorHex - Seed color hex string.
+ * @param mode - Light/dark/system mode. Defaults to `"light"`.
+ * @param root - Target element. Defaults to `document.documentElement`.
+ * @param options - Optional variant + contrast overrides.
+ */
+declare function applyTheme(sourceColorHex: string, mode?: ThemeMode, root?: HTMLElement, options?: GenerateM3ThemeOptions): void;
+
+/**
+ * MaterialSymbolsPreconnect
+ *
+ * Injects preconnect resource hints for Google Fonts CDN into <head>.
+ * Place this component AS EARLY AS POSSIBLE in the app tree, ideally
+ * directly inside <head> or root layout.
+ *
+ * WHY THIS MATTERS:
+ * If @import url() is inside a CSS file, browser must:
+ * 1. Parse HTML -> download JS bundle -> execute CSS -> hit @import -> start Google Fonts connection
+ * Preconnect hints allow browser to establish TCP handshake + TLS connection early at step 1,
+ * saving 100-500ms connection latency depending on network.
+ *
+ * USAGE:
+ * ```tsx
+ * // app/layout.tsx (Next.js) or index.html equivalent
+ * import { MaterialSymbolsPreconnect } from '@bug-on/m3-expressive';
+ *
+ * export default function RootLayout({ children }) {
+ *   return (
+ *     <html>
+ *       <head>
+ *         <MaterialSymbolsPreconnect />
+ *       </head>
+ *       <body>{children}</body>
+ *     </html>
+ *   );
+ * }
+ * ```
+ *
+ * NOTE: Use this component only with CDN mode.
+ * Self-hosted fonts do not require preconnecting to external origins.
+ */
+interface MaterialSymbolsPreconnectProps {
+    /**
+     * Array of Material Symbols font variants to load.
+     * Include only variants used by application to minimize bandwidth.
+     * @default ["outlined"]
+     */
+    variants?: Array<"outlined" | "rounded" | "sharp">;
+}
+declare function MaterialSymbolsPreconnect({ variants, }: MaterialSymbolsPreconnectProps): react_jsx_runtime.JSX.Element;
+
+declare function cn(...inputs: ClassValue[]): string;
+
+/**
+ * Props cho component {@link Icon}.
+ *
+ * All variable font axes are mapped directly to `font-variation-settings`.
+ */
+interface IconProps extends React$1.HTMLAttributes<HTMLSpanElement> {
+    /**
+     * Name of the Material Symbol in snake_case format.
+     * @example "home", "arrow_forward", "settings"
+     * @see https://fonts.google.com/icons
+     */
+    name: string;
+    /**
+     * Geometric style variant — maps to font family.
+     * @default "outlined"
+     */
+    variant?: "outlined" | "rounded" | "sharp";
+    /**
+     * `FILL` axis. `0` = outlined, `1` = filled.
+     * Features spring animation when `animateFill` is true.
+     * @default 0
+     */
+    fill?: 0 | 1;
+    /**
+     * `wght` axis — stroke weight. Should match surrounding text weight.
+     * @default 400
+     */
+    weight?: 100 | 200 | 300 | 400 | 500 | 600 | 700;
+    /**
+     * `GRAD` axis — fine-tunes visual weight without affecting layout dimensions.
+     * Use `-25` on dark backgrounds to offset light halation effects.
+     * @default 0
+     */
+    grade?: -50 | -25 | 0 | 100 | 200;
+    /**
+     * `opsz` axis — optical size in dp. Used to set `font-size` if `size` is not specified.
+     * Match rendered pixel size for best quality.
+     * @default 24
+     */
+    opticalSize?: 20 | 24 | 40 | 48;
+    /**
+     * Direct `font-size` override in px. `opsz` axis still respects `opticalSize`.
+     * @example size={18} opticalSize={20}
+     */
+    size?: number | "inherit";
+    /**
+     * Enables smooth spring animation when toggling FILL axis (uses `SPRING_TRANSITION_FAST`).
+     * Requires `motion` dependency.
+     * @default false
+     * @example <Icon name="favorite" fill={isLiked ? 1 : 0} animateFill />
+     */
+    animateFill?: boolean;
+}
+/**
+ * Material Symbols (variable font) Icon component.
+ *
+ * Make sure to import the icon font CSS before usage:
+ * ```ts
+ * import '@bug-on/m3-expressive/material-symbols-cdn.css';
+ * ```
+ *
+ * @remarks
+ * - Use snake_case for icon names: `"arrow_forward"`, NOT `"ArrowForward"`.
+ * - `aria-hidden="true"` is attached automatically — provide screen reader labels on parent elements.
+ *
+ * @example
+ * ```tsx
+ * // Basic Icon
+ * <Icon name="home" />
+ *
+ * // Visual customization (filled, heavy weight)
+ * <Icon name="favorite" variant="rounded" fill={1} weight={300} />
+ *
+ * // Animated transition on state change
+ * <Icon name="bookmark" fill={saved ? 1 : 0} animateFill />
+ *
+ * // Custom size override
+ * <Icon name="close" size={18} opticalSize={20} />
+ *
+ * // Combination with other components
+ * <Button icon={<Icon name="add" />}>Add to cart</Button>
+ * ```
+ *
+ * @see https://fonts.google.com/icons
+ * @see https://m3.material.io/styles/icons/overview
+ */
+declare const Icon: React$1.NamedExoticComponent<IconProps & React$1.RefAttributes<HTMLSpanElement>>;
+
+/**
+ * Represents a single ripple wave instance with position and size metadata.
+ *
+ * @example
+ * ```tsx
+ * const ripple: RippleOrigin = { id: Date.now(), x: 50, y: 30, size: 200 };
+ * ```
+ */
+interface RippleOrigin {
+    /** Unique identifier used as React key and for removal. */
+    id: number;
+    /** X coordinate of the pointer event relative to the container's left edge (px). */
+    x: number;
+    /** Y coordinate of the pointer event relative to the container's top edge (px). */
+    y: number;
+    /**
+     * Diameter of the ripple circle (px).
+     * Typically `Math.hypot(width, height) * 2` to ensure it fills the container.
+     */
+    size: number;
+}
+/**
+ * Props for the `Ripple` presentation component.
+ */
+interface RippleProps {
+    /** Active ripple instances to render. Managed by the parent via `useRipple`. */
+    ripples: RippleOrigin[];
+    /** Called when a ripple's exit animation completes — remove it from state. */
+    onRippleDone: (id: number) => void;
+    /**
+     * Completely disables the ripple effect.
+     * Use this when the parent element is disabled or interaction is not desired.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * When `true`, the ripple respects the user's OS-level
+     * `prefers-reduced-motion` accessibility setting and renders nothing if active.
+     *
+     * Set to `false` to always show ripples regardless of system preference.
+     * @default true
+     */
+    respectSystemMotion?: boolean;
+}
+/**
+ * MD3 Expressive Ripple — animated touch-feedback wave layer.
+ *
+ * Renders absolutely-positioned ripple circles inside an `overflow-hidden`
+ * container. Must be placed as a direct child of the interactive element.
+ *
+ * @remarks
+ * - The parent element **must** have `overflow: hidden` and `position: relative`
+ *   (or equivalent) for clipping to work correctly.
+ * - Set `disabled` to `true` on parent's disabled state to avoid stale ripples.
+ * - The ripple color is `currentColor` at 12% opacity — matching MD3 state layer spec.
+ *
+ * @example
+ * ```tsx
+ * const { ripples, onPointerDown, removeRipple } = useRippleState();
+ *
+ * <button onPointerDown={onPointerDown} className="relative overflow-hidden">
+ *   <Ripple ripples={ripples} onRippleDone={removeRipple} />
+ *   Click me
+ * </button>
+ * ```
+ *
+ * @see {@link useRippleState} for the state management hook
+ * @see https://m3.material.io/foundations/interaction/states/overview
+ */
+declare function Ripple({ ripples, onRippleDone, disabled, respectSystemMotion, }: RippleProps): react_jsx_runtime.JSX.Element | null;
+/**
+ * Options for configuring `useRippleState` behaviour.
+ */
+interface UseRippleStateOptions {
+    /**
+     * When `true`, the ripple is suppressed — `onPointerDown` becomes a no-op.
+     * Use this to sync the ripple with the parent element's `disabled` state.
+     * @default false
+     */
+    disabled?: boolean;
+}
+/**
+ * `useRippleState` — state manager for MD3 Expressive ripple waves.
+ *
+ * Tracks active ripple instances and provides pointer event handlers.
+ * Pair with the `<Ripple>` component for rendering.
+ *
+ * @remarks
+ * This hook only manages ripple *state* (coordinates, size, lifecycle).
+ * The actual animation is handled by `<Ripple>` via Framer Motion.
+ * Respecting `prefers-reduced-motion` is handled by `<Ripple>` itself.
+ *
+ * @param options - Configuration options. See {@link UseRippleStateOptions}.
+ * @returns `{ ripples, onPointerDown, removeRipple }` — bind to the interactive element.
+ *
+ * @example
+ * ```tsx
+ * function MyButton({ disabled, children }) {
+ *   const { ripples, onPointerDown, removeRipple } = useRippleState({ disabled });
+ *
+ *   return (
+ *     <button
+ *       disabled={disabled}
+ *       onPointerDown={onPointerDown}
+ *       className="relative overflow-hidden"
+ *     >
+ *       <Ripple ripples={ripples} onRippleDone={removeRipple} disabled={disabled} />
+ *       {children}
+ *     </button>
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link Ripple} for the rendering component
+ */
+declare function useRippleState(options?: UseRippleStateOptions): {
+    ripples: RippleOrigin[];
+    onPointerDown: (e: React$1.PointerEvent<HTMLElement>) => void;
+    removeRipple: (id: number) => void;
+};
+/**
+ * @deprecated Use `useRippleState` instead. This alias will be removed in a future version.
+ * @see {@link useRippleState}
+ */
+declare const useRipple: typeof useRippleState;
+
+interface ThemeContextValue {
+    sourceColor: string;
+    setSourceColor: (color: string) => void;
+    mode: ThemeMode;
+    setMode: (mode: ThemeMode) => void;
+    /** The resolved color scheme actually applied — always "light" or "dark". */
+    effectiveMode: "light" | "dark";
+    /** Active color scheme variant. */
+    variant: SchemeVariant;
+    /** Active contrast level. */
+    contrastLevel: ContrastLevel;
+}
+interface MD3ThemeProviderProps {
+    children: ReactNode;
+    sourceColor?: string;
+    defaultMode?: ThemeMode;
+    persistToLocalStorage?: boolean;
+    /**
+     * Color scheme variant controlling hue and chroma behaviour.
+     * - `"expressive"` — MD3 Expressive 2025 (high-chroma, detached from seed). **Default.**
+     * - `"tonal_spot"` — Standard Android 12+ theme.
+     * - `"vibrant"` | `"fidelity"` | `"content"` | `"monochrome"` | `"neutral"`
+     * @default "expressive"
+     */
+    variant?: SchemeVariant;
+    /**
+     * Contrast level for the generated scheme.
+     * - `0` — Standard (default)
+     * - `0.5` — Medium contrast
+     * - `1` — Maximum contrast (WCAG AAA)
+     * @default 0
+     */
+    contrastLevel?: ContrastLevel;
+    /**
+     * 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;
+}
+declare function MD3ThemeProvider({ children, sourceColor: initialSourceColor, defaultMode, persistToLocalStorage, variant, contrastLevel, typography: typographyProp, fontFamily, fontVariationAxes, enableSnackbar, }: MD3ThemeProviderProps): react_jsx_runtime.JSX.Element;
+declare function useTheme(): ThemeContextValue;
+declare function useThemeMode(): Pick<ThemeContextValue, "mode" | "setMode" | "effectiveMode">;
+
+export { type ContrastLevel as C, type GenerateM3ThemeOptions as G, Icon as I, type MD3ColorScheme as M, Ripple as R, type SchemeVariant as S, type ThemeMode as T, type UseRippleStateOptions as U, type IconProps as a, MD3ThemeProvider as b, type MD3ThemeProviderProps as c, MaterialSymbolsPreconnect as d, type RippleOrigin as e, type RippleProps as f, applyTheme as g, cn as h, generateM3Theme as i, useMediaQuery as j, useRipple as k, useRippleState as l, useTheme as m, useThemeMode as n, resolveMode as r, useRipple$1 as u };