@hinen/pro-element-plus 1.7.17 → 1.8.1

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

@@ -0,0 +1,101 @@
+---
+name: using-form-fields
+description: Use when choosing among the package’s Form* field wrappers or mapping schema-driven field intent to the right wrapper component.
+---
+
+# Using FormFields
+
+## Overview
+
+Use `FormFields` as the **family-level router** for the package’s wrapped field components.
+
+This skill is not about one component with one prop surface. It is about deciding which `Form*` wrapper matches a schema-driven or form-driven need before you pick a concrete field such as `FormText`, `FormNumber`, or `FormSelect`.
+
+## Use it when
+
+- you need the map of available form wrappers
+- you are building a schema-driven form and want consistent wrapper behavior
+- you need to jump from a `valueType` to the matching `Form*` component
+- you are choosing between wrapper-level composition and raw field components
+- you want the shared mental model before selecting a specific wrapped field
+
+## Prefer something else when
+
+- you are still deciding whether the broader workflow is a business form, query page, or another page shell  
+  → use `../building-form-workflows/SKILL.md` or the top-level router first
+- you already know the exact field wrapper you need  
+  → use that concrete skill directly
+- you only need the base wrapper semantics  
+  → use `../using-form-item/SKILL.md`
+- you are choosing page-level query composition rather than field wrappers  
+  → use `../using-query-form/SKILL.md`
+
+## Decision guide
+
+Use `FormFields` if the answer is yes for **two or more** of these:
+
+- Are you still choosing which wrapped field type fits best?
+- Do you need to map schema intent to a concrete `Form*` component?
+- Do multiple field wrappers need to share the same wrapper semantics?
+- Are you trying to understand the boundary between `FormItem` and the higher-level wrapped fields?
+
+If not, go straight to the concrete field skill.
+
+## Start with
+
+1. Decide whether you need the base wrapper only or a concrete wrapped field.
+2. Choose the stored value shape first.
+3. Map that value shape to a field family member.
+4. Only then refine field-specific props.
+
+## Minimal patterns
+
+### Family-level wrapper selection
+
+Use this skill to move from intent to wrapper choice:
+
+- text-like input → `../using-form-text/SKILL.md`
+- numeric stepping or bounds → `../using-form-number/SKILL.md`
+- local dropdown choice → `../using-form-select/SKILL.md`
+- visible single choice → `../using-form-radio-group/SKILL.md`
+- visible multi choice → `../using-form-checkbox-group/SKILL.md`
+- binary toggle → `../using-form-switch/SKILL.md`
+- suggestion-driven text entry → `../using-form-autocomplete/SKILL.md`
+- date-like or time-like values → `../using-form-date-picker/SKILL.md`, `../using-form-time-picker/SKILL.md`
+- hierarchical path or tree choice → `../using-form-cascade-select/SKILL.md`, `../using-form-tree-select/SKILL.md`
+- freeform tags or tag collections → `../using-form-tag-input/SKILL.md`
+- bounded rating input → `../using-form-rate/SKILL.md`
+- custom control with only wrapper semantics → `../using-form-item/SKILL.md`
+
+### QueryForm valueType mapping
+
+Use this family as the conceptual backing for `QueryForm.items` when `valueType` should correspond to a known wrapped field behavior.
+
+## Common mistakes
+
+- treating `FormFields` like one monolithic component
+- choosing the family entry point when the exact wrapper is already obvious
+- thinking every wrapped field has the same field-level props just because the wrapper contract is shared
+- skipping the wrapper-family decision and mixing raw fields with wrapped fields inconsistently
+
+## Related skills
+
+- Business-form workflow router above this family: `../building-form-workflows/SKILL.md`
+- Base wrapper semantics: `../using-form-item/SKILL.md`
+- Text-style wrapped field: `../using-form-text/SKILL.md`
+- Number-style wrapped field: `../using-form-number/SKILL.md`
+- Select-style wrapped field: `../using-form-select/SKILL.md`
+- Wrapped single-choice field: `../using-form-radio-group/SKILL.md`
+- Wrapped multi-choice field: `../using-form-checkbox-group/SKILL.md`
+- Wrapped binary toggle: `../using-form-switch/SKILL.md`
+- Suggestion-driven wrapped field: `../using-form-autocomplete/SKILL.md`
+- Wrapped date and time fields: `../using-form-date-picker/SKILL.md`, `../using-form-time-picker/SKILL.md`
+- Wrapped hierarchical selectors: `../using-form-cascade-select/SKILL.md`, `../using-form-tree-select/SKILL.md`
+- Wrapped tag and rating fields: `../using-form-tag-input/SKILL.md`, `../using-form-rate/SKILL.md`
+- Query-schema form shell: `../using-query-form/SKILL.md`
+
+## References
+
+- Props: `./references/props.md`
+- Examples: `./references/examples.md`
+- Gotchas: `./references/gotchas.md`

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

