@jskit-ai/http-web 0.1.3 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/http-web",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -44,11 +44,11 @@
     "./client/support/contractGuards": "./src/client/support/contractGuards.js"
   },
   "dependencies": {
-    "@jskit-ai/http-runtime": "0.1.156",
-    "@jskit-ai/kernel": "0.1.158",
-    "@jskit-ai/realtime": "0.1.155",
-    "@jskit-ai/resource-crud-core": "0.1.100",
-    "@jskit-ai/shell-web": "0.1.162",
+    "@jskit-ai/http-runtime": "0.1.158",
+    "@jskit-ai/kernel": "0.1.160",
+    "@jskit-ai/realtime": "0.1.157",
+    "@jskit-ai/resource-crud-core": "0.1.102",
+    "@jskit-ai/shell-web": "0.1.164",
     "@mdi/js": "^7.4.47"
   },
   "peerDependencies": {
@@ -64,11 +64,7 @@
       "provides": [
         "runtime.http-web"
       ],
-      "requires": [
-        "runtime.http-client",
-        "runtime.web-error",
-        "runtime.web-placement"
-      ]
+      "requires": []
     },
     "runtime": {
       "server": {
@@ -111,40 +107,18 @@
           },
           {
             "subpath": "./client/components/CrudListScreen",
-            "summary": "Exports the shared generated CRUD list screen."
+            "summary": "Exports the shared CRUD list screen."
           },
           {
             "subpath": "./client/components/CrudViewScreen",
-            "summary": "Exports the shared generated CRUD view screen."
+            "summary": "Exports the shared CRUD view screen."
           },
           {
             "subpath": "./client/components/CrudAddEditScreen",
-            "summary": "Exports the shared generated CRUD add/edit screen."
+            "summary": "Exports the shared CRUD add/edit screen."
           }
-        ],
-        "containerTokens": {
-          "server": [],
-          "client": []
-        }
+        ]
       }
-    },
-    "mutations": {
-      "dependencies": {
-        "runtime": {
-          "@jskit-ai/http-runtime": "0.1.156",
-          "@jskit-ai/kernel": "0.1.158",
-          "@jskit-ai/realtime": "0.1.155",
-          "@jskit-ai/resource-crud-core": "0.1.100",
-          "@jskit-ai/shell-web": "0.1.162",
-          "@mdi/js": "^7.4.47"
-        },
-        "dev": {}
-      },
-      "packageJson": {
-        "scripts": {}
-      },
-      "procfile": {},
-      "files": []
     }
   }
 }

package/patterns/crud-screen-set/PATTERN.md

