Control Island

API and Development

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

Import ControlIsland, ControlIslandStatus, ControlIslandVariant from @prepared911/ui/blocks/control-island. See props.ts for the props and schema.ts for the declaration (inputs and variants). variant is the discriminant of a union: each variant takes only its own props.

Every variant

Prop	Type	Default
`variant`	`ControlIslandVariant`	required
`label`	`LocalizedMessage`	required
`size`	`ButtonSize`	`Medium`
`className`	`string`	none
`id`	`string`	none
`ref`	`Ref<HTMLDivElement>`	none

ControlIslandVariant: Supervisor, Calltaker, Dispatcher. ref, id, and className land on the island (Calltaker, Dispatcher) or on the host around the ButtonGroup (Supervisor).

Supervisor

Prop	Type	Default
`items`	`readonly ControlIslandRoleItem[]`	required
`value`	`DisplayValue \| null`	uncontrolled
`defaultValue`	`DisplayValue \| null`	none
`onValueChange`	`(value: DisplayValue, details: ChangeDetails) => void`	none

ControlIslandRoleItem: value (DisplayValue), icon (Glyph), label (LocalizedMessage), optional disabled.

Calltaker and Dispatcher

Prop	Type	Default
`roleIcon`	`Glyph`	required
`roleLabel`	`LocalizedMessage`	required
`queueLabel`	`LocalizedMessage`	required
`raiseHandIcon`	`Glyph`	required
`raiseHandLabel`	`LocalizedMessage`	required
`raisedHand`	`boolean`	uncontrolled
`defaultRaisedHand`	`boolean`	`false`
`onRaisedHandChange`	`(raised: boolean, details: ChangeDetails) => void`	none

Calltaker only

Prop	Type	Default
`status`	`ControlIslandStatus` (`Busy`, `Ready`, `Ringing`)	uncontrolled
`defaultStatus`	`ControlIslandStatus`	`Busy`
`onStatusChange`	`(status: ControlIslandChoosableStatus, details: ChangeDetails) => void`	none
`busyLabel`	`LocalizedMessage`	required
`readyLabel`	`LocalizedMessage`	required
`ringingLabel`	`LocalizedMessage`	required
`statusMenuLabel`	`LocalizedMessage`	required
`ringingAnnouncement`	`LocalizedMessage`	required
`statusMenuIcon`	`Glyph`	required
`ringingIcon`	`Glyph`	required

ControlIslandChoosableStatus is Busy | Ready. The Dispatcher variant types status, defaultStatus, and onStatusChange as never.

Props

