@appsbd/vue3-appsbd-ui 1.0.18 → 1.0.20

package/.ai/ai_ref_usage_guide.md

@@ -0,0 +1,411 @@
+# Component Usage Guide — AI Reference
+
+A **decision map**, not an API reference. It answers two questions:
+
+1. **Which component does this job?** → the "Pick by Task" tables.
+2. **Which variant/mode of it fits this use case?** → the "Variant Reference" tables.
+
+Read this **before** choosing a component or a `variant`/`mode`/`type` prop value, then read that component's
+own `.ai/ai_ref_[Name].md` for exact props/events/slots. This file deliberately does **not** repeat props.
+
+```
+1. ai_ref_usage_guide.md  -> WHICH component does this job    (Pick by Task)
+2. ai_ref_usage_guide.md  -> WHICH variant/mode of it fits    (Variant Reference)
+3. .ai/ai_ref_[Name].md   -> exact props / events / slots
+4. AI_REFERENCE.md        -> full component index + global registration status
+```
+
+Components marked global in `AI_REFERENCE.md` are usable as `<ab-input-field>` after `app.use(AppsbdUI)`.
+All others must be imported from `vue3-appsbd-ui`. Where two options are equally valid, the surrounding UI
+decides — denser option for admin tables and toolbars, card/tile option for marketing, onboarding and settings.
+
+---
+
+## Pick by Task — Text & Value Input
+
+| I need to… | Use | Notes |
+| --- | --- | --- |
+| Take a short text value (name, title, code) | `AbInputField type="text"` | Default type; `type` can be omitted. |
+| Take a multi-line / paragraph value | `AbField type="textarea"` | Equivalent to `AbInputField as="textarea"`. |
+| Take an email address | `AbInputField type="email"` | Pair with `rules="required\|email"`. |
+| Take a password | `AbInputField type="password"` | Show/hide eye toggle is automatic; move it with `passIconPosition`. |
+| Take a freely typed number (price, ID, amount) | `AbNumberField` (no `variant`) | `AbInputField type="number"` is the same thing — prefer `AbNumberField` for intent. |
+| Take a small bounded count (qty, guests, rating) | `AbNumberField variant="stepper"` | Adds +/- buttons and `min`/`max`/`step` clamping. |
+| Take a phone number / URL | `AbInputField type="tel"` / `type="url"` | Any native input type passes through. |
+| Take an OTP / PIN / verification code | `AbPinInput` | `length`, `groupSize`, `showSeparator`. |
+| Show a value the user should copy (API key, ref no.) | `AbInputField copyable readonly` | Emits `copy-success` / `copy-error` — show your own toast. |
+| Add a unit/currency/icon beside the input | `AbInputField` `prefix` / `postfix` / `icon` slots | Don't hand-build an input-group. |
+| Enter a list of free-form tags/keywords | `AbInputTag` | Use `AbMultiSelect mode="tags"` when suggestions matter. |
+| Let the user pick a number on a track | `AbSlider` | `range` for a two-thumb min/max range. |
+
+## Pick by Task — Choice & Selection
+
+| I need to… | Use | Notes |
+| --- | --- | --- |
+| Turn one setting on/off | `AbToggle` | The default for enable/disable. `variant="column"` when it needs a description. |
+| Turn something on/off as a prominent card choice | `AbFormCheck variant="card"` | A UI-design call — use when the option deserves a titled card, not a switch row. |
+| Accept terms / a single yes-no checkbox | `AbFormCheck type="checkbox"` with one option | Use `AbToggle` only for instantly-applied settings, not form consent. |
+| Pick exactly one of 2–5 short options | `AbFormCheck type="radio" variant="segmented"` | `pill` for a chip look; `default` for a plain radio list. |
+| Pick exactly one of 2–6 options that need explaining | `AbFormCheck type="radio" variant="card"` | Each option gets `title` + `description`. |
+| Pick one option best shown by an icon | `AbFormCheck variant="icon-card"` | Pass `iconComponent` or `icon` per option. |
+| Pick one option that *is* a picture (theme, template) | `AbFormCheck variant="image-radio"` | `AbImageRadioInput` is the standalone image-tile alternative. |
+| Pick one from a long searchable list (7+) | `AbMultiSelect mode="single"` | Below ~7 options a radio group reads better than a dropdown. |
+| Pick several from a known list | `AbMultiSelect mode="multiple"` | Renders removable chips. |
+| Pick several, and allow new values | `AbMultiSelect mode="tags"` | Or `AbInputTag` when there is no option list at all. |
+| Select from a server-backed list | `AbMultiSelect isAjaxSearch` + `onSearch` | Keep local `options` for small fixed lists. |
+| Check several boxes at once (filters, permissions) | `AbFormCheck type="checkbox"` | `limit` caps how many can be checked. |
+| Pick a color | `AbColorPicker` | Swatch radio group, not a native color input. |
+
+## Pick by Task — Date, File & Media Input
+
+| I need to… | Use | Notes |
+| --- | --- | --- |
+| Pick a single date | `AbDateTimePicker mode="date"` | Default mode. |
+| Pick a time only | `AbDateTimePicker mode="time"` | Opening hours, reminder time. |
+| Pick date + time together | `AbDateTimePicker mode="datetime"` | Appointments, scheduled jobs. |
+| Pick a from–to date range | `AbDateTimePicker isRange` | Reporting periods, check-in/check-out. |
+| Format a date for display (no picker) | `abDate` | Dependency-free formatter; defaults from global config. |
+| Upload a photo / logo with a preview | `AbFileUploader type="image"` | Default mode, thumbnail preview built in. |
+| Upload a document / attachment | `AbFileUploader type="file"` + `allowedTypes` | Renders an extension icon instead of a thumbnail. |
+| Let a user set their profile picture | `AbAvatar variant="add"` | Use `variant="image"` once a photo exists. |
+| Validate a file outside a component | `useFileValidator` | Size / MIME / extension checks + icon resolvers. |
+| Rotate through images or content panels | `AbCarousel` | `orientation`, `autoplay`, `edgeFade`. |
+
+## Pick by Task — Form Assembly & Validation
+
+| I need to… | Use | Notes |
+| --- | --- | --- |
+| Render one field whose type is decided at runtime | `AbField type="…"` | text, email, password, number, url, textarea, select, multiselect, tag, checkbox, radio, toggle, switch. |
+| Render a whole form from a JSON/array config | `AbCustomField` + `fieldInputs` | For admin-configurable or API-driven forms. |
+| Build a fixed, hand-written form | Individual `Ab*` fields | Don't reach for `AbCustomField` just to avoid typing markup. |
+| Validate fields | `rules` prop + `abVeeRules` | VeeValidate-backed; errors render automatically under each field. |
+| Split a long form into steps | `AbWizard` + `AbWizardStep` | Per-step blocking validation via `AbSettingsForm`. |
+| Validate a wizard step before advancing | `AbSettingsForm :on-submit` inside the step | Returning `false` stops the wizard. |
+| Put a form inside a dialog | `AbModal` | Built-in VeeValidate form + loader overlay. |
+| Filter a list/table page | `AbFilterPanel` | The mode choice matters more than the props — see below. |
+| Build structured API request params | `abRequestParam` | Pagination / sorting / filtering DTOs. |
+| Set app-wide defaults (size, locale, formats) | `AppsbdUIConfigure` | Most components fall back to `globalConfig` when a prop is unset. |
+
+## Pick by Task — Actions, Dialogs & Confirmation
+
+| I need to… | Use | Notes |
+| --- | --- | --- |
+| Trigger the main action on a screen | `AbButton variant="solid"` | One solid primary button per view. |
+| Offer a secondary action next to it | `AbButton variant="outline"` | Cancel, Back, Reset. |
+| Navigate inside the SPA, styled as a button | `AbButton mode="router-link"` | `mode="link"` for external URLs. |
+| Show a loading state on the action itself | `AbButton` loader props | Don't overlay a separate spinner on a button. |
+| Confirm a destructive action inline (row delete) | `AbConfirmPopover` | Async `onConfirm` with a built-in loader — no modal needed. |
+| Confirm something the user must not miss | `useAlert` `type="confirm"` | `variation="top-color-bar"` for irreversible actions. |
+| Confirm with an async request before closing | `useAlert` `type="confirm-ajax"` | Dialog stays open while the promise resolves. |
+| Show a dialog with a real form in it | `AbModal` | Use `AbEasyModal` when you only need open/close. |
+| Open a quick dialog from a trigger element | `AbEasyModal` | Exposes `openModal()` / `closeModal()`. |
+| Show a dropdown menu or rich popup | `AbPopover` | `trigger`: click / hover / focus / touch / manual. |
+| Explain an icon button on hover | `v-tooltip` directive | Plain string hints — cheapest option. |
+| Show rich or interactive hover content | `AbTooltip` | Slot-driven; use the directive for simple text. |
+
+## Pick by Task — Navigation & Page Structure
+
+| I need to… | Use | Notes |
+| --- | --- | --- |
+| Build an admin/dashboard page shell | `AbMainLayout` | Header, body, footer, left/right sidebar drawers; mobile-responsive. |
+| Build the left navigation | `AbSidebar` + `AbSideMenuItem` | Collapse state persists to `localStorage`. |
+| Switch between sibling content panels | `AbTabs` + `AbTab` | Only one panel visible at a time. |
+| Use tabs as real routes | `AbTabs isRouteMode` | Each tab navigates instead of swapping content. |
+| Reveal stacked sections on demand (FAQ, settings groups) | `AbAccordion` + `AbAccordionItem` | Pick over tabs when sections read in sequence; `multiple` allows several open. |
+| Walk the user through an ordered flow | `AbWizard` + `AbWizardStep` | Order matters — that's what separates it from tabs. |
+| Show keyboard shortcuts in the UI | `AbKbd` / `AbKbdGroup` | Group for chords like Ctrl + K. |
+| Style a scrollable region's scrollbar | `AbScrollbar` | Also emits scroll-position events (infinite scroll). |
+| Offer light/dark switching | `AbDarkModeToggler` + `useTheme` | Syncs with system preference and `localStorage`. |
+| Branch layout on viewport width | `useResponsive` | Bootstrap-5-aligned breakpoints. |
+
+## Pick by Task — Data Display
+
+| I need to… | Use | Notes |
+| --- | --- | --- |
+| Show rows of records | `AbTable` | Column defs + per-cell/header slots + empty slot. |
+| Show rows with grouping, subrows, column chooser, card view | `EliteGrid` | **External** peer dep. Only when `AbTable` genuinely can't do it. |
+| Plot data | `AbChart` | Apache ECharts — full option object or simplified props. |
+| Show a single KPI number | `AbCard variant="tile"` | One number + label. |
+| Show a repeated list row (notification, activity) | `AbCard variant="item"` | Row layout, not a page section. |
+| Show a recommendation / AI callout | `AbCard variant="insight"` | Actionable suggestion panel. |
+| Wrap any page section in a box | `AbCard` (default) | Header / body / footer slots. |
+| Label a status or count | `AbBadge` | `solid` to stand out, `outline` for dense lists. |
+| Show a person's picture | `AbAvatar` | Sizes `xs`–`xxl`. |
+| Present pricing tiers side by side | `AbPricingContainer` + `AbPricingCard` | One card per tier. |
+| Compare tiers feature-by-feature | `AbPricingTable` | Feature rows × package columns. |
+
+## Pick by Task — Feedback & Loading States
+
+| I need to… | Use | Notes |
+| --- | --- | --- |
+| Confirm an action succeeded, non-blocking | `useToast` | `toast.success()` / `.error()` / `.warning()` / `.info()`. |
+| Report something the user must acknowledge | `useAlert` `type="alert"` | Blocking dialog — not for routine success messages. |
+| Show content is loading, shape known | `AbSkeleton` | Better than a spinner for lists and cards. |
+| Show determinate progress (upload %, steps done) | `AbProgressbar` | Colors + sizes `xs`–`xxl`. |
+| Show an action in flight on a button | `AbButton` loader props | Keeps trigger and feedback in one place. |
+| Show a form-wide busy state | `AbModal` loader overlay | Built into the modal, no separate element. |
+
+## Pick by Task — Chat & Voice
+
+| I need to… | Use | Notes |
+| --- | --- | --- |
+| Build a full chat screen (list + composer) | `AbChatBox` | Header, message list, empty/typing states — all slot-overridable. |
+| Add only the message composer | `AbChatInput` | Auto-growing textarea, attachments, add/more dropdown, built-in mic. |
+| Add rows to that composer's dropdown | `AbChatInputMenuItem` | Presentational icon / name / description / action row. |
+| Add voice-to-text to an existing input | `AbVoiceButton` | Same engine as `AbChatInput`'s mic, standalone via `v-model`. |
+
+---
+
+## Commonly Confused Pairs
+
+Where more than one component legitimately solves the same problem, this is the tie-breaker.
+
+| Goal | Option A | Option B | Pick |
+| --- | --- | --- | --- |
+| Numeric input | `AbInputField type="number"` | `AbNumberField` | Identical output — `AbNumberField` is a thin wrapper. Prefer it for intent; use `AbInputField` when the same field can switch types. |
+| Enable / disable something | `AbToggle` | `AbFormCheck variant="card"` | Switch row in settings lists; card when the option needs a title, description or visual weight. UI-design call. |
+| Free-form tag entry | `AbInputTag` | `AbMultiSelect mode="tags"` | `AbInputTag` when there is no option list; `AbMultiSelect` when suggestions or async search matter. |
+| Pick one of a few options | `AbFormCheck type="radio"` | `AbMultiSelect mode="single"` | Radio below ~7 options (all visible); dropdown above that, or when space is tight. |
+| Image-based option picker | `AbFormCheck variant="image-radio"` | `AbImageRadioInput` | `AbFormCheck` inside a form with other checks; `AbImageRadioInput` as a standalone tile picker. |
+| Confirm a delete | `AbConfirmPopover` | `useAlert type="confirm"` | Popover for per-row/inline actions; alert dialog when the consequence is severe or global. |
+| Show a dialog | `AbModal` | `AbEasyModal` | `AbModal` when it contains a validated form; `AbEasyModal` for plain content with imperative open/close. |
+| Group content into sections | `AbTabs` | `AbAccordion` | Tabs for mutually exclusive panels; accordion when sections stack vertically and several may be read. |
+| Hover explanation | `v-tooltip` directive | `AbTooltip` / `AbPopover` | Directive for a string; `AbTooltip` for rich content; `AbPopover` when the content is interactive. |
+| Data grid | `AbTable` | `EliteGrid` | Always `AbTable` first. `EliteGrid` only for grouping, subrows, card view or column chooser. |
+| Success / error feedback | `useToast` | `useAlert` | Toast for routine outcomes; alert only when the user must acknowledge before continuing. |
+| Build a form | Individual `Ab*` fields | `AbCustomField` | Hand-written fields for fixed forms; `AbCustomField` only when the field list is data-driven. |
+
+---
+
+## Variant Reference — AbFormCheck / AbRadioInput
+
+Full prop reference: [ai_ref_AbFormCheck.md](./ai_ref_AbFormCheck.md).
+`type` decides checkbox vs radio; `variant` decides how it looks.
+
+| Variant | Use it when | Avoid it / use instead |
+| --- | --- | --- |
+| `default` | Plain checkbox/radio list — settings, row selection, long option lists (7+). | Options deserve visual weight → a card variant. |
+| `card` | 2–6 choices, each with a title **and** description — plan, shipping method, account type. | 7+ options, or no description needed → `segmented`/`pill`. |
+| `icon-card` | Same as `card`, but one icon explains the option better than prose. | The option needs a real photo → `image-radio`. |
+| `card-flat-check` | Card look with a flat, shadow-free checked state and a centered indicator. | The default card glow already fits. |
+| `image-radio` | The options *are* images — theme, template, banner picker. `isInline` switches big tile ↔ compact chip. | No natural image per option → `card`/`icon-card`. |
+| `segmented` | 2–5 short labels acting like a switch — List/Grid, Monthly/Yearly. | An option needs a description or icon → `card`. |
+| `pill` | Same as `segmented`, rounded chip look — tag-style filters in a toolbar. | Must read as a form field group → `default`/`segmented`. |
+
+Modifier props:
+
+| Prop | Use it when |
+| --- | --- |
+| `isInline` | Options sit in a row instead of stacking. For `image-radio` it selects the compact chip look. |
+| `checkRight` | The indicator sits on the right of the card instead of the left. |
+| `isBoxShadow` | Card-family only: checked state glows instead of changing border color. |
+| `limit` | Checkbox mode: cap how many options can be selected. |
+| `selectorPosition` | `image-radio` only: which corner the check badge sits in. |
+
+## Variant Reference — AbCard
+
+Full prop reference: [ai_ref_AbCard.md](./ai_ref_AbCard.md).
+
+| Variant | Use it when | Avoid it / use instead |
+| --- | --- | --- |
+| `default` | Generic bordered container — form sections, dashboard widgets. | A more specific layout below fits. |
+| `tile` | One big number + label — KPI tiles. | Content is more than a number + label → `default`/`item`. |
+| `item` | A repeatable list row — notification, activity feed, search result. | It's a whole page section → `default`. |
+| `insight` | A suggestion/recommendation panel — "You could save 15%…". | Plain content with no action → `default`. |
+
+`variation` is an unvalidated escape hatch — any string is appended as a raw class. Use it only for one-off
+custom classes, never instead of `variant`.
+
+## Variant Reference — AbButton
+
+Full prop reference: [ai_ref_AbButton.md](./ai_ref_AbButton.md).
+
+| Prop value | Use it when | Avoid it / use instead |
+| --- | --- | --- |
+| `variant="solid"` (default) | The primary or only action — Save, Submit, Create. | It sits next to another solid button → `outline`. |
+| `variant="outline"` | Secondary/tertiary action — Cancel, Back, filter toggles. | It's the primary action → `solid`. |
+| `variant="animated-round"` | A pill-shaped loading button (spinner only, text hidden while animating) — no `isRounded`/`isHideTextOnAnimate` props needed; bind `isAnimated` to a loading ref. | A plain (non-rounded) loading button → `isAnimated`. |
+| `mode="button"` (default) | In-page action or form submit. | The click should navigate. |
+| `mode="link"` | External URL styled as a button. | Internal route → `router-link`. |
+| `mode="router-link"` | Internal SPA navigation styled as a button. | External URL → `link`. |
+| `color="danger"` | Destructive actions — pair with `AbConfirmPopover` or a confirm alert. | Non-destructive actions. |
+
+## Variant Reference — AbBadge
+
+Full prop reference: [ai_ref_AbBadge.md](./ai_ref_AbBadge.md).
+
+| Variant | Use it when | Avoid it / use instead |
+| --- | --- | --- |
+| `solid` (default) | Status that must stand out — "New", unread counts, error states. | Dense table/list where fills feel heavy → `outline`. |
+| `outline` | Low-emphasis labels, or many badges together (tag list). | It needs to grab attention → `solid`. |
+
+## Variant Reference — AbToggle
+
+Full prop reference: [ai_ref_AbToggle.md](./ai_ref_AbToggle.md).
+
+| Variant | Use it when | Avoid it / use instead |
+| --- | --- | --- |
+| `inline` (default) | Label + switch side by side — compact settings rows. | The setting needs a paragraph → `column`. |
+| `inline-left` | The switch should lead before the label. | No reason to lead with the switch → `inline`. |
+| `column` | Label + description stacked above the switch — settings pages. | The label alone is self-explanatory → `inline`. |
+
+`trueValue`/`falseValue` default to `"Y"`/`"N"` from global config — set them explicitly when the API expects
+booleans.
+
+## Variant Reference — AbInputField / AbNumberField / AbField (`type="number"`)
+
+Full prop reference: [ai_ref_AbInputField.md](./ai_ref_AbInputField.md),
+[ai_ref_AbNumberField.md](./ai_ref_AbNumberField.md), [ai_ref_AbField.md](./ai_ref_AbField.md).
+All three route to the same stepper implementation.
+
+| Setting | Use it when | Avoid it / use instead |
+| --- | --- | --- |
+| plain (no `variant`) | Freely typed value — price, arbitrary quantity, ID. | Small bounded range where clicking beats typing → `stepper`. |
+| `variant="stepper"` | Small bounded count — cart quantity, guests, page size, rating. | Large/unbounded range, or clamping is meaningless → plain. |
+| `variant="inset"` | Compact, modern form where the label should sit inside the bordered box above the value (AbInputField only). | Dense multi-column filter rows or very small `xs` fields → default label-above. |
+| `type="password"` | Any secret value — show/hide toggle is added automatically. | An OTP code → `AbPinInput`. |
+| `copyable` | A generated value the user copies — API key, invite link, reference no. | An editable field the user types into. |
+| `prefix` / `postfix` | A unit, currency symbol or domain fragment belongs beside the value. | The affix is actually a separate action → use the `icon` slot. |
+| `isCodeInput` | The field holds a code/identifier needing the mega-input treatment. | Ordinary text. |
+
+## Variant Reference — AbMultiSelect
+
+Full prop reference: [ai_ref_AbMultiSelect.md](./ai_ref_AbMultiSelect.md).
+
+| Mode / prop | Use it when | Avoid it / use instead |
+| --- | --- | --- |
+| `mode="single"` (default) | Exactly one value — country, category, assignee. | More than one value allowed → `multiple`. |
+| `mode="multiple"` | Several values from a known list, shown as removable chips. | The user may type new values → `tags`. |
+| `mode="tags"` | Free-form entry with optional suggestions. | The value set is fixed → `multiple` (prevents typos). |
+| `isAjaxSearch` + `onSearch` | Large or server-backed option lists — customers, products. | Small local list → pass `options` directly. |
+
+## Variant Reference — AbDateTimePicker
+
+Full prop reference: [ai_ref_AbDateTimePicker.md](./ai_ref_AbDateTimePicker.md).
+
+| Mode / prop | Use it when | Avoid it / use instead |
+| --- | --- | --- |
+| `mode="date"` (default) | A single calendar date — birthdate, due date. | Time matters too → `datetime`. |
+| `mode="time"` | Time only — reminder time, opening hours. | A date is also needed → `datetime`. |
+| `mode="datetime"` | Both matter — meetings, appointments, event start. | Only one of the two matters → `date`/`time`. |
+| `isRange` | A from–to range — reporting period, check-in/check-out. | A single point in time. |
+
+## Variant Reference — AbFilterPanel
+
+Full prop reference: [ai_ref_AbFilterPanel.md](./ai_ref_AbFilterPanel.md).
+The mode is driven by how many fields exist and how many a user applies at once — not by looks.
+
+| Mode | Use it when | Avoid it / use instead |
+| --- | --- | --- |
+| standard (no flag) | "Pick a field, then a value" search bar — a handful of fields, one at a time. | Several fields filtered at once → `isAdvance`/`isQuickAdvance`. |
+| `isSingle` | The simplest search box — one always-visible field. Add `isAutoSearch` for live typing. | Multiple distinct fields → standard/`isAdvance`. |
+| `isAdvance` | Data-heavy admin lists where users routinely filter by many fields at once — every field expanded. | Tight space, or only 1–3 fields used → `isQuickAdvance`/`isBuilderFilter`. |
+| `isQuickAdvance` | Compact multi-select quick filters without the full `isAdvance` footprint. | A full field-by-field layout is wanted → `isAdvance`. |
+| `isBuilderFilter` | Many possible fields (10+), only 1–3 applied at a time — Shopify-style "+ Add filter". | Few fields, or users always fill them all → standard/`isAdvance`. |
+| `canScan` | Inventory/POS lookup where scanning a barcode beats typing. | No physical codes to scan. |
+
+## Variant Reference — AbTabs
+
+Full prop reference: [ai_ref_AbTabs.md](./ai_ref_AbTabs.md).
+
+| Variation / prop | Use it when | Avoid it / use instead |
+| --- | --- | --- |
+| `outline` (default) | General-purpose content tab switcher. | A style below fits the surrounding UI better. |
+| `pills` | Filter-like groups — All / Active / Archived. | Page-level content tabs → `outline`/`underline`. |
+| `underline` | Minimal page-level nav under a header — Profile / Settings / Billing. | Tabs need more separation → `pills`/`bg-secondary`. |
+| `bg-secondary` | Tabs embedded inside a card or toolbar. | Tabs sit directly on the page background. |
+| `isRouteMode` | Each tab is a real route, not in-page content. | Tabs just swap visible content — leave it off. |
+
+## Variant Reference — AbAccordion
+
+Full prop reference: [ai_ref_AbAccordion.md](./ai_ref_AbAccordion.md).
+
+| Prop | Use it when |
+| --- | --- |
+| default (no flag) | Only one section open at a time — FAQ, guided settings. |
+| `multiple` | Several sections may be open together — long reference/settings pages. |
+| `iconPosition="left"` | The chevron should lead the title (default is `"right"`). |
+| `variant="responsive"` | Sections should all be visible on large screens (no toggle icon) but collapse into a normal accordion on small screens. `breakpoint` sets the switch point. |
+
+## Variant Reference — AbWizard
+
+Full prop reference: [ai_ref_AbWizard.md](./ai_ref_AbWizard.md).
+
+| Variant / prop | Use it when | Avoid it / use instead |
+| --- | --- | --- |
+| `variant="default"` | Inline multi-step form embedded in a page. | Triggered from a button without leaving the page → a modal variant. |
+| `variant="circular"` | Same, with circular numbered step markers — onboarding. | A flatter indicator fits → `default`. |
+| `variant="modal"` | Flow triggered from a button that must not navigate away. | The wizard is the whole page → `default`/`circular`. |
+| `variant="circular-modal"` | Modal wizard with circular step markers. | — |
+| `orientation="horizontal"` (default) | 2–4 steps, normal page width. | Many steps or a side step list → `vertical`. |
+| `orientation="vertical"` | Many steps, or a settings-style step list beside the content. | Short top-to-bottom flow → `horizontal`. |
+
+## Variant Reference — AbPricingCard
+
+Full prop reference: [ai_ref_AbPricingCard.md](./ai_ref_AbPricingCard.md).
+
+| Variant | Use it when | Avoid it / use instead |
+| --- | --- | --- |
+| `default` | A standard tier, no special emphasis. | One tier should stand out or be de-emphasized. |
+| `minimal` | Low-emphasis tier — "Free" or "Contact us". | It's the tier you want picked → `highlighted`. |
+| `highlighted` | The recommended tier — pair with `recommended` + a `badge`. | A plain tier → `default`. |
+| `badge-price` | The price itself needs a discount/"% off" treatment. | Standard price display → `default`/`highlighted`. |
+
+## Variant Reference — AbAvatar
+
+Full prop reference: [ai_ref_AbAvatar.md](./ai_ref_AbAvatar.md).
+
+| Variant | Use it when | Avoid it / use instead |
+| --- | --- | --- |
+| `image` (default) | A profile photo exists (`src` is set). | No photo yet → `add`. |
+| `add` | Upload placeholder in a profile create/edit form. Pairs with `change` / `triggerFileSelect()`. | A photo already exists → `image`. |
+
+## Variant Reference — AbFileUploader
+
+Full prop reference: [ai_ref_AbFileUploader.md](./ai_ref_AbFileUploader.md).
+
+| Type | Use it when | Avoid it / use instead |
+| --- | --- | --- |
+| `type="image"` (default) | Avatar/photo/logo upload where a thumbnail helps. | Non-image files → `type="file"`. |
+| `type="file"` | Documents and attachments; needs `allowedTypes`, shows an extension icon. | Always an image → `type="image"`. |
+| `isCrop` (with `type="image"`) | The user may want to crop the picked image (avatar, banner); Cancel discards the pick. `cropAspectRatio` locks the shape. | The image is always used as-is → leave `isCrop` off. |
+| `variant="dropzone"` | A prominent upload card with title, helper text (size limits) and an `AbButton`; also accepts drag & drop. `:is-border="false"` swaps the dashed border for a box-shadow. | A compact thumbnail box inside a dense form → default variant. |
+
+## Variant Reference — useAlert
+
+Full prop reference: [ai_ref_useAlert.md](./ai_ref_useAlert.md).
+
+`type` — what the dialog does:
+
+| Type | Use it when |
+| --- | --- |
+| `alert` (default) | Inform only — one dismiss button. |
+| `confirm` | Ask before proceeding — synchronous yes/no. |
+| `confirm-ajax` | Ask, then run an async request while the dialog stays open. |
+
+`variation` — how it looks:
+
+| Variation | Use it when | Avoid it / use instead |
+| --- | --- | --- |
+| `default` | General-purpose — the safe choice. | A style below fits the product surface better. |
+| `modern` | A visually elevated dialog for customer-facing product surfaces. | Dense admin tooling → `minimal`. |
+| `minimal` | Quick, low-chrome confirmations in dense admin tools. | Destructive action → `top-color-bar`. |
+| `top-color-bar` | Destructive / irreversible actions needing an at-a-glance severity cue. | Routine confirmation → `default`/`minimal`. |
+
+---
+
+## Composables & Utilities
+
+| API | Reach for it when |
+| --- | --- |
+| `useAlert` | A blocking dialog is needed — alerts, confirms, async confirms. |
+| `useToast` | Non-blocking success/error/warning/info feedback. |
+| `useTheme` | Reading or toggling light/dark mode in your own UI. |
+| `useResponsive` | Layout must branch on viewport width in script, not CSS. |
+| `useFileValidator` | Validating files outside `AbFileUploader`, or resolving file icons. |
+| `abDate` | Formatting dates for display without pulling in a date library. |
+| `abVeeRules` | Pre-built, localized VeeValidate rules for `rules` props. |
+| `abTranslate` | Localizing your own strings the same way components do. |
+| `abRequestParam` | Building pagination/sort/filter payloads for list APIs. |
+| `abEventBus` / `emitterObj` | Cross-component events where props/provide would be awkward. |
+| `AppsbdUIConfigure` | Setting library-wide defaults once — size, locale, date formats, true/false values. |

