@hinen/pro-element-plus 1.7.17 → 1.8.0

package/dist/skills/using-ellipsis-text/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: using-ellipsis-text
+description: Use when long content must be truncated cleanly while still exposing the full value through the built-in tooltip behavior.
+---
+
+# Using EllipsisText
+
+## Overview
+
+Use `EllipsisText` for a **truncation-plus-tooltip primitive** that detects overflow and only exposes a tooltip when the content is actually clipped.
+
+It is strongest when the UI regularly constrains text width or line count and users still need a reliable way to access the full value without custom overflow logic. By default it already gives you single-line truncation, and it keeps the overflow state in sync when content or container size changes.
+
+## Use it when
+
+Use `EllipsisText` when several of these are true:
+
+- text regularly overflows constrained layouts
+- one-line or multi-line truncation is part of the design
+- a tooltip should reveal the full value
+- the wrapper element should stay configurable
+- you want overflow detection to react to resize or content changes
+
+Strong signals this skill applies:
+
+- table cells
+- card metadata rows
+- dense admin layouts
+- mixed inline text with variable length
+
+## Prefer something else when
+
+- the main problem is image loading or preview rather than text overflow  
+  → use `../using-image/SKILL.md`
+- plain CSS truncation is sufficient and tooltip access to the full value does not matter
+
+## Decision guide
+
+Use `EllipsisText` if the answer is yes for **two or more** of these:
+
+- Will the content often overflow its container?
+- Should the full value be accessible through a built-in tooltip?
+- Do you need single-line or multi-line truncation without writing custom overflow observers?
+- Should the component react correctly when content or layout size changes?
+
+If not, plain text or simple CSS truncation may be enough.
+
+## Start with
+
+1. Start with the default single-line mode; you do not need to pass `truncated` unless you want to be explicit.
+2. Make sure the rendered element actually has a constrained width or line count, otherwise no overflow will happen.
+3. Set the wrapper `tag` if inline versus block semantics matter.
+4. Switch to `lineClamp` only when the design intentionally allows multiple visible lines.
+5. Override tooltip props only when the default reveal behavior is not enough.
+
+## Minimal patterns
+
+### Standard single-line truncation
+
+```vue
+<EllipsisText class="w-300px">{{ text }}</EllipsisText>
+```
+
+This is the smallest correct setup when one line is enough. `truncated` already defaults to `true`.
+
+### Multi-line clamp
+
+Use `lineClamp` when the design should allow a fixed number of visible lines instead of a single-line ellipsis.
+
+```vue
+<EllipsisText tag="div" class="w-300px" :line-clamp="3">
+  {{ text }}
+</EllipsisText>
+```
+
+When `lineClamp` is a positive number, it becomes the active truncation mode and takes precedence over the default single-line behavior.
+
+### Custom tooltip content
+
+Use `tooltip` when the revealed content should differ from the raw rendered text.
+
+```vue
+<EllipsisText class="w-300px" tooltip="Normalized full value">
+  {{ shortLabel }}
+</EllipsisText>
+```
+
+## Common mistakes
+
+- assuming `lineClamp` and single-line truncation are the same strategy or combine visually
+- using the component when tooltip access to the full value is unnecessary
+- forgetting that overflow only happens when the surrounding layout actually constrains the text
+- expecting the tooltip to open even when `disabled` is set or the text is fully visible
+- forgetting that the displayed tag can change layout semantics
+- styling the container in a way that prevents the truncation mode from making sense
+
+## Related skills
+
+- Media primitive with different loading and error concerns: `../using-image/SKILL.md`
+
+## References
+
+- Props: `./references/props.md`
+- Examples: `./references/examples.md`
+- Gotchas: `./references/gotchas.md`

package/dist/skills/using-ellipsis-text/references/examples.md

@@ -0,0 +1,71 @@
+# EllipsisText examples
+
+## 1. Standard single-line truncation
+
+Use `EllipsisText` when dense layouts need one-line truncation with access to the full value on hover or trigger.
+
+Minimal pattern:
+
+```vue
+<EllipsisText class="w-300px">{{ row.name }}</EllipsisText>
+```
+
+Why this is enough:
+
+- single-line truncation is already on by default
+- the tooltip uses the rendered text by default
+- only the width constraint has to come from your layout
+
+Typical fit:
+
+- table cells
+- inline metadata
+- list rows with narrow columns
+
+## 2. Multi-line clamp
+
+Use `lineClamp` when the design allows a fixed number of visible lines before truncation.
+
+Minimal pattern:
+
+```vue
+<EllipsisText tag="div" class="w-300px" :line-clamp="3">
+  {{ description }}
+</EllipsisText>
+```
+
+Use a block-like tag when the surrounding layout should behave like a block container.
+
+Typical fit:
+
+- card descriptions
+- feed previews
+- constrained summary blocks
+
+## 3. Custom tooltip content
+
+Use `tooltip` when the revealed content should differ from the raw rendered text.
+
+Minimal pattern:
+
+```vue
+<EllipsisText class="w-300px" :tooltip="fullLabel">
+  {{ shortLabel }}
+</EllipsisText>
+```
+
+Typical fit:
+
+- normalized full values
+- translated explanatory copy
+- alternate long-form text for abbreviated display
+
+## 4. Dynamic content that changes after render
+
+This still fits `EllipsisText` when the visible text can change after mount and you want the overflow-aware tooltip state to stay correct.
+
+Typical fit:
+
+- cells that refresh after a request
+- toggled tag or badge content
+- responsive layouts that resize with the page

package/dist/skills/using-ellipsis-text/references/gotchas.md

@@ -0,0 +1,19 @@
+# EllipsisText gotchas
+
+- Tooltip behavior is part of the component contract  
+  If tooltip access to the full value does not matter, plain truncation may be enough.
+
+- `lineClamp` uses a different truncation strategy than single-line ellipsis  
+  Choose the mode intentionally instead of treating them as interchangeable. When `lineClamp` is active, it takes precedence over the default single-line mode.
+
+- Tooltip visibility depends on actual overflow  
+  If the text is fully visible, the tooltip stays disabled.
+
+- `disabled` turns off tooltip reveal, not truncation itself  
+  Use it when the text should still be clipped visually but should not open the tooltip.
+
+- Layout constraints are still required  
+  `EllipsisText` does not create overflow on its own; the surrounding width or line budget must make truncation possible.
+
+- The wrapper `tag` affects layout semantics  
+  Inline versus block rendering can change how truncation behaves in the surrounding layout.

package/dist/skills/using-ellipsis-text/references/props.md

@@ -0,0 +1,97 @@
+# EllipsisText props
+
+## Overview
+
+`EllipsisText` combines truncation behavior with built-in tooltip handling and overflow detection.
+
+Use it when overflow-aware reveal behavior matters more than plain text rendering.
+
+## Minimum setup
+
+A minimal working setup is usually just:
+
+```vue
+<EllipsisText class="w-300px">{{ text }}</EllipsisText>
+```
+
+That works because:
+
+- `truncated` defaults to `true`
+- `tag` defaults to `span`
+- the tooltip uses the rendered text content by default
+
+You only need more props when the default single-line mode is not enough.
+
+Typical useful props:
+
+- `truncated`
+- or `lineClamp`
+
+Common optional props:
+
+- `tag`
+- `tooltip`
+- tooltip behavior props inherited from `Tooltip`
+
+## Core props
+
+### `truncated`
+
+Enables single-line truncation.
+
+Default: `true`
+
+### `lineClamp`
+
+Enables multi-line truncation.
+
+Use this when the design allows more than one visible line.
+
+Default: `false`
+
+When `lineClamp` is a positive number, the component uses multi-line clamping and the single-line `truncated` class no longer applies.
+
+### `tag`
+
+Controls the wrapper element.
+
+Default: `span`
+
+### `tooltip`
+
+Overrides the tooltip content.
+
+If not provided, the component falls back to the rendered text content.
+
+### `disabled`
+
+Disables the tooltip even if the text is overflowed.
+
+This affects tooltip visibility, not the truncation styles themselves.
+
+### Tooltip behavior props
+
+Useful inherited props include:
+
+- `trigger`
+- `placement`
+- `effect`
+- `showAfter`
+- `showArrow`
+- `hideAfter`
+- `enterable`
+- `teleported`
+
+## Behavior notes
+
+The tooltip is disabled when the text is fully visible or when the component is explicitly disabled.
+
+The overflow state updates when content or size changes, so slot content that changes after render can still produce the correct tooltip behavior.
+
+If you pass both `truncated` and `lineClamp`, treat `lineClamp` as the active mode.
+
+## Import
+
+```ts
+import { EllipsisText } from '@hinen/pro-element-plus';
+```

