@godxjp/ui 20.2.1 → 21.0.0

package/dist/i18n/messages/vi.json

@@ -159,6 +159,22 @@
       "error": "Không hợp lệ",
       "validating": "Đang kiểm tra",
       "submitFailed": "Không thể gửi biểu mẫu. Vui lòng thử lại."
+    },
+    "chatComposer": {
+      "label": "Tin nhắn",
+      "placeholder": "Nhập tin nhắn",
+      "send": "Gửi tin nhắn",
+      "cancel": "Dừng tạo câu trả lời",
+      "hintEnter": "Enter để gửi · Shift + Enter để xuống dòng",
+      "hintShiftEnter": "Shift + Enter để gửi · Enter để xuống dòng"
+    },
+    "chatSuggestion": {
+      "label": "Gợi ý",
+      "empty": "Không có gợi ý phù hợp",
+      "count": {
+        "one": "{count} gợi ý",
+        "other": "{count} gợi ý"
+      }
     }
   },
   "feedback": {
@@ -283,6 +299,13 @@
     "progress": {
       "ariaLabel": "Tiến độ",
       "breakdownSeparator": ", "
+    },
+    "tree": {
+      "expand": "Mở rộng",
+      "collapse": "Thu gọn",
+      "loading": "Đang tải nút con…",
+      "empty": "Không có gì để hiển thị",
+      "selected": "Đã chọn"
     }
   },
   "ui": {
@@ -524,5 +547,26 @@
   "textExamples": {
     "preservedText": "Văn bản thuần",
     "sampleText": "Dòng đầu\n  Dòng thụt vào\n\nDòng cuối"
+  },
+  "chat": {
+    "bubble": {
+      "typing": "Đang nhập…",
+      "loading": "Đang tải tin nhắn",
+      "you": "Bạn",
+      "assistant": "Trợ lý",
+      "tone": {
+        "info": "Thông tin",
+        "success": "Thành công",
+        "warning": "Cảnh báo",
+        "destructive": "Lỗi"
+      }
+    },
+    "list": {
+      "label": "Cuộc trò chuyện",
+      "jumpToLatest": "Đến tin mới nhất",
+      "newMessages": {
+        "other": "{count} tin nhắn mới"
+      }
+    }
   }
 }

package/dist/lib/tree.d.ts

@@ -0,0 +1,53 @@
+import type * as React from "react";
+/** Normalized tree node — the conventional `treeData` / Cascader `options` shape. */
+export type TreeOption = {
+    value: string;
+    label: React.ReactNode;
+    disabled?: boolean;
+    disableCheckbox?: boolean;
+    /** When false with `loadData`, shows expand affordance */
+    isLeaf?: boolean;
+    /**
+     * Per-node glyph, drawn by `Tree` when `showIcon` is on. Carried through the normalizer so the
+     * page tree and the dropdown tree keep ONE node shape; `TreeSelect` simply never reads it.
+     */
+    icon?: React.ReactNode;
+    children?: TreeOption[];
+};
+export type TreeFieldNames = {
+    label?: string;
+    value?: string;
+    children?: string;
+};
+export type NormalizedTreeOption = TreeOption & {
+    children?: NormalizedTreeOption[];
+};
+type RawTreeNode = Record<string, unknown>;
+export declare function reactNodeText(value: React.ReactNode): string;
+export declare function normalizeTreeOptions(nodes: RawTreeNode[] | undefined, fieldNames?: TreeFieldNames): NormalizedTreeOption[];
+export declare function getNodeByPath(options: NormalizedTreeOption[], path: string[]): NormalizedTreeOption[];
+export declare function getOptionsAtPath(options: NormalizedTreeOption[], path: string[]): NormalizedTreeOption[];
+export declare function formatPathLabels(chain: NormalizedTreeOption[], separator?: string): string;
+export type TreePath = {
+    path: string[];
+    labels: string[];
+};
+export declare function collectLeafPaths(options: NormalizedTreeOption[], prefix?: string[], root?: NormalizedTreeOption[]): TreePath[];
+export declare function collectAllPaths(options: NormalizedTreeOption[], prefix?: string[], root?: NormalizedTreeOption[]): TreePath[];
+export declare function pathKey(path: string[]): string;
+export declare function pathsEqual(a: string[], b: string[]): boolean;
+export declare function filterTreeOptions(options: NormalizedTreeOption[], query: string, filter?: (query: string, path: NormalizedTreeOption[]) => boolean): TreePath[];
+export declare function getDescendantValues(node: NormalizedTreeOption): string[];
+export declare function flattenVisibleTree(options: NormalizedTreeOption[], expandedKeys: Set<string>, depth?: number): {
+    node: NormalizedTreeOption;
+    depth: number;
+    hasChildren: boolean;
+}[];
+export declare function filterVisibleTree(options: NormalizedTreeOption[], query: string): {
+    node: NormalizedTreeOption;
+    depth: number;
+    hasChildren: boolean;
+}[];
+export declare function collectAllExpandableKeys(options: NormalizedTreeOption[]): string[];
+export declare function findNodeByValue(options: NormalizedTreeOption[], value: string): NormalizedTreeOption | undefined;
+export {};

