@appsbd/vue3-appsbd-ui 1.0.3 → 1.0.4

package/.ai/ai_ref_abRequestParam.md

@@ -1,55 +1,40 @@
-# abRequestParam (Library)
-
-Data-transfer classes used to build structured API request parameters for paginated, sorted, and filtered data queries.
-
-## Installation
-
-```javascript
-npm install @vue3-appsbd-ui
-```
-
-## Usage
-
-```javascript
-import abRequestParam from "@vue3-appsbd-ui/libraries/abRequestParam";
-
-const params = new abRequestParam();
-
-// Pagination
-params.limit = 25;
-params.page = 1;
-
-// Sorting
-params.AddSortItem("created_at", "desc");
-
-// Filtering
-params.AddSrcItem("status", "active", "eq");
-params.AddSrcItem("name", "John", "like");
-
-// Output suitable for axios or fetch payload
-console.log(params);
-```
-
-## API Reference
-
-### `abRequestParam` Class
-
-**Properties**
-
-| Property | Type | Description |
-|---|---|---|
-| `data` | `any` | Arbitrary payload attached to the request (e.g. form data). |
-| `limit` | `string\|number` | Number of records per page. |
-| `page` | `string\|number` | Current page number. |
-| `filter_prop` | `string` | Optional filter property identifier. |
-| `sort_by` | `abSortParam[]` | Array of sort descriptors. |
-| `src_by` | `abSrcParam[]` | Array of filter/search descriptors. |
-| `group_by` | `string[]` | Array of property names to group results by. |
-| `force` | `boolean` | Forces the server to bypass cache. |
-
-**Methods**
-
-| Method | Signature | Description |
-|---|---|---|
-| `AddSortItem(prop, ord)` | `Function` | Appends a sort rule. `ord` defaults to `'asc'`, accepts `'asc' \| 'desc'`. |
-| `AddSrcItem(prop, val, opr)` | `Function` | Appends a search rule. `opr` defaults to `'eq'`, accepts `'eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'like', 'in'`. |
+# abRequestParam (Library)
+
+Data-transfer classes for building structured API request parameters for paginated, sorted, and filtered data queries.
+
+## Usage
+
+```javascript
+import abRequestParam from "@vue3-appsbd-ui/libraries/abRequestParam";
+
+const params = new abRequestParam();
+params.limit = 25;
+params.page = 1;
+params.AddSortItem("created_at", "desc");
+params.AddSrcItem("status", "active", "eq");
+params.AddSrcItem("name", "John", "like");
+```
+
+## API Reference
+
+### `abRequestParam` Class
+
+**Properties**
+
+| Property | Type | Description |
+|---|---|---|
+| `data` | `any` | Arbitrary payload attached to the request. |
+| `limit` | `string\|number` | Number of records per page. |
+| `page` | `string\|number` | Current page number. |
+| `filter_prop` | `string` | Optional filter property identifier. |
+| `sort_by` | `abSortParam[]` | Array of sort descriptors. |
+| `src_by` | `abSrcParam[]` | Array of filter/search descriptors. |
+| `group_by` | `string[]` | Array of property names to group results by. |
+| `force` | `boolean` | Forces the server to bypass cache. |
+
+**Methods**
+
+| Method | Signature | Description |
+|---|---|---|
+| `AddSortItem(prop, ord)` | `Function` | Appends a sort rule. `ord` defaults to `'asc'`, accepts `'asc' \| 'desc'`. |
+| `AddSrcItem(prop, val, opr)` | `Function` | Appends a search rule. `opr` defaults to `'eq'`, accepts `'eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'like', 'in'`. |

package/.ai/ai_ref_abTranslate.md

@@ -1,33 +1,48 @@
 # abTranslate (Library)
 
-A localization utility wrapping `vue3-gettext`. Exposes helper methods `translateGettext` and `translateGetMsg` that automatically interpolate parameters and translate strings, falling back safely if gettext isn't initialized.
+Localization utility wrapping `vue3-gettext`. Exposes `translateGettext` (translates + interpolates) and `translateGetMsg` (interpolates only).
 
