@carbon/motion 11.48.0 → 11.49.0

package/src/index.ts

@@ -5,69 +5,5 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-export const fast01 = '70ms';
-export const fast02 = '110ms';
-export const moderate01 = '150ms';
-export const moderate02 = '240ms';
-export const slow01 = '400ms';
-export const slow02 = '700ms';
-// V11 Tokens
-export const durationFast01 = fast01;
-export const durationFast02 = fast02;
-export const durationModerate01 = moderate01;
-export const durationModerate02 = moderate02;
-export const durationSlow01 = slow01;
-export const durationSlow02 = slow02;
-
-export const unstable_tokens = [
-  'fast01',
-  'fast02',
-  'moderate01',
-  'moderate02',
-  'slow01',
-  'slow02',
-  'durationFast01',
-  'durationFast02',
-  'durationModerate01',
-  'durationModerate02',
-  'durationSlow01',
-  'durationSlow02',
-] as const;
-
-export type EasingName = 'standard' | 'entrance' | 'exit';
-export type EasingMode = 'productive' | 'expressive';
-export type EasingMap = Record<EasingName, Record<EasingMode, string>>;
-
-export const easings: EasingMap = {
-  standard: {
-    productive: 'cubic-bezier(0.2, 0, 0.38, 0.9)',
-    expressive: 'cubic-bezier(0.4, 0.14, 0.3, 1)',
-  },
-  entrance: {
-    productive: 'cubic-bezier(0, 0, 0.38, 0.9)',
-    expressive: 'cubic-bezier(0, 0, 0.3, 1)',
-  },
-  exit: {
-    productive: 'cubic-bezier(0.2, 0, 1, 0.9)',
-    expressive: 'cubic-bezier(0.4, 0.14, 1, 1)',
-  },
-};
-
-export const motion = (name: EasingName, mode: EasingMode) => {
-  if (!easings[name]) {
-    throw new Error(
-      `Unable to find easing \`${name}\` in our supported easings. Expected ` +
-        `one of: ${Object.keys(easings).join(', ')}`
-    );
-  }
-
-  const easing = easings[name];
-  if (!easing[mode]) {
-    throw new Error(
-      `Unable to find a mode for the easing \`${name}\` called: \`${mode}\`. ` +
-        `Expected one of: ${Object.keys(easing).join(', ')}`
-    );
-  }
-
-  return easing[mode];
-};
+export * from './tokens';
+export * from './surfaces';

package/src/surfaces.ts

