@appsbd/vue3-appsbd-ui 1.0.18 → 1.0.20

package/.ai/ai_ref_AbAccordion.md

@@ -0,0 +1,69 @@
+# AbAccordion — AI Reference
+
+Group container for a vertically stacked set of collapsible sections (shadcn-style accordion). Controls open/close behavior (single vs. multiple open) and the shared icon position / title / body background colors for every child. Wrap `AbAccordionItem` children inside it. Use it instead of `AbTabs` when content should stack vertically and reveal on demand, rather than switching between panels.
+
+## Installation
+
+Globally registered by the plugin — use `<ab-accordion>` directly, or `import { AbAccordion } from "vue3-appsbd-ui"`. No extra peer dependency required; the default trigger icon uses Bootstrap Icons (`bi bi-chevron-down`), already a peer dependency of this library.
+
+## Usage
+
+```vue
+<template>
+  <ab-accordion>
+    <ab-accordion-item title="Is it accessible?" default-open>
+      <p>Yes. It follows the WAI-ARIA design pattern.</p>
+    </ab-accordion-item>
+    <ab-accordion-item title="Is it styled?">
+      <p>Yes. It ships with modern default styles.</p>
+    </ab-accordion-item>
+  </ab-accordion>
+</template>
+```
+
+Multiple items open at once, icon on the left, custom colors:
+
+```vue
+<ab-accordion multiple icon-position="left" title-bg-color="#f8f5ff" body-bg-color="#fdfcff">
+  <ab-accordion-item title="First">...</ab-accordion-item>
+  <ab-accordion-item title="Second">...</ab-accordion-item>
+</ab-accordion>
+```
+
+Responsive: expanded, non-collapsible sections on large screens, accordion on small screens:
+
+```vue
+<ab-accordion variant="responsive" breakpoint="md">
+  <ab-accordion-item title="Overview">...</ab-accordion-item>
+  <ab-accordion-item title="Details">...</ab-accordion-item>
+</ab-accordion>
+```
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `multiple` | `Boolean` | `false` | When `true`, more than one item can be open at once. When `false` (default), opening an item closes any other open item in the group. |
+| `variant` | `String` | `"default"` | `"default"` (always an accordion) or `"responsive"`. With `"responsive"`, at viewport widths >= `breakpoint` every item is always expanded and shows no toggle icon/button (static sections, not clickable); below it, it behaves as a normal accordion, collapsed by default (unless an item has `defaultOpen`). |
+| `breakpoint` | `String` | `"lg"` | Only used by `variant="responsive"`. Bootstrap breakpoint at/above which items become static: `"sm"` (576px), `"md"` (768px), `"lg"` (992px), `"xl"` (1200px), `"xxl"` (1400px). |
+| `iconPosition` | `String` | `"right"` | Where the expand/collapse icon renders on every child item's trigger: `"left"` or `"right"`. Applies to the whole group, not set per item. |
+| `titleBgColor` | `String` | `"#fff"` | Background color applied to every child item's title/trigger row. Accepts a hex or `rgb()`/`rgba()` string; the trigger's text color is automatically switched to a light or dark shade based on this background's luminance, so it stays readable regardless of the surrounding app theme (light or dark mode). |
+| `bodyBgColor` | `String` | `"#fff"` | Background color applied to every child item's expanded body panel. Same automatic text-contrast behavior as `titleBgColor`. |
+
+## Events
+
+None — open/close state is managed internally via `provide`/`inject` with child `AbAccordionItem`s.
+
+## Slots
+
+| Name | Description |
+| --- | --- |
+| `default` | Accepts `AbAccordionItem` children. |
+
+## v-model
+
+No — open/close state is internal per item (see [`AbAccordionItem`](./ai_ref_AbAccordionItem.md)'s `defaultOpen`), not bound on `AbAccordion`.
+
+## Provides
+
+Provides an `apbdAccordion` context (`iconPosition`, `titleBgColor`, `bodyBgColor`, internal `isStatic`/`toggleItem`/`isItemOpen`) consumed by every descendant `AbAccordionItem`. An `AbAccordionItem` rendered outside an `AbAccordion` has nothing to inject and will not work.

package/.ai/ai_ref_AbAccordionItem.md

@@ -0,0 +1,48 @@
+# AbAccordionItem — AI Reference
+
+Single collapsible row inside an [`AbAccordion`](./ai_ref_AbAccordion.md) group. Must be used inside an `AbAccordion` parent — it injects shared context (icon position, colors, open/close control) from there. The body slot accepts any content: plain text, an `AbCard`, or any other component.
+
+## Usage
+
+```vue
+<ab-accordion>
+  <ab-accordion-item title="Is it accessible?" default-open>
+    <p>Yes. It follows the WAI-ARIA design pattern.</p>
+  </ab-accordion-item>
+</ab-accordion>
+```
+
+Custom icon (scoped slot receives `{ isOpen }`):
+
+```vue
+<ab-accordion-item title="Custom icon">
+  <template #icon="{ isOpen }">
+    <i :class="isOpen ? 'bi bi-dash-lg' : 'bi bi-plus-lg'"></i>
+  </template>
+  <p>Body content...</p>
+</ab-accordion-item>
+```
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` | `String` | `""` | Label shown in the trigger row. Ignored if the `title` slot is provided. |
+| `disabled` | `Boolean` | `false` | Prevents the item from being toggled (trigger renders as a disabled `<button>`). |
+| `defaultOpen` | `Boolean` | `false` | Opens the item on mount. |
+
+## Slots
+
+| Name | Description |
+| --- | --- |
+| `default` | The expandable body content. Accepts any markup or component. Animates open/closed with a smooth height transition (not an abrupt toggle). |
+| `title` | Overrides the trigger label instead of using the `title` prop. |
+| `icon` | Overrides the default chevron icon. Receives `{ isOpen: Boolean }` so a custom icon can reflect the item's expanded state. |
+
+## v-model
+
+No — open/close state is internal, driven by `defaultOpen` on mount and toggled by clicking the trigger (or via the parent `AbAccordion`'s `multiple`/single-open rule).
+
+## Injects
+
+Injects the `apbdAccordion` context provided by the parent `AbAccordion` (`iconPosition`, `titleBgColor`, `bodyBgColor`, `toggleItem`, `isItemOpen`).

package/.ai/ai_ref_AbActionButton.md

@@ -0,0 +1,151 @@
+# AbActionButton — AI Reference
+
+Thin wrapper around `AbButton` for CRUD-style actions (add, edit, save, delete, cancel, and more). Each action resolves to a default label/icon/color preset; the component emits a single `action` event on click (after an optional confirmation step for actions like `delete`) and never performs the underlying business logic itself — the parent owns the workflow. Two modes, mutually exclusive:
+
+- **Single** (`action` prop, a string) — renders one button. Typically used for a state-changing button where the parent changes `action` in response (e.g. `edit` → `save` → `add`).
+- **Group** (`actions` prop, an array) — renders a whole row of action buttons from **one** component instance instead of repeating `<AbActionButton action="..." />` per action. Use this whenever a row/card needs several fixed actions at once (e.g. View + Edit + Delete on a table row).
+
+When `actions` is a non-empty array it takes over rendering and `action`/`label`/`icon`/`color`/`variant`/`confirm`/`confirmOptions` (the single-mode props) are ignored — set those per-item inside the array instead.
+
+Prefer this over a raw `AbButton` whenever a button's meaning is one of the CRUD-style actions, whether alone or as part of a fixed group.
+
+## Installation
+
+Not globally registered — import explicitly. Icons are rendered via `@lucide/vue` (already a peer dependency).
+
+```js
+import { AbActionButton } from "vue3-appsbd-ui";
+```
+
+## Usage
+
+Single action:
+
+```vue
+<template>
+  <ab-action-button action="edit" @action="handleAction" />
+</template>
+
+<script setup>
+function handleAction(action) {
+  console.log(action); // "edit"
+}
+</script>
+```
+
+Group of actions — one component renders the whole row:
+
+```vue
+<template>
+  <ab-action-button :actions="['view', 'edit', 'delete']" @action="handleRowAction" />
+</template>
+
+<script setup>
+function handleRowAction(action) {
+  // "view" | "edit" | "delete"
+}
+</script>
+```
+
+Per-item overrides (array items can be plain strings or objects — mix freely):
+
+```vue
+<template>
+  <ab-action-button
+    :actions="[
+      'view',
+      { action: 'edit', disabled: !canEdit },
+      { action: 'delete', confirmOptions: { message: 'This user will be permanently removed.' } },
+      { action: 'approve', label: 'Approve', icon: CircleCheckBig, color: 'success', show: isPending },
+    ]"
+    @action="handleRowAction"
+  />
+</template>
+
+<script setup>
+import { CircleCheckBig } from '@lucide/vue';
+</script>
+```
+
+State-change workflow (single mode, parent decides what the button becomes next):
+
+```vue
+<template>
+  <ab-action-button :action="rowAction" :loading="isSaving" @action="handleRowAction" />
+</template>
+
+<script setup>
+import { ref } from 'vue';
+
+const rowAction = ref('edit');
+const isSaving = ref(false);
+
+function handleRowAction(action) {
+  if (action === 'edit') {
+    rowAction.value = 'save';
+  } else if (action === 'save') {
+    isSaving.value = true;
+    saveToServer().then(() => {
+      isSaving.value = false;
+      rowAction.value = 'add';
+    });
+  }
+}
+</script>
+```
+
+Delete with a custom confirmation message (built-in confirm uses `useAlert`):
+
+```vue
+<ab-action-button
+  action="delete"
+  :confirm-options="{ message: 'This user will be permanently removed.' }"
+  @action="handleDelete"
+/>
+```
+
+Custom action (not in the predefined set):
+
+```vue
+<script setup>
+import { CircleCheckBig } from '@lucide/vue';
+</script>
+
+<template>
+  <ab-action-button action="approve" label="Approve" :icon="CircleCheckBig" color="success" @action="handleApprove" />
+</template>
+```
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `action` | `String` | `null` | Single-mode action key. Presets: `add`, `edit`, `save`, `delete`, `cancel`, `view`, `close`, `submit`. Any other string is accepted as a custom action. Ignored when `actions` is a non-empty array. |
+| `actions` | `Array` | `[]` | Group mode. Each item is either a plain action-key `String`, or an `Object`: `{ action, label?, icon?, color?, variant?, loading?, disabled?, confirm?, confirmOptions?, show?, ...otherAbButtonProps }`. `action` is required per item; every other key falls back the same way the single-mode props do (item override → preset → built-in default). `show` (`Boolean`, default `true`) conditionally excludes that button from the row. Unrecognized keys on an item (e.g. `size`, `isRounded`) are forwarded straight through to that item's `AbButton`, same as extra attrs in single mode. |
+| `label` | `String` | `null` | Single mode only. Overrides the preset label. Falls back to the preset's label, then to the raw `action` string. |
+| `icon` | `Component` \| `Boolean` | `null` | Single mode only. Overrides the preset icon (a `@lucide/vue` icon component). Pass `false` to force no icon. |
+| `color` | `String` | `null` | Single mode only. Overrides the preset `AbButton` `color`. Falls back to the preset's color, then `"primary"`. |
+| `variant` | `String` | `null` | Single mode only. Overrides the preset `AbButton` `variant` (`solid`, `outline`, `animated-round`). Falls back to the preset's variant, then `"solid"`. |
+| `loading` | `Boolean` | `false` | Single mode only. Maps to `AbButton`'s `is-animated`. Also disables the button while `true`. In group mode, set `loading` per item instead. |
+| `disabled` | `Boolean` | `false` | Single mode only. Disables the button (combined with `loading`). In group mode, set `disabled` per item instead. |
+| `confirm` | `Boolean` | `null` | Single mode only. Whether to show a confirmation dialog before emitting the action. Falls back to the preset's default (`true` only for `delete`), then `false`. |
+| `confirmOptions` | `Object` | `{}` | Single mode only. Shallow-merged into the confirmation dialog's options (`title`, `message`, `icon`, `confirmText`, `cancelText`, …) — same shape `useAlert`'s `alert()` accepts. |
+
+Any other prop supported by `AbButton` (`size`, `mode`, `isRounded`, `isIconBtn`, `iconPosition`, `showIconDivider`, …) can be passed directly on `<AbActionButton>` and is forwarded through unchanged (standard Vue attrs fallthrough) — applied to the single button in single mode, or to **every** button in group mode (overridable per item, since an item's own matching key wins).
+
+## Events
+
+| Event | Payload | Description |
+| --- | --- | --- |
+| `action` | `(action: String, event: MouseEvent)` | Fired once an action is approved — immediately, or after the user confirms (for actions with `confirm` truthy). In group mode, fired per-button with that button's own action key. The component performs no business logic itself. |
+
+## Slots
+
+| Name | Description |
+| --- | --- |
+| `default` | Single mode only. Overrides the button's label content (defaults to the resolved label). |
+| `action` | Group mode only. Overrides each button's label content. Scoped: `{ item, action }` — `item` is the fully resolved `{ action, label, icon, color, variant, loading, disabled, confirm, confirmOptions, show }` object for that button, `action` is its key. Defaults to `item.label`. |
+
+## v-model
+
+None.

package/.ai/ai_ref_AbBadge.md

@@ -2,13 +2,18 @@
 
 Bootstrap badge wrapper for statuses or counts with size, variant, shape, and icon variations.
 
+**Default variant is `solid`** — when asked to generate `AbBadge` with no specific style requested, generate it as-is (don't pass `variant` at all) and it renders as a plain filled badge, the way it's used everywhere in this library.
+
 ## Usage
 
 ```vue
 <template>
