@bug-on/md3-tokens 3.0.0 → 3.0.3

package/dist/index.d.ts

@@ -1,7 +1,204 @@
 /**
  * MD3 Expressive Motion Tokens
- * Framework-agnostic JS objects.
+ *
+ * Source of truth for all motion in the design system. Two layers:
+ *
+ * 1. **Physics-based system** (May 2025, primary) — Spring tokens per the MD3
+ *    motion physics system. Use these for Framer Motion / JS animations.
+ * 2. **Legacy easing + duration** (still valid for CSS transitions) — Original
+ *    MD3 cubic-bezier tokens kept as a fallback.
+ *
+ * @see https://m3.material.io/styles/motion/overview/how-it-works
+ * @see https://m3.material.io/styles/motion/overview/specs
  */
+/** Motion scheme — controls whether springs bounce (expressive) or not (standard). */
+type MotionScheme = "expressive" | "standard";
+/** Spring speed tier. */
+type SpringSpeed = "fast" | "default" | "slow";
+/** Spring type — spatial (position/size/shape) or effects (color/opacity). */
+type SpringType = "spatial" | "effects";
+/** Raw MD3 spring token — damping ratio + stiffness as specified in the design token. */
+interface MD3SpringToken {
+    /** Damping ratio: 0 = no damping, 1 = critically damped (no bounce). */
+    dampingRatio: number;
+    /** Spring stiffness. Higher = faster animation. */
+    stiffness: number;
+}
+/** A pre-converted spring ready for Framer Motion `Transition`. */
+interface FramerSpring {
+    type: "spring";
+    /** Absolute damping coefficient (converted from dampingRatio). */
+    damping: number;
+    stiffness: number;
+}
+/** Web CSS curve equivalent for a spring token (for CSS transitions). */
+interface WebCurveToken {
+    /** CSS cubic-bezier(...) string. */
+    curve: string;
+    /** Duration in milliseconds. */
+    durationMs: number;
+}
+/**
+ * Raw MD3 spring tokens per the official specification.
+ * Values are identical for both "expressive" and "standard" schemes —
+ * the scheme is applied at the product level, not the token level.
+ *
+ * @see https://m3.material.io/styles/motion/easing-and-duration/tokens-specs
+ */
+declare const md3SpringTokens: {
+    readonly fast: {
+        readonly spatial: {
+            dampingRatio: number;
+            stiffness: number;
+        };
+        readonly effects: {
+            dampingRatio: number;
+            stiffness: number;
+        };
+    };
+    readonly default: {
+        readonly spatial: {
+            dampingRatio: number;
+            stiffness: number;
+        };
+        readonly effects: {
+            dampingRatio: number;
+            stiffness: number;
+        };
+    };
+    readonly slow: {
+        readonly spatial: {
+            dampingRatio: number;
+            stiffness: number;
+        };
+        readonly effects: {
+            dampingRatio: number;
+            stiffness: number;
+        };
+    };
+};
+/**
+ * Ready-to-use Framer Motion spring configs, derived from MD3 spring tokens.
+ *
+ * Use **spatial** springs for: position, size, border-radius, rotation, scale.
+ * Use **effects** springs for: color, opacity (no overshoot).
+ *
+ * @example
+ * ```tsx
+ * import { framerSprings } from "@md3-expressive/tokens";
+ * <m.div transition={framerSprings.fast.spatial} />
+ * ```
+ */
+declare const framerSprings: {
+    readonly fast: {
+        readonly spatial: FramerSpring;
+        readonly effects: FramerSpring;
+    };
+    readonly default: {
+        readonly spatial: FramerSpring;
+        readonly effects: FramerSpring;
+    };
+    readonly slow: {
+        readonly spatial: FramerSpring;
+        readonly effects: FramerSpring;
+    };
+};
+declare const FAST_SPATIAL_SPRING: FramerSpring;
+declare const FAST_EFFECTS_SPRING: FramerSpring;
+declare const DEFAULT_SPATIAL_SPRING: FramerSpring;
+declare const DEFAULT_EFFECTS_SPRING: FramerSpring;
+declare const SLOW_SPATIAL_SPRING: FramerSpring;
+declare const SLOW_EFFECTS_SPRING: FramerSpring;
+/**
+ * CSS cubic-bezier + duration equivalents of MD3 spring tokens.
+ * For non-interruptible CSS transitions when JS springs are unavailable.
+ *
+ * @see https://m3.material.io/styles/motion/overview/specs
+ */
+declare const webCurves: {
+    readonly expressive: {
+        readonly fast: {
+            readonly spatial: {
+                curve: string;
+                durationMs: number;
+            };
+            readonly effects: {
+                curve: string;
+                durationMs: number;
+            };
+        };
+        readonly default: {
+            readonly spatial: {
+                curve: string;
+                durationMs: number;
+            };
+            readonly effects: {
+                curve: string;
+                durationMs: number;
+            };
+        };
+        readonly slow: {
+            readonly spatial: {
+                curve: string;
+                durationMs: number;
+            };
+            readonly effects: {
+                curve: string;
+                durationMs: number;
+            };
+        };
+    };
+    readonly standard: {
+        readonly fast: {
+            readonly spatial: {
+                curve: string;
+                durationMs: number;
+            };
+            readonly effects: {
+                curve: string;
+                durationMs: number;
+            };
+        };
+        readonly default: {
+            readonly spatial: {
+                curve: string;
+                durationMs: number;
+            };
+            readonly effects: {
+                curve: string;
+                durationMs: number;
+            };
+        };
+        readonly slow: {
+            readonly spatial: {
+                curve: string;
+                durationMs: number;
+            };
+            readonly effects: {
+                curve: string;
+                durationMs: number;
+            };
+        };
+    };
+};
+/**
+ * Get a Framer Motion spring config for the given scheme, speed, and type.
+ *
+ * @example
+ * ```tsx
+ * transition={getSpring("expressive", "fast", "spatial")}
+ * ```
+ */
+declare function getSpring(_scheme: MotionScheme, speed: SpringSpeed, type: SpringType): FramerSpring;
+/**
+ * Get a CSS transition string for the given scheme, speed, and type.
+ *
+ * @example
+ * ```ts
+ * element.style.transition = `transform ${getCSSTransition("expressive", "fast", "spatial")}`;
+ * ```
+ */
+declare function getCSSTransition(scheme: MotionScheme, speed: SpringSpeed, type: SpringType): string;
 declare const duration: {
     readonly short1: 50;
     readonly short2: 100;
@@ -21,38 +218,30 @@ declare const duration: {
     readonly extraLong4: 1000;
 };
 declare const easing: {
-    readonly standard: [number, number, number, number];
-    readonly standardAccelerate: [number, number, number, number];
-    readonly standardDecelerate: [number, number, number, number];
     readonly emphasized: [number, number, number, number];
     readonly emphasizedAccelerate: [number, number, number, number];
     readonly emphasizedDecelerate: [number, number, number, number];
+    readonly standard: [number, number, number, number];
+    readonly standardAccelerate: [number, number, number, number];
+    readonly standardDecelerate: [number, number, number, number];
+    readonly legacy: [number, number, number, number];
+    readonly legacyAccelerate: [number, number, number, number];
+    readonly legacyDecelerate: [number, number, number, number];
+    readonly linear: [number, number, number, number];
 };
+/** @deprecated Use `framerSprings.default.spatial` or `DEFAULT_SPATIAL_SPRING` instead. */
 declare const spring: {
-    readonly default: {
-        readonly type: "spring";
-        readonly stiffness: 500;
-        readonly damping: 30;
-        readonly mass: 0.8;
-    };
-    readonly snappy: {
-        readonly type: "spring";
-        readonly stiffness: 600;
-        readonly damping: 25;
-    };
-    readonly gentle: {
-        readonly type: "spring";
-        readonly stiffness: 300;
-        readonly damping: 20;
-    };
+    readonly default: FramerSpring;
+    readonly snappy: FramerSpring;
+    readonly gentle: FramerSpring;
     readonly bouncy: {
+        readonly damping: number;
         readonly type: "spring";
-        readonly stiffness: 400;
-        readonly damping: 15;
+        readonly stiffness: number;
     };
 };
 declare const motionTokens: {
-    duration: {
+    readonly duration: {
         readonly short1: 50;
         readonly short2: 100;
         readonly short3: 150;
@@ -70,37 +259,251 @@ declare const motionTokens: {
         readonly extraLong3: 900;
         readonly extraLong4: 1000;
     };
-    easing: {
-        readonly standard: [number, number, number, number];
-        readonly standardAccelerate: [number, number, number, number];
-        readonly standardDecelerate: [number, number, number, number];
+    readonly easing: {
         readonly emphasized: [number, number, number, number];
         readonly emphasizedAccelerate: [number, number, number, number];
         readonly emphasizedDecelerate: [number, number, number, number];
+        readonly standard: [number, number, number, number];
+        readonly standardAccelerate: [number, number, number, number];
+        readonly standardDecelerate: [number, number, number, number];
+        readonly legacy: [number, number, number, number];
+        readonly legacyAccelerate: [number, number, number, number];
+        readonly legacyDecelerate: [number, number, number, number];
+        readonly linear: [number, number, number, number];
+    };
+    readonly spring: {
+        readonly fast: {
+            readonly spatial: {
+                dampingRatio: number;
+                stiffness: number;
+            };
+            readonly effects: {
+                dampingRatio: number;
+                stiffness: number;
+            };
+        };
+        readonly default: {
+            readonly spatial: {
+                dampingRatio: number;
+                stiffness: number;
+            };
+            readonly effects: {
+                dampingRatio: number;
+                stiffness: number;
+            };
+        };
+        readonly slow: {
+            readonly spatial: {
+                dampingRatio: number;
+                stiffness: number;
+            };
+            readonly effects: {
+                dampingRatio: number;
+                stiffness: number;
+            };
+        };
     };
-    spring: {
+    readonly framerSprings: {
+        readonly fast: {
+            readonly spatial: FramerSpring;
+            readonly effects: FramerSpring;
+        };
         readonly default: {
-            readonly type: "spring";
-            readonly stiffness: 500;
-            readonly damping: 30;
-            readonly mass: 0.8;
+            readonly spatial: FramerSpring;
+            readonly effects: FramerSpring;
         };
-        readonly snappy: {
-            readonly type: "spring";
-            readonly stiffness: 600;
-            readonly damping: 25;
+        readonly slow: {
+            readonly spatial: FramerSpring;
+            readonly effects: FramerSpring;
         };
-        readonly gentle: {
-            readonly type: "spring";
-            readonly stiffness: 300;
-            readonly damping: 20;
+    };
+    readonly webCurves: {
+        readonly expressive: {
+            readonly fast: {
+                readonly spatial: {
+                    curve: string;
+                    durationMs: number;
+                };
+                readonly effects: {
+                    curve: string;
+                    durationMs: number;
+                };
+            };
+            readonly default: {
+                readonly spatial: {
+                    curve: string;
+                    durationMs: number;
+                };
+                readonly effects: {
+                    curve: string;
+                    durationMs: number;
+                };
+            };
+            readonly slow: {
+                readonly spatial: {
+                    curve: string;
+                    durationMs: number;
+                };
+                readonly effects: {
+                    curve: string;
+                    durationMs: number;
+                };
+            };
         };
-        readonly bouncy: {
-            readonly type: "spring";
-            readonly stiffness: 400;
-            readonly damping: 15;
+        readonly standard: {
+            readonly fast: {
+                readonly spatial: {
+                    curve: string;
+                    durationMs: number;
+                };
+                readonly effects: {
+                    curve: string;
+                    durationMs: number;
+                };
+            };
+            readonly default: {
+                readonly spatial: {
+                    curve: string;
+                    durationMs: number;
+                };
+                readonly effects: {
+                    curve: string;
+                    durationMs: number;
+                };
+            };
+            readonly slow: {
+                readonly spatial: {
+                    curve: string;
+                    durationMs: number;
+                };
+                readonly effects: {
+                    curve: string;
+                    durationMs: number;
+                };
+            };
         };
     };
 };
 
-export { duration, easing, motionTokens, spring };
+/**
+ * MD3 Expressive Shape Tokens
+ *
+ * TypeScript counterpart to `shape.css`. Provides numeric corner radius values,
+ * CSS custom property names, and asymmetric corner helpers.
+ *
+ * Updated for M3 Expressive (May 2025): 10-level corner radius scale.
+ *
+ * @see https://m3.material.io/styles/shape/corner-radius-scale
+ */
+/**
+ * Numeric corner radius values (px) for all 10 shape scale levels.
+ * Map directly to `--md-sys-shape-corner-*` CSS custom properties.
+ *
+ * @example
+ * ```ts
+ * element.style.borderRadius = `${cornerRadius.medium}px`; // 12px
+ * ```
+ */
+declare const cornerRadius: {
+    readonly none: 0;
+    readonly extraSmall: 4;
+    readonly small: 8;
+    readonly medium: 12;
+    readonly large: 16;
+    /** New in M3 Expressive (May 2025) */
+    readonly largeIncreased: 20;
+    readonly extraLarge: 28;
+    /** New in M3 Expressive (May 2025) */
+    readonly extraLargeIncreased: 32;
+    /** New in M3 Expressive (May 2025) */
+    readonly extraExtraLarge: 48;
+    readonly full: 9999;
+};
+type CornerRadiusKey = keyof typeof cornerRadius;
+/**
+ * Maps each corner radius key to its CSS custom property name.
+ *
+ * @example
+ * ```ts
+ * const cssVar = cornerCssVar.medium; // "--md-sys-shape-corner-medium"
+ * element.style.borderRadius = `var(${cssVar})`;
+ * ```
+ */
+declare const cornerCssVar: Record<CornerRadiusKey, string>;
+/**
+ * Describes per-corner rounding for asymmetric shapes.
+ * Follows CSS `border-radius` shorthand order:
+ * top-left, top-right, bottom-right, bottom-left.
+ */
+interface AsymmetricCorners {
+    topLeft: number;
+    topRight: number;
+    bottomRight: number;
+    bottomLeft: number;
+}
+/** Shorthand presets for common asymmetric corner patterns. */
+declare const asymmetricCorners: {
+    /** Fully rounded top, square bottom — e.g. menu at top of screen. */
+    readonly topFull: (r?: 28) => AsymmetricCorners;
+    /** Square top, fully rounded bottom — e.g. menu at bottom of screen. */
+    readonly bottomFull: (r?: 28) => AsymmetricCorners;
+    /** Rounded start edge only — e.g. left item in a grouped set. */
+    readonly startFull: (r?: 9999) => AsymmetricCorners;
+    /** Rounded end edge only — e.g. right item in a grouped set. */
+    readonly endFull: (r?: 9999) => AsymmetricCorners;
+};
+/**
+ * Converts an `AsymmetricCorners` object to a CSS `border-radius` string.
+ *
+ * @example
+ * ```ts
+ * element.style.borderRadius = toCSS(asymmetricCorners.topFull());
+ * // "28px 28px 0px 0px"
+ * ```
+ */
+declare function asymmetricCornersToCSS(corners: AsymmetricCorners): string;
+/**
+ * Calculates the inner border-radius that maintains optical roundness
+ * when nesting one rounded container inside another.
+ *
+ * Formula: `inner = outer - padding`
+ *
+ * @see https://m3.material.io/styles/shape/corner-radius-scale#adjust-for-optical-roundness
+ *
+ * @example
+ * ```ts
+ * // Container has extraExtraLarge (48px), padding is 14px
+ * const inner = opticalRadius(cornerRadius.extraExtraLarge, 14); // 34
+ * ```
+ */
+declare function opticalRadius(outerRadius: number, padding: number): number;
+declare const shapeTokens: {
+    readonly cornerRadius: {
+        readonly none: 0;
+        readonly extraSmall: 4;
+        readonly small: 8;
+        readonly medium: 12;
+        readonly large: 16;
+        /** New in M3 Expressive (May 2025) */
+        readonly largeIncreased: 20;
+        readonly extraLarge: 28;
+        /** New in M3 Expressive (May 2025) */
+        readonly extraLargeIncreased: 32;
+        /** New in M3 Expressive (May 2025) */
+        readonly extraExtraLarge: 48;
+        readonly full: 9999;
+    };
+    readonly cornerCssVar: Record<"none" | "extraSmall" | "small" | "medium" | "large" | "largeIncreased" | "extraLarge" | "extraLargeIncreased" | "extraExtraLarge" | "full", string>;
+    readonly asymmetricCorners: {
+        /** Fully rounded top, square bottom — e.g. menu at top of screen. */
+        readonly topFull: (r?: 28) => AsymmetricCorners;
+        /** Square top, fully rounded bottom — e.g. menu at bottom of screen. */
+        readonly bottomFull: (r?: 28) => AsymmetricCorners;
+        /** Rounded start edge only — e.g. left item in a grouped set. */
+        readonly startFull: (r?: 9999) => AsymmetricCorners;
+        /** Rounded end edge only — e.g. right item in a grouped set. */
+        readonly endFull: (r?: 9999) => AsymmetricCorners;
+    };
+};
+
+export { type AsymmetricCorners, type CornerRadiusKey, DEFAULT_EFFECTS_SPRING, DEFAULT_SPATIAL_SPRING, FAST_EFFECTS_SPRING, FAST_SPATIAL_SPRING, type FramerSpring, type MD3SpringToken, type MotionScheme, SLOW_EFFECTS_SPRING, SLOW_SPATIAL_SPRING, type SpringSpeed, type SpringType, type WebCurveToken, asymmetricCorners, asymmetricCornersToCSS, cornerCssVar, cornerRadius, duration, easing, framerSprings, getCSSTransition, getSpring, md3SpringTokens, motionTokens, opticalRadius, shapeTokens, spring, webCurves };