@startsimpli/ui 0.4.104 → 0.4.105

package/src/foundry/__tests__/record-validation.test.ts

@@ -0,0 +1,132 @@
+import {
+  hasErrors,
+  mergeRecordData,
+  NAME_FIELD,
+  validateRecord,
+} from '../record-validation';
+import { isSystemAttribute } from '../system-attrs';
+import { toCamelKey } from '../types';
+import type { AttributeDef, EntityTypeDef } from '../types';
+
+function attr(
+  name: string,
+  dataType: AttributeDef['dataType'] = 'text',
+  required = false,
+): AttributeDef {
+  return { id: `id-${name}`, name, dataType, required, config: {} };
+}
+
+// The live patent type: `number` required, the rest optional.
+const PATENT: EntityTypeDef = {
+  id: 'patent-id',
+  key: 'patent',
+  label: 'Patent',
+  attributes: [
+    attr('number', 'text', true),
+    attr('title'),
+    attr('expiration', 'date'),
+    attr('legacy_uuid'),
+    attr('notes', 'json'),
+  ],
+};
+
+describe('validateRecord', () => {
+  it('accepts a complete record', () => {
+    expect(
+      validateRecord(PATENT, 'US1', { number: 'US1', title: 'A patent' }),
+    ).toEqual({});
+  });
+
+  it('honours the red asterisk the form has always drawn', () => {
+    const errors = validateRecord(PATENT, 'US1', { number: '   ' });
+    expect(errors.number).toBe('number is required.');
+    expect(hasErrors(errors)).toBe(true);
+  });
+
+  it('reports EVERY problem at once, not the first', () => {
+    const errors = validateRecord(PATENT, '', { number: '', notes: '{oops' });
+    expect(Object.keys(errors).sort()).toEqual([NAME_FIELD, 'notes', 'number'].sort());
+  });
+
+  it('requires the record name, which is Entity.name and not the `name` attribute', () => {
+    expect(validateRecord(PATENT, '  ', { number: 'US1' })[NAME_FIELD]).toBe(
+      'Give this record a name.',
+    );
+  });
+
+  it('accepts blank optional JSON but refuses malformed JSON', () => {
+    expect(validateRecord(PATENT, 'US1', { number: 'US1', notes: '' })).toEqual({});
+    expect(validateRecord(PATENT, 'US1', { number: 'US1', notes: '{' }).notes).toContain(
+      'not valid JSON',
+    );
+  });
+});
+
+describe('mergeRecordData', () => {
+  const current = {
+    number: 'US20230306066A1',
+    title: 'Systems and methods for web scraping',
+    legacyUuid: '19d1486e-c003-4060-8150-cad5920dca92',
+  };
+
+  it('PRESERVES a system-provenance attribute across an edit', () => {
+    // The guard renders legacy_uuid read-only but keeps it in `values`. If it
+    // were dropped from the form instead, the blank rule below would delete it —
+    // silently breaking the /products/<uuid> redirect printed on the article.
+    expect(isSystemAttribute('legacy_uuid')).toBe(true);
+    const next = mergeRecordData(
+      PATENT,
+      current,
+      {
+        number: 'US20230306066A1',
+        title: 'A better title',
+        legacy_uuid: '19d1486e-c003-4060-8150-cad5920dca92',
+      },
+      toCamelKey,
+    );
+    expect(next.legacyUuid).toBe('19d1486e-c003-4060-8150-cad5920dca92');
+    expect(next.title).toBe('A better title');
+  });
+
+  it('would have LOST it had the field been dropped from the form — the trap, pinned', () => {
+    const next = mergeRecordData(PATENT, current, { number: 'US1', title: 'T' }, toCamelKey);
+    expect(next.legacyUuid).toBeUndefined();
+  });
+
+  it('canonicalizes to camelCase and does not leave both spellings behind', () => {
+    const next = mergeRecordData(
+      PATENT,
+      { legacy_uuid: 'old' },
+      { number: 'US1', legacy_uuid: 'old' },
+      toCamelKey,
+    );
+    expect(next.legacyUuid).toBe('old');
+    expect('legacy_uuid' in next).toBe(false);
+  });
+
+  it('keeps undeclared keys the schema does not know about', () => {
+    const next = mergeRecordData(
+      PATENT,
+      { number: 'US1', _origin: 'seed' },
+      { number: 'US1' },
+      toCamelKey,
+    );
+    expect(next._origin).toBe('seed');
+  });
+});
+
+describe('isSystemAttribute', () => {
+  it('catches the declared provenance names and the conventions around them', () => {
+    expect(isSystemAttribute('legacy_uuid')).toBe(true);
+    expect(isSystemAttribute('LEGACY_UUID')).toBe(true);
+    expect(isSystemAttribute('source_ref')).toBe(true);
+    expect(isSystemAttribute('_origin')).toBe(true);
+    expect(isSystemAttribute('vendor_uuid')).toBe(true);
+  });
+
+  it('leaves ordinary business fields editable', () => {
+    for (const n of ['name', 'number', 'title', 'stock_no', 'code', 'description', 'expiration']) {
+      expect(isSystemAttribute(n)).toBe(false);
+    }
+  });
+});

