@hinen/pro-element-plus 1.7.17 → 1.8.0

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

@@ -0,0 +1,82 @@
+---
+name: using-form-text
+description: Use when a wrapped field should combine FormItem semantics with text-like Element Plus input behavior such as plain text, password, textarea, or simple numeric text entry.
+---
+
+# Using FormText
+
+## Overview
+
+Use `FormText` for a **text-style wrapped field** that combines `FormItem` wrapper behavior with Element Plus input behavior.
+
+It is the right abstraction when text-like entry should stay inside the `Form*` wrapper family instead of composing `FormItem` and `ElInput` manually every time.
+
+## Use it when
+
+- a form schema needs text, password, or textarea input with built-in label and validation behavior
+- you want one wrapper to expose both input props and `FormItem` props
+- the field should expose both `formItem` and `field` refs through one instance
+- wrapper-level tooltip, label, or error behavior should stay consistent with the rest of the form family
+
+## Prefer something else when
+
+- you need step-based numeric input with numeric control semantics  
+  → use `../using-form-number/SKILL.md`
+- you need select-style choice behavior  
+  → use `../using-form-select/SKILL.md`
+- you only need wrapper behavior around custom content  
+  → use `../using-form-item/SKILL.md`
+
+## Decision guide
+
+Use `FormText` if the answer is yes for **two or more** of these:
+
+- Is the stored value fundamentally text-like?
+- Should the field support modes like plain text, password, or textarea?
+- Do you want the wrapper and input refs exposed together?
+- Should label, rules, tooltip, and error rendering come from the shared form-wrapper family?
+
+If not, another concrete `Form*` wrapper is probably a better fit.
+
+## Start with
+
+1. Decide whether the field is plain text, password, textarea, or a simple input `type` variation.
+2. Add the normal `FormItem` props such as `label`, `prop`, and `rules`.
+3. Pass `ElInput`-style props only after the wrapper fit is clear.
+4. Use slots only when the built-in text field shell is not enough.
+
+## Minimal patterns
+
+### Standard wrapped text input
+
+```vue
+<FormText label="Name" prop="name" placeholder="Please enter" />
+```
+
+### Password mode
+
+Use `type="password"` when the field is still text-like but needs password behavior.
+
+### Textarea mode
+
+Use `type="textarea"` when the field should stay in the text-wrapper family but needs multi-line editing.
+
+## Common mistakes
+
+- using `FormText` for step-based numeric control when `FormNumber` is the better fit
+- forgetting that this wrapper mixes both `FormItem` props and input props
+- assuming every `ElInput` event is exhaustively documented by the wrapper examples
+- reaching for manual `FormItem` plus `ElInput` composition when the standard wrapper already fits
+
+## Related skills
+
+- Wrapper-family selection: `../using-form-fields/SKILL.md`
+- Base wrapper only: `../using-form-item/SKILL.md`
+- Numeric wrapped field: `../using-form-number/SKILL.md`
+- Select 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-text/references/examples.md

@@ -0,0 +1,66 @@
+# FormText examples
+
+## 1. Standard wrapped text field
+
+Use `FormText` when a normal text input should inherit the wrapper-family label, tooltip, and validation behavior.
+
+Minimal pattern:
+
+```vue
+<FormText label="Name" prop="name" />
+```
+
+Typical fit:
+
+- names
+- titles
+- identifiers
+- short descriptions
+
+## 2. Password field inside the wrapper family
+
+Use `type="password"` and related input props when the field is still text-like but needs hidden input behavior.
+
+Minimal pattern:
+
+```vue
+<FormText label="Password" prop="password" type="password" />
+```
+
+Typical fit:
+
+- password creation
+- secret entry
+- temporary token input
+
+## 3. Textarea field inside the wrapper family
+
+Use `type="textarea"` when the field should stay in the same wrapper family but needs multi-line entry.
+
+Minimal pattern:
+
+```vue
+<FormText label="Notes" prop="notes" type="textarea" />
+```
+
+Typical fit:
+
+- notes
+- comments
+- longer descriptions
+
+## 4. Instance-oriented field control
+
+Use the combined `{ formItem, field }` instance when parent code needs both wrapper validation access and direct input control.
+
+Minimal pattern:
+
+```vue
+<FormText ref="nameField" label="Name" prop="name" />
+```
+
+Typical fit:
+
+- manual focus after validation
+- explicit validation triggers from toolbar actions
+- form helpers that need the wrapped input ref

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

