oakscriptjs 0.9.6 → 0.10.0

package/src/drawing/output.ts

@@ -0,0 +1,214 @@
+/**
+ * Renderable form of the live drawing objects (labels, lines, boxes, linefills, polylines, tables): the
+ * `IndicatorResult` fields `labels`, `lines`, `boxes`, `linefills`, `polylines` and `tables`.
+ *
+ * Conversion rules:
+ * - x coordinates become bar times: a `bar_index` x is the time of that bar, or of a future bar after the last bar
+ *   (see {@link barTime}); a `bar_time` x (UNIX ms, as PineScript) is converted to the unit of the bar times
+ * - an object with an `na` coordinate (or a bar index before the first bar) is not drawn, as in PineScript
+ * - a property the script did not set is omitted (the renderer uses the PineScript default); a colour set to `na`
+ *   is 'transparent'
+ * - `force_overlay` is kept only when true
+ *
+ * @module drawing/output
+ */
+
+import { all } from './registry.js';
+import { barInterval, barTime } from './bar-time.js';
+import type { Box, ChartPoint, Label, Line, Polyline, Table, color } from '../types/index.js';
+import type {
+  BoxData,
+  LabelData,
+  LineDrawingData,
+  LinefillData,
+  PolylineData,
+  TableCellData,
+  TableData,
+} from '../types/metadata.js';
+
+/** Drawing fields of an IndicatorResult; a kind without live objects is undefined. */
+export interface DrawingOutputs {
+  labels?: LabelData[];
+  lines?: LineDrawingData[];
+  boxes?: BoxData[];
+  linefills?: LinefillData[];
+  polylines?: PolylineData[];
+  tables?: TableData[];
+}
+
+/** A colour of the result: 'transparent' for na (null), '#rrggbb' for a numeric colour. */
+function colorOut(c: color | null | undefined): string | undefined {
+  if (c === undefined) return undefined;
+  if (c === null || (typeof c === 'number' && Number.isNaN(c))) return 'transparent';
+  return typeof c === 'number' ? `#${(c & 0xffffff).toString(16).padStart(6, '0')}` : c;
+}
+
+/** The object without its undefined fields (so that the result has only the properties that were set). */
+function compact<T extends object>(obj: T): T {
+  for (const k of Object.keys(obj) as Array<keyof T>) if (obj[k] === undefined) delete obj[k];
+  return obj;
+}
+
+const overlay = (flag: boolean | undefined): true | undefined => (flag ? true : undefined);
+
+/**
+ * Converts the live drawing objects of the registry. `bars` are the chart bars (their `time` in `timeUnit`, 's' by
+ * default as lightweight-charts); they give the time of a bar index.
+ */
+export function drawingOutputs(bars: ReadonlyArray<{ time: number }>, timeUnit: 's' | 'ms' = 's'): DrawingOutputs {
+  const interval = barInterval(bars);
+  const msUnit = timeUnit === 'ms' ? 1 : 1000;
+  const xTime = (x: number, xloc: 'bar_index' | 'bar_time'): number =>
+    xloc === 'bar_time' ? x / msUnit : barTime(bars, x, interval);
+  const ok = (...values: number[]): boolean => values.every(Number.isFinite);
+
+  const lineData = (l: Line): LineDrawingData | undefined => {
+    const time1 = xTime(l.x1, l.xloc);
+    const time2 = xTime(l.x2, l.xloc);
+    if (!ok(time1, time2, l.y1, l.y2)) return undefined;
+    return compact({
+      time1,
+      price1: l.y1,
+      time2,
+      price2: l.y2,
+      color: colorOut(l.color),
+      width: l.width,
+      style: l.style,
+      extend: l.extend,
+      forceOverlay: overlay(l.force_overlay),
+    });
+  };
+
+  const labelData = (l: Label): LabelData | undefined => {
+    const time = xTime(l.x, l.xloc);
+    // abovebar / belowbar labels are placed at the bar, not at y
+    if (!ok(time) || (l.yloc === 'price' && !ok(l.y))) return undefined;
+    return compact({
+      time,
+      price: l.y,
+      text: l.text ?? '',
+      color: colorOut(l.color),
+      textColor: colorOut(l.textcolor),
+      style: l.style,
+      size: l.size as LabelData['size'],
+      yloc: l.yloc,
+      textAlign: l.textalign,
+      tooltip: l.tooltip,
+      fontFamily: l.text_font_family,
+      textFormatting: l.text_formatting,
+      forceOverlay: overlay(l.force_overlay),
+    });
+  };
+
+  const boxData = (b: Box): BoxData | undefined => {
+    const time1 = xTime(b.left, b.xloc);
+    const time2 = xTime(b.right, b.xloc);
+    if (!ok(time1, time2, b.top, b.bottom)) return undefined;
+    return compact({
+      time1,
+      price1: b.top,
+      time2,
+      price2: b.bottom,
+      bgColor: colorOut(b.bgcolor),
+      borderColor: colorOut(b.border_color),
+      borderWidth: b.border_width,
+      borderStyle: b.border_style,
+      text: b.text,
+      textColor: colorOut(b.text_color),
+      textSize: b.text_size as BoxData['textSize'],
+      textHAlign: b.text_halign,
+      textVAlign: b.text_valign,
+      textWrap: b.text_wrap,
+      fontFamily: b.text_font_family,
+      textFormatting: b.text_formatting,
+      extend: b.extend,
+      forceOverlay: overlay(b.force_overlay),
+    });
+  };
+
+  const polylineData = (p: Polyline): PolylineData | undefined => {
+    const points: PolylineData['points'] = [];
+    for (const point of p.points as ChartPoint[]) {
+      const x = p.xloc === 'bar_time' ? point.time : point.index;
+      const time = x === null ? NaN : xTime(x, p.xloc);
+      if (ok(time, point.price)) points.push({ time, price: point.price });
+    }
+    if (points.length === 0) return undefined;
+    return compact({
+      points,
+      curved: p.curved,
+      closed: p.closed,
+      lineColor: colorOut(p.line_color),
+      fillColor: p.fill_color === null ? undefined : colorOut(p.fill_color),
+      lineStyle: p.line_style,
+      lineWidth: p.line_width,
+      forceOverlay: overlay(p.force_overlay),
+    });
+  };
+
+  const tableData = (t: Table): TableData => {
+    const cells: TableCellData[] = [];
+    for (const [key, c] of t.cells ?? []) {
+      const [column, row] = key.split(',').map(Number) as [number, number];
+      cells.push(
+        compact({
+          row,
+          column,
+          text: c.text ?? '',
+          bgColor: colorOut(c.bgcolor),
+          textColor: colorOut(c.text_color),
+          textSize: c.text_size as TableCellData['textSize'],
+          width: c.width,
+          height: c.height,
+          textHAlign: c.text_halign,
+          textVAlign: c.text_valign,
+          tooltip: c.tooltip,
+          fontFamily: c.text_font_family,
+          textFormatting: c.text_formatting,
+        })
+      );
+    }
+    cells.sort((a, b) => a.row - b.row || a.column - b.column);
+    const merges = (t.merges ?? []).map((m) => ({
+      startColumn: m.start_column,
+      startRow: m.start_row,
+      endColumn: m.end_column,
+      endRow: m.end_row,
+    }));
+    return compact({
+      position: t.position,
+      columns: t.columns,
+      rows: t.rows,
+      cells,
+      merges: merges.length ? merges : undefined,
+      bgColor: colorOut(t.bgcolor),
+      frameColor: colorOut(t.frame_color),
+      frameWidth: t.frame_width,
+      borderColor: colorOut(t.border_color),
+      borderWidth: t.border_width,
+      forceOverlay: overlay(t.force_overlay),
+    });
+  };
+
+  const convert = <T, R>(items: T[], fn: (item: T) => R | undefined): R[] | undefined => {
+    const out: R[] = [];
+    for (const item of items) {
+      const r = fn(item);
+      if (r !== undefined) out.push(r);
+    }
+    return out.length ? out : undefined;
+  };
+
+  return {
+    labels: convert(all('label'), labelData),
+    lines: convert(all('line'), lineData),
+    boxes: convert(all('box'), boxData),
+    linefills: convert(all('linefill'), (f): LinefillData | undefined => {
+      const line1 = lineData(f.line1);
+      const line2 = lineData(f.line2);
+      return line1 && line2 ? compact({ line1, line2, color: colorOut(f.color) }) : undefined;
+    }),
+    polylines: convert(all('polyline'), polylineData),
+    tables: convert(all('table'), tableData),
+  };
+}

