@hinen/pro-element-plus 1.7.17 → 1.8.0

package/dist/skills/using-form-tree-select/references/props.md

@@ -0,0 +1,86 @@
+# FormTreeSelect props
+
+## Overview
+
+`FormTreeSelect` combines `FormItem` props with Element Plus tree-select props.
+
+Use it when visible tree-node selection should stay inside the shared form-wrapper family.
+
+## Minimum setup
+
+Typical useful props:
+
+- `label`
+- `prop`
+- `data`
+
+Common optional field props:
+
+- `props`
+- `showCheckbox`
+- `multiple`
+- `filterable`
+- `lazy`
+
+## Core props
+
+### Wrapper props from `FormItem`
+
+Includes wrapper-level props such as:
+
+- `label`
+- `prop`
+- `rules`
+- `required`
+- `tooltip`
+
+### `data`
+
+The tree node source.
+
+Use this when the visible tree structure is known up front.
+
+### Tree interaction props
+
+Useful field props include:
+
+- `showCheckbox`
+- `checkStrictly`
+- `multiple`
+- `filterable`
+- `renderContent`
+
+### Mapping and lazy-loading props
+
+Use tree mapping and lazy-loading props when the node shape or loading strategy needs configuration.
+
+## Slots
+
+Useful slots include wrapper-level `label` and `error`, plus tree node customization slots for richer node rendering.
+
+## Instance API
+
+The exposed instance combines:
+
+- `formItem`
+- `field`
+
+## Events
+
+Important events include:
+
+- `update:modelValue`
+- `change`
+- `focus`
+- `blur`
+- `clear`
+- `visibleChange`
+- `removeTag`
+- `popupScroll`
+- tree node interaction events such as `nodeClick`, `checkChange`, `check`, `nodeExpand`, and `nodeCollapse`
+
+## Import
+
+```ts
+import { FormTreeSelect } from '@hinen/pro-element-plus';
+```

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

@@ -0,0 +1,88 @@
+---
+name: using-image
+description: Use when you need richer image loading, preview, placeholder, and failure handling than a bare image tag provides.
+---
+
+# Using Image
+
+## Overview
+
+Use `Image` for a **stateful image primitive** that keeps Element Plus image behavior while adding preview defaults, a built-in reload affordance after failure, and empty-state handling when no source is present.
+
+It is strongest when image loading, preview, failure recovery, or placeholder behavior are part of the product flow rather than afterthoughts.
+
+## Use it when
+
+Use `Image` when several of these are true:
+
+- images need preview behavior
+- failure and reload states matter to the workflow
+- loading, preview, or error UI needs slot-level customization
+- empty-state behavior matters when `src` may be missing
+- the default reload control and preview affordances are useful
+
+Strong signals this skill applies:
+
+- thumbnail galleries
+- avatar or cover-image cards
+- image-heavy detail views
+- media lists with recoverable load failures
+
+## Prefer something else when
+
+- you only need text truncation around media metadata  
+  → use `../using-ellipsis-text/SKILL.md`
+- a plain browser image tag is sufficient and preview or retry behavior does not matter
+
+## Decision guide
+
+Use `Image` if the answer is yes for **two or more** of these:
+
+- Should the image support preview or gallery viewing?
+- Should failed loads offer an in-place reload action?
+- Do placeholder, error, or empty states need customization?
+- Is missing or unstable image data part of normal usage?
+
+If not, a plain image element may be enough.
+
+## Start with
+
+1. Decide whether preview is part of the workflow.
+2. Decide whether the default error text and reload control are enough.
+3. Set `src` and optional `previewSrcList` first.
+4. Add slots only when the default states do not fit the product requirement.
+
+## Minimal patterns
+
+### Thumbnail with preview
+
+```vue
+<Image :src="src" :preview="true" />
+```
+
+### Failed image with reload
+
+Use the built-in reload affordance when users should be able to retry a failed asset without reloading the page.
+
+### Empty image placeholder
+
+Use the empty state when `src` may be missing and the layout should still reserve image space cleanly.
+
+## Common mistakes
+
+- turning off the built-in reload control and then expecting users to recover from load failures in place
+- overlooking that preview is enabled by default here
+- treating empty `src` and failed `src` as the same state
+- adding custom slots before confirming whether the built-in image states already fit
+
+When reading package-facing docs, prefer the documented behavior over memorizing one term: this component's public story is about a reload control after failure, even if different docs use slightly different labels for that control.
+
+## Related skills
+
+- Truncating related long text content: `../using-ellipsis-text/SKILL.md`
+
+## References
+
+- Props: `./references/props.md`
+- Examples: `./references/examples.md`
+- Gotchas: `./references/gotchas.md`

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

