@live-change/frontend-template 0.9.199 → 0.9.201

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

@@ -0,0 +1,240 @@
+---
+name: live-change-frontend-editor-form
+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 (recommended: `await`)
+
+Use `await editorData(...)` directly in `<script setup>`, just like `live()`. Suspense handles the loading state.
+
+```javascript
+import { editorData, AutoField, EditorButtons } from '@live-change/frontend-auto-form'
+import { useToast } from 'primevue/usetoast'
+import { useRouter, useRoute } from 'vue-router'
+
+const toast = useToast()
+const router = useRouter()
+const route = useRoute()
+
+const editor = await editorData({
+  service: 'blog',
+  model: 'Article',
+  identifiers: { article: route.params.article },
+  draft: true,
+  onSaved: () => {
+    toast.add({ severity: 'success', summary: 'Saved', life: 1500 })
+  },
+  onCreated: (result) => {
+    router.push({ name: 'article', params: { article: result } })
+  },
+})
+```
+
+For new records, pass empty identifiers:
+
+```javascript
+identifiers: {} // creates a new record
+```
+
+This is the simplest and most readable approach. Use it when identifiers are available at setup time (static values, route params).
+
+## Step 2 – Build the template with AutoField
+
+Use `editor.model.properties.*` as definitions and `editor.data.value` for v-model bindings:
+
+**Important:** Always wrap in a `<form>` element. `EditorButtons` uses `type="submit"` / `type="reset"` internally — without a parent `<form>`, the buttons do nothing.
+
+```vue
+<template>
+  <form @submit.prevent="editor.save()" @reset.prevent="editor.reset()">
+    <div class="space-y-4">
+      <AutoField
+        :definition="editor.model.properties.title"
+        v-model="editor.data.value.title"
+        :error="editor.propertiesErrors?.title"
+        label="Title"
+      />
+      <AutoField
+        :definition="editor.model.properties.body"
+        v-model="editor.data.value.body"
+        :error="editor.propertiesErrors?.body"
+        label="Body"
+      />
+
+      <!-- Custom input inside AutoField — gets label + error automatically -->
+      <AutoField
+        :definition="editor.model.properties.category"
+        v-model="editor.data.value.category"
+        :error="editor.propertiesErrors?.category"
+        label="Category"
+      >
+        <Dropdown
+          v-model="editor.data.value.category"
+          :options="categories"
+          optionLabel="name"
+          optionValue="id"
+          class="w-full"
+        />
+      </AutoField>
+
+      <EditorButtons :editor="editor" :resetButton="true" />
+    </div>
+  </form>
+</template>
+```
+
+No `v-if="editor"` needed — with `await`, the editor is always available after the component loads (Suspense handles the loading state).
+
+## Step 3 – Use EditorButtons (alternative)
+
+Instead of manual buttons, use the `EditorButtons` component:
+
+```vue
+<template>
+  <form @submit.prevent="editor.save()" @reset.prevent="editor.reset()">
+    <!-- fields... -->
+    <EditorButtons :editor="editor" :resetButton="true" />
+  </form>
+</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.
+
+## Showing validation errors — 3 approaches
+
+**Every field in an `editorData` form must show validation errors.** Never use bare `InputText`/`Dropdown` without error feedback.
+
+### Approach 1 — AutoField without slot (default, simplest)
+
+AutoField auto-picks the right input component and renders label + error `Message` automatically:
+
+```vue
+<AutoField :definition="editor.model.properties.name" v-model="editor.data.value.name"
+  :error="editor.propertiesErrors?.name" label="Name" />
+```
+
+Use for standard fields where the default input is fine.
+
+### Approach 2 — AutoField with slot (custom input)
+
+Wrap a custom input inside AutoField. AutoField still renders label and error:
+
+```vue
+<AutoField :definition="editor.model.properties.depth" v-model="editor.data.value.depth"
+  :error="editor.propertiesErrors?.depth" label="Depth">
+  <Dropdown v-model="editor.data.value.depth" :options="depthOptions"
+    placeholder="Select depth" class="w-full" />
+</AutoField>
+```
+
+Use when you need a non-standard input (custom Dropdown formatting, Popover picker, InputNumber with buttons, etc.). AutoField slots: `#default({ validationResult, uid })`, `#label({ uid })`, `#error({ validationResult })`.
+
+### Approach 3 — Manual `Message` (no AutoField wrapper)
+
+When the layout doesn't allow an AutoField wrapper (e.g. sub-fields of an Object property), add error feedback manually:
+
+```vue
+<InputText v-model="editor.data.value.address.street" placeholder="Street" class="w-full" />
+<Message v-if="editor.propertiesErrors?.address" severity="error"
+  variant="simple" size="small" class="mt-1">
+  {{ editor.propertiesErrors.address }}
+</Message>
+```
+
+Use as a last resort when there's no model property definition for the individual field.
+
+## Step 4 – Reactive identifiers with computedAsync (advanced)
+
+When identifiers come from reactive sources that **may change during the component lifetime** (e.g. a prop that changes without page navigation), use `computedAsync`. Create an additional `computed` to alias the data for cleaner template access:
+
+```javascript
+import { computed } from 'vue'
+import { computedAsync } from '@vueuse/core'
+import { editorData, AutoField, EditorButtons } from '@live-change/frontend-auto-form'
+
+const editor = computedAsync(() =>
+  editorData({
+    service: 'blog',
+    model: 'Article',
+    identifiers: { article: props.articleId },
+    draft: true,
+  })
+)
+
+// Alias for cleaner template access
+const editable = computed(() => editor.value?.value)
+```
+
+Then in the template:
+
+```vue
+<template>
+  <form v-if="editor" @submit.prevent="editor.save()" @reset.prevent="editor.reset()">
+    <AutoField
+      :definition="editor.model.properties.title"
+      v-model="editable.value.title"
+      :error="editor.propertiesErrors?.title"
+      label="Title"
+    />
+    <EditorButtons :editor="editor" />
+  </form>
+</template>
+```
+
+**When to use approach 1 vs approach 2:**
+- Route params (`route.params.id`) → use `await` (approach 1). Route changes cause full page remount.
+- Static identifiers (`{}` for new records) → use `await` (approach 1).
+- Reactive prop that changes without remount → use `computedAsync` (approach 2).
+
+## 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 |
+|---|---|
+| `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 |
+| `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 |

