5de242b...develop · reflex-dom

git.iko.soy/reflex-dom

101 files changed+11405−48233

since splitsnapshots

unifiedsplit

.github/workflows/haskell.ymlnew file+47

@@ -0,0 +1,47 @@

1+name: github-action

3+on: [push, pull_request]

5+jobs:

6+ build:

7+ strategy:

8+ matrix:

9+ ghc: ['8.4.4', '8.6.5', '8.8.4', '8.10.2']

10+ os: ['ubuntu-latest', 'macos-latest']

11+ exclude:

12+ # There are some linker warnings in 802 on darwin that

13+ # cause compilation to fail

14+ # See https://github.com/NixOS/nixpkgs/issues/25139

15+ - ghc: '8.0.2'

16+ os: 'macos-latest'

17+ runs-on: ${{ matrix.os }}

18+

19+ name: GHC ${{ matrix.ghc }} on ${{ matrix.os }}

20+ steps:

21+ - uses: actions/checkout@v2

22+ - uses: actions/setup-haskell@v1

23+ with:

24+ ghc-version: ${{ matrix.ghc }}

25+ - name: Cache

26+ uses: actions/cache@v1

27+ env:

28+ cache-name: cache-cabal

29+ with:

30+ path: ~/.cabal

31+ key: ${{ runner.os }}-${{ matrix.ghc }}-build-${{ env.cache-name }}-${{ hashFiles('**/*.cabal') }}-${{ hashFiles('**/cabal.project') }}

32+ restore-keys: |

33+ ${{ runner.os }}-${{ matrix.ghc }}-build-${{ env.cache-name }}-

34+ ${{ runner.os }}-${{ matrix.ghc }}-build-

35+ ${{ runner.os }}-${{ matrix.ghc }}-

36+ ${{ runner.os }}

37+

38+ - name: Set up cabal project file to avoid webkit2gtk

39+ run: cp cabal.project-nogtk cabal.project

40+ - name: Install dependencies

41+ run: |

42+ cabal update

43+ cabal build --only-dependencies --enable-tests --enable-benchmarks all

44+ - name: Build

45+ run: cabal build --enable-tests --enable-benchmarks all

46+ - name: Run tests

47+ run: cabal test all

.gitignore+4

@@ -35,3 +35,7 @@ hsenv.log

3535.cabal-sandbox/

3636cabal.sandbox.config

3737.stack-work

38+codex.tags

39+*.dump-*

40+*.verbose-core2core

41+*.lkshf

CONTRIBUTING.mdnew file+65

@@ -0,0 +1,65 @@

1+# Contribution Guide

3+Contributions and issue reports are encouraged and appreciated!

