chore: added more @spec

lib/bds/desktop/shell_live/post_editor/draft_management.ex

@@ -8,11 +8,14 @@ defmodule BDS.Desktop.ShellLive.PostEditor.DraftManagement do
   alias BDS.Desktop.ShellLive.PostEditor.PostMetadata
   alias BDS.UI.Workbench
 
+  @spec normalize_mode(term()) :: term()
   def normalize_mode(mode) when mode in [:markdown, :preview], do: mode
+  @spec normalize_mode(term()) :: term()
   def normalize_mode("visual"), do: :markdown
   def normalize_mode("preview"), do: :preview
   def normalize_mode(_mode), do: :markdown
 
+  @spec normalize_language(term(), term()) :: term()
   def normalize_language(value, fallback) do
     case value |> to_string() |> String.trim() do
       "" -> fallback
@@ -20,6 +23,7 @@ defmodule BDS.Desktop.ShellLive.PostEditor.DraftManagement do
     end
   end
 
+  @spec normalize_params(term(), term(), term()) :: term()
   def normalize_params(params, current_language, next_language) do
     %{
       "title" => Map.get(params, "title", ""),
@@ -28,12 +32,17 @@ defmodule BDS.Desktop.ShellLive.PostEditor.DraftManagement do
       "tags" => Map.get(params, "tags", ""),
       "categories" => Map.get(params, "categories", ""),
       "author" => Map.get(params, "author", ""),
-      "language" => if(current_language == next_language, do: normalize_language(Map.get(params, "language"), current_language), else: next_language),
+      "language" =>
+        if(current_language == next_language,
+          do: normalize_language(Map.get(params, "language"), current_language),
+          else: next_language
+        ),
       "do_not_translate" => truthy?(Map.get(params, "do_not_translate")),
       "template_slug" => Map.get(params, "template_slug", "")
     }
   end
 
+  @spec current_draft(term(), term(), term(), term()) :: term()
   def current_draft(assigns, %Post{} = post, metadata, active_language) do
     persisted = persisted_form(post, metadata, active_language)
 
@@ -42,10 +51,12 @@ defmodule BDS.Desktop.ShellLive.PostEditor.DraftManagement do
     |> Map.get(active_language, persisted)
   end
 
+  @spec persisted_form(term(), term(), term()) :: term()
   def persisted_form(%Post{} = post, metadata, active_language) do
     persisted_form(post, metadata, active_language, PostMetadata.translations(post.id))
   end
 
+  @spec persisted_form(term(), term(), term(), term()) :: term()
   def persisted_form(post, metadata, active_language, translations) do
     canonical_language = PostMetadata.canonical_language(post, metadata)
     translation = Map.get(translations, active_language)
