@rippling/rippling-sdk 0.2.0-alpha.108 → 0.2.0-alpha.110

package/src/lib/charts/agent-reference.md

@@ -0,0 +1,73 @@
+# Visualization grammar authoring reference
+
+Use these builders only when a chart property must change according to the
+current data point's numeric value. They produce JSON-safe rule data; they do not
+execute callbacks or render a chart.
+
+## Import
+
+In the Deno TypeScript sandbox, import from the module specifier published in
+`capabilities.json`:
+
+```ts
+import { color, greaterThan, value, when } from 'npm:@rippling/rippling-sdk/lib/charts';
+```
+
+## Builders
+
+- `value` reads the current data point's plotted numeric value.
+- `literal(scalar)` explicitly creates a constant. Bare numbers, strings,
+  booleans, and `null` are converted to literals automatically.
+- `equals(left, right)`, `isNot(left, right)`, `lessThan(left, right)`,
+  `greaterThan(left, right)`, `lessOrEqual(left, right)`, and
+  `greaterOrEqual(left, right)` return a condition.
+- `when(condition, ifTrue, ifFalse?)` returns `ifTrue` when the condition is true
+  and `ifFalse` otherwise. Both results are colour strings; the omitted false
+  branch becomes `null` to preserve the chart's default colour.
+- `color(when(...))` marks the conditional result as a color rule.
+
+Example: highlight values over 20 and otherwise preserve the chart's default
+color.
+
+```ts
+const conditionalColor = color(when(greaterThan(value, 20), '$token:categorical.series-5'));
+```
+
+The builders return plain data that renderers and editors can read. Always use
+the builders above. Do not hand-author the serialized `$rule` object shown here:
+
+```json
+{
+  "channel": "color",
+  "$rule": {
+    "kind": "ifElse",
+    "cond": {
+      "kind": "greaterThan",
+      "left": { "kind": "value" },
+      "right": { "kind": "literal", "value": 20 }
+    },
+    "then": { "kind": "literal", "value": "$token:categorical.series-5" },
+    "else": { "kind": "literal", "value": null }
+  }
+}
+```
+
+## Current limits
+
+The current contract supports only the `color` channel and per-point `value`.
+It has one fixed, non-recursive shape: comparisons contain only `value` or
+literal operands, and `when` contains one comparison plus two colour literals.
+Do not place comparisons, `when(...)`, or `color(...)` inside another operand or
+branch.
+
+Rules do not calculate aggregates such as maximum, average, or percentile. Chart
+code may calculate a finite scalar threshold from its data first and then use
+that scalar in a rule. For example, after computing an 80th-percentile
+`threshold`, use
+`color(when(greaterOrEqual(value, threshold), highlightColor))` to highlight the
+top 20%. The rule remains a per-point comparison; the surrounding chart code
+owns the aggregate calculation.
+
+Other data fields, compound boolean logic, opacity, label visibility, and other
+output channels are not supported. Keep static colors as ordinary chart values
+rather than wrapping them in rules.

package/src/lib/charts/builders.ts

@@ -1,37 +1,48 @@
 import { ChartRuleError } from './errors';
 import {
-  type ComparisonKind,
-  type ComparisonNode,
+  type ConditionNode,
+  type ComparisonOperandNode,
+  type EqualityComparisonNode,
   type IfElseNode,
   type LiteralNode,
+  type NumericComparisonNode,
+  type NumericOperandNode,
   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;
+/** A non-recursive comparison operand: `value`, a literal node, or a scalar. */
+export type Operand = ComparisonOperandNode | Scalar;
+export type NumericOperand = NumericOperandNode | number;
 
-function isRuleNode(operand: Operand): operand is RuleNode {
-  return typeof operand === 'object' && operand !== null && 'kind' in operand;
+function hasOwn(value: object, key: PropertyKey): boolean {
+  return Object.prototype.hasOwnProperty.call(value, key);
+}
+
+function isOperandNode(operand: Operand): operand is ComparisonOperandNode {
+  return typeof operand === 'object' && operand !== null && hasOwn(operand, 'kind');
 }
 
 /** 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;
+  return typeof value === 'object' && value !== null && hasOwn(value, '$rule');
 }
 
 /** Wrap a bare scalar as a literal node. */
-export function literal(value: Scalar): LiteralNode {
+export function literal<const TValue extends Scalar>(value: TValue): LiteralNode<TValue> {
+  if (typeof value === 'number' && !Number.isFinite(value)) {
+    throw new ChartRuleError('literal(value) requires a finite number');
+  }
   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);
+function toOperandNode(operand: Operand): ComparisonOperandNode {
+  return isOperandNode(operand) ? operand : literal(operand);
+}
+
+function toNumericOperandNode(operand: NumericOperand): NumericOperandNode {
+  return typeof operand === 'number' ? literal(operand) : operand;
 }
 
 /**
@@ -40,36 +51,43 @@ function toNode(operand: Operand): RuleNode {
  */
 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) });
