Add concept and exercise for Browser.sandbox

Author: ceddlyburge

bin/build.sh

@@ -5,9 +5,10 @@ set -o pipefail
 
 # SANITY CHECKS
 
+echo "Checking that all elm.json files are identical to template/elm.json"
 for elm_json in exercises/*/*/elm.json
 do
-  cmp template/elm.json $elm_json
+  diff -w template/elm.json $elm_json
 done
 echo "All elm.json files are identical to template/elm.json"
 
@@ -63,15 +64,18 @@ rm -rf build
 mkdir -p build/src build/tests
 cp template/elm.json build/
 
-for example_file in exercises/concept/**/.meta/*.elm
+for exemplar_file in exercises/concept/**/.meta/*.elm
 do
-  exercise_dir=$(dirname $(dirname $example_file))
-  # get kebab-case slug and transform it to PascalCase
-  exercise_name=$(basename $exercise_dir | sed -r 's/(^|-)([a-z])/\U\2/g')
+  exercise_dir=$(dirname $(dirname ${exemplar_file}))
+  # solution_file is src/ValentinesDay.elm or similar from config.json
+  solution_file=$(jq --raw-output '.files.solution | .[0]' "${exercise_dir}/.meta/config.json")
+  # solution_file_stub is ValentinesDay or similar
+  solution_file_stub=$(echo ${solution_file} | sed -r 's/src\/([a-zA-Z]*)\.elm/\1/')
+  
   cp $exercise_dir/src/*.elm "build/src/"
-  cp $example_file "build/src/$exercise_name.elm"
+  cp $exemplar_file "build/src/$solution_file_stub.elm"
   # Copy tests files under a unique temporary directory and remove all "skip <| ..."
-  cat "$exercise_dir/tests/Tests.elm" | sed "s/module Tests/module Tests$exercise_name/" | sed 's/skip <|//g' > "build/tests/Tests$exercise_name.elm"
+  cat "$exercise_dir/tests/Tests.elm" | sed "s/module Tests/module Tests$solution_file_stub/" | sed 's/skip <|//g' > "build/tests/Tests$solution_file_stub.elm"
 done
 
 cd build && npx --no-install elm-test-rs --fuzz 10

bin/run_all_exercises.sh

@@ -34,7 +34,7 @@ done
 for exercise_dir in "$exercices"/concept/*
 do
   echo "Running tests for concept exercise $exercise_dir"
-  bin/run.sh "ignored_slug" $exercise_dir $exercise_dir > /dev/null
+  bin/run.sh "ignored_slug" $exercise_dir $exercise_dir
 
   # Check that all tests have a task_id defined
   all_have_task_id=$(jq '.tests | map(.task_id) | all' "$exercise_dir/results.json")

concepts/web-applications-sandbox/.meta/config.json

@@ -0,0 +1,9 @@
+{
+  "blurb": "Learn how to write Web Applications in Elm",
+  "authors": [
+    "ceddlyburge"
+  ],
+  "contributors": [
+    "jiegillet"
+  ]
+}

concepts/web-applications-sandbox/about.md

@@ -0,0 +1,107 @@
+# About
+
+Elm is a delightful language for building reliable web applications.
+It has friendly error messages, great performance, small assets, and no runtime exceptions.
+
+Probably the most famous and widely copied part of Elm is The Elm Architecture, which is a simple pattern for structuring web applications, and is how all Elm web applications are written.
+
+The core idea is that your code is built around a `Model` of your application state, a way to `update` your model, and a way to `view` your model.
+
+The `Model` contains the application’s state - all the data that the application needs.
+It can be any type, but in any useful application it is usually a [record][record].
+If you imagine a simple application with a text box, and text showing the reverse of that text, the model would look like below.
+You can also see this example on the [Elm Guide][elm-guide-text-fields].
+
+```elm
+type alias Model =
+  { text : String
+  }
+```
+
+`update` is a function that gets called with a `Msg` when there's a change (like the user clicking a button).
+It takes the `Msg` and the current `Model`, and returns a new `Model`.
+The `Msg` can be any type, but it is usually a [custom type][custom-type].
+
+```elm
+type Msg
+  = TextChanged String
+
+update : Msg -> Model -> Model
+update msg model =
+  case msg of
+    TextChanged newText ->
+      { model | text = newText }
+```
+
+As with all custom types, the variants of the `Msg` can include as much arbitrary information as they need.
+In the example above the `TextChanged` variant includes a `String`.
+
+`view` is a function that returns HTML to show to the user in the browser.
+It takes the current `Model` and returns an `Html Msg` (the type that Elm uses to represent HTML).
+Each HTML element (for example `<div>`) has a corresponding Elm function (`Html.div`), in the `Html` package.
+Each of these functions takes two parameters, the first is a list of attributes (from the `Html.Attributes` and `Html.Events` packages), and the second is a list of child elements (functions from the `Html` package).
+There is also a `text` function that represents HTML string content, which just takes a string parameter, but is otherwise used in the same way as all the other functions / elements in the `Html` package.
+
+The `view` function can specify that certain events, like clicking a button or editing text in a text box, result in a `Msg` being created, which the Elm Runtime will use to call the `update` function, modify the `Model` and generate updated HTML.
+In the code below this happens with `Html.Events.onInput TextChanged`.
+
+```elm
+view : Model -> Html Msg
+view model =
+  Html.div []
+    [ Html.input
+      [ Html.Attributes.placeholder "Text to reverse"
+      , Html.Attributes.value model.text
+      , Html.Events.onInput TextChanged
+      ]
+      []
+    , Html.div [] [ Html.text (String.reverse model.text) ]
+    ]
+```
+
+`Html.Events.onInput` expects to be passed a function (`String -> Msg`) which it will use to create the `Msg`.
+Different events expect different functions depending on what information they can provide, so for example `Html.Events.onCheck` (for checkboxes) expects `Bool -> Msg` and `Html.Events.onClick` just expects a `Msg`.
+
+The Elm language is pure and functional and no mutation is possible, so the Elm Runtime handles all the things that change.
+You can see all of the different [HTML Elements][html-elements], [Element Attributes][element-attributes] and [HTML Events][html-events] on the Elm package registry.
+
+There are 4 "levels" of web application you can write in Elm, that get progressively more powerful and more complicated (although Elm remains a delightfully simple language and ecosystem).
+These are all defined in the [Browser package][browser-package]:
+
+- [sandbox][browser-sandbox] — react to user input, like buttons and checkboxes
+- [element][browser-element] — talk to the outside world, using HTTP and JavaScript interop
+- [document][browser-document] — control the `<title>` and `<body>` of a web page
+- [application][browser-application] — create full single-page appliations that handle routing / url changes
+
+This concept uses the [sandbox][browser-sandbox], as it is the simplest (and because it is a sandbox, it is relatively easy to work with the Exercism online editor).
+The entry module for an Elm program must be called `Main`, and the function that creates the application must be called `main`,  as below.
+
+```elm
+import Browser
+import Html exposing (Html, Attribute, div, input, text)
+import Html.Attributes exposing (placeholder, value)
+import Html.Events exposing (onInput)
+
+main =
+  Browser.sandbox { init = init, update = update, view = view }
+
+init : Model
+init =
+  { text = "" }
+
+-- Add Model, Msg, update and view here
+```
+
+We have already seen the `update` and `view` functions, and the [sandbox][browser-sandbox] additionally requires an `init` function, to return the initial state of the `Model`.
+
+[record]: https://elm-lang.org/docs/records
+[custom-type]: https://guide.elm-lang.org/types/custom_types.html
+[elm-guide-text-fields]: https://guide.elm-lang.org/architecture/text_fields
+[html-elements]: https://package.elm-lang.org/packages/elm/html/latest/Html
+[element-attributes]: https://package.elm-lang.org/packages/elm/html/latest/Html-Attributes
+[html-events]: https://package.elm-lang.org/packages/elm/html/latest/Html-Events
+[browser-package]: https://package.elm-lang.org/packages/elm/browser/latest/
+[browser-sandbox]: https://package.elm-lang.org/packages/elm/browser/latest/Browser#sandbox
+[browser-element]: https://package.elm-lang.org/packages/elm/browser/latest/Browser#element
+[browser-document]: https://package.elm-lang.org/packages/elm/browser/latest/Browser#document
+[browser-application]: https://package.elm-lang.org/packages/elm/browser/latest/Browser#application

concepts/web-applications-sandbox/introduction.md

@@ -0,0 +1,51 @@
+# About
+
+Elm is a delightful language for building reliable web applications.
+It has friendly error messages, great performance, small assets, and no runtime exceptions.
+
+Probably the most famous and widely copied part of Elm is The Elm Architecture, which is a simple pattern for structuring web applications, and is how all Elm web applications are written.
+
+The core idea is that your code is built around a `Model` of your application state, a way to `update` your model, and a way to `view` your model.
+
+The `Model` contains the application’s state - all the data that the application needs.
+If you imagine a simple application with a text box, and text showing the reverse of that text, the model would look like below.
+You can also see this example on the [Elm Guide][elm-guide-text-fields].
+
+```elm
+type alias Model =
+  { text : String
+  }
+```
+
+`update` is a function that gets called with a `Msg` when there's a change (like the user clicking a button).
+It takes the `Msg` and the current `Model`, and returns a new `Model`.
+
+```elm
+type Msg
+  = TextChanged String
+
+update : Msg -> Model -> Model
+update msg model =
+  case msg of
+    TextChanged newText ->
+      { model | text = newText }
+```
+
+`view` is a function that returns HTML to show to the user in the browser.
+It takes the current `Model` and returns an `Html Msg` (the type that Elm uses to represent HTML).
+
+```elm
+view : Model -> Html Msg
+view model =
+  Html.div []
+    [ Html.input
+      [ Html.Attributes.placeholder "Text to reverse"
+      , Html.Attributes.value model.text
+      , Html.Events.onInput TextChanged
+      ]
+      []
+    , Html.div [] [ Html.text (String.reverse model.text) ]
+    ]
+```
+
+[elm-guide-text-fields]: https://guide.elm-lang.org/architecture/text_fields

concepts/web-applications-sandbox/links.json

@@ -0,0 +1,22 @@
+[
+  {
+    "url": "https://guide.elm-lang.org/architecture/",
+    "description": "The Elm Architecture"
+  },
+  {
+    "url": "https://guide.elm-lang.org/architecture/buttons",
+    "description": "Buttons example (using Browser.sandbox)"
+  },
+  {
+    "url": "https://package.elm-lang.org/packages/elm/browser/latest/",
+    "description": "Browser package"
+  },
+  {
+    "url": "https://github.com/lustre-labs/lustre",
+    "description": "Lustre, a Gleam framework based on The Elm Architecture"
+  },
+  {
+    "url": "https://github.com/redbadger/crux",
+    "description": "Crux, a Rust cross platform app framework based on The Elm Architecture"
+  }
+]

config.json

@@ -210,6 +210,22 @@
         ],
         "status": "beta"
       },
+      {
+        "slug": "paulas-palindromes",
+        "name": "Paula's Palindromes",
+        "uuid": "31f9b8d8-701d-4124-8ca1-726f5969661c",
+        "concepts": [
+          "web-applications-sandbox"
+        ],
+        "prerequisites": [
+          "records",
+          "custom-types",
+          "pattern-matching",
+          "lists",
+          "strings"
+        ],
+        "status": "beta"
+      },
       {
         "slug": "monster-attack",
         "name": "Monster Attack",
@@ -1530,6 +1546,11 @@
       "slug": "random",
       "name": "Random"
     },
+    {
+      "uuid": "d3864c81-b7e4-4b42-87d1-aac069ecb839",
+      "slug": "web-applications-sandbox",
+      "name": "Web Applications"
+    },
     {
       "uuid": "afb8dec3-c776-4f46-a6ee-77d30963cf56",
       "slug": "json",

exercises/concept/paulas-palindromes/.docs/hints.md

@@ -0,0 +1,40 @@
+# Hints
+
+## General
+
+- Check out the [Elm Guide][elm-guide], which has a nice worked example that is similar.
+
+## 1. Define the Model and Msg types for the application, and write the init function
+
+- The `Model` contains the application's state - all the data that the application needs.
+- It should be a [record][record].
+- This application just needs a `String` to store the text in the text box (the tests require it to be called `content`).
+
+- The `Msg` type defines the messages that are passed to the `update` function, to trigger specific changes in the model.
+- It should be a [custom type][custom-type].
+- This application only needs one change to the model - updating the model when the text in the text box changes.
+
+- The `init` function should simply return a `Model` with sensible a default value (the tests require an empty string).
+
+## 2. Write the update function
+
+- In any useful application the update function will use a `case` statement to pattern match on the `Msg` parameter.
+- In each branch of the case statement it will extract information it needs from the `Msg` parameter and return an updated `Model`
+- The `Model` should be a record, and [record update syntax][record-update-syntax] is normally used.
+
+## 3. Write the view function
+
+- The `view` function should return a `div` for the root element
+- The first child should be an `input`, with a `value` attribute for the current text, and an `onInput` attribute / event with the relevant variant of the `Msg`.
+- The second child should be another `div` with a `text` child stating whether the text is a palindrome or not.
+
+## 4. Write the main function
+
+- The main function should just call [`Browser.sandbox`][browser-sandbox]
+- `Browser.sandbox` requires a [record][record] argument with the `init`, `update` and `view` functions.
+
+[elm-guide]: https://guide.elm-lang.org/architecture/text_fields
+[record]: https://elm-lang.org/docs/records
+[custom-type]: https://guide.elm-lang.org/types/custom_types.html
+[record-update-syntax]: https://elm-lang.org/docs/records#updating-records
+[browser-sandbox]: https://package.elm-lang.org/packages/elm/browser/latest/Browser#sandbox

exercises/concept/paulas-palindromes/.docs/instructions.md

@@ -0,0 +1,42 @@
+# Instructions
+
+Your friend Paula is trying to get better at solving crossword clues. She has read that [some clues show that the answer is a palindrome][palindrome-crossword-clues].
+A palindrome is a word or sentence that reads the same backards as forwards.
+
+She asks you write her a very simple website that will check whether a string is a palindrome (or not) so that she can check her guesses.
+
+You decide to do this using an Elm [sandbox][browser-sandox] application.
+
+The application will have a text box, that Paula can type her guess into, and text stating whether or not the text in the box is a palindrome.
+The text will update whenever the text in the text box changes.
+
+## 1. Define the `Model` and `Msg` types for the application, and write the `init` function
+
+The application `Model` needs the string to check, this field should be called `content`.
+
+The application needs a `Msg` to indicate that the text in the Text Box has changed.
+The variant for this should be called `Change`
+
+The `init` function should return a initial `Model` value with an empty `content` field.
+
+## 2. Write the update function
+
+The `update` function should take a `Msg` and a `Model` parameter, and return a new `Model`.
+The `Msg` will carry some text typed by the user, and the new `Model` should include that text.
+
+## 3. Write the view function
+
+Elm requires that the view function has to return an `Html msg` type, which means that you need to return a single element from the view function (and not an  array of elements).
+
+Inside this root element, there should be an `input` element (the Text Box), and a `div` with `text` content to state whether the text in the `input` is a palindrome or not.
+
+The text should be "This is a palindrome" or "Not a palindrome".
+
+## 4. Write the main function
+
+The `main` function should call [`Browser.sandbox`][browser-sandbox], passing a record parameter with the `init`, `update` and `view` functions.
+To make the exercise work on the Exercism online editor, we use a fake `Browser.sandbox` with the code.
+This makes no difference to the code that you write to solve this exercise.
+
+[palindrome-crossword-clues]: https://www.theguardian.com/crosswords/crossword-blog/2012/nov/01/cryptic-crosswords-beginners-palindromes
+[browser-sandbox]: https://package.elm-lang.org/packages/elm/browser/latest/Browser#sandbox