@payloadcms/figma 0.0.1-alpha.7 → 0.0.1-alpha.71

package/dist/db-content-api/utilities/data/transformPublishedLocale.js

@@ -0,0 +1,42 @@
+/**
+ * Transform publishedLocale to localizeStatus format
+ *
+ * publishedLocale is a legacy API that is going to be removed in Payload v4 in favor of localizeStatus.
+ * The db-adapter transforms publishedLocale here so Content API doesn't need to know about it.
+ */ /**
+ * Transforms version data to use localizeStatus format
+ *
+ * If `publishedLocale` is provided and `_status` is a string, transforms to object format.
+ * If `_status` is already an object, leaves it unchanged.
+ *
+ * @example
+ * // Input (old format):
+ * { _status: 'published', text: 'Hello' }, publishedLocale: 'en'
+ *
+ * // Output (new format):
+ * { _status: { en: 'published' }, text: 'Hello' }
+ */ export function transformToLocalizeStatus(versionData, publishedLocale) {
+    // No publishedLocale provided - no transformation needed
+    if (!publishedLocale) {
+        return versionData;
+    }
+    const status = versionData._status;
+    // If _status is already an object (localizeStatus format), return as-is
+    if (typeof status === 'object' && status !== null) {
+        return versionData;
+    }
+    // Transform: publishedLocale + string status → object status
+    if (typeof status === 'string') {
+        // Only the specified locale gets the status, others remain undefined
+        // (Content API / Payload will handle merging with existing locale statuses)
+        return {
+            ...versionData,
+            _status: {
+                [publishedLocale]: status
+            }
+        };
+    }
+    return versionData;
+}
+
+//# sourceMappingURL=transformPublishedLocale.js.map

package/dist/db-content-api/utilities/data/validateRelationships.d.ts

@@ -0,0 +1,7 @@
+import type { Payload } from 'payload';
+export declare function validateRelationshipIds({ collectionSlug, data, payload, }: {
+    collectionSlug: string;
+    data: Record<string, unknown>;
+    payload: Payload;
+}): void;
+//# sourceMappingURL=validateRelationships.d.ts.map

package/dist/db-content-api/utilities/data/validateRelationships.js

@@ -0,0 +1,102 @@
+import { traverseFields } from 'payload';
+const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function collectRelationshipValues({ data, fields }) {
+    const relationships = [];
+    const callback = ({ field, ref })=>{
+        if (!('name' in field) || !field.name) {
+            return;
+        }
+        if (field.type !== 'relationship' && field.type !== 'upload') {
+            return;
+        }
+        if (!ref || typeof ref !== 'object') {
+            return;
+        }
+        const rawValue = ref[field.name];
+        if (rawValue == null || rawValue === '') {
+            return;
+        }
+        // For localized fields, the value is a locale map (e.g. { en: "uuid", fr: "uuid" }).
+        // Iterate locale values instead of treating the map as an ID.
+        if ('localized' in field && field.localized) {
+            if (typeof rawValue === 'object' && !Array.isArray(rawValue)) {
+                for (const localeValue of Object.values(rawValue)){
+                    if (localeValue != null && localeValue !== '') {
+                        parseRelationshipValues(localeValue, field.relationTo, relationships);
+                    }
+                }
+            }
+            return;
+        }
+        parseRelationshipValues(rawValue, field.relationTo, relationships);
+    };
+    traverseFields({
+        callback,
+        fields,
+        fillEmpty: false,
+        ref: data
+    });
+    return relationships;
+}
+function parseRelationshipValues(value, relationTo, relationships) {
+    if (Array.isArray(relationTo)) {
+        // Polymorphic (single or hasMany): value is { relationTo, value } or array of them
+        const values = Array.isArray(value) ? value : [
+            value
+        ];
+        for (const v of values){
+            if (v && typeof v === 'object' && 'relationTo' in v && 'value' in v) {
+                const obj = v;
+                if (obj.value != null && obj.value !== '') {
+                    relationships.push({
+                        collection: obj.relationTo,
+                        value: obj.value
+                    });
+                }
+            }
+        }
+    } else {
+        // Non-polymorphic (single or hasMany): value is a bare ID or array of IDs
+        const values = Array.isArray(value) ? value : [
+            value
+        ];
+        for (const v of values){
+            if (v != null && v !== '') {
+                relationships.push({
+                    collection: relationTo,
+                    value: v
+                });
+            }
+        }
+    }
+}
+function isValidId(value, customIDType) {
+    if (customIDType === 'number') {
+        const num = typeof value === 'number' ? value : typeof value === 'string' ? Number(value) : NaN;
+        return Number.isFinite(num);
+    }
+    if (customIDType === 'text') {
+        return typeof value === 'string' && value.length > 0;
+    }
+    return typeof value === 'string' && UUID_REGEX.test(value);
+}
+export function validateRelationshipIds({ collectionSlug, data, payload }) {
+    const isGlobal = collectionSlug.startsWith('_global-');
+    const actualSlug = isGlobal ? collectionSlug.substring(8) : collectionSlug;
+    const config = isGlobal ? payload.config.globals?.find((g)=>g.slug === actualSlug) : payload.config.collections.find((c)=>c.slug === actualSlug);
+    if (!config?.fields) {
+        return;
+    }
+    const relationships = collectRelationshipValues({
+        data,
+        fields: config.fields
+    });
+    for (const { collection, value } of relationships){
+        const customIDType = payload.collections?.[collection]?.customIDType;
+        if (!isValidId(value, customIDType)) {
+            throw new Error(`Invalid relationship ID "${String(value)}" for collection "${collection}". Expected ${customIDType === 'number' ? 'a number' : customIDType === 'text' ? 'a non-empty string' : 'a valid UUID'}.`);
+        }
+    }
+}
+
+//# sourceMappingURL=validateRelationships.js.map

