platform-types 1.10.695 → 1.10.696

package/dist/cjs/storefrontTheme.js

@@ -2,6 +2,16 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveStorefrontTheme = exports.resolveStorefrontEffectiveSettings = exports.storefrontGlobalSettingsLayer = exports.storefrontContrastRatio = void 0;
 const storefrontDesignRegistry_ts_1 = require("./storefrontDesignRegistry.js");
+const WARNING_SETTING = {
+    link: 'primaryColor',
+    button: 'primaryColor',
+    focus: 'accentColor',
+};
+const SURFACE_SETTING = {
+    page: 'backgroundColor',
+    header: 'headerColor',
+    footer: 'footerColor',
+};
 const channels = (color) => [
     Number.parseInt(color.slice(1, 3), 16),
     Number.parseInt(color.slice(3, 5), 16),
@@ -94,7 +104,13 @@ exports.resolveStorefrontEffectiveSettings = resolveStorefrontEffectiveSettings;
  * resolves defaults plus the design only — correct solely while no GLOBAL design setting
  * is set, so a caller serving or reporting on a storefront passes the row (the edge
  * renderer's `theme-color` is the one exception, design-only by its read grant). Passing
- * already-effective settings as `overrides` rebuilds the same theme.
+ * already-effective settings as `overrides` rebuilds the same tokens.
+ *
+ * `warnings` names only adjustments the design itself caused: the adjusted colour, or the
+ * background of the surface it sits on, is set in `overrides`. No single colour reads at 4.5:1 on
+ * both a white page and its dark-mode counterpart, so a platform or GLOBAL default is always
+ * adjusted somewhere, and a shop that chose nothing has nothing to act on. Pass the design's own
+ * settings, not effective ones, or every default reads as chosen.
  */
 const resolveStorefrontTheme = (overrides = {}, globalsRow) => {
     const settings = (0, exports.resolveStorefrontEffectiveSettings)(overrides, globalsRow);
@@ -127,7 +143,7 @@ const resolveStorefrontTheme = (overrides = {}, globalsRow) => {
         },
         shape: { borderRadius: 4 },
         spacing: 8,
-        warnings,
+        warnings: warnings.filter(({ role, surface }) => overrides[WARNING_SETTING[role]] !== undefined || overrides[SURFACE_SETTING[surface]] !== undefined),
     };
 };
 exports.resolveStorefrontTheme = resolveStorefrontTheme;

package/dist/storefrontDesign.d.ts

@@ -336,6 +336,11 @@ declare global {
     type StorefrontDesignErrorCode = 'STOREFRONT_DESIGN_INVALID' | 'STOREFRONT_SCHEMA_UNSUPPORTED' | 'STOREFRONT_REVISION_CONFLICT' | 'STOREFRONT_DRAFT_NOT_INITIALIZED' | 'STOREFRONT_REQUEST_EXPIRED' | 'STOREFRONT_PUBLICATION_NOT_FOUND'
     /** Web `GET /store` and `GET /literals` `503`: the stored publication cannot be served; retry later. */
      | 'STOREFRONT_PUBLICATION_UNAVAILABLE' | 'STOREFRONT_OPERATION_NOT_FOUND' | 'STOREFRONT_DRAFT_UNAVAILABLE' | 'IDEMPOTENCY_CONFLICT' | 'STOREFRONT_EDITOR_REQUIRED' | 'STOREFRONT_ASSET_NOT_READY' | 'STOREFRONT_PREVIEW_EXPIRED' | 'STOREFRONT_PREVIEW_REVOKED' | 'STOREFRONT_PREVIEW_FORBIDDEN' | 'STOREFRONT_PREVIEW_UNAVAILABLE';
+    /**
+     * A legacy value the editor baseline could not carry. The baseline no longer reports one: every
+     * such value falls back to its default, so a fresh `mappingConflicts` is `[]`. The type stays for a
+     * draft stored before that change, which keeps its conflicts until it is discarded.
+     */
     interface StorefrontDesignMappingConflict {
         path: string;
         code: 'LEGACY_MULTIPLE_PRODUCT_FEEDS' | 'LEGACY_UNMAPPED_CONTENT';
@@ -344,8 +349,10 @@ declare global {
     interface StorefrontEditorBaseline {
         legacyRevision?: number;
         document: StorefrontDesignV1;
+        /** Always `[]`: an invalid colour, an unmapped Home switch, the banner and every refused or oversized literal fall back to defaults. */
         mappingConflicts: StorefrontDesignMappingConflict[];
         legacySourceRevision: string;
+        /** The store's own logo, offered as a suggestion; init copies it into `branding.logo`, and a copy that cannot complete leaves no logo and no conflict. */
         legacyLogo?: {
             source: 'store.photoURL';
             key: string;
@@ -386,6 +393,7 @@ declare global {
         publishedRevision: null;
         document: StorefrontDesignV1;
         dirty: false;
+        /** Always `[]` (see `StorefrontEditorBaseline`). */
         mappingConflicts: StorefrontDesignMappingConflict[];
         legacySourceRevision: string;
     }
@@ -425,6 +433,7 @@ declare global {
         publishedRevision: string | null;
         document: StorefrontDesignV1;
         dirty: boolean;
+        /** Empty for a draft seeded now; only a draft stored before the baseline stopped reporting conflicts carries any. */
         mappingConflicts: StorefrontDesignMappingConflict[];
         legacySourceRevision: string;
         /**
@@ -440,7 +449,7 @@ declare global {
          * content, a link to a disabled or missing page (`DANGLING_REFERENCE`), a slug a published
          * page still owns (`ALIAS_CONFLICT`), a page out of aliases (`ALIAS_LIMIT`), and one
          * `MAPPING_CONFLICT` per unresolved `mappingConflicts` entry, at that entry's path (the
-         * publish refusal itself names the single path `mappingConflicts`). Empty when publishable.
+         * publish refusal itself names the single path `mappingConflicts`; a draft seeded now has none). Empty when publishable.
          * Never blocks a save, and never covers asset readiness, which publish probes on its own
          * (`STOREFRONT_ASSET_NOT_READY`).
          */
@@ -461,6 +470,7 @@ declare global {
     type StorefrontDesignPublishOperationResult = StorefrontDesignPublishResult;
     type StorefrontDesignPublishOperationResponse = StorefrontDesignPublishResponse;
     interface StorefrontDesignPublishResult {
+        /** Only adjustments to a colour the design itself sets; a default colour is never listed. */
         changeSummary: {
             contrastAdjustments: StorefrontThemeWarning[];
         };

package/dist/storefrontTheme.d.ts

@@ -71,7 +71,13 @@ export declare const resolveStorefrontEffectiveSettings: (overrides?: Partial<St
  * resolves defaults plus the design only — correct solely while no GLOBAL design setting
  * is set, so a caller serving or reporting on a storefront passes the row (the edge
  * renderer's `theme-color` is the one exception, design-only by its read grant). Passing
- * already-effective settings as `overrides` rebuilds the same theme.
+ * already-effective settings as `overrides` rebuilds the same tokens.
+ *
+ * `warnings` names only adjustments the design itself caused: the adjusted colour, or the
+ * background of the surface it sits on, is set in `overrides`. No single colour reads at 4.5:1 on
+ * both a white page and its dark-mode counterpart, so a platform or GLOBAL default is always
+ * adjusted somewhere, and a shop that chose nothing has nothing to act on. Pass the design's own
+ * settings, not effective ones, or every default reads as chosen.
  */
 export declare const resolveStorefrontTheme: (overrides?: Partial<StorefrontDesignSettings>, globalsRow?: Record<string, unknown>) => StorefrontResolvedTheme;
 export {};

package/dist/storefrontTheme.js

@@ -1,4 +1,14 @@
 import { resolveStorefrontDesignSettings, validateStorefrontDesignSetting, } from "./storefrontDesignRegistry.js";
+const WARNING_SETTING = {
+    link: 'primaryColor',
+    button: 'primaryColor',
+    focus: 'accentColor',
+};
+const SURFACE_SETTING = {
+    page: 'backgroundColor',
+    header: 'headerColor',
+    footer: 'footerColor',
+};
 const channels = (color) => [
     Number.parseInt(color.slice(1, 3), 16),
     Number.parseInt(color.slice(3, 5), 16),
@@ -88,7 +98,13 @@ export const resolveStorefrontEffectiveSettings = (overrides = {}, globalsRow) =
  * resolves defaults plus the design only — correct solely while no GLOBAL design setting
  * is set, so a caller serving or reporting on a storefront passes the row (the edge
  * renderer's `theme-color` is the one exception, design-only by its read grant). Passing
- * already-effective settings as `overrides` rebuilds the same theme.
+ * already-effective settings as `overrides` rebuilds the same tokens.
+ *
+ * `warnings` names only adjustments the design itself caused: the adjusted colour, or the
+ * background of the surface it sits on, is set in `overrides`. No single colour reads at 4.5:1 on
+ * both a white page and its dark-mode counterpart, so a platform or GLOBAL default is always
+ * adjusted somewhere, and a shop that chose nothing has nothing to act on. Pass the design's own
+ * settings, not effective ones, or every default reads as chosen.
  */
 export const resolveStorefrontTheme = (overrides = {}, globalsRow) => {
     const settings = resolveStorefrontEffectiveSettings(overrides, globalsRow);
@@ -121,6 +137,6 @@ export const resolveStorefrontTheme = (overrides = {}, globalsRow) => {
         },
         shape: { borderRadius: 4 },
         spacing: 8,
-        warnings,
+        warnings: warnings.filter(({ role, surface }) => overrides[WARNING_SETTING[role]] !== undefined || overrides[SURFACE_SETTING[surface]] !== undefined),
     };
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "platform-types",
-	"version": "1.10.695",
+	"version": "1.10.696",
 	"description": "Shared wire and entity contracts for the platform.",
 	"type": "module",
 	"main": "dist/index.js",