@appsbd/vue3-appsbd-ui 1.0.18 → 1.0.20

package/CHANGELOG.md

@@ -2,13 +2,65 @@
 
 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.
+- **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]