App Switcher

Vertical Wave AppBar for jumping between Volue applications, with a settings popover to reorder and hide entries. Built on @volue/wave-react; drops into any Wave-enabled React host.

Wire contract

The bar is fed by two customer-portal-service (portal-api) endpoints:

| Endpoint | Purpose | | ------------------------------- | ---------------------------------------------------------------- | | GET /me/applications | { applications: Application[], settings: AppSettings \| null } | | PUT /me/applications/settings | Body { order: string[], hidden: string[] }, answers 204 |

Both take an optional X-Selected-Tenant-Id header that scopes access and the saved arrangement to one tenant. Both require a Volue Identity bearer token. The package never handles auth: pass a fetchImpl that attaches the token, or point the URLs at a same-origin BFF that does (the portal does the latter, see src/app/api/me/applications).

The server orders the list by the saved order; the client applies hidden (applySettings), because access-hidden and user-hidden are separate facts on the wire.

Quick start

import { AppSwitcher, useApplications } from '@volue/app-switcher';

function Bar() {
  const { state, saveApplications } = useApplications({
    applicationsUrl: '/api/me/applications',
    settingsUrl: '/api/me/applications/settings',
    activeApplicationId: 'intraday-trading'
    // fetchImpl: bearerFetch, tenantId: selectedTenant
  });

  return <AppSwitcher state={state} onSaveApplications={saveApplications} />;
}

Mount it in AppFrame.AppBar (or any full-height flex column). Leave out onSaveApplications to hide the settings item.

Bring your own data layer

Hosts that already have react-query or similar can skip the hook and compose the pure pieces:

• fetchApplications({ url, fetchImpl?, signal?, tenantId? })
• saveApplicationSettings({ url, fetchImpl?, signal?, tenantId?, settings })
• applySettings(applications, settings), deriveSettings(applications)
• <AppSwitcher state={...} onSaveApplications={...} /> with state one of { status: 'loading' }, { status: 'error' }, { status: 'loaded', applications, activeApplicationId? }

Tile behaviour

• access: 'denied' links to requestUrl ("Request access to …"); any other tile links to url.
• Every tile opens in a new tab except the active entry, which stays in the current one.
• An application with no usable http(s) URL is left out of the bar and the settings, unless it is the active one: that stays as an unlinked marker.
• Icons come from icon.pathData; entries without one get a generic fallback.

Development

This package lives in the customer-portal-frontend monorepo under packages/app-switcher/.

npm run dev -w @volue/app-switcher    # Vite playground with real Wave styling and fixture endpoints
                                      # add ?live for real data: needs the portal dev server running
                                      # on localhost:3000 and a signed-in session there (a 502 means
                                      # the proxy found nothing on 3000)
npm run test -w @volue/app-switcher
npm run build -w @volue/app-switcher

Peer dependencies: react, react-dom, @volue/wave-react. The component is a client component.

Releasing

Bump version in package.json in a PR. Merging to main runs the Publish packages workflow, which builds, publishes to npm via trusted publishing and tags @volue/app-switcher@<version>.