zidane-ui 0.0.0-stage → 9.0.2

package/dist/chat/interactions/QuestionForm.js

@@ -0,0 +1,213 @@
+import { useChatLabels } from "../useChatLabels.js";
+import { useTranscriptRenderers } from "../transcript/renderers.js";
+import { BTN_GHOST_LEADING, BTN_PRIMARY, CardError, INPUT, useAutoFocus } from "./card-ui.js";
+import { QuestionField, isRequired } from "./QuestionField.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useMemo, useRef, useState } from "react";
+//#region src/chat/interactions/QuestionForm.tsx
+/**
+* `ask_user` as a card (the desktop app's inbox, `InteractionCard`). The canonical `QuestionPayload` as a form:
+* `text`, `textarea`, `select` (single / `multi`, `selected` pre-ticks),
+* `confirm`. The submitted `answers` map goes verbatim to the canonical
+* `serializeInteractionResponse` server-side (main trims / normalises).
+*
+* Layout: optional intro, one card per question, then a permanent
+* "Additional instructions" textarea (sent as `instructions`, omitted when
+* empty) so the user can refine or override the model's framing. Required
+* questions block Send; skipping a non-required text question sends the key
+* absent (the serializer drops empty entries). Parity with the TUI's form:
+* select / confirm are required unless `required: false`, free text is
+* optional unless `required: true`.
+*
+* Two ways out: **Send** answers (`onAnswer`); **Dismiss** (`onDismiss`,
+* shown when given) cancels so the agent moves on without an answer.
+* Leaving the card alone keeps the question pending. Markdown (the intro)
+* draws through the transcript's `Markdown` slot unless `Markdown` is passed.
+*/
+/**
+* Renders an `ask_user` request as a form: an optional intro, one card per question, and an "Additional instructions" field. Required questions block Send.
+*
+* @param props - The {@link QuestionFormProps}.
+*/
+function QuestionForm({ request, autoFocus = false, onAnswer, onDismiss, Markdown: MarkdownProp, className, style }) {
+	const labels = useChatLabels();
+	const slots = useTranscriptRenderers();
+	const Markdown = MarkdownProp ?? slots.Markdown;
+	const payload = request.payload;
+	const [answers, setAnswers] = useState(() => seedDefaults(payload));
+	const [instructions, setInstructions] = useState("");
+	const [busy, setBusy] = useState(false);
+	const [error, setError] = useState(null);
+	const rootRef = useRef(null);
+	useAutoFocus(rootRef, autoFocus);
+	const canSubmit = useMemo(() => payload.questions.every((q) => {
+		if (!isRequired(q)) return true;
+		const value = answers[q.id];
+		if (q.type === "confirm") return typeof value === "boolean";
+		if (q.type === "select" && q.multi) return Array.isArray(value) && value.length > 0;
+		return typeof value === "string" && value.trim().length > 0;
+	}), [answers, payload.questions]);
+	const submit = async () => {
+		if (busy || !canSubmit) return;
+		setBusy(true);
+		setError(null);
+		try {
+			await onAnswer({
+				kind: "question",
+				answers,
+				...instructions.trim() ? { instructions: instructions.trim() } : {}
+			});
+		} catch (err) {
+			setError(err.message ?? String(err));
+			setBusy(false);
+		}
+	};
+	/** Explicit dismissal: the agent is told there is no answer and continues. */
+	const dismiss = async () => {
+		if (busy || !onDismiss) return;
+		setBusy(true);
+		setError(null);
+		try {
+			await onDismiss();
+		} catch (err) {
+			setError(err.message ?? String(err));
+			setBusy(false);
+		}
+	};
+	const setAnswer = (id, value) => setAnswers((prev) => ({
+		...prev,
+		[id]: value
+	}));
+	return /* @__PURE__ */ jsxs("div", {
+		ref: rootRef,
+		role: "presentation",
+		className: ["flex flex-col gap-3", className].filter(Boolean).join(" "),
+		style,
+		onKeyDown: (e) => {
+			if (e.key === "Enter" && (e.metaKey || e.ctrlKey)) {
+				e.preventDefault();
+				submit();
+			}
+		},
+		children: [
+			payload.intro && /* @__PURE__ */ jsx("div", {
+				className: "prose-styles text-zg-ui text-[var(--zg-text)] zg-pretty",
+				children: /* @__PURE__ */ jsx(Markdown, { children: payload.intro })
+			}),
+			payload.questions.map((q, index) => /* @__PURE__ */ jsx(QuestionField, {
+				index,
+				question: q,
+				value: answers[q.id],
+				onChange: (v) => setAnswer(q.id, v),
+				requestId: request.id,
+				labels
+			}, q.id)),
+			/* @__PURE__ */ jsxs("div", {
+				className: "flex flex-col gap-1.5",
+				children: [/* @__PURE__ */ jsxs("div", {
+					className: "flex items-baseline gap-1.5",
+					children: [/* @__PURE__ */ jsx("label", {
+						htmlFor: `ask-${request.id}-instructions`,
+						className: "text-zg-label font-medium text-[var(--zg-text-muted)]",
+						children: labels.additionalInstructions
+					}), /* @__PURE__ */ jsx("span", {
+						className: "text-zg-meta text-[var(--zg-text-muted)]",
+						children: labels.additionalInstructionsHint
+					})]
+				}), /* @__PURE__ */ jsx("textarea", {
+					id: `ask-${request.id}-instructions`,
+					value: instructions,
+					onChange: (e) => setInstructions(e.target.value),
+					placeholder: labels.additionalInstructionsPlaceholder,
+					rows: 2,
+					spellCheck: false,
+					className: `${INPUT} min-h-14 py-2 resize-y`
+				})]
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "flex items-center gap-2 pt-1",
+				children: [
+					onDismiss && /* @__PURE__ */ jsx("button", {
+						type: "button",
+						onClick: () => void dismiss(),
+						disabled: busy,
+						title: labels.dismissHint,
+						className: BTN_GHOST_LEADING,
+						children: labels.dismiss
+					}),
+					/* @__PURE__ */ jsx(CardError, { error }),
+					/* @__PURE__ */ jsx("span", { className: "flex-1" }),
+					/* @__PURE__ */ jsx("button", {
+						type: "button",
+						onClick: () => void submit(),
+						disabled: busy || !canSubmit,
+						className: BTN_PRIMARY,
+						"data-testid": "inbox-send",
+						children: labels.sendAnswers(payload.questions.length)
+					})
+				]
+			})
+		]
+	});
+}
+/**
+* An answered `ask_user` form, read-only: the same intro and question cards
+* as the live form, each showing what was picked or typed, then the
+* additional instructions when some were given. Used by the transcript
+* (the call's details), so an answer reads the way it was given.
+*
+* @param props - Component props: the `payload` that was asked, the `answers`, optional `instructions`, a unique `id`, and an optional `Markdown` renderer.
+*/
+function AnsweredQuestions({ payload, answers, instructions, id, Markdown: MarkdownProp, className, style }) {
+	const labels = useChatLabels();
+	const slots = useTranscriptRenderers();
+	const Markdown = MarkdownProp ?? slots.Markdown;
+	return /* @__PURE__ */ jsxs("div", {
+		className: ["flex flex-col gap-3", className].filter(Boolean).join(" "),
+		style,
+		children: [
+			payload.intro && /* @__PURE__ */ jsx("div", {
+				className: "prose-styles text-zg-ui text-[var(--zg-text)] zg-pretty",
+				children: /* @__PURE__ */ jsx(Markdown, { children: payload.intro })
+			}),
+			payload.questions.map((q, index) => /* @__PURE__ */ jsx(QuestionField, {
+				index,
+				question: q,
+				value: answers[q.id],
+				onChange: () => void 0,
+				requestId: id,
+				labels,
+				readOnly: true
+			}, q.id)),
+			instructions && instructions.trim() !== "" && /* @__PURE__ */ jsxs("div", {
+				className: "flex flex-col gap-1",
+				children: [/* @__PURE__ */ jsx("span", {
+					className: "text-zg-label font-medium text-[var(--zg-text-muted)]",
+					children: labels.additionalInstructions
+				}), /* @__PURE__ */ jsx("div", {
+					className: "text-zg-ui leading-5 text-[var(--zg-text)] whitespace-pre-wrap zg-pretty",
+					children: instructions
+				})]
+			})
+		]
+	});
+}
+/**
+* Seed the form from the payload: `default` for free text, `selected`
+* pre-ticks for multi-select (an opt-out list arrives already ticked).
+*
+* @param payload - The question payload to read defaults from.
+*/
+function seedDefaults(payload) {
+	const out = {};
+	for (const q of payload.questions) {
+		if ((q.type === "text" || q.type === "textarea") && q.default) out[q.id] = q.default;
+		if (q.type === "select" && q.multi) {
+			const ticked = q.choices.filter((c) => c.selected).map((c) => c.id);
+			if (ticked.length > 0) out[q.id] = ticked;
+		}
+	}
+	return out;
+}
+//#endregion
+export { AnsweredQuestions, QuestionForm, isRequired, seedDefaults };

