App Header

API and Development

View SourceOpens in a new tab Submit IssueOpens in a new tab

Import AppHeader, AppHeaderRole from @prepared911/ui/blocks/app-header. See props.ts for the props and schema.ts for the declaration (inputs and variants). role is the discriminant of a union: each role takes only its own props. AppHeader takes no children, className, id, ref or style. AppHeaderRole: Calltaker, Dispatcher, Supervisor.

Every role

Prop	Type	Default
`role`	`AppHeaderRole`	required
`label`	`LocalizedMessage`	required
`landmark`	`NavbarLandmark`	`Banner`
`sticky`	`boolean`	`false`
`stickyInset`	`NavbarInset`	`0`
`homeHref`	`string`	required
`homeLabel`	`LocalizedMessage`	required
`navigationLabel`	`LocalizedMessage`	required
`overflowLabel`	`LocalizedMessage`	required
`currentPath`	`string`	required
`navigate`	`(path: string) => void`	required
`matchPath`	`NavbarTabsProps["matchPath"]`	pathname equality
`islandLabel`	`LocalizedMessage`	required
`notificationsLabel`	`LocalizedMessage`	required
`onNotificationsPress`	`() => void`	none
`toolsLabel`	`LocalizedMessage`	required
`fullscreenLabel`	`LocalizedMessage`	required
`onFullscreenPress`	`() => void`	none
`closeLabel`	`LocalizedMessage`	required
`onClosePress`	`() => void`	none

AppHeaderRoute: href (string), label (LocalizedMessage), optional extraRouteMatchers.

Calltaker and Dispatcher

Prop	Type	Default
`routes`	`AppHeaderOperatorRoutes` (`live`, `archived`)	required
`roleLabel`	`LocalizedMessage`	required
`queueLabel`	`LocalizedMessage`	required
`raiseHandLabel`	`LocalizedMessage`	required
`raisedHand`	`boolean`	uncontrolled
`defaultRaisedHand`	`boolean`	`false`
`onRaisedHandChange`	`(raised: boolean, details: ChangeDetails) => void`	none
`trainingLabel`	`LocalizedMessage`	required
`onTrainingPress`	`() => void`	none
`preferencesLabel`	`LocalizedMessage`	required
`onPreferencesPress`	`() => void`	none

Calltaker only

Prop	Type	Default
`availability`	`AppHeaderAvailability`	required

AppHeaderAvailability matches ControlIsland's availability except statusItems carry labels only; AppHeader supplies status glyphs. See app-header-availability.ts. The Dispatcher role types availability as never.

Supervisor

Prop	Type	Default
`routes`	`AppHeaderSupervisorRoutes` (`live`, `archived`, `learning`, optional `settings`)	required
`roleLabels`	`AppHeaderRoleLabels` (one `LocalizedMessage` per role)	required
`activeRole`	`AppHeaderRole`	uncontrolled
`defaultActiveRole`	`AppHeaderRole`	`Supervisor`
`onActiveRoleChange`	`(role: AppHeaderRole, details: ChangeDetails) => void`	none
`calltakerQueueLabel`	`LocalizedMessage`	required
`dispatcherQueueLabel`	`LocalizedMessage`	required
`switcherRoles`	`readonly AppHeaderRole[]`	all three
`availability`	`AppHeaderAvailability`	optional
`raiseHandLabel`	`LocalizedMessage`	required
`raisedHand`	`boolean`	uncontrolled
`defaultRaisedHand`	`boolean`	`false`
`onRaisedHandChange`	`(raised: boolean, details: ChangeDetails) => void`	none

Props

