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

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

@@ -0,0 +1,90 @@
+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.NullVariant
+import dev.apexnative.navigation.options.params.Text
+import dev.apexnative.navigation.options.params.Variant
+import dev.apexnative.navigation.options.parsers.BoolParser
+import dev.apexnative.navigation.options.parsers.FractionParser
+import dev.apexnative.navigation.options.parsers.StringListParser
+import dev.apexnative.navigation.options.parsers.TextParser
+import dev.apexnative.navigation.options.parsers.VariantParser
+
+/** `modal.contentSize` (`OptionsModalContentSize`): the size of a modal, in dp. `height` is a number or `'content'`. */
+class ModalContentSizeOptions {
+    @JvmField var width: Fraction = NullFraction()
+    /** `number | 'content'`. */
+    @JvmField var height: Variant = NullVariant()
+
+    fun hasValue(): Boolean = width.hasValue() || height.hasValue()
+
+    fun mergeWith(other: ModalContentSizeOptions) {
+        if (other.width.hasValue()) width = other.width
+        if (other.height.hasValue()) height = other.height
+    }
+
+    fun mergeWithDefault(defaults: ModalContentSizeOptions) {
+        if (!width.hasValue()) width = defaults.width
+        if (!height.hasValue()) height = defaults.height
+    }
+
+    fun copy() = ModalContentSizeOptions().also { it.mergeWith(this) }
+
+    companion object {
+        @JvmStatic
+        fun parse(map: ReadableMap?): ModalContentSizeOptions {
+            val options = ModalContentSizeOptions()
+            if (map == null) return options
+            options.width = FractionParser.parse(map, "width")
+            options.height = VariantParser.parse(map, "height", numbers = true, texts = setOf("content"))
+            return options
+        }
+    }
+}
+
+/** `modal.popover` (`OptionsModalPopover`): where a modal shown as a popover points to. */
+class ModalPopoverOptions {
+    @JvmField var sourceButtonId: Text = NullText()
+    @JvmField var sourceNativeID: Text = NullText()
+    @JvmField var arrowDirections: List<String>? = null
+    @JvmField var adaptive: Bool = NullBool()
+
+    fun hasValue(): Boolean = sourceButtonId.hasValue() || sourceNativeID.hasValue() || arrowDirections != null ||
+        adaptive.hasValue()
+
+    fun mergeWith(other: ModalPopoverOptions) {
+        if (other.sourceButtonId.hasValue()) sourceButtonId = other.sourceButtonId
+        if (other.sourceNativeID.hasValue()) sourceNativeID = other.sourceNativeID
+        other.arrowDirections?.let { arrowDirections = it }
+        if (other.adaptive.hasValue()) adaptive = other.adaptive
+    }
+
+    fun mergeWithDefault(defaults: ModalPopoverOptions) {
+        if (!sourceButtonId.hasValue()) sourceButtonId = defaults.sourceButtonId
+        if (!sourceNativeID.hasValue()) sourceNativeID = defaults.sourceNativeID
+        if (arrowDirections == null) arrowDirections = defaults.arrowDirections
+        if (!adaptive.hasValue()) adaptive = defaults.adaptive
+    }
+
+    fun copy() = ModalPopoverOptions().also { it.mergeWith(this) }
+
+    companion object {
+        private val ARROW_DIRECTIONS = setOf("up", "down", "left", "right")
+
+        @JvmStatic
+        fun parse(map: ReadableMap?): ModalPopoverOptions {
+            val options = ModalPopoverOptions()
+            if (map == null) return options
+            options.sourceButtonId = TextParser.parse(map, "sourceButtonId")
+            options.sourceNativeID = TextParser.parse(map, "sourceNativeID")
+            options.arrowDirections = StringListParser.parse(map, "arrowDirections", ARROW_DIRECTIONS)
+            options.adaptive = BoolParser.parse(map, "adaptive")
+            return options
+        }
+    }
+}

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

