@live-change/frontend-template 0.9.198 → 0.9.199

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

package/.claude/skills/live-change-frontend-command-forms.md

@@ -0,0 +1,215 @@
+---
+description: Build forms with api.command, command-form, workingZone, confirm and toast
+---
+
+# Skill: live-change-frontend-command-forms (Claude Code)
+
+Use this skill when you build **forms and actions** for a LiveChange frontend:
+
+- calling `api.command`,
+- using `<command-form>`,
+- handling destructive actions with confirm + toast.
+
+## Choosing the right pattern
+
+Before using this skill, pick the right approach:
+
+| Pattern | When to use |
+|---|---|
+| `editorData` | **Editing model records** (create/update). Drafts, validation, `AutoField`. See `live-change-frontend-editor-form` skill. |
+| `actionData` | **One-shot action forms** (not CRUD). Submit once → done. See `live-change-frontend-action-form` skill. |
+| `api.command` | **Single button or programmatic calls** (no form fields). This skill, Step 1. |
+| `<command-form>` | **Avoid.** Legacy. Only for trivial prototypes without drafts or `AutoField`. This skill, Step 2. |
+
+**Decision flow:**
+
+1. Does the user fill in form fields? → **No**: use `api.command` (this skill).
+2. Is it editing a model record? → **Yes**: use `editorData`.
+3. Is it a one-shot action? → **Yes**: use `actionData`.
+4. Only use `<command-form>` for the simplest throwaway cases.
+
+## Step 1 – Use `api.command` directly
+
+1. Import and create `api`:
+
+```js
+import { api as useApi } from '@live-change/vue3-ssr'
+
+const api = useApi()
+```
+
+2. Call commands as:
+
+```js
+await api.command(['deviceManager', 'createMyUserDevice'], {
+  name: 'My device'
+})
+
+await api.command(['deviceManager', 'deleteMyUserDevice'], {
+  device: id
+})
+```
+
+3. Wrap in `try/catch` if you need custom error handling.
+
+## Step 2 – `<command-form>` (legacy – prefer editorData/actionData)
+
+> **Note:** `<command-form>` is the oldest pattern. For new code, prefer `editorData` (model editing) or `actionData` (one-shot actions) – they support drafts, `AutoField`, and richer state management.
+
+1. Use `<command-form>` only for trivial forms without drafts or `AutoField`.
+2. Provide:
+   - `service` – service name,
+   - `action` – action name,
+   - `fields` – constant/hidden fields (e.g. ids).
+
+Example:
+
+```vue
+<command-form
+  service="deviceManager"
+  action="updateMyUserDevice"
+  :fields="{ device: deviceId }"
+>
+  <template #default="{ fieldProps, submit, busy }">
+    <div class="space-y-4">
+      <div>
+        <label class="block text-sm font-medium mb-1">
+          Name
+        </label>
+        <InputText v-bind="fieldProps('name')" class="w-full" />
+      </div>
+      <div class="flex justify-end gap-2">
+        <Button
+          label="Save"
+          icon="pi pi-check"
+          :loading="busy"
+          @click="submit"
+        />
+      </div>
+    </div>
+  </template>
+</command-form>
+```
+
+## Step 3 – Confirm + Toast for destructive actions
+
+1. Use PrimeVue `useConfirm` and `useToast`.
+2. Put the `api.command` call in `accept`.
+
+Example:
+
+```js
+import { useConfirm } from 'primevue/useconfirm'
+import { useToast } from 'primevue/usetoast'
+import { api as useApi } from '@live-change/vue3-ssr'
+
+const api = useApi()
+const confirm = useConfirm()
+const toast = useToast()
+
+function deleteDevice(id) {
+  confirm.require({
+    message: 'Are you sure you want to delete this device?',
+    header: 'Confirmation',
+    icon: 'pi pi-exclamation-triangle',
+    accept: async () => {
+      await api.command(['deviceManager', 'deleteMyUserDevice'], { device: id })
+      toast.add({
+        severity: 'success',
+        summary: 'Deleted',
+        life: 2000
+      })
+    }
+  })
+}
+```
+
+## Step 3b – WorkingZone for button actions (outside forms)
+
+When a button triggers an async action outside a form, wrap it with `workingZone.addPromise()` so the global loading spinner activates:
+
+```js
+import { inject } from 'vue'
+import { useToast } from 'primevue/usetoast'
+import { useActions } from '@live-change/vue3-ssr'
+
+const workingZone = inject('workingZone')
+const toast = useToast()
+const actions = useActions()
+
+function createDevice() {
+  workingZone.addPromise('createDevice', (async () => {
+    const result = await actions.deviceManager.createMyUserDevice({ name: 'New device' })
+    toast.add({ severity: 'success', summary: 'Created', life: 2000 })
+    router.push({ name: 'device', params: { device: result } })
+  })())
+}
+```
+
+Combine with `confirm.require()` for destructive actions:
+
+```js
+function deleteDevice(id) {
+  confirm.require({
+    message: 'Are you sure?',
+    header: 'Confirmation',
+    icon: 'pi pi-trash',
+    acceptClass: 'p-button-danger',
+    accept: async () => {
+      workingZone.addPromise('deleteDevice', (async () => {
+        await actions.deviceManager.deleteMyUserDevice({ device: id })
+        toast.add({ severity: 'success', summary: 'Deleted', life: 2000 })
+      })())
+    }
+  })
+}
+```
+
+For a detailed guide, see the `live-change-frontend-action-buttons` skill.
+
+## Step 4 – Pattern for sensitive values (toggle + copy)
+
+1. By default, hide sensitive values (keys, tokens, etc.).
+2. Add:
+   - a toggle button (eye / eye-slash),
+   - a copy button with a toast.
+
+Example:
+
+```vue
+<template>
+  <div class="flex items-center gap-2">
+    <code>
+      {{ revealed ? item.pairingKey : '••••••••••••' }}
+    </code>
+    <Button
+      :icon="revealed ? 'pi pi-eye-slash' : 'pi pi-eye'"
+      text
+      @click="revealed = !revealed"
+    />
+    <Button
+      icon="pi pi-copy"
+      text
+      @click="copyToClipboard(item.pairingKey)"
+    />
+  </div>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import { useToast } from 'primevue/usetoast'
+
+const toast = useToast()
+const revealed = ref(false)
+
+async function copyToClipboard(text) {
+  await navigator.clipboard.writeText(text)
+  toast.add({
+    severity: 'info',
+    summary: 'Copied',
+    life: 1500
+  })
+}
+</script>
+```
+

