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

package/dist/index.d.ts

@@ -9,7 +9,7 @@ import * as react from 'react';
 import { ReactNode, CompositionEvent, RefObject, KeyboardEvent } from 'react';
 export { FORBIDDEN_CODE, NETWORK_LOST, NETWORK_LOST_CODE, errorText, failedBecause, isForbidden, isNetworkLost } from './errors.js';
 import { SettingsGroup, SettingsBackTarget, SettingsTarget } from './components.js';
-export { AgentAvatar, Avatar, BandMark, ErrorNote, Glyph, GlyphKind, INSTRUMENTS, InfoNote, Instrument, LogoLockup, PaneHeader, SettingsActions, SettingsBack, SettingsChoices, SettingsDanger, SettingsDangerRow, SettingsDialog, SettingsEmpty, SettingsFact, SettingsFacts, SettingsField, SettingsFieldProps, SettingsForm, SettingsHead, SettingsLayout, SettingsLoading, SettingsNavItem, SettingsNoAccess, SettingsNotice, SettingsReadError, SettingsRow, SettingsRows, SettingsSaveState, SettingsSaved, SettingsSection, SettingsSingle, WorkshopEmblem, WorkshopIcon, agentInstrument, avatarInitial, avatarTone, instrumentOf, memberOrder, settingsLinkHandler } from './components.js';
+export { AgentAvatar, Avatar, BandMark, BlockedPerson, Combobox, ComboboxItem, DirectoryPage, ErrorNote, FilterGroup, FilterMenu, FilterOption, FilterRow, FilterSelection, Glyph, GlyphKind, INSTRUMENTS, InfoNote, Instrument, LogoLockup, PaneHeader, PersonDirectory, PersonPicker, PersonPickerProps, PersonSearch, PersonSearchProps, PickerOrg, PickerPerson, SettingsActions, SettingsBack, SettingsChoices, SettingsDanger, SettingsDangerRow, SettingsDialog, SettingsEmpty, SettingsFact, SettingsFacts, SettingsField, SettingsFieldProps, SettingsForm, SettingsHead, SettingsLayout, SettingsLoading, SettingsNavItem, SettingsNoAccess, SettingsNotice, SettingsPick, SettingsPicks, SettingsReadError, SettingsRow, SettingsRows, SettingsSaveState, SettingsSaved, SettingsSection, SettingsSingle, TagInput, ToastAction, ToastHost, ToastItem, ToastKind, ToastOptions, WorkshopEmblem, WorkshopIcon, agentInstrument, avatarInitial, avatarTone, dismissAllToasts, dismissToast, facetedCount, filterRows, instrumentOf, memberOrder, peopleDirectory, settingsLinkHandler, splitTags, toast } from './components.js';
 import { ModelCredential, ProjectAgentModels } from '@kanyun-ai-infra/band-contracts/api';
 export { MODEL_CREDENTIAL_CHANGED, MODEL_NOT_CONFIGURED, MODEL_PROJECT_CONSENT_PENDING, MODEL_SELECTION_REQUIRED, MODEL_SERVICE_NOT_FOUND } from '@kanyun-ai-infra/band-contracts/api';
 export { scrollIntoPanel } from './scroll.js';
@@ -343,106 +343,6 @@ declare function useComposition(onEnd: (el: HTMLInputElement | HTMLTextAreaEleme
     };
 };
 
