@ticatec/uniface-element 5.0.4 → 5.1.0

package/docs/NAMING.md

@@ -0,0 +1,362 @@
+# uniface-element Component API Naming Guide
+
+> Version: 1.1 (finalized 2026-09-05; shipped with 5.1.0). Chinese original: [NAMING_CN.md](./NAMING_CN.md) — the Chinese text is authoritative if the two ever disagree.
+> Scope: props, callbacks, instance methods and exported types of every public `@ticatec/uniface-element` component, plus the data objects components consume (column definitions, action objects, …). Internal sub-components (`data_table/parts/*`, `*Panel.svelte`, …) should follow the guide too but carry no compatibility promise.
+> Status: in force from **5.1.0**. 5.1.0 is the Svelte 5 rewrite of the package, so **no old-name aliases or `@deprecated` transitions are kept**; Appendix A is the complete 5.0.x → 5.1.0 old → new table for migration.
+
+---
+
+## 0. Principles
+
+1. **One meaning, one name across the whole library.** Check the vocabulary in Appendix B before naming a new prop; if the word is missing, add it to the vocabulary first.
+2. **Stay close to Svelte 5 / DOM intuition.** Whenever a native attribute exists (`disabled`, `readonly`, `placeholder`, `onclick`), reuse its name instead of inventing a synonym.
+3. **A name says *what*, not *where*.** Component names never leak into prop names (`accordions`, `menuItems` are not allowed).
+4. **A type name says *what it is for*, not *that it is a function*.** The suffixes `Handler / Callback / Fun / Function` are retired.
+
+---
+
+## R1 Event callbacks
+
+| Rule | Form | Examples |
+| --- | --- | --- |
+| Events that exist on DOM elements | all-lowercase `on` + word | `onchange` `onclick` `onfocus` `onblur` `oninput` `onclose` `onselect` `onkeydown` |
+| Custom multi-word events | `on` + PascalCase | `onItemClick` `onPageSizeChange` `onFileUploaded` `onResizeEnd` `onRowClick` `onIconClick` |
+| Forbidden | `xxxHandler`, `xxxCallback`, `handleXxx` as prop names | ~~`rowClickHandler`~~ ~~`closeCallback`~~ ~~`handleCellClick`~~ |
+| Forbidden | the same event in two casings | ~~`onClose` + `onclose`~~ |
+
+"Exists on DOM elements" means an HTML element has an `onxxx` attribute of that name. `onclose` (`<dialog>`), `onselect`, `ontoggle` (`<details>`), `oncontextmenu` all count and are written lowercase.
+
+**Do not use the `on` prefix for callbacks that are not events.** A function that returns data is a loader (R11: `XxxLoader` / `loadXxx`) — e.g. the cascade select loads the next level through `loadChildren`, not `onSelect`.
+
+**Parameters.**
+- `onchange` passes only the new value: `(value: T) => void`. Never the DOM event.
+- DOM-named events other than value changes (`onclick`, `onfocus`, `onkeydown`, …) pass the native event; the parameter is always called `event` (never `e`).
+- Custom events order their arguments "subject first, context second": `onItemClick(item, event?)`. A DOM-named event that carries business data appends it after the event object: `oncontextmenu(event, data)`.
+
+## R2 Notification vs. veto
+
+| Kind | Name | Returns | Meaning |
+| --- | --- | --- | --- |
+| Notification | `onXxx` | `void` | it **has happened**; the caller cannot stop it |
+| Veto hook | `beforeXxx` | `boolean \| Promise<boolean>` | it **is about to happen**; returning `false` cancels it |
+
+- `onchange` is always a notification. Components that need to ask before changing (Tabs closing, TreeView node switch, Transfer moves, Dialog close, attachment/image removal) get a separate `beforeXxx`: `beforeRemove` `beforeChange` `beforeClose` `beforeTransfer`.
+- `beforeXxx` takes the same arguments as its `onXxx` counterpart.
+- The `xxxConfirm` hook naming is retired (`closeConfirm` → `beforeClose`, `removeFileConfirm` → `beforeRemove`). Confirming is one possible implementation of the hook, not its meaning.
+- Plain switches ("may this be closed at all?") are `xxxable` booleans (R5), never hooks.
+
+## R3 Values and binding
+
+- The current value of a form control is always `value` and always `$bindable()`. Range controls use `fromValue` / `toValue`.
+- `value` has a concrete type (`string` / `number` / `UniDate` / `T`); `CommonFieldProps` becomes generic `CommonFieldProps<T>` with `onchange?: (value: T) => void`. No more `value?: any`.
+- Any state the caller may need to write back (`pageNo`, `visible`, `expanded`, `activeTab`, `selectedRows`) is `$bindable()`. Read-only derived values never appear in Props (e.g. `ImageFilesField.text`).
+- `RadioButton` keeps Svelte's `bind:group` convention — the only exception.
+
+## R4 Sub-element pass-through
+
+- The only form is `<part>$<attribute>`, where the attribute part is exactly the attribute name of the target element/component:
+  `menu$height` `label$style` `content$style` `input$class` `input$readonly` `item$style` `body$class` `footer$style` `dialog$style` `page$style`
+- Part names are fixed: `input` `menu` `label` `content` `item` `body` `header` `footer` `dialog` `page` `box` `tag`. New part names are added to Appendix B first.
+- camelCase variants are forbidden: ~~`contentStyle`~~ ~~`itemStyle`~~ ~~`bodyClass`~~ ~~`labelStyle`~~.
+- The root element's style and class are simply `style` and `class`; never `className`.
+
+## R5 Boolean props
+
+- Positive names, no `is` / `has` prefix: `disabled` `readonly` `compact` `visible` `expanded` `virtual` `round`.
+- "Show a part" uses the `show` prefix only: `showText` `showIndicator` `showRowNo` `showAction` `showHorizontalScroll`. No `display*`, no `hide*`.
+- "Allow an operation" uses `xxxable`: `closable` `removable` `clearable` `resizable` `selectable` `confirmable`. No `canXxx`, no `mandatory` (→ `clearable=false`), no `hideClose` (→ `closable=false`).
+- Overlay visibility (Drawer, Dialog, Popover, Overlay, Preview) is `visible` (bindable); expandable containers (accordion items, tree nodes, dropdown panels) use `expanded` (bindable). `isOpen`, `hasFocus`, `open` are not prop names.
+- Enabling/disabling is `disabled` only; never `enable` / `enabled`.
+
+## R6 Semantics, appearance, direction, size
+
+| Prop | Meaning | Values |
+| --- | --- | --- |
+| `type` | **semantic intent** (primary / secondary / danger …) | `ButtonType = 'default' \| 'primary' \| 'secondary' \| 'third' \| 'forth'`; Button's native type is `htmlType` |
+| `variant` | **visual shape / style** | component-specific literal union: Button `'plain' \| 'round' \| ''`, Tag `'borderless' \| 'border' \| 'round'`, Card `'plain' \| '3d'`, Pagination `'plain' \| 'round' \| 'circle'`, ProgressBar `'circular' \| 'linear'`, form editors `EditorVariant` |
+| `direction` | **orientation** | `Direction = 'vertical' \| 'horizontal'`, one shared type |
+| `position` | **relative placement** | `'left' \| 'right' \| 'top' \| 'bottom'` (Drawer, …) |
+| `align` | **alignment** | `'left' \| 'center' \| 'right'` (`'distribute'` only for the Card action bar) |
+| `size` | **discrete size step** | `Size = 'small' \| 'medium' \| 'large'`, one shared type; no `big` / `middle`, no `big: boolean` |
+
+- `type` no longer expresses shape (Pagination and ProgressBar `type` → `variant`).
+- `variant` no longer expresses orientation (NavigatorMenu) and is never an unconstrained `string` (Row / Cell / GridForm / GridField either get a literal union or lose the prop).
+- `arrangement` and `layout` meaning orientation become `direction`; the `FieldLayout` type is renamed `Direction`.
+- Numeric sizes (ProgressBar `size: number`) are renamed to the concrete dimension (`diameter` / `thickness`) so `size` stays reserved for the step enum.
+
+## R7 Dimensions
+
+- Props named with `Width` / `Height` / `Size` (bytes) / `Length` (characters) get their unit from the name; units never appear in the name.
+- Length props accept `number | string`: a number is px, a string is passed through as a CSS length. One shared `toCssSize()` normalizes; a prop that accepts only numbers in one place and only `"48px"` in another is not allowed.
+- Bounds: value ranges use `min` / `max`; dimensions use `xxxMinWidth` / `xxxMaxWidth` / `xxxMinHeight` / `xxxMaxHeight`. Forms that drop the dimension or put it first (`leftMin`, `topMax`, `minYear`) are not allowed.
+- Count limits use `maxXxx` (`maxFiles` `maxLength` `maxTabWidth`) — "at most how many" as opposed to "at most how wide".
+
+## R8 Collections and selection
+
+| Meaning | Name | Used by |
+| --- | --- | --- |
+| Data rows | `list` | DataTable, ListBox, ConciseListTable, Transfer's `sourceList / targetList` |
+| Selectable options | `options` | OptionsSelect, GroupCheckBox, UnitNumberEditor (`units` → `options`), PromptsTextEditor (`words` → `options`) |
+| Navigation / structural items | `items` | Breadcrumbs, Navigator, NavigatorMenu, Accordion, ProgressStepBar (`steps` → `items`), Tabs (`tabs` kept, see exceptions) |
+| Actions | `actions` | ActionBar, Dialog, Card, DataTable row actions |
+| Trees | `tree` / `nodes` | TreeView uses `tree` (`HierarchyTree`), the cascade select uses `nodes` |
+
+- Multi-selection results are `selectedXxx`, plural: `selectedRows` `selectedItems` `selectedOptions`.
+- Single highlight (not a form value) is `activeXxx`: `activeTab` `activeItem` `activeNode`.
+- A form control's selection result is `value` (R3).
+- Field mapping: `keyField` defaults to `"code"`, `textField` to `"text"`, `childrenField` to `"children"`. Every component that accepts object arrays offers both with defaults — never required.
+- Exceptions: `Tabs.keyField` defaults to `"id"`, and `Tabs.tabs` (tab objects are both data and state); both are documented as such.
+
+## R9 Text props
+
+| Name | Meaning |
+| --- | --- |
+| `label` | the caption **next to** a control (CheckBox, RadioButton, FormField, Button, action objects) |
+| `text` | the content a control **itself** displays (Tag, LookupEditor display text) |
+| `title` | the title of a container or entry (Card, Box, Page, Dialog, accordion item, step, column header) |
+| `comment` | a note under the title |
+| `placeholder` | the hint shown when the value is empty |
+| `emptyText` | the message when there is no data (list, table, dropdown) |
+| `noResultsText` | the message when data exists but the filter matches nothing |
+| `xxxText` | the caption of a specific button: `confirmText` `closeText` `cancelText` |
+| `labelSuffix` | label suffix (`':'`) |
+
+- Retired: `topic` (→ `title`), `closeButton` (→ `closeText`), `emptyIndicator` (→ `emptyText`).
+- Two-state switch captions are `checkedText` / `uncheckedText` (Switch's `checkLabel / uncheckLabel`) because they are content the control displays, not a caption beside it.
+
+## R10 Data objects
+
+**Action objects** (button bars, dialogs, cards, table rows and context menus share one shape):
+
+```ts
+interface Action<T = any> {
+    label: string;              // caption
+    icon?: string;
+    tooltip?: string;
+    disabled?: boolean;
+    type?: ButtonType;          // semantics (R6), no per-object literal unions
+    handler: (data: T) => void | Promise<void>;
+}
+```
+
+- The function field is always `handler`; never `callback` / `handle` / `action`.
+- The caption field is always `label`; never `text`.
+- A separator is a `null` element (`ButtonActions` already does this); `ContextMenuItem.separator` aligns with it.
+- `CardAction` gains `label`; `img` stays as a card-specific extension.
+
+**Column definitions**: the header caption is `title` everywhere (ConciseListTable already is; `DataColumn.text` → `title`). `field` `width` `minWidth` `align` `wrap` `formatter` `visible` `resizable` `frozen` remain.
+
+**Option objects**: `{ code, text }` is the default shape (matching the `keyField / textField` defaults) and can be remapped through the field-name props.
+
+## R11 Callback and function type names
+
+| Purpose | Pattern | Examples |
+| --- | --- | --- |
+| Event notification | `OnXxx` | `OnClick` `OnClose` `OnPageChange` `OnItemClick` `OnMenuItemClick` |
+| Veto hook | `BeforeXxx` | `BeforeClose` `BeforeRemove` `BeforeNodeChange` `BeforeTransfer` |
+| Getter | `GetXxx` | `GetText` `GetIcon` `GetRowActions` `GetCellStyle` |
+| Predicate | `IsXxx` | `IsLeaf` `IsNodeVisible` `IsBranch` |
+| Async loading | `XxxLoader` / `LoadXxx` | `ListLazyLoader` `TreeLazyLoader` `LoadChildren` |
+| Compare / filter / format | `XxxFn` | `CompareFn` `FilterFn` `FormatFn` |
+| Imperative "show" APIs | `ShowXxx` | `ShowInfo` `ShowConfirm` |
+
+- Retired suffixes: `Handler` `Callback` `Fun` `Function`; retired prefix form: `FunFilter`.
+- One name, one definition. The same type name exported with different signatures from two entry points (today's `GetRowActions`, `ActionCallback`) is a defect to fix immediately.
+- `types.ts` holds only types shared across modules; a type used by one module lives in that module's directory and is exported from its `index.ts`.
+
+## R12 Instance methods
+
+- `export function xxx()` only; never `export let xxx = () => …` / `export const`.
+- Bare verbs, matching DOM method names where one exists: `focus()` `blur()` `clear()` `open()` `close()` `reset()` `push()` `pop()`.
+- Retired: `setFocus`, `closePopup`, `getNativeElement` (→ `getElement()`; the method returning the DOM node is always `getElement`).
+- Methods are not passed in as props. `clear?: () => void`-style "parent injects a method into the child" is allowed only between internal components, never in a public component's Props.
+
+## R13 Event interfaces and parameter names
+
+- Exactly one event interface file: `src/lib/form/events.ts`, exporting `FocusEvents` `KeyboardEvents` `InputEvents` `MouseEvents` `CompositionEvents` `ClipboardEvents` and the aggregate `EditorEvents`.
+- The parameter name is `event` everywhere.
+- `CommonFieldProps<T>` gets `onfocus / onblur` via `extends FocusEvents` and declares only `onchange?: (value: T) => void` itself; components never re-declare those events.
+- Lists of event names forwarded to native elements (the `keyboardAttrs` kind) are derived from the keys of those interfaces, never hand-written string arrays.
+
+## R14 Defaults and type details
+
+- `theme?: string` defaults to `undefined`; the default look is CSS's job, not `'theme-light'` in JS.
+- `style?: string` / `class?: string` default to `''` and never accept `null`.
+- Optional prop types do not include `null` (use `undefined`); `null` is allowed only when it is a meaningful business value ("explicitly cleared").
+- Enum-like props use exported literal unions, never a bare `string`.
+- The time-granularity type is `TimePrecision = 'H' | 'M' | 'S'`; the prop stays `precision` (sharing the name with NumberEditor's decimal `precision: number` is acceptable because they never co-exist on one component).
+
+## R15 Snippet (slot) names
+
+- Main content is `children`; named snippets use **a noun for position or role**: `header` `footer` `left` `right` `top` `bottom` `sidebar` `leadingIcon` `trailingIcon` `popup` `item` `tab` `node`.
+- Retired: `headerBar` / `pageHeader` / `headerExt` (→ `header` / `headerExtra`), `fromChild / toChild` (→ `from / to`), `popupLayer` (→ `popup`).
+- Render customization prefers Snippets; `itemRender` (component) and `tabRender` (function) stay for now — unifying them into `item` / `tab` snippets is a separate follow-up.
+
+---
+
+## Appendix A — 5.0.x → 5.1.0 old → new
+
+5.1.0 keeps none of the old names: every "Old" entry below no longer exists, callers must replace them wholesale.
+
+### A1 Props, callbacks, instance methods
+
+| Component / file | Old | New | Rule |
+| --- | --- | --- | --- |
+| 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` (returns boolean) | `beforeRemove` (veto) + `onremove` (notify) | 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 (rewritten in 5.1) | `onUpload`, modal `FileUploadPanel` | removed; uploads run inline. New: `layout` `height` `multiple` `uploadText` `emptyText` `showThumbnail` `onPreview` `onremove` `ondownload` `onFileRejected` `onUploadError`, method `openFileDialog()` | R1 R6 R9 |
+| ImageFilesField (rewritten in 5.1) | component `ImageFilesField`, export `./ImageFiles`, folder `image-files` | `ImageEditor`, `./ImageEditor`, `image_editor`; same props as AttachmentEditor plus `previewable` `onPreview` | R5 |
+| AttachmentEditor | export path `./AttachmentFiles` | `./AttachmentEditor` | — |
+| Dialog | `hideClose` | `closable=false` | R5 |
+| Dialog | `closeButton` | `closeText` | R9 |
+| ModalPopover | `canClose` | `closable` | R5 |
+| Picker family, 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` | internal state | 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 |
+| 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` | typo |
+| DataColumn | `text` | `title` | R10 |
+| Pagination, PaginationPanel | `pageNo` (not bindable) | `pageNo = $bindable()` | R3 |
+| 7 components | `export let focus = () => …` | `export function focus()` | R12 |
+| Accordion | `theme = 'theme-light'` | `theme = undefined` | R14 |
+| ListBox | `style?: string \| null` | `style?: string` | R14 |
+| DateTimePicker, TimePanel | `Precision` / inline literal | `TimePrecision` | R14 |
+
+### A2 Defects fixed together with 5.1.0
+
+| Location | Change |
+| --- | --- |
+| `EditorEvents.ts` `keyboardAttrs` | derive from the `KeyboardEvents` keys (includes `onkeydown`) |
+| TextEditor, NumberEditor | wire up `onfocus / onblur / onkeydown / onkeyup / onkeypress` |
+| `types.ts` | remove `GetRowActions` (clashes with DataTable), `HandleAction`, `OnSelectedHandler`; move `CellAction / GetCellAction` into `data_table/lib` |
+| `ContextMenuItem.ts` | `ActionCallback` → `ContextMenuAction`; fields `text`/`action` → `label`/`handler` |
+| ImageFilesField | remove `text` from Props |
+| AttachmentEditor, ImageEditor | type icons `icon_google_image` / `icon_google_picture` do not exist in the icon font (image / PDF types never had an icon) → `icon_google_insert_photo` / `icon_google_picture_as_pdf` |
+| InputOptionsSelect README | align with the implementation (implement `hideOptions / disabledOptions` or drop the docs) |
+
+### A3 Types and data objects
+
+| Old | New |
+| --- | --- |
+| `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` | removed; upload tasks are the component-internal `UploadTask` (`id/file/name/type/size/progress/status/error/thumbnail`); new `UploadedFile` (base of `AttachmentFile` / `ImageFile`) and `RejectReason` |
+| `NodeVisibleFun` | `IsNodeVisible` |
+| `IsLeafDetermine` | `IsLeaf` |
+| `LoadChildrenFun` | `LoadChildren` |
+| `ShowInfoFun` / `ShowConfirmFun` | `ShowInfo` / `ShowConfirm` |
+| `ActionFunction` / `ActionCallback` / `HandleAction` | `ActionHandler` (defined once in `types.ts`; the one permitted "Handler": here it is the noun, not a suffix) |
+| `HrefLink.text` / `HrefLink.action` / `HrefAction` | `label` / `handler` / `OnHrefClick` |
+| `RowEventHandler` / `RowSelectEventHandler` / `SelectionEventHandler` / `TableEventHandler` (DataTable internals) | `OnRowExpand` / `OnRowSelect` / `OnSelectAll` / `OnWidthChange` |
+| `ErrorHandler` (FileUpload) | `OnError` |
+| `DataColumn.escapeHTML` / `Column.escapeHTML` (misnomer) | removed, only `renderHTML` remains |
+| `ListBox.onSelectChange`, `CalendarBase.onselect`, `ConciseListTable.setFocus()`, `Dialog.hideClose` / `closeButton` | removed |
+| `RowAction.callback`, `CardAction.callback`, `CellAction.handle`, `ContextMenuItem.action` | `handler` |
+| `CellAction.text`, `ContextMenuItem.text` | `label` |
+| `RowAction.type: 'primary' \| …` | `type?: ButtonType` |
+| `ButtonSize` | `Size` |
+| `FieldLayout` | `Direction` |
+| `EditorEvents` in `form/types.ts` + `common_editor/EditorEvents.ts` | merged into `form/events.ts` (`EditorEvents`, `KeyboardEvents`, `FocusEvents` … are imported only from there), parameter `event` |
+| `headerBar` / `pageHeader` / `headerExt` / `fromChild` / `toChild` / `popupLayer` | `header` / `header` / `headerExtra` / `from` / `to` / `popup` |
+
+---
+
+## Appendix B — Vocabulary (check here before naming anything)
+
+**State booleans**: `disabled` `readonly` `compact` `visible` `expanded` `virtual` `round` `shadow` `exclusive` `autoFit` `autoHeight` `autoScroll` `autofocus` `indeterminate` `frozen` `alternative`
+**Capability booleans**: `closable` `removable` `clearable` `resizable` `selectable` `expandable` `confirmable` `sortable` `previewable`
+**Show booleans**: `showText` `showIndicator` `showRowNo` `showAction` `showCode` `showHorizontalScroll` `showVerticalScroll` `showHex` `showRgb` `showAlternative` `showThumbnail`
+**Appearance**: `type` `variant` `direction` `layout` `position` `align` `size` `theme` `style` `class` `color` `icon`
+**Dimensions**: `width` `height` `minWidth` `maxWidth` `minHeight` `maxHeight` `rowHeight` `headerHeight` `diameter` `thickness` `margin` `offset` `gap` `span` `rowSpan` `colSpan`
+**Ranges**: `min` `max` `fromValue` `toValue` `maxFiles` `maxSize` `maxLength` `multiple` `accept` `precision` `allowNegative`
+**Collections**: `list` `options` `items` `actions` `tree` `nodes` `columns` `tabs`
+**Selection**: `value` `selectedRows` `selectedItems` `activeTab` `activeItem` `activeNode` `group`
+**Field mapping**: `keyField` `textField` `iconField` `childrenField` `abbrField`
+**Text**: `label` `text` `title` `comment` `placeholder` `emptyText` `noResultsText` `confirmText` `closeText` `cancelText` `checkedText` `uncheckedText` `uploadText` `labelSuffix` `tooltip` `error`
+**Loading and filtering**: `lazyLoader` `loadChildren` `filter` `filterFn` `filterText` `filterPlaceholder`
+**Pass-through parts**: `input$` `menu$` `label$` `content$` `item$` `body$` `header$` `footer$` `dialog$` `page$` `box$` `tag$` `actions$`
+**Events (notifications)**: `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`; between DataTable's internal panels: `onCellClick` `onWidthChange` `onRowExpand` `onRowSelectChange` `onToggleSelectAll`
+**Hooks (veto)**: `beforeClose` `beforeRemove` `beforeChange` `beforeTransfer`
+**Instance methods**: `focus()` `blur()` `clear()` `open()` `close()` `reset()` `push()` `pop()` `getElement()` `openFileDialog()`
+**Snippets**: `children` `header` `headerExtra` `footer` `left` `right` `top` `bottom` `sidebar` `home` `leadingIcon` `trailingIcon` `popup` `item` `tab` `node` `chevronIcon` `nodeIcon` `from` `to`
+
+---
+
+## Appendix C — Checklist for a new component
+
+1. Every prop name is in Appendix B, or the new word has been added there.
+2. `value` is `$bindable()` with a concrete type; every state the caller may write back is bindable.
+3. Callbacks are all `onXxx` (notification, void) or `beforeXxx` (veto, boolean | Promise<boolean>); no `xxxHandler` / `xxxCallback` / `xxxConfirm`.
+4. Arguments: `onchange` passes the value; DOM-named events pass `event`.
+5. Booleans are positive, without `is/has`; `show` for visibility, `xxxable` for capability.
+6. `type` is semantics only, `variant` is appearance, `direction` is orientation, `size` uses `Size`.
+7. Sub-element pass-through is `<part>$<attribute>` only; the root uses `style` / `class`.
+8. Collections are `list / options / items / actions`; multi-select `selectedXxx`, highlight `activeXxx`.
+9. Text uses `label / text / title / placeholder / emptyText / xxxText`.
+10. In data objects the function is `handler` and the caption is `label`.
+11. Exported type names follow R11, and no name is exported with different meanings from `./types` and a module entry.
+12. Instance methods are `export function`, bare verbs.
+13. `theme` defaults to `undefined`, `style / class` to `''`.
+14. After regenerating `docs/components`, the property tables contain none of the old names from Appendix A; `pnpm run check:naming` reports 0 findings.