hibiki_phlex 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4c2497270017a9a8000df2a65a725d71a330698a5bd1ecba91b7e17d535ad625
+  data.tar.gz: ab335047166028c98ea49b12d784660f3667ceff5c5b980a1bfdd4c9402f971e
+SHA512:
+  metadata.gz: 01cb9954a404539ed1c78c9c55542f2b2fa4b2c28d8828e04ae0ceafa0d0352db2664f7519f95f53cb6fdcae538250d8b5d7a471332e1bb8077ad3d868b65af2
+  data.tar.gz: 81a1c655c2e8a4b29e922dd2f397015972a148d2a68ae73150eaed3551a54c2fe0fa77c5afb5705475da70f5f61abd5a07779763ad292b629d65fdd4ea3ca736

data/README.md

@@ -0,0 +1,117 @@
+# hibiki_phlex
+
+Phlex glue for [hibiki](https://github.com/planetaska/hibiki): reactive
+components. A Phlex component is a plain Ruby object, so
+`Hibiki::Reactive` gives it per-instance signals read as ordinary method
+calls — no `.value` anywhere in `view_template` — and a **render effect**
+re-renders it whenever one of those signals changes.
+
+```
+signal write → render effect re-runs → component re-renders
+(same instance) → fresh HTML handed to your block
+```
+
+Transport-agnostic on purpose: the gem depends only on hibiki and phlex.
+The block receiving the HTML decides where it goes — broadcast it over
+Turbo Streams (see [hibiki_rails](../hibiki_rails)), write it to a file,
+diff it in a test.
+
+Incubating inside the hibiki repo while the core gem is pre-release; will
+be extracted to its own repository once hibiki 0.1.0 ships and this API
+stabilizes. Phlex >= 2.4, < 2.5 (see the version-pin rationale below),
+Ruby >= 3.4.
+
+## Usage
+
+```ruby
+class TodoList < Phlex::HTML
+  include Hibiki::Reactive
+  include Hibiki::Phlex::Rerenderable
+
+  state(:items) { [] }
+  derived(:remaining) { items.count { |item| !item[:done] } }
+
+  def view_template
+    div(id: "todos") do
+      h2 { "Todos — #{remaining} remaining" }
+      ul { items.each { |item| li { item[:title] } } }
+    end
+  end
+
+  # Signals compare with ==; build new values instead of mutating in place.
+  def add(title) = self.items = items + [{ title:, done: false }]
+end
+```
+
+```ruby
+list = TodoList.new
+
+effect = Hibiki::Phlex.render_effect(list) do |html|
+  # your transport — e.g. inside a Hibiki::Rails::Channel:
+  # broadcast_replace target: "todos", html:
+end
+
+list.add("write docs")   # → the block runs again with fresh HTML
+effect.dispose           # or let an enclosing Hibiki.root own teardown
+```
+
+- The effect's **first run is the dependency-collecting initial render**:
+  signals read inside `view_template` subscribe it through plain method
+  calls, and that first HTML is yielded too.
+- Re-renders happen **on the same instance** — signal identity lives in
+  the instance, so a fresh instance per render would reset every signal.
+  That's what `Rerenderable` exists for.
+- `render_effect(component, scheduler:)` passes the scheduler through to
+  `Hibiki::Effect`, so reruns can be deferred or debounced (e.g.
+  `Hibiki::Rails::Debounce`).
+- Returns the `Hibiki::Effect`. Created inside `Hibiki.root` (or another
+  effect), the owner tree disposes it automatically; a bare caller calls
+  `#dispose`.
+
+## With hibiki_rails
+
+The combination is the LiveView-ish loop — one signal graph per cable
+connection, one render effect per component:
+
+```ruby
+class TodosChannel < ApplicationCable::Channel
+  include Hibiki::Rails::Channel
+
+  def build_graph
+    @list = TodoList.new
+    Hibiki::Phlex.render_effect(@list) do |html|
+      broadcast_replace target: "todos", html:
+    end
+  end
+
+  def add(data) = @list.add(data["title"])
+end
+```
+
+Granularity is inherent and worth knowing: the ERB style in hibiki_rails
+is one effect **per partial** (fine-grained), a Phlex render effect is one
+effect **per component** (component-grained). Both are correct; pick per
+page. The initial-state pattern (server-rendered placeholder + subscribe
+after the Turbo stream confirms) is transport-side — see the hibiki_rails
+README.
+
+## Why the strict Phlex pin
+
+Phlex components are one-shot: an instance renders once, and a second
+`call` raises `Phlex::DoubleRenderError`. Phlex 2 tracks "spent" purely
+through the private `@_state` ivar — everything else about a render is
+per-call — so `Rerenderable#rerender` clears it and calls again. That is
+the entire adapter, but it leans on a private implementation detail, so:
+
+- the gemspec allows only verified Phlex minors (`>= 2.4, < 2.5`), and
+- `spec/phlex_contract_spec.rb` pins the upstream contract itself, so
+  bumping the bound fails loudly in CI if the internals moved.
+
+## Development
+
+```
+bundle exec rake   # specs + rubocop (same as CI)
+```
+
+Plain RSpec — no Rails; the live end-to-end proof app is `spike/` in the
+parent repo (the `/phlex` page).

data/lib/hibiki/phlex/rerenderable.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Hibiki
+  module Phlex
+    # Lets the same component instance render more than once — required for
+    # render_effect, where signal identity lives in the instance (a fresh
+    # instance per render would reset every signal).
+    #
+    # Phlex 2 marks an instance as spent purely through @_state —
+    # SGML#internal_call raises DoubleRenderError when it is set, and it is
+    # deliberately never cleared after a render (see `rendering?`).
+    # Everything else (output buffer, capture state, the thread-local
+    # current component) is per-call, so clearing @_state before calling
+    # again is the ENTIRE adapter. It leans on a private ivar, which is why
+    # this gem pins Phlex minors and spec/phlex_contract_spec.rb pins the
+    # contract itself.
+    module Rerenderable
+      def rerender(...)
+        @_state = nil
+        call(...)
+      end
+    end
+  end
+end

data/lib/hibiki/phlex/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Hibiki
+  module Phlex
+    VERSION = "0.1.0"
+  end
+end

data/lib/hibiki/phlex.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# NOTE: for everything under lib/hibiki/phlex/ — inside this namespace a bare
+# `Phlex` constant resolves to Hibiki::Phlex, not the framework. Always
+# write `::Phlex.` when you mean the framework.
+module Hibiki
+  # Phlex glue for hibiki: a component is a plain Ruby object, so
+  # Hibiki::Reactive gives it signals read as ordinary method calls, and a
+  # render effect re-renders the same instance (signal identity lives in
+  # the instance) whenever one of them changes.
+  module Phlex
+    # Wrap a component's render in an effect. The effect's first run is the
+    # dependency-collecting initial render — signals read inside
+    # view_template subscribe it through plain method calls — and its HTML
+    # is yielded like every rerun's. On each signal change the component
+    # re-renders ON THE SAME INSTANCE and the fresh HTML goes to the block;
+    # the block owns the transport (broadcast it, print it, diff it).
+    #
+    #   Hibiki::Phlex.render_effect(@list) do |html|
+    #     broadcast_replace target: "todos", html:
+    #   end
+    #
+    # Component-grained by design: one effect per component (the ERB style
+    # in hibiki_rails is one effect per partial — both are correct).
+    # `scheduler:` passes through to Hibiki::Effect, so reruns can be
+    # deferred/debounced (e.g. Hibiki::Rails::Debounce). Returns the Effect;
+    # inside a Hibiki.root or another effect the owner tree adopts it, a
+    # bare caller disposes it by hand.
+    def self.render_effect(component, scheduler: nil, &sink)
+      unless component.respond_to?(:rerender)
+        raise ArgumentError,
+              "#{component.class} has no #rerender — include Hibiki::Phlex::Rerenderable"
+      end
+
+      Effect.new(scheduler:) { sink.call(component.rerender) }
+    end
+  end
+end
+
+require_relative "phlex/version"
+require_relative "phlex/rerenderable"

data/lib/hibiki_phlex.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require "hibiki"
+require "phlex"
+require "hibiki/phlex"

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification
+name: hibiki_phlex
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- planetaska
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: hibiki
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: phlex
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.4'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.4'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+description: 'Make a Phlex component reactive: include Hibiki::Reactive for signals
+  read as plain method calls, Hibiki::Phlex::Rerenderable so the same instance can
+  render again, and wrap it in Hibiki::Phlex.render_effect to get fresh HTML on every
+  signal change — transport-agnostic, the block decides where the HTML goes.'
+email:
+- planetaska@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/hibiki/phlex.rb
+- lib/hibiki/phlex/rerenderable.rb
+- lib/hibiki/phlex/version.rb
+- lib/hibiki_phlex.rb
+homepage: https://github.com/planetaska/hibiki-phlex
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/planetaska/hibiki-phlex
+  source_code_uri: https://github.com/planetaska/hibiki-phlex
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: 'Phlex glue for hibiki: reactive components re-rendered by a render effect.'
+test_files: []