@hinen/pro-element-plus 1.7.17 → 1.8.0

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

@@ -0,0 +1,67 @@
+# FormSelect examples
+
+## 1. Standard wrapped select field
+
+Use `FormSelect` when a local-choice field should keep the same wrapper semantics as the rest of a form.
+
+Minimal pattern:
+
+```vue
+<FormSelect label="Status" prop="status" :options="statusOptions" />
+```
+
+Typical fit:
+
+- status selection
+- role selection
+- category pickers with local dictionaries
+
+## 2. Enum-backed wrapped select
+
+Use `valueEnum` when a compact value-to-label mapping is clearer than an explicit options array.
+
+Minimal pattern:
+
+```vue
+<FormSelect label="Mode" prop="mode" :value-enum="modeEnum" />
+```
+
+Typical fit:
+
+- statuses
+- modes
+- small fixed choice sets
+
+## 3. Grouped local choices
+
+Use grouped `options` when categories matter but the field should remain local-option-driven.
+
+Minimal pattern:
+
+```vue
+<FormSelect label="Category" prop="category" :options="groupedOptions" />
+```
+
+Typical fit:
+
+- grouped taxonomies
+- categorized local lists
+- role or permission groups
+
+## 4. Wrapper-family select field
+
+Use `FormSelect` when a reusable form should keep shared wrapper behavior across text, number, and select fields.
+
+Minimal pattern:
+
+```vue
+<FormText label="Title" prop="title" />
+<FormNumber label="Order" prop="order" />
+<FormSelect label="Status" prop="status" :options="statusOptions" />
+```
+
+Typical fit:
+
+- schema-driven forms
+- mixed forms with `FormText` and `FormNumber`
+- admin forms using consistent wrapper semantics

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

@@ -0,0 +1,13 @@
+# FormSelect gotchas
+
+- `FormSelect` is local-option-focused  
+  If option loading is remote-first or lookup-oriented, prefer `../using-data-select/SKILL.md`.
+
+- `valueEnum` becomes local options  
+  It is a convenience input, not a separate remote or dynamic mode.
+
+- Wrapper slots and select slots live at different layers  
+  Use `label` for the form-item layer and `input-label` for the inner select label-rendering slot.
+
+- This wrapper still depends on the local `Select` abstraction  
+  Grouped options, `valueKey`, and slot behavior follow the wrapped select contract, not an unrelated remote-select model.

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

@@ -0,0 +1,87 @@
+# FormSelect props
+
+## Overview
+
+`FormSelect` combines `FormItem` props with the local-option `Select` props and adds `valueEnum` as a compact option source.
+
+Use it when local choice input should stay inside the standard form-wrapper family.
+
+## Minimum setup
+
+Typical useful props:
+
+- `label`
+- `prop`
+- one of `options` or `valueEnum`
+
+Common optional field props:
+
+- `multiple`
+- `filterable`
+- `clearable`
+- `valueKey`
+
+## Core props
+
+### Wrapper props from `FormItem`
+
+Includes wrapper-level props such as:
+
+- `label`
+- `prop`
+- `rules`
+- `required`
+- `tooltip`
+
+### Select props from `Select`
+
+Commonly useful field props include:
+
+- `options`
+- `modelValue`
+- `multiple`
+- `filterable`
+- `clearable`
+- `valueKey`
+
+### `valueEnum`
+
+Compact mapping from value to label.
+
+The wrapper converts this into local select options when `options` is not provided.
+
+## Slots
+
+Useful slots include:
+
+- wrapper-level `label` and `error`
+- select-level `option`, `header`, `footer`, `prefix`, `empty`, `loading`, `tag`
+- `input-label` for the inner select label-rendering slot
+
+The renamed `input-label` slot matters because the wrapper already uses `label` for the form-item layer.
+
+## Instance API
+
+The exposed instance combines:
+
+- `formItem`
+- `field`
+
+## Events
+
+Important events include:
+
+- `update:modelValue`
+- `change`
+- `focus`
+- `blur`
+- `clear`
+- `visible-change`
+- `remove-tag`
+- `popup-scroll`
+
+## Import
+
+```ts
+import { FormSelect } from '@hinen/pro-element-plus';
+```

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

