domma-cms 0.17.0 → 0.21.0

package/server/services/recipes/onboarding.json

@@ -0,0 +1,426 @@
+{
+  "slug": "onboarding",
+  "name": "Employee Onboarding",
+  "description": "Collects new-starter details and tracks them through a Pending \u2192 Reviewing \u2192 Approved/Rejected workflow. Includes a right-to-work file upload and HR review actions.",
+  "icon": "user-plus",
+  "roles": [
+    {
+      "name": "hr",
+      "label": "HR Reviewer",
+      "level": 2,
+      "permissions": [
+        "notifications"
+      ],
+      "badgeClass": "badge-info"
+    }
+  ],
+  "options": [
+    {
+      "name": "namespace",
+      "label": "Namespace",
+      "default": "onboarding",
+      "hint": "Single name that cascades into every slug below. Change this once and the collection, form, and actions all rename in lockstep — or override the individual slugs below to break the chain."
+    },
+    {
+      "name": "collectionSlug",
+      "label": "Collection slug",
+      "default": "{{namespace}}",
+      "hint": "Where submitted starter records are stored"
+    },
+    {
+      "name": "formSlug",
+      "label": "Form slug",
+      "default": "{{namespace}}-form",
+      "hint": "Embedded via [form name=\"...\" /]"
+    },
+    {
+      "name": "actionPrefix",
+      "label": "Action slug prefix",
+      "default": "{{namespace}}",
+      "hint": "Per-action slugs: <prefix>-review, <prefix>-approve, <prefix>-reject"
+    },
+    {
+      "name": "hrEmail",
+      "label": "HR email (optional)",
+      "default": "",
+      "hint": "If set, scaffolds an HR user account that can review and approve onboarding submissions. Leave blank to skip."
+    },
+    {
+      "name": "hrPassword",
+      "label": "HR initial password (optional)",
+      "default": "",
+      "hint": "Required when HR email is set. The HR user can change this immediately via their profile after first login."
+    }
+  ],
+  "collection": {
+    "title": "Onboarding",
+    "description": "New-starter onboarding submissions",
+    "fields": [
+      {
+        "name": "fullName",
+        "label": "Full name",
+        "type": "text",
+        "required": true
+      },
+      {
+        "name": "email",
+        "label": "Work email",
+        "type": "email",
+        "required": true
+      },
+      {
+        "name": "phone",
+        "label": "Phone number",
+        "type": "text"
+      },
+      {
+        "name": "startDate",
+        "label": "Start date",
+        "type": "date",
+        "required": true
+      },
+      {
+        "name": "role",
+        "label": "Role / position",
+        "type": "text",
+        "required": true
+      },
+      {
+        "name": "manager",
+        "label": "Manager",
+        "type": "text"
+      },
+      {
+        "name": "residencyStatus",
+        "label": "Right-to-work status",
+        "type": "multiselect",
+        "required": true,
+        "options": [
+          {
+            "value": "uk-national",
+            "label": "UK national"
+          },
+          {
+            "value": "settled-status",
+            "label": "Settled status"
+          },
+          {
+            "value": "visa-required",
+            "label": "Visa required"
+          },
+          {
+            "value": "other",
+            "label": "Other"
+          }
+        ]
+      },
+      {
+        "name": "rightToWorkDoc",
+        "label": "Right-to-work document",
+        "type": "file",
+        "required": false,
+        "file": {
+          "accept": "application/pdf,image/jpeg,image/png",
+          "maxSize": 5242880
+        }
+      },
+      {
+        "name": "references",
+        "label": "Reference contacts",
+        "type": "textarea",
+        "required": false,
+        "placeholder": "Name, email, relationship \u2014 one per line"
+      },
+      {
+        "name": "notes",
+        "label": "Notes for HR",
+        "type": "textarea"
+      },
+      {
+        "name": "status",
+        "label": "Status",
+        "type": "select",
+        "required": false,
+        "options": [
+          {
+            "value": "pending",
+            "label": "Pending review"
+          },
+          {
+            "value": "reviewing",
+            "label": "Reviewing"
+          },
+          {
+            "value": "approved",
+            "label": "Approved"
+          },
+          {
+            "value": "rejected",
+            "label": "Rejected"
+          }
+        ]
+      }
+    ],
+    "api": {
+      "read": {
+        "enabled": false
+      },
+      "create": {
+        "enabled": false
+      },
+      "update": {
+        "enabled": false
+      },
+      "delete": {
+        "enabled": false
+      }
+    },
+    "rowAccess": {
+      "update": {
+        "ownerField": "createdBy",
+        "fallbackRoles": [
+          "admin",
+          "super-admin"
+        ]
+      },
+      "delete": {
+        "ownerField": "createdBy",
+        "fallbackRoles": [
+          "admin",
+          "super-admin"
+        ]
+      }
+    }
+  },
+  "form": {
+    "title": "Employee Onboarding",
+    "description": "Welcome aboard \u2014 let's get you set up.",
+    "fields": [
+      {
+        "name": "fullName",
+        "label": "Full name",
+        "type": "text",
+        "required": true,
+        "placeholder": "Alex Morgan"
+      },
+      {
+        "name": "email",
+        "label": "Work email",
+        "type": "email",
+        "required": true,
+        "placeholder": "alex@company.com"
+      },
+      {
+        "name": "phone",
+        "label": "Phone number",
+        "type": "text",
+        "required": false
+      },
+      {
+        "name": "startDate",
+        "label": "Start date",
+        "type": "date",
+        "required": true
+      },
+      {
+        "name": "role",
+        "label": "Role you're starting",
+        "type": "text",
+        "required": true
+      },
+      {
+        "name": "manager",
+        "label": "Your manager",
+        "type": "text",
+        "required": false
+      },
+      {
+        "name": "residencyStatus",
+        "label": "Right-to-work status",
+        "type": "select",
+        "required": true,
+        "options": [
+          {
+            "value": "uk-national",
+            "label": "UK national"
+          },
+          {
+            "value": "settled-status",
+            "label": "Settled status"
+          },
+          {
+            "value": "visa-required",
+            "label": "Visa required"
+          },
+          {
+            "value": "other",
+            "label": "Other"
+          }
+        ]
+      },
+      {
+        "name": "rightToWorkDoc",
+        "label": "Right-to-work document",
+        "type": "file",
+        "required": true,
+        "file": {
+          "accept": "application/pdf,image/jpeg,image/png",
+          "maxSize": 5242880
+        },
+        "helper": "PDF, JPEG or PNG \u2014 up to 5 MB"
+      },
+      {
+        "name": "references",
+        "label": "Reference contacts",
+        "type": "textarea",
+        "required": false,
+        "placeholder": "Name, email, relationship \u2014 one per line"
+      }
+    ],
+    "settings": {
+      "submitText": "Send to HR",
+      "successMessage": "Thanks \u2014 HR will review your details shortly.",
+      "honeypot": true,
+      "rateLimitPerMinute": 3,
+      "actionSlug": ""
+    },
+    "actions": {
+      "collection": {
+        "enabled": true,
+        "slug": ""
+      },
+      "email": {
+        "enabled": false
+      },
+      "webhook": {
+        "enabled": false
+      }
+    }
+  },
+  "users": [
+    {
+      "email":           "{{hrEmail}}",
+      "name":            "HR Lead",
+      "password":        "{{hrPassword}}",
+      "role":            "hr",
+      "additionalRoles": []
+    }
+  ],
+  "actions": [
+    {
+      "slug": "{{actionPrefix}}-review",
+      "title": "Move to reviewing",
+      "description": "HR has picked this up and started checks.",
+      "collection": "{{collectionSlug}}",
+      "trigger": {
+        "label": "Mark as reviewing",
+        "icon": "eye",
+        "style": "primary"
+      },
+      "transition": {
+        "field": "status",
+        "from": [
+          "pending"
+        ],
+        "to": "reviewing"
+      },
+      "access": {
+        "roles": [
+          "hr",
+          "admin",
+          "super-admin"
+        ]
+      },
+      "steps": [
+        {
+          "type": "updateField",
+          "config": {
+            "field": "status",
+            "value": "reviewing"
+          }
+        }
+      ]
+    },
+    {
+      "slug": "{{actionPrefix}}-approve",
+      "title": "Approve",
+      "description": "Right-to-work and references checked; cleared to start.",
+      "collection": "{{collectionSlug}}",
+      "trigger": {
+        "label": "Approve",
+        "icon": "check-circle",
+        "style": "success",
+        "confirmMessage": "Mark this starter as approved?"
+      },
+      "transition": {
+        "field": "status",
+        "from": [
+          "reviewing"
+        ],
+        "to": "approved"
+      },
+      "access": {
+        "roles": [
+          "hr",
+          "admin",
+          "super-admin"
+        ]
+      },
+      "steps": [
+        {
+          "type": "updateField",
+          "config": {
+            "field": "status",
+            "value": "approved"
+          }
+        },
+        {
+          "type": "email",
+          "config": {
+            "to": "{{entry.data.email}}",
+            "subject": "Welcome \u2014 you're cleared to start",
+            "template": "Hi {{entry.data.fullName}},\n\nGreat news \u2014 your onboarding paperwork has been approved. Your first day is {{entry.data.startDate}}.\n\nIf you have any questions before then, just reply to this email.\n\nThe HR team"
+          }
+        }
+      ]
+    },
+    {
+      "slug": "{{actionPrefix}}-reject",
+      "title": "Reject",
+      "description": "Information missing or right-to-work check failed.",
+      "collection": "{{collectionSlug}}",
+      "trigger": {
+        "label": "Reject",
+        "icon": "x-circle",
+        "style": "danger",
+        "confirmMessage": "Reject this onboarding submission?"
+      },
+      "transition": {
+        "field": "status",
+        "from": [
+          "pending",
+          "reviewing"
+        ],
+        "to": "rejected"
+      },
+      "access": {
+        "roles": [
+          "hr",
+          "admin",
+          "super-admin"
+        ]
+      },
+      "steps": [
+        {
+          "type": "updateField",
+          "config": {
+            "field": "status",
+            "value": "rejected"
+          }
+        }
+      ]
+    }
+  ],
+  "wireForm": true,
+  "snippet": "[form name=\"{{formSlug}}\" /]\n\n## All onboarding submissions\n\n[collection slug=\"{{collectionSlug}}\" display=\"cards\" columns=\"2\" title-field=\"fullName\" searchable filterable=\"status,residencyStatus\" sortable transitions /]"
+}

