datocms-plugin-sdk 2.1.1 → 2.2.0-alpha.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "datocms-plugin-sdk",
-  "version": "2.1.1",
+  "version": "2.2.0-alpha.1",
   "description": "DatoCMS Plugin SDK",
   "keywords": [
     "datocms",
@@ -38,7 +38,7 @@
   "dependencies": {
     "@datocms/cma-client": "*",
     "@types/react": "^17.0.3",
-    "datocms-structured-text-utils": "^2.0.0",
+    "datocms-structured-text-utils": "^5.1.16",
     "emoji-regex-xs": "*",
     "penpal": "^4.1.1"
   },
@@ -46,5 +46,5 @@
     "glob": "^11.0.0",
     "typescript": "^5.6.2"
   },
-  "gitHead": "a8fcf4b05fe22e331b2fd95303793088aa15fedf"
+  "gitHead": "998ccd009a2babbc49d883ea4b0ef6539937271c"
 }

package/src/connect.ts

@@ -136,6 +136,15 @@ export type FullConnectParameters = AssetSourcesHook &
   UploadSidebarsHook &
   ValidateManualFieldExtensionParametersHook;
 
+function applyColorScheme(properties: unknown): void {
+  if (typeof document === 'undefined') return;
+  const next = (properties as { colorScheme?: 'light' | 'dark' } | null)
+    ?.colorScheme;
+  if (next !== 'light' && next !== 'dark') return;
+  if (document.documentElement.dataset.theme === next) return;
+  document.documentElement.dataset.theme = next;
+}
+
 export async function connect(
   rawConfiguration: Partial<FullConnectParameters> = {},
 ): Promise<void> {
@@ -185,6 +194,7 @@ export async function connect(
         ),
       ),
       onChange(newSettings: unknown) {
+        applyColorScheme(newSettings);
         if (onChangeListener) {
           onChangeListener(newSettings);
         }
@@ -212,6 +222,7 @@ export async function connect(
 
   const methods = await penpalConnection.promise;
   const initialProperties = await methods.getSettings();
+  applyColorScheme(initialProperties);
 
   if (initialProperties.mode === 'onBoot') {
     let currentProperties = initialProperties;

package/src/ctx/base.ts

@@ -63,6 +63,25 @@ type ProjectProperties = {
   /** Whether the current environment is the primary one */
   isEnvironmentPrimary: boolean;
 
+  /**
+   * The URL of the Content Delivery API (GraphQL) endpoint for the current
+   * project and environment.
+   *
+   * In the vast majority of cases you don't need this: the CDA endpoint is at a
+   * well-known, stable URL. It's exposed here only to support DatoCMS internal
+   * testing against non-production environments (e.g. staging).
+   */
+  cdaEndpointUrl: string;
+
+  /**
+   * The base URL of the Content Management API.
+   *
+   * In the vast majority of cases you don't need this: the CMA lives at a
+   * well-known, stable URL. It's exposed here only to support DatoCMS internal
+   * testing against non-production environments (e.g. staging).
+   */
+  cmaBaseUrl: string;
+
   /** The account/organization that is the project owner */
   owner: Account | Organization;
 
@@ -83,8 +102,33 @@ type ProjectProperties = {
     locale: string;
   };
 
-  /** An object containing the theme colors for the current DatoCMS project */
+  /**
+   * An object containing the theme colors for the current DatoCMS project
+   *
+   * @deprecated Use `semanticColorTokensTheme` instead. This property is kept
+   *   for backward compatibility with third-party plugins.
+   */
   theme: Theme;
+
+  /**
+   * Semantic color tokens for the current DatoCMS project, pre-computed by
+   * the host. A map of CSS custom property names (e.g.
+   * `--color--raised--surface`) to their resolved values for the current
+   * color scheme.
+   */
+  semanticColorTokensTheme: SemanticColorTokensTheme;
+
+  /**
+   * The appearance color scheme the host CMS is currently using. Resolved —
+   * `'system'` is already expanded to `'light'` or `'dark'` by the host.
+   *
+   * The SDK runtime reflects this onto `document.documentElement` as
+   * `data-theme="light"` / `data-theme="dark"` so plugin CSS can branch
+   * with `[data-theme="dark"] { … }` selectors. For non-CSS decisions
+   * (choosing a logo asset, a syntax-highlighting preset, …) branch on
+   * `ctx.colorScheme` directly.
+   */
+  colorScheme: 'light' | 'dark';
 };
 
 /**
@@ -125,7 +169,12 @@ type EntityReposProperties = {
   ssoUsers: Partial<Record<string, SsoUser>>;
 };
 
-/** An object containing the theme colors for the current DatoCMS project */
+/**
+ * An object containing the theme colors for the current DatoCMS project
+ *
+ * @deprecated Use `SemanticColorTokensTheme` instead. This type is kept for
+ *   backward compatibility with third-party plugins.
+ */
 export type Theme = {
   primaryColor: string;
   accentColor: string;
@@ -134,6 +183,21 @@ export type Theme = {
   darkColor: string;
 };
 
+/**
+ * Semantic color tokens for the current DatoCMS project, pre-computed by the
+ * host. Only available on DatoCMS hosts that support the new token system.
+ *
+ * Each key is a ready-to-use CSS custom property name (including the leading
+ * `--`), and each value is the resolved color for the host's current color
+ * scheme — e.g. `{ '--color--raised--surface': 'oklch(…)' }`. The SDK applies
+ * these verbatim onto the plugin canvas, so plugin CSS can reference them
+ * directly with `var(--color--raised--surface)`.
+ *
+ * The token set is whatever the host sends; it is intentionally untyped so it
+ * can evolve on the host without an SDK release.
+ */
+export type SemanticColorTokensTheme = Record<string, string>;
+
 export type BaseMethods = LoadDataMethods &
   UpdatePluginParametersMethods &
   ToastMethods &

package/src/manifest.ts

@@ -3302,6 +3302,28 @@ export const manifest: Manifest = {
             },
             type: 'boolean',
           },
+          cdaEndpointUrl: {
+            comment: {
+              markdownText:
+                "The URL of the Content Delivery API (GraphQL) endpoint for the current\nproject and environment.\n\nIn the vast majority of cases you don't need this: the CDA endpoint is at a\nwell-known, stable URL. It's exposed here only to support DatoCMS internal\ntesting against non-production environments (e.g. staging).",
+            },
+            location: {
+              filePath: 'src/ctx/base.ts',
+              lineNumber: 74,
+            },
+            type: 'string',
+          },
+          cmaBaseUrl: {
+            comment: {
+              markdownText:
+                "The base URL of the Content Management API.\n\nIn the vast majority of cases you don't need this: the CMA lives at a\nwell-known, stable URL. It's exposed here only to support DatoCMS internal\ntesting against non-production environments (e.g. staging).",
+            },
+            location: {
+              filePath: 'src/ctx/base.ts',
+              lineNumber: 83,
+            },
+            type: 'string',
+          },
           owner: {
             comment: {
               markdownText:
@@ -3309,7 +3331,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 67,
+              lineNumber: 86,
             },
             type: 'Account | Organization',
           },
@@ -3321,7 +3343,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 75,
+              lineNumber: 94,
             },
             type: 'Account | undefined',
           },
@@ -3332,7 +3354,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 81,
+              lineNumber: 100,
             },
             type: '{\n    /** Preferred locale */\n    locale: string;\n  }',
           },
