# render.R — HTML rendering and display

# ── Internal: locate and read the bundled JS ───────────────────────────────────

.bundle_js <- function() {

}

# ── Internal: accept either a raw rENA set, a pre-extracted ModelData list,

#             or a qe_plot object ────────────────────────────────────────────

#

# • ena.set objects  → qe_extract() with any forwarded args

# • qe_plot objects  → return the model slot directly

# • anything else    → assumed to be a ModelData list already

.to_model <- function(x, ...) {

}

# ── Internal: resolve graph_opts from a qe_plot object or plain list ──────────

# When x is a qe_plot, its stored opts are used as the base; the caller can

# still pass graph_opts to override individual keys.

.resolve_opts <- function(x, graph_opts = list()) {

}

# ── Internal: resolve title ───────────────────────────────────────────────────

.resolve_title <- function(x, title) {

}

# ── Internal: build the <qe-graph> element with child layer elements ──────────

#

# Each declarative child element maps directly to a rendering layer:

#   <qe-nodes>  — code-node labels (always rendered; controls label mode)

#   <qe-means>  — group mean markers + CI boxes  (omit to hide)

#   <qe-points> — unit scatter dots              (omit to hide)

#   <qe-edges>  — edge network                   (omit to hide)

#   <qe-trajectories> — ordered unit paths       (omit to hide)

#

# Presence of a child = the layer renders.

# Absence            = the layer is hidden.

# DOM order          = SVG render order (later children draw on top).

.build_graph_element <- function(opts) {

  # ── <qe-nodes> — always emitted; controls node label mode ────────────────

  # ── <qe-means> — show group means + optional CI boxes ────────────────────

  # Omit entirely only if explicitly suppressed (not currently exposed in API;

  # defaults to present so `qe_plot(set)` always shows group means).

  # ── <qe-points> — unit scatter dots (only when points = TRUE) ────────────

  }

  # ── <qe-edges> — edge network (omit when no primary target or suppressed) ─

  # Emitted only when at least one of group/unit is set (or compare/also are,

  # though those require a primary).  The R chain functions validate this.

    }

  }

  # ── <qe-trajectories> — ordered unit trajectories ───────────────────────

    )

    )

  }

}

# ── Internal: build the full HTML document string ─────────────────────────────

.build_html <- function(model_json, title = "qeviz", graph_opts = list()) {

}

# ── NULL-coalescing helper ─────────────────────────────────────────────────────

# ══ qe_plot object ════════════════════════════════════════════════════════════

#' Create a qeviz plot object

#'

#' Returns a `qe_plot` object that can be customised with chained `qe_*()`

#' functions and rendered by printing, [qe_export_html()], or [qe_html()].

#'

#' `width` and `height` set the plot dimensions and can be supplied here rather

#' than in a separate sizing call.

#'

#' @param x       Either a raw rENA / tma / ona set object **or** a `ModelData`

#'   list from [qe_model_data()] / [qe_extract()].

#' @param title   Window / tab title used when the plot is saved or opened.

#' @param width   CSS width string. Default `"100%"`.

#' @param height  Plot height in pixels (numeric) or any CSS string. Default `440`.

#' @param ...     Additional arguments forwarded to [qe_extract()] when `x` is a

#'   raw set (e.g. `group_col = "Condition"`).  Directionality is detected

#'   automatically from the set class and rarely needs to be overridden.

#'

#' @return An object of class `qe_plot`.

#'

#' @examples

#' \dontrun{

#' qe_plot(set)

#' qe_plot(set, height = 600) |> qe_group("FirstGame")

#' }

#'

#' @export

qe_plot <- function(x, title = "qeviz", width = "100%", height = 440, ...) {

    ),

  )

}

#' Render a qe_plot object in the viewer

#'

#' Called automatically when a `qe_plot` object is returned at the top level

#' of the console.  Writes to a temp file and opens the RStudio viewer or

#' the system browser.

