MDX error handling UI/UX

[mattrosno]

When there are remote MDX errors, how do we handle those in the page? For example:

1. Entire page breaks and nothing can be rendered
2. Page attempts to use an unsupported MDX component
3. Page uses an MDX component that's supported but has errors and can't be rendered

Joe's Notes

Possible Errors

• Component used that is not recognized by the platform (regardless of whether or not it has a corresponding import)
  • can modify
  • can remove
• An import (or export) statement being used (we don't allow any)
  • possibly can modify (needs testing to be sure)
  • can remove
• A usage of an imported value someplace in the mdx
  • cannot modify (since we don't know the intended behavior)
  • can remove
• Inline styles that are strings instead of objects
  • cannot modify (at best, we will only cover some of the total possibilities)
  • can remove
• Inclusion of HTML comments
  • possibly can modify (needs testing to be sure)
  • can remove
• General Markdown parsing errors
  • this is a non-recoverable error
  • cannot modify
  • cannot remove
• General JSX parsing errors
  • this is a non-recoverable error
  • cannot modify
  • cannot remove

Options

• Modify content - replace part of the AST with something else
• Remove content - remove the affected tree nodes entirely
• Replace full page with error text (as opposed to the actual MDX content)

Consolidated error categories for design consideration

1. Errors propagated from the underlying MDX library (i.e. parsing errors)
   1. markdown parsing errors
   2. jsx parsing errors
   3. usage of an unknown token somewhere in the markdown
2. Unsupported things
   1. import statements
   2. unsupported/unknown components
   3. comments
   4. unsupported frontmatter
3. "This" versus "that" preferences
   1. using string styles on components instead of object styles
   2. using a "wrong" type of image component
   3. using tabs frontmatter instead of schema file docs definitions

[mattrosno]

Hey team! Please add your planning poker estimate with ZenHub @aubrey-oneal @kingtraceyj

[jharvey10]

Notes from dev + design discussion:

General philosophy

Convert each category 2 and 3 error into an inline notification with a corrective action. Potentially linking out to an FAQ or help document with common errors and how to resolve them. Where appropriate (and concise), add a related code snippet below the inline notification showing the problematic MDX.

We will strive towards two separate experiences: dev mode and prod mode. In dev mode, all errors will be presented to the user. In prod mode, we will revisit this and decide what makes sense to show on the live website for still-malformed MDX.

For non-recoverable full-page errors, the concept is the same. Show an inline notification at the top of the page with some details about what happened, potentially with a related code snippet if one is available from the output of the MDX parser.

[kingtraceyj]

@jdharvey-ibm and @alisonjoseph do you mind sharing some screenshots of a few examples? maybe one of an inline error and then one of a full page error?

[jharvey10]

@francinelucca may be able to help out with the error texts. At the moment, I don't think we have any UI demonstrating the errors, but we can definitely get you some of the error text we'd expect to get emitted for each type of error.

[kingtraceyj]

sample error text would be great!

[francinelucca]

will gather info and update here by EOD

[francinelucca]

@kingtraceyj errors:

• Component used that is not recognized by the platform (regardless of whether or not it has a corresponding import)

  

• An import (or export) statement being used (we don't allow any) This doesn't show an error but is a security concern that we shouldn't allow

• A usage of an imported value someplace in the mdx

  

Inline styles that are strings instead of objects

Inclusion of HTML comments

General Markdown parsing errors

General JSX parsing errors