Name	Type	Default	Description
`busyLabel`	`LocalizedMessage`	—	Label of Busy, on the pill and on its menu row.
`items`	`readonly ControlIslandRoleItem[]`	—	The roles in display order. The island does not know which roles exist, so the host supplies all of them.
`label`	`LocalizedMessage`	—	Accessible name of the island (`role="group"`), such as "Role and availability".
`queueLabel`	`LocalizedMessage`	—	The queue (Calltaker) or channel (Dispatcher) the person is working, such as "All queues". Static text.
`raiseHandIcon`	`Glyph`	—	Glyph of the raise hand control.
`raiseHandLabel`	`LocalizedMessage`	—	Name of the raise hand control, such as "Raise hand". It does not change with the pressed state.
`readyLabel`	`LocalizedMessage`	—	Label of Ready, on the pill and on its menu row.
`ringingAnnouncement`	`LocalizedMessage`	—	Announced politely once when the status becomes Ringing, such as "Incoming call".
`ringingIcon`	`Glyph`	—	Glyph before the label of the Ringing pill.
`ringingLabel`	`LocalizedMessage`	—	Label of Ringing, on the pill.
`roleIcon`	`Glyph`	—	Glyph inside the accent role badge.
`roleLabel`	`LocalizedMessage`	—	Name of the role, such as "Calltaker". The badge shows only the glyph, so this is its accessible name.
`statusMenuIcon`	`Glyph`	—	Glyph after the label of the Busy and Ready pill, the chevron that says the pill opens a menu.
`statusMenuLabel`	`LocalizedMessage`	—	Name of the availability menu, such as "Availability". It names the radio group and describes the pill.
`variant`	`ControlIslandVariant`	—	The Supervisor island is an Expanding ButtonGroup of roles. The Calltaker island ends in the availability pill. The Dispatcher island has no availability control.
`className`	`string`	—	Classes appended to the island's host.
`defaultRaisedHand`	`boolean`	`false`	Initial raised state when uncontrolled.
`defaultStatus`	`ControlIslandStatus`	`ControlIslandStatus.Busy`	Initial availability when uncontrolled. A dispatcher has no availability; use {@link ControlIslandVariant.Calltaker}.
`defaultValue`	`DisplayValue \| null`	—	Value of the selected role on first render when uncontrolled.
`id`	`string`	—	Id of the island's host element.
`onRaisedHandChange`	`((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. @param raised - Next raised state @param details - Change metadata
`onStatusChange`	`((status: ControlIslandChoosableStatus, details: ChangeDetails<ChangeReason>) => void)`	—	Called with the chosen availability when a row of the status menu is pressed. It is never called with Ringing, which is not a choice. Cancel the details to keep the previous availability. A dispatcher has no availability; use {@link ControlIslandVariant.Calltaker}. @param status - The chosen availability @param details - Change metadata
`onValueChange`	`((value: DisplayValue, details: ChangeDetails<ChangeReason>) => void)`	—	Called when a role segment is pressed, with `ChangeReason.ItemPress`. Pressing the selected role does not call it. Cancel the details to keep the previous role. @param value - The pressed role's value @param details - Change metadata
`raisedHand`	`boolean`	—	Whether the hand is raised when controlled. Pair with `onRaisedHandChange`.
`ref`	`Ref<HTMLDivElement>`	—	Ref to the island's host element.
`size`	`ButtonSize`	`ButtonSize.Medium`	Control height of the island's controls, from the shared scale (ADR 0012). The role segments, the badge, the raise hand control, and the status pill all follow it. A pill is the control height plus its 1px edge on each side, and the island is a pill plus a 4px inset on each side: Medium is a 38px island with 30px pills.
`status`	`ControlIslandStatus`	—	Availability when controlled. The host sets {@link ControlIslandStatus.Ringing} while a call is incoming and sets the person's choice back when it ends: the island keeps no memory of the choice that Ringing replaced. A dispatcher has no availability; use {@link ControlIslandVariant.Calltaker}.
`value`	`DisplayValue \| null`	—	Value of the selected role when controlled; `null` selects none.

Storybook

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

DefaultOpens in a new tab

Control Island / Usage

Control Island / Accessibility

On this page

Every variant

Supervisor

Calltaker and Dispatcher

Calltaker only

Props

Storybook

Control Island

API and Development

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

Every variant

Prop	Type	Default
`variant`	`ControlIslandVariant`	required
`label`	`LocalizedMessage`	required
`size`	`ButtonSize`	`Medium`
`className`	`string`	none
`id`	`string`	none
`ref`	`Ref<HTMLDivElement>`	none

ControlIslandVariant: Supervisor, Calltaker, Dispatcher. ref, id, and className land on the island (Calltaker, Dispatcher) or on the host around the ButtonGroup (Supervisor).

Supervisor

Prop	Type	Default
`items`	`readonly ControlIslandRoleItem[]`	required
`value`	`DisplayValue \| null`	uncontrolled
`defaultValue`	`DisplayValue \| null`	none
`onValueChange`	`(value: DisplayValue, details: ChangeDetails) => void`	none

ControlIslandRoleItem: value (DisplayValue), icon (Glyph), label (LocalizedMessage), optional disabled.

Calltaker and Dispatcher

Prop	Type	Default
`roleIcon`	`Glyph`	required
`roleLabel`	`LocalizedMessage`	required
`queueLabel`	`LocalizedMessage`	required
`raiseHandIcon`	`Glyph`	required
`raiseHandLabel`	`LocalizedMessage`	required
`raisedHand`	`boolean`	uncontrolled
`defaultRaisedHand`	`boolean`	`false`
`onRaisedHandChange`	`(raised: boolean, details: ChangeDetails) => void`	none

Calltaker only

Prop	Type	Default
`status`	`ControlIslandStatus` (`Busy`, `Ready`, `Ringing`)	uncontrolled
`defaultStatus`	`ControlIslandStatus`	`Busy`
`onStatusChange`	`(status: ControlIslandChoosableStatus, details: ChangeDetails) => void`	none
`busyLabel`	`LocalizedMessage`	required
`readyLabel`	`LocalizedMessage`	required
`ringingLabel`	`LocalizedMessage`	required
`statusMenuLabel`	`LocalizedMessage`	required
`ringingAnnouncement`	`LocalizedMessage`	required
`statusMenuIcon`	`Glyph`	required
`ringingIcon`	`Glyph`	required

ControlIslandChoosableStatus is Busy | Ready. The Dispatcher variant types status, defaultStatus, and onStatusChange as never.

Props

Name	Type	Default	Description
`busyLabel`	`LocalizedMessage`	—	Label of Busy, on the pill and on its menu row.
`items`	`readonly ControlIslandRoleItem[]`	—	The roles in display order. The island does not know which roles exist, so the host supplies all of them.
`label`	`LocalizedMessage`	—	Accessible name of the island (`role="group"`), such as "Role and availability".
`queueLabel`	`LocalizedMessage`	—	The queue (Calltaker) or channel (Dispatcher) the person is working, such as "All queues". Static text.
`raiseHandIcon`	`Glyph`	—	Glyph of the raise hand control.
`raiseHandLabel`	`LocalizedMessage`	—	Name of the raise hand control, such as "Raise hand". It does not change with the pressed state.
`readyLabel`	`LocalizedMessage`	—	Label of Ready, on the pill and on its menu row.
`ringingAnnouncement`	`LocalizedMessage`	—	Announced politely once when the status becomes Ringing, such as "Incoming call".
`ringingIcon`	`Glyph`	—	Glyph before the label of the Ringing pill.
`ringingLabel`	`LocalizedMessage`	—	Label of Ringing, on the pill.
`roleIcon`	`Glyph`	—	Glyph inside the accent role badge.
`roleLabel`	`LocalizedMessage`	—	Name of the role, such as "Calltaker". The badge shows only the glyph, so this is its accessible name.
`statusMenuIcon`	`Glyph`	—	Glyph after the label of the Busy and Ready pill, the chevron that says the pill opens a menu.
`statusMenuLabel`	`LocalizedMessage`	—	Name of the availability menu, such as "Availability". It names the radio group and describes the pill.
`variant`	`ControlIslandVariant`	—	The Supervisor island is an Expanding ButtonGroup of roles. The Calltaker island ends in the availability pill. The Dispatcher island has no availability control.
`className`	`string`	—	Classes appended to the island's host.
`defaultRaisedHand`	`boolean`	`false`	Initial raised state when uncontrolled.
`defaultStatus`	`ControlIslandStatus`	`ControlIslandStatus.Busy`	Initial availability when uncontrolled. A dispatcher has no availability; use {@link ControlIslandVariant.Calltaker}.
`defaultValue`	`DisplayValue \| null`	—	Value of the selected role on first render when uncontrolled.
`id`	`string`	—	Id of the island's host element.
`onRaisedHandChange`	`((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. @param raised - Next raised state @param details - Change metadata
`onStatusChange`	`((status: ControlIslandChoosableStatus, details: ChangeDetails<ChangeReason>) => void)`	—	Called with the chosen availability when a row of the status menu is pressed. It is never called with Ringing, which is not a choice. Cancel the details to keep the previous availability. A dispatcher has no availability; use {@link ControlIslandVariant.Calltaker}. @param status - The chosen availability @param details - Change metadata
`onValueChange`	`((value: DisplayValue, details: ChangeDetails<ChangeReason>) => void)`	—	Called when a role segment is pressed, with `ChangeReason.ItemPress`. Pressing the selected role does not call it. Cancel the details to keep the previous role. @param value - The pressed role's value @param details - Change metadata
`raisedHand`	`boolean`	—	Whether the hand is raised when controlled. Pair with `onRaisedHandChange`.
`ref`	`Ref<HTMLDivElement>`	—	Ref to the island's host element.
`size`	`ButtonSize`	`ButtonSize.Medium`	Control height of the island's controls, from the shared scale (ADR 0012). The role segments, the badge, the raise hand control, and the status pill all follow it. A pill is the control height plus its 1px edge on each side, and the island is a pill plus a 4px inset on each side: Medium is a 38px island with 30px pills.
`status`	`ControlIslandStatus`	—	Availability when controlled. The host sets {@link ControlIslandStatus.Ringing} while a call is incoming and sets the person's choice back when it ends: the island keeps no memory of the choice that Ringing replaced. A dispatcher has no availability; use {@link ControlIslandVariant.Calltaker}.
`value`	`DisplayValue \| null`	—	Value of the selected role when controlled; `null` selects none.

Storybook

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

DefaultOpens in a new tab

Control Island / Usage

Control Island / Accessibility

On this page

Every variant

Supervisor

Calltaker and Dispatcher

Calltaker only

Props

Storybook