💡 Idea - Better <Viewer /> props experience

[ben-polinsky]

Currently, we're pretty restrictive with what props a user needs to provide to the Viewer component.

In web, we have two sets of props required to initialize the viewer. There's one additional set in desktop (file - I'll address that at the end).

• "Connected" - connects to an iModel on the backend. Requires iTwin. Changeset optional.
• Blank Connection - does not connect to an iModel on the backend. Can be used for map, reality-data, or 2D geometrical graphics, feature data, or anything which doesn't need an iModel. Many times, an iTwin is still needed. But for geometry, maps, even some reality data workflows, the iTwin is not necessary. We do currently require extents and a geolocation (lat/long) because the viewer needs to know where to focus.

Our current behavior is to try to detect which sets of props the user is providing and then throw an error if something is missing. This is a bad user experience:

• The user is left wondering what the error means
• If the user figures out the error is their fault, do they know what they need to provide?

Solutions

At the least we should throw a better error with the props the user needs to provide. However, I wonder if we can do better.

Idea 1 - Graceful fallback

We don't throw errors, only warn users (toasts?) if there's a default we are using that they might want to provide. Think about extents or project location. If there's no iModel and the user doesn't provide an extent and/or location, we should use a default for both. If there's an iModelId but it is incorrect, we can still show the map and warn the user that the iModel connection couldn't be made. I think seeing a map is a much better experience than an error page.

Rationale: Often, this Viewer is the first development experience users have with iTwin. We want them to see something with very little effort and guide them through the app to the best of our ability.

Idea 2 - Different routes for different types of viewers

I've also considered an index page with different routes for each type of viewer. We can detect which props/env vars the user has added, perhaps add input boxes for them to change/enter them, and explain what the rationale is behind the different types of viewers - "A blank connection can be used for reality data, geometry, or map-based workflows."

Idea 3 - Different components for different types of viewers

Similar to idea two, this breaks things down at the component rather than route level. Could be used with 2.

Desktop Viewer

For the desktop viewer, we'd do a similar pattern, but treat file paths like iModelIds. If it is provided and fails, we'll warn the user but transition to a blank connection.