Preparation for resolving shortcut property issues by asamuzaK · Pull Request #261 · jsdom/cssstyle

asamuzaK · 2025-12-13T14:37:36Z

Summary

This PR serves as a preparation step to resolve long-standing issues with shorthand properties.
It introduces a mechanism to auto-generate CSS property definitions and refactors the codebase to utilize them.

Key Changes and Reasons

1. Introducing `propertyDefinitions.js`

Change: Added a script to generate lib/generated/propertyDefinitions.js based on property metadata.
Reason: To implement shorthand properties correctly, we need a reliable source of truth for every longhand property (initial values, syntax, inheritance, etc.). Hardcoding these manually is error-prone.
Future Integration with jsdom: The newly introduced lib/generated/propertyDefinitions.js is designed to be the single source of truth for CSS properties. In the future, this is intended to replace propertiesWithResolvedValueImplemented in jsdom's lib/jsdom/living/helpers/style-rules.js, allowing jsdom to delegate property metadata management entirely to cssstyle.

2. Splitting Functions and Clarifying Roles

Change: Decomposed the monolithic normalization logic into smaller, discrete functions.
Reason: To explicitly define the role of each function (separation of concerns). By isolating the logic for different value types and validation steps, the code becomes more readable and easier to maintain. This modularity is essential for handling the complexity of shorthand property expansion in the next steps.

3. Refactoring with Constants

Change: Replaced string literals (e.g., property names) with constants.
Reason: To prevent bugs caused by typos and to improve code maintainability across the parser and normalizer.

Effect

While the direct effects of this PR are limited regarding the overall shorthand behavior, it explicitly resolves the following test case:

web-platform-tests/to-upstream/css/cssom/style-border-shorthand-var.html

Once merged, this PR establishes the necessary data structures and infrastructure, allowing us to implement the complex logic for expanding shorthands into longhands in a follow-up PR with high reliability and low maintenance cost.

domenic · 2025-12-15T00:28:04Z

Can you add a more detailed description of this PR? What changes, why are those changes good, does this fix any bugs currently or is it only for use in a follow-up, etc.? Why do we need a new generated properties list and how does it differ from the other generated lists? What specs does this implement? That sort of thing.

domenic

My biggest worry here is the module-level mutable state.

Otherwise, there are likely improvements that could be made to reduce complexity and code duplication, etc., but they are not blockers, and I am happy to continue with you being the expert on these parts of the code.

lib/normalize.js

domenic · 2025-12-17T04:03:42Z

lib/normalize.js

