@easyling/sanity-connector 1.2.0 → 1.3.0-rc.9

package/dist-types/components/dnt/DebugDNTBadge.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Debug DNT Badge Component
+ *
+ * Displays debug information about the DNT status of a field.
+ * This badge is shown on ALL fields (not just translatable ones) when debug mode is enabled.
+ * It shows whether the field will be included in the translation request and its effective DNT status.
+ */
+import { FieldProps } from 'sanity';
+export type DebugDNTBadgeProps = FieldProps & {
+    /** Name of the group this field belongs to */
+    groupName?: string;
+    /** Name of the fieldset this field belongs to */
+    fieldsetName?: string;
+};
+/**
+ * Debug DNT Badge Component
+ * Shows the effective DNT status for all fields when debug mode is enabled
+ */
+export declare function DebugDNTBadge(props: DebugDNTBadgeProps): import("react/jsx-runtime").JSX.Element;

package/dist-types/components/dnt/index.d.ts

@@ -4,3 +4,4 @@
 export { DNTFieldBadge } from './DNTFieldBadge';
 export { withDNTBadge } from './DNTFieldComponent';
 export { DNTFieldInput } from './DNTFieldInput';
+export { DebugDNTBadge } from './DebugDNTBadge';

package/dist-types/plugin.d.ts

@@ -1,2 +1,12 @@
+/**
+ * Context for plugin configuration state
+ */
+interface PluginConfigContextType {
+    debugMode: boolean;
+}
+/**
+ * Hook to access plugin configuration
+ */
+export declare function usePluginConfig(): PluginConfigContextType;
 declare const _default: import("sanity").Plugin<void>;
 export default _default;

package/dist-types/services/contentExtractor.d.ts

