Formatting tweaks

Author: bvaughn

lib/components/grid/types.ts

@@ -22,7 +22,7 @@ export type GridProps<
    * This component will receive an `index` and `style` prop by default.
    * Additionally it will receive prop values passed to `cellProps`.
    *
-   * ⚠️ The prop types for this component are exported as `CellComponentProps`
+   * ℹ️ The prop types for this component are exported as `CellComponentProps`
    */
   cellComponent: (
     props: {
@@ -94,7 +94,7 @@ export type GridProps<
    *
    * This API has imperative methods for scrolling and a getter for the outermost DOM element.
    *
-   * ⚠️ The `useGridRef` and `useGridCallbackRef` hooks are exported for convenience use in TypeScript projects.
+   * ℹ️ The `useGridRef` and `useGridCallbackRef` hooks are exported for convenience use in TypeScript projects.
    */
   gridRef?: Ref<{
     get element(): HTMLDivElement | null;

lib/components/list/types.ts

@@ -45,7 +45,7 @@ export type ListProps<
    *
    * This API has imperative methods for scrolling and a getter for the outermost DOM element.
    *
-   * ⚠️ The `useListRef` and `useListCallbackRef` hooks are exported for convenience use in TypeScript projects.
+   * ℹ️ The `useListRef` and `useListCallbackRef` hooks are exported for convenience use in TypeScript projects.
    */
   listRef?: Ref<{
     get element(): HTMLDivElement | null;
@@ -86,7 +86,7 @@ export type ListProps<
    * This component will receive an `index` and `style` prop by default.
    * Additionally it will receive prop values passed to `rowProps`.
    *
-   * ⚠️ The prop types for this component are exported as `RowComponentProps`
+   * ℹ️ The prop types for this component are exported as `RowComponentProps`
    */
   rowComponent: (
     props: {

public/generated/js-docs/Grid.json

@@ -29,9 +29,9 @@
     "cellComponent": {
       "description": "React component responsible for rendering a cell.<br/><br/>This component will receive an <code>index</code> and <code>style</code> prop by default.\nAdditionally it will receive prop values passed to <code>cellProps</code>.",
       "html": "<div style=\"min-height: 1rem; padding-left: 2ch; text-indent: -2ch;\"><span class=\"tok-labelName\"><span class=\"tok-propertyName\">cellComponent</span></span><span class=\"tok-punctuation\">:</span><span class=\"\"> </span><span class=\"tok-punctuation\">(</span><span class=\"tok-variableName tok-definition\">props</span><span class=\"tok-punctuation\">:</span><span class=\"\"> </span><span class=\"tok-punctuation\">{</span><span class=\"\"> </span><span class=\"tok-propertyName tok-definition\">ariaAttributes</span><span class=\"tok-punctuation\">:</span><span class=\"\"> </span><span class=\"tok-punctuation\">{</span><span class=\"\"> </span><span class=\"tok-string\">\"aria-colindex\"</span><span class=\"tok-punctuation\">:</span><span class=\"\"> </span><span class=\"tok-typeName\">number</span><span class=\"tok-punctuation\">;</span><span class=\"\"> </span><span class=\"tok-propertyName tok-definition\">role</span><span class=\"tok-punctuation\">:</span><span class=\"\"> </span><span class=\"tok-string\">\"gridcell\"</span><span class=\"tok-punctuation\">;</span><span class=\"\"> </span><span class=\"tok-punctuation\">}</span><span class=\"tok-punctuation\">;</span><span class=\"\"> </span><span class=\"tok-propertyName tok-definition\">columnIndex</span><span class=\"tok-punctuation\">:</span><span class=\"\"> </span><span class=\"tok-typeName\">number</span><span class=\"tok-punctuation\">;</span><span class=\"\"> </span><span class=\"tok-propertyName tok-definition\">rowIndex</span><span class=\"tok-punctuation\">:</span><span class=\"\"> </span><span class=\"tok-typeName\">number</span><span class=\"tok-punctuation\">;</span><span class=\"\"> </span><span class=\"tok-propertyName tok-definition\">style</span><span class=\"tok-punctuation\">:</span><span class=\"\"> </span><span class=\"tok-typeName\">CSSProperties</span><span class=\"tok-punctuation\">;</span><span class=\"\"> </span><span class=\"tok-punctuation\">}</span><span class=\"\"> </span><span class=\"tok-operator\">&#38;</span><span class=\"\"> </span><span class=\"tok-typeName\">CellProps</span><span class=\"tok-punctuation\">)</span><span class=\"\"> </span><span class=\"tok-punctuation\">=&#62;</span><span class=\"\"> </span><span class=\"tok-variableName\">ReactNode</span></div>",
+      "info": "The prop types for this component are exported as <code>CellComponentProps</code>",
       "name": "cellComponent",
-      "required": true,
-      "warning": "The prop types for this component are exported as <code>CellComponentProps</code>"
+      "required": true
     },
     "cellProps": {
       "description": "Additional props to be passed to the cell-rendering component.\nGrid will automatically re-render cells when values in this object change.",
@@ -67,9 +67,9 @@
     "gridRef": {
       "description": "Ref used to interact with this component's imperative API.<br/><br/>This API has imperative methods for scrolling and a getter for the outermost DOM element.",
       "html": "<div style=\"min-height: 1rem; padding-left: 2ch; text-indent: -2ch;\"><span class=\"tok-variableName\"><span class=\"tok-propertyName\">gridRef</span></span><span class=\"tok-operator\">?</span><span class=\"tok-punctuation\">:</span><span class=\"\"> </span><span class=\"tok-variableName\">Ref</span><span class=\"\">&#60;</span><span class=\"tok-punctuation\">{</span><span class=\"\"> </span><span class=\"tok-keyword\">readonly</span><span class=\"\"> </span><span class=\"tok-propertyName tok-definition\">element</span><span class=\"tok-punctuation\">:</span><span class=\"\"> </span><span class=\"tok-typeName\">HTMLDivElement</span><span class=\"\"> </span><span class=\"tok-operator\">|</span><span class=\"\"> </span><span class=\"tok-keyword\">null</span><span class=\"tok-punctuation\">;</span><span class=\"\"> </span><span class=\"tok-propertyName tok-definition\">scrollToCell</span><span class=\"tok-punctuation\">(</span><span class=\"tok-variableName tok-definition\">config</span><span class=\"tok-punctuation\">:</span><span class=\"\"> </span><span class=\"tok-punctuation\">{</span><span class=\"\"> </span><span class=\"tok-propertyName tok-definition\">behavior</span><span class=\"\">?</span><span class=\"tok-punctuation\">:</span><span class=\"\"> </span><span class=\"tok-string\">\"auto\"</span><span class=\"\"> </span><span class=\"tok-operator\">|</span><span class=\"\"> </span><span class=\"tok-string\">\"instant\"</span><span class=\"\"> </span><span class=\"tok-operator\">|</span><span class=\"\"> </span><span class=\"tok-string\">\"smooth\"</span><span class=\"\"> </span><span class=\"tok-operator\">|</span><span class=\"\"> </span><span class=\"tok-typeName\">undefined</span><span class=\"tok-punctuation\">;</span><span class=\"\"> </span><span class=\"tok-propertyName tok-definition\">columnAlign</span><span class=\"\">?</span><span class=\"tok-punctuation\">:</span><span class=\"\"> </span><span class=\"tok-string\">\"auto\"</span><span class=\"\"> </span><span class=\"tok-operator\">|</span><span class=\"\"> </span><span class=\"tok-string\">\"center\"</span><span class=\"\"> </span><span class=\"tok-operator\">|</span><span class=\"\"> </span><span class=\"tok-string\">\"end\"</span><span class=\"\"> </span><span class=\"tok-operator\">|</span><span class=\"\"> </span><span class=\"tok-string\">\"smart\"</span><span class=\"\"> </span><span class=\"tok-operator\">|</span><span class=\"\"> </span><span class=\"tok-string\">\"start\"</span><span class=\"\"> </span><span class=\"tok-operator\">|</span><span class=\"\"> </span><span class=\"tok-typeName\">undefined</span><span class=\"tok-punctuation\">;</span><span class=\"\"> </span><span class=\"tok-propertyName tok-definition\">columnIndex</span><span class=\"tok-punctuation\">:</span><span class=\"\"> </span><span class=\"tok-typeName\">number</span><span class=\"tok-punctuation\">;</span><span class=\"\"> </span><span class=\"tok-propertyName tok-definition\">rowAlign</span><span class=\"\">?</span><span class=\"tok-punctuation\">:</span><span class=\"\"> </span><span class=\"tok-string\">\"auto\"</span><span class=\"\"> </span><span class=\"tok-operator\">|</span><span class=\"\"> </span><span class=\"tok-operator\">.</span><span class=\"tok-operator\">.</span><span class=\"tok-operator\">.</span><span class=\"\"> </span><span class=\"tok-number\">4</span><span class=\"\"> </span><span class=\"tok-typeName\">more</span><span class=\"\"> </span><span class=\"tok-operator\">.</span><span class=\"tok-operator\">.</span><span class=\"tok-operator\">.</span><span class=\"\"> </span><span class=\"tok-operator\">|</span><span class=\"\"> </span><span class=\"tok-typeName\">undefined</span><span class=\"tok-punctuation\">;</span><span class=\"\"> </span><span class=\"tok-propertyName tok-definition\">rowIndex</span><span class=\"tok-punctuation\">:</span><span class=\"\"> </span><span class=\"tok-typeName\">number</span><span class=\"tok-punctuation\">;</span><span class=\"\"> </span><span class=\"tok-punctuation\">}</span><span class=\"tok-punctuation\">)</span><span class=\"tok-punctuation\">:</span><span class=\"\"> </span><span class=\"tok-keyword\">void</span><span class=\"tok-punctuation\">;</span><span class=\"\"> </span><span class=\"tok-propertyName tok-definition\">scrollToColumn</span><span class=\"tok-punctuation\">(</span><span class=\"tok-variableName tok-definition\">config</span><span class=\"tok-punctuation\">:</span><span class=\"\"> </span><span class=\"tok-operator\">.</span><span class=\"tok-operator\">.</span><span class=\"tok-operator\">.</span></div>",
+      "info": "The <code>useGridRef</code> and <code>useGridCallbackRef</code> hooks are exported for convenience use in TypeScript projects.",
       "name": "gridRef",
-      "required": false,
-      "warning": "The <code>useGridRef</code> and <code>useGridCallbackRef</code> hooks are exported for convenience use in TypeScript projects."
+      "required": false
     },
     "onCellsRendered": {
       "description": "Callback notified when the range of rendered cells changes.",

public/generated/js-docs/List.json

@@ -29,9 +29,9 @@
     "listRef": {
       "description": "Ref used to interact with this component's imperative API.<br/><br/>This API has imperative methods for scrolling and a getter for the outermost DOM element.",
       "html": "<div style=\"min-height: 1rem; padding-left: 2ch; text-indent: -2ch;\"><span class=\"tok-variableName\"><span class=\"tok-propertyName\">listRef</span></span><span class=\"tok-operator\">?</span><span class=\"tok-punctuation\">:</span><span class=\"\"> </span><span class=\"tok-variableName\">Ref</span><span class=\"\">&#60;</span><span class=\"tok-punctuation\">{</span><span class=\"\"> </span><span class=\"tok-keyword\">readonly</span><span class=\"\"> </span><span class=\"tok-propertyName tok-definition\">element</span><span class=\"tok-punctuation\">:</span><span class=\"\"> </span><span class=\"tok-typeName\">HTMLDivElement</span><span class=\"\"> </span><span class=\"tok-operator\">|</span><span class=\"\"> </span><span class=\"tok-keyword\">null</span><span class=\"tok-punctuation\">;</span><span class=\"\"> </span><span class=\"tok-propertyName tok-definition\">scrollToRow</span><span class=\"tok-punctuation\">(</span><span class=\"tok-variableName tok-definition\">config</span><span class=\"tok-punctuation\">:</span><span class=\"\"> </span><span class=\"tok-punctuation\">{</span><span class=\"\"> </span><span class=\"tok-propertyName tok-definition\">align</span><span class=\"\">?</span><span class=\"tok-punctuation\">:</span><span class=\"\"> </span><span class=\"tok-string\">\"auto\"</span><span class=\"\"> </span><span class=\"tok-operator\">|</span><span class=\"\"> </span><span class=\"tok-string\">\"center\"</span><span class=\"\"> </span><span class=\"tok-operator\">|</span><span class=\"\"> </span><span class=\"tok-string\">\"end\"</span><span class=\"\"> </span><span class=\"tok-operator\">|</span><span class=\"\"> </span><span class=\"tok-string\">\"smart\"</span><span class=\"\"> </span><span class=\"tok-operator\">|</span><span class=\"\"> </span><span class=\"tok-string\">\"start\"</span><span class=\"\"> </span><span class=\"tok-operator\">|</span><span class=\"\"> </span><span class=\"tok-typeName\">undefined</span><span class=\"tok-punctuation\">;</span><span class=\"\"> </span><span class=\"tok-propertyName tok-definition\">behavior</span><span class=\"\">?</span><span class=\"tok-punctuation\">:</span><span class=\"\"> </span><span class=\"tok-string\">\"auto\"</span><span class=\"\"> </span><span class=\"tok-operator\">|</span><span class=\"\"> </span><span class=\"tok-string\">\"instant\"</span><span class=\"\"> </span><span class=\"tok-operator\">|</span><span class=\"\"> </span><span class=\"tok-string\">\"smooth\"</span><span class=\"\"> </span><span class=\"tok-operator\">|</span><span class=\"\"> </span><span class=\"tok-typeName\">undefined</span><span class=\"tok-punctuation\">;</span><span class=\"\"> </span><span class=\"tok-propertyName tok-definition\">index</span><span class=\"tok-punctuation\">:</span><span class=\"\"> </span><span class=\"tok-typeName\">number</span><span class=\"tok-punctuation\">;</span><span class=\"\"> </span><span class=\"tok-punctuation\">}</span><span class=\"tok-punctuation\">)</span><span class=\"tok-punctuation\">:</span><span class=\"\"> </span><span class=\"tok-keyword\">void</span><span class=\"tok-punctuation\">;</span><span class=\"\"> </span><span class=\"tok-punctuation\">}</span><span class=\"\">&#62; </span><span class=\"tok-operator\">|</span><span class=\"\"> </span><span class=\"tok-variableName\">undefined</span></div>",
+      "info": "The <code>useListRef</code> and <code>useListCallbackRef</code> hooks are exported for convenience use in TypeScript projects.",
       "name": "listRef",
-      "required": false,
-      "warning": "The <code>useListRef</code> and <code>useListCallbackRef</code> hooks are exported for convenience use in TypeScript projects."
+      "required": false
     },
     "onResize": {
       "description": "Callback notified when the List's outermost HTMLElement resizes.\nThis may be used to (re)scroll a row into view.",
@@ -54,9 +54,9 @@
     "rowComponent": {
       "description": "React component responsible for rendering a row.<br/><br/>This component will receive an <code>index</code> and <code>style</code> prop by default.\nAdditionally it will receive prop values passed to <code>rowProps</code>.",
       "html": "<div style=\"min-height: 1rem; padding-left: 2ch; text-indent: -2ch;\"><span class=\"tok-labelName\"><span class=\"tok-propertyName\">rowComponent</span></span><span class=\"tok-punctuation\">:</span><span class=\"\"> </span><span class=\"tok-punctuation\">(</span><span class=\"tok-variableName tok-definition\">props</span><span class=\"tok-punctuation\">:</span><span class=\"\"> </span><span class=\"tok-punctuation\">{</span><span class=\"\"> </span><span class=\"tok-propertyName tok-definition\">ariaAttributes</span><span class=\"tok-punctuation\">:</span><span class=\"\"> </span><span class=\"tok-punctuation\">{</span><span class=\"\"> </span><span class=\"tok-string\">\"aria-posinset\"</span><span class=\"tok-punctuation\">:</span><span class=\"\"> </span><span class=\"tok-typeName\">number</span><span class=\"tok-punctuation\">;</span><span class=\"\"> </span><span class=\"tok-string\">\"aria-setsize\"</span><span class=\"tok-punctuation\">:</span><span class=\"\"> </span><span class=\"tok-typeName\">number</span><span class=\"tok-punctuation\">;</span><span class=\"\"> </span><span class=\"tok-propertyName tok-definition\">role</span><span class=\"tok-punctuation\">:</span><span class=\"\"> </span><span class=\"tok-string\">\"listitem\"</span><span class=\"tok-punctuation\">;</span><span class=\"\"> </span><span class=\"tok-punctuation\">}</span><span class=\"tok-punctuation\">;</span><span class=\"\"> </span><span class=\"tok-propertyName tok-definition\">index</span><span class=\"tok-punctuation\">:</span><span class=\"\"> </span><span class=\"tok-typeName\">number</span><span class=\"tok-punctuation\">;</span><span class=\"\"> </span><span class=\"tok-propertyName tok-definition\">style</span><span class=\"tok-punctuation\">:</span><span class=\"\"> </span><span class=\"tok-typeName\">CSSProperties</span><span class=\"tok-punctuation\">;</span><span class=\"\"> </span><span class=\"tok-punctuation\">}</span><span class=\"\"> </span><span class=\"tok-operator\">&#38;</span><span class=\"\"> </span><span class=\"tok-typeName\">RowProps</span><span class=\"tok-punctuation\">)</span><span class=\"\"> </span><span class=\"tok-punctuation\">=&#62;</span><span class=\"\"> </span><span class=\"tok-variableName\">ReactNode</span></div>",
+      "info": "The prop types for this component are exported as <code>RowComponentProps</code>",
       "name": "rowComponent",
-      "required": true,
-      "warning": "The prop types for this component are exported as <code>RowComponentProps</code>"
+      "required": true
     },
     "rowCount": {
       "description": "Number of items to be rendered in the list.",

scripts/compile-docs.ts

@@ -84,11 +84,26 @@ async function run() {
             `<span class="tok-propertyName">${name}</span>`
           );
 
-          const [description, warning = ""] = prop.description.split("⚠️");
+          let description = "";
+          let info = "";
+          let warning = "";
+
+          if (prop.description.includes("⚠️")) {
+            const pieces = prop.description.split("⚠️");
+            description = pieces[0];
+            warning = pieces[1] ?? "";
+          } else if (prop.description.includes("ℹ️")) {
+            const pieces = prop.description.split("ℹ️");
+            description = pieces[0];
+            info = pieces[1] ?? "";
+          } else {
+            description = prop.description;
+          }
 
           componentMetadata.props[name] = {
             description: formatDescriptionText(description.trim()),
             html,
+            info: info ? formatDescriptionText(info.trim()) : undefined,
             name,
             required: prop.required,
             warning: warning ? formatDescriptionText(warning.trim()) : undefined

src/components/props/ComponentPropsSection.tsx

@@ -31,6 +31,11 @@ export function ComponentPropsSection({
                   __html: prop.description
                 }}
               ></div>
+              {prop.info && (
+                <Callout className="mt-4" html intent="primary" minimal>
+                  {prop.info}
+                </Callout>
+              )}
               {prop.warning && (
                 <Callout className="mt-4" html intent="warning" minimal>
                   {prop.warning}

src/types.ts

@@ -3,6 +3,7 @@ export type Intent = "danger" | "none" | "primary" | "success" | "warning";
 export type ComponentPropMetadata = {
   description: string;
   html: string;
+  info?: string;
   name: string;
   required: boolean;
   warning?: string;