@@ -0,0 +1,45 @@
+# FormFields examples
+
+## 1. Query field selection
+
+Use this family as the backing model for `QueryForm.items` when a field’s `valueType` should map to a known wrapper behavior.
+
+Typical route:
+
+- text-like query field → `FormText`
+- numeric query field → `FormNumber`
+- local-choice query field → `FormSelect`
+
+Typical fit:
+
+- schema-driven filter forms
+- shared field definitions across tabs or modules
+- consistent wrapper behavior across generated forms
+
+## 2. Schema-driven business form
+
+Start with `FormItem` semantics, then pick the concrete `Form*` wrapper that matches the stored value.
+
+Minimal pattern:
+
+```vue
+<FormText label="Title" prop="title" />
+<FormNumber label="Order" prop="order" />
+<FormSelect label="Status" prop="status" :options="statusOptions" />
+```
+
+Typical fit:
+
+- admin edit forms
+- settings forms with mixed value shapes
+- reusable field configuration layers
+
+## 3. Base wrapper versus concrete wrapper choice
+
+Use this family view when you know the field belongs in a business form, but you still need to decide whether it should stay a base wrapper or move into a concrete `Form*` field.
+
+Typical fit:
+
+- custom upload or bespoke control that only needs `FormItem` semantics
+- text, number, or select field that should reuse an existing wrapped component
+- schema-driven form where some fields use standard wrappers and one field stays custom

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

@@ -0,0 +1,6 @@
+# FormFields gotchas
+
+- `FormFields` is a family entry point, not one monolithic field with a huge prop surface.
+- Every concrete `Form*` wrapper combines the underlying input props with `FormItem` behavior.
+- Shared wrapper semantics do not mean identical field props across the whole family.
+- If you already know the exact wrapped field you need, go to that concrete skill instead of staying at the family level.

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

@@ -0,0 +1,57 @@
+# FormFields family
+
+## Overview
+
+`FormFields` is an exported family of wrapped field components, not a single component.
+
+All members share the same basic pattern:
+
+- wrapper behavior from `FormItem`
+- field behavior from an underlying concrete input component
+
+## Included wrappers
+
+Currently exported family members include:
+
+- `FormText`
+- `FormNumber`
+- `FormSelect`
+- `FormCheckboxGroup`
+- `FormRadioGroup`
+- `FormSwitch`
+- `FormCascadeSelect`
+- `FormDatePicker`
+- `FormTimePicker`
+- `FormTagInput`
+- `FormTreeSelect`
+- `FormRate`
+- `FormAutocomplete`
+- `FormItem`
+
+## Family shape
+
+Most concrete `Form*` wrappers combine:
+
+- form-item props such as `label`, `prop`, `rules`, and `tooltip`
+- field-specific props from the wrapped control
+- slot pass-through for both wrapper and field concerns
+- an exposed instance shaped as `{ formItem, field }`
+
+## When this matters
+
+Use this family view when:
+
+- mapping schema intent to a concrete wrapper
+- deciding whether wrapper semantics should stay consistent across a form
+- choosing between base `FormItem` and a specific wrapped field
+
+## Import
+
+```ts
+import {
+  FormItem,
+  FormText,
+  FormNumber,
+  FormSelect,
+} from '@hinen/pro-element-plus';
+```

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

