@carbon/motion 11.48.0 → 11.49.0

package/index.scss

@@ -5,7 +5,9 @@
 // LICENSE file in the root directory of this source tree.
 //
 
+@use 'sass:list';
 @use 'sass:map';
+@use 'scss/generated/surfaces' as generated;
 
 /// Common component easings
 /// @type Map
@@ -121,3 +123,134 @@ $slow-01: $duration-slow-01;
 /// @type Duration
 /// @group @carbon/motion
 $slow-02: $duration-slow-02;
+
+/// Named motion intents shared across Carbon implementations
+/// @type Map
+/// @access public
+/// @group @carbon/motion
+$surfaces: generated.$surfaces;
+
+/// Get a named motion surface or one of its properties
+/// @param {String} $name - The motion surface name
+/// @param {String | Null} $property [null] - An optional surface property
+/// @access public
+/// @group @carbon/motion
+/// @return {Map | *} The surface definition or requested property
+@function surface($name, $property: null) {
+  @if not map.has-key($surfaces, $name) {
+    @error 'Unable to find a motion surface named #{$name}.';
+  }
+
+  $definition: map.get($surfaces, $name);
+
+  @if not $property {
+    @return $definition;
+  }
+
+  @if not map.has-key($definition, $property) {
+    @error 'Unable to find a property named #{$property} on the #{$name} motion surface.';
+  }
+
+  @return map.get($definition, $property);
+}
+
+/// Surface duration tokens mapped to their duration values
+/// @access private
+/// @group @carbon/motion
+$-durations: (
+  'fast-01': $duration-fast-01,
+  'fast-02': $duration-fast-02,
+  'moderate-01': $duration-moderate-01,
+  'moderate-02': $duration-moderate-02,
+  'slow-01': $duration-slow-01,
+  'slow-02': $duration-slow-02,
+);
+
+/// Apply a named reveal surface in CSS from the shared surface map.
+///
+/// Resting / `[data-carbon-surface-state='enter']` use the surface enter
+/// keyframes. `[data-carbon-surface-state='exit']` uses the exit keyframes.
+/// Transitions (and `@starting-style` for first-mount enter) are guarded
+/// behind `prefers-reduced-motion: no-preference` - users who prefer reduced
+/// motion get the resting styles with no animation at all.
+///
+/// Typical usage with controlled open/close:
+///
+/// ```scss
+/// [data-carbon-surface='contextual'] {
+///   @include motion.surface(contextual);
+/// }
+/// ```
+///
+/// Shared-element surfaces morph one element into another and have no
+/// CSS-only form; they need a JavaScript engine (Motion in React, View
+/// Transitions for web components), so this mixin rejects them
+/// @param {String} $name - The motion surface name
+/// @access public
+/// @group @carbon/motion
+@mixin surface($name) {
+  $definition: surface($name);
+  $kind: map.get($definition, kind);
+
+  @if $kind != 'reveal' {
+    @error 'The #{$name} surface is a shared-element morph with no CSS-only form. Pair it with a JavaScript engine instead.';
+  }
+
+  $enter: map.get($definition, enter);
+  $exit: map.get($definition, exit);
+  $duration: map.get($-durations, map.get($definition, duration));
+  $enter-easing: map.get($definition, enter-easing);
+  $exit-easing: map.get($definition, exit-easing);
+  $properties: ();
+
+  @each $property, $value in $enter {
+    $properties: list.append($properties, $property, $separator: comma);
+  }
+
+  // resting / enter styles apply regardless of motion preference
+  &,
+  &[data-carbon-surface-state='enter'] {
+    @each $property, $value in $enter {
+      #{$property}: #{$value};
+    }
+  }
+
+  &[data-carbon-surface-state='exit'] {
+    @each $property, $value in $exit {
+      #{$property}: #{$value};
+    }
+  }
+
+  @media (prefers-reduced-motion: no-preference) {
+    // `auto` sizes, e.g. disclosure block-size, interpolate where
+    // supported
+    interpolate-size: allow-keywords;
+    transition-duration: $duration;
+    transition-property: $properties;
+
+    &,
+    &[data-carbon-surface-state='enter'] {
+      transition-timing-function: motion(
+        list.nth($enter-easing, 1),
+        list.nth($enter-easing, 2)
+      );
+    }
+
+    &[data-carbon-surface-state='exit'] {
+      transition-timing-function: motion(
+        list.nth($exit-easing, 1),
+        list.nth($exit-easing, 2)
+      );
+    }
+
+    // the styles the element enters from when it is first rendered
+    @starting-style {
+      &,
+      &[data-carbon-surface-state='enter'] {
+        @each $property, $value in $exit {
+          #{$property}: #{$value};
+        }
+      }
+    }
+  }
+}