package/dist/skills/using-form-autocomplete/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: using-form-autocomplete
+description: Use when a wrapped field should combine FormItem semantics with callback-driven autocomplete suggestions inside the Form* wrapper family.
+---
+
+# Using FormAutocomplete
+
+## Overview
+
+Use `FormAutocomplete` for a **suggestion-driven wrapped field** that combines `FormItem` behavior with Element Plus autocomplete input behavior.
+
+It fits fields where typing should trigger suggestions or completions, but the field still needs to live inside the shared `Form*` wrapper family with standard label, validation, and tooltip behavior.
+
+## Use it when
+
+- a field should suggest options while typing
+- callback-driven suggestions are part of the core field behavior
+- you want autocomplete behavior plus built-in `FormItem` labels, rules, and help text
+- the field should expose both `formItem` and autocomplete `field` refs together
+
+## Prefer something else when
+
+- the option set is already known and select-style UI fits better  
+  → use `../using-form-select/SKILL.md`
+- the field should collect freeform tags instead of one current text value  
+  → use `../using-form-tag-input/SKILL.md`
+- you only need wrapper behavior around custom content  
+  → use `../using-form-item/SKILL.md`
+
+## Decision guide
+
+Use `FormAutocomplete` if the answer is yes for **two or more** of these:
+
+- Should typing actively drive suggestions?
+- Is the suggestion source callback-based rather than a fixed local option list?
+- Should the field stay inside the shared form-wrapper family?
+- Do you want wrapper validation access and autocomplete instance access together?
+
+If not, `FormSelect`, `FormTagInput`, or another wrapper may fit better.
+
+## Start with
+
+1. Decide what the text value represents and how suggestions should be fetched.
+2. Add the normal `FormItem` props such as `label`, `prop`, and `rules`.
+3. Add `fetchSuggestions` and related autocomplete props only after the wrapper choice is clear.
+4. Use slots only when the default suggestion row is not enough.
+
+## Minimal patterns
+
+### Standard wrapped autocomplete
+
+```vue
+<FormAutocomplete
+  label="Repository"
+  prop="repo"
+  :fetch-suggestions="fetchSuggestions"
+/>
+```
+
+### Suggest only after typing
+
+Use `triggerOnFocus="false"` when suggestions should wait for input instead of opening immediately on focus.
+
+### Custom suggestion row
+
+Use the default suggestion slot when each suggestion needs richer content than plain text.
+
+## Common mistakes
+
+- using `FormAutocomplete` when a fixed local choice list should just use `FormSelect`
+- treating autocomplete like a multi-tag input when the field only stores one current value
+- forgetting that suggestion behavior depends on `fetchSuggestions`, not a local `options` prop
+- reaching for manual `FormItem` plus autocomplete composition when the standard wrapper already fits
+
+## Related skills
+
+- Selection-control router when autocomplete is still one candidate among several choice patterns: `../building-selection-inputs/SKILL.md`
+- Wrapper-family selection: `../using-form-fields/SKILL.md`
+- Base wrapper only: `../using-form-item/SKILL.md`
+- Wrapped local select: `../using-form-select/SKILL.md`
+- Wrapped tag list input: `../using-form-tag-input/SKILL.md`
+
+## References
+
+- Props: `./references/props.md`
+- Examples: `./references/examples.md`
+- Gotchas: `./references/gotchas.md`

package/dist/skills/using-form-autocomplete/references/examples.md

