@jskit-ai/crud-ui-generator 0.1.1

package/templates/src/pages/admin/ui-generator/ListElement.vue

@@ -0,0 +1,103 @@
+<template>
+  <section class="ui-generator-list-element d-flex flex-column ga-4">
+    <v-card rounded="lg" elevation="1" border>
+      <v-card-item>
+        <div class="d-flex align-center ga-3 flex-wrap w-100">
+          <div>
+            <v-card-title class="px-0">${option:namespace|plural|pascal}</v-card-title>
+            <v-card-subtitle class="px-0">Manage ${option:namespace|plural|default(records)}.</v-card-subtitle>
+          </div>
+          <v-spacer />
+          <v-btn variant="outlined" :loading="records.isFetching.value" @click="records.reload">Refresh</v-btn>
+          <v-btn v-if="UI_NEW_URL" color="primary" :to="records.resolveParams(UI_NEW_URL)">New ${option:namespace|singular|default(record)}</v-btn>
+        </div>
+      </v-card-item>
+      <v-divider />
+      <v-card-text class="pt-4">
+        <template v-if="records.showListSkeleton.value">
+          <v-skeleton-loader type="text@2, list-item-two-line@5" />
+        </template>
+        <template v-else>
+          <v-progress-linear v-if="records.isRefetching.value" indeterminate class="mb-3" />
+
+          <div v-if="records.items.value.length < 1" class="text-center py-6 text-medium-emphasis">
+            No records yet.
+          </div>
+          <v-table v-else density="comfortable">
+            <thead>
+              <tr>
+__JSKIT_UI_LIST_HEADER_COLUMNS__
+                <th v-if="UI_VIEW_URL" class="text-right">Open</th>
+                <th v-if="UI_EDIT_URL" class="text-right">Edit</th>
+              </tr>
+            </thead>
+            <tbody>
+              <tr v-for="(record, index) in records.items.value" :key="records.resolveRowKey(record, index)">
+__JSKIT_UI_LIST_ROW_COLUMNS__
+                <td v-if="UI_VIEW_URL" class="text-right">
+                  <v-btn
+                    size="small"
+                    variant="text"
+                    :to="records.resolveViewUrl(record)"
+                    :disabled="!records.resolveViewUrl(record)"
+                  >
+                    Open
+                  </v-btn>
+                </td>
+                <td v-if="UI_EDIT_URL" class="text-right">
+                  <v-btn
+                    size="small"
+                    variant="text"
+                    :to="records.resolveEditUrl(record)"
+                    :disabled="!records.resolveEditUrl(record)"
+                  >
+                    Edit
+                  </v-btn>
+                </td>
+              </tr>
+            </tbody>
+          </v-table>
+
+          <div v-if="records.hasMore.value" class="d-flex justify-center pt-4">
+            <v-btn variant="text" :loading="records.isLoadingMore.value" @click="records.loadMore">Load more</v-btn>
+          </div>
+        </template>
+      </v-card-text>
+    </v-card>
+  </section>
+</template>
+
+<script setup>
+import { useList } from "@jskit-ai/users-web/client/composables/useList";
+
+const UI_OPERATION_ADAPTER = null;
+const UI_RECORD_ID_PARAM = "${option:id-param|trim}";
+const UI_LIST_API_URL = "${option:api-path|trim}";
+const UI_VIEW_URL = __JSKIT_UI_HAS_VIEW_ROUTE__ ? `./:${UI_RECORD_ID_PARAM}` : "";
+const UI_EDIT_URL = __JSKIT_UI_HAS_EDIT_ROUTE__ ? `./:${UI_RECORD_ID_PARAM}/edit` : "";
+const UI_NEW_URL = __JSKIT_UI_HAS_NEW_ROUTE__ ? "./new" : "";
+const UI_RECORD_CHANGED_EVENT = __JSKIT_UI_RECORD_CHANGED_EVENT__;
+
+const records = useList({
+  adapter: UI_OPERATION_ADAPTER || undefined,
+  apiSuffix: UI_LIST_API_URL,
+  queryKeyFactory: (surfaceId = "", workspaceSlug = "") => [
+    "ui-generator",
+    "${option:namespace|kebab}",
+    "list",
+    String(surfaceId || ""),
+    String(workspaceSlug || "")
+  ],
+  placementSource: "ui-generator.${option:namespace|kebab}.list",
+  fallbackLoadError: "Unable to load records.",
+  recordIdParam: UI_RECORD_ID_PARAM,
+  recordIdSelector: (item = {}) => __JSKIT_UI_LIST_RECORD_ID_EXPR__,
+  viewUrlTemplate: UI_VIEW_URL,
+  editUrlTemplate: UI_EDIT_URL,
+  realtime: UI_RECORD_CHANGED_EVENT
+    ? {
+        event: UI_RECORD_CHANGED_EVENT
+      }
+    : null
+});
+</script>

