@rippling/rippling-sdk 0.2.0-alpha.105 → 0.2.0-alpha.106

package/src/lib/charts/builders.ts

@@ -0,0 +1,90 @@
+import { ChartRuleError } from './errors';
+import {
+  type ComparisonKind,
+  type ComparisonNode,
+  type IfElseNode,
+  type LiteralNode,
+  type RefNode,
+  type RuleNode,
+  type RulePlaceholder,
+  type Scalar,
+} from './types';
+
+/** A rule node, a nested rule (`{$rule}` placeholder), or a bare scalar. */
+export type Operand = RuleNode | RulePlaceholder | Scalar;
+
+function isRuleNode(operand: Operand): operand is RuleNode {
+  return typeof operand === 'object' && operand !== null && 'kind' in operand;
+}
+
+/** True when a value is a `{$rule}` placeholder — the marker the builders emit. */
+export function isRulePlaceholder(value: unknown): value is RulePlaceholder {
+  return typeof value === 'object' && value !== null && '$rule' in value;
+}
+
+/** Wrap a bare scalar as a literal node. */
+export function literal(value: Scalar): LiteralNode {
+  return { kind: 'literal', value };
+}
+
+function toNode(operand: Operand): RuleNode {
+  if (isRulePlaceholder(operand)) {
+    return operand.$rule; // a nested rule — unwrap it, never wrap it as a literal
+  }
+  return isRuleNode(operand) ? operand : literal(operand);
+}
+
+/**
+ * `value` — this data point's plotted numeric value: a bar's height, a point's
+ * y, a slice's amount. It is what a colour rule compares against a constant.
+ */
+export const value: RefNode = Object.freeze({ kind: 'value' });
+
+/* Comparisons — return a condition. */
+function comparison(kind: ComparisonKind): (left: Operand, right: Operand) => ComparisonNode {
+  return (left, right) => ({ kind, left: toNode(left), right: toNode(right) });
+}
+export const equals = comparison('equals');
+export const isNot = comparison('isNot');
+export const lessThan = comparison('lessThan');
+export const greaterThan = comparison('greaterThan');
+export const lessOrEqual = comparison('lessOrEqual');
+export const greaterOrEqual = comparison('greaterOrEqual');
+
+/**
+ * A conditional value: pick `ifTrue` when the condition holds, else `ifFalse`.
+ * Channel-agnostic — wrap it in a channel builder (`color`) to target something.
+ *
+ *   when(lessThan(value, 100), '#E24B4A', '#378ADD')
+ *   // → '#E24B4A' when this point's value is under 100, '#378ADD' otherwise
+ *
+ * `ifFalse` is optional and defaults to `null` — for a colour, that means no
+ * override (the chart's default is kept). Returns a plain node, not a placeholder.
+ */
+export function when(condition: RuleNode, ifTrue: Operand, ifFalse?: Operand): IfElseNode {
+  if (ifTrue === undefined) {
+    throw new ChartRuleError('when(condition, ifTrue, ifFalse?) needs a value for the true case');
+  }
+  return {
+    kind: 'ifElse',
+    cond: condition,
+    then: toNode(ifTrue),
+    else: toNode(ifFalse ?? null),
+  };
+}
+
+/**
+ * Target the colour channel — the v1 channel. Wrap a conditional value so the
+ * renderer knows it resolves to a colour, and the panel knows what it edits.
+ *
+ *   color(when(lessThan(value, 100), '#E24B4A', '#378ADD'))
+ *   // → red when this point's value is under 100, blue otherwise
+ *
+ * Takes a conditional value — a `when(...)` (`IfElseNode`) or an already-wrapped
+ * rule — not a bare `value` or comparison: those resolve to a number or a
+ * boolean, which is not a colour. `evaluate` enforces the same at runtime for a
+ * deserialized rule. Returns a `{$rule}` placeholder tagged `channel: 'color'`.
+ */
+export function color(rule: IfElseNode | RulePlaceholder): RulePlaceholder {
+  return { $rule: isRulePlaceholder(rule) ? rule.$rule : rule, channel: 'color' };
+}

