Polaris tokens major version upgrades (#10801)

This PR introduces breaking changes, including additions and deprecations, as part of the major version upgrade to `@shopify/polaris-tokens`. The key changes include: - Introduced `themeNameDefault` constant. - Deprecated `tokens` export (replace with `themeDefault`). - Introduced `themeDefault` export (convenience alias for `themes[themeNameDefault]`). - Deprecated all individual token group exports e.g. `color`, `space`, `motion`, etc... - Deprecated `metadata` export (replace with `metaThemeDefault`). - Introduced `metaThemeDefault` export (convenience alias for `metaThemes[themeNameDefault]`). - Introduced new theme types: * `ThemeName` * `MetaTheme` * `MetaThemeShape` * `MetaTokenGroupShape` * `MetaTokenProperties` * `Theme` - Renamed `MetadataGroup` to `MetaTokenGroupShape`. - Renamed `getCustomPropertyNames` to `getThemeVarNames`. - Introduced `isTokenName` type guard (ensure an unknown value is a valid theme token). - Updated `createVar` utility (now creates a complete CSS variable function e.g. ```ts // Before: createVar('token-name') //=> '--p-token-name' // After: createVar('token-name') //=> 'var(--p-token-name)' ``` - Renamed `createVar` to `createVarName`. - Introduced `createVarName` utility (behaves similar to the legacy `createVar` utility). - Exposed `metaThemes` object containing all meta theme objects (useful for low level integrations such as the Polaris site, Polaris for VS Code, etc...). - Deprecated a collection of unintentionally exposed Polaris utils and types: * `getUnit` * `toEm` * `rem` * `tokensToRems` * `getKeyframeNames` * `removeMetadata` * `MetaBreakpointsTokenGroup` * `BreakpointsAliasDirectionMediaConditions` * `BreakpointsMediaConditions` * `isKeyOf` * `createExact` * `createMetadata` - Deprecated `@shopify/polaris-tokens/json` entry point. --------- Co-authored-by: Sophie Schneider <thesophieschneider@gmail.com>
Shopify · Oct 3, 2023 · 2cdc59f · 2cdc59f
1 parent 05b1dcd
commit 2cdc59f
Show file tree

Hide file tree

Showing 44 changed files with 447 additions and 326 deletions.
diff --git a/.changeset/gentle-suns-relax.md b/.changeset/gentle-suns-relax.md
@@ -0,0 +1,5 @@
+---
+'@shopify/polaris-tokens': major
+---
+
+Deprecated a collection of types, utils, and JSON exports
diff --git a/polaris-for-vscode/src/server.ts b/polaris-for-vscode/src/server.ts
@@ -1,5 +1,9 @@
-import {createVar, metadata} from '@shopify/polaris-tokens';
-import type {MetadataGroup} from '@shopify/polaris-tokens';
+import type {MetaTheme, MetaTokenGroupShape} from '@shopify/polaris-tokens';
+import {
+  createVarName,
+  metaThemeDefault,
+  isTokenName,
+} from '@shopify/polaris-tokens';
 import {
   createConnection,
   TextDocuments,
@@ -19,16 +23,16 @@ const excludedTokenGroupNames = [] as const;
 
 type ExcludedTokenGroupName = typeof excludedTokenGroupNames[number];
 
-type TokenGroupName = Exclude<keyof typeof metadata, ExcludedTokenGroupName>;
+type TokenGroupName = Exclude<keyof MetaTheme, ExcludedTokenGroupName>;
 
 const tokenGroups = Object.fromEntries(
-  Object.entries(metadata).filter(
+  Object.entries(metaThemeDefault).filter(
     ([tokenGroupName]) =>
       !excludedTokenGroupNames.includes(
         tokenGroupName as ExcludedTokenGroupName,
       ),
   ),
-) as unknown as Omit<typeof metadata, ExcludedTokenGroupName>;
+) as unknown as Omit<MetaTheme, ExcludedTokenGroupName>;
 
 type TokenGroupCompletionItems = {
   [T in TokenGroupName]: CompletionItem[];
@@ -39,19 +43,25 @@ type TokenGroupCompletionItems = {
  */
 const tokenGroupCompletionItems = Object.fromEntries(
   Object.entries(tokenGroups).map(
-    ([tokenGroupName, tokenGroup]: [string, MetadataGroup]) => {
+    ([tokenGroupName, tokenGroup]: [string, MetaTokenGroupShape]) => {
       const completionItems: CompletionItem[] = Object.entries(tokenGroup).map(
-        ([tokenName, tokenProperties]): CompletionItem => ({
-          label: createVar(tokenName),
-          insertText: `${createVar(tokenName)}`,
-          detail: tokenProperties.value,
-          documentation: tokenProperties.description,
-          filterText: createVar(tokenName),
-          kind:
-            tokenGroupName === 'color'
-              ? CompletionItemKind.Color
-              : CompletionItemKind.Variable,
-        }),
+        ([tokenName, tokenProperties]): CompletionItem => {
+          if (!isTokenName(tokenName)) {
+            throw new Error(`Invalid token name: ${tokenName}`);
+          }
+
+          return {
+            label: createVarName(tokenName),
+            insertText: `${createVarName(tokenName)}`,
+            detail: tokenProperties.value,
+            documentation: tokenProperties.description,
+            filterText: createVarName(tokenName),
+            kind:
+              tokenGroupName === 'color'
+                ? CompletionItemKind.Color
+                : CompletionItemKind.Variable,
+          };
+        },
       );
 
       return [tokenGroupName, completionItems];

diff --git a/polaris-migrator/src/migrations/v9-scss-replace-color/transform.ts b/polaris-migrator/src/migrations/v9-scss-replace-color/transform.ts
@@ -2,7 +2,6 @@ import type {FileInfo, API, Options} from 'jscodeshift';
 import type {Plugin} from 'postcss';
 import postcss from 'postcss';
 import valueParser from 'postcss-value-parser';
-import {createVar} from '@shopify/polaris-tokens';
 
 import type {NamespaceOptions} from '../../utilities/sass';
 import {
@@ -239,5 +238,7 @@ const propertyMaps = {
 };
 
 const polarisCustomPropertyRegEx = new RegExp(
-  Object.keys(tokenColors).map(createVar).join('|'),
+  Object.keys(tokenColors)
+    .map((tokenName) => `--p-${tokenName}`)
+    .join('|'),
 );
diff --git a/polaris-migrator/src/utilities/sass.ts b/polaris-migrator/src/utilities/sass.ts
@@ -18,14 +18,14 @@ import type {
   Dimension,
 } from 'postcss-value-parser';
 import valueParser from 'postcss-value-parser';
-import {toPx, getCustomPropertyNames, tokens} from '@shopify/polaris-tokens';
+import {toPx, getThemeVarNames, themeDefault} from '@shopify/polaris-tokens';
 
 import {POLARIS_MIGRATOR_COMMENT} from './constants';
 
 const defaultNamespace = '';
 
-const polarisCustomPropertyRegEx = new RegExp(
-  getCustomPropertyNames(tokens).join('|'),
+const themeVarNamesRegExp = new RegExp(
+  getThemeVarNames(themeDefault).join('|'),
 );
 
 function getNamespace(options?: NamespaceOptions) {
@@ -325,7 +325,7 @@ export function isTransformableDuration(
 export function isPolarisVar(node: Node): boolean {
   return (
     isSassFunction('var', node) &&
-    polarisCustomPropertyRegEx.test(node.nodes?.[0]?.value ?? '')
+    themeVarNamesRegExp.test(node.nodes?.[0]?.value ?? '')
   );
 }
 

diff --git a/polaris-react/src/components/ActionList/components/Item/Item.tsx b/polaris-react/src/components/ActionList/components/Item/Item.tsx
@@ -1,5 +1,4 @@
 import React, {useRef, useState} from 'react';
-import {zIndex} from '@shopify/polaris-tokens';
 
 import {classNames} from '../../../../utilities/css';
 import type {ActionListItemDescriptor} from '../../../../types';
@@ -14,6 +13,7 @@ import {InlineStack} from '../../../InlineStack';
 import {Box} from '../../../Box';
 import {Tooltip} from '../../../Tooltip';
 import {useIsomorphicLayoutEffect} from '../../../../utilities/use-isomorphic-layout-effect';
+import {useTheme} from '../../../../utilities/use-theme';
 
 export type ItemProps = ActionListItemDescriptor;
 
@@ -155,6 +155,7 @@ export function Item({
 }
 
 export const TruncateText = ({children}: {children: string}) => {
+  const theme = useTheme();
   const textRef = useRef<HTMLSpanElement>(null);
   const [isOverflowing, setIsOverflowing] = useState(false);
   useIsomorphicLayoutEffect(() => {
@@ -174,7 +175,7 @@ export const TruncateText = ({children}: {children: string}) => {
 
   return isOverflowing ? (
     <Tooltip
-      zIndexOverride={Number(zIndex['z-index-11'])}
+      zIndexOverride={Number(theme.zIndex['z-index-11'])}
       preferredPosition="above"
       hoverDelay={1000}
       content={children}

diff --git a/polaris-react/src/components/Frame/Frame.tsx b/polaris-react/src/components/Frame/Frame.tsx
@@ -2,7 +2,6 @@ import React, {PureComponent, createRef} from 'react';
 import type {MouseEvent} from 'react';
 import {MobileCancelMajor} from '@shopify/polaris-icons';
 import {CSSTransition} from 'react-transition-group';
-import {motion} from '@shopify/polaris-tokens';
 
 import {useI18n} from '../../utilities/i18n';
 import {useMediaQuery} from '../../utilities/media-query';
@@ -21,6 +20,7 @@ import type {
   ToastID,
   ToastPropsWithID,
 } from '../../utilities/frame';
+import {UseTheme} from '../../utilities/use-theme';
 
 import {
   ToastManager,
@@ -136,44 +136,48 @@ class FrameInner extends PureComponent<CombinedProps, State> {
     };
 
     const navigationMarkup = navigation ? (
-      <TrapFocus trapping={mobileNavShowing}>
-        <CSSTransition
-          nodeRef={this.navigationNode}
-          appear={isNavigationCollapsed}
-          exit={isNavigationCollapsed}
-          in={showMobileNavigation}
-          timeout={parseInt(motion['motion-duration-300'], 10)}
-          classNames={navTransitionClasses}
-        >
-          <div
-            key="NavContent"
-            {...mobileNavAttributes}
-            aria-label={i18n.translate('Polaris.Frame.navigationLabel')}
-            ref={this.navigationNode}
-            className={navClassName}
-            onKeyDown={this.handleNavKeydown}
-            id={APP_FRAME_NAV}
-            hidden={mobileNavHidden}
-          >
-            {navigation}
-            <button
-              type="button"
-              className={styles.NavigationDismiss}
-              onClick={this.handleNavigationDismiss}
-              aria-hidden={
-                mobileNavHidden ||
-                (!isNavigationCollapsed && !showMobileNavigation)
-              }
-              aria-label={i18n.translate(
-                'Polaris.Frame.Navigation.closeMobileNavigationLabel',
-              )}
-              tabIndex={tabIndex}
+      <UseTheme>
+        {(theme) => (
+          <TrapFocus trapping={mobileNavShowing}>
+            <CSSTransition
+              nodeRef={this.navigationNode}
+              appear={isNavigationCollapsed}
+              exit={isNavigationCollapsed}
+              in={showMobileNavigation}
+              timeout={parseInt(theme.motion['motion-duration-300'], 10)}
+              classNames={navTransitionClasses}
             >
-              <Icon source={MobileCancelMajor} />
-            </button>
-          </div>
-        </CSSTransition>
-      </TrapFocus>
+              <div
+                key="NavContent"
+                {...mobileNavAttributes}
+                aria-label={i18n.translate('Polaris.Frame.navigationLabel')}
+                ref={this.navigationNode}
+                className={navClassName}
+                onKeyDown={this.handleNavKeydown}
+                id={APP_FRAME_NAV}
+                hidden={mobileNavHidden}
+              >
+                {navigation}
+                <button
+                  type="button"
+                  className={styles.NavigationDismiss}
+                  onClick={this.handleNavigationDismiss}
+                  aria-hidden={
+                    mobileNavHidden ||
+                    (!isNavigationCollapsed && !showMobileNavigation)
+                  }
+                  aria-label={i18n.translate(
+                    'Polaris.Frame.Navigation.closeMobileNavigationLabel',
+                  )}
+                  tabIndex={tabIndex}
+                >
+                  <Icon source={MobileCancelMajor} />
+                </button>
+              </div>
+            </CSSTransition>
+          </TrapFocus>
+        )}
+      </UseTheme>
     ) : null;
 
     const loadingMarkup =

diff --git a/polaris-react/src/components/IndexTable/IndexTable.tsx b/polaris-react/src/components/IndexTable/IndexTable.tsx
@@ -1,7 +1,7 @@
 import React, {useRef, useState, useEffect, useCallback, useMemo} from 'react';
 import {SortAscendingMajor, SortDescendingMajor} from '@shopify/polaris-icons';
 import {CSSTransition} from 'react-transition-group';
-import {tokens, toPx, motion} from '@shopify/polaris-tokens';
+import {themeDefault, toPx} from '@shopify/polaris-tokens';
 
 import {debounce} from '../../utilities/debounce';
 import {useToggle} from '../../utilities/use-toggle';
@@ -39,6 +39,7 @@ import type {
   Width,
   TooltipOverlayProps,
 } from '../Tooltip';
+import {useTheme} from '../../utilities/use-theme';
 
 import {getTableHeadingsBySelector} from './utilities';
 import {ScrollContainer, Cell, Row} from './components';
@@ -146,6 +147,8 @@ function IndexTableBase({
   hasZebraStriping,
   ...restProps
 }: IndexTableBaseProps) {
+  const theme = useTheme();
+
   const {
     loading,
     bulkSelectState,
@@ -546,7 +549,7 @@ function IndexTableBase({
     <CSSTransition
       in={loading}
       classNames={loadingTransitionClassNames}
-      timeout={parseInt(motion['motion-duration-100'], 10)}
+      timeout={parseInt(theme.motion['motion-duration-100'], 10)}
       nodeRef={loadingElement}
       appear
       unmountOnExit
@@ -1135,7 +1138,7 @@ const isBreakpointsXS = () => {
   return typeof window === 'undefined'
     ? false
     : window.innerWidth <
-        parseFloat(toPx(tokens.breakpoints['breakpoints-sm']) ?? '');
+        parseFloat(toPx(themeDefault.breakpoints['breakpoints-sm']) ?? '');
 };
 
 function getHeadingKey(heading: IndexTableHeading): string {

diff --git a/polaris-react/src/components/Modal/components/Dialog/Dialog.tsx b/polaris-react/src/components/Modal/components/Dialog/Dialog.tsx
@@ -1,7 +1,6 @@
 import React, {useContext, useRef, useEffect} from 'react';
 import type {SetStateAction, Dispatch} from 'react';
 import {Transition, CSSTransition} from 'react-transition-group';
-import {motion} from '@shopify/polaris-tokens';
 
 import {classNames, variationName} from '../../../../utilities/css';
 import {focusFirstFocusableNode} from '../../../../utilities/focus';
@@ -11,6 +10,7 @@ import {TrapFocus} from '../../../TrapFocus';
 import type {ModalSize} from '../../Modal';
 import {Text} from '../../../Text';
 import {FrameContext} from '../../../../utilities/frame';
+import {useTheme} from '../../../../utilities/use-theme';
 
 import styles from './Dialog.scss';
 
@@ -43,6 +43,7 @@ export function Dialog({
   hasToasts,
   ...props
 }: DialogProps) {
+  const theme = useTheme();
   const containerNode = useRef<HTMLDivElement>(null);
   const frameContext = useContext(FrameContext);
   let toastMessages;
@@ -95,7 +96,7 @@ export function Dialog({
       nodeRef={containerNode}
       mountOnEnter
       unmountOnExit
-      timeout={parseInt(motion['motion-duration-200'], 10)}
+      timeout={parseInt(theme.motion['motion-duration-200'], 10)}
       onEntered={onEntered}
       onExited={onExited}
     >