@aerokit/sdk 14.66.0 → 14.68.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aerokit/sdk",
-  "version": "14.66.0",
+  "version": "14.68.0",
   "description": "Unified TypeScript SDK for modern cloud platforms.",
   "scripts": {
     "clean": "rm -rf dist",

package/test/api.js

@@ -19,6 +19,8 @@ export function makeApi(request, manifest) {
     count: (entity) => request.get(url(entity, '/count')).then(asJson).then((body) => (typeof body === 'number' ? body : body.count)),
     get: (entity, id) => request.get(url(entity, '/' + id)).then(asJson),
     getResponse: (entity, id) => request.get(url(entity, '/' + id)),
+    // the generated controller's filtered read (what the list's filters POST): [{ propertyName, operator, value }]
+    search: (entity, conditions) => request.post(url(entity, '/search'), { data: { conditions } }).then(asJson),
     create: (entity, data) => request.post(url(entity), { data }).then(asJson),
     update: (entity, id, data) => request.put(url(entity, '/' + id), { data }).then(asJson),
     // Answers whether the row is gone. A record whose process declares `whenDeleted: refuse` is

package/test/flows/crud.js

@@ -1,6 +1,7 @@
 import { expect, test } from '../fixtures.js';
+import { makeApi } from '../api.js';
 import { fillField, fillForm, resolveRelationSamples } from '../form.js';
-import { handleField, sampleRecord } from '../sample-values.js';
+import { freshUniques, handleField, sampleRecord } from '../sample-values.js';
 
 // Server-side row lookup via the toolbar "Search <Entity>..." box - present on every list
 // layout (manage-list, master-detail, document) and searching the string columns server-side.
@@ -14,6 +15,23 @@ function dataRow(page, text) {
   return page.locator('tbody tr', { hasText: text });
 }
 
+// Edit and Delete of a row live in its "Row actions" menu - the one place every list layout
+// (manage, document, master-detail) offers both; the manage list's record sheet puts Delete behind
+// an overflow menu and its primary button may be a process task rather than Edit (#7491).
+async function rowAction(page, text, action) {
+  await dataRow(page, text).getByRole('button', { name: 'Row actions' }).click();
+  await page.getByRole('menuitem', { name: action, exact: true }).click();
+}
+
+// A walk that fails halfway leaves its APPTEST- row behind, and the next run's REST flow then hits
+// a unique: column with it (409). Remove whatever the walk created - the edited name starts with
+// the created one - unless the UI delete already did.
+async function removeLeftovers(client, manifest, entity, handle, created) {
+  const idProperty = manifest.idProperty ?? 'Id';
+  const rows = await client.search(entity, [{ propertyName: handle.name, operator: 'LIKE', value: created + '%' }]);
+  for (const row of rows ?? []) await client.remove(entity, row[idProperty]);
+}
+
 export function crudFlow(manifest, entity, opts = {}) {
   const cfg = opts.extend?.entities?.[entity.name] ?? {};
   const skip = new Set(cfg.skip ?? []);
@@ -26,59 +44,60 @@ export function crudFlow(manifest, entity, opts = {}) {
   if (!handleField(entity)) return;
 
   test(`${entity.name}: create, edit and delete through the UI`, async ({ page, api }) => {
-    const record = sampleRecord(entity);
+    const record = await freshUniques(makeApi(api, manifest), entity, sampleRecord(entity));
     const handle = handleField(entity);
     const relationSamples = await resolveRelationSamples(api, manifest, entity);
 
-    // create
-    await page.goto(manifest.standaloneShell + entity.route);
-    // exact: the empty state adds a second "New <Entity>" button that a substring match also hits
-    await page.getByRole('button', { name: 'New', exact: true }).click();
-    await expect(page).toHaveURL(/\/create$/);
-    await cfg.beforeCreate?.(page, record);
-    await fillForm(page, manifest, entity, record, relationSamples, opts);
-    await page.getByRole('button', { name: 'Create', exact: true }).click();
-    if (entity.layout === 'document') {
-      // a document create lands on the NEW record's page (line-item editing continues there);
-      // saving an edit is what returns to the list
-      await expect(page).toHaveURL(/\/edit$/);
+    const created = record[handle.name];
+    const listRoute = entity.route.replace(/[#/]/g, '\\$&');
+    try {
+      // create
       await page.goto(manifest.standaloneShell + entity.route);
-    } else {
-      await expect(page).toHaveURL(new RegExp(entity.route.replace(/[#/]/g, '\\$&') + '$'));
-    }
-    await filterBy(page, record[handle.name]);
-    await expect(dataRow(page, record[handle.name])).toHaveCount(1);
-    await cfg.afterCreate?.(page, record);
+      // exact: the empty state adds a second "New <Entity>" button that a substring match also hits
+      await page.getByRole('button', { name: 'New', exact: true }).click();
+      await expect(page).toHaveURL(/\/create$/);
+      await cfg.beforeCreate?.(page, record);
+      await fillForm(page, manifest, entity, record, relationSamples, opts);
+      await page.getByRole('button', { name: 'Create', exact: true }).click();
+      // A create lands on the NEW record's page when there is more to do there - a document's
+      // line items, a manage record's detail collections - and on the list otherwise. Saving an
+      // edit is what returns to the list.
+      const recordPage = entity.layout === 'document' ? '/[^/]+/edit' : '(/[^/]+/edit)?';
+      await expect(page).toHaveURL(new RegExp(listRoute + recordPage + '$'));
+      if (page.url().endsWith('/edit')) await page.goto(manifest.standaloneShell + entity.route);
+      await filterBy(page, created);
+      await expect(dataRow(page, created)).toHaveCount(1);
+      await cfg.afterCreate?.(page, record);
 
-    // edit (via the detail pane the row selection reveals)
-    if (!skip.has('edit')) {
-      const updated = record[handle.name] + '-UPD';
-      await dataRow(page, record[handle.name]).click();
-      // exact: substring name matching would also hit e.g. a "Credit Notes" sidebar item
-      await page.getByRole('button', { name: 'Edit', exact: true }).first().click();
-      await expect(page).toHaveURL(/\/edit$/);
-      // the record loads async after the form renders - filling before the fetch completes
-      // gets overwritten by the load and Save persists the OLD value
-      await expect(page.locator('#f_' + handle.name)).toHaveValue(record[handle.name]);
-      await fillField(page, handle, updated, opts);
-      await page.getByRole('button', { name: 'Save', exact: true }).click();
-      await expect(page).toHaveURL(new RegExp(entity.route.replace(/[#/]/g, '\\$&') + '$'));
-      await filterBy(page, updated);
-      await expect(dataRow(page, updated)).toHaveCount(1);
-      record[handle.name] = updated;
-    }
+      // edit
+      if (!skip.has('edit')) {
+        const updated = created + '-UPD';
+        await rowAction(page, created, 'Edit');
+        await expect(page).toHaveURL(/\/edit$/);
+        // the record loads async after the form renders - filling before the fetch completes
+        // gets overwritten by the load and Save persists the OLD value
+        await expect(page.locator('#f_' + handle.name)).toHaveValue(created);
+        await fillField(page, handle, updated, opts);
+        await page.getByRole('button', { name: 'Save', exact: true }).click();
+        await expect(page).toHaveURL(new RegExp(listRoute + '$'));
+        await filterBy(page, updated);
+        await expect(dataRow(page, updated)).toHaveCount(1);
+        record[handle.name] = updated;
+      }
 
-    // delete (detail pane trash button, then the confirm dialog). An entity whose process declares
-    // `whenDeleted: refuse` answers the delete with an error toast while its instance runs - the
-    // create above started it - so the walk stops here and the REST flow asserts that refusal.
-    if (!skip.has('delete') && !entity.deleteGuardedByProcess?.length) {
-      await dataRow(page, record[handle.name]).click();
-      await page.getByRole('button', { name: 'Delete', exact: true }).first().click();
-      const dialog = page.locator('[x-h-dialog-overlay][data-open]');
-      await dialog.getByRole('button', { name: 'Delete', exact: true }).click();
-      await expect(dialog).toHaveCount(0);
-      await filterBy(page, record[handle.name]);
-      await expect(dataRow(page, record[handle.name])).toHaveCount(0);
+      // delete (row menu, then the confirm dialog). An entity whose process declares
+      // `whenDeleted: refuse` answers the delete with an error toast while its instance runs - the
+      // create above started it - so the walk stops here and the REST flow asserts that refusal.
+      if (!skip.has('delete') && !entity.deleteGuardedByProcess?.length) {
+        await rowAction(page, record[handle.name], 'Delete');
+        const dialog = page.locator('[x-h-dialog-overlay][data-open]');
+        await dialog.getByRole('button', { name: 'Delete', exact: true }).click();
+        await expect(dialog).toHaveCount(0);
+        await filterBy(page, record[handle.name]);
+        await expect(dataRow(page, record[handle.name])).toHaveCount(0);
+      }
+    } finally {
+      await removeLeftovers(makeApi(api, manifest), manifest, entity, handle, created);
     }
   });
 }

package/test/flows/list.js

@@ -1,14 +1,21 @@
 import { expect, test } from '../fixtures.js';
 import { labelOf } from '../sample-values.js';
 
-// The list page renders: plural title in the toolbar, then one of three bodies -
+// The shell breadcrumb's current crumb - the one page element every list layout shares that names
+// the entity (the sidebar label, which the manifest's labelPlural mirrors).
+export function listCrumb(page, entity) {
+  return page.locator('[x-h-breadcrumb-page]', { hasText: entity.labelPlural }).first();
+}
+
+// The list page renders under the shell breadcrumb naming it by its plural label (the #7491
+// manage list carries no title of its own), then one of three bodies -
 // a tree (hierarchy entities render role=treeitem nodes, no table), the table with one
 // column header per major field, or (when the entity has no rows yet) the empty state.
 // When seed data is expected, rows/nodes must actually be there.
 export function listFlow(manifest, entity) {
   test(`${entity.name}: list page renders the declared columns`, async ({ page }) => {
     await page.goto(manifest.standaloneShell + entity.route);
-    await expect(page.locator('[x-h-toolbar-title]', { hasText: entity.labelPlural }).first()).toBeVisible();
+    await expect(listCrumb(page, entity)).toBeVisible();
     if (entity.hierarchy) {
       if (entity.expectSeedData) {
         await expect(page.getByRole('treeitem').first()).toBeVisible();

package/test/flows/multilingual.js

@@ -1,4 +1,5 @@
 import { expect, test } from '../fixtures.js';
+import { listCrumb } from './list.js';
 
 // The read-time translation overlay: switch the shared language key (what the Region &
 // Language setting writes), reload, and a known seed row shows its translated name.
@@ -9,7 +10,7 @@ export function multilingualFlow(manifest, entity) {
 
   test(`${entity.name}: ${sample.language} translation overlays on read`, async ({ page }) => {
     await page.goto(manifest.standaloneShell + entity.route);
-    await expect(page.locator('[x-h-toolbar-title]', { hasText: entity.labelPlural }).first()).toBeVisible();
+    await expect(listCrumb(page, entity)).toBeVisible();
     await page.evaluate((lang) => localStorage.setItem('codbex.harmonia.language', lang), sample.language);
     await page.reload();
     await expect(page.locator('tbody tr', { hasText: sample.translated }).first()).toBeVisible();

package/test/flows/my.js

@@ -1,7 +1,7 @@
 import { makeApi } from '../api.js';
 import { expect, test } from '../fixtures.js';
 import { resolveRelationSamples } from '../form.js';
-import { sampleRecord } from '../sample-values.js';
+import { freshUniques, sampleRecord } from '../sample-values.js';
 
 // Wave 2 (UI parity): the personal PAGE renders what the wire serves. Driven by the same
 // own-row lifecycle as the wire test (created through the scoped controller, removed in the
@@ -88,6 +88,7 @@ export function myFlow(manifest, entity, opts = {}) {
     }
     // the owner FK is server-forced on the personal surface; sending a value must be pointless
     delete payload[entity.personal.owner];
+    await freshUniques(makeApi(api, manifest), entity, payload);
     return { payload, samples };
   }
 

package/test/flows/rest.js

@@ -1,7 +1,7 @@
 import { makeApi } from '../api.js';
 import { expect, test } from '../fixtures.js';
 import { resolveRelationSamples } from '../form.js';
-import { handleField, sampleRecord } from '../sample-values.js';
+import { freshUniques, handleField, sampleRecord } from '../sample-values.js';
 
 // The same contract over the generated REST controllers, no browser: isolates backend
 // failures from UI failures and verifies the manifest's field names bind.
@@ -19,6 +19,7 @@ export function restFlow(manifest, entity, opts = {}) {
     for (const sample of await resolveRelationSamples(api, manifest, entity)) {
       payload[sample.relation.name] = sample.id;
     }
+    await freshUniques(client, entity, payload);
 
     const created = await client.create(entity, payload);
     const id = created?.[idProperty];

package/test/form.js

@@ -16,21 +16,31 @@ export async function fillField(page, field, value, opts = {}) {
   await input.fill(String(value));
 }
 
-// The x-h-select directive hides its input and builds a button[role=combobox] trigger
-// labelled by the field label; options carry role=option.
-export async function pickDropdown(page, relation, optionText) {
+// The x-h-select directive hides its input and appends a button[role=combobox] trigger beside it;
+// options carry role=option.
+// The generated manage/document forms give that input id="f_<Name>", so the trigger is reached
+// through its sibling - independent of how the field label reads. The accessible name is the
+// fallback for a form whose select input carries no id (the my/partner surfaces).
+async function relationTrigger(page, relation) {
+  const input = page.locator('#f_' + relation.name);
+  if (await input.count()) return input.locator('xpath=../button[@role="combobox"]');
   // Anchored prefix match: the combobox accessible name is the label plus the placeholder or
   // selected value ("Country Select a Country..."), so exact matching finds nothing - while a
   // bare substring match collides with longer sibling labels ("Type" also hits "Chart Type").
   const label = relation.label ?? relation.name;
   const anchored = new RegExp('^' + label.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '\\b');
-  await page.getByRole('combobox', { name: anchored }).first().click();
+  return page.getByRole('combobox', { name: anchored }).first();
+}
+
+export async function pickDropdown(page, relation, optionText) {
+  const trigger = await relationTrigger(page, relation);
+  await trigger.click();
   const option = page.getByRole('option', { name: optionText }).first();
   try {
     await option.click({ timeout: 10_000 });
   } catch {
     // the option list re-rendered mid-click (async option load reflow) - reopen and retry
-    await page.getByRole('combobox', { name: anchored }).first().click();
+    await trigger.click();
     await option.click({ force: true });
   }
 }

package/test/sample-values.js

@@ -11,6 +11,7 @@ function rand(chars, n) {
 // cleanup marker and the searchable handle); short strings always contain a digit so
 // they can never collide with letter-only nomenclature seeds (ISO codes etc.).
 export function sampleValue(field) {
+  if (field.unique && field.type !== 'string') return uniqueValue(field);
   switch (field.type) {
     case 'string': {
       const len = field.length ?? 64;
@@ -40,8 +41,10 @@ export function sampleValue(field) {
 // A `pattern:` field (an authored regex, or the address regex behind `format: email`) is rejected
 // by the generated controller with 400 unless the value has the declared shape, so the marker value
 // above has to be traded for one that matches: the candidates are tried in order and the first that
-// both matches and fits the declared length wins. A pattern nothing here matches keeps the plain
-// marker - the controller's own 400 then names the field and the pattern, which is the message the
+// both matches and fits the declared length wins. When nothing here matches (an IBAN-shaped regex
+// mixing character classes by position), an optional field is left unset - the record is valid
+// without it, and no flow needs it filled (dirigible #7525) - while a required one keeps the plain
+// marker: the controller's own 400 then names the field and the pattern, which is the message the
 // module author needs, and a silent near-miss would not.
 function shaped(field, value) {
   let regex;
@@ -59,7 +62,60 @@ function shaped(field, value) {
     token, // letters and digits, no separator
     rand(DIGITS, 10), // a numeric code
   ];
-  return candidates.find((candidate) => candidate.length <= (field.length ?? 255) && regex.test(candidate)) ?? value;
+  const match = candidates.find((candidate) => candidate.length <= (field.length ?? 255) && regex.test(candidate));
+  return match ?? (field.required ? value : undefined);
+}
+
+// A `unique:` field refuses a second row carrying its value with 409 - the module's guard doing its
+// job. The per-type constants above are the one value certain to collide: with a seeded row, with
+// the row a parallel flow of the same run is creating, or with one an earlier failed run left
+// behind (dirigible #7530). So a unique field draws a fresh value per record, away from the range
+// an author seeds (a year, a small code): an integer in the hundred-thousands, a date in the 22nd
+// century. Strings need none of this - the marker above is already random.
+function uniqueValue(field) {
+  const n = 100000 + Math.floor(Math.random() * 900000);
+  switch (field.type) {
+    case 'integer':
+    case 'bigint':
+      return n;
+    case 'decimal':
+    case 'double':
+      return n + 0.25;
+    case 'date':
+    case 'timestamp':
+    case 'datetime': {
+      const at = new Date(Date.UTC(2100, 0, 1) + (n % 36500) * 86400000);
+      return field.type === 'date' ? at.toISOString().slice(0, 10) : at.toISOString().replace(/\.\d{3}Z$/, 'Z');
+    }
+    default:
+      return sampleValue({ ...field, unique: false });
+  }
+}
+
+// A drawn value is unlikely to collide, not certain not to - probe the live rows for each unique
+// field of the record through the controller's filtered read and redraw on a hit, so the create the
+// flow is about to send cannot be refused for a value that is already taken. The value goes as a
+// string - the controller coerces it to the property's own type (an Integer would not bind to a Long
+// or BigDecimal column). A probe that fails (an older controller without /search) keeps the value.
+export async function freshUniques(client, entity, record) {
+  let redrawn = false;
+  for (const field of editableFields(entity)) {
+    if (!field.unique || !(field.name in record)) continue;
+    for (let attempt = 0; attempt < 5; attempt++) {
+      let rows;
+      try {
+        rows = await client.search(entity, [{ propertyName: field.name, operator: 'EQ', value: String(record[field.name]) }]);
+      } catch {
+        break;
+      }
+      if (!rows?.length) break;
+      record[field.name] = field.type === 'string' ? sampleValue(field) : uniqueValue(field);
+      redrawn = true;
+    }
+  }
+  // a redrawn field may be the right-hand side of a compare check - re-derive its left operand
+  if (redrawn) steerCompares(entity, record);
+  return record;
 }
 
 export function editableFields(entity) {
@@ -70,17 +126,25 @@ export function editableFields(entity) {
 // against live target rows).
 export function sampleRecord(entity) {
   const record = {};
-  for (const field of editableFields(entity)) record[field.name] = sampleValue(field);
+  for (const field of editableFields(entity)) {
+    const value = sampleValue(field);
+    if (value !== undefined) record[field.name] = value;
+  }
   // an exactlyOne check rejects a record where more than one of the named fields is set -
   // keep only the first of each declared set
   for (const set of entity.exactlyOne ?? []) {
     for (const name of set.slice(1)) delete record[name];
   }
-  // a compare check relates the record's own field to a second value - another of its fields, or a
-  // literal - and the sample values above are per-type constants, so two dates come out EQUAL and a
-  // strict comparison (gt/lt/ne) would be rejected with 400, just as a sample quantity of 7 fails a
-  // `le 5`. Derive the left operand from whichever right-hand side the check names, by the smallest
-  // step that satisfies the declared operator (equality satisfies ge/le/eq).
+  steerCompares(entity, record);
+  return record;
+}
+
+// A compare check relates the record's own field to a second value - another of its fields, or a
+// literal - and the sample values above are per-type constants, so two dates come out EQUAL and a
+// strict comparison (gt/lt/ne) would be rejected with 400, just as a sample quantity of 7 fails a
+// `le 5`. Derive the left operand from whichever right-hand side the check names, by the smallest
+// step that satisfies the declared operator (equality satisfies ge/le/eq).
+function steerCompares(entity, record) {
   for (const check of entity.compare ?? []) {
     if (!(check.field in record)) continue;
     const type = (entity.fields ?? []).find((f) => f.name === check.field)?.type;