@furystack/shades-common-components 12.4.0 → 12.6.0

package/src/components/wizard/index.spec.tsx

@@ -1,7 +1,7 @@
 import { Injector } from '@furystack/inject'
 import type { ChildrenList } from '@furystack/shades'
-import { createComponent, initializeShadeRoot, Shade } from '@furystack/shades'
-import { sleepAsync, usingAsync } from '@furystack/utils'
+import { createComponent, flushUpdates, initializeShadeRoot, Shade } from '@furystack/shades'
+import { usingAsync } from '@furystack/utils'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import type { WizardStepProps } from './index.js'
 import { Wizard } from './index.js'
@@ -72,15 +72,23 @@ describe('Wizard', () => {
   const renderWizard = async (
     steps: Array<(props: WizardStepProps, children: ChildrenList) => JSX.Element>,
     onFinish?: () => void,
+    options?: { stepLabels?: string[]; showProgress?: boolean },
   ) => {
     const injector = new Injector()
     const root = document.getElementById('root')!
     initializeShadeRoot({
       injector,
       rootElement: root,
-      jsxElement: <Wizard steps={steps} onFinish={onFinish} />,
+      jsxElement: (
+        <Wizard
+          steps={steps}
+          onFinish={onFinish}
+          stepLabels={options?.stepLabels}
+          showProgress={options?.showProgress}
+        />
+      ),
     })
-    await sleepAsync(50)
+    await flushUpdates()
 
     const wizard = root.querySelector('shades-wizard') as HTMLElement
 
@@ -96,12 +104,12 @@ describe('Wizard', () => {
       clickNext: async () => {
         const btn = getStepElement()?.querySelector('.next-btn') as HTMLButtonElement
         btn?.click()
-        await sleepAsync(50)
+        await flushUpdates()
       },
       clickPrev: async () => {
         const btn = getStepElement()?.querySelector('.prev-btn') as HTMLButtonElement
         btn?.click()
-        await sleepAsync(50)
+        await flushUpdates()
       },
       [Symbol.asyncDispose]: () => injector[Symbol.asyncDispose](),
     }
@@ -215,6 +223,115 @@ describe('Wizard', () => {
     })
   })
 
+  describe('step indicator', () => {
+    it('should not render step indicator when stepLabels is not provided', async () => {
+      await usingAsync(await renderWizard([Step1, Step2]), async ({ wizard }) => {
+        const indicator = wizard.querySelector('[data-testid="wizard-step-indicator"]')
+        expect(indicator).toBeNull()
+      })
+    })
+
+    it('should render step indicator when stepLabels is provided', async () => {
+      await usingAsync(
+        await renderWizard([Step1, Step2, Step3], undefined, {
+          stepLabels: ['First', 'Second', 'Third'],
+        }),
+        async ({ wizard }) => {
+          const indicator = wizard.querySelector('[data-testid="wizard-step-indicator"]')
+          expect(indicator).toBeTruthy()
+
+          const circles = indicator?.querySelectorAll('.wizard-step-circle')
+          expect(circles?.length).toBe(3)
+        },
+      )
+    })
+
+    it('should show step labels', async () => {
+      await usingAsync(
+        await renderWizard([Step1, Step2], undefined, {
+          stepLabels: ['Setup', 'Confirm'],
+        }),
+        async ({ wizard }) => {
+          const labels = wizard.querySelectorAll('.wizard-step-label')
+          expect(labels[0]?.textContent).toBe('Setup')
+          expect(labels[1]?.textContent).toBe('Confirm')
+        },
+      )
+    })
+
+    it('should mark the current step as active', async () => {
+      await usingAsync(
+        await renderWizard([Step1, Step2, Step3], undefined, {
+          stepLabels: ['A', 'B', 'C'],
+        }),
+        async ({ wizard }) => {
+          const circles = wizard.querySelectorAll('.wizard-step-circle')
+          expect(circles[0]?.hasAttribute('data-active')).toBe(true)
+          expect(circles[1]?.hasAttribute('data-active')).toBe(false)
+        },
+      )
+    })
+
+    it('should update active step on navigation', async () => {
+      await usingAsync(
+        await renderWizard([Step1, Step2, Step3], undefined, {
+          stepLabels: ['A', 'B', 'C'],
+        }),
+        async ({ wizard, clickNext }) => {
+          await clickNext()
+          const circles = wizard.querySelectorAll('.wizard-step-circle')
+          expect(circles[0]?.hasAttribute('data-completed')).toBe(true)
+          expect(circles[1]?.hasAttribute('data-active')).toBe(true)
+          expect(circles[2]?.hasAttribute('data-active')).toBe(false)
+        },
+      )
+    })
+  })
+
+  describe('progress bar', () => {
+    it('should not render progress bar when showProgress is false', async () => {
+      await usingAsync(await renderWizard([Step1, Step2]), async ({ wizard }) => {
+        const progressBar = wizard.querySelector('[data-testid="wizard-progress-bar"]')
+        expect(progressBar).toBeNull()
+      })
+    })
+
+    it('should render progress bar when showProgress is true', async () => {
+      await usingAsync(
+        await renderWizard([Step1, Step2, Step3], undefined, { showProgress: true }),
+        async ({ wizard }) => {
+          const progressBar = wizard.querySelector('[data-testid="wizard-progress-bar"]')
+          expect(progressBar).toBeTruthy()
+        },
+      )
+    })
+
+    it('should start at 0% on first step', async () => {
+      await usingAsync(
+        await renderWizard([Step1, Step2, Step3], undefined, { showProgress: true }),
+        async ({ wizard }) => {
+          const fill = wizard.querySelector('.wizard-progress-fill') as HTMLElement
+          expect(fill?.style.width).toBe('0%')
+        },
+      )
+    })
+
+    it('should update progress on navigation', async () => {
+      await usingAsync(
+        await renderWizard([Step1, Step2, Step3], undefined, { showProgress: true }),
+        async ({ wizard, clickNext }) => {
+          await clickNext()
+          const fill = wizard.querySelector('.wizard-progress-fill') as HTMLElement
+          expect(fill?.style.width).toBe('50%')
+
+          await clickNext()
+          const fill2 = wizard.querySelector('.wizard-progress-fill') as HTMLElement
+          expect(fill2?.style.width).toBe('100%')
+        },
+      )
+    })
+  })
+
   describe('Paper container', () => {
     it('should render step inside a Paper component', async () => {
       await usingAsync(await renderWizard([Step1]), async ({ wizard }) => {

package/src/components/wizard/index.tsx

@@ -1,5 +1,6 @@
 import type { ChildrenList } from '@furystack/shades'
 import { createComponent, Shade } from '@furystack/shades'
+import { cssVariableTheme } from '../../services/css-variable-theme.js'
 import { Paper } from '../paper.js'
 
 export interface WizardStepProps {
@@ -30,6 +31,14 @@ export interface WizardProps {
    * A callback that will be executed when the wizard is completed
    */
   onFinish?: () => void
+  /**
+   * Optional labels for each step. When provided, a step indicator is shown above the content.
+   */
+  stepLabels?: string[]
+  /**
+   * When true, a progress bar is shown above the content.
+   */
+  showProgress?: boolean
 }
 
 export const Wizard = Shade<WizardProps>({
@@ -42,15 +51,131 @@ export const Wizard = Shade<WizardProps>({
       width: '100%',
       height: '100%',
     },
+    '& .wizard-step-indicator': {
+      display: 'flex',
+      alignItems: 'center',
+      justifyContent: 'center',
+      padding: '16px 24px 8px',
+      gap: '0',
+    },
+    '& .wizard-step-node': {
+      display: 'flex',
+      flexDirection: 'column',
+      alignItems: 'center',
+      gap: '4px',
+      zIndex: '1',
+      minWidth: '32px',
+    },
+    '& .wizard-step-circle': {
+      width: '28px',
+      height: '28px',
+      borderRadius: '50%',
+      display: 'flex',
+      alignItems: 'center',
+      justifyContent: 'center',
+      fontSize: cssVariableTheme.typography.fontSize.xs,
+      fontWeight: cssVariableTheme.typography.fontWeight.semibold,
+      border: `2px solid ${cssVariableTheme.action.subtleBorder}`,
+      background: cssVariableTheme.background.default,
+      color: cssVariableTheme.text.secondary,
+      transition: `all ${cssVariableTheme.transitions.duration.normal} ease`,
+    },
+    '& .wizard-step-circle[data-active]': {
+      borderColor: cssVariableTheme.palette.primary.main,
+      background: cssVariableTheme.palette.primary.main,
+      color: cssVariableTheme.palette.primary.mainContrast,
+    },
+    '& .wizard-step-circle[data-completed]': {
+      borderColor: cssVariableTheme.palette.primary.main,
+      background: cssVariableTheme.palette.primary.main,
+      color: cssVariableTheme.palette.primary.mainContrast,
+      opacity: '0.7',
+    },
+    '& .wizard-step-label': {
+      fontSize: cssVariableTheme.typography.fontSize.xs,
+      color: cssVariableTheme.text.secondary,
+      textAlign: 'center',
+      maxWidth: '80px',
+      overflow: 'hidden',
+      textOverflow: 'ellipsis',
+      whiteSpace: 'nowrap',
+    },
+    '& .wizard-step-label[data-active]': {
+      color: cssVariableTheme.palette.primary.main,
+      fontWeight: cssVariableTheme.typography.fontWeight.semibold,
+    },
+    '& .wizard-step-connector': {
+      flex: '1',
+      height: '2px',
+      background: cssVariableTheme.action.subtleBorder,
+      minWidth: '24px',
+      alignSelf: 'flex-start',
+      marginTop: '14px',
+      transition: `background ${cssVariableTheme.transitions.duration.normal} ease`,
+    },
+    '& .wizard-step-connector[data-completed]': {
+      background: cssVariableTheme.palette.primary.main,
+    },
+    '& .wizard-progress-bar': {
+      height: '4px',
+      background: cssVariableTheme.action.subtleBorder,
+      margin: '12px 24px 4px',
+      borderRadius: '2px',
+      overflow: 'hidden',
+    },
+    '& .wizard-progress-fill': {
+      height: '100%',
+      background: cssVariableTheme.palette.primary.main,
+      borderRadius: '2px',
+      transition: `width ${cssVariableTheme.transitions.duration.normal} ease`,
+    },
   },
   render: ({ props, useState }) => {
     const [currentPage, setCurrentPage] = useState('currentPage', 0)
 
+    if (props.stepLabels && props.stepLabels.length !== props.steps.length) {
+      console.warn(
+        `[Wizard] stepLabels length (${props.stepLabels.length}) does not match steps length (${props.steps.length}).`,
+      )
+    }
+
     const CurrentPage = props.steps[currentPage]
+    const progressPercent = props.steps.length > 1 ? (currentPage / (props.steps.length - 1)) * 100 : 100
 
     return (
       <div className="wizard-container">
         <Paper style={{ maxWidth: '100%', maxHeight: '100%' }} elevation={3} onclick={(ev) => ev.stopPropagation()}>
+          {props.stepLabels && props.stepLabels.length > 0 && (
+            <div className="wizard-step-indicator" data-testid="wizard-step-indicator">
+              {props.steps.map((_, index) => (
+                <>
+                  {index > 0 && (
+                    <div
+                      className="wizard-step-connector"
+                      {...(index <= currentPage ? { 'data-completed': '' } : {})}
+                    />
+                  )}
+                  <div className="wizard-step-node">
+                    <div
+                      className="wizard-step-circle"
+                      {...(index === currentPage ? { 'data-active': '' } : {})}
+                      {...(index < currentPage ? { 'data-completed': '' } : {})}
+                    >
+                      {(index + 1).toString()}
+                    </div>
+                    <span className="wizard-step-label" {...(index === currentPage ? { 'data-active': '' } : {})}>
+                      {props.stepLabels?.[index] ?? ''}
+                    </span>
+                  </div>
+                </>
+              ))}
+            </div>
+          )}
+          {props.showProgress && (
+            <div className="wizard-progress-bar" data-testid="wizard-progress-bar">
+              <div className="wizard-progress-fill" style={{ width: `${progressPercent}%` }} />
+            </div>
+          )}
           <CurrentPage
             currentPage={currentPage}
             maxPages={props.steps.length}

package/src/utils/promisify-animation.ts

@@ -13,6 +13,9 @@ export const promisifyAnimation = async (
     if (!el) {
       return reject(new Error('No element provided'))
     }
+    if (typeof el.animate !== 'function') {
+      return resolve({} as AnimationPlaybackEvent)
+    }
     const prefersReducedMotion = window.matchMedia?.('(prefers-reduced-motion: reduce)')?.matches
     const resolvedOptions: KeyframeAnimationOptions =
       typeof options === 'number' ? { duration: options } : { ...options }