docs(chore): Standard HTML attributes note (#2289)

* refactored to include MDN and htmlElement in each component's frontmatter

* escape < and >

* change MDN to mdnUrl for consistency with frontmatter naming

* modify getFrontmatter to grab all frontmatter

* fixed small bug

* added error handling for fs.readFileSync

* refactored getFrontmatter to handle error

Co-authored-by: Joe Buono <[email protected]>

Author: joebuono

docs/scripts/generate-props-tables.ts

@@ -1,8 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import { globbyStream } from 'globby';
-import { getCatalog } from './util/getCatalog';
-import { getAllTypesData } from './util/getAllTypesData';
+import { getAllTypesData, getCatalog, getFrontmatter } from './util';
 import type {
   Catalog,
   Category,
@@ -14,7 +13,6 @@ import { capitalizeString } from '@/utils/capitalizeString';
 
 const catalog = getCatalog();
 const { allTypeFilesInterfaceData } = getAllTypesData();
-debugger;
 
 createAllPropsTables();
 
@@ -62,13 +60,15 @@ async function createAllPropsTables() {
 
     if (!mainTableAndExpander) continue;
 
+    const { mdnUrl, htmlElement } = getFrontmatter(componentFilepath as string);
+
     fs.writeFileSync(
       path.join(
         __dirname,
         '../../docs/src/pages/[platform]/components/',
         `./${componentPageName}/props-table.mdx`
       ),
-      Output(componentName, tableAndExpanders)
+      Output(componentName, tableAndExpanders, mdnUrl, htmlElement)
     );
     console.log(`✅ ${componentPageName} Props Tables are updated.`);
   }
@@ -78,10 +78,7 @@ type CategoryProperty = { [key in Category]: Properties };
 type SortedPropertiesByCategory = { [key: string]: Properties }[];
 type PropertiesByCategory = Record<Category, Properties>;
 
-/**
- * @todo After Marketing Launch 2022-06, to update the note under the Props Heading to specify the HTML element's name and MDN link. Ticket: https://app.asana.com/0/1201736086077838/1202477702049308/f
- */
-function Output(displayName, tableAndExpanders) {
+function Output(displayName, tableAndExpanders, mdnUrl, htmlElement) {
   return `
 {/* DO NOT EDIT DIRECTLY */}
 {/* This file is autogenerated by "docs/scripts/generate-props-tables.ts" script. */}
@@ -92,7 +89,11 @@ ${tableAndExpanders.join('')}
 
 See [Style Props](/react/theming/style-props) for all supported style and layout properties.
 
-The ${displayName} component will accept any of the standard HTML attributes that a HTML element accepts. Standard element attributes can be found in the <Link href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element" isExternal={true}>MDN Documentation</Link>.
+${displayName} will also accept any of the standard HTML attributes that a <code>\\<${
+    htmlElement || 'div'
+  }\\></code> element accepts, which can be found in the <Link href="${
+    mdnUrl || 'https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div'
+  }" isExternal>MDN Documentation</Link>.
 `;
 }
 

docs/scripts/util/getFrontmatter.ts

@@ -0,0 +1,48 @@
+import fs from 'fs';
+import { MetaInfo } from '@/data/meta';
+
+/*
+
+Returns the frontmatter as an object of key/value pairs. For example:
+
+Input (string):
+
+---
+title: Flex
+mdnUrl: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div
+htmlElement: div
+---
+
+Output (object):
+
+{
+  title: 'Flex',
+  mdnUrl: 'https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div',
+  htmlElement: 'div',
+}
+
+*/
+
+export function getFrontmatter(componentFilepath: string) {
+  let fileData = '';
+  try {
+    fileData = fs.readFileSync(componentFilepath, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      console.log('File not found!');
+    } else {
+      throw err;
+    }
+  }
+
+  if (!fileData) {
+    return {};
+  }
+
+  const frontmatter = fileData.split('---')[1].trim().split('\n');
+
+  return frontmatter.reduce((acc, line) => {
+    const [key, value] = line.split(': ');
+    return { ...acc, [key]: value };
+  }, {}) as MetaInfo;
+}

docs/scripts/util/index.ts

@@ -0,0 +1,4 @@
+export { getAllTypesData } from './getAllTypesData';
+export { getCatalog } from './getCatalog';
+export { getFrontmatter } from './getFrontmatter';
+export { sanitize } from './sanitize';

docs/src/data/meta.ts

@@ -5,6 +5,8 @@ export interface MetaInfo {
       description?: string;
       metaTitle?: string;
       metaDescription?: string;
+      mdnUrl?: string;
+      htmlElement?: string;
       supportedFrameworks?: string;
       slug?: string;
     };

docs/src/pages/[platform]/components/alert/index.page.mdx

@@ -4,6 +4,8 @@ description: Alert displays a brief message in a way that attracts the user’s
 ariaPattern: https://www.w3.org/WAI/ARIA/apg/patterns/alert
 themeSource: packages/ui/src/theme/tokens/components/alert.ts
 reactSource: packages/react/src/primitives/Alert/Alert.tsx
+mdnUrl: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div
+htmlElement: div
 supportedFrameworks: react
 ---
 

docs/src/pages/[platform]/components/alert/props-table.mdx

@@ -382,4 +382,4 @@ ResponsiveStyle<Property.FlexWrap>
 
 See [Style Props](/react/theming/style-props) for all supported style and layout properties.
 
-The Alert component will accept any of the standard HTML attributes that a HTML element accepts. Standard element attributes can be found in the <Link href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element" isExternal={true}>MDN Documentation</Link>.
+Alert will also accept any of the standard HTML attributes that a <code>\<div\></code> element accepts, which can be found in the <Link href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div" isExternal>MDN Documentation</Link>.

docs/src/pages/[platform]/components/badge/index.page.mdx

@@ -3,6 +3,8 @@ title: Badge
 description: Badge is a color-coded element used to display a status or message about an item.
 themeSource: packages/ui/src/theme/tokens/components/badge.ts
 reactSource: packages/react/src/primitives/Badge/Badge.tsx
+mdnUrl: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span
+htmlElement: span
 supportedFrameworks: react
 ---
 

docs/src/pages/[platform]/components/badge/props-table.mdx

@@ -262,4 +262,4 @@ ResponsiveStyle<Property.FlexShrink>
 
 See [Style Props](/react/theming/style-props) for all supported style and layout properties.
 
-The Badge component will accept any of the standard HTML attributes that a HTML element accepts. Standard element attributes can be found in the <Link href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element" isExternal={true}>MDN Documentation</Link>.
+Badge will also accept any of the standard HTML attributes that a <code>\<span\></code> element accepts, which can be found in the <Link href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span" isExternal>MDN Documentation</Link>.

docs/src/pages/[platform]/components/button/index.page.mdx

@@ -4,6 +4,8 @@ description: Button allows users to perform actions.
 ariaPattern: https://www.w3.org/WAI/ARIA/apg/patterns/button
 themeSource: packages/ui/src/theme/tokens/components/button.ts
 reactSource: packages/react/src/primitives/Button/Button.tsx
+mdnUrl: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button
+htmlElement: button
 supportedFrameworks: react
 ---
 

docs/src/pages/[platform]/components/button/props-table.mdx

@@ -492,4 +492,4 @@ ResponsiveStyle<Property.FlexWrap>
 
 See [Style Props](/react/theming/style-props) for all supported style and layout properties.
 
-The Button component will accept any of the standard HTML attributes that a HTML element accepts. Standard element attributes can be found in the <Link href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element" isExternal={true}>MDN Documentation</Link>.
+Button will also accept any of the standard HTML attributes that a <code>\<button\></code> element accepts, which can be found in the <Link href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button" isExternal>MDN Documentation</Link>.