Add new concept time and concept exercise kurokos-clock (#748)

* add concept

* add exercise

* add practice exercises

* Apply suggestions from code review

* Apply suggestions from code review

Co-authored-by: Cedd Burge <[email protected]>

* mention time manipulation packages in the intro

* expand date format explanation

* add link to elm-time-format

* add introduction

* bin/configlet fmt --update

---------

Co-authored-by: Cedd Burge <[email protected]>

Author: jiegillet

bin/generate_concept_exercise.sh

@@ -22,7 +22,7 @@ echo "Fetching latest version of configlet..."
 echo "Adding configuration files..."
 UUID=$(bin/configlet uuid)
 jq --arg slug "$CONCEPT_SLUG" --arg uuid "$UUID" \
-    '.concepts += [{slug: $slug, name: "Write name from slug", uuid: $uuid }]' \
+    '.concepts += [{uuid: $uuid, slug: $slug, name: "Write name from slug" }]' \
     config.json > config.json.tmp
 mv config.json.tmp config.json
 

concepts/time/.meta/config.json

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

concepts/time/about.md

@@ -0,0 +1,56 @@
+# About
+
+The `Time` module is used to display human-readable dates / times.
+While it's technically possibly to manipulate times with `Time`, there are Elm community packages that are far more suited to the task, such as [`justinmimbs/date`][date] or [`CoderDennis/elm-time-format`][elm-time-format].
+
+## Posix
+
+Times are represented by the opaque type `Posix`, which wraps Unix epoch time, the number of milliseconds passed since January 1st, 1970 at midnight UTC.
+A `Posix` is an non-ambiguous value that does not vary between time zones, therefore a good choice for keeping time.
+In an Elm application, `Posix` times will typically be provided by external sources, such as the browser.
+
+It is possible to transform a `Posix` into a number of millisecond and vice-versa with the following functions:
+
+```elm
+posixToMillis : Posix -> Int
+millisToPosix : Int -> Posix
+```
+
+## Time Zones
+
+In our day-to-day lives, we humans usually don't read `Posix` and instead prefer local time, which depends on our location on Earth, and local daylight-saving rules.
+In Elm, this information is encoded in the opaque type `Zone`, usually provided by the browser.
+
+There is a special `Zone` that is always accessible:
+
+```elm
+utc : Zone
+```
+
+## Human times
+
+With a `Posix` and a `Zone`, we have enough information to show local time in any level of details.
+Here is a list of the functions that can be used for that:
+
+```elm
+toYear : Zone -> Posix -> Int
+toMonth : Zone -> Posix -> Month
+toDay : Zone -> Posix -> Int
+toWeekday : Zone -> Posix -> Weekday
+toHour : Zone -> Posix -> Int
+toMinute : Zone -> Posix -> Int
+toSecond : Zone -> Posix -> Int
+toMillis : Zone -> Posix -> Int
+```
+
+You will have spotted two more `Time` custom types:
+
+```elm
+type Month = Jan | Feb | Mar | Apr | May | Jun | Jul | Aug | Sep | Oct | Nov | Dec
+type Weekday = Mon | Tue | Wed | Thu | Fri | Sat | Sun
+```
+
+It is left to users to convert these custom types to human-readable values.
+
+[date]: https://package.elm-lang.org/packages/justinmimbs/date/latest
+[elm-time-format]: https://package.elm-lang.org/packages/CoderDennis/elm-time-format/latest

concepts/time/introduction.md

@@ -0,0 +1,56 @@
+# Introduction
+
+The `Time` module is used to display human-readable dates / times.
+While it's technically possibly to manipulate times with `Time`, there are Elm community packages that are far more suited to the task, such as [`justinmimbs/date`][date] or [`CoderDennis/elm-time-format`][elm-time-format].
+
+## Posix
+
+Times are represented by the opaque type `Posix`, which wraps Unix epoch time, the number of milliseconds passed since January 1st, 1970 at midnight UTC.
+A `Posix` is an non-ambiguous value that does not vary between time zones, therefore a good choice for keeping time.
+In an Elm application, `Posix` times will typically be provided by external sources, such as the browser.
+
+It is possible to transform a `Posix` into a number of millisecond and vice-versa with the following functions:
+
+```elm
+posixToMillis : Posix -> Int
+millisToPosix : Int -> Posix
+```
+
+## Time Zones
+
+In our day-to-day lives, we humans usually don't read `Posix` and instead prefer local time, which depends on our location on Earth, and local daylight-saving rules.
+In Elm, this information is encoded in the opaque type `Zone`, usually provided by the browser.
+
+There is a special `Zone` that is always accessible:
+
+```elm
+utc : Zone
+```
+
+## Human times
+
+With a `Posix` and a `Zone`, we have enough information to show local time in any level of details.
+Here is a list of the functions that can be used for that:
+
+```elm
+toYear : Zone -> Posix -> Int
+toMonth : Zone -> Posix -> Month
+toDay : Zone -> Posix -> Int
+toWeekday : Zone -> Posix -> Weekday
+toHour : Zone -> Posix -> Int
+toMinute : Zone -> Posix -> Int
+toSecond : Zone -> Posix -> Int
+toMillis : Zone -> Posix -> Int
+```
+
+You will have spotted two more `Time` custom types:
+
+```elm
+type Month = Jan | Feb | Mar | Apr | May | Jun | Jul | Aug | Sep | Oct | Nov | Dec
+type Weekday = Mon | Tue | Wed | Thu | Fri | Sat | Sun
+```
+
+It is left to users to convert these custom types to human-readable values.
+
+[date]: https://package.elm-lang.org/packages/justinmimbs/date/latest
+[elm-time-format]: https://package.elm-lang.org/packages/CoderDennis/elm-time-format/latest

concepts/time/links.json

@@ -0,0 +1,26 @@
+[
+  {
+    "url": "https://guide.elm-lang.org/effects/time",
+    "description": "Official guide about using time in an Elm application"
+  },
+  {
+    "url": "https://package.elm-lang.org/packages/elm/time/latest/",
+    "description": "Documentation of the Time module"
+  },
+  {
+    "url": "https://package.elm-lang.org/packages/justinmimbs/date/latest/",
+    "description": "Community package for working with dates without times or zones."
+  },
+  {
+    "url": "https://package.elm-lang.org/packages/waratuman/time-extra/latest/",
+    "description": "Community package for manipulating Posix types."
+  },
+  {
+    "url": "https://package.elm-lang.org/packages/CoderDennis/elm-time-format/latest/",
+    "description": "Community package for formatting dates and times with support for internationalization."
+  },
+  {
+    "url": "https://package.elm-lang.org/packages/rtfeldman/elm-iso8601-date-strings/latest/",
+    "description": "Community package for parsing and rendering ISO-8601 date strings."
+  }
+]

config.json

@@ -388,6 +388,20 @@
           "pattern-matching"
         ],
         "status": "beta"