@@ -0,0 +1,31 @@
+# Image examples
+
+## 1. Thumbnail with preview
+
+Use `preview` and `previewSrcList` when the same image should expand into a viewer or gallery flow.
+
+Typical fit:
+
+- product galleries
+- avatar preview
+- image-heavy detail pages
+
+## 2. Retryable image load
+
+Keep `showRefresh` enabled when users should be able to retry a failed asset without reloading the page.
+
+Typical fit:
+
+- unstable remote assets
+- user-uploaded content
+- CDN-backed thumbnails
+
+## 3. Custom failure or empty state
+
+Use the `error`, `refreshButton`, `placeholder`, or `empty` slots when the fallback UI needs product-specific language or styling.
+
+Typical fit:
+
+- branded empty states
+- custom retry buttons
+- loading placeholders matched to layout skeletons

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

@@ -0,0 +1,13 @@
+# Image gotchas
+
+- `preview` defaults to `true` here  
+  If preview should be disabled, set it explicitly.
+
+- `previewTeleported` defaults to `true`  
+  This affects where the preview viewer renders.
+
+- Setting `showRefresh` to `false` removes the retry affordance  
+  After a failed load, users will have no built-in recovery action.
+
+- Empty `src` and failed `src` are different states  
+  Missing source shows the empty-state path; failed source shows the error-state path.

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

@@ -0,0 +1,91 @@
+# Image props
+
+## Overview
+
+`Image` extends Element Plus image behavior with retry, preview defaults, and explicit empty-state handling.
+
+Use it when loading-state behavior is part of the component choice, not just the image URL itself.
+
+## Minimum setup
+
+Typical useful props:
+
+- `src`
+
+Common optional props:
+
+- `preview`
+- `previewSrcList`
+- `showRefresh`
+- `showError`
+- `errorText`
+
+## Core props
+
+### `src`
+
+The image source URL.
+
+If `src` is empty, the component renders its empty state instead of trying to load an image.
+
+### `preview`
+
+Toggles preview behavior.
+
+Default: `true`
+
+### `previewSrcList`
+
+Preview gallery source list.
+
+If preview is enabled and no list is provided, the component falls back to the current computed source.
+
+### `showRefresh`
+
+Shows a reload action after failure.
+
+Default: `true`
+
+### `showError`
+
+Controls whether the error text is shown.
+
+Default: `true`
+
+### `errorText`
+
+Overrides the default localized error text.
+
+### `previewTeleported`
+
+Controls preview viewer teleport behavior.
+
+Default: `true`
+
+## Slots
+
+Useful slots include:
+
+- `error`
+- `refreshButton`
+- `placeholder`
+- `empty`
+- `viewer`
+- `progress`
+- `toolbar`
+
+## Events
+
+Important events include:
+
+- `load`
+- `error`
+- `switch`
+- `close`
+- `show`
+
+## Import
+
+```ts
+import { Image } from '@hinen/pro-element-plus';
+```

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

