Add createViewTransition function (#1450)

Co-authored-by: Adam Skoufis <[email protected]>

Author: wuz

.changeset/good-wombats-doubt.md

@@ -0,0 +1,5 @@
+---
+"@vanilla-extract/babel-plugin-debug-ids": minor
+---
+
+Add support for the new `createViewTransition` API

.changeset/purple-cheetahs-hear.md

@@ -0,0 +1,20 @@
+---
+"@vanilla-extract/css": minor
+---
+
+Add `createViewTransition` API
+
+`createViewTransition` creates a single scoped view transition name for use with CSS View Transitions. This avoids potential naming collisions with other view transitions.
+
+```ts
+import {
+  style,
+  createViewTransition
+} from '@vanilla-extract/css';
+
+export const titleViewTransition = createViewTransition();
+
+export const pageTitle = style({
+  viewTransitionName: titleViewTransition
+});
+``

packages/babel-plugin-debug-ids/src/index.test.ts

@@ -230,6 +230,19 @@ describe('babel plugin', () => {
     `);
   });
 
+  it('should handle createViewTransition assigned to const', () => {
+    const source = `
+      import { createViewTransition } from '@vanilla-extract/css';
+
+      const myViewTransition = createViewTransition();
+    `;
+
+    expect(transform(source)).toMatchInlineSnapshot(`
+      import { createViewTransition } from '@vanilla-extract/css';
+      const myViewTransition = createViewTransition("myViewTransition");
+    `);
+  });
+
   it('should handle fontFace assigned to const', () => {
     const source = `
       import { fontFace } from '@vanilla-extract/css';

packages/babel-plugin-debug-ids/src/index.ts

@@ -39,6 +39,9 @@ const debuggableFunctionConfig = {
   createContainer: {
     maxParams: 1,
   },
+  createViewTransition: {
+    maxParams: 1,
+  },
   layer: {
     maxParams: 2,
     hasDebugId: ({ arguments: args }) => {

packages/css/src/index.ts

@@ -13,4 +13,5 @@ export * from './theme';
 export * from './style';
 export * from './vars';
 export { createContainer } from './container';
+export { createViewTransition } from './viewTransition';
 export * from './layer';

packages/css/src/viewTransition.ts

@@ -0,0 +1,6 @@
+import { generateIdentifier } from './identifier';
+
+// createViewTransition is used for locally scoping CSS view transitions
+// For now it is mostly just an alias of generateIdentifier
+export const createViewTransition = (debugId?: string) =>
+  generateIdentifier(debugId);

site/contents.js

@@ -25,6 +25,7 @@ const contents = [
       'keyframes',
       'create-container',
       'layer',
+      'create-view-transition',
       'add-function-serializer',
     ],
   },

site/docs/api/create-view-transition.md

@@ -0,0 +1,37 @@
+---
+title: createViewTransition
+parent: api
+---
+
+# createViewTransition
+
+Creates a single scoped view transition name for use with [CSS View Transitions].
+This avoids potential naming collisions with other view transitions.
+
+> 🚧  Ensure your target browsers [support view transitions].
+> Vanilla-extract supports the [view transition syntax][css view transitions] but does not polyfill the feature in unsupported browsers.
+
+```ts compiled
+// itemPage.css.ts
+import {
+  style,
+  createViewTransition
+} from '@vanilla-extract/css';
+
+export const titleViewTransition = createViewTransition();
+
+export const pageTitle = style({
+  viewTransitionName: titleViewTransition
+});
+
+// navigation.css.ts
+import { style } from '@vanilla-extract/css';
+import { titleViewTransition } from './itemPage.css.ts';
+
+export const navigationLinkTitle = style({
+  viewTransitionName: titleViewTransition
+});
+```
+
+[css view transitions]: https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API#css_additions
+[support view transitions]: https://caniuse.com/view-transitions