tessl/npm-cssstyle

CSSStyleDeclaration Object Model implementation for Node.js

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Property Management

Name: tessl/npm-cssstyle
Author: tessl

Core methods for getting, setting, and removing CSS properties with priority support, validation, and shorthand property handling.

Capabilities

Get Property Value

Retrieves the value of a specified CSS property.

/**
 * Returns the value of a CSS property
 * @param property - CSS property name (camelCase or kebab-case)
 * @returns Property value as string, or empty string if not set
 */
getPropertyValue(property: string): string;

Usage Examples:

const style = new CSSStyleDeclaration();
style.color = "red";
style.setProperty("font-size", "16px");

console.log(style.getPropertyValue("color")); // "red"
console.log(style.getPropertyValue("font-size")); // "16px"
console.log(style.getPropertyValue("margin")); // "" (not set)

// Works with both naming conventions
console.log(style.getPropertyValue("backgroundColor")); // ""
console.log(style.getPropertyValue("background-color")); // ""

Set Property

Sets a CSS property with optional priority, performing validation and shorthand expansion.

/**
 * Sets a CSS property with optional priority
 * @param property - CSS property name
 * @param value - CSS property value
 * @param priority - Optional priority ("important" or null/undefined)
 */
setProperty(property: string, value: string, priority?: string | null): void;

Usage Examples:

const style = new CSSStyleDeclaration();

// Basic property setting
style.setProperty("color", "blue");
style.setProperty("font-size", "18px");

// With important priority
style.setProperty("background-color", "yellow", "important");

// Setting shorthand properties
style.setProperty("margin", "10px 20px");
// Expands to: margin-top: 10px, margin-right: 20px, margin-bottom: 10px, margin-left: 20px

style.setProperty("border", "1px solid red");
// Expands to: border-width: 1px, border-style: solid, border-color: red

// Custom properties (CSS variables)
style.setProperty("--main-color", "#3498db");

// Invalid values are silently ignored
style.setProperty("color", "invalid-color"); // No effect

Remove Property

Removes a CSS property and returns its previous value.

/**
 * Removes a CSS property and returns its previous value
 * @param property - CSS property name to remove
 * @returns Previous value of the property, or empty string if not set
 */
removeProperty(property: string): string;

Usage Examples:

const style = new CSSStyleDeclaration();
style.color = "red";
style.fontSize = "16px";

// Remove a property
const oldColor = style.removeProperty("color");
console.log(oldColor); // "red"
console.log(style.color); // "" (removed)

// Removing non-existent property
const oldMargin = style.removeProperty("margin");
console.log(oldMargin); // ""

// Property is also removed from cssText
console.log(style.cssText); // "font-size: 16px;" (color removed)

Get Property Priority

Returns the priority of a CSS property (either "important" or empty string).

/**
 * Returns the priority of a CSS property
 * @param property - CSS property name
 * @returns "important" if the property has important priority, empty string otherwise
 */
getPropertyPriority(property: string): string;

Usage Examples:

const style = new CSSStyleDeclaration();
style.setProperty("color", "red");
style.setProperty("background", "blue", "important");

console.log(style.getPropertyPriority("color")); // ""
console.log(style.getPropertyPriority("background")); // "important"
console.log(style.getPropertyPriority("margin")); // "" (not set)

Item Access

Retrieves the property name at a specified index in the style declaration.

/**
 * Returns the property name at the specified index
 * @param index - Zero-based index of the property
 * @returns Property name at the index, or empty string if index is out of bounds
 * @throws TypeError if no arguments provided
 */
item(index: number): string;

Usage Examples:

const style = new CSSStyleDeclaration();
style.color = "red";
style.fontSize = "16px";
style.margin = "10px";

console.log(style.length); // 3

// Access properties by index
console.log(style.item(0)); // "color"
console.log(style.item(1)); // "font-size"
console.log(style.item(2)); // "margin"

