@purposeinplay/payload-ai-translate 0.1.0

package/dist/client/excluded-fields-field.js

@@ -0,0 +1,553 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useConfig, useField, useFormFields } from '@payloadcms/ui';
+import { formatAdminURL } from 'payload/shared';
+import { useCallback, useEffect, useMemo, useState } from 'react';
+// Lightweight module-level cache of the client-config response. The
+// component re-mounts on every row collapse/expand in the array UI,
+// and fetching the same payload N times per page render is a waste —
+// every row in `perCollection` needs the SAME map. TTL is intentionally
+// long (5 min) because the map only changes when a developer adds/
+// removes localized fields and restarts the server; admins editing the
+// settings global don't affect it.
+const CLIENT_CONFIG_TTL_MS = 5 * 60 * 1000;
+let cached = null;
+let inFlight = null;
+async function fetchTranslatableFieldsBySlug(url) {
+    const now = Date.now();
+    if (cached && cached.expiresAt > now) return cached.value;
+    if (inFlight) return inFlight;
+    inFlight = (async ()=>{
+        try {
+            const res = await fetch(url, {
+                credentials: 'include'
+            });
+            if (!res.ok) return {};
+            const data = await res.json();
+            const map = data.translatableFieldsBySlug ?? {};
+            cached = {
+                value: map,
+                expiresAt: Date.now() + CLIENT_CONFIG_TTL_MS
+            };
+            return map;
+        } catch  {
+            // Don't cache failures — let the next mount retry.
+            return {};
+        } finally{
+            inFlight = null;
+        }
+    })();
+    return inFlight;
+}
+/**
+ * Custom admin component for `perCollection[i].excludedFieldPaths`.
+ *
+ * Stores an exclude-list (top-level field paths the admin opted OUT of
+ * translation). Rendered as a grouped list — one checkbox per
+ * top-level field on the surface. Unchecking a top-level field
+ * excludes EVERY descendant path under it (prefix-match in
+ * `isPathExcluded`).
+ *
+ * Design rationale:
+ *
+ * 1. **Editor mental model.** Editors think in terms of the fields
+ *    they see in the doc editor ("Layout", "Meta"), not internal dot-
+ *    paths. The earlier flat list of paths like
+ *    `layout.columns.link.label` was technically correct but useless
+ *    for non-developers.
+ * 2. **One checkbox per top-level field.** Coarse but predictable:
+ *    "uncheck Layout" → nothing under `layout.*` is translated.
+ *    Per-leaf exclusions are still expressible via direct DB writes
+ *    or future per-field controls if needed; the common case is
+ *    coverage at the section level.
+ * 3. **Disclosure of details.** A collapsible "Show 14 sub-paths"
+ *    affordance reveals every descendant path the resolver found, so
+ *    a developer / careful editor can verify what's actually
+ *    affected. Read-only — not interactive.
+ * 4. **Exclude-list semantics.** Default = empty array = translate
+ *    everything. New localized fields added later start "checked"
+ *    automatically.
+ *
+ * Sibling slug derivation: Payload doesn't give the component direct
+ * access to its row neighbours, so we strip the trailing
+ * `.excludedFieldPaths` segment from `path` and append `.slug` to
+ * address the sibling.
+ */ export function ExcludedFieldsField({ path }) {
+    // `text hasMany` value is `string[]` (or null/undefined when unset).
+    const { value, setValue } = useField({
+        path
+    });
+    // Respect both `routes.api` AND Next.js `basePath` (e.g. blog-wild
+    // mounts everything under `/blog`, so the api lives at
+    // `/blog/api/...`). `formatAdminURL` reads `NEXT_BASE_PATH` and
+    // prepends it; using a raw fetch with `apiRoute` alone 404s in
+    // basePath setups.
+    const { config } = useConfig();
+    const apiRoute = config.routes?.api ?? '/api';
+    const endpointUrl = useMemo(()=>formatAdminURL({
+            apiRoute,
+            path: '/ai-translate/client-config',
+            serverURL: ''
+        }), [
+        apiRoute
+    ]);
+    // Sibling `slug` value, read from the form state. `useFormFields`
+    // re-renders when the selected value changes — so the widget
+    // updates as soon as the admin picks a slug from the dropdown.
+    const siblingSlugPath = useMemo(()=>path.replace(/\.excludedFieldPaths$/, '.slug'), [
+        path
+    ]);
+    const slug = useFormFields(([fields])=>fields?.[siblingSlugPath]?.value);
+    const [map, setMap] = useState(null);
+    const [loading, setLoading] = useState(true);
+    useEffect(()=>{
+        let alive = true;
+        fetchTranslatableFieldsBySlug(endpointUrl).then((m)=>{
+            if (alive) {
+                setMap(m);
+                setLoading(false);
+            }
+        });
+        return ()=>{
+            alive = false;
+        };
+    }, [
+        endpointUrl
+    ]);
+    const availablePaths = useMemo(()=>{
+        if (!slug || !map) return null;
+        return map[slug] ?? [];
+    }, [
+        slug,
+        map
+    ]);
+    // Group paths by their first segment. Each group becomes a single
+    // checkbox row — that's the editor's unit of control. Children
+    // surface in the disclosure under each group for transparency.
+    const groups = useMemo(()=>{
+        if (!availablePaths) return null;
+        const byTop = new Map();
+        for (const p of availablePaths){
+            const top = p.split('.')[0];
+            const list = byTop.get(top) ?? [];
+            list.push(p);
+            byTop.set(top, list);
+        }
+        return [
+            ...byTop.entries()
+        ].sort(([a], [b])=>a.localeCompare(b)).map(([top, paths])=>({
+                top,
+                paths
+            }));
+    }, [
+        availablePaths
+    ]);
+    const excluded = useMemo(()=>new Set(Array.isArray(value) ? value.filter((v)=>typeof v === 'string') : []), [
+        value
+    ]);
+    // Top-level checkbox: storing the parent path (e.g. `layout`) is all
+    // we need — the API filter does prefix matching, so excluding
+    // `layout` covers `layout.columns.richText` etc. automatically.
+    //
+    // BUG-06 fix: pre-fix, adding a parent path silently DELETED any
+    // descendant entries the admin had specifically configured. Toggling
+    // the parent off then permanently destroyed that fine-grained
+    // intent. Now we PRESERVE descendants — the parent's prefix-match
+    // is the primary effect, but descendant entries stay in storage so
+    // unchecking the parent restores the previous specific state.
+    const handleToggleTop = useCallback((topPath)=>{
+        const next = new Set(excluded);
+        if (next.has(topPath)) {
+            next.delete(topPath);
+        } else {
+            next.add(topPath);
+        // BUG-06: do NOT delete descendants. Prefix-match makes them
+        // redundant for the filter's purposes, but the entries are
+        // the admin's recorded intent. Keeping them lets unchecking
+        // the parent reveal the original fine-grained state.
+        }
+        // Normalize empty -> null so the DB row keeps an empty array
+        // instead of an explicit-empty marker. Both are semantically
+        // identical downstream, but `null` round-trips cleaner.
+        setValue(next.size === 0 ? null : [
+            ...next
+        ]);
+    }, [
+        excluded,
+        setValue
+    ]);
+    const handleSelectAll = useCallback(()=>{
+        setValue(null);
+    }, [
+        setValue
+    ]);
+    // BUG-07 fix: pre-fix, "Exclude all" REPLACED the whole set with just
+    // top-level paths, wiping any fine-grained entries the admin had
+    // configured. Now it ADDS top-level paths to the existing set —
+    // descendants survive so the original specificity is preserved.
+    const handleExcludeAll = useCallback(()=>{
+        if (!groups || groups.length === 0) return;
+        const next = new Set(excluded);
+        for (const g of groups)next.add(g.top);
+        setValue(next.size === 0 ? null : [
+            ...next
+        ]);
+    }, [
+        groups,
+        excluded,
+        setValue
+    ]);
+    // --- Empty / loading states ---
+    if (!slug) {
+        return /*#__PURE__*/ _jsx(Wrapper, {
+            children: /*#__PURE__*/ _jsx("p", {
+                style: mutedStyle,
+                children: "Select a slug above and the translatable fields for that collection will appear here."
+            })
+        });
+    }
+    if (loading || !map) {
+        return /*#__PURE__*/ _jsx(Wrapper, {
+            children: /*#__PURE__*/ _jsx("p", {
+                style: mutedStyle,
+                children: "Loading available fields…"
+            })
+        });
+    }
+    if (!groups || groups.length === 0) {
+        return /*#__PURE__*/ _jsx(Wrapper, {
+            children: /*#__PURE__*/ _jsxs("p", {
+                style: mutedStyle,
+                children: [
+                    'No translatable fields found for "',
+                    slug,
+                    '". A field needs',
+                    ' ',
+                    /*#__PURE__*/ _jsx("code", {
+                        style: inlineCodeStyle,
+                        children: "localized: true"
+                    }),
+                    " in its config to appear here."
+                ]
+            })
+        });
+    }
+    // Stale top-level entries — excluded paths that no longer exist as
+    // top-level fields on the surface. Survive a schema rename so the
+    // admin can clean them up without DB access.
+    const knownTops = new Set(groups.map((g)=>g.top));
+    const staleEntries = [
+        ...excluded
+    ].filter((p)=>{
+        const top = p.split('.')[0];
+        return !knownTops.has(top);
+    });
+    // BUG-09 fix: surface deeper-than-top-level exclusions in the UI.
+    // Pre-fix, paths like `layout.columns.richText` were invisible —
+    // the widget grouped only on top segment, so admins debugging
+    // "why isn't this translating?" had no way to discover the deep
+    // entry. Now we show them explicitly under an "Advanced path
+    // exclusions" section.
+    const deepEntries = [
+        ...excluded
+    ].filter((p)=>{
+        const top = p.split('.')[0];
+        return knownTops.has(top) && p.includes('.');
+    });
+    const removeDeepEntry = (path)=>{
+        const next = new Set(excluded);
+        next.delete(path);
+        setValue(next.size === 0 ? null : [
+            ...next
+        ]);
+    };
+    return /*#__PURE__*/ _jsxs(Wrapper, {
+        children: [
+            /*#__PURE__*/ _jsxs("p", {
+                style: mutedStyle,
+                children: [
+                    "Pick which top-level fields get translated for this surface. Unchecked fields are",
+                    ' ',
+                    /*#__PURE__*/ _jsx("strong", {
+                        children: "excluded from all translation"
+                    }),
+                    " — both auto-translate on publish and the manual Translate… dialog. Defaults to every field being translated."
+                ]
+            }),
+            /*#__PURE__*/ _jsxs("div", {
+                style: actionsRowStyle,
+                children: [
+                    /*#__PURE__*/ _jsx("button", {
+                        type: "button",
+                        onClick: handleSelectAll,
+                        style: linkButtonStyle,
+                        children: "Translate all"
+                    }),
+                    /*#__PURE__*/ _jsx("span", {
+                        style: dividerStyle,
+                        "aria-hidden": true,
+                        children: "·"
+                    }),
+                    /*#__PURE__*/ _jsx("button", {
+                        type: "button",
+                        onClick: handleExcludeAll,
+                        style: linkButtonStyle,
+                        children: "Exclude all"
+                    })
+                ]
+            }),
+            /*#__PURE__*/ _jsx("ul", {
+                style: listStyle,
+                children: groups.map(({ top, paths })=>/*#__PURE__*/ _jsx(GroupRow, {
+                        top: top,
+                        paths: paths,
+                        excluded: excluded.has(top),
+                        onToggle: handleToggleTop
+                    }, top))
+            }),
+            deepEntries.length > 0 && /*#__PURE__*/ _jsxs("details", {
+                style: staleDetailsStyle,
+                children: [
+                    /*#__PURE__*/ _jsxs("summary", {
+                        style: staleSummaryStyle,
+                        children: [
+                            deepEntries.length,
+                            " advanced path exclusion",
+                            deepEntries.length === 1 ? '' : 's',
+                            " below top level (BUG-09)"
+                        ]
+                    }),
+                    /*#__PURE__*/ _jsx("p", {
+                        style: mutedStyle,
+                        children: "These nested paths exclude specific fields below their top-level parent. They were written via SQL, migration, or an earlier version of this widget — and remain in effect independently of the top-level checkboxes above. Remove individual entries if you want to translate them."
+                    }),
+                    /*#__PURE__*/ _jsx("ul", {
+                        style: staleListStyle,
+                        children: deepEntries.map((deep)=>/*#__PURE__*/ _jsxs("li", {
+                                style: staleItemStyle,
+                                children: [
+                                    /*#__PURE__*/ _jsx("code", {
+                                        style: inlineCodeStyle,
+                                        children: deep
+                                    }),
+                                    /*#__PURE__*/ _jsx("button", {
+                                        type: "button",
+                                        onClick: ()=>removeDeepEntry(deep),
+                                        style: {
+                                            ...linkButtonStyle,
+                                            marginLeft: '0.75rem'
+                                        },
+                                        "aria-label": `Remove advanced exclusion ${deep}`,
+                                        children: "remove"
+                                    })
+                                ]
+                            }, deep))
+                    })
+                ]
+            }),
+            staleEntries.length > 0 && /*#__PURE__*/ _jsxs("details", {
+                style: staleDetailsStyle,
+                children: [
+                    /*#__PURE__*/ _jsxs("summary", {
+                        style: staleSummaryStyle,
+                        children: [
+                            staleEntries.length,
+                            " stored exclusion",
+                            staleEntries.length === 1 ? '' : 's',
+                            " no longer present on this surface"
+                        ]
+                    }),
+                    /*#__PURE__*/ _jsx("ul", {
+                        style: staleListStyle,
+                        children: staleEntries.map((stale)=>/*#__PURE__*/ _jsx("li", {
+                                style: staleItemStyle,
+                                children: /*#__PURE__*/ _jsx("code", {
+                                    style: inlineCodeStyle,
+                                    children: stale
+                                })
+                            }, stale))
+                    })
+                ]
+            })
+        ]
+    });
+}
+function Wrapper({ children }) {
+    return /*#__PURE__*/ _jsxs("div", {
+        className: "field-type",
+        children: [
+            /*#__PURE__*/ _jsx("label", {
+                className: "field-label",
+                children: "Translated fields"
+            }),
+            children
+        ]
+    });
+}
+function GroupRow({ top, paths, excluded, onToggle }) {
+    // Only show the disclosure when there's actually descendant info to
+    // disclose. A flat top-level field (e.g. `title`) has only one
+    // path — itself — and showing "1 sub-path: title" is just noise.
+    const hasChildren = paths.some((p)=>p !== top);
+    return /*#__PURE__*/ _jsxs("li", {
+        style: groupItemStyle,
+        children: [
+            /*#__PURE__*/ _jsxs("label", {
+                style: labelRowStyle,
+                children: [
+                    /*#__PURE__*/ _jsx("input", {
+                        type: "checkbox",
+                        checked: !excluded,
+                        onChange: ()=>onToggle(top)
+                    }),
+                    /*#__PURE__*/ _jsx("span", {
+                        style: groupNameStyle,
+                        children: humanize(top)
+                    }),
+                    /*#__PURE__*/ _jsx("code", {
+                        style: inlineCodeStyle,
+                        children: top
+                    })
+                ]
+            }),
+            hasChildren && /*#__PURE__*/ _jsxs("details", {
+                style: disclosureStyle,
+                children: [
+                    /*#__PURE__*/ _jsxs("summary", {
+                        style: disclosureSummaryStyle,
+                        children: [
+                            "Show ",
+                            paths.length,
+                            " field path",
+                            paths.length === 1 ? '' : 's',
+                            " covered"
+                        ]
+                    }),
+                    /*#__PURE__*/ _jsx("ul", {
+                        style: pathListStyle,
+                        children: paths.map((p)=>/*#__PURE__*/ _jsx("li", {
+                                style: pathListItemStyle,
+                                children: /*#__PURE__*/ _jsx("code", {
+                                    style: inlineCodeStyle,
+                                    children: p
+                                })
+                            }, p))
+                    })
+                ]
+            })
+        ]
+    });
+}
+/**
+ * Turn a kebab/snake/camel field name into a human label.
+ * `metaTitle` -> `Meta Title`. `social_links` -> `Social Links`.
+ * `meta-data` -> `Meta Data`.
+ *
+ * Best-effort only — Payload field labels can be arbitrary strings or
+ * functions in the field config. Exposing them through the public
+ * client-config endpoint would mean expanding the API contract; this
+ * heuristic covers 90% of cases for the common camelCase / snake_case
+ * patterns Payload generates by default.
+ */ function humanize(name) {
+    return name.replace(/[-_]+/g, ' ').replace(/([a-z])([A-Z])/g, '$1 $2').replace(/\b\w/g, (c)=>c.toUpperCase());
+}
+// ---------------------------------------------------------------------------
+// Inline styles — keeps the component zero-dep on consumer CSS. Uses
+// Payload's CSS custom properties so the widget matches the active
+// theme (light/dark) without an additional stylesheet import.
+// ---------------------------------------------------------------------------
+const mutedStyle = {
+    color: 'var(--theme-elevation-500)',
+    fontSize: '0.85em',
+    margin: '0.25em 0 0.75em'
+};
+const actionsRowStyle = {
+    display: 'flex',
+    alignItems: 'center',
+    gap: '0.5em',
+    margin: '0 0 0.5em',
+    fontSize: '0.85em'
+};
+const linkButtonStyle = {
+    background: 'none',
+    border: 'none',
+    color: 'var(--theme-text)',
+    cursor: 'pointer',
+    padding: 0,
+    textDecoration: 'underline',
+    font: 'inherit'
+};
+const dividerStyle = {
+    color: 'var(--theme-elevation-400)'
+};
+const listStyle = {
+    listStyle: 'none',
+    margin: 0,
+    padding: '0.5em',
+    border: '1px solid var(--theme-elevation-150)',
+    borderRadius: '4px',
+    maxHeight: '420px',
+    overflowY: 'auto'
+};
+const groupItemStyle = {
+    padding: '0.4em 0',
+    borderBottom: '1px solid var(--theme-elevation-100)'
+};
+const labelRowStyle = {
+    display: 'flex',
+    alignItems: 'center',
+    gap: '0.5em',
+    cursor: 'pointer'
+};
+const groupNameStyle = {
+    fontWeight: 500
+};
+const inlineCodeStyle = {
+    fontFamily: 'var(--font-mono, monospace)',
+    fontSize: '0.8em',
+    color: 'var(--theme-elevation-500)',
+    background: 'var(--theme-elevation-100)',
+    padding: '0.05em 0.4em',
+    borderRadius: '3px'
+};
+const disclosureStyle = {
+    marginTop: '0.3em',
+    marginLeft: '1.6em',
+    fontSize: '0.85em'
+};
+const disclosureSummaryStyle = {
+    cursor: 'pointer',
+    color: 'var(--theme-elevation-500)',
+    userSelect: 'none'
+};
+const pathListStyle = {
+    listStyle: 'none',
+    margin: '0.3em 0 0',
+    padding: 0,
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '0.15em'
+};
+const pathListItemStyle = {
+    paddingLeft: '0.4em'
+};
+const staleDetailsStyle = {
+    marginTop: '0.75em',
+    fontSize: '0.85em'
+};
+const staleSummaryStyle = {
+    cursor: 'pointer',
+    color: 'var(--theme-warning-700, var(--theme-elevation-500))',
+    userSelect: 'none'
+};
+const staleListStyle = {
+    listStyle: 'none',
+    margin: '0.3em 0 0',
+    padding: 0,
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '0.15em'
+};
+const staleItemStyle = {
+    paddingLeft: '1em'
+};

package/dist/client/field-translate-button.d.ts

@@ -0,0 +1,6 @@
+import type React from 'react';
+type FieldTranslateButtonProps = {
+    path: string;
+};
+export declare function FieldTranslateButton(props: FieldTranslateButtonProps): React.JSX.Element;
+export {};