package/lib/index.d.ts

@@ -4,21 +4,5 @@
  * 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 declare const fast01 = "70ms";
-export declare const fast02 = "110ms";
-export declare const moderate01 = "150ms";
-export declare const moderate02 = "240ms";
-export declare const slow01 = "400ms";
-export declare const slow02 = "700ms";
-export declare const durationFast01 = "70ms";
-export declare const durationFast02 = "110ms";
-export declare const durationModerate01 = "150ms";
-export declare const durationModerate02 = "240ms";
-export declare const durationSlow01 = "400ms";
-export declare const durationSlow02 = "700ms";
-export declare const unstable_tokens: readonly ["fast01", "fast02", "moderate01", "moderate02", "slow01", "slow02", "durationFast01", "durationFast02", "durationModerate01", "durationModerate02", "durationSlow01", "durationSlow02"];
-export type EasingName = 'standard' | 'entrance' | 'exit';
-export type EasingMode = 'productive' | 'expressive';
-export type EasingMap = Record<EasingName, Record<EasingMode, string>>;
-export declare const easings: EasingMap;
-export declare const motion: (name: EasingName, mode: EasingMode) => string;
+export * from './tokens';
+export * from './surfaces';

package/lib/index.js

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-//#region src/index.ts
+//#region src/tokens.ts
 /**
 * Copyright IBM Corp. 2018, 2026
 *
@@ -32,18 +32,71 @@ const unstable_tokens = [
 	"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) => {
@@ -52,6 +105,97 @@ const motion = (name, mode) => {
 	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;
@@ -62,9 +206,13 @@ exports.durationSlow02 = durationSlow02;
 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;

package/lib/surfaces.d.ts

@@ -0,0 +1,165 @@
+/**
+ * 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;
+}
+interface RevealSurface extends MotionSurfaceBase {
+    kind: 'reveal';
+    enter: RevealKeyframe;
+    exit: RevealKeyframe;
+}
+interface SharedElementSurface extends MotionSurfaceBase {
+    kind: 'shared-element';
+    enter?: RevealKeyframe;
+    exit?: RevealKeyframe;
+    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 declare const surfaces: {
+    readonly disclosure: {
+        readonly kind: "reveal";
+        readonly duration: "moderate-01";
+        readonly enter: {
+            readonly blockSize: "auto";
+            readonly opacity: 1;
+        };
+        readonly exit: {
+            readonly blockSize: 0;
+            readonly opacity: 0;
+        };
+        readonly enterEasing: readonly ["entrance", "productive"];
+        readonly exitEasing: readonly ["exit", "productive"];
+    };
+    readonly contextual: {
+        readonly kind: "reveal";
+        readonly duration: "fast-02";
+        readonly enter: {
+            readonly opacity: 1;
+            readonly transform: "scale(1)";
+        };
+        readonly exit: {
+            readonly opacity: 0;
+            readonly transform: "scale(0.96)";
+        };
+        readonly enterEasing: readonly ["entrance", "expressive"];
+        readonly exitEasing: readonly ["exit", "expressive"];
+    };
+    readonly stretch: {
+        readonly kind: "reveal";
+        readonly duration: "slow-01";
+        readonly enter: {
+            readonly opacity: 1;
+            readonly clipPath: "inset(0 0 0 0)";
+        };
+        readonly exit: {
+            readonly opacity: 0;
+            readonly clipPath: "inset(50% 0 50% 0)";
+        };
+        readonly enterEasing: readonly ["entrance", "expressive"];
+        readonly exitEasing: readonly ["exit", "expressive"];
+    };
+    readonly expand: {
+        readonly kind: "shared-element";
+        readonly duration: "moderate-02";
+        readonly enter: {
+            readonly opacity: 1;
+            readonly transform: "scale(1)";
+        };
+        readonly exit: {
+            readonly opacity: 0;
+            readonly transform: "scale(0.96)";
+        };
+        readonly enterEasing: readonly ["standard", "productive"];
+        readonly exitEasing: readonly ["standard", "productive"];
+    };
+    readonly invoke: {
+        readonly kind: "shared-element";
+        readonly origin: "trigger";
+        readonly duration: "moderate-02";
+        readonly enterEasing: readonly ["standard", "expressive"];
+        readonly exitEasing: readonly ["standard", "expressive"];
+    };
+};
+export type MotionSurfaceName = keyof typeof surfaces;
+export declare const getMotionSurface: (name: MotionSurfaceName) => {
+    readonly kind: "reveal";
+    readonly duration: "moderate-01";
+    readonly enter: {
+        readonly blockSize: "auto";
+        readonly opacity: 1;
+    };
+    readonly exit: {
+        readonly blockSize: 0;
+        readonly opacity: 0;
+    };
+    readonly enterEasing: readonly ["entrance", "productive"];
+    readonly exitEasing: readonly ["exit", "productive"];
+} | {
+    readonly kind: "reveal";
+    readonly duration: "fast-02";
+    readonly enter: {
+        readonly opacity: 1;
+        readonly transform: "scale(1)";
+    };
+    readonly exit: {
+        readonly opacity: 0;
+        readonly transform: "scale(0.96)";
+    };
+    readonly enterEasing: readonly ["entrance", "expressive"];
+    readonly exitEasing: readonly ["exit", "expressive"];
+} | {
+    readonly kind: "reveal";
+    readonly duration: "slow-01";
+    readonly enter: {
+        readonly opacity: 1;
+        readonly clipPath: "inset(0 0 0 0)";
+    };
+    readonly exit: {
+        readonly opacity: 0;
+        readonly clipPath: "inset(50% 0 50% 0)";
+    };
+    readonly enterEasing: readonly ["entrance", "expressive"];
+    readonly exitEasing: readonly ["exit", "expressive"];
+} | {
+    readonly kind: "shared-element";
+    readonly duration: "moderate-02";
+    readonly enter: {
+        readonly opacity: 1;
+        readonly transform: "scale(1)";
+    };
+    readonly exit: {
+        readonly opacity: 0;
+        readonly transform: "scale(0.96)";
+    };
+    readonly enterEasing: readonly ["standard", "productive"];
+    readonly exitEasing: readonly ["standard", "productive"];
+} | {
+    readonly kind: "shared-element";
+    readonly origin: "trigger";
+    readonly duration: "moderate-02";
+    readonly enterEasing: readonly ["standard", "expressive"];
+    readonly exitEasing: readonly ["standard", "expressive"];
+};
+export {};

package/lib/tokens.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 declare const fast01 = "70ms";
+export declare const fast02 = "110ms";
+export declare const moderate01 = "150ms";
+export declare const moderate02 = "240ms";
+export declare const slow01 = "400ms";
+export declare const slow02 = "700ms";
+export declare const durationFast01 = "70ms";
+export declare const durationFast02 = "110ms";
+export declare const durationModerate01 = "150ms";
+export declare const durationModerate02 = "240ms";
+export declare const durationSlow01 = "400ms";
+export declare const durationSlow02 = "700ms";
+export declare const unstable_tokens: readonly ["fast01", "fast02", "moderate01", "moderate02", "slow01", "slow02", "durationFast01", "durationFast02", "durationModerate01", "durationModerate02", "durationSlow01", "durationSlow02"];
+export type DurationName = 'fast-01' | 'fast-02' | 'moderate-01' | 'moderate-02' | 'slow-01' | 'slow-02';
+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>>;
+export declare const easings: EasingMap;
+export declare const motion: (name: EasingName, mode: EasingMode) => string;
+export declare const resolveEasing: (name: EasingName, mode: EasingMode) => CubicBezier;
+export declare const resolveDuration: (name: DurationName) => string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@carbon/motion",
   "description": "Motion helpers for digital and software products using the Carbon Design System",
-  "version": "11.48.0",
+  "version": "11.49.0",
   "license": "Apache-2.0",
   "main": "lib/index.js",
   "module": "es/index.js",
@@ -28,12 +28,12 @@
   },
   "scripts": {
     "build:types": "tsc -p tsconfig.types.json",
-    "build": "yarn clean && carbon-cli bundle src/index.ts --name CarbonMotion && yarn build:types",
-    "clean": "rimraf es lib umd",
+    "build": "yarn clean && carbon-cli bundle src/index.ts --name CarbonMotion && node tasks/build.mjs && yarn build:types",
+    "clean": "rimraf es lib umd scss/generated",
     "postinstall": "ibmtelemetry --config=telemetry.yml"
   },
   "devDependencies": {
-    "@carbon/cli": "^11.46.0",
+    "@carbon/cli": "^11.47.0",
     "rimraf": "^6.0.1",
     "typescript": "^6.0.3",
     "typescript-config-carbon": "^0.11.0"
@@ -41,5 +41,5 @@
   "dependencies": {
     "@ibm/telemetry-js": "^1.5.0"
   },
-  "gitHead": "5102bd860864c2580048183ffaf50d1ffd4400b5"
+  "gitHead": "a57cf8a896fe3fe09c5ab27648cd58947f37360a"
 }

package/scss/generated/_surfaces.scss

@@ -0,0 +1,103 @@
+// Code generated by @carbon/motion. DO NOT EDIT.
+//
+// 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.
+//
+
+$surfaces: (
+  disclosure: (
+    kind: 'reveal',
+    duration: 'moderate-01',
+    enter: (
+      block-size: 'auto',
+      opacity: 1,
+    ),
+    exit: (
+      block-size: 0,
+      opacity: 0,
+    ),
+    enter-easing: (
+      'entrance',
+      'productive',
+    ),
+    exit-easing: (
+      'exit',
+      'productive',
+    ),
+  ),
+  contextual: (
+    kind: 'reveal',
+    duration: 'fast-02',
+    enter: (
+      opacity: 1,
+      transform: 'scale(1)',
+    ),
+    exit: (
+      opacity: 0,
+      transform: 'scale(0.96)',
+    ),
+    enter-easing: (
+      'entrance',
+      'expressive',
+    ),
+    exit-easing: (
+      'exit',
+      'expressive',
+    ),
+  ),
+  stretch: (
+    kind: 'reveal',
+    duration: 'slow-01',
+    enter: (
+      opacity: 1,
+      clip-path: 'inset(0 0 0 0)',
+    ),
+    exit: (
+      opacity: 0,
+      clip-path: 'inset(50% 0 50% 0)',
+    ),
+    enter-easing: (
+      'entrance',
+      'expressive',
+    ),
+    exit-easing: (
+      'exit',
+      'expressive',
+    ),
+  ),
+  expand: (
+    kind: 'shared-element',
+    duration: 'moderate-02',
+    enter: (
+      opacity: 1,
+      transform: 'scale(1)',
+    ),
+    exit: (
+      opacity: 0,
+      transform: 'scale(0.96)',
+    ),
+    enter-easing: (
+      'standard',
+      'productive',
+    ),
+    exit-easing: (
+      'standard',
+      'productive',
+    ),
+  ),
+  invoke: (
+    kind: 'shared-element',
+    origin: 'trigger',
+    duration: 'moderate-02',
+    enter-easing: (
+      'standard',
+      'expressive',
+    ),
+    exit-easing: (
+      'standard',
+      'expressive',
+    ),
+  ),
+);