Skip to main content

blitz_script/
application_document.rs

1use std::sync::Arc;
2use std::task::Context;
3
4use blitz_dom::{DocGuard, DocGuardMut, Document, DocumentConfig};
5use blitz_traits::events::UiEvent;
6
7/// A script-capable document backend constructible from HTML.
8pub trait ScriptDocumentBackend: Document + Sized {
9    fn from_html(html: Arc<str>, config: DocumentConfig) -> Result<Self, String>;
10    fn execute_scripts(&mut self) -> Result<(), String>;
11}
12
13/// Opt-in support for attaching an engine-native host to a script document.
14///
15/// Attachment is a separate, fallible step so callers can complete it after
16/// constructing the document and before calling `execute_scripts`. This
17/// extension does not change the requirements for [`ScriptDocumentBackend`].
18pub trait NativeHostDocumentBackend: ScriptDocumentBackend {
19    /// The engine-specific host owned by this backend after attachment.
20    type Host;
21
22    /// Attach `host` to this document before executing its scripts.
23    ///
24    /// Ownership of `host` transfers to the backend when this method is
25    /// called. On success, the backend keeps it for the attached document's
26    /// lifetime and is responsible for releasing it during teardown or
27    /// disposal. On failure, the backend must release any partially attached
28    /// resources and must not retain `host` as an attached host. This method
29    /// does not execute scripts.
30    fn attach_native_host(&mut self, host: Self::Host) -> Result<(), String>;
31}
32
33#[repr(transparent)]
34/// A statically dispatched document wrapper with the backend's layout and ownership.
35pub struct ApplicationDocument<D: ScriptDocumentBackend>(D);
36
37impl<D: ScriptDocumentBackend> ApplicationDocument<D> {
38    pub fn from_html(html: Arc<str>, config: DocumentConfig) -> Result<Self, String> {
39        D::from_html(html, config).map(Self)
40    }
41
42    pub fn backend(&self) -> &D {
43        &self.0
44    }
45
46    pub fn backend_mut(&mut self) -> &mut D {
47        &mut self.0
48    }
49
50    pub fn into_backend(self) -> D {
51        self.0
52    }
53
54    pub fn execute_scripts(&mut self) -> Result<(), String> {
55        self.0.execute_scripts()
56    }
57}
58
59impl<D: NativeHostDocumentBackend> ApplicationDocument<D> {
60    /// Attaches the backend's native host before script execution.
61    ///
62    /// Ownership and failure cleanup follow [`NativeHostDocumentBackend`].
63    pub fn attach_native_host(&mut self, host: D::Host) -> Result<(), String> {
64        self.0.attach_native_host(host)
65    }
66}
67
68impl<D: ScriptDocumentBackend> Document for ApplicationDocument<D> {
69    fn inner(&self) -> DocGuard<'_> {
70        self.0.inner()
71    }
72
73    fn inner_mut(&mut self) -> DocGuardMut<'_> {
74        self.0.inner_mut()
75    }
76
77    fn handle_ui_event(&mut self, event: UiEvent) {
78        self.0.handle_ui_event(event)
79    }
80
81    fn poll(&mut self, context: Option<Context>) -> bool {
82        self.0.poll(context)
83    }
84
85    fn poll_for_settle(&mut self, context: Option<Context>, timers: bool) -> bool {
86        self.0.poll_for_settle(context, timers)
87    }
88
89    fn prepare_teardown(&mut self) {
90        self.0.prepare_teardown();
91    }
92
93    fn dispose(self: Box<Self>) -> Arc<blitz_dom::release::Teardown> {
94        Box::new(self.0).dispose()
95    }
96
97    fn set_page_visible(&mut self, visible: bool) {
98        self.0.set_page_visible(visible);
99    }
100
101    fn freeze(&mut self) {
102        self.0.freeze();
103    }
104
105    fn finish_restore(&mut self) {
106        self.0.finish_restore();
107    }
108
109    fn resume(&mut self) {
110        self.0.resume();
111    }
112}