[Toast] Add tone, actionOnComponent and leadingIcon props to Toast

[lone-star]

WHY are these changes introduced?

We would like to add more customisation to the current Toast component:

• tone: this allows us to provide specific tones for styling.
• actionOnComponent: this makes the whole component clickable instead of having a link inside
• leadingIcon: we can use custom icons in the component.

WHAT is this pull request doing?

Magic tone

We can change the tone of the toast to magic

Action on component

The whole component is now clickable.

action-on-component.mp4

Leading icon

In this example, we have both the magic tone, the leading icon, and the Action On Component

magic-leading-icon.mp4

How to 🎩

🖥 Local development instructions
🗒 General tophatting guidelines
📄 Changelog guidelines

🎩 checklist

• Tested a snapshot
• Tested on mobile
• Tested on multiple browsers
• Tested for accessibility
• Updated the component's README.md with documentation changes
• Tophatted documentation changes in the style guide

[alex-page]

@lone-star how can we consolidate error with your proposal for tone? I know this would be a breaking change but error does a lot of the features you want to suggest in this PR. Adds an icon, changes the color etc.

What is the timeline for this change and what priority is it? I would like to think a bit more about the existing toast functionality and how we can consolidate it with the new proposals.

[lone-star]

Thanks for looking at the PR Alex!

You are exactly right, I decomposed the error UI changes in order to make them work for tone, so we would be able to consolidate the both with a tone=error|tone. Then with a leadingIcon={...}.

I left the error as is in order to keep things backward compatible, but we could change it.

The timelines for this are quite urgent. It would be good to have a resolution as soon as possible.

More context: Together with @sainihas and @jameswfindlater, we have been discussing the need for a different sort of notification component for Polaris. The Toast component is only used for ephemeral messages, and we would like to have more permanent notifications for the user. It is also important for those more permanent notifications to integrate well with the current Toast UI. For the moment we are introducing these changes, but we anticipate further iterations on the Toast component.

[elsom25]

+1 this is a critical piece of the Taxonomy mission. I do think there'll be an evolved answer overtime as magic patterns are solidified more but this feels like a reasonable stepping stone (particularly given the decomposition).

[alex-page]

Thanks @lone-star and @elsom25. Would there be any interest to do a follow up PRs to:

1. Add error to tone as a non breaking change, deprecate error prop and create a migration for error to tone and leadingIcon
2. In v13 branch remove error as a breaking change

It's a lot of work on our team to keep the library as small as it is meant to be. I am aligned with this change but don't want the follow up work to disappear. I understand you are moving fast but these consolidations are super important to stop our props bloating. Let me know.

[elsom25]

It seems sensible to me if this feels worth a breaking change from your vantage-point. Magic-toning seems to be something that's propagating to many elements in polaris at this point so also feels broadly in-line (but I'll defer to @lone-star here)

[lone-star]

@alex-page Happy to make those PRs, the direction seems clear and straightforward.

I've raised an issue here that contains the changes you requested: #11451 (not sure about the right labels)

Please let me know if there is anything else, then I'll fix the conflicts and update the current PR.

[heyjoethomas]

1. What is the TLDR UX for making the Toast clickable? Seems like a strange pattern to me. Is there a flow or general pattern documented/laid out somewhere?
2. Would love to learn more about the needs for a more permanent notification type.

[alenaiouguina]

@heyjoethomas you can check out the prototype here to get a bit more context on the pattern and why we're introducing it for the taxonomy mission (magic autofill is a core experience of this new product). It also illustrates why there's a need for a more permanent toast for magic specifically within the context of winter editions launch.

We'll work with polaris team on the component for a persistent toast post-editions.

[lone-star]

Rebased to update with the icon changes.
Is there anything I can do to help this PR progress?

[alex-page]

@lone-star I wanted to ask if this could be a wrapper with overrides in magic-ui? Does this feature need to be accessible to 3P developers? Just want to make sure we are adding to Polaris for the right reasons.

[lone-star]

Thanks for your feedback Alex. Here are some of my investigation, as well as my understanding. Happy to be corrected if there are mistakes.

Could we use a separate component to display the magic messages?

I initially prototyped a separate component. Unfortunately the page that displays this component also uses the Polaris Toast. Since the Toast component uses a fixed positioning (similar to the component that I want to use), the two of them overlap.

The only way is therefore to integrate with the current Polaris Toast manager so that we don't have overlapping fixed components. I believe this to be true both for the proposed Magic toast (in this PR), and for the permanent component that @alenaiouguina is referring to here. Some pages already have overlaps between Toast and floating pills (ie: Variant Card, cc @sainihas). So we don't want to introduce yet another ugly UI. More so since we expect user actions to trigger both a magic Toast and a standard Toast in a closely timed manner. It's essential then for us to be able to stack toasts.

Could we integrate with the ToastManager with a wrapper?

There are 2 options there:

• Using global selectors: In the current Toast API, is no way to differentiate a "Magic" toast from a Normal toast, other than the text content itself (I don't see any ID or way to manually select a specific toast in the DOM). Even if we could, we would need to completely update the DOM in order to build the UI.
• Overriding the Frame component (that includes the ToastManager): 😨 I don't think that's an option.

Do we want to expose to 3P?

We are already exposing magic tones to 3P, and I expect us to expose this feature in the future (as for all the other magic UI elements). Since the Toast component itself is already being deprecated in favour of the AppBridge toast API, this won't change what 3P use in the immediate term. I assume that once we have had the opportunity to rework the feature we'll be able to expose it to 3P in AppBridge.

[chloerice]

Hey @lone-star, thanks for contributing! The magic tone looks great ✨ I've provided detailed suggestions to simplify and align the API additions with the rest of the system.

[lone-star]

Thank you for the feedback, I've updated the PR

[matallo]

Code and 🎩 (while pairing) LGTM! Minor non-blocking comments

[matallo]

these are quite similar, maybe stylistic but can we set it as a const but use the ternary in the source prop?

[lone-star]

It actually makes readability more messy due to typescript:

With the following:

const leadingIconMarkup =
  error || icon ? (
    <div className={styles.LeadingIcon}>
      <Icon source={error ? AlertCircleIcon : icon} tone="inherit" />
    </div>
  ) : null;

Typescript will complain that the source prop cannot be undefined. That's because it is unable to pickup the logic where source=icon only if error is nullish and that means that icon is defined. The solution for this involves adding some additional conditionals, and that makes readability really bad because we get multiple levels of nested ternary. I'd rather have a let with 2 conditional, a single level of nesting and a bit of repetition.

[lone-star]

/snapit

[github-actions]

🫰✨ Thanks @lone-star! Your snapshots have been published to npm.

Test the snapshots by updating your package.json with the newly published versions:

yarn add @shopify/polaris-migrator@0.0.0-snapshot-release-20240124105023

yarn add @shopify/polaris@0.0.0-snapshot-release-20240124105023

yarn add @shopify/polaris-tokens@0.0.0-snapshot-release-20240124105023

yarn add @shopify/stylelint-polaris@0.0.0-snapshot-release-20240124105023