The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
Render the onboarding agent arc's real steps in Storybook (#12369)
Tonio4436cf00a2e2
diff --git a/ui/storybook/.storybook/preview.tsx b/ui/storybook/.storybook/preview.tsxindex 5643e371d8..b4a1b93276 100644--- a/ui/storybook/.storybook/preview.tsx+++ b/ui/storybook/.storybook/preview.tsx@@ -3,6 +3,7 @@ import type { Preview } from "@storybook/react-vite";import { QueryClient, QueryClientProvider } from "@tanstack/react-query";import type { WorkTimelineResult } from "@paperclipai/shared";import { MemoryRouter } from "@/lib/router";+import { ONBOARDING_STORAGE_KEY } from "@/components/OnboardingWizard";import { BreadcrumbProvider } from "@/context/BreadcrumbContext";import { CompanyProvider } from "@/context/CompanyContext";import { DialogProvider } from "@/context/DialogContext";@@ -130,6 +131,23 @@ function installStorybookApiFixtures() {});}+ if (url.pathname === "/api/instance/settings") {+ return Response.json({});+ }++ // The onboarding wizard's connect step reads these. An empty environment+ // list is the cloud-tenant shape — agents run in a managed sandbox rather+ // than a configured environment — and it is also the state that produces+ // the "no managed sandbox environment is available" notice, which is worth+ // being able to look at rather than only meeting it on a live stack.+ if (/^\/api\/companies\/[^/]+\/environments$/.test(url.pathname)) {+ return Response.json([]);+ }++ if (/^\/api\/companies\/[^/]+\/adapters\/[^/]+\/models$/.test(url.pathname)) {+ return Response.json([]);+ }+if (url.pathname === "/api/adapters") {return Response.json([{@@ -449,6 +467,28 @@ const preview: Preview = {},},},++ /**+ * Every story starts without an onboarding draft.+ *+ * `localStorage` is per-origin and the preview frame keeps one for the whole+ * session, so a story that seeds a draft would otherwise hand it to whatever a+ * reviewer opens next: the wizard restores that saved step ahead of the step+ * the new story asked for, and the reviewer lands on a screen they never+ * clicked on.+ *+ * Cleared here rather than on the seeding story's unmount, deliberately.+ * Switching stories navigates the preview iframe, so the page is torn down+ * rather than React-unmounted and an unmount cleanup never runs — which is+ * exactly how the first attempt at this leaked anyway.+ */+ beforeEach: () => {+ try {+ window.localStorage.removeItem(ONBOARDING_STORAGE_KEY);+ } catch {+ // Storage access throws in some privacy modes; nothing to clean up there.+ }+ },};export default preview;diff --git a/ui/storybook/fixtures/onboardingDraft.test.ts b/ui/storybook/fixtures/onboardingDraft.test.tsnew file mode 100644index 0000000000..d086011d7f--- /dev/null+++ b/ui/storybook/fixtures/onboardingDraft.test.ts@@ -0,0 +1,66 @@+// @vitest-environment jsdom++import { afterEach, describe, expect, it } from "vitest";++import { ONBOARDING_STORAGE_KEY } from "@/components/OnboardingWizard";+import {+ STORYBOOK_AGENT_ID,+ STORYBOOK_COMPANY_ID,+ clearOnboardingDraft,+ readOnboardingDraft,+ seedOnboardingDraft,+} from "./onboardingDraft";++afterEach(() => {+ window.localStorage.clear();+});++describe("storybook onboarding draft", () => {+ // The leak this exists to stop: `localStorage` is per-origin and shared by+ // every story in a session, so a seeded draft left behind makes the *next*+ // story restore a saved step instead of the one it asked for. The reviewer+ // then sees a screen they did not click on, which reads as a wizard bug.+ it("leaves nothing behind once cleared", () => {+ seedOnboardingDraft(5);+ expect(readOnboardingDraft()).not.toBeNull();++ clearOnboardingDraft();+ expect(readOnboardingDraft()).toBeNull();+ expect(window.localStorage.getItem(ONBOARDING_STORAGE_KEY)).toBeNull();+ });++ it("writes the step the story asked for", () => {+ for (const step of [3, 4, 5] as const) {+ seedOnboardingDraft(step);+ expect(readOnboardingDraft()?.step).toBe(step);+ }+ });++ // `createdAgentId` is what `launchStateIncomplete` checks. Filling it in+ // before the hire would paint over the guard step 5 is supposed to show when+ // it is reached without an agent, so the earlier steps must leave it empty.+ it("only claims an agent exists from the review step onward", () => {+ seedOnboardingDraft(3);+ expect(readOnboardingDraft()?.createdAgentId).toBe("");++ seedOnboardingDraft(4);+ expect(readOnboardingDraft()?.createdAgentId).toBe("");++ seedOnboardingDraft(5);+ expect(readOnboardingDraft()?.createdAgentId).toBe(STORYBOOK_AGENT_ID);+ });++ // `restoreOnboardingState` treats restoring as an authorization decision and+ // throws the whole blob away when the saved company is not one the account+ // owns. Seeding a company the fixtures do not report would silently restore+ // nothing, and every story would quietly fall back to its `initialStep`.+ it("names the company the fixtures report as owned", () => {+ seedOnboardingDraft(5);+ expect(readOnboardingDraft()?.createdCompanyId).toBe(STORYBOOK_COMPANY_ID);+ });++ it("survives a malformed value without throwing", () => {+ window.localStorage.setItem(ONBOARDING_STORAGE_KEY, "{not json");+ expect(readOnboardingDraft()).toBeNull();+ });+});diff --git a/ui/storybook/fixtures/onboardingDraft.ts b/ui/storybook/fixtures/onboardingDraft.tsnew file mode 100644index 0000000000..2af977c54c--- /dev/null+++ b/ui/storybook/fixtures/onboardingDraft.ts@@ -0,0 +1,50 @@+import { ONBOARDING_STORAGE_KEY } from "@/components/OnboardingWizard";++/**+ * The onboarding draft, as the wizard stories need to write it.+ *+ * `localStorage` is per-origin, so every story in a Storybook session shares+ * one. A story that seeds a draft and walks away leaves it for the next one:+ * the wizard restores a saved step ahead of whatever step that story asked for,+ * and the reviewer gets a screen they did not click on. So seeding and clearing+ * are a pair, and they live here rather than inline so the pairing is testable.+ *+ * The key is imported rather than restated. It is the wizard's, and a second+ * copy of a storage key is a bug waiting for the first one to be renamed.+ */++export const STORYBOOK_COMPANY_ID = "company-storybook";+export const STORYBOOK_AGENT_ID = "agent-storybook";++export function seedOnboardingDraft(step: 3 | 4 | 5): void {+ window.localStorage.setItem(+ ONBOARDING_STORAGE_KEY,+ JSON.stringify({+ step,+ companyName: "Paperclip Storybook",+ agentName: "Darnold",+ agentRole: "general",+ adapterType: "claude_code",+ createdCompanyId: STORYBOOK_COMPANY_ID,+ createdCompanyPrefix: "PAP",+ // Only from the review step onward. Before the hire there is no agent, and+ // filling this in earlier would hide the incomplete-state guard step 5+ // shows when it is reached without one.+ createdAgentId: step >= 5 ? STORYBOOK_AGENT_ID : "",+ }),+ );+}++export function clearOnboardingDraft(): void {+ window.localStorage.removeItem(ONBOARDING_STORAGE_KEY);+}++export function readOnboardingDraft(): Record<string, unknown> | null {+ const raw = window.localStorage.getItem(ONBOARDING_STORAGE_KEY);+ if (raw === null) return null;+ try {+ return JSON.parse(raw) as Record<string, unknown>;+ } catch {+ return null;+ }+}diff --git a/ui/storybook/stories/onboarding-agent-arc.stories.tsx b/ui/storybook/stories/onboarding-agent-arc.stories.tsxindex 710827d1a8..d4ec67077c 100644--- a/ui/storybook/stories/onboarding-agent-arc.stories.tsx+++ b/ui/storybook/stories/onboarding-agent-arc.stories.tsx@@ -1,12 +1,29 @@import type { Meta, StoryObj } from "@storybook/react-vite";-import { AgentCapsule } from "@/components/AgentCapsule";+import { useEffect, useState } from "react";++import { OnboardingWizard } from "@/components/OnboardingWizard";+import { PillGuy } from "@/components/onboarding/PillGuy";import { Stepper } from "@/components/onboarding/Stepper";+import { useCompanyListQuery } from "@/api/companies-query";+import { useDialog } from "@/context/DialogContext";+import {+ STORYBOOK_COMPANY_ID,+ clearOnboardingDraft,+ seedOnboardingDraft,+} from "../fixtures/onboardingDraft";/**- * The onboarding wizard's agent arc: create the agent, connect it, review.- * These are the three steps a customer walks inside the tenant — company- * creation happens in Cloud before they arrive, which is why the strip counts- * to three rather than to the wizard's own step numbers.+ * The onboarding wizard's agent arc: create the agent, connect a model, review.+ * These are the three steps a customer walks inside the tenant — the+ * organization is named in Cloud before they arrive, which is why the strip+ * counts to three rather than to the wizard's own step numbers.+ *+ * The step stories below mount the real wizard against the Storybook API+ * fixtures. That matters more here than in most stories: these screens only+ * render for a signed-in account that owns a provisioned stack, so before this+ * existed the only way to see them was to walk a real signup — and when the+ * connect step failed on a live stack, the review step behind it could not be+ * reached at all.*/const meta = {title: "Onboarding/Agent arc",@@ -15,6 +32,83 @@ const meta = {export default meta;+/**+ * Seeds the draft the wizard restores from, opens it, and takes the draft back+ * out again on the way past.+ *+ * Three details the wizard's own design forces:+ *+ * The draft is written during render, not in an effect. Roughly twenty+ * `useState(saved?.x ?? default)` initializers read the restored blob exactly+ * once, on first render, so a draft written after mount arrives too late to+ * matter.+ *+ * `createdCompanyId` has to be a company the fixtures report as owned.+ * `restoreOnboardingState` treats restoring as an authorization decision and+ * discards the whole blob when the saved company is not in the list — correctly,+ * since localStorage is per-origin and would otherwise hand one account's draft+ * to another.+ *+ * Step 5 is seeded rather than requested: `openOnboarding({ initialStep })`+ * accepts 1–4 only, because the review step is somewhere the wizard arrives+ * rather than somewhere it starts.+ *+ * And the cleanup is not housekeeping. That same per-origin storage is shared+ * with every other story in the session: a draft left behind makes the next+ * story restore a saved step ahead of the one it asked for, so the reviewer+ * lands on a screen they did not click on and reads it as a wizard bug.+ */+function WizardAtStep({ step }: { step: 3 | 4 | 5 }) {+ const [seeded] = useState(() => {+ seedOnboardingDraft(step);+ return true;+ });++ useEffect(() => clearOnboardingDraft, []);++ // Nothing is mounted until the companies list has settled, and that ordering+ // is load-bearing rather than tidiness. The wizard's own mount gate waits on+ // `isFetching`, but this query is *disabled* until the account settles, and a+ // disabled query is not fetching — so mounting immediately gets an inner+ // wizard whose ~20 one-shot initializers read a null draft, take `initialStep`+ // instead, and then persist that back over the seed. A real session does not+ // hit this because the dashboard has already loaded the list by the time+ // anyone opens onboarding.+ const companies = useCompanyListQuery();+ const ready = companies.isSuccess && companies.data !== undefined;++ const { openOnboarding } = useDialog();+ useEffect(() => {+ if (!seeded || !ready) return;+ // `initialStep` is deliberately omitted for the review step. An explicit+ // option overrides the restored draft — "options take precedence over saved+ // state" is the wizard's rule, not an accident — so passing one here would+ // clamp 5 to 4 and land on Connect. Steps 3 and 4 pass it because being+ // explicit is better when the option can express the step; step 5 cannot be+ // expressed that way, so the draft carries it alone.+ openOnboarding(+ step <= 4+ ? { initialStep: step as 3 | 4, companyId: STORYBOOK_COMPANY_ID }+ : { companyId: STORYBOOK_COMPANY_ID },+ );+ }, [seeded, ready, openOnboarding, step]);++ if (!ready) return null;+ return <OnboardingWizard />;+}++export const CreateYourAgent: StoryObj = {+ render: () => <WizardAtStep step={3} />,+};++export const ConnectAModel: StoryObj = {+ render: () => <WizardAtStep step={4} />,+};++export const Review: StoryObj = {+ render: () => <WizardAtStep step={5} />,+};+export const ProgressStrip: StoryObj = {render: () => (<div className="w-[420px] space-y-10">@@ -26,15 +120,15 @@ export const ProgressStrip: StoryObj = {};/**- * The capsule's three states, which the wizard holds in one tree slot so the- * morph reads as a single object coming to life rather than three renders.+ * The agent's two states, side by side. `dormant` waits to be configured;+ * `alive` is the hired agent on the review step.*/-export const CapsuleStates: StoryObj = {+export const PillStates: StoryObj = {render: () => (<div className="flex items-center gap-12">- {(["slot", "configured", "online"] as const).map((state) => (+ {(["dormant", "alive"] as const).map((state) => (<div key={state} className="flex flex-col items-center gap-3">- <AgentCapsule state={state} gradient={5} glow="blue" size="md" strokeDraw />+ <PillGuy state={state} className="size-(--sz-72px)" /><span className="text-(length:--text-micro) uppercase tracking-widest text-muted-foreground">{state}</span>@@ -45,20 +139,32 @@ export const CapsuleStates: StoryObj = {};/**- * The same three states rendered with the default cross-fade, for comparison- * with the traced outline above.+ * The transition on its own, on a loop.+ *+ * Worth a story of its own because it is the arc's payoff and the hardest part+ * to judge from a still. The two states share a silhouette but differ in fill,+ * eye shape, and a tuft the dormant state does not have at all, so they+ * cross-fade rather than path-morph — there is no honest interpolation between+ * them, and a faked one warps the eyes through shapes the design never draws.*/-export const CapsuleStatesCrossfade: StoryObj = {- render: () => (- <div className="flex items-center gap-12">- {(["slot", "configured", "online"] as const).map((state) => (- <div key={state} className="flex flex-col items-center gap-3">- <AgentCapsule state={state} gradient={5} glow="blue" size="md" />- <span className="text-(length:--text-micro) uppercase tracking-widest text-muted-foreground">- {state}- </span>- </div>- ))}- </div>- ),+export const PillMorph: StoryObj = {+ render: function PillMorphStory() {+ const [alive, setAlive] = useState(false);+ useEffect(() => {+ const id = setInterval(() => setAlive((v) => !v), 1800);+ return () => clearInterval(id);+ }, []);+ return (+ <div className="flex flex-col items-center gap-4">+ <PillGuy state={alive ? "alive" : "dormant"} className="size-(--sz-72px)" />+ <button+ type="button"+ onClick={() => setAlive((v) => !v)}+ className="text-(length:--text-micro) uppercase tracking-widest text-muted-foreground hover:text-foreground"+ >+ {alive ? "alive" : "dormant"} — click to toggle+ </button>+ </div>+ );+ },};