package/dist/chat/interactions/card-ui.d.ts

@@ -0,0 +1,40 @@
+import { CSSProperties, RefObject } from "react";
+//#region src/chat/interactions/card-ui.d.ts
+/** Class names of a secondary button in an interaction card. */
+declare const BTN: string;
+/** Class names of the primary (solid) button in an interaction card. */
+declare const BTN_PRIMARY: string;
+/** Class names of a ghost button in an interaction card. */
+declare const BTN_GHOST: string;
+/** A ghost button that leads a footer: pulled out by its padding so its text sits on the card's content edge. */
+declare const BTN_GHOST_LEADING: string;
+/** Class names of the danger button in an interaction card: the danger fill. */
+declare const BTN_DANGER: string;
+/** Class names of a text field in an interaction card. */
+declare const INPUT = "zg-well w-full text-zg-ui px-2.5 placeholder:text-[var(--zg-text-subtle)]";
+/** Props for {@link CardError}. */
+interface CardErrorProps {
+  /** The message to show, or `null` to render nothing. */
+  error: string | null;
+  /** Extra classes on the root element. */
+  className?: string;
+  /** Inline styles on the root element, merged after the component's own. */
+  style?: CSSProperties;
+}
+/**
+ * Renders an inline error message, or nothing when there is none.
+ *
+ * @param props - Component props: the `error` text.
+ */
+declare function CardError({ error, className, style }: CardErrorProps): import("react").JSX.Element | null;
+/**
+ * Move keyboard focus to the card's first focusable control when asked
+ * (the card became the head, or the user came through "Open inbox").
+ * `preventScroll`: the panel body scrolls the card into view itself.
+ *
+ * @param root - Ref to the card's root element.
+ * @param when - Focuses the first control when it turns true.
+ */
+declare function useAutoFocus(root: RefObject<HTMLElement | null>, when: boolean): void;
+//#endregion
+export { BTN, BTN_DANGER, BTN_GHOST, BTN_GHOST_LEADING, BTN_PRIMARY, CardError, CardErrorProps, INPUT, useAutoFocus };

