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

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

@@ -62,8 +62,30 @@ 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 `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;
+    /**
+     * 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';
 };
 /**
  * These properties provide access to "entity repos", that is, the collection of
@@ -98,7 +120,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;
@@ -106,6 +133,114 @@ export type Theme = {
     lightColor: string;
     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 = {
+    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;
+    colorRaisedSurface?: string;
+    colorRaisedSurfaceHover?: string;
+    colorRaisedSurfaceActive?: string;
+    colorPrimarySurface?: string;
+    colorPrimarySurfaceHover?: string;
+    colorPrimarySurfaceActive?: string;
+    colorPrimarySurfaceMuted?: string;
+    colorPrimaryInk?: string;
+    colorPrimaryBorder?: string;
+    colorTintedSurface?: string;
+    colorTintedSurfaceHover?: string;
+    colorTintedSurfaceActive?: string;
+    colorTintedInk?: string;
+    colorAccentSurface?: string;
+    colorAccentInk?: string;
+    colorSelectedSurface?: string;
+    colorSelectedInk?: string;
+    colorSelectedBorder?: string;
+    colorDisabledSurface?: string;
+    colorDisabledInk?: string;
+    colorDangerSurface?: string;
+    colorDangerInk?: string;
+    colorEnterpriseSurface?: string;
+    colorFocusBorder?: string;
+    colorFocusOutline?: string;
+    colorFeedbackFailInk?: string;
+    colorFeedbackFailBorder?: string;
+    colorFeedbackFailOutline?: string;
+    colorFeedbackWarningInk?: string;
+    colorFeedbackWarningSurface?: string;
+    colorFeedbackSuccessInk?: string;
+    colorFeedbackWarningBorder?: string;
+    colorFeedbackSuccessBorder?: string;
+    colorHighlightSurface?: string;
+    colorDiffAddedSurface?: string;
+    colorDiffRemovedSurface?: string;
+    colorDiffChangedSurface?: string;
+    colorDiffAddedSurfaceSubtle?: string;
+    colorDiffRemovedSurfaceSubtle?: string;
+    colorDiffChangedSurfaceSubtle?: string;
+    colorDiffAddedOutlineSubtle?: string;
+    colorDiffRemovedOutlineSubtle?: string;
+    colorDiffChangedOutlineSubtle?: string;
+    colorDiffChangedBorder?: string;
+    colorDiffChangedBorderNegative?: string;
+    colorStatusDraftInk?: string;
+    colorStatusOutdatedInk?: string;
+    colorStatusPublishedInk?: string;
+    colorBackdropSurface?: string;
+    colorBackdropInk?: string;
+    colorOverlaySurface?: string;
+    colorOverlaySurfaceSubtle?: string;
+    colorOverlayInk?: string;
+    colorStackedSurfaceBase?: string;
+    colorStackedSurface?: string;
+    colorStackedSurfaceRaised?: string;
+    colorStackedInk?: string;
+    colorStackedInkSubtle?: string;
+    colorStackedBorder?: string;
+    colorStackedSurfaceHover?: string;
+    colorStackedSurfaceTranslucent?: string;
+    colorStackedSurfaceButton?: string;
+    colorStackedSurfaceButtonActive?: string;
+    colorProgressTrack?: string;
+    colorProgressFill?: string;
+    colorProgressFillHover?: string;
+    colorTooltipSurface?: string;
+    colorTooltipSurfaceHover?: string;
+    colorTooltipInk?: string;
+    colorTooltipInkSubtle?: string;
+    colorCodeSurface?: string;
+    colorCodeInk?: string;
+    colorShadowSubtle?: string;
+    colorShadow?: string;
+    colorShadowStrong?: string;
+    colorScrollbar?: string;
+    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 & ItemDialogMethods & UploadDialogMethods & CustomDialogMethods & NavigateMethods;
 /**
  * These methods can be used to asyncronously load additional information your

package/dist/esm/manifest.js

@@ -3110,13 +3110,34 @@ export var manifest = {
                     theme: {
                         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',
+                    },
+                    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: 111,
+                        },
+                        type: "'light' | 'dark'",
+                    },
                 },
             },
             {
@@ -3131,7 +3152,7 @@ export var manifest = {
                         },
                         location: {
                             filePath: 'src/ctx/base.ts',
-                            lineNumber: 97,
+                            lineNumber: 121,
                         },
                         type: 'Partial<Record<string, ItemType>>',
                     },
@@ -3141,7 +3162,7 @@ export var manifest = {
                         },
                         location: {
                             filePath: 'src/ctx/base.ts',
-                            lineNumber: 104,
+                            lineNumber: 128,
                         },
                         type: 'Partial<Record<string, Field>>',
                     },
@@ -3151,7 +3172,7 @@ export var manifest = {
                         },
                         location: {
                             filePath: 'src/ctx/base.ts',
-                            lineNumber: 111,
+                            lineNumber: 135,
                         },
                         type: 'Partial<Record<string, Fieldset>>',
                     },
@@ -3161,7 +3182,7 @@ export var manifest = {
                         },
                         location: {
                             filePath: 'src/ctx/base.ts',
-                            lineNumber: 118,
+                            lineNumber: 142,
                         },
                         type: 'Partial<Record<string, User>>',
                     },
@@ -3171,7 +3192,7 @@ export var manifest = {
                         },
                         location: {
                             filePath: 'src/ctx/base.ts',
-                            lineNumber: 125,
+                            lineNumber: 149,
                         },
                         type: 'Partial<Record<string, SsoUser>>',
                     },
@@ -3192,7 +3213,7 @@ export var manifest = {
                         },
                         location: {
                             filePath: 'src/ctx/base.ts',
-                            lineNumber: 168,
+                            lineNumber: 353,
                         },
                         type: '(itemTypeId: string) => Promise<Field[]>',
                     },
@@ -3203,7 +3224,7 @@ export var manifest = {
                         },
                         location: {
                             filePath: 'src/ctx/base.ts',
-                            lineNumber: 187,
+                            lineNumber: 372,
                         },
                         type: '(itemTypeId: string) => Promise<Fieldset[]>',
                     },
@@ -3214,7 +3235,7 @@ export var manifest = {
                         },
                         location: {
                             filePath: 'src/ctx/base.ts',
-                            lineNumber: 204,
+                            lineNumber: 389,
                         },
                         type: '() => Promise<Field[]>',
                     },
@@ -3225,7 +3246,7 @@ export var manifest = {
                         },
                         location: {
                             filePath: 'src/ctx/base.ts',
-                            lineNumber: 217,
+                            lineNumber: 402,
                         },
                         type: '() => Promise<User[]>',
                     },
@@ -3236,7 +3257,7 @@ export var manifest = {
                         },
                         location: {
                             filePath: 'src/ctx/base.ts',
-                            lineNumber: 230,
+                            lineNumber: 415,
                         },
                         type: '() => Promise<SsoUser[]>',
                     },
@@ -3255,7 +3276,7 @@ export var manifest = {
                         },
                         location: {
                             filePath: 'src/ctx/base.ts',
-                            lineNumber: 252,
+                            lineNumber: 437,
                         },
                         type: '(params: Record<string, unknown>) => Promise<void>',
                     },
@@ -3266,7 +3287,7 @@ export var manifest = {
                         },
                         location: {
                             filePath: 'src/ctx/base.ts',
-                            lineNumber: 303,
+                            lineNumber: 488,
                         },
                         type: '(\n    fieldId: string,\n    changes: FieldAppearanceChange[],\n  ) => Promise<void>',
                     },
@@ -3285,7 +3306,7 @@ export var manifest = {
                         },
                         location: {
                             filePath: 'src/ctx/base.ts',
-                            lineNumber: 408,
+                            lineNumber: 593,
                         },
                         type: '(message: string) => Promise<void>',
                     },
@@ -3296,7 +3317,7 @@ export var manifest = {
                         },
                         location: {
                             filePath: 'src/ctx/base.ts',
-                            lineNumber: 423,
+                            lineNumber: 608,
                         },
                         type: '(message: string) => Promise<void>',
                     },
@@ -3307,7 +3328,7 @@ export var manifest = {
                         },
                         location: {
                             filePath: 'src/ctx/base.ts',
-                            lineNumber: 447,
+                            lineNumber: 632,
                         },
                         type: '<CtaValue = unknown>(\n    toast: Toast<CtaValue>,\n  ) => Promise<CtaValue | null>',
                     },
@@ -3326,7 +3347,7 @@ export var manifest = {
                         },
                         location: {
                             filePath: 'src/ctx/base.ts',
-                            lineNumber: 333,
+                            lineNumber: 518,
                         },
                         type: '(itemTypeId: string) => Promise<Item | null>',
                     },
@@ -3337,7 +3358,7 @@ export var manifest = {
                         },
                         location: {
                             filePath: 'src/ctx/base.ts',
-                            lineNumber: 354,
+                            lineNumber: 539,
                         },
                         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 +3369,7 @@ export var manifest = {
                         },
                         location: {
                             filePath: 'src/ctx/base.ts',
-                            lineNumber: 386,
+                            lineNumber: 571,
                         },
                         type: '(itemId: string) => Promise<Item | null>',
                     },
@@ -3367,7 +3388,7 @@ export var manifest = {
                         },
                         location: {
                             filePath: 'src/ctx/base.ts',
-                            lineNumber: 474,
+                            lineNumber: 659,
                         },
                         type: '{\n    (options: { multiple: true }): Promise<Upload[] | null>;\n    (options?: { multiple: false }): Promise<Upload | null>;\n  }',
                     },
@@ -3378,7 +3399,7 @@ export var manifest = {
                         },
                         location: {
                             filePath: 'src/ctx/base.ts',
-                            lineNumber: 502,
+                            lineNumber: 687,
                         },
                         type: '(\n    uploadId: string,\n  ) => Promise<(Upload & { deleted?: true }) | null>',
                     },
@@ -3389,7 +3410,7 @@ export var manifest = {
                         },
                         location: {
                             filePath: 'src/ctx/base.ts',
-                            lineNumber: 530,
+                            lineNumber: 715,
                         },
                         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 +3429,7 @@ export var manifest = {
                         },
                         location: {
                             filePath: 'src/ctx/base.ts',
-                            lineNumber: 561,
+                            lineNumber: 746,
                         },
                         type: '(modal: Modal) => Promise<unknown>',
                     },
@@ -3419,7 +3440,7 @@ export var manifest = {
                         },
                         location: {
                             filePath: 'src/ctx/base.ts',
-                            lineNumber: 598,
+                            lineNumber: 783,
                         },
                         type: '(options: ConfirmOptions) => Promise<unknown>',
                     },
@@ -3438,7 +3459,7 @@ export var manifest = {
                         },
                         location: {
                             filePath: 'src/ctx/base.ts',
-                            lineNumber: 612,
+                            lineNumber: 797,
                         },
                         type: '(path: string) => Promise<void>',
                     },