+      },
+      {
+        "slug": "kurokos-clock",
+        "name": "Kuroko's Clock",
+        "uuid": "5fd8037b-df05-4e14-90e1-70f52487d14c",
+        "concepts": [
+          "time"
+        ],
+        "prerequisites": [
+          "strings",
+          "custom-types",
+          "pattern-matching"
+        ],
+        "status": "beta"
       }
     ],
     "practice": [
@@ -1031,16 +1045,14 @@
         "name": "Gigasecond",
         "uuid": "5ddfed31-b787-48f9-b3bf-4a8d157d1c3d",
         "practices": [
-          "basics-1"
+          "time"
         ],
         "prerequisites": [
           "basics-1",
-          "basics-2"
+          "basics-2",
+          "time"
         ],
-        "difficulty": 1,
-        "topics": [
-          "dates"
-        ]
+        "difficulty": 1
       },
       {
         "slug": "rna-transcription",
@@ -1534,8 +1546,11 @@
         "slug": "swift-scheduling",
         "name": "Swift Scheduling",
         "uuid": "d0438147-3983-47bf-a4db-27fb0f5ae90e",
-        "practices": [],
+        "practices": [
+          "time"
+        ],
         "prerequisites": [
+          "time",
           "strings",
           "records",
           "custom-types",
@@ -1675,6 +1690,11 @@
       "uuid": "afb8dec3-c776-4f46-a6ee-77d30963cf56",
       "slug": "json",
       "name": "JSON"
+    },
+    {
+      "uuid": "9dbfbc83-7e02-4ab4-867a-52ecd2276566",
+      "slug": "time",
+      "name": "Time"
     }
   ],
   "key_features": [

exercises/concept/kurokos-clock/.docs/hints.md

@@ -0,0 +1,34 @@
+# Hints
+
+## General
+
+- Check out the [`elm/time` documentation][elm-time] for working with dates and times
+- The introduction showcases most of the necessary concepts to solve the exercise
+
+## 1. It's a date
+
+- The [`String.fromInt` function][fromInt] can convert numbers to strings
+- You'll need to convert months to their numeric representation, consider creating a helper function
+- For the Japanese locale, you can copy paste the characters from the instructions (年, 月, 日), the numbers should not be formatted in a Japanese encoding
+
+## 2. It's show time
+
+- The [`modBy` function][modBy] can help with hour conversion
+- Use [`String.padLeft`][padLeft] to ensure minutes have leading zeros
+- For the Japanese locale, you can copy paste the characters from the instructions (時, 分), the numbers should not be formatted in a Japanese encoding
+
+## 3. Get in the zone
+
+- [`Time.toYear`][toYear], [`Time.toMonth`][toMonth], [`Time.toDay`][toDay] can help get date parts
+- [`Time.toHour`][toHour] and [`Time.toMinute`][toMinute] can help get time parts
+- Combine the results from `showLocalDate` and `showLocalTime`
+
+[elm-time]: https://package.elm-lang.org/packages/elm/time/latest/
+[fromInt]: https://package.elm-lang.org/packages/elm/core/latest/String#fromInt
+[modBy]: https://package.elm-lang.org/packages/elm/core/latest/Basics#modBy
+[padLeft]: https://package.elm-lang.org/packages/elm/core/latest/String#padLeft
+[toYear]: https://package.elm-lang.org/packages/elm/time/latest/Time#toYear
+[toMonth]: https://package.elm-lang.org/packages/elm/time/latest/Time#toMonth
+[toDay]: https://package.elm-lang.org/packages/elm/time/latest/Time#toDay
+[toHour]: https://package.elm-lang.org/packages/elm/time/latest/Time#toHour
+[toMinute]: https://package.elm-lang.org/packages/elm/time/latest/Time#toMinute

exercises/concept/kurokos-clock/.docs/instructions.md

@@ -0,0 +1,50 @@
+# Instructions
+
+Your Japanese friend Kuroko is a streamer with an international appeal.
+Kuroko's streaming schedule is pretty intricate, each stream seemingly starts at a different time every day.
+
+He asks for your help in building a small application that will display his schedule in his viewers' local time zones: Kuroko's Clock.
+He has an additional requirement: the app should be able to display the time in two different languages: Japanese and US English.
+
+## 1. It's a date
+
+Define a function `showLocalDate : Locale -> Int -> Month -> Int -> String` which will display a (valid) local date.
+
+In the `US` locale, the format will be `Month/Day/Year` without leading zeroes.
+
+In the `JP` locale, the format will be `Year年Month月Day日`, also without leading zeroes.
+
+```elm
+showLocalDate US 2025 May 1
+    -- "5/1/2025"
+showLocalDate JP 2025 May 1
+    -- "2025年5月1日"
+```
+
+## 2. It's show time
+
+Define a function `showLocalTime : Locale -> Int -> Int -> String` which will display a (valid) local time.
+
+In the `US` locale, the hours will be shown in 12-hour notation along with "PM" or "AM", and the minutes will be shown with leading zeros.
+
+In the `JP` locale, the hour will be shown in 24-hour notation before "時" and the minutes will be shown without leading zeros before "分".
+
+```elm
+showLocalTime US 13 8
+    -- "1:08 PM"
+showLocalTime JP 13 8
+    -- "13時8分"
+```
+
+## 3. Get in the zone
+
+Define a function `showDateTime : Locale -> Zone -> Posix -> String` which will display a date and time relative to a time zone in a specific locale.
+
+Use `showLocalDate` and `showLocalTime` to display the final result.
+
+```elm
+showDateTime US Time.utc (Time.millisToPosix 0)
+    -- "1/1/1970 12:00 AM"
+showDateTime JP Time.utc (Time.millisToPosix 0)
+    -- "1970年1月1日0時0分"
+```

exercises/concept/kurokos-clock/.docs/introduction.md

@@ -0,0 +1,58 @@
+# Introduction
+
+## Time
+
+The `Time` module is used to display human-readable dates / times.
+While it's technically possibly to manipulate times with `Time`, there are Elm community packages that are far more suited to the task, such as [`justinmimbs/date`][date] or [`CoderDennis/elm-time-format`][elm-time-format].
+
+### Posix
+
+Times are represented by the opaque type `Posix`, which wraps Unix epoch time, the number of milliseconds passed since January 1st, 1970 at midnight UTC.
+A `Posix` is an non-ambiguous value that does not vary between time zones, therefore a good choice for keeping time.
+In an Elm application, `Posix` times will typically be provided by external sources, such as the browser.
+
+It is possible to transform a `Posix` into a number of millisecond and vice-versa with the following functions:
+
+```elm
+posixToMillis : Posix -> Int
+millisToPosix : Int -> Posix
+```
+
+### Time Zones
+
+In our day-to-day lives, we humans usually don't read `Posix` and instead prefer local time, which depends on our location on Earth, and local daylight-saving rules.
+In Elm, this information is encoded in the opaque type `Zone`, usually provided by the browser.
+
+There is a special `Zone` that is always accessible:
+
+```elm
+utc : Zone
+```
+
+### Human times
+
+With a `Posix` and a `Zone`, we have enough information to show local time in any level of details.
+Here is a list of the functions that can be used for that:
+
+```elm
+toYear : Zone -> Posix -> Int
+toMonth : Zone -> Posix -> Month
+toDay : Zone -> Posix -> Int
+toWeekday : Zone -> Posix -> Weekday
+toHour : Zone -> Posix -> Int
+toMinute : Zone -> Posix -> Int
+toSecond : Zone -> Posix -> Int
+toMillis : Zone -> Posix -> Int
+```
+
+You will have spotted two more `Time` custom types:
+
+```elm
+type Month = Jan | Feb | Mar | Apr | May | Jun | Jul | Aug | Sep | Oct | Nov | Dec
+type Weekday = Mon | Tue | Wed | Thu | Fri | Sat | Sun
+```
+
+It is left to users to convert these custom types to human-readable values.
+
+[date]: https://package.elm-lang.org/packages/justinmimbs/date/latest
+[elm-time-format]: https://package.elm-lang.org/packages/CoderDennis/elm-time-format/latest

exercises/concept/kurokos-clock/.docs/introduction.md.tpl

@@ -0,0 +1,3 @@
+# Introduction
+
+%{concept: time}