corex

defmodule Corex.SignaturePad do
  @moduledoc ~S'''
  Phoenix implementation of [Zag.js Signature Pad](https://zagjs.com/components/react/signature-pad).

  ## Examples

  <!-- tabs-open -->

  ### Basic Usage

  ```heex
  <.signature_pad id="my-signature-pad" class="signature-pad">
    <:label>Sign here</:label>
    <:clear_trigger>
      <.icon name="hero-x-mark" />
    </:clear_trigger>
  </.signature_pad>
  ```

  ### With Callback

  ```heex
  <.signature_pad
    id="my-signature-pad"
    on_draw_end="signature_drawn"
    class="signature-pad">
    <:label>Sign here</:label>
    <:clear_trigger>
      <.icon name="hero-x-mark" />
    </:clear_trigger>
  </.signature_pad>
  ```

  ```elixir
  def handle_event("signature_drawn", %{"paths" => paths}, socket) do
    {:noreply, put_flash(socket, :info, "Signature drawn with #{length(paths)} paths")}
  end
  ```

  ### Custom Drawing Options

  ```heex
  <.signature_pad
    id="my-signature-pad"
    drawing_fill="blue"
    drawing_size={3}
    drawing_simulate_pressure
    class="signature-pad">
    <:label>Sign here</:label>
    <:clear_trigger>
      <.icon name="hero-x-mark" />
    </:clear_trigger>
  </.signature_pad>
  ```

  <!-- tabs-close -->

  ## Phoenix Form Integration

  When using with Phoenix forms, you must add an id to the form using the `Corex.Form.get_form_id/1` function.

  ### Controller

  ```elixir
  defmodule MyAppWeb.PageController do
    use MyAppWeb, :controller

    def home(conn, params) do
      form = Phoenix.Component.to_form(Map.get(params, "user", %{}), as: :user)
      render(conn, :home, form: form)
    end
  end
  ```

  ```heex
  <.form :let={f} as={:user} for={@form} id={get_form_id(@form)} method="get">
    <.signature_pad field={f[:signature]} id="my-signature-pad" class="signature-pad">
      <:label>Sign here</:label>
      <:clear_trigger>
        <.icon name="hero-x-mark" />
      </:clear_trigger>
      <:error :let={msg}>
        <.icon name="hero-exclamation-circle" class="icon" />
        {msg}
      </:error>
    </.signature_pad>
    <button type="submit">Submit</button>
  </.form>
  ```

  ### Live View

  When using Phoenix form in a Live view you must also add controlled mode. This allows the Live view to be the source of truth and the component to be in sync accordingly.

  ```elixir
  defmodule MyAppWeb.SignaturePadLive do
    use MyAppWeb, :live_view

    def mount(_params, _session, socket) do
      form = to_form(%{"signature" => nil}, as: :user)
      {:ok, assign(socket, :form, form)}
    end

    def render(assigns) do
      ~H"""
      <.form as={:user} for={@form} id={get_form_id(@form)}>
        <.signature_pad
          field={@form[:signature]}
          id="my-signature-pad"
          class="signature-pad"
          controlled
        >
          <:label>Sign here</:label>
          <:clear_trigger>
            <.icon name="hero-x-mark" />
          </:clear_trigger>
          <:error :let={msg}>
            <.icon name="hero-exclamation-circle" class="icon" />
            {msg}
          </:error>
        </.signature_pad>
        <button type="submit">Submit</button>
      </.form>
      """
    end
  end
  ```

  ### With Ecto changeset

  First create your schema and changeset:

  ```elixir
  defmodule MyApp.Accounts.User do
    use Ecto.Schema
    import Ecto.Changeset

    schema "users" do
      field :name, :string
      field :signature, :text
      timestamps(type: :utc_datetime)
    end

    def changeset(user, attrs) do
      user
      |> cast(attrs, [:name, :signature])
      |> validate_required([:name, :signature])
    end
  end
  ```

  ```elixir
  defmodule MyAppWeb.UserLive do
    use MyAppWeb, :live_view
    alias MyApp.Accounts.User

    def mount(_params, _session, socket) do
      {:ok, assign(socket, :form, to_form(User.changeset(%User{}, %{})))}
    end

    def handle_event("validate", %{"user" => user_params}, socket) do
      changeset = User.changeset(%User{}, user_params)
      {:noreply, assign(socket, form: to_form(changeset, action: :validate))}
    end

    def render(assigns) do
      ~H"""
      <.form for={@form} id={get_form_id(@form)} phx-change="validate">
        <.signature_pad
          field={@form[:signature]}
          id="my-signature-pad"
          class="signature-pad"
        >
          <:label>Sign here</:label>
          <:clear_trigger>
            <.icon name="hero-x-mark" />
          </:clear_trigger>
          <:error :let={msg}>
            <.icon name="hero-exclamation-circle" class="icon" />
            {msg}
          </:error>
        </.signature_pad>
      </.form>
      """
    end
  end
  ```

  ## API Control

  In order to use the API, you must use an id on the component

  ***Client-side***

  ```heex
  <button phx-click={Corex.SignaturePad.clear("my-signature-pad")}>
    Clear Signature
  </button>
  ```

  ***Server-side***

  ```elixir
  def handle_event("clear_signature", _, socket) do
    {:noreply, Corex.SignaturePad.clear(socket, "my-signature-pad")}
  end
  ```

  ## Styling

  Use data attributes to target elements:

  ```css
  [data-scope="signature-pad"][data-part="root"] {}
  [data-scope="signature-pad"][data-part="label"] {}
  [data-scope="signature-pad"][data-part="control"] {}
  [data-scope="signature-pad"][data-part="segment"] {}
  [data-scope="signature-pad"][data-part="guide"] {}
  [data-scope="signature-pad"][data-part="clear-trigger"] {}
  [data-scope="signature-pad"][data-part="hidden-input"] {}
  ```

  If you wish to use the default Corex styling, you can use the class `signature-pad` on the component.
  This requires to install `Mix.Tasks.Corex.Design` first and import the component css file.

  ```css
  @import "../corex/main.css";
  @import "../corex/tokens/themes/neo/light.css";
  @import "../corex/components/signature-pad.css";
  ```

  You can then use modifiers

  ```heex
  <.signature_pad class="signature-pad signature-pad--accent signature-pad--lg">
  ```

  Learn more about modifiers and [Corex Design](https://corex-ui.com/components/signature-pad#modifiers)
  '''

  @doc type: :component
  use Phoenix.Component

  alias Corex.SignaturePad.Anatomy.{
    Props,
    Root,
    Label,
    Control,
    Segment,
    Guide,
    ClearTrigger,
    HiddenInput
  }

  alias Corex.SignaturePad.Connect

  @doc """
  Renders a signature pad component.
  """

  attr(:id, :string,
    required: false,
    doc: "The id of the signature pad, useful for API to identify the signature pad"
  )

  attr(:drawing_fill, :string,
    default: "black",
    doc: "The fill color for drawing strokes"
  )

  attr(:drawing_size, :integer,
    default: 2,
    doc: "The size/thickness of drawing strokes"
  )

  attr(:drawing_simulate_pressure, :boolean,
    default: false,
    doc: "Whether to simulate pressure for drawing strokes"
  )

  attr(:drawing_smoothing, :float,
    default: 0.9,
    doc: "Smoothing factor for drawing strokes (0–1, perfect-freehand option)"
  )

  attr(:drawing_easing, :string,
    default: nil,
    doc: "Easing function for drawing strokes (perfect-freehand option)"
  )

  attr(:drawing_thinning, :float,
    default: nil,
    doc: "Thinning factor for drawing strokes (perfect-freehand option)"
  )

  attr(:drawing_streamline, :float,
    default: 0.1,
    doc: "Streamline factor for drawing strokes (perfect-freehand option)"
  )

  attr(:dir, :string,
    default: nil,
    values: [nil, "ltr", "rtl"],
    doc:
      "The direction of the signature pad. When nil, derived from document (html lang + config :rtl_locales)"
  )

  attr(:on_draw_end, :string,
    default: nil,
    doc: "The server event name when drawing ends"
  )

  attr(:on_draw_end_client, :string,
    default: nil,
    doc: "The client event name when drawing ends"
  )

  attr(:controlled, :boolean,
    default: false,
    doc: "Whether the signature pad is controlled"
  )

  attr(:paths, :any,
    default: nil,
    doc:
      "The initial paths or the controlled paths of the signature pad. Can be a list or a JSON string."
  )

  attr(:name, :string, doc: "The name of the signature pad input for form submission")

  attr(:errors, :list,
    default: [],
    doc: "List of error messages to display"
  )

  attr(:field, Phoenix.HTML.FormField,
    doc:
      "A form field struct retrieved from the form, for example: @form[:signature]. Automatically sets id, name, value, and errors from the form field"
  )

  attr(:rest, :global)

  slot :label, required: false do
    attr(:class, :string, required: false)
  end

  slot :clear_trigger, required: false do
    attr(:class, :string, required: false)

    attr(:aria_label, :string,
      doc:
        "Accessibility label for the clear button. Defaults to 'Clear signature' if not provided."
    )
  end

  slot :error, required: false do
    attr(:class, :string, required: false)
  end

  def signature_pad(%{field: %Phoenix.HTML.FormField{} = field} = assigns) do
    errors = if Phoenix.Component.used_input?(field), do: field.errors, else: []

    paths_value =
      case field.value do
        nil -> nil
        "" -> nil
        value when is_binary(value) -> value
        value when is_list(value) -> Corex.Json.encode!(value)
        _ -> nil
      end

    assigns =
      assigns
      |> assign(field: nil)
      |> assign(:errors, Enum.map(errors, &Corex.Gettext.translate_error(&1)))
      |> assign_new(:id, fn -> field.id end)
      |> assign_new(:name, fn -> field.name end)
      |> assign(:paths, paths_value)

    signature_pad(assigns)
  end

  def signature_pad(assigns) do
    assigns =
      assigns
      |> assign_new(:id, fn -> "signature-pad-#{System.unique_integer([:positive])}" end)
      |> assign_new(:name, fn -> "name-#{System.unique_integer([:positive])}" end)

    ~H"""
    <div
      id={@id}
      phx-hook="SignaturePad"
      {@rest}
      {Connect.props(%Props{
        id: @id,
        controlled: @controlled,
        paths: @paths,
        drawing_fill: @drawing_fill,
        drawing_size: @drawing_size,
        drawing_simulate_pressure: @drawing_simulate_pressure,
        drawing_smoothing: @drawing_smoothing,
        drawing_easing: @drawing_easing,
        drawing_thinning: @drawing_thinning,
        drawing_streamline: @drawing_streamline,
        dir: @dir,
        on_draw_end: @on_draw_end,
        on_draw_end_client: @on_draw_end_client,
        name: @name
      })}
    >
      <div {Connect.root(%Root{id: @id, dir: @dir})}>
        <label :if={@label != []} {Connect.label(%Label{id: @id, dir: @dir})}>
          {render_slot(@label)}
        </label>
        <div {Connect.control(%Control{id: @id, dir: @dir})}>
          <svg {Connect.segment(%Segment{id: @id, dir: @dir})} fill={@drawing_fill}>
            <path
              :for={path <- parse_paths(@paths)}
              data-scope="signature-pad"
              data-part="path"
              d={path}
            />
          </svg>
          <button
            :if={@clear_trigger != []}
            {Connect.clear_trigger(%ClearTrigger{
              id: @id,
              dir: @dir,
              has_paths: has_paths?(@paths),
              aria_label: case @clear_trigger do
                [entry | _] -> Map.get(entry, :aria_label)
                _ -> nil
              end
            })}
          >
            {render_slot(@clear_trigger)}
          </button>
          <div {Connect.guide(%Guide{id: @id, dir: @dir})} />
        </div>
        <input {Connect.hidden_input(%HiddenInput{id: @id, dir: @dir, name: @name})} />
        <div :if={!Enum.empty?(@errors)} :for={msg <- @errors} data-scope="signature-pad" data-part="error">
          {render_slot(@error, msg)}
        </div>
      </div>
    </div>
    """
  end

  @doc type: :api
  @doc """
  Clears the signature pad from client-side. Returns a `Phoenix.LiveView.JS` command.

  ## Examples

      <button phx-click={Corex.SignaturePad.clear("my-signature-pad")}>
        Clear
      </button>
  """
  def clear(signature_pad_id) when is_binary(signature_pad_id) do
    Phoenix.LiveView.JS.dispatch("phx:signature-pad:clear",
      to: "##{signature_pad_id}",
      detail: %{id: signature_pad_id},
      bubbles: false
    )
  end

  @doc type: :api
  @doc """
  Clears the signature pad from server-side. Pushes a LiveView event.

  ## Examples

      def handle_event("clear_signature", _params, socket) do
        {:noreply, Corex.SignaturePad.clear(socket, "my-signature-pad")}
      end
  """
  def clear(socket, signature_pad_id)
      when is_struct(socket, Phoenix.LiveView.Socket) and is_binary(signature_pad_id) do
    Phoenix.LiveView.push_event(socket, "signature_pad_clear", %{
      signature_pad_id: signature_pad_id
    })
  end

  defp has_paths?(nil), do: false
  defp has_paths?(""), do: false
  defp has_paths?(paths) when is_list(paths), do: paths != []

  defp has_paths?(paths) when is_binary(paths) do
    case Corex.Json.encoder().decode(paths) do
      {:ok, list} when is_list(list) -> list != []
      _ -> false
    end
  end

  defp has_paths?(_), do: false

  defp parse_paths(nil), do: []
  defp parse_paths(""), do: []
  defp parse_paths(paths) when is_list(paths), do: Enum.filter(paths, &is_binary/1)

  defp parse_paths(paths) when is_binary(paths) do
    case Corex.Json.encoder().decode(paths) do
      {:ok, list} when is_list(list) -> Enum.filter(list, &is_binary/1)
      _ -> []
    end
  end

  defp parse_paths(_), do: []
end