@sansavision/yousaid-react 0.0.0-stage → 0.2.0

package/dist/rooms.d.ts

@@ -0,0 +1,158 @@
+import type { AgentRunView, HumanHandoff, PendingApprovalView, RealtimeStatus, RoomCanvasView, RoomDetail, RoomMemberView, RoomRealtimeEvent } from "@sansavision/yousaid";
+/**
+ * Live Room events over the realtime WebSocket: ordered by sequence, deduped,
+ * resumed from the last processed sequence after reconnects, and rebuilt from
+ * a snapshot when the client fell far behind. Falls back to HTTP catch-up
+ * polling where WebSocket is unavailable.
+ * @experimental
+ */
+export declare function useRoomEvents(roomId: string | null, options?: {
+    onEvent?: (event: RoomRealtimeEvent) => void;
+    pollMs?: number;
+}): {
+    events: RoomRealtimeEvent[];
+    status: RealtimeStatus;
+    lastSequence: number;
+};
+/**
+ * One agent run, polled until it reaches a terminal state, with cancel.
+ * @experimental
+ */
+export declare function useAgentRun(runId: string | null, options?: {
+    pollMs?: number;
+}): {
+    run: AgentRunView | null;
+    loading: boolean;
+    error: string;
+    refresh: () => Promise<AgentRunView | null>;
+    cancel: () => Promise<void>;
+};
+/**
+ * Actions a teammate is reviewing in Rooms you can see. Customers only see that a review is pending.
+ * @experimental
+ */
+export declare function usePendingApprovals(roomId?: string, options?: {
+    pollMs?: number;
+}): {
+    approvals: PendingApprovalView[];
+    loading: boolean;
+    error: string;
+    refresh: () => Promise<void>;
+};
+/**
+ * The customer-visible Room Canvas. Internal fields never reach the SDK.
+ * @experimental
+ */
+export declare function useRoomCanvas(roomId: string | null): {
+    canvas: RoomCanvasView | null;
+    loading: boolean;
+    error: string;
+    refresh: () => Promise<void>;
+};
+/**
+ * Customers in the Room (staff identities are never exposed to the SDK).
+ * @experimental
+ */
+export declare function useRoomMembers(roomId: string | null): {
+    members: RoomMemberView[];
+    memberCount: number;
+    loading: boolean;
+    error: string;
+    refresh: () => Promise<void>;
+};
+/**
+ * "Talk to a person": request, show the acknowledgement and SLA, or withdraw.
+ * @experimental
+ */
+export declare function useRequestHuman(roomId: string | null): {
+    handoff: HumanHandoff | null;
+    active: boolean;
+    pending: boolean;
+    error: string;
+    request: (reason?: string) => Promise<HumanHandoff | null>;
+    withdraw: () => Promise<void>;
+    refresh: () => Promise<void>;
+};
+/** @experimental */
+export type CanvasEntry = {
+    key: string;
+    label: string;
+    kind: "text";
+    value: string;
+} | {
+    key: string;
+    label: string;
+    kind: "list";
+    value: string[];
+} | {
+    key: string;
+    label: string;
+    kind: "pairs";
+    value: Array<[string, string]>;
+};
+/** @experimental */
+export declare const DEFAULT_CANVAS_LABELS: Record<string, string>;
+/**
+ * Turn Canvas content into labeled, renderable entries. Empty fields are skipped; unknown fields keep a readable label.
+ * @experimental
+ */
+export declare function canvasEntries(content: Record<string, unknown>, labels?: Record<string, string>): CanvasEntry[];
+/**
+ * Renders Canvas fields as readable sections, never raw JSON. Themeable through --ys-* variables and className.
+ * @experimental
+ */
+export declare function RoomCanvas({ detail, canvas, labels, className, title, emptyMessage, }: {
+    detail?: Pick<RoomDetail, "canvas">;
+    canvas?: Pick<RoomCanvasView, "content" | "version"> | null;
+    labels?: Record<string, string>;
+    className?: string;
+    title?: string;
+    emptyMessage?: string;
+}): import("react").JSX.Element;
+/** @experimental */
+export type MentionAgent = {
+    alias: string;
+    label: string;
+    description: string;
+};
+/** @experimental */
+export declare const DEFAULT_MENTION_AGENTS: MentionAgent[];
+/** @experimental */
+export declare function filterAgents(agents: MentionAgent[], query: string): MentionAgent[];
+/**
+ * Keyboard model for the mention listbox: returns the next active index, a selection, or a close request.
+ * @experimental
+ */
+export declare function mentionMenuKey(key: string, activeIndex: number, count: number): {
+    activeIndex: number;
+    select?: boolean;
+    close?: boolean;
+    handled: boolean;
+};
+/**
+ * Interactive @agent picker: a filterable listbox with arrow-key, Home/End,
+ * Enter/Tab and Escape handling. Controlled (activeIndex + onActiveIndexChange,
+ * for use inside a composer that keeps focus) or uncontrolled.
+ * @experimental
+ */
+export declare function AgentMentionMenu({ agents, query, onSelect, onClose, activeIndex: controlledIndex, onActiveIndexChange, id, className, }: {
+    agents?: MentionAgent[];
+    query?: string;
+    onSelect?: (agent: MentionAgent) => void;
+    onClose?: () => void;
+    activeIndex?: number;
+    onActiveIndexChange?: (index: number) => void;
+    id?: string;
+    className?: string;
+}): import("react").JSX.Element;
+/**
+ * A persistent, honest way to reach a person. Shows the acknowledgement and expected response time once requested.
+ * @experimental
+ */
+export declare function RequestHumanButton({ roomId, className }: {
+    roomId: string;
+    className?: string;
+}): import("react").JSX.Element;
+/** @experimental */
+export declare const roomAgentStyles = ".ys-canvas{display:grid;gap:8px}.ys-canvas h4{margin:0;font-size:12px;font-weight:750}.ys-canvas dl{margin:0;display:grid;gap:10px}.ys-canvas dt{color:var(--ys-muted,#aaa6b2);font-size:10px;text-transform:uppercase;letter-spacing:.08em}.ys-canvas dd{margin:3px 0 0}.ys-canvas dd p{margin:0}.ys-canvas ul{margin:0;padding-left:18px}.ys-canvas__empty{margin:0;color:var(--ys-muted,#aaa6b2)}.ys-mentions{list-style:none;margin:6px 0 0;padding:4px;border:1px solid var(--ys-line,#2c2b34);border-radius:12px;background:var(--ys-panel,#19191f);max-width:360px}.ys-mentions li{display:grid;gap:2px;padding:8px 10px;border-radius:9px;cursor:pointer}.ys-mentions li.is-active{background:var(--ys-inset,#212129)}.ys-mentions small{color:var(--ys-muted,#aaa6b2)}.ys-mentions--empty{margin:6px 0 0;color:var(--ys-muted,#aaa6b2);font-size:12px}.ys-human{display:grid;gap:6px;margin-top:10px}.ys-human>button,.ys-human form button{justify-self:start;border:1px solid var(--ys-line,#2c2b34);border-radius:10px;background:transparent;color:var(--ys-text,#f4f1eb);padding:8px 11px;font-weight:700;cursor:pointer}.ys-human.is-requested{padding:10px;border-radius:12px;background:#18342c;color:var(--ys-mint,#6eddbb)}.ys-human p{margin:0}.ys-human form{display:grid;gap:8px}.ys-human form span{display:flex;gap:8px}.ys-human textarea{width:100%;min-height:60px;border:1px solid var(--ys-line,#2c2b34);border-radius:10px;background:#0e0e13;color:var(--ys-text,#f4f1eb);padding:8px}";
+//# sourceMappingURL=rooms.d.ts.map

