Pane scaffolds (Adaptive)

mandatory

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).

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

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

R1 — Four scaffolds

Scaffold	Slots	When to use
istDetailPaneScaffold	list + detail	2-pane: list of items + selected detail
upportingPaneScaffold	main + supporting	2-pane: primary content + auxiliary info
hreePaneScaffold	main + supporting + extra	3-pane: main + supporting + extra (max layout)
avigationSuiteScaffold	navigation + content	Wraps app; provides adaptive nav (bottom-barraildrawer)

R2 — Windowsizeclass behavior

Class	ListDetail	Supporting	ThreePane	NavigationSuite
ompact(< 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
edium(600-839dp)	2 panes (list 40% + detail 60%)	2 panes (main 65% + supporting 35%)	2 panes (main + supporting; extra in bottom sheet)	Navigation rail
xpanded(840-1199dp)	2 panes (list 40% + detail 60%)	2 panes (main 70% + supporting 30%)	3 panes (main + supporting + extra)	Modal nav drawer OR rail
arge(≥ 1200dp)	2 panes + nav drawer	2 panes + nav drawer	3 panes + nav drawer	Standard nav drawer (always visible)

Cross~~link: [`window~~size~~classes.kmd`](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 sidebyside; selection updates detail.

R4 — SupportingPaneScaffold

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

Compact: main full~~screen; supporting accessible via bottom sheet (swipe~~up).
Medium+: sidebyside; 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 sidebyside.

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-barraildrawer 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

*1*ListDetail compact: 1 pane visible (list); select → detail full-screen.
*2*ListDetail medium: 2 panes; select updates detail.
*3*Supporting compact: main full; supporting in bottom sheet.
*4*ThreePane expanded: 3 panes visible.
*5*NavigationSuite Compact: bottom nav bar present; nav rail/drawer absent.
*6*NavigationSuite Medium: nav rail; bottom bar absent.
*7*Window resize Compact → Medium: pane appears via spring transition; reduced-motion → instant.
*8*Keyboard nav: Tab traverses panes in visual order.
*9*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