Name	Type	Default	Description
`accountLabel`	`LocalizedMessage`	—	Accessible name of the account cog (`settings`), which opens the account menu.
`accountName`	`UserMenuName`	—	The person's name in the account menu header.
`appearanceLabels`	`UserMenuAppearanceLabels`	—	Names of the theme choices. The account menu shows the theme row from these.
`calltakerQueueLabel`	`LocalizedMessage`	—	Queue label on the Calltaker segment when that role is offered.
`closeLabel`	`LocalizedMessage`	—	Name of the close control (x). Always required, and used only when `onClosePress` is passed.
`currentPath`	`string`	—	Current pathname, which decides the current tab.
`dispatcherQueueLabel`	`LocalizedMessage`	—	Channel label on the Dispatcher segment when that role is offered.
`fullscreenLabel`	`LocalizedMessage`	—	Name of the full screen control. Always required, and used only when `onFullscreenPress` is passed.
`homeHref`	`string`	—	Where the Axon mark at the start goes, usually the home route.
`homeLabel`	`LocalizedMessage`	—	Accessible name of the Axon mark's link, such as "Home".
`islandLabel`	`LocalizedMessage`	—	Accessible name of the ControlIsland at the start, such as "Role and availability".
`label`	`LocalizedMessage`	—	Accessible name of the bar. It names the banner, or the navigation landmark when `landmark` says so.
`navigate`	`(path: string) => void`	—	Called with a route's `href` on an unmodified primary click on a tab, and on a press of its row in the overflow menu, so a client router can handle both. @param path - The route's `href`
`navigationLabel`	`LocalizedMessage`	—	Accessible name of the navigation landmark that holds the route tabs.
`notificationsLabel`	`LocalizedMessage`	—	Name of the notifications control (bell-ring).
`onSignOut`	`() => void \| Promise<void>`	—	Called when a person presses Log out. When it returns a promise the row stays busy until the promise settles, then the menu closes. The block does not log the person out.
`overflowLabel`	`LocalizedMessage`	—	Visible label of the control that opens the menu of routes that do not fit.
`preferencesLabel`	`LocalizedMessage`	—	Name of the preferences control (settings-2).
`queueLabel`	`LocalizedMessage`	—	The queue (Calltaker) or channel (Dispatcher) being worked, such as "All queues". Static text.
`raiseHandLabel`	`LocalizedMessage`	—	Name of the raise hand control. It does not change with the pressed state. Name of the raise hand control when Calltaker or Dispatcher is selected in the switcher.
`reduceMotionLabel`	`LocalizedMessage`	—	Label of the Reduce motion switch in the account menu. The row lets a person turn animation off on a slow device.
`role`	`AppHeaderRole`	—	The Calltaker header. The Dispatcher header. The Supervisor header.
`roleLabel`	`LocalizedMessage`	—	Name of the role on the island's badge, such as "Calltaker". The badge shows only a glyph.
`roleLabels`	`Readonly<Record<AppHeaderRole, LocalizedMessage>>`	—	Names of the switcher's roles. Each is its segment's accessible name and shows while the segment is selected.
`routes`	`AppHeaderOperatorRoutes \| AppHeaderSupervisorRoutes`	—	The route tabs: Live and Archived. The route tabs: Live, Archived, Learning and Settings.
`signingOutLabel`	`LocalizedMessage`	—	Label of the log out row while `onSignOut` is pending.
`signOutLabel`	`LocalizedMessage`	—	Label of the log out row. It is the last row of the account menu.
`toolsLabel`	`LocalizedMessage`	—	Accessible name of the cluster after the separator: preferences (where the role has it), and full screen and close when their handlers are passed.
`trainingLabel`	`LocalizedMessage`	—	Name of the training control (graduation-cap).
`accountEmail`	`DisplayValue`	—	The person's email in the account menu header. Truncated there; the full text is the title.
`activeRole`	`AppHeaderRole`	—	The role selected in the switcher when controlled. The header stays the Supervisor header whatever it holds.
`appearance`	`AppearanceMode`	—	Controlled appearance preference. Pair with `onAppearanceChange`. The host applies it.
`availability`	`AppHeaderAvailability`	—	Call-taker availability copy and state, in the same shape as ControlIsland's `availability` except status glyphs, which AppHeader supplies (AH-4). A dispatcher has no availability; use {@link AppHeaderRole.Calltaker}. Call-taker availability when the Calltaker role is offered. Omitted when the switcher has no Calltaker segment.
`defaultActiveRole`	`AppHeaderRole`	`AppHeaderRole.Supervisor`	The role selected in the switcher on first render when uncontrolled.
`defaultAppearance`	`AppearanceMode`	`system`	Initial appearance preference when uncontrolled.
`defaultRaisedHand`	`boolean`	`false false`	Initial raised state when uncontrolled.
`defaultReduceMotion`	`boolean`	`false`	Initial reduce motion preference when uncontrolled.
`landmark`	`NavbarLandmark`	`NavbarLandmark.Banner`	Landmark of the bar. A shell that has a banner of its own passes {@link NavbarLandmark.Navigation} so a page never has two banners.
`matchPath`	`MatchPathFn`	—	Route matcher, for example react-router `matchPath`. Defaults to pathname equality.
`onActiveRoleChange`	`((role: AppHeaderRole, details: ChangeDetails<ChangeReason>) => void)`	—	Called when a role segment is pressed; pressing the selected role does not call it. Cancel the details to keep the previous role. @param role - The pressed role @param details - Change metadata
`onAppearanceChange`	`AppearanceChangeHandler`	—	Called when a person picks a theme. The block only reports the choice; the host applies it, for example by setting `data-theme` on the document. The menu stays open. May be canceled.
`onClosePress`	`(() => void)`	—	Called when the close control is pressed. The control renders only when this is passed.
`onFullscreenPress`	`(() => void)`	—	Called when the full screen control is pressed. The control renders only when this is passed.
`onNotificationsPress`	`(() => void)`	—	Called when the notifications control is pressed.
`onPreferencesPress`	`(() => void)`	—	Called when the preferences control is pressed.
`onRaisedHandChange`	`((raised: boolean, details: ChangeDetails<ChangeReason>) => void) \| ((raised: boolean, details: ChangeDetails<ChangeReason>) => void)`	—	Called with the next state when the raise hand control is pressed. Cancel the details to keep the previous state. Called with the next raised state when the raise hand control is pressed in an operator role. Cancel the details to keep the previous state. @param raised - Next raised state @param details - Change metadata
`onReduceMotionChange`	`ReduceMotionChangeHandler`	—	Called when a person flips the Reduce motion switch. The block only reports the choice; the host applies it, for example by setting `data-motion="reduced"` on the document. May be canceled.
`onTrainingPress`	`(() => void)`	—	Called when the training control is pressed.
`raisedHand`	`boolean`	—	Whether the hand is raised when controlled. Pair with `onRaisedHandChange`. Whether the hand is raised when an operator role is selected. Pair with `onRaisedHandChange`.
`reduceMotion`	`boolean`	—	Controlled reduce motion preference. Pair with `onReduceMotionChange`. The host applies it.
`showNotifications`	`boolean`	—	Whether the notifications control renders. Defaults to `true`. A host that cannot honour notifications passes `false`, and the control is then left out of the DOM. `notificationsLabel` stays required and is unused then.
`sticky`	`boolean`	`false`	Keeps the bar at the block-start edge of its scrollport while the page scrolls.
`stickyInset`	`NavbarInset`	`0`	Distance between the stuck bar and the block-start edge, as a `--space-*` step. Only read when `sticky`.
`switcherRoles`	`readonly AppHeaderRole[]`	—	Roles offered in the switcher, in design order. Defaults to Supervisor, Calltaker and Dispatcher. When a route drops access to the active role, omit it here; the island falls back to the first entry without calling `onActiveRoleChange`.

