conceptql 0.6.0 → 0.7.0

data/lib/conceptql/diagram_renderer/drawing.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+require "json"
+
+module ConceptQL
+  module DiagramRenderer
+    # The drawing that frontend/lib/conceptql-diagram/src/renderer.js makes on
+    # its first update(), at duration 0: the stream gradients for <defs> and the
+    # <g class="vis-algorithm"> group with the links, the nodes and the recall
+    # arcs. Elements, attributes and their order are the renderer's. Each
+    # method names the renderer.js method it ports. lockNodes changes only the
+    # class of the root svg, which the caller writes.
+    #
+    # data is a diagram tree with ids (DiagramData.from makes one).
+    #
+    # Two options serve the in-app SVG (App). They write what renderer.js does
+    # with event handlers and transitions:
+    #
+    # - hooks: each node group gets data-node-id (the element that onNodeClick
+    #   listens on), and each "+" insert button gets data-insert-before (the
+    #   element that onInsertBefore listens on) unless lock_nodes is true. Each
+    #   element that a transition moves (MOVED) gets data-diagram-key, made
+    #   from node ids as the D3 joins key them, so it is the same in every
+    #   render of the same node. Each recall arc (.vis-connect) gets
+    #   data-recall-node-ids, a JSON array of the ids of the nodes whose
+    #   mouseenter shows the arcs (see recall_node_ids).
+    # - css_transforms: each MOVED element's position is written as
+    #   style="transform: translate(Xpx, Ypx)" and not as the transform
+    #   attribute, because CSS transitions cannot animate the attribute.
+    class Drawing
+      # The classes of the elements whose transform renderer.js transitions.
+      MOVED = %w[vis-link vis-link-new vis-link-path vis-node].freeze
+
+      attr_reader :data, :show_counts, :show_options
+
+      def initialize(data, show_counts: false, show_options: false, hooks: false, lock_nodes: true, css_transforms: false)
+        @data = data
+        @show_counts = show_counts
+        @show_options = show_options
+        @hooks = hooks
+        @lock_nodes = lock_nodes
+        @css_transforms = css_transforms
+        root = Geometry.layout(data)
+        @nodes = root.descendants
+        @links = root.links
+      end
+
+      # updateLinearGradients
+      def gradients
+        Geometry::LINEAR_GRADIENTS.map do |gradient|
+          stops = [ [ "5%", 0 ], [ "95%", 1 ] ].map do |offset, opacity|
+            Svg.element("stop", { "offset" => offset, "stop-color" => gradient[:color], "stop-opacity" => opacity })
+          end
+          Svg.element("linearGradient", { "x1" => 0, "x2" => 0, "y1" => 0, "y2" => 1, "id" => "gradient-#{gradient[:name]}" }, stops)
+        end
+      end
+
+      # updateTree: the links, then the nodes, then the recall arcs.
+      def algorithm
+        children = @links.map { link(_1) } + @nodes.map { node(_1) } + recall_connections.map { recall(_1) }
+        Svg.element("g", { "class" => "vis-algorithm", "data-test-diagram-group" => "" }, children)
+      end
+
+      private
+
+      # updateLinks, for one link.
+      def link(link)
+        target = link.target.data
+        streams = target["outputTypes"].each_with_index.map { |type, i| stream(link, type, i) }
+        attributes = { "class" => "vis-link", **place(Geometry.link_offset(target["outputTypes"]), 0), **key("link:#{link_key(link)}") }
+        Svg.element("g", attributes, streams + [ insert_button(link) ])
+      end
+
+      # The "+" insert button of a link (.vis-link-new).
+      def insert_button(link)
+        classes = [ "vis-link-new" ]
+        classes << "is-selectable" if JsFormat.truthy?(link.target.data["isAttachable"])
+        position = Geometry.insert_button_position(link)
+        text = link.source.data["name"] == "root" && link.target.data["name"] == "hidden" ? [ "New Stream" ] : []
+        attributes = { "class" => classes.join(" "), **place(position[:x], position[:y]), **key("link-new:#{link_key(link)}") }
+        attributes["data-insert-before"] = link.target.data["id"] if @hooks && !@lock_nodes
+        Svg.element("g", attributes, [
+          Svg.element("circle", { "r" => 15 }),
+          Svg.element("use", { "xlink:href" => "#operator-new", "height" => 20, "width" => 20, "x" => -10, "y" => -10 }),
+          Svg.element("text", { "class" => "vis-link-text", "x" => 30, "y" => 1 }, text)
+        ])
+      end
+
+      # One stream of a link (.vis-link-path): the target and source paths and,
+      # with show_counts, the count label.
+      def stream(link, type, index)
+        path = Geometry.connector_path(link)
+        color = link.target.data["name"] == "hidden" ? "placeholder" : type
+        children = [
+          Svg.element("path", { "class" => "vis-link-path-target", "data-color" => color, "d" => path }),
+          Svg.element("path", { "class" => "vis-link-path-source", "stroke" => Geometry.source_gradient(link, index), "d" => path })
+        ]
+        children << count_label(link, type, index) if show_counts
+        attributes = { "class" => "vis-link-path", **place(Geometry.stream_offset(index), 0), **key("link-path:#{link_key(link)}:#{index}") }
+        Svg.element("g", attributes, children)
+      end
+
+      def count_label(link, type, index)
+        target = link.target.data
+        lines = Geometry.count_label_lines(target["counts"], type) || []
+        position = Geometry.count_label_position(link, index, target["outputTypes"].length)
+        tspans = lines.each_with_index.map do |line, j|
+          Svg.element("tspan", { "x" => 0, "dy" => j.zero? ? 0 : Geometry::COUNT_LABEL[:line_height] }, [ line ])
+        end
+        Svg.element("text", {
+          "class" => "vis-link-count",
+          "transform" => translate(position[:x], position[:y]),
+          "text-anchor" => position[:anchor],
+          "fill" => Geometry.count_label_color(type),
+          "font-size" => Geometry::COUNT_LABEL[:font_size]
+        }, tspans)
+      end
+
+      # updateNodes, for one node.
+      def node(node)
+        d = node.data
+        label = label?(d)
+        classes = [ "vis-node" ]
+        classes << "is-active" if JsFormat.truthy?(d["isSelected"])
+        classes << "is-error" unless empty?(d["errors"])
+        classes << "is-warning" unless empty?(d["warnings"])
+        classes << "is-label" if label
+        position = Geometry.node_position(node)
+
+        attributes = {
+          "operator-type" => "#{d['name']}-#{node.data_index}",
+          "class" => classes.join(" "),
+          "data-test-node" => "",
+          **place(position[:x], position[:y])
+        }
+        attributes.merge!("data-node-id" => d["id"], **key("node:#{JsFormat.string(d['id'])}")) if @hooks
+        Svg.element("g", attributes, [
+          Svg.element("use", { "class" => "vis-node-point", "height" => 40, "width" => 40, "data-color" => Geometry.point_color(d["outputTypes"]), "xlink:href" => "#operator-base-#{template(d, 'base')}" }),
+          Svg.element("use", { "class" => "vis-node-icon", "height" => 26, "width" => 26, "transform" => "translate(7,7)", "xlink:href" => "#operator-#{d['name']}" }),
+          Svg.element("use", { "class" => "vis-node-label", "xlink:href" => "#operator-label", "height" => 8, "width" => 10, "transform" => "translate(45, 32)" }),
+          badge("vis-node-warning", "#operator-warning"),
+          badge("vis-node-error", "#operator-error"),
+          description(d, label)
+        ])
+      end
+
+      # The warning and error badges, which CSS shows on .is-warning and
+      # .is-error nodes.
+      def badge(name, href)
+        Svg.element("g", { "class" => name }, [
+          Svg.element("circle", { "r" => 12 }),
+          Svg.element("use", { "xlink:href" => href, "height" => 22, "width" => 22, "transform" => "translate(-11,-11)" })
+        ])
+      end
+
+      # The title and the description lines. A labelled node's first value
+      # line is indented past the label icon.
+      def description(data, label)
+        title = Geometry.node_title(data)
+        heading = Svg.element("tspan", { "class" => "vis-node-description-heading", "style" => "font-size: 12px;" }, text(title))
+        values = Geometry.description_lines(data, show_options:).each_with_index.map do |line, i|
+          Svg.element("tspan", {
+            "class" => "vis-node-description-value",
+            "style" => "font-size: 10px;",
+            "x" => label && i.zero? ? 15 : 0,
+            "y" => "#{JsFormat.number(((i + 1) * 1.4) + 0.2)}em"
+          }, text(line))
+        end
+        Svg.element("text", { "class" => "vis-node-description", "transform" => "translate(45,21)" }, [ heading, *values ])
+      end
+
+      # updateRecalls, for one recall arc.
+      def recall(connection)
+        attributes = { "class" => "vis-connect", "d" => Geometry.recall_path(connection) }
+        attributes["data-recall-node-ids"] = JSON.generate(recall_node_ids(connection)) if @hooks
+        Svg.element("path", attributes)
+      end
+
+      # The ids of the nodes for which isRecalled finds this arc. renderer.js
+      # shows every arc on the mouseenter of such a node. A recall node
+      # compares its first value, and any other node its label when that is
+      # truthy, with the first value of the arc's recall.
+      def recall_node_ids(connection)
+        value = connection[0].data["values"][0]
+        nodes = @nodes.select do |node|
+          d = node.data
+          if d["name"] == "recall"
+            values = d["values"]
+            (values.is_a?(Array) || values.is_a?(String)) && !values.empty? && same?(values[0], value)
+          else
+            label?(d) && same?(d["parameters"]["label"], value)
+          end
+        end
+        nodes.map { JsFormat.string(_1.data["id"]) }
+      end
+
+      # recallConnections: each recall node with the first node (in
+      # descendants order) whose label is the recall's first value.
+      def recall_connections
+        @nodes.filter_map do |recall|
+          values = recall.data["values"]
+          next unless recall.data["name"] == "recall" && !empty?(values)
+
+          recalled = @nodes.find do |node|
+            parameters = node.data["parameters"]
+            parameters.is_a?(Hash) && parameters.key?("label") && same?(parameters["label"], values[0])
+          end
+          [ recall, recalled ] if recalled
+        end
+      end
+
+      # The is-label class: `params && params.label`.
+      def label?(data)
+        parameters = data["parameters"]
+        parameters.is_a?(Hash) && JsFormat.truthy?(parameters["label"])
+      end
+
+      # isEmpty in renderer.js: nil, an empty string or array, or an object
+      # whose length is 0.
+      def empty?(value)
+        case value
+        when nil then true
+        when String, Array then value.empty?
+        when Hash then value["length"].is_a?(Numeric) && value["length"].zero?
+        else false
+        end
+      end
+
+      # JavaScript ===: arrays and objects are equal only to themselves.
+      def same?(a, b) = a.is_a?(Array) || a.is_a?(Hash) ? a.equal?(b) : a == b
+
+      # A key in a template literal: a missing key is "undefined".
+      def template(data, key) = data.key?(key) ? JsFormat.string(data[key]) : "undefined"
+
+      # d3's text(value): nil is no text.
+      def text(value) = value.nil? ? [] : [ JsFormat.string(value) ].reject(&:empty?)
+
+      def translate(x, y) = "translate(#{JsFormat.number(x)},#{JsFormat.number(y)})"
+
+      # The position of a MOVED element: the transform attribute or, with
+      # css_transforms, the same translation as a CSS transform.
+      def place(x, y)
+        return { "transform" => translate(x, y) } unless @css_transforms
+
+        { "style" => "transform: translate(#{JsFormat.number(x)}px, #{JsFormat.number(y)}px)" }
+      end
+
+      # The data-diagram-key attribute of a MOVED element, with hooks.
+      def key(value) = @hooks ? { "data-diagram-key" => value } : {}
+
+      # The D3 join key of a link (updateTree): "<source id>-<target id>".
+      def link_key(link) = "#{JsFormat.string(link.source.data['id'])}-#{JsFormat.string(link.target.data['id'])}"
+    end
+  end
+end