@@ -0,0 +1,13 @@
+# FormText gotchas
+
+- `FormText` mixes wrapper props and input props  
+  Keep clear which settings belong to the form-item shell versus the inner input.
+
+- Not every numeric-looking field should use `FormText`  
+  If the feature needs step, bounds, or numeric control semantics, prefer `../using-form-number/SKILL.md`.
+
+- Styling can target different layers  
+  Use wrapper classes for shell styling and `inputStyle` or `inputClass` for the inner input element.
+
+- The exposed instance is split into `formItem` and `field`  
+  Validation methods live on `formItem`; direct input methods such as focus live on `field`.

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

@@ -0,0 +1,98 @@
+# FormText props
+
+## Overview
+
+`FormText` combines `FormItem` props with Element Plus input props.
+
+Use it when text-like field behavior should live inside the standard form-wrapper family instead of manually composing `FormItem` and `ElInput`.
+
+## Minimum setup
+
+Typical useful props:
+
+- `label`
+- `prop`
+- `modelValue`
+- `placeholder`
+
+Mode-specific optional props:
+
+- `type`
+- `showPassword`
+- `rows`
+- `clearable`
+
+## Core props
+
+### Wrapper props from `FormItem`
+
+Includes wrapper-level props such as:
+
+- `label`
+- `prop`
+- `rules`
+- `required`
+- `tooltip`
+- `htmlFor`
+
+### Text-field props from `ElInput`
+
+Commonly useful field props include:
+
+- `modelValue`
+- `type`
+- `placeholder`
+- `clearable`
+- `maxlength`
+- `showWordLimit`
+- `readonly`
+- `autofocus`
+
+### `inputStyle` and `inputClass`
+
+Use these to style the inner input element rather than the outer wrapper shell.
+
+### `min`, `max`, and `step`
+
+Use these only for simple numeric-text input cases.
+
+If the field really needs step-based numeric control semantics such as bounded stepping, precision, or true numeric input behavior, prefer `../using-form-number/SKILL.md` instead.
+
+## Slots
+
+The wrapper supports both wrapper-level and input-level slots.
+
+Useful examples include:
+
+- `label`
+- `error`
+- `prepend`
+- `append`
+- `prefix`
+- `suffix`
+
+## Instance API
+
+The exposed instance combines:
+
+- `formItem`
+- `field`
+
+Use this when parent code needs both wrapper validation methods and direct input methods such as focus.
+
+## Events
+
+`FormText` keeps the main Element Plus input events, including:
+
+- `update:modelValue`
+- `change`
+- `input`
+- `focus`
+- `blur`
+- `clear`
+
+## Import
+
+```ts
+import { FormText } from '@hinen/pro-element-plus';
+```

package/dist/skills/using-form-time-picker/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: using-form-time-picker
+description: Use when a wrapped field should combine FormItem semantics with time or time-range picking behavior inside the Form* wrapper family.
+---
+
+# Using FormTimePicker
+
+## Overview
+
+Use `FormTimePicker` for a **time-oriented wrapped field** that combines `FormItem` behavior with Element Plus time picker behavior.
+
+It fits fields where the value is time-like or time-range-like and the field should stay inside the same wrapper family as sibling fields.
+
+## Use it when
+
+- a field captures time values or time ranges
+- you want time-picker behavior plus built-in `FormItem` label and validation support
+- disabled-time callbacks or range behavior are part of the field contract
+- the field should expose both `formItem` and time-picker `field` refs together
+
+## Prefer something else when
+
+- the field needs date or date-range semantics  
+  → use `../using-form-date-picker/SKILL.md`
+- you only need wrapper behavior around custom content  
+  → use `../using-form-item/SKILL.md`
+
+## Decision guide
+
+Use `FormTimePicker` if the answer is yes for **two or more** of these:
+
+- Is the stored value fundamentally time-like rather than date-like?
+- Do time range or disabled-time rules matter to normal usage?
+- Should the field stay inside the shared form-wrapper family?
+- Do you want wrapper validation access and time-picker instance access together?
+
+If not, `FormDatePicker` or another wrapper is probably a better fit.
+
+## Start with
+
+1. Decide whether the field is single-time or range-based.
+2. Add the normal `FormItem` props such as `label`, `prop`, and `rules`.
+3. Add time-specific props such as `isRange` or disabled-time callbacks after the wrapper choice is clear.
+4. Use date-oriented wrappers instead if the value is not time-only.
+
+## Minimal patterns
+
+### Standard wrapped time field
+
+```vue
+<FormTimePicker label="Start Time" prop="startTime" />
+```
+
+### Time range field
+
+Use `isRange` when the field stores a start and end time together.
+
+### Limited-time field
+
+Use disabled hour or minute callbacks when the valid time window matters to the product flow.
+
+## Common mistakes
+
+- using `FormTimePicker` when the field is really date-oriented
+- forgetting that time range fields have a different value contract than single-time fields
+- mixing wrapper concerns and field concerns without deciding the time contract first
+
+## Related skills
+
+- Wrapper-family selection: `../using-form-fields/SKILL.md`
+- Base wrapper only: `../using-form-item/SKILL.md`
+- Wrapped date picker: `../using-form-date-picker/SKILL.md`
+
+## References
+
+- Props: `./references/props.md`
+- Examples: `./references/examples.md`
+- Gotchas: `./references/gotchas.md`

