Class: BarefootJS::Context

Inherits:
Object
  • Object
show all
Defined in:
lib/barefoot_js.rb

Overview

Context is the bf object every compiled .erb template receives as a local. One instance per render (root or child); render_child / register_components_from_manifest construct a fresh child instance per nested render, chaining scope/slot identity off the caller.

Constant Summary collapse

NUMERIC_STRING_RE =

JS-compat callees -- invoked from generated ERB templates as bf.json(val), bf.floor(val), etc. Numeric coercion follows JS semantics (NaN propagates; non-numeric input yields NaN rather than silently 0). json bubbles backend/marshalling errors loudly rather than producing an empty payload.

/\A\s*[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?\s*\z/.freeze

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(backend = nil) ⇒ Context

Returns a new instance of Context.



66
67
68
 
# File 'lib/barefoot_js.rb', line 66

def initialize(backend = nil)
  @backend = backend
end

Class Method Details

.derive_vars_from_defaults(defaults, props) ⇒ Object

Derive template-var kvs from a manifest entry's ssrDefaults section. Each entry shape: { value:, propName:, isRestProps: }. For isRestProps, the rest bag passes through unchanged (or the static {} if the caller didn't supply one). For ordinary entries the caller's props[propName] wins when present, otherwise the static value does. propName-less entries (signal / memo locals) always use the static value.

