Skip to content

spark_web

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

spark_web

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
lib
lib
 
 
test
test
 
 
CHANGELOG.md
CHANGELOG.md
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
pubspec.yaml
pubspec.yaml
 
 

README.md

spark_web

Server-safe Web API abstraction for Dart, mirroring the MDN Web API naming exactly.

Overview

spark_web provides a cross-platform Web API layer that works on both the Dart VM (server) and dart2js/dart2wasm (browser).

  • On the browser, types wrap the real package:web DOM objects.
  • On the server, types are no-ops or provide Dart-native fallbacks (e.g., Storage backed by a Map, Crypto.randomUUID() via dart:math).

Because the naming matches MDN exactly, developers can look up any type or method on MDN Web Docs and apply the same knowledge.

Installation

dependencies:
  spark_web:
    path: ../spark_web  # or from pub

Usage

import 'package:spark_web/spark_web.dart' as web;

void main() {
  // DOM — same API as MDN
  final el = web.document.querySelector('#app');
  el?.classList.add('ready');
  el?.setAttribute('data-loaded', 'true');

  // Window
  web.window.localStorage.setItem('key', 'value');
  final uuid = web.window.crypto.randomUUID();

  // Events
  el?.addEventListener('click', (event) {
    print('Clicked: ${event.type}');
  });

  // Clipboard
  web.window.navigator.clipboard.writeText('Hello!');

  // Timers
  web.window.setTimeout(() => print('delayed'), 1000);
}

Accessing the native package:web object

On the browser, every spark_web type wraps a native package:web object. Use .raw to access it:

final sparkElement = web.document.querySelector('div');
final nativeElement = sparkElement?.raw; // web.Element from package:web (null on server)

Permissions

final status = await web.window.navigator.permissions.query(
  const web.PermissionDescriptor(name: web.PermissionName.camera),
);
print(status.state); // PermissionState(prompt)

Platform detection

if (web.kIsBrowser) {
  // Browser-only code
}

Architecture

spark_web/lib/
├── spark_web.dart              # Barrel export + global singletons (window, document)
└── src/
    ├── api.dart                # Conditional import pivot (server ↔ browser)
    ├── core.dart               # EventTarget, Event, Node, NodeList, MutationObserver
    ├── dom.dart                # Element, HTMLElement, Document, ShadowRoot, Text, Comment
    ├── collections.dart        # DOMTokenList, NamedNodeMap, Attr
    ├── css.dart                # CSSStyleSheet, CSSStyleDeclaration
    ├── canvas.dart             # CanvasRenderingContext2D, TextMetrics, ImageData
    ├── file.dart               # Blob, File, FileList
    ├── geolocation.dart        # Geolocation, GeolocationPosition, GeolocationCoordinates
    ├── notification.dart       # Notification, NotificationOptions, NotificationAction
    ├── permissions.dart        # Permissions, PermissionStatus, PermissionDescriptor
    ├── window.dart             # Window, Storage, Location, History, Navigator, Console, ...
    ├── server/                 # Server implementations (no-ops / Dart-native fallbacks)
    │   ├── factory.dart
    │   ├── dom.dart
    │   ├── collections.dart
    │   ├── css.dart
    │   ├── canvas.dart
    │   ├── file.dart
    │   ├── geolocation.dart
    │   ├── notification.dart
    │   ├── permissions.dart
    │   └── window.dart
    └── browser/                # Browser implementations (wrap package:web)
        ├── factory.dart
        ├── dom.dart
        ├── collections.dart
        ├── css.dart
        ├── canvas.dart
        ├── file.dart
        ├── geolocation.dart
        ├── notification.dart
        ├── permissions.dart
        └── window.dart

API Coverage

The table below tracks what percentage of the MDN Web API is implemented. Contributions welcome!

DOM Core

API Status Notes
EventTarget ✅ Done addEventListener, removeEventListener, dispatchEvent
Event ✅ Done type, target, currentTarget, bubbles, cancelable, preventDefault, stopPropagation, stopImmediatePropagation
MouseEvent ✅ Done clientX/Y, pageX/Y, screenX/Y, button, buttons, modifier keys
KeyboardEvent ✅ Done key, code, repeat, location, modifier keys
InputEvent ✅ Done data, inputType, isComposing
FocusEvent ✅ Done relatedTarget
WheelEvent ✅ Done deltaX, deltaY, deltaZ, deltaMode
TouchEvent ✅ Done touches, targetTouches, changedTouches, modifier keys
PointerEvent ✅ Done pointerId, width, height, pressure, tangentialPressure, tiltX/Y, twist, pointerType, isPrimary
DragEvent ✅ Done dataTransfer
AnimationEvent ✅ Done animationName, elapsedTime, pseudoElement
TransitionEvent ✅ Done propertyName, elapsedTime, pseudoElement
CustomEvent ✅ Done detail
Node ✅ Done Full tree traversal, appendChild, removeChild, cloneNode, etc.
NodeList ✅ Done length, item()
MutationObserver ✅ Done observe, disconnect, takeRecords
MutationRecord ✅ Done type, target, addedNodes, removedNodes, attributeName
TreeWalker ❌ TODO
NodeIterator ❌ TODO
Range ❌ TODO
Selection ❌ TODO