package/.ai/ai_ref_useAlert.md

@@ -2,6 +2,8 @@
 
 Provides a procedural API to trigger modal alerts, notifications, and confirmations using the global `$alert` instance.
 
+> This is backed internally by `AbBaseAlert`, a mount-only root the plugin's `install()` mounts once into `document.body` — it is **not** a named export of the package. `import { AbBaseAlert } from "vue3-appsbd-ui"` resolves to `undefined`. Always reach it through `useAlert()` (or the `$alert` global property) as shown below.
+
 ## Usage
 
 ```html

package/.ai/ai_ref_useToast.md

@@ -2,6 +2,8 @@
 
 Provides a procedural API to spawn toast notifications using the globally registered `$toast` instance.
 
+> This is backed internally by `AbToast`, a mount-only root the plugin's `install()` mounts once into `document.body` — it is **not** a named export of the package. `import { AbToast } from "vue3-appsbd-ui"` resolves to `undefined`. Always reach it through `useToast()` (or the `$toast` global property) as shown below.
+
 ## Usage
 
 ```html

package/AI_REFERENCE.md

@@ -8,19 +8,22 @@
 
 **Upgrading a consuming project?** Read [.ai/ai_ref_migration_guide.md](./.ai/ai_ref_migration_guide.md) — per-version breaking-change find/replace steps meant for an AI agent to apply mechanically when bumping this library's version in another project.
 
