@hinen/pro-element-plus 1.7.16 → 1.8.0

package/dist/skills/building-selection-inputs/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: building-selection-inputs
+description: Use when you need to route selection UX into the right direct component or form-wrapper skill across dropdown, checkbox, radio, and request-driven choice patterns.
+---
+
+# Building selection inputs
+
+## Overview
+
+Use this skill as the **selection-control router** for the package.
+
+Its job is to decide between visible choice sets, dropdowns, remote option loading, and form-wrapper variants, then hand off to the right normalized `using-*` skill.
+
+## Use it when
+
+Use this skill when several of these are true:
+
+- you need to choose between dropdown, checkbox, radio, or remote-select patterns
+- you need to know when to use a base selection component versus a `Form*` wrapper
+- you want one quick routing layer before opening a component skill
+- option visibility, option source, or wrapper context are still undecided
+
+Strong signals this skill applies:
+
+- “should users see all options or open a dropdown?”
+- “is this local data or request-driven data?”
+- “does this belong in a form wrapper?”
+
+## Prefer something else when
+
+- you already know the exact selection component you need  
+  → open `../using-select/SKILL.md`, `../using-data-select/SKILL.md`, `../using-radio-group/SKILL.md`, or `../using-checkbox-group/SKILL.md` directly
+- the broader workflow is still undecided and the main question is page shape or form shape  
+  → use `../choosing-components/SKILL.md`, `../building-form-workflows/SKILL.md`, or `../building-query-pages/SKILL.md`
+
+## Decision guide
+
+Use `building-selection-inputs` if the answer is yes for **two or more** of these:
+
+- Are several selection modalities still plausible?
+- Does option visibility versus dropdown behavior matter to the UX?
+- Is the source of options still undecided between local and request-driven?
+- Do you need to choose between direct controls and form-wrapper versions?
+
+If not, go straight to the narrowest known selection skill.
+
+## Recommended path
+
+1. Decide whether users should see all options at once or open a dropdown.
+2. Decide whether the option list is local or request-driven.
+3. If choices stay visible:
+   - one visible choice → `../using-radio-group/SKILL.md`
+   - many visible choices → `../using-checkbox-group/SKILL.md`
+4. If choices live in a dropdown:
+   - local options → `../using-select/SKILL.md`
+   - request-driven or filter-aware options → `../using-data-select/SKILL.md`
+5. If the control lives inside a schema-driven form or wrapper flow, swap to the matching `using-form-*` skill instead of the direct control.
+   - wrapped local dropdown → `../using-form-select/SKILL.md`
+   - wrapped visible single choice → `../using-form-radio-group/SKILL.md`
+   - wrapped visible multi choice → `../using-form-checkbox-group/SKILL.md`
+   - if request behavior is the dominant concern, compare `../using-data-select/SKILL.md` and `../using-form-select/SKILL.md` intentionally because there is no dedicated wrapped `DataSelect` router here
+
+## Common mistakes
+
+- choosing a dropdown when the UX needs visible comparison of a short set
+- using visible radio or checkbox groups for long lists that should be selects
+- skipping the local-versus-request-driven decision and forcing `Select` or `DataSelect` too early
+- choosing direct controls when the field really belongs in a wrapped form flow
+
+## Related skills
+
+- Top-level router: `../choosing-components/SKILL.md`
+- Local dropdown: `../using-select/SKILL.md`
+- Request-aware dropdown: `../using-data-select/SKILL.md`
+- Visible single-choice control: `../using-radio-group/SKILL.md`
+- Visible multi-choice control: `../using-checkbox-group/SKILL.md`
+- Wrapped local dropdown: `../using-form-select/SKILL.md`
+- Wrapped visible single-choice control: `../using-form-radio-group/SKILL.md`
+- Wrapped visible multi-choice control: `../using-form-checkbox-group/SKILL.md`
+
+## References
+
+- Selection guide: `./references/selection-guide.md`
+- Examples: `./references/examples.md`
+- Gotchas: `./references/gotchas.md`

package/dist/skills/building-selection-inputs/references/examples.md

