@appsbd/vue3-appsbd-ui 1.0.13 → 1.0.15

package/.ai/ai_ref_AbChatBox.md

@@ -0,0 +1,148 @@
+# AbChatBox — AI Reference
+
+A full chat conversation container built on top of `AbChatInput` — header, scrollable message list (with
+empty/typing states), and the composer. Every part is slot-overridable, so pick this over building a chat UI by
+hand whenever you need a message list around `AbChatInput`, not just the composer itself.
+
+## Installation
+
+Not globally registered — import it explicitly:
+
+```js
+import { AbChatBox } from 'vue3-appsbd-ui';
+```
+
+No extra peer deps beyond `AbChatInput`'s own (`@lucide/vue`).
+
+## Usage
+
+`v-model:messages` holds the conversation array, `v-model` holds the composer's text. Submitting auto-appends the
+user's message and fires `send` — handle that to call your API and push the reply back:
+
+```vue
+<template>
+  <AbChatBox
+    v-model="message"
+    v-model:messages="messages"
+    title="Support Bot"
+    subtitle="Usually replies in a few seconds"
+    :loading="loading"
+    @send="onSend"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue';
+import { AbChatBox } from 'vue3-appsbd-ui';
+
+const message = ref('');
+const messages = ref([
+  { id: 1, role: 'assistant', name: 'Assistant', text: 'Hi! How can I help you today?' },
+]);
+const loading = ref(false);
+
+function onSend({ message, files }) {
+  loading.value = true;
+  callMyApi(message).then((reply) => {
+    loading.value = false;
+    messages.value.push({ id: Date.now(), role: 'assistant', text: reply });
+  });
+}
+</script>
+```
+
+Any `AbChatInput` prop/event/slot works directly on `AbChatBox` — it's forwarded straight to the inner composer:
+
+```vue
+<template>
+  <AbChatBox
+    v-model="message"
+    v-model:messages="messages"
+    v-model:files="files"
+    :max-file-size="2"
+    :allowed-extensions="['jpg', 'jpeg', 'png', 'pdf']"
+    placeholder="Ask anything"
+  >
+    <template #single-input="{ addToAttach }">
+      <AbChatInputMenuItem :icon="Paperclip" name="Upload file" :action="() => addToAttach()" />
+    </template>
+  </AbChatBox>
+</template>
+```
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `messages` | `Array` | `[]` | v-model:messages. See "Message shape" below. |
+| `modelValue` | `String` | `""` | Two-way-bound composer text — forwarded to the inner `AbChatInput`. |
+| `title` | `String` | `""` | Default header title (translated). |
+| `subtitle` | `String` | `""` | Default header subtitle (translated). |
+| `avatar` | `String` | `""` | Default header avatar image URL. |
+| `loading` | `Boolean` | `false` | Shows the typing indicator at the bottom of the message list. |
+| `emptyText` | `String` | `"Start a conversation"` | Text shown by the default empty state (translated). |
+| `emptyIcon` | `Object \| Function` | `MessageCircle` | Icon shown above `emptyText`. Pass `null` to hide it. |
+| `autoScroll` | `Boolean` | `true` | Auto-scrolls the message list to the bottom on new messages / `loading` changes. |
+| `containerClass` | `String` | `undefined` | Extra class on the root element. |
+
+Any other prop not listed above (`placeholder`, `disabled`, `readonly`, `minHeight`, `maxHeight`, `submitOnEnter`,
+`allowNewLine`, `autoFocus`, `autoPreview`, `maxFileSize`, `allowedExtensions`, `borderRadius`,
+`filePreviewWidth`, `filePreviewHeight`, `showFileName`, `showVoiceButton`, ...) falls through untouched to the
+inner `AbChatInput` — see `.ai/ai_ref_AbChatInput.md` for the full list.
+
+## Events
+
+| Event | Payload | Description |
+| --- | --- | --- |
+| `update:messages` | `Message[]` | v-model:messages sync — fires after the user's message is auto-appended, or after `addMessage()`. |
+| `update:modelValue` | `string` | v-model sync for the composer text. |
+| `send` | `{ message: string, files: FileEntry[] }` | Fired right after the user's message is auto-appended to `messages` — hook here to call an API and push the reply. |
+
+Any other `AbChatInput` event (`focus`, `blur`, `keydown`, `file-click`, `file-remove`, `file-reject`,
+`voice-start`, `voice-stop`, `voice-cancel`, `voice-error`, `update:files`) is forwarded straight from the inner
+composer — listen for it on `AbChatBox` exactly as you would on `AbChatInput`. Note: `submit` itself is **not**
+forwarded — `AbChatBox` consumes it internally to auto-append + emit `send`.
+
+## Slots
+
+| Name | Description |
+| --- | --- |
+| `header` | Overrides the entire header. Scoped: `{ title, subtitle, avatar }`. |
+| `header-actions` | Adds content to the right side of the default header, without replacing it. |
+| `empty` | Overrides the empty state (shown when `messages` is empty). |
+| `message` | Overrides one message's whole bubble. Scoped: `{ message, index }`. |
+| `message-avatar` | Overrides just the avatar inside the default bubble. Scoped: `{ message }`. |
+| `typing` | Overrides the typing indicator (shown when `loading` is `true`). |
+| `left` / `right` / `send-button` / `menu-trigger` / `single-input` / `multiple-input` | `AbChatInput`'s own slots — forwarded straight through to the inner composer with the same scoped props (`addToAttach`, `addFiles`, `removeFile`, `clearFiles`, `updateText`, `focus`, `submit`). See `.ai/ai_ref_AbChatInput.md`. |
+
+## v-model
+
+Yes — two v-models: `modelValue` + `update:modelValue` (string, the composer text) and `messages` +
+`update:messages` (`Message[]`, the conversation). A third, `files` + `update:files`, is available by passthrough
+if you use `v-model:files` (forwarded to the inner `AbChatInput`).
+
+### Message shape
+
+Any plain object works — only `role` is read internally (to align the bubble left/right); everything else is
+just read by the default bubble template (or your own, via `#message`).
+
+```js
+{
+  id,      // stable key; auto-generated if omitted
+  role,    // "user" | "assistant" | "system" — "user" aligns right, others left
+  text,    // message body
+  name,    // optional sender name, shown above the text
+  avatar,  // optional avatar image URL
+  time,    // optional string, shown below the text
+  files,   // optional array — rendered as a small attachment list ({ name } or a plain string)
+}
+```
+
+## Exposed methods
+
+| Method | Description |
+| --- | --- |
+| `addMessage(message)` | Appends a message (fills in a default `id`/`role` if omitted), fires `update:messages`, and auto-scrolls. Returns the stored message. |
+| `scrollToBottom()` | Scrolls the message list to the bottom. |
+| `focus()` | Focuses the composer's textarea. |
+| `chatInput` | Raw template ref to the inner `AbChatInput` — call any of its own exposed methods directly (`submit()`, `addToAttach()`, `startRecording()`, etc). See `.ai/ai_ref_AbChatInput.md`. |