@@ -64,8 +75,8 @@ defmodule BDS.Desktop.ShellLive.PostEditor.DraftManagement do
       }
     else
       %{
-        "title" => translation && translation.title || "",
-        "excerpt" => translation && translation.excerpt || "",
+        "title" => (translation && translation.title) || "",
+        "excerpt" => (translation && translation.excerpt) || "",
         "content" => if(translation, do: Posts.editor_body(translation), else: ""),
         "tags" => Enum.join(post.tags || [], ", "),
         "categories" => Enum.join(post.categories || [], ", "),
@@ -77,22 +88,43 @@ defmodule BDS.Desktop.ShellLive.PostEditor.DraftManagement do
     end
   end
 
+  @spec maybe_update_draft(term(), term(), term(), term(), term(), term(), term()) :: term()
   def maybe_update_draft(socket, post_id, post, current_language, next_language, draft, true) do
     workbench = Workbench.mark_dirty(socket.assigns.workbench, :post, post_id)
 
     socket
     |> assign(:workbench, workbench)
-    |> assign(:post_editor_drafts, put_nested_map(socket.assigns.post_editor_drafts, post_id, next_language, draft))
-    |> assign(:post_editor_active_languages, Map.put(socket.assigns.post_editor_active_languages, post_id, next_language))
-    |> assign(:post_editor_save_states, Map.put(socket.assigns.post_editor_save_states, post_id, :dirty))
-    |> assign(:tab_meta, Map.put(socket.assigns.tab_meta, {:post, post_id}, %{title: draft["title"], subtitle: Atom.to_string(post.status || :draft)}))
+    |> assign(
+      :post_editor_drafts,
+      put_nested_map(socket.assigns.post_editor_drafts, post_id, next_language, draft)
+    )
+    |> assign(
+      :post_editor_active_languages,
+      Map.put(socket.assigns.post_editor_active_languages, post_id, next_language)
+    )
+    |> assign(
+      :post_editor_save_states,
+      Map.put(socket.assigns.post_editor_save_states, post_id, :dirty)
+    )
+    |> assign(
+      :tab_meta,
+      Map.put(socket.assigns.tab_meta, {:post, post_id}, %{
+        title: draft["title"],
+        subtitle: Atom.to_string(post.status || :draft)
+      })
+    )
     |> maybe_drop_old_language_draft(post_id, current_language, next_language)
   end
 
   def maybe_update_draft(socket, post_id, _post, _current_language, next_language, _draft, false) do
-    assign(socket, :post_editor_active_languages, Map.put(socket.assigns.post_editor_active_languages, post_id, next_language))
+    assign(
+      socket,
+      :post_editor_active_languages,
+      Map.put(socket.assigns.post_editor_active_languages, post_id, next_language)
+    )
   end
 
+  @spec put_draft_field(term(), term(), term(), term(), term(), term()) :: term()
   def put_draft_field(socket, post_id, post, active_language, field, value) do
     metadata = PostMetadata.project_metadata(post.project_id)
     draft = Map.put(current_draft(socket.assigns, post, metadata, active_language), field, value)
@@ -100,15 +132,28 @@ defmodule BDS.Desktop.ShellLive.PostEditor.DraftManagement do
 
     socket
     |> assign(:workbench, workbench)
-    |> assign(:post_editor_drafts, put_nested_map(socket.assigns.post_editor_drafts, post_id, active_language, draft))
-    |> assign(:post_editor_save_states, Map.put(socket.assigns.post_editor_save_states, post_id, :dirty))
+    |> assign(
+      :post_editor_drafts,
+      put_nested_map(socket.assigns.post_editor_drafts, post_id, active_language, draft)
+    )
+    |> assign(
+      :post_editor_save_states,
+      Map.put(socket.assigns.post_editor_save_states, post_id, :dirty)
+    )
   end
 
+  @spec put_query_state(term(), term(), term(), term()) :: term()
   def put_query_state(socket, post_id, kind, value) do
     key = query_key(kind)
-    assign(socket, key, Map.put(Map.get(socket.assigns, key, %{}), post_id, to_string(value || "")))
+
+    assign(
+      socket,
+      key,
+      Map.put(Map.get(socket.assigns, key, %{}), post_id, to_string(value || ""))
+    )
   end
 
+  @spec query_value(term(), term(), term()) :: term()
   def query_value(assigns, kind, post_id) do
     assigns
     |> Map.get(query_key(kind), %{})
@@ -118,25 +163,33 @@ defmodule BDS.Desktop.ShellLive.PostEditor.DraftManagement do
   defp query_key(:tags), do: :post_editor_tag_queries
   defp query_key(:categories), do: :post_editor_category_queries
 
-  defp maybe_drop_old_language_draft(socket, _post_id, current_language, next_language) when current_language == next_language,
-    do: socket
+  defp maybe_drop_old_language_draft(socket, _post_id, current_language, next_language)
+       when current_language == next_language,
+       do: socket
 
   defp maybe_drop_old_language_draft(socket, post_id, current_language, _next_language) do
-    assign(socket, :post_editor_drafts, delete_nested_map(socket.assigns.post_editor_drafts, post_id, current_language))
+    assign(
+      socket,
+      :post_editor_drafts,
+      delete_nested_map(socket.assigns.post_editor_drafts, post_id, current_language)
+    )
   end
 
+  @spec toggled_sections(term(), term(), term()) :: term()
   def toggled_sections(expanded_by_post, post_id, section) do
     expanded_by_post
     |> Map.get(post_id, %{metadata: false, excerpt: false})
     |> Map.put_new(:metadata, false)
     |> Map.put_new(:excerpt, false)
-    |> Map.update!(section, &not &1)
+    |> Map.update!(section, &(not &1))
   end
 
+  @spec put_nested_map(term(), term(), term(), term()) :: term()
   def put_nested_map(map, key, nested_key, value) do
     Map.update(map, key, %{nested_key => value}, &Map.put(&1, nested_key, value))
   end
 
+  @spec delete_nested_map(term(), term(), term()) :: term()
   def delete_nested_map(map, key, nested_key) do
     case Map.get(map, key) do
       nil ->
@@ -150,20 +203,26 @@ defmodule BDS.Desktop.ShellLive.PostEditor.DraftManagement do
     end
   end
 
-  def reload_with_assigned_workbench(socket, reload), do: reload.(socket, socket.assigns.workbench)
+  @spec reload_with_assigned_workbench(term(), term()) :: term()
+  def reload_with_assigned_workbench(socket, reload),
+    do: reload.(socket, socket.assigns.workbench)
 
+  @spec save_state_for_action(term()) :: term()
   def save_state_for_action(:publish), do: :published
   def save_state_for_action(_action), do: :saved
 
+  @spec record_title(term(), term()) :: term()
   def record_title(%Translation{title: title}, post),
     do: blank_to_nil(title) || post.title || post.slug || post.id
 
   def record_title(%Post{title: title, slug: slug, id: id}, _post),
     do: blank_to_nil(title) || blank_to_nil(slug) || id
 
+  @spec record_status(term()) :: term()
   def record_status(%Translation{status: status}), do: status || :draft
   def record_status(%Post{status: status}), do: status || :draft
 
+  @spec editing_canonical_language?(term(), term(), term()) :: term()
   def editing_canonical_language?(translations, active_language, canonical_language) do
     active_language == canonical_language or not Map.has_key?(translations, active_language)
   end

lib/bds/desktop/shell_live/post_editor/list_values.ex

@@ -3,17 +3,22 @@ defmodule BDS.Desktop.ShellLive.PostEditor.ListValues do
 
   alias BDS.{Metadata, Tags}
 
+  @spec field_key(term()) :: term()
   def field_key(:tags), do: "tags"
   def field_key(:categories), do: "categories"
 
+  @spec tag_values(term()) :: term()
   def tag_values(form), do: csv_to_list(Map.get(form, "tags", ""))
+  @spec category_values(term()) :: term()
   def category_values(form), do: csv_to_list(Map.get(form, "categories", ""))
 
+  @spec tag_suggestions(term(), term(), term()) :: term()
   def tag_suggestions(form, options, query) do
     selected = MapSet.new(tag_values(form))
     filter_suggestions(options, query, fn option -> option.name end, selected)
   end
 
+  @spec tag_chips(term(), term()) :: term()
   def tag_chips(form, options) do
     option_map = Map.new(options, fn option -> {option.name, option} end)
 
@@ -23,6 +28,7 @@ defmodule BDS.Desktop.ShellLive.PostEditor.ListValues do
     end)
   end
 
