@appsbd/vue3-appsbd-ui 1.0.1 → 1.0.3

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