@apexnative/navigation 0.0.0-stage → 1.0.0-alpha.0

package/android/src/main/java/dev/apexnative/navigation/options/InterpolationOptions.kt

@@ -0,0 +1,203 @@
+package dev.apexnative.navigation.options
+
+import com.facebook.react.bridge.ReadableMap
+import dev.apexnative.navigation.options.params.Bool
+import dev.apexnative.navigation.options.params.Fraction
+import dev.apexnative.navigation.options.params.NullBool
+import dev.apexnative.navigation.options.params.NullFraction
+import dev.apexnative.navigation.options.params.NullText
+import dev.apexnative.navigation.options.params.Text
+import dev.apexnative.navigation.options.parsers.BoolParser
+import dev.apexnative.navigation.options.parsers.FractionParser
+import dev.apexnative.navigation.options.parsers.TextParser
+
+/**
+ * An `Interpolation`: the curve of an animation. The fields of every `type` are read; a field the type doesn't use is
+ * not looked at. Without a type, or with an unknown one, the value moves linearly.
+ */
+class InterpolationOptions {
+    @JvmField var type: Text = NullText()
+    @JvmField var factor: Fraction = NullFraction()
+    @JvmField var tension: Fraction = NullFraction()
+    @JvmField var mass: Fraction = NullFraction()
+    @JvmField var damping: Fraction = NullFraction()
+    @JvmField var stiffness: Fraction = NullFraction()
+    @JvmField var allowsOverdamping: Bool = NullBool()
+    @JvmField var initialVelocity: Fraction = NullFraction()
+
+    fun hasValue(): Boolean = type.hasValue() || factor.hasValue() || tension.hasValue() || mass.hasValue() ||
+        damping.hasValue() || stiffness.hasValue() || allowsOverdamping.hasValue() || initialVelocity.hasValue()
+
+    fun mergeWith(other: InterpolationOptions) {
+        if (other.type.hasValue()) type = other.type
+        if (other.factor.hasValue()) factor = other.factor
+        if (other.tension.hasValue()) tension = other.tension
+        if (other.mass.hasValue()) mass = other.mass
+        if (other.damping.hasValue()) damping = other.damping
+        if (other.stiffness.hasValue()) stiffness = other.stiffness
+        if (other.allowsOverdamping.hasValue()) allowsOverdamping = other.allowsOverdamping
+        if (other.initialVelocity.hasValue()) initialVelocity = other.initialVelocity
+    }
+
+    fun mergeWithDefault(defaults: InterpolationOptions) {
+        if (!type.hasValue()) type = defaults.type
+        if (!factor.hasValue()) factor = defaults.factor
+        if (!tension.hasValue()) tension = defaults.tension
+        if (!mass.hasValue()) mass = defaults.mass
+        if (!damping.hasValue()) damping = defaults.damping
+        if (!stiffness.hasValue()) stiffness = defaults.stiffness
+        if (!allowsOverdamping.hasValue()) allowsOverdamping = defaults.allowsOverdamping
+        if (!initialVelocity.hasValue()) initialVelocity = defaults.initialVelocity
+    }
+
+    fun copy() = InterpolationOptions().also { it.mergeWith(this) }
+
+    companion object {
+        private val TYPES = setOf(
+            "linear", "accelerate", "decelerate", "accelerateDecelerate", "decelerateAccelerate", "fastOutSlowIn",
+            "overshoot", "spring",
+        )
+
+        @JvmStatic
+        fun parse(map: ReadableMap?): InterpolationOptions {
+            val options = InterpolationOptions()
+            if (map == null) return options
+            options.type = TextParser.parse(map, "type", TYPES)
+            options.factor = FractionParser.parse(map, "factor")
+            options.tension = FractionParser.parse(map, "tension")
+            options.mass = FractionParser.parse(map, "mass")
+            options.damping = FractionParser.parse(map, "damping")
+            options.stiffness = FractionParser.parse(map, "stiffness")
+            options.allowsOverdamping = BoolParser.parse(map, "allowsOverdamping")
+            options.initialVelocity = FractionParser.parse(map, "initialVelocity")
+            return options
+        }
+    }
+}
+
+/**
+ * `OptionsAnimationPropertyConfig`: the animation of one property of a view. `duration` and `startDelay` are in
+ * milliseconds and not below 0.
+ */
+class PropertyAnimationOptions {
+    @JvmField var from: Fraction = NullFraction()
+    @JvmField var to: Fraction = NullFraction()
+    @JvmField var duration: Fraction = NullFraction()
+    @JvmField var startDelay: Fraction = NullFraction()
+    @JvmField var interpolation = InterpolationOptions()
+
+    fun hasValue(): Boolean = from.hasValue() || to.hasValue() || duration.hasValue() || startDelay.hasValue() ||
+        interpolation.hasValue()
+
+    fun mergeWith(other: PropertyAnimationOptions) {
+        if (other.from.hasValue()) from = other.from
+        if (other.to.hasValue()) to = other.to
+        if (other.duration.hasValue()) duration = other.duration
+        if (other.startDelay.hasValue()) startDelay = other.startDelay
+        interpolation.mergeWith(other.interpolation)
+    }
+
+    fun mergeWithDefault(defaults: PropertyAnimationOptions) {
+        if (!from.hasValue()) from = defaults.from
+        if (!to.hasValue()) to = defaults.to
+        if (!duration.hasValue()) duration = defaults.duration
+        if (!startDelay.hasValue()) startDelay = defaults.startDelay
+        interpolation.mergeWithDefault(defaults.interpolation)
+    }
+
+    fun copy() = PropertyAnimationOptions().also { it.mergeWith(this) }
+
+    companion object {
+        @JvmStatic
+        fun parse(map: ReadableMap?): PropertyAnimationOptions {
+            val options = PropertyAnimationOptions()
+            if (map == null) return options
+            options.from = FractionParser.parse(map, "from")
+            options.to = FractionParser.parse(map, "to")
+            options.duration = FractionParser.parseDuration(map, "duration")
+            options.startDelay = FractionParser.parseDuration(map, "startDelay")
+            options.interpolation = map.group("interpolation") { InterpolationOptions.parse(it) }
+            return options
+        }
+    }
+}
+
+/**
+ * `ElementAnimation` (`AppearingElementAnimation`, `DisappearingElementAnimation`): the animation of one property of an
+ * element transition. `duration` and `startDelay` are in milliseconds and not below 0.
+ */
+class ElementAnimationOptions {
+    @JvmField var from: Fraction = NullFraction()
+    @JvmField var to: Fraction = NullFraction()
+    @JvmField var duration: Fraction = NullFraction()
+    @JvmField var startDelay: Fraction = NullFraction()
+    @JvmField var interpolation = InterpolationOptions()
+
+    fun hasValue(): Boolean = from.hasValue() || to.hasValue() || duration.hasValue() || startDelay.hasValue() ||
+        interpolation.hasValue()
+
+    fun mergeWith(other: ElementAnimationOptions) {
+        if (other.from.hasValue()) from = other.from
+        if (other.to.hasValue()) to = other.to
+        if (other.duration.hasValue()) duration = other.duration
+        if (other.startDelay.hasValue()) startDelay = other.startDelay
+        interpolation.mergeWith(other.interpolation)
+    }
+
+    fun mergeWithDefault(defaults: ElementAnimationOptions) {
+        if (!from.hasValue()) from = defaults.from
+        if (!to.hasValue()) to = defaults.to
+        if (!duration.hasValue()) duration = defaults.duration
+        if (!startDelay.hasValue()) startDelay = defaults.startDelay
+        interpolation.mergeWithDefault(defaults.interpolation)
+    }
+
+    fun copy() = ElementAnimationOptions().also { it.mergeWith(this) }
+
+    companion object {
+        @JvmStatic
+        fun parse(map: ReadableMap?): ElementAnimationOptions {
+            val options = ElementAnimationOptions()
+            if (map == null) return options
+            options.from = FractionParser.parse(map, "from")
+            options.to = FractionParser.parse(map, "to")
+            options.duration = FractionParser.parseDuration(map, "duration")
+            options.startDelay = FractionParser.parseDuration(map, "startDelay")
+            options.interpolation = map.group("interpolation") { InterpolationOptions.parse(it) }
+            return options
+        }
+    }
+}
+
+/**
+ * `ZoomTransitionOptions`: the zoom of a screen out of a view. `fromId: null` is an explicit "no view" ([Text.isNone]).
+ */
+class ZoomTransitionOptions {
+    @JvmField var fromId: Text = NullText()
+    @JvmField var enabled: Bool = NullBool()
+
+    fun hasValue(): Boolean = fromId.hasValue() || enabled.hasValue()
+
+    fun mergeWith(other: ZoomTransitionOptions) {
+        if (other.fromId.hasValue()) fromId = other.fromId
+        if (other.enabled.hasValue()) enabled = other.enabled
+    }
+
+    fun mergeWithDefault(defaults: ZoomTransitionOptions) {
+        if (!fromId.hasValue()) fromId = defaults.fromId
+        if (!enabled.hasValue()) enabled = defaults.enabled
+    }
+
+    fun copy() = ZoomTransitionOptions().also { it.mergeWith(this) }
+
+    companion object {
+        @JvmStatic
+        fun parse(map: ReadableMap?): ZoomTransitionOptions {
+            val options = ZoomTransitionOptions()
+            if (map == null) return options
+            options.fromId = TextParser.parse(map, "fromId")
+            options.enabled = BoolParser.parse(map, "enabled")
+            return options
+        }
+    }
+}