@@ -0,0 +1,92 @@
+---
+name: using-form-item
+description: Use when wrapper-level label, validation, tooltip, and error-display behavior matter more than the inner field control, especially inside the Form* wrapper family.
+---
+
+# Using FormItem
+
+## Overview
+
+Use `FormItem` as the **base wrapper abstraction** for the `Form*` field family when label rendering, validation state, tooltip behavior, and error presentation matter more than the specific input control inside.
+
+It is the wrapper contract that the rest of the form-foundation skills build on. Reach for it when you need custom content inside a standard form-item shell or when you need to understand what the higher-level `Form*` wrappers are adding.
+
+## Use it when
+
+- you need wrapper-level label, validation, and tooltip behavior around custom content
+- you want the base mental model used by the rest of the `Form*` wrapper family
+- the field control is custom, but the label and validation shell should stay standard
+- you need the truncated expandable error behavior provided by this wrapper
+- parent code needs a direct form-item instance rather than a combined field wrapper
+
+## Prefer something else when
+
+- you are still routing at the business-form workflow level and have not yet decided whether the field should stay custom or use a standard wrapper  
+  → use `../building-form-workflows/SKILL.md`
+- you need the full wrapper family map first  
+  → use `../using-form-fields/SKILL.md`
+- you already know the concrete wrapped field you need  
+  → use one of `../using-form-text/SKILL.md`, `../using-form-number/SKILL.md`, or `../using-form-select/SKILL.md`
+- you need query-schema routing rather than a single form-item shell  
+  → use `../using-query-form/SKILL.md`
+
+## Decision guide
+
+Use `FormItem` if the answer is yes for **two or more** of these:
+
+- Is the wrapper behavior more important than the input component?
+- Do you need a custom child control inside a standard form-item shell?
+- Should tooltip, label, and validation behavior stay consistent with the `Form*` family?
+- Do you need direct access to form-item instance methods like `validate()` or `clearValidate()`?
+
+If not, a concrete `Form*` field wrapper is usually the better fit.
+
+## Start with
+
+1. Decide whether you truly need a custom inner control.
+2. Pass normal form-item props such as `label`, `prop`, `rules`, and `required`.
+3. Add `tooltip` only when label help is part of the field contract.
+4. Use a concrete `Form*` wrapper instead if the inner field is already standard.
+
+## Minimal patterns
+
+### Base wrapper around custom content
+
+```vue
+<FormItem label="Project Name" prop="name" :rules="rules.name">
+  <ElInput v-model="form.name" />
+</FormItem>
+```
+
+### Tooltip-backed label
+
+Use `tooltip` when label help should stay attached to the wrapper rather than the field body.
+
+### Instance-oriented wrapper usage
+
+Use the exposed form-item instance when parent code needs:
+
+- `validate()`
+- `clearValidate()`
+- `resetField()`
+
+## Common mistakes
+
+- using `FormItem` directly when a concrete `Form*` wrapper would be clearer
+- treating it as if it manages field value behavior by itself
+- forgetting that the main value of this component is the wrapper shell, not the inner control
+- assuming the custom error rendering behaves exactly like plain Element Plus form-item output
+
+## Related skills
+
+- Business-form router above this wrapper layer: `../building-form-workflows/SKILL.md`
+- Wrapper-family selection: `../using-form-fields/SKILL.md`
+- Text-style wrapped field: `../using-form-text/SKILL.md`
+- Number-style wrapped field: `../using-form-number/SKILL.md`
+- Select-style wrapped field: `../using-form-select/SKILL.md`
+
+## References
+
+- Props: `./references/props.md`
+- Examples: `./references/examples.md`
+- Gotchas: `./references/gotchas.md`

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

