@live-change/frontend-template 0.9.197 → 0.9.199

package/.cursor/skills/live-change-design-models-relations.md

@@ -0,0 +1,168 @@
+---
+description: Design models with userItem, itemOf, propertyOf relations and access control
+---
+
+# Skill: live-change-design-models-relations
+
+Ten skill opisuje **krok po kroku**, jak projektować modele i relacje (`userItem`, `itemOf`, `propertyOf`, `foreignModel`) w serwisach LiveChange.
+
+## Kiedy używać
+
+Użyj tego skilla, gdy:
+
+- dodajesz nowy model do serwisu,
+- przenosisz dane z ręcznego CRUD na relacje,
+- potrzebujesz spójnego wzorca dla access control i indeksów.
+
+## 1. Dobierz typ relacji
+
+Zastanów się, jak model jest powiązany z resztą domeny:
+
+- **`userItem`** – obiekt należy do zalogowanego użytkownika (np. konto, urządzenie użytkownika).
+- **`itemOf`** – lista elementów należy do innego modelu (np. połączenia urządzenia, pozycje zamówienia).
+- **`propertyOf`** – pojedyncza właściwość/model ze stanem o ID równym rodzicowi (np. stan kursora, ustawienia).
+- **bez relacji** – gdy obiekt jest globalny lub ma inną strukturę (np. globalny config).
+
+Wybierz jedną główną relację na model – dodatkowe powiązania możesz odzwierciedlić polami i indeksami.
+
+## 2. Zdefiniuj `properties` w czytelny sposób
+
+1. Utwórz sekcję `properties`:
+   - każdą właściwość zapisuj wieloliniowo,
+   - jasno określ typ, domyślne wartości, walidację.
+
+2. Przykład:
+
+```js
+properties: {
+  name: {
+    type: String,
+    validation: ['nonEmpty']
+  },
+  status: {
+    type: String,
+    default: 'offline'
+  },
+  capabilities: {
+    type: Array,
+    of: {
+      type: String
+    }
+  }
+}
+```
+
+## 3. Skonfiguruj relację
+
+### `userItem`
+
+1. Dodaj blok `userItem` w definicji modelu.
+2. Ustaw role dla odczytu i zapisu.
+3. Ogranicz `writeableProperties` do pól, które użytkownik może zmieniać.
+
+```js
+userItem: {
+  readAccessControl: { roles: ['owner', 'admin'] },
+  writeAccessControl: { roles: ['owner', 'admin'] },
+  writeableProperties: ['name']
+}
+```
+
+### `itemOf`
+
+1. Ustal model rodzica (`what`).
+2. W razie potrzeby użyj `definition.foreignModel`, jeśli rodzic jest w innym serwisie.
+
+```js
+itemOf: {
+  what: Device,
+  readAccessControl: { roles: ['owner', 'admin'] },
+  writeAccessControl: { roles: ['owner', 'admin'] }
+}
+```
+
+### `propertyOf`
+
+1. Użyj, gdy chcesz, żeby ID modelu = ID rodzica.
+2. To ułatwia odczyt (`Model.get(parentId)`).
+
+```js
+propertyOf: {
+  what: Device,
+  readAccessControl: { roles: ['owner', 'admin'] },
+  writeAccessControl: { roles: ['owner', 'admin'] }
+}
+```
+
+### `propertyOf` z wieloma rodzicami (1:1 relacja do wielu encji)
+
+Użyj, gdy model ma być „łącznikiem 1:1” pomiędzy kilkoma encjami (np. faktura ↔ kontrahent w konkretnej roli),
+żeby generator relacji/CRUD rozumiał, że to jest relacja, a nie pole `someId` w `properties`.
+
+Uwagi:
+
+- Najczęściej jest to 1 lub 2 rodziców, ale lista `propertyOf` może zawierać **dowolnie wiele** modeli (np. relacja łącząca 3+ encje).
+- Jeśli encja jest relacją, **nie dodawaj ręcznie** pól typu `...Id` w `properties` tylko po to, żeby “zrobić join” – generator CRUD nie potraktuje tego jako relacji.
+
+Przykład:
+
+```js
+const CostInvoice = definition.foreignModel('invoice', 'CostInvoice')
+const Contractor = definition.foreignModel('company', 'Contractor')
+
+definition.model({
+  name: 'Supplier',
+  properties: {
+    // opcjonalne pola dodatkowe
+  },
+  propertyOf: [
+    { what: CostInvoice },
+    { what: Contractor }
+  ]
+})
+```
+
+### `foreignModel`
+
+1. Na początku pliku z modelem zadeklaruj:
+
+```js
+const Device = definition.foreignModel('deviceManager', 'Device')
+```
+
+2. Potem używaj `Device` w `itemOf`/`propertyOf`.
+
+## 4. Dodaj indeksy
+
+1. Zidentyfikuj typowe zapytania (np. po `sessionKey`, po `(device, status)`).
+2. Dodaj sekcję `indexes`:
+
+```js
+indexes: {
+  bySessionKey: {
+    property: ['sessionKey']
+  },
+  byDeviceAndStatus: {
+    property: ['device', 'status']
+  }
+}
+```
+
+3. Używaj tych indeksów w widokach i akcjach (`indexObjectGet`, `indexRangeGet`).
+
+## 5. Ustal access control na poziomie modelu/relacji
+
+1. Dla `userItem` / `itemOf` / `propertyOf` ustaw zawsze:
+   - `readAccessControl`,
+   - `writeAccessControl`.
+
+2. Nie zakładaj domyślnych reguł – wpisz je wprost w definicji modelu.
+
+## 6. Sprawdź wygenerowane widoki/akcje
+
+Po dodaniu relacji:
+
+1. Sprawdź, jakie widoki/akcje generuje plugin (np. `myUserDevices`, `createMyUserDevice`, itp.).
+2. Zastanów się, czy potrzebujesz dodatkowych, niestandardowych widoków/akcji:
+   - jeśli tak, dodaj je, ale **nie duplikuj** tego, co generuje relacja.
+

