@appsbd/vue3-appsbd-ui 1.0.18 → 1.0.19

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

@@ -14,13 +14,13 @@
 
 | 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)                     |
+| `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). | [.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)           |
+| `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,10 +32,10 @@
 | `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)                           |
 | `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)             |
@@ -63,6 +63,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)                     |

package/CHANGELOG.md

@@ -2,13 +2,34 @@
 
 All notable changes to `@appsbd/vue3-appsbd-ui` are documented here. Format loosely follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [1.0.19] - 2026-09-14
+
+- **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.
+- **Added**: `AbButton` `variant` prop (`String`, default `"solid"`) — the button design was previously picked entirely through the `isOutline` boolean; `variant` generalizes that into a design-variant switch (`"solid"` | `"outline"`) in the same style as `AbTabs`' new `variation` prop, so a consumer (or an AI assistant) reaches for one consistent prop name across components instead of a one-off boolean per component. `isOutline` still works unchanged (now a deprecated alias for `variant="outline"`) — no behavior change, and the default (`variant="solid"`, i.e. a plain filled button) matches the existing default look exactly. This is also now the library's documented default: generate `AbButton` with its solid variant unless a different one is requested.
+- **Added** (breaking): `AbTabs` `variation` prop (`String`, default `"outline"`) — the nav design was previously picked entirely through raw `navClass` strings (`nav-pills`, `nav-underline`, `nav-bg-secondary`, `nav-outline`), which required a consumer (or an AI assistant) to already know those class names existed. `variation` now generates the base class automatically (e.g. `variation="pills"` → `nav-pills`), merged with anything still passed via `navClass` for modifiers (`nav-xs`/`nav-fill`/`nav-secondary`/`nav-vertical`, etc.); pass `variation=""` to opt out and drive `navClass` manually as before. **Breaking**: `navClass`'s own default changed from `"nav-pills"` to `""`, and the effective default nav design changed from pills to **outline** — a consumer relying on the old implicit `nav-pills` default with no explicit `navClass` now gets the outline look instead; pass `variation="pills"` to keep the old appearance. This is also now the library's documented default: generate `AbTabs` with its outline variation unless a different one is requested.
+- **Added**: `AbInputField` `copyable` prop — renders a plain, borderless postfix button that copies the field's current value to the clipboard via the Clipboard API. The library previously had no copy-to-clipboard affordance anywhere — consumers needing "show a read-only value with a copy button" (e.g. a one-time download token, a permanent download URL) had to hand-roll it by composing `AbInputField` + `AbButton` + the raw Clipboard API themselves. There is no built-in confirmation UI: success/failure emits `copy-success`/`copy-error` with an already-translated message (`copySuccessMsg`/`copyErrorMsg` props), so a consumer wires up its own feedback (e.g. `useToast()`, shown in the playground's "Copyable" example) rather than the component forcing a toast dependency on everyone. Pair with a native `readonly` attribute (falls through via `$attrs`, no dedicated prop needed) for a display-only copyable field.
+- **Docs**: Added `.ai/ai_ref_EliteGrid.md` — an AI reference for `EliteGrid` (from the external `@appsbd/vue3-elite-grid` peer dependency, only imported/demonstrated in `playground/components/EliteGridTest.vue`, not developed in this library), previously undocumented outside that playground example itself. Covers props, events, slots, the `EliteColumnModel.getColumn()` column config shape, exposed methods, and its `--eg-*` CSS variable theming API, sourced from the package's own docs site.
+- **Docs**: `AbBaseAlert` and `AbToast` are internal mount-only roots (mounted into `document.body` by `install()`, reached only via `useAlert()`/`useToast()`) — neither was ever a named export, but both compile straight into the built bundle (pulled in by the plugins) and are easy to find by grepping the bundle or the source tree, with nothing warning that `import { AbToast } from "vue3-appsbd-ui"` silently resolves to `undefined`. `.ai/ai_ref_useAlert.md` and `.ai/ai_ref_useToast.md` now say so explicitly.
+- **Docs**: `AbModal`'s `showMsgOnly(msg, isHideFooter?)` exposed method was documented as just "Switch to message-only mode", with no explanation of what `isHideFooter` does — easy to misread the boolean as an auto-close/auto-dismiss flag given the method name. Clarified in `.ai/ai_ref_AbModal.md`: it swaps the footer for a static "Close" button instead of the default/slotted one; there is no auto-dismiss, the modal stays open until the user clicks it (or the parent unmounts the modal). No behavior change.
+- **Docs**: `AbInputField`'s `isCodeInput` prop was documented as "monospace / code-input styling" — it actually renders `.mega-input-field`, a small fixed-size (e.g. 64px at `md`) single-character box with huge bold centered text, the exact per-digit style `AbPinInput` uses for OTP/PIN boxes. Anyone reaching for it to display a token, API key, or URL got a box too narrow to show more than its first few characters, with the rest scrolled out of view. `.ai/ai_ref_AbInputField.md` and the playground's Props table now describe it accurately — it's a single-digit PIN box, not a monospace/code-display style, and `maxlength="1"` is not set automatically. No behavior change.
+- **Fixed**: `AbConfirmPopover`'s `onConfirm` prop — an async handler that resolved to nothing (the natural `async (itemData) => { await doWork(); }` shape, with no explicit return) fell through to the terminal "Completed successfully" alert panel instead of just closing, forcing an extra unwanted OK click even though the work had already finished; only an explicit `{ next: 'close' }` return closed it, and that contract was undocumented. Resolving to nothing (or `null`) now closes the popover directly, same as `{ next: 'close' }`. Returning `{ next: 'confirm' | 'confirm-ajax', ... }` (chain a second step) or any other truthy object like `{ status, message }` (show the success/error alert panel deliberately) behave exactly as before — see `.ai/ai_ref_AbConfirmPopover.md`'s new "onConfirm return contract" table.
+- **Removed** (breaking): `AbModal`'s `isModalVisible` prop — it was never wired to anything in the component (no `v-if`/`v-show`/class toggle), so passing it had zero effect; the `.ai/ai_ref_AbModal.md` doc incorrectly documented it as `v-model:is-modal-visible`-capable. Visibility has always actually worked by mounting/unmounting `<AbModal>` itself with `v-if` in the parent (the pattern every existing usage in this library already uses) — that's unchanged.
+
 ## [1.0.18]
 
