Undeprecate Example and rename it to LiveExample

Author: msaraiva

lib/surface/catalogue/examples.ex

@@ -1,10 +1,13 @@
 defmodule Surface.Catalogue.Examples do
   @moduledoc since: "0.8.0"
   @moduledoc ~S'''
-  A generic LiveView to create multiple examples for catalogue tools.
+  A generic LiveView to create multiple stateless examples for the Surface Catalogue.
 
   Each example must be a function component defined with the module attribute `@example`.
 
+  > **NOTE**: If your examples require manipulating state (data) through `handle_event` callbacks,
+  > use `Surface.Catalogue.LiveExample` instead.
+
   ## Options
 
   Besides the buit-in options provided by the LiveView itself, examples can also

lib/surface/catalogue/example.ex renamed to lib/surface/catalogue/live_example.ex

@@ -1,10 +1,10 @@
-defmodule Surface.Catalogue.Example do
+defmodule Surface.Catalogue.LiveExample do
   @moduledoc """
-  > #### Deprecation warning {: .warning}
-  >
-  > This component has been deprecated in favor of `Surface.Catalogue.Examples`.
+  A generic LiveView to create a single live example for the Surface Catalogue.
 
-  A generic LiveView to create a single example for catalogue tools.
+  Use `LiveExample` if your example requires manipulating state (data) through
+  `handle_event` callbacks. For stateless examples, you should use `Surface.Catalogue.Examples`
+  as it allows defining multiple examples on a single module.
 
   ## Options
 
@@ -36,16 +36,7 @@ defmodule Surface.Catalogue.Example do
 
   """
 
-  @moduledoc deprecated: "Use `Surface.Catalogue.Examples` instead"
-
   defmacro __using__(opts) do
-    if Mix.env() != :test do
-      IO.warn(
-        "`Surface.Catalogue.Example` is deprecated. Use `Surface.Catalogue.Examples` instead",
-        Macro.Env.stacktrace(__CALLER__)
-      )
-    end
-
     subject = Surface.Catalogue.fetch_subject!(opts, __MODULE__, __CALLER__)
 
     quote do

test/support/catalogue/fake_example.ex

@@ -1,5 +1,5 @@
 defmodule Surface.Catalogue.FakeExample do
-  use Surface.Catalogue.Example,
+  use Surface.Catalogue.LiveExample,
     subject: Surface.FakeComponent,
     title: "A fake example",
     assert: ["The code"]

test/support/catalogue/fake_example_moduledoc.ex

@@ -1,7 +1,7 @@
 defmodule Surface.Catalogue.FakeExampleModuleDocFalse do
   @moduledoc false
 
-  use Surface.Catalogue.Example,
+  use Surface.Catalogue.LiveExample,
     subject: Surface.FakeComponent,
     title: "A fake example"
 

test/support/catalogue/fake_example_with_user_config.ex

@@ -1,5 +1,5 @@
 defmodule Surface.Catalogue.FakeExampleWithUserConfig do
-  use Surface.Catalogue.Example,
+  use Surface.Catalogue.LiveExample,
     subject: Surface.FakeComponent,
     head_css: "User's fake css",
     head_js: "User's fake js"

test/support/live_view_test/fake_example.ex

@@ -1,5 +1,5 @@
 defmodule Surface.LiveViewTestTest.FakeExample do
-  use Surface.Catalogue.Example,
+  use Surface.Catalogue.LiveExample,
     subject: Surface.LiveViewTestTest.FakeComponent,
     title: "A fake example",
     assert: "the code"

test/support/live_view_test/fake_example_for_other_fake_component.ex

@@ -1,5 +1,5 @@
 defmodule Surface.LiveViewTestTest.FakeExampleForOtherFakeComponent do
-  use Surface.Catalogue.Example,
+  use Surface.Catalogue.LiveExample,
     subject: Surface.LiveViewTestTest.OtherFakeComponent,
     title: "A fake example"
 

test/surface/catalogue/example_test.exs renamed to test/surface/catalogue/live_example_test.exs

@@ -1,4 +1,4 @@
-defmodule Surface.Catalogue.ExampleTest do
+defmodule Surface.Catalogue.LiveExampleTest do
   use ExUnit.Case
 
   alias Surface.Catalogue.FakeExample
@@ -31,16 +31,16 @@ defmodule Surface.Catalogue.ExampleTest do
   test "subject is required" do
     code = """
     defmodule ExampleTest_subject_is_required do
-      use Surface.Catalogue.Example
+      use Surface.Catalogue.LiveExample
     end
     """
 
     message = """
-    code.exs:2: no subject defined for Surface.Catalogue.Example
+    code.exs:2: no subject defined for Surface.Catalogue.LiveExample
 
     Hint: You can define the subject using the :subject option. Example:
 
-      use Surface.Catalogue.Example, subject: MyApp.MyButton
+      use Surface.Catalogue.LiveExample, subject: MyApp.MyButton
     """
 
     assert_raise CompileError, message, fn ->