package/src/foundry/__tests__/types.test.ts

@@ -0,0 +1,53 @@
+/**
+ * The key transform is a JOIN between this package and every tenant app: the
+ * app writes `Entity.data` through its own helper and this module reads it. Two
+ * spellings of the same rule produce a blank cell and no error, so the rule is
+ * pinned here rather than assumed.
+ */
+import { readRecordValue, recordLabel, sameId, toCamelKey } from '../types';
+
+describe('toCamelKey', () => {
+  it('camelises a snake_case attribute name', () => {
+    expect(toCamelKey('stock_no')).toBe('stockNo');
+    expect(toCamelKey('legacy_uuid')).toBe('legacyUuid');
+    expect(toCamelKey('country_code_2')).toBe('countryCode2');
+  });
+
+  it('COLLAPSES a run of underscores, the way the api client does', () => {
+    // `_` rather than `_+` here would look `foo__bar` up as `foo_Bar`, a key
+    // nothing ever wrote.
+    expect(toCamelKey('foo__bar')).toBe('fooBar');
+  });
+
+  it('leaves an already-camel name alone', () => {
+    expect(toCamelKey('stockNo')).toBe('stockNo');
+  });
+});
+
+describe('readRecordValue', () => {
+  it('prefers the camelised key and falls back to the raw one', () => {
+    expect(readRecordValue({ stockNo: 'SW4435' }, 'stock_no')).toBe('SW4435');
+    expect(readRecordValue({ stock_no: 'SW4435' }, 'stock_no')).toBe('SW4435');
+    expect(readRecordValue({}, 'stock_no')).toBeUndefined();
+    expect(readRecordValue(undefined, 'stock_no')).toBeUndefined();
+  });
+
+  it('takes the app own transform when it has one', () => {
+    expect(readRecordValue({ STOCK_NO: 'x' }, 'stock_no', (n) => n.toUpperCase())).toBe('x');
+  });
+});
+
+describe('sameId / recordLabel', () => {
+  it('compares a UUID string and a fixture number as strings', () => {
+    expect(sameId('7', 7)).toBe(true);
+    expect(sameId(null, 7)).toBe(false);
+  });
+
+  it('falls back name -> external id -> short id', () => {
+    expect(recordLabel({ id: 'abcdef012345', name: 'Widget' })).toBe('Widget');
+    expect(recordLabel({ id: 'abcdef012345', name: '', externalId: 'SW1' })).toBe('SW1');
+    expect(recordLabel({ id: 'abcdef012345' })).toBe('#abcdef01');
+    expect(recordLabel(null, 'abcdef012345')).toBe('#abcdef01');
+    expect(recordLabel(null)).toBe('Unknown record');
+  });
+});

package/src/foundry/index.ts

