chore: extracting utilities and adding more unit tests

Author: canerakdas

src/generators/web/ui/components/SideBar/index.jsx

@@ -2,54 +2,28 @@ import Select from '@node-core/ui-components/Common/Select';
 import SideBar from '@node-core/ui-components/Containers/Sidebar';
 
 import styles from './index.module.css';
-import { relative } from '../../../../../utils/url.mjs';
-import { buildSideBarGroups } from '../../utils/sidebar.mjs';
+import {
+  buildSideBarGroups,
+  getCompatibleVersions,
+  redirect,
+} from './utils/index.mjs';
 
 import { title, version, versions, pages } from '#theme/config';
 
-/**
- * Extracts the major version number from a version string.
- * @param {string} v - Version string (e.g., 'v14.0.0', '14.0.0')
- * @returns {number}
- */
-const getMajorVersion = v => parseInt(String(v).match(/\d+/)?.[0] ?? '0', 10);
-
-/**
- * Redirect to a URL
- * @param {string} url URL
- */
-const redirect = url => (window.location.href = url);
-
 /**
  * Sidebar component for MDX documentation with version selection and page navigation
  * @param {{ metadata: import('../../types').SerializedMetadata }} props
  */
 export default ({ metadata }) => {
-  const introducedMajor = getMajorVersion(
-    metadata.added ?? metadata.introduced_in
-  );
-
+  // Build sidebar groups from metadata, categorizing pages and preserving order
+  const groups = buildSideBarGroups(pages, metadata);
   // Filter pre-computed versions by compatibility and resolve per-page URL
-  const compatibleVersions = versions
-    .filter(v => v.major >= introducedMajor)
-    .map(({ url, label }) => ({
-      value: url.replace('{path}', metadata.path),
-      label,
-    }));
-
-  const items = pages.map(([heading, path, category]) => ({
-    label: heading,
-    link:
-      metadata.path === path
-        ? `${metadata.basename}.html`
-        : `${relative(path, metadata.path)}.html`,
-    category,
-  }));
+  const compatibleVersions = getCompatibleVersions(versions, metadata);
 
   return (
     <SideBar
       pathname={`${metadata.basename}.html`}
-      groups={buildSideBarGroups(items)}
+      groups={groups}
       onSelect={redirect}
       as={props => <a {...props} rel="prefetch" />}
       title="Navigation"

src/generators/web/ui/components/SideBar/utils/__tests__/index.test.mjs

@@ -0,0 +1,217 @@
+'use strict';
+
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+const {
+  buildSideBarGroups,
+  getSidebarItems,
+  getMajorVersion,
+  getCompatibleVersions,
+} = await import('../index.mjs');
+
+const pages = [
+  ['File System API', 'fs', 'File System'],
+  ['HTTP API', 'http', 'Networking'],
+  ['Path API', 'path', 'File System'],
+  ['Index', 'index'],
+];
+
+const versions = [
+  { major: 14, url: '/api/v14/{path}.html', label: 'v14' },
+  { major: 16, url: '/api/v16/{path}.html', label: 'v16' },
+  { major: 18, url: '/api/v18/{path}.html', label: 'v18' },
+];
+
+describe('buildSideBarGroups', () => {
+  it('groups entries by category and preserves insertion order', () => {
+    const metadata = { path: 'fs', basename: 'fs' };
+
+    const result = buildSideBarGroups(pages, metadata);
+
+    assert.deepStrictEqual(result, [
+      {
+        groupName: 'File System',
+        items: [
+          { label: 'File System API', link: 'fs.html' },
+          { label: 'Path API', link: 'path.html' },
+        ],
+      },
+      {
+        groupName: 'Networking',
+        items: [{ label: 'HTTP API', link: 'http.html' }],
+      },
+    ]);
+  });
+
+  it('puts entries without category into an Others group at the end by default', () => {
+    const uncategorizedPages = [
+      ['Buffer', 'buffer', 'Binary'],
+      ['Unknown', 'unknown'],
+      ['Config', 'config', ''],
+    ];
+    const metadata = { path: 'buffer', basename: 'buffer' };
+
+    const result = buildSideBarGroups(uncategorizedPages, metadata);
+
+    assert.equal(result.at(-1).groupName, 'Others');
+    assert.deepStrictEqual(result.at(-1).items, [
+      { label: 'Unknown', link: 'unknown.html' },
+      { label: 'Config', link: 'config.html' },
+    ]);
+  });
+
+  it('uses a custom default group name when provided', () => {
+    const metadata = { path: 'unknown', basename: 'unknown' };
+    const result = buildSideBarGroups(
+      [['Unknown', 'unknown']],
+      metadata,
+      'General'
+    );
+
+    assert.deepStrictEqual(result, [
+      {
+        groupName: 'General',
+        items: [{ label: 'Unknown', link: 'unknown.html' }],
+      },
+    ]);
+  });
+
+  it('returns an empty array when given no entries', () => {
+    assert.deepStrictEqual(
+      buildSideBarGroups([], { path: 'fs', basename: 'fs' }),
+      []
+    );
+  });
+});
+
+describe('getSidebarItems', () => {
+  it('maps pages to sidebar items and keeps category values', () => {
+    const metadata = { path: 'fs', basename: 'fs' };
+    const result = getSidebarItems(pages.slice(0, 3), metadata);
+
+    assert.deepStrictEqual(result, [
+      {
+        label: 'File System API',
+        link: 'fs.html',
+        category: 'File System',
+      },
+      {
+        label: 'HTTP API',
+        link: 'http.html',
+        category: 'Networking',
+      },
+      {
+        label: 'Path API',
+        link: 'path.html',
+        category: 'File System',
+      },
+    ]);
+  });
+
+  it('uses basename html for the current page and relative links for others', () => {
+    const metadata = { path: 'guide/fs', basename: 'fs' };
+    const result = getSidebarItems(
+      [
+        ['File System API', 'guide/fs', 'File System'],
+        ['HTTP API', 'guide/http', 'Networking'],
+        ['Child API', 'guide/sub/child'],
+      ],
+      metadata
+    );
+
+    assert.deepStrictEqual(result, [
+      {
+        label: 'File System API',
+        link: 'fs.html',
+        category: 'File System',
+      },
+      {
+        label: 'HTTP API',
+        link: 'http.html',
+        category: 'Networking',
+      },
+      {
+        label: 'Child API',
+        link: 'sub/child.html',
+        category: undefined,
+      },
+    ]);
+  });
+});
+
+describe('getMajorVersion', () => {
+  it('extracts major version from "v" prefixed string', () => {
+    assert.strictEqual(getMajorVersion('v14.0.0'), 14);
+    assert.strictEqual(getMajorVersion('v18.12.0'), 18);
+  });
+
+  it('extracts major version without "v" prefix', () => {
+    assert.strictEqual(getMajorVersion('16.0.0'), 16);
+    assert.strictEqual(getMajorVersion('20.1.0'), 20);
+  });
+
+  it('handles single digit versions', () => {
+    assert.strictEqual(getMajorVersion('v4'), 4);
+    assert.strictEqual(getMajorVersion('9'), 9);
+  });
+
+  it('returns integer only', () => {
+    const result = getMajorVersion('v14.5.3');
+    assert.strictEqual(typeof result, 'number');
+    assert.strictEqual(result % 1, 0);
+  });
+});
+
+describe('getCompatibleVersions', () => {
+  it('includes versions with equal or greater major version', () => {
+    const metadata = { added: 'v14.0.0', path: 'fs.md' };
+    const result = getCompatibleVersions(versions, metadata);
+
+    assert.deepStrictEqual(result, [
+      { value: '/api/v14/fs.md.html', label: 'v14' },
+      { value: '/api/v16/fs.md.html', label: 'v16' },
+      { value: '/api/v18/fs.md.html', label: 'v18' },
+    ]);
+  });
+
+  it('filters out versions with lower major version', () => {
+    const metadata = { added: 'v18.0.0', path: 'fs.md' };
+    const result = getCompatibleVersions(versions, metadata);
+
+    assert.deepStrictEqual(result, [
+      { value: '/api/v18/fs.md.html', label: 'v18' },
+    ]);
+  });
+
+  it('uses introduced_in as fallback when added is missing', () => {
+    const metadata = { introduced_in: 'v16.0.0', path: 'fs.md' };
+    const result = getCompatibleVersions(versions, metadata);
+
+    assert.deepStrictEqual(result, [
+      { value: '/api/v16/fs.md.html', label: 'v16' },
+      { value: '/api/v18/fs.md.html', label: 'v18' },
+    ]);
+  });
+
+  it('defaults to v0 when no version info provided', () => {
+    const metadata = { path: 'fs.md' };
+    const result = getCompatibleVersions(versions, metadata);
+
+    assert.deepStrictEqual(result, [
+      { value: '/api/v14/fs.md.html', label: 'v14' },
+      { value: '/api/v16/fs.md.html', label: 'v16' },
+      { value: '/api/v18/fs.md.html', label: 'v18' },
+    ]);
+  });
+
+  it('replaces {path} placeholder in URL', () => {
+    const metadata = { added: 'v14.0.0', path: 'file/system' };
+    const result = getCompatibleVersions(versions, metadata);
+
+    result.forEach(item => {
+      assert.ok(!item.value.includes('{path}'));
+      assert.ok(item.value.includes(metadata.path));
+    });
+  });
+});

src/generators/web/ui/components/SideBar/utils/index.mjs

@@ -0,0 +1,116 @@
+import { relative } from '../../../../../../utils/url.mjs';
+import { SIDEBAR_GROUPS } from '../../../constants.mjs';
+
+/**
+ * @deprecated This is being exported temporarily during the transition period.
+ * Reverse lookup: filename (e.g. 'fs.html') -> groupName, used as category
+ * fallback for pages without explicit category in metadata.
+ */
+export const fileToGroup = new Map(
+  SIDEBAR_GROUPS.flatMap(({ groupName, items }) =>
+    items.map(item => [item, groupName])
+  )
+);
+
+/**
+ * Builds grouped sidebar navigation from categorized page entries.
+ * Pages without a category are placed under the provided default group.
+ *
+ * @param {Array<[string, string, string?]>} pages - Array of page entries as [heading, path, category?]
+ * @param {{ path: string, basename: string }} metadata - Metadata for the current page, used to resolve links
+ * @param {string} [defaultGroupName='Others'] - Name for the default group containing uncategorized pages
+ * @returns {Array<{ groupName: string, items: Array<{ label: string, link: string }> }>}
+ */
+export const buildSideBarGroups = (
+  pages,
+  metadata,
+  defaultGroupName = 'Others'
+) => {
+  const items = getSidebarItems(pages, metadata);
+  const groups = new Map();
+  const others = [];
+
+  // Group entries by category while preserving insertion order
+  for (const { label, link, category } of items) {
+    const linkFilename = link.split('/').at(-1);
+
+    // Skip index pages as they are typically the main entry point for a section
+    // and may not need to be listed separately in the sidebar.
+    if (linkFilename === 'index.html') {
+      continue;
+    }
+
+    const resolvedCategory = category ?? fileToGroup.get(linkFilename);
+
+    if (!resolvedCategory) {
+      others.push({ label, link });
+      continue;
+    }
+
+    const groupItems = groups.get(resolvedCategory) ?? [];
+    groupItems.push({ label, link });
+    groups.set(resolvedCategory, groupItems);
+  }
+
+  // Convert the groups map to an array while preserving the original order of categories
+  const orderedGroups = [...groups.entries()].map(([groupName, items]) => ({
+    groupName,
+    items,
+  }));
+
+  if (others.length > 0) {
+    orderedGroups.push({ groupName: defaultGroupName, items: others });
+  }
+
+  return orderedGroups;
+};
+
+/**
+ * Converts page entries to sidebar items with resolved links based on current page metadata.
+ * @param {Array<[string, string, string?]>} pages
+ * @param {{ path: string, basename: string }} metadata
+ * @returns {Array<{ label: string, link: string, category?: string }>}
+ */
+export const getSidebarItems = (pages, metadata) =>
+  pages.map(([heading, path, category]) => ({
+    label: heading,
+    link:
+      metadata.path === path
+        ? `${metadata.basename}.html`
+        : `${relative(path, metadata.path)}.html`,
+    category,
+  }));
+
+/**
+ * Extracts the major version number from a version string.
+ * @param {string} v - Version string (e.g., 'v14.0.0', '14.0.0')
+ * @returns {number}
+ */
+export const getMajorVersion = v =>
+  parseInt(String(v).match(/\d+/)?.[0] ?? '0', 10);
+
+/**
+ * Filters pre-computed versions by compatibility and resolves per-page URL based on metadata.
+ * @param {Array<{ major: number, url: string, label: string }>} versions
+ * @param {{ added?: string, introduced_in?: string, path: string }} metadata
+ * @returns {Array<{ value: string, label: string }>}
+ */
+export const getCompatibleVersions = (versions, metadata) => {
+  const introducedMajor = getMajorVersion(
+    metadata.added ?? metadata.introduced_in
+  );
+
+  // Filter pre-computed versions by compatibility and resolve per-page URL
+  return versions
+    .filter(v => v.major >= introducedMajor)
+    .map(({ url, label }) => ({
+      value: url.replace('{path}', metadata.path),
+      label,
+    }));
+};
+
+/**
+ * Redirect to a URL
+ * @param {string} url URL
+ */
+export const redirect = url => (window.location.href = url);