+**Building a UI with this library? Read [.ai/ai_ref_usage_guide.md](./.ai/ai_ref_usage_guide.md) first.** It is the decision map: "Pick by Task" tables mapping a plain-language need to the right component and prop (*take a password* → `AbInputField type="password"`; *enable/disable something* → `AbToggle`, or `AbFormCheck variant="card"` when the option deserves a card), "Variant Reference" tables for every component with more than one variant/mode, and a "Commonly Confused Pairs" tie-breaker table (`AbInputField type="number"` vs `AbNumberField`, `AbTable` vs `EliteGrid`, `useToast` vs `useAlert`, …). Use the table below to confirm a component exists and how it's registered, that guide to choose between components, then `.ai/ai_ref_[Name].md` for exact props.
+
 ## Components & APIs
 
 ✅ = globally registered via `app.use(AppsbdUI)` — all others require `import { X } from "vue3-appsbd-ui"`.
 
 | Component / API                |  G  | Purpose                                                                                                                | Reference                                                              |
 | :----------------------------- | :-: | :--------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------- |
-| `AbButton`                     | ✅  | Customizable push button with loader animation.                                                                        | [.ai/ai_ref_AbButton.md](./.ai/ai_ref_AbButton.md)                     |
-| `AbCard`                       | ✅  | Flexible card container; use CSS-class variants (e.g. `tile-card`, `item-card`, `insight-card`) for layout variations. | [.ai/ai_ref_AbCard.md](./.ai/ai_ref_AbCard.md)                         |
+| `AbButton`                     | ✅  | Customizable push button with loader animation. Default `variant` is `"solid"`.                                        | [.ai/ai_ref_AbButton.md](./.ai/ai_ref_AbButton.md)                     |
+| `AbActionButton`               |  —  | `AbButton` wrapper for CRUD-style actions (add/edit/save/delete/cancel/…) — single `action` string, or an `actions` array to render a whole group from one component — emits a single `action` event, built-in confirm for `delete`. | [.ai/ai_ref_AbActionButton.md](./.ai/ai_ref_AbActionButton.md)         |
+| `AbCard`                       | ✅  | Flexible card container. Default `variant` is `"default"`; also `"tile"`, `"item"`, `"insight"` layout variants.       | [.ai/ai_ref_AbCard.md](./.ai/ai_ref_AbCard.md)                         |
 | `AbModal`                      | ✅  | Full-featured dialog with built-in VeeValidate form, loader, and message-only mode.                                    | [.ai/ai_ref_AbModal.md](./.ai/ai_ref_AbModal.md)                       |
 | `AbProgressbar`                | ✅  | Animated Bootstrap progress bar with color and size variants.                                                          | [.ai/ai_ref_AbProgressbar.md](./.ai/ai_ref_AbProgressbar.md)           |
