Improve docs & readme & small refactor

README.md

@@ -2,9 +2,13 @@
 
 [Heroicons](https://github.com/tailwindlabs/heroicons) are "a set of free MIT-licensed high-quality SVG icons for you to use in your web projects". This package gives you Elixir functions to drop Heroicons into your HTML, styled with arbitrary classes.
 
+This library provides optimized svgs for each Heroicon packaged as a Phoenix Component (and as a function for backwards-compatibility).
+
+In order to provide the best balance of fast compilation times and run-time performance, Phoenix Components are just-in-time compiled on first use and then cached in an ETS-backed cache.
+
 Heroicons are designed by [Steve Schoger](https://twitter.com/steveschoger)
 
-Current Heroicons Version: **2.0.0**
+Current Heroicons Version: **2.0.10**. It's possible to configure a different Heroicon version locally, see [mix heroicons.update](https://hexdocs.pm/heroicons/Mix.Tasks.Heroicons.Update.html)
 
 ## Installation
 
@@ -31,7 +35,7 @@ The components are in `Heroicons.Solid`, `Heroicons.Outline`, and `Heroicons.Min
 and style it with some classes
 
 ```eex
-<Heroicons.Solid.cake class="h-6 w-6 text-gray-500" />
+<Heroicons.Solid.cake class="w-6 h-6 text-gray-500" />
 ```
 
 There are also function versions of each component:

lib/heroicons.ex

@@ -1,26 +1,34 @@
 defmodule Heroicons do
+  @latest_version "2.0.10"
+
   @moduledoc """
   This library provides Phoenix Components for every [Heroicon](https://github.com/tailwindlabs/heroicons).
-  See `Heroicons.Outline` and `Heroicons.Solid` for the two styles of icon.
+  See `Heroicons.Outline`, `Heroicons.Solid` and `Heroicons.Mini` for the three styles of icon.
 
   ## Examples
-      <Heroicons.Outline.adjustments />
+      <Heroicons.Outline.adjustments_vertical />
 
-      <Heroicons.Solid.arrow_circle_right class="w-6 h-6" />
+      <Heroicons.Solid.arrow_right_circle class="w-6 h-6" />
+
+      <Heroicons.Mini.bell class="w-4 h-4" />
 
   Can also be used as a function
 
-      <%= Heroicons.Outline.adjustments() %>
+      <%= Heroicons.Outline.adjustments_vertical() %>
 
-      <%= Heroicons.Solid.arrow_circle_right(class: "w-6 h-6") />
+      <%= Heroicons.Solid.arrow_right_circle(class: "w-6 h-6") />
+
+      <%= Heroicons.Mini.bell(class: "w-4 h-4") />
+
+
+  This library comes pre-packaged with the icons from Heroicons version `#{@latest_version}`,
+  but can be locally configured and updated. See `Mix.Tasks.Heroicons.Update` for details
 
   Heroicons are designed by [Steve Schoger](https://twitter.com/steveschoger)
   """
 
   # https://github.com/tailwindlabs/heroicons/releases
 
-  @latest_version "2.0.10"
-
   @tmp_dir_name "heroicons-elixir"
   use Application
   require Logger
@@ -28,7 +36,7 @@ defmodule Heroicons do
   @doc false
   def start(_type, _args) do
     children = [
-      {Heroicons.IconCache, []}
+      {Heroicons.Cache, []}
     ]
 
     opts = [strategy: :one_for_one, name: Heroicons.Supervisor]

lib/heroicons/cache.ex

@@ -1,11 +1,18 @@
-defmodule Heroicons.IconCache do
-  @doc "Get's an icon's body from the filesystem"
+defmodule Heroicons.Cache do
+  @moduledoc """
+  An ETS-backed cache for icons. We cache both pre-compiled Phoenix Components and icon bodies as strings.
+
+  Uses the icon's path on disk as a key.
+  """
+
   use GenServer
 
   @name __MODULE__
 
+  @doc false
   def start_link(_), do: GenServer.start_link(__MODULE__, [], name: @name)
 
+  @doc "Fetch a pre-compiled Phoenix Component from the cache or disk, given a `path`"
   def fetch_component(path) do
     case :ets.lookup(@name.Components, path) do
       [{^path, component}] ->
@@ -16,6 +23,7 @@ defmodule Heroicons.IconCache do
     end
   end
 
+  @doc "Fetch a icon's body from the cache or disk, given a `path`"
   def fetch_body(path) do
     case :ets.lookup(@name, path) do
       [{^path, body}] ->
@@ -26,6 +34,7 @@ defmodule Heroicons.IconCache do
     end
   end
 
+  @impl true
   def init(_) do
     :ets.new(@name, [:set, :protected, :named_table])
     :ets.new(@name.Components, [:set, :protected, :named_table])
@@ -33,6 +42,7 @@ defmodule Heroicons.IconCache do
     {:ok, []}
   end
 
+  @impl true
   def handle_call({:cache_body, path}, _ref, state) do
     body = read_body(path)
 

lib/heroicons/generator.ex

@@ -1,4 +1,5 @@
 defmodule Heroicons.Generator do
+  @moduledoc false
   defmacro __using__(icon_dir: icon_dir) do
     icon_paths =
       Path.absname(icon_dir, :code.priv_dir(:heroicons))
@@ -73,7 +74,7 @@ defmodule Heroicons.Generator do
 
     {component, _binding} =
       Code.eval_quoted(
-        Heroicons.IconCache.fetch_component(path),
+        Heroicons.Cache.fetch_component(path),
         assigns: assigns
       )
 
@@ -97,7 +98,7 @@ defmodule Heroicons.Generator do
        "<svg",
        Phoenix.HTML.Safe.to_iodata(attrs),
        " ",
-       Heroicons.IconCache.fetch_body(path)
+       Heroicons.Cache.fetch_body(path)
      ]}
   end
 end

lib/heroicons/outline.ex

@@ -1,7 +1,6 @@
 defmodule Heroicons.Outline do
   @moduledoc """
   Outline style icons drawn with a stroke, packaged as Phoenix Components.
-
   For primary navigation and marketing sections, with an outlined appearance,
   designed to be rendered at 24x24.
   """

lib/heroicons/solid.ex

@@ -1,7 +1,6 @@
 defmodule Heroicons.Solid do
   @moduledoc """
   Solid style icons drawn with fills, packaged as Phoenix Components.
-
   For primary navigation and marketing sections, with a filled appearance,
   designed to be rendered at 24x24.
   """

lib/mix/tasks/heroicons.ex

@@ -1,7 +1,9 @@
 defmodule Mix.Tasks.Heroicons do
   @moduledoc """
   Invokes heroicons mix utilities.
+
   Usage:
+
       $ mix heroicons
   """
 

lib/mix/tasks/heroicons/update.ex

@@ -1,9 +1,17 @@
 defmodule Mix.Tasks.Heroicons.Update do
   @moduledoc """
   Update heroicons.
-  By default, it downloads the latest version but you
-  can configure it in your config files, such as:
+
+  By default, it downloads the latest version but you can configure it
+  in your config files.
+
+  Example:
+
       config :heroicons, :version, "#{Heroicons.latest_version()}"
+
+  Then update with
+
+      $ mix heroicons.update
   """
 
   @shortdoc "Update heroicons assets"