Animate the completion of a checklist item in the widget

code/core/src/components/components/Particles.stories.tsx

@@ -0,0 +1,18 @@
+import preview from '../../../../.storybook/preview';
+import { Particles } from './Particles';
+
+const SomeComponent = (props: React.ComponentProps<'div'>) => {
+  return <div {...props}>Cool</div>;
+};
+
+const meta = preview.meta({
+  component: Particles,
+  parameters: {
+    layout: 'centered',
+  },
+  args: {
+    anchor: SomeComponent,
+  },
+});
+
+export const Default = meta.story({});

code/core/src/components/components/Particles.tsx

@@ -0,0 +1,165 @@
+import type { ComponentProps } from 'react';
+import React, { memo, useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+
+import { keyframes, styled } from 'storybook/theming';
+
+const Shape = styled.svg(({ color }) => ({
+  fill: color,
+  position: 'absolute',
+  inset: '0',
+  margin: 'auto',
+  width: '12px',
+  height: '12px',
+  pointerEvents: 'none',
+}));
+
+const Donut = (props: ComponentProps<typeof Shape>) => (
+  <Shape viewBox="0 0 90 90" xmlns="http://www.w3.org/2000/svg" color="red" {...props}>
+    <path d="M45 0c24.853 0 45 20.147 45 45S69.853 90 45 90 0 69.853 0 45 20.147 0 45 0zm.5 27C35.283 27 27 35.283 27 45.5S35.283 64 45.5 64 64 55.717 64 45.5 55.717 27 45.5 27z" />
+  </Shape>
+);
+
+const L = (props: ComponentProps<typeof Shape>) => (
+  <Shape viewBox="0 0 55 89" xmlns="http://www.w3.org/2000/svg" color="#66BF3C" {...props}>
+    <path d="M55 3v83a3 3 0 01-3 3H3a3 3 0 01-3-3V64a3 3 0 013-3h21a3 3 0 003-3V3a3 3 0 013-3h22a3 3 0 013 3z" />
+  </Shape>
+);
+
+const Slice = (props: ComponentProps<typeof Shape>) => (
+  <Shape viewBox="0 0 92 92" xmlns="http://www.w3.org/2000/svg" color="#FF4785" {...props}>
+    <path d="M92 89V3c0-3-2.056-3-3-3C39.294 0 0 39.294 0 89c0 0 0 3 3 3h86a3 3 0 003-3z" />
+  </Shape>
+);
+
+const Square = ({ style, ...props }: ComponentProps<typeof Shape>) => (
+  <Shape
+    viewBox="0 0 90 90"
+    xmlns="http://www.w3.org/2000/svg"
+    color="#1EA7FD"
+    {...props}
+    style={{ borderRadius: 5, ...style }}
+  >
+    <path d="M0 0h90v90H0z" />
+  </Shape>
+);
+
+const Triangle = (props: ComponentProps<typeof Shape>) => (
+  <Shape viewBox="0 0 96 88" xmlns="http://www.w3.org/2000/svg" color="#FFAE00" {...props}>
+    <path d="M50.63 1.785l44.928 81.77A3 3 0 0192.928 88H3.072a3 3 0 01-2.629-4.445l44.929-81.77a3 3 0 015.258 0z" />
+  </Shape>
+);
+
+const T = (props: ComponentProps<typeof Shape>) => (
+  <Shape viewBox="0 0 92 62" xmlns="http://www.w3.org/2000/svg" color="#FC521F" {...props}>
+    <path d="M63 3v25a3 3 0 003 3h23a3 3 0 013 3v25a3 3 0 01-3 3H3a3 3 0 01-3-3V34a3 3 0 013-3h24a3 3 0 003-3V3a3 3 0 013-3h27a3 3 0 013 3z" />
+  </Shape>
+);
+
+const Z = (props: ComponentProps<typeof Shape>) => (
+  <Shape viewBox="0 0 56 90" xmlns="http://www.w3.org/2000/svg" color="#6F2CAC" {...props}>
+    <path d="M28 3v25a3 3 0 003 3h22a3 3 0 013 3v53a3 3 0 01-3 3H31a3 3 0 01-3-3V62a3 3 0 00-3-3H3a3 3 0 01-3-3V3a3 3 0 013-3h22a3 3 0 013 3z" />
+  </Shape>
+);
+
+const fadeToTransparent = keyframes`
+  to {
+    opacity: 0;
+  }
+`;
+
+const disperse = keyframes`
+  to {
+    transform: translate(
+      calc(cos(var(--angle)) * var(--distance)),
+      calc(sin(var(--angle)) * var(--distance))
+    ) rotate(var(--rotation));
+  }
+`;
+
+const slideDown = keyframes`
+  to {
+    transform: translateY(50px);
+  }
+`;
+
+const Container = styled.div({
+  position: 'absolute',
+  display: 'flex',
+  flexDirection: 'row',
+  flexWrap: 'wrap',
+  gap: 10,
+  '--particle-curve': 'cubic-bezier(0.2, 0.56, 0, 1)',
+  animation: `${slideDown} 1000ms forwards cubic-bezier(0.587, -0.381, 0.583, 0.599)`,
+  animationDelay: '150ms',
+  zIndex: 999,
+
+  svg: {
+    width: 15,
+    height: 15,
+    animation: `${fadeToTransparent} var(--fade-duration) forwards, ${disperse} 1000ms forwards var(--particle-curve)`,
+  },
+});
+
+const FADE_DURATION = 1200;
+const NUM_OF_PARTICLES = 8;
+// `JITTER` is the amount of variance allowed for each angle.
+// Tweak this value to control how orderly/chaotic the animation appears.
+const JITTER = 15;
+
+const random = (min: number, max: number) => Math.random() * (max - min) + min;
+const sortRandomly = (array: any[]) => array.sort(() => Math.random() - 0.5);
+
+export const Particles = memo(function Particles({
+  anchor: Anchor,
+}: {
+  anchor: React.ElementType;
+}) {
+  const anchorRef = useRef<HTMLDivElement>(null);
+  const [left, setLeft] = useState(0);
+  const [top, setTop] = useState(0);
+
+  const shapes = sortRandomly([Donut, L, Slice, Square, Triangle, T, Z]);
+  const colors = sortRandomly([
+    '#FF0000',
+    '#FF4787',
+    '#66BF3C',
+    '#1EA7FD',
+    '#FC521F',
+    '#6F2CAC',
+    '#FFAE00',
+  ]);
+
+  useLayoutEffect(() => {
+    const rect = anchorRef.current?.getBoundingClientRect();
+    if (rect) {
+      setLeft(rect.left + rect.width / 2);
+      setTop(rect.top + rect.height / 2);
+    }
+  }, []);
+
+  return (
+    <div ref={anchorRef}>
+      <Anchor />
+      {createPortal(
+        <Container style={{ top: top + 'px', left: left + 'px' }}>
+          {shapes.map((Particle, index) => {
+            const angle = (360 / NUM_OF_PARTICLES) * index + random(-JITTER, JITTER);
+            const distance = random(50, 80);
+            const rotation = random(-360, 360);
+
+            const style = {
+              '--angle': angle + 'deg',
+              '--distance': distance + 'px',
+              '--rotation': rotation + 'deg',
+              '--fade-duration': FADE_DURATION + 'ms',
+            } as React.CSSProperties;
+
+            return <Particle key={Particle.name} style={style} color={colors[index]} />;
+          })}
+        </Container>,
+        document.getElementById('root') ?? document.body
+      )}
+    </div>
+  );
+});

code/core/src/manager-api/stores/checklist.ts

@@ -8,7 +8,6 @@ import {
 export const universalChecklistStore = experimental_UniversalStore.create<StoreState, StoreEvent>({
   ...UNIVERSAL_CHECKLIST_STORE_OPTIONS,
   leader: globalThis.CONFIG_TYPE === 'PRODUCTION',
-  debug: true,
 });
 
 export const checklistStore = createChecklistStore(universalChecklistStore);

code/core/src/manager/components/sidebar/ChecklistModule.stories.tsx

@@ -36,7 +36,28 @@ const meta = preview.meta({
   },
 });
 
-export const Default = meta.story({});
+export const Default = meta.story({
+  play: () => {
+    setTimeout(() => {
+      mockStore.setState({
+        loaded: true,
+        muted: false,
+        accepted: ['controls'],
+        done: ['install-storybook', 'render-component', 'whats-new-storybook-10', 'viewports'],
+        skipped: ['more-components', 'more-stories'],
+      });
+    }, 4000);
+    setTimeout(() => {
+      mockStore.setState({
+        loaded: true,
+        muted: false,
+        accepted: ['controls'],
+        done: ['install-storybook', 'render-component', 'whats-new-storybook-10', 'viewports'],
+        skipped: ['more-components', 'more-stories', 'install-vitest'],
+      });
+    }, 8000);
+  },
+});
 
 export const Narrow = meta.story({
   decorators: [(Story) => <div style={{ maxWidth: 200 }}>{Story()}</div>],

code/core/src/manager/components/sidebar/ChecklistModule.tsx

@@ -1,4 +1,4 @@
-import React, { createRef, useMemo } from 'react';
+import React, { createRef, useEffect, useMemo, useState } from 'react';
 
 import {
   Card,
@@ -20,15 +20,32 @@ import {
   EyeCloseIcon,
   ListUnorderedIcon,
   StatusFailIcon,
+  StatusPassIcon,
 } from '@storybook/icons';
 
 import { internal_checklistStore as checklistStore } from '#manager-stores';
 import { useStorybookApi } from 'storybook/manager-api';
-import { styled } from 'storybook/theming';
+import { keyframes, styled } from 'storybook/theming';
 
+import { Particles } from '../../../components/components/Particles';
 import { TextFlip } from '../TextFlip';
 import { Transition, TransitionGroup } from '../Transition';
-import { useChecklist } from './useChecklist';
+import { type ChecklistItem, useChecklist } from './useChecklist';
+
+const fadeScaleIn = keyframes`
+  from {
+    opacity: 0;
+    transform: scale(0.7);
+  }
+  to {
+    opacity: 1;
+    transform: scale(1);
+  }
+`;
+
+type ChecklistItemWithRef = ChecklistItem & {
+  nodeRef: React.RefObject<HTMLLIElement>;
+};
 
 const CollapsibleWithMargin = styled(Collapsible)(({ collapsed }) => ({
   marginTop: collapsed ? 0 : 16,
@@ -52,6 +69,27 @@ const ProgressCircle = styled(ProgressSpinner)(({ theme }) => ({
   color: theme.color.secondary,
 }));
 
+const Checked = styled(StatusPassIcon)(({ theme }) => ({
+  padding: 1,
+  borderRadius: '50%',
+  background: theme.color.positive,
+  color: theme.background.content,
+  animation: `${fadeScaleIn} 500ms forwards`,
+}));
+
+const ItemLabel = styled.span<{ isCompleted: boolean; isSkipped: boolean }>(
+  ({ theme, isCompleted, isSkipped }) => ({
+    textDecoration: isSkipped ? 'line-through' : 'none',
+    color: isSkipped
+      ? theme.textMutedColor
+      : isCompleted
+        ? theme.base === 'dark'
+          ? theme.color.positive
+          : theme.color.positiveText
+        : theme.color.defaultText,
+  })
+);
+
 const title = (progress: number) => {
   switch (true) {
     case progress < 25:
@@ -84,13 +122,28 @@ const OpenGuideAction = ({ children }: { children?: React.ReactNode }) => {
 
 export const ChecklistModule = () => {
   const api = useStorybookApi();
-  const { loaded, allItems, nextItems, progress, mute } = useChecklist();
+  const { loaded, accepted, done, skipped, allItems, nextItems, progress, mute } = useChecklist();
+
+  const [items, setItems] = useState<ChecklistItemWithRef[]>([]);
 
-  const next = useMemo(
-    () => nextItems.map((item) => ({ ...item, nodeRef: createRef<HTMLDivElement>() })),
+  const itemsWithRef = useMemo(
+    () => nextItems.map((item) => ({ ...item, nodeRef: createRef<HTMLLIElement>() })),
     [nextItems]
   );
-  const hasTasks = next.length > 0;
+
+  useEffect(() => {
+    setItems((current) =>
+      current.map((item) => ({
+        ...item,
+        isCompleted: accepted.includes(item.id) || done.includes(item.id),
+        isSkipped: skipped.includes(item.id),
+      }))
+    );
+    const timeout = setTimeout(setItems, 2000, itemsWithRef);
+    return () => clearTimeout(timeout);
+  }, [accepted, done, skipped, itemsWithRef]);
+
+  const hasTasks = items.length > 0;
 
   return (
     <CollapsibleWithMargin collapsed={!hasTasks}>
@@ -182,15 +235,22 @@ export const ChecklistModule = () => {
           )}
         >
           <TransitionGroup as="ul" component={Listbox}>
-            {next.map((item) => (
+            {items.map((item) => (
               <Transition key={item.id} nodeRef={item.nodeRef} timeout={300}>
+                {/* @ts-expect-error Ref doesn't understand "as" prop */}
                 <ListboxItem as="li" ref={item.nodeRef}>
                   <ListboxAction onClick={() => api.navigate(`/settings/guide#${item.id}`)}>
                     <ListboxIcon>
-                      <StatusFailIcon />
+                      {item.isCompleted ? (
+                        <Particles anchor={Checked} key={item.id} />
+                      ) : (
+                        <StatusFailIcon />
+                      )}
                     </ListboxIcon>
                     <ListboxText>
-                      <span>{item.label}</span>
+                      <ItemLabel isCompleted={item.isCompleted} isSkipped={item.isSkipped}>
+                        {item.label}
+                      </ItemLabel>
                     </ListboxText>
                   </ListboxAction>
                   {item.action && (

code/core/src/manager/components/sidebar/useChecklist.ts

@@ -29,6 +29,7 @@ export type ChecklistItem = RawItemWithSection & {
   isOpen: boolean;
   isLockedBy: string[];
   isReady: boolean;
+  isCompleted: boolean;
   isAccepted: boolean;
   isDone: boolean;
   isSkipped: boolean;
@@ -85,6 +86,7 @@ export const useChecklist = () => {
     return Object.values(itemsById).map<ChecklistItem>((item) => {
       const isAccepted = accepted.includes(item.id);
       const isDone = done.includes(item.id);
+      const isCompleted = isAccepted || isDone;
       const isSkipped = skipped.includes(item.id);
       const isMuted = Array.isArray(muted) ? muted.includes(item.id) : !!muted;
 
@@ -101,6 +103,7 @@ export const useChecklist = () => {
         isOpen,
         isLockedBy,
         isReady,
+        isCompleted,
         isAccepted,
         isDone,
         isSkipped,

code/core/src/manager/manager-stores.mock.ts

@@ -52,7 +52,6 @@ export const internal_universalChecklistStore = new experimental_MockUniversalSt
   {
     ...UNIVERSAL_CHECKLIST_STORE_OPTIONS,
     leader: globalThis.CONFIG_TYPE === 'PRODUCTION',
-    debug: true,
   },
   testUtils
 ) as unknown as UniversalStore<StoreState, StoreEvent>;

code/core/src/manager/settings/Checklist/Checklist.tsx

@@ -32,7 +32,7 @@ type ChecklistSection = {
 };
 
 type ChecklistItemWithRef = ChecklistItem & {
-  nodeRef?: React.RefObject<HTMLLIElement>;
+  nodeRef: React.RefObject<HTMLLIElement>;
 };
 
 const Sections = styled.ol(({ theme }) => ({