+          for (const position of borderPositions) {
+            const longhandProperty = `${namePart}-${position}-${linePart}`;
+            const longhandItem = createPropertyItem(longhandProperty, lineValue, priority);
+            if (longhandProperties.has(longhandProperty)) {


This pattern (lines 1346-1354) appears multiple times. Can we extract it into a helper?

6507ee3

Please take a look.

I think there are still other instances of the pattern I identified:

https://github.com/asamuzaK/cssstyle/blob/4ba7f29b738413e44e5a24d362751308c22bfc22/lib/normalize.js#L1378-L1386

https://github.com/asamuzaK/cssstyle/blob/4ba7f29b738413e44e5a24d362751308c22bfc22/lib/normalize.js#L1390-L1398

a35b915

Please take a look.

Now we have these three duplicated:

cssstyle/lib/normalize.js

Lines 1306 to 1314 in a35b915

if (properties.has(longhandProperty)) {

const { priority: existingPriority } = properties.get(longhandProperty);

if (!existingPriority) {

properties.delete(longhandProperty);

properties.set(longhandProperty, longhandItem);

}

} else {

properties.set(longhandProperty, longhandItem);

}

cssstyle/lib/normalize.js

Lines 1330 to 1338 in a35b915

if (safe && properties.has(property)) {

const { priority: existingPriority } = properties.get(property);

if (!existingPriority) {

properties.delete(property);

properties.set(property, item);

}

} else {

properties.set(property, item);

}

cssstyle/lib/normalize.js

Lines 1401 to 1409 in a35b915

} else if (longhandProperties.has(property)) {

const { priority } = longhandProperties.get(property);

if (!priority) {

longhandProperties.delete(property);

longhandProperties.set(property, item);

}

} else {

longhandProperties.set(property, item);

}

I think maybe you missed what I was referring to in the original comment, which was specifically the block from 1346-1354? Both of your attempted refactorings so far do not focus on that specific code pattern, but instead pull out larger chunks of code. And because they pull out larger chunks of code, they miss and duplicate the smaller pattern I am pointing to.

15cd48c
Is this what you're saying?

Updated generateBorderLineShorthand, generateBorderPositionShorthand, and generateBorderNameShorthand to use a default parameter for priority instead of reassigning within the function. This simplifies the function signatures and improves code clarity.

Replaces direct calls to createPropertyItem with getPropertyItem for border-related properties in prepareBorderProperties, streamlining property item retrieval and improving code consistency.

Replaces the borderCollections object with borderCollectionConfig and dynamically constructs borderCollections with items and priorityItems maps. Renames priorItems to priorityItems throughout for clarity and consistency, and updates related logic in prepareBorderShorthands.

Renamed 'namePriorItems' to 'namePriorityItems' in prepareBorderShorthands for consistency and clarity.

Extracted repeated logic for updating border longhand properties into a new helper function, updatePositionLonghands. This improves code readability and maintainability in the border property normalization process.

Introduces the updateLonghandProperties helper to consolidate logic for updating longhand properties in multiple places. This reduces code duplication and improves maintainability in normalize.js.

Replaces all instances of the variable 'nameItem' with 'shorthandItem'. No functional changes were made; this is a variable renaming for better meaning and code readability.

Renamed generateBorderNameShorthand to generateBorderShorthand and updated related variable names for clarity. This improves code readability and better reflects the function's purpose.

Simplifies and consolidates logic for updating longhand CSS properties by replacing the previous updatePositionLonghands and updateLonghandProperties functions with a single updateLonghandProperties function. This change improves maintainability and ensures consistent handling of property priorities, especially when dealing with 'important' flags.

asamuzaK marked this pull request as draft December 13, 2025 14:37

asamuzaK force-pushed the defs branch 2 times, most recently from 05d1ddb to 38299f6 Compare December 14, 2025 06:26

asamuzaK changed the title ~~Address shorthand property issues~~ Preparation for resolving shortcut property issues Dec 14, 2025

asamuzaK marked this pull request as ready for review December 14, 2025 12:20

asamuzaK force-pushed the defs branch from 38299f6 to 61cde76 Compare December 16, 2025 13:52

domenic reviewed Dec 17, 2025

View reviewed changes

asamuzaK added 3 commits December 17, 2025 23:41

Add generator script

3acbff4

Update normalizer

7f1efa0

Optimize code

1419805

asamuzaK force-pushed the defs branch from 61cde76 to 1419805 Compare December 17, 2025 14:42

asamuzaK force-pushed the defs branch from ba288ad to 623c66b Compare December 17, 2025 15:06

Refactor border property item retrieval logic

7491e43

Replaces direct calls to createPropertyItem with getPropertyItem for border-related properties in prepareBorderProperties, streamlining property item retrieval and improving code consistency.

asamuzaK force-pushed the defs branch from 623c66b to 7491e43 Compare December 17, 2025 15:30

asamuzaK added 3 commits December 18, 2025 08:48

Fix border shorthand variable name

d7ecb50

Renamed 'namePriorItems' to 'namePriorityItems' in prepareBorderShorthands for consistency and clarity.

Refactor border longhand property updates

6507ee3

Extracted repeated logic for updating border longhand properties into a new helper function, updatePositionLonghands. This improves code readability and maintainability in the border property normalization process.

asamuzaK requested a review from domenic December 18, 2025 00:04

asamuzaK added 4 commits December 18, 2025 09:28

Undo unnecessary change

4ba7f29

Refactor longhand property updates into helper function

a35b915

Introduces the updateLonghandProperties helper to consolidate logic for updating longhand properties in multiple places. This reduces code duplication and improves maintainability in normalize.js.

Refactor border property variable naming

37ff437

Replaces all instances of the variable 'nameItem' with 'shorthandItem'. No functional changes were made; this is a variable renaming for better meaning and code readability.

Refactor border shorthand generation functions

c67c95c

Renamed generateBorderNameShorthand to generateBorderShorthand and updated related variable names for clarity. This improves code readability and better reflects the function's purpose.

asamuzaK force-pushed the defs branch from 94ebe8c to c67c95c Compare December 20, 2025 00:42

domenic approved these changes Dec 31, 2025

View reviewed changes

domenic merged commit a3413ab into jsdom:main Dec 31, 2025
3 checks passed

asamuzaK deleted the defs branch December 31, 2025 06:18

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Preparation for resolving shortcut property issues#261

Preparation for resolving shortcut property issues#261
domenic merged 13 commits intojsdom:mainfrom
asamuzaK:defs

asamuzaK commented Dec 13, 2025 •

edited

Loading

Uh oh!

domenic commented Dec 15, 2025

Uh oh!

domenic left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

domenic Dec 17, 2025

Uh oh!

asamuzaK Dec 18, 2025

Uh oh!

domenic Dec 19, 2025

Uh oh!

asamuzaK Dec 20, 2025

Uh oh!

domenic Dec 21, 2025

Uh oh!

asamuzaK Dec 26, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Comments

	if (properties.has(longhandProperty)) {
	const { priority: existingPriority } = properties.get(longhandProperty);
	if (!existingPriority) {
	properties.delete(longhandProperty);
	properties.set(longhandProperty, longhandItem);
	}
	} else {
	properties.set(longhandProperty, longhandItem);
	}

	if (safe && properties.has(property)) {
	const { priority: existingPriority } = properties.get(property);
	if (!existingPriority) {
	properties.delete(property);
	properties.set(property, item);
	}
	} else {
	properties.set(property, item);
	}

	} else if (longhandProperties.has(property)) {
	const { priority } = longhandProperties.get(property);
	if (!priority) {
	longhandProperties.delete(property);
	longhandProperties.set(property, item);
	}
	} else {
	longhandProperties.set(property, item);
	}

Uh oh!

Conversation

asamuzaK commented Dec 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Key Changes and Reasons

1. Introducing propertyDefinitions.js

2. Splitting Functions and Clarifying Roles

3. Refactoring with Constants

Effect

Uh oh!

domenic commented Dec 15, 2025

Uh oh!

domenic left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

domenic Dec 17, 2025

Choose a reason for hiding this comment

Uh oh!

asamuzaK Dec 18, 2025

Choose a reason for hiding this comment

Uh oh!

domenic Dec 19, 2025

Choose a reason for hiding this comment

Uh oh!

asamuzaK Dec 20, 2025

Choose a reason for hiding this comment

Uh oh!

domenic Dec 21, 2025

Choose a reason for hiding this comment

Uh oh!

asamuzaK Dec 26, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Comments

asamuzaK commented Dec 13, 2025 •

edited

Loading

1. Introducing `propertyDefinitions.js`