Pane scaffolds (Adaptive)

app-layout specs/app-layout/pane-scaffolds.kmd

Material 3 Adaptive pane scaffolds — concrete APIs that materialize the canonical layouts (Feed/List-detail/Supporting/Custom) from canonical-layouts.kmd. ListDetailPaneScaffold, SupportingPaneScaffold, ThreePaneScaffold, NavigationSuiteScaffold. Auto-switches per window size class (Compact/Medium/Expanded/Large).

When this spec applies

Primary triggers

Use ThreePaneScaffold / ListDetailPaneScaffold / SupportingPaneScaffold / NavigationSuiteScaffold

All triggers

Build adaptive surface with 1-3 panes
Implement list-detail OR supporting-pane layout
Switch navigation pattern automatically per window size

Spec — Pane scaffolds

Sibling: canonical-layouts.kmd (4 layouts: Feed / List-detail / Supporting / Custom). Esta spec define APIs concretas que materializam essas layouts.

Princípios

Window-size-aware — single API; behavior switches per window-size-classes.kmd.
Default content slots — main + supporting + extra (3-pane max).
NavigationSuite unified — bottom-bar (Compact) ↔ nav-rail (Medium) ↔ nav-drawer (Expanded+) auto-switch.
Smooth transitions — pane appearing/disappearing animated via spring (per motion.kmd R9.1).

R1 — Four scaffolds

Scaffold	Slots	When to use
ListDetailPaneScaffold	list + detail	2-pane: list of items + selected detail
SupportingPaneScaffold	main + supporting	2-pane: primary content + auxiliary info
ThreePaneScaffold	main + supporting + extra	3-pane: main + supporting + extra (max layout)
NavigationSuiteScaffold	navigation + content	Wraps app; provides adaptive nav (bottom-bar/rail/drawer)

R2 — Window-size-class behavior

Class	ListDetail	Supporting	ThreePane	NavigationSuite
Compact (< 600dp)	1 pane visible (list OR detail; navigation via push/back)	1 pane (main; supporting in bottom sheet)	1 pane (main; others in sheets/menus)	Bottom nav bar
Medium (600-839dp)	2 panes (list 40% + detail 60%)	2 panes (main 65% + supporting 35%)	2 panes (main + supporting; extra in bottom sheet)	Navigation rail
Expanded (840-1199dp)	2 panes (list 40% + detail 60%)	2 panes (main 70% + supporting 30%)	3 panes (main + supporting + extra)	Modal nav drawer OR rail
Large (≥ 1200dp)	2 panes + nav drawer	2 panes + nav drawer	3 panes + nav drawer	Standard nav drawer (always visible)

Cross-link: window-size-classes.kmd for canonical breakpoints.

R3 — ListDetailPaneScaffold

KoderListDetailPaneScaffold(
  navigator: KoderListDetailPaneScaffoldNavigator(...),
  listPane: (context) => ItemListView(...),
  detailPane: (context) => ItemDetailView(...),
)

Navigator tracks selected item id; navigation programmatic (push/pop).
Compact: list visible by default; selecting item → detail full-screen + back button returns to list.
Medium+: list + detail visible side-by-side; selection updates detail.

R4 — SupportingPaneScaffold

KoderSupportingPaneScaffold(
  mainPane: (context) => ArticleBody(...),
  supportingPane: (context) => RelatedItems(...),
)

Compact: main full-screen; supporting accessible via bottom sheet (swipe-up).
Medium+: side-by-side; ratio per R2.

R5 — ThreePaneScaffold

KoderThreePaneScaffold(
  navigator: KoderThreePaneScaffoldNavigator(...),
  mainPane: (context) => ...,
  supportingPane: (context) => ...,
  extraPane: (context) => ...,
)

Compact: 1 visible (main); others in menus/sheets.
Medium: 2 panes (main + supporting; extra inaccessible OR bottom sheet).
Expanded+: 3 panes side-by-side.

R6 — NavigationSuiteScaffold

