@hinen/pro-element-plus 1.7.16 → 1.8.0

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

@@ -0,0 +1,375 @@
+# DataTable props
+
+## Overview
+
+`DataTable` supports two primary modes:
+
+1. **Remote mode** — pass `queryFn`
+2. **Static mode** — pass `data`
+
+Start by choosing the mode. Do not assume every `DataTable` should fetch remotely.
+
+## Minimum setup
+
+### Remote mode
+
+Use this when the component should own querying, pagination, sorting, and refresh.
+
+Required:
+
+- `columns`
+- `queryFn`
+
+`queryFn` must return:
+
+```ts
+{
+  data: RecordType[],
+  total: number,
+  success: boolean,
+}
+```
+
+### Static mode
+
+Use this when rows already exist in memory.
+
+Required:
+
+- `columns`
+- `data`
+
+Typical optional prop:
+
+- `pagination: false`
+
+## Mode-specific behavior
+
+| Prop / API                        | Remote mode                           | Static mode         |
+| --------------------------------- | ------------------------------------- | ------------------- |
+| `queryFn`                         | used                                  | not needed          |
+| `data`                            | optional override only if intentional | primary data source |
+| `refresh()`                       | supported                             | not supported       |
+| `refetch()`                       | supported                             | not supported       |
+| `enabled`                         | meaningful                            | usually irrelevant  |
+| `queryKey`                        | meaningful                            | usually irrelevant  |
+| `initialData` / `placeholderData` | meaningful                            | not needed          |
+
+If `data` is passed, do not design parent code around remote query APIs.
+
+## Core props
+
+### `columns`
+
+The main source of truth.
+
+`columns` controls:
+
+- rendered table columns
+- generated query form items
+- query field ordering
+- value enum mapping
+- custom cell rendering
+- visibility in table and form
+
+Common fields:
+
+- `prop`
+- `label`
+- `hideInForm`
+- `hideInTable`
+- `valueType`
+- `valueEnum`
+- `formItemProps`
+- `formItemOrder`
+- `renderCell`
+- `renderHeaderCell`
+- `renderFilterIcon`
+- `ellipsis`
+
+### `queryFn`
+
+Async loader for remote mode.
+
+It receives:
+
+- current search params
+- `currentPage`
+- `pageSize`
+- sort info
+
+It must return:
+
+```ts
+{
+  data,
+  total,
+  success,
+}
+```
+
+Use this when `DataTable` should own fetching.
+
+### `data`
+
+Static row array.
+
+Use this when:
+
+- rows are already available
+- built-in remote querying is unnecessary
+- the page still benefits from the standard table shell
+
+### `pagination`
+
+Controls pager rendering.
+
+- pass `false` to disable
+- pass an object to customize pagination props
+- omit it to use built-in defaults
+
+Check `hidePaginationWhenEmpty` before assuming the pager will always render.
+
+### `form`
+
+Query form configuration.
+
+Use this for:
+
+- `initialValues`
+- label and layout behavior
+- other QueryForm-level config
+
+The query form only appears if `columns` can generate at least one form item.
+
+### `enabled`
+
+Boolean or function for gating remote queries.
+
+Use this when querying should wait for prerequisites such as:
+
+- route params
+- async dictionaries
+- parent state
+- active tab state
+
+### `selectionBar`
+
+Controls selected-row affordance.
+
+- `true` enables the default selected-row bar
+- `false` disables it
+- object form customizes bar props
+- slot form replaces the built-in review UI
+
+The built-in checkbox review keeps cross-page state internally only when `rowKey` is provided.
+
+- `selectionChange` remains current-page oriented
+- `getSelectionRows()` remains current-page oriented
+- `reviewPopoverProps` customizes the built-in 查看已选 popover
+- use the `selectionBar` slot only when the page should replace the built-in review UI entirely
+
+### `selectedRowKeys` / `v-model:selectedRowKeys`
+
+Controls selection state from parent (controlled mode).
+
+Type: `DataTableSelectionKeyType[]` (string or number)
+
+Use this when:
+
+- parent needs reactive access to selected row keys
+- selection should sync with external state (URL, storage, other components)
+- programmatic selection control is required
+
+When provided, `DataTable` operates in controlled mode:
+
+- the component emits `update:selectedRowKeys` on selection changes
+- parent state becomes the source of truth
+- internal selection state defers to the prop
+
+Cross-page selection works with `selectedRowKeys` when `rowKey` is defined. The prop accepts keys from any page, not just the current one.
+
+```vue
+<DataTable
+  v-model:selectedRowKeys="selectedKeys"
+  :columns="columns"
+  :query-fn="queryFn"
+  row-key="id"
+  row-selection
+/>
+```
+
+```ts
+const selectedKeys = ref<DataTableSelectionKeyType[]>([]);
+
+// Set programmatically
+selectedKeys.value = ['id1', 'id2'];
+
+// Clear
+selectedKeys.value = [];
+```
+
+### `selection`
+
+Customizes built-in cross-page checkbox review items. For state control, use `v-model:selectedRowKeys` instead.
+
+Use this prop only for customization, never for state management.
+
+Common fields:
+
+- `formatter(row)` customizes the default review tag text
+- `render(...)` customizes each built-in review item
+
+Use `rowKey` with this when checkbox review should stay correct across pages.
+
+### `fixedHeader` / `fixedHeaderOffset`
+
+Use when the header should stay visible while the user scrolls.
+
+### `fixedFooter` / `fixedFooterOffset`
+
+Use when pagination should stay accessible near the viewport bottom.
+
+### `hidePaginationWhenEmpty`
+
+Use intentionally.
+
+If `true`, empty results can hide pagination completely.
+
+### `loading`
+
+External loading flag.
+
+Use this when the page has prerequisite loading that is separate from the table's own remote query loading.
+
+### `highlightCurrentRow`
+
+In `DataTable`, this prop now does more than turn on native Element Plus highlighting.
+
+When `highlightCurrentRow` is `true`, `DataTable` enters its built-in single-select mode:
+
+- a leading radio column is rendered
+- the current row stays visually highlighted
+- radio click becomes the selection trigger
+- row click still emits `rowClick`, but does not change the current row
+
+Use this only when the page intentionally wants radio-driven single selection.
+
+### `rowKey`
+
+`rowKey` becomes especially important when single-select mode is controlled.
+
+Use `rowKey` when:
+
+- using built-in cross-page checkbox review through `selection`
+- passing `currentRowKey`
+- expecting current-row state to survive data replacement
+- needing stable single-select identity beyond row index
+
+Without `rowKey`, built-in checkbox review cannot aggregate rows across pages correctly.
+
+### `currentRowKey`
+
+Use `currentRowKey` together with `rowKey` for controlled current-row sync in single-select mode.
+
+Notes:
+
+- it is meaningful only when `rowKey` is provided
+- setting it to a matching key selects and highlights that row
+- setting it to `undefined` clears the current single-select row in `DataTable`
+- setting it to a defined but unmatched key also clears the current single-select row
+- this empty-key clearing behavior is a `DataTable` wrapper convention, not a documented Element Plus `current-row-key` contract
+
+## Exported helpers
+
+These are exported with `DataTable`:
+
+- `defineDataTableColumns`
+- `defineDataTableEnabled`
+- `defineDataTableInitialData`
+- `defineDataTablePlaceholderData`
+- `defineDataTableQueryFn`
+- `defineDataTableQueryKey`
+- `useDataTable`
+
+Use them when stronger typing or reusable table configuration improves clarity.
+
+## Instance API
+
+Use `useDataTable()` when parent code needs imperative control.
+
+Common methods:
+
+- `setSearchParams()`
+- `getSearchParams()`
+- `getFormData()`
+- `setFormData()`
+- `resetForm()`
+- `resetPagination()`
+- `resetAll()`
+- `setCurrentPage()`
+- `setPageSize()`
+- `getDataSource()`
+- `clearSelection()`
+- `refresh()`
+- `refetch()`
+
+Current-row related methods:
+
+- `setCurrentRow(row)` selects the current row in single-select mode
+- `setCurrentRow()` clears the current single-select row
+- `clearSelection()` clears checkbox selection, not single-select current-row state
+
+Selection notes:
+
+- `getSelectionRows()` returns current-page checkbox rows
+- cross-page checkbox review state is internal, not exposed through a new instance method
+
+Notes:
+
+- `refresh()` and `refetch()` are for remote mode only
+- form methods assume a generated query form actually exists
+
+## Events
+
+`DataTable` re-emits table events and adds query-related events.
+
+Useful additions:
+
+- `formDataChange`
+- `searchParamsChange`
+
+Use them when parent code should observe search-state changes without replacing the component shell.
+
+## Slots
+
+Available extension points:
+
+- `toolbar`
+- `selectionBar`
+- `append`
+- `empty`
+- `error`
+
+Use these before building a custom shell around `ElTable`.
+
+`selectionBar` slot notes:
+
+- it replaces the built-in review UI
+- in cross-page checkbox mode, its `selection` slot prop is the aggregated selected rows
+- `clear` still clears the full checkbox selection state
+
+## Import
+
+```ts
+import {
+  DataTable,
+  defineDataTableColumns,
+  defineDataTableEnabled,
+  defineDataTableInitialData,
+  defineDataTablePlaceholderData,
+  defineDataTableQueryFn,
+  defineDataTableQueryKey,
+  useDataTable,
+} from '@hinen/pro-element-plus';
+```