@@ -0,0 +1,88 @@
+---
+id: crud/crud-screen-set
+title: CRUD list, view, create, and edit screens
+summary: Build a routed CRUD user interface as thin application pages over JSKIT's shared screen components and composables.
+keywords: actions, add, crud, delete, edit, filters, list, material, routes, view, vue
+requires: @jskit-ai/http-web, @jskit-ai/resource-crud-core
+---
+
+# CRUD list, view, create, and edit screens
+
+## Use when
+
+Use this pattern when a shared CRUD resource should have normal list, detail,
+create, edit, and delete routes. The shared JSKIT screens own responsive chrome,
+loading skeletons, load-error retry states, mutation feedback, route-aware data
+operations, and common extensions. Application pages supply product copy,
+fields, routes, and optional actions.
+
+## Do not use when
+
+Do not use this pattern for a one-off command, an embedded read-only value, or a
+domain whose operations are not CRUD. Do not replace the shared screens simply
+to add filters, row actions, bulk actions, permission gating, includes, or
+supporting detail content; those are public extension seams.
+
+## Product decisions
+
+Decide which operations exist, the route hierarchy, record title, visible
+fields, create/edit participation, destructive confirmation language, access
+surface, filters, and domain actions. The resource contract and product intent
+are authoritative. Do not derive these decisions from a live table or a field
+questionnaire.
+
+## Invariants
+
+- Route pages stay thin and use `useCrudListScreen()`, `useCrudViewScreen()`,
+  or `useCrudAddEditScreen()`.
+- Transport and validators come from the shared resource contract.
+- Initial visible loading uses structure-matching skeletons; pending buttons use
+  stable disabled labels, never spinners.
+- Resource-load errors stay inside the screen with retry. Command success and
+  failure use JSKIT's shared toast/snackbar feedback path.
+- URLs are route templates or route objects resolved through the screen runtime.
+- Product field components are ordinary application source.
+- Query keys and placement sources describe the resource, not an authoring tool.
+- No generated-file markers, overwrite contracts, receipts, or provenance remain.
+
+## Framework APIs
+
+Use `CrudListScreen`, `CrudViewScreen`, `CrudAddEditScreen`, and
+`CrudDeleteAction` with their matching composables from `@jskit-ai/http-web`.
+Use `defineCrudListFilters()`, `defineCrudListRowActions()`, and
+`defineCrudListBulkActions()` for optional list extensions. The resource comes
+from `defineCrudResource()` in `@jskit-ai/resource-crud-core`.
+
+## Example files
+
+`example/books/` contains concrete list, view, new, and edit pages for the
+owner-scoped `bookResource` pattern. `BookFormFields.vue` and `formFields.js`
+show the small product-owned form seam. `listExtensions.js` makes optional
+filters and actions explicit without adding empty screen machinery elsewhere.
+
+## Variation points
+
+Change routes, labels, visible fields, field components, filters, query params,
+realtime events, delete availability, and action definitions. Use the screen
+slots for domain-specific content. Use a lower-level request composable only
+when the wire contract genuinely is not CRUD.
+
+## Verification
+
+- Mount each route with a representative resource response.
+- Verify skeleton, empty, success, local load-error, and retry states.
+- Verify create, edit, validation failure, delete confirmation, and navigation.
+- Verify filters and actions when declared.
+- Exercise compact, medium, and expanded widths with Playwright.
+- Confirm keyboard access, 48 CSS-pixel compact targets, no horizontal overflow,
+  and toast-based mutation feedback.
+
+## Avoid
+
+- route-local `fetch()` or duplicated request serializers
+- copying shared screen chrome into every route
+- spinner or circular-progress loading states
+- transient in-page command-error banners that push the layout
+- generator-branded CSS classes, cache keys, or placement ids
+- comments or metadata reserving fields for a future authoring command
+- a second source of truth for resource field validation

package/patterns/crud-screen-set/example/books/BookEditPage.vue

@@ -0,0 +1,54 @@
+<script setup>
+import { computed } from "vue";
+import { useRoute } from "vue-router";
+import CrudAddEditScreen from "@jskit-ai/http-web/client/components/CrudAddEditScreen";
+import { useCrudAddEditScreen } from "@jskit-ai/http-web/client/composables/useCrudAddEditScreen";
+import { bookResource } from "@local/books/shared";
+import BookFormFields from "./BookFormFields.vue";
+import { bookFormFields } from "./formFields.js";
+
+const route = useRoute();
+const routeRecordId = computed(() => String(route.params.bookId || "").trim());
+
+const screen = useCrudAddEditScreen({
+  mode: "edit",
+  title: "Edit book",
+  subtitle: "Update this catalogue entry.",
+  saveLabel: "Save changes",
+  cancelTo: "/books/:bookId",
+  preserveCancelQuery: true,
+  resource: bookResource,
+  operationName: "patch",
+  formFields: bookFormFields,
+  addEditOptions: {
+    apiUrlTemplate: "/books/:bookId",
+    placementSource: "crud.books.edit",
+    writeMethod: "PATCH",
+    requestRecoveryLabel: "Book",
+    fallbackLoadError: "Unable to load this book.",
+    fallbackSaveError: "Unable to save this book.",
+    recordIdParam: "bookId",
+    routeRecordId,
+    viewUrlTemplate: "/books/:bookId",
+    listUrlTemplate: "/books"
+  },
+  saveSuccess: {
+    invalidateQueryKey: ["crud", "books"],
+    listUrlTemplate: "/books"
+  }
+});
+</script>
+
+<template>
+  <CrudAddEditScreen :screen="screen">
+    <template #fields="fieldRuntime">
+      <BookFormFields
+        v-model:title="fieldRuntime.formState.title"
+        v-model:author="fieldRuntime.formState.author"
+        v-model:notes="fieldRuntime.formState.notes"
+        :readonly="fieldRuntime.addEdit.isFieldLocked"
+        :resolve-field-errors="fieldRuntime.resolveFieldErrors"
+      />
+    </template>
+  </CrudAddEditScreen>
+</template>

