or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

css-style-declaration.mdcss-value-parsing.mdindex.mdproperty-management.mdutility-functions.md
tile.json

index.mddocs/

CSSStyle

CSSStyle is a Node.js implementation of the CSS Object Model CSSStyleDeclaration class that provides comprehensive support for CSS property parsing, validation, and manipulation. It extends the CSSOM specification with modern CSS features, enabling developers to programmatically handle CSS styles in Node.js environments without browser dependencies.

Package Information

  • Package Name: cssstyle
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install cssstyle

Core Imports

const { CSSStyleDeclaration } = require("cssstyle");

For ES modules:

import { CSSStyleDeclaration } from "cssstyle";

Basic Usage

const { CSSStyleDeclaration } = require("cssstyle");

// Create a new style declaration
const style = new CSSStyleDeclaration();

// Set individual properties
style.setProperty("color", "red");
style.setProperty("font-size", "16px", "important");

// Access properties
console.log(style.color); // "red"
console.log(style.getPropertyValue("color")); // "red"
console.log(style.getPropertyPriority("font-size")); // "important"

// Work with CSS text
style.cssText = "background: blue; border: 1px solid black;";
console.log(style.cssText); // "background: blue; border: 1px solid black;"

// Enumerate properties
for (let i = 0; i < style.length; i++) {
  const property = style.item(i);
  console.log(`${property}: ${style.getPropertyValue(property)}`);
}

Architecture

CSSStyle is built around several key components:

  • CSSStyleDeclaration Class: Main class implementing the W3C CSSStyleDeclaration interface
  • CSS Property System: Dynamic property generation with getter/setter pairs for all CSS properties
  • Parser Engine: Comprehensive CSS value parsing using css-tree and custom parsers
  • Validation System: Property-value validation with support for CSS specifications
  • Shorthand Expansion: Automatic shorthand property expansion (e.g., margin → margin-top, margin-right, etc.)
  • Change Tracking: Optional callback system for monitoring style changes

Capabilities

CSS Style Declaration

Core CSSStyleDeclaration class implementing the W3C CSS Object Model interface. Provides property management, CSS text serialization, and change tracking.

class CSSStyleDeclaration {
  constructor(onChangeCallback?: Function, opt?: { context?: object });
  
  // CSS text representation
  get cssText(): string;
  set cssText(value: string);
  
  // Property count
  get length(): number;
  
  // Parent rule reference (readonly)
  get parentRule(): CSSRule | null;
  
  // CSS float property alias
  get cssFloat(): string;
  set cssFloat(value: string);
}

CSS Style Declaration

Property Management

Methods for getting, setting, and removing CSS properties with priority support and validation.

// Core property methods
getPropertyValue(property: string): string;
setProperty(property: string, value: string, priority?: string): void;
removeProperty(property: string): string;
getPropertyPriority(property: string): string;
item(index: number): string;

Property Management

CSS Value Parsing

Comprehensive CSS value parsing and validation utilities supporting all CSS data types, functions, and modern features.

// Core parsing functions
function prepareValue(value: any, globalObject?: object): string;
function parseColor(val: string): string | undefined;
function parseLength(val: string, restrictToPositive?: boolean): string | undefined;
function parseUrl(val: string): string | undefined;
function isValidPropertyValue(prop: string, val: string): boolean;

CSS Value Parsing

Utility Functions

Helper functions for CSS property name transformation, string manipulation, and property descriptor creation.

// Property name transformation
function dashedToCamelCase(dashed: string): string;
function camelCaseToDashed(camelCase: string): string;

// String utilities
function asciiLowercase(s: string): string;
function splitOnASCIIWhitespace(str: string): string[];

Utility Functions

Types

// Constructor options
interface CSSStyleDeclarationOptions {
  context?: Window | Element | CSSRule;
}

// Change callback function type
type ChangeCallback = (cssText: string) => void;

// CSS property priority values
type PropertyPriority = "" | "important";

// Numeric type constants for parsing
const NUM_TYPE = {
  UNDEFINED: 0,
  VAR: 1,
  NUMBER: 2,
  PERCENT: 4,
  LENGTH: 8,
  ANGLE: 0x10,
  CALC: 0x20
};

Error Handling

CSSStyle throws specific errors for invalid operations:

  • DOMException with NoModificationAllowedError: Thrown when attempting to modify readonly computed styles
  • TypeError: Thrown for invalid argument types or missing required arguments
  • Parser functions return undefined for invalid CSS values rather than throwing errors
  • Property setters silently ignore invalid values to match browser behavior