Feat: Adding Breadcrumbs to the payroll flow component #680

dmortal · 2025-10-15T21:02:55Z

Screen.Recording.2025-10-16.at.3.25.26.PM.mov

dmortal · 2025-10-16T19:27:00Z

src/components/Common/UI/Breadcrumbs/Breadcrumbs.module.scss

@@ -0,0 +1,58 @@
+@use '../../../../styles/Helpers' as *;


WIP: this is auto-generated style - will adjust in the follow up

src/components/Common/UI/ProgressBreadcrumbs/ProgressBreadcrumbs.tsx

dmortal · 2025-10-16T19:31:38Z

src/components/Payroll/PayrollConfiguration/PayrollConfiguration.tsx

-    onEvent(componentEvents.RUN_PAYROLL_EMPLOYEE_EDIT, { employeeId: employee.uuid })
+    onEvent(componentEvents.RUN_PAYROLL_EMPLOYEE_EDIT, {
+      employeeId: employee.uuid,
+      firstName: employee.firstName,


To display employee name in the breadcrumb

src/components/Payroll/PayrollFlow/PayrollFlow.tsx

dmortal · 2025-10-16T19:33:40Z

src/components/Payroll/PayrollFlow/payrollStateMachine.ts

+  [componentEvents.RUN_PAYROLL_EDIT]: undefined
 }

+export const payrollFlowBreadcrumbsNodes: BreadcrumbNodes = {


This is the structure that establishes relationships between breadcrumbs for the flow

dmortal · 2025-10-16T19:34:05Z

src/components/Payroll/PayrollFlow/payrollStateMachine.ts

+      key: 'landing',
+      label: 'breadcrumbs.landing',
+      namespace: 'Payroll.Flow',
+      onNavigate: ((ctx: PayrollFlowContextInterface) => ({


Basically custom reducer for a specific breadcrumb

dmortal · 2025-10-16T19:35:31Z

src/components/Payroll/PayrollFlow/payrollStateMachine.ts

  })
 }

+const breadcrumbNavigateTransition = (targetState: string) =>


This is a factory that creates a specific transition for allowed breadcrumb - for now, each state needs to define all possible breadcrumb transitions - this can be automated, but we might prefer explicit approach in the spirit of FSMs

dmortal · 2025-10-16T19:36:17Z

src/components/Payroll/PayrollFlow/payrollStateMachine.ts

+  transition(
+    componentEvents.BREADCRUMB_NAVIGATE,
+    targetState,
+    guard(


guard ensures that transition to a target state happens if relative breadcrumb is clicked

dmortal · 2025-10-16T19:38:03Z

src/helpers/breadcrumbHelpers.ts

@@ -0,0 +1,145 @@
+import type {


This is breadcrumb node to trail resolution plus hydration of breadcrumbs with updated variables/translations

Copilot

Pull Request Overview

This PR introduces a breadcrumb navigation system for the Payroll Flow, replacing the step-based progress bar with clickable breadcrumbs. The implementation includes helper functions for building and managing breadcrumb trails, a new ProgressBreadcrumbs component, and updates to the payroll state machine to support breadcrumb-based navigation.

Key Changes:

Added breadcrumb navigation system with helper functions for building trails and resolving template variables
Created ProgressBreadcrumbs component with full test coverage and Storybook stories
Updated payroll flow to use breadcrumbs instead of step numbers for navigation
Removed back button functionality from PayrollOverview in favor of breadcrumb navigation

Reviewed Changes

Copilot reviewed 27 out of 28 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/helpers/breadcrumbHelpers.ts	Core helper functions for building breadcrumb trails and resolving template variables
src/helpers/breadcrumbHelpers.test.ts	Comprehensive test suite for breadcrumb helper functions
src/components/Common/UI/ProgressBreadcrumbs/*	New breadcrumbs component with types, styles, tests, and stories
src/components/Payroll/PayrollFlow/payrollStateMachine.ts	Updated state machine with breadcrumb nodes and navigation transitions
src/components/Payroll/PayrollFlow/PayrollFlow.tsx	Integrated breadcrumb building and i18n support
src/components/Flow/Flow.tsx	Added conditional rendering for breadcrumbs vs progress bar
src/components/Payroll/PayrollOverview/*	Removed back button and showBackButton prop
src/i18n/en/Payroll.Flow.json	Translation keys for breadcrumb labels
src/shared/constants.ts	Added BREADCRUMB_NAVIGATE event constant

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

src/components/Payroll/PayrollOverview/PayrollOverviewPresentation.tsx

src/components/Payroll/PayrollFlow/payrollStateMachine.ts

package.json

Co-authored-by: Copilot <[email protected]>

serikjensen

Left some feedback primarily around the separation of the Breadcrumbs UI and our application logic/utilities. Essentially we want the component in UI to only deal with the presentation and have the simplest API possible. We'll want to remove the translation and event concerns from that component.

One suggestion I have that might simplify this would be to create an additional Breadcrumb component in the common directory that will utilize the presentation component from UI and can be provided with our app specific configuration. That'll allow us to centralize our app complexity for managing breadcrumbs while keeping it simple for the partners to wire up adapters to the UI portions

Let's set up time to pair and we can chat more about it

src/components/Common/UI/ProgressBreadcrumbs/ProgressBreadcrumbs.tsx

src/components/Common/FlowBreadcrumbs/FlowBreadcrumbsTypes.ts

serikjensen · 2025-10-16T20:02:40Z

src/components/Common/FlowBreadcrumbs/FlowBreadcrumbsTypes.ts

+  /**
+   * Event handler for breadcrumb navigation
+   */
+  onNavigate?: (context: unknown) => unknown


My rec here would be to

Remove onNavigate from the Breadcrumb and move it to the ProgressBreadcrumb props below

Update onNavigate to have the unique key or id above passed as the argument

Remove onEvent from below

(Note: I'm flexible on the onNavigate being here or in the parent, placing it in the parent would keep it a little more aligned with Tabs where you have a single callback function for the component when it is selected that is called with the id of the item as an argument)

src/components/Common/UI/ProgressBreadcrumbs/ProgressBreadcrumbsTypes.ts

src/components/Common/UI/ProgressBreadcrumbs/ProgressBreadcrumbs.tsx

serikjensen · 2025-10-16T21:20:20Z

src/components/Common/UI/ProgressBreadcrumbs/ProgressBreadcrumbs.tsx

+                  <button
+                    type="button"
+                    className={styles.link}
+                    onClick={() => {
+                      handleBreadcrumbClick(breadcrumb)
+                    }}
+                  >


@jeffredodd should this have a role of link set even though it is a button?

serikjensen · 2025-10-16T21:21:54Z

src/components/Flow/Flow.tsx

+        {progressBarType === 'breadcrumbs' && (
+          <Components.ProgressBreadcrumbs
+            breadcrumbs={currentBreadcrumb ? (breadcrumbs[currentBreadcrumb] ?? []) : []}
+            cta={current.context.progressBarCta}


Ex. my rec here would be to break out the CTA and just align that here with a flex layout instead of having breadcrumbs needing to worry about the CTA

src/components/Payroll/PayrollFlow/PayrollFlow.tsx

serikjensen · 2025-10-16T21:28:44Z

src/helpers/breadcrumbHelpers.ts

+  Breadcrumb,
+  BreadcrumbNodes,
+  BreadcrumbNode,
+  BreadcrumbTrail,


Looking more at the usage, i think we should implement a Common component that can expose these interfaces which wraps the Components.Breadcrumbs from UI. That'll allow us to implement the complexity seen here that is specific to our codebase, while allowing the UI portion of the breadcrumb to be simplified by consumers

jeffredodd

Some nits, nothing huge

jeffredodd · 2025-10-17T21:07:48Z

.ladle/adapters/PlainComponentAdapter.tsx

  },
+  Breadcrumbs: ({ breadcrumbs, currentBreadcrumbId, ariaLabel, onClick }: BreadcrumbsProps) => {
+    return (
+      <div className="progress-breadcrumbs">


Would you mind doing this with a nav like wai aria shows? Should be a simple change https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/examples/breadcrumb/

jeffredodd · 2025-10-17T21:23:11Z

src/components/Common/UI/Breadcrumbs/Breadcrumbs.module.scss

+
+    &:focus-visible {
+      outline: var(--g-focusRingWidth) solid var(--g-focusRingColor);
+      outline-offset: 2px;


too bad we don't have --g-focusRingOffset

src/components/Common/UI/Breadcrumbs/Breadcrumbs.stories.tsx

serikjensen

LGTM! Thanks for updating!

src/components/Common/UI/Breadcrumbs/BreadcrumbsTypes.ts

dmortal added 6 commits October 15, 2025 12:38

chore: checkpoint - initial translation approach

b81b5b6

chore: breadcrumb composition

0383554

chore: semi-working version

b985b4e

fix: adding variables to correct step only

65e44f7

chore: initial navigation is established

dcede1c

chore: tests and story fixes

0edfae5

dmortal commented Oct 16, 2025

View reviewed changes

src/components/Common/UI/ProgressBreadcrumbs/ProgressBreadcrumbs.tsx Outdated Show resolved Hide resolved

dmortal commented Oct 16, 2025

View reviewed changes

src/components/Common/UI/ProgressBreadcrumbs/ProgressBreadcrumbs.tsx Outdated Show resolved Hide resolved

dmortal commented Oct 16, 2025

View reviewed changes

src/components/Common/UI/ProgressBreadcrumbs/ProgressBreadcrumbs.tsx Outdated Show resolved Hide resolved

dmortal commented Oct 16, 2025

View reviewed changes

src/components/Payroll/PayrollFlow/PayrollFlow.tsx Outdated Show resolved Hide resolved

dmortal commented Oct 16, 2025

View reviewed changes

Merge remote-tracking branch 'origin/main' into da/breadcrumbs

f51c8f8

dmortal marked this pull request as ready for review October 16, 2025 19:39

Copilot AI review requested due to automatic review settings October 16, 2025 19:39

Copilot AI reviewed Oct 16, 2025

View reviewed changes

src/components/Payroll/PayrollOverview/PayrollOverviewPresentation.tsx Show resolved Hide resolved

src/components/Payroll/PayrollFlow/payrollStateMachine.ts Outdated Show resolved Hide resolved

package.json Show resolved Hide resolved

dmortal changed the title ~~Da/breadcrumbs~~ Feat: Adding Breadcrumbs to the payroll flow component Oct 16, 2025

Update src/components/Payroll/PayrollFlow/payrollStateMachine.ts

e854e00

Co-authored-by: Copilot <[email protected]>

serikjensen reviewed Oct 16, 2025

View reviewed changes

dmortal added 5 commits October 17, 2025 10:27

Merge remote-tracking branch 'origin/main' into da/breadcrumbs

50532bb

chore: separating UI breadcrumbs from flow logic

859c02a

fix: fixing test/story

cbdd6a0

feat: allowing multiple resource file loading in usei18n hook

9e73458

feat: allowing multiple resource file loading in usei18n hook

c67be05

jeffredodd reviewed Oct 17, 2025

View reviewed changes

serikjensen approved these changes Oct 17, 2025

View reviewed changes

src/components/Common/UI/Breadcrumbs/BreadcrumbsTypes.ts Outdated Show resolved Hide resolved

Merge branch 'main' into da/breadcrumbs

7f1548f

dmortal enabled auto-merge (squash) October 20, 2025 12:29

fix: tests

a450667

dmortal merged commit 9863e14 into main Oct 20, 2025
7 checks passed

dmortal deleted the da/breadcrumbs branch October 20, 2025 13:37

Feat: Adding Breadcrumbs to the payroll flow component #680

Feat: Adding Breadcrumbs to the payroll flow component #680

Uh oh!

Conversation

dmortal commented Oct 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

serikjensen left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

serikjensen Oct 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jeffredodd left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

serikjensen left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

dmortal commented Oct 15, 2025 •

edited

Loading

serikjensen Oct 16, 2025 •

edited

Loading