Merge pull request #2 from feijihe/main

feat: i18n

Author: kasonyang

astro.config.mjs

@@ -0,0 +1,49 @@
+---
+title: Animation
+---
+
+## Introduction
+
+Deft supports animation, similar to CSS animations.
+
+## Define Animation
+
+Unlike the @keyframes in Web, in Deft, you need to define the animation by `animation_create`, currently only the `transform` property is supported.
+
+**Example**
+
+```javascript
+// Create a rotate animation, the animation name is my-rotate
+animation_create("my-rotate", {
+    // Start frame
+    "0": {
+        transform: 'rotate(0deg)'
+    },
+    // end frame
+    "1": {
+        transform: 'rotate(360deg)'
+    }
+});
+```
+
+_Note: The animation name should be unique_
+
+## Apply Animation
+
+Like Web CSS animations, Deft applies animations through css, supporting the following CSS properties:
+
+**animation-name** Animation name, defined by `animation_create` function
+
+**animation-duration** Animation duration, in milliseconds
+
+**animation-iteration-count** Animation loop count, default is 1
+
+
+**Example**
+
+```jsx
+<Button style={{
+    animationName: 'my-rotate',
+    animationDuration: 2000,
+}}>MyButton</Button>
+```

src/content/docs/en/advanced/animation.md

@@ -0,0 +1,141 @@
+---
+title: Custom Components (Rust)
+---
+
+import { Image } from 'astro:assets';
+import initImg from "../../../../assets/hello-element/init.png";
+import renderImg from "../../../../assets/hello-element/render.png";
+
+
+Deft includes some commonly used basic components and allows you to create custom components to meet complex requirements.
+
+_Note: Custom components here refer to basic components like Label and Button. If you need to create custom React/Vue/Solid components, you should refer to the custom component tutorials for the respective frameworks; this tutorial does not apply._
+
+### Creating a Custom Component
+
+Creating a custom component is very simple—you only need to implement the `ElementBackend` trait.
+
+The `ElementBackend` trait has several methods, but only the `create` method is mandatory. Other methods can be implemented optionally based on requirements.
+
+First, we need to create a struct to represent our custom component. Here, we use `HelloBackend` as an example.
+
+```rust
+pub struct HelloBackend {
+    element_weak: ElementWeak,
+}
+
+impl ElementBackend for HelloBackend {
+    fn create(element: &mut Element) -> Self where Self: Sized {
+        Self {
+            // Save a weak reference to the element, which will be used later
+            element_weak: element.as_weak(),
+        }
+    }
+}
+```
+
+### Registering the Custom Component
+
+After creating the custom component, it needs to be registered. This can be done during the initialization of the JS engine.
+
+```rust
+impl IApp for AppImpl {
+    
+    fn init_js_engine(&mut self, _js_engine: &mut JsEngine) {
+        // Register our custom component with the tag "hello"
+        register_component::<HelloBackend>("hello");
+    }
+    ...
+}
+```
+
+Here, we register this component as the `hello` component.
+
+### Creating JS Binding for the Custom Component
+
+To use this custom component in JS, we need to create a JS binding: `HelloElement` .
+
+```javascript
+class HelloElement extends Element {
+    constructor() {
+        // "hello" is the element's tag, which must match the tag declared during registration
+        super("hello");
+    }
+}
+```
+
+`HelloElement` inherits from the `Element` class, which is the base class for all components.
+
+### Using the Custom Component
+
+After completing the three steps of `creation`, `registration`, and `binding`, the component can be directly used in JS code.
+
+First, define some basic styles for it.
+
+```css
+body {
+    justify-content: center;
+    align-items: center;
+}
+hello {
+    width: 100px;
+    height: 100px;
+    background: #ccc;
+}
+```
+
+Then, instantiate a `hello` component and add it to the document flow.
+
+```javascript
+const helloElement = new HelloElement();
+window.body.addChild(helloElement);
+```
+
+The running effect is as follows:
+
+<Image src={initImg} alt="hello element" width="300" />
+
+### Rendering the Component
+
+As shown, our custom component is displayed in the window, but it doesn't do anything yet. Now, let's enhance this component by adding custom rendering logic, which is typically required for custom components.
+
+To add custom rendering logic, implement the `ElementBackend::render` method.
+
+```rust
+impl ElementBackend for HelloBackend {
+    ...
+    fn render(&mut self) -> RenderFn {
+        // Upgrade the weak reference to the element to a strong reference
+        let element = self.element_weak.upgrade_mut().unwrap();
+        // Get the element's size information
+        let bounds = element.get_bounds();
+        // Get the center coordinates of the element
+        let center = (bounds.width / 2.0, bounds.height / 2.0);
+        // Calculate the radius
+        let radius = f32::min(center.0, center.1);
+        RenderFn::new(move |painter| {
+            let mut paint = Paint::default();
+            // Use fill style
+            paint.set_style(PaintStyle::Fill);
+            paint.set_color(Color::from_rgb(0, 80, 0));
+            // Draw a circle
+            painter.canvas.draw_circle(center, radius, &paint);
+        })
+    }
+}
+```
+
+The `render` method returns a `RenderFn` object containing our component's rendering logic. In the example above, we draw a solid circle. Rerun the application to see the final effect:
+
+<Image src={renderImg} alt="custom element with renderer"  width="300" />
+
+### Related Code and Reference Examples
+
+The complete code for this article can be found in the Deft repository: https://github.com/deft-ui/deft/blob/main/examples/custom_element.rs
+
+More reference examples:
+
+1. Video playback (ffmpeg): https://github.com/deft-ui/deft-video
+2. Remote desktop (SPICE): https://github.com/kasonyang/tiny-spice
+
+