Storybook

Interactive examples and edge cases for this component are in Storybook.

DefaultOpens in a new tab

App Header / Usage

App Header / Accessibility

On this page

Every role

Calltaker and Dispatcher

App Header

API and Development

View SourceOpens in a new tab Submit IssueOpens in a new tab

Every role

Prop	Type	Default
`role`	`AppHeaderRole`	required
`label`	`LocalizedMessage`	required
`landmark`	`NavbarLandmark`	`Banner`
`sticky`	`boolean`	`false`
`stickyInset`	`NavbarInset`	`0`
`homeHref`	`string`	required
`homeLabel`	`LocalizedMessage`	required
`navigationLabel`	`LocalizedMessage`	required
`overflowLabel`	`LocalizedMessage`	required
`currentPath`	`string`	required
`navigate`	`(path: string) => void`	required
`matchPath`	`NavbarTabsProps["matchPath"]`	pathname equality
`islandLabel`	`LocalizedMessage`	required
`notificationsLabel`	`LocalizedMessage`	required
`onNotificationsPress`	`() => void`	none
`toolsLabel`	`LocalizedMessage`	required
`fullscreenLabel`	`LocalizedMessage`	required
`onFullscreenPress`	`() => void`	none
`closeLabel`	`LocalizedMessage`	required
`onClosePress`	`() => void`	none

AppHeaderRoute: href (string), label (LocalizedMessage), optional extraRouteMatchers.

Calltaker and Dispatcher

Prop	Type	Default
`routes`	`AppHeaderOperatorRoutes` (`live`, `archived`)	required
`roleLabel`	`LocalizedMessage`	required
`queueLabel`	`LocalizedMessage`	required
`raiseHandLabel`	`LocalizedMessage`	required
`raisedHand`	`boolean`	uncontrolled
`defaultRaisedHand`	`boolean`	`false`
`onRaisedHandChange`	`(raised: boolean, details: ChangeDetails) => void`	none
`trainingLabel`	`LocalizedMessage`	required
`onTrainingPress`	`() => void`	none
`preferencesLabel`	`LocalizedMessage`	required
`onPreferencesPress`	`() => void`	none

Calltaker only

Prop	Type	Default
`availability`	`AppHeaderAvailability`	required

