@globalpayments-private/gpds-pattern-web-react 0.0.0-stage → 0.1.1-pr.50.g2356b27

package/dist/composition/list.js

@@ -0,0 +1,90 @@
+import { resolveReference } from './reference';
+import { reactChildrenToArray } from './children';
+/** Marker component for one table column. Never rendered — see the module doc. */
+export function DataTableCol(_props) {
+    return null;
+}
+/** Marker component for the table view. Never rendered. */
+export function DataTable(_props) {
+    return null;
+}
+DataTable.Col = DataTableCol;
+/** Marker component for the board view. Never rendered — see the module doc. */
+export function Board(_props) {
+    return null;
+}
+/** Marker component for the card-grid view. Never rendered — see the module doc. */
+export function CardGrid(_props) {
+    return null;
+}
+/** Marker component for the list workflow. Never rendered — see the module doc. */
+export function List(_props) {
+    return null;
+}
+function columnFrom(element) {
+    const { field, label, sortable, align, width, reference, children } = element.props;
+    const base = {
+        field,
+        label,
+        sortable,
+        align,
+        width,
+        reference: resolveReference(reference),
+    };
+    return children ? { ...base, ...children(field, label) } : base;
+}
+function columnsFrom(children) {
+    const nodes = [];
+    reactChildrenToArray(children).forEach((child) => {
+        if (isElementOfType(child, DataTableCol)) {
+            nodes.push(child);
+        }
+    });
+    return nodes.map(columnFrom);
+}
+/**
+ * Reads a `<List>` element's props and view child into a `UdsAdminListConfig`
+ * — the exact shape `GpResource`'s `config.list` takes (ADR 0022).
+ *
+ * `perPage` is a scalar, forwarded as `UdsAdminResource.perPage` rather than
+ * as a member of this config (see `admin-config.ts`'s `perPage` doc) — the
+ * caller (`resource.tsx`) is responsible for placing it there; this function
+ * only returns what belongs under `list`.
+ *
+ * The view child decides the `layout` and nothing else: all three read the
+ * same `<DataTable.Col>` children into the same `columns`, which is what
+ * makes swapping one for another a one-tag change (ADR 0016). A `<List>` with
+ * no recognised view child keeps the table default rather than rendering
+ * nothing, matching the behaviour before the board and grid views existed.
+ */
+export function listConfigFromChildren(listChildren) {
+    const view = reactChildrenToArray(listChildren).find((child) => isElementOfType(child, DataTable) || isElementOfType(child, Board) || isElementOfType(child, CardGrid));
+    const columns = columnsFrom(view?.props.children);
+    const layout = layoutFrom(view);
+    const { rowActions, bulkActions } = view?.props ?? {};
+    // Written only when present, so an unconfigured member reaches the pattern
+    // as absent rather than as an explicit `undefined` — the same rule
+    // `listConfigFor` follows for the shorthands it hoists.
+    const config = columns.length ? { columns, layout } : { layout };
+    if (rowActions !== undefined)
+        config.rowActions = rowActions;
+    if (bulkActions !== undefined)
+        config.bulkActions = bulkActions;
+    return config;
+}
+/** The `layout` a view child stands for. `<DataTable>` and an absent child both mean a table. */
+function layoutFrom(view) {
+    if (view && isElementOfType(view, Board)) {
+        const { groupBy, lanes, title, fields, minLaneWidth } = view.props;
+        return { kind: 'board', groupBy, lanes, title, fields, minLaneWidth };
+    }
+    if (view && isElementOfType(view, CardGrid)) {
+        const { title, media, fields, minColumnWidth } = view.props;
+        return { kind: 'grid', title, media, fields, minColumnWidth };
+    }
+    return { kind: 'table' };
+}
+/** A React element whose `type` is exactly this marker function — not a subclass, not a lookalike. */
+function isElementOfType(node, type) {
+    return typeof node === 'object' && node !== null && 'type' in node && node.type === type;
+}

package/dist/composition/record.d.ts