package/server/services/references.js

@@ -0,0 +1,174 @@
+/**
+ * Reference resolver — turn raw foreign-key ids stored on entries into
+ * displayable values from the target collections.
+ *
+ * Reference field schema shape:
+ *   {
+ *     name:      "jobId",
+ *     label:     "Job",
+ *     type:      "reference",
+ *     reference: {
+ *       collection:    "jobs",        // target collection slug (required)
+ *       displayField:  "title",       // field on the target to show     (default: "title")
+ *       searchField:   "title",       // field to search on in picker UI (default: displayField)
+ *       linkTemplate:  "/jobs/{{id}}" // optional link template — `{{id}}` substituted
+ *     }
+ *   }
+ *
+ * Storage stays the same: `entry.data.jobId` is the target's id (or an array
+ * of ids for one-to-many references). The resolver attaches a parallel
+ * `entry._refs` map that callers can use to render labels without mutating
+ * the raw data shape.
+ *
+ * Batching: when resolving N entries that each have a `jobId`, we collect
+ * all distinct ids once, fetch the target collection in a single pass, then
+ * decorate every entry from the lookup map — one adapter call per *target
+ * collection* per resolve, not per entry.
+ *
+ * Missing-target handling: if a referenced id no longer exists (the target
+ * was deleted), the entry gets `_refs.<field> = { id, display: null, missing: true }`
+ * so callers can render a graceful "(deleted)" indicator instead of crashing.
+ */
+import {getAdapter} from './adapterRegistry.js';
+
+/**
+ * Extract the list of reference field definitions from a schema.
+ *
+ * @param {object} schema
+ * @returns {Array<{name:string, label:string, reference:object}>}
+ */
+export function referenceFields(schema) {
+    return (schema?.fields || []).filter(f => f.type === 'reference' && f.reference?.collection);
+}
+
+/**
+ * Resolve all reference fields on a batch of entries.
+ *
+ * Each entry is mutated in place to add `_refs`:
+ *   entry._refs = {
+ *     jobId: { id: 'abc', display: 'Senior Engineer', missing: false, link: '/jobs/abc' }
+ *   }
+ *
+ * For one-to-many (array) references the shape is:
+ *   entry._refs = {
+ *     skillIds: [{id, display, link, missing}, ...]
+ *   }
+ *
+ * Returns the entries (same reference) for chainable use.
+ *
+ * @param {object}      schema   - Source collection schema
+ * @param {object[]}    entries  - Source entries; each may be mutated
+ * @param {object}      [opts]
+ * @param {Function}    [opts.adapterResolver] - Optional async (slug) → adapter — for tests
+ * @returns {Promise<object[]>}
+ */
+export async function resolveReferences(schema, entries, opts = {}) {
+    if (!Array.isArray(entries) || !entries.length) return entries;
+
+    const refs = referenceFields(schema);
+    if (!refs.length) return entries;
+
+    const resolver = opts.adapterResolver || getAdapter;
+
+    // Group distinct ids per target collection so we make one adapter call
+    // per collection regardless of how many fields reference it.
+    /** @type {Map<string, Set<string>>} */
+    const idsByCollection = new Map();
+    for (const field of refs) {
+        const target = field.reference.collection;
+        if (!idsByCollection.has(target)) idsByCollection.set(target, new Set());
+        const bucket = idsByCollection.get(target);
+        for (const e of entries) {
+            const raw = e.data?.[field.name];
+            if (raw == null || raw === '') continue;
+            if (Array.isArray(raw)) raw.forEach(v => v != null && bucket.add(String(v)));
+            else bucket.add(String(raw));
+        }
+    }
+
+    // Fetch each target collection once, build a lookup map { collectionSlug → Map<id, entry> }
+    /** @type {Map<string, Map<string, object>>} */
+    const lookups = new Map();
+    for (const [collectionSlug, idSet] of idsByCollection) {
+        if (!idSet.size) { lookups.set(collectionSlug, new Map()); continue; }
+        try {
+            const adapter = await resolver(collectionSlug);
+            // FileAdapter: cheap to read all then filter; MongoAdapter: $in is the
+            // right call but we don't have a list-by-ids API yet. For now, get()
+            // each id in parallel — N requests but small N (distinct refs only).
+            const map = new Map();
+            await Promise.all([...idSet].map(async id => {
+                try {
+                    const target = await adapter.get(collectionSlug, id);
+                    if (target) map.set(id, target);
+                } catch { /* missing target — left out of the map */ }
+            }));
+            lookups.set(collectionSlug, map);
+        } catch {
+            lookups.set(collectionSlug, new Map());     // collection gone — all refs render as missing
+        }
+    }
+
+    // Decorate every entry with resolved _refs
+    for (const entry of entries) {
+        entry._refs = entry._refs || {};
+        for (const field of refs) {
+            const raw = entry.data?.[field.name];
+            if (raw == null || raw === '') continue;
+            const map = lookups.get(field.reference.collection) || new Map();
+            if (Array.isArray(raw)) {
+                entry._refs[field.name] = raw.filter(v => v != null).map(id => buildRef(field, String(id), map));
+            } else {
+                entry._refs[field.name] = buildRef(field, String(raw), map);
+            }
+        }
+    }
+
+    return entries;
+}
+
+/**
+ * Build a single resolved-ref record for an id.
+ *
+ * @param {object} field
+ * @param {string} id
+ * @param {Map<string, object>} lookupMap
+ * @returns {{id:string, display:string|null, missing:boolean, link:string|null}}
+ */
+function buildRef(field, id, lookupMap) {
+    const target = lookupMap.get(id);
+    if (!target) {
+        return { id, display: null, missing: true, link: null };
+    }
+    const displayField = field.reference.displayField || 'title';
+    const raw = target.data?.[displayField];
+    const display = (raw == null || raw === '') ? id : String(raw);
+    let link = null;
+    if (field.reference.linkTemplate) {
+        link = String(field.reference.linkTemplate).replace(/\{\{\s*id\s*\}\}/g, encodeURIComponent(id));
+    }
+    return { id, display, missing: false, link };
+}
+
+/**
+ * Convenience helper for renderers — get the display label for a reference
+ * field on a single entry, falling back to the raw value when no resolution
+ * was performed (e.g. a caller skipped `resolveRefs: true`).
+ *
+ * Handles arrays by joining with ", ".
+ *
+ * @param {object} entry
+ * @param {string} fieldName
+ * @returns {string}
+ */
+export function refDisplay(entry, fieldName) {
+    const r = entry?._refs?.[fieldName];
+    if (r == null) {
+        const raw = entry?.data?.[fieldName];
+        return raw == null ? '' : (Array.isArray(raw) ? raw.join(', ') : String(raw));
+    }
+    if (Array.isArray(r)) {
+        return r.map(x => x.missing ? `${x.id} (missing)` : x.display).join(', ');
+    }
+    return r.missing ? `${r.id} (missing)` : r.display;
+}