git.iko.soy/lynxjs-elm/compiler
on master help sign in
lynxjs-elm/compiler/packages/browser/README.md
270 lines 5.6 kB history raw
1# lynxjs-elm/browser
3Elm application lifecycle for LynxJS. Replaces browser DOM rendering with LynxJS PAPI calls via `globalThis.page` and `__FlushElementTree()`.
5## Setup
7Add to your `elm.json`:
9```json
11 "dependencies": {
12 "direct": {
13 "lynxjs-elm/browser": "1.0.0"
14 }
15 }
17```
19## Modules
21- [`Browser`](#browser) — Program entry points (sandbox, element, document, application)
22- [`Browser.Dom`](#browserdom) — Viewport queries, focus/blur
23- [`Browser.Events`](#browserevents) — Global event subscriptions (animation, keyboard, mouse, window)
24- [`Browser.Navigation`](#browsernavigation) — URL navigation (stubbed in LynxJS)
26---
28## Browser
30```elm
31import Browser
32```
34### Programs
36```elm
37sandbox :
38 { init : model
39 , view : model -> VirtualDom.Node msg
40 , update : msg -> model -> model
41 }
42 -> Program () model msg
43```
45Create a sandboxed program with no side effects. Good for learning and prototyping.
47```elm
48element :
49 { init : flags -> ( model, Cmd msg )
50 , view : model -> VirtualDom.Node msg
51 , update : msg -> model -> ( model, Cmd msg )
52 , subscriptions : model -> Sub msg
53 }
54 -> Program flags model msg
55```
57Create a program with commands and subscriptions.
59```elm
60document :
61 { init : flags -> ( model, Cmd msg )
62 , view : model -> Document msg
63 , update : msg -> model -> ( model, Cmd msg )
64 , subscriptions : model -> Sub msg
65 }
66 -> Program flags model msg
67```
69Like `element` but the view returns a `Document`:
71```elm
72type alias Document msg =
73 { title : String
74 , body : List (VirtualDom.Node msg)
75 }
76```
78Note: `title` is ignored in LynxJS. It exists for API compatibility with elm/browser.
80```elm
81application :
82 { init : flags -> Url.Url -> Key -> ( model, Cmd msg )
83 , view : model -> Document msg
84 , update : msg -> model -> ( model, Cmd msg )
85 , subscriptions : model -> Sub msg
86 , onUrlRequest : UrlRequest -> msg
87 , onUrlChange : Url.Url -> msg
88 }
89 -> Program flags model msg
90```
92URL-managing application. URL support is stubbed in LynxJS — `init` receives a dummy localhost URL.
94```elm
95type UrlRequest
96 = Internal Url.Url
97 | External String
98```
100### Example
102```elm
103import Browser
104import Lynx exposing (..)
105import Lynx.Attributes exposing (..)
106import Lynx.Events exposing (..)
108main =
109 Browser.sandbox
110 { init = 0
111 , view = view
112 , update = update
113 }
115type Msg = Increment | Decrement
117update msg model =
118 case msg of
119 Increment -> model + 1
120 Decrement -> model - 1
122view model =
123 Lynx.view [ alignItems "center", padding 20 ]
124 [ Lynx.view [ onTap Decrement ] [ Lynx.text [] [ textContent "-" ] ]
125 , Lynx.text [ fontSize 48 ] [ textContent (String.fromInt model) ]
126 , Lynx.view [ onTap Increment ] [ Lynx.text [] [ textContent "+" ] ]
127 ]
128```
130### Lifecycle
1321. Virtual DOM tree rendered to native view objects
1332. Appended to `globalThis.page` (LynxJS root node)
1343. `__FlushElementTree()` called to sync native UI
1354. On each update: diff, patch, then flush again
137---
139## Browser.Dom
141```elm
142import Browser.Dom
143```
145**Note:** Most DOM queries are stubbed in LynxJS. Element lookups by ID return `NotFound`.
147### Types
149```elm
150type Error = NotFound String
151```
153```elm
154type alias Viewport =
155 { scene : { width : Float, height : Float }
156 , viewport : { x : Float, y : Float, width : Float, height : Float }
157 }
158```
160```elm
161type alias Element =
162 { scene : { width : Float, height : Float }
163 , viewport : { x : Float, y : Float, width : Float, height : Float }
164 , element : { x : Float, y : Float, width : Float, height : Float }
165 }
166```
168### Focus & Blur
170```elm
171focus : String -> Task Error ()
172blur : String -> Task Error ()
173```
175Focus or blur an element by ID. Stubbed in LynxJS.
177### Viewport
179```elm
180getViewport : Task x Viewport
181setViewport : Float -> Float -> Task x ()
182getViewportOf : String -> Task Error Viewport
183setViewportOf : String -> Float -> Float -> Task Error ()
184```
186### Element Queries
188```elm
189getElement : String -> Task Error Element
190```
192Get position and size of an element by ID. Stubbed in LynxJS.
194---
196## Browser.Events
198```elm
199import Browser.Events
200```
202**Note:** Global event subscriptions are stubbed in LynxJS. These functions exist for API compatibility but subscriptions won't fire.
204### Animation
206```elm
207onAnimationFrame : (Time.Posix -> msg) -> Sub msg
208onAnimationFrameDelta : (Float -> msg) -> Sub msg
209```
211Subscribe to animation frames (~60 fps). `onAnimationFrameDelta` provides milliseconds since the last frame.
213### Keyboard
215```elm
216onKeyPress : Json.Decoder msg -> Sub msg
217onKeyDown : Json.Decoder msg -> Sub msg
218onKeyUp : Json.Decoder msg -> Sub msg
219```
221### Mouse
223```elm
224onClick : Json.Decoder msg -> Sub msg
225onMouseMove : Json.Decoder msg -> Sub msg
226onMouseDown : Json.Decoder msg -> Sub msg
227onMouseUp : Json.Decoder msg -> Sub msg
228```
230### Window
232```elm
233onResize : (Int -> Int -> msg) -> Sub msg
234onVisibilityChange : (Visibility -> msg) -> Sub msg
235```
237```elm
238type Visibility = Visible | Hidden
239```
241---
243## Browser.Navigation
245```elm
246import Browser.Navigation
247```
249**All functions are no-ops in LynxJS.** They exist for API compatibility with elm/browser.
251```elm
252type Key
253```
255Opaque navigation authority. Empty in LynxJS.
257```elm
258pushUrl : Key -> String -> Cmd msg
259replaceUrl : Key -> String -> Cmd msg
260back : Key -> Int -> Cmd msg
261forward : Key -> Int -> Cmd msg
262load : String -> Cmd msg
263reload : Cmd msg
264```
266---
268## License
270BSD-3-Clause