@focus-reactive/payload-plugin-translator 0.4.0 → 0.5.1

package/dist/server/modules/task-runner/sync-runner/SyncRunnerProvider.d.ts

@@ -1,7 +1,7 @@
-import type { Config, Payload } from 'payload';
-import type { TaskRunner } from '../TaskRunner.interface';
-import type { TaskRunnerProvider, TaskRunnerContext } from '../TaskRunnerProvider.interface';
-import type { SyncRunnerOptions } from './types';
+import type { Config, Payload } from "payload";
+import type { TaskRunner } from "../TaskRunner.interface";
+import type { TaskRunnerProvider, TaskHandler } from "../TaskRunnerProvider.interface";
+import type { SyncRunnerOptions } from "./types";
 /**
  * Synchronous TaskRunnerProvider implementation.
  *
@@ -9,16 +9,24 @@ import type { SyncRunnerOptions } from './types';
  * Useful for development, testing, or simple use cases.
  */
 export declare class SyncRunnerProvider implements TaskRunnerProvider {
-    private handler?;
     private readonly tasks;
     constructor(options?: SyncRunnerOptions);
-    create(payload: Payload): TaskRunner;
-    configure(context: TaskRunnerContext): (config: Config) => Config;
+    create(payload: Payload, handler: TaskHandler): TaskRunner;
+    configure(): (config: Config) => Config;
 }
 /**
- * Creates a synchronous TaskRunnerProvider.
+ * Creates a synchronous task runner: translations execute inline on enqueue,
+ * with no Payload Jobs queue. Status is kept in an in-memory map (bounded by
+ * `maxSize`/`ttlMs`) and is **lost on server restart**, so this is best for
+ * development, tests, or simple single-process setups — not serverless. Pass the
+ * result as `translatorPlugin({ runner })`.
  *
- * Executes translations immediately without queuing.
- * Results are stored in memory and lost on server restart.
+ * @param options - In-memory store bounds: `maxSize` (default 100) and `ttlMs`
+ *   (default 1h) for completed/failed task records.
+ * @returns A {@link TaskRunnerProvider} for the plugin's `runner` option.
+ * @example
+ * ```ts
+ * translatorPlugin({ collections, translationProvider, runner: createSyncRunner() })
+ * ```
  */
 export declare function createSyncRunner(options?: SyncRunnerOptions): TaskRunnerProvider;

package/dist/server/modules/task-runner/sync-runner/SyncRunnerProvider.js

@@ -1,15 +1,13 @@
-import { SyncTaskRunner } from './SyncTaskRunner';
-import { LazyMap } from '../../../shared/utils';
+import { SyncTaskRunner } from "./SyncTaskRunner";
+import { LazyMap } from "../../../shared/utils";
 const DEFAULT_MAX_SIZE = 100;