package/templates/src/pages/admin/ui-generator/NewElement.vue

@@ -0,0 +1,114 @@
+<template>
+  <section class="ui-generator-new-element d-flex flex-column ga-4">
+    <v-card rounded="lg" elevation="1" border>
+      <v-card-item>
+        <div class="d-flex align-center ga-3 flex-wrap w-100">
+          <div>
+            <v-card-title class="px-0">New ${option:namespace|singular|pascal|default(Record)}</v-card-title>
+            <v-card-subtitle class="px-0">Create a new ${option:namespace|singular|default(record)}.</v-card-subtitle>
+          </div>
+          <v-spacer />
+          <v-btn v-if="UI_LIST_URL" variant="text" :to="formRuntime.addEdit.resolveParams(UI_LIST_URL)">Cancel</v-btn>
+          <v-btn
+            color="primary"
+            :loading="formRuntime.addEdit.isSaving"
+            :disabled="
+              formRuntime.addEdit.isInitialLoading ||
+              formRuntime.addEdit.isRefetching ||
+              !formRuntime.addEdit.canSave
+            "
+            @click="formRuntime.addEdit.submit"
+          >
+            Save ${option:namespace|singular|default(record)}
+          </v-btn>
+        </div>
+      </v-card-item>
+      <v-divider />
+      <v-card-text class="pt-4">
+        <p v-if="formRuntime.addEdit.loadError" class="text-body-2 text-medium-emphasis mb-0">
+          {{ formRuntime.addEdit.loadError }}
+        </p>
+        <v-form v-else @submit.prevent="formRuntime.addEdit.submit" novalidate>
+          <v-row>
+            <v-col v-for="field in formRuntime.formFields" :key="field.key" cols="12" md="6">
+              <v-switch
+                v-if="field.component === 'switch'"
+                v-model="formRuntime.form[field.key]"
+                :label="field.label"
+                color="primary"
+                hide-details="auto"
+                :disabled="
+                  !formRuntime.addEdit.canSave ||
+                  formRuntime.addEdit.isSaving ||
+                  formRuntime.addEdit.isRefetching
+                "
+                :error-messages="formRuntime.resolveFieldErrors(field.key)"
+              />
+              <v-text-field
+                v-else
+                v-model="formRuntime.form[field.key]"
+                :label="field.label"
+                :type="field.inputType"
+                variant="outlined"
+                density="comfortable"
+                :maxlength="field.maxLength || undefined"
+                :readonly="
+                  !formRuntime.addEdit.canSave ||
+                  formRuntime.addEdit.isSaving ||
+                  formRuntime.addEdit.isRefetching
+                "
+                :error-messages="formRuntime.resolveFieldErrors(field.key)"
+              />
+            </v-col>
+          </v-row>
+        </v-form>
+      </v-card-text>
+    </v-card>
+  </section>
+</template>
+
+<script setup>
+import { useCrudSchemaForm } from "@jskit-ai/users-web/client/composables/useCrudSchemaForm";
+import { ${option:resource-export|trim} as uiResource } from "/${option:resource-file|trim}";
+
+const UI_OPERATION_ADAPTER = null;
+const UI_RECORD_ID_PARAM = "${option:id-param|trim}";
+const UI_CREATE_API_URL = "${option:api-path|trim}";
+const UI_LIST_URL = __JSKIT_UI_HAS_LIST_ROUTE__ ? ".." : "";
+const UI_VIEW_URL = __JSKIT_UI_HAS_VIEW_ROUTE__ ? `../:${UI_RECORD_ID_PARAM}` : "";
+const UI_RECORD_CHANGED_EVENT = __JSKIT_UI_RECORD_CHANGED_EVENT__;
+const UI_CREATE_FORM_FIELDS = Object.freeze(__JSKIT_UI_CREATE_FORM_FIELDS__);
+
+const formRuntime = useCrudSchemaForm({
+  resource: uiResource,
+  operationName: "create",
+  formFields: UI_CREATE_FORM_FIELDS,
+  addEditOptions: {
+    adapter: UI_OPERATION_ADAPTER || undefined,
+    apiSuffix: UI_CREATE_API_URL,
+    queryKeyFactory: (surfaceId = "", workspaceSlug = "") => [
+      "ui-generator",
+      "${option:namespace|kebab}",
+      "create",
+      String(surfaceId || ""),
+      String(workspaceSlug || "")
+    ],
+    placementSource: "ui-generator.${option:namespace|kebab}.new",
+    readEnabled: false,
+    writeMethod: "POST",
+    fallbackSaveError: "Unable to save record.",
+    recordIdParam: UI_RECORD_ID_PARAM,
+    viewUrlTemplate: UI_VIEW_URL,
+    listUrlTemplate: UI_LIST_URL,
+    realtime: UI_RECORD_CHANGED_EVENT
+      ? {
+          event: UI_RECORD_CHANGED_EVENT
+        }
+      : null
+  },
+  saveSuccess: {
+    invalidateQueryKey: ["ui-generator", "${option:namespace|kebab}"],
+    listUrlTemplate: UI_LIST_URL
+  }
+});
+</script>

