@hinen/pro-element-plus 1.7.17 → 1.8.1

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

@@ -0,0 +1,82 @@
+# FormNumber props
+
+## Overview
+
+`FormNumber` combines `FormItem` props with Element Plus input-number props.
+
+Use it when numeric-control semantics should stay inside the standard form-wrapper family.
+
+## Minimum setup
+
+Typical useful props:
+
+- `label`
+- `prop`
+- `modelValue`
+
+Numeric-control props often worth deciding early:
+
+- `min`
+- `max`
+- `step`
+- `precision`
+
+## Core props
+
+### Wrapper props from `FormItem`
+
+Includes wrapper-level props such as:
+
+- `label`
+- `prop`
+- `rules`
+- `required`
+- `tooltip`
+
+### Numeric-field props from `ElInputNumber`
+
+Commonly useful field props include:
+
+- `modelValue`
+- `min`
+- `max`
+- `step`
+- `precision`
+- `disabled`
+- `size`
+
+These are the props that usually determine whether this wrapper is the correct abstraction.
+
+## Slots
+
+The wrapper supports both wrapper-level and numeric-field slots.
+
+Most important wrapper slots remain:
+
+- `label`
+- `error`
+
+## Instance API
+
+The exposed instance combines:
+
+- `formItem`
+- `field`
+
+Use this when parent code needs wrapper validation methods and direct access to the numeric input instance.
+
+## Events
+
+Important events include:
+
+- `update:modelValue`
+- `change`
+- `input`
+- `focus`
+- `blur`
+
+## Import
+
+```ts
+import { FormNumber } from '@hinen/pro-element-plus';
+```

package/dist/skills/using-form-radio-group/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: using-form-radio-group
+description: Use when a wrapped field should combine FormItem semantics with single-choice radio-group behavior inside the Form* wrapper family.
+---
+
+# Using FormRadioGroup
+
+## Overview
+
+Use `FormRadioGroup` for a **single-choice wrapped field** that combines `FormItem` behavior with the package’s `RadioGroup` abstraction.
+
+It fits fields where the user should pick exactly one option from a fixed set while staying inside the shared form-wrapper family.
+
+## Use it when
+
+- a schema-driven field should expose one-of-many choice behavior
+- you want radio-group options plus built-in form labels, rules, and tooltip support
+- options can come from `options` or lightweight `valueEnum` mappings
+- the field should expose both `formItem` and radio-group `field` refs together
+
+## Prefer something else when
+
+- you need the raw radio-group component outside FormFields  
+  → use `../using-radio-group/SKILL.md`
+- the field should allow multiple checked values  
+  → use `../using-form-checkbox-group/SKILL.md`
+- the field is really a binary toggle  
+  → use `../using-form-switch/SKILL.md`
+
+## Decision guide
+
+Use `FormRadioGroup` if the answer is yes for **two or more** of these:
+
+- Should the user choose exactly one option from a fixed set?
+- Is the option set local enough for `options` or `valueEnum`?
+- Should the field stay inside the shared form-wrapper family?
+- Do you want wrapper validation access and radio-group instance access together?
+
+If not, `FormCheckboxGroup`, `FormSwitch`, or another wrapper may fit better.
+
+## Start with
+
+1. Decide whether the field is single-choice, multi-choice, or binary.
+2. Add the normal `FormItem` props such as `label`, `prop`, and `rules`.
+3. Choose `options` or `valueEnum` after the wrapper choice is clear.
+4. Use checkbox groups or switches instead if the interaction is not really one-of-many.
+
+## Minimal patterns
+
+### Standard wrapped radio group
+
+```vue
+<FormRadioGroup label="Status" prop="status" :options="options" />
+```
+
+### Enum-backed wrapped radio group
+
+Use `valueEnum` when a compact mapping is clearer than an explicit options array.
+
+### Custom option rendering
+
+Use slots when the option body should render as custom radio buttons or richer content.
+
+## Common mistakes
+
+- using `FormRadioGroup` when many values can be selected
+- using it for a true or false toggle that should be a switch instead
+- forgetting that `valueEnum` is converted into local options by the wrapper
+
+## Related skills
+
+- Selection-control router above this wrapped choice: `../building-selection-inputs/SKILL.md`
+- Wrapper-family selection: `../using-form-fields/SKILL.md`
+- Base wrapper only: `../using-form-item/SKILL.md`
+- Raw radio group: `../using-radio-group/SKILL.md`
+- Wrapped checkbox group: `../using-form-checkbox-group/SKILL.md`
+- Wrapped switch: `../using-form-switch/SKILL.md`
+
+## References
+
+- Props: `./references/props.md`
+- Examples: `./references/examples.md`
+- Gotchas: `./references/gotchas.md`

