devela/lang/js/
web_api.rs

Help
1// devela::lang:js::web_api
2//
3//! Implements Web API methods for [`Js`].
4//
5// In sync with `./web_api.js`.
6//
7// TOC
8// - core APis
9//   - console
10//   - events
11//   - history
12//   - permissions
13//
14// - extended APis
15//   - media & graphics
16//     - canvas
17//   - system & hardware
18//   - performance & optimization
19//     - time
20//   - advanced & experimental
21//
22// LINKS
23// - https://developer.mozilla.org/en-US/docs/Web/API
24// - https://www.w3schools.com/jsref/api_canvas.asp
25// - https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API/Tutorial/Drawing_text
26//
27// NOTES
28// - https://doc.rust-lang.org/reference/items/external-blocks.html
29// - strings: https://alexcrichton.github.io/wasm-bindgen/reference/types/str.html
30//
31// ✅ Use safe fn when:
32//   - The function does not perform pointer dereferencing or other memory-unsafe operations.
33//   - It always behaves safely (e.g., a function that just draws to the Canvas API).
34//   - You want to avoid unnecessary unsafe blocks in Rust when calling it.
35// ❌ Avoid safe fn if:
36//   - The function can mutate raw memory (e.g., passing buffers, pointers).
37//   - It can throw exceptions that Rust cannot catch.
38//   - It performs DOM manipulations that might trigger undefined behavior.
39//
40// TODO
41// - doc-link using const (fn?) using a url-base for links
42// - get the text measure (how to receive it)
43//   - https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/measureText
44//
45// WIP: https://chatgpt.com/c/67c41538-9248-8007-8762-00ca739fade8
46//
47// # API Hierarchy
48// ## 1. Core Web APIs (Essential & Universal)
49// - DOM & Events – Document interaction (`document`, `window`, `EventTarget`)
50// - CSSOM & UI – Styling & animations (`getComputedStyle`, `requestAnimationFrame`)
51// - History & Navigation – Page state control (`history`, `location`)
52// - Storage & Persistence – Data management (`localStorage`, `IndexedDB`, `Cache API`, `File System API`)
53// - [x] Console & Debugging – Logging & diagnostics (`console.log`, `console.error`, `console.group`)
54// - Permissions & Credentials – User consent & authentication (`Permissions API`, `Credential Management`)
55// - Security & Policies – Web protection (`CSP`, `Subresource Integrity`)
56// - Networking & Communication – Data exchange & background tasks:
57//   - HTTP Requests – Fetching data (`Fetch API`, `XMLHttpRequest`)
58//   - WebSockets & SSE – Real-time communication (`WebSocket`, `EventSource`)
59//   - Service Workers & Background Sync – Offline & background tasks (`ServiceWorker`, `Push API`)
60//
61// ## 2. Extended Web APIs (Specialized & System-Oriented)
62// - Media & Graphics – Visuals, audio, and real-time streaming:
63//   - [ ] Canvas & WebGL – 2D/3D rendering (`Canvas API`, `WebGL`, `WebGPU`)
64//   - SVG & Vector Graphics – Scalable graphics (`SVG API`)
65//   - Audio & Video – Media processing (`Web Audio`, `MediaStream`, `MSE`)
66//   - WebRTC & Streaming – Real-time video & communication (`getUserMedia`, `RTCPeerConnection`)
67//
68// - System & Hardware – Device access & integrations:
69//   - Sensors & Motion – (`Accelerometer`, `Gyroscope`)
70//   - Geolocation & Orientation – (`Geolocation API`)
71//   - External Device APIs – (`Web Bluetooth`, `WebUSB`, `Web Serial`, `Web HID`)
72//   - Battery & Power Management – (`Battery API`, `Wake Lock`)
73//
74// - Performance & Optimization – Resource efficiency:
75//   - Performance Monitoring – Timing & metrics (`performance.now`, `Resource Timing`)
76//   - Memory & CPU Management – Efficiency tools (`SharedArrayBuffer`, `Atomics`)
77//
78// - Advanced & Experimental – Low-level, parallelism, and niche APIs:
79//   - WebAssembly (WASM) – Low-level execution (`WebAssembly.instantiateStreaming`)
80//   - Workers & Multithreading – Parallel processing (`Web Workers`, `SharedArrayBuffer`)
81//   - Scheduler & Background Execution – Task prioritization (`Scheduler API`)
82//   - Gamepad & Input Devices – Game controls & pointer locking (`Gamepad API`, `Pointer Lock`)
83
84use devela::{js_reexport, transmute, Js, JsEvent, JsPermission, JsPermissionState};
85
86// helper for Web API doc links
87#[rustfmt::skip]
88macro_rules! web_api {
89    ($path_with_end_bar:literal, $method:literal) => { concat!["([", $method,
90        "](https://developer.mozilla.org/en-US/docs/Web/API/",
91        $path_with_end_bar, $method, "))" ]
92    };
93    (canvas $method:literal) => { concat!["([", $method,
94        "](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/",
95        $method, "))" ]
96    };
97    (console $method:literal) => { concat!["([", $method,
98        "](https://developer.mozilla.org/en-US/docs/Web/API/console/",
99        $method, "_static))" ] };
100}
101
102/* core APIs */
103
104/// # Web API console
105///
106/// - <https://developer.mozilla.org/en-US/docs/Web/API/console>
107#[rustfmt::skip]
108impl Js {
109    #[doc = web_api!(console "debug")]
110    /// Outputs a message to the console with the debug log level.
111    pub fn console_debug(text: &str) { unsafe { console_debug(text.as_ptr(), text.len()); } }
112    #[doc = web_api!(console "error")]
113    /// Outputs a message to the console with the error log level.
114    pub fn console_error(text: &str) { unsafe { console_error(text.as_ptr(), text.len()); } }
115    #[doc = web_api!(console "info")]
116    /// Outputs a message to the console with the info log level.
117    pub fn console_info(text: &str) { unsafe { console_info(text.as_ptr(), text.len()); } }
118    #[doc = web_api!(console "log")]
119    /// Outputs a message to the console.
120    pub fn console_log(text: &str) { unsafe { console_log(text.as_ptr(), text.len()); } }
121    #[doc = web_api!(console "trace")]
122    /// Outputs a stack trace.
123    pub fn console_trace() { unsafe { console_trace(); } }
124    #[doc = web_api!(console "warn")]
125    /// Outputs a message to the console with the warning log level.
126    pub fn console_warn(text: &str) { unsafe { console_warn(text.as_ptr(), text.len()); } }
127    //
128    #[doc = web_api!(console "group")]
129    /// Creates a new inline group, indenting all following output by another level.
130    pub fn console_group(text: &str) { unsafe { console_group(text.as_ptr(), text.len()); } }
131    #[doc = web_api!(console "groupEnd")]
132    /// Exits the current inline group.
133    pub fn console_group_end() { unsafe { console_group_end(); } }
134}
135js_reexport! {
136    [ module: "api_console" ]
137    unsafe fn "console_debug" console_debug(str_ptr: *const u8, str_len: usize);
138    unsafe fn "console_error" console_error(str_ptr: *const u8, str_len: usize);
139    unsafe fn "console_info" console_info(str_ptr: *const u8, str_len: usize);
140    unsafe fn "console_log" console_log(str_ptr: *const u8, str_len: usize);
141    unsafe fn "console_trace" console_trace();
142    unsafe fn "console_warn" console_warn(str_ptr: *const u8, str_len: usize);
143    //
144    unsafe fn "console_group" console_group(str_ptr: *const u8, str_len: usize);
145    unsafe fn "console_groupEnd" console_group_end();
146}
147
148/// # Web API Events
149///
150/// Provides event handling for interactivity.
151/// Uses Rust function pointers to manage callbacks.
152///
153/// - <https://developer.mozilla.org/en-US/docs/Web/API/Event>
154/// - <https://developer.mozilla.org/en-US/docs/Web/API/EventTarget>
155/// - <https://developer.mozilla.org/en-US/docs/Web/API/EventListener>
156#[rustfmt::skip]
157impl Js {
158    #[doc = web_api!("Event", "addEventListener")]
159    /// Attaches a Rust function `event` listener from an `element`.
160    pub fn event_add_listener(element: &str, event: JsEvent, rust_fn: extern "C" fn()) {
161        unsafe {
162            event_add_listener(element.as_ptr(), element.len(),
163            event.as_str().as_ptr(), event.as_str().len(), rust_fn as usize);
164        }
165    }
166    #[doc = web_api!("Event", "removeEventListener")]
167    /// Removes a a Rust function `event` listener from an `element`.
168    pub fn event_remove_listener(element: &str, event: JsEvent, rust_fn: extern "C" fn()) {
169        unsafe {
170            event_remove_listener(element.as_ptr(), element.len(),
171            event.as_str().as_ptr(), event.as_str().len(), rust_fn as usize);
172        }
173    }
174    #[doc = web_api!("Event", "addEventListenerJs")]
175    /// Attaches a JavaScript function `event` linstener to an `element`.
176    pub fn event_add_listener_js(element: &str, event: JsEvent, js_fn_name: &str) {
177        unsafe {
178            event_add_listener_js(element.as_ptr(), element.len(),
179            event.as_str().as_ptr(), event.as_str().len(), js_fn_name.as_ptr(), js_fn_name.len());
180        }
181    }
182    #[doc = web_api!("Event", "removeEventListenerJs")]
183    /// Removes a JavaScript function `event` listener from an `element`.
184    pub fn event_remove_listener_js(element: &str, event: JsEvent, js_fn_name: &str) {
185        unsafe {
186            event_remove_listener_js(
187                element.as_ptr(), element.len(),
188                event.as_str().as_ptr(), event.as_str().len(),
189                js_fn_name.as_ptr(), js_fn_name.len()
190            );
191        }
192    }
193
194    /// Callback dispatcher for WebAssembly events.
195    ///
196    /// - This function is used by JavaScript to invoke a Rust function pointer.
197    /// - It allows Rust event listeners to execute when triggered by JS.
198    /// - The `callback_ptr` is a function pointer cast from JS,
199    ///   which is then transmuted into a callable Rust function.
200    ///
201    /// # Safety
202    /// `callback_ptr` must be a valid function pointer.
203    ///
204    /// # Example
205    /// ```ignore
206    /// #[unsafe(no_mangle)]
207    /// pub extern "C" fn my_callback() {
208    ///     Js::console_log("Button clicked!");
209    /// }
210    /// Js::event_add_listener("#my_button", JsEvent::Click, my_callback);
211    /// ```
212    #[unsafe(no_mangle)]
213    pub unsafe extern "C" fn wasm_callback(callback_ptr: usize) {
214        let callback = callback_ptr as *const ();
215        let callback: extern "C" fn() = unsafe { transmute(callback) };
216        callback();
217    }
218}
219js_reexport! {
220    [ module: "api_events" ]
221    unsafe fn "event_addListener" event_add_listener(element_ptr: *const u8,
222        element_len: usize, event_ptr: *const u8, event_len: usize, callback_ptr: usize);
223    unsafe fn "event_removeListener" event_remove_listener(element_ptr: *const u8,
224        element_len: usize, event_ptr: *const u8, event_len: usize, callback_ptr: usize);
225    unsafe fn "event_addListenerJs" event_add_listener_js(
226        element_ptr: *const u8, element_len: usize,
227        event_ptr: *const u8, event_len: usize, js_fn_ptr: *const u8, js_fn_len: usize
228    );
229    unsafe fn "event_removeListenerJs" event_remove_listener_js(
230        element_ptr: *const u8, element_len: usize,
231        event_ptr: *const u8, event_len: usize, js_fn_ptr: *const u8, js_fn_len: usize
232    );
233}
234
235/// # Web API history & navigation
236///
237/// - <https://developer.mozilla.org/en-US/docs/Web/API/History>
238/// - <https://developer.mozilla.org/en-US/docs/Web/API/Location>
239#[rustfmt::skip]
240impl Js {
241    #[doc = web_api!("History", "back")]
242    /// Moves the browser back one step in the session history.
243    pub fn history_back() { unsafe { history_back(); } }
244
245    #[doc = web_api!("History", "forward")]
246    /// Moves the browser forward one step in the session history.
247    pub fn history_forward() { unsafe { history_forward(); } }
248
249    #[doc = web_api!("History", "go")]
250    /// Moves the browser to a specific point in the session history.
251    /// Use negative values to go back, positive to go forward.
252    pub fn history_go(delta: i32) { unsafe { history_go(delta); } }
253
254    #[doc = web_api!("History", "pushState")]
255    /// Adds an entry to the session history stack.
256    pub fn history_push_state(state: &str, title: &str, url: &str) {
257        unsafe { history_push_state(state.as_ptr(), state.len(), title.as_ptr(), title.len(),
258            url.as_ptr(), url.len()); }
259    }
260
261    #[doc = web_api!("History", "replaceState")]
262    /// Modifies the current history entry without creating a new one.
263    pub fn history_replace_state(state: &str, title: &str, url: &str) {
264        unsafe { history_replace_state(state.as_ptr(), state.len(), title.as_ptr(), title.len(),
265            url.as_ptr(), url.len()); }
266    }
267
268    #[doc = web_api!("Location", "reload")]
269    /// Reloads the current document.
270    pub fn location_reload() { unsafe { location_reload(); } }
271
272    #[doc = web_api!("Location", "assign")]
273    /// Loads the specified URL.
274    pub fn location_assign(url: &str) { unsafe { location_assign(url.as_ptr(), url.len()); } }
275
276    #[doc = web_api!("Location", "replace")]
277    /// Replaces the current document with the specified URL without creating a new entry in the history.
278    pub fn location_replace(url: &str) { unsafe { location_replace(url.as_ptr(), url.len()); } }
279}
280js_reexport! {
281    [ module: "api_history_navigation" ]
282    unsafe fn "history_back" history_back();
283    unsafe fn "history_forward" history_forward();
284    unsafe fn "history_go" history_go(delta: i32);
285    unsafe fn "history_pushState" history_push_state(state_ptr: *const u8, state_len: usize,
286        title_ptr: *const u8, title_len: usize, url_ptr: *const u8, url_len: usize);
287    unsafe fn "history_replaceState" history_replace_state(state_ptr: *const u8, state_len: usize,
288        title_ptr: *const u8, title_len: usize, url_ptr: *const u8, url_len: usize);
289    //
290    unsafe fn "location_reload" location_reload();
291    unsafe fn "location_assign" location_assign(url_ptr: *const u8, url_len: usize);
292    unsafe fn "location_replace" location_replace(url_ptr: *const u8, url_len: usize);
293}
294
295/// # Web API permissions
296///
297/// - <https://developer.mozilla.org/en-US/docs/Web/API/Permissions_API>
298#[rustfmt::skip]
299impl Js {
300    #[doc = web_api!("Permissions", "query")]
301    /// Queries the status of a given permission.
302    ///
303    /// Returns `Granted`, `Denied`, `Prompt`, or `Unknown` if unsupported.
304    pub fn permissions_query(permission: JsPermission) -> JsPermissionState {
305        unsafe { permissions_query(permission.as_str().as_ptr(), permission.as_str().len()) }
306        .into()
307    }
308
309}
310js_reexport! {
311    [ module: "api_permissions" ]
312    unsafe fn "permissions_query" permissions_query(name_ptr: *const u8, name_len: usize) -> i32;
313}
314
315/* extended APIs */
316
317/// # Web API canvas
318///
319/// - <https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D>
320/// - <https://html.spec.whatwg.org/multipage/canvas.html>
321#[rustfmt::skip]
322impl Js {
323    /* custom */
324    /// Sets the active canvas by ID.
325    pub fn set_canvas(id: &str) { unsafe { set_canvas(id.as_ptr(), id.len()); } }
326
327    /* colors and styles */
328
329    #[doc = web_api!(canvas "fillStyle")]
330    /// Sets the color or style for filling shapes.
331    pub fn fill_style(r: u8, g: u8, b: u8) { fill_style(r, g, b); }
332
333    #[doc = web_api!(canvas "strokeStyle")]
334    /// Sets the color or style for lines.
335    pub fn stroke_style(r: u8, g: u8, b: u8) { stroke_style(r, g, b); }
336
337    /* draw */
338
339    #[doc = web_api!(canvas "fillRect")]
340    /// Draws a filled rectangle.
341    pub fn fill_rect(x: f64, y: f64, w: f64, h: f64) { fill_rect(x, y, w, h); }
342
343    ///
344    pub fn draw_line(x1: f64, y1: f64, x2: f64, y2: f64) { draw_line(x1, y1, x2, y2); }
345
346    ///
347    pub fn draw_circle(x: f64, y: f64, radius: f64) { draw_circle(x, y, radius); }
348
349    /* text */
350
351    #[doc = web_api!(canvas "fillText")]
352    /// Draws a filled text string at the specified coordinates
353    pub fn fill_text(text: &str, x: f64, y: f64) {
354        unsafe { fill_text(text.as_ptr(), text.len(), x, y); }
355    }
356}
357js_reexport! {
358    [ module: "api_canvas" ]
359    /* custom */
360    unsafe fn set_canvas(str_ptr: *const u8, str_len: usize);
361
362    /* draw */
363    safe fn "fillRect" fill_rect(x: f64, y: f64, w: f64, h: f64);
364    safe fn "fillStyle" fill_style(r: u8, g: u8, b: u8);
365    safe fn "strokeStyle" stroke_style(r: u8, g: u8, b: u8);
366    safe fn draw_line(x1: f64, y1: f64, x2: f64, y2: f64);
367    safe fn draw_circle(x: f64, y: f64, radius: f64);
368
369    /* text */
370    unsafe fn "fillText" fill_text(str_ptr: *const u8, str_len: usize, x: f64, y: f64);
371}
372
373/// # Web API time
374#[rustfmt::skip]
375impl Js {
376    ///
377    pub fn get_time() -> f64 { get_time() }
378}
379js_reexport! {
380    [ module: "api_timing" ]
381    safe fn get_time() -> f64;
382}
383
384/*
385
386 The `CanvasRenderingContext2D` interface provides a comprehensive set of methods for drawing and
387 manipulating graphics on a `<canvas>` element. Here's a concise list of its primary methods:
388
389 ### **Drawing Rectangles**
390 - **`fillRect(x, y, width, height)`**: Draws a filled rectangle.
391 - **`strokeRect(x, y, width, height)`**: Draws a rectangular outline.
392 - **`clearRect(x, y, width, height)`**: Clears the specified rectangular area, making it fully transparent.
393
394 ### **Path Drawing**
395 - **`beginPath()`**: Starts a new path.
396 - **`moveTo(x, y)`**: Moves the pen to the specified coordinates.
397 - **`lineTo(x, y)`**: Draws a line from the current position to the specified coordinates.
398 - **`closePath()`**: Closes the current path by drawing a straight line back to the start.
399 - **`stroke()`**: Strokes (outlines) the current path.
400 - **`fill()`**: Fills the current path.
401
402 ### **Drawing Text**
403 - **`fillText(text, x, y [, maxWidth])`**: Draws filled text at the specified position.
404 - **`strokeText(text, x, y [, maxWidth])`**: Draws text outline at the specified position.
405 - **`measureText(text)`**: Returns metrics for the specified text.
406
407 ### **Line Styles**
408 - **`lineWidth`**: Sets the width of lines.
409 - **`lineCap`**: Sets the style of line endpoints (`'butt'`, `'round'`, `'square'`).
410 - **`lineJoin`**: Sets the style of line joins (`'bevel'`, `'round'`, `'miter'`).
411 - **`miterLimit`**: Sets the miter limit ratio.
412 - **`setLineDash(segments)`**: Sets the pattern of dashes and gaps used to stroke paths.
413 - **`getLineDash()`**: Returns the current line dash pattern.
414
415 ### **Colors and Styles**
416 - **`fillStyle`**: Sets the color or style for filling shapes.
417 - **`strokeStyle`**: Sets the color or style for lines.
418 - **`createLinearGradient(x0, y0, x1, y1)`**: Creates a linear gradient.
419 - **`createRadialGradient(x0, y0, r0, x1, y1, r1)`**: Creates a radial gradient.
420 - **`createPattern(image, repetition)`**: Creates a pattern using the specified image.
421
422 ### **Image Drawing**
423 - **`drawImage(image, dx, dy)`**: Draws an image at the specified position.
424 - **`drawImage(image, dx, dy, dWidth, dHeight)`**: Draws an image scaled to the specified dimensions.
425 - **`drawImage(image, sx, sy, sWidth, sHeight, dx, dy, dWidth, dHeight)`**: Draws a portion of an image scaled to the specified dimensions.
426
427 ### **Transformations**
428 - **`scale(x, y)`**: Scales the drawing horizontally and vertically.
429 - **`rotate(angle)`**: Rotates the drawing by the specified angle (in radians).
430 - **`translate(x, y)`**: Moves the canvas and its origin on the grid.
431 - **`transform(a, b, c, d, e, f)`**: Multiplies the current transformation matrix with the specified matrix.
432 - **`setTransform(a, b, c, d, e, f)`**: Resets the transformation matrix and then applies the specified matrix.
433 - **`resetTransform()`**: Resets the transformation matrix to the identity matrix.
434
435 ### **Compositing and Effects**
436 - **`globalAlpha`**: Sets the opacity level for drawing operations.
437 - **`globalCompositeOperation`**: Sets how new drawings are combined with existing canvas content.
438 - **`shadowColor`**: Sets the color of shadows.
439 - **`shadowBlur`**: Sets the level of blur for shadows.
440 - **`shadowOffsetX`**: Sets the horizontal distance of the shadow.
441 - **`shadowOffsetY`**: Sets the vertical distance of the shadow.
442
443 ### **Pixel Manipulation**
444 - **`createImageData(width, height)`**: Creates a new, blank ImageData object.
445 - **`getImageData(sx, sy, sw, sh)`**: Returns an ImageData object representing the pixel data for the specified rectangle.
446 - **`putImageData(imageData, dx, dy)`**: Puts the image data onto the canvas at the specified position.
447
448 ### **Canvas State**
449 - **`save()`**: Saves the current drawing state.
450 - **`restore()`**: Restores the most recently saved drawing state.
451
452 For a comprehensive overview and detailed descriptions of these methods, refer to the [MDN Web Docs on CanvasRenderingContext2D](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D).
453
454*/
devela/lang/js/web_api.rs

devela/lang/js/
web_api.rs