@@ -0,0 +1,44 @@
+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.NullBool
+import dev.apexnative.navigation.options.params.NullThemeColour
+import dev.apexnative.navigation.options.params.ThemeColour
+import dev.apexnative.navigation.options.parsers.BoolParser
+
+/** `navigationBar`: Android's navigation bar under a screen. */
+class NavigationBarOptions {
+    @JvmField var backgroundColor: ThemeColour = NullThemeColour()
+    @JvmField var visible: Bool = NullBool()
+    @JvmField var drawBehind: Bool = NullBool()
+
+    fun hasValue(): Boolean = backgroundColor.hasValue() || visible.hasValue() || drawBehind.hasValue()
+
+    fun mergeWith(other: NavigationBarOptions) {
+        backgroundColor = backgroundColor.mergeWith(other.backgroundColor)
+        if (other.visible.hasValue()) visible = other.visible
+        if (other.drawBehind.hasValue()) drawBehind = other.drawBehind
+    }
+
+    fun mergeWithDefault(defaults: NavigationBarOptions) {
+        backgroundColor = backgroundColor.withDefault(defaults.backgroundColor)
+        if (!visible.hasValue()) visible = defaults.visible
+        if (!drawBehind.hasValue()) drawBehind = defaults.drawBehind
+    }
+
+    fun copy() = NavigationBarOptions().also { it.mergeWith(this) }
+
+    companion object {
+        @JvmStatic
+        fun parse(context: Context?, map: ReadableMap?): NavigationBarOptions {
+            val options = NavigationBarOptions()
+            if (map == null) return options
+            options.backgroundColor = ThemeColour.parse(context, map, "backgroundColor")
+            options.visible = BoolParser.parse(map, "visible")
+            options.drawBehind = BoolParser.parse(map, "drawBehind")
+            return options
+        }
+    }
+}

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