Wrapper que substitui o Scaffold root:

KoderNavigationSuiteScaffold(
  destinations: [
    NavDestination(icon: home, label: "Home"),
    NavDestination(icon: search, label: "Search"),
    NavDestination(icon: settings, label: "Settings"),
  ],
  currentIndex: 0,
  onDestinationSelected: (i) {...},
  content: (context) => HomeScreen(...),
)

Auto-switches navigation pattern per R2.
Cross-link: navigation.kmd for individual nav components (bottom bar / rail / drawer).

R7 — Transitions

Pane appearing/disappearing during window-size-class change:

Spring motion-spatial-default per motion.kmd R9.1.
Crossfade content; slide pane edge.
Reduced-motion: instant transition.

Navigation between items within scaffold:

Compact ListDetail: slide-from-right entrance (per navigation/back-behavior.kmd).
Medium+: in-place pane update (no slide).

R8 — Surface bindings

Surface	API
Flutter	`KoderListDetailPaneScaffold`, `KoderSupportingPaneScaffold`, `KoderThreePaneScaffold`, `KoderNavigationSuiteScaffold` em `koder_kit/` (futuro)
Web	`<koder-list-detail-pane-scaffold>`, etc. em `koder_web_kit`; CSS grid + container queries
Compose Android	Wraps `androidx.compose.material3.adaptive.*Scaffold` from compose-material3-adaptive
SwiftUI iOS	Wraps `NavigationSplitView` with adaptive behavior
CLI / TUI	Single-pane only; navigation via slash commands

R9 — Acessibilidade

Each pane is role="region" aria-label="<pane-name>".
Navigation suite: bottom-bar/rail/drawer each have own ARIA per navigation.kmd.
Pane size change announce via aria-live="polite" (terse: "Detail pane expanded").
Focus management: cross-pane focus moves predictably (Tab follows visual order).
Reduced-motion: no slide; instant.

R10 — i18n

Key	en-US	pt-BR
`scaffold.pane.list`	"List"	"Lista"
`scaffold.pane.detail`	"Detail"	"Detalhes"
`scaffold.pane.main`	"Main"	"Principal"
`scaffold.pane.supporting`	"Supporting"	"Auxiliar"
`scaffold.pane.extra`	"Extra"	"Extra"
`scaffold.back_to_list`	"Back to list"	"Voltar à lista"

R11 — Per-preset variation

Cosmetic only — pane sizes and transitions identical; visual styling (borders, dividers between panes) per preset.

Preset	Pane divider
`material3` / `material_expressive`	1dp `outline-variant`
`material2`	1dp `outline`
`terminal_classic`	Vertical bar `│` text characters
`brutalist`	3dp solid border
`cyberpunk_neon`	Glow line in accent
`minimalist_mono`	No divider (white space only)
`glassmorphism`	Frosted glass divider

T-suite

T1 ListDetail compact: 1 pane visible (list); select → detail full-screen.
T2 ListDetail medium: 2 panes; select updates detail.
T3 Supporting compact: main full; supporting in bottom sheet.
T4 ThreePane expanded: 3 panes visible.
T5 NavigationSuite Compact: bottom nav bar present; nav rail/drawer absent.
T6 NavigationSuite Medium: nav rail; bottom bar absent.
T7 Window resize Compact → Medium: pane appears via spring transition; reduced-motion → instant.
T8 Keyboard nav: Tab traverses panes in visual order.
T9 A11y: each pane has role/aria-label.

Cross-link

Canonical layouts: canonical-layouts.kmd
Breakpoints: window-size-classes.kmd
Navigation patterns: ../components/navigation.kmd
Back behavior: ../navigation/back-behavior.kmd
Motion: ../themes/motion.kmd R9
Refs: compose-material3-adaptive, NavigationSplitView SwiftUI, Material 3 Adaptive

References

specs/app-layout/canonical-layouts.kmd
specs/app-layout/window-size-classes.kmd
specs/components/navigation.kmd
specs/themes/motion.kmd