@hinen/pro-element-plus 1.7.17 → 1.8.0

package/dist/skills/using-data-table/references/examples.md

@@ -0,0 +1,347 @@
+# DataTable examples
+
+## 1. Standard admin list page
+
+Use `DataTable` when the page is a classic list page with:
+
+- filters
+- remote rows
+- pagination
+- sorting
+- refresh
+- row-level actions
+
+Typical fit:
+
+- user management
+- order lists
+- audit records
+- resource inventories
+
+Recommended pattern:
+
+- define query metadata in `columns`
+- map backend response through `queryFn`
+- keep table shell standard
+- add toolbar actions through the `toolbar` slot
+
+Minimal pattern:
+
+```vue
+<DataTable :columns="columns" :query-fn="queryFn" />
+```
+
+## 2. Static readonly table
+
+Use static mode when rows already exist and the page still benefits from the standard table shell.
+
+Minimal pattern:
+
+```vue
+<DataTable :columns="columns" :data="rows" :pagination="false" />
+```
+
+Typical fit:
+
+- small comparison tables
+- review screens
+- embedded feature detail lists
+- local-only display data
+
+Recommended pattern:
+
+- pass `columns`
+- pass `data`
+- set `pagination: false` when paging is unnecessary
+
+Do not build around `refresh()` or `refetch()` in this mode.
+
+## 3. Controlled table shell
+
+Use `useDataTable()` and the exported helpers when parent code needs explicit control.
+
+Minimal pattern:
+
+```ts
+const table = useDataTable();
+table.setSearchParams({ status: 'active' });
+```
+
+Typical fit:
+
+- toolbar buttons should set filters
+- route changes should restore search params
+- tabs should reset pagination
+- external controls should trigger a refresh
+
+Recommended pattern:
+
+- let `DataTable` own rendering and query execution
+- let parent code coordinate through imperative methods only where needed
+- avoid rebuilding query state outside the component unless the feature truly requires it
+
+## 4. Delayed query until prerequisites are ready
+
+Use `enabled` when querying should wait for setup work.
+
+Minimal pattern:
+
+```vue
+<DataTable
+  :columns="columns"
+  :query-fn="queryFn"
+  :enabled="Boolean(projectId)"
+/>
+```
+
+Typical fit:
+
+- option dictionaries must load first
+- route state is incomplete
+- a project or tenant must be selected first
+- inactive tabs should not fetch yet
+
+Recommended pattern:
+
+- keep `columns` stable
+- compute `enabled` from the prerequisite
+- pass external `loading` if setup work is separate from table querying
+
+## 5. Shared empty and error states
+
+Use `DataTable` with `../../using-config-provider/SKILL.md` when multiple list pages should share fallback rendering.
+
+Minimal pattern:
+
+```vue
+<ConfigProvider>
+  <DataTable :columns="columns" :query-fn="queryFn" />
+</ConfigProvider>
+```
+
+Typical fit:
+
+- one feature contains several list pages
+- empty states should use the same wording and visuals
+- error states should stay consistent across the module
+
+Prefer ConfigProvider-level defaults over repeating custom slots everywhere.
+
+## 6. Selection-oriented batch actions
+
+Use row selection and `selectionBar` when the page supports batch operations.
+
+Minimal pattern:
+
+```vue
+<DataTable :columns="columns" :query-fn="queryFn" row-selection />
+```
+
+Typical fit:
+
+- bulk enable or disable
+- batch export
+- multi-row review
+- batch delete with confirmation
+
+Recommended pattern:
+
+- keep selection behavior inside the `DataTable` shell
+- add `selection` when the built-in checkbox review should stay useful across pages
+- replace the default `selectionBar` only when page-specific actions need fully custom UI
+
+## 7. Built-in cross-page checkbox review
+
+Use `selection` when checkbox selection should keep the built-in review state across pages.
+
+Minimal pattern:
+
+```vue
+<DataTable
+  :columns="columns"
+  :query-fn="queryFn"
+  row-key="id"
+  row-selection
+  :selection="{
+    formatter: (row) => row.name,
+  }"
+/>
+```
+
+Recommended pattern:
+
+- treat `selection` as the item-level customization API for this review behavior
+- provide `rowKey` so built-in review items can aggregate across pages
+- use `formatter(row)` when the default tag text needs a small change
+- use `render(...)` when each built-in review item needs custom rendering
+- use `selectionBar.reviewPopoverProps` when the built-in 查看已选 popover needs container-level tweaks (default placement is 'bottom-start')
+- keep using `selectionChange` and `getSelectionRows()` as current-page signals
+
+Use the `selectionBar` slot only when the page should replace the built-in review UI completely.
+
+## 12. Controlled selection with v-model:selectedRowKeys
+
+Use `v-model:selectedRowKeys` when parent state should control checkbox selection.
+
+Minimal pattern:
+
+```vue
+<DataTable
+  v-model:selectedRowKeys="selectedKeys"
+  :columns="columns"
+  :query-fn="queryFn"
+  row-key="id"
+  row-selection
+/>
+```
+
+```ts
+import { ref } from 'vue';
+import type { DataTableSelectionKeyType } from '@hinen/pro-element-plus';
+
+const selectedKeys = ref<DataTableSelectionKeyType[]>([]);
+
+// Set selection programmatically
+function selectAllVisible(rows: User[]) {
+  selectedKeys.value = rows.map((row) => row.id);
+}
+
+// Clear selection
+function clearSelection() {
+  selectedKeys.value = [];
+}
+
+// React to changes
+watch(selectedKeys, (keys) => {
+  console.log('Selected:', keys);
+});
+```
+
+Recommended pattern:
+
+- use `v-model:selectedRowKeys` for controlled mode, no prop for internal mode
+- always provide `rowKey` when selection should persist across pages
+- update the model ref directly to change selection from parent
+- use `selection` prop only for customization, never for state control
+- instance methods like `getSelectionRows()` still work in controlled mode
+
+## 13. Cross-page selection with controlled mode
+
+Use `v-model:selectedRowKeys` with `rowKey` to maintain selection across pagination.
+
+Minimal pattern:
+
+```vue
+<DataTable
+  v-model:selectedRowKeys="selectedKeys"
+  :columns="columns"
+  :query-fn="queryFn"
+  row-key="id"
+  row-selection
+  :selection="{
+    formatter: (row) => row.name,
+  }"
+/>
+```
+
+```ts
+const selectedKeys = ref<DataTableSelectionKeyType[]>([]);
+
+// Select rows on page 1
+selectedKeys.value = [1, 2, 3];
+
+// Navigate to page 2 and add more selections
+// selectedKeys.value now contains keys from both pages: [1, 2, 3, 4, 5]
+selectedKeys.value = [...selectedKeys.value, 4, 5];
+
+// Built-in review UI shows all 5 selections
+```
+
+Recommended pattern:
+
+- `rowKey` is required for cross-page selection to work correctly
+- the model accepts keys from any page, not just the current one
+- built-in review UI aggregates selections across pages when `rowKey` is provided
+- `selectionChange` event still emits current-page changes only
+
+## 8. Sticky large-page table
+
+Use `fixedHeader` or `fixedFooter` when the page is long enough that default table scrolling becomes awkward.
+
+Typical fit:
+
+- long filter forms above the table
+- large result sets
+- bottom pagination that should stay reachable
+
+Add sticky behavior after the main search and pagination flow is already correct.
+
+## 9. DataTable inside an overlay shell
+
+Use `DataTable` inside `../../using-modal/SKILL.md` or `../../using-drawer/SKILL.md` when the filter-plus-results surface belongs in a temporary overlay rather than a full page.
+
+Minimal pattern:
+
+```vue
+<Drawer :model-value="visible" title="Select User" @cancel="visible = false">
+  <DataTable :columns="columns" :query-fn="queryFn" />
+</Drawer>
+```
+
+Typical fit:
+
+- select-from-list drawers
+- review-history overlays
+- search-and-pick workflows inside a larger page
+
+## 10. Built-in radio single-select row
+
+Use `highlightCurrentRow` when the page wants `DataTable` to own a radio-based single-select row state.
+
+Minimal pattern:
+
+```vue
+<DataTable
+  ref="tableRef"
+  :columns="columns"
+  :data="rows"
+  row-key="id"
+  highlight-current-row
+  @current-change="handleCurrentChange"
+/>
+```
+
+Recommended pattern:
+
+- provide `rowKey` when selection should stay stable across data updates
+- treat the radio as the selection trigger
+- use `setCurrentRow(row)` for imperative select
+- use `setCurrentRow()` to clear the single-select current row
+
+Do not expect row clicks to change the current row in this mode.
+
+Checkbox review changes do not affect this single-select mode.
+
+## 11. Controlled current row with `currentRowKey`
+
+Use `currentRowKey` when parent state should control which single-select row is active.
+
+Minimal pattern:
+
+```vue
+<DataTable
+  :columns="columns"
+  :data="rows"
+  row-key="id"
+  highlight-current-row
+  :current-row-key="currentRowKey"
+/>
+```
+
+Recommended pattern:
+
+- always pair `currentRowKey` with `rowKey`
+- set `currentRowKey` to a row key to select that row
+- set `currentRowKey` to `undefined` to clear the current single-select row
+
+Do not use `clearSelection()` for this flow; that targets checkbox selection rather than current-row state.

