multipaz/org.multipaz.cards/CardListLayoutCalculator

CardListLayoutCalculator

Pure, deterministic layout and visual state calculator for card lists.

This calculator is completely stateless and side-effect free. It translates layout configuration parameters (CardListLayoutParameters), viewport constraints, and active focus/drag identifiers into exact geometric coordinates, dimensions, and visual properties (CardVisualState) for every card in a list.

Responsibilities

Dimension & Aspect Ratio Calculation: Computes aspect-ratio preserved card dimensions and horizontal centering offsets based on viewport constraints (computeCardDimensions).
Total Height & Offsets: Computes total scrollable heights, top content offsets, and list margins (computeLayout).
Visual State Derivation: Computes the exact y, scale, elevation, alpha, and zIndex for any card at any point in time (computeCardVisualState).
Drag Target Resolution: Determines target index insertion points during active drag gestures based on vertical overlap thresholds (findTargetIndexForDragY).

Used in conjunction with VerticalCardListModel across both Compose Multiplatform and SwiftUI.

Functions

computeCardDimensions

fun computeCardDimensions(viewportWidth: Double, cardMaxHeight: Double?, paddingHorizontal: Double, aspectRatio: Double): CardDimensions

Computes the rendered dimensions and horizontal centering offset for a card.

computeCardStep

fun computeCardStep(cardHeight: Double, unfocusedVisiblePercent: Int, spacing: Double): Double

Computes the vertical step distance allocated to a card in standard list mode.

computeCardVisualState

fun computeCardVisualState(cardIdentifier: String, index: Int, cards: List<CardLayoutItem>, layout: CardListLayout, params: CardListLayoutParameters, focusedCardIdentifier: String?, draggedCardIdentifier: String?, dragCurrentY: Double): CardVisualState

Computes the visual state for a card given its position and interaction state.

computeDetailTopOffset

fun computeDetailTopOffset(paddingTop: Double, focusedCardHeight: Double, spacing: Double = 24.0): Double

Computes the top offset for the detail view below a focused card.

computeLayout

fun computeLayout(params: CardListLayoutParameters, cards: List<CardLayoutItem>, isAnyFocused: Boolean): CardListLayout

Computes overall layout metadata for the card list container.

findTargetIndexForDragY

fun findTargetIndexForDragY(dragCurrentY: Double, layout: CardListLayout, cards: List<CardLayoutItem>, params: CardListLayoutParameters): Int

Finds the target index for a dragged card given its current Y position.