@appsbd/vue3-appsbd-ui 1.0.19 → 1.0.21

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

@@ -20,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>
@@ -35,13 +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) or `"outline"` (border-only, matches `isOutline`). Drives which class is generated for `color` (e.g. `"outline"` → `btn-outline-{color}`). |
+| `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` | 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_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_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_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

package/.ai/ai_ref_AbFilterPanel.md

@@ -4,9 +4,9 @@ Advanced filter panel for list and table views. Supports quick/advance modes, si
 
 `isMultiple` is functional in `isQuickAdvance` mode for `dd` fields: selections toggle on/off and render as removable tag chips on the popover trigger (no `AbMultiSelect` involved). The popover's option list is searchable — locally against `options`, or via `isAjaxSearch` + `onSearch` for server-side search.
 
-`isBuilderFilter` is a Shopify-style filter builder: no field is visible until the user clicks the `+` button. That opens a popover which first lists every not-yet-applied `filterOptions` entry by `name`; picking one swaps the same popover to a value editor matching that field's `type` (`dd`→`AbMultiSelect`, `t`→`AbInputField`, `tr`→min/max inputs, `d`/`dr`→`AbDateTimePicker`) plus Cancel/Apply Filter buttons. A `"t"` (plain text/number) field also applies on `Enter` in its input — same no-op-when-empty guard as clicking Apply Filter. Apply pushes it in as a removable chip (e.g. "Email : gmail" — see `builderChipSeparator` slot below). By default (`isBuilderAutoSearch: false`), a global Search button is shown so search fires only on clicking Search, and Reset clears all applied chips. When `isBuilderAutoSearch: true`, every Apply and chip removal immediately fires `searchFilter` without showing a Search button. A field's `operators` is fixed by its schema entry, same as other modes — this mode does not add an is/is-not/contains operator picker, only the value input changes per `type`.
+`isBuilderFilter` is a Shopify-style filter builder: no field is visible until the user clicks the `+` button. That opens a popover which first lists every not-yet-applied `filterOptions` entry by `name`; picking one swaps the same popover to a value editor matching that field's `type` (`dd`→`AbMultiSelect`, `t`→`AbInputField`, `tr`→min/max inputs, `d`/`dr`→`AbDateTimePicker`) plus Cancel/Apply Filter buttons. A `"t"` (plain text/number) field also applies on `Enter` in its input — same no-op-when-empty guard as clicking Apply Filter. Apply pushes it in as a removable chip (e.g. "Email : gmail" — see `builderChipSeparator` slot below). By default (`isBuilderAutoSearch: false`), a Search button is shown so search fires only on clicking Search, and Reset clears all applied chips. When `isBuilderAutoSearch: true`, every Apply and chip removal immediately fires `searchFilter` without showing a Search button (only Reset). The Search/Reset buttons are hidden entirely while no chip is applied — they appear right after the `+` button once the first chip is applied, and vanish again when Reset is clicked or the last chip is removed individually. A field's `operators` is fixed by its schema entry, same as other modes — this mode does not add an is/is-not/contains operator picker, only the value input changes per `type`.
 
-Standard-search, advance-search, and quick-advance field layouts are all plain flex (`d-flex flex-wrap gap-2`) — no Bootstrap grid. Each field grows/shrinks on its own, which means a field left alone on the last row will stretch to fill the remaining row width; give a `filterOptions` entry a `width`, `minWidth`, and/or `maxWidth` key (`String | Number` — a number is px, e.g. `maxWidth: 280`, or a CSS string like `"50%"`) to control that specific field's size. All three are forwarded straight to the underlying `AbInputField`/`AbMultiSelect`/`AbDateTimePicker`'s own same-named props, and also constrain that field's flex-item wrapper directly (`width` sets `flex: 0 0 <width>` so it stops growing/shrinking; `minWidth`/`maxWidth` clamp it while it keeps growing/shrinking with its siblings).
+Standard-search, advance-search, and quick-advance field layouts are all plain flex (`d-flex flex-wrap gap-2`) — no Bootstrap grid. Each field grows/shrinks on its own, which means a field left alone on the last row will stretch to fill the remaining row width; give a `filterOptions` entry a `width`, `minWidth`, and/or `maxWidth` key (`String | Number` — a number is px, e.g. `maxWidth: 280`, or a CSS string like `"50%"`) to control that specific field's size. All three are forwarded straight to the underlying `AbInputField`/`AbMultiSelect`/`AbDateTimePicker`'s own same-named props, and also constrain that field's flex-item wrapper directly (`width` sets `flex: 0 0 min(<width>, 100%)` so it stops growing/shrinking; `minWidth`/`maxWidth` clamp it while it keeps growing/shrinking with its siblings). Every one of these is applied as `min(<value>, 100%)`, so a fixed value like `width: 300` never overflows a narrower container on small screens — it shrinks to fit instead.
 
 The standard-mode property-selector (and the scan field it swaps for) isn't part of `filterOptions` — it's not tied to one field, it lists all of them — so it has no `width`/`minWidth`/`maxWidth` key to set. It's also the only item in its row until a property is picked (or whenever `showScanFld` is on), so without sizing it it'll stretch to fill the row the same way an unsized `filterOptions` field would. Use the panel-level `propertySelectWidth`/`propertySelectMinWidth`/`propertySelectMaxWidth` props for that slot instead.
 
