feat: add elm-pages documentation site

.github/workflows/docs.yml

@@ -0,0 +1,49 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'apps/docs/**'
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: 'pages'
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'pnpm'
+
+      - run: pnpm install --frozen-lockfile
+
+      - name: Build docs site
+        run: pnpm --filter docs-site build
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: apps/docs/dist
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -12,3 +12,4 @@ packged/
 out-tsc/
 .direnv/
 .corepack/
+.worktrees/

apps/docs/.gitignore

@@ -0,0 +1,5 @@
+node_modules/
+elm-stuff/
+dist/
+.elm-pages/
+functions/

apps/docs/README.md

@@ -0,0 +1 @@
+# README

apps/docs/app/Api.elm

@@ -0,0 +1,26 @@
+module Api exposing (routes)
+
+import ApiRoute exposing (ApiRoute)
+import BackendTask exposing (BackendTask)
+import FatalError exposing (FatalError)
+import Html exposing (Html)
+import Pages.Manifest as Manifest
+import Route exposing (Route)
+
+
+routes :
+    BackendTask FatalError (List Route)
+    -> (Maybe { indent : Int, newLines : Bool } -> Html Never -> String)
+    -> List (ApiRoute ApiRoute.Response)
+routes getStaticRoutes htmlToString =
+    []
+
+
+manifest : Manifest.Config
+manifest =
+    Manifest.init
+        { name = "Site Name"
+        , description = "Description"
+        , startUrl = Route.Index |> Route.toPath
+        , icons = []
+        }

apps/docs/app/Effect.elm

@@ -0,0 +1,190 @@
+module Effect exposing (Effect(..), batch, fromCmd, map, none, perform, testPerform)
+
+{-|
+
+@docs Effect, batch, fromCmd, map, none, perform, testPerform
+
+-}
+
+import Browser.Navigation
+import Form
+import Http
+import Json.Decode as Decode
+import Pages.Fetcher
+import Test.PagesProgram.SimulatedEffect as SimulatedEffect exposing (SimulatedEffect)
+import Url exposing (Url)
+
+
+{-| -}
+type Effect msg
+    = None
+    | Cmd (Cmd msg)
+    | Batch (List (Effect msg))
+    | GetStargazers (Result Http.Error Int -> msg)
+    | SetField { formId : String, name : String, value : String }
+    | FetchRouteData
+        { data : Maybe FormData
+        , toMsg : Result Http.Error Url -> msg
+        }
+    | Submit
+        { values : FormData
+        , toMsg : Result Http.Error Url -> msg
+        }
+    | SubmitFetcher (Pages.Fetcher.Fetcher msg)
+
+
+{-| -}
+type alias RequestInfo =
+    { contentType : String
+    , body : String
+    }
+
+
+{-| -}
+none : Effect msg
+none =
+    None
+
+
+{-| -}
+batch : List (Effect msg) -> Effect msg
+batch =
+    Batch
+
+
+{-| -}
+fromCmd : Cmd msg -> Effect msg
+fromCmd =
+    Cmd
+
+
+{-| -}
+map : (a -> b) -> Effect a -> Effect b
+map fn effect =
+    case effect of
+        None ->
+            None
+
+        Cmd cmd ->
+            Cmd (Cmd.map fn cmd)
+
+        Batch list ->
+            Batch (List.map (map fn) list)
+
+        GetStargazers toMsg ->
+            GetStargazers (toMsg >> fn)
+
+        FetchRouteData fetchInfo ->
+            FetchRouteData
+                { data = fetchInfo.data
+                , toMsg = fetchInfo.toMsg >> fn
+                }
+
+        Submit fetchInfo ->
+            Submit
+                { values = fetchInfo.values
+                , toMsg = fetchInfo.toMsg >> fn
+                }
+
+        SetField info ->
+            SetField info
+
+        SubmitFetcher fetcher ->
+            fetcher
+                |> Pages.Fetcher.map fn
+                |> SubmitFetcher
+
+
+{-| -}
+perform :
+    { fetchRouteData :
+        { data : Maybe FormData
+        , toMsg : Result Http.Error Url -> pageMsg
+        }
+        -> Cmd msg
+    , submit :
+        { values : FormData
+        , toMsg : Result Http.Error Url -> pageMsg
+        }
+        -> Cmd msg
+    , runFetcher :
+        Pages.Fetcher.Fetcher pageMsg
+        -> Cmd msg
+    , fromPageMsg : pageMsg -> msg
+    , key : Browser.Navigation.Key
+    , setField : { formId : String, name : String, value : String } -> Cmd msg
+    }
+    -> Effect pageMsg
+    -> Cmd msg
+perform ({ fromPageMsg, key } as helpers) effect =
+    case effect of
+        None ->
+            Cmd.none
+
+        Cmd cmd ->
+            Cmd.map fromPageMsg cmd
+
+        SetField info ->
+            helpers.setField info
+
+        Batch list ->
+            Cmd.batch (List.map (perform helpers) list)
+
+        GetStargazers toMsg ->
+            Http.get
+                { url =
+                    "https://api.github.com/repos/dillonkearns/elm-pages"
+                , expect = Http.expectJson (toMsg >> fromPageMsg) (Decode.field "stargazers_count" Decode.int)
+                }
+
+        FetchRouteData fetchInfo ->
+            helpers.fetchRouteData
+                fetchInfo
+
+        Submit record ->
+            helpers.submit record
+
+        SubmitFetcher record ->
+            helpers.runFetcher record
+
+
+{-| Decompose an Effect into a SimulatedEffect for the test framework.
+Maintain this function alongside `perform` when adding custom Effect variants.
+-}
+testPerform : Effect msg -> SimulatedEffect msg
+testPerform effect =
+    case effect of
+        None ->
+            SimulatedEffect.none
+
+        Cmd _ ->
+            SimulatedEffect.none
+
+        Batch list ->
+            SimulatedEffect.batch (List.map testPerform list)
+
+        GetStargazers toMsg ->
+            -- In tests, provide a mock value for the stargazers count.
+            -- Alternatively, return SimulatedEffect.none and use
+            -- PagesProgram.simulateMsg to provide the result manually.
+            SimulatedEffect.dispatchMsg (toMsg (Ok 0))
+
+        SetField info ->
+            SimulatedEffect.setField info
+
+        FetchRouteData _ ->
+            SimulatedEffect.none
+
+        Submit _ ->
+            SimulatedEffect.none
+
+        SubmitFetcher fetcher ->
+            SimulatedEffect.submitFetcher fetcher
+
+
+type alias FormData =
+    { fields : List ( String, String )
+    , method : Form.Method
+    , action : String
+    , id : Maybe String
+    }

