phoenix_kit

defmodule PhoenixKit.Modules.Storage.Dimension do
  @moduledoc """
  Schema for dimension presets for automatic file variant generation.

  Dimensions define target sizes and quality settings for automatically
  generating different versions of uploaded images and videos.

  ## Fields

  - `name` - Unique name for this dimension (e.g., "thumbnail", "medium")
  - `width` - Target width in pixels (nullable = maintain aspect ratio)
  - `height` - Target height in pixels (nullable = maintain aspect ratio)
  - `quality` - Quality setting (1-100 for images, CRF 0-51 for videos)
  - `format` - Output format override (nullable = preserve original)
  - `applies_to` - What this dimension applies to: "image", "video", or "both"
  - `enabled` - Whether this dimension is active
  - `order` - Display order in admin interface

  ## Quality Settings

  ### Images (JPEG, WebP, PNG)
  - Range: 1-100
  - 85 = Good quality (default)
  - 95 = High quality
  - 70 = Medium quality

  ### Videos (MP4, WebM)
  - Range: 0-51 (CRF - Constant Rate Factor)
  - Lower = Higher quality
  - 23 = Good quality (default)
  - 18 = High quality
  - 28 = Medium quality

  ## Examples

      # Image thumbnail
      %Dimension{
        name: "thumbnail",
        width: 150,
        height: 150,
        quality: 85,
        format: "jpg",
        applies_to: "image",
        enabled: true,
        order: 1
      }

      # Video 720p variant
      %Dimension{
        name: "720p",
        width: 1280,
        height: 720,
        quality: 23,
        format: "mp4",
        applies_to: "video",
        enabled: true,
        order: 2
      }

      # Responsive image (maintain aspect ratio)
      %Dimension{
        name: "large",
        width: 1920,
        height: nil,  # Maintain aspect ratio
        quality: 85,
        format: nil,  # Preserve original
        applies_to: "image",
        enabled: true,
        order: 3
      }
  """
  use Ecto.Schema
  use PhoenixKit.SchemaPrefix
  import Ecto.Changeset

  alias PhoenixKit.Modules.Storage.DimensionOptions

  @primary_key {:uuid, UUIDv7, autogenerate: true}
  @foreign_key_type UUIDv7

  # The sizes every variant set has (V205): a size's name is part of every
  # file URL, and core and modules ask for these by name. The first three
  # of `@aspect_slots` feed grids and justified layouts, so they keep the
  # aspect ratio; only `thumbnail` may be cropped.
  @crop_modes ~w(center focus)
  @shapes ~w(any wide tall)
  @fit_sides ~w(width height)
  @standard_slots ~w(thumbnail small medium large video_thumbnail)
  @aspect_slots ~w(small medium large)

  @type t :: %__MODULE__{
          uuid: UUIDv7.t() | nil,
          name: String.t() | nil,
          width: integer() | nil,
          height: integer() | nil,
          quality: integer() | nil,
          format: String.t() | nil,
          applies_to: String.t() | nil,
          enabled: boolean(),
          maintain_aspect_ratio: boolean(),
          options: PhoenixKit.Modules.Storage.DimensionOptions.t(),
          alternative_formats: [String.t()],
          order: integer(),
          variant_set_uuid: UUIDv7.t() | nil,
          inserted_at: DateTime.t() | nil,
          updated_at: DateTime.t() | nil
        }

  schema "phoenix_kit_storage_dimensions" do
    field :name, :string
    field :width, :integer
    field :height, :integer
    field :quality, :integer
    field :format, :string
    field :applies_to, :string
    field :enabled, :boolean, default: true
    field :maintain_aspect_ratio, :boolean, default: true
    # The rendition's options (V217): how a fixed box is cropped, which side a
    # proportional one fixes, who it is made for, whether it keeps an HDR gain map.
    # One JSON object with a typed struct (`DimensionOptions`); `shape` and the
    # others are not part of the spec hash, as they were not as columns: they decide
    # whether a file gets the size, not what the size looks like.
    embeds_one :options, PhoenixKit.Modules.Storage.DimensionOptions,
      on_replace: :update,
      defaults_to_struct: true

    field :alternative_formats, {:array, :string}, default: []
    field :order, :integer, default: 0

    # The variant set the size belongs to (V205). The column defaults to the
    # Default set, so a writer that names none lands there;
    # `read_after_writes` reads the default back.
    field :variant_set_uuid, UUIDv7, read_after_writes: true

    timestamps(type: :utc_datetime)
  end

  @doc """
  Changeset for creating or updating a dimension.

  ## Required Fields

  - `name`
  - `applies_to`
  - `width` - Required when `maintain_aspect_ratio` is true or false

  ## Optional Fields

  - `height` - Required when `maintain_aspect_ratio` is false (fixed dimensions)
  - `maintain_aspect_ratio` - Whether to preserve aspect ratio (default: true)

  ## Validation Rules

  - Name must be unique
  - Width must be specified (always required)
  - Height must be specified when `maintain_aspect_ratio` is false
  - Width and height must be positive integers
  - Quality must be between 1-100 for images or 0-51 for videos
  - Applies to must be one of: "image", "video", "both"
  - Format must be valid if specified
  - Order must be >= 0
  """
  def changeset(dimension, attrs) do
    dimension
    |> cast(fold_options(attrs), [
      :name,
      :width,
      :height,
      :quality,
      :format,
      :applies_to,
      :enabled,
      :maintain_aspect_ratio,
      :alternative_formats,
      :order
    ])
    |> cast_embed(:options, with: &DimensionOptions.changeset/2)
    |> validate_required([:name, :applies_to])
    |> validate_format(:name, ~r/^[a-z0-9_]+$/,
      message: "must contain only lowercase letters, numbers, and underscores"
    )
    |> validate_length(:name, min: 1, max: 50)
    |> validate_inclusion(:applies_to, ["image", "video", "both"])
    |> surface_option_errors()
    |> validate_number(:width, greater_than: 0)
    |> validate_number(:height, greater_than: 0)
    |> validate_number(:order, greater_than_or_equal_to: 0)
    |> validate_dimension_size()
    |> clear_width_when_height_fixed()
    |> validate_quality()
    |> validate_format()
    |> validate_alternative_formats()
    |> validate_standard_slot()
    |> validate_standard_fit_side()
    |> validate_standard_shape()
    |> unique_constraint(:name, name: :phoenix_kit_storage_dimensions_name_index)
  end

  # The options a form or a caller names at the top level (`crop_mode: "focus"`,
  # `"keep_hdr" => "true"`) go into `options`, whichever kind of key the map uses
  # (Ecto allows one kind per map). A map that already has `options` keeps them and
  # the top-level names win.
  defp fold_options(attrs) when is_map(attrs) do
    names = DimensionOptions.keys()
    keys = Enum.flat_map(names, &[&1, Atom.to_string(&1)])
    {flat, rest} = Map.split(attrs, keys)

    if flat == %{} do
      attrs
    else
      string_keys? = Enum.any?(Map.keys(rest) ++ Map.keys(flat), &is_binary/1)
      existing = Map.get(rest, :options) || Map.get(rest, "options") || %{}

      merged =
        Map.new(existing, fn {k, v} -> {to_string(k), v} end)
        |> Map.merge(Map.new(flat, fn {k, v} -> {to_string(k), v} end))

      rest
      |> Map.drop([:options, "options"])
      |> Map.put(if(string_keys?, do: "options", else: :options), merged)
    end
  end

  defp fold_options(attrs), do: attrs

  # An option's error shows under its own name in the editor (`render_error(cs, :shape)`),
  # as it did when each was a column of its own.
  defp surface_option_errors(%Ecto.Changeset{changes: %{options: %Ecto.Changeset{} = opts}} = cs) do
    Enum.reduce(opts.errors, cs, fn {key, {message, meta}}, acc ->
      add_error(acc, key, message, meta)
    end)
  end

  defp surface_option_errors(cs), do: cs

  # An option as the changeset has it: the changed value, else the stored one.
  defp option(changeset, key) do
    case get_field(changeset, :options) do
      %DimensionOptions{} = options -> Map.get(options, key)
      _ -> Map.get(%DimensionOptions{}, key)
    end
  end

  # Whether the form changed `key` (or the size is new, so everything is set).
  defp option_changed?(changeset, key) do
    case changeset.changes do
      %{options: %Ecto.Changeset{changes: changes}} -> Map.has_key?(changes, key)
      _ -> false
    end
  end

  @doc """
  A `%Dimension{}` built from a keyword list or map whose keys may include the
  options (`crop_mode`, `fit_by`, `shape`, `keep_hdr`) at the top level, as the
  changeset takes them. For code and tests that need a size without a database.
  """
  @spec new(Enumerable.t()) :: t()
  def new(attrs \\ []) do
    {options, rest} = attrs |> Map.new() |> Map.split(DimensionOptions.keys())
    struct!(__MODULE__, Map.put(rest, :options, struct!(DimensionOptions, options)))
  end

  @doc "How a rendition is cropped when it is a fixed box: `center` or `focus`."
  def crop_mode(%__MODULE__{options: %DimensionOptions{crop_mode: mode}}), do: mode
  def crop_mode(_), do: "center"

  @doc "The side a rendition that keeps proportions fixes: `width` or `height`."
  def fit_by(%__MODULE__{options: %DimensionOptions{fit_by: side}}), do: side
  def fit_by(_), do: "width"

  @doc "Which pictures the rendition is made for: `any`, `wide` or `tall`."
  def shape(%__MODULE__{options: %DimensionOptions{shape: shape}}), do: shape
  def shape(_), do: "any"

  @doc "Whether the rendition of an HDR photo keeps the gain map (when it can)."
  def keep_hdr?(%__MODULE__{options: %DimensionOptions{keep_hdr: keep}}), do: keep == true
  def keep_hdr?(_), do: false

  @doc "Whether the rendition leaves the camera's metadata out (on unless a size says otherwise)."
  def strip_metadata?(%__MODULE__{options: %DimensionOptions{strip_metadata: strip}}),
    do: strip != false

  def strip_metadata?(_), do: true

  @doc "Whether an animated GIF or WebP stays animated in this rendition (on unless a size says otherwise)."
  def keep_animation?(%__MODULE__{options: %DimensionOptions{keep_animation: keep}}),
    do: keep != false

  def keep_animation?(_), do: true

  @doc "How a fixed rendition can be cropped: around the middle, or around the subject."
  def crop_modes, do: @crop_modes

  @doc """
  Whether `dimension` is cropped around the photo's focal point: a fixed box
  (not one that keeps proportions) whose crop mode is `focus`.
  """
  def focus_crop?(%__MODULE__{maintain_aspect_ratio: false} = dimension),
    do: crop_mode(dimension) == "focus"

  def focus_crop?(_dimension), do: false

  @doc "Which pictures a rendition can be made for: every one, the wide ones, the tall ones."
  def shapes, do: @shapes

  @doc "The side a rendition that keeps proportions can fix: its width, or its height."
  def fit_sides, do: @fit_sides

  @doc """
  Whether `dimension` keeps proportions and fixes its **height** (the width
  follows each photo: a horizontal panorama's thumbnail).
  """
  def fixed_height?(%__MODULE__{maintain_aspect_ratio: true} = dimension),
    do: fit_by(dimension) == "height"

  def fixed_height?(_dimension), do: false

  @doc "The sizes every variant set has; they cannot be renamed or deleted."
  def standard_slots, do: @standard_slots

  @doc "The standard sizes that always keep the aspect ratio."
  def aspect_slots, do: @aspect_slots

  @doc "Whether `dimension` is one of the standard sizes."
  def standard_slot?(%__MODULE__{name: name}), do: name in @standard_slots

  # A standard size keeps its name, and small/medium/large keep the aspect
  # ratio, whatever else an admin changes about them.
  defp validate_standard_slot(changeset) do
    old_name = changeset.data.name
    name = get_field(changeset, :name)

    cond do
      old_name in @standard_slots and name != old_name ->
        add_error(changeset, :name, "is a standard size and cannot be renamed")

      # Checked when the size is made, renamed, or its aspect setting is
      # changed: an install whose `small` was cropped before V205 can still
      # switch it off or change its quality without fixing that first.
      name in @aspect_slots and get_field(changeset, :maintain_aspect_ratio) == false and
          (is_nil(changeset.data.uuid) or Map.has_key?(changeset.changes, :name) or
             Map.has_key?(changeset.changes, :maintain_aspect_ratio)) ->
        add_error(
          changeset,
          :maintain_aspect_ratio,
          "must stay on for %{name}: only thumbnail may be cropped",
          name: name
        )

      true ->
        changeset
    end
  end

  # A rendition that keeps proportions and fixes its height has no width: it follows
  # each photo, and a width left over from before would make the rendition look
  # like a width-picked one (`variant_for/2`).
  defp clear_width_when_height_fixed(changeset) do
    if get_field(changeset, :maintain_aspect_ratio) != false and
         option(changeset, :fit_by) == "height",
       do: put_change(changeset, :width, nil),
       else: changeset
  end

  # The standard sizes are picked by width (`variant_for/2`, the stand-in of a size
  # not made yet), so they keep fixing it. Checked when the size is made, renamed,
  # or its fixed side is changed.
  defp validate_standard_fit_side(changeset) do
    name = get_field(changeset, :name)

    if name in @standard_slots and option(changeset, :fit_by) == "height" and
         (is_nil(changeset.data.uuid) or Map.has_key?(changeset.changes, :name) or
            option_changed?(changeset, :fit_by)) do
      add_error(
        changeset,
        :fit_by,
        "must stay on width for %{name}: the standard sizes are picked by width",
        name: name
      )
    else
      changeset
    end
  end

  # The standard sizes are asked for by name for every picture, so none of them
  # may be limited to wide or tall ones.
  defp validate_standard_shape(changeset) do
    name = get_field(changeset, :name)

    if name in @standard_slots and option(changeset, :shape) != "any" and
         (is_nil(changeset.data.uuid) or Map.has_key?(changeset.changes, :name) or
            option_changed?(changeset, :shape)) do
      add_error(
        changeset,
        :shape,
        "must stay on any picture for %{name}: the standard sizes are made for every one",
        name: name
      )
    else
      changeset
    end
  end

  # Validate dimensions based on maintain_aspect_ratio setting
  defp validate_dimension_size(changeset) do
    width = get_field(changeset, :width)
    height = get_field(changeset, :height)
    maintain_aspect = get_field(changeset, :maintain_aspect_ratio)
    fit_by = option(changeset, :fit_by)

    cond do
      # Keeping proportions with a fixed height: the height is the size, and the
      # width is left to follow each photo.
      maintain_aspect != false and fit_by == "height" and is_nil(height) ->
        add_error(changeset, :height, "height is required when the height is fixed")

      maintain_aspect != false and fit_by == "height" ->
        changeset

      is_nil(width) ->
        add_error(changeset, :width, "width is required")

      maintain_aspect == false && is_nil(height) ->
        add_error(changeset, :height, "height is required when not maintaining aspect ratio")

      true ->
        changeset
    end
  end

  # Validate quality based on file type
  defp validate_quality(changeset) do
    quality = get_field(changeset, :quality)
    applies_to = get_field(changeset, :applies_to)
    format = get_field(changeset, :format)

    cond do
      is_nil(quality) ->
        changeset

      # A video rendition that is a still frame (the video thumbnail) outputs an
      # image, so it uses the image quality scale (1-100), whatever its name
      applies_to == "video" and format in ["jpg", "jpeg", "png", "webp", "gif"] ->
        validate_number(changeset, :quality,
          greater_than_or_equal_to: 1,
          less_than_or_equal_to: 100
        )

      applies_to in ["image", "both"] ->
        validate_number(changeset, :quality,
          greater_than_or_equal_to: 1,
          less_than_or_equal_to: 100
        )

      applies_to == "video" ->
        validate_number(changeset, :quality,
          greater_than_or_equal_to: 0,
          less_than_or_equal_to: 51
        )

      true ->
        changeset
    end
  end

  # Validate format is supported
  defp validate_format(changeset) do
    format = get_field(changeset, :format)
    applies_to = get_field(changeset, :applies_to)

    if is_nil(format) do
      changeset
    else
      valid_formats = get_valid_formats(applies_to)

      if format in valid_formats do
        changeset
      else
        add_error(changeset, :format, "must be one of: #{Enum.join(valid_formats, ", ")}")
      end
    end
  end

  # Validate alternative_formats: must be valid image formats, no duplicates, exclude primary format
  defp validate_alternative_formats(changeset) do
    alt_formats = get_field(changeset, :alternative_formats) || []
    primary_format = get_field(changeset, :format)
    applies_to = get_field(changeset, :applies_to)

    # Filter out empty strings (from hidden checkbox input)
    alt_formats = Enum.reject(alt_formats, &(&1 == ""))
    changeset = put_change(changeset, :alternative_formats, alt_formats)

    cond do
      alt_formats == [] ->
        changeset

      applies_to == "video" ->
        add_error(changeset, :alternative_formats, "not supported for video-only dimensions")

      true ->
        valid = get_valid_image_formats()
        invalid = Enum.reject(alt_formats, &(&1 in valid))
        has_primary = primary_format && primary_format in alt_formats
        has_dupes = length(alt_formats) != length(Enum.uniq(alt_formats))

        changeset
        |> then(fn cs ->
          if invalid != [],
            do:
              add_error(cs, :alternative_formats, "invalid formats: #{Enum.join(invalid, ", ")}"),
            else: cs
        end)
        |> then(fn cs ->
          if has_primary,
            do: add_error(cs, :alternative_formats, "must not include the primary format"),
            else: cs
        end)
        |> then(fn cs ->
          if has_dupes,
            do: add_error(cs, :alternative_formats, "must not contain duplicates"),
            else: cs
        end)
    end
  end

  defp get_valid_image_formats, do: ["jpg", "jpeg", "png", "webp", "avif", "gif"]

  defp get_valid_formats("image"), do: ["jpg", "jpeg", "png", "webp", "gif"]
  # Videos can output video formats, but video_thumbnail outputs JPG images
  defp get_valid_formats("video"), do: ["mp4", "webm", "avi", "mov", "jpg", "jpeg", "png", "webp"]

  defp get_valid_formats("both"),
    do: ["jpg", "jpeg", "png", "webp", "gif", "mp4", "webm", "avi", "mov"]

  @doc """
  Returns whether this dimension applies to images.
  """
  def applies_to_images?(%__MODULE__{applies_to: applies_to})
      when applies_to in ["image", "both"],
      do: true

  def applies_to_images?(_), do: false

  @doc """
  Returns whether this dimension applies to videos.
  """
  def applies_to_videos?(%__MODULE__{applies_to: applies_to})
      when applies_to in ["video", "both"],
      do: true

  def applies_to_videos?(_), do: false

  @doc """
  Returns whether this dimension preserves aspect ratio.
  """
  def preserve_aspect_ratio?(%__MODULE__{maintain_aspect_ratio: maintain_aspect}) do
    maintain_aspect == true
  end

  @doc """
  Returns a human-readable description of this dimension.
  """
  def description(%__MODULE__{
        name: name,
        width: width,
        height: height,
        format: format,
        maintain_aspect_ratio: maintain_aspect
      }) do
    size_desc =
      cond do
        maintain_aspect && width -> "#{width}px wide (aspect ratio maintained)"
        width && height -> "#{width}x#{height}"
        width -> "#{width}px wide"
        height -> "#{height}px tall"
        true -> "auto"
      end

    format_desc = if format, do: " (#{format})", else: ""
    "#{name}: #{size_desc}#{format_desc}"
  end
end