@@ -3340,13 +3362,37 @@ export const manifest: Manifest = {
             comment: {
               markdownText:
                 'An object containing the theme colors for the current DatoCMS project.',
+              deprecatedMarkdownText:
+                'Use `semanticColorTokensTheme` instead. This property is kept\nfor backward compatibility with third-party plugins.',
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 87,
+              lineNumber: 111,
             },
             type: 'Theme',
           },
+          semanticColorTokensTheme: {
+            comment: {
+              markdownText:
+                'Semantic color tokens for the current DatoCMS project, pre-computed by\nthe host. A map of CSS custom property names (e.g.\n`--color--raised--surface`) to their resolved values for the current\ncolor scheme.',
+            },
+            location: {
+              filePath: 'src/ctx/base.ts',
+              lineNumber: 119,
+            },
+            type: 'SemanticColorTokensTheme',
+          },
+          colorScheme: {
+            comment: {
+              markdownText:
+                'The appearance color scheme the host CMS is currently using. Resolved —\n`\'system\'` is already expanded to `\'light\'` or `\'dark\'` by the host.\n\nThe SDK runtime reflects this onto `document.documentElement` as\n`data-theme="light"` / `data-theme="dark"` so plugin CSS can branch\nwith `[data-theme="dark"] { … }` selectors. For non-CSS decisions\n(choosing a logo asset, a syntax-highlighting preset, …) branch on\n`ctx.colorScheme` directly.',
+            },
+            location: {
+              filePath: 'src/ctx/base.ts',
+              lineNumber: 131,
+            },
+            type: "'light' | 'dark'",
+          },
         },
       },
       {
@@ -3363,7 +3409,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 97,
+              lineNumber: 141,
             },
             type: 'Partial<Record<string, ItemType>>',
           },
