@corbits/react-ui 0.1.0

package/dist/lib/workflow-run-progress.js

@@ -0,0 +1,135 @@
+import { classifyRunError } from "./workflow-run-error.js";
+/** Label colour for a step's status, shared by every stepper/sidebar rendering. */ export function workflowStepLabelClass(status) {
+    if (status === "current") return "text-foreground";
+    if (status === "failed") return "text-destructive";
+    return "text-muted-foreground";
+}
+/** Mark glyph for a step's status: a checkmark, an exclamation, or its number. */ export function workflowStepGlyph(status, number) {
+    if (status === "completed") return "✓";
+    if (status === "failed") return "!";
+    return String(number);
+}
+export function getStepPhase(progress, stepId) {
+    return progress?.steps.get(stepId)?.phase;
+}
+export function isStepRunning(phase) {
+    return phase === "in-flight" || phase === "awaiting-signal" || phase === "awaiting-timer";
+}
+/** The aggregate phase of a display step from its runtime steps. */ export function displayStepPhase(progress, stepIds) {
+    if (stepIds.length === 0) return undefined;
+    const terminal = stepIds[stepIds.length - 1];
+    if (terminal !== undefined && getStepPhase(progress, terminal) === "completed") return "completed";
+    for (const id of stepIds){
+        const phase = getStepPhase(progress, id);
+        if (isStepRunning(phase)) return phase;
+    }
+    for (const id of stepIds){
+        if (getStepPhase(progress, id) === "failed") return "failed";
+    }
+    for (const id of stepIds){
+        if (getStepPhase(progress, id) !== undefined) return "in-flight";
+    }
+    return undefined;
+}
+function hasAnyProgress(progress, step) {
+    return step.stepIds.some((id)=>getStepPhase(progress, id) !== undefined);
+}
+/**
+ * Index of the display step the run is currently on. A step whose own phase
+ * is `failed` is never treated as passed even when a later, independently
+ * running branch has progressed — independent steps can run concurrently, so
+ * a later step's progress says nothing about whether this one failed.
+ * Returns the last index once every step is complete.
+ */ export function activeDisplayStepIndex(progress, steps) {
+    for(let i = 0; i < steps.length; i++){
+        const step = steps[i];
+        if (step === undefined) continue;
+        const phase = displayStepPhase(progress, step.stepIds);
+        if (phase === "completed") continue;
+        if (phase === "failed") return i;
+        const laterProgressed = steps.slice(i + 1).some((later)=>hasAnyProgress(progress, later));
+        if (laterProgressed) continue;
+        return i;
+    }
+    return Math.max(0, steps.length - 1);
+}
+export function buildStepperSteps(progress, steps) {
+    const activeIdx = activeDisplayStepIndex(progress, steps);
+    // A completed run marks every entry done: the final step's output can lag
+    // behind the run's own terminal phase, and without this it would linger
+    // as "current" on an already-finished run.
+    const runCompleted = progress?.phase === "completed";
+    return steps.map((step, i)=>{
+        let status;
+        if (runCompleted || i < activeIdx) {
+            status = "completed";
+        } else if (i > activeIdx) {
+            status = "pending";
+        } else {
+            const phase = displayStepPhase(progress, step.stepIds);
+            status = phase === "completed" ? "completed" : phase === "failed" ? "failed" : "current";
+        }
+        return {
+            number: i + 1,
+            label: step.label,
+            status
+        };
+    });
+}
+/** The active display step, or `null` while the run is terminal. */ export function activeDisplayStep(progress, steps) {
+    if (steps.length === 0) return null;
+    return steps[activeDisplayStepIndex(progress, steps)] ?? null;
+}
+/**
+ * The "what's happening now" verb for a live status line, taken from the
+ * active step's `activityLabel`. Returns `null` — showing no line — once the
+ * run is terminal, while the first step owns its own loading UI, once the
+ * active group is done or parked on a human gate, or when the active step
+ * carries no `activityLabel` at all (a gate or intake step): silence there is
+ * correct, never a stepper noun standing in for it.
+ */ export function liveStatusLabel(progress, steps) {
+    if (progress === null) return null;
+    if (progress.phase === "failed" || progress.phase === "completed") return null;
+    const idx = activeDisplayStepIndex(progress, steps);
+    if (idx === 0) return null;
+    const step = steps[idx];
+    if (step === undefined) return null;
+    const phase = displayStepPhase(progress, step.stepIds);
+    if (phase === "completed" || phase === "awaiting-signal") return null;
+    return step.activityLabel ?? null;
+}
+/** Label of the first display step whose aggregate phase is `failed`. Does
+ * not require `progress.phase === "failed"` — a caller flagging failure from
+ * a single failed step ahead of the run's own phase flip still gets a name. */ export function failedDisplayStepLabel(progress, steps) {
+    if (progress === null) return null;
+    for (const step of steps){
+        if (displayStepPhase(progress, step.stepIds) === "failed") return step.label;
+    }
+    return null;
+}
+/** The sanitized end-user message from whichever step failed the run, or
+ * `null` if the run has not failed or no step carries an error. Uses the
+ * first error found in map-iteration order — a run design that attaches an
+ * error to more than one step at once is a design this cannot disambiguate. */ export function failedRunErrorMessage(progress) {
+    if (progress?.phase !== "failed") return null;
+    for (const step of progress.steps.values()){
+        if (step.lastErrorMessage !== undefined) return classifyRunError(step.lastErrorMessage).userMessage;
+    }
+    return null;
+}
+/**
+ * True only for a genuine never-started run: a non-null progress with an
+ * empty step map, where that emptiness came from an event log that was
+ * actually read. `logRead` distinguishes that from a log-unavailable fallback
+ * (a legacy run, or a read error) that can synthesize the same empty-step
+ * shape regardless of phase — in that case whether it started is unknown, so
+ * this returns `false` rather than making a false "never started" claim.
+ */ export function runNeverStarted(progress, logRead) {
+    return progress !== null && logRead && progress.steps.size === 0;
+}
+/** Honest copy for the pre-interactive window before a run's first step has
+ * recorded any activity: queued (`pending`, or no progress yet) reads
+ * differently from a runtime already booting that first step. */ export function runStartLabel(progress) {
+    if (progress === null || progress.phase === "pending") return "Starting your workflow…";
+    return "Preparing your workflow…";
+}