package/dist/db-content-api/utilities/joins.d.ts

@@ -0,0 +1,53 @@
+import type { JoinQuery, Payload } from 'payload';
+import type { components } from '../generated/content-api-types.js';
+type ContentAPIJoin = components['schemas']['JoinClause'][number];
+/**
+ * Convert Payload's JoinQuery to Content API's join format.
+ *
+ * ## Content API Join Limitations
+ *
+ * The following Payload join features are NOT YET supported by Content API:
+ *
+ * 1. **hasMany relationships** - Content API's join uses `data#>'{path}'#>>'{}'` to extract
+ *    a single ID. HasMany relationships store arrays `["id1", "id2"]` which can't match.
+ *
+ * 2. **Array field relationships** - `on: 'array.category'` expects iteration over array
+ *    elements, but Content API treats the path as a single JSONB extraction.
+ *
+ * 3. **Polymorphic relationships** - Stored as `{ relationTo, value }` objects, but
+ *    Content API expects a simple ID string.
+ *
+ * Note: "Where querying through joins" (e.g., `where: { 'relatedPosts.title': { equals: 'x' } }`)
+ * is a separate Payload feature that filters documents based on joined data. This is NOT
+ * a join feature but a where clause feature, and would need separate Content API support.
+ *
+ * Payload's JoinQuery format (at runtime):
+ * {
+ *   'group.relatedPosts': {    // joinPath - where results go in the document
+ *     sort: '-title',
+ *     limit: 10,
+ *     page: 2,                 // page-based pagination
+ *     where: { ... },          // Payload where format
+ *     count: true
+ *   }
+ * }
+ *
+ * Content API's join format:
+ * [{
+ *   collectionId: 'posts',     // collection to join FROM
+ *   on: 'group.category',      // field in joined collection pointing to this doc
+ *   path: 'group.relatedPosts', // where to put results
+ *   count: false,
+ *   where: { ... },            // Content API where format
+ *   sort: '-title',
+ *   limit: 10,
+ *   page: 2
+ * }]
+ *
+ * The mapping requires the collection config to resolve:
+ * - Which collection each join field refers to
+ * - What the 'on' field is for each join
+ */
+export declare function convertPayloadJoinsToContentAPI(payload: Payload, collectionSlug: string, joins: false | JoinQuery | undefined, locale?: string): ContentAPIJoin[] | undefined;
+export {};
+//# sourceMappingURL=joins.d.ts.map

