@stigmer/react 3.6.0 → 3.8.0

package/src/conversation/ConversationComposer.tsx

@@ -0,0 +1,156 @@
+"use client";
+
+import { useId, useState } from "react";
+import { Send, TriangleAlert } from "lucide-react";
+import { cn } from "@stigmer/theme";
+import { getUserMessage } from "@stigmer/sdk";
+import { ChannelSendOutcome } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/message_io_pb";
+import type { SendChannelMessageOutput } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/message_io_pb";
+import { Button } from "../button/Button.js";
+import { SpinnerIcon } from "../composer/icons.js";
+import { useComposer } from "../composer/useComposer.js";
+
+/** Props for {@link ConversationComposer}. */
+export interface ConversationComposerProps {
+  /** Send a staff reply (from `useConversationParticipation().reply`). */
+  readonly onSend: (text: string) => Promise<SendChannelMessageOutput>;
+  /** `true` while a reply is in flight. */
+  readonly isSending: boolean;
+  /**
+   * Why replying is unavailable, when it is — rendered in place of the
+   * input (a senderless provider, or a conversation the customer has
+   * not started yet). `null` enables the composer.
+   */
+  readonly disabledReason: string | null;
+  /**
+   * A pre-send forecast that ANNOTATES the enabled input — the
+   * `disabledReason` pattern's sibling with the opposite contract
+   * (channel-conversations DD-014 D-e): a closed service window is a
+   * forecast, not a structural block, so the input stays usable and the
+   * send engines remain the authority. Rendered above the input and
+   * associated via `aria-describedby` (never a live region: the
+   * advisory is state a reader meets on open, not an event). Compute it
+   * with `serviceWindowOf`; `null` or omitted renders nothing.
+   */
+  readonly advisory?: string | null;
+  /** Additional classes for the composer container. */
+  readonly className?: string;
+}
+
+/**
+ * The staff reply composer. Sending is an implicit takeover — the agent
+ * goes quiet the moment a staff reply lands, before the send itself —
+ * so this composer is only ever rendered alongside the control banner
+ * that shows that state change.
+ *
+ * Outcome honesty: `refused` keeps the draft (the words never left) and
+ * renders the server's refusal detail verbatim; `queued` clears it and
+ * says the platform is retrying; a thrown failure keeps the draft and
+ * renders the error. The timeline shows the delivered item via its own
+ * read — this component never fabricates one.
+ */
+export function ConversationComposer({
+  onSend,
+  isSending,
+  disabledReason,
+  advisory,
+  className,
+}: ConversationComposerProps) {
+  const advisoryId = useId();
+  const hasAdvisory = advisory != null && advisory !== "";
+  const [notice, setNotice] = useState<{
+    readonly kind: "refused" | "queued" | "error";
+    readonly text: string;
+  } | null>(null);
+
+  const composer = useComposer({
+    onSubmit: (message) => {
+      setNotice(null);
+      onSend(message).then(
+        (output) => {
+          if (output.outcome === ChannelSendOutcome.refused) {
+            // The words never left; keep them so the user can adjust.
+            composer.setMessage(message);
+            setNotice({
+              kind: "refused",
+              text: output.detail || "The provider refused this message.",
+            });
+          } else if (output.outcome === ChannelSendOutcome.queued) {
+            setNotice({
+              kind: "queued",
+              text: "Delivery hit a transient issue — the platform is retrying in the background.",
+            });
+          }
+        },
+        (err) => {
+          composer.setMessage(message);
+          setNotice({ kind: "error", text: getUserMessage(err) });
+        },
+      );
+    },
+    disabled: disabledReason !== null || isSending,
+  });
+
+  if (disabledReason !== null) {
+    return (
+      <div className={cn("border-t border-border px-4 py-3", className)}>
+        <p className="text-center text-xs text-muted-foreground">{disabledReason}</p>
+      </div>
+    );
+  }
+
+  return (
+    <div className={cn("border-t border-border px-4 py-3", className)}>
+      {/* The persistent forecast sits above the transient send-outcome
+          notice: the notice is the more recent event and belongs closest
+          to the input it reacts to. */}
+      {hasAdvisory && (
+        <p
+          id={advisoryId}
+          className="mb-2 flex items-start gap-1.5 rounded-md bg-status-degraded-subtle px-2.5 py-1.5 text-xs text-status-degraded"
+        >
+          <TriangleAlert aria-hidden="true" className="mt-0.5 size-3.5 shrink-0" />
+          <span className="min-w-0">{advisory}</span>
+        </p>
+      )}
+      {notice && (
+        <p
+          className={cn(
+            "mb-2 text-xs",
+            notice.kind === "queued" ? "text-muted-foreground" : "text-destructive",
+          )}
+          role="status"
+        >
+          {notice.text}
+        </p>
+      )}
+      <div className="flex items-end gap-2">
+        <textarea
+          {...composer.textareaProps}
+          rows={1}
+          placeholder="Reply as your business…"
+          aria-label="Reply to the customer"
+          aria-describedby={hasAdvisory ? advisoryId : undefined}
+          className={cn(
+            "min-h-9 flex-1 resize-none rounded-md border border-border bg-background",
+            "px-3 py-2 text-sm text-foreground placeholder:text-muted-foreground-faint",
+            "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+          )}
+        />
+        <Button
+          variant="primary"
+          size="sm"
+          onClick={composer.submit}
+          disabled={!composer.canSubmit || isSending}
+          aria-label="Send reply"
+        >
+          {/* The house in-flight glyph (the session composer's pattern):
+              the spinner replaces the Send icon so the button itself
+              reports progress, not just its label. */}
+          {isSending ? <SpinnerIcon /> : <Send aria-hidden="true" className="size-4" />}
+          {isSending ? "Sending…" : "Send"}
+        </Button>
+      </div>
+    </div>
+  );
+}

package/src/conversation/ConversationControlBanner.tsx

@@ -0,0 +1,193 @@
+"use client";
+
+import { useState } from "react";
+import { Bot, User } from "lucide-react";
+import { cn } from "@stigmer/theme";
+import { getUserMessage } from "@stigmer/sdk";
+import {
+  ConversationControl,
+  type ChannelConversation,
+} from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/conversation_io_pb";
+import { Button } from "../button/Button.js";
+import type { UseConversationParticipationReturn } from "./useConversationParticipation.js";
+
+/** Props for {@link ConversationControlBanner}. */
+export interface ConversationControlBannerProps {
+  /** The conversation's fresh participation state. */
+  readonly conversation: ChannelConversation;
+  /** The participation commands (from `useConversationParticipation`). */
+  readonly participation: UseConversationParticipationReturn;
+  /**
+   * `true` when the customer's last message has not been answered —
+   * the conversation row's server-derived `awaiting_reply` fact, which
+   * is bounce-aware: a staff reply the provider later failed does not
+   * count as an answer (channel-conversations F-28/DD-015). Arms the
+   * handback confirm guard (DD-007 D-e): handing back runs NO turn, so
+   * the agent stays quiet until the customer next speaks, and the
+   * unanswered state must be unmissable. Never derive this from
+   * timeline authorship — the send attempt's presence on the timeline
+   * says nothing about whether the customer received it.
+   */
+  readonly unansweredCustomer: boolean;
+  /**
+   * Whether the channel's provider has a staff send lane. Senderless
+   * providers disable takeover with the reason — a takeover there would
+   * silence the agent while no human reply could reach the customer,
+   * which is exactly what the server refuses.
+   */
+  readonly supportsStaffReplies: boolean;
+  /**
+   * The signed-in staff member's identity account id, when the host
+   * knows it — lets the banner attribute a human hold: "You have this
+   * conversation" when it matches, "A teammate has this conversation"
+   * when it differs. When omitted the banner only states that a human
+   * holds it — the holder may be the viewer themself, so "a teammate"
+   * would be a guess. Optional: the SDK never assumes a host's auth
+   * state.
+   */
+  readonly currentIdentityAccountId?: string;
+  /** Additional classes for the banner container. */
+  readonly className?: string;
+}
+
+/**
+ * Who may speak to the customer, and the controls that move it: take
+ * over (the agent goes quiet) and hand back (the agent resumes, with
+ * the context it missed injected on its next turn).
+ *
+ * Truth rules: state renders from the conversation row the server
+ * answered — a takeover that lost its race renders the WINNER's hold,
+ * because that is what happened. Failures render verbatim beside the
+ * control that caused them.
+ */
+export function ConversationControlBanner({
+  conversation,
+  participation,
+  unansweredCustomer,
+  supportsStaffReplies,
+  currentIdentityAccountId,
+  className,
+}: ConversationControlBannerProps) {
+  const [confirmingHandBack, setConfirmingHandBack] = useState(false);
+
+  const humanHeld = conversation.control === ConversationControl.control_human;
+  const heldByMe =
+    humanHeld &&
+    currentIdentityAccountId !== undefined &&
+    conversation.controlledBy === currentIdentityAccountId;
+
+  const { takeOver, handBack, pendingCommands, commandErrors } = participation;
+  const error = commandErrors.get("takeOver") ?? commandErrors.get("handBack");
+
+  const requestHandBack = () => {
+    if (unansweredCustomer) {
+      setConfirmingHandBack(true);
+      return;
+    }
+    void handBack().catch(() => {
+      // Recorded in commandErrors and rendered below.
+    });
+  };
+
+  return (
+    <div
+      className={cn(
+        "border-b border-border px-4 py-2",
+        humanHeld ? "bg-primary-subtle" : "bg-muted-faint",
+        className,
+      )}
+    >
+      <div className="flex flex-wrap items-center justify-between gap-2">
+        <p className="flex items-center gap-1.5 text-sm text-foreground">
+          {humanHeld ? (
+            <>
+              <User aria-hidden="true" className="size-4 text-muted-foreground" />
+              {heldByMe
+                ? "You have this conversation — the agent is quiet until you hand it back."
+                : currentIdentityAccountId !== undefined
+                  ? "A teammate has this conversation — the agent is quiet until handback."
+                  : // Without the host's identity the holder may be the
+                    // viewer themself — claiming "a teammate" would be a
+                    // guess. State only what the row proves: a human
+                    // holds it (channel-conversations F-01).
+                    "This conversation is with a human — the agent is quiet until handback."}
+            </>
+          ) : (
+            <>
+              <Bot aria-hidden="true" className="size-4 text-muted-foreground" />
+              The agent is serving this conversation.
+            </>
+          )}
+        </p>
+
+        {confirmingHandBack ? (
+          <div className="flex items-center gap-2">
+            <span className="text-xs text-destructive">
+              The customer&apos;s last message has no reply — the agent stays
+              quiet until they write again.
+            </span>
+            <Button
+              variant="outline"
+              size="xs"
+              onClick={() => {
+                setConfirmingHandBack(false);
+                void handBack().catch(() => {
+                  // Recorded in commandErrors and rendered below.
+                });
+              }}
+              disabled={pendingCommands.has("handBack")}
+            >
+              Hand back anyway
+            </Button>
+            <Button
+              variant="primary"
+              size="xs"
+              onClick={() => setConfirmingHandBack(false)}
+            >
+              Keep the conversation
+            </Button>
+          </div>
+        ) : humanHeld ? (
+          <Button
+            variant="outline"
+            size="xs"
+            onClick={requestHandBack}
+            disabled={pendingCommands.has("handBack")}
+          >
+            {pendingCommands.has("handBack") ? "Handing back…" : "Hand back to agent"}
+          </Button>
+        ) : (
+          <div className="flex items-center gap-2">
+            {!supportsStaffReplies && (
+              // Visible text, never a native title (F-18): a disabled
+              // Button swallows hover (disabled:pointer-events-none) and
+              // leaves the tab order, so a title on it is unreachable by
+              // every input method. Kept short — the composer's own
+              // notice already explains the missing staff reply lane.
+              <span className="text-xs text-muted-foreground">
+                This channel&apos;s provider has no staff send lane yet — a
+                takeover would silence the agent with no way to reply.
+              </span>
+            )}
+            <Button
+              variant="outline"
+              size="xs"
+              onClick={() =>
+                void takeOver().catch(() => {
+                  // Recorded in commandErrors and rendered below.
+                })
+              }
+              disabled={!supportsStaffReplies || pendingCommands.has("takeOver")}
+            >
+              {pendingCommands.has("takeOver") ? "Taking over…" : "Take over"}
+            </Button>
+          </div>
+        )}
+      </div>
+
+      {error && (
+        <p className="mt-1 text-xs text-destructive">{getUserMessage(error)}</p>
+      )}
+    </div>
+  );
+}