calculation-breakdown 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 Notable changes, starting with 0.1.0. The latest five releases are detailed here; older releases are archived.
 
+## 0.1.2 — 2026-10-26
+
+- Added an opt-in locale mode to the playground that preserves calculation edits, keeps the default example limited to the calculation, and falls back to semantic keys without generated dictionary placeholders.
+- Made the playground vertically scrollable and its three panels usable on mobile screens.
+- Fixed the deployed playground by including every browser ESM module, and kept release artifact inspection JSON-safe by suppressing duplicate package lifecycle scripts.
+
 ## 0.1.1 — 2026-10-26
 
 - Added the guarded npm, Git tag, release-PR, and GitHub Pages deployment workflow used by `payload-vars`.

package/docs/assets/calculation-breakdown/calculation-breakdown-builder.js

@@ -0,0 +1,242 @@
+import { CalculationBreakdownError } from './calculation-breakdown.error.js';
+import { toHumanString, } from './calculation-breakdown-human-string.js';
+const DECIMAL_PATTERN = /^-?(?:0|[1-9]\d*)(?:\.\d+)?$/;
+const CURRENCY_PATTERN = /^[A-Z]{3}$/;
+const DURATION_UNITS = new Set([
+    'milliseconds',
+    'seconds',
+    'minutes',
+    'hours',
+    'days',
+]);
+const ROUNDING_MODES = new Set([
+    'up',
+    'down',
+    'nearest',
+]);
+const GROUP_ROLES = new Set([
+    'detail',
+    'summary',
+]);
+const GROUP_ORIENTATIONS = new Set([
+    'horizontal',
+    'vertical',
+]);
+const OPERATORS = new Set([
+    'add',
+    'subtract',
+    'multiply',
+    'divide',
+    'minimum',
+    'maximum',
+]);
+const OPERATOR_ALIASES = {
+    sub: 'subtract',
+    mul: 'multiply',
+    div: 'divide',
+    min: 'minimum',
+    max: 'maximum',
+};
+function assertSemantic(semantic) {
+    if (semantic.trim().length === 0) {
+        throw new CalculationBreakdownError('INVALID_SEMANTIC', 'Semantic must be a non-empty string.');
+    }
+}
+function assertDecimal(value) {
+    if (!DECIMAL_PATTERN.test(value)) {
+        throw new CalculationBreakdownError('INVALID_DECIMAL', `Invalid decimal string: ${value}`);
+    }
+}
+function assertDurationOptions(options) {
+    if (!options)
+        return;
+    const hasRounding = options.rounding !== undefined;
+    const hasStep = options.step !== undefined;
+    const step = options.step;
+    if (hasRounding &&
+        !ROUNDING_MODES.has(options.rounding)) {
+        throw new CalculationBreakdownError('INVALID_ROUNDING', `Invalid rounding mode: ${String(options.rounding)}`);
+    }
+    if (hasRounding !== hasStep) {
+        throw new CalculationBreakdownError('INVALID_ROUNDING_STEP', 'Rounding and step must be provided together.');
+    }
+    if (hasStep &&
+        (step === undefined || !Number.isFinite(step) || step <= 0)) {
+        throw new CalculationBreakdownError('INVALID_ROUNDING_STEP', 'Rounding step must be a positive finite number.');
+    }
+}
+function deepFreeze(value) {
+    if (typeof value !== 'object' || value === null || Object.isFrozen(value)) {
+        return value;
+    }
+    Object.freeze(value);
+    for (const child of Object.values(value))
+        deepFreeze(child);
+    return value;
+}
+function cloneJson(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+/**
+ * Records a typed, serializable breakdown of a calculation performed elsewhere.
+ *
+ * This builder does not evaluate operations or calculate the result. The calling
+ * application supplies every value, including the authoritative result.
+ *
+ * @typeParam Semantic - String union used to label the domain meaning of values.
+ *
+ * @example
+ * ```ts
+ * const breakdown = new CalculationBreakdownBuilder<'price' | 'total'>()
+ *     .breakdown(({ money, constant, multiply }) =>
+ *         multiply(money('price', '100.00', 'USD'), constant('0.9')),
+ *     )
+ *     .result(({ money }) => money('total', '90.00', 'USD'))
+ *     .build();
+ * ```
+ */
+export class CalculationBreakdownBuilder {
+    breakdownValue;
+    resultValue;
+    nodeBuilder = {
+        money: (semantic, amount, currency) => this.createMoney(semantic, amount, currency),
+        duration: (semantic, amount, unit, options) => this.createDuration(semantic, amount, unit, options),
+        number: (semantic, value) => this.createNumber(semantic, value),
+        percent: (semantic, value) => this.createPercent(semantic, value),
+        constant: (value) => this.createConstant(value),
+        group: (expression, options) => this.createGroup(expression, options),
+        operator: (left, operator, right) => this.createOperation(left, operator, right),
+        add: (left, right) => this.createOperation(left, 'add', right),
+        subtract: (left, right) => this.createOperation(left, 'subtract', right),
+        sub: (left, right) => this.createOperation(left, 'sub', right),
+        multiply: (left, right) => this.createOperation(left, 'multiply', right),
+        mul: (left, right) => this.createOperation(left, 'mul', right),
+        divide: (left, right) => this.createOperation(left, 'divide', right),
+        div: (left, right) => this.createOperation(left, 'div', right),
+        minimum: (left, right) => this.createOperation(left, 'minimum', right),
+        min: (left, right) => this.createOperation(left, 'min', right),
+        maximum: (left, right) => this.createOperation(left, 'maximum', right),
+        max: (left, right) => this.createOperation(left, 'max', right),
+    };
+    /**
+     * Sets the root node that describes the calculation.
+     *
+     * @param create - Callback that describes the calculation using typed factories.
+     * @returns This builder for fluent chaining.
+     */
+    breakdown(create) {
+        this.breakdownValue = create(this.nodeBuilder);
+        return this;
+    }
+    /**
+     * Sets the authoritative result calculated by the calling application.
+     *
+     * @param create - Callback that constructs a money, duration, or number value.
+     * @returns This builder for fluent chaining.
+     */
+    result(create) {
+        this.resultValue = create(this.nodeBuilder);
+        return this;
+    }
+    /**
+     * Produces a detached, deeply frozen calculation breakdown.
+     *
+     * @throws {CalculationBreakdownError} If either the breakdown or result is missing.
+     */
+    build() {
+        if (!this.breakdownValue) {
+            throw new CalculationBreakdownError('MISSING_BREAKDOWN', 'A breakdown is required before building.');
+        }
+        if (!this.resultValue) {
+            throw new CalculationBreakdownError('MISSING_RESULT', 'A result is required before building.');
+        }
+        return deepFreeze(cloneJson({
+            breakdown: this.breakdownValue,
+            result: this.resultValue,
+        }));
+    }
+    /** Builds and renders the calculation using localized semantic labels. */
+    toHumanString(options) {
+        return toHumanString(this.build(), options);
+    }
+    createMoney(semantic, amount, currency) {
+        assertSemantic(semantic);
+        assertDecimal(amount);
+        if (!CURRENCY_PATTERN.test(currency)) {
+            throw new CalculationBreakdownError('INVALID_CURRENCY', `Currency must be a three-letter uppercase code: ${currency}`);
+        }
+        return deepFreeze({ type: 'money', semantic, amount, currency });
+    }
+    createDuration(semantic, amount, unit, options) {
+        assertSemantic(semantic);
+        assertDecimal(amount);
+        if (!DURATION_UNITS.has(unit)) {
+            throw new CalculationBreakdownError('INVALID_DURATION_UNIT', `Unsupported duration unit: ${unit}`);
+        }
+        assertDurationOptions(options);
+        return deepFreeze({
+            type: 'duration',
+            semantic,
+            amount,
+            unit,
+            ...(options?.rounding ? { rounding: options.rounding } : {}),
+            ...(options?.step !== undefined ? { step: options.step } : {}),
+        });
+    }
+    createNumber(semantic, value) {
+        assertSemantic(semantic);
+        assertDecimal(value);
+        return deepFreeze({ type: 'number', semantic, value });
+    }
+    createPercent(semantic, value) {
+        assertSemantic(semantic);
+        assertDecimal(value);
+        return deepFreeze({ type: 'percent', semantic, value });
+    }
+    createConstant(value) {
+        assertDecimal(value);
+        return deepFreeze({ type: 'constant', value });
+    }
+    createGroup(expression, options) {
+        if (options?.semantic !== undefined) {
+            assertSemantic(options.semantic);
+        }
+        if (options?.role !== undefined &&
+            !GROUP_ROLES.has(options.role)) {
+            throw new CalculationBreakdownError('INVALID_GROUP_ROLE', `Unsupported group role: ${String(options.role)}`);
+        }
+        if (options?.orientation !== undefined &&
+            !GROUP_ORIENTATIONS.has(options.orientation)) {
+            throw new CalculationBreakdownError('INVALID_GROUP_ORIENTATION', `Unsupported group orientation: ${String(options.orientation)}`);
+        }
+        return deepFreeze({
+            type: 'group',
+            expression,
+            ...(options?.wrap === true ? { wrap: true } : {}),
+            ...(options?.semantic !== undefined
+                ? { semantic: options.semantic }
+                : {}),
+            ...(options?.result !== undefined
+                ? { result: options.result }
+                : {}),
+            ...(options?.role !== undefined
+                ? { role: options.role }
+                : {}),
+            ...(options?.orientation !== undefined
+                ? { orientation: options.orientation }
+                : {}),
+        });
+    }
+    createOperation(left, operator, right) {
+        const normalizedOperator = OPERATOR_ALIASES[operator] ?? operator;
+        if (!OPERATORS.has(normalizedOperator)) {
+            throw new CalculationBreakdownError('INVALID_OPERATOR', `Unsupported operator: ${operator}`);
+        }
+        return deepFreeze({
+            type: 'operation',
+            operator: normalizedOperator,
+            operands: [left, right],
+        });
+    }
+}
+//# sourceMappingURL=calculation-breakdown-builder.js.map

package/docs/assets/calculation-breakdown/calculation-breakdown-human-string.js

@@ -0,0 +1,86 @@
+const INFIX_OPERATORS = {
+    add: '+',
+    subtract: '−',
+    multiply: '×',
+    divide: '÷',
+};
+function localizeDecimal(value, locale) {
+    return locale === 'cs' ? value.replace('.', ',') : value;
+}
+function decimalToPercent(value) {
+    const negative = value.startsWith('-');
+    const unsigned = negative ? value.slice(1) : value;
+    const [whole = '0', fraction = ''] = unsigned.split('.');
+    const digits = `${whole}${fraction}`;
+    const decimalIndex = whole.length + 2;
+    const padded = digits.padEnd(decimalIndex, '0');
+    const integer = padded
+        .slice(0, decimalIndex)
+        .replace(/^0+(?=\d)/, '');
+    const decimals = padded.slice(decimalIndex).replace(/0+$/, '');
+    return `${negative ? '-' : ''}${integer}${decimals ? `.${decimals}` : ''}`;
+}
+function localizeDurationUnit(amount, unit, locale) {
+    const singularUnit = unit.slice(0, -1);
+    const unitPart = new Intl.NumberFormat(locale, {
+        style: 'unit',
+        unit: singularUnit,
+        unitDisplay: 'long',
+        useGrouping: false,
+    })
+        .formatToParts(Number(amount))
+        .find((part) => part.type === 'unit');
+    if (!unitPart) {
+        throw new Error(`Unable to localize duration unit: ${unit}`);
+    }
+    return unitPart.value;
+}
+function labelValue(value, semantic, options) {
+    if (options.includeNames === false)
+        return value;
+    const entry = options.dictionary[options.locale]?.[semantic];
+    const label = typeof entry === 'string' ? entry : (entry?.name ?? semantic);
+    return `${value} ${label}`;
+}
+function renderValue(value, options) {
+    const rawDecimal = value.type === 'number' || value.type === 'percent'
+        ? value.value
+        : value.amount;
+    const decimal = localizeDecimal(rawDecimal, options.locale);
+    if (value.type === 'money') {
+        return labelValue(`${decimal} ${value.currency}`, value.semantic, options);
+    }
+    if (value.type === 'duration') {
+        return labelValue(`${decimal} ${localizeDurationUnit(value.amount, value.unit, options.locale)}`, value.semantic, options);
+    }
+    if (value.type === 'percent') {
+        return labelValue(`${localizeDecimal(decimalToPercent(value.value), options.locale)}%`, value.semantic, options);
+    }
+    return labelValue(decimal, value.semantic, options);
+}
+function renderNode(node, options, nested = false) {
+    if (node.type === 'constant') {
+        return localizeDecimal(node.value, options.locale);
+    }
+    if (node.type === 'group') {
+        const result = node.result
+            ? ` = ${renderValue(node.result, options)}`
+            : '';
+        return `(${renderNode(node.expression, options)}${result})`;
+    }
+    if (node.type !== 'operation') {
+        return renderValue(node, options);
+    }
+    const [left, right] = node.operands;
+    if (node.operator === 'minimum' || node.operator === 'maximum') {
+        const functionName = node.operator === 'minimum' ? 'min' : 'max';
+        return `${functionName}(${renderNode(left, options)}, ${renderNode(right, options)})`;
+    }
+    const rendered = `${renderNode(left, options, true)} ${INFIX_OPERATORS[node.operator]} ${renderNode(right, options, true)}`;
+    return nested ? `(${rendered})` : rendered;
+}
+/** Renders a plain calculation breakdown without changing its serialized form. */
+export function toHumanString(calculation, options) {
+    return `${renderNode(calculation.breakdown, options)} = ${renderValue(calculation.result, options)}`;
+}
+//# sourceMappingURL=calculation-breakdown-human-string.js.map

package/docs/assets/calculation-breakdown/calculation-breakdown.error.js

@@ -0,0 +1,16 @@
+/** Error thrown when a calculation breakdown contains invalid or incomplete input. */
+export class CalculationBreakdownError extends Error {
+    code;
+    /**
+     * Creates a calculation breakdown error.
+     *
+     * @param code - Stable code suitable for programmatic error handling.
+     * @param message - Human-readable explanation of the failure.
+     */
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'CalculationBreakdownError';
+    }
+}
+//# sourceMappingURL=calculation-breakdown.error.js.map

