@hinen/pro-element-plus 1.7.17 → 1.8.0

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

@@ -0,0 +1,13 @@
+# FormCascadeSelect gotchas
+
+- Cascader paths and tree nodes are different UX choices  
+  Use `../using-form-tree-select/SKILL.md` when visible node semantics matter more than path traversal.
+
+- Cascader `props` control major behavior  
+  Expand trigger, strictness, multiple choice, and lazy loading are not minor details.
+
+- A flat list should not become a fake hierarchy  
+  If nesting is not part of the product model, `../using-form-select/SKILL.md` is usually clearer.
+
+- Cascader `props` can change selection semantics, not just visuals  
+  Multiple mode, strict checking, expand trigger, and lazy loading all affect what the field means and how users traverse it.

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

@@ -0,0 +1,138 @@
+# FormCascadeSelect props
+
+## Overview
+
+`FormCascadeSelect` combines `FormItem` props with Element Plus cascader props.
+
+Use it when hierarchical path selection should stay inside the shared form-wrapper family.
+
+## Minimum setup
+
+Typical useful props:
+
+- `label`
+- `prop`
+- `options`
+
+Common optional field props:
+
+- `props`
+- `filterable`
+- `clearable`
+
+## Core props
+
+### Wrapper props from `FormItem`
+
+Includes wrapper-level props such as:
+
+- `label`
+- `prop`
+- `rules`
+- `required`
+- `tooltip`
+
+### `options`
+
+The hierarchical option source.
+
+Use this when the full cascader tree is known up front.
+
+### Cascader `props`
+
+Use cascader configuration props to control:
+
+- expand trigger
+- multiple selection
+- strict checking behavior
+- lazy loading
+
+### Common selection props
+
+Useful field props include:
+
+- `filterable`
+- `clearable`
+- `showAllLevels`
+
+### `renderDefault`
+
+A function that receives `{ node, data }` and returns VNode content for customizing cascader node display.
+
+Use this when you cannot use the `default` slot (for example, in DataTable query forms rendered dynamically) but still need to customize how each cascader node appears.
+
+**Signature:**
+
+```typescript
+renderDefault?: (scope: {
+  node: CascaderNode;
+  data: CascaderOption;
+}) => VNodeChild;
+```
+
+**Example:**
+
+```tsx
+<FormCascadeSelect
+  label="Category"
+  prop="category"
+  :options="categoryOptions"
+  :render-default="({ node, data }) => (
+    <span>
+      {data.label}
+      {!node.isLeaf && ` (${data.children?.length || 0})`}
+    </span>
+  )"
+/>
+```
+
+**When to use:**
+
+- In DataTable query forms where slots cannot be passed via dynamic component rendering
+- When you need programmatic control over node rendering
+- When the render logic depends on external state that is easier to access in the parent component
+
+**Note:** When both `renderDefault` prop and `default` slot are provided, the slot takes precedence.
+
+## Slots
+
+Useful slots include wrapper-level `label` and `error`, plus cascader node customization slots where richer node rendering is needed.
+
+### `default` slot
+
+Customize cascader node rendering via slot (preferred when possible):
+
+```vue
+<FormCascadeSelect label="Category" prop="category" :options="options">
+  <template #default="{ node, data }">
+    <span>{{ data.label }}</span>
+    <span v-if="!node.isLeaf"> ({{ data.children.length }}) </span>
+  </template>
+</FormCascadeSelect>
+```
+
+## Instance API
+
+The exposed instance combines:
+
+- `formItem`
+- `field`
+
+## Events
+
+Important events include:
+
+- `update:modelValue`
+- `change`
+- `focus`
+- `blur`
+- `clear`
+- `expandChange`
+- `removeTag`
+- `visibleChange`
+
+## Import
+
+```ts
+import { FormCascadeSelect } from '@hinen/pro-element-plus';
+```

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