@@ -0,0 +1,21 @@
+/**
+ * FOUNDRY TENANT UI — the list, link and publication verbs every tenant app
+ * needs, and no tenant app should have to rediscover.
+ *
+ * A SUBPATH AND NOT THE ROOT BARREL, deliberately. Everything here speaks the
+ * foundry tenant contract (declared types, attributes, relationships, grants).
+ * `org-landing`, `present-web` and the rest of the @startsimpli/ui consumers have
+ * no such API and should not pull this in by importing the package.
+ *
+ *     import { linkSidesFor, listParams } from '@startsimpli/ui/foundry'
+ *
+ * Lifted out of one tenant's fork under CLAUDE.md rule 9 — bd startsim-768w.63.
+ */
+export * from './types';
+export * from './links';
+export * from './list-query';
+export * from './publication';
+export * from './record-validation';
+export * from './system-attrs';
+export { LinkPanel, linkQueryKey } from './LinkPanel';
+export type { LinkPanelApi, LinkPanelProps, LinkPanelPage } from './LinkPanel';

package/src/foundry/links.ts

@@ -0,0 +1,227 @@
+/**
+ * THE LINK SIDE — one relationship, read from either end.
+ *
+ * A tenant's relationships are declared, directional and few: `RelationshipDef`
+ * fixes a source type and a target type, and the tenant's `_validate_edge_types`
+ * refuses an edge written the other way round. The screen the user is on does
+ * NOT change that. So the natural unit is not "the products of a category" or
+ * "the patents on a product" — it is a LINK SIDE: "for a record of type X,
+ * relationship R reaches records of type Y, and X sits at <end> of the edge".
+ *
+ * Modelling it that way is what stops the two ends drifting. The alternative —
+ * one component per direction — is two fetches and two chances to disagree about
+ * what a link is, and the reverse one is the one nobody demos.
+ *
+ * THE DIRECTION TRAP THIS MODULE EXISTS TO CONTAIN. "Link this patent to a
+ * product" must still POST source=<product>, target=<patent>, because that is
+ * the direction the def declares. A component that naively used
+ * (thisRecord, thatRecord) is wrong exactly half the time. `edgeEndpoints()` is
+ * the single place that decision is made.
+ *
+ * Lifted out of a tenant fork (bd startsim-768w.63); originally bd startsim-16d5.
+ */
+import {
+  sameId,
+  type EntityId,
+  type EntityRecordShape,
+  type EntityTypeShape,
+  type RelationshipDefShape,
+  type RelationshipEdgeShape,
+} from './types';
+
+export { sameId, recordLabel } from './types';
+
+/** Which end of the edge THIS record occupies. */
+export type EdgeRole = 'source' | 'target';
+
+export interface LinkSide {
+  /** RelationshipDef.key — the `rel_type` on the wire. */
+  relType: string;
+  /** The end THIS record occupies in the declared edge. */
+  role: EdgeRole;
+  /** The type key of the records on the OTHER end. */
+  farTypeKey: string;
+  /** The other type's human label, for the panel heading. */
+  farTypeLabel: string;
+}
+
+/**
+ * Every link side a type has, from the org's declared relationships.
+ *
+ * A self-referential def (source_type === target_type) yields BOTH sides, which
+ * is correct and is why this returns a list rather than a map keyed by relType:
+ * "translations of this draft" and "the draft this is a translation of" are two
+ * different panels over one relationship.
+ */
+export function linkSidesFor(
+  type: EntityTypeShape | null | undefined,
+  defs: RelationshipDefShape[],
+  types: EntityTypeShape[],
+): LinkSide[] {
+  if (!type) return [];
+  const byId = new Map(types.map((t) => [String(t.id), t]));
+  const sides: LinkSide[] = [];
+  for (const def of defs) {
+    const src = byId.get(String(def.sourceType));
+    const tgt = byId.get(String(def.targetType));
+    if (!src || !tgt) continue; // a def naming a type this caller cannot read
+    if (String(def.sourceType) === String(type.id)) {
+      sides.push({ relType: def.key, role: 'source', farTypeKey: tgt.key, farTypeLabel: tgt.label });
+    }
+    if (String(def.targetType) === String(type.id)) {
+      sides.push({ relType: def.key, role: 'target', farTypeKey: src.key, farTypeLabel: src.label });
+    }
+  }
+  return sides;
+}
+
+/**
+ * The `related_direction` that returns the FAR records for a side.
+ *
+ * MEASURED against a live tenant rather than read off the docstring, because
+ * `filters._one_hop`'s prose ("direction describes the RECORD's end") is
+ * ambiguous about WHICH record and the wrong answer returns an empty list with
+ * `applied_filters` still reporting success. The parameter describes the RESULT
+ * record's end: so when THIS record is the source, the far record is the target
+ * -> 'in'; when this record is the target, the far record is the source -> 'out'.
+ */
+export function farDirection(side: LinkSide): 'in' | 'out' {
+  return side.role === 'source' ? 'in' : 'out';
+}
+
+/**
+ * The `related_direction` for listing records OF THIS TYPE that are linked to a
+ * named FAR record — "the products in this category", "the patents on this
+ * article". The mirror of `farDirection`, and the reason it is its own function
+ * rather than a `!` at a call site: the parameter always describes the RESULT
+ * record's end of the edge, and here the result is the NEAR record, so the two
+ * readings are opposites and swapping them returns an empty list with
+ * `applied_filters` still reporting success.
+ */
+export function nearDirection(side: LinkSide): 'in' | 'out' {
+  return side.role === 'source' ? 'out' : 'in';
+}
+
+/**
+ * The (source, target) a NEW edge for this side must carry — the declared
+ * direction, never the user's viewpoint. See the module note.
+ */
+export function edgeEndpoints(
+  side: LinkSide,
+  thisId: EntityId,
+  farId: EntityId,
+): { relType: string; source: EntityId; target: EntityId } {
+  return side.role === 'source'
+    ? { relType: side.relType, source: thisId, target: farId }
+    : { relType: side.relType, source: farId, target: thisId };
+}
+
+/** The edges from a record's full edge set that belong to one side. */
+export function edgesForSide<E extends RelationshipEdgeShape>(
+  edges: E[],
+  side: LinkSide,
+  thisId: EntityId,
+): E[] {
+  return edges.filter(
+    (e) =>
+      e.relType === side.relType &&
+      (side.role === 'source' ? sameId(e.source, thisId) : sameId(e.target, thisId)),
+  );
+}
+
+/** The far end of an edge, given which end this record is on. */
+export function farIdOf(edge: RelationshipEdgeShape, side: LinkSide): EntityId {
+  return side.role === 'source' ? edge.target : edge.source;
+}
+
+export interface LinkRow<
+  E extends RelationshipEdgeShape = RelationshipEdgeShape,
+  R extends EntityRecordShape = EntityRecordShape,
+> {
+  edge: E;
+  record: R | null;
+}
+
+/**
+ * Pair each edge with the far record it points at.
+ *
+ * BOTH HALVES ARE NEEDED AND NEITHER SUBSTITUTES FOR THE OTHER: the entity
+ * query carries the far record's NAME and its attributes, and the edge carries
+ * the id that unlinking deletes. A row whose record is null is an edge whose far
+ * end this caller cannot read (a per-type or per-row gate) — it is rendered as
+ * such rather than dropped, because silently hiding an association would
+ * understate what the record is linked to.
+ */
+export function joinLinkRows<E extends RelationshipEdgeShape, R extends EntityRecordShape>(
+  edges: E[],
+  side: LinkSide,
+  farRecords: R[],
+): LinkRow<E, R>[] {
+  const byId = new Map(farRecords.map((r) => [String(r.id), r]));
+  return edges.map((edge) => ({
+    edge,
+    record: byId.get(String(farIdOf(edge, side))) ?? null,
+  }));
+}
+
+/**
+ * Candidates for a new link: everything of the far type that is not already
+ * linked, and never the record itself.
+ *
+ * ALREADY-LINKED IS EXCLUDED IN THE PICKER because nothing below it enforces
+ * cardinality — neither "at most one" nor per-org uniqueness is expressible on
+ * the relationship model (bd startsim-768w.16.17), and the tenant accepts a
+ * duplicate `(rel_type, source, target)` without complaint. Two identical edges
+ * render the same far record twice.
+ */
+export function linkCandidates<R extends EntityRecordShape>(
+  pool: R[],
+  linkedFarIds: EntityId[],
+  selfId: EntityId,
+): R[] {
+  const taken = new Set(linkedFarIds.map(String));
+  return pool.filter((r) => !taken.has(String(r.id)) && !sameId(r.id, selfId));
+}
+
+/** Per-record link counts for one page of a table, from one bulk edge read. */
+export function countLinksByRecord(
+  edges: RelationshipEdgeShape[],
+  side: LinkSide,
+): Map<string, number> {
+  const out = new Map<string, number>();
+  for (const e of edges) {
+    if (e.relType !== side.relType) continue;
+    const key = String(side.role === 'source' ? e.source : e.target);
+    out.set(key, (out.get(key) ?? 0) + 1);
+  }
+  return out;
+}
+
+/**
+ * The counts a STRANGER would see — the same edges, narrowed by the rule the
+ * public read path enforces.
+ *
+ * THE RESTRICTIVE POLICY GATES AN EDGE ON BOTH ENDS BEING PUBLISHED
+ * (tenant-starter apps/core/public_rls.py; the app layer says it again in
+ * `PublicEntityDetailSerializer.get_related`). So an admin row reading "3 links"
+ * and a public page listing two of them are BOTH correct, and the difference is
+ * the thing that must not be silent — on a legal notice the number is the claim.
+ *
+ * Zero when the record itself is unpublished, because then it has no public page
+ * at all — not "3 links that nobody can see".
+ */
+export function countPublicLinksByRecord(
+  edges: RelationshipEdgeShape[],
+  side: LinkSide,
+  publishedIds: Set<string>,
+): Map<string, number> {
+  const out = new Map<string, number>();
+  for (const e of edges) {
+    if (e.relType !== side.relType) continue;
+    const nearId = String(side.role === 'source' ? e.source : e.target);
+    const farId = String(side.role === 'source' ? e.target : e.source);
+    if (!publishedIds.has(nearId) || !publishedIds.has(farId)) continue;
+    out.set(nearId, (out.get(nearId) ?? 0) + 1);
+  }
+  return out;
+}

