Improve member view table behavior+style, fix config settings (#493)

## Description of the implemented changes
The changes were:
- [x] Bugfixing
- [x] New Feature
- [ ] Breaking Change
- [x] Refactoring

This PR standardizes interactive table behavior and improves settings robustness.
It makes the new hover/focus-visible row highlight the default for clickable tables, keeps sticky first-column behavior configurable (and optimized for member selection UX), and tightens SMTP source-of-truth handling so ENV-based and UI-based configuration do not conflict.

## What has been changed?
- Refactored `CoreComponents.table` to expose interaction state via `data-row-interactive` and moved default row hover/focus styling to CSS.
- Made the new row highlight behavior (`hover` + `:has(:focus-visible)`) the default for clickable zebra tables.
- Kept sticky-first-column as an explicit table option and preserved sticky-specific selection accent behavior.
- Updated member overview table usage to the sticky-first-column mode and refined scrolling behavior (table scrollbar within container, not page-coupled).
- Adjusted table-related tests to validate the new interaction contract (attribute/CSS-driven behavior instead of legacy ring classes).
- Improved SMTP config handling:
  - clearer ENV-vs-Settings behavior (ENV-only mode when host env is set),
  - read-only and warning behavior in global settings UI when required env keys are missing,
  - updated related config/tests/docs.
- Updated docs and changelog (`CHANGELOG.md`, `DESIGN_GUIDELINES.md`, `CODE_GUIDELINES.md`, SMTP concept docs).
- Updated gettext catalogs (`default.pot`, `en`, `de`) for new/changed UI strings.

## Definition of Done
### Code Quality
- [x] No new technical depths
- [x] Linting passed
- [x] Documentation is added were needed

### Accessibility
- [x] New elements are properly defined with html-tags
- [x] Colour contrast follows WCAG criteria
- [x] Aria labels are added when needed
- [x] Everything is accessible by keyboard
- [x] Tab-Order is comprehensible
- [x] All interactive elements have a visible focus

### Testing
- [x] Tests for new code are written
- [x] All tests pass
- [ ] axe-core dev tools show no critical or major issues

## Additional Notes
- Branch includes 4 commits:
  - `fix: make sure smtp can be set either via env or ui`
  - `fix: make horizontal scrollbars sticky to bottom`
  - `docs: update changelog`
  - `feat: make checkbox column in member view sticky`
- Full fast suite passed (`mix test --exclude slow --exclude ui`): 2017 tests, 0 failures (plus expected non-failing warning logs in test output).
- Reviewer focus areas:
  1. **Cross-table UX consistency** after moving row interaction styling to component/CSS contract.
  2. **Sticky table behavior** (selection accent stripe, zebra background, keyboard focus visibility).
  3. **SMTP precedence and UI constraints** in global settings when ENV mode is active.
  4. **Regression risk in tests** that previously asserted ring-based row classes.
- No breaking API changes expected; behavior change is primarily visual/interaction-level and intentional.

Reviewed-on: #493
Co-authored-by: Simon <s.thiessen@local-it.org>
Co-committed-by: Simon <s.thiessen@local-it.org>

lib/mv/config.ex

@@ -470,56 +470,77 @@ defmodule Mv.Config do
   # ---------------------------------------------------------------------------
 
   @doc """
-  Returns SMTP host. ENV `SMTP_HOST` overrides Settings.
+  Returns SMTP host.
+
+  Policy:
+  - ENV-only mode (`SMTP_HOST` set): read from ENV `SMTP_HOST`
+  - Settings mode: read from Settings only
   """
   @spec smtp_host() :: String.t() | nil
   def smtp_host do
-    smtp_env_or_setting("SMTP_HOST", :smtp_host)
-  end
-
-  @doc """
-  Returns SMTP port as integer. ENV `SMTP_PORT` (parsed) overrides Settings.
-  Returns nil when neither ENV nor Settings provide a valid port.
-  """
-  @spec smtp_port() :: non_neg_integer() | nil
-  def smtp_port do
-    case System.get_env("SMTP_PORT") do
-      nil ->
-        get_from_settings_integer(:smtp_port)
-
-      value when is_binary(value) ->
-        case Integer.parse(String.trim(value)) do
-          {port, _} when port > 0 -> port
-          _ -> nil
-        end
+    if smtp_env_mode?() do
+      System.get_env("SMTP_HOST") |> trim_nil()
+    else
+      get_from_settings(:smtp_host)
     end
   end
 
   @doc """
-  Returns SMTP username. ENV `SMTP_USERNAME` overrides Settings.
+  Returns SMTP port as integer.
+
+  Policy:
+  - ENV-only mode (`SMTP_HOST` set): read from ENV `SMTP_PORT`
+  - Settings mode: read from Settings only
+  """
+  @spec smtp_port() :: non_neg_integer() | nil
+  def smtp_port do
+    if smtp_env_mode?() do
+      parse_smtp_port_env(System.get_env("SMTP_PORT"))
+    else
+      get_from_settings_integer(:smtp_port)
+    end
+  end
+
+  @doc """
+  Returns SMTP username.
+
+  Policy:
+  - ENV-only mode (`SMTP_HOST` set): read from ENV `SMTP_USERNAME`
+  - Settings mode: read from Settings only
   """
   @spec smtp_username() :: String.t() | nil
   def smtp_username do
-    smtp_env_or_setting("SMTP_USERNAME", :smtp_username)
+    if smtp_env_mode?() do
+      System.get_env("SMTP_USERNAME") |> trim_nil()
+    else
+      get_from_settings(:smtp_username)
+    end
   end
 
   @doc """
   Returns SMTP password.
 
-  Priority: `SMTP_PASSWORD` ENV > `SMTP_PASSWORD_FILE` (file contents) > Settings.
+  Policy:
+  - ENV-only mode (`SMTP_HOST` set): `SMTP_PASSWORD` > `SMTP_PASSWORD_FILE`
+  - Settings mode: read from Settings only
+
   Strips trailing whitespace/newlines from file contents.
   """
   @spec smtp_password() :: String.t() | nil
   def smtp_password do
-    case System.get_env("SMTP_PASSWORD") do
-      nil -> smtp_password_from_file_or_settings()
-      value -> trim_nil(value)
+    if smtp_env_mode?() do
+      case System.get_env("SMTP_PASSWORD") do
+        nil -> smtp_password_from_file()
+        value -> trim_nil(value)
+      end
+    else
+      get_smtp_password_from_settings()
     end
   end
 
-  defp smtp_password_from_file_or_settings do
+  defp smtp_password_from_file do
     case System.get_env("SMTP_PASSWORD_FILE") do
-      nil -> get_smtp_password_from_settings()
+      nil -> nil
       path -> read_smtp_password_file(path)
     end
   end
@@ -533,11 +554,18 @@ defmodule Mv.Config do
 
   @doc """
   Returns SMTP TLS/SSL mode string (e.g. 'tls', 'ssl', 'none').
-  ENV `SMTP_SSL` overrides Settings.
+
+  Policy:
+  - ENV-only mode (`SMTP_HOST` set): read from ENV `SMTP_SSL`
+  - Settings mode: read from Settings only
   """
   @spec smtp_ssl() :: String.t() | nil
   def smtp_ssl do
-    smtp_env_or_setting("SMTP_SSL", :smtp_ssl)
+    if smtp_env_mode?() do
+      System.get_env("SMTP_SSL") |> trim_nil()
+    else
+      get_from_settings(:smtp_ssl)
+    end
   end
 
   @doc """
@@ -549,12 +577,32 @@ defmodule Mv.Config do
   end
 
   @doc """
-  Returns true when any SMTP ENV variable is set (used in Settings UI for hints).
+  Returns true when SMTP is managed by environment variables.
+
+  Policy: if `SMTP_HOST` is set, SMTP is treated as ENV-only.
   """
-  @spec smtp_env_configured?() :: boolean()
-  def smtp_env_configured? do
-    smtp_host_env_set?() or smtp_port_env_set?() or smtp_username_env_set?() or
-      smtp_password_env_set?() or smtp_ssl_env_set?()
+  @spec smtp_env_mode?() :: boolean()
+  def smtp_env_mode? do
+    smtp_host_env_set?()
+  end
+
+  @doc """
+  Returns missing required SMTP ENV keys for ENV-only mode warnings.
+
+  Required in ENV-only mode:
+  - `SMTP_USERNAME`
+  - one of `SMTP_PASSWORD` or `SMTP_PASSWORD_FILE`
+  """
+  @spec smtp_missing_required_env_keys() :: [String.t()]
+  def smtp_missing_required_env_keys do
+    if smtp_env_mode?() do
+      []
+      |> maybe_add_missing("SMTP_USERNAME", smtp_username_env_set?())
+      |> maybe_add_missing("SMTP_PASSWORD/SMTP_PASSWORD_FILE", smtp_password_env_set?())
+      |> Enum.reverse()
+    else
+      []
+    end
   end
 
   @doc "Returns true if SMTP_HOST ENV is set."
@@ -618,14 +666,18 @@ defmodule Mv.Config do
   @spec mail_from_email_env_set?() :: boolean()
   def mail_from_email_env_set?, do: env_set?("MAIL_FROM_EMAIL")
 
-  # Reads a plain string SMTP setting: ENV first, then Settings.
-  defp smtp_env_or_setting(env_key, setting_key) do
-    case System.get_env(env_key) do
-      nil -> get_from_settings(setting_key)
-      value -> trim_nil(value)
+  defp parse_smtp_port_env(value) when is_binary(value) do
+    case Integer.parse(String.trim(value)) do
+      {port, _} when port > 0 -> port
+      _ -> nil
     end
   end
 
+  defp parse_smtp_port_env(_), do: nil
+
+  defp maybe_add_missing(acc, _label, true), do: acc
+  defp maybe_add_missing(acc, label, false), do: [label | acc]
+
   # Reads an integer setting attribute from Settings.
   defp get_from_settings_integer(key) do
     case Mv.Membership.get_settings() do

lib/mv_web/components/core_components.ex

@@ -938,6 +938,16 @@ defmodule MvWeb.CoreComponents do
     doc:
       "when true, thead th get lg:sticky lg:top-0 bg-base-100 z-10 for use inside a scroll container on desktop"
 
+  attr :wrapper_overflow_class, :string,
+    default: "overflow-x-auto",
+    doc:
+      "overflow class for the table wrapper; set to overflow-visible when outer container owns scrolling"
+
+  attr :sticky_first_col, :boolean,
+    default: false,
+    doc:
+      "when true, first header/body column gets sticky left positioning to keep selection controls visible"
+
   slot :col, required: true do
     attr :label, :string
     attr :class, :string
@@ -974,15 +984,19 @@ defmodule MvWeb.CoreComponents do
     ~H"""
     <div
       id={@row_click && "#{@id}-keyboard"}
-      class="overflow-auto"
+      class={@wrapper_overflow_class}
+      data-sticky-first-col-rows={@sticky_first_col && "true"}
       phx-hook={@row_click && "TableRowKeydown"}
     >
       <table class="table table-zebra">
         <thead>
           <tr>
             <th
-              :for={col <- @col}
-              class={table_th_class(col, @sticky_header)}
+              :for={{col, col_idx} <- Enum.with_index(@col)}
+              class={[
+                table_th_class(col, @sticky_header),
+                @sticky_first_col && col_idx == 0 && "sticky left-0 z-30 bg-base-100"
+              ]}
               aria-sort={table_th_aria_sort(col, @sort_field, @sort_order)}
             >
               {col[:label]}
@@ -1006,7 +1020,13 @@ defmodule MvWeb.CoreComponents do
           <tr
             :for={row <- @rows}
             id={@row_id && @row_id.(row)}
-            class={table_row_tr_class(@row_click, table_row_selected?(assigns, row))}
+            class={[
+              table_row_tr_class(
+                table_row_selected?(assigns, row),
+                @sticky_first_col
+              )
+            ]}
+            data-row-interactive={@row_click && "true"}
             data-selected={table_row_selected?(assigns, row) && "true"}
             title={@row_click && @row_tooltip}
           >
@@ -1026,6 +1046,13 @@ defmodule MvWeb.CoreComponents do
                 has_click = col[:col_click] || @row_click
                 classes = ["max-w-xs"]
 
+                classes =
+                  if @sticky_first_col && col_idx == 0 do
+                    ["sticky-first-col-cell sticky left-0 z-20" | classes]
+                  else
+                    classes
+                  end
+
                 classes =
                   if col_class == nil || (col_class && !String.contains?(col_class, "text-center")) do
                     ["truncate" | classes]
@@ -1040,7 +1067,7 @@ defmodule MvWeb.CoreComponents do
                     classes
                   end
 
-                # WCAG: no focus ring on the cell itself; row shows focus via focus-within
+                # WCAG: no focus ring on the cell itself; sticky zebra rows show keyboard focus via CSS :has(:focus-visible)
                 classes =
                   if @row_click && @first_row_click_col_idx == col_idx do
                     [
@@ -1111,30 +1138,11 @@ defmodule MvWeb.CoreComponents do
     end
   end
 
-  # Returns CSS classes for table row: hover/focus-within outline when row_click is set,
-  # and stronger selected outline when selected (WCAG: not color-only).
-  # Hover/focus-within are omitted for the selected row so the selected ring stays visible.
-  defp table_row_tr_class(row_click, selected?) do
-    has_row_click? = not is_nil(row_click)
-    base = []
-
-    base =
-      if has_row_click? and not selected?,
-        do:
-          base ++
-            [
-              "hover:ring-2",
-              "hover:ring-inset",
-              "hover:ring-base-content/10",
-              "focus-within:ring-2",
-              "focus-within:ring-inset",
-              "focus-within:ring-base-content/10"
-            ],
-        else: base
-
-    base = if selected?, do: base ++ ["ring-2", "ring-inset", "ring-primary"], else: base
-    Enum.join(base, " ")
-  end
+  # Returns CSS classes for table row selection styles.
+  # Hover/focus row highlighting is CSS-driven via [data-row-interactive] selectors in app.css.
+  # Sticky-first-column zebra tables use CSS accents and omit selected row ring classes.
+  defp table_row_tr_class(true, false), do: "ring-2 ring-inset ring-primary"
+  defp table_row_tr_class(_, _), do: ""
 
   defp table_th_aria_sort(col, sort_field, sort_order) do
     col_sort = Map.get(col, :sort_field)

lib/mv_web/live/global_settings_live.ex

@@ -85,14 +85,8 @@ defmodule MvWeb.GlobalSettingsLive do
       |> assign(:oidc_configured, Mv.Config.oidc_configured?())
       |> assign(:oidc_client_secret_set, Mv.Config.oidc_client_secret_set?())
       |> assign(:registration_enabled, settings.registration_enabled != false)
-      |> assign(:smtp_env_configured, Mv.Config.smtp_env_configured?())
-      |> assign(:smtp_host_env_set, Mv.Config.smtp_host_env_set?())
-      |> assign(:smtp_port_env_set, Mv.Config.smtp_port_env_set?())
-      |> assign(:smtp_username_env_set, Mv.Config.smtp_username_env_set?())
-      |> assign(:smtp_password_env_set, Mv.Config.smtp_password_env_set?())
-      |> assign(:smtp_ssl_env_set, Mv.Config.smtp_ssl_env_set?())
-      |> assign(:smtp_from_name_env_set, Mv.Config.mail_from_name_env_set?())
-      |> assign(:smtp_from_email_env_set, Mv.Config.mail_from_email_env_set?())
+      |> assign(:smtp_env_mode, Mv.Config.smtp_env_mode?())
+      |> assign(:smtp_missing_required_env_keys, Mv.Config.smtp_missing_required_env_keys())
       |> assign(:smtp_password_set, present?(Mv.Config.smtp_password()))
       |> assign(:smtp_configured, Mv.Config.smtp_configured?())
       |> assign(:smtp_test_result, nil)
@@ -321,12 +315,25 @@ defmodule MvWeb.GlobalSettingsLive do
         </.form_section>
         <%!-- SMTP / E-Mail Section --%>
         <.form_section title={gettext("SMTP / E-Mail")}>
-          <%= if @smtp_env_configured do %>
+          <%= if @smtp_env_mode do %>
             <p class="text-sm text-base-content/70 mb-4">
-              {gettext("Some values are set via environment variables. Those fields are read-only.")}
+              {gettext(
+                "SMTP is fully managed via environment variables. All SMTP fields are read-only."
+              )}
             </p>
           <% end %>
 
+          <%= if @smtp_env_mode and @smtp_missing_required_env_keys != [] do %>
+            <div class="mb-4 flex items-start gap-2 p-3 rounded-lg border border-warning bg-warning/10 text-warning-aa text-sm">
+              <.icon name="hero-exclamation-triangle" class="size-5 shrink-0 mt-0.5" />
+              <span>
+                {gettext("SMTP environment configuration appears incomplete. Missing: %{keys}",
+                  keys: Enum.join(@smtp_missing_required_env_keys, ", ")
+                )}
+              </span>
+            </div>
+          <% end %>
+
           <%= if @environment == :prod and not @smtp_configured do %>
             <div class="mb-4 flex items-start gap-2 p-3 rounded-lg border border-warning bg-warning/10 text-warning-aa text-sm">
               <.icon name="hero-exclamation-triangle" class="size-5 shrink-0 mt-0.5" />
@@ -345,32 +352,26 @@ defmodule MvWeb.GlobalSettingsLive do
                   field={@form[:smtp_host]}
                   type="text"
                   label={gettext("Host")}
-                  disabled={@smtp_host_env_set}
-                  placeholder={
-                    if(@smtp_host_env_set,
-                      do: gettext("From SMTP_HOST"),
-                      else: "smtp.example.com"
-                    )
-                  }
+                  disabled={@smtp_env_mode}
+                  placeholder="smtp.example.com"
                 />
                 <.input
                   field={@form[:smtp_port]}
                   type="number"
                   label={gettext("Port")}
-                  disabled={@smtp_port_env_set}
-                  placeholder={if(@smtp_port_env_set, do: gettext("From SMTP_PORT"), else: "587")}
+                  disabled={@smtp_env_mode}
+                  placeholder="587"
                 />
                 <.input
                   field={@form[:smtp_ssl]}
                   type="select"
                   label={gettext("TLS/SSL")}
-                  disabled={@smtp_ssl_env_set}
+                  disabled={@smtp_env_mode}
                   options={[
                     {gettext("TLS (port 587, recommended)"), "tls"},
                     {gettext("SSL (port 465)"), "ssl"},
                     {gettext("None (port 25, insecure)"), "none"}
                   ]}
-                  placeholder={if(@smtp_ssl_env_set, do: gettext("From SMTP_SSL"), else: nil)}
                 />
               </div>
 
@@ -379,28 +380,20 @@ defmodule MvWeb.GlobalSettingsLive do
                   field={@form[:smtp_username]}
                   type="text"
                   label={gettext("Username")}
-                  disabled={@smtp_username_env_set}
-                  placeholder={
-                    if(@smtp_username_env_set,
-                      do: gettext("From SMTP_USERNAME"),
-                      else: "user@example.com"
-                    )
-                  }
+                  disabled={@smtp_env_mode}
+                  placeholder="user@example.com"
                 />
                 <.input
                   field={@form[:smtp_password]}
                   type="password"
                   label={gettext("Password")}
-                  disabled={@smtp_password_env_set}
+                  disabled={@smtp_env_mode}
                   placeholder={
-                    if(@smtp_password_env_set,
-                      do: gettext("From SMTP_PASSWORD"),
-                      else:
-                        if(@smtp_password_set,
-                          do: gettext("Leave blank to keep current"),
-                          else: nil
-                        )
-                    )
+                    if @smtp_env_mode do
+                      gettext("From SMTP_PASSWORD")
+                    else
+                      if @smtp_password_set, do: gettext("Leave blank to keep current"), else: nil
+                    end
                   }
                 />
               </div>
@@ -410,22 +403,15 @@ defmodule MvWeb.GlobalSettingsLive do
                   field={@form[:smtp_from_email]}
                   type="email"
                   label={gettext("Sender email (From)")}
-                  disabled={@smtp_from_email_env_set}
-                  placeholder={
-                    if(@smtp_from_email_env_set,
-                      do: gettext("From MAIL_FROM_EMAIL"),
-                      else: "noreply@example.com"
-                    )
-                  }
+                  disabled={@smtp_env_mode}
+                  placeholder="noreply@example.com"
                 />
                 <.input
                   field={@form[:smtp_from_name]}
                   type="text"
                   label={gettext("Sender name (From)")}
-                  disabled={@smtp_from_name_env_set}
-                  placeholder={
-                    if(@smtp_from_name_env_set, do: gettext("From MAIL_FROM_NAME"), else: "Mila")
-                  }
+                  disabled={@smtp_env_mode}
+                  placeholder="Mila"
                 />
               </div>
             </div>
@@ -435,11 +421,7 @@ defmodule MvWeb.GlobalSettingsLive do
               )}
             </p>
             <.button
