Start of a Philosophical Rewrite for Version 1.0.0

.github/workflows/ci.yml

@@ -2,125 +2,78 @@ name: CI
 
 on:
   push:
-    branches: [main]
+    branches:
+      - main
   pull_request:
-    branches: [main]
 
 env:
   MIX_ENV: test
-  OTP_VERSION_SPEC: "26.x"
-  ELIXIR_VERSION_SPEC: "1.16.x"
-
-jobs:
-  compile:
-    name: Compile
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-      - name: Set up Elixir
-        uses: erlef/setup-beam@v1
-        with:
-          otp-version: ${{ env.OTP_VERSION_SPEC }}
-          elixir-version: ${{ env.ELIXIR_VERSION_SPEC }}
-      - name: Install dependencies
-        run: mix deps.get
-      - name: Compile dependencies
-        run: mix deps.compile
-      - name: Compile
-        run: mix compile --warnings-as-errors
 
+jobs:        
   test:
     name: Test
     runs-on: ubuntu-latest
 
+    # Test on the 3 latest Elixir versions with the latest OTP version that each supports
+    strategy:
+      matrix:
+        include:
+          - elixir: 1.16.x
+            otp: 26.x
+
+          - elixir: 1.17.x
+            otp: 27.x
+
+          - elixir: 1.18.x
+            otp: 28.x
+            lint: true
+
     steps:
       - name: Checkout
         uses: actions/checkout@v4
       - name: Set up Elixir
         uses: erlef/setup-beam@v1
         with:
-          otp-version: ${{ env.OTP_VERSION_SPEC }}
-          elixir-version: ${{ env.ELIXIR_VERSION_SPEC }}
+          otp-version: ${{ matrix.otp }}
+          elixir-version: ${{ matrix.elixir }}
+
       - name: Install dependencies
         run: mix deps.get
-      - name: Compile dependencies
-        run: mix deps.compile
+
+      # We only check for warnings on latest Elixir version
+      - name: Compile & lint
+        run: mix compile --warnings-as-errors
+        if: ${{ matrix.lint }}
+
       - name: Run tests
         run: mix test
 
   check-formatted:
     name: Check Formatted
     runs-on: ubuntu-latest
 
+    # Check formatting on the latest Elixir version only
+    strategy:
+      matrix:
+        include:
+          - elixir: 1.18.x
+            otp: 28.x
+
     steps:
       - name: Checkout
         uses: actions/checkout@v4
+
       - name: Set up Elixir
         uses: erlef/setup-beam@v1
         with:
-          otp-version: ${{ env.OTP_VERSION_SPEC }}
-          elixir-version: ${{ env.ELIXIR_VERSION_SPEC }}
+          otp-version: ${{ matrix.otp }}
+          elixir-version: ${{ matrix.elixir }}
+
       - name: Install dependencies
         run: mix deps.get
-      - name: Compile dependencies
-        run: mix deps.compile
-      - name: Check formatted
-        run: mix format --check-formatted
-
-  # credo:
-  #   name: Credo
-  #   runs-on: ubuntu-latest
-
-  #   steps:
-  #     - name: Checkout
-  #       uses: actions/checkout@v4
-  #     - name: Set up Elixir
-  #       uses: erlef/setup-beam@v1
-  #       with:
-  #         otp-version: ${{ env.OTP_VERSION_SPEC }}
-  #         elixir-version: ${{ env.ELIXIR_VERSION_SPEC }}
-  #     - name: Install dependencies
-  #       run: mix deps.get
-  #     - name: Compile dependencies
-  #       run: mix deps.compile
-  #     - name: Run credo
-  #       run: mix credo --strict
-
-  # dialyzer:
-  #   name: Dialyzer
-  #   runs-on: ubuntu-latest
 
-  #   env:
-  #     MIX_ENV: dev
+      - name: Compile
+        run: mix compile
 
