Skip to content

Extract HTML DSL and VDOM into separate packages#27

Merged
kevin-sakemaer merged 4 commits intomainfrom
claude/extract-spark-vdom-package-90iCf
Feb 13, 2026
Merged

Extract HTML DSL and VDOM into separate packages#27
kevin-sakemaer merged 4 commits intomainfrom
claude/extract-spark-vdom-package-90iCf

Conversation

@kevin-sakemaer
Copy link
Copy Markdown
Contributor

Summary

This PR extracts the HTML DSL and Virtual DOM functionality from the spark framework package into two new standalone packages: spark_html_dsl and spark_vdom. This improves modularity, allows independent versioning, and enables use of these components outside the full Spark framework.

Key Changes

  • New spark_html_dsl package: Contains core node types (Node, Text, RawHtml, Element) and HTML DSL helpers (h(), div(), span(), p(), a(), button(), input(), etc.)

    • Moved from packages/spark/lib/src/html/node.dart and elements.dart
    • Includes CSP nonce injection support via Dart Zones
    • Provides Element.eventWrapper static hook for event wrapping
    • Comprehensive test coverage in elements_test.dart, html_test.dart, and node_test.dart
  • New spark_vdom package: Contains the browser-side Virtual DOM engine

    • Moved from packages/spark/lib/src/component/vdom_web.dart
    • Exports mount(), mountList(), patch(), and createNode() functions
    • Handles efficient DOM diffing, patching, and hydration
    • Includes SVG namespace handling and foreignObject context switching
    • Provides conditional exports: browser implementation for web, stub for VM/server
    • Comprehensive test coverage including memory leak tests, hydration tests, and attribute patching tests
  • Updated spark package: Now depends on spark_html_dsl and spark_vdom as external dependencies

    • Removed internal HTML DSL and VDOM implementations
    • Updated all imports to use the new packages
    • Removed packages/spark/lib/src/html/dsl.dart and extensions.dart
    • Updated spark.dart to re-export from new packages
  • Updated workspace: Added new packages to pubspec.yaml workspace configuration

  • Test updates: Migrated all HTML DSL and VDOM tests to their respective new packages, with updated imports throughout the spark package test suite

Notable Implementation Details

  • Both new packages use conditional imports to provide browser-specific implementations while maintaining VM/server compatibility
  • The VDOM engine includes sophisticated namespace handling for SVG elements and proper context switching for foreignObject
  • CSP nonce injection is implemented via Dart Zones, allowing secure inline script/style injection
  • Event listener cleanup is properly handled to prevent memory leaks during DOM patching
  • Hydration logic intelligently skips comment nodes and reuses existing DOM elements when possible

https://claude.ai/code/session_016djT9tGK3QkDpcRN7gmerd

Split the VDOM system from spark_framework into two standalone packages:

- spark_html_dsl: Pure Dart package with VNode types (VNode, Text, RawHtml,
  Element) and HTML DSL helpers (div, span, h1, button, input, etc.).
  Zero external dependencies.

- spark_vdom: Browser VDOM engine (mount, patch, createNode, mountList)
  with server/VM stubs. Depends on spark_html_dsl + package:web.
  Re-exports spark_html_dsl for convenience.

spark_framework now depends on both packages and uses re-export shims
to preserve all existing import paths. Also removes the unused
extensions.dart (SparkEventTargetExtension).

Both new packages are fully tested (55 tests total across VM and browser).
All 342 existing spark_framework tests continue to pass.

https://claude.ai/code/session_016djT9tGK3QkDpcRN7gmerd
- Rename VNode to Node across spark_html_dsl and spark_vdom (the old
  name was to avoid dart:html conflict which no longer applies)
- Remove re-export shim files from spark_framework (dsl.dart,
  node.dart, elements.dart, vdom.dart, vdom_web.dart, vdom_stub.dart)
- Update spark.dart barrel to export directly from spark_html_dsl
- Add public barrel exports to spark_vdom (vdom.dart, vdom_web.dart)
- Update all spark_framework imports to point directly to new packages
- Resolve ambiguous_export by hiding Node from spark_web re-export

https://claude.ai/code/session_016djT9tGK3QkDpcRN7gmerd
…rrides

The openapi test files create temp projects with a path dependency on
spark_framework. Since spark_framework now depends on spark_html_dsl
and spark_vdom, those packages also need local path overrides for
dart pub get to resolve them.

https://claude.ai/code/session_016djT9tGK3QkDpcRN7gmerd
@kevin-sakemaer kevin-sakemaer marked this pull request as ready for review February 13, 2026 13:59
@kevin-sakemaer kevin-sakemaer merged commit 919a0ef into main Feb 13, 2026
5 checks passed
@kevin-sakemaer kevin-sakemaer deleted the claude/extract-spark-vdom-package-90iCf branch February 13, 2026 13:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants