@ticatec/topside-elements 1.0.0

package/docs/NAMING_CN.md

@@ -0,0 +1,364 @@
+# topside-elements 组件 API 命名规范
+
+> 版本：1.1（2026-09-05 定稿；随 5.1.0 落地）
+> 适用范围：`@ticatec/topside-elements` 所有公开组件的属性、回调、实例方法、导出类型，以及组件消费的数据对象（列定义、动作对象等）。内部子组件（`data_table/parts/*`、`*Panel.svelte` 等）也应遵守，但不受兼容承诺约束。
+> 状态说明：本规范自 **5.1.0** 起全量生效。5.1.0 是按 Svelte 5 语法重做的组件包，因此**不保留任何旧名别名或 `@deprecated` 过渡**；附录 A 是 5.0.x → 5.1.0 的完整新旧对照表，供迁移时查阅。
+
+---
+
+## 0. 总原则
+
+1. **同一语义，全库只有一个名字。** 先查附录 B 的词表，再给新属性起名；词表里没有的，先补词表再写代码。
+2. **贴近 Svelte 5 / DOM 的直觉。** 能与原生属性同名的（`disabled`、`readonly`、`placeholder`、`onclick`）就同名，不发明近义词。
+3. **名字说明"是什么"，不说明"在哪个组件里"。** 不把组件名塞进属性名（`accordions`、`menuItems` 这类都不允许）。
+4. **类型名说明"用途"，不说明"是函数"。** `Handler / Callback / Fun / Function` 后缀一律不用。
+
+---
+
+## R1 事件回调命名
+
+| 规则 | 写法 | 例子 |
+| --- | --- | --- |
+| 与 DOM 同名的事件 | 全小写 `on` + 单词 | `onchange` `onclick` `onfocus` `onblur` `oninput` `onclose` `onselect` `onkeydown` |
+| 自定义多词事件 | `on` + PascalCase | `onItemClick` `onPageSizeChange` `onFileUploaded` `onResizeEnd` `onRowClick` `onIconClick` |
+| 禁止 | `xxxHandler`、`xxxCallback`、`handleXxx` 作为 prop 名 | ~~`rowClickHandler`~~ ~~`closeCallback`~~ ~~`handleCellClick`~~ |
+| 禁止 | 同一事件同时存在两种大小写 | ~~`onClose` + `onclose`~~ |
+
+判断"是否与 DOM 同名"的口径：HTML 元素上存在同名 `onxxx` 属性即算同名。`onclose`（`<dialog>`）、`onselect`、`ontoggle`（`<details>`）、`oncontextmenu` 都属于 DOM 同名，写小写。
+
+**回调不是事件时不要用 `on` 前缀。** 返回数据的加载函数用 R11 的 `XxxLoader` / `loadXxx`（例：级联选择器加载下一级用 `loadChildren`，而不是 `onSelect`）。
+
+**参数约定。**
+- `onchange` 只传新值：`(value: T) => void`。不传 DOM 事件。
+- 与 DOM 同名且不是值变更的事件（`onclick`、`onfocus`、`onkeydown`…）传原生事件对象，参数名统一为 `event`（不用 `e`）。
+- 自定义事件按"主体在前、上下文在后"排列：`onItemClick(item, event?)`。DOM 同名事件若需要附带业务数据，数据跟在事件对象之后：`oncontextmenu(event, data)`。
+
+## R2 通知与否决
+
+| 类别 | 命名 | 返回值 | 语义 |
+| --- | --- | --- | --- |
+| 通知 | `onXxx` | `void` | 事情**已经**发生，调用方不能阻止 |
+| 否决钩子 | `beforeXxx` | `boolean \| Promise<boolean>` | 事情**将要**发生，返回 `false` 则取消 |
+
+- `onchange` 永远是通知。需要在变更前询问的组件（Tabs 关闭、TreeView 切换节点、Transfer 移动、Dialog 关闭、附件/图片删除）另开 `beforeXxx`：`beforeRemove` `beforeChange` `beforeClose` `beforeTransfer`。
+- `beforeXxx` 的参数与对应 `onXxx` 相同。
+- 不再使用 `xxxConfirm` 命名钩子（`closeConfirm` → `beforeClose`，`removeFileConfirm` → `beforeRemove`）。"确认"是钩子实现里的一种做法，不是钩子本身的语义。
+- 纯布尔开关（如"是否允许关闭"）用 R5 的 `xxxable`，不用钩子代替。
+
+## R3 值与绑定
+
+- 表单控件的当前值一律叫 `value`，且是 `$bindable()`。范围控件用 `fromValue` / `toValue`。
+- `value` 的类型必须具体（`string` / `number` / `UniDate` / `T`），`CommonFieldProps` 泛型化为 `CommonFieldProps<T>`，`onchange?: (value: T) => void`；不再写 `value?: any`。
+- 组件对外暴露、且调用方需要回写的状态（`pageNo`、`visible`、`expanded`、`activeTab`、`selectedRows`）都应是 `$bindable()`；只读派生值不得出现在 Props 里（例：`ImageFilesField.text`）。
+- `RadioButton` 沿用 Svelte 惯例 `bind:group`，是唯一例外。
+
+## R4 子元素属性透传
+
+- 唯一写法：`<部件>$<属性>`，属性部分与目标元素/组件的属性名完全一致。
+  `menu$height` `label$style` `content$style` `input$class` `input$readonly` `item$style` `body$class` `footer$style` `dialog$style` `page$style`
+- 部件名固定为：`input` `menu` `label` `content` `item` `body` `header` `footer` `dialog` `page` `box` `tag`。新增部件名先加到附录 B。
+- 禁止 camelCase 变体：~~`contentStyle`~~ ~~`itemStyle`~~ ~~`bodyClass`~~ ~~`labelStyle`~~。
+- 组件根元素的样式和类名就是 `style` 和 `class`，不用 `className`。
+
+## R5 布尔属性
+
+- 正向命名、无 `is` / `has` 前缀：`disabled` `readonly` `compact` `visible` `expanded` `virtual` `round`。
+- "显示某部件"只用 `show` 前缀：`showText` `showIndicator` `showRowNo` `showAction` `showHorizontalScroll`。不用 `display*`、不用 `hide*`。
+- "允许某操作"用 `xxxable`：`closable` `removable` `clearable` `resizable` `selectable` `confirmable`。不用 `canXxx`、不用 `mandatory`（→ `clearable=false`）、不用 `hideClose`（→ `closable=false`）。
+- 覆盖层（Drawer、Dialog、Popover、Overlay、Preview）可见性统一 `visible`（bindable）；可展开容器（Accordion 项、树节点、下拉面板）统一 `expanded`（bindable）。`isOpen`、`hasFocus`、`open` 不作为 prop 名。
+- 启用/禁用只用 `disabled`，不用 `enable` / `enabled`。
+
+## R6 语义、外观、方向、尺寸
+
+| 属性 | 含义 | 取值 |
+| --- | --- | --- |
+| `type` | **语义意图**（主/次/危险…） | `ButtonType = 'default' \| 'primary' \| 'secondary' \| 'third' \| 'forth'`；Button 的原生类型用 `htmlType` |
+| `variant` | **外观形状/风格** | 由组件自定的字面量联合：Button `'plain' \| 'round' \| ''`，Tag `'borderless' \| 'border' \| 'round'`，Card `'plain' \| '3d'`，Pagination `'plain' \| 'round' \| 'circle'`，ProgressBar `'circular' \| 'linear'`，表单 `EditorVariant` |
+| `direction` | **纵横方向** | `Direction = 'vertical' \| 'horizontal'`，全库共用一个类型 |
+| `position` | **相对位置** | `'left' \| 'right' \| 'top' \| 'bottom'`（Drawer 等） |
+| `align` | **对齐** | `'left' \| 'center' \| 'right'`（`'distribute'` 仅 Card 动作栏） |
+| `size` | **离散尺寸档位** | `Size = 'small' \| 'medium' \| 'large'`，全库共用；不用 `big` / `middle`，不用 `big: boolean` |
+
+- `type` 不再用于表达形状（Pagination、ProgressBar 的 `type` → `variant`）。
+- `variant` 不再用于表达方向（NavigatorMenu）或不受约束的 `string`（Row / Cell / GridForm / GridField 要么给出字面量联合，要么删除）。
+- `arrangement`、`layout` 表达纵横时一律改为 `direction`；`FieldLayout` 类型改名 `Direction`。
+- 数值型尺寸（ProgressBar 的 `size: number`）改名为具体维度 `diameter` / `thickness`，不占用 `size`。
+
+## R7 尺寸数值
+
+- 属性名带 `Width` / `Height` / `Size`（字节）/ `Length`（字符）的，单位由名字决定，不在名字里写单位。
+- 长度类属性接受 `number | string`：number 按 px，string 原样作为 CSS 长度。库内统一用一个 `toCssSize()` 归一，不允许一处只收 number、另一处只收 `"48px"`。
+- 上下限命名：值域用 `min` / `max`；尺寸用 `xxxMinWidth` / `xxxMaxWidth` / `xxxMinHeight` / `xxxMaxHeight`。不用 `leftMin`、`topMax`、`minYear` 这类省略维度或把维度放前面的写法。
+- 数量上限用 `maxXxx`（`maxFiles` `maxLength` `maxTabWidth`），与上一条不冲突：前者是"最多几个"，后者是"最大多宽"。
+
+## R8 集合与选中态
+
+| 语义 | 名字 | 用于 |
+| --- | --- | --- |
+| 数据行 | `list` | DataTable、ListBox、ConciseListTable、Transfer 的 `sourceList / targetList` |
+| 可选项 | `options` | OptionsSelect、GroupCheckBox、UnitNumberEditor（`units` → `options`）、PromptsTextEditor（`words` → `options`） |
+| 导航/结构项 | `items` | Breadcrumbs、Navigator、NavigatorMenu、Accordion、ProgressStepBar（`steps` → `items`）、Tabs（`tabs` 保留，见例外） |
+| 动作 | `actions` | ActionBar、Dialog、Card、DataTable 行动作 |
+| 树 | `tree` / `nodes` | TreeView 用 `tree`（`HierarchyTree`），级联选择器用 `nodes` |
+
+- 多选结果 `selectedXxx`，复数：`selectedRows` `selectedItems` `selectedOptions`。
+- 单选高亮（非表单值）`activeXxx`：`activeTab` `activeItem` `activeNode`。
+- 表单控件的选择结果就是 `value`（R3）。
+- 键/文本字段：`keyField` 默认 `"code"`，`textField` 默认 `"text"`，`childrenField` 默认 `"children"`。凡接受对象数组的组件都应提供这两个属性并给默认值，不做必填。
+- 例外：`Tabs.keyField` 默认 `"id"`、`Tabs.tabs`（tab 对象既是数据又是状态），在文档中标注。
+
+## R9 文本类属性
+
+| 名字 | 含义 |
+| --- | --- |
+| `label` | 控件**旁边**的说明文字（CheckBox、RadioButton、FormField、Button、动作对象） |
+| `text` | 控件**自身**显示的内容（Tag、LookupEditor 的显示文本） |
+| `title` | 容器或条目的标题（Card、Box、Page、Dialog、Accordion 项、步骤、列头） |
+| `comment` | 标题下的附注 |
+| `placeholder` | 空值时的输入提示 |
+| `emptyText` | 无数据时的文案（列表、表格、下拉） |
+| `noResultsText` | 有数据但筛选无结果时的文案 |
+| `xxxText` | 某个按钮的文字：`confirmText` `closeText` `cancelText` |
+| `labelSuffix` | 标签后缀（`':'`） |
+
+- 不用 `topic`（→ `title`）、`closeButton`（→ `closeText`）、`emptyIndicator`（→ `emptyText`）。
+- 二元开关文字用 `checkedText` / `uncheckedText`（Switch 的 `checkLabel / uncheckLabel`），因为那是控件自身显示的内容而不是旁边的标签。
+
+## R10 数据对象
+
+**动作对象**（按钮栏、对话框、卡片、表格行、右键菜单共用同一形状）：
+
+```ts
+interface Action<T = any> {
+    label: string;              // 显示文字
+    icon?: string;
+    tooltip?: string;
+    disabled?: boolean;
+    type?: ButtonType;          // 语义（R6），不再各自写字面量
+    handler: (data: T) => void | Promise<void>;
+}
+```
+
+- 处理函数字段一律 `handler`；不用 `callback` / `handle` / `action`。
+- 文字字段一律 `label`；不用 `text`。
+- 分隔符用 `null` 元素（`ButtonActions` 已是此约定），`ContextMenuItem.separator` 与之对齐。
+- `CardAction` 补上 `label`，`img` 保留为卡片特有扩展。
+
+**列定义**：表头文字统一 `title`（ConciseListTable 已是），`DataColumn.text` 改为 `title`；`field` `width` `minWidth` `align` `wrap` `formatter` `visible` `resizable` `frozen` 沿用。
+
+**选项对象**：`{ code, text }` 是默认形状（与 `keyField / textField` 默认值一致），可通过字段名属性映射。
+
+## R11 回调与函数类型命名
+
+| 用途 | 命名 | 例子 |
+| --- | --- | --- |
+| 事件通知 | `OnXxx` | `OnClick` `OnClose` `OnPageChange` `OnItemClick` `OnMenuItemClick` |
+| 否决钩子 | `BeforeXxx` | `BeforeClose` `BeforeRemove` `BeforeNodeChange` `BeforeTransfer` |
+| 取值 | `GetXxx` | `GetText` `GetIcon` `GetRowActions` `GetCellStyle` |
+| 判定 | `IsXxx` | `IsLeaf` `IsNodeVisible` `IsBranch` |
+| 异步加载 | `XxxLoader` / `LoadXxx` | `ListLazyLoader` `TreeLazyLoader` `LoadChildren` |
+| 比较/过滤/格式化 | `XxxFn` | `CompareFn` `FilterFn` `FormatFn` |
+| 显示型命令式 API | `ShowXxx` | `ShowInfo` `ShowConfirm` |
+
+- 退役后缀：`Handler` `Callback` `Fun` `Function`；退役前缀式：`FunFilter`。
+- 一个名字只能有一个定义。同名类型在两个入口导出不同签名（当前的 `GetRowActions`、`ActionCallback`）是必须立即修复的缺陷。
+- `types.ts` 只放跨模块共享的类型；只被一个模块使用的类型放在该模块目录下并从该模块的 `index.ts` 导出。
+
+## R12 实例方法
+
+- 只用 `export function xxx()`，不用 `export let xxx = () => …` / `export const`。
+- 动词原形，与 DOM 方法同名时同名：`focus()` `blur()` `clear()` `open()` `close()` `reset()` `push()` `pop()`。
+- 不用 `setFocus`、`closePopup`、`getNativeElement`（→ `getElement()`；取 DOM 节点的方法统一 `getElement`）。
+- 方法不作为 prop 传入。`clear?: () => void` 这类"父组件把方法塞给子组件"的写法只允许在内部组件间使用，不得出现在公开组件的 Props 里。
+
+## R13 事件接口与参数名
+
+- 全库只有一份事件接口：`src/lib/form/events.ts`，导出 `FocusEvents` `KeyboardEvents` `InputEvents` `MouseEvents` `CompositionEvents` `ClipboardEvents`，以及聚合的 `EditorEvents`。
+- 参数名统一 `event`。
+- `CommonFieldProps<T>` 通过 `extends FocusEvents` 获得 `onfocus / onblur`，自己只声明 `onchange?: (value: T) => void`；不再在组件里手写同名事件。
+- 透传给原生元素的事件名单（`keyboardAttrs` 一类）必须从上述接口的键派生，不允许手写字符串数组。
+
+## R14 默认值与类型细节
+
+- `theme?: string` 默认 `undefined`；默认外观由 CSS 负责，不在 JS 里写 `'theme-light'`。
+- `style?: string` / `class?: string` 默认 `''`，不接受 `null`。
+- 可选属性的类型不含 `null`（用 `undefined`）；只有当 `null` 是有意义的业务值（"显式清空"）时才允许出现。
+- 枚举型属性用字面量联合并导出类型；不用 `string` 泛泛接收。
+- 时间粒度类型统一 `TimePrecision = 'H' | 'M' | 'S'`，prop 名保留 `precision`（与 NumberEditor 的小数位 `precision: number` 同名但类型不同，属于可接受的同名，因为不会出现在同一组件上）。
+
+## R15 Snippet（插槽）命名
+
+- 主内容 `children`；命名插槽用**位置或角色的名词**：`header` `footer` `left` `right` `top` `bottom` `sidebar` `leadingIcon` `trailingIcon` `popup` `item` `tab` `node`。
+- 不用 `headerBar` / `pageHeader` / `headerExt`（→ `header` / `headerExtra`），不用 `fromChild / toChild`（→ `from / to`），不用 `popupLayer`（→ `popup`）。
+- 渲染定制优先用 Snippet；`itemRender`（传组件）与 `tabRender`（传函数）暂时保留，统一为 `item` / `tab` Snippet 作为后续独立改造项。
+
+---
+
+## 附录 A　5.0.x → 5.1.0 新旧对照表
+
+5.1.0 不保留旧名：下表中的"旧"在 5.1.0 里已经不存在，调用方需要整体替换。
+
+### A1　属性、回调、实例方法
+
+| 组件 / 文件 | 旧 | 新 | 规则 |
+| --- | --- | --- | --- |
+| Dialog、CommonDialog、DialogManager | `onClose` | `onclose` | R1 |
+| CascadeOptionSelect、CascadePanel、OptionsBox | `onSelect`（loader） | `loadChildren` | R1/R11 |
+| ConciseListTable | `rowClickHandler` | `onRowClick` | R1 |
+| ConciseListTable | `setFocus()` | `focus()` | R12 |
+| Navigator | `itemClickHandler` | `onItemClick` | R1 |
+| TreeView | `onContextMenu` | `oncontextmenu` | R1 |
+| TreeNodeView | `onToggle` | `ontoggle` | R1 |
+| CommonPicker | `iconClickHandler` | `onIconClick` | R1 |
+| CommonDialog | `confirmHandler` | `onconfirm` | R1 |
+| CommonDialog | `enableConfirm` | `confirmable` | R5 |
+| Tabs | `onremove`（返回 boolean） | `beforeRemove`（否决）+ `onremove`（通知） | R2 |
+| TreeView | `onchange: OnNodeSelectionChange`（返回 Promise<boolean>） | `beforeChange` + `onchange` | R2 |
+| Transfer | `onchange: TransferData` | `beforeTransfer` + `onchange` | R2 |
+| Dialog | `closeConfirm` | `beforeClose` | R2 |
+| AttachmentEditor、ImageFilesField | `removeFileConfirm` | `beforeRemove` | R2 |
+| AttachmentEditor（5.1 重写） | `onUpload`、弹窗式 `FileUploadPanel` | 删除；上传内联，新增 `layout` `height` `multiple` `uploadText` `emptyText` `showThumbnail` `onPreview` `onremove` `ondownload` `onFileRejected` `onUploadError`、方法 `openFileDialog()` | R1 R6 R9 |
+| ImageFilesField（5.1 重写） | 组件名 `ImageFilesField`、导出路径 `./ImageFiles`、目录 `image-files` | `ImageEditor`、`./ImageEditor`、`image_editor`；属性同 AttachmentEditor，另有 `previewable` `onPreview` | R5 |
+| AttachmentEditor | 导出路径 `./AttachmentFiles` | `./AttachmentEditor` | — |
+| Dialog | `hideClose` | `closable=false` | R5 |
+| Dialog | `closeButton` | `closeText` | R9 |
+| ModalPopover | `canClose` | `closable` | R5 |
+| Picker 系列、LookupEditor、TimeEditor | `mandatory` | `clearable=false` | R5 |
+| CommonEditor | `canClean` | `clearable` | R5 |
+| CommonRangeEditor | `showFromClean / showToClean` | `fromClearable / toClearable` | R5 |
+| BasePicker、CommonPicker | `isOpen` | `expanded` | R5 |
+| AccordionItemView | `isOpen` | `expanded` | R5 |
+| CommonPopupEditor | `hasFocus` | 内部状态 | R3 |
+| CommonPopupEditor | `closePopup()` | `close()` | R12 |
+| CommonEditor | `getNativeElement()` | `getElement()` | R12 |
+| ContentPanel | `displayHorizontalScroll` | `showHorizontalScroll` | R5 |
+| IndicatorColumn | `displayNo` | `showRowNo` | R5 |
+| CommonPicker | `displayAction` | `showAction` | R5 |
+| InputOptionsSelect | `displayCode` | `showCode` | R5 |
+| ScrollBar | `enable` | `disabled` | R5 |
+| OptionsSelect、OptionsMultiSelect | `disableOptions` | `disabledOptions` | R5/D1 |
+| FormEditor、CommonPicker、CommonRangeEditor | `className` | `class` | R4 |
+| Card、Box | `contentStyle` | `content$style` | R4 |
+| GroupCheckBox、GroupRadioBox | `itemStyle` | `item$style` | R4 |
+| Popover | `bodyClass` | `body$class` | R4 |
+| Pagination、PaginationPanel | `type` | `variant` | R6 |
+| Pagination、PaginationPanel | `big: boolean` | `size: Size` | R6 |
+| ProgressBar | `type` | `variant` | R6 |
+| ProgressBar | `size: number` / `height: number` | `diameter` / `thickness` | R6 |
+| Tag | `size: 'middle'` | `'medium'` | R6 |
+| Button、IconButton、TextButton、Tag | `size: 'big'` | `'large'` | R6 |
+| NavigatorMenu | `variant: 'vertical' \| 'horizontal'` | `direction` | R6 |
+| GridField | `arrangement` | `direction` | R6 |
+| FormField | `layout` / `FieldLayout` | `direction` / `Direction` | R6 |
+| Card | `actionsAlign` | `actions$align` | R4 |
+| ColumnsLayout | `leftMin / leftMax / rightMin / rightMax` | `leftMinWidth / leftMaxWidth / rightMinWidth / rightMaxWidth` | R7 |
+| RowsLayout | `topMin / topMax / bottomMin / bottomMax` | `topMinHeight / topMaxHeight / bottomMinHeight / bottomMaxHeight` | R7 |
+| YearPickupPanel | `minYear / maxYear` | `min / max` | R7 |
+| Drawer | `width: number` | `width: number \| string` | R7 |
+| Accordion | `accordions` | `items` | R8 |
+| NavigatorMenu | `menuItems` | `items` | R8 |
+| ProgressStepBar | `steps` | `items` | R8 |
+| ActionBar | `buttons` | `actions` | R8 |
+| UnitNumberEditor | `units` | `options` | R8 |
+| PromptsTextEditor | `words` | `options` | R8 |
+| ListBox | `selectedList` | `selectedItems` | R8 |
+| DataTable | `emptyIndicator` | `emptyText` | R9 |
+| ProgressStep、ProgressStepBlock | `topic` | `title` | R9 |
+| Switch | `checkLabel / uncheckLabel` | `checkedText / uncheckedText` | R9 |
+| PaginationPanel | `rowCountLabel` | `rowCountText` | R9 |
+| DataColumn | `warp` | `wrap` | 拼写 |
+| DataColumn | `text` | `title` | R10 |
+| Pagination、PaginationPanel | `pageNo`（非 bindable） | `pageNo = $bindable()` | R3 |
+| 7 个组件 | `export let focus = () => …` | `export function focus()` | R12 |
+| Accordion | `theme = 'theme-light'` | `theme = undefined` | R14 |
+| ListBox | `style?: string \| null` | `style?: string` | R14 |
+| DateTimePicker、TimePanel | `Precision` / 内联字面量 | `TimePrecision` | R14 |
+
+### A2　缺陷修复（随 5.1.0 一并完成）
+
+| 位置 | 处理 |
+| --- | --- |
+| `EditorEvents.ts` `keyboardAttrs` | 改为从 `KeyboardEvents` 键派生，含 `onkeydown` |
+| TextEditor、NumberEditor | 接线 `onfocus / onblur / onkeydown / onkeyup / onkeypress` |
+| `types.ts` | 删除 `GetRowActions`（与 DataTable 冲突）、`HandleAction`、`OnSelectedHandler`；`CellAction / GetCellAction` 迁入 `data_table/lib` |
+| `ContextMenuItem.ts` | `ActionCallback` → `ContextMenuAction`；字段 `text`/`action` → `label`/`handler` |
+| ImageFilesField | 从 Props 删除 `text` |
+| AttachmentEditor、ImageEditor | 类型图标 `icon_google_image`、`icon_google_picture` 在图标字体里不存在（图片 / PDF 类型一直没有图标） → `icon_google_insert_photo`、`icon_google_picture_as_pdf` |
+| Tooltip（5.1.1） | 目标元素在 tooltip 显示期间被移除 / 隐藏时浏览器不再派发 `mouseleave`，tooltip 会永久停留 → 改为跟踪目标元素（`MutationObserver` + `isConnected` / `checkVisibility`），并在 `data-tip` 清空、滚动、窗口失焦时收起 |
+| overlay/dialog（5.1.1） | 删除无人引用的死文件 `DialogActions.ts`（仍带退役名 `closeConfirm`）；`DialogCloseConfirm.ts` 更名为 `BeforeClose.ts`，与其中的类型名一致 |
+| InputOptionsSelect README | 与实现对齐（实现 `hideOptions / disabledOptions` 或删文档） |
+
+### A3　类型与数据对象
+
+| 旧 | 新 |
+| --- | --- |
+| `MouseClickHandler` | `OnClick` |
+| `TabActionHandler` | `OnTabAction` |
+| `TabCloseHandler` | `BeforeTabClose` |
+| `RowClickHandler` | `OnRowClick` |
+| `ItemClickHandler` | `OnItemClick` |
+| `OnMenuClick` | `OnMenuItemClick` |
+| `OnNodeSelectionChange` | `BeforeNodeChange` |
+| `TransferData` | `BeforeTransfer` |
+| `OnSelectHandler` / `OnChangeHandler` | `OnSelect` / `OnChange` |
+| `FunFilter` | `FilterFn` |
+| `CompareFunction` | `CompareFn` |
+| `FormatCell` | `FormatCellFn` |
+| `UploadFile`（class）、`FileUploadBar`、`FileUploadPanel` | 删除；上传任务改为组件内部的 `UploadTask`（`id/file/name/type/size/progress/status/error/thumbnail`），新增 `UploadedFile`（`AttachmentFile` / `ImageFile` 的公共基类）、`RejectReason` |
+| `NodeVisibleFun` | `IsNodeVisible` |
+| `IsLeafDetermine` | `IsLeaf` |
+| `LoadChildrenFun` | `LoadChildren` |
+| `ShowInfoFun` / `ShowConfirmFun` | `ShowInfo` / `ShowConfirm` |
+| `ActionFunction` / `ActionCallback` / `HandleAction` | `ActionHandler`（定义在 `types.ts`，唯一允许的 Handler：它是名词"处理器"而非后缀） |
+| `HrefLink.text` / `HrefLink.action` / `HrefAction` | `label` / `handler` / `OnHrefClick` |
+| `RowEventHandler` / `RowSelectEventHandler` / `SelectionEventHandler` / `TableEventHandler`（DataTable 内部） | `OnRowExpand` / `OnRowSelect` / `OnSelectAll` / `OnWidthChange` |
+| `ErrorHandler`（FileUpload） | `OnError` |
+| `DataColumn.escapeHTML` / `Column.escapeHTML`（误命名） | 删除，只保留 `renderHTML` |
+| `ListBox.onSelectChange`、`CalendarBase.onselect`、`ConciseListTable.setFocus()`、`Dialog.hideClose` / `closeButton` | 删除 |
+| `RowAction.callback`、`CardAction.callback`、`CellAction.handle`、`ContextMenuItem.action` | `handler` |
+| `CellAction.text`、`ContextMenuItem.text` | `label` |
+| `RowAction.type: 'primary' \| …` | `type?: ButtonType` |
+| `ButtonSize` | `Size` |
+| `FieldLayout` | `Direction` |
+| `form/types.ts` 的 `EditorEvents` + `common_editor/EditorEvents.ts` | 合并为 `form/events.ts`（`EditorEvents`、`KeyboardEvents`、`FocusEvents` … 只从这里导入），参数名 `event` |
+| `headerBar` / `pageHeader` / `headerExt` / `fromChild` / `toChild` / `popupLayer` | `header` / `header` / `headerExtra` / `from` / `to` / `popup` |
+
+---
+
+## 附录 B　词表（起名先查这里）
+
+**状态布尔**：`disabled` `readonly` `compact` `visible` `expanded` `virtual` `round` `shadow` `exclusive` `autoFit` `autoHeight` `autoScroll` `autofocus` `indeterminate` `frozen` `alternative`
+**能力布尔**：`closable` `removable` `clearable` `resizable` `selectable` `expandable` `confirmable` `sortable` `previewable`
+**显示布尔**：`showText` `showIndicator` `showRowNo` `showAction` `showCode` `showHorizontalScroll` `showVerticalScroll` `showHex` `showRgb` `showAlternative` `showThumbnail`
+**外观**：`type` `variant` `direction` `layout` `position` `align` `size` `theme` `style` `class` `color` `icon`
+**尺寸**：`width` `height` `minWidth` `maxWidth` `minHeight` `maxHeight` `rowHeight` `headerHeight` `diameter` `thickness` `margin` `offset` `gap` `span` `rowSpan` `colSpan`
+**范围**：`min` `max` `fromValue` `toValue` `maxFiles` `maxSize` `maxLength` `multiple` `accept` `precision` `allowNegative`
+**集合**：`list` `options` `items` `actions` `tree` `nodes` `columns` `tabs`
+**选中**：`value` `selectedRows` `selectedItems` `activeTab` `activeItem` `activeNode` `group`
+**字段映射**：`keyField` `textField` `iconField` `childrenField` `abbrField`
+**文本**：`label` `text` `title` `comment` `placeholder` `emptyText` `noResultsText` `confirmText` `closeText` `cancelText` `checkedText` `uncheckedText` `uploadText` `labelSuffix` `tooltip` `error`
+**加载与过滤**：`lazyLoader` `loadChildren` `filter` `filterFn` `filterText` `filterPlaceholder`
+**透传部件**：`input$` `menu$` `label$` `content$` `item$` `body$` `header$` `footer$` `dialog$` `page$` `box$` `tag$` `actions$`
+**事件（通知）**：`onchange` `onclick` `ondblclick` `onfocus` `onblur` `oninput` `onclose` `onselect` `ondelete` `onremove` `onrefresh` `onconfirm` `onaction` `ondownload` `onretry` `onkeydown` `onkeyup` `onkeypress` `oncontextmenu` `ontoggle` `onItemClick` `onRowClick` `onIconClick` `onPageSizeChange` `onFileUploaded` `onFileRejected` `onUploadError` `onPreview` `onResizeEnd`；DataTable 内部面板间：`onCellClick` `onWidthChange` `onRowExpand` `onRowSelectChange` `onToggleSelectAll`
+**钩子（否决）**：`beforeClose` `beforeRemove` `beforeChange` `beforeTransfer`
+**实例方法**：`focus()` `blur()` `clear()` `open()` `close()` `reset()` `push()` `pop()` `getElement()` `openFileDialog()`
+**Snippet**：`children` `header` `headerExtra` `footer` `left` `right` `top` `bottom` `sidebar` `home` `leadingIcon` `trailingIcon` `popup` `item` `tab` `node` `chevronIcon` `nodeIcon` `from` `to`
+
+---
+
+## 附录 C　新组件自检清单
+
+1. 所有属性名都在附录 B 里，或已把新词加进附录 B。
+2. `value` 是 `$bindable()` 且类型具体；调用方需要回写的状态都可绑定。
+3. 回调全部是 `onXxx`（通知，返回 void）或 `beforeXxx`（否决，返回 boolean | Promise<boolean>）；没有 `xxxHandler` / `xxxCallback` / `xxxConfirm`。
+4. 事件参数：`onchange` 传值；DOM 同名事件传 `event`。
+5. 布尔属性正向、无 `is/has`、显示用 `show`、能力用 `xxxable`。
+6. `type` 只表示语义，`variant` 表示外观，`direction` 表示纵横，`size` 用 `Size`。
+7. 子元素透传只用 `<部件>$<属性>`；根元素用 `style` / `class`。
+8. 集合用 `list / options / items / actions`；多选 `selectedXxx`，高亮 `activeXxx`。
+9. 文本用 `label / text / title / placeholder / emptyText / xxxText`。
+10. 数据对象里的处理函数叫 `handler`，文字叫 `label`。
+11. 导出类型名符合 R11，且在 `./types` 与模块入口之间没有同名不同义。
+12. 实例方法用 `export function`，动词原形。
+13. `theme` 默认 `undefined`，`style / class` 默认 `''`。
+14. 在 `docs/components` 重新生成后，属性表里没有附录 A 中的任何旧名；`pnpm run check:naming` 为 0 项。