package/dist/lib/tree.js

@@ -0,0 +1,155 @@
+function reactNodeText(value) {
+  if (value == null || typeof value === "boolean") return "";
+  if (typeof value === "string" || typeof value === "number" || typeof value === "bigint") {
+    return String(value);
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => reactNodeText(item)).join("");
+  }
+  return "";
+}
+function unknownText(value) {
+  if (typeof value === "string" || typeof value === "number" || typeof value === "bigint") {
+    return String(value);
+  }
+  return "";
+}
+function normalizeTreeOptions(nodes, fieldNames) {
+  if (!nodes?.length) return [];
+  const labelKey = fieldNames?.label ?? "label";
+  const valueKey = fieldNames?.value ?? "value";
+  const childrenKey = fieldNames?.children ?? "children";
+  return nodes.map((node) => {
+    const children = node[childrenKey];
+    const value = unknownText(node[valueKey]);
+    const label = node[labelKey];
+    return {
+      value,
+      label: label ?? value,
+      disabled: Boolean(node.disabled),
+      disableCheckbox: Boolean(node.disableCheckbox),
+      isLeaf: node.isLeaf,
+      icon: node.icon,
+      children: Array.isArray(children) ? normalizeTreeOptions(children, fieldNames) : void 0
+    };
+  });
+}
+function getNodeByPath(options, path) {
+  const chain = [];
+  let level = options;
+  for (const segment of path) {
+    const found = level.find((n) => n.value === segment);
+    if (!found) break;
+    chain.push(found);
+    level = found.children ?? [];
+  }
+  return chain;
+}
+function getOptionsAtPath(options, path) {
+  if (!path.length) return options;
+  const chain = getNodeByPath(options, path);
+  return chain.at(-1)?.children ?? [];
+}
+function formatPathLabels(chain, separator = " / ") {
+  return chain.map((n) => reactNodeText(n.label)).join(separator);
+}
+function collectLeafPaths(options, prefix = [], root = options) {
+  const out = [];
+  for (const node of options) {
+    const path = [...prefix, node.value];
+    const hasChildren = (node.children?.length ?? 0) > 0;
+    if (!hasChildren || node.isLeaf === true) {
+      out.push({ path, labels: getNodeByPath(root, path).map((n) => reactNodeText(n.label)) });
+    }
+    if (hasChildren) out.push(...collectLeafPaths(node.children, path, root));
+  }
+  return out;
+}
+function collectAllPaths(options, prefix = [], root = options) {
+  const out = [];
+  for (const node of options) {
+    const path = [...prefix, node.value];
+    out.push({ path, labels: getNodeByPath(root, path).map((n) => reactNodeText(n.label)) });
+    if (node.children?.length) out.push(...collectAllPaths(node.children, path, root));
+  }
+  return out;
+}
+function pathKey(path) {
+  return path.join("\0");
+}
+function pathsEqual(a, b) {
+  return a.length === b.length && a.every((v, i) => v === b[i]);
+}
+function filterTreeOptions(options, query, filter) {
+  const q = query.trim().toLowerCase();
+  if (!q) return [];
+  const paths = collectLeafPaths(options);
+  return paths.filter(({ path }) => {
+    const chain = getNodeByPath(options, path);
+    if (filter) return filter(query, chain);
+    return chain.some((n) => reactNodeText(n.label).toLowerCase().includes(q));
+  });
+}
+function getDescendantValues(node) {
+  const values = [node.value];
+  for (const child of node.children ?? []) values.push(...getDescendantValues(child));
+  return values;
+}
+function flattenVisibleTree(options, expandedKeys, depth = 0) {
+  const out = [];
+  for (const node of options) {
+    const hasChildren = (node.children?.length ?? 0) > 0 && node.isLeaf !== true;
+    out.push({ node, depth, hasChildren });
+    if (hasChildren && expandedKeys.has(node.value)) {
+      out.push(...flattenVisibleTree(node.children, expandedKeys, depth + 1));
+    }
+  }
+  return out;
+}
+function filterVisibleTree(options, query) {
+  const q = query.trim().toLowerCase();
+  if (!q) return flattenVisibleTree(options, new Set(collectAllExpandableKeys(options)));
+  function matches(nodes, depth) {
+    return nodes.flatMap((node) => {
+      const children = node.isLeaf ? [] : matches(node.children ?? [], depth + 1);
+      if (!reactNodeText(node.label).toLowerCase().includes(q) && children.length === 0) return [];
+      return [{ node, depth, hasChildren: children.length > 0 }, ...children];
+    });
+  }
+  return matches(options, 0);
+}
+function collectAllExpandableKeys(options) {
+  const keys = [];
+  for (const node of options) {
+    if ((node.children?.length ?? 0) > 0 && node.isLeaf !== true) {
+      keys.push(node.value);
+      keys.push(...collectAllExpandableKeys(node.children));
+    }
+  }
+  return keys;
+}
+function findNodeByValue(options, value) {
+  for (const node of options) {
+    if (node.value === value) return node;
+    const nested = node.children ? findNodeByValue(node.children, value) : void 0;
+    if (nested) return nested;
+  }
+  return void 0;
+}
+export {
+  collectAllExpandableKeys,
+  collectAllPaths,
+  collectLeafPaths,
+  filterTreeOptions,
+  filterVisibleTree,
+  findNodeByValue,
+  flattenVisibleTree,
+  formatPathLabels,
+  getDescendantValues,
+  getNodeByPath,
+  getOptionsAtPath,
+  normalizeTreeOptions,
+  pathKey,
+  pathsEqual,
+  reactNodeText
+};