package/.ai/ai_ref_AbChatInput.md

@@ -0,0 +1,235 @@
+# AbChatInput — AI Reference
+
+A ChatGPT-style auto-growing chat/message composer. Use for AI chat interfaces, comment boxes that need to grow with content, or any message input needing configurable Enter/Shift+Enter/Ctrl+Enter submit behavior. Pair with `AbChatInputMenuItem` for the built-in add/more dropdown.
+
+## Installation
+
+Not globally registered — import it explicitly:
+
+```js
+import { AbChatInput, AbChatInputMenuItem } from 'vue3-appsbd-ui';
+```
+
+No extra peer deps beyond the library's own (`@lucide/vue` for the default "+" icon).
+
+## Usage
+
+A send button (arrow-up icon, `AbButton` with `color="primary"`) renders on the right by default and calls the
+same submit logic as pressing Enter — no manual wiring needed:
+
+```vue
+<template>
+  <AbChatInput v-model="message" placeholder="Ask anything" @submit="onSubmit" />
+</template>
+
+<script setup>
+import { ref } from 'vue';
+import { AbChatInput } from 'vue3-appsbd-ui';
+
+const message = ref('');
+function onSubmit({ message, files }) {
+  console.log(message, files);
+}
+</script>
+```
+
+Override the default send button via the scoped `#send-button` slot (e.g. to add a label, swap the icon, or
+change its color) — call the scoped `submit()` to fire the same `submit` event the default button would:
+
+```vue
+<template>
+  <AbChatInput v-model="message" @submit="onSubmit">
+    <template #send-button="{ submit }">
+      <AbButton color="success" is-icon-btn is-rounded size="sm" @click="submit">
+        <Send :size="18" />
+      </AbButton>
+    </template>
+  </AbChatInput>
+</template>
+```
+
+Add/more dropdown (0 items = no trigger, 1 item = direct action with no popover, 2+ items = a real dropdown):
+
+```vue
+<template>
+  <AbChatInput v-model="message">
+    <template #multiple-input>
+      <AbChatInputMenuItem v-for="item in menuItems" :key="item.name" v-bind="item" />
+    </template>
+  </AbChatInput>
+</template>
+```
+
+File attachments — selection stays the consumer's job, validation/storage/preview are internal. Every content
+slot (`left`/`right`/`menu-trigger`/`single-input`/`multiple-input`) is scoped, handing back `addToAttach` (opens
+a native file picker and routes the selection through `addFiles`) among other methods — no template
+`<input type="file">` and no ref needed:
+
+```vue
+<template>
+  <AbChatInput
+    v-model="message"
+    v-model:files="attachedFiles"
+    :max-file-size="2"
+    :allowed-extensions="['jpg', 'jpeg', 'png', 'pdf']"
+  >
+    <template #single-input="{ addToAttach }">
+      <AbChatInputMenuItem
+        :icon="Paperclip"
+        name="Upload file"
+        :action="() => addToAttach({ accept: '.jpg,.jpeg,.png,.pdf' })"
+      />
+    </template>
+  </AbChatInput>
+</template>
+```
+
+## Voice input
+
+Uses the browser's native Web Speech API (`SpeechRecognition`) — no extra dependency, no API key. A built-in mic
+button renders in the `right` area (before the `right` slot and the send button) whenever `showVoiceButton` is
+`true` (default).
+Clicking it (or calling `startRecording()`) swaps the whole composer row for a full-width recording bar — a live
+audio-reactive waveform (via `getUserMedia` + `AnalyserNode`) plus three controls:
+
+- **✕ cancel** — discards everything spoken this session, reverting `modelValue` to what it was before recording started.
+- **■ stop** — stops recording and keeps the transcribed text in the textarea (no submit).
+- **↑ submit** — stops recording, keeps the text, then fires `submit` immediately.
+
+Recognized speech is appended to the existing `modelValue` (not replaced), one final phrase at a time — interim
+(still-speaking) text is not shown live.
+
+A small language-code badge (e.g. `EN`, `BN`) sits on the mic button's corner. Clicking it opens an `AbPopover`
+with a searchable list of ~130 BCP-47 locales; picking one sets that recognition session's `SpeechRecognition.lang`
+and persists the choice to `localStorage` (key `apbd-chat-input-voice-lang`) so it's remembered next visit. This
+never touches the browser's own language/locale settings — only this component's own recognizer instance.
+
+Not supported in Firefox. On iOS, only Safari itself gets it — Chrome/Firefox/Edge/Opera on iOS run on the same
+underlying WebKit engine and expose the same `webkitSpeechRecognition` constructor, but iOS never grants the mic
+permission for it outside of Safari's own app (no permission prompt ever appears; `.start()` would otherwise fail
+with a confusing, prompt-less "permission denied"), so these are detected via user-agent and treated as unsupported
+too. The mic button still renders in all of these cases but is `disabled`, with a tooltip explaining why. Where it
+is supported, requires the browser's mic permission prompt to be accepted.
+
+On Android, the live waveform is skipped (bars stay flat) — recognition and transcription work normally. Android's
+mic hardware only allows one exclusive audio-capture session at a time; a second concurrent `getUserMedia` stream
+for the waveform would starve `SpeechRecognition` of audio (no error, no transcript, ever). This is detected via
+user-agent, not feature-tested.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `modelValue` | `String` | `""` | Two-way-bound message text. |
+| `files` | `Array` | `[]` | v-model:files — see "Attached file shape" below. |
+| `placeholder` | `String` | `""` | Textarea placeholder (translated). |
+| `disabled` | `Boolean` | `false` | Disables the textarea and the menu trigger. |
+| `readonly` | `Boolean` | `false` | Makes the textarea read-only. |
+| `loading` | `Boolean` | `false` | Visual loading state (CSS hook only — does not itself disable input). |
+| `minHeight` | `Number` | `52` | Minimum textarea height in px. Also the threshold: past this, the composer switches to the "grown" stacked layout (see below). |
+| `maxHeight` | `Number` | `200` | Maximum textarea height in px; internal scroll kicks in beyond this. |
+| `submitOnEnter` | `Boolean` | `true` | `true`: Enter submits, Shift+Enter inserts a newline. `false`: Enter inserts a newline, Ctrl+Enter/Cmd+Enter submits. |
+| `allowNewLine` | `Boolean` | `true` | If `false`, Enter never inserts a newline regardless of `submitOnEnter`. |
+| `autoFocus` | `Boolean` | `false` | Focus the textarea on mount. |
+| `autoPreview` | `Boolean` | `true` | When `true`, clicking a file chip opens the built-in preview lightbox. When `false`, only the `file-click` event fires. |
+| `maxFileSize` | `Number` | `null` | Max size in MB per file. `null` = no limit. Enforced by `addFiles()`. |
+| `allowedExtensions` | `Array` | `[]` | Case-insensitive allowed extensions (e.g. `['jpg','png','pdf']`). Empty = all types allowed. Enforced by `addFiles()`. |
+| `containerClass` | `String` | `undefined` | Wrapper class; falls back to `globalConfig.inputContainerClass`. |
+| `borderRadius` | `String` | `"1.5rem"` | Composer roundness — any CSS length (e.g. `"0.5rem"`, `"8px"`, `"1.5rem"`). |
+| `filePreviewWidth` | `Number` | `24` | Width (px) of each attached file's thumbnail/icon in the chip. |
+| `filePreviewHeight` | `Number` | `24` | Height (px) of each attached file's thumbnail/icon in the chip. |
+| `showFileName` | `Boolean` | `true` | Show/hide the filename text next to the chip thumbnail. |
+| `showVoiceButton` | `Boolean` | `true` | Show/hide the built-in mic button (see "Voice input" below). Set `false` to build custom voice UI via slots instead. |
+
+## Events
+
+| Event | Payload | Description |
+| --- | --- | --- |
+| `update:modelValue` | `string` | v-model sync. |
+| `update:files` | `FileEntry[]` | v-model:files sync — fired after `addFiles`/`removeFile`/`clearFiles`. |
+| `submit` | `{ message: string, files: FileEntry[] }` | Fired on Enter/Ctrl+Enter/Cmd+Enter per `submitOnEnter`. Not fired when `disabled`/`readonly`. |
+| `focus` / `blur` | `FocusEvent` | Forwarded native events. |
+| `keydown` | `KeyboardEvent` | Forwarded native event; fires before any submit/newline logic runs. |
+| `file-click` | `FileEntry` | A file chip was clicked (fires regardless of `autoPreview`). |
+| `file-remove` | `FileEntry` | A file chip's remove button was clicked. |
+| `file-reject` | `{ file: File, reason: string }` | A file failed `maxFileSize`/`allowedExtensions` validation. A `useToast` error is also shown. |
+| `voice-start` | — | Voice recording started (mic button clicked or `startRecording()` called). |
+| `voice-stop` | — | Recording stopped normally (■ button, ↑ submit button, `stopRecording()`, or the browser ending it on its own) — transcribed text is kept in `modelValue`. |
+| `voice-cancel` | — | Recording was cancelled (✕ button or `cancelRecording()`) — `modelValue` is reverted to what it was before recording started. |
+| `voice-error` | `Error \| SpeechRecognitionErrorEvent` | Mic permission was denied, or the recognition engine errored. A `useToast` error is also shown (except benign `no-speech`/`aborted` errors). |
+
+## Slots
+
+| Name | Description |
+| --- | --- |
+| `left` | Left action area (e.g. an attachment button). Scoped — see below. |
+| `right` | Right action area, rendered before the send button (e.g. extra icon buttons). Scoped — see below. |
+| `send-button` | Overrides the default send button (an `AbButton` with an arrow-up icon, `color="primary"`, calling `submit()`). Always rendered — there's no prop to hide it; override this slot with empty content if you don't want one. Scoped — see below. |
+| `menu-trigger` | Overrides the default "+" icon on the add/more trigger. Only rendered when the trigger itself renders (see below). Scoped — see below. |
+| `single-input` | One static `AbChatInputMenuItem` for the add/more dropdown. Scoped — see below. |
+| `multiple-input` | A `v-for`'d set of `AbChatInputMenuItem`s for the add/more dropdown. Scoped — see below. |
+
+**All six slots are scoped**, receiving the same props so slot content can drive the composer directly:
+
+| Scoped prop | Description |
+| --- | --- |
+| `addToAttach(options?)` | Opens a native file picker and routes the selection through `addFiles`. `options`: `{ accept, multiple }` (`multiple` defaults to `true`). |
+| `addFiles(files)` | Same as the exposed method — validates and appends an already-obtained `File[]`/`FileList` (drag-drop, paste, etc.). |
+| `removeFile(id)` | Same as the exposed method. |
+| `clearFiles()` | Same as the exposed method. |
+| `updateText(text)` | Replaces the message text (fires `update:modelValue`). |
+| `focus()` | Focuses the textarea. |
+| `submit()` | Same as the exposed method — fires `submit` with `{ message, files }`. No-op when `disabled`/`readonly`. |
+
+A single-item `#single-input`/`#multiple-input` action can use these directly — `onMenuTriggerClick`'s no-dropdown
+fast path reads the item's `action` prop with these same bindings applied, so `:action="addToAttach"` works there too.
+
+**Layout — single line vs. "grown"**: below `minHeight` worth of content (one line), `left`/textarea/`right` share a single row, centered. Past that, the composer switches to a ChatGPT-style stacked layout: the textarea becomes its own full-width row on top, and `left`/`right` wrap onto a second full-width row below it (`right` stays pinned to that row's end even when `left` isn't rendered at all). This is purely CSS-driven off the same measured content height — no extra prop.
+
+**Add/more trigger behavior** is driven by the total count of valid items across `single-input` + `multiple-input` combined, not by which slot they came from:
+- 0 items → no trigger renders at all (fully backward-compatible with plain `left`-slot-only usage).
+- 1 item → the trigger stays the default "+" icon; clicking it calls that item's `action` directly, no dropdown opens.
+- 2+ items → clicking the trigger opens a dropdown (custom-positioned, teleported to `<body>`, matching the composer's full width — not `AbPopover`, which sizes/anchors to the trigger button instead) listing every item (with a divider between the two slot groups if both are non-empty). Opens below by default and flips above (capped to the available space, scrolling internally if needed) when there isn't room below — never clipped by the viewport or a scrolling ancestor.
+
+## v-model
+
+Yes — `modelValue` + `update:modelValue` (string). Also a second v-model: `files` + `update:files` (`FileEntry[]`).
+
+### Attached file shape (`FileEntry`)
+
+```js
+{
+  id,           // stable string key, generated internally
+  file,         // the raw File object
+  name,
+  size,
+  type,
+  extension,    // lowercased, no dot
+  isImage,      // boolean — drives chip thumbnail vs icon
+  previewKind,  // 'image' | 'video' | 'audio' | 'pdf' | 'none' — drives lightbox rendering
+  url,          // objectURL — revoked automatically on removeFile()/clearFiles()/unmount
+  fileIcon,     // icon component for non-image chip display
+}
+```
+
+## Exposed methods
+
+Same methods as the scoped slot props above (see "Slots"), also available via a template ref for use outside
+any slot — e.g. a toolbar button elsewhere on the page.
+
+| Method | Description |
+| --- | --- |
+| `addFiles(files)` | Accepts a `File[]` or `FileList`. Validates each against `maxFileSize`/`allowedExtensions`; rejected files fire `file-reject` + a toast and are never added. Accepted files are appended and `update:files` fires once with the full list. |
+| `removeFile(id)` | Removes one attached file by `id`, revoking its object URL. |
+| `clearFiles()` | Removes all attached files, revoking every object URL. |
+| `addToAttach(options?)` | Opens a native file picker and routes the selection through `addFiles`. `options`: `{ accept, multiple }`. |
+| `updateText(text)` | Replaces the message text (fires `update:modelValue`). |
+| `focus()` | Focuses the textarea. |
+| `submit()` | Fires `submit` with `{ message, files }` (same as clicking the default send button). No-op when `disabled`/`readonly`. |
+| `startRecording()` | Starts voice input (same as clicking the mic button). No-op if unsupported/disabled/readonly/already recording. |
+| `stopRecording()` | Stops recording, keeping the transcribed text (same as the ■ button). |
+| `cancelRecording()` | Stops recording and discards the transcribed text (same as the ✕ button). |
+
+## Provides
+
+`abChatInputCloseMenu` (no-arg function) — consumed by `AbChatInputMenuItem` to auto-close the dropdown after its `action` fires. Not meant to be consumed by anything else.

package/.ai/ai_ref_AbChatInputMenuItem.md

@@ -0,0 +1,55 @@
+# AbChatInputMenuItem — AI Reference
+
+A single row (icon + name + optional description) for `AbChatInput`'s add/more dropdown. Not useful outside `AbChatInput` — see [.ai/ai_ref_AbChatInput.md](./ai_ref_AbChatInput.md).
+
+## Installation
+
+Not globally registered — import it explicitly. Requires `@lucide/vue` (or any icon component) for the `icon` prop.
+
+## Usage
+
+```vue
+<template>
+  <AbChatInput v-model="message">
+    <template #single-input>
+      <AbChatInputMenuItem :icon="Paperclip" name="Attach a file" description="jpg, png, pdf" :action="onAttach" />
+    </template>
+  </AbChatInput>
+</template>
+
+<script setup>
+import { ref } from 'vue';
+import { AbChatInput, AbChatInputMenuItem } from 'vue3-appsbd-ui';
+import { Paperclip } from '@lucide/vue';
+
+const message = ref('');
+function onAttach() { /* open a file picker, etc. */ }
+</script>
+```
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `icon` | `Object \| Function` | `null` | Icon component (e.g. a `@lucide/vue` icon). |
+| `name` | `String` | `""` | Item title (passed through `translateGetMsg`). |
+| `description` | `String` | `""` | Optional secondary line (passed through `translateGetMsg`). |
+| `action` | `Function` | `null` | Called on click. **Important:** when this item is the only one registered across `#single-input`/`#multiple-input`, `AbChatInput` reads this prop directly off the item's VNode and calls it without mounting the item — always pass a plain function, not something that depends on the component being mounted first. |
+
+## Events
+
+| Event | Payload | Description |
+| --- | --- | --- |
+| `click` | — | Fired on click, after `action()`. |
+
+## Slots
+
+None.
+
+## v-model
+
+Not applicable — stateless presentational item.
+
+## Injects
+
+`abChatInputCloseMenu` (optional, no-arg function) — provided by the parent `AbChatInput`; called after `action()`/`click` to close the dropdown. No consumer wiring needed.

package/.ai/ai_ref_AbDateTimePicker.md

@@ -46,7 +46,7 @@ const datetime = ref(null);
 | `monthNames` | `Array` | `undefined` | Custom full month names. |
 | `monthNamesShort` | `Array` | `undefined` | Custom short month names. |
 | `dayNames` | `Array` | `undefined` | Custom day names. |
-| `formatDigit` | `Function` | `undefined` | Locale digit formatter (e.g. Bengali digits). |
+| `digits` | `Array` | `undefined` | 10-character digits array (0-9) for locale digit transliteration (e.g. Bangla digits), overriding `globalConfig.digits`. |
 | `rangeSeparator` | `String` | `undefined` | Display separator between range start/end. |
 | `mode` | `String` | `"date"` | `date`, `time`, or `datetime`. |
 | `is24Hour` | `Boolean` | `undefined` | 24-hour clock. |

package/.ai/ai_ref_AbFileUploader.md

@@ -1,6 +1,8 @@
 # AbFileUploader — AI Reference
 
-File upload input with drag-and-drop, size validation, and preview. Can render a default uploader UI or accept a custom one via slots.
+File upload input with drag-and-drop, size/type validation, and preview. Supports an image-only
+mode (default) or a generic file mode with extension-icon previews. Can render a default uploader
+UI or accept a custom one via slots.
 
 > Also available inside `AbCustomField` via the `FU` field type — see [.ai/ai_ref_AbCustomField.md](./ai_ref_AbCustomField.md).
 
@@ -8,9 +10,17 @@ File upload input with drag-and-drop, size validation, and preview. Can render a
 
 ```vue
 <template>
-  <ab-file-uploader v-model="file" label="Upload avatar" :max-size="1.5" @on-select-files="handleFiles" />
+  <ab-file-uploader v-model="avatar" label="Upload avatar" :max-size="1.5" @on-select-files="handleFiles" />
 
-  <ab-file-uploader v-model="file" :max-size="5">
+  <!-- File mode: allowedTypes is required, non-image files show an extension icon -->
+  <ab-file-uploader
+    v-model="doc"
+    type="file"
+    :allowed-types="['pdf', 'doc', 'docx', 'xlsx']"
+    :max-size="5"
+  />
+
+  <ab-file-uploader v-model="avatar" :max-size="5">
     <template #dial>
       <div class="my-drop-zone">Drop files here</div>
     </template>
@@ -19,7 +29,8 @@ File upload input with drag-and-drop, size validation, and preview. Can render a
 
 <script setup>
 import { ref } from 'vue';
-const file = ref(null);
+const avatar = ref(null);
+const doc = ref(null);
 function handleFiles(files) { console.log('Selected files:', files); }
 </script>
 ```
@@ -32,13 +43,18 @@ function handleFiles(files) { console.log('Selected files:', files); }
 | `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`. |
 
 ## Events
 
 | Event | Payload | Description |
 | --- | --- | --- |
-| `update:modelValue` | `file` | v-model sync. |
-| `onSelectFiles` | `files` | All selected files after size validation. |
+| `update:modelValue` | `file \| null` | v-model sync. |
+| `onSelectFiles` | `files` | All selected files after validation. |
 
 ## Slots
 
@@ -47,3 +63,15 @@ function handleFiles(files) { console.log('Selected files:', files); }
 | `label` | Custom label. |
 | `dial` | Custom uploader UI (replaces the default design). |
 | `default` | Alternative custom UI slot. |
+
+## v-model
+
+Yes — `modelValue` + `update:modelValue`. Holds a `File` object (or a URL string for pre-existing
+previews), or `null`.
+
+## Notes
+
+- 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
+  checked against the file's actual MIME type.

package/.ai/ai_ref_AbFormCheck.md

@@ -1,6 +1,6 @@
 # AbFormCheck / AbRadioInput — AI Reference
 
-Checkbox or radio group with card, segmented, and pill visual variants. `AbRadioInput` is an alias export of `AbFormCheck`.
+Checkbox or radio group with card, icon-card, card-flat-check, image-radio, segmented, and pill visual variants. `AbRadioInput` is an alias export of `AbFormCheck`.
 
 ## Usage
 
@@ -17,6 +17,41 @@ Checkbox or radio group with card, segmented, and pill visual variants. `AbRadio
   />
 
   <ab-form-check v-model="plan" type="radio" name="plan" variant="card" :options="plans" />
+
+  <!-- Custom check icon (card-family variants only) -->
+  <ab-form-check v-model="plan" type="radio" name="plan2" variant="card" :options="plans" :check-icon-component="Check" />
+
+  <!-- Flat, shadow-free card with the indicator on the right (card-family variants only) -->
+  <ab-form-check v-model="plan" type="radio" name="plan3" variant="card" :options="plans" flat-check check-right />
+
+  <!-- icon-card: icon centered on top by default (no containerClass needed) -->
+  <ab-form-check v-model="plan" type="radio" name="plan4" variant="icon-card" :options="plans" />
+
+  <!-- card-flat-check: flatCheck styling on by default -->
+  <ab-form-check v-model="plan" type="radio" name="plan5" variant="card-flat-check" :options="plans" />
+
+  <!-- isInline false on a card-family variant: full-width stacked column with a gap between cards -->
+  <ab-form-check v-model="plan" type="radio" name="plan6" variant="card" :options="plans" :is-inline="false" />
+
+  <!-- image-radio: big image tile, native input hidden, check badge overlays a corner -->
+  <ab-form-check
+    v-model="theme"
+    type="radio"
+    name="theme"
+    variant="image-radio"
+    card-width="140px"
+    selector-position="top-right"
+    :options="[
+      { val: 'light', title: 'Light', img_src: '/light.png' },
+      { val: 'dark', title: 'Dark', img_src: '/dark.png' },
+    ]"
+  />
+
+  <!-- image-radio chip mode: isInline=true swaps the big tile for a compact icon+text chip -->
+  <ab-form-check v-model="theme" type="radio" name="theme2" variant="image-radio" :options="themes" is-inline />
+
+  <!-- isBoxShadow: checked state as a colored box-shadow glow instead of a border-color change -->
+  <ab-form-check v-model="plan" type="radio" name="plan7" variant="card" :options="plans" is-box-shadow />
 </template>
 ```
 
@@ -29,16 +64,26 @@ Checkbox or radio group with card, segmented, and pill visual variants. `AbRadio
 | `rules` | `String` | `""` | VeeValidate rules. |
 | `val` | `any` | `null` | Initial value. |
 | `type` | `String` | `"checkbox"` | `"checkbox"` or `"radio"`. |
-| `isInline` | `Boolean` | `false` | Render options inline. |
-| `options` | `Array` | `[]` | Each: `{ val, title, description?, icon?, img_src?, iconComponent?, disable? }`. |
+| `isInline` | `Boolean` | `false` | Render options inline. On `variant="image-radio"` this means something different: options always flow in a wrapping tile grid regardless of this prop; `isInline` instead toggles a compact icon+text chip look (`true`, check badge leads on the left like a normal radio/checkbox and only takes up space once checked) vs. the default big image tile (`false`, check badge overlays the image corner). |
+| `options` | `Array` | `[]` | Each: `{ val, title, description?, icon?, img_src?, iconComponent?, disable?, class? }`. `description` is always rendered via `v-html` — only pass trusted/sanitized HTML. |
 | `name` | `String` | **required** | Field name. |
 | `limit` | `Number` | `0` | Max selections (0 = unlimited). |
-| `containerClass` | `String` | `"mb-3"` | Wrapper class. |
+| `containerClass` | `String` | `"mb-3"` | Wrapper class. `variant="card"`/`"icon-card"`/`"card-flat-check"`/`"image-radio"` layout keywords: `left-top`, `middle-top` (icon position). `icon-card` and `image-radio` default to `middle-top` if neither keyword is passed. |
 | `size` | `String` | `"md"` | Control size. |
 | `iconSize` | `String` | `"24px"` | Icon size (when option has an icon). |
 | `iconGap` | `String` | `"10px"` | Gap between icon and label. |
-| `variant` | `String` | `"default"` | `default`, `card`, `segmented`, `pill`. |
-| `cardWidth` | `String` | `"auto"` | Width of card options (e.g. `"160px"`, `"50%"`, `"12rem"`). |
+| `variant` | `String` | `"default"` | `default`, `card`, `icon-card` (card with the icon centered on top by default), `card-flat-check` (card with `flatCheck` styling on by default), `image-radio` (image-first card; native input hidden, check badge overlays the image's top-left corner), `segmented`, `pill`. |
+| `cardWidth` | `String` | `"auto"` | Width of the card itself for card-family variants (e.g. `"160px"`, `"50%"`, `"12rem"`). Applies in both inline and stacked (`isInline` set to `false`) layouts. |
+| `checkIcon` | `String` | `undefined` | CSS icon class rendered inside the checked input, replacing the native checkmark/dot. Card-family variants only. |
+| `checkIconComponent` | `Component` | `undefined` | A Vue component (e.g. a Lucide icon) rendered inside the checked input, replacing the native checkmark/dot. Card-family variants only. On `variant="image-radio"`, a built-in circle-check icon is used automatically when neither this nor `checkIcon` is set. |
+| `flatCheck` | `Boolean` | `false` | Shadow-free checked style for card-family variants: border-color change + accent-colored title instead of box-shadow, indicator vertically centered. Always on for `variant="card-flat-check"`. |
+| `checkRight` | `Boolean` | `false` | Moves the checkbox/radio indicator to the right side of the card (card-family variants only). Typically combined with `flatCheck`. |
+| `selectorPosition` | `String` | `"top-left"` | Corner the check badge overlays on the image: `"top-left"`, `"top-right"`, `"bottom-left"`, `"bottom-right"`. `variant="image-radio"` only. |
+| `isBoxShadow` | `Boolean` | `false` | Card-family variants only (`card`, `icon-card`, `card-flat-check`, `image-radio`). Shows checked state as a colored box-shadow glow instead of a border-color change — the border stays transparent throughout, matching the classic `AbImageRadioInput` look. |
+
+Card-family variants `card`, `icon-card`, `card-flat-check` with `isInline` set to `false` (the default) stack in a full-width column with a gap between cards, instead of the content-sized cards used when `isInline` set to `true`.
+
+`variant="image-radio"` behaves differently from the rest of the card family: options always flow in a wrapping tile grid (never full-width stacked), the native checkbox/radio dot is always hidden, and `isInline` instead switches between two looks — `false` (default): a big image fills the tile with the title below and a check badge overlaying the corner set by `selectorPosition`; `true`: a compact icon+text chip where the check badge leads on the left (like a normal radio/checkbox) instead of overlaying a corner, and only takes up space once an option is checked.
 
 ## Events
 
@@ -48,12 +93,26 @@ Checkbox or radio group with card, segmented, and pill visual variants. `AbRadio
 
 ## Slots
 
+Per-option slots are **not** dynamically named per option (no `-{title}`/`-{val}` suffix) — each is a single
+scoped slot rendered once per option, scoped with `{ check, index }` (`check` is the current `options[index]`
+item). If different options need different content, branch inside the template on `check.val`/`index`:
+
+```vue
+<ab-form-check variant="card" :options="plans" v-model="plan" type="radio" name="plan">
+  <template #option-label="{ check }">
+    <template v-if="check.val === 'pro'">
+      <ab-badge variant="danger">Popular</ab-badge> {{ check.title }}
+    </template>
+    <template v-else>{{ check.title }}</template>
+  </template>
+</ab-form-check>
+```
+
 | Name | Description |
 | --- | --- |
-| `label` | Group label. |
-| `description` | Group description. |
+| `label` | Group label (the whole component's `label` prop/heading — not per-option). |
+| `description` | Per-option description, scoped `{ check, index }`. Overrides the option's `description` key (the default content renders it via `v-html`). |
 | `help-text` | Helper text. |
-| `input-img-{option.title}` | Per-option image slot. |
-| `input-icon-{option.title}` | Per-option icon component slot. |
-| `label-{option.title}` | Per-option label slot. |
-| `description-{option.title}` | Per-option description slot. |
+| `input-icon` | Per-option image/icon area, scoped `{ check, index }` (card-family/segmented/pill variants). Overrides `img_src`/`icon`/`iconComponent`. |
+| `option-label` | Per-option title, scoped `{ check, index }` (card-family/segmented/pill variants). Overrides the option's `title`. Deliberately not named `label` — that name is already the group-level heading slot above. |
+| `check-icon` | Per-option checked-state icon, scoped `{ check, index }` (card-family variants only). Default content falls back to `checkIcon`/`checkIconComponent`; overrides both when provided. |

package/.ai/ai_ref_AbInputField.md

@@ -43,6 +43,8 @@ const form = reactive({ email: '' });
 | `maxlength` | `any` | `null` | Native `maxlength`. |
 | `isLeftIconBorder` | `Boolean` | `false` | Renders border between the prefix icon and the input. |
 | `isRightIconBorder` | `Boolean` | `false` | Renders border between the postfix icon and the input. |
+
+> Set both `isLeftIconBorder` and `isRightIconBorder` to `true` to show a border on both sides at once — the whole input group (icons + field) is treated as one unified box on focus.
 | `passIconPosition` | `String` | `"right"` | Position of the show password icon (`"left"`, `"right"`). |
 | `isHideLabel` | `Boolean` | `false` | Hide the label visually. |
 | `iconPosition` | `String` | `undefined` | Position of the custom `#icon` slot (`"left"`, `"right"`). |