diff --git a/lib/surface/catalogue/examples.ex b/lib/surface/catalogue/examples.ex index 3bf771919..1e670a3e1 100644 --- a/lib/surface/catalogue/examples.ex +++ b/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 diff --git a/lib/surface/catalogue/example.ex b/lib/surface/catalogue/live_example.ex similarity index 87% rename from lib/surface/catalogue/example.ex rename to lib/surface/catalogue/live_example.ex index 4f8b548d8..fc0395833 100644 --- a/lib/surface/catalogue/example.ex +++ b/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 diff --git a/test/support/catalogue/fake_example.ex b/test/support/catalogue/fake_example.ex index 22ec52398..9c7d5c3c2 100644 --- a/test/support/catalogue/fake_example.ex +++ b/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"] diff --git a/test/support/catalogue/fake_example_moduledoc.ex b/test/support/catalogue/fake_example_moduledoc.ex index a2140bc7c..a2d6789fe 100644 --- a/test/support/catalogue/fake_example_moduledoc.ex +++ b/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" diff --git a/test/support/catalogue/fake_example_with_user_config.ex b/test/support/catalogue/fake_example_with_user_config.ex index d3bed1242..cbb485ad9 100644 --- a/test/support/catalogue/fake_example_with_user_config.ex +++ b/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" diff --git a/test/support/live_view_test/fake_example.ex b/test/support/live_view_test/fake_example.ex index 335229efd..1560bde01 100644 --- a/test/support/live_view_test/fake_example.ex +++ b/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" diff --git a/test/support/live_view_test/fake_example_for_other_fake_component.ex b/test/support/live_view_test/fake_example_for_other_fake_component.ex index c32d7dc08..354395fff 100644 --- a/test/support/live_view_test/fake_example_for_other_fake_component.ex +++ b/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" diff --git a/test/surface/catalogue/example_test.exs b/test/surface/catalogue/live_example_test.exs similarity index 84% rename from test/surface/catalogue/example_test.exs rename to test/surface/catalogue/live_example_test.exs index 3e87439bc..3c52df960 100644 --- a/test/surface/catalogue/example_test.exs +++ b/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 ->