src/content/docs/en/advanced/custom-component.mdx

@@ -0,0 +1,68 @@
+---
+title: Cross-Language Call
+---
+
+## JavaScript Call Rust
+
+1. Declare a Rust function
+
+   Sync function
+   ```rust
+   #[deft_macros::js_func]
+   pub fn hello(message: String) -> String {
+       println("value from js: ", message);
+       "Hi, I am Rust".to_string()
+   }
+   ```
+   Async function
+   ```rust
+   #[deft_macros::js_func]
+   pub async fn hello_async(message: String) -> String {
+       println("value from js: ", message);
+       "Hi, I am Rust".to_string()
+   }
+   ```
+2. Register Rust functions to JavaScript engine
+   ```rust
+   impl IApp for YourApp {
+      fn init_js_engine(&mut self, js_engine: &mut JsEngine) {
+         js_engine.add_global_func(hello::new());
+         js_engine.add_global_func(hello_async::new());
+      }
+      ...
+   }   
+   ```
+3. JavaScript调用
+   ```javascript
+   // Call sync function
+   const value = hello("Hello, I am JavaScript");
+   console.log('value from rust', value);
+   
+   // Call async function
+   const value = await hello_async("Hello, I am JavaScript");
+   console.log('value from rust', value);
+   ```
+
+## Rust Call JavaScript
+
+**Rust global execute JavaScript code**
+
+```rust
+let mut js_engine = JsEngine::get();
+js_engine.eval_module("console.log(111)", "test.js");
+```
+
+**Rust call JavaScript function**
+JavaScript call Rust, and pass a JavaScript function as a parameter to Rust, at this time, Rust can use `call_as_function` to call the JavaScript function.
+```rust
+#[deft_macros::js_func]
+pub fn my_rust_fn(callback: JsValue) {
+    // callback is a function object passed from JavaScript
+    // execute JavaScript callback
+    callback.call_as_function(vec![JsValue::Bool(true)]);   
+}
+```
+
+
+
+

src/content/docs/en/advanced/ffi.md

@@ -0,0 +1,29 @@
+---
+title: Renderers
+---
+
+### Introduction
+
+Deft comes with the following 3 renderers.
+
+| Name       | Description                     | Support Platforms           |
+|------------|---------------------------------|-----------------------------|
+| SoftBuffer | CPU rendering                   | Windows/MacOS/Linux         | 
+| GL         | GPU rendering                   | Windows/MacOS/Linux/Android | 
+| SoftGL     | CPU rendering, GPU presentation | Windows/MacOS/Linux/Android |
+
+Usually, `GL` renderer has better performance, but consumes more memory, and `SoftGL` is suitable for scenarios where `SoftBuffer` is not supported but still want to use CPU rendering.
+
+By default, Deft will automatically match a renderer based on the order in the table. If you want to change the default matching order, you can set it as follows.
+
+1. Create a window and specify the `preferredRenderers` parameter, for example:
+   ```javascript
+    const window = new Window({
+        // prioritize use GL renderers
+        preferredRenderers: ["GL", "SoftBuffer"]
+    });
+   ```
+2. Set the `DEFT_RENDERERS` environment variable, which will take effect for all Deft applications, for example:
+   ```
+   export DEFT_RENDERERS=GL,SoftBuffer
+   ```