feat(ui): announce the user button's in-flight action

.changeset/mosaic-user-button-pending-announcement.md

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

packages/ui/src/mosaic/user-button/__tests__/user-button.view.test.tsx

@@ -513,7 +513,9 @@ describe('UserButtonView, the workspace list', () => {
  it('says so to a screen reader, since nothing else reports the rows landing', () => {
  renderList({ organizationsLoading: true });
 
- expect(screen.getByRole('status')).toHaveTextContent('Loading organizations…');
+ // The popup's own region speaks for the action a row is running, so the placeholder is asked
+ // for by its text: the two report different waits and are both on the page here.
+ expect(screen.getByText('Loading organizations…').closest('[role="status"]')).toBeInTheDocument();
  });
 
  it('leaves the account row above it alone, since it does not wait on the list', () => {
@@ -726,6 +728,48 @@ describe('UserButtonView, one action at a time', () => {
  expect(onSwitchSession).not.toHaveBeenCalled();
  expect(row).toHaveFocus();
  });
+
+ // The row keeps focus while it stands down, so nothing about the surface reports the wait on its
+ // own: the spinner is a picture, and `aria-disabled` says a row cannot be used rather than why.
+ // Named from the key, so the surface says what is running rather than that something is.
+ it.each([
+ [userButtonBusyKeys.selectOrganization('org_2'), 'Switching to Other Co', {}],
+ [userButtonBusyKeys.selectOrganization(null), 'Switching to Personal account', {}],
+ [userButtonBusyKeys.switchSession('sess_2'), 'Switching to bob@example.com', {}],
+ [userButtonBusyKeys.signOutSession('sess_2'), 'Signing out of bob@example.com', {}],
+ [userButtonBusyKeys.signOutAll(), 'Signing out of all accounts', {}],
+ [userButtonBusyKeys.acceptInvitation('inv_1'), 'Joining Gamma', { invitations: [gamma] }],
+ [userButtonBusyKeys.acceptSuggestion('sug_1'), 'Requesting to join Beta', { suggestions: [beta] }],
+ ])('names the wait in a live region: %s', (pendingKey, announcement, props) => {
+ render(surface(pendingKey, props));
+
+ expect(screen.getByRole('status')).toHaveTextContent(announcement);
+ });
+
+ // A region that mounts with its message already in it is not announced, so the popup carries an
+ // empty one from the moment it opens and the message lands in a region that is already there.
+ it('carries the region while idle', () => {
+ render(surface(null));
+
+ expect(screen.getByRole('status')).toBeEmptyDOMElement();
+ });
+
+ // Picking a workspace closes the popup behind it, so a region living in the popup would be taken
+ // off the page while it was still being read out. It belongs to the surface, which stays.
+ it('carries the region whether or not the popup is open', () => {
+ render(surface(userButtonBusyKeys.selectOrganization('org_2'), { defaultOpen: false }));
+
+ expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
+ expect(screen.getByRole('status')).toHaveTextContent('Switching to Other Co');
+ });
+
+ // A key can outlive what it names: an account signs out from its own row, and the row is gone
+ // before the action lands. The region says nothing rather than announcing a half-filled template.
+ it('says nothing for an action it cannot name', () => {
+ render(surface(userButtonBusyKeys.switchSession('sess_9')));
+
+ expect(screen.getByRole('status')).toBeEmptyDOMElement();
+ });
 });
 
 describe('UserButtonTrigger', () => {

packages/ui/src/mosaic/user-button/user-button.messages.ts

@@ -13,6 +13,14 @@ export const userButtonBase = {
  popup: {
  label: 'Account',
  },
+ // What the popup's live region says while an action runs, by the affordance that owns it.
+ status: {
+ switching: 'Switching to {name}',
+ signingOut: 'Signing out of {identifier}',
+ signingOutAll: 'Signing out of all accounts',
+ joining: 'Joining {name}',
+ requesting: 'Requesting to join {name}',
+ },
  workspaces: {
  personal: 'Personal account',
  loading: 'Loading organizations…',

packages/ui/src/mosaic/user-button/user-button.styles.ts

@@ -3,6 +3,17 @@ import * as stylex from '@stylexjs/stylex';
 import { colorVars, fontWeightVars, radiusVars, space, typeScaleVars } from '../tokens.stylex';
 
 export const styles = stylex.create({
+ // Takes the live region out of the layout without taking it out of the accessibility tree, which
+ // `display: none` and `visibility: hidden` both do.
+ visuallyHidden: {
+ overflow: 'hidden',
+ clipPath: 'inset(50%)',
+ position: 'absolute',
+ whiteSpace: 'nowrap',
+ height: '1px',
+ width: '1px',
+ },
+
  // The avatar is the trigger, so the button paints nothing of its own.
  trigger: {
  padding: 0,

packages/ui/src/mosaic/user-button/user-button.view.tsx

@@ -85,6 +85,48 @@ function useBusy(key?: string): { busy: boolean; disabled: boolean } {
  return { busy: pendingKey === key, disabled: pendingKey !== key };
 }
 
+/**
+ * What the surface says while an action runs, by the key that owns it. Keyed through
+ * `userButtonBusyKeys` rather than by parsing `pendingKey`, so the key grammar stays in one place,
+ * and built from the rows' own names so the announcement names the same thing the row does.
+ */
+function pendingAnnouncements(data: UserButtonContextValue): Map<string, string> {
+ const switching = (name: string) => fill(m.status.switching, { name });
+ const announcements = new Map<string, string>([
+ [userButtonBusyKeys.selectOrganization(null), switching(m.workspaces.personal)],
+ [userButtonBusyKeys.signOutAll(), m.status.signingOutAll],
+ ]);
+
+ // The active organization is described whole rather than found in `memberships`, so it is named
+ // here even while the list it belongs to is still loading.
+ for (const membership of data.activeOrganization
+ ? [data.activeOrganization, ...data.memberships]
+ : data.memberships) {
+ announcements.set(userButtonBusyKeys.selectOrganization(membership.organizationId), switching(membership.name));
+ }
+ // Accounts are named by identifier, the way their rows are.
+ for (const session of [data.activeSession, ...data.additionalSessions]) {
+ announcements.set(userButtonBusyKeys.switchSession(session.sessionId), switching(session.identifier));
+ announcements.set(
+ userButtonBusyKeys.signOutSession(session.sessionId),
+ fill(m.status.signingOut, { identifier: session.identifier }),
+ );
+ }
+ for (const invitation of data.invitations) {
+ announcements.set(
+ userButtonBusyKeys.acceptInvitation(invitation.id),
+ fill(m.status.joining, { name: invitation.organizationName }),
+ );
+ }
+ for (const suggestion of data.suggestions) {
+ announcements.set(
+ userButtonBusyKeys.acceptSuggestion(suggestion.id),
+ fill(m.status.requesting, { name: suggestion.name }),
+ );
+ }
+ return announcements;
+}
+
 interface ActiveWorkspace {
  name: string;
  imageUrl?: string;
@@ -937,7 +979,10 @@ export function UserButtonRoot(props: UserButtonRootProps): ReactElement {
  placement={placement ?? 'bottom-start'}
  sideOffset={sideOffset}
  >
- <UserButtonContext.Provider value={{ ...data, layout }}>{children}</UserButtonContext.Provider>
+ <UserButtonContext.Provider value={{ ...data, layout }}>
+ {children}
+ <ActionStatus />
+ </UserButtonContext.Provider>
  </Popover.Root>
  );
 }
@@ -989,6 +1034,28 @@ export function UserButtonTrigger({
  );
 }
 
+/**
+ * Speaks the one in-flight action. `pendingKey` allows a single action at a time, so the surface
+ * needs one region rather than one per affordance.
+ *
+ * It belongs to the surface rather than to the popup or the acting row, both of which go while the
+ * action is still running: picking a workspace closes the popup behind it, and a row leaves when the
+ * list re-sorts or an account signs out. A region taken off the page mid-announcement is not read.
+ */
+function ActionStatus(): ReactElement {
+ const data = useUserButtonContext();
+ // Mounted whether or not anything is running: a region that arrives with its message already in
+ // it is not announced, so the message has to land in a region that is already on the page.
+ return (
+ <span
+ role='status'
+ {...stylex.props(styles.visuallyHidden)}
+ >
+ {(data.pendingKey && pendingAnnouncements(data).get(data.pendingKey)) || ''}
+ </span>
+ );
+}
+
 /** The popover surface: header, workspace list, additional accounts, and footer. */
 export function UserButtonPopup(): ReactElement {
  return (

.changeset/mosaic-user-button-pending-announcement.md

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

packages/ui/src/mosaic/user-button/__tests__/user-button.view.test.tsx

@@ -513,7 +513,9 @@ describe('UserButtonView, the workspace list', () => {
  it('says so to a screen reader, since nothing else reports the rows landing', () => {
  renderList({ organizationsLoading: true });
 
- expect(screen.getByRole('status')).toHaveTextContent('Loading organizations…');
+ // The popup's own region speaks for the action a row is running, so the placeholder is asked
+ // for by its text: the two report different waits and are both on the page here.
+ expect(screen.getByText('Loading organizations…').closest('[role="status"]')).toBeInTheDocument();
  });
 
  it('leaves the account row above it alone, since it does not wait on the list', () => {
@@ -726,6 +728,48 @@ describe('UserButtonView, one action at a time', () => {
  expect(onSwitchSession).not.toHaveBeenCalled();
  expect(row).toHaveFocus();
  });
+
+ // The row keeps focus while it stands down, so nothing about the surface reports the wait on its
+ // own: the spinner is a picture, and `aria-disabled` says a row cannot be used rather than why.
+ // Named from the key, so the surface says what is running rather than that something is.
+ it.each([
+ [userButtonBusyKeys.selectOrganization('org_2'), 'Switching to Other Co', {}],
+ [userButtonBusyKeys.selectOrganization(null), 'Switching to Personal account', {}],
+ [userButtonBusyKeys.switchSession('sess_2'), 'Switching to bob@example.com', {}],
+ [userButtonBusyKeys.signOutSession('sess_2'), 'Signing out of bob@example.com', {}],
+ [userButtonBusyKeys.signOutAll(), 'Signing out of all accounts', {}],
+ [userButtonBusyKeys.acceptInvitation('inv_1'), 'Joining Gamma', { invitations: [gamma] }],
+ [userButtonBusyKeys.acceptSuggestion('sug_1'), 'Requesting to join Beta', { suggestions: [beta] }],
+ ])('names the wait in a live region: %s', (pendingKey, announcement, props) => {
+ render(surface(pendingKey, props));
+
+ expect(screen.getByRole('status')).toHaveTextContent(announcement);
+ });
+
+ // A region that mounts with its message already in it is not announced, so the popup carries an
+ // empty one from the moment it opens and the message lands in a region that is already there.
+ it('carries the region while idle', () => {
+ render(surface(null));
+
+ expect(screen.getByRole('status')).toBeEmptyDOMElement();
+ });
+
+ // Picking a workspace closes the popup behind it, so a region living in the popup would be taken
+ // off the page while it was still being read out. It belongs to the surface, which stays.
+ it('carries the region whether or not the popup is open', () => {
+ render(surface(userButtonBusyKeys.selectOrganization('org_2'), { defaultOpen: false }));
+
+ expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
+ expect(screen.getByRole('status')).toHaveTextContent('Switching to Other Co');
+ });
+
+ // A key can outlive what it names: an account signs out from its own row, and the row is gone
+ // before the action lands. The region says nothing rather than announcing a half-filled template.
+ it('says nothing for an action it cannot name', () => {
+ render(surface(userButtonBusyKeys.switchSession('sess_9')));
+
+ expect(screen.getByRole('status')).toBeEmptyDOMElement();
+ });
 });
 
 describe('UserButtonTrigger', () => {

packages/ui/src/mosaic/user-button/user-button.messages.ts

@@ -13,6 +13,14 @@ export const userButtonBase = {
  popup: {
  label: 'Account',
  },
+ // What the popup's live region says while an action runs, by the affordance that owns it.
+ status: {
+ switching: 'Switching to {name}',
+ signingOut: 'Signing out of {identifier}',
+ signingOutAll: 'Signing out of all accounts',
+ joining: 'Joining {name}',
+ requesting: 'Requesting to join {name}',
+ },
  workspaces: {
  personal: 'Personal account',
  loading: 'Loading organizations…',

packages/ui/src/mosaic/user-button/user-button.styles.ts

@@ -3,6 +3,17 @@ import * as stylex from '@stylexjs/stylex';
 import { colorVars, fontWeightVars, radiusVars, space, typeScaleVars } from '../tokens.stylex';
 
 export const styles = stylex.create({
+ // Takes the live region out of the layout without taking it out of the accessibility tree, which
+ // `display: none` and `visibility: hidden` both do.
+ visuallyHidden: {
+ overflow: 'hidden',
+ clipPath: 'inset(50%)',
+ position: 'absolute',
+ whiteSpace: 'nowrap',
+ height: '1px',
+ width: '1px',
+ },
+
  // The avatar is the trigger, so the button paints nothing of its own.
  trigger: {
  padding: 0,

packages/ui/src/mosaic/user-button/user-button.view.tsx

@@ -85,6 +85,48 @@ function useBusy(key?: string): { busy: boolean; disabled: boolean } {
  return { busy: pendingKey === key, disabled: pendingKey !== key };
 }
 
+/**
+ * What the surface says while an action runs, by the key that owns it. Keyed through
+ * `userButtonBusyKeys` rather than by parsing `pendingKey`, so the key grammar stays in one place,
+ * and built from the rows' own names so the announcement names the same thing the row does.
+ */
+function pendingAnnouncements(data: UserButtonContextValue): Map<string, string> {
+ const switching = (name: string) => fill(m.status.switching, { name });
+ const announcements = new Map<string, string>([
+ [userButtonBusyKeys.selectOrganization(null), switching(m.workspaces.personal)],
+ [userButtonBusyKeys.signOutAll(), m.status.signingOutAll],
+ ]);
+
+ // The active organization is described whole rather than found in `memberships`, so it is named
+ // here even while the list it belongs to is still loading.
+ for (const membership of data.activeOrganization
+ ? [data.activeOrganization, ...data.memberships]
+ : data.memberships) {
+ announcements.set(userButtonBusyKeys.selectOrganization(membership.organizationId), switching(membership.name));
+ }
+ // Accounts are named by identifier, the way their rows are.
+ for (const session of [data.activeSession, ...data.additionalSessions]) {
+ announcements.set(userButtonBusyKeys.switchSession(session.sessionId), switching(session.identifier));
+ announcements.set(
+ userButtonBusyKeys.signOutSession(session.sessionId),
+ fill(m.status.signingOut, { identifier: session.identifier }),
+ );
+ }
+ for (const invitation of data.invitations) {
+ announcements.set(
+ userButtonBusyKeys.acceptInvitation(invitation.id),
+ fill(m.status.joining, { name: invitation.organizationName }),
+ );
+ }
+ for (const suggestion of data.suggestions) {
+ announcements.set(
+ userButtonBusyKeys.acceptSuggestion(suggestion.id),
+ fill(m.status.requesting, { name: suggestion.name }),
+ );
+ }
+ return announcements;
+}
+
 interface ActiveWorkspace {
  name: string;
  imageUrl?: string;
@@ -937,7 +979,10 @@ export function UserButtonRoot(props: UserButtonRootProps): ReactElement {
  placement={placement ?? 'bottom-start'}
  sideOffset={sideOffset}
  >
- <UserButtonContext.Provider value={{ ...data, layout }}>{children}</UserButtonContext.Provider>
+ <UserButtonContext.Provider value={{ ...data, layout }}>
+ {children}
+ <ActionStatus />
+ </UserButtonContext.Provider>
  </Popover.Root>
  );
 }
@@ -989,6 +1034,28 @@ export function UserButtonTrigger({
  );
 }
 
+/**
+ * Speaks the one in-flight action. `pendingKey` allows a single action at a time, so the surface
+ * needs one region rather than one per affordance.
+ *
+ * It belongs to the surface rather than to the popup or the acting row, both of which go while the
+ * action is still running: picking a workspace closes the popup behind it, and a row leaves when the
+ * list re-sorts or an account signs out. A region taken off the page mid-announcement is not read.
+ */
+function ActionStatus(): ReactElement {
+ const data = useUserButtonContext();
+ // Mounted whether or not anything is running: a region that arrives with its message already in
+ // it is not announced, so the message has to land in a region that is already on the page.
+ return (
+ <span
+ role='status'
+ {...stylex.props(styles.visuallyHidden)}
+ >
+ {(data.pendingKey && pendingAnnouncements(data).get(data.pendingKey)) || ''}
+ </span>
+ );
+}
+
 /** The popover surface: header, workspace list, additional accounts, and footer. */
 export function UserButtonPopup(): ReactElement {
  return (

.changeset/mosaic-user-button-pending-announcement.md

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

packages/ui/src/mosaic/user-button/__tests__/user-button.view.test.tsx

@@ -513,7 +513,9 @@ describe('UserButtonView, the workspace list', () => {
  it('says so to a screen reader, since nothing else reports the rows landing', () => {
  renderList({ organizationsLoading: true });
 
- expect(screen.getByRole('status')).toHaveTextContent('Loading organizations…');
+ // The popup's own region speaks for the action a row is running, so the placeholder is asked
+ // for by its text: the two report different waits and are both on the page here.
+ expect(screen.getByText('Loading organizations…').closest('[role="status"]')).toBeInTheDocument();
  });
 
  it('leaves the account row above it alone, since it does not wait on the list', () => {
@@ -726,6 +728,48 @@ describe('UserButtonView, one action at a time', () => {
  expect(onSwitchSession).not.toHaveBeenCalled();
  expect(row).toHaveFocus();
  });
+
+ // The row keeps focus while it stands down, so nothing about the surface reports the wait on its
+ // own: the spinner is a picture, and `aria-disabled` says a row cannot be used rather than why.
+ // Named from the key, so the surface says what is running rather than that something is.
+ it.each([
+ [userButtonBusyKeys.selectOrganization('org_2'), 'Switching to Other Co', {}],
+ [userButtonBusyKeys.selectOrganization(null), 'Switching to Personal account', {}],
+ [userButtonBusyKeys.switchSession('sess_2'), 'Switching to bob@example.com', {}],
+ [userButtonBusyKeys.signOutSession('sess_2'), 'Signing out of bob@example.com', {}],
+ [userButtonBusyKeys.signOutAll(), 'Signing out of all accounts', {}],
+ [userButtonBusyKeys.acceptInvitation('inv_1'), 'Joining Gamma', { invitations: [gamma] }],
+ [userButtonBusyKeys.acceptSuggestion('sug_1'), 'Requesting to join Beta', { suggestions: [beta] }],
+ ])('names the wait in a live region: %s', (pendingKey, announcement, props) => {
+ render(surface(pendingKey, props));
+
+ expect(screen.getByRole('status')).toHaveTextContent(announcement);
+ });
+
+ // A region that mounts with its message already in it is not announced, so the popup carries an
+ // empty one from the moment it opens and the message lands in a region that is already there.
+ it('carries the region while idle', () => {
+ render(surface(null));
+
+ expect(screen.getByRole('status')).toBeEmptyDOMElement();
+ });
+
+ // Picking a workspace closes the popup behind it, so a region living in the popup would be taken
+ // off the page while it was still being read out. It belongs to the surface, which stays.
+ it('carries the region whether or not the popup is open', () => {
+ render(surface(userButtonBusyKeys.selectOrganization('org_2'), { defaultOpen: false }));
+
+ expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
+ expect(screen.getByRole('status')).toHaveTextContent('Switching to Other Co');
+ });
+
+ // A key can outlive what it names: an account signs out from its own row, and the row is gone
+ // before the action lands. The region says nothing rather than announcing a half-filled template.
+ it('says nothing for an action it cannot name', () => {
+ render(surface(userButtonBusyKeys.switchSession('sess_9')));
+
+ expect(screen.getByRole('status')).toBeEmptyDOMElement();
+ });
 });
 
 describe('UserButtonTrigger', () => {

packages/ui/src/mosaic/user-button/user-button.messages.ts

@@ -13,6 +13,14 @@ export const userButtonBase = {
  popup: {
  label: 'Account',
  },
+ // What the popup's live region says while an action runs, by the affordance that owns it.
+ status: {
+ switching: 'Switching to {name}',
+ signingOut: 'Signing out of {identifier}',
+ signingOutAll: 'Signing out of all accounts',
+ joining: 'Joining {name}',
+ requesting: 'Requesting to join {name}',
+ },
  workspaces: {
  personal: 'Personal account',
  loading: 'Loading organizations…',

packages/ui/src/mosaic/user-button/user-button.styles.ts

@@ -3,6 +3,17 @@ import * as stylex from '@stylexjs/stylex';
 import { colorVars, fontWeightVars, radiusVars, space, typeScaleVars } from '../tokens.stylex';
 
 export const styles = stylex.create({
+ // Takes the live region out of the layout without taking it out of the accessibility tree, which
+ // `display: none` and `visibility: hidden` both do.
+ visuallyHidden: {
+ overflow: 'hidden',
+ clipPath: 'inset(50%)',
+ position: 'absolute',
+ whiteSpace: 'nowrap',
+ height: '1px',
+ width: '1px',
+ },
+
  // The avatar is the trigger, so the button paints nothing of its own.
  trigger: {
  padding: 0,

packages/ui/src/mosaic/user-button/user-button.view.tsx

@@ -85,6 +85,48 @@ function useBusy(key?: string): { busy: boolean; disabled: boolean } {
  return { busy: pendingKey === key, disabled: pendingKey !== key };
 }
 
+/**
+ * What the surface says while an action runs, by the key that owns it. Keyed through
+ * `userButtonBusyKeys` rather than by parsing `pendingKey`, so the key grammar stays in one place,
+ * and built from the rows' own names so the announcement names the same thing the row does.
+ */
+function pendingAnnouncements(data: UserButtonContextValue): Map<string, string> {
+ const switching = (name: string) => fill(m.status.switching, { name });
+ const announcements = new Map<string, string>([
+ [userButtonBusyKeys.selectOrganization(null), switching(m.workspaces.personal)],
+ [userButtonBusyKeys.signOutAll(), m.status.signingOutAll],
+ ]);
+
+ // The active organization is described whole rather than found in `memberships`, so it is named
+ // here even while the list it belongs to is still loading.
+ for (const membership of data.activeOrganization
+ ? [data.activeOrganization, ...data.memberships]
+ : data.memberships) {
+ announcements.set(userButtonBusyKeys.selectOrganization(membership.organizationId), switching(membership.name));
+ }
+ // Accounts are named by identifier, the way their rows are.
+ for (const session of [data.activeSession, ...data.additionalSessions]) {
+ announcements.set(userButtonBusyKeys.switchSession(session.sessionId), switching(session.identifier));
+ announcements.set(
+ userButtonBusyKeys.signOutSession(session.sessionId),
+ fill(m.status.signingOut, { identifier: session.identifier }),
+ );
+ }
+ for (const invitation of data.invitations) {
+ announcements.set(
+ userButtonBusyKeys.acceptInvitation(invitation.id),
+ fill(m.status.joining, { name: invitation.organizationName }),
+ );
+ }
+ for (const suggestion of data.suggestions) {
+ announcements.set(
+ userButtonBusyKeys.acceptSuggestion(suggestion.id),
+ fill(m.status.requesting, { name: suggestion.name }),
+ );
+ }
+ return announcements;
+}
+
 interface ActiveWorkspace {
  name: string;
  imageUrl?: string;
@@ -937,7 +979,10 @@ export function UserButtonRoot(props: UserButtonRootProps): ReactElement {
  placement={placement ?? 'bottom-start'}
  sideOffset={sideOffset}
  >
- <UserButtonContext.Provider value={{ ...data, layout }}>{children}</UserButtonContext.Provider>
+ <UserButtonContext.Provider value={{ ...data, layout }}>
+ {children}
+ <ActionStatus />
+ </UserButtonContext.Provider>
  </Popover.Root>
  );
 }
@@ -989,6 +1034,28 @@ export function UserButtonTrigger({
  );
 }
 
+/**
+ * Speaks the one in-flight action. `pendingKey` allows a single action at a time, so the surface
+ * needs one region rather than one per affordance.
+ *
+ * It belongs to the surface rather than to the popup or the acting row, both of which go while the
+ * action is still running: picking a workspace closes the popup behind it, and a row leaves when the
+ * list re-sorts or an account signs out. A region taken off the page mid-announcement is not read.
+ */
+function ActionStatus(): ReactElement {
+ const data = useUserButtonContext();
+ // Mounted whether or not anything is running: a region that arrives with its message already in
+ // it is not announced, so the message has to land in a region that is already on the page.
+ return (
+ <span
+ role='status'
+ {...stylex.props(styles.visuallyHidden)}
+ >
+ {(data.pendingKey && pendingAnnouncements(data).get(data.pendingKey)) || ''}
+ </span>
+ );
+}
+
 /** The popover surface: header, workspace list, additional accounts, and footer. */
 export function UserButtonPopup(): ReactElement {
  return (

.changeset/mosaic-user-button-pending-announcement.md

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

packages/ui/src/mosaic/user-button/__tests__/user-button.view.test.tsx

@@ -513,7 +513,9 @@ describe('UserButtonView, the workspace list', () => {
  it('says so to a screen reader, since nothing else reports the rows landing', () => {
  renderList({ organizationsLoading: true });
 
- expect(screen.getByRole('status')).toHaveTextContent('Loading organizations…');
+ // The popup's own region speaks for the action a row is running, so the placeholder is asked
+ // for by its text: the two report different waits and are both on the page here.
+ expect(screen.getByText('Loading organizations…').closest('[role="status"]')).toBeInTheDocument();
  });
 
  it('leaves the account row above it alone, since it does not wait on the list', () => {
@@ -726,6 +728,48 @@ describe('UserButtonView, one action at a time', () => {
  expect(onSwitchSession).not.toHaveBeenCalled();
  expect(row).toHaveFocus();
  });
+
+ // The row keeps focus while it stands down, so nothing about the surface reports the wait on its
+ // own: the spinner is a picture, and `aria-disabled` says a row cannot be used rather than why.
+ // Named from the key, so the surface says what is running rather than that something is.
+ it.each([
+ [userButtonBusyKeys.selectOrganization('org_2'), 'Switching to Other Co', {}],
+ [userButtonBusyKeys.selectOrganization(null), 'Switching to Personal account', {}],
+ [userButtonBusyKeys.switchSession('sess_2'), 'Switching to bob@example.com', {}],
+ [userButtonBusyKeys.signOutSession('sess_2'), 'Signing out of bob@example.com', {}],
+ [userButtonBusyKeys.signOutAll(), 'Signing out of all accounts', {}],
+ [userButtonBusyKeys.acceptInvitation('inv_1'), 'Joining Gamma', { invitations: [gamma] }],
+ [userButtonBusyKeys.acceptSuggestion('sug_1'), 'Requesting to join Beta', { suggestions: [beta] }],
+ ])('names the wait in a live region: %s', (pendingKey, announcement, props) => {
+ render(surface(pendingKey, props));
+
+ expect(screen.getByRole('status')).toHaveTextContent(announcement);
+ });
+
+ // A region that mounts with its message already in it is not announced, so the popup carries an
+ // empty one from the moment it opens and the message lands in a region that is already there.
+ it('carries the region while idle', () => {
+ render(surface(null));
+
+ expect(screen.getByRole('status')).toBeEmptyDOMElement();
+ });
+
+ // Picking a workspace closes the popup behind it, so a region living in the popup would be taken
+ // off the page while it was still being read out. It belongs to the surface, which stays.
+ it('carries the region whether or not the popup is open', () => {
+ render(surface(userButtonBusyKeys.selectOrganization('org_2'), { defaultOpen: false }));
+
+ expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
+ expect(screen.getByRole('status')).toHaveTextContent('Switching to Other Co');
+ });
+
+ // A key can outlive what it names: an account signs out from its own row, and the row is gone
+ // before the action lands. The region says nothing rather than announcing a half-filled template.
+ it('says nothing for an action it cannot name', () => {
+ render(surface(userButtonBusyKeys.switchSession('sess_9')));
+
+ expect(screen.getByRole('status')).toBeEmptyDOMElement();
+ });
 });
 
 describe('UserButtonTrigger', () => {

packages/ui/src/mosaic/user-button/user-button.messages.ts

@@ -13,6 +13,14 @@ export const userButtonBase = {
  popup: {
  label: 'Account',
  },
+ // What the popup's live region says while an action runs, by the affordance that owns it.
+ status: {
+ switching: 'Switching to {name}',
+ signingOut: 'Signing out of {identifier}',
+ signingOutAll: 'Signing out of all accounts',
+ joining: 'Joining {name}',
+ requesting: 'Requesting to join {name}',
+ },
  workspaces: {
  personal: 'Personal account',
  loading: 'Loading organizations…',

packages/ui/src/mosaic/user-button/user-button.styles.ts

@@ -3,6 +3,17 @@ import * as stylex from '@stylexjs/stylex';
 import { colorVars, fontWeightVars, radiusVars, space, typeScaleVars } from '../tokens.stylex';
 
 export const styles = stylex.create({
+ // Takes the live region out of the layout without taking it out of the accessibility tree, which
+ // `display: none` and `visibility: hidden` both do.
+ visuallyHidden: {
+ overflow: 'hidden',
+ clipPath: 'inset(50%)',
+ position: 'absolute',
+ whiteSpace: 'nowrap',
+ height: '1px',
+ width: '1px',
+ },
+
  // The avatar is the trigger, so the button paints nothing of its own.
  trigger: {
  padding: 0,

packages/ui/src/mosaic/user-button/user-button.view.tsx

@@ -85,6 +85,48 @@ function useBusy(key?: string): { busy: boolean; disabled: boolean } {
  return { busy: pendingKey === key, disabled: pendingKey !== key };
 }
 
+/**
+ * What the surface says while an action runs, by the key that owns it. Keyed through
+ * `userButtonBusyKeys` rather than by parsing `pendingKey`, so the key grammar stays in one place,
+ * and built from the rows' own names so the announcement names the same thing the row does.
+ */
+function pendingAnnouncements(data: UserButtonContextValue): Map<string, string> {
+ const switching = (name: string) => fill(m.status.switching, { name });
+ const announcements = new Map<string, string>([
+ [userButtonBusyKeys.selectOrganization(null), switching(m.workspaces.personal)],
+ [userButtonBusyKeys.signOutAll(), m.status.signingOutAll],
+ ]);
+
+ // The active organization is described whole rather than found in `memberships`, so it is named
+ // here even while the list it belongs to is still loading.
+ for (const membership of data.activeOrganization
+ ? [data.activeOrganization, ...data.memberships]
+ : data.memberships) {
+ announcements.set(userButtonBusyKeys.selectOrganization(membership.organizationId), switching(membership.name));
+ }
+ // Accounts are named by identifier, the way their rows are.
+ for (const session of [data.activeSession, ...data.additionalSessions]) {
+ announcements.set(userButtonBusyKeys.switchSession(session.sessionId), switching(session.identifier));
+ announcements.set(
+ userButtonBusyKeys.signOutSession(session.sessionId),
+ fill(m.status.signingOut, { identifier: session.identifier }),
+ );
+ }
+ for (const invitation of data.invitations) {
+ announcements.set(
+ userButtonBusyKeys.acceptInvitation(invitation.id),
+ fill(m.status.joining, { name: invitation.organizationName }),
+ );
+ }
+ for (const suggestion of data.suggestions) {
+ announcements.set(
+ userButtonBusyKeys.acceptSuggestion(suggestion.id),
+ fill(m.status.requesting, { name: suggestion.name }),
+ );
+ }
+ return announcements;
+}
+
 interface ActiveWorkspace {
  name: string;
  imageUrl?: string;
@@ -937,7 +979,10 @@ export function UserButtonRoot(props: UserButtonRootProps): ReactElement {
  placement={placement ?? 'bottom-start'}
  sideOffset={sideOffset}
  >
- <UserButtonContext.Provider value={{ ...data, layout }}>{children}</UserButtonContext.Provider>
+ <UserButtonContext.Provider value={{ ...data, layout }}>
+ {children}
+ <ActionStatus />
+ </UserButtonContext.Provider>
  </Popover.Root>
  );
 }
@@ -989,6 +1034,28 @@ export function UserButtonTrigger({
  );
 }
 
+/**
+ * Speaks the one in-flight action. `pendingKey` allows a single action at a time, so the surface
+ * needs one region rather than one per affordance.
+ *
+ * It belongs to the surface rather than to the popup or the acting row, both of which go while the
+ * action is still running: picking a workspace closes the popup behind it, and a row leaves when the
+ * list re-sorts or an account signs out. A region taken off the page mid-announcement is not read.
+ */
+function ActionStatus(): ReactElement {
+ const data = useUserButtonContext();
+ // Mounted whether or not anything is running: a region that arrives with its message already in
+ // it is not announced, so the message has to land in a region that is already on the page.
+ return (
+ <span
+ role='status'
+ {...stylex.props(styles.visuallyHidden)}
+ >
+ {(data.pendingKey && pendingAnnouncements(data).get(data.pendingKey)) || ''}
+ </span>
+ );
+}
+
 /** The popover surface: header, workspace list, additional accounts, and footer. */
 export function UserButtonPopup(): ReactElement {
  return (

.changeset/mosaic-user-button-pending-announcement.md

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

packages/ui/src/mosaic/user-button/__tests__/user-button.view.test.tsx

@@ -513,7 +513,9 @@ describe('UserButtonView, the workspace list', () => {
  it('says so to a screen reader, since nothing else reports the rows landing', () => {
  renderList({ organizationsLoading: true });
 
- expect(screen.getByRole('status')).toHaveTextContent('Loading organizations…');
+ // The popup's own region speaks for the action a row is running, so the placeholder is asked
+ // for by its text: the two report different waits and are both on the page here.
+ expect(screen.getByText('Loading organizations…').closest('[role="status"]')).toBeInTheDocument();
  });
 
  it('leaves the account row above it alone, since it does not wait on the list', () => {
@@ -726,6 +728,48 @@ describe('UserButtonView, one action at a time', () => {
  expect(onSwitchSession).not.toHaveBeenCalled();
  expect(row).toHaveFocus();
  });
+
+ // The row keeps focus while it stands down, so nothing about the surface reports the wait on its
+ // own: the spinner is a picture, and `aria-disabled` says a row cannot be used rather than why.
+ // Named from the key, so the surface says what is running rather than that something is.
+ it.each([
+ [userButtonBusyKeys.selectOrganization('org_2'), 'Switching to Other Co', {}],
+ [userButtonBusyKeys.selectOrganization(null), 'Switching to Personal account', {}],
+ [userButtonBusyKeys.switchSession('sess_2'), 'Switching to bob@example.com', {}],
+ [userButtonBusyKeys.signOutSession('sess_2'), 'Signing out of bob@example.com', {}],
+ [userButtonBusyKeys.signOutAll(), 'Signing out of all accounts', {}],
+ [userButtonBusyKeys.acceptInvitation('inv_1'), 'Joining Gamma', { invitations: [gamma] }],
+ [userButtonBusyKeys.acceptSuggestion('sug_1'), 'Requesting to join Beta', { suggestions: [beta] }],
+ ])('names the wait in a live region: %s', (pendingKey, announcement, props) => {
+ render(surface(pendingKey, props));
+
+ expect(screen.getByRole('status')).toHaveTextContent(announcement);
+ });
+
+ // A region that mounts with its message already in it is not announced, so the popup carries an
+ // empty one from the moment it opens and the message lands in a region that is already there.
+ it('carries the region while idle', () => {
+ render(surface(null));
+
+ expect(screen.getByRole('status')).toBeEmptyDOMElement();
+ });
+
+ // Picking a workspace closes the popup behind it, so a region living in the popup would be taken
+ // off the page while it was still being read out. It belongs to the surface, which stays.
+ it('carries the region whether or not the popup is open', () => {
+ render(surface(userButtonBusyKeys.selectOrganization('org_2'), { defaultOpen: false }));
+
+ expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
+ expect(screen.getByRole('status')).toHaveTextContent('Switching to Other Co');
+ });
+
+ // A key can outlive what it names: an account signs out from its own row, and the row is gone
+ // before the action lands. The region says nothing rather than announcing a half-filled template.
+ it('says nothing for an action it cannot name', () => {
+ render(surface(userButtonBusyKeys.switchSession('sess_9')));
+
+ expect(screen.getByRole('status')).toBeEmptyDOMElement();
+ });
 });
 
 describe('UserButtonTrigger', () => {

packages/ui/src/mosaic/user-button/user-button.messages.ts

@@ -13,6 +13,14 @@ export const userButtonBase = {
  popup: {
  label: 'Account',
  },
+ // What the popup's live region says while an action runs, by the affordance that owns it.
+ status: {
+ switching: 'Switching to {name}',
+ signingOut: 'Signing out of {identifier}',
+ signingOutAll: 'Signing out of all accounts',
+ joining: 'Joining {name}',
+ requesting: 'Requesting to join {name}',
+ },
  workspaces: {
  personal: 'Personal account',
  loading: 'Loading organizations…',

packages/ui/src/mosaic/user-button/user-button.styles.ts

@@ -3,6 +3,17 @@ import * as stylex from '@stylexjs/stylex';
 import { colorVars, fontWeightVars, radiusVars, space, typeScaleVars } from '../tokens.stylex';
 
 export const styles = stylex.create({
+ // Takes the live region out of the layout without taking it out of the accessibility tree, which
+ // `display: none` and `visibility: hidden` both do.
+ visuallyHidden: {
+ overflow: 'hidden',
+ clipPath: 'inset(50%)',
+ position: 'absolute',
+ whiteSpace: 'nowrap',
+ height: '1px',
+ width: '1px',
+ },
+
  // The avatar is the trigger, so the button paints nothing of its own.
  trigger: {
  padding: 0,

packages/ui/src/mosaic/user-button/user-button.view.tsx

@@ -85,6 +85,48 @@ function useBusy(key?: string): { busy: boolean; disabled: boolean } {
  return { busy: pendingKey === key, disabled: pendingKey !== key };
 }
 
+/**
+ * What the surface says while an action runs, by the key that owns it. Keyed through
+ * `userButtonBusyKeys` rather than by parsing `pendingKey`, so the key grammar stays in one place,
+ * and built from the rows' own names so the announcement names the same thing the row does.
+ */
+function pendingAnnouncements(data: UserButtonContextValue): Map<string, string> {
+ const switching = (name: string) => fill(m.status.switching, { name });
+ const announcements = new Map<string, string>([
+ [userButtonBusyKeys.selectOrganization(null), switching(m.workspaces.personal)],
+ [userButtonBusyKeys.signOutAll(), m.status.signingOutAll],
+ ]);
+
+ // The active organization is described whole rather than found in `memberships`, so it is named
+ // here even while the list it belongs to is still loading.
+ for (const membership of data.activeOrganization
+ ? [data.activeOrganization, ...data.memberships]
+ : data.memberships) {
+ announcements.set(userButtonBusyKeys.selectOrganization(membership.organizationId), switching(membership.name));
+ }
+ // Accounts are named by identifier, the way their rows are.
+ for (const session of [data.activeSession, ...data.additionalSessions]) {
+ announcements.set(userButtonBusyKeys.switchSession(session.sessionId), switching(session.identifier));
+ announcements.set(
+ userButtonBusyKeys.signOutSession(session.sessionId),
+ fill(m.status.signingOut, { identifier: session.identifier }),
+ );
+ }
+ for (const invitation of data.invitations) {
+ announcements.set(
+ userButtonBusyKeys.acceptInvitation(invitation.id),
+ fill(m.status.joining, { name: invitation.organizationName }),
+ );
+ }
+ for (const suggestion of data.suggestions) {
+ announcements.set(
+ userButtonBusyKeys.acceptSuggestion(suggestion.id),
+ fill(m.status.requesting, { name: suggestion.name }),
+ );
+ }
+ return announcements;
+}
+
 interface ActiveWorkspace {
  name: string;
  imageUrl?: string;
@@ -937,7 +979,10 @@ export function UserButtonRoot(props: UserButtonRootProps): ReactElement {
  placement={placement ?? 'bottom-start'}
  sideOffset={sideOffset}
  >
- <UserButtonContext.Provider value={{ ...data, layout }}>{children}</UserButtonContext.Provider>
+ <UserButtonContext.Provider value={{ ...data, layout }}>
+ {children}
+ <ActionStatus />
+ </UserButtonContext.Provider>
  </Popover.Root>
  );
 }
@@ -989,6 +1034,28 @@ export function UserButtonTrigger({
  );
 }
 
+/**
+ * Speaks the one in-flight action. `pendingKey` allows a single action at a time, so the surface
+ * needs one region rather than one per affordance.
+ *
+ * It belongs to the surface rather than to the popup or the acting row, both of which go while the
+ * action is still running: picking a workspace closes the popup behind it, and a row leaves when the
+ * list re-sorts or an account signs out. A region taken off the page mid-announcement is not read.
+ */
+function ActionStatus(): ReactElement {
+ const data = useUserButtonContext();
+ // Mounted whether or not anything is running: a region that arrives with its message already in
+ // it is not announced, so the message has to land in a region that is already on the page.
+ return (
+ <span
+ role='status'
+ {...stylex.props(styles.visuallyHidden)}
+ >
+ {(data.pendingKey && pendingAnnouncements(data).get(data.pendingKey)) || ''}
+ </span>
+ );
+}
+
 /** The popover surface: header, workspace list, additional accounts, and footer. */
 export function UserButtonPopup(): ReactElement {
  return (

.changeset/mosaic-user-button-pending-announcement.md

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

packages/ui/src/mosaic/user-button/__tests__/user-button.view.test.tsx

@@ -513,7 +513,9 @@ describe('UserButtonView, the workspace list', () => {
  it('says so to a screen reader, since nothing else reports the rows landing', () => {
  renderList({ organizationsLoading: true });
 
- expect(screen.getByRole('status')).toHaveTextContent('Loading organizations…');
+ // The popup's own region speaks for the action a row is running, so the placeholder is asked
+ // for by its text: the two report different waits and are both on the page here.
+ expect(screen.getByText('Loading organizations…').closest('[role="status"]')).toBeInTheDocument();
  });
 
  it('leaves the account row above it alone, since it does not wait on the list', () => {
@@ -726,6 +728,48 @@ describe('UserButtonView, one action at a time', () => {
  expect(onSwitchSession).not.toHaveBeenCalled();
  expect(row).toHaveFocus();
  });
+
+ // The row keeps focus while it stands down, so nothing about the surface reports the wait on its
+ // own: the spinner is a picture, and `aria-disabled` says a row cannot be used rather than why.
+ // Named from the key, so the surface says what is running rather than that something is.
+ it.each([
+ [userButtonBusyKeys.selectOrganization('org_2'), 'Switching to Other Co', {}],
+ [userButtonBusyKeys.selectOrganization(null), 'Switching to Personal account', {}],
+ [userButtonBusyKeys.switchSession('sess_2'), 'Switching to bob@example.com', {}],
+ [userButtonBusyKeys.signOutSession('sess_2'), 'Signing out of bob@example.com', {}],
+ [userButtonBusyKeys.signOutAll(), 'Signing out of all accounts', {}],
+ [userButtonBusyKeys.acceptInvitation('inv_1'), 'Joining Gamma', { invitations: [gamma] }],
+ [userButtonBusyKeys.acceptSuggestion('sug_1'), 'Requesting to join Beta', { suggestions: [beta] }],
+ ])('names the wait in a live region: %s', (pendingKey, announcement, props) => {
+ render(surface(pendingKey, props));
+
+ expect(screen.getByRole('status')).toHaveTextContent(announcement);
+ });
+
+ // A region that mounts with its message already in it is not announced, so the popup carries an
+ // empty one from the moment it opens and the message lands in a region that is already there.
+ it('carries the region while idle', () => {
+ render(surface(null));
+
+ expect(screen.getByRole('status')).toBeEmptyDOMElement();
+ });
+
+ // Picking a workspace closes the popup behind it, so a region living in the popup would be taken
+ // off the page while it was still being read out. It belongs to the surface, which stays.
+ it('carries the region whether or not the popup is open', () => {
+ render(surface(userButtonBusyKeys.selectOrganization('org_2'), { defaultOpen: false }));
+
+ expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
+ expect(screen.getByRole('status')).toHaveTextContent('Switching to Other Co');
+ });
+
+ // A key can outlive what it names: an account signs out from its own row, and the row is gone
+ // before the action lands. The region says nothing rather than announcing a half-filled template.
+ it('says nothing for an action it cannot name', () => {
+ render(surface(userButtonBusyKeys.switchSession('sess_9')));
+
+ expect(screen.getByRole('status')).toBeEmptyDOMElement();
+ });
 });
 
 describe('UserButtonTrigger', () => {

packages/ui/src/mosaic/user-button/user-button.messages.ts

@@ -13,6 +13,14 @@ export const userButtonBase = {
  popup: {
  label: 'Account',
  },
+ // What the popup's live region says while an action runs, by the affordance that owns it.
+ status: {
+ switching: 'Switching to {name}',
+ signingOut: 'Signing out of {identifier}',
+ signingOutAll: 'Signing out of all accounts',
+ joining: 'Joining {name}',
+ requesting: 'Requesting to join {name}',
+ },
  workspaces: {
  personal: 'Personal account',
  loading: 'Loading organizations…',

packages/ui/src/mosaic/user-button/user-button.styles.ts

@@ -3,6 +3,17 @@ import * as stylex from '@stylexjs/stylex';
 import { colorVars, fontWeightVars, radiusVars, space, typeScaleVars } from '../tokens.stylex';
 
 export const styles = stylex.create({
+ // Takes the live region out of the layout without taking it out of the accessibility tree, which
+ // `display: none` and `visibility: hidden` both do.
+ visuallyHidden: {
+ overflow: 'hidden',
+ clipPath: 'inset(50%)',
+ position: 'absolute',
+ whiteSpace: 'nowrap',
+ height: '1px',
+ width: '1px',
+ },
+
  // The avatar is the trigger, so the button paints nothing of its own.
  trigger: {
  padding: 0,

packages/ui/src/mosaic/user-button/user-button.view.tsx

@@ -85,6 +85,48 @@ function useBusy(key?: string): { busy: boolean; disabled: boolean } {
  return { busy: pendingKey === key, disabled: pendingKey !== key };
 }
 
+/**
+ * What the surface says while an action runs, by the key that owns it. Keyed through
+ * `userButtonBusyKeys` rather than by parsing `pendingKey`, so the key grammar stays in one place,
+ * and built from the rows' own names so the announcement names the same thing the row does.
+ */
+function pendingAnnouncements(data: UserButtonContextValue): Map<string, string> {
+ const switching = (name: string) => fill(m.status.switching, { name });
+ const announcements = new Map<string, string>([
+ [userButtonBusyKeys.selectOrganization(null), switching(m.workspaces.personal)],
+ [userButtonBusyKeys.signOutAll(), m.status.signingOutAll],
+ ]);
+
+ // The active organization is described whole rather than found in `memberships`, so it is named
+ // here even while the list it belongs to is still loading.
+ for (const membership of data.activeOrganization
+ ? [data.activeOrganization, ...data.memberships]
+ : data.memberships) {
+ announcements.set(userButtonBusyKeys.selectOrganization(membership.organizationId), switching(membership.name));
+ }
+ // Accounts are named by identifier, the way their rows are.
+ for (const session of [data.activeSession, ...data.additionalSessions]) {
+ announcements.set(userButtonBusyKeys.switchSession(session.sessionId), switching(session.identifier));
+ announcements.set(
+ userButtonBusyKeys.signOutSession(session.sessionId),
+ fill(m.status.signingOut, { identifier: session.identifier }),
+ );
+ }
+ for (const invitation of data.invitations) {
+ announcements.set(
+ userButtonBusyKeys.acceptInvitation(invitation.id),
+ fill(m.status.joining, { name: invitation.organizationName }),
+ );
+ }
+ for (const suggestion of data.suggestions) {
+ announcements.set(
+ userButtonBusyKeys.acceptSuggestion(suggestion.id),
+ fill(m.status.requesting, { name: suggestion.name }),
+ );
+ }
+ return announcements;
+}
+
 interface ActiveWorkspace {
  name: string;
  imageUrl?: string;
@@ -937,7 +979,10 @@ export function UserButtonRoot(props: UserButtonRootProps): ReactElement {
  placement={placement ?? 'bottom-start'}
  sideOffset={sideOffset}
  >
- <UserButtonContext.Provider value={{ ...data, layout }}>{children}</UserButtonContext.Provider>
+ <UserButtonContext.Provider value={{ ...data, layout }}>
+ {children}
+ <ActionStatus />
+ </UserButtonContext.Provider>
  </Popover.Root>
  );
 }
@@ -989,6 +1034,28 @@ export function UserButtonTrigger({
  );
 }
 
+/**
+ * Speaks the one in-flight action. `pendingKey` allows a single action at a time, so the surface
+ * needs one region rather than one per affordance.
+ *
+ * It belongs to the surface rather than to the popup or the acting row, both of which go while the
+ * action is still running: picking a workspace closes the popup behind it, and a row leaves when the
+ * list re-sorts or an account signs out. A region taken off the page mid-announcement is not read.
+ */
+function ActionStatus(): ReactElement {
+ const data = useUserButtonContext();
+ // Mounted whether or not anything is running: a region that arrives with its message already in
+ // it is not announced, so the message has to land in a region that is already on the page.
+ return (
+ <span
+ role='status'
+ {...stylex.props(styles.visuallyHidden)}
+ >
+ {(data.pendingKey && pendingAnnouncements(data).get(data.pendingKey)) || ''}
+ </span>
+ );
+}
+
 /** The popover surface: header, workspace list, additional accounts, and footer. */
 export function UserButtonPopup(): ReactElement {
  return (

.changeset/mosaic-user-button-pending-announcement.md

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

packages/ui/src/mosaic/user-button/__tests__/user-button.view.test.tsx

@@ -513,7 +513,9 @@ describe('UserButtonView, the workspace list', () => {
  it('says so to a screen reader, since nothing else reports the rows landing', () => {
  renderList({ organizationsLoading: true });
 
- expect(screen.getByRole('status')).toHaveTextContent('Loading organizations…');
+ // The popup's own region speaks for the action a row is running, so the placeholder is asked
+ // for by its text: the two report different waits and are both on the page here.
+ expect(screen.getByText('Loading organizations…').closest('[role="status"]')).toBeInTheDocument();
  });
 
  it('leaves the account row above it alone, since it does not wait on the list', () => {
@@ -726,6 +728,48 @@ describe('UserButtonView, one action at a time', () => {
  expect(onSwitchSession).not.toHaveBeenCalled();
  expect(row).toHaveFocus();
  });
+
+ // The row keeps focus while it stands down, so nothing about the surface reports the wait on its
+ // own: the spinner is a picture, and `aria-disabled` says a row cannot be used rather than why.
+ // Named from the key, so the surface says what is running rather than that something is.
+ it.each([
+ [userButtonBusyKeys.selectOrganization('org_2'), 'Switching to Other Co', {}],
+ [userButtonBusyKeys.selectOrganization(null), 'Switching to Personal account', {}],
+ [userButtonBusyKeys.switchSession('sess_2'), 'Switching to bob@example.com', {}],
+ [userButtonBusyKeys.signOutSession('sess_2'), 'Signing out of bob@example.com', {}],
+ [userButtonBusyKeys.signOutAll(), 'Signing out of all accounts', {}],
+ [userButtonBusyKeys.acceptInvitation('inv_1'), 'Joining Gamma', { invitations: [gamma] }],
+ [userButtonBusyKeys.acceptSuggestion('sug_1'), 'Requesting to join Beta', { suggestions: [beta] }],
+ ])('names the wait in a live region: %s', (pendingKey, announcement, props) => {
+ render(surface(pendingKey, props));
+
+ expect(screen.getByRole('status')).toHaveTextContent(announcement);
+ });
+
+ // A region that mounts with its message already in it is not announced, so the popup carries an
+ // empty one from the moment it opens and the message lands in a region that is already there.
+ it('carries the region while idle', () => {
+ render(surface(null));
+
+ expect(screen.getByRole('status')).toBeEmptyDOMElement();
+ });
+
+ // Picking a workspace closes the popup behind it, so a region living in the popup would be taken
+ // off the page while it was still being read out. It belongs to the surface, which stays.
+ it('carries the region whether or not the popup is open', () => {
+ render(surface(userButtonBusyKeys.selectOrganization('org_2'), { defaultOpen: false }));
+
+ expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
+ expect(screen.getByRole('status')).toHaveTextContent('Switching to Other Co');
+ });
+
+ // A key can outlive what it names: an account signs out from its own row, and the row is gone
+ // before the action lands. The region says nothing rather than announcing a half-filled template.
+ it('says nothing for an action it cannot name', () => {
+ render(surface(userButtonBusyKeys.switchSession('sess_9')));
+
+ expect(screen.getByRole('status')).toBeEmptyDOMElement();
+ });
 });
 
 describe('UserButtonTrigger', () => {

packages/ui/src/mosaic/user-button/user-button.messages.ts

@@ -13,6 +13,14 @@ export const userButtonBase = {
  popup: {
  label: 'Account',
  },
+ // What the popup's live region says while an action runs, by the affordance that owns it.
+ status: {
+ switching: 'Switching to {name}',
+ signingOut: 'Signing out of {identifier}',
+ signingOutAll: 'Signing out of all accounts',
+ joining: 'Joining {name}',
+ requesting: 'Requesting to join {name}',
+ },
  workspaces: {
  personal: 'Personal account',
  loading: 'Loading organizations…',

packages/ui/src/mosaic/user-button/user-button.styles.ts

@@ -3,6 +3,17 @@ import * as stylex from '@stylexjs/stylex';
 import { colorVars, fontWeightVars, radiusVars, space, typeScaleVars } from '../tokens.stylex';
 
 export const styles = stylex.create({
+ // Takes the live region out of the layout without taking it out of the accessibility tree, which
+ // `display: none` and `visibility: hidden` both do.
+ visuallyHidden: {
+ overflow: 'hidden',
+ clipPath: 'inset(50%)',
+ position: 'absolute',
+ whiteSpace: 'nowrap',
+ height: '1px',
+ width: '1px',
+ },
+
  // The avatar is the trigger, so the button paints nothing of its own.
  trigger: {
  padding: 0,

packages/ui/src/mosaic/user-button/user-button.view.tsx

@@ -85,6 +85,48 @@ function useBusy(key?: string): { busy: boolean; disabled: boolean } {
  return { busy: pendingKey === key, disabled: pendingKey !== key };
 }
 
+/**
+ * What the surface says while an action runs, by the key that owns it. Keyed through
+ * `userButtonBusyKeys` rather than by parsing `pendingKey`, so the key grammar stays in one place,
+ * and built from the rows' own names so the announcement names the same thing the row does.
+ */
+function pendingAnnouncements(data: UserButtonContextValue): Map<string, string> {
+ const switching = (name: string) => fill(m.status.switching, { name });
+ const announcements = new Map<string, string>([
+ [userButtonBusyKeys.selectOrganization(null), switching(m.workspaces.personal)],
+ [userButtonBusyKeys.signOutAll(), m.status.signingOutAll],
+ ]);
+
+ // The active organization is described whole rather than found in `memberships`, so it is named
+ // here even while the list it belongs to is still loading.
+ for (const membership of data.activeOrganization
+ ? [data.activeOrganization, ...data.memberships]
+ : data.memberships) {
+ announcements.set(userButtonBusyKeys.selectOrganization(membership.organizationId), switching(membership.name));
+ }
+ // Accounts are named by identifier, the way their rows are.
+ for (const session of [data.activeSession, ...data.additionalSessions]) {
+ announcements.set(userButtonBusyKeys.switchSession(session.sessionId), switching(session.identifier));
+ announcements.set(
+ userButtonBusyKeys.signOutSession(session.sessionId),
+ fill(m.status.signingOut, { identifier: session.identifier }),
+ );
+ }
+ for (const invitation of data.invitations) {
+ announcements.set(
+ userButtonBusyKeys.acceptInvitation(invitation.id),
+ fill(m.status.joining, { name: invitation.organizationName }),
+ );
+ }
+ for (const suggestion of data.suggestions) {
+ announcements.set(
+ userButtonBusyKeys.acceptSuggestion(suggestion.id),
+ fill(m.status.requesting, { name: suggestion.name }),
+ );
+ }
+ return announcements;
+}
+
 interface ActiveWorkspace {
  name: string;
  imageUrl?: string;
@@ -937,7 +979,10 @@ export function UserButtonRoot(props: UserButtonRootProps): ReactElement {
  placement={placement ?? 'bottom-start'}
  sideOffset={sideOffset}
  >
- <UserButtonContext.Provider value={{ ...data, layout }}>{children}</UserButtonContext.Provider>
+ <UserButtonContext.Provider value={{ ...data, layout }}>
+ {children}
+ <ActionStatus />
+ </UserButtonContext.Provider>
  </Popover.Root>
  );
 }
@@ -989,6 +1034,28 @@ export function UserButtonTrigger({
  );
 }
 
+/**
+ * Speaks the one in-flight action. `pendingKey` allows a single action at a time, so the surface
+ * needs one region rather than one per affordance.
+ *
+ * It belongs to the surface rather than to the popup or the acting row, both of which go while the
+ * action is still running: picking a workspace closes the popup behind it, and a row leaves when the
+ * list re-sorts or an account signs out. A region taken off the page mid-announcement is not read.
+ */
+function ActionStatus(): ReactElement {
+ const data = useUserButtonContext();
+ // Mounted whether or not anything is running: a region that arrives with its message already in
+ // it is not announced, so the message has to land in a region that is already on the page.
+ return (
+ <span
+ role='status'
+ {...stylex.props(styles.visuallyHidden)}
+ >
+ {(data.pendingKey && pendingAnnouncements(data).get(data.pendingKey)) || ''}
+ </span>
+ );
+}
+
 /** The popover surface: header, workspace list, additional accounts, and footer. */
 export function UserButtonPopup(): ReactElement {
  return (

.changeset/mosaic-user-button-pending-announcement.md

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

packages/ui/src/mosaic/user-button/__tests__/user-button.view.test.tsx

@@ -513,7 +513,9 @@ describe('UserButtonView, the workspace list', () => {
  it('says so to a screen reader, since nothing else reports the rows landing', () => {
  renderList({ organizationsLoading: true });
 
- expect(screen.getByRole('status')).toHaveTextContent('Loading organizations…');
+ // The popup's own region speaks for the action a row is running, so the placeholder is asked
+ // for by its text: the two report different waits and are both on the page here.
+ expect(screen.getByText('Loading organizations…').closest('[role="status"]')).toBeInTheDocument();
  });
 
  it('leaves the account row above it alone, since it does not wait on the list', () => {
@@ -726,6 +728,48 @@ describe('UserButtonView, one action at a time', () => {
  expect(onSwitchSession).not.toHaveBeenCalled();
  expect(row).toHaveFocus();
  });
+
+ // The row keeps focus while it stands down, so nothing about the surface reports the wait on its
+ // own: the spinner is a picture, and `aria-disabled` says a row cannot be used rather than why.
+ // Named from the key, so the surface says what is running rather than that something is.
+ it.each([
+ [userButtonBusyKeys.selectOrganization('org_2'), 'Switching to Other Co', {}],
+ [userButtonBusyKeys.selectOrganization(null), 'Switching to Personal account', {}],
+ [userButtonBusyKeys.switchSession('sess_2'), 'Switching to bob@example.com', {}],
+ [userButtonBusyKeys.signOutSession('sess_2'), 'Signing out of bob@example.com', {}],
+ [userButtonBusyKeys.signOutAll(), 'Signing out of all accounts', {}],
+ [userButtonBusyKeys.acceptInvitation('inv_1'), 'Joining Gamma', { invitations: [gamma] }],
+ [userButtonBusyKeys.acceptSuggestion('sug_1'), 'Requesting to join Beta', { suggestions: [beta] }],
+ ])('names the wait in a live region: %s', (pendingKey, announcement, props) => {
+ render(surface(pendingKey, props));
+
+ expect(screen.getByRole('status')).toHaveTextContent(announcement);
+ });
+
+ // A region that mounts with its message already in it is not announced, so the popup carries an
+ // empty one from the moment it opens and the message lands in a region that is already there.
+ it('carries the region while idle', () => {
+ render(surface(null));
+
+ expect(screen.getByRole('status')).toBeEmptyDOMElement();
+ });
+
+ // Picking a workspace closes the popup behind it, so a region living in the popup would be taken
+ // off the page while it was still being read out. It belongs to the surface, which stays.
+ it('carries the region whether or not the popup is open', () => {
+ render(surface(userButtonBusyKeys.selectOrganization('org_2'), { defaultOpen: false }));
+
+ expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
+ expect(screen.getByRole('status')).toHaveTextContent('Switching to Other Co');
+ });
+
+ // A key can outlive what it names: an account signs out from its own row, and the row is gone
+ // before the action lands. The region says nothing rather than announcing a half-filled template.
+ it('says nothing for an action it cannot name', () => {
+ render(surface(userButtonBusyKeys.switchSession('sess_9')));
+
+ expect(screen.getByRole('status')).toBeEmptyDOMElement();
+ });
 });
 
 describe('UserButtonTrigger', () => {

packages/ui/src/mosaic/user-button/user-button.messages.ts

@@ -13,6 +13,14 @@ export const userButtonBase = {
  popup: {
  label: 'Account',
  },
+ // What the popup's live region says while an action runs, by the affordance that owns it.
+ status: {
+ switching: 'Switching to {name}',
+ signingOut: 'Signing out of {identifier}',
+ signingOutAll: 'Signing out of all accounts',
+ joining: 'Joining {name}',
+ requesting: 'Requesting to join {name}',
+ },
  workspaces: {
  personal: 'Personal account',
  loading: 'Loading organizations…',

packages/ui/src/mosaic/user-button/user-button.styles.ts

@@ -3,6 +3,17 @@ import * as stylex from '@stylexjs/stylex';
 import { colorVars, fontWeightVars, radiusVars, space, typeScaleVars } from '../tokens.stylex';
 
 export const styles = stylex.create({
+ // Takes the live region out of the layout without taking it out of the accessibility tree, which
+ // `display: none` and `visibility: hidden` both do.
+ visuallyHidden: {
+ overflow: 'hidden',
+ clipPath: 'inset(50%)',
+ position: 'absolute',
+ whiteSpace: 'nowrap',
+ height: '1px',
+ width: '1px',
+ },
+
  // The avatar is the trigger, so the button paints nothing of its own.
  trigger: {
  padding: 0,

packages/ui/src/mosaic/user-button/user-button.view.tsx

@@ -85,6 +85,48 @@ function useBusy(key?: string): { busy: boolean; disabled: boolean } {
  return { busy: pendingKey === key, disabled: pendingKey !== key };
 }
 
+/**
+ * What the surface says while an action runs, by the key that owns it. Keyed through
+ * `userButtonBusyKeys` rather than by parsing `pendingKey`, so the key grammar stays in one place,
+ * and built from the rows' own names so the announcement names the same thing the row does.
+ */
+function pendingAnnouncements(data: UserButtonContextValue): Map<string, string> {
+ const switching = (name: string) => fill(m.status.switching, { name });
+ const announcements = new Map<string, string>([
+ [userButtonBusyKeys.selectOrganization(null), switching(m.workspaces.personal)],
+ [userButtonBusyKeys.signOutAll(), m.status.signingOutAll],
+ ]);
+
+ // The active organization is described whole rather than found in `memberships`, so it is named
+ // here even while the list it belongs to is still loading.
+ for (const membership of data.activeOrganization
+ ? [data.activeOrganization, ...data.memberships]
+ : data.memberships) {
+ announcements.set(userButtonBusyKeys.selectOrganization(membership.organizationId), switching(membership.name));
+ }
+ // Accounts are named by identifier, the way their rows are.
+ for (const session of [data.activeSession, ...data.additionalSessions]) {
+ announcements.set(userButtonBusyKeys.switchSession(session.sessionId), switching(session.identifier));
+ announcements.set(
+ userButtonBusyKeys.signOutSession(session.sessionId),
+ fill(m.status.signingOut, { identifier: session.identifier }),
+ );
+ }
+ for (const invitation of data.invitations) {
+ announcements.set(
+ userButtonBusyKeys.acceptInvitation(invitation.id),
+ fill(m.status.joining, { name: invitation.organizationName }),
+ );
+ }
+ for (const suggestion of data.suggestions) {
+ announcements.set(
+ userButtonBusyKeys.acceptSuggestion(suggestion.id),
+ fill(m.status.requesting, { name: suggestion.name }),
+ );
+ }
+ return announcements;
+}
+
 interface ActiveWorkspace {
  name: string;
  imageUrl?: string;
@@ -937,7 +979,10 @@ export function UserButtonRoot(props: UserButtonRootProps): ReactElement {
  placement={placement ?? 'bottom-start'}
  sideOffset={sideOffset}
  >
- <UserButtonContext.Provider value={{ ...data, layout }}>{children}</UserButtonContext.Provider>
+ <UserButtonContext.Provider value={{ ...data, layout }}>
+ {children}
+ <ActionStatus />
+ </UserButtonContext.Provider>
  </Popover.Root>
  );
 }
@@ -989,6 +1034,28 @@ export function UserButtonTrigger({
  );
 }
 
+/**
+ * Speaks the one in-flight action. `pendingKey` allows a single action at a time, so the surface
+ * needs one region rather than one per affordance.
+ *
+ * It belongs to the surface rather than to the popup or the acting row, both of which go while the
+ * action is still running: picking a workspace closes the popup behind it, and a row leaves when the
+ * list re-sorts or an account signs out. A region taken off the page mid-announcement is not read.
+ */
+function ActionStatus(): ReactElement {
+ const data = useUserButtonContext();
+ // Mounted whether or not anything is running: a region that arrives with its message already in
+ // it is not announced, so the message has to land in a region that is already on the page.
+ return (
+ <span
+ role='status'
+ {...stylex.props(styles.visuallyHidden)}
+ >
+ {(data.pendingKey && pendingAnnouncements(data).get(data.pendingKey)) || ''}
+ </span>
+ );
+}
+
 /** The popover surface: header, workspace list, additional accounts, and footer. */
 export function UserButtonPopup(): ReactElement {
  return (