Add Temporal-style Decimal documentation and cookbook

[jessealama]

As the Decimal proposal reaches a steady stage in its data model, API design, and reason for existing, it seemed valuable to me to create a cookbook, folllowing the example of Temporal.

[Copilot]

Pull Request Overview

Adds comprehensive Decimal documentation and examples, including a cookbook, API tests, and a docs build pipeline.

• Introduces new scripts in package.json for testing and building docs
• Adds markdown docs (why-decimal.md, cookbook.md, etc.) and HTML templates
• Implements test runners and a build script (testExamples.*, buildDocs.js)

Reviewed Changes

Copilot reviewed 14 out of 16 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
package.json	Added docs/test scripts and proposal-decimal dependency
index.html	Updated spec container date and unintentionally duplicated menu HTML
docs/why-decimal.md	New introduction doc explaining Decimal motivation
docs/index.md	New landing page with links to docs and cookbook
docs/cookbook.md	New cookbook with usage examples
docs/testExamples.mjs	Test runner for code blocks in markdown (ESM)
docs/testExamples.js	Test runner for code blocks in markdown (CJS)
docs/test-api.mjs	Basic API smoke tests
docs/head.html.part	HTML header template
docs/tail.html.part	HTML footer template
docs/buildDocs.js	Markdown-to-HTML build script
docs/.gitignore	Ignored docs output and node_modules

Comments suppressed due to low confidence (2)

index.html:3234