@@ -8,6 +8,12 @@ export interface ExtendedDocumentContent extends DocumentContent {
     slug?: string;
     /** Fields can be either flat values or TranslatableField objects with value and dnt properties */
     fields?: Record<string, any>;
+    /** Whether the title was found at the document's top level (false if extracted from nested fields) */
+    titleFoundAtTopLevel?: boolean;
+    /** Whether the body/content was found at the document's top level (false if extracted from nested fields) */
+    bodyFoundAtTopLevel?: boolean;
+    /** The field name where body content was found (e.g., 'body', 'content', 'text', or nested path) */
+    bodyFieldName?: string;
 }
 export interface ExtractedContent {
     documentId: string;
@@ -24,6 +30,46 @@ export declare class ContentExtractor {
      * @returns The inferred Sanity type string
      */
     private inferSanityType;
+    /**
+     * Check if a value is an atomic Sanity type that should NOT be recursively flattened
+     * These include types like slug, date, datetime, reference, image, file, etc.
+     * Custom object types (e.g., articleInfo, footnoteInfo) are NOT atomic and should be flattened
+     */
+    private isSanitySpecialType;
+    /**
+     * Check if an object should be recursively flattened into separate fields
+     * Plain objects (fieldsets, custom object types without _type) should be flattened
+     * Sanity special types should NOT be flattened
+     */
+    private shouldFlattenObject;
+    /**
+     * Recursively flatten a nested object into individual TranslatableField entries
+     * Each leaf field gets its own entry with a dotted path key
+     *
+     * Arrays of objects with _key are flattened with key-based paths like:
+     *   article.footnotes[_key == "abc123"].footnote
+     *
+     * @param obj - The object to flatten
+     * @param basePath - The base path prefix for keys
+     * @param fields - The fields record to populate
+     * @param docContext - Document context for GROQ path generation
+     */
+    private flattenObjectToFields;
+    /**
+     * Flatten an array into individual TranslatableField entries
+     * Arrays of objects with _key get key-based paths
+     *
+     * @param array - The array to flatten
+     * @param fieldPath - The field path for this array
+     * @param fieldName - The field name (last segment of path)
+     * @param fields - The fields record to populate
+     * @param docContext - Document context for GROQ path generation
+     */
+    private flattenArrayToFields;
+    /**
+     * Add a leaf field (primitive or atomic Sanity type) to the fields record
+     */
+    private addLeafField;
     /**
      * Extract content from a single Sanity document and convert to HTML
      */
@@ -40,6 +86,13 @@ export declare class ContentExtractor {
     /**
      * Apply DNT preferences to extracted fields based on document type
      * Now uses document-type-based configuration that applies to all documents of the same type
+     *
+     * DNT priority:
+     * 1. Stored user preference (explicit override)
+     * 2. Default based on field type (slug, date, datetime, reference, etc.)
+     * 3. Default based on field name (containing "author" or "contributor")
+     * 4. Default based on group/fieldset name (containing "date" or "time")
+     * 5. Default to translatable (dnt: false)
      */
     private applyDNTPreferences;
     /**
@@ -77,16 +130,30 @@ export declare class ContentExtractor {
     /**
      * Separate main content from metadata fields
      * All fields are immediately wrapped in TranslatableField format with type information
+     * DNT defaults are computed based on field type and name patterns
+     *
+     * Complex types (objects/fieldsets) are recursively flattened into individual fields
+     * using dotted path notation (e.g., "metadata.version", "metadata.status")
      */
     private separateContentAndFields;
+    /**
+     * Recursively search nested objects and fieldsets for a body/content field
+     */
+    private findBodyInNestedFields;
     /**
      * Extract slug from document
      */
     private extractSlug;
     /**
      * Extract title from document
+     * Searches top-level fields first, then descends into nested objects/fieldsets
+     * @returns Object with title string and flag indicating if found at top level
      */
     private extractTitle;
+    /**
+     * Recursively search nested objects and fieldsets for a title field
+     */
+    private findTitleInNestedFields;
     /**
      * Escape HTML special characters
      */

package/dist-types/services/dntStorageAdapter.d.ts

@@ -44,7 +44,7 @@ export declare class DNTStorageAdapter implements DNTStorage {
      * @deprecated Use getFieldsForType instead. This method now uses document type, not document ID.
      * Get DNT preferences - now based on document type, not individual document ID
      */
-    getPreferences(documentId: string): Promise<DNTPreferences | null>;
+    getPreferences(_documentId: string): Promise<DNTPreferences | null>;
     /**
      * @deprecated Use setFieldDNT instead
      */
@@ -52,7 +52,7 @@ export declare class DNTStorageAdapter implements DNTStorage {
     /**
      * @deprecated Use clearFieldsForType instead
      */
-    clearPreferences(documentId: string): Promise<void>;
+    clearPreferences(_documentId: string): Promise<void>;
 }
 /**
  * Legacy DNT Storage Adapter using localStorage (deprecated)

package/dist-types/services/documentCreationService.d.ts

@@ -14,6 +14,23 @@ export interface DocumentCreationOptions {
     parentDocumentId?: string;
     /** Creation mode: 'draft' creates a draft document, 'published' creates a published document */
     creationMode?: 'draft' | 'published';
+    /**
+     * Whether the title was found at the document's top level during extraction.
+     * When false, the translated title should not be written as a top-level field.
+     * This is tracked in-memory by the plugin, not sent to the translation backend.
+     */
+    titleFoundAtTopLevel?: boolean;
+    /**
+     * Whether the body/content was found at the document's top level during extraction.
+     * When false, the translated body should not be written as a top-level field.
+     * This is tracked in-memory by the plugin, not sent to the translation backend.
+     */
+    bodyFoundAtTopLevel?: boolean;
+    /**
+     * The field name where body content was originally found (e.g., 'body', 'content', or nested path).
+     * Used to write translated content back to the correct location.
+     */
+    bodyFieldName?: string;
 }
 export interface SlugFallbackInfo {
     documentId: string;
@@ -69,8 +86,13 @@ export declare class DocumentCreationService {
     private validateBusinessRules;
     /**
      * Check if document has meaningful content
+     * Searches both top-level and nested fields for title/body content
      */
     private documentHasContent;
+    /**
+     * Recursively search nested objects for title or body content
+     */
+    private hasContentInNestedFields;
     /**
      * Format error messages with additional context
      * Requirements: 4.3, 4.4
@@ -96,6 +118,33 @@ export declare class DocumentCreationService {
      * Requirements: 4.3, 4.4
      */
     createRollbackPlan(createdDocumentIds: string[]): RollbackInfo;
+    /**
+     * Parse a field path that may contain array key selectors
+     * e.g., "article.footnotes[_key == \"c82437b14d71\"].footnote"
+     *
+     * @param fieldPath - The field path (may be from the field key or from the path property)
+     * @returns Array of path segments with type information
+     */
+    private parseFieldPath;
+    /**
+     * Unflatten fields with complex paths back into nested objects
+     * Handles both simple dotted paths and GROQ-style array key paths:
+     *   - "metadata.version" → { metadata: { version: ... } }
+     *   - "article.footnotes[_key == \"abc\"].footnote" → { article: { footnotes: [{ _key: "abc", footnote: ... }] } }
+     *
+     * @param fields - Flattened fields with path keys
+     * @param originalDocument - Original document for preserving array structure
+     * @returns Unflattened nested object structure
+     */
+    private unflattenFields;
+    /**
+     * Get the original nested value from the original document using a dotted path
+     *
+     * @param document - The original document
+     * @param fieldPath - The dotted path to the field
+     * @returns The original value at the path, or undefined
+     */
+    private getOriginalValueByPath;
     /**
      * Merge translated content back into original document structure
      * Requirements: 1.2, 3.2, 3.4

package/dist-types/services/translationService.d.ts

@@ -3,12 +3,17 @@ import { ExtendedDocumentContent } from './contentExtractor';
  * Field object structure supporting translation-invariant fields
  */
 export interface TranslatableField {
-    /** The actual field value */
+    /** The actual field value (serialized as string for the protobuf) */
     value: unknown;
     /** Do Not Translate flag - if true, the field should not be translated */
     dnt?: boolean;
     /** Type of the field value from Sanity (e.g., 'string', 'number', 'date', 'slug', 'array', 'object') */
     type?: string;
+    /**
+     * GROQ-style path for reconstructing the document structure
+     * Example: *[_type == "blogPost" && _id == $documentId][0].article.footnotes[_key == "abc123"].footnote
+     */
+    path?: string;
 }
 export interface TranslationRequest {
     documentId: string;
@@ -92,6 +97,8 @@ export interface TranslationRequestPayload {
         targetLanguage?: string;
         /** Array of target locale codes (e.g., ['es', 'fr', 'de']) - for multi-locale support */
         targetLocales?: string[];
+        /** Whether the title was found at the document's top level (false if extracted from nested fields) */
+        titleFoundAtTopLevel?: boolean;
     };
 }
 /**
@@ -130,6 +137,11 @@ export interface TranslatedDocument {
      * Target locale code for this translation (e.g., 'es', 'fr', 'de')
      */
     locale?: string;
+    /**
+     * Whether the title was found at the document's top level
+     * When false, the translated title should not be written as a top-level field
+     */
+    titleFoundAtTopLevel?: boolean;
 }
 /**
  * Response format expected from the translation service

package/dist-types/services/unifiedConfigStorage.d.ts

@@ -29,6 +29,8 @@ export interface UnifiedPluginConfig {
     defaultLocale?: string;
     /** DNT field map: { [documentType]: { [fieldPath]: boolean } } */
     dntFieldMap?: Record<string, Record<string, boolean>>;
+    /** Debug mode - when enabled, shows additional DNT badges on all fields */
+    debugMode?: boolean;
     /** Configuration version for migrations */
     version?: string;
     /** Last updated timestamp */
@@ -120,4 +122,12 @@ export declare class UnifiedConfigStorage {
      * Get default document creation mode with fallback to default
      */
     getDefaultDocumentCreationMode(): Promise<'draft' | 'published'>;
+    /**
+     * Get debug mode status
+     */
+    getDebugMode(): Promise<boolean>;
+    /**
+     * Set debug mode status
+     */
+    setDebugMode(enabled: boolean): Promise<void>;
 }

package/dist-types/types/pluginConfig.d.ts

@@ -37,6 +37,8 @@ export interface PluginConfiguration {
     defaultLocale?: string;
     /** Document-type-based DNT field configurations */
     dntFieldConfigurations?: DNTTypeConfig[];
+    /** When enabled, displays additional DNT status badges on all fields */
+    debugMode?: boolean;
     /** Configuration schema version for migration purposes */
     version?: string;
     /** ISO 8601 timestamp of last configuration update */

package/dist-types/utils/dntDefaults.d.ts

@@ -0,0 +1,101 @@
+/**
+ * DNT (Do Not Translate) Defaults Utility
+ *
+ * Determines whether a field should default to DNT based on:
+ * - Field type (slug, date, datetime, reference, image, file, geopoint, number, boolean)
+ * - Field name patterns (containing "author" or "contributor")
+ * - Group/fieldset name patterns (containing "date" or "time")
+ */
+/**
+ * Field types that are inherently non-translatable
+ * These fields contain data that should not be modified by translation
+ */
+export declare const NON_TRANSLATABLE_TYPES: string[];
+/**
+ * Field name patterns that indicate DNT by default (case-insensitive)
+ * Fields with names containing these strings should not be translated
+ */
+export declare const DNT_FIELD_NAME_PATTERNS: string[];
+/**
+ * Group/fieldset name patterns that indicate all contained fields should be DNT (case-insensitive)
+ */
+export declare const DNT_GROUP_NAME_PATTERNS: string[];
+/**
+ * Context information about a field's location in the schema
+ */
+export interface FieldContext {
+    /** The field path (e.g., 'title', 'content.author') */
+    fieldPath: string;
+    /** The field name (last segment of path) */
+    fieldName: string;
+    /** The Sanity field type (e.g., 'string', 'date', 'slug') */
+    fieldType?: string;
+    /** Name of the group this field belongs to, if any */
+    groupName?: string;
+    /** Name of the fieldset this field belongs to, if any */
+    fieldsetName?: string;
+}
+/**
+ * Result of DNT default computation
+ */
+export interface DNTDefaultResult {
+    /** Whether the field should default to DNT */
+    shouldBeDNT: boolean;
+    /** Reason for the DNT default decision */
+    reason: string;
+}
+/**
+ * Check if a field type is inherently non-translatable
+ *
+ * @param fieldType - The Sanity field type
+ * @returns True if the field type should not be translated
+ */
+export declare function isNonTranslatableType(fieldType: string | undefined): boolean;
+/**
+ * Check if a field name matches DNT patterns
+ *
+ * @param fieldName - The field name to check
+ * @returns Object with match status and matched pattern
+ */
+export declare function matchesDNTFieldNamePattern(fieldName: string): {
+    matches: boolean;
+    pattern?: string;
+};
+/**
+ * Check if a group or fieldset name matches DNT patterns
+ *
+ * @param groupOrFieldsetName - The group or fieldset name to check
+ * @returns Object with match status and matched pattern
+ */
+export declare function matchesDNTGroupPattern(groupOrFieldsetName: string | undefined): {
+    matches: boolean;
+    pattern?: string;
+};
+/**
+ * Compute the default DNT status for a field based on its context
+ *
+ * Priority order:
+ * 1. Non-translatable field type (slug, date, etc.)
+ * 2. Field name contains "author" or "contributor"
+ * 3. Field is in a group/fieldset containing "date" or "time"
+ *
+ * @param context - Field context information
+ * @returns DNT default result with reason
+ */
+export declare function computeDNTDefault(context: FieldContext): DNTDefaultResult;
+/**
+ * Determine if a field should show DNT badge based on translatability
+ * Only translatable field types should show the badge
+ *
+ * @param fieldType - The Sanity field type
+ * @returns True if the field should show a DNT badge
+ */
+export declare function shouldShowDNTBadge(fieldType: string | undefined): boolean;
+/**
+ * Get a human-readable description of the DNT status for debugging
+ *
+ * @param context - Field context information
+ * @param storedDNT - The stored DNT status (if any)
+ * @returns Debug description
+ */
+export declare function getDNTDebugInfo(context: FieldContext, storedDNT?: boolean): string;

package/dist-types/utils/index.d.ts

@@ -7,8 +7,10 @@ export * from './logger';
 export * from './validator';
 export * from './oauthLogger';
 export * from './oauthErrorFeedback';
+export * from './dntDefaults';
 export { HtmlFormatter } from './htmlFormatter';
 export { Logger, LogLevel, defaultLogger } from './logger';
 export { Validator } from './validator';
 export { OAuthLogger, createOAuthLogger } from './oauthLogger';
 export { OAuthErrorFeedback, createOAuthErrorFeedback } from './oauthErrorFeedback';
+export { computeDNTDefault, isNonTranslatableType, matchesDNTFieldNamePattern, matchesDNTGroupPattern, NON_TRANSLATABLE_TYPES, DNT_FIELD_NAME_PATTERNS, DNT_GROUP_NAME_PATTERNS } from './dntDefaults';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@easyling/sanity-connector",
-  "version": "1.2.0",
+  "version": "1.3.0-rc.9",
   "description": "A *Sanity Studio v4* plugin that enables document translation with support for single and bulk operations, using Easyling's AI translation capabilities.",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -72,7 +72,7 @@
     "sanity": "^4.16.0"
   },
   "devDependencies": {
-    "@easyling/sanity": "^1.0.6",
+    "@easyling/sanity": "^2.0.0",
     "@sanity/icons": "^3.7.4",
     "@sanity/ui": "^3.1.11",
     "@semantic-release/changelog": "^6.0.3",
@@ -87,16 +87,16 @@
     "@types/jest": "^29.0.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
-    "@typescript-eslint/eslint-plugin": "^6.21.0",
-    "@typescript-eslint/parser": "^6.21.0",
-    "eslint": "^8.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.48.1",
+    "@typescript-eslint/parser": "^8.48.1",
+    "eslint": "^9.39.1",
     "get-random-values-esm": "^1.0.2",
     "jest": "^29.0.0",
     "jest-environment-jsdom": "^30.2.0",
     "jsdom": "^27.1.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "rimraf": "^5.0.0",
+    "rimraf": "^6.1.2",
     "sanity": "^4.0.0",
     "ts-jest": "^29.4.5",
     "ts-loader": "^9.5.4",