package/dist/db-content-api/utilities/joins.js

@@ -0,0 +1,139 @@
+import { addFallbackSort } from '../temp-utilities/sorting.js';
+import { convertPayloadWhereToContentAPI } from './where.js';
+/**
+ * Convert Payload's JoinQuery to Content API's join format.
+ *
+ * ## Content API Join Limitations
+ *
+ * The following Payload join features are NOT YET supported by Content API:
+ *
+ * 1. **hasMany relationships** - Content API's join uses `data#>'{path}'#>>'{}'` to extract
+ *    a single ID. HasMany relationships store arrays `["id1", "id2"]` which can't match.
+ *
+ * 2. **Array field relationships** - `on: 'array.category'` expects iteration over array
+ *    elements, but Content API treats the path as a single JSONB extraction.
+ *
+ * 3. **Polymorphic relationships** - Stored as `{ relationTo, value }` objects, but
+ *    Content API expects a simple ID string.
+ *
+ * Note: "Where querying through joins" (e.g., `where: { 'relatedPosts.title': { equals: 'x' } }`)
+ * is a separate Payload feature that filters documents based on joined data. This is NOT
+ * a join feature but a where clause feature, and would need separate Content API support.
+ *
+ * Payload's JoinQuery format (at runtime):
+ * {
+ *   'group.relatedPosts': {    // joinPath - where results go in the document
+ *     sort: '-title',
+ *     limit: 10,
+ *     page: 2,                 // page-based pagination
+ *     where: { ... },          // Payload where format
+ *     count: true
+ *   }
+ * }
+ *
+ * Content API's join format:
+ * [{
+ *   collectionId: 'posts',     // collection to join FROM
+ *   on: 'group.category',      // field in joined collection pointing to this doc
+ *   path: 'group.relatedPosts', // where to put results
+ *   count: false,
+ *   where: { ... },            // Content API where format
+ *   sort: '-title',
+ *   limit: 10,
+ *   page: 2
+ * }]
+ *
+ * The mapping requires the collection config to resolve:
+ * - Which collection each join field refers to
+ * - What the 'on' field is for each join
+ */ export function convertPayloadJoinsToContentAPI(payload, collectionSlug, joins, locale) {
+    const collectionConfig = payload.config.collections.find((c)=>c.slug === collectionSlug);
+    if (!collectionConfig) {
+        return undefined;
+    }
+    // joins === false means explicitly disable all joins
+    // joins === undefined means use defaults (no custom query params)
+    if (joins === false || !joins) {
+        return undefined;
+    }
+    const result = [];
+    // Iterate through all join paths in the query
+    for (const [joinPath, joinQueryValue] of Object.entries(joins)){
+        // joinQuery === false means skip this specific join
+        if (joinQueryValue === false) {
+            continue;
+        }
+        // Normalize undefined/empty to empty object
+        const joinQuery = joinQueryValue ?? {};
+        // Find the SanitizedJoin config for this joinPath
+        // SanitizedJoins is indexed by the collection being joined FROM
+        let foundJoin;
+        // Search through all collections in the joins config
+        for (const [collectionSlug, sanitizedJoins] of Object.entries(collectionConfig.joins)){
+            for (const sanitizedJoin of sanitizedJoins){
+                if (sanitizedJoin.joinPath === joinPath) {
+                    const on = locale && sanitizedJoin.getForeignPath ? sanitizedJoin.getForeignPath({
+                        locale
+                    }) : sanitizedJoin.field.on;
+                    foundJoin = {
+                        collectionSlug,
+                        defaultLimit: sanitizedJoin.field.defaultLimit,
+                        defaultSort: sanitizedJoin.field.defaultSort,
+                        on
+                    };
+                    break;
+                }
+            }
+            if (foundJoin) {
+                break;
+            }
+        }
+        // Also check polymorphic joins
+        if (!foundJoin) {
+            for (const sanitizedJoin of collectionConfig.polymorphicJoins){
+                if (sanitizedJoin.joinPath === joinPath) {
+                    const collections = sanitizedJoin.field.collection;
+                    const on = locale && sanitizedJoin.getForeignPath ? sanitizedJoin.getForeignPath({
+                        locale
+                    }) : sanitizedJoin.field.on;
+                    foundJoin = {
+                        collectionSlug: collections,
+                        defaultSort: sanitizedJoin.field.defaultSort,
+                        on
+                    };
+                    break;
+                }
+            }
+        }
+        if (!foundJoin) {
+            payload.logger.warn(`Join path '${joinPath}' not found in collection config for '${collectionConfig.slug}'`);
+            continue;
+        }
+        // Fall back to the default limit if not specified in the query
+        const effectiveLimit = joinQuery.limit ?? foundJoin.defaultLimit;
+        // Add fallback sort for the joined collection
+        const sortWithFallback = addFallbackSort(joinQuery.sort, payload, foundJoin.collectionSlug, foundJoin.defaultSort);
+        const contentAPIJoin = {
+            collectionId: foundJoin.collectionSlug,
+            count: joinQuery.count ?? false,
+            on: foundJoin.on,
+            path: joinPath,
+            ...effectiveLimit !== undefined && {
+                limit: effectiveLimit
+            },
+            ...joinQuery.page && {
+                page: joinQuery.page
+            },
+            ...sortWithFallback && {
+                sort: sortWithFallback
+            },
+            ...joinQuery.where && {
+                where: convertPayloadWhereToContentAPI(joinQuery.where)
+            }
+        };
+        result.push(contentAPIJoin);
+    }
+    return result.length > 0 ? result : undefined;
+}
+
+//# sourceMappingURL=joins.js.map

