ElementaryUI Documentation

The ElementaryUI Browser Runtime is a package that provides the JavaScript glue code necessary to run ElementaryUI WebAssembly applications in the browser. It consists of two main components:

1. JavaScriptKit Runtime: A Swift-to-JavaScript interop layer (vendored from JavaScriptKit).
2. WASI Bootstrap: A minimal WASI setup for browser environments using @bjorn3/browser_wasi_shim.

In ElementaryUI, you define your UI components using the @View macro. A view is a struct that implements a body property returning some View. You can use built-in HTML-like DSL elements (such as div, p, button) to construct your interface. Reactivity is handled via the @State property wrapper.

@View
struct Counter {
    @State var count = 0
    
    var body: some View {
        div {
            p { "Count: \(count)" }
            button { "Increment" }
                .onClick { count += 1 }
        }
    }
}

ElementaryUI provides several methods to respond to changes in a view's lifecycle:

• onAppear(_:): Executes a closure when the view appears in the UI.
• onDisappear(_:): Executes a closure when the view is removed from the UI.
• onChange(of:initial:_:): Executes a closure when a specific value changes. The initial parameter allows you to specify if the closure should run immediately upon attachment.

Animations can be triggered globally or attached to specific views:

• withAnimation(_:_:): Wraps a state change to animate all resulting UI transitions.
• animation(_:value:): Attaches a specific animation style to a view, which triggers whenever the specified value changes.
• Animatable: A protocol used to define custom interpolation logic for complex animations.

To run the Swiftle example project on your local machine, you must first install the dependencies using pnpm. After installation, you can choose between a development mode with hot reloading or a production-style preview build.

Prerequisites

• pnpm installed on your system.
• Refer to https://elementary.codes for general setup guides if needed.

# Install dependencies
pnpm preinstall && pnpm install

# Option 1: Development mode (build + watch)
pnpm dev

# Option 2: Production preview (build and serve)
pnpm build
pnpm preview

To set up the Basic Example project, use pnpm to run the preinstall and install commands. This ensures all dependencies are correctly prepared.

pnpm preinstall && pnpm install

To generate a production-ready embedded release build and preview it locally, run the build command followed by the preview command.

pnpm build
pnpm preview

Use the runApplication function from elementary-ui-browser-runtime to provide the necessary JavaScript glue code, JavaScriptKit interop, and WASI bootstrap required to execute ElementaryUI WebAssembly applications in a browser environment.

Important Note: If you are not using an ElementaryUI Vite setup, you should use the JavaScriptKit swift package js plugin instead of this runtime.

import { runApplication } from "elementary-ui-browser-runtime";

await runApplication(async (imports) => {
  const { instance } = await WebAssembly.instantiateStreaming(
    fetch("./App.wasm"),
    imports
  );
  return instance;
});

The bridge-js.config.json file controls how the JavaScript bridge is exposed within the browser environment. The primary configuration option is exposeToGlobal, which determines if the bridge is attached to the global scope (e.g., window).

{
  "exposeToGlobal": false
}

Use runApplication() to bootstrap a JavaScriptKit SwiftRuntime and a WASI shim to execute an ElementaryUI Swift application in a web environment.

To use this function, you must provide an initializer function. This function receives an importsObject containing the necessary WebAssembly imports (javascript_kit and wasi_snapshot_preview1) and must return a Promise that resolves to a WebAssembly.Instance.

import { runApplication } from "@elementary-ui/browser-runtime";

await runApplication(async (imports) => {
  // 1. Fetch your compiled Swift WASM module
  const response = await fetch("path/to/your/app.wasm");
  const bytes = await response.arrayBuffer();

  // 2. Instantiate the WASM module using the provided imports
  const { instance } = await WebAssembly.instantiate(bytes, imports);

  return instance;
});