269 lines
14 KiB
C++
269 lines
14 KiB
C++
//SPDX-License-Identifier: LGPL-3.0-only
|
|
//SPDX-FileCopyrightText: Copyright (C) 2026 Catcrafts®
|
|
|
|
// Browser DOM bindings — absorbed from Crafter.CppDOM. Only meaningful
|
|
// when the build defined CRAFTER_GRAPHICS_WINDOW_DOM (i.e. a wasm32-*
|
|
// target paired with additional/dom-env.js); on native platforms the
|
|
// partition still parses but every method links to nothing because the
|
|
// build excludes the impl. project.cpp's per-target module set is what
|
|
// makes the partition disappear from the native libs.
|
|
//
|
|
// Two-class hierarchy (simplified from CppDOM's three-class design):
|
|
// HtmlElementPtr — non-owning element reference. Tracks every handler
|
|
// it registered and clears them on destruction, so
|
|
// the silent-leak bug from CppDOM's bare-pointer
|
|
// flavour can't happen. Releases the JS handle on
|
|
// destruction.
|
|
// HtmlElement — `HtmlElementPtr` plus element ownership: removes
|
|
// the element from the DOM on destruction. The new
|
|
// `Create` factory builds a fresh element under a
|
|
// parent and returns one of these.
|
|
//
|
|
// Move-only throughout. The JS handle (`ptr`) of a moved-from instance
|
|
// is zeroed so the destructor of the moved-from carcass is a no-op.
|
|
|
|
export module Crafter.Graphics:Dom;
|
|
#ifdef CRAFTER_GRAPHICS_WINDOW_DOM
|
|
import std;
|
|
import :DomEvents;
|
|
|
|
export namespace Crafter::Dom {
|
|
|
|
class HtmlElementPtr {
|
|
public:
|
|
// Opaque JS-side element cookie. 0 = "no element"; the destructor
|
|
// treats 0 as "moved-from, nothing to release".
|
|
std::int32_t ptr;
|
|
|
|
// Look up an existing element by its DOM id.
|
|
HtmlElementPtr(const std::string_view id);
|
|
// Look up + replace innerHTML in one step (matches CppDOM).
|
|
HtmlElementPtr(const std::string_view id, const std::string_view html);
|
|
|
|
protected:
|
|
// Adopt a JS handle directly (used by HtmlElement::Create — the
|
|
// JS side has already minted the handle, no second lookup needed).
|
|
// Tagged-type ctor so the public id-based overloads stay
|
|
// unambiguous from the call site.
|
|
struct FromHandle { std::int32_t handle; };
|
|
explicit HtmlElementPtr(FromHandle h) noexcept : ptr(h.handle) {}
|
|
|
|
public:
|
|
|
|
// Move-only — copying would silently double-free the JS handle.
|
|
HtmlElementPtr(HtmlElementPtr&&) noexcept;
|
|
HtmlElementPtr& operator=(HtmlElementPtr&&) noexcept;
|
|
HtmlElementPtr(const HtmlElementPtr&) = delete;
|
|
HtmlElementPtr& operator=(const HtmlElementPtr&) = delete;
|
|
|
|
~HtmlElementPtr();
|
|
|
|
// DOM ops ─────────────────────────────────────────────────────
|
|
void SetInnerHTML(const std::string_view html);
|
|
void SetStyle(const std::string_view style);
|
|
|
|
// WARNING: SetProperty sets a *CSS* property (el.style.setProperty).
|
|
// It is NOT setAttribute — the name is historical. For href / src /
|
|
// disabled / aria-* / data-*, use SetAttribute below.
|
|
void SetProperty(const std::string_view property, const std::string_view value);
|
|
|
|
void AddClass(const std::string_view className);
|
|
void RemoveClass(const std::string_view className);
|
|
void ToggleClass(const std::string_view className);
|
|
bool HasClass(const std::string_view className);
|
|
std::string GetValue();
|
|
void SetValue(const std::string_view value);
|
|
|
|
// Attributes ──────────────────────────────────────────────────
|
|
//
|
|
// Real setAttribute/getAttribute access. Before these existed the
|
|
// only way to change an href or toggle `disabled` was to re-render
|
|
// the parent's innerHTML, which destroys every descendant and every
|
|
// listener attached to them just to change one string.
|
|
void SetAttribute(const std::string_view name, const std::string_view value);
|
|
void RemoveAttribute(const std::string_view name);
|
|
|
|
// nullopt = attribute absent. Distinct from an empty string, which
|
|
// means present-with-no-value (`alt=""`, `disabled=""`) — for
|
|
// boolean attributes presence alone is the signal.
|
|
std::optional<std::string> GetAttribute(const std::string_view name);
|
|
bool HasAttribute(const std::string_view name);
|
|
|
|
// Checkbox / radio state. GetValue cannot express this: `el.value`
|
|
// on a checkbox is "on" whether or not it is ticked.
|
|
bool GetChecked();
|
|
void SetChecked(bool checked);
|
|
|
|
// Move keyboard focus to / away from this element. AddFocusListener
|
|
// could already observe focus, but nothing could set it, which makes
|
|
// an accessible "jump to first invalid field" impossible.
|
|
void Focus();
|
|
void Blur();
|
|
|
|
// Listener API — each Add* returns an opaque id that can be
|
|
// passed to the matching Remove*. The destructor automatically
|
|
// removes every handler still registered, so manual removal is
|
|
// optional. Returns 0 only if registration failed at the JS
|
|
// boundary (the element was already collected). The 23 event
|
|
// types are 1:1 with CppDOM's surface.
|
|
//
|
|
// `preventDefault` (mouse / key / wheel kinds only — the others are
|
|
// not cancelable events, so the flag would be a silent no-op and is
|
|
// deliberately absent):
|
|
// Cancels the browser's default action. The JS bridge applies it
|
|
// BEFORE dispatching into wasm, so a trap in the callback cannot let
|
|
// the default action through anyway.
|
|
//
|
|
// This is what makes client-side routing over real, crawlable
|
|
// `<a href="/foo">` links possible: take the click, cancel the
|
|
// navigation, then Router::PushState. Without it the handler runs
|
|
// *and* the browser performs a full page load. It is also mandatory
|
|
// on dragover/drop — a drop target does not function at all unless
|
|
// the default is cancelled.
|
|
//
|
|
// Wheel additionally registers with `{ passive: false }` when set,
|
|
// or the browser drops the cancellation with a console warning.
|
|
//
|
|
// AddSubmitListener has no flag: its handler always preventDefaults,
|
|
// because a native form POST would navigate away from the wasm app.
|
|
std::int32_t AddClickListener(std::function<void(Crafter::Dom::MouseEvent)> callback,
|
|
bool preventDefault = false);
|
|
void RemoveClickListener(std::int32_t id);
|
|
|
|
std::int32_t AddMouseOverListener(std::function<void(Crafter::Dom::MouseEvent)> callback,
|
|
bool preventDefault = false);
|
|
void RemoveMouseOverListener(std::int32_t id);
|
|
|
|
std::int32_t AddMouseOutListener(std::function<void(Crafter::Dom::MouseEvent)> callback,
|
|
bool preventDefault = false);
|
|
void RemoveMouseOutListener(std::int32_t id);
|
|
|
|
std::int32_t AddMouseMoveListener(std::function<void(Crafter::Dom::MouseEvent)> callback,
|
|
bool preventDefault = false);
|
|
void RemoveMouseMoveListener(std::int32_t id);
|
|
|
|
std::int32_t AddMouseDownListener(std::function<void(Crafter::Dom::MouseEvent)> callback,
|
|
bool preventDefault = false);
|
|
void RemoveMouseDownListener(std::int32_t id);
|
|
|
|
std::int32_t AddMouseUpListener(std::function<void(Crafter::Dom::MouseEvent)> callback,
|
|
bool preventDefault = false);
|
|
void RemoveMouseUpListener(std::int32_t id);
|
|
|
|
std::int32_t AddFocusListener(std::function<void(Crafter::Dom::FocusEvent)> callback);
|
|
void RemoveFocusListener(std::int32_t id);
|
|
|
|
std::int32_t AddBlurListener(std::function<void(Crafter::Dom::FocusEvent)> callback);
|
|
void RemoveBlurListener(std::int32_t id);
|
|
|
|
std::int32_t AddKeyDownListener(std::function<void(Crafter::Dom::KeyboardEvent)> callback,
|
|
bool preventDefault = false);
|
|
void RemoveKeyDownListener(std::int32_t id);
|
|
|
|
std::int32_t AddKeyUpListener(std::function<void(Crafter::Dom::KeyboardEvent)> callback,
|
|
bool preventDefault = false);
|
|
void RemoveKeyUpListener(std::int32_t id);
|
|
|
|
std::int32_t AddKeyPressListener(std::function<void(Crafter::Dom::KeyboardEvent)> callback,
|
|
bool preventDefault = false);
|
|
void RemoveKeyPressListener(std::int32_t id);
|
|
|
|
std::int32_t AddChangeListener(std::function<void(Crafter::Dom::ChangeEvent)> callback);
|
|
void RemoveChangeListener(std::int32_t id);
|
|
|
|
std::int32_t AddSubmitListener(std::function<void()> callback);
|
|
void RemoveSubmitListener(std::int32_t id);
|
|
|
|
std::int32_t AddInputListener(std::function<void(Crafter::Dom::InputEvent)> callback);
|
|
void RemoveInputListener(std::int32_t id);
|
|
|
|
std::int32_t AddResizeListener(std::function<void(Crafter::Dom::ResizeEvent)> callback);
|
|
void RemoveResizeListener(std::int32_t id);
|
|
|
|
std::int32_t AddScrollListener(std::function<void(Crafter::Dom::ScrollEvent)> callback);
|
|
void RemoveScrollListener(std::int32_t id);
|
|
|
|
std::int32_t AddContextMenuListener(std::function<void(Crafter::Dom::MouseEvent)> callback,
|
|
bool preventDefault = false);
|
|
void RemoveContextMenuListener(std::int32_t id);
|
|
|
|
std::int32_t AddDragStartListener(std::function<void(Crafter::Dom::MouseEvent)> callback,
|
|
bool preventDefault = false);
|
|
void RemoveDragStartListener(std::int32_t id);
|
|
|
|
std::int32_t AddDragEndListener(std::function<void(Crafter::Dom::MouseEvent)> callback,
|
|
bool preventDefault = false);
|
|
void RemoveDragEndListener(std::int32_t id);
|
|
|
|
std::int32_t AddDropListener(std::function<void(Crafter::Dom::MouseEvent)> callback,
|
|
bool preventDefault = false);
|
|
void RemoveDropListener(std::int32_t id);
|
|
|
|
std::int32_t AddDragOverListener(std::function<void(Crafter::Dom::MouseEvent)> callback,
|
|
bool preventDefault = false);
|
|
void RemoveDragOverListener(std::int32_t id);
|
|
|
|
std::int32_t AddDragEnterListener(std::function<void(Crafter::Dom::MouseEvent)> callback,
|
|
bool preventDefault = false);
|
|
void RemoveDragEnterListener(std::int32_t id);
|
|
|
|
std::int32_t AddDragLeaveListener(std::function<void(Crafter::Dom::MouseEvent)> callback,
|
|
bool preventDefault = false);
|
|
void RemoveDragLeaveListener(std::int32_t id);
|
|
|
|
std::int32_t AddWheelListener(std::function<void(Crafter::Dom::WheelEvent)> callback,
|
|
bool preventDefault = false);
|
|
void RemoveWheelListener(std::int32_t id);
|
|
|
|
protected:
|
|
// Per-event-kind handler-id lists. Each `Add*Listener` push_backs
|
|
// the id it returns; `RemoveAllHandlers` walks every list and
|
|
// calls the matching JS Remove on each id. The lists are indexed
|
|
// by event kind so a single handler-id collision across kinds
|
|
// (allowed by the JS bridge — counters are per-event-kind)
|
|
// doesn't cause a wrong-kind remove.
|
|
std::vector<std::int32_t> handlerIds_[24];
|
|
|
|
// Shared cleanup used by the destructor AND by move-assignment.
|
|
// Removes every registered handler from both the C++ map and
|
|
// the JS side, then frees the JS handle. Leaves `ptr == 0` on
|
|
// return so a second call is a no-op.
|
|
void RemoveAllHandlersAndFree();
|
|
};
|
|
|
|
class HtmlElement : public HtmlElementPtr {
|
|
public:
|
|
// Adopt an existing element by id; the dtor will remove it from
|
|
// the DOM. Useful when the caller created the element in markup
|
|
// and wants C++ to own its lifetime from now on.
|
|
HtmlElement(const std::string_view id);
|
|
HtmlElement(const std::string_view id, const std::string_view html);
|
|
|
|
HtmlElement(HtmlElement&&) noexcept;
|
|
HtmlElement& operator=(HtmlElement&&) noexcept;
|
|
|
|
~HtmlElement();
|
|
|
|
// Create a new element and append it to `parent`. Optional `id`
|
|
// sets the new element's DOM id (use it when you want to look the
|
|
// element up from non-C++ code later); empty leaves the element
|
|
// unnamed. Returns an owning handle — the element is removed from
|
|
// the DOM when this `HtmlElement` is destroyed.
|
|
static HtmlElement Create(const HtmlElementPtr& parent,
|
|
std::string_view tagName,
|
|
std::string_view id = {});
|
|
|
|
// Convenience: create a top-level element under document.body.
|
|
static HtmlElement CreateInBody(std::string_view tagName,
|
|
std::string_view id = {});
|
|
|
|
private:
|
|
// Hidden ctor used by Create/CreateInBody — takes an already
|
|
// allocated JS handle via the base class FromHandle tag. Kept
|
|
// private so user code doesn't construct an HtmlElement from a
|
|
// raw handle by accident.
|
|
explicit HtmlElement(HtmlElementPtr::FromHandle h) noexcept
|
|
: HtmlElementPtr(h) {}
|
|
};
|
|
}
|
|
#endif // CRAFTER_GRAPHICS_WINDOW_DOM
|