@live-change/frontend-template 0.9.198 → 0.9.200

package/.claude/skills/live-change-frontend-action-form/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: live-change-frontend-action-form
+description: Build one-shot action forms with actionData, AutoField and ActionButtons
+---
+
+# Skill: live-change-frontend-action-form (Claude Code)
+
+Use this skill when you build **one-shot action forms** with `actionData` and `AutoField` in a LiveChange frontend.
+
+## When to use
+
+- You need a form for a command/action (not CRUD model editing).
+- The form submits once, then shows a "done" state.
+- You want draft auto-save while the user fills in the form.
+
+**Editing a model record instead?** Use `editorData` (see `live-change-frontend-editor-form` skill).
+**No form fields, just a button?** Use `api.command` (see `live-change-frontend-command-forms` skill).
+
+## Step 1 – Set up actionData
+
+```javascript
+import { AutoField, actionData, ActionButtons } from '@live-change/frontend-auto-form'
+
+const formData = await actionData({
+  service: 'blog',
+  action: 'publishArticle',
+  parameters: { article: props.articleId },   // fixed params (not shown as fields)
+  initialValue: { scheduleTime: null },       // initial values for editable fields
+  draft: true,
+  doneToast: 'Article published!',
+  onDone: (result) => {
+    router.push({ name: 'articles' })
+  },
+})
+```
+
+For reactive parameters, use `computedAsync`:
+
+```javascript
+import { computedAsync } from '@vueuse/core'
+
+const formData = computedAsync(() =>
+  actionData({
+    service: 'blog',
+    action: 'publishArticle',
+    parameters: { article: props.articleId },
+  })
+)
+```
+
+## Step 2 – Build the template with AutoField
+
+**Every field must show validation errors.** Always pass `:error="formData.propertiesErrors?.fieldName"` to AutoField — or use a manual `Message` if not using AutoField (see `live-change-frontend-editor-form` skill for all 3 approaches).
+
+**Always wrap in `<form>`** with `@submit.prevent` and `@reset.prevent` handlers. `ActionButtons` uses `type="submit"` / `type="reset"` internally — without a parent `<form>`, the buttons do nothing.
+
+Use `formData.action.properties.*` as definitions and `formData.value.*` as v-model:
+
+```vue
+<template>
+  <form @submit.prevent="formData.submit()" @reset.prevent="formData.reset()">
+    <AutoField
+      :definition="formData.action.properties.scheduleTime"
+      v-model="formData.data.value.scheduleTime"
+      :error="formData.propertiesErrors?.scheduleTime"
+      label="Schedule time"
+    />
+    <AutoField
+      :definition="formData.action.properties.message"
+      v-model="formData.data.value.message"
+      :error="formData.propertiesErrors?.message"
+      label="Message"
+    />
+
+    <ActionButtons :actionFormData="formData" :resetButton="true" />
+  </form>
+</template>
+```
+
+## Step 3 – Handle done state
+
+After successful submission, `formData.done` becomes `true`:
+
+```vue
+<template>
+  <div v-if="formData.done" class="text-center">
+    <i class="pi pi-check-circle text-4xl text-green-500 mb-2"></i>
+    <p>Article published successfully!</p>
+  </div>
+  <form v-else @submit.prevent="formData.submit()" @reset.prevent="formData.reset()">
+    <!-- fields + ActionButtons -->
+  </form>
+</template>
+```
+
+## Step 4 – Manual buttons (alternative to ActionButtons)
+
+```vue
+<div class="flex gap-2 justify-end">
+  <Button
+    type="submit"
+    :label="formData.submitting ? 'Executing...' : 'Execute'"
+    :icon="formData.submitting ? 'pi pi-spin pi-spinner' : 'pi pi-play'"
+    :disabled="formData.submitting"
+  />
+  <Button type="reset" label="Reset" :disabled="!formData.changed" icon="pi pi-eraser" />
+</div>
+```
+
+## editorData vs actionData
+
+| Aspect | `editorData` | `actionData` |
+|---|---|---|
+| Purpose | CRUD model editing | One-shot command form |
+| Identifier | `model` + `identifiers` | `action` + `parameters` |
+| Create/update | Detects automatically | Always "execute" |
+| After submit | Record is saved | `done` becomes `true` |
+| Definition source | `editor.model` | `formData.action` |
+| `parameters` | Extra params on save | Fixed fields excluded from form |
+
+## Key options
+
+| Option | Default | Description |
+|---|---|---|
+| `service` | required | Service name |
+| `action` | required | Action name |
+| `parameters` | `{}` | Fixed identifier fields (not editable) |
+| `initialValue` | `{}` | Initial values for editable fields |
+| `draft` | `true` | Auto-save draft while filling |
+| `debounce` | `600` | Debounce delay in ms |
+| `doneToast` | `"Action done"` | Toast after success |
+| `onDone` | – | Callback after success |
+
+## Key returned properties
+
+| Property | Description |
+|---|---|
+| `data` | Editable form data (recommended), it is a ref, it should be used with value - editor.data.value |
+| `value` | Editable form data (obsolete), it is a ref, it should be used with value - editor.value.value |
+| `action` | Action definition (`.properties.*` for `AutoField`) |
+| `editableProperties` | Properties not fixed by `parameters` |
+| `changed` | Form differs from initial value |
+| `submit()` | Execute the action |
+| `submitting` | Action call in progress |
+| `done` | `true` after success |
+| `reset()` | Discard draft, restore initial value |
+| `propertiesErrors` | Server validation errors per property |
+| `draftChanged` | Draft auto-saved but not submitted |
+| `savingDraft` | Draft auto-save in progress |