@@ -0,0 +1,83 @@
+---
+name: using-form-checkbox-group
+description: Use when a wrapped field should combine FormItem semantics with multi-choice checkbox-group behavior inside the Form* wrapper family.
+---
+
+# Using FormCheckboxGroup
+
+## Overview
+
+Use `FormCheckboxGroup` for a **multi-choice wrapped field** that combines `FormItem` behavior with the package’s `CheckboxGroup` abstraction.
+
+It fits fields where the user should pick zero or more values from a fixed set while staying inside the shared form-wrapper family.
+
+## Use it when
+
+- a field should capture multiple selected values from a fixed option set
+- you want checkbox-group behavior plus form labels, rules, and tooltip support
+- options can come from `options` or lightweight `valueEnum` mappings
+- the field should expose both `formItem` and checkbox-group `field` refs together
+
+## Prefer something else when
+
+- you need the raw checkbox group component outside FormFields  
+  → use `../using-checkbox-group/SKILL.md`
+- only one option should be selected  
+  → use `../using-form-radio-group/SKILL.md`
+- the field is really a binary toggle  
+  → use `../using-form-switch/SKILL.md`
+
+## Decision guide
+
+Use `FormCheckboxGroup` if the answer is yes for **two or more** of these:
+
+- Should the user be able to select many values 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 checkbox-group instance access together?
+
+If not, `FormRadioGroup`, `FormSwitch`, or another wrapper may fit better.
+
+## Start with
+
+1. Decide whether the field is multi-choice, single-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 radio groups or switches instead if the interaction is not really many-of-many.
+
+## Minimal patterns
+
+### Standard wrapped checkbox group
+
+```vue
+<FormCheckboxGroup label="Permissions" prop="permissions" :options="options" />
+```
+
+### Enum-backed wrapped checkbox group
+
+Use `valueEnum` when a compact mapping is clearer than an explicit options array.
+
+### Custom checkbox rendering
+
+Use slots when the option body should render as checkbox buttons or richer content.
+
+## Common mistakes
+
+- using `FormCheckboxGroup` when only one option should be chosen
+- 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 checkbox group: `../using-checkbox-group/SKILL.md`
+- Wrapped radio group: `../using-form-radio-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-checkbox-group/references/examples.md

@@ -0,0 +1,61 @@
+# FormCheckboxGroup examples
+
+## 1. Standard many-of-many field
+
+Use `FormCheckboxGroup` when a wrapped form field should allow many selected values from a fixed local set.
+
+Minimal pattern:
+
+```vue
+<FormCheckboxGroup
+  label="Permissions"
+  prop="permissions"
+  :options="permissionOptions"
+/>
+```
+
+Typical fit:
+
+- permissions
+- feature selection
+- preference groups
+
+## 2. Enum-backed checkbox field
+
+Use `valueEnum` when a compact value-to-label mapping is clearer than an explicit options array.
+
+Minimal pattern:
+
+```vue
+<FormCheckboxGroup
+  label="Capabilities"
+  prop="capabilities"
+  :value-enum="capabilityEnum"
+/>
+```
+
+Typical fit:
+
+- admin toggles with several allowed flags
+- small fixed capability sets
+- compact settings groups
+
+## 3. Custom checkbox rendering
+
+Use slots when the option body should render as checkbox buttons or richer content.
+
+Minimal pattern:
+
+```vue
+<FormCheckboxGroup label="Features" prop="features" :options="featureOptions">
+  <template #default="{ option }">
+    <span>{{ option.label }}</span>
+  </template>
+</FormCheckboxGroup>
+```
+
+Typical fit:
+
+- button-style choices
+- icon-backed options
+- detailed option descriptions

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

@@ -0,0 +1,13 @@
+# FormCheckboxGroup gotchas
+
+- Checkbox groups are for many-of-many choice  
+  If only one value may be selected, use `../using-form-radio-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-checkbox-group/references/props.md

