@hinen/pro-element-plus 1.7.17 → 1.8.1

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

@@ -0,0 +1,134 @@
+---
+name: using-query-form
+description: Use when building a schema-driven query or filter surface that should emit search state, support collapse, and optionally expose query-focused form instance methods.
+---
+
+# Using QueryForm
+
+## Overview
+
+Use `QueryForm` for a **schema-driven search or filter form** where one `items` array should define the fields, the field type, and the initial filter state.
+
+It is a page-level filter surface, not a generic replacement for every form. `QueryForm` is strongest when the main job is to collect query criteria, emit `search` and `reset` events, and optionally expose a small instance API for parent-driven filter control.
+
+## Use it when
+
+Use `QueryForm` when several of these are true:
+
+- the page needs a compact search or filter panel
+- one schema array should define the whole filter surface
+- field choice should come from `valueType` instead of hand-written component branching
+- filters may collapse when the list gets long
+- parent code may need to read, restore, or set filter values programmatically
+- the form may later pair with `../using-data-table/SKILL.md`
+
+Strong signals this skill applies:
+
+- admin search bars
+- report filter panels
+- list-page query areas
+- reusable filter sections shared across tabs
+
+## Prefer something else when
+
+- the page also needs built-in result rendering, pagination, and refresh control  
+  → use `../using-data-table/SKILL.md`
+- you are choosing field wrappers for a general-purpose create or edit form  
+  → use `../building-form-workflows/SKILL.md`
+- the same filter surface should live inside an overlay shell instead of a normal page layout  
+  → use `../using-modal/SKILL.md` or `../using-drawer/SKILL.md` for the shell choice, then keep `QueryForm` as the inner filter shell
+- the layout and validation flow are highly custom and should not be driven by `items`
+- search buttons, collapse behavior, and tag-style overflow state are not part of the intended UX
+
+## Decision guide
+
+Use `QueryForm` if the answer is yes for **two or more** of these:
+
+- Should one `items` array define most fields?
+- Is the primary outcome a `search` event rather than a full submit workflow?
+- Should the filter surface support collapse and overflow tags?
+- Does parent code need `getFormData()`, `setFormData()`, or `restore()`?
+- Should different field components be selected through `valueType`?
+
+If not, a standard form workflow is usually a better fit.
+
+## Start with
+
+1. Define `items` around the real filters, not every possible field.
+2. Pick the correct `valueType` for each item first.
+3. Add `initialValues` only for defaults that matter to query behavior.
+4. Tune `width`, `gutter`, and collapse settings after the field list is stable.
+
+## Minimal patterns
+
+### Standalone query surface
+
+Use this when the page only needs to collect and emit filter state.
+
+```vue
+<QueryForm :items="items" @search="handleSearch" @reset="handleReset" />
+```
+
+### Schema-driven mixed fields
+
+Use `valueType` to choose the field wrapper instead of branching in the template.
+
+```ts
+const items = [
+  {
+    label: 'Keyword',
+    prop: 'keyword',
+  },
+  {
+    label: 'Status',
+    prop: 'status',
+    valueType: 'select',
+    options: [
+      { label: 'Enabled', value: 'enabled' },
+      { label: 'Disabled', value: 'disabled' },
+    ],
+  },
+  {
+    label: 'Created At',
+    prop: 'createdAt',
+    valueType: 'date',
+    type: 'daterange',
+  },
+];
+```
+
+### Programmatic filter control
+
+Use the instance only when parent code truly needs to coordinate the filter state.
+
+Common methods:
+
+- `getFormData()`
+- `setFormData()`
+- `restore()`
+- `resetFields()`
+- `validate()`
+
+## Common mistakes
+
+- treating `QueryForm` like a generic edit form instead of a query surface
+- putting too many rarely used fields into `items` before validating the product need
+- forgetting that `searchOnReset` defaults to running search after reset
+- assuming all form-field props work for every `valueType`
+- using programmatic control when simple `search` and `reset` events are enough
+- tuning collapse widths before the field schema is settled
+
+## Related skills
+
+- Combined query and result shell: `../using-data-table/SKILL.md`
+- General form-wrapper selection: `../building-form-workflows/SKILL.md`
+- Wrapped select behavior behind common `valueType` choices: `../using-form-select/SKILL.md`
+- Local select fields inside form schemas: `../using-select/SKILL.md`
+- Remote or request-driven select fields: `../using-data-select/SKILL.md`
+- Overlay shells that may host this filter surface: `../using-modal/SKILL.md`, `../using-drawer/SKILL.md`
+
+## References
+
+- Props: `./references/props.md`
+- Examples: `./references/examples.md`
+- Gotchas: `./references/gotchas.md`

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

