Update changelog, migration guide and docs

CHANGELOG.md

@@ -1,8 +1,25 @@
 # Changelog
 
-## v0.12.0 (yyyy-mm-dd)
+## v0.12.0 (2024-09-24)
 
-This version moves all Form helpers to a [separate library](https://github.com/surface-ui/surface_form). Form Helpers are no longer used in new apps from Surface v0.12. Older applications who wish to maintain compatibility, add `{:surface_form, "~> 0.1.0"}` to your `mix.exs`.
+* Add column information to diagnostics to improve error/warning messages during compiler validation
+* Add compiler option `:generate_assets` to switch on/off component-related CSS/JS generation
+* Fix warning line when using  `@deprecated` on function components
+* Raise compile error when catalogue module cannot be found
+
+### Deprecations
+
+* Deprecate components `<LivePatch>`, `<LiveRedirect>` and `<Link>`, in favor of `<.link>`
+* Deprecate component `<Context>` as support for scoped-aware context is planned to be removed in `v0.13`.
+
+### Breaking Changes
+
+* Move all form-related components, including `<Form>` and all inputs to a separate `surface_form` project.
+  For more info, see [Migration Guide](https://github.com/surface-ui/surface/blob/main/MIGRATING.md#migrating-to-v012x).
+* Rename `Surface.Catalogue.Example` to `Surface.Catalogue.LiveExample` as its use now should only be required in
+  live examples that update assigns through `handle_event` calls
+* Remove deprecated slot attributes `for`, `name` and `ìndex`
+* Remove deprecated slot `:args` option and directive
 
 ## v0.11.5 (2024-09-04)
 

MIGRATING.md

@@ -1,3 +1,36 @@
+# Migrating to `v0.12.x`
+
+### Forms
+
+Component `<Form>` and all its related input components (`<TextInput>`, `<Checkbox>`, etc.) have been
+deprecated and moved to a separate project called `surface_form_helpers`. The reason those components were created
+in the first place was to add support for [scope-aware contexts](https://www.surface-ui.org/contexts#scope-aware-context)
+to forms. Since this feature has been deprecated due to the lack of built-in support in Liveview, we strongly
+recommend using the new built-in [<.form>](https://hexdocs.pm/phoenix_live_view/Phoenix.Component.html#form/)
+component, along with [Phoenix.HTML.Form](https://hexdocs.pm/phoenix_html/Phoenix.HTML.Form.html) and
+[Phoenix.HTML.FormField](https://hexdocs.pm/phoenix_html/Phoenix.HTML.FormField.html) structs. This new Liveview API
+is way more efficient regarding diff-tracking and should be the default way to desing forms.
+
+If you're not able to update all your forms at once, `surface_form_helpers` can be used as a safe fallback so you can
+gradually replace them.
+
+### Using `surface_form_helpers`
+
+```elixir
+def deps do
+  [
+    {:surface_form_helpers, "~> 0.1.0"}
+  ]
+end
+```
+
+### Surface Catalogue
+
+In case you're using `surface_catalogue` and have examples using `Surface.Catalogue.Example`, you need to
+rename those with `Surface.Catalogue.LiveExample`. Pay attention that you should use `LiveExample` mostly
+if your example requires manipulating state (data) through `handle_event` callbacks. For stateless examples,
+use `Surface.Catalogue.Examples` instead, as it allows defining multiple examples on a single module.
+
 # Migrating from `v0.7.x` to `v0.8.x`
 
 Historically, most of the updates that require changes in your code, can be automatically

lib/surface/components/link.ex

@@ -4,7 +4,7 @@ defmodule Surface.Components.Link do
   >
   > This component has been deprecated in favor of liveview's built-in `<.link>`
   > and will be removed in `v0.13`. See https://hexdocs.pm/phoenix_live_view/live-navigation.html for
-  > more info usage.
+  > more info and usage.
 
   Generates a link to the given URL.
 

lib/surface/components/live_patch.ex

@@ -4,7 +4,7 @@ defmodule Surface.Components.LivePatch do
   >
   > This component has been deprecated in favor of liveview's built-in `<.link>`
   > and will be removed in `v0.13`. See https://hexdocs.pm/phoenix_live_view/live-navigation.html for
-  > more info usage.
+  > more info and usage.
 
   Defines a link that will **patch** the current LiveView.
 

lib/surface/components/live_redirect.ex

@@ -4,7 +4,7 @@ defmodule Surface.Components.LiveRedirect do
   >
   > This component has been deprecated in favor of liveview's built-in `<.link>`
   > and will be removed in `v0.13`. See https://hexdocs.pm/phoenix_live_view/live-navigation.html for
-  > more info usage.
+  > more info and usage.
 
   Defines a link that will **redirect** to a new LiveView.