package/src/foundry/list-query.ts

@@ -0,0 +1,241 @@
+/**
+ * THE LIST QUERY — search, sort, per-column filters, as pure functions.
+ *
+ * A tenant's list endpoint serves `?search=`, `?order=attr.<name>` and the full
+ * `?attr.<name>[__op]=` operator set, so every one of those verbs belongs on the
+ * SERVER. Doing them in the browser is only correct while the whole corpus fits
+ * in one page, and it stops being correct silently.
+ *
+ * MEASURED AGAINST A LIVE TENANT, not read off a docstring, because every
+ * mistake in this file is SILENT:
+ *
+ *   ?order=attr.<declared>     200, `applied_filters: ["order"]`, really ordered
+ *   ?order=attr.<undeclared>   200, `applied_filters: ["order"]`, ORDERED BY NOTHING
+ *   ?order=name                400 {"order": "expected recent, oldest, relevance,
+ *                                   or attr.<name>"}
+ *   ?order=recent / oldest     created_at desc / asc
+ *   ?attr.<date>__icontains=   400 "must be an ISO-8601 date or timestamp"
+ *
+ * So a sort arrow that moves while the rows do not is one typo away at all
+ * times, and the only defence is that the column -> attribute mapping is derived
+ * from the SAME `type.attributes` list the columns were built from.
+ *
+ * THE ID MAPPING IS THE TRAP. A column builder must namespace an attribute whose
+ * name collides with a framing column — a type that declares an attribute
+ * literally called `name` needs the id `attr_name`, because the id `name`
+ * belongs to the framing column that renders `Entity.name`. `order=attr.attr_name`
+ * would be accepted and sort nothing.
+ *
+ * Lifted out of a tenant fork (bd startsim-768w.63); originally bd startsim-4ph9d.
+ */
+import type { AttributeShape } from './types';
+
+/** The leading column, rendering `Entity.name`. */
+export const NAME_COLUMN_ID = 'name';
+/** The trailing column, rendering `Entity.created_at`. */
+export const CREATED_COLUMN_ID = 'createdAt';
+/** Prefix a column builder uses when an attribute name collides with a framing id. */
+export const ATTR_COLUMN_PREFIX = 'attr_';
+
+const RESERVED_COLUMN_IDS = new Set([NAME_COLUMN_ID, CREATED_COLUMN_ID]);
+
+/** The column id an attribute gets. One definition, two callers, so the table
+ *  and the query can never disagree about a name. */
+export function columnIdForAttribute(attr: AttributeShape): string {
+  return RESERVED_COLUMN_IDS.has(attr.name) ? `${ATTR_COLUMN_PREFIX}${attr.name}` : attr.name;
+}
+
+/**
+ * The declared attribute a column renders, or null for a framing/derived column.
+ *
+ * INVERTS `columnIdForAttribute` rather than re-deriving the id rule, so the two
+ * cannot drift — and so an attribute whose own name happens to start with
+ * `attr_` maps to itself instead of being mistaken for a namespaced one.
+ */
+export function attributeForColumn<A extends AttributeShape>(
+  columnId: string,
+  attributes: A[],
+): A | null {
+  if (RESERVED_COLUMN_IDS.has(columnId)) return null;
+  return attributes.find((a) => columnIdForAttribute(a) === columnId) ?? null;
+}
+
+export type SortDirection = 'asc' | 'desc';
+
+export interface ListSort {
+  columnId: string;
+  direction: SortDirection;
+}
+
+/**
+ * Can the SERVER order by this column?
+ *
+ * `Entity.name` cannot be ordered (`?order=name` is a 400), which is why a type
+ * that wants a sortable primary column declares its own attribute for it. The
+ * leading Name column is therefore NOT sortable and should say so — a sort
+ * control that silently orders by a different value than the one in the cell is
+ * the failure this whole module is shaped to avoid. Association-count and any
+ * other derived column: same answer, no server ordering exists for a COUNT.
+ */
+export function isSortableColumn(columnId: string, attributes: AttributeShape[]): boolean {
+  if (columnId === CREATED_COLUMN_ID) return true;
+  return attributeForColumn(columnId, attributes) !== null;
+}
+
+/** The `?order=` value for a sort, or null when the column cannot be ordered. */
+export function orderParam(
+  sort: ListSort | null | undefined,
+  attributes: AttributeShape[],
+): string | null {
+  if (!sort) return null;
+  if (sort.columnId === CREATED_COLUMN_ID) return sort.direction === 'desc' ? 'recent' : 'oldest';
+  const attr = attributeForColumn(sort.columnId, attributes);
+  if (!attr) return null;
+  return `${sort.direction === 'desc' ? '-' : ''}attr.${attr.name}`;
+}
+
+/**
+ * A per-column filter the table can offer. `kind` decides both the widget and
+ * the operator, because the two are not independent: `__icontains` on a date
+ * attribute is a 400, not an empty result.
+ */
+export interface ColumnFilterDef {
+  /** Filter id === the table column id it sits under. */
+  id: string;
+  label: string;
+  kind: 'text' | 'date-window';
+  attrName: string;
+}
+
+/** Value the dropdown/select uses for "no filter" (UnifiedTable's own sentinel). */
+export const ALL_VALUE = 'all';
+
+/** Date-window choices, expressed as an operator against today. */
+export const DATE_WINDOWS = {
+  past: 'Before today',
+  future: 'Today or later',
+} as const;
+export type DateWindow = keyof typeof DATE_WINDOWS;
+
+/**
+ * The filters a type offers, from its declared attributes.
+ *
+ * `longtext` is filterable the same way `text` is (both land in `value_text`),
+ * but a `json` or `boolean` attribute gets nothing: neither has a widget here
+ * worth the ambiguity, and a filter box that quietly matches nothing is the
+ * thing `ignored_filters` exists to prevent.
+ */
+export function columnFiltersFor(attributes: AttributeShape[]): ColumnFilterDef[] {
+  const out: ColumnFilterDef[] = [];
+  for (const attr of attributes) {
+    const id = columnIdForAttribute(attr);
+    if (attr.dataType === 'text' || attr.dataType === 'longtext') {
+      out.push({ id, label: attr.name.replace(/_/g, ' '), kind: 'text', attrName: attr.name });
+    } else if (attr.dataType === 'date') {
+      out.push({
+        id,
+        label: attr.name.replace(/_/g, ' '),
+        kind: 'date-window',
+        attrName: attr.name,
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * Labels for a dropdown of far records, DISAMBIGUATED.
+ *
+ * `FilterItem.options` is a `string[]` and the widget reports back the option it
+ * rendered, so the label has to identify the record uniquely. `name` is usually
+ * free text and two records may share one; two identical options would collapse
+ * into a single entry that filters by whichever id the map happened to keep.
+ * Repeats get a short id suffix; unique names are left alone.
+ */
+export function farOptionLabels(
+  records: { id: string | number; name: string }[],
+): Map<string, string> {
+  const counts = new Map<string, number>();
+  for (const r of records) {
+    const base = r.name || String(r.id);
+    counts.set(base, (counts.get(base) ?? 0) + 1);
+  }
+  const out = new Map<string, string>();
+  for (const r of records) {
+    const base = r.name || String(r.id);
+    const label =
+      (counts.get(base) ?? 0) > 1 ? `${base} (#${String(r.id).slice(0, 8)})` : base;
+    out.set(label, String(r.id));
+  }
+  return out;
+}
+
+/** A link-side filter: "products IN this category", "patents ON this article". */
+export interface RelatedFilter {
+  /** The far record's id. */
+  relatedTo: string;
+  /** RelationshipDef.key. */
+  via: string;
+  /** The end THIS type's records occupy — see links.nearDirection. */
+  direction: 'in' | 'out';
+}
+
+export interface ListQuery {
+  type: string;
+  page: number;
+  search?: string;
+  sort?: ListSort | null;
+  /** columnId -> raw filter value (already stripped of the 'all' sentinel). */
+  filters?: Record<string, string>;
+  related?: RelatedFilter | null;
+  pageSize?: number;
+}
+
+/**
+ * The querystring for one page of a list.
+ *
+ * RAW SERVER NAMES, deliberately. `@startsimpli/api` camel->snake converts
+ * request BODIES and not `params` (its url-builder appends keys verbatim), and
+ * `attr.number__icontains` could not survive that transform anyway — there is no
+ * camelCase spelling of a double underscore. A mistyped key here does not error:
+ * the response reports it under `ignored_filters` and returns the UNFILTERED
+ * page, which reads as "everything matches".
+ */
+export function listParams(
+  query: ListQuery,
+  attributes: AttributeShape[],
+  today: Date = new Date(),
+): Record<string, string | number> {
+  const params: Record<string, string | number> = { type: query.type, page: query.page };
+  if (query.pageSize) params.page_size = query.pageSize;
+
+  const search = (query.search ?? '').trim();
+  if (search) params.search = search;
+
+  const order = orderParam(query.sort, attributes);
+  if (order) params.order = order;
+
+  const defs = new Map(columnFiltersFor(attributes).map((d) => [d.id, d]));
+  for (const [columnId, raw] of Object.entries(query.filters ?? {})) {
+    const value = String(raw ?? '').trim();
+    if (!value || value === ALL_VALUE) continue;
+    const def = defs.get(columnId);
+    if (!def) continue; // a filter for a column this type does not declare
+    if (def.kind === 'text') {
+      params[`attr.${def.attrName}__icontains`] = value;
+    } else if (value === 'past' || value === 'future') {
+      // Dates are compared as normalized ISO text server-side, so the bound has
+      // to be a plain YYYY-MM-DD. `lt today` / `gte today` splits a date column
+      // into "already past" and "still running" with no third state.
+      const iso = today.toISOString().slice(0, 10);
+      params[`attr.${def.attrName}__${value === 'past' ? 'lt' : 'gte'}`] = iso;
+    }
+  }
+
+  if (query.related) {
+    params.related_to = query.related.relatedTo;
+    params.related_via = query.related.via;
+    params.related_direction = query.related.direction;
+  }
+  return params;
+}