@nitrogenbuilder/connector-payload 1.1.1 → 1.2.0

package/dist/localization.js

@@ -0,0 +1,563 @@
+/**
+ * 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 { NITROGEN_COMPONENT_CATALOG_COLLECTION, findAllDocs, } from './inventory/indexing.js';
+/**
+ * Reads the sanitized Payload localization config at runtime. Returns null
+ * when the project has no Payload-level localization configured.
+ */
+export function getPayloadLocalization(payload) {
+    const localization = payload.config.localization;
+    if (!localization || typeof localization !== 'object')
+        return null;
+    const value = localization;
+    let locales = [];
+    if (Array.isArray(value.localeCodes)) {
+        locales = value.localeCodes.map(String).filter(Boolean);
+    }
+    else if (Array.isArray(value.locales)) {
+        locales = value.locales
+            .map((locale) => typeof locale === 'string'
+            ? locale
+            : String(locale?.code ?? ''))
+            .filter(Boolean);
+    }
+    const defaultLocale = typeof value.defaultLocale === 'string' ? value.defaultLocale : '';
+    if (locales.length === 0 || !defaultLocale)
+        return null;
+    return { locales, defaultLocale };
+}
+/** Reads `?lang=` (alias `?locale=`) off a request URL. */
+export function getRequestLanguage(req) {
+    try {
+        const url = new URL(req.url || '', 'http://localhost');
+        const lang = url.searchParams.get('lang') || url.searchParams.get('locale') || '';
+        return lang.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 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 function resolveLocaleOptions(payload, lang) {
+    if (!lang)
+        return {};
+    const localization = getPayloadLocalization(payload);
+    if (!localization || !localization.locales.includes(lang))
+        return {};
+    return { locale: lang, fallbackLocale: localization.defaultLocale };
+}
+export function getCollectionConfig(payload, collectionSlug) {
+    return (payload.config.collections || []).find((collection) => collection.slug === collectionSlug);
+}
+/** Text-bearing field types eligible for translation. */
+const LOCALIZABLE_FIELD_TYPES = new Set(['text', 'textarea', 'richText']);
+/**
+ * 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 function getLocalizedTextFieldPaths(fields, prefix = '') {
+    const paths = [];
+    for (const field of fields || []) {
+        const f = field;
+        const name = typeof f.name === 'string' && f.name ? f.name : undefined;
+        if (name && LOCALIZABLE_FIELD_TYPES.has(f.type) && f.localized) {
+            paths.push(`${prefix}${name}`);
+            continue;
+        }
+        // Array/blocks rows can't be addressed by a dot-path (getByPath cannot
+        // index rows), so only non-repeating containers are walked.
+        if (Array.isArray(f.fields) && f.type !== 'array') {
+            const nestedPrefix = name && f.type === 'group' ? `${prefix}${name}.` : prefix;
+            paths.push(...getLocalizedTextFieldPaths(f.fields, nestedPrefix));
+        }
+        if (Array.isArray(f.tabs)) {
+            for (const tab of f.tabs) {
+                const nestedPrefix = tab.name ? `${prefix}${tab.name}.` : prefix;
+                paths.push(...getLocalizedTextFieldPaths(tab.fields || [], nestedPrefix));
+            }
+        }
+    }
+    return paths;
+}
+// ---------------------------------------------------------------------------
+// Nitrogen settings localization (builder content)
+// ---------------------------------------------------------------------------
+/**
+ * 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 function getLocalizationSettings(settings) {
+    const localization = settings.nitrogenConfig?.localization;
+    if (!localization || typeof localization !== 'object')
+        return null;
+    const value = localization;
+    if (!value.enabled ||
+        !value.defaultLanguage ||
+        !Array.isArray(value.languages) ||
+        value.languages.length === 0) {
+        return null;
+    }
+    return value;
+}
+// ---------------------------------------------------------------------------
+// Shared value helpers
+// ---------------------------------------------------------------------------
+function hasContent(value) {
+    if (value === undefined || value === null)
+        return false;
+    if (typeof value === 'string')
+        return value.trim() !== '';
+    return true;
+}
+function getByPath(obj, path) {
+    let current = obj;
+    for (const part of path.split('.')) {
+        if (!current || typeof current !== 'object')
+            return undefined;
+        current = current[part];
+    }
+    return current;
+}
+function isPlainObject(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * A stored translatable value: every key is a configured language code.
+ * (Responsive values keyed by breakpoint names never collide because
+ * breakpoint names are not language codes.)
+ */
+function isLangMap(value, codes) {
+    const keys = Object.keys(value);
+    return keys.length > 0 && keys.every((key) => codes.has(key));
+}
+// ---------------------------------------------------------------------------
+// Dynamic data meta
+// ---------------------------------------------------------------------------
+/** `Post.`-namespaced dynamic-data keys for a doc field path. */
+function dynamicDataKeysForField(path) {
+    const keys = [`Post.${path}`];
+    if (path === 'title')
+        keys.push('Post.post_title');
+    return keys;
+}
+/**
+ * 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 async function fetchLocaleAllDoc(payload, collectionSlug, docId) {
+    if (!getPayloadLocalization(payload))
+        return null;
+    try {
+        return (await payload.findByID({
+            collection: collectionSlug,
+            id: docId,
+            depth: 0,
+            locale: 'all',
+            overrideAccess: true,
+            disableErrors: true,
+        }));
+    }
+    catch {
+        return 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 function getDefaultLocaleTitle(payload, localeAllDoc) {
+    const localization = getPayloadLocalization(payload);
+    if (!localization || !localeAllDoc)
+        return null;
+    const title = localeAllDoc.title;
+    if (!isPlainObject(title))
+        return null;
+    const value = title[localization.defaultLocale];
+    if (typeof value === 'string')
+        return value;
+    // No default-locale title stored — first stored one, matching the
+    // renderer's language-resolution fallback chain.
+    for (const candidate of Object.values(title)) {
+        if (typeof candidate === 'string' && candidate)
+            return candidate;
+    }
+    return 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 async function buildDynamicDataMeta(payload, collectionSlug, docId, localeAllDoc) {
+    const localization = getPayloadLocalization(payload);
+    if (!localization)
+        return null;
+    const collection = getCollectionConfig(payload, collectionSlug);
+    if (!collection)
+        return null;
+    const fieldPaths = getLocalizedTextFieldPaths(collection.fields);
+    const meta = {
+        eligibleKeys: fieldPaths.flatMap(dynamicDataKeysForField),
+        translatedKeys: {},
+        perPostNamespaces: ['Post'],
+    };
+    if (fieldPaths.length === 0)
+        return meta;
+    const doc = localeAllDoc !== undefined
+        ? localeAllDoc
+        : docId !== undefined
+            ? await fetchLocaleAllDoc(payload, collectionSlug, docId)
+            : null;
+    if (!doc)
+        return meta;
+    for (const lang of localization.locales) {
+        const translated = [];
+        for (const path of fieldPaths) {
+            const value = getByPath(doc, path);
+            if (isPlainObject(value) && hasContent(value[lang])) {
+                translated.push(...dynamicDataKeysForField(path));
+            }
+        }
+        meta.translatedKeys[lang] = translated;
+    }
+    return meta;
+}
+/**
+ * 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 async function loadTranslatablePropDefs(payload) {
+    const defs = new Map();
+    try {
+        const docs = await findAllDocs(payload, NITROGEN_COMPONENT_CATALOG_COLLECTION);
+        for (const doc of docs) {
+            const definition = doc.definition;
+            if (!definition?.categories)
+                continue;
+            const byGroup = {};
+            for (const category of Object.values(definition.categories)) {
+                for (const [groupKey, group] of Object.entries(category?.groups || {})) {
+                    if (!group?.props || Object.keys(group.props).length === 0)
+                        continue;
+                    byGroup[groupKey] = { ...byGroup[groupKey], ...group.props };
+                }
+            }
+            if (Object.keys(byGroup).length > 0) {
+                defs.set(doc.componentName, byGroup);
+            }
+        }
+    }
+    catch {
+        // Catalog unavailable — heuristic fallback.
+    }
+    return defs;
+}
+function countLangMap(value, ctx, counter) {
+    const hasDefault = hasContent(value[ctx.defaultLanguage]);
+    const hasLang = hasContent(value[ctx.lang]);
+    if (!hasDefault && !hasLang)
+        return;
+    counter.total += 1;
+    if (hasDefault && !hasLang)
+        counter.untranslated += 1;
+}
+/** A DynamicValue binding: `{ key, before?, fallback?, after? }`. */
+function isDynamicValue(value) {
+    if (typeof value.key !== 'string')
+        return false;
+    const keys = Object.keys(value);
+    return keys.every((key) => ['key', 'before', 'fallback', 'after'].includes(key));
+}
+function countDynamicValueSlots(value, ctx, counter) {
+    for (const slot of ['before', 'fallback', 'after']) {
+        const slotValue = value[slot];
+        if (slotValue === undefined || typeof slotValue === 'boolean')
+            continue;
+        if (isPlainObject(slotValue) && isLangMap(slotValue, ctx.codes)) {
+            // Language-keyed boolean toggles (`fallback: { en: true }`) are
+            // settings, not text — mirror the bare-boolean skip above.
+            if (typeof slotValue[ctx.defaultLanguage] === 'boolean' ||
+                typeof slotValue[ctx.lang] === 'boolean') {
+                continue;
+            }
+            countLangMap(slotValue, ctx, counter);
+        }
+        else if (hasContent(slotValue)) {
+            // Legacy bare value = default language only.
+            counter.total += 1;
+            counter.untranslated += 1;
+        }
+    }
+}
+/**
+ * Heuristic walk for props without catalog definitions: any nested object
+ * whose keys are all configured language codes counts as a translatable
+ * value; it is untranslated in L when it has a default-language value but no
+ * L value. Bare values are NOT counted here (we cannot know they are
+ * translatable without a definition).
+ */
+function walkValueHeuristic(value, ctx, counter) {
+    if (!value || typeof value !== 'object')
+        return;
+    if (Array.isArray(value)) {
+        for (const item of value)
+            walkValueHeuristic(item, ctx, counter);
+        return;
+    }
+    const record = value;
+    if (isLangMap(record, ctx.codes)) {
+        countLangMap(record, ctx, counter);
+        return;
+    }
+    for (const [key, nested] of Object.entries(record)) {
+        if (key === 'children')
+            continue;
+        walkValueHeuristic(nested, ctx, counter);
+    }
+}
+/** Editor storage convention: `props[group][propKey + '___dynamic']` holds a
+ * DynamicValue binding for the base prop. */
+const DYNAMIC_KEY_SUFFIX = '___dynamic';
+/**
+ * One stored prop entry, dispatching on the editor's key conventions.
+ * `<key>___dynamic` entries hold DynamicValue bindings whose text slots are
+ * page content regardless of the base prop's own translatability (the
+ * renderer language-resolves every dynamic slot).
+ */
+function countPropEntry(key, value, defs, ctx, counter) {
+    if (key.endsWith(DYNAMIC_KEY_SUFFIX)) {
+        if (isPlainObject(value) && isDynamicValue(value)) {
+            countDynamicValueSlots(value, ctx, counter);
+        }
+        else {
+            walkValueHeuristic(value, ctx, counter);
+        }
+        return;
+    }
+    countPropValue(value, defs?.[key], ctx, counter);
+}
+function countPropValue(value, def, ctx, counter) {
+    if (def?.translatable) {
+        if (isPlainObject(value)) {
+            if (isLangMap(value, ctx.codes)) {
+                countLangMap(value, ctx, counter);
+                return;
+            }
+            if (isDynamicValue(value)) {
+                countDynamicValueSlots(value, ctx, counter);
+                return;
+            }
+        }
+        if (hasContent(value)) {
+            // Legacy bare value = default language only.
+            counter.total += 1;
+            counter.untranslated += 1;
+        }
+        return;
+    }
+    if (def?.type === 'array' && Array.isArray(value)) {
+        for (const item of value) {
+            if (!isPlainObject(item))
+                continue;
+            for (const [key, nested] of Object.entries(item)) {
+                countPropEntry(key, nested, def.props, ctx, counter);
+            }
+        }
+        return;
+    }
+    if (def?.props && isPlainObject(value)) {
+        for (const [key, nested] of Object.entries(value)) {
+            countPropEntry(key, nested, def.props, ctx, counter);
+        }
+        return;
+    }
+    if (!def)
+        walkValueHeuristic(value, ctx, counter);
+}
+function moduleNameFromNode(node) {
+    for (const key of ['module', 'moduleId']) {
+        const value = node[key];
+        if (typeof value === 'string')
+            return value;
+        if (isPlainObject(value) &&
+            typeof value.name === 'string') {
+            return value.name;
+        }
+    }
+    return null;
+}
+/**
+ * Walks the module tree counting translatable prop values for one language.
+ * Modules hidden in that language are skipped entirely, including their
+ * subtree. The editor stores hidden languages at `props.__hiddenLanguages`
+ * (canonical); module-level `hiddenLanguages` is the legacy fallback.
+ */
+function walkModules(modules, ctx, defs, counter) {
+    if (!Array.isArray(modules))
+        return;
+    for (const maybeNode of modules) {
+        if (!isPlainObject(maybeNode))
+            continue;
+        const node = maybeNode;
+        const props = node.props;
+        const hiddenLanguages = (isPlainObject(props) ? props.__hiddenLanguages : undefined) ??
+            node.hiddenLanguages;
+        if (Array.isArray(hiddenLanguages) && hiddenLanguages.includes(ctx.lang)) {
+            continue;
+        }
+        const componentName = moduleNameFromNode(node);
+        const componentDefs = componentName ? defs.get(componentName) : undefined;
+        if (isPlainObject(props)) {
+            // Prop values are stored group-keyed: props[groupKey][propKey].
+            // `__`-prefixed keys are instance metadata (__label, __hiddenLanguages).
+            for (const [groupKey, groupValue] of Object.entries(props)) {
+                if (groupKey === 'children' || groupKey.startsWith('__'))
+                    continue;
+                if (isPlainObject(groupValue)) {
+                    if (isLangMap(groupValue, ctx.codes)) {
+                        // Flat (ungrouped) translatable value — count it directly.
+                        countLangMap(groupValue, ctx, counter);
+                        continue;
+                    }
+                    const groupDefs = componentDefs?.[groupKey];
+                    for (const [propKey, propValue] of Object.entries(groupValue)) {
+                        countPropEntry(propKey, propValue, groupDefs, ctx, counter);
+                    }
+                }
+                else {
+                    walkValueHeuristic(groupValue, ctx, counter);
+                }
+            }
+            const children = props.children;
+            if (Array.isArray(children)) {
+                walkModules(children, ctx, defs, counter);
+            }
+            else if (isPlainObject(children)) {
+                for (const slotChildren of Object.values(children)) {
+                    walkModules(slotChildren, ctx, defs, counter);
+                }
+            }
+        }
+        if (Array.isArray(node.children)) {
+            walkModules(node.children, ctx, defs, counter);
+        }
+    }
+}
+/**
+ * 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 async function computeDocTranslationStatus(args) {
+    const { payload, collectionSlug, docId, nitrogenData, localization } = args;
+    const defaultLanguage = localization.defaultLanguage;
+    const languages = (localization.languages || [])
+        .map((language) => language.code)
+        .filter(Boolean);
+    const nonDefault = languages.filter((code) => code !== defaultLanguage);
+    if (!defaultLanguage || nonDefault.length === 0)
+        return null;
+    const codes = new Set(languages.concat(defaultLanguage));
+    const propDefs = args.propDefs ?? (await loadTranslatablePropDefs(payload));
+    // Field-side coverage relies on Payload-native localization.
+    let fieldPaths = [];
+    let localeAllDoc = args.localeAllDoc ?? null;
+    if (getPayloadLocalization(payload)) {
+        const collection = getCollectionConfig(payload, collectionSlug);
+        fieldPaths = collection ? getLocalizedTextFieldPaths(collection.fields) : [];
+        if (fieldPaths.length > 0 && localeAllDoc === null && args.localeAllDoc === undefined) {
+            localeAllDoc = await fetchLocaleAllDoc(payload, collectionSlug, docId);
+        }
+    }
+    const statuses = {};
+    for (const lang of nonDefault) {
+        const ctx = { lang, defaultLanguage, codes };
+        const propCounter = { total: 0, untranslated: 0 };
+        walkModules(nitrogenData, ctx, propDefs, propCounter);
+        const fieldCounter = { total: 0, untranslated: 0 };
+        let slugTranslated;
+        let seoTranslated;
+        if (localeAllDoc) {
+            let seoTotal = 0;
+            let seoUntranslated = 0;
+            for (const path of fieldPaths) {
+                const value = getByPath(localeAllDoc, path);
+                if (!isPlainObject(value))
+                    continue;
+                const hasDefault = hasContent(value[defaultLanguage]);
+                const hasLang = hasContent(value[lang]);
+                if (path === 'slug') {
+                    slugTranslated = hasLang;
+                    continue;
+                }
+                if (!hasDefault && !hasLang)
+                    continue;
+                fieldCounter.total += 1;
+                if (hasDefault && !hasLang) {
+                    fieldCounter.untranslated += 1;
+                    if (path.startsWith('meta.'))
+                        seoUntranslated += 1;
+                }
+                if (path.startsWith('meta.'))
+                    seoTotal += 1;
+            }
+            if (seoTotal > 0)
+                seoTranslated = seoUntranslated === 0;
+        }
+        const total = propCounter.total + fieldCounter.total;
+        const untranslated = propCounter.untranslated + fieldCounter.untranslated;
+        const state = total === 0 || untranslated === 0
+            ? 'complete'
+            : untranslated >= total
+                ? 'none'
+                : 'partial';
+        statuses[lang] = {
+            state,
+            untranslatedProps: propCounter.untranslated,
+            untranslatedFields: fieldCounter.untranslated,
+            ...(slugTranslated !== undefined ? { slugTranslated } : {}),
+            ...(seoTranslated !== undefined ? { seoTranslated } : {}),
+        };
+    }
+    return statuses;
+}

package/dist/types.d.ts

@@ -123,8 +123,11 @@ interface TemplateUpdateData {
 }
 export interface SlugLookupRequestBody {
     slug?: string;
+    /** Language to resolve localized fields/slugs in (alias of ?lang=). */
+    lang?: string;
     data?: {
         slug?: string;
+        lang?: string;
     };
 }
 export interface MediaUpdateRequestBody {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitrogenbuilder/connector-payload",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Nitrogen page builder connector plugin for Payload CMS 3.x",
   "author": "Leonardo Dentzien <leo@torchmedia.ca>",
   "type": "module",