@@ -0,0 +1,167 @@
+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.NullBool
+import dev.apexnative.navigation.options.params.NullFraction
+import dev.apexnative.navigation.options.params.NullText
+import dev.apexnative.navigation.options.params.NullVariant
+import dev.apexnative.navigation.options.params.Text
+import dev.apexnative.navigation.options.params.Variant
+import dev.apexnative.navigation.options.parsers.BoolParser
+import dev.apexnative.navigation.options.parsers.TextParser
+import dev.apexnative.navigation.options.parsers.VariantParser
+
+/**
+ * The options of a layout, read once from the JSON JavaScript sends ([OptionsReader]): a node's own, the result of a
+ * merge, or its own over those of the layouts around it and the default options. Every group merges key by key at any
+ * depth; a value replaces; an array replaces whole, `[]` included; a key the upper side doesn't set leaves the lower
+ * one; colors merge side by side. Merging copies groups and lists of groups, so two options never share one; values are
+ * immutable and may be shared. The one exception is a button menu ([ButtonMenuOptions]), shared on purpose.
+ *
+ * Fields follow the TS interface `Options` (`src/interfaces/Options.ts`); `window` and `layout.direction` come only in
+ * the default options.
+ */
+class Options {
+    @JvmField var topBar = TopBarOptions()
+    @JvmField var toolbar = ToolbarOptions()
+    @JvmField var scrollEdgeEffect = ScrollEdgeEffectOptions()
+    @JvmField var statusBar = StatusBarOptions()
+    @JvmField var navigationBar = NavigationBarOptions()
+    @JvmField var layout = LayoutOptions()
+    @JvmField var modal = ModalOptions()
+    @JvmField var modalPresentationStyle: Text = NullText()
+    @JvmField var modalTransitionStyle: Text = NullText()
+    @JvmField var overlay = OverlayOptions()
+    @JvmField var sideMenu = SideMenuOptions()
+    @JvmField var splitView = SplitViewGroupOptions()
+    @JvmField var bottomTabs = BottomTabsOptions()
+    @JvmField var bottomTab = BottomTabOptions()
+    @JvmField var animations = AnimationsOptions()
+    /** `boolean | 'edge'`. */
+    @JvmField var popGesture: Variant = NullVariant()
+    @JvmField var hardwareBackButton = HardwareBackButtonOptions()
+    @JvmField var fab = FabOptions()
+    /** `keyCommands`; null when the options don't give them. */
+    @JvmField var keyCommands: List<KeyCommandOptions>? = null
+    @JvmField var blurOnUnmount: Bool = NullBool()
+    @JvmField var preview = PreviewOptions()
+    @JvmField var window = WindowOptions()
+
+    /** A copy of every group: changing it leaves these options as they are. */
+    fun copy(): Options = Options().mergeWith(this)
+
+    /** The values [other] gives go over these; returns these options. */
+    fun mergeWith(other: Options): Options {
+        topBar.mergeWith(other.topBar)
+        toolbar.mergeWith(other.toolbar)
+        scrollEdgeEffect.mergeWith(other.scrollEdgeEffect)
+        statusBar.mergeWith(other.statusBar)
+        navigationBar.mergeWith(other.navigationBar)
+        layout.mergeWith(other.layout)
+        modal.mergeWith(other.modal)
+        if (other.modalPresentationStyle.hasValue()) modalPresentationStyle = other.modalPresentationStyle
+        if (other.modalTransitionStyle.hasValue()) modalTransitionStyle = other.modalTransitionStyle
+        overlay.mergeWith(other.overlay)
+        sideMenu.mergeWith(other.sideMenu)
+        splitView.mergeWith(other.splitView)
+        bottomTabs.mergeWith(other.bottomTabs)
+        bottomTab.mergeWith(other.bottomTab)
+        animations.mergeWith(other.animations)
+        if (other.popGesture.hasValue()) popGesture = other.popGesture
+        hardwareBackButton.mergeWith(other.hardwareBackButton)
+        fab.mergeWith(other.fab)
+        other.keyCommands?.let { keyCommands = it.map(KeyCommandOptions::copy) }
+        if (other.blurOnUnmount.hasValue()) blurOnUnmount = other.blurOnUnmount
+        preview.mergeWith(other.preview)
+        window.mergeWith(other.window)
+        return this
+    }
+
+    /**
+     * The values these options don't give come from [defaultOptions], which doesn't change and shares no group with
+     * these options afterwards; returns these options.
+     */
+    fun withDefaultOptions(defaultOptions: Options): Options {
+        topBar.mergeWithDefault(defaultOptions.topBar)
+        toolbar.mergeWithDefault(defaultOptions.toolbar)
+        scrollEdgeEffect.mergeWithDefault(defaultOptions.scrollEdgeEffect)
+        statusBar.mergeWithDefault(defaultOptions.statusBar)
+        navigationBar.mergeWithDefault(defaultOptions.navigationBar)
+        layout.mergeWithDefault(defaultOptions.layout)
+        modal.mergeWithDefault(defaultOptions.modal)
+        if (!modalPresentationStyle.hasValue()) modalPresentationStyle = defaultOptions.modalPresentationStyle
+        if (!modalTransitionStyle.hasValue()) modalTransitionStyle = defaultOptions.modalTransitionStyle
+        overlay.mergeWithDefault(defaultOptions.overlay)
+        sideMenu.mergeWithDefault(defaultOptions.sideMenu)
+        splitView.mergeWithDefault(defaultOptions.splitView)
+        bottomTabs.mergeWithDefault(defaultOptions.bottomTabs)
+        bottomTab.mergeWithDefault(defaultOptions.bottomTab)
+        animations.mergeWithDefault(defaultOptions.animations)
+        if (!popGesture.hasValue()) popGesture = defaultOptions.popGesture
+        hardwareBackButton.mergeWithDefault(defaultOptions.hardwareBackButton)
+        fab.mergeWithDefault(defaultOptions.fab)
+        if (keyCommands == null) keyCommands = defaultOptions.keyCommands?.map(KeyCommandOptions::copy)
+        if (!blurOnUnmount.hasValue()) blurOnUnmount = defaultOptions.blurOnUnmount
+        preview.mergeWithDefault(defaultOptions.preview)
+        window.mergeWithDefault(defaultOptions.window)
+        return this
+    }
+
+    /** One of the options that act once is set ([clearOneShotOptions]). */
+    fun hasOneShotOptions(): Boolean = bottomTabs.currentTabIndex.hasValue() || bottomTabs.currentTabId.hasValue() ||
+        sideMenu.left.visible.hasValue() || sideMenu.right.visible.hasValue()
+
+    /**
+     * Takes away the options that act once: `bottomTabs.currentTabIndex`, `bottomTabs.currentTabId`,
+     * `sideMenu.left.visible`, `sideMenu.right.visible`. A node's own options never keep them; whoever acts on them
+     * reads them from the options that bring them (the layout's at creation, the merged ones at `mergeOptions`).
+     */
+    fun clearOneShotOptions() {
+        bottomTabs.currentTabIndex = NullFraction()
+        bottomTabs.currentTabId = NullText()
+        sideMenu.left.visible = NullBool()
+        sideMenu.right.visible = NullBool()
+    }
+
+    companion object {
+        private val PRESENTATION_STYLES = setOf(
+            "pageSheet", "formSheet", "fullScreen", "overFullScreen", "overCurrentContext", "currentContext", "popover",
+        )
+        private val TRANSITION_STYLES = setOf("coverVertical", "crossDissolve", "flipHorizontal", "partialCurl")
+
+        /**
+         * Reads the options of [map]; [context] resolves platform colors. Use [OptionsReader.read], which also gives
+         * the path of a value that couldn't be read.
+         */
+        @JvmStatic
+        fun parse(context: Context?, map: ReadableMap?): Options {
+            val options = Options()
+            if (map == null) return options
+            options.topBar = map.group("topBar") { TopBarOptions.parse(context, it) }
+            options.toolbar = map.group("toolbar") { ToolbarOptions.parse(context, it) }
+            options.scrollEdgeEffect = map.group("scrollEdgeEffect") { ScrollEdgeEffectOptions.parse(it) }
+            options.statusBar = map.group("statusBar") { StatusBarOptions.parse(context, it) }
+            options.navigationBar = map.group("navigationBar") { NavigationBarOptions.parse(context, it) }
+            options.layout = map.group("layout") { LayoutOptions.parse(context, it) }
+            options.modal = map.group("modal") { ModalOptions.parse(it) }
+            options.modalPresentationStyle = TextParser.parse(map, "modalPresentationStyle", PRESENTATION_STYLES)
+            options.modalTransitionStyle = TextParser.parse(map, "modalTransitionStyle", TRANSITION_STYLES)
+            options.overlay = map.group("overlay") { OverlayOptions.parse(it) }
+            options.sideMenu = map.group("sideMenu") { SideMenuOptions.parse(it) }
+            options.splitView = map.group("splitView") { SplitViewGroupOptions.parse(it) }
+            options.bottomTabs = map.group("bottomTabs") { BottomTabsOptions.parse(context, it) }
+            options.bottomTab = map.group("bottomTab") { BottomTabOptions.parse(context, it) }
+            options.animations = map.group("animations") { AnimationsOptions.parse(it) }
+            options.popGesture = VariantParser.parse(map, "popGesture", booleans = true, texts = setOf("edge"))
+            options.hardwareBackButton = map.group("hardwareBackButton") { HardwareBackButtonOptions.parse(it) }
+            options.fab = map.group("fab") { FabOptions.parse(context, it) }
+            options.keyCommands = map.groupList("keyCommands") { KeyCommandOptions.parse(it) }
+            options.blurOnUnmount = BoolParser.parse(map, "blurOnUnmount")
+            options.preview = map.group("preview") { PreviewOptions.parse(it) }
+            options.window = map.group("window") { WindowOptions.parse(context, it) }
+            return options
+        }
+    }
+}

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

