@calliopelabs/ui 0.11.0 → 0.12.0

package/README.md

@@ -284,6 +284,19 @@ The package fetches nothing. `DataTable` reads a `TableController`: rows, state,
 
 ## Workflows
 
+`WorkflowQuestionCard` shows a host-owned runtime question, including several
+fields, optional choices and Unicode answers. Bind `question.id`, its opaque
+`revision`, `answers` and delivery `state` to the same request. `onSubmit` reports
+answer intent only; the host must authorize delivery and set `submitting` before
+starting its request. Use `accepted` when the service accepted the answer and
+`acknowledged` only with correlated worker evidence. For uncertain delivery,
+`onRefresh` reads the original request without submitting it again. A changed
+question identity or revision requires a fresh host-owned answer draft.
+
+The card handles loading, empty, read-only, expired and unavailable states. Its
+copy is overridable through the `workflowQuestion` message group. It never starts
+work, grants permission, fetches data or infers acknowledgment from a click.
+
 The workflow surfaces are module-neutral: software, content, media, legal, document review, process, paperwork and automations are labels and versions the host supplies, and nothing in the model assumes tickets, repositories or code. They are host-driven: data in, callbacks out. The package never fetches, saves, authorizes or runs anything.
 
 - **Gallery.** `WorkflowGallery` is a full page of `WorkflowCard`s with search, a module filter, scope and status filters, grid and list views, and create and import when the host passes their handlers. Its filters are controlled (`filters`, `onFiltersChange`): a host that searches on its server passes them to its query; one that holds every definition uses `filterWorkflows(workflows, filters)`. Empty and no-matches are different states.

package/dist/index.d.ts

@@ -64,6 +64,8 @@ export { Tabs, TabsContent, TabsList, TabsTrigger } from "./primitives/Tabs.js";
 export { Skeleton } from "./primitives/Skeleton.js";
 export type { WorkflowAction, WorkflowAvailability, WorkflowModule, WorkflowPermissions, WorkflowScope, WorkflowStatus, WorkflowSummary, } from "./workflow/model.js";
 export { WorkflowCard, WorkflowCardSkeleton, type WorkflowCardActions, type WorkflowCardProps, } from "./workflow/WorkflowCard.js";
+export { WorkflowQuestionCard, type WorkflowQuestionCardProps, } from "./workflow/WorkflowQuestionCard.js";
+export type { WorkflowQuestion, WorkflowQuestionField, WorkflowQuestionState, WorkflowQuestionAnswers, WorkflowQuestionSubmission, } from "./workflow/question.js";
 export { ANY_FILTER, DEFAULT_WORKFLOW_FILTERS, filterWorkflows, isFiltered, type WorkflowGalleryFilters, } from "./workflow/gallery.js";
 export { WorkflowGallery, type WorkflowGalleryProps, type WorkflowGalleryView, } from "./workflow/WorkflowGallery.js";
 export { ARTIFACT_TONE, GATE_TONE, RUN_STAGE_TONE, VERDICT_TONE, type Artifact, type ArtifactStatus, type Gate, type GateStatus, type ReviewComment, type ReviewDecision, type ReviewVerdict, type RunStage, type RunStageStatus, type RunValue, } from "./workflow/run.js";

package/dist/index.js