#'

#' @param x A `qe_plot` object.

#' @param ... Ignored.

#' @export

print.qe_plot <- function(x, ...) {

}

# ══ Chain functions ════════════════════════════════════════════════════════════

#' Select which group means to display

#'

#' Controls which groups' mean markers and CI boxes appear in the plot.  This

#' is independent of edge rendering — use [qe_edges()] to select whose network

#' to draw.

#'

#' @param p         A `qe_plot` object.

#' @param ...       Group names to show means for.  Supply one or more strings,

#'   each matching a value in the model's group column.  Omit entirely to show

#'   means for **all** groups in the model (the default).

#' @param by        The metadata column used for grouping (e.g. `"Condition"`).

#'   Optional — used to validate against the column baked into the model at

#'   extraction time.  An error is raised if the column name does not match.

#' @param intervals Logical.  Show 95% CI box(es) around group mean(s).

#'   Default `TRUE`.

#'

#' @return The modified `qe_plot` object.

#'

#' @examples

#' \dontrun{

#' # Show means for all groups (default)

#' qe_plot(set) |> qe_group()

#'

#' # Show means for specific groups only

#' qe_plot(set) |> qe_group("FirstGame", "SecondGame")

#'

#' # Explicit column name — validates against model

#' qe_plot(set) |> qe_group("FirstGame", by = "Condition")

#' }

#'

#' @export

qe_group <- function(p, ..., by = NULL, intervals = TRUE) {

  # Validate `by` against the model's group_col

    }

  }

  # Validate requested group names against model

    }

    # Comma-separated list → `groups` attribute (means filter)

  } else {

    # No names → show all groups; remove any previous filter

  }

}

#' Select which edge network to draw

#'

#' Controls edge rendering.  Supply **either** a group name (`group`) **or** a

#' specific unit ID (`unit`) as the primary edge source; `compare` or `also`

#' optionally bring in a second group for subtraction or overlay.  Omitting both

#' `group` and `unit` (or calling `qe_edges(show = FALSE)`) suppresses the edge

#' network entirely, leaving only group means and unit points visible.

#'

#' Use [qe_units()] to inspect the unit IDs present in the model.

#'

#' @param p       A `qe_plot` object.

#' @param group   Name of the primary group whose **mean** edge network to draw.

#'   Must match a value in the model's group column.  Mutually exclusive with

#'   `unit`.

#' @param unit    ID of a single unit whose **individual** edge network to draw

#'   (e.g. `"FirstGame::steven z"`).  Mutually exclusive with `group`.

#'   `compare` and `also` are not supported when `unit` is supplied.

#' @param compare Name of a second group to subtract (`group − compare`).

#'   Positive differences use the primary colour; negative use the secondary.

#'   Cannot be combined with `unit`.

#' @param also    Name of a second group to overlay alongside `group`.

#'   Cannot be combined with `unit`.

#' @param show    Logical.  `FALSE` suppresses all edge rendering regardless of

#'   other arguments.  Default `TRUE`.

#'

#' @return The modified `qe_plot` object.

#'

#' @examples

#' \dontrun{

#' # Single group mean network

#' qe_plot(set) |> qe_edges("FirstGame")

#'

#' # Individual unit network

#' qe_plot(set) |> qe_edges(unit = "FirstGame::steven z")

#'

#' # Individual unit + show all group means

#' qe_plot(set) |> qe_group() |> qe_edges(unit = "FirstGame::steven z")

#'

#' # Subtraction

#' qe_plot(set) |> qe_edges("FirstGame", compare = "SecondGame")

#'

#' # Overlay

#' qe_plot(set) |> qe_edges("FirstGame", also = "SecondGame")

#'

#' # No edges (means and/or points only)

#' qe_plot(set) |> qe_group() |> qe_edges(show = FALSE)

#' }

#'

#' @export

