From 879cef62f1c6f4b4693ab93f7bf0aef8a4f03e47 Mon Sep 17 00:00:00 2001
From: timujeen <timujeen@gmail.com>
Date: Sun, 15 Mar 2026 20:22:16 +0000
Subject: [PATCH] Show not-installed packages on Modules page with install
 instructions

---
 lib/phoenix_kit/module_registry.ex         | 28 +++++++++++++
 lib/phoenix_kit_web/live/modules.ex        |  2 +
 lib/phoenix_kit_web/live/modules.html.heex | 48 ++++++++++++++++------
 3 files changed, 65 insertions(+), 13 deletions(-)

diff --git a/lib/phoenix_kit/module_registry.ex b/lib/phoenix_kit/module_registry.ex
index d8c494511..e0698e0ff 100644
--- a/lib/phoenix_kit/module_registry.ex
+++ b/lib/phoenix_kit/module_registry.ex
@@ -213,6 +213,18 @@ defmodule PhoenixKit.ModuleRegistry do
     end)
   end
 
+  @doc """
+  Returns known external PhoenixKit packages that are not currently installed.
+
+  Used by the admin Modules page to inform users about available packages
+  they can add as dependencies.
+  """
+  @spec not_installed_packages() :: [map()]
+  def not_installed_packages do
+    known_external_packages()
+    |> Enum.reject(fn pkg -> Code.ensure_loaded?(pkg.module) end)
+  end
+
   @doc "Returns all feature module key strings from registered modules."
   @spec all_feature_keys() :: [String.t()]
   def all_feature_keys do
@@ -413,6 +425,22 @@ defmodule PhoenixKit.ModuleRegistry do
     ]
   end
 
+  # Known external PhoenixKit packages. Listed here so the admin Modules page
+  # can show "not installed" cards for packages the user hasn't added yet.
+  defp known_external_packages do
+    [
+      %{
+        module: PhoenixKit.Modules.Newsletters,
+        hex_package: "phoenix_kit_newsletters",
+        name: "Newsletters",
+        description:
+          "Email newsletter management with list subscriptions, broadcast campaigns, and delivery tracking.",
+        icon: "📧",
+        hex_url: "https://hex.pm/packages/phoenix_kit_newsletters"
+      }
+    ]
+  end
+
   defp warn_duplicate_tab_ids(tabs) do
     tabs
     |> Enum.map(& &1.id)
diff --git a/lib/phoenix_kit_web/live/modules.ex b/lib/phoenix_kit_web/live/modules.ex
index dec2bf10b..985bcd526 100644
--- a/lib/phoenix_kit_web/live/modules.ex
+++ b/lib/phoenix_kit_web/live/modules.ex
@@ -31,6 +31,7 @@ defmodule PhoenixKitWeb.Live.Modules do
 
     external_modules = load_external_modules(module_configs)
     dep_warnings = ModuleRegistry.dependency_warnings()
+    not_installed = ModuleRegistry.not_installed_packages()
 
     socket =
       socket
@@ -40,6 +41,7 @@ defmodule PhoenixKitWeb.Live.Modules do
       |> assign(:module_configs, module_configs)
       |> assign(:external_modules, external_modules)
       |> assign(:dep_warnings, dep_warnings)
+      |> assign(:not_installed_packages, not_installed)
 
     {:ok, socket}
   end
diff --git a/lib/phoenix_kit_web/live/modules.html.heex b/lib/phoenix_kit_web/live/modules.html.heex
index 9bfd6c36d..d1bcf1570 100644
--- a/lib/phoenix_kit_web/live/modules.html.heex
+++ b/lib/phoenix_kit_web/live/modules.html.heex
@@ -1422,21 +1422,43 @@
       <% end %>
     </div>
 
-    <%!-- Future Modules Section --%>
-    <div class="mt-8">
-      <div class="card bg-base-100 shadow-xl border-2 border-dashed border-base-300">
-        <div class="card-body text-center py-8">
-          <div class="text-4xl mb-4 opacity-50">📦</div>
-          <h3 class="text-xl font-semibold text-base-content/60 mb-2">
-            More Modules Coming Soon
-          </h3>
-          <p class="text-base-content/50">
-            Additional system modules and extensions will be available here as they're developed.
-            Each module will have its own dedicated configuration page for scalable management.
-          </p>
+    <%!-- Available Packages (known but not installed) --%>
+    <%= if @not_installed_packages != [] do %>
+      <div class="mt-8">
+        <h2 class="text-lg font-semibold mb-3 text-base-content/70">Available Packages</h2>
+        <div class="grid gap-6 md:grid-cols-2 lg:grid-cols-3">
+          <%= for pkg <- @not_installed_packages do %>
+            <div class="card bg-base-100 shadow border-2 border-dashed border-base-300">
+              <div class="card-body">
+                <div class="flex items-center gap-3">
+                  <div class="text-3xl opacity-60">{pkg.icon}</div>
+                  <div class="flex-1">
+                    <h3 class="card-title text-base-content/70">{pkg.name}</h3>
+                    <p class="text-sm text-base-content/50">{pkg.description}</p>
+                  </div>
+                </div>
+
+                <div class="divider my-2"></div>
+
+                <div class="flex items-center justify-between gap-2 flex-wrap">
+                  <span class="badge badge-ghost badge-outline">Not installed</span>
+                  <a href={pkg.hex_url} target="_blank" class="btn btn-xs btn-outline">
+                    <.icon name="hero-arrow-top-right-on-square" class="w-3 h-3" /> Hex.pm
+                  </a>
+                </div>
+
+                <div class="mt-2">
+                  <p class="text-xs text-base-content/40 mb-1">Add to mix.exs:</p>
+                  <code class="block text-xs bg-base-200 rounded p-2 font-mono">
+                    {~s|{:#{pkg.hex_package}, "~> 0.1"}|}
+                  </code>
+                </div>
+              </div>
+            </div>
+          <% end %>
         </div>
       </div>
-    </div>
+    <% end %>
 
     <%!-- Module Management Help --%>
     <div class="alert alert-info mt-6">