-## Installation
+## Setup
 
 ```javascript
-npm install @vue3-appsbd-ui
+// Option 1 — recommended: auto-registers the instance
+import { abCreateGettext } from "@appsbd/vue3-appsbd-ui";
+import translations from "./translations.json";
+
+const gettext = abCreateGettext({
+  availableLanguages: { en_US: "English", bn_BD: "Bengali" },
+  defaultLanguage: "en_US",
+  translations,
+});
+app.use(gettext);
+
+// Option 2 — manual registration
+import { createGettext } from "vue3-gettext";
+import { initTranslate } from "@appsbd/vue3-appsbd-ui";
+
+const gettext = createGettext(options);
+initTranslate(gettext);
 ```
 
 ## Usage
 
 ```javascript
-import { translateGettext, translateGetMsg } from "@vue3-appsbd-ui/libraries/abTranslate";
+import { translateGettext, translateGetMsg } from "@appsbd/vue3-appsbd-ui";
 
-// Simple translation
-const greeting = translateGettext("Hello World");
+// Translates the base string AND each param value
+translateGettext("Welcome %{name}", { name: "Admin" });
+// → "স্বাগতম প্রশাসক" (if both strings are translated)
 
-// Translation with interpolation (assuming vue3-gettext translates "Welcome %{name}")
-const welcome = translateGettext("Welcome %{name}", { name: "John" });
-
-// Only interpolates without translating the base string
-const msg = translateGetMsg("Error code: %{code}", { code: "404" });
+// Interpolates only — does NOT translate anything
+translateGetMsg("Error code: %{code}", { code: "404" });
+// → "Error code: 404"
 ```
 
 ## API Reference
 
 | Export | Signature | Description |
-|---|---|---|
-| `initTranslate(gettextInstance)` | `Function` | Registers the global gettext instance to be used outside of Vue components. |
+| --- | --- | --- |
 | `abCreateGettext(options)` | `Function` | Creates a gettext instance and auto-registers it via `initTranslate`. |
-| `translateGettext(msg, params)` | `Function` | Translates a string `msg` and interpolates any variables provided in `params` object. |
-| `translateGetMsg(msg, params)` | `Function` | Interpolates the `params` into `msg` but does not translate the base string. |
+| `initTranslate(gettextInstance)` | `Function` | Registers an existing gettext instance for use outside Vue components. |
+| `translateGettext(msg, params)` | `Function` | Translates `msg` and interpolates `params`; also translates param values. |
+| `translateGetMsg(msg, params)` | `Function` | Interpolates `params` into `msg` without translating. |

package/.ai/ai_ref_abVeeRules.md

@@ -1,42 +1,33 @@
-# abVeeRules (Library)
-
-A collection of pre-configured VeeValidate validation rules integrated with localization via `abTranslate`.
-
-## Installation
-
-```javascript
-npm install @vue3-appsbd-ui
-```
-
-## Usage
-
-These rules are typically used internally by the library's `AbField` or form components, but can be imported and registered globally if needed.
-
-```javascript
-import { abAllRules } from "@vue3-appsbd-ui/libraries/abVeeRules";
-import { defineRule } from "vee-validate";
-
-// Register all custom library rules manually if needed
-Object.keys(abAllRules).forEach(rule => {
-  defineRule(rule, abAllRules[rule]);
-});
-```
-
-## API Reference
-
-### `abAllRules` Object
-
-An object containing validation functions conforming to VeeValidate's custom rule signature `(value, params, field)`. 
-
-Included rules:
-- `required`: Returns translated `%{fld_name} is required`.
-- `numeric`: Returns translated `%{fld_name} should be numeric`.
-- `email`: Returns translated `%{fld_name} not a valid email address`.
-- `min`: Native min validation.
-- `min_value`: Returns translated `%{fld_name} should be more than X`.
-- `max`: Native max validation.
-- `max_value`: Returns translated `%{fld_name} should be less than X`.
-- `confirmed`: Checks password confirmation match.
-- `url`: Validates URL format.
-- `isUnique`: Custom stub for async uniqueness check.
-- `isValid`: Custom stub for async validity check.
+# abVeeRules (Library)
+
+Pre-configured VeeValidate validation rules integrated with localization via `abTranslate`.
+
+## Usage
+
+```javascript
+import { abAllRules } from "@vue3-appsbd-ui/libraries/abVeeRules";
+import { defineRule } from "vee-validate";
+
+Object.keys(abAllRules).forEach(rule => {
+  defineRule(rule, abAllRules[rule]);
+});
+```
+
+## API Reference
+
+### `abAllRules` Object
+
+Validation functions conforming to VeeValidate's custom rule signature `(value, params, field)`.
+
+Included rules:
+- `required`: Returns translated `%{fld_name} is required`.
+- `numeric`: Returns translated `%{fld_name} should be numeric`.
+- `email`: Returns translated `%{fld_name} not a valid email address`.
+- `min`: Native min validation.
+- `min_value`: Returns translated `%{fld_name} should be more than X`.
+- `max`: Native max validation.
+- `max_value`: Returns translated `%{fld_name} should be less than X`.
+- `confirmed`: Checks password confirmation match.
+- `url`: Validates URL format.
+- `isUnique`: Custom stub for async uniqueness check.
+- `isValid`: Custom stub for async validity check.