package/.claude/skills/live-change-frontend-data-views.md

@@ -0,0 +1,182 @@
+---
+description: Build reactive data views with usePath, live, .with() and useClient auth guards
+---
+
+# Skill: live-change-frontend-data-views (Claude Code)
+
+Use this skill when you build **reactive data views** using `usePath`, `live`, `.with()`, and `useClient` in a LiveChange frontend.
+
+## When to use
+
+- You are loading data from backend views.
+- Paths depend on reactive values (route params, props, client state).
+- You need to load related objects alongside the main data.
+- You need to restrict data loading for unauthenticated users.
+
+## Step 1 – Basic data loading with computed paths
+
+When paths depend on reactive values (route params, props), wrap them in `computed()`:
+
+```javascript
+import { computed, unref } from 'vue'
+import { usePath, live } from '@live-change/vue3-ssr'
+import { useRoute } from 'vue-router'
+
+const path = usePath()
+const route = useRoute()
+const articleId = route.params.article
+
+const articlePath = computed(() => path.blog.article({ article: unref(articleId) }))
+const commentsPath = computed(() => path.blog.articleComments({ article: unref(articleId) }))
+
+const [article, comments] = await Promise.all([
+  live(articlePath),
+  live(commentsPath),
+])
+```
+
+In templates access `.value`:
+
+```vue
+<h1>{{ article.value?.title }}</h1>
+<div v-for="comment in comments.value" :key="comment.id">
+  {{ comment.text }}
+</div>
+```
+
+## Step 2 – Load related objects with `.with()`
+
+Chain `.with()` to attach related data to each item:
+
+```javascript
+const articlesPath = computed(() =>
+  path.blog.articlesByCreatedAt({ limit: 20 })
+    .with(article => path.userIdentification.identification({
+      sessionOrUserType: article.authorType,
+      sessionOrUser: article.author
+    }).bind('authorProfile'))
+    .with(article => path.blog.articleCategory({ category: article.category }).bind('categoryData'))
+)
+
+const [articles] = await Promise.all([live(articlesPath)])
+```
+
+Access in template:
+
+```vue
+<div v-for="article in articles.value" :key="article.id">
+  <h3>{{ article.title }}</h3>
+  <span>by {{ article.authorProfile?.firstName }}</span>
+  <Tag :value="article.categoryData?.name" />
+</div>
+```
+
+### Nested `.with()` (with inside with)
+
+```javascript
+const eventPath = computed(() =>
+  path.myService.event({ event: eventId })
+    .with(event => path.myService.eventState({ event: event.id }).bind('state')
+      .with(state => path.myService.roundPairs({
+        event: event.id,
+        round: state.round
+      }).bind('roundPairs'))
+    )
+)
+```
+
+## Step 3 – Conditional loading with `useClient`
+
+Use `useClient()` to check authentication state and conditionally build paths:
+
+```javascript
+import { useClient } from '@live-change/vue3-ssr'
+
+const client = useClient()
+
+// Path that only loads for logged-in users (null path = no fetch)
+const myDataPath = computed(() =>
+  client.value.user && path.blog.myArticles({})
+)
+
+// Path that only loads for admins
+const adminPath = computed(() =>
+  client.value.roles.includes('admin') && path.blog.allArticles({})
+)
+
+const [myData, adminData] = await Promise.all([
+  live(myDataPath),
+  live(adminPath),
+])
+```
+
+When the path is `null` / `false` / `undefined`, `live()` returns a ref with `null` value and does not subscribe.
+
+### Conditional rendering in templates
+
+```vue
+<template>
+  <!-- Admin-only button -->
+  <Button v-if="client.roles.includes('admin')"
+    label="Create" icon="pi pi-plus" @click="create" />
+
+  <!-- Show different content based on auth -->
+  <div v-if="client.user">
+    <!-- Authenticated content -->
+  </div>
+  <div v-else>
+    <p>Please sign in to see your articles.</p>
+    <router-link :to="{ name: 'user:signIn' }">Sign in</router-link>
+  </div>
+</template>
+```
+
+## Step 4 – Dependent paths
+
+When one path depends on data from another, load them sequentially:
+
+```javascript
+// First load
+const [article] = await Promise.all([live(articlePath)])
+
+// Dependent path using data from first load
+const authorPath = computed(() =>
+  article.value && path.userIdentification.identification({
+    sessionOrUserType: article.value.authorType,
+    sessionOrUser: article.value.author
+  })
+)
+const [author] = await Promise.all([live(authorPath)])
+```
+
+Or use `.with()` to combine them in a single query (preferred when possible).
+
+## Step 5 – Props-based paths in components
+
+When building reusable components that receive IDs as props:
+
+```vue
+<script setup>
+  import { computed } from 'vue'
+  import { usePath, live } from '@live-change/vue3-ssr'
+
+  const props = defineProps({
+    articleId: { type: String, required: true }
+  })
+
+  const path = usePath()
+
+  const articlePath = computed(() => path.blog.article({ article: props.articleId }))
+  const [article] = await Promise.all([live(articlePath)])
+</script>
+```
+
+## Summary
+
+| Pattern | When to use |
+|---|---|
+| `computed(() => path.xxx(...))` | Path depends on reactive values |
+| `.with(item => path.yyy(...).bind('field'))` | Attach related objects |
+| `client.value.user && path.xxx(...)` | Load only when authenticated |
+| `client.value.roles.includes('admin')` | Load/show only for specific roles |
+| Sequential `live()` calls | Path depends on data from previous load |