Render

Mon, 01 Jan 0001 00:00:00 +0000

@statili/forge ·v0.0.2-beta.0 ·5 exports

# render function

signatures

render(arg1: RenderOptions): (args_0: Fact) => string
render(options: RenderOptions, fact: Fact): string

Turns a {@link Fact} into a sentence.

Rendering is deliberately separate from fact generation: one claim can be spoken at several lengths, in several languages, with the consumer’s own axis names — none of which is possible once prose has been baked into the result. Swap this function out entirely to localise.

Parameters

Name	Type	Description
options	RenderOptions	Axis labels, units, and verbosity.
fact	Fact	The fact to render.

Returns

string

A sentence describing the fact.

Examples

const speak = render({ labels: { x: "week", y: "signups" }, units: { y: "users" } });
speak(fact);
// "Each additional unit of week is associated with an increase of 8.23 users
//  in signups. At week = 0 the fitted value of signups is 3.53 users."

Terse, for an aria-label

render({ labels: { x: "week", y: "signups" }, verbosity: "terse" })(fact);
// "signups: up 8.23 per additional unit of week."

# renderAnnotation function

packages/forge/src/render.ts:463

signatures

renderAnnotation(arg1: RenderOptions): (args_0: Annotation) => string
renderAnnotation(options: RenderOptions, annotation: Annotation): string

Turns an {@link Annotation} into a display label — a legend entry for a curve, a plot-line caption for a marker.

Lives here for the same reason {@link render} does: without it every consumer reimplements the "vertex" → "Vertex" mapping, and they drift apart the moment a new role is added.

Parameters

Name	Type	Description
options	RenderOptions	Axis labels and verbosity. Units are unused today.
annotation	Annotation	The annotation to label.

Returns

string

A short label, safe to put in a legend or on an axis.

Example

renderAnnotation({})(curve);                          // "Linear fit"
renderAnnotation({ labels: { x: "hour" } })(marker);  // "Vertex at hour = 3"

# AxisLabels interface

packages/forge/src/render.ts:9

signature

interface AxisLabels {
  x?: string;
  y?: string;
}

Axis names, so a rendered fact reads in the reader’s domain rather than in algebra. “As advertising spend increases, monthly sales tend to increase” beats “As X increases, Y tends to increase” — especially as chart alt text.

# AxisUnits interface

packages/forge/src/render.ts:15

signature

interface AxisUnits {
  x?: string;
  y?: string;
}

Units appended to quantities, e.g. { y: "£" } or { x: "days" }.

# RenderOptions interface

packages/forge/src/render.ts:20

signature

interface RenderOptions {
  labels?: AxisLabels;
  units?: AxisUnits;
  /**
   * `"terse"` yields a single clause suitable for an `aria-label` or a tooltip.
   * `"full"` yields one to three sentences for a `<desc>` or a body paragraph.
   * @default "full"
   */
  verbosity?: "terse" | "full";
}

Types

Mon, 01 Jan 0001 00:00:00 +0000

@statili/forge ·v0.0.2-beta.0 ·17 exports

# ClaimMap interface

packages/forge/src/types.ts:89

signature

interface ClaimMap {
  // ── Shape of the relationship ─────────────────────────────────────────────

  /** Direction and rate of a straight-line relationship. */
  "trend.linear": {
    direction: "rising" | "falling" | "flat";
    /** Change in Y per one-unit increase in X. */
    slope: number;
    intercept: number;
  };

  /** Shape of a fitted polynomial curve. */
  "trend.polynomial": {
    degree: number;
    leadingCoefficient: number;
    shape: "line" | "parabola-up" | "parabola-down" | "cubic" | "higher-order";
    /** X position of the extremum. Quadratics only; `null` otherwise. */
    vertexX: number | null;
    equation: string;
  };

  /** Growth regime of a fitted power law, y = a·x^b. */
  "trend.power": {
    /** The exponent b. */
    exponent: number;
    /** The scale coefficient a — the predicted Y at x = 1. */
    scale: number;
    regime: "superlinear" | "proportional" | "sublinear" | "flat" | "inverse";
    /** Y is multiplied by this when X doubles: 2^b. */
    doublingFactor: number;
    equation: string;
  };

  /** Constant proportional growth or decay, y = a·e^(bx). */
  "trend.exponential": {
    /** The growth rate b. */
    rate: number;
    /** The initial value a — the predicted Y at x = 0. */
    initial: number;
    direction: "growth" | "decay" | "flat";
    /** Y is multiplied by this for each unit step in X: e^b. */
    perStepFactor:
// …truncated

Type shortened for readability — see the source for the full definition.

Forge on statili

Render

# render function

Parameters

Returns

Examples

# renderAnnotation function

Parameters

Returns

Example

# AxisLabels interface

# AxisUnits interface

# RenderOptions interface

Types

# ClaimMap interface