package/dist/skills/using-form-radio-group/references/examples.md

@@ -0,0 +1,53 @@
+# FormRadioGroup examples
+
+## 1. Standard one-of-many field
+
+Use `FormRadioGroup` when a wrapped form field should allow exactly one choice from a fixed local set.
+
+Minimal pattern:
+
+```vue
+<FormRadioGroup label="Status" prop="status" :options="statusOptions" />
+```
+
+Typical fit:
+
+- status
+- mode selection
+- plan choice
+
+## 2. Enum-backed radio field
+
+Use `valueEnum` when a compact value-to-label mapping is clearer than an explicit options array.
+
+Minimal pattern:
+
+```vue
+<FormRadioGroup label="Mode" prop="mode" :value-enum="modeEnum" />
+```
+
+Typical fit:
+
+- small status enums
+- compact configuration modes
+- admin-only choice sets
+
+## 3. Custom radio rendering
+
+Use slots when the option body should render as radio buttons or richer content instead of default labels.
+
+Minimal pattern:
+
+```vue
+<FormRadioGroup label="Plan" prop="plan" :options="planOptions">
+  <template #default="{ option }">
+    <span>{{ option.label }}</span>
+  </template>
+</FormRadioGroup>
+```
+
+Typical fit:
+
+- branded choices
+- icon-backed options
+- explanatory option labels

package/dist/skills/using-form-radio-group/references/gotchas.md

@@ -0,0 +1,13 @@
+# FormRadioGroup gotchas
+
+- Radio groups are for one-of-many choice  
+  If many values can be checked, use `../using-form-checkbox-group/SKILL.md`.
+
+- A switch is often clearer for binary state  
+  If the field is really just on or off, `../using-form-switch/SKILL.md` is usually a better fit.
+
+- `valueEnum` becomes local options  
+  It is a convenience input, not a separate remote option-loading mode.
+
+- This wrapped field is still part of the selection family  
+  If you are not yet sure whether the field should be radio, checkbox, select, or autocomplete, route back up through `../building-selection-inputs/SKILL.md` before locking into this wrapper.

package/dist/skills/using-form-radio-group/references/props.md

@@ -0,0 +1,81 @@
+# FormRadioGroup props
+
+## Overview
+
+`FormRadioGroup` combines `FormItem` props with the package’s `RadioGroup` props and adds `valueEnum` as a compact option source.
+
+Use it when single-choice behavior should stay inside the shared form-wrapper family.
+
+## Minimum setup
+
+A minimal working setup is usually just:
+
+```vue
+<FormRadioGroup label="Status" prop="status" :options="statusOptions" />
+```
+
+That works because the wrapper already combines `FormItem` semantics with radio-group behavior.
+
+Typical useful props:
+
+- `label`
+- `prop`
+- one of `options` or `valueEnum`
+
+## Core props
+
+### Wrapper props from `FormItem`
+
+Includes wrapper-level props such as:
+
+- `label`
+- `prop`
+- `rules`
+- `required`
+- `tooltip`
+
+`label` and `prop` are the minimum wrapper-level anchors in most schema-driven usage.
+
+### Radio-group props
+
+Useful field props include:
+
+- `options`
+- `modelValue`
+- disabled-state and layout props from the wrapped radio-group abstraction
+
+Use `options` for the normal local-choice case. Treat `modelValue` as the selected stored value for the field, not as a visual-only toggle.
+
+### `valueEnum`
+
+Compact mapping from value to label.
+
+The wrapper converts this into local radio options when `options` is not provided.
+
+Use either `options` or `valueEnum` as the option source of truth. `valueEnum` is a compact local mapping, not a remote-loading mode.
+
+## Slots
+
+Useful slots include wrapper-level `label` and `error`, plus radio option-rendering slots from the wrapped radio-group abstraction.
+
+Reach for slots after the one-of-many field semantics are already correct.
+
+## Instance API
+
+The exposed instance combines:
+
+- `formItem`
+- `field`
+
+## Events
+
+Important events include:
+
+- `update:modelValue`
+- `change`
+
+## Import
+
+```ts
+import { FormRadioGroup } from '@hinen/pro-element-plus';
+```

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