package/docs/components/README.md

@@ -0,0 +1,135 @@
+# Topside Element 组件文档
+
+本目录依据 `package.json exports` 和组件源码自动生成，共收录 **73** 个公开组件。每个组件都包含独立属性文档和可复制的 Svelte 示例。
+
+- 重新生成：`pnpm run docs:components`
+- 属性来源：组件内 `Props` 接口及 `$props()` 默认值
+- 文档不复用历史 README，避免旧 API 污染
+
+## 表单
+
+| 组件 | 导入路径 | 示例 | 属性数 |
+| --- | --- | --- | ---: |
+| [AttachmentEditor](./attachment-editor/README.md) | `@ticatec/topside-elements/AttachmentEditor` | [示例](./attachment-editor/example.svelte) | 30 |
+| [CascadeOptionsSelect](./cascade-options-select/README.md) | `@ticatec/topside-elements/CascadeOptionsSelect` | [示例](./cascade-options-select/example.svelte) | 27 |
+| [Checkbox](./checkbox/README.md) | `@ticatec/topside-elements/Checkbox` | [示例](./checkbox/example.svelte) | 11 |
+| [ColorPicker](./color-picker/README.md) | `@ticatec/topside-elements/ColorPicker` | [示例](./color-picker/example.svelte) | 13 |
+| [DatePicker](./date-picker/README.md) | `@ticatec/topside-elements/DatePicker` | [示例](./date-picker/example.svelte) | 19 |
+| [DateRange](./date-range/README.md) | `@ticatec/topside-elements/DateRange` | [示例](./date-range/example.svelte) | 14 |
+| [DateTimePicker](./date-time-picker/README.md) | `@ticatec/topside-elements/DateTimePicker` | [示例](./date-time-picker/example.svelte) | 17 |
+| [GroupCheckBox](./group-check-box/README.md) | `@ticatec/topside-elements/GroupCheckBox` | [示例](./group-check-box/example.svelte) | 20 |
+| [GroupRadioBox](./group-radio-box/README.md) | `@ticatec/topside-elements/GroupRadioBox` | [示例](./group-radio-box/example.svelte) | 17 |
+| [ImageEditor](./image-editor/README.md) | `@ticatec/topside-elements/ImageEditor` | [示例](./image-editor/example.svelte) | 30 |
+| [InputOptionsSelect](./input-options-select/README.md) | `@ticatec/topside-elements/InputOptionsSelect` | [示例](./input-options-select/example.svelte) | 23 |
+| [LookupEditor](./lookup-editor/README.md) | `@ticatec/topside-elements/LookupEditor` | [示例](./lookup-editor/example.svelte) | 17 |
+| [MemoEditor](./memo-editor/README.md) | `@ticatec/topside-elements/MemoEditor` | [示例](./memo-editor/example.svelte) | 24 |
+| [NumberEditor](./number-editor/README.md) | `@ticatec/topside-elements/NumberEditor` | [示例](./number-editor/example.svelte) | 25 |
+| [NumberRange](./number-range/README.md) | `@ticatec/topside-elements/NumberRange` | [示例](./number-range/example.svelte) | 14 |
+| [OptionsMultiSelect](./options-multi-select/README.md) | `@ticatec/topside-elements/OptionsMultiSelect` | [示例](./options-multi-select/example.svelte) | 27 |
+| [OptionsSelect](./options-select/README.md) | `@ticatec/topside-elements/OptionsSelect` | [示例](./options-select/example.svelte) | 25 |
+| [PasswordEditor](./password-editor/README.md) | `@ticatec/topside-elements/PasswordEditor` | [示例](./password-editor/example.svelte) | 17 |
+| [PromptsTextEditor](./prompts-text-editor/README.md) | `@ticatec/topside-elements/PromptsTextEditor` | [示例](./prompts-text-editor/example.svelte) | 18 |
+| [RadioButton](./radio-button/README.md) | `@ticatec/topside-elements/RadioButton` | [示例](./radio-button/example.svelte) | 10 |
+| [SearchBox](./search-box/README.md) | `@ticatec/topside-elements/SearchBox` | [示例](./search-box/example.svelte) | 17 |
+| [Switch](./switch/README.md) | `@ticatec/topside-elements/Switch` | [示例](./switch/example.svelte) | 5 |
+| [TextEditor](./text-editor/README.md) | `@ticatec/topside-elements/TextEditor` | [示例](./text-editor/example.svelte) | 22 |
+| [TimeEditor](./time-editor/README.md) | `@ticatec/topside-elements/TimeEditor` | [示例](./time-editor/example.svelte) | 19 |
+| [UnitNumberEditor](./unit-number-editor/README.md) | `@ticatec/topside-elements/UnitNumberEditor` | [示例](./unit-number-editor/example.svelte) | 19 |
+
+## 布局
+
+| 组件 | 导入路径 | 示例 | 属性数 |
+| --- | --- | --- | ---: |
+| [ActionBar](./action-bar/README.md) | `@ticatec/topside-elements/ActionBar` | [示例](./action-bar/example.svelte) | 4 |
+| [AppTopBar](./app-top-bar/README.md) | `@ticatec/topside-elements/AppTopBar` | [示例](./app-top-bar/example.svelte) | 6 |
+| [Box](./box/README.md) | `@ticatec/topside-elements/Box` | [示例](./box/example.svelte) | 8 |
+| [CriteriaField](./criteria-field/README.md) | `@ticatec/topside-elements/CriteriaField` | [示例](./criteria-field/example.svelte) | 7 |
+| [FlexForm](./topside-flexi/README.md) | `@ticatec/topside-elements/FlexForm` | [示例](./topside-flexi/example.svelte) | 3 |
+| [FlexRowForm](./flex-row-form/README.md) | `@ticatec/topside-elements/FlexRowForm` | [示例](./flex-row-form/example.svelte) | 4 |
+| [FormField](./form-field/README.md) | `@ticatec/topside-elements/FormField` | [示例](./form-field/example.svelte) | 11 |
+| [GridForm](./grid-form/README.md) | `@ticatec/topside-elements/GridForm` | [示例](./grid-form/example.svelte) | 5 |
+| [Page](./page/README.md) | `@ticatec/topside-elements/Page` | [示例](./page/example.svelte) | 12 |
+
+## 导航
+
+| 组件 | 导入路径 | 示例 | 属性数 |
+| --- | --- | --- | ---: |
+| [Breadcrumbs](./breadcrumbs/README.md) | `@ticatec/topside-elements/Breadcrumbs` | [示例](./breadcrumbs/example.svelte) | 6 |
+| [Navigator](./navigator/README.md) | `@ticatec/topside-elements/Navigator` | [示例](./navigator/example.svelte) | 6 |
+| [NavigatorMenu](./navigator-menu/README.md) | `@ticatec/topside-elements/NavigatorMenu` | [示例](./navigator-menu/example.svelte) | 6 |
+| [PageStack](./page-stack/README.md) | `@ticatec/topside-elements/PageStack` | [示例](./page-stack/example.svelte) | 5 |
+| [Pagination](./pagination/README.md) | `@ticatec/topside-elements/Pagination` | [示例](./pagination/example.svelte) | 7 |
+| [ProgressStepBar](./progress-step-bar/README.md) | `@ticatec/topside-elements/ProgressStepBar` | [示例](./progress-step-bar/example.svelte) | 4 |
+| [Tabs](./tabs/README.md) | `@ticatec/topside-elements/Tabs` | [示例](./tabs/example.svelte) | 15 |
+
+## 反馈
+
+| 组件 | 导入路径 | 示例 | 属性数 |
+| --- | --- | --- | ---: |
+| [ProgressBar](./progress-bar/README.md) | `@ticatec/topside-elements/ProgressBar` | [示例](./progress-bar/example.svelte) | 6 |
+
+## 浮层与弹窗
+
+| 组件 | 导入路径 | 示例 | 属性数 |
+| --- | --- | --- | ---: |
+| [CommonDialog](./common-dialog/README.md) | `@ticatec/topside-elements/CommonDialog` | [示例](./common-dialog/example.svelte) | 10 |
+| [Dialog](./dialog/README.md) | `@ticatec/topside-elements/Dialog` | [示例](./dialog/example.svelte) | 11 |
+| [DialogBoard](./dialog-board/README.md) | `@ticatec/topside-elements/DialogBoard` | [示例](./dialog-board/example.svelte) | 0 |
+| [Drawer](./drawer/README.md) | `@ticatec/topside-elements/Drawer` | [示例](./drawer/example.svelte) | 5 |
+| [FullScreenOverlay](./full-screen-overlay/README.md) | `@ticatec/topside-elements/FullScreenOverlay` | [示例](./full-screen-overlay/example.svelte) | 2 |
+| [PopupHint](./popup-hint/README.md) | `@ticatec/topside-elements/PopupHint` | [示例](./popup-hint/example.svelte) | 2 |
+| [Tooltip](./tooltip/README.md) | `@ticatec/topside-elements/Tooltip` | [示例](./tooltip/example.svelte) | 2 |
+
+## 复合组件
+
+| 组件 | 导入路径 | 示例 | 属性数 |
+| --- | --- | --- | ---: |
+| [PaginationPanel](./pagination-panel/README.md) | `@ticatec/topside-elements/PaginationPanel` | [示例](./pagination-panel/example.svelte) | 13 |
+| [Transfer](./transfer/README.md) | `@ticatec/topside-elements/Transfer` | [示例](./transfer/example.svelte) | 12 |
+
+## 命令式服务
+
+| 组件 | 导入路径 | 示例 | 属性数 |
+| --- | --- | --- | ---: |
+| [ContextMenu](./context-menu/README.md) | `@ticatec/topside-elements/ContextMenu` | [示例](./context-menu/example.svelte) | 8 |
+| [Indicator](./indicator/README.md) | `@ticatec/topside-elements/Indicator` | [示例](./indicator/example.svelte) | 4 |
+| [MessageBox](./message-box/README.md) | `@ticatec/topside-elements/MessageBox` | [示例](./message-box/example.svelte) | 9 |
+| [Toast](./toast/README.md) | `@ticatec/topside-elements/Toast` | [示例](./toast/example.svelte) | 8 |
+
+## 数据表格
+
+| 组件 | 导入路径 | 示例 | 属性数 |
+| --- | --- | --- | ---: |
+| [DataTable](./data-table/README.md) | `@ticatec/topside-elements/DataTable` | [示例](./data-table/example.svelte) | 15 |
+
+## 数据展示
+
+| 组件 | 导入路径 | 示例 | 属性数 |
+| --- | --- | --- | ---: |
+| [Accordion](./accordion/README.md) | `@ticatec/topside-elements/Accordion` | [示例](./accordion/example.svelte) | 5 |
+| [Card](./card/README.md) | `@ticatec/topside-elements/Card` | [示例](./card/example.svelte) | 11 |
+| [ConciseDataTable](./concise-data-table/README.md) | `@ticatec/topside-elements/ConciseDataTable` | [示例](./concise-data-table/example.svelte) | 10 |
+| [ListBox](./list-box/README.md) | `@ticatec/topside-elements/ListBox` | [示例](./list-box/example.svelte) | 20 |
+| [TreeView](./tree-view/README.md) | `@ticatec/topside-elements/TreeView` | [示例](./tree-view/example.svelte) | 17 |
+
+## 通用
+
+| 组件 | 导入路径 | 示例 | 属性数 |
+| --- | --- | --- | ---: |
+| [Button](./button/README.md) | `@ticatec/topside-elements/Button` | [示例](./button/example.svelte) | 14 |
+| [Icon](./icon/README.md) | `@ticatec/topside-elements/Icon` | [示例](./icon/example.svelte) | 8 |
+| [IconButton](./icon-button/README.md) | `@ticatec/topside-elements/IconButton` | [示例](./icon-button/example.svelte) | 12 |
+| [Separator](./separator/README.md) | `@ticatec/topside-elements/Separator` | [示例](./separator/example.svelte) | 2 |
+| [Split](./split/README.md) | `@ticatec/topside-elements/Split` | [示例](./split/example.svelte) | 5 |
+| [Tag](./tag/README.md) | `@ticatec/topside-elements/Tag` | [示例](./tag/example.svelte) | 10 |
+| [TextButton](./text-button/README.md) | `@ticatec/topside-elements/TextButton` | [示例](./text-button/example.svelte) | 13 |
+
+## 应用布局
+
+| 组件 | 导入路径 | 示例 | 属性数 |
+| --- | --- | --- | ---: |
+| [ClassicLayout](./classic-layout/README.md) | `@ticatec/topside-elements/app-layout/ClassicLayout` | [示例](./classic-layout/example.svelte) | 15 |
+| [ColumnsLayout](./columns-layout/README.md) | `@ticatec/topside-elements/app-layout/ColumnsLayout` | [示例](./columns-layout/example.svelte) | 13 |
+| [HeaderLayout](./header-layout/README.md) | `@ticatec/topside-elements/app-layout/HeaderLayout` | [示例](./header-layout/example.svelte) | 8 |
+| [RowsLayout](./rows-layout/README.md) | `@ticatec/topside-elements/app-layout/RowsLayout` | [示例](./rows-layout/example.svelte) | 13 |
+| [SidebarLayout](./sidebar-layout/README.md) | `@ticatec/topside-elements/app-layout/SidebarLayout` | [示例](./sidebar-layout/example.svelte) | 8 |

