MapControls

From the Base UI reference for Toolbar.Root, Toolbar.Button and Toolbar.Separator, as the Toolbar spec gives them. "From" says who does it.

Home and End do nothing, as on Toolbar. + and − zoom the map from the map canvas (Accessibility), not from these controls.

MapControls listens to no keys of its own and sets no aria-keyshortcuts, leaving + and − to the map. Accessibility gives those keys to the screen ("+ and − zoom, arrow keys pan"), the map canvas has focus when they are pressed, and the controls can't know that the screen binds them, so announcing a shortcut could promise one that does nothing.

The pause button swaps its name, "Pause" or "Resume", and sets no aria-pressed. The APG's button pattern gives a two-state button one of two forms: a toggle whose label stays the same while aria-pressed says its state, such as "Mute", pressed or not; or a button whose label changes with the state, such as Play and Pause, which then has no aria-pressed, since "Pause, pressed" says the opposite of what it means. The icon swaps between pause and play, each naming the action a press takes, and the contract asks that everything the eye is told the ear is told, so the name swaps with the icon: a fixed "Pause" with aria-pressed would be heard as "Pause, pressed" while the eye sees play. The name says what the press does, as zoom in and zoom out do, and it is the name Mylder's map already gives the button. A screen reader may not announce the new name on the press itself; the vehicles stopping or moving is the press's feedback, and the name is read the next time focus reaches the button.

The 3D toggle takes the APG's other form: its name, "3D view", stays the same while aria-pressed says whether the map is tilted, heard as "3D view, toggle button, pressed" or "not pressed". Its icon, the cube, stays the same too, and its on fill is what the eye is told. The state is the map's, which a gesture changes as well as a press, so it is a state to announce rather than an action to name, as "Pause" is: a name that swapped, "Tilt the map" and "Lay the map flat", would leave the ear without the map's state once a gesture had tilted it. aria-pressed follows tilted, so a gesture the screen passes on is heard the next time focus reaches the toggle.

The compass's name says what a press does, "Reset to north", at every heading, as the zoom and centre buttons name theirs, and it sets no aria-pressed: the press is an action, not a state.

The compass tells the ear what its needle tells the eye: whether the map is turned away from north. While the needle is drawn turned, a finite heading that isn't a whole turn from north, the compass is described by the turnedFromNorth owned string, "Map turned away from north", through aria-describedby pointing at a VisuallyHidden span after it, the contract's part for words the eye gets from an icon, heard after its name as "Reset to north, button, Map turned away from north"; at north, and for a heading that isn't finite, which draws the needle unturned, the span and the aria-describedby are gone. aria-describedby is ARIA 1.0, which every screen reader reads, where ARIA 1.3's aria-description is not yet read evenly. The description changes only between north and turned, never at each degree, so a turn the screen passes frame by frame doesn't change what is heard until the map reaches north, where a screen reader would repeat or drop a number that changed at every frame; the name stays "Reset to north", what a press does, at every heading. The exact angle stays the map's to describe, as the zoom is: the needle's angle tells the eye no number either, only which way north lies, and the ear learns that north is not up.

What axe won't catch, from the contract, each with how this component meets it:

• Everything the eye is told, the ear is told, for every shape each prop accepts: each icon is aria-hidden inside its button, and the button's aria-label says the action it shows ("Zoom in", "Zoom out", "Centre the map", "Reset to north", and "Pause" or "Resume" as the pause or play icon shows), or, for the 3D toggle, the view it turns on, "3D view"; the toggle's on fill is its aria-pressed; the compass's turned needle is its description, "Map turned away from north", through aria-describedby and VisuallyHidden, while heading turns it, and none at north, as the paragraph above says; a dimmed button is announced through aria-disabled; the separators are announced as such.
• Every landmark and named region has an accessible name: the bar is a toolbar named "Map controls" by its owned string, so it tells itself apart from the top bar's toolbars.
• Every default label can be overridden: mapControlsLabel, zoomInLabel, zoomOutLabel, centerMapLabel, view3dLabel, resetNorthLabel, turnedFromNorthLabel, pauseLabel and resumeLabel.
• Every shape the type accepts renders, in every variant: the props take no ReactNode; both orientations, every …Disabled combination and disabled render all three buttons, square, in the same order, and the 3D toggle in either state of tilted, the compass at any heading, 0, negative, past 360 or not finite, and the pause button in either state of paused after them when their handlers are given.
• A hidden copy kept for animation is aria-hidden, and a collapsed region is inert: none here; the controls keep no hidden copy and collapse nothing.
• Native semantics first: native <button>s from Toolbar.Button, Base UI's toolbar and separator roles, with ARIA only for the names an icon can't give.
• Focus moves in reading order and returns on close: the arrow keys move zoom in, zoom out, centre, then the 3D toggle, the compass and pause, in document order; the controls open nothing; a button that hits a zoom limit stays focusable, the 3D toggle stays the same element as tilted changes, the compass stays in the bar at north, and the pause button stays the same element as its icon and name swap, so focus never jumps away from the key a person pressed.
• Every target is at least size.target-min square: each button is size.control (34 px) square.
• Loops stop when the system asks for less motion: none here; the controls have no loop and no transition, and the compass's needle jumps to each heading it is given, so the motion is the screen's own turn of the map, which reads the motion tokens' reduced values (CR-12).

Every word MapControls announces is its own; it shows none. No key in packages/perron/src/locale/en.ts said any of these, so all nine are new, each added when its button joined, each with a JSDoc line like its neighbours, and agents write the Danish, Swedish and Norwegian.

The four new keys are mapControls "Map controls", zoomIn "Zoom in", zoomOut "Zoom out" and centerMap "Centre the map", overridden by mapControlsLabel, zoomInLabel, zoomOutLabel and centerMapLabel. They are the words the Toolbar spec's map stories and the IconButton spec's examples already use, packages/perron/icons/icons.json gives locate the use "Centre the map on the network", each names the action as a verb and what it acts on, in sentence case (Content design), and the keys take the American spelling of code names.

The pause button's two keys joined later: pause "Pause" and resume "Resume", overridden by pauseLabel and resumeLabel. They are the names Mylder's map gives the button in English, and in Danish, "Pause" and "Fortsæt", from its dictionary; the Swedish, "Pausa" and "Fortsätt", and the Norwegian, "Pause" and "Fortsett", were written for Perron, since Mylder has no Swedish or Norwegian. Each is the verb of the press, and packages/perron/icons/icons.json gives pause and play the uses "Stop the vehicles moving on the map" and "Set the vehicles moving again". "Resume" rather than "Play": the map isn't media, and the press resumes the motion the reader paused.

The 3D toggle's and the compass's two keys joined with them, for perron#186, whose changeset names them: view3d and resetNorth, overridden by view3dLabel and resetNorthLabel. Agents write the Danish, Swedish and Norwegian, since Mylder's dictionary has neither yet.

The compass's English, "Reset to north", is the issue's: the verb of the press and where it turns the map, in sentence case, as packages/perron/icons/icons.json gives compass the use "turn the map back to it". The key is resetNorth, the action as the other buttons' keys are.

The compass's description is the key turnedFromNorth, "Map turned away from north", overridden by turnedFromNorthLabel, which joined when the review held the compass to the contract's "everything the eye is told, the ear is told": a statement of the map's state, as the needle shows it, rather than an action, since the name already says the press. Agents write the Danish, Swedish and Norwegian: "Kortet er drejet væk fra nord", "Kartan är roterad bort från norr" and "Kartet er dreid bort fra nord".

The 3D toggle's name is the key view3d, "3D view", overridden by view3dLabel. A toggle's name stays the same while aria-pressed says its state (see Keyboard and ARIA), so it names what the press turns on rather than the press itself: "3D view, pressed" says the map is in 3D, where a verb, "Tilt the map, pressed", reads as a step already taken. "3D" is what the issue and the cube icon's use call the view, and is written alike in all four locales; the key puts the noun first, as mapControls does, since a key can't start with a digit.

For a caller using the component, with the reason. Each row is a rule: a must row's Don't is never right, a should row's needs a reason, and Checked by says what catches the Don't in a caller's code.