@@ -0,0 +1,81 @@
+---
+name: using-form-switch
+description: Use when a wrapped field should combine FormItem semantics with boolean or on-off switch behavior inside the Form* wrapper family.
+---
+
+# Using FormSwitch
+
+## Overview
+
+Use `FormSwitch` for a **boolean wrapped field** that combines `FormItem` behavior with Element Plus switch behavior.
+
+It fits fields where the value is fundamentally on or off and the field should stay inside the shared form-wrapper family.
+
+## Use it when
+
+- a field represents enabled, disabled, or another binary state
+- you want Element Plus switch behavior plus built-in `FormItem` label and validation handling
+- active and inactive text or loading state are part of the field contract
+- the field should expose both `formItem` and switch `field` refs together
+
+## Prefer something else when
+
+- the field should choose among named options instead of true or false  
+  → use `../using-form-radio-group/SKILL.md`
+- the field should allow many checked values from a list  
+  → use `../using-form-checkbox-group/SKILL.md`
+- you only need wrapper behavior around custom content  
+  → use `../using-form-item/SKILL.md`
+
+## Decision guide
+
+Use `FormSwitch` if the answer is yes for **two or more** of these:
+
+- Is the value fundamentally boolean or binary?
+- Should the UX be toggle-like rather than list-like?
+- Should the field stay inside the shared form-wrapper family?
+- Do you want wrapper validation access and switch instance access together?
+
+If not, `FormRadioGroup`, `FormCheckboxGroup`, or another wrapper may fit better.
+
+## Start with
+
+1. Decide whether the value is truly boolean or just a small named-choice set.
+2. Add the normal `FormItem` props such as `label`, `prop`, and `rules`.
+3. Add switch-specific props such as loading, width, or active or inactive text after the wrapper choice is clear.
+4. Move to radio or checkbox groups if the field is not really a toggle.
+
+## Minimal patterns
+
+### Standard wrapped switch
+
+```vue
+<FormSwitch label="Enabled" prop="enabled" />
+```
+
+### Text-backed toggle
+
+Use active and inactive text when the toggle should read as a product state rather than a raw boolean.
+
+### Loading toggle
+
+Use loading state when the toggle change triggers async work and the field should show that feedback directly.
+
+## Common mistakes
+
+- using `FormSwitch` for named choices that should be radios instead
+- treating a switch like a multi-choice control
+- forgetting that toggle semantics communicate binary state, not one-of-many selection
+
+## Related skills
+
+- 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`
+
+## References
+
+- Props: `./references/props.md`
+- Examples: `./references/examples.md`
+- Gotchas: `./references/gotchas.md`

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

@@ -0,0 +1,54 @@
+# FormSwitch examples
+
+## 1. Standard boolean field
+
+Use `FormSwitch` when the field stores a simple on or off state inside a wrapped form flow.
+
+Minimal pattern:
+
+```vue
+<FormSwitch label="Enabled" prop="enabled" />
+```
+
+Typical fit:
+
+- enabled state
+- publish toggle
+- feature flag setting
+
+## 2. Toggle with state labels
+
+Use active and inactive text when the switch should read as a named product state.
+
+Minimal pattern:
+
+```vue
+<FormSwitch
+  label="Visibility"
+  prop="visible"
+  active-text="Visible"
+  inactive-text="Hidden"
+/>
+```
+
+Typical fit:
+
+- public versus private
+- allow versus deny
+- visible versus hidden
+
+## 3. Async toggle flow
+
+Use loading state when toggling should show in-progress feedback directly on the control.
+
+Minimal pattern:
+
+```vue
+<FormSwitch label="Sync" prop="syncEnabled" :loading="saving" />
+```
+
+Typical fit:
+
+- settings save-on-toggle
+- remote status updates
+- permission toggles

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

@@ -0,0 +1,10 @@
+# FormSwitch gotchas
+
+- Switches communicate binary state  
+  If the user is choosing among named options, `../using-form-radio-group/SKILL.md` is usually clearer.
+
+- Wrapper props and switch props are merged  
+  Keep clear which behavior belongs to the form shell and which belongs to the toggle control.
+
+- Loading and disabled state change the interaction contract  
+  Treat them as part of the field behavior, not just visual polish.

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

@@ -0,0 +1,83 @@
+# FormSwitch props
+
+## Overview
+
+`FormSwitch` combines `FormItem` props with Element Plus switch props.
+
+Use it when binary toggle behavior should stay inside the shared form-wrapper family.
+
+## Minimum setup
+
+A minimal working setup is usually just:
+
+```vue
+<FormSwitch label="Enabled" prop="enabled" />
+```
+
+That is enough when the field stores a true or false value inside a wrapped form flow.
+
+Typical useful props:
+
+- `label`
+- `prop`
+- `modelValue`
+
+Common optional field props:
+
+- `disabled`
+- `loading`
+- active or inactive text
+
+## Core props
+
+### Wrapper props from `FormItem`
+
+Includes wrapper-level props such as:
+
+- `label`
+- `prop`
+- `rules`
+- `required`
+- `tooltip`
+
+### Common switch props
+
+Useful field props include:
+
+- `modelValue`
+- `disabled`
+- `loading`
+- width and icon-related props
+
+Treat `modelValue` as the real stored boolean value for the field, not just a visual state flag.
+
+### Active and inactive presentation props
+
+Use switch text and presentation props when the toggle should communicate explicit product states.
+
+Reach for these only after the field is clearly a binary toggle rather than a radio-style named choice.
+
+## Slots
+
+Useful slots include wrapper-level `label` and `error`, plus switch action-content slots where custom active or inactive visuals matter.
+
+## Instance API
+
+The exposed instance combines:
+
+- `formItem`
+- `field`
+
+## Events
+
+Important events include:
+
+- `update:modelValue`
+- `change`
+- `input`
+
+## Import
+
+```ts
+import { FormSwitch } from '@hinen/pro-element-plus';
+```

package/dist/skills/using-form-tag-input/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: using-form-tag-input
+description: Use when a wrapped field should combine FormItem semantics with editable freeform tag-list behavior inside the Form* wrapper family.
+---
+
+# Using FormTagInput
+
+## Overview
+
+Use `FormTagInput` for a **freeform tag-list wrapped field** that combines `FormItem` behavior with Element Plus input-tag behavior.
+
+It fits fields where users should create, edit, remove, and possibly reorder arbitrary tag values while staying inside the shared form-wrapper family.
+
+## Use it when
+
+- a field collects multiple freeform tags instead of a fixed option list
+- you want input-tag behavior plus built-in `FormItem` labels, rules, and help text
+- max tag count, drag behavior, or custom tag rendering are part of the field contract
+- the field should expose both `formItem` and tag-input `field` refs together
+
+## Prefer something else when
+
+- suggestions should drive the input experience  
+  → use `../using-form-autocomplete/SKILL.md`
+- the choices come from a fixed select list  
+  → use `../using-form-select/SKILL.md`
+- you only need one current text value instead of a tag collection  
+  → use `../using-form-text/SKILL.md`
+
+## Decision guide
+
+Use `FormTagInput` if the answer is yes for **two or more** of these:
+
+- Should the field store many freeform tag values?
+- Do users need to add or remove tags directly inside the control?
+- Should the field stay inside the shared form-wrapper family?
+- Do you want wrapper validation access and tag-input instance access together?
+
+If not, `FormAutocomplete`, `FormSelect`, or another wrapper may fit better.
+
+## Start with
+
+1. Decide whether the field is freeform tags, a suggested single value, or a fixed choice set.
+2. Add the normal `FormItem` props such as `label`, `prop`, and `rules`.
+3. Add tag-input props such as `max`, `clearable`, or drag behavior after the wrapper choice is clear.
+4. Use autocomplete or select wrappers instead if the field is not really a tag collection.
+
+## Minimal patterns
+
+### Standard wrapped tag input
+
+```vue
+<FormTagInput label="Tags" prop="tags" />
+```
+
+### Max-tag or trigger-controlled input
+
+Use props like `max` or `trigger` when the product flow constrains tag creation.
+
+### Custom tag rendering
+
+Use the `tag` slot when each tag needs richer visual treatment than the default tag shell.
+
+## Common mistakes
+
+- using `FormTagInput` when the field should really be one suggested value from autocomplete
+- using it for a fixed option list that should be modeled as a select-style field
+- forgetting that this field stores a list of values, not one current string
+
+## 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 autocomplete: `../using-form-autocomplete/SKILL.md`
+- Wrapped local select: `../using-form-select/SKILL.md`
+- Wrapped text field: `../using-form-text/SKILL.md`
+
+## References
+
+- Props: `./references/props.md`
+- Examples: `./references/examples.md`
+- Gotchas: `./references/gotchas.md`

package/dist/skills/using-form-tag-input/references/examples.md

@@ -0,0 +1,53 @@
+# FormTagInput examples
+
+## 1. Standard freeform tag field
+
+Use `FormTagInput` when users should add and remove many arbitrary values inside a wrapped form flow.
+
+Minimal pattern:
+
+```vue
+<FormTagInput label="Tags" prop="tags" />
+```
+
+Typical fit:
+
+- labels
+- keywords
+- topics
+
+## 2. Constrained tag entry
+
+Use props like `max` or custom triggers when product rules constrain how tags are created.
+
+Minimal pattern:
+
+```vue
+<FormTagInput label="Keywords" prop="keywords" :max="5" />
+```
+
+Typical fit:
+
+- limited tag counts
+- special separator triggers
+- controlled metadata entry
+
+## 3. Custom tag rendering
+
+Use the `tag` slot when each tag should render with custom visuals or metadata.
+
+Minimal pattern:
+
+```vue
+<FormTagInput label="Labels" prop="labels">
+  <template #tag="{ item }">
+    <span>{{ item }}</span>
+  </template>
+</FormTagInput>
+```
+
+Typical fit:
+
+- colored tags
+- tags with status indicators
+- tags with branded treatment

package/dist/skills/using-form-tag-input/references/gotchas.md

@@ -0,0 +1,13 @@
+# FormTagInput gotchas
+
+- `FormTagInput` stores a list of values  
+  If the field should hold one current value with suggestions, use `../using-form-autocomplete/SKILL.md`.
+
+- Freeform tags and fixed choices are different field contracts  
+  If the option set is known, `../using-form-select/SKILL.md` is usually clearer.
+
+- Wrapper props and input-tag props are merged  
+  Keep clear which behavior belongs to the form shell and which belongs to tag-entry behavior.
+
+- Tag count rules and uniqueness rules are part of field meaning  
+  If max count, duplicate handling, or editing triggers matter, treat them as part of the field contract rather than as cosmetic tuning.

package/dist/skills/using-form-tag-input/references/props.md

@@ -0,0 +1,80 @@
+# FormTagInput props
+
+## Overview
+
+`FormTagInput` combines `FormItem` props with Element Plus input-tag props.
+
+Use it when editable tag-list behavior should stay inside the shared form-wrapper family.
+
+## Minimum setup
+
+Typical useful props:
+
+- `label`
+- `prop`
+- `modelValue`
+
+Common optional field props:
+
+- `max`
+- `clearable`
+- `draggable`
+- `trigger`
+
+## Core props
+
+### Wrapper props from `FormItem`
+
+Includes wrapper-level props such as:
+
+- `label`
+- `prop`
+- `rules`
+- `required`
+- `tooltip`
+
+### Common input-tag props
+
+Useful field props include:
+
+- `modelValue`
+- `max`
+- `min`
+- uniqueness-related behavior
+- `clearable`
+- `draggable`
+- `autofocus`
+
+## Slots
+
+Useful slots include wrapper-level `label` and `error`, plus tag-input slots such as:
+
+- `tag`
+- `prefix`
+- `suffix`
+
+## Instance API
+
+The exposed instance combines:
+
+- `formItem`
+- `field`
+
+## Events
+
+Important events include:
+
+- `update:modelValue`
+- `change`
+- `input`
+- `focus`
+- `blur`
+- `clear`
+- `remove-tag`
+- `add-tag`
+
+## Import
+
+```ts
+import { FormTagInput } from '@hinen/pro-element-plus';
+```