Update "Setting up your device" page for MacOS Setup Experience by sgress454 · Pull Request #33770 · fleetdm/fleet

sgress454 · 2025-10-02T18:38:28Z

Related issue: Resolves #33173

Details

This PR updates the "Setting up your device" page which appears in Linux and Windows (and as of #30117, MacOS) setup experiences. Front-end updates:

Lots of renaming of things that were software-specific to now more generically refer to "setup step"
Removed the "My Device" heading
Moved the info button inside the table header
Added status of setup script run to the table
Updated the empty state to not refer specifically to software
Added optional setup_only query param to the /device page which, if set, will always show the "setting up your device" page even if all setup is complete. Normally as soon as setup finishes, the front-end redirects to the regular My Device page. In the case of MacOS setup experience, we don't want this to happen as we expect to either 1) keep the setup experience up indefinitely if we're blocking device setup on software install failure, or 2) close the setup dialog on successful completion. This query param is also handy for testing.
Added new "Configuration complete" state to be shown when all setup steps are finished (successfully or not). This is only applicable on MacOS, since other platforms will redirect to the My Device page when finished.

This PR also includes one small backend change to the /device/{token}/setup_experience/status API endpoint, to have it return a scripts array alongside the existing software array. This endpoint is not documented publicly.

Checklist for submitter

If some of the following don't apply, delete the relevant line.

Changes file added for user-visible changes in changes/, orbit/changes/ or ee/fleetd-chrome/changes.
See Changes files for more information.

Testing

Added/updated automated tests
Updated existing DeviceUserPage tests that check the SettingUpYourDevice content, and added new tests for the new scripts content and the new query param.
QA'd all new/changed functionality manually