@@ -0,0 +1,85 @@
+# FormCheckboxGroup props
+
+## Overview
+
+`FormCheckboxGroup` combines `FormItem` props with the package’s `CheckboxGroup` props and adds `valueEnum` as a compact option source.
+
+Use it when many-of-many selection should stay inside the shared form-wrapper family.
+
+## Minimum setup
+
+A minimal working setup is usually just:
+
+```vue
+<FormCheckboxGroup
+  label="Permissions"
+  prop="permissions"
+  :options="permissionOptions"
+/>
+```
+
+That works because the wrapper already combines `FormItem` semantics with checkbox-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.
+
+### Checkbox-group props
+
+Useful field props include:
+
+- `options`
+- `modelValue`
+- disabled-state and layout props from the wrapped checkbox-group abstraction
+
+Use `options` for the normal local-choice case. Treat `modelValue` as the selected values array for the field, not as a visual-only helper.
+
+### `valueEnum`
+
+Compact mapping from value to label.
+
+The wrapper converts this into local checkbox 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 checkbox option-rendering slots from the wrapped checkbox-group abstraction.
+
+Reach for slots after the many-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 { FormCheckboxGroup } from '@hinen/pro-element-plus';
+```

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

@@ -0,0 +1,79 @@
+---
+name: using-form-date-picker
+description: Use when a wrapped field should combine FormItem semantics with date, calendar, or date-range picking behavior inside the Form* wrapper family.
+---
+
+# Using FormDatePicker
+
+## Overview
+
+Use `FormDatePicker` for a **date-oriented wrapped field** that combines `FormItem` behavior with Element Plus date picker modes.
+
+It fits fields where the value is date-like or range-like and the field should stay inside the same wrapper family as sibling text, number, and select fields.
+
+## Use it when
+
+- a field captures dates, weeks, months, years, or date ranges
+- you want date-picker modes plus built-in `FormItem` labels and validation
+- shortcuts, format configuration, or range behavior are part of the field contract
+- the field should expose both `formItem` and date-picker `field` refs together
+
+## Prefer something else when
+
+- the field is time-only  
+  → use `../using-form-time-picker/SKILL.md`
+- you only need wrapper behavior around custom content  
+  → use `../using-form-item/SKILL.md`
+
+## Decision guide
+
+Use `FormDatePicker` if the answer is yes for **two or more** of these:
+
+- Is the stored value fundamentally date-like rather than time-only?
+- Do date-picker modes or ranges matter to the normal interaction?
+- Should the field stay inside the shared form-wrapper family?
+- Do you want wrapper validation access and date-picker instance access together?
+
+If not, `FormTimePicker` or another wrapper is probably a better fit.
+
+## Start with
+
+1. Decide whether the field is single-date, multi-date, or range-based.
+2. Add the normal `FormItem` props such as `label`, `prop`, and `rules`.
+3. Choose `type`, formatting, and shortcuts only after the wrapper choice is clear.
+4. Use time-only wrappers instead if the value is not date-oriented.
+
+## Minimal patterns
+
+### Standard wrapped date field
+
+```vue
+<FormDatePicker label="Due Date" prop="dueDate" type="date" />
+```
+
+### Date range field
+
+Use `type="daterange"` when the field stores a start-and-end date range.
+
+### Shortcut-driven date field
+
+Use `shortcuts` when common date presets are part of the product flow.
+
+## Common mistakes
+
+- using `FormDatePicker` for time-only input
+- forgetting that picker `type` changes the value shape and UX meaning
+- mixing wrapper concerns and field concerns without deciding the date contract first
+- manually composing `FormItem` and `ElDatePicker` when the standard wrapper already fits
+
+## Related skills
+
+- Wrapper-family selection: `../using-form-fields/SKILL.md`
+- Base wrapper only: `../using-form-item/SKILL.md`
+- Wrapped time picker: `../using-form-time-picker/SKILL.md`
+
+## References
+
+- Props: `./references/props.md`
+- Examples: `./references/examples.md`
+- Gotchas: `./references/gotchas.md`

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

@@ -0,0 +1,54 @@
+# FormDatePicker examples
+
+## 1. Standard date field
+
+Use `FormDatePicker` when the field stores a single date-like value inside a wrapped form flow.
+
+Minimal pattern:
+
+```vue
+<FormDatePicker label="Due Date" prop="dueDate" type="date" />
+```
+
+Typical fit:
+
+- due date
+- birthday
+- publish date
+
+## 2. Date range field
+
+Use date-range modes when the field stores a start and end date together.
+
+Minimal pattern:
+
+```vue
+<FormDatePicker label="Active Range" prop="activeRange" type="daterange" />
+```
+
+Typical fit:
+
+- reporting windows
+- booking periods
+- active date ranges
+
+## 3. Shortcut-backed date picking
+
+Use `shortcuts` when common date presets are part of the intended workflow.
+
+Minimal pattern:
+
+```vue
+<FormDatePicker
+  label="Window"
+  prop="window"
+  type="daterange"
+  :shortcuts="shortcuts"
+/>
+```
+
+Typical fit:
+
+- today and yesterday
+- last week
+- last month

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

@@ -0,0 +1,10 @@
+# FormDatePicker gotchas
+
+- `type` changes the UX and value shape  
+  Decide the picker mode first instead of treating it like a minor prop.
+
+- Date range and single date are different field contracts  
+  Keep placeholders, formatting, and downstream value handling aligned with the chosen mode.
+
+- Use `../using-form-time-picker/SKILL.md` for time-only fields  
+  Date picking and time picking are related but different wrapper decisions.

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

@@ -0,0 +1,99 @@
+# FormDatePicker props
+
+## Overview
+
+`FormDatePicker` combines `FormItem` props with Element Plus date picker props.
+
+Use it when date and range semantics should stay inside the shared form-wrapper family.
+
+## Minimum setup
+
+Typical useful props:
+
+- `label`
+- `prop`
+- `type`
+
+Common optional field props:
+
+- `format`
+- `valueFormat`
+- `shortcuts`
+- range placeholders and separators
+
+## Core props
+
+### Wrapper props from `FormItem`
+
+Includes wrapper-level props such as:
+
+- `label`
+- `prop`
+- `rules`
+- `required`
+- `tooltip`
+
+### `type`
+
+The main date-mode selector.
+
+Common modes include:
+
+- `date`
+- `dates`
+- `week`
+- `month`
+- `months`
+- `year`
+- `years`
+- `daterange`
+- `monthrange`
+- `yearrange`
+
+### Formatting and default-value props
+
+Useful field props include:
+
+- `format`
+- `valueFormat`
+- `defaultValue`
+- `shortcuts`
+
+### Range-related props
+
+Use range props when the field stores a start and end value:
+
+- `rangeSeparator`
+- `startPlaceholder`
+- `endPlaceholder`
+- `unlinkPanels`
+
+## Slots
+
+Useful slots include wrapper-level `label` and `error`, plus picker customization slots for icon and panel decoration.
+
+## Instance API
+
+The exposed instance combines:
+
+- `formItem`
+- `field`
+
+## Events
+
+Important events include:
+
+- `update:modelValue`
+- `change`
+- `focus`
+- `blur`
+- `clear`
+- `calendar-change`
+- `panel-change`
+- `visible-change`
+
+## Import
+
+```ts
+import { FormDatePicker } from '@hinen/pro-element-plus';
+```