@jskit-ai/agent-docs 0.1.54 → 0.1.56

package/guide/agent/generators/advanced-cruds.md

@@ -454,7 +454,9 @@ This is the list-page container.
 Its job is usually to:
 
 - call `useCrudListScreen()`
-- pass page-local `listFilters` and `listBulkActions`
+- pass page-local `listFilters`, `listBulkActions`, and `listRowActions` when needed
+- pass `syntheticRows` when the page needs non-CRUD display rows such as an owner/master row
+- pass read options such as `requestQueryParams` and `readEnabled` when the list read needs them
 - render the shared `CrudListScreen`
 - resolve list/view/edit/new URLs
 - pass route query state through when navigating deeper
@@ -470,6 +472,8 @@ Its job is usually to:
 - call `useCrudViewScreen()`
 - render the shared `CrudViewScreen`
 - resolve "back" and "edit" navigation
+- pass read options such as `requestQueryParams`, `readEnabled`, and `queryKeyFactory` when the detail read needs them
+- use the shared view slots for page-specific sections around the generated field list
 
 Again, the runtime behavior is mostly uphill. The page is a route-level composition layer.
 
@@ -822,6 +826,8 @@ Use this rule of thumb when deciding where to edit:
 | Change SQL, joins, parent filters, or advanced search | `repository.js` | This is the data-access layer |
 | Add cross-record or domain rules on save/delete | `service.js` | This is business logic |
 | Change shared CRUD screen chrome, load states, or retry behavior | `users-web` shared screen components | Generated pages consume the shared screen contract |
+| Add per-row commands to a generated list page | page-local `listRowActions.js`, usually calling `useCommand()`-backed composables | The shared list screen renders action chrome; the page owns explicit mutation behavior |
+| Add non-CRUD display rows to a generated list page | route page `syntheticRows` input | Synthetic rows are presentation rows, not repository records |
 | Change page-specific display behavior | the route pages, generated slots, and app-owned composables | This is presentation |
 | Change form field layout and inputs | `_components/CrudAddEditForm.vue` and `CrudAddEditFormFields.js` | This is the generated form field layer |
 
@@ -832,6 +838,7 @@ The baseline generator output is only the start. As the tutorial's `contacts`, `
 - `src/server/listQueryValidators.js` when a list needs extra query filters beyond `q`
 - `src/server/service.test.js` once save/delete rules stop being trivial
 - `packages/contacts/src/shared/contactListFilters.js` when the contacts CRUD gains structured list filters that both server and client should share
+- `src/pages/.../contacts/listRowActions.js` when a generated list needs row-level commands such as Delete, Block, or Unblock
 - `src/composables/addresses/useAddressDisplay.js` when addresses need app-specific display formatting
 - `src/composables/comments/useCommentsListRuntime.js` when an embedded comments list needs local UI state
 
@@ -840,6 +847,81 @@ That is the right direction of growth:
 - server customizations stay in the CRUD package
 - presentation and page-specific UI state stay in app-owned client files
 - shared structured list filters live best in a CRUD-package shared module that both server and client can import
