Navigation

One screen is visible at a time, so the user builds a mental map of your app from what they can reach and how they got there. Navigation is that map. Get it wrong and people cannot find features that exist.

There is a second reason to take it seriously. Both platforms have long-established conventions for moving backwards, and users have them in their fingers. Nobody reads your app's navigation model; they apply the one they already know. An app that contradicts it feels broken even when every screen works.

Android users go back with a system gesture or button that works everywhere, in every app, including yours. It is not your control and you do not get to disable it. Your job is to have a sensible answer for it on every screen: pop the stack, close the sheet, dismiss the keyboard. When there is nothing left to pop on a root screen, it leaves your app, and that is correct behaviour rather than a bug to prevent.

iOS has no system back button, so each screen supplies a back control in the navigation bar, and the edge swipe from the left does the same thing. If you replace the standard bar with your own design, the swipe frequently stops working, and users who rely on it will conclude your app is stuck.

Handle both, and let the same logic serve both. One function that answers "what does backwards mean here" is called by the Android system back and the iOS back control alike. Two divergent implementations drift, and the divergence shows up as a platform-specific bug nobody can reproduce.

There is one pattern to avoid: quietly repurposing back as cancel. If going back from a half-written visit note discards it without a word, the user who reflexively swiped has lost their work to a gesture they use a hundred times a day for something harmless. Either save the draft, or ask. Preferably save the draft.

type Screen =
  | { name: "siteList" }
  | { name: "employeeDetail"; employeeId: number }
  | { name: "visitNotes"; employeeId: number };

const HOME: Screen[] = [{ name: "siteList" }];

/** Turns an external path into the stack the user should arrive on. */
export function resolveLink(path: string): Screen[] {
  const parts = path.split("/").filter((part) => part.length > 0);

  if (parts[0] !== "employees") return HOME;
  if (parts.length === 1) return HOME;

  const employeeId = Number(parts[1]);
  if (!Number.isInteger(employeeId) || employeeId <= 0) return HOME;

  const stack: Screen[] = [...HOME, { name: "employeeDetail", employeeId }];
  if (parts[2] === "notes") {
    stack.push({ name: "visitNotes", employeeId });
  }
  return stack;
}

// "/employees/482/notes" arrives on the notes screen, and back still works.

• The shape matters more than the API. Every navigation library expresses this differently; what carries across is that a link resolves to an array of screens rather than a single destination.
• That array is the whole point. Land the user directly on the notes screen with an empty stack behind it and their first back gesture drops them out of the app. Land them on the same screen with the site list underneath and they can explore from where they arrived, which is what they expect.
• The path is untrusted input. It can come from a notification, a text message, a QR code on a piece of equipment, or someone typing. Number("abc") produces NaN and Number("") produces zero, so both the integer check and the positive check are doing real work here.
• Unknown paths fall back to a known screen instead of throwing. Links outlive app versions: a colleague shares a link from a newer build, or an old notification arrives after a redesign. A predictable fallback beats a crash on launch, and a crash on launch from a link is a particularly hard failure to diagnose.
• Keeping resolution in one pure function makes it directly testable. You can assert the resolved stack for a dozen paths in milliseconds, with no device and no navigator involved.