datocms-plugin-sdk 2.1.1 → 3.0.0-alpha.0

package/manifest.json

@@ -3109,13 +3109,24 @@
           },
           "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 `semanticColorTokensTheme` instead. This property is kept\nfor backward compatibility with third-party plugins."
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 87
+              "lineNumber": 92
             },
             "type": "Theme"
+          },
+          "semanticColorTokensTheme": {
+            "comment": {
+              "markdownText": "Semantic color tokens for the current DatoCMS project, pre-computed by\nthe host. Only available on DatoCMS hosts that support the new token\nsystem."
+            },
+            "location": {
+              "filePath": "src/ctx/base.ts",
+              "lineNumber": 99
+            },
+            "type": "SemanticColorTokensTheme"
           }
         }
       },
@@ -3131,7 +3142,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 97
+              "lineNumber": 109
             },
             "type": "Partial<Record<string, ItemType>>"
           },
@@ -3141,7 +3152,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 104
+              "lineNumber": 116
             },
             "type": "Partial<Record<string, Field>>"
           },
@@ -3151,7 +3162,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 111
+              "lineNumber": 123
             },
             "type": "Partial<Record<string, Fieldset>>"
           },
@@ -3161,7 +3172,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 118
+              "lineNumber": 130
             },
             "type": "Partial<Record<string, User>>"
           },
@@ -3171,7 +3182,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 125
+              "lineNumber": 137
             },
             "type": "Partial<Record<string, SsoUser>>"
           }
@@ -3192,7 +3203,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 168
+              "lineNumber": 341
             },
             "type": "(itemTypeId: string) => Promise<Field[]>"
           },
@@ -3203,7 +3214,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 187
+              "lineNumber": 360
             },
             "type": "(itemTypeId: string) => Promise<Fieldset[]>"
           },
@@ -3214,7 +3225,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 204
+              "lineNumber": 377
             },
             "type": "() => Promise<Field[]>"
           },
@@ -3225,7 +3236,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 217
+              "lineNumber": 390
             },
             "type": "() => Promise<User[]>"
           },
@@ -3236,7 +3247,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 230
+              "lineNumber": 403
             },
             "type": "() => Promise<SsoUser[]>"
           }
@@ -3255,7 +3266,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 252
+              "lineNumber": 425
             },
             "type": "(params: Record<string, unknown>) => Promise<void>"
           },
@@ -3266,7 +3277,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 303
+              "lineNumber": 476
             },
             "type": "(\n    fieldId: string,\n    changes: FieldAppearanceChange[],\n  ) => Promise<void>"
           }
@@ -3285,7 +3296,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 408
+              "lineNumber": 581
             },
             "type": "(message: string) => Promise<void>"
           },
@@ -3296,7 +3307,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 423
+              "lineNumber": 596
             },
             "type": "(message: string) => Promise<void>"
           },
@@ -3307,7 +3318,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 447
+              "lineNumber": 620
             },
             "type": "<CtaValue = unknown>(\n    toast: Toast<CtaValue>,\n  ) => Promise<CtaValue | null>"
           }
@@ -3326,7 +3337,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 333
+              "lineNumber": 506
             },
             "type": "(itemTypeId: string) => Promise<Item | null>"
           },
@@ -3337,7 +3348,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 354
+              "lineNumber": 527
             },
             "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  }"
           },
@@ -3348,7 +3359,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 386
+              "lineNumber": 559
             },
             "type": "(itemId: string) => Promise<Item | null>"
           }
@@ -3367,7 +3378,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 474
+              "lineNumber": 647
             },
             "type": "{\n    (options: { multiple: true }): Promise<Upload[] | null>;\n    (options?: { multiple: false }): Promise<Upload | null>;\n  }"
           },
@@ -3378,7 +3389,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 502
+              "lineNumber": 675
             },
             "type": "(\n    uploadId: string,\n  ) => Promise<(Upload & { deleted?: true }) | null>"
           },
@@ -3389,7 +3400,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 530
+              "lineNumber": 703
             },
             "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>"
           }
@@ -3408,7 +3419,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 561
+              "lineNumber": 734
             },
             "type": "(modal: Modal) => Promise<unknown>"
           },
@@ -3419,7 +3430,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 598
+              "lineNumber": 771
             },
             "type": "(options: ConfirmOptions) => Promise<unknown>"
           }
@@ -3438,7 +3449,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 612
+              "lineNumber": 785
             },
             "type": "(path: string) => Promise<void>"
           }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "datocms-plugin-sdk",
-  "version": "2.1.1",
+  "version": "3.0.0-alpha.0",
   "description": "DatoCMS Plugin SDK",
   "keywords": [
     "datocms",
@@ -46,5 +46,5 @@
     "glob": "^11.0.0",
     "typescript": "^5.6.2"
   },
-  "gitHead": "a8fcf4b05fe22e331b2fd95303793088aa15fedf"
+  "gitHead": "01c46332e40377d305c3abd262c3d1840385ec49"
 }

package/src/ctx/base.ts

