datocms-plugin-sdk 2.1.5 → 2.2.0-alpha.2

package/dist/types/ctx/base.d.ts

@@ -79,8 +79,34 @@ type ProjectProperties = {
         /** Preferred locale */
         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 `cssDesignTokens` 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.
+     */
+    cssDesignTokens: cssDesignTokens;
+    /**
+     * 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` two ways:
+     * the `data-color-scheme="light"` / `data-color-scheme="dark"` attribute,
+     * so plugin CSS can branch with `[data-color-scheme="dark"] { … }`
+     * selectors; and the actual `color-scheme` CSS property, so `light-dark()`
+     * resolves to the correct branch (and native form controls / scrollbars
+     * match) everywhere in the plugin frame. For non-CSS decisions (choosing a
+     * logo asset, a syntax-highlighting preset, …) branch on `ctx.colorScheme`
+     * directly.
+     */
+    colorScheme: 'light' | 'dark';
 };
 /**
  * These properties provide access to "entity repos", that is, the collection of
@@ -115,7 +141,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 `cssDesignTokens` instead. This type is kept for
+ *   backward compatibility with third-party plugins.
+ */
 export type Theme = {
     primaryColor: string;
     accentColor: string;
@@ -123,6 +154,20 @@ export type Theme = {
     lightColor: string;
     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 cssDesignTokens = Record<string, string>;
 export type BaseMethods = LoadDataMethods & UpdatePluginParametersMethods & ToastMethods & ItemDialogMethods & UploadDialogMethods & CustomDialogMethods & NavigateMethods;
 /**
  * These methods can be used to asyncronously load additional information your

package/manifest.json

@@ -3129,13 +3129,34 @@
           },
           "theme": {
             "comment": {
-              "markdownText": "An object containing the theme colors for the current DatoCMS project."
+              "markdownText": "An object containing the theme colors for the current DatoCMS project.",
+              "deprecatedMarkdownText": "Use `cssDesignTokens` instead. This property is kept\nfor backward compatibility with third-party plugins."
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 106
+              "lineNumber": 111
             },
             "type": "Theme"
+          },
+          "cssDesignTokens": {
+            "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": "cssDesignTokens"
+          },
+          "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` two ways:\nthe `data-color-scheme=\"light\"` / `data-color-scheme=\"dark\"` attribute,\nso plugin CSS can branch with `[data-color-scheme=\"dark\"] { … }`\nselectors; and the actual `color-scheme` CSS property, so `light-dark()`\nresolves to the correct branch (and native form controls / scrollbars\nmatch) everywhere in the plugin frame. For non-CSS decisions (choosing a\nlogo asset, a syntax-highlighting preset, …) branch on `ctx.colorScheme`\ndirectly."
+            },
+            "location": {
+              "filePath": "src/ctx/base.ts",
+              "lineNumber": 134
+            },
+            "type": "'light' | 'dark'"
           }
         }
       },
@@ -3151,7 +3172,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 116
+              "lineNumber": 144
             },
             "type": "Partial<Record<string, ItemType>>"
           },
@@ -3161,7 +3182,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 123
+              "lineNumber": 151
             },
             "type": "Partial<Record<string, Field>>"
           },
@@ -3171,7 +3192,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 130
+              "lineNumber": 158
             },
             "type": "Partial<Record<string, Fieldset>>"
           },
@@ -3181,7 +3202,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 137
+              "lineNumber": 165
             },
             "type": "Partial<Record<string, User>>"
           },
@@ -3191,7 +3212,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 144
+              "lineNumber": 172
             },
             "type": "Partial<Record<string, SsoUser>>"
           }
@@ -3212,7 +3233,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 187
+              "lineNumber": 235
             },
             "type": "(itemTypeId: string) => Promise<Field[]>"
           },
@@ -3223,7 +3244,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 206
+              "lineNumber": 254
             },
             "type": "(itemTypeId: string) => Promise<Fieldset[]>"
           },
@@ -3234,7 +3255,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 223
+              "lineNumber": 271
             },
             "type": "() => Promise<Field[]>"
           },
@@ -3245,7 +3266,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 236
+              "lineNumber": 284
             },
             "type": "() => Promise<User[]>"
           },
@@ -3256,7 +3277,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 249
+              "lineNumber": 297
             },
             "type": "() => Promise<SsoUser[]>"
           }
@@ -3275,7 +3296,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 271
+              "lineNumber": 319
             },
             "type": "(params: Record<string, unknown>) => Promise<void>"
           },
@@ -3286,7 +3307,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 322
+              "lineNumber": 370
             },
             "type": "(\n    fieldId: string,\n    changes: FieldAppearanceChange[],\n  ) => Promise<void>"
           }
@@ -3305,7 +3326,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 427
+              "lineNumber": 475
             },
             "type": "(message: string) => Promise<void>"
           },
@@ -3316,7 +3337,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 442
+              "lineNumber": 490
             },
             "type": "(message: string) => Promise<void>"
           },
@@ -3327,7 +3348,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 466
+              "lineNumber": 514
             },
             "type": "<CtaValue = unknown>(\n    toast: Toast<CtaValue>,\n  ) => Promise<CtaValue | null>"
           }
@@ -3346,7 +3367,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 352
+              "lineNumber": 400
             },
             "type": "(itemTypeId: string) => Promise<Item | null>"
           },
@@ -3357,7 +3378,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 373
+              "lineNumber": 421
             },
             "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  }"
           },
@@ -3368,7 +3389,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 405
+              "lineNumber": 453
             },
             "type": "(itemId: string) => Promise<Item | null>"
           }
@@ -3387,7 +3408,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 493
+              "lineNumber": 541
             },
             "type": "{\n    (options: { multiple: true }): Promise<Upload[] | null>;\n    (options?: { multiple: false }): Promise<Upload | null>;\n  }"
           },
@@ -3398,7 +3419,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 521
+              "lineNumber": 569
             },
             "type": "(\n    uploadId: string,\n  ) => Promise<(Upload & { deleted?: true }) | null>"
           },
@@ -3409,7 +3430,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 549
+              "lineNumber": 597
             },
             "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>"
           }
@@ -3428,7 +3449,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 580
+              "lineNumber": 628
             },
             "type": "(modal: Modal) => Promise<unknown>"
           },
@@ -3439,7 +3460,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 617
+              "lineNumber": 665
             },
             "type": "(options: ConfirmOptions) => Promise<unknown>"
           }
@@ -3458,7 +3479,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 631
+              "lineNumber": 679
             },
             "type": "(path: string) => Promise<void>"
           }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "datocms-plugin-sdk",
-  "version": "2.1.5",
+  "version": "2.2.0-alpha.2",
   "description": "DatoCMS Plugin SDK",
   "keywords": [
     "datocms",
@@ -30,7 +30,8 @@
   "scripts": {
     "build": "npm run generate-manifest && tsc && tsc --project ./tsconfig.esnext.json",
     "generate-manifest": "tsx generateManifest.ts && biome format --write src/manifest.ts",
-    "prebuild": "rimraf dist"
+    "prebuild": "rimraf dist",
+    "install-in-place": "npm run build && rm -rf $INSTALL_PATH/node_modules/datocms-plugin-sdk/dist && cp -rf dist manifest.json $INSTALL_PATH/node_modules/datocms-plugin-sdk"
   },
   "bugs": {
     "url": "https://github.com/datocms/plugins-sdk/issues"
@@ -46,5 +47,5 @@
     "glob": "^11.0.0",
     "typescript": "^5.6.2"
   },
-  "gitHead": "1fc2f5b9c06a8bac49bd0e2cf731e599415ce010"
+  "gitHead": "2db7d26fc8a8c765621f30b2e1363af6036778c0"
 }

package/src/connect.ts

@@ -136,6 +136,21 @@ 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.colorScheme === next) return;
+  document.documentElement.dataset.colorScheme = next;
+  // Also set the actual `color-scheme` CSS property on the root so that
+  // `light-dark()` resolves to the correct branch and native form controls /
+  // scrollbars match — everywhere in the plugin frame, including DOM rendered
+  // outside any `Canvas`/portal. The `data-color-scheme` attribute above is
+  // just a hook for explicit CSS branching; it doesn't drive `light-dark()`.
+  document.documentElement.style.colorScheme = next;
+}
+
 export async function connect(
   rawConfiguration: Partial<FullConnectParameters> = {},
 ): Promise<void> {
@@ -167,7 +182,7 @@ export async function connect(
 
   const penpalConnection = connectToParent({
     methods: {
-      sdkVersion: () => '0.3.0',
+      sdkVersion: () => '0.3.1',
       implementedHooks: () =>
         Object.fromEntries(
           Object.keys(rawConfiguration).map((hook) => {
@@ -185,6 +200,7 @@ export async function connect(
         ),
       ),
       onChange(newSettings: unknown) {
+        applyColorScheme(newSettings);
         if (onChangeListener) {
           onChangeListener(newSettings);
         }
@@ -212,6 +228,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

@@ -102,8 +102,36 @@ 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 `cssDesignTokens` 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.
+   */
+  cssDesignTokens: cssDesignTokens;
+
+  /**
+   * 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` two ways:
+   * the `data-color-scheme="light"` / `data-color-scheme="dark"` attribute,
+   * so plugin CSS can branch with `[data-color-scheme="dark"] { … }`
+   * selectors; and the actual `color-scheme` CSS property, so `light-dark()`
+   * resolves to the correct branch (and native form controls / scrollbars
+   * match) everywhere in the plugin frame. For non-CSS decisions (choosing a
+   * logo asset, a syntax-highlighting preset, …) branch on `ctx.colorScheme`
+   * directly.
+   */
+  colorScheme: 'light' | 'dark';
 };
 
 /**
@@ -144,7 +172,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 `cssDesignTokens` instead. This type is kept for
+ *   backward compatibility with third-party plugins.
+ */
 export type Theme = {
   primaryColor: string;
   accentColor: string;
@@ -153,6 +186,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 cssDesignTokens = Record<string, string>;
+
 export type BaseMethods = LoadDataMethods &
   UpdatePluginParametersMethods &
   ToastMethods &