-| `AbInputField`                 | ✅  | Core text input with VeeValidate, prefix/postfix/icon slots.                                                           | [.ai/ai_ref_AbInputField.md](./.ai/ai_ref_AbInputField.md)             |
-| `AbNumberField`                | ✅  | Numeric input with increment/decrement buttons, min/max/step clamping, and VeeValidate integration.                    | [.ai/ai_ref_AbNumberField.md](./.ai/ai_ref_AbNumberField.md)           |
-| `AbField`                      | ✅  | Polymorphic field wrapper - renders any input type via a `type` prop.                                                  | [.ai/ai_ref_AbField.md](./.ai/ai_ref_AbField.md)                       |
+| `AbInputField`                 | ✅  | Core text input with VeeValidate, prefix/postfix/icon slots. `variant="stepper"` turns it into a numeric stepper (min/max/step, +/- buttons); `variant="inset"` puts the label inside the bordered box; `variant="outlined"` is a floating label that moves onto the top border on focus/filled. | [.ai/ai_ref_AbInputField.md](./.ai/ai_ref_AbInputField.md)             |
+| `AbNumberField`                | ✅  | Numeric input. Defaults to a plain `type="number"` input; `variant="stepper"` renders `AbInputField`'s numeric stepper (min/max/step, +/- buttons) — thin wrapper around `AbInputField`. | [.ai/ai_ref_AbNumberField.md](./.ai/ai_ref_AbNumberField.md)           |
+| `AbField`                      | ✅  | Polymorphic field wrapper - renders any input type via a `type` prop. `type="number"` + `variant="stepper"` renders `AbInputField`'s numeric stepper. | [.ai/ai_ref_AbField.md](./.ai/ai_ref_AbField.md)                       |
 | `AbCustomField`                | ✅  | Dynamic form scaffold driven by a `fieldInputs` array.                                                                 | [.ai/ai_ref_AbCustomField.md](./.ai/ai_ref_AbCustomField.md)           |
 | `AbDateTimePicker`             | ✅  | Date / time / range picker. Also import `v-calendar/style.css` in consuming app.                                       | [.ai/ai_ref_AbDateTimePicker.md](./.ai/ai_ref_AbDateTimePicker.md)     |
 | `AbFormCheck` / `AbRadioInput` | ✅  | Checkbox / radio group (default, card, icon-card, card-flat-check, image-radio, segmented, pill variants). `AbRadioInput` is an alias of `AbFormCheck`. | [.ai/ai_ref_AbFormCheck.md](./.ai/ai_ref_AbFormCheck.md)               |
