@hinen/pro-element-plus 1.7.17 → 1.8.1

package/dist/skills/using-data-select/references/props.md

@@ -0,0 +1,126 @@
+# DataSelect props
+
+## Overview
+
+`DataSelect` extends the select surface with option-source modes, request handling, custom filtering, and request debounce behavior.
+
+Choose the option source first. Most later decisions depend on that.
+
+## Source modes
+
+### 1. `options`
+
+Use for local option arrays.
+
+### 2. `valueEnum`
+
+Use for lightweight value-to-label maps.
+
+### 3. `request`
+
+Use when options should be loaded asynchronously.
+
+The request signature is:
+
+```ts
+(filterContent?: string, params?: Record<string, any>) =>
+  Promise<DataSelectOptionType[]>;
+```
+
+## Core props
+
+### `options`
+
+Local option source.
+
+Supports flat options and grouped options through nested `options` arrays.
+
+### `valueEnum`
+
+Compact mapping from value to label.
+
+Use this when writing an explicit options array would add little value.
+
+### `request`
+
+Async option loader used when `options` and `valueEnum` are absent.
+
+The component watches both filter content and `params`, then refreshes the remote options.
+
+### `params`
+
+Extra request parameters passed into `request`.
+
+Use this when the option set depends on parent state such as project, tenant, or tab context.
+
+### `filterable`
+
+Accepts:
+
+- `true` for local filtering
+- `'remote'` for remote filtering semantics
+
+`'remote'` skips local option filtering and treats search text as a remote-query concern.
+
+### `filterOption`
+
+Custom local filtering function.
+
+Used only when the component is not in remote filtering mode.
+
+### `disableOption`
+
+Dynamic disable logic.
+
+Signature:
+
+```ts
+(filterContent: string, option: DataSelectOptionType) => boolean;
+```
+
+### `debounceTime` and `debounceWaitTime`
+
+Request debounce controls.
+
+Defaults:
+
+- `debounceTime: 300`
+- `debounceWaitTime: 500`
+
+## Slots
+
+Useful slots:
+
+- `option`
+- `header`
+- `footer`
+- `prefix`
+- `empty`
+- `loading`
+- `tag`
+- `label`
+- default slot receiving `{ options }`
+
+## Instance API
+
+Exposed methods:
+
+- `focus()`
+- `blur()`
+
+## Events
+
+Useful events:
+
+- `update:modelValue`
+- `change`
+- `search`
+- `visible-change`
+- `remove-tag`
+- `popup-scroll`
+
+## Import
+
+```ts
+import { DataSelect } from '@hinen/pro-element-plus';
+```

package/dist/skills/using-data-table/SKILL.md