@@ -0,0 +1,21 @@
+package dev.apexnative.navigation.options
+
+/**
+ * The one point where the options of the app change: a process-wide generation that grows at each change. A node's
+ * resolved options are kept while the generation stays and the nodes they were built along are the same
+ * (`ViewController.resolveCurrentOptions`). Exactly two places call [optionsChanged]: the write of a node's own options
+ * (`ViewController.options`, and `changeOptions` through it) and the store of new default options
+ * ([DefaultOptions.set]). Nothing else changes a node's own options or the defaults. Main thread only.
+ */
+object OptionsCache {
+    /** The generation of the options; it only grows. */
+    @JvmStatic
+    var generation: Long = 0
+        private set
+
+    /** A node's own options or the default options changed: every resolved result built before is stale. */
+    @JvmStatic
+    fun optionsChanged() {
+        generation++
+    }
+}

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

@@ -0,0 +1,133 @@
+package dev.apexnative.navigation.options
+
+import android.content.Context
+import com.facebook.react.bridge.ReadableArray
+import com.facebook.react.bridge.ReadableMap
+
+/**
+ * Reads an options tree from React Native's data into typed [Options], on the thread the data came on (the
+ * native-modules thread). Reading is tolerant: a value of the wrong kind is unset, a group that isn't an object is
+ * empty, unknown keys are not read, and nothing stops the rest of the tree. An exception while reading a value is
+ * caught around the group it happened in: that group reads as empty, and the dotted path of the first such value is
+ * kept ([Result.unreadablePath]), for the text `unreadableOption` of the command.
+ *
+ * Groups read their children through [group] and [groupList], which keep the path; their values through the parsers
+ * of `parsers/` and `ThemeColour.parse`.
+ */
+object OptionsReader {
+    /** The options read, and the path of the first value that could not be read; none when all could. */
+    class Result(
+        /** The options, every value that could be read. */
+        @JvmField val options: Options,
+        /** `topBar.rightButtons[1].icon`; none when every value could be read. */
+        @JvmField val unreadablePath: String?,
+    )
+
+    /** Reads [map] whole; [context] (the app's) is the one colors resolve platform colors with, none in unit tests. */
+    @JvmStatic
+    fun read(map: ReadableMap?, context: Context?): Result {
+        val state = State()
+        val previous = current.get()
+        current.set(state)
+        try {
+            val options = try {
+                Options.parse(context, map)
+            } catch (e: Exception) {
+                state.failed(e)
+                Options()
+            }
+            return Result(options, state.unreadable)
+        } finally {
+            current.set(previous)
+        }
+    }
+
+    /** The dotted path of [key] in the group being read now; [key] alone outside a reading. */
+    internal fun pathOf(key: String): String = current.get()?.pathWith(key) ?: key
+
+    // The path of the group being read, and the first value that could not be read. One per reading thread.
+    private class State {
+        val path = ArrayList<String>()
+        var unreadable: String? = null
+
+        fun pathWith(segment: String): String {
+            if (path.isEmpty()) return segment
+            val base = path.joinToString(".")
+            return if (segment.startsWith("[")) base + segment else "$base.$segment"
+        }
+
+        fun failed(e: Exception) {
+            if (unreadable != null) return
+            unreadable = when {
+                e is UnreadableValueException -> pathWith(e.segment)
+                path.isEmpty() -> ""
+                else -> path.joinToString(".")
+            }
+        }
+    }
+
+    private val current = ThreadLocal<State?>()
+
+    internal fun enter(segment: String) {
+        current.get()?.path?.add(segment)
+    }
+
+    internal fun leave() {
+        current.get()?.path?.let { if (it.isNotEmpty()) it.removeAt(it.size - 1) }
+    }
+
+    internal fun failed(e: Exception) {
+        current.get()?.failed(e)
+    }
+}
+
+/**
+ * The group of [key], read by [parse] from its object; [parse] gets null for a missing key, `null`, or a value that
+ * isn't an object, and gives the empty group then. An exception while reading it gives the empty group too, and keeps
+ * the path of the failure.
+ */
+internal inline fun <G> ReadableMap.group(key: String, parse: (ReadableMap?) -> G): G {
+    // The map is read before the key is entered: a failure of the read itself is the key's own, not a child's.
+    val map = try {
+        optMap(key)
+    } catch (e: Exception) {
+        OptionsReader.failed(e)
+        return parse(null)
+    }
+    OptionsReader.enter(key)
+    try {
+        return parse(map)
+    } catch (e: Exception) {
+        OptionsReader.failed(e)
+        return parse(null)
+    } finally {
+        OptionsReader.leave()
+    }
+}
+
+/**
+ * The array of groups of [key], each item read by [parse] as [group] reads one (an item that isn't an object is an
+ * empty group); null when the key is missing or isn't an array. `[]` is an empty list: it replaces what the layers
+ * below give.
+ */
+internal inline fun <G> ReadableMap.groupList(key: String, parse: (ReadableMap?) -> G): List<G>? {
+    val array = optArray(key) ?: return null
+    return (0 until array.size()).map { index ->
+        OptionsReader.enter("$key[$index]")
+        try {
+            parse(itemAt(array, index))
+        } catch (e: Exception) {
+            OptionsReader.failed(e)
+            parse(null)
+        } finally {
+            OptionsReader.leave()
+        }
+    }
+}
+
+// The object at [index]; an item React Native can't give fails as the item itself, whose path the reading holds.
+internal fun itemAt(array: ReadableArray, index: Int): ReadableMap? = try {
+    array.optMap(index)
+} catch (e: UnreadableValueException) {
+    throw IllegalStateException("the item can't be read", e)
+}

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