package/dist/chat/interactions/card-ui.js

@@ -0,0 +1,63 @@
+import { buttonClass } from "../../components/button.js";
+import { jsx } from "react/jsx-runtime";
+import { useEffect, useRef } from "react";
+//#region src/chat/interactions/card-ui.tsx
+/**
+* Shared controls for the interaction cards (a question form, a plan
+* review), wherever they show: the desktop app's inbox, `HostInteractions`.
+* Button and field classes, the inline error, first-control focus.
+*/
+/** Class names of a secondary button in an interaction card. */
+const BTN = `${buttonClass({ variant: "secondary" })} !text-[var(--zg-text)] font-medium`;
+/** Class names of the primary (solid) button in an interaction card. */
+const BTN_PRIMARY = buttonClass({ variant: "solid" });
+/** Class names of a ghost button in an interaction card. */
+const BTN_GHOST = buttonClass({ variant: "ghost" });
+/** A ghost button that leads a footer: pulled out by its padding so its text sits on the card's content edge. */
+const BTN_GHOST_LEADING = buttonClass({
+	variant: "ghost",
+	flush: "start"
+});
+/** Class names of the danger button in an interaction card: the danger fill. */
+const BTN_DANGER = buttonClass({ variant: "danger-solid" });
+/** Class names of a text field in an interaction card. */
+const INPUT = "zg-well w-full text-zg-ui px-2.5 placeholder:text-[var(--zg-text-subtle)]";
+/**
+* Renders an inline error message, or nothing when there is none.
+*
+* @param props - Component props: the `error` text.
+*/
+function CardError({ error, className, style }) {
+	if (!error) return null;
+	return /* @__PURE__ */ jsx("span", {
+		role: "alert",
+		className: ["min-w-0 truncate text-zg-meta text-[var(--zg-error)]", className].filter(Boolean).join(" "),
+		style,
+		title: error,
+		children: error
+	});
+}
+/**
+* Move keyboard focus to the card's first focusable control when asked
+* (the card became the head, or the user came through "Open inbox").
+* `preventScroll`: the panel body scrolls the card into view itself.
+*
+* @param root - Ref to the card's root element.
+* @param when - Focuses the first control when it turns true.
+*/
+function useAutoFocus(root, when) {
+	const pending = useRef(null);
+	useEffect(() => {
+		if (!when) return;
+		pending.current = requestAnimationFrame(() => {
+			pending.current = null;
+			(root.current?.querySelector("[data-autofocus]") ?? root.current?.querySelector("input, textarea, [role=\"radio\"]:not([tabindex=\"-1\"]), [role=\"checkbox\"], button:not([disabled])"))?.focus({ preventScroll: true });
+			root.current?.scrollIntoView({ block: "nearest" });
+		});
+	}, [root, when]);
+	useEffect(() => () => {
+		if (pending.current !== null) cancelAnimationFrame(pending.current);
+	}, []);
+}
+//#endregion
+export { BTN, BTN_DANGER, BTN_GHOST, BTN_GHOST_LEADING, BTN_PRIMARY, CardError, INPUT, useAutoFocus };