(note that as of now we'd only have at most one script, showing multiple here to demonstrate the different states)

codecov · 2025-10-02T18:41:11Z

Codecov Report

❌ Patch coverage is 84.61538% with 12 lines in your changes missing coverage. Please review.
✅ Project coverage is 64.00%. Comparing base (651fdfb) to head (185707b).
⚠️ Report is 40 commits behind head on main.

Files with missing lines	Patch %	Lines
...le/SetupScriptStatusCell/SetupScriptStatusCell.tsx	68.42%	6 Missing ⚠️
ee/server/service/devices.go	40.00%	2 Missing and 1 partial ⚠️
...Device/SetupStatusTable/SetupStatusTableConfig.tsx	86.66%	2 Missing ⚠️
...UpYourDevice/SetupStatusTable/SetupStatusTable.tsx	90.90%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main   #33770   +/-   ##
=======================================
  Coverage   64.00%   64.00%           
=======================================
  Files        2068     2070    +2     
  Lines      207230   207319   +89     
  Branches     6861     6788   -73     
=======================================
+ Hits       132642   132702   +60     
- Misses      64157    64182   +25     
- Partials    10431    10435    +4

Flag	Coverage Δ
backend	`65.11% <40.00%> (-0.01%)`	⬇️
frontend	`53.39% <87.67%> (+0.04%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

sgress454 · 2025-10-02T18:41:07Z

This file is the only backend change, to allow the host setup status API to return scripts info. Currently the array will have at most one entry, but no reason not to future-proof it for a world of multiple setup scripts.

FWIW given that nopkg is landing, it looks like the plan is to have "scripts that behave as software" so the scripts section would actually go away here.

@rachaelshaw does that sound right? When is that work expected to land?

In any event, if we keep this result in we need updates to the contributor API docs to reflect the revised shape of the response payload. Looks like the existing response is wrong anyway given that it it shows script so there's a 100% chance we need to change that endpoint. This can/probably should be its own PR so we're not needing to get two different sets of codeowners to simultaneously approve a thing.

In any event, if we keep this result in we need updates to the contributor API docs to reflect the revised shape of the response payload. Looks like the existing response is wrong anyway given that it it shows script so there's a 100% chance we need to change that endpoint. This can/probably should be its own PR so we're not needing to get two different sets of codeowners to simultaneously approve a thing.

This is a different API (which is not documented at all AFAICT). It tripped me up too. The one you're referring to is:

POST /api/fleet/orbit/setup_experience/status

but this one is

POST /api/fleet/device/{token}/setup_experience/status

sgress454 · 2025-10-02T18:41:40Z

Mainly renaming and adding mock setup script data.

sgress454 · 2025-10-02T18:42:05Z

New component to render the name of a setup script in the table. Mostly a copy of the software version, with a different image and text.

sgress454 · 2025-10-02T18:43:24Z

+  .graphic {
+      width: $pad-xlarge;
+      scale: 60%;
+  }


Open to other ideas here. The width matches the one added for the software icon so that all the icons / graphics can be centered with each other. Since it's an SVG with a defined width in the markup, scale is the only way to resize with CSS afaik.

sgress454 · 2025-10-02T18:44:21Z

New component to render the status of a setup script in the table. Mostly a copy of the Software version, with some different labels.

sgress454 · 2025-10-02T18:50:08Z

+  // Sort the statuses so that scripts are always at the bottom.
+  statuses.sort((a, b) => {
+    if (a.type === b.type) {
+      return 0;
+    }
+    if (a.type === "script") {
+      return 1;
+    }
+    return -1;
+  });


Make sure that scripts show up last.

sgress454 · 2025-10-02T18:50:21Z

+        isAllPagesSelected={false}
+        disableTableHeader={false}
+        disablePagination
+        manualSortBy


Don't sort (since we did it above).

sgress454 · 2025-10-02T18:50:48Z

+      if (type === "software") {
+        return <SetupSoftwareProcessCell name={name || "Unknown software"} />;
+      }
+      if (type === "script") {
+        return <SetupScriptProcessCell name={name || "Unknown script"} />;
+      }


Render the right type of process cell based on type.

sgress454 · 2025-10-02T18:50:55Z

+      if (type === "software") {
+        return <SetupSoftwareStatusCell status={status || "pending"} />;
+      }
+      if (type === "script") {
+        return <SetupScriptStatusCell status={status || "pending"} />;
+      }
+      return null;


Render the right type of status cell based on type.

sgress454 · 2025-10-02T18:51:11Z

+  .empty-table__container {
+    max-width: 100%;
+  }


To center the content

sgress454 · 2025-10-02T22:24:21Z

+const SetupScriptProcessCell = ({ name }: ISetupScriptProcessCell) => {
+  return (
+    <span className={baseClass}>
+      <Graphic name="file-sh" className={`${baseClass}__icon`} />


I grabbed this from the Setup Experience admin UI; we don't have an <Icon> for it.

iansltx

Couple of test naming nits, plus the whole "we need to document contributor API changes, but that can be its own PR" thing.

We do need to talk through setup experience scripts as their own thing as based on my understanding of setup experience sort-term roadmap the intent is to replace those with nopkg for arbitrary ordering (vs. always having scripts last), so while the API changes we're making now are rather lightweight we'll be tossing them rather soon.

Cleaning scripts up so we don't have three ways to run scripts (script entities, setup experience scripts, nopkg) feels like something we need to do in Fleet 5 at the latest (I don't think we need to do it here, and given that we need the script for macOS setup experience, fair enough to include it here in a way that requires fewer FE changes to consume). /cc @rachaelshaw

Once the test nits are resolved and there's a parallel PR for contributor docs updates, I'll 👍 this.

iansltx · 2025-10-06T02:28:47Z

FWIW given that nopkg is landing, it looks like the plan is to have "scripts that behave as software" so the scripts section would actually go away here.

@rachaelshaw does that sound right? When is that work expected to land?

In any event, if we keep this result in we need updates to the contributor API docs to reflect the revised shape of the response payload. Looks like the existing response is wrong anyway given that it it shows script so there's a 100% chance we need to change that endpoint. This can/probably should be its own PR so we're not needing to get two different sets of codeowners to simultaneously approve a thing.

fix test names Co-authored-by: Ian Littman <iansltx@gmail.com>

sgress454 · 2025-10-06T12:38:03Z

Cleaning scripts up so we don't have three ways to run scripts (script entities, setup experience scripts, nopkg) feels like something we need to do in Fleet 5 at the latest (I don't think we need to do it here, and given that we need the script for macOS setup experience, fair enough to include it here in a way that requires fewer FE changes to consume). /cc @rachaelshaw

Agreed. I don't have all the context for nopkg, and I'm always +1 on thinking about using existing systems to accomplish related tasks. It does seem like the software system has some baggage that I'm not keen on putting on scripts as well, versus just making self-service scripts possible using the existing scripts framework. We'll have to have guidance on when to use a script vs. a nopkg, people will want to schedule / batch nopkg installs like they can with scripts, etc. But if this is all in progress already then 🤐 .

Once the test nits are resolved and there's a parallel PR for contributor docs updates, I'll 👍 this.

Test nits are in, and as mentioned above there's no docs to update for this particular API. If that's unintentional, I'll make a PR to add one.

iansltx · 2025-10-06T13:57:41Z

Cleaning scripts up so we don't have three ways to run scripts (script entities, setup experience scripts, nopkg) feels like something we need to do in Fleet 5 at the latest (I don't think we need to do it here, and given that we need the script for macOS setup experience, fair enough to include it here in a way that requires fewer FE changes to consume). /cc @rachaelshaw

Agreed. I don't have all the context for nopkg, and I'm always +1 on thinking about using existing systems to accomplish related tasks. It does seem like the software system has some baggage that I'm not keen on putting on scripts as well, versus just making self-service scripts possible using the existing scripts framework. We'll have to have guidance on when to use a script vs. a nopkg, people will want to schedule / batch nopkg installs like they can with scripts, etc. But if this is all in progress already then 🤐 .

Looks like it just got pushed to Ready to estimate (#31719, /cc @cdcme).

Once the test nits are resolved and there's a parallel PR for contributor docs updates, I'll 👍 this.

Test nits are in, and as mentioned above there's no docs to update for this particular API. If that's unintentional, I'll make a PR to add one.

Missing docs at all on the endpoint was a miss from earlier then. Please PR the add to the contributor API docs. Will approve this one in the interim so as not to block.

iansltx

Approving given the endpoint touched will get documented in another PR with its own approver.

**Related issue:** Resolves #46973 > **Draft:** on-device QA (Mac/iPhone/iPad) is pending hardware, expected next week. Opening as draft for early review of the approach. ## Description FMA and custom-package app icons were misaligned on the macOS setup experience ("Setting up your device") screen — icons rendered at different sizes and their "Install …" labels didn't line up. **Root cause:** `SetupSoftwareProcessCell` forced `.software-icon__small { width: $pad-xlarge }` (32px, width only). That class lands on different elements in `SoftwareIcon`'s two render paths, so it hit them differently: - **Fleet-maintained / VPP apps (icon URL)** → the class is on the wrapper `<div>`; the 24px `<img>` inside stayed 24px, left-aligned. - **Custom packages (no URL)** → the class is on the fallback **SVG** itself, which got stretched to 32px wide. Result: different icon sizes/positions by app type → the misalignment. **Fix:** remove the width override so every app type renders `SoftwareIcon` at its consistent, vertically-centered 24px "small" size. ## Testing Verified in Storybook (added `SetupSoftwareProcessCell.stories.tsx`, `MixedAlignment` story) with real matched brand icons (Chrome, 1Password, VS Code, Zoom), a generic custom-package icon, and a URL/`<img>` icon stacked together: - **Before** (with the override): icons render at mixed 24/32px sizes; "Install …" labels don't align. <img width="1135" height="398" alt="before" src="https://github.com/user-attachments/assets/fe216ab4-0a7b-4211-b8aa-96e65e6ca3f5" /> - **After** (this change): all icons render at 24px, centered, labels aligned. <img width="1185" height="425" alt="after" src="https://github.com/user-attachments/assets/28257eb8-df6e-4168-a0bb-28dda4bb40ba" /> On-device QA to follow once hardware is available. ## Notes for reviewer - The `width: $pad-xlarge` (32px) was added in #33770, so 32px may have been the *intended* icon size. This change makes them a consistent **24px**. If a larger icon is desired, that's a follow-up done properly via a real `SoftwareIcon` size (not a width-only override) — flagging for PD input since this is `:product`-labeled. - Included a Storybook story for visual verification/regression; happy to drop it if that's not wanted here. # Checklist for submitter - [x] Changes file added for user-visible changes in `changes/`. See [Changes files](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/guides/committing-changes.md#changes-files) for more information. ## Testing - [ ] QA'd all new/changed functionality manually  - Added a Storybook story for visual verification (not an automated test).  ## Summary by CodeRabbit * **Bug Fixes** * Improved software process cell styling for more consistent icon sizing and alignment. * **Tests** * Added Storybook scenarios covering fleet-maintained apps, custom packages, uploaded icons, and mixed app layouts.

sgress454 added 11 commits October 2, 2025 13:17

initial refactor

2cd5aeb

more refactor

6ac9898

Show scripts in setup experience status

6ef30fc

add test

e1a9949

refactor API response handling

04362c0

add script to test data

e7d0c61

update test

49bf34d

fix empty state

6e4f84c

fix sort

edbafae

changelog

18fba54

Merge branch 'main' into sgress454/33173-my-device-setup-page-updates

c88f3f9

sgress454 requested review from a team as code owners October 2, 2025 18:38

sgress454 temporarily deployed to Docker Hub October 2, 2025 18:38 — with GitHub Actions Inactive

don't marshal in the api

533e6ef

sgress454 temporarily deployed to Docker Hub October 2, 2025 22:00 — with GitHub Actions Inactive

sgress454 commented Oct 2, 2025

View reviewed changes

switch to finished screen if all done

a9cd17f

sgress454 had a problem deploying to Docker Hub October 2, 2025 22:13 — with GitHub Actions Error

sgress454 added 2 commits October 2, 2025 23:22

update code + test

b8a3299

Merge branch 'main' into sgress454/33173-my-device-setup-page-updates

be803c7

sgress454 temporarily deployed to Docker Hub October 2, 2025 22:23 — with GitHub Actions Inactive

sgress454 commented Oct 2, 2025

View reviewed changes

sgress454 assigned iansltx Oct 2, 2025

iansltx reviewed Oct 6, 2025

View reviewed changes

Apply suggestions from code review

185707b

fix test names Co-authored-by: Ian Littman <iansltx@gmail.com>

sgress454 temporarily deployed to Docker Hub October 6, 2025 12:10 — with GitHub Actions Inactive

iansltx approved these changes Oct 6, 2025

View reviewed changes

sgress454 merged commit 12ab93d into main Oct 6, 2025
41 checks passed

sgress454 deleted the sgress454/33173-my-device-setup-page-updates branch October 6, 2025 15:45

raju249 mentioned this pull request Jul 27, 2026

Center-align setup experience app icons #49962

Merged

2 tasks

Uh oh!

Conversation

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

Uh oh!

Details

Checklist for submitter

Testing

Uh oh!

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

Uh oh!

Codecov Report

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!

sgress454 Oct 2, 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!

sgress454 Oct 2, 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!

sgress454 Oct 2, 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!

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!

Choose a reason for hiding this comment

Uh oh!

iansltx left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

sgress454 commented Oct 6, 2025

Uh oh!

iansltx commented Oct 6, 2025

Uh oh!

iansltx left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

sgress454 commented Oct 2, 2025 •

edited

Loading

codecov Bot commented Oct 2, 2025 •

edited

Loading

sgress454 Oct 2, 2025 •

edited

Loading

sgress454 Oct 2, 2025 •

edited

Loading

sgress454 Oct 2, 2025 •

edited

Loading