Better error messages for useSteps and stepper components (#1240)

* feat: provide better error messages when useSteps or stepper components are used in the wrong context

* docs: describe proper useSteps usage in the docs as well

Author: fritz-c

.changeset/serious-seals-divide.md

@@ -0,0 +1,5 @@
+---
+'spectacle': minor
+---
+
+provide better error messages when useSteps or stepper components are used in the wrong context

docs/api-reference.md

@@ -90,7 +90,7 @@ These tags are for adding tables with content to your slides.
 
 ## useSteps
 
-The `useSteps` hook allows a component to participate in the _slide step sequence_ for a given Slide.
+The `useSteps` hook allows a component to participate in the _slide step sequence_ for a given Slide. It must be called inside a component that sits somewhere underneath a slide component, i.e., `<Slide><MyComponentThatUsesUseStepsInside /></Slide>`, so it can access the `SlideContext` managed by the Slide component.
 
 NOTE: the vast majority of use cases are covered by the `Stepper` and `Appear` components documented below- in fact, they are implemented via this hook. The only case in which you may need to use this hook explicitly is if you need more precise control over a component in your presentation.
 

packages/spectacle/src/components/appear.tsx

@@ -16,7 +16,15 @@ const SteppedComponent = (props: SteppedComponentProps): JSX.Element => {
     activeStyle = { opacity: '1' },
     inactiveStyle = { opacity: '0' }
   } = props;
-  const { immediate } = useContext(SlideContext);
+  const slideContext = useContext(SlideContext);
+  if (slideContext === null) {
+    throw new Error(
+      'This component must be used within a SlideContext.Provider. Did you' +
+        ' put an <Appear> or <Stepper> component outside of a <Slide>?'
+    );
+  }
+
+  const { immediate } = slideContext;
 
   const { isActive, step, placeholder } = useSteps(numSteps, {
     id,

packages/spectacle/src/hooks/use-steps.tsx

@@ -22,7 +22,15 @@ export function useSteps(
 ) {
   const [stepId] = useState(userProvidedId || ulid);
 
-  const { activeStepIndex, activationThresholds } = useContext(SlideContext);
+  const slideContext = useContext(SlideContext);
+  if (slideContext === null) {
+    throw new Error(
+      '`useSteps` must be called within a SlideContext.Provider. Did you' +
+        ' call `useSteps` in a component that was not placed inside a <Slide>?'
+    );
+  }
+
+  const { activeStepIndex, activationThresholds } = slideContext;
 
   let relStep: number;