-const DEFAULT_TTL_MS = 60 * 60 * 1000 // 1 hour
-;
+const DEFAULT_TTL_MS = 60 * 60 * 1000; // 1 hour
 /**
  * Synchronous TaskRunnerProvider implementation.
  *
  * Executes translations immediately without Payload Jobs.
  * Useful for development, testing, or simple use cases.
  */ export class SyncRunnerProvider {
-    handler;
     tasks;
     constructor(options){
         const maxSize = options?.maxSize ?? DEFAULT_MAX_SIZE;
@@ -17,24 +15,36 @@ const DEFAULT_TTL_MS = 60 * 60 * 1000 // 1 hour
         this.tasks = new LazyMap({
             maxSize,
             ttlMs,
-            isRemovable: (task)=>task.status === 'completed' || task.status === 'failed',
+            isRemovable: (task)=>task.status === "completed" || task.status === "failed",
             getTimestamp: (task)=>new Date(task.updatedAt).getTime()
         });
     }
-    create(payload) {
-        if (!this.handler) throw new Error('SyncRunnerProvider not configured. Call configure() first.');
-        return new SyncTaskRunner(payload, this.handler, this.tasks);
+    // SyncRunner executes the translation inline on enqueue, so it needs the
+    // handler at create time — taken from the caller-supplied argument rather than
+    // stashed on the instance during configure(). No ambient state, no ordering
+    // coupling: create() is a pure function of its arguments.
+    create(payload, handler) {
+        return new SyncTaskRunner(payload, handler, this.tasks);
     }
-    configure(context) {
-        this.handler = context.handler;
+    // No config changes needed — translations run synchronously, no Payload jobs.
+    configure() {
         return (config)=>config;
     }
 }
 /**
- * Creates a synchronous TaskRunnerProvider.
+ * Creates a synchronous task runner: translations execute inline on enqueue,
+ * with no Payload Jobs queue. Status is kept in an in-memory map (bounded by
+ * `maxSize`/`ttlMs`) and is **lost on server restart**, so this is best for
+ * development, tests, or simple single-process setups — not serverless. Pass the
+ * result as `translatorPlugin({ runner })`.
  *
- * Executes translations immediately without queuing.
- * Results are stored in memory and lost on server restart.
+ * @param options - In-memory store bounds: `maxSize` (default 100) and `ttlMs`
+ *   (default 1h) for completed/failed task records.
+ * @returns A {@link TaskRunnerProvider} for the plugin's `runner` option.
+ * @example
+ * ```ts
+ * translatorPlugin({ collections, translationProvider, runner: createSyncRunner() })
+ * ```
  */ export function createSyncRunner(options) {
     return new SyncRunnerProvider(options);
 }

package/dist/server/modules/translation-levels/PluginConfigBuilder.d.ts

@@ -0,0 +1,46 @@
+import type { CollectionConfig, Config, Endpoint } from "payload";
+import type { AccessGuard } from "../../../types/AccessGuard";
+import type { RawPayloadComponentExport } from "../../../client/shared/types/PayloadComponentExport";
+import type { TaskRunnerFactory } from "../task-runner";
+import type { CollectionAdminSlot, LevelContext } from "./types";
+type ConfigModifier = (config: Config) => Config;
+export type PluginConfigBuilderDeps = {
+    collections: CollectionConfig[];
+    basePath: string;
+    access?: AccessGuard;
+    taskRunnerFactory: TaskRunnerFactory;
+};
+/**
+ * The single place that mutates the Payload `config`. Levels (through the narrow
+ * {@link LevelContext}) and the plugin (through `addAdminProvider` /
+ * `addConfigModifier`) only *describe* their contributions; `applyTo(config)` is
+ * the one sink that writes them in. This keeps Payload's in-place-mutation style
+ * — including the lazy nested-config init — confined here, so `plugin.ts` and the
+ * levels stay free of direct config mutation.
+ *
+ * It implements {@link LevelContext}, so the same instance is what levels receive
+ * as their context (they see only `addEndpoints` / `addCollectionComponent`).
+ */
+export declare class PluginConfigBuilder implements LevelContext {
+    readonly collections: CollectionConfig[];
+    readonly basePath: string;
+    readonly access?: AccessGuard;
+    readonly taskRunnerFactory: TaskRunnerFactory;
+    private readonly endpoints;
+    private readonly collectionComponents;
+    private readonly adminProviders;
+    private readonly configModifiers;
+    constructor(deps: PluginConfigBuilderDeps);
+    addEndpoints(endpoints: Endpoint[]): void;
+    addCollectionComponent(slot: CollectionAdminSlot, make: (collection: CollectionConfig) => RawPayloadComponentExport): void;
+    /** Register a global admin provider (e.g. the client cache provider). */
+    addAdminProvider(provider: RawPayloadComponentExport): void;
+    /** Register a config modifier (e.g. the runner's jobs/autorun/onInit setup). */
+    addConfigModifier(modifier: ConfigModifier): void;
+    /** The one sink that writes every accumulated contribution into `config`. */
+    applyTo(config: Config): Config;
+    private attachAdminProviders;
+    private attachCollectionComponents;
+    private registerEndpoints;
+}
+export {};

package/dist/server/modules/translation-levels/PluginConfigBuilder.js

@@ -0,0 +1,108 @@
+const endpointKey = (endpoint)=>`${endpoint.method} ${endpoint.path}`;
+function attachToSlot(collection, slot, component) {
+    if (!collection.admin) collection.admin = {};
+    if (!collection.admin.components) collection.admin.components = {};
+    const components = collection.admin.components;
+    if (slot === "beforeDocumentControls") {
+        if (!components.edit) components.edit = {};
+        if (!components.edit.beforeDocumentControls) components.edit.beforeDocumentControls = [];
+        components.edit.beforeDocumentControls.push(component);
+        return;
+    }
+    if (slot === "beforeListTable") {
+        if (!components.beforeListTable) components.beforeListTable = [];
+        components.beforeListTable.push(component);
+        return;
+    }
+    // Exhaustiveness: a new CollectionAdminSlot must be handled above, not fall through.
+    slot;
+}
+/**
+ * The single place that mutates the Payload `config`. Levels (through the narrow
+ * {@link LevelContext}) and the plugin (through `addAdminProvider` /
+ * `addConfigModifier`) only *describe* their contributions; `applyTo(config)` is
+ * the one sink that writes them in. This keeps Payload's in-place-mutation style
+ * — including the lazy nested-config init — confined here, so `plugin.ts` and the
+ * levels stay free of direct config mutation.
+ *
+ * It implements {@link LevelContext}, so the same instance is what levels receive
+ * as their context (they see only `addEndpoints` / `addCollectionComponent`).
+ */ export class PluginConfigBuilder {
+    collections;
+    basePath;
+    access;
+    taskRunnerFactory;
+    endpoints = [];
+    collectionComponents = [];
+    adminProviders = [];
+    configModifiers = [];
+    constructor(deps){
+        this.collections = deps.collections;
+        this.basePath = deps.basePath;
+        this.access = deps.access;
+        this.taskRunnerFactory = deps.taskRunnerFactory;
+    }
+    addEndpoints(endpoints) {
+        this.endpoints.push(...endpoints);
+    }
+    addCollectionComponent(slot, make) {
+        this.collectionComponents.push({
+            slot,
+            make
+        });
+    }
+    /** Register a global admin provider (e.g. the client cache provider). */ addAdminProvider(provider) {
+        this.adminProviders.push(provider);
+    }
+    /** Register a config modifier (e.g. the runner's jobs/autorun/onInit setup). */ addConfigModifier(modifier) {
+        this.configModifiers.push(modifier);
+    }
+    /** The one sink that writes every accumulated contribution into `config`. */ applyTo(config) {
+        // Config modifiers first — a runner's modifier may return a fresh config
+        // object, so everything else must be applied to its result.
+        let result = config;
+        for (const modify of this.configModifiers)result = modify(result);
+        this.attachAdminProviders(result);
+        this.attachCollectionComponents(result);
+        this.registerEndpoints(result);
+        return result;
+    }
+    attachAdminProviders(config) {
+        if (this.adminProviders.length === 0) return;
+        if (!config.admin) config.admin = {};
+        if (!config.admin.components) config.admin.components = {};
+        if (!config.admin.components.providers) config.admin.components.providers = [];
+        // Not deduplicated. Unlike a duplicate endpoint (a route conflict), a
+        // duplicate admin provider is harmless, and providers have no reliable
+        // identity key across their shapes (`string | { path } | false`, with
+        // distinguishing `serverProps`). The single CacheProvider is added once per
+        // plugin instance.
+        config.admin.components.providers.push(...this.adminProviders);
+    }
+    attachCollectionComponents(config) {
+        if (this.collectionComponents.length === 0) return;
+        const managed = new Set(this.collections.map((collection)=>collection.slug));
+        config.collections?.forEach((collection)=>{
+            if (!managed.has(collection.slug)) return;
+            for (const { slot, make } of this.collectionComponents){
+                attachToSlot(collection, slot, make(collection));
+            }
+        });
+    }
+    registerEndpoints(config) {
+        if (this.endpoints.length === 0) return;
+        if (!config.endpoints) config.endpoints = [];
+        // Seed from endpoints already on the config so each (method, path) registers
+        // once — across the levels' contributions AND anything already present (e.g.
+        // the plugin registered twice, or a host route at the same path).
+        const seen = new Set(config.endpoints.map(endpointKey));
+        for (const endpoint of this.endpoints){
+            const key = endpointKey(endpoint);
+            if (seen.has(key)) continue;
+            seen.add(key);
+            config.endpoints.push(endpoint);
+        }
+    }
+}
+
+//# sourceMappingURL=PluginConfigBuilder.js.map

package/dist/server/modules/translation-levels/collectionLevel.d.ts

@@ -0,0 +1,15 @@
+import type { TranslationLevel } from "./types";
+/**
+ * Bulk collection translation: a dashboard on the list view (translate many
+ * documents at once), backed by the same shared document-translation API as
+ * {@link documentLevel}.
+ *
+ * @since 0.5.0
+ * @returns An opaque {@link TranslationLevel} to list in `translatorPlugin({ levels })`.
+ * @example
+ * ```ts
+ * // Enable only bulk collection translation (no per-document popup):
+ * translatorPlugin({ collections: [Posts], translationProvider, runner, levels: [collectionLevel()] })
+ * ```
+ */
+export declare function collectionLevel(): TranslationLevel;

package/dist/server/modules/translation-levels/collectionLevel.js

@@ -0,0 +1,24 @@
+import { BulkDocumentTranslationDashboard } from "../../../client/widgets/bulk-translation-dashboard/ui/BulkTranslationDashboard.export";
+import { useDocTranslationApi } from "./useDocTranslationApi";
+/**
+ * Bulk collection translation: a dashboard on the list view (translate many
+ * documents at once), backed by the same shared document-translation API as
+ * {@link documentLevel}.
+ *
+ * @since 0.5.0
+ * @returns An opaque {@link TranslationLevel} to list in `translatorPlugin({ levels })`.
+ * @example
+ * ```ts
+ * // Enable only bulk collection translation (no per-document popup):
+ * translatorPlugin({ collections: [Posts], translationProvider, runner, levels: [collectionLevel()] })
+ * ```
+ */ export function collectionLevel() {
+    return {
+        extend (ctx) {
+            useDocTranslationApi(ctx);
+            ctx.addCollectionComponent("beforeListTable", ()=>new BulkDocumentTranslationDashboard(ctx.access));
+        }
+    };
+}
+
+//# sourceMappingURL=collectionLevel.js.map

package/dist/server/modules/translation-levels/documentLevel.d.ts

@@ -0,0 +1,19 @@
+import type { TranslationLevel } from "./types";
+/**
+ * Per-document translation: a popup control on the document edit view, backed by
+ * the shared document-translation API (async/job by default; synchronous if the
+ * configured `runner` is a sync runner).
+ *
+ * @since 0.5.0
+ * @returns An opaque {@link TranslationLevel} to list in `translatorPlugin({ levels })`.
+ * @example
+ * ```ts
+ * translatorPlugin({
+ *   collections: [Posts],
+ *   translationProvider,
+ *   runner: createPayloadJobsRunner(),
+ *   levels: [documentLevel(), collectionLevel()], // this is the default — omit for the same result
+ * })
+ * ```
+ */
+export declare function documentLevel(): TranslationLevel;

package/dist/server/modules/translation-levels/documentLevel.js

@@ -0,0 +1,28 @@
+import { TranslateDocumentExport } from "../../../client/widgets/translate-document";
+import { useDocTranslationApi } from "./useDocTranslationApi";
+/**
+ * Per-document translation: a popup control on the document edit view, backed by
+ * the shared document-translation API (async/job by default; synchronous if the
+ * configured `runner` is a sync runner).
+ *
+ * @since 0.5.0
+ * @returns An opaque {@link TranslationLevel} to list in `translatorPlugin({ levels })`.
+ * @example
+ * ```ts
+ * translatorPlugin({
+ *   collections: [Posts],
+ *   translationProvider,
+ *   runner: createPayloadJobsRunner(),
+ *   levels: [documentLevel(), collectionLevel()], // this is the default — omit for the same result
+ * })
+ * ```
+ */ export function documentLevel() {
+    return {
+        extend (ctx) {
+            useDocTranslationApi(ctx);
+            ctx.addCollectionComponent("beforeDocumentControls", (collection)=>new TranslateDocumentExport(collection, ctx.access));
+        }
+    };
+}
+
+//# sourceMappingURL=documentLevel.js.map

package/dist/server/modules/translation-levels/index.d.ts

@@ -0,0 +1,3 @@
+export type { TranslationLevel } from "./types";
+export { documentLevel } from "./documentLevel";
+export { collectionLevel } from "./collectionLevel";

package/dist/server/modules/translation-levels/index.js

@@ -0,0 +1,4 @@
+export { documentLevel } from "./documentLevel";
+export { collectionLevel } from "./collectionLevel";
+
+//# sourceMappingURL=index.js.map

package/dist/server/modules/translation-levels/types.d.ts

@@ -0,0 +1,42 @@
+import type { CollectionConfig, Endpoint } from "payload";
+import type { AccessGuard } from "../../../types/AccessGuard";
+import type { RawPayloadComponentExport } from "../../../client/shared/types/PayloadComponentExport";
+import type { TaskRunnerFactory } from "../task-runner";
+export type CollectionAdminSlot = "beforeDocumentControls" | "beforeListTable";
+/**
+ * A composable translation surface (document / collection / field).
+ *
+ * Treat it as an **opaque value**: create one with `documentLevel()` /
+ * `collectionLevel()` (and, later, `fieldLevel()`) and list it in
+ * `translatorPlugin({ levels })`. It is produced only by those built-in
+ * factories — not externally implementable yet, since {@link LevelContext} is
+ * intentionally not exported. Opening it later (export `LevelContext`, drop the
+ * `@internal` tag) is additive and non-breaking.
+ *
+ * @since 0.5.0
+ */
+export interface TranslationLevel {
+    /**
+     * Not a stable contract yet — produce via the level factories.
+     * @internal
+     */
+    extend(ctx: LevelContext): void;
+}
+/**
+ * Public-ready shape, kept internal until external levels are needed.
+ *
+ * A level contributes via these generic primitives; it never mutates the raw
+ * Payload config. The plugin deduplicates endpoints by method + path on apply.
+ * (fieldLevel — Phase 2 — will also read `schemaMap` + `translationProvider`.)
+ * @internal
+ */
+export interface LevelContext {
+    readonly collections: CollectionConfig[];
+    readonly basePath: string;
+    readonly access?: AccessGuard;
+    readonly taskRunnerFactory: TaskRunnerFactory;
+    /** Register endpoints. Deduplicated by method + path when applied. */
+    addEndpoints(endpoints: Endpoint[]): void;
+    /** Attach an admin component to a slot on every managed collection. */
+    addCollectionComponent(slot: CollectionAdminSlot, make: (collection: CollectionConfig) => RawPayloadComponentExport): void;
+}

package/dist/server/modules/translation-levels/types.js

@@ -0,0 +1,10 @@
+/**
+ * Public-ready shape, kept internal until external levels are needed.
+ *
+ * A level contributes via these generic primitives; it never mutates the raw
+ * Payload config. The plugin deduplicates endpoints by method + path on apply.
+ * (fieldLevel — Phase 2 — will also read `schemaMap` + `translationProvider`.)
+ * @internal
+ */ export { };
+
+//# sourceMappingURL=types.js.map

package/dist/server/modules/translation-levels/useDocTranslationApi.d.ts

@@ -0,0 +1,8 @@
+import type { LevelContext } from "./types";
+/**
+ * Contribute the runner-agnostic document-translation API — the shared 6-route
+ * bundle, bound to the level context's runner. Both `documentLevel` and
+ * `collectionLevel` call this; the plugin deduplicates the endpoints by method +
+ * path, so the bundle registers exactly once.
+ */
+export declare function useDocTranslationApi(ctx: LevelContext): void;

package/dist/server/modules/translation-levels/useDocTranslationApi.js

@@ -0,0 +1,18 @@
+import { createTranslationRoutes } from "../../features/createTranslationRoutes";
+/**
+ * Contribute the runner-agnostic document-translation API — the shared 6-route
+ * bundle, bound to the level context's runner. Both `documentLevel` and
+ * `collectionLevel` call this; the plugin deduplicates the endpoints by method +
+ * path, so the bundle registers exactly once.
+ */ export function useDocTranslationApi(ctx) {
+    ctx.addEndpoints(createTranslationRoutes({
+        taskRunnerFactory: ctx.taskRunnerFactory,
+        collectionConfig: {
+            availableCollections: new Set(ctx.collections.map((collection)=>collection.slug))
+        },
+        access: ctx.access,
+        basePath: ctx.basePath
+    }));
+}
+
+//# sourceMappingURL=useDocTranslationApi.js.map

package/dist/server/modules/translation-pipeline/index.d.ts

@@ -1,3 +1,5 @@
-export { TranslationPipeline } from './TranslationPipeline';
-export type { TranslationStrategy } from './strategies';
-export { OverwriteStrategy, SkipExistingStrategy } from './strategies';
+export { TranslationPipeline } from "./TranslationPipeline";
+export { translateContent } from "./translateContent";
+export type { TranslateContentArgs } from "./translateContent";
+export type { TranslationStrategy } from "./strategies";
+export { OverwriteStrategy, SkipExistingStrategy } from "./strategies";

package/dist/server/modules/translation-pipeline/index.js

@@ -1,4 +1,5 @@
-export { TranslationPipeline } from './TranslationPipeline';
-export { OverwriteStrategy, SkipExistingStrategy } from './strategies';
+export { TranslationPipeline } from "./TranslationPipeline";
+export { translateContent } from "./translateContent";
+export { OverwriteStrategy, SkipExistingStrategy } from "./strategies";
 
 //# sourceMappingURL=index.js.map

package/dist/server/modules/translation-pipeline/stages/data-reconciler/DataReconciler.d.ts

@@ -1,11 +1,7 @@
-import type { Field } from 'payload';
+import type { Field } from "payload";
 /**
- * Deep merges source and target data with target priority.
- * Creates full document shape needed for Payload validation.
- *
- * Logic:
- * - If targetValue exists and is not empty → use targetValue
- * - Otherwise → use sourceValue
+ * Deep-merges source and target data with target priority, producing the full document shape
+ * Payload validation needs. Built on the shared {@link walkFields} engine.
  *
  * Stage 1 of the translation pipeline.
  */
@@ -14,12 +10,10 @@ export declare class DataReconciler {
     constructor(schema: Field[]);
     /**
      * Reconciles source and target data into a complete document shape.
-     * The result contains all fields needed for Payload validation.
      *
      * @param sourceData - Source locale document data
      * @param targetData - Target locale document data (may be empty/partial)
      * @returns Complete document shape with reconciled field values
      */
     reconcile(sourceData: Record<string, unknown>, targetData: Record<string, unknown>): Record<string, unknown>;
-    private reconcileFields;
 }