package/docs/assets/calculation-breakdown/calculation-breakdown.interface.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=calculation-breakdown.interface.js.map

package/docs/assets/calculation-breakdown/calculation-breakdown.type.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=calculation-breakdown.type.js.map

package/docs/changelog.md

@@ -8,6 +8,12 @@ title: Changelog
 
 Notable changes, starting with 0.1.0. The latest five releases are detailed here; older releases are archived.
 
+## 0.1.2 — 2026-10-26
+
+- Added an opt-in locale mode to the playground that preserves calculation edits, keeps the default example limited to the calculation, and falls back to semantic keys without generated dictionary placeholders.
+- Made the playground vertically scrollable and its three panels usable on mobile screens.
+- Fixed the deployed playground by including every browser ESM module, and kept release artifact inspection JSON-safe by suppressing duplicate package lifecycle scripts.
+
 ## 0.1.1 — 2026-10-26
 
 - Added the guarded npm, Git tag, release-PR, and GitHub Pages deployment workflow used by `payload-vars`.

package/docs/index.md

@@ -6,7 +6,7 @@ title: calculation-breakdown
 
 # calculation-breakdown
 
-Package version: v0.1.1
+Package version: v0.1.2
 
 Typed, serializable breakdowns of calculations performed elsewhere.
 