package/android/src/main/java/dev/apexnative/navigation/options/KeyCommandOptions.kt

@@ -0,0 +1,49 @@
+package dev.apexnative.navigation.options
+
+import com.facebook.react.bridge.ReadableMap
+import dev.apexnative.navigation.options.params.NullText
+import dev.apexnative.navigation.options.params.Text
+import dev.apexnative.navigation.options.parsers.StringListParser
+import dev.apexnative.navigation.options.parsers.TextParser
+
+/** An item of `keyCommands`: a keyboard shortcut of a screen. */
+class KeyCommandOptions {
+    @JvmField var id: Text = NullText()
+    @JvmField var input: Text = NullText()
+    /** Unknown modifiers are dropped. */
+    @JvmField var modifiers: List<String>? = null
+    @JvmField var title: Text = NullText()
+
+    fun hasValue(): Boolean = id.hasValue() || input.hasValue() || modifiers != null || title.hasValue()
+
+    fun mergeWith(other: KeyCommandOptions) {
+        if (other.id.hasValue()) id = other.id
+        if (other.input.hasValue()) input = other.input
+        other.modifiers?.let { modifiers = it }
+        if (other.title.hasValue()) title = other.title
+    }
+
+    fun mergeWithDefault(defaults: KeyCommandOptions) {
+        if (!id.hasValue()) id = defaults.id
+        if (!input.hasValue()) input = defaults.input
+        if (modifiers == null) modifiers = defaults.modifiers
+        if (!title.hasValue()) title = defaults.title
+    }
+
+    fun copy() = KeyCommandOptions().also { it.mergeWith(this) }
+
+    companion object {
+        private val MODIFIERS = setOf("command", "shift", "option", "alternate", "control")
+
+        @JvmStatic
+        fun parse(map: ReadableMap?): KeyCommandOptions {
+            val options = KeyCommandOptions()
+            if (map == null) return options
+            options.id = TextParser.parse(map, "id")
+            options.input = TextParser.parse(map, "input")
+            options.modifiers = StringListParser.parse(map, "modifiers", MODIFIERS)
+            options.title = TextParser.parse(map, "title")
+            return options
+        }
+    }
+}

