@stonecrop/desktop 0.16.6 → 0.17.0

package/README.md

@@ -1,6 +1,8 @@
 # @stonecrop/desktop
 
-A three-view UI shell for Stonecrop applications. Renders a doctype list → records list → record form layout driven entirely by the host application's Registry and HST state. Desktop owns no data lifecycle — it emits events and the host app decides what to do.
+A three-view UI shell for Stonecrop applications. Renders a doctype list → records list → record form layout driven by the host application's Registry and HST state.
+
+Desktop reads through Stonecrop — on navigating to a list or a record it calls `Stonecrop.getRecords` / `Stonecrop.getRecord`, which fetch through the host's registered `DataClient` and write into HST. Writes are the host's: Desktop emits `action` and the host dispatches it.
 
 ## Features
 
@@ -20,32 +22,42 @@ Desktop requires `@stonecrop/stonecrop` to be installed and the `StonecropPlugin
 
 ```typescript
 import { createApp } from 'vue'
-import Stonecrop from '@stonecrop/stonecrop'
-import { registry } from './registry'
+import Stonecrop, { Doctype } from '@stonecrop/stonecrop'
+import { RestDataClient } from './client'
+import planDoctype from './doctypes/plan.json'
+
+const app = createApp(App)
+
+// The plugin constructs the Registry itself and provides it as `$registry` — it does not
+// accept one. Register doctypes on that instance, after install.
+app.use(Stonecrop, { router, client: new RestDataClient() })
+
+const registry = app.config.globalProperties.$registry
+registry.addDoctype(Doctype.fromObject(planDoctype))
 
-createApp(App).use(Stonecrop, { registry }).mount('#app')
+app.mount('#app')
 ```
 
+`client` is the `DataClient` Desktop reads through. It can also be supplied later with
+`stonecrop.setClient(client)` — Nuxt hosts do this from a plugin via `useStonecropSetup().registerClient`.
+
 ## Basic Usage
 
 ```vue
 <script setup lang="ts">
 import { Desktop } from '@stonecrop/desktop'
-import type { ActionEventPayload } from '@stonecrop/desktop'
-import { useStonecrop } from '@stonecrop/stonecrop'
-
-const { stonecrop } = useStonecrop()
+import { useClientAction } from '@stonecrop/stonecrop'
 
-async function handleAction(payload: ActionEventPayload) {
-  const node = stonecrop.value?.getRecordById(payload.doctype, payload.recordId)
-  await node?.triggerTransition(payload.name, { fsmContext: payload.data })
-}
+// Runs an action's clientHandler when the doctype declares one, dispatches to the server
+// otherwise, and reconciles the store and the route with the identity the server settled on.
+// In a Nuxt host this is auto-imported — drop the import line.
+const { run } = useClientAction()
 </script>
 
 <template>
   <Desktop
     :available-doctypes="['plan', 'recipe', 'resource']"
-    @action="handleAction"
+    @action="run"
   />
 </template>
 ```
@@ -56,25 +68,27 @@ async function handleAction(payload: ActionEventPayload) {
 |------|------|---------|-------------|
 | `availableDoctypes` | `string[]` | `[]` | Doctype slugs to display in the doctypes list |
 | `routeAdapter` | `RouteAdapter` | — | Custom routing layer (required for Nuxt/custom hosts) |
-| `confirmFn` | `(msg: string) => boolean \| Promise<boolean>` | `window.confirm` | Replacement for the native browser confirm dialog |
-| `recordIdField` | `string` | `'id'` | Field name for the canonical record ID in list views |
+
+Record identity is not a prop. It is declared per doctype (`primaryKey`, falling back to `id`) and
+resolved through `Doctype.getRecordId`, so a row's link always matches the key the record is stored
+under. One shell renders many doctypes, so a single prop could never answer this correctly.
 
 ## Emitted Events
 
 | Event | When |
 |-------|------|
-| `action` | User triggers an FSM transition or DELETE |
+| `action` | User triggers a declared action — an FSM transition or a Command |
 | `navigate` | Desktop wants to change views |
 | `record:open` | User opens a specific record |
-| `load-records` | Desktop navigates to a records list and needs records loaded into HST |
-| `load-record` | Desktop navigates to a record form and needs a single record loaded into HST |
+| `load-records` | Desktop is about to read a records list (notification — Desktop performs the read) |
+| `load-record` | Desktop is about to read a single record (notification — Desktop performs the read) |
 
 See [api.md](./api.md) for payload type definitions.
 
 ### Event Handling Notes
 
-- **action**: Desktop reads available transitions from `Doctype.getAvailableTransitions` using `Stonecrop.getRecordState`. **Desktop never calls `triggerTransition` itself** — that is the host application's responsibility.
-- **load-records / load-record**: Desktop reads from HST but doesn't fetch data. Host apps should listen for these events, fetch from their data source, and call `stonecrop.addRecords()` or `stonecrop.addRecord()` to populate HST.
+- **action**: Desktop merges `Doctype.getAvailableTransitions` and `Doctype.getAvailableCommands`, both resolved against `Stonecrop.getRecordState`, into one Actions dropdown. **Desktop never dispatches** — that is the host application's responsibility.
+- **load-records / load-record**: notifications, not fetch requests. Desktop reads through `Stonecrop.getRecords` / `Stonecrop.getRecord` itself, using the registered `DataClient`; these events announce that read so a host can hang analytics off it. A host that fetches here races Desktop's own read into the same HST key. `load-record` is not emitted for a draft, which has nothing to fetch.
 
 ## Router Adapter
 
@@ -111,37 +125,36 @@ function useCustomRouteAdapter(): RouteAdapter {
 
 ## Handling `action` Events
 
-The complete host-side pattern for handling an action in a Nuxt context:
+Dispatching is not the whole job: the result has to land in HST under the identity the *server*
+settled on, which for a newly created record is not the id that was dispatched.
 
-```typescript
-import type { ActionEventPayload } from '@stonecrop/desktop'
-import { useStonecrop } from '@stonecrop/stonecrop'
+Bind `@action` to `useClientAction`'s `run`, as in Basic Usage above. It runs an action's
+`clientHandler` when it has one, dispatches otherwise, and reconciles the store and the route. It
+lives in `@stonecrop/stonecrop`, so every Vue 3 host gets the same one; Nuxt hosts also get it as an
+auto-import from `@stonecrop/nuxt`.
 