package/dist/skills/using-drawer/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: using-drawer
+description: Use when an edge-attached overlay should keep Element Plus drawer behavior while adding standard confirm and cancel actions, confirm loading state, and size presets.
+---
+
+# Using Drawer
+
+## Overview
+
+Use `Drawer` for a **side-panel workflow** that should preserve Element Plus drawer behavior while adding standard confirm and cancel actions, size presets, scroll-shadow treatment, and an opinionated footer model.
+
+It fits workflows that need more room or should stay visually connected to the current page. Like `Modal`, it is more than a thin shell because it bakes in action semantics and sizing conventions.
+
+## Use it when
+
+Use `Drawer` when several of these are true:
+
+- the interaction needs more horizontal or vertical space than a centered dialog
+- the workflow should feel attached to the current page rather than interrupt it completely
+- confirm and cancel are still the main actions
+- built-in footer behavior is preferable to custom action scaffolding
+- direction and edge attachment matter to the UX
+
+Strong signals this skill applies:
+
+- side-panel editors
+- review and approve panels
+- nested overlay workflows
+- detail panels with richer body content
+
+## Prefer something else when
+
+- the interaction is short, centered, and dialog-like  
+  → use `../using-modal/SKILL.md`
+- you are still choosing the right overlay shell  
+  → use `../building-modal-workflows/SKILL.md`
+- the flow has no meaningful confirm/cancel model
+- the feature should not consume edge-attached page space
+
+## Decision guide
+
+Use `Drawer` if the answer is yes for **two or more** of these:
+
+- Should the panel attach to an edge instead of appearing centered?
+- Does the content need more room than a modal usually gets?
+- Should the workflow keep standard confirm and cancel actions?
+- Do direction and opening side matter to the experience?
+- Would a standard footer save custom shell work?
+
+If not, `Modal` or a lower-level drawer composition may be a better fit.
+
+## Start with
+
+1. Control visibility through `modelValue`.
+2. Use the default footer unless the action layout is truly custom.
+3. Prefer `size` presets before hard-coding `width`.
+4. Treat `ok` and `cancel` as business events that still need close logic.
+
+## Minimal patterns
+
+### Standard side-panel workflow
+
+```vue
+<Drawer
+  :model-value="visible"
+  title="Edit Project"
+  :confirm-loading="saving"
+  @update:model-value="visible = $event"
+  @cancel="visible = false"
+  @ok="handleSubmit"
+>
+  <ProjectForm />
+</Drawer>
+```
+
+### Custom header or footer
+
+Use header and footer slots only when the built-in structure is not sufficient.
+
+### Direction-aware drawer
+
+Use `direction` intentionally when the overlay should come from the left, right, top, or bottom.
+
+## Common mistakes
+
+- choosing `Drawer` just because the content is large, even when a centered modal would still communicate better
+- assuming `ok` or `cancel` closes the drawer automatically
+- overriding the footer too early for a standard submit flow
+- forgetting that `appendToBody` defaults to `true`
+- assuming `size` and `width` are interchangeable
+- ignoring `withHeader` when the design intentionally removes the header area
+
+## Related skills
+
+- Centered dialog workflow shell: `../using-modal/SKILL.md`
+- Overlay-pattern selection: `../building-modal-workflows/SKILL.md`
+- Form workflow when the body is an editor or wrapped form: `../building-form-workflows/SKILL.md`
+- Query or list shells when the body is filter-plus-results content: `../using-query-form/SKILL.md`, `../using-data-table/SKILL.md`
+
+## References
+
+- Props: `./references/props.md`
+- Examples: `./references/examples.md`
+- Gotchas: `./references/gotchas.md`