@@ -32,16 +35,18 @@
 | `AbEasyModal`                  |  —  | Lightweight modal wrapper that exposes `openModal` / `closeModal`.                                                     | [.ai/ai_ref_AbEasyModal.md](./.ai/ai_ref_AbEasyModal.md)               |
 | `AbPinInput`                   |  —  | Segmented PIN / OTP entry field.                                                                                       | [.ai/ai_ref_AbPinInput.md](./.ai/ai_ref_AbPinInput.md)                 |
 | `AbAvatar`                     |  —  | Profile image (or file-upload avatar variant).                                                                         | [.ai/ai_ref_AbAvatar.md](./.ai/ai_ref_AbAvatar.md)                     |
-| `AbTabs`                       |  —  | Tabbed interface container; supports router-link mode.                                                                 | [.ai/ai_ref_AbTabs.md](./.ai/ai_ref_AbTabs.md)                         |
+| `AbTabs`                       |  —  | Tabbed interface container; supports router-link mode. Default `variation` is `"outline"`.                             | [.ai/ai_ref_AbTabs.md](./.ai/ai_ref_AbTabs.md)                         |
 | `AbTab`                        |  —  | Individual tab pane / link.                                                                                            | [.ai/ai_ref_AbTab.md](./.ai/ai_ref_AbTab.md)                           |