package/src/lib/charts/describe.ts

@@ -0,0 +1,67 @@
+import { isRulePlaceholder } from './builders';
+import { RuleDepthError, UnknownNodeError } from './errors';
+import { assertRuleNode, literalValue } from './guards';
+import { MAX_RULE_DEPTH, type Control, type Rule, type RuleNode } from './types';
+
+/**
+ * Turn a rule into the shape the settings panel renders: a label plus its
+ * editable parts. Accepts a `{$rule}` placeholder or a bare tree. Walks the same
+ * tree `evaluate` runs — and validates each node the same way — so a malformed or
+ * unknown node throws a `ChartRuleError` here too, never a native `TypeError`.
+ * The unwrap is gated on `isRulePlaceholder` (not a raw `'$rule' in rule`) so a
+ * `null`/primitive rule reaches `assertRuleNode` instead of throwing on `in`.
+ * A tree nested past `MAX_RULE_DEPTH` throws `RuleDepthError`.
+ */
+export function describe(rule: Rule): Control {
+  if (isRulePlaceholder(rule)) {
+    return visit(rule.$rule, 0);
+  }
+  return visit(rule, 0);
+}
+
+function visit(node: RuleNode, depth: number): Control {
+  if (depth > MAX_RULE_DEPTH) {
+    throw new RuleDepthError(MAX_RULE_DEPTH);
+  }
+  assertRuleNode(node);
+  const next = depth + 1;
+  switch (node.kind) {
+    case 'value':
+      return { role: 'ref', label: "this row's value" };
+    case 'literal': {
+      const scalar = literalValue(node);
+      return { role: 'literal', label: String(scalar), value: scalar };
+    }
+
+    case 'equals':
+      return comparison('is', node.left, node.right, next);
+    case 'isNot':
+      return comparison('is not', node.left, node.right, next);
+    case 'lessThan':
+      return comparison('is under', node.left, node.right, next);
+    case 'greaterThan':
+      return comparison('is over', node.left, node.right, next);
+    case 'lessOrEqual':
+      return comparison('is at most', node.left, node.right, next);
+    case 'greaterOrEqual':
+      return comparison('is at least', node.left, node.right, next);
+
+    case 'ifElse':
+      return {
+        role: 'rule',
+        label: 'when',
+        parts: [visit(node.cond, next), visit(node.then, next), visit(node.else, next)],
+      };
+
+    default:
+      return unreachable(node);
+  }
+}
+
+function comparison(label: string, left: RuleNode, right: RuleNode, depth: number): Control {
+  return { role: 'comparison', label, parts: [visit(left, depth), visit(right, depth)] };
+}
+
+function unreachable(node: never): never {
+  throw new UnknownNodeError((node as { kind?: string }).kind);
+}

package/src/lib/charts/errors.ts

@@ -0,0 +1,48 @@
+/** Base class for every error the chart-rule evaluator can throw. */
+export class ChartRuleError extends Error {}
+
+/**
+ * A node whose `kind` is not in the vocabulary. The caller catches this and
+ * shows the setting as "configured in code", read-only.
+ */
+export class UnknownNodeError extends ChartRuleError {
+  constructor(public readonly kind?: string) {
+    super(`Unknown chart-rule node: ${kind ?? '(missing kind)'}`);
+    this.name = 'UnknownNodeError';
+  }
+}
+
+/** A node evaluated to the wrong type of value (e.g. comparing non-numbers). */
+export class RuleTypeError extends ChartRuleError {
+  constructor(message: string) {
+    super(message);
+    this.name = 'RuleTypeError';
+  }
+}
+
+/**
+ * A structurally invalid node in a deserialized tree: not an object, no string
+ * `kind`, or a `literal` without a scalar `value`. Distinct from
+ * `UnknownNodeError` (a well-formed node whose `kind` is simply not in the
+ * vocabulary — the intentional escape hatch). Like the others it is a
+ * `ChartRuleError`, so a caller reading an untrusted rule catches it instead of
+ * a native `TypeError` (or, worse, an `undefined` slipping through silently).
+ */
+export class MalformedRuleError extends ChartRuleError {
+  constructor(message: string) {
+    super(message);
+    this.name = 'MalformedRuleError';
+  }
+}
+
+/**
+ * A rule nested deeper than the evaluator will walk. Guards against a
+ * stack-overflowing tree from untrusted, deserialized input; like the others it
+ * is a `ChartRuleError`, so the caller's escape hatch catches it.
+ */
+export class RuleDepthError extends ChartRuleError {
+  constructor(maxDepth: number) {
+    super(`chart rule nested deeper than ${maxDepth} levels`);
+    this.name = 'RuleDepthError';
+  }
+}