+  @spec category_suggestions(term(), term(), term()) :: term()
   def category_suggestions(form, options, query) do
     selected = MapSet.new(category_values(form))
     filter_suggestions(options, query, & &1, selected)
@@ -34,11 +40,14 @@ defmodule BDS.Desktop.ShellLive.PostEditor.ListValues do
     options
     |> Enum.filter(fn option ->
       label = labeler.(option)
-      not MapSet.member?(selected, label) and (query == "" or String.contains?(String.downcase(label), query))
+
+      not MapSet.member?(selected, label) and
+        (query == "" or String.contains?(String.downcase(label), query))
     end)
     |> Enum.take(8)
   end
 
+  @spec query_addable?(term(), term(), term(), term()) :: term()
   def query_addable?(query, selected_values, options, labeler) do
     normalized = normalize_query(query)
 
@@ -54,6 +63,7 @@ defmodule BDS.Desktop.ShellLive.PostEditor.ListValues do
     |> String.downcase()
   end
 
+  @spec normalize_list_entry(term()) :: term()
   def normalize_list_entry(value) do
     value
     |> to_string()
@@ -61,6 +71,7 @@ defmodule BDS.Desktop.ShellLive.PostEditor.ListValues do
     |> String.downcase()
   end
 
+  @spec ensure_list_value(term(), term(), term()) :: term()
   def ensure_list_value(project_id, :tags, value) do
     if Enum.any?(Tags.list_tags(project_id), &(String.downcase(&1.name) == value)) do
       :ok
@@ -83,6 +94,7 @@ defmodule BDS.Desktop.ShellLive.PostEditor.ListValues do
     _error -> :ok
   end
 
+  @spec csv_to_list(term()) :: term()
   def csv_to_list(value) do
     value
     |> to_string()
@@ -91,6 +103,7 @@ defmodule BDS.Desktop.ShellLive.PostEditor.ListValues do
     |> Enum.reject(&(&1 == ""))
   end
 
+  @spec tag_chip_style(term()) :: term()
   def tag_chip_style(nil), do: nil
 
   def tag_chip_style(color) do
@@ -121,5 +134,6 @@ defmodule BDS.Desktop.ShellLive.PostEditor.ListValues do
 
   defp contrast_color(_color), do: "#ffffff"
 
+  @spec ai_overlay_fields(term()) :: term()
   def ai_overlay_fields(selected), do: Enum.filter(selected, & &1.accepted)
 end

lib/bds/desktop/shell_live/post_editor/persistence.ex

