feat(clerk-js): Add dev mode notice to components

.changeset/hungry-clouds-return.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': minor
+"@clerk/types": minor
+---
+
+Add a development mode notice to components and also introduce `popoverBox` descriptor.

packages/clerk-js/src/ui/components/CreateOrganization/CreateOrganizationPage.tsx

@@ -1,6 +1,6 @@
 import { useClerk } from '@clerk/shared/react';
 
-import { useCreateOrganizationContext } from '../../contexts';
+import { useCreateOrganizationContext, useEnvironment } from '../../contexts';
 import { localizationKeys } from '../../customizables';
 import { Card, useCardState, withCardStateProvider } from '../../elements';
 import { CreateOrganizationForm } from './CreateOrganizationForm';
@@ -10,10 +10,13 @@ export const CreateOrganizationPage = withCardStateProvider(() => {
 
   const { mode, navigateAfterCreateOrganization, skipInvitationScreen } = useCreateOrganizationContext();
   const card = useCardState();
+  const { isDevelopmentOrStaging } = useEnvironment();
 
   return (
     <Card.Root sx={t => ({ width: t.sizes.$108 })}>
-      <Card.Content sx={t => ({ padding: `${t.space.$4} ${t.space.$5} ${t.space.$6}` })}>
+      <Card.Content
+        sx={t => ({ padding: `${t.space.$4} ${t.space.$5} ${isDevelopmentOrStaging() ? t.space.$12 : t.space.$6}` })}
+      >
         <Card.Alert>{card.error}</Card.Alert>
         <CreateOrganizationForm
           skipInvitationScreen={skipInvitationScreen}

packages/clerk-js/src/ui/customizables/elementDescriptors.ts

@@ -24,6 +24,7 @@ export const APPEARANCE_KEYS = containsAllElementsConfigKeys([
   'cardBox',
   'card',
   'footerItem',
+  'popoverBox',
 
   'actionCard',
 

packages/clerk-js/src/ui/elements/Card/CardClerkAndPagesTag.tsx

@@ -1,52 +1,90 @@
 import React from 'react';
 
 import { useEnvironment } from '../../contexts';
-import { Flex, Icon, Link, Text } from '../../customizables';
+import { Box, Col, Flex, Icon, Link, Text } from '../../customizables';
 import { LogoMark } from '../../icons';
-import type { PropsOfComponent } from '../../styledSystem';
+import type { PropsOfComponent, ThemableCssProp } from '../../styledSystem';
+import { DevModeNotice, DevModeOverlay } from '../DevModeNotice';
 import { Card } from '.';
 
 export const CardClerkAndPagesTag = React.memo(
-  React.forwardRef<HTMLDivElement, PropsOfComponent<typeof Flex> & { withFooterPages?: boolean }>((props, ref) => {
-    const { sx, withFooterPages = false, ...rest } = props;
-    const { branded } = useEnvironment().displayConfig;
+  React.forwardRef<
+    HTMLDivElement,
+    PropsOfComponent<typeof Flex> & {
+      withFooterPages?: boolean;
+      devModeNoticeSx?: ThemableCssProp;
+      outerSx?: ThemableCssProp;
+      withDevOverlay?: boolean;
+    }
+  >((props, ref) => {
+    const { sx, outerSx, withFooterPages = false, withDevOverlay = false, devModeNoticeSx, ...rest } = props;
+    const { displayConfig, isDevelopmentOrStaging } = useEnvironment();
+    const withDevModeNotice = isDevelopmentOrStaging();
 
-    if (!(branded || withFooterPages)) {
+    if (!(displayConfig.branded || withFooterPages) && !withDevModeNotice) {
       return null;
     }
 
     return (
-      <Flex
+      <Box
         sx={[
-          t => ({
-            ':has(div:only-child)': {
-              justifyContent: 'center',
-            },
-            justifyContent: 'space-between',
+          {
             width: '100%',
-            padding: `0 ${t.space.$8}`,
-          }),
-          sx,
+            position: 'relative',
+            isolation: 'isolate',
+          },
+          outerSx,
         ]}
-        {...rest}
-        ref={ref}
       >
-        {branded && (
-          <Flex
-            gap={1}
-            align='center'
-            justify='center'
-            sx={t => ({ color: t.colors.$colorTextSecondary })}
-          >
-            <>
-              <Text variant='buttonSmall'>Secured by</Text>
-              <LogoMarkIconLink />
-            </>
-          </Flex>
-        )}
+        {withDevOverlay && <DevModeOverlay gradient={0} />}
+        <Col
+          sx={t => ({
+            gap: displayConfig.branded || withFooterPages ? t.space.$2 : 0,
+            marginLeft: 'auto',
+            marginRight: 'auto',
+            width: '100%',
+            justifyContent: 'center',
+            alignItems: 'center',
+            zIndex: 1,
+            position: 'relative',
+          })}
+        >
+          {(displayConfig.branded || withFooterPages) && (
+            <Flex
+              sx={[
+                {
+                  ':has(div:only-child)': {
+                    justifyContent: 'center',
+                  },
+                  justifyContent: 'space-between',
+                  width: '100%',
+                },
+                sx,
+              ]}
+              {...rest}
+              ref={ref}
+            >
+              {displayConfig.branded && (
+                <Flex
+                  gap={1}
+                  align='center'
+                  justify='center'
+                  sx={t => ({ color: t.colors.$colorTextSecondary })}
+                >
+                  <>
+                    <Text variant='buttonSmall'>Secured by</Text>
+                    <LogoMarkIconLink />
+                  </>
+                </Flex>
+              )}
+
+              {withFooterPages && <Card.FooterLinks />}
+            </Flex>
+          )}
 
-        {withFooterPages && <Card.FooterLinks />}
-      </Flex>
+          <DevModeNotice sx={devModeNoticeSx} />
+        </Col>
+      </Box>
     );
   }),
 );

packages/clerk-js/src/ui/elements/Card/CardContent.tsx

@@ -10,7 +10,7 @@ import {
   useLocalizations,
 } from '../../customizables';
 import { Close } from '../../icons';
-import { type PropsOfComponent } from '../../styledSystem';
+import type { PropsOfComponent } from '../../styledSystem';
 import { useCardState, useFlowMetadata } from '../contexts';
 import { IconButton } from '../IconButton';
 import { useUnsafeModalContext } from '../Modal';
@@ -24,6 +24,7 @@ export const CardContent = React.forwardRef<HTMLDivElement, CardContentProps>((p
   const { maintenanceMode } = useEnvironment();
   const card = useCardState();
   const { t } = useLocalizations();
+  const { isDevelopmentOrStaging } = useEnvironment();
 
   return (
     <Flex
@@ -43,7 +44,7 @@ export const CardContent = React.forwardRef<HTMLDivElement, CardContentProps>((p
           boxShadow: t.shadows.$cardContentShadow,
           borderRadius: t.radii.$lg,
           position: 'relative',
-          padding: `${t.space.$8} ${t.space.$10}`,
+          padding: `${t.space.$8} ${t.space.$10} ${isDevelopmentOrStaging() ? t.space.$12 : t.space.$8} ${t.space.$10}`,
           justifyContent: 'center',
           alignContent: 'center',
         }),

packages/clerk-js/src/ui/elements/Card/CardFooter.tsx

@@ -12,12 +12,14 @@ type CardFooterProps = PropsOfComponent<typeof Flex> & {
 };
 export const CardFooter = React.forwardRef<HTMLDivElement, CardFooterProps>((props, ref) => {
   const { children, isProfileFooter = false, sx, ...rest } = props;
-  const { branded } = useEnvironment().displayConfig;
+  const { displayConfig, isDevelopmentOrStaging } = useEnvironment();
+  const { branded } = displayConfig;
+  const withDevModeNotice = isDevelopmentOrStaging();
   const { helpPageUrl, privacyPageUrl, termsPageUrl } = useAppearance().parsedLayout;
   const sponsorOrLinksExist = !!(branded || helpPageUrl || privacyPageUrl || termsPageUrl);
   const showSponsorAndLinks = isProfileFooter ? branded : sponsorOrLinksExist;
 
-  if (!children && !showSponsorAndLinks) {
+  if (!children && !(showSponsorAndLinks || withDevModeNotice)) {
     return null;
   }
 
@@ -64,7 +66,13 @@ export const CardFooter = React.forwardRef<HTMLDivElement, CardFooterProps>((pro
     >
       {children}
 
-      {showSponsorAndLinks && <Card.ClerkAndPagesTag withFooterPages={!isProfileFooter} />}
+      <Card.ClerkAndPagesTag
+        withFooterPages={showSponsorAndLinks && !isProfileFooter}
+        devModeNoticeSx={t => ({
+          padding: t.space.$none,
+        })}
+        withDevOverlay
+      />
     </Flex>
   );
 });

packages/clerk-js/src/ui/elements/DevModeNotice.tsx

@@ -0,0 +1,55 @@
+import type { ThemableCssProp } from 'ui/styledSystem';
+
+import { useEnvironment } from '../contexts';
+import { Box, Text } from '../customizables';
+
+type DevModeOverlayProps = {
+  gradient?: number;
+};
+
+export const DevModeOverlay = (props: DevModeOverlayProps) => {
+  const { gradient = 60 } = props;
+  const { isDevelopmentOrStaging } = useEnvironment();
+
+  if (!isDevelopmentOrStaging()) {
+    return null;
+  }
+
+  return (
+    <Box
+      sx={t => ({
+        userSelect: 'none',
+        pointerEvents: 'none',
+        inset: 0,
+        position: 'absolute',
+        background: `repeating-linear-gradient(-45deg,${t.colors.$warningAlpha100},${t.colors.$warningAlpha100} 6px,${t.colors.$warningAlpha150} 6px,${t.colors.$warningAlpha150} 12px)`,
+        maskImage: `linear-gradient(transparent ${gradient}%, black)`,
+      })}
+    />
+  );
+};
+
+type DevModeNoticeProps = { sx?: ThemableCssProp };
+export const DevModeNotice = (props: DevModeNoticeProps) => {
+  const { sx } = props;
+  const { isDevelopmentOrStaging } = useEnvironment();
+
+  if (!isDevelopmentOrStaging()) {
+    return null;
+  }
+
+  return (
+    <Text
+      sx={[
+        t => ({
+          color: t.colors.$warning500,
+          fontWeight: t.fontWeights.$semibold,
+          padding: t.space.$1x5,
+        }),
+        sx,
+      ]}
+    >
+      Development mode
+    </Text>
+  );
+};

packages/clerk-js/src/ui/elements/Navbar.tsx

@@ -12,6 +12,7 @@ import { animations, common, mqu } from '../styledSystem';
 import { colors } from '../utils';
 import { Card } from './Card';
 import { withFloatingTree } from './contexts';
+import { DevModeOverlay } from './DevModeNotice';
 import { Popover } from './Popover';
 
 type NavbarContextValue = { isOpen: boolean; open: () => void; close: () => void };
@@ -140,6 +141,7 @@ const NavbarContainer = (
         },
         flex: `0 0 ${t.space.$57}`,
         width: t.sizes.$57,
+        position: 'relative',
         maxWidth: t.space.$57,
         background: common.mergedColorsBackground(
           colors.setAlpha(t.colors.$colorBackground, 1),
@@ -151,6 +153,8 @@ const NavbarContainer = (
         justifyContent: 'space-between',
       })}
     >
+      <DevModeOverlay />
+
       <Col sx={t => ({ gap: t.space.$6, flex: `0 0 ${t.space.$60}` })}>
         <Col
           sx={t => ({
@@ -172,10 +176,9 @@ const NavbarContainer = (
       </Col>
 
       <Card.ClerkAndPagesTag
-        sx={theme => ({
+        sx={{
           width: 'fit-content',
-          paddingLeft: theme.space.$3,
-        })}
+        }}
       />
     </Col>
   );

packages/clerk-js/src/ui/elements/PopoverCard.tsx

@@ -1,17 +1,20 @@
 import React from 'react';
 
 import { useEnvironment } from '../contexts';
-import { Col, Flex, Flow, useAppearance } from '../customizables';
+import { Col, descriptors, Flex, Flow, useAppearance } from '../customizables';
+import type { ElementDescriptor } from '../customizables/elementDescriptors';
 import type { PropsOfComponent } from '../styledSystem';
 import { animations, common } from '../styledSystem';
 import { colors } from '../utils';
 import { Card } from '.';
 
 const PopoverCardRoot = React.forwardRef<HTMLDivElement, PropsOfComponent<typeof Card.Content>>((props, ref) => {
+  const { elementDescriptor, ...rest } = props;
   return (
     <Flow.Part part='popover'>
       <Card.Root
-        {...props}
+        elementDescriptor={[descriptors.popoverBox, elementDescriptor as ElementDescriptor]}
+        {...rest}
         ref={ref}
         sx={t => ({
           width: t.sizes.$94,
@@ -70,8 +73,6 @@ const PopoverCardFooter = (props: PropsOfComponent<typeof Flex>) => {
           ),
           marginTop: `-${t.space.$2}`,
           paddingTop: t.space.$2,
-          borderBottomLeftRadius: 'inherit',
-          borderBottomRightRadius: 'inherit',
           '&:empty': {
             padding: 0,
             marginTop: 0,
@@ -89,12 +90,16 @@ const PopoverCardFooter = (props: PropsOfComponent<typeof Flex>) => {
     >
       {children}
 
-      {shouldShowTagOrLinks && (
-        <Card.ClerkAndPagesTag
-          withFooterPages
-          sx={t => ({ padding: `${t.space.$4} ${t.space.$8}` })}
-        />
-      )}
+      <Card.ClerkAndPagesTag
+        outerSx={t => ({
+          padding: `${t.space.$4} ${t.space.$none}`,
+        })}
+        withFooterPages={!!shouldShowTagOrLinks}
+        devModeNoticeSx={t => ({
+          padding: t.space.$none,
+        })}
+        withDevOverlay
+      />
     </Col>
   );
 };

packages/clerk-js/src/ui/elements/index.ts

@@ -55,3 +55,4 @@ export * from './Card';
 export * from './ProfileCard';
 export * from './Gauge';
 export * from './Animated';
+export * from './DevModeNotice';

packages/clerk-js/src/ui/polishedAppearance.ts

@@ -164,6 +164,10 @@ export const polishedAppearance: Appearance = {
         borderWidth: 0,
         boxShadow: `${theme.shadows.$cardBoxShadow}, ${BORDER_SHADOW_LENGTH} ${theme.colors.$neutralAlpha100}`,
       },
+      popoverBox: {
+        borderWidth: 0,
+        boxShadow: `${theme.shadows.$cardBoxShadow}, ${BORDER_SHADOW_LENGTH} ${theme.colors.$neutralAlpha100}`,
+      },
       card: {
         ...cardContentStyles(theme),
       },

packages/types/src/appearance.ts

@@ -143,6 +143,7 @@ export type ElementsConfig = {
   cardBox: WithOptions;
   card: WithOptions;
   actionCard: WithOptions;
+  popoverBox: WithOptions;
 
   logoBox: WithOptions;
   logoImage: WithOptions;