@live-change/frontend-template 0.9.197 → 0.9.199

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

package/.cursor/skills/live-change-frontend-ssr-setup.md

@@ -0,0 +1,119 @@
+---
+description: Set up SSR entry points, router, PrimeVue theme and Suspense data loading
+---
+
+# Skill: live-change-frontend-ssr-setup
+
+Ten skill opisuje **konfigurację frontendu** opartego o live-change-stack:
+
+- entry-client / entry-server,
+- router i meta `signedIn`,
+- konfigurację PrimeVue / motywu.
+
+## 1. Entry points – klient i serwer
+
+1. W projekcie frontendowym upewnij się, że masz dwa entry points:
+   - `entry-client.js` (lub `.ts`),
+   - `entry-server.js` (lub `.ts`).
+
+2. Skorzystaj z helperów z `@live-change/frontend-base`:
+
+```js
+// entry-client.js
+import { clientEntry } from '@live-change/frontend-base/client-entry.js'
+import App from './App.vue'
+import { createRouter } from './router.js'
+import { config } from './config.js'
+
+export default clientEntry(App, createRouter, config)
+```
+
+```js
+// entry-server.js
+import { serverEntry, sitemapEntry } from '@live-change/frontend-base/server-entry.js'
+import App from './App.vue'
+import { createRouter, routerSitemap } from './router.js'
+import { config } from './config.js'
+
+export const render = serverEntry(App, createRouter, config)
+export const sitemap = sitemapEntry(App, createRouter, routerSitemap, config)
+```
+
+## 2. Router – `vite-plugin-pages` + meta `signedIn`
+
+1. Użyj `vite-plugin-pages` do generowania tras z `src/pages/`.
+2. Dodaj blok `<route>` w plikach stron, np.:
+
+```vue
+<route>
+  { "name": "devices", "meta": { "signedIn": true } }
+</route>
+```
+
+3. W routerze dodaj guard logowania (jeśli go nie ma):
+
+```js
+router.beforeEach((to) => {
+  if(to.meta.signedIn && !isLoggedIn()) {
+    localStorage.setItem('redirectAfterLogin', to.fullPath)
+    return { name: 'user:signIn' }
+  }
+})
+```
+
+Funkcja `isLoggedIn()` może opierać się na stanie sesji/usera w store lub prostym sprawdzeniu tokena/ciasteczek.
+
+## 3. Konfiguracja PrimeVue – motyw i opcje
+
+1. W pliku `config.js` skonfiguruj PrimeVue:
+
+```js
+import { definePreset } from '@primevue/themes'
+import Aura from '@primevue/themes/aura'
+
+const MyPreset = definePreset(Aura, {
+  semantic: {
+    primary: {
+      50: '{indigo.50}',
+      100: '{indigo.100}',
+      200: '{indigo.200}',
+      300: '{indigo.300}',
+      400: '{indigo.400}',
+      500: '{indigo.500}',
+      600: '{indigo.600}',
+      700: '{indigo.700}',
+      800: '{indigo.800}',
+      900: '{indigo.900}',
+      950: '{indigo.950}'
+    }
+  }
+})
+
+export const config = {
+  theme: {
+    preset: MyPreset,
+    options: {
+      darkModeSelector: '.app-dark-mode'
+    }
+  }
+}
+```
+
+2. Upewnij się, że App.vue używa tego configu przez globalną konfigurację PrimeVue (zgodnie z template’em live-change-stack).
+
+## 4. Globalne komponenty i formularze
+
+1. W `App.vue` zarejestruj globalne komponenty używane często w projekcie:
+   - auto-form components,
+   - globalne layouty, jeśli są.
+
+2. Dzięki temu na stronach używasz np. `<command-form>` bez lokalnego importu.
+
+## 5. SSR i `live/path` + Suspense
+
+1. Upewnij się, że root aplikacji (np. `ViewRoot`) opakowuje strony w `<Suspense>`.
+2. Strony powinny:
+   - używać `await Promise.all([live(path()....)])` w `script setup`,
+   - korzystać z `.value` w template,
+   - nie wykonywać pobierania danych w `onMounted`.
+

