Skip to content
RANDSUM — TypeScript Dice Rolling Library for Tabletop RPGs

@randsum/display-utils — UI Utilities

@randsum/display-utils is an internal package that provides helper utilities for building UIs on top of @randsum/roller. It powers the site’s interactive playground, the component library’s modifier reference panel, and the StackBlitz “open in editor” feature. It is consumed by @randsum/component-library and is not published to npm separately.

computeSteps

Section titled “computeSteps”

Converts a RollRecord into an ordered array of TooltipStep values describing every modifier applied during the roll — initial dice, each modifier step, and the final result. Designed for rendering step-by-step roll breakdowns.

Signature

Section titled “Signature”
import { computeSteps } from '@randsum/display-utils'
import type { TooltipStep } from '@randsum/display-utils'


const steps: readonly TooltipStep[] = computeSteps(rollRecord)

TooltipStep union

Section titled “TooltipStep union”
KindFieldsDescription
`‘rolls’``label`, `unchanged`, `removed`, `added`A modifier step showing kept/removed dice
`‘arithmetic’``label`, `display`A +/−/× modifier applied to the total
`‘finalRolls’``rolls`, `arithmeticDelta`Final dice pool and net arithmetic offset
`‘divider’`—Visual separator (reserved)

Example

Section titled “Example”
import { roll } from '@randsum/roller'
import { computeSteps } from '@randsum/display-utils'


const result = roll('4d6L')
const record = result.rolls[0]!
const steps = computeSteps(record)


for (const step of steps) {
if (step.kind === 'rolls') {
  console.log(step.label, 'kept:', step.unchanged, 'removed:', step.removed)
}
}

formatAsMath

Section titled “formatAsMath”

Formats an array of roll values (and an optional arithmetic delta) as a readable math expression.

import { formatAsMath } from '@randsum/display-utils'


formatAsMath([3, 4, 5])       // "3 + 4 + 5"
formatAsMath([3, 4, 5], 2)    // "3 + 4 + 5 + 2"
formatAsMath([3, 4, 5], -2)   // "3 + 4 + 5 - 2"

MODIFIER_DOCS

Section titled “MODIFIER_DOCS”

A structured reference for all RANDSUM dice notation modifiers. Each key is a modifier notation symbol. Used to power modifier reference UIs like the component library’s reference panel.

Signature

Section titled “Signature”
import { MODIFIER_DOCS } from '@randsum/display-utils'
import type { ModifierDoc } from '@randsum/display-utils'


const dropDoc: ModifierDoc = MODIFIER_DOCS['L']
console.log(dropDoc.title)        // "Drop Lowest"
console.log(dropDoc.description)  // "Remove the lowest-valued dice..."
console.log(dropDoc.examples)     // [{ notation: '4d6L', description: '...' }]

ModifierDoc shape

Section titled “ModifierDoc shape”
FieldTypeDescription
`title``string`Human-readable modifier name
`description``string`What the modifier does
`displayBase``string`Primary notation symbol
`displayOptional``string | undefined`Optional parameter display
`forms``{ notation, note }[]`All valid notation forms
`comparisons``{ operator, note }[] | undefined`Comparison operators (if applicable)
`examples``{ notation, description }[]`Annotated examples

buildStackBlitzProject

Section titled “buildStackBlitzProject”

Generates a StackBlitz project configuration for a given dice notation string, for use with “Open in StackBlitz” buttons.

import { buildStackBlitzProject } from '@randsum/display-utils'


const project = buildStackBlitzProject('4d6L')
// project.title    — "RANDSUM — 4d6L"
// project.template — "node"
// project.files    — { 'index.ts': '...', 'package.json': '...' }

The notation string is safely escaped using JSON.stringify — backticks and interpolation sequences cannot corrupt the generated code.

Section titled “Links”