@live-change/frontend-template 0.9.198 → 0.9.199

package/.cursor/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/.cursor/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 |

package/.cursor/skills/live-change-frontend-editor-form.md

@@ -0,0 +1,177 @@
+---
+description: Build CRUD editing forms with editorData and AutoField components
+---
+
+# Skill: live-change-frontend-editor-form (Claude Code)
+
+Use this skill when you build **CRUD editing forms** with `editorData` and `AutoField` in a LiveChange frontend.
+
+## When to use
+
+- You need a create/edit form for a model record.
+- You want draft auto-saving while the user types.
+- You prefer individual `<AutoField>` components over `<AutoEditor>` for layout control.
+
+**Not editing a model?** Use `actionData` instead (see `live-change-frontend-action-form` skill).
+**No form fields, just a button?** Use `api.command` (see `live-change-frontend-command-forms` skill).
+
+## Step 1 – Set up editorData
+
+```javascript
+import { ref, getCurrentInstance } from 'vue'
+import { AutoField, editorData } from '@live-change/frontend-auto-form'
+import { useToast } from 'primevue/usetoast'
+import { useRouter } from 'vue-router'
+
+const toast = useToast()
+const router = useRouter()
+const appContext = getCurrentInstance().appContext
+
+const editor = ref(null)
+
+async function loadEditor() {
+  editor.value = await editorData({
+    service: 'blog',
+    model: 'Article',
+    identifiers: { article: props.articleId },
+    draft: true,
+    appContext,
+    toast,
+    onSaved: () => {
+      toast.add({ severity: 'success', summary: 'Saved', life: 1500 })
+    },
+    onCreated: (result) => {
+      router.push({ name: 'article', params: { article: result } })
+    },
+  })
+}
+
+loadEditor()
+```
+
+For new records, pass an empty or missing identifier:
+
+```javascript
+identifiers: { article: props.articleId } // props.articleId can be undefined for new
+```
+
+## Step 2 – Build the template with AutoField
+
+Use `editor.model.properties.*` as definitions and `editor.value.*` as v-model:
+
+```vue
+<template>
+  <div v-if="editor" class="space-y-4">
+    <AutoField
+      :definition="editor.model.properties.title"
+      v-model="editor.value.title"
+      :error="editor.propertiesErrors?.title"
+      label="Title"
+    />
+    <AutoField
+      :definition="editor.model.properties.body"
+      v-model="editor.value.body"
+      :error="editor.propertiesErrors?.body"
+      label="Body"
+    />
+
+    <!-- Manual field alongside AutoField -->
+    <div>
+      <label class="block text-sm font-medium mb-1">Category</label>
+      <Dropdown
+        v-model="editor.value.category"
+        :options="categories"
+        optionLabel="name"
+        optionValue="id"
+        class="w-full"
+      />
+    </div>
+
+    <!-- Buttons -->
+    <div class="flex gap-2 justify-end">
+      <Button v-if="!editor.isNew" @click="editor.save()"
+        label="Save" icon="pi pi-save"
+        :disabled="!editor.changed" />
+      <Button v-else @click="editor.save()"
+        label="Create" icon="pi pi-plus" severity="success"
+        :disabled="!editor.changed" />
+      <Button @click="editor.reset()"
+        label="Reset" icon="pi pi-eraser"
+        :disabled="!editor.changed" />
+    </div>
+  </div>
+</template>
+```
+
+## Step 3 – Use EditorButtons (alternative)
+
+Instead of manual buttons, use the `EditorButtons` component:
+
+```vue
+<template>
+  <div v-if="editor">
+    <!-- fields... -->
+    <EditorButtons :editor="editor" :resetButton="true" />
+  </div>
+</template>
+
+<script setup>
+  import { EditorButtons } from '@live-change/frontend-auto-form'
+</script>
+```
+
+`EditorButtons` automatically handles:
+- "Saving draft..." spinner,
+- "Draft changed" hint,
+- validation error message,
+- Save/Create button (disabled when nothing changed),
+- optional Reset button.
+
+## Step 4 – Reactive identifiers with computedAsync
+
+When identifiers come from reactive sources (route params, props):
+
+```javascript
+import { computedAsync } from '@vueuse/core'
+
+const editor = computedAsync(() =>
+  editorData({
+    service: 'blog',
+    model: 'Article',
+    identifiers: { article: props.articleId },
+    draft: true,
+    appContext,
+    toast,
+  })
+)
+```
+
+## Key options reference
+
+| Option | Default | Description |
+|---|---|---|
+| `service` | required | Service name |
+| `model` | required | Model name |
+| `identifiers` | required | e.g. `{ article: id }` |
+| `draft` | `true` | Auto-save draft while editing |
+| `autoSave` | `false` | Auto-save directly (when `draft: false`) |
+| `debounce` | `600` | Debounce delay in ms |
+| `initialData` | `{}` | Default values for new records |
+| `parameters` | `{}` | Extra params sent with every action |
+| `onSaved` | – | Callback after save |
+| `onCreated` | – | Callback after create (receives result) |
+
+## Key returned properties
+
+| Property | Description |
+|---|---|
+| `value` | Editable data (use with `v-model`) |
+| `model` | Model definition (use `.properties.*` for `AutoField`) |
+| `changed` | `true` when there are unsaved changes |
+| `isNew` | `true` when creating (no existing record) |
+| `save()` | Submit to backend |
+| `reset()` | Discard draft, restore saved state |
+| `propertiesErrors` | Server validation errors per property |
+| `saving` | Save in progress |
+| `draftChanged` | Draft auto-saved but not submitted |
+| `savingDraft` | Draft auto-save in progress |