rsx-rb 0.1.0

data/examples/components/button.rsx

@@ -0,0 +1,22 @@
+# A small component with typed props, defaults and pass-through attributes.
+#
+# Required props are declared as required keywords, optional ones get defaults,
+# and `**rest` collects anything else so callers can add ids, data attributes or
+# aria attributes without the component knowing about them.
+
+component Button do |label: nil, variant: "primary", size: "md", disabled: false, children: nil, **rest|
+  classes = ["btn", "btn-#{variant}", "btn-#{size}"]
+
+  return (
+    <button
+      className={classes}
+      disabled={disabled}
+      aria={disabled ? { disabled: true } : nil}
+      {**rest}
+    >
+      {label || children}
+    </button>
+  )
+end
+
+export default Button

data/examples/components/card.rsx

@@ -0,0 +1,21 @@
+# Composition: children plus "slot" props that are themselves markup.
+#
+# Because attribute values can be any Ruby expression, a slot is just a prop
+# that happens to hold markup: <Card header={<h1>Title</h1>}>.
+
+component Card do |title: nil, header: nil, footer: nil, children: nil|
+  return (
+    <section className="card">
+      {/* A header prop wins over the plain title, like a slot overriding a default */}
+      <header className="card-header">
+        {header || (title && <h2 className="card-title">{title}</h2>)}
+      </header>
+
+      <div className="card-body">{children}</div>
+
+      {footer && <footer className="card-footer">{footer}</footer>}
+    </section>
+  )
+end
+
+export default Card

data/examples/components/sidebar.rsx

@@ -0,0 +1,29 @@
+# Caching. Two levels are available:
+#
+#   1. `cache:` on the component caches its entire output, keyed by its props.
+#   2. `cache(key) { ... }` inside a body caches one fragment, which is useful
+#      when only part of the markup is expensive.
+#
+# Both keys include a digest of this file, so editing the component invalidates
+# what it cached.
+
+component Sidebar, cache: { expires_in: 300 } do |section:, unread: 0|
+  return (
+    <nav className="sidebar" aria={{ label: "Primary" }}>
+      <ul>
+        {%w[dashboard projects reports settings].map do |name|
+          <li key={name} className={{ current: name == section }}>
+            <a href={"/#{name}"}>{name.capitalize}</a>
+          </li>
+        end}
+      </ul>
+
+      {/* Expensive, but only worth caching for a minute */}
+      {cache(["sidebar-unread", unread], expires_in: 60) do
+        <p className="unread">{unread} unread</p>
+      end}
+    </nav>
+  )
+end
+
+export default Sidebar

data/examples/components/theme.rsx

@@ -0,0 +1,29 @@
+# Context: pass a value down the tree without threading it through props.
+
+Theme = RSX.create_context("light", name: "Theme")
+
+component ThemedPanel do |children: nil|
+  theme = use_context(Theme)
+
+  return (
+    <div className={["panel", "panel-#{theme}"]} data={{ theme: theme }}>
+      {children}
+    </div>
+  )
+end
+
+# Anything rendered inside <Theme.Provider value={"dark"}> sees "dark",
+# including components several levels down.
+component ThemeDemo do |props|
+  return (
+    <>
+      <ThemedPanel>Uses the default theme.</ThemedPanel>
+
+      <Theme.Provider value={"dark"}>
+        <ThemedPanel>Dark, because of the provider above.</ThemedPanel>
+      </Theme.Provider>
+    </>
+  )
+end
+
+export default ThemeDemo

data/examples/components/user_table.rsx

@@ -0,0 +1,64 @@
+# A more involved component: loops, conditional branches, helper methods,
+# computed classes and inline styles.
+
+import Button from "components/button"
+
+component UserTable do |users:, sort: :name, current_user: nil|
+  # Plain Ruby methods, defined and called like JavaScript function declarations.
+  def initials(user)
+    user[:name].split.map { |part| part[0] }.join.upcase
+  end
+
+  def status_style(user)
+    { color: user[:active] ? "#0a7" : "#999", fontWeight: user[:active] ? 600 : 400 }
+  end
+
+  sorted = users.sort_by { |user| user[sort].to_s }
+
+  return (
+    <table className="users">
+      <thead>
+        <tr>
+          <th>Person</th>
+          <th>Status</th>
+          <th className="numeric">Posts</th>
+          <th></th>
+        </tr>
+      </thead>
+
+      <tbody>
+        {sorted.map do |user|
+          <tr
+            key={user[:id]}
+            className={{ "is-you" => user == current_user, "is-inactive" => !user[:active] }}
+            data={{ user_id: user[:id] }}
+          >
+            <td>
+              <span className="avatar">{initials(user)}</span>
+              {user[:name]}
+              {user == current_user && <em className="you"> (you)</em>}
+            </td>
+
+            <td style={status_style(user)}>
+              {user[:active] ? "Active" : "Inactive"}
+            </td>
+
+            <td className="numeric">{user[:posts_count]}</td>
+
+            <td>
+              <Button label="Edit" variant="link" size="sm" data-user={user[:id]} />
+            </td>
+          </tr>
+        end}
+      </tbody>
+
+      {users.empty? && (
+        <tfoot>
+          <tr><td colSpan={4}>Nobody here yet.</td></tr>
+        </tfoot>
+      )}
+    </table>
+  )
+end
+
+export default UserTable