@@ -0,0 +1,289 @@
+---
+name: using-data-table
+description: Use when building a page-level list that combines filters, table rows, pagination, remote querying, or programmatic search and refresh control in one place.
+---
+
+# Using DataTable
+
+## Overview
+
+Use `DataTable` for **page-level list views** where query controls, table rendering, pagination, loading and error UI, and optional programmatic control should live together.
+
+`DataTable` is not just a table wrapper. It combines:
+
+- query form generation from `columns`
+- table rendering
+- pagination
+- remote querying through `queryFn`
+- imperative control through `useDataTable()`
+
+It supports two valid modes:
+
+1. **Remote mode** — pass `queryFn`
+2. **Static mode** — pass `data`
+
+Choose it when one component should own the full **search → fetch → render → paginate → refresh** flow.
+
+## Use it when
+
+Use `DataTable` when a page needs several of these concerns together:
+
+- filters and table rows belong to the same page-level component
+- columns should define both display behavior and query behavior
+- the page needs pagination, sorting, or refresh
+- parent code needs to set search params or trigger table actions programmatically
+- loading, empty, and error states should follow one standard shell
+
+Strong signals this skill applies:
+
+- admin list pages
+- management consoles
+- searchable resource lists
+- tab pages with controlled list state
+- pages that need toolbar actions tied to table state
+
+## Prefer something else when
+
+- you only need a standalone filter form  
+  → use `../using-query-form/SKILL.md`
+- you are still shaping page structure and interaction model  
+  → use `../building-query-pages/SKILL.md`
+- the same query-and-result surface should live inside an overlay shell instead of a normal page layout  
+  → use `../using-modal/SKILL.md` or `../using-drawer/SKILL.md` for the shell choice, then keep `DataTable` as the inner list shell
+- you only need a very small static table with no search, no paging, and no imperative control
+- the page layout is highly custom and should not be driven by column metadata
+- multi-level nested headers are a primary requirement
+- virtualization or infinite scrolling is more important than standard pagination
+
+## Decision guide
+
+Use `DataTable` if the answer is yes for **two or more** of these:
+
+- Does the page need both filters and a table?
+- Should `columns` also describe query inputs?
+- Does the page need pagination or sorting?
+- Will parent code need refresh, reset, or search-param control?
+- Should loading, empty, and error handling follow a shared pattern?
+
+If not, a simpler table or a standalone form is usually a better fit.
+
+## Start with
+
+1. Decide the mode first:
+   - **Remote mode** → `columns` + `queryFn`
+   - **Static mode** → `columns` + `data`
+2. Keep `columns` as the source of truth for table and query metadata.
+3. Add selection bar, `selection`, sticky layout, and custom slots only after the base flow is correct.
+4. Use `useDataTable()` only when parent code truly needs imperative control.
+
+5. Treat `highlightCurrentRow` intentionally.
+   In `DataTable`, this is not just native Element Plus row highlighting anymore. It enables the built-in single-select mode with a leading radio column.
+
+## Minimal patterns
+
+### Remote mode
+
+Use this when the page should own querying, pagination, sorting, and refresh.
+
+```ts
+import {
+  DataTable,
+  defineDataTableColumns,
+  defineDataTableQueryFn,
+} from '@hinen/pro-element-plus';
+
+const columns = defineDataTableColumns<User>(() => [
+  {
+    label: 'Name',
+    prop: 'name',
+    formItemProps: {
+      placeholder: 'Search name',
+    },
+  },
+  {
+    label: 'Status',
+    prop: 'status',
+    valueType: 'select',
+    valueEnum: {
+      active: { label: 'Active', type: 'success' },
+      disabled: { label: 'Disabled', type: 'info' },
+    },
+  },
+]);
+
+const queryFn = defineDataTableQueryFn(
+  async ({ currentPage = 1, pageSize = 10, ...params }, sort) => {
+    const res = await fetchUsers({ currentPage, pageSize, ...params, sort });
+
+    return {
+      data: res.list,
+      total: res.total,
+      success: res.success,
+    };
+  }
+);
+```
+
+```vue
+<DataTable :columns="columns" :query-fn="queryFn" />
+```
+
+### Static mode
+
+Use this when rows are already available and the page does not need built-in remote querying.
+
+```vue
+<DataTable :columns="columns" :data="rows" :pagination="false" />
+```
+
+In static mode:
+
+- `queryFn` is not needed
+- `refresh()` and `refetch()` are not available
+- query-related helpers are usually unnecessary
+
+## Programmatic control
+
+Use `useDataTable()` when parent code needs imperative control.
+
+Common methods:
+
+- `setSearchParams()`
+- `getSearchParams()`
+- `resetPagination()`
+- `resetAll()`
+- `setCurrentPage()`
+- `setPageSize()`
+- `clearSelection()`
+- `getDataSource()`
+- `refresh()` / `refetch()` in remote mode only
+
+Use this pattern when toolbars, tabs, route sync, or external controls need to coordinate the table.
+
+For current-row control in single-select mode:
+
+- use `setCurrentRow(row)` to select a row programmatically
+- use `setCurrentRow()` to clear the current single-select row
+- use `currentRowKey` together with `rowKey` for controlled current-row sync
+- do not rely on row clicks to change the current row when `highlightCurrentRow` is enabled
+- do not use `clearSelection()` to clear single-select current-row state; that method is for checkbox selection
+
+## Controlled selection mode
+
+`DataTable` supports two selection modes:
+
+1. **Internal mode** — the component owns selection state (default)
+2. **Controlled mode** — parent state owns selection via `v-model:selectedRowKeys`
+
+### Internal mode
+
+Use internal mode when the page does not need to read or manipulate selection from outside the component.
+
+```vue
+<DataTable :columns="columns" :query-fn="queryFn" row-selection />
+```
+
+### Controlled mode
+
+Use controlled mode when parent code needs to:
+
+- read selected row keys reactively
+- set selection from external state
+- sync selection with URL, storage, or other components
+- clear or modify selection programmatically
+
+```vue
+<DataTable
+  v-model:selectedRowKeys="selectedKeys"
+  :columns="columns"
+  :query-fn="queryFn"
+  row-selection
+/>
+```
+
+```ts
+const selectedKeys = ref<DataTableSelectionKeyType[]>([]);
+
+// Read selection
+console.log(selectedKeys.value);
+
+// Set selection
+selectedKeys.value = ['id1', 'id2'];
+
+// Clear selection
+selectedKeys.value = [];
+```
+
+### Key differences
+
+| Aspect            | Internal mode           | Controlled mode                              |
+| ----------------- | ----------------------- | -------------------------------------------- |
+| State owner       | `DataTable` internal    | Parent via `selectedKeys`                    |
+| Prop              | none                    | `v-model:selectedRowKeys`                    |
+| Emit              | `selectionChange`       | `selectionChange` + `update:selectedRowKeys` |
+| Initial selection | none                    | controlled by parent                         |
+| Clear from parent | call `clearSelection()` | set model to `[]`                            |
+
+### Important notes
+
+- `selectedRowKeys` is typed as `DataTableSelectionKeyType[]` (string or number)
+- When `v-model:selectedRowKeys` is provided, the component operates in controlled mode
+- The `selection` prop remains for customization only, never for state control
+- Cross-page selection requires `rowKey` in both modes
+- Instance methods like `getSelectionRows()`, `toggleRowSelection()` still work in controlled mode
+- `clearSelection()` still clears the internal selection, but in controlled mode you should update the parent state instead
+
+## Slots
+
+Use slots when the page needs light customization without replacing the standard shell:
+
+- `toolbar`
+- `selectionBar`
+- `append`
+- `empty`
+- `error`
+
+Prefer slots over rebuilding table scaffolding from scratch.
+
+For checkbox selection review:
+
+- `selection` is the public API for built-in checkbox review item customization
+- `formatter(row)` customizes the built-in review tag text
+- `render(...)` customizes each built-in review item
+- `selectionBar.reviewPopoverProps` customizes the built-in 查看已选 popover (default placement is 'bottom-start')
+- `rowKey` is required if the built-in checkbox review should stay correct across pages
+- the `selectionBar` slot replaces the built-in review UI instead of extending it
+- in cross-page checkbox mode, the `selectionBar` slot receives the aggregated selected rows, so Search/Reset or pagination should not make that slot-level selection disappear
+- `selectionChange` and `getSelectionRows()` still describe the current page only
+- single-select behavior from `highlightCurrentRow` is unchanged
+
+## Common mistakes
+
+- Treating `DataTable` as a dumb table instead of a page-level query shell
+- Returning the wrong shape from `queryFn`
+- Passing `data` and still calling `refresh()` or `refetch()`
+- Forgetting that query form generation depends on `columns`
+- Using `DataTable` for highly custom layouts that are not column-driven
+- Ignoring `enabled` when queries depend on prerequisites
+- Accidentally hiding pagination through `hidePaginationWhenEmpty`
+- Assuming `success` is optional in remote mode
+- Expecting cross-page checkbox review state without `rowKey`
+- Treating `selectionChange` or `getSelectionRows()` as cross-page aggregate APIs
+- Assuming the `selectionBar` slot keeps the built-in review UI
+- Treating `selectionBar.reviewPopoverProps` as item-render customization instead of popover-container customization
+- Treating `highlightCurrentRow` as a visual-only prop in `DataTable`
+- Expecting row clicks to change the current row when built-in single-select mode is active
+- Using `currentRowKey` without `rowKey` and expecting controlled current-row sync to work
+
+## Related skills
+
+- Standalone filter form: `../using-query-form/SKILL.md`
+- Page structure and list-page shaping: `../building-query-pages/SKILL.md`
+- Shared empty and error rendering: `../using-config-provider/SKILL.md`
+- Overlay shells that may host this list surface: `../using-modal/SKILL.md`, `../using-drawer/SKILL.md`
+
+## References
+
+- Props: `./references/props.md`
+- Examples: `./references/examples.md`
+- Gotchas: `./references/gotchas.md`