Merge pull request #2 from storyofams/feat/docs

Feat/docs

example/.env.example

@@ -1,2 +1,3 @@
 NEXT_PUBLIC_STORYBLOK_TOKEN=
+STORYBLOK_PREVIEW_TOKEN=
 PREVIEW_TOKEN=

example/src/graphql/queries/articleItem.graphql

@@ -6,6 +6,7 @@ query articleItem($slug: ID!) {
         filename
       }
       intro
+      _editable
     }
     uuid
   }

example/src/graphql/queries/galleryItem.graphql

@@ -4,6 +4,7 @@ query galleryItem($slug: ID!) {
       images {
         filename
       }
+      _editable
     }
     uuid
   }

example/src/graphql/sdk.ts

@@ -935,7 +935,7 @@ export type ArticleItemQuery = { __typename?: 'QueryType' } & {
         content?: Maybe<
           { __typename?: 'ArticleComponent' } & Pick<
             ArticleComponent,
-            'title' | 'intro'
+            'title' | 'intro' | '_editable'
           > & {
               teaser_image?: Maybe<
                 { __typename?: 'Asset' } & Pick<Asset, 'filename'>
@@ -989,11 +989,14 @@ export type GalleryItemQuery = { __typename?: 'QueryType' } & {
   GalleryItem?: Maybe<
     { __typename?: 'GalleryItem' } & Pick<GalleryItem, 'uuid'> & {
         content?: Maybe<
-          { __typename?: 'GalleryComponent' } & {
-            images?: Maybe<
-              Array<Maybe<{ __typename?: 'Asset' } & Pick<Asset, 'filename'>>>
-            >;
-          }
+          { __typename?: 'GalleryComponent' } & Pick<
+            GalleryComponent,
+            '_editable'
+          > & {
+              images?: Maybe<
+                Array<Maybe<{ __typename?: 'Asset' } & Pick<Asset, 'filename'>>>
+              >;
+            }
         >;
       }
   >;
@@ -1008,6 +1011,7 @@ export const ArticleItemDocument = gql`
           filename
         }
         intro
+        _editable
       }
       uuid
     }
@@ -1040,6 +1044,7 @@ export const GalleryItemDocument = gql`
         images {
           filename
         }
+        _editable
       }
       uuid
     }

example/src/pages/article/[slug].tsx

@@ -15,8 +15,6 @@ import {
 type ArticleProps = WithStoryProps;
 
 const Article = ({ story }: ArticleProps) => {
-  // console.log(story);
-
   return (
     <Box
       sx={{

jest.config.js

@@ -20,4 +20,5 @@ module.exports = {
     '@testing-library/jest-dom/extend-expect',
     './jest.setup.js',
   ],
+  collectCoverageFrom: ['src/**/*.{ts,tsx}'],
 };

src/bridge/context.tsx

@@ -18,7 +18,7 @@ interface ContextProps {
 
 interface ProviderProps {
   children: ReactNode;
-  /*
+  /**
    * Relations that need to be resolved in preview mode, for example:
    * `['Post.author']`
    */

src/client/index.ts

@@ -3,8 +3,20 @@ import { GraphQLClient } from 'graphql-request';
 import type { GetStaticPropsResult, GetStaticPropsContext } from 'next';
 
 interface ClientOptions {
+  /**
+   * Custom fetch init parameters, `graphql-request` version.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch#parameters
+   */
   additionalOptions?: ConstructorParameters<typeof GraphQLClient>[1];
+  /** Storyblok API token (preview or publish) */
   token: string;
+  /**
+   * Which version of the story to load. Defaults to `'draft'` in development,
+   * and `'published'` in production.
+   *
+   * @default `process.env.NODE_ENV === 'development' ? 'draft' : 'published'`
+   */
   version?: 'draft' | 'published';
 }
 

src/image/Image.tsx

@@ -12,12 +12,19 @@ interface ImageProps
       HTMLImageElement
     >,
     GetImagePropsOptions {
-  /*
-    It's recommended to put lazy=false on images that are already in viewport
-    on load
-    @default true
-  */
+  /**
+   * It's recommended to put lazy=false on images that are already in viewport
+   * on load. If false, the image is loaded eagerly.
+   *
+   * @default true
+   */
   lazy?: boolean;
+  /**
+   * The media attribute specifies a media condition (similar to a media query)
+   * that the user agent will evaluate for each <source> element.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/picture#the_media_attribute
+   */
   media?: string;
 }
 

src/image/getImageProps.ts

@@ -1,7 +1,23 @@
 export interface GetImagePropsOptions {
-  fixed?: number[];
-  fluid?: number | number[];
-  /** @default true */
+  /**
+   * Optimize the image sizes for a fixed size. Use if you know the exact size
+   * the image will be.
+   * Format: `[width, height]`.
+   */
+  fixed?: [number, number];
+  /**
+   * Optimize the image sizes for a fluid size. Fluid is for images that stretch
+   * a container of variable size (different size based on screen size).
+   * Use if you don't know the exact size the image will be.
+   * Format: `width` or `[width, height]`.
+   */
+  fluid?: number | [number, number];
+  /**
+   * Apply the `smart` filter.
+   * @see https://www.storyblok.com/docs/image-service#facial-detection-and-smart-cropping
+   *
+   * @default true
+   */
   smart?: boolean;
 }
 

src/next/previewHandlers.ts

@@ -1,7 +1,13 @@
 import type { NextApiRequest, NextApiResponse } from 'next';
 
 interface NextPreviewHandlersProps {
+  /**
+   * A secret token (random string of characters) to activate preview mode.
+   */
   previewToken: string;
+  /**
+   * Storyblok API token with preview access (access to draft versions)
+   */
   storyblokToken: string;
 }
 

src/utils/getExcerpt.ts

@@ -1,6 +1,25 @@
 import { Richtext } from '../story';
 
-import { getPlainText } from './getPlainText';
+import { getPlainText, GetPlainTextOptions } from './getPlainText';
 
-export const getExcerpt = (richtext: Richtext, maxLength = 320) =>
-  getPlainText(richtext, { addNewlines: false, maxLength });
+interface GetExcerptOptions extends GetPlainTextOptions {
+  /**
+   * After how many characters the text should be cut off.
+   *
+   * @default 320
+   */
+  maxLength?: number;
+}
+
+export const getExcerpt = (
+  richtext: Richtext,
+  { maxLength, ...options }: GetExcerptOptions = { maxLength: 320 },
+) => {
+  const text = getPlainText(richtext, { addNewlines: false, ...options });
+
+  if (!text || !maxLength || text?.length < maxLength) {
+    return text;
+  }
+
+  return `${text?.substring(0, maxLength)}…`;
+};

src/utils/getPlainText.ts

@@ -41,19 +41,23 @@ const renderNodes = (nodes: any, addNewlines: boolean) =>
     .map((node) => renderNode(node, addNewlines))
     .filter((node) => node !== null)
     .join('')
-    // Remove multiple spaces with one
+    // Replace multiple spaces with one
     .replace(/[^\S\r\n]{2,}/g, ' ');
 
-interface GetExcerptOptions {
-  /* @default true */
+export interface GetPlainTextOptions {
+  /**
+   * Whether to add newlines (`\n\n`) after nodes and instead of hr's and
+   * br's.
+   *
+   * @default true
+   */
   addNewlines?: boolean;
-  maxLength?: number;
 }
 
 export const getPlainText = (
   richtext: Richtext,
-  { addNewlines, maxLength }: GetExcerptOptions = {},
-) => {
+  { addNewlines }: GetPlainTextOptions = {},
+): string => {
   if (!richtext?.content?.length) {
     return '';
   }
@@ -63,9 +67,5 @@ export const getPlainText = (
     addNewlines !== undefined ? addNewlines : true,
   );
 
-  if (!text || !maxLength || text?.length < maxLength) {
-    return text;
-  }
-
-  return `${text?.substring(0, maxLength)}…`;
+  return text;
 };

website/docs/api/Image.md

@@ -0,0 +1,86 @@
+---
+id: Image
+title: Image
+sidebar_label: Image
+hide_title: true
+---
+
+# `Image`
+
+A component that renders optimized and responsive images using Storyblok's image service. With support for lazy loading and LQIP (Low-Quality Image Placeholders).
+
+The component will automatically try to load a WebP version of the image if the browser supports it.
+
+Lazy loading uses the native browser implementation if available, otherwise an IntersectionObserver (polyfilled if needed) is used as fallback.
+
+The low-quality image placeholder is a small (max 32 pixels wide), blurred version of the image that is loaded as fast as possible and presented while the full image is loading. As soon as the full image loads, the placeholder is faded out.
+
+## Parameters
+
+`Image` accepts the normal HTML `img` attributes, but the `src` is expected to be a Storyblok asset URL.
+
+There are two important parameters that make sure the images are responsive: `fixed` and `fluid`. You should use one or the other.
+- `fixed`: use if you know the exact size the image will be.
+- `fluid`: is made for images that stretch a container of variable size (different size based on screen size). Use if you don't know the exact size the image will be.
+
+```ts no-transpile
+interface GetImagePropsOptions {
+  /**
+   * Optimize the image sizes for a fixed size. Use if you know the exact size
+   * the image will be.
+   * Format: `[width, height]`.
+   */
+  fixed?: [number, number];
+  /**
+   * Optimize the image sizes for a fluid size. Fluid is for images that stretch
+   * a container of variable size (different size based on screen size).
+   * Use if you don't know the exact size the image will be.
+   * Format: `width` or `[width, height]`.
+   */
+  fluid?: number | [number, number];
+  /**
+   * Apply the `smart` filter.
+   * @see https://www.storyblok.com/docs/image-service#facial-detection-and-smart-cropping
+   *
+   * @default true
+   */
+  smart?: boolean;
+}
+
+interface ImageProps
+  extends React.DetailedHTMLProps<
+      React.ImgHTMLAttributes<HTMLImageElement>,
+      HTMLImageElement
+    >,
+    GetImagePropsOptions {
+  /**
+   * It's recommended to put lazy=false on images that are already in viewport
+   * on load. If false, the image is loaded eagerly.
+   *
+   * @default true
+   */
+  lazy?: boolean;
+  /**
+   * The media attribute specifies a media condition (similar to a media query)
+   * that the user agent will evaluate for each <source> element.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/picture#the_media_attribute
+   */
+  media?: string;
+}
+
+const Image: (props: ImageProps) => JSX.Element
+```
+
+## Usage
+
+### Basic example
+
+```ts
+<Image
+  src={storyblok_image?.filename}
+  fluid={696}
+  alt={storyblok_image?.alt}
+  width="100%"
+/>
+```

website/docs/api/StoryProvider.md

@@ -0,0 +1,41 @@
+---
+id: StoryProvider
+title: StoryProvider
+sidebar_label: StoryProvider
+hide_title: true
+---
+
+# `StoryProvider`
+
+A global provider that provides the context to make `withStory` work, holding the current story. Also makes sure the Storyblok JS Bridge gets loaded when needed.
+
+## Parameters
+
+`StoryProvider` accepts the following properties:
+
+```ts no-transpile
+interface ProviderProps {
+  children: ReactNode;
+  /**
+   * Relations that need to be resolved in preview mode, for example:
+   * `['Post.author']`
+   */
+  resolveRelations?: string[];
+}
+
+const StoryProvider: (props: ProviderProps) => JSX.Element
+```
+
+## Usage
+
+### Basic example
+
+Wrap your entire app in the provider. For example in Next.js, in the render function of `_app`:
+
+```ts
+// Other providers
+<StoryProvider>
+  // The rest of your app
+  <Component {...pageProps} />
+</StoryProvider>
+```