// Out of bounds returns empty string
console.log(style.item(5)); // ""
console.log(style.item(-1)); // ""

// Missing argument throws error
try {
  style.item(); // TypeError: 1 argument required, but only 0 present.
} catch (e) {
  console.log(e.message);
}

// Iterate through all properties
for (let i = 0; i < style.length; i++) {
  const property = style.item(i);
  const value = style.getPropertyValue(property);
  const priority = style.getPropertyPriority(property);
  console.log(`${property}: ${value}${priority ? ' !' + priority : ''}`);
}

Array-Like Access

Properties can also be accessed using bracket notation with numeric indices.

// Array-like property access
style[0]; // First property name
style[1]; // Second property name
// etc.

Usage Examples:

const style = new CSSStyleDeclaration();
style.color = "red";
style.fontSize = "16px";

// Direct array-like access
console.log(style[0]); // "color"
console.log(style[1]); // "font-size"

// Iteration using for...in
for (let index in style) {
  if (style.hasOwnProperty(index) && !isNaN(index)) {
    console.log(`${index}: ${style[index]}`);
  }
}

Shorthand Property Handling

Shorthand properties are automatically expanded into their constituent longhand properties.

// Shorthand properties supported:
// - background
// - border, border-top, border-right, border-bottom, border-left  
// - font
// - margin
// - padding
// - flex

Usage Examples:

const style = new CSSStyleDeclaration();

// Setting margin shorthand
style.setProperty("margin", "10px 20px 30px 40px");

// Expands to individual properties
console.log(style.getPropertyValue("margin-top"));    // "10px"
console.log(style.getPropertyValue("margin-right"));  // "20px"
console.log(style.getPropertyValue("margin-bottom")); // "30px"
console.log(style.getPropertyValue("margin-left"));   // "40px"

// Setting border shorthand
style.setProperty("border", "2px solid blue");

// Expands to individual border properties
console.log(style.getPropertyValue("border-width")); // "2px"
console.log(style.getPropertyValue("border-style")); // "solid"
console.log(style.getPropertyValue("border-color")); // "blue"

// Shorthand getter reconstructs value when possible
console.log(style.getPropertyValue("border")); // "2px solid blue"

Custom Properties (CSS Variables)

CSS custom properties (variables) are fully supported with special handling.

// Custom property names start with "--"
style.setProperty("--main-color", "#3498db");
style.setProperty("--base-size", "16px");

Usage Examples:

const style = new CSSStyleDeclaration();

// Set custom properties
style.setProperty("--primary-color", "#3498db");
style.setProperty("--font-size-base", "16px");
style.setProperty("--border-radius", "4px");

// Get custom properties
console.log(style.getPropertyValue("--primary-color")); // "#3498db"

// Use in regular properties
style.setProperty("color", "var(--primary-color)");
style.setProperty("font-size", "var(--font-size-base)");

// Custom properties bypass validation
style.setProperty("--any-value", "this can be anything!");

Validation and Error Handling

Property validation follows CSS specifications with graceful error handling.

Invalid property names: Silently ignored for unknown properties
Invalid values: Silently ignored, property remains unchanged
Readonly modifications: Throw DOMException for computed styles
Type coercion: Values are converted to strings following Web IDL rules

Usage Examples:

const style = new CSSStyleDeclaration();

// Invalid property names (silently ignored)
style.setProperty("unknown-property", "value"); // No effect

// Invalid values (silently ignored)
style.setProperty("color", "not-a-color"); // No effect
style.setProperty("font-size", "invalid"); // No effect

// Valid values are accepted
style.setProperty("color", "red"); // Works
style.setProperty("font-size", "16px"); // Works

// Readonly style (throws error)
const computedStyle = new CSSStyleDeclaration(null, { context: window });
try {
  computedStyle.setProperty("color", "red");
} catch (e) {
  console.log(e.name); // "NoModificationAllowedError"
}

Install with Tessl CLI