Examples catalog

_components/header.vto

@@ -0,0 +1,42 @@
+
+<header class="fixed top-0 w-full h-16 z-30">
+   <svg
+    class="rotate-180 -z-10 absolute top-0 left-0"
+    height="100%"
+    width="100%"
+    xmlns="http://www.w3.org/2000/svg"
+    viewBox="0 0 1000 70"
+    preserveAspectRatio="none"
+    fill="url(#gradient)"
+  >
+    <linearGradient id="gradient">
+      <stop style="stop-color: #1d4ed8" offset="0%" />
+      <stop style="stop-color: #3b82f6" offset="100%" />
+    </linearGradient>
+    <rect width="1000" height="61" y="9" />
+    <path d="M0 0 Q 500 10 1000 0 L 1000 10 L 0 10 Z" />
+  </svg>
+  <nav class="z-20 h-full">
+    <div class="h-full flex items-center justify-between pb-2 pt-1 sm:pt-2 px-6 sm:px-8 ">
+      <div class="flex gap-2 items-center">
+        <button id="sidebar_open" class="md:hidden hover:bg-gray-50/15 p-2 -ml-2 rounded-full inline-block active:bg-gray-100/25">
+          <svg class="text-white w-6 h-6" fill="none" stroke="currentColor" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg" title="Open sidebar">
+            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 6h16M4 12h16m-7 6h7"></path>
+          </svg>
+        </button>
+        <div class="flex items-center gap-3">
+          <img src="/static/logos/no-padding/mf2-logo-only.svg" class="size-10" />
+          <div class="flex flex-col sm:flex-row sm:items-baseline">
+            <a href="/" class="text-white
+            font-serif font-bold text-2xl hover:underline underline-offset-4">MessageFormat 2</a>
+            <span class="mx-2 text-white select-none hidden sm:block">/</span>
+            <span class="text-white text-lg leading-4">{{ title }}</span>
+          </div>
+        </div>
+      </div>
+      <ul class="flex">
+        <li class="mx-2 hidden sm:block"><a href="/playground/" class="px-4 py-2 font-bold text-blue-600 rounded-full bg-gray-50 hover:bg-blue-200 active:bg-blue-200 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 focus:ring-offset-white">Playground</a></li>
+      </ul>
+    </div>
+  </nav>
+</header>

_includes/example.vto

@@ -0,0 +1,27 @@
+---
+layout: layout.vto
+---
+
+{{ comp.header({ title: "Examples" }) }}
+
+<div id="content" class="flex gap-4 mt-20">
+  <div class="w-full flex  justify-center">
+    <main class="max-w-[90ch] overflow-x-hidden w-full px-6 sm:px-8 md:px-16">
+      <p class="mb-4"><a href="/examples/" class="underline underline-offset-4 hover:text-blue-600 text-lg">← Back to Overview</a></p>
+      <h1 class="text-4xl font-serif font-bold text-black border-b border-gray-200 pb-2 mb-4">{{ title }}</h1>
+      <p class="markdown">{{ description }}</p>
+      <div class="markdown mb-16">{{ content }}</div>
+      {{ if related && related.length > 0 }}
+        <h2 class="text-2xl font-serif font-bold text-black border-b border-gray-200 pb-2 mb-4">Related</h2>
+        <ul class="list-disc ml-6 mb-16">
+          {{ for item of related }}
+            <li>
+              <a href="/{{ item }}" class="underline underline-offset-4 hover:text-blue-600 text-lg">{{ search.data(item).section }}: {{ search.data(item).title }}</a>
+            </li>
+          {{ /for }}
+        </ul>
+      {{ /if }}
+      {{ comp.footer({ padding: "" }) }}
+    </main>
+  </div>
+</div>

_includes/layout.vto

@@ -9,7 +9,7 @@
     <script src="/static/js/leader-line.min.js" defer></script>
     <script src="/src/utils.entry.js" inline></script>
     {{ /if }}
-    {{ if url.startsWith('/docs/') }}
+    {{ if url.startsWith('/docs/') || url.startsWith('/examples/') }}
     <script src="/src/interactive.entry.js" type="module"></script>
     {{ /if }}
     {{ if url == '/playground/' }}

docs/_data.yml

@@ -3,6 +3,7 @@ sidebar:
   - docs/quick-start/
   - docs/why/
   - docs/translators/
+  - examples/
   - section: Reference
     children:
       - docs/reference/functions/

