feat(clerk-js,shared): Export useOrganizationCreationDefaults hook (#7690)

Author: LauraBeatris

.changeset/blue-books-return.md

@@ -0,0 +1,8 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/nextjs': minor
+'@clerk/shared': minor
+'@clerk/clerk-react': minor
+---
+
+Export `useOrganizationCreationDefaults` hook to fetch suggested organization name and logo from default naming rules

packages/clerk-js/src/ui/components/SessionTasks/tasks/TaskChooseOrganization/index.tsx

@@ -1,13 +1,12 @@
-import { useClerk, useSession, useUser } from '@clerk/shared/react';
+import { useClerk, useOrganizationCreationDefaults, useSession, useUser } from '@clerk/shared/react';
 import type { OrganizationCreationDefaultsResource } from '@clerk/shared/types';
 import { useState } from 'react';
 
-import { useEnvironment, useSignOutContext, withCoreSessionSwitchGuard } from '@/ui/contexts';
+import { useSignOutContext, withCoreSessionSwitchGuard } from '@/ui/contexts';
 import { descriptors, Flex, Flow, localizationKeys, Spinner } from '@/ui/customizables';
 import { Card } from '@/ui/elements/Card';
 import { withCardStateProvider } from '@/ui/elements/contexts';
 import { Header } from '@/ui/elements/Header';
-import { useFetch } from '@/ui/hooks';
 import { useMultipleSessions } from '@/ui/hooks/useMultipleSessions';
 import { useOrganizationListInView } from '@/ui/hooks/useOrganizationListInView';
 
@@ -18,11 +17,7 @@ import { CreateOrganizationScreen } from './CreateOrganizationScreen';
 const TaskChooseOrganizationInternal = () => {
   const { user } = useUser();
   const { userMemberships, userSuggestions, userInvitations } = useOrganizationListInView();
-  const { organizationSettings } = useEnvironment();
-  const organizationCreationDefaults = useFetch(
-    organizationSettings.organizationCreationDefaults?.enabled ? user?.getOrganizationCreationDefaults : undefined,
-    'organization-creation-defaults',
-  );
+  const organizationCreationDefaults = useOrganizationCreationDefaults();
 
   const isLoading =
     userMemberships?.isLoading ||

packages/nextjs/src/client-boundary/hooks.ts

@@ -4,6 +4,7 @@ export {
   useClerk,
   useEmailLink,
   useOrganization,
+  useOrganizationCreationDefaults,
   useOrganizationList,
   useSession,
   useSessionList,
@@ -12,6 +13,7 @@ export {
   useUser,
   useReverification,
 } from '@clerk/clerk-react';
+export type { UseOrganizationCreationDefaultsParams, UseOrganizationCreationDefaultsReturn } from '@clerk/clerk-react';
 
 export {
   isClerkAPIResponseError,

packages/nextjs/src/index.ts

@@ -51,6 +51,7 @@ export {
   useClerk,
   useEmailLink,
   useOrganization,
+  useOrganizationCreationDefaults,
   useOrganizationList,
   useReverification,
   useSession,
@@ -59,6 +60,10 @@ export {
   useSignUp,
   useUser,
 } from './client-boundary/hooks';
+export type {
+  UseOrganizationCreationDefaultsParams,
+  UseOrganizationCreationDefaultsReturn,
+} from './client-boundary/hooks';
 
 /**
  * Conditionally export components that exhibit different behavior

packages/react-router/src/__tests__/__snapshots__/exports.test.ts.snap

@@ -52,6 +52,7 @@ exports[`root public exports > should not change unexpectedly 1`] = `
   "useClerk",
   "useEmailLink",
   "useOrganization",
+  "useOrganizationCreationDefaults",
   "useOrganizationList",
   "useReverification",
   "useSession",

packages/react/src/hooks/index.ts

@@ -5,6 +5,7 @@ export { useSignUp } from './useSignUp';
 export {
   useClerk,
   useOrganization,
+  useOrganizationCreationDefaults,
   useOrganizationList,
   useSessionList,
   useUser,
@@ -16,3 +17,4 @@ export {
   __experimental_PaymentElementProvider,
   __experimental_PaymentElement,
 } from '@clerk/shared/react';
+export type { UseOrganizationCreationDefaultsParams, UseOrganizationCreationDefaultsReturn } from '@clerk/shared/react';

packages/remix/src/__tests__/__snapshots__/exports.test.ts.snap

@@ -47,6 +47,7 @@ exports[`root public exports > should not change unexpectedly 1`] = `
   "useClerk",
   "useEmailLink",
   "useOrganization",
+  "useOrganizationCreationDefaults",
   "useOrganizationList",
   "useReverification",
   "useSession",

packages/shared/src/react/hooks/index.ts

@@ -1,6 +1,11 @@
 export { assertContextExists, createContextAndHook } from './createContextAndHook';
 export { useAPIKeys as __experimental_useAPIKeys } from './useAPIKeys';
 export { useOrganization } from './useOrganization';
+export { useOrganizationCreationDefaults } from './useOrganizationCreationDefaults';
+export type {
+  UseOrganizationCreationDefaultsParams,
+  UseOrganizationCreationDefaultsReturn,
+} from './useOrganizationCreationDefaults';
 export { useOrganizationList } from './useOrganizationList';
 export { useAttemptToEnableOrganizations } from './useAttemptToEnableOrganizations';
 export { useSafeLayoutEffect } from './useSafeLayoutEffect';

packages/shared/src/react/hooks/useOrganizationCreationDefaults.rq.tsx

@@ -0,0 +1,66 @@
+import { eventMethodCalled } from '../../telemetry/events/method-called';
+import type { EnvironmentResource } from '../../types/environment';
+import { defineKeepPreviousDataFn } from '../clerk-rq/keep-previous-data';
+import { useClerkQuery } from '../clerk-rq/useQuery';
+import { useClerkInstanceContext, useUserContext } from '../contexts';
+import { useOrganizationCreationDefaultsCacheKeys } from './useOrganizationCreationDefaults.shared';
+import type {
+  UseOrganizationCreationDefaultsParams,
+  UseOrganizationCreationDefaultsReturn,
+} from './useOrganizationCreationDefaults.types';
+
+/**
+ * The `useOrganizationCreationDefaults()` hook retrieves the organization creation defaults for the current user.
+ *
+ * @example
+ * ### Basic usage
+ *
+ * ```tsx
+ * import { useOrganizationCreationDefaults } from '@clerk/clerk-react'
+ *
+ * export default function CreateOrganizationForm() {
+ *   const { data, isLoading } = useOrganizationCreationDefaults()
+ *
+ *   if (isLoading) return <div>Loading...</div>
+ *
+ *   return (
+ *     <form>
+ *       <input defaultValue={data?.form.name} placeholder="Organization name" />
+ *       <input defaultValue={data?.form.slug} placeholder="Slug" />
+ *       <button type="submit">Create</button>
+ *     </form>
+ *   )
+ * }
+ * ```
+ */
+export function useOrganizationCreationDefaults(
+  params: UseOrganizationCreationDefaultsParams = {},
+): UseOrganizationCreationDefaultsReturn {
+  const { keepPreviousData = true, enabled = true } = params;
+  const clerk = useClerkInstanceContext();
+  const user = useUserContext();
+
+  // @ts-expect-error `__unstable__environment` is not typed
+  const environment = clerk.__unstable__environment as unknown as EnvironmentResource | null | undefined;
+  const featureEnabled = environment?.organizationSettings?.organizationCreationDefaults?.enabled ?? false;
+
+  clerk.telemetry?.record(eventMethodCalled('useOrganizationCreationDefaults'));
+
+  const { queryKey } = useOrganizationCreationDefaultsCacheKeys({ userId: user?.id ?? null });
+
+  const queryEnabled = Boolean(user) && enabled && featureEnabled && clerk.loaded;
+
+  const query = useClerkQuery({
+    queryKey,
+    queryFn: user?.getOrganizationCreationDefaults,
+    enabled: queryEnabled,
+    placeholderData: defineKeepPreviousDataFn(keepPreviousData),
+  });
+
+  return {
+    data: query.data,
+    error: (query.error ?? null) as UseOrganizationCreationDefaultsReturn['error'],
+    isLoading: query.isLoading,
+    isFetching: query.isFetching,
+  };
+}

packages/shared/src/react/hooks/useOrganizationCreationDefaults.shared.ts

@@ -0,0 +1,20 @@
+import { useMemo } from 'react';
+
+import { STABLE_KEYS } from '../stable-keys';
+import { createCacheKeys } from './createCacheKeys';
+
+export function useOrganizationCreationDefaultsCacheKeys(params: { userId: string | null }) {
+  const { userId } = params;
+  return useMemo(() => {
+    return createCacheKeys({
+      stablePrefix: STABLE_KEYS.ORGANIZATION_CREATION_DEFAULTS_KEY,
+      authenticated: Boolean(userId),
+      tracked: {
+        userId: userId ?? null,
+      },
+      untracked: {
+        args: {},
+      },
+    });
+  }, [userId]);
+}