feat(ui): add UserButton controller

.changeset/mosaic-user-button-controller.md

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

.changeset/mosaic-user-button-integration.md

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

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

@@ -7,13 +7,16 @@ import { useClerk } from './useClerk';
  *
  * @internal
  */
-export function useAttemptToEnableOrganizations(caller: 'useOrganization' | 'useOrganizationList') {
+export function useAttemptToEnableOrganizations(
+ caller: 'useOrganization' | 'useOrganizationList',
+ { enabled = true }: { enabled?: boolean } = {},
+) {
  const clerk = useClerk();
  const hasAttempted = useRef(false);
 
  useEffect(() => {
  // Guard to not run this effect twice on Clerk resource update
- if (hasAttempted.current) {
+ if (!enabled || hasAttempted.current) {
  return;
  }
 
@@ -23,5 +26,5 @@ export function useAttemptToEnableOrganizations(caller: 'useOrganization' | 'use
  for: 'organizations',
  caller,
  });
- }, [clerk, caller]);
+ }, [clerk, caller, enabled]);
 }

packages/shared/src/react/hooks/useOrganization.tsx

@@ -61,6 +61,12 @@ export type UseOrganizationParams = {
  * </ul>
  */
  invitations?: true | PaginatedHookConfig<GetInvitationsParams>;
+ /**
+ * Skip the development prompt that offers to enable Organizations.
+ *
+ * @internal
+ */
+ __internal_skipAttemptToEnableOrganizations?: boolean;
 };
 
 /**
@@ -275,10 +281,13 @@ export function useOrganization<T extends UseOrganizationParams>(params?: T): Us
  membershipRequests: membershipRequestsListParams,
  memberships: membersListParams,
  invitations: invitationsListParams,
+ __internal_skipAttemptToEnableOrganizations,
  } = params || {};
 
  useAssertWrappedByClerkProvider('useOrganization');
- useAttemptToEnableOrganizations('useOrganization');
+ useAttemptToEnableOrganizations('useOrganization', {
+ enabled: !__internal_skipAttemptToEnableOrganizations,
+ });
 
  const organization = useOrganizationBase();
  const session = useSessionBase();

packages/shared/src/react/hooks/useOrganizationList.tsx

@@ -253,7 +253,10 @@ export function useOrganizationList<T extends UseOrganizationListParams>(params?
  const { userMemberships, userInvitations, userSuggestions } = params || {};
 
  useAssertWrappedByClerkProvider('useOrganizationList');
- useAttemptToEnableOrganizations('useOrganizationList');
+ // No list keys means this call is not using Organizations; the prompt is for the lists.
+ useAttemptToEnableOrganizations('useOrganizationList', {
+ enabled: userMemberships !== undefined || userInvitations !== undefined || userSuggestions !== undefined,
+ });
 
  const userMembershipsSafeValues = useWithSafeValues(userMemberships, {
  initialPage: 1,

packages/swingset/src/stories/user-button.mdx

@@ -74,7 +74,7 @@ Exports are flat (not `UserButton.Trigger`) so each part declares its own `'use
 ## Trigger
 
 The active workspace's avatar and what it is called: the org and its plan wherever one heads the
-trigger, the account otherwise.
+trigger, no selection when personal is hidden and none is active, the account otherwise.
 
 `renderTriggerLabel={false}` leaves the avatar alone.
 
@@ -164,6 +164,18 @@ accounts" ever meant here.
  storyModule={UserButtonStories}
 />
 
+## No organization selected
+
+`hidePersonal` withholds the personal workspace — the instance does this when it forces an
+organization, or the app does it itself. With no org active either, the lead is not the account:
+trigger and header say **No organization selected**, the mark is square, and the gear is **Manage
+account**.
+
+<Story
+ name='NoOrganizationSelected'
+ storyModule={UserButtonStories}
+/>
+
 ## Menu items
 
 `customMenuItems` adds the app's own rows to the foot of the popup, ahead of Clerk's own. A row with

packages/swingset/src/stories/user-button.stories.tsx

@@ -143,9 +143,19 @@ const LATENCY_MS = 800;
  * The actions that would navigate somewhere in a real app (Manage, Invite, Create organization, Add
  * account) have nowhere to go here, so they only close the popover.
  */