package/dist/skills/using-drawer/references/examples.md

@@ -0,0 +1,109 @@
+# Drawer examples
+
+## 1. Side-panel editor
+
+Use `Drawer` when the content needs more room than a centered modal but should still behave like one workflow.
+
+Minimal pattern:
+
+```vue
+<Drawer
+  :model-value="visible"
+  title="Edit Project"
+  @cancel="visible = false"
+  @ok="handleSave"
+>
+  <ProjectForm />
+</Drawer>
+```
+
+Typical fit:
+
+- project editors
+- user-detail edit panels
+- multi-section settings panels
+
+Recommended pattern:
+
+- keep the form in the body slot
+- use the built-in footer first
+- close only after the parent updates `modelValue`
+
+## 2. Review and approve panel
+
+Use `Drawer` when users should keep page context while reviewing detail content and deciding whether to confirm or cancel.
+
+Minimal pattern:
+
+```vue
+<Drawer
+  :model-value="visible"
+  title="Review"
+  @cancel="visible = false"
+  @ok="handleApprove"
+>
+  <ReviewPanel />
+</Drawer>
+```
+
+Typical fit:
+
+- audit review panels
+- approval sidebars
+- edge-attached detail inspection
+
+The default footer is a strong fit here because the workflow is still basically confirm or cancel.
+
+## 3. Nested drawer flow
+
+Use `Drawer` when a larger parent panel may open a secondary panel.
+
+Minimal pattern:
+
+```vue
+<Drawer :model-value="visible" title="Parent Panel">
+  <NestedTask />
+</Drawer>
+```
+
+Typical fit:
+
+- choosing related entities from inside an editor
+- step-in detail inspection
+- nested configuration tasks
+
+Account for `appendToBody` and visibility state intentionally in these flows.
+
+## 4. Direction-specific layouts
+
+Use `direction` when the drawer’s opening edge communicates meaning or fits the page layout better.
+
+Minimal pattern:
+
+```vue
+<Drawer :model-value="visible" direction="rtl" title="Details" />
+```
+
+Typical fit:
+
+- right-side detail drawers
+- left-side navigation-adjacent panels
+- top or bottom temporary panels for shorter content
+
+## 5. Drawer with query or list content
+
+Use `Drawer` when the overlay body is really a query/list workflow and the user benefits from more room or stronger page context.
+
+Minimal pattern:
+
+```vue
+<Drawer :model-value="visible" title="Select Project" @cancel="visible = false">
+  <DataTable :columns="columns" :query-fn="queryFn" />
+</Drawer>
+```
+
+Typical fit:
+
+- select-from-list drawers
+- side-panel result review
+- wider filter-plus-results overlays