@@ -0,0 +1,137 @@
+import type { ReactNode } from 'react';
+import type { UdsAdminRecordConfig, UdsRecordField, UdsRecordGroup, UdsRecordRelatedPanel } from '@globalpayments-private/gpds-pattern-web';
+/**
+ * `Show`, `Edit`, `Create` and `TabbedShowLayout`: non-rendering marker
+ * components read by `Resource` (`resource.tsx`) to build a
+ * `UdsAdminRecordConfig` before anything reaches `gp-resource`/
+ * `gp-pattern-record`. Same "why these never render" reasoning as
+ * `list.tsx` and `simple-form.tsx`.
+ *
+ * Named after real react-admin's own view components
+ * (https://marmelab.com/react-admin/EditTutorial.html,
+ * https://marmelab.com/react-admin/Create.html,
+ * https://marmelab.com/react-admin/TabbedShowLayout.html):
+ *
+ * ```tsx
+ * <Resource name="deals">
+ *   <Edit>
+ *     <SimpleForm>
+ *       <TextInput field="reference" label="Reference" />
+ *     </SimpleForm>
+ *   </Edit>
+ * </Resource>
+ * ```
+ *
+ * ## What these wrappers do, and the one thing they still cannot
+ *
+ * In real react-admin `<Edit>` and `<Create>` are *routed views*, and a
+ * resource may give each a **different** field set. That is now expressible:
+ * `UdsRecordField.modes` gates a field to the modes that have it (ADR 0031),
+ * and these wrappers are read into it — a field written under one wrapper
+ * only is gated to that wrapper's mode, and a field every wrapper present
+ * declares identically is left ungated, which is what a resource authored
+ * before `modes` existed already meant.
+ *
+ * Three things remain unexpressible, because the shell renders all three
+ * modes from one `fields` array, one `groups` array and one `layout`:
+ *
+ * - **Contradictory field order.** `<Show>` ordering `a, b` and `<Edit>`
+ *   ordering `b, a` cannot both be honoured by one array.
+ * - **A tab renamed between modes**, or a layout that is `tabs` in one
+ *   wrapper and a flat `<SimpleForm>` in another.
+ * - **Different related panels per mode.** A wrapper that declares no
+ *   `<ReferenceManyField>` is read as silent on the subject rather than as
+ *   saying there are none — otherwise the natural authoring, panels under
+ *   `<Show>` and not under `<Edit>`, would be an error. Two wrappers that
+ *   each declare panels and disagree is the real contradiction, and that is
+ *   rejected.
+ *
+ * Each is rejected loudly at read time rather than silently resolved to
+ * whichever wrapper happened to be read last. An affordance that quietly
+ * drops half of what it was given is the failure mode this layer's
+ * predecessor comment warned about; an error that names the limitation is
+ * not that.
+ *
+ * ## `<ReferenceManyField>` inside a view
+ *
+ * A `<ReferenceManyField>` written beside the form — react-admin's own
+ * placement — is read into `UdsRecordConfig.related`, the record-level
+ * related panel ADR 0031 adds, and takes its id from the record on screen.
+ * See `reference-many.tsx`.
+ */
+export interface ShowProps {
+    /** A `<SimpleForm>` or a `<TabbedShowLayout>`. */
+    children?: ReactNode;
+}
+/** Marker component for the show view. Never rendered — see the module doc. */
+export declare function Show(_props: ShowProps): null;
+export type EditProps = ShowProps;
+/** Marker component for the edit view. Never rendered — see the module doc. */
+export declare function Edit(_props: EditProps): null;
+export type CreateProps = ShowProps;
+/** Marker component for the create view. Never rendered — see the module doc. */
+export declare function Create(_props: CreateProps): null;
+/**
+ * One tab of a `<TabbedShowLayout>`, mirroring react-admin's
+ * `<TabbedShowLayout.Tab label="summary" path="summary">`.
+ */
+export interface TabbedShowLayoutTabProps {
+    label: string;
+    /**
+     * The tab's stable key, written to the URL and used as the panel's DOM id
+     * (`UdsRecordGroup.id`).
+     *
+     * Mirrors react-admin's `path`, including its default: omit it on the first
+     * tab and that tab becomes the index. Here the fallback is a slug of
+     * `label` rather than a positional index, because `UdsRecordGroup.id`'s own
+     * doc rules an index out — reordering tabs would silently re-point every
+     * saved link.
+     */
+    path?: string;
+    /** The input markers whose fields this tab renders, in order. */
+    children?: ReactNode;
+}
+/** Marker component for one tab. Never rendered — see the module doc. */
+export declare function TabbedShowLayoutTab(_props: TabbedShowLayoutTabProps): null;
+export interface TabbedShowLayoutProps {
+    /** `<TabbedShowLayout.Tab>` children, in order. */
+    children?: ReactNode;
+}
+/**
+ * Marker component for a tabbed record, read into `UdsRecordConfig.groups`
+ * plus `layout: 'tabs'`. Never rendered — see the module doc.
+ */
+export declare function TabbedShowLayout(_props: TabbedShowLayoutProps): null;
+export declare namespace TabbedShowLayout {
+    var Tab: typeof TabbedShowLayoutTab;
+}
+/** Everything a record view child resolves to. */
+interface RecordShape {
+    fields: UdsRecordField[];
+    groups?: UdsRecordGroup[];
+    layout?: 'tabs';
+    /** The `<ReferenceManyField>` panels written beside the form. */
+    panels: UdsRecordRelatedPanel[];
+}
+/**
+ * Reads a `<Show>`/`<Edit>`/`<Create>` element's view child into the fields,
+ * groups and layout they stand for.
+ *
+ * A `<SimpleForm>` yields fields and no groups. A `<TabbedShowLayout>` yields
+ * the concatenation of its tabs' fields — the flat array the shell renders —
+ * plus the `groups` that say which tab each one belongs to, plus the `tabs`
+ * layout that makes them tabs rather than stacked fieldsets.
+ */
+export declare function recordShapeFromView(viewChildren: ReactNode): RecordShape;
+/**
+ * Reads every `<Show>`/`<Edit>`/`<Create>` child of a `<Resource>` into the
+ * one `UdsAdminRecordConfig` the shell renders for all three modes.
+ *
+ * Returns `undefined` when the resource has none, so a list-only resource
+ * stays list-only rather than gaining an empty record config.
+ *
+ * @throws when the wrappers describe something one `fields`/`groups`/`layout`
+ * set cannot hold — see the module doc.
+ */
+export declare function recordConfigFromChildren(children: ReactNode): UdsAdminRecordConfig | undefined;
+export {};