+| `AbAccordion`                  |  —  | Shadcn-style collapsible group container. Default `iconPosition` is `"right"`; opening one item closes others unless `multiple`.  | [.ai/ai_ref_AbAccordion.md](./.ai/ai_ref_AbAccordion.md)               |
+| `AbAccordionItem`               |  —  | Single collapsible row inside `AbAccordion`. Body slot accepts any content.                                           | [.ai/ai_ref_AbAccordionItem.md](./.ai/ai_ref_AbAccordionItem.md)       |
 | `AbImageRadioInput`            |  —  | Image-based radio group for visual option pickers.                                                                     | [.ai/ai_ref_AbImageRadioInput.md](./.ai/ai_ref_AbImageRadioInput.md)   |
-| `AbBadge`                      |  —  | Status / count label (Bootstrap badge utility).                                                                        | [.ai/ai_ref_AbBadge.md](./.ai/ai_ref_AbBadge.md)                       |
+| `AbBadge`                      |  —  | Status / count label (Bootstrap badge utility). Default `variant` is `"solid"`.                                        | [.ai/ai_ref_AbBadge.md](./.ai/ai_ref_AbBadge.md)                       |
 | `AbSidebar`                    |  —  | Collapsible sidebar navigation with optional search.                                                                   | [.ai/ai_ref_AbSidebar.md](./.ai/ai_ref_AbSidebar.md)                   |
 | `AbSideMenuItem`               |  —  | Sidebar nav item (router-link, anchor, submenu parent, or section title).                                              | [.ai/ai_ref_AbSideMenuItem.md](./.ai/ai_ref_AbSideMenuItem.md)         |
 | `AbMainLayout`                 |  —  | Full-page application shell with left/right sidebar drawers, header, body, and footer slots. Mobile-responsive.        | [.ai/ai_ref_AbMainLayout.md](./.ai/ai_ref_AbMainLayout.md)             |
 | `AbSlider`                     |  —  | Single or range numeric slider.                                                                                        | [.ai/ai_ref_AbSlider.md](./.ai/ai_ref_AbSlider.md)                     |
 | `AbColorPicker`                |  —  | Radio-style color swatch picker.                                                                                       | [.ai/ai_ref_AbColorPicker.md](./.ai/ai_ref_AbColorPicker.md)           |
