feat: Introduce Waitlist component docs

docs/authentication/configuration/restrictions.mdx

@@ -16,6 +16,9 @@ To configure sign-up modes:
 1. Under the **Sign-up modes** section, you can enable one of the following options:
    - **[Public](#public)**
    - **[Restricted](#restricted)**
+   - **[Waitlist](#waitlist)**
+   > [!NOTE]
+   > The `<Waitlist />` component is only available in Core 2. If you are using Next.js is available after <code>@clerk/nextjs\@6.2.0</code>
 
 ### Public
 
@@ -31,6 +34,18 @@ Additional features available in **Restricted** mode:
 
 - The [`<SignUp />`](/docs/components/authentication/sign-up) is accessible only to users who have been invited and have a valid invitation link. Users who don't have access will see a message indicating that they need an invitation to sign up.
 
+### Waitlist
+
+In **Waitlist** mode, users can register their interest in your application by joining a waitlist. This mode is ideal for applications in early development stages or those wanting to generate interest before launch.
+
+Additional features available in **Waitlist** mode:
+
+- The [`<SignIn />`](/docs/components/authentication/sign-in) component will only be accessible to users who have been approved from the waitlist.
+
+- The [`<SignUp />`](/docs/components/authentication/sign-up) is accessible only to users who have been invited and have a valid invitation link. Users who don't have access will see a message indicating that they need an invitation to sign up.
+
+- The [`<Waitlist />`](/docs/components/waitlist/overview) component provides a form where users can submit their details to join the waitlist. Once approved by admins, users will receive an email with access instructions.
+
 ## Allowlist
 
 > [!NOTE]

docs/components/waitlist/overview.mdx

@@ -0,0 +1,233 @@
+---
+title: '`<Waitlist />` component'
+description: The <Waitlist /> component renders a waitlist form that allows users to join for early access to your application.
+---
+
+![The \<Waitlist /> component renders a waitlist form that allows users to join for early access to your application.](/docs/images/ui-components/waitlist.svg)
+
+The `<Waitlist />` component renders a waitlist form that allows users to join for early access to your application.
+
+> [!NOTE]
+> The `<Waitlist />` component is only available in Core 2. If you are using Next.js is available after <code>@clerk/nextjs\@6.2.0</code>
+
+## Properties
+
+All props are optional.
+
+<Properties>
+  - `appearance`
+  - <code>[Appearance](/docs/customization/overview) | undefined</code>
+
+  Optional object to style your components. Will only affect [Clerk components](/docs/components/overview) and not [Account Portal](/docs/customization/account-portal/overview) pages.
+
+  ---
+
+  - `afterJoinWaitlistUrl`
+  - `string`
+
+  Full URL or path to navigate to after joining the waitlist.
+
+  ---
+
+  - `signInUrl`
+  - `string`
+
+  Full URL or path to the sign in page. Use this property to provide the target of the 'Sign In' link that's rendered. It's recommended to use [NEXT\_PUBLIC\_CLERK\_SIGN\_IN\_URL](/docs/deployments/clerk-environment-variables#sign-in-and-sign-up-redirects) instead.
+</Properties>
+
+## Usage with frameworks
+
+The following example includes a basic implementation of the `<Waitlist />` component. You can use this as a starting point for your own implementation.
+
+<Tabs items={["Next.js", "React"]}>
+  <Tab>
+    <CodeBlockTabs options={["App Router", "Pages Router"]}>
+      ```jsx {{ filename: '/app/waitlist/[[...waitlist]]/page.tsx' }}
+      import { Waitlist } from '@clerk/nextjs'
+
+      export default function WaitlistPage() {
+        return <Waitlist />
+      }
+      ```
+
+      ```jsx {{ filename: '/pages/waitlist/[[...index]].tsx' }}
+      import { Waitlist } from '@clerk/nextjs'
+
+      export default function WaitlistPage() {
+        return <Waitlist />
+      }
+      ```
+    </CodeBlockTabs>
+  </Tab>
+
+  <Tab>
+    ```jsx {{ filename: '/waitlist.tsx' }}
+    import { Waitlist } from '@clerk/clerk-react'
+
+    export default function WaitlistPage() {
+      return <Waitlist />
+    }
+    ```
+  </Tab>
+</Tabs>
+
+## Usage with JavaScript
+
+The following methods available on an instance of the [`Clerk`](/docs/references/javascript/clerk/clerk) class are used to render and control the `<Waitlist />` component:
+
+- [`mountWaitlist()`](#mount-waitlist)
+- [`unmountWaitlist()`](#unmount-waitlist)
+- [`openWaitlist()`](#open-waitlist)
+- [`closeWaitlist()`](#close-waitlist)
+
+The following examples assume that you have followed the [quickstart](/docs/quickstarts/javascript) in order to add Clerk to your JavaScript application.
+
+### <code>mount<wbr />Waitlist()</code>
+
+Render the `<Waitlist />` component to an HTML `<div>` element.
+
+```typescript
+function mountWaitlist(node: HTMLDivElement, props?: WaitlistProps): void
+```
+
+### <code>mount<wbr />Waitlist()</code> params
+
+<Properties>
+  - `node`
+  - [`HTMLDivElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDivElement)
+
+  The `<div>` element used to render in the `<Waitlist />` component
+
+  ---
+
+  - `props?`
+  - [`WaitlistProps`](#properties)
+
+  The properties to pass to the `<Waitlist />` component
+</Properties>
+
+#### `mountWaitlist()` usage
+
+```js {{ filename: 'main.js', mark: [13] }}
+import { Clerk } from '@clerk/clerk-js'
+
+// Initialize Clerk with your Clerk publishable key
+const clerk = new Clerk('{{pub_key}}')
+await clerk.load()
+
+document.getElementById('app').innerHTML = `
+  <div id="waitlist"></div>
+`
+
+const waitlistDiv = document.getElementById('waitlist')
+
+clerk.mountWaitlist(waitlistDiv)
+```
+
+### <code>unmount<wbr />Waitlist()</code>
+
+Unmount and run cleanup on an existing `<Waitlist />` component instance.
+
+```typescript
+function unmountWaitlist(node: HTMLDivElement): void
+```
+
+#### `unmountWaitlist()` params
+
+<Properties>
+  - `node`
+  - [`HTMLDivElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDivElement)
+
+  The container `<div>` element with a rendered `<Waitlist />` component instance
+</Properties>
+
+#### `unmountWaitlist()` usage
+
+```js {{ filename: 'main.js', mark: [17] }}
+import { Clerk } from '@clerk/clerk-js'
+
+// Initialize Clerk with your Clerk publishable key
+const clerk = new Clerk('{{pub_key}}')
+await clerk.load()
+
+document.getElementById('app').innerHTML = `
+  <div id="waitlist"></div>
+`
+
+const waitlistDiv = document.getElementById('waitlist')
+
+clerk.mountWaitlist(waitlistDiv)
+
+// ...
+
+clerk.unmountWaitlist(waitlistDiv)
+```
+
+### `openWaitlist()`
+
+Opens the `<Waitlist />` component as an overlay at the root of your HTML `body` element.
+
+```typescript
+function openWaitlist(props?: WaitlistProps): void
+```
+
+#### `openWaitlist()` params
+
+<Properties>
+  - `props?`
+  - [`WaitlistProps`](#properties)
+
+  The properties to pass to the `<Waitlist />` component
+</Properties>
+
+#### `openWaitlist()` usage
+
+```js {{ filename: 'main.js', mark: [13] }}
+import { Clerk } from '@clerk/clerk-js'
+
+// Initialize Clerk with your Clerk publishable key
+const clerk = new Clerk('{{pub_key}}')
+await clerk.load()
+
+document.getElementById('app').innerHTML = `
+  <div id="waitlist"></div>
+`
+
+const waitlistDiv = document.getElementById('waitlist')
+
+clerk.openWaitlist(waitlistDiv)
+```
+
+### `closeWaitlist()`
+
+Closes the waitlist overlay.
+
+```typescript
+function closeWaitlist(): void
+```
+
+#### `closeWaitlist()` usage
+
+```js {{ filename: 'main.js', mark: [17] }}
+import { Clerk } from '@clerk/clerk-js'
+
+// Initialize Clerk with your Clerk publishable key
+const clerk = new Clerk('{{pub_key}}')
+await clerk.load()
+
+document.getElementById('app').innerHTML = `
+  <div id="waitlist"></div>
+`
+
+const waitlistDiv = document.getElementById('waitlist')
+
+clerk.openWaitlist(waitlistDiv)
+
+// ...
+
+clerk.closeWaitlist(waitlistDiv)
+```
+
+## Customization
+
+To learn about how to customize Clerk components, see the [customization documentation](/docs/customization/overview).

docs/manifest.json

@@ -219,6 +219,18 @@
                 ]
               ]
             },
+            {
+              "title": "Waitlist Components",
+              "items": [
+                [
+                  {
+                    "title": "`<Waitlist />`",
+                    "wrap": false,
+                    "href": "/docs/components/waitlist/overview"
+                  }
+                ]
+              ]
+            },
             {
               "title": "Control Components",
               "items": [
@@ -1854,6 +1866,10 @@
                           "title": "Organization methods",
                           "href": "/docs/references/javascript/clerk/organization-methods"
                         },
+                        {
+                          "title": "Waitlist methods",
+                          "href": "/docs/references/javascript/clerk/waitlist-methods"
+                        },
                         {
                           "title": "Redirect methods",
                           "href": "/docs/references/javascript/clerk/redirect-methods"

docs/references/javascript/clerk/clerk.mdx

@@ -525,6 +525,13 @@ The `Clerk` class also contains a number of methods for interacting with Clerk's
 - [`mountOrganizationList`](/docs/components/organization/organization-list#mount-organization-list)
 - [`unmountOrganizationList`](/docs/components/organization/organization-list#unmount-organization-list)
 
+### `<Waitlist />`
+
+- [`mountWaitlist()`](/docs/components/waitlist/overview#mount-waitlist)
+- [`unmountWaitlist()`](/docs/components/waitlist/overview#unmount-waitlist)
+- [`openWaitlist()`](/docs/components/waitlist/overview#open-waitlist)
+- [`closeWaitlist()`](/docs/components/waitlist/overview#close-waitlist)
+
 ## Additional methods
 
 In addition to the methods listed above, the `Clerk` class also has the following methods:
@@ -534,6 +541,10 @@ In addition to the methods listed above, the `Clerk` class also has the followin
 - [`getOrganization()`](/docs/references/javascript/clerk/organization-methods#get-organization)
 - [`createOrganization()`](/docs/references/javascript/clerk/organization-methods#create-organization)
 
+### Waitlist
+
+- [`joinWaitlist()`](/docs/references/javascript/clerk/waitlist-methods#get-organization)
+
 ### Redirect
 
 - [`navigate()`](/docs/references/javascript/clerk/redirect-methods#navigate)

docs/references/javascript/clerk/waitlist-methods.mdx

@@ -0,0 +1,69 @@
+---
+title: Waitlist methods
+description: Explore methods on the Clerk class that allow you to add users to your waitlist.
+---
+
+These methods on the [`Clerk`](/docs/references/javascript/clerk/clerk) class allow you to add users to your [waitlist](/docs/authentication/configuration/restrictions#waitlist).
+
+The following example assume:
+
+- you have followed the [quickstart](/docs/quickstarts/javascript) in order to add Clerk to your JavaScript application
+- you have set your sign-up mode to [**Waitlist**](docs/authentication/configuration/restrictions#waitlist)
+
+## `joinWaitlist()`
+
+Create a new waitlist entry programatically.
+
+```typescript
+function joinWaitlist({ emailAddress }: JoinWaitlistParams): Promise<Waitlist>
+```
+
+### Parameters
+
+<Properties>
+  - `emailAddress`
+  - `string`
+
+  The email address of the user you want to add in the waitlist
+</Properties>
+
+### Example
+
+<Tabs items={['NPM module']}>
+  <Tab>
+    <CodeBlockTabs options={["main.js", "index.html"]}>
+      ```js {{ filename: 'main.js', mark: [[9, 12]] }}
+      import { Clerk } from '@clerk/clerk-js'
+
+      // Initialize Clerk with your Clerk publishable key
+      const clerk = new Clerk('{{pub_key}}')
+      await clerk.load()
+
+      const joinWaitlistButton = document.getElementById('join-waitlist-button')
+      joinWaitlistButton.addEventListener('click', () => {
+        clerk
+          .joinWaitlist({ emailAddress: '[email protected]' })
+          .then((res) => console.log(res))
+          .catch((error) => console.log('An error occurred:', error.errors))
+      })
+      ```
+
+      ```html {{ filename: 'index.html' }}
+      <!doctype html>
+      <html lang="en">
+        <head>
+          <meta charset="UTF-8" />
+          <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+          <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+          <title>Clerk + JavaScript App</title>
+        </head>
+        <body>
+          <div id="app"></div>
+          <button id="join-waitlist-button">Join Waitlist</button>
+          <script type="module" src="/main.js"></script>
+        </body>
+      </html>
+      ```
+    </CodeBlockTabs>
+  </Tab>
+</Tabs>