oakscriptjs 0.9.6 → 0.10.1

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';
@@ -134,6 +139,7 @@ export {
   input_session,
   input_time,
 } from './runtime/inputs.js';
+export { isInputActive } from './runtime/input-active.js';
 
 export type {
   OakScriptContext,
@@ -142,12 +148,14 @@ export type {
   SeriesHandle,
   SeriesOptions,
   InputConfig,
+  InputCondition,
   InputOptions,
   OhlcvData,
   PlotConfig,
   HLineConfig,
   FillConfig,
   ArrowConfig,
+  CandleConfig,
 } from './runtime/types.js';
 
 // Strategy types and constants (the script API forwards strategy.* calls to a host engine)
@@ -164,7 +172,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.1';
 
 /**
  * Library information
@@ -182,7 +190,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/index.ts

@@ -41,11 +41,14 @@ export type {
   SeriesHandle,
   SeriesOptions,
   InputConfig,
+  InputCondition,
   InputOptions,
   OhlcvData,
     PlotConfig,
 } from './types.js';
 
+export { isInputActive } from './input-active.js';
+
 // Adapter exports
 export { LightweightChartsAdapter } from './adapters/LightweightChartsAdapter.js';
 export type { LightweightSeriesDefinitions } from './adapters/LightweightChartsAdapter.js';

package/src/runtime/input-active.ts

@@ -0,0 +1,50 @@
+/**
+ * @fileoverview PineScript `active` of an input: whether the settings dialog lets the user edit it
+ * @module runtime/input-active
+ */
+
+import type { InputConfig, InputCondition } from './types.js';
+
+/** Current value of an input: the host value, else the default of its config. */
+function inputValue(id: string, inputs: Record<string, unknown>, configs?: readonly InputConfig[]): unknown {
+  const value = inputs[id];
+  if (value !== undefined) return value;
+  return configs?.find((c) => c.id === id)?.defval;
+}
+
+function holds(condition: InputCondition, inputs: Record<string, unknown>, configs?: readonly InputConfig[]): boolean {
+  if (typeof condition === 'string') return inputValue(condition, inputs, configs) === true;
+  if ('not' in condition) return !holds(condition.not, inputs, configs);
+  if ('any' in condition) return condition.any.some((c) => holds(c, inputs, configs));
+  if ('all' in condition) return condition.all.every((c) => holds(c, inputs, configs));
+  const value = inputValue(condition.input, inputs, configs);
+  if (!('eq' in condition) && !('ne' in condition)) return value === true;
+  return (!('eq' in condition) || value === condition.eq) && (!('ne' in condition) || value !== condition.ne);
+}
+
+/**
+ * Whether an input is active (PineScript `active`): an inactive input is shown greyed out in the settings and
+ * cannot be edited. It still gives its value to the script.
+ *
+ * @param config - The input
+ * @param inputs - Current input values by id
+ * @param configs - All the inputs of the indicator: gives the default of an input that has no value in `inputs`
+ * @returns true when `config.active` is not set, is true, or is a condition that holds
+ *
+ * @example
+ * ```typescript
+ * const configs: InputConfig[] = [
+ *   { id: 'showMa1', type: 'bool', defval: true, title: 'MA #1' },
+ *   { id: 'ma1Length', type: 'int', defval: 20, active: 'showMa1' },
+ *   { id: 'bbMult', type: 'float', defval: 2, active: { input: 'maType', eq: 'SMA + Bollinger Bands' } },
+ * ];
+ * isInputActive(configs[1], { showMa1: false }) // false
+ * isInputActive(configs[1], {}, configs) // true: the default of showMa1
+ * ```
+ */
+export function isInputActive(config: InputConfig, inputs: Record<string, unknown> = {}, configs?: readonly InputConfig[]): boolean {
+  const { active } = config;
+  if (active === undefined) return true;
+  if (typeof active === 'boolean') return active;
+  return holds(active, inputs, configs);
+}

package/src/runtime/types.ts

@@ -46,6 +46,22 @@ export interface ChartAdapter {
   createPane?(): number;
 }
 
+/**
+ * Condition on other inputs, as plain data (PineScript `active = <expression>`):
+ * - `'showMa'`: the bool input `showMa` is true
+ * - `{ input: 'maType', eq: 'SMA' }` / `{ input: 'maType', ne: 'None' }`: the value of an input is / is not a value
+ *   (strict equality; without `eq` and `ne`: the input is true)
+ * - `{ not: c }`, `{ any: [c1, c2] }` (or), `{ all: [c1, c2] }` (and)
+ *
+ * Evaluated by `isInputActive()`.
+ */
+export type InputCondition =
+  | string
+  | { input: string; eq?: unknown; ne?: unknown }
+  | { not: InputCondition }
+  | { any: InputCondition[] }
+  | { all: InputCondition[] };
+
 /**
  * Configuration for registering an input
  */
@@ -78,10 +94,17 @@ export interface InputConfig {
   /** Ask for the value when the script is added to a chart (PineScript `confirm`) */
   confirm?: boolean;
   /**
-   * Where the input value is shown (PineScript `display`); not set means the PineScript default: 'all', except
-   * color inputs: 'none'
+   * Where the input value is shown (PineScript `display`); not set means the PineScript default: 'none' for
+   * bool, color and time inputs, 'all' for the others
    */
   display?: 'all' | 'none' | 'data_window' | 'status_line';
+  /**
+   * Whether the input can be edited (PineScript `active`): an inactive input is shown greyed out in the settings.
+   * UI only: an inactive input still gives its value to the script. Not set means always active. A boolean is the
+   * value for the current inputs; an `InputCondition` names the inputs it depends on, so a host can apply it
+   * without running the script (see `isInputActive()`)
+   */
+  active?: boolean | InputCondition;
 }
 
 /**
@@ -138,6 +161,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