@unofficialbox/box-open-elements 0.4.0 → 0.6.0

package/dist/patterns/agent-chat/controller.d.ts

@@ -0,0 +1,27 @@
+import { Controller } from "../../core/controller.js";
+import type { AgentActionDecision, AgentActionProposal, AgentChatEvents, AgentChatMessage, AgentChatSessionConfig, AgentChatState } from "./types.js";
+/**
+ * Headless conversation session: sends turns through the streaming
+ * `AgentChatTransport`, folds typed stream events (deltas, citations,
+ * action proposals) into one growing agent message, supports stopping a
+ * generation mid-stream (the partial reply is kept), and routes HITL
+ * decisions through the transport's `resolveAction` capability.
+ */
+export declare class AgentChatController extends Controller<AgentChatState, AgentChatEvents> {
+    readonly config: AgentChatSessionConfig;
+    private sendCounter;
+    private activeAbortController;
+    constructor(config: AgentChatSessionConfig);
+    connect(): void;
+    disconnect(): void;
+    getMessage(messageId: string): AgentChatMessage | undefined;
+    /** Abort the in-flight generation; whatever already streamed is kept. */
+    stop(): void;
+    /**
+     * Send a user turn and stream the agent's reply. One send at a time: a
+     * new send while a reply is streaming stops the previous generation.
+     */
+    send(body: string): Promise<AgentChatMessage | null>;
+    /** Resolve a HITL proposal through the transport capability. */
+    resolveAction(proposalId: string, decision: AgentActionDecision, note?: string): Promise<AgentActionProposal | null>;
+}

package/dist/patterns/agent-chat/controller.js

@@ -0,0 +1,182 @@
+import { Controller } from "../../core/controller.js";
+const createInitialState = () => ({
+    connected: false,
+    streaming: false,
+    messages: [],
+    error: null,
+});
+/**
+ * Headless conversation session: sends turns through the streaming
+ * `AgentChatTransport`, folds typed stream events (deltas, citations,
+ * action proposals) into one growing agent message, supports stopping a
+ * generation mid-stream (the partial reply is kept), and routes HITL
+ * decisions through the transport's `resolveAction` capability.
+ */
+export class AgentChatController extends Controller {
+    config;
+    sendCounter = 0;
+    activeAbortController = null;
+    constructor(config) {
+        super(createInitialState());
+        this.config = config;
+    }
+    connect() {
+        if (this.state.connected) {
+            return;
+        }
+        this.setState({ ...this.state, connected: true });
+        this.emit("connected", undefined);
+    }
+    disconnect() {
+        if (!this.state.connected) {
+            return;
+        }
+        this.activeAbortController?.abort();
+        this.activeAbortController = null;
+        this.setState(createInitialState());
+        this.emit("disconnected", undefined);
+    }
+    getMessage(messageId) {
+        return this.state.messages.find(message => message.id === messageId);
+    }
+    /** Abort the in-flight generation; whatever already streamed is kept. */
+    stop() {
+        this.activeAbortController?.abort();
+    }
+    /**
+     * Send a user turn and stream the agent's reply. One send at a time: a
+     * new send while a reply is streaming stops the previous generation.
+     */
+    async send(body) {
+        const trimmed = body.trim();
+        if (!this.state.connected || trimmed.length === 0) {
+            return null;
+        }
+        this.activeAbortController?.abort();
+        const abortController = typeof AbortController === "function" ? new AbortController() : null;
+        this.activeAbortController = abortController;
+        this.sendCounter += 1;
+        const turn = this.sendCounter;
+        const userMessage = {
+            id: `user-${String(turn)}`,
+            role: "user",
+            body: trimmed,
+            status: "complete",
+            citations: [],
+            proposals: [],
+        };
+        const agentMessage = {
+            id: `agent-${String(turn)}`,
+            role: "agent",
+            body: "",
+            status: "streaming",
+            ...(this.config.agentName ? { actor: { name: this.config.agentName } } : {}),
+            citations: [],
+            proposals: [],
+        };
+        this.setState({
+            ...this.state,
+            streaming: true,
+            error: null,
+            messages: [...this.state.messages, userMessage, agentMessage],
+        });
+        this.emit("streamingChanged", { streaming: true });
+        this.emit("messagesChanged", { messages: this.state.messages });
+        const patchAgentMessage = (patch) => {
+            this.setState({
+                ...this.state,
+                messages: this.state.messages.map(message => message.id === agentMessage.id ? { ...message, ...patch } : message),
+            });
+            this.emit("messagesChanged", { messages: this.state.messages });
+        };
+        const onEvent = (event) => {
+            const current = this.getMessage(agentMessage.id);
+            if (!current || current.status !== "streaming") {
+                return;
+            }
+            if (event.kind === "delta") {
+                patchAgentMessage({ body: current.body + event.text });
+            }
+            else if (event.kind === "citation") {
+                patchAgentMessage({ citations: [...current.citations, event.citation] });
+            }
+            else {
+                patchAgentMessage({ proposals: [...current.proposals, event.proposal] });
+            }
+        };
+        const finish = (patch) => {
+            patchAgentMessage(patch);
+            // A superseded send must not clear the newer send's streaming flag.
+            if (turn === this.sendCounter) {
+                this.setState({ ...this.state, streaming: false });
+                this.emit("streamingChanged", { streaming: false });
+            }
+        };
+        try {
+            await this.config.transport.sendMessage({
+                body: trimmed,
+                token: this.config.token,
+                onEvent,
+                ...(abortController ? { signal: abortController.signal } : {}),
+            });
+            finish({ status: "complete" });
+        }
+        catch (error) {
+            if (abortController?.signal.aborted) {
+                // A stop is not a failure: keep the partial reply.
+                finish({ status: "complete" });
+            }
+            else {
+                const message = error instanceof Error ? error.message : "The agent reply failed";
+                finish({ status: "error", errorMessage: message });
+                this.setState({ ...this.state, error: message });
+                this.emit("sendFailed", { message });
+            }
+        }
+        finally {
+            if (this.activeAbortController === abortController) {
+                this.activeAbortController = null;
+            }
+        }
+        return this.getMessage(agentMessage.id) ?? null;
+    }
+    /** Resolve a HITL proposal through the transport capability. */
+    async resolveAction(proposalId, decision, note) {
+        const transport = this.config.transport;
+        if (!transport.resolveAction) {
+            throw new Error("Agent-chat transport does not support resolveAction");
+        }
+        const holder = this.state.messages.find(message => message.proposals.some(proposal => proposal.id === proposalId));
+        const pending = holder?.proposals.find(proposal => proposal.id === proposalId);
+        if (!this.state.connected || !holder || !pending || pending.decision) {
+            return null;
+        }
+        try {
+            // Called on the transport so class-based implementations keep `this`.
+            const resolved = await transport.resolveAction({
+                proposalId,
+                decision,
+                ...(note !== undefined ? { note } : {}),
+                token: this.config.token,
+            });
+            this.setState({
+                ...this.state,
+                messages: this.state.messages.map(message => message.id === holder.id
+                    ? {
+                        ...message,
+                        proposals: message.proposals.map(proposal => proposal.id === proposalId ? { ...proposal, ...resolved } : proposal),
+                    }
+                    : message),
+            });
+            this.emit("messagesChanged", { messages: this.state.messages });
+            this.emit("actionResolved", { proposal: { ...pending, ...resolved }, decision });
+            return { ...pending, ...resolved };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : `Agent action ${decision} failed`;
+            this.setState({ ...this.state, error: message });
+            this.emit("sendFailed", { message });
+            return null;
+        }
+    }
+}