@@ -0,0 +1,87 @@
+# Selection-input examples
+
+## 1. Short status picker
+
+Use `../../using-radio-group/SKILL.md` when a single visible choice is clearer than a dropdown.
+
+Minimal pattern:
+
+```vue
+<RadioGroup :options="statusOptions" v-model="status" />
+```
+
+Why this fits:
+
+- only one value can be chosen
+- the option set is short enough to stay visible
+- comparison is easier than opening a dropdown
+
+## 2. Multi-tag preferences
+
+Use `../../using-checkbox-group/SKILL.md` when users need to see and combine several fixed options.
+
+Minimal pattern:
+
+```vue
+<CheckboxGroup :options="featureOptions" v-model="enabledFeatures" />
+```
+
+Why this fits:
+
+- multiple values may be selected
+- the option set is local and comparison-friendly
+- visibility matters more than saving space
+
+## 3. Large or remote option list
+
+Use `../../using-data-select/SKILL.md` when options depend on a request, params, or typed filtering.
+
+Minimal pattern:
+
+```vue
+<DataSelect v-model="userId" :request="requestUsers" filterable="remote" />
+```
+
+Why this fits:
+
+- options come from a request instead of a fixed local array
+- loading behavior is part of the component decision
+- a dropdown is more scalable than visible choices
+
+## 4. Local dropdown for known options
+
+Use `../../using-select/SKILL.md` when the options are known locally but still clearer in a dropdown than as visible radios or checkboxes.
+
+Minimal pattern:
+
+```vue
+<Select :options="statusOptions" v-model="status" />
+```
+
+Why this fits:
+
+- the option list is local
+- space matters more than visible comparison
+- request behavior is not part of the component choice
+
+## 5. Same semantics inside a form wrapper
+
+Use the matching `../../using-form-*.md` skill when the same choice semantics belong inside a schema-driven form flow.
+
+Minimal pattern:
+
+```vue
+<FormRadioGroup label="Status" prop="status" :options="statusOptions" />
+```
+
+Common routes:
+
+- wrapped visible single choice → `../../using-form-radio-group/SKILL.md`
+- wrapped visible multi choice → `../../using-form-checkbox-group/SKILL.md`
+- wrapped local dropdown → `../../using-form-select/SKILL.md`
+
+Special note:
+
+- if request behavior is the dominant concern inside a form-like surface, compare `../../using-data-select/SKILL.md` and `../../using-form-select/SKILL.md` intentionally, because there is no dedicated wrapped `DataSelect` router here
+
+Use this route when the wrapper boundary matters as much as the selection modality.

package/dist/skills/building-selection-inputs/references/gotchas.md

@@ -0,0 +1,19 @@
+# Selection-input gotchas
+
+- “Visible choices” and “dropdown choices” are different UX decisions  
+  Do not choose by implementation habit before deciding which interaction users should see.
+
+- The routing order matters  
+  Decide visible-versus-dropdown first, local-versus-request-driven second, and direct-versus-wrapper third. Reversing that order usually creates the wrong component choice.
+
+- Short option sets often should stay visible  
+  Do not jump to a dropdown when a short set benefits from direct comparison as radios or checkboxes.
+
+- Long visible choice sets become noise fast  
+  If users must scan too many always-visible options, move back toward `Select` or `DataSelect` instead of forcing radio or checkbox groups.
+
+- Local and request-driven options are different component families  
+  If loading behavior matters, make that decision before picking between `Select` and `DataSelect`.
+
+- Direct controls and form-wrapper controls are different abstraction levels  
+  Use the wrapper variants when the field belongs inside schema-driven form flow.

package/dist/skills/building-selection-inputs/references/selection-guide.md

