Skip to content

Build your personal knowledge base with Trilium Notes

feat(client): simulate a mobile device's system bars from `.env`

Elian Doranab0f66dfe617
diff --git a/apps/client/.env b/apps/client/.env
index dc6392a2f2..768aae00ee 100644
--- a/apps/client/.env
+++ b/apps/client/.env
@@ -1 +1,3 @@
-VITE_CKEDITOR_ENABLE_INSPECTOR=false
\ No newline at end of file
+VITE_CKEDITOR_ENABLE_INSPECTOR=false
+# Simulates system bars, e.g. "0 0 48 0" (top right bottom left, CSS px).
+#VITE_DEBUG_SAFE_AREA_INSETS=0 0 48 0
\ No newline at end of file
diff --git a/apps/client/src/index.ts b/apps/client/src/index.ts
index bb86866e5a..02461000e5 100644
--- a/apps/client/src/index.ts
+++ b/apps/client/src/index.ts
@@ -33,6 +33,10 @@ async function bootstrap() {
initThemeChangeNotifier();
loadIcons();
setBodyAttributes();
+ const debugSafeAreaInsets = import.meta.env.VITE_DEBUG_SAFE_AREA_INSETS;
+ if (debugSafeAreaInsets) {
+ (await import("./services/debug_safe_area")).default(debugSafeAreaInsets);
+ }
reportSplashPhase("application");
await loadScripts();
hideSplash();
diff --git a/apps/client/src/services/debug_safe_area.css b/apps/client/src/services/debug_safe_area.css
new file mode 100644
index 0000000000..59a4c89559
--- /dev/null
+++ b/apps/client/src/services/debug_safe_area.css
@@ -0,0 +1,13 @@
+.debug-safe-area-overlay {
+ position: fixed;
+ inset: 0;
+ border-style: solid;
+ border-color: rgba(255, 0, 0, 0.35);
+ border-width:
+ var(--safe-area-inset-top)
+ var(--safe-area-inset-right)
+ var(--safe-area-inset-bottom)
+ var(--safe-area-inset-left);
+ pointer-events: none;
+ z-index: 100000;
+}
diff --git a/apps/client/src/services/debug_safe_area.spec.ts b/apps/client/src/services/debug_safe_area.spec.ts
new file mode 100644
index 0000000000..0c7b619622
--- /dev/null
+++ b/apps/client/src/services/debug_safe_area.spec.ts
@@ -0,0 +1,37 @@
+import { afterEach, describe, expect, it } from "vitest";
+
+import simulateSafeAreaInsets, { parseSafeAreaInsets } from "./debug_safe_area";
+
+describe("debug_safe_area", () => {
+ afterEach(() => {
+ document.documentElement.removeAttribute("style");
+ document.querySelector(".debug-safe-area-overlay")?.remove();
+ });
+
+ it("expands the CSS padding shorthand and rejects malformed values", () => {
+ expect(parseSafeAreaInsets("48")).toEqual({ top: 48, right: 48, bottom: 48, left: 48 });
+ expect(parseSafeAreaInsets("24 0")).toEqual({ top: 24, right: 0, bottom: 24, left: 0 });
+ expect(parseSafeAreaInsets(" 24 0 48 ")).toEqual({ top: 24, right: 0, bottom: 48, left: 0 });
+ expect(parseSafeAreaInsets("1 2 3 4")).toEqual({ top: 1, right: 2, bottom: 3, left: 4 });
+
+ expect(parseSafeAreaInsets("1 2 3 4 5")).toBeNull();
+ expect(parseSafeAreaInsets("48px")).toBeNull();
+ expect(parseSafeAreaInsets("0 -8")).toBeNull();
+ });
+
+ it("sets the inset properties and adds the overlay", () => {
+ simulateSafeAreaInsets("0 0 48 0");
+
+ const style = document.documentElement.style;
+ expect(style.getPropertyValue("--safe-area-inset-top")).toBe("0px");
+ expect(style.getPropertyValue("--safe-area-inset-bottom")).toBe("48px");
+ expect(document.querySelectorAll(".debug-safe-area-overlay")).toHaveLength(1);
+ });
+
+ it("leaves the page alone for a malformed value", () => {
+ simulateSafeAreaInsets("tall");
+
+ expect(document.documentElement.style.getPropertyValue("--safe-area-inset-bottom")).toBe("");
+ expect(document.querySelector(".debug-safe-area-overlay")).toBeNull();
+ });
+});
diff --git a/apps/client/src/services/debug_safe_area.ts b/apps/client/src/services/debug_safe_area.ts
new file mode 100644
index 0000000000..0ebda4ac55
--- /dev/null
+++ b/apps/client/src/services/debug_safe_area.ts
@@ -0,0 +1,41 @@
+import "./debug_safe_area.css";
+
+const SIDES = [ "top", "right", "bottom", "left" ] as const;
+
+type Side = typeof SIDES[number];
+
+/**
+ * Simulates the system bars of a mobile device: sets the `--safe-area-inset-*` properties the way
+ * the Android shell's `MainActivity` does, and outlines the covered area in red so that anything
+ * drawn under a system bar shows through it.
+ *
+ * @param spec the insets in CSS pixels, in the order and with the shorthand of the CSS `padding`
+ * property (`"0 0 48 0"`, `"24 0 48"`, `"48"`).
+ */
+export default function simulateSafeAreaInsets(spec: string) {
+ const insets = parseSafeAreaInsets(spec);
+ if (!insets) {
+ console.warn(`Ignoring VITE_DEBUG_SAFE_AREA_INSETS="${spec}": expected 1 to 4 numbers.`);
+ return;
+ }
+
+ const root = document.documentElement;
+ for (const side of SIDES) {
+ root.style.setProperty(`--safe-area-inset-${side}`, `${insets[side]}px`);
+ }
+
+ const overlay = document.createElement("div");
+ overlay.className = "debug-safe-area-overlay";
+ document.body.append(overlay);
+}
+
+export function parseSafeAreaInsets(spec: string): Record<Side, number> | null {
+ const values = spec.trim().split(/\s+/).map(Number);
+ const isValid = (value: number) => Number.isFinite(value) && value >= 0;
+ if (values.length > 4 || !values.every(isValid)) {
+ return null;
+ }
+
+ const [ top, right = top, bottom = top, left = right ] = values;
+ return { top, right, bottom, left };
+}
diff --git a/apps/client/src/vite-env.d.ts b/apps/client/src/vite-env.d.ts
index c81a92ed8f..b6201def0b 100644
--- a/apps/client/src/vite-env.d.ts
+++ b/apps/client/src/vite-env.d.ts
@@ -9,6 +9,11 @@ interface ImportMetaEnv {
readonly VITE_CKEDITOR_ENABLE_INSPECTOR?: "true" | "false";
/** Sends standalone's API calls through the service worker instead of the worker-owning tab. */
readonly VITE_DISABLE_LOCAL_FETCH?: "true" | "false";
+ /**
+ * Simulates a mobile device's system bars: the `--safe-area-inset-*` values in CSS pixels, in
+ * the order of the CSS `padding` shorthand (`"0 0 48 0"`). Empty turns the simulation off.
+ */
+ readonly VITE_DEBUG_SAFE_AREA_INSETS?: string;
}
interface ImportMeta {
diff --git a/apps/standalone/.env b/apps/standalone/.env
index efd1fd5179..4b69466f62 100644
--- a/apps/standalone/.env
+++ b/apps/standalone/.env
@@ -1 +1,3 @@
VITE_CKEDITOR_ENABLE_INSPECTOR=false
+# Simulates system bars, e.g. "0 0 48 0" (top right bottom left, CSS px).
+VITE_DEBUG_SAFE_AREA_INSETS=