+/* Comparisons — return a condition with no nested expressions. */
+function equalityComparison(
+  kind: EqualityComparisonNode['kind'],
+): (left: Operand, right: Operand) => EqualityComparisonNode {
+  return (left, right) => ({ kind, left: toOperandNode(left), right: toOperandNode(right) });
+}
+function numericComparison(
+  kind: NumericComparisonNode['kind'],
+): (left: NumericOperand, right: NumericOperand) => NumericComparisonNode {
+  return (left, right) => ({ kind, left: toNumericOperandNode(left), right: toNumericOperandNode(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');
+export const equals = equalityComparison('equals');
+export const isNot = equalityComparison('isNot');
+export const lessThan = numericComparison('lessThan');
+export const greaterThan = numericComparison('greaterThan');
+export const lessOrEqual = numericComparison('lessOrEqual');
+export const greaterOrEqual = numericComparison('greaterOrEqual');
 
 /**
- * A conditional value: pick `ifTrue` when the condition holds, else `ifFalse`.
- * Channel-agnostic — wrap it in a channel builder (`color`) to target something.
+ * A conditional colour: pick `ifTrue` when the condition holds, else `ifFalse`.
  *
  *   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.
+ * override (the chart's default is kept). Branches are colour literals only;
+ * nested rules are intentionally unsupported in v1.
  */
-export function when(condition: RuleNode, ifTrue: Operand, ifFalse?: Operand): IfElseNode {
+export function when(condition: ConditionNode, ifTrue: string, ifFalse: string | null = null): 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),
+    then: literal(ifTrue),
+    else: literal(ifFalse),
   };
 }
 
@@ -80,11 +98,9 @@ export function when(condition: RuleNode, ifTrue: Operand, ifFalse?: Operand): I
  *   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'`.
+ * Takes the flat conditional value produced by `when(...)`. Returns a `{$rule}`
+ * placeholder tagged `channel: 'color'`.
  */
-export function color(rule: IfElseNode | RulePlaceholder): RulePlaceholder {
-  return { $rule: isRulePlaceholder(rule) ? rule.$rule : rule, channel: 'color' };
+export function color(rule: IfElseNode): RulePlaceholder {
+  return { $rule: rule, channel: 'color' };
 }

package/src/lib/charts/capabilities.json

@@ -0,0 +1,96 @@
+{
+  "contractVersion": 1,
+  "moduleSpecifier": "npm:@rippling/rippling-sdk/lib/charts",
+  "builders": {
+    "value": {
+      "kind": "input",
+      "returns": "number"
+    },
+    "literal": {
+      "kind": "literal",
+      "parameters": [
+        "scalar"
+      ],
+      "returns": "value"
+    },
+    "equals": {
+      "kind": "comparison",
+      "parameters": [
+        "value",
+        "value"
+      ],
+      "returns": "condition"
+    },
+    "isNot": {
+      "kind": "comparison",
+      "parameters": [
+        "value",
+        "value"
+      ],
+      "returns": "condition"
+    },
+    "lessThan": {
+      "kind": "comparison",
+      "parameters": [
+        "value",
+        "value"
+      ],
+      "returns": "condition"
+    },
+    "greaterThan": {
+      "kind": "comparison",
+      "parameters": [
+        "value",
+        "value"
+      ],
+      "returns": "condition"
+    },
+    "lessOrEqual": {
+      "kind": "comparison",
+      "parameters": [
+        "value",
+        "value"
+      ],
+      "returns": "condition"
+    },
+    "greaterOrEqual": {
+      "kind": "comparison",
+      "parameters": [
+        "value",
+        "value"
+      ],
+      "returns": "condition"
+    },
+    "when": {
+      "kind": "conditional",
+      "parameters": [
+        "condition",
+        "color",
+        "color?"
+      ],
+      "returns": "conditional-color"
+    },
+    "color": {
+      "kind": "channel",
+      "parameters": [
+        "conditional-color"
+      ],
+      "returns": "color-rule",
+      "placeholderChannel": "color"
+    }
+  },
+  "supportedChannels": [
+    "color"
+  ],
+  "supportedNodeKinds": [
+    "literal",
+    "value",
+    "equals",
+    "isNot",
+    "lessThan",
+    "greaterThan",
+    "lessOrEqual",
+    "greaterOrEqual",
+    "ifElse"
+  ]
+}

package/src/lib/charts/describe.ts

@@ -1,56 +1,50 @@
-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';
+import { UnknownNodeError } from './errors';
+import { parseChartRule } from './schema';
+import { type ComparisonOperandNode, type Control, 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
+ * editable parts. Accepts a `{$rule}` placeholder or a bare node. Reads the same
+ * value `evaluate` runs — and validates it 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`.
+ * The Valibot parser rejects malformed or nested values before this flat
+ * formatter reads them.
  */
-export function describe(rule: Rule): Control {
-  if (isRulePlaceholder(rule)) {
-    return visit(rule.$rule, 0);
+export function describe(rule: unknown): Control {
+  const parsedRule = parseChartRule(rule);
+  if ('$rule' in parsedRule) {
+    return visit(parsedRule.$rule);
   }
-  return visit(rule, 0);
+  return visit(parsedRule);
 }
 
-function visit(node: RuleNode, depth: number): Control {
-  if (depth > MAX_RULE_DEPTH) {
-    throw new RuleDepthError(MAX_RULE_DEPTH);
-  }
-  assertRuleNode(node);
-  const next = depth + 1;
+function visit(node: RuleNode): Control {
   switch (node.kind) {
     case 'value':
       return { role: 'ref', label: "this row's value" };
     case 'literal': {
-      const scalar = literalValue(node);
+      const scalar = node.value;
       return { role: 'literal', label: String(scalar), value: scalar };
     }
 
     case 'equals':
-      return comparison('is', node.left, node.right, next);
+      return comparison('is', node.left, node.right);
     case 'isNot':
-      return comparison('is not', node.left, node.right, next);
+      return comparison('is not', node.left, node.right);
     case 'lessThan':
-      return comparison('is under', node.left, node.right, next);
+      return comparison('is under', node.left, node.right);
     case 'greaterThan':
-      return comparison('is over', node.left, node.right, next);
+      return comparison('is over', node.left, node.right);
     case 'lessOrEqual':
-      return comparison('is at most', node.left, node.right, next);
+      return comparison('is at most', node.left, node.right);
     case 'greaterOrEqual':
-      return comparison('is at least', node.left, node.right, next);
+      return comparison('is at least', node.left, node.right);
 
     case 'ifElse':
       return {
         role: 'rule',
         label: 'when',
-        parts: [visit(node.cond, next), visit(node.then, next), visit(node.else, next)],
+        parts: [visit(node.cond), literalControl(node.then.value), literalControl(node.else.value)],
       };
 
     default:
@@ -58,8 +52,16 @@ function visit(node: RuleNode, depth: number): Control {
   }
 }
 
-function comparison(label: string, left: RuleNode, right: RuleNode, depth: number): Control {
-  return { role: 'comparison', label, parts: [visit(left, depth), visit(right, depth)] };
+function comparison(label: string, left: ComparisonOperandNode, right: ComparisonOperandNode): Control {
+  return { role: 'comparison', label, parts: [operandControl(left), operandControl(right)] };
+}
+
+function operandControl(node: ComparisonOperandNode): Control {
+  return node.kind === 'value' ? { role: 'ref', label: "this row's value" } : literalControl(node.value);
+}
+
+function literalControl(value: string | number | boolean | null): Control {
+  return { role: 'literal', label: String(value), value };
 }
 
 function unreachable(node: never): never {

package/src/lib/charts/errors.ts

@@ -21,7 +21,7 @@ export class RuleTypeError extends ChartRuleError {
 }
 
 /**
- * A structurally invalid node in a deserialized tree: not an object, no string
+ * A structurally invalid node in a deserialized value: 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
@@ -35,11 +35,7 @@ export class MalformedRuleError extends ChartRuleError {
   }
 }
 
-/**
- * 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.
- */
+/** @deprecated v1 is non-recursive. Retained for source compatibility. */
 export class RuleDepthError extends ChartRuleError {
   constructor(maxDepth: number) {
     super(`chart rule nested deeper than ${maxDepth} levels`);

package/src/lib/charts/evaluate.ts

@@ -1,9 +1,8 @@
-import { isRulePlaceholder } from './builders';
-import { MalformedRuleError, RuleDepthError, RuleTypeError, UnknownNodeError } from './errors';
-import { assertRuleNode, literalValue } from './guards';
+import { MalformedRuleError, RuleTypeError, UnknownNodeError } from './errors';
+import { parseChartRule } from './schema';
 import {
-  MAX_RULE_DEPTH,
-  type Rule,
+  type ComparisonOperandNode,
+  type NumericOperandNode,
   type RuleChannel,
   type RuleContext,
   type RuleNode,
@@ -12,51 +11,45 @@ import {
 
 /**
  * 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
+ * bare node. 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.
+ * Pure and non-recursive: the only inputs are the validated flat rule and the
+ * context. No clock, randomness, callbacks, or I/O.
  */
-export function evaluate(rule: Rule, ctx: RuleContext): RuleValue {
-  if (isRulePlaceholder(rule)) {
-    return coerceForChannel(rule.channel, visit(rule.$rule, ctx, 0));
+export function evaluate(rule: unknown, ctx: RuleContext): RuleValue {
+  const parsedRule = parseChartRule(rule);
+  if ('$rule' in parsedRule) {
+    return coerceForChannel(parsedRule.channel, visit(parsedRule.$rule, ctx));
   }
-  return visit(rule, ctx, 0);
+  return visit(parsedRule, ctx);
 }
 
-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;
+function visit(node: RuleNode, ctx: RuleContext): RuleValue {
   switch (node.kind) {
     case 'value':
       return ctx.value;
     case 'literal':
-      return literalValue(node);
+      return node.value;
 
     case 'equals':
-      return visit(node.left, ctx, next) === visit(node.right, ctx, next);
+      return operand(node.left, ctx) === operand(node.right, ctx);
     case 'isNot':
-      return visit(node.left, ctx, next) !== visit(node.right, ctx, next);
+      return operand(node.left, ctx) !== operand(node.right, ctx);
     case 'lessThan':
-      return num(visit(node.left, ctx, next)) < num(visit(node.right, ctx, next));
+      return numericOperand(node.left, ctx) < numericOperand(node.right, ctx);
     case 'greaterThan':
-      return num(visit(node.left, ctx, next)) > num(visit(node.right, ctx, next));
+      return numericOperand(node.left, ctx) > numericOperand(node.right, ctx);
     case 'lessOrEqual':
-      return num(visit(node.left, ctx, next)) <= num(visit(node.right, ctx, next));
+      return numericOperand(node.left, ctx) <= numericOperand(node.right, ctx);
     case 'greaterOrEqual':
-      return num(visit(node.left, ctx, next)) >= num(visit(node.right, ctx, next));
+      return numericOperand(node.left, ctx) >= numericOperand(node.right, ctx);
 
     case 'ifElse':
-      return bool(visit(node.cond, ctx, next)) ? visit(node.then, ctx, next) : visit(node.else, ctx, next);
+      return visit(node.cond, ctx) ? node.then.value : node.else.value;
 
     default:
       return unreachable(node);
@@ -67,18 +60,12 @@ function visit(node: RuleNode, ctx: RuleContext, depth: number): RuleValue {
 /* 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 operand(node: ComparisonOperandNode, ctx: RuleContext): RuleValue {
+  return node.kind === 'value' ? ctx.value : node.value;
 }
 
-function bool(value: RuleValue): boolean {
-  if (typeof value === 'boolean') {
-    return value;
-  }
-  throw new RuleTypeError(`expected a boolean, got ${typeName(value)}`);
+function numericOperand(node: NumericOperandNode, ctx: RuleContext): number {
+  return node.kind === 'value' ? ctx.value : node.value;
 }
 
 /** A colour channel must resolve to a colour string, or null for "no override". */