fix(AuthProvider): split guardComponent into loadingComponent + guardComponent

[erickteowarang]

Summary

• AuthProvider's single guardComponent slot rendered for the union of !isReady and !isAuthenticated. Any sign-in screen wired into that slot — the obvious thing to do, and what the type name implies — flashes on every reload before the session is known. This contradicts the canonical pattern documented in useAuth's own JSDoc.
• Add loadingComponent for the !isReady state. Narrow guardComponent to fire only when isReady && !isAuthenticated (sign-in screens no longer flash).
• OAuth callback child-suppression now keys off loadingComponent — the slot that explicitly owns the !isReady state.
• Default flash protection: when autoLogin is enabled and a slot is omitted, the protected tree is hidden during that state instead of briefly rendering children. When autoLogin is off, children render in those windows — preserving the useAuthSuspense pattern (where a <Suspense> boundary inside the tree owns the loading UI) and public-app cases.

Default behavior matrix (no slots passed)

autoLogin	!isReady	isReady && !isAuthenticated
true	hidden	hidden
false / unset	children render	children render

Migration

// Before — guardComponent doubled as loading + unauthenticated
<AuthProvider client={authClient} guardComponent={() => <LoadingScreen />}>

// After — use the slot that matches your intent
<AuthProvider
  client={authClient}
  loadingComponent={() => <LoadingScreen />}
  guardComponent={() => <SignInScreen />}
>

// Or, with autoLogin, omit both and rely on default flash protection
<AuthProvider client={authClient} autoLogin>

If you were passing a loading UI to guardComponent, rename to loadingComponent. If you were passing a sign-in screen, keep it on guardComponent — it will no longer flash before the auth check resolves.

Test plan

• pnpm type-check clean
• pnpm lint 0 warnings / 0 errors
• pnpm test — 1015 tests pass, including:
  • New regression: guardComponent does NOT render during !isReady
  • Renamed: loadingComponent renders during !isReady
  • Reframed: callback-pending suppression triggers off loadingComponent
  • New: autoLogin hides children during !isReady when no loadingComponent is set
  • New: autoLogin hides children during !isAuthenticated when no guardComponent is set
  • New: without autoLogin, children render during !isReady (Suspense pattern preserved)
• pnpm fmt applied
• Changeset added (.changeset/auth-loading-component.md, minor)
• Docs updated (docs/concepts/authentication.md)

🤖 Generated with Claude Code

[IzumiSy]

/review

[github-actions]

Generated by API Design Review for issue #269

[github-actions]

[2/2 — Medium] guardComponent-only consumers get a blank screen during OAuth callback

The condition props.loadingComponent == null means: when a consumer provides only guardComponent (no loadingComponent), resolvedChildren is set to null during a pending OAuth callback.

Execution path with guardComponent only + callbackStatus === "pending":

1. resolvedChildren = null (this line)
2. hasGuard = true (since guardComponent is set)
3. AuthGuard receives children = null
4. !isReady branch in AuthGuard: loadingComponent ? loadingComponent() : children → undefined ? ... : null → blank screen

The migration note says "if you were passing a sign-in screen, keep it on guardComponent", which is exactly the consumer who reaches this path. Previously with the old code (props.guardComponent == null), those consumers would have seen guardComponent() rendered during the OAuth callback exchange. Now they see nothing.

This is probably intentional (you don't want a sign-in screen flashing during an active OAuth flow), but:

• The migration guide doesn't document this behavioral difference for the OAuth callback case
• The test "should render guarded children while callback is pending" was removed and replaced with a loadingComponent variant — leaving no coverage for the guardComponent-only + callback-pending path

Suggested fix: add a sentence to the changeset migration note acknowledging this and cover the scenario in a test:

it("should render nothing during callback when only guardComponent is set", async () => {
  // guardComponent-only consumers see null (not their guard) during OAuth
  // callback, because loadingComponent owns the !isReady state.
  ...

Alternatively, if showing guardComponent during callback is preferable UX (avoiding a blank flash), the condition could be:

callbackStatus === "pending" && props.loadingComponent == null && props.guardComponent == null
  ? null
  : props.children;

though this would render the sign-in screen during callback, which is the original bug this PR fixes for the loading case.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@tailor-platform/app-shell@269

npm i https://pkg.pr.new/@tailor-platform/app-shell-sdk-plugin@269

npm i https://pkg.pr.new/@tailor-platform/app-shell-vite-plugin@269

commit: 659ddd6

[IzumiSy]

loadingComponent() and guardComponent() are invoked as plain function calls here, which means any hooks inside them become hooks of the AuthGuard component. Since these calls are conditional (loadingComponent() only when !isReady, guardComponent() only when !isAuthenticated), this violates React's rules of hooks — the hook call order inside AuthGuard changes depending on auth state.

In practice, passing a component that calls hooks (e.g. a sign-in screen using useAuth()) to guardComponent triggers: React has detected a change in the order of Hooks called by AuthGuard.

Using createElement gives each slot its own fiber with an isolated hook scope:

Suggested change

	if (loadingComponent) return loadingComponent();
	return hideUnresolved ? null : children;
	}
	if (!isAuthenticated) {
	if (guardComponent) return guardComponent();
	if (loadingComponent) return createElement(loadingComponent);
	return hideUnresolved ? null : children;
	}
	if (!isAuthenticated) {
	if (guardComponent) return createElement(guardComponent);