@@ -0,0 +1,47 @@
+# Selection guide
+
+Use this guide when the control is already known to be a **selection input** and the remaining decision is about modality, option source, or wrapper depth.
+
+## 1. Decide whether options stay visible or live in a dropdown
+
+- visible single choice → `../../using-radio-group/SKILL.md`
+- visible multi choice → `../../using-checkbox-group/SKILL.md`
+- dropdown choice → continue to the source decision below
+
+## 2. If it is a dropdown, decide whether options are local or request-driven
+
+- local dropdown, grouped options, custom slots → `../../using-select/SKILL.md`
+- request-driven options, filter-aware loading, debounce → `../../using-data-select/SKILL.md`
+
+Prefer `DataSelect` only when option-loading behavior is part of the component decision, not just a future possibility.
+
+## 3. Decide whether the control should be direct or wrapped
+
+Use the direct component when:
+
+- the control stands on its own
+- wrapper-level label and validation behavior are not the main abstraction
+- the main choice is purely about UX modality
+
+Use form wrappers when:
+
+- the control lives inside a schema-driven form
+- the field should inherit `FormItem` label, validation, and wrapper behavior
+- the choice semantics stay the same, but the abstraction level changes
+
+Wrapper destinations:
+
+- `../../using-form-select/SKILL.md`
+- `../../using-form-checkbox-group/SKILL.md`
+- `../../using-form-radio-group/SKILL.md`
+- `../../using-form-cascade-select/SKILL.md`
+- `../../using-form-tree-select/SKILL.md`
+- `../../using-form-autocomplete/SKILL.md`
+
+## 4. Keep these routing rules straight
+
+- visible vs dropdown is a UX decision first
+- local vs request-driven is a data-source decision second
+- direct vs wrapper is an abstraction-level decision third
+
+If the broader page or workflow family is still unclear, hand back up to `../../choosing-components/SKILL.md` instead of forcing a selection-control decision too early.

package/dist/skills/choosing-components/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: choosing-components
+description: Use when you know the workflow or page shape you need, but not yet which @hinen/pro-element-plus using-* skill should lead the implementation.
+---
+
+# Choosing components
+
+## Overview
+
+Use this skill as the **top-level router** for the package skill system.
+
+It is not a component API guide. Its job is to move from product intent — query page, form flow, overlay, selection control, or display primitive — into the smallest correct `using-*` or `building-*` skill.
+
+## Use it when
+
+Use this skill when several of these are true:
+
+- you know the workflow you need, but not the component name
+- you need to decide between a direct component and a `Form*` wrapper
+- you need to narrow down selection, overlay, query, or display building blocks quickly
+- you want one routing layer before opening a deeper component skill
+
+Strong signals this skill applies:
+
+- “which component should I use here?”
+- “is this a QueryForm page or a DataTable page?”
+- “should this be a select, radios, or checkboxes?”
+- “does this belong in a form wrapper?”
+
+## Prefer something else when
+
+- you already know the exact component and only need its usage rules  
+  → open the matching `using-*` skill directly
+- you are already narrowed to one workflow family such as selection, forms, overlays, or query pages  
+  → use `../building-selection-inputs/SKILL.md`, `../building-form-workflows/SKILL.md`, `../building-modal-workflows/SKILL.md`, or `../building-query-pages/SKILL.md`
+
+## Decision guide
+
+Use `choosing-components` if the answer is yes for **two or more** of these:
+
+- Do you only know the user task, not the component?
+- Are several component families still plausible?
+- Do you need help choosing between direct components and wrapper variants?
+- Would opening one routing skill first reduce the chance of picking the wrong implementation path?
+
+If not, go straight to the narrowest known `using-*` skill.
+
+## Recommended path
+
+1. Start from the user task: query page, schema form, overlay flow, selection input, or display-only primitive.
+2. Pick the relevant workflow router:
+   - query and result pages → `../building-query-pages/SKILL.md`
+   - schema-driven forms → `../building-form-workflows/SKILL.md`
+   - modal and drawer flows → `../building-modal-workflows/SKILL.md`
+   - choice controls → `../building-selection-inputs/SKILL.md`
+3. If none of those fit cleanly, use the component-group map to jump directly into the smallest `using-*` skill.
+4. Once narrowed, leave this skill and finish in the destination skill instead of staying at the top level.
+
+## Common mistakes
+
+- staying in the top-level router when the correct destination skill is already obvious
+- jumping directly to a low-level component before deciding whether the workflow wants a wrapper or page-level shell
+- treating `choosing-components` like a props guide instead of a handoff layer
+- using one component family to force-fit a workflow that clearly belongs to another family
+
+## Related skills
+
+- Selection-control router: `../building-selection-inputs/SKILL.md`
+- Form-workflow router: `../building-form-workflows/SKILL.md`
+- Overlay router: `../building-modal-workflows/SKILL.md`
+- Query-page router: `../building-query-pages/SKILL.md`
+
+## References
+
+- Component map: `./references/component-groups.md`
+- Selection decision guide: `./references/selection-guide.md`
+- Examples: `./references/examples.md`
+- Gotchas: `./references/gotchas.md`