package/patterns/crud-screen-set/example/books/BookFormFields.vue

@@ -0,0 +1,52 @@
+<script setup>
+const title = defineModel("title", { type: String, default: "" });
+const author = defineModel("author", { type: String, default: "" });
+const notes = defineModel("notes", { type: String, default: "" });
+
+defineProps({
+  readonly: {
+    type: Boolean,
+    default: false
+  },
+  resolveFieldErrors: {
+    type: Function,
+    required: true
+  }
+});
+</script>
+
+<template>
+  <v-col cols="12" md="6">
+    <v-text-field
+      v-model="title"
+      label="Title"
+      variant="outlined"
+      density="comfortable"
+      maxlength="255"
+      :readonly="readonly"
+      :error-messages="resolveFieldErrors('title')"
+    />
+  </v-col>
+  <v-col cols="12" md="6">
+    <v-text-field
+      v-model="author"
+      label="Author"
+      variant="outlined"
+      density="comfortable"
+      maxlength="255"
+      :readonly="readonly"
+      :error-messages="resolveFieldErrors('author')"
+    />
+  </v-col>
+  <v-col cols="12">
+    <v-textarea
+      v-model="notes"
+      label="Notes"
+      variant="outlined"
+      density="comfortable"
+      auto-grow
+      :readonly="readonly"
+      :error-messages="resolveFieldErrors('notes')"
+    />
+  </v-col>
+</template>

package/patterns/crud-screen-set/example/books/BookListPage.vue

@@ -0,0 +1,54 @@
+<script setup>
+import CrudListScreen from "@jskit-ai/http-web/client/components/CrudListScreen";
+import { useCrudListScreen } from "@jskit-ai/http-web/client/composables/useCrudListScreen";
+import { bookResource } from "@local/books/shared";
+import { listBulkActions, listFilters, listRowActions } from "./listExtensions.js";
+
+const screen = useCrudListScreen({
+  resource: bookResource,
+  resourceNamespace: "books",
+  apiSuffix: "/books",
+  recordIdParam: "bookId",
+  recordIdSelector: (book = {}) => book.id,
+  titleFallbackFieldKey: "title",
+  viewUrlTemplate: "/books/:bookId",
+  editUrlTemplate: "/books/:bookId/edit",
+  newUrlTemplate: "/books/new",
+  listFilters,
+  listBulkActions,
+  listRowActions,
+  requestRecoveryLabel: "Books",
+  fallbackLoadError: "Unable to load books."
+});
+</script>
+
+<template>
+  <CrudListScreen
+    :screen="screen"
+    title-label="Books"
+    heading-title="My books"
+    subtitle="Search and maintain your catalogue."
+    create-label="Add book"
+    empty-title="No books yet"
+    empty-body="Add your first book to begin the catalogue."
+  >
+    <template #card-fields="{ record, formatListCardValue }">
+      <dl class="d-grid ga-2 mb-0">
+        <div>
+          <dt class="text-caption text-medium-emphasis">Author</dt>
+          <dd class="text-body-2 mb-0">{{ formatListCardValue(record.author) }}</dd>
+        </div>
+      </dl>
+    </template>
+
+    <template #table-header>
+      <th>Title</th>
+      <th>Author</th>
+    </template>
+
+    <template #table-row="{ record }">
+      <td>{{ record.title }}</td>
+      <td>{{ record.author }}</td>
+    </template>
+  </CrudListScreen>
+</template>

package/patterns/crud-screen-set/example/books/BookNewPage.vue

