@nitrogenbuilder/connector-payload 1.1.0 → 1.2.0

package/dist/inventory/indexing.js

@@ -10,50 +10,41 @@ function moduleNameFromNode(node) {
     }
     return null;
 }
-function collectUsageFromTree(modules, pathPrefix, results, parentContext, depth = 0) {
+function collectUsageFromTree(modules, pathPrefix, results) {
     if (!Array.isArray(modules))
         return;
     modules.forEach((maybeNode, index) => {
         if (!maybeNode || typeof maybeNode !== 'object')
             return;
         const node = maybeNode;
-        const modulePath = `${pathPrefix}[${index}]`;
         const componentName = moduleNameFromNode(node);
+        // The tree path is no longer stored, but it is still the identity of last
+        // resort for a node that carries no id of its own. Such a node reverts to
+        // the old positional behaviour and churns when the tree is reordered.
+        const modulePath = `${pathPrefix}[${index}]`;
         const moduleId = typeof node.id === 'string' || typeof node.id === 'number'
             ? String(node.id)
             : modulePath;
-        const currentContext = componentName
-            ? {
-                componentName,
-                moduleId,
-                modulePath,
-            }
-            : parentContext;
         if (componentName) {
             results.push({
                 componentName,
-                depth,
                 moduleId,
-                modulePath,
-                parentComponentName: parentContext?.componentName,
-                parentModuleId: parentContext?.moduleId,
-                parentModulePath: parentContext?.modulePath,
             });
         }
         const props = node.props;
         if (props && typeof props === 'object') {
             const children = props.children;
             if (Array.isArray(children)) {
-                collectUsageFromTree(children, `${modulePath}.props.children`, results, currentContext, depth + 1);
+                collectUsageFromTree(children, `${modulePath}.props.children`, results);
             }
             else if (children && typeof children === 'object') {
                 for (const [slotName, slotChildren] of Object.entries(children)) {
-                    collectUsageFromTree(slotChildren, `${modulePath}.props.children.${slotName}`, results, currentContext, depth + 1);
+                    collectUsageFromTree(slotChildren, `${modulePath}.props.children.${slotName}`, results);
                 }
             }
         }
         if (Array.isArray(node.children)) {
-            collectUsageFromTree(node.children, `${modulePath}.children`, results, currentContext, depth + 1);
+            collectUsageFromTree(node.children, `${modulePath}.children`, results);
         }
     });
 }
@@ -71,6 +62,7 @@ export async function findAllDocs(payload, collection, options, req) {
             collection: collection,
             depth: 0,
             limit: options?.limit ?? 200,
+            locale: options?.locale,
             page,
             overrideAccess: true,
             pagination: true,
@@ -84,62 +76,77 @@ export async function findAllDocs(payload, collection, options, req) {
     }
     return docs;
 }
-async function deleteUsageDocs(payload, docs, req) {
-    for (const doc of docs) {
-        await payload.delete({
-            collection: NITROGEN_COMPONENT_USAGE_COLLECTION,
-            id: doc.id,
-            overrideAccess: true,
-            req,
-        });
-    }
+/**
+ * Delete usage rows in one bulk statement rather than paginating the ids and
+ * issuing a `payload.delete` per row. Usage is rebuilt wholesale on every save,
+ * so a document with N modules previously cost N deletes (plus the finds to
+ * discover them) on the critical path of the save transaction.
+ */
+async function deleteUsageDocsWhere(payload, where, req) {
+    await payload.delete({
+        collection: NITROGEN_COMPONENT_USAGE_COLLECTION,
+        overrideAccess: true,
+        req,
+        where,
+    });
 }
-async function findUsageDocsForSource(payload, sourceCollection, sourceDocumentId, req) {
-    return findAllDocs(payload, NITROGEN_COMPONENT_USAGE_COLLECTION, {
-        limit: 100,
-        select: {
-            id: true,
-        },
-        where: {
-            and: [
-                {
-                    sourceCollection: {
-                        equals: sourceCollection,
-                    },
+function usageDocsForSourceWhere(sourceCollection, sourceDocumentId) {
+    return {
+        and: [
+            {
+                sourceCollection: {
+                    equals: sourceCollection,
                 },
-                {
-                    sourceDocumentId: {
-                        equals: sourceDocumentId,
-                    },
+            },
+            {
+                sourceDocumentId: {
+                    equals: sourceDocumentId,
                 },
-            ],
-        },
-    }, req);
+            },
+        ],
+    };
+}
+function usageKeyFor(sourceCollection, sourceDocumentId, record) {
+    return `${sourceCollection}:${sourceDocumentId}:${record.moduleId}:${record.componentName}`;
+}
+function usageSourceFields(doc) {
+    return {
+        sourceTitle: doc.title || '',
+        sourceSlug: doc.slug || '',
+        sourceStatus: doc.status || doc._status || '',
+    };
+}
+/**
+ * `componentName`, `moduleId`, `sourceCollection` and `sourceDocumentId` are all
+ * encoded in the usage key, so a key match already implies they agree; the
+ * source fields are reconciled separately by a single bulk update. That leaves
+ * only `sourceType`, which is checked defensively so a row written with the
+ * wrong value can still heal.
+ */
+function usageRowIsCurrent(row, sourceType) {
+    return row.sourceType === sourceType;
+}
+function usageRowData(sourceCollection, sourceType, sourceDocumentId, sourceFields, record) {
+    return {
+        usageKey: usageKeyFor(sourceCollection, sourceDocumentId, record),
+        componentName: record.componentName,
+        sourceCollection,
+        sourceType,
+        sourceDocumentId,
+        ...sourceFields,
+        moduleId: record.moduleId,
+    };
 }
 async function createUsageDocs(payload, sourceCollection, sourceType, doc, req) {
     const sourceDocumentId = String(doc.id);
+    const sourceFields = usageSourceFields(doc);
     const usageRecords = extractComponentUsageRecords(doc.nitrogenData);
     for (const record of usageRecords) {
         await payload.create({
             collection: NITROGEN_COMPONENT_USAGE_COLLECTION,
             overrideAccess: true,
             req,
-            data: {
-                usageKey: `${sourceCollection}:${sourceDocumentId}:${record.moduleId}:${record.modulePath}:${record.componentName}`,
-                componentName: record.componentName,
-                depth: record.depth,
-                sourceCollection,
-                sourceType,
-                sourceDocumentId,
-                sourceTitle: doc.title || '',
-                sourceSlug: doc.slug || '',
-                sourceStatus: doc.status || doc._status || '',
-                moduleId: record.moduleId,
-                modulePath: record.modulePath,
-                parentComponentName: record.parentComponentName || '',
-                parentModuleId: record.parentModuleId || '',
-                parentModulePath: record.parentModulePath || '',
-            },
+            data: usageRowData(sourceCollection, sourceType, sourceDocumentId, sourceFields, record),
         });
     }
     return usageRecords.length;
@@ -193,23 +200,72 @@ export async function syncComponentCatalog(payload, manifestInput, req) {
 }
 export async function reindexDocumentUsage(payload, sourceCollection, doc, sourceType = 'document', req) {
     const sourceDocumentId = String(doc.id);
-    const docsForSource = await findUsageDocsForSource(payload, sourceCollection, sourceDocumentId, req);
-    await deleteUsageDocs(payload, docsForSource, req);
-    return createUsageDocs(payload, sourceCollection, sourceType, doc, req);
+    const sourceWhere = usageDocsForSourceWhere(sourceCollection, sourceDocumentId);
+    const sourceFields = usageSourceFields(doc);
+    const usageRecords = extractComponentUsageRecords(doc.nitrogenData);
+    // Usage rows describe tree *structure* only — nothing derived from module
+    // props or content. Editing copy therefore leaves every row identical, so
+    // diffing turns the common autosave case into zero writes instead of a full
+    // delete-and-recreate of every row on the save's critical path.
+    const existingRows = await findAllDocs(payload, NITROGEN_COMPONENT_USAGE_COLLECTION, { limit: 200, where: sourceWhere }, req);
+    const desiredByKey = new Map();
+    for (const record of usageRecords) {
+        desiredByKey.set(usageKeyFor(sourceCollection, sourceDocumentId, record), record);
+    }
+    const existingByKey = new Map();
+    const staleKeys = [];
+    for (const row of existingRows) {
+        if (desiredByKey.has(row.usageKey))
+            existingByKey.set(row.usageKey, row);
+        else
+            staleKeys.push(row.usageKey);
+    }
+    if (staleKeys.length > 0) {
+        await deleteUsageDocsWhere(payload, { usageKey: { in: staleKeys } }, req);
+    }
+    // Title/slug/status are identical across every row of the document, so when
+    // they change one bulk update fixes the whole set rather than N row updates.
+    const sourceFieldsStale = existingRows.some((row) => (row.sourceTitle || '') !== sourceFields.sourceTitle ||
+        (row.sourceSlug || '') !== sourceFields.sourceSlug ||
+        (row.sourceStatus || '') !== sourceFields.sourceStatus);
+    if (sourceFieldsStale && existingByKey.size > 0) {
+        await payload.update({
+            collection: NITROGEN_COMPONENT_USAGE_COLLECTION,
+            overrideAccess: true,
+            req,
+            where: sourceWhere,
+            data: sourceFields,
+        });
+    }
+    for (const [usageKey, record] of desiredByKey) {
+        const row = existingByKey.get(usageKey);
+        const data = usageRowData(sourceCollection, sourceType, sourceDocumentId, sourceFields, record);
+        if (!row) {
+            await payload.create({
+                collection: NITROGEN_COMPONENT_USAGE_COLLECTION,
+                overrideAccess: true,
+                req,
+                data,
+            });
+        }
+        else if (!usageRowIsCurrent(row, sourceType)) {
+            await payload.update({
+                collection: NITROGEN_COMPONENT_USAGE_COLLECTION,
+                id: row.id,
+                overrideAccess: true,
+                req,
+                data,
+            });
+        }
+    }
+    return usageRecords.length;
 }
 export async function deleteDocumentUsage(payload, sourceCollection, sourceDocumentId, req) {
-    const docsForSource = await findUsageDocsForSource(payload, sourceCollection, String(sourceDocumentId), req);
-    await deleteUsageDocs(payload, docsForSource, req);
+    await deleteUsageDocsWhere(payload, usageDocsForSourceWhere(sourceCollection, String(sourceDocumentId)), req);
 }
 export async function reindexAllComponentInventory(payload, collections, manifestInput, req) {
     const entries = await syncComponentCatalog(payload, manifestInput, req);
-    const usageDocs = await findAllDocs(payload, NITROGEN_COMPONENT_USAGE_COLLECTION, {
-        limit: 200,
-        select: {
-            id: true,
-        },
-    }, req);
-    await deleteUsageDocs(payload, usageDocs, req);
+    await deleteUsageDocsWhere(payload, { id: { exists: true } }, req);
     let documentCount = 0;
     let usageCount = 0;
     for (const collection of collections) {

package/dist/localization.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Localization support — locale threading for read endpoints, dynamic-data
+ * translation metadata, and per-language translation status for builder
+ * content.
+ *
+ * Two independent layers cooperate here:
+ *
+ * 1. **Payload-native localization** (field data). When the host project's
+ *    Payload config has `localization` configured (either directly or injected
+ *    from the plugin's `localization` option), eligible text fields are
+ *    localized and read endpoints thread `?lang=` through to
+ *    `payload.find`/`findByID` as `locale` + `fallbackLocale`.
+ * 2. **Nitrogen settings localization** (builder content). Site languages live
+ *    in the `nitrogen-settings` global under `nitrogenConfig.localization`.
+ *    Translatable prop values inside `nitrogenData` are stored language-keyed
+ *    with the language as the OUTER key (`{ en: ..., es: ... }`); legacy bare
+ *    values read as the default language.
+ *
+ * Everything is gated: with no localization configured anywhere, every helper
+ * returns null/empty and callers behave exactly as before.
+ */
+import type { Field, Payload, PayloadRequest, SanitizedCollectionConfig } from 'payload';
+import type { ComponentManifestProp, DynamicDataMeta, LanguageStatus, LocalizationSettings } from '@nitrogenbuilder/types';
+import type { NitrogenSettingsGlobal } from './types.js';
+export interface PayloadLocaleConfig {
+    locales: string[];
+    defaultLocale: string;
+}
+/**
+ * Reads the sanitized Payload localization config at runtime. Returns null
+ * when the project has no Payload-level localization configured.
+ */
+export declare function getPayloadLocalization(payload: Payload): PayloadLocaleConfig | null;
+/** Reads `?lang=` (alias `?locale=`) off a request URL. */
+export declare function getRequestLanguage(req: PayloadRequest): string | null;
+export interface LocaleQueryOptions {
+    locale?: string;
+    fallbackLocale?: string;
+}
+/**
+ * Turns a requested language into `locale`/`fallbackLocale` options for
+ * `payload.find`/`findByID`. Returns `{}` (default behavior) when no language
+ * was requested, the project has no Payload localization, or the language is
+ * not a configured locale.
+ */
+export declare function resolveLocaleOptions(payload: Payload, lang?: string | null): LocaleQueryOptions;
+export declare function getCollectionConfig(payload: Payload, collectionSlug: string): SanitizedCollectionConfig | undefined;
+/**
+ * Dot-paths of localized text-typed fields of a collection config. Walks
+ * groups, rows, collapsibles, and tabs; named groups/tabs contribute a path
+ * segment.
+ */
+export declare function getLocalizedTextFieldPaths(fields: Field[] | undefined, prefix?: string): string[];
+/**
+ * The site language config from the `nitrogen-settings` global. Null when
+ * localization is absent or disabled — callers must treat null as
+ * "no localization behavior at all".
+ */
+export declare function getLocalizationSettings(settings: NitrogenSettingsGlobal): LocalizationSettings | null;
+/**
+ * Fetches a doc with every locale's value for localized fields (one
+ * `locale: 'all'` query). Returns null when the project has no Payload
+ * localization configured or the doc can't be read — advisory callers keep
+ * their default behavior in that case.
+ */
+export declare function fetchLocaleAllDoc(payload: Payload, collectionSlug: string, docId: string | number): Promise<Record<string, unknown> | null>;
+/**
+ * The default-locale title from a `locale: 'all'` doc, for editor-facing
+ * single-doc responses. The editor edits default-language field data only
+ * (the CMS admin owns field translations), so the `title` it displays and
+ * PATCHes back on save must never be a locale-resolved one. Returns null when
+ * there is nothing to override (no localization, title not localized, or no
+ * stored title) — callers then keep the response title as-is.
+ */
+export declare function getDefaultLocaleTitle(payload: Payload, localeAllDoc: Record<string, unknown> | null): string | null;
+/**
+ * Builds the connector-provided metadata the editor uses to badge
+ * untranslated CMS fields. Eligible keys are the localized text-typed fields
+ * of the collection config; translated keys per language are the fields whose
+ * locale-specific value exists (checked via one `locale: 'all'` fetch, or a
+ * caller-preloaded `localeAllDoc` to avoid a duplicate query).
+ *
+ * Returns null when the project has no Payload localization configured, so
+ * callers can attach `dynamic_data_meta` conditionally with zero change to
+ * the default response shape.
+ */
+export declare function buildDynamicDataMeta(payload: Payload, collectionSlug: string, docId?: string | number, localeAllDoc?: Record<string, unknown> | null): Promise<DynamicDataMeta | null>;
+type CatalogPropDef = ComponentManifestProp & {
+    translatable?: boolean;
+};
+/**
+ * componentName → group key → propKey → prop definition. Module prop values
+ * are stored group-keyed (`props[groupKey][propKey]`, mirroring the renderer's
+ * `spreadProps`), so the group level is preserved for lookups during the walk.
+ */
+export type TranslatablePropDefs = Map<string, Record<string, Record<string, CatalogPropDef>>>;
+/**
+ * Loads component prop definitions from the nitrogen-component-catalog
+ * collection so translatable props can be identified precisely. Returns an
+ * empty map when the catalog is unavailable — the walk then falls back to the
+ * lang-map heuristic.
+ */
+export declare function loadTranslatablePropDefs(payload: Payload): Promise<TranslatablePropDefs>;
+export interface ComputeTranslationStatusArgs {
+    payload: Payload;
+    collectionSlug: string;
+    docId: string | number;
+    nitrogenData: unknown;
+    localization: LocalizationSettings;
+    /** Preloaded catalog defs (avoids a re-fetch when batching). */
+    propDefs?: TranslatablePropDefs;
+    /** Preloaded `locale: 'all'` doc (avoids a re-fetch when batching). */
+    localeAllDoc?: Record<string, unknown> | null;
+}
+/**
+ * Computes per-language translation status for one page/template. Returns a
+ * `{ [langCode]: LanguageStatus }` map covering every configured non-default
+ * language, or null when there is nothing to compute.
+ */
+export declare function computeDocTranslationStatus(args: ComputeTranslationStatusArgs): Promise<Record<string, LanguageStatus> | null>;
+export {};