@@ -58,9 +58,9 @@ function handleSearch(data) {
 | `isMaxDate`                | `Boolean` | `true`          | Limit date pickers to today as max.                        |
 | `size`                     | `String`  | `"xs"`          | Control size.                                              |
 | `advanceContainerClass`    | `String`  | `""`            | Extra class on each field's flex-item wrapper in advance mode (base sizing is `flex: 1 1 240px`, wraps as needed — not a Bootstrap grid). To fix a single field's width instead, use that field's own `width` prop (`AbInputField`/`AbMultiSelect`/`AbDateTimePicker`). |
-| `propertySelectWidth`      | `String` \| `Number` | `undefined` | Width of the standard-mode property-selector / scan-field slot (number = px). |
-| `propertySelectMinWidth`   | `String` \| `Number` | `undefined` | `min-width` of that same slot. |
-| `propertySelectMaxWidth`   | `String` \| `Number` | `undefined` | `max-width` of that same slot — it's the only item in its row until a property is picked (or in scan mode), so it stretches to fill it without one. |
+| `propertySelectWidth`      | `String` \| `Number` | `undefined` | Width of the standard-mode property-selector / scan-field slot (number = px). Applied as `min(<value>, 100%)`, so it shrinks on small screens instead of overflowing. |
+| `propertySelectMinWidth`   | `String` \| `Number` | `undefined` | `min-width` of that same slot (same `min(<value>, 100%)` clamp). |
+| `propertySelectMaxWidth`   | `String` \| `Number` | `undefined` | `max-width` of that same slot — it's the only item in its row until a property is picked (or in scan mode), so it stretches to fill it without one (same `min(<value>, 100%)` clamp). |
 | `isQuickAdvanceAutoSearch` | `Boolean` | `false`         | Fire search automatically on field change (quick advance). |
 | `defaultFilterId`          | `String` \| `Number` | `""` | Pre-selects a default filter property in standard search mode (when `!isSingle && !isAdvance && !isQuickAdvance`). |
 
@@ -82,3 +82,4 @@ function handleSearch(data) {
 | `hints`                | Helper text.    |
 | `builderChipSeparator` | `isBuilderFilter` mode only. Overrides the connector text rendered between an applied chip's field name and its value (e.g. "Email **:** gmail", "Revenue **:** 12 - 23" for `tr`/`dr` range fields). Receives `{ field }`. Default content is `:`. |
 | `builderAddLabel`      | `isBuilderFilter` mode only. Renders before the static `+` icon inside the "Add filter" button — use it to add a label next to the icon. Not scoped. Empty by default. |
+| `builderTitle`         | `isBuilderFilter` mode only. Title rendered at the far left of the row, inside the same box style as the applied chips. Hidden until at least one chip is applied (and again after Reset / removing the last chip). Not scoped. Default content is `Filter Title`. |

package/.ai/ai_ref_AbInputField.md

@@ -1,6 +1,6 @@
 # AbInputField — AI Reference
 
-Core text input with VeeValidate integration, localized feedback, and prefix/postfix/hint slots. Use for single-line text inputs; use `AbField` for a polymorphic field that can render selects, toggles, etc. Pass `variant="stepper"` to turn it into a numeric stepper input (min/max/step clamping, +/- buttons) — this replaces the deprecated `AbNumberField`.
+Core text input with VeeValidate integration, localized feedback, and prefix/postfix/hint slots. Use for single-line text inputs; use `AbField` for a polymorphic field that can render selects, toggles, etc. Pass `variant="stepper"` to turn it into a numeric stepper input (min/max/step clamping, +/- buttons) — [`AbNumberField`](./ai_ref_AbNumberField.md) is a thin wrapper exposing the same `variant` prop, defaulting to a plain `type="number"` input when it's unset.
 
 ## Usage
 
@@ -49,6 +49,18 @@ const qty = ref(1);
 </script>
 ```
 
+Inset label variant (label inside the bordered box; acts as the placeholder while empty/unfocused, moves to the top on focus / when filled):
+
+```vue
+<ab-input-field v-model="username" variant="inset" name="username" label="Username" />
+```
+
+Outlined variant (floating label: looks like the placeholder when empty, moves onto the top border on focus / when filled; `placeholder` shows on focus):
+
+```vue
+<ab-input-field v-model="username" variant="outlined" name="username" label="Username" placeholder="Enter username" />
+```
+
 Copyable (read-only value with a copy-to-clipboard button — no built-in confirmation UI, wire your own via the `copy-success`/`copy-error` events):
 
 ```vue
@@ -85,9 +97,9 @@ const { toast } = useToast();
 | `size` | `String` | `undefined` | Adjusts component size (`xs`, `sm`, `md`, `lg`, `xl`, `xxl`). |
 | `rules` | `String \| Object` | `""` | VeeValidate rules. |
 | `containerClass` | `String` | `undefined` | Class on the wrapper `<div>`. |
-| `width` | `String \| Number` | `undefined` | Explicit width on the wrapper `<div>`. 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 `<div>` (same number/string rules as `width`). |
-| `maxWidth` | `String \| Number` | `undefined` | `max-width` on the wrapper `<div>` (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 wrapper `<div>`. 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 `<div>` (same number/string rules as `width`, same `min(<value>, 100%)` clamp). |
+| `maxWidth` | `String \| Number` | `undefined` | `max-width` on the wrapper `<div>` (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 beneath the input. |
 | `prefix` | `String` | `""` | Prefix text/icon (shortcut for `#prefix` slot). |
 | `postfix` | `String` | `""` | Postfix text/icon. |
@@ -101,16 +113,24 @@ const { toast } = useToast();
 | `iconPosition` | `String` | `undefined` | Position of the custom `#icon` slot (`"left"`, `"right"`). |
 | `inputClass` | `String \| Object \| Array` | `undefined` | Additional class(es) for the input element. |
 | `inputStyle` | `String \| Object \| Array` | `undefined` | Additional style(s) for the input element. |
-| `variant` | `String` | `undefined` | Layout variant. `"stepper"` renders a numeric stepper (forces `type="number"`, shows +/- buttons, enables `min`/`max`/`step` clamping). |
+| `variant` | `String` | `undefined` | Layout variant. `"stepper"` renders a numeric stepper (forces `type="number"`, shows +/- buttons, enables `min`/`max`/`step` clamping). `"inset"` renders the label inside the bordered field: it acts as the placeholder (centered) while empty and unfocused, and moves to the top, stacked above the value, on focus or when filled — the real `placeholder` shows on focus (border/focus/error styles unchanged; a left `#icon`/`prefix` gets a fixed width so the label aligns — use an icon, not long text). `"outlined"` renders a floating label: shown like a placeholder while empty/unfocused, floats onto the top border when focused or filled, the border is cut away behind it, no label background, RTL supported (real `placeholder` appears on focus; scales with `size`). |
 | `min` | `Number \| String` | `null` | *(stepper variant)* Minimum allowed value. Clamps input and disables the minus button at the floor. |
 | `max` | `Number \| String` | `null` | *(stepper variant)* Maximum allowed value. Clamps input and disables the plus button at the ceiling. |
 | `step` | `Number \| String` | `1` | *(stepper variant)* Increment/decrement amount. |
 | `showButtons` | `Boolean` | `true` | *(stepper variant)* Render the minus/plus controls. |
 | `isBorder` | `Boolean` | `false` | *(stepper variant)* Show inner borders between minus/input/plus. Default is a seamless pill. |
-| `copyable` | `Boolean` | `false` | Renders a plain, borderless postfix button that copies the current value to the clipboard (via the Clipboard API). No built-in confirmation UI — listen for `copy-success`/`copy-error` to show your own (e.g. `useToast()`). Pair with a native `readonly` attribute for a display-only copyable value — there is no built-in read-only mode, `readonly`/`disabled` fall through to the native input via `$attrs`. |
+| `copyable` | `Boolean` | `false` | Renders a plain, borderless postfix button that copies the current value to the clipboard (via the Clipboard API). No built-in confirmation UI — listen for `copy-success`/`copy-error` to show your own (e.g. `useToast()`). Pair with a native `readonly` attribute for a display-only copyable value. |
 | `copySuccessMsg` | `String` | `"Copied to clipboard"` | Message text passed to the `copy-success` event after a successful copy (`copyable` only). Runs through the same translation pipeline as `label`/`hints`. |
 | `copyErrorMsg` | `String` | `"Failed to copy"` | Message text passed to the `copy-error` event when copying fails, e.g. the Clipboard API is unavailable outside a secure context (`copyable` only). |
 
+## Read-only mode
+
+Not a dedicated prop — pass the native `readonly` attribute (it falls through to the input via `$attrs`, same as `disabled`). Unlike `disabled`, it renders exactly like a normal enabled field (no greyed-out background), it keeps the value focusable/selectable/copyable, and it's still submitted with the form — use it when the value must not be *changed* but should still look and read like every other field. On `variant="stepper"`, `readonly` also disables the +/- buttons, so the value truly can't change (native `readonly` alone only blocks typing in the number input, not button clicks).
+
+```vue
+<ab-input-field v-model="accountId" name="account_id" label="Account ID" readonly />
+```
+
 ## Events
 
 | Event | Payload | Description |

package/.ai/ai_ref_AbMultiSelect.md

@@ -27,9 +27,9 @@ Searchable single/multi/tag select. Custom built-in replacement for `@vueform/mu
 | `name` | `String` | `""` | VeeValidate field name. |
 | `rules` | `String \| Object` | `""` | VeeValidate rules. |
 | `containerClass` | `String` | `undefined` | Wrapper class. |
-| `width` | `String \| Number` | `undefined` | Explicit width on the wrapper `<div>`. 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 `<div>` (same number/string rules as `width`). |
-| `maxWidth` | `String \| Number` | `undefined` | `max-width` on the wrapper `<div>` (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 wrapper `<div>`. 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 `<div>` (same number/string rules as `width`, same `min(<value>, 100%)` clamp). |
+| `maxWidth` | `String \| Number` | `undefined` | `max-width` on the wrapper `<div>` (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. |
 | `multiple` | `Boolean` | `false` | Deprecated — use `mode` instead. |
 | `searchable` | `Boolean` | `false` | Enable option search/filter. |

package/.ai/ai_ref_AbNumberField.md

@@ -1,16 +1,18 @@
 # AbNumberField — AI Reference
 
-> **Deprecated.** `AbNumberField` is now a thin wrapper around [`AbInputField`](./ai_ref_AbInputField.md) with `variant="stepper"`. It is kept for backward compatibility and still works exactly as documented below, but prefer `<ab-input-field variant="stepper" ... />` in new code.
-
-Numeric input with minus/plus buttons, min/max clamping, custom step, and VeeValidate integration. Renders as a seamless pill by default; pass `is-border` to show internal dividers between buttons and input.
+Numeric input with VeeValidate integration. By default it renders a plain native `type="number"` input; pass `variant="stepper"` to turn it into a stepper with minus/plus buttons, min/max clamping, and a custom step. `AbNumberField` is a thin wrapper around [`AbInputField`](./ai_ref_AbInputField.md) — `<ab-number-field variant="stepper" ... />` and `<ab-input-field variant="stepper" type="number" ... />` render identically. Renders the stepper as a seamless pill by default; pass `is-border` to show internal dividers between buttons and input.
 
 ## Usage
 
 ```vue
 <template>
-  <ab-number-field v-model="qty" name="quantity" label="Quantity" :min="1" :max="10" :step="1" hints="Clamped between 1 and 10" />
+  <!-- Default: plain number input -->
+  <ab-number-field v-model="qty" name="quantity" label="Quantity" />
+
+  <!-- Stepper: minus/plus buttons with min/max clamping -->
+  <ab-number-field v-model="qty" name="quantity" label="Quantity" variant="stepper" :min="1" :max="10" :step="1" hints="Clamped between 1 and 10" />
 
-  <ab-number-field v-model="qty" name="quantity" label="Quantity" is-border />
+  <ab-number-field v-model="qty" name="quantity" label="Quantity" variant="stepper" is-border />
 </template>
 
 <script setup>
@@ -32,12 +34,14 @@ const qty = ref(1);
 | `hints` | `String` | `""` | Helper text beneath the input. |
 | `prefix` | `String` | `""` | Prefix text/icon (shortcut for `#prefix` slot). |
 | `postfix` | `String` | `""` | Postfix text/icon. |
-| `min` | `Number \| String` | `null` | Minimum allowed value. Clamps input and disables the minus button at the floor. |
-| `max` | `Number \| String` | `null` | Maximum allowed value. Clamps input and disables the plus button at the ceiling. |
-| `step` | `Number \| String` | `1` | Increment/decrement amount. |
-| `showButtons` | `Boolean` | `true` | Render the minus/plus controls. |
+| `variant` | `String` | `undefined` | Pass `"stepper"` to render minus/plus buttons with min/max/step clamping. Left unset, renders a plain native `type="number"` input with no buttons or clamping (min/max/step are still applied as native input attributes). |
+| `min` | `Number \| String` | `null` | Minimum allowed value. With `variant="stepper"`, clamps the typed value and disables the minus button at the floor; otherwise it's only the native `min` attribute. |
+| `max` | `Number \| String` | `null` | Maximum allowed value. With `variant="stepper"`, clamps the typed value and disables the plus button at the ceiling; otherwise it's only the native `max` attribute. |
+| `step` | `Number \| String` | `1` | Increment/decrement amount (`variant="stepper"`), or the native `step` attribute otherwise. |
+| `showButtons` | `Boolean` | `true` | Render the minus/plus controls. Only applies when `variant="stepper"`. |
 | `disabled` | `Boolean` | `false` | Disable the field and both buttons. |
-| `isBorder` | `Boolean` | `false` | Show inner borders between minus/input/plus. Default is a seamless pill. |
+| `readonly` | `Boolean` | `false` | Make the field read-only and disable both buttons (`variant="stepper"`). Renders like a normal enabled field (no greyed-out background), unlike `disabled`. |
+| `isBorder` | `Boolean` | `false` | Show inner borders between minus/input/plus. Default is a seamless pill. Only applies when `variant="stepper"`. |
 | `isLeftIconBorder` | `Boolean` | `false` | Render border between the prefix icon and the input. |
 | `isRightIconBorder` | `Boolean` | `false` | Render border between the postfix icon and the input. |
 | `size` | `String` | `undefined` | Input size: `"xs"`, `"sm"`, `"md"`, `"lg"`, `"xl"`. Falls back to `globalConfig.size`, then `"md"`. |
@@ -46,8 +50,8 @@ const qty = ref(1);
 
 | Event | Payload | Description |
 | --- | --- | --- |
-| `update:modelValue` | `number \| null` | v-model sync. Value is `number` after clamping, or `null` when cleared. |
-| `input` | `number` | Fired on input after clamping. |
+| `update:modelValue` | `number \| null` | v-model sync. With `variant="stepper"`, value is `number` after clamping, or `null` when cleared. |
+| `input` | `number` | Fired on input. With `variant="stepper"`, fired after clamping. |
 | `keyup` | `KeyboardEvent` | Forwarded native event. |
 | `keydown` | `KeyboardEvent` | Forwarded native event. |
 | `paste` | `ClipboardEvent` | Forwarded native event. |
@@ -57,6 +61,10 @@ const qty = ref(1);
 | Name | Description |
 | --- | --- |
 | `label` | Custom label content. |
-| `prefix` | Prefix icon / text (rendered before the minus button). |
-| `postfix` | Postfix icon / text (rendered after the plus button). |
+| `prefix` | Prefix icon / text (rendered before the minus button when `variant="stepper"`). |
+| `postfix` | Postfix icon / text (rendered after the plus button when `variant="stepper"`). |
 | `hints` | Helper text (overrides `hints` prop). |
+
+## v-model
+
+Yes — `modelValue` + `update:modelValue`. Nullable; with `variant="stepper"` the value is clamped to `min`/`max` and coerced to `number` (or `null` when the field is cleared).

package/.ai/ai_ref_AbToggle.md

@@ -25,6 +25,9 @@ Accessible switch/toggle control. Supports title + description layout and custom
 | `size` | `String` | `"md"` | Toggle size. |
 | `trueValue` | `any` | `"Y"` | Value when checked. |
 | `falseValue` | `any` | `"N"` | Value when unchecked. |
+| `hasIcon` | `Boolean` | `false` | Renders default enable (check) and disable (cross) icons inside switch track. |
+| `onIcon` | `Component \| String` | `Check` | Custom icon component or CSS class for enabled state. |
+| `offIcon` | `Component \| String` | `X` | Custom icon component or CSS class for disabled state. |
 | `title` | `String \| null` | `null` | Title next to the toggle. |
 | `description` | `String \| null` | `null` | Description under the title. |
 | `hints` | `String \| null` | `null` | Helper text. |
@@ -43,4 +46,6 @@ Accessible switch/toggle control. Supports title + description layout and custom
 | `title` | Custom title. |
 | `description` | Custom description. |
 | `descriptionContainer` | Wraps the entire title + description block. |
+| `on-icon` | Custom icon for enabled state inside track. |
+| `off-icon` | Custom icon for disabled state inside track. |
 | `hints` | Custom hints. |