package/.claude/skills/live-change-frontend-action-form.md

@@ -0,0 +1,143 @@
+---
+description: Build one-shot action forms with actionData, AutoField and ActionButtons
+---
+
+# Skill: live-change-frontend-action-form (Claude Code)
+
+Use this skill when you build **one-shot action forms** with `actionData` and `AutoField` in a LiveChange frontend.
+
+## When to use
+
+- You need a form for a command/action (not CRUD model editing).
+- The form submits once, then shows a "done" state.
+- You want draft auto-save while the user fills in the form.
+
+**Editing a model record instead?** Use `editorData` (see `live-change-frontend-editor-form` skill).
+**No form fields, just a button?** Use `api.command` (see `live-change-frontend-command-forms` skill).
+
+## Step 1 – Set up actionData
+
+```javascript
+import { AutoField, actionData, ActionButtons } from '@live-change/frontend-auto-form'
+
+const formData = await actionData({
+  service: 'blog',
+  action: 'publishArticle',
+  parameters: { article: props.articleId },   // fixed params (not shown as fields)
+  initialValue: { scheduleTime: null },       // initial values for editable fields
+  draft: true,
+  doneToast: 'Article published!',
+  onDone: (result) => {
+    router.push({ name: 'articles' })
+  },
+})
+```
+
+For reactive parameters, use `computedAsync`:
+
+```javascript
+import { computedAsync } from '@vueuse/core'
+
+const formData = computedAsync(() =>
+  actionData({
+    service: 'blog',
+    action: 'publishArticle',
+    parameters: { article: props.articleId },
+  })
+)
+```
+
+## Step 2 – Build the template with AutoField
+
+Use `formData.action.properties.*` as definitions and `formData.value.*` as v-model:
+
+```vue
+<template>
+  <form @submit.prevent="formData.submit()" @reset.prevent="formData.reset()">
+    <AutoField
+      :definition="formData.action.properties.scheduleTime"
+      v-model="formData.value.scheduleTime"
+      :error="formData.propertiesErrors?.scheduleTime"
+      label="Schedule time"
+    />
+    <AutoField
+      :definition="formData.action.properties.message"
+      v-model="formData.value.message"
+      :error="formData.propertiesErrors?.message"
+      label="Message"
+    />
+
+    <ActionButtons :actionFormData="formData" :resetButton="true" />
+  </form>
+</template>
+```
+
+## Step 3 – Handle done state
+
+After successful submission, `formData.done` becomes `true`:
+
+```vue
+<template>
+  <div v-if="formData.done" class="text-center">
+    <i class="pi pi-check-circle text-4xl text-green-500 mb-2"></i>
+    <p>Article published successfully!</p>
+  </div>
+  <form v-else @submit.prevent="formData.submit()" @reset.prevent="formData.reset()">
+    <!-- fields + ActionButtons -->
+  </form>
+</template>
+```
+
+## Step 4 – Manual buttons (alternative to ActionButtons)
+
+```vue
+<div class="flex gap-2 justify-end">
+  <Button
+    type="submit"
+    :label="formData.submitting ? 'Executing...' : 'Execute'"
+    :icon="formData.submitting ? 'pi pi-spin pi-spinner' : 'pi pi-play'"
+    :disabled="formData.submitting"
+  />
+  <Button type="reset" label="Reset" :disabled="!formData.changed" icon="pi pi-eraser" />
+</div>
+```
+
+## editorData vs actionData
+
+| Aspect | `editorData` | `actionData` |
+|---|---|---|
+| Purpose | CRUD model editing | One-shot command form |
+| Identifier | `model` + `identifiers` | `action` + `parameters` |
+| Create/update | Detects automatically | Always "execute" |
+| After submit | Record is saved | `done` becomes `true` |
+| Definition source | `editor.model` | `formData.action` |
+| `parameters` | Extra params on save | Fixed fields excluded from form |
+
+## Key options
+
+| Option | Default | Description |
+|---|---|---|
+| `service` | required | Service name |
+| `action` | required | Action name |
+| `parameters` | `{}` | Fixed identifier fields (not editable) |
+| `initialValue` | `{}` | Initial values for editable fields |
+| `draft` | `true` | Auto-save draft while filling |
+| `debounce` | `600` | Debounce delay in ms |
+| `doneToast` | `"Action done"` | Toast after success |
+| `onDone` | – | Callback after success |
+
+## Key returned properties
+
+| Property | Description |
+|---|---|
+| `value` | Editable form data |
+| `action` | Action definition (`.properties.*` for `AutoField`) |
+| `editableProperties` | Properties not fixed by `parameters` |
+| `changed` | Form differs from initial value |
+| `submit()` | Execute the action |
+| `submitting` | Action call in progress |
+| `done` | `true` after success |
+| `reset()` | Discard draft, restore initial value |
+| `propertiesErrors` | Server validation errors per property |
+| `draftChanged` | Draft auto-saved but not submitted |
+| `savingDraft` | Draft auto-save in progress |