@@ -0,0 +1,113 @@
+---
+name: using-modal
+description: Use when a centered overlay should keep Element Plus dialog behavior while adding standard confirm and cancel actions, confirm loading state, and size presets.
+---
+
+# Using Modal
+
+## Overview
+
+Use `Modal` for a **centered dialog workflow** that should keep Element Plus dialog behavior while adding a standard footer, size presets, confirm loading state, and scroll-shadow treatment for long content.
+
+It is best for short, focused overlay flows where confirm and cancel are first-class actions. It is not just a visual wrapper around `ElDialog`; it adds a stronger default action model.
+
+## Use it when
+
+Use `Modal` when several of these are true:
+
+- the interaction fits a centered dialog
+- the flow should expose standard confirm and cancel buttons
+- async submit state should appear on the confirm button
+- size presets are preferable to ad hoc widths
+- the content may overflow and still needs a stable shell
+
+Strong signals this skill applies:
+
+- confirmation dialogs with meaningful body content
+- small record editors
+- detail review dialogs
+- one-step approval or submit flows
+
+## Prefer something else when
+
+- the workflow needs a side panel or should stay anchored to the viewport edge  
+  → use `../using-drawer/SKILL.md`
+- you are still choosing the right overlay pattern  
+  → use `../building-modal-workflows/SKILL.md`
+- the interaction is so small that plain Element Plus dialog usage is clearer than the added footer semantics
+- the feature needs highly custom actions with no confirm/cancel model
+
+## Decision guide
+
+Use `Modal` if the answer is yes for **two or more** of these:
+
+- Should the overlay be centered rather than edge-attached?
+- Do confirm and cancel represent the core business actions?
+- Should submit loading live on the confirm button?
+- Will a `small`, `default`, or `large` preset be enough for sizing?
+- Should the feature keep standard dialog lifecycle events while gaining a stronger footer contract?
+
+If not, `Drawer` or a lower-level dialog composition may fit better.
+
+## Start with
+
+1. Control visibility through `modelValue`.
+2. Use the built-in footer for standard confirm and cancel flows.
+3. Choose `size` before reaching for explicit `width`.
+4. Keep close behavior in business code by handling `cancel`, `ok`, and `update:modelValue` explicitly.
+
+## Minimal patterns
+
+### Standard confirm and cancel flow
+
+```vue
+<Modal
+  :model-value="visible"
+  title="Edit User"
+  :confirm-loading="saving"
+  @update:model-value="visible = $event"
+  @cancel="visible = false"
+  @ok="handleSubmit"
+>
+  <UserForm />
+</Modal>
+```
+
+### Hide the default footer
+
+Use this when the content manages its own actions.
+
+```vue
+<Modal
+  :model-value="visible"
+  :footer="false"
+  @update:model-value="visible = $event"
+>
+  <CustomWorkflow />
+</Modal>
+```
+
+### Custom footer slot
+
+Use the slot only when the default two-button action model is not enough.
+
+## Common mistakes
+
+- assuming `ok` or `cancel` automatically closes the modal
+- using exact `width` immediately instead of trying `size` first
+- forgetting that `okButtonProps.type` can override `okType`
+- rebuilding footer actions from scratch for a standard submit flow
+- using `Modal` for long, panel-like workflows that should really be drawers
+
+## Related skills
+
+- Side-panel workflow shell: `../using-drawer/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-modal/references/examples.md

@@ -0,0 +1,122 @@
+# Modal examples
+
+## 1. Standard confirm dialog
+
+Use `Modal` when the main job is confirming or cancelling a short workflow with meaningful body content.
+
+Minimal pattern:
+
+```vue
+<Modal
+  :model-value="visible"
+  title="Confirm"
+  @cancel="visible = false"
+  @ok="handleConfirm"
+/>
+```
+
+Typical fit:
+
+- delete confirmations with extra context
+- approval dialogs
+- one-step submit flows
+
+Recommended pattern:
+
+- keep the default footer
+- wire `cancel` and `ok` in parent code
+- use `confirmLoading` for async work
+
+## 2. Small record editor
+
+Use `Modal` when a compact editor should stay centered and focused.
+
+Minimal pattern:
+
+```vue
+<Modal
+  :model-value="visible"
+  title="Rename"
+  @cancel="visible = false"
+  @ok="handleSave"
+>
+  <RenameForm />
+</Modal>
+```
+
+Typical fit:
+
+- rename dialogs
+- status-change dialogs
+- lightweight metadata editors
+
+Recommended pattern:
+
+- start with `size="small"` or `size="default"`
+- keep the form inside the body slot
+- close on successful submit, not on button click alone
+
+## 3. Overflowing long-form content
+
+Use `Modal` when the body may scroll but the shell should stay stable.
+
+Minimal pattern:
+
+```vue
+<Modal
+  :model-value="visible"
+  title="Review Terms"
+  @cancel="visible = false"
+  @ok="handleAccept"
+>
+  <LongContent />
+</Modal>
+```
+
+Typical fit:
+
+- policy review dialogs
+- long explanations with a final confirm action
+- large read-only detail content that still behaves like a dialog
+
+The component already handles scrollable body rendering and header or footer shadow transitions.
+
+## 4. Custom action layout
+
+Use the `footer` slot when the default two-button pattern cannot express the workflow.
+
+Minimal pattern:
+
+```vue
+<Modal :model-value="visible">
+  <template #footer>
+    <CustomActions />
+  </template>
+</Modal>
+```
+
+Typical fit:
+
+- three-way decision flows
+- secondary destructive action next to save
+- multi-step footer controls
+
+Prefer the built-in footer until the product flow genuinely needs more than confirm and cancel.
+
+## 5. Modal with query or list content
+
+Use `Modal` when the overlay stays centered, but the inner body is really a query/list workflow rather than a simple editor.
+
+Minimal pattern:
+
+```vue
+<Modal :model-value="visible" title="Choose User" @cancel="visible = false">
+  <QueryForm :items="items" @search="handleSearch" />
+</Modal>
+```
+
+Typical fit:
+
+- centered search-and-pick dialogs
+- short review-history overlays
+- quick filter panels that should not become full drawers

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

@@ -0,0 +1,16 @@
+# Modal gotchas
+
+- `size` is a library-level preset  
+  It is not part of Element Plus dialog props, so treat it as the preferred convenience layer here.
+
+- `width` and `size` are not the same decision  
+  Reach for `width` only when the presets do not match product intent.
+
+- `ok` and `cancel` do not close the modal automatically  
+  Parent code still needs to update `modelValue` or handle the dialog lifecycle explicitly.
+
+- `okButtonProps` can override `okType`  
+  If the confirm button style looks wrong, check both values.
+
+- Hiding the footer removes the built-in action model  
+  Once `footer` is `false` or the slot replaces it, your own content must provide the workflow affordances.

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

@@ -0,0 +1,100 @@
+# Modal props
+
+## Overview
+
+`Modal` extends Element Plus dialog props and adds a standard footer contract, size presets, and button-level loading state.
+
+Choose the action model first, then choose sizing.
+
+## Minimum setup
+
+Required in normal usage:
+
+- `modelValue`
+
+Typical optional props:
+
+- `title`
+- `size`
+- `footer`
+- `confirmLoading`
+
+## Core props
+
+### `modelValue`
+
+Controls visibility.
+
+Use `update:modelValue` to keep parent state in sync.
+
+### `size`
+
+Library-level preset sizing.
+
+Supported values:
+
+- `small`
+- `default`
+- `large`
+
+Default: `default`
+
+If `width` is provided, use that intentionally instead of relying on the preset alone.
+
+### `width`
+
+Inherited from Element Plus dialog props.
+
+Use this only when the preset sizes are not sufficient.
+
+### `footer`
+
+Controls whether the default footer is rendered.
+
+Default: `true`
+
+### `confirmLoading`
+
+Shows loading on the built-in confirm button.
+
+Default: `false`
+
+### `okText` and `cancelText`
+
+Override the localized button labels.
+
+### `okType`
+
+Sets the built-in confirm button type.
+
+Default: `primary`
+
+### `okButtonProps` and `cancelButtonProps`
+
+Pass partial Element Plus button props into the built-in footer actions.
+
+Use these for fine-grained button overrides without replacing the whole footer.
+
+## Events
+
+`Modal` keeps Element Plus dialog events and adds:
+
+- `ok`
+- `cancel`
+
+These are business-action events. They do not automatically close the modal.
+
+## Slots
+
+Useful slots:
+
+- default body slot
+- `footer`
+
+All other dialog slots still pass through.
+
+## Import
+
+```ts
+import { Modal } from '@hinen/pro-element-plus';
+```