qe_edges <- function(p, group = NULL, unit = NULL,

                     compare = NULL, also = NULL, show = TRUE) {

    # TypeScript reads getAttribute('edges') !== 'false', so we must emit the

    # string "false" — a logical FALSE would be omitted and edges would stay on.

  }

  # Validate group-based targets

    }

  }

  # Validate unit ID

  }

}

#' Show or hide unit points

#'

#' @param p    A `qe_plot` object.

#' @param show Logical. Default `TRUE`.

#' @return The modified `qe_plot` object.

#' @export

qe_points <- function(p, show = TRUE) {

}

#' Show or hide trajectory paths

#'

#' Adds a `<qe-trajectories>` layer to the rendered graph.  QEviz only renders

#' supplied trajectory rows; accumulation, dooring, model selection, and

#' inference remain the caller's responsibility.

#'

#' @param p A `qe_plot` object.

#' @param units Optional character vector of unit IDs to show.  Omit to show all

#'   units present in the model's `trajectories` frame.

#' @param smooth Path treatment: `"none"` for observed steps or `"poly"` for

#'   polynomial smoothing.

#' @param max_degree Upper bound on polynomial degree when `smooth = "poly"`.

#'   With `degree_selection = "loocv_2d"` the actual degree is chosen in

#'   `1..max_degree`; with `"fixed"` this degree is always used.

#' @param degree_selection Degree selection when `smooth = "poly"`. `"loocv_2d"`

#'   (default) picks the degree by joint 2D leave-one-out cross-validation;

#'   `"fixed"` always uses `max_degree`. Near-origin points are excluded from the

#'   fit (still drawn), matching `ena.plot.trajectory()`.

#' @param points Logical. Show observed state dots.

#' @param tips Logical. Show the leading current-state marker.

#' @param playhead Optional numeric time value. Rows after this value are hidden.

#' @param line_style `"uniform"` or `"tapered"`.

#' @param stroke_width Uniform stroke width in display pixels.

#' @param stroke_width_range Numeric length-2 vector for tapered paths.

#' @param opacity_range Numeric length-2 vector for tapered paths.

#' @param show Logical. `FALSE` suppresses trajectory rendering.

#'

#' @return The modified `qe_plot` object.

#'

#' @export

qe_trajectories <- function(p, units = NULL, smooth = c("none", "poly"),

                            max_degree = 3L,

                            degree_selection = c("loocv_2d", "fixed"),

                            points = TRUE, tips = TRUE,

                            playhead = NULL,

                            line_style = c("uniform", "tapered"),

                            stroke_width = 2,

                            stroke_width_range = c(1, 6),

                            opacity_range = c(0.3, 1),

                            show = TRUE) {

  }

    }

  }

}

#' Control label visibility

#'

#' @param p      A `qe_plot` object.

#' @param nodes  Label mode for code nodes.  One of `"on"`, `"off"`,

#'   `"click"`, `"auto"`. Default `"on"`.

#' @param means  Label mode for group means. Default `"on"`.

#' @param points Label mode for unit points. Default `"auto"`.

#' @return The modified `qe_plot` object.

#' @export

qe_labels <- function(p, nodes = "on", means = "on", points = "auto") {

}

# ══ Output functions ═══════════════════════════════════════════════════════════

# All three accept a qe_plot object, a raw ena.set, or a plain ModelData list.

#' Return a qeviz plot as an HTML string

#'

#' @param x           A `qe_plot` object, a raw rENA / tma / ona set, or a

#'   `ModelData` list from [qe_model_data()] / [qe_extract()].

#' @param title       `<title>` text. Defaults to the title stored in the

#'   `qe_plot` object when one is supplied.

#' @param graph_opts  Named list of `<qe-graph>` attribute overrides.  When `x`

#'   is a `qe_plot` object the stored opts are used as the base; keys supplied

#'   here take precedence.

#' @param ...         Additional arguments forwarded to [qe_extract()] when `x`

#'   is a raw set.

#' @return A single character string containing a complete HTML document.