+- shared generated screen chrome stays in `users-web`; adapted pages feed it definitions, slots, and explicit command handlers
+
+### Shared screen read options and detail slots
+
+Use the shared list and detail screens first, even when a page needs includes, permission gating, or domain sections.
+
+`useCrudListScreen(...)` accepts the common list read-pass-through options that adapted list pages usually need:
+
+- `requestQueryParams`
+- `readEnabled`
+
+For example, a permission-gated list can stay on the shared list screen:
+
+```js
+const canReadProjectAccess = computed(() =>
+  access.value?.canManageProjectAccess === true
+);
+
+const screen = useCrudListScreen({
+  resource: projectAccessResource,
+  apiSuffix: "/project-access",
+  readEnabled: canReadProjectAccess,
+  requestQueryParams() {
+    return {
+      include: "userId,roleId"
+    };
+  }
+});
+```
+
+`readEnabled` gates the underlying Query-backed read. The screen still owns load, empty, error, retry, filters, row actions, and responsive list chrome. The page owns only the permission condition.
+
+`useCrudViewScreen(...)` accepts the same read-pass-through options that adapted detail pages usually need:
+
+- `requestQueryParams`
+- `readEnabled`
+- `queryKeyFactory`
+
+For example:
+
+```js
+const screen = useCrudViewScreen({
+  resource: drumResource,
+  apiUrlTemplate: "/drums/:recordId",
+  requestQueryParams() {
+    return {
+      include: "drumSpecId,locationId,contents,contents.processingLotId"
+    };
+  }
+});
+```
+
+Render domain sections through `CrudViewScreen` slots instead of replacing the shared load/error/retry chrome:
+
+```vue
+<CrudViewScreen :screen="screen" resource-singular-title="Drum">
+  <template #before-fields="{ view }">
+    <DrumArrivalSummary :drum="view.record" />
+  </template>
+
+  <template #fields="{ view }">
+    <GeneratedDrumFields :record="view.record" />
+  </template>
+
+  <template #after-fields="{ view }">
+    <DrumProvenancePanel :drum="view.record" />
+  </template>
+
+  <template #supporting-content="{ view }">
+    <DrumContentsPanel :drum="view.record" />
+  </template>
+</CrudViewScreen>
+```
+
+The screen still owns loading, not-found, retry, title, back/edit actions, and responsive shell structure. The page owns only the domain panels.
 
 ## Search and filters: the deep dive
 
@@ -1146,11 +1228,96 @@ The generated runtime passes action handlers:
 
 Keep bulk action definitions page-local unless another page needs to share them.
 
+### Pattern 3C: row actions and synthetic display rows
+
+Generated CRUD list pages can keep the shared list screen while adding per-row actions and non-CRUD display rows.
+
+Use row actions for explicit commands on one record. JSKIT renders the action menu in card and table layouts, tracks per-row execution state, and passes the handler enough context to run app-owned commands. It does not invent or auto-replay writes.
+
+For example:
+
+```js
+import { defineCrudListRowActions } from "@jskit-ai/users-web/client/rowActions";
+
+const listRowActions = defineCrudListRowActions([
+  {
+    key: "delete",
+    label: "Delete",
+    color: "error",
+    visible: ({ record }) => record.isOwnerRow !== true,
+    disabled: ({ record }) => record.isOwnerRow === true,
+    loading: ({ record }) => deleteCommand.isRunningFor(record.id),
+    async run({ record, reload }) {
+      await deleteCommand.runFor(record);
+      await reload();
+    }
+  }
+]);
+
+export { listRowActions };
+```
+
+Pass the actions into the generated list screen:
+
+```js
+import { listRowActions } from "./listRowActions.js";
+
+const screen = useCrudListScreen({
+  resource: uiResource,
+  apiSuffix: "/allowed-login-emails",
+  listRowActions
+});
+```
+
+The row-action handler receives:
+
+- `action`
+- `record`
+- `index`
+- `recordId`
+- `records`
+- `reload`
+
+Use `syntheticRows` when the page needs display rows that do not come from the CRUD list response, such as an owner row at the top of an allowlist. An array is prepended by default. Use `{ prepend, append }` when placement matters.
+
+```js
+const ownerRows = computed(() => owner.value
+  ? [
+      {
+        key: "owner",
+        record: {
+          id: owner.value.id,
+          email: owner.value.email,
+          role: "Owner",
+          isOwnerRow: true
+        }
+      }
+    ]
+  : []);
+
+const screen = useCrudListScreen({
+  resource: uiResource,
+  apiSuffix: "/allowed-login-emails",
+  listRowActions,
+  syntheticRows: ownerRows
+});
+```
+
+Synthetic rows:
+
+- render in the same card/table layouts as real rows
+- do not get standard Open/Edit CRUD navigation
+- are excluded from bulk selection by default
+- can still participate in row-action visibility/disabled logic
+
+Use this seam for display rows only. If a row should be persisted, it should come from the CRUD list response.
+
 #### Exact file checklist
 
 For a generated CRUD, treat this as the concrete file plan:
 
 - edit `src/pages/.../contacts/listFilters.js`
