refactor(onboarding): migrate to Nuxt UI + browser history support (#1949)

## Summary

- Standardize the onboarding flow on Nuxt UI primitives across all steps
(Core Settings, Plugins, Internal Boot, License, Summary, Next Steps)
- Replace HeadlessUI Disclosure components with @unraid/ui Accordion
(enhanced with v-model and open state slot props)
- Integrate browser back/forward navigation support and "No Updates
Needed" messaging (from #1964)
- Polish UX: disabled button states, alert styling, skip button
behavior, radio button boot mode selection

## What Changed

### HeadlessUI → Nuxt UI Migration
- **All onboarding steps** now use Nuxt UI components (`USelectMenu`,
`UInput`, `UCheckbox`, `UAlert`, `UModal`, `UButton`, `URadioGroup`)
instead of HeadlessUI or native HTML elements
- **All `@headlessui/vue` imports removed from onboarding**
- Custom `<transition>` wrappers removed — Accordion uses Reka UI's
built-in animations

### Accordion Enhancement (@unraid/ui)
- Extended `Accordion` component with optional `v-model` support,
`itemClass` prop, and `{ open }` boolean in scoped slots
- Changes are **additive** — existing accordion usage is unaffected (no
global style changes)

### UX Polish
- Radio buttons for boot mode selection (USB vs Storage)
- Disabled state on BrandButton via `aria-disabled` with
`pointer-events-none`
- `cursor-not-allowed` on disabled Back/Skip navigation buttons
- Neutral-colored UAlerts for info panels and warnings
- Solid green UAlert for initialization ready state
- Outline variant for Skip button in license step
- Placeholder text in empty device select menus
- Guard against `slotCount` NaN from undefined USelectMenu values
- `:disabled` on reboot modal buttons to prevent double-click

### Browser History + No-Changes Messaging (from #1964)
- Browser back/forward navigation support within onboarding flows
- "No Updates Needed" messaging when no configuration changes are
applied
- Enhanced session handling with improved distinction between automatic
and manual onboarding modes

### Test Updates
- Replaced HeadlessUI Disclosure mocks with Accordion stubs
- Fixed auto-import bypass: tests use VM state for USelectMenu
interaction (Nuxt UI auto-imports bypass `global.stubs`)
- Updated "Setup Applied" → "No Updates Needed" assertions for
no-changes path
- All 618 web tests pass, all 1962 API tests pass

## Why

- The onboarding flow mixed native controls, HeadlessUI components, and
older modal patterns — making the UI feel uneven
- HeadlessUI was an unnecessary dependency when @unraid/ui (backed by
Reka UI) provides equivalent components
- Disabled states were not communicated visually to users

## Includes

- #1964 (feat: onboarding use history) — merged into this branch

## Verification

```bash
pnpm --dir web test -- --run
pnpm --dir web lint
pnpm --dir web type-check
pnpm --dir api test -- --run
pnpm --dir api lint
pnpm --dir api type-check
```

## Smoke Test

1. Walk the full onboarding flow — confirm all controls use consistent
Nuxt UI styling
2. Setup Boot: verify radio buttons for USB/Storage selection, disabled
states on Back/Skip during load
3. Internal Boot: expand/collapse eligibility details, verify device
selects have placeholder text
4. License: test Skip dialog with solid info alert and outline Skip
button
5. Summary: expand/collapse plugins accordion, verify "No Updates
Needed" when no changes apply
6. Next Steps: verify reboot confirmation modal buttons disable during
submission
7. Browser back/forward: navigate between steps using browser history
buttons

---------

Co-authored-by: Eli Bosley <eli@bosley.dev>

Author: Ajit-Mehrotra

plugin/source/dynamix.unraid.net/install/doinst.sh

@@ -31,3 +31,9 @@ cp usr/local/unraid-api/.env.production usr/local/unraid-api/.env
 ( cd usr/local/bin ; ln -sf ../lib/node_modules/npm/bin/npm-cli.js npm )
 ( cd usr/local/bin ; rm -rf npx )
 ( cd usr/local/bin ; ln -sf ../lib/node_modules/npm/bin/npx-cli.js npx )
+( cd usr/local/bin ; rm -rf corepack )
+( cd usr/local/bin ; ln -sf ../lib/node_modules/corepack/dist/corepack.js corepack )
+( cd usr/local/bin ; rm -rf npm )
+( cd usr/local/bin ; ln -sf ../lib/node_modules/npm/bin/npm-cli.js npm )
+( cd usr/local/bin ; rm -rf npx )
+( cd usr/local/bin ; ln -sf ../lib/node_modules/npm/bin/npx-cli.js npx )

unraid-ui/src/components/brand/brand-button.variants.ts

@@ -1,7 +1,7 @@
 import { cva, type VariantProps } from 'class-variance-authority';
 
 export const brandButtonVariants = cva(
-  'group text-center font-semibold leading-none relative z-0 flex flex-row items-center justify-center border-2 border-solid shadow-none cursor-pointer rounded-md hover:shadow-md focus:shadow-md disabled:opacity-25 disabled:hover:opacity-25 disabled:focus:opacity-25 disabled:cursor-not-allowed',
+  'group text-center font-semibold leading-none relative z-0 flex flex-row items-center justify-center border-2 border-solid shadow-none cursor-pointer rounded-md hover:shadow-md focus:shadow-md disabled:opacity-25 disabled:hover:opacity-25 disabled:focus:opacity-25 disabled:cursor-not-allowed aria-disabled:opacity-25 aria-disabled:cursor-not-allowed aria-disabled:hover:opacity-25 aria-disabled:hover:shadow-none',
   {
     variants: {
       variant: {

unraid-ui/src/components/common/accordion/Accordion.vue

@@ -5,6 +5,7 @@ import {
   AccordionRoot,
   AccordionTrigger,
 } from '@/components/ui/accordion';
+import { computed, ref, watch } from 'vue';
 
 export interface AccordionItemData {
   value: string;
@@ -18,21 +19,50 @@ export interface AccordionProps {
   type?: 'single' | 'multiple';
   collapsible?: boolean;
   defaultValue?: string | string[];
+  modelValue?: string | string[];
   class?: string;
+  itemClass?: string;
+  triggerClass?: string;
 }
 
 const props = withDefaults(defineProps<AccordionProps>(), {
   type: 'single',
   collapsible: true,
 });
+
+const emit = defineEmits<{
+  'update:modelValue': [value: string | string[]];
+}>();
+
+const openValue = ref<string | string[] | undefined>(props.modelValue ?? props.defaultValue);
+
+watch(
+  () => props.modelValue,
+  (val) => {
+    if (val !== undefined) openValue.value = val;
+  }
+);
+
+function isItemOpen(itemValue: string): boolean {
+  if (!openValue.value) return false;
+  if (Array.isArray(openValue.value)) return openValue.value.includes(itemValue);
+  return openValue.value === itemValue;
+}
+
+function handleUpdate(value: string | string[]) {
+  openValue.value = value;
+  emit('update:modelValue', value);
+}
 </script>
 
 <template>
   <AccordionRoot
     :type="type"
     :collapsible="collapsible"
     :default-value="defaultValue"
+    :model-value="openValue"
     :class="props.class"
+    @update:model-value="handleUpdate"
   >
     <!-- Default slot for direct composition -->
     <slot />
@@ -44,14 +74,15 @@ const props = withDefaults(defineProps<AccordionProps>(), {
         :key="item.value"
         :value="item.value"
         :disabled="item.disabled"
+        :class="props.itemClass"
       >
-        <AccordionTrigger>
-          <slot name="trigger" :item="item">
+        <AccordionTrigger :class="props.triggerClass">
+          <slot name="trigger" :item="item" :open="isItemOpen(item.value)">
             {{ item.title }}
           </slot>
         </AccordionTrigger>
         <AccordionContent>
-          <slot name="content" :item="item">
+          <slot name="content" :item="item" :open="isItemOpen(item.value)">
             {{ item.content }}
           </slot>
         </AccordionContent>

web/__test__/components/Onboarding/OnboardingCoreSettingsStep.test.ts

@@ -69,36 +69,6 @@ vi.mock('@unraid/ui', () => ({
     template:
       '<button data-testid="brand-button" :disabled="disabled" @click="$emit(\'click\')"><slot />{{ text }}</button>',
   },
-  Select: {
-    props: ['modelValue', 'items', 'disabled'],
-    emits: ['update:modelValue'],
-    template: `
-      <select
-        data-testid="select"
-        :disabled="disabled"
-        :value="modelValue"
-        @change="$emit('update:modelValue', $event.target.value)"
-      >
-        <option v-for="item in items" :key="item.value" :value="item.value">{{ item.label }}</option>
-      </select>
-    `,
-  },
-}));
-
-vi.mock('@headlessui/vue', () => ({
-  Switch: {
-    props: ['modelValue', 'disabled'],
-    emits: ['update:modelValue'],
-    template: `
-      <input
-        data-testid="switch"
-        type="checkbox"
-        :checked="modelValue"
-        :disabled="disabled"
-        @change="$emit('update:modelValue', $event.target.checked)"
-      />
-    `,
-  },
 }));
 
 vi.mock('@vvo/tzdb', () => ({
@@ -173,6 +143,35 @@ const mountComponent = (props: Record<string, unknown> = {}) => {
     },
     global: {
       plugins: [createTestI18n()],
+      stubs: {
+        USelectMenu: {
+          props: ['modelValue', 'items', 'disabled'],
+          emits: ['update:modelValue'],
+          template: `
+            <select
+              data-testid="select-menu"
+              :disabled="disabled"
+              :value="modelValue"
+              @change="$emit('update:modelValue', $event.target.value)"
+            >
+              <option v-for="item in items" :key="item.value" :value="item.value">{{ item.label }}</option>
+            </select>
+          `,
+        },
+        USwitch: {
+          props: ['modelValue', 'disabled'],
+          emits: ['update:modelValue'],
+          template: `
+            <input
+              data-testid="switch"
+              type="checkbox"
+              :checked="modelValue"
+              :disabled="disabled"
+              @change="$emit('update:modelValue', $event.target.checked)"
+            />
+          `,
+        },
+      },
     },
   });
 

web/__test__/components/Onboarding/OnboardingInternalBootStandalone.test.ts

@@ -1,6 +1,6 @@
-import { flushPromises, mount } from '@vue/test-utils';
+import { enableAutoUnmount, flushPromises, mount } from '@vue/test-utils';
 
-import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import type {
   InternalBootApplyMessages,
@@ -11,6 +11,14 @@ import type {
 import OnboardingInternalBootStandalone from '~/components/Onboarding/standalone/OnboardingInternalBoot.standalone.vue';
 import { createTestI18n } from '../../utils/i18n';
 
+const INTERNAL_BOOT_HISTORY_STATE_KEY = '__unraidOnboardingInternalBoot';
+
+type InternalBootHistoryState = {
+  sessionId: string;
+  stepId: 'CONFIGURE_BOOT' | 'SUMMARY';
+  position: number;
+};
+
 const {
   draftStore,
   applyInternalBootSelectionMock,
@@ -129,10 +137,50 @@ const mountComponent = () =>
     },
   });
 
+enableAutoUnmount(afterEach);
+
+const getInternalBootHistoryState = (): InternalBootHistoryState | null => {
+  const state =
+    typeof window.history.state === 'object' && window.history.state !== null
+      ? (window.history.state as Record<string, unknown>)
+      : null;
+  const candidate = state?.[INTERNAL_BOOT_HISTORY_STATE_KEY];
+  if (!candidate || typeof candidate !== 'object') {
+    return null;
+  }
+
+  const sessionId =
+    typeof (candidate as Record<string, unknown>).sessionId === 'string'
+      ? ((candidate as Record<string, unknown>).sessionId as string)
+      : null;
+  const stepId =
+    (candidate as Record<string, unknown>).stepId === 'CONFIGURE_BOOT' ||
+    (candidate as Record<string, unknown>).stepId === 'SUMMARY'
+      ? ((candidate as Record<string, unknown>).stepId as InternalBootHistoryState['stepId'])
+      : null;
+  const position = Number((candidate as Record<string, unknown>).position);
+
+  if (!sessionId || !stepId || !Number.isInteger(position)) {
+    return null;
+  }
+
+  return {
+    sessionId,
+    stepId,
+    position,
+  };
+};
+
+const dispatchPopstate = (state: Record<string, unknown> | null) => {
+  window.history.replaceState(state, '', window.location.href);
+  window.dispatchEvent(new PopStateEvent('popstate', { state }));
+};
+
 describe('OnboardingInternalBoot.standalone.vue', () => {
   beforeEach(() => {
     vi.useFakeTimers();
     vi.clearAllMocks();
+    window.history.replaceState(null, '', window.location.href);
 
     draftStore.internalBootSelection = null;
     draftStore.internalBootApplySucceeded = false;
@@ -182,8 +230,9 @@ describe('OnboardingInternalBoot.standalone.vue', () => {
 
     expect(applyInternalBootSelectionMock).not.toHaveBeenCalled();
     expect(draftStore.setInternalBootApplySucceeded).toHaveBeenCalledWith(false);
-    expect(wrapper.text()).toContain('Setup Applied');
-    expect(wrapper.text()).toContain('No settings changed. Skipping configuration mutations.');
+    expect(wrapper.text()).toContain('No Updates Needed');
+    expect(wrapper.text()).toContain('No changes needed. Skipping configuration updates.');
+    expect(wrapper.find('[data-testid="internal-boot-standalone-edit-again"]').exists()).toBe(true);
     expect(stepperPropsRef.value).toMatchObject({
       activeStepIndex: 1,
     });
@@ -278,7 +327,69 @@ describe('OnboardingInternalBoot.standalone.vue', () => {
     expect(wrapper.find('[data-testid="internal-boot-step-stub"]').exists()).toBe(true);
   });
 
+  it('restores the configure step when browser back leaves a reversible result', async () => {
+    const wrapper = mountComponent();
+
+    await wrapper.get('[data-testid="internal-boot-step-complete"]').trigger('click');
+    await flushPromises();
+
+    const currentHistoryState = getInternalBootHistoryState();
+    expect(currentHistoryState).toMatchObject({
+      stepId: 'SUMMARY',
+      position: 1,
+    });
+
+    dispatchPopstate({
+      [INTERNAL_BOOT_HISTORY_STATE_KEY]: {
+        sessionId: currentHistoryState?.sessionId,
+        stepId: 'CONFIGURE_BOOT',
+        position: 0,
+      },
+    });
+    await flushPromises();
+    await wrapper.vm.$nextTick();
+
+    expect(stepperPropsRef.value).toMatchObject({
+      activeStepIndex: 0,
+    });
+    expect(wrapper.find('[data-testid="internal-boot-step-stub"]').exists()).toBe(true);
+  });
+
+  it('closes when browser back leaves a fully applied result', async () => {
+    draftStore.internalBootSelection = {
+      poolName: 'cache',
+      slotCount: 1,
+      devices: ['DISK-A'],
+      bootSizeMiB: 16384,
+      updateBios: true,
+    };
+
+    const wrapper = mountComponent();
+
+    await wrapper.get('[data-testid="internal-boot-step-complete"]').trigger('click');
+    await flushPromises();
+
+    const currentHistoryState = getInternalBootHistoryState();
+    expect(currentHistoryState).toMatchObject({
+      stepId: 'SUMMARY',
+      position: 1,
+    });
+
+    dispatchPopstate({
+      [INTERNAL_BOOT_HISTORY_STATE_KEY]: {
+        sessionId: currentHistoryState?.sessionId,
+        stepId: 'CONFIGURE_BOOT',
+        position: 0,
+      },
+    });
+    await flushPromises();
+
+    expect(cleanupOnboardingStorageMock).toHaveBeenCalledTimes(1);
+    expect(wrapper.find('[data-testid="dialog-stub"]').exists()).toBe(false);
+  });
+
   it('closes locally after showing a result', async () => {
+    const historyGoSpy = vi.spyOn(window.history, 'go').mockImplementation(() => {});
     const wrapper = mountComponent();
 
     await wrapper.get('[data-testid="internal-boot-step-complete"]').trigger('click');
@@ -287,24 +398,38 @@ describe('OnboardingInternalBoot.standalone.vue', () => {
     await wrapper.get('[data-testid="internal-boot-standalone-result-close"]').trigger('click');
     await flushPromises();
 
+    expect(historyGoSpy).toHaveBeenCalledWith(-2);
+    dispatchPopstate(null);
+    await flushPromises();
+
     expect(wrapper.find('[data-testid="internal-boot-standalone-result"]').exists()).toBe(false);
   });
 
   it('closes when the shared dialog requests dismissal', async () => {
+    const historyGoSpy = vi.spyOn(window.history, 'go').mockImplementation(() => {});
     const wrapper = mountComponent();
 
     await wrapper.get('[data-testid="dialog-dismiss"]').trigger('click');
     await flushPromises();
 
+    expect(historyGoSpy).toHaveBeenCalledWith(-1);
+    dispatchPopstate(null);
+    await flushPromises();
+
     expect(wrapper.find('[data-testid="dialog-stub"]').exists()).toBe(false);
   });
 
   it('closes via the top-right X button', async () => {
+    const historyGoSpy = vi.spyOn(window.history, 'go').mockImplementation(() => {});
     const wrapper = mountComponent();
 
     await wrapper.get('[data-testid="internal-boot-standalone-close"]').trigger('click');
     await flushPromises();
 
+    expect(historyGoSpy).toHaveBeenCalledWith(-1);
+    dispatchPopstate(null);
+    await flushPromises();
+
     expect(cleanupOnboardingStorageMock).toHaveBeenCalledTimes(1);
     expect(wrapper.find('[data-testid="dialog-stub"]').exists()).toBe(false);
   });
@@ -337,6 +462,7 @@ describe('OnboardingInternalBoot.standalone.vue', () => {
   });
 
   it('clears onboarding storage when closing after a successful result', async () => {
+    vi.spyOn(window.history, 'go').mockImplementation(() => {});
     const wrapper = mountComponent();
 
     await wrapper.get('[data-testid="internal-boot-step-complete"]').trigger('click');
@@ -347,6 +473,9 @@ describe('OnboardingInternalBoot.standalone.vue', () => {
     await wrapper.get('[data-testid="internal-boot-standalone-result-close"]').trigger('click');
     await flushPromises();
 
+    dispatchPopstate(null);
+    await flushPromises();
+
     expect(cleanupOnboardingStorageMock).toHaveBeenCalledTimes(1);
   });
 });