barefoot_js 0.18.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f77e9970654fbb8ba3c2bcd8c6f0d46348260286f58087a4539ef1e2af68be7c
+  data.tar.gz: 0d9dd2e4fcf6e840622d3ab15b4759342c2ad2081665e23bf72c8ac25d1e4a14
+SHA512:
+  metadata.gz: c40f59ac73e033c93d60bd87e19192cbd577a0709344f49cf477a9159943d1dcb3c4994109fd240f6571b0b43bf1b745a89ba59eb3c4a76abfa87beb168329b8
+  data.tar.gz: 3e13dcb87d4031846592504e2eaa97fdcca6221479dde88095b9ab4d6a073aeca6127d624636970a1fefebda3f1031c7699c27165d5e6ee1c1d94b0561563988

data/lib/barefoot_js/backend/erb.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require 'erb'
+require 'json'
+
+module BarefootJS
+  module Backend
+    # ERB rendering backend for the BarefootJS runtime.
+    #
+    # The engine-agnostic runtime logic -- the JS-compat value helpers,
+    # array/string methods, hydration markers, child rendering -- lives in
+    # `BarefootJS::Context`. This backend supplies the four engine-specific
+    # operations the runtime delegates to, targeting Ruby stdlib ERB:
+    #
+    #   encode_json(data)            -> JSON string (injectable encoder)
+    #   mark_raw(str)                -> identity (ERB has no "safe string"
+    #                                    wrapper type -- ERB's own `<%=` is
+    #                                    NOT auto-escaping, so the compiled
+    #                                    templates that need escaping call
+    #                                    `bf.h(...)` explicitly; `mark_raw`
+    #                                    only exists so runtime helpers that
+    #                                    already produce finished HTML --
+    #                                    e.g. spread_attrs -- share one
+    #                                    interface with the Kolon/EP ports)
+    #   materialize(value)           -> resolve a captured-children value
+    #                                    to a string
+    #   render_named(name, bf, vars) -> render `<name>.erb` with `bf` and
+    #                                    `v` (vars, symbol-keyed) bound
+    #
+    # Pair it with the @barefootjs/erb compile-time adapter, which emits
+    # `.erb` templates that call the runtime as a `bf` local: `<%= bf.h(v[:x])
+    # %>`, `<%= bf.spread_attrs(bag) %>`. Unlike the Perl backends, this has
+    # no dependency on a web framework: a plain directory of `.erb` files
+    # renders under any Rack app (or none at all).
+    class Erb
+      # ERB template locals contract (spec/compiler.md "ERB emission
+      # contract"): every compiled template receives exactly two locals --
+      # `bf` (the BarefootJS::Context for this render) and `v` (a Hash with
+      # SYMBOL keys holding every prop/signal/memo/module-constant the
+      # template references). This is enforced by binding `bf` and `v` as
+      # local variables in a dedicated eval scope per render (see
+      # `render_named`) rather than passing a generic binding, so a template
+      # can never accidentally see Ruby method-local state.
+      # `cache:` mirrors the Xslate/Kolon backend's `cache => $DEV ? 0 : 1`
+      # constructor option: true (default, production) parses each `.erb`
+      # file once and reuses the compiled ERB::Compiler output for the life
+      # of the process; false (dev) re-reads and re-parses from disk on
+      # every `render_named` call, so `bf build --watch` output is picked up
+      # on the next request without restarting the server.
+      def initialize(path:, json_encoder: nil, cache: true)
+        @dir = path
+        @json_encoder = json_encoder || ->(data) { JSON.generate(data) }
+        @cache = {}
+        @cache_enabled = cache
+      end
+
+      def encode_json(data)
+        @json_encoder.call(data)
+      end
+
+      # ERB has no "already-safe" string wrapper the way Kolon's `mark_raw`
+      # or Mojo::ByteStream do -- stdlib ERB's `<%=` never auto-escapes, so
+      # there is nothing to opt out of. Identity, kept only so runtime
+      # helpers (`spread_attrs`) share one `backend.mark_raw(...)` call
+      # shape across every BarefootJS backend port.
+      def mark_raw(str)
+        str
+      end
+
+      # JSX children captured by the adapter's buffer-slice capture
+      # resolve to a plain String already; a Proc is called and its
+      # result used (mirrors the Perl backends' CODE-ref materialisation
+      # for engines whose children-capture mechanism yields a callable).
+      def materialize(value)
+        value.respond_to?(:call) ? value.call : value
+      end
+
+      # Render `<name>.erb` (relative to `path`) with `child_bf` bound as
+      # `bf` and `vars` (a Hash, symbol-keyed) bound as `v`.
+      def render_named(name, child_bf, vars)
+        template = load_template(name)
+        Renderer.new(child_bf, vars || {}).render(template)
+      end
+
+      private
+
+      def load_template(name)
+        return build_template(name) unless @cache_enabled
+
+        @cache[name] ||= build_template(name)
+      end
+
+      def build_template(name)
+        file = File.join(@dir, "#{name}.erb")
+        src = File.read(file, encoding: 'UTF-8')
+        ERB.new(src, trim_mode: '-', eoutvar: '_erbout')
+      end
+
+      # A dedicated per-render binding host. `bf` and `v` are the ONLY
+      # locals a compiled template may reference (see the class docstring);
+      # giving each render its own tiny object (rather than reusing a
+      # shared binding) means concurrent / nested renders never see each
+      # other's `v`.
+      class Renderer
+        def initialize(bf, v)
+          @bf = bf
+          @v = v
+        end
+
+        def render(template)
+          # `bf` / `v` must be real LOCAL variables (not instance
+          # variables) at the point `binding` is captured -- ERB templates
+          # reference them as bare identifiers (`bf.h(...)`, `v[:x]`), and
+          # `Binding` only exposes locals in scope + the object's own
+          # instance variables under their own `@`-prefixed names.
+          bf = @bf
+          v = @v
+          template.result(binding)
+        end
+      end
+    end
+  end
+end

