@bug-on/md3-react 0.1.0

package/dist/ui/typography/typography-tokens.d.ts

@@ -0,0 +1,220 @@
+/**
+ * @file typography-tokens.ts
+ * @description MD3 Expressive Typography Token Definitions.
+ *
+ * Port of `androidx.compose.material3.tokens.TypographyTokens` (Kotlin class).
+ *
+ * ### Memory Optimization
+ * All 30 `TextStyle` properties are implemented as **lazy getters** — they are
+ * computed on first access and cached, rather than being computed eagerly at
+ * construction time. This reduces the instantiation cost of `TypographyTokens`.
+ *
+ * ### Variable Font Axes
+ * Supports customizable CSS `font-variation-settings` via {@link FontVariationAxes}.
+ * - Default `ROND` value is `100` (maximum roundness of Google Sans Flex).
+ * - Other axes remain at font defaults unless explicitly overridden.
+ *
+ * @example Basic usage (default tokens)
+ * ```ts
+ * const tokens = new TypographyTokens();
+ * const style = tokens.BodyLarge; // { fontSize, fontWeight, ... }
+ * ```
+ *
+ * @example Custom font family
+ * ```ts
+ * const tokens = new TypographyTokens({ fontFamily: "'Inter', sans-serif" });
+ * ```
+ *
+ * @example Custom ROND axis (partial roundness)
+ * ```ts
+ * const tokens = new TypographyTokens({ fontVariationAxes: { ROND: 50 } });
+ * ```
+ */
+/**
+ * Configurable axes for CSS `font-variation-settings`.
+ *
+ * Each key maps to a named variable font axis. Any axis not specified falls
+ * back to the font's own default value.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/CSS/font-variation-settings
+ *
+ * @example
+ * ```ts
+ * const axes: FontVariationAxes = { ROND: 100, wght: 600 };
+ * ```
+ */
+export interface FontVariationAxes {
+    /**
+     * Roundness axis of Google Sans Flex Variable Font.
+     * Range: `0` (sharp corners) – `100` (fully rounded).
+     * @default 100
+     */
+    ROND?: number;
+    /**
+     * Weight axis. Overrides `font-weight` via variation settings.
+     * @default font default
+     */
+    wght?: number;
+    /**
+     * Width axis. Controls glyph condensation/expansion.
+     * @default font default
+     */
+    wdth?: number;
+    /** Any additional named variation axis supported by the font. */
+    [axis: string]: number | undefined;
+}
+/**
+ * Default font variation axes for MD3 Expressive.
+ * Sets `ROND` to `100` for maximum roundness; all other axes use font defaults.
+ */
+export declare const DEFAULT_FONT_VARIATION_AXES: Readonly<FontVariationAxes>;
+/**
+ * Serializes a {@link FontVariationAxes} map into a CSS `font-variation-settings` string.
+ *
+ * @example
+ * ```ts
+ * serializeFontVariationAxes({ ROND: 100, wght: 700 });
+ * // → '"ROND" 100, "wght" 700'
+ * ```
+ */
+export declare function serializeFontVariationAxes(axes: FontVariationAxes): string;
+/**
+ * Pre-computed default `font-variation-settings` string.
+ * Equivalent to `'"ROND" 100'`.
+ */
+export declare const MD3_EXPRESSIVE_FONT_VARIATION: string;
+/**
+ * Web equivalent of Compose's `TextStyle`.
+ *
+ * All properties are readonly and map directly to CSS font properties.
+ * The `fontVariationSettings` field carries the serialized variable-font axes.
+ */
+export interface TextStyle {
+    /** CSS `font-family` value. */
+    readonly fontFamily: string;
+    /** CSS `font-weight` numeric value (e.g. `400`, `700`). */
+    readonly fontWeight: number;
+    /** CSS `font-size` in `rem` units. */
+    readonly fontSize: string;
+    /** CSS `line-height` in `rem` units. */
+    readonly lineHeight: string;
+    /** CSS `letter-spacing` in `px` units. */
+    readonly letterSpacing: string;
+    /**
+     * CSS `font-variation-settings` string.
+     * @example '"ROND" 100'
+     * @example '"ROND" 50, "wght" 600'
+     */
+    readonly fontVariationSettings: string;
+}
+/**
+ * Constructor options for {@link TypographyTokens}.
+ */
+export interface TypographyTokensOptions {
+    /**
+     * Custom CSS `font-family` string. When provided, overrides the default
+     * Google Sans Flex font for all token styles.
+     *
+     * @example "'Roboto', sans-serif"
+     */
+    fontFamily?: string;
+    /**
+     * Variable font axes to apply via `font-variation-settings`.
+     * Merged on top of {@link DEFAULT_FONT_VARIATION_AXES}.
+     * Provide only the axes you want to override.
+     *
+     * @example { ROND: 0 } // sharp corners
+     */
+    fontVariationAxes?: FontVariationAxes;
+}
+/**
+ * MD3 Expressive Typography Token class.
+ *
+ * Port of `internal class TypographyTokens(val fontFamily: FontFamily? = null)`
+ * from `androidx.compose.material3.tokens.TypographyTokens`.
+ *
+ * Provides 30 pre-defined {@link TextStyle} properties (15 baseline + 15 emphasized),
+ * each implemented as a **lazy getter** — computed once on first access, then cached.
+ *
+ * ### Customization
+ * Pass {@link TypographyTokensOptions} to the constructor to override:
+ * - `fontFamily` — swap the typeface
+ * - `fontVariationAxes` — control variable font axes (e.g., `ROND`)
+ *
+ * @example Default
+ * ```ts
+ * const tokens = new TypographyTokens();
+ * ```
+ *
+ * @example Custom font + half-rounded
+ * ```ts
+ * const tokens = new TypographyTokens({
+ *   fontFamily: "'Inter', sans-serif",
+ *   fontVariationAxes: { ROND: 50 },
+ * });
+ * ```
+ */
+export declare class TypographyTokens {
+    #private;
+    constructor(options?: TypographyTokensOptions | string);
+    /** Display Large – `57px`, weight 400 */
+    get DisplayLarge(): TextStyle;
+    /** Display Medium – `45px`, weight 400 */
+    get DisplayMedium(): TextStyle;
+    /** Display Small – `36px`, weight 400 */
+    get DisplaySmall(): TextStyle;
+    /** Headline Large – `32px`, weight 400 */
+    get HeadlineLarge(): TextStyle;
+    /** Headline Medium – `28px`, weight 400 */
+    get HeadlineMedium(): TextStyle;
+    /** Headline Small – `24px`, weight 400 */
+    get HeadlineSmall(): TextStyle;
+    /** Title Large – `22px`, weight 400 */
+    get TitleLarge(): TextStyle;
+    /** Title Medium – `16px`, weight 500 */
+    get TitleMedium(): TextStyle;
+    /** Title Small – `14px`, weight 500 */
+    get TitleSmall(): TextStyle;
+    /** Body Large – `16px`, weight 400 */
+    get BodyLarge(): TextStyle;
+    /** Body Medium – `14px`, weight 400 */
+    get BodyMedium(): TextStyle;
+    /** Body Small – `12px`, weight 400 */
+    get BodySmall(): TextStyle;
+    /** Label Large – `14px`, weight 500 */
+    get LabelLarge(): TextStyle;
+    /** Label Medium – `12px`, weight 500 */
+    get LabelMedium(): TextStyle;
+    /** Label Small – `11px`, weight 500 */
+    get LabelSmall(): TextStyle;
+    /** Display Large Emphasized – `57px`, weight 800 */
+    get DisplayLargeEmphasized(): TextStyle;
+    /** Display Medium Emphasized – `45px`, weight 800 */
+    get DisplayMediumEmphasized(): TextStyle;
+    /** Display Small Emphasized – `36px`, weight 800 */
+    get DisplaySmallEmphasized(): TextStyle;
+    /** Headline Large Emphasized – `32px`, weight 800 */
+    get HeadlineLargeEmphasized(): TextStyle;
+    /** Headline Medium Emphasized – `28px`, weight 800 */
+    get HeadlineMediumEmphasized(): TextStyle;
+    /** Headline Small Emphasized – `24px`, weight 800 */
+    get HeadlineSmallEmphasized(): TextStyle;
+    /** Title Large Emphasized – `22px`, weight 700 */
+    get TitleLargeEmphasized(): TextStyle;
+    /** Title Medium Emphasized – `16px`, weight 700 */
+    get TitleMediumEmphasized(): TextStyle;
+    /** Title Small Emphasized – `14px`, weight 700 */
+    get TitleSmallEmphasized(): TextStyle;
+    /** Body Large Emphasized – `16px`, weight 700 */
+    get BodyLargeEmphasized(): TextStyle;
+    /** Body Medium Emphasized – `14px`, weight 700 */
+    get BodyMediumEmphasized(): TextStyle;
+    /** Body Small Emphasized – `12px`, weight 700 */
+    get BodySmallEmphasized(): TextStyle;
+    /** Label Large Emphasized – `14px`, weight 800 */
+    get LabelLargeEmphasized(): TextStyle;
+    /** Label Medium Emphasized – `12px`, weight 800 */
+    get LabelMediumEmphasized(): TextStyle;
+    /** Label Small Emphasized – `11px`, weight 800 */
+    get LabelSmallEmphasized(): TextStyle;
+}

