@contentful/experience-design-system-types 2.41.1-dev-build-0eca66e2.0 → 2.41.1-dev-build-8f1f54c3.0

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experience-design-system-types",
-  "version": "2.41.1-dev-build-0eca66e2.0",
+  "version": "2.41.1-dev-build-8f1f54c3.0",
   "license": "MIT",
   "type": "module",
   "module": "./dist/src/index.js",

package/dist/src/cdf/build.d.ts

@@ -9,6 +9,10 @@ export interface CDFDocument {
     $schema: typeof CDF_SCHEMA_URL;
     [key: string]: unknown;
 }
+/**
+ * Every document that is saved, previewed or pushed is built here, so this is where a token property that has no kind is
+ * given one: the API rejects it, and the preview does not notice. `onRepair` hears about each repair.
+ */
 export declare function buildCDF(components: Array<{
     key: string;
     entry: CDFComponentEntry;
@@ -17,6 +21,7 @@ export declare function buildCDF(components: Array<{
     entry: CDFTokenEntry;
 }>, opts?: {
     deleteAll?: boolean;
+    onRepair?: (message: string) => void;
 }): CDFDocument | undefined;
 /**
  * Filters a CDF document down to a selected subset of component keys and

package/dist/src/cdf/build.js

@@ -1,3 +1,4 @@
+import { repairTokenKinds } from './repair-token-kinds.js';
 import { CDF_SCHEMA_URL } from './schema.js';
 /** Drops `$required` from slot definitions — the server never reads it and
  * older CDF consumers reject unknown slot fields. */
@@ -34,12 +35,16 @@ function resolveTokenPathCollisions(tokens) {
         return { path, entry: token.entry };
     });
 }
+/**
+ * Every document that is saved, previewed or pushed is built here, so this is where a token property that has no kind is
+ * given one: the API rejects it, and the preview does not notice. `onRepair` hears about each repair.
+ */
 export function buildCDF(components, tokens, opts = {}) {
     if (components.length === 0 && tokens.length === 0 && !opts.deleteAll)
         return undefined;
     const doc = { $schema: CDF_SCHEMA_URL };
     for (const { key, entry } of components) {
-        setAtPath(doc, key, stripUnsupportedSlotFields(entry));
+        setAtPath(doc, key, stripUnsupportedSlotFields(repairTokenKinds(entry, key, tokens, opts.onRepair)));
     }
     for (const { path, entry } of resolveTokenPathCollisions(tokens)) {
         setAtPath(doc, path, entry);

package/dist/src/cdf/repair-token-kinds.d.ts

@@ -0,0 +1,8 @@
+import type { CDFComponentEntry, CDFTokenEntry } from './types.js';
+type Tokens = Array<{
+    path: string;
+    entry: CDFTokenEntry;
+}>;
+/** Gives every token property a `$token.kind`. Says what it did through `note`, so a repair is never silent. */
+export declare function repairTokenKinds(entry: CDFComponentEntry, componentKey: string, tokens: Tokens, note?: (message: string) => void): CDFComponentEntry;
+export {};

package/dist/src/cdf/repair-token-kinds.js

@@ -0,0 +1,46 @@
+/** The warning the agent writes into a description when it left the kind out. Once the kind is settled it is stale, and a description is customer-facing text. */
+const UNRESOLVED_WARNING = /\s*WARNING: token_kind unknown[^\n]*/;
+/**
+ * The token's own type if the property's default names a token that exists, which is the token the property is bound to.
+ * Failing that, the one type shared by every token with the property's name in its path, or undefined when there is not
+ * exactly one.
+ */
+function inferTokenKind(propName, prop, tokens) {
+    const bound = typeof prop.$default === 'string' ? tokens.find(({ path }) => path === prop.$default) : undefined;
+    if (bound)
+        return bound.entry.$type;
+    const name = propName.toLowerCase();
+    const kinds = new Set(tokens.filter(({ path }) => path.toLowerCase().split('.').includes(name)).map(({ entry }) => entry.$type));
+    return kinds.size === 1 ? [...kinds][0] : undefined;
+}
+function withoutWarning(prop) {
+    if (prop.$description === undefined)
+        return prop;
+    const description = prop.$description.replace(UNRESOLVED_WARNING, '').trim();
+    const { $description: _stale, ...rest } = prop;
+    return description ? { ...rest, $description: description } : rest;
+}
+/** Gives every token property a `$token.kind`. Says what it did through `note`, so a repair is never silent. */
+export function repairTokenKinds(entry, componentKey, tokens, note) {
+    const properties = { ...entry.$properties };
+    let repaired = false;
+    for (const [name, prop] of Object.entries(entry.$properties)) {
+        if (prop.$type !== 'token' || prop['$token.kind'])
+            continue;
+        repaired = true;
+        const kind = inferTokenKind(name, prop, tokens);
+        if (kind) {
+            properties[name] = { ...withoutWarning(prop), '$token.kind': kind };
+            note?.(`${componentKey}.${name} had no token kind, so "${kind}" was taken from the token file`);
+        }
+        else {
+            // Its default and allowed list are token paths, which mean nothing on a string property.
+            const plain = { ...withoutWarning(prop), $type: 'string' };
+            delete plain['$token.allowed'];
+            delete plain.$default;
+            properties[name] = plain;
+            note?.(`${componentKey}.${name} had no token kind and none could be told, so it was saved as a string property`);
+        }
+    }
+    return repaired ? { ...entry, $properties: properties } : entry;
+}

package/dist/src/cdf/schema.d.ts

@@ -84,6 +84,7 @@ export declare const cdfJsonSchema: {
                 };
                 readonly '$token.kind': {
                     readonly type: "string";
+                    readonly minLength: 1;
                 };
                 readonly '$token.allowed': {
                     readonly type: "array";
@@ -92,6 +93,19 @@ export declare const cdfJsonSchema: {
                     };
                 };
             };
+            readonly if: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly $type: {
+                        readonly const: "token";
+                    };
+                };
+                readonly required: readonly ["$type"];
+            };
+            readonly then: {
+                readonly type: "object";
+                readonly required: readonly ["$token.kind"];
+            };
             readonly additionalProperties: false;
         };
         readonly slot: {

package/dist/src/cdf/schema.js

@@ -49,9 +49,12 @@ export const cdfJsonSchema = {
                 $required: { type: 'boolean' },
                 $default: {},
                 $values: { type: 'array', items: { type: 'string' } },
-                '$token.kind': { type: 'string' },
+                '$token.kind': { type: 'string', minLength: 1 },
                 '$token.allowed': { type: 'array', items: { type: 'string' } },
             },
+            // The API rejects a token property that does not say which kind of token it takes.
+            if: { type: 'object', properties: { $type: { const: 'token' } }, required: ['$type'] },
+            then: { type: 'object', required: ['$token.kind'] },
             additionalProperties: false,
         },
         slot: {

package/dist/src/cdf/validate.js

@@ -39,14 +39,55 @@ export function parseCDFComponents(obj, prefix = '') {
     }
     return { components, tokens };
 }