package/.claude/skills/live-change-frontend-analytics/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: live-change-frontend-analytics
+description: Integrate analytics tracking with analytics.emit and provider wiring
+---
+
+# Skill: live-change-frontend-analytics (Claude Code)
+
+Use this skill when you add **analytics tracking** to a LiveChange frontend.
+
+## When to use
+
+- You need to track user actions, page views, or custom events.
+- You are integrating PostHog, GA4, or another analytics provider.
+- You need consent-aware analytics.
+
+## Step 1 – Emit events with `analytics`
+
+Import `analytics` from `@live-change/vue3-components` and emit events:
+
+```javascript
+import { analytics } from '@live-change/vue3-components'
+
+// In a component or handler:
+analytics.emit('article:published', { articleId: article.id })
+analytics.emit('button:clicked', { action: 'delete', target: 'article' })
+```
+
+Standard built-in events:
+
+| Event | Payload | When emitted |
+|---|---|---|
+| `pageView` | route `to` object | On route change (automatic in App.vue) |
+| `user:identification` | `{ user, session, identification, contacts }` | When user identity is known |
+| `consent` | `{ analytics: boolean }` | When user grants/denies tracking consent |
+| `locale:change` | locale settings object | When language/locale changes |
+
+## Step 2 – Wire user identification in App.vue
+
+Emit `user:identification` when the user profile is loaded:
+
+```javascript
+import { analytics } from '@live-change/vue3-components'
+import { usePath, live, useClient } from '@live-change/vue3-ssr'
+import { computed, watch } from 'vue'
+
+const client = useClient()
+const path = usePath()
+
+if(typeof window !== 'undefined') {
+  Promise.all([
+    live(path.userIdentification.myIdentification()),
+  ]).then(([identification]) => {
+    const fullIdentification = computed(() => ({
+      user: client.value.user,
+      session: client.value.session,
+      identification: identification.value,
+    }))
+    watch(fullIdentification, (newId) => {
+      analytics.emit('user:identification', newId)
+    }, { immediate: true })
+  })
+}
+```
+
+## Step 3 – Create a provider file (e.g. PostHog)
+
+Create a file like `src/analytics/posthog.js`:
+
+```javascript
+import { analytics } from '@live-change/vue3-components'
+import posthog from 'posthog-js'
+
+posthog.init('phc_YOUR_KEY', {
+  api_host: 'https://eu.i.posthog.com',
+  person_profiles: 'always'
+})
+
+// Page views
+analytics.on('pageView', (to) => {
+  posthog.register({
+    route: { name: to.name, params: to.params }
+  })
+})
+
+// User identification
+analytics.on('user:identification', (identification) => {
+  if (!identification.user) {
+    posthog.reset()
+    return
+  }
+  posthog.identify(identification.user, {
+    firstName: identification.identification?.firstName,
+    lastName: identification.identification?.lastName,
+  })
+})
+
+// Consent
+analytics.on('consent', (payload) => {
+  if (payload?.analytics === true) {
+    posthog.opt_in_capturing()
+  } else {
+    posthog.opt_out_capturing()
+  }
+})
+
+// Catch-all for custom events
+const ignored = ['user:identification', 'pageView', 'consent']
+analytics.on('*', (type, event) => {
+  if (ignored.includes(type)) return
+  posthog.capture(type, event)
+})
+```
+
+Import it in `App.vue`:
+
+```javascript
+import './analytics/posthog'
+```
+
+## Step 4 – Emit custom events in components
+
+```javascript
+// Track a form submission
+analytics.emit('form:submitted', { formName: 'contactForm' })
+
+// Track a feature usage
+analytics.emit('feature:used', { feature: 'darkMode', enabled: true })
+
+// Track navigation
+analytics.emit('navigation:click', { target: 'pricing', source: 'navbar' })
+```
+
+## Step 5 – Consent handling
+
+Emit consent events from your consent banner:
+
+```javascript
+function acceptAnalytics() {
+  analytics.emit('consent', { analytics: true })
+}
+
+function rejectAnalytics() {
+  analytics.emit('consent', { analytics: false })
+}
+```
+
+Provider files listen for `consent` and enable/disable tracking accordingly.

