refactor(Calendar): migrate to motion components

change/@fluentui-react-calendar-compat-51c1ee36-d9f0-4d16-9a35-8e1fda9424e3.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "refactor(react-calendar): migrate to motion components",
+  "packageName": "@fluentui/react-calendar-compat",
+  "email": "robertpenner@microsoft.com",
+  "dependentChangeType": "patch"
+}

change/@fluentui-react-motion-bbaaafd1-d86c-4b82-99bd-49a92507f93e.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "fix(react-motion): apply MotionComponent type to presence definition",
+  "packageName": "@fluentui/react-motion",
+  "email": "robertpenner@microsoft.com",
+  "dependentChangeType": "patch"
+}

packages/react-components/react-calendar-compat/MOTION_MIGRATION_PLAN.md

@@ -0,0 +1,107 @@
+# Calendar Motion Migration Plan
+
+## Overview
+
+Migration of Calendar animations from CSS keyframe animations to Fluent UI v9 motion components.
+
+**Last Updated:** January 2026
+**Status:** Phase 2 complete (all animations migrated to motion components)
+
+---
+
+## Current State
+
+### Completed (Phase 1: Slide Animations)
+
+- ✅ Created `DirectionalSlide` component using `Slide.In` from `@fluentui/react-motion-components-preview`
+- ✅ Migrated `CalendarDayGrid` row animations to motion components
+- ✅ Migrated `CalendarMonth` row animations to motion components
+- ✅ Updated `CalendarGridRow` to use `React.forwardRef` (required for motion ref)
+- ✅ Using `motionTokens.durationSlower` (400ms) and `motionTokens.curveDecelerateMax`
+
+### Completed (Phase 2: CSS Animation Migration)
+
+- ✅ Migrated `CalendarYear` row animations to `DirectionalSlide` motion components
+- ✅ Removed CSS slide animations from `CalendarPicker` styles
+- ✅ Created `HeaderFade` component using `Fade.In` from `@fluentui/react-motion-components-preview`
+- ✅ Migrated header fade animations in `CalendarDay`, `CalendarMonth`, `CalendarYear`
+- ✅ Removed CSS fade animations from `useCalendarDayStyles.styles.ts`
+- ✅ Removed CSS fade animations from `useCalendarPickerStyles.styles.ts`
+- ✅ Marked animation constants as `@deprecated` in `animations.ts`
+
+---
+
+## Phase 2: Remaining CSS Animation Migration (COMPLETED)
+
+### Summary
+
+All CSS animations have been migrated to motion components:
+
+#### 1. CalendarYear/CalendarPicker Slide Animations ✅
+
+- Added `DirectionalSlide` wrappers around year rows in `CalendarYear.tsx`
+- Removed CSS slide animation styles from `useCalendarPickerStyles.styles.ts`
+- Uses same pattern as CalendarMonth
+
+#### 2. Header Fade Animations ✅
+
+- Created `HeaderFade` component using `Fade.In` from `@fluentui/react-motion-components-preview`
+- Uses `motionTokens.durationGentle` (~250ms) for timing
+- Component uses `navigationKey` prop to trigger animation on value change
+- Migrated in `CalendarDay.tsx`, `CalendarMonth.tsx`, `CalendarYear.tsx`
+- Removed CSS fade animations from style files
+
+#### 3. Animation Constants ✅
+
+- All animation constants in `animations.ts` marked as `@deprecated`
+- Constants retained for backwards compatibility only
+
+### Migration Order (COMPLETED)
+
+1. **CalendarYear slide animations** ✅
+
+   - Same pattern as CalendarMonth
+   - Removed `SLIDE_*_IN20` and `DURATION_3` usage
+
+2. **Header fade animations** ✅
+
+   - Created `HeaderFade` component with `navigationKey` for triggering
+   - Used standard motion tokens (slight deviation from original easing accepted)
+
+3. **Animation constants deprecated** ✅
+   - All exports marked `@deprecated` for backwards compatibility
+
+---
+
+## Validation Tasks
+
+- [x] Build passes: `yarn nx run react-calendar-compat:build`
+- [x] Unit tests pass: `yarn nx run react-calendar-compat:test`
+- [ ] Run VR tests: `yarn nx run vr-tests-react-components:test-vr`
+- [ ] Test keyboard navigation
+- [ ] Test reduced motion preference (`prefers-reduced-motion`)
+- [ ] Cross-browser validation (Chrome, Firefox, Safari)
+
+---
+
+## Files Modified
+
+| File                                 | Status | Changes                                                |
+| ------------------------------------ | ------ | ------------------------------------------------------ |
+| `CalendarDayGrid.tsx`                | ✅     | `DirectionalSlide` wrappers for day rows               |
+| `CalendarGridRow.tsx`                | ✅     | Added `React.forwardRef`                               |
+| `CalendarMonth.tsx`                  | ✅     | `DirectionalSlide` wrappers for month rows, HeaderFade |
+| `CalendarYear.tsx`                   | ✅     | `DirectionalSlide` wrappers for year rows, HeaderFade  |
+| `calendarMotions.tsx`                | ✅     | Created `DirectionalSlide` and `HeaderFade` components |
+| `useCalendarDayGridStyles.styles.ts` | ✅     | Removed CSS slide animations                           |
+| `useCalendarPickerStyles.styles.ts`  | ✅     | Removed CSS slide and fade animations                  |
+| `CalendarDay.tsx`                    | ✅     | Added `HeaderFade` for header                          |
+| `useCalendarDayStyles.styles.ts`     | ✅     | Removed CSS fade animation                             |
+| `animations.ts`                      | ✅     | All exports marked `@deprecated`                       |
+
+---
+
+## References
+
+- [Fluent UI Motion Documentation](https://react.fluentui.dev/?path=/docs/motion-introduction--docs)
+- [react-motion-components-preview](../../react-motion-components-preview/)

packages/react-components/react-calendar-compat/library/package.json

@@ -15,6 +15,8 @@
     "@fluentui/keyboard-keys": "^9.0.8",
     "@fluentui/react-icons": "^2.0.245",
     "@fluentui/react-jsx-runtime": "^9.3.4",
+    "@fluentui/react-motion": "^9.11.5",
+    "@fluentui/react-motion-components-preview": "^0.14.2",
     "@fluentui/react-shared-contexts": "^9.26.0",
     "@fluentui/react-tabster": "^9.26.11",
     "@fluentui/react-theme": "^9.2.0",

packages/react-components/react-calendar-compat/library/src/components/CalendarDay/CalendarDay.tsx

@@ -6,9 +6,11 @@ import { mergeClasses } from '@griffel/react';
 import { addMonths, compareDatePart, getMonthEnd, getMonthStart } from '../../utils';
 import { CalendarDayGrid } from '../CalendarDayGrid/CalendarDayGrid';
 import { useCalendarDayStyles_unstable } from './useCalendarDayStyles.styles';
+import { HeaderFade } from '../../utils/calendarMotions';
 import type { ICalendarDayGrid } from '../CalendarDayGrid/CalendarDayGrid.types';
 import type { CalendarDayProps, CalendarDayStyles } from './CalendarDay.types';
 import type { JSXElement } from '@fluentui/react-utilities';
+import { AnimationDirection } from '../../Calendar';
 
 /**
  * @internal
@@ -40,7 +42,7 @@ export const CalendarDay: React.FunctionComponent<CalendarDayProps> = props => {
     onNavigateDate,
     showWeekNumbers,
     dateRangeType,
-    animationDirection,
+    animationDirection = AnimationDirection.Vertical,
   } = props;
 
   const classNames = useCalendarDayStyles_unstable({
@@ -69,9 +71,11 @@ export const CalendarDay: React.FunctionComponent<CalendarDayProps> = props => {
           onKeyDown={onButtonKeyDown(onHeaderSelect)}
           type="button"
         >
-          <span aria-live="polite" aria-atomic="true">
-            {monthAndYear}
-          </span>
+          <HeaderFade navigationKey={monthAndYear}>
+            <span aria-live="polite" aria-atomic="true">
+              {monthAndYear}
+            </span>
+          </HeaderFade>
         </HeaderButtonComponentType>
         <CalendarDayNavigationButtons {...props} classNames={classNames} />
       </div>

packages/react-components/react-calendar-compat/library/src/components/CalendarDay/useCalendarDayStyles.styles.ts

@@ -2,10 +2,11 @@
 
 import { tokens } from '@fluentui/react-theme';
 import { makeStyles, mergeClasses, shorthands } from '@griffel/react';
-import { DURATION_2, EASING_FUNCTION_2, FADE_IN } from '../../utils/animations';
 import type { SlotClassNames } from '@fluentui/react-utilities';
 import type { CalendarDayStyles, CalendarDayStyleProps } from './CalendarDay.types';
 
+// Note: FADE_IN, DURATION_2, EASING_FUNCTION_2 animations removed - now handled by HeaderFade motion component
+
 /**
  * @internal
  */
@@ -64,12 +65,7 @@ const useMonthAndYearStyles = makeStyles({
     textOverflow: 'ellipsis',
     whiteSpace: 'nowrap',
   },
-  animation: {
-    animationDuration: DURATION_2,
-    animationFillMode: 'both',
-    animationName: FADE_IN,
-    animationTimingFunction: EASING_FUNCTION_2,
-  },
+  // CSS animation removed - now handled by HeaderFade motion component
   headerIsClickable: {
     '&:hover': {
       backgroundColor: tokens.colorBrandBackgroundInvertedHover,
@@ -166,7 +162,7 @@ export const useCalendarDayStyles_unstable = (props: CalendarDayStyleProps): Cal
     monthAndYear: mergeClasses(
       calendarDayClassNames.monthAndYear,
       monthAndYearStyles.base,
-      monthAndYearStyles.animation,
+      // CSS animation removed - now handled by HeaderFade motion component
       headerIsClickable && monthAndYearStyles.headerIsClickable,
     ),
     monthComponents: mergeClasses(calendarDayClassNames.monthComponents, monthComponentsStyles.base),

packages/react-components/react-calendar-compat/library/src/components/CalendarDayGrid/CalendarDayGrid.tsx

@@ -12,6 +12,8 @@ import { useWeekCornerStyles, WeekCorners } from './useWeekCornerStyles.styles';
 import { mergeClasses } from '@griffel/react';
 import type { Day } from '../../utils';
 import type { CalendarDayGridProps } from './CalendarDayGrid.types';
+import { DirectionalSlide } from '../../utils/calendarMotions';
+import { AnimationDirection } from '../../Calendar';
 
 export interface DayInfo extends Day {
   onSelected: () => void;
@@ -75,6 +77,7 @@ export const CalendarDayGrid: React.FunctionComponent<CalendarDayGridProps> = pr
 
   const weeks = useWeeks(props, onSelectDate, getSetRefCallback);
   const animateBackwards = useAnimateBackwards(weeks);
+
   const [getWeekCornerStyles, calculateRoundedStyles] = useWeekCornerStyles(props);
 
   React.useImperativeHandle(
@@ -130,7 +133,7 @@ export const CalendarDayGrid: React.FunctionComponent<CalendarDayGridProps> = pr
     showWeekNumbers,
     labelledBy,
     lightenDaysOutsideNavigatedMonth,
-    animationDirection,
+    animationDirection = AnimationDirection.Vertical,
   } = props;
 
   const classNames = useCalendarDayGridStyles_unstable({
@@ -156,6 +159,8 @@ export const CalendarDayGrid: React.FunctionComponent<CalendarDayGridProps> = pr
   } as const;
 
   const arrowNavigationAttributes = useArrowNavigationGroup({ axis: 'grid' });
+  const firstWeek = weeks[0];
+  const finalWeek = weeks![weeks!.length - 1];
 
   return (
     <table
@@ -169,34 +174,40 @@ export const CalendarDayGrid: React.FunctionComponent<CalendarDayGridProps> = pr
     >
       <tbody>
         <CalendarMonthHeaderRow {...props} classNames={classNames} weeks={weeks} />
-        <CalendarGridRow
-          {...props}
-          {...partialWeekProps}
-          week={weeks[0]}
-          weekIndex={-1}
-          rowClassName={classNames.firstTransitionWeek}
-          aria-role="presentation"
-          ariaHidden={true}
-        />
-        {weeks!.slice(1, weeks!.length - 1).map((week: DayInfo[], weekIndex: number) => (
+        <DirectionalSlide key={'firstTransitionWeek_' + firstWeek[0].key} {...{ animationDirection, animateBackwards }}>
           <CalendarGridRow
             {...props}
             {...partialWeekProps}
-            key={weekIndex}
-            week={week}
-            weekIndex={weekIndex}
-            rowClassName={classNames.weekRow}
+            week={firstWeek}
+            weekIndex={-1}
+            rowClassName={classNames.firstTransitionWeek}
+            aria-role="presentation"
+            ariaHidden={true}
           />
+        </DirectionalSlide>
+        {weeks!.slice(1, weeks!.length - 1).map((week: DayInfo[], weekIndex: number) => (
+          <DirectionalSlide key={weekIndex + '_' + week[0].key} {...{ animationDirection, animateBackwards }}>
+            <CalendarGridRow
+              {...props}
+              {...partialWeekProps}
+              key={weekIndex}
+              week={week}
+              weekIndex={weekIndex}
+              rowClassName={classNames.weekRow}
+            />
+          </DirectionalSlide>
         ))}
-        <CalendarGridRow
-          {...props}
-          {...partialWeekProps}
-          week={weeks![weeks!.length - 1]}
-          weekIndex={-2}
-          rowClassName={classNames.lastTransitionWeek}
-          aria-role="presentation"
-          ariaHidden={true}
-        />
+        <DirectionalSlide key={'lastTransitionWeek_' + finalWeek[0].key} {...{ animationDirection, animateBackwards }}>
+          <CalendarGridRow
+            {...props}
+            {...partialWeekProps}
+            week={finalWeek}
+            weekIndex={-2}
+            rowClassName={classNames.lastTransitionWeek}
+            aria-role="presentation"
+            ariaHidden={true}
+          />
+        </DirectionalSlide>
       </tbody>
     </table>
   );

packages/react-components/react-calendar-compat/library/src/components/CalendarDayGrid/CalendarGridRow.tsx

@@ -1,3 +1,5 @@
+'use client';
+
 import * as React from 'react';
 import { getWeekNumbersInMonth } from '../../utils';
 import { CalendarGridDayCell } from './CalendarGridDayCell';
@@ -28,7 +30,7 @@ export interface CalendarGridRowProps extends CalendarDayGridProps {
 /**
  * @internal
  */
-export const CalendarGridRow: React.FunctionComponent<CalendarGridRowProps> = props => {
+export const CalendarGridRow = React.forwardRef<HTMLTableRowElement, CalendarGridRowProps>((props, ref) => {
   const {
     ariaHidden,
     classNames,
@@ -52,7 +54,7 @@ export const CalendarGridRow: React.FunctionComponent<CalendarGridRowProps> = pr
     : '';
 
   return (
-    <tr role={ariaRole} aria-hidden={ariaHidden} className={rowClassName} key={weekIndex + '_' + week[0].key}>
+    <tr ref={ref} role={ariaRole} aria-hidden={ariaHidden} className={rowClassName} key={weekIndex + '_' + week[0].key}>
       {showWeekNumbers && weekNumbers && (
         <th
           className={classNames.weekNumberCell}
@@ -69,4 +71,6 @@ export const CalendarGridRow: React.FunctionComponent<CalendarGridRowProps> = pr
       ))}
     </tr>
   );
-};
+});
+
+CalendarGridRow.displayName = 'CalendarGridRow';