Docs for methods and upgrade guide

docs/api.mdx → docs/api-v7.mdx

@@ -2,7 +2,7 @@
 sidebar_position: 3
 ---
 
-# API
+# API (v7 and Below)
 
 ## Carousel Props
 

docs/api/index.mdx

@@ -2,8 +2,6 @@
 sidebar_position: 3
 ---
 
-# API v8
+# API (v8+)
 
-## children
-
-## scrollDistance
+Nuka v8 and above are completely rewritten with new props and might not be completely backwards compatable with v7.

docs/api/methods.mdx

@@ -2,9 +2,33 @@
 sidebar_position: 2
 ---
 
+import { MethodsDemo } from '../../website/src/components/demos';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
 # Methods
 
-Nuka Carousel has a few exposed methods that allow the user to control certain parts of the carousel manually.
+Nuka Carousel has a few exposed methods that allow the user to control certain parts of the carousel manually. These methods are accessed via a ref attached to the carousel.
+
+```tsx title="MyComponent.tsx"
+import { useRef } from 'react';
+import Carousel, { SlideHandle } from 'nuka-carousel';
+
+const MyComponent = () => {
+  const ref = useRef<SlideHandle>(null);
+
+  return (
+    <div>
+      <Carousel ref={ref}>...</Carousel>
+
+      <button onClick={() => ref.current.goBack()}>Back</button>
+      <button onClick={() => ref.current.goForward()}>Forward</button>
+    </div>
+  );
+};
+```
+
+---
 
 ## Progression
 
@@ -20,4 +44,4 @@ Advances the carousel backward by the given `scrollDistance`.
 
 ### Usage/Examples
 
-Add examples here
+<MethodsDemo />

docs/v8-upgrade-guide.mdx

@@ -0,0 +1,101 @@
+---
+sidebar_position: 6
+---
+
+# v8 Upgrade Guide
+
+Nuka v8 and above are completely rewritten with new props and might not be completely backwards compatable with v7.
+
+---
+
+## New Props
+
+`scrollDistance`
+
+`showPageIndicators`
+
+`pageIndicatorProps`
+
+`wrapperClassName`
+
+Read more about how to use them in the API (v8+) pages.
+
+---
+
+## Removed Props
+
+`adaptiveHeight` - The carousel should adapt automatically to the height of the items in the carousel without the need of this prop.
+
+`adaptiveHeightAnimation` - The carousel should adapt automatically to the height of the items in the carousel without the need of this prop.
+
+`carouselId`
+
+`cellAlign` - this should just be controlled through passed CSS (prop `wrapperClassName`).
+
+`cellSpacing` - this should just be controlled through passed CSS.
+
+`defaultControlsConfig`
+
+`disableAnimation` - should just be controlled through passed CSS.
+
+`dragging` - this is always on, it defaults to the OS/browser settings.
+
+`dragThreshold` - this defaults to the OS/browser settings.
+
+`easing` - should just be controlled through passed CSS.
+
+`edgeEasing` - should just be controlled through passed CSS.
+
+`enableKeyboardControls` - this should be native without interference. If the content is focusable through normal tabbing, it will focus.
+
+`keyCodeConfig` - should be native.
+
+`landmark`
+
+`renderTop{direction}Controls` - build your own next/prev controls with the goBack() and goForward() exposed methods.
+
+`scrollMode` - always on `remainder` for now.
+
+`slideIndex`
+
+`slidesToScroll` - renamed to scrollDistance.
+
+`slidesToShow` - now based on media queries and how large the slides are.
+
+`speed` - should be native.
+
+`style` - pass styles through the wrapperClassName if needed.
+
+`swiping` - default to OS/browser settings.
+
+`tabbed` - should be native.
+
+`withoutControls` - controls are not rendered by default. Use methods to build your own next/prev triggers or style the page controls with `showPageIndicators` and `pageIndicatorProps`.
+
+`zoomScale` - should just be controlled through passed CSS.
+
+---
+
+## Props in consideration
+
+These v7 and below props are being worked on or are considered for v8.
+
+`afterSlide`
+
+`beforeSlide`
+
+`disableEdgeSwiping`
+
+`frameAriaLabel`
+
+`onDragStart`
+
+`onDrag`
+
+`onDragEnd`
+
+`onUserNavigation`
+
+`pauseOnHover`
+
+`wrapAround` - right now, you can wrap the the front but it won't infinitely scroll like in v7.

packages/nuka/src/Carousel/CarouselTests.stories.tsx

@@ -30,7 +30,7 @@ const StorybookComponent = (props: CarouselProps) => {
 };
 
 const meta: Meta<typeof Carousel> = {
-  title: 'components/TestRunners',
+  title: 'TestRunners',
   component: StorybookComponent,
   tags: ['autodocs'],
 };
@@ -103,7 +103,7 @@ export const Slide: Story = {
           canvas.getByTestId('overflow').offsetLeft
       );
     });
-    
+
     await userEvent.click(forwardButton);
 
     await waitFor(async () => {

website/src/components/demos.tsx

@@ -54,3 +54,23 @@ export const BasicDemo = ({
     </div>
   );
 };
+
+export const MethodsDemo = () => {
+  const ref = useRef<SlideHandle>(null);
+  return (
+    <div>
+      <Carousel autoplay={false} scrollDistance={'slide'} ref={ref}>
+        {generateCards()}
+      </Carousel>
+
+      <div>
+        <button onClick={() => ref.current && ref.current.goBack()}>
+          goBack()
+        </button>
+        <button onClick={() => ref.current && ref.current.goForward()}>
+          goForward()
+        </button>
+      </div>
+    </div>
+  );
+};