@@ -0,0 +1,45 @@
+<script setup>
+import CrudAddEditScreen from "@jskit-ai/http-web/client/components/CrudAddEditScreen";
+import { useCrudAddEditScreen } from "@jskit-ai/http-web/client/composables/useCrudAddEditScreen";
+import { bookResource } from "@local/books/shared";
+import BookFormFields from "./BookFormFields.vue";
+import { bookFormFields } from "./formFields.js";
+
+const screen = useCrudAddEditScreen({
+  mode: "new",
+  title: "Add book",
+  subtitle: "Add a book to your catalogue.",
+  saveLabel: "Save book",
+  cancelTo: "/books",
+  resource: bookResource,
+  operationName: "create",
+  formFields: bookFormFields,
+  addEditOptions: {
+    apiSuffix: "/books",
+    placementSource: "crud.books.new",
+    readEnabled: false,
+    writeMethod: "POST",
+    recordIdParam: "bookId",
+    viewUrlTemplate: "/books/:bookId",
+    listUrlTemplate: "/books"
+  },
+  saveSuccess: {
+    invalidateQueryKey: ["crud", "books"],
+    listUrlTemplate: "/books"
+  }
+});
+</script>
+
+<template>
+  <CrudAddEditScreen :screen="screen">
+    <template #fields="fieldRuntime">
+      <BookFormFields
+        v-model:title="fieldRuntime.formState.title"
+        v-model:author="fieldRuntime.formState.author"
+        v-model:notes="fieldRuntime.formState.notes"
+        :readonly="fieldRuntime.addEdit.isFieldLocked"
+        :resolve-field-errors="fieldRuntime.resolveFieldErrors"
+      />
+    </template>
+  </CrudAddEditScreen>
+</template>

package/patterns/crud-screen-set/example/books/BookViewPage.vue

@@ -0,0 +1,50 @@
+<script setup>
+import CrudDeleteAction from "@jskit-ai/http-web/client/components/CrudDeleteAction";
+import CrudViewScreen from "@jskit-ai/http-web/client/components/CrudViewScreen";
+import { useCrudDeleteAction } from "@jskit-ai/http-web/client/composables/useCrudDeleteAction";
+import { useCrudViewScreen } from "@jskit-ai/http-web/client/composables/useCrudViewScreen";
+import { bookResource } from "@local/books/shared";
+
+const screen = useCrudViewScreen({
+  resource: bookResource,
+  resourceNamespace: "books",
+  apiUrlTemplate: "/books/:bookId",
+  recordIdParam: "bookId",
+  titleFallbackFieldKey: "title",
+  listUrlTemplate: "/books",
+  editUrlTemplate: "/books/:bookId/edit",
+  requestRecoveryLabel: "Book",
+  fallbackLoadError: "Unable to load this book."
+});
+
+const deleteAction = useCrudDeleteAction({
+  screen,
+  resource: bookResource,
+  resourceNamespace: "books",
+  apiUrlTemplate: "/books/:bookId"
+});
+</script>
+
+<template>
+  <CrudViewScreen
+    :screen="screen"
+    resource-singular-title="Book"
+    resource-plural-title="Books"
+    description="Review this catalogue entry."
+  >
+    <template #actions>
+      <CrudDeleteAction :action="deleteAction" resource-singular-title="Book" />
+    </template>
+
+    <template #fields="{ view }">
+      <v-col cols="12" md="6">
+        <div class="text-caption text-medium-emphasis">Author</div>
+        <div class="text-body-1">{{ view.record?.author }}</div>
+      </v-col>
+      <v-col cols="12">
+        <div class="text-caption text-medium-emphasis">Notes</div>
+        <div class="text-body-1 text-pre-wrap">{{ view.record?.notes || "No notes" }}</div>
+      </v-col>
+    </template>
+  </CrudViewScreen>
+</template>

package/patterns/crud-screen-set/example/books/formFields.js

