@appsbd/vue3-appsbd-ui 1.0.19 → 1.0.20

package/.ai/ai_ref_migration_guide.md

@@ -29,6 +29,11 @@
   - Find: `<AbFilterPanel ...>` usages in either default (standard) mode or `is-advance`/`isAdvance` mode that relied on the Bootstrap grid for field widths — either the default 2-columns-per-row layout, or an explicit `advance-container-class`/`advanceContainerClass` Bootstrap grid class (e.g. `"col-12 col-sm-6"`).
   - Replace: nothing required to keep working — fields now lay out via flex (`flex: 1 1 240px`, wraps automatically), which also fixes long field labels getting clipped. A Bootstrap grid class passed to `advance-container-class` no longer has a `.row` ancestor to size against and should be replaced with either a plain width class/CSS, or the new `width` prop on the individual field component (`AbInputField`/`AbMultiSelect`/`AbDateTimePicker`) inside `filterOptions`.
 
+- **`AbNumberField` no longer always renders as a stepper — default changed to a plain `type="number"` input.**
+  - Find: `<AbNumberField ...>` usages with no `variant` prop (relying on the old implicit always-stepper look: minus/plus buttons, min/max clamping).
+  - Replace: add `variant="stepper"` to keep the previous appearance and behavior exactly. No change needed if the plain-input look is acceptable.
+  - See [`.ai/ai_ref_AbNumberField.md`](./ai_ref_AbNumberField.md) for the full `variant` prop.
+
 ### ℹ️ Also shipped (no action needed)
 
 - `AbFilterPanel`'s `.apbd-filter-chip-group` (quick-advance multi-select popover trigger) height fixed to match input-field heights at every size (`xs`…`xxl`), and no longer changes height (grows or shrinks) once a tag is selected — a `min-height` per size acts as a floor while still allowing the box to grow when tags wrap onto a second line.

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_REFERENCE.md

@@ -8,6 +8,8 @@
 
 **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"`.
@@ -15,11 +17,12 @@
 | Component / API                |  G  | Purpose                                                                                                                | Reference                                                              |
 | :----------------------------- | :-: | :--------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------- |
 | `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. `variant="stepper"` turns it into a numeric stepper (min/max/step, +/- buttons). | [.ai/ai_ref_AbInputField.md](./.ai/ai_ref_AbInputField.md)             |
-| `AbNumberField`                | ✅  | **Deprecated** — thin wrapper around `AbInputField variant="stepper"`, kept for backward compatibility. Use `AbInputField variant="stepper"` in new code. | [.ai/ai_ref_AbNumberField.md](./.ai/ai_ref_AbNumberField.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)     |
@@ -34,6 +37,8 @@
 | `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. 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). 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)                   |