apps/docs/app/ErrorPage.elm

@@ -0,0 +1,84 @@
+module ErrorPage exposing (ErrorPage(..), Model, Msg, head, init, internalError, notFound, statusCode, update, view)
+
+import Effect exposing (Effect)
+import Head
+import Html exposing (Html)
+import View exposing (View)
+
+
+type Msg
+    = Increment
+
+
+type alias Model =
+    { count : Int
+    }
+
+
+init : ErrorPage -> ( Model, Effect Msg )
+init errorPage =
+    ( { count = 0 }
+    , Effect.none
+    )
+
+
+update : ErrorPage -> Msg -> Model -> ( Model, Effect Msg )
+update errorPage msg model =
+    case msg of
+        Increment ->
+            ( { model | count = model.count + 1 }, Effect.none )
+
+
+head : ErrorPage -> List Head.Tag
+head errorPage =
+    []
+
+
+type ErrorPage
+    = NotFound
+    | InternalError String
+
+
+notFound : ErrorPage
+notFound =
+    NotFound
+
+
+internalError : String -> ErrorPage
+internalError =
+    InternalError
+
+
+view : ErrorPage -> Model -> View Msg
+view error model =
+    { body =
+        [ Html.div []
+            [ Html.p []
+                [ Html.text <|
+                    case error of
+                        NotFound ->
+                            "Page not found. Maybe try another URL?"
+
+                        InternalError string ->
+                            "Something went wrong.\n" ++ string
+                ]
+            ]
+        ]
+    , title =
+        case error of
+            NotFound ->
+                "Page Not Found"
+
+            InternalError string ->
+                "Unexpected Error"
+    }
+
+
+statusCode : ErrorPage -> number
+statusCode error =
+    case error of
+        NotFound ->
+            404
+
+        InternalError _ ->
+            500