@@ -0,0 +1,59 @@
+# FormItem examples
+
+## 1. Wrapper around a custom control
+
+Use `FormItem` when the field UI is custom but the label, validation, and error shell should stay standard.
+
+Minimal pattern:
+
+```vue
+<FormItem label="Members" prop="members">
+  <MemberPicker v-model="members" />
+</FormItem>
+```
+
+Typical fit:
+
+- custom composite controls
+- third-party inputs placed inside a normal form shell
+- feature-specific widgets that still belong to a standard form
+
+Recommended pattern:
+
+- keep the custom control in the default slot
+- let `FormItem` handle label, rules, and error state
+
+## 2. Base model for the Form\* family
+
+Use `FormItem` as the mental model for understanding higher-level wrappers like `FormText`, `FormNumber`, and `FormSelect`.
+
+Minimal pattern:
+
+```vue
+<FormText label="Name" prop="name" />
+```
+
+This is the wrapped-field version of keeping the same label, rule, and error shell.
+
+Typical fit:
+
+- deciding whether to use the base wrapper or a concrete wrapped field
+- understanding where tooltip and label behavior comes from
+
+## 3. Tooltip-backed label behavior
+
+Use `tooltip` when field help belongs next to the label rather than inside helper text or placeholder copy.
+
+Minimal pattern:
+
+```vue
+<FormItem label="API Key" prop="apiKey" tooltip="Use the server-issued key.">
+  <Input v-model="apiKey" />
+</FormItem>
+```
+
+Typical fit:
+
+- policy explanations
+- field-specific format hints
+- admin forms with ambiguous labels

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

@@ -0,0 +1,13 @@
+# FormItem gotchas
+
+- `FormItem` is only the wrapper shell  
+  It does not choose or manage the inner field component for you.
+
+- `htmlFor` replaces the raw `for` prop name  
+  Use `htmlFor` when you need explicit label-to-input binding.
+
+- `tooltip` is wrapper-level behavior  
+  Put label help here only when it belongs to the label contract, not when it should live in field content.
+
+- Error rendering is customized  
+  This wrapper truncates long errors and expands them on hover, so do not assume the plain Element Plus visual behavior.

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

@@ -0,0 +1,85 @@
+# FormItem props
+
+## Overview
+
+`FormItem` extends the Element Plus form-item contract and adds two important wrapper-level capabilities:
+
+- `htmlFor` as the explicit label-to-field binding prop
+- `tooltip` for label help content
+
+It also customizes error rendering and exposes the underlying form-item instance methods.
+
+## Minimum setup
+
+Typical useful props:
+
+- `label`
+- `prop`
+- `rules`
+- `required`
+
+Optional wrapper enhancements:
+
+- `tooltip`
+- `htmlFor`
+
+## Core props
+
+### Standard form-item props
+
+`FormItem` keeps the normal Element Plus form-item surface, including commonly used props such as:
+
+- `prop`
+- `label`
+- `labelPosition`
+- `rules`
+- `required`
+- `error`
+- `validateStatus`
+
+### `htmlFor`
+
+Wrapper alias for the label `for` binding.
+
+Use this when the label should point to an inner input element explicitly.
+
+### `tooltip`
+
+Accepts:
+
+- a simple string
+- a partial tooltip-props object
+
+Use this when label help should be rendered next to the field label.
+
+## Slots
+
+Useful wrapper slots:
+
+- default
+- `label`
+- `error`
+
+These are the same extension points the higher-level `Form*` wrappers compose around.
+
+## Instance API
+
+Exposed form-item instance behavior includes:
+
+- `validate()`
+- `clearValidate()`
+- `resetField()`
+- `size`
+- `validateMessage`
+- `validateState`
+
+## Import
+
+```ts
+import { FormItem } from '@hinen/pro-element-plus';
+```
+
+## Notes
+
+- This component is the base wrapper for the `Form*` field family.
+- It does not manage field value behavior on its own; the inner control still owns that part.

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