@@ -0,0 +1,86 @@
+---
+name: using-form-rate
+description: Use when a wrapped field should combine FormItem semantics with rating-style input behavior inside the Form* wrapper family.
+---
+
+# Using FormRate
+
+## Overview
+
+Use `FormRate` for a **rating-style wrapped field** that combines `FormItem` behavior with Element Plus rate behavior.
+
+It fits fields where the value represents a score or rating and the interaction should feel like rating input rather than selecting from named options.
+
+## Use it when
+
+- a field captures rating semantics rather than a named enum
+- you want Element Plus rate behavior plus built-in `FormItem` labels and validation
+- score text, half values, or icon customization are part of the field contract
+- the field should expose both `formItem` and rate `field` refs together
+
+## Prefer something else when
+
+- the value should be a labeled option instead of stars or scores  
+  → use `../using-form-radio-group/SKILL.md`
+- the field should allow several checked values instead of one interpreted score  
+  → use `../using-form-checkbox-group/SKILL.md`
+- the field is really a numeric control with step or bounds semantics  
+  → use `../using-form-number/SKILL.md`
+- you only need wrapper behavior around custom content  
+  → use `../using-form-item/SKILL.md`
+
+## Decision guide
+
+Use `FormRate` if the answer is yes for **two or more** of these:
+
+- Is the value fundamentally a rating or score rather than a named option?
+- Should the interaction feel like stars, icons, or a visual score input?
+- Should the field stay inside the shared form-wrapper family?
+- Do you want wrapper validation access and rate instance access together?
+
+If not, `FormRadioGroup`, `FormNumber`, or another wrapper may fit better.
+
+## Start with
+
+1. Decide whether the field is truly rating-like or just another numeric or option value.
+2. Add the normal `FormItem` props such as `label`, `prop`, and `rules`.
+3. Add rate-specific props such as `allowHalf`, `showText`, or icon customization after the wrapper choice is clear.
+4. Use radio or numeric wrappers instead if the interaction is not really a rating.
+
+## Minimal patterns
+
+### Standard wrapped rating field
+
+```vue
+<FormRate label="Satisfaction" prop="satisfaction" />
+```
+
+### Text-backed or score-backed rating
+
+Use `showText` or `showScore` when the control should explain the rating value more explicitly.
+
+### Icon-customized rating
+
+Use custom icons or colors when the rating UI should communicate a domain-specific scale.
+
+## Common mistakes
+
+- using `FormRate` when the value is really a named choice that should be radios
+- treating rating input like a generic numeric field
+- forgetting that visual icon or text configuration changes how users interpret the score
+
+## Related skills
+
+- Business-form workflow router: `../building-form-workflows/SKILL.md`
+- Selection-control router when rating 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 radio group: `../using-form-radio-group/SKILL.md`
+- Wrapped checkbox group: `../using-form-checkbox-group/SKILL.md`
+- Wrapped number field: `../using-form-number/SKILL.md`
+
+## References
+
+- Props: `./references/props.md`
+- Examples: `./references/examples.md`
+- Gotchas: `./references/gotchas.md`

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

