@live-change/frontend-template 0.9.199 → 0.9.201

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

@@ -0,0 +1,129 @@
+---
+name: live-change-frontend-range-list
+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/.claude/skills/live-change-frontend-ssr-setup/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: live-change-frontend-ssr-setup
+description: Set up SSR entry points, router, PrimeVue theme and Suspense data loading
+---
+
+# Skill: live-change-frontend-ssr-setup (Claude Code)
+
+Use this skill to set up or adjust a **LiveChange SSR frontend**:
+
+- client/server entry points,
+- router + `meta.signedIn`,
+- PrimeVue theme configuration.
+
+## Step 1 – Client and server entry points
+
+1. Ensure the frontend has two entry files:
+   - `entry-client.js` (or `.ts`),
+   - `entry-server.js` (or `.ts`).
+
+2. Use helpers from `@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)
+```
+
+## Step 2 – Router and `meta.signedIn`
+
+1. Use `vite-plugin-pages` to auto-generate routes from `src/pages/`.
+2. Add a `<route>` block to each page with basic meta:
+
+```vue
+<route>
+  { "name": "devices", "meta": { "signedIn": true } }
+</route>
+```
+
+3. Add a navigation guard for signed-in pages:
+
+```js
+router.beforeEach((to) => {
+  if(to.meta.signedIn && !isLoggedIn()) {
+    localStorage.setItem('redirectAfterLogin', to.fullPath)
+    return { name: 'user:signIn' }
+  }
+})
+```
+
+Implement `isLoggedIn()` according to the project’s auth/session model.
+
+## Step 3 – PrimeVue theme configuration
+
+1. In `config.js`, configure the PrimeVue theme using `definePreset`:
+
+```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. Ensure the app uses this config when initializing PrimeVue (usually in `App.vue` / main entry).
+
+## Step 4 – Global components and forms
+
+1. In `App.vue` (or main setup), register global components used throughout the app:
+   - auto-form components,
+   - common layout components, etc.
+2. This allows pages to use components like `<command-form>` without local imports.
+
+## Step 5 – SSR-friendly data loading
+
+1. Ensure the root of the app (e.g. `ViewRoot`) wraps content in `<Suspense>`.
+2. In page components:
+   - use `await Promise.all([live(path()....)])` inside `script setup`,
+   - read from `.value` in templates,
+   - **do not** fetch main data in `onMounted`.
+

package/.cursor/rules/live-change-backend-actions-views-triggers.mdc

@@ -58,6 +58,67 @@ definition.action({
   - korzystaj z indeksów (`indexObjectGet`, `indexRangeGet`),
   - nie implementuj skomplikowanej logiki w widokach, jeśli można ją przenieść do akcji.
 
+## Widoki – reguła: `get` + `observable` zawsze razem
+
+Widok musi być dokładnie jednym z trzech wariantów:
+
+- `daoPath` (preferowane) — framework wygeneruje zarówno `get`, jak i `observable`
+- `get` + `observable` — oba wymagane, jeśli źródło danych jest zewnętrzne lub custom-reactive
+- `fetch` — jednorazowy request/response (często `remote: true`), bez reaktywnego strumienia
+
+Nigdy nie definiuj samego `get` bez `observable` ani samego `observable` bez `get`. To psuje użycie reaktywne i może kończyć się błędami w processorach, które owijają oba callbacki (np. access control).
+
+### Poprawnie: `daoPath` zamiast ręcznego `get`/`observable`
+
+```js
+definition.view({
+  name: 'costInvoice',
+  properties: {
+    costInvoice: {
+      type: String
+    }
+  },
+  returns: { type: Object },
+  async daoPath({ costInvoice }) {
+    return CostInvoice.path(costInvoice)
+  }
+})
+```
+
+### Poprawnie: `get` + `observable` razem (zewnętrzne źródło)
+
+```js
+definition.view({
+  name: 'session',
+  properties: {},
+  returns: { type: Number },
+  async get(params, { client }) {
+    return onlineClient.get(['online', 'session', { ...params, session: client.session }])
+  },
+  async observable(params, { client }) {
+    return onlineClient.observable(
+      ['online', 'session', { ...params, session: client.session }],
+      ReactiveDao.ObservableValue
+    )
+  }
+})
+```
+
+### Źle: samo `get` bez `observable`
+
+```js
+definition.view({
+  name: 'brokenView',
+  properties: {
+    id: { type: String }
+  },
+  returns: { type: Object },
+  async get({ id }) {
+    return await SomeModel.get(id)
+  }
+})
+```
+
 ### Wzorzec widoku zakresowego
 
 ```js