package/android/src/main/java/dev/apexnative/navigation/options/LargeTitleOptions.kt

@@ -0,0 +1,78 @@
+package dev.apexnative.navigation.options
+
+import android.content.Context
+import com.facebook.react.bridge.ReadableMap
+import dev.apexnative.navigation.options.params.Bool
+import dev.apexnative.navigation.options.params.Fraction
+import dev.apexnative.navigation.options.params.NullBool
+import dev.apexnative.navigation.options.params.NullFraction
+import dev.apexnative.navigation.options.params.NullText
+import dev.apexnative.navigation.options.params.NullThemeColour
+import dev.apexnative.navigation.options.params.Text
+import dev.apexnative.navigation.options.params.ThemeColour
+import dev.apexnative.navigation.options.parsers.BoolParser
+import dev.apexnative.navigation.options.parsers.FontParser
+import dev.apexnative.navigation.options.parsers.FractionParser
+import dev.apexnative.navigation.options.parsers.TextParser
+
+/** `topBar.largeTitle`: the title big under the row of the bar, as Material 3's large top app bar. */
+class LargeTitleOptions {
+    @JvmField var visible: Bool = NullBool()
+    @JvmField var displayMode: Text = NullText()
+    @JvmField var collapseOnScroll: Bool = NullBool()
+    @JvmField var fontSize: Fraction = NullFraction()
+    @JvmField var color: ThemeColour = NullThemeColour()
+    @JvmField var font = FontOptions()
+
+    /**
+     * When the large title shows: [ALWAYS], [NEVER] or [AUTOMATIC], as on the screen below. `displayMode` over
+     * `visible`; `inline` puts the title in the row of the bar, as without a large title.
+     */
+    fun mode(): String = when (val mode = displayMode.get(null)) {
+        ALWAYS, AUTOMATIC -> mode
+        null -> if (visible.isTrue) ALWAYS else NEVER
+        else -> NEVER
+    }
+
+    fun mergeWith(other: LargeTitleOptions) {
+        if (other.visible.hasValue()) visible = other.visible
+        if (other.displayMode.hasValue()) displayMode = other.displayMode
+        if (other.collapseOnScroll.hasValue()) collapseOnScroll = other.collapseOnScroll
+        if (other.fontSize.hasValue()) fontSize = other.fontSize
+        color = color.mergeWith(other.color)
+        font.mergeWith(other.font)
+    }
+
+    fun mergeWithDefault(defaultOptions: LargeTitleOptions) {
+        if (!visible.hasValue()) visible = defaultOptions.visible
+        if (!displayMode.hasValue()) displayMode = defaultOptions.displayMode
+        if (!collapseOnScroll.hasValue()) collapseOnScroll = defaultOptions.collapseOnScroll
+        if (!fontSize.hasValue()) fontSize = defaultOptions.fontSize
+        color = color.withDefault(defaultOptions.color)
+        font.mergeWithDefault(defaultOptions.font)
+    }
+
+    /** Any of its options set: they change what shows. */
+    fun hasValue() = visible.hasValue() || displayMode.hasValue() || collapseOnScroll.hasValue() ||
+            fontSize.hasValue() || color.hasValue() || font.hasValue()
+
+    companion object {
+        const val ALWAYS = "always"
+        const val NEVER = "never"
+        const val AUTOMATIC = "automatic"
+        private val DISPLAY_MODES = setOf(ALWAYS, NEVER, AUTOMATIC, "inline")
+
+        @JvmStatic
+        fun parse(context: Context?, json: ReadableMap?): LargeTitleOptions {
+            val options = LargeTitleOptions()
+            if (json == null) return options
+            options.visible = BoolParser.parse(json, "visible")
+            options.displayMode = TextParser.parse(json, "displayMode", DISPLAY_MODES)
+            options.collapseOnScroll = BoolParser.parse(json, "collapseOnScroll")
+            options.fontSize = FractionParser.parse(json, "fontSize")
+            options.color = ThemeColour.parse(context, json, "color")
+            options.font = FontParser.parse(json)
+            return options
+        }
+    }
+}

