@appsbd/vue3-appsbd-ui 1.0.14 → 1.0.16

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

@@ -14,21 +14,17 @@ No extra peer deps beyond the library's own (`@lucide/vue` for the default "+" i
 
 ## 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 #right>
-      <button type="button" class="btn btn-primary btn-sm rounded-circle">
-        <ArrowUp :size="16" />
-      </button>
-    </template>
-  </AbChatInput>
+  <AbChatInput v-model="message" placeholder="Ask anything" @submit="onSubmit" />
 </template>
 
 <script setup>
 import { ref } from 'vue';
 import { AbChatInput } from 'vue3-appsbd-ui';
-import { ArrowUp } from '@lucide/vue';
 
 const message = ref('');
 function onSubmit({ message, files }) {
@@ -37,6 +33,21 @@ function onSubmit({ 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
@@ -76,24 +87,88 @@ a native file picker and routes the selection through `addFiles`) among other me
 ## 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 (next to the `right` slot) 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:
+button renders in the `right` area (before the `right` slot and the send button) whenever `showVoiceButton` is
+`true` (default).
+
+The composer layout never changes while recording, on every platform — no full-width recording bar swap: the
+textarea stays visible **and stays fully editable** (typing/deleting mid-recording works normally) and fills with
+the transcribed text live as it's recognized. The mic button shows a Google Assistant-style listening cue: its
+circle fills with the theme's primary color (icon turns white to read against it), with a few rings pulsing
+outward from behind it on a loop (`.apbd-chat-input__voice-ring`, staggered so they overlap continuously). Clicking
+it (or calling `stopRecording()`) stops and keeps the text — there's no dedicated cancel button in this UI
+(`cancelRecording()` is still available programmatically via a template ref), and the default send button (or
+`submit()`/Enter generally) stops recording first when called mid-listening, then fires `submit` immediately.
 
-- **✕ 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.
+On every platform, the textarea is refocused automatically the moment listening ends (stop, cancel, or a
+voice-triggered submit) — the cursor lands right back in it so the user can keep typing without an extra tap.
 
-Recognized speech is appended to the existing `modelValue` (not replaced), one final phrase at a time — interim
-(still-speaking) text is not shown live.
+Recognized speech is appended to the existing `modelValue` (not replaced), converting instantly as the user speaks
+on every platform — interim results drive `modelValue` live so the text is already there before the user taps the
+mic to stop, not just once they do (see below).
 
 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/Safari — the mic button still renders there but is `disabled`, with a tooltip explaining
-why. Requires the browser's mic permission prompt to be accepted.
+### Voice punctuation
+
+Two independent behaviors, each its own boolean prop, **both default `true`**:
+
+- **`voicePunctuationCommands`** — saying a punctuation word inserts the actual mark, same idea as Google/Apple
+  dictation: English `"period"`/`"full stop"` → `.`, `"comma"` → `,`, `"question mark"` → `?`; Bengali
+  `"পূর্ণচ্ছেদ"` → `।`, `"কমা"` → `,`, `"প্রশ্নবোধক"` → `?`. Matched against the recognized transcript text itself
+  (not `voiceLang`), so it works regardless of which recognition language is selected. Matching uses
+  script-agnostic lookaround (not `\b`, which only understands ASCII letters — a no-op for Bengali) so a command
+  word only triggers standalone, never as a substring of a longer word (e.g. saying "দাঁড়িপাল্লা" doesn't trigger
+  on the "দাড়ি" inside it). `"দাড়ি"` itself (an earlier alternate trigger, same meaning as `"পূর্ণচ্ছেদ"`) was
+  dropped entirely rather than just boundary-guarded — it's also ordinary vocabulary (beard), so a sentence
+  actually about a beard would still lose that word every time. `"কমা"` keeps a similar, smaller risk (it's also
+  a common verb, "to decrease") — left as-is, since removing every word with *any* plausible double meaning
+  would leave nothing left to trigger on.
+- **`voiceAutoPunctuate`** — when a new utterance is about to be appended onto existing text, a sentence-ending
+  mark is inserted first if the existing text doesn't already end with one — `.` normally, `।` when `voiceLang`
+  starts with `bn`. Applies between pauses (each per-utterance restart, see below), not mid-utterance.
+
+Set either to `false` to disable it independently; both keep working with the default Web Speech transcript as-is
+when off.
+
+Both also auto-capitalize the sentence start they create: `voiceAutoPunctuate` capitalizes the first letter of a
+new utterance right after it inserts a boundary mark (and always capitalizes the very first letter of the whole
+message, regardless of this prop); `voicePunctuationCommands` capitalizes the letter right after any mark it
+inserts mid-utterance (`"hello period how are you"` → `"Hello. How are you"`). Same script-agnostic approach as the
+punctuation matching above — plain `toUpperCase()` on the matched letter, which is a no-op for scripts without a
+case concept (Bengali, Arabic, CJK, …), so it needs no per-language list.
+
+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.
+
+Some browsers/builds hold back `isFinal` results until `.stop()` is called instead of firing them per pause segment
+— waiting for that would mean the transcript only shows up once the user taps stop, not while they're actually
+speaking (and on some builds it never reliably fires at all). `interimResults` is on by default to sidestep that,
+converting speech to text instantly instead of only once recording stops — **except on Safari** (desktop and iOS
+both), where it's kept `false`: Safari's engine has a bug where enabling it can fail to (re)start the recognizer
+entirely, surfacing as a generic "Microphone permission denied" error indistinguishable from an actually-denied
+permission. Safari still converts per finished phrase (not mid-utterance), just not keystroke-by-keystroke live.
+
+`continuous`+`interimResults` together is also unreliable across browsers/builds in a way delta-tracking
+`e.results` (via `resultIndex` or position) can't fully work around — it's been observed restating/duplicating
+earlier words in a later result with no restart involved at all. So `recognition.continuous` is always `false` —
+each internal session covers exactly one utterance, and a transparent onend-restart (also covers Safari's own
+quirk of ending a `continuous: true` session early) picks the next utterance back up automatically, so it still
+reads as continuous listening. Within one utterance's `onresult`, only the latest `e.results` entry is read — no
+cross-event bookkeeping needed, since there's nothing earlier in that same array to conflict with.
+
+Because the textarea stays editable during recording, `onresult` can't just privately accumulate a running
+transcript either — that would silently clobber whatever the user just typed or deleted. Instead it reads the
+current `modelValue`, strips back off the exact suffix it itself inserted last time (if that suffix is still there
+untouched), and rebuilds from that stable base with the freshly recognized text appended; if the suffix isn't
+there anymore, whatever's currently in the field — including the user's edit — becomes the new base instead of
+being overwritten.
 
 ## Props
 
@@ -119,6 +194,8 @@ why. Requires the browser's mic permission prompt to be accepted.
 | `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. |
+| `voicePunctuationCommands` | `Boolean` | `true` | Say a punctuation word (e.g. "period", "পূর্ণচ্ছেদ") to insert the actual mark — see "Voice punctuation" above. |
+| `voiceAutoPunctuate` | `Boolean` | `true` | Auto-insert a sentence-ending mark between voice utterances when one isn't already there — see "Voice punctuation" above. |
 
 ## Events
 
@@ -133,8 +210,8 @@ why. Requires the browser's mic permission prompt to be accepted.
 | `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-stop` | — | Recording stopped normally (mic button tapped again, `stopRecording()`, or the browser ending it on its own) — transcribed text is kept in `modelValue`. |
+| `voice-cancel` | — | Recording was cancelled via `cancelRecording()` (no dedicated UI button — call it programmatically via a template ref) — `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
@@ -142,12 +219,13 @@ why. Requires the browser's mic permission prompt to be accepted.
 | Name | Description |
 | --- | --- |
 | `left` | Left action area (e.g. an attachment button). Scoped — see below. |
-| `right` | Right action area (e.g. send/mic 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 five slots are scoped**, receiving the same props so slot content can drive the composer directly:
+**All six slots are scoped**, receiving the same props so slot content can drive the composer directly:
 
 | Scoped prop | Description |
 | --- | --- |
@@ -157,6 +235,7 @@ why. Requires the browser's mic permission prompt to be accepted.
 | `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.
@@ -202,6 +281,7 @@ any slot — e.g. a toolbar button elsewhere on the page.
 | `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). |

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

@@ -36,3 +36,30 @@ Each event payload is an object with `scrollTop`, `scrollHeight`, `scrollRatio`,
 | Name | Description |
 | --- | --- |
 | `default` | Scrollable content. |
+
+## Exposed methods
+
+Available via a template ref, for programmatic scroll control (e.g. scrolling a chat/message list to the bottom on new content):
+
+| Method | Description |
+| --- | --- |
+| `scrollToBottom(behavior?)` | Scrolls to the bottom. `behavior`: `"auto"` (default) or `"smooth"`. |
+| `scrollToTop(behavior?)` | Scrolls to the top. `behavior`: `"auto"` (default) or `"smooth"`. |
+| `scrollTo(options)` | Same as the native `Element.scrollTo(options)` (e.g. `{ top, left, behavior }`). |
+| `scrollArea` | Raw ref to the internal scrollable element, for anything not covered above. |
+
+```vue
+<template>
+  <AbScrollbar ref="listRef" style="height: 300px">
+    <div v-for="m in messages" :key="m.id">{{ m.text }}</div>
+  </AbScrollbar>
+</template>
+
+<script setup>
+import { ref, nextTick } from 'vue';
+const listRef = ref(null);
+function onNewMessage() {
+  nextTick(() => listRef.value.scrollToBottom());
+}
+</script>
+```

package/.ai/ai_ref_AbVoiceButton.md

@@ -0,0 +1,112 @@
+# AbVoiceButton — AI Reference
+
+A standalone voice-to-text mic button — the same recognition engine and behavior as `AbChatInput`'s built-in mic,
+with no composer attached. Use it to bolt voice input onto any existing input, form field, search box, or custom
+UI via `v-model`; pick `AbChatInput` instead when you need the whole chat composer (textarea, file attachments,
+add/more dropdown) with voice input built in.
+
+## Installation
+
+Not globally registered — import it explicitly:
+
+```js
+import { AbVoiceButton } from 'vue3-appsbd-ui';
+```
+
+No extra peer deps beyond the library's own (`@lucide/vue` for the mic icon). Uses the browser's native Web
+Speech API (`SpeechRecognition`) — no dependency, no API key.
+
+## Usage
+
+```vue
+<template>
+  <AbVoiceButton v-model="message" />
+  <p>{{ message }}</p>
+</template>
+
+<script setup>
+import { ref } from 'vue';
+import { AbVoiceButton } from 'vue3-appsbd-ui';
+
+const message = ref('');
+</script>
+```
+
+Pin the recognition language explicitly (there's no built-in language picker here, unlike `AbChatInput`'s mic
+button — pass whichever locale your app already knows the user wants):
+
+```vue
+<AbVoiceButton v-model="message" lang="bn-BD" />
+```
+
+## Behavior
+
+Tapping the button (or calling `startRecording()`) starts listening; the mic icon stays the mic icon, but its
+circle fills with the theme's primary color (`--#{prefix}theme`) and the icon turns white, with a few rings
+pulsing outward from behind it on a loop — a Google Assistant-style listening cue, on every platform (same cue,
+same architecture as `AbChatInput`'s built-in mic — this component just has no composer/textarea attached to it).
+Tap it again (or call `stopRecording()`) to stop and keep the text.
+
+Recognized speech merges into `modelValue` live as the user speaks, via one internal recognition session per
+utterance (`continuous: false` + `interimResults: true`, restarted transparently between utterances) — on every
+platform except Safari (desktop and iOS both), where `interimResults` is kept `false`: Safari's engine has a bug
+where enabling it can fail to (re)start the recognizer entirely, surfacing as a generic "Microphone permission
+denied" error indistinguishable from an actually-denied permission. Safari still converts per finished phrase, just
+not keystroke-by-keystroke live. Reads the current `modelValue` on each update and replaces only the exact suffix
+it last inserted itself, so external edits to `modelValue` between voice updates (e.g. the consumer's own code, or
+a bound `<textarea>` the user is also typing into) are preserved rather than clobbered.
+
+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, so these are detected via user-agent and treated as unsupported too
+(button `disabled`, tooltip explains why). Requires the browser's mic permission prompt to be accepted where
+supported.
+
+### Voice punctuation
+
+Two independent behaviors, each its own boolean prop, **both default `true`** (identical to `AbChatInput`'s):
+
+- **`voicePunctuationCommands`** — saying a punctuation word inserts the actual mark: English `"period"`/
+  `"full stop"` → `.`, `"comma"` → `,`, `"question mark"` → `?`; Bengali `"পূর্ণচ্ছেদ"` → `।`, `"কমা"` → `,`,
+  `"প্রশ্নবোধক"` → `?`. Matched against the transcript text itself, independent of `lang`. Matching uses
+  script-agnostic Unicode lookaround (not `\b`, a no-op for Bengali script), so a command word only triggers
+  standalone, never as a substring of a longer word.
+- **`voiceAutoPunctuate`** — a sentence-ending mark is inserted between voice utterances when the existing text
+  doesn't already end with one — `.` normally, `।` when `lang` (or the auto-detected language) starts with `bn`.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `modelValue` | `String` | `""` | Two-way-bound transcribed text. |
+| `disabled` | `Boolean` | `false` | Disables the button. |
+| `size` | `Number` | `40` | Button diameter in px. Icon and listening rings scale with it. |
+| `lang` | `String` | `""` | BCP-47 recognition locale (e.g. `"bn-BD"`). Empty = auto-detect from `document.documentElement.lang` / `navigator.language`. |
+| `voicePunctuationCommands` | `Boolean` | `true` | Say a punctuation word (e.g. "period", "পূর্ণচ্ছেদ") to insert the actual mark — see "Voice punctuation" above. |
+| `voiceAutoPunctuate` | `Boolean` | `true` | Auto-insert a sentence-ending mark between voice utterances when one isn't already there — see "Voice punctuation" above. |
+
+## Events
+
+| Event | Payload | Description |
+| --- | --- | --- |
+| `update:modelValue` | `string` | v-model sync. |
+| `voice-start` | — | Voice recording started (mic tapped, or `startRecording()` called). |
+| `voice-stop` | — | Recording stopped normally (mic tapped again, `stopRecording()`, or the browser ending it on its own) — transcribed text is kept in `modelValue`. |
+| `voice-cancel` | — | Recording was cancelled via `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
+
+None.
+
+## v-model
+
+Yes — `modelValue` + `update:modelValue` (string).
+
+## Exposed methods
+
+| Method | Description |
+| --- | --- |
+| `startRecording()` | Starts voice input (same as tapping the button). No-op if unsupported/disabled/already recording. |
+| `stopRecording()` | Stops recording, keeping the transcribed text (same as tapping the button again). |
+| `cancelRecording()` | Stops recording and reverts `modelValue` to what it was before recording started. No dedicated UI for this — call it via a template ref. |

package/.ai/ai_ref_global_config.md

@@ -7,13 +7,11 @@ Call `AppsbdUIConfigure` once during app initialization to set library-wide loca
 ```javascript
 import { AppsbdUIConfigure } from "@vue3-appsbd-ui";
 
-const banglaDigits = ["০", "১", "২", "৩", "৪", "৫", "৬", "৭", "৮", "৯"];
-
 AppsbdUIConfigure({
   monthNames: ["জানুয়ারি", "ফেব্রুয়ারি", "মার্চ", "এপ্রিল", "মে", "জুন", "জুলাই", "আগস্ট", "সেপ্টেম্বর", "অক্টোবর", "নভেম্বর", "ডিসেম্বর"],
   monthNamesShort: ["জানু", "ফেব্রু", "মার্চ", "এপ্রি", "মে", "জুন", "জুলাই", "আগস্ট", "সেপ্টে", "অক্টো", "নভে", "ডিসে"],
   dayNames: ["শনি", "রবি", "সোম", "মঙ্গল", "বুধ", "বৃহঃ", "শুক্র"],
-  formatDigit: (val) => String(val).replace(/\d/g, (d) => banglaDigits[d]),
+  digits: ["০", "১", "২", "৩", "৪", "৫", "৬", "৭", "৮", "৯"],
   is24Hour: false,
   rangeSeparator: " থেকে ",
   dateDataFormat: "YYYY-MM-DD",
@@ -32,7 +30,7 @@ AppsbdUIConfigure({
 | `monthNames` | `String[]` | English full names | Array of 12 full month names. |
 | `monthNamesShort` | `String[]` | English short names | Array of 12 short month names. |
 | `dayNames` | `String[]` | English 3-letter names | Array of 7 short day names (Sat-first). |
-| `formatDigit` | `Function` | `(val) => String(val)` | Digit formatter applied to `AbNumberField` (display-only) and `AbDateTimePicker`. |
+| `digits` | `String[]` | `undefined` | Array of 10 digit characters (0-9) for locale digit transliteration (e.g. Bangla digits), applied by `AbDateTimePicker` and `formatCurrency`/`formatAmount`. |
 | `rangeSeparator` | `String` | `' ↔ '` | Separator for date ranges in `AbDateTimePicker`. |
 | `is24Hour` | `Boolean` | `false` | Whether to use 24-hour format in `AbDateTimePicker`. |
 | `dateDataFormat` | `String` | `'YYYY-MM-DD'` | Global format for date data. |
@@ -56,3 +54,40 @@ AppsbdUIConfigure({
 | `button.iconPosition` | `String` | `'left'` | Global default icon position for buttons (`left`, `right`). |
 | `isModalBorder` | `Boolean` | `true` | Global default modal border. |
 | `modalLoader` | `String` | `'AbLoader'` | Global default modal loader component. |
+| `currency` | `String` | `'$'` | Global default currency symbol, used by `formatCurrency`/`formatAmount`. |
+| `currencyPosition` | `String` | `'left'` | Global default currency symbol position: `'left'`, `'right'`, `'left_space'`, `'right_space'`. |
+| `thousandSeparator` | `String` | `','` | Global default thousand separator, used by `formatCurrency`/`formatAmount`. |
+| `decimalSeparator` | `String` | `'.'` | Global default decimal separator, used by `formatCurrency`/`formatAmount`. |
+| `numberOfDecimals` | `Number` | `2` | Global default number of decimal digits, used by `formatCurrency`/`formatAmount`. |
+| `round` | `Boolean` | `false` | Global default: round to `numberOfDecimals` instead of truncating, used by `formatCurrency`/`formatAmount`. |
+
+## `formatCurrency` / `formatAmount` utils
+
+```javascript
+import { formatCurrency, formatAmount } from "@vue3-appsbd-ui";
+
+formatCurrency(1234.5);
+// -> "$1,234.50" (uses globalConfig.currency/currencyPosition/thousandSeparator/decimalSeparator/numberOfDecimals)
+
+formatCurrency(1234.5, { currency: "৳", currencyPosition: "right_space", numberOfDecimals: 0 });
+// -> "1,234 ৳"
+
+formatAmount(1234.5); // plain number, no currency symbol -> "1,234.50"
+
+// round (default false) — extra decimals are truncated, not rounded up:
+formatCurrency(1234.499);               // -> "$1,234.49" (truncated)
+formatCurrency(1234.499, { round: true }); // -> "$1,234.50" (rounded)
+```
+
+Any option not passed falls back to `globalConfig`, then to the hardcoded default (prop > global config > built-in default, same resolution order as other components). `digits` (see above, or `options.digits` per-call) is also applied to the formatted output via the internal `formatDigits` util. By default `round` is `false`: `numberOfDecimals` truncates extra digits rather than rounding (`1234.499` at 2 decimals -> `1234.49`, never `1234.50`); pass `round: true` (or `globalConfig.round = true`) for standard rounding.
+
+## `formatDigits` util
+
+```javascript
+import { formatDigits } from "@vue3-appsbd-ui";
+
+formatDigits(123); // no globalConfig.digits set -> "123"
+formatDigits(123, ["০", "১", "২", "৩", "৪", "৫", "৬", "৭", "৮", "৯"]); // -> "১২৩"
+```
+
+Used internally by `AbDateTimePicker` (`digits` prop) and `formatCurrency`/`formatAmount` (`options.digits`) to transliterate digits; falls back to `globalConfig.digits` when no array is passed, and returns the value unchanged (stringified) when neither is set.