@spec actor_opts(Phoenix.LiveView.Socket.t()) :: actor_opts()

Extracts [actor_uuid: uuid] from socket.assigns.phoenix_kit_current_user.

Returns [] when no user is signed in. Pass the result straight into any PhoenixKitCatalogue.Catalogue mutating function as its trailing opts argument.

@spec actor_uuid(Phoenix.LiveView.Socket.t()) :: Ecto.UUID.t() | nil

Returns the current user's UUID from socket assigns, or nil.

@spec derive_activity_action(String.t(), String.t() | nil) :: String.t() | nil

Maps an LV operation string + entity_type to the canonical activity action atom the catalogue context already uses on the success path.

Falls back to nil when the operation doesn't follow the <verb>_<entity> shape; the caller skips the audit-row write in that case (engineer log still fires).

@spec escape_html(String.t() | nil) :: String.t()

HTML-escapes a string for safe interpolation into raw markup.

@spec format_byte_size(integer() | nil) :: String.t()

Human-readable byte size with B / KB / MB / GB suffixes.

@spec format_time_ago(DateTime.t() | nil) :: String.t()

Translated relative-time label for a timestamp.

Buckets: < 1m → "just now", < 1h → "Nm ago", < 1d → "Nh ago", < 1w → "Nd ago", else Mon DD, YYYY (locale-formatted via gettext'd strftime template).

@spec log_operation_error(Phoenix.LiveView.Socket.t(), String.t(), map()) :: :ok

Logs a failed LV mutation in two places at once:

1. Engineer log — Logger.error with the operation, the LV-level entity context, and the changeset / atom reason. This is the rich-context line that production-incident triage reads.
2. User-visible audit row — an Activity entry with the same action atom the success path would have written, plus metadata.db_pending: true. The audit feed therefore records what the user attempted, not just what succeeded — a deliberate change in the post-Apr 2026 pipeline (workspace AGENTS.md C12 agent #2 — "Activity logging coverage").

The action atom is derived from operation via derive_activity_action/2. Validation cycles (form-validate events) never reach this helper — by construction it's only called from {:error, _} handle_event branches, where the failure is a real infrastructure / consistency error worth auditing.

Expected context keys

• :entity_type — "item" / "category" / "catalogue" / "manufacturer" / "supplier" (drives both the activity resource_type and the action-atom prefix).
• :entity_uuid — primary-key UUID; lands as resource_uuid.
• :reason — an %Ecto.Changeset{}, an atom, or any other inspectable shape. Logged engineer-side; on the audit row it's summarised into PII-safe metadata.error_keys (changeset field names only — never values, since user-typed strings can carry PII).

Activity-log failures (missing table, ownership errors, sandbox exit) are swallowed by ActivityLog.log/1; they never bubble up to the LV.

@spec pdf_error_message(map()) :: String.t() | nil

Pulls the error_message off a (possibly preloaded) Pdf row; nil if no error.

@spec pdf_extracted_at(map()) :: DateTime.t() | NaiveDateTime.t() | nil

Pulls the extracted_at timestamp off a (possibly preloaded) Pdf row; nil if not extracted.

@spec pdf_extraction_pages(map()) :: integer() | nil

Pulls the page count off a (possibly preloaded) Pdf row; returns nil if unknown.

@spec pdf_extraction_status(map()) :: String.t()

Pulls the extraction status off a (possibly preloaded) Pdf row; defaults to pending.

@spec pdf_status_badge_class(String.t()) :: String.t()

daisyUI badge class for an extraction status string.

@spec pdf_status_label(String.t()) :: String.t()

Translated label for an extraction status.

@spec status_label(String.t() | nil) :: String.t()

Translates a catalogue/category/item/manufacturer/supplier status field value to a localised label via gettext.

Handles every status string that any catalogue schema can emit (active / inactive / archived / deleted / discontinued) with explicit literal gettext(...) clauses so mix gettext.extract picks them up. Unknown status values pass through unchanged — never use String.capitalize/1 on translated text because the result would pin English casing on a value the extractor can't see.