@@ -148,6 +209,33 @@ definition.trigger({
 })
 ```
 
+## Change triggers – reakcja na zmiany modeli
+
+Modele z relacjami (`propertyOf`, `itemOf`, `userItem`, itp.) automatycznie odpalają change triggery przy każdym create/update/delete. Konwencja nazw: `{changeType}{ServiceName}_{ModelName}`:
+
+- `changeSvc_Model` — odpala się przy każdej zmianie (rekomendowane, obsługuje wszystkie przypadki)
+- `createSvc_Model` / `updateSvc_Model` / `deleteSvc_Model` — konkretne zdarzenia cyklu życia
+
+Parametry: `{ objectType, object, identifiers, data, oldData, changeType }`.
+
+```js
+// Reaguj na dowolną zmianę modelu Schedule z serwisu cron
+definition.trigger({
+  name: 'changeCron_Schedule',
+  properties: {
+    object: { type: Schedule, validation: ['nonEmpty'] },
+    data: { type: Object },
+    oldData: { type: Object }
+  },
+  async execute({ object, data, oldData }, { triggerService }) {
+    if(oldData) { /* wyczyść stary stan */ }
+    if(data) { /* ustaw nowy stan */ }
+  }
+})
+```
+
+Sprawdzaj `data`/`oldData`: oba obecne = update, tylko `data` = create, tylko `oldData` = delete.
+
 ## Wzorzec „pending + resolve” (asynchroniczny wynik)
 
 - Używaj, gdy akcja w serwisie musi poczekać na wynik z zewnętrznego procesu (np. urządzenie, worker).

package/.cursor/rules/live-change-backend-event-sourcing.mdc

@@ -0,0 +1,185 @@
+---
+description: Event-sourcing data flow rules — emit events for DB writes, use triggerService for cross-service writes
+globs: **/services/**/*.js
+alwaysApply: false
+---
+
+# LiveChange backend – event-sourcing i przepływ danych
+
+## Jak płyną dane w LiveChange
+
+LiveChange stosuje wzorzec event-sourcing:
+
+1. **Akcje i triggery** walidują dane i publikują eventy przez `emit()`.
+2. **Eventy** (`definition.event()`) wykonują faktyczne zapisy do bazy (`Model.create`, `Model.update`, `Model.delete`).
+3. Dla modeli z **relacjami** (`userItem`, `itemOf`, `propertyOf`, itp.) relations plugin auto-generuje eventy i triggery CRUD — używaj ich przez `triggerService()`.
+4. Dla **zapisów między serwisami** zawsze używaj `triggerService()` — `foreignModel` jest tylko do odczytu.
+
+```
+Akcja/Trigger  ──emit()──▶  Event handler  ──▶  Model.create/update/delete
+       │
+       └──triggerService()──▶  Trigger innego serwisu  ──emit()──▶  ...
+```
+
+## Reguła 1: Nie używaj Model.create/update/delete bezpośrednio w akcjach i triggerach
+
+Akcje i triggery **nie powinny** wywoływać `Model.create()`, `Model.update()` ani `Model.delete()` bezpośrednio. Zamiast tego:
+
+- **Jeśli model ma relacje** (auto-generowane CRUD) → użyj `triggerService()` do wywołania triggera relacji (np. `serviceName_createModelName`, `serviceName_updateModelName`, `serviceName_setModelName`).
+- **Jeśli nie ma triggera relacji** → użyj `emit()` do opublikowania eventu, a potem zdefiniuj `definition.event()`, który wykona zapis.
+
+### Poprawnie: emit z akcji
+
+```js
+definition.action({
+  name: 'createImage',
+  properties: { /* ... */ },
+  waitForEvents: true,
+  async execute({ image, name, width, height }, { client, service }, emit) {
+    const id = image || app.generateUid()
+    // walidacja, logika biznesowa...
+    emit({
+      type: 'ImageCreated',
+      image: id,
+      data: { name, width, height }
+    })
+    return id
+  }
+})
+
+definition.event({
+  name: 'ImageCreated',
+  async execute({ image, data }) {
+    await Image.create({ ...data, id: image })
+  }
+})
+```
+
+### Poprawnie: triggerService dla triggerów relacji
+
+```js
+definition.action({
+  name: 'giveCard',
+  properties: { /* ... */ },
+  async execute({ receiverType, receiver }, { client, triggerService }, emit) {
+    // Użyj auto-generowanego triggera z relations plugin
+    await triggerService({
+      service: definition.name,
+      type: 'businessCard_setReceivedCard',
+    }, {
+      sessionOrUserType: receiverType,
+      sessionOrUser: receiver,
+      // ...
+    })
+  }
+})
+```
+
+### Źle: bezpośredni zapis w akcji
+
+```js
+// ❌ NIE RÓB TEGO
+definition.action({
+  name: 'createSomething',
+  async execute({ name }, { client }, emit) {
+    const id = app.generateUid()
+    await Something.create({ id, name })  // ❌ bezpośredni zapis w akcji
+    return id
+  }
+})
+```
+
+## Reguła 2: Eventy mogą modyfikować tylko modele tego samego serwisu
+
+Handlery eventów (`definition.event()`) mogą zapisywać tylko do modeli zdefiniowanych w **tym samym serwisie**. Nie próbuj zapisywać do `foreignModel` — jest tylko do odczytu (`.get()`, `.indexObjectGet()`, `.indexRangeGet()`, ale nie `.create()`, `.update()`, `.delete()`).
+
+Do zapisów między serwisami używaj `triggerService()` z akcji lub triggera:
+
+```js
+// ✅ Poprawnie: zapis między serwisami przez triggerService
+definition.trigger({
+  name: 'chargeCollected_billing_TopUp',
+  async execute(props, { triggerService }, emit) {
+    // Zapis do innego serwisu przez jego zadeklarowany trigger
+    await triggerService({
+      service: 'balance',
+      type: 'balance_setOrUpdateBalance',
+    }, { ownerType: 'billing_Billing', owner: props.cause })
+
+    // Zapis do własnego serwisu przez triggerService (trigger relacji)
+    await triggerService({
+      service: definition.name,
+      type: 'billing_updateTopUp'
+    }, { topUp: props.cause, state: 'paid' })
+  }
+})
+```
+
+```js
+// ❌ NIE RÓB TEGO — foreignModel jest tylko do odczytu
+const ExternalModel = definition.foreignModel('otherService', 'SomeModel')
+
+definition.event({
+  name: 'SomethingHappened',
+  async execute({ id }) {
+    await ExternalModel.update(id, { status: 'done' })  // ❌ nie zadziała
+  }
+})
+```
+
+## `waitForEvents: true`
+
+Gdy akcja lub trigger emituje eventy i musi poczekać na ich przetworzenie przed zwróceniem wyniku, ustaw `waitForEvents: true`:
+
+```js
+definition.action({
+  name: 'createNotification',
+  waitForEvents: true,
+  async execute({ message }, { client }, emit) {
+    const id = app.generateUid()
+    emit({
+      type: 'created',
+      notification: id,
+      data: { message, sessionOrUserType: 'user_User', sessionOrUser: client.user }
+    })
+    return id  // event jest przetworzony zanim to się zwróci
+  }
+})
+```
+
+Bez `waitForEvents: true` akcja zwraca wynik natychmiast, a eventy są przetwarzane asynchronicznie.
+
+## Triggery relacji (auto-generowane)
+
+Gdy model ma relacje (`userItem`, `itemOf`, `propertyOf`, itp.), relations plugin auto-generuje triggery CRUD. Użyj `describe`, żeby je odkryć:
+
+```bash
+node server/start.js describe --service myService --output yaml
+```
+
+Typowe auto-generowane triggery:
+- `serviceName_createModelName` — tworzenie rekordu
+- `serviceName_updateModelName` — aktualizacja rekordu
+- `serviceName_deleteModelName` — usuwanie rekordu
+- `serviceName_setModelName` — upsert (utwórz lub nadpisz)
+- `serviceName_setOrUpdateModelName` — ustaw jeśli nie istnieje, zaktualizuj jeśli istnieje
+
+Wywołuj je przez `triggerService()`:
+
+```js
+await triggerService({
+  service: 'myService',
+  type: 'myService_createMyModel'
+}, {
+  // właściwości pasujące do pól modelu
+})
+```
+
+## Podsumowanie
+
+| Gdzie | Może wywoływać Model.create/update/delete? | Jak zmieniać dane |
+|---|---|---|
+| `definition.event()` | ✅ Tak (tylko modele tego samego serwisu) | Bezpośredni zapis |
+| `definition.action()` | ❌ Nie | `emit()` lub `triggerService()` |
+| `definition.trigger()` | ❌ Nie | `emit()` lub `triggerService()` |
+| Między serwisami | ❌ Nigdy przez foreignModel | `triggerService()` do docelowego serwisu |

package/.cursor/rules/live-change-backend-models-and-relations.mdc

@@ -169,6 +169,68 @@ Zasady:
 - pierwszy argument to nazwa serwisu,
 - drugi to nazwa modelu w tamtym serwisie.
 
+## Automatycznie dodawane pola z relacji
+
+Relacje automatycznie dodają **pola identyfikatorów** i **indeksy** do modelu. **Nie definiuj ich ponownie** w `properties`.
+
+**Konwencja nazw:** nazwa pola = nazwa modelu rodzica z małą pierwszą literą (`Device` → `device`, `CostInvoice` → `costInvoice`).
+
+| Relacja | Dodane pole/pola | Dodane indeksy |
+|---|---|---|
+| `itemOf: { what: Device }` | `device` | `byDevice` |
+| `propertyOf: { what: Device }` | `device` | `byDevice` |
+| `userItem` | `user` | `byUser` |
+| `userProperty` | `user` | `byUser` |
+| `sessionOrUserProperty` | `sessionOrUserType`, `sessionOrUser` | `bySessionOrUser` (hash) |
+| `sessionOrUserProperty: { extendedWith: ['object'] }` | + `objectType`, `object` | indeksy złożone |
+| `propertyOfAny: { ownerTypes: [...] }` | `ownerType`, `owner` | `byOwner` (hash) |
+| `boundTo: { what: Device }` | `device` | `byDevice` (hash) |
+
+Dla relacji z wieloma rodzicami (np. `propertyOf: [{ what: A }, { what: B }]`) tworzone są wszystkie kombinacje indeksów (`byA`, `byB`, `byAAndB`).
+
+## `propertyOfAny` — typy rodzica (`{name}Types`)
+
+`propertyOfAny` jest relacją polimorficzną. Lista dozwolonych typów jest podawana w polach `{name}Types`, gdzie `{name}` pochodzi z `to`.
+
+- Gdy `to` nie jest podane, domyślnie jest `['owner']`, więc użyj `ownerTypes`.
+- Gdy `to: ['invoice']`, użyj `invoiceTypes`.
+
+```js
+// domyślnie to: ['owner']
+propertyOfAny: {
+  ownerTypes: ['invoice_CostInvoice', 'invoice_IncomeInvoice']
+}
+
+// jawnie
+propertyOfAny: {
+  to: ['invoice'],
+  invoiceTypes: ['invoice_CostInvoice', 'invoice_IncomeInvoice']
+}
+```
+
+```js
+// ✅ Poprawnie — definiuj tylko SWOJE pola
+definition.model({
+  name: 'Connection',
+  properties: {
+    status: { type: String }  // 'device' NIE jest tutaj — dodaje go itemOf
+  },
+  itemOf: { what: Device }   // automatycznie dodaje pole 'device' + indeks 'byDevice'
+})
+
+// ❌ Źle — redundantne pole
+definition.model({
+  name: 'Connection',
+  properties: {
+    device: { type: String },  // ❌ już dodane przez itemOf
+    status: { type: String }
+  },
+  itemOf: { what: Device }
+})
+```
+
+Użyj `node server/start.js describe --service myService --model MyModel --output yaml` żeby zobaczyć wszystkie pola łącznie z automatycznie dodanymi.
+
 ## Indeksy
 
 - Definiuj indeksy jawnie w modelu, gdy będziesz często wyszukiwać po danym polu lub kombinacji pól.