package/.cursor/skills/live-change-design-service.md

@@ -0,0 +1,75 @@
+---
+description: Create or restructure a LiveChange backend service with proper directory layout
+---
+
+# Skill: live-change-design-service
+
+Ten skill opisuje **krok po kroku**, jak zaprojektować nowy serwis w LiveChange / live-change-stack albo sensownie rozbudować istniejący.
+
+## Kiedy używać
+
+Użyj tego skilla, gdy:
+
+- dodajesz **nowy serwis domenowy** do projektu,
+- przenosisz większy kawałek logiki z innego serwisu,
+- potrzebujesz upewnić się, że struktura plików i rejestracja serwisu są zgodne z konwencją.
+
+## Kroki – nowy serwis
+
+1. **Nazwij serwis**
+   - Wybierz zwięzłą, domenową nazwę, np. `payments`, `notifications`, `deviceManager`.
+   - Nazwa będzie używana jako `name` w `createServiceDefinition` oraz w `app.config.js`.
+
+2. **Utwórz katalog serwisu**
+   - Ścieżka: `server/services/<serviceName>/`.
+   - W katalogu utwórz pliki:
+     - `definition.js`
+     - `index.js`
+     - opcjonalnie `config.js`
+     - pliki domenowe (np. `models.js`, `authenticator.js`, `actions.js`), jeśli potrzebne.
+
+3. **Zaimplementuj `definition.js`**
+   - Importuj `app` z `@live-change/framework`.
+   - Jeśli serwis korzysta z relacji lub access control:
+     - importuj `relationsPlugin` z `@live-change/relations-plugin`,
+     - importuj `accessControlService` z `@live-change/access-control-service`.
+   - Wywołaj `app.createServiceDefinition({ name, use })`.
+   - **Nie** deklaruj tu modeli, akcji ani widoków.
+
+4. **Zaimplementuj `index.js`**
+   - Importuj `definition` z `./definition.js`.
+   - Importuj wszystkie pliki domenowe (np. `./models.js`, `./authenticator.js`).
+   - Eksportuj `definition` jako `default`.
+   - Nie dodawaj innej logiki do `index.js`.
+
+5. **(Opcjonalnie) utwórz `config.js`**
+   - Importuj `definition`.
+   - Odczytaj `definition.config` i rozwiąż wartości domyślne.
+   - Eksportuj plain object z konfiguracją serwisu.
+
+6. **Dodaj serwis do `services.list.js`**
+   - Importuj z katalogu serwisu, nie z pojedynczego pliku.
+   - Dodaj serwis do eksportowanego obiektu.
+
+7. **Dodaj serwis do `app.config.js`**
+   - W sekcji `services` dodaj `{ name: '<serviceName>' }`.
+   - Upewnij się, że kolejność jest sensowna:
+     - serwisy bazowe/plugins (user, session, accessControl) na początku,
+     - serwisy domenowe zależne od nich – dalej.
+
+8. **Sprawdź zależności**
+   - Jeśli serwis korzysta z modeli w innych serwisach:
+     - użyj `definition.foreignModel` wewnątrz domenowych plików serwisu,
+     - nie importuj bezpośrednio ich plików modeli.
+   - Upewnij się, że serwisy, od których zależysz, są wcześniejsze w `app.config.js`.
+
+## Kroki – rozbudowa istniejącego serwisu
+
+1. Przejrzyj istniejący katalog `server/services/<serviceName>/`.
+2. Sprawdź, czy `definition.js` ma poprawne `use` (relacje, accessControl).
+3. Nowe modele/akcje/widoki/triggery dodaj do **osobnych plików domenowych**:
+   - jeśli logika jest powiązana z istniejącym modelem – do jego pliku,
+   - jeśli tworzysz większy nowy obszar – do nowego pliku (np. `notifications.js`).
+4. Upewnij się, że nowy plik jest importowany w `index.js`.
+5. Nie dodawaj ciężkiej logiki do `definition.js` ani `index.js`.
+

