spark library

Spark Framework - Lightweight isomorphic SSR for Dart.

This library provides the core building blocks for creating isomorphic web components that can be rendered on the server and hydrated in the browser. It exports the base WebComponent class, the SparkComponent for vDOM-based components, and other shared utilities.

Libraries

package:spark/spark.dart: Core isomorphic library. Import this in your components and shared code.
package:spark/server.dart: Server-side utilities (rendering, routing). Import this only in your server entry point (e.g., bin/server.dart).

Quick Start

Import this library in your components:
```
import 'package:spark/spark.dart';
```

Create a reactive component by extending SparkComponent:

@Component(tag: 'my-counter')
class Counter extends SparkComponent {
  @Attribute(observable: true)
  int count = 0;

  @override
  html.Element build() {
    return html.div(
      ['Count: $count'],
      onClick: (_) => count++,
    );
  }
}

// web/main.dart
void main() {
  Counter.register();
}

Server-Side Rendering (SSR)

For server-side rendered pages, use the @Page annotation and SparkPage class. See package:spark/server.dart for details.

Classes

AnimationEvent: An animation event.
Attr: An attribute on an Element.
Attribute: Marks a field as a reactive attribute.
CanvasRenderingContext2D: Provides 2D rendering methods for the <canvas> element.
Clipboard: Provides read and write access to the system clipboard.
Component: Marks a class as an island component that can be hydrated on the client.
ComponentStyleRegistry: Registry for component CSS.
Console: Provides access to the debugging console.
Cookie: Represents an HTTP Cookie.
Crypto: Provides access to cryptographic functions.
CssAlignContent: CSS align-content property values.
CssAlignItems: CSS align-items property values.
CssAlignSelf: CSS align-self property values.
CssAngle: CSS angle value.
CssBackgroundAttachment: CSS background-attachment property values.
CssBackgroundClip: CSS background-clip property values.
CssBackgroundImage: CSS background-image property values.
CssBackgroundOrigin: CSS background-origin property values.
CssBackgroundPosition: CSS background-position property values.
CssBackgroundRepeat: CSS background-repeat property values.
CssBackgroundSize: CSS background-size property values.
CssBorder: CSS border shorthand value.
CssBorderRadius: CSS border-radius value.
CssBorderStyle: CSS border-style values.
CssBoxShadow: CSS box-shadow value type.
CssColor: CSS color value type.
CssCursor: CSS cursor property values.
CssDisplay: CSS display property values.
CssFilter: CSS filter function values.
CssFlexDirection: CSS flex-direction property values.
CssFlexShorthand: CSS flex shorthand property values.
CssFlexWrap: CSS flex-wrap property values.
CssFontFamily: CSS font-family value.
CssFontStyle: CSS font-style property values.
CssFontWeight: CSS font-weight property values.
CssGlobal: Global CSS keywords applicable to any property.
CssGradientStop: Represents a color stop in a gradient.
CssJustifyContent: CSS justify-content property values.
CssLength: CSS length/size value type.
CssNumber: CSS numeric value (unitless). Used for z-index, opacity, line-height, flex-grow, flex-shrink, etc.
CssOutline: CSS outline shorthand property.
CssOutlineOffset: CSS outline-offset property.
CssOverflow: CSS overflow property values.
CssPosition: CSS position property values.
CssSpacing: CSS spacing value for margin and padding properties.
CssStyle: A common interface for CSS styles and stylesheets.
CSSStyleDeclaration: Represents an element's inline CSS styles.
CSSStyleSheet: A CSS stylesheet that can be constructed and applied to shadow roots.
CssTextAlign: CSS text-align property values.
CssTextDecoration: CSS text-decoration property values.
CssTextShadow: CSS text-shadow value type.
CssTextTransform: CSS text-transform property values.
CssTimingFunction: CSS transition-timing-function values.
CssTransform: CSS transform functions.
CssTransition: CSS transition value.
CssValue: Base interface for all CSS value types. All CSS types implement this interface to provide CSS string output.
CssWhiteSpace: CSS white-space property values.
CssWordBreak: CSS word-break property values.
CssZIndex: CSS z-index value (accepts auto and integers).
CustomElementRegistry: Registry for custom elements.
CustomEvent: A custom event with arbitrary detail data.
DataTransfer: Holds the data being dragged during a drag-and-drop operation.
DocumentFragment: See: https://developer.mozilla.org/en-US/docs/Web/API/DocumentFragment
DOMTokenList: A set of space-separated tokens (e.g., CSS classes via Element.classList).
DragEvent: A drag event.
Element: An HTML element with a tag, attributes, and children.
ElementDefinitionOptions: Options for CustomElementRegistry.define.
Email: Validates that a string is a valid email.
Endpoint: Annotation for defining API endpoints.
Event: Represents an event that takes place on an EventTarget.
EventTarget: Base interface for objects that can receive events.
ExternalDocumentation: Allows referencing an external resource for extended documentation.
FocusEvent: A focus event.
Geolocation: The Geolocation interface represents an object able to programmatically obtain the position of the device.
GeolocationCoordinates: Represents the position and altitude of the device on Earth, as well as the accuracy with which these properties are calculated.
GeolocationPosition: Represents the position of the concerned device at a given time.
GeolocationPositionError: Represents the reason of an error occurring when using the geolocating device.
History: Allows manipulation of the browser session history.
HTMLAnchorElement: See: https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement
HTMLAudioElement: See: https://developer.mozilla.org/en-US/docs/Web/API/HTMLAudioElement
HTMLBRElement: See: https://developer.mozilla.org/en-US/docs/Web/API/HTMLBRElement
HTMLButtonElement: See: https://developer.mozilla.org/en-US/docs/Web/API/HTMLButtonElement
HTMLCanvasElement: See: https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement
HTMLCollection: A collection of Element objects.
HTMLDetailsElement: See: https://developer.mozilla.org/en-US/docs/Web/API/HTMLDetailsElement
HTMLDialogElement: See: https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement
HTMLDivElement: See: https://developer.mozilla.org/en-US/docs/Web/API/HTMLDivElement
HTMLElement: Represents an HTML Element.
HTMLFormElement: See: https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement
HTMLHeadingElement: See: https://developer.mozilla.org/en-US/docs/Web/API/HTMLHeadingElement
HTMLHRElement: See: https://developer.mozilla.org/en-US/docs/Web/API/HTMLHRElement
HTMLIFrameElement: See: https://developer.mozilla.org/en-US/docs/Web/API/HTMLIFrameElement
HTMLImageElement: See: https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement
HTMLInputElement: See: https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement
HTMLLabelElement: See: https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement
HTMLLIElement: See: https://developer.mozilla.org/en-US/docs/Web/API/HTMLLIElement
HTMLMediaElement: Base class for media elements (audio & video).
HTMLMeterElement: See: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMeterElement
HTMLOListElement: See: https://developer.mozilla.org/en-US/docs/Web/API/HTMLOListElement
HTMLOptionElement: See: https://developer.mozilla.org/en-US/docs/Web/API/HTMLOptionElement
HTMLOutputElement: See: https://developer.mozilla.org/en-US/docs/Web/API/HTMLOutputElement
HTMLParagraphElement: See: https://developer.mozilla.org/en-US/docs/Web/API/HTMLParagraphElement
HTMLPreElement: See: https://developer.mozilla.org/en-US/docs/Web/API/HTMLPreElement
HTMLProgressElement: See: https://developer.mozilla.org/en-US/docs/Web/API/HTMLProgressElement
HTMLSelectElement: See: https://developer.mozilla.org/en-US/docs/Web/API/HTMLSelectElement
HTMLSlotElement: See: https://developer.mozilla.org/en-US/docs/Web/API/HTMLSlotElement
HTMLSpanElement: See: https://developer.mozilla.org/en-US/docs/Web/API/HTMLSpanElement
HTMLTableCellElement: See: https://developer.mozilla.org/en-US/docs/Web/API/HTMLTableCellElement
HTMLTableElement: See: https://developer.mozilla.org/en-US/docs/Web/API/HTMLTableElement
HTMLTableRowElement: See: https://developer.mozilla.org/en-US/docs/Web/API/HTMLTableRowElement
HTMLTableSectionElement: See: https://developer.mozilla.org/en-US/docs/Web/API/HTMLTableSectionElement
HTMLTemplateElement: See: https://developer.mozilla.org/en-US/docs/Web/API/HTMLTemplateElement
HTMLTextAreaElement: See: https://developer.mozilla.org/en-US/docs/Web/API/HTMLTextAreaElement
HTMLUListElement: See: https://developer.mozilla.org/en-US/docs/Web/API/HTMLUListElement
HTMLVideoElement: See: https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement
ImageData: Represents pixel data for a rectangular area of a canvas.
InputEvent: An input event.
IsBooleanString: Validates that a string represents a boolean ("true", "false", "1", "0").
IsDate: Validates that a string is a valid date (ISO 8601).
IsNumeric: Validates that a string contains only numbers.
IsString: Validates that a value is a string.
KeyboardEvent: A keyboard event.
Length: Validates that a string length is within min and max.
Location: Represents the URL of the current document.
Max: Validates that a number is at most value.
Min: Validates that a number is at least value.
MouseEvent: A mouse event.
MultipartPart: Represents a part in a multipart request.
MutationObserver: See observers.dart for the full definition — re-exported here to break the circular dependency between core.dart and observers.dart.
MutationObserverInit: Initialization options for MutationObserver.observe.
MutationRecord: A single mutation record observed by a MutationObserver.
NamedNodeMap: A collection of Attr objects.
Navigator: Information about the user agent.
Node: Base class for all HTML nodes.
NodeList: A list of Node objects.
NotEmpty: Validates that a string is not empty.
Notification: A system notification displayed to the user.
NotificationAction: Describes an action button shown in a notification.
NotificationDirection: Direction for notification text display.
NotificationOptions: Options for creating a Notification.
NotificationPermission: Permission state for the Notification API.
OpenApi: global configuration for the OpenAPI specification.
Page: Marks a class as a page that will be registered with the Spark router.
PageData<T>: Response containing typed data to render the page.
PageError: Response for rendering an error page.
PageRedirect: Response indicating a redirect to another URL.
PageResponse<T>: Sealed class representing possible responses from a page loader.
Parameter: Describes a single operation parameter.
Pattern: Validates that a string matches the given pattern.
Performance: Provides access to performance-related information.
PointerEvent: A pointer event.
PositionOptions: Options for methods Geolocation.getCurrentPosition and Geolocation.watchPosition.
Props: A typed wrapper for component props that provides convenient accessors.
RawHtml: A raw HTML node. The content is rendered exactly as provided, without escaping. Use with caution.
RenderingContext: Base type for canvas rendering contexts.
SecurityScheme: Defines a security scheme for the API.
SecuritySchemeFlow: Defines an OAuth2 flow.
ServerAnimationEvent
ServerCustomEvent
ServerDataTransfer
ServerDragEvent
ServerEvent
ServerFocusEvent
ServerInputEvent
ServerKeyboardEvent
ServerMouseEvent
ServerPointerEvent
ServerTouch
ServerTouchEvent
ServerTouchList
ServerTransitionEvent
ServerWheelEvent
ShadowRoot: See: https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot
ShadowRootInit: Options for HTMLElement.attachShadow.
SparkComponent: A reactive Web Component for Spark.
SparkEndpoint: Abstract base class for Spark API endpoints without a request body.
SparkEndpointWithBody<T>: Abstract base class for Spark API endpoints with a typed request body.
SparkPage<T>: Abstract base class for Spark pages.
SparkRequest: Request context for page loaders.
Storage: Provides access to session or local storage.
Style: A typed representation of CSS styles.
Stylesheet: A map of CSS selectors to their styles.
Text: A text node containing a string value. The content is automatically escaped when rendered.
TextMetrics: Measurement of a text string.
Touch: A single contact point on a touch-sensitive device.
TouchEvent: A touch event.
TouchList: A list of Touch objects.
TransitionEvent: A transition event.
Validator: Base class for all validators.
WebComponent: Abstract base class for Spark components.
WheelEvent: A wheel event.
Window: The global window object.