-  #   steps:
-  #     - name: Checkout
-  #       uses: actions/checkout@v4
-  #     - name: Set mix file hash
-  #       id: set_vars
-  #       run: |
-  #         mix_hash="${{ hashFiles(format('{0}{1}', github.workspace, '/mix.lock')) }}"
-  #         echo "::set-output name=mix_hash::$mix_hash"
-  #     - name: Cache PLT files
-  #       id: cache-plt
-  #       uses: actions/cache@v4
-  #       with:
-  #         path: |
-  #           _build/dev/*.plt
-  #           _build/dev/*.plt.hash
-  #         key: plt-cache-${{ steps.set_vars.outputs.mix_hash }}
-  #         restore-keys: |
-  #           plt-cache-
-  #     - name: Set up Elixir
-  #       uses: erlef/setup-beam@v1
-  #       with:
-  #         otp-version: ${{ env.OTP_VERSION_SPEC }}
-  #         elixir-version: ${{ env.ELIXIR_VERSION_SPEC }}
-  #     - name: Install dependencies
-  #       run: mix deps.get
-  #     - name: Compile dependencies
-  #       run: mix deps.compile
-  #     - name: Run dialyzer
-  #       run: mix dialyzer
+      - name: Check formatted
+        run: mix format --check-formatted

README.md

@@ -15,7 +15,7 @@ installed by adding `plox` to your list of dependencies in `mix.exs`:
 ```elixir
 def deps do
   [
-    {:plox, "~> 0.1.0"}
+    {:plox, "~> 0.2.0"}
   ]
 end
 ```