@@ -0,0 +1,62 @@
+# FormAutocomplete examples
+
+## 1. Suggestion-driven text field
+
+Use `FormAutocomplete` when typing should surface likely matches while the field still behaves like one wrapped text value.
+
+Minimal pattern:
+
+```vue
+<FormAutocomplete
+  label="Repository"
+  prop="repo"
+  :fetch-suggestions="fetchSuggestions"
+/>
+```
+
+Typical fit:
+
+- repository lookup
+- city suggestions
+- account or member search terms
+
+## 2. Suggestions after typing begins
+
+Use `triggerOnFocus="false"` when the field should stay quiet on focus and only suggest after the user types.
+
+Minimal pattern:
+
+```vue
+<FormAutocomplete
+  label="Member"
+  prop="member"
+  :fetch-suggestions="fetchMembers"
+  :trigger-on-focus="false"
+/>
+```
+
+Typical fit:
+
+- large suggestion spaces
+- expensive lookup callbacks
+- search-like field behavior
+
+## 3. Custom suggestion rendering
+
+Use the suggestion-row slot when each result needs more context than a single label.
+
+Minimal pattern:
+
+```vue
+<FormAutocomplete label="Package" prop="pkg" :fetch-suggestions="fetchPackages">
+  <template #default="{ item }">
+    <span>{{ item.label }}</span>
+  </template>
+</FormAutocomplete>
+```
+
+Typical fit:
+
+- label plus metadata
+- title plus URL
+- name plus secondary description

package/dist/skills/using-form-autocomplete/references/gotchas.md

@@ -0,0 +1,13 @@
+# FormAutocomplete gotchas
+
+- `FormAutocomplete` is suggestion-driven, not option-list-driven  
+  If the option set is already known, `../using-form-select/SKILL.md` is usually clearer.
+
+- The field still stores one current value  
+  If the feature needs many freeform entries, prefer `../using-form-tag-input/SKILL.md`.
+
+- Wrapper props and autocomplete props are merged  
+  Keep clear which behavior belongs to the form shell and which belongs to the suggestion input.
+
+- `fetchSuggestions` is the core behavior, not an enhancement  
+  If the field does not really need callback-driven suggestions, autocomplete adds complexity where a local select or text field would be clearer.

package/dist/skills/using-form-autocomplete/references/props.md

@@ -0,0 +1,100 @@
+# FormAutocomplete props
+
+## Overview
+
+`FormAutocomplete` combines `FormItem` props with Element Plus autocomplete props.
+
+Use it when callback-driven suggestions should live inside the shared form-wrapper family.
+
+## Minimum setup
+
+A minimal working setup is usually just:
+
+```vue
+<FormAutocomplete
+  label="Repository"
+  prop="repo"
+  :fetch-suggestions="fetchSuggestions"
+/>
+```
+
+That is enough when callback-driven suggestions are the real reason to use the field.
+
+Typical useful props:
+
+- `label`
+- `prop`
+- `modelValue`
+- `fetchSuggestions`
+
+Common optional field props:
+
+- `triggerOnFocus`
+- `placeholder`
+- `readonly`
+
+## Core props
+
+### Wrapper props from `FormItem`
+
+Includes wrapper-level props such as:
+
+- `label`
+- `prop`
+- `rules`
+- `required`
+- `tooltip`
+
+### `fetchSuggestions`
+
+The main autocomplete hook.
+
+Use this to provide callback-driven suggestions from local logic or async-backed lookup code.
+
+This is the real required behavior prop in normal usage. If suggestion fetching is not central, the field usually wants `FormSelect` or `FormText` instead.
+
+### Common autocomplete props
+
+Useful field props include:
+
+- `modelValue`
+- `triggerOnFocus`
+- `placeholder`
+- `readonly`
+
+`triggerOnFocus` is one of the first behavior props to check because it changes whether the field feels like proactive suggestion or search-after-typing.
+
+## Slots
+
+Useful slots include:
+
+- wrapper-level `label` and `error`
+- autocomplete suggestion-row slots such as the default item slot
+- input-adornment slots such as `prefix` and `suffix`
+
+Use item slots only after the fetch shape and selection behavior are already correct.
+
+## Instance API
+
+The exposed instance combines:
+
+- `formItem`
+- `field`
+
+## Events
+
+Important events include:
+
+- `update:modelValue`
+- `input`
+- `change`
+- `focus`
+- `blur`
+- `select`
+- `clear`
+
+## Import
+
+```ts
+import { FormAutocomplete } from '@hinen/pro-element-plus';
+```

