chore(docs): add custom data reference tests

Signed-off-by: John Yanarella <jyanarella@nvidia.com>

Author: johnyanarella

projects/site/src/docs/custom-data.test.ts

@@ -0,0 +1,217 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import{readFile,readdir}from'node:fs/promises';
+import{dirname,join,relative,resolve}from'node:path';
+import{describe,expect,it}from'vitest';
+
+constDOCUMENTATION_BASE_URL='https://nvidia.github.io/elements/';
+constCUSTOM_DATA_SCHEMA_URL=
+'https://raw.githubusercontent.com/microsoft/vscode-html-languageservice/main/docs/customData.schema.json';
+constDOCUMENTATION_ROOT=import.meta.dirname;
+constPROJECTS_ROOT=resolve(DOCUMENTATION_ROOT,'../../..');
+
+interfaceComponentDocumentation{
+tag: string;
+url: string;
+}
+
+interfaceCustomDataReference{
+name: string;
+url: string;
+}
+
+interfaceCustomDataTag{
+name: string;
+references?: CustomDataReference[];
+}
+
+interfaceHtmlCustomData{
+$schema: string;
+tags?: CustomDataTag[];
+version: number;
+}
+
+interfaceCustomElementDeclaration{
+metadata?: Record<string,unknown>;
+tagName?: string;
+}
+
+interfaceCustomElementsManifest{
+modules: {
+declarations?: CustomElementDeclaration[];
+}[];
+}
+
+interfaceProjectPackage{
+customElements?: string;
+name?: string;
+}
+
+describe('HTML Custom Data references',()=>{
+it('uses the V1 reference shape with valid HTTPS URLs',async()=>{
+for(constcustomDataofawaitgetCustomData()){
+expect(customData.$schema).toBe(CUSTOM_DATA_SCHEMA_URL);
+expect(customData.version).toBe(1.1);
+
+for(consttagofcustomData.tags??[]){
+for(constreferenceoftag.references??[]){
+expect(reference).toMatchObject({
+name: expect.any(String),
+url: expect.any(String)
+});
+expect(newURL(reference.url).protocol).toBe('https:');
+}
+}
+}
+});
+
+it('maps CEM ARIA metadata to the WAI-ARIA Reference label',async()=>{
+constdeclarationsByTag=awaitgetManifestDeclarations();
+constcustomDataTagsByName=newMap(
+(awaitgetCustomData()).flatMap(customData=>(customData.tags??[]).map(tag=>[tag.name,tag]))
+);
+
+for(const[tagName,declaration]ofdeclarationsByTag){
+consturl=declaration.metadata?.aria;
+if(!isHttpsUrl(url)){
+continue;
+}
+
+expect(customDataTagsByName.get(tagName)?.references).toContainEqual({name: 'WAI-ARIA Reference', url });
+}
+});
+
+it('generates canonical references for every documented public tag',async()=>{
+constdocumentation=awaitgetComponentDocumentation();
+constdeclarationsByTag=awaitgetManifestDeclarations();
+constcustomDataTagsByName=newMap(
+(awaitgetCustomData()).flatMap(customData=>(customData.tags??[]).map(tag=>[tag.name,tag]))
+);
+
+expect(documentation.length).toBeGreaterThan(0);
+
+for(constcomponentofdocumentation){
+expect(declarationsByTag.get(component.tag)?.metadata?.documentation).toBe(component.url);
+
+consttag=customDataTagsByName.get(component.tag);
+expect(tag?.references).toContainEqual({name: 'Documentation',url: component.url});
+
+consturl=newURL(component.url);
+expect(url.origin).toBe('https://nvidia.github.io');
+expect(url.pathname).toMatch(/^\/elements\/docs\//);
+}
+});
+});
+
+asyncfunctiongetComponentDocumentation(): Promise<ComponentDocumentation[]>{
+constfiles=[
+ ...(awaitgetTopLevelMarkdownFiles(join(DOCUMENTATION_ROOT,'elements'))),
+join(DOCUMENTATION_ROOT,'elements/data-grid/index.md'),
+ ...(awaitgetTopLevelMarkdownFiles(join(DOCUMENTATION_ROOT,'code'))),
+ ...(awaitgetTopLevelMarkdownFiles(join(DOCUMENTATION_ROOT,'monaco'))),
+ ...(awaitgetTopLevelMarkdownFiles(join(DOCUMENTATION_ROOT,'media'))),
+join(DOCUMENTATION_ROOT,'markdown/index.md')
+];
+
+constdocumentation=awaitPromise.all(
+files.map(asyncfile=>{
+constcontent=awaitreadFile(file,'utf8');
+consttags=[
+content.match(/tag:\s*'([^']+)'/)?.[1],
+ ...[...(content.match(/associatedElements:\s*\[([\s\S]*?)\]/)?.[1]?.matchAll(/'([^']+)'/g)??[])].map(
+match=>match[1]
+)
+].filter((tag): tag is string=>!!tag);
+
+returntags.map(tag=>({ tag,url: getDocumentationUrl(file)}));
+})
+);
+
+return[...newMap(documentation.flat().map(component=>[component.tag,component])).values()];
+}
+
+asyncfunctiongetCustomData(): Promise<HtmlCustomData[]>{
+constcustomData=awaitPromise.all(
+(awaitgetElementsPackages()).map(async({ customElements, directory })=>{
+try{
+constdataPath=join(directory,dirname(customElements),'data.html.json');
+returnJSON.parse(awaitreadFile(dataPath,'utf8'))asHtmlCustomData;
+}catch{
+returnnull;
+}
+})
+);
+
+returncustomData.filter((data): data is HtmlCustomData=>data!==null);
+}
+
+asyncfunctiongetManifestDeclarations(): Promise<Map<string,CustomElementDeclaration>>{
+constmanifests=awaitPromise.all(
+(awaitgetElementsPackages()).map(async({ customElements, directory })=>{
+returnJSON.parse(awaitreadFile(join(directory,customElements),'utf8'))asCustomElementsManifest;
+})
+);
+
+returnnewMap(
+manifests.flatMap(manifest=>
+manifest.modules.flatMap(module=>
+(module.declarations??[])
+.filter((declaration): declaration is CustomElementDeclaration&{tagName: string}=>!!declaration.tagName)
+.map(declaration=>[declaration.tagName,declaration])
+)
+)
+);
+}
+
+asyncfunctiongetElementsPackages(): Promise<{customElements: string;directory: string}[]>{
+constdirectories=awaitreaddir(PROJECTS_ROOT,{withFileTypes: true});
+constpackages=awaitPromise.all(
+directories
+.filter(directory=>directory.isDirectory())
+.map(asyncdirectory=>{
+constprojectDirectory=join(PROJECTS_ROOT,directory.name);
+try{
+constpackageJson=JSON.parse(
+awaitreadFile(join(projectDirectory,'package.json'),'utf8')
+)asProjectPackage;
+returnpackageJson.name?.startsWith('@nvidia-elements/')&&packageJson.customElements
+ ? {customElements: packageJson.customElements,directory: projectDirectory}
+ : null;
+}catch{
+returnnull;
+}
+})
+);
+
+returnpackages.filter((project): project is {customElements: string;directory: string}=>project!==null);
+}
+
+asyncfunctiongetTopLevelMarkdownFiles(directory: string): Promise<string[]>{
+try{
+constentries=awaitreaddir(directory,{withFileTypes: true});
+returnentries
+.filter(entry=>entry.isFile()&&entry.name.endsWith('.md'))
+.map(entry=>join(directory,entry.name));
+}catch{
+return[];
+}
+}
+
+functiongetDocumentationUrl(file: string): string{
+constfilePath=relative(DOCUMENTATION_ROOT,file).replace(/\.md$/,'');
+constroute=filePath.endsWith('/index') ? filePath.slice(0,-'/index'.length) : filePath;
+returnnewURL(`docs/${route}/`,DOCUMENTATION_BASE_URL).href;
+}
+
+functionisHttpsUrl(value: unknown): value is string{
+if(typeofvalue!=='string'){
+returnfalse;
+}
+
+try{
+returnnewURL(value).protocol==='https:';
+}catch{
+returnfalse;
+}
+}