chore(clerk-react,types): Update Typedoc for hooks and <ClerkProvider> (#5643)

Co-authored-by: LekoArts <lekoarts@gmail.com>

Author: alexisintech

.changeset/pretty-wasps-press.md

@@ -0,0 +1,8 @@
+---
+'@clerk/backend': patch
+'@clerk/shared': patch
+'@clerk/clerk-react': patch
+'@clerk/types': patch
+---
+
+Improve JSDoc comments

.typedoc/custom-plugin.mjs

@@ -80,6 +80,10 @@ function getCatchAllReplacements() {
       pattern: /\(CreateOrganizationParams\)/g,
       replace: '([CreateOrganizationParams](#create-organization-params))',
     },
+    {
+      pattern: /\| `SignInResource` \|/,
+      replace: '| [SignInResource](/docs/references/javascript/sign-in) |',
+    },
     {
       /**
        * By default, `@deprecated` is output with `**Deprecated**`. We want to add a full stop to it.

packages/backend/src/api/endpoints/InstanceApi.ts

@@ -52,17 +52,17 @@ type UpdateOrganizationSettingsParams = {
   adminDeleteEnabled?: boolean | null | undefined;
   domainsEnabled?: boolean | null | undefined;
   /**
-   * Specify which enrollment modes to enable for your Organization Domains.
+   * Specifies which [enrollment modes](https://clerk.com/docs/organizations/verified-domains#enrollment-mode) to enable for your Organization Domains.
    *
    * @remarks Supported modes are 'automatic_invitation' & 'automatic_suggestion'.
    */
   domainsEnrollmentModes?: Array<string> | undefined;
   /**
-   * Specify what the default organization role is for an organization creator.
+   * Specifies what the default organization role is for an organization creator.
    */
   creatorRoleId?: string | null | undefined;
   /**
-   * Specify what the default organization role is for the organization domains.
+   * Specifies what the default organization role is for the organization domains.
    */
   domainsDefaultRoleId?: string | null | undefined;
 };

packages/react/src/hooks/useAuth.ts

@@ -17,24 +17,25 @@ import { invalidStateError } from '../errors/messages';
 import { useAssertWrappedByClerkProvider } from './useAssertWrappedByClerkProvider';
 import { createGetToken, createSignOut } from './utils';
 
-type Nullish<T> = T | undefined | null;
-type InitialAuthState = Record<string, any>;
 /**
  * @inline
  */
-type UseAuthOptions = Nullish<InitialAuthState | PendingSessionOptions>;
+type UseAuthOptions = Record<string, any> | PendingSessionOptions | undefined | null;
 
 /**
  * The `useAuth()` hook provides access to the current user's authentication state and methods to manage the active session.
  *
+ * > [!NOTE]
+ * > To access auth data server-side, see the [`Auth` object reference doc](https://clerk.com/docs/references/backend/types/auth-object).
+ *
  * <If sdk="nextjs">
  * By default, Next.js opts all routes into static rendering. If you need to opt a route or routes into dynamic rendering because you need to access the authentication data at request time, you can create a boundary by passing the `dynamic` prop to `<ClerkProvider>`. See the [guide on rendering modes](https://clerk.com/docs/references/nextjs/rendering-modes) for more information, including code examples.
  * </If>
  *
  * @unionReturnHeadings
  * ["Initialization", "Signed out", "Signed in (no active organization)", "Signed in (with active organization)"]
  *
- * @param [initialAuthStateOrOptions] - An object containing the initial authentication state. If not provided, the hook will attempt to derive the state from the context.
+ * @param [initialAuthStateOrOptions] - An object containing the initial authentication state or options for the `useAuth()` hook. If not provided, the hook will attempt to derive the state from the context. `treatPendingAsSignedOut` is a boolean that indicates whether pending sessions are considered as signed out or not. Defaults to `true`.
  *
  * @function
  *

packages/react/src/types.ts

@@ -24,15 +24,15 @@ declare global {
 export type IsomorphicClerkOptions = Without<ClerkOptions, 'isSatellite'> & {
   Clerk?: ClerkProp;
   /**
-   * Define the URL that `@clerk/clerk-js` should be hot-loaded from
+   * The URL that `@clerk/clerk-js` should be hot-loaded from.
    */
   clerkJSUrl?: string;
   /**
    * If your web application only uses [Control Components](https://clerk.com/docs/components/overview#control-components), you can set this value to `'headless'` and load a minimal ClerkJS bundle for optimal page performance.
    */
   clerkJSVariant?: 'headless' | '';
   /**
-   * Define the npm version for `@clerk/clerk-js`
+   * The npm version for `@clerk/clerk-js`.
    */
   clerkJSVersion?: string;
   /**

packages/shared/src/react/hooks/useOrganization.tsx

@@ -32,7 +32,7 @@ export type UseOrganizationParams = {
    * If set to `true`, all default properties will be used.<br />
    * Otherwise, accepts an object with the following optional properties:
    * <ul>
-   *  <li>`enrollmentMode`: A string that filters the domains by the provided enrollment mode.</li>
+   *  <li>`enrollmentMode`: A string that filters the domains by the provided [enrollment mode](https://clerk.com/docs/organizations/verified-domains#enrollment-mode).</li>
    *  <li>Any of the properties described in [Shared properties](#shared-properties).</li>
    * </ul>
    */
@@ -69,7 +69,7 @@ export type UseOrganizationParams = {
    * If set to `true`, all default properties will be used.<br />
    * Otherwise, accepts an object with the following optional properties:
    * <ul>
-   *  <li>`status`: A string that filters the subscriptions by the provided status.</li>
+   *  <li>`orgId`: A string that filters the subscriptions by the provided organization ID.</li>
    *  <li>Any of the properties described in [Shared properties](#shared-properties).</li>
    * </ul>
    */

packages/types/src/hooks.ts

@@ -180,7 +180,7 @@ export type UseSessionReturn =
        */
       isSignedIn: undefined;
       /**
-       * Holds the current active session for the user.
+       * The current active session for the user.
        */
       session: undefined;
     }
@@ -233,7 +233,7 @@ export type UseUserReturn =
        */
       isSignedIn: undefined;
       /**
-       * The `User` object for the current user. If the user isn't signed in, `user` will be `null`.
+       * The `User` object for the current user.
        */
       user: undefined;
     }

packages/types/src/localization.ts

@@ -5,7 +5,7 @@ export type LocalizationValue = string;
 
 /**
  * A type containing all the possible localization keys the prebuilt Clerk components support.
- * Users aiming to customise a few strings can also peak at the `data-localization-key` attribute by inspecting
+ * Users aiming to customize a few strings can also peak at the `data-localization-key` attribute by inspecting
  * the DOM and updating the corresponding key.
  * Users aiming to completely localize the components by providing a complete translation can use
  * the default english resource object from {@link https://github.com/clerk/javascript Clerk's open source repo}

packages/types/src/multiDomain.ts

@@ -11,7 +11,7 @@ import type { ClerkOptions } from './clerk';
 export type MultiDomainAndOrProxy =
   | {
       /**
-       * Whether the application is a satellite application.
+       * A boolean that indicates whether the application is a satellite application.
        */
       isSatellite?: never;
       /**
@@ -37,7 +37,7 @@ export type MultiDomainAndOrProxy =
 export type MultiDomainAndOrProxyPrimitives =
   | {
       /**
-       * Whether the application is a satellite application.
+       * A boolean that indicates whether the application is a satellite application.
        */
       isSatellite?: never;
       /**

packages/types/src/redirects.ts

@@ -9,8 +9,8 @@ export type AfterSignOutUrl = {
 
 export type AfterMultiSessionSingleSignOutUrl = {
   /**
-   * Full URL or path to navigate to after signing out the current user is complete.
-   * This option applies to multi-session applications.
+   * The full URL or path to navigate to after signing out the current user is complete.
+   * This option applies to [multi-session applications](https://clerk.com/docs/authentication/configuration/session-options#multi-session-applications).
    */
   afterMultiSessionSingleSignOutUrl?: string | null;
 };
