@feedvalue/vue 0.1.0 → 0.1.2

package/README.md

@@ -50,6 +50,48 @@ const { open, isReady, isOpen } = useFeedValue();
 </template>
 ```
 
+### Headless Mode
+
+For complete UI control, use headless mode. The SDK fetches config and provides all API methods but renders no DOM elements:
+
+```typescript
+// main.ts
+app.use(createFeedValue({
+  widgetId: 'your-widget-id',
+  headless: true, // No trigger button or modal rendered
+}));
+```
+
+```vue
+<script setup>
+import { ref } from 'vue';
+import { useFeedValue } from '@feedvalue/vue';
+
+const { isReady, isOpen, open, close, submit, isSubmitting, isHeadless } = useFeedValue();
+const message = ref('');
+
+async function handleSubmit() {
+  await submit({ message: message.value });
+  message.value = '';
+  close();
+}
+</script>
+
+<template>
+  <button @click="open" :disabled="!isReady">
+    Feedback
+  </button>
+
+  <div v-if="isOpen" class="my-modal">
+    <textarea v-model="message" placeholder="Your feedback..." />
+    <button @click="handleSubmit" :disabled="isSubmitting">
+      {{ isSubmitting ? 'Sending...' : 'Submit' }}
+    </button>
+    <button @click="close">Cancel</button>
+  </div>
+</template>
+```
+
 ### Standalone Usage (No Plugin)
 
 ```vue
@@ -99,8 +141,53 @@ async function handleSubmit() {
 </template>
 ```
 
+### Custom Fields
+
+Custom fields allow you to collect structured data beyond the main feedback message. **Custom fields must be defined in your widget configuration on the FeedValue dashboard before use.**
+
+1. Go to your widget settings in the FeedValue dashboard
+2. Add custom fields with types: `text`, `email`, or `emoji`
+3. Use `customFieldValues` when submitting:
+
+```vue
+<script setup>
+import { ref } from 'vue';
+import { useFeedValue } from '@feedvalue/vue';
+
+const { submit, isReady } = useFeedValue();
+const name = ref('');
+const category = ref('feature');
+
+async function handleSubmit() {
+  await submit({
+    message: 'Detailed feedback',
+    customFieldValues: {
+      // Field IDs must match those defined in your widget configuration
+      name: name.value,
+      category: category.value,
+    },
+  });
+}
+</script>
+
+<template>
+  <form @submit.prevent="handleSubmit">
+    <input v-model="name" placeholder="Your name" />
+    <select v-model="category">
+      <option value="bug">Bug Report</option>
+      <option value="feature">Feature Request</option>
+    </select>
+    <button type="submit" :disabled="!isReady">Submit</button>
+  </form>
+</template>
+```
+
+> **Important**: The field IDs in `customFieldValues` must match the field IDs defined in your widget configuration on the dashboard.
+
 ### User Identification
 
+Attach user context to feedback submissions. This data is **not shown in the widget UI** but is stored with the submission and visible in your FeedValue dashboard:
+
 ```vue
 <script setup>
 import { watch } from 'vue';
@@ -124,6 +211,10 @@ watch(() => props.user, (user) => {
 </script>
 ```
 
+> **User Data vs Custom Fields**
+> - **User data** (`identify`/`setData`): Hidden from users, automatically attached to submissions. Use for internal context like user IDs, subscription plans, etc.
+> - **Custom fields** (`customFieldValues`): Shown as form inputs in the widget. Users fill these in themselves. Must be defined in widget configuration first.
+
 ### Options API Support
 
 ```vue
@@ -149,11 +240,12 @@ export default {
 
 Creates a Vue plugin for FeedValue.
 
-| Option | Type | Required | Description |
-|--------|------|----------|-------------|
-| `widgetId` | `string` | Yes | Widget ID from FeedValue dashboard |
-| `apiBaseUrl` | `string` | No | Custom API URL (for self-hosted) |
-| `config` | `Partial<FeedValueConfig>` | No | Configuration overrides |
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `widgetId` | `string` | Yes | - | Widget ID from FeedValue dashboard |
+| `apiBaseUrl` | `string` | No | Production URL | Custom API URL (for self-hosted) |
+| `config` | `Partial<FeedValueConfig>` | No | - | Configuration overrides |
+| `headless` | `boolean` | No | `false` | Disable all DOM rendering |
 
 ### `useFeedValue(widgetId?, config?)`
 
@@ -176,6 +268,7 @@ Composable to access FeedValue functionality.
 | `isVisible` | `Readonly<Ref<boolean>>` | Trigger is visible |
 | `error` | `Readonly<Ref<Error \| null>>` | Current error |
 | `isSubmitting` | `Readonly<Ref<boolean>>` | Submission in progress |
+| `isHeadless` | `Readonly<Ref<boolean>>` | Running in headless mode |
 | `open` | `() => void` | Open modal |
 | `close` | `() => void` | Close modal |
 | `toggle` | `() => void` | Toggle modal |
@@ -216,6 +309,18 @@ export default defineNuxtPlugin((nuxtApp) => {
 });
 ```
 
+For headless mode in Nuxt:
+
+```typescript
+// plugins/feedvalue.client.ts
+export default defineNuxtPlugin((nuxtApp) => {
+  nuxtApp.vueApp.use(createFeedValue({
+    widgetId: 'your-widget-id',
+    headless: true, // Build your own UI
+  }));
+});
+```
+
 The `.client.ts` suffix ensures the plugin only runs on the client side.
 
 ## SSR Support
@@ -239,6 +344,18 @@ const { isReady } = useFeedValue();
 </template>
 ```
 
+## Default vs Headless Mode
+
+| Feature | Default Mode | Headless Mode |
+|---------|--------------|---------------|
+| Trigger button | Dashboard-styled | You build it |
+| Modal | Dashboard-styled | You build it |
+| API methods | Available | Available |
+| User tracking | Available | Available |
+| Dashboard config | Fetched | Fetched |
+
+Use `headless: true` when you want complete control over the UI.
+
 ## Requirements
 
 - Vue 3.3.0 or higher

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feedvalue/vue",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "FeedValue Vue 3 SDK - Plugin and Composables for Vue 3+",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -23,17 +23,26 @@
     "README.md"
   ],
   "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint src",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
   "peerDependencies": {
     "vue": ">=3.3.0"
   },
   "dependencies": {
-    "@feedvalue/core": "^0.1.0"
+    "@feedvalue/core": "workspace:^"
   },
   "devDependencies": {
     "@vitejs/plugin-vue": "^5.2.0",
     "@vitest/coverage-v8": "^2.1.0",
     "@vue/test-utils": "^2.4.0",
-    "eslint": "^9.17.0",
     "happy-dom": "^15.11.0",
     "tsup": "^8.3.0",
     "typescript": "^5.7.0",
@@ -65,15 +74,5 @@
   ],
   "engines": {
     "node": ">=18"
-  },
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "lint": "eslint src --ext .ts",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "typecheck": "tsc --noEmit",
-    "clean": "rm -rf dist"
   }
-}
+}