package/dist/skills/using-drawer/references/gotchas.md

@@ -0,0 +1,16 @@
+# Drawer gotchas
+
+- `appendToBody` defaults to `true`  
+  This changes layering and portal behavior compared with assuming Element Plus defaults unchanged.
+
+- `ok` and `cancel` do not close the drawer automatically  
+  They are workflow events, not implicit visibility updates.
+
+- `okButtonProps.type` takes precedence over `okType`  
+  If the confirm button style is surprising, check both settings.
+
+- `size` behaves differently by direction  
+  Left and right drawers use width-oriented sizing. Top and bottom drawers use height-oriented sizing.
+
+- Removing the header changes the scroll-shadow experience  
+  If `withHeader` is `false`, do not assume the overlay still behaves like the standard headered shell.

package/dist/skills/using-drawer/references/props.md

@@ -0,0 +1,105 @@
+# Drawer props
+
+## Overview
+
+`Drawer` extends Element Plus drawer props and adds a standard footer action model, size presets, confirm loading state, and a default `appendToBody: true` behavior.
+
+Choose the edge-attached workflow first, then decide whether the default footer is enough.
+
+## Minimum setup
+
+Required in normal usage:
+
+- `modelValue`
+
+Typical optional props:
+
+- `title`
+- `direction`
+- `size`
+- `width`
+- `footer`
+- `confirmLoading`
+
+## Core props
+
+### `modelValue`
+
+Controls drawer visibility.
+
+### `direction`
+
+Inherited from Element Plus drawer props.
+
+Use it to choose where the drawer enters from.
+
+### `size`
+
+Library-level preset sizing.
+
+Supported values:
+
+- `small`
+- `default`
+- `large`
+
+Default: `default`
+
+The preset affects max width for left or right drawers and max height for top or bottom drawers.
+
+### `width`
+
+Explicit drawer size override.
+
+If present, it becomes the main sizing input instead of relying on presets alone.
+
+### `footer`
+
+Controls whether the built-in footer is rendered.
+
+Default: `true`
+
+### `confirmLoading`
+
+Shows loading on the built-in confirm button.
+
+Default: `false`
+
+### `okText`, `cancelText`, `okType`, `okButtonProps`, `cancelButtonProps`
+
+Customize the built-in action buttons without replacing the whole footer.
+
+### `appendToBody`
+
+Overridden default: `true`
+
+This differs from treating it as just another inherited Element Plus prop, so account for it explicitly in nested or portal-heavy layouts.
+
+### `withHeader`
+
+Inherited from Element Plus drawer props.
+
+Use this when the header should be hidden entirely.
+
+## Events
+
+`Drawer` keeps Element Plus drawer events and adds:
+
+- `ok`
+- `cancel`
+
+These are business-action events and do not close the drawer on their own.
+
+## Slots
+
+Useful slots:
+
+- default body slot
+- `header`
+- `footer`
+
+## Import
+
+```ts
+import { Drawer } from '@hinen/pro-element-plus';
+```