calculation-breakdown 0.0.0-stage → 0.1.2

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/assets/calculation-breakdown/index.js

@@ -0,0 +1,4 @@
+export { CalculationBreakdownBuilder } from './calculation-breakdown-builder.js';
+export { toHumanString, } from './calculation-breakdown-human-string.js';
+export { CalculationBreakdownError, } from './calculation-breakdown.error.js';
+//# sourceMappingURL=index.js.map

package/docs/changelog-archive.md

@@ -0,0 +1,9 @@
+---
+title: Changelog archive
+---
+
+<!-- Generated from CHANGELOG-ARCHIVE.md. Do not edit directly. -->
+
+# Changelog archive
+
+Full notes for older releases. See the [changelog](CHANGELOG.md) for current releases.

package/docs/changelog.md

@@ -0,0 +1,25 @@
+---
+title: Changelog
+---
+
+<!-- Generated from CHANGELOG.md. Do not edit directly. -->
+
+# 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`.
+
+## 0.1.0 — 2026-10-26
+
+### Added
+
+- Added the typed calculation breakdown builder, localized human-readable formatter, and interactive invoice playground.

package/docs/index.md

@@ -0,0 +1,13 @@
+---
+title: calculation-breakdown
+---
+
+<!-- Generated by scripts/lib/docs.mjs. Do not edit directly. -->
+
+# calculation-breakdown
+
+Package version: v0.1.2
+
+Typed, serializable breakdowns of calculations performed elsewhere.
+
+[Open the playground](playground/) · [Read the README](https://github.com/ThisMeansMore/calculation-breakdown#readme) · [Changelog](changelog.html)

package/docs/playground/index.html

@@ -0,0 +1,110 @@
+<!doctype html>
+<html lang="en">
+    <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <meta
+            name="description"
+            content="An interactive calculation-breakdown builder playground."
+        />
+        <title>calculation-breakdown playground</title>
+        <link rel="stylesheet" href="./playground.css" />
+    </head>
+    <body>
+        <header class="topbar">
+            <div>
+                <a class="brand" href="../README.md">calculation-breakdown</a>
+                <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>
+                <button id="run" class="button" type="button">
+                    <span aria-hidden="true">▶</span> Run
+                </button>
+            </div>
+        </header>
+
+        <main class="workspace">
+            <section class="panel editor-panel" aria-labelledby="builder-heading">
+                <div class="panel-heading">
+                    <div>
+                        <span class="step">01</span>
+                        <h1 id="builder-heading">Builder</h1>
+                    </div>
+                    <span>TypeScript</span>
+                </div>
+                <div class="code-editor">
+                    <pre id="builder-highlight" class="code-highlight" aria-hidden="true"></pre>
+                    <textarea id="builder" wrap="off" spellcheck="false" aria-label="Builder TypeScript"></textarea>
+                </div>
+            </section>
+
+            <section class="panel editor-panel" aria-labelledby="css-heading">
+                <div class="panel-heading">
+                    <div>
+                        <span class="step">02</span>
+                        <h2 id="css-heading">Formula CSS</h2>
+                    </div>
+                    <span>Package rendering only</span>
+                </div>
+                <div class="code-editor">
+                    <pre id="css-highlight" class="code-highlight" aria-hidden="true"></pre>
+                    <textarea id="css" spellcheck="false" aria-label="Preview CSS"></textarea>
+                </div>
+            </section>
+
+            <section class="panel preview-panel" aria-labelledby="preview-heading">
+                <div class="panel-heading">
+                    <div>
+                        <span class="step">03</span>
+                        <h2 id="preview-heading">UI preview</h2>
+                    </div>
+                    <div class="panel-heading-meta">
+                        <span>Headless package · demo visualization only</span>
+                        <span id="status" role="status">Ready</span>
+                    </div>
+                </div>
+                <div id="preview" class="preview-stage"></div>
+            </section>
+        </main>
+
+        <template id="preview-template">
+            <article class="calculation-card">
+                <div class="calculation-card__header">
+                    <div class="calculation-card__eyebrow" data-title>Calculation</div>
+                    <div class="language-switcher" role="group" aria-label="Preview language">
+                        <button type="button" data-locale="en" aria-pressed="true">EN</button>
+                        <button type="button" data-locale="cs" aria-pressed="false">CS</button>
+                    </div>
+                </div>
+                <div class="card-controls">
+                    <div class="view-switcher" role="group" aria-label="Preview format">
+                        <button type="button" data-view="table" aria-pressed="true">Table</button>
+                        <button type="button" data-view="formula" aria-pressed="false">Formula</button>
+                        <button type="button" data-view="formula-names" aria-pressed="false">Formula with names</button>
+                    </div>
+                </div>
+                <code class="calculation-card__command" data-command></code>
+                <div class="calculation-card__expression" data-expression></div>
+                <dl class="calculation-card__meta">
+                    <div>
+                        <dt>Result type</dt>
+                        <dd data-result-type></dd>
+                    </div>
+                </dl>
+                <details class="calculation-card__json">
+                    <summary>Serialized breakdown</summary>
+                    <pre data-json></pre>
+                </details>
+            </article>
+        </template>
+
+        <script type="module" src="./playground.js"></script>
+    </body>
+</html>

package/docs/playground/playground.css

@@ -0,0 +1,407 @@
+:root {
+    color-scheme: dark;
+    --canvas: #11110f;
+    --panel: #191916;
+    --panel-raised: #20201c;
+    --line: #35352e;
+    --muted: #96968a;
+    --text: #f3f1e8;
+    --accent: #d9ff57;
+    --danger: #ff806d;
+    font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont,
+        "Segoe UI", sans-serif;
+}
+
+* { box-sizing: border-box; }
+
+html,
+body {
+    height: 100%;
+    overflow: hidden;
+}
+
+body {
+    margin: 0;
+    display: flex;
+    flex-direction: column;
+    background: var(--canvas);
+    color: var(--text);
+}
+
+.topbar {
+    flex: 0 0 auto;
+    min-height: 68px;
+    padding: 12px 18px;
+    border-bottom: 1px solid var(--line);
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 20px;
+}
+
+.brand {
+    color: var(--text);
+    font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+    font-size: 15px;
+    font-weight: 700;
+    text-decoration: none;
+}
+
+.badge {
+    margin-left: 10px;
+    padding: 3px 7px;
+    border: 1px solid #55651f;
+    border-radius: 999px;
+    color: var(--accent);
+    font-size: 11px;
+    text-transform: uppercase;
+    letter-spacing: .08em;
+}
+
+.actions,
+.locale-control {
+    display: flex;
+    align-items: center;
+    gap: 9px;
+}
+
+.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;
+    border: 1px solid var(--line);
+    border-radius: 7px;
+    font: inherit;
+}
+
+select {
+    padding: 0 30px 0 10px;
+    background: var(--panel);
+    color: var(--text);
+}
+
+.button {
+    padding: 0 14px;
+    background: var(--accent);
+    color: #181a0c;
+    font-size: 13px;
+    font-weight: 750;
+    cursor: pointer;
+}
+
+.button:hover { filter: brightness(1.08); }
+.button-secondary { background: transparent; color: var(--text); }
+
+.workspace {
+    flex: 1;
+    min-height: 0;
+    display: grid;
+    grid-template-columns: minmax(280px, .92fr) minmax(260px, .72fr) minmax(360px, 1.25fr);
+}
+
+.panel {
+    min-width: 0;
+    min-height: 0;
+    overflow: hidden;
+    display: flex;
+    flex-direction: column;
+    border-right: 1px solid var(--line);
+}
+
+.panel:last-child { border-right: 0; }
+
+.panel-heading {
+    min-height: 50px;
+    padding: 0 14px;
+    border-bottom: 1px solid var(--line);
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 12px;
+    color: var(--muted);
+    font-size: 11px;
+    letter-spacing: .04em;
+}
+
+.panel-heading > div { display: flex; align-items: center; gap: 9px; }
+.panel-heading-meta { justify-content: flex-end; text-align: right; }
+.panel-heading h1, .panel-heading h2 { margin: 0; color: var(--text); font-size: 13px; }
+.step { color: var(--accent); font-family: ui-monospace, monospace; }
+
+.code-editor {
+    position: relative;
+    flex: 1;
+    min-height: 0;
+    overflow: hidden;
+    background: var(--panel);
+}
+
+textarea,
+.code-highlight {
+    position: absolute;
+    inset: 0;
+    width: 100%;
+    height: 100%;
+    margin: 0;
+    resize: none;
+    border: 0;
+    outline: 0;
+    padding: 18px;
+    overflow: auto;
+    white-space: pre;
+    overflow-wrap: normal;
+    font: 13px/21px Menlo, Monaco, Consolas, "Liberation Mono", monospace;
+    font-synthesis: none;
+    font-variant-ligatures: none;
+    letter-spacing: 0;
+    word-spacing: 0;
+    text-indent: 0;
+    tab-size: 2;
+}
+
+.code-highlight {
+    pointer-events: none;
+    overflow: hidden;
+    color: #d7d7c8;
+}
+
+#builder {
+    overflow-x: scroll;
+    overflow-y: auto;
+}
+
+textarea {
+    z-index: 1;
+    background: transparent;
+    color: transparent;
+    -webkit-text-fill-color: transparent;
+    caret-color: var(--accent);
+}
+
+textarea::selection {
+    background: rgba(123, 148, 54, .42);
+    -webkit-text-fill-color: transparent;
+}
+
+textarea:focus { box-shadow: inset 0 0 0 1px #596927; }
+
+.code-editor:focus-within .code-highlight {
+    visibility: hidden;
+}
+
+.code-editor textarea:focus {
+    color: #d7d7c8;
+    -webkit-text-fill-color: #d7d7c8;
+}
+
+.token-comment { color: #707568; }
+.token-keyword, .token-atrule { color: #d780f5; }
+.token-string { color: #b7d77a; }
+.token-number, .token-color { color: #f2a65a; }
+.token-function { color: #78c7f2; }
+.token-property { color: #7bd8c4; }
+.token-selector { color: #f1d17b; }
+.preview-panel { background: #151513; }
+
+.preview-stage {
+    flex: 1;
+    min-height: 0;
+    padding: clamp(20px, 4vw, 54px);
+    display: grid;
+    place-items: start center;
+    overflow-x: hidden;
+    overflow-y: auto;
+    background-image: radial-gradient(#34342e 1px, transparent 1px);
+    background-size: 18px 18px;
+}
+
+.preview-list {
+    width: min(100%, 620px);
+    min-width: 0;
+    display: grid;
+    gap: 24px;
+}
+
+.calculation-card {
+    position: relative;
+    width: min(100%, 560px);
+    min-width: 0;
+    justify-self: center;
+    overflow-x: auto;
+    overflow-y: hidden;
+    padding: 30px;
+    border: 1px solid #d9dfc2;
+    border-radius: 18px;
+    background: #f7f8f1;
+    color: #1c2114;
+    box-shadow: 0 28px 70px rgba(0, 0, 0, .32);
+    font-family: Inter, system-ui, sans-serif;
+}
+
+.calculation-card__header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 16px;
+    margin-bottom: 14px;
+}
+
+.calculation-card__eyebrow {
+    margin: 0;
+    color: #637236;
+    font-size: 11px;
+    font-weight: 800;
+    letter-spacing: .12em;
+    text-transform: uppercase;
+}
+
+.card-controls {
+    display: flex;
+    align-items: center;
+    justify-content: flex-start;
+    gap: 9px;
+    margin-bottom: 18px;
+}
+
+.language-switcher,
+.view-switcher {
+    display: grid;
+    grid-template-columns: 1fr 1fr;
+    padding: 3px;
+    border: 1px solid #d4d9c5;
+    border-radius: 999px;
+    background: #e9ecdf;
+}
+
+.language-switcher[hidden] { display: none; }
+
+.view-switcher {
+    grid-template-columns: repeat(3, 1fr);
+}
+
+.language-switcher button,
+.view-switcher button {
+    min-width: 34px;
+    padding: 5px 8px;
+    border: 0;
+    border-radius: 999px;
+    background: transparent;
+    color: #747966;
+    font: 800 10px/1 ui-monospace, monospace;
+    cursor: pointer;
+}
+
+.language-switcher button[aria-pressed="true"],
+.view-switcher button[aria-pressed="true"] {
+    background: #1c2114;
+    color: #f7f8f1;
+}
+
+.calculation-card__meta {
+    display: grid;
+    grid-template-columns: 1fr;
+    gap: 12px;
+    margin: 26px 0 0;
+}
+
+.calculation-card__meta div {
+    padding-top: 12px;
+    border-top: 1px solid #d9dfc2;
+}
+
+.calculation-card__meta dt {
+    color: #6b705f;
+    font-size: 11px;
+    text-transform: uppercase;
+}
+
+.calculation-card__meta dd {
+    margin: 5px 0 0;
+    font: 600 13px ui-monospace, monospace;
+}
+
+.calculation-card__command {
+    display: block;
+    margin-bottom: 14px;
+    color: #6b705f;
+    font: 11px/1.5 ui-monospace, monospace;
+    white-space: nowrap;
+}
+
+.calculation-card__command[hidden] { display: none; }
+
+.calculation-card__json { margin-top: 24px; }
+.calculation-card__json summary { cursor: pointer; font-size: 13px; }
+.calculation-card__json pre {
+    max-height: 240px;
+    overflow: auto;
+    padding: 14px;
+    border-radius: 9px;
+    background: #e9ecdf;
+    font: 11px/1.5 ui-monospace, monospace;
+}
+
+.preview-error {
+    width: min(100%, 560px);
+    padding: 18px;
+    border: 1px solid #693b33;
+    border-radius: 10px;
+    background: #291b18;
+    color: var(--danger);
+    font: 13px/1.55 ui-monospace, monospace;
+    white-space: pre-wrap;
+}
+
+#status[data-state="error"] { color: var(--danger); }
+#status[data-state="success"] { color: var(--accent); }
+
+@media (max-width: 980px) {
+    .workspace {
+        grid-template-columns: 1fr 1fr;
+        grid-template-rows: repeat(2, minmax(0, 1fr));
+    }
+    .preview-panel { grid-column: 1 / -1; }
+}
+
+@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: none;
+        grid-auto-rows: max(560px, 80dvh);
+    }
+    .preview-panel { grid-column: auto; }
+    .panel {
+        min-height: 560px;
+        border-right: 0;
+        border-bottom: 1px solid var(--line);
+    }
+}