package/dist/props/components/data-display.prop.d.ts

@@ -28,7 +28,8 @@ export type ProseProp = {
     className?: ClassNameProp;
     children?: ChildrenProp;
 };
-import type { ActionProp, ClassNameProp, DescriptionProp, IconProp, TitleProp, ColumnDefProp, GetRowIdProp, OnRowClickProp, OnSelectChangeProp, OnSortChangeProp, OnTableDensityChangeProp, SelectedIdsProp, SortStateProp, TableDensityProp, TablePresetProp, BreakpointProp, DensityProp, ChildrenProp, ToneProp, AvatarShapeProp, HeadingLevelProp, HandlerProp, SizeProp, LabelProp, IdProp, DescriptionsLayoutProp, DescriptionsColumnProp, DescriptionsSpanProp, DescriptionsItemsProp, SortDirectionProp, OnColumnFilterChangeProp, OnRowProp, TableExpandableProp, TableRowSelectionProp, TableScrollProp, TableStickyProp, TableSummaryProp } from "../vocabulary/index.js";
+import type { ActionProp, ClassNameProp, DescriptionProp, IconProp, TitleProp, ColumnDefProp, GetRowIdProp, OnRowClickProp, OnSelectChangeProp, OnSortChangeProp, OnTableDensityChangeProp, SelectedIdsProp, SortStateProp, TableDensityProp, TablePresetProp, BreakpointProp, DensityProp, ChildrenProp, PendingProp, ToneProp, AvatarShapeProp, HeadingLevelProp, HandlerProp, SizeProp, LabelProp, IdProp, DescriptionsLayoutProp, DescriptionsColumnProp, DescriptionsSpanProp, DescriptionsItemsProp, SortDirectionProp, OnColumnFilterChangeProp, OnRowProp, TableExpandableProp, TableRowSelectionProp, TableScrollProp, TableStickyProp, TableSummaryProp, DisabledProp, ValueProp, DefaultValueProp, OnValueChangeProp } from "../vocabulary/index.js";
+import type { TreeFieldNamesProp, TreeOptionProp } from "./data-entry.prop.js";
 /**
  * One key in a `Legend`: a tone, and the words that tone stands for.
  *
@@ -493,3 +494,188 @@ export type TimelineGridProp = {
     className?: ClassNameProp;
     id?: IdProp;
 };
+/**
+ * @see Tree — one node of the standalone, on-page tree view.
+ *
+ * Structurally the same node `TreeSelect`/`Cascader` take (one tree model, two surfaces — the
+ * normalizer lives in `src/lib/tree.ts`), plus the per-node glyph the ON-PAGE surface needs and a
+ * dropdown does not.
+ */
+export type TreeNodeProp = TreeOptionProp & {
+    /** Glyph drawn before the label when `showIcon` is on. Decorative — the label carries the name. */
+    icon?: React.ReactNode;
+    children?: TreeNodeProp[];
+};
+/**
+ * @see Tree — the WAI-ARIA APG "Tree View" on a page (Ant's `Tree` / `DirectoryTree`).
+ *
+ * `TreeSelect` is the same hierarchy inside a Popover. A flat indented list only LOOKS like a tree
+ * (that was `TreeList`, removed in 21.0.0 with `Tree` as its replacement), so reach for `Tree`
+ * whenever nodes expand, collapse, or are navigated by keyboard.
+ *
+ * Ant's key-shaped names are mapped onto this package's controlled vocabulary and NOT re-spelled:
+ * selection is `value`/`defaultValue`/`onValueChange`, expansion is
+ * `expandedValues`/`defaultExpandedValues`/`onExpandedValuesChange`, checks are
+ * `checkedValues`/`defaultCheckedValues`/`onCheckedValuesChange`.
+ * @see docs/roadmap/tree-components.md §3
+ */
+export type TreeProp = {
+    /** The hierarchy (antd `treeData`). Use `fieldNames` to remap keys off an API response. */
+    treeData: readonly TreeNodeProp[];
+    /** Remap the data's own key names (antd `fieldNames`). */
+    fieldNames?: TreeFieldNamesProp;
+    /** Controlled selection. `string` while single, `string[]` once `multiple` is on. */
+    value?: ValueProp<string | string[]>;
+    /** Uncontrolled initial selection (controlled-triad rule). */
+    defaultValue?: DefaultValueProp<string | string[]>;
+    /** Selection change. Emits `string | undefined` while single, `string[]` once `multiple` is on. */
+    onValueChange?: OnValueChangeProp<string | string[] | undefined>;
+    /** Allow more than one selected node (antd `multiple`). Also sets `aria-multiselectable`. */
+    multiple?: boolean;
+    /** Draw a checkbox on every node (antd `checkable`). Checks are a SEPARATE axis from selection. */
+    checkable?: boolean;
+    /** Parent and child checks are independent (antd `checkStrictly`) — no cascade, no `mixed`. */
+    checkStrictly?: boolean;
+    /** Controlled checked nodes (antd `checkedKeys`). */
+    checkedValues?: readonly string[];
+    /** Uncontrolled initial checked nodes (antd `defaultCheckedKeys`). */
+    defaultCheckedValues?: readonly string[];
+    /** Checked-set change (antd `onCheck`). Fires for controlled and uncontrolled trees alike. */
+    onCheckedValuesChange?: (values: string[]) => void;
+    /** Controlled expanded branches (antd `expandedKeys`). */
+    expandedValues?: readonly string[];
+    /** Uncontrolled initial expanded branches (antd `defaultExpandedKeys`). */
+    defaultExpandedValues?: readonly string[];
+    /** Expansion change (antd `onExpand`). Fires for controlled and uncontrolled trees alike. */
+    onExpandedValuesChange?: (values: string[]) => void;
+    /** Start with every branch open (antd `defaultExpandAll`). Seeded once, never re-applied. */
+    defaultExpandAll?: boolean;
+    /**
+     * Lazy children (antd `loadData`). Called ONCE per node the first time a branch with no
+     * `children` and `isLeaf !== true` is expanded; push the fetched children into `treeData`.
+     */
+    loadData?: (node: TreeNodeProp) => void | Promise<void>;
+    /** Render a node's title (antd `titleRender`). */
+    titleRender?: (node: TreeNodeProp) => React.ReactNode;
+    /** Draw the connector rails between a parent and its children (antd `showLine`). */
+    showLine?: boolean;
+    /** Draw each node's `icon` (antd `showIcon`). `variant="directory"` supplies folder/file glyphs. */
+    showIcon?: boolean;
+    /** `directory` is antd's `<DirectoryTree>`: folder/file glyphs and a full-row selected band. */
+    variant?: "default" | "directory";
+    /** Row height tier — the shared `--control-height` ladder. Default `md`. */
+    size?: SizeProp;
+    /** Disable the whole tree: nothing selects, checks or expands; nodes stay readable. */
+    disabled?: DisabledProp;
+    className?: ClassNameProp;
+    id?: IdProp;
+    /** Accessible name of the `role="tree"` container. Required unless `aria-labelledby` is given. */
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+};
+/**
+ * @see ChatBubble — which side of the conversation the message sits on. LOGICAL, not physical:
+ * `start` is the inline start of the reading direction (left in `ltr`, right in `rtl`), so a feed
+ * flips correctly under `dir="rtl"` with no per-locale branch. `start` = the other party,
+ * `end` = the reader's own messages, which is the convention every chat client shares.
+ */
+export type ChatBubblePlacementProp = "start" | "end";
+/**
+ * @see ChatBubble — STRUCTURAL treatment of the message body, orthogonal to `tone` (which owns
+ * colour). Ant Design X's `shadow` is deliberately absent: this design system is a 1px-border
+ * system with no drop shadows (docs/TOKENS.md).
+ *
+ * - `filled` (default) — the quiet `--chat-bubble-background` wash.
+ * - `outlined` — transparent body inside a 1px `--chat-bubble-border-color` edge.
+ * - `borderless` — no fill and no edge; long assistant prose that should read as page copy.
+ */
+export type ChatBubbleVariantProp = "filled" | "borderless" | "outlined";
+/**
+ * @see ChatBubble — status intent for a message that is not ordinary conversation (a failed send,
+ * a rate-limit warning, a tool result). A subset of `ToneProp`: `muted` and `neutral` are not
+ * offered because a bubble is already the quiet surface, so they would name no distinct state.
+ *
+ * Never colour alone (WCAG 1.4.1): a toned bubble also renders a localized `sr-only` tone word.
+ */
+export type ChatBubbleToneProp = Extract<ToneProp, "default" | "info" | "success" | "warning" | "destructive">;
+/**
+ * @see ChatBubble — the streaming type-on animation. `true` takes the defaults (1 character every
+ * 50ms); the object form retunes them per instance.
+ *
+ * It animates only when `children` is a plain string — a `ReactNode` has no character count to
+ * reveal — and it is DROPPED ENTIRELY under `prefers-reduced-motion: reduce`, which renders the
+ * full text immediately (WCAG 2.2 SC 2.3.3).
+ */
+export type ChatBubbleTypingProp = boolean | {
+    step?: number;
+    interval?: number;
+};
+/** @see ChatBubble — one message in a conversation. */
+export type ChatBubbleProp = {
+    /** The message. A `ReactNode`; pass a plain string to make `typing` animatable. */
+    children?: ChildrenProp;
+    /** Which side of the feed the message sits on. Default `start`. */
+    placement?: ChatBubblePlacementProp;
+    /** Structural treatment of the body. Default `filled`. */
+    variant?: ChatBubbleVariantProp;
+    /**
+     * The author's mark — a real `<Avatar>` node, never a styled div. It is decorative when the
+     * `header` already names the author, so mark it `aria-hidden` at the call site.
+     */
+    avatar?: ChildrenProp;
+    /**
+     * Line above the body — the author, and anything that identifies the turn. When it is present
+     * the bubble takes its ACCESSIBLE NAME from it, so keep it text.
+     */
+    header?: ChildrenProp;
+    /** Line below the body — timestamps, per-message actions, token counts. */
+    footer?: ChildrenProp;
+    /** The reply has been requested and has not arrived: renders `Skeleton`, sets `aria-busy`. */
+    loading?: PendingProp;
+    /** Stream the text in character by character. Honours `prefers-reduced-motion`. */
+    typing?: ChatBubbleTypingProp;
+    /** Type step and inner inset. Default `md`. */
+    size?: SizeProp;
+    /** Status intent. Default `default`. */
+    tone?: ChatBubbleToneProp;
+    className?: ClassNameProp;
+    id?: IdProp;
+};
+/** @see ChatBubbleList — one entry of the feed: a `ChatBubble`'s own props plus its identity. */
+export type ChatMessageProp = Omit<ChatBubbleProp, "children" | "id"> & {
+    /** Stable message id. Also the React key and the rendered `<article>`'s DOM id. */
+    id: IdProp;
+    /** Key into the list's `roles` map — `"user"`, `"assistant"`, `"system"`, or your own. */
+    role?: string;
+    /** The message body. Named `content` here because `children` is not a data field. */
+    content?: ChildrenProp;
+};
+/**
+ * @see ChatBubbleList — the message feed.
+ *
+ * It scrolls inside itself, so it needs a DEFINITE height from the caller (`className="h-96"`, or
+ * a flex/grid parent that gives it a track). Without one it grows to its content and nothing ever
+ * overflows, which silently disables `autoScroll` and the jump-to-latest affordance.
+ */
+export type ChatBubbleListProp = {
+    /** Messages in conversation order, oldest first. */
+    items: readonly ChatMessageProp[];
+    /**
+     * Per-role bubble defaults, merged UNDER each message's own props. This is what keeps a feed
+     * consistent: `{ assistant: { placement: "start", variant: "filled" }, user: { placement:
+     * "end" } }` is written once instead of on every message.
+     */
+    roles?: Record<string, Partial<ChatBubbleProp>>;
+    /**
+     * Keep the newest message in view while the reader is already at the bottom. Default `true`.
+     *
+     * It is NOT "scroll to the bottom when content arrives": the moment the reader scrolls up the
+     * pin is revoked and a focusable "jump to latest" affordance appears instead, because yanking a
+     * reader back mid-sentence is a change of context they did not request (WCAG 3.2.5).
+     */
+    autoScroll?: boolean;
+    /** Accessible name of the feed. A plain string — it lands on `aria-label`. Defaults via `t()`. */
+    label?: Extract<LabelProp, string>;
+    className?: ClassNameProp;
+    id?: IdProp;
+};

