feat: Add backgroundColor var on LoadingDots

[ahayes91]

Summary

Fixes: #2990

https://canvas.workdaydesign.com/components/indicators/loading-dots/ shows a circle variant for use on gray/dark/image-based backgrounds. Our LoadingDots component styling needed some TLC to allow consumers to set the background color to match this pattern, and our Storybook entries can be updated to show how to achieve this variant.

I also noticed some links to docs were broken in the codebase so I updated that too.

Release Category

Components
Documentation

Release Note

Adds capability to LoadingDots to accept a loadingDotColor prop to change loading dots color, with the capability to override that var with a stencil - intended for use with the circle variant for dark backgrounds/images, which is now shown in Storybook with Custom Shape story.
Also adds a animationDurationMs prop in the same pattern, with a Custom Color and Animation story in storybook demonstrating the use of both these new props.

---

Checklist

• MDX documentation adheres to Canvas Kit's Documentation Guidelines
• Label ready for review has been added to PR

For the Reviewer

• PR title is short and descriptive
• PR summary describes the change (Fixes/Resolves linked correctly)
• PR Release Notes describes additional information useful to call out in a release message or removed if not applicable
• Breaking Changes provides useful information to upgrade to this code or removed if not applicable

Where Should the Reviewer Start?

Grab a cuppa and settle in because this is nice and short 🤞

Areas for Feedback? (optional)

• Code
• Documentation
• Testing
• Codemods

Testing Manually

To test this, run yarn start locally with this branch and test out the LoadingDots stories to make sure they're still a-ok

Screenshots or GIFs (if applicable)

Screen.Recording.2024-10-31.at.09.56.21.mov

Thank You Gif (optional)

[cypress]

Workday/canvas-kit    Run #7965

Run Properties:   Passed #7965  •  f66259bf38 ℹ️: Merge 37f0f71222f09d29e4a6805e56930a3e8ab2ed7f into d5be4cb8b7153fd97fb8c3301e83...

Project	Workday/canvas-kit
Branch Review	loading-dots-a11y-example
Run status	Passed #7965
Run duration	03m 56s
Commit	f66259bf38 ℹ️: Merge 37f0f71222f09d29e4a6805e56930a3e8ab2ed7f into d5be4cb8b7153fd97fb8c3301e83...
Committer	Aislinn Hayes
View all properties for this run ↗︎

---

Test results
Failures	0
Flaky	30
Pending	24
Skipped	0
Passing	1092
View all changes introduced in this branch ↗︎

UI Coverage  21.86%
Untested elements	1624
Tested elements	452

Accessibility  99.18%
Failed rules	5 critical   5 serious   0 moderate   2 minor
Failed elements	177

[mannycarrera4]

Have a few thoughts on how we can improve this!

Using data-part

We've been trying to move towards having one stencil per component if possible and using data-part to style sub elements. Since LoadingDots doesn't have any sub components, we can still give access to those lower level elements via styling.

Instead of having LoadingAnimationDot we can just render a div with a data-part:

export const LoadingDots = createComponent('div')({
  displayName: 'LoadingDots',
  Component: (
    {backgroundColor, animationDurationMs, ...elemProps}: LoadingDotsProps,
    ref,
    Element
  ) => {
    return (
      <Element
        ref={ref}
        {...handleCsProp(elemProps, loadingDotsStencil({backgroundColor, animationDurationMs}))}
      >
        <div data-part="loading-animation-dot" />
        <div data-part="loading-animation-dot" />
        <div data-part="loading-animation-dot" />
      </Element>
    );
  },
});

Less components, cleaning up code, nice!

Targeting parts within the parent stencil

Now that we've removed some code, we need to update our stencil to style these elements

export const loadingDotsStencil = createStencil({
  vars: {
    animationDurationMs: '40ms',
    backgroundColor: system.color.bg.alt.strong,
  },
  base: ({backgroundColor, animationDurationMs}) => ({
    display: 'inline-flex',
    gap: system.space.x2,
    '& [data-part="loading-animation-dot"]': {
      backgroundColor,
      width: system.space.x4,
      height: system.space.x4,
      fontSize: system.space.zero,
      borderRadius: system.shape.round,
      transform: 'scale(0)',
      display: 'inline-block',
      animationName: keyframesLoading,
      animationDuration: calc.multiply(animationDurationMs, 35),
      animationIterationCount: 'infinite',
      animationTimingFunction: 'ease-in-out',
      animationFillMode: 'both',
      '&:nth-child(1)': {
        animationDelay: '0ms',
      },
      '&:nth-child(2)': {
        animationDelay: calc.multiply(animationDurationMs, 4),
      },
      '&:nth-child(3)': {
        animationDelay: calc.multiply(animationDurationMs, 8),
      },
    },
  }),
});

Notice how we target our sub elements with & [data-part="loading-animation-dor"]. Because we need these to be dynamic in color, we use the callback function to pass in our css variables at the start of base: ({backgroundColor, animationDuractionMs}) => ({}). Notice how we pass that to our stencil in the render function of the component up above.

API Suggestions

• Maybe instead of naming the prop backgroundColor we change it to something like loadingDotColor.
• We can make this even more flexible by adding animationDurationMs to the props so consumers can change the duration if they'd like.
• We can now update the storybook example to reflect how you can style this component something like:

const loadingStencil = createStencil({
  base: {
    borderRadius: system.shape.round,
    backgroundColor: system.color.bg.overlay,
    height: 80,
    width: 80,
    alignItems: 'center',
    justifyContent: 'center',
    display: 'flex',
    [loadingDotsStencil.vars.backgroundColor]: 'red',
    [loadingDotsStencil.vars.animationDurationMs]: '100ms',
  },
});

export const CircleVariant = () => {
  return (
    <div className={styleOverrides.parentContainer}>
      <LoadingDots cs={loadingStencil()} />
    </div>
  );
};

[ahayes91]

Looks great @mannycarrera4 ! One more question - should we show the use of the prop itself in Storybook too? Or keep the example of the stencil override as the default?

[mannycarrera4]

This story looks like it's the custom shape once since you're putting it in a circle, let's rename this CustomShape

[mannycarrera4]

I think by default this is the color of the loading dots, so no need to showcase that here.

[ahayes91]

my bad, this is supposed to be system.color.icon.inverse for the circle variant design!

[mannycarrera4]

Nice work on this! Thanks for making our dev experience better!