@@ -27,7 +27,7 @@ Documentation is published on [HexDocs](https://hexdocs.pm) and can be found at
 
 <img width="740" src="images/readme-example-plot@2x.png" alt="Example screenshot">
 
-Start by setting up your data, scales, and dataset:
+Start by setting up your data, dimensions, axes, and dataset:
 
 ```elixir
 data = [
@@ -38,44 +38,39 @@ data = [
   %{date: ~D[2023-08-05], value: 50.0}
 ]
 
-date_scale = date_scale(Date.range(~D[2023-08-01], ~D[2023-08-05]))
-number_scale = number_scale(0.0, 80.0)
+dimensions = Plox.Dimensions.new(800, 250)
 
-dataset =
-  dataset(data,
-    x: {date_scale, & &1.date},
-    y: {number_scale, & &1.value}
-  )
-```
+x_axis = Plox.XAxis.new(
+  Plox.DateScale.new(Date.range(~D[2023-08-01], ~D[2023-08-05])),
+  dimensions
+)
 
-Once you have those, you can build a `Plox.Graph` struct:
+y_axis = Plox.YAxis.new(Plox.NumberScale.new(0.0, 80.0), dimensions)
 
-```elixir
-example_graph =
-  to_graph(
-    scales: [date_scale: date_scale, number_scale: number_scale],
-    datasets: [dataset: dataset]
+dataset =
+  Plox.Dataset.new(data,
+    x: {x_axis, & &1.date},
+    y: {y_axis, & &1.value}
   )
 ```
 
-Finally, render the `Plox.Graph` directly within your HEEx template:
+Once you have those, you can render a `graph` component within your HEEx template:
 
 ```html
-<.graph :let={graph} id="example_graph" for={@example_graph} width="800" height="250">
-  <:legend>
-    <.legend_item color="#EC7E16" label="Data" />
-  </:legend>
+<.graph id="example_graph" dimensions={@dimensions}>
+  <.x_axis_labels :let={date} axis={@x_axis}>
+    {Calendar.strftime(date, "%-m/%-d")}
+  </.x_axis_labels>
 
-  <.x_axis :let={date} scale={graph[:date_scale]}>
-    <%= Calendar.strftime(date, "%-m/%-d") %>
-  </.x_axis>
+  <.y_axis_labels :let={value} axis={@y_axis} ticks={5}>
+    {value}
+  </.y_axis_labels>
 
-  <.y_axis :let={value} scale={graph[:number_scale]} ticks={5}>
-    <%= value %>
-  </.y_axis>
+  <.x_axis_grid_lines axis={@x_axis} stroke="#D3D3D3" />
+  <.y_axis_grid_lines axis={@y_axis} ticks={5} stroke="#D3D3D3" />
 
-  <.line_plot dataset={graph[:dataset]} color="#EC7E16" />
+  <.polyline points={points(@dataset[:x], @dataset[:y])} stroke="#EC7E16" stroke-width={2} />
 
-  <.points_plot dataset={graph[:dataset]} color="#EC7E16" />
+  <.circle cx={@dataset[:x]} cy={@dataset[:y]} r={3} fill="#EC7E16" />
 </.graph>
 ```

docs/migration_guide.md

@@ -0,0 +1,112 @@
+# Plox Migration Guide (0.2.0 to X.X.X)
+
+Plox has gone through a major philosophical rewrite since its initial publication. This
+guide will help users convert their current Plox graphs over to the new approach.
+
+## Example of 0.2.0 usage
+
+1. Set up data, scales, and dataset:
+
+```elixir
+data = [
+  %{date: ~D[2023-08-01], value: 35.0},
+  %{date: ~D[2023-08-02], value: 60.0},
+  %{date: ~D[2023-08-03], value: 65.0},
+  %{date: ~D[2023-08-04], value: 10.0},
+  %{date: ~D[2023-08-05], value: 50.0}
+]
+
+date_scale = date_scale(Date.range(~D[2023-08-01], ~D[2023-08-05]))
+number_scale = number_scale(0.0, 80.0)
+
+dataset =
+  dataset(data,
+    x: {date_scale, & &1.date},
+    y: {number_scale, & &1.value}
+  )
+```
+
+2. Build a `Plox.Graph` struct:
+
+```elixir
+example_graph =
+  to_graph(
+    scales: [date_scale: date_scale, number_scale: number_scale],
+    datasets: [dataset: dataset]
+  )
+```
+
+3. Render the `Plox.Graph` within your HEEx template:
+
+```html
+<.graph :let={graph} id="example_graph" for={@example_graph} width="800" height="250">
+  <.x_axis :let={date} scale={graph[:date_scale]}>
+    {Calendar.strftime(date, "%-m/%-d")}
+  </.x_axis>
+
+  <.y_axis :let={value} scale={graph[:number_scale]} ticks={5}>
+    {value}
+  </.y_axis>
+
+  <.line_plot dataset={graph[:dataset]} color="#EC7E16" />
+
+  <.points_plot dataset={graph[:dataset]} color="#EC7E16" />
+</.graph>
+```
+
+## Example of X.X.X usage
+
+1. Set up data, dimensions, axes, and dataset:
+
+```elixir
+data = [
+  %{date: ~D[2023-08-01], value: 35.0},
+  %{date: ~D[2023-08-02], value: 60.0},
+  %{date: ~D[2023-08-03], value: 65.0},
+  %{date: ~D[2023-08-04], value: 10.0},
+  %{date: ~D[2023-08-05], value: 50.0}
+]
+
+# Instead of passing the height and width via the `graph` component,
+# create Dimensions and pass them to each Axis
+dimensions = Plox.Dimensions.new(800, 250)
+
+# Instead of creating separate Scales, we need them when creating our Axes
+x_axis = Plox.XAxis.new(
+  Plox.DateScale.new(Date.range(~D[2023-08-01], ~D[2023-08-05])),
+  dimensions
+)
+
+y_axis = Plox.YAxis.new(Plox.NumberScale.new(0.0, 80.0), dimensions)
+
+# Create a Dataset with our Axes
+dataset =
+  Plox.Dataset.new(data,
+    x: {x_axis, & &1.date},
+    y: {y_axis, & &1.value}
+  )
+```
+
+2. Render the `graph` component within your HEEx template:
+
+```html
+<.graph id="example_graph" dimensions={@dimensions}>
+  <!-- Render axis labels and lines individually -->
+  <.x_axis_labels :let={date} axis={@x_axis}>
+    {Calendar.strftime(date, "%-m/%-d")}
+  </.x_axis_labels>
+
+  <.y_axis_labels :let={value} axis={@y_axis} ticks={5}>
+    {value}
+  </.y_axis_labels>
+
+  <.x_axis_grid_lines axis={@x_axis} stroke="#D3D3D3" />
+  <.y_axis_grid_lines axis={@y_axis} ticks={5} stroke="#D3D3D3" />
+
+  <!-- Use the `points/2` helper to generate a list of {x, y} tuples from our Dataset -->
+  <.polyline points={points(@dataset[:x], @dataset[:y])} stroke="#EC7E16" stroke-width={2} />
+
+  <!-- Pass all the `x` values and the `y` values to render circles at each datapoint -->
+  <.circle cx={@dataset[:x]} cy={@dataset[:y]} r={3} fill="#EC7E16" />
+</.graph>
+```