package/dist/rooms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rooms.d.ts","sourceRoot":"","sources":["../src/rooms.tsx"],"names":[],"mappings":"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"}

package/dist/rooms.js

@@ -0,0 +1,442 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useId, useRef, useState, } from "react";
+import { useYouSaid } from "./context.js";
+/* Headless hooks (PRD 12.3). Each hook works without the bundled components. */
+const MAX_EVENTS = 500;
+const TERMINAL_RUN_STATES = new Set(["completed", "failed", "cancelled", "approval_needed"]);
+/**
+ * Live Room events over the realtime WebSocket: ordered by sequence, deduped,
+ * resumed from the last processed sequence after reconnects, and rebuilt from
+ * a snapshot when the client fell far behind. Falls back to HTTP catch-up
+ * polling where WebSocket is unavailable.
+ * @experimental
+ */
+export function useRoomEvents(roomId, options = {}) {
+    const client = useYouSaid();
+    const [events, setEvents] = useState([]);
+    const [status, setStatus] = useState("idle");
+    const [lastSequence, setLastSequence] = useState(0);
+    const onEvent = useRef(options.onEvent);
+    onEvent.current = options.onEvent;
+    useEffect(() => {
+        if (!roomId)
+            return;
+        setEvents([]);
+        setLastSequence(0);
+        const handlers = {
+            onEvent: (event) => {
+                setEvents((current) => [...current, event].slice(-MAX_EVENTS));
+                setLastSequence(event.sequence);
+                onEvent.current?.(event);
+            },
+            onSnapshot: (snapshot) => {
+                setEvents(snapshot.events.slice(-MAX_EVENTS));
+                setLastSequence(snapshot.sequence);
+            },
+            onStatus: setStatus,
+        };
+        const realtime = client.realtime(roomId, handlers);
+        if (typeof globalThis.WebSocket === "function") {
+            realtime.start();
+            return () => realtime.stop();
+        }
+        let stopped = false;
+        let timer;
+        const poll = async () => {
+            try {
+                let page = await client.roomEvents(roomId, realtime.lastSequence);
+                realtime.ingest(page);
+                while (page.hasMore && !stopped) {
+                    page = await client.roomEvents(roomId, page.nextSequence);
+                    realtime.ingest(page);
+                }
+                setStatus("open");
+            }
+            catch {
+                setStatus("reconnecting");
+            }
+            if (!stopped)
+                timer = setTimeout(poll, options.pollMs ?? 5_000);
+        };
+        void poll();
+        return () => {
+            stopped = true;
+            if (timer)
+                clearTimeout(timer);
+        };
+    }, [client, roomId, options.pollMs]);
+    return { events, status, lastSequence };
+}
+/**
+ * One agent run, polled until it reaches a terminal state, with cancel.
+ * @experimental
+ */
+export function useAgentRun(runId, options = {}) {
+    const client = useYouSaid();
+    const [run, setRun] = useState(null);
+    const [error, setError] = useState("");
+    const [loading, setLoading] = useState(Boolean(runId));
+    const refresh = useCallback(async () => {
+        if (!runId)
+            return null;
+        try {
+            const next = await client.getAgentRun(runId);
+            setRun(next);
+            setError("");
+            return next;
+        }
+        catch (reason) {
+            setError(reason instanceof Error ? reason.message : "The agent run is unavailable.");
+            return null;
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [client, runId]);
+    useEffect(() => {
+        if (!runId) {
+            setRun(null);
+            setLoading(false);
+            return;
+        }
+        let stopped = false;
+        let timer;
+        const tick = async () => {
+            const next = await refresh();
+            if (!stopped && (!next || !TERMINAL_RUN_STATES.has(next.status)))
+                timer = setTimeout(tick, options.pollMs ?? 1_500);
+        };
+        setLoading(true);
+        void tick();
+        return () => { stopped = true; if (timer)
+            clearTimeout(timer); };
+    }, [runId, refresh, options.pollMs]);
+    const cancel = useCallback(async () => {
+        if (!runId)
+            return;
+        try {
+            setRun(await client.cancelAgentRun(runId));
+        }
+        catch (reason) {
+            setError(reason instanceof Error ? reason.message : "The run could not be cancelled.");
+        }
+    }, [client, runId]);
+    return { run, loading, error, refresh, cancel };
+}
+/**
+ * Actions a teammate is reviewing in Rooms you can see. Customers only see that a review is pending.
+ * @experimental
+ */
+export function usePendingApprovals(roomId, options = {}) {
+    const client = useYouSaid();
+    const [approvals, setApprovals] = useState([]);
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState("");
+    const refresh = useCallback(async () => {
+        try {
+            setApprovals(await client.listPendingApprovals(roomId));
+            setError("");
+        }
+        catch (reason) {
+            setError(reason instanceof Error ? reason.message : "Approvals could not be loaded.");
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [client, roomId]);
+    useEffect(() => {
+        void refresh();
+        if (!options.pollMs)
+            return;
+        const timer = setInterval(() => void refresh(), options.pollMs);
+        return () => clearInterval(timer);
+    }, [refresh, options.pollMs]);
+    return { approvals, loading, error, refresh };
+}
+/**
+ * The customer-visible Room Canvas. Internal fields never reach the SDK.
+ * @experimental
+ */
+export function useRoomCanvas(roomId) {
+    const client = useYouSaid();
+    const [canvas, setCanvas] = useState(null);
+    const [loading, setLoading] = useState(Boolean(roomId));
+    const [error, setError] = useState("");
+    const refresh = useCallback(async () => {
+        if (!roomId) {
+            setCanvas(null);
+            setLoading(false);
+            return;
+        }
+        setLoading(true);
+        try {
+            setCanvas(await client.getRoomCanvas(roomId));
+            setError("");
+        }
+        catch (reason) {
+            setError(reason instanceof Error ? reason.message : "The Canvas could not be loaded.");
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [client, roomId]);
+    useEffect(() => { void refresh(); }, [refresh]);
+    return { canvas, loading, error, refresh };
+}
+/**
+ * Customers in the Room (staff identities are never exposed to the SDK).
+ * @experimental
+ */
+export function useRoomMembers(roomId) {
+    const client = useYouSaid();
+    const [members, setMembers] = useState([]);
+    const [memberCount, setMemberCount] = useState(0);
+    const [loading, setLoading] = useState(Boolean(roomId));
+    const [error, setError] = useState("");
+    const refresh = useCallback(async () => {
+        if (!roomId) {
+            setMembers([]);
+            setMemberCount(0);
+            setLoading(false);
+            return;
+        }
+        setLoading(true);
+        try {
+            const result = await client.listRoomMembers(roomId);
+            setMembers(result.members);
+            setMemberCount(result.memberCount);
+            setError("");
+        }
+        catch (reason) {
+            setError(reason instanceof Error ? reason.message : "Members could not be loaded.");
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [client, roomId]);
+    useEffect(() => { void refresh(); }, [refresh]);
+    return { members, memberCount, loading, error, refresh };
+}
+/**
+ * "Talk to a person": request, show the acknowledgement and SLA, or withdraw.
+ * @experimental
+ */
+export function useRequestHuman(roomId) {
+    const client = useYouSaid();
+    const [handoff, setHandoff] = useState(null);
+    const [pending, setPending] = useState(false);
+    const [error, setError] = useState("");
+    const refresh = useCallback(async () => {
+        if (!roomId) {
+            setHandoff(null);
+            return;
+        }
+        try {
+            setHandoff(await client.getHumanHandoff(roomId));
+        }
+        catch { /* the button stays available; a request surfaces its own error */ }
+    }, [client, roomId]);
+    useEffect(() => { void refresh(); }, [refresh]);
+    const request = useCallback(async (reason = "") => {
+        if (!roomId)
+            return null;
+        setPending(true);
+        setError("");
+        try {
+            const next = await client.requestHuman(roomId, reason);
+            setHandoff(next);
+            return next;
+        }
+        catch (reason) {
+            setError(reason instanceof Error ? reason.message : "Your request could not be sent. Try again.");
+            return null;
+        }
+        finally {
+            setPending(false);
+        }
+    }, [client, roomId]);
+    const withdraw = useCallback(async () => {
+        if (!roomId)
+            return;
+        setPending(true);
+        setError("");
+        try {
+            await client.withdrawHumanHandoff(roomId);
+            setHandoff(null);
+        }
+        catch (reason) {
+            setError(reason instanceof Error ? reason.message : "The request could not be withdrawn.");
+        }
+        finally {
+            setPending(false);
+        }
+    }, [client, roomId]);
+    return { handoff, active: Boolean(handoff && (handoff.status === "open" || handoff.status === "acknowledged")), pending, error, request, withdraw, refresh };
+}
+/** @experimental */
+export const DEFAULT_CANVAS_LABELS = {
+    purpose: "Why this Room exists",
+    outcome: "Done means",
+    currentState: "Where things stand",
+    confirmedFacts: "Confirmed",
+    hypotheses: "Working theories",
+    openQuestions: "Open questions",
+    affected: "Who is affected",
+    decisions: "Decisions",
+    promises: "Commitments",
+    actions: "Next actions",
+    release: "Release",
+    verification: "Verification",
+    canonicalAnswer: "Answer",
+};
+const CANVAS_ORDER = Object.keys(DEFAULT_CANVAS_LABELS);
+function humanize(key) {
+    const spaced = key.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/[_-]+/g, " ").trim().toLowerCase();
+    return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+}
+function itemText(value) {
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    if (value && typeof value === "object") {
+        const record = value;
+        const primary = record.title ?? record.statement ?? record.text ?? record.summary ?? record.name;
+        if (typeof primary === "string") {
+            const status = typeof record.status === "string" ? ` (${record.status.replaceAll("_", " ")})` : "";
+            return `${primary}${status}`;
+        }
+        return Object.entries(record).filter(([, item]) => item !== null && item !== undefined && item !== "").map(([key, item]) => `${humanize(key)}: ${itemText(item)}`).join(", ");
+    }
+    return "";
+}
+/**
+ * Turn Canvas content into labeled, renderable entries. Empty fields are skipped; unknown fields keep a readable label.
+ * @experimental
+ */
+export function canvasEntries(content, labels = {}) {
+    const merged = { ...DEFAULT_CANVAS_LABELS, ...labels };
+    const keys = [...CANVAS_ORDER.filter((key) => key in content), ...Object.keys(content).filter((key) => !CANVAS_ORDER.includes(key) && key !== "fieldVisibility").sort()];
+    const entries = [];
+    for (const key of keys) {
+        const value = content[key];
+        const label = merged[key] ?? humanize(key);
+        if (value === null || value === undefined || value === "")
+            continue;
+        if (Array.isArray(value)) {
+            const items = value.map(itemText).filter(Boolean);
+            if (items.length)
+                entries.push({ key, label, kind: "list", value: items });
+            continue;
+        }
+        if (typeof value === "object") {
+            const record = value;
+            if (key === "verification") {
+                if (record.attempted !== true && !record.result)
+                    continue;
+                entries.push({ key, label, kind: "text", value: record.attempted === true ? `Checked${record.result ? `: ${String(record.result).replaceAll("_", " ")}` : ""}${typeof record.note === "string" && record.note ? `. ${record.note}` : ""}` : String(record.result) });
+                continue;
+            }
+            const pairs = Object.entries(record).filter(([, item]) => item !== null && item !== undefined && item !== "").map(([name, item]) => [humanize(name), itemText(item)]).filter(([, item]) => item);
+            if (pairs.length)
+                entries.push({ key, label, kind: "pairs", value: pairs });
+            continue;
+        }
+        entries.push({ key, label, kind: "text", value: itemText(value) });
+    }
+    return entries;
+}
+/**
+ * Renders Canvas fields as readable sections, never raw JSON. Themeable through --ys-* variables and className.
+ * @experimental
+ */
+export function RoomCanvas({ detail, canvas, labels, className = "", title = "Room outcome", emptyMessage = "The team has not filled in the Canvas yet.", }) {
+    const content = canvas?.content ?? detail?.canvas?.content ?? {};
+    const version = canvas?.version ?? detail?.canvas?.version;
+    const entries = canvasEntries(content, labels);
+    const headingId = useId();
+    return (_jsxs("section", { className: `ys-canvas ${className}`.trim(), "aria-labelledby": headingId, "data-canvas-version": version ?? undefined, children: [_jsx("h4", { id: headingId, children: title }), entries.length ? (_jsx("dl", { children: entries.map((entry) => (_jsxs("div", { "data-canvas-field": entry.key, children: [_jsx("dt", { children: entry.label }), _jsx("dd", { children: entry.kind === "text" ? (_jsx("p", { children: entry.value })) : entry.kind === "list" ? (_jsx("ul", { children: entry.value.map((item, index) => _jsx("li", { children: item }, `${entry.key}-${index}`)) })) : (_jsx("ul", { children: entry.value.map(([name, item]) => _jsxs("li", { children: [_jsx("strong", { children: name }), " ", item] }, `${entry.key}-${name}`)) })) })] }, entry.key))) })) : (_jsx("p", { className: "ys-canvas__empty", children: emptyMessage }))] }));
+}
+/** @experimental */
+export const DEFAULT_MENTION_AGENTS = [
+    { alias: "support", label: "@support", description: "Answers from approved help and this Room" },
+    { alias: "product", label: "@product", description: "Summarizes needs, trade-offs and open questions" },
+    { alias: "incident", label: "@incident", description: "Structures what is known about an outage or bug" },
+];
+/** @experimental */
+export function filterAgents(agents, query) {
+    const needle = query.trim().toLowerCase().replace(/^@/, "");
+    return agents.filter((agent) => !needle || agent.alias.startsWith(needle) || agent.label.toLowerCase().includes(needle));
+}
+/**
+ * Keyboard model for the mention listbox: returns the next active index, a selection, or a close request.
+ * @experimental
+ */
+export function mentionMenuKey(key, activeIndex, count) {
+    if (!count)
+        return { activeIndex: 0, handled: key === "Escape", ...(key === "Escape" ? { close: true } : {}) };
+    if (key === "ArrowDown")
+        return { activeIndex: (activeIndex + 1) % count, handled: true };
+    if (key === "ArrowUp")
+        return { activeIndex: (activeIndex - 1 + count) % count, handled: true };
+    if (key === "Home")
+        return { activeIndex: 0, handled: true };
+    if (key === "End")
+        return { activeIndex: count - 1, handled: true };
+    if (key === "Enter" || key === "Tab")
+        return { activeIndex, select: true, handled: true };
+    if (key === "Escape")
+        return { activeIndex, close: true, handled: true };
+    return { activeIndex, handled: false };
+}
+/**
+ * Interactive @agent picker: a filterable listbox with arrow-key, Home/End,
+ * Enter/Tab and Escape handling. Controlled (activeIndex + onActiveIndexChange,
+ * for use inside a composer that keeps focus) or uncontrolled.
+ * @experimental
+ */
+export function AgentMentionMenu({ agents = DEFAULT_MENTION_AGENTS, query = "", onSelect, onClose, activeIndex: controlledIndex, onActiveIndexChange, id, className = "", }) {
+    const generatedId = useId();
+    const listId = id ?? `ys-mentions-${generatedId}`;
+    const matches = filterAgents(agents, query);
+    const [localIndex, setLocalIndex] = useState(0);
+    const activeIndex = Math.min(controlledIndex ?? localIndex, Math.max(0, matches.length - 1));
+    const setIndex = (index) => { setLocalIndex(index); onActiveIndexChange?.(index); };
+    function onKeyDown(event) {
+        const result = mentionMenuKey(event.key, activeIndex, matches.length);
+        if (!result.handled)
+            return;
+        event.preventDefault();
+        if (result.close) {
+            onClose?.();
+            return;
+        }
+        if (result.select && matches[activeIndex]) {
+            onSelect?.(matches[activeIndex]);
+            return;
+        }
+        setIndex(result.activeIndex);
+    }
+    if (!matches.length)
+        return _jsxs("p", { className: `ys-mentions ys-mentions--empty ${className}`.trim(), role: "status", children: ["No agent matches @", query, "."] });
+    return (_jsx("ul", { id: listId, role: "listbox", "aria-label": "Mention an agent", "aria-activedescendant": `${listId}-${matches[activeIndex]?.alias ?? ""}`, tabIndex: 0, className: `ys-mentions ${className}`.trim(), onKeyDown: onKeyDown, children: matches.map((agent, index) => (_jsxs("li", { id: `${listId}-${agent.alias}`, role: "option", "aria-selected": index === activeIndex, className: index === activeIndex ? "is-active" : "", onMouseEnter: () => setIndex(index), onMouseDown: (event) => { event.preventDefault(); onSelect?.(agent); }, children: [_jsx("strong", { children: agent.label }), _jsx("small", { children: agent.description })] }, agent.alias))) }));
+}
+/**
+ * A persistent, honest way to reach a person. Shows the acknowledgement and expected response time once requested.
+ * @experimental
+ */
+export function RequestHumanButton({ roomId, className = "" }) {
+    const human = useRequestHuman(roomId);
+    const [asking, setAsking] = useState(false);
+    const [reason, setReason] = useState("");
+    if (human.active && human.handoff) {
+        return (_jsxs("div", { className: `ys-human is-requested ${className}`.trim(), role: "status", "aria-live": "polite", children: [_jsx("strong", { children: human.handoff.acknowledged ? "A teammate has your request" : "A person has been asked to help" }), _jsx("p", { children: human.handoff.message }), _jsx("button", { type: "button", onClick: () => void human.withdraw(), disabled: human.pending, children: "Withdraw request" }), human.error ? _jsx("p", { role: "alert", children: human.error }) : null] }));
+    }
+    return (_jsxs("div", { className: `ys-human ${className}`.trim(), children: [asking ? (_jsxs("form", { onSubmit: (event) => { event.preventDefault(); void human.request(reason).then((result) => { if (result) {
+                    setAsking(false);
+                    setReason("");
+                } }); }, children: [_jsxs("label", { children: ["What should the team know? (optional)", _jsx("textarea", { value: reason, maxLength: 1_000, onChange: (event) => setReason(event.target.value) })] }), _jsxs("span", { children: [_jsx("button", { type: "submit", disabled: human.pending, children: human.pending ? "Sending…" : "Ask for a person" }), _jsx("button", { type: "button", onClick: () => setAsking(false), children: "Cancel" })] })] })) : (_jsx("button", { type: "button", onClick: () => setAsking(true), "aria-haspopup": "dialog", children: "Talk to a person" })), human.error ? _jsx("p", { role: "alert", children: human.error }) : null] }));
+}
+/** @experimental */
+export const roomAgentStyles = `.ys-canvas{display:grid;gap:8px}.ys-canvas h4{margin:0;font-size:12px;font-weight:750}.ys-canvas dl{margin:0;display:grid;gap:10px}.ys-canvas dt{color:var(--ys-muted,#aaa6b2);font-size:10px;text-transform:uppercase;letter-spacing:.08em}.ys-canvas dd{margin:3px 0 0}.ys-canvas dd p{margin:0}.ys-canvas ul{margin:0;padding-left:18px}.ys-canvas__empty{margin:0;color:var(--ys-muted,#aaa6b2)}.ys-mentions{list-style:none;margin:6px 0 0;padding:4px;border:1px solid var(--ys-line,#2c2b34);border-radius:12px;background:var(--ys-panel,#19191f);max-width:360px}.ys-mentions li{display:grid;gap:2px;padding:8px 10px;border-radius:9px;cursor:pointer}.ys-mentions li.is-active{background:var(--ys-inset,#212129)}.ys-mentions small{color:var(--ys-muted,#aaa6b2)}.ys-mentions--empty{margin:6px 0 0;color:var(--ys-muted,#aaa6b2);font-size:12px}.ys-human{display:grid;gap:6px;margin-top:10px}.ys-human>button,.ys-human form button{justify-self:start;border:1px solid var(--ys-line,#2c2b34);border-radius:10px;background:transparent;color:var(--ys-text,#f4f1eb);padding:8px 11px;font-weight:700;cursor:pointer}.ys-human.is-requested{padding:10px;border-radius:12px;background:#18342c;color:var(--ys-mint,#6eddbb)}.ys-human p{margin:0}.ys-human form{display:grid;gap:8px}.ys-human form span{display:flex;gap:8px}.ys-human textarea{width:100%;min-height:60px;border:1px solid var(--ys-line,#2c2b34);border-radius:10px;background:#0e0e13;color:var(--ys-text,#f4f1eb);padding:8px}`;

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@sansavision/yousaid-react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "React 19 components and hooks for YouSaid: provider, launcher, inbox and lifecycle receipts.",
+  "private": false,
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json"
+  },
+  "peerDependencies": {
+    "react": ">=19"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@sansavision/yousaid": "^0.2.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Sansa-Organisation/yousaid.git",
+    "directory": "packages/react"
+  },
+  "homepage": "https://yousaid.dev/docs/sdk",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}