@@ -0,0 +1,31 @@
+const bookFormFields = Object.freeze([
+  Object.freeze({
+    key: "title",
+    label: "Title",
+    type: "string",
+    nullable: false,
+    inputType: "text",
+    component: "text",
+    maxLength: 255
+  }),
+  Object.freeze({
+    key: "author",
+    label: "Author",
+    type: "string",
+    nullable: false,
+    inputType: "text",
+    component: "text",
+    maxLength: 255
+  }),
+  Object.freeze({
+    key: "notes",
+    label: "Notes",
+    type: "string",
+    nullable: true,
+    inputType: "textarea",
+    component: "textarea",
+    maxLength: 65535
+  })
+]);
+
+export { bookFormFields };

package/patterns/crud-screen-set/example/books/listExtensions.js

@@ -0,0 +1,9 @@
+import { defineCrudListBulkActions } from "@jskit-ai/http-web/client/bulkActions";
+import { defineCrudListFilters } from "@jskit-ai/http-web/client/filters";
+import { defineCrudListRowActions } from "@jskit-ai/http-web/client/rowActions";
+
+const listFilters = defineCrudListFilters({});
+const listBulkActions = defineCrudListBulkActions([]);
+const listRowActions = defineCrudListRowActions([]);
+
+export { listBulkActions, listFilters, listRowActions };

package/src/client/components/CrudAddEditScreen.vue