package/dist/skills/using-form-time-picker/references/examples.md

@@ -0,0 +1,53 @@
+# FormTimePicker examples
+
+## 1. Standard time field
+
+Use `FormTimePicker` when the field stores one time-like value inside a wrapped form flow.
+
+Minimal pattern:
+
+```vue
+<FormTimePicker label="Start Time" prop="startTime" />
+```
+
+Typical fit:
+
+- start time
+- opening time
+- reminder time
+
+## 2. Time range field
+
+Use `isRange` when the field stores a start and end time together.
+
+Minimal pattern:
+
+```vue
+<FormTimePicker label="Hours" prop="hours" is-range />
+```
+
+Typical fit:
+
+- opening hours
+- meeting windows
+- service availability blocks
+
+## 3. Limited-time selection
+
+Use disabled hour, minute, or second callbacks when the valid time window is constrained by product rules.
+
+Minimal pattern:
+
+```vue
+<FormTimePicker
+  label="Appointment Time"
+  prop="appointmentTime"
+  :disabled-hours="disabledHours"
+/>
+```
+
+Typical fit:
+
+- business-hour selection
+- appointment boundaries
+- restricted booking slots

package/dist/skills/using-form-time-picker/references/gotchas.md

@@ -0,0 +1,10 @@
+# FormTimePicker gotchas
+
+- Time-only and date-oriented fields are different wrapper choices  
+  Use `../using-form-date-picker/SKILL.md` when calendar semantics matter.
+
+- `isRange` changes the field contract  
+  A time range is not just a single time with extra placeholders.
+
+- Disabled-time callbacks are core behavior  
+  Treat them as part of the field semantics, not just visual polish.

package/dist/skills/using-form-time-picker/references/props.md

@@ -0,0 +1,89 @@
+# FormTimePicker props
+
+## Overview
+
+`FormTimePicker` combines `FormItem` props with Element Plus time picker props.
+
+Use it when time and time-range semantics should stay inside the shared form-wrapper family.
+
+## Minimum setup
+
+A minimal working setup is usually just:
+
+```vue
+<FormTimePicker label="Start Time" prop="startTime" />
+```
+
+That is enough when the field stores one time-like value inside a wrapped form flow.
+
+Typical useful props:
+
+- `label`
+- `prop`
+- `modelValue`
+
+Common optional field props:
+
+- `isRange`
+- `placeholder`
+- `startPlaceholder`
+- `endPlaceholder`
+
+## Core props
+
+### Wrapper props from `FormItem`
+
+Includes wrapper-level props such as:
+
+- `label`
+- `prop`
+- `rules`
+- `required`
+- `tooltip`
+
+### Time-picker props
+
+Useful field props include:
+
+- `isRange`
+- `modelValue`
+- `placeholder`
+- `rangeSeparator`
+- `startPlaceholder`
+- `endPlaceholder`
+- `arrowControl`
+- `valueFormat`
+
+`modelValue` is the current stored time value or time-range value for the field. `valueFormat` matters when the parent expects a specific serialized time shape instead of the picker default.
+
+### Disabled-time callbacks
+
+Use these when valid hours, minutes, or seconds depend on business rules.
+
+## Slots
+
+Useful slots include wrapper-level `label` and `error`, plus normal time-picker customization slots where supported.
+
+## Instance API
+
+The exposed instance combines:
+
+- `formItem`
+- `field`
+
+## Events
+
+Important events include:
+
+- `update:modelValue`
+- `change`
+- `focus`
+- `blur`
+- `clear`
+- `visible-change`
+
+## Import
+
+```ts
+import { FormTimePicker } from '@hinen/pro-element-plus';
+```

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