+function entryValidator(name) {
+    const check = ajv.getSchema(`${CDF_SCHEMA_URL}#/definitions/${name}`);
+    if (!check)
+        throw new Error(`the CDF schema has no "${name}" definition`);
+    return check;
+}
+const validateComponentEntry = entryValidator('component');
+const validateTokenEntry = entryValidator('token');
+// A failed if/then rule adds a second, vaguer error; the first one already says what is wrong.
+function toValidationErrors(errors, prefix = '') {
+    return (errors ?? [])
+        .filter((err) => err.keyword !== 'if')
+        .map((err) => ({
+        path: `${prefix}${err.instancePath}` || '/',
+        message: err.message ?? 'Unknown validation error',
+        expected: err.params ? JSON.stringify(err.params) : undefined,
+    }));
+}
+/**
+ * The schema's top level is a `oneOf` of component, token and group, and Ajv reports a failed `oneOf` by listing the errors
+ * of every branch, which buries the real one under errors from branches that never applied. This validates each entry
+ * against the one definition its `$type` names instead, so the errors are about the entry that is wrong.
+ */
+function entryErrors(node, prefix) {
+    const errors = [];
+    for (const [key, value] of Object.entries(node)) {
+        if (key.startsWith('$') || typeof value !== 'object' || value === null)
+            continue;
+        const path = `${prefix}/${key}`;
+        const type = value['$type'];
+        const check = type === 'component'
+            ? validateComponentEntry
+            : TOKEN_TYPE_SET.has(type)
+                ? validateTokenEntry
+                : undefined;
+        if (!check) {
+            errors.push(...entryErrors(value, path));
+        }
+        else if (!check(value)) {
+            errors.push(...toValidationErrors(check.errors, path));
+        }
+    }
+    return errors;
+}
 export function validateCDF(input) {
     const valid = validate(input);
     if (!valid) {
-        const errors = (validate.errors ?? []).map((err) => ({
-            path: err.instancePath || '/',
-            message: err.message ?? 'Unknown validation error',
-            expected: err.params ? JSON.stringify(err.params) : undefined,
-        }));
+        const focused = typeof input === 'object' && input !== null ? entryErrors(input, '') : [];
+        const errors = focused.length > 0 ? focused : toValidationErrors(validate.errors);
         return { valid: false, errors, components: [], tokens: [] };
     }
     const file = input;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experience-design-system-types",
-  "version": "2.41.1-dev-build-0eca66e2.0",
+  "version": "2.41.1-dev-build-8f1f54c3.0",
   "license": "MIT",
   "type": "module",
   "module": "./dist/src/index.js",