package/android/src/main/java/dev/apexnative/navigation/options/LayoutAnimation.kt

@@ -0,0 +1,157 @@
+package dev.apexnative.navigation.options
+
+import com.facebook.react.bridge.ReadableMap
+
+/**
+ * The animation of a layout coming in or going out (`animations.push`, `pop`, `setStackRoot`, `showModal`,
+ * `dismissModal`): its shared elements (`sharedElementTransitions`) and its element transitions. Open: the animation of
+ * each command is its own group over these fields (a subclass with `mergeWith` of its own class, which calls this one's
+ * first).
+ */
+open class LayoutAnimation(
+    @JvmField var sharedElements: SharedElements = SharedElements(),
+    @JvmField var elementTransitions: ElementTransitions = ElementTransitions(),
+) {
+    open fun hasValue(): Boolean = sharedElements.hasValue() || elementTransitions.hasValue()
+
+    fun mergeWith(other: LayoutAnimation) {
+        sharedElements.mergeWith(other.sharedElements)
+        elementTransitions.mergeWith(other.elementTransitions)
+    }
+
+    fun mergeWithDefault(defaults: LayoutAnimation) {
+        sharedElements.mergeWithDefault(defaults.sharedElements)
+        elementTransitions.mergeWithDefault(defaults.elementTransitions)
+    }
+
+    open fun copy(): LayoutAnimation = LayoutAnimation().also { it.mergeWith(this) }
+
+    /** Reads the fields of this class from [map] into this animation; a subclass reads its own after it. */
+    protected fun readAnimation(map: ReadableMap) {
+        sharedElements =
+            SharedElements(map.groupList("sharedElementTransitions") { SharedElementTransitionOptions.parse(it) })
+        elementTransitions =
+            ElementTransitions(map.groupList("elementTransitions") { ElementTransitionOptions.parse(it) })
+    }
+
+    companion object {
+        @JvmStatic
+        fun parse(map: ReadableMap?): LayoutAnimation {
+            val animation = LayoutAnimation()
+            if (map != null) animation.readAnimation(map)
+            return animation
+        }
+    }
+}
+
+/** `sharedElementTransitions`: the shared elements of an animation; null when the options don't give them. */
+class SharedElements(@JvmField var elements: List<SharedElementTransitionOptions>? = null) {
+    /** The shared elements; none when the options don't give them. */
+    fun get(): List<SharedElementTransitionOptions> = elements.orEmpty()
+
+    /** The options give the list, `[]` included. */
+    fun hasValue(): Boolean = elements != null
+
+    fun mergeWith(other: SharedElements) {
+        other.elements?.let { elements = it.map(SharedElementTransitionOptions::copy) }
+    }
+
+    fun mergeWithDefault(defaults: SharedElements) {
+        if (elements == null) elements = defaults.elements?.map(SharedElementTransitionOptions::copy)
+    }
+
+    fun copy() = SharedElements().also { it.mergeWith(this) }
+}
+
+/**
+ * `elementTransitions`: views of one screen that move, fade or scale on their own during an animation; null when the
+ * options don't give them.
+ */
+class ElementTransitions(@JvmField var items: List<ElementTransitionOptions>? = null) {
+    /** The element transitions; none when the options don't give them. */
+    val transitions: List<ElementTransitionOptions>
+        get() = items.orEmpty()
+
+    /** The options give the list, `[]` included. */
+    fun hasValue(): Boolean = items != null
+
+    fun mergeWith(other: ElementTransitions) {
+        other.items?.let { items = it.map(ElementTransitionOptions::copy) }
+    }
+
+    fun mergeWithDefault(defaults: ElementTransitions) {
+        if (items == null) items = defaults.items?.map(ElementTransitionOptions::copy)
+    }
+
+    fun copy() = ElementTransitions().also { it.mergeWith(this) }
+}
+
+/**
+ * An element transition: the view with `nativeID` [id], on the screen that comes or the one that goes, and the
+ * animation of each of its properties (`ElementTransition`).
+ */
+class ElementTransitionOptions(@JvmField var id: String = "") {
+    @JvmField var alpha = ElementAnimationOptions()
+    @JvmField var x = ElementAnimationOptions()
+    @JvmField var y = ElementAnimationOptions()
+    @JvmField var translationX = ElementAnimationOptions()
+    @JvmField var translationY = ElementAnimationOptions()
+    @JvmField var scaleX = ElementAnimationOptions()
+    @JvmField var scaleY = ElementAnimationOptions()
+    @JvmField var rotationX = ElementAnimationOptions()
+    @JvmField var rotationY = ElementAnimationOptions()
+    @JvmField var rotation = ElementAnimationOptions()
+
+    fun hasValue(): Boolean = id.isNotEmpty() || alpha.hasValue() || x.hasValue() || y.hasValue() ||
+        translationX.hasValue() || translationY.hasValue() || scaleX.hasValue() || scaleY.hasValue() ||
+        rotationX.hasValue() || rotationY.hasValue() || rotation.hasValue()
+
+    fun mergeWith(other: ElementTransitionOptions) {
+        if (other.id.isNotEmpty()) id = other.id
+        alpha.mergeWith(other.alpha)
+        x.mergeWith(other.x)
+        y.mergeWith(other.y)
+        translationX.mergeWith(other.translationX)
+        translationY.mergeWith(other.translationY)
+        scaleX.mergeWith(other.scaleX)
+        scaleY.mergeWith(other.scaleY)
+        rotationX.mergeWith(other.rotationX)
+        rotationY.mergeWith(other.rotationY)
+        rotation.mergeWith(other.rotation)
+    }
+
+    fun mergeWithDefault(defaults: ElementTransitionOptions) {
+        if (id.isEmpty()) id = defaults.id
+        alpha.mergeWithDefault(defaults.alpha)
+        x.mergeWithDefault(defaults.x)
+        y.mergeWithDefault(defaults.y)
+        translationX.mergeWithDefault(defaults.translationX)
+        translationY.mergeWithDefault(defaults.translationY)
+        scaleX.mergeWithDefault(defaults.scaleX)
+        scaleY.mergeWithDefault(defaults.scaleY)
+        rotationX.mergeWithDefault(defaults.rotationX)
+        rotationY.mergeWithDefault(defaults.rotationY)
+        rotation.mergeWithDefault(defaults.rotation)
+    }
+
+    fun copy() = ElementTransitionOptions().also { it.mergeWith(this) }
+
+    companion object {
+        @JvmStatic
+        fun parse(map: ReadableMap?): ElementTransitionOptions {
+            val options = ElementTransitionOptions(map?.opt("id") as? String ?: "")
+            if (map == null) return options
+            options.alpha = map.group("alpha") { ElementAnimationOptions.parse(it) }
+            options.x = map.group("x") { ElementAnimationOptions.parse(it) }
+            options.y = map.group("y") { ElementAnimationOptions.parse(it) }
+            options.translationX = map.group("translationX") { ElementAnimationOptions.parse(it) }
+            options.translationY = map.group("translationY") { ElementAnimationOptions.parse(it) }
+            options.scaleX = map.group("scaleX") { ElementAnimationOptions.parse(it) }
+            options.scaleY = map.group("scaleY") { ElementAnimationOptions.parse(it) }
+            options.rotationX = map.group("rotationX") { ElementAnimationOptions.parse(it) }
+            options.rotationY = map.group("rotationY") { ElementAnimationOptions.parse(it) }
+            options.rotation = map.group("rotation") { ElementAnimationOptions.parse(it) }
+            return options
+        }
+    }
+}

