@bug-on/m3-expressive 1.0.0

package/dist/typography-339RV6v7.d.mts

@@ -0,0 +1,486 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as React from 'react';
+import { ReactNode } from 'react';
+
+/**
+ * TypographyKeyTokens - MD3 Expressive Typography Key Tokens Enum
+ *
+ * Port of androidx.compose.material3.tokens.TypographyKeyTokens (Kotlin enum class).
+ * Used to reference a specific TextStyle via Typography.fromToken().
+ *
+ * Contains 30 keys: 15 baseline + 15 emphasized (MD3 Expressive).
+ */
+declare enum TypographyKeyTokens {
+    BodyLarge = "BodyLarge",
+    BodyMedium = "BodyMedium",
+    BodySmall = "BodySmall",
+    DisplayLarge = "DisplayLarge",
+    DisplayMedium = "DisplayMedium",
+    DisplaySmall = "DisplaySmall",
+    HeadlineLarge = "HeadlineLarge",
+    HeadlineMedium = "HeadlineMedium",
+    HeadlineSmall = "HeadlineSmall",
+    LabelLarge = "LabelLarge",
+    LabelMedium = "LabelMedium",
+    LabelSmall = "LabelSmall",
+    TitleLarge = "TitleLarge",
+    TitleMedium = "TitleMedium",
+    TitleSmall = "TitleSmall",
+    BodyLargeEmphasized = "BodyLargeEmphasized",
+    BodyMediumEmphasized = "BodyMediumEmphasized",
+    BodySmallEmphasized = "BodySmallEmphasized",
+    DisplayLargeEmphasized = "DisplayLargeEmphasized",
+    DisplayMediumEmphasized = "DisplayMediumEmphasized",
+    DisplaySmallEmphasized = "DisplaySmallEmphasized",
+    HeadlineLargeEmphasized = "HeadlineLargeEmphasized",
+    HeadlineMediumEmphasized = "HeadlineMediumEmphasized",
+    HeadlineSmallEmphasized = "HeadlineSmallEmphasized",
+    LabelLargeEmphasized = "LabelLargeEmphasized",
+    LabelMediumEmphasized = "LabelMediumEmphasized",
+    LabelSmallEmphasized = "LabelSmallEmphasized",
+    TitleLargeEmphasized = "TitleLargeEmphasized",
+    TitleMediumEmphasized = "TitleMediumEmphasized",
+    TitleSmallEmphasized = "TitleSmallEmphasized"
+}
+
+/**
+ * @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 };
+ * ```
+ */
+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.
+ */
+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'
+ * ```
+ */
+declare function serializeFontVariationAxes(axes: FontVariationAxes): string;
+/**
+ * Pre-computed default `font-variation-settings` string.
+ * Equivalent to `'"ROND" 100'`.
+ */
+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.
+ */
+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}.
+ */
+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 },
+ * });
+ * ```
+ */
+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;
+}
+
+/**
+ * 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 } })
+ * );
+ * ```
+ */
+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}.
+ */
+declare const TypographyContext: 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>
+ * ```
+ */
+declare function useTypography(): Typography;
+/**
+ * Props for {@link TypographyProvider}.
+ */
+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>
+ * ```
+ */
+declare function TypographyProvider({ children, typography, fontFamily, fontVariationAxes, }: TypographyProviderProps): react_jsx_runtime.JSX.Element;
+
+export { DEFAULT_FONT_VARIATION_AXES as D, type FontVariationAxes as F, MD3_EXPRESSIVE_FONT_VARIATION as M, type TextStyle as T, Typography as a, TypographyContext as b, TypographyKeyTokens as c, TypographyProvider as d, type TypographyProviderProps as e, TypographyTokens as f, type TypographyTokensOptions as g, serializeFontVariationAxes as s, useTypography as u };