@@ -41,7 +46,7 @@
 | `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)               |

package/CHANGELOG.md

@@ -2,8 +2,39 @@
 
 All notable changes to `@appsbd/vue3-appsbd-ui` are documented here. Format loosely follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [Unreleased]
+
+- **Added**: `AbInputField` `variant="outlined"` — a floating (Material-style) label. While the field is empty and unfocused the label looks like the placeholder; on focus or once it has a value it shrinks and sits on the top border with the border cut away behind it (the label has no background, so it works on any container color; RTL supported), and takes the focus (or error) color. A `placeholder`, if set, appears on focus. Scales with the existing `size` prop (`xs`–`xxl`); a left `#icon`/`prefix` gets a fixed width so the resting label clears it. The input is now wrapped in a `div.apbd-input-body` (`display: contents` for every other variant, so no layout change). No change when `variant` is unset. See `.ai/ai_ref_AbInputField.md`.
+- **Added**: `AbFileUploader` `variant="dropzone"` (`"default"` | `"dropzone"`, default `"default"`) — a larger upload card: an icon on top, a `title` and `description`, then an `AbButton` as the upload trigger (`buttonText` default `"Upload"`, `buttonColor` default `"primary"`, `buttonSize`). Clicking the card opens the file browser and a file can also be dropped onto it; the icon area has a fixed height (88px, `--afu-preview-height` to change) that the picked image fills (aspect ratio kept, never wider than the card), so the card has the same size with and without an image and a picked non-image file shows its icon, both with the usual hover-to-remove overlay. `isBorder` (`Boolean`, default `true`) picks a dashed border, or `false` for a borderless card with a box-shadow. `width`/`height` size the card. No change when `variant` is unset.
+- **Added**: `AbFileUploader` `icon` slot — replaces the empty-state icon (the top icon of the dropzone, or the image/file icon of the default design) — and `remove-icon` slot, which replaces the icon on the hover-to-remove overlay. The dropzone also gets `title`, `description` and `button` slots for its texts, and the `isCrop` dialog's texts can be replaced through `crop-title`, `crop-cancel` and `crop-apply` slots. Default icons are unchanged when the slots aren't used.
+- **Fixed**: `AbFileUploader` — clicking the hover-to-remove overlay threw a `ReferenceError` (`removeFile` reset an undefined `naturalImgSize`) before emitting `update:modelValue`/`onSelectFiles`, so a picked file could not be removed. The leftover lines are gone and removal works again.
+- **Added**: `AbInputField` `variant="inset"` — the label moves inside the bordered field, stacked above the value (small muted label, normal-weight value). The border, focus ring and validation styles are unchanged from the default field. Scales with the existing `size` prop (`xs`–`xxl`). A left `#icon`/`prefix` gets a fixed width so the label lines up with the value — use an icon there, not long text. No change when `variant` is unset. See `.ai/ai_ref_AbInputField.md`.
+- **Added**: `AbActionButton` `actions` prop (`Array`, default `[]`) — group mode. Renders a whole row of action buttons from one component instance instead of repeating `<AbActionButton action="..." />` per action (e.g. View + Edit + Delete on a table row). Each item is either a plain action-key `String` or an object `{ action, label?, icon?, color?, variant?, loading?, disabled?, confirm?, confirmOptions?, show? }`, resolved against the same built-in presets as single mode (item override > preset > built-in default); `show` (default `true`) conditionally excludes that button, and extra keys on an item forward through to that item's `AbButton`. The `action` event fires per-button with the same `(action, event)` signature as before. `action` is no longer a required prop — passing a non-empty `actions` array switches the component into group mode and `action`/`label`/`icon`/`color`/`variant`/`confirm`/`confirmOptions` are ignored in favor of per-item values. Existing single-`action` usage is unaffected. New scoped `#action` slot (`{ item, action }`) overrides a group button's label content. See `.ai/ai_ref_AbActionButton.md`.
+
+## [1.0.20] - 2026-09-22
+
+- **Added**: `AbFileUploader` `maxWidth`/`maxHeight` props (`String | Number`, both default `undefined`) — caps a picked image file's actual resolution rather than the preview box. If the image exceeds `maxWidth`/`maxHeight` (number = px), it's downscaled client-side (canvas, aspect ratio kept, never upscaled) before being previewed and emitted via `update:modelValue`/`onSelectFiles`, so what a consumer later uploads is already capped without them needing to know the source image's dimensions ahead of time. The preview container is unaffected — it always keeps its own `width`/`height` box (default `100px`/`73px`) and fits the (possibly downscaled) image inside it via the existing `object-fit: contain`, so it never overflows. No change when `maxWidth`/`maxHeight` are unset.
+- **Added**: `AbFileUploader` `isCrop` (`Boolean`, default `false`) and `cropAspectRatio` (`Number`, default `null` = free-form) props. `isCrop` (image mode only, ignored for `type="file"`) opens a crop dialog right after an image is picked — drag the box to move it, drag a corner to resize, then **Crop**; **Cancel** closes the dialog and selects nothing (a previously selected image stays). Built-in canvas cropper, no new dependency. jpeg/png/webp keep their format, anything else (e.g. gif) is exported as png. `update:modelValue` gets the cropped `File`; `onSelectFiles` receives `[file]`. No change when `isCrop` is off.
+- **Changed**: `AbColorPicker` — the outline ring on the selected swatch was always the theme color for every swatch. It now takes the selected swatch's own `color` (selecting red gives a red ring). Swatches whose `color` is a gradient or `url()` (not usable in a box-shadow) keep the theme-color ring. The gap between swatches also grew from `0 3px` to `10px` (both directions) so the selected ring, which extends 4px outward, no longer touches neighbouring swatches or wrapped rows.
+- **Fixed**: `AbButton` — while animating with the text hidden (`isHideTextOnAnimate`, or a rounded button), the loader icon still had the 5px left margin meant to separate it from the label, so it sat off-center. The margin is now removed when the text is hidden (new `.apbd-animated-text-hidden` class).
+- **Changed**: `AbButton` — a button that is both rounded and animated (`isRounded` + `isAnimated`) now always hides its text while animating: `isHideTextOnAnimate` is forced on in that case, even if explicitly passed as `false`. Passing `isHideTextOnAnimate` directly with `isAnimated` still works as before. Buttons that are only one of rounded/animated are unaffected.
+- **Added**: `AbButton` `variant="animated-round"` — a preset that acts as `isRounded` + text hidden while animating, so neither needs to be passed; the animation itself still follows `isAnimated` (e.g. bound to a loading ref). Combine with `isOutline` for an outline look. `variant` validator now accepts `"solid"` | `"outline"` | `"animated-round"`.
+- **Added**: `AbAccordion` `variant` (`"default"` | `"responsive"`, default `"default"`) and `breakpoint` (`"sm"` | `"md"` | `"lg"` | `"xl"` | `"xxl"`, default `"lg"`) props. `variant="responsive"` renders every `AbAccordionItem` always expanded, with no toggle icon and a non-clickable heading, at viewport widths >= `breakpoint`; below it, it behaves as a normal accordion, collapsed by default. No change for the default variant. Also the library's new convention: different designs of a component are added as variations of the existing component, not new components.
+- **Fixed**: Playground's `DocsToc` (the "On this page" sidebar) — clicking a section link animated *every* jump with `scrollTo({ behavior: "smooth" })` regardless of distance. A native smooth scroll is cancelled outright by a single wheel/trackpad nudge, and its duration grows with distance (measured at ~1.7s to cross the 17,000px Usage Guide page), so a jump to a far section was routinely interrupted partway and left stranded thousands of pixels short — while the TOC still highlighted the clicked item, making it look like the link simply did nothing. Jumps farther than 3 viewport heights now scroll instantly (`behavior: "auto"`), leaving no animation to interrupt; short hops still animate, where the motion helps orientation. Same rule applied to the "Back to top" button. Separately, the scroll-spy observer was un-muted by a fixed 600ms timer that expired mid-animation on long pages, letting the scroll handler overwrite the active highlight with whatever section was passing by — it now watches `scrollTop` and un-mutes once the scroll has actually stopped, with a 4s hard cap so a backgrounded tab (where `requestAnimationFrame` is paused) can't leave it stuck. Only ever visible on pages long enough for the animation to outlast a user's next trackpad touch, which is why the much longer Usage Guide page surfaced it.
+- **Added**: `AbAccordion` + `AbAccordionItem` — a new shadcn-style collapsible accordion component. `AbAccordion` is the group container (`multiple` for allowing more than one open item at once, default `false`; `iconPosition` — `"left"`/`"right"`, default `"right"`; `titleBgColor`/`bodyBgColor`, both default `"#fff"`); `AbAccordionItem` is a single row (`title`, `disabled`, `defaultOpen` props) with a `default` body slot that accepts any content (text, `AbCard`, or any other component), a `title` slot, and an `icon` slot (scoped with `{ isOpen }`) to override the default rotating chevron. Panels animate open/closed with a smooth JS-measured height transition rather than an abrupt toggle. See `.ai/ai_ref_AbAccordion.md` and `.ai/ai_ref_AbAccordionItem.md`.
+- **Fixed**: `width`/`minWidth`/`maxWidth` (`AbInputField`, `AbMultiSelect`, `AbDateTimePicker`, and `AbFilterPanel`'s own per-field flex-item sizing plus its `propertySelectWidth`/`propertySelectMinWidth`/`propertySelectMaxWidth` props) applied a fixed CSS length straight through with no cap relative to the parent's actual space — a field given e.g. `width: 300` stayed exactly `300px` wide even inside a narrower container, most noticeable in `AbFilterPanel`'s flex-wrap rows on small screens, where a fixed-width field would overflow its row instead of shrinking to fit. All four now apply every one of these values as `min(<value>, 100%)`, so a fixed size still renders at its intended width when there's room but shrinks to fit a narrower parent instead of overflowing it. No prop signature change — same `String | Number` types/defaults.
+- **Added**: `AbInputField` read-only mode — the native `readonly` attribute already fell through to the input via `$attrs` for plain text/password fields, but `variant="stepper"`'s +/- buttons are separate elements unaffected by it, so a "read-only" stepper could still have its value changed by clicking them. `readonly` (and `disabled`) now also disable both buttons, giving the stepper a true read-only/disabled mode. No change for non-stepper fields, which already worked this way. Documented as a first-class "Read-only State" in `.ai/ai_ref_AbInputField.md` and the playground, replacing the old "there is no built-in read-only mode" caveat. `AbNumberField` gets the same fix through a new, explicit `readonly` prop (`Boolean`, default `false`), matching its existing explicit `disabled` prop.
+- **Fixed**: `AbInputField`'s `variant="stepper"` +/- buttons ignored `disabled`/`readonly` when passed as a bare attribute (e.g. `<AbInputField variant="stepper" disabled />`, the common way to write it). A bare attribute on a prop not declared by the component compiles to `$attrs.disabled = ""` (empty string) — correct per HTML boolean-attribute semantics, and handled correctly by the native `<input>` itself, but the buttons' own `isDecrementDisabled`/`isIncrementDisabled` checks used plain JS truthiness (`if (this.$attrs?.disabled)`), and `""` is falsy in JS, so the check silently passed and the buttons stayed clickable. Both checks now also treat `""` as true, matching how the browser already treats the native input.
+- **Changed** (breaking): `AbNumberField` is no longer deprecated and no longer always renders as a stepper. It's still a thin wrapper around `AbInputField`, but now exposes the same `variant` prop: left unset (the new default), it renders a plain native `type="number"` input with no buttons; pass `variant="stepper"` to get the previous minus/plus-buttons/min-max-clamping behavior, unchanged. **Breaking**: a consumer using the no-props default (relying on the old implicit always-stepper look) now gets a plain number input instead — pass `variant="stepper"` to keep the previous appearance.
+- **Fixed**: `AbFormCheck`'s `icon-card` variant (and `image-radio` in its default, non-`isInline` tile view) — the `middle-top` layout is supposed to center the icon above the title/description (as `.ai/ai_ref_AbFormCheck.md` and the playground's own "Icon Card Variant" example already claimed), but a leftover `flex-direction: row-reverse; align-items: start;` override inside `.middle-top:has(.input-img) .form-check` (`src/styles/components/_checkbox.scss`) undid the centering, pinning the icon+label block to one corner of the card instead. Removed the override; the icon now renders centered on top as documented, matching the already-correct `card`/`card-flat-check` variants.
+- **Added**: `AbActionButton` — a new `AbButton` wrapper for CRUD-style actions (`add`/`edit`/`save`/`delete`/`cancel`/`view`/`close`/`submit`, plus any custom action string). Each action resolves to a default label/icon/color preset (overridable via `label`/`icon`/`color`/`variant` props); the component emits a single `action` event on click and performs no business logic itself — the parent owns the workflow and typically changes the `action` prop in response (e.g. `edit` → `save` → `add`). `delete` (and any action with `confirm` set) asks for confirmation via the existing `useAlert()` dialog before emitting, configurable through `confirmOptions`. `loading`/`disabled` map to `AbButton`'s `is-animated`/native `disabled`; any other `AbButton` prop (`size`, `mode`, `isRounded`, …) passes straight through. See `.ai/ai_ref_AbActionButton.md`.
+- **Docs**: Added `.ai/ai_ref_usage_guide.md`, linked from `AI_REFERENCE.md` — a full decision map for generating UI with this library, separate from the per-component prop/event/slot reference. It answers two questions in table form: **"which component does this job?"** (nine "Pick by Task" tables — text & value input, choice & selection, date/file/media, form assembly & validation, actions & dialogs, navigation & page structure, data display, feedback & loading, chat & voice — mapping a plain-language need like "take a password" or "enable/disable something" to the exact component and prop, e.g. `AbInputField type="password"`, `AbToggle`), and **"which variant/mode of it fits?"** (per-component Variant Reference tables for `AbFormCheck`, `AbCard`, `AbButton`, `AbBadge`, `AbToggle`, the input/number fields, `AbMultiSelect`, `AbDateTimePicker`, `AbFilterPanel`, `AbTabs`, `AbAccordion`, `AbWizard`, `AbPricingCard`, `AbAvatar`, `AbFileUploader`, `useAlert`). Adds a "Commonly Confused Pairs" tie-breaker table for cases where two components legitimately overlap (`AbInputField type="number"` vs `AbNumberField`, `AbToggle` vs `AbFormCheck variant="card"`, `AbInputTag` vs `AbMultiSelect mode="tags"`, `AbTable` vs `EliteGrid`, `useToast` vs `useAlert`, …) and a composables/utilities table. Also added a matching playground page (`playground/components/UsageGuideTest.vue`, under Sidebar → AI Integration → "Usage Guide") — tables only, no live examples, since the per-component pages already demo every variant.
+
 ## [1.0.19] - 2026-09-14
 
