@appsbd/vue3-appsbd-ui 1.0.1 → 1.0.2

package/.ai/ai_ref_abVeeRules.md

@@ -0,0 +1,42 @@
+# 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.

package/.ai/ai_ref_useAlert.md

@@ -0,0 +1,63 @@
+# 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). |

package/.ai/ai_ref_useFileValidator.md

@@ -0,0 +1,46 @@
+# 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). |

package/.ai/ai_ref_useResponsive.md

@@ -0,0 +1,55 @@
+# 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`). |

package/.ai/ai_ref_useTheme.md

@@ -0,0 +1,39 @@
+# 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'`). |

package/.ai/ai_ref_useToast.md

@@ -0,0 +1,42 @@
+# useToast (Composable)
+
+Provides a procedural API to spawn toast notifications using the globally registered `$toast` instance (usually powered by `vue-toastification`).
+
+## Installation
+
+```javascript
+npm install @vue3-appsbd-ui
+```
+
+## Usage
+
+```html
+<script setup>
+import { useToast } from "@vue3-appsbd-ui";
+
+const { toast } = useToast();
+
+function showNotifications() {
+  toast.success("Profile saved successfully");
+  toast.error("Failed to connect to server", { timeout: 5000 });
+}
+</script>
+
+<template>
+  <button @click="showNotifications">Show Toasts</button>
+</template>
+```
+
+## API Reference
+
+### `toast` Methods
+
+| Method | Signature | Description |
+|---|---|---|
+| `toast(msg, options)` | `Function` | Spawns a default toast notification. |
+| `toast.success(msg, options)` | `Function` | Spawns a success toast notification. |
+| `toast.error(msg, options)` | `Function` | Spawns an error toast notification. |
+| `toast.warning(msg, options)` | `Function` | Spawns a warning toast notification. |
+| `toast.info(msg, options)` | `Function` | Spawns an info toast notification. |
+| `toast.dismiss(id)` | `Function` | Dismisses a specific toast by its ID. |
+| `toast.clear()` | `Function` | Clears all currently visible toasts. |

package/AI_REFERENCE.md

@@ -94,6 +94,15 @@ Each component also has a standalone reference under `.ai/` with installation, f
 | `AbPricingTable`               | Stylized, responsive pricing table component with feature list and package columns.                                    | [.ai/ai_ref_AbPricingTable.md](./.ai/ai_ref_AbPricingTable.md)         |
 | `AbChart`                      | Flexible chart component powered by Apache ECharts.                                                                    | [.ai/ai_ref_AbChart.md](./.ai/ai_ref_AbChart.md)                       |
 | `AbDarkModeToggler`            | Light / dark theme toggle (pairs with `useTheme`).                                                                     | [.ai/ai_ref_AbDarkModeToggler.md](./.ai/ai_ref_AbDarkModeToggler.md)   |
+| `useAlert`                     | Procedural API to trigger SweetAlert-based modal alerts, notifications, and confirmations.                             | [.ai/ai_ref_useAlert.md](./.ai/ai_ref_useAlert.md)                     |
+| `abEventBus` / `emitterObj`    | Lightweight global event bus using `tiny-emitter`.                                                                     | [.ai/ai_ref_abEventBus.md](./.ai/ai_ref_abEventBus.md)                 |
+| `useTheme`                     | Composable for light/dark theme toggling with localStorage and system preference sync.                                 | [.ai/ai_ref_useTheme.md](./.ai/ai_ref_useTheme.md)                     |
+| `useToast`                     | Procedural API to spawn toast notifications (success, error, warning, info).                                           | [.ai/ai_ref_useToast.md](./.ai/ai_ref_useToast.md)                     |
+| `useFileValidator`             | File validation utilities (size, MIME type) and file icon/image resolvers.                                             | [.ai/ai_ref_useFileValidator.md](./.ai/ai_ref_useFileValidator.md)     |
+| `useResponsive`                | Real-time viewport width tracker for responsive layout decisions (Bootstrap 5 aligned).                                | [.ai/ai_ref_useResponsive.md](./.ai/ai_ref_useResponsive.md)           |
+| `abTranslate`                  | Localization utility wrapping `vue3-gettext` with automatic variable interpolation.                                    | [.ai/ai_ref_abTranslate.md](./.ai/ai_ref_abTranslate.md)               |
+| `abVeeRules`                   | Collection of pre-configured VeeValidate validation rules integrated with localization.                                | [.ai/ai_ref_abVeeRules.md](./.ai/ai_ref_abVeeRules.md)                 |
+| `abRequestParam`               | Data-transfer classes to build structured API request parameters (pagination, sorting, filtering).                     | [.ai/ai_ref_abRequestParam.md](./.ai/ai_ref_abRequestParam.md)         |
 
 ## 3. Full Component API Reference
 
