chore(repo): Hide @experimental from typedoc rendering

.changeset/quiet-signs-peel.md

@@ -0,0 +1,10 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/backend': patch
+'@clerk/shared': patch
+'@clerk/clerk-react': patch
+'@clerk/types': patch
+'@clerk/clerk-expo': patch
+---
+
+Update jsdocs mentions of `@experimental` tag.

.typedoc/custom-plugin.mjs

@@ -1,4 +1,4 @@
-// @ts-check
+// @ts-check - Enable TypeScript checks for safer MDX post-processing and link rewriting
 import { MarkdownPageEvent } from 'typedoc-plugin-markdown';
 
 /**

.typedoc/custom-theme.mjs

@@ -218,13 +218,19 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext {
         const customizedModel = model;
         customizedModel.typeParameters = undefined;
 
-        // Extract the Accessors group (if any) and prevent default rendering for it
         const originalGroups = customizedModel.groups;
-        const accessorsGroup = originalGroups?.find(g => g.title === 'Accessors');
-        const groupsWithoutAccessors = originalGroups?.filter(g => g.title !== 'Accessors');
+
+        // When an interface extends another interface, typedoc will generate a "Methods" group
+        // We want to hide this group from being rendered
+        const groupsWithoutMethods = originalGroups?.filter(g => g.title !== 'Methods');
+
+        // Extract the Accessors group (if any) and prevent default rendering for it
+        const accessorsGroup = groupsWithoutMethods?.find(g => g.title === 'Accessors');
+        const groupsWithoutAccessors = groupsWithoutMethods?.filter(g => g.title !== 'Accessors');
 
         customizedModel.groups = groupsWithoutAccessors;
         const nonAccessorOutput = superPartials.memberWithGroups(customizedModel, options);
+
         customizedModel.groups = originalGroups;
 
         /** @type {string[]} */

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

