gt-sanity 2.0.21 → 2.1.0

package/src/index.ts

@@ -1,10 +1,35 @@
+import type { PortableTextHtmlComponents } from '@portabletext/to-html';
+import { getLocaleProperties } from 'generaltranslation';
+import { libraryDefaultLocale } from 'generaltranslation/internal';
+import { definePlugin } from 'sanity';
+import { route } from 'sanity/router';
+import { translateAction } from './actions/translateAction';
+import { gt, pluginConfig } from './adapter/core';
+import type {
+  DedupeFields,
+  IgnoreFields,
+  SkipFields,
+  TranslateDocumentFilter,
+  FieldLevelTranslationMode,
+} from './adapter/types';
+import {
+  createInternationalizedArrayTypes,
+  resolveFieldLevelConfig,
+} from './schema/createInternationalizedArrayTypes';
+import type { GTFieldLevelLocalizationConfig } from './schema/types';
+import TranslationsTool from './components/page/TranslationsTool';
+import { documentInternationalization } from './documentInternationalization';
+import type { CustomDeserializers } from './serialization/types';
+import { SECRETS_NAMESPACE } from './utils/shared';
+
+// ===== Document Internationalization ===== //
 export {
-  documentInternationalization,
   useDocumentInternationalizationContext,
   DocumentInternationalizationMenu,
   useDeleteTranslationAction,
   useDuplicateWithTranslationsAction,
 } from './documentInternationalization';