package/.cursor/skills/live-change-frontend-action-buttons.md

@@ -0,0 +1,128 @@
+---
+description: Build async action buttons with workingZone, toast and confirm dialogs
+---
+
+# Skill: live-change-frontend-action-buttons (Claude Code)
+
+Use this skill when you build **buttons that trigger async actions** outside of forms, using `workingZone`, `toast`, and optionally `confirm`.
+
+## When to use
+
+- A button triggers a backend action (delete, approve, toggle, etc.) — **no form fields**.
+- You want the global loading spinner to appear while the action runs.
+- Destructive actions need a confirmation dialog before executing.
+
+**Need a form with fields?** Use `editorData` (model editing) or `actionData` (one-shot actions) instead.
+
+## Step 1 – Inject workingZone, set up toast/confirm
+
+```javascript
+import { inject } from 'vue'
+import { useToast } from 'primevue/usetoast'
+import { useConfirm } from 'primevue/useconfirm'
+import { useApi, useActions } from '@live-change/vue3-ssr'
+
+const workingZone = inject('workingZone')
+const toast = useToast()
+const confirm = useConfirm()
+const api = useApi()
+const actions = useActions()
+```
+
+`workingZone` is provided by `ViewRoot` (which wraps every page in `<WorkingZone>`). When you call `workingZone.addPromise(name, promise)`, the global spinner/blur activates until the promise resolves.
+
+## Step 2 – Simple action button
+
+Wrap the async operation in `workingZone.addPromise()`:
+
+```javascript
+function createItem() {
+  workingZone.addPromise('createItem', (async () => {
+    const result = await actions.blog.createArticle({})
+    toast.add({ severity: 'success', summary: 'Article created', life: 2000 })
+    router.push({ name: 'article:edit', params: { article: result } })
+  })())
+}
+```
+
+**Important:** Note the `(async () => { ... })()` pattern – you must invoke the async IIFE immediately so `addPromise` receives a Promise, not a function.
+
+Template:
+
+```vue
+<Button label="Create article" icon="pi pi-plus" @click="createItem" />
+```
+
+## Step 3 – Destructive action with confirm
+
+Use `confirm.require()` before the action:
+
+```javascript
+function deleteItem(item) {
+  confirm.require({
+    message: 'Are you sure you want to delete this article?',
+    header: 'Confirmation',
+    icon: 'pi pi-trash',
+    acceptClass: 'p-button-danger',
+    accept: async () => {
+      workingZone.addPromise('deleteArticle', (async () => {
+        await actions.blog.deleteArticle({ article: item.id })
+        toast.add({ severity: 'success', summary: 'Deleted', life: 2000 })
+      })())
+    },
+    reject: () => {
+      toast.add({ severity: 'info', summary: 'Cancelled', life: 1500 })
+    }
+  })
+}
+```
+
+Template:
+
+```vue
+<Button label="Delete" icon="pi pi-trash" severity="danger" @click="deleteItem(article)" />
+```
+
+## Step 4 – Error handling
+
+Add try/catch inside the async IIFE:
+
+```javascript
+function toggleStatus(item) {
+  workingZone.addPromise('toggleStatus', (async () => {
+    try {
+      await actions.blog.toggleArticleStatus({ article: item.id })
+      toast.add({ severity: 'success', summary: 'Status updated', life: 2000 })
+    } catch(e) {
+      toast.add({ severity: 'error', summary: 'Error', detail: e?.message ?? e, life: 5000 })
+    }
+  })())
+}
+```
+
+## Step 5 – Using api.command instead of actions
+
+Both work. `actions` is shorthand for typed service actions:
+
+```javascript
+// Using actions (preferred when available):
+await actions.blog.deleteArticle({ article: id })
+
+// Using api.command (always works):
+await api.command(['blog', 'deleteArticle'], { article: id })
+```
+
+## Pattern summary
+
+```
+Button click
+  → confirm.require() (if destructive)
+    → workingZone.addPromise('name', (async () => {
+        try {
+          await actions.service.action({ ... })
+          toast.add({ severity: 'success', ... })
+        } catch(e) {
+          toast.add({ severity: 'error', ... })
+        }
+      })())
+```

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