@@ -0,0 +1,60 @@
+# FormRate examples
+
+## 1. Standard rating field
+
+Use `FormRate` when the field stores a visual score or rating inside a wrapped form flow.
+
+Minimal pattern:
+
+```vue
+<FormRate label="Satisfaction" prop="satisfaction" />
+```
+
+Typical fit:
+
+- satisfaction ratings
+- review scores
+- feedback quality scores
+
+## 2. Text-backed or score-backed rating
+
+Use `showText` or `showScore` when the rating should explain its value more explicitly.
+
+Minimal pattern:
+
+```vue
+<FormRate label="Quality" prop="quality" show-text />
+```
+
+Typical fit:
+
+- user surveys
+- service-quality feedback
+- evaluation forms
+
+## 3. Custom icon rating
+
+Use custom icons or colors when the rating scale should match a domain-specific visual language.
+
+Minimal pattern:
+
+```vue
+<FormRate label="Mood" prop="mood" :icons="icons" :colors="colors" />
+```
+
+Typical fit:
+
+- mood scales
+- reaction scales
+- branded review UIs
+
+## 4. Wrapped rating in a mixed business form
+
+Use `FormRate` alongside text, number, or select wrappers when one field is truly a score while the rest of the form still follows the shared wrapper family.
+
+Minimal pattern:
+
+```vue
+<FormText label="Comment" prop="comment" />
+<FormRate label="Rating" prop="rating" />
+```

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

@@ -0,0 +1,16 @@
+# FormRate gotchas
+
+- Ratings are not the same as named choices  
+  If users are choosing among explicit labeled options, `../using-form-radio-group/SKILL.md` is usually clearer.
+
+- Ratings are not many-of-many selection  
+  If users may intentionally choose several values at once, `../using-form-checkbox-group/SKILL.md` is usually a better fit.
+
+- Ratings are not just generic numbers  
+  If the field needs step, min, max, or precision semantics rather than a visual score UI, prefer `../using-form-number/SKILL.md`.
+
+- Visual customization changes meaning  
+  Icons, colors, and text affect how users interpret the scale, so treat them as part of the field contract.
+
+- This wrapped field is still part of the selection family  
+  If you are not yet sure whether the field should be rating, radio, checkbox, or another choice pattern, route back up through `../building-selection-inputs/SKILL.md` before locking into this wrapper.

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

@@ -0,0 +1,88 @@
+# FormRate props
+
+## Overview
+
+`FormRate` combines `FormItem` props with Element Plus rate props.
+
+Use it when rating-style interaction should stay inside the shared form-wrapper family.
+
+## Minimum setup
+
+A minimal working setup is usually just:
+
+```vue
+<FormRate label="Satisfaction" prop="satisfaction" />
+```
+
+That is enough when the field stores one visual score inside a wrapped form flow.
+
+Typical useful props:
+
+- `label`
+- `prop`
+- `modelValue`
+
+Common optional field props:
+
+- `allowHalf`
+- `showText`
+- `showScore`
+- `clearable`
+
+## Core props
+
+### Wrapper props from `FormItem`
+
+Includes wrapper-level props such as:
+
+- `label`
+- `prop`
+- `rules`
+- `required`
+- `tooltip`
+
+### Common rate props
+
+Useful field props include:
+
+- `modelValue`
+- `max`
+- `allowHalf`
+- `showText`
+- `showScore`
+- `clearable`
+
+Treat `modelValue` as the current score for the field. `allowHalf`, `showText`, and `showScore` all change how users understand the rating contract, not just how it looks.
+
+### Visual customization props
+
+Use visual props when the score UI should communicate a domain-specific scale:
+
+- `icons`
+- `voidIcon`
+- `colors`
+- `texts`
+
+## Slots
+
+Useful slots include wrapper-level `label` and `error`.
+
+## Instance API
+
+The exposed instance combines:
+
+- `formItem`
+- `field`
+
+## Events
+
+Important events include:
+
+- `update:modelValue`
+- `change`
+
+## Import
+
+```ts
+import { FormRate } from '@hinen/pro-element-plus';
+```

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