+  <!-- Default: solid variant (no variant prop needed) -->
   <ab-badge color="primary">New</ab-badge>
   <ab-badge color="success" is-rounded-pill>12</ab-badge>
-  <ab-badge color="warning" is-outline>Pending</ab-badge>
+
+  <!-- Outline variant -->
+  <ab-badge color="warning" variant="outline">Pending</ab-badge>
 </template>
 ```
 
@@ -18,7 +23,8 @@ Bootstrap badge wrapper for statuses or counts with size, variant, shape, and ic
 | --- | --- | --- | --- |
 | `size` | `String` | `"md"` | Size of the badge (`sm`, `md`, `lg`). |
 | `color` | `String` | `"primary"` | Color theme (`primary`, `secondary`, `danger`, `warning`, `success`, `info`). |
-| `isOutline` | `Boolean` | `false` | Outlined style with transparent background. |
+| `variant` | `String` | `"solid"` | Design variant — `"solid"` (plain filled badge) or `"outline"` (bordered, transparent background; matches `isOutline`). |
+| `isOutline` | `Boolean` | `false` | Deprecated — equivalent to `variant="outline"`, kept for backward compatibility. Prefer `variant="outline"` in new code. |
 | `isRoundedPill` | `Boolean` | `false` | Transforms badge to a fully rounded pill shape. |
 | `isDot` | `Boolean` | `false` | Prepends a dot indicator layout. |
 | `isAdd` | `Boolean` | `false` | Adjusts styling for an add/plus icon badge. |

package/.ai/ai_ref_AbButton.md

@@ -2,13 +2,17 @@
 
 Customizable button with optional loader animation and leading icon slot.
 
+**Default variant is `solid`** — when asked to generate `AbButton` with no specific style requested, generate it as-is (don't pass `variant` at all) and it renders as a plain filled button, the way it's used everywhere in this library.
+
 ## Usage
 
 ```vue
 <template>