DOM Elements

API Status Notes
Element ✅ Done tagName, id, className, innerHTML, classList, querySelector, etc.
HTMLElement ✅ Done innerText, hidden, title, style, shadowRoot, attachShadow
HTMLDivElement ✅ Done
HTMLSpanElement ✅ Done
HTMLParagraphElement ✅ Done
HTMLInputElement ✅ Done value, type, placeholder, disabled, checked, name
HTMLTextAreaElement ✅ Done value, placeholder, disabled, rows, cols
HTMLButtonElement ✅ Done disabled, type
HTMLSelectElement ✅ Done value, selectedIndex, disabled
HTMLOptionElement ✅ Done value, text, selected
HTMLAnchorElement ✅ Done href, target
HTMLImageElement ✅ Done src, alt, width, height
HTMLFormElement ✅ Done action, method, submit(), reset(), reportValidity()
HTMLLabelElement ✅ Done htmlFor
HTMLTemplateElement ✅ Done content
HTMLCanvasElement ✅ Done getContext(), toDataURL(), width, height
HTMLMediaElement ✅ Done src, currentTime, duration, paused, volume, play(), pause(), load(), etc.
HTMLVideoElement ✅ Done width, height, videoWidth, videoHeight, poster, playsInline
HTMLAudioElement ✅ Done Inherits all from HTMLMediaElement
HTMLDialogElement ✅ Done open, returnValue, show(), showModal(), close()
HTMLDetailsElement ✅ Done open, name
HTMLSlotElement ✅ Done name, assignedNodes(), assignedElements()
HTMLIFrameElement ✅ Done src, name, allow, allowFullscreen, width, height, loading, referrerPolicy
HTMLTableElement ✅ Done caption, tHead, tFoot, createTBody(), insertRow(), deleteRow()
HTMLTableSectionElement ✅ Done insertRow(), deleteRow()
HTMLTableRowElement ✅ Done rowIndex, sectionRowIndex, insertCell(), deleteCell()
HTMLTableCellElement ✅ Done colSpan, rowSpan, cellIndex
HTMLHeadingElement ✅ Done h1–h6
HTMLUListElement ✅ Done
HTMLOListElement ✅ Done reversed, start, type
HTMLLIElement ✅ Done value
HTMLPreElement ✅ Done
HTMLHRElement ✅ Done
HTMLBRElement ✅ Done
HTMLProgressElement ✅ Done value, max, position
HTMLMeterElement ✅ Done value, min, max, low, high, optimum
HTMLOutputElement ✅ Done value, defaultValue, name, type, htmlFor

Document & Fragments

API Status Notes
Document ✅ Done createElement, createTextNode, querySelector, getElementById, etc.
DocumentFragment ✅ Done querySelector, querySelectorAll
ShadowRoot ✅ Done host, mode, adoptedStyleSheets, querySelector
Text ✅ Done data, wholeText
Comment ✅ Done data
DOMParser ❌ TODO parseFromString()
XMLSerializer ❌ TODO serializeToString()

Collections

API Status Notes
DOMTokenList ✅ Done add, remove, toggle, contains, replace
NamedNodeMap ✅ Done item, getNamedItem, removeNamedItem
Attr ✅ Done name, value
HTMLCollection ❌ TODO namedItem()
DOMStringMap ❌ TODO dataset access
DOMRect ❌ TODO x, y, width, height, top, right, bottom, left
DOMRectReadOnly ❌ TODO

CSS

API Status Notes
CSSStyleSheet ✅ Done replaceSync, replace
CSSStyleDeclaration ✅ Done getPropertyValue, setProperty, removeProperty, display, visibility, opacity
CSSRule ❌ TODO
CSSStyleRule ❌ TODO
CSSMediaRule ❌ TODO
CSSKeyframesRule ❌ TODO
CSSKeyframeRule ❌ TODO
MediaQueryList ❌ TODO matches, media, addListener()
StyleSheetList ❌ TODO

Window & Globals

