feat(core): format-bytes

projects/core/package.json

@@ -378,6 +378,18 @@
       "types": "./dist/file/define.d.ts",
       "default": "./dist/file/define.js"
     },
+    "./format-bytes": {
+      "types": "./dist/format-bytes/index.d.ts",
+      "default": "./dist/format-bytes/index.js"
+    },
+    "./format-bytes/index.js": {
+      "types": "./dist/format-bytes/index.d.ts",
+      "default": "./dist/format-bytes/index.js"
+    },
+    "./format-bytes/define.js": {
+      "types": "./dist/format-bytes/define.d.ts",
+      "default": "./dist/format-bytes/define.js"
+    },
     "./format-datetime": {
       "types": "./dist/format-datetime/index.d.ts",
       "default": "./dist/format-datetime/index.js"

projects/core/src/bundle.ts

@@ -27,6 +27,7 @@ import '@nvidia-elements/core/dropdown/define.js';
 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-bytes/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';
@@ -96,6 +97,7 @@ export * from '@nvidia-elements/core/dropdown';
 export * from '@nvidia-elements/core/dropdown-group';
 export * from '@nvidia-elements/core/dropzone';
 export * from '@nvidia-elements/core/file';
+export * from '@nvidia-elements/core/format-bytes';
 export * from '@nvidia-elements/core/format-datetime';
 export * from '@nvidia-elements/core/format-number';
 export * from '@nvidia-elements/core/format-relative-time';

projects/core/src/format-bytes/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 { FormatBytes } from '@nvidia-elements/core/format-bytes';
+
+define(FormatBytes);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'nve-format-bytes': FormatBytes;
+  }
+}

projects/core/src/format-bytes/format-bytes.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-bytes/format-bytes.examples.ts

@@ -0,0 +1,94 @@
+// 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-bytes/define.js';
+
+export default {
+  title: 'Elements/FormatBytes',
+  component: 'nve-format-bytes'
+};
+
+/**
+ * @summary Automatic decimal conversion for concise file sizes and storage metrics. The component selects the appropriate unit from the byte count.
+ */
+export const Default = {
+  render: () => html`
+    <div nve-layout="column gap:sm">
+      <nve-format-bytes>1024</nve-format-bytes>
+      <nve-format-bytes>1048576</nve-format-bytes>
+      <nve-format-bytes>1073741824</nve-format-bytes>
+    </div>
+  `
+};
+
+/**
+ * @summary Forced unit magnitudes for comparing byte counts on a consistent scale. Use when values need the same unit across a table or chart.
+ */
+export const Unit = {
+  render: () => html`
+    <div nve-layout="column gap:sm">
+      <nve-format-bytes unit="kb">1048576</nve-format-bytes>
+      <nve-format-bytes unit="mb">1048576</nve-format-bytes>
+      <nve-format-bytes unit="gb">1048576</nve-format-bytes>
+    </div>
+  `
+};
+
+/**
+ * @summary Short and long unit labels for compact metrics or explanatory text. Long labels improve clarity when space allows.
+ */
+export const UnitDisplay = {
+  render: () => html`
+    <div nve-layout="column gap:sm">
+      <nve-format-bytes unit-display="short">1048576</nve-format-bytes>
+      <nve-format-bytes unit-display="long">1048576</nve-format-bytes>
+      <nve-format-bytes display="binary" unit-display="long">1048576</nve-format-bytes>
+    </div>
+  `
+};
+
+/**
+ * @summary Fraction digit controls for matching the precision of storage measurements. Use fixed digits when values must align visually.
+ */
+export const Precision = {
+  render: () => html`
+    <div nve-layout="column gap:sm">
+      <nve-format-bytes maximum-fraction-digits="0">1234567</nve-format-bytes>
+      <nve-format-bytes maximum-fraction-digits="2">1234567</nve-format-bytes>
+      <nve-format-bytes minimum-fraction-digits="3" maximum-fraction-digits="3">1234567</nve-format-bytes>
+    </div>
+  `
+};
+
+/**
+ * @summary Explicit locale formatting for audiences whose numeric separators differ from the document language. Unit labels remain lowercase English.
+ */
+export const Locale = {
+  render: () => html`
+    <div nve-layout="column gap:sm">
+      <nve-format-bytes locale="en-US">1048576</nve-format-bytes>
+      <nve-format-bytes locale="de-DE">1048576</nve-format-bytes>
+      <nve-format-bytes locale="fr-FR">1048576</nve-format-bytes>
+    </div>
+  `
+};
+
+/**
+ * @summary Value attribute input for JavaScript or bound data. It takes precedence over text content while the text remains an SSR fallback.
+ */
+export const Value = {
+  render: () => html`<nve-format-bytes value="1048576">1024</nve-format-bytes>`
+};
+
+/**
+ * @summary Decimal and binary conversion for matching SI or IEC storage conventions. Use the convention expected by the surrounding product.
+ */
+export const Display = {
+  render: () => html`
+    <div nve-layout="column gap:sm">
+      <nve-format-bytes display="decimal">1024</nve-format-bytes>
+      <nve-format-bytes display="binary">1024</nve-format-bytes>
+    </div>
+  `
+};

projects/core/src/format-bytes/format-bytes.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 { FormatBytes } from '@nvidia-elements/core/format-bytes';
+import '@nvidia-elements/core/format-bytes/define.js';
+
+describe(FormatBytes.metadata.tag, () => {
+  it('should pass axe check', async () => {
+    const fixture = await createFixture(html`
+      <nve-format-bytes locale="en-US">1048576</nve-format-bytes>
+      <nve-format-bytes locale="en-US" display="binary" unit-display="long">1048576</nve-format-bytes>
+      <nve-format-bytes locale="de-DE" unit="kb">1048576</nve-format-bytes>
+    `);
+
+    try {
+      await elementIsStable(fixture.querySelector(FormatBytes.metadata.tag));
+      const results = await runAxe([FormatBytes.metadata.tag]);
+      expect(results.violations.length).toBe(0);
+    } finally {
+      removeFixture(fixture);
+    }
+  });
+});

projects/core/src/format-bytes/format-bytes.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 { describe, expect, test } from 'vitest';
+import { lighthouseRunner } from '@internals/vite';
+
+describe('format-bytes lighthouse report', () => {
+  test('format-bytes should meet lighthouse benchmarks', async () => {
+    const report = await lighthouseRunner.getReport('nve-format-bytes', /* html */ `
+      <nve-format-bytes locale="en-US">1048576</nve-format-bytes>
+      <script type="module">
+        import '@nvidia-elements/core/format-bytes/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(11);
+  });
+});

projects/core/src/format-bytes/format-bytes.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 { FormatBytes } from '@nvidia-elements/core/format-bytes';
+import '@nvidia-elements/core/format-bytes/define.js';
+
+describe(FormatBytes.metadata.tag, () => {
+  it('should render formatted semantic output during ssr', async () => {
+    const result = await ssrRunner.render(html`<nve-format-bytes locale="en-US" value="1048576"></nve-format-bytes>`);
+    expect(result.includes('shadowroot="open"')).toBe(true);
+    expect(result.includes('<data internal-host value="1048576">')).toBe(true);
+    expect(result.includes('1.05 mb')).toBe(true);
+    expect(result.includes('nve-format-bytes')).toBe(true);
+  });
+});