add descriptions to table and get rid of unessasary isRelative

Author: LFDanLu

packages/dev/s2-docs/pages/s2/Reference.mdx

@@ -37,8 +37,6 @@ Size props like `width` and `height` accept arbitrary pixel values. Values are c
 
 ## Text
 
-// TODO: edit copy
-
 Spectrum 2 typography can be applied via the `font` [shorthand](#shorthand), which sets `fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, and `color`. You can override any of these individually.
 
 ```tsx

packages/dev/s2-docs/src/styleProperties.ts

@@ -392,6 +392,7 @@ export const spacingTypeValues = {
   negativeSpacing: negativeBaseSpacingValues
 };
 
+// a mapping of value to relative links that should be replaced in place
 // opted NOT to link to Fonts from 'ui', 'code', etc since the visual example
 // is so close to the area in the table where those are rendered
 const relativeLinks: {[key: string]: string} = {
@@ -402,48 +403,46 @@ const relativeLinks: {[key: string]: string} = {
   'baseColors': '#colors'
 }
 
+// a mapping of value to mdn links that should be replaced in place
 const mdnTypeLinks: {[key: string]: string} = {
   'string': 'https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String',
   'number': 'https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number'
 };
 
-const mdnPropertyLinks: {[key: string]: {[value: string]: {href: string, isRelative?: boolean}}} = {
+// a mapping of value to links that should be replaced in place with the provided string
+const mdnPropertyLinks: {[key: string]: {[value: string]: string}} = {
   'flexShrink': {
-    'number': {
-      href: 'https://developer.mozilla.org/en-US/docs/Web/CSS/flex-shrink',
-    }
+    'number':  'https://developer.mozilla.org/en-US/docs/Web/CSS/flex-shrink'
   },
   'flexGrow': {
-    'number': {
-      href: 'https://developer.mozilla.org/en-US/docs/Web/CSS/flex-grow'
-    }
+    'number': 'https://developer.mozilla.org/en-US/docs/Web/CSS/flex-grow'
   },
   'gridColumnStart': {
-    'string': {
-      href: 'https://developer.mozilla.org/en-US/docs/Web/CSS/grid-column-start'
-    }
+    'string': 'https://developer.mozilla.org/en-US/docs/Web/CSS/grid-column-start'
   },
   'gridColumnEnd': {
-    'string': {
-      href: 'https://developer.mozilla.org/en-US/docs/Web/CSS/grid-column-end'
-    }
+    'string': 'https://developer.mozilla.org/en-US/docs/Web/CSS/grid-column-end'
   },
   'gridRowStart': {
-    'string': {
-      href: 'https://developer.mozilla.org/en-US/docs/Web/CSS/grid-row-start'
-    }
+    'string': 'https://developer.mozilla.org/en-US/docs/Web/CSS/grid-row-start'
   },
   'gridRowEnd': {
-    'string': {
-      href: 'https://developer.mozilla.org/en-US/docs/Web/CSS/grid-row-end'
-    }
+    'string': 'https://developer.mozilla.org/en-US/docs/Web/CSS/grid-row-end'
   }
 };
 
+const propertyDescriptions: {[key: string]: string} = {
+  'rotate': 'Accepts a number (treated as degrees) or a string with units (deg, rad, grad, turn).',
+  'scaleX': 'Accepts a number or percentage string.',
+  'scaleY': 'Accepts a number or percentage string.',
+  'aspectRatio': 'Also accepts a ratio in the format number/number (e.g., 16/9, 4/3).'
+};
+
 interface StyleMacroPropertyDefinition {
   values: string[],
   additionalTypes?: string[],
-  links?: {[value: string]: {href: string, isRelative?: boolean}}
+  links?: {[value: string]: {href: string, isRelative?: boolean}},
+  description?: string
 }
 
 export function getPropertyDefinitions(propertyCategory: string): {[key: string]: StyleMacroPropertyDefinition} {
@@ -454,8 +453,9 @@ export function getPropertyDefinitions(propertyCategory: string): {[key: string]
     let links: {[value: string]: {href: string, isRelative?: boolean}} = {};
 
     if (mdnPropertyLinks[name]) {
-      links = {...mdnPropertyLinks[name]};
-      values = [Object.keys(links)[0]];
+      let [key, value] = Object.entries(mdnPropertyLinks[name])[0];
+      links[key] = {href: value};
+      values = [key];
     } else {
       // see if the property has any common types that should link to MDN instead
       for (let value of values) {
@@ -475,7 +475,8 @@ export function getPropertyDefinitions(propertyCategory: string): {[key: string]
     result[name] = {
       values,
       additionalTypes: getAdditionalTypes(name),
-      links: Object.keys(links).length > 0 ? links : undefined
+      links: Object.keys(links).length > 0 ? links : undefined,
+      description: propertyDescriptions[name]
     };
   }
   return result;

packages/dev/s2-docs/src/types.tsx

@@ -754,14 +754,14 @@ function StyleMacroTypePopover({typeName, description, body}: StyleMacroTypePopo
 interface StyleMacroPropertyDefinition {
   values: string[],
   additionalTypes?: string[],
-  links?: {[value: string]: {href: string, isRelative?: boolean}}
+  links?: {[value: string]: {href: string, isRelative?: boolean}},
+  description?: string
 }
 
 interface StyleMacroPropertiesProps {
   properties: {[propertyName: string]: StyleMacroPropertyDefinition}
 }
 
-// TODO: fix the width of the columns so that they are consistent
 export function StyleMacroProperties({properties}: StyleMacroPropertiesProps) {
   let propertyNames = Object.keys(properties);
 
@@ -780,62 +780,65 @@ export function StyleMacroProperties({properties}: StyleMacroPropertiesProps) {
           let links = propDef.links || {};
 
           return (
-            <TableRow key={index}>
-              <TableCell role="rowheader">
-                <code className={codeStyle}>
-                  <span className={codeStyles.attribute}>{propertyName}</span>
-                </code>
-              </TableCell>
-              <TableCell>
-                <code className={codeStyle}>
-                  {values.map((value, i) => (
-                    <React.Fragment key={i}>
-                      {i > 0 && <Punctuation>{' | '}</Punctuation>}
-                      {links[value] ? (
-                        <ColorLink
-                          href={links[value].href}
-                          type="variable"
-                          rel={links[value].isRelative ? undefined : "noreferrer"}
-                          target={links[value].isRelative ? undefined : "_blank"}>
-                          {value}
-                        </ColorLink>
-                      ) : (
-                        <span className={codeStyles.string}>'{value}'</span>
-                      )}
-                    </React.Fragment>
-                  ))}
-                  {propDef.additionalTypes && propDef.additionalTypes.map((typeName, i) => {
-                    let typeLink = styleMacroTypeLinks[typeName];
-                    return (
-                      <React.Fragment key={`type-${i}`}>
-                        {(values.length > 0 || i > 0) && <Punctuation>{' | '}</Punctuation>}
-                        {typeLink ? (
-                          // only if the type link has a description and/or body do we want to render the type popover
-                          // this is to make things like baseColor
-                          typeLink.link && !typeLink.description && !typeLink.body ? (
-                            <ColorLink href={typeLink.link} type="variable">{typeName}</ColorLink>
-                          ) : (
-                            <StyleMacroTypePopover
-                              typeName={typeName}
-                              description={typeLink.description}
-                              body={typeLink.body} />
-                          )
-                        ) : undefined}
+            <React.Fragment key={index}>
+              <TableRow>
+                <TableCell role="rowheader" hideBorder={!!propDef.description}>
+                  <code className={codeStyle}>
+                    <span className={codeStyles.attribute}>{propertyName}</span>
+                  </code>
+                </TableCell>
+                <TableCell hideBorder={!!propDef.description}>
+                  <code className={codeStyle}>
+                    {values.map((value, i) => (
+                      <React.Fragment key={i}>
+                        {i > 0 && <Punctuation>{' | '}</Punctuation>}
+                        {links[value] ? (
+                          <ColorLink
+                            href={links[value].href}
+                            type="variable"
+                            rel={links[value].isRelative ? undefined : "noreferrer"}
+                            target={links[value].isRelative ? undefined : "_blank"}>
+                            {value}
+                          </ColorLink>
+                        ) : (
+                          <span className={codeStyles.string}>'{value}'</span>
+                        )}
                       </React.Fragment>
-                    );
-                  })}
-                </code>
-              </TableCell>
-            </TableRow>
+                    ))}
+                    {propDef.additionalTypes && propDef.additionalTypes.map((typeName, i) => {
+                      let typeLink = styleMacroTypeLinks[typeName];
+                      return (
+                        <React.Fragment key={`type-${i}`}>
+                          {(values.length > 0 || i > 0) && <Punctuation>{' | '}</Punctuation>}
+                          {typeLink ? (
+                            // only if the type link has a description and/or body do we want to render the type popover
+                            // this is to make things like baseColor
+                            typeLink.link && !typeLink.description && !typeLink.body ? (
+                              <ColorLink href={typeLink.link} type="variable">{typeName}</ColorLink>
+                            ) : (
+                              <StyleMacroTypePopover
+                                typeName={typeName}
+                                description={typeLink.description}
+                                body={typeLink.body} />
+                            )
+                          ) : undefined}
+                        </React.Fragment>
+                      );
+                    })}
+                  </code>
+                </TableCell>
+              </TableRow>
+              {propDef.description && (
+                <TableRow>
+                  <TableCell colSpan={2}>{propDef.description}</TableCell>
+                </TableRow>
+              )}
+            </React.Fragment>
           );
         })}
       </TableBody>
     </Table>
   );
 }
 
-//  same for spacing, perhaps do the type that contains the same explaination, and remove the text blob
-// TODO: add to the table a description col span 2 to describe what things like aspectRatio and such accept (aka This takes a). this exists in the Prop table so look there
-
 // TODO: For the Shorthands, have a column for Name, value (what values it accepts), and mapping where mapping is what properties it maps to
-//