data/examples/user_profile.rsx

@@ -0,0 +1,51 @@
+component UserProfile do
+  # 1. Regular Ruby variables
+  user = {
+    first_name: "Jane",
+    last_name: "Doe",
+    avatar_url: "https://placeholder.com/avatar.png",
+    is_admin: true
+  }
+
+  # 2. A Ruby method, called from inside the markup
+  def format_name(person)
+    "#{person[:first_name]} #{person[:last_name]}"
+  end
+
+  # 3. Inline style hash (camelCase properties, just like React)
+  alert_style = {
+    color: "darkred",
+    backgroundColor: "pink",
+    padding: "10px",
+    borderRadius: "5px"
+  }
+
+  return (
+    # Rule: wrap multiple elements in a single root container (or an empty fragment <>)
+    <>
+      {/* Dynamic text injection using curly braces */}
+      <h1>Welcome back, {format_name(user)}!</h1>
+
+      {/* Dynamic attribute binding using curly braces (no quotes around braces) */}
+      <img
+        src={user[:avatar_url]}
+        alt="User profile picture"
+        className="profile-image" # Rule: use 'className' instead of 'class'
+      />
+
+      {/* Conditional rendering using a Ruby ternary */}
+      {user[:is_admin] ? (
+        <p style={alert_style}>Admin privileges active.</p>
+      ) : (
+        <p>Standard user account.</p>
+      )}
+
+      {/* Event handlers are JavaScript, so they are written as strings */}
+      <button onClick={"alert('Settings opened!')"}>
+        Account Settings
+      </button>
+    </>
+  )
+end
+
+export default UserProfile

data/examples/views/dashboard.html.rsx

@@ -0,0 +1,26 @@
+# A Rails view: app/views/pages/dashboard.html.rsx
+#
+# Inside a view, `self` is the Rails view context, so controller instance
+# variables and every Rails helper are available directly.
+
+import Card from "components/card"
+import Sidebar from "components/sidebar"
+import UserTable from "components/user_table"
+
+<div className="dashboard">
+  <Sidebar section="dashboard" unread={@unread_count} />
+
+  <main>
+    <h1>Team</h1>
+
+    <Card title="Everyone" footer={<a href="/users/new">Invite someone</a>}>
+      <UserTable users={@users} current_user={@current_user} sort={:name} />
+    </Card>
+
+    {@users.empty? && (
+      <Card title="Getting started">
+        <p>Invite a teammate to see them listed here.</p>
+      </Card>
+    )}
+  </main>
+</div>

data/exe/rsx

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+lib = File.expand_path("../lib", __dir__)
+$LOAD_PATH.unshift(lib) if File.directory?(lib) && !$LOAD_PATH.include?(lib)
+
+require "rsx"
+require "rsx/cli"
+
+exit RSX::CLI.start(ARGV)

data/lib/rsx/attributes.rb