data/lib/barefoot_js/dev_reload.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module BarefootJS
+  # Framework-agnostic dev-only browser auto-reload for BarefootJS apps.
+  #
+  # Ruby port of BarefootJS::DevReload (@barefootjs/perl), companion to
+  # `barefoot build --watch` in @barefootjs/cli. The CLI drops
+  # `<dist>/.dev/build-id` after every successful rebuild that changed output;
+  # a browser snippet subscribes to an SSE endpoint that emits `event: reload`
+  # when that file changes, so an editor save triggers an automatic reload.
+  #
+  #   require 'barefoot_js/dev_reload'
+  #
+  #   # Mount the SSE endpoint (dev only) as a plain Rack app, e.g. from
+  #   # config.ru's Rack::Builder:
+  #   map "#{BASE}/_bf/reload" do
+  #     run BarefootJS::DevReload.to_app(dist_dir: 'dist')
+  #   end
+  #
+  #   # And emit the browser snippet before </body> in your layout:
+  #   BarefootJS::DevReload.snippet("#{BASE}/_bf/reload")
+  #
+  # This is a plain Rack app (not a Sinatra route) so it works the same way
+  # under any Rack-based host, mirroring the Perl module's PSGI-app shape.
+  module DevReload
+    # Sentinel path contract with @barefootjs/cli (DEV_SENTINEL_SUBDIR /
+    # DEV_SENTINEL_FILENAME in packages/cli/src/lib/build.ts). Duplicated so
+    # this package avoids a runtime dep on the CLI — keep in sync with the CLI.
+    DEV_SUBDIR = '.dev'
+    BUILD_ID_FILE = 'build-id'
+
+    SCROLL_STORAGE_KEY = '__bf_devreload_scroll'
+
+    # Heartbeat < any reasonable proxy/server idle timeout so a quiet
+    # connection doesn't get reaped between rebuilds.
+    HEARTBEAT_S = 5
+    # Polling instead of a filesystem-event gem (e.g. `listen`) keeps the
+    # runtime dependency-free. Sub-second latency is imperceptible next to a
+    # browser reload.
+    POLL_S = 0.5
+
+    # <dist>/.dev/build-id — the sentinel `barefoot build --watch` rewrites.
+    def self.build_id_path(dist_dir)
+      File.join(dist_dir, DEV_SUBDIR, BUILD_ID_FILE)
+    end
+
+    # Ensure <dist>/.dev exists so the watcher can write the sentinel even if
+    # the server started first.
+    def self.ensure_dev_dir(dist_dir)
+      dev = File.join(dist_dir, DEV_SUBDIR)
+      FileUtils.mkdir_p(dev)
+      dev
+    end
+
+    def self.read_build_id(path)
+      return '' unless File.file?(path)
+
+      File.read(path, encoding: 'UTF-8').strip
+    rescue Errno::ENOENT
+      ''
+    end
+
+    # The browser snippet: a small IIFE — EventSource subscriber + scrollY
+    # preservation across reloads. Idempotent across duplicate mounts (the
+    # window.__bfDevReload guard). Returns a plain HTML string; callers embed
+    # it directly (ERB's own `<%=` never auto-escapes, so no `mark_raw` needed
+    # the way the Kolon/EP ports require).
+    def self.snippet(endpoint)
+      ep = js_str(endpoint)
+      sk = js_str(SCROLL_STORAGE_KEY)
+      "<script>(function(){if(window.__bfDevReload)return;window.__bfDevReload=1;" \
+        "try{var s=sessionStorage.getItem(#{sk});if(s){sessionStorage.removeItem(#{sk});" \
+        "var y=parseInt(s,10);if(!isNaN(y)){var restore=function(){window.scrollTo(0,y)};" \
+        "if(document.readyState==='loading'){addEventListener('DOMContentLoaded',restore,{once:true})}" \
+        "else{restore()}}}}catch(e){}var es=new EventSource(#{ep});" \
+        "es.addEventListener('reload',function(){try{sessionStorage.setItem(#{sk},String(window.scrollY))}" \
+        "catch(e){}location.reload()});es.addEventListener('error',function(){})})();</script>"
+    end
+
+    # A ready-made Rack app for the SSE endpoint. Streams `event: reload`
+    # whenever <dist>/.dev/build-id changes, with `: hb` heartbeats in
+    # between.
+    #
+    # The response body is a lazy `Enumerator` — Puma (and any Rack server
+    # that doesn't buffer the body) writes each yielded chunk to the socket
+    # as it's produced, giving true incremental streaming without needing
+    # `env['rack.hijack']`. A write failure on a disconnected client surfaces
+    # as an exception raised back into the Enumerator's block at the `y <<`
+    # call (Ruby re-raises consumer-side exceptions at the fiber's yield
+    # point) — the `rescue` below turns that into a clean loop exit, the
+    # same role Perl's `local $SIG{PIPE} = 'IGNORE'; eval { ... }` plays.
+    #
+    # DevReload is automatically a no-op unless mounted, and should only be
+    # mounted in development — see app.rb's `DEV` guard.
+    def self.to_app(dist_dir: 'dist')
+      path = build_id_path(dist_dir)
+      ensure_dev_dir(dist_dir)
+
+      lambda do |env|
+        last_event_id = (env['HTTP_LAST_EVENT_ID'] || '').strip
+
+        body = Enumerator.new do |y|
+          begin
+            y << "retry: 1000\n\n"
+
+            initial = read_build_id(path)
+            last_sent = ''
+            unless initial.empty?
+              last_sent = initial
+              # A stale Last-Event-ID means a build happened while the client
+              # was disconnected — fire `reload` immediately so the missed
+              # rebuild doesn't stay unpainted.
+              event = (!last_event_id.empty? && last_event_id != initial) ? 'reload' : 'hello'
+              y << "event: #{event}\nid: #{initial}\ndata: #{initial}\n\n"
+            end
+
+            since_hb = 0
+            loop do
+              sleep(POLL_S)
+              id = read_build_id(path)
+              if !id.empty? && id != last_sent
+                last_sent = id
+                since_hb = 0
+                y << "event: reload\nid: #{id}\ndata: #{id}\n\n"
+              else
+                since_hb += POLL_S
+                if since_hb >= HEARTBEAT_S
+                  since_hb = 0
+                  y << ": hb\n\n"
+                end
+              end
+            end
+          rescue IOError, Errno::EPIPE, Errno::ECONNRESET
+            # Client disconnected — stop producing chunks.
+          end
+        end
+
+        # Rack 3 requires lowercase header names (Rack::Lint enforces this in
+        # development; Rack 2 accepted either case).
+        [200, {
+          'content-type' => 'text/event-stream',
+          'cache-control' => 'no-cache, no-transform',
+          'x-accel-buffering' => 'no',
+        }, body]
+      end
+    end
+
+    # Minimal JS string escape for the handful of characters that can appear
+    # in a URL path or storage key. Good enough for package-internal + trusted
+    # operator-supplied strings; never interpolate untrusted input here.
+    def self.js_str(s)
+      t = s.to_s.gsub('\\', '\\\\\\\\').gsub('"', '\\"').gsub("\n", '\\n').gsub("\r", '\\r')
+      %("#{t}")
+    end
+    private_class_method :js_str
+  end
+end