defmodule GenDOM.CompositionEvent do
  @moduledoc """
  Represents events related to composition of text input.

  The CompositionEvent interface represents events that occur due to the user indirectly
  entering text. This includes input through Input Method Editors (IMEs), speech recognition
  systems, and other text composition systems where text is composed before being committed.

  ## Specification Compliance

  This module implements the CompositionEvent interface as defined by:
  - **UI Events Specification**: https://www.w3.org/TR/uievents/#interface-compositionevent
  - **MDN CompositionEvent Reference**: https://developer.mozilla.org/en-US/docs/Web/API/CompositionEvent

  ## Inheritance Chain

  ```
  GenDOM.Event (Base)
  └── GenDOM.UIEvent
      └── GenDOM.CompositionEvent (extends UIEvent)
  ```

  **Inherits from:** `GenDOM.UIEvent`

  ## Properties

  ### Composition Data
  - `data` - The characters generated by the input method
  - `locale` - The locale of current input method (deprecated, non-standard)

  ## Event Types

  CompositionEvent is used for:
  - `compositionstart` - Composition session is starting
  - `compositionupdate` - New character is added to the composition
  - `compositionend` - Composition session is complete

  ## Event Sequence

  A typical composition sequence:
  1. `compositionstart` - User begins composition (e.g., starts typing in IME)
  2. `compositionupdate` - Fires for each character/change during composition
  3. `compositionend` - User commits the text (e.g., presses Enter in IME)

  ## Input Method Editors (IMEs)

  IMEs are commonly used for:
  - East Asian languages (Chinese, Japanese, Korean)
  - Complex scripts (Arabic, Hindi, Thai)
  - Emoji input
  - Voice-to-text conversion
  - Predictive text input

  ## Usage Notes

  - During composition, the DOM may show temporary text
  - The final text may differ from intermediate states
  - Always handle `compositionend` to get the final text
  - Some operations should be deferred until composition completes

  ## Examples

      # Creating a CompositionEvent
      event = GenDOM.CompositionEvent.new("compositionstart", %{
        data: "",
        view: window,
        bubbles: true,
        cancelable: false
      })

      # Handling composition events
      case event.type do
        "compositionstart" ->
          # Mark that composition is in progress
          set_composing(true)
          disable_validation()
          
        "compositionupdate" ->
          # Show intermediate composition text
          display_preview(event.data)
          
        "compositionend" ->
          # Composition complete, process final text
          set_composing(false)
          commit_text(event.data)
          enable_validation()
      end

      # Deferring actions during composition
      if is_composing? do
        # Don't perform certain actions during composition
        queue_action()
      else
        perform_action()
      end
  """

  use GenDOM.UIEvent, [
    # The characters generated by the input method
    data: "",                     # Text being composed or final composed text
    
    # Deprecated/non-standard properties
    locale: ""                    # Locale of input method (deprecated, non-standard)
  ]

  @doc """
  Initializes the attributes of a CompositionEvent object.

  This method implements the CompositionEvent `initCompositionEvent()` specification.
  It initializes a CompositionEvent that was created using the deprecated
  Document.createEvent() method.

  ## Deprecation Notice
  **This method is deprecated.** Use the CompositionEvent() constructor instead to create
  and initialize composition events. This method is maintained only for backward compatibility.

  ## Parameters
  - `event` - The CompositionEvent struct to initialize
  - `type` - Event type ("compositionstart", "compositionupdate", or "compositionend")
  - `can_bubble` - Whether the event can bubble
  - `cancelable` - Whether the event can be canceled
  - `view` - The Window associated with the event
  - `data` - The composition string
  - `locale` - The locale of the input method (deprecated)

  ## Returns
  Returns `:not_implemented` (would normally return undefined/nil)

  ## Examples
      # Legacy code example (deprecated - do not use in new code)
      event = Document.create_event(document, "CompositionEvent")
      GenDOM.CompositionEvent.init_composition_event(event,
        "compositionstart",
        true,              # can_bubble
        false,             # cancelable
        window,            # view
        "",                # data
        "en-US"           # locale
      )

  ## Modern Alternative
  Instead of using this deprecated method, create CompositionEvent instances directly:

      event = GenDOM.CompositionEvent.new("compositionstart", %{
        bubbles: true,
        cancelable: false,
        view: window,
        data: ""
      })

  ## MDN Reference
  https://developer.mozilla.org/en-US/docs/Web/API/CompositionEvent/initCompositionEvent
  """
  def init_composition_event(_event, _type, _can_bubble, _cancelable, _view, _data, _locale) do
    :not_implemented
  end
end
