feat(api-history): minor table styling

electron · dsanders11 · Aug 12, 2024 · Jun 1, 2024 · Jun 3, 2024 · Jun 4, 2024
commit f1e9b096593e384915e94153e86907f741de59c8
@@ -256,3 +256,27 @@
 .navbar__logo {
   width: 2rem;
 }
+
+// TODO: Test these on mobile
+details.api-history {
+  transform: translateY(
+    calc(
+      var(--ifm-heading-vertical-rhythm-bottom) * var(--ifm-leading) * -0.5
+    )
+  );
+
+  summary {
+    width: fit-content;
+    font-weight: normal;
+    font-style: italic;
+
+    &:hover {
+      cursor: pointer;
+    }
+  }
+
+  table {
+    margin-top: 0.5rem;
+    margin-bottom: 0;
+  }
+}
@@ -1,109 +1,186 @@
-import { InlineCode, Link, Parent, Table, TableRow } from 'mdast';
-import { MdxJsxFlowElement } from 'mdast-util-mdx-jsx';
-import { parse as parseYaml } from 'yaml'
+import {
+  BlockContent,
+  DefinitionContent,
+  InlineCode,
+  Link,
+  Node,
+  RootContentMap,
+  TableRow,
+} from 'mdast';
+import {
+  MdxJsxAttribute,
+  MdxJsxExpressionAttribute,
+  MdxJsxFlowElementData,
+} from 'mdast-util-mdx-jsx';
+import { parse as parseYaml } from 'yaml';
 
 enum Change {
-  ADDED = "API ADDED",
-  CHANGED = "API CHANGED",
-  DEPRECATED = "API DEPRECATED",
-  REMOVED = "API REMOVED",
+  ADDED = 'API ADDED',
+  CHANGED = 'API CHANGED',
+  DEPRECATED = 'API DEPRECATED',
+  REMOVED = 'API REMOVED',
 }
 
 type ApiHistory = {
   added?: { 'pr-url': string }[];
-  deprecated?: { 'pr-url': string, 'breaking-changes-header': string }[];
-  removed?: { 'pr-url': string, 'breaking-changes-header': string }[];
-  changes?: { 'pr-url': string, description: string }[];
-}
+  deprecated?: { 'pr-url': string; 'breaking-changes-header': string }[];
+  removed?: { 'pr-url': string; 'breaking-changes-header': string }[];
+  changes?: { 'pr-url': string; description: string }[];
+};
 
 export default function attacher() {
   return transformer;
 }
 
 // TODO: Add styling based on type
-const generateTableRow = (type: Change, prUrl: string, changes?: string) => ({
-    type: "tableRow",
+const generateTableRow = (type: Change, prUrl: string, changes?: string) =>
+  ({
+    type: 'tableRow',
     children: [
       {
-        type: "tableCell",
+        type: 'tableCell',
         children: [
           {
-            type: "link",
+            type: 'link',
             title: null,
             url: prUrl,
-            children: [ { type: "inlineCode", value: '#' + prUrl.split("/").at(-1) } ],
+            children: [
+              { type: 'inlineCode', value: '#' + prUrl.split('/').at(-1) },
+            ],
           },
         ],
       },
       {
-        type: "tableCell",
+        type: 'tableCell',
         children: [
           // TODO: Handle formatting for inline code in changes. Maybe support full markdown?
-          { type: "text", value: changes || type },
+          ...(changes
+            ? [{ type: 'text', value: changes }]
+            : [{ type: 'inlineCode', value: type }]),
         ],
       },
     ],
-  } as TableRow
-)
+  } as TableRow);
 
