@hinen/pro-element-plus 1.7.17 → 1.8.0

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

@@ -0,0 +1,91 @@
+---
+name: using-checkbox-group
+description: Use when users should see several local options at once and pick any number of them without hiding the choices inside a dropdown or wrapper flow.
+---
+
+# Using CheckboxGroup
+
+## Overview
+
+Use `CheckboxGroup` for a **visible multi-choice control** when users should see all options at once and select zero or more values.
+
+It is the direct, non-wrapper counterpart to `../using-form-checkbox-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 `CheckboxGroup` when several of these are true:
+
+- multi-select choices should stay visible
+- a simple local `options` array is enough
+- checkbox semantics are clearer than a dropdown
+- custom rendered checkbox options may help the UX
+- the control does not need form-wrapper semantics
+
+Strong signals this skill applies:
+
+- permission sets
+- preference groups
+- visible multi-tag selection
+- short local feature lists
+
+## Prefer something else when
+
+- the choice is single-select  
+  → use `../using-radio-group/SKILL.md`
+- the same control belongs inside a form wrapper  
+  → use `../using-form-checkbox-group/SKILL.md`
+- the option set is large enough that a dropdown is clearer  
+  → use `../using-select/SKILL.md`
+
+## Decision guide
+
+Use `CheckboxGroup` if the answer is yes for **two or more** of these:
+
+- Should users be able to select many values from a fixed set?
+- Does keeping all options visible improve comparison or understanding?
+- Is the option set small and local enough for an `options` array?
+- Is a direct component clearer than introducing a form wrapper?
+
+If not, `RadioGroup`, `Select`, or a form-wrapper version may fit better.
+
+## Start with
+
+1. Confirm that the choice is truly many-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 checkbox group
+
+```vue
+<CheckboxGroup :options="options" v-model="values" />
+```
+
+### Disabled option set
+
+Use `disabled` or per-option `disabled` values when unavailable choices should stay visible but not selectable.
+
+### Custom option rendering
+
+Use the default slot when the option body should render as checkbox buttons or richer content instead of plain labels.
+
+## Common mistakes
+
+- using `CheckboxGroup` when only one value should be selected
+- using visible checkboxes 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 single-choice counterpart: `../using-radio-group/SKILL.md`
+- Wrapped multi-choice version: `../using-form-checkbox-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-checkbox-group/references/examples.md

@@ -0,0 +1,55 @@
+# CheckboxGroup examples
+
+## 1. Standard visible multi-choice control
+
+Use `CheckboxGroup` when users should choose zero or more values and comparing all options at once is useful.
+
+Minimal pattern:
+
+```vue
+<CheckboxGroup :options="permissionOptions" v-model="permissions" />
+```
+
+Typical fit:
+
+- permission sets
+- feature toggles by group
+- preference clusters
+
+## 2. Disabled options remain visible
+
+Use disabled group or option state when unavailable choices should still be visible for context.
+
+Minimal pattern:
+
+```vue
+<CheckboxGroup :options="featureOptions" v-model="enabledFeatures" />
+```
+
+Mark individual options disabled when users should still understand the full option set.
+
+Typical fit:
+
+- plan-restricted features
+- permission-limited selections
+- staged rollout options
+
+## 3. Custom checkbox rendering
+
+Use the default slot when the option body should render as checkbox buttons or richer custom UI.
+
+Minimal pattern:
+
+```vue
+<CheckboxGroup :options="filterOptions" v-model="selectedFilters">
+  <template #default="{ option }">
+    <span>{{ option.label }}</span>
+  </template>
+</CheckboxGroup>
+```
+
+Typical fit:
+
+- button-style multi-selects
+- icon-backed choices
+- grouped visible filters

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

