@aerokit/sdk 14.69.0 → 14.71.0

package/package.json

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

package/test/flows/crud.js

@@ -1,7 +1,7 @@
 import { expect, test } from '../fixtures.js';
 import { makeApi } from '../api.js';
 import { fillField, fillForm, resolveRelationSamples } from '../form.js';
-import { freshUniques, handleField, sampleRecord } from '../sample-values.js';
+import { freshUniqueKeys, 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.
@@ -36,6 +36,8 @@ export function crudFlow(manifest, entity, opts = {}) {
   const cfg = opts.extend?.entities?.[entity.name] ?? {};
   const skip = new Set(cfg.skip ?? []);
   if (skip.has('crud')) return;
+  // no power page to walk: a composition child is reached through its parent (dirigible #7545)
+  if (!entity.route) return;
   // A hierarchy entity lists as a tree, and a calendar/slots entity replaces the table page
   // entirely - no filter row / data rows to drive the walk below; create/read/update/delete
   // stays covered by the REST flow. Same for an entity without a string handle field (nothing
@@ -47,6 +49,8 @@ export function crudFlow(manifest, entity, opts = {}) {
     const record = await freshUniques(makeApi(api, manifest), entity, sampleRecord(entity));
     const handle = handleField(entity);
     const relationSamples = await resolveRelationSamples(api, manifest, entity);
+    const taken = await freshUniqueKeys(makeApi(api, manifest), entity, record, relationSamples);
+    test.skip(!!taken, `every ${entity.name} combination of the unique key [${taken}] tried already has a row`);
 
     const created = record[handle.name];
     const listRoute = entity.route.replace(/[#/]/g, '\\$&');
@@ -61,7 +65,7 @@ export function crudFlow(manifest, entity, 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.
+      // edit returns to the list, except on a document, whose Save stays on it (#7359).
       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);
@@ -78,7 +82,20 @@ export function crudFlow(manifest, entity, opts = {}) {
         // 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();
+        if (entity.layout === 'document') {
+          // A document Save STAYS on the document and re-reads it (#7359): wait for the update to
+          // land, then leave for the list the way a user does (dirigible #7545).
+          const save = page.getByRole('button', { name: 'Save', exact: true });
+          const saved = page.waitForResponse((response) => response.request().method() === 'PUT' && response.ok());
+          await save.click();
+          await saved;
+          // Save is disabled again once the re-read header is the new pristine state - leaving before
+          // that would meet the unsaved-changes guard
+          await expect(save).toBeDisabled();
+          await page.getByRole('button', { name: 'Back to list', exact: true }).click();
+        } else {
+          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);

package/test/flows/list.js

@@ -1,6 +1,11 @@
 import { expect, test } from '../fixtures.js';
 import { labelOf } from '../sample-values.js';
 
+// The calendar / slot-picker view root. The slots page renders `x-h-slot-picker.responsive`, and an
+// attribute selector matches an attribute NAME exactly, so the modifier form is listed with its dot
+// escaped (dirigible #7545).
+export const CALENDAR_OR_SLOTS = '[x-h-calendar], [x-h-slot-picker], [x-h-slot-picker\\.responsive]';
+
 // 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) {
@@ -13,6 +18,8 @@ export function listCrumb(page, entity) {
 // 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) {
+  // no power page: a composition child is reached through its parent (dirigible #7545)
+  if (!entity.route) return;
   test(`${entity.name}: list page renders the declared columns`, async ({ page }) => {
     await page.goto(manifest.standaloneShell + entity.route);
     await expect(listCrumb(page, entity)).toBeVisible();
@@ -24,7 +31,7 @@ export function listFlow(manifest, entity) {
     }
     if (entity.layout === 'calendar' || entity.layout === 'slots') {
       // the view family renders a calendar / slot picker instead of the table
-      await expect(page.locator('[x-h-calendar], [x-h-slot-picker]').first()).toBeVisible();
+      await expect(page.locator(CALENDAR_OR_SLOTS).first()).toBeVisible();
       return;
     }
     // filter({ visible: true }): the empty-state markup stays in the DOM (x-show) above the

package/test/flows/multilingual.js

@@ -11,7 +11,7 @@ const OVERLAY_TIMEOUT = 15_000;
 // Needs a concrete sample in the manifest: { language, base, translated }.
 export function multilingualFlow(manifest, entity) {
   const sample = entity.multilingualSample;
-  if (!entity.multilingual || !sample) return;
+  if (!entity.multilingual || !sample || !entity.route) return;
 
   test(`${entity.name}: ${sample.language} translation overlays on read`, async ({ page }) => {
     await page.goto(manifest.standaloneShell + entity.route);
@@ -26,20 +26,23 @@ export function multilingualFlow(manifest, entity) {
 // Set the language key and reload, waiting for the list's own data GET (the paged getAll on the
 // entity's controller) so the assertion starts once the rows are on their way, and answering what
 // that read asked for and got back - which is what tells a slow render from a missing translation.
+// The wait is registered only once the reload has committed: registered before it, it also matched
+// a list GET still in flight from the document the reload replaced, whose body is gone (#7584). The
+// new document issues its own GET only after its scripts have loaded, so it cannot slip past.
 async function reloadIn(page, manifest, entity, language) {
   await page.evaluate(([key, lang]) => localStorage.setItem(key, lang), [LANGUAGE_KEY, language]);
   const controllerPath = manifest.restBase + entity.api;
-  const listRead = page.waitForResponse(
-    (response) => response.request().method() === 'GET' && new URL(response.url()).pathname === controllerPath,
+  await page.reload({ waitUntil: 'commit' });
+  const response = await page.waitForResponse(
+    (candidate) => candidate.request().method() === 'GET' && new URL(candidate.url()).pathname === controllerPath,
     { timeout: OVERLAY_TIMEOUT },
   );
-  await page.reload();
-  const response = await listRead;
   return {
     language,
     acceptLanguage: await response.request().headerValue('accept-language'),
     status: response.status(),
-    body: await response.text(),
+    // Only the diagnostic reads the body, so a body the browser no longer holds must not fail the flow.
+    body: await response.text().catch(() => null),
   };
 }
 
@@ -52,9 +55,14 @@ async function expectRowShowing(page, text, read) {
     throw new Error(
       `no list row shows '${text}' after reloading in '${read.language}': the list GET sent Accept-Language ` +
         `${read.acceptLanguage ?? '(none)'} and answered ${read.status}, ` +
-        `${read.body.includes(text) ? 'WITH' : 'WITHOUT'} '${text}' in its body; the table's first row reads ` +
+        `${describeBody(read.body, text)}; the table's first row reads ` +
         `${firstRow ? `'${firstRow}'` : '(no rows)'}`,
       { cause: error },
     );
   }
 }
+
+function describeBody(body, text) {
+  if (body === null) return 'its body unavailable';
+  return `${body.includes(text) ? 'WITH' : 'WITHOUT'} '${text}' in its body`;
+}

package/test/flows/my.js

@@ -2,6 +2,7 @@ import { makeApi } from '../api.js';
 import { expect, test } from '../fixtures.js';
 import { resolveRelationSamples } from '../form.js';
 import { freshUniques, sampleRecord } from '../sample-values.js';
+import { CALENDAR_OR_SLOTS } from './list.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
@@ -28,7 +29,7 @@ function myUiTest(manifest, entity, mine, buildContext, idProperty) {
       const layout = entity.personal.layout ?? 'list';
       if (layout === 'calendar' || layout === 'slots') {
         await page.goto(manifest.standaloneShell + entity.personal.route);
-        await expect(page.locator('[x-h-calendar], [x-h-slot-picker]').first()).toBeVisible();
+        await expect(page.locator(CALENDAR_OR_SLOTS).first()).toBeVisible();
         return;
       }
       if (layout === 'document-chat' || layout === 'document') {
@@ -40,7 +41,9 @@ function myUiTest(manifest, entity, mine, buildContext, idProperty) {
           await page.getByRole('button', { name: /send/i }).first().click();
           await expect(page.getByText(message).first(), 'the sent message must render as a bubble').toBeVisible();
         } else {
-          await expect(page.locator('[x-h-toolbar-title]').first()).toBeVisible();
+          // visible only: the document carries a second toolbar title (its items table's), which can
+          // be the first in DOM order while hidden (dirigible #7545)
+          await expect(page.locator('[x-h-toolbar-title]').filter({ visible: true }).first()).toBeVisible();
         }
         return;
       }

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 { freshUniques, handleField, sampleRecord } from '../sample-values.js';
+import { freshUniqueKeys, 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.
@@ -16,7 +16,10 @@ export function restFlow(manifest, entity, opts = {}) {
     const handle = handleField(entity);
     // same resolution the UI flow uses: cross-model targets via apiAbsolute, entityStatus
     // relations left to their init: DB default
-    for (const sample of await resolveRelationSamples(api, manifest, entity)) {
+    const samples = await resolveRelationSamples(api, manifest, entity);
+    const taken = await freshUniqueKeys(client, entity, payload, samples);
+    test.skip(!!taken, `every ${entity.name} combination of the unique key [${taken}] tried already has a row`);
+    for (const sample of samples) {
       payload[sample.relation.name] = sample.id;
     }
     await freshUniques(client, entity, payload);

package/test/flows/shell.js

@@ -4,6 +4,7 @@ import { expect, test } from '../fixtures.js';
 // under its nav group and opens the module SPA in the embedded iframe. Requires the
 // navigation module that defines the groups, so it is opt-in: APPTEST_SHELL=1.
 export function shellFlow(manifest, entity) {
+  if (!entity.route) return; // no power page, no menu item
   test(`${entity.name}: shared shell menu item opens the module`, async ({ page }) => {
     test.skip(!process.env.APPTEST_SHELL, 'APPTEST_SHELL=1 enables the shared shell flow');
     await page.goto('/services/web/application/');

package/test/form.js

@@ -1,4 +1,5 @@
 import { makeApi } from './api.js';
+import { expect } from './fixtures.js';
 import { editableFields, handleField } from './sample-values.js';
 
 // Generated form controls: every field input has id="f_<Name>"; a to-one relation is a
@@ -34,15 +35,25 @@ async function relationTrigger(page, relation) {
 
 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
+  const input = page.locator('#f_' + relation.name);
+  // visible only: an option list that is closing, or another select's, must not be the one clicked
+  const option = page.getByRole('option', { name: optionText }).filter({ visible: true }).first();
+  for (let attempt = 0; ; attempt++) {
     await trigger.click();
-    await option.click({ force: true });
+    try {
+      await option.click({ timeout: 10_000 });
+    } catch {
+      // the option list re-rendered mid-click (async option load reflow) - reopen and retry
+      await trigger.click();
+      await option.click({ force: true });
+    }
+    // The list must be closed before the next relation's trigger is clicked: a click landing while
+    // it is still open only dismisses it, and that select stays empty - the second of two relations
+    // to the same entity was left at its placeholder that way (dirigible #7545).
+    await expect(option).toBeHidden();
+    if (!(await input.count()) || (await input.inputValue()) !== '' || attempt > 0) break;
   }
+  if (await input.count()) await expect(input, `${relation.name} must hold the picked "${optionText}"`).not.toHaveValue('');
 }
 
 // Resolve a live option for each to-one relation: take the first suitable row of the
@@ -54,7 +65,9 @@ export async function pickDropdown(page, relation, optionText) {
 // - a where: option filter narrows the candidate rows to matching ones;
 // - a dependsOn cascade forces CONSISTENT samples: the dependent row is chosen first and
 //   its filterBy FK becomes the trigger sibling's sample (independent first rows would
-//   pick e.g. Country=Afghanistan + City=Sofia, and the cascade then offers no options).
+//   pick e.g. Country=Afghanistan + City=Sofia, and the cascade then offers no options);
+// - a relation an agree check or a composite unique key names keeps a page of candidate rows, so
+//   agreeing rows can be chosen here and a free key combination by freshUniqueKeys.
 export async function resolveRelationSamples(request, manifest, entity) {
   const api = makeApi(request, manifest);
   const idProperty = manifest.idProperty ?? 'Id';
@@ -67,11 +80,13 @@ export async function resolveRelationSamples(request, manifest, entity) {
     return { rows: await api.list(target, limit), labelFrom: relation.labelFrom ?? handleField(target)?.name ?? 'Name' };
   }
 
+  const constrained = new Set([...(entity.agree ?? []).flatMap((check) => check.relations), ...(entity.uniqueKeys ?? []).flat()]);
   const samples = [];
   for (const relation of entity.relations ?? []) {
     if (relation.entityStatus) continue;
-    // a filtered picker needs a matching candidate, so fetch a page and filter client-side
-    const wide = relation.where || relation.leafOnly;
+    // a filtered picker needs a matching candidate, so fetch a page and filter client-side; a
+    // constrained relation needs alternatives to choose from
+    const wide = relation.where || relation.leafOnly || constrained.has(relation.name);
     const { rows: fetched, labelFrom } = await fetchRows(relation, wide ? 200 : 1);
     let rows = relation.where ? fetched?.filter((r) => String(r[relation.where.by]) === String(relation.where.value)) : fetched;
     if (relation.leafOnly && rows?.length) {
@@ -91,12 +106,18 @@ export async function resolveRelationSamples(request, manifest, entity) {
       // relation unset rather than clicking blind
       continue;
     }
-    samples.push({
+    const sample = {
       relation,
-      row: rows[0],
-      id: rows[0][idProperty],
-      label: label ?? String(rows[0][idProperty]),
-    });
+      rows,
+      // re-point the sample at another of its candidate rows
+      use(row) {
+        this.row = row;
+        this.id = row[idProperty];
+        this.label = row[labelFrom] ?? String(row[idProperty]);
+      },
+    };
+    sample.use(rows[0]);
+    samples.push(sample);
   }
 
   // cascade consistency: re-point each dependsOn trigger at the row the dependent's choice implies
@@ -104,6 +125,9 @@ export async function resolveRelationSamples(request, manifest, entity) {
     const dependsOn = sample.relation.dependsOn;
     if (!dependsOn?.filterBy) continue;
     const trigger = samples.find((s) => s.relation.name === dependsOn.relation);
+    // a cascade pair is chosen together - neither side may be swapped for a candidate later
+    sample.rows = [sample.row];
+    if (trigger) trigger.rows = [trigger.row];
     const impliedId = sample.row[dependsOn.filterBy];
     if (!trigger || impliedId == null || trigger.id === impliedId) continue;
     const path = trigger.relation.apiAbsolute ?? (trigger.relation.api ? manifest.restBase + trigger.relation.api : null);
@@ -111,20 +135,46 @@ export async function resolveRelationSamples(request, manifest, entity) {
     const row = await api.getPath(`${path}/${impliedId}`);
     if (!row) continue;
     trigger.row = row;
+    trigger.rows = [row];
     trigger.id = impliedId;
     trigger.label = row[trigger.relation.labelFrom ?? 'Name'];
   }
+  alignAgreeing(entity, samples);
   return samples;
 }
 
+// An agree check refuses a record whose two relations point at targets that differ on onProperty
+// (a transfer between stores of two companies), and the first row of each target is an arbitrary
+// pair. Choose the first lead row for which every other side has a candidate carrying the same value.
+function alignAgreeing(entity, samples) {
+  for (const check of entity.agree ?? []) {
+    const sides = check.relations.map((name) => samples.find((s) => s.relation.name === name));
+    if (sides.some((side) => !side)) continue; // an unset side has nothing to disagree about
+    const [lead, ...others] = sides;
+    for (const row of lead.rows) {
+      const value = row[check.onProperty];
+      if (value == null) continue;
+      const matches = others.map((side) => side.rows.find((candidate) => String(candidate[check.onProperty]) === String(value)));
+      if (matches.some((match) => !match)) continue;
+      lead.use(row);
+      others.forEach((side, i) => side.use(matches[i]));
+      break;
+    }
+  }
+}
+
 export async function fillForm(page, manifest, entity, record, relationSamples, opts = {}) {
   for (const field of editableFields(entity)) {
     if (record[field.name] === undefined) continue;
     await fillField(page, field, record[field.name], opts);
   }
+  // a readOnly relation renders as a disabled combobox (an update-time calculated action, a
+  // platform-owned FK) - the server sets it, so there is nothing to pick (dirigible #7554); the
+  // REST flows still post its sample, which the calculated action overwrites or checks
+  const pickable = relationSamples.filter((s) => !s.relation.readOnly);
   // cascade order: a dependsOn trigger must be picked BEFORE its dependent, so the narrowed
   // option list is the one the dependent's sample was chosen from
-  const triggers = relationSamples.filter((s) => !s.relation.dependsOn);
-  const dependents = relationSamples.filter((s) => s.relation.dependsOn);
+  const triggers = pickable.filter((s) => !s.relation.dependsOn);
+  const dependents = pickable.filter((s) => s.relation.dependsOn);
   for (const sample of [...triggers, ...dependents]) await pickDropdown(page, sample.relation, sample.label);
 }

package/test/sample-values.js

@@ -1,4 +1,5 @@
 const ALPHA = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+const LOWER = ALPHA.toLowerCase();
 const DIGITS = '0123456789';
 
 function rand(chars, n) {
@@ -33,6 +34,12 @@ export function sampleValue(field) {
       // full ISO instant: the generated Java entities bind java.time.Instant, which rejects a
       // zone-less value; the UI fill slices this to the datetime-local shape
       return '2026-07-08T10:00:00Z';
+    // the input shapes of an <input type="month|week"> - a month column is VARCHAR(7), so the
+    // default marker overflows it (dirigible #7545)
+    case 'month':
+      return '2026-07';
+    case 'week':
+      return '2026-W28';
     default:
       return 'APPTEST-' + rand(ALPHA + DIGITS, 6);
   }
@@ -61,6 +68,10 @@ function shaped(field, value) {
     `apptest.${token}@apptest.example.com`, // format: email and other address-shaped patterns
     token, // letters and digits, no separator
     rand(DIGITS, 10), // a numeric code
+    // a letters-only code (an ISO language or country code, ^[a-z]{2,3}$) - kept short, the shape
+    // such a pattern declares, and within the declared length (dirigible #7545)
+    rand(LOWER, Math.min(field.length ?? 3, 3)),
+    rand(ALPHA, Math.min(field.length ?? 3, 3)),
   ];
   const match = candidates.find((candidate) => candidate.length <= (field.length ?? 255) && regex.test(candidate));
   return match ?? (field.required ? value : undefined);
@@ -87,6 +98,10 @@ function uniqueValue(field) {
       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');
     }
+    case 'month':
+      return `${2100 + (n % 900)}-${String(1 + (n % 12)).padStart(2, '0')}`;
+    case 'week':
+      return `${2100 + (n % 900)}-W${String(1 + (n % 52)).padStart(2, '0')}`;
     default:
       return sampleValue({ ...field, unique: false });
   }
@@ -118,6 +133,65 @@ export async function freshUniques(client, entity, record) {
   return record;
 }
 
+// A composite unique key (`unique: [ProjectTimesheet, Employee]` - one timesheet per employee per
+// project-month) refuses a second row carrying the same combination with 409, and the first row of
+// each relation is the combination a seed most likely holds already (dirigible #7545). Walk the
+// candidate rows of the key's relations (and redraw its own fields) until the controller's filtered
+// read finds no row with that combination, keeping every agree check satisfied. Answers the key no
+// free combination was found for - the flow skips with it - or null when the record is free. Call it
+// before the relation samples are copied into the record.
+export async function freshUniqueKeys(client, entity, record, samples) {
+  for (const key of entity.uniqueKeys ?? []) {
+    const related = key.map((name) => samples.find((s) => s.relation.name === name)).filter(Boolean);
+    const drawn = editableFields(entity).filter((f) => key.includes(f.name) && f.name in record);
+    // a member left unset is NULL, and a NULL never collides
+    if (related.length + drawn.length < key.length) continue;
+    let free = false;
+    for (const combination of combinations(related.map((s) => s.rows), related.length ? 50 : 5)) {
+      combination.forEach((row, i) => related[i].use(row));
+      if (!agreeing(entity, samples)) continue;
+      const value = (name) => related.find((s) => s.relation.name === name)?.id ?? record[name];
+      let rows;
+      try {
+        rows = await client.search(entity, key.map((name) => ({ propertyName: name, operator: 'EQ', value: String(value(name)) })));
+      } catch {
+        free = true; // an older controller without /search - keep the combination, as freshUniques does
+        break;
+      }
+      if (!rows?.length) {
+        free = true;
+        break;
+      }
+      for (const field of drawn) record[field.name] = field.type === 'string' ? sampleValue(field) : uniqueValue(field);
+    }
+    if (!free) return key;
+    if (drawn.length) steerCompares(entity, record);
+  }
+  return null;
+}
+
+// The first `limit` entries of the cartesian product of the candidate lists, in order - so the first
+// combination is the one the samples started with. No lists yields `limit` empty combinations: a key
+// of own fields only is retried by redrawing them.
+function* combinations(lists, limit) {
+  const index = lists.map(() => 0);
+  for (let produced = 0; produced < limit; produced++) {
+    yield lists.map((list, i) => list[index[i]]);
+    let i = lists.length - 1;
+    while (i >= 0 && ++index[i] === lists[i].length) index[i--] = 0;
+    if (lists.length && i < 0) return;
+  }
+}
+
+// Whether the relation samples satisfy every agree check of the entity (an unset side has nothing to
+// disagree about).
+export function agreeing(entity, samples) {
+  return (entity.agree ?? []).every((check) => {
+    const values = check.relations.map((name) => samples.find((s) => s.relation.name === name)?.row?.[check.onProperty]);
+    return values.some((value) => value == null) || values.every((value) => String(value) === String(values[0]));
+  });
+}
+
 export function editableFields(entity) {
   return (entity.fields ?? []).filter((f) => !f.readOnly && !f.primaryKey && !f.generated);
 }