-function transformer(tree: Parent) {
+// ! Typescript witchcraft to avoid adding `remark-mdx` as a dependency <https://mdxjs.com/packages/remark-mdx/#types>
+interface MdxJsxFlowElementWithSummary extends ParentWithMdxJsxFlowElement {
+  type: 'mdxJsxFlowElement';
+  name: string | null;
+  attributes: Array<MdxJsxAttribute | MdxJsxExpressionAttribute>;
+  children: Array<
+    | BlockContent
+    | DefinitionContent
+    | MdxJsxFlowElementWithSummary
+    | { type: 'text'; value: string }
+  >;
+  data?: MdxJsxFlowElementData | undefined;
+}
+interface RootContentMapWithMdxJsxFlowElement extends RootContentMap {
+  mdxJsxFlowElement: MdxJsxFlowElementWithSummary;
+}
+type RootContentWithMdxJsxFlowElement =
+  RootContentMapWithMdxJsxFlowElement[keyof RootContentMapWithMdxJsxFlowElement];
+interface ParentWithMdxJsxFlowElement extends Node {
+  children: Array<RootContentWithMdxJsxFlowElement>;
+}
+
+function transformer(tree: ParentWithMdxJsxFlowElement) {
   for (let nodeIdx = 0; nodeIdx < tree.children.length; nodeIdx++) {
     const node = tree.children[nodeIdx];
 
-    const isYamlHistoryCodeBlock = node.type === 'code' && node.lang === 'YAML' && node.meta === 'history';
+    const isYamlHistoryCodeBlock =
+      node.type === 'code' && node.lang === 'YAML' && node.meta === 'history';
     if (!isYamlHistoryCodeBlock) continue;
 
     // TODO: Handle validation
     const apiHistory = parseYaml(node.value) as ApiHistory;
 
     // ? Maybe this is too much abstraction?
-    let apiHistoryChangeRows: TableRow[] = [
-      ...(apiHistory.added?.map(added => generateTableRow(Change.ADDED, added['pr-url'])) ?? []),
-      ...(apiHistory.changes?.map(change => generateTableRow(Change.CHANGED, change['pr-url'], change['description'])) ?? []),
-      ...(apiHistory.deprecated?.map(deprecated => generateTableRow(Change.DEPRECATED, deprecated['pr-url'])) ?? []),
-      ...(apiHistory.removed?.map(removed => generateTableRow(Change.REMOVED, removed['pr-url'])) ?? []),
+    const apiHistoryChangeRows: TableRow[] = [
+      ...(apiHistory.added?.map((added) =>
+        generateTableRow(Change.ADDED, added['pr-url'])
+      ) ?? []),
+      ...(apiHistory.changes?.map((change) =>
+        generateTableRow(
+          Change.CHANGED,
+          change['pr-url'],
+          change['description']
+        )
+      ) ?? []),
+      ...(apiHistory.deprecated?.map((deprecated) =>
+        generateTableRow(Change.DEPRECATED, deprecated['pr-url'])
+      ) ?? []),
+      ...(apiHistory.removed?.map((removed) =>
+        generateTableRow(Change.REMOVED, removed['pr-url'])
+      ) ?? []),
     ];
 
     // Sort by PR number, lower number on bottom of table
     apiHistoryChangeRows.sort((a, b) => {
-      const aPrNumber = parseInt(((a.children[0].children[0] as Link).children[0] as InlineCode).value.slice(1));
-      const bPrNumber = parseInt(((b.children[0].children[0] as Link).children[0] as InlineCode).value.slice(1));
+      const aPrNumber = parseInt(
+        (
+          (a.children[0].children[0] as Link).children[0] as InlineCode
+        ).value.slice(1)
+      );
+      const bPrNumber = parseInt(
+        (
+          (b.children[0].children[0] as Link).children[0] as InlineCode
+        ).value.slice(1)
+      );
       return bPrNumber - aPrNumber;
-    })
+    });
 
     const apiHistoryDetails = {
-      type: "mdxJsxFlowElement",
-      // TODO: Maybe use a custom element? Change "Details" at least.
-      name: "Details",
-      attributes: [],
+      type: 'mdxJsxFlowElement',
+      name: 'details',
+      attributes: [
+        {
+          type: 'mdxJsxAttribute',
+          name: 'class',
+          value: 'api-history',
+        },
+      ],
       children: [
         {
-          type: "table",
-          align: [ "center", "center" ],
+          type: 'mdxJsxFlowElement',
+          name: 'summary',
+          attributes: [],
+          children: [
+            {
+              type: 'text',
+              value: 'History',
+            },
+          ],
+          data: {
+            _mdxExplicitJsx: true,
+          },
+        },
+        {
+          type: 'table',
+          align: ['center', 'center'],
           children: [
             {
-              type: "tableRow",
+              type: 'tableRow',
               children: [
                 {
-                  type: "tableCell",
-                  children: [ { type: "text", value: "Version" } ],
+                  type: 'tableCell',
+                  children: [{ type: 'text', value: 'PR' }],
                 },
                 {
-                  type: "tableCell",
-                  children: [ { type: "text", value: "Changes" } ],
+                  type: 'tableCell',
+                  children: [{ type: 'text', value: 'Changes' }],
                 },
               ],
             },
             ...apiHistoryChangeRows,
           ],
-        } satisfies Table,
+        },
       ],
       data: {
         _mdxExplicitJsx: true,
       },
-    } satisfies MdxJsxFlowElement
+    } satisfies MdxJsxFlowElementWithSummary;
 
-    // TODO: Find better type than 'any'
-    tree.children[nodeIdx] = apiHistoryDetails as any;
+    tree.children[nodeIdx] = apiHistoryDetails;
   }
 }