@shipfox/client-workflows 0.2.0

package/src/components/workflow-status/status-visuals.test.ts

@@ -0,0 +1,38 @@
+import {
+  type JobStatusDto,
+  jobStatusSchema,
+  type WorkflowRunStatusDto,
+  workflowRunStatusSchema,
+} from '@shipfox/api-workflows-dto';
+import {getWorkflowStatusVisual} from './status-visuals.js';
+
+const EXPECTED_RUN_LABELS: Record<WorkflowRunStatusDto, string> = {
+  pending: 'Pending',
+  running: 'Running',
+  succeeded: 'Succeeded',
+  failed: 'Failed',
+  cancelled: 'Cancelled',
+};
+
+const EXPECTED_JOB_LABELS: Record<JobStatusDto, string> = {
+  ...EXPECTED_RUN_LABELS,
+  skipped: 'Skipped',
+};
+
+describe('getWorkflowStatusVisual', () => {
+  test.each(
+    workflowRunStatusSchema.options,
+  )('maps the run %s status to its own label', (status) => {
+    expect(getWorkflowStatusVisual(status).label).toBe(EXPECTED_RUN_LABELS[status]);
+  });
+
+  test.each(jobStatusSchema.options)('maps the job %s status to its own label', (status) => {
+    expect(getWorkflowStatusVisual(status).label).toBe(EXPECTED_JOB_LABELS[status]);
+  });
+
+  test('returns the shared running visual', () => {
+    const visual = getWorkflowStatusVisual('running');
+
+    expect(visual).toEqual({kind: 'running', label: 'Running', dot: 'info', badge: 'info'});
+  });
+});

package/src/components/workflow-status/status-visuals.ts

@@ -0,0 +1,36 @@
+import type {BadgeVariant} from '@shipfox/react-ui/badge';
+import type {DotVariant} from '@shipfox/react-ui/dot';
+import type {WorkflowStatus} from '#core/workflow-run.js';
+
+export type {WorkflowStatus};
+
+export interface WorkflowStatusVisual {
+  kind: WorkflowStatus;
+  label: string;
+  dot: DotVariant;
+  badge: BadgeVariant;
+}
+
+// The status -> visual mapping shared by the run-header pill (color + label) and
+// WorkflowStatusIcon (which renders the glyph per kind). The exhaustive switch turns any new
+// status the API grows into (DESIGN.md section 9) into a compile error; reserve the `warning`
+// tone for the queued/awaiting-* states when they land.
+export function getWorkflowStatusVisual(status: WorkflowStatus): WorkflowStatusVisual {
+  switch (status) {
+    case 'pending':
+      return {kind: 'pending', label: 'Pending', dot: 'neutral', badge: 'neutral'};
+    case 'running':
+      return {kind: 'running', label: 'Running', dot: 'info', badge: 'info'};
+    case 'succeeded':
+      return {kind: 'succeeded', label: 'Succeeded', dot: 'success', badge: 'success'};
+    case 'failed':
+      return {kind: 'failed', label: 'Failed', dot: 'error', badge: 'error'};
+    case 'cancelled':
+      return {kind: 'cancelled', label: 'Cancelled', dot: 'neutral', badge: 'neutral'};
+    case 'skipped':
+      return {kind: 'skipped', label: 'Skipped', dot: 'neutral', badge: 'neutral'};
+  }
+
+  const exhaustive: never = status;
+  return exhaustive;
+}

package/src/components/workflow-status/workflow-status-icon.stories.tsx