package/dist/chat/interactions/hooks.d.ts

@@ -0,0 +1,19 @@
+import { ChatInteraction } from "../headless/host.js";
+//#region src/chat/interactions/hooks.d.ts
+/**
+ * One session's pending requests, oldest first; empty for no session or a host without interactions.
+ *
+ * @param sessionId - The session, or `null`.
+ */
+declare function usePendingInteractions(sessionId: string | null): readonly ChatInteraction[];
+/**
+ * The oldest pending request of one session, or `null`. Re-renders only when that request changes, not when more queue
+ * behind it (a sidebar dot reads it per row).
+ *
+ * @param sessionId - The session, or `null`.
+ */
+declare function useInteractionHead(sessionId: string | null): ChatInteraction | null;
+/** Every session's pending requests, in arrival order; empty when the host only lists them per session. */
+declare function useAllInteractions(): readonly ChatInteraction[];
+//#endregion
+export { useAllInteractions, useInteractionHead, usePendingInteractions };

package/dist/chat/interactions/hooks.js

@@ -0,0 +1,40 @@
+import { constant, useReadable } from "../headless/store.js";
+import { useOptionalChatHost } from "../ChatProvider.js";
+import { useCallback, useMemo, useSyncExternalStore } from "react";
+//#region src/chat/interactions/hooks.ts
+/**
+* Readers of the requests the agent waits on (`ChatHost.interactions`):
+* one session's, its head (the oldest), and every session's. Each re-renders
+* only for what it returns.
+*/
+const NONE = constant([]);
+/**
+* One session's pending requests, oldest first; empty for no session or a host without interactions.
+*
+* @param sessionId - The session, or `null`.
+*/
+function usePendingInteractions(sessionId) {
+	const interactions = useOptionalChatHost()?.interactions;
+	const store = useMemo(() => interactions && sessionId ? interactions.pending(sessionId) : NONE, [interactions, sessionId]);
+	return useReadable(store);
+}
+/**
+* The oldest pending request of one session, or `null`. Re-renders only when that request changes, not when more queue
+* behind it (a sidebar dot reads it per row).
+*
+* @param sessionId - The session, or `null`.
+*/
+function useInteractionHead(sessionId) {
+	const interactions = useOptionalChatHost()?.interactions;
+	const store = useMemo(() => interactions && sessionId ? interactions.pending(sessionId) : NONE, [interactions, sessionId]);
+	const head = useCallback(() => store.get()[0] ?? null, [store]);
+	return useSyncExternalStore(store.subscribe, head, head);
+}
+/** Every session's pending requests, in arrival order; empty when the host only lists them per session. */
+function useAllInteractions() {
+	const interactions = useOptionalChatHost()?.interactions;
+	const store = useMemo(() => interactions?.all?.() ?? NONE, [interactions]);
+	return useReadable(store);
+}
+//#endregion
+export { useAllInteractions, useInteractionHead, usePendingInteractions };