@@ -0,0 +1,97 @@
+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 item of the menu of a preview (`PreviewMenuItem`); `actions` makes it a submenu. */
+class PreviewMenuItemOptions {
+    @JvmField var id: Text = NullText()
+    @JvmField var title: Text = NullText()
+    @JvmField var style: Text = NullText()
+    @JvmField var actions: List<PreviewMenuItemOptions>? = null
+
+    fun hasValue(): Boolean = id.hasValue() || title.hasValue() || style.hasValue() || actions != null
+
+    fun mergeWith(other: PreviewMenuItemOptions) {
+        if (other.id.hasValue()) id = other.id
+        if (other.title.hasValue()) title = other.title
+        if (other.style.hasValue()) style = other.style
+        other.actions?.let { actions = it.map(PreviewMenuItemOptions::copy) }
+    }
+
+    fun mergeWithDefault(defaults: PreviewMenuItemOptions) {
+        if (!id.hasValue()) id = defaults.id
+        if (!title.hasValue()) title = defaults.title
+        if (!style.hasValue()) style = defaults.style
+        if (actions == null) actions = defaults.actions?.map(PreviewMenuItemOptions::copy)
+    }
+
+    fun copy() = PreviewMenuItemOptions().also { it.mergeWith(this) }
+
+    companion object {
+        private val STYLES = setOf("default", "selected", "destructive")
+
+        @JvmStatic
+        fun parse(map: ReadableMap?): PreviewMenuItemOptions {
+            val options = PreviewMenuItemOptions()
+            if (map == null) return options
+            options.id = TextParser.parse(map, "id")
+            options.title = TextParser.parse(map, "title")
+            options.style = TextParser.parse(map, "style", STYLES)
+            options.actions = map.groupList("actions") { PreviewMenuItemOptions.parse(it) }
+            return options
+        }
+    }
+}
+
+/** `preview` (`PreviewOptions`): the preview of a screen that a long press on the view with `nativeID` shows. */
+class PreviewOptions {
+    @JvmField var nativeID: Text = NullText()
+    @JvmField var commit: Bool = NullBool()
+    @JvmField var actions: List<PreviewMenuItemOptions>? = null
+    @JvmField var width: Fraction = NullFraction()
+    @JvmField var height: Fraction = NullFraction()
+
+    fun hasValue(): Boolean = nativeID.hasValue() || commit.hasValue() || actions != null || width.hasValue() ||
+        height.hasValue()
+
+    fun mergeWith(other: PreviewOptions) {
+        if (other.nativeID.hasValue()) nativeID = other.nativeID
+        if (other.commit.hasValue()) commit = other.commit
+        other.actions?.let { actions = it.map(PreviewMenuItemOptions::copy) }
+        if (other.width.hasValue()) width = other.width
+        if (other.height.hasValue()) height = other.height
+    }
+
+    fun mergeWithDefault(defaults: PreviewOptions) {
+        if (!nativeID.hasValue()) nativeID = defaults.nativeID
+        if (!commit.hasValue()) commit = defaults.commit
+        if (actions == null) actions = defaults.actions?.map(PreviewMenuItemOptions::copy)
+        if (!width.hasValue()) width = defaults.width
+        if (!height.hasValue()) height = defaults.height
+    }
+
+    fun copy() = PreviewOptions().also { it.mergeWith(this) }
+
+    companion object {
+        @JvmStatic
+        fun parse(map: ReadableMap?): PreviewOptions {
+            val options = PreviewOptions()
+            if (map == null) return options
+            options.nativeID = TextParser.parse(map, "nativeID")
+            options.commit = BoolParser.parse(map, "commit")
+            options.actions = map.groupList("actions") { PreviewMenuItemOptions.parse(it) }
+            options.width = FractionParser.parse(map, "width")
+            options.height = FractionParser.parse(map, "height")
+            return options
+        }
+    }
+}

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