-function usePrototype(): Omit<UserButtonProps, 'mode'> {
+function usePrototype({
+ hidePersonal = false,
+ startWithoutOrganization = false,
+}: {
+ hidePersonal?: boolean;
+ startWithoutOrganization?: boolean;
+} = {}): Omit<UserButtonProps, 'mode'> {
  const [open, setOpen] = useState(false);
- const [accounts, setAccounts] = useState(initialAccounts);
+ const [accounts, setAccounts] = useState(() =>
+ startWithoutOrganization
+ ? initialAccounts.map(a => (a.session.sessionId === colin.sessionId ? { ...a, activeOrganizationId: null } : a))
+ : initialAccounts,
+ );
  const [activeSessionId, setActiveSessionId] = useState(colin.sessionId);
  const [pendingKey, setPendingKey] = useState<string | null>(null);
 
@@ -196,6 +206,7 @@ function usePrototype(): Omit<UserButtonProps, 'mode'> {
  suggestions: account.suggestions,
  invitations: account.invitations,
  additionalSessions: accounts.filter(a => a.session.sessionId !== activeSessionId).map(a => a.session),
+ hidePersonal,
  // Selecting an organization only ever acts on the active account, and is the one action that
  // closes the surface behind it.
  onSelectOrganization: organizationId =>
@@ -300,6 +311,19 @@ export function User(_args: Record<string, unknown>) {
  );
 }
 
+export function NoOrganizationSelected(_args: Record<string, unknown>) {
+ const prototype = usePrototype({ hidePersonal: true, startWithoutOrganization: true });
+
+ // Personal is withheld and nothing is active, so the lead is no selection — not the account.
+ // Picking an organization leaves it.
+ return (
+ <UserButtonView
+ {...prototype}
+ mode='combined'
+ />
+ );
+}
+
 export function SingleSession(_args: Record<string, unknown>) {
  const prototype = usePrototype();
 

packages/ui/src/hooks/useOrganizationListInView.ts

@@ -5,14 +5,18 @@ import { useInView } from './useInView';
 
 /**
  * @internal
+ *
+ * `enabled` withholds the list params so the three requests do not start. Defaults on.
  */
-export const useOrganizationListInView = () => {
- const { userMemberships, userInvitations, userSuggestions } = useOrganizationList(organizationListParams);
+export const useOrganizationListInView = ({ enabled = true }: { enabled?: boolean } = {}) => {
+ const { userMemberships, userInvitations, userSuggestions } = useOrganizationList(
+ enabled ? organizationListParams : undefined,
+ );
 
  const { ref } = useInView({
  threshold: 0,
  onChange: inView => {
- if (!inView) {
+ if (!enabled || !inView) {
  return;
  }
  if (userMemberships.hasNextPage) {

packages/ui/src/mosaic/components/button/submit-button.test.tsx

@@ -317,19 +317,29 @@ describe('Mosaic SubmitButton spin delay', () => {
  expect(atoms(spinner()).length).toBeLessThan(hidden.length);
  });
 
- // A consumer who already knows the action is slow has nothing to gain by waiting.
+ // A consumer who already knows the action is slow has nothing to gain by waiting: there is no
+ // delay left to outlast, so the spinner shows in the render that starts the action rather than a
+ // timer's.
  it('lets the consumer opt out of the delay', () => {
- render(
+const { rerender } = render(
  <SubmitButton
  isPending
- spinDelay={{ delay: 0 }}
+ spinDelay={{ delay: 1000 }}
  >
  Save
  </SubmitButton>,
  );
  const hidden = atoms(spinner());
 
- advance(0);
+ rerender(
+ <SubmitButton
+ isPending
+ spinDelay={{ delay: 0 }}
+ >
+ Save
+ </SubmitButton>,
+ );
+
  expect(atoms(spinner()).length).toBeLessThan(hidden.length);
  });
 

packages/ui/src/mosaic/hooks/__tests__/useSpinDelay.test.ts

@@ -76,6 +76,27 @@ describe('useSpinDelay', () => {
  expect(result.current).toBeNull();
  });
 
+ // Direct feedback on a click has nothing to debounce, so a zero delay must not cost a timer's
+ // worth of render passes before the spinner appears.
+ it('surfaces the value in the same pass when there is no delay to wait out', async () => {
+ const { result, rerender } = render(null, { delay: 0, minDuration: 200 });
+ await act(() => rerender({ value: 'a' }));
+
+ expect(result.current).toBe('a');
+ });
+
+ it('still holds a zero-delay value for minDuration', async () => {
+ const { result, rerender } = render(null, { delay: 0, minDuration: 200 });
+ await act(() => rerender({ value: 'a' }));
+ await act(() => rerender({ value: null }));
+
+ await advance(199);
+ expect(result.current).toBe('a');
+
+ await advance(1);
+ expect(result.current).toBeNull();
+ });
+
  it('swaps to a new value immediately when one replaces another mid-show', async () => {
  const { result, rerender } = render(null, { delay: 500, minDuration: 200 });
  await act(() => rerender({ value: 'a' }));

packages/ui/src/mosaic/hooks/useSpinDelay.ts

@@ -1,7 +1,7 @@
 import { useEffect, useRef, useState } from 'react';
 
 export interface SpinDelayOptions {
- /** Wait this long before showing the value, so quick actions never flash a spinner. */
+ /** Wait this long before showing the value, so quick actions never flash a spinner. `0` shows it straight away. */
  delay?: number;
  /** Once shown, keep the value up at least this long, so the spinner never flickers off. */
  minDuration?: number;
@@ -25,11 +25,17 @@ export function useSpinDelay<T>(value: T | null, options: SpinDelayOptions = {})
  const shownAt = useRef(0);
 
  useEffect(() => {
- // Nothing showing yet: arm a timer so the value only surfaces if it outlasts `delay`.
+ // Nothing showing yet: arm a timer so the value only surfaces if it outlasts `delay`. With no
+ // delay there is nothing to outlast, so it surfaces in this pass rather than a timer's.
  if (shown === null) {
  if (value === null) {
  return;
  }
+ if (delay <= 0) {
+ shownAt.current = Date.now();
+ setShown(value);
+ return;
+ }
  const timer = setTimeout(() => {
  shownAt.current = Date.now();
  setShown(value);

.changeset/mosaic-user-button-controller.md

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

.changeset/mosaic-user-button-integration.md

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

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

@@ -7,13 +7,16 @@ import { useClerk } from './useClerk';
  *
  * @internal
  */
-export function useAttemptToEnableOrganizations(caller: 'useOrganization' | 'useOrganizationList') {
+export function useAttemptToEnableOrganizations(
+ caller: 'useOrganization' | 'useOrganizationList',
+ { enabled = true }: { enabled?: boolean } = {},
+) {
  const clerk = useClerk();
  const hasAttempted = useRef(false);
 
  useEffect(() => {
  // Guard to not run this effect twice on Clerk resource update
- if (hasAttempted.current) {
+ if (!enabled || hasAttempted.current) {
  return;
  }
 
@@ -23,5 +26,5 @@ export function useAttemptToEnableOrganizations(caller: 'useOrganization' | 'use
  for: 'organizations',
  caller,
  });
- }, [clerk, caller]);
+ }, [clerk, caller, enabled]);
 }

packages/shared/src/react/hooks/useOrganization.tsx

@@ -61,6 +61,12 @@ export type UseOrganizationParams = {
  * </ul>
  */
  invitations?: true | PaginatedHookConfig<GetInvitationsParams>;
+ /**
+ * Skip the development prompt that offers to enable Organizations.
+ *
+ * @internal
+ */
+ __internal_skipAttemptToEnableOrganizations?: boolean;
 };
 
 /**
@@ -275,10 +281,13 @@ export function useOrganization<T extends UseOrganizationParams>(params?: T): Us
  membershipRequests: membershipRequestsListParams,
  memberships: membersListParams,
  invitations: invitationsListParams,
+ __internal_skipAttemptToEnableOrganizations,
  } = params || {};
 
  useAssertWrappedByClerkProvider('useOrganization');
- useAttemptToEnableOrganizations('useOrganization');
+ useAttemptToEnableOrganizations('useOrganization', {
+ enabled: !__internal_skipAttemptToEnableOrganizations,
+ });
 
  const organization = useOrganizationBase();
  const session = useSessionBase();

packages/shared/src/react/hooks/useOrganizationList.tsx

@@ -253,7 +253,10 @@ export function useOrganizationList<T extends UseOrganizationListParams>(params?
  const { userMemberships, userInvitations, userSuggestions } = params || {};
 
  useAssertWrappedByClerkProvider('useOrganizationList');
- useAttemptToEnableOrganizations('useOrganizationList');
+ // No list keys means this call is not using Organizations; the prompt is for the lists.
+ useAttemptToEnableOrganizations('useOrganizationList', {
+ enabled: userMemberships !== undefined || userInvitations !== undefined || userSuggestions !== undefined,
+ });
 
  const userMembershipsSafeValues = useWithSafeValues(userMemberships, {
  initialPage: 1,

packages/swingset/src/stories/user-button.mdx

@@ -74,7 +74,7 @@ Exports are flat (not `UserButton.Trigger`) so each part declares its own `'use
 ## Trigger
 
 The active workspace's avatar and what it is called: the org and its plan wherever one heads the
-trigger, the account otherwise.
+trigger, no selection when personal is hidden and none is active, the account otherwise.
 
 `renderTriggerLabel={false}` leaves the avatar alone.
 
@@ -164,6 +164,18 @@ accounts" ever meant here.
  storyModule={UserButtonStories}
 />
 
+## No organization selected
+
+`hidePersonal` withholds the personal workspace — the instance does this when it forces an
+organization, or the app does it itself. With no org active either, the lead is not the account:
+trigger and header say **No organization selected**, the mark is square, and the gear is **Manage
+account**.
+
+<Story
+ name='NoOrganizationSelected'
+ storyModule={UserButtonStories}
+/>
+
 ## Menu items
 
 `customMenuItems` adds the app's own rows to the foot of the popup, ahead of Clerk's own. A row with

packages/swingset/src/stories/user-button.stories.tsx

@@ -143,9 +143,19 @@ const LATENCY_MS = 800;
  * The actions that would navigate somewhere in a real app (Manage, Invite, Create organization, Add
  * account) have nowhere to go here, so they only close the popover.
  */
-function usePrototype(): Omit<UserButtonProps, 'mode'> {
+function usePrototype({
+ hidePersonal = false,
+ startWithoutOrganization = false,
+}: {
+ hidePersonal?: boolean;
+ startWithoutOrganization?: boolean;
+} = {}): Omit<UserButtonProps, 'mode'> {
  const [open, setOpen] = useState(false);
- const [accounts, setAccounts] = useState(initialAccounts);
+ const [accounts, setAccounts] = useState(() =>
+ startWithoutOrganization
+ ? initialAccounts.map(a => (a.session.sessionId === colin.sessionId ? { ...a, activeOrganizationId: null } : a))
+ : initialAccounts,
+ );
  const [activeSessionId, setActiveSessionId] = useState(colin.sessionId);
  const [pendingKey, setPendingKey] = useState<string | null>(null);
 
@@ -196,6 +206,7 @@ function usePrototype(): Omit<UserButtonProps, 'mode'> {
  suggestions: account.suggestions,
  invitations: account.invitations,
  additionalSessions: accounts.filter(a => a.session.sessionId !== activeSessionId).map(a => a.session),
+ hidePersonal,
  // Selecting an organization only ever acts on the active account, and is the one action that
  // closes the surface behind it.
  onSelectOrganization: organizationId =>
@@ -300,6 +311,19 @@ export function User(_args: Record<string, unknown>) {
  );
 }
 
+export function NoOrganizationSelected(_args: Record<string, unknown>) {
+ const prototype = usePrototype({ hidePersonal: true, startWithoutOrganization: true });
+
+ // Personal is withheld and nothing is active, so the lead is no selection — not the account.
+ // Picking an organization leaves it.
+ return (
+ <UserButtonView
+ {...prototype}
+ mode='combined'
+ />
+ );
+}
+
 export function SingleSession(_args: Record<string, unknown>) {
  const prototype = usePrototype();
 

packages/ui/src/hooks/useOrganizationListInView.ts

@@ -5,14 +5,18 @@ import { useInView } from './useInView';
 
 /**
  * @internal
+ *
+ * `enabled` withholds the list params so the three requests do not start. Defaults on.
  */
-export const useOrganizationListInView = () => {
- const { userMemberships, userInvitations, userSuggestions } = useOrganizationList(organizationListParams);
+export const useOrganizationListInView = ({ enabled = true }: { enabled?: boolean } = {}) => {
+ const { userMemberships, userInvitations, userSuggestions } = useOrganizationList(
+ enabled ? organizationListParams : undefined,
+ );
 
  const { ref } = useInView({
  threshold: 0,
  onChange: inView => {
- if (!inView) {
+ if (!enabled || !inView) {
  return;
  }
  if (userMemberships.hasNextPage) {

packages/ui/src/mosaic/components/button/submit-button.test.tsx

@@ -317,19 +317,29 @@ describe('Mosaic SubmitButton spin delay', () => {
  expect(atoms(spinner()).length).toBeLessThan(hidden.length);
  });
 
- // A consumer who already knows the action is slow has nothing to gain by waiting.
+ // A consumer who already knows the action is slow has nothing to gain by waiting: there is no
+ // delay left to outlast, so the spinner shows in the render that starts the action rather than a
+ // timer's.
  it('lets the consumer opt out of the delay', () => {
- render(
+const { rerender } = render(
  <SubmitButton
  isPending
- spinDelay={{ delay: 0 }}
+ spinDelay={{ delay: 1000 }}
  >
  Save
  </SubmitButton>,
  );
  const hidden = atoms(spinner());
 
- advance(0);
+ rerender(
+ <SubmitButton
+ isPending
+ spinDelay={{ delay: 0 }}
+ >
+ Save
+ </SubmitButton>,
+ );
+
  expect(atoms(spinner()).length).toBeLessThan(hidden.length);
  });
 

packages/ui/src/mosaic/hooks/__tests__/useSpinDelay.test.ts

@@ -76,6 +76,27 @@ describe('useSpinDelay', () => {
  expect(result.current).toBeNull();
  });
 
+ // Direct feedback on a click has nothing to debounce, so a zero delay must not cost a timer's
+ // worth of render passes before the spinner appears.
+ it('surfaces the value in the same pass when there is no delay to wait out', async () => {
+ const { result, rerender } = render(null, { delay: 0, minDuration: 200 });
+ await act(() => rerender({ value: 'a' }));
+
+ expect(result.current).toBe('a');
+ });
+
+ it('still holds a zero-delay value for minDuration', async () => {
+ const { result, rerender } = render(null, { delay: 0, minDuration: 200 });
+ await act(() => rerender({ value: 'a' }));
+ await act(() => rerender({ value: null }));
+
+ await advance(199);
+ expect(result.current).toBe('a');
+
+ await advance(1);
+ expect(result.current).toBeNull();
+ });
+
  it('swaps to a new value immediately when one replaces another mid-show', async () => {
  const { result, rerender } = render(null, { delay: 500, minDuration: 200 });
  await act(() => rerender({ value: 'a' }));

packages/ui/src/mosaic/hooks/useSpinDelay.ts

@@ -1,7 +1,7 @@
 import { useEffect, useRef, useState } from 'react';
 
 export interface SpinDelayOptions {
- /** Wait this long before showing the value, so quick actions never flash a spinner. */
+ /** Wait this long before showing the value, so quick actions never flash a spinner. `0` shows it straight away. */
  delay?: number;
  /** Once shown, keep the value up at least this long, so the spinner never flickers off. */
  minDuration?: number;
@@ -25,11 +25,17 @@ export function useSpinDelay<T>(value: T | null, options: SpinDelayOptions = {})
  const shownAt = useRef(0);
 
  useEffect(() => {
- // Nothing showing yet: arm a timer so the value only surfaces if it outlasts `delay`.
+ // Nothing showing yet: arm a timer so the value only surfaces if it outlasts `delay`. With no
+ // delay there is nothing to outlast, so it surfaces in this pass rather than a timer's.
  if (shown === null) {
  if (value === null) {
  return;
  }
+ if (delay <= 0) {
+ shownAt.current = Date.now();
+ setShown(value);
+ return;
+ }
  const timer = setTimeout(() => {
  shownAt.current = Date.now();
  setShown(value);

.changeset/mosaic-user-button-controller.md

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

.changeset/mosaic-user-button-integration.md

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

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

@@ -7,13 +7,16 @@ import { useClerk } from './useClerk';
  *
  * @internal
  */
-export function useAttemptToEnableOrganizations(caller: 'useOrganization' | 'useOrganizationList') {
+export function useAttemptToEnableOrganizations(
+ caller: 'useOrganization' | 'useOrganizationList',
+ { enabled = true }: { enabled?: boolean } = {},
+) {
  const clerk = useClerk();
  const hasAttempted = useRef(false);
 
  useEffect(() => {
  // Guard to not run this effect twice on Clerk resource update
- if (hasAttempted.current) {
+ if (!enabled || hasAttempted.current) {
  return;
  }
 
@@ -23,5 +26,5 @@ export function useAttemptToEnableOrganizations(caller: 'useOrganization' | 'use
  for: 'organizations',
  caller,
  });
- }, [clerk, caller]);
+ }, [clerk, caller, enabled]);
 }

packages/shared/src/react/hooks/useOrganization.tsx

@@ -61,6 +61,12 @@ export type UseOrganizationParams = {
  * </ul>
  */
  invitations?: true | PaginatedHookConfig<GetInvitationsParams>;
+ /**
+ * Skip the development prompt that offers to enable Organizations.
+ *
+ * @internal
+ */
+ __internal_skipAttemptToEnableOrganizations?: boolean;
 };
 
 /**
@@ -275,10 +281,13 @@ export function useOrganization<T extends UseOrganizationParams>(params?: T): Us
  membershipRequests: membershipRequestsListParams,
  memberships: membersListParams,
  invitations: invitationsListParams,
+ __internal_skipAttemptToEnableOrganizations,
  } = params || {};
 
  useAssertWrappedByClerkProvider('useOrganization');
- useAttemptToEnableOrganizations('useOrganization');
+ useAttemptToEnableOrganizations('useOrganization', {
+ enabled: !__internal_skipAttemptToEnableOrganizations,
+ });
 
  const organization = useOrganizationBase();
  const session = useSessionBase();

packages/shared/src/react/hooks/useOrganizationList.tsx

@@ -253,7 +253,10 @@ export function useOrganizationList<T extends UseOrganizationListParams>(params?
  const { userMemberships, userInvitations, userSuggestions } = params || {};
 
  useAssertWrappedByClerkProvider('useOrganizationList');
- useAttemptToEnableOrganizations('useOrganizationList');
+ // No list keys means this call is not using Organizations; the prompt is for the lists.
+ useAttemptToEnableOrganizations('useOrganizationList', {
+ enabled: userMemberships !== undefined || userInvitations !== undefined || userSuggestions !== undefined,
+ });
 
  const userMembershipsSafeValues = useWithSafeValues(userMemberships, {
  initialPage: 1,

packages/swingset/src/stories/user-button.mdx

@@ -74,7 +74,7 @@ Exports are flat (not `UserButton.Trigger`) so each part declares its own `'use
 ## Trigger
 
 The active workspace's avatar and what it is called: the org and its plan wherever one heads the
-trigger, the account otherwise.
+trigger, no selection when personal is hidden and none is active, the account otherwise.
 
 `renderTriggerLabel={false}` leaves the avatar alone.
 
@@ -164,6 +164,18 @@ accounts" ever meant here.
  storyModule={UserButtonStories}
 />
 
+## No organization selected
+
+`hidePersonal` withholds the personal workspace — the instance does this when it forces an
+organization, or the app does it itself. With no org active either, the lead is not the account:
+trigger and header say **No organization selected**, the mark is square, and the gear is **Manage
+account**.
+
+<Story
+ name='NoOrganizationSelected'
+ storyModule={UserButtonStories}
+/>
+
 ## Menu items
 
 `customMenuItems` adds the app's own rows to the foot of the popup, ahead of Clerk's own. A row with

packages/swingset/src/stories/user-button.stories.tsx

@@ -143,9 +143,19 @@ const LATENCY_MS = 800;
  * The actions that would navigate somewhere in a real app (Manage, Invite, Create organization, Add
  * account) have nowhere to go here, so they only close the popover.
  */
-function usePrototype(): Omit<UserButtonProps, 'mode'> {
+function usePrototype({
+ hidePersonal = false,
+ startWithoutOrganization = false,
+}: {
+ hidePersonal?: boolean;
+ startWithoutOrganization?: boolean;
+} = {}): Omit<UserButtonProps, 'mode'> {
  const [open, setOpen] = useState(false);
- const [accounts, setAccounts] = useState(initialAccounts);
+ const [accounts, setAccounts] = useState(() =>
+ startWithoutOrganization
+ ? initialAccounts.map(a => (a.session.sessionId === colin.sessionId ? { ...a, activeOrganizationId: null } : a))
+ : initialAccounts,
+ );
  const [activeSessionId, setActiveSessionId] = useState(colin.sessionId);
  const [pendingKey, setPendingKey] = useState<string | null>(null);
 
@@ -196,6 +206,7 @@ function usePrototype(): Omit<UserButtonProps, 'mode'> {
  suggestions: account.suggestions,
  invitations: account.invitations,
  additionalSessions: accounts.filter(a => a.session.sessionId !== activeSessionId).map(a => a.session),
+ hidePersonal,
  // Selecting an organization only ever acts on the active account, and is the one action that
  // closes the surface behind it.
  onSelectOrganization: organizationId =>
@@ -300,6 +311,19 @@ export function User(_args: Record<string, unknown>) {
  );
 }
 
+export function NoOrganizationSelected(_args: Record<string, unknown>) {
+ const prototype = usePrototype({ hidePersonal: true, startWithoutOrganization: true });
+
+ // Personal is withheld and nothing is active, so the lead is no selection — not the account.
+ // Picking an organization leaves it.
+ return (
+ <UserButtonView
+ {...prototype}
+ mode='combined'
+ />
+ );
+}
+
 export function SingleSession(_args: Record<string, unknown>) {
  const prototype = usePrototype();
 

packages/ui/src/hooks/useOrganizationListInView.ts

@@ -5,14 +5,18 @@ import { useInView } from './useInView';
 
 /**
  * @internal
+ *
+ * `enabled` withholds the list params so the three requests do not start. Defaults on.
  */
-export const useOrganizationListInView = () => {
- const { userMemberships, userInvitations, userSuggestions } = useOrganizationList(organizationListParams);
+export const useOrganizationListInView = ({ enabled = true }: { enabled?: boolean } = {}) => {
+ const { userMemberships, userInvitations, userSuggestions } = useOrganizationList(
+ enabled ? organizationListParams : undefined,
+ );
 
  const { ref } = useInView({
  threshold: 0,
  onChange: inView => {
- if (!inView) {
+ if (!enabled || !inView) {
  return;
  }
  if (userMemberships.hasNextPage) {

packages/ui/src/mosaic/components/button/submit-button.test.tsx

@@ -317,19 +317,29 @@ describe('Mosaic SubmitButton spin delay', () => {
  expect(atoms(spinner()).length).toBeLessThan(hidden.length);
  });
 
- // A consumer who already knows the action is slow has nothing to gain by waiting.
+ // A consumer who already knows the action is slow has nothing to gain by waiting: there is no
+ // delay left to outlast, so the spinner shows in the render that starts the action rather than a
+ // timer's.
  it('lets the consumer opt out of the delay', () => {
- render(
+const { rerender } = render(
  <SubmitButton
  isPending
- spinDelay={{ delay: 0 }}
+ spinDelay={{ delay: 1000 }}
  >
  Save
  </SubmitButton>,
  );
  const hidden = atoms(spinner());
 
- advance(0);
+ rerender(
+ <SubmitButton
+ isPending
+ spinDelay={{ delay: 0 }}
+ >
+ Save
+ </SubmitButton>,
+ );
+
  expect(atoms(spinner()).length).toBeLessThan(hidden.length);
  });
 

packages/ui/src/mosaic/hooks/__tests__/useSpinDelay.test.ts

@@ -76,6 +76,27 @@ describe('useSpinDelay', () => {
  expect(result.current).toBeNull();
  });
 
+ // Direct feedback on a click has nothing to debounce, so a zero delay must not cost a timer's
+ // worth of render passes before the spinner appears.
+ it('surfaces the value in the same pass when there is no delay to wait out', async () => {
+ const { result, rerender } = render(null, { delay: 0, minDuration: 200 });
+ await act(() => rerender({ value: 'a' }));
+
+ expect(result.current).toBe('a');
+ });
+
+ it('still holds a zero-delay value for minDuration', async () => {
+ const { result, rerender } = render(null, { delay: 0, minDuration: 200 });
+ await act(() => rerender({ value: 'a' }));
+ await act(() => rerender({ value: null }));
+
+ await advance(199);
+ expect(result.current).toBe('a');
+
+ await advance(1);
+ expect(result.current).toBeNull();
+ });
+
  it('swaps to a new value immediately when one replaces another mid-show', async () => {
  const { result, rerender } = render(null, { delay: 500, minDuration: 200 });
  await act(() => rerender({ value: 'a' }));

packages/ui/src/mosaic/hooks/useSpinDelay.ts

@@ -1,7 +1,7 @@
 import { useEffect, useRef, useState } from 'react';
 
 export interface SpinDelayOptions {
- /** Wait this long before showing the value, so quick actions never flash a spinner. */
+ /** Wait this long before showing the value, so quick actions never flash a spinner. `0` shows it straight away. */
  delay?: number;
  /** Once shown, keep the value up at least this long, so the spinner never flickers off. */
  minDuration?: number;
@@ -25,11 +25,17 @@ export function useSpinDelay<T>(value: T | null, options: SpinDelayOptions = {})
  const shownAt = useRef(0);
 
  useEffect(() => {
- // Nothing showing yet: arm a timer so the value only surfaces if it outlasts `delay`.
+ // Nothing showing yet: arm a timer so the value only surfaces if it outlasts `delay`. With no
+ // delay there is nothing to outlast, so it surfaces in this pass rather than a timer's.
  if (shown === null) {
  if (value === null) {
  return;
  }
+ if (delay <= 0) {
+ shownAt.current = Date.now();
+ setShown(value);
+ return;
+ }
  const timer = setTimeout(() => {
  shownAt.current = Date.now();
  setShown(value);

.changeset/mosaic-user-button-controller.md

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

.changeset/mosaic-user-button-integration.md

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

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

@@ -7,13 +7,16 @@ import { useClerk } from './useClerk';
  *
  * @internal
  */
-export function useAttemptToEnableOrganizations(caller: 'useOrganization' | 'useOrganizationList') {
+export function useAttemptToEnableOrganizations(
+ caller: 'useOrganization' | 'useOrganizationList',
+ { enabled = true }: { enabled?: boolean } = {},
+) {
  const clerk = useClerk();
  const hasAttempted = useRef(false);
 
  useEffect(() => {
  // Guard to not run this effect twice on Clerk resource update
- if (hasAttempted.current) {
+ if (!enabled || hasAttempted.current) {
  return;
  }
 
@@ -23,5 +26,5 @@ export function useAttemptToEnableOrganizations(caller: 'useOrganization' | 'use
  for: 'organizations',
  caller,
  });
- }, [clerk, caller]);
+ }, [clerk, caller, enabled]);
 }

packages/shared/src/react/hooks/useOrganization.tsx

@@ -61,6 +61,12 @@ export type UseOrganizationParams = {
  * </ul>
  */
  invitations?: true | PaginatedHookConfig<GetInvitationsParams>;
+ /**
+ * Skip the development prompt that offers to enable Organizations.
+ *
+ * @internal
+ */
+ __internal_skipAttemptToEnableOrganizations?: boolean;
 };
 
 /**
@@ -275,10 +281,13 @@ export function useOrganization<T extends UseOrganizationParams>(params?: T): Us
  membershipRequests: membershipRequestsListParams,
  memberships: membersListParams,
  invitations: invitationsListParams,
+ __internal_skipAttemptToEnableOrganizations,
  } = params || {};
 
  useAssertWrappedByClerkProvider('useOrganization');
- useAttemptToEnableOrganizations('useOrganization');
+ useAttemptToEnableOrganizations('useOrganization', {
+ enabled: !__internal_skipAttemptToEnableOrganizations,
+ });
 
  const organization = useOrganizationBase();
  const session = useSessionBase();

packages/shared/src/react/hooks/useOrganizationList.tsx

@@ -253,7 +253,10 @@ export function useOrganizationList<T extends UseOrganizationListParams>(params?
  const { userMemberships, userInvitations, userSuggestions } = params || {};
 
  useAssertWrappedByClerkProvider('useOrganizationList');
- useAttemptToEnableOrganizations('useOrganizationList');
+ // No list keys means this call is not using Organizations; the prompt is for the lists.
+ useAttemptToEnableOrganizations('useOrganizationList', {
+ enabled: userMemberships !== undefined || userInvitations !== undefined || userSuggestions !== undefined,
+ });
 
  const userMembershipsSafeValues = useWithSafeValues(userMemberships, {
  initialPage: 1,

packages/swingset/src/stories/user-button.mdx

@@ -74,7 +74,7 @@ Exports are flat (not `UserButton.Trigger`) so each part declares its own `'use
 ## Trigger
 
 The active workspace's avatar and what it is called: the org and its plan wherever one heads the
-trigger, the account otherwise.
+trigger, no selection when personal is hidden and none is active, the account otherwise.
 
 `renderTriggerLabel={false}` leaves the avatar alone.
 
@@ -164,6 +164,18 @@ accounts" ever meant here.
  storyModule={UserButtonStories}
 />
 
+## No organization selected
+
+`hidePersonal` withholds the personal workspace — the instance does this when it forces an
+organization, or the app does it itself. With no org active either, the lead is not the account:
+trigger and header say **No organization selected**, the mark is square, and the gear is **Manage
+account**.
+
+<Story
+ name='NoOrganizationSelected'
+ storyModule={UserButtonStories}
+/>
+
 ## Menu items
 
 `customMenuItems` adds the app's own rows to the foot of the popup, ahead of Clerk's own. A row with

packages/swingset/src/stories/user-button.stories.tsx

@@ -143,9 +143,19 @@ const LATENCY_MS = 800;
  * The actions that would navigate somewhere in a real app (Manage, Invite, Create organization, Add
  * account) have nowhere to go here, so they only close the popover.
  */
-function usePrototype(): Omit<UserButtonProps, 'mode'> {
+function usePrototype({
+ hidePersonal = false,
+ startWithoutOrganization = false,
+}: {
+ hidePersonal?: boolean;
+ startWithoutOrganization?: boolean;
+} = {}): Omit<UserButtonProps, 'mode'> {
  const [open, setOpen] = useState(false);
- const [accounts, setAccounts] = useState(initialAccounts);
+ const [accounts, setAccounts] = useState(() =>
+ startWithoutOrganization
+ ? initialAccounts.map(a => (a.session.sessionId === colin.sessionId ? { ...a, activeOrganizationId: null } : a))
+ : initialAccounts,
+ );
  const [activeSessionId, setActiveSessionId] = useState(colin.sessionId);
  const [pendingKey, setPendingKey] = useState<string | null>(null);
 
@@ -196,6 +206,7 @@ function usePrototype(): Omit<UserButtonProps, 'mode'> {
  suggestions: account.suggestions,
  invitations: account.invitations,
  additionalSessions: accounts.filter(a => a.session.sessionId !== activeSessionId).map(a => a.session),
+ hidePersonal,
  // Selecting an organization only ever acts on the active account, and is the one action that
  // closes the surface behind it.
  onSelectOrganization: organizationId =>
@@ -300,6 +311,19 @@ export function User(_args: Record<string, unknown>) {
  );
 }
 
+export function NoOrganizationSelected(_args: Record<string, unknown>) {
+ const prototype = usePrototype({ hidePersonal: true, startWithoutOrganization: true });
+
+ // Personal is withheld and nothing is active, so the lead is no selection — not the account.
+ // Picking an organization leaves it.
+ return (
+ <UserButtonView
+ {...prototype}
+ mode='combined'
+ />
+ );
+}
+
 export function SingleSession(_args: Record<string, unknown>) {
  const prototype = usePrototype();
 

packages/ui/src/hooks/useOrganizationListInView.ts

@@ -5,14 +5,18 @@ import { useInView } from './useInView';
 
 /**
  * @internal
+ *
+ * `enabled` withholds the list params so the three requests do not start. Defaults on.
  */
-export const useOrganizationListInView = () => {
- const { userMemberships, userInvitations, userSuggestions } = useOrganizationList(organizationListParams);
+export const useOrganizationListInView = ({ enabled = true }: { enabled?: boolean } = {}) => {
+ const { userMemberships, userInvitations, userSuggestions } = useOrganizationList(
+ enabled ? organizationListParams : undefined,
+ );
 
  const { ref } = useInView({
  threshold: 0,
  onChange: inView => {
- if (!inView) {
+ if (!enabled || !inView) {
  return;
  }
  if (userMemberships.hasNextPage) {

packages/ui/src/mosaic/components/button/submit-button.test.tsx

@@ -317,19 +317,29 @@ describe('Mosaic SubmitButton spin delay', () => {
  expect(atoms(spinner()).length).toBeLessThan(hidden.length);
  });
 
- // A consumer who already knows the action is slow has nothing to gain by waiting.
+ // A consumer who already knows the action is slow has nothing to gain by waiting: there is no
+ // delay left to outlast, so the spinner shows in the render that starts the action rather than a
+ // timer's.
  it('lets the consumer opt out of the delay', () => {
- render(
+const { rerender } = render(
  <SubmitButton
  isPending
- spinDelay={{ delay: 0 }}
+ spinDelay={{ delay: 1000 }}
  >
  Save
  </SubmitButton>,
  );
  const hidden = atoms(spinner());
 
- advance(0);
+ rerender(
+ <SubmitButton
+ isPending
+ spinDelay={{ delay: 0 }}
+ >
+ Save
+ </SubmitButton>,
+ );
+
  expect(atoms(spinner()).length).toBeLessThan(hidden.length);
  });
 

packages/ui/src/mosaic/hooks/__tests__/useSpinDelay.test.ts

@@ -76,6 +76,27 @@ describe('useSpinDelay', () => {
  expect(result.current).toBeNull();
  });
 
+ // Direct feedback on a click has nothing to debounce, so a zero delay must not cost a timer's
+ // worth of render passes before the spinner appears.
+ it('surfaces the value in the same pass when there is no delay to wait out', async () => {
+ const { result, rerender } = render(null, { delay: 0, minDuration: 200 });
+ await act(() => rerender({ value: 'a' }));
+
+ expect(result.current).toBe('a');
+ });
+
+ it('still holds a zero-delay value for minDuration', async () => {
+ const { result, rerender } = render(null, { delay: 0, minDuration: 200 });
+ await act(() => rerender({ value: 'a' }));
+ await act(() => rerender({ value: null }));
+
+ await advance(199);
+ expect(result.current).toBe('a');
+
+ await advance(1);
+ expect(result.current).toBeNull();
+ });
+
  it('swaps to a new value immediately when one replaces another mid-show', async () => {
  const { result, rerender } = render(null, { delay: 500, minDuration: 200 });
  await act(() => rerender({ value: 'a' }));

packages/ui/src/mosaic/hooks/useSpinDelay.ts

@@ -1,7 +1,7 @@
 import { useEffect, useRef, useState } from 'react';
 
 export interface SpinDelayOptions {
- /** Wait this long before showing the value, so quick actions never flash a spinner. */
+ /** Wait this long before showing the value, so quick actions never flash a spinner. `0` shows it straight away. */
  delay?: number;
  /** Once shown, keep the value up at least this long, so the spinner never flickers off. */
  minDuration?: number;
@@ -25,11 +25,17 @@ export function useSpinDelay<T>(value: T | null, options: SpinDelayOptions = {})
  const shownAt = useRef(0);
 
  useEffect(() => {
- // Nothing showing yet: arm a timer so the value only surfaces if it outlasts `delay`.
+ // Nothing showing yet: arm a timer so the value only surfaces if it outlasts `delay`. With no
+ // delay there is nothing to outlast, so it surfaces in this pass rather than a timer's.
  if (shown === null) {
  if (value === null) {
  return;
  }
+ if (delay <= 0) {
+ shownAt.current = Date.now();
+ setShown(value);
+ return;
+ }
  const timer = setTimeout(() => {
  shownAt.current = Date.now();
  setShown(value);

.changeset/mosaic-user-button-controller.md

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

.changeset/mosaic-user-button-integration.md

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

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

@@ -7,13 +7,16 @@ import { useClerk } from './useClerk';
  *
  * @internal
  */
-export function useAttemptToEnableOrganizations(caller: 'useOrganization' | 'useOrganizationList') {
+export function useAttemptToEnableOrganizations(
+ caller: 'useOrganization' | 'useOrganizationList',
+ { enabled = true }: { enabled?: boolean } = {},
+) {
  const clerk = useClerk();
  const hasAttempted = useRef(false);
 
  useEffect(() => {
  // Guard to not run this effect twice on Clerk resource update
- if (hasAttempted.current) {
+ if (!enabled || hasAttempted.current) {
  return;
  }
 
@@ -23,5 +26,5 @@ export function useAttemptToEnableOrganizations(caller: 'useOrganization' | 'use
  for: 'organizations',
  caller,
  });
- }, [clerk, caller]);
+ }, [clerk, caller, enabled]);
 }

packages/shared/src/react/hooks/useOrganization.tsx

@@ -61,6 +61,12 @@ export type UseOrganizationParams = {
  * </ul>
  */
  invitations?: true | PaginatedHookConfig<GetInvitationsParams>;
+ /**
+ * Skip the development prompt that offers to enable Organizations.
+ *
+ * @internal
+ */
+ __internal_skipAttemptToEnableOrganizations?: boolean;
 };
 
 /**
@@ -275,10 +281,13 @@ export function useOrganization<T extends UseOrganizationParams>(params?: T): Us
  membershipRequests: membershipRequestsListParams,
  memberships: membersListParams,
  invitations: invitationsListParams,
+ __internal_skipAttemptToEnableOrganizations,
  } = params || {};
 
  useAssertWrappedByClerkProvider('useOrganization');
- useAttemptToEnableOrganizations('useOrganization');
+ useAttemptToEnableOrganizations('useOrganization', {
+ enabled: !__internal_skipAttemptToEnableOrganizations,
+ });
 
  const organization = useOrganizationBase();
  const session = useSessionBase();

packages/shared/src/react/hooks/useOrganizationList.tsx

@@ -253,7 +253,10 @@ export function useOrganizationList<T extends UseOrganizationListParams>(params?
  const { userMemberships, userInvitations, userSuggestions } = params || {};
 
  useAssertWrappedByClerkProvider('useOrganizationList');
- useAttemptToEnableOrganizations('useOrganizationList');
+ // No list keys means this call is not using Organizations; the prompt is for the lists.
+ useAttemptToEnableOrganizations('useOrganizationList', {
+ enabled: userMemberships !== undefined || userInvitations !== undefined || userSuggestions !== undefined,
+ });
 
  const userMembershipsSafeValues = useWithSafeValues(userMemberships, {
  initialPage: 1,

packages/swingset/src/stories/user-button.mdx

@@ -74,7 +74,7 @@ Exports are flat (not `UserButton.Trigger`) so each part declares its own `'use
 ## Trigger
 
 The active workspace's avatar and what it is called: the org and its plan wherever one heads the
-trigger, the account otherwise.
+trigger, no selection when personal is hidden and none is active, the account otherwise.
 
 `renderTriggerLabel={false}` leaves the avatar alone.
 
@@ -164,6 +164,18 @@ accounts" ever meant here.
  storyModule={UserButtonStories}
 />
 
+## No organization selected
+
+`hidePersonal` withholds the personal workspace — the instance does this when it forces an
+organization, or the app does it itself. With no org active either, the lead is not the account:
+trigger and header say **No organization selected**, the mark is square, and the gear is **Manage
+account**.
+
+<Story
+ name='NoOrganizationSelected'
+ storyModule={UserButtonStories}
+/>
+
 ## Menu items
 
 `customMenuItems` adds the app's own rows to the foot of the popup, ahead of Clerk's own. A row with

packages/swingset/src/stories/user-button.stories.tsx

@@ -143,9 +143,19 @@ const LATENCY_MS = 800;
  * The actions that would navigate somewhere in a real app (Manage, Invite, Create organization, Add
  * account) have nowhere to go here, so they only close the popover.
  */
-function usePrototype(): Omit<UserButtonProps, 'mode'> {
+function usePrototype({
+ hidePersonal = false,
+ startWithoutOrganization = false,
+}: {
+ hidePersonal?: boolean;
+ startWithoutOrganization?: boolean;
+} = {}): Omit<UserButtonProps, 'mode'> {
  const [open, setOpen] = useState(false);
- const [accounts, setAccounts] = useState(initialAccounts);
+ const [accounts, setAccounts] = useState(() =>
+ startWithoutOrganization
+ ? initialAccounts.map(a => (a.session.sessionId === colin.sessionId ? { ...a, activeOrganizationId: null } : a))
+ : initialAccounts,
+ );
  const [activeSessionId, setActiveSessionId] = useState(colin.sessionId);
  const [pendingKey, setPendingKey] = useState<string | null>(null);
 
@@ -196,6 +206,7 @@ function usePrototype(): Omit<UserButtonProps, 'mode'> {
  suggestions: account.suggestions,
  invitations: account.invitations,
  additionalSessions: accounts.filter(a => a.session.sessionId !== activeSessionId).map(a => a.session),
+ hidePersonal,
  // Selecting an organization only ever acts on the active account, and is the one action that
  // closes the surface behind it.
  onSelectOrganization: organizationId =>
@@ -300,6 +311,19 @@ export function User(_args: Record<string, unknown>) {
  );
 }
 
+export function NoOrganizationSelected(_args: Record<string, unknown>) {
+ const prototype = usePrototype({ hidePersonal: true, startWithoutOrganization: true });
+
+ // Personal is withheld and nothing is active, so the lead is no selection — not the account.
+ // Picking an organization leaves it.
+ return (
+ <UserButtonView
+ {...prototype}
+ mode='combined'
+ />
+ );
+}
+
 export function SingleSession(_args: Record<string, unknown>) {
  const prototype = usePrototype();
 

packages/ui/src/hooks/useOrganizationListInView.ts

@@ -5,14 +5,18 @@ import { useInView } from './useInView';
 
 /**
  * @internal
+ *
+ * `enabled` withholds the list params so the three requests do not start. Defaults on.
  */
-export const useOrganizationListInView = () => {
- const { userMemberships, userInvitations, userSuggestions } = useOrganizationList(organizationListParams);
+export const useOrganizationListInView = ({ enabled = true }: { enabled?: boolean } = {}) => {
+ const { userMemberships, userInvitations, userSuggestions } = useOrganizationList(
+ enabled ? organizationListParams : undefined,
+ );
 
  const { ref } = useInView({
  threshold: 0,
  onChange: inView => {
- if (!inView) {
+ if (!enabled || !inView) {
  return;
  }
  if (userMemberships.hasNextPage) {

packages/ui/src/mosaic/components/button/submit-button.test.tsx

@@ -317,19 +317,29 @@ describe('Mosaic SubmitButton spin delay', () => {
  expect(atoms(spinner()).length).toBeLessThan(hidden.length);
  });
 
- // A consumer who already knows the action is slow has nothing to gain by waiting.
+ // A consumer who already knows the action is slow has nothing to gain by waiting: there is no
+ // delay left to outlast, so the spinner shows in the render that starts the action rather than a
+ // timer's.
  it('lets the consumer opt out of the delay', () => {
- render(
+const { rerender } = render(
  <SubmitButton
  isPending
- spinDelay={{ delay: 0 }}
+ spinDelay={{ delay: 1000 }}
  >
  Save
  </SubmitButton>,
  );
  const hidden = atoms(spinner());
 
- advance(0);
+ rerender(
+ <SubmitButton
+ isPending
+ spinDelay={{ delay: 0 }}
+ >
+ Save
+ </SubmitButton>,
+ );
+
  expect(atoms(spinner()).length).toBeLessThan(hidden.length);
  });
 

packages/ui/src/mosaic/hooks/__tests__/useSpinDelay.test.ts

@@ -76,6 +76,27 @@ describe('useSpinDelay', () => {
  expect(result.current).toBeNull();
  });
 
+ // Direct feedback on a click has nothing to debounce, so a zero delay must not cost a timer's
+ // worth of render passes before the spinner appears.
+ it('surfaces the value in the same pass when there is no delay to wait out', async () => {
+ const { result, rerender } = render(null, { delay: 0, minDuration: 200 });
+ await act(() => rerender({ value: 'a' }));
+
+ expect(result.current).toBe('a');
+ });
+
+ it('still holds a zero-delay value for minDuration', async () => {
+ const { result, rerender } = render(null, { delay: 0, minDuration: 200 });
+ await act(() => rerender({ value: 'a' }));
+ await act(() => rerender({ value: null }));
+
+ await advance(199);
+ expect(result.current).toBe('a');
+
+ await advance(1);
+ expect(result.current).toBeNull();
+ });
+
  it('swaps to a new value immediately when one replaces another mid-show', async () => {
  const { result, rerender } = render(null, { delay: 500, minDuration: 200 });
  await act(() => rerender({ value: 'a' }));

packages/ui/src/mosaic/hooks/useSpinDelay.ts

@@ -1,7 +1,7 @@
 import { useEffect, useRef, useState } from 'react';
 
 export interface SpinDelayOptions {
- /** Wait this long before showing the value, so quick actions never flash a spinner. */
+ /** Wait this long before showing the value, so quick actions never flash a spinner. `0` shows it straight away. */
  delay?: number;
  /** Once shown, keep the value up at least this long, so the spinner never flickers off. */
  minDuration?: number;
@@ -25,11 +25,17 @@ export function useSpinDelay<T>(value: T | null, options: SpinDelayOptions = {})
  const shownAt = useRef(0);
 
  useEffect(() => {
- // Nothing showing yet: arm a timer so the value only surfaces if it outlasts `delay`.
+ // Nothing showing yet: arm a timer so the value only surfaces if it outlasts `delay`. With no
+ // delay there is nothing to outlast, so it surfaces in this pass rather than a timer's.
  if (shown === null) {
  if (value === null) {
  return;
  }
+ if (delay <= 0) {
+ shownAt.current = Date.now();
+ setShown(value);
+ return;
+ }
  const timer = setTimeout(() => {
  shownAt.current = Date.now();
  setShown(value);

.changeset/mosaic-user-button-controller.md

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

.changeset/mosaic-user-button-integration.md

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

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

@@ -7,13 +7,16 @@ import { useClerk } from './useClerk';
  *
  * @internal
  */
-export function useAttemptToEnableOrganizations(caller: 'useOrganization' | 'useOrganizationList') {
+export function useAttemptToEnableOrganizations(
+ caller: 'useOrganization' | 'useOrganizationList',
+ { enabled = true }: { enabled?: boolean } = {},
+) {
  const clerk = useClerk();
  const hasAttempted = useRef(false);
 
  useEffect(() => {
  // Guard to not run this effect twice on Clerk resource update
- if (hasAttempted.current) {
+ if (!enabled || hasAttempted.current) {
  return;
  }
 
@@ -23,5 +26,5 @@ export function useAttemptToEnableOrganizations(caller: 'useOrganization' | 'use
  for: 'organizations',
  caller,
  });
- }, [clerk, caller]);
+ }, [clerk, caller, enabled]);
 }

packages/shared/src/react/hooks/useOrganization.tsx

@@ -61,6 +61,12 @@ export type UseOrganizationParams = {
  * </ul>
  */
  invitations?: true | PaginatedHookConfig<GetInvitationsParams>;
+ /**
+ * Skip the development prompt that offers to enable Organizations.
+ *
+ * @internal
+ */
+ __internal_skipAttemptToEnableOrganizations?: boolean;
 };
 
 /**
@@ -275,10 +281,13 @@ export function useOrganization<T extends UseOrganizationParams>(params?: T): Us
  membershipRequests: membershipRequestsListParams,
  memberships: membersListParams,
  invitations: invitationsListParams,
+ __internal_skipAttemptToEnableOrganizations,
  } = params || {};
 
  useAssertWrappedByClerkProvider('useOrganization');
- useAttemptToEnableOrganizations('useOrganization');
+ useAttemptToEnableOrganizations('useOrganization', {
+ enabled: !__internal_skipAttemptToEnableOrganizations,
+ });
 
  const organization = useOrganizationBase();
  const session = useSessionBase();

packages/shared/src/react/hooks/useOrganizationList.tsx

@@ -253,7 +253,10 @@ export function useOrganizationList<T extends UseOrganizationListParams>(params?
  const { userMemberships, userInvitations, userSuggestions } = params || {};
 
  useAssertWrappedByClerkProvider('useOrganizationList');
- useAttemptToEnableOrganizations('useOrganizationList');
+ // No list keys means this call is not using Organizations; the prompt is for the lists.
+ useAttemptToEnableOrganizations('useOrganizationList', {
+ enabled: userMemberships !== undefined || userInvitations !== undefined || userSuggestions !== undefined,
+ });
 
  const userMembershipsSafeValues = useWithSafeValues(userMemberships, {
  initialPage: 1,

packages/swingset/src/stories/user-button.mdx

@@ -74,7 +74,7 @@ Exports are flat (not `UserButton.Trigger`) so each part declares its own `'use
 ## Trigger
 
 The active workspace's avatar and what it is called: the org and its plan wherever one heads the
-trigger, the account otherwise.
+trigger, no selection when personal is hidden and none is active, the account otherwise.
 
 `renderTriggerLabel={false}` leaves the avatar alone.
 
@@ -164,6 +164,18 @@ accounts" ever meant here.
  storyModule={UserButtonStories}
 />
 
+## No organization selected
+
+`hidePersonal` withholds the personal workspace — the instance does this when it forces an
+organization, or the app does it itself. With no org active either, the lead is not the account:
+trigger and header say **No organization selected**, the mark is square, and the gear is **Manage
+account**.
+
+<Story
+ name='NoOrganizationSelected'
+ storyModule={UserButtonStories}
+/>
+
 ## Menu items
 
 `customMenuItems` adds the app's own rows to the foot of the popup, ahead of Clerk's own. A row with

packages/swingset/src/stories/user-button.stories.tsx

@@ -143,9 +143,19 @@ const LATENCY_MS = 800;
  * The actions that would navigate somewhere in a real app (Manage, Invite, Create organization, Add
  * account) have nowhere to go here, so they only close the popover.
  */
-function usePrototype(): Omit<UserButtonProps, 'mode'> {
+function usePrototype({
+ hidePersonal = false,
+ startWithoutOrganization = false,
+}: {
+ hidePersonal?: boolean;
+ startWithoutOrganization?: boolean;
+} = {}): Omit<UserButtonProps, 'mode'> {
  const [open, setOpen] = useState(false);
- const [accounts, setAccounts] = useState(initialAccounts);
+ const [accounts, setAccounts] = useState(() =>
+ startWithoutOrganization
+ ? initialAccounts.map(a => (a.session.sessionId === colin.sessionId ? { ...a, activeOrganizationId: null } : a))
+ : initialAccounts,
+ );
  const [activeSessionId, setActiveSessionId] = useState(colin.sessionId);
  const [pendingKey, setPendingKey] = useState<string | null>(null);
 
@@ -196,6 +206,7 @@ function usePrototype(): Omit<UserButtonProps, 'mode'> {
  suggestions: account.suggestions,
  invitations: account.invitations,
  additionalSessions: accounts.filter(a => a.session.sessionId !== activeSessionId).map(a => a.session),
+ hidePersonal,
  // Selecting an organization only ever acts on the active account, and is the one action that
  // closes the surface behind it.
  onSelectOrganization: organizationId =>
@@ -300,6 +311,19 @@ export function User(_args: Record<string, unknown>) {
  );
 }
 
+export function NoOrganizationSelected(_args: Record<string, unknown>) {
+ const prototype = usePrototype({ hidePersonal: true, startWithoutOrganization: true });
+
+ // Personal is withheld and nothing is active, so the lead is no selection — not the account.
+ // Picking an organization leaves it.
+ return (
+ <UserButtonView
+ {...prototype}
+ mode='combined'
+ />
+ );
+}
+
 export function SingleSession(_args: Record<string, unknown>) {
  const prototype = usePrototype();
 

packages/ui/src/hooks/useOrganizationListInView.ts

@@ -5,14 +5,18 @@ import { useInView } from './useInView';
 
 /**
  * @internal
+ *
+ * `enabled` withholds the list params so the three requests do not start. Defaults on.
  */
-export const useOrganizationListInView = () => {
- const { userMemberships, userInvitations, userSuggestions } = useOrganizationList(organizationListParams);
+export const useOrganizationListInView = ({ enabled = true }: { enabled?: boolean } = {}) => {
+ const { userMemberships, userInvitations, userSuggestions } = useOrganizationList(
+ enabled ? organizationListParams : undefined,
+ );
 
  const { ref } = useInView({
  threshold: 0,
  onChange: inView => {
- if (!inView) {
+ if (!enabled || !inView) {
  return;
  }
  if (userMemberships.hasNextPage) {

packages/ui/src/mosaic/components/button/submit-button.test.tsx

@@ -317,19 +317,29 @@ describe('Mosaic SubmitButton spin delay', () => {
  expect(atoms(spinner()).length).toBeLessThan(hidden.length);
  });
 
- // A consumer who already knows the action is slow has nothing to gain by waiting.
+ // A consumer who already knows the action is slow has nothing to gain by waiting: there is no
+ // delay left to outlast, so the spinner shows in the render that starts the action rather than a
+ // timer's.
  it('lets the consumer opt out of the delay', () => {
- render(
+const { rerender } = render(
  <SubmitButton
  isPending
- spinDelay={{ delay: 0 }}
+ spinDelay={{ delay: 1000 }}
  >
  Save
  </SubmitButton>,
  );
  const hidden = atoms(spinner());
 
- advance(0);
+ rerender(
+ <SubmitButton
+ isPending
+ spinDelay={{ delay: 0 }}
+ >
+ Save
+ </SubmitButton>,
+ );
+
  expect(atoms(spinner()).length).toBeLessThan(hidden.length);
  });
 

packages/ui/src/mosaic/hooks/__tests__/useSpinDelay.test.ts

@@ -76,6 +76,27 @@ describe('useSpinDelay', () => {
  expect(result.current).toBeNull();
  });
 
+ // Direct feedback on a click has nothing to debounce, so a zero delay must not cost a timer's
+ // worth of render passes before the spinner appears.
+ it('surfaces the value in the same pass when there is no delay to wait out', async () => {
+ const { result, rerender } = render(null, { delay: 0, minDuration: 200 });
+ await act(() => rerender({ value: 'a' }));
+
+ expect(result.current).toBe('a');
+ });
+
+ it('still holds a zero-delay value for minDuration', async () => {
+ const { result, rerender } = render(null, { delay: 0, minDuration: 200 });
+ await act(() => rerender({ value: 'a' }));
+ await act(() => rerender({ value: null }));
+
+ await advance(199);
+ expect(result.current).toBe('a');
+
+ await advance(1);
+ expect(result.current).toBeNull();
+ });
+
  it('swaps to a new value immediately when one replaces another mid-show', async () => {
  const { result, rerender } = render(null, { delay: 500, minDuration: 200 });
  await act(() => rerender({ value: 'a' }));

packages/ui/src/mosaic/hooks/useSpinDelay.ts

@@ -1,7 +1,7 @@
 import { useEffect, useRef, useState } from 'react';
 
 export interface SpinDelayOptions {
- /** Wait this long before showing the value, so quick actions never flash a spinner. */
+ /** Wait this long before showing the value, so quick actions never flash a spinner. `0` shows it straight away. */
  delay?: number;
  /** Once shown, keep the value up at least this long, so the spinner never flickers off. */
  minDuration?: number;
@@ -25,11 +25,17 @@ export function useSpinDelay<T>(value: T | null, options: SpinDelayOptions = {})
  const shownAt = useRef(0);
 
  useEffect(() => {
- // Nothing showing yet: arm a timer so the value only surfaces if it outlasts `delay`.
+ // Nothing showing yet: arm a timer so the value only surfaces if it outlasts `delay`. With no
+ // delay there is nothing to outlast, so it surfaces in this pass rather than a timer's.
  if (shown === null) {
  if (value === null) {
  return;
  }
+ if (delay <= 0) {
+ shownAt.current = Date.now();
+ setShown(value);
+ return;
+ }
  const timer = setTimeout(() => {
  shownAt.current = Date.now();
  setShown(value);

.changeset/mosaic-user-button-controller.md

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

.changeset/mosaic-user-button-integration.md

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

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

@@ -7,13 +7,16 @@ import { useClerk } from './useClerk';
  *
  * @internal
  */
-export function useAttemptToEnableOrganizations(caller: 'useOrganization' | 'useOrganizationList') {
+export function useAttemptToEnableOrganizations(
+ caller: 'useOrganization' | 'useOrganizationList',
+ { enabled = true }: { enabled?: boolean } = {},
+) {
  const clerk = useClerk();
  const hasAttempted = useRef(false);
 
  useEffect(() => {
  // Guard to not run this effect twice on Clerk resource update
- if (hasAttempted.current) {
+ if (!enabled || hasAttempted.current) {
  return;
  }
 
@@ -23,5 +26,5 @@ export function useAttemptToEnableOrganizations(caller: 'useOrganization' | 'use
  for: 'organizations',
  caller,
  });
- }, [clerk, caller]);
+ }, [clerk, caller, enabled]);
 }

packages/shared/src/react/hooks/useOrganization.tsx

@@ -61,6 +61,12 @@ export type UseOrganizationParams = {
  * </ul>
  */
  invitations?: true | PaginatedHookConfig<GetInvitationsParams>;
+ /**
+ * Skip the development prompt that offers to enable Organizations.
+ *
+ * @internal
+ */
+ __internal_skipAttemptToEnableOrganizations?: boolean;
 };
 
 /**
@@ -275,10 +281,13 @@ export function useOrganization<T extends UseOrganizationParams>(params?: T): Us
  membershipRequests: membershipRequestsListParams,
  memberships: membersListParams,
  invitations: invitationsListParams,
+ __internal_skipAttemptToEnableOrganizations,
  } = params || {};
 
  useAssertWrappedByClerkProvider('useOrganization');
- useAttemptToEnableOrganizations('useOrganization');
+ useAttemptToEnableOrganizations('useOrganization', {
+ enabled: !__internal_skipAttemptToEnableOrganizations,
+ });
 
  const organization = useOrganizationBase();
  const session = useSessionBase();

packages/shared/src/react/hooks/useOrganizationList.tsx

@@ -253,7 +253,10 @@ export function useOrganizationList<T extends UseOrganizationListParams>(params?
  const { userMemberships, userInvitations, userSuggestions } = params || {};
 
  useAssertWrappedByClerkProvider('useOrganizationList');
- useAttemptToEnableOrganizations('useOrganizationList');
+ // No list keys means this call is not using Organizations; the prompt is for the lists.
+ useAttemptToEnableOrganizations('useOrganizationList', {
+ enabled: userMemberships !== undefined || userInvitations !== undefined || userSuggestions !== undefined,
+ });
 
  const userMembershipsSafeValues = useWithSafeValues(userMemberships, {
  initialPage: 1,

packages/swingset/src/stories/user-button.mdx

@@ -74,7 +74,7 @@ Exports are flat (not `UserButton.Trigger`) so each part declares its own `'use
 ## Trigger
 
 The active workspace's avatar and what it is called: the org and its plan wherever one heads the
-trigger, the account otherwise.
+trigger, no selection when personal is hidden and none is active, the account otherwise.
 
 `renderTriggerLabel={false}` leaves the avatar alone.
 
@@ -164,6 +164,18 @@ accounts" ever meant here.
  storyModule={UserButtonStories}
 />
 
+## No organization selected
+
+`hidePersonal` withholds the personal workspace — the instance does this when it forces an
+organization, or the app does it itself. With no org active either, the lead is not the account:
+trigger and header say **No organization selected**, the mark is square, and the gear is **Manage
+account**.
+
+<Story
+ name='NoOrganizationSelected'
+ storyModule={UserButtonStories}
+/>
+
 ## Menu items
 
 `customMenuItems` adds the app's own rows to the foot of the popup, ahead of Clerk's own. A row with

packages/swingset/src/stories/user-button.stories.tsx

@@ -143,9 +143,19 @@ const LATENCY_MS = 800;
  * The actions that would navigate somewhere in a real app (Manage, Invite, Create organization, Add
  * account) have nowhere to go here, so they only close the popover.
  */
-function usePrototype(): Omit<UserButtonProps, 'mode'> {
+function usePrototype({
+ hidePersonal = false,
+ startWithoutOrganization = false,
+}: {
+ hidePersonal?: boolean;
+ startWithoutOrganization?: boolean;
+} = {}): Omit<UserButtonProps, 'mode'> {
  const [open, setOpen] = useState(false);
- const [accounts, setAccounts] = useState(initialAccounts);
+ const [accounts, setAccounts] = useState(() =>
+ startWithoutOrganization
+ ? initialAccounts.map(a => (a.session.sessionId === colin.sessionId ? { ...a, activeOrganizationId: null } : a))
+ : initialAccounts,
+ );
  const [activeSessionId, setActiveSessionId] = useState(colin.sessionId);
  const [pendingKey, setPendingKey] = useState<string | null>(null);
 
@@ -196,6 +206,7 @@ function usePrototype(): Omit<UserButtonProps, 'mode'> {
  suggestions: account.suggestions,
  invitations: account.invitations,
  additionalSessions: accounts.filter(a => a.session.sessionId !== activeSessionId).map(a => a.session),
+ hidePersonal,
  // Selecting an organization only ever acts on the active account, and is the one action that
  // closes the surface behind it.
  onSelectOrganization: organizationId =>
@@ -300,6 +311,19 @@ export function User(_args: Record<string, unknown>) {
  );
 }
 
+export function NoOrganizationSelected(_args: Record<string, unknown>) {
+ const prototype = usePrototype({ hidePersonal: true, startWithoutOrganization: true });
+
+ // Personal is withheld and nothing is active, so the lead is no selection — not the account.
+ // Picking an organization leaves it.
+ return (
+ <UserButtonView
+ {...prototype}
+ mode='combined'
+ />
+ );
+}
+
 export function SingleSession(_args: Record<string, unknown>) {
  const prototype = usePrototype();
 

packages/ui/src/hooks/useOrganizationListInView.ts

@@ -5,14 +5,18 @@ import { useInView } from './useInView';
 
 /**
  * @internal
+ *
+ * `enabled` withholds the list params so the three requests do not start. Defaults on.
  */
-export const useOrganizationListInView = () => {
- const { userMemberships, userInvitations, userSuggestions } = useOrganizationList(organizationListParams);
+export const useOrganizationListInView = ({ enabled = true }: { enabled?: boolean } = {}) => {
+ const { userMemberships, userInvitations, userSuggestions } = useOrganizationList(
+ enabled ? organizationListParams : undefined,
+ );
 
  const { ref } = useInView({
  threshold: 0,
  onChange: inView => {
- if (!inView) {
+ if (!enabled || !inView) {
  return;
  }
  if (userMemberships.hasNextPage) {

packages/ui/src/mosaic/components/button/submit-button.test.tsx

@@ -317,19 +317,29 @@ describe('Mosaic SubmitButton spin delay', () => {
  expect(atoms(spinner()).length).toBeLessThan(hidden.length);
  });
 
- // A consumer who already knows the action is slow has nothing to gain by waiting.
+ // A consumer who already knows the action is slow has nothing to gain by waiting: there is no
+ // delay left to outlast, so the spinner shows in the render that starts the action rather than a
+ // timer's.
  it('lets the consumer opt out of the delay', () => {
- render(
+const { rerender } = render(
  <SubmitButton
  isPending
- spinDelay={{ delay: 0 }}
+ spinDelay={{ delay: 1000 }}
  >
  Save
  </SubmitButton>,
  );
  const hidden = atoms(spinner());
 
- advance(0);
+ rerender(
+ <SubmitButton
+ isPending
+ spinDelay={{ delay: 0 }}
+ >
+ Save
+ </SubmitButton>,
+ );
+
  expect(atoms(spinner()).length).toBeLessThan(hidden.length);
  });
 

packages/ui/src/mosaic/hooks/__tests__/useSpinDelay.test.ts

@@ -76,6 +76,27 @@ describe('useSpinDelay', () => {
  expect(result.current).toBeNull();
  });
 
+ // Direct feedback on a click has nothing to debounce, so a zero delay must not cost a timer's
+ // worth of render passes before the spinner appears.
+ it('surfaces the value in the same pass when there is no delay to wait out', async () => {
+ const { result, rerender } = render(null, { delay: 0, minDuration: 200 });
+ await act(() => rerender({ value: 'a' }));
+
+ expect(result.current).toBe('a');
+ });
+
+ it('still holds a zero-delay value for minDuration', async () => {
+ const { result, rerender } = render(null, { delay: 0, minDuration: 200 });
+ await act(() => rerender({ value: 'a' }));
+ await act(() => rerender({ value: null }));
+
+ await advance(199);
+ expect(result.current).toBe('a');
+
+ await advance(1);
+ expect(result.current).toBeNull();
+ });
+
  it('swaps to a new value immediately when one replaces another mid-show', async () => {
  const { result, rerender } = render(null, { delay: 500, minDuration: 200 });
  await act(() => rerender({ value: 'a' }));

packages/ui/src/mosaic/hooks/useSpinDelay.ts

@@ -1,7 +1,7 @@
 import { useEffect, useRef, useState } from 'react';
 
 export interface SpinDelayOptions {
- /** Wait this long before showing the value, so quick actions never flash a spinner. */
+ /** Wait this long before showing the value, so quick actions never flash a spinner. `0` shows it straight away. */
  delay?: number;
  /** Once shown, keep the value up at least this long, so the spinner never flickers off. */
  minDuration?: number;
@@ -25,11 +25,17 @@ export function useSpinDelay<T>(value: T | null, options: SpinDelayOptions = {})
  const shownAt = useRef(0);
 
  useEffect(() => {
- // Nothing showing yet: arm a timer so the value only surfaces if it outlasts `delay`.
+ // Nothing showing yet: arm a timer so the value only surfaces if it outlasts `delay`. With no
+ // delay there is nothing to outlast, so it surfaces in this pass rather than a timer's.
  if (shown === null) {
  if (value === null) {
  return;
  }
+ if (delay <= 0) {
+ shownAt.current = Date.now();
+ setShown(value);
+ return;
+ }
  const timer = setTimeout(() => {
  shownAt.current = Date.now();
  setShown(value);

.changeset/mosaic-user-button-controller.md

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

.changeset/mosaic-user-button-integration.md

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

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

@@ -7,13 +7,16 @@ import { useClerk } from './useClerk';
  *
  * @internal
  */
-export function useAttemptToEnableOrganizations(caller: 'useOrganization' | 'useOrganizationList') {
+export function useAttemptToEnableOrganizations(
+ caller: 'useOrganization' | 'useOrganizationList',
+ { enabled = true }: { enabled?: boolean } = {},
+) {
  const clerk = useClerk();
  const hasAttempted = useRef(false);
 
  useEffect(() => {
  // Guard to not run this effect twice on Clerk resource update
- if (hasAttempted.current) {
+ if (!enabled || hasAttempted.current) {
  return;
  }
 
@@ -23,5 +26,5 @@ export function useAttemptToEnableOrganizations(caller: 'useOrganization' | 'use
  for: 'organizations',
  caller,
  });
- }, [clerk, caller]);
+ }, [clerk, caller, enabled]);
 }

packages/shared/src/react/hooks/useOrganization.tsx

@@ -61,6 +61,12 @@ export type UseOrganizationParams = {
  * </ul>
  */
  invitations?: true | PaginatedHookConfig<GetInvitationsParams>;
+ /**
+ * Skip the development prompt that offers to enable Organizations.
+ *
+ * @internal
+ */
+ __internal_skipAttemptToEnableOrganizations?: boolean;
 };
 
 /**
@@ -275,10 +281,13 @@ export function useOrganization<T extends UseOrganizationParams>(params?: T): Us
  membershipRequests: membershipRequestsListParams,
  memberships: membersListParams,
  invitations: invitationsListParams,
+ __internal_skipAttemptToEnableOrganizations,
  } = params || {};
 
  useAssertWrappedByClerkProvider('useOrganization');
- useAttemptToEnableOrganizations('useOrganization');
+ useAttemptToEnableOrganizations('useOrganization', {
+ enabled: !__internal_skipAttemptToEnableOrganizations,
+ });
 
  const organization = useOrganizationBase();
  const session = useSessionBase();

packages/shared/src/react/hooks/useOrganizationList.tsx

@@ -253,7 +253,10 @@ export function useOrganizationList<T extends UseOrganizationListParams>(params?
  const { userMemberships, userInvitations, userSuggestions } = params || {};
 
  useAssertWrappedByClerkProvider('useOrganizationList');
- useAttemptToEnableOrganizations('useOrganizationList');
+ // No list keys means this call is not using Organizations; the prompt is for the lists.
+ useAttemptToEnableOrganizations('useOrganizationList', {
+ enabled: userMemberships !== undefined || userInvitations !== undefined || userSuggestions !== undefined,
+ });
 
  const userMembershipsSafeValues = useWithSafeValues(userMemberships, {
  initialPage: 1,

packages/swingset/src/stories/user-button.mdx

@@ -74,7 +74,7 @@ Exports are flat (not `UserButton.Trigger`) so each part declares its own `'use
 ## Trigger
 
 The active workspace's avatar and what it is called: the org and its plan wherever one heads the
-trigger, the account otherwise.
+trigger, no selection when personal is hidden and none is active, the account otherwise.
 
 `renderTriggerLabel={false}` leaves the avatar alone.
 
@@ -164,6 +164,18 @@ accounts" ever meant here.
  storyModule={UserButtonStories}
 />
 
+## No organization selected
+
+`hidePersonal` withholds the personal workspace — the instance does this when it forces an
+organization, or the app does it itself. With no org active either, the lead is not the account:
+trigger and header say **No organization selected**, the mark is square, and the gear is **Manage
+account**.
+
+<Story
+ name='NoOrganizationSelected'
+ storyModule={UserButtonStories}
+/>
+
 ## Menu items
 
 `customMenuItems` adds the app's own rows to the foot of the popup, ahead of Clerk's own. A row with

packages/swingset/src/stories/user-button.stories.tsx

@@ -143,9 +143,19 @@ const LATENCY_MS = 800;
  * The actions that would navigate somewhere in a real app (Manage, Invite, Create organization, Add
  * account) have nowhere to go here, so they only close the popover.
  */
-function usePrototype(): Omit<UserButtonProps, 'mode'> {
+function usePrototype({
+ hidePersonal = false,
+ startWithoutOrganization = false,
+}: {
+ hidePersonal?: boolean;
+ startWithoutOrganization?: boolean;
+} = {}): Omit<UserButtonProps, 'mode'> {
  const [open, setOpen] = useState(false);
- const [accounts, setAccounts] = useState(initialAccounts);
+ const [accounts, setAccounts] = useState(() =>
+ startWithoutOrganization
+ ? initialAccounts.map(a => (a.session.sessionId === colin.sessionId ? { ...a, activeOrganizationId: null } : a))
+ : initialAccounts,
+ );
  const [activeSessionId, setActiveSessionId] = useState(colin.sessionId);
  const [pendingKey, setPendingKey] = useState<string | null>(null);
 
@@ -196,6 +206,7 @@ function usePrototype(): Omit<UserButtonProps, 'mode'> {
  suggestions: account.suggestions,
  invitations: account.invitations,
  additionalSessions: accounts.filter(a => a.session.sessionId !== activeSessionId).map(a => a.session),
+ hidePersonal,
  // Selecting an organization only ever acts on the active account, and is the one action that
  // closes the surface behind it.
  onSelectOrganization: organizationId =>
@@ -300,6 +311,19 @@ export function User(_args: Record<string, unknown>) {
  );
 }
 
+export function NoOrganizationSelected(_args: Record<string, unknown>) {
+ const prototype = usePrototype({ hidePersonal: true, startWithoutOrganization: true });
+
+ // Personal is withheld and nothing is active, so the lead is no selection — not the account.
+ // Picking an organization leaves it.
+ return (
+ <UserButtonView
+ {...prototype}
+ mode='combined'
+ />
+ );
+}
+
 export function SingleSession(_args: Record<string, unknown>) {
  const prototype = usePrototype();
 

packages/ui/src/hooks/useOrganizationListInView.ts

@@ -5,14 +5,18 @@ import { useInView } from './useInView';
 
 /**
  * @internal
+ *
+ * `enabled` withholds the list params so the three requests do not start. Defaults on.
  */
-export const useOrganizationListInView = () => {
- const { userMemberships, userInvitations, userSuggestions } = useOrganizationList(organizationListParams);
+export const useOrganizationListInView = ({ enabled = true }: { enabled?: boolean } = {}) => {
+ const { userMemberships, userInvitations, userSuggestions } = useOrganizationList(
+ enabled ? organizationListParams : undefined,
+ );
 
  const { ref } = useInView({
  threshold: 0,
  onChange: inView => {
- if (!inView) {
+ if (!enabled || !inView) {
  return;
  }
  if (userMemberships.hasNextPage) {

packages/ui/src/mosaic/components/button/submit-button.test.tsx

@@ -317,19 +317,29 @@ describe('Mosaic SubmitButton spin delay', () => {
  expect(atoms(spinner()).length).toBeLessThan(hidden.length);
  });
 
- // A consumer who already knows the action is slow has nothing to gain by waiting.
+ // A consumer who already knows the action is slow has nothing to gain by waiting: there is no
+ // delay left to outlast, so the spinner shows in the render that starts the action rather than a
+ // timer's.
  it('lets the consumer opt out of the delay', () => {
- render(
+const { rerender } = render(
  <SubmitButton
  isPending
- spinDelay={{ delay: 0 }}
+ spinDelay={{ delay: 1000 }}
  >
  Save
  </SubmitButton>,
  );
  const hidden = atoms(spinner());
 
- advance(0);
+ rerender(
+ <SubmitButton
+ isPending
+ spinDelay={{ delay: 0 }}
+ >
+ Save
+ </SubmitButton>,
+ );
+
  expect(atoms(spinner()).length).toBeLessThan(hidden.length);
  });
 

packages/ui/src/mosaic/hooks/__tests__/useSpinDelay.test.ts

@@ -76,6 +76,27 @@ describe('useSpinDelay', () => {
  expect(result.current).toBeNull();
  });
 
+ // Direct feedback on a click has nothing to debounce, so a zero delay must not cost a timer's
+ // worth of render passes before the spinner appears.
+ it('surfaces the value in the same pass when there is no delay to wait out', async () => {
+ const { result, rerender } = render(null, { delay: 0, minDuration: 200 });
+ await act(() => rerender({ value: 'a' }));
+
+ expect(result.current).toBe('a');
+ });
+
+ it('still holds a zero-delay value for minDuration', async () => {
+ const { result, rerender } = render(null, { delay: 0, minDuration: 200 });
+ await act(() => rerender({ value: 'a' }));
+ await act(() => rerender({ value: null }));
+
+ await advance(199);
+ expect(result.current).toBe('a');
+
+ await advance(1);
+ expect(result.current).toBeNull();
+ });
+
  it('swaps to a new value immediately when one replaces another mid-show', async () => {
  const { result, rerender } = render(null, { delay: 500, minDuration: 200 });
  await act(() => rerender({ value: 'a' }));

packages/ui/src/mosaic/hooks/useSpinDelay.ts

@@ -1,7 +1,7 @@
 import { useEffect, useRef, useState } from 'react';
 
 export interface SpinDelayOptions {
- /** Wait this long before showing the value, so quick actions never flash a spinner. */
+ /** Wait this long before showing the value, so quick actions never flash a spinner. `0` shows it straight away. */
  delay?: number;
  /** Once shown, keep the value up at least this long, so the spinner never flickers off. */
  minDuration?: number;
@@ -25,11 +25,17 @@ export function useSpinDelay<T>(value: T | null, options: SpinDelayOptions = {})
  const shownAt = useRef(0);
 
  useEffect(() => {
- // Nothing showing yet: arm a timer so the value only surfaces if it outlasts `delay`.
+ // Nothing showing yet: arm a timer so the value only surfaces if it outlasts `delay`. With no
+ // delay there is nothing to outlast, so it surfaces in this pass rather than a timer's.
  if (shown === null) {
  if (value === null) {
  return;
  }
+ if (delay <= 0) {
+ shownAt.current = Date.now();
+ setShown(value);
+ return;
+ }
  const timer = setTimeout(() => {
  shownAt.current = Date.now();
  setShown(value);