@@ -0,0 +1,143 @@
+---
+description: Build one-shot action forms with actionData, AutoField and ActionButtons
+---
+
+# Skill: live-change-frontend-action-form (Claude Code)
+
+Use this skill when you build **one-shot action forms** with `actionData` and `AutoField` in a LiveChange frontend.
+
+## When to use
+
+- You need a form for a command/action (not CRUD model editing).
+- The form submits once, then shows a "done" state.
+- You want draft auto-save while the user fills in the form.
+
+**Editing a model record instead?** Use `editorData` (see `live-change-frontend-editor-form` skill).
+**No form fields, just a button?** Use `api.command` (see `live-change-frontend-command-forms` skill).
+
+## Step 1 – Set up actionData
+
+```javascript
+import { AutoField, actionData, ActionButtons } from '@live-change/frontend-auto-form'
+
+const formData = await actionData({
+  service: 'blog',
+  action: 'publishArticle',
+  parameters: { article: props.articleId },   // fixed params (not shown as fields)
+  initialValue: { scheduleTime: null },       // initial values for editable fields
+  draft: true,
+  doneToast: 'Article published!',
+  onDone: (result) => {
+    router.push({ name: 'articles' })
+  },
+})
+```
+
+For reactive parameters, use `computedAsync`:
+
+```javascript
+import { computedAsync } from '@vueuse/core'
+
+const formData = computedAsync(() =>
+  actionData({
+    service: 'blog',
+    action: 'publishArticle',
+    parameters: { article: props.articleId },
+  })
+)
+```
+
+## Step 2 – Build the template with AutoField
+
+Use `formData.action.properties.*` as definitions and `formData.value.*` as v-model:
+
+```vue
+<template>
+  <form @submit.prevent="formData.submit()" @reset.prevent="formData.reset()">
+    <AutoField
+      :definition="formData.action.properties.scheduleTime"
+      v-model="formData.value.scheduleTime"
+      :error="formData.propertiesErrors?.scheduleTime"
+      label="Schedule time"
+    />
+    <AutoField
+      :definition="formData.action.properties.message"
+      v-model="formData.value.message"
+      :error="formData.propertiesErrors?.message"
+      label="Message"
+    />
+
+    <ActionButtons :actionFormData="formData" :resetButton="true" />
+  </form>
+</template>
+```
+
+## Step 3 – Handle done state
+
+After successful submission, `formData.done` becomes `true`:
+
+```vue
+<template>
+  <div v-if="formData.done" class="text-center">
+    <i class="pi pi-check-circle text-4xl text-green-500 mb-2"></i>
+    <p>Article published successfully!</p>
+  </div>
+  <form v-else @submit.prevent="formData.submit()" @reset.prevent="formData.reset()">
+    <!-- fields + ActionButtons -->
+  </form>
+</template>
+```
+
+## Step 4 – Manual buttons (alternative to ActionButtons)
+
+```vue
+<div class="flex gap-2 justify-end">
+  <Button
+    type="submit"
+    :label="formData.submitting ? 'Executing...' : 'Execute'"
+    :icon="formData.submitting ? 'pi pi-spin pi-spinner' : 'pi pi-play'"
+    :disabled="formData.submitting"
+  />
+  <Button type="reset" label="Reset" :disabled="!formData.changed" icon="pi pi-eraser" />
+</div>
+```
+
+## editorData vs actionData
+
+| Aspect | `editorData` | `actionData` |
+|---|---|---|
+| Purpose | CRUD model editing | One-shot command form |
+| Identifier | `model` + `identifiers` | `action` + `parameters` |
+| Create/update | Detects automatically | Always "execute" |
+| After submit | Record is saved | `done` becomes `true` |
+| Definition source | `editor.model` | `formData.action` |
+| `parameters` | Extra params on save | Fixed fields excluded from form |
+
+## Key options
+
+| Option | Default | Description |
+|---|---|---|
+| `service` | required | Service name |
+| `action` | required | Action name |
+| `parameters` | `{}` | Fixed identifier fields (not editable) |
+| `initialValue` | `{}` | Initial values for editable fields |
+| `draft` | `true` | Auto-save draft while filling |
+| `debounce` | `600` | Debounce delay in ms |
+| `doneToast` | `"Action done"` | Toast after success |
+| `onDone` | – | Callback after success |
+
+## Key returned properties
+
+| Property | Description |
+|---|---|
+| `value` | Editable form data |
+| `action` | Action definition (`.properties.*` for `AutoField`) |
+| `editableProperties` | Properties not fixed by `parameters` |
+| `changed` | Form differs from initial value |
+| `submit()` | Execute the action |
+| `submitting` | Action call in progress |
+| `done` | `true` after success |
+| `reset()` | Discard draft, restore initial value |
+| `propertiesErrors` | Server validation errors per property |
+| `draftChanged` | Draft auto-saved but not submitted |
+| `savingDraft` | Draft auto-save in progress |