examples.vto

@@ -0,0 +1,45 @@
+---
+layout: layout.vto
+title: Examples
+sections:
+  - numbers
+  - variants
+---
+
+{{ comp.header({ title: "Examples" }) }}
+
+<div class="px-8 mt-24 mb-12 mx-auto max-w-screen-lg">
+  <h1 class="text-4xl font-serif font-bold text-black border-b border-gray-200 pb-2 mb-8">Examples</h1>
+  <div class="markdown mb-8">
+    <p>MessageFormat 2 is a powerful and flexible language for creating localized messages. This examples catalog showcases a variety of common use cases and how to solve them with MessageFormat 2.</p>
+
+    <p>Each example includes an interactive playground where you can experiment with the code and see the output in real-time. The examples are organized by category.</p>
+
+    <div class="text-lg bg-blue-50 border-l-4 border-blue-500 text-blue-900 p-4 mb-8">
+      Looking for a structured walkthrough of MessageFormat 2 instead? Check out the <a href="/docs/quick-start/" class="underline underline-offset-4 hover:text-blue-600">Quick Start</a>.
+    </div>
+  </div>
+
+
+  <div class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-6 mb-12">
+    {{ for section of sections }}
+    <div>
+      <h2 class="text-2xl font-serif font-bold text-black border-b border-gray-200">{{ search.page(`example_${section}`).section }}</h2>
+      <ul class="mt-3">
+        {{ for page of search.pages(`example_${section}`) }}
+        <li><a href="{{ page.url }}" class="text-lg text-black underline hover:text-blue-600 flex items-center gap-2">
+          <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 328 258" width="1rem" class="stroke-black">
+            <path d="m86 58-71 70 71 72M186 15l-46 228M242 59l71 71-71 72" fill="none" stroke-linecap="round" stroke-linejoin="round" stroke-width="30"></path>
+          </svg>
+          {{ page.title }}
+        </a></li>
+        {{ /for }}
+      </ul>
+    </div>
+    {{ /for }}
+  </div>
+
+
+  {{ comp.footer({ padding: "" }) }}
+</div>
+

examples/_data.yml

@@ -0,0 +1 @@
+layout: example.vto

examples/numbers/_data.yml

@@ -0,0 +1,3 @@
+section: Numbers
+tags:
+  - example_numbers

examples/numbers/compact-notation.md

@@ -0,0 +1,38 @@
+---
+title: Compact notation
+description: Print numbers in compact notation, such as 100K or 1.23M.
+related:
+  - examples/numbers/rounding-and-precision/
+---
+
+<mf2-interactive>
+
+```mf2
+{ 123456 :number notation=compact }
+```
+
+</mf2-interactive>
+
+<mf2-interactive>
+
+```mf2
+{ 123456 :number notation=compact compactDisplay=long }
+```
+
+</mf2-interactive>
+
+Compact notation is a way of expressing large numbers in a more concise form. It
+is commonly used in financial and scientific applications.
+
+The denominator of the compact form is a power of 10. In US English, examples
+are 1,000 (K), 1,000,000 (M), or 1,000,000,000 (B). In other locales, different
+denominators may be used, which may not always be a power of 1000. In India, for
+example, 1,00,000 (L) is used to represent 100,000.
+
+<mf2-interactive locale="en-IN">
+
+```mf2
+{ 123456 :number notation=compact }
+```
+
+</mf2-interactive>

examples/numbers/engineering-notation.md