package/dist/chat/interactions/index.d.ts

@@ -0,0 +1,8 @@
+import { HostInteractions, HostInteractionsProps } from "./HostInteractions.js";
+import { InboxPanel, InboxPanelProps } from "./InboxPanel.js";
+import { useAllInteractions, useInteractionHead, usePendingInteractions } from "./hooks.js";
+import { InteractionCard, InteractionCardProps } from "./InteractionCard.js";
+import { PlanBody, PlanBodyProps, PlanCard, PlanCardProps } from "./PlanCard.js";
+import { QuestionField, QuestionFieldProps, isRequired } from "./QuestionField.js";
+import { AnsweredQuestions, AnsweredQuestionsProps, QuestionForm, QuestionFormProps, seedDefaults } from "./QuestionForm.js";
+export { AnsweredQuestions, AnsweredQuestionsProps, HostInteractions, HostInteractionsProps, InboxPanel, InboxPanelProps, InteractionCard, InteractionCardProps, PlanBody, PlanBodyProps, PlanCard, PlanCardProps, QuestionField, QuestionFieldProps, QuestionForm, QuestionFormProps, isRequired, seedDefaults, useAllInteractions, useInteractionHead, usePendingInteractions };

package/dist/chat/interactions/index.js

@@ -0,0 +1,8 @@
+import { useAllInteractions, useInteractionHead, usePendingInteractions } from "./hooks.js";
+import { PlanBody, PlanCard } from "./PlanCard.js";
+import { QuestionField, isRequired } from "./QuestionField.js";
+import { AnsweredQuestions, QuestionForm, seedDefaults } from "./QuestionForm.js";
+import { InteractionCard } from "./InteractionCard.js";
+import { HostInteractions } from "./HostInteractions.js";
+import { InboxPanel } from "./InboxPanel.js";
+export { AnsweredQuestions, HostInteractions, InboxPanel, InteractionCard, PlanBody, PlanCard, QuestionField, QuestionForm, isRequired, seedDefaults, useAllInteractions, useInteractionHead, usePendingInteractions };

package/dist/chat/provider-color.d.ts

@@ -0,0 +1,32 @@
+//#region src/chat/provider-color.d.ts
+/**
+ * One stable color per provider, derived from its key so new providers get
+ * a color without a lookup table and the same provider always looks the
+ * same. Well-known providers pin a hue that matches their brand feel; the
+ * rest hash onto the wheel.
+ *
+ * Output is a CSS `hsl()` string at fixed saturation / lightness tuned for
+ * the dark theme: readable as text, and soft when used as a tinted fill via
+ * `color-mix`.
+ */
+/**
+ * The hue (0 to 359) for a provider key: the pinned hue of a well-known provider whose name the key starts with, else a hash of the key.
+ *
+ * @param providerKey - The provider key, matched case-insensitively.
+ */
+declare function providerHue(providerKey: string): number;
+/**
+ * Text / border color.
+ *
+ * @param providerKey - The provider key, matched case-insensitively.
+ */
+declare function providerColor(providerKey: string): string;
+/**
+ * Soft tinted fill for chips / badges.
+ *
+ * @param providerKey - The provider key, matched case-insensitively.
+ * @param percent - How much of the provider color to mix in, 0 to 100.
+ */
+declare function providerTint(providerKey: string, percent?: number): string;
+//#endregion
+export { providerColor, providerHue, providerTint };

package/dist/chat/provider-color.js

