@sveltia/cms 0.63.1 → 0.64.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sveltia/cms",
-  "version": "0.63.1",
+  "version": "0.64.0",
   "license": "MIT",
   "type": "module",
   "repository": {

package/types/public.d.ts

@@ -158,7 +158,7 @@ export type FieldMediaLibraryOptions = {
  */
 export type MediaFieldProps = {
     /**
-     * Default value. A file path or complete URL.
+     * Default value. Accepts a file path or complete URL.
      */
     default?: string;
     /**
@@ -303,7 +303,7 @@ export type BooleanFieldProps = {
      */
     widget: "boolean";
     /**
-     * Default value.
+     * Default value. Accepts `true` or `false`.
      */
     default?: boolean;
 };
@@ -340,7 +340,7 @@ export type CodeFieldProps = {
     output_code_only?: boolean;
     /**
      * Output property names. It has no effect if
-     * `output_code_only` is `true`.
+     * `output_code_only` is `true`. Default: `{ code: 'code', lang: 'lang' }`.
      */
     keys?: {
         code: string;
@@ -360,7 +360,8 @@ export type ColorFieldProps = {
      */
     widget: "color";
     /**
-     * Default value. Accepts a Hex color code.
+     * Default value. Accepts a Hex color code in the six-value (`#RRGGBB`)
+     * or eight-value (`#RRGGBBAA`) syntax.
      */
     default?: string;
     /**
@@ -511,7 +512,9 @@ export type ListFieldProps = {
      */
     widget: "list";
     /**
-     * Default value.
+     * Default value. The
+     * format depends on how the field is configured, with or without `field`, `fields` or `types`. See
+     * the document for details.
      */
     default?: string[] | Record<string, any>[] | Record<string, any>;
     /**
@@ -569,7 +572,8 @@ export type MapFieldProps = {
      */
     widget: "map";
     /**
-     * Default value. Accepts a stringified single GeoJSON geometry object.
+     * Default value. Accepts a stringified single GeoJSON geometry object
+     * that contains `type` and `coordinates` properties.
      */
     default?: string;
     /**
@@ -736,12 +740,14 @@ export type RelationFieldProps = {
     file?: string;
     /**
      * Field name to be stored as the value, or
-     * `{{slug}}`. It can contain a locale prefix like `{{locale}}/{{slug}}` if i18n is enabled.
+     * `{{slug}}` (entry slug). It can contain a locale prefix like `{{locale}}/{{slug}}` if i18n is
+     * enabled. Default: `{{slug}}`.
      */
-    value_field: FieldKeyPath | string;
+    value_field?: FieldKeyPath | string;
     /**
      * Name of fields to be displayed. It can
-     * contain string templates. Default: `value_field` field value.
+     * contain string templates. Default: `value_field` field value or the referenced collection’s
+     * `identifier_field`, which is `title` by default.
      */
     display_fields?: (FieldKeyPath | string)[];
     /**
@@ -854,13 +860,17 @@ export type UuidFieldProps = {
  */
 export type UuidField = CommonFieldProps & UuidFieldProps;
 /**
- * Custom field definition. It can contain any properties.
+ * Entry field using a built-in widget.
+ */
+export type StandardField = BooleanField | CodeField | ColorField | ComputeField | DateTimeField | FileField | HiddenField | ImageField | KeyValueField | ListField | MapField | MarkdownField | NumberField | ObjectField | RelationField | SelectField | StringField | TextField | UuidField;
+/**
+ * Entry field using a custom widget. It can contain any properties.
  */
 export type CustomField = CommonFieldProps & Record<string, any>;
 /**
  * Entry field.
  */
-export type Field = BooleanField | CodeField | ColorField | ComputeField | DateTimeField | FileField | HiddenField | ImageField | KeyValueField | ListField | MapField | MarkdownField | NumberField | ObjectField | RelationField | SelectField | StringField | TextField | UuidField | CustomField;
+export type Field = StandardField | CustomField;
 /**
  * Internationalization (i18n) file structure type.
  */
@@ -1171,7 +1181,8 @@ export type Collection = {
      */
     extension?: FileExtension;
     /**
-     * File format. Entry collection only. Default: `yaml-frontmatter`.
+     * File format. It should match the file extension. Default:
+     * `yaml-frontmatter`.
      */
     format?: FileFormat;
     /**
@@ -1263,7 +1274,7 @@ export type Collection = {
 /**
  * Supported backend name.
  */
-export type BackendName = "github" | "gitlab";
+export type BackendName = "github" | "gitlab" | "test-repo";
 /**
  * Custom commit messages.
  */
@@ -1309,28 +1320,34 @@ export type BackendOptions = {
     repo?: string;
     /**
      * Git branch name. If omitted, the default branch, usually `main` or
-     * `master`, will be used.
+     * `master`, will be used. Git backends only.
      */
     branch?: string;
     /**
-     * API endpoint of the backend. Required when using GitHub Enterprise
-     * Server or a self-hosted GitLab instance. Default: `https://api.github.com` (GitHub) or
-     * `https://gitlab.com/api/v4` (GitLab).
+     * REST API endpoint for the backend. Required when using GitHub
+     * Enterprise Server or a self-hosted GitLab instance. Git backends only. Default:
+     * `https://api.github.com` (GitHub) or `https://gitlab.com/api/v4` (GitLab).
      */
     api_root?: string;
+    /**
+     * GraphQL API endpoint for the backend. Git backends only.
+     * Default: inferred from `api_root` option value.
+     */
+    graphql_api_root?: string;
     /**
      * Site domain used for OAuth, which will be included in the
-     * `site_id` param to be sent to the API endpoint. Default: `location.hostname`.
+     * `site_id` param to be sent to the API endpoint. Git backends only. Default: `location.hostname`.
      */
     site_domain?: string;
     /**
      * OAuth base URL origin. Required when using an OAuth client other
-     * than Netlify, including Sveltia CMS Authenticator. Default: `https://api.netlify.com`.
+     * than Netlify, including Sveltia CMS Authenticator. Git backends only. Default:
+     * `https://api.netlify.com`.
      */
     base_url?: string;
     /**
-     * OAuth base URL path. Default: `auth` (GitHub) or
-     * `oauth/authorize` (GitLab).
+     * OAuth base URL path. Git backends only. Default: `auth`
+     * (GitHub) or `oauth/authorize` (GitLab).
      */
     auth_endpoint?: string;
     /**
@@ -1343,7 +1360,7 @@ export type BackendOptions = {
      */
     app_id?: string;
     /**
-     * Custom commit messages.
+     * Custom commit messages. Git backends only.
      */
     commit_messages?: CommitMessages;
     /**
@@ -1351,21 +1368,23 @@ export type BackendOptions = {
      */
     preview_context?: string;
     /**
-     * Pull request label prefix for Editorial Workflow. Default:
-     * `sveltia-cms/`.
+     * Pull request label prefix for Editorial Workflow. Git
+     * backends only. Default: `sveltia-cms/`.
      */
     cms_label_prefix?: string;
     /**
-     * Whether to use squash marge for Editorial Workflow. Default:
-     * `false`.
+     * Whether to use squash marge for Editorial Workflow. Git
+     * backends only. Default: `false`.
      */
     squash_merges?: boolean;
     /**
-     * Whether to use Open Authoring. Default: `false`.
+     * Whether to use Open Authoring. Git backends only. Default:
+     * `false`.
      */
     open_authoring?: boolean;
     /**
-     * Authentication scope for Open Authoring.
+     * Authentication scope for Open Authoring. Git
+     * backends only.
      */
     auth_scope?: "repo" | "public_repo";
     /**