@@ -3374,7 +3420,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 104,
+              lineNumber: 148,
             },
             type: 'Partial<Record<string, Field>>',
           },
@@ -3385,7 +3431,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 111,
+              lineNumber: 155,
             },
             type: 'Partial<Record<string, Fieldset>>',
           },
@@ -3396,7 +3442,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 118,
+              lineNumber: 162,
             },
             type: 'Partial<Record<string, User>>',
           },
@@ -3407,7 +3453,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 125,
+              lineNumber: 169,
             },
             type: 'Partial<Record<string, SsoUser>>',
           },
@@ -3431,7 +3477,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 168,
+              lineNumber: 232,
             },
             type: '(itemTypeId: string) => Promise<Field[]>',
           },
@@ -3444,7 +3490,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 187,
+              lineNumber: 251,
             },
             type: '(itemTypeId: string) => Promise<Fieldset[]>',
           },
@@ -3457,7 +3503,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 204,
+              lineNumber: 268,
             },
             type: '() => Promise<Field[]>',
           },
@@ -3470,7 +3516,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 217,
+              lineNumber: 281,
             },
             type: '() => Promise<User[]>',
           },
@@ -3483,7 +3529,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 230,
+              lineNumber: 294,
             },
             type: '() => Promise<SsoUser[]>',
           },
@@ -3505,7 +3551,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 252,
+              lineNumber: 316,
             },
             type: '(params: Record<string, unknown>) => Promise<void>',
           },
@@ -3518,7 +3564,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 303,
+              lineNumber: 367,
             },
             type: '(\n    fieldId: string,\n    changes: FieldAppearanceChange[],\n  ) => Promise<void>',
           },
@@ -3540,7 +3586,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 408,
+              lineNumber: 472,
             },
             type: '(message: string) => Promise<void>',
           },
@@ -3553,7 +3599,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 423,
+              lineNumber: 487,
             },
             type: '(message: string) => Promise<void>',
           },
@@ -3566,7 +3612,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 447,
+              lineNumber: 511,
             },
             type: '<CtaValue = unknown>(\n    toast: Toast<CtaValue>,\n  ) => Promise<CtaValue | null>',
           },
@@ -3588,7 +3634,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 333,
+              lineNumber: 397,
             },
             type: '(itemTypeId: string) => Promise<Item | null>',
           },
@@ -3601,7 +3647,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 354,
+              lineNumber: 418,
             },
             type: '{\n    (\n      itemTypeId: string,\n      options: { multiple: true; initialLocationQuery?: ItemListLocationQuery },\n    ): Promise<Item[] | null>;\n    (\n      itemTypeId: string,\n      options?: {\n        multiple: false;\n        initialLocationQuery?: ItemListLocationQuery;\n      },\n    ): Promise<Item | null>;\n  }',
           },
@@ -3614,7 +3660,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 386,
+              lineNumber: 450,
             },
             type: '(itemId: string) => Promise<Item | null>',
           },
@@ -3636,7 +3682,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 474,
+              lineNumber: 538,
             },
             type: '{\n    (options: { multiple: true }): Promise<Upload[] | null>;\n    (options?: { multiple: false }): Promise<Upload | null>;\n  }',
           },
@@ -3649,7 +3695,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 502,
+              lineNumber: 566,
             },
             type: '(\n    uploadId: string,\n  ) => Promise<(Upload & { deleted?: true }) | null>',
           },
@@ -3662,7 +3708,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 530,
+              lineNumber: 594,
             },
             type: '(\n    /** The "single asset" field structure */\n    fileFieldValue: FileFieldValue,\n    /** Shows metadata information for a specific locale */\n    locale?: string,\n  ) => Promise<FileFieldValue | null>',
           },
@@ -3684,7 +3730,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 561,
+              lineNumber: 625,
             },
             type: '(modal: Modal) => Promise<unknown>',
           },
@@ -3697,7 +3743,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 598,
+              lineNumber: 662,
             },
             type: '(options: ConfirmOptions) => Promise<unknown>',
           },
@@ -3718,7 +3764,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 612,
+              lineNumber: 676,
             },
             type: '(path: string) => Promise<void>',
           },