@@ -0,0 +1,67 @@
+//#region src/chat/provider-color.ts
+/**
+* One stable color per provider, derived from its key so new providers get
+* a color without a lookup table and the same provider always looks the
+* same. Well-known providers pin a hue that matches their brand feel; the
+* rest hash onto the wheel.
+*
+* Output is a CSS `hsl()` string at fixed saturation / lightness tuned for
+* the dark theme: readable as text, and soft when used as a tinted fill via
+* `color-mix`.
+*/
+const PINNED_HUE = {
+	anthropic: 24,
+	openai: 160,
+	google: 210,
+	gemini: 210,
+	xai: 0,
+	mistral: 30,
+	groq: 300,
+	openrouter: 265,
+	deepseek: 230,
+	ollama: 120,
+	local: 120,
+	together: 190,
+	fireworks: 12,
+	bedrock: 40,
+	azure: 205,
+	vertex: 215
+};
+function hashHue(key) {
+	let h = 2166136261;
+	for (let i = 0; i < key.length; i++) {
+		h ^= key.charCodeAt(i);
+		h = Math.imul(h, 16777619);
+	}
+	return Math.abs(h) % 360;
+}
+/**
+* The hue (0 to 359) for a provider key: the pinned hue of a well-known provider whose name the key starts with, else a hash of the key.
+*
+* @param providerKey - The provider key, matched case-insensitively.
+*/
+function providerHue(providerKey) {
+	const k = providerKey.toLowerCase();
+	const pinned = Object.entries(PINNED_HUE).find(([name]) => k.startsWith(name));
+	return pinned ? pinned[1] : hashHue(k);
+}
+/**
+* Text / border color.
+*
+* @param providerKey - The provider key, matched case-insensitively.
+*/
+function providerColor(providerKey) {
+	const hue = providerHue(providerKey);
+	return `hsl(${hue} ${hue < 15 || hue > 345 ? 55 : 62}% 66%)`;
+}
+/**
+* Soft tinted fill for chips / badges.
+*
+* @param providerKey - The provider key, matched case-insensitively.
+* @param percent - How much of the provider color to mix in, 0 to 100.
+*/
+function providerTint(providerKey, percent = 16) {
+	return `color-mix(in srgb, ${providerColor(providerKey)} ${percent}%, transparent)`;
+}
+//#endregion
+export { providerColor, providerHue, providerTint };

package/dist/chat/rich-composer/MentionList.d.ts

@@ -0,0 +1,49 @@
+//#region src/chat/rich-composer/MentionList.d.ts
+interface MentionItem {
+  id: string;
+  label: string;
+  description?: string;
+  /** A short value at the row's end (`12 messages`). */
+  meta?: string;
+  /**
+   * `/` popover only — distinguishes extension commands and their
+   * argument suggestions from skill mentions. Commands insert plain
+   * text (`insertText`) instead of an atomic mention node so the user
+   * keeps typing arguments after selection.
+   */
+  kind?: 'command' | 'command-arg';
+  /** Full replacement text for the suggestion range (commands / args). */
+  insertText?: string;
+  /**
+   * Provider section stamped by the canonical `mergeSuggestions`
+   * ("Commands" / "Skills"). Consecutive items sharing a section group
+   * under one section label, mirroring the TUI's `── Commands ──`
+   * separator rows. Labels are chrome: keyboard navigation walks items only.
+   */
+  section?: string;
+}
+type MentionKind = 'files' | 'skills' | 'extensions' | 'chats';
+interface Props {
+  items: MentionItem[];
+  command: (item: MentionItem) => void;
+  query: string;
+  kind?: MentionKind;
+  /** The Tab hint (`#` chats: the scope Tab switches to). */
+  scopeLabel?: string;
+}
+interface MentionListRef {
+  /**
+   * ↑ / ↓ / Enter / Tab over `items`, the list the renderer has right now
+   * (the rendered props trail it by a frame); `pick` inserts the choice.
+   * The renderer only calls this while the list shows items, so Enter is
+   * always taken.
+   */
+  onKeyDown: (props: {
+    event: KeyboardEvent;
+    items: MentionItem[];
+    pick: (item: MentionItem) => void;
+  }) => boolean;
+}
+declare const MentionList: import("react").ForwardRefExoticComponent<Props & import("react").RefAttributes<MentionListRef>>;
+//#endregion
+export { MentionItem, MentionKind, MentionList, MentionListRef };