@@ -74,6 +74,7 @@ export { Popover, PopoverAnchor, PopoverContent, PopoverHeader, PopoverTrigger,
 export { Tabs, TabsContent, TabsList, TabsTrigger } from "./primitives/Tabs.js";
 export { Skeleton } from "./primitives/Skeleton.js";
 export { WorkflowCard, WorkflowCardSkeleton, } from "./workflow/WorkflowCard.js";
+export { WorkflowQuestionCard, } from "./workflow/WorkflowQuestionCard.js";
 export { ANY_FILTER, DEFAULT_WORKFLOW_FILTERS, filterWorkflows, isFiltered, } from "./workflow/gallery.js";
 export { WorkflowGallery, } from "./workflow/WorkflowGallery.js";
 export { ARTIFACT_TONE, GATE_TONE, RUN_STAGE_TONE, VERDICT_TONE, } from "./workflow/run.js";

package/dist/provider/messages.d.ts

@@ -1,4 +1,5 @@
 import type { ProductTheme } from "../appearance/product.js";
+import type { WorkflowQuestionState } from "../workflow/question.js";
 import type { WorkflowAction, WorkflowAvailability, WorkflowScope, WorkflowStatus } from "../workflow/model.js";
 import type { ArtifactStatus, GateStatus, ReviewDecision, ReviewVerdict, RunStageStatus } from "../workflow/run.js";
 import type { WorkflowConnectReason, WorkflowNode, WorkflowNodeKind, WorkflowSelector } from "../workflow/definition.js";
@@ -21,6 +22,23 @@ import type { WorkflowReadError } from "../workflow/portable.js";
  * it (plurals, numbers, word order).
  */
 export interface Messages {
+    workflowQuestion: {
+        title: string;
+        worker: (worker: string) => string;
+        state: (state: WorkflowQuestionState) => string;
+        description: (state: WorkflowQuestionState) => string;
+        loading: string;
+        empty: string;
+        answer: string;
+        answers: string;
+        otherAnswers: string;
+        multipleHint: string;
+        invalidAnswer: string;
+        readOnly: string;
+        send: string;
+        sending: string;
+        refresh: string;
+    };
     shell: {
         skipToContent: string;
         /** The mobile button and drawer title for the sidebar. */

package/dist/provider/messages.js

@@ -144,6 +144,39 @@ function problemText({ code, values: v }) {
     }
 }
 export const defaultMessages = {
+    workflowQuestion: {
+        title: "Question for this run",
+        worker: (worker) => `Worker: ${worker}`,
+        state: (state) => ({
+            waiting: "Waiting for an answer",
+            submitting: "Sending answer",
+            accepted: "Answer sent",
+            acknowledged: "Worker acknowledged",
+            expired: "Answer window closed",
+            "delivery-unknown": "Delivery unconfirmed",
+            unavailable: "Question unavailable",
+        })[state],
+        description: (state) => ({
+            waiting: "Answer the questions below to continue this task.",
+            submitting: "Sending your answer to this task.",
+            accepted: "Waiting for the worker to acknowledge your answer.",
+            acknowledged: "The worker acknowledged this answer.",
+            expired: "This question can no longer accept an answer.",
+            "delivery-unknown": "Check delivery before sending another answer.",
+            unavailable: "The current question could not be read. Check again to continue.",
+        })[state],
+        loading: "Loading question…",
+        empty: "Nothing needs an answer right now.",
+        answer: "Answer",
+        answers: "Answers",
+        otherAnswers: "Additional answers",
+        multipleHint: "Choose options or enter additional answers on separate lines. Up to eight answers.",
+        invalidAnswer: "Answer each question with up to 4,000 characters per answer. Multiple answers must be distinct, with no more than eight.",
+        readOnly: "An operator can provide these answers.",
+        send: "Send answer",
+        sending: "Sending answer…",
+        refresh: "Check delivery",
+    },
     shell: {
         skipToContent: "Skip to content",
         navigation: "Navigation",

package/dist/workflow/WorkflowQuestionCard.d.ts

@@ -0,0 +1,18 @@
+import * as React from "react";
+import type { WorkflowQuestion, WorkflowQuestionAnswers, WorkflowQuestionState, WorkflowQuestionSubmission } from "./question.js";
+export interface WorkflowQuestionCardProps {
+    question: WorkflowQuestion | null;
+    state: WorkflowQuestionState;
+    answers?: WorkflowQuestionAnswers;
+    onAnswersChange?: (answers: WorkflowQuestionAnswers) => void;
+    /** Synchronous intent notification. Set the controlled state before starting delivery. */
+    onSubmit?: (submission: WorkflowQuestionSubmission) => void;
+    /** Read current delivery state. This action never submits an answer. */
+    onRefresh?: () => void;
+    canAnswer?: boolean;
+    reason?: string;
+    loading?: boolean;
+    className?: string;
+}
+/** Controlled projection: a submit callback is never evidence of runtime acknowledgment. */
+export declare function WorkflowQuestionCard(props: WorkflowQuestionCardProps): React.JSX.Element;

package/dist/workflow/WorkflowQuestionCard.js

@@ -0,0 +1,78 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { cn } from "../lib/cn.js";
+import { Button } from "../primitives/Button.js";
+import { Checkbox } from "../primitives/Checkbox.js";
+import { Field } from "../primitives/Field.js";
+import { Textarea } from "../primitives/Textarea.js";
+import { Skeleton } from "../primitives/Skeleton.js";
+import { useUI } from "../provider/UIProvider.js";
+import { StatusBadge } from "../status/StatusBadge.js";
+const TONE = {
+    waiting: "warn",
+    submitting: "info",
+    accepted: "info",
+    acknowledged: "ok",
+    expired: "muted",
+    "delivery-unknown": "warn",
+    unavailable: "error",
+};
+function textValid(value) {
+    return value.trim().length > 0 && Array.from(value).length <= 4000 && !value.includes("\0");
+}
+function answerValid(field, value) {
+    if (field.multiple)
+        return (value !== undefined &&
+            typeof value !== "string" &&
+            value.length > 0 &&
+            value.length <= 8 &&
+            new Set(value).size === value.length &&
+            value.every(textValid));
+    return typeof value === "string" && textValid(value);
+}
+/** Controlled projection: a submit callback is never evidence of runtime acknowledgment. */
+export function WorkflowQuestionCard(props) {
+    return (_jsx(QuestionBody, { ...props }, JSON.stringify([props.question?.id, props.question?.revision])));
+}
+function QuestionBody({ question, state, answers = {}, onAnswersChange, onSubmit, onRefresh, canAnswer = true, reason, loading = false, className, }) {
+    const t = useUI().messages.workflowQuestion;
+    const id = React.useId();
+    const [attempted, setAttempted] = React.useState(false);
+    const editable = !loading && state === "waiting" && canAnswer && !!onSubmit && !!onAnswersChange;
+    const set = (field, value) => {
+        if (editable)
+            onAnswersChange?.({ ...answers, [field]: value });
+    };
+    const submit = (event) => {
+        event.preventDefault();
+        if (!editable || !question?.fields.length)
+            return;
+        setAttempted(true);
+        if (question.fields.some((field) => !answerValid(field, answers[field.id])))
+            return;
+        const selected = Object.fromEntries(question.fields.map((field) => {
+            const value = answers[field.id];
+            return [field.id, typeof value === "string" ? value : [...value]];
+        }));
+        onSubmit?.({ questionId: question.id, revision: question.revision, answers: selected });
+    };
+    return (_jsxs("section", { "data-slot": "workflow-question-card", "aria-labelledby": `${id}-title`, "aria-busy": loading || state === "submitting", className: cn("space-y-4 rounded-lg border bg-card p-4 text-card-foreground", className), children: [_jsxs("div", { className: "flex flex-wrap items-start justify-between gap-3", children: [_jsxs("div", { className: "min-w-0 space-y-1", children: [_jsx("h3", { id: `${id}-title`, className: "font-medium break-words", children: question?.title ?? t.title }), question?.worker && (_jsx("p", { className: "text-sm text-muted-foreground", children: t.worker(question.worker) }))] }), !loading && (_jsx(StatusBadge, { tone: TONE[state], pulse: state === "submitting" || state === "accepted", children: t.state(state) }))] }), _jsx("p", { role: "status", className: "text-sm text-muted-foreground", children: loading ? t.loading : t.description(state) }), reason && _jsx("p", { className: "text-sm text-muted-foreground", children: reason }), loading ? (_jsxs("div", { className: "space-y-3", children: [_jsx(Skeleton, { className: "h-5 w-1/2" }), _jsx(Skeleton, { className: "h-20 w-full" })] })) : !question?.fields.length ? (state === "waiting" ? (_jsx("p", { className: "text-sm text-muted-foreground", children: t.empty })) : null) : (_jsxs("form", { onSubmit: submit, noValidate: true, className: "space-y-5", children: [question.fields.map((field, index) => {
+                        const value = answers[field.id];
+                        const selected = value !== undefined && typeof value !== "string" ? value : [];
+                        const labels = new Set(field.options?.map((option) => option.label));
+                        const custom = selected.filter((answer) => !labels.has(answer));
+                        const error = attempted && !answerValid(field, value) ? t.invalidAnswer : undefined;
+                        return (_jsxs("fieldset", { disabled: !editable, className: "min-w-0 space-y-3", children: [_jsx("legend", { className: "mb-3 text-sm font-medium break-words whitespace-pre-wrap", children: field.text }), !!field.options?.length && (_jsx("div", { className: "flex flex-wrap gap-2", children: field.options.map((option, optionIndex) => field.multiple ? (_jsxs("label", { htmlFor: `${id}-${index}-${optionIndex}`, className: "flex max-w-full min-w-0 items-start gap-2 rounded-lg border p-2 text-sm", children: [_jsx(Checkbox, { id: `${id}-${index}-${optionIndex}`, disabled: !editable, checked: selected.includes(option.label), onCheckedChange: (checked) => set(field.id, checked === true
+                                                    ? [
+                                                        ...selected.filter((answer) => answer !== option.label),
+                                                        option.label,
+                                                    ]
+                                                    : selected.filter((answer) => answer !== option.label)) }), _jsxs("span", { className: "min-w-0 break-words", children: [option.label, option.description && (_jsxs("span", { className: "mt-1 block text-xs text-muted-foreground", children: [" ", option.description] }))] })] }, option.label)) : (_jsx(Button, { type: "button", variant: "outline", disabled: !editable, className: "h-auto max-w-full min-w-0 py-2 text-left", "aria-pressed": value === option.label, onClick: () => set(field.id, option.label), children: _jsxs("span", { className: "min-w-0 break-words whitespace-normal", children: [option.label, option.description && (_jsxs("span", { className: "mt-1 block text-xs text-muted-foreground", children: [" ", option.description] }))] }) }, option.label))) })), _jsx(Field, { label: field.multiple ? (field.options?.length ? t.otherAnswers : t.answers) : t.answer, hint: field.multiple ? t.multipleHint : undefined, error: error, children: _jsx(Textarea, { readOnly: !editable, disabled: !editable, rows: 3, value: field.multiple ? custom.join("\n") : typeof value === "string" ? value : "", onChange: (event) => set(field.id, field.multiple
+                                            ? [
+                                                ...selected.filter((answer) => labels.has(answer)),
+                                                ...(event.target.value === "" ? [] : event.target.value.split("\n")),
+                                            ]
+                                            : event.target.value) }) })] }, field.id));
+                    }), !canAnswer && state === "waiting" && !reason && (_jsx("p", { className: "text-sm text-muted-foreground", children: t.readOnly })), onSubmit && (state === "waiting" || state === "submitting") && (_jsx(Button, { type: "submit", disabled: !editable, children: state === "submitting" ? t.sending : t.send }))] })), onRefresh && (state === "delivery-unknown" || state === "unavailable") && (_jsx(Button, { type: "button", variant: "outline", onClick: onRefresh, children: t.refresh }))] }));
+}

package/dist/workflow/question.d.ts

@@ -0,0 +1,26 @@
+/** Runtime question state supplied by the host, independently of form submission. */
+export type WorkflowQuestionState = "waiting" | "submitting" | "accepted" | "acknowledged" | "expired" | "delivery-unknown" | "unavailable";
+export interface WorkflowQuestionField {
+    id: string;
+    text: string;
+    options?: readonly {
+        label: string;
+        description?: string;
+    }[];
+    multiple?: boolean;
+}
+export interface WorkflowQuestion {
+    id: string;
+    /** Opaque host revision, echoed unchanged with the answer intent. */
+    revision: string;
+    title?: string;
+    worker?: string;
+    fields: readonly WorkflowQuestionField[];
+}
+export type WorkflowQuestionAnswers = Readonly<Record<string, string | readonly string[]>>;
+/** Intent only. The host owns authorization, delivery correlation and acknowledgment. */
+export interface WorkflowQuestionSubmission {
+    questionId: string;
+    revision: string;
+    answers: WorkflowQuestionAnswers;
+}

package/dist/workflow/question.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calliopelabs/ui",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Calliope AI shared operator UI: app shell, navigation, page frame, data table and list patterns, status colours, design tokens and appearance for Astrolift AI and Zentinelle AI.",
   "keywords": [
     "calliope-ai",