@@ -0,0 +1,103 @@
+# QueryForm examples
+
+## 1. Standalone list filter panel
+
+Use `QueryForm` when the page needs a dedicated filter area but result rendering lives elsewhere.
+
+Minimal pattern:
+
+```vue
+<QueryForm :items="items" @search="handleSearch" @reset="handleReset" />
+```
+
+Typical fit:
+
+- search bars above a custom chart or card list
+- tab-level filter sections
+- report filters that drive several downstream widgets
+
+Recommended pattern:
+
+- keep the schema in `items`
+- react to `search` in parent code
+- let the component own basic reset and validation flow
+
+## 2. Pre-DataTable query surface
+
+Use `QueryForm` when a page currently only needs filters, but may later grow into a combined list shell.
+
+Minimal pattern:
+
+```vue
+<QueryForm :items="items" @search="handleSearch" />
+```
+
+Typical fit:
+
+- feature work that starts with filters first
+- pages migrating toward `../../using-data-table/SKILL.md`
+- custom layouts that still want standardized query controls
+
+Keep field semantics and prop names stable so the page can later move into `DataTable` more easily.
+
+## 3. Long filter set with collapse
+
+Use collapse behavior when the default page view should stay compact.
+
+Minimal pattern:
+
+```vue
+<QueryForm :items="items" collapsable :default-collapsed-rows="1" />
+```
+
+Typical fit:
+
+- advanced search panels
+- internal admin pages with many optional filters
+- responsive layouts where the number of visible filters changes by breakpoint
+
+Recommended pattern:
+
+- keep `collapsable` enabled
+- tune `defaultCollapsedRows` after validating the field list
+- use tag overflow as a summary, not as the primary way to understand active filters
+
+## 4. Parent-controlled filter state
+
+Use the instance API when toolbars, tabs, or route state need to coordinate the form.
+
+Minimal pattern:
+
+```ts
+queryFormRef.value?.setFormData({ status: 'active' });
+```
+
+Typical fit:
+
+- clicking a dashboard card should preset filters
+- tab changes should restore a previous filter state
+- parent code needs to merge new params without recreating the schema
+
+Recommended pattern:
+
+- use `setFormData()` sparingly
+- call `getFormData()` when parent code needs the current normalized query state
+- reserve `restore()` for explicit rollback behavior
+
+## 5. QueryForm inside an overlay shell
+
+Use `QueryForm` inside `../../using-modal/SKILL.md` or `../../using-drawer/SKILL.md` when the overlay body needs filters but does not yet need a full `DataTable` shell.
+
+Minimal pattern:
+
+```vue
+<Modal :model-value="visible" title="Advanced Filter" @cancel="visible = false">
+  <QueryForm :items="items" @search="handleSearch" />
+</Modal>
+```
+
+Typical fit:
+
+- advanced filter overlays
+- side-panel filter refinement before applying changes
+- modal query surfaces that drive custom cards or charts

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

@@ -0,0 +1,19 @@
+# QueryForm gotchas
+
+- `searchOnReset` defaults to `true`  
+  Reset can trigger a search immediately, so do not assume reset is a purely local UI action.
+
+- Item `width` overrides form-level `width`  
+  If one field looks misaligned, check `item.width` before changing the whole form layout.
+
+- Missing `valueType` means text input  
+  Omitting `valueType` does not produce an error. It falls back to the text field wrapper.
+
+- Collapse behavior is width-based  
+  `defaultCollapsedRows` works through width accumulation, not by counting a fixed number of items.
+
+- `restore()` uses the shadow copy, not the original props  
+  The restore target tracks the last shadow state, which changes after search or `setFormData()` when `setShadow` is enabled.
+
+- Validation still follows Element Plus rules  
+  `QueryForm` adds query behavior, but field rules and validation behavior still come from the underlying Element Plus form contract.

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

