Humal 1.4.0

Added

1. Browser runtime: a web namespace for accessing browser functionality from Humal.
2. DOM helpers: web.element(), web.text(), web.value(), and web.button() for working with page elements.
3. Event handling: web.on(), web.off(), and web.button().onClick() for registering and removing event listeners.
4. Browser API access: access to window, document, navigator, Fetch, Web Crypto, and other available browser APIs.
5. Storage support: convenient lowercase aliases for Local Storage, Session Storage, and IndexedDB.
6. Asynchronous browser code: browser programs can use Humal's async fn and await syntax.
7. Parcel transformer: a custom transformer that compiles .hum files and connects browser applications to the Humal Web runtime.
8. Browser environment configuration: the env option in humal.config.json allows projects to select browser-specific tooling behavior.
9. Browser input compatibility: browser handling for programs that use Humal's input syntax.

Improvements

1. Runtime validation: browser-only functionality reports a clear error when used outside a browser.
2. Element handling: DOM helpers accept CSS selectors and supported existing element objects.
3. Error reporting: missing elements and invalid event callbacks produce explicit errors.
4. Browser method binding: callable browser properties are bound to the appropriate context when needed.
5. Constructor handling: browser constructors are distinguished from regular methods.
6. Cleaner UI code: common DOM operations can be expressed with Humal helpers.
7. Tooling integration: browser projects can use browser-specific type declarations and lint configuration when the project tooling is configured for env: "browser".

Getting started

1. Install Humal

npm install -g @qvelop444/humal

2. Create a browser project

Run:

humal init myapp --env browser
cd myapp
npm install

Humal initializes the browser project, including the configuration, HTML entry point, Parcel configuration, and npm scripts.

The generated project structure is:

myapp/
├── index.html
├── .parcelrc
├── humal.config.json
├── package.json
├── .gitignore
└── src/
    └── main.hum

3. Browser environment configuration

Humal creates humal.config.json with the browser environment enabled:

{
  "entry": "src/main.hum",
  "sourceDir": "src",
  "module": "esm",
  "env": "browser",
  "webEntry": "index.html"
}

The env option enables browser-specific tooling behavior. The webEntry option identifies the HTML entry point used by Parcel.

4. Write your first browser application

The generated index.html references src/main.hum. Replace the contents of src/main.hum with:

web.document.title = "Humal Web"

web.text("#status", "Ready")

fn saveName()
    let name = web.value("#name")
    web.localstorage.setItem("name", name)
    web.text("#status", "Saved: " + name)

web.value("#name", web.localstorage.getItem("name") ?? "")

web.button("#save").onClick(saveName)

This example demonstrates DOM manipulation, event handling, and persistent browser storage using Humal syntax.

5. Run the development server

Start Parcel through Humal:

npm run dev:web

Open the local URL printed by Parcel in your terminal, usually http://localhost:1234/.

Create a production build with:

npm run build:web

The production build is written to Parcel's output directory, normally dist/.

Manual Parcel configuration

This section is intended for existing projects that want to add Humal Web without using the browser project template.

Install the required packages:

npm install --save-dev parcel @qvelop444/humal

Create a .parcelrc file in the project root:

{
  "extends": "@parcel/config-default",
  "transformers": {
    "*.hum": [
      "./node_modules/@qvelop444/humal/src/parcel.js"
    ]
  }
}

The relative path points to Humal's Parcel transformer inside the installed npm package. Parcel uses this transformer to compile .hum files into JavaScript.

Configure the npm scripts in package.json:

{
  "scripts": {
    "dev:web": "humal dev:web",
    "build:web": "humal build:web"
  }
}

Ensure that humal.config.json specifies "env": "browser" and that index.html references the correct .hum entry point.

The web API

DOM helpers

API	Description
web.document	Access the browser document
web.window	Access the browser window
web.element(target)	Resolve a selector or element
web.text(target, value)	Set an element's text
web.value(target)	Read an element's value
web.value(target, value)	Set an element's value
web.button(target)	Access button helper methods
web.on(target, event, callback, options)	Register an event listener
web.off(target, event, callback, options)	Remove an event listener
web.ready(callback)	Run a callback when the DOM is ready
web.alert(message)	Show a browser alert

The button helper supports .onClick(), .text(), and .disable().

Browser API aliases

Humal Web provides lowercase aliases for selected browser APIs:

web.localstorage
web.sessionstorage
web.indexeddb
web.urlsearchparams
web.abortcontroller
web.intersectionobserver
web.mutationobserver
web.resizeobserver
web.websocket
web.sharedworker
web.broadcastchannel
web.textencoder
web.textdecoder
web.formdata
web.filereader

These aliases expose the corresponding browser objects through the web namespace. Their availability depends on browser support and the execution environment.

Network requests and asynchronous code

async fn loadData()
    let response = await web.fetch("/api/data")

    if !response.ok
        throw new Error("Request failed")

    let data = await response.json()
    web.text("#status", JSON.stringify(data))

web.button("#load").onClick(loadData)

Network errors and HTTP error responses should be handled separately. For example, fetch() does not normally reject just because a server responds with status 404 or 500; check response.ok or response.status.

Install the VS Code extension

Download the .vsix file, then in VS Code go to the Extensions view, click the three dots, select Install from VSIX..., and choose the downloaded .vsix file.