package/dist/composition/record.js

@@ -0,0 +1,257 @@
+import { SimpleForm, fieldsFromChildren } from './simple-form';
+import { findReferenceManyFields, relatedPanelFrom } from './reference-many';
+import { reactChildrenToArray } from './children';
+/** Marker component for the show view. Never rendered — see the module doc. */
+export function Show(_props) {
+    return null;
+}
+/** Marker component for the edit view. Never rendered — see the module doc. */
+export function Edit(_props) {
+    return null;
+}
+/** Marker component for the create view. Never rendered — see the module doc. */
+export function Create(_props) {
+    return null;
+}
+/** Marker component for one tab. Never rendered — see the module doc. */
+export function TabbedShowLayoutTab(_props) {
+    return null;
+}
+/**
+ * Marker component for a tabbed record, read into `UdsRecordConfig.groups`
+ * plus `layout: 'tabs'`. Never rendered — see the module doc.
+ */
+export function TabbedShowLayout(_props) {
+    return null;
+}
+TabbedShowLayout.Tab = TabbedShowLayoutTab;
+/**
+ * Reads a `<Show>`/`<Edit>`/`<Create>` element's view child into the fields,
+ * groups and layout they stand for.
+ *
+ * A `<SimpleForm>` yields fields and no groups. A `<TabbedShowLayout>` yields
+ * the concatenation of its tabs' fields — the flat array the shell renders —
+ * plus the `groups` that say which tab each one belongs to, plus the `tabs`
+ * layout that makes them tabs rather than stacked fieldsets.
+ */
+export function recordShapeFromView(viewChildren) {
+    const children = reactChildrenToArray(viewChildren);
+    const panels = findReferenceManyFields(viewChildren).map(relatedPanelFrom);
+    const form = children.find((child) => isElementOfType(child, SimpleForm));
+    if (form) {
+        return { fields: fieldsFromChildren(form.props.children), panels };
+    }
+    const tabbed = children.find((child) => isElementOfType(child, TabbedShowLayout));
+    if (!tabbed) {
+        return { fields: [], panels };
+    }
+    const tabs = reactChildrenToArray(tabbed.props.children).filter((child) => isElementOfType(child, TabbedShowLayoutTab));
+    const fields = [];
+    const groups = tabs.map((tab) => {
+        const tabFields = fieldsFromChildren(tab.props.children);
+        fields.push(...tabFields);
+        return {
+            id: tab.props.path ?? slug(tab.props.label),
+            label: tab.props.label,
+            fields: tabFields.map((field) => field.field),
+        };
+    });
+    return { fields, groups, layout: 'tabs', panels };
+}
+/**
+ * Reads every `<Show>`/`<Edit>`/`<Create>` child of a `<Resource>` into the
+ * one `UdsAdminRecordConfig` the shell renders for all three modes.
+ *
+ * Returns `undefined` when the resource has none, so a list-only resource
+ * stays list-only rather than gaining an empty record config.
+ *
+ * @throws when the wrappers describe something one `fields`/`groups`/`layout`
+ * set cannot hold — see the module doc.
+ */
+export function recordConfigFromChildren(children) {
+    const views = reactChildrenToArray(children).filter((child) => isRecordViewElement(child));
+    if (!views.length) {
+        return undefined;
+    }
+    const read = views.map((view) => ({
+        name: nameOf(view),
+        mode: modeOf(view),
+        shape: recordShapeFromView(view.props.children),
+    }));
+    // Only wrappers that actually hold a form have a layout to disagree about.
+    // A `<Show>` carrying nothing but a `<ReferenceManyField>` is silent here,
+    // the same way it is silent about fields.
+    const withFields = read.filter(({ shape }) => shape.fields.length > 0);
+    const layouts = new Set(withFields.map(({ shape }) => shape.layout ?? 'flat'));
+    if (layouts.size > 1) {
+        throw divergent(read, 'use different layouts, and the shell has one layout for all three modes');
+    }
+    const fields = mergeFields(read);
+    const groups = mergeGroups(read);
+    const related = mergePanels(read);
+    const layout = withFields.find(({ shape }) => shape.layout)?.shape.layout;
+    return {
+        fields,
+        ...(groups ? { groups } : {}),
+        ...(layout ? { layout } : {}),
+        ...(related.length ? { related } : {}),
+    };
+}
+/**
+ * The one `fields` array every wrapper agrees with, with `modes` written on
+ * the entries that are not in all of them.
+ *
+ * A field is identified by its *whole definition*, not by its name, so the
+ * same field carrying a different label or input per mode is two gated
+ * entries rather than a conflict — the shell narrows by mode before anything
+ * reads them, so only one is ever live at a time.
+ *
+ * A field every declared mode has is left **ungated**, which is what makes
+ * this backward compatible: two identical wrappers produce exactly the config
+ * they produced before `modes` existed, and a mode no wrapper declares still
+ * renders the fields they all agree on rather than nothing at all.
+ */
+function mergeFields(read) {
+    const merged = mergeOrder(read.map(({ shape }) => shape.fields), (field) => JSON.stringify(field));
+    if (!merged) {
+        throw divergent(read, 'order the same fields differently, and the shell renders one ordered array');
+    }
+    const modes = new Set(read.map(({ mode }) => mode));
+    return merged.map((field) => {
+        const declaredIn = read
+            .filter(({ shape }) => shape.fields.some((candidate) => sameField(candidate, field)))
+            .map(({ mode }) => mode);
+        const distinct = [...new Set(declaredIn)];
+        return distinct.length === modes.size ? field : { ...field, modes: distinct };
+    });
+}
+/**
+ * The one `groups` array, merged the same way.
+ *
+ * A group's *fields* may legitimately differ between modes — that is the
+ * per-mode field set arriving inside a tab — so they are merged and the shell
+ * narrows each group to the fields the mode actually has, dropping a group
+ * left empty. A group's **label** may not differ: one tab strip is rendered
+ * for all three modes, and there is nowhere to put the second name.
+ */
+function mergeGroups(read) {
+    const lists = read.map(({ shape }) => shape.groups ?? []);
+    if (lists.every((groups) => groups.length === 0)) {
+        return undefined;
+    }
+    // Every wrapper that tabs its fields must name the *same* tabs: the shell
+    // renders one tab strip, so a tab present in one mode and renamed in
+    // another would quietly become a tab holding nothing.
+    const declared = lists.filter((groups) => groups.length > 0);
+    const ids = declared.map((groups) => [...groups.map((group) => group.id)].sort().join());
+    if (ids.some((set) => set !== ids[0])) {
+        throw divergent(read, 'name different tabs, and the shell renders one tab strip');
+    }
+    const merged = mergeOrder(lists, (group) => group.id);
+    if (!merged) {
+        throw divergent(read, 'order the same tabs differently, and the shell renders one tab strip');
+    }
+    return merged.map((group) => {
+        const declarations = lists.flat().filter((candidate) => candidate.id === group.id);
+        if (declarations.some((candidate) => candidate.label !== group.label)) {
+            throw divergent(read, `label the "${group.id}" tab differently, and the shell renders one tab strip`);
+        }
+        const fields = mergeOrder(declarations.map((candidate) => candidate.fields), (field) => field);
+        if (!fields) {
+            throw divergent(read, `order the "${group.id}" tab's fields differently`);
+        }
+        return { ...group, fields };
+    });
+}
+/**
+ * The related panels, taken from whichever wrappers declared any.
+ *
+ * A wrapper declaring none is silent rather than empty: panels under `<Show>`
+ * and not under `<Edit>` is the natural authoring, and reading the `<Edit>` as
+ * "there are no panels" would make it an error. Two wrappers that both declare
+ * panels and disagree is a real contradiction — `UdsRecordConfig.related` is
+ * one array for the whole record — and is rejected.
+ */
+function mergePanels(read) {
+    const declared = read.filter(({ shape }) => shape.panels.length > 0);
+    if (!declared.length) {
+        return [];
+    }
+    const [first, ...rest] = declared;
+    if (rest.some(({ shape }) => JSON.stringify(shape.panels) !== JSON.stringify(first.shape.panels))) {
+        throw divergent(read, 'declare different related panels, and the shell renders one set beneath the record');
+    }
+    return first.shape.panels;
+}
+/**
+ * Merge ordered lists into the one order every input agrees with, or
+ * `undefined` when they contradict each other.
+ *
+ * First appearance wins the position; a list whose own items then run
+ * backwards through that order is the contradiction. Cheap, and it catches
+ * the case a set comparison would miss.
+ */
+function mergeOrder(lists, keyOf) {
+    const merged = [];
+    const positions = new Map();
+    for (const list of lists) {
+        for (const item of list) {
+            const key = keyOf(item);
+            if (!positions.has(key)) {
+                positions.set(key, merged.length);
+                merged.push(item);
+            }
+        }
+    }
+    for (const list of lists) {
+        const seen = list.map((item) => positions.get(keyOf(item)));
+        for (let i = 1; i < seen.length; i += 1) {
+            if (seen[i] <= seen[i - 1]) {
+                return undefined;
+            }
+        }
+    }
+    return merged;
+}
+/** Two fields are the same field when their whole definitions match. */
+function sameField(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+/** The one error shape, naming the wrappers and what they asked for. */
+function divergent(read, problem) {
+    const names = read.map(({ name }) => `<${name}>`).join(' and ');
+    return new Error(`${names} ${problem}. A field set may differ per mode — write the differing fields under one ` +
+        'wrapper each and they are gated with `modes` — but this cannot be. See ' +
+        'docs/adr/0031-the-record-pattern-gains-modes-and-related-panels.md.');
+}
+/** `'Billing details'` → `'billing-details'`. */
+function slug(label) {
+    return label
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+const RECORD_VIEWS = new Map([
+    [Show, { name: 'Show', mode: 'show' }],
+    [Edit, { name: 'Edit', mode: 'edit' }],
+    [Create, { name: 'Create', mode: 'create' }],
+]);
+function isRecordViewElement(node) {
+    return (typeof node === 'object' &&
+        node !== null &&
+        'type' in node &&
+        RECORD_VIEWS.has(node.type));
+}
+/** The wrapper's tag name, for the error message. Only ever called on an element `isRecordViewElement` passed. */
+function nameOf(view) {
+    return RECORD_VIEWS.get(view.type).name;
+}
+/** The mode the wrapper stands for, which is what its fields are gated to. */
+function modeOf(view) {
+    return RECORD_VIEWS.get(view.type).mode;
+}
+/** A React element whose `type` is exactly this marker function. */
+function isElementOfType(node, type) {
+    return typeof node === 'object' && node !== null && 'type' in node && node.type === type;
+}

package/dist/composition/reference-many.d.ts

@@ -0,0 +1,86 @@
+import type { ReactElement, ReactNode } from 'react';
+import type { UdsAdminListConfig, UdsRecordId, UdsRecordRelatedPanel } from '@globalpayments-private/gpds-pattern-web';
+/**
+ * `ReferenceManyField`: the composition spelling of a related-records panel,
+ * mirroring real react-admin's
+ * https://marmelab.com/react-admin/ReferenceManyField.html:
+ *
+ * ```tsx
+ * <Show>
+ *   <SimpleForm>
+ *     <TextInput field="number" label="Invoice" />
+ *   </SimpleForm>
+ *   <ReferenceManyField reference="invoice-lines" target="invoiceId" label="Lines">
+ *     <DataTable>
+ *       <DataTable.Col field="sku" label="SKU" />
+ *     </DataTable>
+ *   </ReferenceManyField>
+ * </Show>
+ * ```
+ *
+ * Rows are read with `getManyReference` rather than `getList`, `target` names
+ * the field on the referenced resource holding the other record's id, and the
+ * child is a view — in react-admin almost always a `<DataTable>`, and that
+ * nesting is kept here. All three of this layer's view children work, since
+ * what they select is the layout and a related panel is a list like any other.
+ *
+ * ## Two placements, and `id` is what tells them apart
+ *
+ * **Inside a `<Show>`/`<Edit>`/`<Create>`** — react-admin's own spelling — the
+ * panel belongs to the record on screen and takes its id from it, so `id` is
+ * neither needed nor accepted. This resolves to `UdsRecordConfig.related`,
+ * which `gp-pattern-record` renders beneath the form.
+ *
+ * **As a child of `<Resource>`** the panel *is* the resource's view, with no
+ * record around it to take an id from, so `id` is required and explicit. This
+ * resolves to `UdsListConfig.related` exactly as it did before the
+ * record-level member existed, and is still how a panel is written when there
+ * is no record pattern on the page.
+ *
+ * Neither placement guesses: an `id` where one cannot be honoured, or a
+ * missing `id` where there is nothing to infer it from, is an error at read
+ * time rather than a panel quietly listing the wrong records — or, worse, all
+ * of them. See ADR 0031.
+ */
+export interface ReferenceManyFieldProps {
+    /** The resource holding the related records. */
+    reference: string;
+    /** The field on that resource holding this record's id. */
+    target: string;
+    /**
+     * This record's id. Required as a child of `<Resource>`, rejected inside a
+     * record view — see the module doc.
+     */
+    id?: UdsRecordId;
+    /** Heading rendered above the panel. Used by the record-level placement. */
+    label?: string;
+    /** The view child: `<DataTable>`, `<Board>` or `<CardGrid>`. */
+    children?: ReactNode;
+}
+/** Marker component for a related-records panel. Never rendered — see `list.tsx`'s module doc. */
+export declare function ReferenceManyField(_props: ReferenceManyFieldProps): null;
+/**
+ * Reads a `<ReferenceManyField>` element into the `UdsAdminListConfig` a
+ * related panel is: the view child's columns and layout, plus the `related`
+ * member that redirects the read to `getManyReference`.
+ *
+ * @throws when `id` is absent — there is no record context at `<Resource>`
+ * level to take one from, and a `related` without an id would read the whole
+ * resource unfiltered.
+ */
+export declare function relatedListConfigFrom(element: ReactElement<ReferenceManyFieldProps>): UdsAdminListConfig;
+/**
+ * Reads a `<ReferenceManyField>` written **inside a record view** into the
+ * `UdsRecordRelatedPanel` the pattern layer renders beneath the form.
+ *
+ * @throws when `id` is given — the panel's id is the record's, and honouring
+ * an explicit one would mean a panel under invoice 7 listing invoice 9's
+ * lines with nothing on screen saying so.
+ */
+export declare function relatedPanelFrom(element: ReactElement<ReferenceManyFieldProps>): UdsRecordRelatedPanel;
+/** Every `<ReferenceManyField>` among some children, in order. */
+export declare function findReferenceManyFields(children: ReactNode): ReactElement<ReferenceManyFieldProps>[];
+/** The resource a `<ReferenceManyField>` points at, which becomes the `<gp-resource name>`. */
+export declare function referenceOf(element: ReactElement<ReferenceManyFieldProps>): string;
+/** The first `<ReferenceManyField>` among some children, if any. */
+export declare function findReferenceManyField(children: ReactNode): ReactElement<ReferenceManyFieldProps> | undefined;

package/dist/composition/reference-many.js

@@ -0,0 +1,60 @@
+import { listConfigFromChildren } from './list';
+import { reactChildrenToArray } from './children';
+/** Marker component for a related-records panel. Never rendered — see `list.tsx`'s module doc. */
+export function ReferenceManyField(_props) {
+    return null;
+}
+/**
+ * Reads a `<ReferenceManyField>` element into the `UdsAdminListConfig` a
+ * related panel is: the view child's columns and layout, plus the `related`
+ * member that redirects the read to `getManyReference`.
+ *
+ * @throws when `id` is absent — there is no record context at `<Resource>`
+ * level to take one from, and a `related` without an id would read the whole
+ * resource unfiltered.
+ */
+export function relatedListConfigFrom(element) {
+    const { reference, target, id, children } = element.props;
+    if (id === undefined) {
+        throw new Error(`<ReferenceManyField reference="${reference}"> is a child of <Resource>, where there is no record ` +
+            'to take an id from, so `id` is required. Move it inside <Show> to have the id taken from the ' +
+            'record, or pass `id` explicitly. See docs/adr/0031-the-record-pattern-gains-modes-and-related-panels.md.');
+    }
+    return { ...listConfigFromChildren(children), related: { target, id } };
+}
+/**
+ * Reads a `<ReferenceManyField>` written **inside a record view** into the
+ * `UdsRecordRelatedPanel` the pattern layer renders beneath the form.
+ *
+ * @throws when `id` is given — the panel's id is the record's, and honouring
+ * an explicit one would mean a panel under invoice 7 listing invoice 9's
+ * lines with nothing on screen saying so.
+ */
+export function relatedPanelFrom(element) {
+    const { reference, target, id, label, children } = element.props;
+    if (id !== undefined) {
+        throw new Error(`<ReferenceManyField reference="${reference}"> is inside a record view, where its id is the ` +
+            "record's own, so `id` cannot be set. Remove it, or move the panel out to <Resource> level " +
+            'where an explicit id is what a panel has instead of a record. ' +
+            'See docs/adr/0031-the-record-pattern-gains-modes-and-related-panels.md.');
+    }
+    return { resource: reference, target, heading: label, list: listConfigFromChildren(children) };
+}
+/** Every `<ReferenceManyField>` among some children, in order. */
+export function findReferenceManyFields(children) {
+    return reactChildrenToArray(children).filter(isReferenceManyField);
+}
+/** The resource a `<ReferenceManyField>` points at, which becomes the `<gp-resource name>`. */
+export function referenceOf(element) {
+    return element.props.reference;
+}
+/** The first `<ReferenceManyField>` among some children, if any. */
+export function findReferenceManyField(children) {
+    return reactChildrenToArray(children).find(isReferenceManyField);
+}
+function isReferenceManyField(node) {
+    return (typeof node === 'object' &&
+        node !== null &&
+        'type' in node &&
+        node.type === ReferenceManyField);
+}

package/dist/composition/reference.d.ts

@@ -0,0 +1,13 @@
+import type { UdsReference } from '@globalpayments-private/gpds-pattern-web';
+/**
+ * The `{ resource: 'merchants' }` shorthand every column/field that can point
+ * at another resource accepts: a bare resource name, defaulting the
+ * referenced field to `'name'`, or the full `{ resource, field }` object
+ * passed straight through.
+ *
+ * Shared by `list.tsx` (`DataTable.Col`'s `reference`) and `simple-form.tsx`
+ * (`TextInput`/`ReferenceInput`'s `reference`) so both desugar the one
+ * shorthand identically — `UdsListColumn.reference` and
+ * `UdsRecordField.reference` are both typed `UdsReference | undefined`.
+ */
+export declare function resolveReference(reference: string | UdsReference | undefined): UdsReference | undefined;

package/dist/composition/reference.js

@@ -0,0 +1,17 @@
+/**
+ * The `{ resource: 'merchants' }` shorthand every column/field that can point
+ * at another resource accepts: a bare resource name, defaulting the
+ * referenced field to `'name'`, or the full `{ resource, field }` object
+ * passed straight through.
+ *
+ * Shared by `list.tsx` (`DataTable.Col`'s `reference`) and `simple-form.tsx`
+ * (`TextInput`/`ReferenceInput`'s `reference`) so both desugar the one
+ * shorthand identically — `UdsListColumn.reference` and
+ * `UdsRecordField.reference` are both typed `UdsReference | undefined`.
+ */
+export function resolveReference(reference) {
+    if (reference === undefined) {
+        return undefined;
+    }
+    return typeof reference === 'string' ? { resource: reference, field: 'name' } : reference;
+}