band-design 0.0.0 → 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,1030 @@
1
+ import * as react from 'react';
2
+ import { SVGProps, ReactNode, Ref, MouseEvent, RefObject, KeyboardEvent, FocusEvent, ReactElement, InputHTMLAttributes } from 'react';
3
+ import { LucideIcon } from 'lucide-react';
4
+ import { MemberView, PeopleApi, TurnState } from '@kanyun-ai-infra/band-plugin-sdk';
5
+ import { B as Blocked, f as StallView } from './reactions-6uescbo-.js';
6
+ export { M as MESSAGE_EMOJI, b as MESSAGE_EMOJI_MEANING, c as MessageActor, d as MessageEmoji, e as MessageReaction } from './reactions-6uescbo-.js';
7
+ import '@kanyun-ai-infra/band-contracts';
8
+
9
+ interface IconProps extends Omit<SVGProps<SVGSVGElement>, "children" | "dangerouslySetInnerHTML" | "width" | "height" | "strokeWidth" | "role" | "aria-hidden" | "aria-label" | "aria-labelledby"> {
10
+ /** 图标从 lucide-react 按需导入,不按字符串查全量图标表。 */
11
+ icon: LucideIcon;
12
+ /** @default 16 */
13
+ size?: 16 | 20 | 24;
14
+ /**
15
+ * 24 网格内的线宽;默认 2.1 在 16px 下对应手写图标的 1.4px。
16
+ * @default 2.1
17
+ */
18
+ strokeWidth?: number;
19
+ /** 独立传达含义时给可访问名;旁边已有文字时省略,避免重复读出。 */
20
+ label?: string;
21
+ }
22
+ /** Band 通用线构图标:默认作装饰,不改变品牌状态符号与乐器资产。 */
23
+ declare function Icon({ icon: Svg, size, strokeWidth, label, ...props }: IconProps): react.JSX.Element;
24
+
25
+ /**
26
+ * 一行错误提示:操作失败时显示在面板里。`children` 为空(null、undefined、空串、false)时什么也不渲染。
27
+ * 给了 `retry` 是「读失败」:整行是 alert,提示后面跟「重试」。全站读数据失败只走这一个出口,各页不自己拼;
28
+ * 原因里断网那句由宿主统一写(`errors` 的 `NETWORK_LOST`)。
29
+ */
30
+ declare function ErrorNote({ children, retry }: {
31
+ children: ReactNode;
32
+ retry?: () => void;
33
+ }): react.JSX.Element | null;
34
+ /** 不是错误的一句说明(比如「已经交给 Rondo 了」):不用红色,不抢眼。 */
35
+ declare function InfoNote({ children }: {
36
+ children: ReactNode;
37
+ }): react.JSX.Element | null;
38
+ /** 面板头:标题(`h2`)在左,`children`(筛选、按钮、说明)在右。 */
39
+ declare function PaneHeader({ title, children }: {
40
+ title: ReactNode;
41
+ children?: ReactNode;
42
+ }): react.JSX.Element;
43
+ /**
44
+ * 头像的底色(Band Design `--av1`…`--av5`)。给了 `order`(项目里人的 id,按成员列表的顺序)就按位置轮着取,
45
+ * 五人以内互不相同,同一页上对话、成员、@ 候选看到的是同一种颜色;不在里面的按 id 取一个固定的。
46
+ */
47
+ declare function avatarTone(id: string, order?: readonly string[]): number;
48
+ /** 项目里人的 id,按成员列表的顺序(Agent 不占底色):传给 `Avatar` 的 `order`。 */
49
+ declare function memberOrder(members: readonly MemberView[]): string[];
50
+ /** 头像上的字:名字的第一个字(「王敏」写「王」),拉丁字母大写;没有名字写「?」。 */
51
+ declare function avatarInitial(name: string): string;
52
+ /**
53
+ * 成员头像(Band Design `.av`):人是带底色的名字首字;Agent 是标志里的蓝色符头(DESIGN.md · Rondo)。
54
+ * 旁边已经写了名字时 `decorative` 让读屏跳过它;单独出现时读出名字。
55
+ */
56
+ declare function Avatar({ id, name, agent, instrument, size, decorative, order, }: {
57
+ id: string;
58
+ name: string;
59
+ /** @default false */
60
+ agent?: boolean;
61
+ /** 工坊 Agent 的乐器(`instrumentOf`);不给就画 Rondo 的符头。只对 `agent` 有效。 */
62
+ instrument?: Instrument;
63
+ /** @default "sm" */
64
+ size?: "xs" | "sm" | "md";
65
+ /** @default false */
66
+ decorative?: boolean;
67
+ /** 项目里人的 id(`memberOrder(members)`),决定底色;见 `avatarTone`。 */
68
+ order?: readonly string[];
69
+ }): react.JSX.Element;
70
+ /** 状态符号:每行最右边一个 16px 符号,含义全站一致(DESIGN.md「状态符号」,样式在 Band Design)。 */
71
+ type GlyphKind = "working" | "needs" | "new" | "done" | "seen" | "waiting" | "queued" | "failed" | "";
72
+ /** `bg`:后台还有排着的回合(符号底下垫一层)。装饰性,含义由同一行的文字给出。 */
73
+ declare function Glyph({ kind, bg, }: {
74
+ kind: GlyphKind;
75
+ /** @default false */
76
+ bg?: boolean;
77
+ }): react.JSX.Element;
78
+ /** 项目里某个 Agent 的乐器(`instrumentOf`,同伴是项目里全部 Agent);Rondo 没有。 */
79
+ declare function agentInstrument(id: string, members: readonly MemberView[]): Instrument | undefined;
80
+ /** 项目里某个 Agent 的头像:名字取成员显示名,工坊 Agent 画乐器,Rondo 画符头。 */
81
+ declare function AgentAvatar({ id, members, size, decorative, }: {
82
+ id: string;
83
+ members: readonly MemberView[] | undefined;
84
+ /** @default "xs" */
85
+ size?: "xs" | "sm" | "md";
86
+ /** @default false */
87
+ decorative?: boolean;
88
+ }): react.JSX.Element;
89
+ /** 工坊 Agent 的乐器(DESIGN.md「乐器:谁在演」),顺序就是 tokens `instruments/index.json` 的顺序。 */
90
+ declare const INSTRUMENTS: readonly ["sax", "keys", "guitar", "drum", "trumpet", "violin"];
91
+ type Instrument = (typeof INSTRUMENTS)[number];
92
+ /**
93
+ * 一个工坊里各 Agent 的缺省乐器:名字的 FNV-1a 对乐器数取模,同工坊里撞了顺延到下一件空闲的;
94
+ * `peers` 是这个工坊的全部 Agent(顺序无关,按名字排序后依次分配,结果不随阶段顺序变)。
95
+ * Rondo 不拿乐器(返回 undefined,画符头)。超过六个时乐器会重复。
96
+ */
97
+ declare function instrumentOf(name: string, peers: readonly string[]): Instrument | undefined;
98
+ /**
99
+ * 工坊 icon(v8 §7「工坊 icon」):`icon` 是工坊卡片上的字段,`genre:<曲风>` 画内置曲风;仓库内图片还读不到、
100
+ * 没写或认不出时画标志简版。画的是只有乐器的简版(见 `GENRE_COMPACT_SRC`),48px 及以上的完整版用
101
+ * `WorkshopEmblem`。装饰性,名称由旁边的文字给出。
102
+ */
103
+ declare function WorkshopIcon({ icon, size, tile, }: {
104
+ icon?: string;
105
+ /** @default 20 */
106
+ size?: number;
107
+ /**
108
+ * 画在方底板上(DESIGN.md「工坊 icon」:底板归宿主)。
109
+ * @default false
110
+ */
111
+ tile?: boolean;
112
+ }): react.JSX.Element;
113
+ /**
114
+ * 工坊 icon 的完整版(带英文流派名),画在方底板上,给 48px 及以上的大卡与工坊页头用(DESIGN.md「工坊 icon」)。
115
+ * 和 `WorkshopIcon` 分开,是为了让只画小图标的插件打包时摇掉完整版的图。
116
+ */
117
+ declare function WorkshopEmblem({ icon, size, }: {
118
+ icon?: string;
119
+ /** @default 48 */
120
+ size?: number;
121
+ }): react.JSX.Element;
122
+ /** Band 标志简版(三个连杠音符,中间那个蓝色的代表 Agent)。装饰性。 */
123
+ declare function BandMark({ size, className, }: {
124
+ /** @default 20 */
125
+ size?: number;
126
+ className?: string;
127
+ }): react.JSX.Element;
128
+ /** Band 字标(五线谱 + 三个音符 + 「Band」,DESIGN.md「标志」)。样式在 Band Design 的 `.logo`。 */
129
+ declare function LogoLockup(): react.JSX.Element;
130
+
131
+ /** 一次页内跳转的目标:页键与地址参数,由调用方交给宿主。 */
132
+ interface SettingsTarget {
133
+ page: string;
134
+ params?: Record<string, string>;
135
+ }
136
+ /** 导航里的一项(分区导航的链接)。 */
137
+ interface SettingsNavItem extends SettingsTarget {
138
+ slug: string;
139
+ title: string;
140
+ href: string;
141
+ /** 右侧 16px 状态符号(同侧栏),可选。 */
142
+ glyph?: ReactNode;
143
+ }
144
+ interface SettingsGroup {
145
+ group: string;
146
+ sections: readonly SettingsNavItem[];
147
+ }
148
+ /** 页头上方那行返回(`‹ 设置`、`‹ 列表名`)。 */
149
+ interface SettingsBackTarget extends SettingsTarget {
150
+ label: string;
151
+ href: string;
152
+ }
153
+ type Navigate = (target: SettingsTarget) => void;
154
+ /** 只在主键上点(没按修饰键)时走页内跳转;其余交给浏览器(新标签页)。 */
155
+ declare function settingsLinkHandler(go: Navigate | undefined, target: SettingsTarget): (e: MouseEvent<HTMLAnchorElement>) => void;
156
+ /**
157
+ * 四个作用域共用的骨架(稿 §3.1、§3.7):左边分区导航、右边内容。作用域只决定导航头与分区名单;
158
+ * 摆法与手机宽度(600px)下的两页切换不变。导航是链接列表(`aria-current="page"`),不是 tablist。
159
+ */
160
+ declare function SettingsLayout({ navLabel, title, obj, crumb, groups, current, view, back, backMobile, onNavigate, mainRef, children, }: {
161
+ /** 分区导航的 aria-label(「设置分区」「项目设置分区」)。 */
162
+ navLabel: string;
163
+ title: string;
164
+ /** 导航头第二行(「只有你看得到这里」)。 */
165
+ obj?: ReactNode;
166
+ /** 导航头上方的面包屑;项目、工坊作用域的对象头沿用页面顶栏,一般不传。 */
167
+ crumb?: ReactNode;
168
+ groups: readonly SettingsGroup[];
169
+ /** 当前分区的 slug;目录页不传。 */
170
+ current?: string | undefined;
171
+ /** @default "page" */
172
+ view?: "page" | "index";
173
+ /** 详情 / 新增页头上的「‹ 列表名」:宽窄都画(稿 §3.2)。 */
174
+ back?: SettingsBackTarget | undefined;
175
+ /** 分区页给手机宽度的「‹ 设置」:只在窄屏画(稿 §3.7)。 */
176
+ backMobile?: SettingsBackTarget | undefined;
177
+ /** 页内跳转;不给就按普通链接走。 */
178
+ onNavigate?: Navigate;
179
+ /** 内容区的 ref(接线层在上面装未保存离开的守卫)。 */
180
+ mainRef?: Ref<HTMLElement>;
181
+ children: ReactNode;
182
+ }): react.JSX.Element;
183
+ /** 「‹ 列表名」:详情、新增页头上方;`mobileOnly` 是只在手机宽度画的「‹ 设置」。 */
184
+ declare function SettingsBack({ target, onNavigate, mobileOnly, }: {
185
+ target: SettingsBackTarget;
186
+ onNavigate?: Navigate | undefined;
187
+ /** @default false */
188
+ mobileOnly?: boolean;
189
+ }): react.JSX.Element;
190
+ /** 页头:标题(分区名)+ 一句说明这里管什么、谁看得到 + 主操作(靠右,一页最多一个)。 */
191
+ declare function SettingsHead({ title, desc, action, }: {
192
+ title: ReactNode;
193
+ desc?: ReactNode;
194
+ action?: ReactNode;
195
+ }): react.JSX.Element;
196
+ /** 列表:行不画框不画线,悬停垫浅底;整行进详情。 */
197
+ declare function SettingsRows({ label, children }: {
198
+ label: string;
199
+ children: ReactNode;
200
+ }): react.JSX.Element;
201
+ /**
202
+ * 一行:(可选的头像 / 图标位)名称 + 标记 / 一行元信息 / 右端最多一个快捷操作 + 进详情的箭头。
203
+ * 给了 `onOpen` 时整行可点。
204
+ */
205
+ declare function SettingsRow({ title, tags, meta, actions, leading, href, onOpen, mono, isNew, extra, }: {
206
+ title: ReactNode;
207
+ tags?: ReactNode;
208
+ meta?: readonly ReactNode[];
209
+ actions?: ReactNode;
210
+ /** 名称左边的头像或图标(成员行用 `Avatar`),占两行高。 */
211
+ leading?: ReactNode;
212
+ href?: string;
213
+ onOpen?: () => void;
214
+ /** @default false */
215
+ mono?: boolean;
216
+ /**
217
+ * 刚保存的那一行垫 `--ok-soft`(回列表时标出来)。
218
+ * @default false
219
+ */
220
+ isNew?: boolean;
221
+ /** 行内展开的一块,占满整行宽。画它时别给 `onOpen`:整行链接会盖住它。 */
222
+ extra?: ReactNode;
223
+ }): react.JSX.Element;
224
+ interface SettingsFact {
225
+ key: string;
226
+ value: ReactNode;
227
+ }
228
+ /** 详情概况:定义列表,不画框。 */
229
+ declare function SettingsFacts({ items }: {
230
+ items: readonly SettingsFact[];
231
+ }): react.JSX.Element;
232
+ /** 一节:`h2` + 可选的一句说明 + 内容;节与节之间留白,不画线、不套卡(稿 §3.1)。 */
233
+ declare function SettingsSection({ title, desc, children, }: {
234
+ title: string;
235
+ desc?: ReactNode;
236
+ children: ReactNode;
237
+ }): react.JSX.Element;
238
+ /**
239
+ * 只有一份设置的分区(提醒、批准):不分节、不画 h2(稿 §3.2),控件、说明与反馈竖排。
240
+ * 名字给 `aria-label`;里面要成组的控件自己放 `fieldset`(组件抹掉它的默认框)。
241
+ */
242
+ declare function SettingsSingle({ label, children }: {
243
+ label: string;
244
+ children: ReactNode;
245
+ }): react.JSX.Element;
246
+ /** 一排勾选(`.choice`):自动折行。 */
247
+ declare function SettingsChoices({ children }: {
248
+ children: ReactNode;
249
+ }): react.JSX.Element;
250
+ /** 起点选项块的一项:标题加一句说明。 */
251
+ interface SettingsPick<T extends string> {
252
+ value: T;
253
+ label: ReactNode;
254
+ line?: ReactNode;
255
+ }
256
+ /**
257
+ * 选项块(单选):一排块,每块一句标题、一句说明,选中的块 `--accent-soft` 底加 2px `--accent` 内描边;
258
+ * 用在「先选类型,下面再填该填的字段」的表单最前面(设置体系 §4.1;新建工坊的「从哪开始」)。
259
+ * 单选按钮藏起来(`.sr-only`),块本身是 `label`,键盘方向键照原生单选走。≤599 宽一列。
260
+ */
261
+ declare function SettingsPicks<T extends string>({ label, value, onChange, options, disabled, }: {
262
+ label: ReactNode;
263
+ value: T;
264
+ onChange: (value: T) => void;
265
+ options: readonly SettingsPick<T>[];
266
+ /** @default false */
267
+ disabled?: boolean;
268
+ }): react.JSX.Element;
269
+ /** 危险操作区:只在详情页最下面,每项一行(动作 + 后果一句 + 按钮),按钮是 `.btn.danger`(稿 §3.6)。 */
270
+ declare function SettingsDanger({ children }: {
271
+ children: ReactNode;
272
+ }): react.JSX.Element;
273
+ declare function SettingsDangerRow({ title, note, action, }: {
274
+ title: ReactNode;
275
+ note: ReactNode;
276
+ action: ReactNode;
277
+ }): react.JSX.Element;
278
+ /** 加载:页头照常画,内容区用 Band Design 的 `.tuning`(五线谱)配「正在读取<什么>…」;不画骨架条(稿 §3.3)。 */
279
+ declare function SettingsLoading({ text }: {
280
+ text: string;
281
+ }): react.JSX.Element;
282
+ /** 空:休止符插画 + 一句「还没有什么、有了能做什么」+ 主操作(没有新增权限时不画按钮)。 */
283
+ declare function SettingsEmpty({ children, action }: {
284
+ children: ReactNode;
285
+ action?: ReactNode;
286
+ }): react.JSX.Element;
287
+ /** 读失败:一行 `ErrorNote`(「<什么>没读出来:<原因>」+「重试」)。 */
288
+ declare function SettingsReadError({ children, retry }: {
289
+ children: ReactNode;
290
+ retry: () => void;
291
+ }): react.JSX.Element;
292
+ /**
293
+ * 没有权限(读 403)与环境没开通:标题、谁能看 / 缺什么、去找谁,一个离开的按钮(可不给);不画重试(稿 §3.3)。
294
+ */
295
+ declare function SettingsNoAccess({ title, children, action, }: {
296
+ title: string;
297
+ children: ReactNode;
298
+ action?: {
299
+ label: string;
300
+ onClick: () => void;
301
+ } | undefined;
302
+ }): react.JSX.Element;
303
+ /** 保存后的读屏播报(「已保存」「已删除」,不抢眼、不占版面)。 */
304
+ declare function SettingsNotice({ text }: {
305
+ text: string;
306
+ }): react.JSX.Element;
307
+ /** 「已保存」那一句(控件旁或按钮旁,停四拍由调用方的 `useSavedNote` 管)。 */
308
+ declare function SettingsSaved({ text, }: {
309
+ /** @default "已保存" */
310
+ text?: ReactNode;
311
+ }): react.JSX.Element;
312
+ /**
313
+ * 确认弹窗(稿 §3.6):`--scrim`、`--shadow-pop`、`--r-xl`;标题问动作,正文列后果,末尾写能不能恢复。
314
+ * 不用输入名字确认:弹窗已列后果,多打一遍字不增加信息。
315
+ */
316
+ declare function SettingsDialog({ title, children, actions, onClose, }: {
317
+ title: string;
318
+ children: ReactNode;
319
+ actions: ReactNode;
320
+ onClose: () => void;
321
+ }): react.JSX.Element;
322
+ /** 设置里的表单:字段竖排,最宽 560。提交走 `onSubmit`(已 `preventDefault`)。 */
323
+ declare function SettingsForm({ label, onSubmit, children, }: {
324
+ label?: string;
325
+ onSubmit?: () => void;
326
+ children: ReactNode;
327
+ }): react.JSX.Element;
328
+ /** 字段的输入要挂的属性:id、读屏说明、出错标记。 */
329
+ interface SettingsFieldProps {
330
+ id: string;
331
+ "aria-describedby"?: string;
332
+ "aria-invalid"?: true;
333
+ }
334
+ /**
335
+ * 字段行:标签(必填写「必填」)、输入、下一行的提示或出错、计数。提示 / 出错 / 计数用 Band Design 的
336
+ * `.field-note`(出错加 `.err`)与 `.field-count`(DESIGN.md「控件」),出错时输入挂 `aria-invalid`。
337
+ * 输入本身由调用方用 Band Design 的 `.field` 画,组件只摆位置、接好 id 与读屏说明。
338
+ */
339
+ declare function SettingsField({ label, required, optional, hint, error, count, over, children, }: {
340
+ label: ReactNode;
341
+ /** @default false */
342
+ required?: boolean;
343
+ /**
344
+ * 选填:标签旁写「选填」(稿 §3.5 的样张两种都标);与 `required` 不同时给。
345
+ * @default false
346
+ */
347
+ optional?: boolean;
348
+ hint?: ReactNode;
349
+ /** 出错的话;有它时不画提示。 */
350
+ error?: ReactNode;
351
+ /** 计数(「12 / 200」),靠右。 */
352
+ count?: ReactNode;
353
+ /**
354
+ * 计数超了:计数变红。
355
+ * @default false
356
+ */
357
+ over?: boolean;
358
+ children: (props: SettingsFieldProps) => ReactNode;
359
+ }): react.JSX.Element;
360
+ /** 表单末尾的操作行:按钮 + 保存反馈 / 还缺什么。 */
361
+ declare function SettingsActions({ children, end, }: {
362
+ children: ReactNode;
363
+ /** @default false */
364
+ end?: boolean;
365
+ }): react.JSX.Element;
366
+ /**
367
+ * 保存反馈(稿 §3.5):`saving` 时写在做什么(「正在验证…」那一档的旁注),`saved` 停四拍的「已保存」,
368
+ * `failed` 是贴在按钮旁的整体错误(「没保存:」开头),`missing` 是按钮置灰时缺什么(「还差 key 没填」)。
369
+ * 不用 Toast;读屏走 `aria-live`。
370
+ */
371
+ declare function SettingsSaveState({ saving, saved, failed, missing, }: {
372
+ saving?: ReactNode;
373
+ /** `true` 写「已保存」;给文字或节点就照它写(「已保存,ModelGate 验证通过」)。 */
374
+ saved?: ReactNode;
375
+ failed?: ReactNode;
376
+ missing?: ReactNode;
377
+ }): react.JSX.Element;
378
+
379
+ /** 一个人。`id` 是 ldap;`path` 是部门路径(「研发中心 / 平台组」),只用来看清是谁。 */
380
+ interface PickerPerson {
381
+ id: string;
382
+ name: string;
383
+ path?: string;
384
+ /** 部门 id 链(「/」隔开,`1/5/9`),算部门勾选态用;推不出时没有。 */
385
+ chain?: string;
386
+ /** false:还没登录过 Band(名字从组织架构来)。不影响能不能选,只在已选名单里标一句。 */
387
+ inBand?: boolean;
388
+ }
389
+ /** 一个部门。`count` 是含下级部门的总人数;`count` 与 `chain` 都有才画勾选框。 */
390
+ interface PickerOrg {
391
+ id: string;
392
+ name: string;
393
+ path?: string;
394
+ chain?: string;
395
+ count?: number;
396
+ }
397
+ /** 不能选的人:原因写在候选行上;带 `chain` 时从部门的可选人数里扣掉。 */
398
+ type BlockedPerson = Blocked;
399
+ /** 目录的一页:一层部门的下级部门与直属的人,或一次搜索的结果。 */
400
+ interface DirectoryPage {
401
+ orgs: readonly PickerOrg[];
402
+ people: readonly PickerPerson[];
403
+ /** 搜索结果被上游截断了:提示换个更准的词。 */
404
+ truncated?: boolean;
405
+ /** 组织架构读不到、退回了 Band 用户目录:写原因,弹层顶上一直显示。 */
406
+ fallback?: string;
407
+ }
408
+ /** 数据口。所有方法收 `signal`:换词、关弹层时取消上一次。 */
409
+ interface PersonDirectory {
410
+ /** 组织架构现在用不了时的原因(退回了 Band 用户目录):没搜之前也在弹层顶上显示。 */
411
+ unavailable?: string;
412
+ search(q: string, opts: {
413
+ signal: AbortSignal;
414
+ }): Promise<DirectoryPage>;
415
+ /** 按部门浏览;`null` 是根。没有这个方法就只能搜。 */
416
+ browse?(orgId: string | null, opts: {
417
+ signal: AbortSignal;
418
+ chain?: string;
419
+ }): Promise<DirectoryPage>;
420
+ /** 一个部门(含下级)的全部人,最多 `limit` 个;`total` 是真实总数。 */
421
+ members?(orgId: string, opts: {
422
+ signal: AbortSignal;
423
+ limit: number;
424
+ chain?: string;
425
+ }): Promise<{
426
+ people: readonly PickerPerson[];
427
+ total: number;
428
+ }>;
429
+ /** 粘贴多个 ldap 时按 ldap 批量解析;找不到的放 `missing`。 */
430
+ resolve?(ids: readonly string[], opts: {
431
+ signal: AbortSignal;
432
+ }): Promise<{
433
+ people: readonly PickerPerson[];
434
+ missing: readonly string[];
435
+ /** 只能认出一部分人的原因(组织架构读不到):写进提示,免得用户以为 ldap 写错了。 */
436
+ fallback?: string;
437
+ }>;
438
+ }
439
+ interface PersonSearchProps {
440
+ /** 输入框的无障碍名(「添加管理员」「加人」)。 */
441
+ label: string;
442
+ /** 输入框的 id(可见 `<label htmlFor>` 指向它,如 `SettingsField` 给的 `id`)。 */
443
+ inputId?: string;
444
+ /** 输入框的说明链(如 `SettingsField` 给的 `aria-describedby`)。 */
445
+ describedBy?: string;
446
+ directory: PersonDirectory;
447
+ /** 已选的人:在候选里打勾(多选)或显示在输入框里(单选),不再重复加。 */
448
+ picked: readonly PickerPerson[];
449
+ /** 选中的人(单选一个;多选可能是整个部门或一次粘贴的一批,已按 ldap 去重)。 */
450
+ onPick(people: readonly PickerPerson[]): void;
451
+ /** 取消选中(多选里点已勾的人、取消整个部门;单选里点 ×)。 */
452
+ onUnpick?(ids: readonly string[]): void;
453
+ /** @default false */
454
+ multiple?: boolean;
455
+ /** 还能再加几个人(名单上限减去已选);不给就不限。 */
456
+ room?: number;
457
+ /**
458
+ * 不能选的人与原因(「已经是管理员」)。
459
+ * @default []
460
+ */
461
+ disabled?: readonly BlockedPerson[];
462
+ /**
463
+ * 目录里没有的 ldap 也能加(名字先写 ldap)。
464
+ * @default false
465
+ */
466
+ allowUnknown?: boolean;
467
+ /** 搜索词;给了就由宿主管值,与 onQueryChange 配合,让表单能保护尚未加入名单的输入。 */
468
+ query?: string;
469
+ /** 用户输入或选择使搜索词变化时通知宿主;不给 query 时仍由组件自己记。 */
470
+ onQueryChange?(query: string): void;
471
+ /**
472
+ * 手动输入与粘贴的账号形状;分享兼容历史账号用 account(contracts 的 isUsableId),缺省仍只收 ldap。读回的人不再判。
473
+ * @default "ldap"
474
+ */
475
+ unknownIdKind?: "ldap" | "account";
476
+ placeholder?: string;
477
+ /**
478
+ * 整个控件禁用(保存中)。
479
+ * @default false
480
+ */
481
+ busy?: boolean;
482
+ /**
483
+ * 根的名字(浏览时路径的第一段)。
484
+ * @default "全部门"
485
+ */
486
+ rootLabel?: string;
487
+ /**
488
+ * 取到一个部门的全员时,把带部门链的人交给宿主(宿主拿来给名单里已有、还没链的人补链,省一次解析)。
489
+ * 包括已经在名单里、这次没有新加的人。
490
+ */
491
+ onLearn?(people: readonly PickerPerson[]): void;
492
+ /**
493
+ * 一开始就展开(样张、设计站用)。
494
+ * @default false
495
+ */
496
+ defaultOpen?: boolean;
497
+ /**
498
+ * 一开始的搜索词(样张用)。
499
+ * @default ""
500
+ */
501
+ defaultQuery?: string;
502
+ /**
503
+ * 一开始浏览到哪(从根往下的部门,样张用)。
504
+ * @default []
505
+ */
506
+ defaultTrail?: readonly PickerOrg[];
507
+ }
508
+ /** 搜索框 + 弹层:搜人、按部门逐级进入、勾整个部门、粘贴多个 ldap。 */
509
+ declare function PersonSearch({ label, inputId, describedBy, directory, picked, onPick, onUnpick, multiple, room, disabled, allowUnknown, query: controlledQuery, onQueryChange, unknownIdKind, placeholder, busy, rootLabel, onLearn, defaultOpen, defaultQuery, defaultTrail, }: PersonSearchProps): react.JSX.Element;
510
+ interface PersonPickerProps extends Omit<PersonSearchProps, "picked" | "onPick" | "onUnpick" | "room" | "multiple"> {
511
+ /** 受控:名单上的人,按加入先后。 */
512
+ value: readonly PickerPerson[];
513
+ onChange(next: readonly PickerPerson[]): void;
514
+ /** 名单上限(同服务端)。 */
515
+ max?: number;
516
+ /**
517
+ * 只读:只列名单,没有加人和移出。
518
+ * @default false
519
+ */
520
+ readOnly?: boolean;
521
+ /**
522
+ * 移出前在行内再确认一次(改动即时生效的名单用;有「保存」的表单不用)。
523
+ * @default false
524
+ */
525
+ confirmRemove?: boolean;
526
+ /**
527
+ * 名单为空时的一句话。
528
+ * @default "还没有人"
529
+ */
530
+ emptyText?: string;
531
+ /**
532
+ * 这些人不能移出与原因(「创建人」);取消整个部门时也不动他们。
533
+ * @default {}
534
+ */
535
+ locked?: Readonly<Record<string, string>>;
536
+ /** 换掉下面的加人框(一次加一个、要另填角色再提交的地方:放单选的 `PersonSearch` 和提交按钮)。 */
537
+ addSlot?: ReactNode;
538
+ }
539
+ /** 名单 + 加人:已选的人一行一个(头像、名字、ldap、部门),可移出;下面是多选的 `PersonSearch`。 */
540
+ declare function PersonPicker({ value, onChange, max, readOnly, confirmRemove, emptyText, locked, addSlot, label, ...search }: PersonPickerProps): react.JSX.Element;
541
+ /**
542
+ * 选人的数据口:宿主给了 `ctx.people` 就按组织架构选(没登录过 Band 的人也搜得到、能按部门浏览);老宿主没有时退回
543
+ * 原来的用户目录搜索(各设置接口上的 `searchUsers`:只有登录过 Band 的人,只能搜、不能按部门浏览);连 `searchUsers` 也没有
544
+ * (如内测名单)就只能按 ldap 加、粘贴多个 ldap。两种退路都在弹层顶上写明原因。
545
+ */
546
+ declare function directoryFor(people: PeopleApi | undefined, searchUsers?: (q: string) => Promise<readonly {
547
+ id: string;
548
+ displayName: string;
549
+ }[]>): PersonDirectory;
550
+ /** 把宿主的人员目录(`ctx.people`)接成选择器的数据口。取消信号不往下传:过期的结果组件自己丢掉。 */
551
+ declare function peopleDirectory(api: PeopleApi): PersonDirectory;
552
+
553
+ /** 名单里的一个人:至少有 id,链可选(其余字段原样保留)。 */
554
+ interface ChainedEntry {
555
+ id: string;
556
+ chain?: string | undefined;
557
+ }
558
+ interface PersonList<T extends ChainedEntry> {
559
+ /** 名单(链都已从缓存填好)。 */
560
+ list: T[];
561
+ /** 读回或保存回包:写进名单,并给缓存里没有的人补一次链。 */
562
+ load(people: readonly T[]): void;
563
+ /** 选人框改了名单(加人、移出、整部门)。 */
564
+ onChange(next: readonly T[]): void;
565
+ /** 整部门取回的全员(`PersonPicker` 的 `onLearn`)。 */
566
+ onLearn(people: readonly ChainedEntry[]): void;
567
+ /** 名单里还没链的人数;没有部门树、组织架构没接上或还没补过时是 0。 */
568
+ noChain: number;
569
+ }
570
+ declare function usePersonList<T extends ChainedEntry>(directory: PersonDirectory): PersonList<T>;
571
+
572
+ /**
573
+ * 回合轨迹的视图模型(纯函数,不碰 React):把 `TurnState` 已有的 `steps` / `step` / `log` / `activity` / `usualMs`
574
+ * 折成一条竖向轨迹。协议里没有每步的用时与子步归属,所以:
575
+ *
576
+ * - 有 `steps`:每一步一条,正在做的那一步带上「在做什么」和流水(流水是整回合的,挂在当前步下面,
577
+ * 超过几行时给「看全部 N 行」);每一步都做完、回合还在收尾时补一条「现在」。
578
+ * - 没有 `steps`(本仓库的宿主一直给空数组):流水本身就是轨迹,最后一行是「现在」。
579
+ * - `activity` 与流水都没有:退回一行摘要,不放会动的圆点。
580
+ *
581
+ * 停止与重试不在这里:那是锁定插件 turn-bar 的按钮,轨迹只写状态与「去哪里点」。
582
+ */
583
+
584
+ /** 流水默认显示最后几行:面板里看的是「现在」,更早的收起来。 */
585
+ declare const LOG_TAIL = 6;
586
+ /** 条目左侧那个圆点的样子。 */
587
+ type Mark = "done" | "now" | "wait" | "next" | "failed" | "stopped";
588
+ interface SubItem {
589
+ text: string;
590
+ /** 最后一行(正在做)用 Agent 蓝的实心点,其余灰点。 */
591
+ now?: boolean;
592
+ }
593
+ interface TraceItem {
594
+ key: string;
595
+ mark: Mark;
596
+ /** 读屏念的状态词(视觉上只是一个圆点)。 */
597
+ state: string;
598
+ title: string;
599
+ detail?: string;
600
+ /** 细节那一行是不是失败的原因(红)。 */
601
+ detailTone?: "bad";
602
+ /** 细节下面再一行灰字(结束时写「用时 X」)。 */
603
+ meta?: string;
604
+ subs?: SubItem[];
605
+ /** 有流水可以收起 / 展开(只有正在做的那一步有,展开着时同时给 `subs`)。 */
606
+ canExpand?: boolean;
607
+ /** 右侧的小字(用时、时刻)。 */
608
+ side?: string;
609
+ /** 门禁这类徽标。 */
610
+ badge?: string;
611
+ /** 「现在」这一条:灰掉的圆点,不做动画(activity 与流水都没有时)。 */
612
+ quiet?: boolean;
613
+ }
614
+ interface Trail {
615
+ /** 头部左边:谁在跑。 */
616
+ title: string;
617
+ /** 头部右边:步骤进度或已用时间。 */
618
+ side?: string;
619
+ items: TraceItem[];
620
+ /** 轨迹下面那一行:失败了去哪里重试、门禁在等谁。 */
621
+ banner?: {
622
+ lead: string;
623
+ text: string;
624
+ };
625
+ /** 没有 steps 也没有流水时,子步(流水)要不要展开、能不能展开。 */
626
+ log?: {
627
+ count: number;
628
+ open: boolean;
629
+ };
630
+ }
631
+ interface TrailOpts {
632
+ /** 已用毫秒;宿主没给 `startedAt` 时是 null。 */
633
+ elapsed: number | null;
634
+ /** 有 steps 时,当前步骤下面的流水展开着没有。 */
635
+ subsOpen: boolean;
636
+ /** 没有 steps 时,流水显示全部还是只显示最后几行。 */
637
+ allLog: boolean;
638
+ /** agent / 成员 id → 显示名。 */
639
+ name: (id: string) => string;
640
+ /** 阶段 id → 显示名。 */
641
+ stageName: (id: string) => string;
642
+ /** 此刻在等批准的门禁阶段(已经交出来、还没批);没有是 undefined。 */
643
+ gate?: string;
644
+ }
645
+ /** 一回合的轨迹;项目还没跑过回合时返回 undefined(空态由界面画)。 */
646
+ declare function trailOf(turn: TurnState, opts: TrailOpts): Trail | undefined;
647
+
648
+ /** props 表用得到的名字:视图模型与类型一并从子路径导出,`AgentTrace` 只认它收到的 props。 */
649
+ interface AgentTraceProps {
650
+ /** `ctx.turns.state()` 读回来的回合状态:`current` 在跑、否则画 `last`;两者都没有画 `empty`。 */
651
+ turn: TurnState;
652
+ /** 已用毫秒;宿主没给 `startedAt` 时传 null(头部与当前步不写已用)。 */
653
+ elapsed: number | null;
654
+ /** agent / 成员 id → 显示名(如 `memberName(members, id)`)。 */
655
+ name: (id: string) => string;
656
+ /** 阶段 id → 显示名(门禁那一行写等的是哪个阶段)。 */
657
+ stageName: (id: string) => string;
658
+ /** 此刻在等批准的门禁阶段(已交付、还没批);没有就不画那一行。 */
659
+ gate?: string;
660
+ /** 一次回合都没跑过时画的东西(空态说明由调用方给);不给就什么都不画。 */
661
+ empty?: ReactNode;
662
+ }
663
+ declare function AgentTrace({ turn, elapsed, name, stageName, gate, empty }: AgentTraceProps): react.JSX.Element;
664
+
665
+ /** 一次回合要画的数据:{@link AgentRun} 只用这些字段,宿主给的回合状态(`TurnState.current`)直接符合。 */
666
+ interface AgentRunTurn {
667
+ /** 回合所属修改请求的 id;`stopOnPage` 时写进 `data-band-turn-status`。 */
668
+ changeRequestId: string;
669
+ /** 在做这件事的 Agent 的 id。 */
670
+ agent: string;
671
+ /** 回合开始的时刻(ISO);不给就不显示用时。 */
672
+ startedAt?: string | undefined;
673
+ /** 回合摘要:宿主没给 `activity` 时当正文。 */
674
+ summary: string;
675
+ /** 现在在做什么:`note` 是一句给成员看的话,`action` 是「动词 + 路径」。 */
676
+ activity?: {
677
+ note?: string | undefined;
678
+ action?: string | undefined;
679
+ } | undefined;
680
+ /** 步骤名;空数组不画步骤列表。 */
681
+ steps: readonly string[];
682
+ /** 正在进行的步骤下标:之前的算做完,之后的算还没到。 */
683
+ step: number;
684
+ /** 有人点了停止、在等收尾;`by` 是点的人的 id。 */
685
+ stopping?: {
686
+ by: string;
687
+ } | undefined;
688
+ /** 很久没有新进展的判断依据;不给就不提示。 */
689
+ stall?: StallView | undefined;
690
+ }
691
+ interface AgentRunProps {
692
+ turn: AgentRunTurn;
693
+ /** 成员表:用来把 id 换成显示名;没有(刚开始读)时 Rondo 写「Rondo」,其余写 id。 */
694
+ members: readonly MemberView[] | undefined;
695
+ /** 名字后面的一小段(如「改「讲义」」「回合 #3」);不给就只写名字。 */
696
+ context?: ReactNode;
697
+ /**
698
+ * 「停止」插槽:放在状态下面,不在读屏播报区里。宿主放自己的 `StopTurn`(先问再停、没有权限不显示);不给就没有。
699
+ * 正在停下(`turn.stopping`)时不画,那句话已经说明白了。
700
+ */
701
+ stop?: ReactNode;
702
+ /**
703
+ * 页面上这条状态带着「停止」:在外层标 `data-band-turn-status`(值是回合 id),回合栏据此不再重复写一份。
704
+ * 缺省随 `stop` 里有没有真东西(不是 undefined、null、false、空串);宿主因没有权限没放 `stop`、但仍要占住回合栏的位置时,显式传 true。
705
+ * @default 随 stop 是否存在
706
+ */
707
+ stopOnPage?: boolean;
708
+ }
709
+ declare function AgentRun({ turn, members, context, stop, stopOnPage }: AgentRunProps): react.JSX.Element;
710
+
711
+ /** 「已用」:从 `startedAt` 起,按页面共用的那只表走。没有开始时刻返回 null。 */
712
+ declare function useElapsed(startedAt: string | undefined): number | null;
713
+ /**
714
+ * 页面共用的那只表的当前时刻(毫秒):长回合的「已 N 分钟没有新进展」跟着它走,和「已用」同一拍。
715
+ * `active` 为假时不起表(没在跑的回合不用每秒钟重画)。
716
+ */
717
+ declare function useNow(active?: boolean): number;
718
+
719
+ /** 显示名;成员表里还没有(刚开始、成员表没重读完)时按 `agentDisplayName` 的规则:Rondo 写「Rondo」,其余写 id。 */
720
+ declare function memberDisplayName(members: readonly MemberView[] | undefined, id: string): string;
721
+
722
+ declare const TURN_STATUS_ATTR = "data-band-turn-status";
723
+ /** 页面上现在有没有这个回合的、看得见的带「停止」的状态消息。订阅期间随文档变化更新。 */
724
+ declare function useTurnStatusOnPage(changeRequestId: string): boolean;
725
+
726
+ declare function useMessageList<T extends HTMLElement>(): {
727
+ ref: RefObject<T | null>;
728
+ onKeyDown: (e: KeyboardEvent<T>) => void;
729
+ onFocus: (e: FocusEvent<T>) => void;
730
+ };
731
+
732
+ interface TooltipProps {
733
+ /** 纯文字,几个字。不能放链接、按钮(提示不可聚焦);要可交互的内容用 Popover。 */
734
+ label: string;
735
+ /** 触发器:一个可聚焦元素(通常是 button / .iconbtn)。 */
736
+ children: ReactElement;
737
+ /**
738
+ * 缺省 top,放不下翻面。
739
+ * @default "top"
740
+ */
741
+ side?: "top" | "bottom" | "left" | "right";
742
+ /** 快捷键提示,如 "⌘K",画在文字右边。只是文字:不绑定按键(按键绑定在各自的处理函数里)。 */
743
+ shortcut?: string;
744
+ }
745
+ /**
746
+ * 同一个按钮既要提示又要弹菜单时,写成 `<Menu trigger={<Tooltip label="更多"><button /></Tooltip>} …/>`:
747
+ * Menu 把触发器要的 props 与 ref 递给 Tooltip,Tooltip 与里面那个按钮自己的 props 合并:同名的 onXxx 都跑、
748
+ * ref 都拿到(公开的 props 只有 `TooltipProps`)。
749
+ */
750
+ declare function Tooltip(props: TooltipProps): react.JSX.Element;
751
+
752
+ type MenuEntry = {
753
+ kind?: "item";
754
+ id: string;
755
+ label: string;
756
+ onSelect: () => void;
757
+ disabled?: boolean;
758
+ /** 危险动作:字用 --bad;别放在第一项 */
759
+ danger?: boolean;
760
+ /** 快捷键提示,只是文字,不绑定按键 */
761
+ shortcut?: string;
762
+ /** 灰色的一行补充说明 */
763
+ hint?: string;
764
+ } | {
765
+ kind: "check";
766
+ id: string;
767
+ label: string;
768
+ checked: boolean;
769
+ onCheckedChange: (next: boolean) => void;
770
+ disabled?: boolean;
771
+ } | {
772
+ kind: "separator";
773
+ } | {
774
+ kind: "group";
775
+ label: string;
776
+ items: readonly MenuEntry[];
777
+ };
778
+ interface MenuProps {
779
+ /** 菜单的无障碍名(也用于触发器没有文字时) */
780
+ label: string;
781
+ /** 触发器:一个 button 元素 */
782
+ trigger: ReactElement;
783
+ items: readonly MenuEntry[];
784
+ /**
785
+ * 缺省 bottom,放不下翻面
786
+ * @default "bottom"
787
+ */
788
+ side?: "bottom" | "top";
789
+ /**
790
+ * 缺省 start:贴着触发它的元素弹出,左边对齐,右边放不下改右对齐(DESIGN.md)
791
+ * @default "start"
792
+ */
793
+ align?: "start" | "end";
794
+ }
795
+ declare function Menu({ label, trigger, items, side, align }: MenuProps): react.JSX.Element;
796
+
797
+ interface DialogProps {
798
+ open: boolean;
799
+ onOpenChange: (open: boolean) => void;
800
+ title: string;
801
+ description?: ReactNode;
802
+ children?: ReactNode;
803
+ /**
804
+ * 底部动作区里调用方自己的按钮,主按钮放最右。动作区**固定**在最左带一个关闭按钮(Dialog 没有右上角 ×,
805
+ * 触屏上也没有 Esc),所以这里别再放取消。
806
+ */
807
+ actions?: ReactNode;
808
+ /**
809
+ * 关闭按钮的字。
810
+ * @default 传了 `actions` 时「取消」,没传时「关闭」
811
+ */
812
+ closeLabel?: string;
813
+ /**
814
+ * 缺省 md
815
+ * @default "md"
816
+ */
817
+ size?: "sm" | "md" | "lg";
818
+ /**
819
+ * 进行中不许关:false 时 Esc 与点遮罩都不关。缺省 true
820
+ * @default true
821
+ */
822
+ dismissible?: boolean;
823
+ }
824
+ declare function Dialog({ open, onOpenChange, title, description, children, actions, closeLabel, size, dismissible, }: DialogProps): react.JSX.Element;
825
+ interface ConfirmDialogProps {
826
+ open: boolean;
827
+ onOpenChange: (open: boolean) => void;
828
+ title: string;
829
+ /** 写清后果:会删掉什么、能不能找回 */
830
+ consequence: ReactNode;
831
+ /** 确认按钮写动作本身(「删除工坊」),不写「确定」。进行中时调用方换成进行中的说法(「删除中…」) */
832
+ confirmLabel: string;
833
+ /**
834
+ * 缺省「取消」
835
+ * @default "取消"
836
+ */
837
+ cancelLabel?: string;
838
+ /** @default false */
839
+ danger?: boolean;
840
+ /**
841
+ * 进行中:确认按钮 aria-disabled 并转圈,取消、Esc 都不能关
842
+ * @default false
843
+ */
844
+ busy?: boolean;
845
+ /** 点确认:不会自己关,成功后由调用方把 `open` 置为 false(失败要留在这里重试) */
846
+ onConfirm: () => void;
847
+ }
848
+ declare function ConfirmDialog({ open, onOpenChange, title, consequence, confirmLabel, cancelLabel, danger, busy, onConfirm, }: ConfirmDialogProps): react.JSX.Element;
849
+
850
+ /** 下拉里的一项。`group` 相同的排在一段,段的顺序按它第一次出现的顺序。 */
851
+ interface ComboboxItem {
852
+ value: string;
853
+ label: string;
854
+ group?: string;
855
+ /** 行尾的补充说明(部门、类型),用等宽字体。 */
856
+ meta?: string;
857
+ /** label 之外用来搜索的文字(部门、拼音备注),不进占位提示。 */
858
+ keywords?: string;
859
+ }
860
+ interface ComboboxProps {
861
+ /** 输入框的无障碍名,也是空结果那句「没有匹配的<label>」里的名字。 */
862
+ label: string;
863
+ items: readonly ComboboxItem[];
864
+ /** 受控:已选的值,按选中的先后。 */
865
+ value: readonly string[];
866
+ onChange(next: readonly string[]): void;
867
+ /**
868
+ * 多选:回车与空格切换选中、列表不关;单选:回车选中并关闭。
869
+ * @default false
870
+ */
871
+ multiple?: boolean;
872
+ placeholder?: string;
873
+ /** 空结果那一行的整句,缺省「没有匹配的<label>」。 */
874
+ emptyText?: string;
875
+ /**
876
+ * 查询非空、且没有名字正好相同的候选时,列表末尾多一行「新建」。选中它时把这句查询交回调用方
877
+ * (建完由调用方把新值放进 `value`)。
878
+ */
879
+ onCreate?(name: string): void;
880
+ /** 「新建」那行的写法,缺省「新建「<查询>」」。 */
881
+ createLabel?(name: string): string;
882
+ /** @default false */
883
+ disabled?: boolean;
884
+ /**
885
+ * 候选正在取(调用方边搜边取时):列表里画一行「加载中…」,已有的候选照常显示,空结果那句不说。
886
+ * 只是显示状态:控件不取数,候选仍由调用方给。
887
+ * @default false
888
+ */
889
+ loading?: boolean;
890
+ /** 候选取失败:列表里画这一句(写明原因与怎么办),已有的候选照常显示,空结果那句不说。同时 `loading` 时先说失败。 */
891
+ error?: string;
892
+ /**
893
+ * 自由输入(只用于单选,`multiple` 时忽略):输入框里的字就是值,候选只是建议。每敲一个字就经
894
+ * `onChange([文字])` 交回;选中候选把它的 `value` 写进框里;没用方向键或鼠标挪到某个候选时回车保留原文,
895
+ * 不会被首个候选顶替。值不画成 chip、不出「没有匹配的」与「新建」行(`emptyText`、`onCreate`、`createLabel`
896
+ * 在这个模式下不用)。输入框空着时 `value` 是 `[]`。
897
+ */
898
+ allowCustom?: boolean;
899
+ /**
900
+ * 透传给输入框的少数原生属性(`label` 之外的 id、长度上限与校验关联),读屏名仍是 `label`。
901
+ * 调用方在外面自画可见的 `<label htmlFor>` 时靠 `id` 关联。只在 `allowCustom` 下有效(`multiple` 时 `allowCustom` 被忽略,`inputProps` 一并无效),运行时只取这四个键,别的键不落到输入框。
902
+ */
903
+ inputProps?: ComboboxInputProps;
904
+ /**
905
+ * 候选一出现(`items` 从无到有或换了一批)就展开列表,不等聚焦。给「填完 key 就想看到可选项」的场景,
906
+ * 只在 `allowCustom` 下有效;焦点进了别的控件时收起,不留一个没人管的下拉。
907
+ */
908
+ autoOpen?: boolean;
909
+ }
910
+ /** `inputProps` 允许的原生属性:只放不改变控件语义的几项。 */
911
+ type ComboboxInputProps = Pick<InputHTMLAttributes<HTMLInputElement>, "id" | "maxLength" | "aria-invalid" | "aria-describedby">;
912
+ /**
913
+ * 可搜索的选择,两种写法:缺省是「值是候选里选出来的」(单选 / 多选,见 {@link ComboboxProps});
914
+ * `allowCustom` 且单选时是「文字即值」的自由输入。
915
+ */
916
+ declare function Combobox(props: ComboboxProps): react.JSX.Element;
917
+ /**
918
+ * 一段文字拆成标签:按逗号(半角、全角)、换行、制表符拆,去掉首尾空白与空串,**不去重**
919
+ * (重复要提示,不能悄悄吃掉)。纯函数,单测与 TagInput 共用。
920
+ */
921
+ declare function splitTags(text: string): string[];
922
+ /**
923
+ * 数组值(样张 §2「Tag Input」):值受控,回车或逗号确认一个,粘贴带分隔符时整段拆开;重复的值不加入,
924
+ * 已有的那个闪一下红底并在下面写一句(「「x」重复了,已跳过」,1.8 秒后退回);输入框空着时退格删最后一个。
925
+ *
926
+ * 输入法:回车、退格都经 `withImeGuard`——组字中选字的回车不能当成「加一个标签」。
927
+ */
928
+ declare function TagInput({ label, value, onChange, placeholder, hint, disabled, id, }: {
929
+ /** 输入框的无障碍名。 */
930
+ label: string;
931
+ /** 受控:标签,按加入的先后。 */
932
+ value: readonly string[];
933
+ onChange(next: readonly string[]): void;
934
+ placeholder?: string;
935
+ /** 常态那句说明(「粘贴「五年级, 分数」会拆成两个」);重复时换成提示,1.8 秒后退回这句。 */
936
+ hint?: string;
937
+ /** @default false */
938
+ disabled?: boolean;
939
+ id?: string;
940
+ }): react.JSX.Element;
941
+ /** 筛选项:一段里的一个值。 */
942
+ interface FilterOption {
943
+ value: string;
944
+ label: string;
945
+ }
946
+ /** 一段筛选:`key` 是行数据里的字段名。 */
947
+ interface FilterGroup {
948
+ key: string;
949
+ label: string;
950
+ options: readonly FilterOption[];
951
+ }
952
+ /** 一行在各分组上的取值(`row[group.key]`)。 */
953
+ type FilterRow = Readonly<Record<string, string>>;
954
+ /** 已选:分组 key → 选中的值(段内是「或」)。 */
955
+ type FilterSelection = Readonly<Record<string, readonly string[]>>;
956
+ /**
957
+ * 计数(样张 §2「Filter Menu」的 faceted 口径):某个选项的计数 = 在**其他**分组的已选条件下还剩多少行,
958
+ * 也带自己这一段——和产物库的「勾了别的组,这一段的数跟着缩」同一口径。纯函数,单测与 FilterMenu 共用。
959
+ */
960
+ declare function facetedCount(rows: readonly FilterRow[], groups: readonly FilterGroup[], selection: FilterSelection, groupKey: string, value: string): number;
961
+ /** 按已选筛行:每组内是「或」,组之间是「且」。纯函数。 */
962
+ declare function filterRows(rows: readonly FilterRow[], groups: readonly FilterGroup[], selection: FilterSelection): readonly FilterRow[];
963
+ /**
964
+ * 分组筛选(样张 §2「Filter Menu」)。分组可折叠(组标题是按钮,`aria-expanded`),计数按当前其他分组
965
+ * 的已选算(`facetedCount`),已选的做成 chip 可单个移除,右端「清空」。值受控。
966
+ *
967
+ * 键盘:组标题与每个勾选框都在正常的 Tab 顺序里(勾选框是原生 `<input type="checkbox">`),空格切换;
968
+ * 点组标题只折叠/展开,不改筛选。
969
+ */
970
+ declare function FilterMenu({ groups, rows, value, onChange, emptyText, }: {
971
+ groups: readonly FilterGroup[];
972
+ /** 用来算计数的行(通常是未筛选的全量;传筛过的会让计数越筛越小)。 */
973
+ rows: readonly FilterRow[];
974
+ value: FilterSelection;
975
+ onChange(next: FilterSelection): void;
976
+ /** 一段里一个选项都没有时那一行,缺省「没有可筛的」。 */
977
+ emptyText?: string;
978
+ }): react.JSX.Element;
979
+
980
+ /** 宿主画的一次性容器;一页只有一个(`band-shell`)。插件调 `toast()`,不自己画。 */
981
+ declare function ToastHost(): react.JSX.Element;
982
+
983
+ /**
984
+ * 页面里的 toast(backlog #5):刚做完一件事的即时回执。宿主(外壳)画唯一一层容器 `ToastHost`,
985
+ * 插件与锁定插件只 import 这里的 `toast()` 入队,不自己画容器——两个插件同时弹也落进同一摞,不会各画一层。
986
+ *
987
+ * 模块级 store 是有意为之:`@kanyun-ai-infra/band-plugin-react` 是宿主提供的共享模块,宿主与每个插件拿到同一个
988
+ * 实例;而每个插件各开一个 React root,React context 跨不过去,ctx 也没有这个能力(加它要改协议)。
989
+ *
990
+ * 规则照样张:
991
+ * - 成功 4 秒自己收;鼠标停在上面时不收,移开后 2 秒再收;
992
+ * - 错误不自己走,要么点「重试」要么关掉(没给动作时容器补一个「关闭」);
993
+ * - 进行中做完在同一条里变成勾(用同一个 id 再调一次 `toast`),不新弹一条;
994
+ * - 同时最多三条,第四条挤掉最早的一条(进行中的先留着)。
995
+ *
996
+ * 模块级状态跟着页面活:测试要清干净用 `dismissAllToasts`。
997
+ */
998
+ type ToastKind = "ok" | "bad" | "busy";
999
+ /** toast 上的一个动作(错误一般是「重试」)。 */
1000
+ interface ToastAction {
1001
+ label: string;
1002
+ onClick: () => void;
1003
+ }
1004
+ interface ToastOptions {
1005
+ /** 缺省 `ok`。 */
1006
+ kind?: ToastKind;
1007
+ /** 一行说明。 */
1008
+ text: string;
1009
+ /** 第二行小字。 */
1010
+ detail?: string;
1011
+ /** 一个动作;错误的「重试」放这里。 */
1012
+ action?: ToastAction;
1013
+ /** 传已有的 id:改那一条(进行中做完变成勾),不新弹一条。 */
1014
+ id?: string;
1015
+ }
1016
+ interface ToastItem {
1017
+ id: string;
1018
+ kind: ToastKind;
1019
+ text: string;
1020
+ detail?: string;
1021
+ action?: ToastAction;
1022
+ }
1023
+ /** 弹一条;传 `id` 就是改那一条。返回它的 id。 */
1024
+ declare function toast(opts: ToastOptions): string;
1025
+ /** 收起一条(动作、Esc、关掉都走这里)。 */
1026
+ declare function dismissToast(id: string): void;
1027
+ /** 全部收掉(换身份、测试收尾)。 */
1028
+ declare function dismissAllToasts(): void;
1029
+
1030
+ export { AgentAvatar, AgentRun, type AgentRunProps, type AgentRunTurn, AgentTrace, type AgentTraceProps, Avatar, BandMark, type BlockedPerson, type ChainedEntry, Combobox, type ComboboxInputProps, type ComboboxItem, type ComboboxProps, ConfirmDialog, type ConfirmDialogProps, Dialog, type DialogProps, type DirectoryPage, ErrorNote, type FilterGroup, FilterMenu, type FilterOption, type FilterRow, type FilterSelection, Glyph, type GlyphKind, INSTRUMENTS, Icon, type IconProps, InfoNote, type Instrument, LOG_TAIL, LogoLockup, type Mark, Menu, type MenuEntry, type MenuProps, PaneHeader, type PersonDirectory, type PersonList, PersonPicker, type PersonPickerProps, PersonSearch, type PersonSearchProps, type PickerOrg, type PickerPerson, SettingsActions, SettingsBack, type SettingsBackTarget, SettingsChoices, SettingsDanger, SettingsDangerRow, SettingsDialog, SettingsEmpty, type SettingsFact, SettingsFacts, SettingsField, type SettingsFieldProps, SettingsForm, type SettingsGroup, SettingsHead, SettingsLayout, SettingsLoading, type SettingsNavItem, SettingsNoAccess, SettingsNotice, type SettingsPick, SettingsPicks, SettingsReadError, SettingsRow, SettingsRows, SettingsSaveState, SettingsSaved, SettingsSection, SettingsSingle, type SettingsTarget, type SubItem, TURN_STATUS_ATTR, TagInput, type ToastAction, ToastHost, type ToastItem, type ToastKind, type ToastOptions, Tooltip, type TooltipProps, type TraceItem, type Trail, type TrailOpts, WorkshopEmblem, WorkshopIcon, agentInstrument, avatarInitial, avatarTone, directoryFor, dismissAllToasts, dismissToast, facetedCount, filterRows, instrumentOf, memberDisplayName, memberOrder, peopleDirectory, settingsLinkHandler, splitTags, toast, trailOf, useElapsed, useMessageList, useNow, usePersonList, useTurnStatusOnPage };