-const { stonecrop } = useStonecrop()
+Three things are adjustable, for the cases that genuinely differ between applications:
 
-async function handleAction(payload: ActionEventPayload) {
-  if (!stonecrop.value) return
+| Option | Replaces | Use it for |
+|--------|----------|------------|
+| `buildArgs` | the `[{ id, data }]` envelope | a backend expecting another argument shape |
+| `followRecord` | `router.replace('/{doctype}/{id}')` | a locale prefix, a nested route, or staying put |
+| `onError` | a blocking `window.alert` | your own notification system |
 
-  // 1. Optionally persist field changes to HST before the transition
-  const store = stonecrop.value.getStore()
-  for (const [field, value] of Object.entries(payload.data)) {
-    const path = `${payload.doctype}.${payload.recordId}.${field}`
-    if (store.has(path) && store.get(path) !== value) {
-      store.set(path, value)
-    }
-  }
+`args` is an opaque JSON array: nothing validates it, so both ends of your own stack have to agree.
+`examples/desktop` uses positional `[recordId, data]` and supplies `buildArgs` to say so.
 
-  // 2. Call the server (StonecropClient, $fetch, tRPC — whatever your stack uses)
-  const result = await client.runAction({ name: payload.doctype }, payload.name, [
-    { id: payload.recordId, data: payload.data },
-  ])
+Resolving a record's identity and keying it into HST are deliberately **not** adjustable. That rule
+is declared on the doctype and re-derived server-side by the adapter, and every host that re-derived
+it client-side got it wrong. If you dispatch through `Stonecrop.dispatchAction` directly instead of
+using this composable, that method still files the returned record under the settled identity — you
+cannot store it under the wrong key by accident. What you lose is the stale-key cleanup and the
+route-follow, which need the id you dispatched.
 
-  // 3. Sync the server response back into HST
-  if (result.success && result.data) {
-    stonecrop.value.addRecord(payload.doctype, payload.recordId, result.data)
-  }
-}
-```
+Do not copy form data into HST before dispatching. Desktop already hands you the current form
+snapshot in `payload.data`, and an unsaved record has no HST node to write to.
+
+See the [host integration guide](../docs/guides/desktop-integration.md) for the full wiring.
 
 ## Provide / Inject
 
@@ -150,8 +163,10 @@ Desktop provides a `desktopMethods` object that child components (slot content)
 ```typescript
 import { inject } from 'vue'
 
-const { navigateToDoctype, openRecord, createNewRecord, handleDelete, emitAction } =
+const { navigateToDoctype, openRecord, createNewRecord, emitAction } =
   inject('desktopMethods')!
 ```
 
-`emitAction(name, data?)` is a convenience wrapper for emitting an `action` event from deeply nested slot content without passing refs down manually.
+`emitAction(name, data?)` is a convenience wrapper for emitting an `action` event from deeply nested slot content without passing refs down manually.
+
+Desktop blesses no action name. It used to expose a `handleDelete` method and a `confirmFn` prop, which together emitted a hardcoded `DELETE` action and prompted before it — but no doctype declares `DELETE`, so it failed on every click, and only the host knows which of its actions are destructive. Removal is a workflow outcome: declare an action with a `nextState` such as `Archived` or `CANCELLED`, and confirm inside your own `@action` handler before dispatching.

package/dist/desktop.d.ts

@@ -1,3 +1,4 @@
+import { ActionEventPayload } from '@stonecrop/stonecrop';
 import ActionSet from './components/ActionSet.vue';
 import CommandPalette from './components/CommandPalette.vue';
 import Desktop from './components/Desktop.vue';
@@ -10,18 +11,7 @@ import SheetNav from './components/SheetNav.vue';
  */
 export declare type ActionElements = ButtonElement | DropdownElement;
 
-/**
- * Payload emitted with the 'action' event when the user triggers an FSM transition
- * @public
- */
-export declare type ActionEventPayload = {
-    /** The FSM transition name (e.g. 'SAVE', 'SUBMIT', 'APPROVE') */
-    name: string;
-    doctype: string;
-    recordId: string;
-    /** Snapshot of the form data at the time the action was triggered */
-    data: Record<string, any>;
-};
+export { ActionEventPayload }
 
 export { ActionSet }