package/.claude/skills/live-change-frontend-analytics.md

@@ -0,0 +1,146 @@
+---
+description: Integrate analytics tracking with analytics.emit and provider wiring
+---
+
+# Skill: live-change-frontend-analytics (Claude Code)
+
+Use this skill when you add **analytics tracking** to a LiveChange frontend.
+
+## When to use
+
+- You need to track user actions, page views, or custom events.
+- You are integrating PostHog, GA4, or another analytics provider.
+- You need consent-aware analytics.
+
+## Step 1 – Emit events with `analytics`
+
+Import `analytics` from `@live-change/vue3-components` and emit events:
+
+```javascript
+import { analytics } from '@live-change/vue3-components'
+
+// In a component or handler:
+analytics.emit('article:published', { articleId: article.id })
+analytics.emit('button:clicked', { action: 'delete', target: 'article' })
+```
+
+Standard built-in events:
+
+| Event | Payload | When emitted |
+|---|---|---|
+| `pageView` | route `to` object | On route change (automatic in App.vue) |
+| `user:identification` | `{ user, session, identification, contacts }` | When user identity is known |
+| `consent` | `{ analytics: boolean }` | When user grants/denies tracking consent |
+| `locale:change` | locale settings object | When language/locale changes |
+
+## Step 2 – Wire user identification in App.vue
+
+Emit `user:identification` when the user profile is loaded:
+
+```javascript
+import { analytics } from '@live-change/vue3-components'
+import { usePath, live, useClient } from '@live-change/vue3-ssr'
+import { computed, watch } from 'vue'
+
+const client = useClient()
+const path = usePath()
+
+if(typeof window !== 'undefined') {
+  Promise.all([
+    live(path.userIdentification.myIdentification()),
+  ]).then(([identification]) => {
+    const fullIdentification = computed(() => ({
+      user: client.value.user,
+      session: client.value.session,
+      identification: identification.value,
+    }))
+    watch(fullIdentification, (newId) => {
+      analytics.emit('user:identification', newId)
+    }, { immediate: true })
+  })
+}
+```
+
+## Step 3 – Create a provider file (e.g. PostHog)
+
+Create a file like `src/analytics/posthog.js`:
+
+```javascript
+import { analytics } from '@live-change/vue3-components'
+import posthog from 'posthog-js'
+
+posthog.init('phc_YOUR_KEY', {
+  api_host: 'https://eu.i.posthog.com',
+  person_profiles: 'always'
+})
+
+// Page views
+analytics.on('pageView', (to) => {
+  posthog.register({
+    route: { name: to.name, params: to.params }
+  })
+})
+
+// User identification
+analytics.on('user:identification', (identification) => {
+  if (!identification.user) {
+    posthog.reset()
+    return
+  }
+  posthog.identify(identification.user, {
+    firstName: identification.identification?.firstName,
+    lastName: identification.identification?.lastName,
+  })
+})
+
+// Consent
+analytics.on('consent', (payload) => {
+  if (payload?.analytics === true) {
+    posthog.opt_in_capturing()
+  } else {
+    posthog.opt_out_capturing()
+  }
+})
+
+// Catch-all for custom events
+const ignored = ['user:identification', 'pageView', 'consent']
+analytics.on('*', (type, event) => {
+  if (ignored.includes(type)) return
+  posthog.capture(type, event)
+})
+```
+
+Import it in `App.vue`:
+
+```javascript
+import './analytics/posthog'
+```
+
+## Step 4 – Emit custom events in components
+
+```javascript
+// Track a form submission
+analytics.emit('form:submitted', { formName: 'contactForm' })
+
+// Track a feature usage
+analytics.emit('feature:used', { feature: 'darkMode', enabled: true })
+
+// Track navigation
+analytics.emit('navigation:click', { target: 'pricing', source: 'navbar' })
+```
+
+## Step 5 – Consent handling
+
+Emit consent events from your consent banner:
+
+```javascript
+function acceptAnalytics() {
+  analytics.emit('consent', { analytics: true })
+}
+
+function rejectAnalytics() {
+  analytics.emit('consent', { analytics: false })
+}
+```
+
+Provider files listen for `consent` and enable/disable tracking accordingly.