Add SDK Explorer readme and code comments (#6)

* Add SDK Explorer readme and code comments

* Dupe readme text to SDK Explorer home page

Author: colepeters

sdk-explorer/README.md

@@ -1,50 +1,21 @@
-# React + TypeScript + Vite
+# SDK Explorer
 
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+The Sanity App SDK Explorer contains an assortment of example interfaces built with our React SDK’s hooks.
+The purpose of the Explorer is to demonstrate how these hooks can be used to build out interfaces powered
+by Sanity, with a variety of approaches to styling.
 
-Currently, two official plugins are available:
+Each example contains an interface rendered in the browser as well as a link to the example’s code on
+GitHub to demonstrate how the example is built. Example code is enriched with comments and may freely
+be used in your own applications.
 
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react/README.md) uses [Babel](https://babeljs.io/) for Fast Refresh
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+## Running the SDK Explorer
 
-## Expanding the ESLint configuration
+We'll have a deployed version of the SDK Explorer available soon.
 
-If you are developing a production application, we recommend updating the configuration to enable type aware lint rules:
+For now, you can run the SDK Explorer locally:
 
-- Configure the top-level `parserOptions` property like this:
-
-```js
-export default tseslint.config({
-  languageOptions: {
-    // other options...
-    parserOptions: {
-      project: ['./tsconfig.node.json', './tsconfig.app.json'],
-      tsconfigRootDir: import.meta.dirname,
-    },
-  },
-})
-```
-
-- Replace `tseslint.configs.recommended` to `tseslint.configs.recommendedTypeChecked` or `tseslint.configs.strictTypeChecked`
-- Optionally add `...tseslint.configs.stylisticTypeChecked`
-- Install [eslint-plugin-react](https://github.com/jsx-eslint/eslint-plugin-react) and update the config:
-
-```js
-// eslint.config.js
-import react from 'eslint-plugin-react'
-
-export default tseslint.config({
-  // Set the react version
-  settings: { react: { version: '18.3' } },
-  plugins: {
-    // Add the react plugin
-    react,
-  },
-  rules: {
-    // other rules...
-    // Enable its recommended rules
-    ...react.configs.recommended.rules,
-    ...react.configs['jsx-runtime'].rules,
-  },
-})
-```
+1. Clone the SDK Examples Git repo: `git clone [email protected]:sanity-io/sdk-examples.git`
+1. Switch to the SDK Explorer app: `cd ./sdk-examples/sdk-explorer`
+1. Install dependencies: `pnpm install`
+1. Run the application’s dev server: `pnpm dev`
+1. Open the URL displayed by the dev server (usually `localhost:5173`)

sdk-explorer/src/Home.tsx

@@ -15,11 +15,21 @@ export default function Home() {
         >
           SDK Explorer
         </Heading>
-        <Text size={3} muted>
-          The Sanity SDK Explorer contains an assortment of examples for each
-          component available in the SDK. This copywriting should be more
-          exciting!
-        </Text>
+        <Stack space={5}>
+          <Text size={3} muted>
+            The Sanity App SDK Explorer contains an assortment of example
+            interfaces built with our React SDK’s hooks. The purpose of the
+            Explorer is to demonstrate how these hooks can be used to build out
+            interfaces powered by Sanity, with a variety of approaches to
+            styling.
+          </Text>
+          <Text size={3} muted>
+            Each example contains an interface rendered in the browser as well
+            as a link to the example’s code on GitHub to demonstrate how the
+            example is built. Example code is enriched with comments and may
+            freely be used in your own applications.
+          </Text>
+        </Stack>
       </Stack>
 
       <Stack space={5} paddingY={4}>

sdk-explorer/src/document-collections/PreviewGrid/PreviewGrid.tsx

@@ -5,16 +5,24 @@ import { Suspense, useRef } from 'react'
 import ExampleLayout from '../../ExampleLayout'
 import './styles.css'
 
+// The DocumentPreview component uses the `usePreview` hook to render a document preview interface
 function DocumentPreview({ document }: { document: DocumentHandle }) {
+  // Generate a ref for the outer element
+  // This keeps the usePreview hook from resolving if the preview is not currently displayed in the viewport
   const ref = useRef(null)
+
+  // Get the preview's title, subtitle, and media fields,
+  // plus an `isPending` flag to indicate if preview value resolutions are pending
   const {
     results: { title, subtitle, media },
     isPending,
   } = usePreview({ document, ref })
 
   return (
     <button
+      // Assign the ref to the outer element
       ref={ref}
+      // When preview values are resolving, we’ll lower the opacity to indicate this state visually
       className={`group appearance-none text-start p-3 rounded-md border-1 border-gray-100 shadow-xl ${isPending ? 'opacity-50' : 'opacity-100'}`}
       onClick={() => alert(`Great pick! ${title} is an excellent book.`)}
     >
@@ -31,6 +39,8 @@ function DocumentPreview({ document }: { document: DocumentHandle }) {
 }
 
 function PreviewGrid() {
+  // Use the `useDocuments` hook to return an index of document handles for all of our 'book' type documents
+  // Sort the documents by the author's last name, then the release date
   const { results: books, isPending } = useDocuments({
     filter: '_type == "book"',
     sort: [

sdk-explorer/src/document-collections/PreviewList/PreviewList.tsx

@@ -14,18 +14,26 @@ function Loading() {
   )
 }
 
+// The DocumentPreview component uses the `usePreview` hook to render a document preview interface
 function DocumentPreview({ document }: { document: DocumentHandle }) {
+  // Generate a ref for the outer element
+  // This keeps the usePreview hook from resolving if the preview is not currently displayed in the viewport
   const ref = useRef(null)
+
+  // Get the preview's title, subtitle, and media fields,
+  // plus an `isPending` flag to indicate if preview value resolutions are pending
   const {
     results: { title, subtitle, media },
     isPending,
   } = usePreview({ document, ref })
 
   return (
     <Button
+      // Assign the ref to the outer element
       ref={ref}
       mode='bleed'
       onClick={() => alert(`Good choice! ${title} is an excellent book.`)}
+      // When preview values are resolving, we’ll lower the opacity to indicate this state visually
       style={{ opacity: isPending ? 0.5 : 1 }}
     >
       <Inline space={4}>
@@ -46,6 +54,8 @@ function DocumentPreview({ document }: { document: DocumentHandle }) {
 }
 
 function PreviewList() {
+  // Use the `useDocuments` hook to return an index of document handles for all of our 'book' type documents
+  // Sort the documents by the author's last name, then the release date
   const { results: books, isPending } = useDocuments({
     filter: '_type == "book"',
     sort: [

sdk-explorer/src/users/UserProfile/UserProfile.tsx

@@ -3,9 +3,14 @@ import { useAuthState, useCurrentUser } from '@sanity/sdk-react/hooks'
 import { Avatar, Card, Container, Flex, Grid, Stack, Text } from '@sanity/ui'
 
 export default function UserProfile() {
+  // Use the `useAuthState` hook to ensure there's currently a logged in user
   const { type } = useAuthState()
+
+  // Use the `useCurrentUser` hook to get the current user.
+  // The returned object contains fields like the user's name, profile image, email address, roles, and authentication provider
   const user = useCurrentUser()
 
+  // Render a user profile if the authentication state indicated a logged in user and a user object is available
   return type === AuthStateType.LOGGED_IN && user ? (
     <Container width={1}>
       <Card padding={4} margin={2} radius={3} shadow={3}>
@@ -36,6 +41,7 @@ export default function UserProfile() {
       </Card>
     </Container>
   ) : (
+    // Render a placeholder if there's no user currently logged in
     <Container padding={5}>
       <Text as='h2' size={4} align='center'>
         Nobody home! Try logging in?