package/templates/src/pages/admin/ui-generator/ViewElement.vue

@@ -0,0 +1,71 @@
+<template>
+  <section class="ui-generator-view-element d-flex flex-column ga-4">
+    <v-card rounded="lg" elevation="1" border>
+      <v-card-item>
+        <div class="d-flex align-center ga-3 flex-wrap w-100">
+          <div>
+            <v-card-title class="px-0">${option:namespace|singular|pascal|default(Record)}</v-card-title>
+            <v-card-subtitle class="px-0">View and manage this ${option:namespace|singular|default(record)}.</v-card-subtitle>
+          </div>
+          <v-spacer />
+          <v-btn v-if="UI_LIST_URL" variant="text" :to="view.resolveParams(UI_LIST_URL)">Back to ${option:namespace|plural|default(records)}</v-btn>
+          <v-btn v-if="UI_EDIT_URL" color="primary" variant="outlined" :to="view.resolveParams(UI_EDIT_URL)">Edit</v-btn>
+        </div>
+      </v-card-item>
+      <v-divider />
+      <v-card-text class="pt-4">
+        <div v-if="view.loadError.value || view.isNotFound.value" class="text-body-2 text-medium-emphasis py-2">
+          Record unavailable.
+        </div>
+
+        <template v-else-if="view.isLoading.value">
+          <v-skeleton-loader type="text@2, list-item-two-line@5" />
+        </template>
+
+        <template v-else>
+          <v-progress-linear v-if="view.isRefetching.value" indeterminate class="mb-4" />
+          <v-row>
+__JSKIT_UI_VIEW_COLUMNS__
+          </v-row>
+        </template>
+      </v-card-text>
+    </v-card>
+  </section>
+</template>
+
+<script setup>
+import { useView } from "@jskit-ai/users-web/client/composables/useView";
+
+const UI_OPERATION_ADAPTER = null;
+const UI_RECORD_ID_PARAM = "${option:id-param|trim}";
+const UI_API_BASE_URL = "${option:api-path|trim}";
+const UI_VIEW_API_URL = `${UI_API_BASE_URL}/:${UI_RECORD_ID_PARAM}`;
+const UI_LIST_URL = __JSKIT_UI_HAS_LIST_ROUTE__ ? ".." : "";
+const UI_EDIT_URL = __JSKIT_UI_HAS_EDIT_ROUTE__ ? "./edit" : "";
+const UI_RECORD_CHANGED_EVENT = __JSKIT_UI_RECORD_CHANGED_EVENT__;
+
+const view = useView({
+  adapter: UI_OPERATION_ADAPTER || undefined,
+  apiUrlTemplate: UI_VIEW_API_URL,
+  recordIdParam: UI_RECORD_ID_PARAM,
+  includeRecordIdInQueryKey: true,
+  queryKeyFactory: (surfaceId = "", workspaceSlug = "") => [
+    "ui-generator",
+    "${option:namespace|kebab}",
+    "view",
+    String(surfaceId || ""),
+    String(workspaceSlug || "")
+  ],
+  placementSource: "ui-generator.${option:namespace|kebab}.view",
+  fallbackLoadError: "Unable to load record.",
+  notFoundMessage: "Record not found.",
+  listUrlTemplate: UI_LIST_URL,
+  editUrlTemplate: UI_EDIT_URL,
+  realtime: UI_RECORD_CHANGED_EVENT
+    ? {
+        event: UI_RECORD_CHANGED_EVENT
+      }
+    : null
+});
+
+</script>