Enums

CanvasContextType: Identifies the type of rendering context to create.
ContentType: Standardized content types supported by Spark.
SameSite: Represents the SameSite attribute of a cookie.

Constants

kIsBrowser → const bool: Whether the code is running in a browser environment.

Properties

componentStyles → ComponentStyleRegistry: Global registry instance.
final
document → Document: The global document object.
final
notificationMaxActions → int: Returns the max actions on server (always 0).
no setter
notificationPermission → NotificationPermission: Returns the notification permission on server (always 'default').
no setter
window → Window: The global window object.
final

Functions

a(dynamic children, {String? href, String? target, String? id, String? className, Map<String, dynamic>? attributes, dynamic onClick(MouseEvent)?}) → Element
article(dynamic children, {String? id, String? className, Map<String, dynamic>? attributes}) → Element
aside(dynamic children, {String? id, String? className, Map<String, dynamic>? attributes}) → Element
b(dynamic children, {String? id, String? className, Map<String, dynamic>? attributes}) → Element
blockquote(dynamic children, {String? id, String? className, Map<String, dynamic>? attributes}) → Element
body(dynamic children, {String? id, String? className, Map<String, dynamic>? attributes}) → Element
br() → Element
button(dynamic children, {String? type, String? id, String? className, Map<String, dynamic>? attributes, dynamic onClick(MouseEvent)?}) → Element
canvasContextTypeToString(CanvasContextType type) → String: Returns the native context-type string (e.g. '2d') for the given enum.
clearStyleSheetCache() → void: Clears the stylesheet cache.
code(dynamic children, {String? id, String? className, Map<String, dynamic>? attributes}) → Element
createAnimationEvent(String type) → AnimationEvent: Creates a server-side AnimationEvent.
createCSSStyleSheet() → CSSStyleSheet: Creates a server-side CSSStyleSheet (no-op).
createCustomEvent(String type, [Object? detail]) → CustomEvent: Creates a server-side CustomEvent.
createDocument() → Document: Creates a server-side Document instance.
createDragEvent(String type) → DragEvent: Creates a server-side DragEvent.
createEvent(String type) → Event: Creates a server-side Event.
createFocusEvent(String type) → FocusEvent: Creates a server-side FocusEvent.
createInputEvent(String type) → InputEvent: Creates a server-side InputEvent.
createKeyboardEvent(String type) → KeyboardEvent: Creates a server-side KeyboardEvent.
createMouseEvent(String type) → MouseEvent: Creates a server-side MouseEvent.
createMutationObserver(MutationCallback callback) → MutationObserver: Creates a server-side MutationObserver.
createNotification(String title, [NotificationOptions? options]) → Notification: Creates a server-side Notification (no-op).
createPointerEvent(String type) → PointerEvent: Creates a server-side PointerEvent.
createStyleSheet(String cssText) → CSSStyleSheet: Creates or retrieves a cached web.CSSStyleSheet from the given CSS string.
createTouchEvent(String type) → TouchEvent: Creates a server-side TouchEvent.
createTransitionEvent(String type) → TransitionEvent: Creates a server-side TransitionEvent.
createWheelEvent(String type) → WheelEvent: Creates a server-side WheelEvent.
createWindow() → Window: Creates a server-side Window instance.
css(Map<String, Style> rules) → Stylesheet: Helper to create a stylesheet from a map of rules.
decodeProps(String encoded) → Map<String, dynamic>: Decodes a base64-encoded JSON string back to a Map.
div(dynamic children, {String? id, String? className, Map<String, dynamic>? attributes, dynamic onClick(MouseEvent)?, dynamic onDoubleClick(MouseEvent)?, dynamic onMouseEnter(MouseEvent)?, dynamic onMouseLeave(MouseEvent)?}) → Element
element(String tag, dynamic children, {String? id, String? className, Map<String, dynamic>? attributes}) → Element: Generic helper for custom elements.
em(dynamic children, {String? id, String? className, Map<String, dynamic>? attributes}) → Element
encodeProps(Map<String, dynamic> props) → String: Encodes a Map as a base64-encoded JSON string for use in HTML attributes.
footer(dynamic children, {String? id, String? className, Map<String, dynamic>? attributes}) → Element
form(dynamic children, {String? action, String? method, String? id, String? className, Map<String, dynamic>? attributes}) → Element
getPropsBool(Map<String, dynamic> props, String key, [bool defaultValue = false]) → bool: Extracts a bool value from props.
getPropsDouble(Map<String, dynamic> props, String key, [double defaultValue = 0.0]) → double: Extracts a double value from props.
getPropsInt(Map<String, dynamic> props, String key, [int defaultValue = 0]) → int: Extracts an int value from props.
getPropsList<T>(Map<String, dynamic> props, String key) → List<T>: Extracts a List value from props.
getPropsMap(Map<String, dynamic> props, String key) → Map<String, dynamic>: Extracts a nested Map value from props.
getPropsString(Map<String, dynamic> props, String key, [String defaultValue = '']) → String: Extracts a String value from props.
getPropsValue<T>(Map<String, dynamic> props, String key, T defaultValue) → T: Type-safe props helper for extracting values from decoded props.
h(String tag, {String? id, String? className, Map<String, dynamic>? attributes, Map<String, Function>? events, List? children, bool selfClosing = false}) → Element: Creates a generic virtual DOM element.
h1(dynamic children, {String? id, String? className, Map<String, dynamic>? attributes}) → Element
h2(dynamic children, {String? id, String? className, Map<String, dynamic>? attributes}) → Element
h3(dynamic children, {String? id, String? className, Map<String, dynamic>? attributes}) → Element
h4(dynamic children, {String? id, String? className, Map<String, dynamic>? attributes}) → Element
h5(dynamic children, {String? id, String? className, Map<String, dynamic>? attributes}) → Element
h6(dynamic children, {String? id, String? className, Map<String, dynamic>? attributes}) → Element
head(dynamic children, {String? id, String? className, Map<String, dynamic>? attributes}) → Element
header(dynamic children, {String? id, String? className, Map<String, dynamic>? attributes}) → Element
hr({String? id, String? className, Map<String, dynamic>? attributes}) → Element
html(dynamic children, {String? id, String? className, Map<String, dynamic>? attributes}) → Element
hydrateAll() → void: Hydrates all registered components found in the DOM.
hydrateComponents(Map<String, ComponentFactory> components) → void: Convenience function to register multiple components and hydrate.
i(dynamic children, {String? id, String? className, Map<String, dynamic>? attributes}) → Element
img({String? src, String? alt, String? id, String? className, Map<String, dynamic>? attributes}) → Element
input<T>({String? type, String? name, T? value, String? placeholder, String? id, String? className, Map<String, dynamic>? attributes, FutureOr<void> onInput(Event)?, dynamic onChange(Event)?, dynamic onKeyDown(KeyboardEvent)?, dynamic onKeyUp(KeyboardEvent)?}) → Element
label(dynamic children, {String? htmlFor, String? id, String? className, Map<String, dynamic>? attributes}) → Element
li(dynamic children, {String? id, String? className, Map<String, dynamic>? attributes}) → Element
link({String? id, String? className, String? rel, String? href, Map<String, dynamic>? attributes}) → Element
main(dynamic children, {String? id, String? className, Map<String, dynamic>? attributes}) → Element
meta({String? id, String? className, Map<String, dynamic>? attributes}) → Element
nav(dynamic children, {String? id, String? className, Map<String, dynamic>? attributes}) → Element
ol(dynamic children, {String? id, String? className, Map<String, dynamic>? attributes}) → Element
option(dynamic children, {String? value, bool? selected, String? id, String? className, Map<String, dynamic>? attributes}) → Element
p(dynamic children, {String? id, String? className, Map<String, dynamic>? attributes}) → Element
pre(dynamic children, {String? id, String? className, Map<String, dynamic>? attributes}) → Element
query(String selector) → Element?: Queries for an element within the component's shadow root.
queryAll(String selector) → List<Element>: Queries for all matching elements within the component's shadow root.
registerComponent(String tagName, ComponentFactory factory) → void: Registers a component factory for hydration.
requestNotificationPermission() → Future<NotificationPermission>: Requests notification permission on server (always returns 'default').
s(dynamic children, {String? id, String? className, Map<String, dynamic>? attributes}) → Element
script(dynamic children, {String? src, String? type, bool? async, bool? defer, String? id, String? className, Map<String, dynamic>? attributes}) → Element
section(dynamic children, {String? id, String? className, Map<String, dynamic>? attributes}) → Element
select(dynamic children, {String? name, String? id, String? className, Map<String, dynamic>? attributes}) → Element
small(dynamic children, {String? id, String? className, Map<String, dynamic>? attributes}) → Element
span(dynamic children, {String? id, String? className, Map<String, dynamic>? attributes, dynamic onClick(MouseEvent)?}) → Element
strong(dynamic children, {String? id, String? className, Map<String, dynamic>? attributes}) → Element
style(dynamic children, {String? id, String? className, Map<String, dynamic>? attributes}) → Element
template(dynamic children, {String? shadowrootmode, String? id, String? className, Map<String, dynamic>? attributes}) → Element
textarea(dynamic children, {String? name, String? rows, String? cols, String? id, String? className, Map<String, dynamic>? attributes}) → Element
title(dynamic children) → Element
u(dynamic children, {String? id, String? className, Map<String, dynamic>? attributes}) → Element
ul(dynamic children, {String? id, String? className, Map<String, dynamic>? attributes}) → Element

Typedefs

ComponentFactory = Function: Factory function type for creating component instances.
EventListener = void Function(Event event): Callback type for event listeners.
MutationCallback = void Function(List<MutationRecord> mutations, MutationObserver observer): Callback type for MutationObserver.
PageRequest = SparkRequest: Legacy alias for backward compatibility.
PositionCallback = void Function(GeolocationPosition position)
PositionErrorCallback = void Function(GeolocationPositionError error)

Exceptions / Errors

ApiError: Standard JSON Error Response DTO
SparkHttpException: Base HTTP Exception
SparkValidationException: Exception for Validation Failures

spark library

Libraries

Quick Start

Server-Side Rendering (SSR)

Classes

Enums

Constants

Properties

Functions

Typedefs

Exceptions / Errors

spark_framework package

spark library