@@ -0,0 +1,90 @@
+import {Code, Text} from '@shipfox/react-ui/typography';
+import type {Meta, StoryObj} from '@storybook/react';
+import type {JobStatus} from '#core/workflow-run.js';
+import {getWorkflowStatusVisual} from './status-visuals.js';
+import {WorkflowStatusIcon} from './workflow-status-icon.js';
+
+const statuses: JobStatus[] = ['pending', 'running', 'succeeded', 'failed', 'cancelled', 'skipped'];
+
+const meta = {
+  title: 'Workflows/StatusIcon',
+  component: WorkflowStatusIcon,
+  parameters: {layout: 'centered'},
+  argTypes: {
+    status: {
+      control: 'select',
+      options: statuses,
+    },
+    size: {
+      control: {type: 'number', min: 8, max: 24, step: 1},
+    },
+    ripple: {
+      control: 'boolean',
+    },
+  },
+  args: {
+    status: 'running',
+    size: 14,
+    ripple: false,
+  },
+  decorators: [
+    (Story) => (
+      <div className="bg-background-neutral-base p-24">
+        <Story />
+      </div>
+    ),
+  ],
+} satisfies Meta<typeof WorkflowStatusIcon>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// Every state at the surface size (14px) plus a compact size, sharing the tuned glyph scale.
+export const Playground: Story = {};
+
+export const Variants: Story = {
+  render: () => (
+    <div className="flex flex-col gap-32">
+      <Scale label="DAG node / run row (14px)" size={14} />
+      <Scale label="Compact (12px)" size={12} />
+    </div>
+  ),
+};
+
+export const InContext: Story = {
+  render: () => (
+    <div className="grid grid-cols-2 gap-12">
+      {statuses.map((status) => (
+        <div
+          key={status}
+          className="flex w-208 items-center gap-8 rounded-8 border border-border-neutral-base bg-background-components-base px-10 py-7"
+        >
+          <WorkflowStatusIcon status={status} size={14} />
+          <Code variant="label" bold className="truncate text-foreground-neutral-base">
+            {status}-job
+          </Code>
+        </div>
+      ))}
+    </div>
+  ),
+};
+
+function Scale({label, size, ripple}: {label: string; size: number; ripple?: boolean}) {
+  return (
+    <div className="flex flex-col gap-12">
+      <Code variant="label" className="text-foreground-neutral-subtle">
+        {label}
+      </Code>
+      <div className="flex items-start gap-32">
+        {statuses.map((status) => (
+          <div key={status} className="flex flex-col items-center gap-6">
+            <WorkflowStatusIcon status={status} size={size} ripple={ripple} />
+            <Text size="xs" className="text-foreground-neutral-muted">
+              {getWorkflowStatusVisual(status).label}
+            </Text>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}

package/src/components/workflow-status/workflow-status-icon.tsx

@@ -0,0 +1,135 @@
+import {Dot, type DotVariant} from '@shipfox/react-ui/dot';
+import {Icon, type IconName} from '@shipfox/react-ui/icon';
+import {Tooltip, TooltipContent, TooltipTrigger} from '@shipfox/react-ui/tooltip';
+import {cn} from '@shipfox/react-ui/utils';
+import type {ReactNode} from 'react';
+import {getWorkflowStatusVisual, type WorkflowStatus} from './status-visuals.js';
+
+// Status glyphs use the same saturated accent tokens as IconBadge/StatusBadge.
+const toneByVariant: Record<DotVariant, string> = {
+  neutral: 'text-tag-neutral-icon',
+  info: 'text-tag-blue-icon',
+  feature: 'text-tag-purple-icon',
+  success: 'text-tag-success-icon',
+  warning: 'text-tag-warning-icon',
+  error: 'text-tag-error-icon',
+};
+
+// Terminal states are self-contained solid discs; the shape names the state. Running and
+// pending render their own shapes (the live Dot and a bold ring), so they aren't here.
+const glyphByKind: Partial<Record<WorkflowStatus, IconName>> = {
+  succeeded: 'checkCircleSolid',
+  failed: 'xCircleSolid',
+  cancelled: 'forbid2Fill',
+  skipped: 'forbid2Fill',
+};
+
+// The solid discs fill ~90-95% of their viewBox and forbid2Fill ~83%, so one numeric size
+// renders different diameters. These multipliers land every disc at the running Dot's diameter.
+const glyphScale: Partial<Record<IconName, number>> = {
+  checkCircleSolid: 1.12,
+  xCircleSolid: 1.06,
+  forbid2Fill: 1.22,
+};
+
+// Only the two sizes the app uses are mapped; both are literal strings so Tailwind emits them.
+const dotSizeClass: Record<number, string> = {
+  12: 'size-12',
+  14: 'size-14',
+  20: 'size-20',
+};
+
+// Pending is a neutral ring: a filled disc with a transparent center punched out by a radial
+// mask. Reads as "not started" and stays visually consistent with the solid discs - much
+// bolder than a dotted outline. Tune the mask stops to make the band thicker or thinner.
+const PENDING_RING_MASK = 'radial-gradient(circle closest-side, transparent 0 52%, #000 56%)';
+
+export interface WorkflowStatusIconProps {
+  status: WorkflowStatus;
+  jobMode?: 'one_shot' | 'listening';
+  /** Optical diameter in px: 14 in the DAG node and run row. */
+  size?: number;
+  /** Pulsing halo for the running state. */
+  ripple?: boolean;
+  /**
+   * Wrap the indicator in a hover tooltip naming the status. Defaults on. Pass false where
+   * the status text is already visible next to it (the DAG node) to avoid a redundant tooltip.
+   */
+  tooltip?: boolean;
+  className?: string;
+}
+
+/**
+ * The job/run/step state indicator: an icon-in-circle glyph whose shape (not just color)
+ * names the state. Carries the status as its accessible name (`role="img"`) and, by default,
+ * a hover tooltip, so the state is reachable by pointer and assistive tech everywhere.
+ */
+export function WorkflowStatusIcon({
+  status,
+  jobMode = 'one_shot',
+  size = 14,
+  ripple = true,
+  tooltip = true,
+  className,
+}: WorkflowStatusIconProps) {
+  const visual = getWorkflowStatusVisual(status);
+  const box = dotSizeClass[size] ?? 'size-14';
+
+  let glyph: ReactNode;
+  if (visual.kind === 'running') {
+    glyph =
+      jobMode === 'listening' ? (
+        <span
+          className={cn(
+            'inline-flex shrink-0 items-center justify-center rounded-full bg-current',
+            box,
+            toneByVariant.info,
+          )}
+        >
+          <Icon
+            name="pulseLine"
+            size={Math.max(8, Math.round(size * 0.7))}
+            className="text-white"
+          />
+        </span>
+      ) : (
+        <Dot variant="info" ripple={ripple} className={box} />
+      );
+  } else if (visual.kind === 'pending') {
+    glyph = (
+      <span
+        className={cn('rounded-full bg-current', box, toneByVariant.neutral)}
+        style={{maskImage: PENDING_RING_MASK, WebkitMaskImage: PENDING_RING_MASK}}
+      />
+    );
+  } else {
+    const name = glyphByKind[visual.kind] ?? 'forbid2Fill';
+    glyph = (
+      <span
+        className={cn(
+          'inline-flex shrink-0 items-center justify-center',
+          box,
+          toneByVariant[visual.dot],
+          (visual.kind === 'cancelled' || visual.kind === 'skipped') && 'opacity-70',
+        )}
+      >
+        <Icon name={name} size={Math.round(size * (glyphScale[name] ?? 1))} />
+      </span>
+    );
+  }
+
+  const indicator = (
+    <span role="img" aria-label={visual.label} className={cn('inline-flex shrink-0', className)}>
+      {glyph}
+    </span>
+  );
+
+  if (!tooltip) return indicator;
+
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>{indicator}</TooltipTrigger>
+      <TooltipContent>{visual.label}</TooltipContent>
+    </Tooltip>
+  );
+}

package/src/core/entities/job-execution.ts

@@ -0,0 +1,139 @@
+import type {
+  WorkflowExecutionEventDto,
+  WorkflowRunJobExecutionDetailDto,
+} from '@shipfox/api-workflows-dto';
+import {type Duration, intervalToDuration} from 'date-fns';
+import {type Step, toStep} from './step.js';
+
+export type JobExecutionStatus = WorkflowRunJobExecutionDetailDto['status'];
+export type JobExecutionTime =
+  | {state: 'fixed'; elapsed: Duration}
+  | {state: 'live'; fromIso: string};
+export type JobExecutionDisplayDuration =
+  | ({kind: 'queue'} & JobExecutionTime)
+  | ({kind: 'run'} & JobExecutionTime);
+
+interface JobExecutionFields {
+  id: string;
+  jobId: string;
+  sequence: number;
+  name: string;
+  status: JobExecutionStatus;
+  statusReason: string | null;
+  triggerEvents: WorkflowExecutionEventDto[];
+  queuedAt: string | null;
+  startedAt: string | null;
+  finishedAt: string | null;
+  timedOutAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+  steps: Step[];
+}
+
+export class JobExecution {
+  id!: string;
+  jobId!: string;
+  sequence!: number;
+  name!: string;
+  status!: JobExecutionStatus;
+  statusReason!: string | null;
+  triggerEvents!: WorkflowExecutionEventDto[];
+  queuedAt!: string | null;
+  startedAt!: string | null;
+  finishedAt!: string | null;
+  timedOutAt!: string | null;
+  createdAt!: string;
+  updatedAt!: string;
+  steps!: Step[];
+
+  constructor(fields: JobExecutionFields) {
+    Object.assign(this, fields);
+  }
+
+  get queueTime(): JobExecutionTime | null {
+    return jobExecutionQueueTimeFromTimestamps(this);
+  }
+
+  get runTime(): JobExecutionTime | null {
+    return jobExecutionRunTimeFromTimestamps(this);
+  }
+
+  get displayDuration(): JobExecutionDisplayDuration | null {
+    return jobExecutionDisplayDurationFromTimestamps(this);
+  }
+}
+
+export function toJobExecution(dto: WorkflowRunJobExecutionDetailDto): JobExecution {
+  return new JobExecution({
+    id: dto.id,
+    jobId: dto.job_id,
+    sequence: dto.sequence,
+    name: dto.name,
+    status: dto.status,
+    statusReason: dto.status_reason,
+    triggerEvents: dto.trigger_events ?? [],
+    queuedAt: dto.queued_at ?? null,
+    startedAt: dto.started_at ?? null,
+    finishedAt: dto.finished_at ?? null,
+    timedOutAt: dto.timed_out_at ?? null,
+    createdAt: dto.created_at,
+    updatedAt: dto.updated_at,
+    steps: dto.steps.map(toStep),
+  });
+}
+
+export function jobExecutionQueueTimeFromTimestamps({
+  queuedAt,
+  startedAt,
+  finishedAt,
+}: {
+  queuedAt: string | null;
+  startedAt: string | null;
+  finishedAt: string | null;
+}): JobExecutionTime | null {
+  if (queuedAt === null) return null;
+  if (finishedAt !== null && startedAt === null) return null;
+  if (startedAt === null) return {state: 'live', fromIso: queuedAt};
+
+  const elapsed = durationBetween(queuedAt, startedAt);
+  return elapsed === null ? null : {state: 'fixed', elapsed};
+}
+
+export function jobExecutionRunTimeFromTimestamps({
+  startedAt,
+  finishedAt,
+}: {
+  startedAt: string | null;
+  finishedAt: string | null;
+}): JobExecutionTime | null {
+  if (startedAt === null) return null;
+  if (finishedAt === null) return {state: 'live', fromIso: startedAt};
+
+  const elapsed = durationBetween(startedAt, finishedAt);
+  return elapsed === null ? null : {state: 'fixed', elapsed};
+}
+
+export function jobExecutionDisplayDurationFromTimestamps(timestamps: {
+  queuedAt: string | null;
+  startedAt: string | null;
+  finishedAt: string | null;
+}): JobExecutionDisplayDuration | null {
+  const runTime = jobExecutionRunTimeFromTimestamps(timestamps);
+  if (runTime !== null) return {kind: 'run', ...runTime};
+
+  const queueTime = jobExecutionQueueTimeFromTimestamps(timestamps);
+  if (queueTime !== null) return {kind: 'queue', ...queueTime};
+
+  return null;
+}
+
+function durationBetween(from: string, to: string): Duration | null {
+  const start = new Date(from);
+  const end = new Date(to);
+  if (!Number.isFinite(start.getTime()) || !Number.isFinite(end.getTime())) return null;
+
+  return intervalToDuration({
+    start,
+    end: end < start ? start : end,
+  });
+}

package/src/core/entities/job.ts

@@ -0,0 +1,149 @@
+import type {
+  JobListeningDto,
+  JobModeDto,
+  JobStatusDto,
+  JobStatusReasonDto,
+  ListenerStatusDto,
+  ResolutionReasonDto,
+  WorkflowRunJobDetailDto,
+} from '@shipfox/api-workflows-dto';
+import {
+  type JobExecution,
+  type JobExecutionDisplayDuration,
+  toJobExecution,
+} from './job-execution.js';
+
+export type JobStatus = JobStatusDto;
+export type JobMode = JobModeDto;
+export type ListenerStatus = ListenerStatusDto;
+export type ResolutionReason = ResolutionReasonDto;
+export type JobStatusReason = JobStatusReasonDto;
+
+export type JobDisplayDuration = JobExecutionDisplayDuration;
+
+export const WORKFLOW_JOB_STATUSES = [
+  'pending',
+  'running',
+  'succeeded',
+  'failed',
+  'cancelled',
+  'skipped',
+] as const satisfies readonly JobStatus[];
+
+export const TERMINAL_WORKFLOW_JOB_STATUSES = [
+  'succeeded',
+  'failed',
+  'cancelled',
+  'skipped',
+] as const satisfies readonly JobStatus[];
+
+const TERMINAL_JOB_STATUS_SET = new Set<JobStatus>(TERMINAL_WORKFLOW_JOB_STATUSES);
+
+interface JobFields {
+  id: string;
+  runAttemptId: string;
+  key: string;
+  name: string | null;
+  mode: JobMode;
+  status: JobStatus;
+  statusReason: JobStatusReason | null;
+  carriedOver: boolean;
+  listening: JobListeningDto | null;
+  listenerStatus: ListenerStatus;
+  resolutionReason: ResolutionReason | null;
+  dependencies: string[];
+  position: number;
+  createdAt: string;
+  updatedAt: string;
+  jobExecutions: JobExecution[];
+}
+
+export class Job {
+  id!: string;
+  runAttemptId!: string;
+  key!: string;
+  name!: string | null;
+  mode!: JobMode;
+  status!: JobStatus;
+  statusReason!: JobStatusReason | null;
+  carriedOver!: boolean;
+  listening!: JobListeningDto | null;
+  listenerStatus!: ListenerStatus;
+  resolutionReason!: ResolutionReason | null;
+  dependencies!: string[];
+  position!: number;
+  createdAt!: string;
+  updatedAt!: string;
+  jobExecutions!: JobExecution[];
+
+  constructor(fields: JobFields) {
+    Object.assign(this, fields);
+  }
+
+  get displayName(): string {
+    return this.name || this.key;
+  }
+
+  get displayDuration(): JobDisplayDuration | null {
+    if (this.mode === 'listening') return null;
+    if (this.jobExecutions.length !== 1) return null;
+    return this.jobExecutions[0]?.displayDuration ?? null;
+  }
+
+  get executionCountVisible(): boolean {
+    return (
+      this.jobExecutions.length > 0 && (this.mode === 'listening' || this.jobExecutions.length > 1)
+    );
+  }
+}
+
+export function isTerminalJobStatus(status: JobStatus): boolean {
+  return TERMINAL_JOB_STATUS_SET.has(status);
+}
+
+export function resolveJobExecution(
+  job: Job,
+  jobExecutionId: string | undefined,
+): JobExecution | undefined {
+  const selectedExecution = jobExecutionId
+    ? job.jobExecutions.find((jobExecution) => jobExecution.id === jobExecutionId)
+    : undefined;
+  if (selectedExecution) return selectedExecution;
+
+  return defaultJobExecution(job);
+}
+
+export function defaultJobExecution(job: Job): JobExecution | undefined {
+  const runningExecution = job.jobExecutions.find(
+    (jobExecution) => jobExecution.status === 'running',
+  );
+  if (runningExecution) return runningExecution;
+
+  return job.jobExecutions.reduce<JobExecution | undefined>((latest, jobExecution) => {
+    if (!latest) return jobExecution;
+    return jobExecution.sequence > latest.sequence ? jobExecution : latest;
+  }, undefined);
+}
+
+export function toJob(dto: WorkflowRunJobDetailDto): Job {
+  const jobExecutions = dto.job_executions.map(toJobExecution);
+
+  return new Job({
+    id: dto.id,
+    runAttemptId: dto.run_attempt_id,
+    key: dto.key,
+    name: dto.name,
+    mode: dto.mode,
+    status: dto.status,
+    statusReason: dto.status_reason,
+    carriedOver: dto.carried_over,
+    listening: dto.listening,
+    listenerStatus: dto.listener_status,
+    resolutionReason: dto.resolution_reason,
+    dependencies: dto.dependencies,
+    position: dto.position,
+    createdAt: dto.created_at,
+    updatedAt: dto.updated_at,
+    jobExecutions,
+  });
+}

package/src/core/entities/step-attempt.ts

@@ -0,0 +1,89 @@
+import type {StepAttemptDto, StepGateResultDto} from '@shipfox/api-workflows-dto';
+import {type Duration, intervalToDuration} from 'date-fns';
+
+export type StepGateResult = StepGateResultDto;
+export type StepAttemptDisplayDuration =
+  | {state: 'fixed'; elapsed: Duration}
+  | {state: 'live'; fromIso: string};
+
+interface StepAttemptFields {
+  id: string;
+  stepId: string;
+  jobExecutionId: string;
+  attempt: number;
+  executionOrder: number;
+  status: string;
+  exitCode: number | null;
+  output: Record<string, unknown> | null;
+  error: Record<string, unknown> | null;
+  gateResult: StepGateResult;
+  restartFeedback: string | null;
+  startedAt: string;
+  finishedAt: string | null;
+}
+
+export class StepAttempt {
+  id!: string;
+  stepId!: string;
+  jobExecutionId!: string;
+  attempt!: number;
+  executionOrder!: number;
+  status!: string;
+  exitCode!: number | null;
+  output!: Record<string, unknown> | null;
+  error!: Record<string, unknown> | null;
+  gateResult!: StepGateResult;
+  restartFeedback!: string | null;
+  startedAt!: string;
+  finishedAt!: string | null;
+
+  constructor(fields: StepAttemptFields) {
+    Object.assign(this, fields);
+  }
+
+  get displayDuration(): StepAttemptDisplayDuration | null {
+    return stepAttemptDisplayDurationFromTimestamps(this);
+  }
+}
+
+export function toStepAttempt(dto: StepAttemptDto, jobExecutionId: string): StepAttempt {
+  return new StepAttempt({
+    id: dto.id,
+    stepId: dto.step_id,
+    jobExecutionId,
+    attempt: dto.attempt,
+    executionOrder: dto.execution_order,
+    status: dto.status,
+    exitCode: dto.exit_code ?? null,
+    output: dto.output ?? null,
+    error: dto.error ?? null,
+    gateResult: dto.gate_result ?? null,
+    restartFeedback: dto.restart_feedback ?? null,
+    startedAt: dto.started_at,
+    finishedAt: dto.finished_at ?? null,
+  });
+}
+
+export function stepAttemptDisplayDurationFromTimestamps({
+  startedAt,
+  finishedAt,
+}: {
+  startedAt: string;
+  finishedAt: string | null;
+}): StepAttemptDisplayDuration | null {
+  if (finishedAt === null) return {state: 'live', fromIso: startedAt};
+
+  const elapsed = durationBetween(startedAt, finishedAt);
+  return elapsed === null ? null : {state: 'fixed', elapsed};
+}
+
+function durationBetween(from: string, to: string): Duration | null {
+  const start = new Date(from);
+  const end = new Date(to);
+  if (!Number.isFinite(start.getTime()) || !Number.isFinite(end.getTime())) return null;
+
+  return intervalToDuration({
+    start,
+    end: end < start ? start : end,
+  });
+}