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

package/dist/plugin.js

@@ -0,0 +1,135 @@
+import { PEDIGREE_VIEWS } from '@captiveorigins/onepedigree-core';
+import { createCohortsCollection, createIndividualsCollection } from './collections.js';
+import { cohortMembersEndpoint, pedigreeEndpoint, relativesEndpoint, validateEndpoint } from './endpoints.js';
+import { createParentageField } from './fields.js';
+import { cohortBirthParentBeforeChange, parentageBeforeChange, parentBeforeDelete, rememberAccessMode } from './integrity.js';
+import { resolveOptions } from './mapping.js';
+const CLIENT = '@captiveorigins/payload-plugin-onepedigree/client';
+const panelField = (opts) => ({
+    name: 'pedigreePanel',
+    type: 'ui',
+    admin: {
+        components: {
+            Field: {
+                path: `${CLIENT}#PedigreePanel`,
+                clientProps: {
+                    views: opts.views?.enabled ?? PEDIGREE_VIEWS,
+                    defaultView: opts.views?.default ?? 'pedigree',
+                    settingsGlobal: opts.admin?.settings === false ? null : opts.settingsGlobal,
+                    terminology: opts.terminology ?? {},
+                },
+            },
+        },
+    },
+});
+const graphGlobal = (opts) => ({
+    slug: opts.graphGlobal,
+    admin: { hidden: true },
+    // Internal: written in the same transaction as each parentage change (serialization and cache revision).
+    access: { read: () => false, update: () => false },
+    fields: [{ name: 'revision', type: 'number', defaultValue: 0 }],
+});
+const settingsGlobal = (opts) => ({
+    slug: opts.settingsGlobal,
+    label: 'Pedigree settings',
+    access: { read: () => true, update: opts.admin?.settingsAccess ?? (({ req }) => Boolean(req.user)) },
+    fields: [
+        {
+            name: 'theme',
+            type: 'json',
+            admin: {
+                description: 'Colors of pedigree views: choose a preset and adjust any color with a hex code.',
+                components: { Field: `${CLIENT}#ThemeField` },
+            },
+        },
+        {
+            name: 'defaultView',
+            type: 'select',
+            defaultValue: opts.views?.default ?? 'pedigree',
+            options: (opts.views?.enabled ?? PEDIGREE_VIEWS).map((v) => ({ label: v[0].toUpperCase() + v.slice(1), value: v })),
+        },
+    ],
+});
+/**
+ * OnePedigree for Payload. Maps (or creates) an individuals collection,
+ * validates parentage on every write, serializes parentage changes, applies
+ * the deletion policy, and adds permission-aware pedigree endpoints and Admin
+ * components. Never creates collections for parents, roles, modes, edges or
+ * occurrences.
+ */
+export const onePedigree = (options) => (config) => {
+    const opts = resolveOptions(options);
+    let collections = [...(config.collections ?? [])];
+    if (opts.mode === 'managed') {
+        if (opts.cohorts?.managed && !collections.some((c) => c.slug === opts.cohorts.collection))
+            collections.push((options.overrides?.cohorts ?? ((c) => c))(createCohortsCollection({ slug: opts.cohorts.collection })));
+        if (!collections.some((c) => c.slug === opts.collection))
+            collections.push((options.overrides?.individuals ?? ((c) => c))(createIndividualsCollection({ slug: opts.collection, cohorts: opts.cohorts?.collection ?? null, roles: opts.roles, selectors: opts.selectors, terms: opts.terminology?.parents, userPreference: opts.terminology?.userPreference })));
+    }
+    if (!collections.some((c) => c.slug === opts.collection))
+        throw new Error(`OnePedigree: collection "${opts.collection}" not found`);
+    collections = collections.map((c) => {
+        if (c.slug === opts.collection) {
+            const inject = opts.mode === 'standard-fields' && !c.fields.some((f) => 'name' in f && f.name === 'parentage')
+                ? [(options.overrides?.parentageField ?? ((f) => f))(createParentageField({
+                        individuals: opts.collection,
+                        cohorts: opts.cohorts?.collection,
+                        roles: opts.roles,
+                        defaultMode: opts.reproductiveModes?.default,
+                        selectors: opts.selectors,
+                        terms: opts.terminology?.parents,
+                        userPreference: opts.terminology?.userPreference,
+                    }))]
+                : [];
+            if (opts.disabled)
+                return { ...c, fields: [...c.fields, ...inject] };
+            return {
+                ...c,
+                fields: [...c.fields, ...inject, ...(opts.admin?.panel === false ? [] : [panelField(opts)])],
+                hooks: {
+                    ...c.hooks,
+                    beforeOperation: [...(c.hooks?.beforeOperation ?? []), rememberAccessMode],
+                    beforeChange: [...(c.hooks?.beforeChange ?? []), parentageBeforeChange(opts)],
+                    beforeDelete: [...(c.hooks?.beforeDelete ?? []), parentBeforeDelete(opts)],
+                },
+                endpoints: [...(Array.isArray(c.endpoints) ? c.endpoints : []), pedigreeEndpoint(opts), relativesEndpoint(opts), validateEndpoint(opts)],
+            };
+        }
+        if (opts.cohorts && c.slug === opts.cohorts.collection && !opts.disabled)
+            return {
+                ...c,
+                endpoints: [...(Array.isArray(c.endpoints) ? c.endpoints : []), cohortMembersEndpoint(opts)],
+                hooks: { ...c.hooks, beforeChange: [...(c.hooks?.beforeChange ?? []), cohortBirthParentBeforeChange(opts)] },
+            };
+        return c;
+    });
+    const globals = [...(config.globals ?? [])];
+    if (!opts.disabled) {
+        globals.push(graphGlobal(opts));
+        if (opts.admin?.settings !== false && !globals.some((g) => g.slug === opts.settingsGlobal))
+            globals.push(settingsGlobal(opts));
+    }
+    // The graph revision document must exist before the first parentage write: two transactions
+    // that each create it would not conflict, so concurrent writes could both commit.
+    const onInit = async (payload) => {
+        await config.onInit?.(payload);
+        if (opts.disabled)
+            return;
+        // Retried: on a fresh database this can race other startup writes creating the same
+        // MongoDB collection (a transient transaction error). Startup is never blocked by it.
+        for (let attempt = 1; attempt <= 5; attempt++)
+            try {
+                const current = (await payload.findGlobal({ slug: opts.graphGlobal, depth: 0, overrideAccess: true }));
+                if (!current?.createdAt)
+                    await payload.updateGlobal({ slug: opts.graphGlobal, data: { revision: current?.revision ?? 0 }, overrideAccess: true, context: { onepedigreeInternal: true } });
+                return;
+            }
+            catch (error) {
+                if (attempt === 5)
+                    payload.logger.error({ err: error }, 'OnePedigree: could not create the pedigree graph revision document; it is created on the next start');
+                else
+                    await new Promise((r) => setTimeout(r, 200 * attempt));
+            }
+    };
+    return { ...config, collections, globals, onInit, custom: { ...config.custom, onepedigree: opts } };
+};