-/** 下拉里的一项。`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;
-
 /** 重跑上一回合没做成或停下的阶段 `stage`（宿主给的 `retryStage`）；没有 submit-change 的人置灰（服务端照旧逐动作判）。 */
 declare function Retry({ ctx, stage }: {
     ctx: ProjectCtx;
@@ -954,7 +854,7 @@ declare function useReactionPatches(ctx: Pick<ProjectCtx, "events" | "threads">,
  * 消息间移动，`Home` `End` 到头尾。返回值挂在列表容器上。
  */
 declare function useMessageList<T extends HTMLElement>(): {
-    ref: RefObject<T>;
+    ref: RefObject<T | null>;
     onKeyDown: (e: KeyboardEvent<T>) => void;
     onFocus: (e: React.FocusEvent<T>) => void;
 };
@@ -1024,56 +924,6 @@ declare function MemoryNote({ ctx, turnId }: {
     turnId: string;
 }): react.JSX.Element | null;
 
-/**
- * 页面里的 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;
-
 /**
  * Rondo 状态消息与回执页脚的写法（[note](../../../../.agents/notes/proposed/feature/2026-10-28-agent-presence-in-thread.md)
  * §3、§7）：用时怎么念、回执页脚那一句怎么拼。纯函数，`band-chat`、`band-comment`、`band-turn-bar` 共用。
@@ -1308,4 +1158,4 @@ declare function useSavedNote(): [string, (text: string) => void];
 /** 跨页提示落到本页：挂上后取一次（放在 effect 里：`aria-live` 只在内容变化时播报）。 */
 declare function useCrossPageNotice(slug: string): [string, (text: string) => void];
 
-export { type AddableItem, type AttachSource, Combobox, type ComboboxItem, type Draft, type DraftItem, ExternalImportPanel, type ExternalImportSource, type FileCheck, type FileItem, type FileLimits, type FilterGroup, FilterMenu, type FilterOption, type FilterRow, type FilterSelection, FirstDeliveryAction, type FirstTurnEnd, MODELS_FOR_PAGE, MODEL_NEEDS_PERSONAL, MODEL_NEEDS_SETTINGS, MODEL_PROVISION_REASON, MODEL_REQUIRED_REASON, Markdown, type MemoNote, MemoryNote, Message, MessageAttachments, type MessageAttachmentsProps, type MessageProps, ModelHint, Mount, NO_KEY_BUTTON, NO_KEY_TEXT, NoKeyNotice, PASTE_FOLD_CHARS, PERSONAL_MODELS_PAGE, PROJECT_MODEL_HEADING, PROJECT_MODEL_NEEDS_ME, PROJECT_MODEL_SPEND, type PendingReaction, type PluginState, type ProjectModelNeeds, PromptInput, type PromptInputProps, QUOTE_DRAW, REACTION_MEANING, REPO_URL_EXAMPLE, RESUME_PAGE, type RefCandidate, type RefItem, Retry, STAGE_EVENTS, STATUS_CHIP, STOPPED_UNDONE, STOP_COST, type SelectedEntity, SettingsBackTarget, SettingsFrame, SettingsGroup, SettingsTarget, type ShownReaction, type StallView, StatusMessage, StopTurn, TARGET_REPO_DOCS, THREAD_EVENTS, TURN_STATUS_ATTR, TagInput, TargetRepoNote, type ToastAction, ToastHost, type ToastItem, type ToastKind, type ToastOptions, type Trigger, TurnStopped, type TurnStoppedEvent, type Uploader, VersionReference, type VersionReferenceInfo, type VersionReferences, afterSend, agentIn, agentLabel, alreadyHandedText, anchorLabel, anchorQuote, canRestoreProject, checkFiles, clearFresh, composerSpendLine, createState, credentialOptionLabel, defaultOf, deletedProjectText, dismissAllToasts, dismissToast, draftFileBytes, durationText, emptyDraft, enterSection, entriesFor, errorRepo, errorRequestAccessUrl, estimateMinutesText, facetedCount, failed, failureReason, fileExt, filterByQuery, filterRows, firstTurnEnd, flushAllDrafts, formatBytes, gateRule, gateWho, hasContent, importConnector, importFrom, inline, isModelRequired, isProvisionFailure, isThreadTail, itemKey, leaveThen, loadVersionReferences, localDay, markFresh, markFreshMany, markNotice, markdownOf, memberName, memoNote, memoryItem, mentionCandidates, mentionQuery, mentionsIn, mergeReactions, modelHintText, parseDraft, parseMemoryItem, peekFresh, peekFreshAll, persistable, personalImportSource, personalImportSources, plainText, popoverLeft, projectModelNeedsOf, projectModelNeedsText, projectModelNote, provisionConsentText, queuePosition, queueSlot, queuedMessages, quoteFace, quoteLine, reactMount, reactedBy, reactionLabel, reactionWho, readComments, receiptFileNames, receiptFooter, refTargets, registerDraftFlusher, rejectionText, replaceRange, repoFieldHint, roleLabel, saveDraft, settingsLink, settingsNavigate, settledPending, shortTime, shortWhen, splitTags, stallNoteOf, statusText, stopQueuedNote, takeDraft, takeNotice, targetRepoErrorId, threadConfirmation, threadPath, toMessageExtras, toast, triggerAt, turnEndWord, turnStoppedOf, uploadFailureLines, uploading, useAppData, useArtifactRole, useComposition, useCrossPageNotice, useCtxData, useDraft, useElapsed, useFreshRow, useFreshRows, useHandToAgent, useLeaveGuard, useMembers, useMessageList, useNarrow, useNow, useProjectAttachments, useReactionPatches, useRoute, useSavedNote, useSelectedArtifact, useSelectedEntity, useSettledText, useSlotEntries, useStateOf, useTurnStatusOnPage, useUnsavedGuard, useVersionReferences, usualDurationText, versionLabel, versionReferenceLabel, versionReferenceText, wasStopped };
+export { type AddableItem, type AttachSource, type Draft, type DraftItem, ExternalImportPanel, type ExternalImportSource, type FileCheck, type FileItem, type FileLimits, FirstDeliveryAction, type FirstTurnEnd, MODELS_FOR_PAGE, MODEL_NEEDS_PERSONAL, MODEL_NEEDS_SETTINGS, MODEL_PROVISION_REASON, MODEL_REQUIRED_REASON, Markdown, type MemoNote, MemoryNote, Message, MessageAttachments, type MessageAttachmentsProps, type MessageProps, ModelHint, Mount, NO_KEY_BUTTON, NO_KEY_TEXT, NoKeyNotice, PASTE_FOLD_CHARS, PERSONAL_MODELS_PAGE, PROJECT_MODEL_HEADING, PROJECT_MODEL_NEEDS_ME, PROJECT_MODEL_SPEND, type PendingReaction, type PluginState, type ProjectModelNeeds, PromptInput, type PromptInputProps, QUOTE_DRAW, REACTION_MEANING, REPO_URL_EXAMPLE, RESUME_PAGE, type RefCandidate, type RefItem, Retry, STAGE_EVENTS, STATUS_CHIP, STOPPED_UNDONE, STOP_COST, type SelectedEntity, SettingsBackTarget, SettingsFrame, SettingsGroup, SettingsTarget, type ShownReaction, type StallView, StatusMessage, StopTurn, TARGET_REPO_DOCS, THREAD_EVENTS, TURN_STATUS_ATTR, TargetRepoNote, type Trigger, TurnStopped, type TurnStoppedEvent, type Uploader, VersionReference, type VersionReferenceInfo, type VersionReferences, afterSend, agentIn, agentLabel, alreadyHandedText, anchorLabel, anchorQuote, canRestoreProject, checkFiles, clearFresh, composerSpendLine, createState, credentialOptionLabel, defaultOf, deletedProjectText, draftFileBytes, durationText, emptyDraft, enterSection, entriesFor, errorRepo, errorRequestAccessUrl, estimateMinutesText, failed, failureReason, fileExt, filterByQuery, firstTurnEnd, flushAllDrafts, formatBytes, gateRule, gateWho, hasContent, importConnector, importFrom, inline, isModelRequired, isProvisionFailure, isThreadTail, itemKey, leaveThen, loadVersionReferences, localDay, markFresh, markFreshMany, markNotice, markdownOf, memberName, memoNote, memoryItem, mentionCandidates, mentionQuery, mentionsIn, mergeReactions, modelHintText, parseDraft, parseMemoryItem, peekFresh, peekFreshAll, persistable, personalImportSource, personalImportSources, plainText, popoverLeft, projectModelNeedsOf, projectModelNeedsText, projectModelNote, provisionConsentText, queuePosition, queueSlot, queuedMessages, quoteFace, quoteLine, reactMount, reactedBy, reactionLabel, reactionWho, readComments, receiptFileNames, receiptFooter, refTargets, registerDraftFlusher, rejectionText, replaceRange, repoFieldHint, roleLabel, saveDraft, settingsLink, settingsNavigate, settledPending, shortTime, shortWhen, stallNoteOf, statusText, stopQueuedNote, takeDraft, takeNotice, targetRepoErrorId, threadConfirmation, threadPath, toMessageExtras, triggerAt, turnEndWord, turnStoppedOf, uploadFailureLines, uploading, useAppData, useArtifactRole, useComposition, useCrossPageNotice, useCtxData, useDraft, useElapsed, useFreshRow, useFreshRows, useHandToAgent, useLeaveGuard, useMembers, useMessageList, useNarrow, useNow, useProjectAttachments, useReactionPatches, useRoute, useSavedNote, useSelectedArtifact, useSelectedEntity, useSettledText, useSlotEntries, useStateOf, useTurnStatusOnPage, useUnsavedGuard, useVersionReferences, usualDurationText, versionLabel, versionReferenceLabel, versionReferenceText, wasStopped };