5+- [Opening Issues](#opening-issues)

6+- [Submitting Changes](#submitting-changes)

7+ - [Guidelines for Commit Messages](#guidelines-for-commit-messages)

8+ - [Guidelines for Pull Requests](#guidelines-for-pull-requests)

9+ - [Code Quality](#code-quality)

10+ - [Documentation](#documentation)

11+

12+## Opening Issues

13+

14+Before opening an issue, please check whether your issue has already been reported. Assuming it has not:

15+

16+* Describe the issue you're encountering or the suggestion you're making

17+* Include any relevant steps to reproduce or code samples you can. It's always easier for us to debug if we have something that demonstrates the error.

18+* Let us know what version of this project you were using. If you're using a github checkout, provide the git hash.

19+* Describe how you're building this project (i.e., via reflex-platform, cabal install, stack, obelisk, etc.). If you're using reflex-platform or obelisk, provide the git hash of your checkout.

20+

21+## Submitting Changes

22+

23+### Guidelines for Commit Messages

24+

25+#### Summary Line

26+The summary line of your commit message should summarize the changes being made. Commit messages should be written in the imperative mood and should describe what happens when the commit is applied.

27+

28+One way to think about it is that your commit message should be able to complete the sentence:

29+"When applied, this commit will..."

30+

31+#### Body

32+For breaking changes, new features, refactors, or other major changes, the body of the commit message should describe the motivation behind the change in greater detail and may include references to the issue tracker. The body shouldn't repeat code/comments from the diff.

33+

34+### Guidelines for Pull Requests

35+

36+Wherever possible, pull requests should add a single feature or fix a single bug. Pull requests should not bundle several unrelated changes.

37+

38+### Code Quality

39+

40+#### Warnings

41+

42+Your pull request should add no new warnings to the project. It should also generally not disable any warnings.

43+

44+#### Build and Test

45+

46+Make sure the project builds and that the tests pass! This will generally also be checked by CI before merge, but trying it yourself first means you'll catch problems earlier and your contribution can be merged that much sooner!

47+

48+### Documentation

49+

50+#### In the code

51+We're always striving to improve documentation. Please include [haddock](https://haskell-haddock.readthedocs.io/en/latest/index.html) documentation for any added code, and update the documentation for any code you modify.

52+

53+#### In the Changelog

54+Add an entry to the changelog when your PR:

55+* Adds a feature

56+* Deprecates something

57+* Includes a breaking change

58+* Makes any other change that will impact users

59+

60+You may need to add changelog entries to one or both of the changelogs in this repository:

61+* [reflex-dom-core's changelog](reflex-dom-core/ChangeLog.md)

62+* [reflex-dom's changelog](reflex-dom/ChangeLog.md)

63+

64+#### In the [Readme](README.md)

65+The readme is the first place a lot of people look for information about the repository. Update any parts of the readme that are affected by your PR.

FAQ.mdnew file+31

@@ -0,0 +1,31 @@

1+# Frequently Asked Questions

3+### How do I configure DOM events with flags like `preventDefault` and `stopPropagation`?

5+Using `element`, a low-level DOM builder function. Its second argument, `ElementConfig`, has a `_elementConfig_eventSpec` field that can be modified using `addEventSpecFlags`. It takes a `Proxy` that specifies the `DomSpace`, an event name, and a callback which takes the event result and returns an event flag, which can enable behavior like `preventDefault` and `stopPropagation`.

7+The type signature on `def` is needed because the fields of the `ElementConfig` can change the type of the `ElementConfig`. GHC can probably figure out the type of the resulting `ElementConfig`, but it doesn't know what the type of `def` was before the modifications, since it never gets used with that configuration.

9+For example:

10+

11+```haskell

12+{-# LANGUAGE OverloadedStrings #-}

13+{-# LANGUAGE ScopedTypeVariables #-}

14+

15+import Control.Lens ((&), (%~), (.~))

16+import Data.Proxy

17+import Reflex.Dom

18+

19+main :: IO ()

20+main = mainWidget $ do

21+ (click, ()) <- linkPreventDefault $ text "reflex-frp"

22+ display =<< count click

23+

24+linkPreventDefault :: forall t m a. DomBuilder t m => m a -> m (Event t (), a)

25+linkPreventDefault c = do

26+ let cfg = (def :: ElementConfig EventResult t (DomBuilderSpace m))

27+ & elementConfig_initialAttributes .~ ("href" =: "https://reflex-frp.org")

28+ & elementConfig_eventSpec %~ addEventSpecFlags (Proxy :: Proxy (DomBuilderSpace m)) Click (const preventDefault)

29+ (link, a) <- element "a" cfg c

30+ return (domEvent Click link, a)

31+```

LICENSE+1−1

@@ -1,4 +1,4 @@

22All rights reserved.

44Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Quickref.md+10−55

@@ -28,7 +28,7 @@ Widgets may return any type (this is 'a' in many of the functions below). Often

2828-- This version returns the 'El' as well.

2929[W] el' :: Text -> m a -> m (El, a)

3030

31−-- These two additionally apply attributes to the element, such as ("class" =: "blah")

31+-- These two additionally apply attributes to the element, such as ("class" =: "blah"). (=:) is 'Map.singleton'

3232[W] elAttr :: Text -> Map Text Text -> m a -> m a

3333[W] elAttr' :: Text -> Map Text Text -> m a -> m (El, a)

3434

@@ -36,13 +36,16 @@ Widgets may return any type (this is 'a' in many of the functions below). Often

3636[W] elDynAttr :: Text -> Dynamic (Map Text Text) -> m a -> m a

3737[W] elDynAttr' :: Text -> Dynamic (Map Text Text) -> m a -> m (El, a)

3838

39+-- As above, but with an optional XML namespace for the tag. Note that this does *not* set the 'xmlns' attribute. See https://www.w3.org/TR/DOM-Level-2-Core/core.html#ID-DocCrElNS

40+[W] elDynAttrNS' :: Maybe Text -> Text -> Dynamic (Map Text Text) -> m a -> m (El, a)

41+

3942-- Shortcut for elAttr when you only want to set the "class" attribute.

4043[W] elClass :: Text -> Text -> m a -> m a

4144

4245-- Even shorter-cut for above when element type is "div". Create a div of given class.

4346[W] divClass :: Text -> m a -> m a

4447

45−-- Create a widget of given type with arbitrary, Dymamic HTML inside.

48+-- Create a widget of given type with arbitrary, Dynamic HTML inside.

4649[W] elDynHtml' :: Text -> Dynamic Text -> m El

4750[W] elDynHtmlAttr' :: Text -> Map Text Text -> Dynamic Text -> m El

4851

@@ -72,32 +75,10 @@ Note the "list" functions do not imply particular HTML tags (ul, li, etc), thoug

7275

7376-- Same as dyn, but takes initial value and an update Event instead of a Dynamic.

7477[W] widgetHold :: m a -> Event (m a) -> m (Dynamic a)

75−

76−-- Turn a Dynamic key/value map into a set of dynamically-changing widgets.

77−[W] listWithKey :: Ord k =>

78− Dynamic (Map k v) -> (k -> Dynamic v -> m a ) -> m (Dynamic (Map k a))

79−

80−-- Same as above where the widget constructor doesn't care about the key.

81−[W] list :: Ord k =>

82− Dynamic (Map k v) -> ( Dynamic v -> m a ) -> m (Dynamic (Map k a))

83−

84−-- Even simpler version where there are no keys and we just use a list.

85−[W] simpleList ::

86− Dynamic [v] -> ( Dynamic v -> m a ) -> m (Dynamic [a])

87−

88−-- Like listWithKey specialized for widgets returning (Event a).

89−[W] listViewWithKey :: Ord k =>

90− Dynamic (Map k v) -> (k -> Dynamic v -> m (Event a)) -> m (Event (Map k a))

91−

92−-- Create a dynamically-changing set of widgets, one of which is selected at any time.

93−[W] selectViewListWithKey_ :: Ord k => Dynamic k ->

94− Dynamic (Map k v) -> (k -> Dynamic v -> Dynamic Bool -> m (Event a)) -> m (Event k)

95−

96−-- Same as listWithKey, but takes initial values and an updates Event instead of a Dynamic.

97−[W] listWithKey' :: Ord k =>

98− Map k v -> Event (Map k (Maybe v)) -> (k -> v -> Event v -> m a) -> m (Dynamic (Map k a))

9978```

10079

80+Also see the "Collection management functions" section in the `reflex` Quick Reference.

81+

10182### Utility widgets

10283

10384These are useful widgets that are implemented (or could be implemented) in terms of the low-level widgets above.

@@ -132,27 +113,12 @@ Some of these widget builders take a configuration record and return a record co

132113

133114## Connecting to the real world (I/O)

134115

135−### Connecting to DOM events

136−

137116```haskell

138117-- Extract the specified Event from an 'El'. See Reflex.Dom.Widget.Basic

139118[ ] domEvent :: EventName en -> El -> Event (EventResultType en)

140119```

141120

142−### Performing arbitrary I/O in response to Events

143−

144−```haskell

145−-- Run side-effecting actions in Event when it occurs; returned Event contains

146−-- results. Side effects run in (WidgetHost m) monad, which includes [S] and [H]

147−-- and can also do I/O via liftIO

148−[W] performEvent :: Event ( WidgetHost m a) -> m (Event a)

149−

150−-- Just run side-effects; no return Event

151−[W] performEvent_ :: Event ( WidgetHost m ()) -> m ()

152−

153−-- Actions run asynchronously; actions are given a callback to send return values

154−[W] performEventAsync :: Event ((a -> IO ()) -> WidgetHost m ()) -> m (Event a)

155−```

121+Also see the "Connection to the real world" and "Time" sections in the `reflex` Quick Reference.

156122

157123### XMLHttpRequest

158124

@@ -175,16 +141,6 @@ Convenience functions for XMLHttpRequest. see Reflex.Dom.Xhr

175141[W] getAndDecode :: FromJSON a => Event Text -> m (Event (Maybe a))

176142```

177143

178−### Time

179−

180−```haskell

181−-- Create Event at given interval with given basis time.

182−[W] tickLossy :: NominalDiffTime -> UTCTime -> m (Event t TickInfo)

183−

184−-- Delay an Event's occurrences by a given amount in seconds.

185−[W] delay :: NominalDiffTime -> Event t a -> m (Event t a)

186−```

187−

188144## Startup

189145

190146```haskell

@@ -198,7 +154,6 @@ Convenience functions for XMLHttpRequest. see Reflex.Dom.Xhr

198154[I] mainWidgetWithCss ::

199155 ByteString ->

200156 Widget Spider (Gui Spider (WithWebView SpiderHost) (HostFrame Spider)) () -> IO ()

201−

202−-- One-shot Event that is triggered once all initial widgets are built

203−[W] getPostBuild :: m (Event ())

204157```

158+

159+Also see the corresponding section in the `reflex` Quick Reference.

README.md+15−9

@@ -1,17 +1,23 @@

1−## Reflex-DOM

2−### A Framework for Functional Reactive Web Apps in Haskell

1+## [Reflex-DOM](https://reflex-frp.org)

4−Reflex-DOM is a framework for building web applications in Haskell, based on the [Functional Reactive Programming](https://wiki.haskell.org/Functional_Reactive_Programming) library [Reflex](https://github.com/reflex-frp/reflex).

3+[![Haskell](https://img.shields.io/badge/language-Haskell-orange.svg)](https://haskell.org) [![Hackage](https://img.shields.io/hackage/v/reflex-dom.svg)](https://hackage.haskell.org/package/reflex-dom) [![Hackage CI](https://matrix.hackage.haskell.org/api/v2/packages/reflex-dom/badge)](https://matrix.hackage.haskell.org/#/package/reflex-dom) [![BSD3 License](https://img.shields.io/badge/license-BSD3-blue.svg)](https://github.com/reflex-frp/reflex-dom/blob/master/LICENSE)

6−Comprehensive documentation is still a work in progress, but a [demo](https://github.com/reflex-frp/reflex-platform) is available and an introductory talk is available at [Part 1](https://www.youtube.com/watch?v=mYvkcskJbc4) / [Part 2](https://www.youtube.com/watch?v=3qfc9XFVo2c) ([Slides](https://obsidian.systems/reflex-nyhug/)).

5+Web applications without callbacks or side-effects. Reflex-DOM brings the power of [Functional Reactive Programming (FRP)](https://wiki.haskell.org/Functional_Reactive_Programming) to the web. Build [HTML](https://developer.mozilla.org/en-US/docs/Web/HTML) and other [Document Object Model (DOM)](https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model) data with a pure functional interface.

8−A summary of Reflex-DOM functions is available in the [quick reference](Quickref.md).

7+Reflex-DOM is a framework for building web applications in [Haskell](https://www.haskell.org/), based on the [Functional Reactive Programming](https://wiki.haskell.org/Functional_Reactive_Programming) library [Reflex](https://github.com/reflex-frp/reflex).

9+**Visit https://reflex-frp.org/ for more information, tutorials, documentation and [examples](https://examples.reflex-frp.org/).**

910

1011### Additional resources

11−[Get started with Reflex](https://github.com/reflex-frp/reflex-platform)

1212

13−[/r/reflexfrp](https://www.reddit.com/r/reflexfrp)

13+* [Official Website](https://reflex-frp.org/)

14+* [Quick Reference](Quickref.md)

15+* [Obelisk](https://github.com/obsidiansystems/obelisk#obelisk): A framework built on Reflex and Reflex-DOM for functional reactive web and mobile applications, with batteries included.

16+* [Get started with Reflex](https://github.com/reflex-frp/reflex-platform)

17+* [/r/reflexfrp](https://www.reddit.com/r/reflexfrp)

18+* [irc.freenode.net #reflex-frp](http://webchat.freenode.net?channels=%23reflex-frp&uio=d4)

1419

15−[hackage](https://hackage.haskell.org/package/reflex)

20+### Hacking

1621

17−[irc.freenode.net #reflex-frp](http://webchat.freenode.net?channels=%23reflex-frp&uio=d4)

22+Use the `./scripts/hack-on haskell-overlays/reflex-packages/dep/reflex-dom` script in [Reflex Platform](https://github.com/reflex-frp/reflex-platform) to checkout the source code of `reflex-dom` locally in `./dep/reflex-dom` directory.

23+Then do modifications to the source in place, and use the `./try-reflex` or `./scripts/work-on` scripts to create the shell to test your changes.

cabal.projectnew file+10

@@ -0,0 +1,10 @@

1+packages:

2+ reflex-dom-core/

3+ reflex-dom/

4+ chrome-test-utils/

5+ reflex-dom-test-selenium/

7+source-repository-package

8+ type: git

9+ location: https://github.com/dfordivam/hspec-webdriver-clone

10+ tag: 0d748b7bb7cd74dce0a55a1ec86b01dbb8a71cd8

cabal.project-nogtknew file+14

@@ -0,0 +1,14 @@

1+packages:

2+ reflex-dom-core/

3+ reflex-dom/

5+package reflex-dom-core

6+ flags: -hydration-tests -gc-tests

8+package reflex-dom

9+ flags: +use-warp -webkit2gtk

10+

11+source-repository-package

12+ type: git

13+ location: https://github.com/dfordivam/hspec-webdriver-clone

14+ tag: 0d748b7bb7cd74dce0a55a1ec86b01dbb8a71cd8

chrome-test-utils/LICENSEnew file+12

@@ -0,0 +1,12 @@

4+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

6+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

8+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

10+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

11+

12+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

chrome-test-utils/chrome-test-utils.cabalnew file+30

@@ -0,0 +1,30 @@

1+Name: chrome-test-utils

2+Version: 0.5

3+Synopsis: Utilities to write headless Chromium tests

4+License: BSD3

5+License-file: LICENSE

6+Author: Obsidian Systems LLC

7+Maintainer: maintainer@obsidian.systems

8+Stability: Experimental

9+Build-type: Simple

10+Cabal-version: >=1.9.2

11+

12+library

13+ hs-source-dirs: src

14+ ghc-options: -Wall -fwarn-tabs -funbox-strict-fields -O2 -ferror-spans

15+ build-depends: base

16+ , linux-namespaces

17+ , process

18+ , temporary

19+ , text

20+ , unix

21+ exposed-modules:

22+ Test.Util.UnshareNetwork

23+ Test.Util.ChromeFlags

24+ if !os(linux) || !arch(x86_64)

25+ buildable: False

26+

27+source-repository head

28+ type: git

29+ location: https://github.com/reflex-frp/reflex-dom

30+ subdir: chrome-test-utils

chrome-test-utils/src/Test/Util/ChromeFlags.hsnew file+17

@@ -0,0 +1,17 @@

1+{-# LANGUAGE OverloadedStrings #-}

2+module Test.Util.ChromeFlags where

4+import Data.Semigroup

5+import Data.Text

6+import System.IO.Temp

8+withSandboxedChromeFlags :: Bool -> ([Text] -> IO a) -> IO a

9+withSandboxedChromeFlags headless action =

10+ withSystemTempDirectory "reflex-dom-core_test" $ \tmp ->

11+ action

12+ [ if headless then "--headless" else "--auto-open-devtools-for-tabs"

13+ , "--disable-gpu"

14+ , "--no-sandbox"

15+ , "--remote-debugging-port=9222"

16+ , "--user-data-dir=" <> pack tmp

17+ ]

chrome-test-utils/src/Test/Util/UnshareNetwork.hsnew file+12

@@ -0,0 +1,12 @@

1+module Test.Util.UnshareNetwork where

3+import System.Linux.Namespaces

4+import System.Posix

5+import System.Process

7+unshareNetwork :: IO ()

8+unshareNetwork = do

9+ uid <- getEffectiveUserID

10+ unshare [User, Network]

11+ writeUserMappings Nothing [UserMapping 0 uid 1]

12+ callCommand "ip link set lo up ; ip addr"

codex.tagsdeleted−44025