+- **Fixed**: `AbColorPicker` rendered an empty box with no feedback when used with default props — `colors` defaults to `[]` and the component has no built-in palette (by design, same as `AbMultiSelect`'s `options`), so a first-time use without passing `colors` looked broken. Now warns in dev (`import.meta.env.DEV`, stripped from production builds) when `colors` is empty, pointing at the expected `{ name, color, title? }` shape.
+- **Fixed**: Playground's `DocsToc` (the "On this page" sidebar) — clicking a section link called the target heading's native `scrollIntoView({ block: "start" })`, which walks up *every* scrollable ancestor, including `.apbd-container`/`.apbd-main-content` (`overflow: hidden` — still a valid scroll container by spec even with no visible scrollbar). That silently scrolled those too, shifting the whole app shell (page header, left sidebar) up and clipping it out of view behind their own `overflow: hidden`, while the doc content itself scrolled correctly — most noticeable on longer pages like Color Picker's "Sizes" section. Now scrolls only the actual doc scroll container (`.apbd-app-body`) directly via `scrollTo()`, matching the pattern already used by the TOC's own "Back to top" button.
+- **Fixed**: `AbColorPicker`'s selected-state check mark was hard-coded to `rgba(255, 255, 255, 0.65)`, invisible against a white or light-grey swatch — a text-color palette almost always has one, so selecting it gave no visual feedback at all. The checked swatch now also gets a two-tone outline ring (`box-shadow`, themeable via `--#{$prefix}apbd-cp-checked-color`, falling back to `--bs-primary`) independent of swatch color, and the check mark itself uses `mix-blend-mode: difference` so it inverts against whatever color sits behind it — visible on both light and dark swatches.
 - **Fixed**: `AbMainLayout`'s `.apbd-right-sidebar` had no responsive handling at all — unlike `.apbd-left-sidebar` (which becomes an absolute overlay drawer under `575.98px`), the right sidebar just stayed in the flex row at any viewport width, squeezing `.apbd-main-content` on tablet-size screens with no mobile/overlay treatment built for it. Now hidden entirely below `1199.98px` (Bootstrap's `xl` breakpoint).
 - **Added**: `AbFilterPanel` `#builderChipSeparator` slot (`isBuilderFilter` mode, scoped: `{ field }`) — overrides the connector rendered between an applied chip's field name and its value, for every field type. Previously this text auto-generated from the field's `operators` for most types (`"is"`, `"is not"`, `"contains"`, etc., via a hardcoded `BUILDER_OPERATOR_LABELS` map) while range (`tr`/`dr`) chips separately hardcoded "is between X and Y" — both are gone now. Chips default to a plain `:` connector, customizable per-field through this slot; range chips render their value as `start - end` (e.g. "Revenue : 12 - 23").
 - **Added**: `AbFilterPanel` `#builderAddLabel` slot (`isBuilderFilter` mode, not scoped) — renders before the static `+` icon inside the "Add filter" button, letting a consumer add a text label next to it. Empty by default (icon-only, unchanged from before).
 - **Added**: `AbFilterPanel` `isBuilderFilter` mode — a `"t"` (plain text/number) field's popup editor now also applies on `Enter`, not just by clicking Apply Filter. Same guard as the button (a no-op on an empty value); `"tr"`/`"dd"`/`"d"`/`"dr"` fields are unaffected.
 - **Fixed**: `AbFilterPanel`'s `.apbd-filter-tag-remove` (the `×` icon that removes a chip — used by both the quick-advance tag chips and `isBuilderFilter` chips) had no hover feedback at all, `color: inherit` on every state. Now transitions to the theme's danger red (`--#{$prefix}apbd-danger-color`) on hover/focus, signaling the removal action.
+- **Added**: `AbInputField` `variant="stepper"` prop — turns the field into a numeric stepper: forces `type="number"`, renders minus/plus buttons, and adds `min`/`max`/`step`/`showButtons`/`isBorder` props for range clamping and layout, matching what `AbNumberField` did on its own. Lets the numeric-stepper look/behavior live on the same component as every other input variant (password, icon, prefix/postfix) instead of a separate SFC.
+- **Changed**: `AbNumberField` is now a thin deprecated wrapper around `AbInputField` with `variant="stepper"` — its own props/events/slots and rendered output are unchanged, so existing usage keeps working with no code changes needed. Prefer `<AbInputField variant="stepper" />` directly in new code.
+- **Added**: `AbField` `variant`, `min`, `step`, `showButtons`, and `isBorder` props (`type="number"` only) — forwarded straight through to `AbInputField`, so `<AbField type="number" variant="stepper" />` now gets the same numeric-stepper behavior (min/max/step clamping, +/- buttons) as using `AbInputField` directly. `type="number"` without `variant` still renders a plain native number input, unchanged. `AbField`'s existing `max` prop (selection limit for multiselect/tag/checkbox, `-1` = unlimited) is reused as the stepper's numeric ceiling for `type="number"` too — `-1`/unset is treated as "no ceiling" there as well, so no default-value change for existing usage.
 
 ## [1.0.17]