package/dist/patterns/agent-chat/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./types.js";
+export * from "./controller.js";
+export * from "./agent-chat.js";

package/dist/patterns/agent-chat/index.js

@@ -0,0 +1,6 @@
+// Conversation model + streaming transport contract
+export * from "./types.js";
+// Headless streaming session
+export * from "./controller.js";
+// Composed conversation surface
+export * from "./agent-chat.js";

package/dist/patterns/agent-chat/types.d.ts

@@ -0,0 +1,109 @@
+export type AgentRole = "user" | "agent";
+export type AgentMessageStatus = "streaming" | "complete" | "error";
+/** Same shape as the timeline's evidence chips — deep-linkable supporting content. */
+export interface AgentCitation {
+    id: string;
+    label: string;
+    /** Optional deep link; the shell always emits `citation-selected` either way. */
+    href?: string;
+}
+export type AgentActionDecision = "approved" | "rejected";
+/**
+ * A human-in-the-loop proposal: the agent wants to take a governed action
+ * and the card renders the review inline — the CLM "human-governed AI
+ * recommendations" requirement, delivered where the conversation happens.
+ */
+export interface AgentActionProposal {
+    id: string;
+    /** Short imperative title: "Apply standard liability clause". */
+    title: string;
+    summary?: string;
+    /** Reviewable parameters rendered on the card. */
+    params?: Array<{
+        label: string;
+        value: string;
+    }>;
+    /** Present once a decision has landed. */
+    decision?: AgentActionDecision;
+    note?: string;
+}
+export interface AgentChatMessage {
+    id: string;
+    role: AgentRole;
+    body: string;
+    status: AgentMessageStatus;
+    actor?: {
+        name: string;
+        initials?: string;
+    };
+    timestamp?: string;
+    citations: AgentCitation[];
+    proposals: AgentActionProposal[];
+    /** Human-readable failure detail when `status` is "error". */
+    errorMessage?: string;
+}
+/** Typed stream events a transport delivers while a reply generates. */
+export type AgentStreamEvent = {
+    kind: "delta";
+    text: string;
+} | {
+    kind: "citation";
+    citation: AgentCitation;
+} | {
+    kind: "proposal";
+    proposal: AgentActionProposal;
+};
+export interface AgentSendRequest {
+    body: string;
+    token: string;
+    signal?: AbortSignal;
+    /** Called for each stream event; the returned promise settles when the reply ends. */
+    onEvent: (event: AgentStreamEvent) => void;
+}
+export interface AgentResolveActionRequest {
+    proposalId: string;
+    decision: AgentActionDecision;
+    note?: string;
+    token: string;
+}
+/**
+ * One narrow contract for the conversation. `sendMessage` streams a reply
+ * through `onEvent` and settles when generation ends (an abort via `signal`
+ * settles early with whatever streamed). `resolveAction` is an optional
+ * capability: the shell only renders Approve/Reject when the transport
+ * provides it, and invoking it on the controller without the capability
+ * throws a descriptive error (a programming error, not a runtime state).
+ */
+export interface AgentChatTransport {
+    sendMessage(request: AgentSendRequest): Promise<void>;
+    resolveAction?(request: AgentResolveActionRequest): Promise<AgentActionProposal>;
+}
+export interface AgentChatSessionConfig {
+    token: string;
+    transport: AgentChatTransport;
+    /** Display name for agent bubbles; defaults to "Agent". */
+    agentName?: string;
+}
+export interface AgentChatState {
+    connected: boolean;
+    streaming: boolean;
+    messages: AgentChatMessage[];
+    error: string | null;
+}
+export interface AgentChatEvents {
+    connected: undefined;
+    disconnected: undefined;
+    messagesChanged: {
+        messages: AgentChatMessage[];
+    };
+    streamingChanged: {
+        streaming: boolean;
+    };
+    sendFailed: {
+        message: string;
+    };
+    actionResolved: {
+        proposal: AgentActionProposal;
+        decision: AgentActionDecision;
+    };
+}

