@captiveorigins/payload-plugin-onepedigree 0.0.0-stage → 0.1.0-alpha.11

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Captive Origins
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,89 @@
-# Temporary Holding Version
+# @captiveorigins/payload-plugin-onepedigree
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[OnePedigree](../../README.md) for Payload CMS 3: parentage on your own collection, cycle-safe
+writes, deletion policies, permission-aware pedigree endpoints for all 13 views, and Admin
+components (pedigree preview, relatives, color theme settings).
+
+```ts
+import { onePedigree } from '@captiveorigins/payload-plugin-onepedigree'
+
+export default buildConfig({
+  collections: [Animals, Clutches],
+  plugins: [
+    onePedigree({
+      collection: 'animals',
+      mode: 'standard-fields', // or 'managed' (creates the collections) or 'mapped' (your fields)
+      cohorts: { collection: 'clutches' },
+      hiddenRecords: 'placeholder', // a private relative shows as an anonymous "private record"
+      navigation: { individualUrl: '/animals/{id}' },
+    }),
+  ],
+})
+```
+
+## Modes
+
+- **`managed`**: creates `individuals`-style and cohort collections from the factories
+  (`createIndividualsCollection`, `createCohortsCollection`).
+- **`standard-fields`** (default): adds the `parentage` group (`parents[{ individual, role }]`,
+  `reproductiveMode`, `cohort`) to your existing collection.
+- **`mapped`**: uses your fields, e.g. `{ kind: 'role-fields', roles: { mother: 'dam', father: 'sire' }, cohort: 'clutch' }`
+  or `{ kind: 'parent-array', path: 'lineage', individualField: 'animal', roleField: 'role' }`.
+
+The plugin never creates collections for parents, roles, modes, graph edges or occurrences.
+
+## Parent labels
+
+Stored roles stay `mother` / `father`; only the words change. `terminology.parents` sets the
+default (`'mother-father'` (default), `'dam-sire'`, `'female-male-parent'`, or custom
+`{ maternal, paternal }`). Add `createParentTermsPreferenceField()` to your users collection
+and pass its path as `terminology.userPreference`: each user then sees their own choice in the
+Mother/Father pickers and in relatives.
+
+## Cohorts are birthing events
+
+A cohort is one birthing event (a clutch, a litter, twins): one mother, fathers may differ per
+member. With `cohorts.birthParentField` (the cohort's field naming the mother), a member whose
+recorded mother differs is refused, and so is changing the cohort's mother while members disagree.
+
+## Integrity
+
+On every write (Admin, REST, GraphQL, Local API, imports):
+
+- self-parents, duplicated parents and **cycles** are rejected with field-addressable errors;
+  the cycle check walks the full stored descendant line;
+- a parent the editor **cannot read** is rejected, with the same message as a missing one;
+- host `rules` (e.g. taxonomy) run on the proposed record;
+- parentage changes are **serialized**: each updates a graph-revision global in the same
+  transaction, so two concurrent edits that would together form a cycle cannot both commit
+  (requires a MongoDB replica set or another adapter with transactions). The revision also
+  serves as a cache key.
+
+Deleting a recorded parent is refused (`onReferencedIndividualDelete: 'restrict'`, default) or
+removes the references (`'detach'`).
+
+## Endpoints
+
+| Route | |
+|---|---|
+| `GET /api/<collection>/:id/pedigree?view=…` | Projection + layout; `ancestorDepth`, `descendantDepth`, `relatedId`, `cohortId`, `occurrenceMode`, `includeSiblings`, `orientation`, `maxNodes`, `layout=false` |
+| `GET /api/<collection>/:id/relatives` | Parents, offspring, siblings (full / partial / unresolved), cohort mates |
+| `POST /api/<collection>/:id/pedigree/validate` | Check `{ parents, reproductiveMode, cohort }` without saving (needs update access) |
+| `GET /api/<cohorts>/:id/members` | Members the requester may see |
+
+Every read runs as the requester (access control applies), is bounded by `limits`
+(`maxDepth`, `maxNodes`) and returns display projections, not documents. Records the requester
+cannot read are omitted or replaced by anonymous placeholders; their IDs, names and links never
+appear in responses. Add an index on the parent path (`parentage.parents.individual`, or your
+role fields) in production; the standard fields declare it.
+
+## Admin
+
+- A pedigree panel on the edit view: preview of the saved record in any view (pan, zoom,
+  selection), relatives, and structural notices.
+- A **Pedigree settings** global: color theme (seven presets, per-view accents, hex editing)
+  used by the preview; read it in your frontend to match.
+
+## License
+
+MIT

package/dist/client/ParentRoleLabel.d.ts

@@ -0,0 +1,8 @@
+import { type ParentTerms } from '@captiveorigins/onepedigree-core';
+/** Mother/Father picker label in the signed-in user's own terms (e.g. Dam/Sire), else the site default. */
+export declare function ParentRoleLabel({ side, defaultTerms, userPreference, path }: {
+    side: 'maternal' | 'paternal';
+    defaultTerms: ParentTerms;
+    userPreference: string | null;
+    path?: string;
+}): import("react").JSX.Element;

package/dist/client/ParentRoleLabel.js

@@ -0,0 +1,11 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { resolveParentTerms } from '@captiveorigins/onepedigree-core';
+import { FieldLabel, useAuth } from '@payloadcms/ui';
+const getAt = (doc, path) => path.split('.').reduce((o, k) => (o && typeof o === 'object' ? o[k] : undefined), doc);
+/** Mother/Father picker label in the signed-in user's own terms (e.g. Dam/Sire), else the site default. */
+export function ParentRoleLabel({ side, defaultTerms, userPreference, path }) {
+    const { user } = useAuth();
+    const terms = resolveParentTerms(userPreference && user ? getAt(user, userPreference) : undefined, defaultTerms);
+    return _jsx(FieldLabel, { label: terms[side], path: path });
+}

package/dist/client/PedigreePanel.d.ts

@@ -0,0 +1,13 @@
+import '@captiveorigins/onepedigree-react/styles.css';
+import type { PedigreeViewId } from '@captiveorigins/onepedigree-core';
+export type PedigreePanelProps = {
+    views: PedigreeViewId[];
+    defaultView: PedigreeViewId;
+    settingsGlobal: string | null;
+    terminology?: {
+        individual?: string;
+        individuals?: string;
+    };
+};
+/** Admin: pedigree preview of the saved record (any view), derived relatives and structural notices. */
+export declare function PedigreePanel(props: PedigreePanelProps): import("react").JSX.Element;

package/dist/client/PedigreePanel.js

@@ -0,0 +1,43 @@
+'use client';
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import '@captiveorigins/onepedigree-react/styles.css';
+import { PedigreeExplorer, VIEW_LABELS } from '@captiveorigins/onepedigree-react';
+import { useConfig, useDocumentInfo } from '@payloadcms/ui';
+import { useEffect, useState } from 'react';
+const name = (s) => ('private' in s ? 'Private record' : (s.label ?? s.id));
+const list = (items) => (items.length ? items.map(name).join(', ') : '—');
+/** Admin: pedigree preview of the saved record (any view), derived relatives and structural notices. */
+export function PedigreePanel(props) {
+    const { id, collectionSlug } = useDocumentInfo();
+    const { config } = useConfig();
+    const [view, setView] = useState(props.defaultView);
+    const [data, setData] = useState(null);
+    const [relatives, setRelatives] = useState(null);
+    const [theme, setTheme] = useState(undefined);
+    const api = `${config.serverURL ?? ''}${config.routes.api}`;
+    useEffect(() => {
+        if (!id || !collectionSlug)
+            return;
+        let live = true;
+        fetch(`${api}/${collectionSlug}/${id}/pedigree?view=${view}`, { credentials: 'include' })
+            .then((r) => (r.ok ? r.json() : null))
+            .then((j) => live && setData(j));
+        return () => {
+            live = false;
+        };
+    }, [api, collectionSlug, id, view]);
+    useEffect(() => {
+        if (!id || !collectionSlug)
+            return;
+        fetch(`${api}/${collectionSlug}/${id}/relatives`, { credentials: 'include' })
+            .then((r) => (r.ok ? r.json() : null))
+            .then(setRelatives);
+        if (props.settingsGlobal)
+            fetch(`${api}/globals/${props.settingsGlobal}`, { credentials: 'include' })
+                .then((r) => (r.ok ? r.json() : null))
+                .then((g) => g?.theme && setTheme(g.theme));
+    }, [api, collectionSlug, id, props.settingsGlobal]);
+    if (!id)
+        return _jsx("p", { className: "field-description", children: "Save this record to see its pedigree." });
+    return (_jsxs("div", { className: "onepedigree-panel", style: { marginBottom: 'var(--base, 20px)' }, children: [_jsx("label", { className: "field-label", htmlFor: "onepedigree-view", children: "Pedigree" }), _jsx("select", { id: "onepedigree-view", value: view, onChange: (e) => setView(e.target.value), children: props.views.map((v) => (_jsx("option", { value: v, children: VIEW_LABELS[v] }, v))) }), _jsx("p", { className: "field-description", children: "Shows the saved record; save to update." }), data ? _jsx(PedigreeExplorer, { projection: data.projection, layout: data.layout, height: "26rem", theme: theme, terminology: props.terminology }) : _jsx("p", { children: "Loading\u2026" }), data?.projection.issues.length ? (_jsx("ul", { className: "onepedigree-notices", children: data.projection.issues.map((i, n) => (_jsx("li", { children: i.message }, n))) })) : null, relatives && (_jsxs("dl", { className: "onepedigree-relatives", children: [_jsx("dt", { children: "Parents" }), _jsx("dd", { children: relatives.parents.length ? relatives.parents.map((p) => `${name(p.individual)} (${p.label})`).join(', ') : '—' }), _jsx("dt", { children: "Offspring" }), _jsx("dd", { children: list(relatives.children) }), _jsx("dt", { children: "Full siblings" }), _jsx("dd", { children: list(relatives.siblings.full) }), _jsx("dt", { children: "Partial siblings" }), _jsx("dd", { children: list(relatives.siblings.partial) }), relatives.siblings.unresolved.length > 0 && (_jsxs(_Fragment, { children: [_jsx("dt", { children: "Same recorded parents, incomplete" }), _jsx("dd", { children: list(relatives.siblings.unresolved) })] })), relatives.cohort && (_jsxs(_Fragment, { children: [_jsx("dt", { children: "Cohort mates" }), _jsx("dd", { children: list(relatives.cohort.mates) })] }))] }))] }));
+}

package/dist/client/ThemeField.d.ts

@@ -0,0 +1,5 @@
+import '@captiveorigins/onepedigree-react/styles.css';
+/** Admin: the color theme of pedigree views (preset + hex adjustments), stored as JSON. */
+export declare function ThemeField({ path }: {
+    path: string;
+}): import("react").JSX.Element;

package/dist/client/ThemeField.js

@@ -0,0 +1,13 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import '@captiveorigins/onepedigree-react/styles.css';
+import { ThemeEditor, THEME_PRESETS, VIEW_LABELS } from '@captiveorigins/onepedigree-react';
+import { useField } from '@payloadcms/ui';
+import { useState } from 'react';
+/** Admin: the color theme of pedigree views (preset + hex adjustments), stored as JSON. */
+export function ThemeField({ path }) {
+    const { value, setValue } = useField({ path });
+    const [view, setView] = useState('pedigree');
+    const theme = value && typeof value === 'object' && 'colors' in value ? value : structuredClone(THEME_PRESETS[0]);
+    return (_jsxs("div", { className: "field-type onepedigree-theme-field", style: { maxWidth: '24rem', marginBottom: 'var(--base, 20px)' }, children: [_jsx("label", { className: "field-label", htmlFor: "onepedigree-theme-view", children: "Preview colors for" }), _jsx("select", { id: "onepedigree-theme-view", value: view, onChange: (e) => setView(e.target.value), children: Object.keys(VIEW_LABELS).map((v) => (_jsx("option", { value: v, children: VIEW_LABELS[v] }, v))) }), _jsx(ThemeEditor, { value: theme, view: view, onChange: (t) => setValue(t) })] }));
+}

package/dist/client/index.d.ts

@@ -0,0 +1,3 @@
+export { PedigreePanel, type PedigreePanelProps } from './PedigreePanel.js';
+export { ThemeField } from './ThemeField.js';
+export { ParentRoleLabel } from './ParentRoleLabel.js';

package/dist/client/index.js

@@ -0,0 +1,4 @@
+'use client';
+export { PedigreePanel } from './PedigreePanel.js';
+export { ThemeField } from './ThemeField.js';
+export { ParentRoleLabel } from './ParentRoleLabel.js';

package/dist/collections.d.ts

@@ -0,0 +1,16 @@
+import type { CollectionConfig, Field } from 'payload';
+import { createParentageField } from './fields.js';
+type FactoryOptions = {
+    slug: string;
+    labels?: {
+        singular: string;
+        plural: string;
+    };
+    additionalFields?: Field[];
+    access?: CollectionConfig['access'];
+};
+/** A minimal individuals collection: name, optional external ID and sex label, parentage. */
+export declare const createIndividualsCollection: (o: FactoryOptions & Pick<Parameters<typeof createParentageField>[0], "cohorts" | "roles" | "selectors" | "terms" | "userPreference">) => CollectionConfig;
+/** A minimal cohorts collection: a label plus host fields. Members are derived from each individual's parentage. */
+export declare const createCohortsCollection: (o: FactoryOptions) => CollectionConfig;
+export {};

package/dist/collections.js

@@ -0,0 +1,25 @@
+import { createParentageField } from './fields.js';
+const signedIn = ({ req }) => Boolean(req.user);
+/** A minimal individuals collection: name, optional external ID and sex label, parentage. */
+export const createIndividualsCollection = (o) => ({
+    slug: o.slug,
+    labels: o.labels ?? { singular: 'Individual', plural: 'Individuals' },
+    admin: { useAsTitle: 'name', defaultColumns: ['name', 'sex', 'updatedAt'] },
+    access: o.access ?? { read: () => true, create: signedIn, update: signedIn, delete: signedIn },
+    fields: [
+        { name: 'name', type: 'text' },
+        { type: 'row', fields: [{ name: 'externalId', type: 'text', index: true }, { name: 'sex', type: 'text' }] },
+        createParentageField({ individuals: o.slug, cohorts: o.cohorts, roles: o.roles, selectors: o.selectors, terms: o.terms, userPreference: o.userPreference }),
+        ...(o.additionalFields ?? []),
+    ],
+    timestamps: true,
+});
+/** A minimal cohorts collection: a label plus host fields. Members are derived from each individual's parentage. */
+export const createCohortsCollection = (o) => ({
+    slug: o.slug,
+    labels: o.labels ?? { singular: 'Cohort', plural: 'Cohorts' },
+    admin: { useAsTitle: 'name' },
+    access: o.access ?? { read: () => true, create: signedIn, update: signedIn, delete: signedIn },
+    fields: [{ name: 'name', type: 'text' }, ...(o.additionalFields ?? [])],
+    timestamps: true,
+});

package/dist/endpoints.d.ts

@@ -0,0 +1,75 @@
+import { type Individual, type OccurrenceMode, type PedigreeIssue, type PedigreeRepository, type PedigreeViewId } from '@captiveorigins/onepedigree-core';
+import { type Endpoint, type PayloadRequest } from 'payload';
+import type { ResolvedOptions } from './types.js';
+type Doc = Record<string, unknown>;
+/** Reads as the requester (access control applies) unless `trusted`. */
+export declare function payloadRepository(req: PayloadRequest, opts: ResolvedOptions, trusted?: boolean): PedigreeRepository<Doc>;
+/**
+ * Removes every reference to a record the requester did not receive. With
+ * `placeholder`, requested-but-hidden parents become anonymous "private"
+ * individuals (fresh IDs per response, no name); otherwise they are omitted.
+ * Returns whether unloaded (not hidden) parents exist, i.e. the view is limited.
+ */
+export declare function redact(individuals: Individual[], hidden: ReadonlySet<string>, opts: ResolvedOptions): {
+    individuals: Individual[];
+    beyond: boolean;
+    hiddenSeen: boolean;
+};
+export type PedigreeQuery = Partial<Record<'view' | 'ancestorDepth' | 'descendantDepth' | 'maxNodes' | 'relatedId' | 'cohortId' | 'occurrenceMode' | 'includeSiblings' | 'orientation' | 'layout', string>>;
+/**
+ * A permission-filtered projection (and layout) of one view, read as the
+ * request's user. The endpoint uses it; host pages call it too (with a
+ * request from `createLocalReq`). Null when the focal record is not readable.
+ */
+export declare function getPedigree(req: PayloadRequest, opts: ResolvedOptions, id: string, query?: PedigreeQuery): Promise<{
+    schemaVersion: 1;
+    revision: number;
+    projection: {
+        issues: PedigreeIssue[];
+        truncated: boolean;
+        view: PedigreeViewId;
+        focalId: import("@captiveorigins/onepedigree-core").IndividualId;
+        occurrenceMode: OccurrenceMode;
+        occurrences: readonly import("@captiveorigins/onepedigree-core").IndividualOccurrence[];
+        edges: readonly import("@captiveorigins/onepedigree-core").ProjectedEdge[];
+        individuals: Readonly<Record<import("@captiveorigins/onepedigree-core").IndividualId, Individual>>;
+        structures: Readonly<Record<import("@captiveorigins/onepedigree-core").IndividualId, import("@captiveorigins/onepedigree-core").ReproductiveStructure>>;
+        groups: readonly import("@captiveorigins/onepedigree-core").ProjectionGroup[];
+    };
+    layout: import("@captiveorigins/onepedigree-core").LayoutResult | null;
+} | null>;
+/** GET /:id/pedigree?view=…: a permission-filtered projection (and layout) for one view. */
+export declare const pedigreeEndpoint: (opts: ResolvedOptions) => Endpoint;
+export type Summary = {
+    id: string;
+    label: string | null;
+    sex: string | null;
+    href: string | null;
+} | {
+    private: true;
+};
+/** Parents, offspring, siblings (full / partial / unresolved) and cohort mates the request's user may see. Null when not readable. */
+export declare function getRelatives(req: PayloadRequest, opts: ResolvedOptions, id: string): Promise<{
+    parents: {
+        role: import("@captiveorigins/onepedigree-core").ParentRole | null;
+        label: string;
+        individual: Summary;
+    }[];
+    children: Summary[];
+    siblings: {
+        full: Summary[];
+        partial: Summary[];
+        unresolved: Summary[];
+    };
+    cohort: {
+        id: string;
+        mates: Summary[];
+    } | null;
+} | null>;
+/** GET /:id/relatives */
+export declare const relativesEndpoint: (opts: ResolvedOptions) => Endpoint;
+/** POST /:id/pedigree/validate { parents, reproductiveMode, cohort }: check a proposed change without saving. */
+export declare const validateEndpoint: (opts: ResolvedOptions) => Endpoint;
+/** GET /api/<cohorts>/:id/members: members the requester may see (from each member's parentage). */
+export declare const cohortMembersEndpoint: (opts: ResolvedOptions) => Endpoint;
+export {};

package/dist/endpoints.js

@@ -0,0 +1,245 @@
+import { getSiblings, indexPedigree, layoutSync, loadNeighborhood, PEDIGREE_VIEWS, projectPedigree, roleLabel, } from '@captiveorigins/onepedigree-core';
+import { addDataAndFileToRequest, APIError } from 'payload';
+import { checkParentage } from './integrity.js';
+import { childrenWhere, documentAdapter, graphSelect, termsFor, toIndividual } from './mapping.js';
+/** Reads as the requester (access control applies) unless `trusted`. */
+export function payloadRepository(req, opts, trusted = false) {
+    const find = async (where) => (await req.payload.find({
+        collection: opts.collection,
+        where,
+        depth: 0,
+        limit: opts.limits.maxNodes,
+        pagination: false,
+        select: graphSelect(opts),
+        overrideAccess: trusted,
+        req,
+    })).docs;
+    return { getByIds: (ids) => find({ id: { in: [...ids] } }), findChildrenOf: (ids) => find(childrenWhere(opts, ids)) };
+}
+const int = (v, fallback, max) => {
+    const n = v === null ? fallback : Math.floor(Number(v));
+    return Number.isFinite(n) ? Math.max(0, Math.min(max, n)) : fallback;
+};
+const hrefFor = (opts, id) => opts.navigation?.individualUrl?.replace('{id}', encodeURIComponent(id)) ?? null;
+/**
+ * Removes every reference to a record the requester did not receive. With
+ * `placeholder`, requested-but-hidden parents become anonymous "private"
+ * individuals (fresh IDs per response, no name); otherwise they are omitted.
+ * Returns whether unloaded (not hidden) parents exist, i.e. the view is limited.
+ */
+export function redact(individuals, hidden, opts) {
+    const loaded = new Set(individuals.map((i) => i.id));
+    const placeholders = new Map();
+    let beyond = false;
+    let hiddenSeen = false;
+    const out = individuals.map((ind) => {
+        const parents = [];
+        for (const p of ind.parentage?.parents ?? []) {
+            if (loaded.has(p.individual))
+                parents.push(p);
+            else if (hidden.has(p.individual)) {
+                hiddenSeen = true;
+                if (opts.hiddenRecords === 'placeholder') {
+                    if (!placeholders.has(p.individual))
+                        placeholders.set(p.individual, `private-${placeholders.size + 1}`);
+                    parents.push({ individual: placeholders.get(p.individual), role: p.role ?? null });
+                }
+            }
+            else
+                beyond = true;
+        }
+        const data = { ...(ind.data ?? {}), href: hrefFor(opts, ind.id) };
+        return { ...ind, data, parentage: ind.parentage ? { ...ind.parentage, parents } : null };
+    });
+    for (const id of placeholders.values())
+        out.push({ id, label: null, sex: null, parentage: null, data: { private: true } });
+    return { individuals: out, beyond, hiddenSeen };
+}
+async function readable(req, collection, id) {
+    return req.payload.findByID({ collection: collection, id, depth: 0, overrideAccess: false, disableErrors: true, req });
+}
+async function canUpdate(req, opts, id) {
+    const access = req.payload.collections[opts.collection]?.config.access.update;
+    if (!access)
+        return Boolean(req.user);
+    const result = await access({ req, id, data: undefined });
+    if (result === true)
+        return true;
+    if (!result)
+        return false;
+    return (await req.payload.count({ collection: opts.collection, where: { and: [result, { id: { equals: id } }] }, overrideAccess: true, req })).totalDocs > 0;
+}
+const DOWN_VIEWS = new Set(['descendants', 'hourglass', 'population', 'timeline']);
+/**
+ * A permission-filtered projection (and layout) of one view, read as the
+ * request's user. The endpoint uses it; host pages call it too (with a
+ * request from `createLocalReq`). Null when the focal record is not readable.
+ */
+export async function getPedigree(req, opts, id, query = {}) {
+    if (!(await readable(req, opts.collection, id)))
+        return null;
+    const q = { get: (k) => query[k] ?? null };
+    const enabled = opts.views?.enabled ?? PEDIGREE_VIEWS;
+    const view = (q.get('view') ?? opts.views?.default ?? 'pedigree');
+    if (!enabled.includes(view))
+        throw new APIError('Unknown or disabled view.', 400);
+    const max = opts.limits.maxDepth;
+    const ancestorDepth = int(q.get('ancestorDepth'), 4, max);
+    const descendantDepth = int(q.get('descendantDepth'), 3, max);
+    const maxNodes = int(q.get('maxNodes'), opts.limits.maxNodes, opts.limits.maxNodes);
+    const relatedId = q.get('relatedId') && (await readable(req, opts.collection, q.get('relatedId'))) ? q.get('relatedId') : undefined;
+    const modeParam = q.get('occurrenceMode');
+    const occurrenceMode = modeParam === 'merge' || modeParam === 'separate' || modeParam === 'hybrid' ? modeParam : undefined;
+    const focalIds = [id, ...(relatedId ? [relatedId] : [])];
+    let cohortId;
+    if (view === 'cohort' && opts.cohorts) {
+        cohortId = q.get('cohortId') ?? undefined;
+        const self = (await readable(req, opts.collection, id));
+        cohortId ??= String(toIndividual(self, opts).parentage?.cohort ?? '') || undefined;
+        if (cohortId) {
+            const { docs } = await req.payload.find({
+                collection: opts.collection,
+                where: { [opts.fields.parentage.cohort]: { equals: cohortId } },
+                depth: 0,
+                limit: maxNodes,
+                pagination: false,
+                select: {},
+                overrideAccess: false,
+                req,
+            });
+            focalIds.push(...docs.map((d) => String(d.id)));
+        }
+    }
+    const both = view === 'population' || view === 'timeline';
+    const n = await loadNeighborhood(payloadRepository(req, opts), documentAdapter(opts), {
+        focalIds,
+        ancestorDepth: view === 'cohort' ? 1 : view === 'descendants' ? 0 : relatedId ? max : ancestorDepth,
+        descendantDepth: DOWN_VIEWS.has(view) ? descendantDepth : 0,
+        includeSiblings: both || q.get('includeSiblings') === 'true',
+        maxNodes,
+    });
+    const { individuals, beyond, hiddenSeen } = redact([...n.document.individuals], new Set(n.unavailable), opts);
+    // Names of the cohorts involved that the requester may read (for cohort markers).
+    const cohortIds = [...new Set(individuals.map((i) => i.parentage?.cohort).filter((c) => Boolean(c)))];
+    const cohorts = opts.cohorts && cohortIds.length
+        ? (await req.payload.find({
+            collection: opts.cohorts.collection,
+            where: { id: { in: cohortIds } },
+            depth: 0,
+            pagination: false,
+            overrideAccess: false,
+            req,
+        })).docs.map((c) => ({ id: String(c.id), label: typeof c[opts.cohorts.label] === 'string' ? c[opts.cohorts.label] : null }))
+        : [];
+    const document = { schemaVersion: 1, individuals, cohorts };
+    const projection = projectPedigree(document, {
+        focalId: id,
+        view,
+        ancestorDepth,
+        descendantDepth,
+        relatedId,
+        cohortId,
+        maxNodes,
+        includeSiblings: q.get('includeSiblings') === 'true',
+        includeCohortMembers: true,
+        lineageRoles: opts.lineageRoles,
+        ...(occurrenceMode ? { occurrenceMode } : {}),
+    });
+    const issues = [...projection.issues];
+    if (hiddenSeen)
+        issues.push({ severity: 'notice', code: 'HIDDEN_RECORD', message: 'Some related records are private and not shown.' });
+    const result = { ...projection, issues, truncated: projection.truncated || n.truncated || beyond };
+    const revision = (await req.payload.findGlobal({ slug: opts.graphGlobal, depth: 0, overrideAccess: true, req }))?.revision ?? 0;
+    const orientation = q.get('orientation') === 'horizontal' ? 'horizontal' : 'vertical';
+    return {
+        schemaVersion: 1,
+        revision,
+        projection: result,
+        layout: q.get('layout') === 'false' ? null : layoutSync(result, { orientation }),
+    };
+}
+/** GET /:id/pedigree?view=…: a permission-filtered projection (and layout) for one view. */
+export const pedigreeEndpoint = (opts) => ({
+    path: '/:id/pedigree',
+    method: 'get',
+    handler: async (req) => {
+        const params = new URL(req.url ?? 'http://local', 'http://local').searchParams;
+        const result = await getPedigree(req, opts, String(req.routeParams?.id), Object.fromEntries(params));
+        return result ? Response.json(result) : Response.json({ error: 'Not found' }, { status: 404 });
+    },
+});
+const summary = (ind, opts) => ({ id: ind.id, label: ind.label ?? null, sex: ind.sex ?? null, href: hrefFor(opts, ind.id) });
+/** Parents, offspring, siblings (full / partial / unresolved) and cohort mates the request's user may see. Null when not readable. */
+export async function getRelatives(req, opts, id) {
+    if (!(await readable(req, opts.collection, id)))
+        return null;
+    const n = await loadNeighborhood(payloadRepository(req, opts), documentAdapter(opts), { focalIds: [id], ancestorDepth: 1, descendantDepth: 1, includeSiblings: true, maxNodes: opts.limits.maxNodes });
+    const { individuals } = redact([...n.document.individuals], new Set(n.unavailable), opts);
+    const index = indexPedigree({ schemaVersion: 1, individuals });
+    const at = (x) => (index.individuals.get(x)?.data?.private ? { private: true } : summary(index.individuals.get(x), opts));
+    const self = index.individuals.get(id);
+    const s = getSiblings(index, id);
+    const cohort = self.parentage?.cohort;
+    const cohortMates = cohort ? [...(index.membersOf.get(cohort) ?? [])].filter((m) => m !== id) : [];
+    const terms = await termsFor(opts, req.user);
+    return {
+        parents: (self.parentage?.parents ?? []).map((p) => ({ role: p.role ?? null, label: roleLabel(p.role, terms, opts.lineageRoles), individual: at(p.individual) })),
+        children: [...(index.childrenOf.get(id) ?? [])].map(at),
+        siblings: { full: s.full.map(at), partial: s.partial.map(at), unresolved: s.unresolved.map(at) },
+        cohort: cohort ? { id: cohort, mates: cohortMates.map(at) } : null,
+    };
+}
+/** GET /:id/relatives */
+export const relativesEndpoint = (opts) => ({
+    path: '/:id/relatives',
+    method: 'get',
+    handler: async (req) => {
+        const result = await getRelatives(req, opts, String(req.routeParams?.id));
+        return result ? Response.json(result) : Response.json({ error: 'Not found' }, { status: 404 });
+    },
+});
+/** POST /:id/pedigree/validate { parents, reproductiveMode, cohort }: check a proposed change without saving. */
+export const validateEndpoint = (opts) => ({
+    path: '/:id/pedigree/validate',
+    method: 'post',
+    handler: async (req) => {
+        const id = String(req.routeParams?.id);
+        if (!(await readable(req, opts.collection, id)) || !(await canUpdate(req, opts, id)))
+            return Response.json({ error: 'Not found' }, { status: 404 });
+        await addDataAndFileToRequest(req);
+        const body = (req.data ?? {});
+        const parents = Array.isArray(body.parents)
+            ? body.parents.flatMap((p) => p && typeof p === 'object' && typeof p.individual === 'string'
+                ? [{ individual: p.individual, role: typeof p.role === 'string' ? p.role : null }]
+                : [])
+            : [];
+        const issues = await checkParentage(req, opts, {
+            id,
+            parents,
+            reproductiveMode: typeof body.reproductiveMode === 'string' ? body.reproductiveMode : null,
+            cohort: typeof body.cohort === 'string' ? body.cohort : null,
+        });
+        return Response.json({ valid: !issues.some((i) => i.severity === 'error'), issues });
+    },
+});
+/** GET /api/<cohorts>/:id/members: members the requester may see (from each member's parentage). */
+export const cohortMembersEndpoint = (opts) => ({
+    path: '/:id/members',
+    method: 'get',
+    handler: async (req) => {
+        const id = String(req.routeParams?.id);
+        if (!opts.cohorts || !(await readable(req, opts.cohorts.collection, id)))
+            return Response.json({ error: 'Not found' }, { status: 404 });
+        const { docs } = await req.payload.find({
+            collection: opts.collection,
+            where: { [opts.fields.parentage.cohort]: { equals: id } },
+            depth: 0,
+            limit: opts.limits.maxNodes,
+            pagination: false,
+            select: graphSelect(opts),
+            overrideAccess: false,
+            req,
+        });
+        return Response.json({ members: docs.map((d) => summary(toIndividual(d, opts), opts)) });
+    },
+});

package/dist/fields.d.ts

@@ -0,0 +1,41 @@
+import { type ParentTerms, type ParentTermsPreset, type ReproductiveModeId } from '@captiveorigins/onepedigree-core';
+import type { Field } from 'payload';
+/** The canonical parents array: any number of contributors, each with an optional role. */
+export declare const createParentsField: (o: {
+    individuals: string;
+    roles?: readonly string[];
+}) => Field;
+export declare const createReproductiveModeField: (o?: {
+    defaultValue?: ReproductiveModeId | null;
+}) => Field;
+export declare const createCohortField: (o: {
+    cohorts: string;
+}) => Field;
+/**
+ * A Mother/Father (or Dam/Sire) picker backed by the canonical parents array:
+ * shows the first parent with the role, and on save replaces the rows with
+ * that role when the picker changed. Not stored itself (virtual).
+ */
+export declare const createRoleSelectorField: (o: {
+    individuals: string;
+    side: "maternal" | "paternal";
+    terms?: ParentTermsPreset | ParentTerms;
+    userPreference?: string;
+}) => Field;
+/**
+ * A user's own words for the parent roles (add to your users collection and
+ * pass its path as `terminology.userPreference`). Display only.
+ */
+export declare const createParentTermsPreferenceField: (o?: {
+    name?: string;
+}) => Field;
+/** The standard `parentage` group (parents, reproductive mode, cohort), with Mother/Father pickers unless `selectors` is false. */
+export declare const createParentageField: (o: {
+    individuals: string;
+    cohorts?: string | null;
+    roles?: readonly string[];
+    defaultMode?: ReproductiveModeId | null;
+    selectors?: boolean;
+    terms?: ParentTermsPreset | ParentTerms;
+    userPreference?: string;
+}) => Field;