@@ -45,14 +45,14 @@ export type RedirectOptions = SignInForceRedirectUrl &
 
 export type AuthenticateWithRedirectParams = {
   /**
-   * Full URL or path to the route that will complete the OAuth or SAML flow.
+   * The full URL or path to the route that will complete the OAuth or SAML flow.
    * Typically, this will be a simple `/sso-callback` route that calls `Clerk.handleRedirectCallback`
    * or mounts the <AuthenticateWithRedirectCallback /> component.
    */
   redirectUrl: string;
 
   /**
-   * Full URL or path to navigate to after the OAuth or SAML flow completes.
+   * The full URL or path to navigate to after the OAuth or SAML flow completes.
    */
   redirectUrlComplete: string;
 
@@ -94,7 +94,7 @@ export type RedirectUrlProp = {
 
 export type SignUpForceRedirectUrl = {
   /**
-   * If provided, this URL will always be redirected to after the user signs up. It's recommended to use the [environment variable](https://clerk.com/docs/deployments/clerk-environment-variables#sign-in-and-sign-up-redirects) instead.
+   * This URL will always be redirected to after the user signs up. It's recommended to use the [environment variable](https://clerk.com/docs/deployments/clerk-environment-variables#sign-in-and-sign-up-redirects) instead.
    */
   signUpForceRedirectUrl?: string | null;
 };
@@ -117,7 +117,7 @@ export type SignInFallbackRedirectUrl = {
 
 export type SignInForceRedirectUrl = {
   /**
-   * If provided, this URL will always be redirected to after the user signs in. It's recommended to use the [environment variable](https://clerk.com/docs/deployments/clerk-environment-variables#sign-in-and-sign-up-redirects) instead.
+   * This URL will always be redirected to after the user signs in. It's recommended to use the [environment variable](https://clerk.com/docs/deployments/clerk-environment-variables#sign-in-and-sign-up-redirects) instead.
    */
   signInForceRedirectUrl?: string | null;
 };