kino

defmodule Kino.Input do
  @moduledoc """
  Various input elements for entering data.

  ## Examples

  First, create an input and make sure it is rendered,
  either by placing it at the end of a code cell or by
  explicitly rendering it with `Kino.render/1`.

      input = Kino.Input.text("Name")

  Then read the value after the input has been rendered:

      name = Kino.Input.read(input)

  All inputs are shared by default: once you change the input,
  your changes will be immediately replicated to all users
  reading the notebook. Use `Kino.Control.form/2` if you want
  each user to have their own input.

  ## Async API

  You can subscribe to input changes or use the `Stream`
  API for event feed. See the `Kino.Control` module for
  more details.
  """

  defstruct [:ref, :id, :destination, :attrs]

  @opaque t :: %__MODULE__{
            ref: Kino.Output.ref(),
            id: String.t(),
            destination: Process.dest(),
            attrs: map()
          }

  defp new(attrs) do
    token = Kino.Bridge.generate_token()
    persistent_id = {token, attrs} |> :erlang.phash2() |> Integer.to_string()

    ref = Kino.Output.random_ref()
    subscription_manager = Kino.SubscriptionManager.cross_node_name()

    Kino.Bridge.reference_object(ref, self())
    Kino.Bridge.monitor_object(ref, subscription_manager, {:clear_topic, ref})

    %__MODULE__{ref: ref, id: persistent_id, destination: subscription_manager, attrs: attrs}
  end

  @doc false
  def duplicate(input) do
    input.attrs
    |> Map.drop([:ref, :id, :destination])
    |> new()
  end

  @doc """
  Creates a new text input.

  ## Options

    * `:default` - the initial input value. Defaults to `""`

    * `:debounce` - determines when input changes are emitted. When
      set to `:blur`, the change propagates when the user leaves the
      input. When set to a non-negative number of milliseconds, the
      change propagates after the specified delay. Defaults to `:blur`
  """
  @spec text(String.t(), keyword()) :: t()
  def text(label, opts \\ []) when is_binary(label) and is_list(opts) do
    default = opts |> Keyword.get(:default, "") |> to_string()
    debounce = Keyword.get(opts, :debounce, :blur)

    assert_debounce_value!(debounce)

    new(%{type: :text, label: label, default: default, debounce: debounce})
  end

  @doc """
  Creates a new multiline text input.

  ## Options

    * `:default` - the initial input value. Defaults to `""`

    * `:monospace` - whether to use a monospace font inside the textarea.
      Defaults to `false`

    * `:debounce` - determines when input changes are emitted. When
      set to `:blur`, the change propagates when the user leaves the
      input. When set to a non-negative number of milliseconds, the
      change propagates after the specified delay. Defaults to `:blur`
  """
  @spec textarea(String.t(), keyword()) :: t()
  def textarea(label, opts \\ []) when is_binary(label) and is_list(opts) do
    default = opts |> Keyword.get(:default, "") |> to_string()
    monospace = Keyword.get(opts, :monospace, false)
    debounce = Keyword.get(opts, :debounce, :blur)

    assert_debounce_value!(debounce)

    new(%{
      type: :textarea,
      label: label,
      default: default,
      monospace: monospace,
      debounce: debounce
    })
  end

  @doc """
  Creates a new password input.

  This is similar to text input, except the content is not
  visible by default.

  ## Options

    * `:default` - the initial input value. Defaults to `""`

    * `:debounce` - determines when input changes are emitted. When
      set to `:blur`, the change propagates when the user leaves the
      input. When set to a non-negative number of milliseconds, the
      change propagates after the specified delay. Defaults to `:blur`
  """
  @spec password(String.t(), keyword()) :: t()
  def password(label, opts \\ []) when is_binary(label) and is_list(opts) do
    default = opts |> Keyword.get(:default, "") |> to_string()
    debounce = Keyword.get(opts, :debounce, :blur)

    assert_debounce_value!(debounce)

    new(%{type: :password, label: label, default: default, debounce: debounce})
  end

  @doc """
  Creates a new number input.

  The input value is can be either a number or `nil`.

  ## Options

    * `:default` - the initial input value. Defaults to `nil`

    * `:debounce` - determines when input changes are emitted. When
      set to `:blur`, the change propagates when the user leaves the
      input. When set to a non-negative number of milliseconds, the
      change propagates after the specified delay. Defaults to `:blur`
  """
  @spec number(String.t(), keyword()) :: t()
  def number(label, opts \\ []) when is_binary(label) and is_list(opts) do
    default = Keyword.get(opts, :default, nil)
    debounce = Keyword.get(opts, :debounce, :blur)

    assert_default_value!(default, "be either number or nil", fn value ->
      is_nil(value) or is_number(value)
    end)

    assert_debounce_value!(debounce)

    new(%{type: :number, label: label, default: default, debounce: debounce})
  end

  defp assert_default_value!(value, message, check) do
    unless check.(value) do
      raise ArgumentError, "expected :default to #{message}, got: #{inspect(value)}"
    end
  end

  defp assert_debounce_value!(value) do
    unless value == :blur or (is_number(value) and value >= 0) do
      raise ArgumentError,
            ~s/expected :debounce to be :blur or a non-negative number, got: #{inspect(value)}/
    end
  end

  @doc """
  Creates a new URL input.

  The input value can be either a valid URL string or `nil`.

  ## Options

    * `:default` - the initial input value. Defaults to `nil`

    * `:debounce` - determines when input changes are emitted. When
      set to `:blur`, the change propagates when the user leaves the
      input. When set to a non-negative number of milliseconds, the
      change propagates after the specified delay. Defaults to `:blur`
  """
  @spec url(String.t(), keyword()) :: t()
  def url(label, opts \\ []) when is_binary(label) and is_list(opts) do
    default = Keyword.get(opts, :default, nil)
    debounce = Keyword.get(opts, :debounce, :blur)

    assert_default_value!(default, "be either string or nil", fn value ->
      is_nil(value) or is_binary(value)
    end)

    assert_debounce_value!(debounce)

    new(%{type: :url, label: label, default: default, debounce: debounce})
  end

  @doc """
  Creates a new select input.

  The input expects a list of options in the form `[{value, label}]`,
  where `value` is an arbitrary term and `label` is a descriptive
  string.

  ## Options

    * `:default` - the initial input value. Defaults to the first
      value from the given list of options

  ## Examples

      Kino.Input.select("Language", [en: "English", fr: "Français"])

      Kino.Input.select("Language", [{1, "One"}, {2, "Two"}, {3, "Three"}])
  """
  @spec select(String.t(), list({value :: term(), label :: String.t()}), keyword()) :: t()
  def select(label, options, opts \\ [])
      when is_binary(label) and is_list(options) and is_list(opts) do
    if options == [] do
      raise ArgumentError, "expected at least one option, got: []"
    end

    options = Enum.map(options, fn {key, val} -> {key, to_string(val)} end)
    values = Enum.map(options, &elem(&1, 0))
    default = Keyword.get_lazy(opts, :default, fn -> hd(values) end)

    if default not in values do
      raise ArgumentError,
            "expected :default to be either of #{Enum.map_join(values, ", ", &inspect/1)}, got: #{inspect(default)}"
    end

    new(%{type: :select, label: label, options: options, default: default})
  end

  @doc """
  Creates a new checkbox.

  The input value can be either `true` or `false`.

  ## Options

    * `:default` - the initial input value. Defaults to `false`
  """
  @spec checkbox(String.t(), keyword()) :: t()
  def checkbox(label, opts \\ []) when is_binary(label) and is_list(opts) do
    default = Keyword.get(opts, :default, false)
    assert_default_value!(default, "be a boolean", &is_boolean/1)
    new(%{type: :checkbox, label: label, default: default})
  end

  @doc """
  Creates a new slider input.

  The input value can be either float in the configured range.

  ## Options

    * `:default` - the initial input value. Defaults to the
      minimum value

    * `:min` - the minimum value

    * `:max` - the maximum value

    * `:step` - the slider increment

    * `:debounce` - determines when input changes are emitted. When
      set to a non-negative number of milliseconds, the change propagates
      after the specified delay. Defaults to `250`
  """
  @spec range(String.t(), keyword()) :: t()
  def range(label, opts \\ []) when is_binary(label) and is_list(opts) do
    min = Keyword.get(opts, :min, 0)
    max = Keyword.get(opts, :max, 100)
    step = Keyword.get(opts, :step, 1)
    default = Keyword.get(opts, :default, min)
    # In Safari range input is blurred as soon as it's clicked,
    # so we don't support blur as debounce for this input
    debounce = Keyword.get(opts, :debounce, 250)

    if min >= max do
      raise ArgumentError,
            "expected :min to be less than :max, got: #{inspect(min)} and #{inspect(max)}"
    end

    if step <= 0 do
      raise ArgumentError, "expected :step to be positive, got: #{inspect(step)}"
    end

    assert_default_value!(default, "be a number", &is_number/1)

    if default < min or default > max do
      raise ArgumentError,
            "expected :default to be between :min and :max, got: #{inspect(default)}"
    end

    unless is_number(debounce) and debounce >= 0 do
      raise ArgumentError,
            ~s/expected :debounce to be a non-negative number, got: #{inspect(debounce)}/
    end

    new(%{
      type: :range,
      label: label,
      default: default,
      min: min,
      max: max,
      step: step,
      debounce: debounce
    })
  end

  @doc """
  Creates a new datetime input.

  The input is editable in user-local time zone, however the value
  is always read in UTC as a `%NaiveDateTime{}` struct.

  ## Options

    * `:default` - the initial input value. Defaults to `nil`

    * `:min` - the minimum datetime value (in UTC)

    * `:max` - the maximum datetime value (in UTC)
  """
  @spec utc_datetime(String.t(), keyword()) :: t()
  def utc_datetime(label, opts \\ []) when is_binary(label) and is_list(opts) do
    min = Keyword.get(opts, :min, nil) |> truncate_datetime()
    max = Keyword.get(opts, :max, nil) |> truncate_datetime()
    default = Keyword.get(opts, :default, nil) |> truncate_datetime()

    if min && max && NaiveDateTime.compare(min, max) == :gt do
      raise ArgumentError,
            "expected a non-empty range, but :min (#{inspect(min)}) is after :max (#{inspect(max)})"
    end

    assert_default_value!(
      default,
      "be %NaiveDateTime{} or nil",
      &(is_struct(&1, NaiveDateTime) or &1 == nil)
    )

    if min && default && NaiveDateTime.compare(default, min) == :lt do
      raise ArgumentError,
            "invalid :default, #{inspect(default)} is before :min (#{inspect(min)})"
    end

    if max && default && NaiveDateTime.compare(default, max) == :gt do
      raise ArgumentError,
            "invalid :default, #{inspect(default)} is after :max (#{inspect(max)})"
    end

    new(%{
      type: :utc_datetime,
      label: label,
      default: default,
      min: min,
      max: max
    })
  end

  defp truncate_datetime(nil), do: nil

  defp truncate_datetime(datetime) do
    datetime
    |> NaiveDateTime.truncate(:second)
    |> Map.replace!(:second, 0)
  end

  @doc """
  Creates a new time input.

  The input is editable in user-local time zone, however the value
  is always read in UTC as a `%Time{}` struct.

  ## Options

    * `:default` - the initial input value. Defaults to `nil`

    * `:min` - the minimum time value (in UTC)

    * `:max` - the maximum time value (in UTC)
  """
  @spec utc_time(String.t(), keyword()) :: t()
  def utc_time(label, opts \\ []) when is_binary(label) and is_list(opts) do
    min = Keyword.get(opts, :min, nil) |> truncate_time()
    max = Keyword.get(opts, :max, nil) |> truncate_time()
    default = Keyword.get(opts, :default, nil) |> truncate_time()

    if min && max && Time.compare(min, max) == :gt do
      raise ArgumentError,
            "expected a non-empty range, but :min (#{inspect(min)}) is after :max (#{inspect(max)})"
    end

    assert_default_value!(default, "be %Time{} or nil", &(is_struct(&1, Time) or &1 == nil))

    if min && default && Time.compare(default, min) == :lt do
      raise ArgumentError,
            "invalid :default, #{inspect(default)} is before :min (#{inspect(min)})"
    end

    if max && default && Time.compare(default, max) == :gt do
      raise ArgumentError,
            "invalid :default, #{inspect(default)} is after :max (#{inspect(max)})"
    end

    new(%{
      type: :utc_time,
      label: label,
      default: default,
      min: min,
      max: max
    })
  end

  defp truncate_time(nil), do: nil

  defp truncate_time(time) do
    time
    |> Time.truncate(:second)
    |> Map.replace!(:second, 0)
  end

  @doc """
  Creates a new date input.

  The input is read as a `%Date{}` struct.

  ## Options

    * `:default` - the initial input value. Defaults to `nil`

    * `:min` - the minimum date value

    * `:max` - the maximum date value
  """
  @spec date(String.t(), keyword()) :: t()
  def date(label, opts \\ []) when is_binary(label) and is_list(opts) do
    min = Keyword.get(opts, :min, nil)
    max = Keyword.get(opts, :max, nil)
    default = Keyword.get(opts, :default, nil)

    if min && max && Date.compare(min, max) == :gt do
      raise ArgumentError,
            "expected a non-empty range, but :min (#{inspect(min)}) is after :max (#{inspect(max)})"
    end

    assert_default_value!(default, "be %Date{} or nil", &(is_struct(&1, Date) or &1 == nil))

    if min && default && Date.compare(default, min) == :lt do
      raise ArgumentError,
            "invalid :default, #{inspect(default)} is before :min (#{inspect(min)})"
    end

    if max && default && Date.compare(default, max) == :gt do
      raise ArgumentError,
            "invalid :default, #{inspect(default)} is after :max (#{inspect(max)})"
    end

    new(%{
      type: :date,
      label: label,
      default: default,
      min: min,
      max: max
    })
  end

  @doc """
  Creates a new color input.

  The input value can be a hex color string.

  ## Options

    * `:default` - the initial input value. Defaults to `#6583FF`

    * `:debounce` - determines when input changes are emitted. When
      set to `:blur`, the change propagates when the user leaves the
      input. When set to a non-negative number of milliseconds, the
      change propagates after the specified delay. Defaults to `:blur`
  """
  @spec color(String.t(), keyword()) :: t()
  def color(label, opts \\ []) when is_binary(label) and is_list(opts) do
    default = Keyword.get(opts, :default, "#6583FF")
    debounce = Keyword.get(opts, :debounce, :blur)

    assert_default_value!(default, "be a string", &is_binary/1)

    assert_debounce_value!(debounce)

    new(%{type: :color, label: label, default: default, debounce: debounce})
  end

  @doc """
  Creates a new image input.

  The input value is a map, with an image file and metadata:

      %{
        file_ref: term(),
        height: pos_integer(),
        width: pos_integer(),
        format: :rgb | :png | :jpeg
      }

  Note that the value can also be `nil`, if no image is selected.

  The file path can then be accessed using `file_path/1`.

  > #### Warning {: .warning}
  >
  > The image input is shared by default: once you upload a image,
  > the image will be replicated to all users reading the notebook.
  > Use `Kino.Control.form/2` if you want each user to have a distinct
  > image upload with an explicit submission button.

  ## Options

    * `:format` - the format to read the image as, either of:

      * `:rgb` (default) - the binary includes raw pixel values, each
        encoded as a single byte in the HWC order. Such binary can be
        directly converted to an `Nx` tensor, with no additional decoding

      * `:png`

      * `:jpeg` (or `:jpg`)

    * `:size` - the size to fit the image into, given as `{height, width}`

    * `:fit` - the strategy of fitting the image into `:size`, either of:

      * `:contain` (default) - resizes the image, such that it fits in
        a box of `:size`, but preserving the aspect ratio. The resulting
        image can be smaller or equal to `:size`

      * `:match` - resizes the image to `:size`, with no respect for
        aspect ratio

      * `:pad` - same as `:contain`, but pads the image to match `:size`
        exactly

      * `:crop` - resizes the image, such that one edge fits in `:size`
        and the other overflows, then center-crops the image to match
        `:size` exactly

  """
  @spec image(String.t(), keyword()) :: t()
  def image(label, opts \\ []) do
    format =
      case Keyword.get(opts, :format, :rgb) do
        :rgb ->
          :rgb

        :png ->
          :png

        :jpeg ->
          :jpeg

        :jpg ->
          :jpeg

        other ->
          raise ArgumentError,
                "expected :format to be either of :rgb, :png or :jpeg/:jpg, got: #{inspect(other)}"
      end

    size = Keyword.get(opts, :size, nil)
    fit = Keyword.get(opts, :fit, :contain)

    unless fit in [:match, :contain, :pad, :crop] do
      raise ArgumentError,
            "expected :fit to be either of :contain, :match, :pad or :crop, got: #{inspect(fit)}"
    end

    new(%{type: :image, label: label, default: nil, size: size, format: format, fit: fit})
  end

  @doc """
  Creates a new audio input.

  The input value is a map, with an audio file and metadata:

      %{
        file_ref: term(),
        num_channels: pos_integer(),
        sampling_rate: pos_integer(),
        format: :pcm_f32 | :wav
      }

  Note that the value can also be `nil`, if no audio is selected.

  The file path can then be accessed using `file_path/1`.

  > #### Warning {: .warning}
  >
  > The audio input is shared by default: once you upload an audio,
  > the audio will be replicated to all users reading the notebook.
  > Use `Kino.Control.form/2` if you want each user to have a distinct
  > audio upload with an explicit submission button.

  ## Options

    * `:format` - the format to read the audio as, either of:

      * `:pcm_f32` (default) - the PCM (32-bit float) format. Note that
        the binary uses native system endianness. Such binary can be
        directly converted to an `Nx` tensor, with no additional decoding

      * `:wav`

    * `:sampling_rate` - the sampling rate (samples per second) of
      the audio data. Defaults to `48_000`

  """
  @spec audio(String.t(), keyword()) :: t()
  def audio(label, opts \\ []) do
    format = Keyword.get(opts, :format, :pcm_f32)
    sampling_rate = Keyword.get(opts, :sampling_rate, 48_000)

    unless format in [:pcm_f32, :wav] do
      raise ArgumentError,
            "expected :format to be either of :pcm_f32 or :wav, got: #{inspect(format)}"
    end

    new(%{type: :audio, label: label, default: nil, format: format, sampling_rate: sampling_rate})
  end

  @doc """
  Creates a new file input.

  The input value is a map, with a file and metadata:

      %{
        file_ref: term(),
        client_name: String.t()
      }

  Note that the value can also be `nil`, if no file is selected.

  The file path can then be accessed using `file_path/1`.

  > #### Warning {: .warning}
  >
  > The file input is shared by default: once you upload a file,
  > the file will be replicated to all users reading the notebook.
  > Use `Kino.Control.form/2` if you want each user to have a distinct
  > file upload with an explicit submission button.

  ## Considerations

  Note that a file may be deleted in certain cases, specifically:

    * when the file is reuploaded
    * when used with a form and the uploading user leaves
    * when the input is removed

  The deletion is not immediate and you are unlikely to run into this
  in practice, however theoretically `file_path/1` may point to a
  non-existing file.

  ## Options

    * `:accept` - the list of accepted file types (either extensions
      or MIME types) or `:any`. Defaults to `:any`

  ## Examples

  To read the content of currently uploaded file we would do:

      # [Cell 1]

      input = Kino.Input.file("File")

      # [Cell 2]

      value = Kino.Input.read(input)
      path = Kino.Input.file_path(value.file_ref)
      File.read!(path)

  And here's how we could process an asynchronous form submission:

      # [Cell 1]

      form = Kino.Control.form([file: Kino.Input.file("File")], submit: "Send")

      # [Cell 2]

      form
      |> Kino.Control.stream()
      |> Kino.listen(fn event ->
        path = Kino.Input.file_path(event.data.file.file_ref)
        content = File.read!(path)
        IO.inspect(content)
      end)

  """

  @spec file(String.t(), keyword()) :: t()
  def file(label, opts \\ []) when is_binary(label) and is_list(opts) do
    accept = Keyword.get(opts, :accept, :any)

    case accept do
      :any ->
        :ok

      [_ | _] ->
        :ok

      other ->
        raise ArgumentError, "expected :accept to be a non-empty list, got: #{inspect(other)}"
    end

    new(%{type: :file, label: label, default: nil, accept: accept})
  end

  @doc """
  Synchronously reads the current input value.

  ## Examples

      input =
        Kino.Input.text("Name")
        |> Kino.render()

      Kino.Input.read(input)
  """
  @spec read(t()) :: term()
  def read(%Kino.Input{} = input) do
    case Kino.Bridge.get_input_value(input.id) do
      {:ok, value} ->
        value

      {:error, reason} ->
        raise "failed to read input value, reason: #{inspect(reason)}"
    end
  end

  @doc """
  Returns file path for the given file identifier.
  """
  @spec file_path(file_ref) :: String.t() when file_ref: {:file, id :: String.t()}
  def file_path({:file, file_id} = file_ref) do
    case Kino.Bridge.get_file_path(file_ref) do
      {:ok, path} ->
        path

      {:error, _reason} ->
        # Return a non-existing path for consistency
        Path.join([System.tmp_dir!(), "nonexistent", file_id])
    end
  end
end

defimpl Enumerable, for: Kino.Input do
  def reduce(input, acc, fun), do: Enumerable.reduce(Kino.Control.stream([input]), acc, fun)
  def member?(_input, _value), do: {:error, __MODULE__}
  def count(_input), do: {:error, __MODULE__}
  def slice(_input), do: {:error, __MODULE__}
end