package/.claude/skills/live-change-frontend-locale-time/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: live-change-frontend-locale-time
+description: Handle locale, timezone, currentTime, time synchronization and email locale
+---
+
+# Skill: live-change-frontend-locale-time (Claude Code)
+
+Use this skill when you work with **locale, language, time, and timezone** in a LiveChange frontend.
+
+## When to use
+
+- You need to display dates/times in the user's timezone.
+- You are building a time-sensitive feature (countdown, deadline, scheduling).
+- You need to sync locale with vue-i18n.
+- You are writing an email template that must use the recipient's language.
+
+## Step 1 – Set up locale in App.vue
+
+```javascript
+import { watch } from 'vue'
+import { useI18n } from 'vue-i18n'
+import { useLocale } from '@live-change/vue3-components'
+
+const { locale: i18nLocale } = useI18n()
+const locale = useLocale()
+
+// Capture browser locale settings and save to backend
+locale.captureLocale()
+
+// Watch for locale changes and sync with vue-i18n
+locale.getLocaleObservable()
+watch(() => locale.localeRef.value, (newLocale) => {
+  if (newLocale?.language && i18nLocale.value !== newLocale.language) {
+    i18nLocale.value = newLocale.language
+  }
+}, { immediate: true })
+```
+
+## Step 2 – Display dates in user timezone
+
+Use vue-i18n's `d()` function for formatting and `locale.localTime()` for SSR timezone conversion:
+
+```vue
+<template>
+  <span>{{ d(locale.localTime(new Date(article.createdAt)), 'long') }}</span>
+</template>
+
+<script setup>
+  import { useI18n } from 'vue-i18n'
+  import { useLocale } from '@live-change/vue3-components'
+
+  const { d } = useI18n()
+  const locale = useLocale()
+</script>
+```
+
+`locale.localTime(date)` converts server timestamps to the user's timezone during SSR. On the client (browser), it returns the date unchanged since the browser handles timezone natively.
+
+## Step 3 – Use `currentTime` for reactive clocks
+
+`currentTime` is a global `Ref<number>` that ticks every 500ms:
+
+```vue
+<template>
+  <span>{{ formattedTime }}</span>
+</template>
+
+<script setup>
+  import { computed } from 'vue'
+  import { currentTime } from '@live-change/frontend-base'
+  import { useI18n } from 'vue-i18n'
+
+  const { d } = useI18n()
+  const formattedTime = computed(() =>
+    isNaN(currentTime.value) ? '' : d(new Date(currentTime.value), 'time')
+  )
+</script>
+```
+
+Any component reading `currentTime` re-renders automatically every 500ms.
+
+## Step 4 – Correct clock skew with `useTimeSynchronization`
+
+When the client clock differs from the server clock (important for real-time features like quizzes, countdowns, auctions):
+
+```javascript
+import { useTimeSynchronization } from '@live-change/vue3-ssr'
+import { currentTime } from '@live-change/frontend-base'
+
+const timeSync = useTimeSynchronization()
+
+// Convert client time to server time (reactive computed)
+const serverTime = timeSync.localToServerComputed(currentTime)
+
+// Countdown to a server-side deadline
+const timeRemaining = computed(() => deadline.value - serverTime.value)
+const seconds = computed(() => Math.max(0, Math.floor(timeRemaining.value / 1000) % 60))
+const minutes = computed(() => Math.max(0, Math.floor(timeRemaining.value / 1000 / 60)))
+```
+
+Enable time synchronization in `config.js`:
+
+```javascript
+export default {
+  timeSynchronization: true,
+  // ...
+}
+```
+
+**When to use:** Only when clock skew matters – real-time events, countdown timers, time-limited actions. For simple date display, `currentTime` alone is sufficient.
+
+### Returned object from `useTimeSynchronization()`:
+
+| Property | Description |
+|---|---|
+| `diff` | Server-client time offset in ms |
+| `synchronized` | `true` once sync is complete |
+| `serverToLocal(ts)` | Convert server timestamp to local |
+| `localToServer(ts)` | Convert local timestamp to server |
+| `serverToLocalComputed(ts)` | Reactive computed version |
+| `localToServerComputed(ts)` | Reactive computed version |
+
+## Step 5 – Smooth countdown with requestAnimationFrame
+
+For sub-500ms precision (e.g. animated countdown knobs):
+
+```javascript
+import { ref } from 'vue'
+import { useRafFn } from '@vueuse/core'
+import { useTimeSynchronization } from '@live-change/vue3-ssr'
+
+const rafNow = ref(Date.now())
+useRafFn(() => { rafNow.value = Date.now() })
+
+const timeSync = useTimeSynchronization()
+const rafServerTime = timeSync.localToServerComputed(rafNow)
+
+const countdown = computed(() =>
+  Math.max(0, deadline.value - rafServerTime.value)
+)
+```
+
+## Step 6 – Locale in email templates
+
+Email templates render server-side. They fetch the recipient's locale explicitly:
+
+```javascript
+import { useI18n } from 'vue-i18n'
+import { useLocale } from '@live-change/vue3-components'
+
+const { locale: i18nLocale, t } = useI18n()
+const locale = useLocale()
+
+// props.json contains { user, client: { session } }
+const data = JSON.parse(json)
+
+// Fetch locale for the recipient (not current session)
+await Promise.all([
+  locale.getOtherUserOrSessionLocale(data.user, data.client?.session)
+])
+
+// Apply to vue-i18n
+if (locale.getLanguage()) i18nLocale.value = locale.getLanguage()
+```
+
+Key differences from regular pages:
+
+| Aspect | Regular page | Email template |
+|---|---|---|
+| Locale source | `locale.getLocale()` (current user) | `locale.getOtherUserOrSessionLocale(user, session)` |
+| Time conversion | `locale.localTime()` only on SSR | Always server-side |
+| Reactive updates | Yes | No (one-shot SSR render) |