package/docs/playground/index.html

@@ -17,6 +17,10 @@
                 <span class="badge">playground</span>
             </div>
             <div class="actions">
+                <label class="option-control">
+                    <input id="use-locale" type="checkbox" />
+                    <span>Use locale</span>
+                </label>
                 <button id="reset" class="button button-secondary" type="button">
                     Reset
                 </button>

package/docs/playground/playground.css

@@ -67,6 +67,22 @@ body {
 
 .locale-control { color: var(--muted); font-size: 12px; }
 
+.option-control {
+    display: inline-flex;
+    align-items: center;
+    gap: 7px;
+    color: var(--muted);
+    font-size: 12px;
+    cursor: pointer;
+}
+
+.option-control input {
+    width: 15px;
+    height: 15px;
+    margin: 0;
+    accent-color: var(--accent);
+}
+
 select,
 .button {
     height: 36px;
@@ -274,6 +290,8 @@ textarea:focus { box-shadow: inset 0 0 0 1px #596927; }
     background: #e9ecdf;
 }
 
+.language-switcher[hidden] { display: none; }
+
 .view-switcher {
     grid-template-columns: repeat(3, 1fr);
 }
@@ -363,12 +381,27 @@ textarea:focus { box-shadow: inset 0 0 0 1px #596927; }
 }
 
 @media (max-width: 650px) {
+    html,
+    body {
+        height: auto;
+        min-height: 100%;
+        overflow-x: hidden;
+        overflow-y: auto;
+        -webkit-overflow-scrolling: touch;
+    }
+
     .topbar { align-items: flex-start; flex-direction: column; }
     .actions { width: 100%; flex-wrap: wrap; }
     .workspace {
+        flex: none;
         grid-template-columns: 1fr;
-        grid-template-rows: repeat(3, minmax(0, 1fr));
+        grid-template-rows: none;
+        grid-auto-rows: max(560px, 80dvh);
     }
     .preview-panel { grid-column: auto; }
-    .panel { border-right: 0; border-bottom: 1px solid var(--line); }
+    .panel {
+        min-height: 560px;
+        border-right: 0;
+        border-bottom: 1px solid var(--line);
+    }
 }

package/docs/playground/playground.js

@@ -3,7 +3,7 @@ import {
     toHumanString,
 } from '../assets/calculation-breakdown/index.js';
 
-const DEFAULT_BUILDER = `// Derive calendar-day counts in UTC to avoid daylight-saving offsets.
+const DEFAULT_BUILDER_WITH_LOCALE = `// Derive calendar-day counts in UTC to avoid daylight-saving offsets.
 const helper = {
   now: new Date(),
   get year() { return this.now.getFullYear(); },
@@ -179,6 +179,35 @@ return {
   dictionary, // Optional: comment out this line to use semantic keys directly.
 };`;
 
+const localeMetadataStart = DEFAULT_BUILDER_WITH_LOCALE.indexOf(
+    '\n// Optional localized title',
+);
+const DEFAULT_BUILDER_CORE = DEFAULT_BUILDER_WITH_LOCALE.slice(
+    0,
+    localeMetadataStart,
+);
+const DEFAULT_LOCALE_METADATA = DEFAULT_BUILDER_WITH_LOCALE.slice(
+    localeMetadataStart,
+);
+const DEFAULT_MINIMAL_EXPORT = `
+
+// Export only the calculation; renderers fall back to its semantic keys.
+return { calculation: invoice };`;
+const DEFAULT_BUILDER = `${DEFAULT_BUILDER_CORE}${DEFAULT_MINIMAL_EXPORT}`;
+
+function setBuilderLocaleMode(source, useLocale) {
+    const localizedStart = source.indexOf('\n// Optional localized title');
+    const hasMinimalExport = source.endsWith(DEFAULT_MINIMAL_EXPORT);
+    const core = localizedStart >= 0
+        ? source.slice(0, localizedStart)
+        : hasMinimalExport
+            ? source.slice(0, -DEFAULT_MINIMAL_EXPORT.length)
+            : source;
+
+    if (localizedStart < 0 && !hasMinimalExport) return source;
+    return `${core}${useLocale ? DEFAULT_LOCALE_METADATA : DEFAULT_MINIMAL_EXPORT}`;
+}
+
 const DEFAULT_CSS = `.calculation-card__expression {
   font: 650 14px/1.45 Inter, system-ui, sans-serif;
   white-space: nowrap;
@@ -325,6 +354,7 @@ const elements = {
     status: document.querySelector('#status'),
     run: document.querySelector('#run'),
     reset: document.querySelector('#reset'),
+    useLocale: document.querySelector('#use-locale'),
 };
 
 let updateTimer;
@@ -1114,10 +1144,16 @@ function render() {
         hideTooltip();
         const output = evaluateBuilder(elements.builder.value);
         const locale = selectedLocale;
-        const dictionary = output.dictionary ?? {};
+        const useLocale = elements.useLocale.checked;
+        const dictionary = useLocale ? output.dictionary ?? {} : {};
+        const hasLocalization = useLocale && Boolean(
+            output.title || output.dictionary,
+        );
         const examples = output.examples ?? [
             {
-                title: output.title ?? { en: 'Calculation', cs: 'Výpočet' },
+                title: useLocale
+                    ? output.title ?? { en: 'Calculation', cs: 'Výpočet' }
+                    : undefined,
                 calculation: output.calculation,
             },
         ];
@@ -1128,6 +1164,10 @@ function render() {
             const fragment = elements.template.content.cloneNode(true);
             const calculation = example.calculation;
             const entries = createSemanticEntries(output, calculation, locale);
+            const languageSwitcher = fragment.querySelector(
+                '.language-switcher',
+            );
+            languageSwitcher.hidden = !hasLocalization;
 
             for (const button of fragment.querySelectorAll('[data-locale]')) {
                 const isActive = button.dataset.locale === locale;
@@ -1170,7 +1210,9 @@ function render() {
             fragment.querySelector('[data-result-type]').textContent =
                 calculation.result.type;
             const includeNames = selectedView === 'formula-names';
-            const command = `toHumanString(calculation, { locale: '${locale}', dictionary, includeNames: ${includeNames} })`;
+            const command = useLocale
+                ? `toHumanString(calculation, { locale: '${locale}', dictionary, includeNames: ${includeNames} })`
+                : `toHumanString(calculation, { includeNames: ${includeNames} })`;
             const commandElement = fragment.querySelector('[data-command]');
             commandElement.hidden = selectedView === 'table';
             commandElement.innerHTML = highlight(
@@ -1214,6 +1256,7 @@ function scheduleRender() {
 }
 
 function reset() {
+    elements.useLocale.checked = false;
     elements.builder.value = DEFAULT_BUILDER;
     elements.css.value = DEFAULT_CSS;
     selectedLocale = 'en';
@@ -1245,6 +1288,15 @@ for (const editor of [elements.builder, elements.css]) {
 
 elements.run.addEventListener('click', render);
 elements.reset.addEventListener('click', reset);
+elements.useLocale.addEventListener('change', () => {
+    selectedLocale = 'en';
+    elements.builder.value = setBuilderLocaleMode(
+        elements.builder.value,
+        elements.useLocale.checked,
+    );
+    updateHighlights();
+    render();
+});
 elements.preview.addEventListener('scroll', hideTooltip, { passive: true });
 window.addEventListener('resize', hideTooltip, { passive: true });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "calculation-breakdown",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Typed, serializable breakdowns of calculations performed by financial and billing systems",
   "type": "module",
   "license": "MIT",