@appsbd/vue3-appsbd-ui 1.0.3 → 1.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appsbd/vue3-appsbd-ui",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Reusable Vue 3 component library",
   "type": "module",
   "main": "./dist/vue3-appsbd-ui.cjs.js",
@@ -23,10 +23,16 @@
     "dist",
     "readme.md",
     "AI_REFERENCE.md",
+    "AI_REF.md",
     ".ai",
+    "skills",
+    "scripts/postinstall.js",
+    "scripts/setup.js",
+    "scripts/skill-groups.js",
     "design-system.md"
   ],
   "scripts": {
+    "postinstall": "node scripts/postinstall.js",
     "up": "npm run build && npm publish",
     "dev": "vite --mode playground",
     "lib": "vite",

package/readme.md

@@ -27,7 +27,65 @@ npm install bootstrap bootstrap-icons vee-validate @vee-validate/rules vue-route
 
 ## 🤖 AI Assistant Integration
 
-If you are generating code in a project that consumes this library, provide your AI with the `AI_REFERENCE.md` file for immediate context on component existence, prop signatures, and usage patterns.
+Installing this library automatically copies AI skills into your project so Claude Code and Agent-based tools can generate correct component code without guessing props or imports.
+
+### What gets installed
+
+Running `npm install @appsbd/vue3-appsbd-ui` copies the following automatically:
+
+| Destination | Purpose |
+| --- | --- |
+| `.claude/commands/` | Slash commands for Claude Code (`/use-appsbd-ui`, `/generate-module`) |
+| `.claude/skills/` | Skills auto-detected by Claude Code |
+| `.agent/workflows/` | Workflow commands for Agent-based tools |
+| `.agent/skills/` | Skills for Agent-based tools |
+
+### Available slash commands
+
+| Command | Description |
+| --- | --- |
+| `/use-appsbd-ui` | Loads component reference before generating any code — always run this first |
+| `/generate-module` | Scaffolds a full CRUD module (List + Form + Composable) for a given entity |
+
+**Example:**
+```
+/generate-module
+
+Module: Invoice
+Fields:
+- title (text, required)
+- amount (number, required, min: 0)
+- status (select: Draft | Sent | Paid, required)
+- due_date (date)
+
+API: /api/invoices
+Output: src/modules/invoices/
+```
+
+### Optional: enable additional AI tools
+
+To also install skills for Cursor or Windsurf, pass `APPSBD_AGENTS` during install:
+
+```bash
+APPSBD_AGENTS=cursor npm install @appsbd/vue3-appsbd-ui
+APPSBD_AGENTS=cursor,windsurf npm install @appsbd/vue3-appsbd-ui
+```
+
+Or run the setup script any time after install:
+
+```bash
+node node_modules/@appsbd/vue3-appsbd-ui/scripts/setup.js --cursor --windsurf
+```
+
+### Manual reference
+
+If you prefer not to use auto-installed skills, the reference files are included in the package:
+
+- `node_modules/@appsbd/vue3-appsbd-ui/AI_REF.md` — compact component index (~500 tokens, start here)
+- `node_modules/@appsbd/vue3-appsbd-ui/AI_REFERENCE.md` — full table with descriptions
+- `node_modules/@appsbd/vue3-appsbd-ui/.ai/ai_ref_[Name].md` — per-component props/events/slots
+
+Point your AI to read `AI_REF.md` first, then the specific `.ai/` file for the component you need.
 
 ## 🛠️ Setup
 

package/scripts/postinstall.js

@@ -0,0 +1,55 @@
+import { existsSync, mkdirSync, copyFileSync, readFileSync, readdirSync } from "fs";
+import { join, resolve } from "path";
+import { fileURLToPath } from "url";
+import { getSkillGroups } from "./skill-groups.js";
+
+const __dirname = fileURLToPath(new URL(".", import.meta.url));
+const pkgRoot = resolve(__dirname, "..");
+
+// INIT_CWD = directory where `npm install` was invoked (consuming project root).
+const projectRoot = process.env.INIT_CWD || resolve(__dirname, "../../../..");
+
+// Skip when the library is installing its own devDependencies.
+try {
+  const pkg = JSON.parse(readFileSync(join(projectRoot, "package.json"), "utf8"));
+  if (pkg.name === "@appsbd/vue3-appsbd-ui") process.exit(0);
+} catch {
+  // consuming project has no package.json at that path — continue anyway
+}
+
+// Optional agents: APPSBD_AGENTS=cursor,windsurf npm install @appsbd/vue3-appsbd-ui
+const agents = process.env.APPSBD_AGENTS
+  ? process.env.APPSBD_AGENTS.split(",").map((a) => a.trim().toLowerCase())
+  : [];
+
+try {
+  copySkills(pkgRoot, projectRoot, agents);
+} catch (err) {
+  // Non-fatal — never break npm install
+  console.warn("[@appsbd/vue3-appsbd-ui] Could not install skills:", err.message);
+}
+
+export function copySkills(pkgRoot, projectRoot, agents = []) {
+  const groups = getSkillGroups(pkgRoot, projectRoot, agents);
+  let copied = 0, skipped = 0;
+
+  for (const group of groups) {
+    if (!existsSync(group.src)) continue;
+    const files = readdirSync(group.src).filter((f) => f.endsWith(".md"));
+
+    for (const dest of group.dests) {
+      if (!existsSync(dest)) mkdirSync(dest, { recursive: true });
+      for (const file of files) {
+        const dst = join(dest, file);
+        if (group.override.includes(file) || !existsSync(dst)) {
+          copyFileSync(join(group.src, file), dst);
+          copied++;
+        } else {
+          skipped++;
+        }
+      }
+    }
+  }
+
+  console.log(`[@appsbd/vue3-appsbd-ui] Skills → copied: ${copied}, skipped (preserved): ${skipped}`);
+}

package/scripts/setup.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+// Usage: node node_modules/@appsbd/vue3-appsbd-ui/scripts/setup.js --cursor --windsurf
+
+import { resolve } from "path";
+import { fileURLToPath } from "url";
+import { copySkills } from "./postinstall.js";
+
+const __dirname = fileURLToPath(new URL(".", import.meta.url));
+const pkgRoot = resolve(__dirname, "..");
+const projectRoot = process.env.INIT_CWD || process.cwd();
+
+const agents = process.argv
+  .filter((a) => a.startsWith("--"))
+  .map((a) => a.slice(2).toLowerCase());
+
+copySkills(pkgRoot, projectRoot, agents);

package/scripts/skill-groups.js

@@ -0,0 +1,38 @@
+import { join } from "path";
+
+// Central config for all agent skill destinations.
+// Add new agents here — postinstall.js and setup.js both use this.
+
+const OPTIONAL_AGENTS = {
+  cursor: (pkgRoot, projectRoot) => [
+    { src: join(pkgRoot, "skills", "commands"), dests: [join(projectRoot, ".cursor", "rules")], override: ["use-appsbd-ui.md"] },
+    { src: join(pkgRoot, "skills", "skills"),   dests: [join(projectRoot, ".cursor", "rules")], override: [] },
+  ],
+  windsurf: (pkgRoot, projectRoot) => [
+    { src: join(pkgRoot, "skills", "commands"), dests: [join(projectRoot, ".windsurf", "workflows")], override: ["use-appsbd-ui.md"] },
+    { src: join(pkgRoot, "skills", "skills"),   dests: [join(projectRoot, ".windsurf", "rules")],     override: [] },
+  ],
+};
+
+export function getSkillGroups(pkgRoot, projectRoot, agents = []) {
+  const groups = [
+    // Always installed — Claude Code + Agent
+    {
+      src: join(pkgRoot, "skills", "commands"),
+      dests: [join(projectRoot, ".claude", "commands"), join(projectRoot, ".agent", "workflows")],
+      override: ["use-appsbd-ui.md"],
+    },
+    {
+      src: join(pkgRoot, "skills", "skills"),
+      dests: [join(projectRoot, ".claude", "skills"), join(projectRoot, ".agent", "skills")],
+      override: [],
+    },
+  ];
+
+  for (const agent of agents) {
+    if (OPTIONAL_AGENTS[agent]) groups.push(...OPTIONAL_AGENTS[agent](pkgRoot, projectRoot));
+    else console.warn(`[@appsbd/vue3-appsbd-ui] Unknown agent "${agent}" — skipped. Available: ${Object.keys(OPTIONAL_AGENTS).join(", ")}`);
+  }
+
+  return groups;
+}

package/skills/commands/generate-module.md

@@ -0,0 +1,76 @@
+---
+description: Generate a full CRUD module (List + Form + Composable) using @appsbd/vue3-appsbd-ui components
+---
+
+# Generate Module
+
+## Before anything else
+
+Invoke `/use-appsbd-ui` to load the component reference. Use only props/events/slots documented there.
+
+## What to generate
+
+Given a module name and field definitions, scaffold three files:
+
+### 1. `[Name]List.vue` — List/Table view
+
+- Use `AbTable` for the data grid
+- `AbButton` (primary) to open the create form
+- `AbConfirmPopover` on each row's delete action
+- `AbSkeleton` while data is loading
+- `AbBadge` for status/boolean columns
+- Call `useToast` on successful delete
+
+### 2. `[Name]Form.vue` — Create / Edit form
+
+- Wrap everything in `AbModal` with `v-model:is-modal-visible`
+- Map each field to the correct Ab* input:
+  | Field type     | Component         |
+  |----------------|-------------------|
+  | text / email   | `AbInputField`    |
+  | number         | `AbNumberField`   |
+  | select (single)| `AbMultiSelect` mode="single" |
+  | select (multi) | `AbMultiSelect` mode="multiple" |
+  | boolean/switch | `AbToggle`        |
+  | date / range   | `AbDateTimePicker`|
+  | radio group    | `AbFormCheck`     |
+  | textarea       | `AbInputField` type="textarea" |
+  | file           | `AbFileUploader`  |
+- Add VeeValidate `rules` prop on required / validated fields
+- `@on-submit` handler calls composable save method
+- Call `modal.value.showLoader(true)` before async, `showLoader(false)` after
+- Call `useToast` success/error inside the submit handler
+
+### 3. `use[Name].js` — Composable
+
+- `ref` for list data, single item, loading state, pagination
+- `fetchList()`, `fetchOne(id)`, `save(payload)`, `remove(id)` functions
+- `save` detects create vs edit by presence of `id`
+- Return all refs and functions
+
+## Output format
+
+Ask the user for:
+1. **Module name** (PascalCase, e.g. `Product`)
+2. **Fields** — name, type, required?, options (for selects)
+3. **API base path** (e.g. `/api/products`)
+4. **Output folder** (default: `src/modules/[name]/`)
+
+Then generate all three files in one response, each in a separate code block labeled with its file path.
+
+## Example invocation
+
+```
+/generate-module
+
+Module: Invoice
+Fields:
+- title (text, required)
+- amount (number, required, min: 0)
+- status (select: Draft | Sent | Paid, required)
+- due_date (date, required)
+- notes (textarea)
+
+API: /api/invoices
+Output: src/modules/invoices/
+```

package/skills/commands/settings-form.md

@@ -0,0 +1,175 @@
+---
+description: Use when building a settings or preferences page with AbSettingsForm
+---
+
+# Generate a Settings Form
+
+## Before anything else
+
+Read `node_modules/@appsbd/vue3-appsbd-ui/.ai/ai_ref_AbSettingsForm.md` for the full API.
+
+## What AbSettingsForm does
+
+- Wraps fields in a VeeValidate `<Form>` with a built-in submit/loading state.
+- When nested inside an `AbWizardStep`, auto-registers as the step's validator — returning `false` from `onSubmit` blocks the wizard from advancing.
+- Standalone use (outside a wizard) works as a plain validated form.
+
+## Supported field components
+
+| Field type | Component |
+|---|---|
+| text / email / password | `<ab-input-field>` |
+| number | `<ab-number-field>` |
+| select (single) | `<ab-multi-select mode="single">` |
+| select (multi) | `<ab-multi-select mode="multiple">` |
+| boolean / switch | `<ab-toggle>` |
+| date | `<ab-date-time-picker>` |
+| checkbox / radio group | `<ab-form-check>` |
+| textarea | `<ab-input-field type="textarea">` |
+| file / avatar | `<ab-file-uploader>` |
+| tags | `<ab-input-tag>` |
+| color | `<ab-color-picker>` |
+
+## Rules
+
+- Import `AbSettingsForm` explicitly — it is **not** globally registered.
+- Pass the save handler to `:on-submit`. The component manages the loading state automatically — do not add a separate loading ref.
+- Return `false` (or throw) from `onSubmit` to block wizard progression or keep the form in error state.
+- Wrap each field in `<ab-field>` only when you need a standalone label+error wrapper outside a component that has its own label prop.
+- All `Ab*` form inputs must receive a `name` prop for VeeValidate to track them.
+
+## Standalone settings page
+
+```vue
+<template>
+  <ab-settings-form :on-submit="save">
+    <ab-input-field v-model="form.name"  name="name"  label="Display name"  rules="required" />
+    <ab-input-field v-model="form.email" name="email" label="Email"          rules="required|email" />
+    <ab-toggle      v-model="form.notifications" name="notifications" title="Email notifications" />
+    <ab-multi-select
+      v-model="form.language"
+      name="language"
+      label="Language"
+      :options="languageOptions"
+      label-key="title"
+      value-key="val"
+    />
+  </ab-settings-form>
+</template>
+
+<script setup>
+import { ref } from "vue";
+import { AbSettingsForm, useToast } from "@appsbd/vue3-appsbd-ui";
+
+const { toast } = useToast();
+
+const form = ref({
+  name: "",
+  email: "",
+  notifications: false,
+  language: null,
+});
+
+const languageOptions = [
+  { val: "en", title: "English" },
+  { val: "bn", title: "Bengali" },
+  { val: "ar", title: "Arabic" },
+];
+
+async function save(values) {
+  await api.saveProfile(values);
+  toast.success("Settings saved.");
+}
+</script>
+```
+
+## Wizard with per-step validation
+
+```vue
+<template>
+  <ab-wizard @finished="onFinished">
+    <ab-wizard-step title="Account">
+      <ab-settings-form :on-submit="validateAccount">
+        <ab-input-field v-model="form.email"    name="email"    label="Email"    rules="required|email" />
+        <ab-input-field v-model="form.password" name="password" label="Password" rules="required|min:8" type="password" />
+      </ab-settings-form>
+    </ab-wizard-step>
+
+    <ab-wizard-step title="Profile">
+      <ab-settings-form :on-submit="validateProfile">
+        <ab-input-field v-model="form.name" name="name" label="Full name" rules="required" />
+        <ab-multi-select
+          v-model="form.role"
+          name="role"
+          label="Role"
+          :options="roleOptions"
+          label-key="title"
+          value-key="val"
+          rules="required"
+        />
+      </ab-settings-form>
+    </ab-wizard-step>
+
+    <ab-wizard-step title="Preferences">
+      <ab-settings-form>
+        <ab-toggle v-model="form.emails"    name="emails"    title="Email me updates" />
+        <ab-toggle v-model="form.marketing" name="marketing" title="Marketing emails" />
+      </ab-settings-form>
+    </ab-wizard-step>
+  </ab-wizard>
+</template>
+
+<script setup>
+import { ref } from "vue";
+import { AbSettingsForm, useToast } from "@appsbd/vue3-appsbd-ui";
+
+const { toast } = useToast();
+
+const form = ref({
+  email: "", password: "", name: "", role: null,
+  emails: false, marketing: false,
+});
+
+const roleOptions = [
+  { val: "admin",  title: "Admin" },
+  { val: "editor", title: "Editor" },
+  { val: "viewer", title: "Viewer" },
+];
+
+async function validateAccount(values) {
+  const taken = await api.checkEmail(values.email);
+  if (taken) return false; // blocks wizard from advancing to next step
+}
+
+async function validateProfile(values) {
+  // return false to block, or nothing to allow
+}
+
+function onFinished() {
+  toast.success("Setup complete!");
+}
+</script>
+```
+
+## Output format
+
+Ask the user for:
+1. **Sections / steps** — one settings form per wizard step, or a single standalone form
+2. **Fields per section** — name, type, required?, options (for selects)
+3. **Save / API endpoint**
+
+Then generate the Vue file(s) in one response, each in a separate code block labeled with its file path.
+
+## Example invocation
+
+```
+/settings-form
+
+Page: User Profile Settings
+Sections:
+  - Account: email (required), password (required, min 8)
+  - Preferences: language (select: English|Bengali|Arabic), email_notifications (toggle), theme (select: Light|Dark)
+
+API: /api/user/settings
+Output: src/pages/settings/ProfileSettings.vue
+```

package/skills/commands/use-appsbd-ui.md

@@ -0,0 +1,40 @@
+---
+description: Use when generating code that uses @appsbd/vue3-appsbd-ui components or APIs
+---
+
+# Using @appsbd/vue3-appsbd-ui
+
+## Rules
+
+- Use `Ab*` components before reaching for any external UI library.
+- Never guess props, events, or slots — always read the reference file first.
+- Globally registered components need no import. All others: `import { X } from "@appsbd/vue3-appsbd-ui"`.
+
+## Workflow
+
+1. Read `node_modules/@appsbd/vue3-appsbd-ui/AI_REF.md` to find available components and their reference file paths.
+2. Read `node_modules/@appsbd/vue3-appsbd-ui/.ai/ai_ref_[ComponentName].md` for the exact props / events / slots before writing any code.
+3. Generate code using only the documented API from that file.
+
+## Quick API (no file read needed)
+
+```js
+// Toast
+import { useToast } from "@appsbd/vue3-appsbd-ui";
+const { toast } = useToast();
+toast.success("Done"); // .error / .warning / .info
+
+// Alert
+import { useAlert } from "@appsbd/vue3-appsbd-ui";
+const { alert } = useAlert();
+alert.confirm("Sure?", "", { onConfirm: async () => {} });
+
+// Theme
+import { useTheme } from "@appsbd/vue3-appsbd-ui";
+const { toggleTheme } = useTheme();
+```
+
+```html
+<!-- v-tooltip (global directive) -->
+<ab-button v-tooltip="'Helper text'">Save</ab-button>
+```