package/dist/types.d.ts

@@ -0,0 +1,130 @@
+import type { LineageRoleConfig, ParentTerms, ParentTermsPreset, PedigreeViewId, ReproductiveModeId, ValidationRule } from '@captiveorigins/onepedigree-core';
+import type { Access, CollectionConfig, Field } from 'payload';
+/** How parentage is stored on the host collection. */
+export type ParentageMapping = {
+    /** `parents[{ individual, role }]`, `reproductiveMode`, `cohort` in a group (default path `parentage`). */
+    kind: 'parent-array';
+    path?: string;
+    /** Names inside each parent row (defaults: `individual`, `role`). */
+    individualField?: string;
+    roleField?: string;
+    reproductiveMode?: string;
+    cohort?: string;
+} | {
+    /** One relationship field per role, e.g. `{ mother: 'dam', father: 'sire' }`. */
+    kind: 'role-fields';
+    roles: Record<string, string>;
+    reproductiveMode?: string;
+    cohort?: string;
+};
+export type OnePedigreePluginOptions = {
+    /** Collection holding individuals (e.g. `animals`). */
+    collection: string;
+    /**
+     * `managed`: the plugin creates the collection (and cohorts) with standard fields.
+     * `standard-fields`: inject the standard parentage group into your existing collection.
+     * `mapped`: use your existing fields as described by `fields.parentage`.
+     * Default `standard-fields`.
+     */
+    mode?: 'managed' | 'standard-fields' | 'mapped';
+    fields?: {
+        /** Display label field (default `name`, falling back to the ID). */
+        label?: string;
+        sex?: string;
+        parentage?: ParentageMapping;
+        /** Extra fields copied into projections as display data (explicitly approved; never everything). */
+        display?: readonly string[];
+    };
+    /**
+     * Cohort collection: birthing events (a clutch, a litter, twins). `managed: true` creates it.
+     * `birthParentField`: the cohort's field naming the birthing parent; members whose recorded
+     * mother (maternal role) differs are refused. Fathers may differ per member. False: no cohorts.
+     */
+    cohorts?: {
+        collection: string;
+        label?: string;
+        managed?: boolean;
+        birthParentField?: string;
+    } | false;
+    reproductiveModes?: {
+        default?: ReproductiveModeId | null;
+    };
+    /** Mother/Father pickers above the parents list (standard fields; labels from `terminology.parents`). False hides them. */
+    selectors?: boolean;
+    /** Role options in the parent editor (extend the built-ins). */
+    roles?: readonly string[];
+    lineageRoles?: LineageRoleConfig;
+    navigation?: {
+        individualUrl?: string;
+        cohortUrl?: string;
+    };
+    views?: {
+        enabled?: readonly PedigreeViewId[];
+        default?: PedigreeViewId;
+    };
+    /** Bounds for public traversal (requests are clamped to them). */
+    limits?: {
+        maxDepth?: number;
+        maxNodes?: number;
+    };
+    /**
+     * A related record the requester cannot read: `omit` (default) leaves it out;
+     * `placeholder` shows an anonymous "private record" without its ID or name.
+     */
+    hiddenRecords?: 'omit' | 'placeholder';
+    /** Deleting an individual that is someone's parent: refuse (default) or remove the references. */
+    onReferencedIndividualDelete?: 'restrict' | 'detach';
+    /** Host biological rules (e.g. taxonomy). Errors block the write. */
+    rules?: readonly ValidationRule[];
+    /** Labels only; stored keys never change. */
+    terminology?: {
+        individual?: string;
+        individuals?: string;
+        cohort?: string;
+        cohorts?: string;
+        /** Default words for the parent roles: a preset ('mother-father', 'dam-sire', 'female-male-parent') or custom. Default Mother/Father. */
+        parents?: ParentTermsPreset | ParentTerms;
+        /** Path on the signed-in user's document holding their own choice (see `createParentTermsPreferenceField`). */
+        userPreference?: string;
+    };
+    admin?: {
+        /** Pedigree preview, relatives and notices on the individual's edit view (default true). */
+        panel?: boolean;
+        /** A "Pedigree settings" global with the color theme editor (default true). */
+        settings?: boolean;
+        /** Who may change the settings (default: any signed-in user; restrict this in apps with member accounts). */
+        settingsAccess?: Access;
+    };
+    /** Access, fields or hooks to add to collections the plugin creates (managed mode). */
+    overrides?: {
+        individuals?: (c: CollectionConfig) => CollectionConfig;
+        cohorts?: (c: CollectionConfig) => CollectionConfig;
+        parentageField?: (f: Field) => Field;
+    };
+    /** Turn off everything but the fields (e.g. for migrations). */
+    disabled?: boolean;
+};
+export type ResolvedOptions = Required<Pick<OnePedigreePluginOptions, 'collection' | 'mode' | 'hiddenRecords' | 'onReferencedIndividualDelete'>> & Omit<OnePedigreePluginOptions, 'fields' | 'cohorts' | 'limits'> & {
+    fields: {
+        label: string;
+        sex: string | null;
+        parentage: Required<Extract<ParentageMapping, {
+            kind: 'parent-array';
+        }>> | Extract<ParentageMapping, {
+            kind: 'role-fields';
+        }>;
+        display: readonly string[];
+    };
+    cohorts: {
+        collection: string;
+        label: string;
+        managed: boolean;
+        birthParentField: string | null;
+    } | null;
+    limits: {
+        maxDepth: number;
+        maxNodes: number;
+    };
+    graphGlobal: string;
+    settingsGlobal: string;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "@captiveorigins/payload-plugin-onepedigree",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0-alpha.4",
+  "description": "OnePedigree for Payload CMS: parentage fields for existing or managed collections, cycle-safe serialized parentage writes, deletion policies, permission-aware pedigree endpoints for all 13 views, and Admin preview, relatives and color settings.",
+  "keywords": [
+    "payload",
+    "payload-plugin",
+    "payloadcms",
+    "pedigree",
+    "genealogy",
+    "breeding"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mgilardi/onepedigree.git",
+    "directory": "packages/payload"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "import": "./dist/client/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@captiveorigins/onepedigree-core": "^0.1.0-alpha.4",
+    "@captiveorigins/onepedigree-react": "^0.1.0-alpha.4"
+  },
+  "peerDependencies": {
+    "@payloadcms/ui": "^3.80.0",
+    "payload": "^3.80.0",
+    "react": ">=19"
+  },
+  "peerDependenciesMeta": {
+    "@payloadcms/ui": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@payloadcms/db-mongodb": "3.92.1",
+    "@payloadcms/ui": "^3.92.1",
+    "@types/react": "^19.3.0",
+    "graphql": "^16.14.2",
+    "mongodb-memory-server": "^11.3.0",
+    "payload": "^3.92.1",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
 }