@jskit-ai/agent-docs 0.1.55 → 0.1.57

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

@@ -456,6 +456,7 @@ Its job is usually to:
 - call `useCrudListScreen()`
 - 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
@@ -848,9 +849,35 @@ That is the right direction of growth:
 - 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
 
-### Detail read options and extension slots
+### Shared screen read options and detail slots
 
-Use the shared detail screen first, even when the detail page needs includes or domain sections.
+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:
 

package/package.json

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

package/patterns/client-requests.md

@@ -46,6 +46,8 @@ Use the shared CRUD screen wrappers when the route is a generated CRUD page:
 
 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.
@@ -94,6 +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 row actions, synthetic display rows, includes, or domain detail sections
+- 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,6 +28,7 @@ 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 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.

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

@@ -60,6 +60,7 @@ Generated JSKIT apps should feel like real adaptive apps by default, not framewo
 - 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

@@ -509,7 +509,7 @@ Local functions
 
 ### `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 = [], listRowActions = [], syntheticRows = null, routeQueryBlacklist = Object.freeze(["include", "cursor", "limit"]), requestQueryParams = null, 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 = [])`