@@ -83,8 +83,20 @@ 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. Only available on DatoCMS hosts that support the new token
+   * system.
+   */
+  semanticColorTokensTheme: SemanticColorTokensTheme;
 };
 
 /**
@@ -125,7 +137,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 +151,162 @@ export type Theme = {
   darkColor: string;
 };
 
+/**
+ * Known semantic color tokens provided by the DatoCMS host.
+ * All properties are optional — the host may not send all of them.
+ *
+ * camelCase keys are converted to kebab-case CSS custom properties via
+ * `camelToDash`. For example, `colorRaisedSurface` becomes
+ * `--color-raised-surface`.
+ */
+type KnownSemanticColorTokens = {
+  /* --- Standalone --- */
+  colorSurface?: string;
+  colorSurfaceHover?: string;
+  colorSurfaceMuted?: string;
+  colorInk?: string;
+  colorInkSubtle?: string;
+  colorInkHover?: string;
+  colorInkMuted?: string;
+  colorInkPlaceholder?: string;
+  colorInkPrimary?: string;
+  colorInkAccent?: string;
+  colorInkDisabled?: string;
+  colorBorder?: string;
+  colorBorderHover?: string;
+
+  /* --- Context: raised --- */
+  colorRaisedSurface?: string;
+  colorRaisedSurfaceHover?: string;
+  colorRaisedSurfaceActive?: string;
+
+  /* --- Context: primary --- */
+  colorPrimarySurface?: string;
+  colorPrimarySurfaceHover?: string;
+  colorPrimarySurfaceActive?: string;
+  colorPrimarySurfaceMuted?: string;
+  colorPrimaryInk?: string;
+  colorPrimaryBorder?: string;
+
+  /* --- Context: tinted --- */
+  colorTintedSurface?: string;
+  colorTintedSurfaceHover?: string;
+  colorTintedSurfaceActive?: string;
+  colorTintedInk?: string;
+
+  /* --- Context: accent --- */
+  colorAccentSurface?: string;
+  colorAccentInk?: string;
+
+  /* --- Context: selected --- */
+  colorSelectedSurface?: string;
+  colorSelectedInk?: string;
+  colorSelectedBorder?: string;
+
+  /* --- Context: disabled --- */
+  colorDisabledSurface?: string;
+  colorDisabledInk?: string;
+
+  /* --- Context: danger --- */
+  colorDangerSurface?: string;
+  colorDangerInk?: string;
+
+  /* --- Context: enterprise --- */
+  colorEnterpriseSurface?: string;
+
+  /* --- Context: focus --- */
+  colorFocusBorder?: string;
+  colorFocusOutline?: string;
+
+  /* --- Feedback --- */
+  colorFeedbackFailInk?: string;
+  colorFeedbackFailBorder?: string;
+  colorFeedbackFailOutline?: string;
+  colorFeedbackWarningInk?: string;
+  colorFeedbackWarningSurface?: string;
+  colorFeedbackSuccessInk?: string;
+  colorFeedbackWarningBorder?: string;
+  colorFeedbackSuccessBorder?: string;
+
+  /* --- Context: highlight --- */
+  colorHighlightSurface?: string;
+
+  /* --- Diffs --- */
+  colorDiffAddedSurface?: string;
+  colorDiffRemovedSurface?: string;
+  colorDiffChangedSurface?: string;
+  colorDiffAddedSurfaceSubtle?: string;
+  colorDiffRemovedSurfaceSubtle?: string;
+  colorDiffChangedSurfaceSubtle?: string;
+  colorDiffAddedOutlineSubtle?: string;
+  colorDiffRemovedOutlineSubtle?: string;
+  colorDiffChangedOutlineSubtle?: string;
+  colorDiffChangedBorder?: string;
+  colorDiffChangedBorderNegative?: string;
+
+  /* --- Status --- */
+  colorStatusDraftInk?: string;
+  colorStatusOutdatedInk?: string;
+  colorStatusPublishedInk?: string;
+
+  /* --- Backdrop --- */
+  colorBackdropSurface?: string;
+  colorBackdropInk?: string;
+
+  /* --- Overlay --- */
+  colorOverlaySurface?: string;
+  colorOverlaySurfaceSubtle?: string;
+  colorOverlayInk?: string;
+
+  /* --- Stacked --- */
+  colorStackedSurfaceBase?: string;
+  colorStackedSurface?: string;
+  colorStackedSurfaceRaised?: string;
+  colorStackedInk?: string;
+  colorStackedInkSubtle?: string;
+  colorStackedBorder?: string;
+  colorStackedSurfaceHover?: string;
+  colorStackedSurfaceTranslucent?: string;
+  colorStackedSurfaceButton?: string;
+  colorStackedSurfaceButtonActive?: string;
+
+  /* --- Progress --- */
+  colorProgressTrack?: string;
+  colorProgressFill?: string;
+  colorProgressFillHover?: string;
+
+  /* --- Tooltip --- */
+  colorTooltipSurface?: string;
+  colorTooltipSurfaceHover?: string;
+  colorTooltipInk?: string;
+  colorTooltipInkSubtle?: string;
+
+  /* --- Code --- */
+  colorCodeSurface?: string;
+  colorCodeInk?: string;
+
+  /* --- Shadows --- */
+  colorShadowSubtle?: string;
+  colorShadow?: string;
+  colorShadowStrong?: string;
+
+  /* --- Scrollbar --- */
+  colorScrollbar?: string;
+
+  /* --- Shadow composites --- */
+  shadowElevated?: string;
+  shadowFloat?: string;
+  shadowAmbient?: string;
+};
+
+/**
+ * Semantic color tokens for the current DatoCMS project, pre-computed by the
+ * host. Known tokens get autocomplete; unknown tokens are accepted via the
+ * index signature for forward compatibility.
+ */
+export type SemanticColorTokensTheme = KnownSemanticColorTokens &
+  Record<string, string>;
+
 export type BaseMethods = LoadDataMethods &
   UpdatePluginParametersMethods &
   ToastMethods &