package/src/lib/charts/evaluate.ts

@@ -0,0 +1,114 @@
+import { isRulePlaceholder } from './builders';
+import { MalformedRuleError, RuleDepthError, RuleTypeError, UnknownNodeError } from './errors';
+import { assertRuleNode, literalValue } from './guards';
+import {
+  MAX_RULE_DEPTH,
+  type Rule,
+  type RuleChannel,
+  type RuleContext,
+  type RuleNode,
+  type RuleValue,
+} from './types';
+
+/**
+ * Resolve a rule to a value against `ctx`. Accepts a `{$rule}` placeholder or a
+ * bare tree. A malformed or unknown node throws a `ChartRuleError` (never a
+ * native `TypeError`), so a caller reading an untrusted, deserialized rule can
+ * catch every failure with one type. When the rule is a colour placeholder, the
+ * result is checked to be a colour (`string | null`) — a rule that resolves to a
+ * number or boolean is a `RuleTypeError`, not something the renderer paints.
+ *
+ * Pure: the only inputs are the node and the context. No clock, no randomness,
+ * no I/O — which is what makes it safe to run on an untrusted, user-edited tree
+ * and identical across the renderer, the panel readout, and a test. A tree
+ * nested past `MAX_RULE_DEPTH` throws `RuleDepthError` rather than overflowing.
+ */
+export function evaluate(rule: Rule, ctx: RuleContext): RuleValue {
+  if (isRulePlaceholder(rule)) {
+    return coerceForChannel(rule.channel, visit(rule.$rule, ctx, 0));
+  }
+  return visit(rule, ctx, 0);
+}
+
+function visit(node: RuleNode, ctx: RuleContext, depth: number): RuleValue {
+  if (depth > MAX_RULE_DEPTH) {
+    throw new RuleDepthError(MAX_RULE_DEPTH);
+  }
+  assertRuleNode(node);
+  const next = depth + 1;
+  switch (node.kind) {
+    case 'value':
+      return ctx.value;
+    case 'literal':
+      return literalValue(node);
+
+    case 'equals':
+      return visit(node.left, ctx, next) === visit(node.right, ctx, next);
+    case 'isNot':
+      return visit(node.left, ctx, next) !== visit(node.right, ctx, next);
+    case 'lessThan':
+      return num(visit(node.left, ctx, next)) < num(visit(node.right, ctx, next));
+    case 'greaterThan':
+      return num(visit(node.left, ctx, next)) > num(visit(node.right, ctx, next));
+    case 'lessOrEqual':
+      return num(visit(node.left, ctx, next)) <= num(visit(node.right, ctx, next));
+    case 'greaterOrEqual':
+      return num(visit(node.left, ctx, next)) >= num(visit(node.right, ctx, next));
+
+    case 'ifElse':
+      return bool(visit(node.cond, ctx, next)) ? visit(node.then, ctx, next) : visit(node.else, ctx, next);
+
+    default:
+      return unreachable(node);
+  }
+}
+
+/* -------------------------------------------------------------------------- */
+/* Coercions — narrow a RuleValue, or throw a typed error.                      */
+/* -------------------------------------------------------------------------- */
+
+function num(value: RuleValue): number {
+  if (typeof value === 'number') {
+    return value;
+  }
+  throw new RuleTypeError(`expected a number, got ${typeName(value)}`);
+}
+
+function bool(value: RuleValue): boolean {
+  if (typeof value === 'boolean') {
+    return value;
+  }
+  throw new RuleTypeError(`expected a boolean, got ${typeName(value)}`);
+}
+
+/** A colour channel must resolve to a colour string, or null for "no override". */
+function asColor(value: RuleValue): RuleValue {
+  if (value === null || typeof value === 'string') {
+    return value;
+  }
+  throw new RuleTypeError(`a colour rule must resolve to a colour string or null, got ${typeName(value)}`);
+}
+
+/**
+ * Coerce a resolved value to what its channel can use. A colour rule must
+ * resolve to a colour; a future channel would add its own case here. A
+ * placeholder whose `channel` is missing or unrecognised (only possible from
+ * untrusted, deserialized input — the type and schema both pin it to `'color'`)
+ * is malformed rather than silently unchecked.
+ */
+function coerceForChannel(channel: RuleChannel, value: RuleValue): RuleValue {
+  switch (channel) {
+    case 'color':
+      return asColor(value);
+    default:
+      throw new MalformedRuleError(`a rule placeholder has an unsupported channel: ${String(channel)}`);
+  }
+}
+
+function typeName(value: RuleValue): string {
+  return value === null ? 'null' : typeof value;
+}
+
+function unreachable(node: never): never {
+  throw new UnknownNodeError((node as { kind?: string }).kind);
+}