@@ -0,0 +1,13 @@
+# CheckboxGroup gotchas
+
+- `CheckboxGroup` is for many-of-many choice  
+  If only one value can be selected, use `../using-radio-group/SKILL.md`.
+
+- A true or false field is usually not a checkbox-group problem  
+  If the feature is really one binary toggle, a switch-style control is usually clearer than a one-option checkbox group.
+
+- 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-checkbox-group/SKILL.md`.

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

@@ -0,0 +1,83 @@
+# CheckboxGroup props
+
+## Overview
+
+`CheckboxGroup` stays close to Element Plus checkbox-group behavior and adds a first-class local `options` prop.
+
+Use it when many visible local choices should be rendered directly instead of through a dropdown.
+
+## Minimum setup
+
+A minimal working setup is usually just:
+
+```vue
+<CheckboxGroup :options="options" v-model="values" />
+```
+
+That is enough when the options are local and many values may 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 values array.
+
+Use this for the current many-of-many selection state.
+
+Keep the array value shape aligned with the option `value` shape. Mismatched value types make the group look uncontrolled even when data exists.
+
+### Group styling props
+
+Useful inherited props include:
+
+- `disabled`
+- `size`
+- `fill`
+- `textColor`
+
+These are secondary to getting the many-of-many state correct.
+
+## Slots
+
+Useful slots include the default slot receiving `{ options }`.
+
+Use this when the option body should render as custom checkbox content instead of the built-in label rendering.
+
+If you customize the slot heavily, keep the multi-select affordance obvious so the control still reads like a checkbox group instead of loose buttons.
+
+## Events
+
+Important events include:
+
+- `update:modelValue`
+- `change`
+
+## Import
+
+```ts
+import { CheckboxGroup } from '@hinen/pro-element-plus';
+```

package/dist/skills/using-config-provider/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: using-config-provider
+description: Use when a subtree of pro-element-plus components, especially DataTable instances, should share injected empty and error rendering defaults.
+---
+
+# Using ConfigProvider
+
+## Overview
+
+Use `ConfigProvider` to **inject shared pro-element-plus UI defaults into a subtree**, especially shared `DataTable` empty and error rendering.
+
+In the current documented package surface, this component is mostly slot-based. It is not a broad global settings object. Its safest documented job is to let nearby `DataTable` instances share fallback UI without repeating the same local slot customization everywhere.
+
+Package-level docs also hint at locale-oriented copy such as search, reset, and data-error wording, but this skill treats the clearly documented public contract as **subtree-scoped shared rendering and copy for downstream table consumers**, not a general application configuration layer.
+
+## Use it when
+
+Use `ConfigProvider` when several of these are true:
+
+- multiple `DataTable` instances should share the same empty UI
+- multiple `DataTable` instances should share the same error UI
+- the customization belongs to one feature shell or page subtree
+- local per-table slot repetition is starting to create noise
+- you already know the page or feature is in the query/list family and want one shared fallback voice for nearby tables
+
+Strong signals this skill applies:
+
+- one module contains several list pages
+- a feature wants standardized empty and error messaging
+- a dashboard area should share the same list fallback visuals
+- `building-query-pages` or `using-data-table` is already the right shell, and now the remaining question is how to share fallback rendering across sibling tables
+
+## Prefer something else when
+
+- the customization applies to only one table and can stay local there
+- the component subtree does not actually contain `DataTable` consumers
+- you need a broader application configuration system than this slot-based provider offers
+- you only need `empty` or `error` content for one `DataTable`, because local slots are usually clearer than introducing a provider
+
+## Decision guide
+
+Use `ConfigProvider` if the answer is yes for **two or more** of these:
+
+- Should several `DataTable` instances share the same fallback UI?
+- Does the override belong to a subtree rather than every table individually?
+- Would repeating `empty` and `error` slots across tables add noise?
+- Is slot-based injection enough for the current feature?
+
+If only one table needs the customization, keep the slots on that `DataTable` instead of adding a provider layer.
+
+If the broader page shell is still undecided, route through `../building-query-pages/SKILL.md` first.
+
+## Start with
+
+1. Wrap the smallest feature subtree that should share fallback rendering.
+2. Provide `dataTableEmpty` and/or `dataTableError` slots only when the defaults should change.
+3. Keep table-specific special cases local if only one view needs them.
+4. Treat locale-like shared copy as feature-scoped unless the package documents a broader stable contract.
+
+## Minimal patterns
+
+### Shared DataTable fallback shell
+
+```vue
+<ConfigProvider>
+  <template #dataTableEmpty>
+    <EmptyState />
+  </template>
+
+  <template #dataTableError>
+    <ErrorState />
+  </template>
+
+  <FeatureTables />
+</ConfigProvider>
+```
+
+## Common mistakes
+
+- assuming `ConfigProvider` exposes a rich prop API when the current public contract is slot-based
+- wrapping too much of the tree when only one feature area needs the override
+- using it without actual `DataTable` consumers in the subtree
+- moving one-off table customizations here too early and losing local clarity
+- choosing the provider before deciding whether the page even needs a shared query/list shell
+- treating README capability hints as proof of a broad stable global-config API
+
+## Related skills
+
+- Query/list router that usually decides whether this provider is relevant at all: `../building-query-pages/SKILL.md`
+- Page-level list shell that consumes shared empty and error UI: `../using-data-table/SKILL.md`
+
+## References
+
+- Props: `./references/props.md`
+- Examples: `./references/examples.md`
+- Gotchas: `./references/gotchas.md`

package/dist/skills/using-config-provider/references/examples.md

@@ -0,0 +1,38 @@
+# ConfigProvider examples
+
+## 1. Shared table shell
+
+Wrap a feature subtree with `ConfigProvider` when several `DataTable` instances should share fallback rendering.
+
+Typical fit:
+
+- one feature contains several list pages
+- the same copy and visuals should appear across related empty states
+- error rendering should stay consistent inside the module
+
+Recommended pattern:
+
+- wrap the feature boundary, not the whole app by default
+- provide only the slots you need to override
+
+## 2. App-section customization
+
+Use it when the empty and error UI belongs to one part of the app rather than every table individually.
+
+Typical fit:
+
+- admin area tables share one style
+- project area tables share another
+- dashboard lists have their own fallback voice and visuals
+
+This keeps `DataTable` usage local while centralizing the repeated fallback UI.
+
+## 3. Local override remains local
+
+Do **not** use `ConfigProvider` when only one table needs the customization.
+
+Typical fit for staying local:
+
+- one special report screen
+- a single table with unique empty-state actions
+- one-off product copy that should not spread to sibling views

package/dist/skills/using-config-provider/references/gotchas.md

@@ -0,0 +1,13 @@
+# ConfigProvider gotchas
+
+- The current contract is slot-based, not prop-driven  
+  Do not design around a large configuration object that the current component does not expose.
+
+- Scope is the main decision  
+  The sharp edge here is usually wrapping the wrong subtree, not passing the wrong prop.
+
+- It is mainly about `DataTable` fallback rendering today  
+  Do not overstate its role beyond the surfaces the current package actually wires up.
+
+- Local one-off customization can be clearer  
+  If only one table needs a custom empty or error state, a provider can add unnecessary indirection.

package/dist/skills/using-config-provider/references/props.md

@@ -0,0 +1,38 @@
+# ConfigProvider props and slots
+
+## Overview
+
+`ConfigProvider` currently has **no meaningful public props**. The main contract is slot-based subtree configuration for downstream pro-element-plus consumers.
+
+In the current code, the useful public surface is almost entirely about `DataTable` fallback rendering.
+
+## Public surface
+
+### Default slot
+
+Wraps the child subtree that should receive the injected configuration.
+
+### `dataTableError` slot
+
+Provides shared custom error UI for `DataTable` consumers under this provider.
+
+### `dataTableEmpty` slot
+
+Provides shared custom empty UI for `DataTable` consumers under this provider.
+
+## Provider behavior
+
+The component injects slot-based renderers into the subtree through the internal config-provider context.
+
+This means the main decision is not about prop shape. It is about **scope**: which subtree should share the fallback UI.
+
+## Import
+
+```ts
+import { ConfigProvider } from '@hinen/pro-element-plus';
+```
+
+## Notes
+
+- There are no documented public props in the current package surface.
+- The provider is useful mainly when a subtree contains `DataTable` consumers.

package/dist/skills/using-data-select/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: using-data-select
+description: Use when a select needs request-aware, param-driven, enum-driven, or filter-mode-aware option loading rather than a purely local option list.
+---
+
+# Using DataSelect
+
+## Overview
+
+Use `DataSelect` for a **dropdown whose option source may be remote, param-driven, or enum-driven** while still keeping a standard select shell.
+
+It supports three valid source modes:
+
+1. **Local options mode** — pass `options`
+2. **Enum mode** — pass `valueEnum`
+3. **Request mode** — pass `request`
+
+It also supports two filtering models:
+
+- local filtering with `filterable: true`
+- remote filtering with `filterable: 'remote'`
+
+Choose it when option loading behavior is part of the component decision, not just a data detail.
+
+## Use it when
+
+Use `DataSelect` when several of these are true:
+
+- options may come from a request
+- dropdown options should react to params or search content
+- `valueEnum` is a convenient compact mapping for small choice sets
+- local and remote filtering need to be expressed intentionally
+- options may need dynamic disable logic through `disableOption`
+
+Strong signals this skill applies:
+
+- user lookup selects
+- tenant or project selectors backed by the server
+- filterable selects with changing option sets
+- enum-backed status selectors that may later become remote
+
+## Prefer something else when
+
+- the choices are purely local and should stay simple  
+  → use `../using-select/SKILL.md`
+- you need always-visible choices rather than a dropdown  
+  → use `../building-selection-inputs/SKILL.md`
+- the field belongs inside a schema-driven wrapper flow and request behavior is not the main reason to choose the component  
+  → use `../using-form-select/SKILL.md`
+- request behavior is irrelevant and a plain select wrapper already fits
+
+## Decision guide
+
+Use `DataSelect` if the answer is yes for **two or more** of these:
+
+- Will the option source come from `request`, `params`, or `valueEnum`?
+- Should filtering behavior change request execution or remote search state?
+- Do options need dynamic disabling logic tied to current filter text?
+- Is there a chance this control will move between local and remote option modes?
+- Would a standardized request-aware select be better than hand-writing option-fetch logic?
+
+If not, `Select` is usually the better fit.
+
+If the control belongs inside a wrapped form flow, decide separately whether the wrapper boundary or the request-aware option source is the more important abstraction.
+
+## Start with
+
+1. Decide whether the source of truth is `options`, `valueEnum`, or `request`.
+2. Choose local filtering or remote filtering intentionally.
+3. Add `params` only when the option set truly depends on external state.
+4. Tune debounce only after the request behavior feels correct.
+5. If the same choice belongs in a `FormItem` workflow, compare this skill against `../using-form-select/SKILL.md` instead of assuming there is a one-to-one wrapped `DataSelect` counterpart.
+
+## Minimal patterns
+
+### Local options mode
+
+```vue
+<DataSelect :options="options" />
+```
+
+### Enum mode
+
+```vue
+<DataSelect :value-enum="{ enabled: 'Enabled', disabled: 'Disabled' }" />
+```
+
+### Request mode
+
+```ts
+const request = async (
+  filterContent?: string,
+  params?: Record<string, any>
+) => {
+  return fetchUsers(filterContent, params);
+};
+```
+
+```vue
+<DataSelect :request="request" :params="params" />
+```
+
+### Remote filtering mode
+
+Use `filterable: 'remote'` when search text should drive the option source rather than local filtering.
+
+## Common mistakes
+
+- using `DataSelect` for purely local options that should just use `Select`
+- treating `filterable: true` and `filterable: 'remote'` as the same mode
+- passing both local options and expecting request behavior to still matter
+- tuning debounce before validating the request contract
+- forgetting that `disableOption` runs against the current option shape and filter content
+- assuming remote mode uses Element Plus `remoteMethod`; this component manages its own request path instead
+- assuming there is a dedicated wrapped `FormDataSelect` skill when the wrapper decision may still belong to `FormSelect`
+
+## Related skills
+
+- Local-only dropdown wrapper: `../using-select/SKILL.md`
+- Wrapped select for schema-driven form flows: `../using-form-select/SKILL.md`
+- General selection-pattern choice: `../building-selection-inputs/SKILL.md`
+
+## References
+
+- Props: `./references/props.md`
+- Examples: `./references/examples.md`
+- Gotchas: `./references/gotchas.md`

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

@@ -0,0 +1,67 @@
+# DataSelect examples
+
+## 1. Remote lookup select
+
+Use `request` when the option list depends on backend search, user input, or page params.
+
+Typical fit:
+
+- user or member lookup
+- project picker scoped by tenant
+- select controls backed by a search endpoint
+
+Recommended pattern:
+
+- keep `options` undefined
+- pass `request`
+- add `params` only when the backend needs parent context
+
+## 2. Local enum-backed select
+
+Use `valueEnum` when a full `options` array would be unnecessary repetition.
+
+Typical fit:
+
+- status fields
+- boolean-like mode selection
+- small fixed choice sets that may still benefit from this component’s API shape
+
+This keeps the configuration compact while preserving the same shell.
+
+## 3. Local filterable multi-select
+
+Use `filterable: true` with local options when the user needs to search within an already loaded option set.
+
+Typical fit:
+
+- tag-like multi-selects
+- grouped local options
+- client-side searchable lists
+
+Prefer this over remote filtering when all options are already available.
+
+## 4. Remote filtering workflow
+
+Use `filterable: 'remote'` when search input should change the option source rather than just narrowing what is already loaded.
+
+Typical fit:
+
+- large remote datasets
+- typeahead lookups
+- backend-scoped search dropdowns
+
+Recommended pattern:
+
+- treat `search` as query state
+- do not rely on `filterOption` in this mode
+- tune debounce after measuring UX and request volume
+
+## 5. Dynamic option disabling
+
+Use `disableOption` when choices stay visible but should become unavailable under specific conditions.
+
+Typical fit:
+
+- options blocked by permission state
+- options disabled for current filter context
+- grouped choices with conditional availability

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

@@ -0,0 +1,19 @@
+# DataSelect gotchas
+
+- `options` or `valueEnum` bypass request mode  
+  If either is present, the component does not use `request` for the option source.
+
+- `filterable: true` and `filterable: 'remote'` are different  
+  Local filtering runs `filterOption`. Remote filtering skips local filtering and treats the search text as remote state.
+
+- `filterOption` does not control remote filtering  
+  In remote mode, changing `filterOption` will not change the filtering behavior you see.
+
+- Debounce settings affect both UX and network load  
+  Tune `debounceTime` and `debounceWaitTime` intentionally instead of guessing.
+
+- Loading can come from two places  
+  The final loading state combines external `loading` and the component’s internal request loading.
+
+- Object values require `valueKey` awareness  
+  If option values are objects, stable identity depends on the configured `valueKey`.