Summary
With full-bleed content (the behavior requested in #4), position: fixed top-anchored overlays — banners, toasts, modal headers — render under the iOS status bar unless the app hand-rolls env(safe-area-inset-top) math. The gem's .native-inset-top helpers cover in-flow layout (they inject an ::before spacer) but nothing covers fixed overlays, and the pattern isn't documented. We've now shipped the same one-line fix three separate times, each one first reported as a device-only bug by a tester.
Setup
- Cora (
cora.computer) — Rails 8 + Inertia/React, ruby_native 0.10.11, Normal Mode iOS shell, full-bleed webview
What we hit (three independent device-reported bugs, same root cause)
- Full-screen preview modal: header rendered beneath the notch — the Close button was visible but untappable. Fix:
pt-[max(0.75rem,env(safe-area-inset-top))] on the modal container.
- Account-reconnect banner (
fixed top-3): the clock/battery painted straight over the banner copy (tester screenshot). Fix: top: max(0.75rem, calc(env(safe-area-inset-top, 0px) + 0.5rem)).
- Welcome overlay: same story, same fix.
None of these reproduce in desktop Safari/Chrome or simulators without a notch, so each burned a report → triage → device-verify loop before the obvious fix.
Asks
- Document the fixed-overlay pattern alongside the full-bleed /
.native-inset docs: "any position: fixed element anchored with top: needs max(<your-offset>, env(safe-area-inset-top) + <gap>)" — one paragraph would have saved us three bug cycles.
- Bless
--ruby-native-safe-area-inset-top as public API. ruby_native.css already defines the helpers via var(--ruby-native-safe-area-inset-top, env(safe-area-inset-top)) — with the comment that Android's WebView doesn't populate env(safe-area-inset-*). That means our pure-env() fixes above are iOS-only and will silently collapse to 0 on the Android shell. If apps are supposed to write var(--ruby-native-safe-area-inset-top, env(safe-area-inset-top)) instead of raw env(), please document it; a tiny utility class for fixed overlays (e.g. .native-fixed-top) would be even better.
If this is already covered on rubynative.com and we just missed it, feel free to close with a pointer.
Summary
With full-bleed content (the behavior requested in #4),
position: fixedtop-anchored overlays — banners, toasts, modal headers — render under the iOS status bar unless the app hand-rollsenv(safe-area-inset-top)math. The gem's.native-inset-tophelpers cover in-flow layout (they inject an::beforespacer) but nothing covers fixed overlays, and the pattern isn't documented. We've now shipped the same one-line fix three separate times, each one first reported as a device-only bug by a tester.Setup
cora.computer) — Rails 8 + Inertia/React,ruby_native0.10.11, Normal Mode iOS shell, full-bleed webviewWhat we hit (three independent device-reported bugs, same root cause)
pt-[max(0.75rem,env(safe-area-inset-top))]on the modal container.fixed top-3): the clock/battery painted straight over the banner copy (tester screenshot). Fix:top: max(0.75rem, calc(env(safe-area-inset-top, 0px) + 0.5rem)).None of these reproduce in desktop Safari/Chrome or simulators without a notch, so each burned a report → triage → device-verify loop before the obvious fix.
Asks
.native-insetdocs: "anyposition: fixedelement anchored withtop:needsmax(<your-offset>, env(safe-area-inset-top) + <gap>)" — one paragraph would have saved us three bug cycles.--ruby-native-safe-area-inset-topas public API.ruby_native.cssalready defines the helpers viavar(--ruby-native-safe-area-inset-top, env(safe-area-inset-top))— with the comment that Android's WebView doesn't populateenv(safe-area-inset-*). That means our pure-env()fixes above are iOS-only and will silently collapse to0on the Android shell. If apps are supposed to writevar(--ruby-native-safe-area-inset-top, env(safe-area-inset-top))instead of rawenv(), please document it; a tiny utility class for fixed overlays (e.g..native-fixed-top) would be even better.If this is already covered on rubynative.com and we just missed it, feel free to close with a pointer.