chore(repo): Add Typedoc (#4925)

Author: LekoArts

.changeset/shiny-schools-search.md

@@ -0,0 +1,2 @@
+---
+---

.eslintignore

@@ -17,3 +17,4 @@ package-lock.json
 **/integration/templates/**/*
 commitlint.config.ts
 vitest.workspace.mjs
+typedoc.config.mjs

.gitignore

@@ -94,4 +94,5 @@ test-results
 scripts/.env
 !scripts/.env.example
 
-
+# typedoc
+.typedoc

package.json

@@ -44,6 +44,7 @@
     "test:integration:tanstack-start": "E2E_APP_ID=tanstack.start pnpm test:integration:base --grep @tanstack-start",
     "test:integration:vue": "E2E_APP_ID=vue.vite pnpm test:integration:base --grep @vue",
     "turbo:clean": "turbo daemon clean",
+    "typedoc:generate": "typedoc --tsconfig tsconfig.typedoc.json",
     "version-packages": "changeset version && pnpm install --lockfile-only --engine-strict=false",
     "version-packages:canary": "./scripts/canary.mjs",
     "version-packages:snapshot": "./scripts/snapshot.mjs",
@@ -103,6 +104,7 @@
     "tsup": "catalog:repo",
     "turbo": "^2.0.14",
     "turbo-ignore": "^2.0.6",
+    "typedoc": "0.27.6",
     "typescript": "catalog:repo",
     "verdaccio": "^5.26.3",
     "vitest": "3.0.2",

packages/astro/src/react/hooks.ts

@@ -121,8 +121,6 @@ type UseAuth = () => UseAuthReturn;
  * For projects using a server, you can have immediate access to this data during SSR.
  *
  * @example
- * A simple example:
- *
  * function Hello() {
  *   const { isSignedIn, sessionId, userId } = useAuth();
  *   if(isSignedIn) {
@@ -132,9 +130,8 @@ type UseAuth = () => UseAuthReturn;
  *   return <div>...</div>
  * }
  *
- * @example
  * This page will be fully rendered during SSR:
- *
+ * @example
  * export HelloPage = () => {
  *   const { isSignedIn, sessionId, userId } = useAuth();
  *   console.log(isSignedIn, sessionId, userId)

packages/astro/src/stores/external.ts

@@ -8,8 +8,6 @@ import { $clerk, $csrState, $initialState } from './internal';
  * A client side store that returns the loaded state of clerk-js.
  *
  * @example
- * A simple example:
- *
  * $isLoadedStore.subscribe((authloaded => console.log(loaded))
  */
 export const $isLoadedStore = computed([$csrState], state => state.isLoaded);
@@ -19,8 +17,6 @@ export const $isLoadedStore = computed([$csrState], state => state.isLoaded);
  * It is a nanostore, for instructions on how to use nanostores please review the [documentation](https://github.com/nanostores/nanostores)
  *
  * @example
- * A simple example:
- *
  * $authStore.subscribe((auth) => console.log(auth.userId))
  */
 export const $authStore = batched([$csrState, $initialState], (state, initialState) => {
@@ -42,8 +38,6 @@ export const $authStore = batched([$csrState, $initialState], (state, initialSta
  * It is a nanostore, for instructions on how to use nanostores please review the [documentation](https://github.com/nanostores/nanostores)
  *
  * @example
- * A simple example:
- *
  * $userStore.subscribe((user) => console.log(user.id))
  */
 export const $userStore = computed([$authStore], auth => auth.user);
@@ -54,8 +48,6 @@ export const $userStore = computed([$authStore], auth => auth.user);
  * It is a nanostore, for instructions on how to use nanostores please review the [documentation](https://github.com/nanostores/nanostores)
  *
  * @example
- * A simple example:
- *
  * $sessionStore.subscribe((session) => console.log(session.id))
  */
 export const $sessionStore = computed([$authStore], auth => auth.session);
@@ -66,8 +58,6 @@ export const $sessionStore = computed([$authStore], auth => auth.session);
  * It is a nanostore, for instructions on how to use nanostores please review the [documentation](https://github.com/nanostores/nanostores)
  *
  * @example
- * A simple example:
- *
  * $organizationStore.subscribe((org) => console.log(org.id))
  */
 export const $organizationStore = computed([$authStore], auth => auth.organization);
@@ -78,8 +68,6 @@ export const $organizationStore = computed([$authStore], auth => auth.organizati
  * It is a nanostore, for instructions on how to use nanostores please review the [documentation](https://github.com/nanostores/nanostores)
  *
  * @example
- * A simple example:
- *
  * $clientStore.subscribe((client) => console.log(client.activeSessions))
  */
 export const $clientStore = computed([$csrState], csr => csr.client);
@@ -90,8 +78,6 @@ export const $clientStore = computed([$csrState], csr => csr.client);
  * It is a nanostore, for instructions on how to use nanostores please review the [documentation](https://github.com/nanostores/nanostores)
  *
  * @example
- * A simple example:
- *
  * $clerkStore.subscribe((clerk) => console.log(clerk.publishableKey))
  */
 export const $clerkStore = computed([$clerk], clerk => clerk);
@@ -102,8 +88,6 @@ export const $clerkStore = computed([$clerk], clerk => clerk);
  * It is a nanostore, for instructions on how to use nanostores please review the [documentation](https://github.com/nanostores/nanostores)
  *
  * @example
- * A simple example:
- *
  * $sessionListStore.subscribe((sessionList) => sessionList.map((session) => console.log('Session id:', sessino.id) ))
  */
 export const $sessionListStore = computed([$clientStore], client => client?.sessions);
@@ -114,8 +98,6 @@ export const $sessionListStore = computed([$clientStore], client => client?.sess
  * It is a nanostore, for instructions on how to use nanostores please review the [documentation](https://github.com/nanostores/nanostores)
  *
  * @example
- * A simple example:
- *
  * $signInStore.subscribe((signIn) => console.log(signIn.status))
  */
 export const $signInStore = computed([$clientStore], client => client?.signIn);
@@ -126,8 +108,6 @@ export const $signInStore = computed([$clientStore], client => client?.signIn);
  * It is a nanostore, for instructions on how to use nanostores please review the [documentation](https://github.com/nanostores/nanostores)
  *
  * @example
- * A simple example:
- *
  * $signUpStore.subscribe((signUp) => console.log(signUp.status))
  */
 export const $signUpStore = computed([$clientStore], client => client?.signUp);

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

@@ -20,23 +20,24 @@ type GetInvitationListParams = ClerkPaginationRequest<{
    * Filters invitations based on their status(accepted, pending, revoked).
    *
    * @example
-   * get all revoked invitations
-   *
+   * Get all revoked invitations
+   * ```ts
    * import { createClerkClient } from '@clerk/backend';
    * const clerkClient = createClerkClient(...)
    * await clerkClient.invitations.getInvitationList({ status: 'revoked' })
-   *
+   * ```
    */
   status?: 'accepted' | 'pending' | 'revoked';
   /**
    * Filters invitations based on `email_address` or `id`.
    *
    * @example
-   * get all invitations for a specific email address
+   * Get all invitations for a specific email address
+   * ```ts
    * import { createClerkClient } from '@clerk/backend';
    * const clerkClient = createClerkClient(...)
    * await clerkClient.invitations.getInvitationList({ query: 'user@example.com' })
-   *
+   * ```
    */
   query?: string;
 }>;

packages/backend/src/tokens/authObjects.ts

@@ -40,7 +40,7 @@ export type SignedInAuthObject = {
    * Each item represents the minutes that have passed since the last time a first or second factor were verified.
    * [fistFactorAge, secondFactorAge]
    */
-  factorVerificationAge: [number, number] | null;
+  factorVerificationAge: [firstFactorAge: number, secondFactorAge: number] | null;
   getToken: ServerGetToken;
   has: CheckAuthorizationFromSessionClaims;
   debug: AuthObjectDebug;

packages/clerk-js/src/ui/customizables/makeCustomizable.tsx

@@ -10,23 +10,27 @@ type Customizable<T = Record<never, never>> = T & {
    * elementDescriptor - An optional property that can be an `ElementDescriptor` or an array of `ElementDescriptor` or `undefined`. This property is used to describe the elements for styling purposes.
    *
    * @example
+   * ```tsx
    * <Box
    *   elementDescriptor={[descriptors.icon, descriptors.iconInitials]}
    * />
    *
    * // Output: `cl-icon cl-iconInitials`
+   * ```
    */
   elementDescriptor?: ElementDescriptor | Array<ElementDescriptor | undefined>;
   /**
    * elementId - An optional property that can be an `ElementId`. This property is used to set a unique identifier for the element.
    *
    * @example
+   * ```tsx
    * <Box
    *   elementDescriptor={[descriptors.icon, descriptors.iconInitials]}
    *   elementId={descriptors.icon.setId(id)}
    * />
    *
    * // Output: `cl-icon cl-iconInitials cl-icon__google cl-iconInitials__google`
+   * ```
    */
   elementId?: ElementId;
   css?: never;

packages/clerk-js/src/utils/url.ts

@@ -294,10 +294,10 @@ export const hasUrlInFragment = (_url: URL | string) => {
  * and also includes all search params from both places.
  *
  * @example
- * Input
- * https://accounts.clerk.com/sign-in?user_param=hello#/verify/factor-one?redirect_url=/protected
- * Return value:
- * https://accounts.clerk.com/sign-in/verify/factor-one?user_param=hello&redirect_url=/protected
+ * ```ts
+ * mergeFragmentIntoUrl('https://accounts.clerk.com/sign-in?user_param=hello#/verify/factor-one?redirect_url=/protected')
+ * // Returns: 'https://accounts.clerk.com/sign-in/verify/factor-one?user_param=hello&redirect_url=/protected'
+ * ```
  */
 export const mergeFragmentIntoUrl = (_url: string | URL): URL => {
   const url = new URL(_url);

packages/elements/src/react/common/form/field-state.tsx

@@ -21,7 +21,6 @@ const DISPLAY_NAME = 'ClerkElementsFieldState';
  * @param {Function} children - A function that receives `state`, `message`, and `codes` as an argument. `state` will is a union of `"success" | "error" | "idle" | "warning" | "info"`. `message` will be the corresponding message, e.g. error message. `codes` will be an array of keys that were used to generate the password validation messages. This prop is only available when the field is of type `password` and has `validatePassword` set to `true`.
  *
  * @example
- *
  * <Clerk.Field name="email">
  *  <Clerk.Label>Email</Clerk.Label>
  *  <Clerk.FieldState>

packages/expo/src/provider/ClerkProvider.tsx

@@ -17,8 +17,8 @@ export type ClerkProviderProps = React.ComponentProps<typeof ClerkReactProvider>
   /**
    * Note: Passkey support in Expo is currently in a limited rollout phase.
    * If you're interested in using this feature, please contact us for early access or additional details.
-   *
-   * @experimental This API is experimental and may change at any moment.
+   * This API is experimental and may change at any moment.
+   * @experimental
    */
   __experimental_passkeys?: BuildClerkOptions['__experimental_passkeys'];
   /**

packages/expo/src/provider/singleton/types.ts

@@ -19,8 +19,8 @@ export type BuildClerkOptions = {
   /**
    * Note: Passkey support in Expo is currently in a limited rollout phase.
    * If you're interested in using this feature, please contact us for early access or additional details.
-   *
-   * @experimental This API is experimental and may change at any moment.
+   * This API is experimental and may change at any moment.
+   * @experimental
    */
   __experimental_passkeys?: {
     get: ({

packages/nextjs/src/client-boundary/PromisifiedAuthProvider.tsx

@@ -30,8 +30,6 @@ export function PromisifiedAuthProvider({
  * simply by using the `ClerkProvider`.
  *
  * @example
- * A simple example:
- *
  * import { useAuth } from '@clerk/nextjs'
  *
  * function Hello() {
@@ -44,15 +42,17 @@ export function PromisifiedAuthProvider({
  * }
  *
  * @example
- * Basic example in a NextJs app. This page will be fully rendered during SSR:
+ * This page will be fully rendered during SSR.
  *
+ * ```tsx
  * import { useAuth } from '@clerk/nextjs'
  *
  * export HelloPage = () => {
  *   const { isSignedIn, sessionId, userId } = useAuth();
  *   console.log(isSignedIn, sessionId, userId)
  *   return <div>...</div>
  * }
+ * ```
  */
 export function usePromisifiedAuth() {
   const isPagesRouter = useRouter();

packages/react/src/components/uiComponents.tsx

@@ -78,7 +78,8 @@ type UserButtonPropsWithoutCustomPages = Without<
   userProfileProps?: Pick<UserProfileProps, 'additionalOAuthScopes' | 'appearance'>;
   /**
    * Adding `asProvider` will defer rendering until the `<Outlet />` component is mounted.
-   * @experimental This API is experimental and may change at any moment.
+   * This API is experimental and may change at any moment.
+   * @experimental
    * @default undefined
    */
   __experimental_asProvider?: boolean;
@@ -107,7 +108,8 @@ type OrganizationSwitcherPropsWithoutCustomPages = Without<
   organizationProfileProps?: Pick<OrganizationProfileProps, 'appearance'>;
   /**
    * Adding `asProvider` will defer rendering until the `<Outlet />` component is mounted.
-   * @experimental This API is experimental and may change at any moment.
+   * This API is experimental and may change at any moment.
+   * @experimental
    * @default undefined
    */
   __experimental_asProvider?: boolean;

packages/react/src/hooks/useAuth.ts

@@ -23,8 +23,6 @@ type UseAuth = (initialAuthState?: any) => UseAuthReturn;
  * simply by using the `ClerkProvider`.
  *
  * @example
- * A simple example:
- *
  * import { useAuth } from '@clerk/clerk-react'
  *
  * function Hello() {
@@ -35,17 +33,6 @@ type UseAuth = (initialAuthState?: any) => UseAuthReturn;
  *   console.log(sessionId, userId)
  *   return <div>...</div>
  * }
- *
- * @example
- * Basic example in a NextJs app. This page will be fully rendered during SSR:
- *
- * import { useAuth } from '@clerk/nextjs'
- *
- * export HelloPage = () => {
- *   const { isSignedIn, sessionId, userId } = useAuth();
- *   console.log(isSignedIn, sessionId, userId)
- *   return <div>...</div>
- * }
  */
 export const useAuth: UseAuth = (initialAuthState = {}) => {
   useAssertWrappedByClerkProvider('useAuth');

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

@@ -12,8 +12,6 @@ type UseSession = () => UseSessionReturn;
  * safely access `isSignedIn` state and `session`.
  *
  * @example
- * A simple example:
- *
  * import { useSession } from '@clerk/clerk-react'
  *
  * function Hello() {

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

@@ -10,8 +10,6 @@ import { useAssertWrappedByClerkProvider, useUserContext } from '../contexts';
  * safely access `isSignedIn` state and `user`.
  *
  * @example
- * A simple example:
- *
  * import { useUser } from '@clerk/clerk-react'
  *
  * function Hello() {

packages/types/src/clerk.ts

@@ -346,7 +346,8 @@ export interface Clerk {
   /**
    * Prefetches the data displayed by an organization switcher.
    * It can be used when `mountOrganizationSwitcher({ asStandalone: true})`, to avoid unwanted loading states.
-   * @experimantal This API is still under active development and may change at any moment.
+   * This API is still under active development and may change at any moment.
+   * @experimental
    * @param props Optional user verification configuration parameters.
    */
   __experimental_prefetchOrganizationSwitcher: () => void;
@@ -1080,8 +1081,8 @@ export type UserProfileProps = RoutingOptions & {
    */
   customPages?: CustomPage[];
   /**
-   * @experimental
    * Specify on which page the user profile modal will open.
+   * @experimental
    **/
   __experimental_startPath?: string;
 };
@@ -1161,7 +1162,8 @@ export type UserButtonProps = UserButtonProfileMode & {
   /**
    * If true the `<UserButton />` will only render the popover.
    * Enables developers to implement a custom dialog.
-   * @experimental This API is experimental and may change at any moment.
+   * This API is experimental and may change at any moment.
+   * @experimental
    * @default undefined
    */
   __experimental_asStandalone?: boolean | ((opened: boolean) => void);
@@ -1230,7 +1232,8 @@ export type OrganizationSwitcherProps = CreateOrganizationMode &
     /**
      * If true, `<OrganizationSwitcher />` will only render the popover.
      * Enables developers to implement a custom dialog.
-     * @experimental This API is experimental and may change at any moment.
+     * This API is experimental and may change at any moment.
+     * @experimental
      * @default undefined
      */
     __experimental_asStandalone?: boolean | ((opened: boolean) => void);