package/dist/skills/using-data-table/references/gotchas.md

@@ -0,0 +1,114 @@
+# DataTable gotchas
+
+- `queryFn` must return `{ data, total, success }`  
+  Returning only an array, or using fields such as `rows` or `count`, does not match the component contract.
+
+- `success` is part of the error-state contract  
+  `success: false` is treated as an error signal, so backend mapping should be explicit.
+
+- Static mode and remote mode are different  
+  If you pass `data`, do not assume query lifecycle methods like `refresh()` or `refetch()` are available.
+
+- Query form rendering is column-driven  
+  If every column uses `hideInForm` or lacks `prop`, the generated query form may not render.
+
+- Form instance methods require a real generated form  
+  Calls such as `resetForm()`, `validateForm()`, or `setFormData()` only make sense when form items actually exist.
+
+- `setSearchParams()` has side effects  
+  By default it can merge params, reset pagination, restore form state, and trigger a refetch in remote mode.
+
+- `enabled` should gate real prerequisites  
+  Use it when querying should wait for required state, not as a vague workaround for unstable behavior.
+
+- `hidePaginationWhenEmpty` changes page behavior  
+  Empty results can hide the pager entirely, so verify that this matches product intent.
+
+- `selectionBar` is built in  
+  If selected-row UI appears unexpectedly, check whether row selection and `selectionBar` are both active.
+
+- `selection` customizes built-in checkbox review items  
+  Keep item-level customization in `selection`, not in extra events or instance methods.
+
+- Built-in cross-page checkbox review requires `rowKey`  
+  Without `rowKey`, the review UI cannot aggregate selected rows across pages correctly.
+
+- `formatter(row)` and `render(...)` have different jobs  
+  Use `formatter(row)` to change the default tag text. Use `render(...)` to replace each built-in review item render.
+
+- `selectionBar.reviewPopoverProps` only customizes the popover container  
+  Use it for built-in 查看已选 popover props, not for per-tag content or close behavior.
+
+- The `selectionBar` slot replaces the built-in review UI  
+  Once the slot is used, do not expect the default cross-page review UI to remain visible.
+
+- In cross-page checkbox mode, the `selectionBar` slot gets aggregated rows  
+  Search, Reset, pagination, or other current-page changes should not make the slot-level `selection` suddenly drop to the current page only.
+
+- `selectionChange` and `getSelectionRows()` stay current-page oriented  
+  They do not become cross-page aggregate contracts just because the built-in review UI keeps state across pages.
+
+- `loading` combines with internal query loading  
+  External loading and internal query loading both affect the final visual loading state.
+
+- `columns` affects both display and query behavior  
+  A column change can alter the table UI and the generated search form at the same time.
+
+- `valueEnum` is not only visual  
+  It can influence generated query controls as well as table display.
+
+- Nested multi-level headers are not the primary target  
+  If complex header composition is central to the feature, do not assume `DataTable` is the best fit.
+
+- Do not overuse imperative control  
+  `useDataTable()` should coordinate the component, not replace its internal state model.
+
+- `highlightCurrentRow` is not visual-only in `DataTable`  
+  It enables the built-in radio single-select mode, changes click behavior, and prepends a radio column.
+
+- Row click and current-row change are decoupled in single-select mode  
+  With `highlightCurrentRow: true`, clicking a row still emits `rowClick`, but only clicking the radio changes the current row.
+
+- Controlled single-select requires `rowKey`  
+  If you pass `currentRowKey` without `rowKey`, do not expect stable controlled current-row behavior.
+
+- Clearing single-select current row uses `setCurrentRow()`, not `clearSelection()`  
+  `clearSelection()` is for checkbox selection. To clear the current radio-selected row, use `setCurrentRow()` or set `currentRowKey` to `undefined`.
+
+- Empty `currentRowKey` clearing is a wrapper convention  
+  `DataTable` treats `currentRowKey: undefined` as “clear current row” in single-select mode. This is aligned with the wrapper behavior, not a documented Element Plus `current-row-key` guarantee.
+
+- An unmatched `currentRowKey` also clears the current single-select row  
+  If the provided key does not resolve to any row in the current data set, `DataTable` clears the current row instead of preserving the previous one.
+
+- Single-select behavior is unchanged
+  The built-in cross-page checkbox review does not alter `highlightCurrentRow`, radio selection, or current-row APIs.
+
+- `v-model:selectedRowKeys` enables controlled selection mode
+  When this prop is provided, parent state owns selection. The component emits `update:selectedRowKeys` but defers to the prop value.
+
+- Controlled mode vs internal mode
+  Internal mode: component owns selection state, use `clearSelection()` and `getSelectionRows()`.
+  Controlled mode: parent owns state via `selectedRowKeys`, update the model ref directly to change selection.
+
+- `selection` prop is for customization only
+  Never use `selection` to control selection state. Use `v-model:selectedRowKeys` for state control.
+  `formatter` and `render` in `selection` only customize the review item display.
+
+- `selectedRowKeys` requires matching `rowKey` for cross-page selection
+  Without `rowKey`, the component cannot identify which rows correspond to the provided keys across pages.
+
+- `selectedRowKeys` accepts keys from any page
+  In controlled mode with `rowKey`, the model can contain keys from pages other than the current one. The built-in review UI aggregates them.
+
+- `selectionChange` remains current-page oriented
+  Even in controlled mode, `selectionChange` only emits changes for the current page. Use `watch(selectedKeys)` to observe all changes.
+
+- Instance methods still work in controlled mode
+  `getSelectionRows()`, `toggleRowSelection()`, etc. continue to function, but parent state should be the primary control mechanism.
+
+- Clearing selection in controlled mode
+  Call `clearSelection()` or set `selectedKeys.value = []`. In controlled mode, prefer updating the model directly.
+
+- Default placement for review popover is 'bottom-start'
+  When using `selectionBar.reviewPopoverProps`, the default placement is 'bottom-start'. Only override if necessary.