@@ -0,0 +1,116 @@
+/**
+ * Copyright IBM Corp. 2026
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import type { DurationName, EasingMode, EasingName } from './tokens';
+
+type MotionEasing = readonly [EasingName, EasingMode];
+
+/**
+ * from/to styles for reveal surface - plain CSS property/value pairs
+ * keep values engine-neutral so CSS, WAAPI, and Motion can all consume
+ * them
+ */
+type RevealKeyframe = Record<string, string | number>;
+
+interface MotionSurfaceBase {
+  duration: DurationName;
+  enterEasing: MotionEasing;
+  exitEasing: MotionEasing;
+}
+
+//  reveal surfaces animate a single element between from/to styles
+//  works on every engine, including plain CSS
+interface RevealSurface extends MotionSurfaceBase {
+  kind: 'reveal';
+  enter: RevealKeyframe;
+  exit: RevealKeyframe;
+}
+
+// shared-element surfaces morph one element into another
+// the adapter picks mechanism (Motion layout projection, View Transitions, FLIP)
+// optional enter/exit keyframes document the CSS-replicable layer (opacity /
+// scale) for Sass consumers and future View Transitions fallbacks
+interface SharedElementSurface extends MotionSurfaceBase {
+  kind: 'shared-element';
+  enter?: RevealKeyframe;
+  exit?: RevealKeyframe;
+  // when set to `trigger`, morph starts from the invoking element
+  origin?: 'trigger';
+}
+
+export type MotionSurfaceDefinition = SharedElementSurface | RevealSurface;
+
+/**
+ * Named motion intents. These definitions are engine and framework agnostic.
+ *
+ * `prefers-reduced-motion` is intentionally not represented here: surfaces
+ * never animate when the users request reduced motion. Framework adapters
+ * bail before running, and the Sass output is wrapped in a
+ * `prefers-reduced-motion: no-preference` media query
+ */
+export const surfaces = {
+  // Accordion, table-row expand - reveal in place
+  disclosure: {
+    kind: 'reveal',
+    duration: 'moderate-01',
+    enter: { blockSize: 'auto', opacity: 1 },
+    exit: { blockSize: 0, opacity: 0 },
+    enterEasing: ['entrance', 'productive'],
+    exitEasing: ['exit', 'productive'],
+  },
+  // Icon > tooltip/popover
+  contextual: {
+    kind: 'reveal',
+    duration: 'fast-02',
+    enter: { opacity: 1, transform: 'scale(1)' },
+    exit: { opacity: 0, transform: 'scale(0.96)' },
+    enterEasing: ['entrance', 'expressive'],
+    exitEasing: ['exit', 'expressive'],
+  },
+  // Component reveal, "stretching" from vertical axis
+  stretch: {
+    kind: 'reveal',
+    duration: 'slow-01',
+    enter: { opacity: 1, clipPath: 'inset(0 0 0 0)' },
+    exit: { opacity: 0, clipPath: 'inset(50% 0 50% 0)' },
+    enterEasing: ['entrance', 'expressive'],
+    exitEasing: ['exit', 'expressive'],
+  },
+  // Card/tile > side-panel/tearsheet
+  expand: {
+    kind: 'shared-element',
+    duration: 'moderate-02',
+    enter: { opacity: 1, transform: 'scale(1)' },
+    exit: { opacity: 0, transform: 'scale(0.96)' },
+    enterEasing: ['standard', 'productive'],
+    exitEasing: ['standard', 'productive'],
+  },
+  // Button > modal/menu/popover - morphs from the trigger
+  invoke: {
+    kind: 'shared-element',
+    origin: 'trigger',
+    duration: 'moderate-02',
+    enterEasing: ['standard', 'expressive'],
+    exitEasing: ['standard', 'expressive'],
+  },
+} as const satisfies Record<string, MotionSurfaceDefinition>;
+
+export type MotionSurfaceName = keyof typeof surfaces;
+
+// Give JavaScript consumers a clear error for an unknown surface name.
+export const getMotionSurface = (name: MotionSurfaceName) => {
+  const surface = surfaces[name];
+
+  if (!surface) {
+    throw new Error(
+      `Unable to find motion surface \`${name}\`. Expected one of: ` +
+        Object.keys(surfaces).join(', ')
+    );
+  }
+
+  return surface;
+};

package/src/tokens.ts