@@ -0,0 +1,313 @@
+# frozen_string_literal: true
+
+module RSX
+  # Translates React-style DOM props into HTML attributes.
+  #
+  # Prop names follow React's conventions (className, htmlFor, tabIndex,
+  # strokeWidth, onClick, ...) and are mapped to their HTML spellings. Names that
+  # are already lowercase, snake_case or kebab-case pass through unchanged, so
+  # idiomatic Ruby markup works too.
+  module Attributes
+    # React prop => HTML attribute, for names that are not a simple case change.
+    PROP_NAMES = {
+      "className" => "class",
+      "class_name" => "class",
+      "htmlFor" => "for",
+      "html_for" => "for",
+      "httpEquiv" => "http-equiv",
+      "acceptCharset" => "accept-charset",
+      "charSet" => "charset",
+      "tabIndex" => "tabindex",
+      "readOnly" => "readonly",
+      "maxLength" => "maxlength",
+      "minLength" => "minlength",
+      "autoComplete" => "autocomplete",
+      "autoCapitalize" => "autocapitalize",
+      "autoCorrect" => "autocorrect",
+      "autoFocus" => "autofocus",
+      "autoPlay" => "autoplay",
+      "autoSave" => "autosave",
+      "crossOrigin" => "crossorigin",
+      "dateTime" => "datetime",
+      "encType" => "enctype",
+      "formAction" => "formaction",
+      "formEncType" => "formenctype",
+      "formMethod" => "formmethod",
+      "formNoValidate" => "formnovalidate",
+      "formTarget" => "formtarget",
+      "noValidate" => "novalidate",
+      "noModule" => "nomodule",
+      "srcSet" => "srcset",
+      "srcDoc" => "srcdoc",
+      "srcLang" => "srclang",
+      "hrefLang" => "hreflang",
+      "contentEditable" => "contenteditable",
+      "spellCheck" => "spellcheck",
+      "colSpan" => "colspan",
+      "rowSpan" => "rowspan",
+      "cellPadding" => "cellpadding",
+      "cellSpacing" => "cellspacing",
+      "useMap" => "usemap",
+      "isMap" => "ismap",
+      "allowFullScreen" => "allowfullscreen",
+      "allowTransparency" => "allowtransparency",
+      "playsInline" => "playsinline",
+      "referrerPolicy" => "referrerpolicy",
+      "fetchPriority" => "fetchpriority",
+      "frameBorder" => "frameborder",
+      "marginWidth" => "marginwidth",
+      "marginHeight" => "marginheight",
+      "mediaGroup" => "mediagroup",
+      "inputMode" => "inputmode",
+      "enterKeyHint" => "enterkeyhint",
+      "imageSizes" => "imagesizes",
+      "imageSrcSet" => "imagesrcset",
+      "popoverTarget" => "popovertarget",
+      "popoverTargetAction" => "popovertargetaction",
+      "accessKey" => "accesskey",
+      "itemProp" => "itemprop",
+      "itemScope" => "itemscope",
+      "itemType" => "itemtype",
+      "itemID" => "itemid",
+      "itemRef" => "itemref",
+      "radioGroup" => "radiogroup",
+      "defaultValue" => "value",
+      "defaultChecked" => "checked",
+      "defaultSelected" => "selected"
+    }.freeze
+
+    # SVG/MathML attributes whose camelCase spelling is significant.
+    CASE_SENSITIVE = %w[
+      attributeName attributeType baseFrequency baseProfile calcMode clipPathUnits
+      contentScriptType contentStyleType diffuseConstant edgeMode filterRes filterUnits
+      glyphRef gradientTransform gradientUnits kernelMatrix kernelUnitLength keyPoints
+      keySplines keyTimes lengthAdjust limitingConeAngle markerHeight markerUnits
+      markerWidth maskContentUnits maskUnits numOctaves pathLength patternContentUnits
+      patternTransform patternUnits pointsAtX pointsAtY pointsAtZ preserveAlpha
+      preserveAspectRatio primitiveUnits refX refY repeatCount repeatDur
+      requiredExtensions requiredFeatures specularConstant specularExponent spreadMethod
+      startOffset stdDeviation stitchTiles surfaceScale systemLanguage tableValues
+      targetX targetY textLength viewBox viewTarget xChannelSelector yChannelSelector
+      zoomAndPan
+    ].to_h { |name| [name, name] }.freeze
+
+    # Attributes rendered bare when truthy and omitted when falsy.
+    BOOLEAN = %w[
+      allowfullscreen async autofocus autoplay checked controls default defer disabled
+      formnovalidate hidden inert ismap itemscope loop multiple muted nomodule novalidate
+      open playsinline readonly required reversed selected
+    ].to_h { |name| [name, true] }.freeze
+
+    # Elements that must not be given a closing tag.
+    VOID = %w[
+      area base br col embed hr img input link meta param source track wbr
+    ].to_h { |name| [name, true] }.freeze
+
+    # Elements that may legally use XML self-closing syntax in HTML documents.
+    SELF_CLOSING = %w[
+      circle ellipse line path polygon polyline rect stop use image animate
+      animateMotion animateTransform feBlend feColorMatrix feComposite feFlood
+      feGaussianBlur feImage feMergeNode feOffset fePointLight feSpotLight feTile
+      feTurbulence mpath set
+    ].to_h { |name| [name, true] }.freeze
+
+    # CSS properties that take a bare number (everything else gets "px").
+    UNITLESS_CSS = %w[
+      animation-iteration-count aspect-ratio border-image-outset border-image-slice
+      border-image-width box-flex box-flex-group box-ordinal-group column-count columns
+      flex flex-grow flex-positive flex-shrink flex-negative flex-order font-weight
+      grid-area grid-row grid-row-end grid-row-span grid-row-start grid-column
+      grid-column-end grid-column-span grid-column-start line-clamp line-height opacity
+      order orphans scale tab-size widows z-index zoom fill-opacity flood-opacity
+      stop-opacity stroke-dasharray stroke-dashoffset stroke-miterlimit stroke-opacity
+      stroke-width
+    ].to_h { |name| [name, true] }.freeze
+
+    # Props that describe the element to RSX rather than to the browser.
+    IGNORED = %w[key ref children suppressHydrationWarning].to_h { |name| [name, true] }.freeze
+
+    INVALID_NAME = %r{[\s"'>/=\0]}
+    CAMEL_BOUNDARY = /([a-z0-9])([A-Z])/
+
+    module_function
+
+    # Maps a prop name to its HTML attribute name, or nil when the prop should
+    # not be rendered at all.
+    def attribute_name(prop)
+      name = prop.to_s
+      return nil if IGNORED.key?(name)
+
+      mapped = PROP_NAMES[name]
+      return mapped if mapped
+      return name if CASE_SENSITIVE.key?(name)
+      return name.downcase if name.match?(/\Aon[A-Z]/)
+      return name unless name.match?(/[A-Z]/)
+
+      name.gsub(CAMEL_BOUNDARY, '\1-\2').downcase
+    end
+
+    def boolean?(name)
+      BOOLEAN.key?(name)
+    end
+
+    def void?(tag)
+      VOID.key?(tag)
+    end
+
+    def self_closing?(tag)
+      SELF_CLOSING.key?(tag)
+    end
+
+    # Renders one attribute, including its leading space: ` href="/x"`.
+    def render(name, value)
+      case value
+      when nil, false then ""
+      when true then boolean?(name) ? " #{name}" : %( #{name}="true")
+      else %( #{name}="#{Escape.attribute(value)}")
+      end
+    end
+
+    # class={...} accepts a String, Symbol, Array or Hash.
+    def render_class(value)
+      tokens = class_tokens(value)
+      return "" if tokens.empty?
+
+      %( class="#{Escape.attribute(tokens.join(" "))}")
+    end
+
+    def class_tokens(value)
+      case value
+      when nil, false, true then []
+      when String then value.empty? ? [] : [value]
+      when Symbol then [value.to_s]
+      when Array then value.flat_map { |item| class_tokens(item) }
+      when Hash then value.filter_map { |token, on| token.to_s if on }
+      else [value.to_s]
+      end
+    end
+
+    # style={...} accepts a String or a Hash of CSS properties.
+    def render_style(value)
+      css = style_string(value)
+      return "" if css.nil? || css.empty?
+
+      %( style="#{Escape.attribute(css)}")
+    end
+
+    def style_string(value)
+      case value
+      when nil, false, true then nil
+      when String then value
+      when Array then value.filter_map { |item| style_string(item) }.join(";")
+      when Hash
+        value.filter_map do |property, raw|
+          next if raw.nil? || raw == false || raw == ""
+
+          name = css_property(property)
+          "#{name}:#{css_value(name, raw)}"
+        end.join(";")
+      else value.to_s
+      end
+    end
+
+    def css_property(property)
+      name = property.to_s
+      return name unless name.match?(/[A-Z_]/)
+
+      name = name.tr("_", "-")
+      name.gsub(CAMEL_BOUNDARY, '\1-\2').downcase
+    end
+
+    def css_value(name, value)
+      return "#{value}px" if value.is_a?(Numeric) && value != 0 && !UNITLESS_CSS.key?(name)
+
+      value.to_s
+    end
+
+    # data={...} / aria={...} expand a Hash into prefixed attributes.
+    def render_nested(prefix, value)
+      case value
+      when nil, false then ""
+      when Hash
+        value.filter_map do |key, raw|
+          next if raw.nil?
+
+          # Like React, data-* and aria-* keep booleans as the strings "true"
+          # and "false" rather than becoming bare attributes: ARIA values are
+          # enumerated, so `aria-hidden` alone means nothing.
+          %( #{prefix}-#{css_property(key)}="#{Escape.attribute(nested_value(raw))}")
+        end.join
+      else render(prefix, value)
+      end
+    end
+
+    def nested_value(value)
+      case value
+      when String, Symbol, Numeric, SafeString then value
+      when Array, Hash then RSX.json(value)
+      else value.to_s
+      end
+    end
+
+    # Combines attribute hashes the way React combines props: names that map to
+    # the same HTML attribute collapse, keeping the first position and the last
+    # value, so `<a {...attrs} className="link">` overrides the spread.
+    def merge(*parts)
+      merged = {}
+      positions = {}
+
+      parts.each do |part|
+        next if part.nil? || part == false
+
+        unless part.respond_to?(:each_pair)
+          raise ArgumentError, "spread attributes need a Hash, got #{part.class}"
+        end
+
+        part.each_pair do |prop, value|
+          name = canonical_name(prop)
+          existing = positions[name]
+
+          if existing
+            merged[existing] = value
+          else
+            positions[name] = prop
+            merged[prop] = value
+          end
+        end
+      end
+
+      merged
+    end
+
+    # The name two props have to share to be considered the same attribute.
+    def canonical_name(prop)
+      attribute_name(prop) || prop.to_s
+    end
+
+    # Renders a hash of props as attributes: {**props} / {...props}
+    def render_all(hash)
+      return "" if hash.nil? || hash == false
+
+      unless hash.respond_to?(:each_pair)
+        raise ArgumentError, "spread attributes need a Hash, got #{hash.class}"
+      end
+
+      out = +""
+      hash.each_pair do |prop, value|
+        case prop.to_s
+        when "class", "className", "class_name" then out << render_class(value)
+        when "style" then out << render_style(value)
+        when "data" then out << render_nested("data", value)
+        when "aria" then out << render_nested("aria", value)
+        when "dangerouslySetInnerHTML" then next
+        else
+          name = attribute_name(prop)
+          next if name.nil? || name.empty? || name.match?(INVALID_NAME)
+
+          out << render(name, value)
+        end
+      end
+      out
+    end
+  end
+end

data/lib/rsx/cache.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module RSX
+  # Render caches. Any object responding to `fetch(key, expires_in:) { ... }`
+  # and `clear` can be used as a store, so Rails.cache, Memcached or Redis need
+  # no adapter beyond the thin wrapper below.
+  module Cache
+    # Thread-safe in-process LRU. This is the default store so caching works
+    # with no configuration and no dependencies.
+    class Memory
+      DEFAULT_MAX_ENTRIES = 4096
+
+      def initialize(max_entries: DEFAULT_MAX_ENTRIES)
+        @max_entries = max_entries
+        @entries = {}
+        @lock = Mutex.new
+      end
+
+      def fetch(key, expires_in: nil)
+        found = read(key)
+        return found unless found.nil?
+
+        write(key, yield, expires_in: expires_in)
+      end
+
+      def read(key)
+        @lock.synchronize do
+          value, expires_at = @entries[key]
+          next nil if value.nil?
+
+          if expires_at && expires_at < now
+            @entries.delete(key)
+            next nil
+          end
+
+          # Re-insert so the entry counts as most recently used.
+          @entries.delete(key)
+          @entries[key] = [value, expires_at]
+          value
+        end
+      end
+
+      def write(key, value, expires_in: nil)
+        @lock.synchronize do
+          @entries.delete(key)
+          @entries[key] = [value, expires_in && (now + expires_in)]
+          @entries.shift while @entries.size > @max_entries
+        end
+        value
+      end
+
+      def delete(key)
+        @lock.synchronize { @entries.delete(key) }
+      end
+
+      def clear
+        @lock.synchronize { @entries.clear }
+        self
+      end
+
+      def size
+        @lock.synchronize { @entries.size }
+      end
+
+      private
+
+      def now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+
+    # Stores fragments in Rails.cache so they live alongside the rest of the
+    # application's cache and are invalidated by the same tooling.
+    class Rails
+      def initialize(store = nil)
+        @store = store
+      end
+
+      def store
+        @store || ::Rails.cache
+      end
+
+      def fetch(key, expires_in: nil, &block)
+        store.fetch(key, expires_in: expires_in, &block)
+      end
+
+      def read(key) = store.read(key)
+      def write(key, value, expires_in: nil) = store.write(key, value, expires_in: expires_in)
+      def delete(key) = store.delete(key)
+      def clear = store.clear
+    end
+
+    # Never caches. Useful in tests and for disabling caching outright.
+    class Null
+      def fetch(_key, expires_in: nil) = yield
+      def read(_key) = nil
+      def write(_key, value, expires_in: nil) = value
+      def delete(_key) = nil
+      def clear = self
+    end
+  end
+end