fix(astro): Introduce protect-fallback slot to avoid server islands conflict

.changeset/fair-insects-sort.md

@@ -0,0 +1,28 @@
+---
+"@clerk/astro": minor
+---
+
+Introduce `protect-fallback` slot to avoid naming conflicts with Astro's server islands [`fallback` slot](https://docs.astro.build/en/guides/server-islands/#server-island-fallback-content). 
+
+When using Clerk's `<Protect>` component with `server:defer`, you can now use both slots:
+- `fallback`: Default loading content
+- `protect-fallback`: Shows when a user doesn't have the `role` or `permission` to access the protected content
+
+Regular usage without server islands:
+
+```astro
+<Protect role="admin">
+  <p slot="fallback">Not an admin</p>
+  <p>You're an admin</p>
+</Protect>
+```
+
+Example with server islands:
+
+```astro
+<Protect server:defer role="admin">
+  <p slot="fallback">Loading...</p>
+  <p slot="protect-fallback">Not an admin</p>
+  <p>You're an admin</p>
+</Protect>
+```

integration/templates/astro-node/src/pages/server-islands.astro

@@ -0,0 +1,20 @@
+---
+import { Protect } from "@clerk/astro/components";
+import Layout from "../layouts/Layout.astro";
+---
+
+<Layout title="Page is only accessible by members">
+  <div class="w-full flex justify-center flex-col">
+    <Protect server:defer role="admin">
+      <p slot="fallback">Loading</p>
+      <Fragment slot="protect-fallback">
+        <h1 class="text-2xl text-center">Not an admin</h1>
+        <a
+          class="text-sm text-center text-gray-100 transition hover:text-gray-400"
+          href="/only-members">Go to Members Page</a
+        >
+      </Fragment>
+      <h1 class="text-2xl text-center">I'm an admin</h1>
+    </Protect>
+  </div>
+</Layout>

integration/tests/astro/components.test.ts

@@ -481,4 +481,30 @@ testAgainstRunningApps({ withPattern: ['astro.node.withCustomRoles'] })('basic f
     // Components should be rendered on hard reload
     await u.po.userButton.waitForMounted();
   });
+
+  test('server islands protect component shows correct states', async ({ page, context }) => {
+    const u = createTestUtils({ app, page, context });
+
+    await u.page.goToRelative('/server-islands');
+    // The loading slot for server islands will appear very quickly.
+    // Wait for next state (default slot) to be ready
+    await expect(u.page.getByText('Loading')).toBeHidden();
+    await expect(u.page.getByText('Not an admin')).toBeVisible();
+
+    // Sign in as admin user
+    await u.page.goToRelative('/sign-in');
+    await u.po.signIn.waitForMounted();
+    await u.po.signIn.signInWithEmailAndInstantPassword({
+      email: fakeAdmin2.email,
+      password: fakeAdmin2.password,
+    });
+    await u.po.expect.toBeSignedIn();
+    await u.po.organizationSwitcher.waitForMounted();
+    await u.po.organizationSwitcher.waitForAnOrganizationToSelected();
+
+    // Visit page again
+    await u.page.goToRelative('/server-islands');
+    await expect(u.page.getByText('Loading')).toBeHidden();
+    await expect(u.page.getByText("I'm an admin")).toBeVisible();
+  });
 });

packages/astro/src/astro-components/control/Protect.astro

@@ -27,9 +27,18 @@ type Props = ProtectProps & {
 const { isStatic, ...props } = Astro.props;
 
 const ProtectComponent = isStaticOutput(isStatic) ? ProtectCSR : ProtectSSR;
+
+// Note: Astro server islands also use a "fallback" slot for loading states
+// See: https://docs.astro.build/en/guides/server-islands/#server-island-fallback-content
+// We use "protect-fallback" as our preferred slot name to avoid conflicts
+const hasProtectFallback = Astro.slots.has('protect-fallback');
 ---
 
 <ProtectComponent {...props}>
   <slot />
-  <slot name="fallback" slot="fallback" />
+  {hasProtectFallback ? (
+    <slot name="protect-fallback" slot="protect-fallback" />
+  ) : (
+    <slot name="fallback" slot="fallback" />
+  )}
 </ProtectComponent>

packages/astro/src/astro-components/control/ProtectSSR.astro

@@ -9,6 +9,18 @@ const isUnauthorized =
   (typeof Astro.props.condition === "function" &&
     !Astro.props.condition(has)) ||
   ((Astro.props.role || Astro.props.permission) && !has(Astro.props));
+
+const hasProtectFallback = Astro.slots.has('protect-fallback');
 ---
 
-{isUnauthorized ? <slot name="fallback" /> : <slot />}
+{
+  isUnauthorized ? (
+    hasProtectFallback ? (
+      <slot name="protect-fallback" />
+    ) : (
+      <slot name="fallback" />
+    )
+  ) : (
+    <slot />
+  )
+}