+- **Added**: `AbFilterPanel` `#builderTitle` slot (`isBuilderFilter` mode, not scoped) — a title rendered at the far left of the row, in the same box style as the applied chips. Default content is `Filter Title`. Like the Search/Reset buttons, it's hidden until a chip is applied and vanishes again on Reset or when the last chip is removed.
+- **Changed**: `AbFilterPanel` `isBuilderFilter` mode — the Search/Reset buttons were always visible (pushed to the far right of the row, Search just disabled with no chips). They're now hidden entirely while no chip is applied, render right after the `+` button once a chip is applied, and vanish again when Reset is clicked or the last chip is removed individually. Same for `isBuilderAutoSearch` (Reset only).
+- **Fixed**: `AbFilterPanel` `isBuilderFilter` mode — the popup editor (`.apbd-builder-editor`) had one fixed width (400px) for every `size`, so a `"dr"` (date range) value with full month names (e.g. `"সেপ্টেম্বর ২৮, ২০২৬  ↔  ফেব্রুয়ারি ২৮, ২০২৬"`) overflowed the input at every size except `xs`. The editor now gets a size class (`.apbd-builder-editor-{size}`) with a width per size, measured against that longest value plus the prefix label (460px at `xs` → 660px at `xxl`, capped at `100vw - 2rem`), and the `.apbd-builder-popover` cap was raised to 700px to fit. The date range picker inside the editor also puts an extra space on each side of the `↔` separator (`"  ↔  "`) — a global `rangeSeparator` config still takes precedence.
 - **Fixed**: `AbWizard`'s built-in Previous/Next/Finish navigation buttons (both the inline and modal footers) passed a Bootstrap-style single-token string (`variant="outline-secondary"`, `variant="primary"`, `variant="success"`) to `AbButton`, but `AbButton` has always split color and style into two separate props (`color` + `isOutline`/now `variant`) — `variant` wasn't even a real `AbButton` prop until this release, so these values were silently swallowed with zero visual effect and every nav button rendered as the plain default primary color regardless of intent (Previous never showed as outlined/secondary, Finish never showed as success-colored). Adding `AbButton`'s own `variant` prop (see below) would otherwise have turned this into a dev-console prop-validation warning instead of a silent no-op, so it's fixed now: these buttons pass `color`/`variant` correctly and finally render as originally intended (Previous: secondary outline; Next: primary; Finish: success). Same latent mismatch fixed in several playground docs examples (`CardTest.vue`, `CheckboxTest.vue`, `WizardTest.vue`, `TooltipPopoverTest.vue`, `App.vue`, `.ai/ai_ref_AbFormCheck.md`) that had the same `variant="success"`/`variant="danger"`/`variant="soft"` typo on `AbBadge`/`AbButton` usages.
 - **Added**: `AbCard` `variant` prop (`String`, default `"default"`) — the card's alternate layouts (`tile-card`/`item-card`/`insight-card`) were previously reachable through three different half-mechanisms at once (the `isTileCard` boolean for tile, and the generic `containerClass`/`variation` string props for item/insight, which a consumer had to already know the literal class names for). `variant` (`"default"` | `"tile"` | `"item"` | `"insight"`) is now the single, consistent, documented way to pick one, generating the matching class automatically. `isTileCard`, `containerClass`, and `variation` all still work unchanged — no behavior change, and the default (`variant="default"`, i.e. a plain card) matches the existing default look exactly. This is also now the library's documented default: generate `AbCard` with its default (plain) variant unless a different one is requested.
 - **Added**: `AbBadge` `variant` prop (`String`, default `"solid"`) — same generalization as `AbButton`'s new `variant` prop: the badge design was previously picked entirely through the `isOutline` boolean; `variant` (`"solid"` | `"outline"`) is now the consistent, documented way to switch it. `isOutline` still works unchanged (now a deprecated alias for `variant="outline"`) — no behavior change, and the default (`variant="solid"`, i.e. a plain filled badge) matches the existing default look exactly. This is also now the library's documented default: generate `AbBadge` with its solid variant unless a different one is requested.