Supervisor

Prop	Type	Default
`routes`	`AppHeaderSupervisorRoutes` (`live`, `archived`, `learning`, optional `settings`)	required
`roleLabels`	`AppHeaderRoleLabels` (one `LocalizedMessage` per role)	required
`activeRole`	`AppHeaderRole`	uncontrolled
`defaultActiveRole`	`AppHeaderRole`	`Supervisor`
`onActiveRoleChange`	`(role: AppHeaderRole, details: ChangeDetails) => void`	none
`calltakerQueueLabel`	`LocalizedMessage`	required
`dispatcherQueueLabel`	`LocalizedMessage`	required
`switcherRoles`	`readonly AppHeaderRole[]`	all three
`availability`	`AppHeaderAvailability`	optional
`raiseHandLabel`	`LocalizedMessage`	required
`raisedHand`	`boolean`	uncontrolled
`defaultRaisedHand`	`boolean`	`false`
`onRaisedHandChange`	`(raised: boolean, details: ChangeDetails) => void`	none

Props

Name	Type	Default	Description
`accountLabel`	`LocalizedMessage`	—	Accessible name of the account cog (`settings`), which opens the account menu.
`accountName`	`UserMenuName`	—	The person's name in the account menu header.
`appearanceLabels`	`UserMenuAppearanceLabels`	—	Names of the theme choices. The account menu shows the theme row from these.
`calltakerQueueLabel`	`LocalizedMessage`	—	Queue label on the Calltaker segment when that role is offered.
`closeLabel`	`LocalizedMessage`	—	Name of the close control (x). Always required, and used only when `onClosePress` is passed.
`currentPath`	`string`	—	Current pathname, which decides the current tab.
`dispatcherQueueLabel`	`LocalizedMessage`	—	Channel label on the Dispatcher segment when that role is offered.
`fullscreenLabel`	`LocalizedMessage`	—	Name of the full screen control. Always required, and used only when `onFullscreenPress` is passed.
`homeHref`	`string`	—	Where the Axon mark at the start goes, usually the home route.
`homeLabel`	`LocalizedMessage`	—	Accessible name of the Axon mark's link, such as "Home".
`islandLabel`	`LocalizedMessage`	—	Accessible name of the ControlIsland at the start, such as "Role and availability".
`label`	`LocalizedMessage`	—	Accessible name of the bar. It names the banner, or the navigation landmark when `landmark` says so.
`navigate`	`(path: string) => void`	—	Called with a route's `href` on an unmodified primary click on a tab, and on a press of its row in the overflow menu, so a client router can handle both. @param path - The route's `href`
`navigationLabel`	`LocalizedMessage`	—	Accessible name of the navigation landmark that holds the route tabs.
`notificationsLabel`	`LocalizedMessage`	—	Name of the notifications control (bell-ring).
`onSignOut`	`() => void \| Promise<void>`	—	Called when a person presses Log out. When it returns a promise the row stays busy until the promise settles, then the menu closes. The block does not log the person out.
`overflowLabel`	`LocalizedMessage`	—	Visible label of the control that opens the menu of routes that do not fit.
`preferencesLabel`	`LocalizedMessage`	—	Name of the preferences control (settings-2).
`queueLabel`	`LocalizedMessage`	—	The queue (Calltaker) or channel (Dispatcher) being worked, such as "All queues". Static text.
`raiseHandLabel`	`LocalizedMessage`	—	Name of the raise hand control. It does not change with the pressed state. Name of the raise hand control when Calltaker or Dispatcher is selected in the switcher.
`reduceMotionLabel`	`LocalizedMessage`	—	Label of the Reduce motion switch in the account menu. The row lets a person turn animation off on a slow device.
`role`	`AppHeaderRole`	—	The Calltaker header. The Dispatcher header. The Supervisor header.
`roleLabel`	`LocalizedMessage`	—	Name of the role on the island's badge, such as "Calltaker". The badge shows only a glyph.
`roleLabels`	`Readonly<Record<AppHeaderRole, LocalizedMessage>>`	—	Names of the switcher's roles. Each is its segment's accessible name and shows while the segment is selected.
`routes`	`AppHeaderOperatorRoutes \| AppHeaderSupervisorRoutes`	—	The route tabs: Live and Archived. The route tabs: Live, Archived, Learning and Settings.
`signingOutLabel`	`LocalizedMessage`	—	Label of the log out row while `onSignOut` is pending.
`signOutLabel`	`LocalizedMessage`	—	Label of the log out row. It is the last row of the account menu.
`toolsLabel`	`LocalizedMessage`	—	Accessible name of the cluster after the separator: preferences (where the role has it), and full screen and close when their handlers are passed.
`trainingLabel`	`LocalizedMessage`	—	Name of the training control (graduation-cap).
`accountEmail`	`DisplayValue`	—	The person's email in the account menu header. Truncated there; the full text is the title.
`activeRole`	`AppHeaderRole`	—	The role selected in the switcher when controlled. The header stays the Supervisor header whatever it holds.
`appearance`	`AppearanceMode`	—	Controlled appearance preference. Pair with `onAppearanceChange`. The host applies it.
`availability`	`AppHeaderAvailability`	—	Call-taker availability copy and state, in the same shape as ControlIsland's `availability` except status glyphs, which AppHeader supplies (AH-4). A dispatcher has no availability; use {@link AppHeaderRole.Calltaker}. Call-taker availability when the Calltaker role is offered. Omitted when the switcher has no Calltaker segment.
`defaultActiveRole`	`AppHeaderRole`	`AppHeaderRole.Supervisor`	The role selected in the switcher on first render when uncontrolled.
`defaultAppearance`	`AppearanceMode`	`system`	Initial appearance preference when uncontrolled.
`defaultRaisedHand`	`boolean`	`false false`	Initial raised state when uncontrolled.
`defaultReduceMotion`	`boolean`	`false`	Initial reduce motion preference when uncontrolled.
`landmark`	`NavbarLandmark`	`NavbarLandmark.Banner`	Landmark of the bar. A shell that has a banner of its own passes {@link NavbarLandmark.Navigation} so a page never has two banners.
`matchPath`	`MatchPathFn`	—	Route matcher, for example react-router `matchPath`. Defaults to pathname equality.
`onActiveRoleChange`	`((role: AppHeaderRole, details: ChangeDetails<ChangeReason>) => void)`	—	Called when a role segment is pressed; pressing the selected role does not call it. Cancel the details to keep the previous role. @param role - The pressed role @param details - Change metadata
`onAppearanceChange`	`AppearanceChangeHandler`	—	Called when a person picks a theme. The block only reports the choice; the host applies it, for example by setting `data-theme` on the document. The menu stays open. May be canceled.
`onClosePress`	`(() => void)`	—	Called when the close control is pressed. The control renders only when this is passed.
`onFullscreenPress`	`(() => void)`	—	Called when the full screen control is pressed. The control renders only when this is passed.
`onNotificationsPress`	`(() => void)`	—	Called when the notifications control is pressed.
`onPreferencesPress`	`(() => void)`	—	Called when the preferences control is pressed.
`onRaisedHandChange`	`((raised: boolean, details: ChangeDetails<ChangeReason>) => void) \| ((raised: boolean, details: ChangeDetails<ChangeReason>) => void)`	—	Called with the next state when the raise hand control is pressed. Cancel the details to keep the previous state. Called with the next raised state when the raise hand control is pressed in an operator role. Cancel the details to keep the previous state. @param raised - Next raised state @param details - Change metadata
`onReduceMotionChange`	`ReduceMotionChangeHandler`	—	Called when a person flips the Reduce motion switch. The block only reports the choice; the host applies it, for example by setting `data-motion="reduced"` on the document. May be canceled.
`onTrainingPress`	`(() => void)`	—	Called when the training control is pressed.
`raisedHand`	`boolean`	—	Whether the hand is raised when controlled. Pair with `onRaisedHandChange`. Whether the hand is raised when an operator role is selected. Pair with `onRaisedHandChange`.
`reduceMotion`	`boolean`	—	Controlled reduce motion preference. Pair with `onReduceMotionChange`. The host applies it.
`showNotifications`	`boolean`	—	Whether the notifications control renders. Defaults to `true`. A host that cannot honour notifications passes `false`, and the control is then left out of the DOM. `notificationsLabel` stays required and is unused then.
`sticky`	`boolean`	`false`	Keeps the bar at the block-start edge of its scrollport while the page scrolls.
`stickyInset`	`NavbarInset`	`0`	Distance between the stuck bar and the block-start edge, as a `--space-*` step. Only read when `sticky`.
`switcherRoles`	`readonly AppHeaderRole[]`	—	Roles offered in the switcher, in design order. Defaults to Supervisor, Calltaker and Dispatcher. When a route drops access to the active role, omit it here; the island falls back to the first entry without calling `onActiveRoleChange`.

Storybook

Interactive examples and edge cases for this component are in Storybook.

DefaultOpens in a new tab

App Header / Usage

App Header / Accessibility

On this page

Every role

Calltaker and Dispatcher