@@ -33,8 +33,7 @@ type ExtendSubscriptionItemFreeTrialParams = {
 
 export class BillingAPI extends AbstractAPI {
   /**
-   * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
-   * It is advised to pin the SDK version to avoid breaking changes.
+   * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
    */
   public async getPlanList(params?: GetOrganizationListParams) {
     return this.request<PaginatedResourceResponse<CommercePlan[]>>({
@@ -45,8 +44,7 @@ export class BillingAPI extends AbstractAPI {
   }
 
   /**
-   * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
-   * It is advised to pin the SDK version to avoid breaking changes.
+   * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
    */
   public async cancelSubscriptionItem(subscriptionItemId: string, params?: CancelSubscriptionItemParams) {
     this.requireId(subscriptionItemId);
@@ -58,8 +56,7 @@ export class BillingAPI extends AbstractAPI {
   }
 
   /**
-   * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
-   * It is advised to pin the SDK version to avoid breaking changes.
+   * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
    */
   public async extendSubscriptionItemFreeTrial(
     subscriptionItemId: string,
@@ -74,8 +71,7 @@ export class BillingAPI extends AbstractAPI {
   }
 
   /**
-   * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
-   * It is advised to pin the SDK version to avoid breaking changes.
+   * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
    */
   public async getOrganizationBillingSubscription(organizationId: string) {
     this.requireId(organizationId);
@@ -86,8 +82,7 @@ export class BillingAPI extends AbstractAPI {
   }
 
   /**
-   * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
-   * It is advised to pin the SDK version to avoid breaking changes.
+   * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
    */
   public async getUserBillingSubscription(userId: string) {
     this.requireId(userId);

packages/backend/src/api/factory.ts

@@ -54,8 +54,7 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
     betaFeatures: new BetaFeaturesAPI(request),
     blocklistIdentifiers: new BlocklistIdentifierAPI(request),
     /**
-     * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
-     * It is advised to pin the SDK version to avoid breaking changes.
+     * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
      */
     billing: new BillingAPI(request),
     clients: new ClientAPI(request),

packages/backend/src/api/resources/CommercePlan.ts

@@ -4,9 +4,9 @@ import { Feature } from './Feature';
 import type { CommercePlanJSON } from './JSON';
 
 /**
- * The `CommercePlan` object is similar to the [`CommercePlanResource`](/docs/references/javascript/types/commerce-plan-resource) object as it holds information about a plan, as well as methods for managing it. However, the `CommercePlan` object is different in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/commerce/get/commerce/plans){{ target: '_blank' }} and is not directly accessible from the Frontend API.
+ * The `CommercePlan` object is similar to the [`CommercePlanResource`](/docs/references/javascript/types/commerce-plan-resource) object as it holds information about a plan, as well as methods for managing it. However, the `CommercePlan` object is different in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/commerce/get/commerce/plans) and is not directly accessible from the Frontend API.
  *
- * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to pin the SDK version to avoid breaking changes.
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
  */
 export class CommercePlan {
   constructor(

packages/backend/src/api/resources/CommerceSubscription.ts

@@ -4,9 +4,9 @@ import { CommerceSubscriptionItem } from './CommerceSubscriptionItem';
 import type { CommerceSubscriptionJSON } from './JSON';
 
 /**
- * The `CommerceSubscription` object is similar to the [`CommerceSubscriptionResource`](/docs/references/javascript/types/commerce-subscription-resource) object as it holds information about a subscription, as well as methods for managing it. However, the `CommerceSubscription` object is different in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/billing/get/organizations/%7Borganization_id%7D/billing/subscription){{ target: '_blank' }} and is not directly accessible from the Frontend API.
+ * The `CommerceSubscription` object is similar to the [`CommerceSubscriptionResource`](/docs/references/javascript/types/commerce-subscription-resource) object as it holds information about a subscription, as well as methods for managing it. However, the `CommerceSubscription` object is different in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/billing/get/organizations/%7Borganization_id%7D/billing/subscription) and is not directly accessible from the Frontend API.
  *
- * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to pin the SDK version to avoid breaking changes.
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
  */
 export class CommerceSubscription {
   constructor(

packages/backend/src/api/resources/CommerceSubscriptionItem.ts

@@ -4,9 +4,9 @@ import { CommercePlan } from './CommercePlan';
 import type { CommerceSubscriptionItemJSON } from './JSON';
 
 /**
- * The `CommerceSubscriptionItem` object is similar to the [`CommerceSubscriptionItemResource`](/docs/references/javascript/types/commerce-subscription-item-resource) object as it holds information about a subscription item, as well as methods for managing it. However, the `CommerceSubscriptionItem` object is different in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/commerce/get/commerce/subscription_items){{ target: '_blank' }} and is not directly accessible from the Frontend API.
+ * The `CommerceSubscriptionItem` object is similar to the [`CommerceSubscriptionItemResource`](/docs/references/javascript/types/commerce-subscription-item-resource) object as it holds information about a subscription item, as well as methods for managing it. However, the `CommerceSubscriptionItem` object is different in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/commerce/get/commerce/subscription_items) and is not directly accessible from the Frontend API.
  *
- * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to pin the SDK version to avoid breaking changes.
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
  */
 export class CommerceSubscriptionItem {
   constructor(

packages/backend/src/api/resources/Feature.ts

@@ -3,7 +3,7 @@ import type { FeatureJSON } from './JSON';
 /**
  * The `Feature` object represents a feature of a subscription plan.
  *
- * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to pin the SDK version to avoid breaking changes.
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
  */
 export class Feature {
   constructor(

packages/backend/src/api/resources/JSON.ts

@@ -828,8 +828,7 @@ export interface FeatureJSON extends ClerkResourceJSON {
 }
 
 /**
- * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
- * It is advised to pin the SDK version to avoid breaking changes.
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
  */
 export interface CommercePlanJSON extends ClerkResourceJSON {
   object: typeof ObjectType.CommercePlan;
@@ -860,8 +859,7 @@ type CommerceSubscriptionItemStatus =
   | 'upcoming';
 
 /**
- * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
- * It is advised to pin the SDK version to avoid breaking changes.
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
  */
 export interface CommerceSubscriptionItemJSON extends ClerkResourceJSON {
   object: typeof ObjectType.CommerceSubscriptionItem;

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

@@ -1158,8 +1158,7 @@ export class Clerk implements ClerkInterface {
   };
 
   /**
-   * @experimental
-   * This API is in early access and may change in future releases.
+   * @experimental This API is in early access and may change in future releases.
    *
    * Mount a api keys component at the target element.
    * @param targetNode Target to mount the APIKeys component.
@@ -1201,8 +1200,7 @@ export class Clerk implements ClerkInterface {
   };
 
   /**
-   * @experimental
-   * This API is in early access and may change in future releases.
+   * @experimental This API is in early access and may change in future releases.
    *
    * Unmount a api keys component from the target element.
    * If there is no component mounted at the target node, results in a noop.

packages/expo/src/provider/ClerkProvider.tsx

@@ -23,8 +23,8 @@ export type ClerkProviderProps = Without<React.ComponentProps<typeof ClerkReactP
   /**
    * 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.
-   * This API is experimental and may change at any moment.
-   * @experimental
+   *
+   * @experimental This API is experimental and may change at any moment.
    */
   __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.
-   * This API is experimental and may change at any moment.
-   * @experimental
+   *
+   * @experimental This API is experimental and may change at any moment.
    */
   __experimental_passkeys?: {
     get: ({

packages/react/src/components/CheckoutButton.tsx

@@ -7,7 +7,7 @@ import { assertSingleChild, normalizeWithDefaultValue, safeExecute } from '../ut
 import { withClerk } from './withClerk';
 
 /**
- * @experimental A button component that opens the Clerk Checkout drawer when clicked. This component must be rendered
+ * A button component that opens the Clerk Checkout drawer when clicked. This component must be rendered
  * inside a `<SignedIn />` component to ensure the user is authenticated.
  *
  * @example
@@ -43,6 +43,8 @@ import { withClerk } from './withClerk';
  *
  * @throws {Error} When rendered outside of a `<SignedIn />` component
  * @throws {Error} When `for="organization"` is used without an active organization context
+ *
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
  */
 export const CheckoutButton = withClerk(
   ({ clerk, children, ...props }: WithClerkProp<React.PropsWithChildren<__experimental_CheckoutButtonProps>>) => {

packages/react/src/components/PlanDetailsButton.tsx

@@ -6,7 +6,7 @@ import { assertSingleChild, normalizeWithDefaultValue, safeExecute } from '../ut
 import { withClerk } from './withClerk';
 
 /**
- * @experimental A button component that opens the Clerk Plan Details drawer when clicked. This component is part of
+ * A button component that opens the Clerk Plan Details drawer when clicked. This component is part of
  * Clerk's Billing feature which is available under a public beta.
  *
  * @example
@@ -31,7 +31,7 @@ import { withClerk } from './withClerk';
  * }
  * ```
  *
- * @see https://clerk.com/docs/billing/overview
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
  */
 export const PlanDetailsButton = withClerk(
   ({ clerk, children, ...props }: WithClerkProp<React.PropsWithChildren<__experimental_PlanDetailsButtonProps>>) => {

packages/react/src/components/SubscriptionDetailsButton.tsx

@@ -7,8 +7,7 @@ import { assertSingleChild, normalizeWithDefaultValue, safeExecute } from '../ut
 import { withClerk } from './withClerk';
 
 /**
- * @experimental A button component that opens the Clerk Subscription Details drawer when clicked. This component must be rendered
- * inside a `<SignedIn />` component to ensure the user is authenticated.
+ * A button component that opens the Clerk Subscription Details drawer when clicked. This component must be rendered inside a `<SignedIn />` component to ensure the user is authenticated.
  *
  * @example
  * ```tsx
@@ -38,7 +37,7 @@ import { withClerk } from './withClerk';
  * @throws {Error} When rendered outside of a `<SignedIn />` component
  * @throws {Error} When `for="organization"` is used without an active organization context
  *
- * @see https://clerk.com/docs/billing/overview
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
  */
 export const SubscriptionDetailsButton = withClerk(
   ({

packages/react/src/components/uiComponents.tsx

@@ -81,8 +81,8 @@ type UserButtonPropsWithoutCustomPages = Without<
   userProfileProps?: Pick<UserProfileProps, 'additionalOAuthScopes' | 'appearance'>;
   /**
    * Adding `asProvider` will defer rendering until the `<Outlet />` component is mounted.
-   * This API is experimental and may change at any moment.
-   * @experimental
+   *
+   * @experimental This API is experimental and may change at any moment.
    * @default undefined
    */
   __experimental_asProvider?: boolean;
@@ -99,6 +99,7 @@ type OrganizationSwitcherExportType = typeof _OrganizationSwitcher & {
   /**
    * The `<Outlet />` component can be used in conjunction with `asProvider` in order to control rendering
    * of the `<OrganizationSwitcher />` without affecting its configuration or any custom pages that could be mounted
+   *
    * @experimental This API is experimental and may change at any moment.
    */
   __experimental_Outlet: typeof OrganizationSwitcherOutlet;
@@ -111,8 +112,8 @@ type OrganizationSwitcherPropsWithoutCustomPages = Without<
   organizationProfileProps?: Pick<OrganizationProfileProps, 'appearance'>;
   /**
    * Adding `asProvider` will defer rendering until the `<Outlet />` component is mounted.
-   * This API is experimental and may change at any moment.
-   * @experimental
+   *
+   * @experimental This API is experimental and may change at any moment.
    * @default undefined
    */
   __experimental_asProvider?: boolean;
@@ -609,8 +610,7 @@ export const PricingTable = withClerk(
 );
 
 /**
- * @experimental
- * This component is in early access and may change in future releases.
+ * @experimental This component is in early access and may change in future releases.
  */
 export const APIKeys = withClerk(
   ({ clerk, component, fallback, ...props }: WithClerkProp<APIKeysProps & FallbackProp>) => {