package/README.md

@@ -0,0 +1,71 @@
+---
+title: @live-change/frontend-template
+---
+
+## @live-change/frontend-template
+
+`@live-change/frontend-template` to **szablon kompletnej aplikacji frontendowej** Live Change:
+
+- gotowy SSR + SPA oparty o `@live-change/frontend-base` i `@live-change/vue3-ssr`
+- zintegrowane moduły: `user-frontend`, `security`, `content`, `blog`, `task`, `upload`, `url`, `video-call`, `peer-connection`, `auto-form` i inne
+- standardowa struktura katalogów i skrypty `package.json`
+
+Szablon jest punktem startowym dla nowych projektów (np. `family-tree`, `speed-dating` zostały na nim oparte).
+
+### Najważniejsze zależności
+
+W `package.json` szablonu znajdziesz m.in.:
+
+- `@live-change/frontend-base`
+- `@live-change/frontend-auto-form`
+- `@live-change/vue3-components`
+- `@live-change/vue3-ssr`
+- frontendy: `user-frontend`, `access-control-frontend`, `content-frontend`, `image-frontend`, `task-frontend`, `upload-frontend`, `url-frontend`, `wysiwyg-frontend`, `blog-frontend`, `video-call-frontend`, `peer-connection-frontend`
+
+### Skrypty uruchomieniowe
+
+Typowe skrypty (uproszczony przegląd):
+
+- `memDev` / `localDev` / `dev` – tryby deweloperskie z różną konfiguracją DB
+- `ssrDev` – dev SSR
+- `serveAll` / `serveAllMem` – produkcyjny SSR z API i usługami
+- `apiServer`, `devApiServer`, `memApiServer` – warianty samego API
+- `build`, `build:client`, `build:ssr`, `build:server`, `build:spa` – budowanie frontu i serwera
+- `prerender*` – generowanie statycznych stron
+
+Są one spójne z opisem w dokumentacji serwera (`server/01-getting-started.md`).
+
+### Struktura projektu na bazie szablonu
+
+Typowy projekt zaczynający z `frontend-template` ma:
+
+- `server/app.config.js` – lista usług i konfiguracja klienta
+- `server/services.list.js` – eksport definicji usług
+- `server/start.js` – start CLI (opisany w dokumentacji serwera)
+- `front/src` – kod frontendu:
+  - `App.vue`
+  - `router.js`
+  - `config.js` (i18n, tematy, integracje)
+  - `pages/*` – strony routingu (`vite-plugin-pages`)
+  - `components/*` – komponenty wspólne
+
+W `front/src/config.js` łączysz lokalizacje `frontend-base`, `frontend-auto-form` i innych modułów, podobnie jak w:
+
+- `family-tree/front/src/config.js`
+- `speed-dating/front/src/config.js`
+
+### Praca z szablonem
+
+Typowy flow tworzenia nowej aplikacji:
+
+1. Tworzysz nowy pakiet oparty o `@live-change/frontend-template` (lub kopiujesz repo).
+2. Aktualizujesz `server/app.config.js` i `server/services.list.js`, aby włączyć tylko potrzebne usługi.
+3. Dostosowujesz `front/src/config.js` (temat, i18n, integracje analityki).
+4. Tworzysz nowe strony w `front/src/pages` oraz komponenty w `front/src/components`.
+5. Korzystasz z:
+   - `@live-change/vue3-ssr` do pracy z DAO,
+   - `@live-change/vue3-components` do logiki i formularzy,
+   - `@live-change/frontend-auto-form` do CRUD-ów.
+
+Dokładny „manual” tego flow znajdzie się w sekcji `frontend/01-getting-started.md` dokumentacji.
+