@@ -0,0 +1,146 @@
+# QueryForm props
+
+## Overview
+
+`QueryForm` extends Element Plus form props and adds schema-driven filter configuration, responsive width control, and a small query-focused instance API.
+
+Start by deciding the field schema and event flow first. Layout and collapse props are secondary.
+
+## Minimum setup
+
+Required:
+
+- `items`
+
+Typical optional props:
+
+- `initialValues`
+- `width`
+- `gutter`
+- `collapsable`
+- `defaultCollapsed`
+- `defaultCollapsedRows`
+
+## Core props
+
+### `items`
+
+The source of truth for the filter surface.
+
+Each item describes:
+
+- `prop`
+- `label`
+- `valueType`
+- field-specific props such as `options`, `placeholder`, `rules`, or `tooltip`
+- optional layout overrides such as `width` and `colClassName`
+
+Supported `valueType` values:
+
+- `text`
+- `number`
+- `date`
+- `time`
+- `select`
+- `switch`
+- `radio`
+- `checkbox`
+- `cascade`
+- `tree`
+- `tag`
+- `autocomplete`
+
+If `valueType` is omitted, the component falls back to the text field wrapper.
+
+### `initialValues`
+
+Initial filter state copied into the internal form model.
+
+Use this for meaningful default filters, not as a substitute for parent-owned state syncing.
+
+### `width`
+
+Controls the default field width.
+
+Accepts:
+
+- a number
+- a responsive object with `xs`, `sm`, `md`, `lg`, `xl`, and `xxl`
+
+Individual items can override this through `item.width`.
+
+### `gutter`
+
+Controls spacing between item wrappers.
+
+Like `width`, this can be a number or a responsive object.
+
+### `collapsable`
+
+Enables expand and collapse behavior for long filter lists.
+
+Default: `true`
+
+### `defaultCollapsed`
+
+Controls whether the form starts collapsed.
+
+Default: `true`
+
+### `defaultCollapsedRows`
+
+Controls how much width is shown before the form collapses extra fields into the tag area.
+
+Default: `1`
+
+### `searchOnReset`
+
+If `true`, reset emits `reset` and then triggers the same search path used by submit.
+
+Default: `true`
+
+### `hideLabel`
+
+Hides the visual form labels while keeping the query controls and action row.
+
+Default: `false`
+
+## Events
+
+`QueryForm` forwards Element Plus form events and adds query-specific ones.
+
+Most important additions:
+
+- `search`
+- `reset`
+- `change`
+
+Use `search` as the main integration point for query execution.
+
+## Instance API
+
+The exposed instance combines Element Plus form methods with query helpers.
+
+Available methods:
+
+- `validate()`
+- `validateField()`
+- `resetFields()`
+- `clearValidate()`
+- `scrollToField()`
+- `getFormData()`
+- `restore()`
+- `setFormData(values, options)`
+
+`setFormData()` supports:
+
+- `merge?: boolean` defaulting to `true`
+- `setShadow?: boolean` defaulting to `true`
+
+Use `restore()` when parent code should roll the form back to the last searched or shadow-copied state.
+
+## Import
+
+```ts
+import { QueryForm } from '@hinen/pro-element-plus';
+```

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

@@ -0,0 +1,91 @@
+---
+name: using-radio-group
+description: Use when users should choose exactly one visible option from a short local set without hiding choices inside a dropdown or wrapper flow.
+---
+
+# Using RadioGroup
+
+## Overview
+
+Use `RadioGroup` for a **visible single-choice control** when every option should stay on screen and the user should pick exactly one value.
+
+It is the direct, non-wrapper counterpart to `../using-form-radio-group/SKILL.md`. Reach for it when the options are local, comparison matters, and the control does not need to live inside the `Form*` wrapper family.
+
+## Use it when
+
+Use `RadioGroup` when several of these are true:
+
+- only one option can be chosen
+- showing every option at once helps comparison
+- a simple local `options` array is enough
+- button-style or custom rendered radio options may help the UX
+- the control does not need form-wrapper semantics
+
+Strong signals this skill applies:
+
+- short status sets
+- mode pickers
+- comparison-friendly small choice lists
+- segmented-option style controls
+
+## Prefer something else when
+
+- users may select multiple options  
+  → use `../using-checkbox-group/SKILL.md`
+- the same control belongs inside a form wrapper  
+  → use `../using-form-radio-group/SKILL.md`
+- the option set is large enough that a dropdown is clearer  
+  → use `../using-select/SKILL.md`
+
+## Decision guide
+
+Use `RadioGroup` if the answer is yes for **two or more** of these:
+
+- Should the user choose exactly one option?
+- Does keeping all options visible improve comparison or speed?
+- Is the option set small and local enough for an `options` array?
+- Is a direct component clearer than introducing a form wrapper?
+
+If not, `CheckboxGroup`, `Select`, or a form-wrapper version may fit better.
+
+## Start with
+
+1. Confirm that the choice is truly one-of-many.
+2. Model the local option list as `options`.
+3. Use the default rendering first.
+4. Reach for slot-based custom option rendering only when labels alone are not enough.
+
+## Minimal patterns
+
+### Standard local radio group
+
+```vue
+<RadioGroup :options="options" v-model="value" />
+```
+
+### Disabled option set
+
+Use `disabled` or per-option `disabled` values when availability should stay visible but not selectable.
+
+### Custom option rendering
+
+Use the default slot when the option body should render as radio buttons or richer content instead of plain labels.
+
+## Common mistakes
+
+- using `RadioGroup` when many values should be selectable
+- using visible radios for long option lists that would be clearer as a select
+- reaching for the direct component when the field really belongs in a wrapped form flow
+- rebuilding the option body manually when the standard `options` shape already fits
+
+## Related skills
+
+- Visible multi-select counterpart: `../using-checkbox-group/SKILL.md`
+- Wrapped single-choice version: `../using-form-radio-group/SKILL.md`
+- Dropdown alternative for larger local sets: `../using-select/SKILL.md`
+
+## References
+
+- Props: `./references/props.md`
+- Examples: `./references/examples.md`
+- Gotchas: `./references/gotchas.md`

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