+  <!-- Default: solid variant (no variant prop needed) -->
   <ab-button color="primary">Save</ab-button>
 
-  <ab-button color="secondary" is-outline show-icon-divider>
+  <!-- Outline variant -->
+  <ab-button color="secondary" variant="outline" show-icon-divider>
     <template #icon><i class="bi bi-plus-lg"></i></template>
     New Item
   </ab-button>
@@ -16,6 +20,9 @@ Customizable button with optional loader animation and leading icon slot.
   <ab-button color="primary" :is-animated="isSaving" is-hide-text-on-animate>
     Save
   </ab-button>
+
+  <!-- Preset: rounded + animated (text auto-hidden), no extra props -->
+  <ab-button color="success" variant="animated-round" :is-animated="isSaving">Save</ab-button>
 </template>
 
 <script setup>
@@ -31,12 +38,13 @@ const isSaving = ref(false);
 | `mode` | `String` | `"button"` | Sets the root tag (`button`, `link`, `router-link`). |
 | `type` | `String` | `"button"` | Native button type (`button`, `submit`, `reset`). |
 | `color` | `String` | `"primary"` | Color variant (primary, secondary, success, danger, warning, info, light, dark). |
+| `variant` | `String` | `"solid"` | Design variant — `"solid"` (plain filled button), `"outline"` (border-only, matches `isOutline`) or `"animated-round"` (preset: acts as `isRounded` + text hidden while animating, without passing those props; the loader still shows only while `isAnimated` is `true`; combine with `isOutline` for an outline look). Drives which class is generated for `color` (e.g. `"outline"` → `btn-outline-{color}`). |
 | `size` | `String` | `"md"` | Button size (`xs`, `sm`, `md`, `lg`, `xl`, `xxl`). |