• The navigation menu HTML appears twice, causing duplicate menus on the page. Please remove the redundant block inserted at this location.

    </svg></div><div id="menu-spacer" class="menu-spacer"></div><div id="menu"><div id="menu-search"><input type="text" id="menu-search-box" placeholder="Search..."><div id="menu-search-results" class="inactive"></div></div><div id="menu-pins"><div class="menu-pane-header">Pins<button class="unpin-all">clear</button></div><ul id="menu-pins-list"></ul></div><div class="menu-pane-header">Table of Contents</div><div id="menu-toc"><ol class="toc"><li><span class="item-toggle-none"></span><a href="#sec-decimal-intro-" title="Introduction">Introduction</a></li><li><span class="item-toggle">+</span><a href="#sec-the-decimal-object" title="The Decimal Object"><span class="secnum">1</span> The Decimal Object</a><ol class="toc"><li><span class="item-toggle-none"></span><a href="#sec-decimal-intro" title="Introduction">Introduction</a></li><li><span class="item-toggle">+</span><a href="#sec-decimal-abstract-ops" title="Abstract Operations"><span class="secnum">1.1</span> Abstract Operations</a><ol class="toc"><li><span class="item-toggle-none"></span><a href="#sec-decimal-roundtodecimaldomain" title="RoundToDecimalDomain ( v [ , roundingMode ] )"><span class="secnum">1.1.1</span> RoundToDecimalDomain ( <var>v</var> [ , <var>roundingMode</var> ] )</a></li><li><span class="item-toggle-none"></span><a href="#sec-decimal-applyroundingmodetopositive" title="ApplyRoundingModeToPositive ( m, roundingMode )"><span class="secnum">1.1.2</span> ApplyRoundingModeToPositive ( <var>m</var>, <var>roundingMode</var> )</a></li><li><span class="item-toggle-none"></span><a href="#sec-decimal-abs" title="DecimalAbs ( argument )"><span class="secnum">1.1.3</span> DecimalAbs ( <var>argument</var> )</a></li><li><span class="item-toggle-none"></span><a href="#sec-decimal-negate" title="DecimalNegate ( argument )"><span class="secnum">1.1.4</span> DecimalNegate ( <var>argument</var> )</a></li><li><span class="item-toggle-none"></span><a href="#sec-decimal-canonicalizedecimalstring" title="CanonicalizeDecimalString ( digits )"><span class="secnum">1.1.5</span> CanonicalizeDecimalString ( <var>digits</var> )</a></li><li><span class="item-toggle-none"></span><a href="#sec-decimal-decimaltodecimalstring" title="DecimalToDecimalString ( argument )"><span class="secnum">1.1.6</span> DecimalToDecimalString ( <var>argument</var> )</a></li><li><span class="item-toggle-none"></span><a href="#sec-decimaltoexponentialstring" title="DecimalToExponentialString ( argument )"><span class="secnum">1.1.7</span> DecimalToExponentialString ( <var>argument</var> )</a></li><li><span class="item-toggle-none"></span><a href="#sec-decimal-value-to-object" title="DecimalValueToObject ( argument )"><span class="secnum">1.1.8</span> DecimalValueToObject ( <var>argument</var> )</a></li></ol></li><li><span class="item-toggle">+</span><a href="#sec-the-decimal-constructor" title="The Decimal Constructor"><span class="secnum">1.2</span> The Decimal Constructor</a><ol class="toc"><li><span class="item-toggle">+</span><a href="#sec-the-decimal-constructor-value" title="Decimal ( x )"><span class="secnum">1.2.1</span> Decimal ( <var>x</var> )</a><ol class="toc"><li><span class="item-toggle-none"></span><a href="#sec-runtime-semantics-stringdecimalvalue" title="Runtime Semantics: StringDecimalValue"><span class="secnum">1.2.1.1</span> RS: StringDecimalValue</a></li></ol></li><li><span class="item-toggle">+</span><a href="#sec-the-decimal-amount-object" title="The Decimal.Amount Object"><span class="secnum">1.2.2</span> The Decimal.Amount Object</a><ol class="toc"><li><span class="item-toggle-none"></span><a href="#sec-decimal-amount-intro" title="Introduction">Introduction</a></li><li><span class="item-toggle">+</span><a href="#sec-decimal-amount-abstract-ops" title="Abstract Operations"><span class="secnum">1.2.2.1</span> Abstract Operations</a><ol class="toc"><li><span class="item-toggle-none"></span><a href="#sec-decimal-amount-create-decimal-armount" title="CreateDecimalAmount ( value, digits )"><span class="secnum">1.2.2.1.1</span> CreateDecimalAmount ( <var>value</var>, <var>digits</var> )</a></li></ol></li><li><span class="item-toggle">+</span><a href="#sec-the-decimal-amount-constructor" title="The Decimal.Amount Constructor"><span class="secnum">1.2.2.2</span> The Decimal.Amount Constructor</a><ol class="toc"><li><span class="item-toggle-none"></span><a href="#sec-the-decimal-amount-constructor-value" title="Decimal.Amount ( s, precision )"><span class="secnum">1.2.2.2.1</span> Decimal.Amount ( <var>s</var>, <var>precision</var> )</a></li></ol></li></ol></li></ol></li></ol></li><li><span class="item-toggle">+</span><a href="#sec-decimal-prototype-properties" title="Properties of the Decimal Prototype"><span class="secnum">2</span> Properties of the Decimal Prototype</a><ol class="toc"><li><span class="item-toggle-none"></span><a href="#sec-decimal.prototype.isnan" title="Decimal.prototype.isNaN ( )"><span class="secnum">2.1</span> Decimal.prototype.isNaN ( )</a></li><li><span class="item-toggle-none"></span><a href="#sec-decimal.prototype.isfinite" title="Decimal.prototype.isFinite ( )"><span class="secnum">2.2</span> Decimal.prototype.isFinite ( )</a></li><li><span class="item-toggle-none"></span><a href="#sec-decimal.prototype.exponent" title="Decimal.prototype.exponent ( )"><span class="secnum">2.3</span> Decimal.prototype.exponent ( )</a></li><li><span class="item-toggle-none"></span><a href="#sec-decimal.prototype.mantissa" title="Decimal.prototype.mantissa ( )"><span class="secnum">2.4</span> Decimal.prototype.mantissa ( )</a></li><li><span class="item-toggle-none"></span><a href="#sec-decimal.prototype.abs" title="Decimal.prototype.abs ( )"><span class="secnum">2.5</span> Decimal.prototype.abs ( )</a></li><li><span class="item-toggle-none"></span><a href="#sec-decimal.prototype.negate" title="Decimal.prototype.negate ( )"><span class="secnum">2.6</span> Decimal.prototype.negate ( )</a></li><li><span class="item-toggle-none"></span><a href="#sec-decimal.prototype.add" title="Decimal.prototype.add ( x )"><span class="secnum">2.7</span> Decimal.prototype.add ( <var>x</var> )</a></li><li><span class="item-toggle-none"></span><a href="#sec-decimal.prototype.subtract" title="Decimal.prototype.subtract ( x )"><span class="secnum">2.8</span> Decimal.prototype.subtract ( <var>x</var> )</a></li><li><span class="item-toggle-none"></span><a href="#sec-decimal.prototype.multiply" title="Decimal.prototype.multiply ( x )"><span class="secnum">2.9</span> Decimal.prototype.multiply ( <var>x</var> )</a></li><li><span class="item-toggle-none"></span><a href="#sec-decimal.prototype.divide" title="Decimal.prototype.divide ( x )"><span class="secnum">2.10</span> Decimal.prototype.divide ( <var>x</var> )</a></li><li><span class="item-toggle-none"></span><a href="#sec-decimal.prototype.remainder" title="Decimal.prototype.remainder ( x )"><span class="secnum">2.11</span> Decimal.prototype.remainder ( <var>x</var> )</a></li><li><span class="item-toggle-none"></span><a href="#sec-decimal.prototype.compare" title="Decimal.prototype.compare ( x )"><span class="secnum">2.12</span> Decimal.prototype.compare ( <var>x</var> )</a></li><li><span class="item-toggle-none"></span><a href="#sec-decimal.prototype.equals" title="Decimal.prototype.equals ( x )"><span class="secnum">2.13</span> Decimal.prototype.equals ( <var>x</var> )</a></li><li><span class="item-toggle-none"></span><a href="#sec-decimal.prototype.notequals" title="Decimal.prototype.notEquals ( x )"><span class="secnum">2.14</span> Decimal.prototype.notEquals ( <var>x</var> )</a></li><li><span class="item-toggle-none"></span><a href="#sec-decimal.prototype.lessthan" title="Decimal.prototype.lessThan ( x )"><span class="secnum">2.15</span> Decimal.prototype.lessThan ( <var>x</var> )</a></li><li><span class="item-toggle-none"></span><a href="#sec-decimal.prototype.lessthanorequal" title="Decimal.prototype.lessThanOrEqual ( x )"><span class="secnum">2.16</span> Decimal.prototype.lessThanOrEqual ( <var>x</var> )</a></li><li><span class="item-toggle-none"></span><a href="#sec-decimal.prototype.greaterthan" title="Decimal.prototype.greaterThan ( x )"><span class="secnum">2.17</span> Decimal.prototype.greaterThan ( <var>x</var> )</a></li><li><span class="item-toggle-none"></span><a href="#sec-decimal.prototype.greaterthanorequal" title="Decimal.prototype.greaterThanOrEqual ( x )"><span class="secnum">2.18</span> Decimal.prototype.greaterThanOrEqual ( <var>x</var> )</a></li><li><span class="item-toggle-none"></span><a href="#sec-decimal-method-round" title="Decimal.prototype.round ( numFractionalDigits [ , roundingMode ] )"><span class="secnum">2.19</span> Decimal.prototype.round ( <var>numFractionalDigits</var> [ , <var>roundingMode</var> ] )</a></li><li><span class="item-toggle-none"></span><a href="#sec-decimal-method-scale10" title="Decimal.prototype.scale10 ( n )"><span class="secnum">2.20</span> Decimal.prototype.scale10 ( <var>n</var> )</a></li><li><span class="item-toggle-none"></span><a href="#sec-decimal.prototype.tostring" title="Decimal.prototype.toString ( [ options ] )"><span class="secnum">2.21</span> Decimal.prototype.toString ( [ <var>options</var> ] )</a></li><li><span class="item-toggle-none"></span><a href="#sec-decimal.prototype.tolocalestring" title="Decimal.prototype.toLocaleString ( [ reserved1 [ , reserved2 ] ] )"><span class="secnum">2.22</span> Decimal.prototype.toLocaleString ( [ <var>reserved1</var> [ , <var>reserved2</var> ] ] )</a></li><li><span class="item-toggle-none"></span><a href="#sec-decimal.prototype.toexponential" title="Decimal.prototype.toExponential ( [ options ] )"><span class="secnum">2.23</span> Decimal.prototype.toExponential ( [ <var>options</var> ] )</a></li><li><span class="item-toggle-none"></span><a href="#sec-decimal.prototype.tofixed" title="Decimal.prototype.toFixed ( [ options ] )"><span class="secnum">2.24</span> Decimal.prototype.toFixed ( [ <var>options</var> ] )</a></li><li><span class="item-toggle-none"></span><a href="#sec-decimal.prototype.tojson" title="Decimal.prototype.toJSON ( )"><span class="secnum">2.25</span> Decimal.prototype.toJSON ( )</a></li><li><span class="item-toggle-none"></span><a href="#sec-decimal.prototype.toprecision" title="Decimal.prototype.toPrecision ( [ options ] )"><span class="secnum">2.26</span> Decimal.prototype.toPrecision ( [ <var>options</var> ] )</a></li><li><span class="item-toggle-none"></span><a href="#sec-decimal.prototype.withfractionaldigits" title="Decimal.prototype.withFractionalDigits ( n )"><span class="secnum">2.27</span> Decimal.prototype.withFractionalDigits ( <var>n</var> )</a></li><li><span class="item-toggle-none"></span><a href="#sec-decimal.prototype.withsignificantdigits" title="Decimal.prototype.withSignificantDigits ( n )"><span class="secnum">2.28</span> Decimal.prototype.withSignificantDigits ( <var>n</var> )</a></li><li><span class="item-toggle-none"></span><a href="#sec-decimal.prototype.valueof" title="Decimal.prototype.valueOf ( x )"><span class="secnum">2.29</span> Decimal.prototype.valueOf ( <var>x</var> )</a></li></ol></li><li><span class="item-toggle">+</span><a href="#sec-numbers-and-dates" title="Numbers and Dates"><span class="secnum">3</span> Numbers and Dates</a><ol class="toc"><li><span class="item-toggle">+</span><a href="#sec-number-objects" title="Number Objects"><span class="secnum">3.1</span> Number Objects</a><ol class="toc"><li><span class="item-toggle">+</span><a href="#sec-number-constructor" title="The Number Constructor"><span class="secnum">3.1.1</span> The Number Constructor</a><ol class="toc"><li><span class="item-toggle-none"></span><a href="#sec-number-constructor-number-value" title="Number ( value )"><span class="secnum">3.1.1.1</span> Number ( <var>value</var> )</a></li></ol></li></ol></li><li><span class="item-toggle">+</span><a href="#sec-bigint-objects" title="BigInt Objects"><span class="secnum">3.2</span> BigInt Objects</a><ol class="toc"><li><span class="item-toggle">+</span><a href="#sec-bigint-constructor" title="The BigInt Constructor"><span class="secnum">3.2.1</span> The BigInt Constructor</a><ol class="toc"><li><span class="item-toggle">+</span><a href="#sec-bigint-constructor-number-value" title="BigInt ( value )"><span class="secnum">3.2.1.1</span> BigInt ( <var>value</var> )</a><ol class="toc"><li><span class="item-toggle-none"></span><a href="#sec-numbertobigint" title="DecimalToBigInt ( number )"><span class="secnum">3.2.1.1.1</span> <ins>DecimalToBigInt ( <var>number</var> )</ins></a></li></ol></li></ol></li></ol></li></ol></li><li><span class="item-toggle">+</span><a href="#sec-decimal-intl" title="Amendments to the ECMAScript® 2024 Internationalization API Specification"><span class="secnum">4</span> Amendments to the ECMAScript® 2024 Internationalization API Specification</a><ol class="toc"><li><span class="item-toggle">+</span><a href="#sup-properties-of-the-decimal128-prototype-object" title="Properties of the Decimal128 Prototype Object"><span class="secnum">4.1</span> Properties of the Decimal128 Prototype Object</a><ol class="toc"><li><span class="item-toggle-none"></span><a href="#sup-decimal128.prototype.tolocalestring" title="Decimal128.prototype.toLocaleString ( [ locales [ , options ] ] )"><span class="secnum">4.1.1</span> Decimal128.prototype.toLocaleString ( [ <var>locales</var> [ , <var>options</var> ] ] )</a></li></ol></li><li><span class="item-toggle">+</span><a href="#numberformat-objects" title="NumberFormat Objects"><span class="secnum">4.2</span> NumberFormat Objects</a><ol class="toc"><li><span class="item-toggle">+</span><a href="#sec-numberformat-abstracts" title="Abstract Operations for NumberFormat Objects"><span class="secnum">4.2.1</span> Abstract Operations for NumberFormat Objects</a><ol class="toc"><li><span class="item-toggle-none"></span><a href="#sec-tointlmathematicalvalue" title="ToIntlMathematicalValue ( value )"><span class="secnum">4.2.1.1</span> ToIntlMathematicalValue ( <var>value</var> )</a></li></ol></li></ol></li><li><span class="item-toggle">+</span><a href="#pluralrules-objects" title="PluralRules Objects"><span class="secnum">4.3</span> PluralRules Objects</a><ol class="toc"><li><span class="item-toggle">+</span><a href="#sec-intl-pluralrules-abstracts" title="Abstract Operations for PluralRules Objects"><span class="secnum">4.3.1</span> Abstract Operations for PluralRules Objects</a><ol class="toc"><li><span class="item-toggle-none"></span><a href="#sec-resolveplural" title="ResolvePlural ( pluralRules, n )"><span class="secnum">4.3.1.1</span> ResolvePlural ( <var>pluralRules</var>, <var>n</var> )</a></li><li><span class="item-toggle-none"></span><a href="#sec-resolvepluralrange" title="ResolvePluralRange ( pluralRules, x, y )"><span class="secnum">4.3.1.2</span> ResolvePluralRange ( <var>pluralRules</var>, <var>x</var>, <var>y</var> )</a></li></ol></li></ol></li></ol></li><li><span class="item-toggle-none"></span><a href="#sec-copyright-and-software-license" title="Copyright &amp; Software License"><span class="secnum">A</span> Copyright &amp; Software License</a></li></ol></div></div><div id="spec-container"><h1 class="version">Stage 1 Draft / July 3, 2025</h1><h1 class="title">Decimal</h1>

