Refactor the captcha properties to exist directly under the appearance

.changeset/fluffy-hairs-thank.md

@@ -3,4 +3,4 @@
 '@clerk/types': minor
 ---
 
-Introduce layout configuration options for the appearance of the Turnstile widget
+Introduce the `captcha` appearance property for the CAPTCHA widget

packages/clerk-js/src/ui/components/BlankCaptchaModal/index.tsx

@@ -3,11 +3,11 @@ import { Card, withCardStateProvider } from '../../elements';
 import { Route, Switch } from '../../router';
 
 const BlankCard = withCardStateProvider(() => {
-  const { parsedLayout } = useAppearance();
+  const { parsedCaptcha } = useAppearance();
   const { locale } = useLocalizations();
-  const captchaTheme = parsedLayout?.captchaTheme;
-  const captchaSize = parsedLayout?.captchaSize;
-  const captchaLanguage = parsedLayout?.captchaLanguage || locale;
+  const captchaTheme = parsedCaptcha?.theme;
+  const captchaSize = parsedCaptcha?.size;
+  const captchaLanguage = parsedCaptcha?.language || locale;
 
   return (
     <Card.Root>

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

@@ -1,5 +1,5 @@
 import { fastDeepMergeAndReplace } from '@clerk/shared/utils';
-import type { Appearance, DeepPartial, Elements, Layout, Theme } from '@clerk/types';
+import type { Appearance, CaptchaAppearanceOptions, DeepPartial, Elements, Layout, Theme } from '@clerk/types';
 
 import { createInternalTheme, defaultInternalTheme } from '../foundations';
 import { polishedAppearance } from '../polishedAppearance';
@@ -16,8 +16,12 @@ import {
 export type ParsedElements = Elements[];
 export type ParsedInternalTheme = InternalTheme;
 export type ParsedLayout = Required<Layout>;
+export type ParsedCaptcha = Required<CaptchaAppearanceOptions>;
 
-type PublicAppearanceTopLevelKey = keyof Omit<Appearance, 'baseTheme' | 'elements' | 'layout' | 'variables'>;
+type PublicAppearanceTopLevelKey = keyof Omit<
+  Appearance,
+  'baseTheme' | 'elements' | 'layout' | 'variables' | 'captcha'
+>;
 
 export type AppearanceCascade = {
   globalAppearance?: Appearance;
@@ -29,6 +33,7 @@ export type ParsedAppearance = {
   parsedElements: ParsedElements;
   parsedInternalTheme: ParsedInternalTheme;
   parsedLayout: ParsedLayout;
+  parsedCaptcha: ParsedCaptcha;
 };
 
 const defaultLayout: ParsedLayout = {
@@ -44,9 +49,12 @@ const defaultLayout: ParsedLayout = {
   shimmer: true,
   animations: true,
   unsafe_disableDevelopmentModeWarnings: false,
-  captchaTheme: 'auto',
-  captchaSize: 'normal',
-  captchaLanguage: '',
+};
+
+const defaultCaptchaOptions: ParsedCaptcha = {
+  theme: 'auto',
+  size: 'normal',
+  language: '',
 };
 
 /**
@@ -66,6 +74,7 @@ export const parseAppearance = (cascade: AppearanceCascade): ParsedAppearance =>
 
   const parsedInternalTheme = parseVariables(appearanceList);
   const parsedLayout = parseLayout(appearanceList);
+  const parsedCaptcha = parseCaptcha(appearanceList);
 
   if (
     !appearanceList.find(a => {
@@ -86,7 +95,7 @@ export const parseAppearance = (cascade: AppearanceCascade): ParsedAppearance =>
       return res;
     }),
   );
-  return { parsedElements, parsedInternalTheme, parsedLayout };
+  return { parsedElements, parsedInternalTheme, parsedLayout, parsedCaptcha };
 };
 
 const expand = (theme: Theme | undefined, cascade: any[]) => {
@@ -109,6 +118,13 @@ const parseLayout = (appearanceList: Appearance[]) => {
   return { ...defaultLayout, ...appearanceList.reduce((acc, appearance) => ({ ...acc, ...appearance.layout }), {}) };
 };
 
+const parseCaptcha = (appearanceList: Appearance[]) => {
+  return {
+    ...defaultCaptchaOptions,
+    ...appearanceList.reduce((acc, appearance) => ({ ...acc, ...appearance.captcha }), {}),
+  };
+};
+
 const parseVariables = (appearances: Appearance[]) => {
   const res = {} as DeepPartial<InternalTheme>;
   fastDeepMergeAndReplace({ ...defaultInternalTheme }, res);

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

@@ -14,11 +14,11 @@ export const CaptchaElement = () => {
   const maxHeightValueRef = useRef('0');
   const minHeightValueRef = useRef('unset');
   const marginBottomValueRef = useRef('unset');
-  const { parsedLayout } = useAppearance();
+  const { parsedCaptcha } = useAppearance();
   const { locale } = useLocalizations();
-  const captchaTheme = parsedLayout?.captchaTheme;
-  const captchaSize = parsedLayout?.captchaSize;
-  const captchaLanguage = parsedLayout?.captchaLanguage || locale;
+  const captchaTheme = parsedCaptcha?.theme;
+  const captchaSize = parsedCaptcha?.size;
+  const captchaLanguage = parsedCaptcha?.language || locale;
 
   useEffect(() => {
     if (!elementRef.current) return;

packages/clerk-js/src/utils/captcha/turnstile.ts

@@ -1,6 +1,6 @@
 import { waitForElement } from '@clerk/shared/dom';
 import { loadScript } from '@clerk/shared/loadScript';
-import type { CaptchaWidgetType, Layout } from '@clerk/types';
+import type { CaptchaAppearanceOptions, CaptchaWidgetType } from '@clerk/types';
 
 import { CAPTCHA_ELEMENT_ID, CAPTCHA_INVISIBLE_CLASSNAME } from './constants';
 import type { CaptchaOptions } from './types';
@@ -9,6 +9,12 @@ import type { CaptchaOptions } from './types';
 // CF docs: https://developers.cloudflare.com/turnstile/get-started/client-side-rendering/#disable-implicit-rendering
 const CLOUDFLARE_TURNSTILE_ORIGINAL_URL = 'https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit';
 
+type CaptchaAttributes = {
+  theme?: RenderOptions['theme'];
+  language?: RenderOptions['language'];
+  size: RenderOptions['size'];
+};
+
 interface RenderOptions {
   /**
    * Every widget has a sitekey. This sitekey is associated with the corresponding widget configuration and is created upon the widget creation.
@@ -63,19 +69,19 @@ interface RenderOptions {
    * The default is auto, which respects the user preference. This can be forced to light or dark by setting the theme accordingly.
    * @default 'auto'
    */
-  theme?: Layout['captchaTheme'];
+  theme?: CaptchaAppearanceOptions['theme'];
   /**
    * The widget size. Can take the following values: normal, flexible, compact.
    * @default 'normal'
    */
-  size?: Layout['captchaSize'];
+  size?: CaptchaAppearanceOptions['size'];
   /**
    * Language to display, must be either: auto (default) to use the language that the visitor has chosen,
    * or an ISO 639-1 two-letter language code (e.g. en) or language and country code (e.g. en-US).
    * Refer to the list of supported languages for more information.
    * https://developers.cloudflare.com/turnstile/reference/supported-languages
    */
-  language?: string;
+  language?: CaptchaAppearanceOptions['language'];
   /**
    * A custom value that can be used to differentiate widgets under the same sitekey
    * in analytics and which is returned upon validation. This can only contain up to
@@ -127,10 +133,10 @@ async function loadCaptchaFromCloudflareURL() {
   }
 }
 
-function getCaptchaAttibutesFromElemenet(element: HTMLElement) {
-  const theme = element.getAttribute('data-cl-theme');
-  const language = element.getAttribute('data-cl-language');
-  const size = element.getAttribute('data-cl-size');
+function getCaptchaAttibutesFromElemenet(element: HTMLElement): CaptchaAttributes {
+  const theme = (element.getAttribute('data-cl-theme') as RenderOptions['theme']) || undefined;
+  const language = (element.getAttribute('data-cl-language') as RenderOptions['language']) || undefined;
+  const size = (element.getAttribute('data-cl-size') as RenderOptions['size']) || undefined;
 
   return { theme, language, size };
 }
@@ -170,9 +176,9 @@ export const getTurnstileToken = async (opts: CaptchaOptions) => {
     const modalContainderEl = await waitForElement(modalContainerQuerySelector);
     if (modalContainderEl) {
       const { theme, language, size } = getCaptchaAttibutesFromElemenet(modalContainderEl);
-      captchaTheme = theme as RenderOptions['theme'];
-      captchaLanguage = language as RenderOptions['language'];
-      captchaSize = size as RenderOptions['size'];
+      captchaTheme = theme;
+      captchaLanguage = language;
+      captchaSize = size;
     }
   }
 
@@ -184,9 +190,9 @@ export const getTurnstileToken = async (opts: CaptchaOptions) => {
       widgetContainerQuerySelector = `#${CAPTCHA_ELEMENT_ID}`;
       visibleDiv.style.maxHeight = '0'; // This is to prevent the layout shift when the render method is called
       const { theme, language, size } = getCaptchaAttibutesFromElemenet(visibleDiv);
-      captchaTheme = theme as RenderOptions['theme'];
-      captchaLanguage = language as RenderOptions['language'];
-      captchaSize = size as RenderOptions['size'];
+      captchaTheme = theme;
+      captchaLanguage = language;
+      captchaSize = size;
     } else {
       console.error(
         'Cannot initialize Smart CAPTCHA widget because the `clerk-captcha` DOM element was not found; falling back to Invisible CAPTCHA widget. If you are using a custom flow, visit https://clerk.com/docs/custom-flows/bot-sign-up-protection for instructions',

packages/themes/src/themes/dark.ts

@@ -21,7 +21,4 @@ export const dark = experimental_createTheme({
       '--cl-screen': '#111111',
     },
   },
-  layout: {
-    captchaTheme: 'dark',
-  },
 });

packages/themes/src/themes/shadesOfPurple.ts

@@ -10,7 +10,4 @@ export const shadesOfPurple = experimental_createTheme({
     colorInputText: '#a1fdfe',
     colorShimmer: 'rgba(161,253,254,0.36)',
   },
-  layout: {
-    captchaTheme: 'dark',
-  },
 });

packages/types/src/appearance.ts

@@ -551,6 +551,12 @@ export type Theme = {
    * Eg: `formButtonPrimary__loading: { backgroundColor: 'gray' }`
    */
   elements?: Elements;
+  /**
+   * The appearance of the CAPTCHA widget.
+   * This will be used to style the CAPTCHA widget.
+   * Eg: `theme: 'dark'`
+   */
+  captcha?: CaptchaAppearanceOptions;
 };
 
 export type Layout = {
@@ -630,22 +636,24 @@ export type Layout = {
    * @default false
    */
   unsafe_disableDevelopmentModeWarnings?: boolean;
+};
 
+export type CaptchaAppearanceOptions = {
   /**
    * The widget theme. Can take the following values: light, dark, auto.
    * @default 'auto'
    */
-  captchaTheme?: 'auto' | 'light' | 'dark';
+  theme?: 'auto' | 'light' | 'dark';
   /**
    * The widget size. Can take the following values: normal, flexible, compact.
    * @default 'normal'
    */
-  captchaSize?: 'normal' | 'flexible' | 'compact';
+  size?: 'normal' | 'flexible' | 'compact';
   /**
    * Language to display, must be either: auto (default) to use the language that the visitor has chosen, or an ISO 639-1 two-letter language code (e.g. en) or language and country code (e.g. en-US).
    * Refer to the list of supported languages for more information: https://developers.cloudflare.com/turnstile/reference/supported-languages
    */
-  captchaLanguage?: string;
+  language?: string;
 };
 
 export type SignInTheme = Theme;