#' @examples

#' \dontrun{

#' writeLines(qe_html(set), "plot.html")

#' writeLines(qe_html(qe_plot(set) |> qe_group("FirstGame")), "plot.html")

#' }

#' @export

qe_html <- function(x, title = NULL, graph_opts = list(), ...) {

}

#' Write a self-contained qeviz HTML file

#'

#' @param x          A `qe_plot` object, a raw rENA / tma / ona set, or a

#'   `ModelData` list.

#' @param file       Output file path (should end in `.html`).

#' @param title      `<title>` text (defaults to stored title for `qe_plot` objects).

#' @param graph_opts Named list of `<qe-graph>` attribute overrides.

#' @param open       If `TRUE` (default when interactive), open after writing.

#' @param ...        Additional arguments forwarded to [qe_extract()] when `x`

#'   is a raw set.

#' @return The normalised `file` path, invisibly.

#' @examples

#' \dontrun{

#' qe_export_html(set, "ena_plot.html")

#' qe_export_html(qe_plot(set) |> qe_group("FirstGame"), "fg.html")

#' }

#' @export

qe_export_html <- function(x, file, title = NULL, graph_opts = list(),

                           open = interactive(), ...) {

}

#' Return a qeviz plot as an embeddable HTML fragment

#'

#' Returns a `<div>` with the inlined bundle and a `<qe-visual>` / `<qe-graph>`

#' pair — no `<html>` wrapper, suitable for R Markdown / Quarto via

#' `htmltools::HTML()`.

#'

#' @param x           A `qe_plot` object, a raw rENA / tma / ona set, or a

#'   `ModelData` list.

#' @param height      CSS height of the containing `<div>`. Default `"480px"`.

#' @param graph_opts  Named list of `<qe-graph>` attribute overrides.

#' @param ...         Additional arguments forwarded to [qe_extract()] when `x`

#'   is a raw set.

#' @return A character string of class `"html"`.

#' @examples

#' \dontrun{

#' htmltools::HTML(qe_fragment(set))

#' htmltools::HTML(qe_fragment(qe_plot(set) |> qe_group("FirstGame")))

#' }

#' @export

qe_fragment <- function(x, height = "480px", graph_opts = list(), ...) {

  )

}

# ── Internal: open a file in RStudio viewer or browser ────────────────────────

.open_viewer <- function(path) {

  } else {

  }

}

# frames.R — low-level helpers for building QEFrame structures

#

# A QEFrame is the wire format qeviz expects for every data table:

#   { data: [ {col: val, ...}, ... ], types: { col: "character"|"numeric"|"integer"|"logical" } }

# ── Internal helpers ───────────────────────────────────────────────────────────

#' Convert a data.frame to a QEFrame list

#'

#' Serialises a data.frame into the `{ data, types }` structure expected by

#' qeviz's `ModelData` interface.  Factors are coerced to character.

#'

#' @param df A `data.frame` (or object coercible via `as.data.frame()`).

#' @return A named list with elements `data` (list of row lists) and `types`

#'   (named character vector of column types).

#' @keywords internal

qe_frame <- function(df) {

  })

}

#' Return the names of the first two numeric columns

#'

#' Used to locate the rotated dimension axes (e.g. `SVD1`, `SVD2`) in a

#' nodes or points data.frame without hardcoding column names.

#'

#' @param df A `data.frame`.

#' @return Character vector of length 2.

#' @keywords internal

find_dims <- function(df) {

}

#' Compute per-group means and 95% CI bounds

#'

#' For each group, computes the mean x/y position and a rectangular 95%

#' confidence interval using `t(df = n-1, 0.975) * SE` on each axis

#' independently.  This matches the CI convention used by rENA / Web ENA.

#'

#' @param pts   A `data.frame` with at least the columns named by `x_col`,

#'   `y_col`, and `group_col`.

#' @param x_col Name of the x-coordinate column.

