@djangocfg/widget-chat 0.1.1

package/src/i18n/locales/zh.ts

@@ -0,0 +1,83 @@
+import type { ChatCopy } from "../types";
+
+export const zh: ChatCopy = {
+  transcript: {
+    empty: "暂无消息。",
+    suggestionsLabel: "推荐提问",
+    log: "对话",
+    announceStreaming: "助手正在回复",
+    announceComplete: "回复完成",
+    jumpToLatest: "跳到最新",
+    thinking: "思考中",
+    thinkingElapsed: "{{seconds}} 秒",
+    today: "今天",
+    yesterday: "昨天",
+  },
+  message: {
+    copy: "复制",
+    reply: "回复",
+    copyLink: "复制链接",
+    copiedLink: "链接已复制",
+    jumpToQuoted: "跳转到引用的消息",
+    copied: "已复制",
+    reasoning: "推理",
+    reasoningLive: "推理中…",
+    reasoningTokens: {
+      other: "思考了 {{count}} 个 token",
+    },
+    showMore: "展开",
+    showLess: "收起",
+  },
+  tool: {
+    inputStreaming: "准备中",
+    inputAvailable: "运行中",
+    outputAvailable: "完成",
+    outputError: "失败",
+    collapse: "收起工具调用",
+    expand: "展开工具调用",
+  },
+  composer: {
+    replyClear: "取消回复",
+    input: "消息",
+    placeholder: "问我任何问题",
+    send: "发送",
+    sendShortcut: "按 Enter 发送",
+    stop: "停止",
+    toolsMenu: "工具",
+    toolsSearch: "查找工具…",
+    toolsEmpty: "没有该工具",
+    toolsRecent: "最近使用",
+    toolsForget: "从最近使用中移除",
+    toolRemove: "移除工具",
+    needsFile: "请附上文件",
+    needsSkill: "请说明技能",
+    toolsPicked: "已选工具",
+    thinkOn: "深入思考（更慢、成本更高）",
+    thinkOff: "关闭深入思考",
+  },
+  queue: {
+    prompts: { other: "{{count}} 条消息排队中" },
+    more: { other: "还有 {{count}} 条" },
+    showLess: "收起",
+    remove: "从队列中移除",
+    show: "显示队列",
+    edit: "编辑此提示",
+    send: "立即发送",
+    sendNow: "立即发送，并停止当前回复",
+    sendNowConfirmTitle: "立即发送这条消息？",
+    sendNowConfirmMessage:
+      "当前回复会停止，未完成的工作将丢失。队列中的其余消息保持原有顺序。",
+    replaceDraftTitle: "替换已输入的内容？",
+    replaceDraftMessage:
+      "草稿与这条消息不同。请选择保留哪一个。",
+  },
+  voice: {
+    start: "语音输入",
+    stop: "停止语音输入",
+    language: "语音输入语言",
+    languageMenu: "语音输入语言",
+    languageSearch: "搜索语言",
+    languageEmpty: "未找到语言",
+    languageBack: "返回",
+  },
+};

package/src/i18n/plural.ts

@@ -0,0 +1,62 @@
+import type { PluralCopy } from "./types";
+
+/**
+ * Fill `{{name}}` placeholders.
+ *
+ * The dictionary is plain strings, so there is no interpolator behind it. A
+ * template literal at each call site would put copy assembly back into JSX,
+ * which is the seam this package's i18n exists to close.
+ */
+export function fill(
+  template: string,
+  values: Readonly<Record<string, string | number>>,
+): string {
+  return template.replace(/\{\{(\w+)\}\}/g, (match, key: string) => {
+    const value = values[key];
+    return value === undefined ? match : String(value);
+  });
+}
+
+/**
+ * One `Intl.PluralRules` per language, kept for the life of the tab.
+ *
+ * Constructing one costs a locale-data lookup, and the composer's queue summary
+ * re-renders on every keystroke while a turn streams. The cache is unbounded on
+ * purpose: its key space is the language list, seventeen entries.
+ */
+const rules = new Map<string, Intl.PluralRules>();
+
+function rulesFor(language: string): Intl.PluralRules {
+  const cached = rules.get(language);
+  if (cached !== undefined) return cached;
+  // An unknown or malformed tag throws rather than falling back, and a bad
+  // language must not take the composer down — English plurals on an unknown
+  // tag are wrong in a way the user can read past.
+  let made: Intl.PluralRules;
+  try {
+    made = new Intl.PluralRules(language);
+  } catch {
+    made = new Intl.PluralRules("en");
+  }
+  rules.set(language, made);
+  return made;
+}
+
+/**
+ * Choose a plural form and fill `{{count}}`.
+ *
+ * Falls back to `other` when the category a language selects is absent from the
+ * dictionary. That is not a defect to fail on: `other` is required by the type,
+ * so a fallback always exists, and rendering the wrong-but-readable form beats
+ * rendering nothing at the moment a user is counting their own queued prompts.
+ */
+export function plural(
+  copy: PluralCopy,
+  count: number,
+  language: string,
+  values: Readonly<Record<string, string | number>> = {},
+): string {
+  const category = rulesFor(language).select(count);
+  const template = copy[category] ?? copy.other;
+  return fill(template, { ...values, count });
+}