@@ -6,11 +6,16 @@ defmodule BDS.Desktop.ShellLive.PostEditor.Persistence do
   alias BDS.Desktop.ShellData
   alias BDS.Desktop.ShellLive.PostEditor.{DraftManagement, PostMetadata}
 
+  @spec persist(term(), term(), term(), term(), term()) :: term()
   def persist(%Post{} = post, draft, active_language, metadata, action) do
     canonical_language = PostMetadata.canonical_language(post, metadata)
     translations = PostMetadata.translations(post.id)
 
-    if DraftManagement.editing_canonical_language?(translations, active_language, canonical_language) do
+    if DraftManagement.editing_canonical_language?(
+         translations,
+         active_language,
+         canonical_language
+       ) do
       post
       |> save_canonical_draft(draft)
       |> maybe_publish_post(post.id, action)
@@ -21,12 +26,17 @@ defmodule BDS.Desktop.ShellLive.PostEditor.Persistence do
     end
   end
 
+  @spec discard(term(), term(), term()) :: term()
   def discard(%Post{} = post, active_language, metadata) do
     canonical_language = PostMetadata.canonical_language(post, metadata)
     current_translations = PostMetadata.translations(post.id)
 
     cond do
-      not DraftManagement.editing_canonical_language?(current_translations, active_language, canonical_language) ->
+      not DraftManagement.editing_canonical_language?(
+        current_translations,
+        active_language,
+        canonical_language
+      ) ->
         {:ok, post}
 
       post.file_path not in [nil, ""] and post.status == :draft ->
@@ -37,15 +47,18 @@ defmodule BDS.Desktop.ShellLive.PostEditor.Persistence do
     end
   end
 
+  @spec has_published_version?(term()) :: term()
   def has_published_version?(%Post{} = post),
     do: not is_nil(post.published_at) or post.file_path not in [nil, ""]
 
+  @spec discard_label(term()) :: term()
   def discard_label(%Post{} = post) do
     if has_published_version?(post),
       do: translated("Discard Changes"),
       else: translated("Discard Draft")
   end
 
+  @spec discard_title(term()) :: term()
   def discard_title(%Post{} = post) do
     if has_published_version?(post),
       do: translated("Discard changes and restore the published version"),

lib/bds/desktop/shell_live/post_editor/post_metadata.ex

@@ -8,6 +8,7 @@ defmodule BDS.Desktop.ShellLive.PostEditor.PostMetadata do
   alias BDS.Media.Media, as: MediaRecord
   alias BDS.Posts.{Post, PostMedia}
 
+  @spec project_metadata(term()) :: term()
   def project_metadata(nil), do: %{main_language: "en", blog_languages: []}
 
   def project_metadata(project_id) do
@@ -17,6 +18,7 @@ defmodule BDS.Desktop.ShellLive.PostEditor.PostMetadata do
     _error -> %{main_language: "en", blog_languages: []}
   end
 
+  @spec canonical_language(term(), term()) :: term()
   def canonical_language(post, metadata) do
     BDS.Desktop.ShellLive.PostEditor.DraftManagement.normalize_language(
       post.language,
@@ -24,28 +26,36 @@ defmodule BDS.Desktop.ShellLive.PostEditor.PostMetadata do
     )
   end
 
+  @spec translations(term()) :: term()
   def translations(post_id) do
     {:ok, translations} = Posts.list_post_translations(post_id)
     Map.new(translations, fn translation -> {translation.language, translation} end)
   end
 
+  @spec languages(term()) :: term()
   def languages(metadata) do
-    (([metadata.main_language || "en"] ++ (metadata.blog_languages || [])) ++ Enum.map(I18n.supported_languages(), & &1.code))
+    (([metadata.main_language || "en"] ++ (metadata.blog_languages || [])) ++
+       Enum.map(I18n.supported_languages(), & &1.code))
     |> Enum.reject(&is_nil/1)
     |> Enum.uniq()
   end
 
+  @spec template_options(term()) :: term()
   def template_options(project_id) do
     Repo.all(
       from template in Templates.Template,
         where: template.project_id == ^project_id,
         order_by: [asc: template.title, asc: template.slug],
-        select: %{slug: template.slug, title: fragment("COALESCE(?, ?)", template.title, template.slug)}
+        select: %{
+          slug: template.slug,
+          title: fragment("COALESCE(?, ?)", template.title, template.slug)
+        }
     )
   rescue
     _error -> []
   end
 