Public (not private_class_method): register_components_from_manifest above uses it for the ui/* registry path, but a page that composes flat (non-ui/*) components by hand -- e.g. the blog islands in the Sinatra/xslate/Mojolicious integrations -- needs the exact same ssrDefaults-seeding logic for its own manual register_child_renderer calls. Mirrors the Perl runtime's BarefootJS::_derive_stash_from_defaults, which is likewise callable from integration code (Perl has no enforced privacy; the leading underscore is convention only) -- see integrations/xslate/app.psgi's _register_blog_child and integrations/mojolicious/app.pl's equivalent.



316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
 
# File 'lib/barefoot_js.rb', line 316

def self.derive_vars_from_defaults(defaults, props)
  extra = {}
  defaults.each do |name, d|
    unless d.is_a?(Hash)
      extra[name] = d
      next
    end
    if d[:isRestProps]
      extra[name] = props.key?(name) ? props[name] : d[:value]
      next
    end
    # `propName` rides in from the JSON manifest as a String -- JSON has
    # no symbol type, and the manifest's `symbolize_names: true` parse
    # only symbolizes hash KEYS, never string values. Runtime prop
    # hashes, meanwhile, are symbol-keyed because compiled ERB templates
    # pass `{ children: ... }` literals, so `props.key?(prop_name)` with
    # the String would always miss, silently falling back to the static
    # default for every manifest-registered child (e.g. `children`
    # rendering empty) (#2157).
    prop_name = d[:propName]&.to_sym
    extra[name] =
      if !prop_name.nil? && props.key?(prop_name) && !props[prop_name].nil?
        props[prop_name]
      else
        d[:value]
      end
  end
  extra
end

Instance Method Details

#async_boundary(id, fallback_html) ⇒ Object 



354
355
356
357
 
# File 'lib/barefoot_js.rb', line 354

def async_boundary(id, fallback_html)
  fallback_html = backend.materialize(fallback_html)
  %(<div bf-async="#{id}">#{fallback_html}</div>)
end

#async_resolve(id, content_html) ⇒ Object 



359
360
361
 
# File 'lib/barefoot_js.rb', line 359

def async_resolve(id, content_html)
  %(<template bf-async-resolve="#{id}">#{content_html}</template><script>__bf_swap("#{id}")</script>)
end

#at(recv, i) ⇒ Object

Array.prototype.at(i) -- negative indices count from the end; out-of-bounds -> nil (renders as '' via h, matching JS undefined).



543
544
545
546
547
548
549
550
551
552
553
554
555
 
# File 'lib/barefoot_js.rb', line 543

def at(recv, i)
  return nil unless recv.is_a?(Array)
  return nil if i.nil?

  idx = i.to_i
  len = recv.length
  return nil if len.zero?

  idx = len + idx if idx.negative?
  return nil if idx.negative? || idx >= len

  recv[idx]
end

#bool_str(value) ⇒ Object

Map a JS-boolean-shaped value to the JS String(bool) form. See BarefootJS.pm's bool_str docstring for the boolean-only contract -- callers must have already classified the expression as boolean- result; non-boolean attribute bindings never reach this helper.



164
165
166
 
# File 'lib/barefoot_js.rb', line 164

def bool_str(value)
  value ? 'true' : 'false'
end

#ceil(value) ⇒ Object 



423
424
425
426
 
# File 'lib/barefoot_js.rb', line 423

def ceil(value)
  n = number(value)
  finite_number?(n) ? n.ceil : n
end

#comment(text) ⇒ Object

Comment Markers



156
157
158
 
# File 'lib/barefoot_js.rb', line 156

def comment(text)
  "<!--bf-#{text}-->"
end

#concat(a, b) ⇒ Object

Array.prototype.concat(other) -- merges two arrays in order into a new Array. Non-array operands collapse to empty.



559
560
561
562
563
564
 
# File 'lib/barefoot_js.rb', line 559

def concat(a, b)
  out = []
  out.concat(a) if a.is_a?(Array)
  out.concat(b) if b.is_a?(Array)
  out
end

#data_key_attr ⇒ Object

Emits data-key="<key>" for a keyed loop item, else ''. See BarefootJS.pm's docstring on the client reconciliation contract.



101
102
103
104
105
106
107
 
# File 'lib/barefoot_js.rb', line 101

def data_key_attr
  k = _data_key
  return '' if k.nil?

  escaped = k.to_s.gsub('&', '&amp;').gsub('"', '&quot;')
  %( data-key="#{escaped}")
end

#ends_with(recv, suffix, end_position = nil) ⇒ Object

String.prototype.endsWith(suffix, endPosition?).



719
720
721
722
723
724
725
726
727
 
# File 'lib/barefoot_js.rb', line 719

def ends_with(recv, suffix, end_position = nil)
  s = recv.nil? ? '' : string(recv)
  x = suffix.nil? ? '' : string(suffix)
  unless end_position.nil?
    e = clamp_index(end_position.to_i, s.length)
    s = s[0...e]
  end
  s.end_with?(x)
end

#every(recv, pred) ⇒ Object 



465
466
467
468
469
 
# File 'lib/barefoot_js.rb', line 465

def every(recv, pred)
  return true unless recv.is_a?(Array)

  recv.all? { |item| pred.call(item) }
end

#every_eval(recv, pred_json, param, base_env = {}) ⇒ Object 



892
893
894
 
# File 'lib/barefoot_js.rb', line 892

def every_eval(recv, pred_json, param, base_env = {})
  Evaluator.every_json(recv, pred_json, param, base_env)
end

#filter(recv, pred) ⇒ Object

.filter(fn) / .every(fn) / .some(fn) / .find(fn) / .findIndex(fn) / .findLast(fn) / .findLastIndex(fn) -- legacy block-predicate path for shapes the compiler lowers to a native callable (e.g. a Kolon-style lambda literal). pred is anything responding to #call(item). The _eval family below is the evaluator-driven generalisation used for arbitrary pure bodies.



459
460
461
462
463
 
# File 'lib/barefoot_js.rb', line 459

def filter(recv, pred)
  return [] unless recv.is_a?(Array)

  recv.select { |item| pred.call(item) }
end

#filter_eval(recv, pred_json, param, base_env = {}) ⇒ Object 



888
889
890
 
# File 'lib/barefoot_js.rb', line 888

def filter_eval(recv, pred_json, param, base_env = {})
  Evaluator.filter_json(recv, pred_json, param, base_env)
end

#find(recv, pred) ⇒ Object 



477
478
479
480
481
 
# File 'lib/barefoot_js.rb', line 477

def find(recv, pred)
  return nil unless recv.is_a?(Array)

  recv.find { |item| pred.call(item) }
end

#find_eval(recv, pred_json, param, forward = true, base_env = {}) ⇒ Object 



900
901
902
 
# File 'lib/barefoot_js.rb', line 900

def find_eval(recv, pred_json, param, forward = true, base_env = {})
  Evaluator.find_json(recv, pred_json, param, forward, base_env)
end

#find_index(recv, pred) ⇒ Object 



483
484
485
486
487
488
 
# File 'lib/barefoot_js.rb', line 483

def find_index(recv, pred)
  return -1 unless recv.is_a?(Array)

  recv.each_index { |i| return i if pred.call(recv[i]) }
  -1
end

#find_index_eval(recv, pred_json, param, forward = true, base_env = {}) ⇒ Object 



904
905
906
 
# File 'lib/barefoot_js.rb', line 904

def find_index_eval(recv, pred_json, param, forward = true, base_env = {})
  Evaluator.find_index_json(recv, pred_json, param, forward, base_env)
end

#find_last(recv, pred) ⇒ Object 



490
491
492
493
494
495
 
# File 'lib/barefoot_js.rb', line 490

def find_last(recv, pred)
  return nil unless recv.is_a?(Array)

  recv.reverse_each { |item| return item if pred.call(item) }
  nil
end

#find_last_index(recv, pred) ⇒ Object 



497
498
499
500
501
502
 
# File 'lib/barefoot_js.rb', line 497

def find_last_index(recv, pred)
  return -1 unless recv.is_a?(Array)

  (recv.length - 1).downto(0) { |i| return i if pred.call(recv[i]) }
  -1
end

#flat(recv, depth = 1) ⇒ Object

Array.prototype.flat(depth?) -- flatten nested arrays depth levels deep. depth of -1 is the Infinity sentinel (flatten fully); 0 returns a shallow copy.



599
600
601
602
603
604
605
606
607
608
609
610
611
 
# File 'lib/barefoot_js.rb', line 599

def flat(recv, depth = 1)
  return [] unless recv.is_a?(Array)

  out = []
  recv.each do |el|
    if !depth.zero? && el.is_a?(Array)
      out.concat(flat(el, depth.positive? ? depth - 1 : depth))
    else
      out << el
    end
  end
  out
end

#flat_dynamic(recv, depth) ⇒ Object

Array.prototype.flat(depth) where depth is a DYNAMIC value (#2094) -- e.g. items.flat(props.depth) -- rather than a compile-time literal. Coerces depth via JS ToIntegerOrInfinity (truncate toward zero; NaN/non-numeric -> 0; negative -> 0; +Infinity or a huge finite value -> flatten fully) and delegates to flat.

This is a SEPARATE method from flat, not a smarter overload of it: flat's depth parameter treats -1 as a compile-time SENTINEL meaning "the source literally wrote Infinity" (the parser's own normalisation, baked into the emitted template). A genuinely dynamic depth value that happens to be -1 at render time means the JS-correct OPPOSITE: .flat(-1) never recurses (same as .flat(0), a shallow copy), because real JS only recurses when depth > 0. Reusing flat's int contract for a raw dynamic value would silently invert that case, so this coerces FIRST -- mapping a real +Infinity / huge finite value to flat's own -1 sentinel, and a real negative value to 0 -- and only then delegates to flat's recursion. Mirrors Go's FlatDynamicDepth/coerceFlatDepth (adapter-go-template/runtime/bf.go).



631
632
633
 
# File 'lib/barefoot_js.rb', line 631

def flat_dynamic(recv, depth)
  flat(recv, coerce_flat_depth(depth))
end

#flat_map(recv, key_kind, key) ⇒ Object

Array.prototype.flatMap(fn) value-returning field projection: map each element through a self/field projection, then flatten one level.



637
638
639
640
641
642
 
# File 'lib/barefoot_js.rb', line 637

def flat_map(recv, key_kind, key)
  return [] unless recv.is_a?(Array)

  projected = recv.map { |el| key_kind == 'field' ? field_value(el, key) : el }
  flat(projected, 1)
end

#flat_map_eval(recv, proj_json, param, base_env = {}) ⇒ Object 



908
909
910
 
# File 'lib/barefoot_js.rb', line 908

def flat_map_eval(recv, proj_json, param, base_env = {})
  Evaluator.flat_map_json(recv, proj_json, param, base_env)
end

#flat_map_tuple(recv, *specs) ⇒ Object

Array.prototype.flatMap(i => [i.a, i.b]) -- array-literal tuple projection. Each spec is [kind, key] (['self', ''] or ['field', 'a']).



647
648
649
650
651
652
653
654
655
656
657
 
# File 'lib/barefoot_js.rb', line 647

def flat_map_tuple(recv, *specs)
  return [] unless recv.is_a?(Array)

  out = []
  recv.each do |el|
    specs.each do |kind, key|
      out << (kind == 'field' ? field_value(el, key) : el)
    end
  end
  out
end

#floor(value) ⇒ Object 



418
419
420
421
 
# File 'lib/barefoot_js.rb', line 418

def floor(value)
  n = number(value)
  finite_number?(n) ? n.floor : n
end

#h(value) ⇒ Object

HTML-escaping helper for text interpolation (<%= bf.h(expr) %> -- stdlib ERB does not auto-escape). JS-style stringification via string (numbers per JS Number#toString, nil -> "", booleans -> "true"/"false"), then HTML-escaped.



395
396
397
 
# File 'lib/barefoot_js.rb', line 395

def h(value)
  html_escape(string(value))
end

#hydration_attrs ⇒ Object

Emits bf-h="<host>" bf-m="<slot>" bf-r="" conditionally. See spec/compiler.md "Slot identity".



89
90
91
92
93
94
95
96
97
 
# File 'lib/barefoot_js.rb', line 89

def hydration_attrs
  parts = []
  host = _bf_parent
  mount = _bf_mount
  parts << %(bf-h="#{host.gsub('"', '&quot;')}") if host && !host.empty?
  parts << %(bf-m="#{mount.gsub('"', '&quot;')}") if mount && !mount.empty?
  parts << 'bf-r=""' unless _is_child
  parts.join(' ')
end

#includes(recv, elem) ⇒ Object

Array.prototype.includes(x) / String.prototype.includes(sub) share a method name in JS; dispatch on Ruby class the way BarefootJS.pm dispatches on ref(). The Array arm scans with Evaluator.same_value_zero? (SameValueZero: no cross-type coercion, e.g. [2].includes("2") is false; NaN matches NaN) -- the same algorithm the evaluator's serialized-callback array-method path uses for .includes, so both positions agree.



444
445
446
447
448
449
450
451
 
# File 'lib/barefoot_js.rb', line 444

def includes(recv, elem)
  return recv.any? { |item| Evaluator.same_value_zero?(item, elem) } if recv.is_a?(Array)
  return false if recv.is_a?(Hash)

  s = recv.nil? ? '' : string(recv)
  needle = elem.nil? ? '' : string(elem)
  s.include?(needle)
end

#index_of(recv, elem) ⇒ Object

Array.prototype.indexOf(x) / .lastIndexOf(x) -- value-equality search. Non-array receivers return -1.



533
534
535
 
# File 'lib/barefoot_js.rb', line 533

def index_of(recv, elem)
  array_index_of(recv, elem, false)
end

#join(recv, sep = nil) ⇒ Object

Array.prototype.join(sep) with JS semantics: separator defaults to ",", undefined/null elements render as empty.



515
516
517
518
519
520
 
# File 'lib/barefoot_js.rb', line 515

def join(recv, sep = nil)
  return '' unless recv.is_a?(Array)

  sep = ',' if sep.nil?
  recv.map { |el| string(el) }.join(sep)
end

#json(value) ⇒ Object 



373
374
375
 
# File 'lib/barefoot_js.rb', line 373

def json(value)
  backend.encode_json(value)
end

#last_index_of(recv, elem) ⇒ Object 



537
538
539
 
# File 'lib/barefoot_js.rb', line 537

def last_index_of(recv, elem)
  array_index_of(recv, elem, true)
end

#lc(s) ⇒ Object

String.prototype.toLowerCase() / .toUpperCase().



505
506
507
 
# File 'lib/barefoot_js.rb', line 505

def lc(s)
  s.nil? ? '' : string(s).downcase
end

#length(recv) ⇒ Object

.length works on both arrays (element count) and strings (character count).



524
525
526
527
528
529
 
# File 'lib/barefoot_js.rb', line 524

def length(recv)
  return recv.length if recv.is_a?(Array)
  return 0 if recv.is_a?(Hash) || recv.nil?

  string(recv).length
end

#map_eval(recv, proj_json, param, base_env = {}) ⇒ Object 



912
913
914
 
# File 'lib/barefoot_js.rb', line 912

def map_eval(recv, proj_json, param, base_env = {})
  Evaluator.map_json(recv, proj_json, param, base_env)
end

#number(value) ⇒ Object

JS Number(v) mirror: numeric / boolean inputs convert as expected; non-numeric / nil yield real numeric NaN so downstream arithmetic propagates correctly (Math.floor(NaN) === NaN).



409
410
411
412
413
414
415
416
 
# File 'lib/barefoot_js.rb', line 409

def number(value)
  return Float::NAN if value.nil?
  return value ? 1 : 0 if value.is_a?(TrueClass) || value.is_a?(FalseClass)
  return value if value.is_a?(Numeric)
  return Float(value.strip) if value.is_a?(String) && value.strip =~ NUMERIC_STRING_RE

  Float::NAN
end

#pad_end(recv, target, pad_str = nil) ⇒ Object 



797
798
799
 
# File 'lib/barefoot_js.rb', line 797

def pad_end(recv, target, pad_str = nil)
  pad_string(recv.nil? ? '' : string(recv), target, pad_str, false)
end

#pad_start(recv, target, pad_str = nil) ⇒ Object

String.prototype.padStart / padEnd.



793
794
795
 
# File 'lib/barefoot_js.rb', line 793

def pad_start(recv, target, pad_str = nil)
  pad_string(recv.nil? ? '' : string(recv), target, pad_str, true)
end

#props_attr ⇒ Object 



109
110
111
112
113
114
115
116
117
118
119
 
# File 'lib/barefoot_js.rb', line 109

def props_attr
  props = _props
  return '' unless props && !props.empty?

  # The JSON must be attribute-escaped: a raw `'` inside a string value
  # (e.g. a blog paragraph) terminates the single-quoted attribute and
  # truncates the hydration payload. The browser entity-decodes the
  # attribute value, so the client's JSON.parse sees the original text.
  json = html_escape(backend.encode_json(props))
  %( bf-p='#{json}')
end

#provide_context(name, value) ⇒ Object 



136
137
138
139
 
# File 'lib/barefoot_js.rb', line 136

def provide_context(name, value)
  CONTEXT_STACKS[name].push(value)
  ''
end

#query(base, *triples) ⇒ Object

queryHref(base, { ... }) (#2042) -- build "base?k=v&..." from a flat list of (guard, key, value) triples. A pair is included iff its guard is truthy AND its value is a non-empty string. A value may instead be an Array, which APPENDS one pair per non-empty member. Repeating a key overwrites the value at its first position (URLSearchParams.set semantics); array members always append (.append semantics).



750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
 
# File 'lib/barefoot_js.rb', line 750

def query(base, *triples)
  b = base.nil? ? '' : string(base)
  pairs = []
  pos = {}
  i = 0
  while i + 2 < triples.length
    guard, key, val = triples[i], triples[i + 1], triples[i + 2]
    i += 3
    next unless truthy?(guard)

    k = key.nil? ? '' : string(key)
    if val.is_a?(Array)
      val.each do |m|
        sm = string(m)
        pairs << [k, sm] unless sm.empty?
      end
      next
    end
    v = val.nil? ? '' : string(val)
    next if v.empty?

    if pos.key?(k)
      pairs[pos[k]][1] = v
    else
      pos[k] = pairs.length
      pairs << [k, v]
    end
  end
  return b if pairs.empty?

  "#{b}?#{pairs.map { |pk, pv| "#{form_escape(pk)}=#{form_escape(pv)}" }.join('&')}"
end

#reduce(recv, opts = {}) ⇒ Object

Fold an array into a scalar via the arithmetic-fold catalogue (legacy, pre-#2018 path; reduce_eval below handles arbitrary reducer bodies). opts: { op: '+'|'*', key_kind:, key:, type: 'numeric'|'string', init:, direction: 'left'|'right' }.



843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
 
# File 'lib/barefoot_js.rb', line 843

def reduce(recv, opts = {})
  op = opts[:op] || '+'
  key_kind = opts[:key_kind] || 'self'
  key = opts[:key] || ''
  type = opts[:type] || 'numeric'
  direction = opts[:direction] || 'left'

  items = recv.is_a?(Array) ? recv.dup : []
  items.reverse! if direction == 'right'
  project = lambda { |item| key_kind == 'field' ? field_value(item, key) : item }

  if type == 'string'
    acc = opts[:init].nil? ? '' : string(opts[:init])
    items.each { |item| acc += string(project.call(item)) }
    return acc
  end

  # `init` rides through the adapter as whatever literal the template
  # emits -- often a numeric-looking String (JSON-decoded, not a Ruby
  # numeric literal) -- so route it through the same numeric coercion
  # as every per-element projection rather than trusting its Ruby class.
  acc = opts[:init].nil? ? 0 : numeric_or_zero(opts[:init])
  items.each do |item|
    n = numeric_or_zero(project.call(item))
    acc = op == '*' ? acc * n : acc + n
  end
  acc
end

#reduce_eval(recv, body_json, acc_name, item_name, init, direction = 'left', base_env = {}) ⇒ Object 



884
885
886
 
# File 'lib/barefoot_js.rb', line 884

def reduce_eval(recv, body_json, acc_name, item_name, init, direction = 'left', base_env = {})
  Evaluator.fold_json(recv, body_json, acc_name, item_name, init, direction, base_env)
end

#register_child_renderer(name, renderer) ⇒ Object

Register a renderer for render_child(name, ...). renderer is called as renderer.call(props_hash, invoking_bf) -- the invoking Context matters because a renderer registered on the root may be called from a nested child render, and the grandchild's scope / slot identity must chain off the CALLER's scope id, not the registrant's (#1897).



213
214
215
 
# File 'lib/barefoot_js.rb', line 213

def register_child_renderer(name, renderer)
  _child_renderers[name] = renderer
end

#register_components_from_manifest(manifest, signal_init: {}) ⇒ Object

Bulk registration from build manifest

bf build emits dist/templates/manifest.json describing every component the page might invoke. This walks that manifest and registers one child renderer per UI registry entry (ui/<name>/index -> slot key <name>), seeding each child's template vars from the manifest's statically-derived ssrDefaults (prop destructure defaults + signal/memo initial values). signal_init[slot_key] is an opt-in override for defaults the static extractor can't see through.



244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
 
# File 'lib/barefoot_js.rb', line 244

def register_components_from_manifest(manifest, signal_init: {})
  parent_scope = _scope_id
  parent = self

  manifest.each do |entry_name, entry|
    next if entry_name.to_s == '__barefoot__'

    m = entry_name.to_s.match(%r{\Aui/([^/]+)/index\z})
    next unless m

    slot_key = m[1]
    marked = entry[:markedTemplate] || ''
    next if marked.empty?

    template_name = marked.sub(%r{\Atemplates/}, '').sub(/\.erb\z/, '')
    sig_init = signal_init[slot_key]
    manifest_defaults = entry[:ssrDefaults]

    register_child_renderer(slot_key, lambda do |props, caller|
      host = caller || parent
      host_scope = host._scope_id || parent_scope
      child_bf = self.class.new(parent.backend)
      slot_id = props.delete(:_bf_slot)
      data_key = props.delete(:key)
      child_bf._data_key(data_key) unless data_key.nil?
      child_bf._scope_id(
        slot_id ? "#{host_scope}_#{slot_id}" : "#{template_name}_#{rand.to_s[2, 6]}",
      )
      child_bf._is_child(true)
      if slot_id
        child_bf._bf_parent(host_scope)
        child_bf._bf_mount(slot_id)
      end
      # Share the root registry so the child's own template can render
      # further imported components (#1897).
      child_bf._child_renderers(parent._child_renderers)
      child_bf._scripts(parent._scripts)
      child_bf._script_seen(parent._script_seen)

      extra =
        if sig_init
          sig_init.call(props)
        elsif manifest_defaults
          self.class.send(:derive_vars_from_defaults, manifest_defaults, props)
        else
          {}
        end

      html = parent.backend.render_named(template_name, child_bf, props.merge(extra))
      html.chomp
    end)
  end
end

#register_script(path) ⇒ Object

Script Registration



192
193
194
195
196
197
 
# File 'lib/barefoot_js.rb', line 192

def register_script(path)
  return if _script_seen.key?(path)

  _script_seen[path] = true
  _scripts.push(path)
end

#render_child(name, *args) ⇒ Object 



217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
 
# File 'lib/barefoot_js.rb', line 217

def render_child(name, *args)
  renderer = _child_renderers[name]
  raise "No renderer registered for child component '#{name}'" unless renderer

  # Accept both `render_child(name, k: v, ...)` (kwargs collapse into a
  # trailing Hash under Ruby's argument-splat rules) and the explicit
  # single-Hash form `render_child(name, { k: v })`.
  props = (args.length == 1 && args[0].is_a?(Hash)) ? args[0].dup : Hash[*args]
  # JSX children come in via the ERB backend's content-capture buffer
  # slice; materialize it through the backend so the child renderer sees
  # `props[:children]` as already-rendered HTML. Guard on `key?` so a
  # childless invocation doesn't gain a spurious `children: nil` key.
  props[:children] = backend.materialize(props[:children]) if props.key?(:children)
  renderer.call(props, self)
end

#repeat(recv, count) ⇒ Object

String.prototype.repeat(n) -- a count <= 0 degrades to '' rather than raising (JS throws RangeError for negative counts; SSR templates degrade instead of dying mid-render).



786
787
788
789
790
 
# File 'lib/barefoot_js.rb', line 786

def repeat(recv, count)
  s = recv.nil? ? '' : string(recv)
  n = count.nil? ? 0 : count.to_i
  n.positive? ? s * n : ''
end

#replace(recv, pattern, replacement) ⇒ Object

String.prototype.replace(pattern, replacement) -- string-pattern form only, replacing the FIRST occurrence, literally (no regex metacharacters, no $1-style replacement interpolation).



732
733
734
735
736
737
738
739
740
741
742
 
# File 'lib/barefoot_js.rb', line 732

def replace(recv, pattern, replacement)
  s = recv.nil? ? '' : string(recv)
  o = pattern.nil? ? '' : string(pattern)
  n = replacement.nil? ? '' : string(replacement)
  return n + s if o.empty?

  idx = s.index(o)
  return s if idx.nil?

  s[0...idx] + n + s[(idx + o.length)..]
end

#reverse(recv) ⇒ Object

Array.prototype.reverse() / .toReversed() -- always returns a new Array (SSR renders a snapshot; the mutate-vs-copy JS distinction is moot here).



592
593
594
 
# File 'lib/barefoot_js.rb', line 592

def reverse(recv)
  recv.is_a?(Array) ? recv.reverse : []
end

#revoke_context(name) ⇒ Object 



141
142
143
144
145
 
# File 'lib/barefoot_js.rb', line 141

def revoke_context(name)
  stack = CONTEXT_STACKS[name]
  stack.pop unless stack.empty?
  ''
end

#round(value) ⇒ Object 



428
429
430
431
 
# File 'lib/barefoot_js.rb', line 428

def round(value)
  n = number(value)
  finite_number?(n) ? (n + 0.5).floor : n
end

#scope_attr ⇒ Object

bf-s is the addressable scope id only (#1249).



83
84
85
 
# File 'lib/barefoot_js.rb', line 83

def scope_attr
  _scope_id || ''
end

#scope_comment ⇒ Object

See spec/compiler.md "Slot identity" for the comment-scope wire format.



177
178
179
180
181
182
183
184
185
186
 
# File 'lib/barefoot_js.rb', line 177

def scope_comment
  scope_id = _scope_id || ''
  host_segment = ''
  host = _bf_parent
  mount = _bf_mount
  host_segment = "|h=#{host}|m=#{mount || ''}" if host && !host.empty?
  props_json = ''
  props_json = "|#{backend.encode_json(_props)}" if _props && !_props.empty?
  "<!--bf-scope:#{scope_id}#{host_segment}#{props_json}-->"
end

#scripts ⇒ Object 



199
200
201
 
# File 'lib/barefoot_js.rb', line 199

def scripts
  _scripts.map { |path| %(<script type="module" src="#{path}"></script>) }.join("\n")
end

#search_params(query = '') ⇒ Object

search_params(query = '') -- request-scoped reader for the reactive searchParams() environment signal (router v0.5, #1922), built from a raw query string. The compiled template reads it via v[:searchParams].get('key').



74
75
76
 
# File 'lib/barefoot_js.rb', line 74

def search_params(query = '')
  SearchParams.new(query)
end

#slice(recv, start, end_ = nil) ⇒ Object

Array.prototype.slice(start, end?). Mirrors the Go/Perl bf_slice / slice arithmetic so adapter output stays symmetric.



568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
 
# File 'lib/barefoot_js.rb', line 568

def slice(recv, start, end_ = nil)
  return [] unless recv.is_a?(Array)

  len = recv.length
  return [] if len.zero?

  s = start.nil? ? 0 : start.to_i
  s = len + s if s.negative?
  s = 0 if s.negative?
  s = len if s > len

  e = end_.nil? ? len : end_.to_i
  e = len + e if e.negative?
  e = 0 if e.negative?
  e = len if e > len

  return [] if s >= e

  recv[s...e]
end

#some(recv, pred) ⇒ Object 



471
472
473
474
475
 
# File 'lib/barefoot_js.rb', line 471

def some(recv, pred)
  return false unless recv.is_a?(Array)

  recv.any? { |item| pred.call(item) }
end

#some_eval(recv, pred_json, param, base_env = {}) ⇒ Object 



896
897
898
 
# File 'lib/barefoot_js.rb', line 896

def some_eval(recv, pred_json, param, base_env = {})
  Evaluator.some_json(recv, pred_json, param, base_env)
end

#sort(recv, opts = {}) ⇒ Object

Array.prototype.sort(cmp) / .toSorted(cmp) -- fixed comparator catalogue (legacy, pre-#2018 path; sort_eval below handles arbitrary comparator bodies). opts[:keys] is a priority-ordered list of { key_kind:, key:, compare_type:, direction: }. Stable (ties break on original index) and non-mutating.



806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
 
# File 'lib/barefoot_js.rb', line 806

def sort(recv, opts = {})
  return [] unless recv.is_a?(Array)

  spec = (opts[:keys] || []).map do |k|
    {
      key_kind: k[:key_kind] || 'self',
      key: k[:key] || '',
      compare_type: k[:compare_type] || 'numeric',
      direction: k[:direction] || 'asc',
    }
  end
  return recv.dup if spec.empty?

  decorated = recv.each_with_index.map do |item, idx|
    keys = spec.map { |sp| sp[:key_kind] == 'field' ? field_value(item, sp[:key]) : item }
    [keys, item, idx]
  end

  sorted = decorated.sort do |x, y|
    result = 0
    spec.each_index do |i|
      c = compare_sort_key(x[0][i], y[0][i], spec[i][:compare_type])
      next if c.zero?

      result = spec[i][:direction] == 'desc' ? -c : c
      break
    end
    result.zero? ? (x[2] <=> y[2]) : result
  end

  sorted.map { |pair| pair[1] }
end

#sort_eval(recv, cmp_json, param_a, param_b, base_env = {}) ⇒ Object

Evaluator-driven sort / reduce / higher-order predicates (#2018): the comparator / reducer / predicate body rides as a serialized- ParsedExpr JSON string and is evaluated per element, delegating to the shared BarefootJS::Evaluator. find_eval / find_index_eval take a forward flag (false -> findLast / findLastIndex).



880
881
882
 
# File 'lib/barefoot_js.rb', line 880

def sort_eval(recv, cmp_json, param_a, param_b, base_env = {})
  Evaluator.sort_by_json(recv, cmp_json, param_a, param_b, base_env)
end

#split(recv, sep = nil, limit = nil) ⇒ Object

String.prototype.split(sep) -- string -> Array. An empty separator splits into individual characters; a nil separator returns the whole string in a single-element Array; trailing empty fields are kept (JS parity -- Ruby's String#split(str, -1) already matches this, and (unlike a Regexp) a String separator is matched literally).



684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
 
# File 'lib/barefoot_js.rb', line 684

def split(recv, sep = nil, limit = nil)
  s = (recv.nil? || recv.is_a?(Array) || recv.is_a?(Hash)) ? '' : string(recv)
  parts =
    if sep.nil?
      [s]
    elsif string(sep).empty?
      s.chars
    elsif s.empty?
      ['']
    else
      s.split(string(sep), -1)
    end
  unless limit.nil?
    n = limit.to_i
    if n.zero?
      parts = []
    elsif n.positive? && n < parts.length
      parts = parts[0...n]
    end
  end
  parts
end

#spread_attrs(bag) ⇒ Object

JSX intrinsic-element spread (#1407)

Mirrors the JS spreadAttrs runtime and the Go/Perl adapters' spread helpers so SSR output stays byte-equal across adapters. Generated ERB templates invoke this as <%= bf.spread_attrs(bag) %>.

Skip rules: nil/false values, event handlers (on[A-Z]...), and children. ref is intentionally NOT filtered (matches the JS reference). Key remap: className -> class, htmlFor -> for; SVG camelCase attrs preserved; other camelCase keys lowered to kebab-case. style routes through style_to_css. Output is deterministic: keys are sorted alphabetically before emission.

Unlike the Perl/Go ports, no boolean-sentinel detection is needed -- Ruby's true/false are real booleans, distinct from 0/1, so a bag value's Ruby class alone tells JS-boolean from JS-number.



934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
 
# File 'lib/barefoot_js.rb', line 934

def spread_attrs(bag)
  return '' unless bag.is_a?(Hash)

  parts = []
  bag.keys.sort_by(&:to_s).each do |key|
    key_s = key.to_s
    if key_s.length > 2 && key_s.start_with?('on')
      c = key_s[2]
      next if c.upcase == c
    end
    next if key_s == 'children'

    val = bag[key]
    next if val.nil?

    if val.is_a?(TrueClass) || val.is_a?(FalseClass)
      next unless val

      parts << to_attr_name(key_s)
      next
    end

    if key_s == 'style'
      css = style_to_css(val)
      next if css.nil? || css.empty?

      parts << %(style="#{html_escape(css)}")
      next
    end

    parts << %(#{to_attr_name(key_s)}="#{html_escape(string(val))}")
  end
  return '' if parts.empty?

  # Mark the result raw so the calling template's plain `<%=` doesn't
  # need a second escape pass (the backend decides how "raw" is
  # represented for its engine; ERB's own emit has no auto-escape, so
  # BarefootJS::Backend::Erb's `mark_raw` is the identity function).
  backend.mark_raw(parts.join(' '))
end

#starts_with(recv, prefix, position = nil) ⇒ Object

String.prototype.startsWith(prefix, position?).



708
709
710
711
712
713
714
715
716
 
# File 'lib/barefoot_js.rb', line 708

def starts_with(recv, prefix, position = nil)
  s = recv.nil? ? '' : string(recv)
  p = prefix.nil? ? '' : string(prefix)
  unless position.nil?
    n = clamp_index(position.to_i, s.length)
    s = s[n..] || ''
  end
  s.start_with?(p)
end

#streaming_bootstrap ⇒ Object

Streaming SSR (Out-of-Order)



350
351
352
 
# File 'lib/barefoot_js.rb', line 350

def streaming_bootstrap
  %{<script>(function(){function s(id){var a=document.querySelector('[bf-async="'+id+'"]');var t=document.querySelector('template[bf-async-resolve="'+id+'"]');if(!a||!t)return;a.replaceChildren(t.content.cloneNode(true));a.removeAttribute('bf-async');t.remove();requestAnimationFrame(function(){if(window.__bf_hydrate)window.__bf_hydrate()})};window.__bf_swap=s})()</script>}
end

#string(value) ⇒ Object

JS String(v) mirror, EXCEPT nil renders as '' (not the literal "null") so an unset prop doesn't surface as literal text in user-facing HTML -- the same divergence the Go/Perl adapters document for their string helper. This is the canonical JS-ish stringifier used throughout this file (join, spread_attrs, h, reduce's string fold, ...).



383
384
385
386
387
388
389
 
# File 'lib/barefoot_js.rb', line 383

def string(value)
  return '' if value.nil?
  return value ? 'true' : 'false' if value.is_a?(TrueClass) || value.is_a?(FalseClass)
  return Evaluator.number_to_string(value) if value.is_a?(Numeric)

  value.to_s
end

#text_end ⇒ Object 



172
173
174
 
# File 'lib/barefoot_js.rb', line 172

def text_end
  '<!--/-->'
end

#text_start(slot_id) ⇒ Object 



168
169
170
 
# File 'lib/barefoot_js.rb', line 168

def text_start(slot_id)
  "<!--bf:#{slot_id}-->"
end

#to_fixed(value, digits = 0) ⇒ Object

Number.prototype.toFixed(digits) -- fixed-decimal string with zero-padding, rounding half toward +Infinity (matching round).



668
669
670
671
672
673
674
675
676
677
 
# File 'lib/barefoot_js.rb', line 668

def to_fixed(value, digits = 0)
  n = number(value)
  return 'NaN' if n.respond_to?(:nan?) && n.nan?
  return n.negative? ? '-Infinity' : 'Infinity' if n.respond_to?(:infinite?) && n.infinite?

  digits = 0 if digits.nil? || digits.negative?
  factor = 10.0**digits
  rounded = (n * factor + 0.5).floor
  format("%.#{digits}f", rounded / factor)
end

#trim(recv) ⇒ Object

String.prototype.trim().



660
661
662
663
664
 
# File 'lib/barefoot_js.rb', line 660

def trim(recv)
  return '' if recv.nil? || recv.is_a?(Array) || recv.is_a?(Hash)

  string(recv).gsub(/\A\p{Space}+|\p{Space}+\z/, '')
end

#truthy?(value) ⇒ Boolean

JS truthiness (falsy: false, nil, 0, NaN, ""). Delegates to the shared evaluator so template-emitted conditionals (if bf.truthy?(x)) and callback-body evaluation agree byte-for-byte.

Returns:

  • (Boolean) 


402
403
404
 
# File 'lib/barefoot_js.rb', line 402

def truthy?(value)
  Evaluator.truthy?(value)
end

#uc(s) ⇒ Object 



509
510
511
 
# File 'lib/barefoot_js.rb', line 509

def uc(s)
  s.nil? ? '' : string(s).upcase
end

#use_context(name, default = nil) ⇒ Object 



147
148
149
150
 
# File 'lib/barefoot_js.rb', line 147

def use_context(name, default = nil)
  stack = CONTEXT_STACKS[name]
  stack.empty? ? default : stack.last
end