iobroker.mywebui 1.37.21 → 1.37.22

package/www/node_modules/@node-projects/css-parser/docs/AST.md

@@ -0,0 +1,417 @@
+# Abstract Syntax Tree (AST)
+
+## Overview
+
+The AST represents CSS as a tree structure where each node has a specific type and properties. All nodes share common properties and have type-specific properties.
+
+## Common Properties
+
+All AST nodes have these properties:
+
+### `type`
+
+The node type as a string. See [Node Types](#node-types) for all possible values.
+
+### `position` (optional)
+
+Position information for the node in the source code:
+
+```typescript
+{
+  start: { line: number; column: number };
+  end: { line: number; column: number };
+  source?: string;
+}
+```
+
+### `parent` (optional)
+
+Reference to the parent node in the AST.
+
+## Node Types
+
+### `stylesheet`
+
+The root node representing an entire CSS document.
+
+**Properties:**
+- `stylesheet.source` (optional): Source file path
+- `stylesheet.rules`: Array of top-level rules (may include `whitespace` nodes when `preserveFormatting: true`)
+- `stylesheet.parsingErrors` (optional): Array of parse errors when `silent` option is used
+
+**Example:**
+```json
+{
+  "type": "stylesheet",
+  "stylesheet": {
+    "rules": [
+      // ... other nodes
+    ]
+  }
+}
+```
+
+### `rule`
+
+A CSS rule with selectors and declarations.
+
+**Properties:**
+- `selectors`: Array of CSS selectors as strings
+- `declarations`: Array of declarations and comments
+
+**Example:**
+```json
+{
+  "type": "rule",
+  "selectors": ["body", "html"],
+  "declarations": [
+    {
+      "type": "declaration",
+      "property": "color",
+      "value": "red"
+    }
+  ]
+}
+```
+
+### `declaration`
+
+A CSS property declaration.
+
+**Properties:**
+- `property`: The CSS property name
+- `value`: The CSS property value as a string
+
+**Example:**
+```json
+{
+  "type": "declaration",
+  "property": "background-color",
+  "value": "#ffffff"
+}
+```
+
+### `comment`
+
+A CSS comment.
+
+**Properties:**
+- `comment`: The comment text (without `/*` and `*/`)
+
+**Example:**
+```json
+{
+  "type": "comment",
+  "comment": " This is a comment "
+}
+```
+
+### `whitespace`
+
+A whitespace node that preserves original formatting between sibling nodes. Only present when `preserveFormatting: true` is used during parsing.
+
+**Properties:**
+- `value`: The whitespace text (spaces, newlines, tabs, etc.)
+
+**Example:**
+```json
+{
+  "type": "whitespace",
+  "value": "\n\n"
+}
+```
+
+### `media`
+
+A `@media` rule.
+
+**Properties:**
+- `media`: The media query string
+- `rules`: Array of rules within the media block
+
+**Example:**
+```json
+{
+  "type": "media",
+  "media": "screen and (max-width: 768px)",
+  "rules": [
+    // ... nested rules
+  ]
+}
+```
+
+### `keyframes`
+
+A `@keyframes` rule.
+
+**Properties:**
+- `name`: The keyframes name
+- `vendor` (optional): Vendor prefix (e.g., "-webkit-")
+- `keyframes`: Array of keyframe rules and comments
+
+**Example:**
+```json
+{
+  "type": "keyframes",
+  "name": "fade",
+  "keyframes": [
+    {
+      "type": "keyframe",
+      "values": ["from"],
+      "declarations": [
+        {
+          "type": "declaration",
+          "property": "opacity",
+          "value": "0"
+        }
+      ]
+    }
+  ]
+}
+```
+
+### `keyframe`
+
+A keyframe within a `@keyframes` rule.
+
+**Properties:**
+- `values`: Array of keyframe selectors (e.g., `["from"]`, `["to"]`, `["50%"]`)
+- `declarations`: Array of declarations and comments
+
+### `import`
+
+An `@import` rule.
+
+**Properties:**
+- `import`: The import string (URL or media query)
+
+**Example:**
+```json
+{
+  "type": "import",
+  "import": "url('styles.css')"
+}
+```
+
+### `charset`
+
+A `@charset` rule.
+
+**Properties:**
+- `charset`: The character encoding
+
+**Example:**
+```json
+{
+  "type": "charset",
+  "charset": "utf-8"
+}
+```
+
+### `namespace`
+
+A `@namespace` rule.
+
+**Properties:**
+- `namespace`: The namespace declaration
+
+**Example:**
+```json
+{
+  "type": "namespace",
+  "namespace": "url(http://www.w3.org/1999/xhtml)"
+}
+```
+
+### `supports`
+
+A `@supports` rule.
+
+**Properties:**
+- `supports`: The supports condition
+- `rules`: Array of rules within the supports block
+
+**Example:**
+```json
+{
+  "type": "supports",
+  "supports": "(display: grid)",
+  "rules": [
+    // ... nested rules
+  ]
+}
+```
+
+### `document`
+
+A `@document` rule.
+
+**Properties:**
+- `document`: The document condition
+- `vendor` (optional): Vendor prefix
+- `rules`: Array of rules within the document block
+
+### `page`
+
+A `@page` rule.
+
+**Properties:**
+- `selectors`: Array of page selectors
+- `declarations`: Array of declarations and comments
+
+### `font-face`
+
+A `@font-face` rule.
+
+**Properties:**
+- `declarations`: Array of font declarations and comments
+
+### `host`
+
+A `:host` rule.
+
+**Properties:**
+- `rules`: Array of rules within the host block
+
+### `container`
+
+A `@container` rule.
+
+**Properties:**
+- `container`: The container query
+- `rules`: Array of rules within the container block
+
+### `layer`
+
+A `@layer` rule.
+
+**Properties:**
+- `layer`: The layer name
+- `rules` (optional): Array of rules within the layer block
+
+### `custom-media`
+
+A `@custom-media` rule.
+
+**Properties:**
+- `name`: The custom media query name
+- `media`: The media query definition
+
+### `starting-style`
+
+A `@starting-style` rule.
+
+**Properties:**
+- `rules`: Array of rules within the starting-style block
+
+## Type Hierarchy
+
+The AST nodes are organized in the following hierarchy:
+
+- `CssStylesheetAST` - Root node
+- `CssAtRuleAST` - Union of all at-rule and rule nodes
+- `CssAllNodesAST` - Union of all possible node types
+
+## Working with the AST
+
+### Traversing Nodes
+
+```typescript
+import { parse, CssStylesheetAST } from '@adobe/css-tools';
+
+const ast: CssStylesheetAST = parse('body { color: red; }');
+
+// Access top-level rules
+ast.stylesheet.rules.forEach(rule => {
+  if (rule.type === 'rule') {
+    console.log('Selectors:', rule.selectors);
+    rule.declarations.forEach(decl => {
+      if (decl.type === 'declaration') {
+        console.log(`${decl.property}: ${decl.value}`);
+      }
+    });
+  }
+});
+```
+
+### Modifying Nodes
+
+```typescript
+// Add a new declaration
+const newDecl = {
+  type: 'declaration' as const,
+  property: 'font-size',
+  value: '16px'
+};
+
+// Find a rule and add the declaration
+ast.stylesheet.rules.forEach(rule => {
+  if (rule.type === 'rule' && rule.selectors.includes('body')) {
+    rule.declarations.push(newDecl);
+  }
+});
+```
+
+### Error Handling
+
+When parsing with the `silent` option, errors are collected in the AST:
+
+```typescript
+const ast = parse('invalid css {', { silent: true });
+
+if (ast.stylesheet.parsingErrors) {
+  ast.stylesheet.parsingErrors.forEach(error => {
+    console.error('Parse error:', error.message);
+  });
+}
+```
+
+## Position Information
+
+Position information is available on most nodes and includes:
+
+- `start.line` and `start.column`: Beginning of the node
+- `end.line` and `end.column`: End of the node  
+- `source`: Source file path (if provided during parsing)
+
+This is useful for:
+- Error reporting
+- Source mapping
+- Code analysis tools
+- IDE integration
+
+## Formatting Properties (`preserveFormatting: true`)
+
+When parsing with `preserveFormatting: true`, the parser stores additional formatting metadata on AST nodes to support exact round-trip via identity mode. These properties are optional and only present when formatting is preserved.
+
+### Whitespace Nodes
+
+`CssWhitespaceAST` nodes are inserted between sibling nodes in all arrays (rules, declarations, keyframes) to preserve the original whitespace and line breaks.
+
+### Raw Properties on Nodes
+
+- **`rawPrelude`** (on rules, at-rules with blocks): The exact original text before `{`, preserving whitespace between selector/condition and brace
+- **`rawBetween`** (on declarations): The text between the property name and value, including `:` and any surrounding whitespace (e.g., `": "` or `":  "`)
+- **`rawValue`** (on declarations): The untrimmed original value text
+- **`rawSource`** (on statement at-rules: import, charset, namespace, custom-media, layer statement): The exact original text of the entire at-rule
+
+### AST Modification with Identity Mode
+
+Because formatting data is stored per-node rather than as a single cached string, you can freely insert, remove, or modify AST nodes and identity mode will reflect the changes:
+
+```typescript
+const ast = parse(css, { preserveFormatting: true });
+
+// Insert a new rule — it will be beautified since it has no raw properties
+ast.stylesheet.rules.push({
+  type: CssTypes.rule,
+  selectors: ['.new'],
+  declarations: [{ type: CssTypes.declaration, property: 'color', value: 'blue' }]
+});
+
+// Remove a rule — the surrounding whitespace nodes naturally adapt
+ast.stylesheet.rules.splice(1, 1);
+
+// Identity mode outputs original formatting for untouched nodes + beautified for new nodes
+stringify(ast, { identity: true });
+```

package/www/node_modules/@node-projects/css-parser/docs/CHANGELOG.md

@@ -0,0 +1,205 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [5.0.0] - 2026-03.18
+
+### Changed
+- Fork from Adobe's `@adobe/css-tools` library to `@node-projects/css-tools` package
+- Only ESM code in package
+
+### Added
+- Add `preserveFormatting` parser option to insert whitespace AST nodes and store raw formatting properties for identity round-trip
+- Add `CssTypes.whitespace` node type (`CssWhitespaceAST`) to represent whitespace between sibling nodes
+- Add `identity` compiler option to reproduce original CSS exactly as parsed (round-trip fidelity), with support for AST modifications
+- Add `removeEmptyRules` compiler option to strip rules with empty declaration blocks
+- Add raw formatting properties: `rawPrelude`, `rawBetween`, `rawValue`, `rawSource` on relevant AST nodes
+- Export `CompilerOptions`, `ParseOptions`, and `CssWhitespaceAST` types from the public API
+
+## [4.4.4] - 2025-07-22
+
+### Changed
+- Switch from yarn to npm for package management
+- Switch from eslint to biome for code formatting and linting
+- Reformat codebase to comply with biome recommendations
+- Switch from webpack to rollup for bundling
+
+### Fixed
+- Fix module exports to ensure proper compatibility with bundlers
+- Add validation check to prevent future export issues
+
+## [4.4.3] - 2025-05-15
+
+### Security
+- Fix polynomial regular expression vulnerability on uncontrolled data
+- Refactor code to enable GitHub security static analysis
+
+### Performance
+- Improve parsing performance with minor optimizations
+- Replace regex patterns with string search (indexOf-based) for better performance
+
+### Added
+- Add new utility functions with comprehensive unit tests
+- Add improved formatting for CSS Grid template areas (#283 by @jogibear9988)
+
+### Fixed
+- Fix TypeScript error with ConstructorParameters in Parcel bundler (#444)
+
+## [4.4.2] - 2025-02-12
+
+### Fixed
+- Fix regular expression for parsing quoted values in parentheses
+
+## [4.4.0] - 2024-06-05
+
+### Added
+- Add support for CSS `@starting-style` at-rule (#319)
+
+## [4.3.3] - 2024-01-24
+
+### Changed
+- Update package export configuration (#271)
+
+## [4.3.2] - 2023-11-28
+
+### Security
+- Fix ReDoS vulnerability with crafted CSS strings - CVE-2023-48631
+
+### Fixed
+- Fix parsing issues with `:is()` and nested `:nth-child()` selectors (#211)
+
+## [4.3.1] - 2023-03-14
+
+### Security
+- Fix ReDoS vulnerability with crafted CSS strings - CVE-2023-26364
+
+## [4.3.0] - 2023-03-07
+
+### Changed
+- Update build toolchain and dependencies
+- Update package exports configuration and file structure
+
+## [4.2.0] - 2023-02-21
+
+### Added
+- Add support for CSS `@container` at-rule
+- Add support for CSS `@layer` at-rule
+
+## [4.1.0] - 2023-01-25
+
+### Added
+- Add support for ES Modules (ESM)
+
+## [4.0.2] - 2023-01-12
+
+### Fixed
+- Fix `@import` parsing when URL contains semicolons (#71)
+- Fix regression in selector parsing for attribute selectors (#77)
+
+## [4.0.1] - 2022-08-03
+
+### Fixed
+- Fix `globalThis` configuration for webpack to enable UMD module usage in Node.js environments
+
+## [4.0.0] - 2022-06-09
+
+### Changed
+- Fork from original css library to Adobe's `@adobe/css-tools` package
+- Convert codebase from JavaScript to TypeScript
+- Improve parsing performance by approximately 25%
+- Update all dependencies to latest versions
+- Remove source map support
+
+---
+
+## Legacy Versions (Pre-Adobe Fork)
+
+## [3.0.0] - 2020-07-01
+
+### Changed
+- Bump major version due to major dependency updates and Node.js version requirement changes
+
+## [2.2.1] - 2015-06-17
+
+### Fixed
+- Fix parsing of escaped quotes in quoted strings
+
+## [2.2.0] - 2015-02-18
+
+### Added
+- Add `parsingErrors` property to list errors when parsing with `silent: true`
+- Accept EOL characters and all whitespace characters in at-rules such as `@media`
+
+## [2.1.0] - 2014-08-05
+
+### Added
+- Add `inputSourcemaps` option to disable input source map processing
+- Add `sourcemap: 'generator'` option to return the `SourceMapGenerator` object
+- Use `inherits` package for inheritance (fixes browser compatibility issues)
+
+### Changed
+- Change error message format and add `.reason` property to error objects
+
+## [2.0.0] - 2014-06-18
+
+### Added
+- Add non-enumerable parent reference to each AST node
+- Add support for `@custom-media`, `@host`, and `@font-face` at-rules
+- Allow commas inside selector functions
+- Allow empty property values
+- Add `node.position.content` property
+- Integrate css-parse and css-stringify libraries
+- Apply original source maps from source files
+
+### Changed
+- Change default `options.position` value to `true`
+- Remove comments from properties and values
+
+### Removed
+- Drop Component(1) support
+
+### Fixed
+- Fix assertion errors when selectors are missing
+
+## [1.6.1] - 2014-01-02
+
+### Fixed
+- Fix component.json configuration
+
+## [1.6.0] - 2013-12-21
+
+### Changed
+- Update dependencies
+
+## [1.5.0] - 2013-12-03
+
+### Changed
+- Update dependencies
+
+## [1.1.0] - 2013-04-04
+
+### Changed
+- Update dependencies
+
+## [1.0.7] - 2012-11-21
+
+### Fixed
+- Fix component.json configuration
+
+## [1.0.4] - 2012-11-15
+
+### Changed
+- Update css-stringify dependency
+
+## [1.0.3] - 2012-09-01
+
+### Added
+- Add Component support
+
+## [0.0.1] - 2010-01-03
+
+### Added
+- Initial release