@shipfox/client-onboarding 24.0.0 → 25.0.0

package/src/components/workspace-setup-indicator.tsx

@@ -0,0 +1,126 @@
+import {useClientAnalytics, useMaybeActiveWorkspace} from '@shipfox/client-shell/runtime';
+import {Button} from '@shipfox/react-ui/button';
+import {Icon} from '@shipfox/react-ui/icon';
+import {Panel, PanelBody} from '@shipfox/react-ui/panel';
+import {Popover, PopoverContent, PopoverTrigger} from '@shipfox/react-ui/popover';
+import {cn} from '@shipfox/react-ui/utils';
+import {useCallback, useId, useState} from 'react';
+import type {SetupChecklistItem} from '#core/setup-checklist.js';
+import {useSetupChecklistQueryState} from '#hooks/api/setup-checklist.js';
+import {useCompletionTransition, useShownAnalytics} from '#hooks/use-checklist-analytics.js';
+import {useChecklistDismissal} from '#hooks/use-checklist-dismissal.js';
+import {SetupChecklistBody} from './setup-checklist-body.js';
+import {ChecklistDismissAction, checklistCountLabel} from './setup-checklist-host-primitives.js';
+import type {WorkspaceReference, WorkspaceSetupHostProps} from './setup-checklist-types.js';
+
+export function WorkspaceSetupIndicator(props: WorkspaceSetupHostProps = {}) {
+  if (props.workspace) {
+    return (
+      <WorkspaceSetupIndicatorForWorkspace key={props.workspace.id} workspace={props.workspace} />
+    );
+  }
+
+  return <WorkspaceSetupIndicatorFromShell />;
+}
+
+function WorkspaceSetupIndicatorFromShell() {
+  const workspace = useMaybeActiveWorkspace();
+  return workspace ? (
+    <WorkspaceSetupIndicatorForWorkspace key={workspace.id} workspace={workspace} />
+  ) : null;
+}
+
+function WorkspaceSetupIndicatorForWorkspace({workspace}: {workspace: WorkspaceReference}) {
+  const dismissal = useChecklistDismissal(workspace.id);
+  const queryState = useSetupChecklistQueryState(workspace.id, !dismissal.dismissed);
+  const analytics = useClientAnalytics();
+  const [open, setOpen] = useState(false);
+  const [pulseKey, setPulseKey] = useState(0);
+  const [burstPending, setBurstPending] = useState(false);
+  const handleCompleted = useCallback(
+    (completed: boolean) => {
+      if (!completed) return;
+      setBurstPending(true);
+      if (!open) setPulseKey((key) => key + 1);
+    },
+    [open],
+  );
+  const showCompletion = useCompletionTransition(queryState, 'popover', handleCompleted);
+  const consumeBurst = useCallback(() => setBurstPending(false), []);
+  const triggerId = useId();
+
+  const dismiss = useCallback(() => {
+    dismissal.dismiss();
+    setOpen(false);
+    analytics.capture('onboarding_checklist_dismissed', {host: 'popover'});
+  }, [analytics, dismissal]);
+  const handleAction = useCallback(
+    (item: SetupChecklistItem) => {
+      analytics.capture('onboarding_checklist_row_clicked', {row_id: item.id});
+      setOpen(false);
+    },
+    [analytics],
+  );
+
+  const indicatorReady = queryState.completionReady || queryState.checklist.openCount > 0;
+  const isVisible =
+    !dismissal.dismissed &&
+    queryState.baseSettled &&
+    indicatorReady &&
+    (!queryState.checklist.complete || showCompletion);
+  useShownAnalytics('popover', isVisible);
+
+  if (dismissal.dismissed || !queryState.baseSettled || !indicatorReady) return null;
+  if (queryState.checklist.complete && !showCompletion) return null;
+
+  const countLabel = checklistCountLabel(queryState.checklist);
+  const ariaLabel = `Get started, ${countLabel}`;
+
+  return (
+    <Popover modal={false} open={open} onOpenChange={setOpen}>
+      <PopoverTrigger asChild>
+        <Button
+          type="button"
+          variant="transparent"
+          size="sm"
+          id={triggerId}
+          aria-label={ariaLabel}
+          className="gap-inline"
+        >
+          <span
+            key={pulseKey}
+            className={cn(
+              'inline-flex items-center',
+              pulseKey > 0 && 'motion-safe:animate-[pulse_1s_ease-in-out_1]',
+            )}
+          >
+            <Icon name="circleDottedLine" size={16} aria-hidden="true" />
+          </span>
+          <span>Get started · {countLabel}</span>
+        </Button>
+      </PopoverTrigger>
+      <PopoverContent
+        align="end"
+        className="w-[360px] max-w-[calc(100vw-32px)] p-0"
+        aria-labelledby={triggerId}
+      >
+        <Panel asChild>
+          <section aria-label="Get started">
+            <PanelBody>
+              <SetupChecklistBody
+                checklist={queryState.checklist}
+                workspaceSlug={workspace.slug}
+                completion={showCompletion}
+                showBurst={burstPending}
+                onBurstComplete={consumeBurst}
+                onAction={handleAction}
+                onDone={dismiss}
+              />
+            </PanelBody>
+            <ChecklistDismissAction onDismiss={dismiss} />
+          </section>
+        </Panel>
+      </PopoverContent>
+    </Popover>
+  );
+}

