@kanyun-ai-infra/band-plugin-react 0.1.1 → 0.2.0

package/dist/components.d.ts

@@ -1,6 +1,6 @@
 import * as react from 'react';
-import { ReactNode } from 'react';
-import { MemberView } from '@kanyun-ai-infra/band-plugin-sdk';
+import { ReactNode, Ref, MouseEvent } from 'react';
+import { MemberView, PeopleApi } from '@kanyun-ai-infra/band-plugin-sdk';
 
 /**
  * 一行错误提示：操作失败时显示在面板里。`children` 为空（null、undefined、空串、false）时什么也不渲染。
@@ -96,4 +96,513 @@ declare function BandMark({ size, className }: {
 /** Band 字标（五线谱 + 三个音符 + 「Band」，DESIGN.md「标志」）。样式在 Band Design 的 `.logo`。 */
 declare function LogoLockup(): react.JSX.Element;
 
-export { AgentAvatar, Avatar, BandMark, ErrorNote, Glyph, type GlyphKind, INSTRUMENTS, InfoNote, type Instrument, LogoLockup, PaneHeader, WorkshopEmblem, WorkshopIcon, agentInstrument, avatarInitial, avatarTone, instrumentOf, memberOrder };
+/** 一次页内跳转的目标：页键与地址参数，由调用方交给宿主。 */
+interface SettingsTarget {
+    page: string;
+    params?: Record<string, string>;
+}
+/** 导航里的一项（分区导航的链接）。 */
+interface SettingsNavItem extends SettingsTarget {
+    slug: string;
+    title: string;
+    href: string;
+    /** 右侧 16px 状态符号（同侧栏），可选。 */
+    glyph?: ReactNode;
+}
+interface SettingsGroup {
+    group: string;
+    sections: readonly SettingsNavItem[];
+}
+/** 页头上方那行返回（`‹ 设置`、`‹ 列表名`）。 */
+interface SettingsBackTarget extends SettingsTarget {
+    label: string;
+    href: string;
+}
+type Navigate = (target: SettingsTarget) => void;
+/** 只在主键上点（没按修饰键）时走页内跳转；其余交给浏览器（新标签页）。 */
+declare function settingsLinkHandler(go: Navigate | undefined, target: SettingsTarget): (e: MouseEvent<HTMLAnchorElement>) => void;
+/**
+ * 四个作用域共用的骨架（稿 §3.1、§3.7）：左边分区导航、右边内容。作用域只决定导航头与分区名单；
+ * 摆法与手机宽度（600px）下的两页切换不变。导航是链接列表（`aria-current="page"`），不是 tablist。
+ */
+declare function SettingsLayout({ navLabel, title, obj, crumb, groups, current, view, back, backMobile, onNavigate, mainRef, children, }: {
+    /** 分区导航的 aria-label（「设置分区」「项目设置分区」）。 */
+    navLabel: string;
+    title: string;
+    /** 导航头第二行（「只有你看得到这里」）。 */
+    obj?: ReactNode;
+    /** 导航头上方的面包屑；项目、工坊作用域的对象头沿用页面顶栏，一般不传。 */
+    crumb?: ReactNode;
+    groups: readonly SettingsGroup[];
+    /** 当前分区的 slug；目录页不传。 */
+    current?: string | undefined;
+    view?: "page" | "index";
+    /** 详情 / 新增页头上的「‹ 列表名」：宽窄都画（稿 §3.2）。 */
+    back?: SettingsBackTarget | undefined;
+    /** 分区页给手机宽度的「‹ 设置」：只在窄屏画（稿 §3.7）。 */
+    backMobile?: SettingsBackTarget | undefined;
+    /** 页内跳转；不给就按普通链接走。 */
+    onNavigate?: Navigate;
+    /** 内容区的 ref（接线层在上面装未保存离开的守卫）。 */
+    mainRef?: Ref<HTMLElement>;
+    children: ReactNode;
+}): react.JSX.Element;
+/** 「‹ 列表名」：详情、新增页头上方；`mobileOnly` 是只在手机宽度画的「‹ 设置」。 */
+declare function SettingsBack({ target, onNavigate, mobileOnly, }: {
+    target: SettingsBackTarget;
+    onNavigate?: Navigate | undefined;
+    mobileOnly?: boolean;
+}): react.JSX.Element;
+/** 页头：标题（分区名）+ 一句说明这里管什么、谁看得到 + 主操作（靠右，一页最多一个）。 */
+declare function SettingsHead({ title, desc, action, }: {
+    title: ReactNode;
+    desc?: ReactNode;
+    action?: ReactNode;
+}): react.JSX.Element;
+/** 列表：行不画框不画线，悬停垫浅底；整行进详情。 */
+declare function SettingsRows({ label, children }: {
+    label: string;
+    children: ReactNode;
+}): react.JSX.Element;
+/**
+ * 一行：（可选的头像 / 图标位）名称 + 标记 / 一行元信息 / 右端最多一个快捷操作 + 进详情的箭头。
+ * 给了 `onOpen` 时整行可点。
+ */
+declare function SettingsRow({ title, tags, meta, actions, leading, href, onOpen, mono, isNew, extra, }: {
+    title: ReactNode;
+    tags?: ReactNode;
+    meta?: readonly ReactNode[];
+    actions?: ReactNode;
+    /** 名称左边的头像或图标（成员行用 `Avatar`），占两行高。 */
+    leading?: ReactNode;
+    href?: string;
+    onOpen?: () => void;
+    mono?: boolean;
+    /** 刚保存的那一行垫 `--ok-soft`（回列表时标出来）。 */
+    isNew?: boolean;
+    /** 行内展开的一块，占满整行宽。画它时别给 `onOpen`：整行链接会盖住它。 */
+    extra?: ReactNode;
+}): react.JSX.Element;
+interface SettingsFact {
+    key: string;
+    value: ReactNode;
+}
+/** 详情概况：定义列表，不画框。 */
+declare function SettingsFacts({ items }: {
+    items: readonly SettingsFact[];
+}): react.JSX.Element;
+/** 一节：`h2` + 可选的一句说明 + 内容；节与节之间留白，不画线、不套卡（稿 §3.1）。 */
+declare function SettingsSection({ title, desc, children, }: {
+    title: string;
+    desc?: ReactNode;
+    children: ReactNode;
+}): react.JSX.Element;
+/**
+ * 只有一份设置的分区（提醒、批准）：不分节、不画 h2（稿 §3.2），控件、说明与反馈竖排。
+ * 名字给 `aria-label`；里面要成组的控件自己放 `fieldset`（组件抹掉它的默认框）。
+ */
+declare function SettingsSingle({ label, children }: {
+    label: string;
+    children: ReactNode;
+}): react.JSX.Element;
+/** 一排勾选（`.choice`）：自动折行。 */
+declare function SettingsChoices({ children }: {
+    children: ReactNode;
+}): react.JSX.Element;
+/** 起点选项块的一项：标题加一句说明。 */
+interface SettingsPick<T extends string> {
+    value: T;
+    label: ReactNode;
+    line?: ReactNode;
+}
+/**
+ * 选项块（单选）：一排块，每块一句标题、一句说明，选中的块 `--accent-soft` 底加 2px `--accent` 内描边；
+ * 用在「先选类型，下面再填该填的字段」的表单最前面（设置体系 §4.1；新建工坊的「从哪开始」）。
+ * 单选按钮藏起来（`.sr-only`），块本身是 `label`，键盘方向键照原生单选走。≤599 宽一列。
+ */
+declare function SettingsPicks<T extends string>({ label, value, onChange, options, disabled, }: {
+    label: ReactNode;
+    value: T;
+    onChange: (value: T) => void;
+    options: readonly SettingsPick<T>[];
+    disabled?: boolean;
+}): react.JSX.Element;
+/** 危险操作区：只在详情页最下面，每项一行（动作 + 后果一句 + 按钮），按钮是 `.btn.danger`（稿 §3.6）。 */
+declare function SettingsDanger({ children }: {
+    children: ReactNode;
+}): react.JSX.Element;
+declare function SettingsDangerRow({ title, note, action, }: {
+    title: ReactNode;
+    note: ReactNode;
+    action: ReactNode;
+}): react.JSX.Element;
+/** 加载：页头照常画，内容区用 Band Design 的 `.tuning`（五线谱）配「正在读取<什么>…」；不画骨架条（稿 §3.3）。 */
+declare function SettingsLoading({ text }: {
+    text: string;
+}): react.JSX.Element;
+/** 空：休止符插画 + 一句「还没有什么、有了能做什么」+ 主操作（没有新增权限时不画按钮）。 */
+declare function SettingsEmpty({ children, action }: {
+    children: ReactNode;
+    action?: ReactNode;
+}): react.JSX.Element;
+/** 读失败：一行 `ErrorNote`（「<什么>没读出来：<原因>」+「重试」）。 */
+declare function SettingsReadError({ children, retry }: {
+    children: ReactNode;
+    retry: () => void;
+}): react.JSX.Element;
+/**
+ * 没有权限（读 403）与环境没开通：标题、谁能看 / 缺什么、去找谁，一个离开的按钮（可不给）；不画重试（稿 §3.3）。
+ */
+declare function SettingsNoAccess({ title, children, action, }: {
+    title: string;
+    children: ReactNode;
+    action?: {
+        label: string;
+        onClick: () => void;
+    } | undefined;
+}): react.JSX.Element;
+/** 保存后的读屏播报（「已保存」「已删除」，不抢眼、不占版面）。 */
+declare function SettingsNotice({ text }: {
+    text: string;
+}): react.JSX.Element;
+/** 「已保存」那一句（控件旁或按钮旁，停四拍由调用方的 `useSavedNote` 管）。 */
+declare function SettingsSaved({ text }: {
+    text?: ReactNode;
+}): react.JSX.Element;
+/**
+ * 确认弹窗（稿 §3.6）：`--scrim`、`--shadow-pop`、`--r-xl`；标题问动作，正文列后果，末尾写能不能恢复。
+ * 不用输入名字确认：弹窗已列后果，多打一遍字不增加信息。
+ */
+declare function SettingsDialog({ title, children, actions, onClose, }: {
+    title: string;
+    children: ReactNode;
+    actions: ReactNode;
+    onClose: () => void;
+}): react.JSX.Element;
+/** 设置里的表单：字段竖排，最宽 560。提交走 `onSubmit`（已 `preventDefault`）。 */
+declare function SettingsForm({ label, onSubmit, children, }: {
+    label?: string;
+    onSubmit?: () => void;
+    children: ReactNode;
+}): react.JSX.Element;
+/** 字段的输入要挂的属性：id、读屏说明、出错标记。 */
+interface SettingsFieldProps {
+    id: string;
+    "aria-describedby"?: string;
+    "aria-invalid"?: true;
+}
+/**
+ * 字段行：标签（必填写「必填」）、输入、下一行的提示或出错、计数。提示 / 出错 / 计数用 Band Design 的
+ * `.field-note`（出错加 `.err`）与 `.field-count`（DESIGN.md「控件」），出错时输入挂 `aria-invalid`。
+ * 输入本身由调用方用 Band Design 的 `.field` 画，组件只摆位置、接好 id 与读屏说明。
+ */
+declare function SettingsField({ label, required, optional, hint, error, count, over, children, }: {
+    label: ReactNode;
+    required?: boolean;
+    /** 选填：标签旁写「选填」（稿 §3.5 的样张两种都标）；与 `required` 不同时给。 */
+    optional?: boolean;
+    hint?: ReactNode;
+    /** 出错的话；有它时不画提示。 */
+    error?: ReactNode;
+    /** 计数（「12 / 200」），靠右。 */
+    count?: ReactNode;
+    /** 计数超了：计数变红。 */
+    over?: boolean;
+    children: (props: SettingsFieldProps) => ReactNode;
+}): react.JSX.Element;
+/** 表单末尾的操作行：按钮 + 保存反馈 / 还缺什么。 */
+declare function SettingsActions({ children, end, }: {
+    children: ReactNode;
+    end?: boolean;
+}): react.JSX.Element;
+/**
+ * 保存反馈（稿 §3.5）：`saving` 时写在做什么（「正在验证…」那一档的旁注），`saved` 停四拍的「已保存」，
+ * `failed` 是贴在按钮旁的整体错误（「没保存：」开头），`missing` 是按钮置灰时缺什么（「还差 key 没填」）。
+ * 不用吐司；读屏走 `aria-live`。
+ */
+declare function SettingsSaveState({ saving, saved, failed, missing, }: {
+    saving?: ReactNode;
+    /** `true` 写「已保存」；给文字或节点就照它写（「已保存，ModelGate 验证通过」）。 */
+    saved?: ReactNode;
+    failed?: ReactNode;
+    missing?: ReactNode;
+}): react.JSX.Element;
+
+/** 下拉里的一项。`group` 相同的排在一段，段的顺序按它第一次出现的顺序。 */
+interface ComboboxItem {
+    value: string;
+    label: string;
+    group?: string;
+    /** 行尾的补充说明（部门、类型），用等宽字体。 */
+    meta?: string;
+    /** label 之外用来搜索的文字（部门、拼音备注），不进占位提示。 */
+    keywords?: string;
+}
+/**
+ * 可搜索的单选 / 多选（样张 §2「Combobox」）。键盘：↑↓ 移动、回车选中、「空格」在多选里切换选中、
+ * Esc 关闭、输入过滤；退格在空输入时删掉最后一个已选。
+ *
+ * 空格只在查询为空时切换选中：查询里带了字时空格照常输入，否则「Wang Min」这种名字搜不了
+ * （样张只演示了空查询下的多选，这一点按能打字优先定）。
+ */
+declare function Combobox({ label, items, value, onChange, multiple, placeholder, emptyText, onCreate, createLabel, disabled, }: {
+    /** 输入框的无障碍名，也是空结果那句「没有匹配的<label>」里的名字。 */
+    label: string;
+    items: readonly ComboboxItem[];
+    /** 受控：已选的值，按选中的先后。 */
+    value: readonly string[];
+    onChange(next: readonly string[]): void;
+    /** 多选：回车与空格切换选中、列表不关；单选：回车选中并关闭。 */
+    multiple?: boolean;
+    placeholder?: string;
+    /** 空结果那一行的整句，缺省「没有匹配的<label>」。 */
+    emptyText?: string;
+    /**
+     * 查询非空、且没有名字正好相同的候选时，列表末尾多一行「新建」。选中它时把这句查询交回调用方
+     * （建完由调用方把新值放进 `value`）。
+     */
+    onCreate?(name: string): void;
+    /** 「新建」那行的写法，缺省「新建「<查询>」」。 */
+    createLabel?(name: string): string;
+    disabled?: boolean;
+}): react.JSX.Element;
+/**
+ * 一段文字拆成标签：按逗号（半角、全角）、换行、制表符拆，去掉首尾空白与空串，**不去重**
+ * （重复要提示，不能悄悄吃掉）。纯函数，单测与 TagInput 共用。
+ */
+declare function splitTags(text: string): string[];
+/**
+ * 数组值（样张 §2「Tag Input」）：值受控，回车或逗号确认一个，粘贴带分隔符时整段拆开；重复的值不加入，
+ * 已有的那个闪一下红底并在下面写一句（「「x」重复了，已跳过」，1.8 秒后退回）；输入框空着时退格删最后一个。
+ *
+ * 输入法：回车、退格都经 `withImeGuard`——组字中选字的回车不能当成「加一个标签」。
+ */
+declare function TagInput({ label, value, onChange, placeholder, hint, disabled, id, }: {
+    /** 输入框的无障碍名。 */
+    label: string;
+    /** 受控：标签，按加入的先后。 */
+    value: readonly string[];
+    onChange(next: readonly string[]): void;
+    placeholder?: string;
+    /** 常态那句说明（「粘贴「五年级, 分数」会拆成两个」）；重复时换成提示，1.8 秒后退回这句。 */
+    hint?: string;
+    disabled?: boolean;
+    id?: string;
+}): react.JSX.Element;
+/** 筛选项：一段里的一个值。 */
+interface FilterOption {
+    value: string;
+    label: string;
+}
+/** 一段筛选：`key` 是行数据里的字段名。 */
+interface FilterGroup {
+    key: string;
+    label: string;
+    options: readonly FilterOption[];
+}
+/** 一行在各分组上的取值（`row[group.key]`）。 */
+type FilterRow = Readonly<Record<string, string>>;
+/** 已选：分组 key → 选中的值（段内是「或」）。 */
+type FilterSelection = Readonly<Record<string, readonly string[]>>;
+/**
+ * 计数（样张 §2「Filter Menu」的 faceted 口径）：某个选项的计数 = 在**其他**分组的已选条件下还剩多少行，
+ * 也带自己这一段——和产物库的「勾了别的组，这一段的数跟着缩」同一口径。纯函数，单测与 FilterMenu 共用。
+ */
+declare function facetedCount(rows: readonly FilterRow[], groups: readonly FilterGroup[], selection: FilterSelection, groupKey: string, value: string): number;
+/** 按已选筛行：每组内是「或」，组之间是「且」。纯函数。 */
+declare function filterRows(rows: readonly FilterRow[], groups: readonly FilterGroup[], selection: FilterSelection): readonly FilterRow[];
+/**
+ * 分组筛选（样张 §2「Filter Menu」）。分组可折叠（组标题是按钮，`aria-expanded`），计数按当前其他分组
+ * 的已选算（`facetedCount`），已选的做成 chip 可单个移除，右端「清空」。值受控。
+ *
+ * 键盘：组标题与每个勾选框都在正常的 Tab 顺序里（勾选框是原生 `<input type="checkbox">`），空格切换；
+ * 点组标题只折叠/展开，不改筛选。
+ */
+declare function FilterMenu({ groups, rows, value, onChange, emptyText, }: {
+    groups: readonly FilterGroup[];
+    /** 用来算计数的行（通常是未筛选的全量；传筛过的会让计数越筛越小）。 */
+    rows: readonly FilterRow[];
+    value: FilterSelection;
+    onChange(next: FilterSelection): void;
+    /** 一段里一个选项都没有时那一行，缺省「没有可筛的」。 */
+    emptyText?: string;
+}): react.JSX.Element;
+
+/**
+ * 页面里的 toast（backlog #5）：刚做完一件事的即时回执。宿主（外壳）画唯一一层容器 `ToastHost`，
+ * 插件与锁定插件只 import 这里的 `toast()` 入队，不自己画容器——两个插件同时弹也落进同一摞，不会各画一层。
+ *
+ * 模块级 store 是有意为之：`@kanyun-ai-infra/band-plugin-react` 是宿主提供的共享模块，宿主与每个插件拿到同一个
+ * 实例；而每个插件各开一个 React root，React context 跨不过去，ctx 也没有这个能力（加它要改协议）。
+ *
+ * 规则照样张（docs/design/specimens/band-design-components.html §5，本卡按它实现）：
+ * - 成功 4 秒自己收；鼠标停在上面时不收，移开后 2 秒再收；
+ * - 错误不自己走，要么点「重试」要么关掉（没给动作时容器补一个「关闭」）；
+ * - 进行中做完在同一条里变成勾（用同一个 id 再调一次 `toast`），不新弹一条；
+ * - 同时最多三条，第四条挤掉最早的一条（进行中的先留着）。
+ *
+ * 模块级状态跟着页面活：测试要清干净用 `dismissAllToasts`。
+ */
+type ToastKind = "ok" | "bad" | "busy";
+/** toast 上的一个动作（错误一般是「重试」）。 */
+interface ToastAction {
+    label: string;
+    onClick: () => void;
+}
+interface ToastOptions {
+    /** 缺省 `ok`。 */
+    kind?: ToastKind;
+    /** 一行说明。 */
+    text: string;
+    /** 第二行小字。 */
+    detail?: string;
+    /** 一个动作；错误的「重试」放这里。 */
+    action?: ToastAction;
+    /** 传已有的 id：改那一条（进行中做完变成勾），不新弹一条。 */
+    id?: string;
+}
+interface ToastItem {
+    id: string;
+    kind: ToastKind;
+    text: string;
+    detail?: string;
+    action?: ToastAction;
+}
+/** 弹一条；传 `id` 就是改那一条。返回它的 id。 */
+declare function toast(opts: ToastOptions): string;
+/** 收起一条（动作、Esc、关掉都走这里）。 */
+declare function dismissToast(id: string): void;
+/** 全部收掉（换身份、测试收尾）。 */
+declare function dismissAllToasts(): void;
+
+/** 宿主画的一次性容器；一页只有一个（`band-shell`）。插件调 `toast()`，不自己画。 */
+declare function ToastHost(): react.JSX.Element;
+
+interface ChainedPerson {
+    id: string;
+    /** 这个人所在部门的链；挂在多个部门时任取其一，判定只看是否在某部门之下。 */
+    chain?: string;
+}
+interface Blocked extends ChainedPerson {
+    reason: string;
+}
+
+/** 一个人。`id` 是 ldap；`path` 是部门路径（「研发中心 / 平台组」），只用来看清是谁。 */
+interface PickerPerson {
+    id: string;
+    name: string;
+    path?: string;
+    /** 部门 id 链（「/」隔开，`1/5/9`），算部门勾选态用；推不出时没有。 */
+    chain?: string;
+    /** false：还没登录过 Band（名字从组织架构来）。不影响能不能选（owner 11-14），只在已选名单里标一句。 */
+    inBand?: boolean;
+}
+/** 一个部门。`count` 是含下级部门的总人数；`count` 与 `chain` 都有才画勾选框。 */
+interface PickerOrg {
+    id: string;
+    name: string;
+    path?: string;
+    chain?: string;
+    count?: number;
+}
+/** 不能选的人：原因写在候选行上；带 `chain` 时从部门的可选人数里扣掉。 */
+type BlockedPerson = Blocked;
+/** 目录的一页：一层部门的下级部门与直属的人，或一次搜索的结果。 */
+interface DirectoryPage {
+    orgs: readonly PickerOrg[];
+    people: readonly PickerPerson[];
+    /** 搜索结果被上游截断了：提示换个更准的词。 */
+    truncated?: boolean;
+    /** 组织架构读不到、退回了 Band 用户目录：写原因，弹层顶上一直显示。 */
+    fallback?: string;
+}
+/** 数据口。所有方法收 `signal`：换词、关弹层时取消上一次。 */
+interface PersonDirectory {
+    /** 组织架构现在用不了时的原因（退回了 Band 用户目录）：没搜之前也在弹层顶上显示。 */
+    unavailable?: string;
+    search(q: string, opts: {
+        signal: AbortSignal;
+    }): Promise<DirectoryPage>;
+    /** 按部门浏览；`null` 是根。没有这个方法就只能搜。 */
+    browse?(orgId: string | null, opts: {
+        signal: AbortSignal;
+        chain?: string;
+    }): Promise<DirectoryPage>;
+    /** 一个部门（含下级）的全部人，最多 `limit` 个；`total` 是真实总数。 */
+    members?(orgId: string, opts: {
+        signal: AbortSignal;
+        limit: number;
+        chain?: string;
+    }): Promise<{
+        people: readonly PickerPerson[];
+        total: number;
+    }>;
+    /** 粘贴多个 ldap 时按 ldap 批量解析；找不到的放 `missing`。 */
+    resolve?(ids: readonly string[], opts: {
+        signal: AbortSignal;
+    }): Promise<{
+        people: readonly PickerPerson[];
+        missing: readonly string[];
+        /** 只能认出一部分人的原因（组织架构读不到）：写进提示，免得用户以为 ldap 写错了。 */
+        fallback?: string;
+    }>;
+}
+interface PersonSearchProps {
+    /** 输入框的无障碍名（「添加管理员」「加人」）。 */
+    label: string;
+    directory: PersonDirectory;
+    /** 已选的人：在候选里打勾（多选）或显示在输入框里（单选），不再重复加。 */
+    picked: readonly PickerPerson[];
+    /** 选中的人（单选一个；多选可能是整个部门或一次粘贴的一批，已按 ldap 去重）。 */
+    onPick(people: readonly PickerPerson[]): void;
+    /** 取消选中（多选里点已勾的人、取消整个部门；单选里点 ×）。 */
+    onUnpick?(ids: readonly string[]): void;
+    multiple?: boolean;
+    /** 还能再加几个人（名单上限减去已选）；不给就不限。 */
+    room?: number;
+    /** 不能选的人与原因（「已经是管理员」）。 */
+    disabled?: readonly BlockedPerson[];
+    /** 目录里没有的 ldap 也能加（名字先写 ldap）。 */
+    allowUnknown?: boolean;
+    placeholder?: string;
+    /** 整个控件禁用（保存中）。 */
+    busy?: boolean;
+    /** 根的名字（浏览时路径的第一段）。 */
+    rootLabel?: string;
+    /**
+     * 取到一个部门的全员时，把带部门链的人交给宿主（宿主拿来给名单里已有、还没链的人补链，省一次解析）。
+     * 包括已经在名单里、这次没有新加的人。
+     */
+    onLearn?(people: readonly PickerPerson[]): void;
+    /** 一开始就展开（样张、设计站用）。 */
+    defaultOpen?: boolean;
+    /** 一开始的搜索词（样张用）。 */
+    defaultQuery?: string;
+    /** 一开始浏览到哪（从根往下的部门，样张用）。 */
+    defaultTrail?: readonly PickerOrg[];
+}
+/** 搜索框 + 弹层：搜人、按部门逐级进入、勾整个部门、粘贴多个 ldap。 */
+declare function PersonSearch({ label, directory, picked, onPick, onUnpick, multiple, room, disabled, allowUnknown, placeholder, busy, rootLabel, onLearn, defaultOpen, defaultQuery, defaultTrail, }: PersonSearchProps): react.JSX.Element;
+interface PersonPickerProps extends Omit<PersonSearchProps, "picked" | "onPick" | "onUnpick" | "room" | "multiple"> {
+    /** 受控：名单上的人，按加入先后。 */
+    value: readonly PickerPerson[];
+    onChange(next: readonly PickerPerson[]): void;
+    /** 名单上限（同服务端）。 */
+    max?: number;
+    /** 只读：只列名单，没有加人和移出。 */
+    readOnly?: boolean;
+    /** 移出前在行内再确认一次（改动即时生效的名单用；有「保存」的表单不用）。 */
+    confirmRemove?: boolean;
+    /** 名单为空时的一句话。 */
+    emptyText?: string;
+    /** 这些人不能移出与原因（「创建人」）；取消整个部门时也不动他们。 */
+    locked?: Readonly<Record<string, string>>;
+    /** 换掉下面的加人框（一次加一个、要另填角色再提交的地方：放单选的 `PersonSearch` 和提交按钮）。 */
+    addSlot?: ReactNode;
+}
+/** 名单 + 加人：已选的人一行一个（头像、名字、ldap、部门），可移出；下面是多选的 `PersonSearch`。 */
+declare function PersonPicker({ value, onChange, max, readOnly, confirmRemove, emptyText, locked, addSlot, label, ...search }: PersonPickerProps): react.JSX.Element;
+/** 把宿主的人员目录（`ctx.people`）接成选择器的数据口。取消信号不往下传：过期的结果组件自己丢掉。 */
+declare function peopleDirectory(api: PeopleApi): PersonDirectory;
+
+export { AgentAvatar, Avatar, BandMark, type BlockedPerson, Combobox, type ComboboxItem, type DirectoryPage, ErrorNote, type FilterGroup, FilterMenu, type FilterOption, type FilterRow, type FilterSelection, Glyph, type GlyphKind, INSTRUMENTS, InfoNote, type Instrument, LogoLockup, PaneHeader, type PersonDirectory, 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, TagInput, type ToastAction, ToastHost, type ToastItem, type ToastKind, type ToastOptions, WorkshopEmblem, WorkshopIcon, agentInstrument, avatarInitial, avatarTone, dismissAllToasts, dismissToast, facetedCount, filterRows, instrumentOf, memberOrder, peopleDirectory, settingsLinkHandler, splitTags, toast };