package/src/i18n/types.ts

@@ -0,0 +1,257 @@
+/**
+ * The chat package's copy schema.
+ *
+ * English is the schema of record: every locale dictionary is typed against
+ * `ChatCopy`, so a missing or misspelled key fails `tsc` rather than rendering
+ * `undefined` into a composer button.
+ *
+ * Typing is what replaces the shared locale gates. The four scripts under
+ * `packages/i18n/scripts/` walk the catalogue in `packages/i18n/src/locales/`
+ * and cannot see a package-local dictionary, exactly as they cannot see the
+ * onboarding one.
+ */
+
+/**
+ * The plural categories `Intl.PluralRules` can report.
+ *
+ * `other` is required and the rest are not, because a language HAS the
+ * categories it has: English resolves only `one` and `other`, Russian adds
+ * `few` and `many`, Japanese uses `other` alone. Requiring all six would force
+ * an English catalogue to invent a `few` that no input can ever select.
+ */
+export interface PluralCopy {
+  readonly zero?: string;
+  readonly one?: string;
+  readonly two?: string;
+  readonly few?: string;
+  readonly many?: string;
+  readonly other: string;
+}
+
+/** Copy for the transcript: the log, its empty state, and the wait. */
+export interface TranscriptCopy {
+  /** Shown when there are no messages — an empty transcript is a real state. */
+  readonly empty: string;
+  /**
+   * Accessible name of the starter-prompt list, so the group is not anonymous.
+   *
+   * Only the NAME lives here. The rows' own titles come from the host with its
+   * catalogue, because what an agent can be asked to do is a fact about the
+   * agent and this package does not hold it.
+   */
+  readonly suggestionsLabel: string;
+  /** Accessible name of the log, so the landmark is not anonymous. */
+  readonly log: string;
+  /** The two strings a screen reader hears per turn. */
+  readonly announceStreaming: string;
+  readonly announceComplete: string;
+  /** The return-to-bottom control, which is icon-only. */
+  readonly jumpToLatest: string;
+  /** What the wait is for, before the first token arrives. */
+  readonly thinking: string;
+  /** The elapsed counter. `{{seconds}}` is whole seconds. */
+  readonly thinkingElapsed: string;
+  /**
+   * The two relative day headings. Older days are named by their date, which
+   * `lib-utils` formats in the reader's locale — so there is no third key here.
+   */
+  readonly today: string;
+  readonly yesterday: string;
+}
+
+/** Copy for the message action row and the collapsible reasoning block. */
+export interface MessageCopy {
+  readonly copy: string;
+  readonly copied: string;
+  readonly reply: string;
+  /** Copy a link that reopens this one message. */
+  readonly copyLink: string;
+  /** Confirmation after {@link copyLink}, distinct from `copied`: two actions
+   *  in one row both confirm, and one word for both hides which fired. */
+  readonly copiedLink: string;
+  /** Names the quote above a turn, which is a button back to what it answers. */
+  readonly jumpToQuoted: string;
+  /** Summary of the collapsed reasoning block, once the thought has settled. */
+  readonly reasoning: string;
+  /**
+   * Summary WHILE the thought is still arriving.
+   *
+   * A separate key rather than reusing `reasoning`: a block that says
+   * "Reasoning" while it fills and "Reasoning" when it is done tells the reader
+   * nothing about which state they are looking at, and the live one is the
+   * state that explains why nothing else has appeared yet.
+   */
+  readonly reasoningLive: string;
+  /**
+   * The block's summary when the engine stripped the words and reported only a
+   * count. `{{count}}` is reasoning tokens.
+   *
+   * This exists because the alternative is silence: a provider that ships the
+   * thinking block with its text removed leaves the figure as the only true
+   * thing, and a block keyed on text alone renders nothing at all.
+   *
+   * A `PluralCopy` because it counts: Russian and Polish select a different
+   * form at 1, 2 and 5, and a flat string would read as broken grammar on the
+   * majority of counts rather than on an edge case.
+   */
+  readonly reasoningTokens: PluralCopy;
+  /**
+   * The two labels of the trigger that opens and closes a long turn.
+   *
+   * Both are present because the control is a toggle whose label states what
+   * the next press DOES, not what the current state is — an unlabelled arrow
+   * would leave the reader guessing which direction it goes.
+   */
+  readonly showMore: string;
+  readonly showLess: string;
+}
+
+/**
+ * The four tool-call states, in the order they occur.
+ *
+ * Named for what the user sees rather than for the wire's `input-streaming`
+ * spelling: the vocabulary a person reads is not the vocabulary a protocol
+ * uses, and tying the copy to the second makes a protocol rename a copy change.
+ */
+export interface ToolCopy {
+  readonly inputStreaming: string;
+  readonly inputAvailable: string;
+  readonly outputAvailable: string;
+  readonly outputError: string;
+  /** Names the disclosure button while the call is open. */
+  readonly collapse: string;
+  /** Names it while the call is shut. The chevron is decorative, so this is
+   *  the only thing a screen reader has to go on. */
+  readonly expand: string;
+}
+
+/** Copy for the strip of prompts waiting for the current turn to end. */
+export interface QueueCopy {
+  /** The summary line above a collapsed queue. `{{count}}`. */
+  readonly prompts: PluralCopy;
+  /** The fold: how many rows are hidden past the inline limit. `{{count}}`. */
+  readonly more: PluralCopy;
+  /** Folds them back. */
+  readonly showLess: string;
+  readonly remove: string;
+  readonly show: string;
+  /** Takes the prompt back into the composer. Tooltip only — the row IS the control. */
+  readonly edit: string;
+  /**
+   * Names the control that cuts the running turn short to release one prompt.
+   *
+   * Must name BOTH halves — the turn is lost, and a label reading only "send"
+   * hides that from the one click where it matters.
+   */
+  readonly sendNow: string;
+  /**
+   * The SAME control with no turn to cut short — after a Stop, where the queue
+   * refuses to drain on its own.
+   *
+   * A separate string rather than reusing {@link sendNow}, whose whole job is to
+   * name the interruption: promising to stop a reply that already ended
+   * describes something that cannot happen, and a label that over-warns is
+   * trusted no more than one that under-warns.
+   */
+  readonly send: string;
+  /** The confirmation that guards it. Destructive: work already done is lost. */
+  readonly sendNowConfirmTitle: string;
+  readonly sendNowConfirmMessage: string;
+  /**
+   * Asked when taking a prompt back would overwrite what is already typed.
+   * The buttons are the dialog's own — only the question is ours.
+   */
+  readonly replaceDraftTitle: string;
+  readonly replaceDraftMessage: string;
+}
+
+/** Copy for dictation: the mic, and the language picker beside it. */
+export interface VoiceCopy {
+  readonly start: string;
+  readonly stop: string;
+  readonly language: string;
+  readonly languageMenu: string;
+  readonly languageSearch: string;
+  readonly languageEmpty: string;
+  readonly languageBack: string;
+}
+
+/** Copy for the composer's field, its tools menu, and the send control. */
+export interface ComposerCopy {
+  /** Accessible name of the textarea. */
+  readonly input: string;
+  readonly placeholder: string;
+  readonly send: string;
+  /**
+   * Hover-only hint naming the key that sends, beneath the send label.
+   *
+   * A hint, never the accessible name: it states the binding `field/keys.ts`
+   * actually makes — bare Enter — so it must be re-read there before it is
+   * changed here, and it stays out of `send` so a screen reader is not read a
+   * keyboard tip it cannot act on.
+   */
+  readonly sendShortcut: string;
+  readonly stop: string;
+  /** Dismiss the chip naming the message this draft answers. */
+  readonly replyClear: string;
+  /**
+   * The `+` menu: what this agent can do.
+   *
+   * Names the ARSENAL, not the button's shape. "Add" or "Attach" is what a `+`
+   * means in every other chat product, and this one lists capabilities — a
+   * label borrowed from the familiar gesture would promise a file picker.
+   */
+  readonly toolsMenu: string;
+  readonly toolsSearch: string;
+  readonly toolsEmpty: string;
+  /** Heading for the tools this user reached for last, above the catalogue. */
+  readonly toolsRecent: string;
+  /** Drop one tool from that history: the row's `x`, not the chip's. */
+  readonly toolsForget: string;
+  /** Drop a picked tool from the draft: the chip's `x`. */
+  readonly toolRemove: string;
+  /**
+   * The field's placeholder while a picked tool still lacks its object.
+   *
+   * It REPLACES the ordinary placeholder rather than adding a line, so the
+   * composer stays one box: the standing advice ("Ask anything") is exactly
+   * what stops applying the moment a pick names something more specific.
+   *
+   * Both are imperative and name the act, never the tool — the chip beside the
+   * field already says which tool asked.
+   */
+  readonly needsFile: string;
+  readonly needsSkill: string;
+  /**
+   * Names the ROW OF CHIPS already picked, not the menu that picks them.
+   * Each tool name renders twice — once in `toolsMenu`, once on its chip — so
+   * this label must not echo `toolsMenu`, or a screen reader and a test lose
+   * the only handle telling the two places apart.
+   */
+  readonly toolsPicked: string;
+  /**
+   * Turn the longer-reasoning pass ON — the label while it is off.
+   *
+   * It NAMES THE COST ("slower, costs more") because this is the only surface
+   * that can: the package ships no tooltip, and the button is the last thing a
+   * user touches before spending. A bare "Think longer" sells the upside and
+   * hides the bill.
+   *
+   * **Never put a currency amount here.** Money beside the message box is what
+   * makes people ration — the same reason the allowance indicator is a bar with
+   * no numbers, and amounts live on the review surface (Settings > Plan). State
+   * the DIRECTION, never the figure.
+   */
+  readonly thinkOn: string;
+  /** Turn it OFF — the label while it is on. No cost note: stopping costs nothing. */
+  readonly thinkOff: string;
+}
+
+export interface ChatCopy {
+  readonly transcript: TranscriptCopy;
+  readonly message: MessageCopy;
+  readonly tool: ToolCopy;
+  readonly composer: ComposerCopy;
+  readonly queue: QueueCopy;
+  readonly voice: VoiceCopy;
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+// Public root: <Chat>, the primitives, the composer, and the core contracts.
+//
+// `./content` is NOT re-exported here, and that is the one deliberate
+// exclusion. It pulls `streamdown` plus shiki and katex — a host rendering a
+// read-only transcript, or supplying its own markdown renderer, must not pay
+// for a syntax highlighter. Everything else in this package is behaviour and
+// types, which cost nothing to re-export.
+//
+// A host that renders model markdown imports `@djangocfg/widget-chat/content` and
+// registers `Response` as its own text renderer. That is one line in the part
+// registry, and it keeps the choice — and the weight — with the host.
+
+export * from "./core";
+export * from "./i18n";
+export * from "./store";
+export * from "./primitives";
+export * from "./composer";
+export * from "./ui";

package/src/primitives/index.ts

@@ -0,0 +1,43 @@
+// Headless compound components: behaviour and accessibility, NO styling.
+// Transcript, message, tool calls, the part registry, focus and scroll.
+//
+// May import: store, core, utils.
+// May NOT import: composer, ui, Tailwind classes.
+//
+// Unstyled on purpose — this is the escape hatch. Beside a ready-made <Chat>
+// there is always <ChatProvider> plus your own UI. Without one, prop explosion
+// returns: that is exactly how the predecessor reached 83 props.
+
+export { Transcript } from "./transcript";
+export type { TranscriptProps } from "./transcript";
+export { Message, MessageContent } from "./message";
+export type { MessageProps, MessageContentProps } from "./message";
+export { PartRegistryProvider, usePartRenderer } from "./part-registry";
+export type { PartRegistry, PartRenderer, PartRenderProps, PartRegistryProviderProps } from "./part-registry";
+export { ToolCall, ToolCallHeader, ToolCallInput, ToolCallOutput, SubagentThread } from "./tool-call";
+export type {
+  ToolCallProps,
+  ToolCallHeaderProps,
+  ToolCallInputProps,
+  ToolCallOutputProps,
+  SubagentThreadProps,
+} from "./tool-call";
+export { Suggestions, useHasSuggestions } from "./suggestions";
+export type { SuggestionsProps, SuggestionRenderProps } from "./suggestions";
+export { useDismiss } from "./use-dismiss";
+export type { UseDismissOptions } from "./use-dismiss";
+export {
+  useSelectAllTranscript,
+  selectTranscript,
+  claimsSelectAll,
+  isEditableTarget,
+} from "./use-select-all-transcript";
+export { useRovingFocus } from "./use-roving-focus";
+export type { RovingFocus } from "./use-roving-focus";
+export { useStickToBottom } from "./use-stick-to-bottom";
+export type { StickToBottom } from "./use-stick-to-bottom";
+export { useOverflows } from "./use-overflows";
+export { useTurnActivity } from "./use-turn-activity";
+export type { TurnActivity } from "./use-turn-activity";
+export { ChatTooltip } from "./tooltip";
+export type { ChatTooltipProps } from "./tooltip";

package/src/primitives/message.tsx

@@ -0,0 +1,85 @@
+import { memo, type ReactNode } from "react";
+
+import type { ChatMessage, MessagePart } from "../core/parts";
+import { useMessage } from "../store";
+import { usePartRenderer } from "./part-registry";
+
+export interface MessageProps {
+  readonly id: string;
+  readonly className?: string;
+  /**
+   * Wrap the rendered parts — the bubble, the avatar, the timestamp. Receives
+   * the message so a host can vary by role or status without this component
+   * growing a prop per variation.
+   */
+  readonly children?: (message: ChatMessage, parts: ReactNode) => ReactNode;
+}
+
+/**
+ * One message, rendered from its parts.
+ *
+ * There is no `renderText` / `renderTool` / `renderImage` prop set. Part
+ * rendering resolves through a registry keyed on part type, so a product adds a
+ * part kind by registering a renderer rather than by widening this signature —
+ * the difference between an API that grows O(1) and one that reached 83 props.
+ */
+export const Message = memo(function Message({ id, className, children }: MessageProps) {
+  const message = useMessage(id);
+  if (message === undefined) return null;
+  return (
+    <MessageContent message={message} className={className}>
+      {children}
+    </MessageContent>
+  );
+});
+
+export interface MessageContentProps {
+  readonly message: ChatMessage;
+  readonly className?: string;
+  readonly children?: (message: ChatMessage, parts: ReactNode) => ReactNode;
+}
+
+/**
+ * Render a message we already hold, bypassing the store.
+ *
+ * A subagent's transcript lives INSIDE a tool part, not in the store, so
+ * `useMessage(id)` would find nothing for it. Splitting the lookup from the
+ * rendering lets both paths share one renderer instead of growing a second,
+ * subtly-different one for nested threads.
+ */
+export const MessageContent = memo(function MessageContent({
+  message,
+  className,
+  children,
+}: MessageContentProps) {
+  const parts = (
+    <>
+      {message.parts.map((part) => (
+        <Part key={part.id} part={part} message={message} />
+      ))}
+    </>
+  );
+
+  if (children !== undefined) return <>{children(message, parts)}</>;
+  return (
+    <div className={className} data-role={message.role} data-status={message.status.state}>
+      {parts}
+    </div>
+  );
+});
+
+interface PartProps {
+  readonly part: MessagePart;
+  readonly message: ChatMessage;
+}
+
+/**
+ * Memoized per part so a delta landing in the last text part does not re-render
+ * the tool call above it. Parts are immutable in the reducer, so reference
+ * equality is an exact "did this part change".
+ */
+const Part = memo(function Part({ part, message }: PartProps) {
+  const render = usePartRenderer(part.type);
+  if (render === undefined) return null;
+  return <>{render({ part, message })}</>;
+});

package/src/primitives/part-registry.tsx

@@ -0,0 +1,44 @@
+import { createContext, useContext, useMemo, type ReactNode } from "react";
+
+import type { ChatMessage, MessagePart } from "../core/parts";
+
+export interface PartRenderProps {
+  readonly part: MessagePart;
+  readonly message: ChatMessage;
+}
+
+export type PartRenderer = (props: PartRenderProps) => ReactNode;
+
+/** `type` → renderer. Unregistered types render nothing rather than crashing. */
+export type PartRegistry = Readonly<Record<string, PartRenderer>>;
+
+const PartRegistryContext = createContext<PartRegistry>({});
+
+export interface PartRegistryProviderProps {
+  readonly renderers: PartRegistry;
+  readonly children: ReactNode;
+}
+
+/**
+ * Registry of part renderers, inherited by nested threads.
+ *
+ * Inheritance is the load-bearing part, and it is why this is a context rather
+ * than a prop. A subagent's transcript renders inside a tool part; without
+ * inheritance every host would have to re-register the same renderers at every
+ * nesting level, and the ones they forgot would silently render nothing.
+ * assistant-ui reached the same conclusion.
+ *
+ * Nesting MERGES rather than replaces, so a nested thread can override one
+ * renderer — a compact tool card, say — without losing the rest.
+ */
+export function PartRegistryProvider({ renderers, children }: PartRegistryProviderProps) {
+  const inherited = useContext(PartRegistryContext);
+  const merged = useMemo(() => ({ ...inherited, ...renderers }), [inherited, renderers]);
+  return (
+    <PartRegistryContext.Provider value={merged}>{children}</PartRegistryContext.Provider>
+  );
+}
+
+export function usePartRenderer(type: string): PartRenderer | undefined {
+  return useContext(PartRegistryContext)[type];
+}