sanity-plugin-internationalized-array 1.10.8 → 2.0.0

package/README.md

@@ -8,6 +8,24 @@ A plugin to register array fields with a custom input component to store field v
 
 ![Screenshot of an internationalized input](./img/internationalized-array.png)
 
+- [sanity-plugin-internationalized-array](#sanity-plugin-internationalized-array)
+  - [Installation](#installation)
+  - [Usage for simple field types](#usage-for-simple-field-types)
+  - [Loading languages](#loading-languages)
+  - [Configuring the "Add translation" buttons](#configuring-the-add-translation-buttons)
+  - [Using complex field configurations](#using-complex-field-configurations)
+  - [Creating internationalized objects](#creating-internationalized-objects)
+  - [Validation of individual array items](#validation-of-individual-array-items)
+  - [Usage with @sanity/language-filter](#usage-with-sanitylanguage-filter)
+  - [Shape of stored data](#shape-of-stored-data)
+  - [Querying data](#querying-data)
+  - [Migrate from objects to arrays](#migrate-from-objects-to-arrays)
+    - [Why store localized field data like this?](#why-store-localized-field-data-like-this)
+  - [License](#license)
+  - [Develop \& test](#develop--test)
+    - [Release new version](#release-new-version)
+  - [License](#license-1)
+
 ## Installation
 
 ```
@@ -222,6 +240,37 @@ export default defineType({
 })
 ```
 
+## Validation of individual array items
+
+You may wish to validate individual language fields for various reasons. From the internationalized array field, add a validation rule that can look through all the array items, and return item-specific validation messages at the path of that array item.
+
+```ts
+defineField({
+  name: 'title',
+  type: 'internationalizedArrayString',
+  description: `Use fewer than 5 words.`,
+  validation: (rule) =>
+    rule.custom<{value: string; _type: string; _key: string}[]>((value) => {
+      if (!value) {
+        return 'Title is required'
+      }
+
+      const invalidItems = value.filter(
+        (item) => item.value.split(' ').length > 5,
+      )
+
+      if (invalidItems.length) {
+        return invalidItems.map((item) => ({
+          message: `Title is too long. Must be 5 words or fewer.`,
+          path: [{_key: item._key}, 'value'],
+        }))
+      }
+
+      return true
+    }),
+}),
+```
+
 ## Usage with @sanity/language-filter
 
 If you have many languages and authors that predominately write in only a few, [@sanity/language-filter](https://github.com/sanity-io/language-filter) can be used to reduce the number of language fields shown in the document form.

package/lib/index.d.mts

@@ -0,0 +1,142 @@
+import type {FieldDefinition} from 'sanity'
+import {Plugin as Plugin_2} from 'sanity'
+import type {Rule} from 'sanity'
+import type {RuleTypeConstraint} from 'sanity'
+import type {SanityClient} from 'sanity'
+
+export declare type AllowedType =
+  | 'string'
+  | 'number'
+  | 'boolean'
+  | 'text'
+  | 'reference'
+
+export declare type ArrayConfig = {
+  name: string
+  type: AllowedType
+  languages: Language[]
+  title?: string
+  group?: string
+  hidden?: boolean | (() => boolean)
+  readOnly?: boolean | (() => boolean)
+  validation?: Rule | Rule[]
+  field?: {
+    [key: string]: any
+    options: {
+      [key: string]: any
+    }
+  }
+}
+
+export declare const clear: () => void
+
+export declare const internationalizedArray: Plugin_2<PluginConfig>
+
+export declare type Language = {
+  id: Intl.UnicodeBCP47LocaleIdentifier
+  title: string
+}
+
+export declare type LanguageCallback = (
+  client: SanityClient,
+  selectedValue: Record<string, unknown>
+) => Promise<Language[]>
+
+export declare type PluginConfig = {
+  /**
+   * https://www.sanity.io/docs/api-versioning
+   * @defaultValue '2022-11-27'
+   */
+  apiVersion?: string
+  /**
+   * Specify fields that should be available in the language callback:
+   * ```tsx
+   * {
+   *   select: {
+   *     markets: 'markets'
+   *   },
+   *   languages: (client, {markets}) =>
+   *     query.fetch(groq`*[_type == "language" && market in $markets]{id,title}`, {markets})
+   * }
+   * ```
+   */
+  select?: Record<string, string>
+  /**
+   * You can give it an array of language definitions:
+   * ```tsx
+   * {
+   *   languages: [
+   *     {id: 'en', title: 'English'},
+   *     {id: 'fr', title: 'French'}
+   *   ]
+   * }
+   * ```
+   * You can load them async by passing a function that returns a promise:
+   * ```tsx
+   * {
+   *   languages: async () => {
+   *     const response = await fetch('https://example.com/languages')
+   *     return response.json()
+   *   }
+   * }
+   * ```
+   * You can query your dataset for languages::
+   * ```tsx
+   * {
+   *   languages: (client) =>
+   *     query.fetch(groq`*[_type == "language"]{id,title}`)
+   * }
+   * ```
+   */
+  languages: Language[] | LanguageCallback
+  /**
+   * You can specify a list of language IDs that should be pre-filled when creating a new document
+   * ```tsx
+   * {
+   *  defaultLanguages: ['en']
+   * }
+   * ```
+   */
+  defaultLanguages?: string[]
+  /**
+   * Can be a string matching core field types, as well as custom ones:
+   * ```tsx
+   * {
+   *   fieldTypes: [
+   *     "date", "datetime", "file", "image", "number", "string", "text", "url"
+   *   ]
+   * }
+   * ```
+   * You can also define a type directly:
+   * ```tsx
+   * {
+   *   fieldTypes: [
+   *     defineField({
+   *       name: 'featuredProduct',
+   *       type: 'reference',
+   *       to: [{type: 'product'}]
+   *       hidden: (({document}) => !document?.title)
+   *     })
+   *   ]
+   * }
+   * ```
+   */
+  fieldTypes: (string | RuleTypeConstraint | FieldDefinition)[]
+  /**
+   * Locations where the "+ EN" add language buttons are visible
+   * @defaultValue ['field']
+   * */
+  buttonLocations?: ('field' | 'unstable__fieldAction' | 'document')[]
+  /**
+   * Show or hide the "Add missing languages" button
+   * @defaultValue true
+   * */
+  buttonAddAll?: boolean
+}
+
+export declare type Value = {
+  _key: string
+  value?: string
+}
+
+export {}