#' @param y_col Name of the y-coordinate column.

#' @param group_col Name of the grouping column.

#' @return A `data.frame` with columns `group`, `x`, `y`, `x.low`, `x.high`,

#'   `y.low`, `y.high`.

#' @keywords internal

group_summary <- function(pts, x_col, y_col, group_col) {

    )

  }))

}

# model.R — build ModelData structures from data.frames or rENA/tma set objects

#' Build a qeviz ModelData list from data.frames

#'

#' Assembles the `ModelData` structure consumed by `<qe-visual>` from

#' pre-prepared data.frames.  All data.frames are converted to QEFrames

#' (see [qe_frame()]).

#'

#' @param nodes     `data.frame` of code-node positions.  Must contain columns

#'   `node_id_col`, `x_col`, `y_col`.

#' @param edges     `data.frame` of edge weights.  Must contain `id_col` plus

#'   one column per edge pair (e.g. `Data.Collaboration`).

#' @param points    `data.frame` of unit positions.  Must contain `id_col`,

#'   `group_col`, `x_col`, `y_col`.

#' @param trajectories Optional ordered observations for one or more units.

#'   Must contain `id_col`, `x_col`, `y_col`, and ideally `time`, `RowID`, or

#'   `ActivityNumber` for playhead ordering.

#' @param groups    `data.frame` of group summary statistics as returned by

#'   [group_summary()], or `NULL` to compute automatically from `points`.

#' @param directed  Logical.  `TRUE` for ONA (ordered/directed) models.

#' @param id_col      Name of the unit-ID column in `edges` and `points`.

#' @param node_id_col Name of the code-ID column in `nodes`.

#' @param x_col       Name of the x-coordinate column.

#' @param y_col       Name of the y-coordinate column.

#' @param group_col   Name of the group column in `points`.

#'

#' @return A named list suitable for serialisation with [jsonlite::toJSON()]

#'   and passing to `qe_export_html()` or `qe_plot()`.

#'

#' @examples

#' \dontrun{

#' model <- qe_model_data(nodes_df, edges_df, points_df, directed = FALSE)

#' qe_plot(model)

#' }

#'

#' @export

qe_model_data <- function(

    nodes,

    edges,

    points      = NULL,

    trajectories = NULL,

    groups      = NULL,

    directed    = FALSE,

    id_col      = "ENA_UNIT",

    node_id_col = "code",

    x_col       = "x",

    y_col       = "y",

    group_col   = "Condition"

) {

  }

  )

}

#' Extract a qeviz ModelData list from an rENA / tma model object

#'

#' Reads nodes, points, edges, and group membership from a set object

#' produced by `rENA::model()` (tma pipeline) and returns a `ModelData`

#' list ready for rendering.

#'

#' The set object must expose:

#' * `set$rotation$nodes`  — code positions data.frame with a `code` column

#' * `set$points`          — unit positions data.frame with `ENA_UNIT`,

#'   `Condition`, and rotated-dimension columns

#' * `set$line.weights`    — edge-weight columns (one per code pair)

#' * `set$meta.data`       — unit metadata including `ENA_UNIT`, `Condition`

#'

#' Edge column names are normalised: `" & "` separators are replaced with

#' `"."` so qeviz's edge parser can resolve them (e.g. `"Data & Collab"`

#' becomes `"Data.Collab"`).

#'

#' @param set       A model set object from `rENA::model()` or `ona::model()`.

#' @param directed  Logical, or `NULL` (default).  When `NULL`, directionality

#'   is detected automatically: sets with class `"ena.ordered.set"` (ONA) are

#'   treated as directed; standard ENA sets are treated as undirected.  Pass

#'   `TRUE` or `FALSE` explicitly only if you need to override the default.

#' @param id_col      Unit-ID column name in the set's meta/points frames.

#' @param node_id_col Code-ID column name in the nodes frame.

#' @param group_col   Group column name.

#'

