git.iko.soy/lynxjs-elm/compiler
on master help sign in
lynxjs-elm/compiler/packages/virtual-dom/README.md
141 lines 3.4 kB history raw
1# lynxjs-elm/virtual-dom
3Virtual DOM implementation for Elm on LynxJS. Replaces browser DOM calls with LynxJS PAPI (Platform API) calls for native iOS/Android rendering.
5This is a low-level package. Most apps should use [`lynxjs-elm/ui`](../ui) instead, which provides typed element constructors built on top of this package.
7## Setup
9This package is an indirect dependency — you don't need to add it manually. It's pulled in by `lynxjs-elm/ui` and `lynxjs-elm/browser`.
11## Module: VirtualDom
13```elm
14import VirtualDom
15```
17### Types
19```elm
20type Node msg
21type Attribute msg
22```
24Both are opaque. `Node` represents a native UI element. `Attribute` represents a style, property, attribute, or event handler.
26### Node Creation
28```elm
29node : String -> List (Attribute msg) -> List (Node msg) -> Node msg
30```
32Create a native element with a tag name, attributes, and children.
34```elm
35text : String -> Node msg
36```
38Plain text node. Auto-wrapped in a `<text>` element by the kernel.
40```elm
41nodeNS : String -> String -> List (Attribute msg) -> List (Node msg) -> Node msg
42```
44Namespaced node. The namespace is ignored in LynxJS — behaves like `node`.
46### Attributes
48```elm
49style : String -> String -> Attribute msg
50```
52Inline style. Example: `style "backgroundColor" "red"`.
54```elm
55property : String -> Json.Value -> Attribute msg
56```
58JSON property. Includes XSS protection (blocks innerHTML).
60```elm
61attribute : String -> String -> Attribute msg
62```
64String attribute. Includes XSS protection (blocks `on*` and form actions).
66```elm
67attributeNS : String -> String -> String -> Attribute msg
68```
70Namespaced attribute. Namespace is ignored in LynxJS.
72### Event Handling
74```elm
75on : String -> Handler msg -> Attribute msg
76```
78Attach an event listener. Event names are mapped to LynxJS equivalents at the kernel level:
80| Elm event | LynxJS event |
81|---|---|
82| `click` | `tap` |
83| `dblclick` | `tap` |
84| `mousedown` | `touchstart` |
85| `mousemove` | `touchmove` |
86| `mouseup` | `touchend` |
88```elm
89type Handler msg
90 = Normal (Json.Decoder msg)
91 | MayStopPropagation (Json.Decoder ( msg, Bool ))
92 | MayPreventDefault (Json.Decoder ( msg, Bool ))
93 | Custom (Json.Decoder { message : msg, stopPropagation : Bool, preventDefault : Bool })
94```
96- `Normal` — standard event handling (`bind` prefix)
97- `MayStopPropagation` — uses `catch` prefix to stop propagation in LynxJS
98- `MayPreventDefault` — not applicable in LynxJS (treated as Normal)
99- `Custom` — maps `stopPropagation` to `catch` prefix
101### Message Routing
103```elm
104map : (a -> msg) -> Node a -> Node msg
105```
107Transform messages produced by a subtree.
109```elm
110mapAttribute : (a -> b) -> Attribute a -> Attribute b
111```
113Transform messages in an attribute.
115### Keyed Nodes
117```elm
118keyedNode : String -> List (Attribute msg) -> List ( String, Node msg ) -> Node msg
119```
121Like `node` but each child has a unique string key. Enables efficient reordering, insertion, and removal.
123```elm
124keyedNodeNS : String -> String -> List (Attribute msg) -> List ( String, Node msg ) -> Node msg
125```
127### Lazy Evaluation
129```elm
130lazy : (a -> Node msg) -> a -> Node msg
131lazy2 : (a -> b -> Node msg) -> a -> b -> Node msg
132lazy3 : (a -> b -> c -> Node msg) -> a -> b -> c -> Node msg
133```
135Delay node building. The view function is only called if the arguments have changed (by reference equality). Variants up to `lazy8` are available.
137---
139## License
141BSD-3-Clause