ds-harness-remote-fast/apps/android/src/vendor/ds-bot/views.js

686 lines
35 KiB
JavaScript

// View cards: the blueprint a Bot may show, and the answer a user may send back.
// Pure, so the host can validate a card before it is stored and the client can
// later render the same blueprint. No component runs model-written code: formulas
// go through formula.js, and an html component only ever runs in a sandboxed frame.
import { compileFormula, createScope, evaluate, isName, show } from './formula.js'
const LAYOUT = ['stack', 'row']
const DISPLAY = ['text', 'metric', 'table', 'chart', 'progress', 'callout', 'sources', 'html']
const INPUT_TYPES = ['slider', 'choice', 'toggle', 'number']
const ANSWERS = ['options', 'confirm', 'form', 'submit']
const COMPONENTS = [...LAYOUT, ...DISPLAY, ...INPUT_TYPES, ...ANSWERS]
const TONES = ['good', 'warn', 'bad']
const TEXT_TONES = ['muted']
const CALLOUT_TONES = ['info', 'good', 'warn', 'bad']
export const CHART_KINDS = ['bar', 'hbar', 'line', 'area', 'donut']
const INTERACTIVE = new Set(ANSWERS)
const INPUTS = new Set(INPUT_TYPES)
const PROPS = {
stack: ['children', 'let'],
row: ['children', 'let'],
text: ['text', 'tone'],
metric: ['label', 'value', 'tone', 'caption'],
table: ['columns', 'rows'],
chart: ['kind', 'categories', 'series', 'unit', 'caption'],
progress: ['label', 'percent', 'value', 'max', 'valueLabel', 'tone'],
callout: ['text', 'tone'],
sources: ['items'],
html: ['html', 'summary', 'height'],
slider: ['id', 'label', 'min', 'max', 'step', 'value', 'unit'],
choice: ['id', 'label', 'options', 'value'],
toggle: ['id', 'label', 'value'],
number: ['id', 'label', 'min', 'max', 'step', 'value', 'unit'],
options: ['id', 'options', 'multi'],
confirm: ['id', 'confirmLabel', 'cancelLabel'],
form: ['id', 'fields', 'submitLabel'],
submit: ['id', 'label'],
}
const MAX_DEPTH = 8
const MAX_NODES = 64
const MAX_CHILDREN = 16
const MAX_TEXT = 2000
const MAX_CELL = 200
const MAX_COLUMNS = 8
const MAX_ROWS = 50
const MAX_OPTIONS = 8
const MAX_FIELDS = 6
const SUMMARY_PART = 40
const SUMMARY_COUNT = 8
const RESERVED = new Set(['true', 'false'])
// UTF-8 bytes of the blueprint JSON plus the title. Not a wrapped document:
// the tool rejects a show_view whose viewBytes() is over this before it
// normalizes or validates, so the number has to be the bytes the model sent.
export const VIEW_BYTE_LIMIT = 8192
const isRecord = value => value !== null && typeof value === 'object' && !Array.isArray(value)
const quoted = value => JSON.stringify(value)
const allowed = list => list.join(', ')
const isNumber = value => typeof value === 'number' && Number.isFinite(value)
const isScalar = value => typeof value === 'string' || typeof value === 'boolean' || isNumber(value)
// `{ "=": "a * b" }`: a value worked out from the view's inputs.
export const isFormula = value => isRecord(value) && Object.keys(value).length === 1 && Object.hasOwn(value, '=')
export function viewBytes(title, view) {
return new TextEncoder().encode(`${JSON.stringify(view) ?? ''}${title ?? ''}`).length
}
const NUMERIC = ['value', 'percent', 'min', 'max', 'step', 'height']
const numeric = value => (typeof value === 'string' && value.trim() !== '' && !Number.isNaN(Number(value)) ? Number(value) : value)
// Some providers serialize nested arrays as `{ item: [...] }` (XML-style) and
// numbers as strings. Normalize the blueprint before validation so a model is
// not asked to retry a call whose only fault is the provider's encoding.
// Arrays are unwrapped; numeric fields and chart values accept a numeric string.
// Returns a new object; the input is not mutated.
export function normalizeView(value) {
if (Array.isArray(value)) return value.map(normalizeView)
if (!isRecord(value)) return value
const keys = Object.keys(value)
// Unwrap recursively: a provider may nest the wrapper, as { item: { item: [...] } }.
if (keys.length === 1 && keys[0] === 'item') {
const inner = normalizeView(value.item)
if (Array.isArray(inner)) return inner
}
// Define own properties: an incoming "__proto__" key must become data the
// validator can reject, not hit the prototype setter and vanish from the JSON.
const out = {}
for (const key of keys) Object.defineProperty(out, key, { value: normalizeView(value[key]), writable: true, enumerable: true, configurable: true })
for (const field of NUMERIC) if (Object.hasOwn(out, field)) out[field] = numeric(out[field])
if (Array.isArray(out.values)) out.values = out.values.map(numeric)
return out
}
export function validateView(view) {
const ctx = { ids: new Set(), nodes: 0, interactive: false, inputs: new Map(), lets: new Map(), formulas: [] }
const error = checkNode(view, 'view', 1, ctx) ?? checkFormulas(ctx)
return error === undefined ? { ok: true, interactive: ctx.interactive } : { ok: false, error }
}
// What show_view checks before it shows a view: the same answer on the host and
// in the client. The bytes are measured as sent, before normalizeView unwraps the
// provider's encoding, or a wrapped view could shrink under the byte limit. The
// normalized view and the trimmed title come back; the title may be empty.
export function checkShownView(title, sent) {
let bytes
try { bytes = viewBytes(title, sent) } catch { return { error: 'The view is not JSON data.' } }
if (bytes > VIEW_BYTE_LIMIT) return { error: `The view is ${bytes} bytes; the limit is ${VIEW_BYTE_LIMIT}.` }
if (title !== undefined && title !== null && typeof title !== 'string') return { error: 'title: expected a string' }
const named = String(title ?? '').trim()
const view = normalizeView(sent)
const checked = validateView(view)
if (!checked.ok) return { error: checked.error }
return { title: named, view, interactive: checked.interactive }
}
function checkNode(node, path, depth, ctx) {
if (!isRecord(node)) return `${path}: expected a component object`
if (depth > MAX_DEPTH) return `${path}: ${depth} levels exceeds the limit of ${MAX_DEPTH}`
ctx.nodes += 1
if (ctx.nodes > MAX_NODES) return `${path}: ${ctx.nodes} components exceeds the limit of ${MAX_NODES}`
const type = node.type
if (!COMPONENTS.includes(type)) return `${path}.type: unknown component ${quoted(type)}; allowed: ${allowed(COMPONENTS)}`
const props = PROPS[type]
for (const key of Object.keys(node)) {
if (key === 'type' || props.includes(key)) continue
return `${path}.${key}: unknown property ${quoted(key)}; allowed: ${allowed(props)}`
}
if (INTERACTIVE.has(type)) ctx.interactive = true
switch (type) {
case 'stack': case 'row': return checkLayout(node, path, depth, ctx)
case 'text': return checkText(node, path, ctx)
case 'metric': return checkMetric(node, path, ctx)
case 'table': return checkTable(node, path, ctx)
case 'chart': return checkChart(node, path, ctx)
case 'progress': return checkProgress(node, path, ctx)
case 'callout': return checkCallout(node, path, ctx)
case 'sources': return checkSources(node, path)
case 'html': return checkHtml(node, path)
case 'slider': case 'number': return checkNumberInput(node, path, ctx)
case 'choice': return checkChoice(node, path, ctx)
case 'toggle': return checkToggle(node, path, ctx)
case 'options': return checkOptions(node, path, ctx)
case 'confirm': return checkConfirm(node, path, ctx)
case 'form': return checkForm(node, path, ctx)
default: return checkSubmit(node, path, ctx)
}
}
function checkLayout(node, path, depth, ctx) {
if (node.let !== undefined) {
if (depth !== 1) return `${path}.let: only the outermost component can define names`
if (!isRecord(node.let)) return `${path}.let: expected an object of names to formulas`
for (const [name, source] of Object.entries(node.let)) {
if (!isName(name) || RESERVED.has(name)) return `${path}.let.${name}: a name is letters, digits and _, and starts with a letter or _`
if (typeof source !== 'string') return `${path}.let.${name}: expected a formula string`
ctx.lets.set(name, { source, path: `${path}.let.${name}` })
}
}
if (!Array.isArray(node.children)) return `${path}.children: expected an array of 1 to ${MAX_CHILDREN} components`
if (node.children.length < 1 || node.children.length > MAX_CHILDREN) return `${path}.children: expected 1 to ${MAX_CHILDREN} children; got ${node.children.length}`
for (let index = 0; index < node.children.length; index += 1) {
const error = checkNode(node.children[index], `${path}.children[${index}]`, depth + 1, ctx)
if (error !== undefined) return error
}
return undefined
}
// A property that may be a literal of `kind` or a formula giving one. Formulas are
// checked once the whole tree, with every input and name, is known.
function checkValue(node, key, path, ctx, kind, { required = false, max = MAX_TEXT } = {}) {
const value = node[key]
const at = `${path}.${key}`
if (value === undefined) return required ? `${at}: ${expected(kind)}` : undefined
if (isFormula(value)) {
ctx.formulas.push({ source: value['='], path: at, kind })
return undefined
}
if (kind === 'number') return isNumber(value) ? undefined : `${at}: ${expected(kind)}`
if (Array.isArray(kind)) return kind.includes(value) ? undefined : `${at}: unknown tone ${quoted(value)}; allowed: ${allowed(kind)}`
if (kind === 'string') {
if (typeof value !== 'string') return `${at}: ${expected(kind)}`
return value.length > max ? `${at}: ${value.length} characters exceeds the limit of ${max}` : undefined
}
if (!isScalar(value)) return `${at}: ${expected(kind)}`
return undefined
}
const expected = kind => (kind === 'number' ? 'expected a number' : kind === 'string' ? 'expected a string' : Array.isArray(kind) ? `expected one of ${allowed(kind)}` : 'expected a string or a number')
function checkText(node, path, ctx) {
return checkValue(node, 'text', path, ctx, 'string', { required: true })
?? checkValue(node, 'tone', path, ctx, TEXT_TONES)
}
function checkMetric(node, path, ctx) {
if (typeof node.label !== 'string') return `${path}.label: expected a string`
if (node.value === undefined) return `${path}.value: expected a string or a number`
if (typeof node.value === 'number' && !Number.isFinite(node.value)) return `${path}.value: expected a finite number`
return checkValue(node, 'value', path, ctx, 'scalar')
?? checkValue(node, 'tone', path, ctx, TONES)
?? checkValue(node, 'caption', path, ctx, 'string')
}
function checkTable(node, path, ctx) {
if (!Array.isArray(node.columns)) return `${path}.columns: expected an array of at most ${MAX_COLUMNS} columns`
if (node.columns.length > MAX_COLUMNS) return `${path}.columns: ${node.columns.length} columns exceeds the limit of ${MAX_COLUMNS}`
for (let index = 0; index < node.columns.length; index += 1) {
const column = node.columns[index]
const at = `${path}.columns[${index}]`
if (!isRecord(column)) return `${at}: expected a column object`
for (const key of Object.keys(column)) {
if (key !== 'key' && key !== 'label') return `${at}.${key}: unknown property ${quoted(key)}; allowed: key, label`
}
if (typeof column.key !== 'string' || column.key === '') return `${at}.key: expected a non-empty string`
if (typeof column.label !== 'string') return `${at}.label: expected a string`
}
if (!Array.isArray(node.rows)) return `${path}.rows: expected an array of at most ${MAX_ROWS} rows`
if (node.rows.length > MAX_ROWS) return `${path}.rows: ${node.rows.length} rows exceeds the limit of ${MAX_ROWS}`
for (let row = 0; row < node.rows.length; row += 1) {
const cells = node.rows[row]
if (!Array.isArray(cells)) return `${path}.rows[${row}]: expected an array of cells`
for (let column = 0; column < cells.length; column += 1) {
const at = `${path}.rows[${row}][${column}]`
if (isFormula(cells[column])) { ctx.formulas.push({ source: cells[column]['='], path: at, kind: 'scalar' }); continue }
const text = cellText(cells[column])
if (text.length > MAX_CELL) return `${at}: ${text.length} characters exceeds the limit of ${MAX_CELL}`
}
}
return undefined
}
function checkChart(node, path, ctx) {
if (node.kind !== undefined && !CHART_KINDS.includes(node.kind)) return `${path}.kind: unknown chart ${quoted(node.kind)}; allowed: ${allowed(CHART_KINDS)}`
if (!Array.isArray(node.categories) || node.categories.length === 0) return `${path}.categories: expected a non-empty array of labels`
for (let index = 0; index < node.categories.length; index += 1) {
const label = node.categories[index]
if (typeof label !== 'string' && !isNumber(label)) return `${path}.categories[${index}]: expected a string`
}
if (!Array.isArray(node.series) || node.series.length === 0) return `${path}.series: expected a non-empty array of { name?, values }`
if (node.kind === 'donut' && node.series.length > 1) return `${path}.series: a donut takes one series; got ${node.series.length}`
for (let index = 0; index < node.series.length; index += 1) {
const series = node.series[index]
const at = `${path}.series[${index}]`
if (!isRecord(series)) return `${at}: expected a series object`
for (const key of Object.keys(series)) {
if (key !== 'name' && key !== 'values') return `${at}.${key}: unknown property ${quoted(key)}; allowed: name, values`
}
if (series.name !== undefined && typeof series.name !== 'string') return `${at}.name: expected a string`
if (!Array.isArray(series.values)) return `${at}.values: expected an array of numbers`
if (series.values.length !== node.categories.length) return `${at}.values: ${series.values.length} values for ${node.categories.length} categories`
for (let item = 0; item < series.values.length; item += 1) {
const value = series.values[item]
if (isFormula(value)) ctx.formulas.push({ source: value['='], path: `${at}.values[${item}]`, kind: 'number' })
else if (!isNumber(value)) return `${at}.values[${item}]: expected a number`
}
}
if (node.unit !== undefined && typeof node.unit !== 'string') return `${path}.unit: expected a string`
if (node.caption !== undefined && typeof node.caption !== 'string') return `${path}.caption: expected a string`
return undefined
}
function checkProgress(node, path, ctx) {
if (node.label !== undefined && typeof node.label !== 'string') return `${path}.label: expected a string`
if ((node.percent === undefined) === (node.value === undefined)) return `${path}: give percent (0 to 100), or value with max`
if (node.percent !== undefined && !isFormula(node.percent)) {
if (typeof node.percent !== 'number' || !Number.isFinite(node.percent) || node.percent < 0 || node.percent > 100) return `${path}.percent: expected a number from 0 to 100`
}
if (node.value !== undefined && node.max === undefined) return `${path}.max: expected a number with value`
if (node.value === undefined && node.max !== undefined) return `${path}.value: expected a number with max`
return checkValue(node, 'percent', path, ctx, 'number')
?? checkValue(node, 'value', path, ctx, 'number')
?? checkValue(node, 'max', path, ctx, 'number')
?? checkValue(node, 'valueLabel', path, ctx, 'scalar')
?? checkValue(node, 'tone', path, ctx, TONES)
}
function checkCallout(node, path, ctx) {
return checkValue(node, 'text', path, ctx, 'string', { required: true })
?? checkValue(node, 'tone', path, ctx, CALLOUT_TONES)
}
function checkSources(node, path) {
if (!Array.isArray(node.items) || node.items.length === 0) return `${path}.items: expected a non-empty array of { label, url }`
for (let index = 0; index < node.items.length; index += 1) {
const item = node.items[index]
const at = `${path}.items[${index}]`
if (!isRecord(item)) return `${at}: expected a { label, url } object`
for (const key of Object.keys(item)) {
if (key !== 'label' && key !== 'url') return `${at}.${key}: unknown property ${quoted(key)}; allowed: label, url`
}
if (typeof item.label !== 'string' || item.label.trim() === '') return `${at}.label: expected a non-empty string`
if (typeof item.url !== 'string' || !/^https?:\/\/[^\s]+$/i.test(item.url)) return `${at}.url: expected an http(s) address`
}
return undefined
}
function checkHtml(node, path) {
if (typeof node.html !== 'string' || node.html.trim() === '') return `${path}.html: expected a non-empty string`
if (typeof node.summary !== 'string' || node.summary.trim() === '') return `${path}.summary: expected one line that says what the view shows`
if (node.height !== undefined && (!isNumber(node.height) || node.height <= 0)) return `${path}.height: expected a positive number of pixels`
return undefined
}
function checkInputId(node, path, ctx) {
if (!isName(node.id) || RESERVED.has(node.id)) return `${path}.id: an input id is letters, digits and _, and starts with a letter or _, so formulas can use it`
if (ctx.ids.has(node.id)) return `${path}.id: duplicate id ${quoted(node.id)}`
ctx.ids.add(node.id)
if (typeof node.label !== 'string') return `${path}.label: expected a string`
return undefined
}
function checkNumberInput(node, path, ctx) {
const idError = checkInputId(node, path, ctx)
if (idError !== undefined) return idError
for (const key of ['min', 'max', 'step']) {
if (node[key] !== undefined && !isNumber(node[key])) return `${path}.${key}: expected a number`
}
if (node.type === 'slider' && (node.min === undefined || node.max === undefined)) return `${path}: a slider needs min and max`
if (node.min !== undefined && node.max !== undefined && node.max <= node.min) return `${path}.max: expected more than min (${node.min})`
if (node.step !== undefined && node.step <= 0) return `${path}.step: expected more than 0`
if (!isNumber(node.value)) return `${path}.value: expected a number`
if ((node.min !== undefined && node.value < node.min) || (node.max !== undefined && node.value > node.max)) return `${path}.value: expected a number from ${node.min ?? '-∞'} to ${node.max ?? '∞'}`
if (node.unit !== undefined && typeof node.unit !== 'string') return `${path}.unit: expected a string`
ctx.inputs.set(node.id, node.value)
return undefined
}
function checkChoice(node, path, ctx) {
const idError = checkInputId(node, path, ctx)
if (idError !== undefined) return idError
if (!Array.isArray(node.options) || node.options.length === 0) return `${path}.options: expected a non-empty array of { label, value }`
const labels = new Set()
const values = new Set()
for (let index = 0; index < node.options.length; index += 1) {
const option = node.options[index]
const at = `${path}.options[${index}]`
if (!isRecord(option)) return `${at}: expected a { label, value } object`
for (const key of Object.keys(option)) {
if (key !== 'label' && key !== 'value') return `${at}.${key}: unknown property ${quoted(key)}; allowed: label, value`
}
if (typeof option.label !== 'string' || option.label.trim() === '') return `${at}.label: expected a non-empty string`
if (labels.has(option.label)) return `${at}.label: duplicate label ${quoted(option.label)}`
labels.add(option.label)
const value = option.value ?? option.label
if (!isScalar(value)) return `${at}.value: expected a string, a number or true/false`
if (values.has(value)) return `${at}.value: duplicate value ${quoted(value)}`
values.add(value)
}
const chosen = node.value ?? choiceValue(node.options[0])
if (!values.has(chosen)) return `${path}.value: expected one of the options' values`
ctx.inputs.set(node.id, chosen)
return undefined
}
function checkToggle(node, path, ctx) {
const idError = checkInputId(node, path, ctx)
if (idError !== undefined) return idError
if (node.value !== undefined && typeof node.value !== 'boolean') return `${path}.value: expected true or false`
ctx.inputs.set(node.id, node.value === true)
return undefined
}
function checkOptions(node, path, ctx) {
const idError = checkId(node, path, ctx)
if (idError !== undefined) return idError
if (node.multi !== undefined && typeof node.multi !== 'boolean') return `${path}.multi: expected a boolean`
if (!Array.isArray(node.options)) return `${path}.options: expected an array of 1 to ${MAX_OPTIONS} options`
if (node.options.length < 1 || node.options.length > MAX_OPTIONS) return `${path}.options: expected 1 to ${MAX_OPTIONS} options; got ${node.options.length}`
const labels = new Set()
for (let index = 0; index < node.options.length; index += 1) {
const option = node.options[index]
const at = `${path}.options[${index}]`
if (!isRecord(option)) return `${at}: expected an option object`
for (const key of Object.keys(option)) {
if (key !== 'label' && key !== 'description') return `${at}.${key}: unknown property ${quoted(key)}; allowed: label, description`
}
if (typeof option.label !== 'string' || option.label.trim() === '') return `${at}.label: expected a non-empty string`
if (labels.has(option.label)) return `${at}.label: duplicate label ${quoted(option.label)}`
labels.add(option.label)
if (option.description !== undefined && typeof option.description !== 'string') return `${at}.description: expected a string`
}
return undefined
}
function checkConfirm(node, path, ctx) {
const idError = checkId(node, path, ctx)
if (idError !== undefined) return idError
if (node.confirmLabel !== undefined && typeof node.confirmLabel !== 'string') return `${path}.confirmLabel: expected a string`
if (node.cancelLabel !== undefined && typeof node.cancelLabel !== 'string') return `${path}.cancelLabel: expected a string`
return undefined
}
function checkForm(node, path, ctx) {
const idError = checkId(node, path, ctx)
if (idError !== undefined) return idError
if (node.submitLabel !== undefined && typeof node.submitLabel !== 'string') return `${path}.submitLabel: expected a string`
if (!Array.isArray(node.fields)) return `${path}.fields: expected an array of at most ${MAX_FIELDS} fields`
if (node.fields.length > MAX_FIELDS) return `${path}.fields: ${node.fields.length} fields exceeds the limit of ${MAX_FIELDS}`
const seen = new Set()
for (let index = 0; index < node.fields.length; index += 1) {
const field = node.fields[index]
const at = `${path}.fields[${index}]`
if (!isRecord(field)) return `${at}: expected a field object`
for (const key of Object.keys(field)) {
if (key !== 'id' && key !== 'label' && key !== 'placeholder') return `${at}.${key}: unknown property ${quoted(key)}; allowed: id, label, placeholder`
}
if (typeof field.id !== 'string' || field.id === '') return `${at}.id: expected a non-empty string`
if (field.id === '__proto__') return `${at}.id: "__proto__" cannot be an id`
if (seen.has(field.id)) return `${at}.id: duplicate field id ${quoted(field.id)}`
seen.add(field.id)
if (typeof field.label !== 'string') return `${at}.label: expected a string`
if (field.placeholder !== undefined && typeof field.placeholder !== 'string') return `${at}.placeholder: expected a string`
}
return undefined
}
function checkSubmit(node, path, ctx) {
const idError = checkId(node, path, ctx)
if (idError !== undefined) return idError
if (node.label !== undefined && typeof node.label !== 'string') return `${path}.label: expected a string`
return undefined
}
function checkId(node, path, ctx) {
if (typeof node.id !== 'string' || node.id === '') return `${path}.id: expected a non-empty string`
// A `__proto__` id would write through to a plain object's prototype where the
// answer is kept, losing it silently.
if (node.id === '__proto__') return `${path}.id: "__proto__" cannot be an id`
if (ctx.ids.has(node.id)) return `${path}.id: duplicate id ${quoted(node.id)}`
ctx.ids.add(node.id)
return undefined
}
// Every formula parses, reads only inputs and names the view defines, and gives the
// right kind of value with the inputs as the Bot set them.
function checkFormulas(ctx) {
const known = new Set([...ctx.inputs.keys(), ...ctx.lets.keys()])
const lets = new Map()
for (const [name, entry] of ctx.lets) {
if (ctx.inputs.has(name)) return `${entry.path}: ${quoted(name)} is already an input id`
const compiled = compileFormula(entry.source)
if (compiled.error !== undefined) return `${entry.path}: ${compiled.error}`
const unknown = compiled.names.find(item => !known.has(item))
if (unknown !== undefined) return `${entry.path}: unknown name ${quoted(unknown)}; known: ${allowed([...known]) || '(none)'}`
lets.set(name, compiled.tree)
}
const lookup = createScope(ctx.inputs, lets)
for (const [name, entry] of ctx.lets) {
const result = evaluate(lets.get(name), lookup)
if (result.error !== undefined) return `${entry.path}: ${result.error}`
}
for (const formula of ctx.formulas) {
const compiled = compileFormula(formula.source)
if (compiled.error !== undefined) return `${formula.path}: ${compiled.error}`
const unknown = compiled.names.find(item => !known.has(item))
if (unknown !== undefined) return `${formula.path}: unknown name ${quoted(unknown)}; known: ${allowed([...known]) || '(none)'}`
const result = evaluate(compiled.tree, lookup)
if (result.error !== undefined) return `${formula.path}: ${result.error}`
const problem = kindProblem(result.value, formula.kind)
if (problem !== undefined) return `${formula.path}: the formula gives ${quoted(result.value)}; ${problem}`
}
return undefined
}
function kindProblem(value, kind) {
if (kind === 'number') return isNumber(value) ? undefined : 'expected a number'
if (Array.isArray(kind)) return kind.includes(value) ? undefined : `expected one of ${allowed(kind)}`
if (kind === 'string') return isScalar(value) ? undefined : 'expected text'
return isScalar(value) ? undefined : 'expected a string or a number'
}
function cellText(value) {
if (typeof value === 'string') return value
const text = JSON.stringify(value)
return typeof text === 'string' ? text : ''
}
// -------------------------------------------------------------------------
// Working a blueprint out: the client draws with these, the summary reads them.
const compiled = new WeakMap()
const treeOf = (formula) => {
let entry = compiled.get(formula)
if (entry === undefined) {
entry = compileFormula(formula['='])
compiled.set(formula, entry)
}
return entry
}
export const choiceValue = option => option?.value ?? option?.label
function walk(node, visit) {
if (!isRecord(node)) return
visit(node)
if (LAYOUT.includes(node.type) && Array.isArray(node.children)) for (const child of node.children) walk(child, visit)
}
export function viewInputs(view) {
const found = []
walk(view, (node) => { if (INPUTS.has(node.type)) found.push(node) })
return found
}
export function inputDefault(node) {
if (node.type === 'toggle') return node.value === true
if (node.type === 'choice') return node.value ?? choiceValue(Array.isArray(node.options) ? node.options[0] : undefined)
return node.value
}
export const hasInputs = view => viewInputs(view).length > 0
// The values a view's formulas read: each input's default unless `values` sets it.
export function viewScope(view, values = {}) {
const inputs = new Map()
for (const node of viewInputs(view)) inputs.set(node.id, Object.hasOwn(values, node.id) ? values[node.id] : inputDefault(node))
const lets = new Map()
for (const [name, source] of Object.entries(isRecord(view?.let) ? view.let : {})) {
const entry = compileFormula(source)
if (entry.tree !== undefined) lets.set(name, entry.tree)
}
return createScope(inputs, lets)
}
// A property's value: the literal, or the formula worked out. A formula that fails
// with these inputs gives `fallback`.
export function resolve(value, lookup, fallback = undefined) {
if (!isFormula(value)) return value
const entry = treeOf(value)
if (entry.tree === undefined) return fallback
const result = evaluate(entry.tree, lookup)
return result.error === undefined ? result.value : fallback
}
export const asText = value => (value === undefined || value === null ? '' : show(value))
// -------------------------------------------------------------------------
// Summaries
function clip(text) {
const flat = String(text).replace(/\s+/g, ' ').trim()
return flat.length <= SUMMARY_PART ? flat : flat.slice(0, SUMMARY_PART)
}
const choiceLabel = (node, value) => (Array.isArray(node.options) ? node.options : []).find(option => choiceValue(option) === value)?.label ?? asText(value)
function inputText(node, value) {
if (node.type === 'toggle') return value === true ? 'on' : 'off'
if (node.type === 'choice') return choiceLabel(node, value)
return `${asText(value)}${node.unit ? ` ${node.unit}` : ''}`
}
function progressPercent(node, lookup) {
if (node.percent !== undefined) return Number(resolve(node.percent, lookup, 0))
const max = Number(resolve(node.max, lookup, 0))
return max > 0 ? (Number(resolve(node.value, lookup, 0)) / max) * 100 : 0
}
function componentSummary(node, lookup) {
const value = item => asText(resolve(item, lookup, ''))
switch (node.type) {
case 'text': return `text: ${value(node.text)}`
case 'metric': return `metric: ${node.label}=${value(node.value)}`
case 'table': return `table: ${(Array.isArray(node.columns) ? node.columns : []).map(column => column?.label ?? column?.key ?? '').filter(Boolean).join('/')}`
case 'chart': {
const series = Array.isArray(node.series) ? node.series[0] : undefined
const values = Array.isArray(series?.values) ? series.values : []
const unit = node.unit ? ` ${node.unit}` : ''
return `chart: ${(Array.isArray(node.categories) ? node.categories : []).map((label, index) => `${label}=${value(values[index])}${unit}`).join(', ')}`
}
case 'progress': return `progress: ${node.label ? `${node.label} ` : ''}${Math.round(progressPercent(node, lookup))}%`
case 'callout': return `callout: ${value(node.text)}`
case 'sources': return `sources: ${(Array.isArray(node.items) ? node.items : []).map(item => item?.label).filter(Boolean).join('/')}`
case 'html': return `html: ${node.summary ?? ''}`
case 'slider': case 'number': case 'choice': case 'toggle': return `${node.type}: ${node.label}=${inputText(node, inputDefault(node))}`
case 'options': return `options: ${(Array.isArray(node.options) ? node.options : []).map(option => option?.label).filter(Boolean).join('/')}`
case 'confirm': return 'confirm'
case 'form': return `form: ${(Array.isArray(node.fields) ? node.fields : []).map(field => field?.label ?? field?.id).filter(Boolean).join('/')}`
case 'submit': return `submit: ${node.label ?? 'Send'}`
default: return undefined
}
}
// One line for a handoff or a checkpoint. Containers add nothing of their own;
// each component keeps one short phrase, and the line stops after a few. Formulas
// show what they give with the inputs as the Bot set them.
export function viewSummary(view) {
const parts = []
const lookup = viewScope(view)
const visit = (node) => {
if (parts.length >= SUMMARY_COUNT || !isRecord(node)) return
const line = componentSummary(node, lookup)
if (line !== undefined) parts.push(clip(line))
if (parts.length >= SUMMARY_COUNT || !LAYOUT.includes(node.type) || !Array.isArray(node.children)) return
for (const child of node.children) visit(child)
}
visit(view)
return parts.join('; ')
}
// The inputs of an answer as `Label=value` pairs, for the Bot's history.
export function inputsSummary(view, inputs) {
if (!isRecord(inputs)) return ''
return viewInputs(view)
.filter(node => Object.hasOwn(inputs, node.id))
.map(node => `${node.label || node.id}=${inputText(node, inputs[node.id])}`)
.join('; ')
}
// -------------------------------------------------------------------------
// Answers
function interactiveNodes(node, found = []) {
walk(node, (item) => { if (INTERACTIVE.has(item.type)) found.push(item) })
return found
}
// `action` is the id of the component the user submitted. One submit settles
// the whole card, so only that component's values are kept, plus the inputs'
// values when the view has inputs.
export function validateViewAnswer(view, action, values) {
const nodes = interactiveNodes(view)
if (typeof action !== 'string' || action === '') return { error: `action: expected an interactive component id; allowed: ${allowed(nodes.map(node => node.id))}` }
const node = nodes.find(item => item.id === action)
if (node === undefined) return { error: `action: no interactive component with id ${quoted(action)}; allowed: ${allowed(nodes.map(item => item.id))}` }
if (!isRecord(values)) return { error: 'values: expected an object' }
const inputs = validateInputs(view, values.inputs)
if (inputs.error !== undefined) return inputs
const extra = inputs.inputs === undefined ? {} : { inputs: inputs.inputs }
if (node.type === 'submit') return { ...extra }
const own = node.type === 'options' ? validateOptions(node, values) : node.type === 'confirm' ? validateConfirm(values) : validateForm(node, values)
return own.error === undefined ? { ...own, ...extra } : own
}
// Every input of the view, as sent or else as the Bot set it.
function validateInputs(view, sent) {
const nodes = viewInputs(view)
if (nodes.length === 0) return sent === undefined ? {} : { error: 'values.inputs: this view has no inputs' }
if (sent !== undefined && !isRecord(sent)) return { error: 'values.inputs: expected an object of input ids to values' }
const given = sent ?? {}
const ids = nodes.map(node => node.id)
const unknown = Object.keys(given).find(key => !ids.includes(key))
if (unknown !== undefined) return { error: `values.inputs.${unknown}: unknown input; allowed: ${allowed(ids)}` }
const inputs = {}
for (const node of nodes) {
const value = Object.hasOwn(given, node.id) ? given[node.id] : inputDefault(node)
const at = `values.inputs.${node.id}`
if (node.type === 'toggle' && typeof value !== 'boolean') return { error: `${at}: expected true or false` }
if (node.type === 'choice' && !(Array.isArray(node.options) ? node.options : []).some(option => choiceValue(option) === value)) return { error: `${at}: expected one of the options' values` }
if (node.type === 'slider' || node.type === 'number') {
if (!isNumber(value)) return { error: `${at}: expected a number` }
if ((node.min !== undefined && value < node.min) || (node.max !== undefined && value > node.max)) return { error: `${at}: expected a number from ${node.min ?? '-∞'} to ${node.max ?? '∞'}` }
}
inputs[node.id] = value
}
return { inputs }
}
function validateOptions(node, values) {
if (!Array.isArray(values.selected)) return { error: 'values.selected: expected an array of option labels' }
const labels = new Set((node.options ?? []).map(option => option?.label))
const picked = values.selected.filter(label => typeof label === 'string' && labels.has(label))
const selected = node.multi === true ? [...new Set(picked)] : picked.slice(0, 1)
if (selected.length === 0) return { error: 'values.selected: select at least one option' }
return { selected }
}
function validateConfirm(values) {
if (typeof values.confirmed !== 'boolean') return { error: 'values.confirmed: expected a boolean' }
return { confirmed: values.confirmed }
}
function validateForm(node, values) {
if (!isRecord(values.fields)) return { error: 'values.fields: expected an object of field ids to strings' }
const declared = (node.fields ?? []).map(field => field?.id).filter(id => typeof id === 'string')
const allowedIds = new Set(declared)
const fields = {}
for (const [key, value] of Object.entries(values.fields)) {
if (!allowedIds.has(key)) return { error: `values.fields.${key}: unknown field; allowed: ${allowed(declared)}` }
if (typeof value !== 'string') return { error: `values.fields.${key}: expected a string` }
if (value.length > MAX_TEXT) return { error: `values.fields.${key}: ${value.length} characters exceeds the limit of ${MAX_TEXT}` }
fields[key] = value
}
return { fields }
}