package/dist/skills/choosing-components/references/component-groups.md

@@ -0,0 +1,37 @@
+# Component groups
+
+## Page-building flows
+
+- `../building-query-pages/SKILL.md` for search + results pages
+- `../building-form-workflows/SKILL.md` for schema-driven forms
+- `../building-modal-workflows/SKILL.md` for modal or drawer flows
+- `../building-selection-inputs/SKILL.md` for option picking controls
+
+## Data and display
+
+- `../../using-data-table/SKILL.md` for paginated query + table pages
+- `../../using-query-form/SKILL.md` for standalone filter/search forms
+- `../../using-image/SKILL.md` for image loading, preview, and failure states
+- `../../using-ellipsis-text/SKILL.md` for truncation with tooltip support
+
+## Selection controls
+
+- `../../using-select/SKILL.md` for local select inputs with slots and grouping
+- `../../using-data-select/SKILL.md` for remote or request-driven options
+- `../../using-checkbox-group/SKILL.md` for multi-select sets rendered as checkboxes
+- `../../using-radio-group/SKILL.md` for single-choice sets rendered as radios
+
+## Overlays
+
+- `../../using-modal/SKILL.md` for centered confirm or edit dialogs
+- `../../using-drawer/SKILL.md` for side-panel flows with confirm and cancel actions
+
+## Form wrappers
+
+- `../../using-form-fields/SKILL.md` for the `FormFields` family overview
+- `../../using-form-item/SKILL.md` for label, validation, and tooltip wrapper behavior
+- `../../using-form-text/SKILL.md`, `../../using-form-number/SKILL.md`, `../../using-form-select/SKILL.md` and the other `using-form-*` skills for field-specific details
+
+## Shared configuration
+
+- `../../using-config-provider/SKILL.md` for shared DataTable empty and error rendering

package/dist/skills/choosing-components/references/examples.md

