Toolbars (docked + floating)

components specs/components/toolbars.kmd

Material 3 Expressive Toolbars — substituem o legado Bottom App Bar. Two variants: docked (anchored bottom, 56dp) and floating (horizontal bottom-center OR vertical side, hide-on-scroll). Companion to FAB. Bottom app bar marked deprecated-in-expressive.

Quando esta spec se aplica

Triggers primários

Build contextual action row distinct from app navigation

Todos os triggers

Replace bottom app bar in Koder app
Add contextual actions row anchored to viewport
Pair toolbar with FAB

Spec — Toolbars (docked + floating)

Sibling: app-bars.kmd (navegação principal). Esta spec cobre contextual actions (toolbars), distintos de navegação.

Princípios

App-bar ≠ Toolbar — app-bar é navegação principal (app-bars.kmd). Toolbar é ações contextuais.
Two anchored variants — docked (anchor fixo bottom) vs floating (translucent, hide-on-scroll).
Pair com FAB — floating toolbar mais comum pareando com FAB no canto.
Bottom app bar deprecated-in-expressive — manter retro-compat, mas não recomendar pra novos surfaces.

R1 — Decision tree

Need contextual actions row?
├── NO → use app bar (navegação)
└── YES:
    ├── Few actions, persistent → docked toolbar (R2)
    ├── Many actions OR auto-hide preferred → floating toolbar (R3)
    │   ├── Horizontal default (bottom-center)
    │   └── Vertical (tablet/desktop, side-anchored)
    └── Legacy/migration → bottom app bar (deprecated)

Anchor: bottom of viewport (above safe-area inset per app-layout/safe-area.kmd).
Height: 56dp.
Max actions: 5 (above → migrate to floating OR menu).
Background: surface per color-roles.kmd.
Elevation: 1dp (subtle).
Scroll behavior: lift-on-scroll (slight elevation increase) OR hide-on-scroll-down (configurable).

R2.1 — Anatomia

┌──────────────────────────────────────────┐
│  [Action] [Action] [Action] [Action] [⋯] │   ← 56dp height
└──────────────────────────────────────────┘

Actions: icon-only OR icon+label (configurable per action). Overflow ⋯ quando > 5.

R3.1 — Horizontal floating

Anchor: bottom-center, floating above content (with backdrop blur OR translucent).
Width: hug-content (min 240dp / max 80% viewport).
Padding: 16dp from bottom edge (above safe-area).
Elevation: 3dp.
Shape: shape-corner-extra-large (pill).
Background: surface-container-high per color-roles.kmd.
Behavior: hide-on-scroll-down + reveal-on-scroll-up via spring (motion.kmd R9.1 motion-spatial-default).

R3.2 — Vertical floating

Anchor: right-edge (LTR) or left-edge (RTL); vertically centered or top.
Tablets/desktops (Medium+ window class).
Auto-pin/unpin via drag.
Same elevation + shape + background as horizontal.

R3.3 — FAB pairing

Floating toolbar comumente paired com FAB:

                                       ┌─┐
                                       │+│   ← FAB
                                       └─┘
   ┌──────────────────────┐
   │ [A] [B] [C]          │   ← Floating toolbar (bottom-left)
   └──────────────────────┘

FAB scrolls/hides independently OR paired (configurable per surface).

R4 — Bottom app bar deprecation

app-bars.kmd bottom variant marked deprecated-in-expressive:

Retain support pra apps que ainda usam (no breaking change).
New surfaces SHOULD use docked toolbar instead.
Migration warning visible em koder-spec-audit quando bottom app bar detected em new code.

R5 — Surface bindings

Surface	API
Flutter	`KoderDockedToolbar({actions})` + `KoderFloatingToolbar({actions, direction})` em `koder_kit/` (futuro)
Web	`<koder-docked-toolbar>` + `<koder-floating-toolbar direction="horizontal\|vertical">`
Compose Android	`KoderDockedToolbar` + `KoderFloatingToolbar` (futuro)
SwiftUI iOS	idem (futuro)
CLI / TUI	Status line actions; no floating

R6 — Acessibilidade

Toolbar: role="toolbar" aria-label="<context>".
Actions: standard button semantic per buttons.kmd.
Floating: focus-trap NOT applied (open / not modal).
Hide-on-scroll: aria-hidden="true" when hidden; revealed restores.
Keyboard: Tab through actions; arrow keys navigate (per Material toolbar pattern).

R7 — i18n

Key	en-US	pt-BR
`toolbar.label.actions`	"Actions"	"Ações"
`toolbar.overflow`	"More"	"Mais"

R8 — Reduced-motion

Hide-on-scroll: instant (no spring slide). Lift-on-scroll: elevation change instant.

R9 — Per-preset variation

Preset	Toolbar style
`material3` / `material_expressive`	Default (docked + floating com shape pill)
`material2`	Docked only (sharp corners); floating not supported
`terminal_classic`	Bottom row text-only; no floating
`brutalist`	Sharp corners; flat (no elevation/shadow)
`cyberpunk_neon`	Default + neon outline on floating
`minimalist_mono`	Single border-top; no fill
`glassmorphism`	Floating backdrop-blur 30% (heavier)

T-suite

T1 Docked mount: 3 actions render at bottom; height 56dp.
T2 Docked overflow: 6 actions → 5 visible + ⋯ overflow menu.
T3 Floating horizontal mount: bottom-center; pill shape; elevation 3dp.
T4 Floating hide-on-scroll: scroll down 100px → toolbar slides out; scroll up → slides back.
T5 Floating vertical: Medium window class → side-anchored.
T6 FAB pair: floating toolbar + FAB → both anchor independently OR paired per config.
T7 Bottom app bar deprecation: existing instances continue to work; audit warns on new uses.
T8 Reduced-motion: hide/reveal instant.
T9 A11y: role="toolbar"; keyboard nav functional.

Cross-link

Sibling: app-bars.kmd (navegação)
Companion: buttons.kmd, FAB section
Layout: app-layout/safe-area.kmd R-safe-area
Animation: motion.kmd R9
Refs: M3 Toolbars guidelines

Referências

specs/components/app-bars.kmd
specs/components/buttons.kmd
specs/app-layout/safe-area.kmd
specs/themes/motion.kmd