@@ -0,0 +1,55 @@
+# RadioGroup examples
+
+## 1. Standard visible single-choice control
+
+Use `RadioGroup` when users should pick exactly one value and comparing all options at once is useful.
+
+Minimal pattern:
+
+```vue
+<RadioGroup :options="statusOptions" v-model="status" />
+```
+
+Typical fit:
+
+- status filters
+- display mode toggles
+- short enumerated choices
+
+## 2. Disabled options remain visible
+
+Use disabled group or option state when unavailable choices should still be visible for context.
+
+Minimal pattern:
+
+```vue
+<RadioGroup :options="planOptions" v-model="plan" />
+```
+
+Mark individual options disabled when users should see unavailable states without being able to pick them.
+
+Typical fit:
+
+- permission-limited modes
+- unavailable plans
+- gated product states
+
+## 3. Custom radio rendering
+
+Use the default slot when the option body should render as radio buttons or richer custom UI.
+
+Minimal pattern:
+
+```vue
+<RadioGroup :options="modeOptions" v-model="mode">
+  <template #default="{ option }">
+    <span>{{ option.label }}</span>
+  </template>
+</RadioGroup>
+```
+
+Typical fit:
+
+- segmented controls
+- icon-backed options
+- emphasized current-mode selection

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

@@ -0,0 +1,13 @@
+# RadioGroup gotchas
+
+- `RadioGroup` is for one-of-many choice  
+  If many values can be selected, use `../using-checkbox-group/SKILL.md`.
+
+- A binary state is usually not a radio group problem  
+  If the field is really on or off, a switch-style control is often clearer than two visible radio options.
+
+- Large option sets become noisy when always visible  
+  If the list is too long, `../using-select/SKILL.md` is usually clearer.
+
+- The direct component is not the form-wrapper version  
+  If the control belongs in a wrapped schema or form flow, use `../using-form-radio-group/SKILL.md`.

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

@@ -0,0 +1,83 @@
+# RadioGroup props
+
+## Overview
+
+`RadioGroup` stays close to Element Plus radio-group behavior and adds a first-class local `options` prop.
+
+Use it when one visible local choice set should be rendered directly instead of through a dropdown.
+
+## Minimum setup
+
+A minimal working setup is usually just:
+
+```vue
+<RadioGroup :options="options" v-model="value" />
+```
+
+That is enough when the options are local and exactly one value should be selected.
+
+Typical useful props:
+
+- `options`
+- `modelValue`
+
+Common optional props:
+
+- `disabled`
+- `size`
+- `fill`
+- `textColor`
+
+## Core props
+
+### `options`
+
+The main local option source.
+
+Each option uses the shape:
+
+- `label`
+- `value`
+- optional `disabled`
+
+This is the real required input in normal usage. Without `options`, the component has nothing to render unless you fully replace rendering through slots.
+
+### `modelValue`
+
+The selected value.
+
+Use this for the single current choice.
+
+Match the value type to the option `value` shape. If the current value never equals an option value, nothing will appear selected.
+
+### Group styling props
+
+Useful inherited props include:
+
+- `disabled`
+- `size`
+- `fill`
+- `textColor`
+
+These only matter after the one-of-many behavior is already correct.
+
+## Slots
+
+Useful slots include the default slot receiving `{ options }`.
+
+Use this when the option body should render as custom radio content instead of the built-in label rendering.
+
+If you customize the slot heavily, keep the one-of-many behavior obvious so the control still reads like a radio group instead of a generic button row.
+
+## Events
+
+Important events include:
+
+- `update:modelValue`
+- `change`
+
+## Import
+
+```ts
+import { RadioGroup } from '@hinen/pro-element-plus';
+```