mirror of
https://dev.azure.com/globalhealthx/EMR/_git/helix-engage
synced 2026-04-12 02:38:15 +00:00
feat(onboarding/phase-2): settings hub, setup wizard shell, first-run redirect
Phase 2 of hospital onboarding & self-service plan
(docs/superpowers/plans/2026-04-06-hospital-onboarding-self-service.md
checked in here for the helix-engage repo).
Frontend foundations for the staff-portal Settings hub and 6-step setup
wizard. Backend was Phase 1 (helix-engage-server commit).
New shared components (src/components/setup/):
- wizard-shell.tsx — fullscreen layout with left step navigator, progress
bar, and Skip-for-now affordance
- wizard-step.tsx — single-step wrapper with Mark Complete + Prev/Next/
Finish navigation, completion badge
- section-card.tsx — Settings hub card with title/description/icon, links
to a section page, optional status badge mirroring setup-state
New pages:
- pages/setup-wizard.tsx — top-level /setup route, fullscreen (no AppShell),
loads setup-state from sidecar, renders the active step. Each step has a
placeholder body for now; Phase 5 swaps placeholders for real form
components from the matching settings pages. Already functional end-to-end:
Mark Complete writes to PUT /api/config/setup-state/steps/<step>, Skip
posts to /dismiss, Finish navigates to /.
- pages/team-settings.tsx — moved the existing workspace member listing out
of the old monolithic settings.tsx into its own /settings/team route. No
functional change; Phase 3 will add the invite form + role editor here.
- pages/settings-placeholder.tsx — generic "Coming in Phase X" stub used by
routes for clinics, doctors, telephony, ai, widget until those pages land.
Modified pages:
- pages/settings.tsx — rewritten as the Settings hub (the new /settings
route). Renders SectionCards in 3 groups (Hospital identity, Care
delivery, Channels & automation) with completion badges sourced from
/api/config/setup-state. The hub links to existing pages (/branding,
/rules) and to placeholder pages for the not-yet-built sections.
- pages/login.tsx — after successful login, calls getSetupState() and
redirects to /setup if wizardRequired. Failures fall through to / so an
older sidecar without the setup-state endpoint still works.
- components/layout/sidebar.tsx — collapsed the Configuration group
(Rules Engine + Branding standalone entries) into the single Settings
entry that opens the hub. Removes the IconSlidersUp import that's no
longer used.
New types and helpers (src/lib/setup-state.ts):
- SetupState / SetupStepName / SetupStepStatus types mirroring the sidecar
shape
- SETUP_STEP_NAMES constant + SETUP_STEP_LABELS map (title + description
per step) — single source of truth used by the wizard, hub, and any
future surface that wants to render step metadata
- getSetupState / markSetupStepComplete / markSetupStepIncomplete /
dismissSetupWizard / resetSetupState helpers wrapping the api-client
Other:
- lib/api-client.ts — added apiClient.put() helper for the setup-state
step update mutations (PUT was the only verb missing from the existing
get/post/graphql helpers)
- main.tsx — registered new routes:
/setup (fullscreen, no AppShell)
/settings (the hub, replaces old settings.tsx)
/settings/team (moved member listing)
/settings/clinics (placeholder, Phase 3)
/settings/doctors (placeholder, Phase 3)
/settings/telephony (placeholder, Phase 4)
/settings/ai (placeholder, Phase 4)
/settings/widget (placeholder, Phase 4)
Tested via npx tsc --noEmit and npm run build (clean, only pre-existing
chunk-size and dynamic-import warnings unrelated to this change).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
67
src/components/setup/section-card.tsx
Normal file
67
src/components/setup/section-card.tsx
Normal file
@@ -0,0 +1,67 @@
|
||||
import { Link } from 'react-router';
|
||||
import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
|
||||
import { faArrowRight, faCircleCheck, faCircleExclamation } from '@fortawesome/pro-duotone-svg-icons';
|
||||
import { cx } from '@/utils/cx';
|
||||
|
||||
type SectionStatus = 'complete' | 'incomplete' | 'unknown';
|
||||
|
||||
type SectionCardProps = {
|
||||
title: string;
|
||||
description: string;
|
||||
icon: any;
|
||||
iconColor?: string;
|
||||
href: string;
|
||||
status?: SectionStatus;
|
||||
};
|
||||
|
||||
// Settings hub card. Each card represents one setup-able section (Branding,
|
||||
// Clinics, Doctors, Team, Telephony, AI, Widget, Rules) and links to its
|
||||
// dedicated page. The status badge mirrors the wizard's setup-state so an
|
||||
// admin can see at a glance which sections still need attention.
|
||||
export const SectionCard = ({
|
||||
title,
|
||||
description,
|
||||
icon,
|
||||
iconColor = 'text-brand-primary',
|
||||
href,
|
||||
status = 'unknown',
|
||||
}: SectionCardProps) => {
|
||||
return (
|
||||
<Link
|
||||
to={href}
|
||||
className="group block rounded-xl border border-secondary bg-primary p-5 shadow-xs transition hover:border-brand hover:shadow-md"
|
||||
>
|
||||
<div className="flex items-start justify-between gap-4">
|
||||
<div className="flex items-start gap-4">
|
||||
<div className="flex size-11 shrink-0 items-center justify-center rounded-lg bg-secondary">
|
||||
<FontAwesomeIcon icon={icon} className={cx('size-5', iconColor)} />
|
||||
</div>
|
||||
<div className="min-w-0">
|
||||
<h3 className="text-sm font-semibold text-primary">{title}</h3>
|
||||
<p className="mt-1 text-xs text-tertiary">{description}</p>
|
||||
</div>
|
||||
</div>
|
||||
<FontAwesomeIcon
|
||||
icon={faArrowRight}
|
||||
className="size-4 shrink-0 text-quaternary transition group-hover:translate-x-0.5 group-hover:text-brand-primary"
|
||||
/>
|
||||
</div>
|
||||
|
||||
{status !== 'unknown' && (
|
||||
<div className="mt-4 flex items-center gap-2 border-t border-secondary pt-3">
|
||||
{status === 'complete' ? (
|
||||
<span className="inline-flex items-center gap-1.5 text-xs font-medium text-success-primary">
|
||||
<FontAwesomeIcon icon={faCircleCheck} className="size-3.5" />
|
||||
Configured
|
||||
</span>
|
||||
) : (
|
||||
<span className="inline-flex items-center gap-1.5 text-xs font-medium text-warning-primary">
|
||||
<FontAwesomeIcon icon={faCircleExclamation} className="size-3.5" />
|
||||
Setup needed
|
||||
</span>
|
||||
)}
|
||||
</div>
|
||||
)}
|
||||
</Link>
|
||||
);
|
||||
};
|
||||
106
src/components/setup/wizard-shell.tsx
Normal file
106
src/components/setup/wizard-shell.tsx
Normal file
@@ -0,0 +1,106 @@
|
||||
import type { ReactNode } from 'react';
|
||||
import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
|
||||
import { faCircleCheck, faCircle } from '@fortawesome/pro-duotone-svg-icons';
|
||||
import { Button } from '@/components/base/buttons/button';
|
||||
import { cx } from '@/utils/cx';
|
||||
import { SETUP_STEP_NAMES, SETUP_STEP_LABELS, type SetupStepName, type SetupState } from '@/lib/setup-state';
|
||||
|
||||
type WizardShellProps = {
|
||||
state: SetupState;
|
||||
activeStep: SetupStepName;
|
||||
onSelectStep: (step: SetupStepName) => void;
|
||||
onDismiss: () => void;
|
||||
children: ReactNode;
|
||||
};
|
||||
|
||||
// Layout shell for the onboarding wizard. Renders a left-side step navigator
|
||||
// (with completed/active/upcoming visual states) and a right-side content
|
||||
// pane fed by the parent. The header has a "Skip for now" affordance that
|
||||
// dismisses the wizard for this workspace — once dismissed it never auto-shows
|
||||
// again on login.
|
||||
export const WizardShell = ({ state, activeStep, onSelectStep, onDismiss, children }: WizardShellProps) => {
|
||||
const completedCount = SETUP_STEP_NAMES.filter(s => state.steps[s].completed).length;
|
||||
const totalSteps = SETUP_STEP_NAMES.length;
|
||||
const progressPct = Math.round((completedCount / totalSteps) * 100);
|
||||
|
||||
return (
|
||||
<div className="min-h-screen bg-primary">
|
||||
{/* header */}
|
||||
<header className="border-b border-secondary bg-primary px-8 py-5">
|
||||
<div className="mx-auto flex max-w-6xl items-center justify-between gap-6">
|
||||
<div>
|
||||
<h1 className="text-xl font-bold text-primary">Set up your hospital</h1>
|
||||
<p className="mt-1 text-sm text-tertiary">
|
||||
{completedCount} of {totalSteps} steps complete · finish setup to start using your workspace
|
||||
</p>
|
||||
</div>
|
||||
<Button color="link-gray" size="sm" onClick={onDismiss}>
|
||||
Skip for now
|
||||
</Button>
|
||||
</div>
|
||||
{/* progress bar */}
|
||||
<div className="mx-auto mt-4 max-w-6xl">
|
||||
<div className="h-1.5 w-full overflow-hidden rounded-full bg-secondary">
|
||||
<div
|
||||
className="h-full rounded-full bg-brand-solid transition-all duration-300"
|
||||
style={{ width: `${progressPct}%` }}
|
||||
/>
|
||||
</div>
|
||||
</div>
|
||||
</header>
|
||||
|
||||
{/* body — step navigator + content */}
|
||||
<div className="mx-auto flex max-w-6xl gap-8 px-8 py-8">
|
||||
<nav className="w-72 shrink-0">
|
||||
<ol className="flex flex-col gap-1">
|
||||
{SETUP_STEP_NAMES.map((step, idx) => {
|
||||
const meta = SETUP_STEP_LABELS[step];
|
||||
const status = state.steps[step];
|
||||
const isActive = step === activeStep;
|
||||
const isComplete = status.completed;
|
||||
return (
|
||||
<li key={step}>
|
||||
<button
|
||||
type="button"
|
||||
onClick={() => onSelectStep(step)}
|
||||
className={cx(
|
||||
'group flex w-full items-start gap-3 rounded-lg border px-3 py-3 text-left transition',
|
||||
isActive
|
||||
? 'border-brand bg-brand-primary'
|
||||
: 'border-transparent hover:bg-secondary',
|
||||
)}
|
||||
>
|
||||
<span className="mt-0.5 shrink-0">
|
||||
<FontAwesomeIcon
|
||||
icon={isComplete ? faCircleCheck : faCircle}
|
||||
className={cx(
|
||||
'size-5',
|
||||
isComplete ? 'text-success-primary' : 'text-quaternary',
|
||||
)}
|
||||
/>
|
||||
</span>
|
||||
<span className="flex-1">
|
||||
<span className="block text-xs font-medium text-tertiary">
|
||||
Step {idx + 1}
|
||||
</span>
|
||||
<span
|
||||
className={cx(
|
||||
'block text-sm font-semibold',
|
||||
isActive ? 'text-brand-primary' : 'text-primary',
|
||||
)}
|
||||
>
|
||||
{meta.title}
|
||||
</span>
|
||||
</span>
|
||||
</button>
|
||||
</li>
|
||||
);
|
||||
})}
|
||||
</ol>
|
||||
</nav>
|
||||
|
||||
<main className="min-w-0 flex-1">{children}</main>
|
||||
</div>
|
||||
</div>
|
||||
);
|
||||
};
|
||||
105
src/components/setup/wizard-step.tsx
Normal file
105
src/components/setup/wizard-step.tsx
Normal file
@@ -0,0 +1,105 @@
|
||||
import type { ReactNode } from 'react';
|
||||
import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
|
||||
import { faArrowLeft, faArrowRight, faCircleCheck } from '@fortawesome/pro-duotone-svg-icons';
|
||||
import { Button } from '@/components/base/buttons/button';
|
||||
import { SETUP_STEP_LABELS, type SetupStepName } from '@/lib/setup-state';
|
||||
|
||||
type WizardStepProps = {
|
||||
step: SetupStepName;
|
||||
isCompleted: boolean;
|
||||
isLast: boolean;
|
||||
onPrev: (() => void) | null;
|
||||
onNext: (() => void) | null;
|
||||
onMarkComplete: () => void;
|
||||
onFinish: () => void;
|
||||
saving?: boolean;
|
||||
children: ReactNode;
|
||||
};
|
||||
|
||||
// Single-step wrapper. The parent picks which step is active and supplies
|
||||
// the form content as children. The step provides title, description,
|
||||
// "mark complete" CTA, and prev/next/finish navigation. In Phase 5 the
|
||||
// children will be real form components from the corresponding settings
|
||||
// pages — for now they're placeholders.
|
||||
export const WizardStep = ({
|
||||
step,
|
||||
isCompleted,
|
||||
isLast,
|
||||
onPrev,
|
||||
onNext,
|
||||
onMarkComplete,
|
||||
onFinish,
|
||||
saving = false,
|
||||
children,
|
||||
}: WizardStepProps) => {
|
||||
const meta = SETUP_STEP_LABELS[step];
|
||||
|
||||
return (
|
||||
<div className="rounded-xl border border-secondary bg-primary p-8 shadow-xs">
|
||||
<div className="mb-6 flex items-start justify-between gap-4">
|
||||
<div>
|
||||
<h2 className="text-2xl font-bold text-primary">{meta.title}</h2>
|
||||
<p className="mt-1 text-sm text-tertiary">{meta.description}</p>
|
||||
</div>
|
||||
{isCompleted && (
|
||||
<span className="inline-flex items-center gap-2 rounded-full bg-success-primary px-3 py-1 text-xs font-medium text-success-primary">
|
||||
<FontAwesomeIcon icon={faCircleCheck} className="size-3.5" />
|
||||
Complete
|
||||
</span>
|
||||
)}
|
||||
</div>
|
||||
|
||||
<div className="mb-8">{children}</div>
|
||||
|
||||
<div className="flex items-center justify-between gap-4 border-t border-secondary pt-6">
|
||||
<Button
|
||||
color="secondary"
|
||||
size="md"
|
||||
isDisabled={!onPrev}
|
||||
onClick={onPrev ?? undefined}
|
||||
iconLeading={({ className }: { className?: string }) => (
|
||||
<FontAwesomeIcon icon={faArrowLeft} className={className} />
|
||||
)}
|
||||
>
|
||||
Previous
|
||||
</Button>
|
||||
|
||||
<div className="flex items-center gap-3">
|
||||
{!isCompleted && (
|
||||
<Button
|
||||
color="primary"
|
||||
size="md"
|
||||
isLoading={saving}
|
||||
showTextWhileLoading
|
||||
onClick={onMarkComplete}
|
||||
>
|
||||
Mark complete
|
||||
</Button>
|
||||
)}
|
||||
{isLast ? (
|
||||
<Button
|
||||
color="primary"
|
||||
size="md"
|
||||
isDisabled={!isCompleted}
|
||||
onClick={onFinish}
|
||||
>
|
||||
Finish setup
|
||||
</Button>
|
||||
) : (
|
||||
<Button
|
||||
color={isCompleted ? 'primary' : 'secondary'}
|
||||
size="md"
|
||||
isDisabled={!onNext}
|
||||
onClick={onNext ?? undefined}
|
||||
iconTrailing={({ className }: { className?: string }) => (
|
||||
<FontAwesomeIcon icon={faArrowRight} className={className} />
|
||||
)}
|
||||
>
|
||||
Next
|
||||
</Button>
|
||||
)}
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
);
|
||||
};
|
||||
Reference in New Issue
Block a user