package/.ai/ai_ref_global_config.md

@@ -1,10 +1,8 @@
 # Global UI Configuration (`AppsbdUIConfigure`)
 
-**Purpose**: Configure library-wide locale and formatting defaults (like month names, digits, range separator) so every instance of a library component renders consistently without needing manual prop wiring.
+Call `AppsbdUIConfigure` once during app initialization to set library-wide locale and formatting defaults. Components follow a strict "prop > global config > built-in default" resolution order.
 
-## Installation / Usage
-
-Call `AppsbdUIConfigure` once during your app initialization (e.g., in `main.js`, or when a locale dynamically changes).
+## Usage
 
 ```javascript
 import { AppsbdUIConfigure } from "@vue3-appsbd-ui";
@@ -12,14 +10,8 @@ import { AppsbdUIConfigure } from "@vue3-appsbd-ui";
 const banglaDigits = ["০", "১", "২", "৩", "৪", "৫", "৬", "৭", "৮", "৯"];
 
 AppsbdUIConfigure({
-  monthNames: [
-    "জানুয়ারি", "ফেব্রুয়ারি", "মার্চ", "এপ্রিল", "মে", "জুন",
-    "জুলাই", "আগস্ট", "সেপ্টেম্বর", "অক্টোবর", "নভেম্বর", "ডিসেম্বর"
-  ],
-  monthNamesShort: [
-    "জানু", "ফেব্রু", "মার্চ", "এপ্রি", "মে", "জুন",
-    "জুলাই", "আগস্ট", "সেপ্টে", "অক্টো", "নভে", "ডিসে"
-  ],
+  monthNames: ["জানুয়ারি", "ফেব্রুয়ারি", "মার্চ", "এপ্রিল", "মে", "জুন", "জুলাই", "আগস্ট", "সেপ্টেম্বর", "অক্টোবর", "নভেম্বর", "ডিসেম্বর"],
+  monthNamesShort: ["জানু", "ফেব্রু", "মার্চ", "এপ্রি", "মে", "জুন", "জুলাই", "আগস্ট", "সেপ্টে", "অক্টো", "নভে", "ডিসে"],
   dayNames: ["শনি", "রবি", "সোম", "মঙ্গল", "বুধ", "বৃহঃ", "শুক্র"],
   formatDigit: (val) => String(val).replace(/\d/g, (d) => banglaDigits[d]),
   is24Hour: false,
@@ -40,7 +32,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)` | Function to format digits. Applied dynamically to `AbNumberField` (display-only) and `AbDateTimePicker`. |
+| `formatDigit` | `Function` | `(val) => String(val)` | Digit formatter applied to `AbNumberField` (display-only) and `AbDateTimePicker`. |
 | `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. |
@@ -60,7 +52,5 @@ AppsbdUIConfigure({
 | `trueValue` | `any` | `'Y'` | Default true value for toggles/switches. |
 | `falseValue` | `any` | `'N'` | Default false value for toggles/switches. |
 | `size` | `String` | `'md'` | Global size for components. |
-
-## Precedence Rule
-
-Components follow a strict "prop > global config > built-in default" resolution order. For example, if you pass `:is-24-hour="true"` directly to an `<AbDateTimePicker>`, it will override the global config setting for that specific instance.
+| `iconPosition` | `String` | `'right'` | Global default icon position (`left`, `right`). |
+| `isModalBorder` | `Boolean` | `true` | Global default modal border. |

package/.ai/ai_ref_useAlert.md

@@ -1,63 +1,45 @@
-# useAlert (Composable)
-
-Provides a procedural API to trigger modal alerts, notifications, and confirmations using the global `$alert` instance.
-
-## Installation
-
-Ensure the library is installed:
-
-```javascript
-npm install @vue3-appsbd-ui
-```
-
-## Usage
-
-Import the composable in your `<script setup>` and call it. The `alert` function returns a Promise that resolves when the user dismisses or confirms the dialog.
-
-```html
-<script setup>
-import { useAlert } from "@vue3-appsbd-ui";
-
-const { alert } = useAlert();
-
-async function handleAction() {
-  const result = await alert({
-    type: "confirm",
-    title: "Delete item?",
-    message: "Are you sure you want to delete this?",
-    icon: "warning",
-    confirmText: "Yes, delete",
-    cancelText: "Cancel"
-  });
-  
-  if (result) {
-    // User confirmed
-  }
-}
-</script>
-
-<template>
-  <button @click="handleAction">Delete</button>
-</template>
-```
-
-## API Reference
-
-### `alert(options)`
-
-The `alert` method accepts an options object to configure the dialog.
-
-**Options**
-
-| Property | Type | Default | Description |
-|---|---|---|---|
-| `type` | `string` | `"alert"` | Variant: `"alert"`, `"confirm"`, or `"confirm-ajax"`. |
-| `title` | `string` | - | Headline text for the dialog. |
-| `message` | `string` | - | Detailed body text. |
-| `icon` | `string` | - | Status icon: `"success"`, `"error"`, `"warning"`, `"info"`, `"question"`. |
-| `variation` | `string` | `"default"` | Visual style: `"default"`, `"modern"`, `"minimal"`, `"top-color-bar"`. |
-| `size` | `string` | `"md"` | Width limit: `"sm"`, `"md"`, `"lg"`, `"xl"`, `"auto"`. |
-| `confirmText`| `string` | `"OK"` | Label for the primary accept button. |
-| `cancelText` | `string` | `"Cancel"` | Label for the cancel/decline button. |
-| `onConfirm` | `Function` | - | Async callback executed when accepting a `"confirm-ajax"` modal. |
-| `timer` | `number` | - | Auto-close timer in milliseconds (only for `"alert"` type). |
+# useAlert (Composable)
+
+Provides a procedural API to trigger modal alerts, notifications, and confirmations using the global `$alert` instance.
+
+## Usage
+
+```html
+<script setup>
+import { useAlert } from "@vue3-appsbd-ui";
+
+const { alert } = useAlert();
+
+async function handleAction() {
+  const result = await alert({
+    type: "confirm",
+    title: "Delete item?",
+    message: "Are you sure you want to delete this?",
+    icon: "warning",
+    confirmText: "Yes, delete",
+    cancelText: "Cancel"
+  });
+
+  if (result) {
+    // User confirmed
+  }
+}
+</script>
+```
+
+## API Reference
+
+### `alert(options)`
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `type` | `string` | `"alert"` | Variant: `"alert"`, `"confirm"`, or `"confirm-ajax"`. |
+| `title` | `string` | - | Headline text for the dialog. |
+| `message` | `string` | - | Detailed body text. |
+| `icon` | `string` | - | Status icon: `"success"`, `"error"`, `"warning"`, `"info"`, `"question"`. |
+| `variation` | `string` | `"default"` | Visual style: `"default"`, `"modern"`, `"minimal"`, `"top-color-bar"`. |
+| `size` | `string` | `"md"` | Width limit: `"sm"`, `"md"`, `"lg"`, `"xl"`, `"auto"`. |
+| `confirmText` | `string` | `"OK"` | Label for the primary accept button. |
+| `cancelText` | `string` | `"Cancel"` | Label for the cancel/decline button. |
+| `onConfirm` | `Function` | - | Async callback executed when accepting a `"confirm-ajax"` modal. |
+| `timer` | `number` | - | Auto-close timer in milliseconds (only for `"alert"` type). |

package/.ai/ai_ref_useFileValidator.md

@@ -1,46 +1,31 @@
-# useFileValidator (Composable)
-
-Provides file validation utilities to check file extensions, MIME types, and file sizes. Automatically spawns error toasts if validation fails, and returns a structured file object with icon metadata for UI display.
-
-## Installation
-
-```javascript
-npm install @vue3-appsbd-ui
-```
-
-## Usage
-
-```html
-<script setup>
-import { useFileValidator } from "@vue3-appsbd-ui";
-
-const { getFileInfo, getFileIconByExt } = useFileValidator();
-
-function handleFileUpload(event) {
-  const file = event.target.files[0];
-  if (!file) return;
-
-  // Validates if file is <= 2.0 MB and is a supported type
-  const validatedFile = getFileInfo(file, 2.0);
-  
-  if (validatedFile) {
-    console.log("File is valid!", validatedFile);
-    // validatedFile.isImage
-    // validatedFile.fileIcon
-  }
-}
-</script>
-
-<template>
-  <input type="file" @change="handleFileUpload" />
-</template>
-```
-
-## API Reference
-
-### Returned Methods
-
-| Method | Signature | Description |
-|---|---|---|
-| `getFileInfo(file, sizeLimitMb)` | `Function` | Validates a `File` object against allowed MIME types and max size (`sizeLimitMb`, default `1.0`). If invalid, spawns a toast error and returns `null`. If valid, returns the `file` object augmented with `isImage` and `fileIcon` properties. |
-| `getFileIconByExt(ext, type)` | `Function` | Returns an object `{ isImage: boolean, fileIcon: Component\|String }` based on the file extension and MIME type. Uses `lucide-vue-next` icons for known formats (pdf, zip, doc, xls, ppt, mp4). |
+# useFileValidator (Composable)
+
+Provides file validation utilities to check extensions, MIME types, and file sizes. Automatically spawns error toasts on validation failure and returns a structured file object with icon metadata.
+
+## Usage
+
+```html
+<script setup>
+import { useFileValidator } from "@vue3-appsbd-ui";
+
+const { getFileInfo, getFileIconByExt } = useFileValidator();
+
+function handleFileUpload(event) {
+  const file = event.target.files[0];
+  if (!file) return;
+
+  const validatedFile = getFileInfo(file, 2.0);
+  if (validatedFile) {
+    // validatedFile.isImage
+    // validatedFile.fileIcon
+  }
+}
+</script>
+```
+
+## API Reference
+
+| Method | Signature | Description |
+|---|---|---|
+| `getFileInfo(file, sizeLimitMb)` | `Function` | Validates a `File` object against allowed MIME types and max size (`sizeLimitMb`, default `1.0`). If invalid, spawns a toast error and returns `null`. If valid, returns the `file` augmented with `isImage` and `fileIcon` properties. |
+| `getFileIconByExt(ext, type)` | `Function` | Returns `{ isImage: boolean, fileIcon: Component\|String }` based on file extension and MIME type. Uses `lucide-vue-next` icons for known formats (pdf, zip, doc, xls, ppt, mp4). |

package/.ai/ai_ref_useResponsive.md

@@ -1,55 +1,41 @@
-# useResponsive (Composable)
-
-A Vue 3 composable that tracks the browser viewport width in real-time and exposes reactive helpers for responsive layout decisions. Aligned with Bootstrap 5 breakpoints.
-
-## Installation
-
-```javascript
-npm install @vue3-appsbd-ui
-```
-
-## Usage
-
-```html
-<script setup>
-import { useResponsive } from "@vue3-appsbd-ui";
-
-// Track screen size dynamically
-const { ScreenWidth, ScreenType, isUptoTab } = useResponsive();
-
-// Or provide a custom tablet max-width threshold in pixels
-// const { isUptoTab } = useResponsive({ tabMaxWidth: 900 });
-</script>
-
-<template>
-  <div>
-    <p>Current Width: {{ ScreenWidth }}px</p>
-    <p>Breakpoint: {{ ScreenType }}</p>
-    
-    <div v-if="isUptoTab">
-      Showing Mobile / Tablet Layout
-    </div>
-    <div v-else>
-      Showing Desktop Layout
-    </div>
-  </div>
-</template>
-```
-
-## API Reference
-
-### `useResponsive(options)`
-
-**Options**
-
-| Property | Type | Default | Description |
-|---|---|---|---|
-| `tabMaxWidth` | `number` | `0` | Custom max-width (px) to treat as "up-to tab". When `> 0`, screens at or below this width are considered tablet-sized regardless of breakpoint. |
-
-**Returned Properties**
-
-| Property | Type | Description |
-|---|---|---|
-| `ScreenWidth` | `ComputedRef<number>` | Raw viewport width in pixels. |
-| `ScreenType` | `ComputedRef<string>` | Current Bootstrap-style breakpoint (`'xs'`, `'sm'`, `'md'`, `'lg'`, `'xl'`, `'xxl'`). |
-| `isUptoTab` | `ComputedRef<boolean>` | `true` when the viewport is tablet-sized or smaller (`xs`, `sm`, or `<=` `tabMaxWidth`). |
+# useResponsive (Composable)
+
+Tracks browser viewport width in real-time with reactive helpers for responsive layout decisions, aligned with Bootstrap 5 breakpoints.
+
+## Usage
+
+```html
+<script setup>
+import { useResponsive } from "@vue3-appsbd-ui";
+
+const { ScreenWidth, ScreenType, isUptoTab } = useResponsive();
+// Or with custom tablet threshold:
+// const { isUptoTab } = useResponsive({ tabMaxWidth: 900 });
+</script>
+
+<template>
+  <div>
+    <p>Current Width: {{ ScreenWidth }}px — Breakpoint: {{ ScreenType }}</p>
+    <div v-if="isUptoTab">Mobile / Tablet Layout</div>
+    <div v-else>Desktop Layout</div>
+  </div>
+</template>
+```
+
+## API Reference
+
+### `useResponsive(options)`
+
+**Options**
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `tabMaxWidth` | `number` | `0` | Custom max-width (px) to treat as "up-to tab". When `> 0`, screens at or below this width are considered tablet-sized regardless of breakpoint. |
+
+**Returned Properties**
+
+| Property | Type | Description |
+|---|---|---|
+| `ScreenWidth` | `ComputedRef<number>` | Raw viewport width in pixels. |
+| `ScreenType` | `ComputedRef<string>` | Current Bootstrap-style breakpoint (`'xs'`, `'sm'`, `'md'`, `'lg'`, `'xl'`, `'xxl'`). |
+| `isUptoTab` | `ComputedRef<boolean>` | `true` when viewport is tablet-sized or smaller (`xs`, `sm`, or `<=` `tabMaxWidth`). |

package/.ai/ai_ref_useTheme.md

@@ -1,39 +1,28 @@
-# useTheme (Composable)
-
-A Vue composable that handles light and dark theme toggling, stores the user's preference in `localStorage`, and reacts to system theme changes (`prefers-color-scheme: dark`).
-
-## Installation
-
-```javascript
-npm install @vue3-appsbd-ui
-```
-
-## Usage
-
-```html
-<script setup>
-import { useTheme } from "@vue3-appsbd-ui";
-
-const { theme, toggleTheme, applyTheme } = useTheme();
-
-// Manually switch to 'dark' or 'light'
-// applyTheme('dark');
-</script>
-
-<template>
-  <div>
-    <p>Current Theme: {{ theme }}</p>
-    <button @click="toggleTheme">Toggle Theme</button>
-  </div>
-</template>
-```
-
-## API Reference
-
-### Returned Properties & Methods
-
-| Name | Type | Description |
-|---|---|---|
-| `theme` | `Ref<string>` | A reactive reference containing the current theme (`'light'` or `'dark'`). |
-| `toggleTheme` | `Function` | Toggles the current theme between `'light'` and `'dark'`, updates the DOM (`data-bs-theme`), and saves to `localStorage`. |
-| `applyTheme(value)` | `Function` | Explicitly sets the theme to the provided `value` (`'light'` or `'dark'`). |
+# useTheme (Composable)
+
+Handles light/dark theme toggling, stores preference in `localStorage`, and reacts to system `prefers-color-scheme: dark` changes.
+
+## Usage
+
+```html
+<script setup>
+import { useTheme } from "@vue3-appsbd-ui";
+
+const { theme, toggleTheme, applyTheme } = useTheme();
+</script>
+
+<template>
+  <div>
+    <p>Current Theme: {{ theme }}</p>
+    <button @click="toggleTheme">Toggle Theme</button>
+  </div>
+</template>
+```
+
+## API Reference
+
+| Name | Type | Description |
+|---|---|---|
+| `theme` | `Ref<string>` | Reactive current theme (`'light'` or `'dark'`). |
+| `toggleTheme` | `Function` | Toggles between `'light'` and `'dark'`, updates the DOM (`data-bs-theme`), and saves to `localStorage`. |
+| `applyTheme(value)` | `Function` | Explicitly sets the theme to `'light'` or `'dark'`. |