@kematjaya/crud-ui-generator 0.4.0 → 0.6.0

package/README.md

@@ -1,94 +1,196 @@
 # @kematjaya/crud-ui-generator
 
-Next.js CRUD frontend generator that reads the `crud-specs/{Entity}.json` sidecar written by
-[kematjaya/crud-maker-bundle](https://github.com/kematjaya0/crud-maker-bundle)'s
-`make:kmj-api-crud`, and generates pages, components, and BFF routes matching the shape of a
-hand-written CRUD feature (list/create/edit pages, table with search/pagination/bulk-delete/CSV
-export, form, BFF proxy routes).
+Generator frontend CRUD untuk Next.js yang membaca sidecar `crud-specs/{Entity}.json` yang
+ditulis oleh `make:kmj-api-crud` dari
+[kematjaya/crud-maker-bundle](https://github.com/kematjaya0/crud-maker-bundle), lalu
+menghasilkan halaman, komponen, dan BFF routes dengan bentuk yang sama seperti fitur CRUD yang
+ditulis manual (halaman list/create/edit, tabel dengan search/pagination/bulk-delete/export CSV,
+form, BFF proxy routes).
+
+Ini adalah code generator yang dijalankan saat development (seperti Plop/Hygen), bukan library
+komponen runtime. Generator ini menyasar project yang sudah mengikuti konvensi Next.js di
+monorepo ini:
+
+- `@kematjaya/bootstrap-ui-kit` untuk `ListPageCard`/`TextField`/`Button`/dll.
+- `@kematjaya/access-control-ui` untuk `usePermissions()`
+- `src/lib/http.ts`, `src/lib/bff.ts` (helper proxy BFF — `authedBackend`, `validateOrigin`, `parseJson`, `jsonProblem`)
+- `src/lib/permissions.ts` yang meng-export `requirePermission()`
+- `src/types/api.ts` + `src/types/api.generated.ts` (tipe dari OpenAPI via `openapi-typescript`)
+- `react-select` — hanya kalau ada entity dengan field relasi (`"type": "relation"`); form hasil
+  generate untuk field itu meng-`import AsyncSelect from 'react-select/async'` langsung, jadi
+  `npm install react-select` di project frontend sebelum menjalankan generator untuk entity
+  semacam itu.
+
+Ini bukan scaffolder Next.js serba-guna — menjalankannya pada project yang belum punya
+komponen-komponen di atas akan menghasilkan file yang tidak bisa di-compile sampai Anda
+menambahkannya.
+
+## Instalasi
+
+Tidak perlu instalasi terpisah untuk pemakaian sekali pakai — `npx` akan mengambilnya otomatis:
 
-This is a dev-time code generator (like Plop/Hygen), not a runtime component library. It targets
-projects that already follow this monorepo's Next.js conventions:
+```
+npx @kematjaya/crud-ui-generator <spec-path> [--src <dir>]
+```
 
-- `@kematjaya/bootstrap-ui-kit` for `ListPageCard`/`TextField`/`Button`/etc.
-- `@kematjaya/access-control-ui` for `usePermissions()`
-- `src/lib/http.ts`, `src/lib/bff.ts` (BFF proxy helpers — `authedBackend`, `validateOrigin`, `parseJson`, `jsonProblem`)
-- `src/lib/permissions.ts` exporting `requirePermission()`
-- `src/types/api.ts` + `src/types/api.generated.ts` (OpenAPI types via `openapi-typescript`)
+Kalau ingin dipasang sebagai dev dependency permanen alih-alih `npx` setiap kali:
 
-It is not a general-purpose Next.js scaffolder — running it against a project that doesn't already
-have those pieces will produce files that don't compile until you add them.
+```
+npm install --save-dev @kematjaya/crud-ui-generator
+```
 
-## Usage
+## Cara pakai
 
 ```
 npx @kematjaya/crud-ui-generator <spec-path> [--src <dir>]
 ```
 
-- `<spec-path>` — path to the `crud-specs/{Entity}.json` file written by `make:kmj-api-crud`.
-- `--src <dir>` — the frontend project's `src/` directory to generate into (default: `src`).
+- `<spec-path>` — path ke file `crud-specs/{Entity}.json` yang ditulis oleh `make:kmj-api-crud`.
+- `--src <dir>` — direktori `src/` project frontend tempat hasil generate ditulis (default: `src`).
 
-Example, run from the frontend project root, with the backend as a sibling directory:
+Contoh, dijalankan dari root project frontend, dengan backend sebagai direktori bertetangga:
 
 ```
 npx @kematjaya/crud-ui-generator ../backend/crud-specs/Note.json --src src
 ```
 
-## What it generates
+## Apa saja yang di-generate
 
-Per entity (skipped if the file already exists — safe to re-run):
+Per entity (dilewati kalau file sudah ada — aman dijalankan ulang):
 
 - `app/dashboard/{entities}/page.tsx`, `new/page.tsx`, `[id]/edit/page.tsx`
 - `components/{entities}/{Entity}Table.tsx`, `{Entity}Form.tsx`, `use{Entities}Export.ts`
 - `lib/{entities}-query.ts`, `lib/{entities}-csv.ts`
 - `app/api/{entities}/route.ts`, `[id]/route.ts`, `export/route.ts` (BFF proxy)
 
-Shared, entity-agnostic UI primitives (written once, reused by every entity):
+Primitive UI yang dipakai bersama, tidak spesifik ke satu entity (ditulis sekali, dipakai ulang
+oleh semua entity):
 
 - `components/crud/DeleteConfirmModal.tsx`, `BulkActionsBar.tsx`, `PaginationBar.tsx`,
   `SearchPanel.tsx`, `ExportAllButton.tsx`
 
-Appended to (multi-entity, idempotent — each entity gets one marker-guarded block):
-
-- `lib/api-shapes.ts` — `is{Entity}`/`is{Entity}Collection` type guards
-- `lib/schemas.ts` — a Zod schema per entity
-- `types/api.ts` — types derived from the OpenAPI-generated `paths`/`components`
-
-## Assumptions / caveats
-
-- **Id type comes from the spec's `idType`** (`uuid`/`int`/`string`, written by `ApiCrudRenderer::detectIdType()` off the entity's actual id column) — `validId()` in the generated `[id]/route.ts` and the `is{Entity}` type guard in `api-shapes.ts` are generated to match. Older spec files without `idType` default to `uuid`.
-- **The list filter panel covers every `searchable` field except `textarea`, `date`, and
-  `datetime`.** `naming.ts`'s `filterableFields()` renders one control per remaining field —
-  text/number inputs (ApiPlatform `SearchFilter` `'partial'`/`'exact'` strategy) and a boolean
-  Any/Yes/No select (`'exact'`) — all AND-combined into the same list query (one query param per
-  property, backed by a single `#[ApiFilter(SearchFilter::class, properties: [...])]` on the
-  entity). The table's collapsible Filter button toggles a `crud-filter-collapse` panel around
-  the generated `FilterPanel` component, and only appears when at least one field is filterable.
-  Excluded `searchable` fields get a `cli.ts` next-steps note — no date-range filter control
-  exists yet (a future iteration), and long text isn't a sensible filter input.
-- **CSV export ("Export all") only reflects the first filterable field's current value**, sent as
-  a single OR-search `search` param the backend matches across *every* `searchable` field
-  (textarea included) server-side — a separate, broader contract from the list's precise
-  AND-per-property filtering. The other filter panel fields don't currently narrow the export.
-- **`date`/`datetime` fields are real form fields and table/CSV columns.** Backed by
-  `ui-kit`'s `DateField`/`DateTimeField` (native `<input type="date">`/`type="datetime-local">`).
-  `date` fields round-trip as plain `"Y-m-d"` strings — the backend maker writes a
-  `config/serializer/{Entity}.yaml` Symfony serializer mapping pinning that format (otherwise
-  Symfony's default `DateTimeNormalizer` would emit a full RFC3339 datetime with a spurious
-  time/timezone for a date-only column). `datetime` fields keep the default RFC3339 wire format;
-  the generated form converts to/from `<input type="datetime-local">`'s local-wall-clock string
-  via `src/lib/datetime.ts` (written once, shared across entities) at the `reset()`/`submit()`
-  boundaries — the `Date` constructor's local-time parsing makes this conversion timezone-safe.
-- **The table/CSV export skip `textarea` fields** (long text), mirroring the hand-written Notes
-  feature (shows `title`, not `body`). Everything else (`text`/`number`/`boolean`/`date`/
-  `datetime`) becomes a column.
-- **Getters are assumed on the entity/generated types** in the conventional `get{Field}()` /
-  camelCase-property shape used throughout this boilerplate.
-- **`npm run api:types` must be run first** (after adding the backend's `#[ApiResource]`/
-  `#[ApiFilter]` attributes — see `make:kmj-api-crud`'s printed next-steps) so
-  `src/types/api.ts`'s `paths['/api/{entities}']` / `components['schemas'][...]` lookups resolve.
-  If the entity's `#[ApiResource]` uses a custom `uriTemplate` that doesn't match
-  `permissionPrefix`, fix those lookups by hand.
-- Generated files aren't run through Prettier — run `npm run format` afterwards.
+Ditambahkan ke (multi-entity, idempotent — tiap entity dapat satu blok yang dijaga marker):
+
+- `lib/api-shapes.ts` — type guard `is{Entity}`/`is{Entity}Collection`
+- `lib/schemas.ts` — satu Zod schema per entity
+- `types/api.ts` — tipe hasil turunan dari `paths`/`components` OpenAPI
+
+## Asumsi / catatan penting
+
+- **Tipe id diambil dari `idType` di spec** (`uuid`/`int`/`string`, ditulis oleh
+  `ApiCrudRenderer::detectIdType()` berdasarkan kolom id sebenarnya di entity) — `validId()` di
+  `[id]/route.ts` hasil generate dan type guard `is{Entity}` di `api-shapes.ts` dibuat
+  menyesuaikan. Spec lama tanpa `idType` default ke `uuid`.
+- **Panel filter di halaman list mencakup semua field `searchable` kecuali `textarea`, `date`,
+  dan `datetime`.** `filterableFields()` di `naming.ts` merender satu kontrol per field yang
+  tersisa — input text/number (strategi ApiPlatform `SearchFilter` `'partial'`/`'exact'`) dan
+  select boolean Any/Yes/No (`'exact'`) — semuanya digabung dengan AND dalam satu query list
+  (satu query param per properti, didukung satu
+  `#[ApiFilter(SearchFilter::class, properties: [...])]` di entity). Tombol Filter yang bisa
+  dilipat di tabel membuka panel `crud-filter-collapse` berisi komponen `FilterPanel` hasil
+  generate, dan hanya muncul kalau minimal satu field bisa difilter. Field `searchable` yang
+  dikecualikan akan dapat catatan next-steps di `cli.ts` — belum ada kontrol filter rentang
+  tanggal (iterasi berikutnya), dan teks panjang memang bukan input filter yang masuk akal.
+- **Export CSV ("Export all") hanya mencerminkan nilai field filterable pertama saat ini**,
+  dikirim sebagai satu parameter `search` (OR-search) yang di backend dicocokkan ke *semua*
+  field `searchable` (termasuk textarea) — kontrak yang berbeda dan lebih longgar dari filter
+  AND-per-properti yang presisi di halaman list. Field filter lain belum mempersempit hasil
+  export.
+- **Field `date`/`datetime` adalah field form dan kolom tabel/CSV sungguhan.** Didukung
+  `DateField`/`DateTimeField` dari `ui-kit` (native `<input type="date">`/
+  `type="datetime-local">`). Field `date` bolak-balik sebagai string `"Y-m-d"` polos — maker di
+  sisi backend menulis mapping serializer Symfony `config/serializer/{Entity}.yaml` yang
+  mengunci format itu (kalau tidak, `DateTimeNormalizer` default Symfony akan menghasilkan
+  datetime RFC3339 lengkap dengan jam/timezone yang tidak seharusnya ada untuk kolom
+  date-only). Field `datetime` tetap pakai format wire RFC3339 default; form hasil generate
+  mengonversi ke/dari string local-wall-clock `<input type="datetime-local">` lewat
+  `src/lib/datetime.ts` (ditulis sekali, dipakai bersama semua entity) di boundary
+  `reset()`/`submit()` — parsing local-time dari constructor `Date` membuat konversi ini aman
+  terhadap timezone.
+- **Tabel/export CSV melewati field `textarea`** (teks panjang), meniru fitur Notes yang ditulis
+  manual (menampilkan `title`, bukan `body`). Selain itu (`text`/`number`/`boolean`/`date`/
+  `datetime`) menjadi kolom.
+- **Field relasi ManyToOne (`"type": "relation"`) dirender sebagai `react-select` `AsyncSelect`
+  bertipe pencarian server-side**, bukan `<select>` native — cocok untuk daftar terkait yang bisa
+  bertambah banyak (dropdown biasa hanya nyaman untuk puluhan opsi statis). Field ini butuh
+  metadata tambahan di spec, tidak ditebak dari nama:
+  ```json
+  {
+      "name": "category",
+      "type": "relation",
+      "required": true,
+      "searchable": false,
+      "relatedEntity": "Category",
+      "relatedApiResourcePath": "/api/categories",
+      "relatedFrontendPath": "/api/categories",
+      "displayField": "name",
+      "searchParam": "name"
+  }
+  ```
+  - `relatedEntity` — nama PascalCase entity terkait (harus sudah pernah di-generate lebih dulu
+    lewat tool ini juga, minimal punya `is{RelatedEntity}`/`is{RelatedEntity}Collection` di
+    `lib/api-shapes.ts` dan tipe `{RelatedEntity}` di `types/api.ts` — generator ini tidak pernah
+    menulis keduanya untuk tipe yang belum pernah di-generate sendiri).
+  - `relatedApiResourcePath` dan `relatedFrontendPath` sengaja **dua field terpisah**, sama seperti
+    `apiResourcePath`/`permissionPrefix` di level entity (lihat catatan di bawah soal "fix url") —
+    JANGAN digabung jadi satu:
+    - `relatedApiResourcePath` — URI ApiPlatform asli milik entity terkait (dihitung sama seperti
+      `apiResourcePath`: `pluralize(tableize(relatedEntity))`), ditanam sebagai prefix IRI yang
+      dikirim balik ke backend sebagai value submit (`{relatedApiResourcePath}/{id}`). TIDAK
+      bergantung pada `permissionPrefix` entity terkait.
+    - `relatedFrontendPath` — URL yang dipanggil BROWSER untuk mencari opsi sambil mengetik
+      (dipakai sebagai `fetch` di `load{Field}Options` hasil generate). Ini BFF route frontend
+      milik entity terkait sendiri (`/api/{entitiesKebab-nya}`, dari `permissionPrefix` di spec-nya
+      sendiri) — ambil dari `crud-specs/{RelatedEntity}.json`-nya kalau sudah ada, jangan ditebak
+      di sini.
+    - Dalam kondisi normal keduanya sama persis (`permissionPrefix` default-nya memang plural yang
+      sama), tapi begitu `permissionPrefix` entity terkait dikustomisasi menyimpang, cuma
+      `relatedFrontendPath` yang perlu diperbaiki manual — `relatedApiResourcePath` tetap benar
+      karena tidak pernah bergantung padanya. Menggabungkan keduanya jadi satu field akan mengulang
+      persis bug yang pernah ditambal commit "fix url" untuk `apiResourcePath`/`permissionPrefix` di
+      level entity (permissionPrefix custom bikin frontend manggil URL yang tidak pernah di-serve
+      ApiPlatform → 404).
+  - `displayField` — properti di entity terkait yang ditampilkan sebagai label opsi (mis. `name`)
+    — field ini harus benar-benar ada di spec entity terkait sendiri.
+  - `searchParam` — nama query param yang dipakai list endpoint entity terkait untuk memfilter
+    berdasarkan `displayField` itu (biasanya sama persis dengan `displayField`, cocok dengan
+    `#[ApiFilter(SearchFilter::class, properties: [...])]` di entity terkait).
+  - Pencarian di-debounce 300ms di sisi client, dan defaultOptions memuat halaman pertama begitu
+    dropdown dibuka (tanpa perlu mengetik dulu) — meniru UX dropdown biasa tapi tanpa
+    menarik SELURUH koleksi terkait sekaligus ke browser.
+  - **Dikecualikan dari Filter panel dan CSV export** (baik "Export All" maupun "Export
+    Selected") — sama seperti `textarea`/`date`/`datetime` untuk filter, karena belum ada kontrol
+    filter untuk relasi; untuk CSV karena backend export-data controller (query builder kolom
+    flat, tanpa join) tidak generik bisa menarik properti entity terkait. Field relasi tetap
+    tampil sebagai kolom tabel (`item.{field}.{displayField}`) dan sebagai dropdown form.
+  - **PHP maker (`make:kmj-api-crud`) belum otomatis mendeteksi properti ManyToOne dan menulis
+    field relasi ini ke `crud-specs/{Entity}.json`** — untuk saat ini field relasi ditambahkan ke
+    spec JSON secara manual setelah entity dibuat. Ini murni perluasan generator frontend (`js/`);
+    mendeteksi ManyToOne otomatis di sisi PHP adalah pekerjaan terpisah di
+    `crud-maker-api-bundle`/`crud-maker-core`.
+- **Getter diasumsikan ada** pada entity/tipe hasil generate, dalam bentuk konvensional
+  `get{Field}()` / properti camelCase yang dipakai di seluruh boilerplate ini.
+- **`npm run api:types` harus dijalankan lebih dulu** (setelah atribut `#[ApiResource]`/
+  `#[ApiFilter]` backend ditambahkan — lihat next-steps yang dicetak `make:kmj-api-crud`) supaya
+  lookup `paths['/api/{entities}']` / `components['schemas'][...]` di `src/types/api.ts`
+  berhasil. Lookup ini berdasarkan `apiResourcePath` (catatan literal URI ApiPlatform
+  sebenarnya milik entity, dari spec), **bukan** `permissionPrefix` — kalau `#[ApiResource]`
+  entity memakai `uriTemplate` custom yang tidak cocok dengan `apiResourcePath`, atau project
+  meng-override `api_platform.path_segment_name_generator` dari default-nya, perbaiki lookup itu
+  secara manual.
+- **Panggilan BFF ke backend (`app/api/{entities}/route.ts`, `[id]/route.ts`,
+  `build{Entities}BackendPath` di `lib/{entities}-query.ts`) selalu memakai `apiResourcePath`
+  dari spec, tidak pernah `permissionPrefix`.** `permissionPrefix` hanya menamai route/folder
+  frontend sendiri dan permission key — nilainya bebas (free text) dan bisa berbeda dari URI
+  plural asli ApiPlatform (misalnya entity `Category` yang di-generate dengan
+  `permissionPrefix: "category"` tetap saja disajikan backend di `/api/categories`).
+  `apiResourcePath` ditulis oleh `make:kmj-api-crud` sebagai `pluralize(tableize($shortName))`,
+  meniru persis `path_segment_name_generator` default ApiPlatform — frontend wajib mengikuti
+  nilai ini apa adanya, karena backend digenerate lebih dulu dan menjadi satu-satunya sumber
+  kebenaran untuk URL miliknya sendiri. Spec lama dari sebelum field ini ada akan gagal dimuat
+  dengan pesan error yang jelas; tambahkan `"apiResourcePath"` secara manual (atau generate
+  ulang).
+- File hasil generate tidak melewati Prettier — jalankan `npm run format` setelahnya.
 
 ## Development
 

package/dist/cli.js

@@ -104,10 +104,14 @@ function main() {
     console.log(`  2. Run "npm run api:types" in the frontend project so src/types/api.ts's paths/components lookups resolve.`);
     console.log(`  3. Confirm the OpenAPI collection path is "/api/${names.entitiesKebab}" — if the entity's #[ApiResource] uses a custom uriTemplate, fix the "paths[...]" lookups in the appended src/types/api.ts block by hand.`);
     const excludedFilterFields = spec.fields
-        .filter((f) => f.searchable && ['textarea', 'date', 'datetime'].includes(f.type))
+        .filter((f) => f.searchable && ['textarea', 'date', 'datetime', 'relation'].includes(f.type))
         .map((f) => f.name);
     if (excludedFilterFields.length > 0) {
-        console.log(`  4. Note: "${excludedFilterFields.join(', ')}" ${excludedFilterFields.length > 1 ? 'are' : 'is'} marked searchable but excluded from the generated Filter panel (long text and date/datetime don't have a filter control yet) — long-text fields are also excluded from table/CSV columns.`);
+        console.log(`  4. Note: "${excludedFilterFields.join(', ')}" ${excludedFilterFields.length > 1 ? 'are' : 'is'} marked searchable but excluded from the generated Filter panel (long text, date/datetime, and relation fields don't have a filter control yet) — long-text and relation fields are also excluded from table/CSV columns.`);
+    }
+    const relationFields = spec.fields.filter((f) => f.type === 'relation');
+    if (relationFields.length > 0) {
+        console.log(`  5. Relation field(s) "${relationFields.map((f) => f.name).join(', ')}" each carry two related-entity paths that must stay correct independently: "relatedApiResourcePath" (the real ApiPlatform URI, embedded in the submitted IRI) and "relatedFrontendPath" (the related entity's own frontend BFF route, called by load{Field}Options while searching). They're normally identical, but diverge if the related entity's spec customized "permissionPrefix" away from its "apiResourcePath" plural — conflating them was exactly the bug this project's "fix url" commit fixed for top-level apiResourcePath/permissionPrefix, so don't collapse them back into one value.`);
     }
     console.log(`  Id type: "${spec.idType}" (from the spec's "idType") — validId() in the generated app/api/${names.entitiesKebab}/[id]/route.ts was generated to match.`);
     console.log(`  Run "npm run format" afterwards — generated files aren't pre-formatted to this project's Prettier config.`);

package/dist/naming.js

@@ -13,8 +13,12 @@ export function namesFromSpec(spec) {
     const entitiesCamel = entitiesPascal.charAt(0).toLowerCase() + entitiesPascal.slice(1);
     return { entityPascal, entityCamel, entitiesKebab, entitiesPascal, entitiesCamel };
 }
-/** Field types with no filter-panel control yet — excluded from `filterableFields()`. */
-const UNFILTERABLE_TYPES = ['textarea', 'date', 'datetime'];
+/**
+ * Field types with no filter-panel control yet — excluded from `filterableFields()`.
+ * `relation` has no filter control either (no generated support for filtering by a related
+ * entity's property yet) — same treatment as `date`/`datetime`.
+ */
+export const UNFILTERABLE_TYPES = ['textarea', 'date', 'datetime', 'relation'];
 /**
  * Fields rendered as controls in the list view's Filter panel: every `searchable` field except
  * `textarea` (long text doesn't make a sensible filter input) and `date`/`datetime` (no
@@ -48,7 +52,23 @@ export function lowerWords(identifier) {
 export function displayFields(spec) {
     return spec.fields.filter((f) => f.type !== 'textarea');
 }
-/** Field used to label a single row in delete-confirmation copy / aria-labels. */
+/**
+ * Field used to label a single row in delete-confirmation copy / aria-labels — rendered with
+ * `String(item.{label})`, so it must be a scalar (a relation field would stringify to
+ * "[object Object]").
+ */
 export function labelField(spec) {
-    return displayFields(spec)[0]?.name ?? spec.fields[0]?.name ?? 'id';
+    const scalarDisplay = displayFields(spec).filter((f) => f.type !== 'relation');
+    return scalarDisplay[0]?.name ?? spec.fields.find((f) => f.type !== 'relation')?.name ?? 'id';
+}
+/**
+ * Fields written into CSV export columns (`lib/{entities}-csv.ts`'s `Csv{Entity}` pick and the
+ * export BFF route's `Export{Entity}` shape): `displayFields()` minus `relation` — the backend's
+ * hand-rolled `findExportData()`-style query (a flat column `select()`, no join) has no generic
+ * way to pull a related entity's display property, so a relation column would need bespoke
+ * backend work per entity. Excluded here so generated export code doesn't assume a join that
+ * isn't there; the relation still shows as a table column and a form dropdown.
+ */
+export function exportableFields(spec) {
+    return displayFields(spec).filter((f) => f.type !== 'relation');
 }

package/dist/spec.js

@@ -1,13 +1,36 @@
 import { readFileSync } from 'node:fs';
+const SCALAR_TYPES = ['text', 'textarea', 'number', 'boolean', 'date', 'datetime'];
+function isRelationFieldSpec(f) {
+    return (f.type === 'relation' &&
+        typeof f.relatedEntity === 'string' &&
+        f.relatedEntity !== '' &&
+        typeof f.relatedApiResourcePath === 'string' &&
+        f.relatedApiResourcePath !== '' &&
+        typeof f.relatedFrontendPath === 'string' &&
+        f.relatedFrontendPath !== '' &&
+        typeof f.displayField === 'string' &&
+        f.displayField !== '' &&
+        typeof f.searchParam === 'string' &&
+        f.searchParam !== '');
+}
+function isScalarFieldSpec(f) {
+    return (SCALAR_TYPES.includes(f.type) &&
+        (f.maxLength === null || f.maxLength === undefined || typeof f.maxLength === 'number'));
+}
 function isFieldSpec(value) {
     if (typeof value !== 'object' || value === null)
         return false;
     const f = value;
-    return (typeof f.name === 'string' &&
-        ['text', 'textarea', 'number', 'boolean', 'date', 'datetime'].includes(f.type) &&
-        typeof f.required === 'boolean' &&
-        (f.maxLength === null || typeof f.maxLength === 'number') &&
-        typeof f.searchable === 'boolean');
+    if (typeof f.name !== 'string' || typeof f.required !== 'boolean' || typeof f.searchable !== 'boolean') {
+        return false;
+    }
+    return isRelationFieldSpec(f) || isScalarFieldSpec(f);
+}
+/** Fills in `maxLength: null` for scalar fields that omitted it (relation fields don't have one). */
+function normalizeField(field) {
+    if (field.type === 'relation')
+        return field;
+    return { ...field, maxLength: field.maxLength ?? null };
 }
 export function loadSpec(specPath) {
     let raw;
@@ -31,19 +54,29 @@ export function loadSpec(specPath) {
     if (typeof spec.entity !== 'string' || spec.entity === '') {
         throw new Error(`Spec file missing "entity": ${specPath}`);
     }
+    if (typeof spec.apiResourcePath !== 'string' || spec.apiResourcePath === '') {
+        throw new Error(`Spec file missing "apiResourcePath": ${specPath}\n` +
+            'Regenerate it with a current version of make:kmj-api-crud, or add the field by ' +
+            "hand — it must match the entity's real ApiPlatform collection/item URI (e.g. " +
+            '"/api/categories"), not a guess derived from "permissionPrefix" or "entity".');
+    }
     if (typeof spec.permissionPrefix !== 'string' || spec.permissionPrefix === '') {
         throw new Error(`Spec file missing "permissionPrefix": ${specPath}`);
     }
     if (!Array.isArray(spec.fields) || !spec.fields.every(isFieldSpec)) {
-        throw new Error(`Spec file "fields" is missing or malformed: ${specPath}`);
+        throw new Error(`Spec file "fields" is missing or malformed: ${specPath}\n` +
+            'Relation fields (type: "relation") require "relatedEntity", ' +
+            '"relatedApiResourcePath", "relatedFrontendPath", "displayField", and ' +
+            '"searchParam" — see spec.ts\'s RelationFieldSpec doc comment.');
     }
     const idType = spec.idType === 'int' || spec.idType === 'string' || spec.idType === 'uuid' ? spec.idType : 'uuid';
     return {
         entity: spec.entity,
+        apiResourcePath: spec.apiResourcePath,
         permissionPrefix: spec.permissionPrefix,
         ownerProperty: typeof spec.ownerProperty === 'string' ? spec.ownerProperty : null,
         timestampField: typeof spec.timestampField === 'string' ? spec.timestampField : null,
         idType,
-        fields: spec.fields,
+        fields: spec.fields.map(normalizeField),
     };
 }

package/dist/templates/apiShapes.js

@@ -16,12 +16,22 @@ export function apiShapesMarker(entityPascal) {
 export function apiShapesImport(names) {
     return `import type { ${names.entityPascal}, ${names.entitiesPascal}Collection } from '@/types/api';\n`;
 }
+function fieldCheck(field) {
+    // `is{RelatedEntity}` is a function *declaration* — hoisted, so it's callable here
+    // regardless of whether that entity's own block appears earlier or later in this same
+    // lib/api-shapes.ts file. It must exist in this file already (i.e. the related entity has
+    // already been through this generator) — this generator never writes it for a type it
+    // hasn't itself generated.
+    if (field.type === 'relation')
+        return `is${field.relatedEntity}(value.${field.name})`;
+    return `typeof value.${field.name} === '${tsType(field)}'`;
+}
 export function apiShapesBlock(spec, names) {
     const { entityPascal, entitiesPascal } = names;
     const idJsType = 'int' === spec.idType ? 'number' : 'string';
     const checks = ['isRecord(value)', `typeof value.id === '${idJsType}'`];
     for (const field of spec.fields) {
-        checks.push(`typeof value.${field.name} === '${tsType(field)}'`);
+        checks.push(fieldCheck(field));
     }
     if (null !== spec.timestampField) {
         checks.push(`typeof value.${spec.timestampField} === 'string'`);

package/dist/templates/bffRoutes.js

@@ -1,4 +1,4 @@
-import { displayFields, filterableFields } from '../naming.js';
+import { exportableFields, filterableFields } from '../naming.js';
 function tsType(field) {
     if (field.type === 'number')
         return 'number';
@@ -6,17 +6,18 @@ function tsType(field) {
         return 'boolean';
     return 'string';
 }
-export function listRoute(_spec, names) {
+export function listRoute(spec, names) {
     const { entityCamel, entitiesKebab } = names;
+    const backendPath = spec.apiResourcePath;
     return `import type { NextRequest } from 'next/server';
 import { authedBackend } from '@/lib/bff';
 import { parseJson, validateOrigin } from '@/lib/http';
-import { build${names.entitiesPascal}ApiPath, parse${names.entitiesPascal}Query } from '@/lib/${entitiesKebab}-query';
+import { build${names.entitiesPascal}ApiPath, build${names.entitiesPascal}BackendPath, parse${names.entitiesPascal}Query } from '@/lib/${entitiesKebab}-query';
 import { ${entityCamel}Schema } from '@/lib/schemas';
 
 export async function GET(request: NextRequest) {
     return authedBackend(
-        build${names.entitiesPascal}ApiPath(parse${names.entitiesPascal}Query(request.nextUrl.searchParams))
+        build${names.entitiesPascal}BackendPath(parse${names.entitiesPascal}Query(request.nextUrl.searchParams))
     );
 }
 
@@ -25,7 +26,7 @@ export async function POST(request: NextRequest) {
     if (badOrigin) return badOrigin;
     const parsed = await parseJson(request, ${entityCamel}Schema);
     if ('error' in parsed) return parsed.error;
-    return authedBackend('/api/${entitiesKebab}', {
+    return authedBackend('${backendPath}', {
         method: 'POST',
         body: JSON.stringify(parsed.data)
     });
@@ -43,7 +44,8 @@ function validIdCheck(idType) {
     return "return /^[0-9a-fA-F-]{36}$/.test(id);";
 }
 export function itemRoute(spec, names) {
-    const { entityCamel, entitiesKebab } = names;
+    const { entityCamel } = names;
+    const backendPath = spec.apiResourcePath;
     return `import type { NextRequest } from 'next/server';
 import { authedBackend } from '@/lib/bff';
 import { jsonProblem, parseJson, validateOrigin } from '@/lib/http';
@@ -58,7 +60,7 @@ function validId(id: string) {
 export async function GET(_request: NextRequest, context: Params) {
     const { id } = await context.params;
     if (!validId(id)) return jsonProblem(404, { title: 'Not Found' });
-    return authedBackend(\`/api/${entitiesKebab}/\${id}\`);
+    return authedBackend(\`${backendPath}/\${id}\`);
 }
 
 export async function PATCH(request: NextRequest, context: Params) {
@@ -70,7 +72,7 @@ export async function PATCH(request: NextRequest, context: Params) {
     if ('error' in parsed) return parsed.error;
     // Backend only exposes a Put operation (full replacement) — no Patch operation exists,
     // so the upstream call uses PUT even though the BFF's own contract to the browser stays PATCH.
-    return authedBackend(\`/api/${entitiesKebab}/\${id}\`, {
+    return authedBackend(\`${backendPath}/\${id}\`, {
         method: 'PUT',
         body: JSON.stringify(parsed.data)
     });
@@ -81,7 +83,7 @@ export async function DELETE(request: NextRequest, context: Params) {
     if (badOrigin) return badOrigin;
     const { id } = await context.params;
     if (!validId(id)) return jsonProblem(404, { title: 'Not Found' });
-    return authedBackend(\`/api/${entitiesKebab}/\${id}\`, { method: 'DELETE' });
+    return authedBackend(\`${backendPath}/\${id}\`, { method: 'DELETE' });
 }
 
 export const dynamic = 'force-dynamic';
@@ -93,16 +95,17 @@ export function exportRoute(spec, names) {
     // Reuses the filter panel's first field as the export endpoint's OR-search convenience
     // text — it must be a property that actually exists on `{Entities}Query`.
     const field = filterableFields(spec)[0]?.name ?? null;
-    const cols = displayFields(spec).map((f) => f.name);
+    const cols = exportableFields(spec).map((f) => f.name);
     if (null !== spec.timestampField && !cols.includes(spec.timestampField)) {
         cols.push(spec.timestampField);
     }
-    const fieldsByName = new Map(spec.fields.map((f) => [f.name, f]));
+    const fieldsByName = new Map(spec.fields.filter((f) => f.type !== 'relation').map((f) => [f.name, f]));
+    const fallbackField = { name: '', type: 'text', required: false, maxLength: null, searchable: false };
     const exportFieldsType = cols
-        .map((c) => `    ${c}: ${c === spec.timestampField ? 'string' : tsType(fieldsByName.get(c) ?? { type: 'text' })};`)
+        .map((c) => `    ${c}: ${c === spec.timestampField ? 'string' : tsType(fieldsByName.get(c) ?? fallbackField)};`)
         .join('\n');
     const guardLines = cols.flatMap((c) => {
-        const t = c === spec.timestampField ? 'string' : tsType(fieldsByName.get(c) ?? { type: 'text' });
+        const t = c === spec.timestampField ? 'string' : tsType(fieldsByName.get(c) ?? fallbackField);
         return [`'${c}' in value`, `typeof value.${c} === '${t}'`];
     });
     const guardChecks = guardLines.map((line, i) => `        ${line}${i < guardLines.length - 1 ? ' &&' : ''}`).join('\n');

package/dist/templates/csvLib.js

@@ -1,7 +1,7 @@
-import { displayFields, humanize } from '../naming.js';
+import { exportableFields, humanize } from '../naming.js';
 export function csvLib(spec, names) {
     const { entityPascal, entitiesPascal, entitiesCamel } = names;
-    const fields = displayFields(spec).map((f) => f.name);
+    const fields = exportableFields(spec).map((f) => f.name);
     if (null !== spec.timestampField)
         fields.push(spec.timestampField);
     const pickList = fields.map((f) => `'${f}'`).join(' | ');

package/dist/templates/form.js

@@ -1,8 +1,54 @@
 import { humanize } from '../naming.js';
+function capitalize(s) {
+    return s.charAt(0).toUpperCase() + s.slice(1);
+}
+/** "assignedUser" -> "ASSIGNED_USER" — for this field's per-entity module-level constants. */
+function screamingSnake(name) {
+    return name.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toUpperCase();
+}
+function relationFieldMarkup(field, entitiesKebab) {
+    const label = humanize(field.name);
+    const id = `${entitiesKebab}-${field.name}`;
+    const cap = capitalize(field.name);
+    return `                <div className="mb-3">
+                    <label htmlFor="${id}" className="form-label">
+                        ${label}
+                    </label>
+                    <Controller
+                        name="${field.name}"
+                        control={control}
+                        render={({ field }) => (
+                            <AsyncSelect<RelationOption, false>
+                                inputId="${id}"
+                                instanceId="${id}"
+                                classNamePrefix="react-select"
+                                cacheOptions
+                                defaultOptions
+                                loadOptions={load${cap}Options}
+                                value={${field.name}Option}
+                                onChange={(option) => {
+                                    set${cap}Option(option);
+                                    field.onChange(option ? option.value : '');
+                                }}
+                                onBlur={field.onBlur}
+                                placeholder="Select ${label.toLowerCase()}"
+                                isClearable
+                                aria-invalid={errors.${field.name} ? true : undefined}
+                            />
+                        )}
+                    />
+                    {errors.${field.name} && (
+                        <div className="invalid-feedback d-block">{errors.${field.name}.message}</div>
+                    )}
+                </div>`;
+}
 function fieldMarkup(field, entitiesKebab, autoFocus) {
     const label = humanize(field.name);
     const id = `${entitiesKebab}-${field.name}`;
     const autoFocusProp = autoFocus ? '\n                    autoFocus={mode === \'create\'}' : '';
+    if (field.type === 'relation') {
+        return relationFieldMarkup(field, entitiesKebab);
+    }
     if (field.type === 'textarea') {
         return `                <TextareaField
                     id="${id}"
@@ -54,8 +100,83 @@ function fieldMarkup(field, entitiesKebab, autoFocus) {
                     registration={register('${field.name}')}
                 />`;
 }
+function resetFieldExpr(field) {
+    if (field.type === 'datetime')
+        return `${field.name}: toDatetimeLocalValue(data.${field.name})`;
+    // References the local const declared just above `reset(...)` in the edit-load effect (see
+    // `relationLocalsBlock`) rather than `data.${field.name}` directly, since the submitted
+    // value is the IRI string, not the embedded related-entity object the API returns.
+    if (field.type === 'relation')
+        return field.name;
+    // A non-required text/textarea field is `string | null` in the generated response type
+    // (OpenAPI's `nullable` optional-scalar convention), but the zod schema's `.optional()`
+    // makes the form value `string | undefined` — `?? undefined` bridges that at the reset()
+    // boundary instead of widening the form/schema type to accept `null` everywhere.
+    if ((field.type === 'text' || field.type === 'textarea') && !field.required) {
+        return `${field.name}: data.${field.name} ?? undefined`;
+    }
+    return `${field.name}: data.${field.name}`;
+}
+function relationConstants(field) {
+    const screaming = screamingSnake(field.name);
+    return `const ${screaming}_SEARCH_DEBOUNCE_MS = 300;
+const ${screaming}_SEARCH_PAGE_SIZE = 20;`;
+}
+function relationPreamble(field) {
+    const cap = capitalize(field.name);
+    return `    const [${field.name}Option, set${cap}Option] = useState<RelationOption | null>(null);
+    const ${field.name}DebounceRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);`;
+}
+function relationLoadOptions(field) {
+    const cap = capitalize(field.name);
+    const screaming = screamingSnake(field.name);
+    return `    const load${cap}Options = useCallback((inputValue: string): Promise<RelationOption[]> => {
+        return new Promise((resolve) => {
+            if (${field.name}DebounceRef.current) clearTimeout(${field.name}DebounceRef.current);
+            ${field.name}DebounceRef.current = setTimeout(async () => {
+                let response: Response;
+                try {
+                    response = await fetch(
+                        \`${field.relatedFrontendPath}?${field.searchParam}=\${encodeURIComponent(inputValue)}&itemsPerPage=\${${screaming}_SEARCH_PAGE_SIZE}\`,
+                        { cache: 'no-store' }
+                    );
+                } catch {
+                    resolve([]);
+                    return;
+                }
+                if (!response.ok) {
+                    resolve([]);
+                    return;
+                }
+                const data: unknown = await response.json();
+                if (!is${field.relatedEntity}Collection(data)) {
+                    resolve([]);
+                    return;
+                }
+                resolve(
+                    data.member.map((item) => ({
+                        value: \`${field.relatedApiResourcePath}/\${item.id}\`,
+                        label: item.${field.displayField}
+                    }))
+                );
+            }, ${screaming}_SEARCH_DEBOUNCE_MS);
+        });
+    }, []);`;
+}
+function relationCleanupEffect(fields) {
+    const lines = fields
+        .map((f) => `            if (${f.name}DebounceRef.current) clearTimeout(${f.name}DebounceRef.current);`)
+        .join('\n');
+    return `    useEffect(() => {
+        return () => {
+${lines}
+        };
+    }, []);`;
+}
 export function form(spec, names) {
     const { entityPascal, entityCamel, entitiesKebab } = names;
+    const relationFields = spec.fields.filter((f) => f.type === 'relation');
+    const usesRelation = relationFields.length > 0;
     const usesTextarea = spec.fields.some((f) => f.type === 'textarea');
     const usesText = spec.fields.some((f) => f.type === 'text' || f.type === 'number');
     const usesBoolean = spec.fields.some((f) => f.type === 'boolean');
@@ -73,23 +194,43 @@ export function form(spec, names) {
     const fieldsMarkup = spec.fields
         .map((f, i) => fieldMarkup(f, entitiesKebab, i === 0))
         .join('\n');
-    const resetFields = spec.fields
-        .map((f) => (f.type === 'datetime' ? `${f.name}: toDatetimeLocalValue(data.${f.name})` : `${f.name}: data.${f.name}`))
-        .join(', ');
+    const resetFields = spec.fields.map(resetFieldExpr).join(', ');
     const submitFields = spec.fields
         .map((f) => (f.type === 'datetime' ? `${f.name}: fromDatetimeLocalValue(values.${f.name})` : null))
         .filter((c) => c !== null)
         .join(', ');
+    const reactImports = ['useEffect', 'useState', ...(usesRelation ? ['useCallback', 'useRef'] : [])].sort();
+    const reactHookFormImports = usesRelation ? 'Controller, useForm' : 'useForm';
+    const relatedCollectionGuards = Array.from(new Set(relationFields.map((f) => `is${f.relatedEntity}Collection`)));
+    const apiShapesImports = [`is${entityPascal}`, ...relatedCollectionGuards].join(', ');
+    const relationTypeBlock = usesRelation ? '\ntype RelationOption = { value: string; label: string };\n' : '';
+    const relationConstantsBlock = usesRelation
+        ? '\n' + relationFields.map(relationConstants).join('\n') + '\n'
+        : '';
+    const relationPreambleBlock = usesRelation
+        ? '\n' + relationFields.map(relationPreamble).join('\n')
+        : '';
+    const controlDestructure = usesRelation ? '\n        control,' : '';
+    const relationLoadOptionsBlock = usesRelation
+        ? '\n\n' + relationFields.map(relationLoadOptions).join('\n\n')
+        : '';
+    const relationCleanupBlock = usesRelation ? '\n\n' + relationCleanupEffect(relationFields) : '';
+    const relationLocalsBlock = relationFields
+        .map((f) => `                const ${f.name} = \`${f.relatedApiResourcePath}/\${data.${f.name}.id}\`;`)
+        .join('\n');
+    const relationSetOptionBlock = relationFields
+        .map((f) => `                set${capitalize(f.name)}Option({ value: ${f.name}, label: data.${f.name}.${f.displayField} });`)
+        .join('\n');
     return `'use client';
 
 import { zodResolver } from '@hookform/resolvers/zod';
 import { Button, ListPageCard${fieldComponents ? `, ${fieldComponents}` : ''} } from '@kematjaya/bootstrap-ui-kit';
 import { useRouter } from 'next/navigation';
-import { useEffect, useState } from 'react';
-import { useForm } from 'react-hook-form';
-import { is${entityPascal} } from '@/lib/api-shapes';
+import { ${reactImports.join(', ')} } from 'react';
+import { ${reactHookFormImports} } from 'react-hook-form';${usesRelation ? "\nimport AsyncSelect from 'react-select/async';" : ''}
+import { ${apiShapesImports} } from '@/lib/api-shapes';
 import { ${entityCamel}Schema, type ${entityPascal}FormValues } from '@/lib/schemas';${usesDateTime ? "\nimport { toDatetimeLocalValue, fromDatetimeLocalValue } from '@/lib/datetime';" : ''}
-
+${relationTypeBlock}${relationConstantsBlock}
 type Props = {
     mode: 'create' | 'edit';
     ${entityCamel}Id?: string;
@@ -98,17 +239,17 @@ type Props = {
 export function ${entityPascal}Form({ mode, ${entityCamel}Id }: Props) {
     const router = useRouter();
     const [error, setError] = useState('');
-    const [loading, setLoading] = useState(mode === 'edit');
+    const [loading, setLoading] = useState(mode === 'edit');${relationPreambleBlock}
     const {
         register,
         handleSubmit,
-        reset,
+        reset,${controlDestructure}
         formState: { errors, isSubmitting }
     } = useForm<${entityPascal}FormValues>({
         resolver: zodResolver(${entityCamel}Schema),
         mode: 'onBlur',
         reValidateMode: 'onChange'
-    });
+    });${relationLoadOptionsBlock}${relationCleanupBlock}
 
     useEffect(() => {
         if (mode !== 'edit' || !${entityCamel}Id) return;
@@ -135,8 +276,8 @@ export function ${entityPascal}Form({ mode, ${entityCamel}Id }: Props) {
                 return;
             }
             if (!cancelled) {
-                reset({ ${resetFields} });
-                setLoading(false);
+${relationLocalsBlock ? relationLocalsBlock + '\n' : ''}                reset({ ${resetFields} });
+${relationSetOptionBlock ? relationSetOptionBlock + '\n' : ''}                setLoading(false);
             }
         })();
         return () => {

package/dist/templates/queryLib.js

@@ -63,6 +63,15 @@ export function build${entitiesPascal}ApiPath(state: ${entitiesPascal}Query): st
     return query ? \`/api/${entitiesKebab}?\${query}\` : '/api/${entitiesKebab}';
 }
 
+// The BFF's own route (above) is a free-to-choose frontend slug. The real backend resource
+// lives at a URI ApiPlatform derives from the entity name (see crud-specs/${spec.entity}.json's
+// "apiResourcePath") — used only by the BFF route handler's server-side call to the backend,
+// never by the browser.
+export function build${entitiesPascal}BackendPath(state: ${entitiesPascal}Query): string {
+    const query = buildParams(state).toString();
+    return query ? \`${spec.apiResourcePath}?\${query}\` : '${spec.apiResourcePath}';
+}
+
 export function clampPageToTotal(
     page: number,
     itemsPerPage: number,

package/dist/templates/schemas.js

@@ -12,10 +12,12 @@ function zodField(field) {
     if (field.type === 'number') {
         return field.required ? 'z.number()' : 'z.number().optional()';
     }
+    // Also covers `relation` (the submitted value is an IRI-reference string) — it has no
+    // `maxLength` concept, so that check is simply skipped for it below.
     let expr = 'z.string().trim()';
     if (field.required)
         expr += `.min(1, '${label} is required')`;
-    if (field.maxLength !== null)
+    if (field.type !== 'relation' && field.maxLength !== null)
         expr += `.max(${field.maxLength})`;
     if (!field.required)
         expr += '.optional()';

package/dist/templates/table.js

@@ -1,5 +1,5 @@
 import { displayFields, filterableFields, humanize, labelField, lowerWords } from '../naming.js';
-function columnCell(fieldName, fieldType, timestampField) {
+function columnCell(fieldName, fieldType, timestampField, relationDisplayField) {
     if (fieldName === timestampField || fieldType === 'datetime') {
         return `                                    <td>
                                         {new Date(
@@ -16,6 +16,9 @@ function columnCell(fieldName, fieldType, timestampField) {
                                         ).toLocaleDateString()}
                                     </td>`;
     }
+    if (fieldType === 'relation') {
+        return `                                    <td>{item.${fieldName}.${relationDisplayField}}</td>`;
+    }
     return `                                    <td>{String(item.${fieldName})}</td>`;
 }
 function filterFieldKind(type) {
@@ -33,6 +36,7 @@ export function table(spec, names) {
         cols.push(spec.timestampField);
     }
     const fieldTypeByName = new Map(spec.fields.map((f) => [f.name, f.type]));
+    const relationDisplayByName = new Map(spec.fields.filter((f) => f.type === 'relation').map((f) => [f.name, f.displayField]));
     const label = labelField(spec);
     const noun = lowerWords(entityPascal);
     const pluralNoun = lowerWords(entitiesPascal);
@@ -42,7 +46,7 @@ export function table(spec, names) {
     const filterPanelId = `${noun}-filter-panel`;
     const headCells = cols.map((c) => `                                <th>${humanize(c)}</th>`).join('\n');
     const bodyCells = cols
-        .map((c) => columnCell(c, fieldTypeByName.get(c) ?? null, spec.timestampField))
+        .map((c) => columnCell(c, fieldTypeByName.get(c) ?? null, spec.timestampField, relationDisplayByName.get(c) ?? null))
         .join('\n');
     const filterButtonBlock = hasFilter
         ? `                    <Button

package/dist/templates/typesApi.js

@@ -18,7 +18,13 @@ export function typesApiMarker(entityPascal) {
 }
 export function typesApiBlock(spec, names) {
     const { entityPascal, entitiesPascal, entitiesKebab } = names;
-    const picked = ['id', ...displayFields(spec).map((f) => f.name)];
+    const relationFields = spec.fields.filter((f) => f.type === 'relation');
+    // Relation fields are excluded from the `Pick<Generated{Entity}, ...>` below and intersected
+    // in separately as `{RelatedEntity}` (this entity's own already-generated type, in this same
+    // file) instead — `Generated{Entity}.{field}` is the raw OpenAPI-embedded shape
+    // (`components['schemas']['{RelatedEntity}.jsonld']`), not the nicer `Pick<...>` type this
+    // generator writes for the related entity itself.
+    const picked = ['id', ...displayFields(spec).filter((f) => f.type !== 'relation').map((f) => f.name)];
     if (spec.fields.some((f) => f.type === 'textarea')) {
         for (const f of spec.fields) {
             if (f.type === 'textarea' && !picked.includes(f.name))
@@ -29,6 +35,9 @@ export function typesApiBlock(spec, names) {
         picked.push(spec.timestampField);
     }
     const pickList = picked.map((p) => `'${p}'`).join(' | ');
+    const relationIntersection = relationFields.length > 0
+        ? ' &\n    { ' + relationFields.map((f) => `${f.name}: ${f.relatedEntity}`).join('; ') + ' }'
+        : '';
     return `
 type ${entitiesPascal}CollectionResponses = paths['/api/${entitiesKebab}']['get']['responses'];
 type ${entityPascal}PostResponses = paths['/api/${entitiesKebab}']['post']['responses'];
@@ -40,7 +49,7 @@ type Generated${entitiesPascal}Collection = NonNullable<
 export type ${entityPascal}Input = components['schemas']['${entityPascal}.${entityPascal}Input'];
 export type ${entityPascal} = Required<
     Pick<Generated${entityPascal}, ${pickList}>
->;
+>${relationIntersection};
 export type ${entitiesPascal}Collection = Omit<
     Generated${entitiesPascal}Collection,
     'member' | 'totalItems'

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@kematjaya/crud-ui-generator",
-    "version": "0.4.0",
+    "version": "0.6.0",
     "description": "Next.js CRUD frontend generator that reads crud-specs/{Entity}.json sidecars written by kematjaya/crud-maker-bundle's make:kmj-api-crud and generates pages, components, and BFF routes matching the boilerplate's hand-written Notes feature.",
     "type": "module",
     "license": "MIT",