@stigmer/react 1.0.3 → 2.0.0

package/src/workflow/WorkflowTaskApprovalCard.tsx

@@ -0,0 +1,337 @@
+"use client";
+
+import { memo, useCallback, useEffect, useMemo, useState } from "react";
+import Markdown from "react-markdown";
+import { cn } from "@stigmer/theme";
+import { MARKDOWN_COMPONENTS, REMARK_PLUGINS } from "../internal/markdown-components";
+
+/** Outcome descriptor for UI rendering. */
+export interface TaskOutcome {
+  readonly name: string;
+  readonly label: string;
+}
+
+/** Props for {@link WorkflowTaskApprovalCard}. */
+export interface WorkflowTaskApprovalCardProps {
+  /** Name of the human_input task awaiting a decision. */
+  readonly taskName: string;
+  /**
+   * Resolved prompt text from the workflow's human_input task config.
+   * Rendered as markdown above the decision form to give the reviewer
+   * context about what they are approving.
+   */
+  readonly prompt?: string;
+  /**
+   * Configured outcomes from the workflow definition.
+   * Each entry renders as a button with the label as text.
+   * When empty, defaults to "Approve" / "Reject".
+   */
+  readonly outcomes: readonly TaskOutcome[];
+  /**
+   * JSON Schema describing the reviewer's input form.
+   * When provided, renders form fields from the schema's `properties`.
+   * Text properties render as textareas; others as text inputs.
+   */
+  readonly formSchema?: Record<string, unknown>;
+  /**
+   * Called when the reviewer submits a decision.
+   * The consumer (typically {@link WorkflowExecutionViewer}) wires this
+   * to `useWorkflowExecutionActions().submitTaskApproval`.
+   */
+  readonly onSubmit: (
+    taskName: string,
+    outcome: string,
+    formData?: Record<string, unknown>,
+    comment?: string,
+  ) => Promise<unknown>;
+  /** True while the submission RPC is in flight. */
+  readonly isSubmitting: boolean;
+  /** Additional CSS class names for the root container. */
+  readonly className?: string;
+}
+
+const DEFAULT_OUTCOMES: readonly TaskOutcome[] = [
+  { name: "approve", label: "Approve" },
+  { name: "reject", label: "Reject" },
+];
+
+/**
+ * Interactive approval card for workflow-level human_input tasks.
+ *
+ * Renders dynamic outcome buttons (from workflow configuration),
+ * optional form fields (from JSON Schema), and a comment textarea.
+ * Designed for inline rendering in the execution timeline when a
+ * human_input task is in `waiting_approval` state.
+ *
+ * Distinct from `WorkflowExecutionApprovalCard` (which handles agent
+ * tool approvals with `toolCallId` + `ApprovalAction`). This component
+ * uses `taskName` + `outcome` string + optional `formData`.
+ *
+ * Follows SDK component standards:
+ * - All colors via `--stgm-*` tokens (DD-005)
+ * - Keyboard navigable with ARIA labels (a11y)
+ * - `React.memo` for referential stability (DD-010)
+ * - Zero framework dependencies (DD-004)
+ *
+ * @example
+ * ```tsx
+ * <WorkflowTaskApprovalCard
+ *   taskName="daily_approval"
+ *   prompt="Review today's notification plan.\n\n**DAU**: 7,297 (down 15%)"
+ *   outcomes={[{ name: "approve", label: "Approve Plan" }, { name: "reject", label: "Reject" }]}
+ *   formSchema={{ type: "object", properties: { feedback: { type: "string" } } }}
+ *   onSubmit={actions.submitTaskApproval}
+ *   isSubmitting={actions.isSubmitting}
+ * />
+ * ```
+ */
+export const WorkflowTaskApprovalCard = memo(function WorkflowTaskApprovalCard({
+  taskName,
+  prompt,
+  outcomes: outcomesProp,
+  formSchema,
+  onSubmit,
+  isSubmitting,
+  className,
+}: WorkflowTaskApprovalCardProps) {
+  const outcomes = outcomesProp.length > 0 ? outcomesProp : DEFAULT_OUTCOMES;
+  const [activeOutcome, setActiveOutcome] = useState<string | null>(null);
+  const [comment, setComment] = useState("");
+  const [formData, setFormData] = useState<Record<string, string>>({});
+
+  const formFields = useMemo(() => extractFormFields(formSchema), [formSchema]);
+
+  useEffect(() => {
+    if (!isSubmitting) {
+      setActiveOutcome(null);
+    }
+  }, [isSubmitting]);
+
+  const handleFieldChange = useCallback((fieldName: string, value: string) => {
+    setFormData((prev) => ({ ...prev, [fieldName]: value }));
+  }, []);
+
+  const handleSubmit = useCallback(
+    (outcomeName: string) => {
+      setActiveOutcome(outcomeName);
+      const data = formFields.length > 0
+        ? Object.fromEntries(
+            Object.entries(formData).filter(([, v]) => v.trim() !== ""),
+          )
+        : undefined;
+      onSubmit(
+        taskName,
+        outcomeName,
+        data && Object.keys(data).length > 0 ? data : undefined,
+        comment.trim() || undefined,
+      );
+    },
+    [taskName, formData, comment, formFields.length, onSubmit],
+  );
+
+  return (
+    <div
+      role="form"
+      aria-label={`Approval decision for ${taskName}`}
+      aria-busy={isSubmitting}
+      className={cn(
+        "mt-2 rounded-lg border border-warning/30 bg-warning/5 p-3",
+        className,
+      )}
+    >
+      {prompt && (
+        <div className="mb-3 max-h-80 overflow-y-auto rounded border border-border bg-background p-3">
+          <div className="stgm-prose">
+            <Markdown components={MARKDOWN_COMPONENTS} remarkPlugins={REMARK_PLUGINS}>
+              {prompt}
+            </Markdown>
+          </div>
+        </div>
+      )}
+
+      {formFields.length > 0 && (
+        <div className="mb-3 space-y-2">
+          {formFields.map((field) => (
+            <div key={field.name}>
+              <label
+                htmlFor={`${taskName}-${field.name}`}
+                className="mb-1 block text-xs font-medium text-foreground"
+              >
+                {field.label}
+              </label>
+              <textarea
+                id={`${taskName}-${field.name}`}
+                value={formData[field.name] ?? ""}
+                onChange={(e) => handleFieldChange(field.name, e.target.value)}
+                placeholder={field.description}
+                disabled={isSubmitting}
+                rows={2}
+                className={cn(
+                  "w-full rounded border border-border bg-background px-2 py-1.5 text-xs text-foreground",
+                  "placeholder:text-muted-foreground",
+                  "focus:outline-none focus:ring-1 focus:ring-ring",
+                  "disabled:opacity-50",
+                  "resize-y",
+                )}
+              />
+            </div>
+          ))}
+        </div>
+      )}
+
+      <div className="mb-2">
+        <textarea
+          value={comment}
+          onChange={(e) => setComment(e.target.value)}
+          placeholder="Comment (optional)"
+          disabled={isSubmitting}
+          rows={1}
+          className={cn(
+            "w-full rounded border border-border bg-background px-2 py-1.5 text-xs text-foreground",
+            "placeholder:text-muted-foreground",
+            "focus:outline-none focus:ring-1 focus:ring-ring",
+            "disabled:opacity-50",
+            "resize-y",
+          )}
+        />
+      </div>
+
+      <div className="flex flex-wrap gap-2">
+        {outcomes.map((outcome, index) => (
+          <OutcomeButton
+            key={outcome.name}
+            label={outcome.label || capitalize(outcome.name)}
+            outcomeName={outcome.name}
+            variant={resolveVariant(outcome.name, index, outcomes.length)}
+            isActive={activeOutcome === outcome.name}
+            isSubmitting={isSubmitting}
+            onClick={handleSubmit}
+          />
+        ))}
+      </div>
+    </div>
+  );
+});
+
+// ---------------------------------------------------------------------------
+// Internal sub-components
+// ---------------------------------------------------------------------------
+
+type ButtonVariant = "primary" | "destructive" | "secondary";
+
+function OutcomeButton({
+  label,
+  outcomeName,
+  variant,
+  isActive,
+  isSubmitting,
+  onClick,
+}: {
+  readonly label: string;
+  readonly outcomeName: string;
+  readonly variant: ButtonVariant;
+  readonly isActive: boolean;
+  readonly isSubmitting: boolean;
+  readonly onClick: (name: string) => void;
+}) {
+  const variantClasses: Record<ButtonVariant, string> = {
+    primary: cn(
+      "bg-success text-success-foreground hover:bg-success/90",
+      "disabled:bg-success/50 disabled:text-success-foreground/70",
+    ),
+    destructive: cn(
+      "bg-destructive text-destructive-foreground hover:bg-destructive-hover",
+      "disabled:bg-destructive-subtle0 disabled:text-destructive-foreground/70",
+    ),
+    secondary: cn(
+      "border border-border bg-background text-foreground hover:bg-muted",
+      "disabled:bg-muted-faint disabled:text-muted-foreground-faint",
+    ),
+  };
+
+  return (
+    <button
+      type="button"
+      disabled={isSubmitting}
+      onClick={() => onClick(outcomeName)}
+      aria-label={label}
+      className={cn(
+        "inline-flex items-center justify-center gap-1.5 rounded-md px-3 py-1.5 text-xs font-medium transition-colors",
+        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
+        "disabled:cursor-not-allowed",
+        variantClasses[variant],
+      )}
+    >
+      {isActive && isSubmitting ? <SpinnerIcon /> : null}
+      {label}
+    </button>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+interface FormField {
+  readonly name: string;
+  readonly label: string;
+  readonly description: string;
+}
+
+function extractFormFields(schema?: Record<string, unknown>): FormField[] {
+  if (!schema || typeof schema !== "object") return [];
+  const properties = schema.properties;
+  if (!properties || typeof properties !== "object") return [];
+
+  return Object.entries(properties as Record<string, Record<string, unknown>>).map(
+    ([name, prop]) => ({
+      name,
+      label: capitalize(name.replace(/_/g, " ")),
+      description: (typeof prop?.description === "string" ? prop.description : "") as string,
+    }),
+  );
+}
+
+function resolveVariant(
+  outcomeName: string,
+  index: number,
+  total: number,
+): ButtonVariant {
+  if (index === 0) return "primary";
+
+  const lower = outcomeName.toLowerCase();
+  if (lower === "reject" || lower === "deny" || lower.includes("reject")) {
+    return "destructive";
+  }
+
+  if (index === total - 1 && total === 2) {
+    return "destructive";
+  }
+
+  return "secondary";
+}
+
+function capitalize(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+// ---------------------------------------------------------------------------
+// Inline SVG icons
+// ---------------------------------------------------------------------------
+
+function SpinnerIcon() {
+  return (
+    <svg
+      width="10"
+      height="10"
+      viewBox="0 0 12 12"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      className="animate-spin"
+      aria-hidden="true"
+    >
+      <path d="M6 1.5A4.5 4.5 0 1 1 1.5 6" strokeLinecap="round" />
+    </svg>
+  );
+}

package/src/workflow/WorkflowTaskApprovalSummary.tsx

@@ -0,0 +1,289 @@
+"use client";
+
+import { memo, useMemo } from "react";
+import Markdown from "react-markdown";
+import type { JsonObject } from "@bufbuild/protobuf";
+import { cn } from "@stigmer/theme";
+import { MARKDOWN_COMPONENTS, REMARK_PLUGINS } from "../internal/markdown-components";
+import { formatDuration, formatTimestamp } from "./format-utils";
+import type { TaskOutcome } from "./WorkflowTaskApprovalCard";
+import type { TaskDetailApprovalDecision } from "./execution-inspector";
+
+/** Props for {@link WorkflowTaskApprovalSummary}. */
+export interface WorkflowTaskApprovalSummaryProps {
+  /** Name of the human_input task whose decision is being summarized. */
+  readonly taskName: string;
+  /**
+   * Resolved prompt text from the workflow's human_input task config.
+   * Rendered as markdown so reviewers can see what was decided on.
+   */
+  readonly prompt?: string;
+  /**
+   * Configured outcomes from the workflow definition. Used to resolve the
+   * chosen outcome's human-readable label. When empty, the raw outcome
+   * identifier is shown.
+   */
+  readonly outcomes: readonly TaskOutcome[];
+  /**
+   * The recorded decision, sourced from the canonical task output. When
+   * `null` — or when its `outcome` is still empty — the gate has been
+   * resolved but the decision record has not yet materialized in the
+   * status snapshot; a "finalizing" affordance is shown instead.
+   */
+  readonly decision: TaskDetailApprovalDecision | null;
+  /** Additional CSS class names for the root container. */
+  readonly className?: string;
+}
+
+/**
+ * Read-only decision report for a resolved workflow human_input gate.
+ *
+ * Renders the prompt, the chosen outcome, the reviewer and timing, and any
+ * comment or form answers captured with the decision — sourced entirely
+ * from the canonical task-output record (see `derive-task-detail`). This is
+ * the resolved counterpart to {@link WorkflowTaskApprovalCard}: the card
+ * collects a decision while a gate is `waiting_approval`; this component
+ * presents the decision once it is made, so the Approval tab never offers
+ * an already-answered gate for a second decision.
+ *
+ * Designed for embedding in both the Stigmer Console and third-party
+ * dashboards — no routing, auth, or app-shell dependencies (DD-004). All
+ * visual properties flow through `--stgm-*` tokens (DD-005).
+ *
+ * @example
+ * ```tsx
+ * <WorkflowTaskApprovalSummary
+ *   taskName="team_lead_review"
+ *   prompt="Review today's notification plan."
+ *   outcomes={[{ name: "approve", label: "Approve Plan" }]}
+ *   decision={detail.approval.decision}
+ * />
+ * ```
+ */
+export const WorkflowTaskApprovalSummary = memo(function WorkflowTaskApprovalSummary({
+  taskName,
+  prompt,
+  outcomes,
+  decision,
+  className,
+}: WorkflowTaskApprovalSummaryProps) {
+  const isFinalizing = !decision || decision.outcome === "";
+
+  const outcomeLabel = useMemo(() => {
+    if (!decision || !decision.outcome) return "";
+    const match = outcomes.find((o) => o.name === decision.outcome);
+    return match?.label || capitalize(decision.outcome.replace(/_/g, " "));
+  }, [decision, outcomes]);
+
+  const tone: DecisionTone = useMemo(
+    () => (decision && !isFinalizing ? resolveTone(decision.outcome) : "neutral"),
+    [decision, isFinalizing],
+  );
+
+  const formEntries = useMemo(() => extractFormEntries(decision?.formData ?? null), [decision]);
+
+  return (
+    <div
+      role="group"
+      aria-label={`Approval decision for ${taskName}`}
+      className={cn("mt-2 rounded-lg border border-border bg-muted-subtle p-3", className)}
+    >
+      {/* Decision header */}
+      {isFinalizing ? (
+        <div className="flex items-center gap-2 text-xs text-muted-foreground">
+          <SpinnerIcon />
+          <span>Decision recorded — finalizing…</span>
+        </div>
+      ) : (
+        <div className="flex flex-wrap items-center gap-x-2 gap-y-1">
+          <span
+            className={cn(
+              "inline-flex items-center gap-1.5 rounded-md px-2 py-1 text-xs font-medium",
+              TONE_CLASSES[tone],
+            )}
+          >
+            <ToneIcon tone={tone} />
+            {outcomeLabel}
+          </span>
+          {decision!.autoResolved && (
+            <span className="rounded bg-muted px-1.5 py-0.5 text-[10px] font-medium text-muted-foreground">
+              auto-resolved
+            </span>
+          )}
+        </div>
+      )}
+
+      {/* Reviewer + timing */}
+      {!isFinalizing && (
+        <div className="mt-1.5 flex flex-wrap items-center gap-x-1.5 text-[11px] text-muted-foreground">
+          {decision!.reviewer && (
+            <span>
+              by <span className="font-medium text-foreground">{decision!.reviewer}</span>
+            </span>
+          )}
+          {decision!.respondedAt && (
+            <>
+              {decision!.reviewer && <Dot />}
+              <span className="tabular-nums">{formatTimestamp(decision!.respondedAt)}</span>
+            </>
+          )}
+          {decision!.waitDurationMs > 0 && (
+            <>
+              {(decision!.reviewer || decision!.respondedAt) && <Dot />}
+              <span className="tabular-nums">waited {formatDuration(decision!.waitDurationMs)}</span>
+            </>
+          )}
+        </div>
+      )}
+
+      {/* What was decided on */}
+      {prompt && (
+        <div className="mt-3 max-h-80 overflow-y-auto rounded border border-border bg-background p-3">
+          <div className="stgm-prose">
+            <Markdown components={MARKDOWN_COMPONENTS} remarkPlugins={REMARK_PLUGINS}>
+              {prompt}
+            </Markdown>
+          </div>
+        </div>
+      )}
+
+      {/* Reviewer comment */}
+      {!isFinalizing && decision!.comment && (
+        <div className="mt-3">
+          <p className="mb-1 text-[11px] font-medium uppercase tracking-wide text-muted-foreground">
+            Comment
+          </p>
+          <p className="whitespace-pre-wrap rounded border border-border bg-background p-2 text-xs text-foreground">
+            {decision!.comment}
+          </p>
+        </div>
+      )}
+
+      {/* Submitted form answers */}
+      {!isFinalizing && formEntries.length > 0 && (
+        <dl className="mt-3 space-y-2">
+          {formEntries.map((entry) => (
+            <div key={entry.key}>
+              <dt className="mb-1 text-[11px] font-medium uppercase tracking-wide text-muted-foreground">
+                {entry.label}
+              </dt>
+              <dd className="whitespace-pre-wrap rounded border border-border bg-background p-2 text-xs text-foreground">
+                {entry.value}
+              </dd>
+            </div>
+          ))}
+        </dl>
+      )}
+    </div>
+  );
+});
+
+// ---------------------------------------------------------------------------
+// Tone (visual treatment of the chosen outcome)
+// ---------------------------------------------------------------------------
+
+type DecisionTone = "approve" | "reject" | "neutral";
+
+const TONE_CLASSES: Record<DecisionTone, string> = {
+  approve: "bg-success-subtle text-success",
+  reject: "bg-destructive-subtle text-destructive",
+  neutral: "bg-muted text-foreground",
+};
+
+/**
+ * Maps an outcome identifier to a visual tone. Reject/deny outcomes read
+ * as destructive; approve/accept as success; everything else neutral.
+ * Color is never the sole signal — the outcome label is always shown.
+ */
+function resolveTone(outcome: string): DecisionTone {
+  const lower = outcome.toLowerCase();
+  if (lower.includes("reject") || lower.includes("deny") || lower.includes("decline")) {
+    return "reject";
+  }
+  if (lower.includes("approve") || lower.includes("accept") || lower === "yes") {
+    return "approve";
+  }
+  return "neutral";
+}
+
+// ---------------------------------------------------------------------------
+// Form answer extraction
+// ---------------------------------------------------------------------------
+
+interface FormEntry {
+  readonly key: string;
+  readonly label: string;
+  readonly value: string;
+}
+
+/** Flattens a form-data object into displayable label/value entries. */
+function extractFormEntries(formData: JsonObject | null): FormEntry[] {
+  if (!formData) return [];
+  return Object.entries(formData).map(([key, raw]) => ({
+    key,
+    label: capitalize(key.replace(/_/g, " ")),
+    value: stringifyValue(raw),
+  }));
+}
+
+function stringifyValue(value: unknown): string {
+  if (value === null || value === undefined) return "";
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return String(value);
+  }
+}
+
+function capitalize(s: string): string {
+  return s.length > 0 ? s.charAt(0).toUpperCase() + s.slice(1) : s;
+}
+
+// ---------------------------------------------------------------------------
+// Inline SVG icons
+// ---------------------------------------------------------------------------
+
+function Dot() {
+  return <span aria-hidden="true">·</span>;
+}
+
+function ToneIcon({ tone }: { readonly tone: DecisionTone }) {
+  if (tone === "reject") {
+    return (
+      <svg width="12" height="12" viewBox="0 0 12 12" fill="none" stroke="currentColor" strokeWidth="1.75" aria-hidden="true">
+        <path d="M3 3l6 6M9 3l-6 6" strokeLinecap="round" />
+      </svg>
+    );
+  }
+  if (tone === "approve") {
+    return (
+      <svg width="12" height="12" viewBox="0 0 12 12" fill="none" stroke="currentColor" strokeWidth="1.75" aria-hidden="true">
+        <path d="M2.5 6.5l2.5 2.5 4.5-5.5" strokeLinecap="round" strokeLinejoin="round" />
+      </svg>
+    );
+  }
+  return (
+    <svg width="12" height="12" viewBox="0 0 12 12" fill="none" stroke="currentColor" strokeWidth="1.75" aria-hidden="true">
+      <circle cx="6" cy="6" r="4" />
+    </svg>
+  );
+}
+
+function SpinnerIcon() {
+  return (
+    <svg
+      width="12"
+      height="12"
+      viewBox="0 0 12 12"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      className="animate-spin"
+      aria-hidden="true"
+    >
+      <path d="M6 1.5A4.5 4.5 0 1 1 1.5 6" strokeLinecap="round" />
+    </svg>
+  );
+}