@@ -0,0 +1,70 @@
+package dev.apexnative.navigation.options
+
+import com.facebook.react.bridge.ReadableArray
+import com.facebook.react.bridge.ReadableMap
+import com.facebook.react.bridge.ReadableType
+
+// Reading the options straight from React Native's data: a value of another kind than the one asked for is none, never
+// converted (`"12"` is no number, `1` no yes or no). A failure of React Native's own reading throws an
+// [UnreadableValueException] with the key, which the group around it catches (`OptionsReader`).
+
+/**
+ * A value of the options that React Native's data could not give: [segment] is its key, or `key[index]` in an array.
+ * The group it is in reads as empty, and the path of the first such value is kept (`OptionsReader`).
+ */
+internal class UnreadableValueException(val segment: String, cause: Throwable) : RuntimeException(cause)
+
+/** The map has [key], `null` included. */
+internal fun ReadableMap.has(key: String): Boolean = hasKey(key)
+
+/**
+ * The value of [key] as Kotlin has it: a `String`, a `Double`, a `Boolean`, a [ReadableMap] or a [ReadableArray];
+ * null when the key is missing or `null`.
+ */
+internal fun ReadableMap.opt(key: String): Any? {
+    if (!hasKey(key)) return null
+    return try {
+        when (getType(key)) {
+            ReadableType.Null -> null
+            ReadableType.Boolean -> getBoolean(key)
+            ReadableType.Number -> getDouble(key)
+            ReadableType.String -> getString(key)
+            ReadableType.Map -> getMap(key)
+            ReadableType.Array -> getArray(key)
+        }
+    } catch (e: RuntimeException) {
+        throw UnreadableValueException(key, e)
+    }
+}
+
+/** The object of [key]; null when it is missing or of another kind. */
+internal fun ReadableMap.optMap(key: String): ReadableMap? = opt(key) as? ReadableMap
+
+/** The array of [key]; null when it is missing or of another kind. */
+internal fun ReadableMap.optArray(key: String): ReadableArray? = opt(key) as? ReadableArray
+
+/** The string of [key]; [fallback] when it is missing or of another kind. */
+internal fun ReadableMap.optString(key: String, fallback: String = ""): String = opt(key) as? String ?: fallback
+
+/** The yes or no of [key]; [fallback] when it is missing or of another kind. */
+internal fun ReadableMap.optBoolean(key: String, fallback: Boolean = false): Boolean = opt(key) as? Boolean ?: fallback
+
+/** The item at [index], as [ReadableMap.opt] gives a value; null out of the array. */
+internal fun ReadableArray.opt(index: Int): Any? {
+    if (index < 0 || index >= size()) return null
+    return try {
+        when (getType(index)) {
+            ReadableType.Null -> null
+            ReadableType.Boolean -> getBoolean(index)
+            ReadableType.Number -> getDouble(index)
+            ReadableType.String -> getString(index)
+            ReadableType.Map -> getMap(index)
+            ReadableType.Array -> getArray(index)
+        }
+    } catch (e: RuntimeException) {
+        throw UnreadableValueException("[$index]", e)
+    }
+}
+
+/** The object at [index]; null when it is of another kind or out of the array. */
+internal fun ReadableArray.optMap(index: Int): ReadableMap? = opt(index) as? ReadableMap