-| `AbFileUploader`               |  —  | File upload field with size validation; image mode (default, preview) or file mode (`allowedTypes` + extension icons). | [.ai/ai_ref_AbFileUploader.md](./.ai/ai_ref_AbFileUploader.md)         |
+| `AbFileUploader`               |  —  | File upload field with size validation; image mode (default, preview) or file mode (`allowedTypes` + extension icons); `variant="dropzone"` for a large icon/title/description/button card with drag & drop. | [.ai/ai_ref_AbFileUploader.md](./.ai/ai_ref_AbFileUploader.md)         |
 | `AbFilterPanel`                |  —  | Advanced filter panel with search and scan modes.                                                                      | [.ai/ai_ref_AbFilterPanel.md](./.ai/ai_ref_AbFilterPanel.md)           |
 | `AbSettingsForm`               |  —  | Settings-style form that auto-registers as a wizard step validator.                                                    | [.ai/ai_ref_AbSettingsForm.md](./.ai/ai_ref_AbSettingsForm.md)         |
 | `AbScrollbar`                  |  —  | Styled custom scrollbar wrapper with scroll events.                                                                    | [.ai/ai_ref_AbScrollbar.md](./.ai/ai_ref_AbScrollbar.md)               |
@@ -63,6 +68,7 @@
 | `AbChatBox`                    |  —  | Full chat conversation container (header, message list, empty/typing states) built on `AbChatInput`; every part is slot-overridable. | [.ai/ai_ref_AbChatBox.md](./.ai/ai_ref_AbChatBox.md)                   |
 | `AbVoiceButton`                |  —  | Standalone Web Speech API voice-to-text mic button (v-model), no composer attached — same engine as `AbChatInput`'s built-in mic. | [.ai/ai_ref_AbVoiceButton.md](./.ai/ai_ref_AbVoiceButton.md)           |
 | `AbDarkModeToggler`            |  —  | Light / dark theme toggle (pairs with `useTheme`).                                                                     | [.ai/ai_ref_AbDarkModeToggler.md](./.ai/ai_ref_AbDarkModeToggler.md)   |
+| `EliteGrid`                    |  —  | **External** (`@appsbd/vue3-elite-grid` peer dep, not developed in this library) — advanced data grid: sorting, grouping, subrows, card view, column chooser. Prefer `AbTable` unless you need these. | [.ai/ai_ref_EliteGrid.md](./.ai/ai_ref_EliteGrid.md)                   |
 | `useAlert`                     |  —  | Procedural API to trigger SweetAlert-based modal alerts, notifications, and confirmations.                             | [.ai/ai_ref_useAlert.md](./.ai/ai_ref_useAlert.md)                     |
 | `abEventBus` / `emitterObj`    |  —  | Lightweight global event bus using `tiny-emitter`.                                                                     | [.ai/ai_ref_abEventBus.md](./.ai/ai_ref_abEventBus.md)                 |
 | `useTheme`                     |  —  | Composable for light/dark theme toggling with localStorage and system preference sync.                                 | [.ai/ai_ref_useTheme.md](./.ai/ai_ref_useTheme.md)                     |