+  @spec linked_media(term()) :: term()
   def linked_media(post_id) do
     rows =
       Repo.all(
@@ -74,6 +84,7 @@ defmodule BDS.Desktop.ShellLive.PostEditor.PostMetadata do
     _error -> []
   end
 
+  @spec post_links(term()) :: term()
   def post_links(post_id) do
     %{
       backlinks: related_posts(PostLinks.list_incoming_links(post_id), :source_post_id),
@@ -84,15 +95,29 @@ defmodule BDS.Desktop.ShellLive.PostEditor.PostMetadata do
   defp related_posts(links, key) do
     Enum.map(links, fn link ->
       case Posts.get_post(Map.fetch!(link, key)) do
-        %Post{} = post -> %{id: post.id, title: post.title || post.slug || post.id, text: link.link_text || post.slug || post.id}
-        _other -> nil
+        %Post{} = post ->
+          %{
+            id: post.id,
+            title: post.title || post.slug || post.id,
+            text: link.link_text || post.slug || post.id
+          }
+
+        _other ->
+          nil
       end
     end)
     |> Enum.reject(&is_nil/1)
   end
 
+  @spec translation_flags(term(), term(), term(), term()) :: term()
   def translation_flags(post, canonical_language, active_language, translations) do
-    canonical = %{language: canonical_language, flag: I18n.flag(canonical_language), status: Atom.to_string(post.status || :draft), active: active_language == canonical_language, label: canonical_language}
+    canonical = %{
+      language: canonical_language,
+      flag: I18n.flag(canonical_language),
+      status: Atom.to_string(post.status || :draft),
+      active: active_language == canonical_language,
+      label: canonical_language
+    }
 
     others =
       translations
@@ -111,6 +136,7 @@ defmodule BDS.Desktop.ShellLive.PostEditor.PostMetadata do
     [canonical | others]
   end
 
+  @spec footer(term(), term(), term(), term()) :: term()
   def footer(post, translation, active_language, canonical_language) do
     if active_language == canonical_language do
       %{
@@ -120,8 +146,8 @@ defmodule BDS.Desktop.ShellLive.PostEditor.PostMetadata do
       }
     else
       %{
-        created_at: format_timestamp(translation && translation.created_at || post.created_at),
-        updated_at: format_timestamp(translation && translation.updated_at || post.updated_at),
+        created_at: format_timestamp((translation && translation.created_at) || post.created_at),
+        updated_at: format_timestamp((translation && translation.updated_at) || post.updated_at),
         published_at: format_timestamp(translation && translation.published_at)
       }
     end
@@ -135,10 +161,12 @@ defmodule BDS.Desktop.ShellLive.PostEditor.PostMetadata do
     |> Calendar.strftime("%x")
   end
 
+  @spec display_title(term(), term(), term()) :: term()
   def display_title(title, slug, fallback_id) do
     blank_to_nil(title) || blank_to_nil(slug) || fallback_id || translated("Untitled")
   end
 
+  @spec gallery_count(term()) :: term()
   def gallery_count(form) do
     form
     |> Map.get("content", "")
@@ -147,8 +175,11 @@ defmodule BDS.Desktop.ShellLive.PostEditor.PostMetadata do
     |> length()
   end
 
-  def preview_url(_post, _active_language, _canonical_language, mode) when mode != :preview, do: nil
+  @spec preview_url(term(), term(), term(), term()) :: term()
+  def preview_url(_post, _active_language, _canonical_language, mode) when mode != :preview,
+    do: nil
 
+  @spec preview_url(term(), term(), term(), term()) :: term()
   def preview_url(%Post{} = post, active_language, canonical_language, :preview) do
     query =
       %{}
@@ -156,7 +187,8 @@ defmodule BDS.Desktop.ShellLive.PostEditor.PostMetadata do
       |> maybe_put_query("post_id", post.id)
       |> maybe_put_query("lang", active_language != canonical_language && active_language)
 
-    Preview.base_url() <> canonical_preview_path(post.created_at, post.slug) <> "?" <> URI.encode_query(query)
+    Preview.base_url() <>
+      canonical_preview_path(post.created_at, post.slug) <> "?" <> URI.encode_query(query)
   end
 
   defp canonical_preview_path(created_at_ms, slug) do
@@ -171,10 +203,13 @@ defmodule BDS.Desktop.ShellLive.PostEditor.PostMetadata do
   defp maybe_put_query(query, key, value), do: Map.put(query, key, value)
 
   def truthy?(value) when value in [true, "true", "on", 1, "1"], do: true
+  @spec truthy?(term()) :: term()
   def truthy?(_value), do: false
 
+  @spec blank?(term()) :: term()
   def blank?(value), do: blank_to_nil(value) == nil
 
+  @spec blank_to_nil(term()) :: term()
   def blank_to_nil(value) do
     value
     |> to_string()