package/docs/components/accordion/README.md

@@ -0,0 +1,71 @@
+# Accordion
+
+数据展示组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+可折叠的内容分组容器，用较小空间组织层级信息。
+
+## 适用场景
+
+- FAQ、设置分组和详情折叠区
+- 需要按标题展开或收起大段内容
+
+## 导入
+
+```ts
+import Accordion from '@ticatec/topside-elements/Accordion';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `style` | 否 | `string` | 否 | `''` | 否 | 附加到组件根元素的内联样式。 |
+| `compact` | 否 | `boolean` | 否 | `false` | 否 | 启用紧凑尺寸，减少组件高度和内边距。 |
+| `items` | 是 | `AccordionItem[]` | 否 | `[]` | 否 | 折叠项列表 |
+| `exclusive` | 否 | `boolean` | 否 | `false` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `theme` | 否 | `string` | 否 | `undefined` | 否 | 组件主题标识，通常通过 `data-theme` 选择对应 CSS 变量。 |
+
+> 组件的“可绑定”表示源码使用了 Svelte 5 的 `$bindable`；服务的“响应式”表示成员使用了 `$state`。复杂类型请同时参考 TypeScript 自动补全。
+
+## 重要属性说明
+
+### `items`
+
+折叠项列表
+
+- 类型：`AccordionItem[]`
+- 默认值：`[]`
+- 示例写法：`items={[]}`
+
+## 相关类型定义
+
+以下定义帮助理解复杂属性的数据结构；其中部分辅助类型属于内部实现，不一定是独立导出入口。
+
+### `AccordionItem`
+
+```ts
+export default interface AccordionItem {
+    title: string;
+    content: Snippet;
+}
+```
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import Accordion from '@ticatec/topside-elements/Accordion';
+</script>
+
+<Accordion
+  compact={true}
+  items={[]}
+/>
+```
+
+## 源码
+
+- `src/lib/data_display/accordion/Accordion.svelte`

package/docs/components/accordion/example.svelte

@@ -0,0 +1,8 @@
+<script lang="ts">
+  import Accordion from '@ticatec/topside-elements/Accordion';
+</script>
+
+<Accordion
+  compact={true}
+  items={[]}
+/>