@@ -0,0 +1,147 @@
+/**
+ * Copyright IBM Corp. 2018, 2026
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+export const fast01 = '70ms';
+export const fast02 = '110ms';
+export const moderate01 = '150ms';
+export const moderate02 = '240ms';
+export const slow01 = '400ms';
+export const slow02 = '700ms';
+
+// V11 Tokens
+export const durationFast01 = fast01;
+export const durationFast02 = fast02;
+export const durationModerate01 = moderate01;
+export const durationModerate02 = moderate02;
+export const durationSlow01 = slow01;
+export const durationSlow02 = slow02;
+
+export const unstable_tokens = [
+  'fast01',
+  'fast02',
+  'moderate01',
+  'moderate02',
+  'slow01',
+  'slow02',
+  'durationFast01',
+  'durationFast02',
+  'durationModerate01',
+  'durationModerate02',
+  'durationSlow01',
+  'durationSlow02',
+] as const;
+
+export type DurationName =
+  | 'fast-01'
+  | 'fast-02'
+  | 'moderate-01'
+  | 'moderate-02'
+  | 'slow-01'
+  | 'slow-02';
+
+// Map the surface names to the existing Carbon duration tokens.
+const durations: Record<DurationName, string> = {
+  'fast-01': durationFast01,
+  'fast-02': durationFast02,
+  'moderate-01': durationModerate01,
+  'moderate-02': durationModerate02,
+  'slow-01': durationSlow01,
+  'slow-02': durationSlow02,
+};
+
+export type EasingName = 'standard' | 'entrance' | 'exit';
+export type EasingMode = 'productive' | 'expressive';
+export type CubicBezier = readonly [number, number, number, number];
+export type EasingMap = Record<EasingName, Record<EasingMode, string>>;
+type EasingCurveMap = Record<EasingName, Record<EasingMode, CubicBezier>>;
+
+// Keep one numeric source for every Carbon easing curve.
+const easingCurves: EasingCurveMap = {
+  standard: {
+    productive: [0.2, 0, 0.38, 0.9],
+    expressive: [0.4, 0.14, 0.3, 1],
+  },
+  entrance: {
+    productive: [0, 0, 0.38, 0.9],
+    expressive: [0, 0, 0.3, 1],
+  },
+  exit: {
+    productive: [0.2, 0, 1, 0.9],
+    expressive: [0.4, 0.14, 1, 1],
+  },
+};
+
+const formatEasing = (curve: CubicBezier) =>
+  `cubic-bezier(${curve.join(', ')})`;
+
+export const easings: EasingMap = {
+  standard: {
+    productive: formatEasing(easingCurves.standard.productive),
+    expressive: formatEasing(easingCurves.standard.expressive),
+  },
+  entrance: {
+    productive: formatEasing(easingCurves.entrance.productive),
+    expressive: formatEasing(easingCurves.entrance.expressive),
+  },
+  exit: {
+    productive: formatEasing(easingCurves.exit.productive),
+    expressive: formatEasing(easingCurves.exit.expressive),
+  },
+};
+
+export const motion = (name: EasingName, mode: EasingMode) => {
+  if (!easings[name]) {
+    throw new Error(
+      `Unable to find easing \`${name}\` in our supported easings. Expected ` +
+        `one of: ${Object.keys(easings).join(', ')}`
+    );
+  }
+
+  const easing = easings[name];
+  if (!easing[mode]) {
+    throw new Error(
+      `Unable to find a mode for the easing \`${name}\` called: \`${mode}\`. ` +
+        `Expected one of: ${Object.keys(easing).join(', ')}`
+    );
+  }
+
+  return easing[mode];
+};
+
+// Return the numeric curve required by JavaScript animation engines.
+export const resolveEasing = (name: EasingName, mode: EasingMode) => {
+  if (!easingCurves[name]) {
+    throw new Error(
+      `Unable to find easing \`${name}\` in our supported easings. Expected ` +
+        `one of: ${Object.keys(easingCurves).join(', ')}`
+    );
+  }
+
+  const easing = easingCurves[name];
+  if (!easing[mode]) {
+    throw new Error(
+      `Unable to find a mode for the easing \`${name}\` called: \`${mode}\`. ` +
+        `Expected one of: ${Object.keys(easing).join(', ')}`
+    );
+  }
+
+  return easing[mode];
+};
+
+// Return the existing Carbon duration for a named surface token.
+export const resolveDuration = (name: DurationName) => {
+  const duration = durations[name];
+
+  if (!duration) {
+    throw new Error(
+      `Unable to find duration \`${name}\` in our supported durations. ` +
+        `Expected one of: ${Object.keys(durations).join(', ')}`
+    );
+  }
+
+  return duration;
+};

package/umd/index.js

@@ -2,7 +2,7 @@
 	typeof exports === "object" && typeof module !== "undefined" ? factory(exports) : typeof define === "function" && define.amd ? define(["exports"], factory) : (global = typeof globalThis !== "undefined" ? globalThis : global || self, factory(global.CarbonMotion = {}));
 })(this, function(exports) {
 	Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-	//#region src/index.ts
+	//#region src/tokens.ts
 	/**
 	* Copyright IBM Corp. 2018, 2026
 	*
@@ -35,18 +35,71 @@
 		"durationSlow01",
 		"durationSlow02"
 	];
+	const durations = {
+		"fast-01": durationFast01,
+		"fast-02": durationFast02,
+		"moderate-01": durationModerate01,
+		"moderate-02": durationModerate02,
+		"slow-01": durationSlow01,
+		"slow-02": durationSlow02
+	};
+	const easingCurves = {
+		standard: {
+			productive: [
+				.2,
+				0,
+				.38,
+				.9
+			],
+			expressive: [
+				.4,
+				.14,
+				.3,
+				1
+			]
+		},
+		entrance: {
+			productive: [
+				0,
+				0,
+				.38,
+				.9
+			],
+			expressive: [
+				0,
+				0,
+				.3,
+				1
+			]
+		},
+		exit: {
+			productive: [
+				.2,
+				0,
+				1,
+				.9
+			],
+			expressive: [
+				.4,
+				.14,
+				1,
+				1
+			]
+		}
+	};
+	const formatEasing = (curve) => `cubic-bezier(${curve.join(", ")})`;
 	const easings = {
 		standard: {
-			productive: "cubic-bezier(0.2, 0, 0.38, 0.9)",
-			expressive: "cubic-bezier(0.4, 0.14, 0.3, 1)"
+			productive: formatEasing(easingCurves.standard.productive),
+			expressive: formatEasing(easingCurves.standard.expressive)
 		},
 		entrance: {
-			productive: "cubic-bezier(0, 0, 0.38, 0.9)",
-			expressive: "cubic-bezier(0, 0, 0.3, 1)"
+			productive: formatEasing(easingCurves.entrance.productive),
+			expressive: formatEasing(easingCurves.entrance.expressive)
 		},
 		exit: {
-			productive: "cubic-bezier(0.2, 0, 1, 0.9)",
-			expressive: "cubic-bezier(0.4, 0.14, 1, 1)"
+			productive: formatEasing(easingCurves.exit.productive),
+			expressive: formatEasing(easingCurves.exit.expressive)
 		}
 	};
 	const motion = (name, mode) => {
@@ -55,6 +108,97 @@
 		if (!easing[mode]) throw new Error(`Unable to find a mode for the easing \`${name}\` called: \`${mode}\`. Expected one of: ${Object.keys(easing).join(", ")}`);
 		return easing[mode];
 	};
+	const resolveEasing = (name, mode) => {
+		if (!easingCurves[name]) throw new Error(`Unable to find easing \`${name}\` in our supported easings. Expected one of: ${Object.keys(easingCurves).join(", ")}`);
+		const easing = easingCurves[name];
+		if (!easing[mode]) throw new Error(`Unable to find a mode for the easing \`${name}\` called: \`${mode}\`. Expected one of: ${Object.keys(easing).join(", ")}`);
+		return easing[mode];
+	};
+	const resolveDuration = (name) => {
+		const duration = durations[name];
+		if (!duration) throw new Error(`Unable to find duration \`${name}\` in our supported durations. Expected one of: ${Object.keys(durations).join(", ")}`);
+		return duration;
+	};
+	//#endregion
+	//#region src/surfaces.ts
+	/**
+	* Named motion intents. These definitions are engine and framework agnostic.
+	*
+	* `prefers-reduced-motion` is intentionally not represented here: surfaces
+	* never animate when the users request reduced motion. Framework adapters
+	* bail before running, and the Sass output is wrapped in a
+	* `prefers-reduced-motion: no-preference` media query
+	*/
+	const surfaces = {
+		disclosure: {
+			kind: "reveal",
+			duration: "moderate-01",
+			enter: {
+				blockSize: "auto",
+				opacity: 1
+			},
+			exit: {
+				blockSize: 0,
+				opacity: 0
+			},
+			enterEasing: ["entrance", "productive"],
+			exitEasing: ["exit", "productive"]
+		},
+		contextual: {
+			kind: "reveal",
+			duration: "fast-02",
+			enter: {
+				opacity: 1,
+				transform: "scale(1)"
+			},
+			exit: {
+				opacity: 0,
+				transform: "scale(0.96)"
+			},
+			enterEasing: ["entrance", "expressive"],
+			exitEasing: ["exit", "expressive"]
+		},
+		stretch: {
+			kind: "reveal",
+			duration: "slow-01",
+			enter: {
+				opacity: 1,
+				clipPath: "inset(0 0 0 0)"
+			},
+			exit: {
+				opacity: 0,
+				clipPath: "inset(50% 0 50% 0)"
+			},
+			enterEasing: ["entrance", "expressive"],
+			exitEasing: ["exit", "expressive"]
+		},
+		expand: {
+			kind: "shared-element",
+			duration: "moderate-02",
+			enter: {
+				opacity: 1,
+				transform: "scale(1)"
+			},
+			exit: {
+				opacity: 0,
+				transform: "scale(0.96)"
+			},
+			enterEasing: ["standard", "productive"],
+			exitEasing: ["standard", "productive"]
+		},
+		invoke: {
+			kind: "shared-element",
+			origin: "trigger",
+			duration: "moderate-02",
+			enterEasing: ["standard", "expressive"],
+			exitEasing: ["standard", "expressive"]
+		}
+	};
+	const getMotionSurface = (name) => {
+		const surface = surfaces[name];
+		if (!surface) throw new Error(`Unable to find motion surface \`${name}\`. Expected one of: ` + Object.keys(surfaces).join(", "));
+		return surface;
+	};
 	//#endregion
 	exports.durationFast01 = durationFast01;
 	exports.durationFast02 = durationFast02;
@@ -65,10 +209,14 @@
 	exports.easings = easings;
 	exports.fast01 = fast01;
 	exports.fast02 = fast02;
+	exports.getMotionSurface = getMotionSurface;
 	exports.moderate01 = moderate01;
 	exports.moderate02 = moderate02;
 	exports.motion = motion;
+	exports.resolveDuration = resolveDuration;
+	exports.resolveEasing = resolveEasing;
 	exports.slow01 = slow01;
 	exports.slow02 = slow02;
+	exports.surfaces = surfaces;
 	exports.unstable_tokens = unstable_tokens;
 });