@live-change/frontend-template 0.9.199 → 0.9.201

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-command-forms/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: live-change-frontend-command-forms
+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/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: live-change-frontend-data-views
+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 |