package/dist/ui/typography/typography.d.ts

@@ -0,0 +1,265 @@
+/**
+ * @file typography.tsx
+ * @description MD3 Expressive Typography System for React.
+ *
+ * Port of `androidx.compose.material3.Typography` (Kotlin `@Immutable` class).
+ *
+ * Provides 30 {@link TextStyle} definitions via the React Context API, mirroring
+ * the Compose `LocalTypography` / `MaterialTheme.typography` pattern.
+ *
+ * ### Memory & Performance Optimizations
+ * - The `Typography` class delegates all property access to a `TypographyTokens`
+ *   instance that uses **lazy getters**, so styles are computed only on first use.
+ * - `TypographyProvider` memoizes the context value via `useMemo` to prevent
+ *   unnecessary re-renders downstream.
+ *
+ * @example Wrap your application
+ * ```tsx
+ * <TypographyProvider>
+ *   <App />
+ * </TypographyProvider>
+ * ```
+ *
+ * @example Consume in a component
+ * ```tsx
+ * const typography = useTypography();
+ * <p style={typography.bodyLarge}>Hello</p>
+ * ```
+ *
+ * @example Via token key
+ * ```tsx
+ * const style = typography.fromToken(TypographyKeyTokens.BodyLarge);
+ * ```
+ *
+ * @example Custom font + half-rounded corners
+ * ```tsx
+ * <TypographyProvider
+ *   fontFamily="'Roboto', sans-serif"
+ *   fontVariationAxes={{ ROND: 50 }}
+ * >
+ *   <App />
+ * </TypographyProvider>
+ * ```
+ */
+import { type ReactNode } from "react";
+import { TypographyKeyTokens } from "./typography-key-tokens";
+import { type FontVariationAxes, type TextStyle, TypographyTokens } from "./typography-tokens";
+/**
+ * MD3 Expressive Typography — port of Compose's `@Immutable class Typography(...)`.
+ *
+ * All 30 style properties are **readonly** and lazily resolved from the
+ * underlying {@link TypographyTokens} instance. Use {@link Typography.copy}
+ * to create a customized variant without mutating the original.
+ *
+ * @example Default
+ * ```ts
+ * const typography = new Typography();
+ * const style = typography.displayLarge; // lazy — computed on first access
+ * ```
+ *
+ * @example Custom tokens
+ * ```ts
+ * const typography = new Typography(
+ *   new TypographyTokens({ fontFamily: "'Inter', sans-serif", fontVariationAxes: { ROND: 0 } })
+ * );
+ * ```
+ */
+export declare class Typography {
+    #private;
+    constructor(tokens?: TypographyTokens);
+    /** Display Large text style (`57px`, weight `400`). */
+    get displayLarge(): TextStyle;
+    /** Display Medium text style (`45px`, weight `400`). */
+    get displayMedium(): TextStyle;
+    /** Display Small text style (`36px`, weight `400`). */
+    get displaySmall(): TextStyle;
+    /** Headline Large text style (`32px`, weight `400`). */
+    get headlineLarge(): TextStyle;
+    /** Headline Medium text style (`28px`, weight `400`). */
+    get headlineMedium(): TextStyle;
+    /** Headline Small text style (`24px`, weight `400`). */
+    get headlineSmall(): TextStyle;
+    /** Title Large text style (`22px`, weight `400`). */
+    get titleLarge(): TextStyle;
+    /** Title Medium text style (`16px`, weight `500`). */
+    get titleMedium(): TextStyle;
+    /** Title Small text style (`14px`, weight `500`). */
+    get titleSmall(): TextStyle;
+    /** Body Large text style (`16px`, weight `400`). */
+    get bodyLarge(): TextStyle;
+    /** Body Medium text style (`14px`, weight `400`). */
+    get bodyMedium(): TextStyle;
+    /** Body Small text style (`12px`, weight `400`). */
+    get bodySmall(): TextStyle;
+    /** Label Large text style (`14px`, weight `500`). */
+    get labelLarge(): TextStyle;
+    /** Label Medium text style (`12px`, weight `500`). */
+    get labelMedium(): TextStyle;
+    /** Label Small text style (`11px`, weight `500`). */
+    get labelSmall(): TextStyle;
+    /** Display Large Emphasized text style (`57px`, weight `800`). */
+    get displayLargeEmphasized(): TextStyle;
+    /** Display Medium Emphasized text style (`45px`, weight `800`). */
+    get displayMediumEmphasized(): TextStyle;
+    /** Display Small Emphasized text style (`36px`, weight `800`). */
+    get displaySmallEmphasized(): TextStyle;
+    /** Headline Large Emphasized text style (`32px`, weight `800`). */
+    get headlineLargeEmphasized(): TextStyle;
+    /** Headline Medium Emphasized text style (`28px`, weight `800`). */
+    get headlineMediumEmphasized(): TextStyle;
+    /** Headline Small Emphasized text style (`24px`, weight `800`). */
+    get headlineSmallEmphasized(): TextStyle;
+    /** Title Large Emphasized text style (`22px`, weight `700`). */
+    get titleLargeEmphasized(): TextStyle;
+    /** Title Medium Emphasized text style (`16px`, weight `700`). */
+    get titleMediumEmphasized(): TextStyle;
+    /** Title Small Emphasized text style (`14px`, weight `700`). */
+    get titleSmallEmphasized(): TextStyle;
+    /** Body Large Emphasized text style (`16px`, weight `700`). */
+    get bodyLargeEmphasized(): TextStyle;
+    /** Body Medium Emphasized text style (`14px`, weight `700`). */
+    get bodyMediumEmphasized(): TextStyle;
+    /** Body Small Emphasized text style (`12px`, weight `700`). */
+    get bodySmallEmphasized(): TextStyle;
+    /** Label Large Emphasized text style (`14px`, weight `800`). */
+    get labelLargeEmphasized(): TextStyle;
+    /** Label Medium Emphasized text style (`12px`, weight `800`). */
+    get labelMediumEmphasized(): TextStyle;
+    /** Label Small Emphasized text style (`11px`, weight `800`). */
+    get labelSmallEmphasized(): TextStyle;
+    /**
+     * Returns the `TextStyle` corresponding to the given {@link TypographyKeyTokens}.
+     *
+     * Port of `internal fun Typography.fromToken(value: TypographyKeyTokens): TextStyle`.
+     *
+     * @example
+     * ```ts
+     * const style = typography.fromToken(TypographyKeyTokens.BodyLarge);
+     * ```
+     */
+    fromToken(value: TypographyKeyTokens): TextStyle;
+    /**
+     * Creates a new `Typography` instance with the specified property overrides
+     * merged on top of the current instance's styles.
+     *
+     * Port of Compose's `fun Typography.copy(...)`.
+     *
+     * Unlike a shallow `Object.assign`, this method preserves the lazy-getter
+     * architecture — overridden styles are stored separately and looked up first
+     * on each property access, while non-overridden styles continue to be
+     * resolved from the underlying {@link TypographyTokens}.
+     *
+     * @param overrides - Map of camelCase property names to partial `TextStyle` overrides.
+     * @returns A new `Typography` instance. The original is never mutated.
+     *
+     * @example
+     * ```ts
+     * const custom = typography.copy({ bodyLarge: { fontSize: "2rem" } });
+     * custom.bodyLarge.fontSize; // "2rem"
+     * custom.bodySmall.fontSize; // original token value — untouched
+     * ```
+     */
+    copy(overrides: Partial<Record<TypographyStyleKey, Partial<TextStyle>>>): Typography;
+}
+/**
+ * Union of all camelCase property names on {@link Typography} that return a
+ * {@link TextStyle}. Used as the key type for `copy()` overrides and the
+ * `OverriddenTypography` resolver.
+ */
+type TypographyStyleKey = {
+    [K in keyof Typography]: Typography[K] extends TextStyle ? K : never;
+}[keyof Typography];
+/**
+ * React context that holds the current {@link Typography} instance.
+ *
+ * Port of `internal val LocalTypography = staticCompositionLocalOf { Typography() }`.
+ *
+ * @internal — Prefer {@link useTypography} and {@link TypographyProvider}.
+ */
+export declare const TypographyContext: import("react").Context<Typography>;
+/**
+ * React hook to access the current {@link Typography} from the nearest
+ * {@link TypographyProvider} in the tree. Falls back to the default
+ * googleapis Typography when no provider is present.
+ *
+ * @returns The current `Typography` instance.
+ *
+ * @example
+ * ```tsx
+ * const typography = useTypography();
+ * <p style={typography.bodyLarge}>Hello</p>
+ * ```
+ */
+export declare function useTypography(): Typography;
+/**
+ * Props for {@link TypographyProvider}.
+ */
+export interface TypographyProviderProps {
+    /** The child tree that will have access to the provided typography. */
+    children: ReactNode;
+    /**
+     * A fully custom {@link Typography} instance.
+     * When provided, `fontFamily` and `fontVariationAxes` are ignored.
+     */
+    typography?: Typography;
+    /**
+     * Shorthand to override the CSS `font-family` for all typography styles.
+     * Ignored when `typography` is provided.
+     *
+     * @example "'Roboto', sans-serif"
+     */
+    fontFamily?: string;
+    /**
+     * Variable font axes to apply globally via `font-variation-settings`.
+     * Merged on top of the defaults (`ROND: 100`). Only the axes you specify
+     * will be overridden; unspecified axes retain font defaults.
+     * Ignored when `typography` is provided.
+     *
+     * @example { ROND: 50 }  // half-rounded
+     * @example { ROND: 0 }   // sharp corners
+     */
+    fontVariationAxes?: FontVariationAxes;
+}
+/**
+ * Typography Provider component.
+ *
+ * Port of `CompositionLocalProvider(LocalTypography provides typography)`.
+ * Wrap your application (or a subtree) to provide MD3 Expressive typography
+ * to all descendant components that call {@link useTypography}.
+ *
+ * The context value is **memoized** — it is only re-computed when `typography`,
+ * `fontFamily`, or `fontVariationAxes` change, preventing unnecessary re-renders.
+ *
+ * @example Default (Google Sans Flex, ROND = 100)
+ * ```tsx
+ * <TypographyProvider>
+ *   <App />
+ * </TypographyProvider>
+ * ```
+ *
+ * @example Custom font
+ * ```tsx
+ * <TypographyProvider fontFamily="'Inter', sans-serif">
+ *   <App />
+ * </TypographyProvider>
+ * ```
+ *
+ * @example Partially rounded corners (ROND = 50)
+ * ```tsx
+ * <TypographyProvider fontVariationAxes={{ ROND: 50 }}>
+ *   <App />
+ * </TypographyProvider>
+ * ```
+ *
+ * @example Fully sharp (ROND = 0) with a custom font
+ * ```tsx
+ * <TypographyProvider
+ *   fontFamily="'Outfit', sans-serif"
+ *   fontVariationAxes={{ ROND: 0 }}
+ * >
+ *   <App />
+ * </TypographyProvider>
+ * ```
+ */
+export declare function TypographyProvider({ children, typography, fontFamily, fontVariationAxes, }: TypographyProviderProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@bug-on/md3-react",
+  "version": "0.1.0",
+  "description": "Material Design 3 Expressive React components",
+  "author": "Bug Ổn",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nguyentruongton/bug-on-md3-expressive.git",
+    "directory": "packages/react"
+  },
+  "keywords": [
+    "react",
+    "tailwind",
+    "material-design-3",
+    "md3",
+    "ui-library",
+    "components",
+    "bug-on"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./typography.css": "./dist/typography.css",
+    "./index.css": "./dist/index.css",
+    "./material-symbols-cdn.css": "./dist/material-symbols-cdn.css",
+    "./material-symbols-self-hosted.css": "./dist/material-symbols-self-hosted.css"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "motion": ">=12.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "motion": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@material/material-color-utilities": "^0.3.0",
+    "@radix-ui/react-dialog": "^1.1.15",
+    "@radix-ui/react-dropdown-menu": "^2.1.16",
+    "@radix-ui/react-scroll-area": "^1.2.10",
+    "@radix-ui/react-slot": "^1.2.4",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "tailwind-merge": "^3.3.1",
+    "@bug-on/md3-tokens": "0.1.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^6.0.1",
+    "jsdom": "^29.0.0",
+    "tsup": "^8.4.0",
+    "typescript": "5.8.3",
+    "vitest": "^4.1.0"
+  },
+  "scripts": {
+    "build": "tsup && tsc -p tsconfig.build.json",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "lint": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}