@@ -0,0 +1,82 @@
+---
+name: using-form-number
+description: Use when a wrapped field needs numeric step, bounds, or precision behavior while keeping the shared FormItem shell and combined formItem-plus-field instance shape.
+---
+
+# Using FormNumber
+
+## Overview
+
+Use `FormNumber` for a **numeric wrapped field** that combines `FormItem` wrapper behavior with Element Plus input-number behavior.
+
+It is the right fit when the field needs true numeric control semantics such as stepping, bounds, or precision, not just a text input that happens to accept numbers.
+
+## Use it when
+
+- a schema-driven field must enforce numeric stepping, bounds, or precision
+- you want Element Plus input-number behavior plus `FormItem` labels and rules
+- the field should expose both `formItem` and numeric `field` refs together
+- wrapper-level tooltip, label, and error behavior should stay consistent with the rest of the form family
+
+## Prefer something else when
+
+- you need freeform text, password, or textarea input  
+  → use `../using-form-text/SKILL.md`
+- you need select-style choice input  
+  → use `../using-form-select/SKILL.md`
+- you only need wrapper behavior around custom content  
+  → use `../using-form-item/SKILL.md`
+
+## Decision guide
+
+Use `FormNumber` if the answer is yes for **two or more** of these:
+
+- Should the value behave like a real numeric control rather than freeform text?
+- Do step, min, max, or precision rules matter to normal usage?
+- Should the field stay inside the shared form-wrapper family?
+- Do you need both wrapper validation access and numeric-field instance access?
+
+If not, `FormText` or another wrapper is probably a better fit.
+
+## Start with
+
+1. Decide the numeric contract first: bounds, step, and precision.
+2. Add the normal `FormItem` props such as `label`, `prop`, and `rules`.
+3. Pass numeric-control props only after the wrapper fit is clear.
+4. Use a text wrapper instead if the value is not truly numeric in behavior.
+
+## Minimal patterns
+
+### Standard wrapped number field
+
+```vue
+<FormNumber label="Quantity" prop="quantity" :min="0" :step="1" />
+```
+
+### Precision-aware numeric field
+
+Use `precision` when decimal behavior is part of the field contract.
+
+### Range-bounded numeric field
+
+Use `min` and `max` when bounds are part of normal user guidance, not only a final validation rule.
+
+## Common mistakes
+
+- using `FormNumber` when the feature really wants freeform numeric text input
+- forgetting that this wrapper combines both form-item props and input-number props
+- treating `min`, `max`, or `step` as optional styling hints instead of core numeric behavior
+- manually composing `FormItem` and `ElInputNumber` when the standard wrapper already fits
+
+## Related skills
+
+- Wrapper-family selection: `../using-form-fields/SKILL.md`
+- Base wrapper only: `../using-form-item/SKILL.md`
+- Text-style wrapped field: `../using-form-text/SKILL.md`
+- Select-style wrapped field: `../using-form-select/SKILL.md`
+
+## References
+
+- Props: `./references/props.md`
+- Examples: `./references/examples.md`
+- Gotchas: `./references/gotchas.md`

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

@@ -0,0 +1,66 @@
+# FormNumber examples
+
+## 1. Quantity or count field
+
+Use `FormNumber` when the value is inherently numeric and stepping is part of the normal interaction.
+
+Minimal pattern:
+
+```vue
+<FormNumber label="Count" prop="count" />
+```
+
+Typical fit:
+
+- quantity
+- sort order
+- retry count
+- item limits
+
+## 2. Precision-aware numeric input
+
+Use `precision` when decimals are part of the field contract.
+
+Minimal pattern:
+
+```vue
+<FormNumber label="Rate" prop="rate" :precision="2" />
+```
+
+Typical fit:
+
+- rates
+- percentages
+- decimal thresholds
+
+## 3. Range-bounded numeric field
+
+Use `min` and `max` when the field should communicate allowed bounds directly through the control.
+
+Minimal pattern:
+
+```vue
+<FormNumber label="Age" prop="age" :min="18" :max="99" />
+```
+
+Typical fit:
+
+- age limits
+- pagination size settings
+- configurable thresholds
+
+## 4. Wrapper-family numeric field
+
+Use `FormNumber` when a schema-driven or reusable form should keep the same wrapper semantics as sibling fields.
+
+Minimal pattern:
+
+```vue
+<FormNumber label="Retry Count" prop="retryCount" />
+```
+
+Typical fit:
+
+- shared admin forms
+- generated form schemas
+- mixed forms using `FormText`, `FormNumber`, and `FormSelect` together

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

@@ -0,0 +1,13 @@
+# FormNumber gotchas
+
+- `FormNumber` is for numeric control semantics, not just numeric-looking text  
+  If freeform input is acceptable, `../using-form-text/SKILL.md` may be a better fit.
+
+- Wrapper props and field props are merged  
+  Keep clear which behavior comes from the form shell and which comes from the numeric control.
+
+- The exposed instance is split into `formItem` and `field`  
+  Validation methods live on `formItem`; numeric-field behavior lives on `field`.
+
+- Bounds and stepping are part of the abstraction  
+  If `min`, `max`, or `step` are central to the feature, document them intentionally rather than treating them as minor options.