-              :if={
-                not (@smtp_host_env_set and @smtp_port_env_set and @smtp_username_env_set and
-                       @smtp_password_env_set and @smtp_ssl_env_set and @smtp_from_email_env_set and
-                       @smtp_from_name_env_set)
-              }
+              :if={not @smtp_env_mode}
               phx-disable-with={gettext("Saving...")}
               variant="primary"
               class="mt-2"
@@ -925,9 +907,9 @@ defmodule MvWeb.GlobalSettingsLive do
           |> assign(:oidc_only, Mv.Config.oidc_only?())
           |> assign(:oidc_configured, Mv.Config.oidc_configured?())
           |> assign(:smtp_configured, Mv.Config.smtp_configured?())
+          |> assign(:smtp_env_mode, Mv.Config.smtp_env_mode?())
+          |> assign(:smtp_missing_required_env_keys, Mv.Config.smtp_missing_required_env_keys())
           |> assign(:smtp_password_set, present?(Mv.Config.smtp_password()))
-          |> assign(:smtp_from_name_env_set, Mv.Config.mail_from_name_env_set?())
-          |> assign(:smtp_from_email_env_set, Mv.Config.mail_from_email_env_set?())
           |> assign(:vereinfacht_test_result, test_result)
           |> put_flash(:success, gettext("Settings updated successfully"))
           |> assign_form()