package/android/src/main/java/dev/apexnative/navigation/options/LayoutOptions.kt

@@ -0,0 +1,94 @@
+package dev.apexnative.navigation.options
+
+import android.content.Context
+import com.facebook.react.bridge.ReadableMap
+import dev.apexnative.navigation.options.params.Bool
+import dev.apexnative.navigation.options.params.LayoutDirection
+import dev.apexnative.navigation.options.params.NullBool
+import dev.apexnative.navigation.options.params.NullText
+import dev.apexnative.navigation.options.params.NullThemeColour
+import dev.apexnative.navigation.options.params.Text
+import dev.apexnative.navigation.options.params.ThemeColour
+import dev.apexnative.navigation.options.parsers.BoolParser
+import dev.apexnative.navigation.options.parsers.StringListParser
+import dev.apexnative.navigation.options.parsers.TextParser
+
+/**
+ * `layout`: the look of a layout's own view and what it asks of the system, and the direction of the app (`direction`,
+ * only in the default options).
+ */
+class LayoutOptions {
+    @JvmField var safeAreaEdges: List<String>? = null
+    @JvmField var backgroundColor: ThemeColour = NullThemeColour()
+    @JvmField var componentBackgroundColor: ThemeColour = NullThemeColour()
+    @JvmField var orientation: List<String>? = null
+    @JvmField var verticalBars: Bool = NullBool()
+    @JvmField var drawBehindVerticalBar: Bool = NullBool()
+    @JvmField var autoHideHomeIndicator: Bool = NullBool()
+    @JvmField var deferSystemGestures: List<String>? = null
+    @JvmField var adjustResize: Bool = NullBool()
+    /** `ltr`, `rtl` or `locale`: the direction of the app; see [layoutDirection]. */
+    @JvmField var direction: Text = NullText()
+
+    /** [direction] as a view takes it; [LayoutDirection.DEFAULT] when unset. */
+    val layoutDirection: LayoutDirection
+        get() = LayoutDirection.fromString(direction.get(null))
+
+    fun hasValue(): Boolean = safeAreaEdges != null || backgroundColor.hasValue() ||
+        componentBackgroundColor.hasValue() || orientation != null || verticalBars.hasValue() ||
+        drawBehindVerticalBar.hasValue() || autoHideHomeIndicator.hasValue() || deferSystemGestures != null ||
+        adjustResize.hasValue() || direction.hasValue()
+
+    fun mergeWith(other: LayoutOptions) {
+        other.safeAreaEdges?.let { safeAreaEdges = it }
+        backgroundColor = backgroundColor.mergeWith(other.backgroundColor)
+        componentBackgroundColor = componentBackgroundColor.mergeWith(other.componentBackgroundColor)
+        other.orientation?.let { orientation = it }
+        if (other.verticalBars.hasValue()) verticalBars = other.verticalBars
+        if (other.drawBehindVerticalBar.hasValue()) drawBehindVerticalBar = other.drawBehindVerticalBar
+        if (other.autoHideHomeIndicator.hasValue()) autoHideHomeIndicator = other.autoHideHomeIndicator
+        other.deferSystemGestures?.let { deferSystemGestures = it }
+        if (other.adjustResize.hasValue()) adjustResize = other.adjustResize
+        if (other.direction.hasValue()) direction = other.direction
+    }
+
+    fun mergeWithDefault(defaultOptions: LayoutOptions) {
+        if (safeAreaEdges == null) safeAreaEdges = defaultOptions.safeAreaEdges
+        backgroundColor = backgroundColor.withDefault(defaultOptions.backgroundColor)
+        componentBackgroundColor = componentBackgroundColor.withDefault(defaultOptions.componentBackgroundColor)
+        if (orientation == null) orientation = defaultOptions.orientation
+        if (!verticalBars.hasValue()) verticalBars = defaultOptions.verticalBars
+        if (!drawBehindVerticalBar.hasValue()) drawBehindVerticalBar = defaultOptions.drawBehindVerticalBar
+        if (!autoHideHomeIndicator.hasValue()) autoHideHomeIndicator = defaultOptions.autoHideHomeIndicator
+        if (deferSystemGestures == null) deferSystemGestures = defaultOptions.deferSystemGestures
+        if (!adjustResize.hasValue()) adjustResize = defaultOptions.adjustResize
+        if (!direction.hasValue()) direction = defaultOptions.direction
+    }
+
+    fun copy() = LayoutOptions().also { it.mergeWith(this) }
+
+    companion object {
+        private val EDGES = setOf("top", "right", "bottom", "left")
+        private val ORIENTATIONS = setOf(
+            "all", "default", "portrait", "landscape", "upsideDown", "sensor", "sensorLandscape", "sensorPortrait",
+        )
+        private val DIRECTIONS = setOf("ltr", "rtl", "locale")
+
+        @JvmStatic
+        fun parse(context: Context?, map: ReadableMap?): LayoutOptions {
+            val options = LayoutOptions()
+            if (map == null) return options
+            options.safeAreaEdges = StringListParser.parse(map, "safeAreaEdges", EDGES)
+            options.backgroundColor = ThemeColour.parse(context, map, "backgroundColor")
+            options.componentBackgroundColor = ThemeColour.parse(context, map, "componentBackgroundColor")
+            options.orientation = StringListParser.parse(map, "orientation", ORIENTATIONS)
+            options.verticalBars = BoolParser.parse(map, "verticalBars")
+            options.drawBehindVerticalBar = BoolParser.parse(map, "drawBehindVerticalBar")
+            options.autoHideHomeIndicator = BoolParser.parse(map, "autoHideHomeIndicator")
+            options.deferSystemGestures = StringListParser.parse(map, "deferSystemGestures", EDGES)
+            options.adjustResize = BoolParser.parse(map, "adjustResize")
+            options.direction = TextParser.parse(map, "direction", DIRECTIONS)
+            return options
+        }
+    }
+}

