Add UI metadata options

[Sherlouk]

Problem Statement

In addition to the error message, many error screens also include a contextual icon to reduce cognitive load and often a 'Retry' button. It would be good if Throwable including the built-in errors had the ability to provide:

1. A sensible icon based on the error type
2. A sensible default as to whether this error can be effectively retried
   • For example, most but not all network errors can be immediately retried, but validation errors can't be retried until the input changes.

Suggested Solution

Most likely some optional methods/variables added to the Throwable protocol, with values provided for all built-in errors.

[DandyLyons]

Throwable effectively maps userFriendlyMessage to LocalizedError.errorDescription.

But LocalizedError also defines failureReason, recoverySuggestion. It would be good if we could also provide these to the user and perhaps map them to LocalizedError, if appropriate.

[Jeehut]

@Sherlouk I like the idea of adding an optional icon. Were you thinking about SF Symbols? And can you give examples of different symbols helping separate errors from one another? Were you thinking "levels" as in warning/error or more in "kind of error" like database, network etc.?

As for retrying, my thinking was that this would be an area for the catch handler to decide. It can now easily see which error type and even case was thrown and handle it. If for some error cases a retry makes sense, it can retry automatically or add a retry mechanism to the UI. As for baking this in, I haven't explored providing built-in UIs e.g. a global modal to show in SwiftUI for errors not otherwise handled. Once that's done, I think it would also make sense to think about how to connect these to the UI, such as a "retry" button. If you have explored this area, feel free to share some example UI code so I can better understand and decide from there.

@DandyLyons I left out failure reason and recovery suggestion on purpose to keep things simple. The goal is not to provide a second LocalizedError type, but to make error handling more clear and simple. In my typical usage, a failure reason and recovery suggestion is included in the message already if it makes sense for a specific case. Since they are also just informational text, I think it can all be part of the userFriendlyMessage. If there were some other kinds of data, such as an icon or an action, then we could start thinking about additional fields, I think. But I'm open to reconsider if you have a good reason why it makes sense to keep them separate.

[Sherlouk]

SFSymbols would make sense, there are good symbols for network errors vs database errors vs generic exclamation marks for others. Network is the main thing to call out separately.

Haven't got much thought here but it just seems sensible that if you're defining a set of standardised errors that these would drive the UI too - improving user understanding and taking reasonable actions off the back of it. This could be a separate package dependant on this though.

[DandyLyons]

@Jeehut I agree. It's important that Throwable be easy to adopt. I'm not suggesting that we turn Throwable into another LocalizedError. I'm suggesting that we allow users to opt-in to this functionality. We could for example introduce a Recoverable protocol which inherits from Throwable and maps to LocalizedError.

[Jeehut]

I like both ideas. A separate package that doubles down on the UI aspect of error handling. And a Recoverable protocol that errors can conform to when they are recoverable. I'm still a bit unsure about how we can provide one API that serves for all the different recovery cases. For networking, it might be retry. But in other cases, it can be something like revert or re-enter (with pre-filled data from last try). I'm eager to see what kind of API you would define for it. Feel free to open a separate issue with a suggestion (or a PR if you find discussing with code easier).