package/dist/db-content-api/utilities/locale/index.d.ts

@@ -0,0 +1,10 @@
+import type { Payload } from 'payload';
+/**
+ * Determines what locale to send to Content API based on request locale value
+ * and config's defaultLocale.
+ *
+ * If no locale is provided, falls back to the default locale from config.
+ * Returns undefined for 'all' and '*' (special Payload values for returning all locales).
+ */
+export declare function addFallbackLocale(locale: null | string | undefined, payload: Payload): string | undefined;
+//# sourceMappingURL=index.d.ts.map

package/dist/db-content-api/utilities/locale/index.js

@@ -0,0 +1,21 @@
+/**
+ * Determines what locale to send to Content API based on request locale value
+ * and config's defaultLocale.
+ *
+ * If no locale is provided, falls back to the default locale from config.
+ * Returns undefined for 'all' and '*' (special Payload values for returning all locales).
+ */ export function addFallbackLocale(locale, payload) {
+    const defaultLocale = payload.config.localization ? payload.config.localization.defaultLocale : undefined;
+    if (locale) {
+        // 'all' and '*' are special Payload values meaning "return all locales" - don't send to Content API
+        if (locale === 'all' || locale === '*') {
+            return undefined;
+        }
+        return locale;
+    } else if (defaultLocale) {
+        return defaultLocale;
+    }
+    return undefined;
+}
+
+//# sourceMappingURL=index.js.map

package/dist/db-content-api/utilities/meta/buildLocalizedPaths.d.ts

@@ -0,0 +1,11 @@
+import type { Payload } from 'payload';
+/**
+ * Extracts all localized field paths from a collection's field configuration.
+ * Recursively traverses nested structures (groups, arrays, blocks, tabs) to find fields marked as localized.
+ *
+ * @param payload - The Payload instance containing collection configurations
+ * @param collectionSlug - The slug of the collection to extract localized paths from
+ * @returns Array of dot-notation paths to localized fields (e.g., ['title', 'metadata.description'])
+ */
+export declare function buildLocalizedPaths(payload: Payload, collectionSlug: string): string[];
+//# sourceMappingURL=buildLocalizedPaths.d.ts.map

package/dist/db-content-api/utilities/meta/buildLocalizedPaths.js

