feat(core): add nve-format-number component

projects/core/eslint.config.js

@@ -30,7 +30,11 @@ export default [
     }
   },
   {
-    files: ['src/format-datetime/format-datetime.ts', 'src/format-relative-time/format-relative-time.ts'],
+    files: [
+      'src/format-datetime/format-datetime.ts',
+      'src/format-number/format-number.ts',
+      'src/format-relative-time/format-relative-time.ts'
+    ],
     rules: {
       'local/require-test-completeness': ['error', { skipSuffixes: ['.test.visual.ts'] }]
     }

projects/core/package.json

@@ -381,6 +381,18 @@
       "types": "./dist/format-datetime/define.d.ts",
       "default": "./dist/format-datetime/define.js"
     },
+    "./format-number": {
+      "types": "./dist/format-number/index.d.ts",
+      "default": "./dist/format-number/index.js"
+    },
+    "./format-number/index.js": {
+      "types": "./dist/format-number/index.d.ts",
+      "default": "./dist/format-number/index.js"
+    },
+    "./format-number/define.js": {
+      "types": "./dist/format-number/define.d.ts",
+      "default": "./dist/format-number/define.js"
+    },
     "./format-relative-time": {
       "types": "./dist/format-relative-time/index.d.ts",
       "default": "./dist/format-relative-time/index.js"

projects/core/src/bundle.ts

@@ -28,6 +28,7 @@ import '@nvidia-elements/core/dropdown-group/define.js';
 import '@nvidia-elements/core/dropzone/define.js';
 import '@nvidia-elements/core/file/define.js';
 import '@nvidia-elements/core/format-datetime/define.js';
+import '@nvidia-elements/core/format-number/define.js';
 import '@nvidia-elements/core/format-relative-time/define.js';
 import '@nvidia-elements/core/forms/define.js';
 import '@nvidia-elements/core/grid/define.js';
@@ -81,6 +82,7 @@ export * from '@nvidia-elements/core/dropdown';
 export * from '@nvidia-elements/core/dropzone';
 export * from '@nvidia-elements/core/file';
 export * from '@nvidia-elements/core/format-datetime';
+export * from '@nvidia-elements/core/format-number';
 export * from '@nvidia-elements/core/format-relative-time';
 export * from '@nvidia-elements/core/forms';
 export * from '@nvidia-elements/core/grid';

projects/core/src/format-number/define.ts

@@ -0,0 +1,13 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { define } from '@nvidia-elements/core/internal';
+import { FormatNumber } from '@nvidia-elements/core/format-number';
+
+define(FormatNumber);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'nve-format-number': FormatNumber;
+  }
+}

projects/core/src/format-number/format-number.css

@@ -0,0 +1,14 @@
+/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. */
+/* SPDX-License-Identifier: Apache-2.0 */
+
+:host {
+  display: inline;
+}
+
+[internal-host] {
+  color: var(--nve-sys-text-color, inherit);
+}
+
+slot {
+  display: none;
+}

projects/core/src/format-number/format-number.examples.ts

