npm - @bug-on/m3-expressive - Versions diffs - 1.0.0 - Mend

@bug-on/m3-expressive 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (98) hide show

package/CHANGELOG.md +110 -0
package/README.md +110 -0
package/dist/assets/fonts/GoogleSansFlex-VariableFont.woff2 +0 -0
package/dist/assets/fonts/MaterialSymbolsOutlined-VariableFont_FILL,GRAD,opsz,wght.ttf +0 -0
package/dist/assets/fonts/MaterialSymbolsRounded-VariableFont_FILL,GRAD,opsz,wght.ttf +0 -0
package/dist/assets/fonts/MaterialSymbolsSharp-VariableFont_FILL,GRAD,opsz,wght.ttf +0 -0
package/dist/assets/loading-indicator.svg +19 -0
package/dist/assets/material-symbols-cdn.css +65 -0
package/dist/assets/material-symbols-self-hosted.css +94 -0
package/dist/buttons.d.mts +180 -0
package/dist/buttons.d.ts +180 -0
package/dist/buttons.js +4282 -0
package/dist/buttons.js.map +1 -0
package/dist/buttons.mjs +4227 -0
package/dist/buttons.mjs.map +1 -0
package/dist/core.d.mts +422 -0
package/dist/core.d.ts +422 -0
package/dist/core.js +2581 -0
package/dist/core.js.map +1 -0
package/dist/core.mjs +2547 -0
package/dist/core.mjs.map +1 -0
package/dist/feedback.d.mts +600 -0
package/dist/feedback.d.ts +600 -0
package/dist/feedback.js +2357 -0
package/dist/feedback.js.map +1 -0
package/dist/feedback.mjs +2321 -0
package/dist/feedback.mjs.map +1 -0
package/dist/forms.d.mts +40 -0
package/dist/forms.d.ts +40 -0
package/dist/forms.js +4263 -0
package/dist/forms.js.map +1 -0
package/dist/forms.mjs +4228 -0
package/dist/forms.mjs.map +1 -0
package/dist/icon-button-D-gs0gfj.d.mts +136 -0
package/dist/icon-button-D-gs0gfj.d.ts +136 -0
package/dist/index.css +309 -0
package/dist/index.css.d.ts +2 -0
package/dist/index.d.mts +24 -0
package/dist/index.d.ts +24 -0
package/dist/index.js +23972 -0
package/dist/index.js.map +1 -0
package/dist/index.mjs +23668 -0
package/dist/index.mjs.map +1 -0
package/dist/layout.d.mts +610 -0
package/dist/layout.d.ts +610 -0
package/dist/layout.js +5091 -0
package/dist/layout.js.map +1 -0
package/dist/layout.mjs +5042 -0
package/dist/layout.mjs.map +1 -0
package/dist/material-symbols-cdn.css +65 -0
package/dist/material-symbols-cdn.css.d.ts +2 -0
package/dist/material-symbols-self-hosted.css +94 -0
package/dist/material-symbols-self-hosted.css.d.ts +2 -0
package/dist/md3-DFhj-NZj.d.mts +17 -0
package/dist/md3-DFhj-NZj.d.ts +17 -0
package/dist/navigation.d.mts +2766 -0
package/dist/navigation.d.ts +2766 -0
package/dist/navigation.js +6684 -0
package/dist/navigation.js.map +1 -0
package/dist/navigation.mjs +6573 -0
package/dist/navigation.mjs.map +1 -0
package/dist/overlays.d.mts +161 -0
package/dist/overlays.d.ts +161 -0
package/dist/overlays.js +3298 -0
package/dist/overlays.js.map +1 -0
package/dist/overlays.mjs +3244 -0
package/dist/overlays.mjs.map +1 -0
package/dist/pickers.d.mts +1074 -0
package/dist/pickers.d.ts +1074 -0
package/dist/pickers.js +4240 -0
package/dist/pickers.js.map +1 -0
package/dist/pickers.mjs +4200 -0
package/dist/pickers.mjs.map +1 -0
package/dist/plugin.d.mts +1 -0
package/dist/plugin.d.ts +1 -0
package/dist/plugin.js +13 -0
package/dist/plugin.js.map +1 -0
package/dist/plugin.mjs +3 -0
package/dist/plugin.mjs.map +1 -0
package/dist/scroll-area-CVS6HyLl.d.mts +33 -0
package/dist/scroll-area-CVS6HyLl.d.ts +33 -0
package/dist/shapes.d.mts +1119 -0
package/dist/shapes.d.ts +1119 -0
package/dist/shapes.js +2941 -0
package/dist/shapes.js.map +1 -0
package/dist/shapes.mjs +2889 -0
package/dist/shapes.mjs.map +1 -0
package/dist/side-sheet-modal-BY6VCC8p.d.mts +553 -0
package/dist/side-sheet-modal-CglP6KYA.d.ts +553 -0
package/dist/split-button-trailing-uncheckable-C5CLCIKP.d.ts +731 -0
package/dist/split-button-trailing-uncheckable-MXj_kyNt.d.mts +731 -0
package/dist/text-field-eAIpz9z1.d.mts +1038 -0
package/dist/text-field-eAIpz9z1.d.ts +1038 -0
package/dist/typography-339RV6v7.d.mts +486 -0
package/dist/typography-339RV6v7.d.ts +486 -0
package/dist/typography.css +22 -0
package/dist/typography.css.d.ts +2 -0
package/package.json +207 -0