+export { documentInternationalization };
 export type {
   DocumentInternationalizationConfig,
   Language,
@@ -12,26 +37,18 @@ export type {
   TranslationReference,
 } from './documentInternationalization';
 
-import TranslationsTab from './components/tab/TranslationsTab';
-import {
-  Secrets,
-  Adapter,
-  ExportForTranslation,
-  ImportTranslation,
-  TranslationFunctionContext,
-  TranslationsTabConfigOptions,
-} from './types';
-import { findLatestDraft } from './configuration/utils/findLatestDraft';
-import {
-  BaseDocumentSerializer,
-  BaseDocumentDeserializer,
-  BaseDocumentMerger,
+// ===== Serialization Helpers ===== //
+export { default as TranslationsTab } from './components/tab/TranslationsTab';
+export { findLatestDraft } from './configuration/utils/findLatestDraft';
+export { BaseDocumentSerializer } from './serialization/serialize/index';
+export { BaseDocumentDeserializer } from './serialization/deserialize/BaseDocumentDeserializer';
+export { BaseDocumentMerger } from './serialization/BaseDocumentMerger';
+export {
   defaultStopTypes,
   customSerializers,
-  SerializedDocument,
-} from './serialization';
-import { translateAction } from './actions/translateAction';
-
+} from './serialization/BaseSerializationConfig';
+export { attachGTData, detachGTData } from './serialization/data';
+export { translateAction };
 export type {
   Secrets,
   Adapter,
@@ -39,39 +56,17 @@ export type {
   ImportTranslation,
   TranslationFunctionContext,
   TranslationsTabConfigOptions,
-  SerializedDocument,
-};
-export {
-  TranslationsTab,
-  translateAction,
-  //helpers for end developers who may need to customize serialization
-  findLatestDraft,
-  BaseDocumentSerializer,
-  BaseDocumentDeserializer,
-  BaseDocumentMerger,
-  defaultStopTypes,
-  customSerializers,
-  attachGTData,
-  detachGTData,
-};
+} from './types';
+export type { SerializedDocument } from './serialization/types';
 
-import { definePlugin } from 'sanity';
-import { route } from 'sanity/router';
-import { gt, pluginConfig } from './adapter/core';
-import { libraryDefaultLocale } from 'generaltranslation/internal';
-import { getLocaleProperties } from 'generaltranslation';
-import type {
-  DedupeFields,
-  IgnoreFields,
-  SkipFields,
-  TranslateDocumentFilter,
-} from './adapter/types';
-import TranslationsTool from './components/page/TranslationsTool';
-import { SECRETS_NAMESPACE } from './utils/shared';
-import type { PortableTextHtmlComponents } from '@portabletext/to-html';
-import { attachGTData, detachGTData } from './serialization/data';
-import { documentInternationalization } from './documentInternationalization';
-import type { CustomDeserializers } from './serialization';
+// ===== Field-Level (Internationalized Array) Localization ===== //
+export { createInternationalizedArrayTypes };
+export type {
+  GTFieldLevelLocalizationConfig,
+  FieldLevelFieldType,
+  FieldLevelUIComponents,
+} from './schema/types';
+export type { FieldLevelTranslationMode };
 
 export type GTPluginConfig = Omit<
   Parameters<typeof gt.setConfig>[0],
@@ -98,6 +93,18 @@ export type GTPluginConfig = Omit<
   // with language badges, translation menu, and per-language templates.
   // Requires translateDocuments to specify which document types to enable translations for.
   showDocumentInternationalization?: boolean;
+  // Field-level (internationalized-array) localization. Generates
+  // `internationalizedArray*` schema types + input components when enabled.
+  // `fieldLevelLocalization` is a descriptive alias for the same config.
+  internationalizedArray?: GTFieldLevelLocalizationConfig;
+  fieldLevelLocalization?: GTFieldLevelLocalizationConfig;
+  // How matched documents are translated. Independent from schema generation:
+  // enabling `internationalizedArray` only adds editable fields; routing
+  // translation through the array path requires opting in here. Default 'document'.
+  translationLevel?: FieldLevelTranslationMode;
+  // In 'mixed' mode, the document types that use the internationalized-array
+  // strategy; everything else stays document-level.
+  fieldLevelDocuments?: TranslateDocumentFilter[] | string[];
 };
 
 /**
@@ -134,18 +141,31 @@ export const gtPlugin = definePlugin<GTPluginConfig>(
     additionalDeserializers = {},
     additionalBlockDeserializers = [],
     showDocumentInternationalization = true,
+    internationalizedArray,
+    fieldLevelLocalization,
+    translationLevel = 'document',
+    fieldLevelDocuments,
   }) => {
     // Resolve sourceLocale: explicit sourceLocale > defaultLocale (from gt.config.json) > library default
     const resolvedSourceLocale =
       sourceLocale ?? defaultLocale ?? libraryDefaultLocale;
 
     // Normalize translateDocuments: string[] → TranslateDocumentFilter[]
-    let normalizedTranslateDocuments: TranslateDocumentFilter[] | undefined;
-    if (translateDocuments) {
-      normalizedTranslateDocuments = translateDocuments
-        .map((entry) => (typeof entry === 'string' ? { type: entry } : entry))
+    const normalizeFilters = (
+      entries: (TranslateDocumentFilter | string)[] | undefined
+    ): TranslateDocumentFilter[] | undefined =>
+      entries
+        ?.map((entry) => (typeof entry === 'string' ? { type: entry } : entry))
         .filter((filter) => filter.documentId || filter.type);
-    }
+
+    const normalizedTranslateDocuments = normalizeFilters(translateDocuments);
+    const normalizedFieldLevelDocuments =
+      normalizeFilters(fieldLevelDocuments) ?? [];
+
+    // `internationalizedArray` and `fieldLevelLocalization` are aliases.
+    const fieldLevelConfig = resolveFieldLevelConfig(
+      internationalizedArray ?? fieldLevelLocalization
+    );
 
     pluginConfig.init(
       secretsNamespace,
@@ -163,7 +183,10 @@ export const gtPlugin = definePlugin<GTPluginConfig>(
       additionalStopTypes,
       additionalSerializers,
       additionalDeserializers,
-      additionalBlockDeserializers
+      additionalBlockDeserializers,
+      translationLevel,
+      normalizedFieldLevelDocuments,
+      fieldLevelConfig.typePrefix
     );
     gt.setConfig({
       sourceLocale: resolvedSourceLocale,
@@ -172,13 +195,30 @@ export const gtPlugin = definePlugin<GTPluginConfig>(
       projectId: projectId,
     });
 
+    // Document types localized in place via internationalized arrays must NOT
+    // get @sanity/document-internationalization (language badges + per-locale
+    // documents). Build the set of array-localized types from translationLevel.
+    const arrayLocalizedTypes = new Set<string>();
+    if (translationLevel === 'internationalizedArray') {
+      normalizedTranslateDocuments
+        ?.map((filter) => filter.type)
+        .filter((type): type is string => !!type)
+        .forEach((type) => arrayLocalizedTypes.add(type));
+    } else if (translationLevel === 'mixed') {
+      normalizedFieldLevelDocuments
+        .map((filter) => filter.type)
+        .filter((type): type is string => !!type)
+        .forEach((type) => arrayLocalizedTypes.add(type));
+    }
+
     // Auto-add document internationalization plugin
     const plugins = [];
     if (showDocumentInternationalization) {
       const schemaTypes =
         normalizedTranslateDocuments
           ?.map((filter) => filter.type)
-          .filter((type): type is string => !!type) ?? [];
+          .filter((type): type is string => !!type)
+          .filter((type) => !arrayLocalizedTypes.has(type)) ?? [];
       if (schemaTypes.length > 0) {
         const allLocales = [resolvedSourceLocale, ...locales];
         const supportedLanguages = allLocales.map((locale) => {
@@ -195,9 +235,25 @@ export const gtPlugin = definePlugin<GTPluginConfig>(
       }
     }
 
+    const schemaTypes = fieldLevelConfig.enabled
+      ? createInternationalizedArrayTypes({
+          sourceLocale: resolvedSourceLocale,
+          locales,
+          fieldTypes: fieldLevelConfig.fieldTypes,
+          languageTitles: fieldLevelConfig.languageTitles,
+          getLanguageTitle: fieldLevelConfig.getLanguageTitle,
+          typePrefix: fieldLevelConfig.typePrefix,
+          includeCompatibilityTypes: fieldLevelConfig.includeCompatibilityTypes,
+          components: fieldLevelConfig.components,
+        })
+      : [];
+
     return {
       name: 'gt-sanity',
       plugins,
+      schema: {
+        types: schemaTypes,
+      },
       tools: [
         {
           name: 'translations',

package/src/schema/InternationalizedArrayInput.tsx

@@ -0,0 +1,278 @@
+import React, { useCallback, useMemo } from 'react';
+import { AddIcon, RemoveCircleIcon } from '@sanity/icons';
+import {
+  Box,
+  Button,
+  Card,
+  Flex,
+  Grid,
+  Label,
+  Stack,
+  Text,
+  Tooltip,
+} from '@sanity/ui';
+import {
+  ArrayOfObjectsItem,
+  MemberItemError,
+  setIfMissing,
+  unset,
+  type ArrayOfObjectsInputProps,
+  type ArraySchemaType,
+  type FieldMember,
+  type FormPatch,
+  type ObjectItemProps,
+  type ObjectSchemaType,
+  type PatchEvent,
+} from 'sanity';
+import { randomKey } from '../utils/randomKey';
+
+type LocaleItem = { _key: string; _type?: string; language?: string };
+
+type GTArrayOptions = {
+  sourceLocale: string;
+  locales: string[];
+  titles?: Record<string, string>;
+};
+
+function readGTOptions(
+  schemaType: ArraySchemaType | ObjectSchemaType | undefined
+): GTArrayOptions | undefined {
+  const options = schemaType?.options as
+    | { gtInternationalizedArray?: GTArrayOptions }
+    | undefined;
+  return options?.gtInternationalizedArray;
+}
+
+function toneFromValidation(
+  validation: ObjectItemProps['validation']
+): 'critical' | 'caution' | undefined {
+  if (!validation?.length) return undefined;
+  if (validation.some((marker) => marker.level === 'error')) return 'critical';
+  if (validation.some((marker) => marker.level === 'warning')) return 'caution';
+  return undefined;
+}
+
+function RemoveLocaleButton(props: {
+  isSource: boolean;
+  readOnly: boolean;
+  onRemove: () => void;
+}) {
+  const { isSource, readOnly, onRemove } = props;
+  const button = (
+    // The span keeps the tooltip working when the button is disabled
+    // (disabled buttons don't emit pointer events).
+    <span style={{ paddingBottom: '2px' }}>
+      <Button
+        mode='bleed'
+        icon={RemoveCircleIcon}
+        tone='critical'
+        disabled={readOnly || isSource}
+        onClick={onRemove}
+      />
+    </span>
+  );
+
+  if (!isSource) return button;
+
+  return (
+    <Tooltip
+      animate
+      portal
+      placement='top'
+      fallbackPlacements={['right', 'left']}
+      content={
+        <Text muted size={1}>
+          Can&apos;t remove the source language
+        </Text>
+      }
+    >
+      {button}
+    </Tooltip>
+  );
+}
+
+/**
+ * Item component for generated `internationalizedArray*Value` objects.
+ *
+ * Replaces the default array item (collapsed preview row + edit dialog) with
+ * an inline editor: the `value` field rendered in place, retitled with the
+ * locale label, plus a remove button. This is what makes localized fields
+ * read as "one labeled input per language" instead of a generic object list.
+ */
+export function InternationalizedValueItem(props: ObjectItemProps) {
+  const { inputProps, parentSchemaType, schemaType, validation } = props;
+  const value = props.value as LocaleItem & { value?: unknown };
+  const { onChange } = inputProps;
+
+  const gtOptions =
+    readGTOptions(schemaType) ??
+    readGTOptions(parentSchemaType as ArraySchemaType);
+  const language = value?.language;
+  const languageLabel = language
+    ? (gtOptions?.titles?.[language] ?? language)
+    : 'Unknown language';
+  const isSource = !!language && language === gtOptions?.sourceLocale;
+
+  // For array-based values (e.g. Portable Text), insert patches from the
+  // nested input can arrive rooted at the item while `value` doesn't exist
+  // yet; initialize it and re-root those patches under `value`.
+  const wrappedOnChange = useCallback(
+    (patch: FormPatch | FormPatch[] | PatchEvent) => {
+      if (!Array.isArray(patch)) {
+        onChange(patch);
+        return;
+      }
+      const currentValue = value?.value;
+      const valueIsEmpty =
+        currentValue == null ||
+        (Array.isArray(currentValue) && currentValue.length === 0);
+      const needsRerooting =
+        valueIsEmpty &&
+        patch.some(
+          (p) =>
+            p.type === 'insert' &&
+            Array.isArray(p.path) &&
+            p.path.length > 0 &&
+            (p.path[0] === 'value' || typeof p.path[0] === 'number')
+        );
+      if (!needsRerooting) {
+        onChange(patch);
+        return;
+      }
+      const rerooted = patch.map((p) =>
+        p.type === 'insert' && Array.isArray(p.path) && p.path[0] !== 'value'
+          ? { ...p, path: ['value', ...p.path] }
+          : p
+      );
+      onChange(
+        currentValue === undefined
+          ? [setIfMissing([], ['value']), ...rerooted]
+          : rerooted
+      );
+    },
+    [onChange, value?.value]
+  );
+
+  // Render only the `value` field, with the locale label as its title.
+  const members = useMemo(
+    () =>
+      inputProps.members
+        .filter(
+          (member): member is FieldMember =>
+            member.kind === 'field' && member.name === 'value'
+        )
+        .map((member) => ({
+          ...member,
+          field: {
+            ...member.field,
+            schemaType: {
+              ...member.field.schemaType,
+              title: (
+                <Label muted size={1}>
+                  {languageLabel}
+                </Label>
+              ) as unknown as string,
+            },
+          },
+        })),
+    [inputProps.members, languageLabel]
+  );
+
+  const handleRemove = useCallback(() => {
+    onChange(unset());
+  }, [onChange]);
+
+  return (
+    <Card paddingTop={2} tone={toneFromValidation(validation)}>
+      <Flex align='flex-end' gap={2}>
+        <Box flex={1}>
+          {inputProps.renderInput({
+            ...inputProps,
+            members,
+            onChange: wrappedOnChange,
+            // renderInput's parameter is typed as the base InputProps, which
+            // doesn't know about object members.
+          } as unknown as Parameters<typeof inputProps.renderInput>[0])}
+        </Box>
+        <RemoveLocaleButton
+          isSource={isSource}
+          readOnly={!!inputProps.readOnly}
+          onRemove={handleRemove}
+        />
+      </Flex>
+    </Card>
+  );
+}
+
+/**
+ * Input for generated `internationalizedArray*` fields.
+ *
+ * Renders items inline (each one an `InternationalizedValueItem`) instead of
+ * the default array input's draggable preview rows, followed by one add
+ * button per locale that doesn't have an entry yet. Each add button appends
+ * `{ _key, _type, language }` so the new item lands with its locale preset
+ * (the default "Add item" would create an item with no `language` — a dead
+ * end, since `language` is read-only).
+ */
+export function InternationalizedArrayInput(props: ArrayOfObjectsInputProps) {
+  const { members, schemaType, value, readOnly, onItemAppend } = props;
+  const gtOptions = readGTOptions(schemaType);
+  const itemType = schemaType.of[0]?.name;
+
+  const handleAdd = useCallback(
+    (language: string) => {
+      const item: LocaleItem = { _key: randomKey(), _type: itemType, language };
+      onItemAppend(item);
+    },
+    [onItemAppend, itemType]
+  );
+
+  if (!gtOptions) {
+    // No locale config on the type (not generated by gtPlugin) — fall back
+    // to the default array input rather than rendering a dead-end UI.
+    return props.renderDefault(props);
+  }
+
+  const allLocales = [gtOptions.sourceLocale, ...gtOptions.locales];
+  const existing = new Set(
+    ((value as LocaleItem[] | undefined) ?? [])
+      .map((item) => item.language)
+      .filter(Boolean)
+  );
+  const missing = allLocales.filter((locale) => !existing.has(locale));
+
+  return (
+    <Stack space={3}>
+      {members.length > 0 ? (
+        <Stack space={2}>
+          {members.map((member) =>
+            member.kind === 'item' ? (
+              <ArrayOfObjectsItem key={member.key} {...props} member={member} />
+            ) : (
+              <MemberItemError key={member.key} member={member} />
+            )
+          )}
+        </Stack>
+      ) : (
+        <Card border tone='transparent' padding={3} radius={2}>
+          <Text size={1} muted>
+            This internationalized field currently has no translations.
+          </Text>
+        </Card>
+      )}
+      {!readOnly && missing.length > 0 ? (
+        <Grid columns={Math.min(missing.length, 4)} gap={1}>
+          {missing.map((locale) => (
+            <Button
+              key={locale}
+              icon={AddIcon}
+              mode='ghost'
+              text={gtOptions.titles?.[locale] ?? locale}
+              onClick={() => handleAdd(locale)}
+            />
+          ))}
+        </Grid>
+      ) : null}
+    </Stack>
+  );
+}