+- create `src/pages/.../contacts/listRowActions.js` when the list needs row-level commands
 - make sure the matching server route/action/repository code accepts and applies the declared query params when filters are server-backed
 
 If the filter contract should be shared with server code, promote it into a CRUD package module and import it from both sides:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/agent-docs",
-  "version": "0.1.54",
+  "version": "0.1.56",
   "description": "Distributed JSKIT agent references, prompts, guides, and generated reference maps.",
   "type": "module",
   "files": [

package/patterns/INDEX.md

@@ -30,7 +30,7 @@ How to use it:
   - `client-requests.md`
 - playwright, browser test, e2e, ui verification, authenticated ui test, test auth, dev login as, dev auth bypass
   - `ui-testing.md`
-- generated UI contract, design contract, navigation roles, density, placeholder copy, card shells, shared CRUD screens
+- generated UI contract, design contract, navigation roles, density, placeholder copy, card shells, shared CRUD screens, row actions, synthetic rows, detail slots
   - `generated-ui-contract-tracking.md`
 - filter, filters, search facets, chips, date range, enum filter, lookup filter, `useCrudListFilters`, `createCrudListFilters`
   - `filters.md`

package/patterns/client-requests.md

@@ -44,6 +44,16 @@ Use the shared CRUD screen wrappers when the route is a generated CRUD page:
 - `useCrudViewScreen()` plus `CrudViewScreen` for record view route pages
 - `useCrudAddEditScreen()` plus `CrudAddEditScreen` for generated new/edit route pages
 
+Generated screen wrapper extension rules:
+
+- Use `useCrudListScreen({ readEnabled })` for permission-gated generated list reads instead of splitting the page or replacing the shared list screen.
+- Use `useCrudListScreen({ requestQueryParams })` for list includes or other endpoint query params instead of putting query strings in `apiSuffix`.
+- Use `useCrudViewScreen({ requestQueryParams })` for detail includes instead of putting query strings in `apiUrlTemplate`.
+- Use `readEnabled` and `queryKeyFactory` on `useCrudViewScreen()` when the detail read needs the same gating or cache identity control as `useCrudView()`.
+- Use `CrudViewScreen` slots (`before-fields`, `fields`, `after-fields`, `supporting-content`) for page-specific domain sections while keeping shared load/error/retry chrome.
+- Use `listRowActions` with `defineCrudListRowActions(...)` for row-level commands in `CrudListScreen`.
+- Use `syntheticRows` for display-only rows that do not come from the CRUD response, such as owner/master rows.
+
 Use the CRUD wrappers when they fit:
 
 - `useCrudList()` for routed CRUD lists
@@ -86,5 +96,6 @@ Avoid:
 - manually concatenating scoped route params into API URLs
 - using a lower-level seam when a higher-level routed CRUD or command runtime already fits
 - smuggling query params into `apiUrlTemplate`
+- replacing `CrudListScreen` or `CrudViewScreen` only to add read gating, row actions, synthetic display rows, includes, or domain detail sections
 - reporting routine resource load errors through hand-written global snackbar/banner calls
 - calling `useShellRequestRecoveryRuntime().report(...)` from normal panels just to recover an HTTP read

package/patterns/crud-scaffolding.md

@@ -28,8 +28,10 @@ Rules:
 - Generated CRUD UI must be compact-first. Lists need searchable cards on compact widths and tables only for medium/expanded layouts.
 - Generated CRUD list screens need real loading, empty, and error states. Empty copy should name the resource, such as "No customers yet", and offer the create action when available.
 - Generated CRUD view/new/edit screens should use page headers plus direct sheet panels. Do not use generic card shells as the page architecture.
+- Permission-gated generated CRUD lists should pass `readEnabled` into `useCrudListScreen(...)` instead of replacing the shared list wrapper.
 - Compact CRUD actions should be reachable without a drawer. Use a mobile-visible primary action or FAB for create flows.
-- Row actions should collapse into an overflow/action menu on compact widths and can be inline on wider layouts.
+- Row actions should be declared with `defineCrudListRowActions(...)` in a page-local `listRowActions.js` and passed into `useCrudListScreen(...)`; the shared list screen owns the compact/wide action rendering.
+- Use `syntheticRows` for display-only owner/master rows that should appear inside the shared list layout without becoming CRUD records.
 - Bulk actions should be declared in the generated page-local `listBulkActions.js`. The generated list owns selection state, keeps selection controls hidden until actions exist, and exposes selected ids/records to action handlers.
 - Structured filters should use shared filter definitions and collapse to compact filter controls/sheets when they outgrow simple search. Do not stack dense desktop filter bars on phone widths.
 - Use `--navigation-role` for CRUD list placement intent. Main resources can stay `primary`; nested/detail/workflow CRUD routes should usually be `secondary`, `workflow`, or `none`.

package/patterns/generated-ui-contract-tracking.md

@@ -57,6 +57,10 @@ Generated JSKIT apps should feel like real adaptive apps by default, not framewo
 - Item 6 is complete for the default shell: compact app bars use compact density and bounded top-left/top-right regions, while primary navigation remains in semantic bottom navigation instead of app-bar chrome.
 - CRUD filters are client-side by default: generated list pages create a page-local `listFilters.js` and pass it into `useCrudListScreen(...)`; the shared list screen wires `filterRuntime.queryParams` into the list request and renders `CrudListFilterSurface`. When server filtering is needed, promote the definitions into a shared package module and use `createCrudListFilterContract(...)` so route/action validators, JSON REST search schema, and repository query normalization stay derived from the same definition.
 - CRUD bulk actions are client-side by default: generated list pages create a page-local `listBulkActions.js` and pass it into `useCrudListScreen(...)`; the shared list screen wires `useCrudListBulkActions(...)` and keeps selection controls hidden until actions are declared.
-- Generated CRUD page templates delegate their screen chrome to shared `users-web` screen components (`CrudListScreen`, `CrudViewScreen`, and `CrudAddEditScreen`) so list/view/form load states, retry actions, responsive shell layout, filters, and bulk actions do not drift across generated pages.
+- CRUD row actions are client-side by default: generated list pages can create a page-local `listRowActions.js` with `defineCrudListRowActions(...)` and pass it into `useCrudListScreen(...)`; the shared list screen renders per-row actions in card and table layouts while action handlers stay explicit and page-owned.
+- CRUD synthetic rows are display-only: pass `syntheticRows` into `useCrudListScreen(...)` for owner/master rows that are not repository records. Synthetic rows render through the shared list screen, skip standard Open/Edit links, and are excluded from bulk selection unless explicitly marked selectable.
+- Generated CRUD page templates delegate their screen chrome to shared `users-web` screen components (`CrudListScreen`, `CrudViewScreen`, and `CrudAddEditScreen`) so list/view/form load states, retry actions, responsive shell layout, filters, bulk actions, row actions, and detail slots do not drift across generated pages.
+- Generated CRUD list pages should use `useCrudListScreen({ requestQueryParams, readEnabled })` for list read pass-throughs instead of replacing the shared list chrome for includes or permission-gated reads.
+- Generated CRUD detail pages should use `useCrudViewScreen({ requestQueryParams, readEnabled, queryKeyFactory })` for read pass-throughs and `CrudViewScreen` slots (`before-fields`, `fields`, `after-fields`, `supporting-content`) for domain sections instead of replacing the shared detail chrome.
 - Routine resource-load errors stay local to the generated screen and retry affordance. Action feedback uses the shell error policy through `action-feedback`.
 - `page.supporting-content` is a semantic supporting region in the default shell. Compact layout renders it as a closed bottom sheet; medium/expanded layouts render it as a closed side panel.

package/reference/autogen/packages/users-web.md

@@ -66,6 +66,14 @@ Local functions
 - `clearChip(chip = {})`
 - `clearFilters()`
 
+### `src/client/components/CrudListRecordActionMenu.vue`
+Exports
+- None
+Local functions
+- `isRowActionLoading(action = {})`
+- `isRowActionDisabled(action = {})`
+- `runRowAction(action = {})`
+
 ### `src/client/components/CrudListScreen.vue`
 Exports
 - None
@@ -74,6 +82,12 @@ Local functions
 - `formatListCardValue(value)`
 - `resolveViewLocation(record)`
 - `resolveEditLocation(record)`
+- `hasRowActionsFor(record, index)`
+- `isBulkRowSelected(row = {})`
+- `setBulkRowSelected(row = {}, selected = true)`
+- `allSelectableRowsSelected()`
+- `someSelectableRowsSelected()`
+- `setSelectableRowsSelected(selected = true)`
 
 ### `src/client/components/CrudViewScreen.vue`
 Exports
@@ -484,15 +498,30 @@ Exports
 Local functions
 - `normalizeQueryKeyPrefix(value = [])`
 
+### `src/client/composables/useCrudListRowActions.js`
+Exports
+- `useCrudListRowActions(actions = [], { resolveRecordId = null, resolveContext = null } = {})`
+Local functions
+- `normalizeRowActionKey(actionOrKey = "")`
+- `normalizeRowId(value = "")`
+- `createExecutionKey(actionKey = "", recordId = "", index = 0)`
+- `asContextObject(value = null)`
+
 ### `src/client/composables/useCrudListScreen.js`
 Exports
-- `useCrudListScreen({ adapter = null, resource = null, resourceNamespace = "resource", apiSuffix = "", recordIdParam = "recordId", recordIdSelector = null, titleFallbackFieldKey = "", viewUrlTemplate = "", editUrlTemplate = "", newUrlTemplate = "", recordChangedEvents = [], listFilters = {}, listBulkActions = [], routeQueryBlacklist = Object.freeze(["include", "cursor", "limit"]), requestRecoveryLabel = "Records", fallbackLoadError = "Unable to load records." } = {})`
+- `useCrudListScreen({ adapter = null, resource = null, resourceNamespace = "resource", apiSuffix = "", recordIdParam = "recordId", recordIdSelector = null, titleFallbackFieldKey = "", viewUrlTemplate = "", editUrlTemplate = "", newUrlTemplate = "", recordChangedEvents = [], listFilters = {}, listBulkActions = [], listRowActions = [], syntheticRows = null, routeQueryBlacklist = Object.freeze(["include", "cursor", "limit"]), requestQueryParams = null, readEnabled = true, requestRecoveryLabel = "Records", fallbackLoadError = "Unable to load records." } = {})`
 Local functions
 - `formatCrudListCardValue(value)`
+- `asList(value = [])`
+- `hasSyntheticRowGroups(value = null)`
+- `normalizeSyntheticDisplayRow(source = null, index = 0, placement = "prepend")`
+- `normalizeSyntheticDisplayRows(value = [], placement = "prepend")`
+- `normalizeSyntheticDisplayRowGroups(syntheticRows = null)`
+- `createCrudListDisplayRow(record = {}, index = 0, records = {})`
 
 ### `src/client/composables/useCrudViewScreen.js`
 Exports
-- `useCrudViewScreen({ adapter = null, resource = null, resourceNamespace = "resource", apiUrlTemplate = "", recordIdParam = "recordId", titleFallbackFieldKey = "", listUrlTemplate = "", editUrlTemplate = "", recordChangedEvent = "", requestRecoveryLabel = "Record", fallbackLoadError = "Unable to load record.", notFoundMessage = "Record not found." } = {})`
+- `useCrudViewScreen({ adapter = null, resource = null, resourceNamespace = "resource", apiUrlTemplate = "", recordIdParam = "recordId", titleFallbackFieldKey = "", listUrlTemplate = "", editUrlTemplate = "", recordChangedEvent = "", requestQueryParams = null, readEnabled = true, queryKeyFactory = null, requestRecoveryLabel = "Record", fallbackLoadError = "Unable to load record.", notFoundMessage = "Record not found." } = {})`
 
 ### `src/client/composables/usePagedCollection.js`
 Exports
@@ -605,6 +634,12 @@ Local functions
 Exports
 - `UsersWebClientProvider`
 
+### `src/client/rowActions.js`
+Exports
+- `defineCrudListRowActions(actions = [])`
+Local functions
+- `normalizeCrudListRowAction(rawAction = {}, index = 0)`
+
 ### `src/client/support/contractGuards.js`
 Exports
 - `requireRecord(value, label = "value", owner = "Contract")`