package/src/lib/charts/guards.ts

@@ -0,0 +1,42 @@
+import { MalformedRuleError } from './errors';
+import { type RuleNode, type Scalar } from './types';
+
+/**
+ * Runtime validation for one node of a deserialized, untrusted rule tree, shared
+ * by `evaluate` and `describe`. A rule can arrive from JSON that TypeScript never
+ * checked, so `null`, a non-object, or a node without a string `kind` would throw
+ * a native `TypeError` on the first field read — skipping the `ChartRuleError`
+ * escape hatch a caller relies on. Validate before reading fields.
+ */
+
+const SCALAR_TYPES: ReadonlySet<string> = new Set(['number', 'string', 'boolean']);
+
+/**
+ * Assert `node` is shaped like a rule node — an object carrying a string `kind`.
+ * An unrecognised `kind` is *not* rejected here; that is the caller's `switch`
+ * default (`UnknownNodeError`), the deliberate "configured in code" signal.
+ */
+export function assertRuleNode(node: unknown): asserts node is RuleNode {
+  if (
+    node === null ||
+    typeof node !== 'object' ||
+    Array.isArray(node) ||
+    typeof (node as { kind?: unknown }).kind !== 'string'
+  ) {
+    throw new MalformedRuleError('a rule node must be an object with a string "kind"');
+  }
+}
+
+/**
+ * Read a `literal` node's `value`, rejecting a missing or non-scalar one. Without
+ * this, `{ kind: 'literal' }` resolves to `undefined` and slips past the caller.
+ */
+export function literalValue(node: { value?: unknown }): Scalar {
+  const { value } = node;
+  if (value === null || SCALAR_TYPES.has(typeof value)) {
+    return value as Scalar;
+  }
+  throw new MalformedRuleError(
+    `a literal must carry a scalar value, got ${value === undefined ? 'undefined' : typeof value}`,
+  );
+}

package/src/lib/charts/schema.ts