docs/why-decimal.md:31

• This snippet chains toPrecision(20) and then immediately calls it as a function, which is invalid JavaScript. Split into two separate calls (e.g., (0.1).toPrecision(20) and (0.2).toPrecision(20)) or adjust the example to demonstrate correct usage.

  .toPrecision(20)(

[ptomato]

I thought you might find a read-through useful, so I built the docs and browsed them locally, and left a couple of comments.

One interesting piece of context is that a table of contents in a floating sidebar is one of the most frequent requests we've had for the Temporal cookbook. (We have tables of contents at the head of each page, but people don't want to have to scroll up to the top to jump to another heading, and I agree that's annoying.)

There was this PR which we ultimately decided not to merge at this point, but you might consider it. Or maybe, these days, there is a marked plugin for a floating sidebar.

[jessealama]

I thought you might find a read-through useful, so I built the docs and browsed them locally, and left a couple of comments.

One interesting piece of context is that a table of contents in a floating sidebar is one of the most frequent requests we've had for the Temporal cookbook. (We have tables of contents at the head of each page, but people don't want to have to scroll up to the top to jump to another heading, and I agree that's annoying.)

There was this PR which we ultimately decided not to merge at this point, but you might consider it. Or maybe, these days, there is a marked plugin for a floating sidebar.

Hmm, perhaps we could discuss that in a separate issue?