data/lib/conceptql/diagram_renderer/geometry.rb

@@ -0,0 +1,380 @@
+# frozen_string_literal: true
+
+module ConceptQL
+  module DiagramRenderer
+    # The geometry and presentation rules of the diagram: layout, connector
+    # paths, offsets, colours and label packing. A port of
+    # frontend/lib/conceptql-diagram/src/geometry.js. The JavaScript file is the
+    # reference: every fixture's reference/geometry.json comes from it, and
+    # test/diagram_renderer/geometry_test.rb compares the two. Each method
+    # names the JavaScript function it ports.
+    #
+    # Input is a diagram tree as hashes with string keys ("id", "name", "base",
+    # "humanName", "outputTypes", "values", "parameters", "children", "counts").
+    # A node, as `layout` returns it and the link methods take it, has `x`, `y`
+    # and `data` (a TreeLayout::Node); a link has `source` (the parent) and
+    # `target` (the child). Positions are hashes with symbol keys.
+    #
+    # Coordinates: the tree layout puts depth along +y. The diagram draws the
+    # root at the bottom and grows upward, so every y is negated when drawn.
+    module Geometry
+      extend self
+
+      # NODE_SPACING
+      NODE_SPACING = { x: 200, y: 140 }.freeze
+
+      # LINEAR_GRADIENTS: the colour of each stream type, for link source
+      # gradients.
+      LINEAR_GRADIENTS = [
+        { name: "condition_occurrence", color: "#d6758a" },
+        { name: "death", color: "#a7736f" },
+        { name: "drug_exposure", color: "#cf92d2" },
+        { name: "person", color: "#a9c9e7" },
+        { name: "placeholder", color: "#f6f3f5" },
+        { name: "procedure_cost", color: "#e0d67f" },
+        { name: "procedure_occurrence", color: "#a7e2ac" },
+        { name: "unknown", color: "#958c93" },
+        { name: "visit_occurrence", color: "#e8d4b3" }
+      ].map(&:freeze).freeze
+
+      CHARACTERS_PER_LINE = 20
+      # Option lines ("key: value") may run wider than values: a key cut at 20
+      # characters loses the value readers need (Ryan, 2026-09-24).
+      OPTION_CHARACTERS_PER_LINE = 40
+      MAX_DESCRIPTION_LINES = 3
+      ELLIPSIS = "…"
+
+      # MAX_TITLE_LENGTH: the longest node title (12px bold) that stays clear of
+      # the next node's title.
+      MAX_TITLE_LENGTH = 22
+
+      # Parameters that are never shown as option lines: the label already
+      # heads the description, and the id is bookkeeping.
+      HIDDEN_OPTIONS = %w[label id].freeze
+
+      # COUNT_LABEL: the styling of edge-count labels, the grey of the spec's
+      # GraphViz diagrams.
+      COUNT_LABEL = { fill: "#817980", font_size: 10, line_height: 12, ascent: 8, gap: 8 }.freeze
+
+      # Each stream's count label is coloured like its domain's node glyph (the
+      # colours of diagram_styles.css .vis-node-point[data-color]).
+      DOMAIN_LABEL_COLORS = {
+        "condition_occurrence" => "#ad4a5b",
+        "death" => "#704a4a",
+        "drug_exposure" => "#9f57a5",
+        "observation_period" => "#6fbbba",
+        "person" => "#7193cd",
+        "procedure_occurrence" => "#90d796",
+        "visit_occurrence" => "#d1a776"
+      }.freeze
+
+      # layout: lays the tree out with d3.tree() (TreeLayout). Returns the root
+      # TreeLayout::Node with x and y on every node, and a depth-first pre-order
+      # data_index in input order.
+      def layout(data)
+        root = TreeLayout.hierarchy(data) { _1["children"] }
+
+        index = 0
+        root.each_before do |node|
+          node.data_index = index
+          index += 1
+        end
+
+        TreeLayout.new(node_size: [ NODE_SPACING[:x], NODE_SPACING[:y] ], separation: ->(_a, _b) { 1 }).call(root)
+      end
+
+      # diagonalPath: the connector from a child (target) down to its parent
+      # (source). The +0.01 keeps the path from being perfectly vertical: a
+      # zero-width bounding box would make the objectBoundingBox gradient on the
+      # source path render as nothing.
+      def diagonal_path(link)
+        path("M", link.target.x, ",", -link.target.y, "v30L", link.source.x + 0.01, ",", -link.source.y - 20, "v20")
+      end
+
+      # elbowPath: the right-hand input of a filter enters the filter's side.
+      def elbow_path(link)
+        path("M", link.target.x, ",", -link.target.y + 20, "v10L", link.source.x + 30, ",", -link.source.y - 15, "h-10")
+      end
+
+      # straightPath: streams under the (invisible) root run straight down.
+      def straight_path(link)
+        path("M", link.target.x, ",", -link.target.y + 20, "v10L", link.target.x + 0.01, ",", -link.source.y)
+      end
+
+      # connectorPath: the connector for a link, by the shape of the source
+      # (parent) operator.
+      def connector_path(link)
+        if root?(link.source.data)
+          straight_path(link)
+        elsif second_filter_input?(link)
+          elbow_path(link)
+        else
+          diagonal_path(link)
+        end
+      end
+
+      # recallPath: the arc from a recall node to the node it recalls.
+      def recall_path((from, to))
+        dx = to.x - from.x
+        dy = to.y - from.y
+        dr = Math.sqrt((dx * dx) + (dy * dy)) * 0.8
+        path("M", from.x, ",", -from.y, "A", dr, ",", dr, " 0 0,1 ", to.x, ",", -to.y)
+      end
+
+      # linkOffset: more streams make a wider link bundle, so shift it left to
+      # stay centred.
+      def link_offset(target_output_types)
+        (target_output_types.length - 1) * -2.5
+      end
+
+      # streamOffset: each stream in a bundle sits 5px right of the previous one.
+      def stream_offset(index)
+        index * 5
+      end
+
+      # insertButtonPosition: the position of a link's "+" insert button,
+      # relative to the link group.
+      def insert_button_position(link)
+        source = link.source.data
+        output_types = link.target.data["outputTypes"]
+        x = link.source.x + ((output_types.length - 1) * 2.5)
+        y = -link.source.y - 66
+
+        if root?(source)
+          x = link.target.x
+        else
+          x += (link.target.x - link.source.x) / 2.0
+        end
+
+        x += 17 if source["base"] == "filter" && link.target.x > link.source.x
+
+        { x:, y: }
+      end
+
+      # nodePosition: the top-left of a node's 40x40 glyph box, centred on its
+      # layout point.
+      def node_position(node)
+        { x: node.x - 20, y: -node.y - 20 }
+      end
+
+      # sourceGradient: the stroke of a link's source-side path. Placeholder
+      # under the root, unknown into a hidden node, the cast's own type for
+      # casts, otherwise nil (the CSS data-color on the target path supplies the
+      # colour).
+      def source_gradient(link, stream_index)
+        source = link.source.data
+        target = link.target.data
+
+        if root?(source)
+          "url(#gradient-placeholder)"
+        elsif target["name"] == "hidden"
+          "url(#gradient-unknown)"
+        elsif source["base"] == "cast"
+          type = source["outputTypes"][stream_index]
+          "url(#gradient-#{JsFormat.truthy?(type) ? JsFormat.string(type) : 'unknown'})"
+        end
+      end
+
+      # pointColor: a node's glyph colour key, its single stream type or
+      # "mixed".
+      def point_color(output_types)
+        output_types.length == 1 ? output_types[0] : "mixed"
+      end
+
+      # nodeTitle: a node's title. Its humanName, unless that is longer than
+      # MAX_TITLE_LENGTH and the node is a vocabulary operator: then its
+      # vocabulary ID (e.g. "LOINC" rather than "Logical Observation Identifiers
+      # Names and Codes (Regenstrief Institute)").
+      def node_title(data)
+        title = data["humanName"]
+        vocabulary_id = data["vocabularyId"]
+        return vocabulary_id if title.is_a?(String) && title.length > MAX_TITLE_LENGTH && JsFormat.truthy?(vocabulary_id)
+
+        title
+      end
+
+      # descriptionLines: the lines under a node's heading. The label (if any)
+      # first, cut at 20 characters, then the values packed 20 characters to a
+      # line, 3 lines in all. A single over-long value is cut to 19 characters
+      # plus an ellipsis, and when values overflow the last line the ellipsis
+      # marks the cut.
+      #
+      # With show_options, the node's options follow as "key: value" lines, each
+      # cut at 40 characters, within the same 3-line limit. If they do not all
+      # fit, the last shown line ends in an ellipsis.
+      def description_lines(data, show_options: false)
+        display, overflowed = value_lines(data)
+        return display if !show_options || overflowed
+
+        parameters = data["parameters"]
+        parameters = {} unless JsFormat.truthy?(parameters)
+        options = JsFormat.entries(parameters)
+          .reject { |key, value| HIDDEN_OPTIONS.include?(key) || blank?(value) }
+          .map { |key, value| truncate_line("#{key}: #{value.is_a?(Array) ? JsFormat.join(value, ', ') : JsFormat.string(value)}", OPTION_CHARACTERS_PER_LINE) }
+
+        options.each do |option|
+          if display.length == MAX_DESCRIPTION_LINES
+            display[-1] += ELLIPSIS unless display[-1].end_with?(ELLIPSIS)
+            break
+          end
+          display.push(option)
+        end
+        display
+      end
+
+      # countLabelColor: the text colour of a stream's count label, grey for
+      # other domains.
+      def count_label_color(stream_type)
+        DOMAIN_LABEL_COLORS.fetch(stream_type, COUNT_LABEL[:fill])
+      end
+
+      # formatCount: 1234567 becomes "1,234,567".
+      def format_count(n)
+        JsFormat.string(n).gsub(/\B(?=(\d{3})+(?!\d))/, ",")
+      end
+
+      # countLabelLines: the two label lines for one stream, from the child
+      # node's counts[<stream type>] = { "rows", "n" }; nil when there is
+      # nothing to show.
+      def count_label_lines(counts, stream_type)
+        c = JsFormat.truthy?(counts) ? counts[stream_type] : nil
+        return nil unless c.is_a?(Hash) && c.key?("rows") && c.key?("n")
+
+        [ "rows=#{format_count(c['rows'])}", "n=#{format_count(c['n'])}" ]
+      end
+
+      # countLabelPosition: where a stream's count label sits, in its stream
+      # group's coordinates, beside the midpoint of the connector's sloped (or,
+      # under the root, vertical) run.
+      #
+      # One stream: on the outside of the slope, to the left (anchored at its
+      # end) when the child is left of its parent, otherwise to the right.
+      #
+      # Several streams (drawn side by side, stream 0 leftmost): each label goes
+      # on the side of the bundle nearest its own stream, so the left half of
+      # the streams label on the left and the rest on the right, stacking
+      # outward from the midpoint.
+      #
+      # On the outer side of the slope the connector rises away from the label,
+      # so the label hangs one ascent below the midpoint. On the inner side the
+      # connector falls away beneath it, so the label sits just above.
+      def count_label_position(link, stream_index = 0, stream_count = 1)
+        source = link.source.data
+        from = [ link.target.x, -link.target.y + 30 ]
+        to =
+          if root?(source)
+            [ link.target.x, -link.source.y ]
+          elsif second_filter_input?(link)
+            [ link.source.x + 30, -link.source.y - 15 ]
+          else
+            [ link.source.x, -link.source.y - 20 ]
+          end
+        mid_x = (from[0] + to[0]) / 2.0
+        mid_y = (from[1] + to[1]) / 2.0
+
+        sloped = !root?(source) && link.target.x != link.source.x
+        outer = link.target.x < link.source.x ? "left" : "right"
+
+        if stream_count <= 1
+          side = sloped ? outer : "right"
+          stack = 0
+        else
+          left_count = (stream_count / 2.0).ceil
+          side = stream_index < left_count ? "left" : "right"
+          stack = side == "left" ? stream_index : stream_index - left_count
+        end
+        inner = sloped && side != outer
+
+        # Each label is drawn inside its own stream's group, already shifted
+        # stream_offset(i) right. Cancel that so labels line up just outside the
+        # bundle's left or right edge.
+        own_shift = stream_offset(stream_index)
+        bundle_width = stream_offset(stream_count - 1)
+        label_height = 2 * COUNT_LABEL[:line_height]
+
+        {
+          x: side == "left" ? mid_x - COUNT_LABEL[:gap] - own_shift : mid_x + COUNT_LABEL[:gap] + bundle_width - own_shift,
+          y: inner ? mid_y - 2 - COUNT_LABEL[:line_height] - (stack * label_height) : mid_y + COUNT_LABEL[:ascent] + (stack * label_height),
+          anchor: side == "left" ? "end" : "start"
+        }
+      end
+
+      private
+
+      # A path string: numbers written as JavaScript writes them.
+      def path(*parts)
+        parts.map { _1.is_a?(String) ? _1 : JsFormat.number(_1) }.join
+      end
+
+      def root?(data) = data["name"] == "root"
+
+      # The link enters a filter as the filter's second (right-hand) input. The
+      # JavaScript compares the child object itself (===), so this compares
+      # identity.
+      def second_filter_input?(link)
+        source = link.source.data
+        source["base"] == "filter" && JsFormat.truthy?(source["children"]) && source["children"][1].equal?(link.target.data)
+      end
+
+      # isBlank
+      def blank?(value)
+        value.nil? || value == "" || value == []
+      end
+
+      # truncateLine: cut a line to `limit` characters, ellipsis included,
+      # without leaving a space before the ellipsis.
+      def truncate_line(text, limit)
+        text.length > limit ? JsFormat.trim_end(text[0, limit - 1]) + ELLIPSIS : text
+      end
+
+      # valueLines: the label and value packing JDE has always drawn. Returns
+      # [lines, overflowed]; overflowed means values were cut off because the
+      # lines ran out.
+      def value_lines(data)
+        lines = MAX_DESCRIPTION_LINES
+        overflowed = false
+        characters_remaining = CHARACTERS_PER_LINE
+        display = []
+        line = []
+        values = data["values"]
+        values = JsFormat.truthy?(values) ? values.dup : []
+
+        # If there is a label, cut it and make it the first line.
+        parameters = data["parameters"]
+        if JsFormat.truthy?(parameters) && JsFormat.truthy?(parameters["label"])
+          label_text = parameters["label"]
+          label_text = label_text[0, CHARACTERS_PER_LINE] + ELLIPSIS if JsFormat.length(label_text) > CHARACTERS_PER_LINE
+          display.push(label_text)
+          lines -= 1
+        end
+
+        # Now split the values into lines by the space available. The loop ends
+        # at the first falsy value, as `while ((value = values.pop()))` does.
+        values.reverse!
+        while JsFormat.truthy?(value = values.pop)
+          if JsFormat.length(value) > CHARACTERS_PER_LINE
+            value = value[0, CHARACTERS_PER_LINE - 1] + ELLIPSIS
+          elsif JsFormat.length(value) > characters_remaining
+            display.push(JsFormat.join(line, ", "))
+            lines -= 1
+            if lines.positive?
+              characters_remaining = CHARACTERS_PER_LINE
+              line = []
+            else
+              display[-1] += ELLIPSIS
+              overflowed = true
+              break
+            end
+          end
+
+          line.push(value)
+          characters_remaining -= JsFormat.length(value)
+
+          display.push(JsFormat.join(line, ", ")) if values.empty?
+        end
+
+        [ display, overflowed ]
+      end
+    end
+  end
+end

data/lib/conceptql/diagram_renderer/input_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module ConceptQL
+  module DiagramRenderer
+    # The input is not a diagram tree that DiagramData accepts (InputError in
+    # frontend/lib/conceptql-diagram/cli/src/render-static.js). The message says
+    # what is wrong, with the same text as the JavaScript.
+    class InputError < StandardError
+    end
+  end
+end