feat: improve Explorer UI (#36)

* feat: improve Explorer UI:

- link hooks and styling libs shown in example badges
- improve layouts for responsiveness
- improve file organization

* fix: fix types issue

Author: colepeters

apps/sdk-explorer/src/App.tsx

@@ -5,13 +5,13 @@ import {type JSX} from 'react'
 import {BrowserRouter, Link, Route, Routes} from 'react-router'
 import {createGlobalStyle} from 'styled-components'
 
-import DocumentSearch from './document-collections/DocumentSearch/DocumentSearch'
-import DocumentTable from './document-collections/DocumentTable/DocumentTable'
-import PreviewGrid from './document-collections/PreviewGrid/PreviewGrid'
-import PreviewList from './document-collections/PreviewList/PreviewList'
-import MoviesByActor from './groq/MoviesByActor/MoviesByActor'
+import ScrollOnPathChange from './components/ScollOnPathChange'
+import DocumentSearch from './examples/document-collections/DocumentSearch/DocumentSearch'
+import DocumentTable from './examples/document-collections/DocumentTable/DocumentTable'
+import PreviewGrid from './examples/document-collections/PreviewGrid/PreviewGrid'
+import PreviewList from './examples/document-collections/PreviewList/PreviewList'
+import MoviesByActor from './examples/groq/MoviesByActor/MoviesByActor'
 import Home from './Home'
-import ScrollOnPathChange from './ScollOnPathChange'
 
 const Body = createGlobalStyle`
   body {

apps/sdk-explorer/src/ExampleAttributes.tsx

@@ -1,7 +1,8 @@
 import {Box, Heading, Stack, Text} from '@sanity/ui'
 import {type JSX} from 'react'
 
-import ExampleCard from './ExampleCard'
+import ExampleCard from './components/ExampleCard'
+import {documents, paginatedDocuments, projection, query} from './components/Hooks'
 import DocumentTableImage from './images/DocumentTable.svg'
 import DocumentSearchImage from './images/DoumentSearch.svg'
 import MoviesByActorImage from './images/MoviesByActor.svg'
@@ -15,7 +16,7 @@ export default function Home(): JSX.Element {
         <Heading
           as="h1"
           style={{
-            fontSize: '4rem',
+            fontSize: '3.5rem',
             fontWeight: 400,
             letterSpacing: '-0.025em',
           }}
@@ -47,31 +48,31 @@ export default function Home(): JSX.Element {
               to="/document-collections/document-search"
               title="Document search"
               description="An interface for generating dynamic document searches"
-              hooks={['useDocuments', 'useProjection']}
+              hooks={[documents, projection]}
               styling="Sanity UI"
               img={DocumentSearchImage}
             />
             <ExampleCard
               to="/document-collections/document-table"
               title="Document table"
               description="A tabular rendering of documents and their content"
-              hooks={['usePaginatedDocuments', 'useProjection']}
+              hooks={[paginatedDocuments, projection]}
               styling="Tailwind"
               img={DocumentTableImage}
             />
             <ExampleCard
               to="/document-collections/preview-grid"
               title="Preview grid"
               description="A grid of document previews"
-              hooks={['useDocuments', 'useProjection']}
+              hooks={[documents, projection]}
               styling="Tailwind"
               img={PreviewGridImage}
             />
             <ExampleCard
               to="/document-collections/preview-list"
               title="Preview list"
               description="A list of document previews"
-              hooks={['useDocuments', 'useProjection']}
+              hooks={[documents, projection]}
               styling="Sanity UI"
               img={PreviewListImage}
             />
@@ -90,7 +91,7 @@ export default function Home(): JSX.Element {
               to="/groq/movies-by-actor"
               title="Movies by actor"
               description="Use multiple useQuery hooks to fetch and filter data"
-              hooks={['useQuery']}
+              hooks={[query]}
               styling="Sanity UI"
               img={MoviesByActorImage}
             />

apps/sdk-explorer/src/ExampleCard.tsx

@@ -0,0 +1,48 @@
+import {LaunchIcon} from '@sanity/icons'
+import {Badge, Box, Inline, Label, Stack} from '@sanity/ui'
+import {type JSX} from 'react'
+
+import Hooks, {type HookReference} from './Hooks'
+
+const labelInset = '14ch'
+
+export interface ExampleAttributeProps {
+  hooks: HookReference[]
+  styling: 'Sanity UI' | 'Tailwind'
+}
+
+const stylingLinks = {
+  'Sanity UI': 'https://sanity.io/ui',
+  'Tailwind': 'https://tailwindcss.com',
+}
+
+/**
+ * Lists the hooks and styling choices for a given example
+ */
+export default function ExampleAttributes({hooks, styling}: ExampleAttributeProps): JSX.Element {
+  return (
+    <Stack space={3}>
+      <Inline space={3}>
+        <Label size={1} style={{width: labelInset}}>
+          Hooks:
+        </Label>
+        <Hooks hooks={hooks} />
+      </Inline>
+      <Inline space={3}>
+        <Label size={1} style={{width: labelInset}}>
+          Styled with:
+        </Label>
+        <Badge tone="primary">
+          <a href={stylingLinks[styling]} style={{display: 'inline-block'}}>
+            <Box padding={1}>
+              {styling}
+              <Box display="inline-block" paddingLeft={2} paddingRight={1}>
+                <LaunchIcon />
+              </Box>
+            </Box>
+          </a>
+        </Badge>
+      </Inline>
+    </Stack>
+  )
+}

apps/sdk-explorer/src/Home.tsx

@@ -0,0 +1,77 @@
+import {hues} from '@sanity/color'
+import {Box, Card, Stack, Text} from '@sanity/ui'
+import {type JSX} from 'react'
+import {Link} from 'react-router'
+import styled from 'styled-components'
+
+import ExampleAttributes, {type ExampleAttributeProps} from './ExampleAttributes'
+
+interface ExampleCardProps {
+  description: string
+  hooks: ExampleAttributeProps['hooks']
+  img: string
+  styling: ExampleAttributeProps['styling']
+  title: string
+  to: string
+}
+
+const StyledLink = styled(Link)`
+  &:after {
+    content: '';
+    position: absolute;
+    inset: 0;
+  }
+`
+
+const CardGrid = styled.div`
+  display: grid;
+  grid-auto-flow: row;
+  grid-template-columns: 1fr;
+  align-items: center;
+  gap: 1rem;
+
+  @media (width >= 600px) {
+    grid-template-columns: minmax(50px, 0.25fr) 1fr;
+  }
+`
+
+/**
+ * Shows a summary of an example on the Home page
+ */
+export default function ExampleCard({
+  title,
+  description,
+  hooks,
+  img,
+  styling,
+  to,
+}: ExampleCardProps): JSX.Element {
+  return (
+    <Card shadow={2} paddingX={3} paddingY={4} radius={3} style={{position: 'relative'}}>
+      <CardGrid>
+        <Box
+          display={['none', 'none', 'inline-block']}
+          style={{
+            backgroundImage: `url(${img})`,
+            backgroundSize: 'contain',
+            backgroundRepeat: 'no-repeat',
+            maskImage: 'linear-gradient(to bottom right, white, transparent)',
+            maskMode: 'alpha',
+            aspectRatio: 1,
+          }}
+        />
+        <Stack space={4}>
+          <StyledLink to={to} style={{textDecoration: 'none'}}>
+            <Text as="h3" size={3} weight="medium" style={{color: hues.blue['500'].hex}}>
+              {title}
+            </Text>
+          </StyledLink>
+          <Text size={1} muted>
+            {description}
+          </Text>
+          <ExampleAttributes hooks={hooks} styling={styling} />
+        </Stack>
+      </CardGrid>
+    </Card>
+  )
+}

apps/sdk-explorer/src/components/ExampleAttributes.tsx

@@ -1,15 +1,15 @@
 import {Box, Card, Heading, Stack, Text} from '@sanity/ui'
 import {type JSX} from 'react'
 
-import ExampleAttributes from './ExampleAttributes'
+import ExampleAttributes, {type ExampleAttributeProps} from './ExampleAttributes'
 import ViewCode from './ViewCode'
 
 interface ExampleLayoutProps {
   children: React.ReactNode
   title: string
   codeUrl: string
-  hooks: Array<string>
-  styling: string
+  hooks: ExampleAttributeProps['hooks']
+  styling: ExampleAttributeProps['styling']
   summary: string
 }
 

apps/sdk-explorer/src/components/ExampleCard.tsx

@@ -0,0 +1,52 @@
+import {Badge, Box, Inline} from '@sanity/ui'
+import {type JSX} from 'react'
+
+export interface HookReference {
+  name: 'useDocuments' | 'usePaginatedDocuments' | 'useProjection' | 'useQuery'
+  reference: `https://${string}`
+}
+
+// These consts can't begin with the word `use` or eslint yells at you for
+// passing around a 'hook' reference
+
+const documents: HookReference = {
+  name: 'useDocuments',
+  reference: 'https://sdk-docs.sanity.dev/functions/sdk-react.index.useDocuments.html',
+}
+
+const paginatedDocuments: HookReference = {
+  name: 'usePaginatedDocuments',
+  reference: 'https://sdk-docs.sanity.dev/functions/sdk-react.index.usePaginatedDocuments.html',
+}
+
+const projection: HookReference = {
+  name: 'useProjection',
+  reference: 'https://sdk-docs.sanity.dev/functions/sdk-react.index.useProjection.html',
+}
+
+const query: HookReference = {
+  name: 'useQuery',
+  reference: 'https://sdk-docs.sanity.dev/functions/sdk-react.index.useQuery.html',
+}
+
+export {documents, paginatedDocuments, projection, query}
+
+interface HooksProps {
+  hooks: HookReference[]
+}
+
+export default function Hooks({hooks}: HooksProps): JSX.Element {
+  return (
+    <Inline space={3}>
+      {hooks.map((hook) => (
+        <Badge key={hook.name} tone="primary">
+          <a href={hook.reference} style={{display: 'inline-block'}}>
+            <Box as="span" padding={1}>
+              {hook.name}
+            </Box>
+          </a>
+        </Badge>
+      ))}
+    </Inline>
+  )
+}