@shipfox/client-onboarding 23.0.0 → 25.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/client-onboarding",
   "license": "MIT",
-  "version": "23.0.0",
+  "version": "25.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -14,14 +14,21 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./feature": {
+      "types": "./dist/feature.d.ts",
+      "default": "./dist/feature.js"
     }
   },
   "dependencies": {
     "@swc/helpers": "^0.5.17",
-    "@shipfox/client-agent": "23.0.0",
-    "@shipfox/client-integrations": "23.0.0",
-    "@shipfox/client-projects": "23.0.0",
-    "@shipfox/client-shell": "23.0.0"
+    "@shipfox/client-agent": "25.0.0",
+    "@shipfox/client-integrations": "25.0.0",
+    "@shipfox/client-projects": "25.0.0",
+    "@shipfox/client-runners": "25.0.0",
+    "@shipfox/client-shell": "25.0.0",
+    "@shipfox/client-workspace-settings": "25.0.0",
+    "@shipfox/react-ui": "2.2.0"
   },
   "peerDependencies": {
     "@tanstack/react-query": "^5.101.0",

package/src/components/setup-checklist-body.tsx

@@ -0,0 +1,35 @@
+import {SetupChecklistCompletion} from './setup-checklist-completion.js';
+import {ChecklistRow} from './setup-checklist-row.js';
+import type {SetupChecklistBodyProps} from './setup-checklist-types.js';
+
+export function SetupChecklistBody({
+  checklist,
+  workspaceSlug,
+  completion = false,
+  showBurst = false,
+  onBurstComplete,
+  onAction,
+  onDone,
+}: SetupChecklistBodyProps) {
+  return (
+    <div>
+      {completion ? (
+        <SetupChecklistCompletion
+          showBurst={showBurst}
+          onBurstComplete={onBurstComplete}
+          onDone={onDone}
+        />
+      ) : null}
+      <ol aria-label="Setup steps" className="m-0 list-none p-0">
+        {checklist.items.map((item) => (
+          <ChecklistRow
+            key={item.id}
+            item={item}
+            workspaceSlug={workspaceSlug}
+            onAction={onAction}
+          />
+        ))}
+      </ol>
+    </div>
+  );
+}

package/src/components/setup-checklist-completion.test.tsx

@@ -0,0 +1,124 @@
+// @vitest-environment jsdom
+import '@testing-library/jest-dom/vitest';
+import {afterEach, describe, expect, test, vi} from '@shipfox/vitest/vi';
+import {act, render} from '@testing-library/react';
+import {SetupChecklistCompletion} from './setup-checklist-completion.js';
+import {CONFETTI_PARTICLE_COUNT} from './setup-checklist-confetti.js';
+
+const CONFETTI_START_TIME = 1000;
+const CONFETTI_DURATION_MS = 2000;
+const CANVAS_WIDTH = 480;
+const CANVAS_HEIGHT = 88;
+
+interface CanvasContextSpies {
+  clearRect: ReturnType<typeof vi.fn>;
+  fillRect: ReturnType<typeof vi.fn>;
+}
+
+function setupCanvas(reducedMotion: boolean): CanvasContextSpies {
+  vi.spyOn(window.navigator, 'userAgent', 'get').mockReturnValue('Mozilla/5.0');
+  vi.spyOn(window, 'matchMedia').mockImplementation(
+    (query) =>
+      ({
+        addEventListener: vi.fn(),
+        addListener: vi.fn(),
+        dispatchEvent: vi.fn(() => false),
+        matches: reducedMotion,
+        media: query,
+        onchange: null,
+        removeEventListener: vi.fn(),
+        removeListener: vi.fn(),
+      }) as MediaQueryList,
+  );
+
+  const clearRect = vi.fn();
+  const fillRect = vi.fn();
+  const context = {
+    clearRect,
+    fillRect,
+    fillStyle: '',
+    globalAlpha: 1,
+    restore: vi.fn(),
+    rotate: vi.fn(),
+    save: vi.fn(),
+    scale: vi.fn(),
+    translate: vi.fn(),
+  } as unknown as CanvasRenderingContext2D;
+
+  vi.spyOn(HTMLCanvasElement.prototype, 'getBoundingClientRect').mockReturnValue({
+    bottom: CANVAS_HEIGHT,
+    height: CANVAS_HEIGHT,
+    left: 0,
+    right: CANVAS_WIDTH,
+    top: 0,
+    width: CANVAS_WIDTH,
+    x: 0,
+    y: 0,
+    toJSON: () => ({}),
+  } as DOMRect);
+  vi.spyOn(HTMLCanvasElement.prototype, 'getContext').mockReturnValue(context);
+  vi.spyOn(window, 'getComputedStyle').mockReturnValue({
+    getPropertyValue: () => '#22c55e',
+  } as unknown as CSSStyleDeclaration);
+  vi.spyOn(performance, 'now').mockReturnValue(CONFETTI_START_TIME);
+
+  return {clearRect, fillRect};
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('SetupChecklistCompletion burst', () => {
+  test('keeps a reduced-motion frame after the host consumes the burst', () => {
+    const context = setupCanvas(true);
+    const requestAnimationFrame = vi.spyOn(window, 'requestAnimationFrame');
+    const onBurstComplete = vi.fn();
+    const {rerender} = render(
+      <SetupChecklistCompletion showBurst onBurstComplete={onBurstComplete} />,
+    );
+
+    expect(onBurstComplete).toHaveBeenCalledTimes(1);
+    expect(requestAnimationFrame).not.toHaveBeenCalled();
+    expect(context.fillRect).toHaveBeenCalledTimes(CONFETTI_PARTICLE_COUNT);
+
+    const clearCallsAfterDraw = context.clearRect.mock.calls.length;
+    rerender(<SetupChecklistCompletion showBurst={false} onBurstComplete={onBurstComplete} />);
+
+    expect(context.clearRect).toHaveBeenCalledTimes(clearCallsAfterDraw);
+    expect(context.fillRect).toHaveBeenCalledTimes(CONFETTI_PARTICLE_COUNT);
+  });
+
+  test('animates and completes the burst when motion is allowed', () => {
+    const context = setupCanvas(false);
+    let frameCallback: FrameRequestCallback | undefined;
+    const requestAnimationFrame = vi
+      .spyOn(window, 'requestAnimationFrame')
+      .mockImplementation((callback) => {
+        frameCallback = callback;
+        return 1;
+      });
+    const cancelAnimationFrame = vi.spyOn(window, 'cancelAnimationFrame');
+    const onBurstComplete = vi.fn();
+
+    render(<SetupChecklistCompletion showBurst onBurstComplete={onBurstComplete} />);
+
+    expect(requestAnimationFrame).toHaveBeenCalledTimes(1);
+    expect(context.fillRect).not.toHaveBeenCalled();
+
+    act(() => {
+      frameCallback?.(CONFETTI_START_TIME + 16);
+    });
+
+    expect(context.fillRect).toHaveBeenCalledTimes(CONFETTI_PARTICLE_COUNT);
+    expect(requestAnimationFrame).toHaveBeenCalledTimes(2);
+    expect(onBurstComplete).not.toHaveBeenCalled();
+
+    act(() => {
+      frameCallback?.(CONFETTI_START_TIME + CONFETTI_DURATION_MS);
+    });
+
+    expect(onBurstComplete).toHaveBeenCalledTimes(1);
+    expect(cancelAnimationFrame).not.toHaveBeenCalled();
+  });
+});

package/src/components/setup-checklist-completion.tsx

@@ -0,0 +1,165 @@
+import {Button} from '@shipfox/react-ui/button';
+import {Icon} from '@shipfox/react-ui/icon';
+import {Text} from '@shipfox/react-ui/typography';
+import {useEffect, useRef} from 'react';
+import {createConfettiParticles} from './setup-checklist-confetti.js';
+
+const JSDOM_USER_AGENT_RE = /jsdom/u;
+const CONFETTI_DURATION_MS = 2000;
+const CONFETTI_RANDOM_SEED = 0x5f3759df;
+
+export function SetupChecklistCompletion({
+  showBurst,
+  onBurstComplete,
+  onDone,
+}: {
+  showBurst: boolean;
+  onBurstComplete?: (() => void) | undefined;
+  onDone?: (() => void) | undefined;
+}) {
+  return (
+    <div className="relative overflow-hidden border-b border-tag-success-border bg-tag-success-bg p-panel">
+      <ConfettiBurst active={showBurst} onComplete={onBurstComplete} />
+      <div className="relative flex items-center gap-group">
+        <Icon
+          name="checkCircleSolid"
+          className="size-20 shrink-0 text-tag-success-icon"
+          aria-hidden="true"
+        />
+        <div className="min-w-0 flex-1">
+          <Text size="sm" bold className="text-tag-success-text">
+            You're set up
+          </Text>
+          <Text size="xs" className="text-tag-success-text">
+            Your workspace is ready for its first workflow.
+          </Text>
+        </div>
+        <Button type="button" size="sm" variant="primary" onClick={onDone}>
+          Done
+        </Button>
+      </div>
+    </div>
+  );
+}
+
+function ConfettiBurst({
+  active,
+  onComplete,
+}: {
+  active: boolean;
+  onComplete?: (() => void) | undefined;
+}) {
+  const canvasRef = useRef<HTMLCanvasElement>(null);
+
+  useEffect(() => {
+    if (!active || typeof window === 'undefined') return;
+    let completed = false;
+    const finish = () => {
+      if (completed) return;
+      completed = true;
+      onComplete?.();
+    };
+
+    const prefersReducedMotion =
+      window.matchMedia?.('(prefers-reduced-motion: reduce)')?.matches ?? false;
+    if (typeof navigator !== 'undefined' && JSDOM_USER_AGENT_RE.test(navigator.userAgent)) {
+      finish();
+      return;
+    }
+
+    const canvas = canvasRef.current;
+    if (!canvas) {
+      finish();
+      return;
+    }
+    const bounds = canvas.getBoundingClientRect();
+    if (bounds.width === 0 && bounds.height === 0) {
+      finish();
+      return;
+    }
+    const context = canvas.getContext('2d');
+    if (!context) {
+      finish();
+      return;
+    }
+
+    const pixelRatio = Math.min(window.devicePixelRatio || 1, 2);
+    const width = Math.max(bounds.width, 1);
+    const height = Math.max(bounds.height, 1);
+    canvas.width = Math.floor(width * pixelRatio);
+    canvas.height = Math.floor(height * pixelRatio);
+    context.scale(pixelRatio, pixelRatio);
+
+    const styles = getComputedStyle(canvas);
+    const colors = [
+      styles.getPropertyValue('--color-background-accent-blue-base').trim(),
+      styles.getPropertyValue('--color-background-accent-purple-base').trim(),
+      styles.getPropertyValue('--color-background-accent-success-base').trim(),
+      styles.getPropertyValue('--color-background-accent-warning-base').trim(),
+    ].filter(Boolean);
+    if (colors.length === 0) {
+      finish();
+      return;
+    }
+    const particles = createConfettiParticles(
+      width,
+      height,
+      colors,
+      prefersReducedMotion ? CONFETTI_RANDOM_SEED : undefined,
+    );
+    let frame = 0;
+    const startedAt = performance.now();
+
+    const draw = (now: number, advance = true) => {
+      const elapsed = now - startedAt;
+      context.clearRect(0, 0, width, height);
+      context.globalAlpha = Math.max(0, 1 - elapsed / CONFETTI_DURATION_MS);
+      for (const particle of particles) {
+        if (advance) {
+          particle.vy += 0.025;
+          particle.vx *= 0.985;
+          particle.x += particle.vx;
+          particle.y += particle.vy;
+          particle.rotation += 0.1;
+        }
+        context.save();
+        context.translate(particle.x, particle.y);
+        context.rotate(particle.rotation);
+        context.fillStyle = particle.color;
+        context.fillRect(
+          -particle.size / 2,
+          -particle.size / 2,
+          particle.size,
+          particle.size * 0.6,
+        );
+        context.restore();
+      }
+      context.globalAlpha = 1;
+      if (!advance) return;
+      if (elapsed < CONFETTI_DURATION_MS) {
+        frame = requestAnimationFrame(draw);
+      } else {
+        finish();
+      }
+    };
+
+    if (prefersReducedMotion) {
+      draw(startedAt, false);
+      finish();
+      // Keep the static frame after hosts consume the burst immediately.
+      return;
+    }
+
+    frame = requestAnimationFrame(draw);
+    return () => {
+      cancelAnimationFrame(frame);
+      context.clearRect(0, 0, width, height);
+    };
+  }, [active, onComplete]);
+
+  return (
+    <div aria-hidden="true" className="pointer-events-none absolute inset-0 size-full">
+      <canvas ref={canvasRef} className="size-full" />
+    </div>
+  );
+}

package/src/components/setup-checklist-confetti.test.ts

@@ -0,0 +1,19 @@
+import {describe, expect, test} from '@shipfox/vitest/vi';
+import {CONFETTI_PARTICLE_COUNT, createConfettiParticles} from './setup-checklist-confetti.js';
+
+describe('createConfettiParticles', () => {
+  test('creates a deterministic particle layout within the burst bounds', () => {
+    const palette = ['blue', 'purple', 'success', 'warning'];
+    const seed = 0x5f3759df;
+
+    const first = createConfettiParticles(480, 88, palette, seed);
+    const second = createConfettiParticles(480, 88, palette, seed);
+    const xPositions = first.map(({x}) => x);
+
+    expect(first).toEqual(second);
+    expect(first).toHaveLength(CONFETTI_PARTICLE_COUNT);
+    expect(Math.min(...xPositions)).toBeGreaterThanOrEqual(480 * 0.225);
+    expect(Math.max(...xPositions)).toBeLessThanOrEqual(480 * 0.775);
+    expect(new Set(xPositions).size).toBeGreaterThan(1);
+  });
+});

package/src/components/setup-checklist-confetti.ts

@@ -0,0 +1,39 @@
+export const CONFETTI_PARTICLE_COUNT = 48;
+
+interface ConfettiParticle {
+  x: number;
+  y: number;
+  vx: number;
+  vy: number;
+  rotation: number;
+  size: number;
+  color: string;
+}
+
+export function createConfettiParticles(
+  width: number,
+  height: number,
+  palette: readonly string[],
+  seed?: number,
+): ConfettiParticle[] {
+  const random = seed === undefined ? Math.random : createSeededRandom(seed);
+
+  return Array.from({length: CONFETTI_PARTICLE_COUNT}, (_, index) => ({
+    x: width / 2 + (random() - 0.5) * width * 0.55,
+    y: height * (0.4 + random() * 0.15),
+    vx: (random() - 0.5) * 2.5,
+    vy: -(random() * 0.7 + 0.4),
+    rotation: random() * Math.PI,
+    size: random() * 5 + 5,
+    color: palette[index % palette.length] ?? palette[0] ?? '',
+  }));
+}
+
+function createSeededRandom(seed: number): () => number {
+  let state = seed >>> 0;
+
+  return () => {
+    state = (Math.imul(state, 1_664_525) + 1_013_904_223) >>> 0;
+    return state / 2 ** 32;
+  };
+}

package/src/components/setup-checklist-host-primitives.tsx

@@ -0,0 +1,65 @@
+import {Button, IconButton} from '@shipfox/react-ui/button';
+import {PanelActions, PanelHeader, PanelTitle} from '@shipfox/react-ui/panel';
+import {Skeleton} from '@shipfox/react-ui/skeleton';
+import {Text} from '@shipfox/react-ui/typography';
+import type {SetupChecklist} from '#core/setup-checklist.js';
+
+export function ChecklistDismissAction({onDismiss}: {onDismiss: () => void}) {
+  return (
+    <div className="flex justify-end border-t border-border-neutral-base px-row py-row">
+      <Button type="button" size="sm" variant="transparentMuted" onClick={onDismiss}>
+        Hide setup guide
+      </Button>
+    </div>
+  );
+}
+
+export function ChecklistHeader({
+  count,
+  onDismiss,
+}: {
+  count?: string | undefined;
+  onDismiss: () => void;
+}) {
+  return (
+    <PanelHeader>
+      <div className="flex min-w-0 items-center gap-group">
+        <PanelTitle>Get started</PanelTitle>
+        {count ? (
+          <Text as="span" size="sm" className="shrink-0 text-foreground-neutral-muted">
+            {count}
+          </Text>
+        ) : null}
+      </div>
+      <PanelActions>
+        <IconButton
+          type="button"
+          variant="transparent"
+          size="sm"
+          muted
+          icon="close"
+          aria-label="Hide setup guide"
+          onClick={onDismiss}
+        />
+      </PanelActions>
+    </PanelHeader>
+  );
+}
+
+export function ChecklistSkeleton() {
+  return (
+    <div
+      role="status"
+      aria-label="Loading setup guide"
+      className="flex flex-col gap-inline p-panel"
+    >
+      <Skeleton className="h-16 w-3/4" />
+      <Skeleton className="h-16 w-5/6" />
+      <Skeleton className="h-16 w-2/3" />
+    </div>
+  );
+}
+
+export function checklistCountLabel(checklist: SetupChecklist) {
+  return `${checklist.trackedCount - checklist.openCount} of ${checklist.trackedCount} done`;
+}

package/src/components/setup-checklist-row.tsx

@@ -0,0 +1,189 @@
+import {ButtonLink} from '@shipfox/react-ui/button';
+import {Icon} from '@shipfox/react-ui/icon';
+import {Text} from '@shipfox/react-ui/typography';
+import {cn} from '@shipfox/react-ui/utils';
+import {Link} from '@tanstack/react-router';
+import type {SetupChecklistItem} from '#core/setup-checklist.js';
+
+const GETTING_STARTED_URL = 'https://www.shipfox.io/docs/getting-started';
+
+export function ChecklistRow({
+  item,
+  workspaceSlug,
+  onAction,
+}: {
+  item: SetupChecklistItem;
+  workspaceSlug: string;
+  onAction?: ((item: SetupChecklistItem) => void) | undefined;
+}) {
+  const pointer = !item.tracked;
+  const showDetails = pointer || item.status === 'open';
+  const statusLabel =
+    item.status === 'done'
+      ? 'done'
+      : pointer
+        ? 'next step'
+        : item.attention
+          ? 'needs attention'
+          : 'to do';
+
+  return (
+    <li className="flex min-w-0 items-start gap-group border-b border-border-neutral-base px-row py-row last:border-b-0">
+      <ChecklistStatus item={item} pointer={pointer} label={statusLabel} />
+      <div className="min-w-0 flex-1">
+        <Text
+          as="span"
+          size="sm"
+          className={cn(
+            'block',
+            item.status === 'done' && !pointer
+              ? 'text-foreground-neutral-muted'
+              : 'text-foreground-neutral-base',
+          )}
+        >
+          {item.title}
+        </Text>
+        {showDetails && item.purpose ? (
+          <Text as="span" size="xs" className="mt-tight block text-foreground-neutral-muted">
+            {item.purpose}
+          </Text>
+        ) : null}
+        {showDetails && item.action ? (
+          <div className="mt-inline">
+            <ChecklistActionLink
+              item={item}
+              action={item.action}
+              pointer={pointer}
+              workspaceSlug={workspaceSlug}
+              onAction={onAction}
+            />
+          </div>
+        ) : null}
+      </div>
+    </li>
+  );
+}
+
+function ChecklistStatus({
+  item,
+  pointer,
+  label,
+}: {
+  item: SetupChecklistItem;
+  pointer: boolean;
+  label: string;
+}) {
+  if (pointer) {
+    return (
+      <span className="mt-1 shrink-0">
+        <Icon
+          name={item.status === 'done' ? 'checkCircleSolid' : 'circleDottedLine'}
+          className={cn(
+            'size-16',
+            item.status === 'done'
+              ? 'text-foreground-highlight-interactive'
+              : 'text-foreground-neutral-subtle',
+          )}
+          aria-hidden="true"
+        />
+        <span className="sr-only">{label}</span>
+      </span>
+    );
+  }
+
+  if (item.status === 'done') {
+    return (
+      <span className="mt-1 shrink-0">
+        <Icon
+          name="checkCircleSolid"
+          className="size-16 text-foreground-highlight-interactive"
+          aria-hidden="true"
+        />
+        <span className="sr-only">{label}</span>
+      </span>
+    );
+  }
+
+  return (
+    <span className="mt-1 shrink-0">
+      <span
+        aria-hidden="true"
+        className="block size-16 rounded-full border-2 border-foreground-neutral-subtle"
+      />
+      <span className="sr-only">{label}</span>
+    </span>
+  );
+}
+
+function ChecklistActionLink({
+  item,
+  action,
+  pointer,
+  workspaceSlug,
+  onAction,
+}: {
+  item: SetupChecklistItem;
+  action: NonNullable<SetupChecklistItem['action']>;
+  pointer: boolean;
+  workspaceSlug: string;
+  onAction?: ((item: SetupChecklistItem) => void) | undefined;
+}) {
+  const handleClick = () => onAction?.(item);
+  const variant = pointer ? 'muted' : 'interactive';
+
+  if (action.href === '/docs/getting-started') {
+    return (
+      <ButtonLink asChild variant={variant} underline iconRight="chevronRight">
+        <a href={GETTING_STARTED_URL} onClick={handleClick}>
+          {action.label}
+        </a>
+      </ButtonLink>
+    );
+  }
+
+  if (action.href === '/settings/integrations') {
+    return (
+      <ButtonLink asChild variant={variant} underline iconRight="chevronRight">
+        <Link
+          to="/w/$workspaceSlug/settings/integrations"
+          params={{workspaceSlug}}
+          onClick={handleClick}
+        >
+          {action.label}
+        </Link>
+      </ButtonLink>
+    );
+  }
+
+  if (action.href === '/settings/runners') {
+    return (
+      <ButtonLink asChild variant={variant} underline iconRight="chevronRight">
+        <Link
+          to="/w/$workspaceSlug/settings/runners"
+          params={{workspaceSlug}}
+          onClick={handleClick}
+        >
+          {action.label}
+        </Link>
+      </ButtonLink>
+    );
+  }
+
+  if (action.href === '/settings/agents') {
+    return (
+      <ButtonLink asChild variant={variant} underline iconRight="chevronRight">
+        <Link to="/w/$workspaceSlug/settings/agents" params={{workspaceSlug}} onClick={handleClick}>
+          {action.label}
+        </Link>
+      </ButtonLink>
+    );
+  }
+
+  return (
+    <ButtonLink asChild variant={variant} underline iconRight="chevronRight">
+      <Link to="/w/$workspaceSlug/settings/members" params={{workspaceSlug}} onClick={handleClick}>
+        {action.label}
+      </Link>
+    </ButtonLink>
+  );
+}

package/src/components/setup-checklist-types.ts

@@ -0,0 +1,21 @@
+import type {SetupChecklist, SetupChecklistItem} from '#core/setup-checklist.js';
+
+export interface WorkspaceReference {
+  id: string;
+  slug: string;
+}
+
+export interface WorkspaceSetupHostProps {
+  /** A stable workspace makes the hosts easy to compose in isolated surfaces and stories. */
+  workspace?: WorkspaceReference;
+}
+
+export interface SetupChecklistBodyProps {
+  checklist: SetupChecklist;
+  workspaceSlug: string;
+  completion?: boolean;
+  showBurst?: boolean;
+  onBurstComplete?: () => void;
+  onAction?: ((item: SetupChecklistItem) => void) | undefined;
+  onDone?: () => void;
+}