package/dist/patterns/agent-chat/types.js

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

package/dist/patterns/audit/activity-density.d.ts

@@ -0,0 +1,68 @@
+import type { ActivityDensity, AuditEvent } from "./types.js";
+import { BaseElement } from "../../core/index.js";
+/**
+ * The managerial companion to `box-audit-log`: a calendar heatmap of event
+ * volume per UTC day over a trailing window, for spotting throughput and
+ * quiet periods at a glance.
+ *
+ * Days with activity are buttons in a roving-tabindex grid (arrow keys move
+ * by day and by week, Home/End jump to the ends of the window), each labelled
+ * with its own count and date so the surface is understandable without the
+ * colour. Selecting one emits `day-selected` with that day's events — the
+ * drill-down into the log.
+ */
+export declare class ActivityDensityStrip extends BaseElement {
+    static readonly tagName: string;
+    static get observedAttributes(): string[];
+    private titleEl;
+    private gridEl;
+    private captionEl;
+    private monthsRowEl;
+    private rowsEl;
+    private signature;
+    /** Roving focus position, `week:weekday`. Null until the first render. */
+    private activeKey;
+    private renderedWeeks;
+    /** Raw `events` attribute the parse cache was built from. */
+    private eventsRaw;
+    private eventsCache;
+    get heading(): string;
+    set heading(value: string);
+    /**
+     * Memoized on the raw attribute for the same reason as `box-audit-log`:
+     * `density`, `eventsOn`, and `update` each read it, and an arrow keypress
+     * must not re-parse the payload. Returns a copy.
+     */
+    get events(): AuditEvent[];
+    set events(value: AuditEvent[]);
+    get weeks(): number;
+    set weeks(value: number);
+    get referenceTime(): string;
+    set referenceTime(value: string);
+    /** The computed window — cells, totals, and the busiest day's count. */
+    get density(): ActivityDensity;
+    /** Every event on the given UTC day, in input order. */
+    eventsOn(date: string): AuditEvent[];
+    private emitDaySelected;
+    private buttons;
+    /**
+     * Buttons oldest → newest. DOM order is weekday-major (the grid renders one
+     * row per weekday), so it is *not* chronological — anything that means
+     * "first" or "last day in the window" has to sort by date.
+     */
+    private buttonsByDate;
+    private buttonAt;
+    /** Walk in one grid direction until a day with activity is found. */
+    private step;
+    private focusButton;
+    /**
+     * A day with activity is a labelled button — that label is the accessible
+     * contract, since colour alone carries no meaning. A quiet day is an inert
+     * cell with a hover title: nothing to drill into, and no extra tab stop.
+     */
+    private cellHtml;
+    private rebuild;
+    protected renderTemplate(): void;
+    protected setupListeners(): void;
+    protected update(): void;
+}