@@ -52,28 +52,27 @@ function resolveCancelTo(target = cancelTo.value) {
 </script>
 
 <template>
-  <section class="generated-ui-screen generated-ui-screen--operator ui-generator-add-edit-form d-flex flex-column ga-4">
-    <header class="ui-generator-add-edit-form__header">
-      <div class="ui-generator-add-edit-form__copy">
-        <h1 class="ui-generator-add-edit-form__title">{{ title }}</h1>
+  <section class="crud-screen crud-screen--operator crud-add-edit-form d-flex flex-column ga-4">
+    <header class="crud-add-edit-form__header">
+      <div class="crud-add-edit-form__copy">
+        <h1 class="crud-add-edit-form__title">{{ title }}</h1>
         <p v-if="subtitle" class="text-body-2 text-medium-emphasis mb-0">{{ subtitle }}</p>
       </div>
-      <div class="ui-generator-add-edit-form__actions">
+      <div class="crud-add-edit-form__actions">
         <v-btn v-if="cancelTo" color="primary" variant="outlined" :to="resolveCancelTo(cancelTo)">Cancel</v-btn>
         <v-btn
           color="primary"
           variant="flat"
-          :loading="addEdit.isSaving"
           :disabled="addEdit.isSubmitDisabled"
           @click="addEdit.submit"
         >
-          {{ saveLabel }}
+          {{ addEdit.isSaving ? "Saving…" : saveLabel }}
         </v-btn>
       </div>
     </header>
 
-    <v-sheet rounded="lg" border class="ui-generator-add-edit-form__panel">
-      <div v-if="addEdit.loadError" class="ui-generator-add-edit-form__state">
+    <v-sheet rounded="lg" border class="crud-add-edit-form__panel">
+      <div v-if="addEdit.loadError" class="crud-add-edit-form__state">
         <h2 class="text-h6 mb-2">Unable to load form</h2>
         <p class="text-body-2 text-medium-emphasis mb-4">
           {{ addEdit.loadError }}
@@ -82,10 +81,10 @@ function resolveCancelTo(target = cancelTo.value) {
           v-if="addEdit.canRetryLoad"
           color="primary"
           variant="tonal"
-          :loading="addEdit.isFetching"
+          :disabled="addEdit.isFetching"
           @click="addEdit.refresh"
         >
-          Retry
+          {{ addEdit.isFetching ? "Retrying…" : "Retry" }}
         </v-btn>
       </div>
       <template v-else-if="formRuntime.showFormSkeleton">
@@ -94,8 +93,7 @@ function resolveCancelTo(target = cancelTo.value) {
         </div>
       </template>
       <v-form v-else class="pa-4" @submit.prevent="addEdit.submit" novalidate>
-        <v-progress-linear v-if="addEdit.isRefetching" indeterminate class="mb-4" />
-        <v-row class="ui-generator-add-edit-form__fields">
+        <v-row class="crud-add-edit-form__fields">
           <slot
             name="fields"
             :mode="mode"
@@ -115,71 +113,71 @@ function resolveCancelTo(target = cancelTo.value) {
 </template>
 
 <style scoped>
-.generated-ui-screen {
-  --generated-ui-screen-title-size: clamp(1.35rem, 2vw, 1.85rem);
-  --generated-ui-screen-state-padding: 2.5rem 1.25rem;
+.crud-screen {
+  --crud-screen-title-size: clamp(1.35rem, 2vw, 1.85rem);
+  --crud-screen-state-padding: 2.5rem 1.25rem;
 }
 
-.generated-ui-screen--operator {
-  --generated-ui-screen-state-padding: 2rem 1rem;
+.crud-screen--operator {
+  --crud-screen-state-padding: 2rem 1rem;
 }
 
-.ui-generator-add-edit-form__header {
+.crud-add-edit-form__header {
   align-items: flex-start;
   display: flex;
   gap: 1rem;
   justify-content: space-between;
 }
 
-.ui-generator-add-edit-form__copy {
+.crud-add-edit-form__copy {
   min-width: 0;
 }
 
-.ui-generator-add-edit-form__title {
-  font-size: var(--generated-ui-screen-title-size);
+.crud-add-edit-form__title {
+  font-size: var(--crud-screen-title-size);
   font-weight: 650;
   letter-spacing: -0.02em;
   line-height: 1.15;
   margin: 0 0 0.35rem;
 }
 
-.ui-generator-add-edit-form__actions {
+.crud-add-edit-form__actions {
   display: flex;
   flex-wrap: wrap;
   gap: 0.5rem;
   justify-content: flex-end;
 }
 
-.ui-generator-add-edit-form__panel {
+.crud-add-edit-form__panel {
   overflow: hidden;
 }
 
-.ui-generator-add-edit-form__state {
+.crud-add-edit-form__state {
   margin-inline: auto;
   max-width: 30rem;
-  padding: var(--generated-ui-screen-state-padding);
+  padding: var(--crud-screen-state-padding);
   text-align: center;
 }
 
-.ui-generator-add-edit-form__fields :deep(.v-col) {
+.crud-add-edit-form__fields :deep(.v-col) {
   min-width: 0;
 }
 
 @media (max-width: 960px) {
-  .ui-generator-add-edit-form__header {
+  .crud-add-edit-form__header {
     flex-direction: column;
   }
 
-  .ui-generator-add-edit-form__actions {
+  .crud-add-edit-form__actions {
     width: 100%;
   }
 
-  .ui-generator-add-edit-form__actions :deep(.v-btn) {
+  .crud-add-edit-form__actions :deep(.v-btn) {
     min-height: 48px;
     flex: 1 1 10rem;
   }
 
-  .ui-generator-add-edit-form__state :deep(.v-btn) {
+  .crud-add-edit-form__state :deep(.v-btn) {
     min-height: 48px;
   }
 }

package/src/client/components/CrudDeleteAction.vue

@@ -81,11 +81,10 @@ function handleDialogModelUpdate(isOpen) {
         <v-btn
           color="error"
           variant="flat"
-          :loading="action.isDeleting"
           :disabled="!action.canDelete"
           @click="action.confirm"
         >
-          Delete
+          {{ action.isDeleting ? "Deleting…" : "Delete" }}
         </v-btn>
       </v-card-actions>
     </v-card>

package/src/client/components/CrudListBulkActionSurface.vue

@@ -61,10 +61,9 @@ function isActionExecuting(action = {}) {
         :variant="action.variant"
         :prepend-icon="action.icon || undefined"
         :disabled="isActionDisabled(action)"
-        :loading="isActionExecuting(action)"
         @click="execute(action)"
       >
-        {{ action.label }}
+        {{ isActionExecuting(action) ? `${action.label}…` : action.label }}
       </v-btn>
     </div>
 
@@ -76,7 +75,7 @@ function isActionExecuting(action = {}) {
         <v-list-item
           v-for="action in actions"
           :key="action.key"
-          :title="action.label"
+          :title="isActionExecuting(action) ? `${action.label}…` : action.label"
           :prepend-icon="action.icon || undefined"
           :disabled="isActionDisabled(action)"
           @click="execute(action)"