package/src/schema/__tests__/createInternationalizedArrayTypes.test.ts

@@ -0,0 +1,169 @@
+import { describe, expect, test } from 'vitest';
+import { createInternationalizedArrayTypes } from '../createInternationalizedArrayTypes';
+
+type GeneratedArrayType = {
+  name: string;
+  type: string;
+  components?: { input?: unknown; field?: unknown };
+  of: Array<{
+    name: string;
+    type: string;
+    components?: { item?: unknown };
+    fields: Array<{
+      name: string;
+      type: string;
+      readOnly?: boolean;
+      hidden?: boolean;
+    }>;
+  }>;
+};
+
+const generate = (
+  overrides: Partial<Parameters<typeof createInternationalizedArrayTypes>[0]>
+) =>
+  createInternationalizedArrayTypes({
+    sourceLocale: 'en',
+    locales: ['es', 'fr'],
+    fieldTypes: ['string', 'text'],
+    ...overrides,
+  }) as unknown as GeneratedArrayType[];
+
+describe('createInternationalizedArrayTypes', () => {
+  test('generates internationalizedArrayString', () => {
+    const types = generate({ fieldTypes: ['string'] });
+    const stringType = types.find(
+      (t) => t.name === 'internationalizedArrayString'
+    );
+    expect(stringType).toBeDefined();
+    expect(stringType?.type).toBe('array');
+    const valueObject = stringType?.of[0];
+    expect(valueObject?.name).toBe('internationalizedArrayStringValue');
+    const valueField = valueObject?.fields.find((f) => f.name === 'value');
+    expect(valueField?.type).toBe('string');
+  });
+
+  test('generates internationalizedArrayText with a text value field', () => {
+    const types = generate({ fieldTypes: ['text'] });
+    const textType = types.find((t) => t.name === 'internationalizedArrayText');
+    const valueField = textType?.of[0].fields.find((f) => f.name === 'value');
+    expect(valueField?.type).toBe('text');
+  });
+
+  test('the language field is read-only', () => {
+    const types = generate({ fieldTypes: ['string'] });
+    const languageField = types[0].of[0].fields.find(
+      (f) => f.name === 'language'
+    );
+    expect(languageField?.readOnly).toBe(true);
+  });
+
+  test('generates a Portable Text (block) value field', () => {
+    const types = generate({ fieldTypes: ['block'] });
+    const blockType = types.find(
+      (t) => t.name === 'internationalizedArrayBlock'
+    );
+    const valueField = blockType?.of[0].fields.find(
+      (f) => f.name === 'value'
+    ) as { type: string; of: Array<{ type: string }> } | undefined;
+    expect(valueField?.type).toBe('array');
+    expect(valueField?.of[0].type).toBe('block');
+  });
+
+  test('supports custom field types', () => {
+    const types = generate({
+      fieldTypes: [{ name: 'seo', type: 'seoObject' }],
+    });
+    const seoType = types.find((t) => t.name === 'internationalizedArraySeo');
+    expect(seoType).toBeDefined();
+    expect(seoType?.of[0].name).toBe('internationalizedArraySeoValue');
+    const valueField = seoType?.of[0].fields.find((f) => f.name === 'value');
+    expect(valueField?.type).toBe('seoObject');
+  });
+
+  test('generates compatibility aliases when a custom prefix is used', () => {
+    const types = generate({
+      fieldTypes: ['string'],
+      typePrefix: 'gtArray',
+      includeCompatibilityTypes: true,
+    });
+    expect(types.find((t) => t.name === 'gtArrayString')).toBeDefined();
+    expect(
+      types.find((t) => t.name === 'internationalizedArrayString')
+    ).toBeDefined();
+  });
+
+  test('does not duplicate types when prefix is the default', () => {
+    const names = generate({ fieldTypes: ['string'] }).map((t) => t.name);
+    expect(names).toEqual(['internationalizedArrayString']);
+  });
+
+  test('omits compatibility aliases when disabled', () => {
+    const names = generate({
+      fieldTypes: ['string'],
+      typePrefix: 'gtArray',
+      includeCompatibilityTypes: false,
+    }).map((t) => t.name);
+    expect(names).toEqual(['gtArrayString']);
+  });
+
+  describe('components option', () => {
+    test('attaches GT components by default and hides the language field', () => {
+      const [type] = generate({ fieldTypes: ['string'] });
+      expect(typeof type.components?.input).toBe('function');
+      expect(typeof type.components?.field).toBe('function');
+      expect(typeof type.of[0].components?.item).toBe('function');
+      const languageField = type.of[0].fields.find(
+        (f) => f.name === 'language'
+      );
+      expect(languageField?.hidden).toBe(true);
+    });
+
+    test('replaces slots with custom components', () => {
+      const CustomInput = () => null;
+      const CustomItem = () => null;
+      const [type] = generate({
+        fieldTypes: ['string'],
+        components: { input: CustomInput, item: CustomItem },
+      });
+      expect(type.components?.input).toBe(CustomInput);
+      expect(type.of[0].components?.item).toBe(CustomItem);
+    });
+
+    test('detaches components when set to false', () => {
+      const [type] = generate({
+        fieldTypes: ['string'],
+        components: { input: false, item: false, field: false },
+      });
+      expect(type.components).toBeUndefined();
+      expect(type.of[0].components).toBeUndefined();
+    });
+
+    test('field level-reset default follows the input slot', () => {
+      const [detached] = generate({
+        fieldTypes: ['string'],
+        components: { input: false },
+      });
+      expect(detached.components?.field).toBeUndefined();
+
+      const CustomInput = () => null;
+      const [custom] = generate({
+        fieldTypes: ['string'],
+        components: { input: CustomInput },
+      });
+      expect(custom.components?.field).toBeUndefined();
+      expect(custom.components?.input).toBe(CustomInput);
+    });
+
+    test('keeps the language field visible with a custom or detached item', () => {
+      const [type] = generate({
+        fieldTypes: ['string'],
+        components: { item: false },
+      });
+      const languageField = type.of[0].fields.find(
+        (f) => f.name === 'language'
+      );
+      expect(languageField?.hidden).toBe(false);
+      expect(languageField?.readOnly).toBe(true);
+    });
+  });
+});