fix(clerk-js,localizations,types): Add min and max lengths to username field error (#4771)

Author: alexcarpenter

.changeset/cold-tomatoes-float.md

@@ -0,0 +1,7 @@
+---
+'@clerk/localizations': patch
+'@clerk/clerk-js': patch
+'@clerk/types': patch
+---
+
+Added min and max length username settings to username field error.

packages/clerk-js/src/core/resources/UserSettings.ts

@@ -8,6 +8,7 @@ import type {
   SamlSettings,
   SignInData,
   SignUpData,
+  UsernameSettingsData,
   UserSettingsJSON,
   UserSettingsJSONSnapshot,
   UserSettingsResource,
@@ -19,6 +20,9 @@ import { BaseResource } from './internal';
 const defaultMaxPasswordLength = 72;
 const defaultMinPasswordLength = 8;
 
+const defaultMinUsernameLength = 4;
+const defaultMaxUsernameLength = 64;
+
 export type Actions = {
   create_organization: boolean;
   delete_self: boolean;
@@ -40,6 +44,7 @@ export class UserSettings extends BaseResource implements UserSettingsResource {
   signUp!: SignUpData;
   passwordSettings!: PasswordSettingsData;
   passkeySettings!: PasskeySettingsData;
+  usernameSettings!: UsernameSettingsData;
 
   socialProviderStrategies: OAuthStrategy[] = [];
   authenticatableSocialStrategies: OAuthStrategy[] = [];
@@ -85,6 +90,11 @@ export class UserSettings extends BaseResource implements UserSettingsResource {
           ? defaultMaxPasswordLength
           : Math.min(data?.password_settings?.max_length, defaultMaxPasswordLength),
     };
+    this.usernameSettings = {
+      ...data.username_settings,
+      min_length: Math.max(data?.username_settings?.min_length, defaultMinUsernameLength),
+      max_length: Math.min(data?.username_settings?.max_length, defaultMaxUsernameLength),
+    };
     this.passkeySettings = data.passkey_settings;
     this.socialProviderStrategies = this.getSocialProviderStrategies(data.social);
     this.authenticatableSocialStrategies = this.getAuthenticatableSocialStrategies(data.social);

packages/clerk-js/src/ui/components/SignUp/SignUpStart.tsx

@@ -20,7 +20,7 @@ import { useCardState } from '../../elements/contexts';
 import { useLoadingStatus } from '../../hooks';
 import { useRouter } from '../../router';
 import type { FormControlState } from '../../utils';
-import { buildRequest, createPasswordError, handleError, useFormControl } from '../../utils';
+import { buildRequest, createPasswordError, createUsernameError, handleError, useFormControl } from '../../utils';
 import { SignUpForm } from './SignUpForm';
 import type { ActiveIdentifier } from './signUpFormHelpers';
 import { determineActiveFields, emailOrPhone, getInitialActiveIdentifier, showFormFields } from './signUpFormHelpers';
@@ -52,7 +52,7 @@ function _SignUpStart(): JSX.Element {
   const [missingRequirementsWithTicket, setMissingRequirementsWithTicket] = React.useState(false);
 
   const {
-    userSettings: { passwordSettings },
+    userSettings: { passwordSettings, usernameSettings },
   } = useEnvironment();
 
   const { mode } = userSettings.signUp;
@@ -78,6 +78,7 @@ function _SignUpStart(): JSX.Element {
       label: localizationKeys('formFieldLabel__username'),
       placeholder: localizationKeys('formFieldInputPlaceholder__username'),
       transformer: value => value.trim(),
+      buildErrorMessage: errors => createUsernameError(errors, { t, locale, usernameSettings }),
     }),
     phoneNumber: useFormControl('phoneNumber', signUp.phoneNumber || initialValues.phoneNumber || '', {
       type: 'tel',

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

@@ -23,3 +23,4 @@ export * from './createCustomPages';
 export * from './ExternalElementMounter';
 export * from './colorOptionToHslaScale';
 export * from './createCustomMenuItems';
+export * from './usernameUtils';

packages/clerk-js/src/ui/utils/useFormControl.ts

@@ -32,6 +32,13 @@ type Options = {
       buildErrorMessage?: (err: ClerkAPIError[]) => ClerkAPIError | string | undefined;
       radioOptions?: never;
     }
+  | {
+      label: string | LocalizationKey;
+      type: Extract<HTMLInputTypeAttribute, 'text'>;
+      validatePassword?: never;
+      buildErrorMessage?: (err: ClerkAPIError[]) => ClerkAPIError | string | undefined;
+      radioOptions?: never;
+    }
   | {
       validatePassword?: never;
       buildErrorMessage?: never;

packages/clerk-js/src/ui/utils/usernameUtils.ts

@@ -0,0 +1,26 @@
+import type { ClerkAPIError, UsernameSettingsData } from '@clerk/types';
+
+import { type LocalizationKey, localizationKeys } from '../localization';
+
+type LocalizationConfigProps = {
+  t: (localizationKey: LocalizationKey | string | undefined) => string;
+  locale: string;
+  usernameSettings: Pick<UsernameSettingsData, 'max_length' | 'min_length'>;
+};
+
+export const createUsernameError = (errors: ClerkAPIError[], localizationConfig: LocalizationConfigProps) => {
+  const { t, usernameSettings } = localizationConfig;
+
+  if (!localizationConfig) {
+    return errors[0].longMessage;
+  }
+
+  const msg = t(
+    localizationKeys('unstable__errors.form_username_invalid_length', {
+      min_length: usernameSettings.min_length,
+      max_length: usernameSettings.max_length,
+    }),
+  );
+
+  return msg;
+};

packages/localizations/src/en-US.ts

@@ -50,9 +50,9 @@ export const enUS: LocalizationResource = {
   formFieldInputPlaceholder__organizationDomainEmailAddress: '[email protected]',
   formFieldInputPlaceholder__organizationName: 'Organization name',
   formFieldInputPlaceholder__organizationSlug: 'my-org',
-  formFieldInputPlaceholder__username: undefined,
   formFieldInputPlaceholder__password: 'Enter your password',
   formFieldInputPlaceholder__phoneNumber: 'Enter your phone number',
+  formFieldInputPlaceholder__username: undefined,
   formFieldLabel__automaticInvitations: 'Enable automatic invitations for this domain',
   formFieldLabel__backupCode: 'Backup code',
   formFieldLabel__confirmDeletion: 'Confirmation',
@@ -439,6 +439,7 @@ export const enUS: LocalizationResource = {
       detailsLabel: 'We need to verify your identity before resetting your password.',
     },
     start: {
+      __experimental_titleCombined: 'Continue to {{applicationName}}',
       actionLink: 'Sign up',
       actionLink__join_waitlist: 'Join waitlist',
       actionLink__use_email: 'Use email',
@@ -450,7 +451,6 @@ export const enUS: LocalizationResource = {
       actionText__join_waitlist: 'Want early access?',
       subtitle: 'Welcome back! Please sign in to continue',
       title: 'Sign in to {{applicationName}}',
-      __experimental_titleCombined: 'Continue to {{applicationName}}',
     },
     totpMfa: {
       formTitle: 'Verification code',
@@ -566,7 +566,7 @@ export const enUS: LocalizationResource = {
     form_password_validation_failed: 'Incorrect Password',
     form_username_invalid_character:
       'Your username contains invalid characters. Please use only letters, numbers, and underscores.',
-    form_username_invalid_length: 'Your username must be between 3 and 20 characters long.',
+    form_username_invalid_length: 'Your username must be between {{min_length}} and {{max_length}} characters long.',
     identification_deletion_failed: 'You cannot delete your last identification.',
     not_allowed_access:
       'You do not have permission to access this page. Please contact support if you believe this is an error.',

packages/types/src/userSettings.ts

@@ -72,6 +72,11 @@ export type PasswordSettingsData = {
   min_zxcvbn_strength: number;
 };
 
+export type UsernameSettingsData = {
+  min_length: number;
+  max_length: number;
+};
+
 export type PasskeySettingsData = {
   allow_autofill: boolean;
   show_sign_in_button: boolean;
@@ -119,6 +124,7 @@ export interface UserSettingsJSON extends ClerkResourceJSON {
   sign_up: SignUpData;
   password_settings: PasswordSettingsData;
   passkey_settings: PasskeySettingsData;
+  username_settings: UsernameSettingsData;
 }
 
 export interface UserSettingsResource extends ClerkResource {
@@ -136,6 +142,7 @@ export interface UserSettingsResource extends ClerkResource {
   signIn: SignInData;
   signUp: SignUpData;
   passwordSettings: PasswordSettingsData;
+  usernameSettings: UsernameSettingsData;
   passkeySettings: PasskeySettingsData;
   socialProviderStrategies: OAuthStrategy[];
   authenticatableSocialStrategies: OAuthStrategy[];