@@ -0,0 +1,91 @@
+# Choosing-components examples
+
+## 1. “I need a search page”
+
+Start with `../building-query-pages/SKILL.md` when the page shape is filter plus results, not just one isolated component.
+
+Typical fit:
+
+- admin list page with filters and rows
+- report page with a standard search shell
+- table page that may later need shared empty or error treatment
+
+## 2. “I need a field in a business form”
+
+Start with `../building-form-workflows/SKILL.md` when the main decision is wrapper-family field choice rather than one raw input control.
+
+Typical fit:
+
+- settings form
+- record create or edit form
+- schema-driven form with mixed text, number, and wrapped choice fields
+
+## 3. “I need users to pick from several options”
+
+Start with `../building-selection-inputs/SKILL.md` when the choice is between dropdown, checkbox, radio, wrapper, or request-driven selection.
+
+Typical fit:
+
+- local dropdown versus visible radio decision
+- API-backed selector with remote options
+- selection control that may need a `Form*` wrapper instead of a direct component
+
+## 4. “I need an overlay flow”
+
+Start with `../building-modal-workflows/SKILL.md` when the main decision is centered modal versus side drawer.
+
+Typical fit:
+
+- confirm dialog
+- compact modal editor
+- side-panel review or edit flow
+
+## 5. “I need a selection control inside a form”
+
+Start with `../building-selection-inputs/SKILL.md` to choose the selection modality first, then move into `../building-form-workflows/SKILL.md` or the matching `using-form-*` skill when wrapper semantics become the real decision.
+
+Typical fit:
+
+- status selector inside a schema form
+- wrapped checkbox or radio field in settings forms
+- remote choice input that still belongs to a `FormItem` flow
+
+## 6. “I need an overlay that contains a form”
+
+Start with `../building-modal-workflows/SKILL.md` for the shell decision, then hand off to `../building-form-workflows/SKILL.md` for the body workflow.
+
+Typical fit:
+
+- edit-user modal
+- create-project drawer
+- approval overlay with wrapped fields and validation
+
+## 7. “I need an overlay that contains a searchable list”
+
+Start with `../building-modal-workflows/SKILL.md` for the shell decision, then hand off to `../building-query-pages/SKILL.md` when the body is really filter plus results.
+
+Typical fit:
+
+- select-from-list drawer
+- search-and-pick modal
+- review-history overlay with filters and rows
+
+## 8. “I need the same field semantics in both forms and search pages”
+
+Start with the workflow that owns the current surface, but expect a handoff between `../building-form-workflows/SKILL.md` and `../building-query-pages/SKILL.md` when the field meaning must stay consistent across both contexts.
+
+Typical fit:
+
+- status and date fields that appear in both edit forms and list filters
+- business entities edited in one screen and searched in another
+
+## 9. “I’m not sure whether this is a page shell, a field choice, or an overlay problem”
+
+Stay in `choosing-components` long enough to classify the user task first:
+
+- page with filters and results → `../building-query-pages/SKILL.md`
+- business-form flow → `../building-form-workflows/SKILL.md`
+- overlay shell decision → `../building-modal-workflows/SKILL.md`
+- selection modality decision → `../building-selection-inputs/SKILL.md`
+
+If the destination is already obvious after that classification, leave the top-level router immediately.

package/dist/skills/choosing-components/references/gotchas.md

@@ -0,0 +1,10 @@
+# Choosing-components gotchas
+
+- This skill is a router, not a destination  
+  Once the correct workflow family is clear, move into that skill instead of staying here.
+
+- Workflow shape matters more than component names  
+  Choosing by familiar component names too early often leads to the wrong abstraction level.
+
+- Direct components and `Form*` wrappers are different decisions  
+  If the control belongs in schema-driven form flow, use the form router before picking a direct component.

package/dist/skills/choosing-components/references/selection-guide.md

@@ -0,0 +1,40 @@
+# Selection guide
+
+Use this guide only when you are still at the **top-level routing** stage and selection controls are merely one candidate family among several.
+
+## Start here
+
+- If the product question is really “which kind of selection control is this?” → go to `../../building-selection-inputs/SKILL.md`
+- If the broader page or workflow family is still unclear → stay in `../SKILL.md` and finish the top-level routing first
+
+## Use direct selection components when
+
+- the control stands on its own outside a schema-driven wrapper flow
+- the main question is direct component choice rather than form-shell semantics
+
+Typical direct destinations:
+
+- local dropdown → `../../using-select/SKILL.md`
+- request-driven dropdown → `../../using-data-select/SKILL.md`
+- visible single choice → `../../using-radio-group/SKILL.md`
+- visible multi choice → `../../using-checkbox-group/SKILL.md`
+
+## Use form wrappers when
+
+- the control lives inside a schema-driven form or `QueryForm.items`
+- `FormItem` label, validation, and wrapper behavior should come along with the field
+- the choice semantics stay the same, but the abstraction level changes
+
+Typical wrapper destinations:
+
+- `../../using-form-select/SKILL.md`
+- `../../using-form-checkbox-group/SKILL.md`
+- `../../using-form-radio-group/SKILL.md`
+- `../../using-form-cascade-select/SKILL.md`
+- `../../using-form-tree-select/SKILL.md`
+- `../../using-form-autocomplete/SKILL.md`
+
+## When to leave this guide
+
+- If selection controls are definitely the right family, continue in `../../building-selection-inputs/SKILL.md` or its references instead of staying in the top-level router.
+- If the workflow is already known to be query-page, form-workflow, or overlay work, use that router directly.