package/dist/props/components/data-entry.prop.d.ts

@@ -1376,3 +1376,130 @@ export type BranchScopePickerProp = FieldA11yProps & {
     id?: IdProp;
     className?: ClassNameProp;
 };
+/**
+ * Which keystroke SENDS and which one breaks the line — Ant Design X `Sender.submitType`.
+ *
+ * `enter` (default) is the chat convention: `Enter` sends, `Shift+Enter` inserts a newline.
+ * `shiftEnter` is the inverse, for composers that hold long, deliberately multi-line drafts.
+ * Neither ever fires while an IME conversion is in flight.
+ * @see ChatComposer
+ */
+export type ChatComposerSubmitTypeProp = "enter" | "shiftEnter";
+/**
+ * @see ChatComposer — the message input of a conversation (Ant Design X `Sender`; the industry
+ * calls the control a *composer*, so that is what it is named).
+ *
+ * Built on the real `Textarea` (auto-growing between `--chat-composer-min-height` and
+ * `--chat-composer-max-height`, both derived from the `--control-height` tier) plus real
+ * `Button`s. The `<textarea>` is the semantic focus target: `ref`, `id`, `name` and the whole
+ * `FormField` label/helper/error contract land on it, so a ChatComposer inside a `FormField`
+ * behaves exactly like an `Input` does.
+ */
+export type ChatComposerProp = Omit<React.HTMLAttributes<HTMLDivElement>, "onSubmit" | "defaultValue" | "prefix" | "onChange" | "onKeyDown"> & FieldA11yProps & {
+    /** Controlled draft text. Pair with `onValueChange` or the box freezes. */
+    value?: ValueProp<string>;
+    /** Uncontrolled initial draft text. */
+    defaultValue?: DefaultValueProp<string>;
+    /** Draft-text change handler — fires on every keystroke, including during an IME conversion. */
+    onValueChange?: OnValueChangeProp<string>;
+    /**
+     * Send the draft. Receives the text as typed; never fires for an empty or whitespace-only
+     * draft, and never while `loading`, `disabled` or `readOnly`.
+     */
+    onSubmit?: (value: string) => void;
+    /** Stop the in-flight response. Only reachable while `loading`. */
+    onCancel?: () => void;
+    /**
+     * A response is streaming. The trailing action becomes CANCEL — exactly one trailing action
+     * exists at a time, the same discipline as the picker trailing-action rule.
+     */
+    loading?: PendingProp;
+    /** Which keystroke sends and which breaks the line. Default `enter`. */
+    submitType?: ChatComposerSubmitTypeProp;
+    /** Empty-state text of the draft box; pass it through `t()` at the call site. */
+    placeholder?: PlaceholderProp;
+    /** Disable the whole composer (draft box and every action). */
+    disabled?: DisabledProp;
+    /** Show the draft without allowing an edit; still focusable and selectable. */
+    readOnly?: boolean;
+    /** Slot ABOVE the draft row — attachments, a reply-to banner, a model picker. */
+    header?: React.ReactNode;
+    /** Slot at the inline START of the draft row — an attach button, an avatar. */
+    prefix?: React.ReactNode;
+    /** Slot BELOW the draft row — a hint line, a token counter. */
+    footer?: React.ReactNode;
+    /** Extra trailing actions, rendered BEFORE the send/cancel action. */
+    actions?: React.ReactNode;
+    /** Control height tier on the shared `--control-height` ladder. Default `md`. */
+    size?: SizeProp;
+    /** Hard ceiling on the draft length, forwarded to the textarea. */
+    maxLength?: number;
+    /** Validation state the composer paints. `error` also reports `aria-invalid`. */
+    status?: ControlStatusProp;
+    /** Accessible name override for the send action (localized default otherwise). */
+    submitLabel?: string;
+    /** Accessible name override for the cancel action (localized default otherwise). */
+    cancelLabel?: string;
+    /** Keydown on the draft box — how `ChatSuggestion` drives its list from the composer. */
+    onKeyDown?: React.KeyboardEventHandler<HTMLTextAreaElement>;
+    name?: NameProp;
+    id?: IdProp;
+    className?: ClassNameProp;
+};
+/** @see ChatSuggestion — one row of the trigger-character list. One level of `children` is honoured. */
+export type ChatSuggestionItemProp = {
+    /** Stable value handed to `onValueChange`, and the search haystack when there is no `label`. */
+    value: string;
+    /** Human row label. Falls back to `value`. */
+    label?: string;
+    /** Secondary line under the label. */
+    description?: string;
+    /** Decorative leading node (an icon). */
+    icon?: React.ReactNode;
+    /** Keep the row visible but unselectable. */
+    disabled?: DisabledProp;
+    /** One level of sub-rows; picking the parent drills into them instead of emitting a value. */
+    children?: readonly ChatSuggestionItemProp[];
+};
+/** The render-prop bag `ChatSuggestion` hands to the composer it wraps. */
+export type ChatSuggestionRenderProp = {
+    /**
+     * Re-read the caret and decide whether the list belongs open — call it from the composer's
+     * `onValueChange`. `false` force-closes; no argument force-opens with an empty query.
+     */
+    onTrigger: (value?: string | false) => void;
+    /** Forward to the composer's `onKeyDown`: arrows move, Enter/Tab pick, Escape closes. */
+    onKeyDown: React.KeyboardEventHandler<HTMLTextAreaElement>;
+};
+/**
+ * @see ChatSuggestion — trigger-character autocomplete over a `ChatComposer` (Ant Design X
+ * `Suggestion`).
+ *
+ * The list itself is the existing `Command` (cmdk) inside a `Popover`, so the listbox ARIA comes
+ * from a primitive that already ships it. What this component owns is the part `Command` does not:
+ * spotting the trigger character at the caret in a textarea, tracking the query as the caret
+ * moves, and closing on `Escape` / blur / a word break — `Escape` returns focus to the textarea
+ * and leaves the typed text exactly as it was.
+ */
+export type ChatSuggestionProp = {
+    /** The rows to offer. One level of `children` is honoured. */
+    items: readonly ChatSuggestionItemProp[];
+    /** Fires with the picked row's `value`. The caller owns what that does to the draft text. */
+    onValueChange?: OnValueChangeProp<string>;
+    /** The character that opens the list when typed at a word boundary. Default `/`. */
+    triggerCharacter?: string;
+    /** Controlled open state. */
+    open?: OpenProp;
+    /** Uncontrolled initial open state. */
+    defaultOpen?: DefaultOpenProp;
+    /** Open-state change handler. */
+    onOpenChange?: OnOpenChangeProp;
+    /** The composer to wrap — receives `{ onTrigger, onKeyDown }`. */
+    children: (props: ChatSuggestionRenderProp) => React.ReactNode;
+    /** Text shown when the query matches nothing (localized default otherwise). */
+    emptyMessage?: EmptyMessageProp;
+    /** Accessible name of the suggestion listbox — a plain string (localized default otherwise). */
+    listLabel?: string;
+    id?: IdProp;
+    className?: ClassNameProp;
+};