package/android/src/main/java/dev/apexnative/navigation/options/ModalOptions.kt

@@ -0,0 +1,87 @@
+package dev.apexnative.navigation.options
+
+import com.facebook.react.bridge.ReadableMap
+import dev.apexnative.navigation.options.params.Bool
+import dev.apexnative.navigation.options.params.NullBool
+import dev.apexnative.navigation.options.params.NullText
+import dev.apexnative.navigation.options.params.Text
+import dev.apexnative.navigation.options.parsers.BoolParser
+import dev.apexnative.navigation.options.parsers.TextParser
+
+/**
+ * `modal`: how a modal shows; `sheet` is the group of the sheet module, which keeps its own reading and merging.
+ */
+class ModalOptions {
+    @JvmField var sheet = SheetOptions()
+    @JvmField var contentSize = ModalContentSizeOptions()
+    @JvmField var popover = ModalPopoverOptions()
+    @JvmField var testID: Text = NullText()
+    /** Internal: a swipe down dismisses the modal. */
+    @JvmField var swipeToDismiss: Bool = NullBool()
+
+    fun hasValue(): Boolean = sheet.hasValue || contentSize.hasValue() || popover.hasValue() || testID.hasValue() ||
+        swipeToDismiss.hasValue()
+
+    fun mergeWith(other: ModalOptions) {
+        sheet.mergeWith(other.sheet)
+        contentSize.mergeWith(other.contentSize)
+        popover.mergeWith(other.popover)
+        if (other.testID.hasValue()) testID = other.testID
+        if (other.swipeToDismiss.hasValue()) swipeToDismiss = other.swipeToDismiss
+    }
+
+    fun mergeWithDefault(defaults: ModalOptions) {
+        sheet.mergeWithDefault(defaults.sheet)
+        contentSize.mergeWithDefault(defaults.contentSize)
+        popover.mergeWithDefault(defaults.popover)
+        if (!testID.hasValue()) testID = defaults.testID
+        if (!swipeToDismiss.hasValue()) swipeToDismiss = defaults.swipeToDismiss
+    }
+
+    fun copy() = ModalOptions().also { it.mergeWith(this) }
+
+    companion object {
+        @JvmStatic
+        fun parse(map: ReadableMap?): ModalOptions {
+            val options = ModalOptions()
+            if (map == null) return options
+            options.sheet = map.group("sheet") { SheetOptions.parse(it) }
+            options.contentSize = map.group("contentSize") { ModalContentSizeOptions.parse(it) }
+            options.popover = map.group("popover") { ModalPopoverOptions.parse(it) }
+            options.testID = TextParser.parse(map, "testID")
+            options.swipeToDismiss = BoolParser.parse(map, "swipeToDismiss")
+            return options
+        }
+    }
+}
+
+/** `overlay`: how an overlay takes touches. */
+class OverlayOptions {
+    @JvmField var interceptTouchOutside: Bool = NullBool()
+    @JvmField var testID: Text = NullText()
+
+    fun hasValue(): Boolean = interceptTouchOutside.hasValue() || testID.hasValue()
+
+    fun mergeWith(other: OverlayOptions) {
+        if (other.interceptTouchOutside.hasValue()) interceptTouchOutside = other.interceptTouchOutside
+        if (other.testID.hasValue()) testID = other.testID
+    }
+
+    fun mergeWithDefault(defaults: OverlayOptions) {
+        if (!interceptTouchOutside.hasValue()) interceptTouchOutside = defaults.interceptTouchOutside
+        if (!testID.hasValue()) testID = defaults.testID
+    }
+
+    fun copy() = OverlayOptions().also { it.mergeWith(this) }
+
+    companion object {
+        @JvmStatic
+        fun parse(map: ReadableMap?): OverlayOptions {
+            val options = OverlayOptions()
+            if (map == null) return options
+            options.interceptTouchOutside = BoolParser.parse(map, "interceptTouchOutside")
+            options.testID = TextParser.parse(map, "testID")
+            return options
+        }
+    }
+}