package/.cursor/skills/live-change-frontend-analytics.md

@@ -0,0 +1,146 @@
+---
+description: Integrate analytics tracking with analytics.emit and provider wiring
+---
+
+# Skill: live-change-frontend-analytics (Claude Code)
+
+Use this skill when you add **analytics tracking** to a LiveChange frontend.
+
+## When to use
+
+- You need to track user actions, page views, or custom events.
+- You are integrating PostHog, GA4, or another analytics provider.
+- You need consent-aware analytics.
+
+## Step 1 – Emit events with `analytics`
+
+Import `analytics` from `@live-change/vue3-components` and emit events:
+
+```javascript
+import { analytics } from '@live-change/vue3-components'
+
+// In a component or handler:
+analytics.emit('article:published', { articleId: article.id })
+analytics.emit('button:clicked', { action: 'delete', target: 'article' })
+```
+
+Standard built-in events:
+
+| Event | Payload | When emitted |
+|---|---|---|
+| `pageView` | route `to` object | On route change (automatic in App.vue) |
+| `user:identification` | `{ user, session, identification, contacts }` | When user identity is known |
+| `consent` | `{ analytics: boolean }` | When user grants/denies tracking consent |
+| `locale:change` | locale settings object | When language/locale changes |
+
+## Step 2 – Wire user identification in App.vue
+
+Emit `user:identification` when the user profile is loaded:
+
+```javascript
+import { analytics } from '@live-change/vue3-components'
+import { usePath, live, useClient } from '@live-change/vue3-ssr'
+import { computed, watch } from 'vue'
+
+const client = useClient()
+const path = usePath()
+
+if(typeof window !== 'undefined') {
+  Promise.all([
+    live(path.userIdentification.myIdentification()),
+  ]).then(([identification]) => {
+    const fullIdentification = computed(() => ({
+      user: client.value.user,
+      session: client.value.session,
+      identification: identification.value,
+    }))
+    watch(fullIdentification, (newId) => {
+      analytics.emit('user:identification', newId)
+    }, { immediate: true })
+  })
+}
+```
+
+## Step 3 – Create a provider file (e.g. PostHog)
+
+Create a file like `src/analytics/posthog.js`:
+
+```javascript
+import { analytics } from '@live-change/vue3-components'
+import posthog from 'posthog-js'
+
+posthog.init('phc_YOUR_KEY', {
+  api_host: 'https://eu.i.posthog.com',
+  person_profiles: 'always'
+})
+
+// Page views
+analytics.on('pageView', (to) => {
+  posthog.register({
+    route: { name: to.name, params: to.params }
+  })
+})
+
+// User identification
+analytics.on('user:identification', (identification) => {
+  if (!identification.user) {
+    posthog.reset()
+    return
+  }
+  posthog.identify(identification.user, {
+    firstName: identification.identification?.firstName,
+    lastName: identification.identification?.lastName,
+  })
+})
+
+// Consent
+analytics.on('consent', (payload) => {
+  if (payload?.analytics === true) {
+    posthog.opt_in_capturing()
+  } else {
+    posthog.opt_out_capturing()
+  }
+})
+
+// Catch-all for custom events
+const ignored = ['user:identification', 'pageView', 'consent']
+analytics.on('*', (type, event) => {
+  if (ignored.includes(type)) return
+  posthog.capture(type, event)
+})
+```
+
+Import it in `App.vue`:
+
+```javascript
+import './analytics/posthog'
+```
+
+## Step 4 – Emit custom events in components
+
+```javascript
+// Track a form submission
+analytics.emit('form:submitted', { formName: 'contactForm' })
+
+// Track a feature usage
+analytics.emit('feature:used', { feature: 'darkMode', enabled: true })
+
+// Track navigation
+analytics.emit('navigation:click', { target: 'pricing', source: 'navbar' })
+```
+
+## Step 5 – Consent handling
+
+Emit consent events from your consent banner:
+
+```javascript
+function acceptAnalytics() {
+  analytics.emit('consent', { analytics: true })
+}
+
+function rejectAnalytics() {
+  analytics.emit('consent', { analytics: false })
+}
+```
+
+Provider files listen for `consent` and enable/disable tracking accordingly.