@live-change/frontend-template 0.9.197 → 0.9.199

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

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

@@ -0,0 +1,171 @@
+---
+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.md

@@ -0,0 +1,200 @@
+---
+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.
+

package/.claude/skills/live-change-frontend-range-list.md

@@ -0,0 +1,128 @@
+---
+description: Build paginated scrollable lists with RangeViewer, rangeBuckets and .with()
+---
+
+# Skill: live-change-frontend-range-list (Claude Code)
+
+Use this skill when you build **paginated, scrollable lists** backed by DAO ranges in a LiveChange frontend.
+
+## When to use
+
+- You need a list that loads items in pages (infinite scroll).
+- The list is backed by a DAO range view (e.g. `articlesByCreatedAt`).
+- You want to attach related objects to each item via `.with()`.
+
+## Step 1 – Define the path function
+
+The path function receives a `range` object (with `gt`, `gte`, `lt`, `lte`, `limit`, `reverse`) and returns a DAO path.
+
+Use `reverseRange()` to display items newest-first:
+
+```javascript
+import { reverseRange } from '@live-change/vue3-ssr'
+
+function articlesPathRange(range) {
+  return path.blog.articlesByCreatedAt({ ...reverseRange(range) })
+}
+```
+
+## Step 2 – Attach related objects with `.with()`
+
+Chain `.with()` calls to load related data for each item:
+
+```javascript
+function articlesPathRange(range) {
+  return path.blog.articlesByCreatedAt({ ...reverseRange(range) })
+    .with(article => path.userIdentification.identification({
+      sessionOrUserType: article.authorType,
+      sessionOrUser: article.author
+    }).bind('authorProfile'))
+    .with(article => path.blog.articleStats({ article: article.id }).bind('stats'))
+}
+```
+
+Each `.with()` call:
+- receives a proxy of the item,
+- builds a path to the related data,
+- calls `.bind('fieldName')` to attach the result under that field name.
+
+Nested `.with()` is also supported:
+
+```javascript
+function eventsPathRange(range) {
+  return path.myService.allEvents({ ...reverseRange(range) })
+    .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 – Use `<RangeViewer>` in the template
+
+```vue
+<template>
+  <RangeViewer
+    :pathFunction="articlesPathRange"
+    :canLoadTop="false"
+    canDropBottom
+    loadBottomSensorSize="3000px"
+    dropBottomSensorSize="5000px"
+  >
+    <template #empty>
+      <p class="text-center text-surface-500 my-4">No articles yet.</p>
+    </template>
+    <template #default="{ item: article }">
+      <Card class="mb-2">
+        <template #content>
+          <h3>{{ article.title }}</h3>
+          <p class="text-sm text-surface-500">By {{ article.authorProfile?.firstName }}</p>
+        </template>
+      </Card>
+    </template>
+  </RangeViewer>
+</template>
+```
+
+Key props:
+
+| Prop | Default | Description |
+|---|---|---|
+| `pathFunction` | required | `(range) => path` – builds the DAO path for a given range |
+| `bucketSize` | `20` | Items per page |
+| `canLoadTop` / `canLoadBottom` | `true` | Whether loading in each direction is allowed |
+| `canDropTop` / `canDropBottom` | `false` | Whether to drop pages that scrolled far out of view |
+| `loadBottomSensorSize` | `'500px'` | How far before the bottom to trigger loading (increase for smoother UX) |
+| `dropBottomSensorSize` | `'5000px'` | How far to keep before dropping |
+| `frozen` | `false` | Pause live updates |
+
+Slots:
+
+| Slot | Props | Description |
+|---|---|---|
+| `default` | `{ item, bucket, itemIndex, bucketIndex }` | Render each item |
+| `empty` | – | Shown when there are no items |
+| `loadingTop` / `loadingBottom` | – | Loading spinners |
+| `changedTop` / `changedBottom` | – | Indicators when data changed while frozen |
+
+## Step 4 – Low-level `rangeBuckets` (optional)
+
+For advanced control, use `rangeBuckets` directly:
+
+```javascript
+import { rangeBuckets, reverseRange } from '@live-change/vue3-ssr'
+
+const { buckets, loadBottom, dropTop, freeze, unfreeze } = await rangeBuckets(
+  (range) => path.blog.articlesByCreatedAt({ ...reverseRange(range) }),
+  { bucketSize: 20 }
+)
+```
+
+Iterate in the template:
+
+```vue
+<template v-for="(bucket, bi) in buckets.value" :key="bi">
+  <div v-for="(item, ii) in bucket.data.value" :key="item.id">
+    <!-- render item -->
+  </div>
+</template>
+```