#' @return A `ModelData` list (see [qe_model_data()]).

#'

#' @examples

#' \dontrun{

#' library(tma); library(rENA)

#' data(RS.data)

#' result <- tma::accumulate(tensor, codes = codes,

#'                           context_model = ctx, ordered = FALSE)

#' ena_set   <- rENA::model(result)

#' ena_model <- qe_extract(ena_set, directed = FALSE)

#' qe_plot(ena_model)

#' }

#'

#' @export

qe_extract <- function(

    set,

    directed    = NULL,

    id_col      = "ENA_UNIT",

    node_id_col = "code",

    group_col   = "Condition"

) {

  # ── Directionality ─────────────────────────────────────────────────────────

  # Ordered (ONA) sets carry class "ena.ordered.set", which means the

  # line.weights matrix is asymmetric (A→B and B→A are distinct columns).

  # Auto-detect from the set class so callers don't have to specify it.

  # An explicit directed = TRUE/FALSE overrides the auto-detection.

  }

  # ── Nodes ──────────────────────────────────────────────────────────────────

  # ── Points ─────────────────────────────────────────────────────────────────

  # ── Edges ──────────────────────────────────────────────────────────────────

  # Normalise separator: rENA uses " & ", qeviz expects "."

  # ── Groups (means + 95% CI) ────────────────────────────────────────────────

  )

}

#' List the group names in a model

#'

#' Returns the unique group names present in a `ModelData` list or `qe_plot`

#' object.  Useful when a dataset has more than two groups and you want to

#' iterate over them or validate a group name before passing it to

#' [qe_group()].

#'

#' @param x A `qe_plot` object or a `ModelData` list from [qe_model_data()] /

#'   [qe_extract()].

#'

#' @return A character vector of group names, in the order they appear in the

#'   model's group summary table.

#'

#' @examples

#' \dontrun{

#' model <- qe_extract(set)

#' qe_groups(model)

#' #> [1] "FirstGame"  "SecondGame"

#'

#' # Useful for iterating over all groups:

#' lapply(qe_groups(model), function(g) {

#'   qe_plot(model) |> qe_group(g) |> qe_export_html(paste0(g, ".html"))

#' })

#' }

#'

#' @export

qe_groups <- function(x) {

}

#' List the unit IDs in a model

#'

#' Returns the unit IDs present in a `ModelData` list or `qe_plot` object.

#' Unit IDs are the values in the model's `id_col` column (default

#' `"ENA_UNIT"`), typically in compound form `"Group::Name"` as produced by

#' rENA / tma.  Pass any of these strings to [qe_edges()] as the `unit`

#' argument to plot an individual unit's edge network.

#'

#' @param x A `qe_plot` object or a `ModelData` list from [qe_model_data()] /

#'   [qe_extract()].

#'

#' @return A character vector of unit IDs, in the order they appear in the

#'   model's points table.  Returns `character(0)` if the model has no points

#'   frame.

#'

#' @examples

#' \dontrun{

#' model <- qe_extract(set)

#' qe_units(model)

#' #> [1] "FirstGame::steven z"    "FirstGame::akash v"

#' #> [3] "SecondGame::steven z"   ...

#'

#' # Plot one unit's edge network alongside both group means:

#' qe_plot(set) |>

#'   qe_group() |>

#'   qe_points() |>

#'   qe_edges(unit = "FirstGame::steven z")

#' }

#'

#' @export

qe_units <- function(x) {

}

#' List the trajectory unit IDs in a model

#'

#' Returns the unit IDs present in the model's `trajectories` frame.  If no

#' separate trajectories frame is present, falls back to [qe_units()] because

#' qeviz can use point rows as trajectory states.

#'

#' @param x A `qe_plot` object or a `ModelData` list from [qe_model_data()] /

#'   [qe_extract()].

#'

#' @return A character vector of trajectory unit IDs.

#'

#' @export

qe_trajectory_units <- function(x) {

}