@@ -0,0 +1,82 @@
+---
+name: using-form-tree-select
+description: Use when a wrapped field should combine FormItem semantics with tree-node selection behavior inside the Form* wrapper family.
+---
+
+# Using FormTreeSelect
+
+## Overview
+
+Use `FormTreeSelect` for a **tree-oriented hierarchical wrapped field** that combines `FormItem` behavior with Element Plus tree-select behavior.
+
+It fits fields where node semantics, tree expansion, checkbox selection, or lazy tree loading matter more than simple cascader path traversal.
+
+## Use it when
+
+- a field should pick from tree-shaped data with node semantics
+- you need checkboxes, multiple selection, or lazy tree loading inside the FormFields family
+- tree node rendering or tree-event behavior matters to the field contract
+- the field should expose both `formItem` and tree-select `field` refs together
+
+## Prefer something else when
+
+- a cascader path is the simpler UX  
+  → use `../using-form-cascade-select/SKILL.md`
+- a flat local 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 `FormTreeSelect` if the answer is yes for **two or more** of these:
+
+- Should users interact with nodes in a visible tree rather than a path-only cascader?
+- Do checkboxes, node expansion, or lazy tree loading matter to normal usage?
+- Should the field stay inside the shared form-wrapper family?
+- Do you want wrapper validation access and tree-select instance access together?
+
+If not, `FormCascadeSelect`, `FormSelect`, or another wrapper may fit better.
+
+## Start with
+
+1. Decide whether the hierarchy should behave like tree nodes or a cascader path.
+2. Add the normal `FormItem` props such as `label`, `prop`, and `rules`.
+3. Add `data`, mapping props, and tree interaction props only after the wrapper choice is clear.
+4. Use cascader-oriented wrappers instead if path traversal is the primary UX.
+
+## Minimal patterns
+
+### Standard wrapped tree select
+
+```vue
+<FormTreeSelect label="Department" prop="department" :data="data" />
+```
+
+### Checkbox or multi-select tree
+
+Use tree-select props like `showCheckbox` or `multiple` when the field should support richer node selection behavior.
+
+### Lazy-loaded tree field
+
+Use lazy tree props when children should load on demand instead of being preloaded.
+
+## Common mistakes
+
+- using `FormTreeSelect` when a cascader path would be simpler and clearer
+- treating visible tree selection and cascader traversal as interchangeable
+- forgetting that tree interaction props and events are part of the field contract, not just extra features
+
+## 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 cascader: `../using-form-cascade-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-tree-select/references/examples.md

@@ -0,0 +1,55 @@
+# FormTreeSelect examples
+
+## 1. Standard tree-backed field
+
+Use `FormTreeSelect` when users should select values from visible tree-shaped data inside a wrapped form flow.
+
+Minimal pattern:
+
+```vue
+<FormTreeSelect label="Department" prop="department" :data="data" />
+```
+
+Typical fit:
+
+- department trees
+- category trees
+- nested organization structures
+
+## 2. Checkbox or multi-select tree field
+
+Use `showCheckbox`, `multiple`, or `checkStrictly` when selection behavior should support richer tree semantics.
+
+Minimal pattern:
+
+```vue
+<FormTreeSelect
+  label="Permissions"
+  prop="permissions"
+  :data="data"
+  show-checkbox
+  multiple
+/>
+```
+
+Typical fit:
+
+- permission assignment
+- many-node category selection
+- parent or child selection rules
+
+## 3. Lazy-loaded tree field
+
+Use lazy loading when the full tree is too large to preload.
+
+Minimal pattern:
+
+```vue
+<FormTreeSelect label="Org Unit" prop="orgUnit" :data="data" lazy />
+```
+
+Typical fit:
+
+- remote org charts
+- deep nested data sets
+- server-backed node expansion

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

@@ -0,0 +1,13 @@
+# FormTreeSelect gotchas
+
+- Tree selection and cascader traversal are different UX choices  
+  Use `../using-form-cascade-select/SKILL.md` when path traversal is the clearer interaction.
+
+- Tree interaction props change the field contract  
+  Checkbox mode, strict checking, and lazy loading are not minor details.
+
+- A flat list should not become a fake tree  
+  If hierarchy is not part of the product model, `../using-form-select/SKILL.md` is usually clearer.
+
+- Checkbox tree selection changes the stored value contract  
+  Once `showCheckbox`, `multiple`, or strict checking enters the design, treat the field as a richer node-selection problem, not as a simple select with indentation.