@@ -140,19 +149,13 @@ Global configuration setter for library-wide tokens.
 | Name                  | Type    | Default     | Notes                                                   |
 | --------------------- | ------- | ----------- | ------------------------------------------------------- |
 | `type`                | String  | `"button"`  | Native button type.                                     |
-| `variant`             | String  | `"primary"` | Color variant (`primary`, `secondary`, `danger`, etc.). |
+| `color`               | String  | `"primary"` | Color variant (`primary`, `secondary`, `danger`, etc.). |
 | `size`                | String  | `"md"`      | Button size (`xs`, `sm`, `md`, `lg`, `xl`, `xxl`).      |
-| `isOutline`           | Boolean | `false`     | Applies the outline style for the selected variant.     |
+| `isOutline`           | Boolean | `false`     | Applies the outline style for the selected color.       |
 | `isIconBtn`           | Boolean | `false`     | Adjusts formatting for a button with only an icon.      |
 | `isAnimated`          | Boolean | `false`     | Shows built-in loader animation.                        |
 | `isHideTextOnAnimate` | Boolean | `false`     | Hides slot text while animated.                         |
 | `showIconDivider`     | Boolean | `false`     | Renders divider between `#icon` and label.              |
-| Name                  | Type    | Default     | Notes                                                   |
-| --------------------- | ------- | ----------  | ------------------------------------------              |
-| `type`                | String  | `"button"`  | Native button type.                                     |
-| `isAnimated`          | Boolean | `false`     | Shows built-in loader animation.                        |
-| `isHideTextOnAnimate` | Boolean | `false`     | Hides slot text while animated.                         |
-| `showIconDivider`     | Boolean | `false`     | Renders divider between `#icon` and label.              |
 
 **Slots**
 
@@ -160,7 +163,7 @@ Global configuration setter for library-wide tokens.
 - `icon` ? leading icon element.
 - `svg` ? replaces the built-in loader SVG when `isAnimated` is true.
 
-**Notes** ? Variant and size are controlled via props (`variant`, `size`).
+**Notes** ? Color and size are controlled via props (`color`, `size`).
 
 ---
 
@@ -623,15 +626,15 @@ Option shape: `{ val, label?, img_src?, icon?, iconComponent?, icon_ctnr_class?,
 | Name            | Type    | Default     | Notes |
 | --------------- | ------- | ----------- | ----- |
 | `size`          | String  | `"md"`      |       |
-| `variant`       | String  | `"primary"` |       |
+| `color`         | String  | `"primary"` |       |
 | `isOutline`     | Boolean | `false`     |       |
 | `isRoundedPill` | Boolean | `false`     |       |
 | `isDot`         | Boolean | `false`     |       |
-| `isAvatar`      | Boolean | `false`     |       |
 | `isClose`       | Boolean | `false`     |       |
 | `isAdd`         | Boolean | `false`     |       |
+| `position`      | String  | `"right"`   |       |
 
-**Slots** ? `default` ? badge content.
+**Slots** ? `default` ? badge content, `content` ? icon or image content placed via position.
 
 ---
 
@@ -735,7 +738,7 @@ Custom built-in replacement for `@vueform/multiselect`.
 
 **Events** ? `update:modelValue`, `clear`, `change(value)`, `select(value)`, `open`, `close`, `search-change(query)`.
 
-**Slots** ? `label`, `prefix`, `postfix`, `icon`, `singlelabel(value)`, `option({ option, isSelected })`, `noresults`, `option-loading`, `loader-icon`.
+**Slots** ? `label`, `prefix`, `postfix`, `icon`, `singlelabel(value)`, `taglabel(value)`, `option({ option, isSelected })`, `noresults`, `option-loading`, `loader-icon`.
 
 **v-model** ? yes.