-| `isOutline` | `Boolean` | `false` | Applies the outline style for the selected color. |
+| `isOutline` | `Boolean` | `false` | Deprecated — equivalent to `variant="outline"`, kept for backward compatibility. Prefer `variant="outline"` in new code. |
 | `isIconBtn` | `Boolean` | `false` | Formats the button styling for a single icon. |
 | `isRounded` | `Boolean` | `false` | Applies a fully rounded, pill-like border radius to the button. |
 | `isAnimated` | `Boolean` | `false` | When `true`, renders the loader SVG and optionally hides the label. |
-| `isHideTextOnAnimate` | `Boolean` | `false` | Hides the default slot content while `isAnimated` is `true`. |
+| `isHideTextOnAnimate` | `Boolean` | `false` | Hides the default slot content while `isAnimated` is `true`. Forced to `true` whenever the button is rounded (`isRounded`, or `variant="animated-round"`) — an explicit `false` is ignored in that case. |
 | `showIconDivider` | `Boolean` | `false` | Renders a vertical divider between the `#icon` slot and the label. |
 | `iconPosition` | `String` | `"left"` | Placement of the icon and divider (`"left"` or `"right"`). |
 

package/.ai/ai_ref_AbCard.md

@@ -1,33 +1,30 @@
 # AbCard — AI Reference
 