@@ -0,0 +1,18 @@
+---
+title: Engineering notation
+description: Print numbers in engineering notation, such as 123.45E3.
+related:
+  - examples/numbers/rounding-and-precision/
+---
+
+<mf2-interactive>
+
+```mf2
+{ 12345 :number notation=engineering }
+```
+
+</mf2-interactive>
+
+[Engineering notation](https://en.wikipedia.org/wiki/Engineering_notation) is a
+variant of scientific notation in which the exponent is a multiple of three. It
+is commonly used in engineering and scientific applications.

examples/numbers/padding.md

@@ -0,0 +1,21 @@
+---
+title: Padding with zeros
+description: Pad numbers with zeros to a specific width.
+related:
+  - examples/numbers/rounding-and-precision/
+---
+
+<mf2-interactive>
+
+```mf2
+{ 3 :number minimumIntegerDigits=3 }
+```
+
+</mf2-interactive>
+
+Some applications require numbers to be padded with zeros to a specific width.
+This is often the case when numbers are displayed in a fixed-width font or
+formatted as part of a larger string.
+
+The minimum number of integer digits can be specified using the
+`minimumIntegerDigits` option. Any missing digits are filled with zeros.

examples/numbers/percent.md

@@ -0,0 +1,17 @@
+---
+title: Displaying percentages
+description: Display fractional numbers as percentages, such as 0.5 as 50%.
+related:
+  - examples/numbers/rounding-and-precision/
+---
+
+<mf2-interactive>
+
+```mf2
+{ 0.5 :number style=percent }
+```
+
+</mf2-interactive>
+
+Percentages are a way of expressing numbers as fractions of 100. They are
+commonly used in financial and scientific applications.

examples/numbers/rounding-and-precision.md

@@ -0,0 +1,58 @@
+---
+title: Rounding and precision
+description: Round numbers to a specific number of decimal places or significant digits.
+related:
+  - examples/numbers/scientific-notation/
+---
+
+## Fractional digits
+
+Fractional digits are the number of digits to the right of the decimal point in
+a number.
+
+<mf2-interactive>
+
+```mf2
+{ 3.12345 :number maximumFractionDigits=2 }
+```
+
+</mf2-interactive>
+
+<mf2-interactive>
+
+```mf2
+{ 3 :number minimumFractionDigits=3 }
+```
+
+</mf2-interactive>
+
+When using the `minimumFractionDigits` option, any missing decimal places in the
+original number are filled with zeros.
+
+## Significant digits
+
+[Significant digits](https://en.wikipedia.org/wiki/Significant_figures) are the
+number of digits that carry meaning in a number. They are used to indicate the
+precision of a measurement or calculation.
+
+Any leading zeros are not considered significant. For example, `0.00123` has 3
+significant digits, while `0.001230` has 4 significant digits.
+
+<mf2-interactive>
+
+```mf2
+{ 12.34 :number maximumSignificantDigits=3 }
+```
+
+</mf2-interactive>
+
+<mf2-interactive>
+
+```mf2
+{ 3 :number minimumSignificantDigits=3 }
+```
+
+</mf2-interactive>
+
+When using the `minimumSignificantDigits` option, any missing significant digits
+in the original number are filled with zeros.

examples/numbers/scientific-notation.md

@@ -0,0 +1,21 @@
+---
+title: Scientific notation
+description: Print numbers in scientific notation, such as 1.001E2.
+related:
+  - examples/numbers/rounding-and-precision/
+---
+
+<mf2-interactive>
+
+```mf2
+{ 100.100 :number notation=scientific }
+```
+
+</mf2-interactive>
+
+[Scientific notation](https://en.wikipedia.org/wiki/Scientific_notation) is a
+way of expressing numbers that are too large or too small to be conveniently
+written in decimal form. It is commonly used in scientific applications.
+
+To print a number in scientific notation, use the `:number` function with the
+`notation=scientific` option.

examples/numbers/sign-display.md

@@ -0,0 +1,42 @@
+---
+title: Displaying or hiding the sign
+description: (Forcibly) display or hide the sign of a number.
+---
+
+<mf2-interactive>
+
+```mf2
+{ 1 :number signDisplay=always }
+{ -1 :number signDisplay=always }
+```
+
+</mf2-interactive>
+
+<mf2-interactive>
+
+```mf2
+{ 1 :number signDisplay=never }
+{ -1 :number signDisplay=never }
+```
+
+</mf2-interactive>
+
+By default, positive numbers are not prefixed with a sign, while negative
+numbers are prefixed with a minus sign.
+
+The `signDisplay` option can be used to forcibly display or hide the sign of a
+number. The possible values are:
+
+- `auto` (default): Display the sign only for negative numbers, including
+  negative zero.
+- `always`: Always display the sign, even for positive numbers, and positive
+  zero.
+- `never`: Never display the sign, even for negative numbers, and negative zero.
+- `exceptZero`: Display the sign for all numbers, except for zero.
+- `negative`: Display the sign only for negative numbers, but not for negative
+  zero.
+
+> Floating-point numbers distinguish between positive and negative zero. In
+> modes `auto` and `always`, the sign of negative zero is displayed. If you do
+> not want to display the sign for negative zero, use `negative` instead of
+> `auto`, or `exceptZero` instead of `always`.

examples/variants/_data.yml

@@ -0,0 +1,3 @@
+section: Variants
+tags:
+  - example_variants