@@ -0,0 +1,72 @@
+import { CHART_RULE_CONTRACT_VERSION } from './types';
+
+/** Stable identifier for the published contract, versioned by the tag. */
+export const CHART_RULE_SCHEMA_ID = `https://rippling.com/schemas/${CHART_RULE_CONTRACT_VERSION}.json`;
+
+/**
+ * JSON Schema (2020-12) for the `{$rule}` placeholder and its closed node set.
+ *
+ * This is the contract. A consumer that keeps its own rule evaluator (rather
+ * than importing `evaluate`) can validate against this so the two never drift —
+ * every kind and operand shape the builders can emit is described here.
+ */
+export const chartRuleSchema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  $id: CHART_RULE_SCHEMA_ID,
+  title: 'Chart rule placeholder',
+  description: 'A rule tree the chart agent emits into a chart option, marked with $rule.',
+  type: 'object',
+  required: ['$rule', 'channel'],
+  additionalProperties: false,
+  properties: {
+    // A colour rule's top-level tree is the conditional-value form (`when(...)`),
+    // matching what `color()` builds and accepts. A bare ref/comparison/literal
+    // resolves to a number/boolean/constant, not a colour decision.
+    $rule: { $ref: '#/$defs/ifElse' },
+    channel: { const: 'color' },
+  },
+  $defs: {
+    scalar: { type: ['number', 'string', 'boolean', 'null'] },
+    node: {
+      oneOf: [
+        { $ref: '#/$defs/ref' },
+        { $ref: '#/$defs/literal' },
+        { $ref: '#/$defs/comparison' },
+        { $ref: '#/$defs/ifElse' },
+      ],
+    },
+    ref: {
+      type: 'object',
+      required: ['kind'],
+      additionalProperties: false,
+      properties: { kind: { const: 'value' } },
+    },
+    literal: {
+      type: 'object',
+      required: ['kind', 'value'],
+      additionalProperties: false,
+      properties: { kind: { const: 'literal' }, value: { $ref: '#/$defs/scalar' } },
+    },
+    comparison: {
+      type: 'object',
+      required: ['kind', 'left', 'right'],
+      additionalProperties: false,
+      properties: {
+        kind: { enum: ['equals', 'isNot', 'lessThan', 'greaterThan', 'lessOrEqual', 'greaterOrEqual'] },
+        left: { $ref: '#/$defs/node' },
+        right: { $ref: '#/$defs/node' },
+      },
+    },
+    ifElse: {
+      type: 'object',
+      required: ['kind', 'cond', 'then', 'else'],
+      additionalProperties: false,
+      properties: {
+        kind: { const: 'ifElse' },
+        cond: { $ref: '#/$defs/node' },
+        then: { $ref: '#/$defs/node' },
+        else: { $ref: '#/$defs/node' },
+      },
+    },
+  },
+} as const;

package/src/lib/charts/types.ts

