@gestaltbi/storybook

A story is data

import { resolveStory } from '@gestaltbi/storybook';

const resolved = resolveStory(story, rows, {
  columnDirectory: directory,   // from @gestaltbi/stream
  opContext: context,           // needed only by pivot and correlate panels
  locale: 'it',
  currency: 'EUR',
});

resolved.status     // 'pass' | 'warn' | 'fail' | 'none'
resolved.chapters   // prose with the numbers already in it, panels, verdicts

The output carries no colours, no components and no markup. A host renders ResolvedStory however it renders anything else, which is why the same story reads the same in a browser, a PDF job or a test.

Figures, and the {{token}} rule

Prose never contains a number. It contains a token naming a figure the chapter declares, and the resolver substitutes the value it computed from the frame.

{
  "id": "volume",
  "title": "How much moved",
  "figures": [
    { "id": "qty", "label": "Units sold", "measure": "sold_quant", "reduce": "sum", "format": "integer" }
  ],
  "prose": ["Across the period the business shifted {{qty}} units."],
  "takeaway": "Volume is the place to start."
}

This is the whole discipline of the format. A sentence written this way stays true when the filter moves, when next month lands, and when somebody points it at a different period — because the author committed to what to measure, never to what it came to.

Panels

What is drawn beside the prose. Five kinds, each resolved to plain data.

{
  "kind": "pivot",
  "format": "percent",
  "options": {
    "rows": ["category"],
    "measure": "calc:fail_rate",
    "type": "ratio", "numerator": "failed", "denominator": "resolved",
    "totals": true
  }
}

format says how the cells should be printed — a rate rendered raw is 0.1881408827463219, which is correct and unreadable. The host formats; the story only says what with, the same division of labour as FigureSpec.format.

A report that can be contradicted

A narrative that its own data cannot argue with is marketing. Chapters carry checks from @gestaltbi/stream; they run every time the story is resolved, and a failure is reported next to the paragraph that made the claim.

"checks": [
  { "id": "covers", "type": "covers", "label": "Revenue covered infrastructure, every month",
    "measure": "recognized_revenue", "by": "aws_cost" }
]

A chapter's status is the worst verdict in it, and the story's is the worst of its chapters — none when it asserts nothing at all. In the published Everpix report two checks fail on purpose: revenue never covered AWS, and the accrual margin was never positive. That is the report proving its own thesis rather than asserting it.

Fitting a story to a dataset

A story is written against one dataset's vocabulary. Pointing it at another does not throw — figures come back absent, checks skip — but the result is a page of em dashes, which reads like a bug rather than a mismatch. Ask first.

import { missingColumns } from '@gestaltbi/storybook';

const missing = missingColumns(story, declaredColumns);
if (missing.length) {
  // "This story was written for a different dataset", and name them.
}

requiredColumns walks figures, every panel kind and every check, so it sees a column named in a pivot's denominator as readily as one in a paragraph.

Where stories come from

This package ships none. A story belongs with the data it reads, so a GestaltBI config repo keeps story.json beside processing.json and owns its narrative outright — see Kickstarter Intelligence for a hand-written one.

@gestaltbi/inference writes them too: composeStory asks a model for this format, grounds it against the dataset profile, and hands back a Story ready to resolve. The model chooses what to compute and never learns what it came to — which is the same {{token}} rule, enforced from the other side.