@@ -1267,25 +1249,17 @@ defmodule MvWeb.GlobalSettingsLive do
   end
 
   defp merge_smtp_env_values(s) do
-    s
-    |> put_if_env_set(:smtp_host, Mv.Config.smtp_host_env_set?(), Mv.Config.smtp_host())
-    |> put_if_env_set(:smtp_port, Mv.Config.smtp_port_env_set?(), Mv.Config.smtp_port())
-    |> put_if_env_set(
-      :smtp_username,
-      Mv.Config.smtp_username_env_set?(),
-      Mv.Config.smtp_username()
-    )
-    |> put_if_env_set(:smtp_ssl, Mv.Config.smtp_ssl_env_set?(), Mv.Config.smtp_ssl())
-    |> put_if_env_set(
-      :smtp_from_email,
-      Mv.Config.mail_from_email_env_set?(),
-      Mv.Config.mail_from_email()
-    )
-    |> put_if_env_set(
-      :smtp_from_name,
-      Mv.Config.mail_from_name_env_set?(),
-      Mv.Config.mail_from_name()
-    )
+    if Mv.Config.smtp_env_mode?() do
+      s
+      |> Map.put(:smtp_host, Mv.Config.smtp_host())
+      |> Map.put(:smtp_port, Mv.Config.smtp_port())
+      |> Map.put(:smtp_username, Mv.Config.smtp_username())
+      |> Map.put(:smtp_ssl, Mv.Config.smtp_ssl())
+      |> Map.put(:smtp_from_email, Mv.Config.mail_from_email())
+      |> Map.put(:smtp_from_name, Mv.Config.mail_from_name())
+    else
+      s
+    end
   end
 
   defp enrich_sync_errors([]), do: []

lib/mv_web/live/member_live/index.html.heex

@@ -105,7 +105,9 @@
     <.table
       id="members"
       rows={@members}
+      wrapper_overflow_class="overflow-visible"
       sticky_header={true}
+      sticky_first_col={true}
       row_id={fn member -> "row-#{member.id}" end}
       row_click={fn member -> JS.push("select_row_and_navigate", value: %{id: member.id}) end}
       row_tooltip={gettext("Click for member details")}