package/dist/skills/using-form-cascade-select/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: using-form-cascade-select
+description: Use when a wrapped field should combine FormItem semantics with cascader-style hierarchical path selection inside the Form* wrapper family.
+---
+
+# Using FormCascadeSelect
+
+## Overview
+
+Use `FormCascadeSelect` for a **path-oriented hierarchical wrapped field** that combines `FormItem` behavior with Element Plus cascader behavior.
+
+It fits fields where users should pick through nested options as a path, rather than interact with a full tree selection model.
+
+## Use it when
+
+- a field chooses from nested options where path-style cascading is the right UX
+- you want cascader behavior plus built-in `FormItem` labels, rules, and help text
+- hierarchical options, lazy loading, or filterable cascading are part of the field contract
+- the field should expose both `formItem` and cascader `field` refs together
+
+## Prefer something else when
+
+- tree semantics fit better than path selection  
+  → use `../using-form-tree-select/SKILL.md`
+- a simple local flat choice list is enough  
+  → use `../using-form-select/SKILL.md`
+- you only need wrapper behavior around custom content  
+  → use `../using-form-item/SKILL.md`
+
+## Decision guide
+
+Use `FormCascadeSelect` if the answer is yes for **two or more** of these:
+
+- Should users move through nested options as a path?
+- Is the hierarchy better expressed as parent-to-child expansion instead of a visible tree?
+- Should the field stay inside the shared form-wrapper family?
+- Do you want wrapper validation access and cascader instance access together?
+
+If not, `FormTreeSelect`, `FormSelect`, or another wrapper may fit better.
+
+## Start with
+
+1. Decide whether the hierarchy should behave like a cascader path or a tree.
+2. Add the normal `FormItem` props such as `label`, `prop`, and `rules`.
+3. Add `options`, cascader `props`, and filtering or lazy-loading behavior only after the wrapper choice is clear.
+4. Use tree-oriented wrappers instead if node semantics matter more than path traversal.
+
+## Minimal patterns
+
+### Standard wrapped cascader
+
+```vue
+<FormCascadeSelect label="Category" prop="category" :options="options" />
+```
+
+### Hover-expand or multiple cascader
+
+Use cascader `props` when expand trigger, multiple choice, or strictness should change.
+
+### Lazy-loaded hierarchy
+
+Use lazy cascader props when child nodes should load on demand.
+
+## Common mistakes
+
+- using `FormCascadeSelect` when tree node semantics would be clearer
+- treating path selection and tree selection as interchangeable
+- forgetting that cascader `props` control major behavior such as hover expansion, strictness, and lazy loading
+
+## Related skills
+
+- Business-form workflow router: `../building-form-workflows/SKILL.md`
+- Wrapper-family selection: `../using-form-fields/SKILL.md`
+- Base wrapper only: `../using-form-item/SKILL.md`
+- Wrapped tree select: `../using-form-tree-select/SKILL.md`
+- Wrapped local select: `../using-form-select/SKILL.md`
+
+## References
+
+- Props: `./references/props.md`
+- Examples: `./references/examples.md`
+- Gotchas: `./references/gotchas.md`

package/dist/skills/using-form-cascade-select/references/examples.md

@@ -0,0 +1,59 @@
+# FormCascadeSelect examples
+
+## 1. Standard hierarchical path field
+
+Use `FormCascadeSelect` when users should drill through nested options as a path.
+
+Minimal pattern:
+
+```vue
+<FormCascadeSelect label="Category" prop="category" :options="options" />
+```
+
+Typical fit:
+
+- region selection
+- category path selection
+- nested taxonomy paths
+
+## 2. Multi-select or strict cascader behavior
+
+Use cascader `props` when multiple path selection or strict parent-child behavior matters.
+
+Minimal pattern:
+
+```vue
+<FormCascadeSelect
+  label="Scopes"
+  prop="scopes"
+  :options="options"
+  :props="cascaderProps"
+/>
+```
+
+Typical fit:
+
+- multi-category assignment
+- partial hierarchy selection
+- mixed parent or child pick rules
+
+## 3. Lazy-loaded hierarchy
+
+Use lazy loading when the full option tree is too large to preload.
+
+Minimal pattern:
+
+```vue
+<FormCascadeSelect
+  label="Region"
+  prop="region"
+  :options="options"
+  :props="lazyProps"
+/>
+```
+
+Typical fit:
+
+- remote taxonomy loading
+- deep organization trees
+- large nested catalogs