From 5e9062562c4471114137ee0338de7513b1cc3d2e Mon Sep 17 00:00:00 2001
From: James O'Halloran <james.p.ohalloran@gmail.com>
Date: Mon, 24 Jul 2023 12:00:03 -0300
Subject: [PATCH] Product-tour-2.0 (#1624)

* Add to "advantages of tina"

* Update content for product tour

* split img view

* smoother img fade

* fix images on different levels

* Responsive Layout

* Placeholder stub image

* heading colors & spacing

* Fix broken css

* resolve routing conflict

* Fix scroll TOC callback

* React to window size

* fade out on exite

* Placeholder diagrams

* Updated images

* smoother transitions on fast scroll

* make focus more obvious

* new screenshots

* tweak content

* intro section

* tweak intro

* tweak title

* resposive imgs
---
 content/docs/index.md        |  27 ++--
 content/docs/product-tour.md | 104 ++++++++++----
 content/toc-doc.json         |   2 +-
 pages/docs/[...slug].tsx     |   5 +-
 pages/docs/product-tour.tsx  | 271 +++++++++++++++++++++++++++++++++++
 utils/toc_helpers.ts         |  58 ++++++--
 6 files changed, 417 insertions(+), 50 deletions(-)
 create mode 100644 pages/docs/product-tour.tsx

diff --git a/content/docs/index.md b/content/docs/index.md
index 25d609004..804bbb282 100644
--- a/content/docs/index.md
+++ b/content/docs/index.md
@@ -1,13 +1,13 @@
 ---
 title: Tina Docs
 id: introduction
-last_edited: '2021-07-27T15:51:56.737Z'
+last_edited: '2023-07-18T15:51:56.737Z'
 next: /docs/product-tour
 ---
 
 ## Introduction
 
-Tina is a Git-backed headless content management system that enables developers and content creators to collaborate seamlessly. With Tina, developers can create a custom visual editing experience that is perfectly tailored to their site.
+Tina is an open-source, Git-backed headless content management system (CMS) that empowers both developers and content creators to collaborate seamlessly on a single platform. Tina enables developers to craft a custom visual editing experience perfectly tailored to their website or application while supporting a broad range of content types such as Markdown, MDX, and JSON.
 
 <div style="position:relative;padding-top:56.25%;">
   <iframe width="560" frameborder="0" allowfullscreen
@@ -17,12 +17,23 @@ Tina is a Git-backed headless content management system that enables developers
 
 ## Advantages of Tina
 
-#### Backed by Git
+### Git-based content management
 
-- Both developers and editors collaborate on a single source of truth making site management harmonious.
-- Collaborate on content in real-time with live multi-user editing and change tracking.
+- Tina uses Git to provide a single source of truth for content and code, enhancing collaboration between developers and content editors.
+- Content changes are committed directly to your repository, ensuring version control and content history.
 
-#### Visual Editing
+### Real-time visual editing
 
-- Select and build using your predefined components. Edit text. Adjust the style. Empower editors to edit.
-- Get instant feedback with Tina’s intuitive sidebar editor. Allow your editors to preview their changes before publishing live to your site.
+- Create and edit content directly in the context of your website or application with Tina's real-time visual editor.
+- Customizable content blocks allow content editors to assemble pages and manage content intuitively, similar to using a site builder.
+- The changes made by the editors can be previewed in real-time before publishing, ensuring the quality of the content.
+
+### Control over content
+
+- Tina's open-source model gives you complete control and ownership over your content.
+- Tina's (optional) self-hosted backend gives you piece of mind from vendor lock-in.
+
+### Scalability
+
+- **Performance at Scale:** Tina is designed for large-scale projects. Whether your site has hundreds or tens of thousands of pages, Tina ensures optimal performance.
+- **Powerful Query Capabilities:** With Tina's unique data layer, your Markdown content becomes as flexible and queryable as if it were in a database.
diff --git a/content/docs/product-tour.md b/content/docs/product-tour.md
index d9f906c58..35251de4c 100644
--- a/content/docs/product-tour.md
+++ b/content/docs/product-tour.md
@@ -1,64 +1,106 @@
 ---
-title: Product Tour
+title: Introduction to TinaCMS
 id: /docs/product-tour/
 last_edited: '2022-01-17T15:51:56.737Z'
 next: '/docs/setup-overview'
 ---
 
-To understand the power of Tina, let us first break down Tina into its components.
+Here we give a quick **2 minute overview of TinaCMS**, and how it fits into your website.
 
-## Tina CLI
+> If you're instead just looking to quicky get started, jump to our [Getting Started Guide](/docs/setup-overview/).
 
-![TinaCMS CLI](https://res.cloudinary.com/forestry-demo/image/upload/v1642516210/img/create-tina-app.png 'Setup a project with TinaCMS CLI')
+## Introduction
 
-TinaCMS CLI is a quick and easy way to set up a project with Tina. The CLI can inject Tina into a pre-existing Next.js site, or create a Tina starter site (see our list of [starters](https://app.tina.io/quickstart)) with Tina pre-configured.
+TinaCMS is an open-source Content Management System (CMS) that seamlessly integrates with your Markdown workflow.
 
-A Tina-ified site includes:
+![](https://res.cloudinary.com/forestry-demo/image/upload/v1645712511/tina-io/docs/your-blocks.gif)
 
-- A Tina config file that be used to structure your content and configure Tina.
-- A local version of the Tina GraphQL API (see below!) used to fetch your content.
+### Your Website
 
-The Tina schema file is used to define the shape of your content. To learn more about content modelling within the Tina schema file, click [here](/docs/schema).
-For a list of CLI commands or to learn more about Tina’s CLI, click [here](/docs/cli-overview).
+- With TinaCMS, The developer hosts the site where they like, using whichever framework they choose.
 
-## Tina GraphQl API
+![](https://res.cloudinary.com/forestry-demo/image/upload/v1689874025/tina-io/docs/product-tour/headless_cms1.png)
 
-![Tina GraphQL API](https://res.cloudinary.com/deuzrsg3m/image/upload/v1651008834/carbon_csq54s.png "Fetch data using Tina's GraphQL API")
+### Headless CMS
 
-Tina’s GraphQL API provides a structured API that can be used to fetch your site’s content. This GraphQL API uses your local filesystem as a database. When you define your schema in the Tina schema file, the Tina GraphQL API will generate queries specific to your schema.
+- TinaCMS is "Headless", meaning it's decoupled from your website. TinaCMS provides a queryable content API that your website's code consumes.
 
-When running your site locally, Tina spins up a local GraphQL server at `http://localhost:3000` as well as an Altair client at `http://localhost:4001/altair/` . This allows developers to test out the API and its file fetching capabilities.
+![](https://res.cloudinary.com/forestry-demo/image/upload/v1689874025/tina-io/docs/product-tour/headless_cms2.png)
 
-> When running your site in production with Tina Cloud, instead of the local GraphQL server, your site will run using our hosted content API (more info below!).
+## The CMS Backend
 
-For more info on Tina’s GraphQL API or to understand content fetching, click [here](/docs/features/data-fetching).
+- The TinaCMS backend provides the API for querying your content, offering support for filtering, searching, and pagination.
 
-## Tina Editing UI
+![](https://res.cloudinary.com/forestry-demo/image/upload/v1689874024/tina-io/docs/product-tour/queryable_database.png)
 
-Tina's editing UI is compiled statically into the sites public directory. This allows Tina to be used in any site, regardless of the framework it is built with.
+### Git-backed Content
 
-When a Tina site is served, navigating to the `/admin` (or `/admin/index.html`) route takes you to the Tina editing UI. This UI is used to edit content and manage your site’s content.
+- All your content gets backed by git into JSON/Markdown/MDX files
 
-For more info on Tina’s editing UI, click [here](/docs/using-tina-editor).
+![](https://res.cloudinary.com/forestry-demo/image/upload/v1689874025/tina-io/docs/product-tour/git-backed.png)
 
-Tina has two editing modes. Basic editing, which allows an editor to edit in a "basic editor" and visual editing which can be used on any Reactive site (currently only support react).
+### Tina Cloud
 
-### Visual editing
+- Out of the box, we provide an easy-to-use hosted version of the backend, called Tina Cloud.
 
-![Real-time editing with TinaCMS and Tina Cloud](https://res.cloudinary.com/forestry-demo/image/upload/v1619023278/tina-cms-visual-editing.gif 'Real-time editing with TinaCMS and Tina Cloud')
+![](https://res.cloudinary.com/forestry-demo/image/upload/v1689874024/tina-io/docs/product-tour/tina-cloud.png)
 
-Tina’s sidebar editor allows users to make changes to text, styling or components. Tina’s sidebar editor is set up on the frontend of your site and can be customizable to suit the needs of your site.
+### Self-hosted Backend
 
-To learn more about visual editing and setting up the sidebar, click [here](/docs/tinacms-context).
+- For those preferring more control and customization, TinaCMS also allows you to host the backend entirely on your own stack.
 
-## Tina Cloud
+![](https://res.cloudinary.com/forestry-demo/image/upload/v1689874024/tina-io/docs/product-tour/self-host-backend.png)
 
-![Tina Cloud Dashboard](https://res.cloudinary.com/forestry-demo/image/upload/v1642524904/tina-dashboard.png 'Tina Cloud Dashboard')
+## The CMS Frontend
 
-Tina Cloud is our final piece to providing a full content management experience!
+- TinaCMS provides an intuitive CMS interface for your editors. For sites using React, TinaCMS supports "Visual Editing" to allow content editors to see real-time changes.
 
-When working with Tina in a local environment, **changes made through the Tina sidebar editor are saved locally to your content files** using the local GraphQL API. When editing with Tina Cloud, **edits are saved directly to GitHub** using our hosted content API. The Tina Cloud Dashboard enables you to connect Tina Cloud to your site’s GitHub repo.
+![](https://res.cloudinary.com/forestry-demo/image/upload/v1645712511/tina-io/docs/your-blocks.gif)
 
-Additionally, when a site is configured with Tina Cloud, the editing capability is set behind an authentication wall. This allows only authorized users to make changes to your site. The Tina Cloud Dashboard enables you to invite other users, thus granting them access to edit content on your site and permitting their changes to reflect directly in GitHub.
+### /admin route
 
-Currently Tina Cloud is free to sign up - check it out [here](https://app.tina.io/register)! Or to learn more about Tina Cloud, click [here](/docs/tina-cloud).
+- Users interact with the CMS by navigating to the `/admin` page on your site.
+
+![](https://res.cloudinary.com/forestry-demo/image/upload/v1689874024/tina-io/docs/product-tour/admin.png)
+
+### Saving
+
+- When users make a change in the CMS, a commit is made back to your Git repository.
+
+![](https://res.cloudinary.com/forestry-demo/image/upload/v1689874024/tina-io/docs/product-tour/git-save.png)
+
+## Integrating TinaCMS into a site
+
+TinaCMS can be setup on your site with `tinacms init`. This installs a few Tina packages, and add some boilerplate
+
+![](https://res.cloudinary.com/forestry-demo/image/upload/v1689819318/tina-io/docs/product-tour/cli-init.png)
+
+### Running TinaCMS Locally
+
+- You also have the flexibility to run TinaCMS locally, sourcing local files instead of interacting with the hosted API. This gives developers an ultra-fast feedback loop.
+
+![](https://res.cloudinary.com/forestry-demo/image/upload/v1689874024/tina-io/docs/product-tour/local-workflow.png)
+
+### Content Modelling
+
+- Content in TinaCMS is modelled using a `tina/config.ts` file in your project. Through this, you can define "collections" that model various content types on your site.
+
+![](https://res.cloudinary.com/forestry-demo/image/upload/v1690206543/tina-io/docs/product-tour/content-modelling.png)
+
+### Data-fetching
+
+- TinaCMS provides a GraphQL API, making data-fetching more efficient and powerful.
+
+![](https://res.cloudinary.com/forestry-demo/image/upload/v1690205968/tina-io/docs/product-tour/graphql-query_5.png)
+
+### Client
+
+- Moreover, we also generate a user-friendly client that simplifies the process of querying your content.
+
+![](https://res.cloudinary.com/forestry-demo/image/upload/v1690206445/tina-io/docs/product-tour/client.png)
+
+### Type-safety
+
+- TinaCMS emphasizes type safety, ensuring your content queries remain error-free and consistent, thus improving code reliability and maintainability.
+
+![](https://res.cloudinary.com/forestry-demo/image/upload/v1690206441/tina-io/docs/product-tour/client-typesafe.png)
diff --git a/content/toc-doc.json b/content/toc-doc.json
index 41f6917b4..9e0eacabe 100644
--- a/content/toc-doc.json
+++ b/content/toc-doc.json
@@ -9,7 +9,7 @@
       },
       {
         "slug": "/docs/product-tour/",
-        "title": "Product Tour"
+        "title": "Introduction To TinaCMS"
       },
       {
         "title": "Getting Started",
diff --git a/pages/docs/[...slug].tsx b/pages/docs/[...slug].tsx
index 3031f6709..0eb47c3d8 100644
--- a/pages/docs/[...slug].tsx
+++ b/pages/docs/[...slug].tsx
@@ -132,7 +132,10 @@ export const getStaticPaths: GetStaticPaths = async function () {
   return {
     fallback: false,
     paths: files
-      .filter((file) => !file.endsWith('index.md'))
+      .filter(
+        (file) =>
+          !file.endsWith('index.md') && !file.endsWith('product-tour.md')
+      )
       .map((file) => {
         const path = file.substring(contentDir.length, file.length - 3)
         return { params: { slug: path.split('/') } }
diff --git a/pages/docs/product-tour.tsx b/pages/docs/product-tour.tsx
new file mode 100644
index 000000000..dcbfb37ff
--- /dev/null
+++ b/pages/docs/product-tour.tsx
@@ -0,0 +1,271 @@
+import { getDocProps } from 'utils/docs/getDocProps'
+import { GetStaticProps } from 'next'
+import { useRouter } from 'next/router'
+import { useTocListener } from 'utils/toc_helpers'
+import React, { useCallback, useEffect, useMemo, useRef } from 'react'
+import * as ga from '../../utils/ga'
+import { NextSeo } from 'next-seo'
+import { openGraphImage } from 'utils/open-graph-image'
+import { DocsLayout, MarkdownContent } from 'components/layout'
+import {
+  DocGridContent,
+  DocGridHeader,
+  DocGridToc,
+  DocsGrid,
+  DocsPageTitle,
+} from './[...slug]'
+import { Breadcrumbs } from 'components/DocumentationNavigation/Breadcrumbs'
+import Toc from 'components/toc'
+import { DocsPagination, LastEdited } from 'components/ui'
+import styled from 'styled-components'
+
+export const getStaticProps: GetStaticProps = async function (props) {
+  return await getDocProps(props, 'product-tour')
+}
+
+export default function Page(props) {
+  const router = useRouter()
+
+  const data = props.file.data
+
+  const isCloudDocs = router.asPath.includes('tina-cloud')
+
+  const isBrowser = typeof window !== `undefined`
+
+  const frontmatter = data.frontmatter
+  const markdownBody = data.markdownBody
+  const excerpt = props.file.data.excerpt
+  const tocItems = props.tocItems
+
+  const { activeIds: _activeIds, contentRef } = useTocListener(data)
+  const activeIds = _activeIds.filter((id) => !!id)
+  const activeImg = useRef(null)
+  const transitionImg = useRef(null)
+
+  useEffect(() => {
+    let imgTransitionTimeout: NodeJS.Timeout
+    if (typeof window === 'undefined') return
+    if (!activeIds.length) {
+      return
+    }
+    const imageSrc = (
+      document.querySelector(
+        `h2#${activeIds[0]} ~ *:has(img) img, ` +
+          `h3#${activeIds[0]} ~ *:has(img) img, ` +
+          `h4#${activeIds[0]} ~ *:has(img) img`
+      ) as any
+    )?.src
+
+    // limit activeIds to 1
+    const deepestActiveIds = activeIds.slice(0, 1)
+    document.querySelectorAll('.focused').forEach((el) => {
+      if (deepestActiveIds.indexOf(el.id) === -1) {
+        el.classList.remove('focused')
+      }
+    })
+
+    deepestActiveIds.forEach((id) => {
+      const el = document.querySelector(`#${id}`)
+      if (el) {
+        el.classList.add('focused')
+      }
+    })
+
+    if (activeImg.current.src === imageSrc) return
+
+    if (!activeImg.current.src) {
+      activeImg.current.src = imageSrc
+    } else {
+      transitionImg.current.src = imageSrc
+      transitionImg.current.style.opacity = '1'
+      activeImg.current.style.opacity = '0'
+
+      imgTransitionTimeout = setTimeout(function () {
+        activeImg.current.src = imageSrc
+        transitionImg.current.style.opacity = '0'
+        activeImg.current.style.opacity = '1'
+      }, 350)
+    }
+
+    return () => {
+      if (imgTransitionTimeout) {
+        activeImg.current.src = imageSrc
+        transitionImg.current.style.opacity = '0'
+        activeImg.current.style.opacity = '1'
+
+        clearTimeout(imgTransitionTimeout)
+      }
+    }
+  }, [activeIds, transitionImg, activeImg])
+
+  React.useEffect(() => {
+    const handleRouteChange = (url) => {
+      ga.pageview(url)
+    }
+    //When the component is mounted, subscribe to router changes
+    //and log those page views
+    router.events.on('routeChangeComplete', handleRouteChange)
+
+    // If the component is unmounted, unsubscribe
+    // from the event with the `off` method
+    return () => {
+      router.events.off('routeChangeComplete', handleRouteChange)
+    }
+  }, [router.events])
+  return (
+    <>
+      <NextSeo
+        title={frontmatter.title}
+        titleTemplate={'%s | TinaCMS Docs'}
+        description={excerpt}
+        openGraph={{
+          title: frontmatter.title,
+          description: excerpt,
+          images: [openGraphImage(frontmatter.title, '| TinaCMS Docs')],
+        }}
+      />
+      <DocsLayout navItems={props.docsNav}>
+        <DocContainer>
+          <DocGridHeader>
+            <Breadcrumbs navItems={props.docsNav} />
+            <DocsPageTitle>{frontmatter.title}</DocsPageTitle>
+          </DocGridHeader>
+          {/* <DocGridToc>
+            <Toc tocItems={tocItems} activeIds={activeIds} />
+          </DocGridToc> */}
+          <DocGridContent ref={contentRef}>
+            <hr />
+            <SplitContent>
+              <div id="main-content-container">
+                <MarkdownContent escapeHtml={false} content={markdownBody} />
+              </div>
+              <div id="sticky-img-container">
+                <div className="img-container">
+                  <img
+                    ref={activeImg}
+                    src="https://res.cloudinary.com/forestry-demo/image/upload/v1645712511/tina-io/docs/your-blocks.gif"
+                  />
+                  <img ref={transitionImg} />
+                </div>
+              </div>
+            </SplitContent>
+            <LastEdited date={frontmatter.last_edited} />
+            {(props.prevPage?.slug !== null ||
+              props.nextPage?.slug !== null) && (
+              <DocsPagination
+                prevPage={props.prevPage}
+                nextPage={props.nextPage}
+              />
+            )}
+          </DocGridContent>
+        </DocContainer>
+      </DocsLayout>
+    </>
+  )
+}
+
+export const DocContainer = styled.div`
+  display: block;
+  width: 100%;
+  position: relative;
+  padding: 1rem 2rem 3rem 2rem;
+  margin: 0 auto;
+`
+
+const MAX_SPLIT_IMG_WIDTH = 768
+const SplitContent = styled.div`
+  display: flex;
+  position: relative;
+
+  h3 {
+    font-size: 1.2rem;
+  }
+
+  > * {
+    flex: 1;
+    margin: 0 10px;
+    padding: 10px;
+    box-sizing: border-box;
+  }
+
+  @media (min-width: ${MAX_SPLIT_IMG_WIDTH + 1}px) {
+    #main-content-container > h3:not(:first-child),
+    #main-content-container > h2:not(:first-child) {
+      margin-top: 4.5rem !important;
+    }
+
+    ul {
+      list-style: none;
+    }
+
+    h2,
+    h3,
+    h4 {
+      color: var(--color-light-dark);
+
+      &:not(.focused) * {
+        color: var(--color-light-dark);
+      }
+
+      + p,
+      + ul {
+        padding-left: 1rem;
+        border-left: 4px solid var(--color-light-dark);
+
+        color: var(--color-light-dark);
+        * {
+          color: var(--color-light-dark);
+        }
+      }
+
+      &.focused {
+        color: var(--color-orange);
+
+        + p,
+        + ul {
+          border-left: 4px solid var(--color-orange);
+
+          color: var(--color-primary);
+          * {
+            color: var(--color-primary);
+          }
+        }
+      }
+    }
+  }
+
+  #main-content-container img {
+    display: none;
+  }
+
+  @media (max-width: ${MAX_SPLIT_IMG_WIDTH}px) {
+    #sticky-img-container {
+      display: none;
+    }
+
+    #main-content-container img {
+      display: initial;
+    }
+  }
+
+  #sticky-img-container {
+    position: sticky;
+    top: 10px;
+    width: 100%;
+    height: fit-content;
+
+    img {
+      max-width: 100%;
+      max-height: calc(100vh - 100px);
+      position: absolute;
+      left: 50%;
+      transform: translate(-50%, 0%);
+      top: 0;
+      transition: opacity 0.35s ease-in-out;
+    }
+  }
+
+  .img-container {
+    position: relative;
+  }
+`
diff --git a/utils/toc_helpers.ts b/utils/toc_helpers.ts
index 278e376ff..7088e21bc 100644
--- a/utils/toc_helpers.ts
+++ b/utils/toc_helpers.ts
@@ -14,7 +14,7 @@ function createHeadings(
     'h1, h2, h3, h4, h5, h6'
   )
 
-  htmlElements.forEach(function(heading: HTMLHeadingElement) {
+  htmlElements.forEach(function (heading: HTMLHeadingElement) {
     headings.push({
       id: heading.id,
       offset: heading.offsetTop,
@@ -36,7 +36,7 @@ export function createTocListener(
   const throttledScroll = () => {
     const scrollPos = window.scrollY
     const newActiveIds = []
-    const activeHeadingCandidates = headings.filter(heading => {
+    const activeHeadingCandidates = headings.filter((heading) => {
       return heading.offset - scrollPos < BASE_OFFSET
     })
 
@@ -51,7 +51,7 @@ export function createTocListener(
     if (activeHeading.level != 'H2') {
       const activeHeadingParentCandidates =
         activeHeadingCandidates.length > 0
-          ? activeHeadingCandidates.filter(heading => {
+          ? activeHeadingCandidates.filter((heading) => {
               return heading.level == 'H2'
             })
           : []
@@ -72,7 +72,7 @@ export function createTocListener(
 
   return function onScroll(): void {
     if (!tick) {
-      setTimeout(function() {
+      setTimeout(function () {
         throttledScroll()
         tick = false
       }, THROTTLE_INTERVAL)
@@ -81,20 +81,60 @@ export function createTocListener(
   }
 }
 
+function useHookWithRefCallback() {
+  const ref = React.useRef(null)
+  const setRef = React.useCallback((node) => {
+    if (ref.current) {
+      // Make sure to cleanup any events/references added to the last instance
+    }
+
+    if (node) {
+      // Check if a node is actually passed. Otherwise node would be null.
+      // You can now do what you need to, addEventListeners, measure, etc.
+    }
+
+    // Save a reference to the node
+    ref.current = node
+  }, [])
+
+  return [setRef, ref]
+}
+
+function useWindowSize() {
+  if (typeof window !== 'undefined') {
+    return { width: 1200, height: 800 }
+  }
+
+  const [windowSize, setWindowSize] = React.useState<{
+    width: number
+    height: number
+  }>()
+
+  React.useEffect(() => {
+    window.addEventListener('resize', () => {
+      setWindowSize({ width: window.innerWidth, height: window.innerHeight })
+    })
+  }, [])
+
+  return windowSize
+}
+
 export function useTocListener(data) {
   const [activeIds, setActiveIds] = React.useState([])
-  const contentRef = React.useRef<HTMLDivElement>(null)
+  const [setRef, ref] = useHookWithRefCallback()
+
+  const windowSize = useWindowSize()
 
   React.useEffect(() => {
-    if (typeof window === `undefined` || !contentRef.current) {
+    if (typeof window === `undefined` || !(ref as any).current) {
       return
     }
 
-    const activeTocListener = createTocListener(contentRef, setActiveIds)
+    const activeTocListener = createTocListener(ref as any, setActiveIds)
     window.addEventListener('scroll', activeTocListener)
 
     return () => window.removeEventListener('scroll', activeTocListener)
-  }, [contentRef, data])
+  }, [(ref as any).current, data, windowSize])
 
-  return { contentRef, activeIds }
+  return { contentRef: setRef, activeIds }
 }