@@ -0,0 +1,94 @@
+---
+name: using-form-select
+description: Use when a wrapped field should combine FormItem semantics with local select behavior, grouped options, or lightweight valueEnum mapping inside the Form* wrapper family.
+---
+
+# Using FormSelect
+
+## Overview
+
+Use `FormSelect` for a **select-style wrapped field** that combines `FormItem` wrapper behavior with the local-option `Select` component.
+
+It is the right fit when choice input should stay inside the `Form*` wrapper family and the option source is local enough to be represented by `options` or `valueEnum`.
+
+## Use it when
+
+- a form or query schema needs select behavior plus wrapper-managed label, rules, and help text
+- static options can come from `options` or lightweight `valueEnum` mappings
+- the field should expose both `formItem` and select `field` refs together
+- grouped options or common select slots may be useful while keeping wrapper-family behavior
+
+## Prefer something else when
+
+- you are still choosing among several wrapped field families rather than deciding one select field in isolation  
+  → use `../using-form-fields/SKILL.md` or `../building-form-workflows/SKILL.md`
+- you need the raw select component outside the wrapper family  
+  → use `../using-select/SKILL.md`
+- option data is remote-first and lookup-oriented  
+  → use `../using-data-select/SKILL.md`
+- typing should drive callback-based suggestions instead of choosing from a local option set  
+  → use `../using-form-autocomplete/SKILL.md`
+- the choice should stay visible as radios or checkboxes instead of living in a dropdown  
+  → use `../using-form-radio-group/SKILL.md` or `../using-form-checkbox-group/SKILL.md`
+- the field is fundamentally text-like or numeric rather than choice-based  
+  → use `../using-form-text/SKILL.md` or `../using-form-number/SKILL.md`
+
+## Decision guide
+
+Use `FormSelect` if the answer is yes for **two or more** of these:
+
+- Is the field fundamentally a local-choice input?
+- Should the field stay inside the shared form-wrapper family?
+- Are `options` or `valueEnum` enough for the option source?
+- Do you want wrapper and select instance access exposed together?
+- Would grouped options or standard select slots help without moving to a request-aware select?
+
+If not, `Select`, `DataSelect`, or another wrapped field may fit better.
+
+## Start with
+
+1. Decide whether the option source should be `options` or `valueEnum`.
+2. Add the normal `FormItem` props such as `label`, `prop`, and `rules`.
+3. Use grouped options or slots only after the field choice is clearly correct.
+4. Move to `DataSelect` or `Select` if the wrapper boundary or option-loading boundary is different.
+
+## Minimal patterns
+
+### Standard wrapped select
+
+```vue
+<FormSelect label="Status" prop="status" :options="options" />
+```
+
+### Enum-backed wrapped select
+
+Use `valueEnum` when a compact mapping is clearer than an explicit options array.
+
+### Grouped local options
+
+Use grouped options when categories matter but the field should remain local-option-driven.
+
+## Common mistakes
+
+- using `FormSelect` when the select should actually live outside the wrapper family
+- using `FormSelect` for remote lookup behavior that belongs in `DataSelect`
+- forgetting that `valueEnum` is converted into local options by the wrapper
+- overlooking the special `input-label` slot name used to avoid conflicting with wrapper label slots
+
+## 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`
+- Raw local select component: `../using-select/SKILL.md`
+- Request-aware select component: `../using-data-select/SKILL.md`
+- Wrapped autocomplete field: `../using-form-autocomplete/SKILL.md`
+- Wrapped visible choice fields: `../using-form-radio-group/SKILL.md`, `../using-form-checkbox-group/SKILL.md`
+- Text-style wrapped field: `../using-form-text/SKILL.md`
+- Numeric wrapped field: `../using-form-number/SKILL.md`
+
+## References
+
+- Props: `./references/props.md`
+- Examples: `./references/examples.md`
+- Gotchas: `./references/gotchas.md`