Files
PaperClipAI/ui/src/components/onboarding/Stepper.tsx
T
TonioandClaude Opus 5 42c6f8a424 Onboarding: model source tiles, one input canvas, and Storybook coverage for the agent arc (#12613)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - New customers meet it through onboarding, whose last three steps run
inside the tenant: create an agent, connect a model, review
> - The connect step is the one that decides whether the agent can run
at all, and it had drifted — three contributors changed it in parallel,
and its visual language no longer matched the rest of the flow
> - It also could not be looked at without a provisioned stack, so
defects in it were only found by walking a real signup, and the review
step behind it could not be reached at all when it failed
> - This pull request brings the visual work onto the sign-in behaviour
that already shipped, and adds Storybook coverage for all three steps
> - The benefit is that the step is easier to read, and that it can now
be inspected and driven before it ships rather than after

## Linked Issues or Issue Description

**What existing behavior does this improve?**
The onboarding connect-a-model step. It presented the model choice as a
dropdown plus an "Advanced settings" disclosure, and put each credential
type in a different place, so the controls below moved whenever the
choice changed.

**Subsystem affected**
Tenant onboarding wizard (`ui/src/components/OnboardingWizard.tsx`) and
its Storybook coverage.

**Current behavior**
The step offered every registered adapter through a disclosure.
Credential entry appeared in a different shape per source. None of the
three agent-arc steps could be rendered outside a provisioned cloud
stack, so the sign-in panel and the review step were only reachable by
walking a real signup.

**Proposed behavior**
Two brand tiles for the recommended sources, a link that switches
between subscription and API-key credentials, and one canvas that holds
whichever input the current choice needs. Storybook stories mount the
real wizard against fixtures and walk it forward, so every step and its
states can be inspected locally.

**Reason and benefit**
The step reads as one decision rather than three scattered ones, and its
furniture stays still while the choice changes. The stories mean a
regression in it is visible before release instead of during a signup.

**Breaking changes**
No API or schema change. One behavioural narrowing, described under
Risks.

## What Changed

- Replaces the adapter dropdown and "Advanced settings" disclosure with
`ModelSourceTiles` — brand tiles for Claude Code and Codex.
- Adds `CredentialModeLink`, a text toggle between subscription sign-in
and API keys, replacing the disclosure.
- Adds `ConnectInputCanvas`: one surface that holds the sign-in panel or
the API-key field and resizes between them, so the Connect button below
does not move.
- Keeps the existing sign-in behaviour unchanged. `AgentConfigForm`
changes are presentation only — the provider name in the title, the CTA
wording, and `space-y` to `gap`. No change to the login mutations,
queries, or session handling.
- Restores the sleep marks on the dormant agent for the two steps before
the hire.
- Adds Storybook stories for all three agent-arc steps, with fixtures
for the environments, auth signal, both adapters' login flows, and the
hire.
- Copy: names the provider being signed in to ("Sign in to
Anthropic"/"Sign in to OpenAI"), and drops "Clippy" from the agent-name
helper text.

## Verification

- `pnpm vitest run src/components storybook` in `ui/` — 139 tests over
the touched suites, 1986 across `src/components`.
- `pnpm typecheck` in `ui/` — clean.
- Storybook, `Onboarding/Agent arc`: walk each story. Step 1 has no Back
button, steps 2 and 3 do.
- The sign-in gate: on `Connect a model`, press Connect without signing
in. It holds on step 2 and reports "No working authentication was
found." On `Review`, which fixtures an authenticated signal, Connect
reaches the review step.
- Both providers' login flows: press Sign in on the Claude tile for the
authorization URL and browser-code field, and on the Codex tile for the
device URL and code.
- The Claude sign-in was also walked end to end on a staging tenant,
including the OAuth redirect and pasting the code back.

## Risks

- **Onboarding now offers two model sources instead of every registered
adapter.** `ModelSourceTiles` is fed the `recommended` set, which is
`claude_local` and `codex_local`; Gemini, Cursor, Grok, Kimi, OpenCode
and Paperclip Runner are no longer selectable *during onboarding*. This
is deliberate. The full list is unchanged in agent settings, which is
where an adapter can still be switched after the agent exists, and
adding a source back is one `recommended: true` in
`adapter-display-registry.ts`. Flagging it because it is the one
behavioural narrowing here and it is not visible from the diffstat.
- The API key entered on this step is held in component state and
deliberately never written to the onboarding draft, because that draft
is `localStorage`. A customer who leaves mid-step re-enters the key;
that is the intended trade.
- Storybook-only risk: the fixtures now answer the environment test from
the story's auth state. If a future change moves the hire's gate off the
`adapter_auth_missing` check code, the stories would keep passing while
the product regressed. The gate is asserted in the adapter packages' own
tests, not here.
- Motion changes are low risk and reversible: the input canvas animates
its contents only, and its container was deliberately left unanimated
after an animated wrapper clipped the sign-in panel.

## Model Used

Claude Opus 5 (`claude-opus-5`), via Claude Code with extended thinking,
tool use, and browser-driven verification of the Storybook stories.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [ ] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-09-01 09:57:46 -07:00

142 lines
5.6 KiB
TypeScript

import { cn } from "../../lib/utils";
/**
* The agent arc — create the agent, connect it, review — is the part of the
* wizard a customer walks as a numbered sequence. Company creation happens in
* Cloud before the tenant is ever reached, so it is not one of these steps.
*/
export const AGENT_ARC_TOTAL_STEPS = 3;
/**
* What each segment goes to. These are the labels assistive tech reads, in
* place of a bare number: the wizard has its own step numbering, and two
* controls both announcing "Step 1" while meaning different steps is worse
* than no number at all. The strip's own "Step N of 3" line carries the count.
*/
export const AGENT_ARC_STEP_LABELS = [
"Create your first agent",
"Connect a model",
"Review",
] as const;
/** Wizard step numbers that make up the arc, in order. */
export const AGENT_ARC_WIZARD_STEPS = [3, 4, 5] as const;
/**
* The full walk, for a run that started at the front door rather than partway
* into the arc.
*
* Step 2 is absent: onboarding no longer asks for the mission, so a segment for
* it would be one the run can never fill. The run still passes *through* step 2
* on the "grow" path, which is why position is counted rather than looked up —
* see `onboardingStepPositionFor`.
*/
export const ONBOARDING_WIZARD_STEPS = [1, 3, 4, 5] as const;
/** Destinations for the full walk, in the same order. */
export const ONBOARDING_STEP_LABELS = [
"Name your organization",
"Create your first agent",
"Connect a model",
"Review",
] as const;
/**
* Position in the full walk: how many of its steps are at or behind `step`.
*
* Counted rather than indexed because the wizard visits steps the strip does
* not draw. On the mission step there is no segment to be "on", and an index
* lookup would return nothing and light none of them — reporting no progress
* from a screen the customer reached by making progress. Counting keeps the
* strip on the last segment actually completed.
*/
export function onboardingStepPositionFor(step: number): number {
return ONBOARDING_WIZARD_STEPS.filter((entry) => entry <= step).length;
}
/**
* Map a wizard step onto its position in the arc, or `null` when the step is
* outside it.
*
* The two numbering schemes exist for different reasons and must not be
* conflated: the wizard's own step numbers include entries the customer may
* never see (the front door, and the company/mission steps that are skipped
* when Cloud already created the company), while the strip counts only what
* this leg of the walk actually shows. Deriving one from the other with
* arithmetic would silently produce "Step 0 of 3" the first time a step is
* inserted ahead of the arc.
*/
export function agentArcStepFor(wizardStep: number): number | null {
const index = AGENT_ARC_WIZARD_STEPS.indexOf(wizardStep as (typeof AGENT_ARC_WIZARD_STEPS)[number]);
return index === -1 ? null : index + 1;
}
/**
* Segmented progress strip: three dots, centred over the step's own centred
* hero and heading.
*
* The "Step N of M" count is announced but not drawn. Three dots at this size
* are read in a glance — there is no counting to help with — so the line was
* spending a whole row, and the only left-aligned element on an otherwise
* centred step, to restate what the dots already say. Assistive tech has no
* glance, so the sentence stays in the accessibility tree.
*
* Segments double as the way back to a step already completed, which is the
* affordance the wizard's full-length bar provides outside the arc. A segment
* the customer may not return to stays a disabled button rather than
* disappearing: the wizard can be entered partway in, and a strip that simply
* omitted the steps behind the entry point would misreport how far along they
* are.
*/
export function Stepper({
step,
total = AGENT_ARC_TOTAL_STEPS,
labels = AGENT_ARC_STEP_LABELS,
canJumpToStep,
onJumpToStep,
}: {
step: number;
total?: number;
/**
* What each segment goes to. Defaults to the arc's three; the full walk from
* the front door passes its own four, since the same strip serves both and a
* segment announcing "Create your first agent" on the organization step would
* be worse than a bare number.
*/
labels?: readonly string[];
canJumpToStep?: (target: number) => boolean;
onJumpToStep?: (target: number) => void;
}) {
return (
<div className="mb-11 flex items-center justify-center gap-2">
{Array.from({ length: total }, (_, index) => index + 1).map((segment) => {
const jumpable = Boolean(canJumpToStep?.(segment) && onJumpToStep);
return (
<button
key={segment}
type="button"
aria-label={labels[segment - 1] ?? `Step ${segment}`}
aria-current={segment === step ? "step" : undefined}
disabled={!jumpable}
onClick={() => jumpable && onJumpToStep?.(segment)}
className={cn(
// Dots, not bars: three of them, keeping the bar strip's gap so
// the rhythm is unchanged. A full-width bar implied a continuous
// quantity — how much of the arc is done — which three discrete
// steps do not have. At 6px they carry the row on their own now
// that no label sits under them.
"size-1.5 shrink-0 rounded-full transition-colors",
segment <= step ? "bg-foreground" : "bg-border",
jumpable ? "cursor-pointer" : "cursor-default",
)}
/>
);
})}
{/* Out of flow, so it neither takes a row nor picks up the gap. */}
<span className="sr-only">
Step {step} of {total}
</span>
</div>
);
}