package/src/drawing/registry.ts

@@ -1,5 +1,5 @@
 /**
- * Registry of the live drawing objects (lines, labels, boxes, polylines, linefills), as PineScript
+ * Registry of the live drawing objects (lines, labels, boxes, polylines, linefills, tables), as PineScript
  * keeps them. PineScript rules:
  *
  * - `line.all`, `label.all`, ... list the live objects in creation order (a copy of the list)
@@ -15,9 +15,9 @@
  * @module drawing/registry
  */
 
-import type { Box, Label, Line, Linefill, Polyline } from '../types/index.js';
+import type { Box, Label, Line, Linefill, Polyline, Table } from '../types/index.js';
 
-export type DrawingKind = 'line' | 'label' | 'box' | 'polyline' | 'linefill';
+export type DrawingKind = 'line' | 'label' | 'box' | 'polyline' | 'linefill' | 'table';
 
 interface DrawingTypes {
   line: Line;
@@ -25,6 +25,7 @@ interface DrawingTypes {
   box: Box;
   polyline: Polyline;
   linefill: Linefill;
+  table: Table;
 }
 
 /** Default `max_lines_count`, `max_labels_count`, `max_boxes_count`, `max_polylines_count`. */
@@ -32,9 +33,16 @@ export const DEFAULT_MAX_COUNT = 50;
 /** Objects above the maximum that PineScript keeps before it deletes the oldest ones. */
 const SLACK = 5;
 
-export type DrawingLimits = Partial<Record<Exclude<DrawingKind, 'linefill'>, number>>;
+export type DrawingLimits = Partial<Record<Exclude<DrawingKind, 'linefill' | 'table'>, number>>;
 
-const live: { [K in DrawingKind]: Array<DrawingTypes[K]> } = { line: [], label: [], box: [], polyline: [], linefill: [] };
+const live: { [K in DrawingKind]: Array<DrawingTypes[K]> } = {
+  line: [],
+  label: [],
+  box: [],
+  polyline: [],
+  linefill: [],
+  table: [],
+};
 let limits: Required<DrawingLimits> = {
   line: DEFAULT_MAX_COUNT,
   label: DEFAULT_MAX_COUNT,
@@ -50,6 +58,7 @@ const COORDINATES: { [K in DrawingKind]: Array<keyof DrawingTypes[K]> } = {
   box: ['left', 'top', 'right', 'bottom'],
   polyline: [],
   linefill: [],
+  table: [],
 };
 
 function markDeleted<K extends DrawingKind>(kind: K, obj: DrawingTypes[K], explicit: boolean): void {
@@ -64,7 +73,8 @@ function markDeleted<K extends DrawingKind>(kind: K, obj: DrawingTypes[K], expli
 export function register<K extends DrawingKind>(kind: K, obj: DrawingTypes[K]): DrawingTypes[K] {
   const list = live[kind];
   list.push(obj);
-  const max = limits[kind === 'linefill' ? 'line' : (kind as Exclude<DrawingKind, 'linefill'>)];
+  if (kind === 'table') return obj; // tables have no maximum count
+  const max = limits[kind === 'linefill' ? 'line' : (kind as keyof DrawingLimits)];
   if (list.length > max + SLACK) {
     for (const old of list.splice(0, list.length - max)) markDeleted(kind, old, false);
   }

package/src/index.ts

@@ -32,11 +32,16 @@ import * as label from './label/index.js';
 import * as linefill from './linefill/index.js';
 import * as chartPoint from './chartpoint/index.js';
 import * as polyline from './polyline/index.js';
+import * as table from './table/index.js';
 import * as text from './text/index.js';
 import * as compare from './compare/index.js';
 import * as callsite from './callsite/index.js';
 
-export { taCore, math, array, map, str, color, time, timeframe, matrix, line, box, label, linefill, chartPoint, polyline, text, compare, callsite };
+export { taCore, math, array, map, str, color, time, timeframe, matrix, line, box, label, linefill, chartPoint, polyline, table, text, compare, callsite };
+
+// Renderable drawings (IndicatorResult labels, lines, boxes, linefills, polylines, tables) and future bar times
+export { drawingOutputs, type DrawingOutputs } from './drawing/output.js';
+export { barInterval, barTime } from './drawing/bar-time.js';
 
 // Export Series class (self-contained, no context)
 export { Series, BarData } from './runtime/series.js';
@@ -148,6 +153,7 @@ export type {
   HLineConfig,
   FillConfig,
   ArrowConfig,
+  CandleConfig,
 } from './runtime/types.js';
 
 // Strategy types and constants (the script API forwards strategy.* calls to a host engine)
@@ -164,7 +170,7 @@ export type { LightweightSeriesDefinitions } from './runtime/adapters/Lightweigh
 export { SimpleInputAdapter } from './runtime/adapters/SimpleInputAdapter.js';
 
 // Version
-export const VERSION = '0.9.6';
+export const VERSION = '0.10.0';
 
 /**
  * Library information
@@ -182,7 +188,7 @@ export const info = {
   },
   namespaces: {
     core: ['ta', 'math', 'array', 'map', 'str', 'color', 'time', 'timeframe', 'matrix'],
-    drawing: ['line', 'box', 'label', 'linefill', 'chartPoint', 'polyline', 'text'],
+    drawing: ['line', 'box', 'label', 'linefill', 'chartPoint', 'polyline', 'table', 'text'],
     runtime: ['setContext', 'plot', 'hline', 'input_*'],
     indicator: ['indicator', 'input', 'plotHelper', 'createPlot']
   }

package/src/polyline/index.ts

@@ -4,8 +4,8 @@
  *
  * @remarks
  * Polylines allow connecting multiple points with line segments, enabling complex chart drawings
- * like trend channels, patterns, and custom shapes. This implementation focuses on basic
- * polylines (straight lines) - curved polylines can be added in a future iteration.
+ * like trend channels, patterns, and custom shapes. The `curved` flag goes to the renderer
+ * (`result.polylines` of the script API), which draws the curve.
  *
  * @version 6
  */
@@ -30,7 +30,7 @@ function generateId(): string {
  * Creates a new polyline connecting all points.
  *
  * @param points - Array of chart.point objects to connect
- * @param curved - If true, use curved line segments (default: false, NOT YET SUPPORTED)
+ * @param curved - If true, use curved line segments (default: false)
  * @param closed - If true, connect first point to last point (default: false)
  * @param xloc - X-coordinate mode: 'bar_index' or 'bar_time' (default: 'bar_index')
  * @param line_color - Color of line segments (default: '#2196F3' - blue)
@@ -41,8 +41,6 @@ function generateId(): string {
  * @returns New Polyline object
  *
  * @remarks
- * - The curved parameter is accepted but currently logs a warning as curved lines
- *   are not yet supported. Straight-line connections are used instead.
  * - For meaningful polylines, provide at least 2 points.
  * - Closed polylines can be filled with a color by setting fill_color.
  *
@@ -82,13 +80,6 @@ export function new_polyline(
   line_width: number = 1,
   force_overlay: boolean = false
 ): Polyline {
-  // Warn about curved polylines not being supported yet
-  if (curved) {
-    console.warn(
-      'polyline.new(): curved polylines are not yet supported. Using straight-line connections.'
-    );
-  }
-
   // Validate line_width is positive
   if (line_width < 1) {
     console.warn('polyline.new(): line_width must be at least 1. Using 1.');

package/src/runtime/types.ts

@@ -138,6 +138,29 @@ export interface ArrowConfig {
     forceOverlay?: boolean;
 }
 
+/**
+ * Configuration of a PineScript `plotcandle()` (kind 'candle') or `plotbar()` (kind 'bar') declaration. The candles
+ * are in `result.plotCandles[id]`, the bars in `result.plotBars[id]`.
+ */
+export interface CandleConfig {
+    /** Unique identifier (key of the data in the result) */
+    id: string;
+    /** 'candle' for plotcandle, 'bar' for plotbar */
+    kind: 'candle' | 'bar';
+    /** Display title */
+    title?: string;
+    /** Static body colour (plotcandle) or bar colour (plotbar) */
+    color?: string;
+    /** Static wick colour (plotcandle only) */
+    wickColor?: string;
+    /** Static border colour (plotcandle only) */
+    borderColor?: string;
+    /** Display mode */
+    display?: 'all' | 'none' | 'data_window' | 'status_line' | 'pane';
+    /** Drawn on the main chart pane even when the script is not an overlay (PineScript `force_overlay`); default false */
+    forceOverlay?: boolean;
+}
+
 /**
  * Configuration for horizontal line outputs in generated indicators
  * Matches PineScript hline() function parameters