API Status Notes
Window ✅ Done document, localStorage, setTimeout, requestAnimationFrame, btoa/atob, etc.
Storage ✅ Done getItem, setItem, removeItem, clear, key, length
Location ✅ Done href, protocol, host, pathname, search, hash, origin, etc.
History ✅ Done pushState, replaceState, back, forward, go, state
Navigator ✅ Done userAgent, language, languages, onLine, clipboard
Console ✅ Done log, warn, error, info, debug
Crypto ✅ Done randomUUID()
Performance ✅ Done now()
CustomElementRegistry ✅ Done define, get, upgrade, whenDefined
Clipboard ✅ Done readText, writeText
Screen ❌ TODO width, height, availWidth, availHeight, orientation
VisualViewport ❌ TODO width, height, offsetLeft, offsetTop, scale
BarProp ❌ TODO visible

Async & Networking

API Status Notes
fetch() ❌ TODO Global fetch function
Request ❌ TODO
Response ❌ TODO
Headers ❌ TODO
AbortController ❌ TODO signal, abort()
AbortSignal ❌ TODO aborted, reason
URL ❌ TODO href, origin, protocol, host, pathname, search, hash
URLSearchParams ❌ TODO get, set, append, delete, entries
WebSocket ❌ TODO send(), close(), readyState
EventSource ❌ TODO Server-sent events
XMLHttpRequest ❌ TODO Legacy — consider skipping
FormData ❌ TODO append, get, set, entries
Blob ✅ Done size, type, text(), arrayBuffer(), slice(), stream()
File ✅ Done name, lastModified (extends Blob)
FileList ✅ Done length, item()
FileReader ❌ TODO readAsText(), readAsDataURL(), result

Observers

API Status Notes
MutationObserver ✅ Done observe, disconnect, takeRecords
IntersectionObserver ❌ TODO observe, disconnect, unobserve
ResizeObserver ❌ TODO observe, disconnect, unobserve
PerformanceObserver ❌ TODO

Canvas & Graphics

API Status Notes
CanvasRenderingContext2D ✅ Done Full 2D drawing: rect, path, arc, bezier, text, image, pixel manipulation, transforms, state save/restore, line dash, compositing
TextMetrics ✅ Done width, actualBoundingBoxLeft/Right/Ascent/Descent, fontBoundingBoxAscent/Descent
ImageData ✅ Done width, height, data
OffscreenCanvas ❌ TODO
Path2D ❌ TODO
WebGLRenderingContext ❌ TODO Consider out of scope
WebGL2RenderingContext ❌ TODO Consider out of scope

Media

API Status Notes
MediaStream ❌ TODO
MediaRecorder ❌ TODO
MediaDevices ❌ TODO getUserMedia()
AudioContext ❌ TODO Web Audio API

Web Workers

API Status Notes
Worker ❌ TODO postMessage(), terminate()
SharedWorker ❌ TODO
ServiceWorkerContainer ❌ TODO
BroadcastChannel ❌ TODO postMessage(), close()
MessageChannel ❌ TODO
MessagePort ❌ TODO

Geometry & Layout

API Status Notes
Element.getBoundingClientRect() ❌ TODO Returns DOMRect
Element.getClientRects() ❌ TODO
Element.scrollIntoView() ❌ TODO
Element.scrollTo() ❌ TODO
Element.scroll properties ❌ TODO scrollTop, scrollLeft, scrollWidth, scrollHeight
Element.client properties ❌ TODO clientWidth, clientHeight, clientTop, clientLeft
Element.offset properties ❌ TODO offsetWidth, offsetHeight, offsetTop, offsetLeft, offsetParent

Miscellaneous

API Status Notes
Crypto.getRandomValues() ❌ TODO Typed array crypto
SubtleCrypto ❌ TODO encrypt, decrypt, sign, verify, digest
TextEncoder ❌ TODO encode()
TextDecoder ❌ TODO decode()
structuredClone() ❌ TODO
queueMicrotask() ❌ TODO
Notification ✅ Done title, body, icon, tag, close(), NotificationOptions, NotificationAction, requestPermission()
Geolocation ✅ Done getCurrentPosition, watchPosition, clearWatch, GeolocationPosition, GeolocationCoordinates, PositionOptions
Permissions ✅ Done query(), PermissionStatus, PermissionState, PermissionName, PermissionDescriptor (+ Push, Midi, Device variants)
FullScreen API ❌ TODO requestFullscreen(), exitFullscreen()

Legend: ✅ Done — ❌ TODO

Not all MDN Web APIs are equally relevant for server-safe rendering. The coverage plan prioritizes APIs commonly used in component code (DOM, events, forms, CSS) over niche APIs (WebGL, Web Audio, WebRTC).