package/.claude/skills/live-change-frontend-page-list-detail/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: live-change-frontend-page-list-detail
+description: Build list and detail pages with live data, computed paths, .with() and useClient
+---
+
+# Skill: live-change-frontend-page-list-detail (Claude Code)
+
+Use this skill when you need to build a **list + detail** UI in Vue 3 / PrimeVue / Tailwind for a LiveChange backend.
+
+## When to use
+
+- You are adding a new list page (devices, orders, etc.).
+- You are adding a detail page for a single object.
+- You want to follow the `live(path)` + `Promise.all` pattern compatible with SSR.
+
+## Step 1 – List page (`src/pages/<resource>/index.vue`)
+
+1. Create the file: `src/pages/<resource>/index.vue`.
+2. In the `<template>`, follow this layout:
+   - container with padding (`container mx-auto p-4`),
+   - header with title and “add” button,
+   - empty-state card,
+   - grid of cards or rows.
+
+Example:
+
+```vue
+<template>
+  <div class="container mx-auto p-4">
+    <div class="flex items-center justify-between mb-6">
+      <h1 class="text-2xl font-bold">Devices</h1>
+      <Button label="Add" icon="pi pi-plus" @click="openDialog" />
+    </div>
+
+    <Card v-if="devices.value?.length === 0">
+      <template #content>
+        <p class="text-center text-gray-500">
+          No devices yet
+        </p>
+      </template>
+    </Card>
+
+    <div class="grid gap-4">
+      <Card v-for="device in devices.value" :key="device.id">
+        <template #content>
+          <!-- device content -->
+        </template>
+      </Card>
+    </div>
+  </div>
+</template>
+
+<script setup>
+import { path, live, api as useApi } from '@live-change/vue3-ssr'
+import Button from 'primevue/button'
+import Card from 'primevue/card'
+
+const api = useApi()
+
+const [devices] = await Promise.all([
+  live(path().deviceManager.myUserDevices({}))
+])
+
+function openDialog() {
+  // open dialog for creating a new device
+}
+</script>
+
+<route>
+  { "name": "devices", "meta": { "signedIn": true } }
+</route>
+```
+
+## Step 2 – Detail page (`src/pages/<resource>/[id].vue`)
+
+1. Create `src/pages/<resource>/[id].vue`.
+2. In `script setup`:
+   - use `useRoute()` to get the id (`route.params.id`),
+   - fetch the main object and related data using `Promise.all`.
+
+Example skeleton:
+
+```vue
+<template>
+  <div class="container mx-auto p-4 space-y-4" v-if="item.value">
+    <Card>
+      <template #title>
+        {{ item.value.name }}
+      </template>
+      <template #content>
+        <!-- details -->
+      </template>
+    </Card>
+  </div>
+</template>
+
+<script setup>
+import { path, live } from '@live-change/vue3-ssr'
+import { useRoute } from 'vue-router'
+import Card from 'primevue/card'
+
+const route = useRoute()
+const id = route.params.id
+
+const [item] = await Promise.all([
+  live(path().myService.myUserItem({ item: id }))
+])
+</script>
+
+<route>
+  { "name": "myItem", "meta": { "signedIn": true } }
+</route>
+```
+
+## Step 3 – Computed paths with reactive parameters
+
+When the path depends on reactive values (route params, props), wrap it in `computed()`:
+
+```js
+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 deviceId = route.params.device
+
+const devicePath = computed(() => path.deviceManager.myUserDevice({ device: unref(deviceId) }))
+const connectionsPath = computed(() =>
+  path.deviceManager.deviceOwnedDeviceConnections({ device: unref(deviceId) })
+)
+
+const [device, connections] = await Promise.all([
+  live(devicePath),
+  live(connectionsPath),
+])
+```
+
+## Step 4 – Attach related objects with `.with()`
+
+Use `.with()` to load related data alongside each item:
+
+```js
+const devicesPath = computed(() =>
+  path.deviceManager.myUserDevices({})
+    .with(device => path.deviceManager.deviceState({ device: device.id }).bind('state'))
+    .with(device => path.userIdentification.identification({
+      sessionOrUserType: device.ownerType,
+      sessionOrUser: device.owner
+    }).bind('ownerProfile'))
+)
+
+const [devices] = await Promise.all([live(devicesPath)])
+```
+
+Access in template: `device.state?.online`, `device.ownerProfile?.firstName`.
+
+## Step 5 – Auth guard with `useClient`
+
+Use `useClient()` to conditionally show UI or load data based on authentication:
+
+```js
+import { useClient } from '@live-change/vue3-ssr'
+
+const client = useClient()
+
+// Conditional path (null = no fetch)
+const adminDataPath = computed(() =>
+  client.value.roles.includes('admin') && path.deviceManager.allDevices({})
+)
+const [adminData] = await Promise.all([live(adminDataPath)])
+```
+
+Template:
+
+```vue
+<Button v-if="client.roles.includes('admin')" label="Admin panel" />
+<div v-if="!client.user">
+  <p>Please sign in</p>
+  <router-link :to="{ name: 'user:signIn' }">Sign in</router-link>
+</div>
+```
+
+## Step 6 – Status tags and simple indicators
+
+1. Use PrimeVue `Tag` for status fields.
+2. Map statuses to severities (`success`, `secondary`, etc.).
+
+Example:
+
+```vue
+<Tag
+  :value="conn.status"
+  :severity="conn.status === 'online' ? 'success' : 'secondary'"
+/>
+```
+
+## Step 7 – Large lists with RangeViewer
+
+For large or infinite-scroll lists, use `<RangeViewer>` instead of loading everything at once. See the `live-change-frontend-range-list` skill for details.
+