package/dist/lib/workflow-run.d.ts

@@ -0,0 +1,43 @@
+import type { BadgeTone } from "../ui/badge.js";
+import type { StatusDotTone } from "../ui/status-dot.js";
+/**
+ * What a caller needs to know about a run without knowing what the run *did*.
+ *
+ * Status, identity and timing only. What a run produced — its blocks, its
+ * output, its event log — is a separate contract and deliberately not modelled
+ * here: a strip that lists runs should not have to understand their contents,
+ * and a surface that renders contents can take this alongside them.
+ */
+export type RunStatus = 
+/** Accepted, not yet executing. */
+"provisioning" | "running"
+/** Parked on a human decision. The only status that is *asking* for something. */
+ | "awaiting" | "completed" | "failed" | "stopped";
+export type WorkflowRunSummary = {
+    readonly runId: string;
+    /** Human title for the run's kind, e.g. "Daily brief". Already humanised. */
+    readonly title: string;
+    readonly status: RunStatus;
+    /** ISO timestamp of when the run started. */
+    readonly startedAt: string;
+    /** Where the run opens. */
+    readonly href?: string;
+};
+export declare const RUN_STATUS_LABEL: Record<RunStatus, string>;
+/**
+ * State is the only colour on these surfaces. `awaiting` is the one orange:
+ * it is the single status a person can act on, and orange is the registry's
+ * "this is for you" tone.
+ */
+export declare const RUN_STATUS_TONE: Record<RunStatus, BadgeTone>;
+/**
+ * The dot only marks liveness and failure — the badge above carries the full
+ * status colour. See `status-dot.tsx` for why it is three tones and not six.
+ */
+export declare const RUN_STATUS_DOT_TONE: Record<RunStatus, StatusDotTone>;
+/** A run that will not change again without someone starting a new one. */
+export declare function isTerminalRun(status: RunStatus): boolean;
+/** Still moving or still asking — what an "active runs" strip shows. */
+export declare function isActiveRun(status: RunStatus): boolean;
+/** Attention order, newest first within a band. Sorts a copy. */
+export declare function sortRunsByAttention(runs: readonly WorkflowRunSummary[]): readonly WorkflowRunSummary[];

package/dist/lib/workflow-run.js

@@ -0,0 +1,56 @@
+export const RUN_STATUS_LABEL = {
+    provisioning: "Starting",
+    running: "Running",
+    awaiting: "Needs you",
+    completed: "Completed",
+    failed: "Failed",
+    stopped: "Stopped"
+};
+/**
+ * State is the only colour on these surfaces. `awaiting` is the one orange:
+ * it is the single status a person can act on, and orange is the registry's
+ * "this is for you" tone.
+ */ export const RUN_STATUS_TONE = {
+    provisioning: "neutral",
+    running: "info",
+    awaiting: "accent",
+    completed: "success",
+    failed: "danger",
+    stopped: "neutral"
+};
+/**
+ * The dot only marks liveness and failure — the badge above carries the full
+ * status colour. See `status-dot.tsx` for why it is three tones and not six.
+ */ export const RUN_STATUS_DOT_TONE = {
+    provisioning: "neutral",
+    running: "emphasis",
+    awaiting: "emphasis",
+    completed: "neutral",
+    failed: "danger",
+    stopped: "neutral"
+};
+/** A run that will not change again without someone starting a new one. */ export function isTerminalRun(status) {
+    return status === "completed" || status === "failed" || status === "stopped";
+}
+/** Still moving or still asking — what an "active runs" strip shows. */ export function isActiveRun(status) {
+    return !isTerminalRun(status);
+}
+// Needs-you first, then in-flight, then whatever finished. Failed sorts above
+// completed because a failure is the finished run most likely to need a human.
+const ATTENTION_RANK = {
+    awaiting: 0,
+    running: 1,
+    provisioning: 1,
+    failed: 2,
+    completed: 3,
+    stopped: 4
+};
+/** Attention order, newest first within a band. Sorts a copy. */ export function sortRunsByAttention(runs) {
+    return [
+        ...runs
+    ].sort((a, b)=>{
+        const byAttention = ATTENTION_RANK[a.status] - ATTENTION_RANK[b.status];
+        if (byAttention !== 0) return byAttention;
+        return Date.parse(b.startedAt) - Date.parse(a.startedAt);
+    });
+}