package/src/manifest.ts

@@ -3340,13 +3340,26 @@ 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: 92,
             },
             type: 'Theme',
           },
+          semanticColorTokensTheme: {
+            comment: {
+              markdownText:
+                'Semantic color tokens for the current DatoCMS project, pre-computed by\nthe host. Only available on DatoCMS hosts that support the new token\nsystem.',
+            },
+            location: {
+              filePath: 'src/ctx/base.ts',
+              lineNumber: 99,
+            },
+            type: 'SemanticColorTokensTheme',
+          },
         },
       },
       {
@@ -3363,7 +3376,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 97,
+              lineNumber: 109,
             },
             type: 'Partial<Record<string, ItemType>>',
           },
@@ -3374,7 +3387,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 104,
+              lineNumber: 116,
             },
             type: 'Partial<Record<string, Field>>',
           },
@@ -3385,7 +3398,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 111,
+              lineNumber: 123,
             },
             type: 'Partial<Record<string, Fieldset>>',
           },
@@ -3396,7 +3409,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 118,
+              lineNumber: 130,
             },
             type: 'Partial<Record<string, User>>',
           },
@@ -3407,7 +3420,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 125,
+              lineNumber: 137,
             },
             type: 'Partial<Record<string, SsoUser>>',
           },
@@ -3431,7 +3444,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 168,
+              lineNumber: 341,
             },
             type: '(itemTypeId: string) => Promise<Field[]>',
           },
@@ -3444,7 +3457,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 187,
+              lineNumber: 360,
             },
             type: '(itemTypeId: string) => Promise<Fieldset[]>',
           },
@@ -3457,7 +3470,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 204,
+              lineNumber: 377,
             },
             type: '() => Promise<Field[]>',
           },
@@ -3470,7 +3483,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 217,
+              lineNumber: 390,
             },
             type: '() => Promise<User[]>',
           },
@@ -3483,7 +3496,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 230,
+              lineNumber: 403,
             },
             type: '() => Promise<SsoUser[]>',
           },
@@ -3505,7 +3518,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 252,
+              lineNumber: 425,
             },
             type: '(params: Record<string, unknown>) => Promise<void>',
           },
@@ -3518,7 +3531,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 303,
+              lineNumber: 476,
             },
             type: '(\n    fieldId: string,\n    changes: FieldAppearanceChange[],\n  ) => Promise<void>',
           },
@@ -3540,7 +3553,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 408,
+              lineNumber: 581,
             },
             type: '(message: string) => Promise<void>',
           },
@@ -3553,7 +3566,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 423,
+              lineNumber: 596,
             },
             type: '(message: string) => Promise<void>',
           },
@@ -3566,7 +3579,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 447,
+              lineNumber: 620,
             },
             type: '<CtaValue = unknown>(\n    toast: Toast<CtaValue>,\n  ) => Promise<CtaValue | null>',
           },
@@ -3588,7 +3601,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 333,
+              lineNumber: 506,
             },
             type: '(itemTypeId: string) => Promise<Item | null>',
           },
@@ -3601,7 +3614,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 354,
+              lineNumber: 527,
             },
             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 +3627,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 386,
+              lineNumber: 559,
             },
             type: '(itemId: string) => Promise<Item | null>',
           },
@@ -3636,7 +3649,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 474,
+              lineNumber: 647,
             },
             type: '{\n    (options: { multiple: true }): Promise<Upload[] | null>;\n    (options?: { multiple: false }): Promise<Upload | null>;\n  }',
           },
@@ -3649,7 +3662,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 502,
+              lineNumber: 675,
             },
             type: '(\n    uploadId: string,\n  ) => Promise<(Upload & { deleted?: true }) | null>',
           },
@@ -3662,7 +3675,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 530,
+              lineNumber: 703,
             },
             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 +3697,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 561,
+              lineNumber: 734,
             },
             type: '(modal: Modal) => Promise<unknown>',
           },
@@ -3697,7 +3710,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 598,
+              lineNumber: 771,
             },
             type: '(options: ConfirmOptions) => Promise<unknown>',
           },
@@ -3718,7 +3731,7 @@ export const manifest: Manifest = {
             },
             location: {
               filePath: 'src/ctx/base.ts',
-              lineNumber: 612,
+              lineNumber: 785,
             },
             type: '(path: string) => Promise<void>',
           },