@@ -0,0 +1,74 @@
+/**
+ * Extracts all localized field paths from a collection's field configuration.
+ * Recursively traverses nested structures (groups, arrays, blocks, tabs) to find fields marked as localized.
+ *
+ * @param payload - The Payload instance containing collection configurations
+ * @param collectionSlug - The slug of the collection to extract localized paths from
+ * @returns Array of dot-notation paths to localized fields (e.g., ['title', 'metadata.description'])
+ */ export function buildLocalizedPaths(payload, collectionSlug) {
+    const collectionConfig = payload.config.collections.find((c)=>c.slug === collectionSlug);
+    if (!collectionConfig) {
+        return [];
+    }
+    const localizedPaths = [];
+    traverseFields(collectionConfig.fields, localizedPaths);
+    // Add _status to localized paths if localizeStatus is enabled for this collection
+    // _status is a base field added by Payload when versions.drafts is enabled,
+    // and it becomes localized when versions.drafts.localizeStatus is true
+    // localizeStatus requires both experimental flag AND collection-level config
+    const experimentalLocalizeStatus = 'experimental' in payload.config && payload.config.experimental && typeof payload.config.experimental === 'object' && 'localizeStatus' in payload.config.experimental && payload.config.experimental.localizeStatus === true;
+    const drafts = collectionConfig.versions && typeof collectionConfig.versions === 'object' ? collectionConfig.versions.drafts : false;
+    const collectionLocalizeStatus = drafts && typeof drafts === 'object' && 'localizeStatus' in drafts && drafts.localizeStatus === true;
+    const hasLocalizeStatus = payload.config.localization && experimentalLocalizeStatus && collectionLocalizeStatus;
+    if (hasLocalizeStatus && !localizedPaths.includes('_status')) {
+        localizedPaths.push('_status');
+    }
+    return localizedPaths;
+}
+/** Recursively traverses fields to find and collect localized paths */ function traverseFields(fields, localizedPaths, parentPath = '', parentIsLocalized = false) {
+    for (const field of fields){
+        // Unnamed layout fields (row, collapsible, unnamed group, unnamed tabs) don't store data
+        // at their own level, but their child fields may be localized. Recurse into them with
+        // the same parent path so localized fields bubble up correctly.
+        if (!('name' in field)) {
+            if ('fields' in field && Array.isArray(field.fields)) {
+                traverseFields(field.fields, localizedPaths, parentPath, parentIsLocalized);
+            }
+            if ('tabs' in field && Array.isArray(field.tabs)) {
+                for (const tab of field.tabs){
+                    if (tab.fields) {
+                        const tabPath = tab.name ? buildPath(parentPath, tab.name) : parentPath;
+                        traverseFields(tab.fields, localizedPaths, tabPath, parentIsLocalized);
+                    }
+                }
+            }
+            continue;
+        }
+        const fieldPath = buildPath(parentPath, field.name);
+        const isLocalized = 'localized' in field && field.localized === true;
+        const includeNestedPaths = isLocalized || parentIsLocalized;
+        // Add field to results if localized or parent is localized
+        if (includeNestedPaths) {
+            localizedPaths.push(fieldPath);
+        }
+        // Handle blocks field - has a special 'blocks' array structure and each block has its own nested fields
+        if (field.type === 'blocks' && 'blocks' in field) {
+            for (const block of field.blocks){
+                if ('fields' in block) {
+                    traverseFields(block.fields, localizedPaths, fieldPath, includeNestedPaths);
+                }
+            }
+            continue;
+        }
+        // Handle field type that support nested fields
+        // Recursively handle nested structures (groups, arrays, tab, etc)
+        if ('fields' in field) {
+            traverseFields(field.fields, localizedPaths, fieldPath, includeNestedPaths);
+        }
+    }
+}
+/** Builds a dot-notation path from parent path and field name */ function buildPath(parentPath, fieldName) {
+    return parentPath ? `${parentPath}.${fieldName}` : fieldName;
+}
+
+//# sourceMappingURL=buildLocalizedPaths.js.map

package/dist/db-content-api/utilities/meta/buildMeta.d.ts

