Example: live todo list

# frozen_string_literal: true

# Record-backed reactive row. Identity is the Todo's GlobalID (reactive_record),
# so the signed token re-finds the record server-side — never trusts client state.
#
# Demonstrates the full per-row toolkit, all without a Stimulus controller:
#   * an OPTIMISTIC toggle (checked: :keep) that flips the checkbox the instant
#     you click, before the round trip; the morph reconciles from server truth, a
#     failure snaps it back;
#   * an inline rename that saves on Enter and morphs in place so the field keeps
#     focus + caret (reply.morph over reply.replace);
#   * an OPTIMISTIC archive (hide: true) that hides the row NOW; reply.remove then
#     drops it, so it never flashes back;
#   * a broadcast on every change so the OTHER tabs see the same row update
#     (exclude: reactive_connection_id suppresses the actor's own echo).
class TodoItemComponent < Phlex::HTML
  include Phlex::Reactive::Streamable
  include Phlex::Reactive::Component

  reactive_record :todo
  action :toggle
  action :rename, params: { title: :string }
  action :archive

  def initialize(todo:)
    @todo = todo
  end

  # Streamable#dom_id is render-context-free.
  def id = dom_id(@todo)

  # Toggle done, then broadcast the reconciled row to the other tabs. A replace is
  # keyed by dom id, so idiomorph dedupes it for the actor even without exclude:;
  # passing exclude: keeps every action on one consistent pattern.
  def toggle
    @todo.update!(done: !@todo.done?)
    broadcast
  end

  # Morph in place so the rename input keeps focus + caret after an Enter save,
  # then broadcast the new title to the other tabs.
  def rename(title:)
    @todo.update!(title:) if title.present?
    broadcast
    reply.morph
  end

  # Destroy the record, drop this tab's row in place (reply.remove — no doomed
  # self re-render), and broadcast the removal to the other tabs. Remove is
  # idempotent, so exclude: only spares the actor a redundant echo.
  def archive
    @todo.destroy!
    TodoItemComponent.broadcast_remove_to(*Todo.stream_key, model: @todo, exclude: reactive_connection_id)
    reply.remove
  end

  def view_template
    li(**mix(reactive_root, class: 'flex items-center gap-2 py-1',
                            data: { testid: 'todo', done: @todo.done?.to_s })) do
      # The optimistic checkbox: checked: :keep lets the native flip happen NOW
      # (it skips the unconditional preventDefault), so the box ticks in the same
      # gesture; the morph then overwrites with server truth, a failure reverts it.
      input(type: 'checkbox', checked: @todo.done?,
            **mix(on(:toggle, event: 'change', optimistic: { checked: :keep }),
                  class: 'checkbox checkbox-sm', data: { testid: 'toggle' }))
      # Enter saves the rename (event: "keydown.enter" is Stimulus's native
      # keyboard filter, so ONLY Enter fires it). The Todo's title travels as the
      # `title` param (a named control of this row).
      input(**mix(on(:rename, event: 'keydown.enter'),
                  name: 'title', value: @todo.title,
                  data: { testid: 'todo-title' },
                  class: ['input input-sm flex-1', ('line-through opacity-60' if @todo.done?)]))
      # Instant delete: hide the row NOW (optimistic), remove it on the reply.
      # disable_with: guards against a rapid double-click firing archive twice.
      button(**mix(on(:archive, disable_with: '…', optimistic: { hide: true, to: :root }),
                   class: 'btn btn-xs btn-ghost', data: { testid: 'archive' })) { 'archive' }
    end
  end

  private

  # Re-render this row into every OTHER subscribed tab — exclude the actor, whose
  # own reply.morph / self-replace already updated them.
  def broadcast
    TodoItemComponent.broadcast_replace_to(*Todo.stream_key, model: @todo, exclude: reactive_connection_id)
  end
end

# frozen_string_literal: true

# The live todo list: a record-backed list whose `add` action creates a Todo,
# appends the new row's component to the actor's own reply, AND broadcasts that
# row to every OTHER subscribed tab so two open windows stay in sync. Each row is
# its own reactive component (TodoItemComponent), self-targeting by GlobalID.
#
# State-backed root (a stable placeholder token) — the rows carry the real record
# identity. `disable_with:` on Add stops a rapid double-click from creating two
# todos, and `on_client` clears the composer with zero round trips.
class TodoListComponent < Phlex::HTML
  include Phlex::Reactive::Streamable
  include Phlex::Reactive::Component
  include Phlex::Rails::Helpers::TurboStreamFrom

  reactive_state :build_token # stable placeholder state for the list root
  action :add, params: { title: :string }

  def initialize(build_token: 'list')
    @build_token = build_token
  end

  def id = 'todo-list'

  # Create the todo, append the new row to the OTHER tabs, then re-render self so
  # the actor sees the row + the empty-state clears + the composer resets. An
  # append INSERTS a child (not id-deduped like a replace), so exclude: the actor
  # or their own subscribed tab would get the row a second time on top of this
  # self re-render.
  def add(title:)
    title = title.to_s.strip
    return if title.blank?

    todo = Todo.create!(title:)
    TodoItemComponent.broadcast_append_to(*Todo.stream_key, target: 'todos',
                                                            model: todo, exclude: reactive_connection_id)
  end

  def view_template
    div(**reactive_root(class: 'flex flex-col gap-3')) do
      turbo_stream_from(*Todo.stream_key) # subscribe to cross-tab updates

      ul(id: 'todos', class: 'flex flex-col') do
        if Todo.exists?
          Todo.order(:created_at, :id).each { render TodoItemComponent.new(todo: it) }
        else
          render TodoEmptyComponent.new
        end
      end

      div(class: 'flex gap-2') do
        # Enter in the field adds the todo — the same :add action the button fires
        # on click. event: "keydown.enter" is Stimulus's native keyboard filter,
        # so only Enter dispatches. The field's value rides as the `title` param.
        input(**mix(on(:add, event: 'keydown.enter'),
                    name: 'title', placeholder: 'New todo…', autocomplete: 'off',
                    class: 'input input-bordered flex-1', data: { testid: 'new-todo' }))
        # disable_with: stops a rapid double-click from creating two todos.
        button(**mix(on(:add, disable_with: 'Adding…'),
                     class: 'btn btn-primary', data: { testid: 'add' })) { 'Add' }
        # Client-only tips toggle: show/hide the hint with ZERO round trip — no
        # token, no POST, ever. Pure UX polish the one generic controller applies
        # locally (js.toggle flips the [hidden] flag).
        button(**mix(on_client(:click, js.toggle('#todo-tips')),
                     class: 'btn btn-ghost', data: { testid: 'tips-toggle' })) { 'Tips' }
      end

      p(id: 'todo-tips', hidden: true, class: 'text-xs opacity-60',
        data: { testid: 'todo-tips' }) do
        'Press Enter to add · click the checkbox to toggle · Enter in a row saves the rename.'
      end
    end
  end
end