@@ -0,0 +1,120 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { html } from 'lit';
+import '@nvidia-elements/core/format-number/define.js';
+
+export default {
+  title: 'Elements/FormatNumber',
+  component: 'nve-format-number'
+};
+
+/**
+ * @summary Basic decimal formatting with localized grouping separators. Use for inline counts and metrics.
+ */
+export const Default = {
+  render: () => html`
+  <nve-format-number>1234567.89</nve-format-number>
+  `
+};
+
+/**
+ * @summary Currency formatting for monetary values with locale-aware symbols and separators. Use for prices, budgets, and financial totals.
+ */
+export const Currency = {
+  render: () => html`
+<div nve-layout="column gap:sm">
+  <nve-format-number format-style="currency" currency="USD">1234.56</nve-format-number>
+  <nve-format-number format-style="currency" currency="EUR" currency-display="code">1234.56</nve-format-number>
+  <nve-format-number format-style="currency" currency="JPY" currency-display="name">1234</nve-format-number>
+</div>
+  `
+};
+
+/**
+ * @summary Percent formatting for ratios and completion values. Source values should already represent a fraction (such as 0.85 for 85 percent).
+ */
+export const Percent = {
+  render: () => html`
+<div nve-layout="column gap:sm">
+  <nve-format-number format-style="percent">0.85</nve-format-number>
+  <nve-format-number format-style="percent">0.126</nve-format-number>
+</div>
+  `
+};
+
+/**
+ * @summary Unit formatting for measurements and quantities. Use for distances, storage sizes, or other numeric labels that need a localized unit suffix.
+ */
+export const Unit = {
+  render: () => html`
+<div nve-layout="column gap:sm">
+  <nve-format-number format-style="unit" unit="kilometer">1234.56</nve-format-number>
+  <nve-format-number format-style="unit" unit="byte" unit-display="long">2048</nve-format-number>
+  <nve-format-number format-style="unit" unit="celsius" unit-display="narrow">22</nve-format-number>
+</div>
+  `
+};
+
+/**
+ * @summary Notation presets for scientific, engineering, and compact display. Use compact notation in dashboards or cards where space matters.
+ */
+export const Notation = {
+  render: () => html`
+<div nve-layout="column gap:sm">
+  <nve-format-number notation="compact" compact-display="short">1234567</nve-format-number>
+  <nve-format-number notation="compact" compact-display="long">1234567</nve-format-number>
+  <nve-format-number notation="scientific">1234567</nve-format-number>
+  <nve-format-number notation="engineering">1234567</nve-format-number>
+</div>
+  `
+};
+
+/**
+ * @summary Sign display options for controlling positive and negative indicators. Use 'always' for delta values or 'exceptZero' for change indicators.
+ */
+export const SignDisplay = {
+  render: () => html`
+<div nve-layout="column gap:sm">
+  <nve-format-number sign-display="always">42</nve-format-number>
+  <nve-format-number sign-display="always">-42</nve-format-number>
+  <nve-format-number sign-display="exceptZero">0</nve-format-number>
+  <nve-format-number sign-display="never">-42</nve-format-number>
+</div>
+  `
+};
+
+/**
+ * @summary Fraction digit control for tuning decimal precision. Use to enforce fixed decimal places in financial or scientific contexts.
+ */
+export const FractionDigits = {
+  render: () => html`
+<div nve-layout="column gap:sm">
+  <nve-format-number minimum-fraction-digits="4">1.5</nve-format-number>
+  <nve-format-number maximum-fraction-digits="0">1.567</nve-format-number>
+  <nve-format-number minimum-fraction-digits="2" maximum-fraction-digits="2">3</nve-format-number>
+</div>
+  `
+};
+
+/**
+ * @summary Explicit locale settings for internationalized number output. Use when the target audience locale differs from the document language or browser default.
+ */
+export const Locale = {
+  render: () => html`
+<div nve-layout="column gap:sm">
+  <nve-format-number locale="de-DE" format-style="currency" currency="EUR">1234.56</nve-format-number>
+  <nve-format-number locale="ja-JP" format-style="currency" currency="JPY">1234</nve-format-number>
+  <nve-format-number locale="fr-FR">1234567.89</nve-format-number>
+</div>
+  `
+};
+
+/**
+ * @summary Number attribute input for values supplied by JavaScript or bound data. By default, the component formats text content, which also serves as the SSR fallback, and `number` wins when both are present.
+ */
+export const NumberAttribute = {
+  render: () => html`
+  <nve-format-number number="1234.56" format-style="currency" currency="USD"></nve-format-number>
+  `
+};

projects/core/src/format-number/format-number.test.axe.ts

@@ -0,0 +1,27 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { html } from 'lit';
+import { describe, expect, it } from 'vitest';
+import { createFixture, elementIsStable, removeFixture } from '@internals/testing';
+import { runAxe } from '@internals/testing/axe';
+import { FormatNumber } from '@nvidia-elements/core/format-number';
+import '@nvidia-elements/core/format-number/define.js';
+
+describe(FormatNumber.metadata.tag, () => {
+  it('should pass axe check', async () => {
+    const fixture = await createFixture(html`
+      <nve-format-number locale="en-US">1234567</nve-format-number>
+      <nve-format-number locale="en-US" format-style="currency" currency="USD">1234.56</nve-format-number>
+      <nve-format-number locale="de-DE">1234.56</nve-format-number>
+    `);
+
+    try {
+      await elementIsStable(fixture.querySelector(FormatNumber.metadata.tag));
+      const results = await runAxe([FormatNumber.metadata.tag]);
+      expect(results.violations.length).toBe(0);
+    } finally {
+      removeFixture(fixture);
+    }
+  });
+});

projects/core/src/format-number/format-number.test.lighthouse.ts

@@ -0,0 +1,21 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { expect, test, describe } from 'vitest';
+import { lighthouseRunner } from '@internals/vite';
+
+describe('format-number lighthouse report', () => {
+  test('format-number should meet lighthouse benchmarks', async () => {
+    const report = await lighthouseRunner.getReport('nve-format-number', /* html */`
+      <nve-format-number format-style="currency" currency="USD">1234.56</nve-format-number>
+      <script type="module">
+        import '@nvidia-elements/core/format-number/define.js';
+      </script>
+    `);
+
+    expect(report.scores.performance).toBe(100);
+    expect(report.scores.accessibility).toBe(100);
+    expect(report.scores.bestPractices).toBe(100);
+    expect(report.payload.javascript.kb).toBeLessThan(12);
+  });
+});

projects/core/src/format-number/format-number.test.ssr.ts

@@ -0,0 +1,18 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { html } from 'lit';
+import { describe, expect, it } from 'vitest';
+import { ssrRunner } from '@internals/vite';
+import { FormatNumber } from '@nvidia-elements/core/format-number';
+import '@nvidia-elements/core/format-number/define.js';
+
+describe(FormatNumber.metadata.tag, () => {
+  it('should pass baseline ssr check', async () => {
+    const result = await ssrRunner.render(
+      html`<nve-format-number format-style="currency" currency="USD">1234.56</nve-format-number>`
+    );
+    expect(result.includes('shadowroot="open"')).toBe(true);
+    expect(result.includes('nve-format-number')).toBe(true);
+  });
+});