package/test/buildTemplateContext.test.js

@@ -0,0 +1,331 @@
+import assert from "node:assert/strict";
+import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { buildUiTemplateContext } from "../src/server/buildTemplateContext.js";
+
+async function withTempApp(run) {
+  const appRoot = await mkdtemp(path.join(tmpdir(), "ui-generator-app-"));
+  try {
+    return await run(appRoot);
+  } finally {
+    await rm(appRoot, { recursive: true, force: true });
+  }
+}
+
+async function writeResource(appRoot, relativeFile, source) {
+  const absoluteFile = path.join(appRoot, relativeFile);
+  await mkdir(path.dirname(absoluteFile), { recursive: true });
+  await writeFile(absoluteFile, source, "utf8");
+}
+
+const FULL_RESOURCE_SOURCE = `const customerRecordSchema = {
+  type: "object",
+  properties: {
+    id: { type: "integer" },
+    firstName: { type: "string" },
+    email: { type: "string" },
+    vip: { type: "boolean" },
+    updatedAt: { type: "string", format: "date-time" }
+  },
+  additionalProperties: false
+};
+
+const customerBodySchema = {
+  type: "object",
+  properties: {
+    firstName: { type: "string", maxLength: 120 },
+    email: { type: "string", maxLength: 160 },
+    vip: { type: "boolean" }
+  },
+  additionalProperties: false
+};
+
+const customerResource = {
+  operations: {
+    list: {
+      outputValidator: {
+        schema: {
+          type: "object",
+          properties: {
+            items: {
+              type: "array",
+              items: customerRecordSchema
+            },
+            nextCursor: { type: ["string", "null"] }
+          },
+          additionalProperties: false
+        }
+      }
+    },
+    view: {
+      outputValidator: {
+        schema: customerRecordSchema
+      }
+    },
+    create: {
+      bodyValidator: {
+        schema: customerBodySchema
+      },
+      outputValidator: {
+        schema: customerRecordSchema
+      }
+    },
+    patch: {
+      bodyValidator: {
+        schema: customerBodySchema
+      },
+      outputValidator: {
+        schema: customerRecordSchema
+      }
+    }
+  }
+};
+
+export { customerResource };
+`;
+
+test("buildUiTemplateContext derives list/view/new/edit placeholders from resource validators", async () => {
+  await withTempApp(async (appRoot) => {
+    const resourceFile = "packages/customers/src/shared/customerResource.js";
+    await writeResource(appRoot, resourceFile, FULL_RESOURCE_SOURCE);
+
+    const context = await buildUiTemplateContext({
+      appRoot,
+      options: {
+        namespace: "customers-ui",
+        "api-path": "/crud/customers",
+        operations: "list,view,new,edit",
+        "resource-file": resourceFile,
+        "resource-export": "customerResource"
+      }
+    });
+
+    assert.match(context.__JSKIT_UI_LIST_HEADER_COLUMNS__, /<th>First Name<\/th>/);
+    assert.match(context.__JSKIT_UI_LIST_ROW_COLUMNS__, /record\.updatedAt/);
+    assert.match(context.__JSKIT_UI_VIEW_COLUMNS__, /view\.record\.value\?\.vip/);
+    assert.equal(context.__JSKIT_UI_LIST_RECORD_ID_EXPR__, "item.id");
+    assert.equal(context.__JSKIT_UI_RECORD_CHANGED_EVENT__, "\"customers.record.changed\"");
+    assert.equal(context.__JSKIT_UI_HAS_LIST_ROUTE__, "true");
+    assert.equal(context.__JSKIT_UI_HAS_VIEW_ROUTE__, "true");
+    assert.equal(context.__JSKIT_UI_HAS_NEW_ROUTE__, "true");
+    assert.equal(context.__JSKIT_UI_HAS_EDIT_ROUTE__, "true");
+
+    const createFields = JSON.parse(context.__JSKIT_UI_CREATE_FORM_FIELDS__);
+    const editFields = JSON.parse(context.__JSKIT_UI_EDIT_FORM_FIELDS__);
+    assert.deepEqual(
+      createFields.map((field) => field.key),
+      ["firstName", "email", "vip"]
+    );
+    assert.deepEqual(
+      editFields.map((field) => field.key),
+      ["firstName", "email", "vip"]
+    );
+    assert.equal(createFields[0].inputType, "text");
+    assert.equal(createFields[0].maxLength, 120);
+    assert.equal(createFields[2].component, "switch");
+  });
+});
+
+test('buildUiTemplateContext derives "resource-export" default from resource-file basename', async () => {
+  await withTempApp(async (appRoot) => {
+    const resourceFile = "packages/customers/src/shared/customerResource.js";
+    await writeResource(appRoot, resourceFile, FULL_RESOURCE_SOURCE);
+
+    const context = await buildUiTemplateContext({
+      appRoot,
+      options: {
+        namespace: "customers-ui",
+        "api-path": "/crud/customers",
+        operations: "list,view",
+        "resource-file": resourceFile
+      }
+    });
+
+    assert.equal(context.__JSKIT_UI_RECORD_CHANGED_EVENT__, "\"customers.record.changed\"");
+    assert.equal(context.__JSKIT_UI_HAS_LIST_ROUTE__, "true");
+    assert.equal(context.__JSKIT_UI_HAS_VIEW_ROUTE__, "true");
+  });
+});
+
+test("buildUiTemplateContext filters rendered fields when display-fields is provided", async () => {
+  await withTempApp(async (appRoot) => {
+    const resourceFile = "packages/customers/src/shared/customerResource.js";
+    await writeResource(appRoot, resourceFile, FULL_RESOURCE_SOURCE);
+
+    const context = await buildUiTemplateContext({
+      appRoot,
+      options: {
+        namespace: "customers-ui",
+        "api-path": "/crud/customers",
+        operations: "list,view,new,edit",
+        "resource-file": resourceFile,
+        "resource-export": "customerResource",
+        "display-fields": "firstName,email"
+      }
+    });
+
+    assert.match(context.__JSKIT_UI_LIST_HEADER_COLUMNS__, /<th>First Name<\/th>/);
+    assert.match(context.__JSKIT_UI_LIST_HEADER_COLUMNS__, /<th>Email<\/th>/);
+    assert.doesNotMatch(context.__JSKIT_UI_LIST_HEADER_COLUMNS__, /<th>Id<\/th>/);
+    assert.match(context.__JSKIT_UI_VIEW_COLUMNS__, /view\.record\.value\?\.firstName/);
+    assert.match(context.__JSKIT_UI_VIEW_COLUMNS__, /view\.record\.value\?\.email/);
+    assert.doesNotMatch(context.__JSKIT_UI_VIEW_COLUMNS__, /view\.record\.value\?\.vip/);
+
+    const createFields = JSON.parse(context.__JSKIT_UI_CREATE_FORM_FIELDS__);
+    const editFields = JSON.parse(context.__JSKIT_UI_EDIT_FORM_FIELDS__);
+    assert.deepEqual(
+      createFields.map((field) => field.key),
+      ["firstName", "email"]
+    );
+    assert.deepEqual(
+      editFields.map((field) => field.key),
+      ["firstName", "email"]
+    );
+  });
+});
+
+test("buildUiTemplateContext fails when display-fields includes unknown keys", async () => {
+  await withTempApp(async (appRoot) => {
+    const resourceFile = "packages/customers/src/shared/customerResource.js";
+    await writeResource(appRoot, resourceFile, FULL_RESOURCE_SOURCE);
+
+    await assert.rejects(
+      () =>
+        buildUiTemplateContext({
+          appRoot,
+          options: {
+            namespace: "customers-ui",
+            "api-path": "/crud/customers",
+            operations: "list,view,new,edit",
+            "resource-file": resourceFile,
+            "resource-export": "customerResource",
+            "display-fields": "firstName,unknownField"
+          }
+        }),
+      /display-fields" includes unsupported field\(s\)/
+    );
+  });
+});
+
+test("buildUiTemplateContext supports list-only resources when operations=list", async () => {
+  await withTempApp(async (appRoot) => {
+    const resourceFile = "packages/customers/src/shared/listOnlyResource.js";
+    await writeResource(
+      appRoot,
+      resourceFile,
+      `const listOnlyResource = {
+  operations: {
+    list: {
+      outputValidator: {
+        schema: {
+          type: "object",
+          properties: {
+            items: {
+              type: "array",
+              items: {
+                type: "object",
+                properties: {
+                  id: { type: "integer" },
+                  fullName: { type: "string" }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+};
+
+export { listOnlyResource };
+`
+    );
+
+    const context = await buildUiTemplateContext({
+      appRoot,
+      options: {
+        namespace: "customers-ui",
+        "api-path": "/crud/customers",
+        operations: "list",
+        "resource-file": resourceFile,
+        "resource-export": "listOnlyResource"
+      }
+    });
+
+    assert.equal(context.__JSKIT_UI_HAS_LIST_ROUTE__, "true");
+    assert.equal(context.__JSKIT_UI_HAS_VIEW_ROUTE__, "false");
+    assert.equal(context.__JSKIT_UI_HAS_NEW_ROUTE__, "false");
+    assert.equal(context.__JSKIT_UI_HAS_EDIT_ROUTE__, "false");
+    assert.equal(context.__JSKIT_UI_CREATE_FORM_FIELDS__, "[]");
+    assert.equal(context.__JSKIT_UI_EDIT_FORM_FIELDS__, "[]");
+  });
+});
+
+test("buildUiTemplateContext supports view-only resources when operations=view", async () => {
+  await withTempApp(async (appRoot) => {
+    const resourceFile = "packages/customers/src/shared/viewOnlyResource.js";
+    await writeResource(
+      appRoot,
+      resourceFile,
+      `const viewOnlyResource = {
+  operations: {
+    view: {
+      outputValidator: {
+        schema: {
+          type: "object",
+          properties: {
+            id: { type: "integer" },
+            fullName: { type: "string" }
+          }
+        }
+      }
+    }
+  }
+};
+
+export { viewOnlyResource };
+`
+    );
+
+    const context = await buildUiTemplateContext({
+      appRoot,
+      options: {
+        namespace: "customers-ui",
+        "api-path": "/crud/customers",
+        operations: "view",
+        "resource-file": resourceFile,
+        "resource-export": "viewOnlyResource"
+      }
+    });
+
+    assert.equal(context.__JSKIT_UI_HAS_LIST_ROUTE__, "false");
+    assert.equal(context.__JSKIT_UI_HAS_VIEW_ROUTE__, "true");
+    assert.equal(context.__JSKIT_UI_HAS_NEW_ROUTE__, "false");
+    assert.equal(context.__JSKIT_UI_HAS_EDIT_ROUTE__, "false");
+    assert.equal(context.__JSKIT_UI_RECORD_CHANGED_EVENT__, "\"customers.record.changed\"");
+  });
+});
+
+test("buildUiTemplateContext fails when operations option is invalid", async () => {
+  await withTempApp(async (appRoot) => {
+    const resourceFile = "packages/customers/src/shared/customerResource.js";
+    await writeResource(appRoot, resourceFile, FULL_RESOURCE_SOURCE);
+
+    await assert.rejects(
+      () =>
+        buildUiTemplateContext({
+          appRoot,
+          options: {
+            namespace: "customers-ui",
+            "api-path": "/crud/customers",
+            operations: "create",
+            "resource-file": resourceFile,
+            "resource-export": "customerResource"
+          }
+        }),
+      /operations" supports only: list, view, new, edit/
+    );
+  });
+});