-Bootstrap-style card container with `header`, `body`, and `footer` slots. Visual variations (`tile-card`, `item-card`, `insight-card`, …) are applied through CSS classes on `containerClass` rather than separate components.
+Bootstrap-style card container with `header`, `body`, and `footer` slots. Visual variations (`tile-card`, `item-card`, `insight-card`, …) are applied through CSS classes rather than separate components.
+
+**Default variant is `default`** (a plain card, no layout class) — when asked to generate `AbCard` with no specific style requested, generate it as-is (don't pass `variant` at all).
 
 ## Props
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
-| `containerClass` | `String` | `undefined` | CSS class applied to the card root. |
+| `containerClass` | `String` | `undefined` | CSS class applied to the card root. General-purpose — also still the way to reach a custom, one-off class that isn't one of the built-in `variant` values. |
 | `headerClass` | `String` | `""` | CSS class for the header section. |
 | `bodyClass` | `String` | `""` | CSS class for the body section. |
 | `footerClass` | `String` | `""` | CSS class for the footer section. |
+| `variant` | `String` | `"default"` | Design variant — `"default"` (plain card), `"tile"` (→ `.tile-card`, stat blocks), `"item"` (→ `.item-card`, list rows), or `"insight"` (→ `.insight-card`, insight panels). |
 | `isBorderCard` | `Boolean` | `true` | Whether to display the default card border. |
 | `bgColorVariant` | `String` | `""` | Bootstrap color variant for background (`primary`, `success`, etc.). |
 | `borderBottomVariant` | `String` | `""` | Adds a colored bottom border with the specified variant. |
-| `isTileCard` | `Boolean` | `false` | Applies the `.tile-card` layout styles. |
+| `isTileCard` | `Boolean` | `false` | Deprecated — equivalent to `variant="tile"`, kept for backward compatibility. Prefer `variant="tile"` in new code. |
 | `showBorder` | `Boolean` | `false` | Whether to display the header and footer borders. |
-| `variation` | `String` | `""` | Generic variation class to append to the root. |
+| `variation` | `String` | `""` | Generic escape hatch: any string passed here is appended as a raw class on the root, unvalidated — for one-off/custom classes beyond the four `variant` values. |
 
 ## Usage
 
 ```vue
 <template>
-  <ab-card is-tile-card :is-border-card="false">
-    <template #body>
-      <span class="tile-title">Total Revenue</span>
-      <span class="tile-value">$12,480</span>
-    </template>
-  </ab-card>
-
+  <!-- Default: plain card (no variant prop needed) -->
   <ab-card container-class="shadow-sm" border-bottom-variant="primary" header-class="bg-light">
     <template #header>Card Title</template>
     <template #body>Card Content</template>
@@ -35,6 +32,25 @@ Bootstrap-style card container with `header`, `body`, and `footer` slots. Visual
       <ab-button size="sm">Action</ab-button>
     </template>
   </ab-card>
+
+  <!-- Tile variant: high-level stat blocks -->
+  <ab-card variant="tile" :is-border-card="false">
+    <template #body>
+      <span class="tile-title">Total Revenue</span>
+      <span class="tile-value">$12,480</span>
+    </template>
+  </ab-card>
+
+  <!-- Item variant: flexible list-row layout -->
+  <ab-card variant="item">
+    <template #body>...</template>
+  </ab-card>
+
+  <!-- Insight variant: insight/suggestion panel -->
+  <ab-card variant="insight">
+    <template #header>...</template>
+    <template #body>...</template>
+  </ab-card>
 </template>
 ```
 
@@ -48,4 +64,4 @@ Bootstrap-style card container with `header`, `body`, and `footer` slots. Visual
 
 ## Notes
 
-Do **not** create a new `.vue` file for card variations — define the variant as a CSS class in `src/styles/components/_card.scss` and pass it via `containerClass`.
+Do **not** create a new `.vue` file for card variations — define the variant as a CSS class in `src/styles/components/_card.scss` and expose it through the `variant` enum (or `containerClass`/`variation` for a one-off class).

package/.ai/ai_ref_AbColorPicker.md

@@ -32,7 +32,7 @@ const themeColor = ref('blue');
 | --- | --- | --- | --- |
 | `modelValue` | `String` | `""` | Selected color `name` (v-model). |
 | `name` | `String` | `"color"` | Radio group name. |
-| `colors` | `Array` | `[]` | Each: `{ name, color, title? }`. |
+| `colors` | `Array` | `[]` | Each: `{ name, color, title? }`. The selected swatch's outline ring uses that swatch's own `color` (gradient/`url()` values fall back to the theme color). |
 | `align` | `String` | `"left"` | Flex alignment (`left`, `center`, `right`, …). |
 | `borderRadius` | `String` | `"50%"` | Swatch border-radius. |
 | `size` | `String` | `"md"` | Item size (`xs`, `sm`, `md`, `lg`, `xl`, `xxl`). |

package/.ai/ai_ref_AbConfirmPopover.md

@@ -21,11 +21,26 @@ Confirmation popover with an async `onConfirm` handler and built-in loader. Usef
 <script setup>
 async function handleDelete(record) {
   await api.delete(record.id);
-  // loader and popover close handled by the component
+  // loader is handled by the component; returning nothing here closes the
+  // popover automatically — see "onConfirm return contract" below for the
+  // other return shapes (chaining a second confirm step, a success/error alert).
 }
 </script>
 ```
 
+## `onConfirm` return contract
+
+`onConfirm(itemData)` is awaited; what it resolves to (or throws) decides what happens next:
+
+| Resolves to | Result |
+| --- | --- |
+| Nothing (`undefined`/`null`) — the common case, a plain `async () => { await doWork(); }` | Popover closes. |
+| `{ next: 'close' }` | Popover closes (same as returning nothing; use when you also want to pass through other fields, but no other field is read here). |
+| `{ next: 'confirm', title?, message?, icon?, confirmText?, cancelText?, onConfirm? }` | Popover swaps to a new `type: "confirm"` step (Cancel button shown) — for a secondary confirmation. |
+| `{ next: 'confirm-ajax', ...same fields, onConfirm }` | Same as above but `type: "confirm-ajax"` for the next step. |
+| Any other truthy object, e.g. `{ status: true \| false, message? }` | Popover swaps to a terminal `type: "alert"` panel (icon/color from `status`, message from `message`/`msg`, default "Completed successfully" / falls back to "Something went wrong" when `status === false`) — the user must click OK to dismiss. Use this only when you deliberately want that extra confirmation screen. |
+| Throws | Popover shows an `type: "alert"` error panel ("Unexpected error"), dismissed by OK. |
+
 ## Props
 
 | Name | Type | Default | Description |

package/.ai/ai_ref_AbDateTimePicker.md

@@ -33,9 +33,9 @@ const datetime = ref(null);
 | `isRange` | `Boolean` | `false` | Enable date-range mode. |
 | `size` | `String` | `"md"` | Adjusts component size (`xs`, `sm`, `md`, `lg`, `xl`, `xxl`). |
 | `containerClass` | `String` | `"mb-3"` | Wrapper class. |
-| `width` | `String \| Number` | `undefined` | Explicit width on the `.apbd-date-time-container` wrapper. A number is treated as px (e.g. `220` -> `220px`); a string is used as-is (e.g. `"50%"`). |
-| `minWidth` | `String \| Number` | `undefined` | `min-width` on the wrapper (same number/string rules as `width`). |
-| `maxWidth` | `String \| Number` | `undefined` | `max-width` on the wrapper (same number/string rules as `width`) — caps growth inside a flex/grid parent without a fixed `width`. |
+| `width` | `String \| Number` | `undefined` | Explicit width on the `.apbd-date-time-container` wrapper. A number is treated as px (e.g. `220` -> `220px`); a string is used as-is (e.g. `"50%"`). Applied as `min(<value>, 100%)`, so it shrinks to fit a narrower parent on small screens instead of overflowing it. |
+| `minWidth` | `String \| Number` | `undefined` | `min-width` on the wrapper (same number/string rules as `width`, same `min(<value>, 100%)` clamp). |
+| `maxWidth` | `String \| Number` | `undefined` | `max-width` on the wrapper (same number/string rules as `width`, same `min(<value>, 100%)` clamp) — caps growth inside a flex/grid parent without a fixed `width`. |
 | `hints` | `String` | `""` | Helper text. |
 | `isDisable` | `Boolean` | `false` | Disable the picker. |
 | `visibility` | `String` | `"click"` | v-calendar popover trigger. |

package/.ai/ai_ref_AbField.md

@@ -1,6 +1,6 @@
 # AbField — AI Reference
 
-Polymorphic field wrapper — renders text, textarea, select, multiselect, tag, checkbox, radio, toggle, or switch based on the `type` prop.
+Polymorphic field wrapper — renders text, textarea, select, multiselect, tag, checkbox, radio, toggle, or switch based on the `type` prop. For `type="number"` it renders `AbInputField` (a plain native number input by default); add `variant="stepper"` to get `AbInputField`'s numeric-stepper behavior (min/max/step clamping, +/- buttons) instead.
 
 ## Usage
 
@@ -29,6 +29,26 @@ Polymorphic field wrapper — renders text, textarea, select, multiselect, tag,
 </template>
 ```
 
+Number field — plain by default, stepper via `variant`:
+
+```vue
+<template>
+  <!-- Plain native number input (default) -->
+  <ab-field type="number" v-model="form.age" name="age" label="Age" />
+
+  <!-- Numeric stepper: +/- buttons, min/max/step clamping -->
+  <ab-field
+    type="number"
+    variant="stepper"
+    v-model="form.qty"
+    name="qty"
+    label="Quantity"
+    :min="1"
+    :max="10"
+  />
+</template>
+```
+
 ## Props
 
 | Name | Type | Default | Description |
@@ -50,7 +70,7 @@ Polymorphic field wrapper — renders text, textarea, select, multiselect, tag,
 | `options` | `Array` | `[]` | Options for select / checkbox / radio. |
 | `labelKey` | `String` | `"title"` | Option label property. |
 | `valueKey` | `String` | `"val"` | Option value property. |
-| `max` | `Number` | `-1` | Max selections (multiselect/tag); `-1` = unlimited. |
+| `max` | `Number` | `-1` | Max selections (multiselect/tag); `-1` = unlimited. For a `type="number"` field, this doubles as the stepper's numeric ceiling (`min`/`max`/`step` clamping) — `-1`/unset means no ceiling. |
 | `size` | `String` | `undefined` | Field size. |
 | `object` | `Boolean` | `false` | Return full objects instead of values (multiselect). |
 | `searchable` | `Boolean` | `false` | Enable search (select). |
@@ -70,6 +90,11 @@ Polymorphic field wrapper — renders text, textarea, select, multiselect, tag,
 | `hideSelected` | `Boolean` | `true` | Hide already-selected items from dropdown. |
 | `loading` | `Boolean` | `false` | Show a loading spinner. |
 | `appendToBody` | `Boolean` | `true` | Teleport the dropdown to `<body>`. |
+| `variant` | `String` | `undefined` | `type="number"` only. `"stepper"` renders `AbInputField`'s numeric stepper (forces a native number input, shows minus/plus buttons, enables `min`/`max`/`step` clamping) instead of a plain number input. |
+| `min` | `Number \| String` | `null` | `type="number"` only. Minimum allowed value (native constraint always; also clamped + disables the minus button when `variant="stepper"`). |
+| `step` | `Number \| String` | `1` | `type="number"` only. Increment/decrement amount (stepper variant) / native `step` attribute. |
+| `showButtons` | `Boolean` | `true` | `type="number"` + `variant="stepper"` only. Whether to render the minus/plus buttons. |
+| `isBorder` | `Boolean` | `false` | `type="number"` + `variant="stepper"` only. Show inner borders between minus/input/plus. Default is a seamless pill. |
 
 ## Events
 

package/.ai/ai_ref_AbFileUploader.md

@@ -20,6 +20,27 @@ UI or accept a custom one via slots.
     :max-size="5"
   />
 
+  <!-- isCrop: optional crop dialog after picking an image (Cancel = nothing is selected) -->
+  <ab-file-uploader v-model="avatar" is-crop :crop-aspect-ratio="1" />
+
+  <!-- maxWidth/maxHeight: the picked image file itself is downscaled to fit within 300x200
+       before it's emitted; the container keeps its normal width/height box either way -->
+  <ab-file-uploader v-model="avatar" :max-width="300" :max-height="200" />
+
+  <!-- variant="dropzone": icon on top, title + description, AbButton trigger, drag & drop.
+       :is-border="false" drops the dashed border and uses a box-shadow instead -->
+  <ab-file-uploader
+    v-model="avatar"
+    variant="dropzone"
+    :is-border="false"
+    title="Upload pictures"
+    description="Videos must be less than 30 MB and photos must be less than 2 MB in size."
+    button-text="Upload"
+    :width="360"
+  >
+    <template #icon><i class="bi bi-cloud-arrow-up"></i></template>
+  </ab-file-uploader>
+
   <ab-file-uploader v-model="avatar" :max-size="5">
     <template #dial>
       <div class="my-drop-zone">Drop files here</div>
@@ -40,14 +61,25 @@ function handleFiles(files) { console.log('Selected files:', files); }
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
 | `modelValue` | `File \| Array \| String` | `null` | Selected file (or URL string / array). |
+| `isCrop` | `Boolean` | `false` | Image mode only (ignored for `type="file"`): after an image is picked a crop dialog opens with **Crop** and **Cancel** buttons. Crop selects the cropped image (jpeg/png/webp keep their format, others such as gif become png); Cancel closes the dialog and selects nothing (a previously selected image stays). |
+| `cropAspectRatio` | `Number` | `null` | Width / height ratio the crop box is locked to (`1` = square, `16 / 9`, …). `null` = free-form. Only used with `isCrop`. |
 | `maxSize` | `Number` | `2.0` | Max file size in MB. |
 | `label` | `String` | `""` | Field label. |
 | `containerClass` | `String` | `undefined` | Wrapper class (falls back to globalConfig.inputContainerClass). |
 | `type` | `'image' \| 'file'` | `'image'` | Upload mode. `image` only accepts images and always shows a thumbnail preview. `file` accepts any file listed in `allowedTypes`; non-image files render an extension icon instead of a preview. |
 | `allowedTypes` | `Array<String>` | `[]` | Allowed extensions, no dot (e.g. `['pdf', 'docx']`). **Required when `type="file"`** — logs a console error and rejects every selected file when empty. Also drives the input's `accept` attribute. Ignored in `image` mode. |
 | `showFileName` | `Boolean` | `null` | Whether to render the filename below the container. `null` auto-picks by `type` (off for `image`, on for `file`); pass `true`/`false` to override either mode. |
-| `width` | `String \| Number` | `undefined` | Container width. Number is treated as px. Falls back to the default `100px`. |
-| `height` | `String \| Number` | `undefined` | Container height. Number is treated as px. Falls back to the default `73px`. |
+| `width` | `String \| Number` | `undefined` | Container width. Number is treated as px. Falls back to the default `100px`. Not affected by `maxWidth`/`maxHeight` — the preview box always fits the image via `object-fit: contain`. |
+| `height` | `String \| Number` | `undefined` | Container height. Number is treated as px. Falls back to the default `73px`. Not affected by `maxWidth`/`maxHeight`. |
+| `maxWidth` | `String \| Number` | `undefined` | Applies to any picked image file (number = px). If the image's actual width exceeds this, the file itself is downscaled (aspect ratio kept, canvas-based, never upscaled) before it's shown/emitted — so the file a consumer later uploads is already capped. Does not resize the preview container. |
+| `maxHeight` | `String \| Number` | `undefined` | Same as `maxWidth`, for height. Both are applied together as a "contain" cap — the image is scaled down by whichever ratio is smaller so it fits within `maxWidth x maxHeight`. |
+| `variant` | `'default' \| 'dropzone'` | `'default'` | `dropzone` renders a larger card: icon on top, `title`, `description`, then an `AbButton` trigger; clicking the card or dropping a file on it selects a file. `default` and the custom-slot designs are unchanged. |
+| `isBorder` | `Boolean` | `true` | `variant="dropzone"` only. `true` = dashed border, `false` = borderless with a box-shadow. |
+| `title` | `String` | `""` | `variant="dropzone"` only. Bold heading under the icon; hidden when empty (unless the `title` slot is used). |
+| `description` | `String` | `""` | `variant="dropzone"` only. Muted helper text under the title; hidden when empty (unless the `description` slot is used). |
+| `buttonText` | `String` | `"Upload"` | `variant="dropzone"` only. Label of the trigger button. |
+| `buttonColor` | `String` | `"primary"` | `variant="dropzone"` only. `AbButton` `color` of the trigger button. |
+| `buttonSize` | `String` | `undefined` | `variant="dropzone"` only. `AbButton` `size` of the trigger button; falls back to the global `size`. |
 
 ## Events
 
@@ -63,6 +95,14 @@ function handleFiles(files) { console.log('Selected files:', files); }
 | `label` | Custom label. |
 | `dial` | Custom uploader UI (replaces the default design). |
 | `default` | Alternative custom UI slot. |
+| `icon` | Replaces the empty-state icon — the top icon in `variant="dropzone"`, the image/file icon in the default design. Not shown once a file is picked. |
+| `remove-icon` | Replaces the icon on the hover-to-remove overlay over a picked image / file (both designs). |
+| `title` | `variant="dropzone"` only. Replaces the `title` text. |
+| `description` | `variant="dropzone"` only. Replaces the `description` text. |
+| `button` | `variant="dropzone"` only. Replaces the trigger button's label. |
+| `crop-title` | `isCrop` only. Replaces the crop dialog title (default `Crop image`). |
+| `crop-cancel` | `isCrop` only. Replaces the crop dialog's Cancel button label. |
+| `crop-apply` | `isCrop` only. Replaces the crop dialog's Crop button label. |
 
 ## v-model
 
@@ -71,6 +111,7 @@ previews), or `null`.
 
 ## Notes
 
+- In `variant="dropzone"` the icon area has a fixed height (88px) that a picked image fills (aspect ratio kept via `object-fit: contain`, never wider than the card), so the card has the same size with and without an image; override the height with the `--afu-preview-height` CSS variable. A picked non-image file shows its extension icon at 64px.
 - Icon mapping for non-image files (pdf, zip, doc/docx, xls/xlsx, ppt/pptx, video) comes from the
   shared `useFileValidator()` composable's `getFileIconByExt`, the same mapping `AbChatInput` uses.
 - In `image` mode, validation is unchanged from before: only jpg/jpeg/png/gif/webp are accepted and