docsite - add "note" entry (wix#2244)

* apis - move to "note" attribute

* buidDocs script - add component's "note" and prop's "note" content to render

* Don't render if there's no "note" entry

* fix FloatingButton docs

Co-authored-by: Ethan Sharabi <1780255+ethanshar@users.noreply.github.com>

Author: Inbal-Tish

lib/components/Keyboard/KeyboardInput/keyboardAccessoryView.api.json

@@ -15,8 +15,9 @@
     {
       "name": "kbInputRef",
       "type": "any",
-      "description": "The reference to the actual text input (or the keyboard may not reset when instructed to, etc.).\niOS only.",
-      "required": true
+      "description": "The reference to the actual text input (or the keyboard may not reset when instructed to, etc.).",
+      "required": true,
+      "note": "iOS only"
     },
     {
       "name": "kbComponent",

lib/components/Keyboard/KeyboardTracking/KeyboardTrackingView/keyboardTrackingView.api.json

@@ -27,56 +27,56 @@
     {
       "name": "revealKeyboardInteractive",
       "type": "boolean",
-      "description": "Show the keyboard on a negative scroll\niOS only.",
+      "description": "Show the keyboard on a negative scroll.",
       "note": "iOS only",
       "default": "false"
     },
     {
       "name": "manageScrollView",
       "type": "boolean",
-      "description": "Set to false to turn off inset management and manage it yourself\niOS only.",
+      "description": "Set to false to turn off inset management and manage it yourself.",
       "note": "iOS only",
       "default": "true"
     },
     {
       "name": "requiresSameParentToManageScrollView",
       "type": "boolean",
-      "description": "Set to true manageScrollView is set to true and still does not work,\nit means that the ScrollView found is the wrong one and you'll have\nto have the KeyboardAccessoryView and the ScrollView as siblings\nand set this to true\niOS only.",
+      "description": "Set to true manageScrollView is set to true and still does not work,\nit means that the ScrollView found is the wrong one and you'll have\nto have the KeyboardAccessoryView and the ScrollView as siblings\nand set this to true.",
       "note": "iOS only",
       "default": "false"
     },
     {
       "name": "allowHitsOutsideBounds",
       "type": "boolean",
-      "description": "Allow hitting sub-views that are placed beyond the view bounds\niOS only.",
+      "description": "Allow hitting sub-views that are placed beyond the view bounds.",
       "note": "iOS only",
       "default": "false"
     },
     {
       "name": "addBottomView",
       "type": "boolean",
-      "description": "Add a view beneath the KeyboardAccessoryView\niOS only.",
+      "description": "Add a view beneath the KeyboardAccessoryView.",
       "note": "iOS only",
       "default": "false"
     },
     {
       "name": "bottomViewColor", 
       "type": "string", 
-      "description": "The bottom view's color\niOS only.",       
+      "description": "The bottom view's color.",       
       "note": "iOS only",
       "default": "white"
     },
     {
       "name": "useSafeArea",
       "type": "boolean",
-      "description": "Whether or not to handle SafeArea\niOS only.",
+      "description": "Whether or not to handle SafeArea.",
       "note": "iOS only",
       "default": "true"
     },
     {
       "name": "usesBottomTabs",
       "type": "boolean",
-      "description": "Whether or not to include bottom tab bar inset\niOS only.",
+      "description": "Whether or not to include bottom tab bar inset.",
       "note": "iOS only",
       "default": "false"
     },

scripts/buildDocs.js

@@ -82,6 +82,12 @@ components.forEach(component => {
     content += `:::\n`;
   }
 
+  if (component.note) {
+    content += `:::note\n`;
+    content += `${component.note}\n`;
+    content += `:::\n`;
+  }
+
   /* Images */
   content +=
     `<div style={{display: 'flex', flexDirection: 'row', overflowX: 'auto', maxHeight: '500px', alignItems: 'center'}}>`;
@@ -102,7 +108,10 @@ components.forEach(component => {
   /* Props */
   content += `## API\n`;
   _.sortBy(component.props, p => p.name)?.forEach(prop => {
-    content += `### ${prop.name}\n`;
+    content += `### ${prop.name} \n`;
+    if (prop.note) {
+      content +=  `#### ${prop.note} \n`;
+    }
     content += `${prop.description}  \n`;
     // content += `<span style={{color: 'grey'}}>${_.escape(prop.type)}</span>\n\n`;
     content += `\`${prop.type} \` \n\n`;

src/components/card/card.api.json

@@ -26,8 +26,8 @@
       "description": "Whether the card should have shadow or not",
       "default": "true"
     },
-    {"name": "elevation", "type": "number", "description": "Elevation value (Android only)"},
-    {"name": "enableBlur", "type": "boolean", "description": "Enable blur effect (iOS only)"},
+    {"name": "elevation", "type": "number", "description": "Elevation value", "note": "Android only"},
+    {"name": "enableBlur", "type": "boolean", "description": "Enable blur effect", "note": "iOS only"},
     {
       "name": "blurOptions",
       "type": "object",

src/components/floatingButton/floatingButton.api.json

@@ -23,7 +23,7 @@
       "name": "testID",
       "type": "string",
       "description": "The test id for e2e tests",
-      "note": "<TestID> - the floatingButton container\n<TestID>.button - the floatingButton main button\n<TestID>.secondaryButton - the floatingButton secondaryButton"
+      "note": "Use `testID.button` for the main button or `testID.secondaryButton` for the secondary"
     }
   ],
   "snippet": [

src/components/modal/api/modal.api.json

@@ -10,7 +10,8 @@
     {
       "name": "enableModalBlur",
       "type": "boolean",
-      "description": "Blurs the modal background when transparent (iOS only)"
+      "description": "Blurs the modal background when transparent",
+      "note": "iOS only"
     },
     {
       "name": "blurView",
@@ -32,7 +33,8 @@
     {
       "name": "useGestureHandlerRootView",
       "type": "boolean",
-      "description": "Should add a GestureHandlerRootView (Android only)"
+      "description": "Should add a GestureHandlerRootView",
+      "note": "Android only"
     }
   ],
   "snippet": [

src/components/picker/api/picker.api.json

@@ -32,7 +32,7 @@
       "default": "Picker.modes.FORM"
     },
     {"name": "selectionLimit", "type": "number", "description": "Limit the number of selected items"},
-    {"name": "enableModalBlur", "type": "boolean", "description": "Adds blur effect to picker modal (iOS only)"},
+    {"name": "enableModalBlur", "type": "boolean", "description": "Adds blur effect to picker modal", "note": "iOS only"},
     {
       "name": "renderPicker",
       "type": "(selectedItem, itemLabel) => void",

src/incubator/toast/toast.api.json

@@ -11,7 +11,7 @@
     {"name": "messageStyle", "type": "StyleProp<TextStyle>", "description": "Toast message style"},
     {"name": "centerMessage", "type": "boolean", "description": "Should message be centered in the toast"},
     {"name": "zIndex", "type": "number", "description": "Custom zIndex for toast"},
-    {"name": "elevation", "type": "number", "description": "Custom elevation (Android only)"},
+    {"name": "elevation", "type": "number", "description": "Custom elevation", "note": "Android only"},
     {
       "name": "action",
       "type": "ButtonProps",