package/src/core/setup-checklist.test.ts

@@ -277,6 +277,7 @@ describe('deriveSetupChecklist', () => {
     expect(checklist.items.find((item) => item.id === 'tools')).toMatchObject({
       status: 'done',
       title: 'Connect your tools',
+      attention: false,
     });
   });
 
@@ -284,8 +285,7 @@ describe('deriveSetupChecklist', () => {
     const checklist = deriveSetupChecklist(input());
 
     expect(checklist.items.find((item) => item.id === 'tools')).toMatchObject({
-      purpose:
-        'Connect issue tracking, messaging, observability, or any Shipfox integration so workflows can react to events and agents can use them',
+      purpose: 'Connect issue tracking, messaging, observability, or any Shipfox integration',
       action: {href: '/settings/integrations'},
     });
   });

package/src/core/setup-checklist.ts

@@ -22,6 +22,8 @@ export interface SetupChecklistItem {
   status: SetupChecklistItemStatus;
   /** Tracked items count toward completion; pointers never do. */
   tracked: boolean;
+  /** The row's underlying integration has a connection that needs attention. */
+  attention?: boolean;
   /** One line of purpose, rendered for open and pointer rows. */
   purpose?: string;
   /** Primary action, a link to the settings page where the work happens. */
@@ -49,7 +51,7 @@ export interface SetupChecklistInput {
 
 const TOOLS_TITLE = 'Connect your tools';
 const TOOLS_PURPOSE =
-  'Connect issue tracking, messaging, observability, or any Shipfox integration so workflows can react to events and agents can use them';
+  'Connect issue tracking, messaging, observability, or any Shipfox integration';
 const RUNNER_PURPOSE = 'Jobs wait in `pending` until a runner is online';
 const MODEL_PROVIDER_PURPOSE = 'Agent steps need a model provider to run';
 const FIRST_WORKFLOW_PURPOSE =
@@ -69,6 +71,8 @@ export function deriveSetupChecklist({
   modelProvider,
   membership,
 }: SetupChecklistInput): SetupChecklist {
+  const toolsAttention =
+    !readiness.hasToolIntegration && attentionToolProviders(readiness).length > 0;
   const items: SetupChecklistItem[] = [
     {id: 'source-control', title: 'Connect source control', status: 'done', tracked: true},
     {id: 'project', title: 'Create a project', status: 'done', tracked: true},
@@ -77,6 +81,7 @@ export function deriveSetupChecklist({
       title: toolsTitle(readiness),
       status: readiness.hasToolIntegration ? 'done' : 'open',
       tracked: true,
+      attention: toolsAttention,
       purpose: TOOLS_PURPOSE,
       action: {label: 'Connect', href: '/settings/integrations'},
     },
@@ -137,20 +142,24 @@ export function deriveSetupChecklist({
 
 function toolsTitle(readiness: WorkspaceIntegrationReadiness): string {
   if (!readiness.hasToolIntegration) {
-    const attentionToolProviders = readiness.attentionProviders
-      .map((providerKey) => readiness.providers.find(({provider}) => provider === providerKey))
-      .filter(
-        (provider) => provider !== undefined && !provider.capabilities.includes('source_control'),
-      );
-    if (attentionToolProviders.length === 1) {
-      const provider = attentionToolProviders[0];
+    const providers = attentionToolProviders(readiness);
+    if (providers.length === 1) {
+      const provider = providers[0];
       if (provider !== undefined) {
         return `${provider.displayName || provider.provider} needs attention`;
       }
     }
-    if (attentionToolProviders.length > 1) {
-      return `${attentionToolProviders.length} integrations need attention`;
+    if (providers.length > 1) {
+      return `${providers.length} integrations need attention`;
     }
   }
   return TOOLS_TITLE;
 }
+
+function attentionToolProviders(readiness: WorkspaceIntegrationReadiness) {
+  return readiness.attentionProviders
+    .map((providerKey) => readiness.providers.find(({provider}) => provider === providerKey))
+    .filter(
+      (provider) => provider !== undefined && !provider.capabilities.includes('source_control'),
+    );
+}

package/src/feature.ts

@@ -0,0 +1,16 @@
+import {defineClientFeature} from '@shipfox/client-shell';
+import {lazy} from 'react';
+
+export const onboardingFeature = defineClientFeature({
+  id: 'shipfox.onboarding',
+});
+
+export const WorkspaceSetupChecklist = lazy(async () => {
+  const module = await import('./components/setup-checklist.js');
+  return {default: module.WorkspaceSetupChecklist};
+});
+
+export const WorkspaceSetupIndicator = lazy(async () => {
+  const module = await import('./components/setup-checklist.js');
+  return {default: module.WorkspaceSetupIndicator};
+});

package/src/hooks/api/setup-checklist.ts

@@ -0,0 +1,144 @@
+import {
+  modelProviderCatalogQueryOptions,
+  modelProviderConfigsQueryOptions,
+} from '@shipfox/client-agent';
+import {
+  integrationConnectionsQueryOptions,
+  integrationProvidersQueryOptions,
+} from '@shipfox/client-integrations';
+import {
+  activeProvisionersQueryOptions,
+  installationRunnersStatusQueryOptions,
+} from '@shipfox/client-runners';
+import {
+  listInvitationsQueryOptions,
+  listMembersQueryOptions,
+} from '@shipfox/client-workspace-settings';
+import {useQuery} from '@tanstack/react-query';
+import {deriveIntegrationReadiness} from '#core/integration-readiness.js';
+import {
+  deriveSetupChecklist,
+  type SetupChecklist,
+  type SetupChecklistItemId,
+} from '#core/setup-checklist.js';
+
+const CHECKLIST_STALE_TIME_MS = 5 * 60 * 1000;
+
+export interface ChecklistQueryState {
+  checklist: SetupChecklist;
+  baseSettled: boolean;
+  completionReady: boolean;
+}
+
+/**
+ * Composes the server state needed by both checklist hosts. Keeping this hook
+ * in the API adapter boundary gives each query family one shared cache policy
+ * while allowing dismissed hosts to remain unsubscribed.
+ */
+export function useSetupChecklistQueryState(
+  workspaceId: string,
+  subscribed: boolean,
+): ChecklistQueryState {
+  const queryEnabled = subscribed && Boolean(workspaceId);
+  const queryPolicy = {
+    enabled: queryEnabled,
+    subscribed: queryEnabled,
+    refetchInterval: false,
+    retry: false,
+    staleTime: CHECKLIST_STALE_TIME_MS,
+    refetchOnWindowFocus: false,
+  } as const;
+
+  const providersQuery = useQuery({
+    ...integrationProvidersQueryOptions(),
+    ...queryPolicy,
+  });
+  const connectionsQuery = useQuery({
+    ...integrationConnectionsQueryOptions(workspaceId),
+    ...queryPolicy,
+  });
+  const activeProvisionersQuery = useQuery({
+    ...activeProvisionersQueryOptions(workspaceId),
+    ...queryPolicy,
+  });
+  const runnersStatusQuery = useQuery({
+    ...installationRunnersStatusQueryOptions(workspaceId),
+    ...queryPolicy,
+  });
+  const catalogQuery = useQuery({
+    ...modelProviderCatalogQueryOptions(),
+    ...queryPolicy,
+  });
+  const configsQuery = useQuery({
+    ...modelProviderConfigsQueryOptions(workspaceId),
+    ...queryPolicy,
+  });
+  const membersQuery = useQuery({
+    ...listMembersQueryOptions(workspaceId),
+    ...queryPolicy,
+  });
+  const invitationsQuery = useQuery({
+    ...listInvitationsQueryOptions(workspaceId),
+    ...queryPolicy,
+  });
+
+  const baseSettled = isSettled(providersQuery) && isSettled(connectionsQuery);
+  const runnerSettled = isSettled(activeProvisionersQuery) && isSettled(runnersStatusQuery);
+  const runnerReady = activeProvisionersQuery.isSuccess && runnersStatusQuery.isSuccess;
+  const catalogInstallationProvided =
+    catalogQuery.data !== undefined &&
+    (catalogQuery.data.managedProviderId !== null ||
+      catalogQuery.data.instanceDefaultProviderId !== null);
+  const modelReady = catalogQuery.isSuccess && configsQuery.isSuccess;
+  const membersReady = membersQuery.isSuccess && invitationsQuery.isSuccess;
+  const modelSettled = isSettled(catalogQuery) && isSettled(configsQuery);
+  const membersSettled = isSettled(membersQuery) && isSettled(invitationsQuery);
+  const completionReady =
+    providersQuery.isSuccess &&
+    connectionsQuery.isSuccess &&
+    runnerSettled &&
+    modelSettled &&
+    membersSettled;
+
+  const rawChecklist = deriveSetupChecklist({
+    readiness: deriveIntegrationReadiness({
+      providers: providersQuery.data ?? [],
+      connections: connectionsQuery.data ?? [],
+    }),
+    installationRunners: runnersStatusQuery.data ?? 'managed',
+    workspaceRunnerCapacity: (activeProvisionersQuery.data?.length ?? 0) > 0,
+    modelProvider: {
+      installationProvided: catalogQuery.isSuccess ? catalogInstallationProvided : true,
+      configured: (configsQuery.data?.configs.length ?? 0) > 0,
+    },
+    membership: {
+      memberCount: membersQuery.data?.length ?? 0,
+      pendingInvitationCount: invitationsQuery.data?.length ?? 0,
+    },
+  });
+
+  const hiddenRows = new Set<SetupChecklistItemId>();
+  if (!providersQuery.isSuccess || !connectionsQuery.isSuccess) hiddenRows.add('tools');
+  if (!runnerReady) hiddenRows.add('runner');
+  if (!modelReady) hiddenRows.add('model-provider');
+  if (!membersReady) hiddenRows.add('teammates');
+
+  const items = rawChecklist.items.filter((item) => !hiddenRows.has(item.id));
+  const trackedItems = items.filter((item) => item.tracked);
+  const openCount = trackedItems.filter((item) => item.status === 'open').length;
+
+  return {
+    baseSettled,
+    completionReady,
+    checklist: {
+      items,
+      openCount,
+      trackedCount: trackedItems.length,
+      complete: completionReady && openCount === 0,
+    },
+  };
+}
+
+function isSettled(query: {isError: boolean; isSuccess: boolean}) {
+  return query.isSuccess || query.isError;
+}

package/src/hooks/use-checklist-analytics.ts

@@ -0,0 +1,60 @@
+import {useClientAnalytics} from '@shipfox/client-shell/runtime';
+import {useEffect, useRef, useState} from 'react';
+import type {ChecklistQueryState} from '#hooks/api/setup-checklist.js';
+
+type ChecklistHost = 'panel' | 'popover';
+
+export function useCompletionTransition(
+  queryState: ChecklistQueryState,
+  host: ChecklistHost,
+  onCompleted?: (completed: boolean) => void,
+) {
+  const analytics = useClientAnalytics();
+  const observedIncomplete = useRef(false);
+  const completionHandled = useRef(false);
+  const [showCompletion, setShowCompletion] = useState(false);
+
+  useEffect(() => {
+    if (
+      queryState.baseSettled &&
+      !queryState.checklist.complete &&
+      queryState.checklist.openCount > 0
+    ) {
+      observedIncomplete.current = true;
+    }
+
+    if (!queryState.completionReady) return;
+
+    if (!queryState.checklist.complete) {
+      setShowCompletion(false);
+      return;
+    }
+
+    if (!observedIncomplete.current || completionHandled.current) return;
+    completionHandled.current = true;
+    setShowCompletion(true);
+    onCompleted?.(true);
+    analytics.capture('onboarding_checklist_completed', {host});
+  }, [
+    analytics,
+    host,
+    onCompleted,
+    queryState.baseSettled,
+    queryState.checklist.complete,
+    queryState.checklist.openCount,
+    queryState.completionReady,
+  ]);
+
+  return showCompletion;
+}
+
+export function useShownAnalytics(host: ChecklistHost, visible: boolean) {
+  const analytics = useClientAnalytics();
+  const shown = useRef(false);
+
+  useEffect(() => {
+    if (!visible || shown.current) return;
+    shown.current = true;
+    analytics.capture('onboarding_checklist_shown', {host});
+  }, [analytics, host, visible]);
+}

package/src/hooks/use-checklist-dismissal.ts

@@ -0,0 +1,30 @@
+import {
+  dismissWorkspaceSetupChecklist,
+  isWorkspaceSetupChecklistDismissed,
+  WORKSPACE_SETUP_CHECKLIST_DISMISSAL_EVENT,
+} from '@shipfox/client-shell/runtime';
+import {useCallback, useEffect, useState} from 'react';
+
+export function useChecklistDismissal(workspaceId: string) {
+  const [dismissed, setDismissed] = useState(() => isWorkspaceSetupChecklistDismissed(workspaceId));
+
+  useEffect(() => {
+    const refresh = () => setDismissed(isWorkspaceSetupChecklistDismissed(workspaceId));
+    refresh();
+    window.addEventListener('storage', refresh);
+    window.addEventListener('focus', refresh);
+    window.addEventListener(WORKSPACE_SETUP_CHECKLIST_DISMISSAL_EVENT, refresh);
+    return () => {
+      window.removeEventListener('storage', refresh);
+      window.removeEventListener('focus', refresh);
+      window.removeEventListener(WORKSPACE_SETUP_CHECKLIST_DISMISSAL_EVENT, refresh);
+    };
+  }, [workspaceId]);
+
+  const dismiss = useCallback(() => {
+    dismissWorkspaceSetupChecklist(workspaceId);
+    setDismissed(true);
+  }, [workspaceId]);
+
+  return {dismissed, dismiss};
+}

package/src/index.ts

@@ -13,6 +13,14 @@ export {
   type SetupChecklistItemId,
   type SetupChecklistItemStatus,
 } from '#core/setup-checklist.js';
+export {
+  SetupChecklistBody,
+  type SetupChecklistBodyProps,
+  type WorkspaceReference,
+  WorkspaceSetupChecklist,
+  type WorkspaceSetupHostProps,
+  WorkspaceSetupIndicator,
+} from './components/setup-checklist.js';
 export {
   loadWorkspaceSetupRoute,
   type WorkspaceSetupRouteOptions,