Rename new attribute to something more generic

Author: leonidasmi

packages/yoastseo/docs/CONTRACT.md

@@ -22,7 +22,7 @@ const paper = toPaper( {
 ```
 
 Notes:
-- **Covers the analysis inputs.** The neutral core is `text`, `keyphrase`, `synonyms`, `locale`, `description`, `title`, `slug`, `permalink`, `titleWidth`, `textTitle`, `date`, `writingDirection`, and an open `customData` object. Two typed e-commerce slices are validated, unlike `customData`: `productData` (product flags consumed by the identifier/SKU assessments) and `productImages` (the product's own images — `{ id?, src?, alt }` each; providing the field — even as an empty array — scopes the image assessments to these images instead of the images in the text). The contract also carries optional, **deprecated** WordPress-transitional fields (`wpBlocks`, `shortcodes`, `isFrontPage`): they are real analysis inputs that change WordPress scores, so a remote/API analysis needs them to reproduce in-browser results. They are marked deprecated. Non-WordPress consumers simply omit them.
+- **Covers the analysis inputs.** The neutral core is `text`, `keyphrase`, `synonyms`, `locale`, `description`, `title`, `slug`, `permalink`, `titleWidth`, `textTitle`, `date`, `writingDirection`, and an open `customData` object. Two typed e-commerce slices are validated, unlike `customData`: `productData` (product flags consumed by the identifier/SKU assessments) and `providedImages` (the analyzed item's own images — `{ id?, src?, alt }` each, e.g. a product's featured, gallery and variation images; providing the field — even as an empty array — scopes the image assessments to these images instead of the images in the text). The contract also carries optional, **deprecated** WordPress-transitional fields (`wpBlocks`, `shortcodes`, `isFrontPage`): they are real analysis inputs that change WordPress scores, so a remote/API analysis needs them to reproduce in-browser results. They are marked deprecated. Non-WordPress consumers simply omit them.
 - **`keyphrase` is the canonical field name.** `keyword` is accepted as a deprecated alias so existing consumers can adopt the contract without renaming.
 - **Validation.** `toPaper` throws on structurally invalid input (wrong types, unknown keys). Omitting an optional field is fine — the assessments that need it are simply skipped, matching the engine's existing behaviour.
 - **Closed by design.** The schema is not extensible. Extra top-level fields are rejected, and there is deliberately no hook for swapping in an extended schema — a consumer-specific field would not be part of a shared contract. Consumers that register their own assessments pass extra inputs through `customData`, whose contents the contract carries but does not validate.

packages/yoastseo/spec/contract/paperDtoSpec.js

@@ -92,36 +92,36 @@ describe( "the Paper input contract (PaperDto)", function() {
 			expect( () => toPaper( { text: "x", productData: { hasGlobalSku: true } } ) ).toThrow();
 		} );
 
-		it( "maps a typed productImages array onto the Paper", function() {
-			const productImages = [
+		it( "maps a typed providedImages array onto the Paper", function() {
+			const providedImages = [
 				{ id: 1, src: "https://example.com/image.jpg", alt: "An image" },
 				{ alt: "" },
 			];
-			const paper = toPaper( { text: "x", productImages } );
+			const paper = toPaper( { text: "x", providedImages } );
 
-			expect( paper.getProductImages() ).toEqual( productImages );
+			expect( paper.getProvidedImages() ).toEqual( providedImages );
 		} );
 
-		it( "leaves absent productImages to Paper's default null, meaning the producer did not opt in", function() {
+		it( "leaves absent providedImages to Paper's default null, meaning the producer did not opt in", function() {
 			const paper = toPaper( { text: "x" } );
 
-			expect( paper.getProductImages() ).toBeNull();
-			expect( paper.hasProductImages() ).toBe( false );
+			expect( paper.getProvidedImages() ).toBeNull();
+			expect( paper.hasProvidedImages() ).toBe( false );
 		} );
 
-		it( "accepts an empty productImages array as a valid opt-in: a product without images", function() {
-			const paper = toPaper( { text: "x", productImages: [] } );
+		it( "accepts an empty providedImages array as a valid opt-in: an item without images", function() {
+			const paper = toPaper( { text: "x", providedImages: [] } );
 
-			expect( paper.getProductImages() ).toEqual( [] );
-			expect( paper.hasProductImages() ).toBe( true );
+			expect( paper.getProvidedImages() ).toEqual( [] );
+			expect( paper.hasProvidedImages() ).toBe( true );
 		} );
 
-		it( "type-checks productImages fields and rejects unknown keys (strict)", function() {
-			expect( () => toPaper( { text: "x", productImages: { alt: "not an array" } } ) ).toThrow();
-			expect( () => toPaper( { text: "x", productImages: [ { src: "https://example.com/image.jpg" } ] } ) ).toThrow();
-			expect( () => toPaper( { text: "x", productImages: [ { alt: 1 } ] } ) ).toThrow();
-			expect( () => toPaper( { text: "x", productImages: [ { id: "1", alt: "" } ] } ) ).toThrow();
-			expect( () => toPaper( { text: "x", productImages: [ { alt: "", altText: "typo" } ] } ) ).toThrow();
+		it( "type-checks providedImages fields and rejects unknown keys (strict)", function() {
+			expect( () => toPaper( { text: "x", providedImages: { alt: "not an array" } } ) ).toThrow();
+			expect( () => toPaper( { text: "x", providedImages: [ { src: "https://example.com/image.jpg" } ] } ) ).toThrow();
+			expect( () => toPaper( { text: "x", providedImages: [ { alt: 1 } ] } ) ).toThrow();
+			expect( () => toPaper( { text: "x", providedImages: [ { id: "1", alt: "" } ] } ) ).toThrow();
+			expect( () => toPaper( { text: "x", providedImages: [ { alt: "", altText: "typo" } ] } ) ).toThrow();
 		} );
 
 		it( "accepts the deprecated WP-transitional fields and maps them onto the Paper", function() {

packages/yoastseo/spec/languageProcessing/helpers/image/getImagesInScopeSpec.js

@@ -4,7 +4,7 @@ import Paper from "../../../../src/values/Paper";
 import buildTree from "../../../specHelpers/parse/buildTree";
 import EnglishResearcher from "../../../../src/languageProcessing/languages/en/Researcher";
 
-const productImages = [
+const providedImages = [
 	{ id: 1, src: "https://example.com/featured.jpg", alt: "A featured image" },
 	{ id: 2, src: "https://example.com/gallery.jpg", alt: "" },
 ];
@@ -23,28 +23,28 @@ const buildPaperWithTreeImage = ( attributes = {} ) => {
 };
 
 describe( "getImagesInScope", function() {
-	it( "returns the tree images when the paper carries no productImages attribute", function() {
+	it( "returns the tree images when the paper carries no providedImages attribute", function() {
 		const images = getImagesInScope( buildPaperWithTreeImage() );
 
 		expect( images ).toHaveLength( 1 );
 		expect( images[ 0 ].attributes.alt ).toBe( "tree image" );
 	} );
 
-	it( "returns only the product images, mapped to img pseudo-nodes, when the paper carries them", function() {
-		const images = getImagesInScope( buildPaperWithTreeImage( { productImages } ) );
+	it( "returns only the provided images, mapped to img pseudo-nodes, when the paper carries them", function() {
+		const images = getImagesInScope( buildPaperWithTreeImage( { providedImages } ) );
 
 		expect( images ).toEqual( [
 			{ name: "img", attributes: { src: "https://example.com/featured.jpg", alt: "A featured image" } },
 			{ name: "img", attributes: { src: "https://example.com/gallery.jpg", alt: "" } },
 		] );
 	} );
 
-	it( "returns an empty array when the producer opted in with an empty productImages array, even when the text has images", function() {
-		expect( getImagesInScope( buildPaperWithTreeImage( { productImages: [] } ) ) ).toEqual( [] );
+	it( "returns an empty array when the producer opted in with an empty providedImages array, even when the text has images", function() {
+		expect( getImagesInScope( buildPaperWithTreeImage( { providedImages: [] } ) ) ).toEqual( [] );
 	} );
 
-	it( "defaults missing src and alt to empty strings when mapping product images", function() {
-		expect( getImagesInScope( buildPaperWithTreeImage( { productImages: [ { id: 3 } ] } ) ) ).toEqual( [
+	it( "defaults missing src and alt to empty strings when mapping provided images", function() {
+		expect( getImagesInScope( buildPaperWithTreeImage( { providedImages: [ { id: 3 } ] } ) ) ).toEqual( [
 			{ name: "img", attributes: { src: "", alt: "" } },
 		] );
 	} );
@@ -55,7 +55,7 @@ describe( "getImagesInScope", function() {
 
 		const treePaper = new Paper( `string <img src='${ src }' alt='${ alt }' />` );
 		buildTree( treePaper, new EnglishResearcher( treePaper ) );
-		const productPaper = new Paper( "string without images", { productImages: [ { id: 4, src, alt } ] } );
+		const productPaper = new Paper( "string without images", { providedImages: [ { id: 4, src, alt } ] } );
 
 		const [ treeNode ] = getImagesInScope( treePaper );
 		const [ productNode ] = getImagesInScope( productPaper );

packages/yoastseo/spec/languageProcessing/researches/altTagCountSpec.js

@@ -302,11 +302,11 @@ describe( "Counts images in a text", function() {
 	} );
 } );
 
-describe( "Counts alt-tags of the paper's product images when the producer provides them", function() {
-	it( "classifies the paper's product images by their alt texts and ignores the images in the text", function() {
+describe( "Counts alt-tags of the paper's provided images when the producer provides them", function() {
+	it( "classifies the paper's provided images by their alt texts and ignores the images in the text", function() {
 		const paper = new Paper( "string <img src='http://plaatje' alt='keyword' />", {
 			keyword: "keyword",
-			productImages: [
+			providedImages: [
 				{ id: 1, src: "https://example.com/featured.jpg", alt: "keyword" },
 				{ id: 2, src: "https://example.com/gallery.jpg", alt: "something else" },
 				{ id: 3, src: "https://example.com/variation.jpg", alt: "" },
@@ -323,10 +323,10 @@ describe( "Counts alt-tags of the paper's product images when the producer provi
 		expect( stringToCheck.withAltNonKeyword ).toBe( 1 );
 	} );
 
-	it( "classifies alt-texted product images as withAlt when no keyphrase is set", function() {
+	it( "classifies alt-texted provided images as withAlt when no keyphrase is set", function() {
 		const paper = new Paper( "string", {
 			keyword: "",
-			productImages: [ { id: 1, src: "https://example.com/featured.jpg", alt: "A featured image" } ],
+			providedImages: [ { id: 1, src: "https://example.com/featured.jpg", alt: "A featured image" } ],
 		} );
 		const researcher = new Researcher( paper );
 		researcher.addResearchData( "morphology", morphologyData );
@@ -339,10 +339,10 @@ describe( "Counts alt-tags of the paper's product images when the producer provi
 		expect( stringToCheck.withAltNonKeyword ).toBe( 0 );
 	} );
 
-	it( "classifies nothing when the producer opted in with an empty productImages array, even when the text has images", function() {
+	it( "classifies nothing when the producer opted in with an empty images array, even when the text has images", function() {
 		const paper = new Paper( "string <img src='http://plaatje' alt='keyword' />", {
 			keyword: "keyword",
-			productImages: [],
+			providedImages: [],
 		} );
 		const researcher = new Researcher( paper );
 		researcher.addResearchData( "morphology", morphologyData );

packages/yoastseo/spec/languageProcessing/researches/imageCountInTextSpec.js

@@ -25,10 +25,10 @@ describe( "Counts images in an text", function() {
 	} );
 } );
 
-describe( "Counts the paper's product images when the producer provides them", function() {
-	it( "counts the paper's product images and ignores the images in the text", function() {
+describe( "Counts the paper's provided images when the producer provides them", function() {
+	it( "counts the paper's provided images and ignores the images in the text", function() {
 		const paper = new Paper( "string <img src='http://plaatje' alt='' />", {
-			productImages: [
+			providedImages: [
 				{ id: 1, src: "https://example.com/featured.jpg", alt: "A featured image" },
 				{ id: 2, src: "https://example.com/gallery.jpg", alt: "" },
 			],
@@ -41,8 +41,8 @@ describe( "Counts the paper's product images when the producer provides them", f
 		expect( imageCount ).toBe( 2 );
 	} );
 
-	it( "returns imagecount 0 when the producer opted in with an empty productImages array, even when the text has images", function() {
-		const paper = new Paper( "string <img src='http://plaatje' alt='' />", { productImages: [] } );
+	it( "returns imagecount 0 when the producer opted in with an empty providedImages array, even when the text has images", function() {
+		const paper = new Paper( "string <img src='http://plaatje' alt='' />", { providedImages: [] } );
 		const researcher = new EnglishResearcher( paper );
 		buildTree( paper, researcher );
 

packages/yoastseo/spec/scoring/assessments/seo/ImageAltTagsAssessmentSpec.js

@@ -6,8 +6,8 @@ import Factory from "../../../../src/helpers/factory.js";
 const imageAltTagsAssessment = new ImageAltTagsAssessment();
 
 describe( "test to check if all images have alt tags", function() {
-	it( "still assesses an empty text when the counted images come from the paper's product images", function() {
-		// In the productImages scope the researches count paper-level images, so an empty text must not zero the result.
+	it( "still assesses an empty text when the counted images come from the paper's provided images", function() {
+		// When the paper provides its own images the researches count paper-level images, so an empty text must not zero the result.
 		const result = imageAltTagsAssessment.getResult( new Paper( "" ), Factory.buildMockResearcher( {
 			imageCount: 2,
 			altTagCount: {

packages/yoastseo/spec/scoring/assessments/seo/ImageCountAssessmentSpec.js

@@ -182,9 +182,9 @@ describe( "tests for the assessment applicability.", function() {
 	} );
 } );
 
-describe( "tests for the productImages scope.", function() {
-	it( "still assesses an empty text when the counted images come from the paper's product images.", function() {
-		// In the productImages scope the researches count paper-level images, so an empty text must not zero the result.
+describe( "tests for the provided-images scope.", function() {
+	it( "still assesses an empty text when the counted images come from the paper's provided images.", function() {
+		// When the paper provides its own images the researches count paper-level images, so an empty text must not zero the result.
 		const assessment = imageCountAssessment.getResult( new Paper( "" ), Factory.buildMockResearcher( {
 			imageCount: 4,
 		}, true ) );

packages/yoastseo/spec/scoring/assessments/seo/KeyphraseInImageTextAssessmentSpec.js

@@ -360,9 +360,9 @@ describe( "tests for the assessment applicability.", function() {
 	} );
 } );
 
-describe( "tests for the productImages scope.", function() {
-	it( "still assesses an empty text when the counted images come from the paper's product images.", function() {
-		// In the productImages scope the researches count paper-level images, so an empty text must not zero the result.
+describe( "tests for the provided-images scope.", function() {
+	it( "still assesses an empty text when the counted images come from the paper's provided images.", function() {
+		// When the paper provides its own images the researches count paper-level images, so an empty text must not zero the result.
 		const assessment = new KeyphraseInImagesAssessment().getResult( new Paper( "", { keyword: "keyword" } ), Factory.buildMockResearcher( {
 			imageCount: 4,
 			altTagCount: { noAlt: 0, withAlt: 0, withAltKeyword: 1, withAltNonKeyword: 3 },

packages/yoastseo/spec/values/PaperSpec.js

@@ -130,25 +130,25 @@ describe( "Paper", function() {
 			expect( paper.getProductData() ).toEqual( {} );
 		} );
 
-		it( "returns product images", function() {
+		it( "returns the provided images", function() {
 			const attributes = {
-				productImages: [ { id: 1, src: "https://example.com/image.jpg", alt: "An image" }, { id: 2, src: "", alt: "" } ],
+				providedImages: [ { id: 1, src: "https://example.com/image.jpg", alt: "An image" }, { id: 2, src: "", alt: "" } ],
 			};
 			const paper = new Paper( "", attributes );
-			expect( paper.getProductImages() ).toEqual( attributes.productImages );
+			expect( paper.getProvidedImages() ).toEqual( attributes.providedImages );
 		} );
 
-		it( "returns null for the product images when none are provided", function() {
+		it( "returns null for the provided images when none are provided", function() {
 			const paper = new Paper( "" );
-			expect( paper.getProductImages() ).toBeNull();
-			expect( paper.hasProductImages() ).toBe( false );
+			expect( paper.getProvidedImages() ).toBeNull();
+			expect( paper.hasProvidedImages() ).toBe( false );
 		} );
 
-		it( "treats an explicitly provided empty product images array as having product images", function() {
+		it( "treats an explicitly provided empty providedImages array as having provided images", function() {
 			// The producer opted in: a product without images, which the image assessments must score as such.
-			const paper = new Paper( "", { productImages: [] } );
-			expect( paper.getProductImages() ).toEqual( [] );
-			expect( paper.hasProductImages() ).toBe( true );
+			const paper = new Paper( "", { providedImages: [] } );
+			expect( paper.getProvidedImages() ).toEqual( [] );
+			expect( paper.hasProvidedImages() ).toBe( true );
 		} );
 
 		it( "returns the text title", function() {
@@ -230,9 +230,9 @@ describe( "Paper", function() {
 			expect( paper1.equals( paper2 ) ).toBe( false );
 		} );
 
-		it( "should identify two papers with similar content but dissimilar product images as not equal", function() {
-			const paper1 = new Paper( "This is a test", { productImages: [ { id: 1, src: "https://example.com/image.jpg", alt: "An image" } ] } );
-			const paper2 = new Paper( "This is a test", { productImages: [ { id: 1, src: "https://example.com/image.jpg", alt: "New alt" } ] } );
+		it( "should identify two papers with similar content but dissimilar provided images as not equal", function() {
+			const paper1 = new Paper( "This is a test", { providedImages: [ { id: 1, src: "https://example.com/image.jpg", alt: "An image" } ] } );
+			const paper2 = new Paper( "This is a test", { providedImages: [ { id: 1, src: "https://example.com/image.jpg", alt: "New alt" } ] } );
 			expect( paper1.equals( paper2 ) ).toBe( false );
 		} );
 	} );
@@ -250,10 +250,10 @@ describe( "Paper", function() {
 			expect( paper1.hasSameTreeInputsAs( paper2 ) ).toBe( true );
 		} );
 
-		it( "returns true when only the product images differ", function() {
-			// Product images don't feed the tree builder, so a change must not invalidate the cached tree.
-			const paper1 = new Paper( "<p>Hello world.</p>", { productImages: [ { id: 1, src: "https://example.com/image.jpg", alt: "An image" } ] } );
-			const paper2 = new Paper( "<p>Hello world.</p>", { productImages: [ { id: 2, src: "https://example.com/other.jpg", alt: "" } ] } );
+		it( "returns true when only the provided images differ", function() {
+			// Provided images don't feed the tree builder, so a change must not invalidate the cached tree.
+			const paper1 = new Paper( "<p>Hello world.</p>", { providedImages: [ { id: 1, src: "https://example.com/image.jpg", alt: "An image" } ] } );
+			const paper2 = new Paper( "<p>Hello world.</p>", { providedImages: [ { id: 2, src: "https://example.com/other.jpg", alt: "" } ] } );
 			expect( paper1.hasSameTreeInputsAs( paper2 ) ).toBe( true );
 		} );
 
@@ -385,11 +385,11 @@ describe( "Paper", function() {
 			expect( parsed.getProductData() ).toEqual( productData );
 		} );
 
-		it( "round-trips the product images through serialize and parse", () => {
-			const productImages = [ { id: 1, src: "https://example.com/image.jpg", alt: "An image" }, { id: 2, src: "https://example.com/other.jpg", alt: "" } ];
-			const paper = new Paper( "text", { productImages } );
+		it( "round-trips the provided images through serialize and parse", () => {
+			const providedImages = [ { id: 1, src: "https://example.com/image.jpg", alt: "An image" }, { id: 2, src: "https://example.com/other.jpg", alt: "" } ];
+			const paper = new Paper( "text", { providedImages } );
 			const parsed = Paper.parse( paper.serialize() );
-			expect( parsed.getProductImages() ).toEqual( productImages );
+			expect( parsed.getProvidedImages() ).toEqual( providedImages );
 		} );
 	} );
 	describe( "A test for setters and getters", function() {