@@ -0,0 +1,113 @@
+/**
+ * Chart rule vocabulary — shared types.
+ *
+ * A rule is a small, serializable tree of nodes discriminated by `kind`. The
+ * agent builds it with the helpers in `builders.ts`, which emit it wrapped in a
+ * `{$rule}` placeholder — the same idea as the `{$fn}` placeholders a chart
+ * already emits. The renderer resolves it with `evaluate`; the settings panel
+ * reads it with `describe`. All three agree because a node can only ever be one
+ * of the kinds defined here — the closed set the `chartRuleSchema` describes.
+ *
+ * v1 is scoped to conditional formatting: compare this datum's `value` against a
+ * constant, and (optionally) pick between two values. Richer pieces — aggregates,
+ * logic, more refs — are the documented roadmap in the README.
+ */
+
+export const CHART_RULE_CONTRACT_VERSION = 'chart_rule.v1' as const;
+export type ChartRuleContractVersion = typeof CHART_RULE_CONTRACT_VERSION;
+
+/** A leaf value a rule can carry or resolve to. */
+export type Scalar = number | string | boolean | null;
+
+/* -------------------------------------------------------------------------- */
+/* Nodes — the closed set, discriminated by `kind`. Each appears in every face. */
+/* -------------------------------------------------------------------------- */
+
+/** Reads a value out of the evaluation context — this datum's plotted value. */
+export type RefNode = { kind: 'value' };
+
+export interface LiteralNode {
+  kind: 'literal';
+  value: Scalar;
+}
+
+export type ComparisonKind =
+  | 'equals'
+  | 'isNot'
+  | 'lessThan'
+  | 'greaterThan'
+  | 'lessOrEqual'
+  | 'greaterOrEqual';
+export interface ComparisonNode {
+  kind: ComparisonKind;
+  left: RuleNode;
+  right: RuleNode;
+}
+
+/** The conditional-value form produced by `when(cond, then, else)`. */
+export interface IfElseNode {
+  kind: 'ifElse';
+  cond: RuleNode;
+  then: RuleNode;
+  else: RuleNode;
+}
+
+/** Any node of a rule tree. */
+export type RuleNode = RefNode | LiteralNode | ComparisonNode | IfElseNode;
+
+/* -------------------------------------------------------------------------- */
+/* The placeholder — how a rule is embedded in a chart option (like {$fn}).     */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * The chart channel a rule drives. v1 supports colour only — a rule decides the
+ * colour of a series/datum. Other channels (opacity, label visibility, …) are
+ * the documented roadmap and would be added here.
+ */
+export type RuleChannel = 'color';
+
+/**
+ * What a builder returns: a rule tree, marked so the renderer can find it, and
+ * tagged with the channel it targets. `channel: 'color'` says this resolves to a
+ * colour — so a reader sees the target without inferring it from where it sits.
+ */
+export interface RulePlaceholder {
+  $rule: RuleNode;
+  channel: RuleChannel;
+}
+
+/** A placeholder, or the bare tree — what `evaluate` and `describe` accept. */
+export type Rule = RulePlaceholder | RuleNode;
+
+/* -------------------------------------------------------------------------- */
+/* Evaluation                                                                   */
+/* -------------------------------------------------------------------------- */
+
+/** What a rule is evaluated against: the current datum's value. */
+export interface RuleContext {
+  value: number;
+}
+
+/** The result of evaluating a node. */
+export type RuleValue = Scalar;
+
+/**
+ * The deepest a rule may nest before `evaluate`/`describe` refuse it. Real rules
+ * are a handful of levels; this only stops a pathological deserialized tree from
+ * overflowing the stack. Far below the JS call-stack limit.
+ */
+export const MAX_RULE_DEPTH = 256;
+
+/* -------------------------------------------------------------------------- */
+/* Description — what the settings panel renders                                */
+/* -------------------------------------------------------------------------- */
+
+export type ControlRole = 'rule' | 'comparison' | 'ref' | 'literal';
+
+/** A node as the panel should show it: a label, its editable value, its parts. */
+export interface Control {
+  role: ControlRole;
+  label: string;
+  value?: Scalar;
+  parts?: Control[];
+}

package/src/lib/charts.ts

@@ -0,0 +1,43 @@
+export {
+  color,
+  equals,
+  greaterOrEqual,
+  greaterThan,
+  isNot,
+  isRulePlaceholder,
+  lessOrEqual,
+  lessThan,
+  literal,
+  value,
+  when,
+  type Operand,
+} from './charts/builders';
+export { evaluate } from './charts/evaluate';
+export { describe } from './charts/describe';
+export { chartRuleSchema, CHART_RULE_SCHEMA_ID } from './charts/schema';
+export {
+  ChartRuleError,
+  MalformedRuleError,
+  RuleDepthError,
+  RuleTypeError,
+  UnknownNodeError,
+} from './charts/errors';
+export {
+  CHART_RULE_CONTRACT_VERSION,
+  MAX_RULE_DEPTH,
+  type ChartRuleContractVersion,
+  type ComparisonKind,
+  type ComparisonNode,
+  type Control,
+  type ControlRole,
+  type IfElseNode,
+  type LiteralNode,
+  type RefNode,
+  type Rule,
+  type RuleChannel,
+  type RuleContext,
+  type RuleNode,
+  type RulePlaceholder,
+  type RuleValue,
+  type Scalar,
+} from './charts/types';