@@ -0,0 +1,42 @@
+import type { Payload, Where } from 'payload';
+import type { components } from '../../generated/content-api-types.js';
+import type { PathTypesRecord } from '../../temp-utilities/types.js';
+/**
+ * Metadata sent to Content API for query processing.
+ *
+ * TODO: This interface is defined here temporarily so Content API can test the integration.
+ * Once Content API implements support for pathTypes with relationship info, this type
+ * should be generated from openapi.json and ContentAPIMeta can be removed.
+ */
+export interface ContentAPIMeta {
+    localizedPaths?: string[];
+    pathTypes?: PathTypesRecord;
+    uniquePaths?: {
+        paths: string[];
+    }[];
+}
+/**
+ * The type that Content API currently expects (from generated types).
+ * This is more restrictive than ContentAPIMeta until Content API is updated.
+ */
+type ContentAPIMetaGenerated = components['schemas']['RequestMeta'];
+export interface BuildMetaOptions {
+    collection: string;
+    /** Document data — when provided, unique field constraints are included in meta. */
+    data?: Record<string, unknown>;
+    locale: string | undefined;
+    where?: Where;
+}
+/**
+ * Builds the `meta` object for Content API requests.
+ * Combines pathTypes (for array field handling) and localizedPaths (for locale queries).
+ *
+ * @param payload - The Payload instance
+ * @param options - Options including collection slug, locale, and where clause
+ * @returns Object with meta property ready to spread into request body, or empty object if no meta needed
+ */
+export declare function buildMeta(payload: Payload, options: BuildMetaOptions): {
+    meta?: ContentAPIMetaGenerated;
+};
+export {};
+//# sourceMappingURL=buildMeta.d.ts.map

package/dist/db-content-api/utilities/meta/buildMeta.js

@@ -0,0 +1,41 @@
+import { buildLocalizedPaths } from './buildLocalizedPaths.js';
+import { buildPathTypes } from './buildPathTypes.js';
+import { buildUniquePaths } from './buildUniquePaths.js';
+/**
+ * Builds the `meta` object for Content API requests.
+ * Combines pathTypes (for array field handling) and localizedPaths (for locale queries).
+ *
+ * @param payload - The Payload instance
+ * @param options - Options including collection slug, locale, and where clause
+ * @returns Object with meta property ready to spread into request body, or empty object if no meta needed
+ */ export function buildMeta(payload, options) {
+    const { collection, data, locale, where } = options;
+    const meta = {};
+    // Add pathTypes if there are array fields in the where clause
+    const pathTypes = buildPathTypes(payload, collection, where);
+    if (Object.keys(pathTypes).length > 0) {
+        meta.pathTypes = pathTypes;
+    }
+    // Add localizedPaths if locale is specified (but not 'all')
+    if (locale && locale !== 'all') {
+        const localizedPaths = buildLocalizedPaths(payload, collection);
+        if (localizedPaths.length > 0) {
+            meta.localizedPaths = localizedPaths;
+        }
+    }
+    // Add uniquePaths when data is provided (create/upsert operations)
+    if (data) {
+        const uniquePaths = buildUniquePaths(payload, collection, data);
+        if (uniquePaths.length > 0) {
+            meta.uniquePaths = uniquePaths;
+        }
+    }
+    // Cast to generated type - Content API will need to be updated to handle
+    // the new pathTypes format with relationship info. Until then, it will
+    // ignore the extra fields but still receive the data for testing.
+    return Object.keys(meta).length > 0 ? {
+        meta: meta
+    } : {};
+}
+
+//# sourceMappingURL=buildMeta.js.map

package/dist/db-content-api/utilities/meta/buildPathTypes.d.ts

@@ -0,0 +1,17 @@
+import type { Payload, Where } from 'payload';
+import type { PathTypesRecord } from '../../temp-utilities/types.js';
+/**
+ * Builds pathTypes metadata for Content API request.
+ * Returns a record of paths with their types for proper query generation.
+ *
+ * Includes:
+ * - Array fields (type: "array")
+ * - Relationship fields (type: { type: "relationship", collection, hasMany })
+ * - Join fields (type: { type: "join", collection, hasMany, on })
+ *
+ * Localized array/blocks fields (stored as locale maps) are handled specially:
+ * - The localized field itself is NOT marked as 'array' (it's a locale map object)
+ * - The locale-specific path (e.g. "localizedBlocks.en") IS marked as 'array'
+ */
+export declare function buildPathTypes(payload: Payload, collectionSlug: string, where: undefined | Where): PathTypesRecord;
+//# sourceMappingURL=buildPathTypes.d.ts.map