package/dist/core.d.ts ADDED Viewed

@@ -0,0 +1,422 @@
+import * as React$1 from 'react';
+import { ReactNode } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ClassValue } from 'clsx';
+export { M as MD3ColorStyle, a as MD3Shape, b as MD3Size, P as PolymorphicProps, c as PolymorphicRef } from './md3-DFhj-NZj.js';
+import { a as Typography, F as FontVariationAxes } from './typography-339RV6v7.js';
+/**
+ * useMediaQuery — Responsive hook chuẩn SSR-safe
+ *
+ * Tránh hydration mismatch bằng cách khởi tạo với `false`.
+ *
+ * @example
+ * ```tsx
+ * const isMobile = useMediaQuery('(max-width: 768px)');
+ * ```
+ */
+declare function useMediaQuery(query: string): boolean;
+interface RippleOptions {
+    /** Thời gian hiệu ứng ripple (ms). Mặc định: 600 */
+    duration?: number;
+    /** Màu ripple. Mặc định: 'currentColor' */
+    color?: string;
+    /** Opacity. Mặc định: 0.12 (chuẩn MD3) */
+    opacity?: number;
+    /** Tắt ripple (ví dụ khi disabled) */
+    disabled?: boolean;
+}
+/**
+ * useRipple — Material Design 3 Expressive Ripple Effect
+ *
+ * Hook thuần DOM, không phụ thuộc thư viện animation ngoài.
+ * Chú ý: Yêu cầu element có `position: relative` và `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;
+};
+/**
+ * MaterialSymbolsPreconnect
+ *
+ * Inject preconnect resource hints cho Google Fonts CDN và <head>.
+ * Đặt component này CÀNG SỚM CÀNG TỐT trong app tree, lý tưởng là
+ * ngay trong <head> hoặc root layout.
+ *
+ * WHY THIS MATTERS:
+ * Nếu @import url() nằm trong CSS file, browser phải:
+ * 1. Parse HTML -> download JS bundle -> execute CSS -> gặp @import -> mới bắt đầu connect Google Fonts
+ * Preconnect hints cho phép browser bắt đầu TCP handshake + TLS ngay từ bước 1,
+ * tiết kiệm 100-500ms connection time tùy network.
+ *
+ * USAGE:
+ * ```tsx
+ * // app/layout.tsx (Next.js) hoặc 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: Chỉ dùng component này với CDN mode.
+ * Với self-hosted fonts thì không cần preconnect đến external origin.
+ */
+interface MaterialSymbolsPreconnectProps {
+    /**
+     * Mảng các biến thể font Material Symbols cần tải.
+     * Chỉ nên chọn các biến thể mà ứng dụng thực sự sử dụng để tiết kiệm băng thông.
+     * @default ["outlined"]
+     */
+    variants?: Array<"outlined" | "rounded" | "sharp">;
+}
+declare function MaterialSymbolsPreconnect({ variants, }: MaterialSymbolsPreconnectProps): react_jsx_runtime.JSX.Element;
+type ThemeMode = "light" | "dark" | "system";
+/**
+ * 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;
+    secondary: string;
+    onSecondary: string;
+    secondaryContainer: string;
+    onSecondaryContainer: string;
+    secondaryFixed: string;
+    secondaryFixedDim: string;
+    onSecondaryFixed: string;
+    onSecondaryFixedVariant: string;
+    tertiary: string;
+    onTertiary: string;
+    tertiaryContainer: string;
+    onTertiaryContainer: string;
+    tertiaryFixed: string;
+    tertiaryFixedDim: string;
+    onTertiaryFixed: string;
+    onTertiaryFixedVariant: string;
+    error: string;
+    onError: string;
+    errorContainer: string;
+    onErrorContainer: string;
+    surface: string;
+    onSurface: string;
+    surfaceVariant: string;
+    onSurfaceVariant: string;
+    surfaceTint: 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;
+}
+/**
+ * Generate a complete MD3 color scheme from a source color hex string.
+ * Uses the HCT color space algorithm — same as Material You on Android.
+ */
+declare function generateM3Theme(sourceColorHex: string, mode?: "light" | "dark"): MD3ColorScheme;
+/**
+ * Apply an MD3 dynamic color scheme to the document root as CSS custom properties.
+ * Sets both `--md-sys-color-*` tokens (used by components) and
+ * `--color-m3-*` tokens (used by Tailwind arbitrary values in apps).
+ *
+ * Also sets `data-theme` attribute for dark mode CSS selectors.
+ */
+declare function applyTheme(sourceColorHex: string, mode?: ThemeMode, root?: HTMLElement): void;
+declare function cn(...inputs: ClassValue[]): string;
+/**
+ * Props cho component {@link Icon}.
+ *
+ * Tất cả các trục biến thiên (variable font axes) được map trực tiếp sang `font-variation-settings`.
+ */
+interface IconProps extends React$1.HTMLAttributes<HTMLSpanElement> {
+    /**
+     * Tên của Material Symbol theo định dạng snake_case.
+     * @example "home", "arrow_forward", "settings"
+     * @see https://fonts.google.com/icons
+     */
+    name: string;
+    /**
+     * Kiểu hình học (Geometric style variant) — tương ứng với font family được tải.
+     * @default "outlined"
+     */
+    variant?: "outlined" | "rounded" | "sharp";
+    /**
+     * Trục FILL. `0` = outlined (viền), `1` = filled (tràn màu).
+     * Có hiệu ứng spring khi `animateFill` là true.
+     * @default 0
+     */
+    fill?: 0 | 1;
+    /**
+     * Trục wght — độ dày của nét (stroke weight). Nên khớp với độ dày text xung quanh.
+     * @default 400
+     */
+    weight?: 100 | 200 | 300 | 400 | 500 | 600 | 700;
+    /**
+     * Trục GRAD — tinh chỉnh độ dày thị giác mà không ảnh hưởng tới layout.
+     * Dùng mức `-25` trên nền tối để bù trừ hiệu ứng phát sáng (halation).
+     * @default 0
+     */
+    grade?: -50 | -25 | 0 | 100 | 200;
+    /**
+     * Trục opsz — kích thước quang học (optical size) tính bằng dp. Dùng để thiết lập `font-size` nếu không truyền `size`.
+     * Hãy để giá trị khớp với pixel sẽ render ra để thấy chất lượng tốt nhất.
+     * @default 24
+     */
+    opticalSize?: 20 | 24 | 40 | 48;
+    /**
+     * Ghi đè trực tiếp `font-size` bằng px. Trục `opsz` vẫn sẽ tuân theo thuộc tính `opticalSize`.
+     * @example size={18} opticalSize={20}
+     */
+    size?: number | "inherit";
+    /**
+     * Kích hoạt hiệu ứng spring mượt mà khi chuyển đổi giá trị FILL (sử dụng cấu hình `SPRING_TRANSITION_FAST`).
+     * Yêu cầu dependency `motion/react`.
+     * @default false
+     * @example <Icon name="favorite" fill={isLiked ? 1 : 0} animateFill />
+     */
+    animateFill?: boolean;
+}
+/**
+ * Component hiển thị Icon bằng Material Symbols (variable font).
+ *
+ * Hãy đảm bảo đã import CSS chứa font trước khi dùng:
+ * ```ts
+ * import '@bug-on/m3-expressive/material-symbols.css';
+ * ```
+ *
+ * @remarks
+ * - Đặt tên icon dùng snake_case: `"arrow_forward"`, KHÔNG PHẢI `"ArrowForward"`.
+ * - Thuộc tính `aria-hidden="true"` được tự động thêm vào — bạn cần thêm label đọc bằng giọng nói (accessible labels) ở phần tử cha.
+ *
+ * @example
+ * ```tsx
+ * // Icon cơ bản
+ * <Icon name="home" />
+ *
+ * // Tùy chỉnh trực quan (filled, nét dày)
+ * <Icon name="favorite" variant="rounded" fill={1} weight={300} />
+ *
+ * // Animate khi trạng thái thay đổi
+ * <Icon name="bookmark" fill={saved ? 1 : 0} animateFill />
+ *
+ * // Đổi kích thước icon cụ thể
+ * <Icon name="close" size={18} opticalSize={20} />
+ *
+ * // Kết hợp với các component khác
+ * <Button icon={<Icon name="add" />}>Thêm vào giỏ</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";
+}
+interface MD3ThemeProviderProps {
+    children: ReactNode;
+    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;
+}
+declare function MD3ThemeProvider({ children, sourceColor: initialSourceColor, defaultMode, persistToLocalStorage, typography: typographyProp, fontFamily, fontVariationAxes, enableSnackbar, }: MD3ThemeProviderProps): react_jsx_runtime.JSX.Element;
+declare function useTheme(): ThemeContextValue;
+declare function useThemeMode(): Pick<ThemeContextValue, "mode" | "setMode" | "effectiveMode">;
+export { Icon, type IconProps, type MD3ColorScheme, MD3ThemeProvider, type MD3ThemeProviderProps, MaterialSymbolsPreconnect, Ripple, type RippleOrigin, type RippleProps, type ThemeMode, type UseRippleStateOptions, applyTheme, cn, generateM3Theme, resolveMode, useRipple$1 as useDOMRipple, useMediaQuery, useRipple, useRippleState, useTheme, useThemeMode };